Python Documentation contents

What's New in Python

What's New In Python 3.12

Summary -- Release highlights

New Features

PEP 695: Type Parameter Syntax

PEP 701: Syntactic formalization of f-strings

PEP 684: A Per-Interpreter GIL

PEP 669: Low impact monitoring for CPython

PEP 688: Making the buffer protocol accessible in Python

PEP 709: Comprehension inlining

Improved Error Messages

New Features Related to Type Hints

PEP 692: Using TypedDict for more precise **kwargs typing

PEP 698: Override Decorator for Static Typing

Other Language Changes

New Modules

Improved Modules

array

asyncio

calendar

csv

dis

fractions

importlib.resources

inspect

itertools

math

os

os.path

pathlib

pdb

random

shutil

sqlite3

statistics

sys

tempfile

threading

tkinter

tokenize

types

typing

unicodedata

unittest

uuid

Optimizations

CPython bytecode changes

Demos and Tools

Deprecated

Pending Removal in Python 3.13

Pending Removal in Python 3.14

Pending Removal in Python 3.15

Pending Removal in Future Versions

Removed

asynchat and asyncore

configparser

distutils

ensurepip

enum

ftplib

gzip

hashlib

importlib

imp

io

locale

smtpd

sqlite3

ssl

unittest

webbrowser

xml.etree.ElementTree

zipimport

Others

Porting to Python 3.12

Changes in the Python API

Build Changes

C API Changes

New Features

Porting to Python 3.12

Deprecated

Pending Removal in Python 3.14

Pending Removal in Python 3.15

Pending Removal in Future Versions

Removed

Notable changes in 3.12.4

ipaddress

What's New In Python 3.11

概要 -- リリースハイライト

新しい機能

PEP 657: トレースバックのエラー位置の詳細化

PEP 654: 例外グループと except*

PEP 678: ノートによって例外を充実させる

Windows py.exe ランチャーの改善

型ヒントに関連する新しい機能

PEP 646: Variadic generics

PEP 655: Marking individual TypedDict items as required or not-required

PEP 673: Self 型

PEP 675: Arbitrary literal string type

PEP 681: Data class transforms

PEP 563 may not be the future

その他の言語変更

その他の CPython の実装の変更

新たなモジュール

改良されたモジュール

asyncio

contextlib

データクラス

datetime

enum

fcntl

fractions

functools

hashlib

IDLE と idelelib

inspect

locale

logging

math

operator

os

pathlib

re

shutil

socket

sqlite3

string

sys

sysconfig

tempfile

threading

time

tkinter

traceback

typing

unicodedata

unittest

venv

warnings

zipfile

最適化

Faster CPython

Faster Startup

Frozen imports / Static code objects

Faster Runtime

Cheaper, lazy Python frames

Inlined Python function calls

PEP 659: Specializing Adaptive Interpreter

Misc

FAQ

How should I write my code to utilize these speedups?

Will CPython 3.11 use more memory?

I don't see any speedups in my workload. Why?

Is there a JIT compiler?

About

CPython バイトコードの変更

New opcodes

Replaced opcodes

Changed/removed opcodes

非推奨

Language/Builtins

モジュール

Standard Library

Pending Removal in Python 3.12

削除

Porting to Python 3.11

Build Changes

C API の変更

新しい機能

Porting to Python 3.11

非推奨

Pending Removal in Python 3.12

削除

Python 3.11.4での重要な変更点

tarfile

Python 3.11.5での重要な変更点

OpenSSL

What's New In Python 3.10

概要 -- リリースハイライト

新しい機能

カッコ内のコンテキストマネージャー

エラーメッセージの改善

SyntaxErrors

IndentationErrors

AttributeErrors

NameErrors

PEP 626: Precise line numbers for debugging and other tools

PEP 634: 構造的パターンマッチ

Syntax and operations

Declarative approach

Simple pattern: match to a literal

Behavior without the wildcard

Patterns with a literal and variable

Patterns and classes

Patterns with positional parameters

Nested patterns

Complex patterns and the wildcard

Guard

Other Key Features

Optional EncodingWarning and encoding="locale" option

型ヒントに関連する新しい機能

PEP 604: New Type Union Operator

PEP 612: Parameter Specification Variables

PEP 613: TypeAlias

PEP 647: User-Defined Type Guards

その他の言語変更

新たなモジュール

改良されたモジュール

asyncio

argparse

array

asynchat, asyncore, smtpd

base64

bdb

bisect

codecs

collections.abc

contextlib

curses

データクラス

__slots__

Keyword-only fields

distutils

doctest

エンコーディング

enum

fileinput

faulthandler

gc

glob

hashlib

hmac

IDLE と idelelib

importlib.metadata

inspect

itertools

linecache

os

os.path

pathlib

プラットフォーム

pprint

py_compile

pyclbr

shelve

statistics

site

socket

ssl

sqlite3

sys

_thread

threading

traceback

types

typing

unittest

urllib.parse

xml

zipimport

最適化

非推奨

削除

Porting to Python 3.10

Changes in the Python syntax

Python API の変更

C API の変更

CPython バイトコードの変更

Build Changes

C API の変更

PEP 652: Maintaining the Stable ABI

新しい機能

Porting to Python 3.10

非推奨

削除

Notable security feature in 3.10.7

Notable security feature in 3.10.8

Notable changes in 3.10.12

tarfile

What's New In Python 3.9

概要 -- リリースハイライト

コード中の非推奨警告(DeprecationWarning)をチェックして下さい

新しい機能

辞書のマージと更新演算子

prefixとsuffixを削除する新しい文字列メソッド

標準コレクション型の型ヒントにおける総称型 (generics) の使用

新しいパーサー

その他の言語変更

新たなモジュール

zoneinfo

graphlib

改良されたモジュール

ast

asyncio

compileall

concurrent.futures

curses

datetime

distutils

fcntl

ftplib

gc

hashlib

http

IDLE と idelelib

imaplib

importlib

inspect

ipaddress

math

multiprocessing

nntplib

os

pathlib

pdb

poplib

pprint

pydoc

random

signal

smtplib

socket

time

sys

tracemalloc

typing

unicodedata

venv

xml

最適化

非推奨

削除

Python 3.9への移植

Python API の変更

C API の変更

CPython バイトコードの変更

Build Changes

C API の変更

新しい機能

Python 3.9への移植

削除

Python 3.9.1 での重要な変更点

typing

macOS 11.0 (Big Sur) と Appleシリコンの Mac のサポート

Python 3.9.2 での重要な変更点

collections.abc

urllib.parse

Python 3.9.3 での重要な変更点

Python 3.9.5での重要な変更点

urllib.parse

Notable security feature in 3.9.14

Notable changes in 3.9.17

tarfile

What's New In Python 3.8

概要 -- リリースハイライト

新しい機能

代入式

位置専用引数

コンパイル済みのバイトコードファイルのキャッシュを併存させるファイルシステム

デバッグビルドとリリースビルドのABI 共通化

f-string での = を用いたオブジェクトの表現

PEP 578: Pythonランタイムの監査フック

PEP 587: Python 初期化設定

PEP 590: Vectorcall: a fast calling protocol for CPython

Pickle プロトコルバージョン 5 による帯域外データバッファ

その他の言語変更

新たなモジュール

改良されたモジュール

ast

asyncio

builtins

collections

cProfile

csv

curses

ctypes

datetime

functools

gc

gettext

gzip

IDLE と idelelib

inspect

io

itertools

json.tool

logging

math

mmap

multiprocessing

os

os.path

pathlib

pickle

plistlib

pprint

py_compile

shlex

shutil

socket

ssl

statistics

sys

tarfile

threading

tokenize

tkinter

time

typing

unicodedata

unittest

venv

weakref

xml

xmlrpc

最適化

ビルドならびに C API の変更

非推奨

API と機能の削除

Python 3.8 への移植

Python の挙動の変更

Python API の変更

C API の変更

CPython バイトコードの変更

Demos and Tools

Python3.8.1 での重要な変更点

Python3.8.2 での重要な変更点

Notable changes in Python 3.8.3

Python3.8.8 での重要な変更点

Notable changes in Python 3.8.9

Notable changes in Python 3.8.10

macOS 11.0 (Big Sur) と Appleシリコンの Mac のサポート

Notable changes in Python 3.8.10

urllib.parse

Notable changes in Python 3.8.12

Python API の変更

Notable security feature in 3.8.14

Notable changes in 3.8.17

tarfile

What's New In Python 3.7

概要 -- リリースハイライト

新しい機能

PEP 563: アノテーションの遅延評価

PEP 538: レガシーな C ロケールの抑圧

PEP 540: 強制 UTF-8 実行モード

PEP 553: 組み込みの breakpoint()

PEP 539: スレッドローカルストレージのための新しい C API

PEP 562: モジュール属性へのアクセスのカスタマイズ

PEP 564: ナノ秒単位の分解能を持つ新しい時間関数

PEP 565: Show DeprecationWarning in __main__

PEP 560: typing モジュールとジェネリック型に対する言語コアによるサポート

PEP 552: Hash-based .pyc Files

PEP 545: Python Documentation Translations

Python Development Mode (-X dev)

その他の言語変更

新たなモジュール

contextvars

データクラス

importlib.resources

改良されたモジュール

argparse

asyncio

binascii

calendar

collections

compileall

concurrent.futures

contextlib

cProfile

crypt

datetime

dbm

decimal

dis

distutils

enum

functools

gc

hmac

http.client

http.server

idlelib と IDLE

importlib

io

ipaddress

itertools

locale

logging

math

mimetypes

msilib

multiprocessing

os

pathlib

pdb

py_compile

pydoc

queue

re

signal

socket

socketserver

sqlite3

ssl

string

subprocess

sys

time

tkinter

tracemalloc

types

unicodedata

unittest

unittest.mock

urllib.parse

uu

uuid

warnings

xml

xml.etree

xmlrpc.server

zipapp

zipfile

C API の変更

Build Changes

最適化

その他の CPython の実装の変更

非推奨の Python の挙動

非推奨の Python モジュール、関数、メソッド

aifc

asyncio

collections

dbm

enum

gettext

importlib

locale

macpath

threading

socket

ssl

sunau

sys

wave

C API の非推奨の関数ならびに型

サポート対象プラットフォームからの除外

API と機能の削除

Module Removals

Windows-only Changes

Python 3.7 への移植

Python の挙動の変更

Python API の変更

C API の変更

CPython バイトコードの変更

Windows-only Changes

その他の CPython の実装の変更

Python 3.7.1 での重要な変更点

Python 3.7.2 での重要な変更点

Python 3.7.6 での重要な変更点

Python 3.7.10 での重要な変更点

Notable changes in Python 3.7.11

Notable security feature in 3.7.14

What's New In Python 3.6

概要 -- リリースハイライト

新しい機能

PEP 498: フォーマット済み文字列リテラル

PEP 526: 変数アノテーションの文法

PEP 515: 数値リテラル内のアンダースコア

PEP 525: 非同期ジェネレータ

PEP 530: 非同期内包表記

PEP 487: Simpler customization of class creation

PEP 487: 記述子プロトコルの改善

PEP 519: ファイルシステムパスプロトコルの追加

PEP 495: 地域時間の曖昧さ回避

PEP 529: Windows ファイルシステムのエンコーディングを UTF-8 に変更

PEP 528: Windows コンソールのエンコーディングを UTF-8 に変更

PEP 520: クラス属性の定義の順番を保持

PEP 468: キーワード引数の順番の保持

新たな dict 実装

PEP 523: CPython にフレーム評価 API を追加

PYTHONMALLOC 環境変数

DTrace and SystemTap probing support

その他の言語変更

新たなモジュール

secrets

改良されたモジュール

array

ast

asyncio

binascii

cmath

collections

concurrent.futures

contextlib

datetime

decimal

distutils

email

エンコーディング

enum

faulthandler

fileinput

hashlib

http.client

idlelib と IDLE

importlib

inspect

json

logging

math

multiprocessing

os

pathlib

pdb

pickle

pickletools

pydoc

random

re

readline

rlcompleter

shlex

site

sqlite3

socket

socketserver

ssl

statistics

struct

subprocess

sys

telnetlib

time

timeit

tkinter

traceback

tracemalloc

typing

unicodedata

unittest.mock

urllib.request

urllib.robotparser

venv

warnings

winreg

winsound

xmlrpc.client

zipfile

zlib

最適化

ビルドならびに C API の変更

その他の改善

非推奨

新たなキーワード

非推奨の Python 挙動

非推奨の Python モジュール、関数、メソッド

asynchat

asyncore

dbm

distutils

grp

importlib

os

re

ssl

tkinter

venv

xml

C API の非推奨の関数ならびに型

非推奨のビルドオプション

削除

API と機能の削除

Python 3.6 への移植

'python' コマンドの挙動の変更

Python API の変更

C API の変更

CPython バイトコードの変更

Notable changes in Python 3.6.2

New make regen-all build target

Removal of make touch build target

Notable changes in Python 3.6.4

Notable changes in Python 3.6.5

Notable changes in Python 3.6.7

Notable changes in Python 3.6.10

Notable changes in Python 3.6.13

Notable changes in Python 3.6.14

What's New In Python 3.5

概要 -- リリースハイライト

新しい機能

PEP 492 - コルーチン、 async と await 構文

PEP 465 - 行列の乗算専用の中置演算子

PEP 448 - 追加可能なアンパックへの一般化

PEP 461 - bytes および bytearray のパーセント書式化サポート

PEP 484 - 型ヒント

PEP 471 - os.scandir() 関数 -- より良く、速いディレクトリイテレータ

PEP 475: EINTR で失敗したシステムコールの再試行

PEP 479: ジェネレータ内の StopIteration の処理の変更

PEP 485: 近似的に等しいことを調べる関数

PEP 486: Python ランチャーが仮想環境を認識する

PEP 488: PYO ファイルの廃止

PEP 489: 拡張モジュールの多段階初期化

その他の言語変更

新たなモジュール

typing

zipapp

改良されたモジュール

argparse

asyncio

bz2

cgi

cmath

コード

collections

collections.abc

compileall

concurrent.futures

configparser

contextlib

csv

curses

dbm

difflib

distutils

doctest

email

enum

faulthandler

functools

glob

gzip

heapq

http

http.client

idlelib と IDLE

imaplib

imghdr

importlib

inspect

io

ipaddress

json

linecache

locale

logging

lzma

math

multiprocessing

operator

os

pathlib

pickle

poplib

re

readline

selectors

shutil

signal

smtpd

smtplib

sndhdr

socket

ssl

メモリ BIO サポート

Application-Layer Protocol Negotiation Support

その他の変更

sqlite3

subprocess

sys

sysconfig

tarfile

threading

time

timeit

tkinter

traceback

types

unicodedata

unittest

unittest.mock

urllib

wsgiref

xmlrpc

xml.sax

zipfile

その他のモジュールレベルの変更

最適化

ビルドならびに C API の変更

非推奨

新たなキーワード

非推奨の Python の挙動

サポートされないオペレーティングシステム

非推奨の Python モジュール、関数、メソッド

削除

API と機能の削除

Python 3.5 への移植

Python の挙動の変更

Python API の変更

C API の変更

Notable changes in Python 3.5.4

New make regen-all build target

Removal of make touch build target

What's New In Python 3.4

概要 -- リリースハイライト

新しい機能

PEP 453: Python インストール時の PIP の明示的なブートストラッピング

デフォルトでの pip のブートストラッピング

ドキュメントの変更

PEP 446: 新規作成されたファイル記述子は継承不可

Codec 処理の改良

PEP 451: インポートシステムのための ModuleSpec 型

その他の言語変更

新たなモジュール

asyncio

ensurepip

enum

pathlib

selectors

statistics

tracemalloc

改良されたモジュール

abc

aifc

argparse

audioop

base64

collections

colorsys

contextlib

dbm

dis

doctest

email

filecmp

functools

gc

glob

hashlib

hmac

html

http

idlelib と IDLE

importlib

inspect

ipaddress

logging

marshal

mmap

multiprocessing

operator

os

pdb

pickle

plistlib

poplib

pprint

pty

pydoc

re

resource

select

shelve

shutil

smtpd

smtplib

socket

sqlite3

ssl

stat

struct

subprocess

sunau

sys

tarfile

textwrap

threading

traceback

types

urllib

unittest

venv

wave

weakref

xml.etree

zipfile

CPython の実装の変更

PEP 445: CPython のメモリアロケータのカスタマイズ

PEP 442: オブジェクトの安全なファイナライゼーション

PEP 456: 安全で取り換え可能なハッシュアルゴリズム

PEP 436: Argument Clinic

その他のビルド並びに C API の変更

その他の改善

大幅な最適化

非推奨

Python API の非推奨項目

非推奨の機能

削除

サポートされなくなったオペレーティングシステム

API と機能の削除

コードの整理

Python 3.4 への移植

'python' コマンドの挙動の変更

Python API の変更

C API の変更

3.4.3 の変更

PEP 476: stdlib http クライアントが証明書の検証を行うのをデフォルトで有効化

What's New In Python 3.3

概要 -- リリースハイライト

PEP 405: 仮想環境

PEP 420: 暗黙的な名前空間パッケージ

PEP 3118: 新たなメモリビューの実装とバッファプロトコルのドキュメント

フィーチャー

API の変更

PEP 393: 文字列の柔軟な表現

機能性

性能およびリソース使用量

PEP 397: Windows の Python ランチャ

PEP 3151: OS および IO 例外階層の手直し

PEP 380: サブジェネレータへの委譲構文

PEP 409: 例外コンテキストの抑制

PEP 414: 明示的なユニコードリテラル

PEP 3155: クラスと関数の正規名

PEP 412: キー共有辞書

PEP 362: 関数シグニチャオブジェクト

PEP 421: sys.implementation の追加

SimpleNamespace

インポート実装としての importlib の使用

新たな API

目に見える変化

その他の言語変更

細粒度のインポートロック

組み込みの関数と型

新たなモジュール

faulthandler

ipaddress

lzma

改良されたモジュール

abc

array

base64

binascii

bz2

codecs

collections

contextlib

crypt

curses

datetime

decimal

フィーチャー

API の変更

email

ポリシーフレームワーク

新規ヘッダ API を伴った暫定ポリシー

その他のAPIの変更

ftplib

functools

gc

hmac

http

html

imaplib

inspect

io

itertools

logging

math

mmap

multiprocessing

nntplib

os

pdb

pickle

pydoc

re

sched

select

shlex

shutil

signal

smtpd

smtplib

socket

socketserver

sqlite3

ssl

stat

struct

subprocess

sys

tarfile

tempfile

textwrap

threading

time

types

unittest

urllib

webbrowser

xml.etree.ElementTree

zlib

最適化

ビルドならびに C API の変更

非推奨

サポートされないオペレーティングシステム

非推奨の Python モジュール、関数、メソッド

C API の非推奨の関数ならびに型

非推奨の機能

Python 3.3 への移植

Python コードの移植

C コードの移植

C 拡張のビルド

コマンドラインスイッチの変更

What's New In Python 3.2

PEP 384: 安定 ABI の定義

PEP 389: argparse コマンドライン解析モジュール

PEP 391: logging の辞書ベースの設定

PEP 3148: concurrent.futures モジュール

PEP 3147: PYC リポジトリーディレクトリ

PEP 3149: ABI バージョンでタグ付けされた .so ファイル

PEP 3333: Python Web Server Gateway Interface v1.0.1

その他の言語変更

新たなモジュール、改良されたモジュール、非推奨のモジュール

email

elementtree

functools

itertools

collections

threading

datetime と time

math

abc

io

reprlib

logging

csv

contextlib

decimal と fractions

ftp

popen

select

gzip と zipfile

tarfile

hashlib

ast

os

shutil

sqlite3

html

socket

ssl

nntp

certificates

imaplib

http.client

unittest

random

poplib

asyncore

tempfile

inspect

pydoc

dis

dbm

ctypes

site

sysconfig

pdb

configparser

urllib.parse

mailbox

turtledemo

マルチスレッディング

最適化

Unicode 文字列型

Codecs

ドキュメント

IDLE

コードリポジトリ

ビルドならびに C API の変更

Python 3.2 への移植

What's New In Python 3.1

PEP 372: 順序付き辞書

PEP 378: 1000区切りのための書式指定子

その他の言語変更

新たなモジュール、改良されたモジュール、非推奨のモジュール

最適化

IDLE

ビルドならびに C API の変更

Python 3.1 への移植

What's New In Python 3.0

よくある悩みの種

print関数

リストからビューおよびイテレータへ

順序比較

整数

Unicode 対 8 ビット、ではなく、テキスト対データに

構文の変更の概要

新たな構文

変更された構文

削除された操作

Python 2.6 で既にあった変更

ライブラリの変更

PEP 3101: 文字列整形の新たなアプローチ

例外に関する変更

その他の変更

演算子と特殊メソッド

組み込み

ビルドならびに C API の変更

性能

Python 3.0 への移植

What's New in Python 2.7

Python 2.x の今後

Deprecation Warnings の扱いの変更

Python 3.1 の機能

PEP 372: collections に順序付き辞書を追加

PEP 378: 1000区切りのための書式指定子

PEP 389: コマンドライン解析のための argparse モジュール

PEP 391: logging の辞書ベースの設定

PEP 3106: 辞書 View

PEP 3137: memoryview オブジェクト

その他の言語変更

インタプリタの変更

最適化

新しいモジュールと改良されたモジュール

新しいモジュール: importlib

新しいモジュール: sysconfig

ttk: Tk のテーマ付きウィジェット

更新されたモジュール: unittest

更新されたモジュール: ElementTree 1.3

ビルドならびに C API の変更

カプセル

ポート特有の変更: Windows

ポート特有の変更: Mac OS X

ポート特有の変更: FreeBSD

その他の変更と修正

Python 2.7 への移植

Python 2.7 メンテナンスリリースで追加された新機能

デバッグモード用の2つの新しい環境変数

PEP 434: IDLE 拡張についての全てのブランチにおける例外的な扱い

PEP 466: Python 2.7 のためのネットワークセキュリティ拡張

PEP 477: Python 2.7 への ensurepip (PEP 453) バックポート

デフォルトでの pip のブートストラッピング

ドキュメントの変更

PEP 476: stdlib http クライアントが証明書の検証を行うのをデフォルトで有効化

PEP 493: HTTPS verification migration tools for Python 2.7

New make regen-all build target

Removal of make touch build target

謝辞

What's New in Python 2.6

Python 3.0

開発プロセスに関する変更

新しい課題トラッカー: Roundup

新しいドキュメンテーションフォーマット: Sphinx を使っての reStructuredText

PEP 343: "with" ステートメント

コンテキストマネージャを書く

contextlib モジュール

PEP 366: メインモジュールからの明示的相対インポート

PEP 370: ユーザごとの site-packages ディレクトリ

PEP 371: multiprocessing パッケージ

PEP 3101: 進化版文字列フォーマッティング

PEP 3105: print を関数にする

PEP 3110: 例外処理の変更

PEP 3112: バイトリテラル

PEP 3116: 新しい I/O ライブラリ

PEP 3118: 改訂版バッファプロトコル

PEP 3119: 抽象基底クラス

PEP 3127: 整数リテラルのサポートと文法

PEP 3129: クラスデコレータ

PEP 3141: 数値の型階層

fractions モジュール

その他の言語変更

最適化

インタプリタの変更

新しいモジュールと改良されたモジュール

ast モジュール

future_builtins モジュール

json モジュール: JavaScript オブジェクト記法

plistlib モジュール: プロパティリストパーサ

ctypes の強化

SSL サポートの改善

非推奨と削除

ビルドならびに C API の変更

ポート特有の変更: Windows

ポート特有の変更: Mac OS X

ポート特有の変更: IRIX

Python 2.6 への移植

謝辞

What's New in Python 2.5

PEP 308: 条件式 (Conditional Expressions)

PEP 309: 関数の部分適用

PEP 314: Metadata for Python Software Packages v1.1

PEP 328: 絶対インポート、相対インポート

PEP 338 - モジュールをスクリプトとして実行する

PEP 341: try/except/finally の一体化

PEP 342: ジェネレータの新機能

PEP 343: "with" ステートメント

コンテキストマネージャを書く

contextlib モジュール

PEP 352: 例外の新スタイルクラス化

PEP 353: 添え字型に ssize_t を使う

PEP 357: '__index__' メソッド

その他の言語変更

対話的なインタプリタの変更

最適化

新たなモジュール、改良されたモジュール、削除されたモジュール

ctypes パッケージ

ElementTree パッケージ

hashlib パッケージ

sqlite3 パッケージ

wsgiref パッケージ

ビルドならびに C API の変更

ポート特有の変更

Python 2.5 への移植

謝辞

What's New in Python 2.4

PEP 218: ビルトインの集合オブジェクト

PEP 237: 長整数と整数を一体化していく

PEP 289: ジェネレータ式

PEP 292: より単純な文字列置換 (string substitution)

PEP 318: 関数とメソッドのためのデコレータ

PEP 322: 逆順のイテレーション

PEP 324: 新しい subprocess モジュール

PEP 327: Decimal データ型

なぜ Decimal が必要なのか?

Decimal 型

Context 型

PEP 328: マルチラインインポート

PEP 331: Locale に依存しない Float/String 変換

その他の言語変更

最適化

新たなモジュール、改良されたモジュール、非推奨のモジュール

cookielib

doctest

ビルドならびに C API の変更

ポート特有の変更

Python 2.4 への移植

謝辞

What's New in Python 2.3

PEP 218: 標準の集合データ型

PEP 255: 単純なジェネレータ

PEP 263: ソースコードのエンコーディング

PEP 273: Zip アーカイブからモジュールをインポートする

PEP 277: Windows NT での Unicode ファイル名サポート

PEP 278: Universal Newline サポート

PEP 279: enumerate()

PEP 282: ロギングパッケージ

PEP 285: Boolean 型

PEP 293: コーデックエラーを処理するコールバック

PEP 301: パッケージインデクスと、 Distutils のためのメタデータ

PEP 302: 新たなインポートフック

PEP 305: カンマ区切り形式ファイル

PEP 307: Pickle の機能拡張

拡張スライス

その他の言語変更

文字列に関する変更

最適化

新たなモジュール、改良されたモジュール、非推奨のモジュール

日付時刻型

optparse モジュール

Pymalloc: 特殊化されたオブジェクトアロケータ

ビルドならびに C API の変更

ポート特有の変更

その他の変更と修正

Python 2.3 への移植

謝辞

What's New in Python 2.2

はじめに

PEP 252 と PEP 253: 型とクラスについての変更

旧と新クラス

デスクリプタ

多重継承: ダイヤモンドルール

属性アクセス

関連リンク

PEP 234: イテレータ

PEP 255: 単純なジェネレータ

PEP 237: 長整数と整数を一体化していく

PEP 238: 除算演算子を変更していく

Unicode の変更

PEP 227: 入れ子状のスコープ

新しいモジュールと改良されたモジュール

インタプリタの変更と修正

その他の変更と修正

謝辞

What's New in Python 2.1

はじめに

PEP 227: 入れ子状のスコープ

PEP 236: __future__ 指示文

PEP 207: 拡張比較

PEP 230: 警告フレームワーク

PEP 229: 新しいビルドシステム

PEP 205: 弱参照

PEP 232: 関数の属性

PEP 235: 大文字小文字を区別しないプラットフォームでのモジュールの読み込み

PEP 217: 対話モード用 Display Hook

PEP 208: 新しい型強制モデル

PEP 241: Pythonソフトウェアパッケージのためのメタデータ

新しいモジュールと改良されたモジュール

その他の変更と修正

謝辞

What's New in Python 2.0

はじめに

Python 1.6 はいかがですか?

新しい開発プロセス

Unicode 文字列型

リストの内包表記

累算代入 (Augmented Assignment)

文字列メソッド

循環参照のガベージコレクション

その他の言語コアの変更

言語のマイナー変更

ビルトイン関数の変更

Python 2.0 への移植

拡張と埋め込みについての変更

Distutils: モジュールの簡単インストール

XML モジュール

SAX2 サポート

DOM サポート

PyXML との関係

更新されたモジュール

新しいモジュール

IDLE の改善

削除されたモジュール、非推奨となったモジュール

謝辞

変更履歴

Python next

Security

Core and Builtins

Library

Documentation

Windows

macOS

IDLE

C API

Python 3.12.3 final

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

IDLE

Tools/Demos

C API

Python 3.12.2 final

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

Tools/Demos

Python 3.12.1 final

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

C API

Python 3.12.0 final

Core and Builtins

Library

Documentation

Windows

macOS

Tools/Demos

Python 3.12.0 release candidate 3

Core and Builtins

Library

Documentation

Tests

Build

Python 3.12.0 release candidate 2

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

Tools/Demos

C API

Python 3.12.0 release candidate 1

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

Tools/Demos

C API

Python 3.12.0 beta 4

Security

Core and Builtins

Library

Documentation

Tests

Build

Tools/Demos

C API

Python 3.12.0 beta 3

Core and Builtins

Library

Tests

Windows

C API

Python 3.12.0 beta 2

Security

Core and Builtins

Library

Documentation

Build

Windows

macOS

IDLE

C API

Python 3.12.0 beta 1

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

Tools/Demos

C API

Python 3.12.0 alpha 7

Core and Builtins

Library

Documentation

Tests

Build

Windows

Tools/Demos

C API

Python 3.12.0 alpha 6

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

C API

Python 3.12.0 alpha 5

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

Python 3.12.0 alpha 4

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

Tools/Demos

C API

Python 3.12.0 alpha 3

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

Tools/Demos

C API

Python 3.12.0 alpha 2

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

C API

Python 3.12.0 alpha 1

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

Tools/Demos

C API

Python 3.11.0 beta 1

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

Tools/Demos

C API

Python 3.11.0 alpha 7

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

Tools/Demos

C API

Python 3.11.0 alpha 6

Core and Builtins

Library

Documentation

Tests

Build

Windows

IDLE

C API

Python 3.11.0 alpha 5

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

C API

Python 3.11.0 alpha 4

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

C API

Python 3.11.0 alpha 3

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

C API

Python 3.11.0 alpha 2

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

C API

Python 3.11.0 alpha 1

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

Tools/Demos

C API

Python 3.10.0 beta 1

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

C API

Python 3.10.0 alpha 7

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

IDLE

C API

Python 3.10.0 alpha 6

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

C API

Python 3.10.0 alpha 5

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

C API

Python 3.10.0 alpha 4

Core and Builtins

Library

Documentation

Tests

Build

macOS

Tools/Demos

C API

Python 3.10.0 alpha 3

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

Tools/Demos

C API

Python 3.10.0 alpha 2

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

C API

Python 3.10.0 alpha 1

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

C API

Python 3.9.0 beta 1

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

Tools/Demos

C API

Python 3.9.0 alpha 6

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

Tools/Demos

C API

Python 3.9.0 alpha 5

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

Tools/Demos

C API

Python 3.9.0 alpha 4

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

IDLE

C API

Python 3.9.0 alpha 3

Core and Builtins

Library

Documentation

Build

IDLE

C API

Python 3.9.0 alpha 2

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

C API

Python 3.9.0 alpha 1

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

Tools/Demos

C API

Python 3.8.0 beta 1

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

Tools/Demos

C API

Python 3.8.0 alpha 4

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

Tools/Demos

C API

Python 3.8.0 alpha 3

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

IDLE

Tools/Demos

C API

Python 3.8.0 alpha 2

Core and Builtins

Library

Documentation

Tests

Windows

IDLE

Python 3.8.0 alpha 1

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

Tools/Demos

C API

Python 3.7.0 final

Library

C API

Python 3.7.0 release candidate 1

Core and Builtins

Library

Documentation

Build

Windows

IDLE

Python 3.7.0 beta 5

Core and Builtins

Library

Documentation

Tests

Build

macOS

IDLE

Python 3.7.0 beta 4

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

Tools/Demos

Python 3.7.0 beta 3

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

Tools/Demos

C API

Python 3.7.0 beta 2

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

Tools/Demos

Python 3.7.0 beta 1

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

C API

Python 3.7.0 alpha 4

Core and Builtins

Library

Documentation

Tests

Windows

Tools/Demos

C API

Python 3.7.0 alpha 3

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

Tools/Demos

C API

Python 3.7.0 alpha 2

Core and Builtins

Library

Documentation

Build

IDLE

C API

Python 3.7.0 alpha 1

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

IDLE

Tools/Demos

C API

Python 3.6.6 final

Python 3.6.6 release candidate 1

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

Tools/Demos

C API

Python 3.6.5 final

Tests

Build

Python 3.6.5 release candidate 1

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

Tools/Demos

C API

Python 3.6.4 final

Python 3.6.4 release candidate 1

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

Tools/Demos

C API

Python 3.6.3 final

Library

Build

Python 3.6.3 release candidate 1

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

IDLE

Tools/Demos

Python 3.6.2 final

Python 3.6.2 release candidate 2

Security

Python 3.6.2 release candidate 1

Security

Core and Builtins

Library

IDLE

C API

Build

Documentation

Tools/Demos

Tests

Windows

Python 3.6.1 final

Core and Builtins

Build

Python 3.6.1 release candidate 1

Core and Builtins

Library

IDLE

Windows

C API

Documentation

Tests

Build

Python 3.6.0 final

Python 3.6.0 release candidate 2

Core and Builtins

Tools/Demos

Windows

Build

Python 3.6.0 release candidate 1

Core and Builtins

Library

C API

Documentation

Tools/Demos

Python 3.6.0 beta 4

Core and Builtins

Library

Documentation

Tests

Build

Python 3.6.0 beta 3

Core and Builtins

Library

Windows

Build

Tests

Python 3.6.0 beta 2

Core and Builtins

Library

Windows

C API

Build

Tests

Python 3.6.0 beta 1

Core and Builtins

Library

IDLE

C API

Tests

Build

Tools/Demos

Windows

Python 3.6.0 alpha 4

Core and Builtins

Library

IDLE

Tests

Windows

Build

Python 3.6.0 alpha 3

Security

Core and Builtins

Library

IDLE

C API

Build

Tools/Demos

Documentation

Tests

Python 3.6.0 alpha 2

Security

Core and Builtins

Library

IDLE

Documentation

Tests

Windows

Build

C API

Tools/Demos

Python 3.6.0 alpha 1

Security

Core and Builtins

Library

IDLE

Documentation

Tests

Build

Windows

Tools/Demos

C API

Python 3.5.5 final

Python 3.5.5 release candidate 1

Security

Core and Builtins

Library

Python 3.5.4 final

Library

Python 3.5.4 release candidate 1

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

C API

Python 3.5.3 final

Python 3.5.3 release candidate 1

Security

Core and Builtins

Library

IDLE

C API

Documentation

Tests

Tools/Demos

Windows

Build

Python 3.5.2 final

Core and Builtins

Tests

IDLE

Python 3.5.2 release candidate 1

Security

Core and Builtins

Library

IDLE

Documentation

Tests

Build

Windows

Tools/Demos

Python 3.5.1 final

Core and Builtins

Windows

Python 3.5.1 release candidate 1

Core and Builtins

Library

IDLE

Documentation

Tests

Build

Windows

Tools/Demos

Python 3.5.0 final

Build

Python 3.5.0 release candidate 4

Library

Build

Python 3.5.0 release candidate 3

Core and Builtins

Library

Python 3.5.0 release candidate 2

Core and Builtins

Library

Python 3.5.0 release candidate 1

Core and Builtins

Library

IDLE

Documentation

Tests

Python 3.5.0 beta 4

Core and Builtins

Library

Build

Python 3.5.0 beta 3

Core and Builtins

Library

Tests

Documentation

Build

Python 3.5.0 beta 2

Core and Builtins

Library

Python 3.5.0 beta 1

Core and Builtins

Library

IDLE

Tests

Documentation

Tools/Demos

Python 3.5.0 alpha 4

Core and Builtins

Library

Build

Tests

Tools/Demos

C API

Python 3.5.0 alpha 3

Core and Builtins

Library

Build

Tests

Tools/Demos

Python 3.5.0 alpha 2

Core and Builtins

Library

Build

C API

Windows

Python 3.5.0 alpha 1

Core and Builtins

Library

IDLE

Build

C API

Documentation

Tests

Tools/Demos

Windows

Python チュートリアル

1. やる気を高めよう

2. Python インタプリタを使う

2.1. インタプリタを起動する

2.1.1. 引数の受け渡し

2.1.2. 対話モード

2.2. インタプリタとその環境

2.2.1. ソースコードの文字コード

3. 形式ばらない Python の紹介

3.1. Python を電卓として使う

3.1.1. 数

3.1.2. テキスト

3.1.3. リスト型 (list)

3.2. プログラミングへの第一歩

4. その他の制御フローツール

4.1. if 文

4.2. for 文

4.3. range() 関数

4.4. break 文と continue 文とループの else 節

4.5. pass 文

4.6. match 文

4.7. 関数を定義する

4.8. 関数定義についてもう少し

4.8.1. デフォルトの引数値

4.8.2. キーワード引数

4.8.3. 特殊なパラメータ

4.8.3.1. 位置またはキーワード引数

4.8.3.2. 位置専用引数

4.8.3.3. キーワード専用引数

4.8.3.4. 関数の例

4.8.3.5. 要約

4.8.4. 任意引数リスト

4.8.5. 引数リストのアンパック

4.8.6. ラムダ式

4.8.7. ドキュメンテーション文字列

4.8.8. 関数のアノテーション

4.9. 間奏曲: コーディングスタイル

5. データ構造

5.1. リスト型についてもう少し

5.1.1. リストをスタックとして使う

5.1.2. リストをキューとして使う

5.1.3. リストの内包表記

5.1.4. ネストしたリストの内包表記

5.2. del 文

5.3. タプルとシーケンス

5.4. 集合型

5.5. 辞書型 (dictionary)

5.6. ループのテクニック

5.7. 条件についてもう少し

5.8. シーケンスとその他の型の比較

6. モジュール

6.1. モジュールについてもうすこし

6.1.1. モジュールをスクリプトとして実行する

6.1.2. モジュール検索パス

6.1.3. "コンパイル" された Python ファイル

6.2. 標準モジュール

6.3. dir() 関数

6.4. パッケージ

6.4.1. パッケージから * を import する

6.4.2. パッケージ内参照

6.4.3. 複数ディレクトリ中のパッケージ

7. 入力と出力

7.1. 出力を見やすくフォーマットする

7.1.1. フォーマット済み文字列リテラル

7.1.2. 文字列の format() メソッド

7.1.3. 文字列の手作業でのフォーマット

7.1.4. 古い文字列書式設定方法

7.2. ファイルを読み書きする

7.2.1. ファイルオブジェクトのメソッド

7.2.2. json による構造化されたデータの保存

8. エラーと例外

8.1. 構文エラー

8.2. 例外

8.3. 例外を処理する

8.4. 例外を送出する

8.5. 例外の連鎖

8.6. ユーザー定義例外

8.7. クリーンアップ動作を定義する

8.8. 定義済みクリーンアップ処理

8.9. 複数の関連しない例外の送出と処理

8.10. ノートによって例外を充実させる

9. クラス

9.1. 名前とオブジェクトについて

9.2. Python のスコープと名前空間

9.2.1. スコープと名前空間の例

9.3. クラス初見

9.3.1. クラス定義の構文

9.3.2. クラスオブジェクト

9.3.3. インスタンスオブジェクト

9.3.4. メソッドオブジェクト

9.3.5. クラスとインスタンス変数

9.4. いろいろな注意点

9.5. 継承

9.5.1. 多重継承

9.6. プライベート変数

9.7. 残りのはしばし

9.8. イテレータ (iterator)

9.9. ジェネレータ (generator)

9.10. ジェネレータ式

10. 標準ライブラリミニツアー

10.1. OSへのインターフェース

10.2. ファイルのワイルドカード表記

10.3. コマンドライン引数

10.4. エラー出力のリダイレクトとプログラムの終了

10.5. 文字列のパターンマッチング

10.6. 数学

10.7. インターネットへのアクセス

10.8. 日付と時刻

10.9. データ圧縮

10.10. パフォーマンスの計測

10.11. 品質管理

10.12. バッテリー同梱

11. 標準ライブラリミニツアー --- その 2

11.1. 出力のフォーマット

11.2. 文字列テンプレート

11.3. バイナリデータレコードの操作

11.4. マルチスレッディング

11.5. ログ記録

11.6. 弱参照

11.7. リスト操作のためのツール

11.8. 10 進浮動小数演算

12. 仮想環境とパッケージ

12.1. はじめに

12.2. 仮想環境の作成

12.3. pip を使ったパッケージ管理

13. さあ何を？

14. 対話入力編集と履歴置換

14.1. タブ補完と履歴編集

14.2. 対話的インタープリタの代替

15. 浮動小数点演算、その問題と制限

15.1. 表現エラー

16. 付録

16.1. 対話モード

16.1.1. エラー処理

16.1.2. 実行可能な Python スクリプト

16.1.3. 対話モード用の起動時実行ファイル

16.1.4. カスタマイズ用モジュール

Python のセットアップと利用

1. コマンドラインと環境

1.1. コマンドライン

1.1.1. インターフェイスオプション

1.1.2. 一般オプション

1.1.3. その他のオプション

1.1.4. 使うべきでないオプション

1.2. 環境変数

1.2.1. デバッグモード変数

2. Unix プラットフォームで Python を使う

2.1. 最新バージョンの Python の取得とインストール

2.1.1. Linux

2.1.2. FreeBSD と OpenBSD

2.2. Python のビルド

2.3. Python に関係するパスとファイル

2.4. その他

2.5. Custom OpenSSL

3. Python を構成する

3.1. Build Requirements

3.2. 生成されるファイル

3.2.1. 構成スクリプト

3.3. Configureオプション

3.3.1. 一般的なオプション

3.3.2. WebAssembly オプション

3.3.3. インストールオプション

3.3.4. パフォーマンスに関するオプション

3.3.5. Python Debug Build

3.3.6. Debug options

3.3.7. Linker options

3.3.8. Libraries options

3.3.9. Security Options

3.3.10. macOS のオプション

3.3.11. クロスコンパイルのオプション

3.4. Python Build System

3.4.1. Main files of the build system

3.4.2. Main build steps

3.4.3. Main Makefile targets

3.4.4. C extensions

3.5. Compiler and linker flags

3.5.1. Preprocessor flags

3.5.2. Compiler flags

3.5.3. Linker flags

4. Windows で Python を使う

4.1. 完全版インストーラ

4.1.1. インストール手順

4.1.2. MAX_PATH の制限を除去する

4.1.3. インストーラの GUI なしでインストールする

4.1.4. ダウンロード不要なインストール

4.1.5. インストール後の変更

4.2. Microsoft ストアパッケージ

4.2.1. 既知の問題

4.2.1.1. Redirection of local data, registry, and temporary paths

4.3. nuget.org パッケージ

4.4. 埋め込み可能なパッケージ

4.4.1. Python アプリケーション

4.4.2. Python の埋め込み

4.5. 別のバンドル

4.6. Python を構成する

4.6.1. 補足: 環境変数の設定

4.6.2. Python 実行ファイルを見つける

4.7. UTF-8 モード

4.8. Windows の Python ランチャ

4.8.1. 最初に

4.8.1.1. コマンドラインから起動する

4.8.1.2. 仮想環境 (Virtual environments)

4.8.1.3. スクリプトから起動する

4.8.1.4. ファイルの関連付けから起動する

4.8.2. シェバン (shebang) 行

4.8.3. シェバン行の引数

4.8.4. カスタマイズ

4.8.4.1. INI ファイルによるカスタマイズ

4.8.4.2. デフォルトのPythonバージョンのカスタマイズ

4.8.5. 診断

4.8.6. Dry Run

4.8.7. Install on demand

4.8.8. Return codes

4.9. モジュールの検索

4.10. 追加のモジュール

4.10.1. PyWin32

4.10.2. cx_Freeze

4.11. Windows 上で Python をコンパイルする

4.12. ほかのプラットフォーム

5. Mac で Python を使う

5.1. Getting and Installing Python

5.1.1. Python スクリプトの実行方法

5.1.2. GUI でスクリプトを実行

5.1.3. Configuration

5.2. IDE

5.3. 追加の Python パッケージのインストール

5.4. GUI プログラミング

5.5. Distributing Python Applications

5.6. 他のリソース

6. エディタと IDE

Python 言語リファレンス

1. はじめに

1.1. 別のPythonの実装

1.2. 本マニュアルにおける表記法

2. 字句解析

2.1. 行構造

2.1.1. 論理行 (logical line)

2.1.2. 物理行 (physical line)

2.1.3. コメント (Comments)

2.1.4. エンコード宣言 (encoding declaration)

2.1.5. 明示的な行継続

2.1.6. 非明示的な行継続

2.1.7. 空行

2.1.8. インデント

2.1.9. トークン間の空白

2.2. その他のトークン

2.3. 識別子 (identifier) およびキーワード (keyword)

2.3.1. キーワード (keyword)

2.3.2. ソフトキーワード

2.3.3. 予約済みの識別子種 (reserved classes of identifiers)

2.4. リテラル

2.4.1. 文字列およびバイト列リテラル

2.4.1.1. Escape sequences

2.4.2. 文字列リテラルの結合 (concatenation)

2.4.3. f-strings

2.4.4. 数値リテラル

2.4.5. 整数リテラル

2.4.6. 浮動小数点数リテラル

2.4.7. 虚数 (imaginary) リテラル

2.5. 演算子

2.6. デリミタ (delimiter)

3. データモデル

3.1. オブジェクト、値、および型

3.2. 標準型の階層

3.2.1. None

3.2.2. NotImplemented

3.2.3. Ellipsis

3.2.4. numbers.Number

3.2.4.1. numbers.Integral (整数)

3.2.4.2. numbers.Real (float) (実数)

3.2.4.3. numbers.Complex (complex)

3.2.5. シーケンス型 (sequence)

3.2.5.1. 変更不能なシーケンス (immutable sequence)

3.2.5.2. 変更可能なシーケンス型 (mutable sequence)

3.2.6. 集合型

3.2.7. マッピング型 (mapping)

3.2.7.1. 辞書型 (dictionary)

3.2.8. 呼び出し可能型 (callable type)

3.2.8.1. ユーザ定義関数 (user-defined function)

3.2.8.1.1. Special read-only attributes

3.2.8.1.2. Special writable attributes

3.2.8.2. インスタンスメソッド

3.2.8.3. ジェネレータ関数 (generator function)

3.2.8.4. コルーチン関数 (coroutine function)

3.2.8.5. 非同期ジェネレータ関数 (asynchronous generator function)

3.2.8.6. 組み込み関数 (built-in function)

3.2.8.7. 組み込みメソッド (built-in method)

3.2.8.8. クラス

3.2.8.9. クラスのインスタンス

3.2.9. モジュール

3.2.10. カスタムクラス型

3.2.11. クラスインスタンス (class instance)

3.2.12. I/O オブジェクト (ファイルオブジェクトの別名)

3.2.13. 内部型 (internal type)

3.2.13.1. コードオブジェクト

3.2.13.1.1. Special read-only attributes

3.2.13.1.2. Methods on code objects

3.2.13.2. フレーム (frame) オブジェクト

3.2.13.2.1. Special read-only attributes

3.2.13.2.2. Special writable attributes

3.2.13.2.3. Frame object methods

3.2.13.3. トレースバック (traceback) オブジェクト

3.2.13.4. スライス (slice) オブジェクト

3.2.13.5. 静的メソッド (static method) オブジェクト

3.2.13.6. クラスメソッドオブジェクト

3.3. 特殊メソッド名

3.3.1. 基本的なカスタマイズ

3.3.2. 属性値アクセスをカスタマイズする

3.3.2.1. モジュールの属性値アクセスをカスタマイズする

3.3.2.2. デスクリプタ (descriptor) の実装

3.3.2.3. デスクリプタの呼び出し

3.3.2.4. __slots__

3.3.3. クラス生成をカスタマイズする

3.3.3.1. メタクラス

3.3.3.2. MRO エントリの解決

3.3.3.3. 適切なメタクラスの決定

3.3.3.4. クラスの名前空間の準備

3.3.3.5. クラス本体の実行

3.3.3.6. クラスオブジェクトの作成

3.3.3.7. メタクラスの用途

3.3.4. インスタンスのカスタマイズとサブクラスチェック

3.3.5. ジェネリック型をエミュレートする

3.3.5.1. The purpose of __class_getitem__

3.3.5.2. __class_getitem__ versus __getitem__

3.3.6. 呼び出し可能オブジェクトをエミュレートする

3.3.7. コンテナをエミュレートする

3.3.8. 数値型をエミュレートする

3.3.9. with文とコンテキストマネージャ

3.3.10. クラスパターンマッチの位置引数のカスタマイズ

3.3.11. Emulating buffer types

3.3.12. 特殊メソッド検索

3.4. コルーチン

3.4.1. 待機可能オブジェクト (Awaitable Object)

3.4.2. コルーチンオブジェクト

3.4.3. 非同期イテレータ (Asynchronous Iterator)

3.4.4. 非同期コンテキストマネージャ (Asynchronous Context Manager)

4. 実行モデル

4.1. プログラムの構造

4.2. 名前づけと束縛 (naming and binding)

4.2.1. 名前の束縛

4.2.2. 名前解決

4.2.3. Annotation scopes

4.2.4. Lazy evaluation

4.2.5. 組み込みと制限付きの実行

4.2.6. 動的な機能とのやりとり

4.3. 例外

5. インポートシステム

5.1. importlib

5.2. パッケージ

5.2.1. 通常のパッケージ

5.2.2. 名前空間パッケージ

5.3. 検索

5.3.1. モジュールキャッシュ

5.3.2. ファインダーとローダー

5.3.3. インポートフック

5.3.4. メタパス

5.4. ロード

5.4.1. ローダー

5.4.2. サブモジュール

5.4.3. モジュール仕様

5.4.4. インポート関連のモジュール属性

5.4.5. module.__path__

5.4.6. モジュールの repr

5.4.7. キャッシュされたバイトコードの無効化

5.5. パスベース・ファインダー

5.5.1. パスエントリ・ファインダー

5.5.2. パスエントリ・ファインダー・プロトコル

5.6. 標準のインポートシステムを置き換える

5.7. Package Relative Imports

5.8. __main__ に対する特別な考慮

5.8.1. __main__.__spec__

5.9. 参考資料

6. 式 (expression)

6.1. 算術変換 (arithmetic conversion)

6.2. アトム、原子的要素 (atom)

6.2.1. 識別子 (identifier、または名前 (name))

6.2.2. リテラル

6.2.3. 丸括弧形式 (parenthesized form)

6.2.4. リスト、集合、辞書の表示

6.2.5. リスト表示

6.2.6. 集合表示

6.2.7. 辞書表示

6.2.8. ジェネレータ式

6.2.9. Yield 式

6.2.9.1. ジェネレータ-イテレータメソッド

6.2.9.2. 使用例

6.2.9.3. 非同期ジェネレータ関数 (asynchronous generator function)

6.2.9.4. 非同期ジェネレータイテレータメソッド

6.3. プライマリ

6.3.1. 属性参照

6.3.2. 添字表記 (subscription)

6.3.3. スライス表記 (slicing)

6.3.4. 呼び出し (call)

6.4. Await 式

6.5. べき乗演算 (power operator)

6.6. 単項算術演算とビット単位演算 (unary arithmetic and bitwise operation)

6.7. 二項算術演算 (binary arithmetic operation)

6.8. シフト演算 (shifting operation)

6.9. ビット単位演算の二項演算 (binary bitwise operation)

6.10. 比較

6.10.1. 値の比較

6.10.2. 所属検査演算

6.10.3. 同一性の比較

6.11. ブール演算 (boolean operation)

6.12. 代入式

6.13. 条件式 (Conditional Expressions)

6.14. ラムダ (lambda)

6.15. 式のリスト

6.16. 評価順序

6.17. 演算子の優先順位

7. 単純文 (simple statement)

7.1. 式文 (expression statement)

7.2. 代入文 (assignment statement)

7.2.1. 累算代入文 (augmented assignment statement)

7.2.2. 注釈付き代入文 (annotated assignment statements)

7.3. assert 文

7.4. pass 文

7.5. del 文

7.6. return 文

7.7. yield 文

7.8. raise 文

7.9. break 文

7.10. continue 文

7.11. import 文

7.11.1. future 文 (future statement)

7.12. global 文

7.13. nonlocal 文

7.14. The type statement

8. 複合文 (compound statement)

8.1. if 文

8.2. while 文

8.3. for 文

8.4. try 文

8.4.1. except 節

8.4.2. except* 節

8.4.3. else 節

8.4.4. finally 節

8.5. with 文

8.6. match 文

8.6.1. 概要

8.6.2. ガード

8.6.3. 論駁不可能なケースブロック

8.6.4. パターン

8.6.4.1. OR パターン

8.6.4.2. AS パターン

8.6.4.3. リテラルパターン

8.6.4.4. キャプチャパターン

8.6.4.5. ワイルドカードパターン

8.6.4.6. 値パターン

8.6.4.7. グループパターン

8.6.4.8. シーケンスパターン

8.6.4.9. マッピングパターン

8.6.4.10. クラスパターン

8.7. 関数定義

8.8. クラス定義

8.9. コルーチン

8.9.1. コルーチン関数定義

8.9.2. async for 文

8.9.3. async with 文

8.10. Type parameter lists

8.10.1. Generic functions

8.10.2. Generic classes

8.10.3. Generic type aliases

9. トップレベル要素

9.1. 完全な Python プログラム

9.2. ファイル入力

9.3. 対話的入力

9.4. 式入力

10. 完全な文法仕様

Python 標準ライブラリ

はじめに

利用可能性について

WebAssemblyプラットフォーム

組み込み関数

組み込み定数

site モジュールで追加される定数

組み込み型

真理値判定

ブール演算 --- and, or, not

比較

数値型 int, float, complex

整数型におけるビット単位演算

整数型における追加のメソッド

浮動小数点数に対する追加のメソッド

数値型のハッシュ化

ブーリアン型 - bool

イテレータ型

ジェネレータ型

シーケンス型 --- list, tuple, range

共通のシーケンス演算

イミュータブルなシーケンス型

ミュータブルなシーケンス型

リスト型 (list)

タプル型 (tuple)

range

テキストシーケンス型 --- str

文字列メソッド

printf 形式の文字列書式化

バイナリシーケンス型 --- bytes, bytearray, memoryview

バイトオブジェクト

bytearray オブジェクト

bytes と bytearray の操作

printf 形式での bytes の書式化

メモリビュー

set（集合）型 --- set, frozenset

マッピング型 --- dict

辞書ビューオブジェクト

コンテキストマネージャ型

型アノテーション型 --- ジェネリックエイリアス 、 ユニオン

ジェネリックエイリアス型

標準ジェネリッククラス

GenericAlias オブジェクトの特別な属性

Union 型

その他の組み込み型

モジュール

クラスおよびクラスインスタンス

関数

メソッド

コードオブジェクト

型オブジェクト

ヌルオブジェクト

Ellipsis オブジェクト

NotImplemented オブジェクト

内部オブジェクト

特殊属性

整数と文字列の変換での長さ制限

影響のあるAPI

上限値を設定する

Recommended configuration

組み込み例外

例外コンテキスト

組み込み例外から継承する

基底クラス

具象例外

OS 例外

警告

例外グループ

例外のクラス階層

テキスト処理サービス

string --- Common string operations

文字列定数

カスタムの文字列書式化

書式指定文字列の文法

書式指定ミニ言語仕様

書式指定例

テンプレート文字列

ヘルパー関数

re --- Regular expression operations

正規表現のシンタックス

モジュールコンテンツ

フラグ

関数

例外

正規表現オブジェクト

マッチオブジェクト

正規表現の例

ペアの確認

scanf() をシミュレートする

search() vs. match()

電話帳を作る

テキストの秘匿

全ての副詞を見つける

全ての副詞とその位置を見つける

Raw 文字列記法

トークナイザを書く

difflib --- Helpers for computing deltas

SequenceMatcherオブジェクト

SequenceMatcher の例

Differ オブジェクト

Differ の例

difflib のコマンドラインインターフェース

ndiff example

textwrap --- Text wrapping and filling

unicodedata --- Unicode Database

stringprep --- Internet String Preparation

readline --- GNU readline interface

初期化ファイル

行バッファ

履歴ファイル

履歴リスト

開始フック

補完

使用例

rlcompleter --- Completion function for GNU readline

バイナリデータ処理

struct --- Interpret bytes as packed binary data

関数と例外

書式文字列

バイトオーダ、サイズ、アラインメント

書式指定文字

使用例

Applications

Native Formats

Standard Formats

クラス

codecs --- Codec registry and base classes

Codec 基底クラス

エラーハンドラ

ステートレスなエンコードとデコード

インクリメンタルなエンコードとデコード

IncrementalEncoder オブジェクト

IncrementalDecoder オブジェクト

ストリームのエンコードとデコード

StreamWriter オブジェクト

StreamReader オブジェクト

StreamReaderWriter オブジェクト

StreamRecoder オブジェクト

エンコーディングと Unicode

標準エンコーディング

Python 特有のエンコーディング

テキストエンコーディング

バイナリ変換 (Binary Transforms)

テキスト変換 (Text Transforms)

encodings.idna --- アプリケーションにおける国際化ドメイン名 (IDNA)

encodings.mbcs --- Windows ANSI コードページ

encodings.utf_8_sig --- BOM 印付き UTF-8

データ型

datetime --- Basic date and time types

Aware オブジェクトと Naive オブジェクト

定数

利用可能なデータ型

共通の特徴

オブジェクトが Aware なのか Naive なのかの判断

timedelta オブジェクト

使用例: timedelta

date オブジェクト

使用例: date

datetime オブジェクト

使用例: datetime

time オブジェクト

使用例: time

tzinfo オブジェクト

timezone オブジェクト

strftime() と strptime() の振る舞い

strftime() と strptime() の書式コード

技術詳細

zoneinfo --- IANA time zone support

ZoneInfo を使用する

データソース

Configuring the data sources

Compile-time configuration

Environment configuration

Runtime configuration

ZoneInfo クラス

文字列表現

Pickle serialization

関数

Globals

例外と警告

calendar --- General calendar-related functions

コマンドラインからの使用

collections --- Container datatypes

ChainMap オブジェクト

ChainMap の例とレシピ

Counter オブジェクト

deque オブジェクト

deque のレシピ

defaultdict オブジェクト

defaultdict の使用例

namedtuple() 名前付きフィールドを持つタプルのファクトリ関数

OrderedDict オブジェクト

OrderedDict の例とレシピ

UserDict オブジェクト

UserList オブジェクト

UserString オブジェクト

collections.abc --- Abstract Base Classes for Containers

コレクション抽象基底クラス

コレクションの抽象基底クラス -- 詳細な説明

例とレシピ

heapq --- Heap queue algorithm

基本的な例

優先度キュー実装の注釈

理論

bisect --- Array bisection algorithm

パフォーマンスに関するメモ

ソート済みリストの探索

使用例

array --- Efficient arrays of numeric values

weakref --- 弱参照

弱参照オブジェクト

使用例

ファイナライザオブジェクト

Comparing finalizers with __del__() methods

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

動的な型生成

標準的なインタプリタ型

追加のユーティリティクラスと関数

コルーチンユーティリティ関数

copy --- Shallow and deep copy operations

pprint --- Data pretty printer

関数

PrettyPrinter オブジェクト

使用例

reprlib --- Alternate repr() implementation

Reprオブジェクト

Reprオブジェクトをサブクラス化する

enum --- Support for enumerations

モジュールコンテンツ

データ型

__dunder__ 名のサポート

_sunder_ 名のサポート

ユーティリティとデコレータ

注釈

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

例外

数値と数学モジュール

numbers --- Numeric abstract base classes

数値塔

型実装者のための注意事項

さらに数のABCを追加する

算術演算の実装

math --- Mathematical functions

数論および数表現の関数

指数関数と対数関数

三角関数

角度変換

双曲線関数

特殊関数

定数

cmath --- Mathematical functions for complex numbers

極座標変換

指数関数と対数関数

三角関数

双曲線関数

類別関数

定数

decimal --- Decimal fixed point and floating point arithmetic

クイックスタートチュートリアル

Decimal オブジェクト

論理引数

Context オブジェクト

定数

丸めモード

シグナル

浮動小数点数に関する注意

精度を上げて丸め誤差を抑制する

特殊値

スレッドを使った処理

レシピ

Decimal FAQ

fractions --- Rational numbers

random --- Generate pseudo-random numbers

保守 (bookkeeping) 関数

バイト列用の関数

整数用の関数

シーケンス用の関数

Discrete distributions

実数分布

他の生成器

再現性について

使用例

レシピ

statistics --- Mathematical statistics functions

平均及び中心位置の測度

分散の測度

2入力間の関係の統計

関数の詳細

例外

NormalDist オブジェクト

例とレシピ

Classic probability problems

Monte Carlo inputs for simulations

Approximating binomial distributions

Naive bayesian classifier

Kernel density estimation

関数型プログラミング用モジュール

itertools --- Functions creating iterators for efficient looping

Itertool関数

Itertools レシピ

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

partial オブジェクト

operator --- Standard operators as functions

演算子から関数への対応表

インプレース (in-place) 演算子

ファイルとディレクトリへのアクセス

pathlib --- Object-oriented filesystem paths

基本的な使い方

純粋パス

全般的な性質

演算子

個別の構成要素へのアクセス

メソッドとプロパティ

具象パス

メソッド

Correspondence to tools in the os module

os.path --- Common pathname manipulations

fileinput --- Iterate over lines from multiple input streams

stat --- Interpreting stat() results

filecmp --- File and Directory Comparisons

dircmp クラス

tempfile --- Generate temporary files and directories

使用例

非推奨の関数と変数

glob --- Unix style pathname pattern expansion

fnmatch --- Unix filename pattern matching

linecache --- Random access to text lines

shutil --- High-level file operations

ディレクトリとファイルの操作

プラットフォーム依存の効率的なコピー操作

copytree の例

rmtree の例

アーカイブ化操作

アーカイブ化の例

base_dir を使ったアーカイブ化の例

出力ターミナルのサイズの取得

データの永続化

pickle --- Python object serialization

他の Python モジュールとの関係

marshal との比較

json との比較

データストリームの形式

モジュールインターフェース

pickle 化、非 pickle 化できるもの

クラスインスタンスの pickle 化

外部オブジェクトの永続化

ディスパッチテーブル

状態を持つオブジェクトの扱い

型、関数、その他のオブジェクトに対するリダクションのカスタマイズ

アウトオブバウンドバッファ

生産者 API

消費者 API

使用例

グローバル変数を制限する

性能

使用例

copyreg --- Register pickle support functions

使用例

shelve --- Python object persistence

制限事項

使用例

marshal --- Internal Python object serialization

dbm --- Interfaces to Unix "databases"

dbm.gnu --- GNU database manager

dbm.ndbm --- New Database Manager

dbm.dumb --- 可搬性のある DBM 実装

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

チュートリアル

リファレンス

モジュール関数

モジュール定数

Connection オブジェクト

Cursor オブジェクト

Row オブジェクト

Blob オブジェクト

PrepareProtocol オブジェクト

例外

SQLite と Python の型

デフォルトの適合関数(adapters)とデフォルトの変換関数(converters)(非推奨)

コマンドライン・インターフェース

ハウツー・ガイド

プレースホルダを使用して SQL クエリに値を結び付ける方法

カスタム Python 型を SQLite 値に適合させる方法

適合可能オブジェクトの書き方

適合用呼び出し可能オブジェクト(adapter callables)の登録方法

SQLite 値をカスタム Python 型に変換する方法

適合関数と変換関数のレシピ集

接続(connection)ショートカット・メソッドの使い方

接続(connection)コンテキストマネージャの使い方

SQLite URI の操作方法

行工場(row factories)の作成方法と使用方法

How to handle non-UTF-8 text encodings

説明

トランザクション制御

autocommit 属性に依るトランザクション制御

isolation_level 属性に依るトランザクション制御

データ圧縮とアーカイブ

zlib --- Compression compatible with gzip

gzip --- Support for gzip files

使い方の例

コマンドラインインターフェイス

コマンドラインオプション

bz2 --- Support for bzip2 compression

ファイルの圧縮/解凍

逐次圧縮および展開

一括圧縮/解凍

使い方の例

lzma --- Compression using the LZMA algorithm

圧縮ファイルへの読み書き

メモリ上での圧縮と展開

その他

カスタムフィルタチェインの指定

使用例

zipfile --- Work with ZIP archives

ZipFile オブジェクト

Path オブジェクト

PyZipFile オブジェクト

ZipInfo オブジェクト

コマンドラインインターフェイス

コマンドラインオプション

Decompression pitfalls

From file itself

File System limitations

Resources limitations

Interruption

Default behaviors of extraction

tarfile --- Read and write tar archive files

TarFile オブジェクト

TarInfo オブジェクト

Extraction filters

Default named filters

Filter errors

Hints for further verification

Supporting older Python versions

Stateful extraction filter example

コマンドラインインターフェイス

コマンドラインオプション

使用例

サポートしている tar フォーマット

Unicode に関する問題

ファイルフォーマット

csv --- CSV File Reading and Writing

モジュールコンテンツ

Dialect クラスと書式化パラメータ

reader オブジェクト

writer オブジェクト

使用例

configparser --- Configuration file parser

クイックスタート

サポートされるデータ型

代替値

サポートするINI ファイルの構造

値の補間

マップ型プロトコルアクセス

パーサーの振る舞いをカスタマイズする

レガシーな API の例

ConfigParser オブジェクト

RawConfigParser オブジェクト

例外

tomllib --- Parse TOML files

使用例

変換表

netrc --- netrc file processing

netrc オブジェクト

plistlib --- Generate and parse Apple .plist files

使用例

暗号関連のサービス

hashlib --- Secure hashes and message digests

ハッシュアルゴリズム

使用法

Constructors

属性

Hash Objects

SHAKE 可変長ダイジェスト

File hashing

鍵導出

BLAKE2

ハッシュオブジェクトの作成

定数

使用例

簡単なハッシュ化

Using different digest sizes

Keyed hashing

Randomized hashing

Personalization

ツリーモード

クレジット:

hmac --- Keyed-Hashing for Message Authentication

secrets --- Generate secure random numbers for managing secrets

乱数

トークンの生成

トークンは何バイト使うべきか？

その他の関数

レシピとベストプラクティス

汎用オペレーティングシステムサービス

os --- Miscellaneous operating system interfaces

ファイル名、コマンドライン引数、および環境変数

Python UTF-8 Mode

プロセスのパラメーター

ファイルオブジェクトの生成

ファイル記述子の操作

ターミナルのサイズの問い合わせ

ファイル記述子の継承

ファイルとディレクトリ

Linux 拡張属性

プロセス管理

スケジューラーへのインターフェイス

雑多なシステム情報

乱数

io --- Core tools for working with streams

概要

テキスト I/O

バイナリ I/O

Raw I/O

Text Encoding

Opt-in EncodingWarning

高水準のモジュールインターフェイス

クラス階層

I/O 基底クラス

生ファイルI/O

バッファ付きストリーム

テキスト I/O

性能

バイナリ I/O

テキスト I/O

マルチスレッディング

リエントラント性

time --- Time access and conversions

関数

Clock ID Constants

Timezone Constants

argparse --- Parser for command-line options, arguments and sub-commands

中核的な機能

add_argument() のためのクイックリンク

使用例

パーサーを作る

引数を追加する

引数を解析する

ArgumentParser オブジェクト

prog

usage

description

epilog

parents

formatter_class

prefix_chars

fromfile_prefix_chars

argument_default

allow_abbrev

conflict_handler

add_help

exit_on_error

add_argument() メソッド

name または flags

action

nargs

const

default

type

choices

required

help

metavar

dest

Action クラス

parse_args() メソッド

オプション値の文法

不正な引数

- を含む引数

引数の短縮形 (先頭文字でのマッチング)

sys.argv 以外

Namespace オブジェクト

その他のユーティリティ

サブコマンド

FileType オブジェクト

引数グループ

相互排他

パーサーのデフォルト値

ヘルプの表示

部分解析

ファイル解析のカスタマイズ

終了メソッド

混在した引数の解析

optparse からのアップグレード

例外

getopt --- C-style parser for command line options

logging --- Logging facility for Python

ロガーオブジェクト

ロギングレベル

ハンドラオブジェクト

フォーマッタオブジェクト

フィルタオブジェクト

LogRecord オブジェクト

LogRecord 属性

LoggerAdapter オブジェクト

スレッドセーフ性

モジュールレベルの関数

モジュールレベル属性

warnings モジュールとの統合

logging.config --- Logging configuration

環境設定のための関数

セキュリティで考慮すべき点

環境設定辞書スキーマ

辞書スキーマの詳細

増分設定

オブジェクトの接続

ユーザ定義オブジェクト

ハンドラの設定順序

外部オブジェクトへのアクセス

内部オブジェクトへのアクセス

インポート解決とカスタムインポーター

Configuring QueueHandler and QueueListener

環境設定ファイルの書式

logging.handlers --- Logging handlers

StreamHandler

FileHandler

NullHandler

WatchedFileHandler

BaseRotatingHandler

RotatingFileHandler

TimedRotatingFileHandler

SocketHandler

DatagramHandler

SysLogHandler

NTEventLogHandler

SMTPHandler

MemoryHandler

HTTPHandler

QueueHandler

QueueListener

getpass --- Portable password input

curses --- Terminal handling for character-cell displays

関数

Window オブジェクト

定数

curses.textpad --- curses プログラムのためのテキスト入力ウィジェット

Textbox オブジェクト

curses.ascii --- Utilities for ASCII characters

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

関数

Panel オブジェクト

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

クロスプラットフォーム

Java プラットフォーム

Windows プラットフォーム

macOS プラットフォーム

Unix プラットフォーム

Linux プラットフォーム

errno --- Standard errno system symbols

ctypes --- A foreign function library for Python

ctypesチュートリアル

動的リンクライブラリをロードする

ロードしたdllから関数にアクセスする

関数を呼び出す

基本データ型

続・関数を呼び出す

Calling variadic functions

自作のデータ型とともに関数を呼び出す

要求される引数の型を指定する (関数プロトタイプ)

戻り値の型

ポインタを渡す(または、パラメータの参照渡し)

構造体と共用体

構造体/共用体アライメントとバイトオーダー

構造体と共用体におけるビットフィールド

配列

ポインタ

型変換

不完全型

コールバック関数

dllからエクスポートされた値へアクセスする

びっくり仰天

可変サイズのデータ型

ctypesリファレンス

共有ライブラリを見つける

共有ライブラリをロードする

外部関数

関数プロトタイプ

ユーティリティー関数

データ型

基本データ型

構造化データ型

配列とポインタ

並行実行

threading --- Thread-based parallelism

スレッドローカルデータ

Thread オブジェクト

Lock オブジェクト

RLock オブジェクト

Condition オブジェクト

Semaphore オブジェクト

Semaphore の例

Event オブジェクト

Timer オブジェクト

バリアオブジェクト

with 文でのロック・条件変数・セマフォの使い方

multiprocessing --- Process-based parallelism

はじめに

Process クラス

コンテキストと開始方式

プロセス間でのオブジェクト交換

プロセス間の同期

プロセス間での状態の共有

ワーカープロセスのプールを使用

リファレンス

Process クラスと例外

パイプ (Pipe) とキュー (Queue)

その他

Connection オブジェクト

同期プリミティブ

共有 ctypes オブジェクト

multiprocessing.sharedctypes モジュール

マネージャー

カスタマイズされたマネージャー

リモートマネージャーを使用する

Proxy オブジェクト

クリーンアップ

プロセスプール

リスナーとクライアント

アドレスフォーマット

認証キー

ログ記録

multiprocessing.dummy モジュール

プログラミングガイドライン

すべての開始方式について

開始方式が spawn および forkserver の場合

使用例

multiprocessing.shared_memory --- Shared memory for direct access across processes

The concurrent package

concurrent.futures --- Launching parallel tasks

Executor オブジェクト

ThreadPoolExecutor

ThreadPoolExecutor の例

ProcessPoolExecutor

ProcessPoolExecutor の例

Future オブジェクト

モジュール関数

例外クラス

subprocess --- Subprocess management

subprocess モジュールを使う

よく使われる引数

Popen コンストラクター

例外

セキュリティで考慮すべき点

Popen オブジェクト

Windows Popen ヘルパー

Windows Constants

古い高水準 API

古い関数を subprocess モジュールで置き換える

Replacing /bin/sh shell command substitution

シェルのパイプラインを置き換える

os.system() を置き換える

os.spawn 関数群を置き換える

os.popen(), os.popen2(), os.popen3() を置き換える

Replacing functions from the popen2 module

レガシーなシェル呼び出し関数

注釈

Windows における引数シーケンスから文字列への変換

Disabling use of vfork() or posix_spawn()

sched --- Event scheduler

スケジューラオブジェクト

queue --- A synchronized queue class

キューオブジェクト

SimpleQueue オブジェクト

contextvars --- Context Variables

コンテキスト変数

マニュアルでのコンテキスト管理

asyncio サポート

_thread --- Low-level threading API

ネットワーク通信とプロセス間通信

asyncio --- Asynchronous I/O

Runners

非同期プログラムの実行

Runner context manager

Handling Keyboard Interruption

コルーチンと Task

コルーチン

Awaitable

Task の作成

タスクのキャンセル

Task Groups

スリープ

並行な Task 実行

Eager Task Factory

キャンセルからの保護

タイムアウト

要素の終了待機

スレッド内での実行

外部スレッドからのスケジュール

イントロスペクション

Task オブジェクト

ストリーム

StreamReader

StreamWriter

使用例

ストリームを使った TCP Echo クライアント

ストリームを使った TCP Echo サーバー

HTTP ヘッダーの取得

ストリームを使ってデータを待つオープンソケットの登録

同期プリミティブ

Lock

Event

Condition

Semaphore

BoundedSemaphore

Barrier

サブプロセス

サブプロセスの生成

定数

サブプロセスとやりとりする

サブプロセスとスレッド

使用例

キュー

Queue

優先度付きのキュー

LIFO キュー

例外

使用例

例外

イベントループ

イベントループのメソッド

ループの開始と停止

コールバックのスケジューリング

遅延コールバックのスケジューリング

フューチャーとタスクの生成

ネットワーク接続の確立

ネットワークサーバの生成

ファイルの転送

TLS へのアップグレード

ファイル記述子の監視

ソケットオブジェクトと直接やりとりする

DNS

パイプとやりとりする

Unix シグナル

スレッドまたはプロセスプールでコードを実行する

エラーハンドリング API

デバッグモードの有効化

サブプロセスの実行

コールバックのハンドル

Serverオブジェクト

イベントループの実装

使用例

call_soon() を使った Hello World

call_later() で現在の日時を表示する

読み込みイベント用ファイル記述子の監視

SIGINT および SIGTERM 用のシグナルハンドラーの設定

Future

Future の関数

Future オブジェクト

トランスポートとプロトコル

トランスポート

トランスポートのクラス階層構造

基底トランスポート

読み出し専用のトランスポート

書き込み専用のトランスポート

データグラムトランスポート

サブプロセス化されたトランスポート

プロトコル

基底プロトコル

基底プロトコル

ストリーミングプロトコル

バッファリングされたストリーミングプロトコル

データグラムプロトコル

サブプロセスプロトコル

使用例

TCP エコーサーバー

TCP エコークライアント

UDP エコーサーバー

UDP エコークライアント

既存のソケットへの接続

loop.subprocess_exec() と SubprocessProtocol

ポリシー

ポリシーの取得と設定

ポリシーオブジェクト

プロセスのウオッチャー

ポリシーのカスタマイズ

プラットフォームでのサポート

全てのプラットホーム

Windows

Windows におけるサブプロセスのサポート

macOS

Extending

Writing a Custom Event Loop

Future and Task private constructors

Task lifetime support

高水準の API インデックス

Task

キュー

サブプロセス

ストリーム

同期

例外

低水準の API インデックス

イベントループの取得

イベントループのメソッド

トランスポート

プロトコル

イベントループのポリシー

asyncio での開発

デバッグモード

並行処理とマルチスレッド処理

ブロッキングコードの実行

ログ記録

待ち受け処理を伴わないコルーチンの検出

回収されない例外の検出

socket --- Low-level networking interface

ソケットファミリー

モジュールの内容

例外

定数

関数

ソケットの作成

その他の関数

socket オブジェクト

ソケットタイムアウトの注意事項

タイムアウトと connect メソッド

タイムアウトと accept メソッド

使用例

ssl --- TLS/SSL wrapper for socket objects

関数、定数、例外

ソケットの作成

コンテキストの作成

例外

乱数生成

証明書の取り扱い

定数

SSL ソケット

SSL コンテキスト

証明書

証明書チェイン

CA 証明書

秘密鍵と証明書の組み合わせ

自己署名証明書

使用例

SSLサポートをテストする

クライアントサイドの処理

サーバサイドの処理

ノンブロッキングソケットについての注意事項

メモリ BIO サポート

SSL セッション

セキュリティで考慮すべき点

最善のデフォルト値

手動での設定

証明書の検証

プロトコルのバージョン

暗号の選択

マルチプロセス化

TLS 1.3

select --- Waiting for I/O completion

/dev/poll ポーリングオブジェクト

エッジおよびレベルトリガポーリング (epoll) オブジェクト

ポーリングオブジェクト

kqueue オブジェクト

kevent オブジェクト

selectors --- High-level I/O multiplexing

はじめに

クラス

使用例

signal --- Set handlers for asynchronous events

一般的なルール

Python のシグナルハンドラの実行

シグナルとスレッド

モジュールの内容

使用例

Note on SIGPIPE

Note on Signal Handlers and Exceptions

mmap --- Memory-mapped file support

MADV_* Constants

MAP_* Constants

インターネット上のデータの操作

email --- An email and MIME handling package

email.message: Representing an email message

email.parser: Parsing email messages

FeedParser API

Parser API

追記事項

email.generator: Generating MIME documents

email.policy: Policy Objects

email.errors: Exception and Defect classes

email.headerregistry: Custom Header Objects

email.contentmanager: Managing MIME Content

Content Manager Instances

email: 使用例

email.message.Message: compat32 API を使用した電子メールメッセージの表現

email.mime: Creating email and MIME objects from scratch

email.header: Internationalized headers

email.charset: Representing character sets

email.encoders: Encoders

email.utils: Miscellaneous utilities

email.iterators: Iterators

json --- JSON encoder and decoder

基本的な使い方

エンコーダとデコーダ

例外

標準への準拠と互換性

文字エンコーディング

無限および NaN の数値

オブジェクト中に重複した名前の扱い

トップレベルの非オブジェクト、非配列の値の扱い

実装の制限

コマンドラインインターフェイス

コマンドラインオプション

mailbox --- Manipulate mailboxes in various formats

Mailbox オブジェクト

Maildir オブジェクト

mbox オブジェクト

MH オブジェクト

Babyl オブジェクト

MMDF オブジェクト

Message オブジェクト

MaildirMessage オブジェクト

mboxMessage オブジェクト

MHMessage オブジェクト

BabylMessage オブジェクト

MMDFMessage オブジェクト

例外

使用例

mimetypes --- Map filenames to MIME types

Mime 型オブジェクト

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

セキュリティで考慮すべき点

binascii --- Convert between binary and ASCII

quopri --- Encode and decode MIME quoted-printable data

構造化マークアップツール

html --- HyperText Markup Language support

html.parser --- Simple HTML and XHTML parser

HTML パーサーアプリケーションの例

HTMLParser メソッド

使用例

html.entities --- Definitions of HTML general entities

XMLを扱うモジュール群

XML の脆弱性

The defusedxml Package

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

チュートリアル

XML 木構造と要素

XML の解析

非ブロックパースのためのプル API

関心ある要素の検索

XML ファイルの編集

XML 文書の構築

名前空間のある XML の解析

XPath サポート

使用例

サポートされている XPath 構文

リファレンス

関数

XInclude サポート

使用例

リファレンス

関数

Element オブジェクト

ElementTree オブジェクト

QName オブジェクト

TreeBuilder オブジェクト

XMLParser オブジェクト

XMLPullParser オブジェクト

例外

xml.dom --- The Document Object Model API

モジュールコンテンツ

DOM 内のオブジェクト

DOMImplementation オブジェクト

Node オブジェクト

NodeList オブジェクト

DocumentType オブジェクト

Document オブジェクト

Element オブジェクト

Attr オブジェクト

NamedNodeMap Objects

Comment オブジェクト

Text オブジェクトおよび CDATASection オブジェクト

ProcessingInstruction オブジェクト

例外

適合性

型の対応付け

アクセサメソッド

xml.dom.minidom --- Minimal DOM implementation

DOM オブジェクト

DOM の例

minidom と DOM 標準

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

DOMEventStream オブジェクト

xml.sax --- Support for SAX2 parsers

SAXException オブジェクト

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

ContentHandler オブジェクト

DTDHandler オブジェクト

EntityResolver オブジェクト

ErrorHandler オブジェクト

LexicalHandler Objects

xml.sax.saxutils --- SAX Utilities

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

XMLReader オブジェクト

IncrementalParser オブジェクト

Locator オブジェクト

InputSource オブジェクト

Attributes インターフェース

AttributesNS インターフェース

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

XMLParser オブジェクト

ExpatError 例外

使用例

内容モデルの記述

Expat エラー定数

インターネットプロトコルとサポート

webbrowser --- Convenient web-browser controller

ブラウザコントローラーオブジェクト

wsgiref --- WSGI Utilities and Reference Implementation

wsgiref.util -- WSGI 環境のユーティリティ

wsgiref.headers -- WSGI レスポンスヘッダツール群

wsgiref.simple_server -- シンプルな WSGI HTTP サーバ

wsgiref.validate --- WSGI 準拠チェッカー

wsgiref.handlers -- サーバ／ゲートウェイのベースクラス

wsgiref.types -- WSGI types for static type checking

使用例

urllib --- URL handling modules

urllib.request --- Extensible library for opening URLs

Request オブジェクト

OpenerDirector オブジェクト

BaseHandler オブジェクト

HTTPRedirectHandler オブジェクト

HTTPCookieProcessor オブジェクト

ProxyHandler オブジェクト

HTTPPasswordMgr オブジェクト

HTTPPasswordMgrWithPriorAuth オブジェクト

AbstractBasicAuthHandler オブジェクト

HTTPBasicAuthHandler オブジェクト

ProxyBasicAuthHandler オブジェクト

AbstractDigestAuthHandler オブジェクト

HTTPDigestAuthHandler オブジェクト

ProxyDigestAuthHandler オブジェクト

HTTPHandler オブジェクト

HTTPSHandler オブジェクト

FileHandler オブジェクト

DataHandler オブジェクト

FTPHandler オブジェクト

CacheFTPHandler オブジェクト

UnknownHandler オブジェクト

HTTPErrorProcessor オブジェクト

使用例

レガシーインターフェース

urllib.request の制限事項

urllib.response --- urllib で使用するレスポンスクラス

urllib.parse --- Parse URLs into components

URL の解析

URL parsing security

ASCII エンコードバイト列の解析

構造化された解析結果

URL のクオート

urllib.error --- Exception classes raised by urllib.request

urllib.robotparser --- Parser for robots.txt

http --- HTTP modules

HTTP ステータスコード

HTTP status category

HTTP methods

http.client --- HTTP protocol client

HTTPConnection オブジェクト

HTTPResponse オブジェクト

使用例

HTTPMessage オブジェクト

ftplib --- FTP protocol client

リファレンス

FTP オブジェクト

FTP_TLS オブジェクト

モジュール変数

poplib --- POP3 protocol client

POP3 オブジェクト

POP3 の例

imaplib --- IMAP4 protocol client

IMAP4 オブジェクト

IMAP4 の使用例

smtplib --- SMTP protocol client

SMTP オブジェクト

SMTP 使用例

uuid --- UUID objects according to RFC 4122

コマンドラインからの使用

使用例

Command-Line Example

socketserver --- A framework for network servers

サーバ生成に関するノート

Serverオブジェクト

Request Handler Objects

使用例

socketserver.TCPServer の例

socketserver.UDPServer の例

非同期処理の Mix-in

http.server --- HTTP servers

セキュリティで考慮すべき点

http.cookies --- HTTP state management

Cookieオブジェクト

Morselオブジェクト

使用例

http.cookiejar --- Cookie handling for HTTP clients

CookieJar および FileCookieJar オブジェクト

FileCookieJar のサブクラスと web ブラウザとの連携

CookiePolicy オブジェクト

DefaultCookiePolicy オブジェクト

Cookieオブジェクト

使用例

xmlrpc --- XMLRPC server and client modules

xmlrpc.client --- XML-RPC client access

ServerProxy オブジェクト

DateTime オブジェクト

Binary オブジェクト

Fault オブジェクト

ProtocolError オブジェクト

MultiCall オブジェクト

補助関数

クライアントのサンプル

クライアントとサーバーの利用例

xmlrpc.server --- Basic XML-RPC servers

SimpleXMLRPCServer オブジェクト

SimpleXMLRPCServer の例

CGIXMLRPCRequestHandler

XMLRPC サーバの文書化

DocXMLRPCServer オブジェクト

DocCGIXMLRPCRequestHandler

ipaddress --- IPv4/IPv6 manipulation library

便利なファクトリ関数

IP アドレス

Address オブジェクト

文字列と整数への変換

演算子

比較演算子

算術演算

IP ネットワーク定義

プリフィックス, ネットマスク、ホストマスク

Network オブジェクト

演算子

論理演算子

イテレーション

アドレスのコンテナとしてのネットワーク

インターフェイスオブジェクト

演算子

論理演算子

その他のモジュールレベル関数

Custom Exceptions

マルチメディアサービス

wave --- Read and write WAV files

Wave_read オブジェクト

Wave_write オブジェクト

colorsys --- Conversions between color systems

国際化

gettext --- Multilingual internationalization services

GNU gettext API

クラス形式の API

NullTranslations クラス

GNUTranslations クラス

Solaris メッセージカタログ機構のサポート

Catalog コンストラクタ

プログラムやモジュールを国際化する

モジュールを地域化する

アプリケーションを地域化する

動作中 (on the fly) に言語を切り替える

翻訳処理の遅延解決

謝辞

locale --- Internationalization services

ロケールの背景、詳細、ヒント、助言および補足説明

Python 拡張の作者と、Python を埋め込むようなプログラムに関して

メッセージカタログへのアクセス

プログラムのフレームワーク

turtle --- タートルグラフィックス

はじめに

チュートリアル

Starting a turtle environment

Basic drawing

Pen の制御

The turtle's position

Making algorithmic patterns

How to...

Get started as quickly as possible

Use the turtle module namespace

Use turtle graphics in a script

Use object-oriented turtle graphics

Turtle graphics reference

Turtle のメソッド

TurtleScreen/Screen のメソッド

RawTurtle/Turtle のメソッドと対応する関数

Turtle の動き

Turtle の状態を知る

設定と計測

Pen の制御

描画状態

色の制御

塗りつぶし

さらなる描画の制御

タートルの状態

可視性

見た目

イベントを利用する

特別な Turtle のメソッド

Compound shapes

TurtleScreen/Screen のメソッドと対応する関数

ウィンドウの制御

アニメーションの制御

スクリーンイベントを利用する

入力メソッド

設定と特殊なメソッド

Screen 独自のメソッド、TurtleScreen から継承したもの以外

Public classes

説明

ヘルプと設定

ヘルプの使い方

ドキュメント文字列の翻訳

Screen および Turtle の設定方法

turtledemo --- デモスクリプト

python 2.6からの変更点

python 3.0からの変更点

cmd --- Support for line-oriented command interpreters

Cmdオブジェクト

Cmd の例

shlex --- Simple lexical analysis

shlex オブジェクト

解析規則

Improved Compatibility with Shells

Tk を用いたグラフィカルユーザインターフェイス

tkinter --- Python interface to Tcl/Tk

Architecture

Tkinter モジュール

Tkinter お助け手帳

A Hello World Program

Important Tk Concepts

Understanding How Tkinter Wraps Tcl/Tk

How do I...? What option does...?

Navigating the Tcl/Tk Reference Manual

Threading model

簡単なリファレンス

オプションの設定

Packer

Packer のオプション

ウィジェット変数を関連付ける

ウィンドウマネージャ

Tk オプションデータ型

バインドとイベント

index パラメータ

画像

ファイルハンドラ

tkinter.colorchooser --- Color choosing dialog

tkinter.font --- Tkinter font wrapper

Tkinter ダイアログ

tkinter.simpledialog --- 標準 Tkinter 入力ダイアログ

tkinter.filedialog --- ファイル選択ダイアログ

ネイティブの読み込み/保存ダイアログ

tkinter.commondialog --- Dialog window templates

tkinter.messagebox --- Tkinter message prompts

tkinter.scrolledtext --- Scrolled Text Widget

tkinter.dnd --- Drag and drop support

tkinter.ttk --- Tk themed widgets

Ttk を使う

Ttk ウィジェット

ウィジェット

標準オプション

スクロール可能ウィジェットのオプション

ラベルオプション

互換性オプション

ウィジェットの状態

ttk.Widget

コンボボックス

オプション

仮想イベント

ttk.Combobox

Spinbox

オプション

仮想イベント

ttk.Spinbox

ノートブック

オプション

タブオプション

タブ識別子

仮想イベント

ttk.Notebook

プログレスバー

オプション

ttk.Progressbar

セパレータ

オプション

サイズグリップ

プラットフォーム固有のメモ

バグ

ツリービュー

オプション

要素オプション

タグオプション

カラム識別子

仮想イベント

ttk.Treeview

Ttk スタイル

レイアウト

tkinter.tix --- Tkの拡張ウィジェット

Tixを使う

Tixウィジェット

基本ウィジェット

ファイルセレクタ

階層的リストボックス

表的リストボックス

管理ウィジェット

画像タイプ

その他のウィジェット

ジオメトリマネジャを作る

Tixコマンド

IDLE

メニュー

File メニュー (Shell ウィンドウ、Editor ウィンドウ)

Edit メニュー (Shell ウィンドウ、Editor ウィンドウ)

Format メニュー (Shell ウィンドウ、Editor ウィンドウ)

Run メニュー (Editor ウィンドウのみ)

Shell メニュー (Shell ウィンドウのみ)

Debug メニュー (Shell ウィンドウのみ)

Options メニュー (Shell ウィンドウ、Editor ウィンドウ)

Window メニュー (Shell ウィンドウ、Editor ウィンドウ)

Help メニュー (Shell ウィンドウ、Editor ウィンドウ)

Context menus

Editing and Navigation

Editor windows

Key bindings

自動的な字下げ

検索と置換

補完 (Completions)

呼び出しヒント (Calltips)

Code Context

Shell window

テキストの色

Startup and Code Execution

コマンドラインの使い方

Startup failure

Running user code

User output in Shell

Developing tkinter applications

サブプロセスを起こさずに起動する

Help and Preferences

Help sources

Setting preferences [お好み設定]

IDLE on macOS

Extensions [拡張]

idlelib

開発ツール

typing --- 型ヒントのサポート

Specification for the Python Type System

型エイリアス

NewType

呼び出し可能オブジェクトのアノテーション

ジェネリクス

タプルのアノテーション

クラスオブジェクトの型

ユーザー定義のジェネリック型

Any 型

名前的部分型 vs 構造的部分型

モジュールの内容

特殊型付けプリミティブ

特殊型

特殊形式

Building generic types and type aliases

Other special directives

プロトコル

ABCs for working with IO

Functions and decorators

Introspection helpers

定数

非推奨のエイリアス

Aliases to built-in types

Aliases to types in collections

Aliases to other concrete types

Aliases to container ABCs in collections.abc

Aliases to asynchronous ABCs in collections.abc

Aliases to other ABCs in collections.abc

Aliases to contextlib ABCs

メジャーな機能の非推奨時系列

pydoc --- Documentation generator and online help system

Python 開発モード

Effects of the Python Development Mode

ResourceWarning Example

Bad file descriptor error example

doctest --- Test interactive Python examples

簡単な利用法: docstring 中の実行例をチェックする

簡単な利用法: テキストファイル中の実行例をチェックする

doctest のからくり

どの docstring が検証されるのか?

docstring 内の実行例をどのように認識するのか?

実行コンテキストとは何か?

例外はどう扱えばよいか?

オプションフラグ

ディレクティブ (Directives)

警告

基本 API

単体テスト API

拡張 API

DocTest オブジェクト

Example オブジェクト

DocTestFinder オブジェクト

DocTestParser オブジェクト

DocTestRunner オブジェクト

OutputChecker オブジェクト

デバッグ

アドバイス

unittest --- Unit testing framework

基本的な例

コマンドラインインターフェイス

コマンドラインオプション

テストディスカバリ

テストコードの構成

既存テストコードの再利用

テストのスキップと予期された失敗

サブテストを利用して繰り返しテストの区別を付ける

クラスと関数

テストクラス

テストのグループ化

テストのロードと起動

load_tests プロトコル

クラスとモジュールのフィクスチャ

setUpClass と tearDownClass

setUpModule と tearDownModule

シグナルハンドリング

unittest.mock --- mock object library

クイックガイド

Mock クラス

呼び出し

属性の削除

Mock の名前と name 属性

属性として設定されるモック

patcher

patch

patch.object

patch.dict

patch.multiple

patch のメソッド: start と stop

ビルトインをパッチする

TEST_PREFIX

patch デコレータをネストする

どこにパッチするか

デスクリプタやプロキシオブジェクトにパッチする

MagicMock と magic method のサポート

Magic Method をモックする

Magic Mock

ヘルパー

sentinel

DEFAULT

call

create_autospec

ANY

FILTER_DIR

mock_open

autospec を使う

Sealing mocks

Order of precedence of side_effect, return_value and wraps

unittest.mock --- getting started

Mock を使う

Mock のパッチ用メソッド

オブジェクトのメソッド呼び出しに対するモック

クラスをモックする

モックに名前をつける

全ての呼び出しのトラッキング

戻り値や属性を設定する

モックから例外を発生させる

side_effect の関数と iterable

非同期イテレータをモックする

非同期コンテキストマネージャをモックする

既存のオブジェクトから Mock を作る

Using side_effect to return per file content

patch デコレータ

さらなる例

chained call をモックする

部分的なモック

ジェネレータメソッドをモックする

同じパッチを全てのメソッドに適用する

Unboundメソッドをモックする

モックで複数回の呼び出しをチェックする

ミュータブルな引数に対処する

patch をネストする

MagicMock で辞書をモックする

Mock のサブクラスと属性

patch.dict で import をモックする

Tracking order of calls and less verbose call assertions

More complex argument matching

2to3 --- Python 2 から 3 への自動コード変換

2to3 の使用

変換プログラム

lib2to3 --- 2to3's library

test --- Regression tests package for Python

test パッケージのためのユニットテストを書く

コマンドラインインターフェースを利用してテストを実行する

test.support --- テストのためのユーティリティ関数

test.support.socket_helper --- Utilities for socket tests

test.support.script_helper --- Utilities for the Python execution tests

test.support.bytecode_helper --- Support tools for testing correct bytecode generation

test.support.threading_helper --- Utilities for threading tests

test.support.os_helper --- Utilities for os tests

test.support.import_helper --- Utilities for import tests

test.support.warnings_helper --- Utilities for warnings tests

デバッグとプロファイル

Audit events table

bdb --- Debugger framework

faulthandler --- Dump the Python traceback

tracebackのダンプ

フォールトハンドラの状態

タイムアウト後にtracebackをダンプする

ユーザシグナルに対してtracebackをダンプする

ファイル記述子の問題

使用例

pdb --- Python デバッガ

デバッガコマンド

Python プロファイラ

プロファイラとは

かんたんユーザマニュアル

リファレンスマニュアル -- profile と cProfile

Stats クラス

決定論的プロファイリングとは

制限事項

キャリブレーション (補正)

カスタムな時刻取得用関数を使う

timeit --- Measure execution time of small code snippets

基本的な例

Python インターフェイス

コマンドラインインターフェイス

使用例

trace --- Trace or track Python statement execution

コマンドラインからの使用

主要なオプション

修飾的オプション

フィルターオプション

プログラミングインターフェース

tracemalloc --- Trace memory allocations

使用例

上位10を表示する

差を計算する

メモリブロックのトレースバックを取得する

top を整形化する

Record the current and peak size of all traced memory blocks

API

関数

DomainFilter

Filter

Frame

Snapshot

Statistic

StatisticDiff

Trace

Traceback

ソフトウェア・パッケージと配布

ensurepip --- Bootstrapping the pip installer

コマンドラインインターフェイス

モジュール API

venv --- Creation of virtual environments

仮想環境の作成

仮想環境のしくみ

API

EnvBuilder を拡張する例

zipapp --- Manage executable Python zip archives

基本的な例

コマンドラインインターフェイス

Python API

使用例

インタープリタの指定

Creating Standalone Applications with zipapp

Caveats

The Python Zip Application Archive Format

Python ランタイムサービス

sys --- System-specific parameters and functions

sys.monitoring --- Execution event monitoring

Tool identifiers

Registering and using tools

Events

Local events

Ancillary events

Other events

The STOP_ITERATION event

Turning events on and off

Setting events globally

Per code object events

Disabling events

Registering callback functions

Callback function arguments

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

構成変数

インストールパス

User scheme

posix_user

nt_user

osx_framework_user

Home scheme

posix_home

Prefix scheme

posix_prefix

nt

Installation path functions

その他の関数

sysconfig をスクリプトとして使う

builtins --- Built-in objects

__main__ --- Top-level code environment

__name__ == '__main__'

「トップレベルのスクリプト環境」とは

通常の使われ方

Packaging Considerations

__main__.py in Python Packages

通常の使われ方

import __main__

warnings --- Warning control

警告カテゴリ

警告フィルタ

Describing Warning Filters

デフォルトの警告フィルタ

Overriding the default filter

一時的に警告を抑制する

警告のテスト

Updating Code For New Versions of Dependencies

利用可能な関数

利用可能なコンテキストマネージャー

dataclasses --- Data Classes

モジュールの内容

初期化後の処理

クラス変数

初期化限定変数

凍結されたインスタンス

継承

Re-ordering of keyword-only parameters in __init__()

デフォルトファクトリ関数

可変なデフォルト値

Descriptor-typed fields

contextlib --- with 文コンテキスト用ユーティリティ

ユーティリティ

例とレシピ

可変数個のコンテキストマネージャーをサポートする

__enter__ メソッドからの例外をキャッチする

__enter__ 実装内のクリーンアップ

try-finally + flag 変数パターンを置き換える

コンテキストマネージャーを関数デコレーターとして使う

単回使用、再利用可能、およびリエントラントなコンテキストマネージャ

リエントラントなコンテキストマネージャ

再利用可能なコンテキストマネージャ

abc --- Abstract Base Classes

atexit --- Exit handlers

atexit の例

traceback --- Print or retrieve a stack traceback

TracebackException オブジェクト

StackSummary オブジェクト

FrameSummary オブジェクト

トレースバックの例

__future__ --- Future statement definitions

モジュールコンテンツ

gc --- Garbage Collector interface

inspect --- Inspect live objects

型とメンバー

ソースコードの情報取得

Signature オブジェクトで呼び出し可能オブジェクトを内省する

クラスと関数

インタープリタスタック

属性の静的なフェッチ

Current State of Generators, Coroutines, and Asynchronous Generators

Code Objects Bit Flags

Buffer flags

コマンドラインインターフェイス

site --- Site-specific configuration hook

sitecustomize

usercustomize

readline の設定

モジュールの内容

コマンドラインインターフェイス

カスタム Python インタプリタ

code --- Interpreter base classes

対話的なインタプリタオブジェクト

対話的なコンソールオブジェクト

codeop --- Compile Python code

モジュールのインポート

zipimport --- Import modules from Zip archives

zipimporter オブジェクト

使用例

pkgutil --- Package extension utility

modulefinder --- Find modules used by a script

ModuleFinder の使用例

runpy --- Locating and executing Python modules

importlib --- import の実装

はじめに

関数

importlib.abc -- インポートに関連する抽象基底クラス

importlib.machinery -- インポータおよびパスフック

importlib.util -- インポータのためのユーティリティコード

使用例

プログラムからのインポート

モジュールがインポートできるか確認する

ソースファイルから直接インポートする

Implementing lazy imports

インポーターのセットアップ

Approximating importlib.import_module()

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

Deprecated functions

importlib.resources.abc -- Abstract base classes for resources

importlib.metadata -- Accessing package metadata

概要

機能 API

エントリポイント

配布物メタデータ

配布物バージョン

配布物ファイル

配布物の要件

Mapping import to distribution packages

Distributions

Distribution Discovery

検索アルゴリズムの拡張

The initialization of the sys.path module search path

仮想環境 (Virtual environments)

_pth files

Embedded Python

Python言語サービス

ast --- Abstract Syntax Trees

抽象文法 (Abstract Grammar)

Node クラス

Root nodes

リテラル

変数

式 (expression)

配列要素の参照 (Subscripting)

内包表記 (Comprehension)

文 (Statements)

インポート

制御フロー

Pattern matching

Type parameters

関数およびクラス定義

async と await

ast ヘルパー

コンパイラフラグ

コマンドラインからの使用

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

記号表の生成

記号表の検査

token --- Constants used with Python parse trees

keyword --- Testing for Python keywords

tokenize --- Tokenizer for Python source

入力のトークナイズ

コマンドラインからの使用

使用例

tabnanny --- Detection of ambiguous indentation

pyclbr --- Python module browser support

Function オブジェクト

クラスオブジェクト

py_compile --- Compile Python source files

コマンドラインインターフェイス

compileall --- Byte-compile Python libraries

コマンドラインでの使用

パブリックな関数

dis --- Disassembler for Python bytecode

コマンドライン・インターフェース

バイトコード解析

解析関数

Python バイトコード命令

命令コードコレクション

pickletools --- Tools for pickle developers

コマンドラインの使い方

コマンドラインオプション

プログラミングインターフェース

MS Windows 固有のサービス

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

ファイル操作関連

コンソール I/O 関連

その多の関数

winreg --- Windows registry access

関数

定数

HKEY_* 定数

アクセス権限

64-bit 特有のアクセス権

値の型

レジストリハンドルオブジェクト

winsound --- Sound-playing interface for Windows

Unix 固有のサービス

posix --- The most common POSIX system calls

ラージファイルのサポート

注目すべきモジュールの内容

pwd --- The password database

grp --- The group database

termios --- POSIX style tty control

使用例

tty --- Terminal control functions

pty --- Pseudo-terminal utilities

使用例

fcntl --- The fcntl and ioctl system calls

resource --- Resource usage information

リソースの制限

リソースの使用状態

syslog --- Unix syslog library routines

使用例

シンプルな例

Modules command-line interface (CLI)

取って代わられたモジュール群

aifc --- AIFFおよびAIFCファイルの読み書き

audioop --- 生の音声データを操作する

cgi --- CGI (ゲートウェイインターフェース規格) のサポート

はじめに

cgi モジュールを使う

高水準インターフェース

関数

セキュリティへの配慮

CGI スクリプトを Unix システムにインストールする

CGI スクリプトをテストする

CGI スクリプトをデバッグする

よくある問題と解決法

cgitb --- CGI スクリプトのトレースバック管理機構

chunk --- IFFチャンクデータの読み込み

crypt --- Unix パスワードをチェックするための関数

ハッシュ化方式

モジュール属性

モジュール関数

使用例

imghdr --- 画像の形式を決定する

mailcap --- mailcap ファイルの操作

msilib --- Microsoft インストーラーファイルの読み書き

データベースオブジェクト

ビューオブジェクト

サマリー情報オブジェクト

レコードオブジェクト

エラー

CAB オブジェクト

ディレクトリオブジェクト

フィーチャー

GUI クラス

事前に計算されたテーブル

nis --- Sun の NIS (Yellow Pages) へのインターフェース

nntplib --- NNTP プロトコルクライアント

NNTP オブジェクト

属性

メソッド

ユーティリティー関数

optparse --- Parser for command line options

背景

用語集

オプションとは何か

位置引数とは何か

チュートリアル

オプション・アクションを理解する

store アクション

ブール値 (フラグ) オプションの処理

その他のアクション

デフォルト値

ヘルプの生成

オプションをグループ化する

バージョン番号の出力

optparse のエラー処理法

全てをつなぎ合わせる

リファレンスガイド

parserを作る

パーザへのオプション追加

オプションの定義

オプション属性

標準的なオプション・アクション

標準のオプション型

引数を解析する

オプション解析器への問い合わせと操作

オプション間の衝突

クリーンアップ

その他のメソッド

オプション処理コールバック

callbackオプションの定義

コールバック関数はどのように呼び出されるか

コールバック中で例外を送出する

コールバックの例 1: ありふれたコールバック

コールバックの例 2: オプションの順番をチェックする

コールバックの例 3: オプションの順番をチェックする (汎用的)

コールバックの例 4: 任意の条件をチェックする

コールバックの例5: 固定引数

コールバックの例6: 可変個の引数

optparse の拡張

新しい型の追加

新しいアクションの追加

例外

ossaudiodev --- OSS互換オーディオデバイスへのアクセス

オーディオデバイスオブジェクト

ミキサデバイスオブジェクト

pipes --- シェルパイプラインへのインターフェース

テンプレートオブジェクト

sndhdr --- サウンドファイルの識別

spwd --- シャドウパスワードデータベース

sunau --- Sun AUファイルの読み書き

AU_read オブジェクト

AU_write オブジェクト

telnetlib --- Telnet クライアント

Telnet オブジェクト

Telnet Example

uu --- uuencode形式のエンコードとデコード

xdrlib --- XDR データのエンコードおよびデコード

Packer オブジェクト

Unpacker オブジェクト

例外

セキュリティで考慮すべき点

Python インタプリタの拡張と埋め込み

おすすめのサードパーティツール

サードパーティツールなしで拡張を作る

1. C や C++ による Python の拡張

1.1. 簡単な例

1.2. 幕間小話: エラーと例外

1.3. 例に戻る

1.4. モジュールのメソッドテーブルと初期化関数

1.5. コンパイルとリンク

1.6. C から Python 関数を呼び出す

1.7. 拡張モジュール関数でのパラメタ展開

1.8. 拡張モジュール関数のキーワードパラメタ

1.9. 任意の値を構築する

1.10. 参照カウント法

1.10.1. Python における参照カウント法

1.10.2. 所有権にまつわる規則

1.10.3. 薄氷

1.10.4. NULL ポインタ

1.11. C++での拡張モジュール作成

1.12. 拡張モジュールに C API を提供する

2. 拡張の型の定義: チュートリアル

2.1. 基本的なこと

2.2. 基本のサンプルにデータとメソッドを追加する

2.3. データ属性をこまかく制御する

2.4. 循環ガベージコレクションをサポートする

2.5. 他の型のサブクラスを作る

3. Defining Extension Types: Assorted Topics

3.1. ファイナライズとメモリ解放

3.2. オブジェクト表現

3.3. 属性を管理する

3.3.1. 総称的な属性を管理する

3.3.2. 特定の型に特化した属性の管理

3.4. オブジェクトの比較

3.5. 抽象的なプロトコルのサポート

3.6. 弱参照(Weak Reference)のサポート

3.7. その他いろいろ

4. C および C++ 拡張のビルド

4.1. Building C and C++ Extensions with setuptools

5. Windows 上での C および C++ 拡張モジュールのビルド

5.1. 型どおりのアプローチ

5.2. Unix と Windows の相違点

5.3. DLL 使用の実際

大規模なアプリケーションへの Python ランタイムの埋め込み

1. 他のアプリケーションへの Python の埋め込み

1.1. 高水準の埋め込み

1.2. 超高水準の埋め込みから踏み出す: 概要

1.3. 純粋な埋め込み

1.4. 埋め込まれた Python の拡張

1.5. C++による Python の埋め込み

1.6. Unix 系システムにおけるコンパイルとリンク

Python/C API リファレンスマニュアル

はじめに

コーディング基準

インクルードファイル

便利なマクロ

オブジェクト、型および参照カウント

参照カウント法

参照カウントの詳細

型

例外

Python の埋め込み

デバッグ版ビルド (Debugging Builds)

C API の安定性

Unstable C API

安定 ABI (Stable Appliction Binary Interface)

Limited C API

Stable ABI

APIスコープとパフォーマンスの制限

制限付きAPIの注意点

プラットフォームで考慮すべき点

限定版APIの内容

超高水準レイヤ

参照カウント

例外処理

出力とクリア

例外の送出

警告

エラーインジケータの問い合わせ

シグナルハンドリング

例外クラス

例外オブジェクト

Unicode 例外オブジェクト

再帰の管理

標準例外

標準警告カテゴリ

ユーティリティ

オペレーティングシステム関連のユーティリティ

システム関数

プロセス制御

モジュールのインポート

データ整列化 (data marshalling) のサポート

引数の解釈と値の構築

引数を解析する

文字列とバッファ

数

その他のオブジェクト

API 関数

値の構築

文字列の変換と書式化

PyHash API

リフレクション

codec レジストリとサポート関数

コーデック検索API

Unicode エラーハンドラ用レジストリ API

Support for Perf Maps

抽象オブジェクトレイヤ (Abstract Objects Layer)

オブジェクトプロトコル (object protocol)

Call プロトコル

The tp_call Protocol

The Vectorcall Protocol

再帰の管理

Vectorcall Support API

Object Calling API

Call Support API

数値型プロトコル (number protocol)

シーケンス型プロトコル (sequence protocol)

マップ型プロトコル (mapping protocol)

イテレータプロトコル (iterator protocol)

バッファプロトコル (buffer Protocol)

buffer 構造体

バッファリクエストのタイプ

リクエストに依存しないフィールド

readonly, format

shape, strides, suboffsets

隣接性のリクエスト

複合リクエスト

複雑な配列

NumPy スタイル: shape, strides

PIL スタイル: shape, strides, suboffsets

バッファ関連の関数

古いバッファプロトコル

具象オブジェクト (concrete object) レイヤ

基本オブジェクト (fundamental object)

型オブジェクト

Creating Heap-Allocated Types

None オブジェクト

数値型オブジェクト (numeric object)

整数型オブジェクト (integer object)

Boolean オブジェクト

浮動小数点型オブジェクト (floating point object)

Pack and Unpack functions

Pack functions

Unpack functions

複素数オブジェクト

C 構造体としての複素数

Python オブジェクトとしての複素数型

シーケンスオブジェクト (sequence object)

バイトオブジェクト

bytearray オブジェクト

型チェックマクロ

ダイレクト API 関数

マクロ

Unicode オブジェクトと codec

Unicode オブジェクト

Unicode 型

Unicode 文字プロパティ

Unicode 文字列の生成とアクセス

ロケールエンコーディング

ファイルシステムエンコーディング

wchar_t サポート

組み込み codec (built-in codec)

汎用 codec

UTF-8 Codecs

UTF-32 Codecs

UTF-16 Codecs

UTF-7 Codecs

Unicode-Escape Codecs

Raw-Unicode-Escape Codecs

Latin-1 Codecs

ASCII Codecs

Character Map Codecs

Windows 用の MBCS codec

メソッドとスロット

メソッドおよびスロット関数 (slot function)

タプルオブジェクト (tuple object)

Struct Sequence オブジェクト

リストオブジェクト

Container オブジェクト

辞書オブジェクト (dictionary object)

Set オブジェクト

Function オブジェクト

Function オブジェクト

インスタンスメソッドオブジェクト(Instance Method Objects)

メソッドオブジェクト

セルオブジェクト (cell object)

コードオブジェクト

Extra information

その他のオブジェクト

ファイルオブジェクト

モジュールオブジェクト (module object)

Cモジュールの初期化

一段階初期化

多段階初期化

低水準モジュール作成関数

サポート関数

モジュール検索

イテレータオブジェクト (iterator object)

デスクリプタオブジェクト (descriptor object)

スライスオブジェクト (slice object)

Ellipsis オブジェクト

memoryview オブジェクト

弱参照オブジェクト

カプセル

フレーム (frame) オブジェクト

Internal Frames

ジェネレータオブジェクト

コルーチンオブジェクト

コンテキスト変数オブジェクト

DateTime オブジェクト

型ヒントのためのオブジェクト

初期化 (initialization)、終了処理 (finalization)、スレッド

Python 初期化以前

グローバルな設定変数

インタープリタの初期化と終了処理

プロセスワイドのパラメータ

スレッド状態 (thread state) とグローバルインタプリタロック (global interpreter lock)

拡張コード内で GIL を解放する

Python 以外で作られたスレッド

Cautions about fork()

高レベルAPI

低レベルAPI

サブインタプリタサポート

A Per-Interpreter GIL

バグと注意事項

非同期通知

プロファイルとトレース (profiling and tracing)

高度なデバッガサポート (advanced debugger support)

スレッドローカルストレージのサポート

スレッド固有ストレージ (Thread Specific Storage, TSS) API

動的メモリ確保

メソッド

スレッドローカルストレージ (TLS) API

Python 初期化設定

使用例

PyWideStringList

PyStatus

PyPreConfig

Preinitialize Python with PyPreConfig

PyConfig

Initialization with PyConfig

Isolated Configuration

Python Configuration

Python Path Configuration

Py_RunMain()

Py_GetArgcArgv()

Multi-Phase Initialization Private Provisional API

メモリ管理

概要

Allocator Domains

生メモリインターフェース

メモリインターフェース

オブジェクトアロケータ

Default Memory Allocators

メモリアロケータをカスタマイズする

Debug hooks on the Python memory allocators

pymalloc アロケータ

pymalloc アリーナアロケータのカスタマイズ

tracemalloc C API

使用例

オブジェクト実装サポート (object implementation support)

オブジェクトをヒープ上にメモリ確保する

共通のオブジェクト構造体 (common object structure)

Base object types and macros

Implementing functions and methods

Accessing attributes of extension types

Member flags

Member types

Defining Getters and Setters

型オブジェクト

クイックリファレンス

tp スロット

sub-slots

スロットの定義型 (typedef)

PyTypeObject 定義

PyObject スロット

PyVarObject スロット

PyTypeObject スロット

Static Types

Heap Types

数値オブジェクト構造体

マップオブジェクト構造体

シーケンスオブジェクト構造体

バッファオブジェクト構造体 (buffer object structure)

async オブジェクト構造体

Slot Type typedefs

使用例

循環参照ガベージコレクションをサポートする

Controlling the Garbage Collector State

Querying Garbage Collector State

API と ABI のバージョニング

Python モジュールのインストール

重要用語集

基本的な使い方

どうすればいいの...？

... pip を 3.4 より前のバージョンの Python でインストールするには？

... パッケージを現在のユーザ用のみにインストールするには？

... 科学技術計算用の Python パッケージをインストールするには？

... インストールされた複数のバージョンの Python を並行して使うには？

よくあるインストールに関する問題

Linux で、システムの Python 内にインストールする

pip がインストールされていない

バイナリの拡張のインストール

Python HOWTO

Python 3 への拡張モジュール移植

Python で Curses プログラミング

curses ってなに?

Python の curses module

curses アプリケーションの起動と終了

ウィンドウとパッド

テキストの表示

属性とカラー

ユーザ入力

より多くの情報

デスクリプタ ガイド

入門

シンプルな例: 定数を返すデスクリプタ

動的なルックアップ

管理された属性

名前のカスタマイズ

まとめ

実践的なサンプル

バリデータクラス

カスタムバリデータ

実践的なアプリケーション

技術的なチュートリアル

概要

定義と導入

デスクリプタプロトコル

デスクリプタ呼び出しの概要

インスタンスからの呼び出し

クラスからの呼び出し

superからの呼び出し

呼び出しロジックのまとめ

自動的の名前の伝達

ORMのサンプル

ピュアPythonの等価実装

プロパティ

関数とメソッド

メソッドの種類

静的メソッド

クラスメソッド

メンバーオブジェクトと __slots__

Debugging C API extensions and CPython Internals with GDB

Prerequisites

Setup with Python built from source

Setup for Python from a Linux distro

Using the Debug build and Development mode

Using the python-gdb extension

Pretty-printers

py-list

py-up and py-down

py-bt

py-print

py-locals

Use with GDB commands

列挙型 HOWTO

列挙型メンバーおよびそれらの属性へのプログラム的アクセス

列挙型メンバーと値の重複

番号付けの値が一意であることの確認

値の自動設定を使う

イテレーション

比較

列挙型で許されるメンバーと属性

Enumのサブクラス化の制限

データクラスのサポート

Pickle 化

関数 API

派生列挙型

IntEnum

StrEnum

IntFlag

Flag

その他

__new__() と __init__() のどちらを使うべきか

細かい点

__dunder__ 名のサポート

_sunder_ 名のサポート

_Private__names

Enum メンバー型

Creating members that are mixed with other data types

Enum クラスとメンバーの真偽値

メソッド付きの Enum クラス

Flag のメンバーの組み合わせ

Flag and IntFlag minutia

EnumとFlagはどう違うのか？

Enum クラス

Flag クラス

Enum メンバー (インスタンス)

Flag メンバー

Enum クックブック

値の省略

auto を使う

object を使う

解説文字列を使う

独自の __new__() を使う

OrderedEnum

DuplicateFreeEnum

Planet

TimePeriod

EnumType のサブクラスを作る

関数型プログラミング HOWTO

はじめに

形式的証明可能性

モジュラー性

デバッグやテストの簡単さ

結合性

イテレータ (iterator)

イテレータ対応のデータ型

ジェネレータ式とリスト内包表記

ジェネレータ (generator)

ジェネレータに値を渡す

組み込み関数 (built-in function)

itertools モジュール

新しいイテレータを作る

要素に対して関数を呼ぶ

要素を選択する

組合せ関数

要素をグループ分けする

functools モジュール

operator モジュール

小さな関数とラムダ式

更新履歴と謝辞

参考資料

一般論

Python 特有の話

Python 文書

Logging HOWTO

基本 logging チュートリアル

logging を使うとき

簡単な例

ファイルへの logging

変数データのロギング

表示されるメッセージのフォーマットの変更

メッセージ内での日付と時刻の表示

次のステップ

上級ロギングチュートリアル

Logging Flow

ロガー

ハンドラ

フォーマッタ

ロギングの環境設定

環境設定が与えられないとどうなるか

ライブラリのためのロギングの設定

ロギングレベル

カスタムレベル

便利なハンドラ

ログ記録中に発生する例外

任意のオブジェクトをメッセージに使用する

最適化

その他のリソース

Logging クックブック

複数のモジュールで logging を使う

複数のスレッドからのロギング

複数の handler と formatter

複数の出力先にログを出力する

ログレベルのカスタム処理

設定サーバの例

ブロックする handler を扱う

ネットワーク越しの logging イベントの送受信

作成中のロギングソケットのリスナーを実行する

コンテキスト情報をログ記録出力に付加する

LoggerAdapter を使ったコンテキスト情報の伝達

コンテキスト情報を渡すために dict 以外のオブジェクトを使う

Filter を使ったコンテキスト情報の伝達

contextvars の利用

ハンドラ内でのコンテキスト情報の付与

複数のプロセスからの単一ファイルへのログ記録

concurrent.futures.ProcessPoolExecutorの利用

Gunicorn と uWSGI を用いた Web アプリケーションのデプロイ

ファイルをローテートする

別の format スタイルを利用する

LogRecord のカスタマイズ

Subclassing QueueHandler and QueueListener- a ZeroMQ example

Subclass QueueHandler

Subclass QueueListener

Subclassing QueueHandler and QueueListener- a pynng example

Subclass QueueListener

Subclass QueueHandler

辞書ベースで構成する例

rotator と namer を使ってログローテートをカスタマイズする

より手の込んだ multiprocessing の例

SysLogHandler に送るメッセージに BOM を挿入する

構造化ログを実装する

handler を dictConfig() を使ってカスタマイズする

固有の書式化スタイルをアプリケーション全体で使う

LogRecord ファクトリを使う

カスタムなメッセージオブジェクトを使う

filter を dictConfig() を使ってカスタマイズする

例外の書式化をカスタマイズする

ロギングメッセージを喋る

ロギングメッセージをバッファリングし、条件に従って出力する

バッファリングしながらロギングメッセージを email で送信する

設定によって時刻を UTC(GMT) で書式化する

ロギングの選択にコンテキストマネージャを使う

CLIアプリケーションスターターテンプレート

Qt GUIのログ出力

RFC5424 をサポートする syslog へのロギング

ロガーを出力ストリームのように取り扱う方法

避けるべきパターン

同じログファイルを何度も開く

ロガーをクラスの属性にするか、パラメータで渡す

ライブラリ内でロガーに NullHandler 以外のハンドラーを追加する

大量のロガーを作成する

その他のリソース

正規表現 HOWTO

はじめに

単純なパターン

文字のマッチング

繰り返し

正規表現を使う

正規表現をコンパイルする

バックスラッシュ感染症

マッチの実行

モジュールレベルの関数

コンパイルフラグ

パターンの能力をさらに

さらなる特殊文字

グルーピング

取り出さないグループと名前つきグループ

先読みアサーション (Lookahead Assertions)

文字列を変更する

文字列の分割

検索と置換

よくある問題

文字列メソッドを利用する

match() 対 search()

貪欲 (greedy) 対非貪欲 (non-greedy)

re.VERBOSE の利用

フィードバック

ソケットプログラミング HOWTO

ソケット

歴史

ソケットの作成

IPC

ソケットの利用

バイナリデータ

切断

ソケットが死ぬと

ノンブロッキングソケット

Sorting Techniques

ソートの基本

Key 関数

Operator Module Functions and Partial Function Evaluation

昇順と降順

ソートの安定性と複合的なソート

デコレート - ソート - アンデコレート (DSU)

比較関数

残りのはしばし

Partial Sorts

Unicode HOWTO

Unicode 入門

定義

エンコーディング

参考資料

Python の Unicode サポート

文字列型

バイト列への変換

Python ソースコード内の Unicode リテラル

Unicode プロパティ

Comparing Strings

Unicode 正規表現

参考資料

Unicode データを読み書きする

Unicode ファイル名

Unicode 対応のプログラムを書くための Tips

ファイルエンコーディングの変換

不明なエンコーディングのファイル

参考資料

謝辞

urllib パッケージを使ってインターネット上のリソースを取得するには

はじめに

URL を取得する

データ

ヘッダ

例外を処理する

URLError

HTTPError

エラーコード

エラーをラップする

その1

その2

info と geturl

Openers と Handlers

Basic 認証

プロキシ

ソケットとレイヤー

脚注

Argparse チュートリアル

コンセプト

基礎

位置引数の入門

Optional引数の導入

短いオプション

位置引数とOptional引数の併用

もうちょっとだけ学ぶ

多義性のある引数の指定

競合するオプション

argparse の出力を翻訳するには

結び

ipaddressモジュールの紹介

アドレス/ネットワーク/インターフェースオブジェクトの作成

IPバージョンについての注意

IPホストアドレス

ネットワークを定義する

ホストインターフェース

アドレス/ネットワーク/インターフェースオブジェクト

アドレスのリストとしてのネットワーク

比較

他のモジュールでIPアドレスを使用する

インスタンスの生成に失敗した場合にさらに詳細を取得する

DTrace と SystemTap で CPython を測定する

静的マーカーの有効化

静的 DTrace プローブ

静的 SystemTap マーカー

利用可能な静的マーカー

SystemTap Tapset

使用例

Python support for the Linux perf profiler

How to enable perf profiling support

How to obtain the best results

Annotations Best Practices

Accessing The Annotations Dict Of An Object In Python 3.10 And Newer

Accessing The Annotations Dict Of An Object In Python 3.9 And Older

Manually Un-Stringizing Stringized Annotations

Best Practices For __annotations__ In Any Python Version

__annotations__ Quirks

拡張モジュールを分離する

Who should read this

背景

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

Module State Access from Functions

Heap Types

Changing Static Types to Heap Types

Defining Heap Types

Garbage-Collection Protocol

tp_traverse in Python 3.8 and lower

Delegating tp_traverse

Defining tp_dealloc

Not overriding tp_free

Avoiding PyObject_New

Module State Access from Classes

Module State Access from Regular Methods

Module State Access from Slot Methods, Getters and Setters

Lifetime of the Module State

取り掛かり中の問題

Per-Class Scope

Lossless Conversion to Heap Types

The Python 2.3 Method Resolution Order

The beginning

The C3 Method Resolution Order

Examples

Bad Method Resolution Orders

The end

Resources

Python よくある質問

一般 Python FAQ

一般情報

現実世界での Python

プログラミング FAQ

一般的な質問

コア言語

数と文字列

性能

シーケンス(タプル/リスト)

オブジェクト

モジュール

デザインと歴史 FAQ

Python はなぜ文のグループ化にインデントを使うのですか？

なぜ単純な算術演算が奇妙な結果になるのですか？

なぜ浮動小数点数の計算はこんなに不正確なんですか？

なぜ Python の文字列はイミュータブルなのですか？

なぜメソッドの定義や呼び出しにおいて 'self' を明示しなければならないのですか？

式中で代入ができないのはなぜですか？

Python にメソッドを使う機能 (list.index() 等) と関数を使う機能 (len(list) 等) があるのはなぜですか？

join() がリストやタプルのメソッドではなく文字列のメソッドなのはなぜですか？

例外はどれくらい速いのですか？

Python に switch や case 文がないのはなぜですか？

OS 特有のスレッド実装に依らずにインタプリタでスレッドをエミュレートすることはできないのですか？

なぜラムダ式は文を含むことができないのですか?

Python は C やその他の言語のように機械語にコンパイルできますか？

Python はメモリをどのように管理するのですか？

CPython はなぜ伝統的なガベージコレクションスキームを使わないのですか？

なぜ CPython の終了時にすべてのメモリが解放されるわけではないのですか？

なぜタプルとリストという別のデータ型が用意されているのですか？

CPythonでリストはどのように実装されているのですか？

CPythonで辞書はどのように実装されていますか？

なぜ辞書のキーはイミュータブルでなくてはならないのですか？

なぜ list.sort() はソートされたリストを返さないのですか？

Python ではどのようにインターフェース仕様を特定し適用するのですか？

なぜ goto が無いのですか？

なぜ raw 文字列 (r-strings) はバックスラッシュで終わってはいけないのですか？

属性の代入に "with" 文が使えないのはなぜですか？

なぜジェネレータは with 文をサポートしないのですか？

if/while/def/class 文にコロンが必要なのはなぜですか？

なぜ Python ではリストやタプルの最後にカンマがあっても良いのですか？

ライブラリと拡張 FAQ

ライブラリ一般の質問

よくある作業

スレッド

入力と出力

ネットワーク/インターネットプログラミング

データベース

数学と数

拡張と埋め込み FAQ

C で独自の関数を作ることはできますか？

C++ で独自の関数を作ることはできますか？

C を書くのは大変です。他の方法はありませんか？

C から任意の Python 文を実行するにはどうしますか？

C から任意の Python 式を評価するにはどうしますか？

Python オブジェクトから C の値を取り出すにはどうしますか？

Py_BuildValue() で任意長のタプルを作るにはどうしますか？

C からオブジェクトのメソッドを呼び出すにはどうしますか？

PyErr_Print() (その他 stdout/stderr に印字するもの) からの出力を受け取るにはどうしますか？

C から Python で書かれたモジュールにアクセスするにはどうしますか？

Python から C++ へインターフェースするにはどうしますか？

セットアップファイルでモジュールを追加しようとしたらメイクに失敗しました。なぜですか？

拡張をデバッグするにはどうしますか？

Linux システムで Python モジュールをコンパイルしたいのですが、見つからないファイルがあります。なぜですか？

"不完全 (incomplete) な入力" を "不適切 (invalid) な入力" から区別するにはどうしますか？

未定義の g++ シンボル __builtin_new や __pure_virtual を見つけるにはどうしますか？

メソッドのいくつかは C で、その他は Python で実装されたオブジェクトクラスを (継承などで) 作ることはできますか？

Windows 上の Python FAQ

Python プログラムを Windows で動かすにはどうしますか？

Python スクリプトを実行可能にするにはどうしますか？

Python の起動に時間がかかることがあるのはなぜですか？

どうすれば Python スクリプトを EXE に出来ますか?

*.pyd ファイルは DLL と同じですか？

Python を Windows アプリケーションに埋め込むにはどうしたらいいですか？

エディタが Python ソースにタブを勝手に挿入しないようにするにはどうしますか？

ブロックすることなく押鍵を検出するにはどうしますか？

missing api-ms-win-crt-runtime-l1-1-0.dll エラーを解決するにはどうしますか？

グラフィックユーザインターフェース FAQ

一般的な GUI の質問

Python の GUI ツールキットには何がありますか？

Tkinter の質問

"なぜ Python が私のコンピュータにインストールされているのですか？" FAQ

Python とは何ですか？

なぜ Python が私のマシンにインストールされているのですか？

Python を削除してもいいですか？

用語集

このドキュメントについて

Pythonドキュメント 貢献者

バグへの対処

ドキュメントの不備

Python の課題管理システムを使う

Python への貢献をはじめる

Copyright

歴史とライセンス

Python の歴史

Terms and conditions for accessing or otherwise using Python

PSF LICENSE AGREEMENT FOR PYTHON 3.12.3

BEOPEN.COM LICENSE AGREEMENT FOR PYTHON 2.0

CNRI LICENSE AGREEMENT FOR PYTHON 1.6.1

CWI LICENSE AGREEMENT FOR PYTHON 0.9.0 THROUGH 1.2

ZERO-CLAUSE BSD LICENSE FOR CODE IN THE PYTHON 3.12.3 DOCUMENTATION

Licenses and Acknowledgements for Incorporated Software

Mersenne Twister

ソケット

Asynchronous socket services

Cookie management

Execution tracing

UUencode and UUdecode functions

XML Remote Procedure Calls

test_epoll

Select kqueue

SipHash24

strtod と dtoa

OpenSSL

expat

libffi

zlib

cfuhash

libmpdec

W3C C14N test suite

Audioop

asyncio

What's New in Python

この"What's New in Python"という一連の文書はPythonのメジャーバージョンにおける最も重要な変更点を紹介します。新しくリリースされた後でも最新の状態であり続けたい人にとって必読のものです。

What's New In Python 3.12

Summary -- Release highlights

New Features

New Features Related to Type Hints

Other Language Changes

New Modules

Improved Modules

Optimizations

CPython bytecode changes

Demos and Tools

Deprecated

Removed

Porting to Python 3.12

Build Changes

C API Changes

Notable changes in 3.12.4

What's New In Python 3.11

概要 -- リリースハイライト

新しい機能

型ヒントに関連する新しい機能

その他の言語変更

その他の CPython の実装の変更

新たなモジュール

改良されたモジュール

最適化

Faster CPython

CPython バイトコードの変更

非推奨

Pending Removal in Python 3.12

削除

Porting to Python 3.11

Build Changes

C API の変更

Python 3.11.4での重要な変更点

Python 3.11.5での重要な変更点

What's New In Python 3.10

概要 -- リリースハイライト

新しい機能

型ヒントに関連する新しい機能

その他の言語変更

新たなモジュール

改良されたモジュール

最適化

非推奨

削除

Porting to Python 3.10

CPython バイトコードの変更

Build Changes

C API の変更

Notable security feature in 3.10.7

Notable security feature in 3.10.8

Notable changes in 3.10.12

What's New In Python 3.9

概要 -- リリースハイライト

コード中の非推奨警告(DeprecationWarning)をチェックして下さい

新しい機能

その他の言語変更

新たなモジュール

改良されたモジュール

最適化

非推奨

削除

Python 3.9への移植

Build Changes

C API の変更

Python 3.9.1 での重要な変更点

Python 3.9.2 での重要な変更点

Python 3.9.3 での重要な変更点

Python 3.9.5での重要な変更点

Notable security feature in 3.9.14

Notable changes in 3.9.17

What's New In Python 3.8

概要 -- リリースハイライト

新しい機能

その他の言語変更

新たなモジュール

改良されたモジュール

最適化

ビルドならびに C API の変更

非推奨

API と機能の削除

Python 3.8 への移植

Python3.8.1 での重要な変更点

Python3.8.2 での重要な変更点

Notable changes in Python 3.8.3

Python3.8.8 での重要な変更点

Notable changes in Python 3.8.9

Notable changes in Python 3.8.10

Notable changes in Python 3.8.10

Notable changes in Python 3.8.12

Notable security feature in 3.8.14

Notable changes in 3.8.17

What's New In Python 3.7

概要 -- リリースハイライト

新しい機能

その他の言語変更

新たなモジュール

改良されたモジュール

C API の変更

Build Changes

最適化

その他の CPython の実装の変更

非推奨の Python の挙動

非推奨の Python モジュール、関数、メソッド

C API の非推奨の関数ならびに型

サポート対象プラットフォームからの除外

API と機能の削除

Module Removals

Windows-only Changes

Python 3.7 への移植

Python 3.7.1 での重要な変更点

Python 3.7.2 での重要な変更点

Python 3.7.6 での重要な変更点

Python 3.7.10 での重要な変更点

Notable changes in Python 3.7.11

Notable security feature in 3.7.14

What's New In Python 3.6

概要 -- リリースハイライト

新しい機能

その他の言語変更

新たなモジュール

改良されたモジュール

最適化

ビルドならびに C API の変更

その他の改善

非推奨

削除

Python 3.6 への移植

Notable changes in Python 3.6.2

Notable changes in Python 3.6.4

Notable changes in Python 3.6.5

Notable changes in Python 3.6.7

Notable changes in Python 3.6.10

Notable changes in Python 3.6.13

Notable changes in Python 3.6.14

What's New In Python 3.5

概要 -- リリースハイライト

新しい機能

その他の言語変更

新たなモジュール

改良されたモジュール

その他のモジュールレベルの変更

最適化

ビルドならびに C API の変更

非推奨

削除

Python 3.5 への移植

Notable changes in Python 3.5.4

What's New In Python 3.4

概要 -- リリースハイライト

新しい機能

新たなモジュール

改良されたモジュール

CPython の実装の変更

非推奨

削除

Python 3.4 への移植

3.4.3 の変更

What's New In Python 3.3

概要 -- リリースハイライト

PEP 405: 仮想環境

PEP 420: 暗黙的な名前空間パッケージ

PEP 3118: 新たなメモリビューの実装とバッファプロトコルのドキュメント

PEP 393: 文字列の柔軟な表現

PEP 397: Windows の Python ランチャ

PEP 3151: OS および IO 例外階層の手直し

PEP 380: サブジェネレータへの委譲構文

PEP 409: 例外コンテキストの抑制

PEP 414: 明示的なユニコードリテラル

PEP 3155: クラスと関数の正規名

PEP 412: キー共有辞書

PEP 362: 関数シグニチャオブジェクト

PEP 421: sys.implementation の追加

インポート実装としての importlib の使用

その他の言語変更

細粒度のインポートロック

組み込みの関数と型

新たなモジュール

改良されたモジュール

最適化

ビルドならびに C API の変更

非推奨

Python 3.3 への移植

What's New In Python 3.2

PEP 384: 安定 ABI の定義

PEP 389: argparse コマンドライン解析モジュール

PEP 391: logging の辞書ベースの設定

PEP 3148: concurrent.futures モジュール

PEP 3147: PYC リポジトリーディレクトリ

PEP 3149: ABI バージョンでタグ付けされた .so ファイル

PEP 3333: Python Web Server Gateway Interface v1.0.1

その他の言語変更

新たなモジュール、改良されたモジュール、非推奨のモジュール

マルチスレッディング

最適化

Unicode 文字列型

Codecs

ドキュメント

IDLE

コードリポジトリ

ビルドならびに C API の変更

Python 3.2 への移植

What's New In Python 3.1

PEP 372: 順序付き辞書

PEP 378: 1000区切りのための書式指定子

その他の言語変更

新たなモジュール、改良されたモジュール、非推奨のモジュール

最適化

IDLE

ビルドならびに C API の変更

Python 3.1 への移植

What's New In Python 3.0

よくある悩みの種

構文の変更の概要

Python 2.6 で既にあった変更

ライブラリの変更

PEP 3101: 文字列整形の新たなアプローチ

例外に関する変更

その他の変更

ビルドならびに C API の変更

性能

Python 3.0 への移植

What's New in Python 2.7

Python 2.x の今後

Deprecation Warnings の扱いの変更

Python 3.1 の機能

PEP 372: collections に順序付き辞書を追加

PEP 378: 1000区切りのための書式指定子

PEP 389: コマンドライン解析のための argparse モジュール

PEP 391: logging の辞書ベースの設定

PEP 3106: 辞書 View

PEP 3137: memoryview オブジェクト

その他の言語変更

新しいモジュールと改良されたモジュール

ビルドならびに C API の変更

その他の変更と修正

Python 2.7 への移植

Python 2.7 メンテナンスリリースで追加された新機能

謝辞

What's New in Python 2.6

Python 3.0

開発プロセスに関する変更

PEP 343: "with" ステートメント

PEP 366: メインモジュールからの明示的相対インポート

PEP 370: ユーザごとの site-packages ディレクトリ

PEP 371: multiprocessing パッケージ

PEP 3101: 進化版文字列フォーマッティング

PEP 3105: print を関数にする

PEP 3110: 例外処理の変更

PEP 3112: バイトリテラル

PEP 3116: 新しい I/O ライブラリ

PEP 3118: 改訂版バッファプロトコル

PEP 3119: 抽象基底クラス

PEP 3127: 整数リテラルのサポートと文法

PEP 3129: クラスデコレータ

PEP 3141: 数値の型階層

その他の言語変更

新しいモジュールと改良されたモジュール

非推奨と削除

ビルドならびに C API の変更

Python 2.6 への移植

謝辞

What's New in Python 2.5

PEP 308: 条件式 (Conditional Expressions)

PEP 309: 関数の部分適用

PEP 314: Metadata for Python Software Packages v1.1

PEP 328: 絶対インポート、相対インポート

PEP 338 - モジュールをスクリプトとして実行する

PEP 341: try/except/finally の一体化

PEP 342: ジェネレータの新機能

PEP 343: "with" ステートメント

PEP 352: 例外の新スタイルクラス化

PEP 353: 添え字型に ssize_t を使う

PEP 357: '__index__' メソッド

その他の言語変更

新たなモジュール、改良されたモジュール、削除されたモジュール

ビルドならびに C API の変更

Python 2.5 への移植

謝辞

What's New in Python 2.4

PEP 218: ビルトインの集合オブジェクト

PEP 237: 長整数と整数を一体化していく

PEP 289: ジェネレータ式

PEP 292: より単純な文字列置換 (string substitution)

PEP 318: 関数とメソッドのためのデコレータ

PEP 322: 逆順のイテレーション

PEP 324: 新しい subprocess モジュール

PEP 327: Decimal データ型

PEP 328: マルチラインインポート

PEP 331: Locale に依存しない Float/String 変換

その他の言語変更

新たなモジュール、改良されたモジュール、非推奨のモジュール

ビルドならびに C API の変更

Python 2.4 への移植

謝辞

What's New in Python 2.3

PEP 218: 標準の集合データ型

PEP 255: 単純なジェネレータ

PEP 263: ソースコードのエンコーディング

PEP 273: Zip アーカイブからモジュールをインポートする

PEP 277: Windows NT での Unicode ファイル名サポート

PEP 278: Universal Newline サポート

PEP 279: enumerate()

PEP 282: ロギングパッケージ

PEP 285: Boolean 型

PEP 293: コーデックエラーを処理するコールバック

PEP 301: パッケージインデクスと、 Distutils のためのメタデータ

PEP 302: 新たなインポートフック

PEP 305: カンマ区切り形式ファイル

PEP 307: Pickle の機能拡張

拡張スライス

その他の言語変更

新たなモジュール、改良されたモジュール、非推奨のモジュール

Pymalloc: 特殊化されたオブジェクトアロケータ

ビルドならびに C API の変更

その他の変更と修正

Python 2.3 への移植

謝辞

What's New in Python 2.2

はじめに

PEP 252 と PEP 253: 型とクラスについての変更

PEP 234: イテレータ

PEP 255: 単純なジェネレータ

PEP 237: 長整数と整数を一体化していく

PEP 238: 除算演算子を変更していく

Unicode の変更

PEP 227: 入れ子状のスコープ

新しいモジュールと改良されたモジュール

インタプリタの変更と修正

その他の変更と修正

謝辞

What's New in Python 2.1

はじめに

PEP 227: 入れ子状のスコープ

PEP 236: __future__ 指示文

PEP 207: 拡張比較

PEP 230: 警告フレームワーク

PEP 229: 新しいビルドシステム

PEP 205: 弱参照

PEP 232: 関数の属性

PEP 235: 大文字小文字を区別しないプラットフォームでのモジュールの読み込み

PEP 217: 対話モード用 Display Hook

PEP 208: 新しい型強制モデル

PEP 241: Pythonソフトウェアパッケージのためのメタデータ

新しいモジュールと改良されたモジュール

その他の変更と修正

謝辞

What's New in Python 2.0

はじめに

Python 1.6 はいかがですか?

新しい開発プロセス

Unicode 文字列型

リストの内包表記

累算代入 (Augmented Assignment)

文字列メソッド

循環参照のガベージコレクション

その他の言語コアの変更

Python 2.0 への移植

拡張と埋め込みについての変更

Distutils: モジュールの簡単インストール

XML モジュール

更新されたモジュール

新しいモジュール

IDLE の改善

削除されたモジュール、非推奨となったモジュール

謝辞

The "Changelog" is an HTML version of the file built [https://pypi.org/project/blurb/] from the contents of the Misc/NEWS.d [https://github.com/python/cpython/tree/3.12/Misc/NEWS.d] directory tree, which contains all nontrivial changes to Python for the current version.

変更履歴

Python next

Python 3.12.3 final

Python 3.12.2 final

Python 3.12.1 final

Python 3.12.0 final

Python 3.12.0 release candidate 3

Python 3.12.0 release candidate 2

Python 3.12.0 release candidate 1

Python 3.12.0 beta 4

Python 3.12.0 beta 3

Python 3.12.0 beta 2

Python 3.12.0 beta 1

Python 3.12.0 alpha 7

Python 3.12.0 alpha 6

Python 3.12.0 alpha 5

Python 3.12.0 alpha 4

Python 3.12.0 alpha 3

Python 3.12.0 alpha 2

Python 3.12.0 alpha 1

Python 3.11.0 beta 1

Python 3.11.0 alpha 7

Python 3.11.0 alpha 6

Python 3.11.0 alpha 5

Python 3.11.0 alpha 4

Python 3.11.0 alpha 3

Python 3.11.0 alpha 2

Python 3.11.0 alpha 1

Python 3.10.0 beta 1

Python 3.10.0 alpha 7

Python 3.10.0 alpha 6

Python 3.10.0 alpha 5

Python 3.10.0 alpha 4

Python 3.10.0 alpha 3

Python 3.10.0 alpha 2

Python 3.10.0 alpha 1

Python 3.9.0 beta 1

Python 3.9.0 alpha 6

Python 3.9.0 alpha 5

Python 3.9.0 alpha 4

Python 3.9.0 alpha 3

Python 3.9.0 alpha 2

Python 3.9.0 alpha 1

Python 3.8.0 beta 1

Python 3.8.0 alpha 4

Python 3.8.0 alpha 3

Python 3.8.0 alpha 2

Python 3.8.0 alpha 1

Python 3.7.0 final

Python 3.7.0 release candidate 1

Python 3.7.0 beta 5

Python 3.7.0 beta 4

Python 3.7.0 beta 3

Python 3.7.0 beta 2

Python 3.7.0 beta 1

Python 3.7.0 alpha 4

Python 3.7.0 alpha 3

Python 3.7.0 alpha 2

Python 3.7.0 alpha 1

Python 3.6.6 final

Python 3.6.6 release candidate 1

Python 3.6.5 final

Python 3.6.5 release candidate 1

Python 3.6.4 final

Python 3.6.4 release candidate 1

Python 3.6.3 final

Python 3.6.3 release candidate 1

Python 3.6.2 final

Python 3.6.2 release candidate 2

Python 3.6.2 release candidate 1

Python 3.6.1 final

Python 3.6.1 release candidate 1

Python 3.6.0 final

Python 3.6.0 release candidate 2

Python 3.6.0 release candidate 1

Python 3.6.0 beta 4

Python 3.6.0 beta 3

Python 3.6.0 beta 2

Python 3.6.0 beta 1

Python 3.6.0 alpha 4

Python 3.6.0 alpha 3

Python 3.6.0 alpha 2

Python 3.6.0 alpha 1

Python 3.5.5 final

Python 3.5.5 release candidate 1

Python 3.5.4 final

Python 3.5.4 release candidate 1

Python 3.5.3 final

Python 3.5.3 release candidate 1

Python 3.5.2 final

Python 3.5.2 release candidate 1

Python 3.5.1 final

Python 3.5.1 release candidate 1

Python 3.5.0 final

Python 3.5.0 release candidate 4

Python 3.5.0 release candidate 3

Python 3.5.0 release candidate 2

Python 3.5.0 release candidate 1

Python 3.5.0 beta 4

Python 3.5.0 beta 3

Python 3.5.0 beta 2

Python 3.5.0 beta 1

Python 3.5.0 alpha 4

Python 3.5.0 alpha 3

Python 3.5.0 alpha 2

Python 3.5.0 alpha 1

What's New In Python 3.12

Editor:

Adam Turner

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

参考

PEP 693 [https://peps.python.org/pep-0693/] -- Python 3.12 Release Schedule

Summary -- Release highlights

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

The language changes focus on usability, as f-strings have had many limitations removed and 'Did you mean ...' suggestions continue to improve. The new type parameter syntax and type statement improve ergonomics for using generic types and type aliases with static type checkers.

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

New syntax features:

PEP 695, type parameter syntax and the type statement

New grammar features:

PEP 701, f-strings in the grammar

Interpreter improvements:

PEP 684, a unique per-interpreter GIL

PEP 669, low impact monitoring

Improved 'Did you mean ...' suggestions for NameError, ImportError, and SyntaxError exceptions

Python data model improvements:

PEP 688, using the buffer protocol from Python

Significant improvements in the standard library:

The pathlib.Path class now supports subclassing

The os module received several improvements for Windows support

A command-line interface has been added to the sqlite3 module

isinstance() checks against runtime-checkable protocols enjoy a speed up of between two and 20 times

The asyncio package has had a number of performance improvements, with some benchmarks showing a 75% speed up.

A command-line interface has been added to the uuid module

Due to the changes in PEP 701, producing tokens via the tokenize module is up to 64% faster.

Security improvements:

Replace the builtin hashlib implementations of SHA1, SHA3, SHA2-384, SHA2-512, and MD5 with formally verified code from the HACL* [https://github.com/hacl-star/hacl-star/] project. These builtin implementations remain as fallbacks that are only used when OpenSSL does not provide them.

C API improvements:

PEP 697, unstable C API tier

PEP 683, immortal objects

CPython implementation improvements:

PEP 709, comprehension inlining

CPython support for the Linux perf profiler

Implement stack overflow protection on supported platforms

New typing features:

PEP 692, using TypedDict to annotate **kwargs

PEP 698, typing.override() decorator

Important deprecations, removals or restrictions:

PEP 623 [https://peps.python.org/pep-0623/]: Remove wstr from Unicode objects in Python's C API, reducing the size of every str object by at least 8 bytes.

PEP 632 [https://peps.python.org/pep-0632/]: Remove the distutils package. See the migration guide [https://peps.python.org/pep-0632/#migration-advice] for advice replacing the APIs it provided. The third-party Setuptools [https://setuptools.pypa.io/en/latest/deprecated/distutils-legacy.html] package continues to provide distutils, if you still require it in Python 3.12 and beyond.

gh-95299 [https://github.com/python/cpython/issues/95299]: Do not pre-install setuptools in virtual environments created with venv. This means that distutils, setuptools, pkg_resources, and easy_install will no longer available by default; to access these run pip install setuptools in the activated virtual environment.

The asynchat, asyncore, and imp modules have been removed, along with several unittest.TestCase method aliases.

New Features

PEP 695: Type Parameter Syntax

Generic classes and functions under PEP 484 [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.

PEP 695 [https://peps.python.org/pep-0695/] introduces a new, more compact and explicit way to create generic classes and functions:

def max[T](args: Iterable[T]) -> T:
    ...

class list[T]:
    def __getitem__(self, index: int, /) -> T:
        ...

    def append(self, element: T) -> None:
        ...

In addition, the PEP introduces a new way to declare type aliases using the type statement, which creates an instance of TypeAliasType:

type Point = tuple[float, float]

Type aliases can also be generic:

type Point[T] = tuple[T, T]

The new syntax allows declaring TypeVarTuple and ParamSpec parameters, as well as TypeVar parameters with bounds or constraints:

type IntFunc[**P] = Callable[P, int]  # ParamSpec
type LabeledTuple[*Ts] = tuple[str, *Ts]  # TypeVarTuple
type HashableSequence[T: Hashable] = Sequence[T]  # TypeVar with bound
type IntOrStrSequence[T: (int, str)] = Sequence[T]  # TypeVar with constraints

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

Type parameters declared through a type parameter list are visible within the scope of the declaration and any nested scopes, but not in the outer scope. For example, they can be used in the type annotations for the methods of a generic class or in the class body. However, they cannot be used in the module scope after the class is defined. See 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 annotation scope. Annotation scopes behave for the most part like function scopes, but interact differently with enclosing class scopes. In Python 3.13, annotations will also be evaluated in annotation scopes.

See PEP 695 [https://peps.python.org/pep-0695/] for more details.

(PEP written by Eric Traut. Implementation by Jelle Zijlstra, Eric Traut, and others in gh-103764 [https://github.com/python/cpython/issues/103764].)

PEP 701: Syntactic formalization of f-strings

PEP 701 [https://peps.python.org/pep-0701/] lifts some restrictions on the usage of 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:

Quote reuse: in Python 3.11, reusing the same quotes as the enclosing f-string raises a 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:

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

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

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

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

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

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

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

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

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

See PEP 701 [https://peps.python.org/pep-0701/] for more details.

As a positive side-effect of how this feature has been implemented (by parsing f-strings with the PEG parser [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 SyntaxError:

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

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

>>> my_string = f"{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?

(Contributed by Pablo Galindo, Batuhan Taskaya, Lysandros Nikolaou, Cristián Maureira-Fredes and Marta Gómez in gh-102856 [https://github.com/python/cpython/issues/102856]. PEP written by Pablo Galindo, Batuhan Taskaya, Lysandros Nikolaou and Marta Gómez).

PEP 684: A Per-Interpreter GIL

PEP 684 [https://peps.python.org/pep-0684/] introduces a per-interpreter GIL, so that sub-interpreters may now be created with a unique GIL per interpreter. This allows Python programs to take full advantage of multiple CPU cores. This is currently only available through the C-API, though a Python API is anticipated for 3.13 [https://peps.python.org/pep-0554/].

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

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

For further examples how to use the C-API for sub-interpreters with a per-interpreter GIL, see Modules/_xxsubinterpretersmodule.c [https://github.com/python/cpython/tree/3.12/Modules/_xxsubinterpretersmodule.c].

(Contributed by Eric Snow in gh-104210 [https://github.com/python/cpython/issues/104210], etc.)

PEP 669: Low impact monitoring for CPython

PEP 669 [https://peps.python.org/pep-0669/] defines a new 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 sys.monitoring for details.

(Contributed by Mark Shannon in gh-103082 [https://github.com/python/cpython/issues/103082].)

PEP 688: Making the buffer protocol accessible in Python

PEP 688 [https://peps.python.org/pep-0688/] introduces a way to use the buffer protocol from Python code. Classes that implement the __buffer__() method are now usable as buffer types.

The new collections.abc.Buffer ABC provides a standard way to represent buffer objects, for example in type annotations. The new inspect.BufferFlags enum represents the flags that can be used to customize buffer creation. (Contributed by Jelle Zijlstra in gh-102500 [https://github.com/python/cpython/issues/102500].)

PEP 709: Comprehension inlining

Dictionary, list, and set comprehensions are now inlined, rather than creating a new single-use function object for each execution of the comprehension. This speeds up execution of a comprehension by up to two times. See PEP 709 [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:

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

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

Calling locals() inside a comprehension now includes variables from outside the comprehension, and no longer includes the synthetic .0 variable for the comprehension "argument".

A comprehension iterating directly over locals() (e.g. [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. for k in locals():. To avoid the error, first create a list of keys to iterate over: keys = list(locals()); [k for k in keys].

(Contributed by Carl Meyer and Vladimir Matveev in PEP 709 [https://peps.python.org/pep-0709/].)

Improved Error Messages

Modules from the standard library are now potentially suggested as part of the error messages displayed by the interpreter when a NameError is raised to the top level. (Contributed by Pablo Galindo in gh-98254 [https://github.com/python/cpython/issues/98254].)

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

Improve the error suggestion for NameError exceptions for instances. Now if a 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 self.<NAME> instead of the closest match in the method scope. (Contributed by Pablo Galindo in gh-99139 [https://github.com/python/cpython/issues/99139].)

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

Improve the SyntaxError error message when the user types import x from y instead of from y import x. (Contributed by Pablo Galindo in gh-98931 [https://github.com/python/cpython/issues/98931].)

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

ImportError exceptions raised from failed from <module> import <name> statements now include suggestions for the value of <name> based on the available names in <module>. (Contributed by Pablo Galindo in gh-91058 [https://github.com/python/cpython/issues/91058].)

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

New Features Related to Type Hints

This section covers major changes affecting type hints [https://peps.python.org/pep-0484/] and the typing module.

PEP 692: Using TypedDict for more precise **kwargs typing

Typing **kwargs in a function signature as introduced by PEP 484 [https://peps.python.org/pep-0484/] allowed for valid annotations only in cases where all of the **kwargs were of the same type.

PEP 692 [https://peps.python.org/pep-0692/] specifies a more precise way of typing **kwargs by relying on typed dictionaries:

from typing import TypedDict, Unpack

class Movie(TypedDict):
  name: str
  year: int

def foo(**kwargs: Unpack[Movie]): ...

See PEP 692 [https://peps.python.org/pep-0692/] for more details.

(Contributed by Franek Magiera in gh-103629 [https://github.com/python/cpython/issues/103629].)

PEP 698: Override Decorator for Static Typing

A new decorator typing.override() has been added to the 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"

See PEP 698 [https://peps.python.org/pep-0698/] for more details.

(Contributed by Steven Troxler in gh-101561 [https://github.com/python/cpython/issues/101561].)

Other Language Changes

The parser now raises SyntaxError when parsing source code containing null bytes. (Contributed by Pablo Galindo in gh-96670 [https://github.com/python/cpython/issues/96670].)

A backslash-character pair that is not a valid escape sequence now generates a SyntaxWarning, instead of DeprecationWarning. For example, re.compile("\d+\.\d+") now emits a SyntaxWarning ("\d" is an invalid escape sequence, use raw strings for regular expression: re.compile(r"\d+\.\d+")). In a future Python version, SyntaxError will eventually be raised, instead of SyntaxWarning. (Contributed by Victor Stinner in gh-98401 [https://github.com/python/cpython/issues/98401].)

Octal escapes with value larger than 0o377 (ex: "\477"), deprecated in Python 3.11, now produce a SyntaxWarning, instead of DeprecationWarning. In a future Python version they will be eventually a SyntaxError. (Contributed by Victor Stinner in gh-98401 [https://github.com/python/cpython/issues/98401].)

Variables used in the target part of comprehensions that are not stored to can now be used in assignment expressions (:=). For example, in [(b := 1) for a, b.prop in some_iter], the assignment to b is now allowed. Note that assigning to variables stored to in the target part of comprehensions (like a) is still disallowed, as per PEP 572 [https://peps.python.org/pep-0572/]. (Contributed by Nikita Sobolev in gh-100581 [https://github.com/python/cpython/issues/100581].)

Exceptions raised in a class or type's __set_name__ method are no longer wrapped by a RuntimeError. Context information is added to the exception as a PEP 678 [https://peps.python.org/pep-0678/] note. (Contributed by Irit Katriel in gh-77757 [https://github.com/python/cpython/issues/77757].)

When a try-except* construct handles the entire ExceptionGroup and raises one other exception, that exception is no longer wrapped in an ExceptionGroup. Also changed in version 3.11.4. (Contributed by Irit Katriel in gh-103590 [https://github.com/python/cpython/issues/103590].)

The Garbage Collector now runs only on the eval breaker mechanism of the Python bytecode evaluation loop instead of object allocations. The GC can also run when 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 [https://github.com/python/cpython/issues/97922].)

All builtin and extension callables expecting boolean parameters now accept arguments of any type instead of just bool and int. (Contributed by Serhiy Storchaka in gh-60203 [https://github.com/python/cpython/issues/60203].)

memoryview now supports the half-float type (the "e" format code). (Contributed by Donghee Na and Antoine Pitrou in gh-90751 [https://github.com/python/cpython/issues/90751].)

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 [https://github.com/python/cpython/issues/101264].)

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 [https://github.com/python/cpython/issues/100425].)

ast.parse() now raises SyntaxError instead of ValueError when parsing source code containing null bytes. (Contributed by Pablo Galindo in gh-96670 [https://github.com/python/cpython/issues/96670].)

The extraction methods in tarfile, and 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 tarfile extraction filters for details. In Python 3.14, the default will switch to 'data'. (Contributed by Petr Viktorin in PEP 706 [https://peps.python.org/pep-0706/].)

types.MappingProxyType instances are now hashable if the underlying mapping is hashable. (Contributed by Serhiy Storchaka in gh-87995 [https://github.com/python/cpython/issues/87995].)

Add support for the perf profiler through the new environment variable PYTHONPERFSUPPORT and command-line option -X perf, as well as the new sys.activate_stack_trampoline(), sys.deactivate_stack_trampoline(), and sys.is_stack_trampoline_active() functions. (Design by Pablo Galindo. Contributed by Pablo Galindo and Christian Heimes with contributions from Gregory P. Smith [Google] and Mark Shannon in gh-96123 [https://github.com/python/cpython/issues/96123].)

New Modules

None.

Improved Modules

array

The array.array class now supports subscripting, making it a generic type. (Contributed by Jelle Zijlstra in gh-98658 [https://github.com/python/cpython/issues/98658].)

asyncio

The performance of writing to sockets in asyncio has been significantly improved. asyncio now avoids unnecessary copying when writing to sockets and uses sendmsg() if the platform supports it. (Contributed by Kumar Aditya in gh-91166 [https://github.com/python/cpython/issues/91166].)

Add asyncio.eager_task_factory() and 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 [https://github.com/python/cpython/issues/102853], gh-104140 [https://github.com/python/cpython/issues/104140], and gh-104138 [https://github.com/python/cpython/issues/104138])

On Linux, asyncio uses asyncio.PidfdChildWatcher by default if os.pidfd_open() is available and functional instead of asyncio.ThreadedChildWatcher. (Contributed by Kumar Aditya in gh-98024 [https://github.com/python/cpython/issues/98024].)

The event loop now uses the best available child watcher for each platform (asyncio.PidfdChildWatcher if supported and asyncio.ThreadedChildWatcher otherwise), so manually configuring a child watcher is not recommended. (Contributed by Kumar Aditya in gh-94597 [https://github.com/python/cpython/issues/94597].)

Add loop_factory parameter to asyncio.run() to allow specifying a custom event loop factory. (Contributed by Kumar Aditya in gh-99388 [https://github.com/python/cpython/issues/99388].)

Add C implementation of asyncio.current_task() for 4x-6x speedup. (Contributed by Itamar Oren and Pranav Thulasiram Bhat in gh-100344 [https://github.com/python/cpython/issues/100344].)

asyncio.iscoroutine() now returns False for generators as asyncio does not support legacy generator-based coroutines. (Contributed by Kumar Aditya in gh-102748 [https://github.com/python/cpython/issues/102748].)

asyncio.wait() and asyncio.as_completed() now accepts generators yielding tasks. (Contributed by Kumar Aditya in gh-78530 [https://github.com/python/cpython/issues/78530].)

calendar

Add enums calendar.Month and calendar.Day defining months of the year and days of the week. (Contributed by Prince Roshan in gh-103636 [https://github.com/python/cpython/issues/103636].)

csv

Add csv.QUOTE_NOTNULL and csv.QUOTE_STRINGS flags to provide finer grained control of None and empty strings by csv.writer objects.

dis

Pseudo instruction opcodes (which are used by the compiler but do not appear in executable bytecode) are now exposed in the dis module. HAVE_ARGUMENT is still relevant to real opcodes, but it is not useful for pseudo instructions. Use the new dis.hasarg collection instead. (Contributed by Irit Katriel in gh-94216 [https://github.com/python/cpython/issues/94216].)

Add the dis.hasexc collection to signify instructions that set an exception handler. (Contributed by Irit Katriel in gh-94216 [https://github.com/python/cpython/issues/94216].)

fractions

Objects of type fractions.Fraction now support float-style formatting. (Contributed by Mark Dickinson in gh-100161 [https://github.com/python/cpython/issues/100161].)

importlib.resources

importlib.resources.as_file() now supports resource directories. (Contributed by Jason R. Coombs in gh-97930 [https://github.com/python/cpython/issues/97930].)

Rename first parameter of importlib.resources.files() to anchor. (Contributed by Jason R. Coombs in gh-100598 [https://github.com/python/cpython/issues/100598].)

inspect

Add inspect.markcoroutinefunction() to mark sync functions that return a coroutine for use with inspect.iscoroutinefunction(). (Contributed by Carlton Gibson in gh-99247 [https://github.com/python/cpython/issues/99247].)

Add inspect.getasyncgenstate() and inspect.getasyncgenlocals() for determining the current state of asynchronous generators. (Contributed by Thomas Krennwallner in gh-79940 [https://github.com/python/cpython/issues/79940].)

The performance of inspect.getattr_static() has been considerably improved. Most calls to the function should be at least 2x faster than they were in Python 3.11. (Contributed by Alex Waygood in gh-103193 [https://github.com/python/cpython/issues/103193].)

itertools

Add itertools.batched() for collecting into even-sized tuples where the last batch may be shorter than the rest. (Contributed by Raymond Hettinger in gh-98363 [https://github.com/python/cpython/issues/98363].)

math

Add math.sumprod() for computing a sum of products. (Contributed by Raymond Hettinger in gh-100485 [https://github.com/python/cpython/issues/100485].)

Extend 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 [https://github.com/python/cpython/issues/94906].)

os

Add os.PIDFD_NONBLOCK to open a file descriptor for a process with os.pidfd_open() in non-blocking mode. (Contributed by Kumar Aditya in gh-93312 [https://github.com/python/cpython/issues/93312].)

os.DirEntry now includes an os.DirEntry.is_junction() method to check if the entry is a junction. (Contributed by Charles Machalow in gh-99547 [https://github.com/python/cpython/issues/99547].)

Add os.listdrives(), os.listvolumes() and os.listmounts() functions on Windows for enumerating drives, volumes and mount points. (Contributed by Steve Dower in gh-102519 [https://github.com/python/cpython/issues/102519].)

os.stat() and os.lstat() are now more accurate on Windows. The st_birthtime field will now be filled with the creation time of the file, and 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). st_dev may be up to 64 bits and st_ino up to 128 bits depending on your file system, and 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 [https://github.com/python/cpython/issues/99726].)

As of 3.12.4, os.mkdir() and os.makedirs() on Windows now support passing a mode value of 0o700 to apply access control to the new directory. This implicitly affects tempfile.mkdtemp() and is a mitigation for CVE-2024-4030 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-4030]. Other values for mode continue to be ignored. (Contributed by Steve Dower in gh-118486 [https://github.com/python/cpython/issues/118486].)

os.path

Add os.path.isjunction() to check if a given path is a junction. (Contributed by Charles Machalow in gh-99547 [https://github.com/python/cpython/issues/99547].)

Add os.path.splitroot() to split a path into a triad (drive, root, tail). (Contributed by Barney Gale in gh-101000 [https://github.com/python/cpython/issues/101000].)

pathlib

Add support for subclassing pathlib.PurePath and pathlib.Path, plus their Posix- and Windows-specific variants. Subclasses may override the pathlib.PurePath.with_segments() method to pass information between path instances.

Add pathlib.Path.walk() for walking the directory trees and generating all file or directory names within them, similar to os.walk(). (Contributed by Stanislav Zmiev in gh-90385 [https://github.com/python/cpython/issues/90385].)

Add walk_up optional parameter to pathlib.PurePath.relative_to() to allow the insertion of .. entries in the result; this behavior is more consistent with os.path.relpath(). (Contributed by Domenico Ragusa in gh-84538 [https://github.com/python/cpython/issues/84538].)

Add pathlib.Path.is_junction() as a proxy to os.path.isjunction(). (Contributed by Charles Machalow in gh-99547 [https://github.com/python/cpython/issues/99547].)

Add case_sensitive optional parameter to pathlib.Path.glob(), pathlib.Path.rglob() and pathlib.PurePath.match() for matching the path's case sensitivity, allowing for more precise control over the matching process.

pdb

Add convenience variables to hold values temporarily for debug session and provide quick access to values like the current frame or the return value. (Contributed by Tian Gao in gh-103693 [https://github.com/python/cpython/issues/103693].)

random

Add random.binomialvariate(). (Contributed by Raymond Hettinger in gh-81620 [https://github.com/python/cpython/issues/81620].)

Add a default of lambd=1.0 to random.expovariate(). (Contributed by Raymond Hettinger in gh-100234 [https://github.com/python/cpython/issues/100234].)

shutil

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 [https://github.com/python/cpython/issues/74696].)

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 [https://github.com/python/cpython/issues/102828].)

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 [https://github.com/python/cpython/issues/103179].)

shutil.which() will call 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 [https://github.com/python/cpython/issues/103179].)

shutil.which() will return a path matching the cmd with a component from PATHEXT prior to a direct match elsewhere in the search path on Windows. (Contributed by Charles Machalow in gh-103179 [https://github.com/python/cpython/issues/103179].)

sqlite3

Add a command-line interface. (Contributed by Erlend E. Aasland in gh-77617 [https://github.com/python/cpython/issues/77617].)

Add the sqlite3.Connection.autocommit attribute to sqlite3.Connection and the autocommit parameter to sqlite3.connect() to control PEP 249 [https://peps.python.org/pep-0249/]-compliant transaction handling. (Contributed by Erlend E. Aasland in gh-83638 [https://github.com/python/cpython/issues/83638].)

Add entrypoint keyword-only parameter to sqlite3.Connection.load_extension(), for overriding the SQLite extension entry point. (Contributed by Erlend E. Aasland in gh-103015 [https://github.com/python/cpython/issues/103015].)

Add sqlite3.Connection.getconfig() and sqlite3.Connection.setconfig() to sqlite3.Connection to make configuration changes to a database connection. (Contributed by Erlend E. Aasland in gh-103489 [https://github.com/python/cpython/issues/103489].)

statistics

Extend statistics.correlation() to include as a ranked method for computing the Spearman correlation of ranked data. (Contributed by Raymond Hettinger in gh-95861 [https://github.com/python/cpython/issues/95861].)

sys

Add the sys.monitoring namespace to expose the new PEP 669 monitoring API. (Contributed by Mark Shannon in gh-103082 [https://github.com/python/cpython/issues/103082].)

Add sys.activate_stack_trampoline() and sys.deactivate_stack_trampoline() for activating and deactivating stack profiler trampolines, and 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 [https://github.com/python/cpython/issues/96123].)

Add 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: sys.last_type, sys.last_value and sys.last_traceback. (Contributed by Irit Katriel in gh-102778 [https://github.com/python/cpython/issues/102778].)

sys._current_exceptions() now returns a mapping from thread-id to an exception instance, rather than to a (typ, exc, tb) tuple. (Contributed by Irit Katriel in gh-103176 [https://github.com/python/cpython/issues/103176].)

sys.setrecursionlimit() and 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.

tempfile

The tempfile.NamedTemporaryFile function has a new optional parameter delete_on_close (Contributed by Evgeny Zorin in gh-58451 [https://github.com/python/cpython/issues/58451].)

tempfile.mkdtemp() now always returns an absolute path, even if the argument provided to the dir parameter is a relative path.

As of 3.12.4 on Windows, the default mode 0o700 used by tempfile.mkdtemp() now limits access to the new directory due to changes to os.mkdir(). This is a mitigation for CVE-2024-4030 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-4030]. (Contributed by Steve Dower in gh-118486 [https://github.com/python/cpython/issues/118486].)

threading

Add threading.settrace_all_threads() and 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 [https://github.com/python/cpython/issues/93503].)

tkinter

tkinter.Canvas.coords() now flattens its arguments. It now accepts not only coordinates as separate arguments (x1, y1, x2, y2, ...) and a sequence of coordinates ([x1, y1, x2, y2, ...]), but also coordinates grouped in pairs ((x1, y1), (x2, y2), ... and [(x1, y1), (x2, y2), ...]), like create_*() methods. (Contributed by Serhiy Storchaka in gh-94473 [https://github.com/python/cpython/issues/94473].)

tokenize

The tokenize module includes the changes introduced in PEP 701 [https://peps.python.org/pep-0701/]. (Contributed by Marta Gómez Macías and Pablo Galindo in gh-102856 [https://github.com/python/cpython/issues/102856].) See Porting to Python 3.12 for more information on the changes to the tokenize module.

types

Add types.get_original_bases() to allow for further introspection of ユーザー定義のジェネリック型 when subclassed. (Contributed by James Hilton-Balfe and Alex Waygood in gh-101827 [https://github.com/python/cpython/issues/101827].)

typing

isinstance() checks against runtime-checkable protocols now use inspect.getattr_static() rather than hasattr() to lookup whether attributes exist. This means that descriptors and __getattr__() methods are no longer unexpectedly evaluated during 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 [https://github.com/python/cpython/issues/102433].)

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

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

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

The performance profile of isinstance() checks against runtime-checkable protocols has changed significantly. Most 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, isinstance() checks against protocols with many members may be slower than in Python 3.11. (Contributed by Alex Waygood in gh-74690 [https://github.com/python/cpython/issues/74690] and gh-103193 [https://github.com/python/cpython/issues/103193].)

All typing.TypedDict and typing.NamedTuple classes now have the __orig_bases__ attribute. (Contributed by Adrian Garcia Badaracco in gh-103699 [https://github.com/python/cpython/issues/103699].)

Add frozen_default parameter to typing.dataclass_transform(). (Contributed by Erik De Bonte in gh-99957 [https://github.com/python/cpython/issues/99957].)

unicodedata

The Unicode database has been updated to version 15.0.0. (Contributed by Benjamin Peterson in gh-96734 [https://github.com/python/cpython/issues/96734]).

unittest

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

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)

(Contributed by Giampaolo Rodola in gh-48330 [https://github.com/python/cpython/issues/48330])

uuid

Add a command-line interface. (Contributed by Adam Chhina in gh-88597 [https://github.com/python/cpython/issues/88597].)

Optimizations

Remove wstr and wstr_length members from Unicode objects. It reduces object size by 8 or 16 bytes on 64bit platform. (PEP 623 [https://peps.python.org/pep-0623/]) (Contributed by Inada Naoki in gh-92536 [https://github.com/python/cpython/issues/92536].)

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 [https://github.com/python/cpython/issues/90536] and tuned by Donghee Na in gh-101525 [https://github.com/python/cpython/issues/101525])

Speed up the regular expression substitution (functions re.sub() and re.subn() and corresponding re.Pattern methods) for replacement strings containing group references by 2--3 times. (Contributed by Serhiy Storchaka in gh-91524 [https://github.com/python/cpython/issues/91524].)

Speed up asyncio.Task creation by deferring expensive string formatting. (Contributed by Itamar Oren in gh-103793 [https://github.com/python/cpython/issues/103793].)

The tokenize.tokenize() and tokenize.generate_tokens() functions are up to 64% faster as a side effect of the changes required to cover PEP 701 [https://peps.python.org/pep-0701/] in the tokenize module. (Contributed by Marta Gómez Macías and Pablo Galindo in gh-102856 [https://github.com/python/cpython/issues/102856].)

Speed up super() method calls and attribute loads via the new LOAD_SUPER_ATTR instruction. (Contributed by Carl Meyer and Vladimir Matveev in gh-103497 [https://github.com/python/cpython/issues/103497].)

CPython bytecode changes

Remove the LOAD_METHOD instruction. It has been merged into LOAD_ATTR. LOAD_ATTR will now behave like the old LOAD_METHOD instruction if the low bit of its oparg is set. (Contributed by Ken Jin in gh-93429 [https://github.com/python/cpython/issues/93429].)

Remove the JUMP_IF_FALSE_OR_POP and JUMP_IF_TRUE_OR_POP instructions. (Contributed by Irit Katriel in gh-102859 [https://github.com/python/cpython/issues/102859].)

Remove the PRECALL instruction. (Contributed by Mark Shannon in gh-92925 [https://github.com/python/cpython/issues/92925].)

Add the BINARY_SLICE and STORE_SLICE instructions. (Contributed by Mark Shannon in gh-94163 [https://github.com/python/cpython/issues/94163].)

Add the CALL_INTRINSIC_1 instructions. (Contributed by Mark Shannon in gh-99005 [https://github.com/python/cpython/issues/99005].)

Add the CALL_INTRINSIC_2 instruction. (Contributed by Irit Katriel in gh-101799 [https://github.com/python/cpython/issues/101799].)

Add the CLEANUP_THROW instruction. (Contributed by Brandt Bucher in gh-90997 [https://github.com/python/cpython/issues/90997].)

Add the END_SEND instruction. (Contributed by Mark Shannon in gh-103082 [https://github.com/python/cpython/issues/103082].)

Add the LOAD_FAST_AND_CLEAR instruction as part of the implementation of PEP 709 [https://peps.python.org/pep-0709/]. (Contributed by Carl Meyer in gh-101441 [https://github.com/python/cpython/issues/101441].)

Add the LOAD_FAST_CHECK instruction. (Contributed by Dennis Sweeney in gh-93143 [https://github.com/python/cpython/issues/93143].)

Add the LOAD_FROM_DICT_OR_DEREF, LOAD_FROM_DICT_OR_GLOBALS, and LOAD_LOCALS opcodes as part of the implementation of PEP 695 [https://peps.python.org/pep-0695/]. Remove the LOAD_CLASSDEREF opcode, which can be replaced with LOAD_LOCALS plus LOAD_FROM_DICT_OR_DEREF. (Contributed by Jelle Zijlstra in gh-103764 [https://github.com/python/cpython/issues/103764].)

Add the LOAD_SUPER_ATTR instruction. (Contributed by Carl Meyer and Vladimir Matveev in gh-103497 [https://github.com/python/cpython/issues/103497].)

Add the RETURN_CONST instruction. (Contributed by Wenyang Wang in gh-101632 [https://github.com/python/cpython/issues/101632].)

Demos and Tools

Remove the Tools/demo/ directory which contained old demo scripts. A copy can be found in the old-demos project [https://github.com/gvanrossum/old-demos]. (Contributed by Victor Stinner in gh-97681 [https://github.com/python/cpython/issues/97681].)

Remove outdated example scripts of the Tools/scripts/ directory. A copy can be found in the old-demos project [https://github.com/gvanrossum/old-demos]. (Contributed by Victor Stinner in gh-97669 [https://github.com/python/cpython/issues/97669].)

Deprecated

argparse: The type, choices, and metavar parameters of argparse.BooleanOptionalAction are deprecated and will be removed in 3.14. (Contributed by Nikita Sobolev in gh-92248 [https://github.com/python/cpython/issues/92248].)

ast: The following ast features have been deprecated in documentation since Python 3.8, now cause a DeprecationWarning to be emitted at runtime when they are accessed or used, and will be removed in Python 3.14:

ast.Num

ast.Str

ast.Bytes

ast.NameConstant

ast.Ellipsis

Use ast.Constant instead. (Contributed by Serhiy Storchaka in gh-90953 [https://github.com/python/cpython/issues/90953].)

asyncio:

The child watcher classes asyncio.MultiLoopChildWatcher, asyncio.FastChildWatcher, asyncio.AbstractChildWatcher and asyncio.SafeChildWatcher are deprecated and will be removed in Python 3.14. (Contributed by Kumar Aditya in gh-94597 [https://github.com/python/cpython/issues/94597].)

asyncio.set_child_watcher(), asyncio.get_child_watcher(), asyncio.AbstractEventLoopPolicy.set_child_watcher() and asyncio.AbstractEventLoopPolicy.get_child_watcher() are deprecated and will be removed in Python 3.14. (Contributed by Kumar Aditya in gh-94597 [https://github.com/python/cpython/issues/94597].)

The get_event_loop() method of the default event loop policy now emits a DeprecationWarning if there is no current event loop set and it decides to create one. (Contributed by Serhiy Storchaka and Guido van Rossum in gh-100160 [https://github.com/python/cpython/issues/100160].)

calendar: calendar.January and calendar.February constants are deprecated and replaced by calendar.JANUARY and calendar.FEBRUARY. (Contributed by Prince Roshan in gh-103636 [https://github.com/python/cpython/issues/103636].)

collections.abc: Deprecated collections.abc.ByteString. Prefer Sequence or collections.abc.Buffer. For use in typing, prefer a union, like bytes | bytearray, or collections.abc.Buffer. (Contributed by Shantanu Jain in gh-91896 [https://github.com/python/cpython/issues/91896].)

datetime: datetime.datetime's utcnow() and utcfromtimestamp() are deprecated and will be removed in a future version. Instead, use timezone-aware objects to represent datetimes in UTC: respectively, call now() and fromtimestamp() with the tz parameter set to datetime.UTC. (Contributed by Paul Ganssle in gh-103857 [https://github.com/python/cpython/issues/103857].)

email: Deprecate the isdst parameter in email.utils.localtime(). (Contributed by Alan Williams in gh-72346 [https://github.com/python/cpython/issues/72346].)

importlib.abc: Deprecated the following classes, scheduled for removal in Python 3.14:

importlib.abc.ResourceReader

importlib.abc.Traversable

importlib.abc.TraversableResources

Use importlib.resources.abc classes instead:

importlib.resources.abc.Traversable

importlib.resources.abc.TraversableResources

(Contributed by Jason R. Coombs and Hugo van Kemenade in gh-93963 [https://github.com/python/cpython/issues/93963].)

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 [https://github.com/python/cpython/issues/101588].)

multiprocessing: In Python 3.14, the default multiprocessing start method will change to a safer one on Linux, BSDs, and other non-macOS POSIX platforms where 'fork' is currently the default (gh-84559 [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 get_context() or set_start_method() APIs to explicitly specify when your code requires 'fork'. See contexts and start methods.

pkgutil: pkgutil.find_loader() and pkgutil.get_loader() are deprecated and will be removed in Python 3.14; use importlib.util.find_spec() instead. (Contributed by Nikita Sobolev in gh-97850 [https://github.com/python/cpython/issues/97850].)

pty: The module has two undocumented master_open() and slave_open() functions that have been deprecated since Python 2 but only gained a proper DeprecationWarning in 3.12. Remove them in 3.14. (Contributed by Soumendra Ganguly and Gregory P. Smith in gh-85984 [https://github.com/python/cpython/issues/85984].)

os:

The st_ctime fields return by os.stat() and 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 st_birthtime field. (Contributed by Steve Dower in gh-99726 [https://github.com/python/cpython/issues/99726].)

On POSIX platforms, os.fork() can now raise a 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 to raise awareness as issues encounted by code doing this are becoming more frequent. See the os.fork() documentation for more details along with this discussion on fork being incompatible with threads [https://discuss.python.org/t/33555] for why we're now surfacing this longstanding platform compatibility problem to developers.

When this warning appears due to usage of multiprocessing or concurrent.futures the fix is to use a different multiprocessing start method such as "spawn" or "forkserver".

shutil: The onerror argument of shutil.rmtree() is deprecated; use onexc instead. (Contributed by Irit Katriel in gh-102828 [https://github.com/python/cpython/issues/102828].)

sqlite3:

default adapters and converters are now deprecated. Instead, use the 適合関数と変換関数のレシピ集 and tailor them to your needs. (Contributed by Erlend E. Aasland in gh-90016 [https://github.com/python/cpython/issues/90016].)

In execute(), DeprecationWarning is now emitted when named placeholders are used together with parameters supplied as a sequence instead of as a dict. Starting from Python 3.14, using named placeholders with parameters supplied as a sequence will raise a ProgrammingError. (Contributed by Erlend E. Aasland in gh-101698 [https://github.com/python/cpython/issues/101698].)

sys: The sys.last_type, sys.last_value and sys.last_traceback fields are deprecated. Use sys.last_exc instead. (Contributed by Irit Katriel in gh-102778 [https://github.com/python/cpython/issues/102778].)

tarfile: Extracting tar archives without specifying filter is deprecated until Python 3.14, when 'data' filter will become the default. See Extraction filters for details.

typing:

typing.Hashable and typing.Sized, aliases for collections.abc.Hashable and collections.abc.Sized respectively, are deprecated. (gh-94309 [https://github.com/python/cpython/issues/94309].)

typing.ByteString, deprecated since Python 3.9, now causes a DeprecationWarning to be emitted when it is used. (Contributed by Alex Waygood in gh-91896 [https://github.com/python/cpython/issues/91896].)

xml.etree.ElementTree: The module now emits DeprecationWarning when testing the truth value of an xml.etree.ElementTree.Element. Before, the Python implementation emitted FutureWarning, and the C implementation emitted nothing. (Contributed by Jacob Walls in gh-83122 [https://github.com/python/cpython/issues/83122].)

The 3-arg signatures (type, value, traceback) of coroutine throw(), generator throw() and 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 [https://github.com/python/cpython/issues/89874].)

DeprecationWarning is now raised when __package__ on a module differs from __spec__.parent (previously it was ImportWarning). (Contributed by Brett Cannon in gh-65961 [https://github.com/python/cpython/issues/65961].)

Setting __package__ or __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 [https://github.com/python/cpython/issues/65961].)

The bitwise inversion operator (~) on bool is deprecated. It will throw an error in Python 3.14. Use not for logical negation of bools instead. In the rare case that you really need the bitwise inversion of the underlying int, convert to int explicitly: ~int(x). (Contributed by Tim Hoffmann in gh-103487 [https://github.com/python/cpython/issues/103487].)

Accessing co_lnotab on code objects was deprecated in Python 3.10 via PEP 626 [https://peps.python.org/pep-0626/], but it only got a proper DeprecationWarning in 3.12, therefore it will be removed in 3.14. (Contributed by Nikita Sobolev in gh-101866 [https://github.com/python/cpython/issues/101866].)

Pending Removal in Python 3.13

The following modules and APIs have been deprecated in earlier Python releases, and will be removed in Python 3.13.

Modules (see PEP 594 [https://peps.python.org/pep-0594/]):

aifc

audioop

cgi

cgitb

chunk

crypt

imghdr

mailcap

msilib

nis

nntplib

ossaudiodev

pipes

sndhdr

spwd

sunau

telnetlib

uu

xdrlib

Other modules:

lib2to3, and the 2to3 program (gh-84540 [https://github.com/python/cpython/issues/84540])

APIs:

configparser.LegacyInterpolation (gh-90765 [https://github.com/python/cpython/issues/90765])

locale.resetlocale() (gh-90817 [https://github.com/python/cpython/issues/90817])

turtle.RawTurtle.settiltangle() (gh-50096 [https://github.com/python/cpython/issues/50096])

unittest.findTestCases() (gh-50096 [https://github.com/python/cpython/issues/50096])

unittest.getTestCaseNames() (gh-50096 [https://github.com/python/cpython/issues/50096])

unittest.makeSuite() (gh-50096 [https://github.com/python/cpython/issues/50096])

unittest.TestProgram.usageExit() (gh-67048 [https://github.com/python/cpython/issues/67048])

webbrowser.MacOSX (gh-86421 [https://github.com/python/cpython/issues/86421])

classmethod descriptor chaining (gh-89519 [https://github.com/python/cpython/issues/89519])

importlib.resources deprecated methods:

contents()

is_resource()

open_binary()

open_text()

path()

read_binary()

read_text()

Use importlib.resources.files() instead. Refer to importlib-resources: Migrating from Legacy [https://importlib-resources.readthedocs.io/en/latest/using.html#migrating-from-legacy] (gh-106531 [https://github.com/python/cpython/issues/106531])

Pending Removal in Python 3.14

The following APIs have been deprecated and will be removed in Python 3.14.

argparse: The type, choices, and metavar parameters of argparse.BooleanOptionalAction

ast:

ast.Num

ast.Str

ast.Bytes

ast.NameConstant

ast.Ellipsis

asyncio:

asyncio.MultiLoopChildWatcher

asyncio.FastChildWatcher

asyncio.AbstractChildWatcher

asyncio.SafeChildWatcher

asyncio.set_child_watcher()

asyncio.get_child_watcher(),

asyncio.AbstractEventLoopPolicy.set_child_watcher()

asyncio.AbstractEventLoopPolicy.get_child_watcher()

collections.abc: collections.abc.ByteString.

email: the isdst parameter in email.utils.localtime().

importlib.abc:

importlib.abc.ResourceReader

importlib.abc.Traversable

importlib.abc.TraversableResources

itertools: Support for copy, deepcopy, and pickle operations.

pkgutil:

pkgutil.find_loader()

pkgutil.get_loader().

pty:

pty.master_open()

pty.slave_open()

shutil: The onerror argument of shutil.rmtree()

typing: typing.ByteString

xml.etree.ElementTree: Testing the truth value of an xml.etree.ElementTree.Element.

The __package__ and __cached__ attributes on module objects.

The co_lnotab attribute of code objects.

Pending Removal in Python 3.15

The following APIs have been deprecated and will be removed in Python 3.15.

APIs:

locale.getdefaultlocale() (gh-90817 [https://github.com/python/cpython/issues/90817])

Pending Removal in Future Versions

The following APIs were deprecated in earlier Python versions and will be removed, although there is currently no date scheduled for their removal.

array's 'u' format code (gh-57281 [https://github.com/python/cpython/issues/57281])

typing.Text (gh-92332 [https://github.com/python/cpython/issues/92332])

Currently Python accepts numeric literals immediately followed by keywords, for example 0in x, 1or x, 0if 1else 2. It allows confusing and ambiguous expressions like [0x1for x in y] (which can be interpreted as [0x1 for x in y] or [0x1f or x in y]). A syntax warning is raised if the numeric literal is immediately followed by one of keywords and, else, for, if, in, is and or. In a future release it will be changed to a syntax error. (gh-87999 [https://github.com/python/cpython/issues/87999])

Removed

asynchat and asyncore

These two modules have been removed according to the schedule in PEP 594 [https://peps.python.org/pep-0594/], having been deprecated in Python 3.6. Use asyncio instead. (Contributed by Nikita Sobolev in gh-96580 [https://github.com/python/cpython/issues/96580].)

configparser

Several names deprecated in the configparser way back in 3.2 have been removed per gh-89336 [https://github.com/python/cpython/issues/89336]:

configparser.ParsingError no longer has a filename attribute or argument. Use the source attribute and argument instead.

configparser no longer has a SafeConfigParser class. Use the shorter ConfigParser name instead.

configparser.ConfigParser no longer has a readfp method. Use read_file() instead.

distutils

Remove the distutils package. It was deprecated in Python 3.10 by PEP 632 [https://peps.python.org/pep-0632/] "Deprecate distutils module". For projects still using distutils and cannot be updated to something else, the setuptools project can be installed: it still provides distutils. (Contributed by Victor Stinner in gh-92584 [https://github.com/python/cpython/issues/92584].)

ensurepip

Remove the bundled setuptools wheel from ensurepip, and stop installing setuptools in environments created by venv.

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

easy_install, pkg_resources, setuptools and distutils are no longer provided by default in environments created with venv or bootstrapped with ensurepip, since they are part of the setuptools package. For projects relying on these at runtime, the setuptools project should be declared as a dependency and installed separately (typically, using pip).

(Contributed by Pradyun Gedam in gh-95299 [https://github.com/python/cpython/issues/95299].)

enum

Remove enum's EnumMeta.__getattr__, which is no longer needed for enum attribute access. (Contributed by Ethan Furman in gh-95083 [https://github.com/python/cpython/issues/95083].)

ftplib

Remove ftplib's FTP_TLS.ssl_version class attribute: use the context parameter instead. (Contributed by Victor Stinner in gh-94172 [https://github.com/python/cpython/issues/94172].)

gzip

Remove the filename attribute of gzip's gzip.GzipFile, deprecated since Python 2.6, use the name attribute instead. In write mode, the filename attribute added '.gz' file extension if it was not present. (Contributed by Victor Stinner in gh-94196 [https://github.com/python/cpython/issues/94196].)

hashlib

Remove the pure Python implementation of hashlib's hashlib.pbkdf2_hmac(), deprecated in Python 3.10. Python 3.10 and newer requires OpenSSL 1.1.1 (PEP 644 [https://peps.python.org/pep-0644/]): this OpenSSL version provides a C implementation of pbkdf2_hmac() which is faster. (Contributed by Victor Stinner in gh-94199 [https://github.com/python/cpython/issues/94199].)

importlib

Many previously deprecated cleanups in importlib have now been completed:

References to, and support for module_repr() has been removed. (Contributed by Barry Warsaw in gh-97850 [https://github.com/python/cpython/issues/97850].)

importlib.util.set_package, importlib.util.set_loader and importlib.util.module_for_loader have all been removed. (Contributed by Brett Cannon and Nikita Sobolev in gh-65961 [https://github.com/python/cpython/issues/65961] and gh-97850 [https://github.com/python/cpython/issues/97850].)

Support for find_loader() and find_module() APIs have been removed. (Contributed by Barry Warsaw in gh-98040 [https://github.com/python/cpython/issues/98040].)

importlib.abc.Finder, pkgutil.ImpImporter, and pkgutil.ImpLoader have been removed. (Contributed by Barry Warsaw in gh-98040 [https://github.com/python/cpython/issues/98040].)

imp

The imp module has been removed. (Contributed by Barry Warsaw in gh-98040 [https://github.com/python/cpython/issues/98040].)

To migrate, consult the following correspondence table:

imp

importlib

imp.NullImporter

Insert None into sys.path_importer_cache

imp.cache_from_source()

importlib.util.cache_from_source()

imp.find_module()

importlib.util.find_spec()

imp.get_magic()

importlib.util.MAGIC_NUMBER

imp.get_suffixes()

importlib.machinery.SOURCE_SUFFIXES, importlib.machinery.EXTENSION_SUFFIXES, and importlib.machinery.BYTECODE_SUFFIXES

imp.get_tag()

sys.implementation.cache_tag

imp.load_module()

importlib.import_module()

imp.new_module(name)

types.ModuleType(name)

imp.reload()

importlib.reload()

imp.source_from_cache()

importlib.util.source_from_cache()

imp.load_source()

See below

Replace imp.load_source() with:

import importlib.util
import importlib.machinery

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

Remove imp functions and attributes with no replacements:

Undocumented functions:

imp.init_builtin()

imp.load_compiled()

imp.load_dynamic()

imp.load_package()

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

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

io

Remove io's io.OpenWrapper and _pyio.OpenWrapper, deprecated in Python 3.10: just use open() instead. The open() (io.open()) function is a built-in function. Since Python 3.10, _pyio.open() is also a static method. (Contributed by Victor Stinner in gh-94169 [https://github.com/python/cpython/issues/94169].)

locale

Remove locale's locale.format() function, deprecated in Python 3.7: use locale.format_string() instead. (Contributed by Victor Stinner in gh-94226 [https://github.com/python/cpython/issues/94226].)

smtpd

The smtpd module has been removed according to the schedule in PEP 594 [https://peps.python.org/pep-0594/], having been deprecated in Python 3.4.7 and 3.5.4. Use the aiosmtpd [https://pypi.org/project/aiosmtpd/] PyPI module or any other asyncio-based server instead. (Contributed by Oleg Iarygin in gh-93243 [https://github.com/python/cpython/issues/93243].)

sqlite3

The following undocumented sqlite3 features, deprecated in Python 3.10, are now removed:

sqlite3.enable_shared_cache()

sqlite3.OptimizedUnicode

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

The sqlite3.OptimizedUnicode text factory has been an alias for str since Python 3.3. Code that previously set the text factory to OptimizedUnicode can either use str explicitly, or rely on the default value which is also str.

(Contributed by Erlend E. Aasland in gh-92548 [https://github.com/python/cpython/issues/92548].)

ssl

Remove ssl's ssl.RAND_pseudo_bytes() function, deprecated in Python 3.6: use os.urandom() or ssl.RAND_bytes() instead. (Contributed by Victor Stinner in gh-94199 [https://github.com/python/cpython/issues/94199].)

Remove the ssl.match_hostname() function. It was deprecated in Python 3.7. OpenSSL performs hostname matching since Python 3.7, Python no longer uses the ssl.match_hostname() function. (Contributed by Victor Stinner in gh-94199 [https://github.com/python/cpython/issues/94199].)

Remove the ssl.wrap_socket() function, deprecated in Python 3.7: instead, create a ssl.SSLContext object and call its ssl.SSLContext.wrap_socket method. Any package that still uses ssl.wrap_socket() is broken and insecure. The function neither sends a SNI TLS extension nor validates the server hostname. Code is subject to CWE-295 [https://cwe.mitre.org/data/definitions/295.html] (Improper Certificate Validation). (Contributed by Victor Stinner in gh-94199 [https://github.com/python/cpython/issues/94199].)

unittest

Remove many long-deprecated unittest features:

A number of TestCase method aliases:

Deprecated alias

Method Name

Deprecated in

failUnless

assertTrue()

3.1

failIf

assertFalse()

3.1

failUnlessEqual

assertEqual()

3.1

failIfEqual

assertNotEqual()

3.1

failUnlessAlmostEqual

assertAlmostEqual()

3.1

failIfAlmostEqual

assertNotAlmostEqual()

3.1

failUnlessRaises

assertRaises()

3.1

assert_

assertTrue()

3.2

assertEquals

assertEqual()

3.2

assertNotEquals

assertNotEqual()

3.2

assertAlmostEquals

assertAlmostEqual()

3.2

assertNotAlmostEquals

assertNotAlmostEqual()

3.2

assertRegexpMatches

assertRegex()

3.2

assertRaisesRegexp

assertRaisesRegex()

3.2

assertNotRegexpMatches

assertNotRegex()

3.5

You can use https://github.com/isidentical/teyit to automatically modernise your unit tests.

Undocumented and broken TestCase method assertDictContainsSubset (deprecated in Python 3.2).

Undocumented TestLoader.loadTestsFromModule parameter use_load_tests (deprecated and ignored since Python 3.2).

An alias of the TextTestResult class: _TextTestResult (deprecated in Python 3.2).

(Contributed by Serhiy Storchaka in gh-89325 [https://github.com/python/cpython/issues/89325].)

webbrowser

Remove support for obsolete browsers from webbrowser. The removed browsers include: Grail, Mosaic, Netscape, Galeon, Skipstone, Iceape, Firebird, and Firefox versions 35 and below (gh-102871 [https://github.com/python/cpython/issues/102871]).

xml.etree.ElementTree

Remove the ElementTree.Element.copy() method of the pure Python implementation, deprecated in Python 3.10, use the copy.copy() function instead. The C implementation of xml.etree.ElementTree has no copy() method, only a __copy__() method. (Contributed by Victor Stinner in gh-94383 [https://github.com/python/cpython/issues/94383].)

zipimport

Remove zipimport's find_loader() and find_module() methods, deprecated in Python 3.10: use the find_spec() method instead. See PEP 451 [https://peps.python.org/pep-0451/] for the rationale. (Contributed by Victor Stinner in gh-94379 [https://github.com/python/cpython/issues/94379].)

Others

Remove the suspicious rule from the documentation Makefile and Doc/tools/rstlint.py, both in favor of sphinx-lint [https://github.com/sphinx-contrib/sphinx-lint]. (Contributed by Julien Palard in gh-98179 [https://github.com/python/cpython/issues/98179].)

Remove the keyfile and certfile parameters from the ftplib, imaplib, poplib and smtplib modules, and the key_file, cert_file and check_hostname parameters from the http.client module, all deprecated since Python 3.6. Use the context parameter (ssl_context in imaplib) instead. (Contributed by Victor Stinner in gh-94172 [https://github.com/python/cpython/issues/94172].)

Remove Jython compatibility hacks from several stdlib modules and tests. (Contributed by Nikita Sobolev in gh-99482 [https://github.com/python/cpython/issues/99482].)

Remove _use_broken_old_ctypes_structure_semantics_ flag from ctypes module. (Contributed by Nikita Sobolev in gh-99285 [https://github.com/python/cpython/issues/99285].)

Porting to Python 3.12

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

Changes in the Python API

More strict rules are now applied for numerical group references and group names in regular expressions. Only sequence of ASCII digits is now accepted as a numerical reference. The group name in bytes patterns and replacement strings can now only contain ASCII letters and digits and underscore. (Contributed by Serhiy Storchaka in gh-91760 [https://github.com/python/cpython/issues/91760].)

Remove 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-integer values such as randrange(10.5) or randrange('10') has been changed from ValueError to TypeError. This also prevents bugs where randrange(1e25) would silently select from a larger range than randrange(10**25). (Originally suggested by Serhiy Storchaka gh-86388 [https://github.com/python/cpython/issues/86388].)

argparse.ArgumentParser changed encoding and error handler for reading arguments from file (e.g. fromfile_prefix_chars option) from default text encoding (e.g. locale.getpreferredencoding(False)) to filesystem encoding and error handler. Argument files should be encoded in UTF-8 instead of ANSI Codepage on Windows.

Remove the asyncore-based smtpd module deprecated in Python 3.4.7 and 3.5.4. A recommended replacement is the asyncio-based aiosmtpd [https://pypi.org/project/aiosmtpd/] PyPI module.

shlex.split(): Passing None for s argument now raises an exception, rather than reading sys.stdin. The feature was deprecated in Python 3.9. (Contributed by Victor Stinner in gh-94352 [https://github.com/python/cpython/issues/94352].)

The os module no longer accepts bytes-like paths, like bytearray and memoryview types: only the exact bytes type is accepted for bytes strings. (Contributed by Victor Stinner in gh-98393 [https://github.com/python/cpython/issues/98393].)

syslog.openlog() and syslog.closelog() now fail if used in subinterpreters. syslog.syslog() may still be used in subinterpreters, but now only if 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, syslog is a wrapper around process-global resources, which are best managed from the main interpreter. (Contributed by Donghee Na in gh-99127 [https://github.com/python/cpython/issues/99127].)

The undocumented locking behavior of 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.

sys._current_exceptions() now returns a mapping from thread-id to an exception instance, rather than to a (typ, exc, tb) tuple. (Contributed by Irit Katriel in gh-103176 [https://github.com/python/cpython/issues/103176].)

When extracting tar files using tarfile or shutil.unpack_archive(), pass the filter argument to limit features that may be surprising or dangerous. See Extraction filters for details.

The output of the tokenize.tokenize() and tokenize.generate_tokens() functions is now changed due to the changes introduced in PEP 701 [https://peps.python.org/pep-0701/]. This means that STRING tokens are not emitted any more for f-strings and the tokens described in PEP 701 [https://peps.python.org/pep-0701/] are now produced instead: FSTRING_START, FSTRING_MIDDLE and 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 f"start {1+1} end" the old version of the tokenizer emitted:

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

while the new version emits:

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

Additionally, there may be some minor behavioral changes as a consequence of the changes required to support PEP 701 [https://peps.python.org/pep-0701/]. Some of these changes include:

The type attribute of the tokens emitted when tokenizing some invalid Python characters such as ! has changed from ERRORTOKEN to OP.

Incomplete single-line strings now also raise tokenize.TokenError as incomplete multiline strings do.

Some incomplete or invalid Python code now raises tokenize.TokenError instead of returning arbitrary ERRORTOKEN tokens when tokenizing it.

Mixing tabs and spaces as indentation in the same file is not supported anymore and will raise a TabError.

The threading module now expects the _thread module to have an _is_main_interpreter attribute. It is a function with no arguments that returns True if the current interpreter is the main interpreter.

Any library or application that provides a custom _thread module should provide _is_main_interpreter(). (See gh-112826 [https://github.com/python/cpython/issues/112826].)

Build Changes

Python no longer uses setup.py to build shared C extension modules. Build parameters like headers and libraries are detected in configure script. Extensions are built by Makefile. Most extensions use pkg-config and fall back to manual detection. (Contributed by Christian Heimes in gh-93939 [https://github.com/python/cpython/issues/93939].)

va_start() with two parameters, like va_start(args, format), is now required to build Python. va_start() is no longer called with a single parameter. (Contributed by Kumar Aditya in gh-93207 [https://github.com/python/cpython/issues/93207].)

CPython now uses the ThinLTO option as the default link time optimization policy if the Clang compiler accepts the flag. (Contributed by Donghee Na in gh-89536 [https://github.com/python/cpython/issues/89536].)

Add COMPILEALL_OPTS variable in Makefile to override compileall options (default: -j0) in make install. Also merged the 3 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 [https://github.com/python/cpython/issues/99289].)

Add platform triplets for 64-bit LoongArch:

loongarch64-linux-gnusf

loongarch64-linux-gnuf32

loongarch64-linux-gnu

(Contributed by Zhang Na in gh-90656 [https://github.com/python/cpython/issues/90656].)

PYTHON_FOR_REGEN now require Python 3.10 or newer.

Autoconf 2.71 and aclocal 1.16.4 is now required to regenerate !configure. (Contributed by Christian Heimes in gh-89886 [https://github.com/python/cpython/issues/89886].)

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

C API Changes

New Features

PEP 697 [https://peps.python.org/pep-0697/]: Introduce the 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 PyUnstable_ prefix in names.

Code object constructors:

PyUnstable_Code_New() (renamed from PyCode_New)

PyUnstable_Code_NewWithPosOnlyArgs() (renamed from PyCode_NewWithPosOnlyArgs)

Extra storage for code objects (PEP 523 [https://peps.python.org/pep-0523/]):

PyUnstable_Eval_RequestCodeExtraIndex() (renamed from _PyEval_RequestCodeExtraIndex)

PyUnstable_Code_GetExtra() (renamed from _PyCode_GetExtra)

PyUnstable_Code_SetExtra() (renamed from _PyCode_SetExtra)

The original names will continue to be available until the respective API changes.

(Contributed by Petr Viktorin in gh-101101 [https://github.com/python/cpython/issues/101101].)

PEP 697 [https://peps.python.org/pep-0697/]: Add an API for extending types whose instance memory layout is opaque:

PyType_Spec.basicsize can be zero or negative to specify inheriting or extending the base class size.

PyObject_GetTypeData() and PyType_GetTypeDataSize() added to allow access to subclass-specific instance data.

Py_TPFLAGS_ITEMS_AT_END and PyObject_GetItemData() added to allow safely extending certain variable-sized types, including PyType_Type.

Py_RELATIVE_OFFSET added to allow defining members in terms of a subclass-specific struct.

(Contributed by Petr Viktorin in gh-103509 [https://github.com/python/cpython/issues/103509].)

Add the new limited C API function PyType_FromMetaclass(), which generalizes the existing PyType_FromModuleAndSpec() using an additional metaclass argument. (Contributed by Wenzel Jakob in gh-93012 [https://github.com/python/cpython/issues/93012].)

API for creating objects that can be called using the vectorcall protocol was added to the Limited API:

Py_TPFLAGS_HAVE_VECTORCALL

PyVectorcall_NARGS()

PyVectorcall_Call()

vectorcallfunc

The Py_TPFLAGS_HAVE_VECTORCALL flag is now removed from a class when the class's __call__() method is reassigned. This makes vectorcall safe to use with mutable types (i.e. heap types without the immutable flag, Py_TPFLAGS_IMMUTABLETYPE). Mutable types that do not override tp_call now inherit the Py_TPFLAGS_HAVE_VECTORCALL flag. (Contributed by Petr Viktorin in gh-93274 [https://github.com/python/cpython/issues/93274].)

The Py_TPFLAGS_MANAGED_DICT and Py_TPFLAGS_MANAGED_WEAKREF flags have been added. This allows extensions classes to support object __dict__ and weakrefs with less bookkeeping, using less memory and with faster access.

API for performing calls using the vectorcall protocol was added to the Limited API:

PyObject_Vectorcall()

PyObject_VectorcallMethod()

PY_VECTORCALL_ARGUMENTS_OFFSET

This means that both the incoming and outgoing ends of the vector call protocol are now available in the Limited API. (Contributed by Wenzel Jakob in gh-98586 [https://github.com/python/cpython/issues/98586].)

Add two new public functions, PyEval_SetProfileAllThreads() and 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 [https://github.com/python/cpython/issues/93503].)

Add new function PyFunction_SetVectorcall() to the C API which sets the vectorcall field of a given PyFunctionObject. (Contributed by Andrew Frost in gh-92257 [https://github.com/python/cpython/issues/92257].)

The C API now permits registering callbacks via PyDict_AddWatcher(), 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 [https://github.com/python/cpython/issues/91052].)

Add PyType_AddWatcher() and PyType_Watch() API to register callbacks to receive notification on changes to a type. (Contributed by Carl Meyer in gh-91051 [https://github.com/python/cpython/issues/91051].)

Add PyCode_AddWatcher() and PyCode_ClearWatcher() APIs to register callbacks to receive notification on creation and destruction of code objects. (Contributed by Itamar Oren in gh-91054 [https://github.com/python/cpython/issues/91054].)

Add PyFrame_GetVar() and PyFrame_GetVarString() functions to get a frame variable by its name. (Contributed by Victor Stinner in gh-91248 [https://github.com/python/cpython/issues/91248].)

Add PyErr_GetRaisedException() and 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 PyErr_Fetch() and PyErr_Restore(). This is less error prone and a bit more efficient. (Contributed by Mark Shannon in gh-101578 [https://github.com/python/cpython/issues/101578].)

Add _PyErr_ChainExceptions1, which takes an exception instance, to replace the legacy-API _PyErr_ChainExceptions, which is now deprecated. (Contributed by Mark Shannon in gh-101578 [https://github.com/python/cpython/issues/101578].)

Add PyException_GetArgs() and PyException_SetArgs() as convenience functions for retrieving and modifying the args passed to the exception's constructor. (Contributed by Mark Shannon in gh-101578 [https://github.com/python/cpython/issues/101578].)

Add PyErr_DisplayException(), which takes an exception instance, to replace the legacy-api PyErr_Display(). (Contributed by Irit Katriel in gh-102755 [https://github.com/python/cpython/issues/102755]).

PEP 683 [https://peps.python.org/pep-0683/]: Introduce Immortal Objects, which allows objects to bypass reference counts, and related changes to the C-API:

_Py_IMMORTAL_REFCNT: The reference count that defines an object

as immortal.

_Py_IsImmortal Checks if an object has the immortal reference count.

PyObject_HEAD_INIT This will now initialize reference count to

_Py_IMMORTAL_REFCNT when used with Py_BUILD_CORE.

SSTATE_INTERNED_IMMORTAL An identifier for interned unicode objects

that are immortal.

SSTATE_INTERNED_IMMORTAL_STATIC An identifier for interned unicode

objects that are immortal and static

sys.getunicodeinternedsize This returns the total number of unicode

objects that have been interned. This is now needed for refleak.py to correctly track reference counts and allocated blocks

(Contributed by Eddie Elizondo in gh-84436 [https://github.com/python/cpython/issues/84436].)

PEP 684 [https://peps.python.org/pep-0684/]: Add the new Py_NewInterpreterFromConfig() function and PyInterpreterConfig, which may be used to create sub-interpreters with their own GILs. (See PEP 684: A Per-Interpreter GIL for more info.) (Contributed by Eric Snow in gh-104110 [https://github.com/python/cpython/issues/104110].)

In the limited C API version 3.12, Py_INCREF() and Py_DECREF() functions are now implemented as opaque function calls to hide implementation details. (Contributed by Victor Stinner in gh-105387 [https://github.com/python/cpython/issues/105387].)

Porting to Python 3.12

Legacy Unicode APIs based on Py_UNICODE* representation has been removed. Please migrate to APIs based on UTF-8 or wchar_t*.

Argument parsing functions like PyArg_ParseTuple() doesn't support Py_UNICODE* based format (e.g. u, Z) anymore. Please migrate to other formats for Unicode like s, z, es, and U.

tp_weaklist for all static builtin types is always NULL. This is an internal-only field on 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) _PyObject_GET_WEAKREFS_LISTPTR() macro.

This internal-only 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 __subclasses__() (using PyObject_CallMethod(), for example).

Add support of more formatting options (left aligning, octals, uppercase hexadecimals, intmax_t, ptrdiff_t, wchar_t C strings, variable width and precision) in PyUnicode_FromFormat() and PyUnicode_FromFormatV(). (Contributed by Serhiy Storchaka in gh-98836 [https://github.com/python/cpython/issues/98836].)

An unrecognized format character in PyUnicode_FromFormat() and PyUnicode_FromFormatV() now sets a 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 [https://github.com/python/cpython/issues/95781].)

Fix wrong sign placement in PyUnicode_FromFormat() and PyUnicode_FromFormatV(). (Contributed by Philip Georgi in gh-95504 [https://github.com/python/cpython/issues/95504].)

Extension classes wanting to add a __dict__ or weak reference slot should use Py_TPFLAGS_MANAGED_DICT and Py_TPFLAGS_MANAGED_WEAKREF instead of tp_dictoffset and tp_weaklistoffset, respectively. The use of tp_dictoffset and tp_weaklistoffset is still supported, but does not fully support multiple inheritance (gh-95589 [https://github.com/python/cpython/issues/95589]), and performance may be worse. Classes declaring Py_TPFLAGS_MANAGED_DICT should call _PyObject_VisitManagedDict() and _PyObject_ClearManagedDict() to traverse and clear their instance's dictionaries. To clear weakrefs, call PyObject_ClearWeakRefs(), as before.

The PyUnicode_FSDecoder() function no longer accepts bytes-like paths, like bytearray and memoryview types: only the exact bytes type is accepted for bytes strings. (Contributed by Victor Stinner in gh-98393 [https://github.com/python/cpython/issues/98393].)

The Py_CLEAR, Py_SETREF and 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 [https://github.com/python/cpython/issues/98724].)

The interpreter's error indicator is now always normalized. This means that PyErr_SetObject(), 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 [https://github.com/python/cpython/issues/101578].)

_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 _Py_GetGlobalRefTotal().

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

PyType_FromSpec()

PyType_FromSpecWithBases()

PyType_FromModuleAndSpec()

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

Note that PyType_FromMetaclass() (added in Python 3.12) already disallows creating classes whose metaclass overrides tp_new (__new__() in Python).

Since tp_new overrides almost everything 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 tp_new was called. There is no simple general workaround. One of the following may work for you:

If you control the metaclass, avoid using tp_new in it:

If initialization can be skipped, it can be done in tp_init instead.

If the metaclass doesn't need to be instantiated from Python, set its tp_new to NULL using the Py_TPFLAGS_DISALLOW_INSTANTIATION flag. This makes it acceptable for PyType_From* functions.

Avoid PyType_From* functions: if you don't need C-specific features (slots or setting the instance size), create types by calling the metaclass.

If you know the tp_new can be skipped safely, filter the deprecation warning out using warnings.catch_warnings() from Python.

PyOS_InputHook and PyOS_ReadlineFunctionPointer are no longer called in 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 [https://github.com/python/cpython/issues/104668] for more info.

PyLongObject has had its internals changed for better performance. Although the internals of PyLongObject are private, they are used by some extension modules. The internal fields should no longer be accessed directly, instead the API functions beginning PyLong_... should be used instead. Two new unstable API functions are provided for efficient access to the value of PyLongObjects which fit into a single machine word:

PyUnstable_Long_IsCompact()

PyUnstable_Long_CompactValue()

Custom allocators, set via 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 @ericsnowcurrently.

Deprecated

In accordance with PEP 699 [https://peps.python.org/pep-0699/], the ma_version_tag field in 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 [https://github.com/python/cpython/issues/101193]. PEP by Ken Jin.)

Deprecate global configuration variable:

Py_DebugFlag: use PyConfig.parser_debug

Py_VerboseFlag: use PyConfig.verbose

Py_QuietFlag: use PyConfig.quiet

Py_InteractiveFlag: use PyConfig.interactive

Py_InspectFlag: use PyConfig.inspect

Py_OptimizeFlag: use PyConfig.optimization_level

Py_NoSiteFlag: use PyConfig.site_import

Py_BytesWarningFlag: use PyConfig.bytes_warning

Py_FrozenFlag: use PyConfig.pathconfig_warnings

Py_IgnoreEnvironmentFlag: use PyConfig.use_environment

Py_DontWriteBytecodeFlag: use PyConfig.write_bytecode

Py_NoUserSiteDirectory: use PyConfig.user_site_directory

Py_UnbufferedStdioFlag: use PyConfig.buffered_stdio

Py_HashRandomizationFlag: use PyConfig.use_hash_seed and PyConfig.hash_seed

Py_IsolatedFlag: use PyConfig.isolated

Py_LegacyWindowsFSEncodingFlag: use PyPreConfig.legacy_windows_fs_encoding

Py_LegacyWindowsStdioFlag: use PyConfig.legacy_windows_stdio

Py_FileSystemDefaultEncoding: use PyConfig.filesystem_encoding

Py_HasFileSystemDefaultEncoding: use PyConfig.filesystem_encoding

Py_FileSystemDefaultEncodeErrors: use PyConfig.filesystem_errors

Py_UTF8Mode: use PyPreConfig.utf8_mode (see Py_PreInitialize())

The Py_InitializeFromConfig() API should be used with PyConfig instead. (Contributed by Victor Stinner in gh-77782 [https://github.com/python/cpython/issues/77782].)

Creating immutable types with mutable bases is deprecated and will be disabled in Python 3.14. (gh-95388 [https://github.com/python/cpython/issues/95388])

The structmember.h header is deprecated, though it continues to be available and there are no plans to remove it.

Its contents are now available just by including Python.h, with a Py prefix added if it was missing:

PyMemberDef, PyMember_GetOne() and PyMember_SetOne()

Type macros like Py_T_INT, Py_T_DOUBLE, etc. (previously T_INT, T_DOUBLE, etc.)

The flags Py_READONLY (previously READONLY) and Py_AUDIT_READ (previously all uppercase)

Several items are not exposed from Python.h:

T_OBJECT (use Py_T_OBJECT_EX)

T_NONE (previously undocumented, and pretty quirky)

The macro WRITE_RESTRICTED which does nothing.

The macros RESTRICTED and READ_RESTRICTED, equivalents of Py_AUDIT_READ.

In some configurations, <stddef.h> is not included from Python.h. It should be included manually when using offsetof().

The deprecated header continues to provide its original contents under the original names. Your old code can stay unchanged, unless the extra include and non-namespaced macros bother you greatly.

(Contributed in gh-47146 [https://github.com/python/cpython/issues/47146] by Petr Viktorin, based on earlier work by Alexander Belopolsky and Matthias Braun.)

PyErr_Fetch() and PyErr_Restore() are deprecated. Use PyErr_GetRaisedException() and PyErr_SetRaisedException() instead. (Contributed by Mark Shannon in gh-101578 [https://github.com/python/cpython/issues/101578].)

PyErr_Display() is deprecated. Use PyErr_DisplayException() instead. (Contributed by Irit Katriel in gh-102755 [https://github.com/python/cpython/issues/102755]).

_PyErr_ChainExceptions is deprecated. Use _PyErr_ChainExceptions1 instead. (Contributed by Irit Katriel in gh-102192 [https://github.com/python/cpython/issues/102192].)

Using PyType_FromSpec(), PyType_FromSpecWithBases() or PyType_FromModuleAndSpec() to create a class whose metaclass overrides tp_new is deprecated. Call the metaclass instead.

Pending Removal in Python 3.14

The ma_version_tag field in PyDictObject for extension modules (PEP 699 [https://peps.python.org/pep-0699/]; gh-101193 [https://github.com/python/cpython/issues/101193]).

Global configuration variables:

Py_DebugFlag: use PyConfig.parser_debug

Py_VerboseFlag: use PyConfig.verbose

Py_QuietFlag: use PyConfig.quiet

Py_InteractiveFlag: use PyConfig.interactive

Py_InspectFlag: use PyConfig.inspect

Py_OptimizeFlag: use PyConfig.optimization_level

Py_NoSiteFlag: use PyConfig.site_import

Py_BytesWarningFlag: use PyConfig.bytes_warning

Py_FrozenFlag: use PyConfig.pathconfig_warnings

Py_IgnoreEnvironmentFlag: use PyConfig.use_environment

Py_DontWriteBytecodeFlag: use PyConfig.write_bytecode

Py_NoUserSiteDirectory: use PyConfig.user_site_directory

Py_UnbufferedStdioFlag: use PyConfig.buffered_stdio

Py_HashRandomizationFlag: use PyConfig.use_hash_seed and PyConfig.hash_seed

Py_IsolatedFlag: use PyConfig.isolated

Py_LegacyWindowsFSEncodingFlag: use PyPreConfig.legacy_windows_fs_encoding

Py_LegacyWindowsStdioFlag: use PyConfig.legacy_windows_stdio

Py_FileSystemDefaultEncoding: use PyConfig.filesystem_encoding

Py_HasFileSystemDefaultEncoding: use PyConfig.filesystem_encoding

Py_FileSystemDefaultEncodeErrors: use PyConfig.filesystem_errors

Py_UTF8Mode: use PyPreConfig.utf8_mode (see Py_PreInitialize())

The Py_InitializeFromConfig() API should be used with PyConfig instead.

Creating immutable types with mutable bases (gh-95388 [https://github.com/python/cpython/issues/95388]).

Pending Removal in Python 3.15

PyImport_ImportModuleNoBlock(): use PyImport_ImportModule()

Py_UNICODE_WIDE type: use wchar_t

Py_UNICODE type: use wchar_t

Python initialization functions:

PySys_ResetWarnOptions(): clear sys.warnoptions and warnings.filters

Py_GetExecPrefix(): get sys.exec_prefix

Py_GetPath(): get sys.path

Py_GetPrefix(): get sys.prefix

Py_GetProgramFullPath(): get sys.executable

Py_GetProgramName(): get sys.executable

Py_GetPythonHome(): get PyConfig.home or the PYTHONHOME environment variable

Pending Removal in Future Versions

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

Py_TPFLAGS_HAVE_FINALIZE: unneeded since Python 3.8

PyErr_Fetch(): use PyErr_GetRaisedException()

PyErr_NormalizeException(): use PyErr_GetRaisedException()

PyErr_Restore(): use PyErr_SetRaisedException()

PyModule_GetFilename(): use PyModule_GetFilenameObject()

PyOS_AfterFork(): use PyOS_AfterFork_Child()

PySlice_GetIndicesEx(): use PySlice_Unpack() and PySlice_AdjustIndices()

PyUnicode_AsDecodedObject(): use PyCodec_Decode()

PyUnicode_AsDecodedUnicode(): use PyCodec_Decode()

PyUnicode_AsEncodedObject(): use PyCodec_Encode()

PyUnicode_AsEncodedUnicode(): use PyCodec_Encode()

PyUnicode_READY(): unneeded since Python 3.12

PyErr_Display(): use PyErr_DisplayException()

_PyErr_ChainExceptions(): use _PyErr_ChainExceptions1

PyBytesObject.ob_shash member: call PyObject_Hash() instead

PyDictObject.ma_version_tag member

Thread Local Storage (TLS) API:

PyThread_create_key(): use PyThread_tss_alloc()

PyThread_delete_key(): use PyThread_tss_free()

PyThread_set_key_value(): use PyThread_tss_set()

PyThread_get_key_value(): use PyThread_tss_get()

PyThread_delete_key_value(): use PyThread_tss_delete()

PyThread_ReInitTLS(): unneeded since Python 3.7

Removed

Remove the token.h header file. There was never any public tokenizer C API. The token.h header file was only designed to be used by Python internals. (Contributed by Victor Stinner in gh-92651 [https://github.com/python/cpython/issues/92651].)

Legacy Unicode APIs have been removed. See PEP 623 [https://peps.python.org/pep-0623/] for detail.

PyUnicode_WCHAR_KIND

PyUnicode_AS_UNICODE()

PyUnicode_AsUnicode()

PyUnicode_AsUnicodeAndSize()

PyUnicode_AS_DATA()

PyUnicode_FromUnicode()

PyUnicode_GET_SIZE()

PyUnicode_GetSize()

PyUnicode_GET_DATA_SIZE()

Remove the PyUnicode_InternImmortal() function macro. (Contributed by Victor Stinner in gh-85858 [https://github.com/python/cpython/issues/85858].)

Notable changes in 3.12.4

ipaddress

Fixed is_global and is_private behavior in IPv4Address, IPv6Address, IPv4Network and IPv6Network.

What's New In Python 3.11

編集者:

Pablo Galindo Salgado

この記事では Python 3.10 と比較した Python 3.11 の新機能を解説します。Python 3.11 は2022年10月24日にリリースされました。全詳細については 変更履歴 をご覧ください。

概要 -- リリースハイライト

Python 3.11 は Python 3.10 とくらべて 10-60% 高速です。平均的には、標準ベンチマークスイートでは 1.25倍の高速化を計測しました。詳細については Faster CPython を見てください。

新たな文法機能:

PEP 654: 例外グループと except*

新たな組み込み機能:

PEP 678: ノートによって例外を充実させる

新しい標準ライブラリのモジュール：

PEP 680 [https://peps.python.org/pep-0680/]: tomllib — TOML [https://toml.io/] のパースを標準ライブラリでサポート

インタープリタの改善:

PEP 657: トレースバックのエラー位置の詳細化

新しい -P コマンドライン引数と PYTHONSAFEPATH 環境変数により、 安全でない可能性のあるパス を sys.path に自動的に先頭に付加しないようにします。

新しい型ヒントの機能:

PEP 646: Variadic generics

PEP 655: Marking individual TypedDict items as required or not-required

PEP 673: Self 型

PEP 675: Arbitrary literal string type

PEP 681: Data class transforms

重要な非推奨化、削除と制限：

PEP 594 [https://peps.python.org/pep-0594/]: たくさんのレガシーの標準ライブラリのモジュールが非推奨になり Python 3.13 で削除されます

PEP 624 [https://peps.python.org/pep-0624/]: Py_UNICODE エンコーダー API は削除されました

PEP 670 [https://peps.python.org/pep-0670/]: 静的インライン関数に変換されたマクロ

新しい機能

PEP 657: トレースバックのエラー位置の詳細化

トレースバックの出力時に、インタープリタはエラーを送出した行だけでなく正確な式を指し示すようになりました。たとえば:

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'

以前のバージョンのインタープリタはその行だけを指していたため、どのオブジェクトが None であるかが曖昧でした。これらの強化されたエラーは、深くネストされた dict オブジェクトや複数の関数呼び出しを処理するときにも役立ちます:

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

複雑な算術式と同様に:

Traceback (most recent call last):
  File "calculation.py", line 54, in <module>
    result = (x / y / z) * (a / b / c)
              ~~~~~~^~~
ZeroDivisionError: division by zero

さらに、強化されたトレースバック機能で使用される情報は、一般的な API を介して利用可能になり、 bytecode 命令 とソースコードの場所を関連付けるために使用できます。この情報は次を使用して取得できます:

Python の codeobject.co_positions() メソッド。

C API の PyCode_Addr2Location() 関数。

詳細は PEP 657 [https://peps.python.org/pep-0657/] を参照してください。(Pablo Galindo, Batuhan Taskaya, Ammar Askar の貢献による bpo-43950 [https://bugs.python.org/issue?@action=redirect&bpo=43950])

注釈

この機能は コードオブジェクト に列の位置を保存する必要があり、その結果コンパイルされた Pthon ファイルのインタープリタのメモリ使用量とディスク使用量がわずかに増加する可能性があります。余分な情報を保存せず、余分なトレースバック情報を表示しないようにするには -X no_debug_ranges コマンドライン引数または PYTHONNODEBUGRANGES 環境変数を使用してください。

PEP 654: 例外グループと except*

PEP 654 [https://peps.python.org/pep-0654/] では、プログラムが無関係な複数の例外を同時に送出させて処理できるようにする言語機能が導入されています。組み込み型 ExceptionGroup と BaseExceptionGroup を使用すると、例外をグループ化して一緒に送出することができます。また、新しい except* 構文は、 except を例外グループのサブグループにマッチするように一般化したものです。

より詳しくは PEP 654 [https://peps.python.org/pep-0654/] を参照してください。

(Irit Katriel の貢献による bpo-45292 [https://bugs.python.org/issue?@action=redirect&bpo=45292]。PEP はIrit Katriel, Yury Selivanov, Guido van Rossum によって作成されました。)

PEP 678: ノートによって例外を充実させる

BaseException に add_note() メソッドが追加されました。これは例外が送出された時点では利用できないコンテキスト情報を例外に付与するために使用できます。追加された注釈はデフォルトのトレースバックに表示されます。

より詳しくは PEP 678 [https://peps.python.org/pep-0678/] を参照してください。

(Irit Katriel の貢献による bpo-45607 [https://bugs.python.org/issue?@action=redirect&bpo=45607]。PEP は Zac Hatfield-Dodds によって作成されました。)

Windows py.exe ランチャーの改善

Python 3.11 に含まれる Windows の Python ランチャ のコピーが大幅に更新されました。 PEP 514 [https://peps.python.org/pep-0514/] で定義されているように、制限付きの -<major>.<minor> の代わりに -V:<company>/<tag> 引数を使用した company/tag 構文をサポートするようになりました。これにより、 python.org [https://www.python.org] でホストされている PythonCore 以外のディストリビューションを起動できるようになります。

When using -V: selectors, either company or tag can be omitted, but all installs will be searched. For example, -V:OtherPython/ will select the "best" tag registered for OtherPython, while -V:3.11 or -V:/3.11 will select the "best" distribution with tag 3.11.

When using the legacy -<major>, -<major>.<minor>, -<major>-<bitness> or -<major>.<minor>-<bitness> arguments, all existing behaviour should be preserved from past versions, and only releases from PythonCore will be selected. However, the -64 suffix now implies "not 32-bit" (not necessarily x86-64), as there are multiple supported 64-bit platforms. 32-bit runtimes are detected by checking the runtime's tag for a -32 suffix. All releases of Python since 3.5 have included this in their 32-bit builds.

型ヒントに関連する新しい機能

This section covers major changes affecting PEP 484 [https://peps.python.org/pep-0484/] type hints and the typing module.

PEP 646: Variadic generics

PEP 484 [https://peps.python.org/pep-0484/] previously introduced TypeVar, enabling creation of generics parameterised with a single type. PEP 646 [https://peps.python.org/pep-0646/] adds TypeVarTuple, enabling parameterisation with an arbitrary number of types. In other words, a TypeVarTuple is a variadic type variable, enabling variadic generics.

This enables a wide variety of use cases. In particular, it allows the type of array-like structures in numerical computing libraries such as NumPy and TensorFlow to be parameterised with the array shape. Static type checkers will now be able to catch shape-related bugs in code that uses these libraries.

より詳しくは PEP 646 [https://peps.python.org/pep-0646/] を参照してください。

(Contributed by Matthew Rahtz in bpo-43224 [https://bugs.python.org/issue?@action=redirect&bpo=43224], with contributions by Serhiy Storchaka and Jelle Zijlstra. PEP written by Mark Mendoza, Matthew Rahtz, Pradeep Kumar Srinivasan, and Vincent Siles.)

PEP 655: Marking individual TypedDict items as required or not-required

Required and NotRequired provide a straightforward way to mark whether individual items in a TypedDict must be present. Previously, this was only possible using inheritance.

All fields are still required by default, unless the total parameter is set to False, in which case all fields are still not-required by default. For example, the following specifies a TypedDict with one required and one not-required key:

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)

The following definition is equivalent:

class Movie(TypedDict, total=False):
   title: Required[str]
   year: int

より詳しくは PEP 655 [https://peps.python.org/pep-0655/] を参照してください。

(Contributed by David Foster and Jelle Zijlstra in bpo-47087 [https://bugs.python.org/issue?@action=redirect&bpo=47087]. PEP written by David Foster.)

PEP 673: Self 型

The new Self annotation provides a simple and intuitive way to annotate methods that return an instance of their class. This behaves the same as the TypeVar-based approach specified in PEP 484 [https://peps.python.org/pep-0484/#annotating-instance-and-class-methods], but is more concise and easier to follow.

Common use cases include alternative constructors provided as classmethods, and __enter__() methods that return self:

class MyLock:
    def __enter__(self) -> Self:
        self.lock()
        return self

    ...

class MyInt:
    @classmethod
    def fromhex(cls, s: str) -> Self:
        return cls(int(s, 16))

    ...

Self can also be used to annotate method parameters or attributes of the same type as their enclosing class.

より詳しくは PEP 673 [https://peps.python.org/pep-0673/] を参照してください。

(Contributed by James Hilton-Balfe in bpo-46534 [https://bugs.python.org/issue?@action=redirect&bpo=46534]. PEP written by Pradeep Kumar Srinivasan and James Hilton-Balfe.)

PEP 675: Arbitrary literal string type

The new LiteralString annotation may be used to indicate that a function parameter can be of any literal string type. This allows a function to accept arbitrary literal string types, as well as strings created from other literal strings. Type checkers can then enforce that sensitive functions, such as those that execute SQL statements or shell commands, are called only with static arguments, providing protection against injection attacks.

For example, a SQL query function could be annotated as follows:

def run_query(sql: LiteralString) -> ...
    ...

def caller(
    arbitrary_string: str,
    query_string: LiteralString,
    table_name: LiteralString,
) -> None:
    run_query("SELECT * FROM students")       # ok
    run_query(query_string)                   # ok
    run_query("SELECT * FROM " + table_name)  # ok
    run_query(arbitrary_string)               # type checker error
    run_query(                                # type checker error
        f"SELECT * FROM students WHERE name = {arbitrary_string}"
    )

より詳しくは PEP 675 [https://peps.python.org/pep-0675/] を参照してください。

(Contributed by Jelle Zijlstra in bpo-47088 [https://bugs.python.org/issue?@action=redirect&bpo=47088]. PEP written by Pradeep Kumar Srinivasan and Graham Bleaney.)

PEP 681: Data class transforms

dataclass_transform may be used to decorate a class, metaclass, or a function that is itself a decorator. The presence of @dataclass_transform() tells a static type checker that the decorated object performs runtime "magic" that transforms a class, giving it dataclass-like behaviors.

例えば:

# The create_model decorator is defined by a library.
@typing.dataclass_transform()
def create_model(cls: Type[T]) -> Type[T]:
    cls.__init__ = ...
    cls.__eq__ = ...
    cls.__ne__ = ...
    return cls

# The create_model decorator can now be used to create new model classes:
@create_model
class CustomerModel:
    id: int
    name: str

c = CustomerModel(id=327, name="Eric Idle")

より詳しくは PEP 681 [https://peps.python.org/pep-0681/] を参照してください。

(Contributed by Jelle Zijlstra in gh-91860 [https://github.com/python/cpython/issues/91860]. PEP written by Erik De Bonte and Eric Traut.)

PEP 563 may not be the future

PEP 563 [https://peps.python.org/pep-0563/] Postponed Evaluation of Annotations (the from __future__ import annotations future statement) that was originally planned for release in Python 3.10 has been put on hold indefinitely. See this message from the Steering Council [https://mail.python.org/archives/list/python-dev@python.org/message/VIZEBX5EYMSYIJNDBF6DMUMZOCWHARSO/] for more information.

その他の言語変更

Starred unpacking expressions can now be used in for statements. (See bpo-46725 [https://bugs.python.org/issue?@action=redirect&bpo=46725] for more details.)

Asynchronous comprehensions are now allowed inside comprehensions in asynchronous functions. Outer comprehensions implicitly become asynchronous in this case. (Contributed by Serhiy Storchaka in bpo-33346 [https://bugs.python.org/issue?@action=redirect&bpo=33346].)

A TypeError is now raised instead of an AttributeError in with statements and contextlib.ExitStack.enter_context() for objects that do not support the context manager protocol, and in async with statements and contextlib.AsyncExitStack.enter_async_context() for objects not supporting the asynchronous context manager protocol. (Contributed by Serhiy Storchaka in bpo-12022 [https://bugs.python.org/issue?@action=redirect&bpo=12022] and bpo-44471 [https://bugs.python.org/issue?@action=redirect&bpo=44471].)

Added object.__getstate__(), which provides the default implementation of the __getstate__() method. copying and pickleing 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. This change has an unintended side effect: It trips up a small minority of existing Python projects not expecting object.__getstate__() to exist. See the later comments on gh-70766 [https://github.com/python/cpython/issues/70766] for discussions of what workarounds such code may need. (Contributed by Serhiy Storchaka in bpo-26579 [https://bugs.python.org/issue?@action=redirect&bpo=26579].)

Added a -P command line option and a PYTHONSAFEPATH environment variable, which disable the automatic prepending to sys.path of the script's directory when running a script, or the current directory when using -c and -m. This ensures only stdlib and installed modules are picked up by import, and avoids unintentionally or maliciously shadowing modules with those in a local (and typically user-writable) directory. (Contributed by Victor Stinner in gh-57684 [https://github.com/python/cpython/issues/57684].)

A "z" option was added to the 書式指定ミニ言語仕様 that coerces negative to positive zero after rounding to the format precision. See PEP 682 [https://peps.python.org/pep-0682/] for more details. (Contributed by John Belmonte in gh-90153 [https://github.com/python/cpython/issues/90153].)

Bytes are no longer accepted on sys.path. Support broke sometime between Python 3.2 and 3.6, with no one noticing until after Python 3.10.0 was released. In addition, bringing back support would be problematic due to interactions between -b and sys.path_importer_cache when there is a mixture of str and bytes keys. (Contributed by Thomas Grainger in gh-91181 [https://github.com/python/cpython/issues/91181].)

その他の CPython の実装の変更

The special methods __complex__() for complex and __bytes__() for bytes are implemented to support the typing.SupportsComplex and typing.SupportsBytes protocols. (Contributed by Mark Dickinson and Donghee Na in bpo-24234 [https://bugs.python.org/issue?@action=redirect&bpo=24234].)

siphash13 is added as a new internal hashing algorithm. It has similar security properties as siphash24, but it is slightly faster for long inputs. str, bytes, and some other types now use it as the default algorithm for hash(). PEP 552 [https://peps.python.org/pep-0552/] hash-based .pyc files now use siphash13 too. (Contributed by Inada Naoki in bpo-29410 [https://bugs.python.org/issue?@action=redirect&bpo=29410].)

When an active exception is re-raised by a raise statement with no parameters, the traceback attached to this exception is now always sys.exc_info()[1].__traceback__. This means that changes made to the traceback in the current except clause are reflected in the re-raised exception. (Contributed by Irit Katriel in bpo-45711 [https://bugs.python.org/issue?@action=redirect&bpo=45711].)

The interpreter state's representation of handled exceptions (aka exc_info or _PyErr_StackItem) now only has the exc_value field; exc_type and exc_traceback have been removed, as they can be derived from exc_value. (Contributed by Irit Katriel in bpo-45711 [https://bugs.python.org/issue?@action=redirect&bpo=45711].)

A new command line option, AppendPath, has been added for the Windows installer. It behaves similarly to PrependPath, but appends the install and scripts directories instead of prepending them. (Contributed by Bastian Neuburger in bpo-44934 [https://bugs.python.org/issue?@action=redirect&bpo=44934].)

The PyConfig.module_search_paths_set field must now be set to 1 for initialization to use PyConfig.module_search_paths to initialize sys.path. Otherwise, initialization will recalculate the path and replace any values added to module_search_paths.

The output of the --help option now fits in 50 lines/80 columns. Information about Python environment variables and -X options is now available using the respective --help-env and --help-xoptions flags, and with the new --help-all. (Contributed by Éric Araujo in bpo-46142 [https://bugs.python.org/issue?@action=redirect&bpo=46142].)

Converting between int and str in bases other than 2 (binary), 4, 8 (octal), 16 (hexadecimal), or 32 such as base 10 (decimal) now raises a 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 CVE-2020-10735 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-10735]. This limit can be configured or disabled by environment variable, command line flag, or sys APIs. See the integer string conversion length limitation documentation. The default limit is 4300 digits in string form.

新たなモジュール

tomllib: For parsing TOML [https://toml.io/]. See PEP 680 [https://peps.python.org/pep-0680/] for more details. (Contributed by Taneli Hukkinen in bpo-40059 [https://bugs.python.org/issue?@action=redirect&bpo=40059].)

wsgiref.types: WSGI [https://peps.python.org/pep-3333/]-specific types for static type checking. (Contributed by Sebastian Rittau in bpo-42012 [https://bugs.python.org/issue?@action=redirect&bpo=42012].)

改良されたモジュール

asyncio

Added the TaskGroup class, an asynchronous context manager holding a group of tasks that will wait for all of them upon exit. For new code this is recommended over using create_task() and gather() directly. (Contributed by Yury Selivanov and others in gh-90908 [https://github.com/python/cpython/issues/90908].)

Added timeout(), an asynchronous context manager for setting a timeout on asynchronous operations. For new code this is recommended over using wait_for() directly. (Contributed by Andrew Svetlov in gh-90927 [https://github.com/python/cpython/issues/90927].)

Added the Runner class, which exposes the machinery used by run(). (Contributed by Andrew Svetlov in gh-91218 [https://github.com/python/cpython/issues/91218].)

Added the Barrier class to the synchronization primitives in the asyncio library, and the related BrokenBarrierError exception. (Contributed by Yves Duprat and Andrew Svetlov in gh-87518 [https://github.com/python/cpython/issues/87518].)

Added keyword argument all_errors to asyncio.loop.create_connection() so that multiple connection errors can be raised as an ExceptionGroup.

Added the asyncio.StreamWriter.start_tls() method for upgrading existing stream-based connections to TLS. (Contributed by Ian Good in bpo-34975 [https://bugs.python.org/issue?@action=redirect&bpo=34975].)

Added raw datagram socket functions to the event loop: sock_sendto(), sock_recvfrom() and sock_recvfrom_into(). These have implementations in SelectorEventLoop and ProactorEventLoop. (Contributed by Alex Grönholm in bpo-46805 [https://bugs.python.org/issue?@action=redirect&bpo=46805].)

Added cancelling() and uncancel() methods to Task. These are primarily intended for internal use, notably by TaskGroup.

contextlib

Added non parallel-safe chdir() context manager to change the current working directory and then restore it on exit. Simple wrapper around chdir(). (Contributed by Filipe Laíns in bpo-25625 [https://bugs.python.org/issue?@action=redirect&bpo=25625])

データクラス

Change field default mutability check, allowing only defaults which are hashable instead of any object which is not an instance of dict, list or set. (Contributed by Eric V. Smith in bpo-44674 [https://bugs.python.org/issue?@action=redirect&bpo=44674].)

datetime

Add datetime.UTC, a convenience alias for datetime.timezone.utc. (Contributed by Kabir Kwatra in gh-91973 [https://github.com/python/cpython/issues/91973].)

datetime.date.fromisoformat(), datetime.time.fromisoformat() and datetime.datetime.fromisoformat() can now be used to parse most ISO 8601 formats (barring only those that support fractional hours and minutes). (Contributed by Paul Ganssle in gh-80010 [https://github.com/python/cpython/issues/80010].)

enum

Renamed EnumMeta to EnumType (EnumMeta kept as an alias).

Added StrEnum, with members that can be used as (and must be) strings.

Added ReprEnum, which only modifies the __repr__() of members while returning their literal values (rather than names) for __str__() and __format__() (used by str(), format() and f-strings).

Changed Enum.__format__() (the default for format(), str.format() and f-strings) to always produce the same result as Enum.__str__(): for enums inheriting from ReprEnum it will be the member's value; for all other enums it will be the enum and member name (e.g. Color.RED).

Added a new boundary class parameter to Flag enums and the FlagBoundary enum with its options, to control how to handle out-of-range flag values.

Added the verify() enum decorator and the EnumCheck enum with its options, to check enum classes against several specific constraints.

Added the member() and nonmember() decorators, to ensure the decorated object is/is not converted to an enum member.

Added the property() decorator, which works like property() except for enums. Use this instead of types.DynamicClassAttribute().

Added the global_enum() enum decorator, which adjusts __repr__() and __str__() to show values as members of their module rather than the enum class. For example, 're.ASCII' for the ASCII member of re.RegexFlag rather than 'RegexFlag.ASCII'.

Enhanced Flag to support len(), iteration and in/not in on its members. For example, the following now works: len(AFlag(3)) == 2 and list(AFlag(3)) == (AFlag.ONE, AFlag.TWO)

Changed Enum and Flag so that members are now defined before __init_subclass__() is called; dir() now includes methods, etc., from mixed-in data types.

Changed Flag to only consider primary values (power of two) canonical while composite values (3, 6, 10, etc.) are considered aliases; inverted flags are coerced to their positive equivalent.

fcntl

On FreeBSD, the F_DUP2FD and F_DUP2FD_CLOEXEC flags respectively are supported, the former equals to dup2 usage while the latter set the FD_CLOEXEC flag in addition.

fractions

Support PEP 515 [https://peps.python.org/pep-0515/]-style initialization of Fraction from string. (Contributed by Sergey B Kirpichev in bpo-44258 [https://bugs.python.org/issue?@action=redirect&bpo=44258].)

Fraction now implements an __int__ method, so that an isinstance(some_fraction, typing.SupportsInt) check passes. (Contributed by Mark Dickinson in bpo-44547 [https://bugs.python.org/issue?@action=redirect&bpo=44547].)

functools

functools.singledispatch() now supports types.UnionType and typing.Union as annotations to the dispatch argument.:

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

(Contributed by Yurii Karabas in bpo-46014 [https://bugs.python.org/issue?@action=redirect&bpo=46014].)

hashlib

hashlib.blake2b() and hashlib.blake2s() now prefer libb2 [https://www.blake2.net/] over Python's vendored copy. (Contributed by Christian Heimes in bpo-47095 [https://bugs.python.org/issue?@action=redirect&bpo=47095].)

The internal _sha3 module with SHA3 and SHAKE algorithms now uses tiny_sha3 instead of the Keccak Code Package to reduce code and binary size. The hashlib module prefers optimized SHA3 and SHAKE implementations from OpenSSL. The change affects only installations without OpenSSL support. (Contributed by Christian Heimes in bpo-47098 [https://bugs.python.org/issue?@action=redirect&bpo=47098].)

Add hashlib.file_digest(), a helper function for efficient hashing of files or file-like objects. (Contributed by Christian Heimes in gh-89313 [https://github.com/python/cpython/issues/89313].)

IDLE と idelelib

Apply syntax highlighting to .pyi files. (Contributed by Alex Waygood and Terry Jan Reedy in bpo-45447 [https://bugs.python.org/issue?@action=redirect&bpo=45447].)

Include prompts when saving Shell with inputs and outputs. (Contributed by Terry Jan Reedy in gh-95191 [https://github.com/python/cpython/issues/95191].)

inspect

Add getmembers_static() to return all members without triggering dynamic lookup via the descriptor protocol. (Contributed by Weipeng Hong in bpo-30533 [https://bugs.python.org/issue?@action=redirect&bpo=30533].)

Add ismethodwrapper() for checking if the type of an object is a MethodWrapperType. (Contributed by Hakan Çelik in bpo-29418 [https://bugs.python.org/issue?@action=redirect&bpo=29418].)

Change the frame-related functions in the inspect module to return new FrameInfo and Traceback class instances (backwards compatible with the previous named tuple-like interfaces) that includes the extended PEP 657 [https://peps.python.org/pep-0657/] position information (end line number, column and end column). The affected functions are:

inspect.getframeinfo()

inspect.getouterframes()

inspect.getinnerframes(),

inspect.stack()

inspect.trace()

(Contributed by Pablo Galindo in gh-88116 [https://github.com/python/cpython/issues/88116].)

locale

Add locale.getencoding() to get the current locale encoding. It is similar to locale.getpreferredencoding(False) but ignores the Python UTF-8 Mode.

logging

Added getLevelNamesMapping() to return a mapping from logging level names (e.g. 'CRITICAL') to the values of their corresponding ロギングレベル (e.g. 50, by default). (Contributed by Andrei Kulakovin in gh-88024 [https://github.com/python/cpython/issues/88024].)

Added a createSocket() method to SysLogHandler, to match SocketHandler.createSocket(). It is called automatically during handler initialization and when emitting an event, if there is no active socket. (Contributed by Kirill Pinchuk in gh-88457 [https://github.com/python/cpython/issues/88457].)

math

Add math.exp2(): return 2 raised to the power of x. (Contributed by Gideon Mitchell in bpo-45917 [https://bugs.python.org/issue?@action=redirect&bpo=45917].)

Add math.cbrt(): return the cube root of x. (Contributed by Ajith Ramachandran in bpo-44357 [https://bugs.python.org/issue?@action=redirect&bpo=44357].)

The behaviour of two math.pow() corner cases was changed, for consistency with the IEEE 754 specification. The operations math.pow(0.0, -math.inf) and math.pow(-0.0, -math.inf) now return inf. Previously they raised ValueError. (Contributed by Mark Dickinson in bpo-44339 [https://bugs.python.org/issue?@action=redirect&bpo=44339].)

The math.nan value is now always available. (Contributed by Victor Stinner in bpo-46917 [https://bugs.python.org/issue?@action=redirect&bpo=46917].)

operator

A new function operator.call has been added, such that operator.call(obj, *args, **kwargs) == obj(*args, **kwargs). (Contributed by Antony Lee in bpo-44019 [https://bugs.python.org/issue?@action=redirect&bpo=44019].)

os

On Windows, os.urandom() now uses BCryptGenRandom(), instead of CryptGenRandom() which is deprecated. (Contributed by Donghee Na in bpo-44611 [https://bugs.python.org/issue?@action=redirect&bpo=44611].)

pathlib

glob() and rglob() return only directories if pattern ends with a pathname components separator: sep or altsep. (Contributed by Eisuke Kawasima in bpo-22276 [https://bugs.python.org/issue?@action=redirect&bpo=22276] and bpo-33392 [https://bugs.python.org/issue?@action=redirect&bpo=33392].)

re

Atomic grouping ((?>...)) and possessive quantifiers (*+, ++, ?+, {m,n}+) are now supported in regular expressions. (Contributed by Jeffrey C. Jacobs and Serhiy Storchaka in bpo-433030 [https://bugs.python.org/issue?@action=redirect&bpo=433030].)

shutil

Add optional parameter dir_fd in shutil.rmtree(). (Contributed by Serhiy Storchaka in bpo-46245 [https://bugs.python.org/issue?@action=redirect&bpo=46245].)

socket

Add CAN Socket support for NetBSD. (Contributed by Thomas Klausner in bpo-30512 [https://bugs.python.org/issue?@action=redirect&bpo=30512].)

create_connection() has an option to raise, in case of failure to connect, an ExceptionGroup containing all errors instead of only raising the last error. (Contributed by Irit Katriel in bpo-29980 [https://bugs.python.org/issue?@action=redirect&bpo=29980].)

sqlite3

You can now disable the authorizer by passing None to set_authorizer(). (Contributed by Erlend E. Aasland in bpo-44491 [https://bugs.python.org/issue?@action=redirect&bpo=44491].)

Collation name create_collation() can now contain any Unicode character. Collation names with invalid characters now raise UnicodeEncodeError instead of sqlite3.ProgrammingError. (Contributed by Erlend E. Aasland in bpo-44688 [https://bugs.python.org/issue?@action=redirect&bpo=44688].)

sqlite3 exceptions now include the SQLite extended error code as sqlite_errorcode and the SQLite error name as sqlite_errorname. (Contributed by Aviv Palivoda, Daniel Shahaf, and Erlend E. Aasland in bpo-16379 [https://bugs.python.org/issue?@action=redirect&bpo=16379] and bpo-24139 [https://bugs.python.org/issue?@action=redirect&bpo=24139].)

Add setlimit() and getlimit() to sqlite3.Connection for setting and getting SQLite limits by connection basis. (Contributed by Erlend E. Aasland in bpo-45243 [https://bugs.python.org/issue?@action=redirect&bpo=45243].)

sqlite3 now sets sqlite3.threadsafety based on the default threading mode the underlying SQLite library has been compiled with. (Contributed by Erlend E. Aasland in bpo-45613 [https://bugs.python.org/issue?@action=redirect&bpo=45613].)

sqlite3 C callbacks now use unraisable exceptions if callback tracebacks are enabled. Users can now register an unraisable hook handler to improve their debug experience. (Contributed by Erlend E. Aasland in bpo-45828 [https://bugs.python.org/issue?@action=redirect&bpo=45828].)

Fetch across rollback no longer raises InterfaceError. Instead we leave it to the SQLite library to handle these cases. (Contributed by Erlend E. Aasland in bpo-44092 [https://bugs.python.org/issue?@action=redirect&bpo=44092].)

Add serialize() and deserialize() to sqlite3.Connection for serializing and deserializing databases. (Contributed by Erlend E. Aasland in bpo-41930 [https://bugs.python.org/issue?@action=redirect&bpo=41930].)

Add create_window_function() to sqlite3.Connection for creating aggregate window functions. (Contributed by Erlend E. Aasland in bpo-34916 [https://bugs.python.org/issue?@action=redirect&bpo=34916].)

Add blobopen() to sqlite3.Connection. sqlite3.Blob allows incremental I/O operations on blobs. (Contributed by Aviv Palivoda and Erlend E. Aasland in bpo-24905 [https://bugs.python.org/issue?@action=redirect&bpo=24905].)

string

Add get_identifiers() and is_valid() to string.Template, which respectively return all valid placeholders, and whether any invalid placeholders are present. (Contributed by Ben Kehoe in gh-90465 [https://github.com/python/cpython/issues/90465].)

sys

sys.exc_info() now derives the type and traceback fields from the 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 exc_info(). (Contributed by Irit Katriel in bpo-45711 [https://bugs.python.org/issue?@action=redirect&bpo=45711].)

Add sys.exception() which returns the active exception instance (equivalent to sys.exc_info()[1]). (Contributed by Irit Katriel in bpo-46328 [https://bugs.python.org/issue?@action=redirect&bpo=46328].)

Add the sys.flags.safe_path flag. (Contributed by Victor Stinner in gh-57684 [https://github.com/python/cpython/issues/57684].)

sysconfig

Three new installation schemes (posix_venv, nt_venv and venv) were added and are used when Python creates new virtual environments or when it is running from a virtual environment. The first two schemes (posix_venv and nt_venv) are OS-specific for non-Windows and Windows, the venv is essentially an alias to one of them according to the OS Python runs on. This is useful for downstream distributors who modify sysconfig.get_preferred_scheme(). Third party code that creates new virtual environments should use the new venv installation scheme to determine the paths, as does venv. (Contributed by Miro Hrončok in bpo-45413 [https://bugs.python.org/issue?@action=redirect&bpo=45413].)

tempfile

SpooledTemporaryFile objects now fully implement the methods of io.BufferedIOBase or io.TextIOBase (depending on file mode). This lets them work correctly with APIs that expect file-like objects, such as compression modules. (Contributed by Carey Metcalfe in gh-70363 [https://github.com/python/cpython/issues/70363].)

threading

On Unix, if the sem_clockwait() function is available in the C library (glibc 2.30 and newer), the threading.Lock.acquire() method now uses the monotonic clock (time.CLOCK_MONOTONIC) for the timeout, rather than using the system clock (time.CLOCK_REALTIME), to not be affected by system clock changes. (Contributed by Victor Stinner in bpo-41710 [https://bugs.python.org/issue?@action=redirect&bpo=41710].)

time

On Unix, time.sleep() now uses the clock_nanosleep() or nanosleep() function, if available, which has a resolution of 1 nanosecond (10⁻⁹ seconds), rather than using select() which has a resolution of 1 microsecond (10⁻⁶ seconds). (Contributed by Benjamin Szőke and Victor Stinner in bpo-21302 [https://bugs.python.org/issue?@action=redirect&bpo=21302].)

On Windows 8.1 and newer, time.sleep() now uses a waitable timer based on high-resolution timers [https://docs.microsoft.com/en-us/windows-hardware/drivers/kernel/high-resolution-timers] which has a resolution of 100 nanoseconds (10⁻⁷ seconds). Previously, it had a resolution of 1 millisecond (10⁻³ seconds). (Contributed by Benjamin Szőke, Donghee Na, Eryk Sun and Victor Stinner in bpo-21302 [https://bugs.python.org/issue?@action=redirect&bpo=21302] and bpo-45429 [https://bugs.python.org/issue?@action=redirect&bpo=45429].)

tkinter

Added method info_patchlevel() which returns the exact version of the Tcl library as a named tuple similar to sys.version_info. (Contributed by Serhiy Storchaka in gh-91827 [https://github.com/python/cpython/issues/91827].)

traceback

Add traceback.StackSummary.format_frame_summary() to allow users to override which frames appear in the traceback, and how they are formatted. (Contributed by Ammar Askar in bpo-44569 [https://bugs.python.org/issue?@action=redirect&bpo=44569].)

Add traceback.TracebackException.print(), which prints the formatted TracebackException instance to a file. (Contributed by Irit Katriel in bpo-33809 [https://bugs.python.org/issue?@action=redirect&bpo=33809].)

typing

For major changes, see 型ヒントに関連する新しい機能.

Add typing.assert_never() and typing.Never. typing.assert_never() is useful for asking a type checker to confirm that a line of code is not reachable. At runtime, it raises an AssertionError. (Contributed by Jelle Zijlstra in gh-90633 [https://github.com/python/cpython/issues/90633].)

Add typing.reveal_type(). This is useful for asking a type checker what type it has inferred for a given expression. At runtime it prints the type of the received value. (Contributed by Jelle Zijlstra in gh-90572 [https://github.com/python/cpython/issues/90572].)

Add typing.assert_type(). This is useful for asking a type checker to confirm that the type it has inferred for a given expression matches the given type. At runtime it simply returns the received value. (Contributed by Jelle Zijlstra in gh-90638 [https://github.com/python/cpython/issues/90638].)

typing.TypedDict types can now be generic. (Contributed by Samodya Abeysiriwardane in gh-89026 [https://github.com/python/cpython/issues/89026].)

NamedTuple types can now be generic. (Contributed by Serhiy Storchaka in bpo-43923 [https://bugs.python.org/issue?@action=redirect&bpo=43923].)

Allow subclassing of typing.Any. This is useful for avoiding type checker errors related to highly dynamic class, such as mocks. (Contributed by Shantanu Jain in gh-91154 [https://github.com/python/cpython/issues/91154].)

The typing.final() decorator now sets the __final__ attributed on the decorated object. (Contributed by Jelle Zijlstra in gh-90500 [https://github.com/python/cpython/issues/90500].)

The typing.get_overloads() function can be used for introspecting the overloads of a function. typing.clear_overloads() can be used to clear all registered overloads of a function. (Contributed by Jelle Zijlstra in gh-89263 [https://github.com/python/cpython/issues/89263].)

The __init__() method of Protocol subclasses is now preserved. (Contributed by Adrian Garcia Badarasco in gh-88970 [https://github.com/python/cpython/issues/88970].)

The representation of empty tuple types (Tuple[()]) is simplified. This affects introspection, e.g. get_args(Tuple[()]) now evaluates to () instead of ((),). (Contributed by Serhiy Storchaka in gh-91137 [https://github.com/python/cpython/issues/91137].)

Loosen runtime requirements for type annotations by removing the callable check in the private typing._type_check function. (Contributed by Gregory Beauregard in gh-90802 [https://github.com/python/cpython/issues/90802].)

typing.get_type_hints() now supports evaluating strings as forward references in PEP 585 generic aliases. (Contributed by Niklas Rosenstein in gh-85542 [https://github.com/python/cpython/issues/85542].)

typing.get_type_hints() no longer adds Optional to parameters with None as a default. (Contributed by Nikita Sobolev in gh-90353 [https://github.com/python/cpython/issues/90353].)

typing.get_type_hints() now supports evaluating bare stringified ClassVar annotations. (Contributed by Gregory Beauregard in gh-90711 [https://github.com/python/cpython/issues/90711].)

typing.no_type_check() no longer modifies external classes and functions. It also now correctly marks classmethods as not to be type checked. (Contributed by Nikita Sobolev in gh-90729 [https://github.com/python/cpython/issues/90729].)

unicodedata

The Unicode database has been updated to version 14.0.0. (Contributed by Benjamin Peterson in bpo-45190 [https://bugs.python.org/issue?@action=redirect&bpo=45190]).

unittest

Added methods enterContext() and enterClassContext() of class TestCase, method enterAsyncContext() of class IsolatedAsyncioTestCase and function unittest.enterModuleContext(). (Contributed by Serhiy Storchaka in bpo-45046 [https://bugs.python.org/issue?@action=redirect&bpo=45046].)

venv

When new Python virtual environments are created, the venv sysconfig installation scheme is used to determine the paths inside the environment. When Python runs in a virtual environment, the same installation scheme is the default. That means that downstream distributors can change the default sysconfig install scheme without changing behavior of virtual environments. Third party code that also creates new virtual environments should do the same. (Contributed by Miro Hrončok in bpo-45413 [https://bugs.python.org/issue?@action=redirect&bpo=45413].)

warnings

warnings.catch_warnings() now accepts arguments for warnings.simplefilter(), providing a more concise way to locally ignore warnings or convert them to errors. (Contributed by Zac Hatfield-Dodds in bpo-47074 [https://bugs.python.org/issue?@action=redirect&bpo=47074].)

zipfile

Added support for specifying member name encoding for reading metadata in a ZipFile's directory and file headers. (Contributed by Stephen J. Turnbull and Serhiy Storchaka in bpo-28080 [https://bugs.python.org/issue?@action=redirect&bpo=28080].)

Added ZipFile.mkdir() for creating new directories inside ZIP archives. (Contributed by Sam Ezeh in gh-49083 [https://github.com/python/cpython/issues/49083].)

Added stem, suffix and suffixes to zipfile.Path. (Contributed by Miguel Brito in gh-88261 [https://github.com/python/cpython/issues/88261].)

最適化

This section covers specific optimizations independent of the Faster CPython project, which is covered in its own section.

The compiler now optimizes simple printf-style % formatting on string literals containing only the format codes %s, %r and %a and makes it as fast as a corresponding f-string expression. (Contributed by Serhiy Storchaka in bpo-28307 [https://bugs.python.org/issue?@action=redirect&bpo=28307].)

Integer division (//) is better tuned for optimization by compilers. It is now around 20% faster on x86-64 when dividing an int by a value smaller than 2**30. (Contributed by Gregory P. Smith and Tim Peters in gh-90564 [https://github.com/python/cpython/issues/90564].)

sum() is now nearly 30% faster for integers smaller than 2**30. (Contributed by Stefan Behnel in gh-68264 [https://github.com/python/cpython/issues/68264].)

Resizing lists is streamlined for the common case, speeding up list.append() by ≈15% and simple list comprehensions by up to 20-30% (Contributed by Dennis Sweeney in gh-91165 [https://github.com/python/cpython/issues/91165].)

Dictionaries don't store hash values when all keys are Unicode objects, decreasing dict size. For example, sys.getsizeof(dict.fromkeys("abcdefg")) is reduced from 352 bytes to 272 bytes (23% smaller) on 64-bit platforms. (Contributed by Inada Naoki in bpo-46845 [https://bugs.python.org/issue?@action=redirect&bpo=46845].)

Using asyncio.DatagramProtocol is now orders of magnitude faster when transferring large files over UDP, with speeds over 100 times higher for a ≈60 MiB file. (Contributed by msoxzw in gh-91487 [https://github.com/python/cpython/issues/91487].)

math functions comb() and perm() are now ≈10 times faster for large arguments (with a larger speedup for larger k). (Contributed by Serhiy Storchaka in bpo-37295 [https://bugs.python.org/issue?@action=redirect&bpo=37295].)

The statistics functions mean(), variance() and stdev() now consume iterators in one pass rather than converting them to a list first. This is twice as fast and can save substantial memory. (Contributed by Raymond Hettinger in gh-90415 [https://github.com/python/cpython/issues/90415].)

unicodedata.normalize() now normalizes pure-ASCII strings in constant time. (Contributed by Donghee Na in bpo-44987 [https://bugs.python.org/issue?@action=redirect&bpo=44987].)

Faster CPython

CPython 3.11 is an average of 25% faster [https://github.com/faster-cpython/ideas#published-results] than CPython 3.10 as measured with the pyperformance [https://github.com/python/pyperformance] benchmark suite, when compiled with GCC on Ubuntu Linux. Depending on your workload, the overall speedup could be 10-60%.

This project focuses on two major areas in Python: Faster Startup and Faster Runtime. Optimizations not covered by this project are listed separately under 最適化.

Faster Startup

Frozen imports / Static code objects

Python caches bytecode in the __pycache__ directory to speed up module loading.

Previously in 3.10, Python module execution looked like this:

Read __pycache__ -> Unmarshal -> Heap allocated code object -> Evaluate

In Python 3.11, the core modules essential for Python startup are "frozen". This means that their コードオブジェクト (and bytecode) are statically allocated by the interpreter. This reduces the steps in module execution process to:

Statically allocated code object -> Evaluate

Interpreter startup is now 10-15% faster in Python 3.11. This has a big impact for short-running programs using Python.

(Contributed by Eric Snow, Guido van Rossum and Kumar Aditya in many issues.)

Faster Runtime

Cheaper, lazy Python frames

Python frames, holding execution information, are created whenever Python calls a Python function. The following are new frame optimizations:

Streamlined the frame creation process.

Avoided memory allocation by generously re-using frame space on the C stack.

Streamlined the internal frame struct to contain only essential information. Frames previously held extra debugging and memory management information.

Old-style frame objects are now created only when requested by debuggers or by Python introspection functions such as sys._getframe() and inspect.currentframe(). For most user code, no frame objects are created at all. As a result, nearly all Python functions calls have sped up significantly. We measured a 3-7% speedup in pyperformance.

(Contributed by Mark Shannon in bpo-44590 [https://bugs.python.org/issue?@action=redirect&bpo=44590].)

Inlined Python function calls

During a Python function call, Python will call an evaluating C function to interpret that function's code. This effectively limits pure Python recursion to what's safe for the C stack.

In 3.11, when CPython detects Python code calling another Python function, it sets up a new frame, and "jumps" to the new code inside the new frame. This avoids calling the C interpreting function altogether.

Most Python function calls now consume no C stack space, speeding them up. In simple recursive functions like fibonacci or factorial, we observed a 1.7x speedup. This also means recursive functions can recurse significantly deeper (if the user increases the recursion limit with sys.setrecursionlimit()). We measured a 1-3% improvement in pyperformance.

(Contributed by Pablo Galindo and Mark Shannon in bpo-45256 [https://bugs.python.org/issue?@action=redirect&bpo=45256].)

PEP 659: Specializing Adaptive Interpreter

PEP 659 [https://peps.python.org/pep-0659/] is one of the key parts of the Faster CPython project. The general idea is that while Python is a dynamic language, most code has regions where objects and types rarely change. This concept is known as type stability.

At runtime, Python will try to look for common patterns and type stability in the executing code. Python will then replace the current operation with a more specialized one. This specialized operation uses fast paths available only to those use cases/types, which generally outperform their generic counterparts. This also brings in another concept called inline caching, where Python caches the results of expensive operations directly in the bytecode.

The specializer will also combine certain common instruction pairs into one superinstruction, reducing the overhead during execution.

Python will only specialize when it sees code that is "hot" (executed multiple times). This prevents Python from wasting time on run-once code. Python can also de-specialize when code is too dynamic or when the use changes. Specialization is attempted periodically, and specialization attempts are not too expensive, allowing specialization to adapt to new circumstances.

(PEP written by Mark Shannon, with ideas inspired by Stefan Brunthaler. See PEP 659 [https://peps.python.org/pep-0659/] for more information. Implementation by Mark Shannon and Brandt Bucher, with additional help from Irit Katriel and Dennis Sweeney.)

演算

形式

Specialization

Operation speedup (up to)

Contributor(s)

Binary operations

x + x

x - x

x * x

Binary add, multiply and subtract for common types such as int, float and str take custom fast paths for their underlying types.

10%

Mark Shannon, Donghee Na, Brandt Bucher, Dennis Sweeney

Subscript

a[i]

Subscripting container types such as list, tuple and dict directly index the underlying data structures.

Subscripting custom __getitem__() is also inlined similar to Inlined Python function calls.

10-25%

Irit Katriel, Mark Shannon

Store subscript

a[i] = z

Similar to subscripting specialization above.

10-25%

Dennis Sweeney

呼び出し (call)

f(arg)

C(arg)

Calls to common builtin (C) functions and types such as len() and str directly call their underlying C version. This avoids going through the internal calling convention.

20%

Mark Shannon, Ken Jin

Load global variable

print

len

The object's index in the globals/builtins namespace is cached. Loading globals and builtins require zero namespace lookups.

[1]

Mark Shannon

Load attribute

o.attr

Similar to loading global variables. The attribute's index inside the class/object's namespace is cached. In most cases, attribute loading will require zero namespace lookups.

[2]

Mark Shannon

Load methods for call

o.meth()

The actual address of the method is cached. Method loading now has no namespace lookups -- even for classes with long inheritance chains.

10-20%

Ken Jin, Mark Shannon

Store attribute

o.attr = z

Similar to load attribute optimization.

2% in pyperformance

Mark Shannon

Unpack Sequence

*seq

Specialized for common containers such as list and tuple. Avoids internal calling convention.

8%

Brandt Bucher

[1]

A similar optimization already existed since Python 3.8. 3.11 specializes for more forms and reduces some overhead.

[2]

A similar optimization already existed since Python 3.10. 3.11 specializes for more forms. Furthermore, all attribute loads should be sped up by bpo-45947 [https://bugs.python.org/issue?@action=redirect&bpo=45947].

Misc

Objects now require less memory due to lazily created object namespaces. Their namespace dictionaries now also share keys more freely. (Contributed Mark Shannon in bpo-45340 [https://bugs.python.org/issue?@action=redirect&bpo=45340] and bpo-40116 [https://bugs.python.org/issue?@action=redirect&bpo=40116].)

"Zero-cost" exceptions are implemented, eliminating the cost of try statements when no exception is raised. (Contributed by Mark Shannon in bpo-40222 [https://bugs.python.org/issue?@action=redirect&bpo=40222].)

A more concise representation of exceptions in the interpreter reduced the time required for catching an exception by about 10%. (Contributed by Irit Katriel in bpo-45711 [https://bugs.python.org/issue?@action=redirect&bpo=45711].)

re's regular expression matching engine has been partially refactored, and now uses computed gotos (or "threaded code") on supported platforms. As a result, Python 3.11 executes the pyperformance regular expression benchmarks [https://pyperformance.readthedocs.io/benchmarks.html#regex-dna] up to 10% faster than Python 3.10. (Contributed by Brandt Bucher in gh-91404 [https://github.com/python/cpython/issues/91404].)

FAQ

How should I write my code to utilize these speedups?

Write Pythonic code that follows common best practices; you don't have to change your code. The Faster CPython project optimizes for common code patterns we observe.

Will CPython 3.11 use more memory?

Maybe not; we don't expect memory use to exceed 20% higher than 3.10. This is offset by memory optimizations for frame objects and object dictionaries as mentioned above.

I don't see any speedups in my workload. Why?

Certain code won't have noticeable benefits. If your code spends most of its time on I/O operations, or already does most of its computation in a C extension library like NumPy, there won't be significant speedups. This project currently benefits pure-Python workloads the most.

Furthermore, the pyperformance figures are a geometric mean. Even within the pyperformance benchmarks, certain benchmarks have slowed down slightly, while others have sped up by nearly 2x!

Is there a JIT compiler?

No. We're still exploring other optimizations.

About

Faster CPython explores optimizations for CPython. The main team is funded by Microsoft to work on this full-time. Pablo Galindo Salgado is also funded by Bloomberg LP to work on the project part-time. Finally, many contributors are volunteers from the community.

CPython バイトコードの変更

The bytecode now contains inline cache entries, which take the form of the newly-added CACHE instructions. Many opcodes expect to be followed by an exact number of caches, and instruct the interpreter to skip over them at runtime. Populated caches can look like arbitrary instructions, so great care should be taken when reading or modifying raw, adaptive bytecode containing quickened data.

New opcodes

ASYNC_GEN_WRAP, RETURN_GENERATOR and SEND, used in generators and co-routines.

COPY_FREE_VARS, which avoids needing special caller-side code for closures.

JUMP_BACKWARD_NO_INTERRUPT, for use in certain loops where handling interrupts is undesirable.

MAKE_CELL, to create セルオブジェクト (cell object).

CHECK_EG_MATCH and PREP_RERAISE_STAR, to handle the new exception groups and except* added in PEP 654 [https://peps.python.org/pep-0654/].

PUSH_EXC_INFO, for use in exception handlers.

RESUME, a no-op, for internal tracing, debugging and optimization checks.

Replaced opcodes

Replaced Opcode(s)

New Opcode(s)

注釈

BINARY_*

INPLACE_*

BINARY_OP

Replaced all numeric binary/in-place opcodes with a single opcode

CALL_FUNCTION

CALL_FUNCTION_KW

CALL_METHOD

CALL

KW_NAMES

PRECALL

PUSH_NULL

Decouples argument shifting for methods from handling of keyword arguments; allows better specialization of calls

DUP_TOP

DUP_TOP_TWO

ROT_TWO

ROT_THREE

ROT_FOUR

ROT_N

COPY

SWAP

Stack manipulation instructions

JUMP_IF_NOT_EXC_MATCH

CHECK_EXC_MATCH

Now performs check but doesn't jump

JUMP_ABSOLUTE

POP_JUMP_IF_FALSE

POP_JUMP_IF_TRUE

JUMP_BACKWARD

POP_JUMP_BACKWARD_IF_*

POP_JUMP_FORWARD_IF_*

See [3]; TRUE, FALSE, NONE and NOT_NONE variants for each direction

SETUP_WITH

SETUP_ASYNC_WITH

BEFORE_WITH

with block setup

[3]

All jump opcodes are now relative, including the existing JUMP_IF_TRUE_OR_POP and JUMP_IF_FALSE_OR_POP. The argument is now an offset from the current instruction rather than an absolute location.

Changed/removed opcodes

Changed MATCH_CLASS and MATCH_KEYS to no longer push an additional boolean value to indicate success/failure. Instead, None is pushed on failure in place of the tuple of extracted values.

Changed opcodes that work with exceptions to reflect them now being represented as one item on the stack instead of three (see gh-89874 [https://github.com/python/cpython/issues/89874]).

Removed COPY_DICT_WITHOUT_KEYS, GEN_START, POP_BLOCK, SETUP_FINALLY and YIELD_FROM.

非推奨

This section lists Python APIs that have been deprecated in Python 3.11.

Deprecated C APIs are listed separately.

Language/Builtins

Chaining classmethod descriptors (introduced in bpo-19072 [https://bugs.python.org/issue?@action=redirect&bpo=19072]) is now deprecated. It can no longer be used to wrap other descriptors such as property. The core design of this feature was flawed and caused a number of downstream problems. To "pass-through" a classmethod, consider using the __wrapped__ attribute that was added in Python 3.10. (Contributed by Raymond Hettinger in gh-89519 [https://github.com/python/cpython/issues/89519].)

Octal escapes in string and bytes literals with values larger than 0o377 (255 in decimal) now produce a DeprecationWarning. In a future Python version, they will raise a SyntaxWarning and eventually a SyntaxError. (Contributed by Serhiy Storchaka in gh-81548 [https://github.com/python/cpython/issues/81548].)

The delegation of int() to __trunc__() is now deprecated. Calling int(a) when type(a) implements __trunc__() but not __int__() or __index__() now raises a DeprecationWarning. (Contributed by Zackery Spytz in bpo-44977 [https://bugs.python.org/issue?@action=redirect&bpo=44977].)

モジュール

PEP 594 [https://peps.python.org/pep-0594/] led to the deprecations of the following modules slated for removal in Python 3.13:

aifc

chunk

msilib

pipes

telnetlib

audioop

crypt

nis

sndhdr

uu

cgi

imghdr

nntplib

spwd

xdrlib

cgitb

mailcap

ossaudiodev

sunau

(Contributed by Brett Cannon in bpo-47061 [https://bugs.python.org/issue?@action=redirect&bpo=47061] and Victor Stinner in gh-68966 [https://github.com/python/cpython/issues/68966].)

The asynchat, asyncore and smtpd modules have been deprecated since at least Python 3.6. Their documentation and deprecation warnings have now been updated to note they will be removed in Python 3.12. (Contributed by Hugo van Kemenade in bpo-47022 [https://bugs.python.org/issue?@action=redirect&bpo=47022].)

The lib2to3 package and 2to3 tool are now deprecated and may not be able to parse Python 3.10 or newer. See PEP 617 [https://peps.python.org/pep-0617/], introducing the new PEG parser, for details. (Contributed by Victor Stinner in bpo-40360 [https://bugs.python.org/issue?@action=redirect&bpo=40360].)

Undocumented modules sre_compile, sre_constants and sre_parse are now deprecated. (Contributed by Serhiy Storchaka in bpo-47152 [https://bugs.python.org/issue?@action=redirect&bpo=47152].)

Standard Library

The following have been deprecated in configparser since Python 3.2. Their deprecation warnings have now been updated to note they will be removed in Python 3.12:

the configparser.SafeConfigParser class

the configparser.ParsingError.filename property

the configparser.RawConfigParser.readfp() method

(Contributed by Hugo van Kemenade in bpo-45173 [https://bugs.python.org/issue?@action=redirect&bpo=45173].)

configparser.LegacyInterpolation has been deprecated in the docstring since Python 3.2, and is not listed in the configparser documentation. It now emits a DeprecationWarning and will be removed in Python 3.13. Use configparser.BasicInterpolation or configparser.ExtendedInterpolation instead. (Contributed by Hugo van Kemenade in bpo-46607 [https://bugs.python.org/issue?@action=redirect&bpo=46607].)

The older set of importlib.resources functions were deprecated in favor of the replacements added in Python 3.9 and will be removed in a future Python version, due to not supporting resources located within package subdirectories:

importlib.resources.contents()

importlib.resources.is_resource()

importlib.resources.open_binary()

importlib.resources.open_text()

importlib.resources.read_binary()

importlib.resources.read_text()

importlib.resources.path()

The locale.getdefaultlocale() function is deprecated and will be removed in Python 3.15. Use locale.setlocale(), locale.getpreferredencoding(False) and locale.getlocale() functions instead. (Contributed by Victor Stinner in gh-90817 [https://github.com/python/cpython/issues/90817].)

The locale.resetlocale() function is deprecated and will be removed in Python 3.13. Use locale.setlocale(locale.LC_ALL, "") instead. (Contributed by Victor Stinner in gh-90817 [https://github.com/python/cpython/issues/90817].)

Stricter rules will now be applied for numerical group references and group names in regular expressions. Only sequences of ASCII digits will now be accepted as a numerical reference, and the group name in bytes patterns and replacement strings can only contain ASCII letters, digits and underscores. For now, a deprecation warning is raised for syntax violating these rules. (Contributed by Serhiy Storchaka in gh-91760 [https://github.com/python/cpython/issues/91760].)

In the re module, the re.template() function and the corresponding re.TEMPLATE and re.T flags are deprecated, as they were undocumented and lacked an obvious purpose. They will be removed in Python 3.13. (Contributed by Serhiy Storchaka and Miro Hrončok in gh-92728 [https://github.com/python/cpython/issues/92728].)

turtle.settiltangle() has been deprecated since Python 3.1; it now emits a deprecation warning and will be removed in Python 3.13. Use turtle.tiltangle() instead (it was earlier incorrectly marked as deprecated, and its docstring is now corrected). (Contributed by Hugo van Kemenade in bpo-45837 [https://bugs.python.org/issue?@action=redirect&bpo=45837].)

typing.Text, which exists solely to provide compatibility support between Python 2 and Python 3 code, is now deprecated. Its removal is currently unplanned, but users are encouraged to use str instead wherever possible. (Contributed by Alex Waygood in gh-92332 [https://github.com/python/cpython/issues/92332].)

The keyword argument syntax for constructing typing.TypedDict types is now deprecated. Support will be removed in Python 3.13. (Contributed by Jingchen Ye in gh-90224 [https://github.com/python/cpython/issues/90224].)

webbrowser.MacOSX is deprecated and will be removed in Python 3.13. It is untested, undocumented, and not used by webbrowser itself. (Contributed by Donghee Na in bpo-42255 [https://bugs.python.org/issue?@action=redirect&bpo=42255].)

The behavior of returning a value from a TestCase and IsolatedAsyncioTestCase test methods (other than the default None value) is now deprecated.

Deprecated the following not-formally-documented unittest functions, scheduled for removal in Python 3.13:

unittest.findTestCases()

unittest.makeSuite()

unittest.getTestCaseNames()

Use TestLoader methods instead:

unittest.TestLoader.loadTestsFromModule()

unittest.TestLoader.loadTestsFromTestCase()

unittest.TestLoader.getTestCaseNames()

(Contributed by Erlend E. Aasland in bpo-5846 [https://bugs.python.org/issue?@action=redirect&bpo=5846].)

unittest.TestProgram.usageExit() is marked deprecated, to be removed in 3.13. (Contributed by Carlos Damázio in gh-67048 [https://github.com/python/cpython/issues/67048].)

Pending Removal in Python 3.12

The following Python APIs have been deprecated in earlier Python releases, and will be removed in Python 3.12.

C APIs pending removal are listed separately.

The asynchat module

The asyncore module

The entire distutils package

The imp module

The typing.io namespace

The typing.re namespace

cgi.log()

importlib.find_loader()

importlib.abc.Loader.module_repr()

importlib.abc.MetaPathFinder.find_module()

importlib.abc.PathEntryFinder.find_loader()

importlib.abc.PathEntryFinder.find_module()

importlib.machinery.BuiltinImporter.find_module()

importlib.machinery.BuiltinLoader.module_repr()

importlib.machinery.FileFinder.find_loader()

importlib.machinery.FileFinder.find_module()

importlib.machinery.FrozenImporter.find_module()

importlib.machinery.FrozenLoader.module_repr()

importlib.machinery.PathFinder.find_module()

importlib.machinery.WindowsRegistryFinder.find_module()

importlib.util.module_for_loader()

importlib.util.set_loader_wrapper()

importlib.util.set_package_wrapper()

pkgutil.ImpImporter

pkgutil.ImpLoader

pathlib.Path.link_to()

sqlite3.enable_shared_cache()

sqlite3.OptimizedUnicode()

PYTHONTHREADDEBUG environment variable

The following deprecated aliases in unittest:

非推奨のエイリアス

メソッド名

非推奨となるバージョン

failUnless

assertTrue()

3.1

failIf

assertFalse()

3.1

failUnlessEqual

assertEqual()

3.1

failIfEqual

assertNotEqual()

3.1

failUnlessAlmostEqual

assertAlmostEqual()

3.1

failIfAlmostEqual

assertNotAlmostEqual()

3.1

failUnlessRaises

assertRaises()

3.1

assert_

assertTrue()

3.2

assertEquals

assertEqual()

3.2

assertNotEquals

assertNotEqual()

3.2

assertAlmostEquals

assertAlmostEqual()

3.2

assertNotAlmostEquals

assertNotAlmostEqual()

3.2

assertRegexpMatches

assertRegex()

3.2

assertRaisesRegexp

assertRaisesRegex()

3.2

assertNotRegexpMatches

assertNotRegex()

3.5

削除

This section lists Python APIs that have been removed in Python 3.11.

Removed C APIs are listed separately.

Removed the @asyncio.coroutine() decorator enabling legacy generator-based coroutines to be compatible with async / await code. The function has been deprecated since Python 3.8 and the removal was initially scheduled for Python 3.10. Use async def instead. (Contributed by Illia Volochii in bpo-43216 [https://bugs.python.org/issue?@action=redirect&bpo=43216].)

Removed asyncio.coroutines.CoroWrapper used for wrapping legacy generator-based coroutine objects in the debug mode. (Contributed by Illia Volochii in bpo-43216 [https://bugs.python.org/issue?@action=redirect&bpo=43216].)

Due to significant security concerns, the reuse_address parameter of asyncio.loop.create_datagram_endpoint(), disabled in Python 3.9, is now entirely removed. This is because of the behavior of the socket option SO_REUSEADDR in UDP. (Contributed by Hugo van Kemenade in bpo-45129 [https://bugs.python.org/issue?@action=redirect&bpo=45129].)

Removed the binhex module, deprecated in Python 3.9. Also removed the related, similarly-deprecated binascii functions:

binascii.a2b_hqx()

binascii.b2a_hqx()

binascii.rlecode_hqx()

binascii.rldecode_hqx()

The binascii.crc_hqx() function remains available.

(Contributed by Victor Stinner in bpo-45085 [https://bugs.python.org/issue?@action=redirect&bpo=45085].)

Removed the distutils bdist_msi command deprecated in Python 3.9. Use bdist_wheel (wheel packages) instead. (Contributed by Hugo van Kemenade in bpo-45124 [https://bugs.python.org/issue?@action=redirect&bpo=45124].)

Removed the __getitem__() methods of xml.dom.pulldom.DOMEventStream, wsgiref.util.FileWrapper and fileinput.FileInput, deprecated since Python 3.9. (Contributed by Hugo van Kemenade in bpo-45132 [https://bugs.python.org/issue?@action=redirect&bpo=45132].)

Removed the deprecated gettext functions lgettext(), ldgettext(), lngettext() and ldngettext(). Also removed the bind_textdomain_codeset() function, the NullTranslations.output_charset() and NullTranslations.set_output_charset() methods, and the codeset parameter of translation() and install(), since they are only used for the l*gettext() functions. (Contributed by Donghee Na and Serhiy Storchaka in bpo-44235 [https://bugs.python.org/issue?@action=redirect&bpo=44235].)

Removed from the inspect module:

The getargspec() function, deprecated since Python 3.0; use inspect.signature() or inspect.getfullargspec() instead.

The formatargspec() function, deprecated since Python 3.5; use the inspect.signature() function or the inspect.Signature object directly.

The undocumented Signature.from_builtin() and Signature.from_function() methods, deprecated since Python 3.5; use the Signature.from_callable() method instead.

(Contributed by Hugo van Kemenade in bpo-45320 [https://bugs.python.org/issue?@action=redirect&bpo=45320].)

Removed the __class_getitem__() method from pathlib.PurePath, because it was not used and added by mistake in previous versions. (Contributed by Nikita Sobolev in bpo-46483 [https://bugs.python.org/issue?@action=redirect&bpo=46483].)

Removed the MailmanProxy class in the smtpd module, as it is unusable without the external mailman package. (Contributed by Donghee Na in bpo-35800 [https://bugs.python.org/issue?@action=redirect&bpo=35800].)

Removed the deprecated split() method of _tkinter.TkappType. (Contributed by Erlend E. Aasland in bpo-38371 [https://bugs.python.org/issue?@action=redirect&bpo=38371].)

Removed namespace package support from unittest discovery. It was introduced in Python 3.4 but has been broken since Python 3.7. (Contributed by Inada Naoki in bpo-23882 [https://bugs.python.org/issue?@action=redirect&bpo=23882].)

Removed the undocumented private float.__set_format__() method, previously known as float.__setformat__() in Python 3.7. Its docstring said: "You probably don't want to use this function. It exists mainly to be used in Python's test suite." (Contributed by Victor Stinner in bpo-46852 [https://bugs.python.org/issue?@action=redirect&bpo=46852].)

The --experimental-isolated-subinterpreters configure flag (and corresponding EXPERIMENTAL_ISOLATED_SUBINTERPRETERS macro) have been removed.

Pynche [https://pypi.org/project/Pynche/] --- The Pythonically Natural Color and Hue Editor --- has been moved out of Tools/scripts and is being developed independently [https://gitlab.com/warsaw/pynche/-/tree/main] from the Python source tree.

Porting to Python 3.11

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

Porting notes for the C API are listed separately.

open(), io.open(), codecs.open() and fileinput.FileInput no longer accept 'U' ("universal newline") in the file mode. In Python 3, "universal newline" mode is used by default whenever a file is opened in text mode, and the 'U' flag has been deprecated since Python 3.3. The newline parameter to these functions controls how universal newlines work. (Contributed by Victor Stinner in bpo-37330 [https://bugs.python.org/issue?@action=redirect&bpo=37330].)

ast.AST node positions are now validated when provided to compile() and other related functions. If invalid positions are detected, a ValueError will be raised. (Contributed by Pablo Galindo in gh-93351 [https://github.com/python/cpython/issues/93351])

Prohibited passing non-concurrent.futures.ThreadPoolExecutor executors to asyncio.loop.set_default_executor() following a deprecation in Python 3.8. (Contributed by Illia Volochii in bpo-43234 [https://bugs.python.org/issue?@action=redirect&bpo=43234].)

calendar: The calendar.LocaleTextCalendar and calendar.LocaleHTMLCalendar classes now use locale.getlocale(), instead of using locale.getdefaultlocale(), if no locale is specified. (Contributed by Victor Stinner in bpo-46659 [https://bugs.python.org/issue?@action=redirect&bpo=46659].)

The pdb module now reads the .pdbrc configuration file with the 'UTF-8' encoding. (Contributed by Srinivas Reddy Thatiparthy (శ్రీనివాస్ రెడ్డి తాటిపర్తి) in bpo-41137 [https://bugs.python.org/issue?@action=redirect&bpo=41137].)

The population parameter of random.sample() must be a sequence, and automatic conversion of sets to lists is no longer supported. Also, if the sample size is larger than the population size, a ValueError is raised. (Contributed by Raymond Hettinger in bpo-40465 [https://bugs.python.org/issue?@action=redirect&bpo=40465].)

The random optional parameter of random.shuffle() was removed. It was previously an arbitrary random function to use for the shuffle; now, random.random() (its previous default) will always be used.

In re 正規表現のシンタックス, global inline flags (e.g. (?i)) can now only be used at the start of regular expressions. Using them elsewhere has been deprecated since Python 3.6. (Contributed by Serhiy Storchaka in bpo-47066 [https://bugs.python.org/issue?@action=redirect&bpo=47066].)

In the re module, several long-standing bugs where fixed that, in rare cases, could cause capture groups to get the wrong result. Therefore, this could change the captured output in these cases. (Contributed by Ma Lin in bpo-35859 [https://bugs.python.org/issue?@action=redirect&bpo=35859].)

Build Changes

CPython now has PEP 11 [https://peps.python.org/pep-0011/] Tier 3 support [https://peps.python.org/pep-0011/#tier-3] for cross compiling to the WebAssembly [https://webassembly.org/] platforms Emscripten [https://emscripten.org/] (wasm32-unknown-emscripten, i.e. Python in the browser) and WebAssembly System Interface (WASI) [https://wasi.dev/] (wasm32-unknown-wasi). The effort is inspired by previous work like Pyodide [https://pyodide.org/]. These platforms provide a limited subset of POSIX APIs; Python standard libraries features and modules related to networking, processes, threading, signals, mmap, and users/groups are not available or don't work. (Emscripten contributed by Christian Heimes and Ethan Smith in gh-84461 [https://github.com/python/cpython/issues/84461] and WASI contributed by Christian Heimes in gh-90473 [https://github.com/python/cpython/issues/90473]; platforms promoted in gh-95085 [https://github.com/python/cpython/issues/95085])

Building CPython now requires:

A C11 [https://en.cppreference.com/w/c/11] compiler and standard library. Optional C11 features [https://en.wikipedia.org/wiki/C11_(C_standard_revision)#Optional_features] are not required. (Contributed by Victor Stinner in bpo-46656 [https://bugs.python.org/issue?@action=redirect&bpo=46656], bpo-45440 [https://bugs.python.org/issue?@action=redirect&bpo=45440] and bpo-46640 [https://bugs.python.org/issue?@action=redirect&bpo=46640].)

Support for IEEE 754 [https://en.wikipedia.org/wiki/IEEE_754] floating point numbers. (Contributed by Victor Stinner in bpo-46917 [https://bugs.python.org/issue?@action=redirect&bpo=46917].)

The Py_NO_NAN macro has been removed. Since CPython now requires IEEE 754 floats, NaN values are always available. (Contributed by Victor Stinner in bpo-46656 [https://bugs.python.org/issue?@action=redirect&bpo=46656].)

The tkinter package now requires Tcl/Tk [https://www.tcl.tk] version 8.5.12 or newer. (Contributed by Serhiy Storchaka in bpo-46996 [https://bugs.python.org/issue?@action=redirect&bpo=46996].)

Build dependencies, compiler flags, and linker flags for most stdlib extension modules are now detected by configure. libffi, libnsl, libsqlite3, zlib, bzip2, liblzma, libcrypt, Tcl/Tk, and uuid flags are detected by pkg-config [https://www.freedesktop.org/wiki/Software/pkg-config/] (when available). tkinter now requires a pkg-config command to detect development settings for Tcl/Tk [https://www.tcl.tk] headers and libraries. (Contributed by Christian Heimes and Erlend Egeberg Aasland in bpo-45847 [https://bugs.python.org/issue?@action=redirect&bpo=45847], bpo-45747 [https://bugs.python.org/issue?@action=redirect&bpo=45747], and bpo-45763 [https://bugs.python.org/issue?@action=redirect&bpo=45763].)

libpython is no longer linked against libcrypt. (Contributed by Mike Gilbert in bpo-45433 [https://bugs.python.org/issue?@action=redirect&bpo=45433].)

CPython can now be built with the ThinLTO [https://clang.llvm.org/docs/ThinLTO.html] option via passing thin to --with-lto, i.e. --with-lto=thin. (Contributed by Donghee Na and Brett Holman in bpo-44340 [https://bugs.python.org/issue?@action=redirect&bpo=44340].)

Freelists for object structs can now be disabled. A new configure option --without-freelists can be used to disable all freelists except empty tuple singleton. (Contributed by Christian Heimes in bpo-45522 [https://bugs.python.org/issue?@action=redirect&bpo=45522].)

Modules/Setup and Modules/makesetup have been improved and tied up. Extension modules can now be built through makesetup. All except some test modules can be linked statically into a main binary or library. (Contributed by Brett Cannon and Christian Heimes in bpo-45548 [https://bugs.python.org/issue?@action=redirect&bpo=45548], bpo-45570 [https://bugs.python.org/issue?@action=redirect&bpo=45570], bpo-45571 [https://bugs.python.org/issue?@action=redirect&bpo=45571], and bpo-43974 [https://bugs.python.org/issue?@action=redirect&bpo=43974].)

注釈

Use the environment variables TCLTK_CFLAGS and TCLTK_LIBS to manually specify the location of Tcl/Tk headers and libraries. The configure options --with-tcltk-includes and --with-tcltk-libs have been removed.

On RHEL 7 and CentOS 7 the development packages do not provide tcl.pc and tk.pc; use TCLTK_LIBS="-ltk8.5 -ltkstub8.5 -ltcl8.5". The directory Misc/rhel7 contains .pc files and instructions on how to build Python with RHEL 7's and CentOS 7's Tcl/Tk and OpenSSL.

CPython will now use 30-bit digits by default for the Python int implementation. Previously, the default was to use 30-bit digits on platforms with SIZEOF_VOID_P >= 8, and 15-bit digits otherwise. It's still possible to explicitly request use of 15-bit digits via either the --enable-big-digits option to the configure script or (for Windows) the PYLONG_BITS_IN_DIGIT variable in PC/pyconfig.h, but this option may be removed at some point in the future. (Contributed by Mark Dickinson in bpo-45569 [https://bugs.python.org/issue?@action=redirect&bpo=45569].)

C API の変更

新しい機能

Add a new PyType_GetName() function to get type's short name. (Contributed by Hai Shi in bpo-42035 [https://bugs.python.org/issue?@action=redirect&bpo=42035].)

Add a new PyType_GetQualName() function to get type's qualified name. (Contributed by Hai Shi in bpo-42035 [https://bugs.python.org/issue?@action=redirect&bpo=42035].)

Add new PyThreadState_EnterTracing() and PyThreadState_LeaveTracing() functions to the limited C API to suspend and resume tracing and profiling. (Contributed by Victor Stinner in bpo-43760 [https://bugs.python.org/issue?@action=redirect&bpo=43760].)

Added the Py_Version constant which bears the same value as PY_VERSION_HEX. (Contributed by Gabriele N. Tornetta in bpo-43931 [https://bugs.python.org/issue?@action=redirect&bpo=43931].)

Py_buffer and APIs are now part of the limited API and the stable ABI:

PyObject_CheckBuffer()

PyObject_GetBuffer()

PyBuffer_GetPointer()

PyBuffer_SizeFromFormat()

PyBuffer_ToContiguous()

PyBuffer_FromContiguous()

PyObject_CopyData()

PyBuffer_IsContiguous()

PyBuffer_FillContiguousStrides()

PyBuffer_FillInfo()

PyBuffer_Release()

PyMemoryView_FromBuffer()

bf_getbuffer and bf_releasebuffer type slots

(Contributed by Christian Heimes in bpo-45459 [https://bugs.python.org/issue?@action=redirect&bpo=45459].)

Added the PyType_GetModuleByDef() function, used to get the module in which a method was defined, in cases where this information is not available directly (via PyCMethod). (Contributed by Petr Viktorin in bpo-46613 [https://bugs.python.org/issue?@action=redirect&bpo=46613].)

Add new functions to pack and unpack C double (serialize and deserialize): PyFloat_Pack2(), PyFloat_Pack4(), PyFloat_Pack8(), PyFloat_Unpack2(), PyFloat_Unpack4() and PyFloat_Unpack8(). (Contributed by Victor Stinner in bpo-46906 [https://bugs.python.org/issue?@action=redirect&bpo=46906].)

Add new functions to get frame object attributes: PyFrame_GetBuiltins(), PyFrame_GetGenerator(), PyFrame_GetGlobals(), PyFrame_GetLasti().

Added two new functions to get and set the active exception instance: PyErr_GetHandledException() and PyErr_SetHandledException(). These are alternatives to PyErr_SetExcInfo() and PyErr_GetExcInfo() which work with the legacy 3-tuple representation of exceptions. (Contributed by Irit Katriel in bpo-46343 [https://bugs.python.org/issue?@action=redirect&bpo=46343].)

Added the PyConfig.safe_path member. (Contributed by Victor Stinner in gh-57684 [https://github.com/python/cpython/issues/57684].)

Porting to Python 3.11

Some macros have been converted to static inline functions to avoid macro pitfalls [https://gcc.gnu.org/onlinedocs/cpp/Macro-Pitfalls.html]. The change should be mostly transparent to users, as the replacement functions will cast their arguments to the expected types to avoid compiler warnings due to static type checks. However, when the limited C API is set to >=3.11, these casts are not done, and callers will need to cast arguments to their expected types. See PEP 670 [https://peps.python.org/pep-0670/] for more details. (Contributed by Victor Stinner and Erlend E. Aasland in gh-89653 [https://github.com/python/cpython/issues/89653].)

PyErr_SetExcInfo() no longer uses the type and traceback arguments, the interpreter now derives those values from the exception instance (the value argument). The function still steals references of all three arguments. (Contributed by Irit Katriel in bpo-45711 [https://bugs.python.org/issue?@action=redirect&bpo=45711].)

PyErr_GetExcInfo() now derives the type and traceback fields of the result from the exception instance (the value field). (Contributed by Irit Katriel in bpo-45711 [https://bugs.python.org/issue?@action=redirect&bpo=45711].)

_frozen has a new is_package field to indicate whether or not the frozen module is a package. Previously, a negative value in the size field was the indicator. Now only non-negative values be used for size. (Contributed by Kumar Aditya in bpo-46608 [https://bugs.python.org/issue?@action=redirect&bpo=46608].)

_PyFrameEvalFunction() now takes _PyInterpreterFrame* as its second parameter, instead of PyFrameObject*. See PEP 523 [https://peps.python.org/pep-0523/] for more details of how to use this function pointer type.

PyCode_New() and PyCode_NewWithPosOnlyArgs() now take an additional exception_table argument. Using these functions should be avoided, if at all possible. To get a custom code object: create a code object using the compiler, then get a modified version with the replace method.

PyCodeObject no longer has the co_code, co_varnames, co_cellvars and co_freevars fields. Instead, use PyCode_GetCode(), PyCode_GetVarnames(), PyCode_GetCellvars() and PyCode_GetFreevars() respectively to access them via the C API. (Contributed by Brandt Bucher in bpo-46841 [https://bugs.python.org/issue?@action=redirect&bpo=46841] and Ken Jin in gh-92154 [https://github.com/python/cpython/issues/92154] and gh-94936 [https://github.com/python/cpython/issues/94936].)

The old trashcan macros (Py_TRASHCAN_SAFE_BEGIN/Py_TRASHCAN_SAFE_END) are now deprecated. They should be replaced by the new macros Py_TRASHCAN_BEGIN and Py_TRASHCAN_END.

A tp_dealloc function that has the old macros, such as:

static void
mytype_dealloc(mytype *p)
{
    PyObject_GC_UnTrack(p);
    Py_TRASHCAN_SAFE_BEGIN(p);
    ...
    Py_TRASHCAN_SAFE_END
}

should migrate to the new macros as follows:

static void
mytype_dealloc(mytype *p)
{
    PyObject_GC_UnTrack(p);
    Py_TRASHCAN_BEGIN(p, mytype_dealloc)
    ...
    Py_TRASHCAN_END
}

Note that Py_TRASHCAN_BEGIN has a second argument which should be the deallocation function it is in.

To support older Python versions in the same codebase, you can define the following macros and use them throughout the code (credit: these were copied from the mypy codebase):

#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

The PyType_Ready() function now raises an error if a type is defined with the Py_TPFLAGS_HAVE_GC flag set but has no traverse function (PyTypeObject.tp_traverse). (Contributed by Victor Stinner in bpo-44263 [https://bugs.python.org/issue?@action=redirect&bpo=44263].)

Heap types with the Py_TPFLAGS_IMMUTABLETYPE flag can now inherit the PEP 590 [https://peps.python.org/pep-0590/] vectorcall protocol. Previously, this was only possible for static types. (Contributed by Erlend E. Aasland in bpo-43908 [https://bugs.python.org/issue?@action=redirect&bpo=43908])

Since Py_TYPE() is changed to a inline static function, Py_TYPE(obj) = new_type must be replaced with Py_SET_TYPE(obj, new_type): see the Py_SET_TYPE() function (available since Python 3.9). For backward compatibility, this macro can be used:

#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

(Contributed by Victor Stinner in bpo-39573 [https://bugs.python.org/issue?@action=redirect&bpo=39573].)

Since Py_SIZE() is changed to a inline static function, Py_SIZE(obj) = new_size must be replaced with Py_SET_SIZE(obj, new_size): see the Py_SET_SIZE() function (available since Python 3.9). For backward compatibility, this macro can be used:

#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

(Contributed by Victor Stinner in bpo-39573 [https://bugs.python.org/issue?@action=redirect&bpo=39573].)

<Python.h> no longer includes the header files <stdlib.h>, <stdio.h>, <errno.h> and <string.h> when the Py_LIMITED_API macro is set to 0x030b0000 (Python 3.11) or higher. C extensions should explicitly include the header files after #include <Python.h>. (Contributed by Victor Stinner in bpo-45434 [https://bugs.python.org/issue?@action=redirect&bpo=45434].)

The non-limited API files cellobject.h, classobject.h, code.h, context.h, funcobject.h, genobject.h and longintrepr.h have been moved to the Include/cpython directory. Moreover, the eval.h header file was removed. These files must not be included directly, as they are already included in Python.h: Include Files. If they have been included directly, consider including Python.h instead. (Contributed by Victor Stinner in bpo-35134 [https://bugs.python.org/issue?@action=redirect&bpo=35134].)

The PyUnicode_CHECK_INTERNED() macro has been excluded from the limited C API. It was never usable there, because it used internal structures which are not available in the limited C API. (Contributed by Victor Stinner in bpo-46007 [https://bugs.python.org/issue?@action=redirect&bpo=46007].)

The following frame functions and type are now directly available with #include <Python.h>, it's no longer needed to add #include <frameobject.h>:

PyFrame_Check()

PyFrame_GetBack()

PyFrame_GetBuiltins()

PyFrame_GetGenerator()

PyFrame_GetGlobals()

PyFrame_GetLasti()

PyFrame_GetLocals()

PyFrame_Type

(Contributed by Victor Stinner in gh-93937 [https://github.com/python/cpython/issues/93937].)

The PyFrameObject structure members have been removed from the public C API.

While the documentation notes that the PyFrameObject fields are subject to change at any time, they have been stable for a long time and were used in several popular extensions.

In Python 3.11, the frame struct was reorganized to allow performance optimizations. Some fields were removed entirely, as they were details of the old implementation.

PyFrameObject fields:

f_back: use PyFrame_GetBack().

f_blockstack: removed.

f_builtins: use PyFrame_GetBuiltins().

f_code: use PyFrame_GetCode().

f_gen: use PyFrame_GetGenerator().

f_globals: use PyFrame_GetGlobals().

f_iblock: removed.

f_lasti: use PyFrame_GetLasti(). Code using f_lasti with PyCode_Addr2Line() should use PyFrame_GetLineNumber() instead; it may be faster.

f_lineno: use PyFrame_GetLineNumber()

f_locals: use PyFrame_GetLocals().

f_stackdepth: removed.

f_state: no public API (renamed to f_frame.f_state).

f_trace: no public API.

f_trace_lines: use PyObject_GetAttrString((PyObject*)frame, "f_trace_lines").

f_trace_opcodes: use PyObject_GetAttrString((PyObject*)frame, "f_trace_opcodes").

f_localsplus: no public API (renamed to f_frame.localsplus).

f_valuestack: removed.

The Python frame object is now created lazily. A side effect is that the f_back member must not be accessed directly, since its value is now also computed lazily. The PyFrame_GetBack() function must be called instead.

Debuggers that accessed the f_locals directly must call PyFrame_GetLocals() instead. They no longer need to call PyFrame_FastToLocalsWithError() or PyFrame_LocalsToFast(), in fact they should not call those functions. The necessary updating of the frame is now managed by the virtual machine.

Code defining PyFrame_GetCode() on Python 3.8 and older:

#if PY_VERSION_HEX < 0x030900B1
static inline PyCodeObject* PyFrame_GetCode(PyFrameObject *frame)
{
    Py_INCREF(frame->f_code);
    return frame->f_code;
}
#endif

Code defining PyFrame_GetBack() on Python 3.8 and older:

#if PY_VERSION_HEX < 0x030900B1
static inline PyFrameObject* PyFrame_GetBack(PyFrameObject *frame)
{
    Py_XINCREF(frame->f_back);
    return frame->f_back;
}
#endif

Or use the pythoncapi_compat project [https://github.com/python/pythoncapi-compat] to get these two functions on older Python versions.

Changes of the PyThreadState structure members:

frame: removed, use PyThreadState_GetFrame() (function added to Python 3.9 by bpo-40429 [https://bugs.python.org/issue?@action=redirect&bpo=40429]). Warning: the function returns a strong reference, need to call Py_XDECREF().

tracing: changed, use PyThreadState_EnterTracing() and PyThreadState_LeaveTracing() (functions added to Python 3.11 by bpo-43760 [https://bugs.python.org/issue?@action=redirect&bpo=43760]).

recursion_depth: removed, use (tstate->recursion_limit - tstate->recursion_remaining) instead.

stackcheck_counter: removed.

Code defining PyThreadState_GetFrame() on Python 3.8 and older:

#if PY_VERSION_HEX < 0x030900B1
static inline PyFrameObject* PyThreadState_GetFrame(PyThreadState *tstate)
{
    Py_XINCREF(tstate->frame);
    return tstate->frame;
}
#endif

Code defining PyThreadState_EnterTracing() and PyThreadState_LeaveTracing() on Python 3.10 and older:

#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

Or use the pythoncapi-compat project [https://github.com/python/pythoncapi-compat] to get these functions on old Python functions.

Distributors are encouraged to build Python with the optimized Blake2 library libb2 [https://www.blake2.net/].

The PyConfig.module_search_paths_set field must now be set to 1 for initialization to use PyConfig.module_search_paths to initialize sys.path. Otherwise, initialization will recalculate the path and replace any values added to module_search_paths.

PyConfig_Read() no longer calculates the initial search path, and will not fill any values into PyConfig.module_search_paths. To calculate default paths and then modify them, finish initialization and use PySys_GetObject() to retrieve sys.path as a Python list object and modify it directly.

非推奨

Deprecate the following functions to configure the Python initialization:

PySys_AddWarnOptionUnicode()

PySys_AddWarnOption()

PySys_AddXOption()

PySys_HasWarnOptions()

PySys_SetArgvEx()

PySys_SetArgv()

PySys_SetPath()

Py_SetPath()

Py_SetProgramName()

Py_SetPythonHome()

Py_SetStandardStreamEncoding()

_Py_SetProgramFullPath()

Use the new PyConfig API of the Python Initialization Configuration instead (PEP 587 [https://peps.python.org/pep-0587/]). (Contributed by Victor Stinner in gh-88279 [https://github.com/python/cpython/issues/88279].)

Deprecate the ob_shash member of the PyBytesObject. Use PyObject_Hash() instead. (Contributed by Inada Naoki in bpo-46864 [https://bugs.python.org/issue?@action=redirect&bpo=46864].)

Pending Removal in Python 3.12

The following C APIs have been deprecated in earlier Python releases, and will be removed in Python 3.12.

PyUnicode_AS_DATA()

PyUnicode_AS_UNICODE()

PyUnicode_AsUnicodeAndSize()

PyUnicode_AsUnicode()

PyUnicode_FromUnicode()

PyUnicode_GET_DATA_SIZE()

PyUnicode_GET_SIZE()

PyUnicode_GetSize()

PyUnicode_IS_COMPACT()

PyUnicode_IS_READY()

PyUnicode_READY()

PyUnicode_WSTR_LENGTH()

_PyUnicode_AsUnicode()

PyUnicode_WCHAR_KIND

PyUnicodeObject

PyUnicode_InternImmortal()

削除

PyFrame_BlockSetup() and PyFrame_BlockPop() have been removed. (Contributed by Mark Shannon in bpo-40222 [https://bugs.python.org/issue?@action=redirect&bpo=40222].)

Remove the following math macros using the errno variable:

Py_ADJUST_ERANGE1()

Py_ADJUST_ERANGE2()

Py_OVERFLOWED()

Py_SET_ERANGE_IF_OVERFLOW()

Py_SET_ERRNO_ON_MATH_ERROR()

(Victor Stinner の貢献による bpo-45412 [https://bugs.python.org/issue?@action=redirect&bpo=45412])

Remove Py_UNICODE_COPY() and Py_UNICODE_FILL() macros, deprecated since Python 3.3. Use PyUnicode_CopyCharacters() or memcpy() (wchar_t* string), and PyUnicode_Fill() functions instead. (Contributed by Victor Stinner in bpo-41123 [https://bugs.python.org/issue?@action=redirect&bpo=41123].)

Remove the pystrhex.h header file. It only contains private functions. C extensions should only include the main <Python.h> header file. (Contributed by Victor Stinner in bpo-45434 [https://bugs.python.org/issue?@action=redirect&bpo=45434].)

Remove the Py_FORCE_DOUBLE() macro. It was used by the Py_IS_INFINITY() macro. (Contributed by Victor Stinner in bpo-45440 [https://bugs.python.org/issue?@action=redirect&bpo=45440].)

The following items are no longer available when Py_LIMITED_API is defined:

PyMarshal_WriteLongToFile()

PyMarshal_WriteObjectToFile()

PyMarshal_ReadObjectFromString()

PyMarshal_WriteObjectToString()

Py_MARSHAL_VERSION マクロ

These are not part of the limited API.

(Contributed by Victor Stinner in bpo-45474 [https://bugs.python.org/issue?@action=redirect&bpo=45474].)

Exclude PyWeakref_GET_OBJECT() from the limited C API. It never worked since the PyWeakReference structure is opaque in the limited C API. (Contributed by Victor Stinner in bpo-35134 [https://bugs.python.org/issue?@action=redirect&bpo=35134].)

Remove the PyHeapType_GET_MEMBERS() macro. It was exposed in the public C API by mistake, it must only be used by Python internally. Use the PyTypeObject.tp_members member instead. (Contributed by Victor Stinner in bpo-40170 [https://bugs.python.org/issue?@action=redirect&bpo=40170].)

Remove the HAVE_PY_SET_53BIT_PRECISION macro (moved to the internal C API). (Contributed by Victor Stinner in bpo-45412 [https://bugs.python.org/issue?@action=redirect&bpo=45412].)

Remove the Py_UNICODE encoder APIs, as they have been deprecated since Python 3.3, are little used and are inefficient relative to the recommended alternatives.

削除された関数は以下の通りです:

PyUnicode_Encode()

PyUnicode_EncodeASCII()

PyUnicode_EncodeLatin1()

PyUnicode_EncodeUTF7()

PyUnicode_EncodeUTF8()

PyUnicode_EncodeUTF16()

PyUnicode_EncodeUTF32()

PyUnicode_EncodeUnicodeEscape()

PyUnicode_EncodeRawUnicodeEscape()

PyUnicode_EncodeCharmap()

PyUnicode_TranslateCharmap()

PyUnicode_EncodeDecimal()

PyUnicode_TransformDecimalToASCII()

See PEP 624 [https://peps.python.org/pep-0624/] for details and migration guidance [https://peps.python.org/pep-0624/#alternative-apis]. (Contributed by Inada Naoki in bpo-44029 [https://bugs.python.org/issue?@action=redirect&bpo=44029].)

Python 3.11.4での重要な変更点

tarfile

The extraction methods in tarfile, and 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 Extraction filters for details. In Python 3.12, use without the filter argument will show a DeprecationWarning. In Python 3.14, the default will switch to 'data'. (Contributed by Petr Viktorin in PEP 706 [https://peps.python.org/pep-0706/].)

Python 3.11.5での重要な変更点

OpenSSL

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

What's New In Python 3.10

編集者:

Pablo Galindo Salgado

この記事では Python 3.9 と比較した Python 3.10 の新機能を解説します。Python 3.10 は2021年10月4日にリリースされました。全詳細については 変更履歴 をご覧ください。

概要 -- リリースハイライト

新たな文法機能:

PEP 634 [https://peps.python.org/pep-0634/]、構造的パターンマッチ: 仕様

PEP 635 [https://peps.python.org/pep-0635/]、構造的パターンマッチ: モチベーションと原理

PEP 636 [https://peps.python.org/pep-0636/]、構造的パターンマッチ: チュートリアル

bpo-12782 [https://bugs.python.org/issue?@action=redirect&bpo=12782]、カッコ内のコンテキストマネージャーが正式にサポート

標準ライブラリの新機能:

PEP 618 [https://peps.python.org/pep-0618/]、zipに長さチェックのオプション引数が追加

インタプリタの改善:

PEP 626 [https://peps.python.org/pep-0626/], Precise line numbers for debugging and other tools.

新しい型ヒントの機能:

PEP 604 [https://peps.python.org/pep-0604/], Allow writing union types as X | Y

PEP 612 [https://peps.python.org/pep-0612/], Parameter Specification Variables

PEP 613 [https://peps.python.org/pep-0613/], Explicit Type Aliases

PEP 647 [https://peps.python.org/pep-0647/], User-Defined Type Guards

重要な非推奨化、削除または制限:

PEP 644 [https://peps.python.org/pep-0644/], Require OpenSSL 1.1.1 or newer

PEP 632 [https://peps.python.org/pep-0632/], Deprecate distutils module.

PEP 623 [https://peps.python.org/pep-0623/], Deprecate and prepare for the removal of the wstr member in PyUnicodeObject.

PEP 624 [https://peps.python.org/pep-0624/], Remove Py_UNICODE encoder APIs

PEP 597 [https://peps.python.org/pep-0597/], Add optional EncodingWarning

新しい機能

カッコ内のコンテキストマネージャー

コンテキストマネージャーを複数行で継続して記述する場合に、カッコで囲むことができるようになりました。複数行でたくさんのコンテキストマネージャーを記述するときに、従来のimport文と同じようにフォーマットできます。たとえば、以下のすべての例は有効です:

with (CtxManager() as example):
    ...

with (
    CtxManager1(),
    CtxManager2()
):
    ...

with (CtxManager1() as example,
      CtxManager2()):
    ...

with (CtxManager1(),
      CtxManager2() as example):
    ...

with (
    CtxManager1() as example1,
    CtxManager2() as example2
):
    ...

カッコに囲まれたグループの最後の要素に対する、末尾のカンマも指定可能です。

with (
    CtxManager1() as example1,
    CtxManager2() as example2,
    CtxManager3() as example3,
):
    ...

この新しい構文は、新パーサーによるLL(1)以外の能力を使用しています。詳細は PEP 617 [https://peps.python.org/pep-0617/] を参照してください。

(Guido van Rossum、Pablo Galindo、Lysandros Nikolaou の貢献による bpo-12782 [https://bugs.python.org/issue?@action=redirect&bpo=12782]、bpo-40334 [https://bugs.python.org/issue?@action=redirect&bpo=40334])

エラーメッセージの改善

SyntaxErrors

When parsing code that contains unclosed parentheses or brackets the interpreter now includes the location of the unclosed bracket of parentheses instead of displaying SyntaxError: unexpected EOF while parsing or pointing to some incorrect location. For instance, consider the following code (notice the unclosed '{'):

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()

以前のバージョンのインタープリタは、構文エラーの位置として混乱する場所を報告していました:

File "example.py", line 3
    some_other_code = foo()
                    ^
SyntaxError: invalid syntax

しかしPython 3.10ではより有益なエラーが出力されます:

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

In a similar way, errors involving unclosed string literals (single and triple quoted) now point to the start of the string instead of reporting EOF/EOL.

These improvements are inspired by previous work in the PyPy interpreter.

(Pablo Galindoの貢献による bpo-42864 [https://bugs.python.org/issue?@action=redirect&bpo=42864]、Batuhan Taskayaの貢献による bpo-40176 [https://bugs.python.org/issue?@action=redirect&bpo=40176])

SyntaxError exceptions raised by the interpreter will now highlight the full error range of the expression that constitutes the syntax error itself, instead of just where the problem is detected. In this way, instead of displaying (before Python 3.10):

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

now Python 3.10 will display the exception as:

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

This improvement was contributed by Pablo Galindo in bpo-43914 [https://bugs.python.org/issue?@action=redirect&bpo=43914].

A considerable amount of new specialized messages for SyntaxError exceptions have been incorporated. Some of the most notable ones are as follows:

ブロックの前の : が存在しない:

>>> if rocket.position > event_horizon
  File "<stdin>", line 1
    if rocket.position > event_horizon
                                      ^
SyntaxError: expected ':'

(Pablo Galindo の貢献による bpo-42997 [https://bugs.python.org/issue?@action=redirect&bpo=42997])

内包表記のターゲットにカッコのないタプルを使用:

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

(Pablo Galindo の貢献による bpo-43017 [https://bugs.python.org/issue?@action=redirect&bpo=43017])

コレクションリテラルや式の間のカンマが存在しない:

>>> items = {
... x: 1,
... y: 2
... z: 3,
  File "<stdin>", line 3
    y: 2
       ^
SyntaxError: invalid syntax. Perhaps you forgot a comma?

(Pablo Galindo の貢献による bpo-43822 [https://bugs.python.org/issue?@action=redirect&bpo=43822])

複数の例外の型をカッコで囲んでいない:

>>> try:
...     build_dyson_sphere()
... except NotEnoughScienceError, NotEnoughResourcesError:
  File "<stdin>", line 3
    except NotEnoughScienceError, NotEnoughResourcesError:
           ^
SyntaxError: multiple exception types must be parenthesized

(Pablo Galindo の貢献による bpo-43149 [https://bugs.python.org/issue?@action=redirect&bpo=43149])

辞書のリテラルで : と値が存在しない:

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

(Pablo Galindo の貢献による bpo-43823 [https://bugs.python.org/issue?@action=redirect&bpo=43823])

try ブロックに except または finally ブロックが存在しない:

>>> try:
...     x = 2
... something = 3
  File "<stdin>", line 3
    something  = 3
    ^^^^^^^^^
SyntaxError: expected 'except' or 'finally' block

(Pablo Galindo の貢献による bpo-44305 [https://bugs.python.org/issue?@action=redirect&bpo=44305])

比較で == の代わりに = を使用している:

>>> 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 '='?

(Pablo Galindo の貢献による bpo-43797 [https://bugs.python.org/issue?@action=redirect&bpo=43797])

f-stringで * を使用している:

>>> f"Black holes {*all_black_holes} and revelations"
  File "<stdin>", line 1
    (*all_black_holes)
     ^
SyntaxError: f-string: cannot use starred expression here

(Pablo Galindo の貢献による bpo-41064 [https://bugs.python.org/issue?@action=redirect&bpo=41064])

IndentationErrors

Many IndentationError exceptions now have more context regarding what kind of block was expecting an indentation, including the location of the statement:

>>> def foo():
...    if lel:
...    x = 2
  File "<stdin>", line 3
    x = 2
    ^
IndentationError: expected an indented block after 'if' statement in line 2

AttributeErrors

When printing AttributeError, PyErr_Display() will offer suggestions of similar attribute names in the object that the exception was raised from:

>>> collections.namedtoplo
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: module 'collections' has no attribute 'namedtoplo'. Did you mean: namedtuple?

(Pablo Galindo の貢献による bpo-38530 [https://bugs.python.org/issue?@action=redirect&bpo=38530])

警告

Notice this won't work if PyErr_Display() is not called to display the error which can happen if some other custom error display function is used. This is a common scenario in some REPLs like IPython.

NameErrors

When printing NameError raised by the interpreter, PyErr_Display() will offer suggestions of similar variable names in the function that the exception was raised from:

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

(Pablo Galindo の貢献による bpo-38530 [https://bugs.python.org/issue?@action=redirect&bpo=38530])

警告

Notice this won't work if PyErr_Display() is not called to display the error, which can happen if some other custom error display function is used. This is a common scenario in some REPLs like IPython.

PEP 626: Precise line numbers for debugging and other tools

PEP 626 brings more precise and reliable line numbers for debugging, profiling and coverage tools. Tracing events, with the correct line number, are generated for all lines of code executed and only for lines of code that are executed.

The f_lineno attribute of frame objects will always contain the expected line number.

The co_lnotab attribute of code objects is deprecated and will be removed in 3.12. Code that needs to convert from offset to line number should use the new co_lines() method instead.

PEP 634: 構造的パターンマッチ

Structural pattern matching has been added in the form of a match statement and case statements of patterns with associated actions. Patterns consist of sequences, mappings, primitive data types as well as class instances. Pattern matching enables programs to extract information from complex data types, branch on the structure of data, and apply specific actions based on different forms of data.

Syntax and operations

The generic syntax of pattern matching is:

match subject:
    case <pattern_1>:
        <action_1>
    case <pattern_2>:
        <action_2>
    case <pattern_3>:
        <action_3>
    case _:
        <action_wildcard>

A match statement takes an expression and compares its value to successive patterns given as one or more case blocks. Specifically, pattern matching operates by:

using data with type and shape (the subject)

evaluating the subject in the match statement

comparing the subject with each pattern in a case statement from top to bottom until a match is confirmed.

executing the action associated with the pattern of the confirmed match

If an exact match is not confirmed, the last case, a wildcard _, if provided, will be used as the matching case. If an exact match is not confirmed and a wildcard case does not exist, the entire match block is a no-op.

Declarative approach

Readers may be aware of pattern matching through the simple example of matching a subject (data object) to a literal (pattern) with the switch statement found in C, Java or JavaScript (and many other languages). Often the switch statement is used for comparison of an object/expression with case statements containing literals.

More powerful examples of pattern matching can be found in languages such as Scala and Elixir. With structural pattern matching, the approach is "declarative" and explicitly states the conditions (the patterns) for data to match.

While an "imperative" series of instructions using nested "if" statements could be used to accomplish something similar to structural pattern matching, it is less clear than the "declarative" approach. Instead the "declarative" approach states the conditions to meet for a match and is more readable through its explicit patterns. While structural pattern matching can be used in its simplest form comparing a variable to a literal in a case statement, its true value for Python lies in its handling of the subject's type and shape.

Simple pattern: match to a literal

Let's look at this example as pattern matching in its simplest form: a value, the subject, being matched to several literals, the patterns. In the example below, status is the subject of the match statement. The patterns are each of the case statements, where literals represent request status codes. The associated action to the case is executed after a match:

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"

If the above function is passed a status of 418, "I'm a teapot" is returned. If the above function is passed a status of 500, the case statement with _ will match as a wildcard, and "Something's wrong with the internet" is returned. Note the last block: the variable name, _, acts as a wildcard and insures the subject will always match. The use of _ is optional.

複数のリテラルを``|`` ("or")を使用して組み合わせて1つのパターンにできます。

case 401 | 403 | 404:
    return "Not allowed"

Behavior without the wildcard

If we modify the above example by removing the last case block, the example becomes:

def http_error(status):
    match status:
        case 400:
            return "Bad request"
        case 404:
            return "Not found"
        case 418:
            return "I'm a teapot"

Without the use of _ in a case statement, a match may not exist. If no match exists, the behavior is a no-op. For example, if status of 500 is passed, a no-op occurs.

Patterns with a literal and variable

Patterns can look like unpacking assignments, and a pattern may be used to bind variables. In this example, a data point can be unpacked to its x-coordinate and y-coordinate:

# 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")

The first pattern has two literals, (0, 0), and may be thought of as an extension of the literal pattern shown above. The next two patterns combine a literal and a variable, and the variable binds a value from the subject (point). The fourth pattern captures two values, which makes it conceptually similar to the unpacking assignment (x, y) = point.

Patterns and classes

If you are using classes to structure your data, you can use as a pattern the class name followed by an argument list resembling a constructor. This pattern has the ability to capture class attributes into variables:

class Point:
    x: int
    y: int

def location(point):
    match point:
        case Point(x=0, y=0):
            print("Origin is the point's location.")
        case Point(x=0, y=y):
            print(f"Y={y} and the point is on the y-axis.")
        case Point(x=x, y=0):
            print(f"X={x} and the point is on the x-axis.")
        case Point():
            print("The point is located somewhere else on the plane.")
        case _:
            print("Not a point")

Patterns with positional parameters

いくつかの組み込みクラスでは位置引数が使用でき、属性の順番を提供します(例: データクラス)。クラスの __match_args__ 特殊属性でによって、パターンの中で属性の明確な位置を定義することもできます。("x", "y")が設定された場合、以下のすべてのパターンは等価です(すべて属性 y が var 変数に関連づけられます):

Point(1, var)
Point(1, y=var)
Point(x=1, y=var)
Point(y=var, x=1)

Nested patterns

Patterns can be arbitrarily nested. For example, if our data is a short list of points, it could be matched like this:

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

Complex patterns and the wildcard

To this point, the examples have used _ alone in the last case statement. A wildcard can be used in more complex patterns, such as ('error', code, _). For example:

match test_variable:
    case ('warning', code, 40):
        print("A warning has been received.")
    case ('error', code, _):
        print(f"An error {code} occurred.")

In the above case, test_variable will match for ('error', code, 100) and ('error', code, 800).

Guard

パターンに if 節を追加できます。これは "ガード" と呼ばれます。ガードがfalseの場合、match は次のcaseブロックの処理に移動します。ガードを評価する前に値が取り出されることに注意してください:

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

Other Key Features

Several other key features:

Like unpacking assignments, tuple and list patterns have exactly the same meaning and actually match arbitrary sequences. Technically, the subject must be a sequence. Therefore, an important exception is that patterns don't match iterators. Also, to prevent a common mistake, sequence patterns don't match strings.

Sequence patterns support wildcards: [x, y, *rest] and (x, y, *rest) work similar to wildcards in unpacking assignments. The name after * may also be _, so (x, y, *_) matches a sequence of at least two items without binding the remaining items.

Mapping patterns: {"bandwidth": b, "latency": l} captures the "bandwidth" and "latency" values from a dict. Unlike sequence patterns, extra keys are ignored. A wildcard **rest is also supported. (But **_ would be redundant, so is not allowed.)

サブパターンでは as キーワードを使用して値を取り込みます:

case (Point(x1, y1), Point(x2, y2) as p2): ...

This binds x1, y1, x2, y2 like you would expect without the as clause, and p2 to the entire second item of the subject.

Most literals are compared by equality. However, the singletons True, False and None are compared by identity.

Named constants may be used in patterns. These named constants must be dotted names to prevent the constant from being interpreted as a capture variable:

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 :(")

For the full specification see PEP 634 [https://peps.python.org/pep-0634/]. Motivation and rationale are in PEP 635 [https://peps.python.org/pep-0635/], and a longer tutorial is in PEP 636 [https://peps.python.org/pep-0636/].

Optional EncodingWarning and encoding="locale" option

The default encoding of TextIOWrapper and open() is platform and locale dependent. Since UTF-8 is used on most Unix platforms, omitting encoding option when opening UTF-8 files (e.g. JSON, YAML, TOML, Markdown) is a very common bug. For example:

# BUG: "rb" mode or encoding="utf-8" should be used.
with open("data.json") as f:
    data = json.load(f)

To find this type of bug, an optional EncodingWarning is added. It is emitted when sys.flags.warn_default_encoding is true and locale-specific default encoding is used.

-X warn_default_encoding option and PYTHONWARNDEFAULTENCODING are added to enable the warning.

See Text Encoding for more information.

型ヒントに関連する新しい機能

This section covers major changes affecting PEP 484 [https://peps.python.org/pep-0484/] type hints and the typing module.

PEP 604: New Type Union Operator

A new type union operator was introduced which enables the syntax X | Y. This provides a cleaner way of expressing 'either type X or type Y' instead of using typing.Union, especially in type hints.

In previous versions of Python, to apply a type hint for functions accepting arguments of multiple types, typing.Union was used:

def square(number: Union[int, float]) -> Union[int, float]:
    return number ** 2

Type hints can now be written in a more succinct manner:

def square(number: int | float) -> int | float:
    return number ** 2

This new syntax is also accepted as the second argument to isinstance() and issubclass():

>>> isinstance(1, int | str)
True

See Union 型 and PEP 604 [https://peps.python.org/pep-0604/] for more details.

(Contributed by Maggie Moss and Philippe Prados in bpo-41428 [https://bugs.python.org/issue?@action=redirect&bpo=41428], with additions by Yurii Karabas and Serhiy Storchaka in bpo-44490 [https://bugs.python.org/issue?@action=redirect&bpo=44490].)

PEP 612: Parameter Specification Variables

Two new options to improve the information provided to static type checkers for PEP 484 [https://peps.python.org/pep-0484/]'s Callable have been added to the typing module.

The first is the parameter specification variable. They are used to forward the parameter types of one callable to another callable -- a pattern commonly found in higher order functions and decorators. Examples of usage can be found in typing.ParamSpec. Previously, there was no easy way to type annotate dependency of parameter types in such a precise manner.

The second option is the new Concatenate operator. It's used in conjunction with parameter specification variables to type annotate a higher order callable which adds or removes parameters of another callable. Examples of usage can be found in typing.Concatenate.

See typing.Callable, typing.ParamSpec, typing.Concatenate, typing.ParamSpecArgs, typing.ParamSpecKwargs, and PEP 612 [https://peps.python.org/pep-0612/] for more details.

(Contributed by Ken Jin in bpo-41559 [https://bugs.python.org/issue?@action=redirect&bpo=41559], with minor enhancements by Jelle Zijlstra in bpo-43783 [https://bugs.python.org/issue?@action=redirect&bpo=43783]. PEP written by Mark Mendoza.)

PEP 613: TypeAlias

PEP 484 [https://peps.python.org/pep-0484/] introduced the concept of type aliases, only requiring them to be top-level unannotated assignments. This simplicity sometimes made it difficult for type checkers to distinguish between type aliases and ordinary assignments, especially when forward references or invalid types were involved. Compare:

StrCache = 'Cache[str]'  # a type alias
LOG_PREFIX = 'LOG[DEBUG]'  # a module constant

Now the typing module has a special value TypeAlias which lets you declare type aliases more explicitly:

StrCache: TypeAlias = 'Cache[str]'  # a type alias
LOG_PREFIX = 'LOG[DEBUG]'  # a module constant

より詳しくは、 PEP 613 [https://peps.python.org/pep-0613/] をご覧ください。

(Contributed by Mikhail Golubev in bpo-41923 [https://bugs.python.org/issue?@action=redirect&bpo=41923].)

PEP 647: User-Defined Type Guards

TypeGuard has been added to the typing module to annotate type guard functions and improve information provided to static type checkers during type narrowing. For more information, please see TypeGuard's documentation, and PEP 647 [https://peps.python.org/pep-0647/].

(Contributed by Ken Jin and Guido van Rossum in bpo-43766 [https://bugs.python.org/issue?@action=redirect&bpo=43766]. PEP written by Eric Traut.)

その他の言語変更

The int type has a new method int.bit_count(), returning the number of ones in the binary expansion of a given integer, also known as the population count. (Contributed by Niklas Fiekas in bpo-29882 [https://bugs.python.org/issue?@action=redirect&bpo=29882].)

The views returned by dict.keys(), dict.values() and dict.items() now all have a mapping attribute that gives a types.MappingProxyType object wrapping the original dictionary. (Contributed by Dennis Sweeney in bpo-40890 [https://bugs.python.org/issue?@action=redirect&bpo=40890].)

PEP 618 [https://peps.python.org/pep-0618/]: The zip() function now has an optional strict flag, used to require that all the iterables have an equal length.

Builtin and extension functions that take integer arguments no longer accept Decimals, Fractions and other objects that can be converted to integers only with a loss (e.g. that have the __int__() method but do not have the __index__() method). (Contributed by Serhiy Storchaka in bpo-37999 [https://bugs.python.org/issue?@action=redirect&bpo=37999].)

If object.__ipow__() returns NotImplemented, the operator will correctly fall back to object.__pow__() and object.__rpow__() as expected. (Contributed by Alex Shkop in bpo-38302 [https://bugs.python.org/issue?@action=redirect&bpo=38302].)

Assignment expressions can now be used unparenthesized within set literals and set comprehensions, as well as in sequence indexes (but not slices).

Functions have a new __builtins__ attribute which is used to look for builtin symbols when a function is executed, instead of looking into __globals__['__builtins__']. The attribute is initialized from __globals__["__builtins__"] if it exists, else from the current builtins. (Contributed by Mark Shannon in bpo-42990 [https://bugs.python.org/issue?@action=redirect&bpo=42990].)

Two new builtin functions -- aiter() and anext() have been added to provide asynchronous counterparts to iter() and next(), respectively. (Contributed by Joshua Bronson, Daniel Pope, and Justin Wang in bpo-31861 [https://bugs.python.org/issue?@action=redirect&bpo=31861].)

Static methods (@staticmethod) and class methods (@classmethod) now inherit the method attributes (__module__, __name__, __qualname__, __doc__, __annotations__) and have a new __wrapped__ attribute. Moreover, static methods are now callable as regular functions. (Contributed by Victor Stinner in bpo-43682 [https://bugs.python.org/issue?@action=redirect&bpo=43682].)

Annotations for complex targets (everything beside simple name targets defined by PEP 526 [https://peps.python.org/pep-0526/]) no longer cause any runtime effects with from __future__ import annotations. (Contributed by Batuhan Taskaya in bpo-42737 [https://bugs.python.org/issue?@action=redirect&bpo=42737].)

Class and module objects now lazy-create empty annotations dicts on demand. The annotations dicts are stored in the object’s __dict__ for backwards compatibility. This improves the best practices for working with __annotations__; for more information, please see Annotations Best Practices. (Contributed by Larry Hastings in bpo-43901 [https://bugs.python.org/issue?@action=redirect&bpo=43901].)

Annotations consist of yield, yield from, await or named expressions are now forbidden under from __future__ import annotations due to their side effects. (Contributed by Batuhan Taskaya in bpo-42725 [https://bugs.python.org/issue?@action=redirect&bpo=42725].)

Usage of unbound variables, super() and other expressions that might alter the processing of symbol table as annotations are now rendered effectless under from __future__ import annotations. (Contributed by Batuhan Taskaya in bpo-42725 [https://bugs.python.org/issue?@action=redirect&bpo=42725].)

Hashes of NaN values of both float type and decimal.Decimal type now depend on object identity. Formerly, they always hashed to 0 even though NaN values are not equal to one another. This caused potentially quadratic runtime behavior due to excessive hash collisions when creating dictionaries and sets containing multiple NaNs. (Contributed by Raymond Hettinger in bpo-43475 [https://bugs.python.org/issue?@action=redirect&bpo=43475].)

A SyntaxError (instead of a NameError) will be raised when deleting the __debug__ constant. (Contributed by Donghee Na in bpo-45000 [https://bugs.python.org/issue?@action=redirect&bpo=45000].)

SyntaxError exceptions now have end_lineno and end_offset attributes. They will be None if not determined. (Contributed by Pablo Galindo in bpo-43914 [https://bugs.python.org/issue?@action=redirect&bpo=43914].)

新たなモジュール

None.

改良されたモジュール

asyncio

Add missing connect_accepted_socket() method. (Contributed by Alex Grönholm in bpo-41332 [https://bugs.python.org/issue?@action=redirect&bpo=41332].)

argparse

Misleading phrase "optional arguments" was replaced with "options" in argparse help. Some tests might require adaptation if they rely on exact output match. (Contributed by Raymond Hettinger in bpo-9694 [https://bugs.python.org/issue?@action=redirect&bpo=9694].)

array

The index() method of array.array now has optional start and stop parameters. (Contributed by Anders Lorentsen and Zackery Spytz in bpo-31956 [https://bugs.python.org/issue?@action=redirect&bpo=31956].)

asynchat, asyncore, smtpd

These modules have been marked as deprecated in their module documentation since Python 3.6. An import-time DeprecationWarning has now been added to all three of these modules.

base64

Add base64.b32hexencode() and base64.b32hexdecode() to support the Base32 Encoding with Extended Hex Alphabet.

bdb

Add clearBreakpoints() to reset all set breakpoints. (Contributed by Irit Katriel in bpo-24160 [https://bugs.python.org/issue?@action=redirect&bpo=24160].)

bisect

Added the possibility of providing a key function to the APIs in the bisect module. (Contributed by Raymond Hettinger in bpo-4356 [https://bugs.python.org/issue?@action=redirect&bpo=4356].)

codecs

Add a codecs.unregister() function to unregister a codec search function. (Contributed by Hai Shi in bpo-41842 [https://bugs.python.org/issue?@action=redirect&bpo=41842].)

collections.abc

The __args__ of the parameterized generic for collections.abc.Callable are now consistent with typing.Callable. collections.abc.Callable generic now flattens type parameters, similar to what typing.Callable currently does. This means that collections.abc.Callable[[int, str], str] will have __args__ of (int, str, str); previously this was ([int, str], str). To allow this change, types.GenericAlias can now be subclassed, and a subclass will be returned when subscripting the collections.abc.Callable type. Note that a TypeError may be raised for invalid forms of parameterizing collections.abc.Callable which may have passed silently in Python 3.9. (Contributed by Ken Jin in bpo-42195 [https://bugs.python.org/issue?@action=redirect&bpo=42195].)

contextlib

Add a contextlib.aclosing() context manager to safely close async generators and objects representing asynchronously released resources. (Contributed by Joongi Kim and John Belmonte in bpo-41229 [https://bugs.python.org/issue?@action=redirect&bpo=41229].)

Add asynchronous context manager support to contextlib.nullcontext(). (Contributed by Tom Gringauz in bpo-41543 [https://bugs.python.org/issue?@action=redirect&bpo=41543].)

Add AsyncContextDecorator, for supporting usage of async context managers as decorators.

curses

The extended color functions added in ncurses 6.1 will be used transparently by curses.color_content(), curses.init_color(), curses.init_pair(), and curses.pair_content(). A new function, curses.has_extended_color_support(), indicates whether extended color support is provided by the underlying ncurses library. (Contributed by Jeffrey Kintscher and Hans Petter Jansson in bpo-36982 [https://bugs.python.org/issue?@action=redirect&bpo=36982].)

The BUTTON5_* constants are now exposed in the curses module if they are provided by the underlying curses library. (Contributed by Zackery Spytz in bpo-39273 [https://bugs.python.org/issue?@action=redirect&bpo=39273].)

データクラス

__slots__

Added slots parameter in dataclasses.dataclass() decorator. (Contributed by Yurii Karabas in bpo-42269 [https://bugs.python.org/issue?@action=redirect&bpo=42269])

Keyword-only fields

dataclasses now supports fields that are keyword-only in the generated __init__ method. There are a number of ways of specifying keyword-only fields.

You can say that every field is keyword-only:

from dataclasses import dataclass

@dataclass(kw_only=True)
class Birthday:
    name: str
    birthday: datetime.date

Both name and birthday are keyword-only parameters to the generated __init__ method.

You can specify keyword-only on a per-field basis:

from dataclasses import dataclass, field

@dataclass
class Birthday:
    name: str
    birthday: datetime.date = field(kw_only=True)

Here only birthday is keyword-only. If you set kw_only on individual fields, be aware that there are rules about re-ordering fields due to keyword-only fields needing to follow non-keyword-only fields. See the full dataclasses documentation for details.

You can also specify that all fields following a KW_ONLY marker are keyword-only. This will probably be the most common usage:

from dataclasses import dataclass, KW_ONLY

@dataclass
class Point:
    x: float
    y: float
    _: KW_ONLY
    z: float = 0.0
    t: float = 0.0

Here, z and t are keyword-only parameters, while x and y are not. (Contributed by Eric V. Smith in bpo-43532 [https://bugs.python.org/issue?@action=redirect&bpo=43532].)

distutils

The entire distutils package is deprecated, to be removed in Python 3.12. Its functionality for specifying package builds has already been completely replaced by third-party packages setuptools and packaging, and most other commonly used APIs are available elsewhere in the standard library (such as platform, shutil, subprocess or sysconfig). There are no plans to migrate any other functionality from distutils, and applications that are using other functions should plan to make private copies of the code. Refer to PEP 632 [https://peps.python.org/pep-0632/] for discussion.

The bdist_wininst command deprecated in Python 3.8 has been removed. The bdist_wheel command is now recommended to distribute binary packages on Windows. (Contributed by Victor Stinner in bpo-42802 [https://bugs.python.org/issue?@action=redirect&bpo=42802].)

doctest

When a module does not define __loader__, fall back to __spec__.loader. (Contributed by Brett Cannon in bpo-42133 [https://bugs.python.org/issue?@action=redirect&bpo=42133].)

エンコーディング

encodings.normalize_encoding() now ignores non-ASCII characters. (Contributed by Hai Shi in bpo-39337 [https://bugs.python.org/issue?@action=redirect&bpo=39337].)

enum

Enum __repr__() now returns enum_name.member_name and __str__() now returns member_name. Stdlib enums available as module constants have a repr() of module_name.member_name. (Contributed by Ethan Furman in bpo-40066 [https://bugs.python.org/issue?@action=redirect&bpo=40066].)

Add enum.StrEnum for enums where all members are strings. (Contributed by Ethan Furman in bpo-41816 [https://bugs.python.org/issue?@action=redirect&bpo=41816].)

fileinput

Add encoding and errors parameters in fileinput.input() and fileinput.FileInput. (Contributed by Inada Naoki in bpo-43712 [https://bugs.python.org/issue?@action=redirect&bpo=43712].)

fileinput.hook_compressed() now returns TextIOWrapper object when mode is "r" and file is compressed, like uncompressed files. (Contributed by Inada Naoki in bpo-5758 [https://bugs.python.org/issue?@action=redirect&bpo=5758].)

faulthandler

The faulthandler module now detects if a fatal error occurs during a garbage collector collection. (Contributed by Victor Stinner in bpo-44466 [https://bugs.python.org/issue?@action=redirect&bpo=44466].)

gc

Add audit hooks for gc.get_objects(), gc.get_referrers() and gc.get_referents(). (Contributed by Pablo Galindo in bpo-43439 [https://bugs.python.org/issue?@action=redirect&bpo=43439].)

glob

Add the root_dir and dir_fd parameters in glob() and iglob() which allow to specify the root directory for searching. (Contributed by Serhiy Storchaka in bpo-38144 [https://bugs.python.org/issue?@action=redirect&bpo=38144].)

hashlib

The hashlib module requires OpenSSL 1.1.1 or newer. (Contributed by Christian Heimes in PEP 644 [https://peps.python.org/pep-0644/] and bpo-43669 [https://bugs.python.org/issue?@action=redirect&bpo=43669].)

The hashlib module has preliminary support for OpenSSL 3.0.0. (Contributed by Christian Heimes in bpo-38820 [https://bugs.python.org/issue?@action=redirect&bpo=38820] and other issues.)

The pure-Python fallback of pbkdf2_hmac() is deprecated. In the future PBKDF2-HMAC will only be available when Python has been built with OpenSSL support. (Contributed by Christian Heimes in bpo-43880 [https://bugs.python.org/issue?@action=redirect&bpo=43880].)

hmac

The hmac module now uses OpenSSL's HMAC implementation internally. (Contributed by Christian Heimes in bpo-40645 [https://bugs.python.org/issue?@action=redirect&bpo=40645].)

IDLE と idelelib

Make IDLE invoke sys.excepthook() (when started without '-n'). User hooks were previously ignored. (Contributed by Ken Hilton in bpo-43008 [https://bugs.python.org/issue?@action=redirect&bpo=43008].)

Rearrange the settings dialog. Split the General tab into Windows and Shell/Ed tabs. Move help sources, which extend the Help menu, to the Extensions tab. Make space for new options and shorten the dialog. The latter makes the dialog better fit small screens. (Contributed by Terry Jan Reedy in bpo-40468 [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 [https://bugs.python.org/issue?@action=redirect&bpo=33962].)

The changes above were backported to a 3.9 maintenance release.

Add a Shell sidebar. Move the primary prompt ('>>>') to the sidebar. Add secondary prompts ('...') to the sidebar. Left click and optional drag selects one or more lines of text, as with the editor line number sidebar. Right click after selecting text lines displays a context menu with 'copy with prompts'. This zips together prompts from the sidebar with lines from the selected text. This option also appears on the context menu for the text. (Contributed by Tal Einat in bpo-37903 [https://bugs.python.org/issue?@action=redirect&bpo=37903].)

Use spaces instead of tabs to indent interactive code. This makes interactive code entries 'look right'. Making this feasible was a major motivation for adding the shell sidebar. (Contributed by Terry Jan Reedy in bpo-37892 [https://bugs.python.org/issue?@action=redirect&bpo=37892].)

Highlight the new soft keywords match, case, and _ in pattern-matching statements. However, this highlighting is not perfect and will be incorrect in some rare cases, including some _-s in case patterns. (Contributed by Tal Einat in bpo-44010 [https://bugs.python.org/issue?@action=redirect&bpo=44010].)

New in 3.10 maintenance releases.

Apply syntax highlighting to .pyi files. (Contributed by Alex Waygood and Terry Jan Reedy in bpo-45447 [https://bugs.python.org/issue?@action=redirect&bpo=45447].)

Include prompts when saving Shell with inputs and outputs. (Contributed by Terry Jan Reedy in gh-95191 [https://github.com/python/cpython/issues/95191].)

importlib.metadata

Feature parity with importlib_metadata 4.6 (history [https://importlib-metadata.readthedocs.io/en/latest/history.html]).

importlib.metadata entry points now provide a nicer experience for selecting entry points by group and name through a new importlib.metadata.EntryPoints class. See the Compatibility Note in the docs for more info on the deprecation and usage.

Added importlib.metadata.packages_distributions() for resolving top-level Python modules and packages to their importlib.metadata.Distribution.

inspect

When a module does not define __loader__, fall back to __spec__.loader. (Contributed by Brett Cannon in bpo-42133 [https://bugs.python.org/issue?@action=redirect&bpo=42133].)

Add inspect.get_annotations(), which safely computes the annotations defined on an object. It works around the quirks of accessing the annotations on various types of objects, and makes very few assumptions about the object it examines. inspect.get_annotations() can also correctly un-stringize stringized annotations. inspect.get_annotations() is now considered best practice for accessing the annotations dict defined on any Python object; for more information on best practices for working with annotations, please see Annotations Best Practices. Relatedly, inspect.signature(), inspect.Signature.from_callable(), and inspect.Signature.from_function() now call inspect.get_annotations() to retrieve annotations. This means inspect.signature() and inspect.Signature.from_callable() can also now un-stringize stringized annotations. (Contributed by Larry Hastings in bpo-43817 [https://bugs.python.org/issue?@action=redirect&bpo=43817].)

itertools

Add itertools.pairwise(). (Contributed by Raymond Hettinger in bpo-38200 [https://bugs.python.org/issue?@action=redirect&bpo=38200].)

linecache

When a module does not define __loader__, fall back to __spec__.loader. (Contributed by Brett Cannon in bpo-42133 [https://bugs.python.org/issue?@action=redirect&bpo=42133].)

os

Add os.cpu_count() support for VxWorks RTOS. (Contributed by Peixing Xin in bpo-41440 [https://bugs.python.org/issue?@action=redirect&bpo=41440].)

Add a new function os.eventfd() and related helpers to wrap the eventfd2 syscall on Linux. (Contributed by Christian Heimes in bpo-41001 [https://bugs.python.org/issue?@action=redirect&bpo=41001].)

Add os.splice() that allows to move data between two file descriptors without copying between kernel address space and user address space, where one of the file descriptors must refer to a pipe. (Contributed by Pablo Galindo in bpo-41625 [https://bugs.python.org/issue?@action=redirect&bpo=41625].)

Add O_EVTONLY, O_FSYNC, O_SYMLINK and O_NOFOLLOW_ANY for macOS. (Contributed by Donghee Na in bpo-43106 [https://bugs.python.org/issue?@action=redirect&bpo=43106].)

os.path

os.path.realpath() now accepts a strict keyword-only argument. When set to True, OSError is raised if a path doesn't exist or a symlink loop is encountered. (Contributed by Barney Gale in bpo-43757 [https://bugs.python.org/issue?@action=redirect&bpo=43757].)

pathlib

Add slice support to PurePath.parents. (Contributed by Joshua Cannon in bpo-35498 [https://bugs.python.org/issue?@action=redirect&bpo=35498].)

Add negative indexing support to PurePath.parents. (Contributed by Yaroslav Pankovych in bpo-21041 [https://bugs.python.org/issue?@action=redirect&bpo=21041].)

Add Path.hardlink_to method that supersedes link_to(). The new method has the same argument order as symlink_to(). (Contributed by Barney Gale in bpo-39950 [https://bugs.python.org/issue?@action=redirect&bpo=39950].)

pathlib.Path.stat() and chmod() now accept a follow_symlinks keyword-only argument for consistency with corresponding functions in the os module. (Contributed by Barney Gale in bpo-39906 [https://bugs.python.org/issue?@action=redirect&bpo=39906].)

プラットフォーム

Add platform.freedesktop_os_release() to retrieve operation system identification from freedesktop.org os-release [https://www.freedesktop.org/software/systemd/man/os-release.html] standard file. (Contributed by Christian Heimes in bpo-28468 [https://bugs.python.org/issue?@action=redirect&bpo=28468].)

pprint

pprint.pprint() now accepts a new underscore_numbers keyword argument. (Contributed by sblondon in bpo-42914 [https://bugs.python.org/issue?@action=redirect&bpo=42914].)

pprint can now pretty-print dataclasses.dataclass instances. (Contributed by Lewis Gaul in bpo-43080 [https://bugs.python.org/issue?@action=redirect&bpo=43080].)

py_compile

Add --quiet option to command-line interface of py_compile. (Contributed by Gregory Schevchenko in bpo-38731 [https://bugs.python.org/issue?@action=redirect&bpo=38731].)

pyclbr

Add an end_lineno attribute to the Function and Class objects in the tree returned by pyclbr.readmodule() and pyclbr.readmodule_ex(). It matches the existing (start) lineno. (Contributed by Aviral Srivastava in bpo-38307 [https://bugs.python.org/issue?@action=redirect&bpo=38307].)

shelve

The shelve module now uses pickle.DEFAULT_PROTOCOL by default instead of pickle protocol 3 when creating shelves. (Contributed by Zackery Spytz in bpo-34204 [https://bugs.python.org/issue?@action=redirect&bpo=34204].)

statistics

Add covariance(), Pearson's correlation(), and simple linear_regression() functions. (Contributed by Tymoteusz Wołodźko in bpo-38490 [https://bugs.python.org/issue?@action=redirect&bpo=38490].)

site

When a module does not define __loader__, fall back to __spec__.loader. (Contributed by Brett Cannon in bpo-42133 [https://bugs.python.org/issue?@action=redirect&bpo=42133].)

socket

The exception socket.timeout is now an alias of TimeoutError. (Contributed by Christian Heimes in bpo-42413 [https://bugs.python.org/issue?@action=redirect&bpo=42413].)

Add option to create MPTCP sockets with IPPROTO_MPTCP (Contributed by Rui Cunha in bpo-43571 [https://bugs.python.org/issue?@action=redirect&bpo=43571].)

Add IP_RECVTOS option to receive the type of service (ToS) or DSCP/ECN fields (Contributed by Georg Sauthoff in bpo-44077 [https://bugs.python.org/issue?@action=redirect&bpo=44077].)

ssl

The ssl module requires OpenSSL 1.1.1 or newer. (Contributed by Christian Heimes in PEP 644 [https://peps.python.org/pep-0644/] and bpo-43669 [https://bugs.python.org/issue?@action=redirect&bpo=43669].)

The ssl module has preliminary support for OpenSSL 3.0.0 and new option OP_IGNORE_UNEXPECTED_EOF. (Contributed by Christian Heimes in bpo-38820 [https://bugs.python.org/issue?@action=redirect&bpo=38820], bpo-43794 [https://bugs.python.org/issue?@action=redirect&bpo=43794], bpo-43788 [https://bugs.python.org/issue?@action=redirect&bpo=43788], bpo-43791 [https://bugs.python.org/issue?@action=redirect&bpo=43791], bpo-43799 [https://bugs.python.org/issue?@action=redirect&bpo=43799], bpo-43920 [https://bugs.python.org/issue?@action=redirect&bpo=43920], bpo-43789 [https://bugs.python.org/issue?@action=redirect&bpo=43789], and bpo-43811 [https://bugs.python.org/issue?@action=redirect&bpo=43811].)

Deprecated function and use of deprecated constants now result in a DeprecationWarning. ssl.SSLContext.options has OP_NO_SSLv2 and OP_NO_SSLv3 set by default and therefore cannot warn about setting the flag again. The deprecation section has a list of deprecated features. (Contributed by Christian Heimes in bpo-43880 [https://bugs.python.org/issue?@action=redirect&bpo=43880].)

The ssl module now has more secure default settings. Ciphers without forward secrecy or SHA-1 MAC are disabled by default. Security level 2 prohibits weak RSA, DH, and ECC keys with less than 112 bits of security. SSLContext defaults to minimum protocol version TLS 1.2. Settings are based on Hynek Schlawack's research. (Contributed by Christian Heimes in bpo-43998 [https://bugs.python.org/issue?@action=redirect&bpo=43998].)

The deprecated protocols SSL 3.0, TLS 1.0, and TLS 1.1 are no longer officially supported. Python does not block them actively. However OpenSSL build options, distro configurations, vendor patches, and cipher suites may prevent a successful handshake.

Add a timeout parameter to the ssl.get_server_certificate() function. (Contributed by Zackery Spytz in bpo-31870 [https://bugs.python.org/issue?@action=redirect&bpo=31870].)

The ssl module uses heap-types and multi-phase initialization. (Contributed by Christian Heimes in bpo-42333 [https://bugs.python.org/issue?@action=redirect&bpo=42333].)

A new verify flag VERIFY_X509_PARTIAL_CHAIN has been added. (Contributed by l0x in bpo-40849 [https://bugs.python.org/issue?@action=redirect&bpo=40849].)

sqlite3

Add audit events for connect/handle(), enable_load_extension(), and load_extension(). (Contributed by Erlend E. Aasland in bpo-43762 [https://bugs.python.org/issue?@action=redirect&bpo=43762].)

sys

Add sys.orig_argv attribute: the list of the original command line arguments passed to the Python executable. (Contributed by Victor Stinner in bpo-23427 [https://bugs.python.org/issue?@action=redirect&bpo=23427].)

Add sys.stdlib_module_names, containing the list of the standard library module names. (Contributed by Victor Stinner in bpo-42955 [https://bugs.python.org/issue?@action=redirect&bpo=42955].)

_thread

_thread.interrupt_main() now takes an optional signal number to simulate (the default is still signal.SIGINT). (Contributed by Antoine Pitrou in bpo-43356 [https://bugs.python.org/issue?@action=redirect&bpo=43356].)

threading

Add threading.gettrace() and threading.getprofile() to retrieve the functions set by threading.settrace() and threading.setprofile() respectively. (Contributed by Mario Corchero in bpo-42251 [https://bugs.python.org/issue?@action=redirect&bpo=42251].)

Add threading.__excepthook__ to allow retrieving the original value of threading.excepthook() in case it is set to a broken or a different value. (Contributed by Mario Corchero in bpo-42308 [https://bugs.python.org/issue?@action=redirect&bpo=42308].)

traceback

The format_exception(), format_exception_only(), and print_exception() functions can now take an exception object as a positional-only argument. (Contributed by Zackery Spytz and Matthias Bussonnier in bpo-26389 [https://bugs.python.org/issue?@action=redirect&bpo=26389].)

types

Reintroduce the types.EllipsisType, types.NoneType and types.NotImplementedType classes, providing a new set of types readily interpretable by type checkers. (Contributed by Bas van Beek in bpo-41810 [https://bugs.python.org/issue?@action=redirect&bpo=41810].)

typing

For major changes, see 型ヒントに関連する新しい機能.

The behavior of typing.Literal was changed to conform with PEP 586 [https://peps.python.org/pep-0586/] and to match the behavior of static type checkers specified in the PEP.

Literal now de-duplicates parameters.

Equality comparisons between Literal objects are now order independent.

Literal comparisons now respect types. For example, Literal[0] == Literal[False] previously evaluated to True. It is now False. To support this change, the internally used type cache now supports differentiating types.

Literal objects will now raise a TypeError exception during equality comparisons if any of their parameters are not hashable. Note that declaring Literal with unhashable parameters will not throw an error:

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

(bpo-42345 [https://bugs.python.org/issue?@action=redirect&bpo=42345] でのYurii Karabasの貢献による)

Add new function typing.is_typeddict() to introspect if an annotation is a typing.TypedDict. (Contributed by Patrick Reader in bpo-41792 [https://bugs.python.org/issue?@action=redirect&bpo=41792].)

Subclasses of typing.Protocol which only have data variables declared will now raise a TypeError when checked with isinstance unless they are decorated with runtime_checkable(). Previously, these checks passed silently. Users should decorate their subclasses with the runtime_checkable() decorator if they want runtime protocols. (Contributed by Yurii Karabas in bpo-38908 [https://bugs.python.org/issue?@action=redirect&bpo=38908].)

Importing from the typing.io and typing.re submodules will now emit DeprecationWarning. These submodules have been deprecated since Python 3.8 and will be removed in a future version of Python. Anything belonging to those submodules should be imported directly from typing instead. (Contributed by Sebastian Rittau in bpo-38291 [https://bugs.python.org/issue?@action=redirect&bpo=38291].)

unittest

Add new method assertNoLogs() to complement the existing assertLogs(). (Contributed by Kit Yan Choi in bpo-39385 [https://bugs.python.org/issue?@action=redirect&bpo=39385].)

urllib.parse

Python versions earlier than Python 3.10 allowed using both ; and & as query parameter separators in urllib.parse.parse_qs() and 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 & as the default. This change also affects cgi.parse() and 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 [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 RFC 3986 [https://datatracker.ietf.org/doc/html/rfc3986.html], ASCII newline \n, \r and tab \t characters are stripped from the URL by the parser in urllib.parse preventing such attacks. The removal characters are controlled by a new module level variable urllib.parse._UNSAFE_URL_BYTES_TO_REMOVE. (See gh-88048 [https://github.com/python/cpython/issues/88048])

xml

Add a LexicalHandler class to the xml.sax.handler module. (Contributed by Jonathan Gossage and Zackery Spytz in bpo-35018 [https://bugs.python.org/issue?@action=redirect&bpo=35018].)

zipimport

Add methods related to PEP 451 [https://peps.python.org/pep-0451/]: find_spec(), zipimport.zipimporter.create_module(), and zipimport.zipimporter.exec_module(). (Contributed by Brett Cannon in bpo-42131 [https://bugs.python.org/issue?@action=redirect&bpo=42131].)

Add invalidate_caches() method. (Contributed by Desmond Cheong in bpo-14678 [https://bugs.python.org/issue?@action=redirect&bpo=14678].)

最適化

Constructors str(), bytes() and bytearray() are now faster (around 30--40% for small objects). (Contributed by Serhiy Storchaka in bpo-41334 [https://bugs.python.org/issue?@action=redirect&bpo=41334].)

The runpy module now imports fewer modules. The python3 -m module-name command startup time is 1.4x faster in average. On Linux, python3 -I -m module-name imports 69 modules on Python 3.9, whereas it only imports 51 modules (-18) on Python 3.10. (Contributed by Victor Stinner in bpo-41006 [https://bugs.python.org/issue?@action=redirect&bpo=41006] and bpo-41718 [https://bugs.python.org/issue?@action=redirect&bpo=41718].)

The LOAD_ATTR instruction now uses new "per opcode cache" mechanism. It is about 36% faster now for regular attributes and 44% faster for slots. (Contributed by Pablo Galindo and Yury Selivanov in bpo-42093 [https://bugs.python.org/issue?@action=redirect&bpo=42093] and Guido van Rossum in bpo-42927 [https://bugs.python.org/issue?@action=redirect&bpo=42927], based on ideas implemented originally in PyPy and MicroPython.)

When building Python with --enable-optimizations now -fno-semantic-interposition is added to both the compile and link line. This speeds builds of the Python interpreter created with --enable-shared with gcc by up to 30%. See this article [https://developers.redhat.com/blog/2020/06/25/red-hat-enterprise-linux-8-2-brings-faster-python-3-8-run-speeds/] for more details. (Contributed by Victor Stinner and Pablo Galindo in bpo-38980 [https://bugs.python.org/issue?@action=redirect&bpo=38980].)

Use a new output buffer management code for bz2 / lzma / zlib modules, and add .readall() function to _compression.DecompressReader class. bz2 decompression is now 1.09x ~ 1.17x faster, lzma decompression 1.20x ~ 1.32x faster, GzipFile.read(-1) 1.11x ~ 1.18x faster. (Contributed by Ma Lin, reviewed by Gregory P. Smith, in bpo-41486 [https://bugs.python.org/issue?@action=redirect&bpo=41486])

When using stringized annotations, annotations dicts for functions are no longer created when the function is created. Instead, they are stored as a tuple of strings, and the function object lazily converts this into the annotations dict on demand. This optimization cuts the CPU time needed to define an annotated function by half. (Contributed by Yurii Karabas and Inada Naoki in bpo-42202 [https://bugs.python.org/issue?@action=redirect&bpo=42202].)

Substring search functions such as str1 in str2 and str2.find(str1) now sometimes use Crochemore & Perrin's "Two-Way" string searching algorithm to avoid quadratic behavior on long strings. (Contributed by Dennis Sweeney in bpo-41972 [https://bugs.python.org/issue?@action=redirect&bpo=41972])

Add micro-optimizations to _PyType_Lookup() to improve type attribute cache lookup performance in the common case of cache hits. This makes the interpreter 1.04 times faster on average. (Contributed by Dino Viehland in bpo-43452 [https://bugs.python.org/issue?@action=redirect&bpo=43452].)

The following built-in functions now support the faster PEP 590 [https://peps.python.org/pep-0590/] vectorcall calling convention: map(), filter(), reversed(), bool() and float(). (Contributed by Donghee Na and Jeroen Demeyer in bpo-43575 [https://bugs.python.org/issue?@action=redirect&bpo=43575], bpo-43287 [https://bugs.python.org/issue?@action=redirect&bpo=43287], bpo-41922 [https://bugs.python.org/issue?@action=redirect&bpo=41922], bpo-41873 [https://bugs.python.org/issue?@action=redirect&bpo=41873] and bpo-41870 [https://bugs.python.org/issue?@action=redirect&bpo=41870].)

BZ2File performance is improved by removing internal RLock. This makes BZ2File thread unsafe in the face of multiple simultaneous readers or writers, just like its equivalent classes in gzip and lzma have always been. (Contributed by Inada Naoki in bpo-43785 [https://bugs.python.org/issue?@action=redirect&bpo=43785].)

非推奨

Currently Python accepts numeric literals immediately followed by keywords, for example 0in x, 1or x, 0if 1else 2. It allows confusing and ambiguous expressions like [0x1for x in y] (which can be interpreted as [0x1 for x in y] or [0x1f or x in y]). Starting in this release, a deprecation warning is raised if the numeric literal is immediately followed by one of keywords and, else, for, if, in, is and or. In future releases it will be changed to syntax warning, and finally to syntax error. (Contributed by Serhiy Storchaka in bpo-43833 [https://bugs.python.org/issue?@action=redirect&bpo=43833].)

Starting in this release, there will be a concerted effort to begin cleaning up old import semantics that were kept for Python 2.7 compatibility. Specifically, find_loader()/find_module() (superseded by find_spec()), load_module() (superseded by exec_module()), module_repr() (which the import system takes care of for you), the __package__ attribute (superseded by __spec__.parent), the __loader__ attribute (superseded by __spec__.loader), and the __cached__ attribute (superseded by __spec__.cached) will slowly be removed (as well as other classes and methods in importlib). ImportWarning and/or DeprecationWarning will be raised as appropriate to help identify code which needs updating during this transition.

The entire distutils namespace is deprecated, to be removed in Python 3.12. Refer to the module changes section for more information.

Non-integer arguments to random.randrange() are deprecated. The ValueError is deprecated in favor of a TypeError. (Contributed by Serhiy Storchaka and Raymond Hettinger in bpo-37319 [https://bugs.python.org/issue?@action=redirect&bpo=37319].)

The various load_module() methods of importlib have been documented as deprecated since Python 3.6, but will now also trigger a DeprecationWarning. Use exec_module() instead. (Contributed by Brett Cannon in bpo-26131 [https://bugs.python.org/issue?@action=redirect&bpo=26131].)

zimport.zipimporter.load_module() has been deprecated in preference for exec_module(). (Contributed by Brett Cannon in bpo-26131 [https://bugs.python.org/issue?@action=redirect&bpo=26131].)

The use of load_module() by the import system now triggers an ImportWarning as exec_module() is preferred. (Contributed by Brett Cannon in bpo-26131 [https://bugs.python.org/issue?@action=redirect&bpo=26131].)

The use of importlib.abc.MetaPathFinder.find_module() and importlib.abc.PathEntryFinder.find_module() by the import system now trigger an ImportWarning as importlib.abc.MetaPathFinder.find_spec() and importlib.abc.PathEntryFinder.find_spec() are preferred, respectively. You can use importlib.util.spec_from_loader() to help in porting. (Contributed by Brett Cannon in bpo-42134 [https://bugs.python.org/issue?@action=redirect&bpo=42134].)

The use of importlib.abc.PathEntryFinder.find_loader() by the import system now triggers an ImportWarning as importlib.abc.PathEntryFinder.find_spec() is preferred. You can use importlib.util.spec_from_loader() to help in porting. (Contributed by Brett Cannon in bpo-43672 [https://bugs.python.org/issue?@action=redirect&bpo=43672].)

The various implementations of importlib.abc.MetaPathFinder.find_module() ( importlib.machinery.BuiltinImporter.find_module(), importlib.machinery.FrozenImporter.find_module(), importlib.machinery.WindowsRegistryFinder.find_module(), importlib.machinery.PathFinder.find_module(), importlib.abc.MetaPathFinder.find_module() ), importlib.abc.PathEntryFinder.find_module() ( importlib.machinery.FileFinder.find_module() ), and importlib.abc.PathEntryFinder.find_loader() ( importlib.machinery.FileFinder.find_loader() ) now raise DeprecationWarning and are slated for removal in Python 3.12 (previously they were documented as deprecated in Python 3.4). (Contributed by Brett Cannon in bpo-42135 [https://bugs.python.org/issue?@action=redirect&bpo=42135].)

importlib.abc.Finder is deprecated (including its sole method, find_module()). Both importlib.abc.MetaPathFinder and importlib.abc.PathEntryFinder no longer inherit from the class. Users should inherit from one of these two classes as appropriate instead. (Contributed by Brett Cannon in bpo-42135 [https://bugs.python.org/issue?@action=redirect&bpo=42135].)

The deprecations of imp, importlib.find_loader(), importlib.util.set_package_wrapper(), importlib.util.set_loader_wrapper(), importlib.util.module_for_loader(), pkgutil.ImpImporter, and pkgutil.ImpLoader have all been updated to list Python 3.12 as the slated version of removal (they began raising DeprecationWarning in previous versions of Python). (Contributed by Brett Cannon in bpo-43720 [https://bugs.python.org/issue?@action=redirect&bpo=43720].)

The import system now uses the __spec__ attribute on modules before falling back on module_repr() for a module's __repr__() method. Removal of the use of module_repr() is scheduled for Python 3.12. (Contributed by Brett Cannon in bpo-42137 [https://bugs.python.org/issue?@action=redirect&bpo=42137].)

importlib.abc.Loader.module_repr(), importlib.machinery.FrozenLoader.module_repr(), and importlib.machinery.BuiltinLoader.module_repr() are deprecated and slated for removal in Python 3.12. (Contributed by Brett Cannon in bpo-42136 [https://bugs.python.org/issue?@action=redirect&bpo=42136].)

sqlite3.OptimizedUnicode has been undocumented and obsolete since Python 3.3, when it was made an alias to str. It is now deprecated, scheduled for removal in Python 3.12. (Contributed by Erlend E. Aasland in bpo-42264 [https://bugs.python.org/issue?@action=redirect&bpo=42264].)

The undocumented built-in function sqlite3.enable_shared_cache is now deprecated, scheduled for removal in Python 3.12. Its use is strongly discouraged by the SQLite3 documentation. See the SQLite3 docs [https://sqlite.org/c3ref/enable_shared_cache.html] for more details. If a shared cache must be used, open the database in URI mode using the cache=shared query parameter. (Contributed by Erlend E. Aasland in bpo-24464 [https://bugs.python.org/issue?@action=redirect&bpo=24464].)

The following threading methods are now deprecated:

threading.currentThread => threading.current_thread()

threading.activeCount => threading.active_count()

threading.Condition.notifyAll => threading.Condition.notify_all()

threading.Event.isSet => threading.Event.is_set()

threading.Thread.setName => threading.Thread.name

threading.thread.getName => threading.Thread.name

threading.Thread.isDaemon => threading.Thread.daemon

threading.Thread.setDaemon => threading.Thread.daemon

(Contributed by Jelle Zijlstra in gh-87889 [https://github.com/python/cpython/issues/87889].)

pathlib.Path.link_to() is deprecated and slated for removal in Python 3.12. Use pathlib.Path.hardlink_to() instead. (Contributed by Barney Gale in bpo-39950 [https://bugs.python.org/issue?@action=redirect&bpo=39950].)

cgi.log() is deprecated and slated for removal in Python 3.12. (Contributed by Inada Naoki in bpo-41139 [https://bugs.python.org/issue?@action=redirect&bpo=41139].)

The following ssl features have been deprecated since Python 3.6, Python 3.7, or OpenSSL 1.1.0 and will be removed in 3.11:

OP_NO_SSLv2, OP_NO_SSLv3, OP_NO_TLSv1, OP_NO_TLSv1_1, OP_NO_TLSv1_2, and OP_NO_TLSv1_3 are replaced by minimum_version and maximum_version.

PROTOCOL_SSLv2, PROTOCOL_SSLv3, PROTOCOL_SSLv23, PROTOCOL_TLSv1, PROTOCOL_TLSv1_1, PROTOCOL_TLSv1_2, and PROTOCOL_TLS are deprecated in favor of PROTOCOL_TLS_CLIENT and PROTOCOL_TLS_SERVER

wrap_socket() is replaced by ssl.SSLContext.wrap_socket()

match_hostname()

RAND_pseudo_bytes(), RAND_egd()

NPN features like ssl.SSLSocket.selected_npn_protocol() and ssl.SSLContext.set_npn_protocols() are replaced by ALPN.

The threading debug (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. (Contributed by Victor Stinner in bpo-44584 [https://bugs.python.org/issue?@action=redirect&bpo=44584].)

Importing from the typing.io and typing.re submodules will now emit DeprecationWarning. These submodules will be removed in a future version of Python. Anything belonging to these submodules should be imported directly from typing instead. (Contributed by Sebastian Rittau in bpo-38291 [https://bugs.python.org/issue?@action=redirect&bpo=38291].)

削除

Removed special methods __int__, __float__, __floordiv__, __mod__, __divmod__, __rfloordiv__, __rmod__ and __rdivmod__ of the complex class. They always raised a TypeError. (Contributed by Serhiy Storchaka in bpo-41974 [https://bugs.python.org/issue?@action=redirect&bpo=41974].)

The ParserBase.error() method from the private and undocumented _markupbase module has been removed. html.parser.HTMLParser is the only subclass of ParserBase and its error() implementation was already removed in Python 3.5. (Contributed by Berker Peksag in bpo-31844 [https://bugs.python.org/issue?@action=redirect&bpo=31844].)

Removed the unicodedata.ucnhash_CAPI attribute which was an internal PyCapsule object. The related private _PyUnicode_Name_CAPI structure was moved to the internal C API. (Contributed by Victor Stinner in bpo-42157 [https://bugs.python.org/issue?@action=redirect&bpo=42157].)

Removed the parser module, which was deprecated in 3.9 due to the switch to the new PEG parser, as well as all the C source and header files that were only being used by the old parser, including node.h, parser.h, graminit.h and grammar.h.

Removed the Public C API functions PyParser_SimpleParseStringFlags, PyParser_SimpleParseStringFlagsFilename, PyParser_SimpleParseFileFlags and PyNode_Compile that were deprecated in 3.9 due to the switch to the new PEG parser.

Removed the formatter module, which was deprecated in Python 3.4. It is somewhat obsolete, little used, and not tested. It was originally scheduled to be removed in Python 3.6, but such removals were delayed until after Python 2.7 EOL. Existing users should copy whatever classes they use into their code. (Contributed by Donghee Na and Terry J. Reedy in bpo-42299 [https://bugs.python.org/issue?@action=redirect&bpo=42299].)

Removed the PyModule_GetWarningsModule() function that was useless now due to the _warnings module was converted to a builtin module in 2.6. (Contributed by Hai Shi in bpo-42599 [https://bugs.python.org/issue?@action=redirect&bpo=42599].)

Remove deprecated aliases to コレクション抽象基底クラス from the collections module. (Contributed by Victor Stinner in bpo-37324 [https://bugs.python.org/issue?@action=redirect&bpo=37324].)

The loop parameter has been removed from most of asyncio's high-level API following deprecation in Python 3.8. The motivation behind this change is multifold:

This simplifies the high-level API.

The functions in the high-level API have been implicitly getting the current thread's running event loop since Python 3.7. There isn't a need to pass the event loop to the API in most normal use cases.

Event loop passing is error-prone especially when dealing with loops running in different threads.

Note that the low-level API will still accept loop. See Python API の変更 for examples of how to replace existing code.

(Contributed by Yurii Karabas, Andrew Svetlov, Yury Selivanov and Kyle Stanley in bpo-42392 [https://bugs.python.org/issue?@action=redirect&bpo=42392].)

Porting to Python 3.10

このセクションでは前述の変更とバグフィックスにより必要となるかもしれないコードの変更を列挙します:

Changes in the Python syntax

Deprecation warning is now emitted when compiling previously valid syntax if the numeric literal is immediately followed by a keyword (like in 0in x). In future releases it will be changed to syntax warning, and finally to a syntax error. To get rid of the warning and make the code compatible with future releases just add a space between the numeric literal and the following keyword. (Contributed by Serhiy Storchaka in bpo-43833 [https://bugs.python.org/issue?@action=redirect&bpo=43833].)

Python API の変更

The etype parameters of the format_exception(), format_exception_only(), and print_exception() functions in the traceback module have been renamed to exc. (Contributed by Zackery Spytz and Matthias Bussonnier in bpo-26389 [https://bugs.python.org/issue?@action=redirect&bpo=26389].)

atexit: At Python exit, if a callback registered with atexit.register() fails, its exception is now logged. Previously, only some exceptions were logged, and the last exception was always silently ignored. (Contributed by Victor Stinner in bpo-42639 [https://bugs.python.org/issue?@action=redirect&bpo=42639].)

collections.abc.Callable generic now flattens type parameters, similar to what typing.Callable currently does. This means that collections.abc.Callable[[int, str], str] will have __args__ of (int, str, str); previously this was ([int, str], str). Code which accesses the arguments via typing.get_args() or __args__ need to account for this change. Furthermore, TypeError may be raised for invalid forms of parameterizing collections.abc.Callable which may have passed silently in Python 3.9. (Contributed by Ken Jin in bpo-42195 [https://bugs.python.org/issue?@action=redirect&bpo=42195].)

socket.htons() and socket.ntohs() now raise OverflowError instead of DeprecationWarning if the given parameter will not fit in a 16-bit unsigned integer. (Contributed by Erlend E. Aasland in bpo-42393 [https://bugs.python.org/issue?@action=redirect&bpo=42393].)

The loop parameter has been removed from most of asyncio's high-level API following deprecation in Python 3.8.

A coroutine that currently looks like this:

async def foo(loop):
    await asyncio.sleep(1, loop=loop)

Should be replaced with this:

async def foo():
    await asyncio.sleep(1)

If foo() was specifically designed not to run in the current thread's running event loop (e.g. running in another thread's event loop), consider using asyncio.run_coroutine_threadsafe() instead.

(Contributed by Yurii Karabas, Andrew Svetlov, Yury Selivanov and Kyle Stanley in bpo-42392 [https://bugs.python.org/issue?@action=redirect&bpo=42392].)

The types.FunctionType constructor now inherits the current builtins if the globals dictionary has no "__builtins__" key, rather than using {"None": None} as builtins: same behavior as eval() and exec() functions. Defining a function with def function(...): ... in Python is not affected, globals cannot be overridden with this syntax: it also inherits the current builtins. (Contributed by Victor Stinner in bpo-42990 [https://bugs.python.org/issue?@action=redirect&bpo=42990].)

C API の変更

The C API functions PyParser_SimpleParseStringFlags, PyParser_SimpleParseStringFlagsFilename, PyParser_SimpleParseFileFlags, PyNode_Compile and the type used by these functions, struct _node, were removed due to the switch to the new PEG parser.

Source should be now be compiled directly to a code object using, for example, Py_CompileString(). The resulting code object can then be evaluated using, for example, PyEval_EvalCode().

Specifically:

A call to PyParser_SimpleParseStringFlags followed by PyNode_Compile can be replaced by calling Py_CompileString().

There is no direct replacement for PyParser_SimpleParseFileFlags. To compile code from a FILE * argument, you will need to read the file in C and pass the resulting buffer to Py_CompileString().

To compile a file given a char * filename, explicitly open the file, read it and compile the result. One way to do this is using the io module with PyImport_ImportModule(), PyObject_CallMethod(), PyBytes_AsString() and Py_CompileString(), as sketched below. (Declarations and error handling are omitted.)

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);

For FrameObject objects, the f_lasti member now represents a wordcode offset instead of a simple offset into the bytecode string. This means that this number needs to be multiplied by 2 to be used with APIs that expect a byte offset instead (like PyCode_Addr2Line() for example). Notice as well that the f_lasti member of FrameObject objects is not considered stable: please use PyFrame_GetLineNumber() instead.

CPython バイトコードの変更

The MAKE_FUNCTION instruction now accepts either a dict or a tuple of strings as the function's annotations. (Contributed by Yurii Karabas and Inada Naoki in bpo-42202 [https://bugs.python.org/issue?@action=redirect&bpo=42202].)

Build Changes

PEP 644 [https://peps.python.org/pep-0644/]: Python now requires OpenSSL 1.1.1 or newer. OpenSSL 1.0.2 is no longer supported. (Contributed by Christian Heimes in bpo-43669 [https://bugs.python.org/issue?@action=redirect&bpo=43669].)

The C99 functions snprintf() and vsnprintf() are now required to build Python. (Contributed by Victor Stinner in bpo-36020 [https://bugs.python.org/issue?@action=redirect&bpo=36020].)

sqlite3 requires SQLite 3.7.15 or higher. (Contributed by Sergey Fedoseev and Erlend E. Aasland in bpo-40744 [https://bugs.python.org/issue?@action=redirect&bpo=40744] and bpo-40810 [https://bugs.python.org/issue?@action=redirect&bpo=40810].)

The atexit module must now always be built as a built-in module. (Contributed by Victor Stinner in bpo-42639 [https://bugs.python.org/issue?@action=redirect&bpo=42639].)

Add --disable-test-modules option to the configure script: don't build nor install test modules. (Contributed by Xavier de Gaye, Thomas Petazzoni and Peixing Xin in bpo-27640 [https://bugs.python.org/issue?@action=redirect&bpo=27640].)

Add --with-wheel-pkg-dir=PATH option to the ./configure script. If specified, the ensurepip module looks for setuptools and 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 /usr/share/python-wheels/ directory and don't install the ensurepip._bundled package.

(Contributed by Victor Stinner in bpo-42856 [https://bugs.python.org/issue?@action=redirect&bpo=42856].)

Add a new configure --without-static-libpython option to not build the libpythonMAJOR.MINOR.a static library and not install the python.o object file.

(Contributed by Victor Stinner in bpo-43103 [https://bugs.python.org/issue?@action=redirect&bpo=43103].)

The configure script now uses the pkg-config utility, if available, to detect the location of Tcl/Tk headers and libraries. As before, those locations can be explicitly specified with the --with-tcltk-includes and --with-tcltk-libs configuration options. (Contributed by Manolis Stamatogiannakis in bpo-42603 [https://bugs.python.org/issue?@action=redirect&bpo=42603].)

Add --with-openssl-rpath option to configure script. The option simplifies building Python with a custom OpenSSL installation, e.g. ./configure --with-openssl=/path/to/openssl --with-openssl-rpath=auto. (Contributed by Christian Heimes in bpo-43466 [https://bugs.python.org/issue?@action=redirect&bpo=43466].)

C API の変更

PEP 652: Maintaining the Stable ABI

The Stable ABI (Application Binary Interface) for extension modules or embedding Python is now explicitly defined. C API の安定性 describes C API and ABI stability guarantees along with best practices for using the Stable ABI.

(Contributed by Petr Viktorin in PEP 652 [https://peps.python.org/pep-0652/] and bpo-43795 [https://bugs.python.org/issue?@action=redirect&bpo=43795].)

新しい機能

The result of PyNumber_Index() now always has exact type int. Previously, the result could have been an instance of a subclass of int. (Contributed by Serhiy Storchaka in bpo-40792 [https://bugs.python.org/issue?@action=redirect&bpo=40792].)

Add a new orig_argv member to the PyConfig structure: the list of the original command line arguments passed to the Python executable. (Contributed by Victor Stinner in bpo-23427 [https://bugs.python.org/issue?@action=redirect&bpo=23427].)

The PyDateTime_DATE_GET_TZINFO() and PyDateTime_TIME_GET_TZINFO() macros have been added for accessing the tzinfo attributes of datetime.datetime and datetime.time objects. (Contributed by Zackery Spytz in bpo-30155 [https://bugs.python.org/issue?@action=redirect&bpo=30155].)

Add a PyCodec_Unregister() function to unregister a codec search function. (Contributed by Hai Shi in bpo-41842 [https://bugs.python.org/issue?@action=redirect&bpo=41842].)

The PyIter_Send() function was added to allow sending value into iterator without raising StopIteration exception. (Contributed by Vladimir Matveev in bpo-41756 [https://bugs.python.org/issue?@action=redirect&bpo=41756].)

Add PyUnicode_AsUTF8AndSize() to the limited C API. (Contributed by Alex Gaynor in bpo-41784 [https://bugs.python.org/issue?@action=redirect&bpo=41784].)

Add PyModule_AddObjectRef() function: similar to PyModule_AddObject() but don't steal a reference to the value on success. (Contributed by Victor Stinner in bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741].)

Add Py_NewRef() and Py_XNewRef() functions to increment the reference count of an object and return the object. (Contributed by Victor Stinner in bpo-42262 [https://bugs.python.org/issue?@action=redirect&bpo=42262].)

The PyType_FromSpecWithBases() and PyType_FromModuleAndSpec() functions now accept a single class as the bases argument. (Contributed by Serhiy Storchaka in bpo-42423 [https://bugs.python.org/issue?@action=redirect&bpo=42423].)

The PyType_FromModuleAndSpec() function now accepts NULL tp_doc slot. (Contributed by Hai Shi in bpo-41832 [https://bugs.python.org/issue?@action=redirect&bpo=41832].)

The PyType_GetSlot() function can accept static types. (Contributed by Hai Shi and Petr Viktorin in bpo-41073 [https://bugs.python.org/issue?@action=redirect&bpo=41073].)

Add a new PySet_CheckExact() function to the C-API to check if an object is an instance of set but not an instance of a subtype. (Contributed by Pablo Galindo in bpo-43277 [https://bugs.python.org/issue?@action=redirect&bpo=43277].)

Add PyErr_SetInterruptEx() which allows passing a signal number to simulate. (Contributed by Antoine Pitrou in bpo-43356 [https://bugs.python.org/issue?@action=redirect&bpo=43356].)

The limited C API is now supported if Python is built in debug mode (if the Py_DEBUG macro is defined). In the limited C API, the Py_INCREF() and Py_DECREF() functions are now implemented as opaque function calls, rather than accessing directly the PyObject.ob_refcnt member, if Python is built in debug mode and the Py_LIMITED_API macro targets Python 3.10 or newer. It became possible to support the limited C API in debug mode because the PyObject structure is the same in release and debug mode since Python 3.8 (see bpo-36465 [https://bugs.python.org/issue?@action=redirect&bpo=36465]).

The limited C API is still not supported in the --with-trace-refs special build (Py_TRACE_REFS macro). (Contributed by Victor Stinner in bpo-43688 [https://bugs.python.org/issue?@action=redirect&bpo=43688].)

Add the Py_Is(x, y) function to test if the x object is the y object, the same as x is y in Python. Add also the Py_IsNone(), Py_IsTrue(), Py_IsFalse() functions to test if an object is, respectively, the None singleton, the True singleton or the False singleton. (Contributed by Victor Stinner in bpo-43753 [https://bugs.python.org/issue?@action=redirect&bpo=43753].)

Add new functions to control the garbage collector from C code: PyGC_Enable(), PyGC_Disable(), PyGC_IsEnabled(). These functions allow to activate, deactivate and query the state of the garbage collector from C code without having to import the gc module.

Add a new Py_TPFLAGS_DISALLOW_INSTANTIATION type flag to disallow creating type instances. (Contributed by Victor Stinner in bpo-43916 [https://bugs.python.org/issue?@action=redirect&bpo=43916].)

Add a new Py_TPFLAGS_IMMUTABLETYPE type flag for creating immutable type objects: type attributes cannot be set nor deleted. (Contributed by Victor Stinner and Erlend E. Aasland in bpo-43908 [https://bugs.python.org/issue?@action=redirect&bpo=43908].)

Porting to Python 3.10

The PY_SSIZE_T_CLEAN macro must now be defined to use PyArg_ParseTuple() and Py_BuildValue() formats which use #: es#, et#, s#, u#, y#, z#, U# and Z#. See 引数の解釈と値の構築 and PEP 353 [https://peps.python.org/pep-0353/]. (Contributed by Victor Stinner in bpo-40943 [https://bugs.python.org/issue?@action=redirect&bpo=40943].)

Since Py_REFCNT() is changed to the inline static function, Py_REFCNT(obj) = new_refcnt must be replaced with Py_SET_REFCNT(obj, new_refcnt): see Py_SET_REFCNT() (available since Python 3.9). For backward compatibility, this macro can be used:

#if PY_VERSION_HEX < 0x030900A4
#  define Py_SET_REFCNT(obj, refcnt) ((Py_REFCNT(obj) = (refcnt)), (void)0)
#endif

(Contributed by Victor Stinner in bpo-39573 [https://bugs.python.org/issue?@action=redirect&bpo=39573].)

Calling PyDict_GetItem() without GIL held had been allowed for historical reason. It is no longer allowed. (Contributed by Victor Stinner in bpo-40839 [https://bugs.python.org/issue?@action=redirect&bpo=40839].)

PyUnicode_FromUnicode(NULL, size) and PyUnicode_FromStringAndSize(NULL, size) raise DeprecationWarning now. Use PyUnicode_New() to allocate Unicode object without initial data. (Contributed by Inada Naoki in bpo-36346 [https://bugs.python.org/issue?@action=redirect&bpo=36346].)

The private _PyUnicode_Name_CAPI structure of the PyCapsule API unicodedata.ucnhash_CAPI has been moved to the internal C API. (Contributed by Victor Stinner in bpo-42157 [https://bugs.python.org/issue?@action=redirect&bpo=42157].)

Py_GetPath(), Py_GetPrefix(), Py_GetExecPrefix(), Py_GetProgramFullPath(), Py_GetPythonHome() and Py_GetProgramName() functions now return NULL if called before Py_Initialize() (before Python is initialized). Use the new Python 初期化設定 API to get the Python Path Configuration. (Contributed by Victor Stinner in bpo-42260 [https://bugs.python.org/issue?@action=redirect&bpo=42260].)

PyList_SET_ITEM(), PyTuple_SET_ITEM() and PyCell_SET() macros can no longer be used as l-value or r-value. For example, x = PyList_SET_ITEM(a, b, c) and PyList_SET_ITEM(a, b, c) = x now fail with a compiler error. It prevents bugs like if (PyList_SET_ITEM (a, b, c) < 0) ... test. (Contributed by Zackery Spytz and Victor Stinner in bpo-30459 [https://bugs.python.org/issue?@action=redirect&bpo=30459].)

The non-limited API files odictobject.h, parser_interface.h, picklebufobject.h, pyarena.h, pyctype.h, pydebug.h, pyfpe.h, and pytime.h have been moved to the Include/cpython directory. These files must not be included directly, as they are already included in Python.h; see インクルードファイル. If they have been included directly, consider including Python.h instead. (Contributed by Nicholas Sim in bpo-35134 [https://bugs.python.org/issue?@action=redirect&bpo=35134].)

Use the Py_TPFLAGS_IMMUTABLETYPE type flag to create immutable type objects. Do not rely on Py_TPFLAGS_HEAPTYPE to decide if a type object is mutable or not; check if Py_TPFLAGS_IMMUTABLETYPE is set instead. (Contributed by Victor Stinner and Erlend E. Aasland in bpo-43908 [https://bugs.python.org/issue?@action=redirect&bpo=43908].)

The undocumented function Py_FrozenMain has been removed from the limited API. The function is mainly useful for custom builds of Python. (Contributed by Petr Viktorin in bpo-26241 [https://bugs.python.org/issue?@action=redirect&bpo=26241].)

非推奨

The PyUnicode_InternImmortal() function is now deprecated and will be removed in Python 3.12: use PyUnicode_InternInPlace() instead. (Contributed by Victor Stinner in bpo-41692 [https://bugs.python.org/issue?@action=redirect&bpo=41692].)

削除

Removed Py_UNICODE_str* functions manipulating Py_UNICODE* strings. (Contributed by Inada Naoki in bpo-41123 [https://bugs.python.org/issue?@action=redirect&bpo=41123].)

Py_UNICODE_strlen: use PyUnicode_GetLength() or PyUnicode_GET_LENGTH

Py_UNICODE_strcat: use PyUnicode_CopyCharacters() or PyUnicode_FromFormat()

Py_UNICODE_strcpy, Py_UNICODE_strncpy: use PyUnicode_CopyCharacters() or PyUnicode_Substring()

Py_UNICODE_strcmp: use PyUnicode_Compare()

Py_UNICODE_strncmp: use PyUnicode_Tailmatch()

Py_UNICODE_strchr, Py_UNICODE_strrchr: use PyUnicode_FindChar()

Removed PyUnicode_GetMax(). Please migrate to new (PEP 393 [https://peps.python.org/pep-0393/]) APIs. (Contributed by Inada Naoki in bpo-41103 [https://bugs.python.org/issue?@action=redirect&bpo=41103].)

Removed PyLong_FromUnicode(). Please migrate to PyLong_FromUnicodeObject(). (Contributed by Inada Naoki in bpo-41103 [https://bugs.python.org/issue?@action=redirect&bpo=41103].)

Removed PyUnicode_AsUnicodeCopy(). Please use PyUnicode_AsUCS4Copy() or PyUnicode_AsWideCharString() (Contributed by Inada Naoki in bpo-41103 [https://bugs.python.org/issue?@action=redirect&bpo=41103].)

Removed _Py_CheckRecursionLimit variable: it has been replaced by ceval.recursion_limit of the PyInterpreterState structure. (Contributed by Victor Stinner in bpo-41834 [https://bugs.python.org/issue?@action=redirect&bpo=41834].)

Removed undocumented macros Py_ALLOW_RECURSION and Py_END_ALLOW_RECURSION and the recursion_critical field of the PyInterpreterState structure. (Contributed by Serhiy Storchaka in bpo-41936 [https://bugs.python.org/issue?@action=redirect&bpo=41936].)

Removed the undocumented PyOS_InitInterrupts() function. Initializing Python already implicitly installs signal handlers: see PyConfig.install_signal_handlers. (Contributed by Victor Stinner in bpo-41713 [https://bugs.python.org/issue?@action=redirect&bpo=41713].)

Remove the PyAST_Validate() function. It is no longer possible to build a AST object (mod_ty type) with the public C API. The function was already excluded from the limited C API (PEP 384 [https://peps.python.org/pep-0384/]). (Contributed by Victor Stinner in bpo-43244 [https://bugs.python.org/issue?@action=redirect&bpo=43244].)

Remove the symtable.h header file and the undocumented functions:

PyST_GetScope()

PySymtable_Build()

PySymtable_BuildObject()

PySymtable_Free()

Py_SymtableString()

Py_SymtableStringObject()

The Py_SymtableString() function was part the stable ABI by mistake but it could not be used, because the symtable.h header file was excluded from the limited C API.

Use Python symtable module instead. (Contributed by Victor Stinner in bpo-43244 [https://bugs.python.org/issue?@action=redirect&bpo=43244].)

Remove PyOS_ReadlineFunctionPointer() from the limited C API headers and from python3.dll, the library that provides the stable ABI on Windows. Since the function takes a FILE* argument, its ABI stability cannot be guaranteed. (Contributed by Petr Viktorin in bpo-43868 [https://bugs.python.org/issue?@action=redirect&bpo=43868].)

Remove ast.h, asdl.h, and 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 Py and so could create names conflicts. For example, Python-ast.h defined a Yield macro which was conflict with the Yield name used by the Windows <winbase.h> header. Use the Python ast module instead. (Contributed by Victor Stinner in bpo-43244 [https://bugs.python.org/issue?@action=redirect&bpo=43244].)

Remove the compiler and parser functions using struct _mod type, because the public AST C API was removed:

PyAST_Compile()

PyAST_CompileEx()

PyAST_CompileObject()

PyFuture_FromAST()

PyFuture_FromASTObject()

PyParser_ASTFromFile()

PyParser_ASTFromFileObject()

PyParser_ASTFromFilename()

PyParser_ASTFromString()

PyParser_ASTFromStringObject()

These functions were undocumented and excluded from the limited C API. (Contributed by Victor Stinner in bpo-43244 [https://bugs.python.org/issue?@action=redirect&bpo=43244].)

Remove the pyarena.h header file with functions:

PyArena_New()

PyArena_Free()

PyArena_Malloc()

PyArena_AddPyObject()

These functions were undocumented, excluded from the limited C API, and were only used internally by the compiler. (Contributed by Victor Stinner in bpo-43244 [https://bugs.python.org/issue?@action=redirect&bpo=43244].)

The PyThreadState.use_tracing member has been removed to optimize Python. (Contributed by Mark Shannon in bpo-43760 [https://bugs.python.org/issue?@action=redirect&bpo=43760].)

Notable security feature in 3.10.7

Converting between int and str in bases other than 2 (binary), 4, 8 (octal), 16 (hexadecimal), or 32 such as base 10 (decimal) now raises a 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 CVE-2020-10735 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-10735]. This limit can be configured or disabled by environment variable, command line flag, or sys APIs. See the integer string conversion length limitation documentation. The default limit is 4300 digits in string form.

Notable security feature in 3.10.8

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). (Contributed by Petr Viktorin in gh-98966 [https://github.com/python/cpython/issues/98966].)

Notable changes in 3.10.12

tarfile

The extraction methods in tarfile, and 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 Extraction filters for details. In Python 3.12, use without the filter argument will show a DeprecationWarning. In Python 3.14, the default will switch to 'data'. (Contributed by Petr Viktorin in PEP 706 [https://peps.python.org/pep-0706/].)

What's New In Python 3.9

編集者:

Łukasz Langa

This article explains the new features in Python 3.9, compared to 3.8. Python 3.9 was released on October 5, 2020. For full details, see the changelog.

参考

PEP 596 [https://peps.python.org/pep-0596/] - Python 3.9 リリーススケジュール

概要 -- リリースハイライト

新たな文法機能:

PEP 584 [https://peps.python.org/pep-0584/]、 dict に和集合の演算子が追加されました。

PEP 585 [https://peps.python.org/pep-0585/]、標準コレクション型の型ヒントにおける総称型 (generics) の使用。

PEP 614 [https://peps.python.org/pep-0614/]、デコレータの適用における文法的制約の緩和。

新たな組み込み機能:

PEP 616 [https://peps.python.org/pep-0616/]、prefixとsuffixを削除する文字列メソッド。

標準ライブラリの新機能:

PEP 593 [https://peps.python.org/pep-0593/]、より柔軟な変数・関数アノテーション (訳注: Annotated の導入)。

os.pidfd_open() が追加され、レースやシグナルを使わずにプロセス管理ができるようになりました。

インタプリタの改善:

PEP 573 [https://peps.python.org/pep-0573/], fast access to module state from methods of C extension types;

PEP 617 [https://peps.python.org/pep-0617/]、CPython における PEG (Parser Expression Grammar) ベースの新しい構文解析器の使用。

いくつかのPythonの組み込み型（range, tuple, set, frozenset, list, dict） を PEP 590 [https://peps.python.org/pep-0590/] vectorcall を用いて高速化しました。

garbage collection does not block on resurrected objects;

a number of Python modules (_abc, audioop, _bz2, _codecs, _contextvars, _crypt, _functools, _json, _locale, math, operator, resource, time, _weakref) now use multiphase initialization as defined by PEP 489;

a number of standard library modules (audioop, ast, grp, _hashlib, pwd, _posixsubprocess, random, select, struct, termios, zlib) are now using the stable ABI defined by PEP 384.

新たなライブラリモジュール:

PEP 615 [https://peps.python.org/pep-0615/]、IANAのTime Zone Databaseが標準ライブラリの zoneinfo モジュールで提供されるようになりました。

an implementation of a topological sort of a graph is now provided in the new graphlib module.

リリースプロセスの変更:

PEP 602 [https://peps.python.org/pep-0602/]、CPythonは年次のリリースサイクルを採用します。

コード中の非推奨警告(DeprecationWarning)をチェックして下さい

Python 2.7がまだサポートされていた期間、Python 3の多くの機能はPython 2.7との後方互換性を保っていました。Python 2サポートの終了とともに、この後方互換性レイヤは除去されたか、間もなく除去されます。ここ数年で、それらの多くは警告 DeprecationWarning を出すようになりました。例えば、2012年にリリースされたPython 3.3以降、collections.abc.Mapping の代りに collections.Mapping を使うと、警告 DeprecationWarning が出ます。

警告 DeprecationWarning および PendingDeprecationWarning を確認するために、 -W default コマンドラインオプションを付けて、あなたのアプリケーションをテストして下さい。あるいは、-W error で警告をエラーとして扱うこともできます。サードパーティによるコードの警告を無視するには、Warnings Filter を使うことができます。

Python 3.9は、Python 2後方互換性レイヤを提供する最後のバージョンです。このレイヤは、Pythonプロジェクトの保守管理者に、Python 2サポートを止めてPython 3.9サポートを追加する時間的な余裕を与えるためのものです。

Aliases to Abstract Base Classes in the collections module, like collections.Mapping alias to collections.abc.Mapping, are kept for one last release for backward compatibility. They will be removed from Python 3.10.

より一般的には、あなたのコードが次のバージョンのPythonと互換性を保てるよう、Python Development Mode でテストするようにしてください。

注釈: Pythonのこのバージョンで、既存の多くの非推奨機能が削除されました。詳しくは 削除 を見て下さい。

新しい機能

辞書のマージと更新演算子

組み込みの dict クラスにマージ(|)と更新(|=)演算子が追加されました。この演算子は、辞書をマージする既存の方法 dict.update と {**d1, **d2} を補完します。

以下はプログラム例です:

>>> 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'}

詳細は PEP 584 [https://peps.python.org/pep-0584/] を参照してください。(Brandt Bucher の貢献による bpo-36144 [https://bugs.python.org/issue?@action=redirect&bpo=36144])

prefixとsuffixを削除する新しい文字列メソッド

文字列から不要な prefix や suffix を簡単に削除する str.removeprefix(prefix) と str.removesuffix(suffix) が追加されました。 bytes, bytearray, collections.UserString にも同様のメソッドが追加されました。詳細は PEP 616 [https://peps.python.org/pep-0616/] を参照してください。(Dennis Sweeney の貢献による bpo-39939 [https://bugs.python.org/issue?@action=redirect&bpo=39939])

標準コレクション型の型ヒントにおける総称型 (generics) の使用

型アノテーションで、typing モジュールからインポートしていた大文字の型（List や Dict）の代わりに、総称型（generics）で list や dict といった標準コレクション型が使用できるようになりました。いくつかの他の標準ライブラリの型（queue.Queue など）も総称型として使用できます。

例:

def greet_all(names: list[str]) -> None:
    for name in names:
        print("Hello", name)

詳細は PEP 585 [https://peps.python.org/pep-0585/] を参照してください。(Guido van Rossum、Ethan Smith、Batuhan Taşkaya の貢献による bpo-39481 [https://bugs.python.org/issue?@action=redirect&bpo=39481])

新しいパーサー

Python 3.9は、 LL(1) [https://en.wikipedia.org/wiki/LL_parser] に代えて PEG [https://en.wikipedia.org/wiki/Parsing_expression_grammar] に基づく新しいパーサーを採用しています。新しいパーサーのパフォーマンスは古いパーサーとほぼ同程度ですが、新しい言語の機能を設計する際に、PEGの形式主義はより柔軟です。我々は、この柔軟性をPython 3.10以降に使い始める予定です。

ast モジュールは、新しいパーサーを使って古いパーサーと同じASTを生成します。

In Python 3.10, the old parser will be deleted and so will all functionality that depends on it (primarily the 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 (-X oldparser) or an environment variable (PYTHONOLDPARSER=1).

詳細は PEP 617 [https://peps.python.org/pep-0617/] を参照してください。(Guido van Rossum,、Pablo Galindo、およびLysandros Nikolaouの貢献による bpo-40334 [https://bugs.python.org/issue?@action=redirect&bpo=40334])

その他の言語変更

__import__() now raises ImportError instead of ValueError, which used to occur when a relative import went past its top-level package. (Contributed by Ngalim Siregar in bpo-37444 [https://bugs.python.org/issue?@action=redirect&bpo=37444].)

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 became an absolute path, rather than a relative path. These paths now remain valid after the current directory is changed by os.chdir(). As a side effect, the traceback also displays the absolute path for __main__ module frames in this case. (Contributed by Victor Stinner in bpo-20443 [https://bugs.python.org/issue?@action=redirect&bpo=20443].)

In the Python Development Mode and in debug build, the encoding and errors arguments are now checked for string encoding and decoding operations. Examples: open(), str.encode() and 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 [https://bugs.python.org/issue?@action=redirect&bpo=37388].)

"".replace("", s, n) now returns s instead of an empty string for all non-zero n. It is now consistent with "".replace("", s). There are similar changes for bytes and bytearray objects. (Contributed by Serhiy Storchaka in bpo-28029 [https://bugs.python.org/issue?@action=redirect&bpo=28029].)

Any valid expression can now be used as a decorator. Previously, the grammar was much more restrictive. See PEP 614 [https://peps.python.org/pep-0614/] for details. (Contributed by Brandt Bucher in bpo-39702 [https://bugs.python.org/issue?@action=redirect&bpo=39702].)

Improved help for the typing module. Docstrings are now shown for all special forms and special generic aliases (like Union and List). Using help() with generic alias like List[int] will show the help for the correspondent concrete type (list in this case). (Contributed by Serhiy Storchaka in bpo-40257 [https://bugs.python.org/issue?@action=redirect&bpo=40257].)

Parallel running of aclose() / asend() / athrow() is now prohibited, and ag_running now reflects the actual running status of the async generator. (Contributed by Yury Selivanov in bpo-30773 [https://bugs.python.org/issue?@action=redirect&bpo=30773].)

Unexpected errors in calling the __iter__ method are no longer masked by TypeError in the in operator and functions contains(), indexOf() and countOf() of the operator module. (Contributed by Serhiy Storchaka in bpo-40824 [https://bugs.python.org/issue?@action=redirect&bpo=40824].)

Unparenthesized lambda expressions can no longer be the expression part in an if clause in comprehensions and generator expressions. See bpo-41848 [https://bugs.python.org/issue?@action=redirect&bpo=41848] and bpo-43755 [https://bugs.python.org/issue?@action=redirect&bpo=43755] for details.

新たなモジュール

zoneinfo

zoneinfo モジュールにより標準ライブラリにIANAのタイムゾーンデータベースへのサポートを導入されます。zoneinfo.ZoneInfo という、システムのタイムゾーンデータを背景とした具体的な datetime.tzinfo の実装が追加されます。

以下はプログラム例です:

>>> from zoneinfo import ZoneInfo
>>> from datetime import datetime, timedelta

>>> # Daylight saving time
>>> dt = datetime(2020, 10, 31, 12, tzinfo=ZoneInfo("America/Los_Angeles"))
>>> print(dt)
2020-10-31 12:00:00-07:00
>>> dt.tzname()
'PDT'

>>> # Standard time
>>> dt += timedelta(days=7)
>>> print(dt)
2020-11-07 12:00:00-08:00
>>> print(dt.tzname())
PST

As a fall-back source of data for platforms that don't ship the IANA database, the tzdata [https://pypi.org/project/tzdata/] module was released as a first-party package -- distributed via PyPI and maintained by the CPython core team.

参考

PEP 615 [https://peps.python.org/pep-0615/] -- Support for the IANA Time Zone Database in the Standard Library

PEP作成と実装は Paul Ganssle による。

graphlib

A new module, graphlib, was added that contains the graphlib.TopologicalSorter class to offer functionality to perform topological sorting of graphs. (Contributed by Pablo Galindo, Tim Peters and Larry Hastings in bpo-17005 [https://bugs.python.org/issue?@action=redirect&bpo=17005].)

改良されたモジュール

ast

Added the indent option to dump() which allows it to produce a multiline indented output. (Contributed by Serhiy Storchaka in bpo-37995 [https://bugs.python.org/issue?@action=redirect&bpo=37995].)

Added ast.unparse() as a function in the ast module that can be used to unparse an ast.AST object and produce a string with code that would produce an equivalent ast.AST object when parsed. (Contributed by Pablo Galindo and Batuhan Taskaya in bpo-38870 [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 [https://bugs.python.org/issue?@action=redirect&bpo=39638].)

asyncio

セキュリティ上の重大な懸念により、asyncio.loop.create_datagram_endpoint() での reuse_address 引数は無効になりました。これはソケットオプション SO_REUSEADDR` のUDP における挙動が原因です。詳しくは、loop.create_datagram_endpoint() のドキュメントを参照してください。(Kyle Stanley, Antoine Pitrou, Yury Selivanov による貢献 bpo-37228 [https://bugs.python.org/issue?@action=redirect&bpo=37228])

Added a new coroutine shutdown_default_executor() that schedules a shutdown for the default executor that waits on the ThreadPoolExecutor to finish closing. Also, asyncio.run() has been updated to use the new coroutine. (Contributed by Kyle Stanley in bpo-34037 [https://bugs.python.org/issue?@action=redirect&bpo=34037].)

Added asyncio.PidfdChildWatcher, a Linux-specific child watcher implementation that polls process file descriptors. (bpo-38692 [https://bugs.python.org/issue?@action=redirect&bpo=38692])

Added a new coroutine 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 run_in_executor() that can directly take keyword arguments. (Contributed by Kyle Stanley and Yury Selivanov in bpo-32309 [https://bugs.python.org/issue?@action=redirect&bpo=32309].)

When cancelling the task due to a timeout, 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 [https://bugs.python.org/issue?@action=redirect&bpo=32751].)

asyncio now raises TypeError when calling incompatible methods with an ssl.SSLSocket socket. (Contributed by Ido Michael in bpo-37404 [https://bugs.python.org/issue?@action=redirect&bpo=37404].)

compileall

Added new possibility to use hardlinks for duplicated .pyc files: hardlink_dupes parameter and --hardlink-dupes command line option. (Contributed by Lumír 'Frenzy' Balhar in bpo-40495 [https://bugs.python.org/issue?@action=redirect&bpo=40495].)

Added new options for path manipulation in resulting .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 [https://bugs.python.org/issue?@action=redirect&bpo=38112].)

concurrent.futures

Added a new cancel_futures parameter to 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 [https://bugs.python.org/issue?@action=redirect&bpo=39349].)

Removed daemon threads from ThreadPoolExecutor and ProcessPoolExecutor. This improves compatibility with subinterpreters and predictability in their shutdown processes. (Contributed by Kyle Stanley in bpo-39812 [https://bugs.python.org/issue?@action=redirect&bpo=39812].)

Workers in 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 [https://bugs.python.org/issue?@action=redirect&bpo=39207].)

curses

curses.get_escdelay(), curses.set_escdelay(), curses.get_tabsize(), curses.set_tabsize() の関数が追加されました。(Anthony Sottileによる bpo-38312 [https://bugs.python.org/issue?@action=redirect&bpo=38312] でのコントリビュート。)

datetime

The isocalendar() of datetime.date and isocalendar() of datetime.datetime methods now returns a namedtuple() instead of a tuple. (Contributed by Donghee Na in bpo-24416 [https://bugs.python.org/issue?@action=redirect&bpo=24416].)

distutils

The 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 [https://bugs.python.org/issue?@action=redirect&bpo=40698].)

fcntl

Added constants F_OFD_GETLK, F_OFD_SETLK and F_OFD_SETLKW. (Contributed by Donghee Na in bpo-38602 [https://bugs.python.org/issue?@action=redirect&bpo=38602].)

ftplib

FTP and FTP_TLS now raise a 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 [https://bugs.python.org/issue?@action=redirect&bpo=39259].)

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 [https://bugs.python.org/issue?@action=redirect&bpo=38379].)

Added a new function gc.is_finalized() to check if an object has been finalized by the garbage collector. (Contributed by Pablo Galindo in bpo-39322 [https://bugs.python.org/issue?@action=redirect&bpo=39322].)

hashlib

The hashlib module can now use SHA3 hashes and SHAKE XOF from OpenSSL when available. (Contributed by Christian Heimes in bpo-37630 [https://bugs.python.org/issue?@action=redirect&bpo=37630].)

Builtin hash modules can now be disabled with ./configure --without-builtin-hashlib-hashes or selectively enabled with e.g. ./configure --with-builtin-hashlib-hashes=sha3,blake2 to force use of OpenSSL based implementation. (Contributed by Christian Heimes in bpo-40479 [https://bugs.python.org/issue?@action=redirect&bpo=40479])

http

HTTP status codes 103 EARLY_HINTS, 418 IM_A_TEAPOT and 425 TOO_EARLY are added to http.HTTPStatus. (Contributed by Donghee Na in bpo-39509 [https://bugs.python.org/issue?@action=redirect&bpo=39509] and Ross Rhodes in bpo-39507 [https://bugs.python.org/issue?@action=redirect&bpo=39507].)

IDLE と idelelib

Added option to toggle cursor blink off. (Contributed by Zackery Spytz in bpo-4603 [https://bugs.python.org/issue?@action=redirect&bpo=4603].)

Escape key now closes IDLE completion windows. (Contributed by Johnny Najera in bpo-38944 [https://bugs.python.org/issue?@action=redirect&bpo=38944].)

Added keywords to module name completion list. (Contributed by Terry J. Reedy in bpo-37765 [https://bugs.python.org/issue?@action=redirect&bpo=37765].)

New in 3.9 maintenance releases

Make IDLE invoke sys.excepthook() (when started without '-n'). User hooks were previously ignored. (Contributed by Ken Hilton in bpo-43008 [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 [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 [https://bugs.python.org/issue?@action=redirect&bpo=33962].)

Apply syntax highlighting to .pyi files. (Contributed by Alex Waygood and Terry Jan Reedy in bpo-45447 [https://bugs.python.org/issue?@action=redirect&bpo=45447].)

imaplib

IMAP4 and IMAP4_SSL now have an optional timeout parameter for their constructors. Also, the open() method now has an optional timeout parameter with this change. The overridden methods of IMAP4_SSL and IMAP4_stream were applied to this change. (Contributed by Donghee Na in bpo-38615 [https://bugs.python.org/issue?@action=redirect&bpo=38615].)

imaplib.IMAP4.unselect() is added. 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 imaplib.IMAP4.close(), except that no messages are permanently removed from the currently selected mailbox. (Contributed by Donghee Na in bpo-40375 [https://bugs.python.org/issue?@action=redirect&bpo=40375].)

importlib

To improve consistency with import statements, importlib.util.resolve_name() now raises ImportError instead of ValueError for invalid relative import attempts. (Contributed by Ngalim Siregar in bpo-37444 [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 [https://bugs.python.org/issue?@action=redirect&bpo=39336].)

Added importlib.resources.files() function with support for subdirectories in package data, matching backport in importlib_resources version 1.5. (Contributed by Jason R. Coombs in bpo-39791 [https://bugs.python.org/issue?@action=redirect&bpo=39791].)

Refreshed importlib.metadata from importlib_metadata version 1.6.1.

inspect

inspect.BoundArguments.arguments は OrderedDict から標準のdictに変更されました。(Inada Naoki の貢献による bpo-36350 [https://bugs.python.org/issue?@action=redirect&bpo=36350], bpo-39775 [https://bugs.python.org/issue?@action=redirect&bpo=39775])

ipaddress

ipaddress now supports IPv6 Scoped Addresses (IPv6 address with suffix %<scope_id>).

Scoped IPv6 addresses can be parsed using ipaddress.IPv6Address. If present, scope zone ID is available through the scope_id attribute. (Contributed by Oleksandr Pavliuk in bpo-34788 [https://bugs.python.org/issue?@action=redirect&bpo=34788].)

Starting with Python 3.9.5 the ipaddress module no longer accepts any leading zeros in IPv4 address strings. (Contributed by Christian Heimes in bpo-36384 [https://bugs.python.org/issue?@action=redirect&bpo=36384]).

math

Expanded the math.gcd() function to handle multiple arguments. Formerly, it only supported two arguments. (Contributed by Serhiy Storchaka in bpo-39648 [https://bugs.python.org/issue?@action=redirect&bpo=39648].)

Added math.lcm(): return the least common multiple of specified arguments. (Contributed by Mark Dickinson, Ananthakrishnan and Serhiy Storchaka in bpo-39479 [https://bugs.python.org/issue?@action=redirect&bpo=39479] and bpo-39648 [https://bugs.python.org/issue?@action=redirect&bpo=39648].)

Added math.nextafter(): return the next floating-point value after x towards y. (Contributed by Victor Stinner in bpo-39288 [https://bugs.python.org/issue?@action=redirect&bpo=39288].)

Added math.ulp(): return the value of the least significant bit of a float. (Contributed by Victor Stinner in bpo-39310 [https://bugs.python.org/issue?@action=redirect&bpo=39310].)

multiprocessing

The multiprocessing.SimpleQueue class has a new close() method to explicitly close the queue. (Contributed by Victor Stinner in bpo-30966 [https://bugs.python.org/issue?@action=redirect&bpo=30966].)

nntplib

NNTP and NNTP_SSL now raise a 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 [https://bugs.python.org/issue?@action=redirect&bpo=39259].)

os

Added CLD_KILLED and CLD_STOPPED for si_code. (Contributed by Donghee Na in bpo-38493 [https://bugs.python.org/issue?@action=redirect&bpo=38493].)

Exposed the Linux-specific os.pidfd_open() (bpo-38692 [https://bugs.python.org/issue?@action=redirect&bpo=38692]) and os.P_PIDFD (bpo-38713 [https://bugs.python.org/issue?@action=redirect&bpo=38713]) for process management with file descriptors.

os.unsetenv() 関数が、Windowsでも使えるようになりました。(bpo-39413 [https://bugs.python.org/issue?@action=redirect&bpo=39413] におけるVictor Stinnerの貢献による)

os.putenv() と os.unsetenv() 関数が、常に利用できるようになりました。(bpo-39395 [https://bugs.python.org/issue?@action=redirect&bpo=39395] におけるVictor Stinnerの貢献による)

Added os.waitstatus_to_exitcode() function: convert a wait status to an exit code. (Contributed by Victor Stinner in bpo-40094 [https://bugs.python.org/issue?@action=redirect&bpo=40094].)

pathlib

os.readlink() と同様の動作をする pathlib.Path.readlink() が追加されました。(Girts Folkmanis の貢献による bpo-30618 [https://bugs.python.org/issue?@action=redirect&bpo=30618])

pdb

On Windows now Pdb supports ~/.pdbrc. (Contributed by Tim Hopper and Dan Lidral-Porter in bpo-20523 [https://bugs.python.org/issue?@action=redirect&bpo=20523].)

poplib

POP3 and POP3_SSL now raise a 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 [https://bugs.python.org/issue?@action=redirect&bpo=39259].)

pprint

pprint can now pretty-print types.SimpleNamespace. (Contributed by Carl Bordum Hansen in bpo-37376 [https://bugs.python.org/issue?@action=redirect&bpo=37376].)

pydoc

The documentation string is now shown not only for class, function, method etc, but for any object that has its own __doc__ attribute. (Contributed by Serhiy Storchaka in bpo-40257 [https://bugs.python.org/issue?@action=redirect&bpo=40257].)

random

ランダムなbytesを生成する random.Random.randbytes メソッドが追加されました。(Victor Stinner による貢献 bpo-40286 [https://bugs.python.org/issue?@action=redirect&bpo=40286])

signal

Exposed the Linux-specific signal.pidfd_send_signal() for sending to signals to a process using a file descriptor instead of a pid. (bpo-38712 [https://bugs.python.org/issue?@action=redirect&bpo=38712])

smtplib

SMTP and SMTP_SSL now raise a 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 [https://bugs.python.org/issue?@action=redirect&bpo=39259].)

LMTP constructor now has an optional timeout parameter. (Contributed by Donghee Na in bpo-39329 [https://bugs.python.org/issue?@action=redirect&bpo=39329].)

socket

The socket module now exports the CAN_RAW_JOIN_FILTERS constant on Linux 4.1 and greater. (Contributed by Stefan Tatschner and Zackery Spytz in bpo-25780 [https://bugs.python.org/issue?@action=redirect&bpo=25780].)

The socket module now supports the CAN_J1939 protocol on platforms that support it. (Contributed by Karl Ding in bpo-40291 [https://bugs.python.org/issue?@action=redirect&bpo=40291].)

The socket module now has the socket.send_fds() and socket.recv_fds() functions. (Contributed by Joannah Nanjekye, Shinya Okano and Victor Stinner in bpo-28724 [https://bugs.python.org/issue?@action=redirect&bpo=28724].)

time

On AIX, thread_time() is now implemented with thread_cputime() which has nanosecond resolution, rather than clock_gettime(CLOCK_THREAD_CPUTIME_ID) which has a resolution of 10 milliseconds. (Contributed by Batuhan Taskaya in bpo-40192 [https://bugs.python.org/issue?@action=redirect&bpo=40192])

sys

Added a new 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 "lib" on most platforms. On Fedora and SuSE, it is equal to "lib64" on 64-bit platforms. (Contributed by Jan Matějek, Matěj Cepl, Charalampos Stratakis and Victor Stinner in bpo-1294959 [https://bugs.python.org/issue?@action=redirect&bpo=1294959].)

Previously, sys.stderr was block-buffered when non-interactive. Now stderr defaults to always being line-buffered. (Contributed by Jendrik Seipp in bpo-13601 [https://bugs.python.org/issue?@action=redirect&bpo=13601].)

tracemalloc

Added 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 [https://bugs.python.org/issue?@action=redirect&bpo=40630].)

typing

PEP 593 [https://peps.python.org/pep-0593/] introduced an typing.Annotated type to decorate existing types with context-specific metadata and new include_extras parameter to typing.get_type_hints() to access the metadata at runtime. (Contributed by Till Varoquaux and Konstantin Kashin.)

unicodedata

Unicode データベースが、バージョン 13.0.0 に更新されました。(bpo-39926 [https://bugs.python.org/issue?@action=redirect&bpo=39926])

venv

The activation scripts provided by venv now all specify their prompt customization consistently by always using the value specified by __VENV_PROMPT__. Previously some scripts unconditionally used __VENV_PROMPT__, others only if it happened to be set (which was the default case), and one used __VENV_NAME__ instead. (Contributed by Brett Cannon in bpo-37663 [https://bugs.python.org/issue?@action=redirect&bpo=37663].)

xml

White space characters within attributes are now preserved when serializing 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 [https://bugs.python.org/issue?@action=redirect&bpo=39011].)

最適化

Optimized the idiom for assignment a temporary variable in comprehensions. Now for y in [expr] in comprehensions is as fast as a simple assignment y = expr. For example:

sums = [s for s in [0] for x in data for s in [s + x]]

Unlike the := operator this idiom does not leak a variable to the outer scope.

(Contributed by Serhiy Storchaka in bpo-32856 [https://bugs.python.org/issue?@action=redirect&bpo=32856].)

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 [https://bugs.python.org/issue?@action=redirect&bpo=40010].)

Optimized the subprocess module on FreeBSD using closefrom(). (Contributed by Ed Maste, Conrad Meyer, Kyle Evans, Kubilay Kocak and Victor Stinner in bpo-38061 [https://bugs.python.org/issue?@action=redirect&bpo=38061].)

PyLong_FromDouble() is now up to 1.87x faster for values that fit into long. (Contributed by Sergey Fedoseev in bpo-37986 [https://bugs.python.org/issue?@action=redirect&bpo=37986].)

A number of Python builtins (range, tuple, set, frozenset, list, dict) are now sped up by using PEP 590 [https://peps.python.org/pep-0590/] vectorcall protocol. (Contributed by Donghee Na, Mark Shannon, Jeroen Demeyer and Petr Viktorin in bpo-37207 [https://bugs.python.org/issue?@action=redirect&bpo=37207].)

Optimized 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 [https://bugs.python.org/issue?@action=redirect&bpo=8425].)

Python's small object allocator (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 [https://bugs.python.org/issue?@action=redirect&bpo=37257].)

floor division of float operation now has a better performance. Also the message of ZeroDivisionError for this operation is updated. (Contributed by Donghee Na in bpo-39434 [https://bugs.python.org/issue?@action=redirect&bpo=39434].)

Decoding short ASCII strings with UTF-8 and ascii codecs is now about 15% faster. (Contributed by Inada Naoki in bpo-37348 [https://bugs.python.org/issue?@action=redirect&bpo=37348].)

Here's a summary of performance improvements from Python 3.4 through Python 3.9:

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

These results were generated from the variable access benchmark script at: Tools/scripts/var_access_benchmark.py. The benchmark script displays timings in nanoseconds. The benchmarks were measured on an Intel® Core™ i7-4960HQ processor [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 [https://www.python.org/downloads/macos/].

非推奨

distutilsの bdist_msi コマンドは、現在非推奨です。代わりに、bdist_wheel (wheelパッケージ)を使って下さい。 ( bpo-39586 [https://bugs.python.org/issue?@action=redirect&bpo=39586] でのHugo van Kemenadeによる貢献による)

Currently math.factorial() accepts float instances with non-negative integer values (like 5.0). It raises a ValueError for non-integral and negative floats. It is now deprecated. In future Python versions it will raise a TypeError for all floats. (Contributed by Serhiy Storchaka in bpo-37315 [https://bugs.python.org/issue?@action=redirect&bpo=37315].)

The parser and 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 ast module.

The Public C API functions PyParser_SimpleParseStringFlags(), PyParser_SimpleParseStringFlagsFilename(), PyParser_SimpleParseFileFlags() and PyNode_Compile() are deprecated and will be removed in Python 3.10 together with the old parser.

Using 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 TypeError in a future version of Python. (Contributed by Josh Rosenberg in bpo-35712 [https://bugs.python.org/issue?@action=redirect&bpo=35712].)

The 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 None, int, float, str, bytes, and bytearray.

Opening the 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 [https://bugs.python.org/issue?@action=redirect&bpo=28286].)

Deprecated the split() method of _tkinter.TkappType in favour of the splitlist() method which has more consistent and predicable behavior. (Contributed by Serhiy Storchaka in bpo-38371 [https://bugs.python.org/issue?@action=redirect&bpo=38371].)

The explicit passing of coroutine objects to asyncio.wait() has been deprecated and will be removed in version 3.11. (Contributed by Yury Selivanov and Kyle Stanley in bpo-34790 [https://bugs.python.org/issue?@action=redirect&bpo=34790].)

binhex4 and hexbin4 standards are now deprecated. The binhex module and the following binascii functions are now deprecated:

b2a_hqx(), a2b_hqx()

rlecode_hqx(), rledecode_hqx()

(Contributed by Victor Stinner in bpo-39353 [https://bugs.python.org/issue?@action=redirect&bpo=39353].)

ast classes slice, Index and ExtSlice are considered deprecated and will be removed in future Python versions. value itself should be used instead of Index(value). Tuple(slices, Load()) should be used instead of ExtSlice(slices). (Contributed by Serhiy Storchaka in bpo-34822 [https://bugs.python.org/issue?@action=redirect&bpo=34822].)

ast classes Suite, Param, AugLoad and 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 [https://bugs.python.org/issue?@action=redirect&bpo=39639] and bpo-39969 [https://bugs.python.org/issue?@action=redirect&bpo=39969] and Serhiy Storchaka in bpo-39988 [https://bugs.python.org/issue?@action=redirect&bpo=39988].)

The PyEval_InitThreads() and PyEval_ThreadsInitialized() functions are now deprecated and will be removed in Python 3.11. Calling PyEval_InitThreads() now does nothing. The GIL is initialized by Py_Initialize() since Python 3.7. (Contributed by Victor Stinner in bpo-39877 [https://bugs.python.org/issue?@action=redirect&bpo=39877].)

Passing None as the first argument to the shlex.split() function has been deprecated. (Contributed by Zackery Spytz in bpo-33262 [https://bugs.python.org/issue?@action=redirect&bpo=33262].)

smtpd.MailmanProxy() is now deprecated as it is unusable without an external module, mailman. (Contributed by Samuel Colvin in bpo-35800 [https://bugs.python.org/issue?@action=redirect&bpo=35800].)

The lib2to3 module now emits a PendingDeprecationWarning. Python 3.9 switched to a PEG parser (see PEP 617 [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 lib2to3 module may be removed from the standard library in a future Python version. Consider third-party alternatives such as LibCST [https://libcst.readthedocs.io/] or parso [https://parso.readthedocs.io/]. (Contributed by Carl Meyer in bpo-40360 [https://bugs.python.org/issue?@action=redirect&bpo=40360].)

random.shuffle() の*random* パラメータは非推奨になりました。(Raymond Hettingerの貢献による bpo-40465 [https://bugs.python.org/issue?@action=redirect&bpo=40465])

削除

The erroneous version at unittest.mock.__version__ has been removed.

nntplib.NNTP: xpath() and 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 xgtitle(), please use nntplib.NNTP.descriptions() or nntplib.NNTP.description() instead. (Contributed by Donghee Na in bpo-39366 [https://bugs.python.org/issue?@action=redirect&bpo=39366].)

array.array: tostring() and fromstring() methods have been removed. They were aliases to tobytes() and frombytes(), deprecated since Python 3.2. (Contributed by Victor Stinner in bpo-38916 [https://bugs.python.org/issue?@action=redirect&bpo=38916].)

The undocumented sys.callstats() function has been removed. Since Python 3.7, it was deprecated and always returned None. It required a special build option CALL_PROFILE which was already removed in Python 3.7. (Contributed by Victor Stinner in bpo-37414 [https://bugs.python.org/issue?@action=redirect&bpo=37414].)

The sys.getcheckinterval() and sys.setcheckinterval() functions have been removed. They were deprecated since Python 3.2. Use sys.getswitchinterval() and sys.setswitchinterval() instead. (Contributed by Victor Stinner in bpo-37392 [https://bugs.python.org/issue?@action=redirect&bpo=37392].)

The C function PyImport_Cleanup() has been removed. It was documented as: "Empty the module table. For internal use only." (Contributed by Victor Stinner in bpo-36710 [https://bugs.python.org/issue?@action=redirect&bpo=36710].)

_dummy_thread and 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 [https://bugs.python.org/issue?@action=redirect&bpo=37312].)

aifc.openfp() alias to aifc.open(), sunau.openfp() alias to sunau.open(), and wave.openfp() alias to wave.open() have been removed. They were deprecated since Python 3.7. (Contributed by Victor Stinner in bpo-37320 [https://bugs.python.org/issue?@action=redirect&bpo=37320].)

The isAlive() method of threading.Thread has been removed. It was deprecated since Python 3.8. Use is_alive() instead. (Contributed by Donghee Na in bpo-37804 [https://bugs.python.org/issue?@action=redirect&bpo=37804].)

Methods getchildren() and getiterator() of classes ElementTree and Element in the ElementTree module have been removed. They were deprecated in Python 3.2. Use iter(x) or list(x) instead of x.getchildren() and x.iter() or list(x.iter()) instead of x.getiterator(). (Contributed by Serhiy Storchaka in bpo-36543 [https://bugs.python.org/issue?@action=redirect&bpo=36543].)

The old plistlib API has been removed, it was deprecated since Python 3.4. Use the load(), loads(), dump(), and dumps() functions. Additionally, the use_builtin_types parameter was removed, standard bytes objects are always used instead. (Contributed by Jon Janzen in bpo-36409 [https://bugs.python.org/issue?@action=redirect&bpo=36409].)

The C function PyGen_NeedsFinalizing has been removed. It was not documented, tested, or used anywhere within CPython after the implementation of PEP 442 [https://peps.python.org/pep-0442/]. Patch by Joannah Nanjekye. (Contributed by Joannah Nanjekye in bpo-15088 [https://bugs.python.org/issue?@action=redirect&bpo=15088])

base64.encodestring() and base64.decodestring(), aliases deprecated since Python 3.1, have been removed: use base64.encodebytes() and base64.decodebytes() instead. (Contributed by Victor Stinner in bpo-39351 [https://bugs.python.org/issue?@action=redirect&bpo=39351].)

fractions.gcd() function has been removed, it was deprecated since Python 3.5 (bpo-22486 [https://bugs.python.org/issue?@action=redirect&bpo=22486]): use math.gcd() instead. (Contributed by Victor Stinner in bpo-39350 [https://bugs.python.org/issue?@action=redirect&bpo=39350].)

The buffering parameter of bz2.BZ2File has been removed. Since Python 3.0, it was ignored and using it emitted a DeprecationWarning. Pass an open file object to control how the file is opened. (Contributed by Victor Stinner in bpo-39357 [https://bugs.python.org/issue?@action=redirect&bpo=39357].)

The encoding parameter of json.loads() has been removed. As of Python 3.1, it was deprecated and ignored; using it has emitted a DeprecationWarning since Python 3.8. (Contributed by Inada Naoki in bpo-39377 [https://bugs.python.org/issue?@action=redirect&bpo=39377])

with (await asyncio.lock): and with (yield from asyncio.lock): statements are not longer supported, use async with lock instead. The same is correct for asyncio.Condition and asyncio.Semaphore. (Contributed by Andrew Svetlov in bpo-34793 [https://bugs.python.org/issue?@action=redirect&bpo=34793].)

The sys.getcounts() function, the -X showalloccount command line option and the show_alloc_count field of the C structure PyConfig have been removed. They required a special Python build by defining COUNT_ALLOCS macro. (Contributed by Victor Stinner in bpo-39489 [https://bugs.python.org/issue?@action=redirect&bpo=39489].)

The _field_types attribute of the typing.NamedTuple class has been removed. It was deprecated since Python 3.8. Use the __annotations__ attribute instead. (Contributed by Serhiy Storchaka in bpo-40182 [https://bugs.python.org/issue?@action=redirect&bpo=40182].)

The symtable.SymbolTable.has_exec() method has been removed. It was deprecated since 2006, and only returning False when it's called. (Contributed by Batuhan Taskaya in bpo-40208 [https://bugs.python.org/issue?@action=redirect&bpo=40208])

The asyncio.Task.current_task() and asyncio.Task.all_tasks() have been removed. They were deprecated since Python 3.7 and you can use asyncio.current_task() and asyncio.all_tasks() instead. (Contributed by Rémi Lapeyre in bpo-40967 [https://bugs.python.org/issue?@action=redirect&bpo=40967])

The unescape() method in the html.parser.HTMLParser class has been removed (it was deprecated since Python 3.4). html.unescape() should be used for converting character references to the corresponding unicode characters.

Python 3.9への移植

このセクションでは前述の変更とバグフィックスにより必要となるかもしれないコードの変更を列挙します:

Python API の変更

__import__() and importlib.util.resolve_name() now raise ImportError where it previously raised ValueError. Callers catching the specific exception type and supporting both Python 3.9 and earlier versions will need to catch both using except (ImportError, ValueError):.

The venv activation scripts no longer special-case when __VENV_PROMPT__ is set to "".

The select.epoll.unregister() method no longer ignores the EBADF error. (Contributed by Victor Stinner in bpo-39239 [https://bugs.python.org/issue?@action=redirect&bpo=39239].)

The compresslevel parameter of bz2.BZ2File became keyword-only, since the buffering parameter has been removed. (Contributed by Victor Stinner in bpo-39357 [https://bugs.python.org/issue?@action=redirect&bpo=39357].)

Simplified AST for subscription. Simple indices will be represented by their value, extended slices will be represented as tuples. Index(value) will return a value itself, ExtSlice(slices) will return Tuple(slices, Load()). (Contributed by Serhiy Storchaka in bpo-34822 [https://bugs.python.org/issue?@action=redirect&bpo=34822].)

The importlib module now ignores the PYTHONCASEOK environment variable when the -E or -I command line options are being used.

The encoding parameter has been added to the classes ftplib.FTP and ftplib.FTP_TLS as a keyword-only parameter, and the default encoding is changed from Latin-1 to UTF-8 to follow RFC 2640 [https://datatracker.ietf.org/doc/html/rfc2640.html].

asyncio.loop.shutdown_default_executor() has been added to AbstractEventLoop, meaning alternative event loops that inherit from it should have this method defined. (Contributed by Kyle Stanley in bpo-34037 [https://bugs.python.org/issue?@action=redirect&bpo=34037].)

The constant values of future flags in the __future__ module is updated in order to prevent collision with compiler flags. Previously PyCF_ALLOW_TOP_LEVEL_AWAIT was clashing with CO_FUTURE_DIVISION. (Contributed by Batuhan Taskaya in bpo-39562 [https://bugs.python.org/issue?@action=redirect&bpo=39562])

array('u') now uses wchar_t as C type instead of Py_UNICODE. This change doesn't affect to its behavior because Py_UNICODE is alias of wchar_t since Python 3.3. (Contributed by Inada Naoki in bpo-34538 [https://bugs.python.org/issue?@action=redirect&bpo=34538].)

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'. (Contributed by Vinay Sajip in bpo-37742 [https://bugs.python.org/issue?@action=redirect&bpo=37742].)

Division handling of PurePath now returns NotImplemented instead of raising a TypeError when passed something other than an instance of str or PurePath. This allows creating compatible classes that don't inherit from those mentioned types. (Contributed by Roger Aiudi in bpo-34775 [https://bugs.python.org/issue?@action=redirect&bpo=34775]).

Starting with Python 3.9.5 the 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 socket.inet_aton() treats leading zeros as octal notatation. glibc implementation of modern inet_pton() does not accept any leading zeros. (Contributed by Christian Heimes in bpo-36384 [https://bugs.python.org/issue?@action=redirect&bpo=36384]).

codecs.lookup() now normalizes the encoding name the same way as encodings.normalize_encoding(), except that codecs.lookup() also converts the name to lower case. For example, "latex+latin1" encoding name is now normalized to "latex_latin1". (Contributed by Jordon Xu in bpo-37751 [https://bugs.python.org/issue?@action=redirect&bpo=37751].)

C API の変更

Instances of heap-allocated types (such as those created with 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 tp_traverse function, ensure that all custom tp_traverse functions of heap-allocated types visit the object's type.

例:

int
foo_traverse(foo_struct *self, visitproc visit, void *arg) {
// Rest of the traverse function
#if PY_VERSION_HEX >= 0x03090000
    // This was not needed before Python 3.9 (Python issue 35810 and 40217)
    Py_VISIT(Py_TYPE(self));
#endif
}

If your traverse function delegates to tp_traverse of its base class (or another type), ensure that Py_TYPE(self) is visited only once. Note that only heap type are expected to visit the type in tp_traverse.

For example, if your tp_traverse function includes:

base->tp_traverse(self, visit, arg)

then add:

#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

(See bpo-35810 [https://bugs.python.org/issue?@action=redirect&bpo=35810] and bpo-40217 [https://bugs.python.org/issue?@action=redirect&bpo=40217] for more information.)

The functions PyEval_CallObject, PyEval_CallFunction, PyEval_CallMethod and PyEval_CallObjectWithKeywords are deprecated. Use PyObject_Call() and its variants instead. (See more details in bpo-29548 [https://bugs.python.org/issue?@action=redirect&bpo=29548].)

CPython バイトコードの変更

The LOAD_ASSERTION_ERROR opcode was added for handling the assert statement. Previously, the assert statement would not work correctly if the AssertionError exception was being shadowed. (Contributed by Zackery Spytz in bpo-34880 [https://bugs.python.org/issue?@action=redirect&bpo=34880].)

The COMPARE_OP opcode was split into four distinct instructions:

COMPARE_OP for rich comparisons

IS_OP for 'is' and 'is not' tests

CONTAINS_OP for 'in' and 'not in' tests

JUMP_IF_NOT_EXC_MATCH for checking exceptions in 'try-except' statements.

(Contributed by Mark Shannon in bpo-39156 [https://bugs.python.org/issue?@action=redirect&bpo=39156].)

Build Changes

Added --with-platlibdir option to the configure script: name of the platform-specific library directory, stored in the new sys.platlibdir attribute. See sys.platlibdir attribute for more information. (Contributed by Jan Matějek, Matěj Cepl, Charalampos Stratakis and Victor Stinner in bpo-1294959 [https://bugs.python.org/issue?@action=redirect&bpo=1294959].)

The COUNT_ALLOCS special build macro has been removed. (Contributed by Victor Stinner in bpo-39489 [https://bugs.python.org/issue?@action=redirect&bpo=39489].)

On non-Windows platforms, the setenv() and unsetenv() functions are now required to build Python. (Contributed by Victor Stinner in bpo-39395 [https://bugs.python.org/issue?@action=redirect&bpo=39395].)

On non-Windows platforms, creating bdist_wininst installers is now officially unsupported. (See bpo-10945 [https://bugs.python.org/issue?@action=redirect&bpo=10945] for more details.)

When building Python on macOS from source, _tkinter now links with non-system Tcl and Tk frameworks if they are installed in /Library/Frameworks, as had been the case on older releases of macOS. If a macOS SDK is explicitly configured, by using --enable-universalsdk or -isysroot, only the SDK itself is searched. The default behavior can still be overridden with --with-tcltk-includes and --with-tcltk-libs. (Contributed by Ned Deily in bpo-34956 [https://bugs.python.org/issue?@action=redirect&bpo=34956].)

Python can now be built for Windows 10 ARM64. (Contributed by Steve Dower in bpo-33125 [https://bugs.python.org/issue?@action=redirect&bpo=33125].)

Some individual tests are now skipped when --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 ./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 [https://bugs.python.org/issue?@action=redirect&bpo=36044] and bpo-37707 [https://bugs.python.org/issue?@action=redirect&bpo=37707] for more details.)

C API の変更

新しい機能

PEP 573 [https://peps.python.org/pep-0573/]: Added PyType_FromModuleAndSpec() to associate a module with a class; PyType_GetModule() and PyType_GetModuleState() to retrieve the module and its state; and PyCMethod and METH_METHOD to allow a method to access the class it was defined in. (Contributed by Marcel Plch and Petr Viktorin in bpo-38787 [https://bugs.python.org/issue?@action=redirect&bpo=38787].)

Added PyFrame_GetCode() function: get a frame code. Added PyFrame_GetBack() function: get the frame next outer frame. (Contributed by Victor Stinner in bpo-40421 [https://bugs.python.org/issue?@action=redirect&bpo=40421].)

Added PyFrame_GetLineNumber() to the limited C API. (Contributed by Victor Stinner in bpo-40421 [https://bugs.python.org/issue?@action=redirect&bpo=40421].)

Added PyThreadState_GetInterpreter() and PyInterpreterState_Get() functions to get the interpreter. Added PyThreadState_GetFrame() function to get the current frame of a Python thread state. Added PyThreadState_GetID() function: get the unique identifier of a Python thread state. (Contributed by Victor Stinner in bpo-39947 [https://bugs.python.org/issue?@action=redirect&bpo=39947].)

Added a new public 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 [https://bugs.python.org/issue?@action=redirect&bpo=37194].)

Changes in the limited C API (if Py_LIMITED_API macro is defined):

Provide Py_EnterRecursiveCall() and 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 PyThreadState.recursion_depth field (the structure is opaque in the limited C API).

PyObject_INIT() and PyObject_INIT_VAR() become regular "opaque" function to hide implementation details.

(Contributed by Victor Stinner in bpo-38644 [https://bugs.python.org/issue?@action=redirect&bpo=38644] and bpo-39542 [https://bugs.python.org/issue?@action=redirect&bpo=39542].)

The PyModule_AddType() function is added to help adding a type to a module. (Contributed by Donghee Na in bpo-40024 [https://bugs.python.org/issue?@action=redirect&bpo=40024].)

Added the functions PyObject_GC_IsTracked() and 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 [https://bugs.python.org/issue?@action=redirect&bpo=40241].)

Added _PyObject_FunctionStr() to get a user-friendly string representation of a function-like object. (Patch by Jeroen Demeyer in bpo-37645 [https://bugs.python.org/issue?@action=redirect&bpo=37645].)

Added PyObject_CallOneArg() for calling an object with one positional argument (Patch by Jeroen Demeyer in bpo-37483 [https://bugs.python.org/issue?@action=redirect&bpo=37483].)

Python 3.9への移植

PyInterpreterState.eval_frame (PEP 523 [https://peps.python.org/pep-0523/]) now requires a new mandatory tstate parameter (PyThreadState*). (Contributed by Victor Stinner in bpo-38500 [https://bugs.python.org/issue?@action=redirect&bpo=38500].)

Extension modules: m_traverse, m_clear and m_free functions of 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 (Py_mod_exec function). More precisely, these functions are not called if m_size is greater than 0 and the module state (as returned by PyModule_GetState()) is NULL.

Extension modules without module state (m_size <= 0) are not affected.

If 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 [https://bugs.python.org/issue?@action=redirect&bpo=39984].)

The Windows registry is no longer used to initialize sys.path when the -E option is used (if PyConfig.use_environment is set to 0). This is significant when embedding Python on Windows. (Contributed by Zackery Spytz in bpo-8901 [https://bugs.python.org/issue?@action=redirect&bpo=8901].)

The global variable PyStructSequence_UnnamedField is now a constant and refers to a constant string. (Contributed by Serhiy Storchaka in bpo-38650 [https://bugs.python.org/issue?@action=redirect&bpo=38650].)

The PyGC_Head structure is now opaque. It is only defined in the internal C API (pycore_gc.h). (Contributed by Victor Stinner in bpo-40241 [https://bugs.python.org/issue?@action=redirect&bpo=40241].)

The Py_UNICODE_COPY, Py_UNICODE_FILL, PyUnicode_WSTR_LENGTH, PyUnicode_FromUnicode(), PyUnicode_AsUnicode(), _PyUnicode_AsUnicode, and PyUnicode_AsUnicodeAndSize() are marked as deprecated in C. They have been deprecated by PEP 393 [https://peps.python.org/pep-0393/] since Python 3.3. (Contributed by Inada Naoki in bpo-36346 [https://bugs.python.org/issue?@action=redirect&bpo=36346].)

The Py_FatalError() function is replaced with a macro which logs automatically the name of the current function, unless the Py_LIMITED_API macro is defined. (Contributed by Victor Stinner in bpo-39882 [https://bugs.python.org/issue?@action=redirect&bpo=39882].)

The vectorcall protocol now requires that the caller passes only strings as keyword names. (See bpo-37540 [https://bugs.python.org/issue?@action=redirect&bpo=37540] for more information.)

Implementation details of a number of macros and functions are now hidden:

PyObject_IS_GC() macro was converted to a function.

The PyObject_NEW() macro becomes an alias to the PyObject_New macro, and the PyObject_NEW_VAR() macro becomes an alias to the PyObject_NewVar macro. They no longer access directly the PyTypeObject.tp_basicsize member.

PyObject_GET_WEAKREFS_LISTPTR() macro was converted to a function: the macro accessed directly the PyTypeObject.tp_weaklistoffset member.

PyObject_CheckBuffer() macro was converted to a function: the macro accessed directly the PyTypeObject.tp_as_buffer member.

PyIndex_Check() is now always declared as an opaque function to hide implementation details: removed the PyIndex_Check() macro. The macro accessed directly the PyTypeObject.tp_as_number member.

(See bpo-40170 [https://bugs.python.org/issue?@action=redirect&bpo=40170] for more details.)

削除

Excluded PyFPE_START_PROTECT() and PyFPE_END_PROTECT() macros of pyfpe.h from the limited C API. (Contributed by Victor Stinner in bpo-38835 [https://bugs.python.org/issue?@action=redirect&bpo=38835].)

The tp_print slot of 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 [https://bugs.python.org/issue?@action=redirect&bpo=36974].)

Changes in the limited C API (if Py_LIMITED_API macro is defined):

Excluded the following functions from the limited C API:

PyThreadState_DeleteCurrent() (Contributed by Joannah Nanjekye in bpo-37878 [https://bugs.python.org/issue?@action=redirect&bpo=37878].)

_Py_CheckRecursionLimit

_Py_NewReference()

_Py_ForgetReference()

_PyTraceMalloc_NewReference()

_Py_GetRefTotal()

The trashcan mechanism which never worked in the limited C API.

PyTrash_UNWIND_LEVEL

Py_TRASHCAN_BEGIN_CONDITION

Py_TRASHCAN_BEGIN

Py_TRASHCAN_END

Py_TRASHCAN_SAFE_BEGIN

Py_TRASHCAN_SAFE_END

Moved following functions and definitions to the internal C API:

_PyDebug_PrintTotalRefs()

_Py_PrintReferences()

_Py_PrintReferenceAddresses()

_Py_tracemalloc_config

_Py_AddToAllObjects() (specific to Py_TRACE_REFS build)

(Contributed by Victor Stinner in bpo-38644 [https://bugs.python.org/issue?@action=redirect&bpo=38644] and bpo-39542 [https://bugs.python.org/issue?@action=redirect&bpo=39542].)

Removed _PyRuntime.getframe hook and removed _PyThreadState_GetFrame macro which was an alias to _PyRuntime.getframe. They were only exposed by the internal C API. Removed also PyThreadFrameGetter type. (Contributed by Victor Stinner in bpo-39946 [https://bugs.python.org/issue?@action=redirect&bpo=39946].)

Removed the following functions from the C API. Call PyGC_Collect() explicitly to clear all free lists. (Contributed by Inada Naoki and Victor Stinner in bpo-37340 [https://bugs.python.org/issue?@action=redirect&bpo=37340], bpo-38896 [https://bugs.python.org/issue?@action=redirect&bpo=38896] and bpo-40428 [https://bugs.python.org/issue?@action=redirect&bpo=40428].)

PyAsyncGen_ClearFreeLists()

PyContext_ClearFreeList()

PyDict_ClearFreeList()

PyFloat_ClearFreeList()

PyFrame_ClearFreeList()

PyList_ClearFreeList()

PyMethod_ClearFreeList() and PyCFunction_ClearFreeList(): the free lists of bound method objects have been removed.

PySet_ClearFreeList(): the set free list has been removed in Python 3.4.

PyTuple_ClearFreeList()

PyUnicode_ClearFreeList(): the Unicode free list has been removed in Python 3.3.

Removed _PyUnicode_ClearStaticStrings() function. (Contributed by Victor Stinner in bpo-39465 [https://bugs.python.org/issue?@action=redirect&bpo=39465].)

Removed Py_UNICODE_MATCH. It has been deprecated by PEP 393 [https://peps.python.org/pep-0393/], and broken since Python 3.3. The PyUnicode_Tailmatch() function can be used instead. (Contributed by Inada Naoki in bpo-36346 [https://bugs.python.org/issue?@action=redirect&bpo=36346].)

Cleaned header files of interfaces defined but with no implementation. The public API symbols being removed are: _PyBytes_InsertThousandsGroupingLocale, _PyBytes_InsertThousandsGrouping, _Py_InitializeFromArgs, _Py_InitializeFromWideArgs, _PyFloat_Repr, _PyFloat_Digits, _PyFloat_DigitsInit, PyFrame_ExtendStack, _PyAIterWrapper_Type, PyNullImporter_Type, PyCmpWrapper_Type, PySortWrapper_Type, PyNoArgsFunction. (Contributed by Pablo Galindo Salgado in bpo-39372 [https://bugs.python.org/issue?@action=redirect&bpo=39372].)

Python 3.9.1 での重要な変更点

typing

The behavior of typing.Literal was changed to conform with PEP 586 [https://peps.python.org/pep-0586/] and to match the behavior of static type checkers specified in the PEP.

Literal now de-duplicates parameters.

Equality comparisons between Literal objects are now order independent.

Literal comparisons now respect types. For example, Literal[0] == Literal[False] previously evaluated to True. It is now False. To support this change, the internally used type cache now supports differentiating types.

Literal objects will now raise a TypeError exception during equality comparisons if any of their parameters are not hashable. Note that declaring Literal with mutable parameters will not throw an error:

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

(bpo-42345 [https://bugs.python.org/issue?@action=redirect&bpo=42345] でのYurii Karabasの貢献による)

macOS 11.0 (Big Sur) と Appleシリコンの Mac のサポート

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 ARM64 architecture). A new universal build variant, universal2, is now available to natively support both ARM64 and 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").

(bpo-41100 [https://bugs.python.org/issue?@action=redirect&bpo=41100] でのRonald OussorenとLawrence D'Annaの貢献による)

Python 3.9.2 での重要な変更点

collections.abc

collections.abc.Callable generic now flattens type parameters, similar to what typing.Callable currently does. This means that collections.abc.Callable[[int, str], str] will have __args__ of (int, str, str); previously this was ([int, str], str). To allow this change, types.GenericAlias can now be subclassed, and a subclass will be returned when subscripting the collections.abc.Callable type. Code which accesses the arguments via typing.get_args() or __args__ need to account for this change. A DeprecationWarning may be emitted for invalid forms of parameterizing collections.abc.Callable which may have passed silently in Python 3.9.1. This DeprecationWarning will become a TypeError in Python 3.10. (Contributed by Ken Jin in bpo-42195 [https://bugs.python.org/issue?@action=redirect&bpo=42195].)

urllib.parse

Earlier Python versions allowed using both ; and & as query parameter separators in urllib.parse.parse_qs() and 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 & as the default. This change also affects cgi.parse() and 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 [https://bugs.python.org/issue?@action=redirect&bpo=42967].)

Python 3.9.3 での重要な変更点

A security fix alters the 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 trust_server_pasv_ipv4_address attribute on your FTP instance to True. (See gh-87451 [https://github.com/python/cpython/issues/87451])

Python 3.9.5での重要な変更点

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 RFC 3986 [https://datatracker.ietf.org/doc/html/rfc3986.html], ASCII newline \n, \r and tab \t characters are stripped from the URL by the parser in urllib.parse preventing such attacks. The removal characters are controlled by a new module level variable urllib.parse._UNSAFE_URL_BYTES_TO_REMOVE. (See gh-88048 [https://github.com/python/cpython/issues/88048])

Notable security feature in 3.9.14

Converting between int and str in bases other than 2 (binary), 4, 8 (octal), 16 (hexadecimal), or 32 such as base 10 (decimal) now raises a 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 CVE-2020-10735 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-10735]. This limit can be configured or disabled by environment variable, command line flag, or sys APIs. See the integer string conversion length limitation documentation. The default limit is 4300 digits in string form.

Notable changes in 3.9.17

tarfile

The extraction methods in tarfile, and 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 Extraction filters for details. In Python 3.12, use without the filter argument will show a DeprecationWarning. In Python 3.14, the default will switch to 'data'. (Contributed by Petr Viktorin in PEP 706 [https://peps.python.org/pep-0706/].)

What's New In Python 3.8

編集者:

Raymond Hettinger

This article explains the new features in Python 3.8, compared to 3.7. Python 3.8 was released on October 14, 2019. For full details, see the changelog.

概要 -- リリースハイライト

新しい機能

代入式

大きな構文の一部として、変数に値を割り当てる新しい構文 := が追加されました。この構文は セイウチの目と牙 [https://en.wikipedia.org/wiki/Walrus#/media/File:Pacific_Walrus_-_Bull_(8247646168).jpg] に似ているため、「セイウチ演算子」の愛称で知られています。

以下の例では、代入式により len() 関数を二重に呼びだすことを回避しています:

if (n := len(a)) > 10:
    print(f"List is too long ({n} elements, expected <= 10)")

同様の利点が、マッチがしたかどうかの判定とサブグループの取得とで2回マッチオブジェクトが必要になる、正規表現によるマッチでも、発揮されます:

discount = 0.0
if (mo := re.search(r'(\d+)% discount', advertisement)):
    discount = float(mo.group(1)) / 100.0

この演算子は、生成した値をループ終了の判定とループ本体の両方で使用するような while 文においても、有用です:

# Loop over fixed length blocks
while (block := f.read(256)) != '':
    process(block)

動機となったもう 1 つのユースケースは、リスト内包表記においてフィルター条件の中で計算した値が式の本体でも必要になるところから出てきます:

[clean_name.title() for name in names
 if (clean_name := normalize('NFC', name)) in allowed_names]

セイウチ演算子の使用は、複雑さを減らしたり可読性を向上させる綺麗なケースに限るよう努めてください。

完全な説明は PEP 572 [https://peps.python.org/pep-0572/] を参照してください。

(Emily Morehouse の貢献による bpo-35224 [https://bugs.python.org/issue?@action=redirect&bpo=35224])

位置専用引数

There is a new function parameter syntax / to indicate that some function parameters must be specified positionally and cannot be used as keyword arguments. This is the same notation shown by help() for C functions annotated with Larry Hastings' Argument Clinic [https://devguide.python.org/development-tools/clinic/] tool.

以下の例では、引数 a と b が位置専用、 c と d が位置引数でもキーワード引数でも可、e と f はキーワード引数専用です:

def f(a, b, /, c, d, *, e, f):
    print(a, b, c, d, e, f)

以下は正しい関数呼び出しです:

f(10, 20, 30, d=40, e=50, f=60)

一方、以下は不正です:

f(10, b=20, c=30, d=40, e=50, f=60)   # b cannot be a keyword argument
f(10, 20, 30, 40, 50, f=60)           # e must be a keyword argument

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 divmod() function does not accept keyword arguments:

def divmod(a, b, /):
    "Emulate the built in divmod() function"
    return (a // b, a % b)

もう一つのユースケースは、引数名が有用ではない場合にキーワード引数としての利用を排除することです。例えば組み込み関数 len() は len(obj, /) というシグニチャです。これにより、以下のようなぎこちない呼び出しが排除されます:

len(obj='hello')  # The "obj" keyword argument impairs readability

引数を位置専用とすることは、のちに引数名を変更する際に呼び出し側のコードを壊してしまう心配がないという利点があります。例えば、statistics モジュールでは、dist という引数名が将来変更される可能性があります。これは、関数が以下のような定義だからこそ可能なことです:

def quantiles(dist, /, *, n=4, method='exclusive')
    ...

Since the parameters to the left of / are not exposed as possible keywords, the parameters names remain available for use in **kwargs:

>>> def f(a, b, /, **kwargs):
...     print(a, b, kwargs)
...
>>> f(10, 20, a=1, b=2, c=3)         # a and b are used in two ways
10 20 {'a': 1, 'b': 2, 'c': 3}

これにより、任意のキーワード引数を受け取る関数やメソッドを定義するのが、ぐんとシンプルになります。例えば、これは collections モジュールから抜き出したコードです：

class Counter(dict):

    def __init__(self, iterable=None, /, **kwds):
        # Note "iterable" is a possible keyword argument

詳細は PEP 570 [https://peps.python.org/pep-0570/] を参照してください。

(Pablo Galindo の貢献による bpo-36540 [https://bugs.python.org/issue?@action=redirect&bpo=36540]。)

コンパイル済みのバイトコードファイルのキャッシュを併存させるファイルシステム

暗黙のバイトコードキャッシュは、デフォルトでは各ソースコードのディレクトリ内の __pycache__ サブディレクトリを使用しますが、新たに追加された環境変数 PYTHONPYCACHEPREFIX （またはコマンドラインオプション -X pycache_prefix) を指定すると、ソースコードと分離されたディレクトリツリーに格納されるようになります。

キャッシュの場所は sys.pycache_prefix で参照できます（__pycache__ を使用する場合は None になります）。

（Carl Meyer の貢献による bpo-33499 [https://bugs.python.org/issue?@action=redirect&bpo=33499]）

デバッグビルドとリリースビルドのABI 共通化

Python はリリースモード、デバッグモード両方のビルドにおいて、同じABI を用いるようになりました。Unix において、Python がデバッグモードでビルドされている場合、リリースモードで、あるいは安定ABI を用いて、ビルドされたC拡張モジュールを読み込むことができます。

Release builds and debug builds are now ABI compatible: defining the Py_DEBUG macro no longer implies the Py_TRACE_REFS macro, which introduces the only ABI incompatibility. The Py_TRACE_REFS macro, which adds the sys.getobjects() function and the PYTHONDUMPREFS environment variable, can be set using the new ./configure --with-trace-refs build option. (Contributed by Victor Stinner in bpo-36465 [https://bugs.python.org/issue?@action=redirect&bpo=36465].)

Unix においては、Android とCygwin を除き、C拡張モジュールはlibpython にリンクされなくなりました。静的リンクされたPython は、Python 共有ライブラリを用いてビルドされたC拡張モジュールを読み込めます。(Victor Stinner の貢献による bpo-21536 [https://bugs.python.org/issue?@action=redirect&bpo=21536].)

Unix において、Python がデバッグモードでビルドされている場合、インポートは、リリースモードで、あるいは安定ABI を用いて、ビルドされたC拡張モジュールを探すようになりました。(Victor Stinner の貢献による bpo-36722 [https://bugs.python.org/issue?@action=redirect&bpo=36722].)

Python をアプリケーション内に組み込むためには、新しい --embed オプションを有効にして python3-config --libs --embed とすると、 -lpython3.8 を有効にできます。(アプリケーションがlibpython にリンクされます) Python3.8 以前との互換性を保つためには、 python3-config --libs --embed をまず試みてから、失敗した場合 python3-config --libs (--embed なし) にフォールバックしてください。

Python をアプリケーションに組み込むために、python-3.8-embed pkg-config モジュールが追加されました: pkg-config python-3.8-embed --libs の出力は、-lpython3.8 を含みます。 Python3.8 以前との互換性を保つためには、pkg-config python-X.Y-embed --libs をまず試みてから、失敗した場合 pkg-config python-X.Y --libs (--embed なし) にフォールバックしてください。(X.Y を使用するPython のバージョンに置き換えてください)

一方で、pkg-config python3.8 --libs は出力に -lpython3.8 を含まなくなりました。C拡張モジュールは、libpython にリンクされるべきではありません。 (スクリプトによって処理される、Android とCygwin を除く) この変更では、意図的に後方互換性をなくしています。(Victor Stinner の貢献による bpo-36721 [https://bugs.python.org/issue?@action=redirect&bpo=36721])

f-string での = を用いたオブジェクトの表現

フォーマット済み文字列リテラル(f-string) において = 指定子が有効になりました。f'{expr=}' のようなf-string は、f-string に書かれた式、イコール記号、式を評価されたものの文字列表現、の順で表示されます。例えば:

>>> user = 'eric_idle'
>>> member_since = date(1975, 7, 31)
>>> f'{user=} {member_since=}'
"user='eric_idle' member_since=datetime.date(1975, 7, 31)"

通常の f-string 書式指定子 を用いると、より柔軟に式の結果の表示方法を変えられます:

>>> delta = date.today() - member_since
>>> f'{user=!s}  {delta.days=:,d}'
'user=eric_idle  delta.days=16,075'

= 指定子は式すべてを表示するので、次のような計算も表示できます:

>>> print(f'{theta=}  {cos(radians(theta))=:.3f}')
theta=30  cos(radians(theta))=0.866

(Eric V. Smith, Larry Hastings の貢献による bpo-36817 [https://bugs.python.org/issue?@action=redirect&bpo=36817])

PEP 578: Pythonランタイムの監査フック

このPEP は、監査用フックと信頼された Open のためのフックを追加します。これらは Python およびネイティブコードから利用できます。純粋に Python で書かれたフレームワークやアプリケーションはコードに関する追加情報を得ることができ、システム管理者や埋め込みでの利用者は Python のビルドを常に監査が有効な状態で利用できます。

詳細は PEP 578 [https://peps.python.org/pep-0578/] を参照してください。

PEP 587: Python 初期化設定

PEP 587 [https://peps.python.org/pep-0587/] による C API の改善により、Python 初期化時に、すべての初期化設定に対するより良い制御と改善されたエラー報告が得られます。

新たな構造体:

PyConfig

PyPreConfig

PyStatus

PyWideStringList

新たな関数:

PyConfig_Clear()

PyConfig_InitIsolatedConfig()

PyConfig_InitPythonConfig()

PyConfig_Read()

PyConfig_SetArgv()

PyConfig_SetBytesArgv()

PyConfig_SetBytesString()

PyConfig_SetString()

PyPreConfig_InitIsolatedConfig()

PyPreConfig_InitPythonConfig()

PyStatus_Error()

PyStatus_Exception()

PyStatus_Exit()

PyStatus_IsError()

PyStatus_IsExit()

PyStatus_NoMemory()

PyStatus_Ok()

PyWideStringList_Append()

PyWideStringList_Insert()

Py_BytesMain()

Py_ExitStatusException()

Py_InitializeFromConfig()

Py_PreInitialize()

Py_PreInitializeFromArgs()

Py_PreInitializeFromBytesArgs()

Py_RunMain()

このPEP は、_PyRuntimeState.preconfig (PyPreConfig 型) と PyInterpreterState.config (PyConfig 型) を内部構造体に加えます。PyInterpreterState.config は新たな参照設定となり、グローバル設定や他の内部変数を置き換えます。

Python 初期化設定 も参照してください。

詳細は PEP 587 [https://peps.python.org/pep-0587/] を参照してください。

(Victor Stinner の貢献による bpo-36763 [https://bugs.python.org/issue?@action=redirect&bpo=36763])

PEP 590: Vectorcall: a fast calling protocol for CPython

The Vectorcall Protocol is added to the Python/C API. It is meant to formalize existing optimizations which were already done for various classes. Any static type implementing a callable can use this protocol.

これは現在、暫定版です。Python3.9 から公開で使われることを目ざしています。

詳細は PEP 590 [https://peps.python.org/pep-0590/] を参照してください。

(Contributed by Jeroen Demeyer, Mark Shannon and Petr Viktorin in bpo-36974 [https://bugs.python.org/issue?@action=redirect&bpo=36974].)

Pickle プロトコルバージョン 5 による帯域外データバッファ

pickle モジュールが Python のプロセス間での大容量データ転送でマルチコアないしマルチマシンでの利点を得るためには、メモリコピーの削減のほか、データ種別に応じた圧縮などの個別に合わせた最適化が重要です。

pickle プロトコルバージョン5 は、PEP 3118 [https://peps.python.org/pep-3118/] 互換であるようなデータが、メインのpickle ストリームとは別の独立した通信レイヤで転送されるような、帯域外バッファを提供します。

詳細は PEP 574 [https://peps.python.org/pep-0574/] を参照してください。

(Antoine Pitrou の貢献による bpo-36785 [https://bugs.python.org/issue?@action=redirect&bpo=36785])

その他の言語変更

実装上の問題により、finally 節での continue 文は不正でした。Python3.8 では、この制限は取り除かれています。 (Serhiy Storchaka の貢献による bpo-32489 [https://bugs.python.org/issue?@action=redirect&bpo=32489])

bool, int, fractions.Fraction タイプは、float や decimal.Decimal と同様の as_integer_ratio() メソッドを持つようになりました。このAPI の拡張によって、numerator, denominator = x.as_integer_ratio() のようなコードがより多くの数値型で動作します。 (Lisa Roach の貢献による bpo-33073 [https://bugs.python.org/issue?@action=redirect&bpo=33073] および Raymond Hettinger の貢献による bpo-37819 [https://bugs.python.org/issue?@action=redirect&bpo=37819])

int, float, complex のコンストラクタは、可能ならば __index__() 特殊メソッドを利用し、その場合は対応する __int__(), __float__() や __complex__() は使用できません。(Serhiy Storchaka の貢献による bpo-20092 [https://bugs.python.org/issue?@action=redirect&bpo=20092])

Added support of \N{name} escapes in regular expressions:

>>> notice = 'Copyright © 2019'
>>> copyright_year_pattern = re.compile(r'\N{copyright sign}\s*(\d{4})')
>>> int(copyright_year_pattern.search(notice).group(1))
2019

(Jonathan Eunice, Serhiy Storchaka の貢献による bpo-30688 [https://bugs.python.org/issue?@action=redirect&bpo=30688])

dict と dictview は、reversed() を使って逆順でイテレートすることが可能になりました。(Rémi Lapeyre の貢献による bpo-33462 [https://bugs.python.org/issue?@action=redirect&bpo=33462])

関数内でのキーワード名に関する構文の制限が強化されました。具体的には、f((keyword)=arg) の表現が許容されなくなりました。キーワード引数への代入の際、左側にキーワードそのまま以外の表現を許可する意図は、以前からありませんでした。 (Benjamin Peterson の貢献による bpo-34641 [https://bugs.python.org/issue?@action=redirect&bpo=34641])

yield 文と return 文における一般化されたイテラブルへの展開のために、全体を覆うかっこが不要になりました。これは yield と return の表現を、一般の展開と同様のわかりやすい形式にします:

>>> def parse(family):
        lastname, *members = family.split()
        return lastname.upper(), *members

>>> parse('simpsons homer marge bart lisa maggie')
('SIMPSONS', 'homer', 'marge', 'bart', 'lisa', 'maggie')

(David Cuthbert, Jordan Chapman の貢献による bpo-32117 [https://bugs.python.org/issue?@action=redirect&bpo=32117])

[(10, 20) (30, 40)] のようなコードでコンマが無い場合、コンパイラは SyntaxWarning を、分かりやすい形式で表示します。これで、最初のタプルが呼び出し可能ではないことを TypeError で表示するよりもわかりやすくなります。(Serhiy Storchaka の貢献による bpo-15248 [https://bugs.python.org/issue?@action=redirect&bpo=15248])

datetime.date, datetime.datetime, datetime.timedelta オブジェクトのサブクラス間の算術演算は、基底クラスではなくサブクラスのインスタンスを返すようになりました。この変更は、astimezone() のような、datetime.timedelta に対する算術演算を直接ないし間接的に使用する実装の戻り値の型に影響します。(Paul Ganssle の貢献による bpo-32417 [https://bugs.python.org/issue?@action=redirect&bpo=32417])

Python インタープリタがCtrl-C (SIGINT) によって中断され、KeyboardInterrupt 例外の結果が捕捉されなかった場合、Python プロセスはSIGINT シグナルか、呼び出したプロセスが、Ctrl-C によって終了したことを判別できるような適切な終了コードで終了するようになりました。　POSIX とWindows 上のシェルは、非対話セッション内でスクリプトの終了処理を適切に行うために、これを利用できます。(Gregory P. Smith を通してGoogle の貢献による bpo-1054041 [https://bugs.python.org/issue?@action=redirect&bpo=1054041])

先進的なプログラミングにおいて、既存の関数の types.CodeType オブジェクトを更新する必要が生じます。code オブジェクトはイミュータブルなので、既存のオブジェクトがあるにもかかわらず、新しい code オブジェクトを生成する必要がありました。パラメータが19もあるので、一から作成するのは非合理的です。新しい replace() メソッドを使えば、更新すべきパラメータを書くだけで、新しいクローンを作成することができます。

ここでは、statistics.mean() 関数がキーワード引数として data を使えないように変更する例を見てみましょう:

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

(Victor Stinner の貢献による bpo-37032 [https://bugs.python.org/issue?@action=redirect&bpo=37032])

For integers, the three-argument form of the 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 -1, and a suitable power of that inverse for other negative exponents. For example, to compute the modular multiplicative inverse [https://en.wikipedia.org/wiki/Modular_multiplicative_inverse] of 38 modulo 137, write:

>>> pow(38, -1, 137)
119
>>> 119 * 38 % 137
1

Modular inverses arise in the solution of linear Diophantine equations [https://en.wikipedia.org/wiki/Diophantine_equation]. For example, to find integer solutions for 4258𝑥 + 147𝑦 = 369, first rewrite as 4258𝑥 ≡ 369 (mod 147) then solve:

>>> x = 369 * pow(4258, -1, 147) % 147
>>> y = (4258 * x - 369) // -147
>>> 4258 * x + 147 * y
369

(Mark Dickinson の貢献による bpo-36027 [https://bugs.python.org/issue?@action=redirect&bpo=36027])

辞書内包表現は辞書リテラルと同期されたため、まずキーが解釈され、次に値が解釈されます:

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

この実行順の保証は代入式の役に立ち、キーの表現で代入されたものは、値の表現で使用することができます:

>>> 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'}

(Jörn Heissler の貢献による bpo-35224 [https://bugs.python.org/issue?@action=redirect&bpo=35224])

The 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 (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 __setstate__() method. (Contributed by Pierre Glaser and Olivier Grisel in bpo-35900 [https://bugs.python.org/issue?@action=redirect&bpo=35900].)

新たなモジュール

新しい importlib.metadata モジュールは、サードパーティパッケージからのメタデータ読み込みをサポートします。これは暫定版です。例えば、インストールされたパッケージのバージョンを得たり、エントリーポイントの一覧を得たりできます:

>>> # 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')]

(Barry Warsaw, Jason R. Coombs の貢献による bpo-34632 [https://bugs.python.org/issue?@action=redirect&bpo=34632])

改良されたモジュール

ast

AST ノードは end_lineno と end_col_offset の属性を持つようになりました。これは、正確なノードの終端位置を提供します。(これは、lineno と col_offset の属性を持つノードにのみ有効です)

新しい ast.get_source_segment() 関数は、特定の AST ノードのソースコードを返します。

(Ivan Levkivskyi の貢献による bpo-33416 [https://bugs.python.org/issue?@action=redirect&bpo=33416])

ast.parse() 関数の新しいフラグが有効になりました:

type_comments=True は、そのAST ノードに関連する、PEP 484 [https://peps.python.org/pep-0484/] と PEP 526 [https://peps.python.org/pep-0526/] に規定されるような型コメントを返します;

mode='func_type' can be used to parse PEP 484 [https://peps.python.org/pep-0484/] "signature type comments" (returned for function definition AST nodes);

feature_version=(3, N) を使うと、以前の Python 3 バージョンを指定できます。例えば、feature_version=(3, 4) とすると、async と await キーワードは、予約語ではないとして扱われます。

(Guido van Rossum の貢献による bpo-35766 [https://bugs.python.org/issue?@action=redirect&bpo=35766])

asyncio

asyncio.run() は暫定から安定API に移動しました。この関数は coroutine の実行と、イベントループを管理しながら自動的に結果を返すことに使用できます。例えば:

import asyncio

async def main():
    await asyncio.sleep(0)
    return 42

asyncio.run(main())

これは、だいたい次と等価です

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()

実装はこれよりもずっと複雑なものになっています。ですが、 asyncio.run() は非同期IOプログラムを動かす際にまず選ぶべき選択肢です。

(Yury Selivanov の貢献による bpo-32314 [https://bugs.python.org/issue?@action=redirect&bpo=32314])

python -m asyncio を実行すると、ネイティブ async 対話型インタプリタが起動します。高水準キーワード await を使うコードの試験を簡単に行えます。すべての呼び出しに対して新しいイベントループを作る asyncio.run() を呼び出す必要はありません:

$ 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

(Yury Selivanov の貢献による bpo-37028 [https://bugs.python.org/issue?@action=redirect&bpo=37028])

The exception asyncio.CancelledError now inherits from BaseException rather than Exception and no longer inherits from concurrent.futures.CancelledError. (Contributed by Yury Selivanov in bpo-32528 [https://bugs.python.org/issue?@action=redirect&bpo=32528].)

Windows では、イベントループのデフォルトが ProactorEventLoop になりました。(Victor Stinner の貢献による bpo-34687 [https://bugs.python.org/issue?@action=redirect&bpo=34687])

ProactorEventLoop はUDP もサポートするようになりました。(Adam Meily, Andrew Svetlov の貢献による bpo-29883 [https://bugs.python.org/issue?@action=redirect&bpo=29883])

ProactorEventLoop は KeyboardInterrupt ("CTRL+C") によって中断できるようになりました。(Vladimir Matveev の貢献による bpo-23057 [https://bugs.python.org/issue?@action=redirect&bpo=23057])

asyncio.Task 内で、内包されたコルーチンを得られる asyncio.Task.get_coro() メソッドが追加されました。(Alex Grönholm の貢献による bpo-36999 [https://bugs.python.org/issue?@action=redirect&bpo=36999])

asyncio.create_task() 関数か create_task() の name 引数を指定するか、もしくはタスクに対して set_name() メソッドを呼ぶことによって、asyncio タスクに名前をつけることができます。タスクの名前は、asyncio.Task の repr() 出力で、または get_name() メソッドで確認することができます。(Alex Grönholm の貢献による bpo-34270 [https://bugs.python.org/issue?@action=redirect&bpo=34270])

asyncio.loop.create_connection() は、Happy Eyeballs [https://en.wikipedia.org/wiki/Happy_Eyeballs] をサポートするようになりました。挙動を定義するため、2つの新しいパラメータ: happy_eyeballs_delay と interleave が加えられます。Happy Eyeballs アルゴリズムは、アプリケーションが IPv4 と IPv6 をサポートする場合、その両方を使って接続を保つことによって、アプリケーションの応答性を向上させます。(twisteroid ambassador の貢献による bpo-33530 [https://bugs.python.org/issue?@action=redirect&bpo=33530])

builtins

組み込み関数 compile() が、ast.PyCF_ALLOW_TOP_LEVEL_AWAIT フラグを受け取るようになりました。このフラグが有効である場合、compile() は、一般には有効な公文ではない、トップレベルの await, async for, async with 構文が有効になります。この場合、CO_COROUTINE フラグを持つ非同期コードオブジェクトが返されるでしょう。(Matthias Bussonnier の貢献による bpo-34616 [https://bugs.python.org/issue?@action=redirect&bpo=34616])

collections

collections.namedtuple() の _asdict() メソッドは、collections.OrderedDict ではなく dict を返すようになりました。Python 3.7 からは一般に辞書の順番が保証されるため、このような変更が可能です。OrderedDict 特有の機能を使いたい場合は、結果を OrderedDict(nt._asdict()) 型にキャストして使用することを推奨します。(Raymond Hettinger の貢献による bpo-35864 [https://bugs.python.org/issue?@action=redirect&bpo=35864])

cProfile

cProfile.Profile クラスは、コンテキストマネージャとして使用できるようになりました。このようにしてコードブロックをプロファイルします:

import cProfile

with cProfile.Profile() as profiler:
      # code to be profiled
      ...

(Scott Sanderson の貢献による bpo-29235 [https://bugs.python.org/issue?@action=redirect&bpo=29235])

csv

csv.DictReader は、collections.OrderedDict ではなく dict のインスタンスを返すようになりました。この変更によって、順序を保ちながら、より高速にかつメモリの使用量を減らして実行できます。(Michael Selik の貢献による bpo-34003 [https://bugs.python.org/issue?@action=redirect&bpo=34003])

curses

ncurses ライブラリの、構造化されたバージョン情報を保持する変数を追加しました: ncurses_version　 (Serhiy Storchaka の貢献による bpo-31680 [https://bugs.python.org/issue?@action=redirect&bpo=31680])

ctypes

Windows では、CDLL とそのサブクラスが winmode 引数を受け取り、根底の LoadLibraryEx 呼び出しのフラグを指定できるようになりました。デフォルトでは、フラグは (フルパスか部分パスが初期DLL を読み込むのに使われていた場合) そのDLL が保存されている場所を含んだ信頼済みの場所と、add_dll_directory() によって加えられた場所からのみ、DLL を読み込むようになっています。(Steve Dower の貢献による bpo-36085 [https://bugs.python.org/issue?@action=redirect&bpo=36085])

datetime

Added new alternate constructors datetime.date.fromisocalendar() and datetime.datetime.fromisocalendar(), which construct date and datetime objects respectively from ISO year, week number, and weekday; these are the inverse of each class's isocalendar method. (Contributed by Paul Ganssle in bpo-36004 [https://bugs.python.org/issue?@action=redirect&bpo=36004].)

functools

functools.lru_cache() は、デコレータを返す関数としての使い方に加えて、デコレータそのものとしても使えるようになりました。両方の使い方ができます:

@lru_cache
def f(x):
    ...

@lru_cache(maxsize=256)
def f(x):
    ...

(Raymond Hettinger の貢献による bpo-36772 [https://bugs.python.org/issue?@action=redirect&bpo=36772])

インスタンスが存在する間、計算型プロパティをキャッシュする functools.cached_property() デコレータが追加されました:

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)

(Carl Meyer の貢献による bpo-21145 [https://bugs.python.org/issue?@action=redirect&bpo=21145])

single dispatch を利用して、メソッドを ジェネリック関数 に変換する functools.singledispatchmethod() デコレータが追加されました:

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]

(Ethan Smith の貢献による bpo-32380 [https://bugs.python.org/issue?@action=redirect&bpo=32380])

gc

get_objects() は、オブジェクトを得る世代を指定するオプションのパラメータ引数 generation を受け取るようになりました。(Pablo Galindo の貢献による bpo-36016 [https://bugs.python.org/issue?@action=redirect&bpo=36016])

gettext

pgettext() を含む、類似のいくつかの関数が追加されました。 (Franz Glasner, Éric Araujo, Cheryl Sabella の貢献による bpo-2504 [https://bugs.python.org/issue?@action=redirect&bpo=2504])

gzip

出力の再現性のために、gzip.compress() に mtime パラメータが追加されました。 (Guo Ci Teo の貢献による bpo-34898 [https://bugs.python.org/issue?@action=redirect&bpo=34898])

不正な、あるいは破損した gzip ファイルのうち、所定の種類のものについて、OSError にかわって BadGzipFile 例外が送出されるようになりました。(Filip Gruszczyński, Michele Orrù, Zackery Spytz の貢献による bpo-6584 [https://bugs.python.org/issue?@action=redirect&bpo=6584])

IDLE と idelelib

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 [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 [https://bugs.python.org/issue?@action=redirect&bpo=5680] and bpo-37627 [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 [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 [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 [https://bugs.python.org/issue?@action=redirect&bpo=4603].)

Escape key now closes IDLE completion windows. (Contributed by Johnny Najera in bpo-38944 [https://bugs.python.org/issue?@action=redirect&bpo=38944].)

上で挙げた変更は 3.7 のメンテナンスリリースにバックポートされました。

Add keywords to module name completion list. (Contributed by Terry J. Reedy in bpo-37765 [https://bugs.python.org/issue?@action=redirect&bpo=37765].)

inspect

inspect.getdoc() 関数は、__slots__ 属性に値が docstrings であるような dict がある場合、docstrings の内容を探索できるようになりました。これは、既に property()、classmethod()、staticmethod() に現在あるような、ドキュメント生成の選択肢を提供します:

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)

(Raymond Hettinger の貢献による bpo-36326 [https://bugs.python.org/issue?@action=redirect&bpo=36326])

io

In development mode (-X env) and in debug build, the io.IOBase finalizer now logs the exception if the close() method fails. The exception is ignored silently by default in release build. (Contributed by Victor Stinner in bpo-18748 [https://bugs.python.org/issue?@action=redirect&bpo=18748].)

itertools

itertools.accumulate() 関数に、初期値を定める、オプションの initial キーワード引数が追加されました:

>>> from itertools import accumulate
>>> list(accumulate([10, 5, 30, 15], initial=1000))
[1000, 1010, 1015, 1045, 1060]

(Lisa Roach の貢献による bpo-34659 [https://bugs.python.org/issue?@action=redirect&bpo=34659])

json.tool

一行ごとに別々の JSON オブジェクトへ解析をする --json-lines オプションが追加されました。(Weipeng Hong の貢献による bpo-31553 [https://bugs.python.org/issue?@action=redirect&bpo=31553])

logging

logging.basicConfig() に force キーワード引数が追加されました。これが真になっている場合、ルートのロガーに取り付けられたハンドラは全て取り除かれ、他の引数によって指定された設定が有効になる前に閉じられます。

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 [https://bugs.python.org/issue?@action=redirect&bpo=33897].)

math

二点間のユークリッド距離を計算する math.dist() 関数が追加されました。(Raymond Hettinger の貢献による bpo-33089 [https://bugs.python.org/issue?@action=redirect&bpo=33089])

math.hypot() 関数は、3次元以上を扱えるように拡張されました。以前は、二次元の場合のみに対応していました。(Raymond Hettinger の貢献による bpo-33089 [https://bugs.python.org/issue?@action=redirect&bpo=33089])

sum() に類似する関数として、初期値(デフォルトは1) に対してイテレート可能なオブジェクトの数を掛けていく math.prod() 関数が追加されました:

>>> prior = 0.8
>>> likelihoods = [0.625, 0.84, 0.30]
>>> math.prod(likelihoods, start=prior)
0.126

(Pablo Galindo の貢献による bpo-35606 [https://bugs.python.org/issue?@action=redirect&bpo=35606])

2つの組み合わせの関数 math.perm() と math.comb() が追加されました:

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

(Yash Aggarwal, Keller Fuchs, Serhiy Storchaka, Raymond Hettinger の貢献による bpo-37128 [https://bugs.python.org/issue?@action=redirect&bpo=37128], bpo-37178 [https://bugs.python.org/issue?@action=redirect&bpo=37178], bpo-35431 [https://bugs.python.org/issue?@action=redirect&bpo=35431])

浮動小数点数を介することなく、正確な整数の二乗根を計算する関数 math.isqrt() が追加されました。この関数は、巨大な整数にも使用できます。floor(sqrt(n)) より高速ですが、math.sqrt() より少し遅いです:

>>> r = 650320427
>>> s = r ** 2
>>> isqrt(s - 1)         # correct
650320426
>>> floor(sqrt(s - 1))   # incorrect
650320427

(Mark Dickinson の貢献による bpo-36887 [https://bugs.python.org/issue?@action=redirect&bpo=36887])

math.factorial() 関数は、引数に int、またはそれに類似するもの以外を受け取らなくなりました。(Pablo Galindo の貢献による bpo-33083 [https://bugs.python.org/issue?@action=redirect&bpo=33083])

mmap

The mmap.mmap class now has an madvise() method to access the madvise() system call. (Contributed by Zackery Spytz in bpo-32941 [https://bugs.python.org/issue?@action=redirect&bpo=32941].)

multiprocessing

Added new multiprocessing.shared_memory module. (Contributed by Davin Potts in bpo-35813 [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 [https://bugs.python.org/issue?@action=redirect&bpo=33725].)

os

Added new function add_dll_directory() on Windows for providing additional search paths for native dependencies when importing extension modules or loading DLLs using ctypes. (Contributed by Steve Dower in bpo-36085 [https://bugs.python.org/issue?@action=redirect&bpo=36085].)

A new os.memfd_create() function was added to wrap the memfd_create() syscall. (Contributed by Zackery Spytz and Christian Heimes in bpo-26836 [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, os.stat() will now traverse anything supported by the operating system, while os.lstat() will only open reparse points that identify as "name surrogates" while others are opened as for os.stat(). In all cases, stat_result.st_mode will only have S_IFLNK set for symbolic links and not other kinds of reparse points. To identify other kinds of reparse point, check the new stat_result.st_reparse_tag attribute.

On Windows, os.readlink() is now able to read directory junctions. Note that islink() will return False for directory junctions, and so code that checks islink first will continue to treat junctions as directories, while code that handles errors from os.readlink() may now treat junctions as links.

(Contributed by Steve Dower in bpo-37834 [https://bugs.python.org/issue?@action=redirect&bpo=37834].)

os.path

os.path functions that return a boolean result like exists(), lexists(), isdir(), isfile(), islink(), and ismount() now return False instead of raising ValueError or its subclasses UnicodeEncodeError and UnicodeDecodeError for paths that contain characters or bytes unrepresentable at the OS level. (Contributed by Serhiy Storchaka in bpo-33721 [https://bugs.python.org/issue?@action=redirect&bpo=33721].)

expanduser() on Windows now prefers the USERPROFILE environment variable and does not use HOME, which is not normally set for regular user accounts. (Contributed by Anthony Sottile in bpo-36264 [https://bugs.python.org/issue?@action=redirect&bpo=36264].)

isdir() on Windows no longer returns True for a link to a non-existent directory.

realpath() on Windows now resolves reparse points, including symlinks and directory junctions.

(Contributed by Steve Dower in bpo-37834 [https://bugs.python.org/issue?@action=redirect&bpo=37834].)

pathlib

pathlib.Path methods that return a boolean result like exists(), is_dir(), is_file(), is_mount(), is_symlink(), is_block_device(), is_char_device(), is_fifo(), is_socket() now return False instead of raising ValueError or its subclass UnicodeEncodeError for paths that contain characters unrepresentable at the OS level. (Contributed by Serhiy Storchaka in bpo-33721 [https://bugs.python.org/issue?@action=redirect&bpo=33721].)

Added pathlib.Path.link_to() which creates a hard link pointing to a path. (Contributed by Joannah Nanjekye in bpo-26978 [https://bugs.python.org/issue?@action=redirect&bpo=26978]) Note that link_to was deprecated in 3.10 and removed in 3.12 in favor of a hardlink_to method added in 3.10 which matches the semantics of the existing symlink_to method.

pickle

pickle extensions subclassing the C-optimized Pickler can now override the pickling logic of functions and classes by defining the special reducer_override() method. (Contributed by Pierre Glaser and Olivier Grisel in bpo-35900 [https://bugs.python.org/issue?@action=redirect&bpo=35900].)

plistlib

Added new plistlib.UID and enabled support for reading and writing NSKeyedArchiver-encoded binary plists. (Contributed by Jon Janzen in bpo-26707 [https://bugs.python.org/issue?@action=redirect&bpo=26707].)

pprint

The 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, pprint.pp() that is like pprint.pprint() but with sort_dicts defaulting to False:

>>> from pprint import pprint, pp
>>> d = dict(source='input.txt', operation='filter', destination='output.txt')
>>> pp(d, width=40)                  # Original order
{'source': 'input.txt',
 'operation': 'filter',
 'destination': 'output.txt'}
>>> pprint(d, width=40)              # Keys sorted alphabetically
{'destination': 'output.txt',
 'operation': 'filter',
 'source': 'input.txt'}

(Contributed by Rémi Lapeyre in bpo-30670 [https://bugs.python.org/issue?@action=redirect&bpo=30670].)

py_compile

py_compile.compile() now supports silent mode. (Contributed by Joannah Nanjekye in bpo-22640 [https://bugs.python.org/issue?@action=redirect&bpo=22640].)

shlex

The new shlex.join() function acts as the inverse of shlex.split(). (Contributed by Bo Bayles in bpo-32102 [https://bugs.python.org/issue?@action=redirect&bpo=32102].)

shutil

shutil.copytree() now accepts a new dirs_exist_ok keyword argument. (Contributed by Josh Bronson in bpo-20849 [https://bugs.python.org/issue?@action=redirect&bpo=20849].)

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 tarfile module. (Contributed by C.A.M. Gerlach in bpo-30661 [https://bugs.python.org/issue?@action=redirect&bpo=30661].)

shutil.rmtree() on Windows now removes directory junctions without recursively removing their contents first. (Contributed by Steve Dower in bpo-37834 [https://bugs.python.org/issue?@action=redirect&bpo=37834].)

socket

Added create_server() and 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 [https://bugs.python.org/issue?@action=redirect&bpo=17561].)

The socket.if_nameindex(), socket.if_nametoindex(), and socket.if_indextoname() functions have been implemented on Windows. (Contributed by Zackery Spytz in bpo-37007 [https://bugs.python.org/issue?@action=redirect&bpo=37007].)

ssl

Added post_handshake_auth to enable and verify_client_post_handshake() to initiate TLS 1.3 post-handshake authentication. (Contributed by Christian Heimes in bpo-34670 [https://bugs.python.org/issue?@action=redirect&bpo=34670].)

statistics

Added statistics.fmean() as a faster, floating point variant of statistics.mean(). (Contributed by Raymond Hettinger and Steven D'Aprano in bpo-35904 [https://bugs.python.org/issue?@action=redirect&bpo=35904].)

Added statistics.geometric_mean() (Contributed by Raymond Hettinger in bpo-27181 [https://bugs.python.org/issue?@action=redirect&bpo=27181].)

Added statistics.multimode() that returns a list of the most common values. (Contributed by Raymond Hettinger in bpo-35892 [https://bugs.python.org/issue?@action=redirect&bpo=35892].)

Added 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 [https://bugs.python.org/issue?@action=redirect&bpo=36546].)

Added statistics.NormalDist, a tool for creating and manipulating normal distributions of a random variable. (Contributed by Raymond Hettinger in bpo-36018 [https://bugs.python.org/issue?@action=redirect&bpo=36018].)

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

sys

Add new 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 (gc.collect()). (Contributed by Victor Stinner in bpo-36829 [https://bugs.python.org/issue?@action=redirect&bpo=36829].)

tarfile

The 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 [https://bugs.python.org/issue?@action=redirect&bpo=36268].)

threading

Add a new threading.excepthook() function which handles uncaught threading.Thread.run() exception. It can be overridden to control how uncaught threading.Thread.run() exceptions are handled. (Contributed by Victor Stinner in bpo-1230540 [https://bugs.python.org/issue?@action=redirect&bpo=1230540].)

Add a new threading.get_native_id() function and a native_id attribute to the 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 get_native_id for more information. (Contributed by Jake Tesler in bpo-36084 [https://bugs.python.org/issue?@action=redirect&bpo=36084].)

tokenize

The tokenize module now implicitly emits a 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 [https://bugs.python.org/issue?@action=redirect&bpo=33899].)

tkinter

Added methods selection_from(), selection_present(), selection_range() and selection_to() in the tkinter.Spinbox class. (Contributed by Juliette Monsel in bpo-34829 [https://bugs.python.org/issue?@action=redirect&bpo=34829].)

Added method moveto() in the tkinter.Canvas class. (Contributed by Juliette Monsel in bpo-23831 [https://bugs.python.org/issue?@action=redirect&bpo=23831].)

The tkinter.PhotoImage class now has transparency_get() and transparency_set() methods. (Contributed by Zackery Spytz in bpo-25451 [https://bugs.python.org/issue?@action=redirect&bpo=25451].)

time

Added new clock CLOCK_UPTIME_RAW for macOS 10.12. (Contributed by Joannah Nanjekye in bpo-35702 [https://bugs.python.org/issue?@action=redirect&bpo=35702].)

typing

The typing module incorporates several new features:

A dictionary type with per-key types. See PEP 589 [https://peps.python.org/pep-0589/] and 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:

class Location(TypedDict, total=False):
    lat_long: tuple
    grid_square: str
    xy_coordinate: tuple

Literal types. See PEP 586 [https://peps.python.org/pep-0586/] and typing.Literal. Literal types indicate that a parameter or return value is constrained to one or more specific literal values:

def get_status(port: int) -> Literal['connected', 'disconnected']:
    ...

"Final" variables, functions, methods and classes. See PEP 591 [https://peps.python.org/pep-0591/], typing.Final and typing.final(). The final qualifier instructs a static type checker to restrict subclassing, overriding, or reassignment:

pi: Final[float] = 3.1415926536

Protocol definitions. See PEP 544 [https://peps.python.org/pep-0544/], typing.Protocol and typing.runtime_checkable(). Simple ABCs like typing.SupportsInt are now Protocol subclasses.

New protocol class typing.SupportsIndex.

New functions typing.get_origin() and typing.get_args().

unicodedata

The unicodedata module has been upgraded to use the Unicode 12.1.0 [https://blog.unicode.org/2019/05/unicode-12-1-en.html] release.

New function 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 [https://bugs.python.org/issue?@action=redirect&bpo=32285] and bpo-37966 [https://bugs.python.org/issue?@action=redirect&bpo=37966]).

unittest

Added AsyncMock to support an asynchronous version of Mock. Appropriate new assert functions for testing have been added as well. (Contributed by Lisa Roach in bpo-26467 [https://bugs.python.org/issue?@action=redirect&bpo=26467]).

Added addModuleCleanup() and addClassCleanup() to unittest to support cleanups for setUpModule() and setUpClass(). (Contributed by Lisa Roach in bpo-24412 [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 [https://bugs.python.org/issue?@action=redirect&bpo=35047].)

unittest module gained support for coroutines to be used as test cases with unittest.IsolatedAsyncioTestCase. (Contributed by Andrew Svetlov in bpo-32972 [https://bugs.python.org/issue?@action=redirect&bpo=32972].)

以下はプログラム例です:

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()

venv

venv now includes an Activate.ps1 script on all platforms for activating virtual environments under PowerShell Core 6.1. (Contributed by Brett Cannon in bpo-32718 [https://bugs.python.org/issue?@action=redirect&bpo=32718].)

weakref

The proxy objects returned by weakref.proxy() now support the matrix multiplication operators @ and @= in addition to the other numeric operators. (Contributed by Mark Dickinson in bpo-36669 [https://bugs.python.org/issue?@action=redirect&bpo=36669].)

xml

As mitigation against DTD and external entity retrieval, the xml.dom.minidom and xml.sax modules no longer process external entities by default. (Contributed by Christian Heimes in bpo-17239 [https://bugs.python.org/issue?@action=redirect&bpo=17239].)

The .find*() methods in the xml.etree.ElementTree module support wildcard searches like {*}tag which ignores the namespace and {namespace}* which returns all tags in the given namespace. (Contributed by Stefan Behnel in bpo-28238 [https://bugs.python.org/issue?@action=redirect&bpo=28238].)

The xml.etree.ElementTree module provides a new function –xml.etree.ElementTree.canonicalize() that implements C14N 2.0. (Contributed by Stefan Behnel in bpo-13611 [https://bugs.python.org/issue?@action=redirect&bpo=13611].)

The target object of xml.etree.ElementTree.XMLParser can receive namespace declaration events through the new callback methods start_ns() and end_ns(). Additionally, the 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 [https://bugs.python.org/issue?@action=redirect&bpo=36676] and bpo-36673 [https://bugs.python.org/issue?@action=redirect&bpo=36673].)

xmlrpc

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 [https://bugs.python.org/issue?@action=redirect&bpo=35153].)

最適化

The subprocess module can now use the 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:

close_fds is false;

preexec_fn, pass_fds, cwd and start_new_session parameters are not set;

the executable path contains a directory.

(Contributed by Joannah Nanjekye and Victor Stinner in bpo-35537 [https://bugs.python.org/issue?@action=redirect&bpo=35537].)

shutil.copyfile(), shutil.copy(), shutil.copy2(), shutil.copytree() and 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 "outfd.write(infd.read())". On Windows shutil.copyfile() uses a bigger default buffer size (1 MiB instead of 16 KiB) and a memoryview()-based variant of 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 プラットフォーム依存の効率的なコピー操作 section. (Contributed by Giampaolo Rodolà in bpo-33671 [https://bugs.python.org/issue?@action=redirect&bpo=33671].)

shutil.copytree() uses os.scandir() function and all copy functions depending from it use cached 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 os.stat() syscalls is reduced by 38% making shutil.copytree() especially faster on network filesystems. (Contributed by Giampaolo Rodolà in bpo-33695 [https://bugs.python.org/issue?@action=redirect&bpo=33695].)

The default protocol in the 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.

Removed one Py_ssize_t member from 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 [https://bugs.python.org/issue?@action=redirect&bpo=33597].)

uuid.UUID now uses __slots__ to reduce its memory footprint. (Contributed by Wouter Bolsterlee and Tal Einat in bpo-30977 [https://bugs.python.org/issue?@action=redirect&bpo=30977])

Improved performance of 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 [https://bugs.python.org/issue?@action=redirect&bpo=35664].)

Sped-up field lookups in 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 [https://bugs.python.org/issue?@action=redirect&bpo=32492].)

The list constructor does not overallocate the internal item buffer if the input iterable has a known length (the input implements __len__). This makes the created list 12% smaller on average. (Contributed by Raymond Hettinger and Pablo Galindo in bpo-33234 [https://bugs.python.org/issue?@action=redirect&bpo=33234].)

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 [https://bugs.python.org/issue?@action=redirect&bpo=36012].)

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 [https://bugs.python.org/issue?@action=redirect&bpo=23867], bpo-35582 [https://bugs.python.org/issue?@action=redirect&bpo=35582] and bpo-36127 [https://bugs.python.org/issue?@action=redirect&bpo=36127].)

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 [https://bugs.python.org/issue?@action=redirect&bpo=26219].)

ビルドならびに C API の変更

Default sys.abiflags became an empty string: the 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 [https://bugs.python.org/issue?@action=redirect&bpo=36707].)

Example of changes:

Only python3.8 program is installed, python3.8m program is gone.

Only python3.8-config script is installed, python3.8m-config script is gone.

The 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 .cpython-37m-x86_64-linux-gnu.so became .cpython-38-x86_64-linux-gnu.so in Python 3.8.

The header files have been reorganized to better separate the different kinds of APIs:

Include/*.h should be the portable public stable C API.

Include/cpython/*.h should be the unstable C API specific to CPython; public API, with some private API prefixed by _Py or _PY.

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

(Contributed by Victor Stinner in bpo-35134 [https://bugs.python.org/issue?@action=redirect&bpo=35134] and bpo-35081 [https://bugs.python.org/issue?@action=redirect&bpo=35081], work initiated by Eric Snow in Python 3.7.)

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:

Py_INCREF(), Py_DECREF()

Py_XINCREF(), Py_XDECREF()

PyObject_INIT(), PyObject_INIT_VAR()

Private functions: _PyObject_GC_TRACK(), _PyObject_GC_UNTRACK(), _Py_Dealloc()

(Contributed by Victor Stinner in bpo-35059 [https://bugs.python.org/issue?@action=redirect&bpo=35059].)

The PyByteArray_Init() and 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 [https://bugs.python.org/issue?@action=redirect&bpo=35713].)

The result of PyExceptionClass_Name() is now of type const char * rather of char *. (Contributed by Serhiy Storchaka in bpo-33818 [https://bugs.python.org/issue?@action=redirect&bpo=33818].)

The duality of Modules/Setup.dist and Modules/Setup has been removed. Previously, when updating the CPython source tree, one had to manually copy Modules/Setup.dist (inside the source tree) to 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 Modules/Setup inside the source tree. People who want to customize that file are encouraged to maintain their changes in a git fork of CPython or as patch files, as they would do for any other change to the source tree.

(Contributed by Antoine Pitrou in bpo-32430 [https://bugs.python.org/issue?@action=redirect&bpo=32430].)

Functions that convert Python number to C integer like PyLong_AsLong() and argument parsing functions like PyArg_ParseTuple() with integer converting format units like 'i' will now use the __index__() special method instead of __int__(), if available. The deprecation warning will be emitted for objects with the __int__() method but without the __index__() method (like Decimal and Fraction). PyNumber_Check() will now return 1 for objects implementing __index__(). PyNumber_Long(), PyNumber_Float() and PyFloat_AsDouble() also now use the __index__() method if available. (Contributed by Serhiy Storchaka in bpo-36048 [https://bugs.python.org/issue?@action=redirect&bpo=36048] and bpo-20092 [https://bugs.python.org/issue?@action=redirect&bpo=20092].)

Heap-allocated type objects will now increase their reference count in PyObject_Init() (and its parallel macro PyObject_INIT) instead of in PyType_GenericAlloc(). Types that modify instance allocation or deallocation may need to be adjusted. (Contributed by Eddie Elizondo in bpo-35810 [https://bugs.python.org/issue?@action=redirect&bpo=35810].)

The new function PyCode_NewWithPosOnlyArgs() allows to create code objects like PyCode_New(), but with an extra posonlyargcount parameter for indicating the number of positional-only arguments. (Contributed by Pablo Galindo in bpo-37221 [https://bugs.python.org/issue?@action=redirect&bpo=37221].)

Py_SetPath() now sets sys.executable to the program full path (Py_GetProgramFullPath()) rather than to the program name (Py_GetProgramName()). (Contributed by Victor Stinner in bpo-38234 [https://bugs.python.org/issue?@action=redirect&bpo=38234].)

非推奨

The distutils bdist_wininst command is now deprecated, use bdist_wheel (wheel packages) instead. (Contributed by Victor Stinner in bpo-37481 [https://bugs.python.org/issue?@action=redirect&bpo=37481].)

Deprecated methods getchildren() and getiterator() in the ElementTree module now emit a DeprecationWarning instead of PendingDeprecationWarning. They will be removed in Python 3.9. (Contributed by Serhiy Storchaka in bpo-29209 [https://bugs.python.org/issue?@action=redirect&bpo=29209].)

Passing an object that is not an instance of concurrent.futures.ThreadPoolExecutor to loop.set_default_executor() is deprecated and will be prohibited in Python 3.9. (Contributed by Elvis Pranskevichus in bpo-34075 [https://bugs.python.org/issue?@action=redirect&bpo=34075].)

The __getitem__() methods of xml.dom.pulldom.DOMEventStream, wsgiref.util.FileWrapper and 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 [https://bugs.python.org/issue?@action=redirect&bpo=9372].)

The typing.NamedTuple class has deprecated the _field_types attribute in favor of the __annotations__ attribute which has the same information. (Contributed by Raymond Hettinger in bpo-36320 [https://bugs.python.org/issue?@action=redirect&bpo=36320].)

ast classes Num, Str, Bytes, NameConstant and Ellipsis are considered deprecated and will be removed in future Python versions. Constant should be used instead. (Contributed by Serhiy Storchaka in bpo-32892 [https://bugs.python.org/issue?@action=redirect&bpo=32892].)

ast.NodeVisitor methods visit_Num(), visit_Str(), visit_Bytes(), visit_NameConstant() and visit_Ellipsis() are deprecated now and will not be called in future Python versions. Add the visit_Constant() method to handle all constant nodes. (Contributed by Serhiy Storchaka in bpo-36917 [https://bugs.python.org/issue?@action=redirect&bpo=36917].)

The asyncio.coroutine() decorator is deprecated and will be removed in version 3.10. Instead of @asyncio.coroutine, use async def instead. (Contributed by Andrew Svetlov in bpo-36921 [https://bugs.python.org/issue?@action=redirect&bpo=36921].)

In asyncio, the explicit passing of a loop argument has been deprecated and will be removed in version 3.10 for the following: asyncio.sleep(), asyncio.gather(), asyncio.shield(), asyncio.wait_for(), asyncio.wait(), asyncio.as_completed(), asyncio.Task, asyncio.Lock, asyncio.Event, asyncio.Condition, asyncio.Semaphore, asyncio.BoundedSemaphore, asyncio.Queue, asyncio.create_subprocess_exec(), and asyncio.create_subprocess_shell().

The explicit passing of coroutine objects to asyncio.wait() has been deprecated and will be removed in version 3.11. (Contributed by Yury Selivanov in bpo-34790 [https://bugs.python.org/issue?@action=redirect&bpo=34790].)

The following functions and methods are deprecated in the gettext module: lgettext(), ldgettext(), lngettext() and 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 bind_textdomain_codeset(), methods output_charset() and set_output_charset(), and the codeset parameter of functions translation() and install() are also deprecated, since they are only used for the l*gettext() functions. (Contributed by Serhiy Storchaka in bpo-33710 [https://bugs.python.org/issue?@action=redirect&bpo=33710].)

The isAlive() method of threading.Thread has been deprecated. (Contributed by Donghee Na in bpo-35283 [https://bugs.python.org/issue?@action=redirect&bpo=35283].)

Many builtin and extension functions that take integer arguments will now emit a deprecation warning for Decimals, Fractions and any other objects that can be converted to integers only with a loss (e.g. that have the __int__() method but do not have the __index__() method). In future version they will be errors. (Contributed by Serhiy Storchaka in bpo-36048 [https://bugs.python.org/issue?@action=redirect&bpo=36048].)

Deprecated passing the following arguments as keyword arguments:

func in functools.partialmethod(), weakref.finalize(), profile.Profile.runcall(), cProfile.Profile.runcall(), bdb.Bdb.runcall(), trace.Trace.runfunc() and curses.wrapper().

function in unittest.TestCase.addCleanup().

fn in the submit() method of concurrent.futures.ThreadPoolExecutor and concurrent.futures.ProcessPoolExecutor.

callback in contextlib.ExitStack.callback(), contextlib.AsyncExitStack.callback() and contextlib.AsyncExitStack.push_async_callback().

c and typeid in the create() method of multiprocessing.managers.Server and multiprocessing.managers.SharedMemoryServer.

obj in weakref.finalize().

In future releases of Python, they will be positional-only. (Contributed by Serhiy Storchaka in bpo-36492 [https://bugs.python.org/issue?@action=redirect&bpo=36492].)

API と機能の削除

The following features and APIs have been removed from Python 3.8:

Starting with Python 3.3, importing ABCs from collections was deprecated, and importing should be done from collections.abc. Being able to import from collections was marked for removal in 3.8, but has been delayed to 3.9. (See bpo-36952 [https://bugs.python.org/issue?@action=redirect&bpo=36952].)

The macpath module, deprecated in Python 3.7, has been removed. (Contributed by Victor Stinner in bpo-35471 [https://bugs.python.org/issue?@action=redirect&bpo=35471].)

The function platform.popen() has been removed, after having been deprecated since Python 3.3: use os.popen() instead. (Contributed by Victor Stinner in bpo-35345 [https://bugs.python.org/issue?@action=redirect&bpo=35345].)

The function time.clock() has been removed, after having been deprecated since Python 3.3: use time.perf_counter() or time.process_time() instead, depending on your requirements, to have well-defined behavior. (Contributed by Matthias Bussonnier in bpo-36895 [https://bugs.python.org/issue?@action=redirect&bpo=36895].)

The pyvenv script has been removed in favor of python3.8 -m venv to help eliminate confusion as to what Python interpreter the pyvenv script is tied to. (Contributed by Brett Cannon in bpo-25427 [https://bugs.python.org/issue?@action=redirect&bpo=25427].)

parse_qs, parse_qsl, and escape are removed from the cgi module. They are deprecated in Python 3.2 or older. They should be imported from the urllib.parse and html modules instead.

filemode function is removed from the tarfile module. It is not documented and deprecated since Python 3.3.

The 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 keyword-only. (Contributed by Serhiy Storchaka in bpo-29209 [https://bugs.python.org/issue?@action=redirect&bpo=29209].)

Removed the doctype() method of XMLParser. (Contributed by Serhiy Storchaka in bpo-29209 [https://bugs.python.org/issue?@action=redirect&bpo=29209].)

"unicode_internal" codec is removed. (Contributed by Inada Naoki in bpo-36297 [https://bugs.python.org/issue?@action=redirect&bpo=36297].)

The Cache and Statement objects of the sqlite3 module are not exposed to the user. (Contributed by Aviv Palivoda in bpo-30262 [https://bugs.python.org/issue?@action=redirect&bpo=30262].)

The bufsize keyword argument of fileinput.input() and fileinput.FileInput() which was ignored and deprecated since Python 3.6 has been removed. bpo-36952 [https://bugs.python.org/issue?@action=redirect&bpo=36952] (Contributed by Matthias Bussonnier.)

The functions sys.set_coroutine_wrapper() and sys.get_coroutine_wrapper() deprecated in Python 3.7 have been removed; bpo-36933 [https://bugs.python.org/issue?@action=redirect&bpo=36933] (Contributed by Matthias Bussonnier.)

Python 3.8 への移植

このセクションでは前述の変更とバグフィックスにより必要となるかもしれないコードの変更を列挙します:

Python の挙動の変更

Yield expressions (both yield and yield from clauses) are now disallowed in comprehensions and generator expressions (aside from the iterable expression in the leftmost for clause). (Contributed by Serhiy Storchaka in bpo-10544 [https://bugs.python.org/issue?@action=redirect&bpo=10544].)

The compiler now produces a SyntaxWarning when identity checks (is and 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 (== and !=) instead. (Contributed by Serhiy Storchaka in bpo-34850 [https://bugs.python.org/issue?@action=redirect&bpo=34850].)

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 [https://bugs.python.org/issue?@action=redirect&bpo=35459].)

Removed __str__ implementations from builtin types bool, int, float, complex and few classes from the standard library. They now inherit __str__() from object. As result, defining the __repr__() method in the subclass of these classes will affect their string representation. (Contributed by Serhiy Storchaka in bpo-36793 [https://bugs.python.org/issue?@action=redirect&bpo=36793].)

On AIX, sys.platform doesn't contain the major version anymore. It is always 'aix', instead of 'aix3' .. 'aix7'. Since older Python versions include the version number, so it is recommended to always use sys.platform.startswith('aix'). (Contributed by M. Felt in bpo-36588 [https://bugs.python.org/issue?@action=redirect&bpo=36588].)

PyEval_AcquireLock() and PyEval_AcquireThread() now terminate the current thread if called while the interpreter is finalizing, making them consistent with PyEval_RestoreThread(), Py_END_ALLOW_THREADS(), and PyGILState_Ensure(). If this behavior is not desired, guard the call by checking _Py_IsFinalizing() or sys.is_finalizing(). (Contributed by Joannah Nanjekye in bpo-36475 [https://bugs.python.org/issue?@action=redirect&bpo=36475].)

Python API の変更

The os.getcwdb() function now uses the UTF-8 encoding on Windows, rather than the ANSI code page: see PEP 529 [https://peps.python.org/pep-0529/] for the rationale. The function is no longer deprecated on Windows. (Contributed by Victor Stinner in bpo-37412 [https://bugs.python.org/issue?@action=redirect&bpo=37412].)

subprocess.Popen can now use os.posix_spawn() in some cases for better performance. On Windows Subsystem for Linux and QEMU User Emulation, the Popen constructor using os.posix_spawn() no longer raises an exception on errors like "missing program". Instead the child process fails with a non-zero returncode. (Contributed by Joannah Nanjekye and Victor Stinner in bpo-35537 [https://bugs.python.org/issue?@action=redirect&bpo=35537].)

The preexec_fn argument of * subprocess.Popen is no longer compatible with subinterpreters. The use of the parameter in a subinterpreter now raises RuntimeError. (Contributed by Eric Snow in bpo-34651 [https://bugs.python.org/issue?@action=redirect&bpo=34651], modified by Christian Heimes in bpo-37951 [https://bugs.python.org/issue?@action=redirect&bpo=37951].)

The imap.IMAP4.logout() method no longer silently ignores arbitrary exceptions. (Contributed by Victor Stinner in bpo-36348 [https://bugs.python.org/issue?@action=redirect&bpo=36348].)

The function platform.popen() has been removed, after having been deprecated since Python 3.3: use os.popen() instead. (Contributed by Victor Stinner in bpo-35345 [https://bugs.python.org/issue?@action=redirect&bpo=35345].)

The 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 [https://bugs.python.org/issue?@action=redirect&bpo=35892].)

The selection() method of the 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 selection_set() for changing the selection. (Contributed by Serhiy Storchaka in bpo-31508 [https://bugs.python.org/issue?@action=redirect&bpo=31508].)

The writexml(), toxml() and toprettyxml() methods of xml.dom.minidom, and the write() method of xml.etree, now preserve the attribute order specified by the user. (Contributed by Diego Rojas and Raymond Hettinger in bpo-34160 [https://bugs.python.org/issue?@action=redirect&bpo=34160].)

A dbm.dumb database opened with flags 'r' is now read-only. dbm.dumb.open() with flags 'r' and 'w' no longer creates a database if it does not exist. (Contributed by Serhiy Storchaka in bpo-32749 [https://bugs.python.org/issue?@action=redirect&bpo=32749].)

The doctype() method defined in a subclass of XMLParser will no longer be called and will emit a RuntimeWarning instead of a DeprecationWarning. Define the doctype() method on a target for handling an XML doctype declaration. (Contributed by Serhiy Storchaka in bpo-29209 [https://bugs.python.org/issue?@action=redirect&bpo=29209].)

A RuntimeError is now raised when the custom metaclass doesn't provide the __classcell__ entry in the namespace passed to type.__new__. A DeprecationWarning was emitted in Python 3.6--3.7. (Contributed by Serhiy Storchaka in bpo-23722 [https://bugs.python.org/issue?@action=redirect&bpo=23722].)

The cProfile.Profile class can now be used as a context manager. (Contributed by Scott Sanderson in bpo-29235 [https://bugs.python.org/issue?@action=redirect&bpo=29235].)

shutil.copyfile(), shutil.copy(), shutil.copy2(), shutil.copytree() and shutil.move() use platform-specific "fast-copy" syscalls (see プラットフォーム依存の効率的なコピー操作 section).

shutil.copyfile() default buffer size on Windows was changed from 16 KiB to 1 MiB.

The PyGC_Head struct has changed completely. All code that touched the struct member should be rewritten. (See bpo-33597 [https://bugs.python.org/issue?@action=redirect&bpo=33597].)

The PyInterpreterState struct has been moved into the "internal" header files (specifically Include/internal/pycore_pystate.h). An opaque 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 [https://bugs.python.org/issue?@action=redirect&bpo=35886].)

The mmap.flush() method now returns 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 [https://bugs.python.org/issue?@action=redirect&bpo=2122].)

xml.dom.minidom and xml.sax modules no longer process external entities by default. (Contributed by Christian Heimes in bpo-17239 [https://bugs.python.org/issue?@action=redirect&bpo=17239].)

Deleting a key from a read-only dbm database (dbm.dumb, dbm.gnu or dbm.ndbm) raises error (dbm.dumb.error, dbm.gnu.error or dbm.ndbm.error) instead of KeyError. (Contributed by Xiang Zhang in bpo-33106 [https://bugs.python.org/issue?@action=redirect&bpo=33106].)

Simplified AST for literals. All constants will be represented as ast.Constant instances. Instantiating old classes Num, Str, Bytes, NameConstant and Ellipsis will return an instance of Constant. (Contributed by Serhiy Storchaka in bpo-32892 [https://bugs.python.org/issue?@action=redirect&bpo=32892].)

expanduser() on Windows now prefers the USERPROFILE environment variable and does not use HOME, which is not normally set for regular user accounts. (Contributed by Anthony Sottile in bpo-36264 [https://bugs.python.org/issue?@action=redirect&bpo=36264].)

The exception asyncio.CancelledError now inherits from BaseException rather than Exception and no longer inherits from concurrent.futures.CancelledError. (Contributed by Yury Selivanov in bpo-32528 [https://bugs.python.org/issue?@action=redirect&bpo=32528].)

The function asyncio.wait_for() now correctly waits for cancellation when using an instance of asyncio.Task. Previously, upon reaching timeout, it was cancelled and immediately returned. (Contributed by Elvis Pranskevichus in bpo-32751 [https://bugs.python.org/issue?@action=redirect&bpo=32751].)

The function 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 [https://bugs.python.org/issue?@action=redirect&bpo=37027].)

asyncio.BufferedProtocol has graduated to the stable API.

DLL dependencies for extension modules and DLLs loaded with ctypes on Windows are now resolved more securely. Only the system paths, the directory containing the DLL or PYD file, and directories added with add_dll_directory() are searched for load-time dependencies. Specifically, 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 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 [https://bugs.python.org/issue?@action=redirect&bpo=36085].)

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 [https://bugs.python.org/issue?@action=redirect&bpo=36623].)

types.CodeType has a new parameter in the second position of the constructor (posonlyargcount) to support positional-only arguments defined in PEP 570 [https://peps.python.org/pep-0570/]. The first argument (argcount) now represents the total number of positional arguments (including positional-only arguments). The new replace() method of types.CodeType can be used to make the code future-proof.

The parameter digestmod for hmac.new() no longer uses the MD5 digest by default.

C API の変更

The PyCompilerFlags structure got a new cf_feature_version field. It should be initialized to PY_MINOR_VERSION. The field is ignored by default, and is used if and only if PyCF_ONLY_AST flag is set in cf_flags. (Contributed by Guido van Rossum in bpo-35766 [https://bugs.python.org/issue?@action=redirect&bpo=35766].)

The PyEval_ReInitThreads() function has been removed from the C API. It should not be called explicitly: use PyOS_AfterFork_Child() instead. (Contributed by Victor Stinner in bpo-36728 [https://bugs.python.org/issue?@action=redirect&bpo=36728].)

On Unix, C extensions are no longer linked to libpython except on Android and Cygwin. When Python is embedded, libpython must not be loaded with RTLD_LOCAL, but RTLD_GLOBAL instead. Previously, using RTLD_LOCAL, it was already not possible to load C extensions which were not linked to libpython, like C extensions of the standard library built by the *shared* section of Modules/Setup. (Contributed by Victor Stinner in bpo-21536 [https://bugs.python.org/issue?@action=redirect&bpo=21536].)

Use of # variants of formats in parsing or building value (e.g. PyArg_ParseTuple(), Py_BuildValue(), PyObject_CallFunction(), etc.) without PY_SSIZE_T_CLEAN defined raises DeprecationWarning now. It will be removed in 3.10 or 4.0. Read 引数の解釈と値の構築 for detail. (Contributed by Inada Naoki in bpo-36381 [https://bugs.python.org/issue?@action=redirect&bpo=36381].)

Instances of heap-allocated types (such as those created with PyType_FromSpec()) hold a reference to their type object. Increasing the reference count of these type objects has been moved from PyType_GenericAlloc() to the more low-level functions, PyObject_Init() and PyObject_INIT(). This makes types created through PyType_FromSpec() behave like other classes in managed code.

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:

Remove Py_INCREF on the type object after allocating an instance - if any. This may happen after calling PyObject_New, PyObject_NewVar, PyObject_GC_New(), PyObject_GC_NewVar(), or any other custom allocator that uses PyObject_Init() or PyObject_INIT().

例:

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;
}

Ensure that all custom tp_dealloc functions of heap-allocated types decrease the type's reference count.

例:

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
}

(Contributed by Eddie Elizondo in bpo-35810 [https://bugs.python.org/issue?@action=redirect&bpo=35810].)

The Py_DEPRECATED() macro has been implemented for MSVC. The macro now must be placed before the symbol name.

例:

Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);

(Contributed by Zackery Spytz in bpo-33407 [https://bugs.python.org/issue?@action=redirect&bpo=33407].)

The interpreter does not pretend to support binary compatibility of extension types across feature releases, anymore. A PyTypeObject exported by a third-party extension module is supposed to have all the slots expected in the current Python version, including tp_finalize (Py_TPFLAGS_HAVE_FINALIZE is not checked anymore before reading tp_finalize).

(Contributed by Antoine Pitrou in bpo-32388 [https://bugs.python.org/issue?@action=redirect&bpo=32388].)

The functions PyNode_AddChild() and PyParser_AddToken() now accept two additional int arguments end_lineno and end_col_offset.

The libpython38.a file to allow MinGW tools to link directly against python38.dll is no longer included in the regular Windows distribution. If you require this file, it may be generated with the gendef and dlltool tools, which are part of the MinGW binutils package:

gendef - python38.dll > tmp.def
dlltool --dllname python38.dll --def tmp.def --output-lib libpython38.a

The location of an installed pythonXY.dll will depend on the installation options and the version and language of Windows. See Windows で Python を使う for more information. The resulting library should be placed in the same directory as pythonXY.lib, which is generally the libs directory under your Python installation.

(Contributed by Steve Dower in bpo-37351 [https://bugs.python.org/issue?@action=redirect&bpo=37351].)

CPython バイトコードの変更

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 break, continue and return.

Removed opcodes BREAK_LOOP, CONTINUE_LOOP, SETUP_LOOP and SETUP_EXCEPT. Added new opcodes ROT_FOUR, BEGIN_FINALLY, CALL_FINALLY and POP_FINALLY. Changed the behavior of END_FINALLY and WITH_CLEANUP_START.

(Contributed by Mark Shannon, Antoine Pitrou and Serhiy Storchaka in bpo-17611 [https://bugs.python.org/issue?@action=redirect&bpo=17611].)

Added new opcode END_ASYNC_FOR for handling exceptions raised when awaiting a next item in an async for loop. (Contributed by Serhiy Storchaka in bpo-33041 [https://bugs.python.org/issue?@action=redirect&bpo=33041].)

The 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 PEP 572 [https://peps.python.org/pep-0572/]. (Contributed by Jörn Heissler in bpo-35224 [https://bugs.python.org/issue?@action=redirect&bpo=35224].)

Demos and Tools

Added a benchmark script for timing various ways to access variables: Tools/scripts/var_access_benchmark.py. (Contributed by Raymond Hettinger in bpo-35884 [https://bugs.python.org/issue?@action=redirect&bpo=35884].)

Here's a summary of performance improvements since Python 3.3:

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

The benchmarks were measured on an Intel® Core™ i7-4960HQ processor [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 [https://www.python.org/downloads/macos/]. The benchmark script displays timings in nanoseconds.

Python3.8.1 での重要な変更点

セキュリティ上の重大な懸念により、asyncio.loop.create_datagram_endpoint() での reuse_address 引数は無効になりました。これはソケットオプション SO_REUSEADDR` のUDP における挙動が原因です。詳しくは、loop.create_datagram_endpoint() のドキュメントを参照してください。(Kyle Stanley, Antoine Pitrou, Yury Selivanov による貢献 bpo-37228 [https://bugs.python.org/issue?@action=redirect&bpo=37228])

Python3.8.2 での重要な変更点

Fixed a regression with the ignore callback of shutil.copytree(). The argument types are now str and List[str] again. (Contributed by Manuel Barkhau and Giampaolo Rodola in gh-83571 [https://github.com/python/cpython/issues/83571].)

Notable changes in Python 3.8.3

The constant values of future flags in the __future__ module are updated in order to prevent collision with compiler flags. Previously PyCF_ALLOW_TOP_LEVEL_AWAIT was clashing with CO_FUTURE_DIVISION. (Contributed by Batuhan Taskaya in gh-83743 [https://github.com/python/cpython/issues/83743])

Python3.8.8 での重要な変更点

Earlier Python versions allowed using both ; and & as query parameter separators in urllib.parse.parse_qs() and 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 & as the default. This change also affects cgi.parse() and 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 [https://bugs.python.org/issue?@action=redirect&bpo=42967].)

Notable changes in Python 3.8.9

A security fix alters the 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 trust_server_pasv_ipv4_address attribute on your FTP instance to True. (See gh-87451 [https://github.com/python/cpython/issues/87451])

Notable changes in Python 3.8.10

macOS 11.0 (Big Sur) と Appleシリコンの Mac のサポート

As of 3.8.10, Python now supports building and running on macOS 11 (Big Sur) and on Apple Silicon Macs (based on the ARM64 architecture). A new universal build variant, universal2, is now available to natively support both ARM64 and 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 [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)

Notable changes in Python 3.8.10

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 RFC 3986 [https://datatracker.ietf.org/doc/html/rfc3986.html], ASCII newline \n, \r and tab \t characters are stripped from the URL by the parser in urllib.parse preventing such attacks. The removal characters are controlled by a new module level variable urllib.parse._UNSAFE_URL_BYTES_TO_REMOVE. (See bpo-43882 [https://bugs.python.org/issue?@action=redirect&bpo=43882])

Notable changes in Python 3.8.12

Python API の変更

Starting with Python 3.8.12 the 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 socket.inet_aton() treats leading zeros as octal notation. glibc implementation of modern inet_pton() does not accept any leading zeros.

(Originally contributed by Christian Heimes in bpo-36384 [https://bugs.python.org/issue?@action=redirect&bpo=36384], and backported to 3.8 by Achraf Merzouki.)

Notable security feature in 3.8.14

Converting between int and str in bases other than 2 (binary), 4, 8 (octal), 16 (hexadecimal), or 32 such as base 10 (decimal) now raises a 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 CVE-2020-10735 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-10735]. This limit can be configured or disabled by environment variable, command line flag, or sys APIs. See the integer string conversion length limitation documentation. The default limit is 4300 digits in string form.

Notable changes in 3.8.17

tarfile

The extraction methods in tarfile, and 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 Extraction filters for details. In Python 3.12, use without the filter argument will show a DeprecationWarning. In Python 3.14, the default will switch to 'data'. (Contributed by Petr Viktorin in PEP 706 [https://peps.python.org/pep-0706/].)

What's New In Python 3.7

編集者:

Elvis Pranskevichus <elvis@magic.io>

この記事では Python 3.6 と比較した Python 3.7 の新機能を解説します。Python 3.7 は2018年6月27日にリリースされました。全詳細については 変更履歴 をご覧ください。

概要 -- リリースハイライト

新たな文法機能:

PEP 563 、型アノテーションの評価の遅延。

後方非互換な文法の変更:

async と await は予約されたキーワードになりました。

新たなライブラリモジュール:

contextvars: PEP 567 -- コンテキスト変数

dataclasses: PEP 557 -- データクラス

importlib.resources

新たな組み込み機能:

PEP 553 、新しい breakpoint() 関数。

Python のデータモデルの改善:

PEP 562 、モジュール属性へのアクセスのカスタマイズ。

PEP 560 、typing モジュールとジェネリック型に対する言語コアによるサポート。

dict オブジェクトの挿入順序を保存するという性質が、公式に Python 言語仕様の一部であると 宣言されました 。

標準ライブラリーの顕著な改善

asyncio モジュールに新しい機能が加わりました。顕著な 使い勝手とパフォーマンスの改善 です。

time モジュールが ナノ秒単位の分解能を持つ関数 をサポートするようになりました。

CPython の実装の改善:

デフォルトのテキストエンコーディングとして ASCII を使わなくなりました:

PEP 538 、レガシーな C ロケールの抑圧

PEP 540, UTF-8 実行時モードの強制

PEP 552 、決定論的な .pyc

New Python Development Mode

PEP 565 、 DeprecationWarning の取り扱いの改善

C API の改善:

PEP 539 、スレッドローカルなストレージのための新しい C API

ドキュメントの改善:

PEP 545 、 Python ドキュメント翻訳

新しいドキュメント翻訳: 日本語 [https://docs.python.org/ja/] 、 フランス語 [https://docs.python.org/fr/] 、 韓国語 [https://docs.python.org/ko/] 。

このリリースの特色は、多くの領域での特筆すべきパフォーマンスの改善です。最適化 節に詳細な一覧があります。

1つ前にリリースされた Python との互換性に影響を持つ変更の一覧については、 Python 3.7 への移植 節を参照してください。

新しい機能

PEP 563: アノテーションの遅延評価

Python における型ヒントの到来により、 PEP 3107 [https://peps.python.org/pep-3107/] で追加され PEP 526 [https://peps.python.org/pep-0526/] でさらに改善されたアノテーションの機能について、使い勝手に関する 2 つの明白な問題が明らかになりました:

アノテーションには現在のスコープで既に使える状態になっている名前しか使えない。言い換えれば、どんな種類の前方参照もサポートしない。

ソースコードに注釈を付けるのは Python プログラムの起動時間に好ましくない影響がある。

これらの問題はどちらもアノテーションの評価を遅延することで解決します。アノテーションの定義時に、アノテーションに含まれる式を評価するコードをコンパイルする代わりに、コンパイラは当該の式の AST と同等な文字列形式でアノテーションを保存します。必要であれば、 typing.get_type_hints() を使って実行時にアノテーションを解決できます。たいていのケースではその必要は無く、(短い文字列はインタプリタによって格納されるので) アノテーションを保存するコストはより安くなり、起動時間がより速くなります。

使い勝手の点では、アノテーションは前方参照をサポートするようになり、次の文法が妥当なものになりました:

class C:
    @classmethod
    def from_string(cls, source: str) -> C:
        ...

    def validate_b(self, obj: B) -> bool:
        ...

class B:
    ...

この変更は後方互換性を壊してしまうので、新しい振る舞いは Python 3.7 では __future__ インポートを使いモジュールごとに有効化する必要があります:

from __future__ import annotations

この振る舞いは Python 3.10 でデフォルトになります。

参考

PEP 563 [https://peps.python.org/pep-0563/] -- アノテーションの遅延評価

PEP written and implemented by Łukasz Langa.

PEP 538: レガシーな C ロケールの抑圧

Python 3 シリーズにおける継続中の課題の一つは、非 Windows プラットフォームではデフォルトの C ロケールつまり POSIX ロケールの使用から現在のところ必然的に導かれてしまう "7-bit ASCII" テキストエンコーディングの仮定を取り扱う賢明なデフォルトの方針を決定することです。

PEP 538 [https://peps.python.org/pep-0538/] はインタープリタのデフォルトのコマンドラインインターフェースを更新し、新しく加わった PYTHONCOERCECLOCALE 環境変数のドキュメントにある通り、自動的にロケールを UTF-8 に基づいた利用可能なロケールへ強制します。この方法で LC_CTYPE を自動的に設定すると、コアのインタープリタと (readline などの) ロケールを考慮する C 拡張はデフォルトのテキストエンコーディングとして ASCII ではなく UTF-8 を使うことになります。

PEP 11 [https://peps.python.org/pep-0011/] にあるプラットフォームのサポート定義も、適切に設定された非 ASCII に基づくロケールだけにテキスト処理の完全なサポートを制限するよう更新されました。

この変更の一部として、強制対象として定義されたのロケール (現時点では C.UTF-8, C.utf8, UTF-8) を使っているときの stdin と stdout のデフォルトのエラーハンドラは (strict ではなく) surrogateescape になります。 stderr のデフォルトのエラーハンドラは、ロケールに関係無く引き続き backslashreplace です。

デフォルトではロケールの強制は暗黙に行われますが、ロケールが関係する結合における問題のデバッグを支援するために、 PYTHONCOERCECLOCALE=warn を設定することで (stderr に直接出力される) 明示的な警告を要求できます。この設定を有効にしていると、コアのインタプリタの初期化時にレガシーな C ロケールが有効なままの場合、 Python 実行器が警告を出力します。

PEP 538 [https://peps.python.org/pep-0538/] のロケール強制には、(非 Python アプリケーションや古いバージョンの Python で動くのも含めた) 子プロセスに加え (GNU readline などの) 影響を受ける拡張モジュールにも利益がある一方、適切な対象ロケールが実行するシステムに存在することを要求するという負の面もあります。 (例えば、RHEL/CentOS 7 で起きているように) 適切な対象ロケールで利用可能なものが無いケースにきちんと対処するために、 Python 3.7 には PEP 540: 強制 UTF-8 実行モード も実装されています。

参考

PEP 538 [https://peps.python.org/pep-0538/] -- レガシーな C ロケールから UTF-8 ベースのロケールへの強制

PEP written and implemented by Nick Coghlan.

PEP 540: 強制 UTF-8 実行モード

The new -X utf8 command line option and PYTHONUTF8 environment variable can be used to enable the 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 sys.stdin and sys.stdout streams are set to 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 PEP 540 [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 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 PEP 540: 強制 UTF-8 実行モード).

The UTF-8 mode is enabled by default when the locale is C or POSIX, and the PEP 538 [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 PYTHONCOERCECLOCALE=0 being set, LC_ALL being set, or the lack of a suitable target locale).

参考

PEP 540 [https://peps.python.org/pep-0540/] -- 新しい UTF-8 モードの追加

PEP written and implemented by Victor Stinner

PEP 553: 組み込みの breakpoint()

Python 3.7 には、 Python デバッガへ入って行くための簡単で一貫した手段である、新しい組み込みの breakpoint() 関数があります。

Built-in breakpoint() calls sys.breakpointhook(). By default, the latter imports pdb and then calls pdb.set_trace(), but by binding sys.breakpointhook() to the function of your choosing, breakpoint() can enter any debugger. Additionally, the environment variable PYTHONBREAKPOINT can be set to the callable of your debugger of choice. Set PYTHONBREAKPOINT=0 to completely disable built-in breakpoint().

参考

PEP 553 [https://peps.python.org/pep-0553/] -- 組み込みの breakpoint()

PEP written and implemented by Barry Warsaw

PEP 539: スレッドローカルストレージのための新しい C API

While Python provides a C API for thread-local storage support; the existing 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.

PEP 539 [https://peps.python.org/pep-0539/] changes this by providing a new 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 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.

参考

PEP 539 [https://peps.python.org/pep-0539/] -- A New C-API for Thread-Local Storage in CPython

PEP written by Erik M. Bray; implementation by Masayuki Yamamoto.

PEP 562: モジュール属性へのアクセスのカスタマイズ

Python 3.7 ではモジュールに __getattr__() が定義でき、モジュール属性があるときでも無いときでもこのメソッドが呼び出されます。 __dir__() メソッドもモジュールに定義できます。

この機能が役に立つ典型的な実例はモジュール属性の非推奨化と遅延読み込みです。

参考

PEP 562 [https://peps.python.org/pep-0562/] -- モジュールの __getattr__ と __dir__

PEP written and implemented by Ivan Levkivskyi

PEP 564: ナノ秒単位の分解能を持つ新しい時間関数

モダンなシステムの時計の分解能は、 time.time() 関数やそれに類する関数が返す浮動小数点数の精度を越えることがあります。精度を失わないように、 PEP 564 [https://peps.python.org/pep-0564/] により既存の時間関数の 6 つの新しい "ナノ秒" 版が time モジュールに追加されました:

time.clock_gettime_ns()

time.clock_settime_ns()

time.monotonic_ns()

time.perf_counter_ns()

time.process_time_ns()

time.time_ns()

新しい関数は、整数値としてナノ秒単位の数値を返します。

Measurements [https://peps.python.org/pep-0564/#annex-clocks-resolution-in-python] show that on Linux and Windows the resolution of time.time_ns() is approximately 3 times better than that of time.time().

参考

PEP 564 [https://peps.python.org/pep-0564/] -- ナノ秒単位の分解能を持つ新しい時間関数の追加

PEP written and implemented by Victor Stinner

PEP 565: Show DeprecationWarning in __main__

The default handling of 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 __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:

FutureWarning: always displayed by default, recommended for warnings intended to be seen by application end users (e.g. for deprecated application configuration settings).

DeprecationWarning: displayed by default only in __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.

PendingDeprecationWarning: displayed by default only when running tests, intended for cases where a future version upgrade will change the warning category to DeprecationWarning or FutureWarning.

Previously both DeprecationWarning and 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.

参考

PEP 565 [https://peps.python.org/pep-0565/] -- Show DeprecationWarning in __main__

PEP written and implemented by Nick Coghlan

PEP 560: typing モジュールとジェネリック型に対する言語コアによるサポート

当初 PEP 484 [https://peps.python.org/pep-0484/] は、 CPython のインタプリタのコア部分に どんな 変更も施さないような方法で設計されていました。今では型ヒントと typing モジュールはコミュニティに広く使われるようになったため、この制限は取り除かれました。この PEP では、2 つの特殊メソッド __class_getitem__() と __mro_entries__ が導入され、これらのメソッドはほとんどのクラスと typing にある特別な構成物に使われています。その結果、型に関する様々な操作の速度が最大で 7 倍にまでなり、ジェネリック型はメタクラスの衝突を起こさずに使えるようになり、 typing にずっとあったいくつかのバグが修正されました。

参考

PEP 560 [https://peps.python.org/pep-0560/] -- typing モジュールとジェネリック型に対する言語コアによるサポート

PEP written and implemented by Ivan Levkivskyi

PEP 552: Hash-based .pyc Files

Python has traditionally checked the up-to-dateness of bytecode cache files (i.e., .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 [https://reproducible-builds.org/] and content-based build systems.

PEP 552 [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 .pyc files are called "hash-based". By default, Python still uses timestamp-based invalidation and does not generate hash-based .pyc files at runtime. Hash-based .pyc files may be generated with py_compile or compileall.

Hash-based .pyc files come in two variants: checked and unchecked. Python validates checked hash-based .pyc files against the corresponding source files at runtime but doesn't do so for unchecked hash-based pycs. Unchecked hash-based .pyc files are a useful performance optimization for environments where a system external to Python (e.g., the build system) is responsible for keeping .pyc files up-to-date.

See キャッシュされたバイトコードの無効化 for more information.

参考

PEP 552 [https://peps.python.org/pep-0552/] -- Deterministic pycs

PEP written and implemented by Benjamin Peterson

PEP 545: Python Documentation Translations

PEP 545 [https://peps.python.org/pep-0545/] describes the process of creating and maintaining Python documentation translations.

Three new translations have been added:

日本語: https://docs.python.org/ja/

フランス語: https://docs.python.org/fr/

韓国語: https://docs.python.org/ko/

参考

PEP 545 [https://peps.python.org/pep-0545/] -- Python ドキュメント翻訳

PEP written and implemented by Julien Palard, Inada Naoki, and Victor Stinner.

Python Development Mode (-X dev)

The new -X dev command line option or the new PYTHONDEVMODE environment variable can be used to enable Python Development Mode. When in development mode, Python performs additional runtime checks that are too expensive to be enabled by default. See Python Development Mode documentation for the full description.

その他の言語変更

An await expression and comprehensions containing an async for clause were illegal in the expressions in formatted string literals due to a problem with the implementation. In Python 3.7 this restriction was lifted.

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 [https://bugs.python.org/issue?@action=redirect&bpo=12844] and bpo-18896 [https://bugs.python.org/issue?@action=redirect&bpo=18896].)

bytes.fromhex() and bytearray.fromhex() now ignore all ASCII whitespace, not only spaces. (Contributed by Robert Xiao in bpo-28927 [https://bugs.python.org/issue?@action=redirect&bpo=28927].)

str, bytes, and bytearray gained support for the new 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 [https://bugs.python.org/issue?@action=redirect&bpo=32677].)

ImportError now displays module name and module __file__ path when from ... import ... fails. (Contributed by Matthias Bussonnier in bpo-29546 [https://bugs.python.org/issue?@action=redirect&bpo=29546].)

Circular imports involving absolute imports with binding a submodule to a name are now supported. (Contributed by Serhiy Storchaka in bpo-30024 [https://bugs.python.org/issue?@action=redirect&bpo=30024].)

object.__format__(x, '') is now equivalent to str(x) rather than format(str(self), ''). (Contributed by Serhiy Storchaka in bpo-28974 [https://bugs.python.org/issue?@action=redirect&bpo=28974].)

In order to better support dynamic creation of stack traces, types.TracebackType can now be instantiated from Python code, and the tb_next attribute on tracebacks is now writable. (Contributed by Nathaniel J. Smith in bpo-30579 [https://bugs.python.org/issue?@action=redirect&bpo=30579].)

When using the -m switch, 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 [https://bugs.python.org/issue?@action=redirect&bpo=33053].)

The new -X importtime option or the PYTHONPROFILEIMPORTTIME environment variable can be used to show the timing of each module import. (Contributed by Inada Naoki in bpo-31415 [https://bugs.python.org/issue?@action=redirect&bpo=31415].)

新たなモジュール

contextvars

The new contextvars module and a set of 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 asyncio and 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.

参考

PEP 567 [https://peps.python.org/pep-0567/] -- コンテキスト変数

PEP written and implemented by Yury Selivanov

データクラス

新しい dataclass() デコレータにより データクラス を宣言する方法が提供されます。データクラスは属性を記述するのに、クラス変数アノテーションを使います。コンストラクタや他の __repr__(), __eq__(), __hash__() などのマジックメソッドは自動で生成されます。

以下はプログラム例です:

@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)"

参考

PEP 557 [https://peps.python.org/pep-0557/] -- データクラス

PEP written and implemented by Eric V. Smith

importlib.resources

The new 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 get_resource_reader() function which returns a importlib.abc.ResourceReader instance to support this new API. Built-in file path loaders and zip file loaders both support this.

Contributed by Barry Warsaw and Brett Cannon in bpo-32248 [https://bugs.python.org/issue?@action=redirect&bpo=32248].

参考

importlib_resources [https://importlib-resources.readthedocs.io/en/latest/] -- a PyPI backport for earlier Python versions.

改良されたモジュール

argparse

The new ArgumentParser.parse_intermixed_args() method allows intermixing options and positional arguments. (Contributed by paul.j3 in bpo-14191 [https://bugs.python.org/issue?@action=redirect&bpo=14191].)

asyncio

The asyncio module has received many new features, usability and performance improvements. Notable changes include:

The new provisional 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 [https://bugs.python.org/issue?@action=redirect&bpo=32314].)

asyncio gained support for contextvars. loop.call_soon(), loop.call_soon_threadsafe(), loop.call_later(), loop.call_at(), and Future.add_done_callback() have a new optional keyword-only context parameter. Tasks now track their context automatically. See PEP 567 [https://peps.python.org/pep-0567/] for more details. (Contributed by Yury Selivanov in bpo-32436 [https://bugs.python.org/issue?@action=redirect&bpo=32436].)

The new asyncio.create_task() function has been added as a shortcut to asyncio.get_event_loop().create_task(). (Contributed by Andrew Svetlov in bpo-32311 [https://bugs.python.org/issue?@action=redirect&bpo=32311].)

The new loop.start_tls() method can be used to upgrade an existing connection to TLS. (Contributed by Yury Selivanov in bpo-23749 [https://bugs.python.org/issue?@action=redirect&bpo=23749].)

The new 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 [https://bugs.python.org/issue?@action=redirect&bpo=31819].)

The new asyncio.current_task() function returns the currently running Task instance, and the new asyncio.all_tasks() function returns a set of all existing Task instances in a given loop. The Task.current_task() and Task.all_tasks() methods have been deprecated. (Contributed by Andrew Svetlov in bpo-32250 [https://bugs.python.org/issue?@action=redirect&bpo=32250].)

The new provisional BufferedProtocol class allows implementing streaming protocols with manual control over the receive buffer. (Contributed by Yury Selivanov in bpo-32251 [https://bugs.python.org/issue?@action=redirect&bpo=32251].)

The new asyncio.get_running_loop() function returns the currently running loop, and raises a RuntimeError if no loop is running. This is in contrast with asyncio.get_event_loop(), which will create a new event loop if none is running. (Contributed by Yury Selivanov in bpo-32269 [https://bugs.python.org/issue?@action=redirect&bpo=32269].)

The new StreamWriter.wait_closed() coroutine method allows waiting until the stream writer is closed. The new StreamWriter.is_closing() method can be used to determine if the writer is closing. (Contributed by Andrew Svetlov in bpo-32391 [https://bugs.python.org/issue?@action=redirect&bpo=32391].)

The new loop.sock_sendfile() coroutine method allows sending files using os.sendfile when possible. (Contributed by Andrew Svetlov in bpo-32410 [https://bugs.python.org/issue?@action=redirect&bpo=32410].)

The new Future.get_loop() and Task.get_loop() methods return the instance of the loop on which a task or a future were created. Server.get_loop() allows doing the same for asyncio.Server objects. (Contributed by Yury Selivanov in bpo-32415 [https://bugs.python.org/issue?@action=redirect&bpo=32415] and Srinivas Reddy Thatiparthy in bpo-32418 [https://bugs.python.org/issue?@action=redirect&bpo=32418].)

It is now possible to control how instances of asyncio.Server begin serving. Previously, the server would start serving immediately when created. The new start_serving keyword argument to loop.create_server() and loop.create_unix_server(), as well as Server.start_serving(), and Server.serve_forever() can be used to decouple server instantiation and serving. The new Server.is_serving() method returns True if the server is serving. Server objects are now asynchronous context managers:

srv = await loop.create_server(...)

async with srv:
    # some code

# At this point, srv is closed and no longer accepts new connections.

(Contributed by Yury Selivanov in bpo-32662 [https://bugs.python.org/issue?@action=redirect&bpo=32662].)

Callback objects returned by loop.call_later() gained the new when() method which returns an absolute scheduled callback timestamp. (Contributed by Andrew Svetlov in bpo-32741 [https://bugs.python.org/issue?@action=redirect&bpo=32741].)

The loop.create_datagram_endpoint() method gained support for Unix sockets. (Contributed by Quentin Dawans in bpo-31245 [https://bugs.python.org/issue?@action=redirect&bpo=31245].)

The asyncio.open_connection(), asyncio.start_server() functions, loop.create_connection(), loop.create_server(), 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 [https://bugs.python.org/issue?@action=redirect&bpo=29970].)

The new Handle.cancelled() method returns True if the callback was cancelled. (Contributed by Marat Sharafutdinov in bpo-31943 [https://bugs.python.org/issue?@action=redirect&bpo=31943].)

The asyncio source has been converted to use the async/await syntax. (Contributed by Andrew Svetlov in bpo-32193 [https://bugs.python.org/issue?@action=redirect&bpo=32193].)

The new ReadTransport.is_reading() method can be used to determine the reading state of the transport. Additionally, calls to ReadTransport.resume_reading() and ReadTransport.pause_reading() are now idempotent. (Contributed by Yury Selivanov in bpo-32356 [https://bugs.python.org/issue?@action=redirect&bpo=32356].)

Loop methods which accept socket paths now support passing path-like objects. (Contributed by Yury Selivanov in bpo-32066 [https://bugs.python.org/issue?@action=redirect&bpo=32066].)

In asyncio TCP sockets on Linux are now created with TCP_NODELAY flag set by default. (Contributed by Yury Selivanov and Victor Stinner in bpo-27456 [https://bugs.python.org/issue?@action=redirect&bpo=27456].)

Exceptions occurring in cancelled tasks are no longer logged. (Contributed by Yury Selivanov in bpo-30508 [https://bugs.python.org/issue?@action=redirect&bpo=30508].)

New WindowsSelectorEventLoopPolicy and WindowsProactorEventLoopPolicy classes. (Contributed by Yury Selivanov in bpo-33792 [https://bugs.python.org/issue?@action=redirect&bpo=33792].)

Several asyncio APIs have been deprecated.

binascii

The b2a_uu() function now accepts an optional backtick keyword argument. When it's true, zeros are represented by '`' instead of spaces. (Contributed by Xiang Zhang in bpo-30103 [https://bugs.python.org/issue?@action=redirect&bpo=30103].)

calendar

HTMLCalendar クラスに、作成された HTML カレンダーの CSS クラスのカスタマイズを容易にするクラス属性が新しく加わりました。 (Contributed by Oz Tiram in bpo-30095 [https://bugs.python.org/issue?@action=redirect&bpo=30095].)

collections

collections.namedtuple() がデフォルト値をサポートするようになりました。 (Contributed by Raymond Hettinger in bpo-32320 [https://bugs.python.org/issue?@action=redirect&bpo=32320].)

compileall

compileall.compile_dir() learned the new invalidation_mode parameter, which can be used to enable hash-based .pyc invalidation. The invalidation mode can also be specified on the command line using the new --invalidation-mode argument. (Contributed by Benjamin Peterson in bpo-31650 [https://bugs.python.org/issue?@action=redirect&bpo=31650].)

concurrent.futures

ProcessPoolExecutor と ThreadPoolExecutor が新しいコンストラクタ引数 initializer と initargs をサポートするようになりました。 (Contributed by Antoine Pitrou in bpo-21423 [https://bugs.python.org/issue?@action=redirect&bpo=21423].)

ProcessPoolExecutor が新しい mp_context 引数を通して multiprocessing の context を受け取れるようになりました。 (Contributed by Thomas Moreau in bpo-31540 [https://bugs.python.org/issue?@action=redirect&bpo=31540].)

contextlib

The new nullcontext() is a simpler and faster no-op context manager than ExitStack. (Contributed by Jesse-Bakker in bpo-10049 [https://bugs.python.org/issue?@action=redirect&bpo=10049].)

The new asynccontextmanager(), AbstractAsyncContextManager, and AsyncExitStack have been added to complement their synchronous counterparts. (Contributed by Jelle Zijlstra in bpo-29679 [https://bugs.python.org/issue?@action=redirect&bpo=29679] and bpo-30241 [https://bugs.python.org/issue?@action=redirect&bpo=30241], and by Alexander Mohr and Ilya Kulakov in bpo-29302 [https://bugs.python.org/issue?@action=redirect&bpo=29302].)

cProfile

The cProfile command line now accepts -m module_name as an alternative to script path. (Contributed by Sanyam Khurana in bpo-21862 [https://bugs.python.org/issue?@action=redirect&bpo=21862].)

crypt

The crypt module now supports the Blowfish hashing method. (Contributed by Serhiy Storchaka in bpo-31664 [https://bugs.python.org/issue?@action=redirect&bpo=31664].)

The mksalt() function now allows specifying the number of rounds for hashing. (Contributed by Serhiy Storchaka in bpo-31702 [https://bugs.python.org/issue?@action=redirect&bpo=31702].)

datetime

The new datetime.fromisoformat() method constructs a datetime object from a string in one of the formats output by datetime.isoformat(). (Contributed by Paul Ganssle in bpo-15873 [https://bugs.python.org/issue?@action=redirect&bpo=15873].)

The tzinfo class now supports sub-minute offsets. (Contributed by Alexander Belopolsky in bpo-5288 [https://bugs.python.org/issue?@action=redirect&bpo=5288].)

dbm

dbm.dumb now supports reading read-only files and no longer writes the index file when it is not changed.

decimal

The decimal module now uses context variables to store the decimal context. (Contributed by Yury Selivanov in bpo-32630 [https://bugs.python.org/issue?@action=redirect&bpo=32630].)

dis

The 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 [https://bugs.python.org/issue?@action=redirect&bpo=11822].)

distutils

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 [https://bugs.python.org/issue?@action=redirect&bpo=11913].)

enum

The Enum learned the new _ignore_ class property, which allows listing the names of properties which should not become enum members. (Contributed by Ethan Furman in bpo-31801 [https://bugs.python.org/issue?@action=redirect&bpo=31801].)

In Python 3.8, attempting to check for non-Enum objects in Enum classes will raise a TypeError (e.g. 1 in Color); similarly, attempting to check for non-Flag objects in a Flag member will raise TypeError (e.g. 1 in Perm.RW); currently, both operations return False instead and are deprecated. (Contributed by Ethan Furman in bpo-33217 [https://bugs.python.org/issue?@action=redirect&bpo=33217].)

functools

functools.singledispatch() now supports registering implementations using type annotations. (Contributed by Łukasz Langa in bpo-32227 [https://bugs.python.org/issue?@action=redirect&bpo=32227].)

gc

The new 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 fork() call to make the GC copy-on-write friendly or to speed up collection. The new gc.unfreeze() functions reverses this operation. Additionally, gc.get_freeze_count() can be used to obtain the number of frozen objects. (Contributed by Li Zekun in bpo-31558 [https://bugs.python.org/issue?@action=redirect&bpo=31558].)

hmac

The hmac module now has an optimized one-shot digest() function, which is up to three times faster than HMAC(). (Contributed by Christian Heimes in bpo-32433 [https://bugs.python.org/issue?@action=redirect&bpo=32433].)

http.client

HTTPConnection and HTTPSConnection now support the new blocksize argument for improved upload throughput. (Contributed by Nir Soffer in bpo-31945 [https://bugs.python.org/issue?@action=redirect&bpo=31945].)

http.server

SimpleHTTPRequestHandler now supports the HTTP 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 [https://bugs.python.org/issue?@action=redirect&bpo=29654].)

SimpleHTTPRequestHandler accepts the new directory argument, in addition to the new --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 [https://bugs.python.org/issue?@action=redirect&bpo=28707].)

The new ThreadingHTTPServer class uses threads to handle requests using ThreadingMixin. It is used when http.server is run with -m. (Contributed by Julien Palard in bpo-31639 [https://bugs.python.org/issue?@action=redirect&bpo=31639].)

idlelib と IDLE

自動補完におけるいくつもの修正。 (Contributed by Louie Lu in bpo-15786 [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 [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 [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 [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 [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 [https://bugs.python.org/issue?@action=redirect&bpo=33642], bpo-33768 [https://bugs.python.org/issue?@action=redirect&bpo=33768], and bpo-33679 [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 [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 [https://bugs.python.org/issue?@action=redirect&bpo=1529353].)

上で挙げた変更は 3.6 のメンテナンスリリースにバックポートされました。

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 [https://bugs.python.org/issue?@action=redirect&bpo=5680] and bpo-37627 [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 [https://bugs.python.org/issue?@action=redirect&bpo=17535].)

importlib

The importlib.abc.ResourceReader ABC was introduced to support the loading of resources from packages. See also importlib.resources. (Contributed by Barry Warsaw, Brett Cannon in bpo-32248 [https://bugs.python.org/issue?@action=redirect&bpo=32248].)

importlib.reload() now raises ModuleNotFoundError if the module lacks a spec. (Contributed by Garvit Khatri in bpo-29851 [https://bugs.python.org/issue?@action=redirect&bpo=29851].)

importlib.find_spec() now raises ModuleNotFoundError instead of AttributeError if the specified parent module is not a package (i.e. lacks a __path__ attribute). (Contributed by Milan Oberkirch in bpo-30436 [https://bugs.python.org/issue?@action=redirect&bpo=30436].)

The new importlib.source_hash() can be used to compute the hash of the passed source. A hash-based .pyc file embeds the value returned by this function.

io

The new TextIOWrapper.reconfigure() method can be used to reconfigure the text stream with the new settings. (Contributed by Antoine Pitrou in bpo-30526 [https://bugs.python.org/issue?@action=redirect&bpo=30526] and INADA Naoki in bpo-15216 [https://bugs.python.org/issue?@action=redirect&bpo=15216].)

ipaddress

The new subnet_of() and supernet_of() methods of ipaddress.IPv6Network and ipaddress.IPv4Network can be used for network containment tests. (Contributed by Michel Albert and Cheryl Sabella in bpo-20825 [https://bugs.python.org/issue?@action=redirect&bpo=20825].)

itertools

itertools.islice() now accepts integer-like objects as start, stop, and slice arguments. (Contributed by Will Roberts in bpo-30537 [https://bugs.python.org/issue?@action=redirect&bpo=30537].)

locale

The new monetary argument to locale.format_string() can be used to make the conversion use monetary thousands separators and grouping strings. (Contributed by Garvit in bpo-10379 [https://bugs.python.org/issue?@action=redirect&bpo=10379].)

The locale.getpreferredencoding() function now always returns 'UTF-8' on Android or when in the forced UTF-8 mode.

logging

Logger インスタンスが pickle 化できるようになりました。 (Contributed by Vinay Sajip in bpo-30520 [https://bugs.python.org/issue?@action=redirect&bpo=30520].)

The new StreamHandler.setStream() method can be used to replace the logger stream after handler creation. (Contributed by Vinay Sajip in bpo-30522 [https://bugs.python.org/issue?@action=redirect&bpo=30522].)

It is now possible to specify keyword arguments to handler constructors in configuration passed to logging.config.fileConfig(). (Contributed by Preston Landers in bpo-31080 [https://bugs.python.org/issue?@action=redirect&bpo=31080].)

math

新しい math.remainder() 関数が IEEE 754 方式の剰余演算で実装されています。 Contributed by Mark Dickinson in bpo-29962 [https://bugs.python.org/issue?@action=redirect&bpo=29962].)

mimetypes

The MIME type of .bmp has been changed from 'image/x-ms-bmp' to 'image/bmp'. (Contributed by Nitish Chandra in bpo-22589 [https://bugs.python.org/issue?@action=redirect&bpo=22589].)

msilib

The new Database.Close() method can be used to close the MSI database. (Contributed by Berker Peksag in bpo-20486 [https://bugs.python.org/issue?@action=redirect&bpo=20486].)

multiprocessing

The new Process.close() method explicitly closes the process object and releases all resources associated with it. ValueError is raised if the underlying process is still running. (Contributed by Antoine Pitrou in bpo-30596 [https://bugs.python.org/issue?@action=redirect&bpo=30596].)

The new Process.kill() method can be used to terminate the process using the SIGKILL signal on Unix. (Contributed by Vitor Pereira in bpo-30794 [https://bugs.python.org/issue?@action=redirect&bpo=30794].)

Non-daemonic threads created by Process are now joined on process exit. (Contributed by Antoine Pitrou in bpo-18966 [https://bugs.python.org/issue?@action=redirect&bpo=18966].)

os

os.fwalk() now accepts the path argument as bytes. (Contributed by Serhiy Storchaka in bpo-28682 [https://bugs.python.org/issue?@action=redirect&bpo=28682].)

os.scandir() gained support for file descriptors. (Contributed by Serhiy Storchaka in bpo-25996 [https://bugs.python.org/issue?@action=redirect&bpo=25996].)

The new register_at_fork() function allows registering Python callbacks to be executed at process fork. (Contributed by Antoine Pitrou in bpo-16500 [https://bugs.python.org/issue?@action=redirect&bpo=16500].)

Added os.preadv() (combine the functionality of os.readv() and os.pread()) and os.pwritev() functions (combine the functionality of os.writev() and os.pwrite()). (Contributed by Pablo Galindo in bpo-31368 [https://bugs.python.org/issue?@action=redirect&bpo=31368].)

The mode argument of os.makedirs() no longer affects the file permission bits of newly created intermediate-level directories. (Contributed by Serhiy Storchaka in bpo-19930 [https://bugs.python.org/issue?@action=redirect&bpo=19930].)

os.dup2() now returns the new file descriptor. Previously, None was always returned. (Contributed by Benjamin Peterson in bpo-32441 [https://bugs.python.org/issue?@action=redirect&bpo=32441].)

The structure returned by os.stat() now contains the st_fstype attribute on Solaris and its derivatives. (Contributed by Jesús Cea Avión in bpo-32659 [https://bugs.python.org/issue?@action=redirect&bpo=32659].)

pathlib

The new 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 [https://bugs.python.org/issue?@action=redirect&bpo=30897].)

pdb

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 [https://bugs.python.org/issue?@action=redirect&bpo=31389].)

pdb command line now accepts -m module_name as an alternative to script file. (Contributed by Mario Corchero in bpo-32206 [https://bugs.python.org/issue?@action=redirect&bpo=32206].)

py_compile

py_compile.compile() -- and by extension, compileall -- now respects the SOURCE_DATE_EPOCH environment variable by unconditionally creating .pyc files for hash-based validation. This allows for guaranteeing reproducible builds [https://reproducible-builds.org/] of .pyc files when they are created eagerly. (Contributed by Bernhard M. Wiedemann in bpo-29708 [https://bugs.python.org/issue?@action=redirect&bpo=29708].)

pydoc

The pydoc server can now bind to an arbitrary hostname specified by the new -n command-line argument. (Contributed by Feanil Patel in bpo-31128 [https://bugs.python.org/issue?@action=redirect&bpo=31128].)

queue

The new SimpleQueue class is an unbounded FIFO queue. (Contributed by Antoine Pitrou in bpo-14976 [https://bugs.python.org/issue?@action=redirect&bpo=14976].)

re

The flags re.ASCII, re.LOCALE and re.UNICODE can be set within the scope of a group. (Contributed by Serhiy Storchaka in bpo-31690 [https://bugs.python.org/issue?@action=redirect&bpo=31690].)

re.split() now supports splitting on a pattern like r'\b', '^$' or (?=-) that matches an empty string. (Contributed by Serhiy Storchaka in bpo-25054 [https://bugs.python.org/issue?@action=redirect&bpo=25054].)

Regular expressions compiled with the 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 [https://bugs.python.org/issue?@action=redirect&bpo=30215].)

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 [https://bugs.python.org/issue?@action=redirect&bpo=30349].)

Compiled regular expression and match objects can now be copied using copy.copy() and copy.deepcopy(). (Contributed by Serhiy Storchaka in bpo-10076 [https://bugs.python.org/issue?@action=redirect&bpo=10076].)

signal

The new warn_on_full_buffer argument to the 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 [https://bugs.python.org/issue?@action=redirect&bpo=30050].)

socket

The new socket.getblocking() method returns True if the socket is in blocking mode and False otherwise. (Contributed by Yury Selivanov in bpo-32373 [https://bugs.python.org/issue?@action=redirect&bpo=32373].)

The new socket.close() function closes the passed socket file descriptor. This function should be used instead of os.close() for better compatibility across platforms. (Contributed by Christian Heimes in bpo-32454 [https://bugs.python.org/issue?@action=redirect&bpo=32454].)

The socket module now exposes the socket.TCP_CONGESTION (Linux 2.6.13), socket.TCP_USER_TIMEOUT (Linux 2.6.37), and socket.TCP_NOTSENT_LOWAT (Linux 3.12) constants. (Contributed by Omar Sandoval in bpo-26273 [https://bugs.python.org/issue?@action=redirect&bpo=26273] and Nathaniel J. Smith in bpo-29728 [https://bugs.python.org/issue?@action=redirect&bpo=29728].)

Support for socket.AF_VSOCK sockets has been added to allow communication between virtual machines and their hosts. (Contributed by Cathy Avery in bpo-27584 [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 [https://bugs.python.org/issue?@action=redirect&bpo=28134].)

socketserver

socketserver.ThreadingMixIn.server_close() now waits until all non-daemon threads complete. socketserver.ForkingMixIn.server_close() now waits until all child processes complete.

Add a new socketserver.ForkingMixIn.block_on_close class attribute to socketserver.ForkingMixIn and socketserver.ThreadingMixIn classes. Set the class attribute to False to get the pre-3.7 behaviour.

sqlite3

sqlite3.Connection now exposes the backup() method when the underlying SQLite library is at version 3.6.11 or higher. (Contributed by Lele Gaifax in bpo-27645 [https://bugs.python.org/issue?@action=redirect&bpo=27645].)

The database argument of sqlite3.connect() now accepts any path-like object, instead of just a string. (Contributed by Anders Lorentsen in bpo-31843 [https://bugs.python.org/issue?@action=redirect&bpo=31843].)

ssl

The ssl module now uses OpenSSL's builtin API instead of 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 SSLCertVerificationError and aborts the handshake with a proper TLS Alert message. The new exception contains additional information. Host name validation can be customized with SSLContext.hostname_checks_common_name. (Contributed by Christian Heimes in bpo-31399 [https://bugs.python.org/issue?@action=redirect&bpo=31399].)

注釈

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 サポート対象プラットフォームからの除外 for more details). The ssl module is mostly compatible with LibreSSL 2.7.2 and newer.

The ssl module no longer sends IP addresses in SNI TLS extension. (Contributed by Christian Heimes in bpo-32185 [https://bugs.python.org/issue?@action=redirect&bpo=32185].)

match_hostname() no longer supports partial wildcards like www*.example.org. (Contributed by Mandeep Singh in bpo-23033 [https://bugs.python.org/issue?@action=redirect&bpo=23033] and Christian Heimes in bpo-31399 [https://bugs.python.org/issue?@action=redirect&bpo=31399].)

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 updates. Default cipher suite selection can be configured at compile time. (Contributed by Christian Heimes in bpo-31429 [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 SSLSocket.server_hostname attribute now stores the expected hostname in A-label form ("xn--pythn-mua.org"), rather than the U-label form ("pythön.org"). (Contributed by Nathaniel J. Smith and Christian Heimes in bpo-28414 [https://bugs.python.org/issue?@action=redirect&bpo=28414].)

The 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 TLS 1.3. (Contributed by Christian Heimes in bpo-32947 [https://bugs.python.org/issue?@action=redirect&bpo=32947], bpo-20995 [https://bugs.python.org/issue?@action=redirect&bpo=20995], bpo-29136 [https://bugs.python.org/issue?@action=redirect&bpo=29136], bpo-30622 [https://bugs.python.org/issue?@action=redirect&bpo=30622] and bpo-33618 [https://bugs.python.org/issue?@action=redirect&bpo=33618])

SSLSocket and SSLObject no longer have a public constructor. Direct instantiation was never a documented and supported feature. Instances must be created with SSLContext methods wrap_socket() and wrap_bio(). (Contributed by Christian Heimes in bpo-32951 [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 SSLContext.minimum_version and SSLContext.maximum_version. Supported protocols are indicated by several new flags, such as HAS_TLSv1_1. (Contributed by Christian Heimes in bpo-32609 [https://bugs.python.org/issue?@action=redirect&bpo=32609].)

Added ssl.SSLContext.post_handshake_auth to enable and ssl.SSLSocket.verify_client_post_handshake() to initiate TLS 1.3 post-handshake authentication. (Contributed by Christian Heimes in gh-78851 [https://github.com/python/cpython/issues/78851].)

string

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 [https://bugs.python.org/issue?@action=redirect&bpo=1198569].)

subprocess

The subprocess.run() function accepts the new capture_output keyword argument. When true, stdout and stderr will be captured. This is equivalent to passing subprocess.PIPE as stdout and stderr arguments. (Contributed by Bo Bayles in bpo-32102 [https://bugs.python.org/issue?@action=redirect&bpo=32102].)

The subprocess.run function and the subprocess.Popen constructor now accept the text keyword argument as an alias to universal_newlines. (Contributed by Andrew Clegg in bpo-31756 [https://bugs.python.org/issue?@action=redirect&bpo=31756].)

On Windows the default for close_fds was changed from False to True when redirecting the standard handles. It's now possible to set close_fds to true when redirecting the standard handles. See subprocess.Popen. This means that close_fds now defaults to True on all supported platforms. (Contributed by Segev Finer in bpo-19764 [https://bugs.python.org/issue?@action=redirect&bpo=19764].)

The subprocess module is now more graceful when handling KeyboardInterrupt during subprocess.call(), subprocess.run(), or in a Popen context manager. It now waits a short amount of time for the child to exit, before continuing the handling of the KeyboardInterrupt exception. (Contributed by Gregory P. Smith in bpo-25942 [https://bugs.python.org/issue?@action=redirect&bpo=25942].)

sys

The new sys.breakpointhook() hook function is called by the built-in breakpoint(). (Contributed by Barry Warsaw in bpo-31353 [https://bugs.python.org/issue?@action=redirect&bpo=31353].)

On Android, the new sys.getandroidapilevel() returns the build-time Android API version. (Contributed by Victor Stinner in bpo-28740 [https://bugs.python.org/issue?@action=redirect&bpo=28740].)

The new sys.get_coroutine_origin_tracking_depth() function returns the current coroutine origin tracking depth, as set by the new sys.set_coroutine_origin_tracking_depth(). asyncio has been converted to use this new API instead of the deprecated sys.set_coroutine_wrapper(). (Contributed by Nathaniel J. Smith in bpo-32591 [https://bugs.python.org/issue?@action=redirect&bpo=32591].)

time

PEP 564 [https://peps.python.org/pep-0564/] adds six new functions with nanosecond resolution to the time module:

time.clock_gettime_ns()

time.clock_settime_ns()

time.monotonic_ns()

time.perf_counter_ns()

time.process_time_ns()

time.time_ns()

New clock identifiers have been added:

time.CLOCK_BOOTTIME (Linux): Identical to time.CLOCK_MONOTONIC, except it also includes any time that the system is suspended.

time.CLOCK_PROF (FreeBSD, NetBSD and OpenBSD): High-resolution per-process CPU timer.

time.CLOCK_UPTIME (FreeBSD, OpenBSD): Time whose absolute value is the time the system has been running and not suspended, providing accurate uptime measurement.

The new time.thread_time() and time.thread_time_ns() functions can be used to get per-thread CPU time measurements. (Contributed by Antoine Pitrou in bpo-32025 [https://bugs.python.org/issue?@action=redirect&bpo=32025].)

The new time.pthread_getcpuclockid() function returns the clock ID of the thread-specific CPU-time clock.

tkinter

The new tkinter.ttk.Spinbox class is now available. (Contributed by Alan Moore in bpo-32585 [https://bugs.python.org/issue?@action=redirect&bpo=32585].)

tracemalloc

tracemalloc.Traceback behaves more like regular tracebacks, sorting the frames from oldest to most recent. Traceback.format() now accepts negative limit, truncating the result to the abs(limit) oldest frames. To get the old behaviour, use the new most_recent_first argument to Traceback.format(). (Contributed by Jesse Bakker in bpo-32121 [https://bugs.python.org/issue?@action=redirect&bpo=32121].)

types

The new WrapperDescriptorType, MethodWrapperType, MethodDescriptorType, and ClassMethodDescriptorType classes are now available. (Contributed by Manuel Krebber and Guido van Rossum in bpo-29377 [https://bugs.python.org/issue?@action=redirect&bpo=29377], and Serhiy Storchaka in bpo-32265 [https://bugs.python.org/issue?@action=redirect&bpo=32265].)

The new types.resolve_bases() function resolves MRO entries dynamically as specified by PEP 560 [https://peps.python.org/pep-0560/]. (Contributed by Ivan Levkivskyi in bpo-32717 [https://bugs.python.org/issue?@action=redirect&bpo=32717].)

unicodedata

The internal unicodedata database has been upgraded to use Unicode 11 [https://www.unicode.org/versions/Unicode11.0.0/]. (Contributed by Benjamin Peterson.)

unittest

The new -k command-line option allows filtering tests by a name substring or a Unix shell-like pattern. For example, python -m unittest -k foo runs foo_tests.SomeTest.test_something, bar_tests.SomeTest.test_foo, but not bar_tests.FooTest.test_something. (Contributed by Jonas Haag in bpo-32071 [https://bugs.python.org/issue?@action=redirect&bpo=32071].)

unittest.mock

The sentinel attributes now preserve their identity when they are copied or pickled. (Contributed by Serhiy Storchaka in bpo-20804 [https://bugs.python.org/issue?@action=redirect&bpo=20804].)

The new seal() function allows sealing 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 [https://bugs.python.org/issue?@action=redirect&bpo=30541].)

urllib.parse

urllib.parse.quote() has been updated from RFC 2396 [https://datatracker.ietf.org/doc/html/rfc2396.html] to RFC 3986 [https://datatracker.ietf.org/doc/html/rfc3986.html], adding ~ to the set of characters that are never quoted by default. (Contributed by Christian Theune and Ratnadeep Debnath in bpo-16285 [https://bugs.python.org/issue?@action=redirect&bpo=16285].)

uu

The uu.encode() function now accepts an optional backtick keyword argument. When it's true, zeros are represented by '`' instead of spaces. (Contributed by Xiang Zhang in bpo-30103 [https://bugs.python.org/issue?@action=redirect&bpo=30103].)

uuid

The new 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 [https://bugs.python.org/issue?@action=redirect&bpo=22807].)

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 uuid.uuid1(). If only locally administered MAC addresses are available, the first such one found is returned. (Contributed by Barry Warsaw in bpo-32107 [https://bugs.python.org/issue?@action=redirect&bpo=32107].)

warnings

The initialization of the default warnings filters has changed as follows:

warnings enabled via command line options (including those for -b and the new CPython-specific -X dev option) are always passed to the warnings machinery via the sys.warnoptions attribute.

warnings filters enabled via the command line or the environment now have the following order of precedence:

the BytesWarning filter for -b (or -bb)

any filters specified with the -W option

any filters specified with the PYTHONWARNINGS environment variable

any other CPython specific filters (e.g. the default filter added for the new -X dev mode)

any implicit filters defined directly by the warnings machinery

in CPython debug builds, all warnings are now displayed by default (the implicit filter list is empty)

(Contributed by Nick Coghlan and Victor Stinner in bpo-20361 [https://bugs.python.org/issue?@action=redirect&bpo=20361], bpo-32043 [https://bugs.python.org/issue?@action=redirect&bpo=32043], and bpo-32230 [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 PEP 565: Show DeprecationWarning in __main__ for details. (Contributed by Nick Coghlan in bpo-31975 [https://bugs.python.org/issue?@action=redirect&bpo=31975].)

xml

As mitigation against DTD and external entity retrieval, the xml.dom.minidom and xml.sax modules no longer process external entities by default. (Contributed by Christian Heimes in gh-61441 [https://github.com/python/cpython/issues/61441].)

xml.etree

ElementPath predicates in the find() methods can now compare text of the current node with [. = "text"], not only text in children. Predicates also allow adding spaces for better readability. (Contributed by Stefan Behnel in bpo-31648 [https://bugs.python.org/issue?@action=redirect&bpo=31648].)

xmlrpc.server

SimpleXMLRPCDispatcher.register_function can now be used as a decorator. (Contributed by Xiang Zhang in bpo-7769 [https://bugs.python.org/issue?@action=redirect&bpo=7769].)

zipapp

Function 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 [https://bugs.python.org/issue?@action=redirect&bpo=31072].)

Function create_archive() now accepts an optional compressed argument to generate a compressed archive. A command line option --compress has also been added to support compression. (Contributed by Zhiming Wang in bpo-31638 [https://bugs.python.org/issue?@action=redirect&bpo=31638].)

zipfile

ZipFile now accepts the new compresslevel parameter to control the compression level. (Contributed by Bo Bayles in bpo-21417 [https://bugs.python.org/issue?@action=redirect&bpo=21417].)

Subdirectories in archives created by ZipFile are now stored in alphabetical order. (Contributed by Bernhard M. Wiedemann in bpo-30693 [https://bugs.python.org/issue?@action=redirect&bpo=30693].)

C API の変更

A new API for thread-local storage has been implemented. See PEP 539: スレッドローカルストレージのための新しい C API for an overview and スレッド固有ストレージ (Thread Specific Storage, TSS) API for a complete reference. (Contributed by Masayuki Yamamoto in bpo-25658 [https://bugs.python.org/issue?@action=redirect&bpo=25658].)

The new context variables functionality exposes a number of new C APIs.

The new PyImport_GetModule() function returns the previously imported module with the given name. (Contributed by Eric Snow in bpo-28411 [https://bugs.python.org/issue?@action=redirect&bpo=28411].)

The new Py_RETURN_RICHCOMPARE macro eases writing rich comparison functions. (Contributed by Petr Victorin in bpo-23699 [https://bugs.python.org/issue?@action=redirect&bpo=23699].)

The new Py_UNREACHABLE macro can be used to mark unreachable code paths. (Contributed by Barry Warsaw in bpo-31338 [https://bugs.python.org/issue?@action=redirect&bpo=31338].)

The tracemalloc now exposes a C API through the new PyTraceMalloc_Track() and PyTraceMalloc_Untrack() functions. (Contributed by Victor Stinner in bpo-30054 [https://bugs.python.org/issue?@action=redirect&bpo=30054].)

The new import__find__load__start() and import__find__load__done() static markers can be used to trace module imports. (Contributed by Christian Heimes in bpo-31574 [https://bugs.python.org/issue?@action=redirect&bpo=31574].)

The fields name and doc of structures PyMemberDef, PyGetSetDef, PyStructSequence_Field, PyStructSequence_Desc, and wrapperbase are now of type const char * rather of char *. (Contributed by Serhiy Storchaka in bpo-28761 [https://bugs.python.org/issue?@action=redirect&bpo=28761].)

The result of PyUnicode_AsUTF8AndSize() and PyUnicode_AsUTF8() is now of type const char * rather of char *. (Contributed by Serhiy Storchaka in bpo-28769 [https://bugs.python.org/issue?@action=redirect&bpo=28769].)

The result of PyMapping_Keys(), PyMapping_Values() and PyMapping_Items() is now always a list, rather than a list or a tuple. (Contributed by Oren Milman in bpo-28280 [https://bugs.python.org/issue?@action=redirect&bpo=28280].)

Added functions PySlice_Unpack() and PySlice_AdjustIndices(). (Contributed by Serhiy Storchaka in bpo-27867 [https://bugs.python.org/issue?@action=redirect&bpo=27867].)

PyOS_AfterFork() is deprecated in favour of the new functions PyOS_BeforeFork(), PyOS_AfterFork_Parent() and PyOS_AfterFork_Child(). (Contributed by Antoine Pitrou in bpo-16500 [https://bugs.python.org/issue?@action=redirect&bpo=16500].)

The 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 [https://bugs.python.org/issue?@action=redirect&bpo=22898] and bpo-30697 [https://bugs.python.org/issue?@action=redirect&bpo=30697].

Added C API support for timezones with timezone constructors PyTimeZone_FromOffset() and PyTimeZone_FromOffsetAndName(), and access to the UTC singleton with PyDateTime_TimeZone_UTC. Contributed by Paul Ganssle in bpo-10381 [https://bugs.python.org/issue?@action=redirect&bpo=10381].

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. (Contributed by Serhiy Storchaka in bpo-6532 [https://bugs.python.org/issue?@action=redirect&bpo=6532].)

PyUnicode_AsWideCharString() now raises a ValueError if the second argument is NULL and the wchar_t* string contains null characters. (Contributed by Serhiy Storchaka in bpo-30708 [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 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 Python 3.7 への移植 section in this document and the Python 初期化以前 section in the C API documentation for more details.

The new PyInterpreterState_GetID() returns the unique ID for a given interpreter. (Contributed by Eric Snow in bpo-29102 [https://bugs.python.org/issue?@action=redirect&bpo=29102].)

Py_DecodeLocale(), Py_EncodeLocale() now use the UTF-8 encoding when the UTF-8 mode is enabled. (Contributed by Victor Stinner in bpo-29240 [https://bugs.python.org/issue?@action=redirect&bpo=29240].)

PyUnicode_DecodeLocaleAndSize() and PyUnicode_EncodeLocale() now use the current locale encoding for surrogateescape error handler. (Contributed by Victor Stinner in bpo-29240 [https://bugs.python.org/issue?@action=redirect&bpo=29240].)

The start and end parameters of PyUnicode_FindChar() are now adjusted to behave like string slices. (Contributed by Xiang Zhang in bpo-28822 [https://bugs.python.org/issue?@action=redirect&bpo=28822].)

Build Changes

Support for building --without-threads has been removed. The threading module is now always available. (Contributed by Antoine Pitrou in bpo-31370 [https://bugs.python.org/issue?@action=redirect&bpo=31370].).

A full copy of libffi is no longer bundled for use when building the _ctypes module on non-OSX UNIX platforms. An installed copy of libffi is now required when building _ctypes on such platforms. (Contributed by Zachary Ware in bpo-27979 [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 py -3.6), NuGet is used to download a copy of 32-bit Python for this purpose. (Contributed by Zachary Ware in bpo-30450 [https://bugs.python.org/issue?@action=redirect&bpo=30450].)

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

最適化

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 METH_FASTCALL convention. (Contributed by Victor Stinner in bpo-29300 [https://bugs.python.org/issue?@action=redirect&bpo=29300], bpo-29507 [https://bugs.python.org/issue?@action=redirect&bpo=29507], bpo-29452 [https://bugs.python.org/issue?@action=redirect&bpo=29452], and bpo-29286 [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 [https://bugs.python.org/issue?@action=redirect&bpo=29585], and Ivan Levkivskyi in bpo-31333 [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 [https://bugs.python.org/issue?@action=redirect&bpo=26110].)

The asyncio module received a number of notable optimizations for commonly used functions:

The 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 [https://bugs.python.org/issue?@action=redirect&bpo=32296].)

asyncio.Future callback management has been optimized. (Contributed by Yury Selivanov in bpo-32348 [https://bugs.python.org/issue?@action=redirect&bpo=32348].)

asyncio.gather() is now up to 15% faster. (Contributed by Yury Selivanov in bpo-32355 [https://bugs.python.org/issue?@action=redirect&bpo=32355].)

asyncio.sleep() is now up to 2 times faster when the delay argument is zero or negative. (Contributed by Andrew Svetlov in bpo-32351 [https://bugs.python.org/issue?@action=redirect&bpo=32351].)

The performance overhead of asyncio debug mode has been reduced. (Contributed by Antoine Pitrou in bpo-31970 [https://bugs.python.org/issue?@action=redirect&bpo=31970].)

As a result of PEP 560 work, the import time of typing has been reduced by a factor of 7, and many typing operations are now faster. (Contributed by Ivan Levkivskyi in bpo-32226 [https://bugs.python.org/issue?@action=redirect&bpo=32226].)

sorted() and list.sort() have been optimized for common cases to be up to 40-75% faster. (Contributed by Elliot Gorokhovsky in bpo-28685 [https://bugs.python.org/issue?@action=redirect&bpo=28685].)

dict.copy() is now up to 5.5 times faster. (Contributed by Yury Selivanov in bpo-31179 [https://bugs.python.org/issue?@action=redirect&bpo=31179].)

hasattr() and getattr() are now about 4 times faster when name is not found and obj does not override object.__getattr__() or object.__getattribute__(). (Contributed by INADA Naoki in bpo-32544 [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 [https://bugs.python.org/issue?@action=redirect&bpo=24821].)

The 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 [https://bugs.python.org/issue?@action=redirect&bpo=28638].)

date.fromordinal() and date.fromtimestamp() are now up to 30% faster in the common case. (Contributed by Paul Ganssle in bpo-32403 [https://bugs.python.org/issue?@action=redirect&bpo=32403].)

The os.fwalk() function is now up to 2 times faster thanks to the use of os.scandir(). (Contributed by Serhiy Storchaka in bpo-25996 [https://bugs.python.org/issue?@action=redirect&bpo=25996].)

The speed of the shutil.rmtree() function has been improved by 20--40% thanks to the use of the os.scandir() function. (Contributed by Serhiy Storchaka in bpo-28564 [https://bugs.python.org/issue?@action=redirect&bpo=28564].)

Optimized case-insensitive matching and searching of regular expressions. Searching some patterns can now be up to 20 times faster. (Contributed by Serhiy Storchaka in bpo-30285 [https://bugs.python.org/issue?@action=redirect&bpo=30285].)

re.compile() now converts flags parameter to int object if it is 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 [https://bugs.python.org/issue?@action=redirect&bpo=31671].)

The modify() methods of classes selectors.EpollSelector, selectors.PollSelector and selectors.DevpollSelector may be around 10% faster under heavy loads. (Contributed by Giampaolo Rodola' in bpo-30014 [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 [https://bugs.python.org/issue?@action=redirect&bpo=29469] and bpo-11549 [https://bugs.python.org/issue?@action=redirect&bpo=11549].)

Most functions and methods in abc have been rewritten in C. This makes creation of abstract base classes, and calling isinstance() and 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 [https://bugs.python.org/issue?@action=redirect&bpo=31333])

Significant speed improvements to alternate constructors for datetime.date and datetime.datetime by using fast-path constructors when not constructing subclasses. (Contributed by Paul Ganssle in bpo-32403 [https://bugs.python.org/issue?@action=redirect&bpo=32403])

The speed of comparison of 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 [https://bugs.python.org/issue?@action=redirect&bpo=24700].)

The math.erf() and math.erfc() functions now use the (faster) C library implementation on most platforms. (Contributed by Serhiy Storchaka in bpo-26121 [https://bugs.python.org/issue?@action=redirect&bpo=26121].)

その他の CPython の実装の変更

Trace hooks may now opt out of receiving the line and opt into receiving the opcode events from the interpreter by setting the corresponding new f_trace_lines and f_trace_opcodes attributes on the frame being traced. (Contributed by Nick Coghlan in bpo-31344 [https://bugs.python.org/issue?@action=redirect&bpo=31344].)

Fixed some consistency problems with namespace package module attributes. Namespace module objects now have an __file__ that is set to None (previously unset), and their __spec__.origin is also set to None (previously the string "namespace"). See bpo-32305 [https://bugs.python.org/issue?@action=redirect&bpo=32305]. Also, the namespace module object's __spec__.loader is set to the same value as __loader__ (previously, the former was set to None). See bpo-32303 [https://bugs.python.org/issue?@action=redirect&bpo=32303].

The locals() dictionary now displays in the lexical order that variables were defined. Previously, the order was undefined. (Contributed by Raymond Hettinger in bpo-32690 [https://bugs.python.org/issue?@action=redirect&bpo=32690].)

The distutils 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 [https://bugs.python.org/issue?@action=redirect&bpo=32304].)

非推奨の Python の挙動

Yield expressions (both yield and yield from clauses) are now deprecated in comprehensions and generator expressions (aside from the iterable expression in the leftmost for clause). This ensures that comprehensions always immediately return a container of the appropriate type (rather than potentially returning a 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 DeprecationWarning when compiled, in Python 3.8 this will be a SyntaxError. (Contributed by Serhiy Storchaka in bpo-10544 [https://bugs.python.org/issue?@action=redirect&bpo=10544].)

Returning a subclass of complex from object.__complex__() is deprecated and will be an error in future Python versions. This makes __complex__() consistent with object.__int__() and object.__float__(). (Contributed by Serhiy Storchaka in bpo-28894 [https://bugs.python.org/issue?@action=redirect&bpo=28894].)

非推奨の Python モジュール、関数、メソッド

aifc

aifc.openfp() has been deprecated and will be removed in Python 3.9. Use aifc.open() instead. (Contributed by Brian Curtin in bpo-31985 [https://bugs.python.org/issue?@action=redirect&bpo=31985].)

asyncio

Support for directly await-ing instances of 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 [https://bugs.python.org/issue?@action=redirect&bpo=32253].)

The asyncio.Task.current_task() and asyncio.Task.all_tasks() methods have been deprecated. (Contributed by Andrew Svetlov in bpo-32250 [https://bugs.python.org/issue?@action=redirect&bpo=32250].)

collections

In Python 3.8, the abstract base classes in collections.abc will no longer be exposed in the regular 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 [https://bugs.python.org/issue?@action=redirect&bpo=25988].)

dbm

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 'r' and 'w' modes (this will be an error in future Python releases). (Contributed by Serhiy Storchaka in bpo-28847 [https://bugs.python.org/issue?@action=redirect&bpo=28847].)

enum

In Python 3.8, attempting to check for non-Enum objects in Enum classes will raise a TypeError (e.g. 1 in Color); similarly, attempting to check for non-Flag objects in a Flag member will raise TypeError (e.g. 1 in Perm.RW); currently, both operations return False instead. (Contributed by Ethan Furman in bpo-33217 [https://bugs.python.org/issue?@action=redirect&bpo=33217].)

gettext

Using non-integer value for selecting a plural form in gettext is now deprecated. It never correctly worked. (Contributed by Serhiy Storchaka in bpo-28692 [https://bugs.python.org/issue?@action=redirect&bpo=28692].)

importlib

Methods MetaPathFinder.find_module() (replaced by MetaPathFinder.find_spec()) and PathEntryFinder.find_loader() (replaced by PathEntryFinder.find_spec()) both deprecated in Python 3.4 now emit DeprecationWarning. (Contributed by Matthias Bussonnier in bpo-29576 [https://bugs.python.org/issue?@action=redirect&bpo=29576].)

The importlib.abc.ResourceLoader ABC has been deprecated in favour of importlib.abc.ResourceReader.

locale

locale.format() has been deprecated, use locale.format_string() instead. (Contributed by Garvit in bpo-10379 [https://bugs.python.org/issue?@action=redirect&bpo=10379].)

macpath

The macpath is now deprecated and will be removed in Python 3.8. (Contributed by Chi Hsuan Yen in bpo-9850 [https://bugs.python.org/issue?@action=redirect&bpo=9850].)

threading

dummy_threading and _dummy_thread have been deprecated. It is no longer possible to build Python with threading disabled. Use threading instead. (Contributed by Antoine Pitrou in bpo-31370 [https://bugs.python.org/issue?@action=redirect&bpo=31370].)

socket

The silent argument value truncation in socket.htons() and 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 [https://bugs.python.org/issue?@action=redirect&bpo=28332].)

ssl

ssl.wrap_socket() is deprecated. Use ssl.SSLContext.wrap_socket() instead. (Contributed by Christian Heimes in bpo-28124 [https://bugs.python.org/issue?@action=redirect&bpo=28124].)

sunau

sunau.openfp() has been deprecated and will be removed in Python 3.9. Use sunau.open() instead. (Contributed by Brian Curtin in bpo-31985 [https://bugs.python.org/issue?@action=redirect&bpo=31985].)

sys

Deprecated sys.set_coroutine_wrapper() and sys.get_coroutine_wrapper().

The undocumented sys.callstats() function has been deprecated and will be removed in a future Python version. (Contributed by Victor Stinner in bpo-28799 [https://bugs.python.org/issue?@action=redirect&bpo=28799].)

wave

wave.openfp() has been deprecated and will be removed in Python 3.9. Use wave.open() instead. (Contributed by Brian Curtin in bpo-31985 [https://bugs.python.org/issue?@action=redirect&bpo=31985].)

C API の非推奨の関数ならびに型

Function PySlice_GetIndicesEx() is deprecated and replaced with a macro if Py_LIMITED_API is not set or set to a value in the range between 0x03050400 and 0x03060000 (not inclusive), or is 0x03060100 or higher. (Contributed by Serhiy Storchaka in bpo-27867 [https://bugs.python.org/issue?@action=redirect&bpo=27867].)

PyOS_AfterFork() has been deprecated. Use PyOS_BeforeFork(), PyOS_AfterFork_Parent() or PyOS_AfterFork_Child() instead. (Contributed by Antoine Pitrou in bpo-16500 [https://bugs.python.org/issue?@action=redirect&bpo=16500].)

サポート対象プラットフォームからの除外

FreeBSD 9 とそれ以前のバージョンは公式にはサポートされなくなりました。

For full Unicode support, including within extension modules, *nix platforms are now expected to provide at least one of C.UTF-8 (full locale), C.utf8 (full locale) or UTF-8 (LC_CTYPE-only locale) as an alternative to the legacy ASCII-based C locale.

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 [https://github.com/python/cpython/blob/v3.7.13/.travis.yml] provides an example of using the SSL compatibility testing infrastructure [https://github.com/python/cpython/tree/3.12/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.

API と機能の削除

The following features and APIs have been removed from Python 3.7:

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

Unknown escapes consisting of '\' and an ASCII letter in replacement templates for re.sub() were deprecated in Python 3.5, and will now cause an error.

Removed support of the exclude argument in tarfile.TarFile.add(). It was deprecated in Python 2.7 and 3.2. Use the filter argument instead.

The ntpath.splitunc() function was deprecated in Python 3.1, and has now been removed. Use splitdrive() instead.

collections.namedtuple() no longer supports the verbose parameter or _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 [https://bugs.python.org/issue?@action=redirect&bpo=28638].)

Functions bool(), float(), list() and tuple() no longer take keyword arguments. The first argument of int() can now be passed only as positional argument.

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.

The asyncio.windows_utils.socketpair() function has been removed. Use the socket.socketpair() function instead, it is available on all platforms since Python 3.5. asyncio.windows_utils.socketpair was just an alias to socket.socketpair on Python 3.5 and newer.

asyncio no longer exports the selectors and _overlapped modules as asyncio.selectors and asyncio._overlapped. Replace from asyncio import selectors with import selectors.

Direct instantiation of ssl.SSLSocket and ssl.SSLObject objects is now prohibited. The constructors were never documented, tested, or designed as public constructors. Users were supposed to use ssl.wrap_socket() or ssl.SSLContext. (Contributed by Christian Heimes in bpo-32951 [https://bugs.python.org/issue?@action=redirect&bpo=32951].)

The unused distutils install_misc command has been removed. (Contributed by Eric N. Vander Weele in bpo-29218 [https://bugs.python.org/issue?@action=redirect&bpo=29218].)

Module Removals

The 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 [https://bugs.python.org/issue?@action=redirect&bpo=29137].)

Windows-only Changes

The python launcher, (py.exe), can accept 32 & 64 bit specifiers without having to specify a minor version as well. So py -3-32 and py -3-64 become valid as well as 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 [https://bugs.python.org/issue?@action=redirect&bpo=30291].)

The launcher can be run as py -0 to produce a list of the installed pythons, with default marked with an asterisk. Running 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 [https://bugs.python.org/issue?@action=redirect&bpo=30362].)

Python 3.7 への移植

このセクションでは前述の変更とバグフィックスにより必要となるかもしれないコードの変更を列挙します:

Python の挙動の変更

async and await names are now reserved keywords. Code using these names as identifiers will now raise a SyntaxError. (Contributed by Jelle Zijlstra in bpo-30406 [https://bugs.python.org/issue?@action=redirect&bpo=30406].)

PEP 479 [https://peps.python.org/pep-0479/] is enabled for all code in Python 3.7, meaning that StopIteration exceptions raised directly or indirectly in coroutines and generators are transformed into RuntimeError exceptions. (Contributed by Yury Selivanov in bpo-32670 [https://bugs.python.org/issue?@action=redirect&bpo=32670].)

object.__aiter__() methods can no longer be declared as asynchronous. (Contributed by Yury Selivanov in bpo-31709 [https://bugs.python.org/issue?@action=redirect&bpo=31709].)

以前のバージョンの Python で、誤って以下の構文を許容してしまっていました:

f(1 for x in [1],)

class C(1 for x in [1]):
    pass

Python 3.7 now correctly raises a 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 [https://bugs.python.org/issue?@action=redirect&bpo=32012] and bpo-32023 [https://bugs.python.org/issue?@action=redirect&bpo=32023].)

When using the -m switch, the initial working directory is now added to 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 os.getcwd() or os.path.dirname(__main__.__file__), depending on why the code was checking for the empty string in the first place).

Python API の変更

socketserver.ThreadingMixIn.server_close() now waits until all non-daemon threads complete. Set the new socketserver.ThreadingMixIn.block_on_close class attribute to False to get the pre-3.7 behaviour. (Contributed by Victor Stinner in bpo-31233 [https://bugs.python.org/issue?@action=redirect&bpo=31233] and bpo-33540 [https://bugs.python.org/issue?@action=redirect&bpo=33540].)

socketserver.ForkingMixIn.server_close() now waits until all child processes complete. Set the new socketserver.ForkingMixIn.block_on_close class attribute to False to get the pre-3.7 behaviour. (Contributed by Victor Stinner in bpo-31151 [https://bugs.python.org/issue?@action=redirect&bpo=31151] and bpo-33540 [https://bugs.python.org/issue?@action=redirect&bpo=33540].)

The locale.localeconv() function now temporarily sets the LC_CTYPE locale to the value of LC_NUMERIC in some cases. (Contributed by Victor Stinner in bpo-31900 [https://bugs.python.org/issue?@action=redirect&bpo=31900].)

pkgutil.walk_packages() now raises a ValueError if path is a string. Previously an empty list was returned. (Contributed by Sanyam Khurana in bpo-24744 [https://bugs.python.org/issue?@action=redirect&bpo=24744].)

A format string argument for string.Formatter.format() is now positional-only. Passing it as a keyword argument was deprecated in Python 3.5. (Contributed by Serhiy Storchaka in bpo-29193 [https://bugs.python.org/issue?@action=redirect&bpo=29193].)

Attributes key, value and coded_value of class http.cookies.Morsel are now read-only. Assigning to them was deprecated in Python 3.5. Use the set() method for setting them. (Contributed by Serhiy Storchaka in bpo-29192 [https://bugs.python.org/issue?@action=redirect&bpo=29192].)

The mode argument of 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 makedirs(). (Contributed by Serhiy Storchaka in bpo-19930 [https://bugs.python.org/issue?@action=redirect&bpo=19930].)

The struct.Struct.format type is now str instead of bytes. (Contributed by Victor Stinner in bpo-21071 [https://bugs.python.org/issue?@action=redirect&bpo=21071].)

parse_multipart() now accepts the encoding and errors arguments and returns the same results as 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 [https://bugs.python.org/issue?@action=redirect&bpo=29979].)

Due to internal changes in socket, calling socket.fromshare() on a socket created by socket.share in older Python versions is not supported.

repr for BaseException has changed to not include the trailing comma. Most exceptions are affected by this change. (Contributed by Serhiy Storchaka in bpo-30399 [https://bugs.python.org/issue?@action=redirect&bpo=30399].)

repr for datetime.timedelta has changed to include the keyword arguments in the output. (Contributed by Utkarsh Upadhyay in bpo-30302 [https://bugs.python.org/issue?@action=redirect&bpo=30302].)

Because shutil.rmtree() is now implemented using the os.scandir() function, the user specified handler onerror is now called with the first argument os.scandir instead of os.listdir when listing the directory is failed.

Support for nested sets and set operations in regular expressions as in Unicode Technical Standard #18 [https://unicode.org/reports/tr18/] might be added in the future. This would change the syntax. To facilitate this future change a FutureWarning will be raised in ambiguous cases for the time being. That include sets starting with a literal '[' or containing literal character sequences '--', '&&', '~~', and '||'. To avoid a warning, escape them with a backslash. (Contributed by Serhiy Storchaka in bpo-30349 [https://bugs.python.org/issue?@action=redirect&bpo=30349].)

The result of splitting a string on a regular expression that could match an empty string has been changed. For example splitting on 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 r'\s+'. A 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 'a\n\n', the pattern r'(?m)^\s*?$' will not only match empty strings at positions 2 and 3, but also the string '\n' at positions 2--3. To match only blank lines, the pattern should be rewritten as r'(?m)^[^\S\n]*$'.

re.sub() now replaces empty matches adjacent to a previous non-empty match. For example re.sub('x*', '-', 'abxd') returns now '-a-b--d-' instead of '-a-b-d-' (the first minus between 'b' and 'd' replaces 'x', and the second minus replaces an empty string between 'x' and 'd').

(Contributed by Serhiy Storchaka in bpo-25054 [https://bugs.python.org/issue?@action=redirect&bpo=25054] and bpo-32308 [https://bugs.python.org/issue?@action=redirect&bpo=32308].)

Change re.escape() to only escape regex special characters instead of escaping all characters other than ASCII letters, numbers, and '_'. (Contributed by Serhiy Storchaka in bpo-29995 [https://bugs.python.org/issue?@action=redirect&bpo=29995].)

tracemalloc.Traceback frames are now sorted from oldest to most recent to be more consistent with traceback. (Contributed by Jesse Bakker in bpo-32121 [https://bugs.python.org/issue?@action=redirect&bpo=32121].)

On OSes that support socket.SOCK_NONBLOCK or socket.SOCK_CLOEXEC bit flags, the socket.type no longer has them applied. Therefore, checks like if sock.type == socket.SOCK_STREAM work as expected on all platforms. (Contributed by Yury Selivanov in bpo-32331 [https://bugs.python.org/issue?@action=redirect&bpo=32331].)

On Windows the default for the close_fds argument of subprocess.Popen was changed from False to True when redirecting the standard handles. If you previously depended on handles being inherited when using subprocess.Popen with standard io redirection, you will have to pass close_fds=False to preserve the previous behaviour, or use STARTUPINFO.lpAttributeList.

importlib.machinery.PathFinder.invalidate_caches() -- which implicitly affects importlib.invalidate_caches() -- now deletes entries in sys.path_importer_cache which are set to None. (Contributed by Brett Cannon in bpo-33169 [https://bugs.python.org/issue?@action=redirect&bpo=33169].)

In asyncio, loop.sock_recv(), loop.sock_sendall(), loop.sock_accept(), loop.getaddrinfo(), loop.getnameinfo() have been changed to be proper coroutine methods to match their documentation. Previously, these methods returned asyncio.Future instances. (Contributed by Yury Selivanov in bpo-32327 [https://bugs.python.org/issue?@action=redirect&bpo=32327].)

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 [https://bugs.python.org/issue?@action=redirect&bpo=32662].)

Struct.format is now a str instance instead of a bytes instance. (Contributed by Victor Stinner in bpo-21071 [https://bugs.python.org/issue?@action=redirect&bpo=21071].)

argparse subparsers can now be made mandatory by passing required=True to ArgumentParser.add_subparsers(). (Contributed by Anthony Sottile in bpo-26510 [https://bugs.python.org/issue?@action=redirect&bpo=26510].)

ast.literal_eval() is now stricter. Addition and subtraction of arbitrary numbers are no longer allowed. (Contributed by Serhiy Storchaka in bpo-31778 [https://bugs.python.org/issue?@action=redirect&bpo=31778].)

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 Calendar.itermonthdays3 and Calendar.itermonthdays4 can be used. The new methods return tuples and are not restricted by the range supported by datetime.date. (Contributed by Alexander Belopolsky in bpo-28292 [https://bugs.python.org/issue?@action=redirect&bpo=28292].)

collections.ChainMap now preserves the order of the underlying mappings. (Contributed by Raymond Hettinger in bpo-32792 [https://bugs.python.org/issue?@action=redirect&bpo=32792].)

The submit() method of concurrent.futures.ThreadPoolExecutor and concurrent.futures.ProcessPoolExecutor now raises a RuntimeError if called during interpreter shutdown. (Contributed by Mark Nemec in bpo-33097 [https://bugs.python.org/issue?@action=redirect&bpo=33097].)

The configparser.ConfigParser constructor now uses 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 [https://bugs.python.org/issue?@action=redirect&bpo=23835].)

Several undocumented internal imports were removed. One example is that os.errno is no longer available; use import errno directly instead. Note that such undocumented internal imports may be removed any time without notice, even in micro version releases.

C API の変更

The function PySlice_GetIndicesEx() is considered unsafe for resizable sequences. If the slice indices are not instances of int, but objects that implement the __index__() method, the sequence can be resized after passing its length to PySlice_GetIndicesEx(). This can lead to returning indices out of the length of the sequence. For avoiding possible problems use new functions PySlice_Unpack() and PySlice_AdjustIndices(). (Contributed by Serhiy Storchaka in bpo-27867 [https://bugs.python.org/issue?@action=redirect&bpo=27867].)

CPython バイトコードの変更

There are two new opcodes: LOAD_METHOD and CALL_METHOD. (Contributed by Yury Selivanov and INADA Naoki in bpo-26110 [https://bugs.python.org/issue?@action=redirect&bpo=26110].)

The STORE_ANNOTATION opcode has been removed. (Contributed by Mark Shannon in bpo-32550 [https://bugs.python.org/issue?@action=redirect&bpo=32550].)

Windows-only Changes

The file used to override sys.path is now called <python-executable>._pth instead of 'sys.path'. See モジュールの検索 for more information. (Contributed by Steve Dower in bpo-28137 [https://bugs.python.org/issue?@action=redirect&bpo=28137].)

その他の CPython の実装の変更

In preparation for potential future changes to the public CPython runtime initialization API (see PEP 432 [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 [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:

PySys_AddWarnOptionUnicode() is not currently usable by embedding applications due to the requirement to create a Unicode object prior to calling Py_Initialize. Use PySys_AddWarnOption() instead.

warnings filters added by an embedding application with PySys_AddWarnOption() should now more consistently take precedence over the default filters set by the interpreter

Due to changes in the way the default warnings filters are configured, setting Py_BytesWarningFlag to a value greater than one is no longer sufficient to both emit 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 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 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 [https://bugs.python.org/issue?@action=redirect&bpo=25612].)

Python 3.7.1 での重要な変更点

Starting in 3.7.1, Py_Initialize() now consistently reads and respects all of the same environment settings as 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 [https://bugs.python.org/issue?@action=redirect&bpo=34247]). If this behavior is unwanted, set Py_IgnoreEnvironmentFlag to 1 before calling Py_Initialize().

In 3.7.1 the C API for Context Variables was updated to use PyObject pointers. See also bpo-34762 [https://bugs.python.org/issue?@action=redirect&bpo=34762].

In 3.7.1 the tokenize module now implicitly emits a 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 [https://bugs.python.org/issue?@action=redirect&bpo=33899].)

Python 3.7.2 での重要な変更点

In 3.7.2, venv on Windows no longer copies the original binaries, but creates redirector scripts named python.exe and 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.

Python 3.7.6 での重要な変更点

セキュリティ上の重大な懸念により、asyncio.loop.create_datagram_endpoint() での reuse_address 引数は無効になりました。これはソケットオプション SO_REUSEADDR` のUDP における挙動が原因です。詳しくは、loop.create_datagram_endpoint() のドキュメントを参照してください。(Kyle Stanley, Antoine Pitrou, Yury Selivanov による貢献 bpo-37228 [https://bugs.python.org/issue?@action=redirect&bpo=37228])

Python 3.7.10 での重要な変更点

Earlier Python versions allowed using both ; and & as query parameter separators in urllib.parse.parse_qs() and 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 & as the default. This change also affects cgi.parse() and 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 [https://bugs.python.org/issue?@action=redirect&bpo=42967].)

Notable changes in Python 3.7.11

A security fix alters the 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 trust_server_pasv_ipv4_address attribute on your FTP instance to True. (See gh-87451 [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 \n, \r and tab \t characters are stripped from the URL by the parser urllib.parse() preventing such attacks. The removal characters are controlled by a new module level variable urllib.parse._UNSAFE_URL_BYTES_TO_REMOVE. (See gh-88048 [https://github.com/python/cpython/issues/88048])

Notable security feature in 3.7.14

Converting between int and str in bases other than 2 (binary), 4, 8 (octal), 16 (hexadecimal), or 32 such as base 10 (decimal) now raises a 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 CVE-2020-10735 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-10735]. This limit can be configured or disabled by environment variable, command line flag, or sys APIs. See the integer string conversion length limitation documentation. The default limit is 4300 digits in string form.

What's New In Python 3.6

エディタ:

Elvis Pranskevichus <elvis@magic.io>, Yury Selivanov <yury@magic.io>

この記事では 3.5 と比較した Python 3.6 の新機能を解説します。 Python 3.6 は2016年12月23日にリリースされました。全詳細については 変更履歴 [https://docs.python.org/3.6/whatsnew/changelog.html] をご覧ください。

参考

PEP 494 [https://peps.python.org/pep-0494/] - Python 3.6 リリーススケジュール

概要 -- リリースハイライト

新たな文法機能:

PEP 498、フォーマット済み文字列リテラル。

PEP 515、数値リテラル内のアンダースコア。

PEP 526、変数アノテーションの文法。

PEP 525、非同期ジェネレータ。

PEP 530: 非同期内包表記

新たなライブラリモジュール:

secrets: PEP 506 -- 標準ライブラリーに Secrets モジュールを追加.

CPython の実装の改善:

dict 型は、 Raymond Hettinger [https://mail.python.org/pipermail/python-dev/2012-December/123028.html] の提案に基づき、 PyPy dict implementation [https://morepypy.blogspot.com/2015/01/faster-more-memory-efficient-and-more.html] と同様の よりコンパクトな表現 を使うように再実装されました。その結果、 Python 3.5 と比較して辞書が使うメモリ 20% から 25% 減少しました。

新しいプロトコル により、クラス生成のカスタマイズがより簡単になりました。

クラス属性の定義の順番が 保持されるようになりました。

**kwargs の要素の順序が、キーワード引数が関数に渡されたときの 順序に一致した ものになりました。

DTrace と SystemTap の プローブのサポート が追加されました。

新しい PYTHONMALLOC  環境変数が、インタープリタのメモリ確保とメモリアクセスエラーのデバッグに使えるようになりました。

標準ライブラリーの顕著な改善

The asyncio module has received new features, significant usability and performance improvements, and a fair amount of bug fixes. Starting with Python 3.6 the asyncio module is no longer provisional and its API is considered stable.

A new file system path protocol has been implemented to support path-like objects. All standard library functions operating on paths have been updated to work with the new protocol.

datetime モジュールで 地域時間の曖昧さ回避 がサポートされました。

typing モジュールに数多くの 改善 がなされました。

tracemalloc モジュールが大幅に書き直され、改善されたメモリ割り当てエラーの診断プログラムの提供だけでなく、 ResourceWarning の出力メッセージも改善されています。より詳しいことは PYTHONMALLOC 節 を参照してください。

セキュリティの改善:

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

On Linux, os.urandom() now blocks until the system urandom entropy pool is initialized to increase the security. See the PEP 524 [https://peps.python.org/pep-0524/] for the rationale.

hashlib および ssl モジュールは OpenSSL 1.1.0 をサポートしました。

ssl モジュールのデフォルトの設定と機能群が改善されました。

hashlib モジュールで BLAKE2, SHA-3, SHAKE ハッシュアルゴリズムと scrypt() キー導出関数がサポートされるようになりました。

Windows の改善:

PEP 528 および PEP 529、 Windows のファイルシステムとコンソールのエンコーディングを UTF-8 に変更しました。

py.exe ランチャーを対話的に使うときに、 (コマンドライン引数や設定ファイルで) バージョンを指定しないと Python 3 よりも Python 2 を選択するということはなくなりました。シェバン行の扱いは以前のままで、 "python" とあった場合は Python 2 を指しています。

python.exe and pythonw.exe have been marked as long-path aware, which means that the 260 character path limit may no longer apply. See removing the MAX_PATH limitation for details.

A ._pth file can be added to force isolated mode and fully specify all search paths to avoid registry and environment lookup. See the documentation for more information.

A python36.zip file now works as a landmark to infer PYTHONHOME. See the documentation for more information.

新しい機能

PEP 498: フォーマット済み文字列リテラル

PEP 498 [https://peps.python.org/pep-0498/] は新たな種類の文字列リテラル、すなわち f-strings、 フォーマット済み文字列リテラル を導入しました。

フォーマット済み文字列リテラルはプレフィックスに 'f' をとり str.format() による書式文字列に似ています。これらには中括弧で囲まれた置換フィールドがあります。置換フィールドは実行時に評価される式で、 format() プロトコルによってフォーマットされます:

>>> name = "Fred"
>>> f"He said his name is {name}."
'He said his name is Fred.'
>>> width = 10
>>> precision = 4
>>> value = decimal.Decimal("12.34567")
>>> f"result: {value:{width}.{precision}}"  # nested fields
'result:      12.35'

参考

PEP 498 [https://peps.python.org/pep-0498/] -- Literal String Interpolation.

PEP written and implemented by Eric V. Smith.

Feature documentation.

PEP 526: 変数アノテーションの文法

PEP 484 [https://peps.python.org/pep-0484/] は関数の仮引数の型アノテーション、型ヒント、の標準を導入しました。この PEP は Python に、クラス変数およびインスタンス変数を含む変数の型アノテーションの構文を追加しました:

primes: List[int] = []

captain: str  # Note: no initial value!

class Starship:
    stats: Dict[str, int] = {}

関数アノテーションと同様に、Python インタープリタは変数アノテーションに特定の意味を付加せず、クラスやモジュールの __annotations__ 属性に保存するだけです。

静的型付け言語の変数定義とは対照的に、アノテーションシンタックスの目的は抽象構文木および __annotations__ 属性を通じて、サードパーティツールやライブラリーに型の構造化されたメタデータを指定する簡単な方法を提供することです。

参考

PEP 526 [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.

新構文を使用あるいは使用予定のツール: mypy [https://www.mypy-lang.org/], pytype [https://github.com/google/pytype], PyCharm などなど。

PEP 515: 数値リテラル内のアンダースコア

PEP 515 [https://peps.python.org/pep-0515/] により、可読性向上のために数値リテラル内でアンダースコアを使えるようになりました。例えば:

>>> 1_000_000_000_000_000
1000000000000000
>>> 0x_FF_FF_FF_FF
4294967295

単一のアンダースコアは数字の間と基数指定子の後で許されます。先頭、末尾、あるいは複数のアンダースコアを列内で使用することはできません。

The string formatting language also now has support for the '_' option to signal the use of an underscore for a thousands separator for floating point presentation types and for integer presentation type 'd'. For integer presentation types 'b', 'o', 'x', and 'X', underscores will be inserted every 4 digits:

>>> '{:_}'.format(1000000)
'1_000_000'
>>> '{:_x}'.format(0xFFFFFFFF)
'ffff_ffff'

参考

PEP 515 [https://peps.python.org/pep-0515/] -- 数値リテラル内のアンダースコア

PEP written by Georg Brandl and Serhiy Storchaka.

PEP 525: 非同期ジェネレータ

PEP 492 [https://peps.python.org/pep-0492/] で Python 3.5 はネイティブなコルーチンならびに async / await 構文をサポートしました。Python 3.5 実装における大きな制約は同一の関数実体内で await と yield を使えないことでした。Python 3.6 ではこの制約はなくなり、 非同期ジェネレータ を定義できるようになりました:

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)

新たな構文のおかげでより速く、より簡潔にコードを書くことができます。

参考

PEP 525 [https://peps.python.org/pep-0525/] -- 非同期ジェネレータ

PEP written and implemented by Yury Selivanov.

PEP 530: 非同期内包表記

PEP 530 [https://peps.python.org/pep-0530/] によりリスト、セット、辞書内包表記ならびにジェネレータ式内での async for の使用がサポートされました:

result = [i async for i in aiter() if i % 2]

加えて、 await 式が全ての内包表記でサポートされました:

result = [await fun() for fun in funcs if await condition()]

参考

PEP 530 [https://peps.python.org/pep-0530/] -- 非同期内包表記

PEP written and implemented by Yury Selivanov.

PEP 487: Simpler customization of class creation

It is now possible to customize subclass creation without using a metaclass. The new __init_subclass__ classmethod will be called on the base class whenever a new subclass is created:

class PluginBase:
    subclasses = []

    def __init_subclass__(cls, **kwargs):
        super().__init_subclass__(**kwargs)
        cls.subclasses.append(cls)

class Plugin1(PluginBase):
    pass

class Plugin2(PluginBase):
    pass

In order to allow zero-argument super() calls to work correctly from __init_subclass__() implementations, custom metaclasses must ensure that the new __classcell__ namespace entry is propagated to type.__new__ (as described in クラスオブジェクトの作成).

参考

PEP 487 [https://peps.python.org/pep-0487/] -- Simpler customization of class creation

PEP 著と実装 Martin Teichmann.

Feature documentation

PEP 487: 記述子プロトコルの改善

PEP 487 [https://peps.python.org/pep-0487/] extends the descriptor protocol to include the new optional __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:

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()

参考

PEP 487 [https://peps.python.org/pep-0487/] -- Simpler customization of class creation

PEP 著と実装 Martin Teichmann.

Feature documentation

PEP 519: ファイルシステムパスプロトコルの追加

File system paths have historically been represented as str or 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 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 pathlib from working with pre-existing code, including Python's standard library.

To fix this situation, a new interface represented by os.PathLike has been defined. By implementing the __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 str or bytes object. This means an object is considered path-like if it implements os.PathLike or is a str or bytes object which represents a file system path. Code can use os.fspath(), os.fsdecode(), or os.fsencode() to explicitly get a str and/or bytes representation of a path-like object.

The built-in open() function has been updated to accept os.PathLike objects, as have all relevant functions in the os and os.path modules, and most other functions and classes in the standard library. The os.DirEntry class and relevant classes in pathlib have also been updated to implement 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 path-like objects without any code changes, or at least very minimal ones (e.g. calling 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 pathlib.Path to be used more easily and transparently with pre-existing code:

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

(Implemented by Brett Cannon, Ethan Furman, Dusty Phillips, and Jelle Zijlstra.)

参考

PEP 519 [https://peps.python.org/pep-0519/] -- ファイルシステムパスプロトコルの追加

PEP written by Brett Cannon and Koos Zevenhoven.

PEP 495: 地域時間の曖昧さ回避

世界の大抵の場所で、地域時計が1日繰り下げられることがこれまでありましたし、これからもあるでしょう。そういった時に、同じ日に同じ時間を指す区間があります。そういった状況では地域時計が表示する (あるいは Python の datetime インスタンスが格納する) 情報では、時間内の特定の瞬間を識別することはできません。

PEP 495 [https://peps.python.org/pep-0495/] は時間内の地域時間が同じ二つの瞬間を区別するために、新たな fold 属性を datetime.datetime インスタンスならびに datetime.time クラスに追加しました。

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

fold 属性の値は、曖昧な場合に時間内の二番目の (年代的) 瞬間を表しているものを除く全てのインスタンスで 0 です。

参考

PEP 495 [https://peps.python.org/pep-0495/] -- 地域時間の曖昧さ回避

PEP written by Alexander Belopolsky and Tim Peters, implementation by Alexander Belopolsky.

PEP 529: Windows ファイルシステムのエンコーディングを 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 sys.getfilesystemencoding(), which now defaults to 'utf-8'.

Applications that do not use str to represent paths should use os.fsencode() and os.fsdecode() to ensure their bytes are correctly encoded. To revert to the previous behaviour, set PYTHONLEGACYWINDOWSFSENCODING or call sys._enablelegacywindowsfsencoding().

See PEP 529 [https://peps.python.org/pep-0529/] for more information and discussion of code modifications that may be required.

PEP 528: Windows コンソールのエンコーディングを UTF-8 に変更

The default console on Windows will now accept all Unicode characters and provide correctly read str objects to Python code. sys.stdin, sys.stdout and 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 PYTHONLEGACYWINDOWSSTDIO.

参考

PEP 528 [https://peps.python.org/pep-0528/] -- Windows コンソールのエンコーディングを UTF-8 に変更

PEP written and implemented by Steve Dower.

PEP 520: クラス属性の定義の順番を保持

クラス定義体の中の属性は自然に順序付けられました。すなわち、ソース内での順番と同じになりました。この順番は新たなクラスの __dict__ 属性内で保持されます。

Also, the effective default class execution namespace (returned from type.__prepare__()) is now an insertion-order-preserving mapping.

参考

PEP 520 [https://peps.python.org/pep-0520/] -- クラス属性の定義の順番を保持

PEP written and implemented by Eric Snow.

PEP 468: キーワード引数の順番の保持

関数シグニチャにおける **kwargs は挿入順序を保存するマッピングであることが保証されるようになりました。

参考

PEP 468 [https://peps.python.org/pep-0468/] -- キーワード引数の順番の保持

PEP written and implemented by Eric Snow.

新たな dict 実装

The dict type now uses a "compact" representation based on a proposal by Raymond Hettinger [https://mail.python.org/pipermail/python-dev/2012-December/123028.html] which was first implemented by PyPy [https://morepypy.blogspot.com/2015/01/faster-more-memory-efficient-and-more.html]. The memory usage of the new 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 [https://bugs.python.org/issue?@action=redirect&bpo=27350]. Idea originally suggested by Raymond Hettinger [https://mail.python.org/pipermail/python-dev/2012-December/123028.html].)

PEP 523: CPython にフレーム評価 API を追加

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.

PEP 523 [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.

参考

PEP 523 [https://peps.python.org/pep-0523/] -- Adding a frame evaluation API to CPython

PEP written by Brett Cannon and Dino Viehland.

PYTHONMALLOC 環境変数

新たな環境変数 PYTHONMALLOC により Python メモリアロケータの設定とデバッグフックの導入ができます。

PYTHONMALLOC=debug を使用してリリースモードでコンパイルされた Python で、Python メモリアロケータにデバッグフックを導入できるようになりました。デバッグフックの効果は:

新たに割り当てられたメモリを 0xCB バイトで埋めます

解放されたメモリを 0xDB バイトで埋めます

Python メモリアロケータ API の違反を検知します。例えば PyMem_Malloc() で割り当てられたメモリブロックに PyObject_Free() を呼ぶこと。

バッファ開始前の書き込み (バッファアンダーフロー) を検知します

バッファ終端後の書き込み (バッファオーバーフロー) を検知します

Check that the GIL is held when allocator functions of PYMEM_DOMAIN_OBJ (ex: PyObject_Malloc()) and PYMEM_DOMAIN_MEM (ex: PyMem_Malloc()) domains are called.

Checking if the GIL is held is also a new feature of Python 3.6.

See the PyMem_SetupDebugHooks() function for debug hooks on Python memory allocators.

It is now also possible to force the usage of the malloc() allocator of the C library for all Python memory allocations using 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 tracemalloc module to get the traceback where a memory block was allocated.

Example of fatal error on buffer overflow using python3.6 -X tracemalloc=5 (store 5 frames in traces):

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

(Contributed by Victor Stinner in bpo-26516 [https://bugs.python.org/issue?@action=redirect&bpo=26516] and bpo-26564 [https://bugs.python.org/issue?@action=redirect&bpo=26564].)

DTrace and SystemTap probing support

Python can now be built --with-dtrace which enables static markers for the following events in the interpreter:

関数の呼び出し/復帰

ガベージコレクションの開始/終了

実行されたコードの行。

This can be used to instrument running interpreters in production, without the need to recompile specific debug builds or providing application-specific profiling/debugging code.

詳細については 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 [https://bugs.python.org/issue?@action=redirect&bpo=21590], based on patches by Jesús Cea Avión, David Malcolm, and Nikhil Benesch.)

その他の言語変更

Python 言語コアに小さな変更がいくつか行われました:

A global or nonlocal statement must now textually appear before the first use of the affected name in the same scope. Previously this was a SyntaxWarning.

It is now possible to set a special method to None to indicate that the corresponding operation is not available. For example, if a class sets __iter__() to None, the class is not iterable. (Contributed by Andrew Barnert and Ivan Levkivskyi in bpo-25958 [https://bugs.python.org/issue?@action=redirect&bpo=25958].)

Long sequences of repeated traceback lines are now abbreviated as "[Previous line repeated {count} more times]" (see traceback for an example). (Contributed by Emanuel Barry in bpo-26823 [https://bugs.python.org/issue?@action=redirect&bpo=26823].)

Import now raises the new exception ModuleNotFoundError (subclass of 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 [https://bugs.python.org/issue?@action=redirect&bpo=15767].)

Class methods relying on zero-argument super() will now work correctly when called from metaclass methods during class creation. (Contributed by Martin Teichmann in bpo-23722 [https://bugs.python.org/issue?@action=redirect&bpo=23722].)

新たなモジュール

secrets

The main purpose of the new 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.

警告

Note that the pseudo-random generators in the random module should NOT be used for security purposes. Use secrets on Python 3.6+ and os.urandom() on Python 3.5 and earlier.

参考

PEP 506 [https://peps.python.org/pep-0506/] -- Adding A Secrets Module To The Standard Library

PEP written and implemented by Steven D'Aprano.

改良されたモジュール

array

Exhausted iterators of array.array will now stay exhausted even if the iterated array is extended. This is consistent with the behavior of other mutable sequences.

Contributed by Serhiy Storchaka in bpo-26492 [https://bugs.python.org/issue?@action=redirect&bpo=26492].

ast

The new ast.Constant AST node has been added. It can be used by external AST optimizers for the purposes of constant folding.

Contributed by Victor Stinner in bpo-26146 [https://bugs.python.org/issue?@action=redirect&bpo=26146].

asyncio

Starting with Python 3.6 the asyncio module is no longer provisional and its API is considered stable.

Notable changes in the asyncio module since Python 3.5.0 (all backported to 3.5.x due to the provisional status):

The 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 [https://bugs.python.org/issue?@action=redirect&bpo=28613].)

The ensure_future() function and all functions that use it, such as loop.run_until_complete(), now accept all kinds of awaitable objects. (Contributed by Yury Selivanov.)

他のスレッドからコルーチンをイベントループに送信するための新たな run_coroutine_threadsafe() 関数。 (Contributed by Vincent Michel.)

New Transport.is_closing() method to check if the transport is closing or closed. (Contributed by Yury Selivanov.)

The loop.create_server() method can now accept a list of hosts. (Contributed by Yann Sionneau.)

New loop.create_future() method to create Future objects. This allows alternative event loop implementations, such as uvloop [https://github.com/MagicStack/uvloop], to provide a faster asyncio.Future implementation. (Contributed by Yury Selivanov in bpo-27041 [https://bugs.python.org/issue?@action=redirect&bpo=27041].)

New loop.get_exception_handler() method to get the current exception handler. (Contributed by Yury Selivanov in bpo-27040 [https://bugs.python.org/issue?@action=redirect&bpo=27040].)

新しい StreamReader.readuntil() メソッドで、区切りとなるバイトの並びが出てくるまでストリームからデータを読み取れるようになりました。 (Contributed by Mark Korenberg.)

The performance of StreamReader.readexactly() has been improved. (Contributed by Mark Korenberg in bpo-28370 [https://bugs.python.org/issue?@action=redirect&bpo=28370].)

The loop.getaddrinfo() method is optimized to avoid calling the system getaddrinfo function if the address is already resolved. (Contributed by A. Jesse Jiryu Davis.)

The 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 [https://bugs.python.org/issue?@action=redirect&bpo=25593].)

Future.set_exception will now raise TypeError when passed an instance of the StopIteration exception. (Contributed by Chris Angelico in bpo-26221 [https://bugs.python.org/issue?@action=redirect&bpo=26221].)

New 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 [https://bugs.python.org/issue?@action=redirect&bpo=27392].)

TCP_NODELAY flag is now set for all TCP transports by default. (Contributed by Yury Selivanov in bpo-27456 [https://bugs.python.org/issue?@action=redirect&bpo=27456].)

New loop.shutdown_asyncgens() to properly close pending asynchronous generators before closing the loop. (Contributed by Yury Selivanov in bpo-28003 [https://bugs.python.org/issue?@action=redirect&bpo=28003].)

Future and 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 [https://bugs.python.org/issue?@action=redirect&bpo=26081] and bpo-28544 [https://bugs.python.org/issue?@action=redirect&bpo=28544].)

binascii

The 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 [https://bugs.python.org/issue?@action=redirect&bpo=25357].)

cmath

The new cmath.tau (τ) constant has been added. (Contributed by Lisa Roach in bpo-12345 [https://bugs.python.org/issue?@action=redirect&bpo=12345], see PEP 628 [https://peps.python.org/pep-0628/] for details.)

新たに定数が追加されました。 math.inf と math.nan に対応する cmath.inf と cmath.nan。複素数の repr が使用する書式に対応する cmath.infj と cmath.nanj。 (Contributed by Mark Dickinson in bpo-23229 [https://bugs.python.org/issue?@action=redirect&bpo=23229].)

collections

The new Collection abstract base class has been added to represent sized iterable container classes. (Contributed by Ivan Levkivskyi, docs by Neil Girdhar in bpo-27598 [https://bugs.python.org/issue?@action=redirect&bpo=27598].)

The new Reversible abstract base class represents iterable classes that also provide the __reversed__() method. (Contributed by Ivan Levkivskyi in bpo-25987 [https://bugs.python.org/issue?@action=redirect&bpo=25987].)

The new AsyncGenerator abstract base class represents asynchronous generators. (Contributed by Yury Selivanov in bpo-28720 [https://bugs.python.org/issue?@action=redirect&bpo=28720].)

The namedtuple() function now accepts an optional keyword argument module, which, when specified, is used for the __module__ attribute of the returned named tuple class. (Contributed by Raymond Hettinger in bpo-17941 [https://bugs.python.org/issue?@action=redirect&bpo=17941].)

The verbose and rename arguments for namedtuple() are now keyword-only. (Contributed by Raymond Hettinger in bpo-25628 [https://bugs.python.org/issue?@action=redirect&bpo=25628].)

Recursive collections.deque instances can now be pickled. (Contributed by Serhiy Storchaka in bpo-26482 [https://bugs.python.org/issue?@action=redirect&bpo=26482].)

concurrent.futures

The 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 [https://bugs.python.org/issue?@action=redirect&bpo=27664].)

contextlib

The contextlib.AbstractContextManager class has been added to provide an abstract base class for context managers. It provides a sensible default implementation for __enter__() which returns self and leaves __exit__() an abstract method. A matching class has been added to the typing module as typing.ContextManager. (Contributed by Brett Cannon in bpo-25609 [https://bugs.python.org/issue?@action=redirect&bpo=25609].)

datetime

The datetime and time classes have the new fold attribute used to disambiguate local time when necessary. Many functions in the datetime have been updated to support local time disambiguation. See Local Time Disambiguation section for more information. (Contributed by Alexander Belopolsky in bpo-24773 [https://bugs.python.org/issue?@action=redirect&bpo=24773].)

The datetime.strftime() and date.strftime() methods now support ISO 8601 date directives %G, %u and %V. (Contributed by Ashley Anderson in bpo-12006 [https://bugs.python.org/issue?@action=redirect&bpo=12006].)

The 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 [https://bugs.python.org/issue?@action=redirect&bpo=19475].)

The datetime.combine() now accepts an optional tzinfo argument. (Contributed by Alexander Belopolsky in bpo-27661 [https://bugs.python.org/issue?@action=redirect&bpo=27661].)

decimal

New Decimal.as_integer_ratio() method that returns a pair (n, d) of integers that represent the given Decimal instance as a fraction, in lowest terms and with a positive denominator:

>>> Decimal('-3.14').as_integer_ratio()
(-157, 50)

(Contributed by Stefan Krah amd Mark Dickinson in bpo-25928 [https://bugs.python.org/issue?@action=redirect&bpo=25928].)

distutils

The default_format attribute has been removed from distutils.command.sdist.sdist and the formats attribute defaults to ['gztar']. Although not anticipated, any code relying on the presence of default_format may need to be adapted. See bpo-27819 [https://bugs.python.org/issue?@action=redirect&bpo=27819] for more details.

email

The new email API, enabled via the policy keyword to various constructors, is no longer provisional. The 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 [https://bugs.python.org/issue?@action=redirect&bpo=24277].)

The email.mime classes now all accept an optional policy keyword. (Contributed by Berker Peksag in bpo-27331 [https://bugs.python.org/issue?@action=redirect&bpo=27331].)

The DecodedGenerator now supports the policy keyword.

There is a new policy attribute, message_factory, that controls what class is used by default when the parser creates new message objects. For the email.policy.compat32 policy this is Message, for the new policies it is EmailMessage. (Contributed by R. David Murray in bpo-20476 [https://bugs.python.org/issue?@action=redirect&bpo=20476].)

エンコーディング

On Windows, added the 'oem' encoding to use CP_OEMCP, and the 'ansi' alias for the existing 'mbcs' encoding, which uses the CP_ACP code page. (Contributed by Steve Dower in bpo-27959 [https://bugs.python.org/issue?@action=redirect&bpo=27959].)

enum

Two new enumeration base classes have been added to the enum module: Flag and IntFlags. Both are used to define constants that can be combined using the bitwise operators. (Contributed by Ethan Furman in bpo-23591 [https://bugs.python.org/issue?@action=redirect&bpo=23591].)

Many standard library modules have been updated to use the IntFlags class for their constants.

The new enum.auto value can be used to assign values to enum members automatically:

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

faulthandler

On Windows, the faulthandler module now installs a handler for Windows exceptions: see faulthandler.enable(). (Contributed by Victor Stinner in bpo-23848 [https://bugs.python.org/issue?@action=redirect&bpo=23848].)

fileinput

hook_encoded() now supports the errors argument. (Contributed by Joseph Hackman in bpo-25788 [https://bugs.python.org/issue?@action=redirect&bpo=25788].)

hashlib

hashlib supports OpenSSL 1.1.0. The minimum recommend version is 1.0.2. (Contributed by Christian Heimes in bpo-26470 [https://bugs.python.org/issue?@action=redirect&bpo=26470].)

BLAKE2 hash functions were added to the module. blake2b() and blake2s() are always available and support the full feature set of BLAKE2. (Contributed by Christian Heimes in bpo-26798 [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 sha3_224(), sha3_256(), sha3_384(), sha3_512(), and SHAKE hash functions shake_128() and shake_256() were added. (Contributed by Christian Heimes in bpo-16113 [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 scrypt() is now available with OpenSSL 1.1.0 and newer. (Contributed by Christian Heimes in bpo-27928 [https://bugs.python.org/issue?@action=redirect&bpo=27928].)

http.client

HTTPConnection.request() and endheaders() both now support chunked encoding request bodies. (Contributed by Demian Brecht and Rolf Krahl in bpo-12319 [https://bugs.python.org/issue?@action=redirect&bpo=12319].)

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

自動補完におけるいくつもの修正。 (Contributed by Louie Lu in bpo-15786 [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 [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 [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 [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 [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 [https://bugs.python.org/issue?@action=redirect&bpo=33642], bpo-33768 [https://bugs.python.org/issue?@action=redirect&bpo=33768], and bpo-33679 [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 [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 [https://bugs.python.org/issue?@action=redirect&bpo=1529353].)

importlib

Import now raises the new exception ModuleNotFoundError (subclass of ImportError) when it cannot find a module. Code that current checks for ImportError (in try-except) will still work. (Contributed by Eric Snow in bpo-15767 [https://bugs.python.org/issue?@action=redirect&bpo=15767].)

importlib.util.LazyLoader now calls create_module() on the wrapped loader, removing the restriction that importlib.machinery.BuiltinImporter and importlib.machinery.ExtensionFileLoader couldn't be used with importlib.util.LazyLoader.

importlib.util.cache_from_source(), importlib.util.source_from_cache(), and importlib.util.spec_from_file_location() now accept a path-like object.

inspect

The inspect.signature() function now reports the implicit .0 parameters generated by the compiler for comprehension and generator expression scopes as if they were positional-only parameters called implicit0. (Contributed by Jelle Zijlstra in bpo-19611 [https://bugs.python.org/issue?@action=redirect&bpo=19611].)

To reduce code churn when upgrading from Python 2.7 and the legacy inspect.getargspec() API, the previously documented deprecation of inspect.getfullargspec() has been reversed. While this function is convenient for single/source Python 2/3 code bases, the richer inspect.signature() interface remains the recommended approach for new code. (Contributed by Nick Coghlan in bpo-27172 [https://bugs.python.org/issue?@action=redirect&bpo=27172])

json

json.load() と json.loads() は、バイナリ入力をサポートしました。エンコード済みのJSON は、 UTF-8, UTF-16, UTF-32のいずれかを返すべきです。 (Contributed by Serhiy Storchaka in bpo-17909 [https://bugs.python.org/issue?@action=redirect&bpo=17909].)

logging

新しく WatchedFileHandler.reopenIfNeeded() メソッドが追加され、ログファイルを再オープンする必要があるかどうかをチェックする機能が追加れました。(Contributed by Marian Horban in bpo-24884 [https://bugs.python.org/issue?@action=redirect&bpo=24884].)

math

The tau (τ) constant has been added to the math and cmath modules. (Contributed by Lisa Roach in bpo-12345 [https://bugs.python.org/issue?@action=redirect&bpo=12345], see PEP 628 [https://peps.python.org/pep-0628/] for details.)

multiprocessing

Proxy Objects returned by multiprocessing.Manager() can now be nested. (Contributed by Davin Potts in bpo-6766 [https://bugs.python.org/issue?@action=redirect&bpo=6766].)

os

See the summary of PEP 519 for details on how the os and os.path modules now support path-like objects.

scandir() now supports bytes paths on Windows.

A new close() method allows explicitly closing a scandir() iterator. The scandir() iterator now supports the context manager protocol. If a scandir() iterator is neither exhausted nor explicitly closed a ResourceWarning will be emitted in its destructor. (Contributed by Serhiy Storchaka in bpo-25994 [https://bugs.python.org/issue?@action=redirect&bpo=25994].)

On Linux, os.urandom() now blocks until the system urandom entropy pool is initialized to increase the security. See the PEP 524 [https://peps.python.org/pep-0524/] for the rationale.

The Linux getrandom() syscall (get random bytes) is now exposed as the new os.getrandom() function. (Contributed by Victor Stinner, part of the PEP 524 [https://peps.python.org/pep-0524/])

pathlib

pathlib は path-like objects をサポートしました。 (Contributed by Brett Cannon in bpo-27186 [https://bugs.python.org/issue?@action=redirect&bpo=27186].)

詳細は、 PEP 519 の要約を参照してください。

pdb

Pdb クラスのコンストラクタに、新しくオプション引数 readrc が増えました。この引数は、 .pdbrc ファイルを読み込むかどうかを指定します。

pickle

Objects that need __new__ called with keyword arguments can now be pickled using pickle protocols older than protocol version 4. Protocol version 4 already supports this case. (Contributed by Serhiy Storchaka in bpo-24164 [https://bugs.python.org/issue?@action=redirect&bpo=24164].)

pickletools

pickletools.dis() now outputs the implicit memo index for the MEMOIZE opcode. (Contributed by Serhiy Storchaka in bpo-25382 [https://bugs.python.org/issue?@action=redirect&bpo=25382].)

pydoc

The pydoc module has learned to respect the MANPAGER environment variable. (Contributed by Matthias Klose in bpo-8637 [https://bugs.python.org/issue?@action=redirect&bpo=8637].)

help() and pydoc can now list named tuple fields in the order they were defined rather than alphabetically. (Contributed by Raymond Hettinger in bpo-24879 [https://bugs.python.org/issue?@action=redirect&bpo=24879].)

random

The new choices() function returns a list of elements of specified size from the given population with optional weights. (Contributed by Raymond Hettinger in bpo-18844 [https://bugs.python.org/issue?@action=redirect&bpo=18844].)

re

Added support of modifier spans in regular expressions. Examples: '(?i:p)ython' matches 'python' and 'Python', but not 'PYTHON'; '(?i)g(?-i:v)r' matches 'GvR' and 'gvr', but not 'GVR'. (Contributed by Serhiy Storchaka in bpo-433028 [https://bugs.python.org/issue?@action=redirect&bpo=433028].)

Match object groups can be accessed by __getitem__, which is equivalent to group(). So mo['name'] is now equivalent to mo.group('name'). (Contributed by Eric Smith in bpo-24454 [https://bugs.python.org/issue?@action=redirect&bpo=24454].)

Match objects now support index-like objects as group indices. (Contributed by Jeroen Demeyer and Xiang Zhang in bpo-27177 [https://bugs.python.org/issue?@action=redirect&bpo=27177].)

readline

Added set_auto_history() to enable or disable automatic addition of input to the history list. (Contributed by Tyler Crompton in bpo-26870 [https://bugs.python.org/issue?@action=redirect&bpo=26870].)

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 [https://bugs.python.org/issue?@action=redirect&bpo=25011] and bpo-25209 [https://bugs.python.org/issue?@action=redirect&bpo=25209].)

shlex

The shlex has much improved shell compatibility through the new punctuation_chars argument to control which characters are treated as punctuation. (Contributed by Vinay Sajip in bpo-1521950 [https://bugs.python.org/issue?@action=redirect&bpo=1521950].)

site

When specifying paths to add to sys.path in a .pth file, you may now specify file paths on top of directories (e.g. zip files). (Contributed by Wolfgang Langner in bpo-26587 [https://bugs.python.org/issue?@action=redirect&bpo=26587]).

sqlite3

sqlite3.Cursor.lastrowid は、 REPLACE 文をサポートしました。 (Contributed by Alex LordThorsen in bpo-16864 [https://bugs.python.org/issue?@action=redirect&bpo=16864].)

socket

The ioctl() function now supports the SIO_LOOPBACK_FAST_PATH control code. (Contributed by Daniel Stokes in bpo-26536 [https://bugs.python.org/issue?@action=redirect&bpo=26536].)

The getsockopt() constants SO_DOMAIN, SO_PROTOCOL, SO_PEERSEC, and SO_PASSSEC are now supported. (Contributed by Christian Heimes in bpo-26907 [https://bugs.python.org/issue?@action=redirect&bpo=26907].)

The setsockopt() now supports the setsockopt(level, optname, None, optlen: int) form. (Contributed by Christian Heimes in bpo-27744 [https://bugs.python.org/issue?@action=redirect&bpo=27744].)

The socket module now supports the address family AF_ALG to interface with Linux Kernel crypto API. ALG_*, SOL_ALG and sendmsg_afalg() were added. (Contributed by Christian Heimes in bpo-27744 [https://bugs.python.org/issue?@action=redirect&bpo=27744] with support from Victor Stinner.)

New Linux constants TCP_USER_TIMEOUT and TCP_CONGESTION were added. (Contributed by Omar Sandoval, bpo-26273 [https://bugs.python.org/issue?@action=redirect&bpo=26273]).

socketserver

Servers based on the socketserver module, including those defined in http.server, xmlrpc.server and wsgiref.simple_server, now support the context manager protocol. (Contributed by Aviv Palivoda in bpo-26404 [https://bugs.python.org/issue?@action=redirect&bpo=26404].)

The wfile attribute of StreamRequestHandler classes now implements the io.BufferedIOBase writable interface. In particular, calling write() is now guaranteed to send the data in full. (Contributed by Martin Panter in bpo-26721 [https://bugs.python.org/issue?@action=redirect&bpo=26721].)

ssl

ssl supports OpenSSL 1.1.0. The minimum recommend version is 1.0.2. (Contributed by Christian Heimes in bpo-26470 [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 [https://bugs.python.org/issue?@action=redirect&bpo=27850] and bpo-27766 [https://bugs.python.org/issue?@action=redirect&bpo=27766].)

SSLContext has better default configuration for options and ciphers. (Contributed by Christian Heimes in bpo-28043 [https://bugs.python.org/issue?@action=redirect&bpo=28043].)

SSL session can be copied from one client-side connection to another with the new SSLSession class. TLS session resumption can speed up the initial handshake, reduce latency and improve performance (Contributed by Christian Heimes in bpo-19500 [https://bugs.python.org/issue?@action=redirect&bpo=19500] based on a draft by Alex Warhawk.)

The new 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 IntEnum and IntFlags. (Contributed by Christian Heimes in bpo-28025 [https://bugs.python.org/issue?@action=redirect&bpo=28025].)

Server and client-side specific TLS protocols for SSLContext were added. (Contributed by Christian Heimes in bpo-28085 [https://bugs.python.org/issue?@action=redirect&bpo=28085].)

Added ssl.SSLContext.post_handshake_auth to enable and ssl.SSLSocket.verify_client_post_handshake() to initiate TLS 1.3 post-handshake authentication. (Contributed by Christian Heimes in gh-78851 [https://github.com/python/cpython/issues/78851].)

statistics

A new harmonic_mean() function has been added. (Contributed by Steven D'Aprano in bpo-27181 [https://bugs.python.org/issue?@action=redirect&bpo=27181].)

struct

struct now supports IEEE 754 half-precision floats via the 'e' format specifier. (Contributed by Eli Stevens, Mark Dickinson in bpo-11734 [https://bugs.python.org/issue?@action=redirect&bpo=11734].)

subprocess

subprocess.Popen destructor now emits a ResourceWarning warning if the child process is still running. Use the context manager protocol (with proc: ...) or explicitly call the wait() method to read the exit status of the child process. (Contributed by Victor Stinner in bpo-26741 [https://bugs.python.org/issue?@action=redirect&bpo=26741].)

The 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 [https://bugs.python.org/issue?@action=redirect&bpo=6135].)

sys

The new 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 [https://bugs.python.org/issue?@action=redirect&bpo=27781].)

On Windows the return value of the 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 [https://bugs.python.org/issue?@action=redirect&bpo=27932].)

telnetlib

Telnet is now a context manager (contributed by Stéphane Wirtel in bpo-25485 [https://bugs.python.org/issue?@action=redirect&bpo=25485]).

time

struct_time の属性 tm_gmtoff および tm_zone が全てのプラットフォームで利用できるようになりました。

timeit

The new Timer.autorange() convenience method has been added to call Timer.timeit() repeatedly so that the total run time is greater or equal to 200 milliseconds. (Contributed by Steven D'Aprano in bpo-6422 [https://bugs.python.org/issue?@action=redirect&bpo=6422].)

timeit now warns when there is substantial (4x) variance between best and worst times. (Contributed by Serhiy Storchaka in bpo-23552 [https://bugs.python.org/issue?@action=redirect&bpo=23552].)

tkinter

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. (Contributed by Serhiy Storchaka in bpo-22115 [https://bugs.python.org/issue?@action=redirect&bpo=22115]).

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:

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

(Contributed by Emanuel Barry in bpo-26823 [https://bugs.python.org/issue?@action=redirect&bpo=26823].)

tracemalloc

The tracemalloc module now supports tracing memory allocations in multiple different address spaces.

The new DomainFilter filter class has been added to filter block traces by their address space (domain).

(Contributed by Victor Stinner in bpo-26588 [https://bugs.python.org/issue?@action=redirect&bpo=26588].)

typing

Since the typing module is provisional, all changes introduced in Python 3.6 have also been backported to Python 3.5.x.

The typing module has a much improved support for generic type aliases. For example Dict[str, Tuple[S, T]] is now a valid type annotation. (Contributed by Guido van Rossum in Github #195 [https://github.com/python/typing/pull/195].)

The typing.ContextManager class has been added for representing contextlib.AbstractContextManager. (Contributed by Brett Cannon in bpo-25609 [https://bugs.python.org/issue?@action=redirect&bpo=25609].)

The typing.Collection class has been added for representing collections.abc.Collection. (Contributed by Ivan Levkivskyi in bpo-27598 [https://bugs.python.org/issue?@action=redirect&bpo=27598].)

The typing.ClassVar type construct has been added to mark class variables. As introduced in PEP 526 [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 [https://github.com/python/typing/pull/280].)

A new TYPE_CHECKING constant that is assumed to be True by the static type checkers, but is False at runtime. (Contributed by Guido van Rossum in Github #230 [https://github.com/python/typing/issues/230].)

A new NewType() helper function has been added to create lightweight distinct types for annotations:

from typing import NewType

UserId = NewType('UserId', int)
some_id = UserId(524313)

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 [https://github.com/python/typing/issues/189].)

unicodedata

The unicodedata module now uses data from Unicode 9.0.0 [https://unicode.org/versions/Unicode9.0.0/]. (Contributed by Benjamin Peterson.)

unittest.mock

Mock クラスは、次の改善が行われました。

Mock.assert_called() と Mock.assert_called_once() は、mockオブジェクトが呼ばれたかどうかを確認します。 (Contributed by Amit Saha in bpo-26323 [https://bugs.python.org/issue?@action=redirect&bpo=26323].)

The Mock.reset_mock() method now has two optional keyword only arguments: return_value and side_effect. (Contributed by Kushal Das in bpo-21271 [https://bugs.python.org/issue?@action=redirect&bpo=21271].)

urllib.request

If a HTTP request has a file or iterable body (other than a bytes object) but no Content-Length header, rather than throwing an error, AbstractHTTPHandler now falls back to use chunked transfer encoding. (Contributed by Demian Brecht and Rolf Krahl in bpo-12319 [https://bugs.python.org/issue?@action=redirect&bpo=12319].)

urllib.robotparser

RobotFileParser now supports the Crawl-delay and Request-rate extensions. (Contributed by Nikolay Bogoychev in bpo-16099 [https://bugs.python.org/issue?@action=redirect&bpo=16099].)

venv

venv は、新しいパラメータ `--prompt`` を受け入れました。このパラメータは、 仮想環境を表すプリフィックスを指定します。 (Proposed by Łukasz Balcerzak and ported to 3.6 by Stéphane Wirtel in bpo-22829 [https://bugs.python.org/issue?@action=redirect&bpo=22829].)

warnings

A new optional source parameter has been added to the warnings.warn_explicit() function: the destroyed object which emitted a ResourceWarning. A source attribute has also been added to warnings.WarningMessage (contributed by Victor Stinner in bpo-26568 [https://bugs.python.org/issue?@action=redirect&bpo=26568] and bpo-26567 [https://bugs.python.org/issue?@action=redirect&bpo=26567]).

When a ResourceWarning warning is logged, the tracemalloc module is now used to try to retrieve the traceback where the destroyed object was allocated.

スクリプト example.py での例:

import warnings

def func():
    return open(__file__)

f = func()
f = None

Output of the command python3.6 -Wd -X tracemalloc=5 example.py:

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()

The "Object allocated at" traceback is new and is only displayed if tracemalloc is tracing Python memory allocations and if the warnings module was already imported.

winreg

Added the 64-bit integer type REG_QWORD. (Contributed by Clement Rouault in bpo-23026 [https://bugs.python.org/issue?@action=redirect&bpo=23026].)

winsound

Allowed keyword arguments to be passed to Beep, MessageBeep, and PlaySound (bpo-27982 [https://bugs.python.org/issue?@action=redirect&bpo=27982]).

xmlrpc.client

The xmlrpc.client module now supports unmarshalling additional data types used by the Apache XML-RPC implementation for numerics and None. (Contributed by Serhiy Storchaka in bpo-26885 [https://bugs.python.org/issue?@action=redirect&bpo=26885].)

zipfile

A new ZipInfo.from_file() class method allows making a ZipInfo instance from a filesystem file. A new ZipInfo.is_dir() method can be used to check if the ZipInfo instance represents a directory. (Contributed by Thomas Kluyver in bpo-26039 [https://bugs.python.org/issue?@action=redirect&bpo=26039].)

The 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 [https://bugs.python.org/issue?@action=redirect&bpo=26039].)

zlib

The compress() and decompress() functions now accept keyword arguments. (Contributed by Aviv Palivoda in bpo-26243 [https://bugs.python.org/issue?@action=redirect&bpo=26243] and Xiang Zhang in bpo-16764 [https://bugs.python.org/issue?@action=redirect&bpo=16764] respectively.)

最適化

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 [https://bugs.python.org/issue?@action=redirect&bpo=26647] and bpo-28050 [https://bugs.python.org/issue?@action=redirect&bpo=28050].)

The asyncio.Future class now has an optimized C implementation. (Contributed by Yury Selivanov and INADA Naoki in bpo-26081 [https://bugs.python.org/issue?@action=redirect&bpo=26081].)

The asyncio.Task class now has an optimized C implementation. (Contributed by Yury Selivanov in bpo-28544 [https://bugs.python.org/issue?@action=redirect&bpo=28544].)

Various implementation improvements in the typing module (such as caching of generic types) allow up to 30 times performance improvements and reduced memory footprint.

The ASCII decoder is now up to 60 times as fast for error handlers surrogateescape, ignore and replace (Contributed by Victor Stinner in bpo-24870 [https://bugs.python.org/issue?@action=redirect&bpo=24870]).

The ASCII and the Latin1 encoders are now up to 3 times as fast for the error handler surrogateescape (Contributed by Victor Stinner in bpo-25227 [https://bugs.python.org/issue?@action=redirect&bpo=25227]).

The UTF-8 encoder is now up to 75 times as fast for error handlers ignore, replace, surrogateescape, surrogatepass (Contributed by Victor Stinner in bpo-25267 [https://bugs.python.org/issue?@action=redirect&bpo=25267]).

The UTF-8 decoder is now up to 15 times as fast for error handlers ignore, replace and surrogateescape (Contributed by Victor Stinner in bpo-25301 [https://bugs.python.org/issue?@action=redirect&bpo=25301]).

bytes % args is now up to 2 times faster. (Contributed by Victor Stinner in bpo-25349 [https://bugs.python.org/issue?@action=redirect&bpo=25349]).

bytearray % args is now between 2.5 and 5 times faster. (Contributed by Victor Stinner in bpo-25399 [https://bugs.python.org/issue?@action=redirect&bpo=25399]).

Optimize bytes.fromhex() and bytearray.fromhex(): they are now between 2x and 3.5x faster. (Contributed by Victor Stinner in bpo-25401 [https://bugs.python.org/issue?@action=redirect&bpo=25401]).

Optimize bytes.replace(b'', b'.') and bytearray.replace(b'', b'.'): up to 80% faster. (Contributed by Josh Snider in bpo-26574 [https://bugs.python.org/issue?@action=redirect&bpo=26574]).

Allocator functions of the PyMem_Malloc() domain (PYMEM_DOMAIN_MEM) now use the pymalloc memory allocator instead of 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 malloc() for larger memory blocks. (Contributed by Victor Stinner in bpo-26249 [https://bugs.python.org/issue?@action=redirect&bpo=26249]).

pickle.load() and pickle.loads() are now up to 10% faster when deserializing many small objects (Contributed by Victor Stinner in bpo-27056 [https://bugs.python.org/issue?@action=redirect&bpo=27056]).

Passing keyword arguments to a function has an overhead in comparison with passing positional arguments. Now in extension functions implemented with using Argument Clinic this overhead is significantly decreased. (Contributed by Serhiy Storchaka in bpo-27574 [https://bugs.python.org/issue?@action=redirect&bpo=27574]).

Optimized glob() and iglob() functions in the glob module; they are now about 3--6 times faster. (Contributed by Serhiy Storchaka in bpo-25596 [https://bugs.python.org/issue?@action=redirect&bpo=25596]).

Optimized globbing in pathlib by using os.scandir(); it is now about 1.5--4 times faster. (Contributed by Serhiy Storchaka in bpo-26032 [https://bugs.python.org/issue?@action=redirect&bpo=26032]).

xml.etree.ElementTree parsing, iteration and deepcopy performance has been significantly improved. (Contributed by Serhiy Storchaka in bpo-25638 [https://bugs.python.org/issue?@action=redirect&bpo=25638], bpo-25873 [https://bugs.python.org/issue?@action=redirect&bpo=25873], and bpo-25869 [https://bugs.python.org/issue?@action=redirect&bpo=25869].)

Creation of fractions.Fraction instances from floats and decimals is now 2 to 3 times faster. (Contributed by Serhiy Storchaka in bpo-25971 [https://bugs.python.org/issue?@action=redirect&bpo=25971].)

ビルドならびに C API の変更

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 PY_LONG_LONG. For more information, see PEP 7 [https://peps.python.org/pep-0007/] and bpo-17884 [https://bugs.python.org/issue?@action=redirect&bpo=17884].

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 [https://bugs.python.org/issue?@action=redirect&bpo=26865].

The --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 [https://bugs.python.org/issue?@action=redirect&bpo=26359].)

The GIL must now be held when allocator functions of PYMEM_DOMAIN_OBJ (ex: PyObject_Malloc()) and PYMEM_DOMAIN_MEM (ex: PyMem_Malloc()) domains are called.

New Py_FinalizeEx() API which indicates if flushing buffered data failed. (Contributed by Martin Panter in bpo-5319 [https://bugs.python.org/issue?@action=redirect&bpo=5319].)

PyArg_ParseTupleAndKeywords() now supports positional-only parameters. Positional-only parameters are defined by empty names. (Contributed by Serhiy Storchaka in bpo-26282 [https://bugs.python.org/issue?@action=redirect&bpo=26282]).

PyTraceback_Print method now abbreviates long sequences of repeated lines as "[Previous line repeated {count} more times]". (Contributed by Emanuel Barry in bpo-26823 [https://bugs.python.org/issue?@action=redirect&bpo=26823].)

The new PyErr_SetImportErrorSubclass() function allows for specifying a subclass of ImportError to raise. (Contributed by Eric Snow in bpo-15767 [https://bugs.python.org/issue?@action=redirect&bpo=15767].)

The new PyErr_ResourceWarning() function can be used to generate a ResourceWarning providing the source of the resource allocation. (Contributed by Victor Stinner in bpo-26567 [https://bugs.python.org/issue?@action=redirect&bpo=26567].)

The new PyOS_FSPath() function returns the file system representation of a path-like object. (Contributed by Brett Cannon in bpo-27186 [https://bugs.python.org/issue?@action=redirect&bpo=27186].)

The PyUnicode_FSConverter() and PyUnicode_FSDecoder() functions will now accept path-like objects.

その他の改善

--version (短縮系: -V) が2回与えられた場合、Python は sys.version で詳細な情報を出力します。

$ ./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)]

非推奨

新たなキーワード

async および await を変数、クラス、関数、モジュール名として使用することは推奨されません。async と await は Python 3.5 で PEP 492 [https://peps.python.org/pep-0492/] により導入され、Python 3.7 で正式にキーワードとなります。Python 3.6 から async や await を変数名に使用すると DeprecationWarning が出ます。

非推奨の Python 挙動

Raising the StopIteration exception inside a generator will now generate a DeprecationWarning, and will trigger a RuntimeError in Python 3.7. See PEP 479: ジェネレータ内の StopIteration の処理の変更 for details.

The __aiter__() method is now expected to return an asynchronous iterator directly instead of returning an awaitable as previously. Doing the former will trigger a DeprecationWarning. Backward compatibility will be removed in Python 3.7. (Contributed by Yury Selivanov in bpo-27243 [https://bugs.python.org/issue?@action=redirect&bpo=27243].)

A backslash-character pair that is not a valid escape sequence now generates a DeprecationWarning. Although this will eventually become a SyntaxError, that will not be for several Python releases. (Contributed by Emanuel Barry in bpo-27364 [https://bugs.python.org/issue?@action=redirect&bpo=27364].)

When performing a relative import, falling back on __name__ and __path__ from the calling module when __spec__ or __package__ are not defined now raises an ImportWarning. (Contributed by Rose Ames in bpo-25791 [https://bugs.python.org/issue?@action=redirect&bpo=25791].)

非推奨の Python モジュール、関数、メソッド

asynchat

The asynchat has been deprecated in favor of asyncio. (Contributed by Mariatta in bpo-25002 [https://bugs.python.org/issue?@action=redirect&bpo=25002].)

asyncore

The asyncore has been deprecated in favor of asyncio. (Contributed by Mariatta in bpo-25002 [https://bugs.python.org/issue?@action=redirect&bpo=25002].)

dbm

Unlike other dbm implementations, the dbm.dumb module creates databases with the 'rw' mode and allows modifying the database opened with the 'r' mode. This behavior is now deprecated and will be removed in 3.8. (Contributed by Serhiy Storchaka in bpo-21708 [https://bugs.python.org/issue?@action=redirect&bpo=21708].)

distutils

The undocumented extra_path argument to the 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 [https://bugs.python.org/issue?@action=redirect&bpo=27919] for details.

grp

getgrgid() の非整数の引数のサポートは非推奨になりました。 (Contributed by Serhiy Storchaka in bpo-26129 [https://bugs.python.org/issue?@action=redirect&bpo=26129].)

importlib

The importlib.machinery.SourceFileLoader.load_module() and importlib.machinery.SourcelessFileLoader.load_module() methods are now deprecated. They were the only remaining implementations of importlib.abc.Loader.load_module() in importlib that had not been deprecated in previous versions of Python in favour of importlib.abc.Loader.exec_module().

The importlib.machinery.WindowsRegistryFinder class is now deprecated. As of 3.6.0, it is still added to sys.meta_path by default (on Windows), but this may change in future releases.

os

Undocumented support of general bytes-like objects as paths in os functions, compile() and similar functions is now deprecated. (Contributed by Serhiy Storchaka in bpo-25791 [https://bugs.python.org/issue?@action=redirect&bpo=25791] and bpo-26754 [https://bugs.python.org/issue?@action=redirect&bpo=26754].)

re

Support for inline flags (?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 [https://bugs.python.org/issue?@action=redirect&bpo=22493].)

ssl

OpenSSLの0.9.8, 1.0.0 ,1.0.1 は非推奨となっており、長い間サポートされていません。将来的に ssl モジュールは、OpenSSLの1.0.2 もしくは1.1.0が必須になります。

SSL-related arguments like certfile, keyfile and check_hostname in ftplib, http.client, imaplib, poplib, and smtplib have been deprecated in favor of context. (Contributed by Christian Heimes in bpo-28022 [https://bugs.python.org/issue?@action=redirect&bpo=28022].)

A couple of protocols and functions of the 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 [https://bugs.python.org/issue?@action=redirect&bpo=28022] and bpo-26470 [https://bugs.python.org/issue?@action=redirect&bpo=26470].)

tkinter

The tkinter.tix module is now deprecated. tkinter users should use tkinter.ttk instead.

venv

The pyvenv script has been deprecated in favour of python3 -m venv. This prevents confusion as to what Python interpreter pyvenv is connected to and thus what Python interpreter will be used by the virtual environment. (Contributed by Brett Cannon in bpo-25154 [https://bugs.python.org/issue?@action=redirect&bpo=25154].)

xml

As mitigation against DTD and external entity retrieval, the xml.dom.minidom and xml.sax modules no longer process external entities by default. (Contributed by Christian Heimes in gh-61441 [https://github.com/python/cpython/issues/61441].)

C API の非推奨の関数ならびに型

Undocumented functions PyUnicode_AsEncodedObject(), PyUnicode_AsDecodedObject(), PyUnicode_AsEncodedUnicode() and PyUnicode_AsDecodedUnicode() are deprecated now. Use the generic codec based API instead.

非推奨のビルドオプション

The --with-system-ffi configure flag is now on by default on non-macOS UNIX platforms. It may be disabled by using --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 --with-system-ffi flag when building their system Python.

削除

API と機能の削除

Unknown escapes consisting of '\' and an ASCII letter in regular expressions will now cause an error. In replacement templates for re.sub() they are still allowed, but deprecated. The re.LOCALE flag can now only be used with binary patterns.

inspect.getmoduleinfo() was removed (was deprecated since CPython 3.3). inspect.getmodulename() should be used for obtaining the module name for a given path. (Contributed by Yury Selivanov in bpo-13248 [https://bugs.python.org/issue?@action=redirect&bpo=13248].)

traceback.Ignore class and traceback.usage, traceback.modname, traceback.fullmodname, traceback.find_lines_from_code, traceback.find_lines, traceback.find_strings, traceback.find_executable_lines methods were removed from the traceback module. They were undocumented methods deprecated since Python 3.2 and equivalent functionality is available from private methods.

The tk_menuBar() and tk_bindForTraversal() dummy methods in tkinter widget classes were removed (corresponding Tk commands were obsolete since Tk 4.0).

The open() method of the zipfile.ZipFile class no longer supports the 'U' mode (was deprecated since Python 3.4). Use io.TextIOWrapper for reading compressed text files in universal newlines mode.

The undocumented IN, CDROM, DLFCN, TYPES, CDIO, and STROPTS modules have been removed. They had been available in the platform specific 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 [https://github.com/python/cpython/blob/v3.6.15/Tools/scripts/h2py.py].

非推奨の asynchat.fifo クラスは削除されました。

Python 3.6 への移植

このセクションでは前述の変更とバグフィックスにより必要となるかもしれないコードの変更を列挙します:

'python' コマンドの挙動の変更

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. (Contributed by Serhiy Storchaka in bpo-23034 [https://bugs.python.org/issue?@action=redirect&bpo=23034].)

Python API の変更

open() will no longer allow combining the 'U' mode flag with '+'. (Contributed by Jeff Balogh and John O'Connor in bpo-2091 [https://bugs.python.org/issue?@action=redirect&bpo=2091].)

sqlite3 no longer implicitly commits an open transaction before DDL statements.

On Linux, os.urandom() now blocks until the system urandom entropy pool is initialized to increase the security.

When importlib.abc.Loader.exec_module() is defined, importlib.abc.Loader.create_module() must also be defined.

PyErr_SetImportError() now sets TypeError when its msg argument is not set. Previously only NULL was returned.

The format of the 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 frame.f_lineno, PyFrame_GetLineNumber() or PyCode_Addr2Line() are not affected. Functions directly decoding 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 Objects/lnotab_notes.txt for the co_lnotab format and how to decode it, and see the PEP 511 [https://peps.python.org/pep-0511/] for the rationale.

The functions in the compileall module now return booleans instead of 1 or 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 1 or 0. See bpo-25768 [https://bugs.python.org/issue?@action=redirect&bpo=25768].

Reading the port attribute of urllib.parse.urlsplit() and urlparse() results now raises ValueError for out-of-range values, rather than returning None. See bpo-20059 [https://bugs.python.org/issue?@action=redirect&bpo=20059].

The imp module now raises a DeprecationWarning instead of PendingDeprecationWarning.

The following modules have had missing APIs added to their __all__ attributes to match the documented APIs: calendar, cgi, csv, ElementTree, enum, fileinput, ftplib, logging, mailbox, mimetypes, optparse, plistlib, smtpd, subprocess, tarfile, threading and wave. This means they will export new symbols when import * is used. (Contributed by Joel Taddei and Jacek Kołodziej in bpo-23883 [https://bugs.python.org/issue?@action=redirect&bpo=23883].)

When performing a relative import, if __package__ does not compare equal to __spec__.parent then ImportWarning is raised. (Contributed by Brett Cannon in bpo-25791 [https://bugs.python.org/issue?@action=redirect&bpo=25791].)

When a relative import is performed and no parent package is known, then ImportError will be raised. Previously, SystemError could be raised. (Contributed by Brett Cannon in bpo-18018 [https://bugs.python.org/issue?@action=redirect&bpo=18018].)

Servers based on the socketserver module, including those defined in http.server, xmlrpc.server and wsgiref.simple_server, now only catch exceptions derived from Exception. Therefore if a request handler raises an exception like SystemExit or KeyboardInterrupt, handle_error() is no longer called, and the exception will stop a single-threaded server. (Contributed by Martin Panter in bpo-23430 [https://bugs.python.org/issue?@action=redirect&bpo=23430].)

spwd.getspnam() now raises a PermissionError instead of KeyError if the user doesn't have privileges.

The socket.socket.close() method now raises an exception if an error (e.g. EBADF) was reported by the underlying system call. (Contributed by Martin Panter in bpo-26685 [https://bugs.python.org/issue?@action=redirect&bpo=26685].)

The decode_data argument for the smtpd.SMTPChannel and smtpd.SMTPServer constructors is now False by default. This means that the argument passed to process_message() is now a bytes object by default, and 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.

All optional arguments of the dump(), dumps(), load() and loads() functions and JSONEncoder and JSONDecoder class constructors in the json module are now keyword-only. (Contributed by Serhiy Storchaka in bpo-18726 [https://bugs.python.org/issue?@action=redirect&bpo=18726].)

type.__new__ をオーバーライドしていない type のサブクラスは、オブジェクトの型を得るのに１引数形式を利用することができません。

As part of PEP 487 [https://peps.python.org/pep-0487/], the handling of keyword arguments passed to type (other than the metaclass hint, metaclass) is now consistently delegated to object.__init_subclass__(). This means that type.__new__() and type.__init__() both now accept arbitrary keyword arguments, but object.__init_subclass__() (which is called from type.__new__()) will reject them by default. Custom metaclasses accepting additional keyword arguments will need to adjust their calls to type.__new__() (whether direct or via super) accordingly.

In distutils.command.sdist.sdist, the 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 setup.cfg file containing the following:

[sdist]
formats=zip

この挙動は Setuptools 26.0.0 により以前の Python バージョンにバックポートされました。

In the urllib.request module and the 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 [https://bugs.python.org/issue?@action=redirect&bpo=12319].)

The DictReader now returns rows of type OrderedDict. (Contributed by Steve Holden in bpo-27842 [https://bugs.python.org/issue?@action=redirect&bpo=27842].)

The crypt.METHOD_CRYPT will no longer be added to crypt.methods if unsupported by the platform. (Contributed by Victor Stinner in bpo-25287 [https://bugs.python.org/issue?@action=redirect&bpo=25287].)

The verbose and rename arguments for namedtuple() are now keyword-only. (Contributed by Raymond Hettinger in bpo-25628 [https://bugs.python.org/issue?@action=redirect&bpo=25628].)

On Linux, ctypes.util.find_library() now looks in LD_LIBRARY_PATH for shared libraries. (Contributed by Vinay Sajip in bpo-9998 [https://bugs.python.org/issue?@action=redirect&bpo=9998].)

The imaplib.IMAP4 class now handles flags containing the ']' character in messages sent from the server to improve real-world compatibility. (Contributed by Lita Cho in bpo-21815 [https://bugs.python.org/issue?@action=redirect&bpo=21815].)

The mmap.write() function now returns the number of bytes written like other write methods. (Contributed by Jakub Stasiak in bpo-26335 [https://bugs.python.org/issue?@action=redirect&bpo=26335].)

The pkgutil.iter_modules() and pkgutil.walk_packages() functions now return ModuleInfo named tuples. (Contributed by Ramchandra Apte in bpo-17211 [https://bugs.python.org/issue?@action=redirect&bpo=17211].)

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 [https://bugs.python.org/issue?@action=redirect&bpo=25953].)

zipfile.ZipFile will now raise NotImplementedError for unrecognized compression values. Previously a plain RuntimeError was raised. Additionally, calling ZipFile methods on a closed ZipFile or calling the write() method on a ZipFile created with mode 'r' will raise a ValueError. Previously, a RuntimeError was raised in those scenarios.

when custom metaclasses are combined with zero-argument super() or direct references from methods to the implicit __class__ closure variable, the implicit __classcell__ namespace entry must now be passed up to type.__new__ for initialisation. Failing to do so will result in a DeprecationWarning in Python 3.6 and a RuntimeError in Python 3.8.

With the introduction of ModuleNotFoundError, import system consumers may start expecting import system replacements to raise that more specific exception when appropriate, rather than the less-specific ImportError. To provide future compatibility with such consumers, implementors of alternative import systems that completely replace __import__() will need to update their implementations to raise the new subclass when a module can't be found at all. Implementors 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.

C API の変更

The PyMem_Malloc() allocator family now uses the pymalloc allocator rather than the system malloc(). Applications calling PyMem_Malloc() without holding the GIL can now crash. Set the PYTHONMALLOC environment variable to debug to validate the usage of memory allocators in your application. See bpo-26249 [https://bugs.python.org/issue?@action=redirect&bpo=26249].

Py_Exit() (and the main interpreter) now override the exit status with 120 if flushing buffered data failed. See bpo-5319 [https://bugs.python.org/issue?@action=redirect&bpo=5319].

CPython バイトコードの変更

There have been several major changes to the bytecode in Python 3.6.

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 [https://bugs.python.org/issue?@action=redirect&bpo=26647] and bpo-28050 [https://bugs.python.org/issue?@action=redirect&bpo=28050].)

The new FORMAT_VALUE and BUILD_STRING opcodes as part of the formatted string literal implementation. (Contributed by Eric Smith in bpo-25483 [https://bugs.python.org/issue?@action=redirect&bpo=25483] and Serhiy Storchaka in bpo-27078 [https://bugs.python.org/issue?@action=redirect&bpo=27078].)

The new BUILD_CONST_KEY_MAP opcode to optimize the creation of dictionaries with constant keys. (Contributed by Serhiy Storchaka in bpo-27140 [https://bugs.python.org/issue?@action=redirect&bpo=27140].)

The function call opcodes have been heavily reworked for better performance and simpler implementation. The MAKE_FUNCTION, CALL_FUNCTION, CALL_FUNCTION_KW and BUILD_MAP_UNPACK_WITH_CALL opcodes have been modified, the new CALL_FUNCTION_EX and BUILD_TUPLE_UNPACK_WITH_CALL have been added, and CALL_FUNCTION_VAR, CALL_FUNCTION_VAR_KW and MAKE_CLOSURE opcodes have been removed. (Contributed by Demur Rumed in bpo-27095 [https://bugs.python.org/issue?@action=redirect&bpo=27095], and Serhiy Storchaka in bpo-27213 [https://bugs.python.org/issue?@action=redirect&bpo=27213], bpo-28257 [https://bugs.python.org/issue?@action=redirect&bpo=28257].)

The new SETUP_ANNOTATIONS and STORE_ANNOTATION opcodes have been added to support the new variable annotation syntax. (Contributed by Ivan Levkivskyi in bpo-27985 [https://bugs.python.org/issue?@action=redirect&bpo=27985].)

Notable changes in Python 3.6.2

New make regen-all build target

To simplify cross-compilation, and to ensure that CPython can reliably be compiled without requiring an existing version of Python to already be available, the autotools-based build system no longer attempts to implicitly recompile generated files based on file modification times.

Instead, a new 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 [https://github.com/python/cpython/tree/3.12/Makefile.pre.in] for details.

(Victor Stinner の貢献による bpo-23404 [https://bugs.python.org/issue?@action=redirect&bpo=23404])

Added in version 3.6.2.

Removal of make touch build target

The make touch build target previously used to request implicit regeneration of generated files by updating their modification times has been removed.

It has been replaced by the new make regen-all target.

(Victor Stinner の貢献による bpo-23404 [https://bugs.python.org/issue?@action=redirect&bpo=23404])

バージョン 3.6.2 で変更.

Notable changes in Python 3.6.4

The 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 [https://bugs.python.org/issue?@action=redirect&bpo=22898] and bpo-30697 [https://bugs.python.org/issue?@action=redirect&bpo=30697].)

Notable changes in Python 3.6.5

The locale.localeconv() function now sets temporarily the LC_CTYPE locale to the LC_NUMERIC locale in some cases. (Contributed by Victor Stinner in bpo-31900 [https://bugs.python.org/issue?@action=redirect&bpo=31900].)

Notable changes in Python 3.6.7

xml.dom.minidom and xml.sax modules no longer process external entities by default. See also gh-61441 [https://github.com/python/cpython/issues/61441].

In 3.6.7 the tokenize module now implicitly emits a 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 [https://bugs.python.org/issue?@action=redirect&bpo=33899].)

Notable changes in Python 3.6.10

セキュリティ上の重大な懸念により、asyncio.loop.create_datagram_endpoint() での reuse_address 引数は無効になりました。これはソケットオプション SO_REUSEADDR` のUDP における挙動が原因です。詳しくは、loop.create_datagram_endpoint() のドキュメントを参照してください。(Kyle Stanley, Antoine Pitrou, Yury Selivanov による貢献 bpo-37228 [https://bugs.python.org/issue?@action=redirect&bpo=37228])

Notable changes in Python 3.6.13

Earlier Python versions allowed using both ; and & as query parameter separators in urllib.parse.parse_qs() and 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 & as the default. This change also affects cgi.parse() and 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 [https://bugs.python.org/issue?@action=redirect&bpo=42967].)

Notable changes in Python 3.6.14

A security fix alters the 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 trust_server_pasv_ipv4_address attribute on your FTP instance to True. (See gh-87451 [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 \n, \r and tab \t characters are stripped from the URL by the parser urllib.parse() preventing such attacks. The removal characters are controlled by a new module level variable urllib.parse._UNSAFE_URL_BYTES_TO_REMOVE. (See gh-88048 [https://github.com/python/cpython/issues/88048])

What's New In Python 3.5

エディタ:

Elvis Pranskevichus <elvis@magic.io>, Yury Selivanov <yury@magic.io>

この記事では 3.4 と比較した Python 3.5 の新機能を解説します。 Python 3.5 は2015年9月13日にリリースされました。全詳細については 変更履歴 [https://docs.python.org/3.5/whatsnew/changelog.html] をご覧ください。

参考

PEP 478 [https://peps.python.org/pep-0478/] - Python 3.5 リリーススケジュール

概要 -- リリースハイライト

新たな文法機能:

PEP 492、コルーチン、async 構文と await 構文。

PEP 465、新たな行列乗算演算子 a @ b。

PEP 448、追加可能なアンパックへの一般化。

新たなライブラリモジュール:

typing: PEP 484 -- 型ヒント。

zipapp: PEP 441 Python ZIP アプリケーションのサポートの改善。

新たな組み込み機能:

bytes % args, bytearray % args: PEP 461 -- bytes と bytearray に % 書式化を追加。

新たな bytes.hex(), bytearray.hex() memoryview.hex() メソッド。 (Contributed by Arnon Yaari in bpo-9951 [https://bugs.python.org/issue?@action=redirect&bpo=9951].)

memoryview クラスが、(複数次元の場合を含んだ) タプルの添字をサポートするようになりました。 (bpo-23632 [https://bugs.python.org/issue?@action=redirect&bpo=23632] におけるAntoine Pitrouによる貢献です。)

ジェネレータに gi_yieldfrom 属性が新しく追加され、これは yield from 式で反復処理されるオブジェクトを返します。 (Contributed by Benno Leslie and Yury Selivanov in bpo-24450 [https://bugs.python.org/issue?@action=redirect&bpo=24450].)

新たな例外 RecursionError が最長再帰深度に到達した際に送出されるようになりました。 (Contributed by Georg Brandl in bpo-19235 [https://bugs.python.org/issue?@action=redirect&bpo=19235].)

CPython の実装の改善:

LC_TYPE ロケールが POSIX ロケール (C ロケール) のとき、 sys.stdin および sys.stdout は strict エラーハンドラではなく surrogateescape を使うようになりました。 (Contributed by Victor Stinner in bpo-19977 [https://bugs.python.org/issue?@action=redirect&bpo=19977].)

.pyo ファイルは使われなくなり、.pyc ファイル名に最適化レベルが明示される、より柔軟な仕組みに置き換えられました。(PEP 488 の概要 を参照してください。)

組み込みおよび拡張モジュールが多段階で初期化されるようになりました。これは Python モジュールのロード方法と同じです。 (PEP 489 の概要 を参照してください。)

標準ライブラリーの顕著な改善

collections.OrderedDict が C で実装されました。これにより 4 倍から 100 倍高速になりました。

ssl モジュールに メモリ BIO サポート が追加されました。これにより SSL プロトコルの処理と ネットワーク IO が分離されました。

新たな関数 os.scandir() はディレクトリー走査の 改良され非常に速い方法 を提供します。

functools.lru_cache() の大部分が C で再実装 され、性能が大幅に向上しました。

新たな関数 subprocess.run() は サブプロセスを実行する合理的な方法 を提供します。

traceback モジュールは性能と開発者の利便性が向上し、大いに 強化され ました。

セキュリティの改善:

SSLv3 が標準ライブラリ全体を通じて無効化されました。ただし ssl.SSLContext を手動でインスタンス化することによってなら今でも有効には出来ます。 (詳細に関しては bpo-22638 [https://bugs.python.org/issue?@action=redirect&bpo=22638] を参照してください。この変更は CPython 3.4 と 2.7 にもバックポートされました。)

潜在的なインジェクション攻撃からの防御のために、HTTP クッキーの解析がより厳密に行われるようになりました。 (Contributed by Antoine Pitrou in bpo-22796 [https://bugs.python.org/issue?@action=redirect&bpo=22796].)

Windows の改善:

Windows のインストーラが新しくなり古い MSI を置き換えました。さらに詳しい情報は Windows で Python を使う をご覧ください。

Windows のビルドに Microsoft Visual C++ 14.0 を使うようになっています。拡張モジュールも同じものを使うべきです。

以降は、たくさんのほかの小さな改善、CPython での最適化、非推奨リスト、潜在的な移植性問題を含む、ユーザ向けの変更の包括的なリストになっています。

新しい機能

PEP 492 - コルーチン、 async と await 構文

PEP 492 [https://peps.python.org/pep-0492/] で 待機可能オブジェクト、コルーチン関数、非同期イテレーション、非同期コンテキストマネージャ が追加され、Python における非同期プログラミングを大幅に向上しました。

コルーチン関数は新たな構文 async def を用いて定義されます:

>>> async def coro():
...     return 'spam'

コルーチン関数内で、新たな await 式を用いることで結果が利用可能になるまでコルーチンの実行を停止することが出来ます。__await__() メソッドを定義して awaitable プロトコルを実装する限り、あらゆるオブジェクトは 待機可能 です。

PEP 492 により async for 文も追加されました。非同期イテラブルを反復するのに便利です。

新たな構文を用いた初歩的な HTTP クライアントの例です:

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'', b''
    ]))

    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()

非同期イテレーションと同様に、非同期なコンテキストマネージャの新たな構文があります。以下のスクリプト:

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()

の出力は:

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

async for と async with は両方とも、 async def で宣言されたコルーチン関数内でのみ使えることに注意してください。

コルーチン関数は asyncio loop のような適したイベントループ内で実行させるためのものです。

注釈

バージョン 3.5.2 で変更: CPython 3.5.2 以降では、 __aiter__ は 非同期イテレータ を直接返せます。 awaitable オブジェクトを返すと PendingDeprecationWarning が送出されます。

より詳細なことはドキュメントの 非同期イテレータ (Asynchronous Iterator) 節を参照してください。

参考

PEP 492 [https://peps.python.org/pep-0492/] -- コルーチン、 async 構文と await 構文

PEP written and implemented by Yury Selivanov.

PEP 465 - 行列の乗算専用の中置演算子

PEP 465 [https://peps.python.org/pep-0465/] により @ 行列の乗算のための中置演算子が追加されました。現在のところ Python の型はこの演算子を実装していませんが、__matmul__()、__rmatmul__()、__imatmul__() (それぞれ通常の乗算、反射した乗算、インプレースの乗算) を定義することで実装することが出来ます。これらのメソッドのセマンティクスは他の中置算術演算子のものと類似です。

行列の乗算は数学、科学、工学の多くの分野では非常に一般的です。 @ の追加によりコードをより綺麗に書くことが出来ます:

S = (H @ beta - r).T @ inv(H @ V @ H.T) @ (H @ beta - r)

これはたとえば NumPy を使っても、以下のように書く必要がありました:

S = dot((dot(H, beta) - r).T,
        dot(inv(dot(dot(H, V), H.T)), dot(H, beta) - r))

NumPy 1.10 はこの新たな演算子をサポートしています:

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

参考

PEP 465 [https://peps.python.org/pep-0465/] -- 行列乗算専用の中置演算子

PEP written by Nathaniel J. Smith; implemented by Benjamin Peterson.

PEP 448 - 追加可能なアンパックへの一般化

PEP 448 [https://peps.python.org/pep-0448/] によって、 * イテラブルアンパック演算子と ** 辞書アンパック演算子の利用方法が拡張されました。関数呼び出し で任意の数のアンパックで使えるようになりました:

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

同様に、タプル、リスト、集合、辞書表現でも複数のアンパックが使えます (式のリスト および 辞書表示 を参照してください):

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

参考

PEP 448 [https://peps.python.org/pep-0448/] -- 追加可能なアンパックへの一般化

PEP written by Joshua Landau; implemented by Neil Girdhar, Thomas Wouters, and Joshua Landau.

PEP 461 - bytes および bytearray のパーセント書式化サポート

PEP 461 [https://peps.python.org/pep-0461/] によって、 bytes と bytearray に % 補間演算子 のサポートが追加されます。

補間は通常は文字列演算だと考えられていますが、 bytes や bytearrays 上の補間が意味を持つ場合もあって、この機能が無いと余計な作業が必要になりコードの全体の可読性が損なわれます。この問題は特にワイヤフォーマットプロトコルの取り扱いにおいて重要で、バイナリとASCII互換のテキストが入り交じったものがよく出てきます。

例:

>>> b'Hello %b!' % b'World'
b'Hello World!'

>>> b'x=%i y=%f' % (1, 2.5)
b'x=1 y=2.500000'

Unicode に対して %b は使えませんが、 %a であれば使えます (repr(obj).encode('ascii', 'backslashreplace') と同等):

>>> 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'"

%s および %r 変換型はサポートはされますが、 Python 2 との互換性を持たせる必要のあるコードベースでのみ使われるべきだということに注意してください。

参考

PEP 461 [https://peps.python.org/pep-0461/] -- bytes と bytearray への % 書式化の追加

PEP written by Ethan Furman; implemented by Neil Schemenauer and Ethan Furman.

PEP 484 - 型ヒント

関数アノテーション構文はバージョン 3.0 (PEP 3107 [https://peps.python.org/pep-3107/]) から Python の仕様になりましたが、アノテーションのセマンティクスは未定義のままでした。

経験的に、関数アノテーションの使用の大半は関数の引数と返り値の型ヒントを提供するためのものです。標準ライブラリーが型アノテーションの基本的な定義とツールを持てば、Python ユーザに有益であることは明白となりました。

PEP 484 [https://peps.python.org/pep-0484/] introduces a provisional module to provide these standard definitions and tools, along with some conventions for situations where annotations are not available.

例えば、こちらは引数と返り値の型がアノテーションで定義されている簡単な関数です:

def greeting(name: str) -> str:
    return 'Hello ' + name

While these annotations are available at runtime through the usual __annotations__ attribute, no automatic type checking happens at runtime. Instead, it is assumed that a separate off-line type checker (e.g. mypy [https://mypy-lang.org]) will be used for on-demand source code analysis.

型システムはユニオン、一般型、そして Any という全ての型と互換な (すなわち代入可能) 特殊型をサポートしています。

参考

typing モジュールのドキュメント

PEP 484 [https://peps.python.org/pep-0484/] -- 型ヒント

PEP 著 Guido van Rossum, Jukka Lehtosalo, Łukasz Langa; 実装 Guido van Rossum。

PEP 483 [https://peps.python.org/pep-0483/] -- 型ヒントの理論

PEP written by Guido van Rossum

PEP 471 - os.scandir() 関数 -- より良く、速いディレクトリイテレータ

PEP 471 [https://peps.python.org/pep-0471/] により新しいディレクトリ反復関数 os.scandir() が標準ライブラリへ追加されました。さらに、 scandir を使い os.walk() が実装され、 POSIX システムで3倍から5倍、 Windows システムで7倍から20倍高速になりました。これは主に、ディレクトリツリーを走査するのに必要な os.stat() の呼び出し回数をかなり減らしたことによるものです。

これの他にも、 scandir ファイル名のリストではなくイテレータを返すようになり、非常に大きなディレクトリ群の走査をするときのメモリ効率が改善されました。

次の例では、 os.scandir() を使用して、与えられた path 内の先頭が '.' でないすべてのファイル (ディレクトリを除く) を表示します。 entry.is_file() を呼び出しても、通常は追加のシステムコールは行われません:

for entry in os.scandir(path):
    if not entry.name.startswith('.') and entry.is_file():
        print(entry.name)

参考

PEP 471 [https://peps.python.org/pep-0471/] -- os.scandir() 関数 -- より良く、速いディレクトリイテレータ

PEP 著・実装 Ben Hoyt 補佐 Victor Stinner。

PEP 475: EINTR で失敗したシステムコールの再試行

An 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 InterruptedError in such cases. This meant that, when writing a Python application, the developer had two choices:

InterruptedError を無視する。

呼び出し箇所の全てで InterruptedError を処理し、中断されたシステムコールの再開を試みる。

最初の選択肢では、アプリケーションは断続的に失敗します。二つ目の選択肢では、定型処理を大量に追加せねばならず、コードの可読性が著しく下がります。次の2つを比べてみてください:

print("Hello World")

および:

while True:
    try:
        print("Hello World")
        break
    except InterruptedError:
        continue

PEP 475 [https://peps.python.org/pep-0475/] は EINTR を受けた場合のシステムコールの自動再試行を実装しています。これはほとんどの場合ユーザコードでの EINTR や InterruptedError を扱う負担をなくし、標準ライブラリを含む Python プログラムをより堅牢にします。シグナルハンドラが例外を投げない場合にのみシステムコールを再試行することに注意してください。

下記は、シグナルで中断された際に再試行をするようになった関数のリストです:

open() および io.open();

faulthandler モジュールの関数;

os モジュールの関数: fchdir(), fchmod(), fchown(), fdatasync(), fstat(), fstatvfs(), fsync(), ftruncate(), mkfifo(), mknod(), open(), posix_fadvise(), posix_fallocate(), pread(), pwrite(), read(), readv(), sendfile(), wait3(), wait4(), wait(), waitid(), waitpid(), write(), writev();

special cases: os.close() and os.dup2() now ignore EINTR errors; the syscall is not retried (see the PEP for the rationale);

select モジュール関数: devpoll.poll(), epoll.poll(), kqueue.control(), poll.poll(), select();

socket クラスのメソッド: accept(), connect() (ノンブロッキングソケットを除く), recv(), recvfrom(), recvmsg(), send(), sendall(), sendmsg(), sendto();

signal.sigtimedwait() および signal.sigwaitinfo();

time.sleep().

参考

PEP 475 [https://peps.python.org/pep-0475/] -- EINTR で失敗したシステムコールの再試行

Antoine Pitrou の協力のもと、 PEP および実装は Charles-François Natali と Victor Stinner によって書かれました (『フレンチ・コネクション』)。

PEP 479: ジェネレータ内の StopIteration の処理の変更

Python 3.4 以前では、ジェネレータと StopIteration の組み合わせが驚くような動作をし、分かりづらいバグを隠すことがありました。以前は、ジェネレータ関数内でうっかり StopIteration が送出されると、そのジェネレータの反復処理をしているループ構造が終端に達したと解釈されていました。

PEP 479 [https://peps.python.org/pep-0479/] によってジェネレータのこの振る舞いが変更されました: ジェネレータ内部で StopIteration 例外が送出されたときは、ジェネレータのフレームを抜ける前に RuntimeError に置き換えられます。この変更の一番の目的は、保護されていない next() の呼び出しが StopIteration を送出し、ジェネレータを回している反復処理が黙って終了してしまうような状況で、デバッグをしやすくすることです。これは yield from 構造と組み合わさったとき特に有害になります。

これは後方互換性の無い変更ですので、この新しい振る舞いを有効にするには __future__ のインポートが必要です:

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

__future__ をインポートしておらず、ジェネレータの内部で StopIteration 例外が送出されたときには PendingDeprecationWarning が送出されます。

参考

PEP 479 [https://peps.python.org/pep-0479/] -- ジェネレータ内の StopIteration の処理の変更

PEP written by Chris Angelico and Guido van Rossum. Implemented by Chris Angelico, Yury Selivanov and Nick Coghlan.

PEP 485: 近似的に等しいことを調べる関数

PEP 485 [https://peps.python.org/pep-0485/] により、2値が互いに近似的に等しいか "近い" ことを調べる関数 math.isclose() 及び cmath.isclose() が追加されました。 2値が近いと判断されるかどうかは与えられた絶対及び相対許容差で決まります。相対許容差は isclose 引数間で許される、絶対値の大きい方に対する最大の差です:

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

2値を絶対許容差で比較することも出来ます。絶対許容差は非負数でなければなりません:

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

参考

PEP 485 [https://peps.python.org/pep-0485/] -- A function for testing approximate equality

PEP written by Christopher Barker; implemented by Chris Barker and Tal Einat.

PEP 486: Python ランチャーが仮想環境を認識する

PEP 486 [https://peps.python.org/pep-0486/] により、 Windows ランチャー (PEP 397 [https://peps.python.org/pep-0397/] を参照してください) が有効になっている仮想環境を認識するようになりました。デフォルトのインタプリタを使っていて、 VIRTUAL_ENV 環境変数が設定されているときは、仮想環境のインタプリタが使われます。

参考

PEP 486 [https://peps.python.org/pep-0486/] -- Python ランチャーが仮想環境を認識する

PEP written and implemented by Paul Moore.

PEP 488: PYO ファイルの廃止

PEP 488 [https://peps.python.org/pep-0488/] は .pyo ファイルという概念を廃止しました。つまり、.pyc ファイルは最適化されていないバイトコードと最適化されたバイトコードの両方を指すということです。バイトコードファイルを何度も再生成する必要がないよう、バイトコードが最適化されたときは .pyc ファイルは任意の opt- タグを名前に持つようになりました。この副作用で、-O と -OO のいずれかで実行した場合でも、バイトコードのファイル名が衝突しないようになりました。それにより、-O および -OO で生成したバイトコードは同時に存在できるようになりました。 importlib.util.cache_from_source() にの API は更新され、この変更に役立ちます。

参考

PEP 488 [https://peps.python.org/pep-0488/] -- PYO ファイルの廃止

PEP written and implemented by Brett Cannon.

PEP 489: 拡張モジュールの多段階初期化

PEP 489 [https://peps.python.org/pep-0489/] により拡張モジュールの初期化方式が更新され、 Python 3.4 で PEP 451 [https://peps.python.org/pep-0451/] によって導入された2段階でモジュールを読み込む仕組みが活用できるようになりました。

この変更によって、新しい仕組みを使うことを選択した拡張モジュールのインポートの動作が、 Python のソースコードやバイトコードでできたモジュールにかなり近くなり、これまで ASCII に制限されていたモジュール名に任意の識別子が使えるようになりました。

参考

PEP 489 [https://peps.python.org/pep-0489/] -- 拡張モジュールの多段階初期化

PEP 著 Petr Viktorin, Stefan Behnel, Nick Coghlan; 実装 Petr Viktorin.

その他の言語変更

Python 言語コアに小さな変更がいくつか行われました:

"namereplace" エラーハンドラが追加されました。"backslashreplace" エラーハンドラはデコードと変換で動くようになりました。 (Contributed by Serhiy Storchaka in bpo-19676 [https://bugs.python.org/issue?@action=redirect&bpo=19676] and bpo-22286 [https://bugs.python.org/issue?@action=redirect&bpo=22286].)

-b オプションが bytes と int の比較に影響するようになりました。 (Contributed by Serhiy Storchaka in bpo-23681 [https://bugs.python.org/issue?@action=redirect&bpo=23681].)

新たなカザフ語 kz1048 及びタジク語 koi8_t コーデックス。 (Contributed by Serhiy Storchaka in bpo-22682 [https://bugs.python.org/issue?@action=redirect&bpo=22682] and bpo-22681 [https://bugs.python.org/issue?@action=redirect&bpo=22681].)

プロパティのドキュメンテーション文字列が書き込み可能になりました。これは特に collections.namedtuple() のドキュメンテーション文字列で有用です。 (Contributed by Berker Peksag in bpo-24064 [https://bugs.python.org/issue?@action=redirect&bpo=24064].)

相対インポートに関する循環インポートがサポートされました。(Contributed by Brett Cannon and Antoine Pitrou in bpo-17636 [https://bugs.python.org/issue?@action=redirect&bpo=17636].)

新たなモジュール

typing

The new typing provisional module provides standard definitions and tools for function type annotations. See Type Hints for more information.

zipapp

新たな zipapp モジュール (PEP 441 [https://peps.python.org/pep-0441/] で仕様定義) は実行可能な Python Zip アプリケーションを作成するための API とコマンドラインツールを提供します。 Python Zip アプリケーションは Python 2.6 の bpo-1739468 [https://bugs.python.org/issue?@action=redirect&bpo=1739468] で導入されましたが、それ以降もあまり知られていませんでした。

この新しいモジュールを使ったアプリケーションのバンドル方法は単純で、 __main__.py ファイルを含む全てのファイルをディレクトリ myapp に置き、次のように実行します:

$ python -m zipapp myapp
$ python myapp.pyz

モジュールの実装は bpo-23491 [https://bugs.python.org/issue?@action=redirect&bpo=23491] の Paul Moore による貢献です。

参考

PEP 441 [https://peps.python.org/pep-0441/] -- Python ZIP アプリケーションのサポートの改善 <whatsnew-zipapp>`

改良されたモジュール

argparse

ArgumentParser クラスは、allow_abbrev を False に設定することでロングオプションの 短縮使用 を無効化できるようになりました。 (Contributed by Jonathan Paugh, Steven Bethard, paul j3 and Daniel Eriksson in bpo-14910 [https://bugs.python.org/issue?@action=redirect&bpo=14910].)

asyncio

Since the asyncio module is provisional, all changes introduced in Python 3.5 have also been backported to Python 3.4.x.

Python 3.4.0 以後の asyncio モジュールの重要な変更点:

新たなデバッグ API: loop.set_debug() と loop.get_debug() メソッド。 (Contributed by Victor Stinner.)

proactor イベントループが SSL をサポートしました。 (Contributed by Antoine Pitrou and Victor Stinner in bpo-22560 [https://bugs.python.org/issue?@action=redirect&bpo=22560].)

イベントループが閉じているかどうか調べる新たな loop.is_closed() メソッド。 (Contributed by Victor Stinner in bpo-21326 [https://bugs.python.org/issue?@action=redirect&bpo=21326].)

コルーチンの新しい Task を便利に作成しスケジュールするための新たな loop.create_task()。 create_task メソッドはコルーチンをタスクにラップする全ての asyncio 関数、たとえば asyncio.wait(), asyncio.gather()、にも使われます。 (Contributed by Victor Stinner.)

A new transport.get_write_buffer_limits() method to inquire for high- and low- water limits of the flow control. (Contributed by Victor Stinner.)

async() 関数は ensure_future() により非推奨になりました。(Contributed by Yury Selivanov.)

loop.create_task() メソッドが使うタスクファクトリーをカスタマイズするための新たな loop.set_task_factory() メソッドと loop.get_task_factory() メソッド。 (Yury Selivanovによる貢献。)

新たな Queue.join() および Queue.task_done() キューメソッド。(Contributed by Victor Stinner.)

JoinableQueue クラスは asyncio.Queue クラスにより削除されました。 (Contributed by Victor Stinner.)

3.5.1 での変更:

The ensure_future() function and all functions that use it, such as loop.run_until_complete(), now accept all kinds of awaitable objects. (Contributed by Yury Selivanov.)

他のスレッドからコルーチンをイベントループに送信するための新たな run_coroutine_threadsafe() 関数。 (Contributed by Vincent Michel.)

New Transport.is_closing() method to check if the transport is closing or closed. (Contributed by Yury Selivanov.)

The loop.create_server() method can now accept a list of hosts. (Contributed by Yann Sionneau.)

3.5.2 での変更:

New loop.create_future() method to create Future objects. This allows alternative event loop implementations, such as uvloop [https://github.com/MagicStack/uvloop], to provide a faster asyncio.Future implementation. (Contributed by Yury Selivanov.)

New loop.get_exception_handler() method to get the current exception handler. (Contributed by Yury Selivanov.)

新しい StreamReader.readuntil() メソッドで、区切りとなるバイトの並びが出てくるまでストリームからデータを読み取れるようになりました。 (Contributed by Mark Korenberg.)

The loop.create_connection() and loop.create_server() methods are optimized to avoid calling the system getaddrinfo function if the address is already resolved. (Contributed by A. Jesse Jiryu Davis.)

The loop.sock_connect(sock, address) no longer requires the address to be resolved prior to the call. (Contributed by A. Jesse Jiryu Davis.)

bz2

BZ2Decompressor.decompress メソッドがオプション引数 max_length を取れるようになり、展開されたデータの最大サイズが制限できるようになりました。 (Contributed by Nikolaus Rath in bpo-15955 [https://bugs.python.org/issue?@action=redirect&bpo=15955].)

cgi

The FieldStorage class now supports the context manager protocol. (Contributed by Berker Peksag in bpo-20289 [https://bugs.python.org/issue?@action=redirect&bpo=20289].)

cmath

新たな関数 isclose() は近似的に等しいかどうかを判断する方法を提供します。 (Contributed by Chris Barker and Tal Einat in bpo-24270 [https://bugs.python.org/issue?@action=redirect&bpo=24270].)

コード

InteractiveInterpreter.showtraceback() メソッドが、対話的インタープリタのように連なったスタックトレース全体を表示するようになりました。 (Contributed by Claudiu Popa in bpo-17442 [https://bugs.python.org/issue?@action=redirect&bpo=17442].)

collections

collections.OrderedDict が C で実装されました。これにより 4倍 から 100 倍高速になりました。 (Contributed by Eric Snow in bpo-16991 [https://bugs.python.org/issue?@action=redirect&bpo=16991].)

OrderedDict.items(), OrderedDict.keys(), OrderedDict.values() ビューが reversed() イテレーションをサポートしました。 (Contributed by Serhiy Storchaka in bpo-19505 [https://bugs.python.org/issue?@action=redirect&bpo=19505].)

deque クラスが index()、 insert()、 copy() を定義し、+ と * 演算をサポートしました。これにより deque インスタンスは MutableSequence と認識され、list との代替性が向上しました。 (Contributed by Raymond Hettinger in bpo-23704 [https://bugs.python.org/issue?@action=redirect&bpo=23704].)

namedtuple() で生成されたドキュメンテーション文字列が更新可能となりました:

Point = namedtuple('Point', ['x', 'y'])
Point.__doc__ += ': Cartesian coordinate'
Point.x.__doc__ = 'abscissa'
Point.y.__doc__ = 'ordinate'

(Contributed by Berker Peksag in bpo-24064 [https://bugs.python.org/issue?@action=redirect&bpo=24064].)

The UserString class now implements the __getnewargs__(), __rmod__(), casefold(), format_map(), isprintable(), and maketrans() methods to match the corresponding methods of str. (Contributed by Joe Jevnik in bpo-22189 [https://bugs.python.org/issue?@action=redirect&bpo=22189].)

collections.abc

The Sequence.index() method now accepts start and stop arguments to match the corresponding methods of tuple, list, etc. (Contributed by Devin Jeanpierre in bpo-23086 [https://bugs.python.org/issue?@action=redirect&bpo=23086].)

新たに Generator 抽象基底クラスが追加されました。 (Contributed by Stefan Behnel in bpo-24018 [https://bugs.python.org/issue?@action=redirect&bpo=24018].)

新たに Awaitable, Coroutine, AsyncIterator, AsyncIterable 抽象基底クラスが追加されました。 (Contributed by Yury Selivanov in bpo-24184 [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 [https://pypi.org/project/backports_abc/].

compileall

A new compileall option, -j N, allows running N workers simultaneously to perform parallel bytecode compilation. The compile_dir() function has a corresponding workers parameter. (Contributed by Claudiu Popa in bpo-16104 [https://bugs.python.org/issue?@action=redirect&bpo=16104].)

Another new option, -r, allows controlling the maximum recursion level for subdirectories. (Contributed by Claudiu Popa in bpo-19628 [https://bugs.python.org/issue?@action=redirect&bpo=19628].)

The -q command line option can now be specified more than once, in which case all output, including errors, will be suppressed. The corresponding quiet parameter in compile_dir(), compile_file(), and compile_path() can now accept an integer value indicating the level of output suppression. (Contributed by Thomas Kluyver in bpo-21338 [https://bugs.python.org/issue?@action=redirect&bpo=21338].)

concurrent.futures

The Executor.map() method now accepts a chunksize argument to allow batching of tasks to improve performance when ProcessPoolExecutor() is used. (Contributed by Dan O'Reilly in bpo-11271 [https://bugs.python.org/issue?@action=redirect&bpo=11271].)

The number of workers in the ThreadPoolExecutor constructor is optional now. The default value is 5 times the number of CPUs. (Contributed by Claudiu Popa in bpo-21527 [https://bugs.python.org/issue?@action=redirect&bpo=21527].)

configparser

configparser now provides a way to customize the conversion of values by specifying a dictionary of converters in the ConfigParser constructor, or by defining them as methods in ConfigParser subclasses. Converters defined in a parser instance are inherited by its section proxies.

以下はプログラム例です:

>>> 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']

(Contributed by Łukasz Langa in bpo-18159 [https://bugs.python.org/issue?@action=redirect&bpo=18159].)

contextlib

新規 context manager の contextlib.redirect_stderr() は、ユーティリティスクリプトにて、その出力を sys.stderr に書き出す一方でその向き先を変えれない頑固な API の扱いを簡単にしてくれます (redirect_stdout() と対となるものです)。:

>>> import contextlib, io, logging
>>> f = io.StringIO()
>>> with contextlib.redirect_stderr(f):
...     logging.warning('warning')
...
>>> f.getvalue()
'WARNING:root:warning\n'

(Contributed by Berker Peksag in bpo-22389 [https://bugs.python.org/issue?@action=redirect&bpo=22389].)

csv

writerow() メソッドは、シーケンスだけでなく、 任意のイテラブルをサポートしました。(Contributed by Serhiy Storchaka in bpo-23171 [https://bugs.python.org/issue?@action=redirect&bpo=23171].)

curses

The new update_lines_cols() function updates the LINES and COLS module variables. This is useful for detecting manual screen resizing. (Contributed by Arnon Yaari in bpo-4254 [https://bugs.python.org/issue?@action=redirect&bpo=4254].)

dbm

dumb.open always creates a new database when the flag has the value "n". (Contributed by Claudiu Popa in bpo-18039 [https://bugs.python.org/issue?@action=redirect&bpo=18039].)

difflib

The charset of HTML documents generated by HtmlDiff.make_file() can now be customized by using a new charset keyword-only argument. The default charset of HTML document changed from "ISO-8859-1" to "utf-8". (Contributed by Berker Peksag in bpo-2052 [https://bugs.python.org/issue?@action=redirect&bpo=2052].)

The 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 [https://bugs.python.org/issue?@action=redirect&bpo=17445].)

distutils

Both the build and build_ext commands now accept a -j option to enable parallel building of extension modules. (Contributed by Antoine Pitrou in bpo-5309 [https://bugs.python.org/issue?@action=redirect&bpo=5309].)

The distutils module now supports xz compression, and can be enabled by passing xztar as an argument to bdist --format. (Contributed by Serhiy Storchaka in bpo-16314 [https://bugs.python.org/issue?@action=redirect&bpo=16314].)

doctest

DocTestSuite() 関数が、 module がドキュメンテーション文字列(docstrings)を含まない場合に ValueError を送出するのではなく空の unittest.TestSuite を返すようになりました。 (Contributed by Glenn Jones in bpo-15916 [https://bugs.python.org/issue?@action=redirect&bpo=15916].)

email

A new policy option Policy.mangle_from_ controls whether or not lines that start with "From " in email bodies are prefixed with a ">" character by generators. The default is True for compat32 and False for all other policies. (Contributed by Milan Oberkirch in bpo-20098 [https://bugs.python.org/issue?@action=redirect&bpo=20098].)

A new Message.get_content_disposition() method provides easy access to a canonical value for the Content-Disposition header. (Contributed by Abhilash Raj in bpo-21083 [https://bugs.python.org/issue?@action=redirect&bpo=21083].)

A new policy option EmailPolicy.utf8 can be set to True to encode email headers using the UTF-8 charset instead of using encoded words. This allows Messages to be formatted according to RFC 6532 [https://datatracker.ietf.org/doc/html/rfc6532.html] and used with an SMTP server that supports the RFC 6531 [https://datatracker.ietf.org/doc/html/rfc6531.html] SMTPUTF8 extension. (Contributed by R. David Murray in bpo-24211 [https://bugs.python.org/issue?@action=redirect&bpo=24211].)

The mime.text.MIMEText constructor now accepts a charset.Charset instance. (Contributed by Claude Paroz and Berker Peksag in bpo-16324 [https://bugs.python.org/issue?@action=redirect&bpo=16324].)

enum

Enum 呼び出し可能オブジェクトは、names のみが与えられた場合に enum 値の初期値を指定する新たな引数 start を持ちます:

>>> Animal = enum.Enum('Animal', 'cat dog', start=10)
>>> Animal.cat
<Animal.cat: 10>
>>> Animal.dog
<Animal.dog: 11>

(Contributed by Ethan Furman in bpo-21706 [https://bugs.python.org/issue?@action=redirect&bpo=21706].)

faulthandler

関数 enable(), register(), dump_traceback(), dump_traceback_later() が、ファイル様オブジェクトだけでなくファイル記述子を受け取るようになりました。 (Contributed by Wei Wu in bpo-23566 [https://bugs.python.org/issue?@action=redirect&bpo=23566].)

functools

lru_cache() 機構の多くが C で実装されました。これにより速度が大幅に向上しました。 (Contributed by Matt Joiner, Alexey Kachayev, and Serhiy Storchaka in bpo-14373 [https://bugs.python.org/issue?@action=redirect&bpo=14373].)

glob

iglob() 関数と glob() 関数は、 "**" パターンを使ったサブディレクトリの再帰的な検索をサポートしました。(Contributed by Serhiy Storchaka in bpo-13968 [https://bugs.python.org/issue?@action=redirect&bpo=13968].)

gzip

GzipFile コンストラクタの mode 引数が排他的作成を要求する "x" を受け取るようになりました。 (Contributed by Tim Heaney in bpo-19222 [https://bugs.python.org/issue?@action=redirect&bpo=19222].)

heapq

Element comparison in merge() can now be customized by passing a key function in a new optional key keyword argument, and a new optional reverse keyword argument can be used to reverse element comparison:

>>> 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']

(Contributed by Raymond Hettinger in bpo-13742 [https://bugs.python.org/issue?@action=redirect&bpo=13742].)

http

新しい HTTPStatus のenum は、HTTPステータスコードのセットで、その理由句と詳細な説明は、英語で記載されています。(Contributed by Demian Brecht in bpo-21793 [https://bugs.python.org/issue?@action=redirect&bpo=21793].)

http.client

HTTPConnection.getresponse() now raises a RemoteDisconnected exception when a remote server connection is closed unexpectedly. Additionally, if a ConnectionError (of which RemoteDisconnected is a subclass) is raised, the client socket is now closed automatically, and will reconnect on the next request:

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

(Contributed by Martin Panter in bpo-3566 [https://bugs.python.org/issue?@action=redirect&bpo=3566].)

idlelib と IDLE

idlelib は IDLE シェルとエディタを実装するものであってほかのプログラムからインポートされることを意図してはいないので、改善は毎度のリリースごとに行われます。3.4.0 から始まり、また将来の 3.5.x リリースになされる累積的な変更リストは Lib/idlelib/NEWS.txt で読むことが出来ます。このファイルは IDLE で Help ‣ About IDLE からも辿り着けます。

imaplib

IMAP4 クラスが context manager プロトコルをサポートするようになりました。 with 文とともに使うと、 IMAP4 LOGOUT コマンドがブロックの終了時に自動的に呼び出されます。 (Contributed by Tarek Ziadé and Serhiy Storchaka in bpo-4972 [https://bugs.python.org/issue?@action=redirect&bpo=4972].)

The imaplib module now supports RFC 5161 [https://datatracker.ietf.org/doc/html/rfc5161.html] (ENABLE Extension) and RFC 6855 [https://datatracker.ietf.org/doc/html/rfc6855.html] (UTF-8 Support) via the IMAP4.enable() method. A new IMAP4.utf8_enabled attribute tracks whether or not RFC 6855 [https://datatracker.ietf.org/doc/html/rfc6855.html] support is enabled. (Contributed by Milan Oberkirch, R. David Murray, and Maciej Szulik in bpo-21800 [https://bugs.python.org/issue?@action=redirect&bpo=21800].)

The 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 [https://bugs.python.org/issue?@action=redirect&bpo=21800].)

imghdr

The what() function now recognizes the OpenEXR [https://www.openexr.com] format (contributed by Martin Vignali and Claudiu Popa in bpo-20295 [https://bugs.python.org/issue?@action=redirect&bpo=20295]), and the WebP [https://en.wikipedia.org/wiki/WebP] format (contributed by Fabrice Aneche and Claudiu Popa in bpo-20197 [https://bugs.python.org/issue?@action=redirect&bpo=20197].)

importlib

The util.LazyLoader class allows for lazy loading of modules in applications where startup time is important. (Contributed by Brett Cannon in bpo-17621 [https://bugs.python.org/issue?@action=redirect&bpo=17621].)

The 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 exec(code, module.__dict__). (Contributed by Brett Cannon in bpo-21156 [https://bugs.python.org/issue?@action=redirect&bpo=21156].)

The new util.module_from_spec() function is now the preferred way to create a new module. As opposed to creating a 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 [https://bugs.python.org/issue?@action=redirect&bpo=20383].)

inspect

Both the Signature and Parameter classes are now picklable and hashable. (Contributed by Yury Selivanov in bpo-20726 [https://bugs.python.org/issue?@action=redirect&bpo=20726] and bpo-20334 [https://bugs.python.org/issue?@action=redirect&bpo=20334].)

A new BoundArguments.apply_defaults() method provides a way to set default values for missing arguments:

>>> def foo(a, b='ham', *args): pass
>>> ba = inspect.signature(foo).bind('spam')
>>> ba.apply_defaults()
>>> ba.arguments
OrderedDict([('a', 'spam'), ('b', 'ham'), ('args', ())])

(Contributed by Yury Selivanov in bpo-24190 [https://bugs.python.org/issue?@action=redirect&bpo=24190].)

A new class method Signature.from_callable() makes subclassing of Signature easier. (Contributed by Yury Selivanov and Eric Snow in bpo-17373 [https://bugs.python.org/issue?@action=redirect&bpo=17373].)

The signature() function now accepts a follow_wrapped optional keyword argument, which, when set to False, disables automatic following of __wrapped__ links. (Contributed by Yury Selivanov in bpo-20691 [https://bugs.python.org/issue?@action=redirect&bpo=20691].)

A set of new functions to inspect coroutine functions and coroutine objects has been added: iscoroutine(), iscoroutinefunction(), isawaitable(), getcoroutinelocals(), and getcoroutinestate(). (Contributed by Yury Selivanov in bpo-24017 [https://bugs.python.org/issue?@action=redirect&bpo=24017] and bpo-24400 [https://bugs.python.org/issue?@action=redirect&bpo=24400].)

The stack(), trace(), getouterframes(), and getinnerframes() functions now return a list of named tuples. (Contributed by Daniel Shahaf in bpo-16808 [https://bugs.python.org/issue?@action=redirect&bpo=16808].)

io

A new BufferedIOBase.readinto1() method, that uses at most one call to the underlying raw stream's RawIOBase.read() or RawIOBase.readinto() methods. (Contributed by Nikolaus Rath in bpo-20578 [https://bugs.python.org/issue?@action=redirect&bpo=20578].)

ipaddress

Both the IPv4Network and IPv6Network classes now accept an (address, netmask) tuple argument, so as to easily construct network objects from existing addresses:

>>> 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')

(Contributed by Peter Moody and Antoine Pitrou in bpo-16531 [https://bugs.python.org/issue?@action=redirect&bpo=16531].)

A new reverse_pointer attribute for the IPv4Network and IPv6Network classes returns the name of the reverse DNS PTR record:

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

(Contributed by Leon Weber in bpo-20480 [https://bugs.python.org/issue?@action=redirect&bpo=20480].)

json

The json.tool command line interface now preserves the order of keys in JSON objects passed in input. The new --sort-keys option can be used to sort the keys alphabetically. (Contributed by Berker Peksag in bpo-21650 [https://bugs.python.org/issue?@action=redirect&bpo=21650].)

JSON decoder now raises JSONDecodeError instead of ValueError to provide better context information about the error. (Contributed by Serhiy Storchaka in bpo-19361 [https://bugs.python.org/issue?@action=redirect&bpo=19361].)

linecache

A new lazycache() function can be used to capture information about a non-file-based module to permit getting its lines later via 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 [https://bugs.python.org/issue?@action=redirect&bpo=17911].)

locale

A new delocalize() function can be used to convert a string into a normalized number string, taking the LC_NUMERIC settings into account:

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

(Contributed by Cédric Krier in bpo-13918 [https://bugs.python.org/issue?@action=redirect&bpo=13918].)

logging

All logging methods (Logger log(), exception(), critical(), debug(), etc.), now accept exception instances as an exc_info argument, in addition to boolean values and exception tuples:

>>> import logging
>>> try:
...     1/0
... except ZeroDivisionError as ex:
...     logging.error('exception', exc_info=ex)
ERROR:root:exception

(Contributed by Yury Selivanov in bpo-20537 [https://bugs.python.org/issue?@action=redirect&bpo=20537].)

The handlers.HTTPHandler class now accepts an optional ssl.SSLContext instance to configure SSL settings used in an HTTP connection. (Contributed by Alex Gaynor in bpo-22788 [https://bugs.python.org/issue?@action=redirect&bpo=22788].)

The handlers.QueueListener class now takes a respect_handler_level keyword argument which, if set to True, will pass messages to handlers taking handler levels into account. (Contributed by Vinay Sajip.)

lzma

The 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 [https://bugs.python.org/issue?@action=redirect&bpo=15955].)

math

math モジュールに定数 inf および nan が追加されました。 (Contributed by Mark Dickinson in bpo-23185 [https://bugs.python.org/issue?@action=redirect&bpo=23185].)

新たな関数 isclose() は近似的に等しいことを調べる方法を提供します。 (Contributed by Chris Barker and Tal Einat in bpo-24270 [https://bugs.python.org/issue?@action=redirect&bpo=24270].)

新たに関数 gcd() が追加されました。関数 fractions.gcd() は非推奨です。 (Contributed by Mark Dickinson and Serhiy Storchaka in bpo-22486 [https://bugs.python.org/issue?@action=redirect&bpo=22486].)

multiprocessing

sharedctypes.synchronized() オブジェクトが コンテキストマネージャ プロトコルをサポートするようになりました。 (Contributed by Charles-François Natali in bpo-21565 [https://bugs.python.org/issue?@action=redirect&bpo=21565].)

operator

attrgetter(), itemgetter(), and methodcaller() objects now support pickling. (Contributed by Josh Rosenberg and Serhiy Storchaka in bpo-22955 [https://bugs.python.org/issue?@action=redirect&bpo=22955].)

行列乗算を行う matmul() 関数と imatmul() 関数が新しく追加されました。 (Contributed by Benjamin Peterson in bpo-21176 [https://bugs.python.org/issue?@action=redirect&bpo=21176].)

os

The new scandir() function returning an iterator of DirEntry objects has been added. If possible, 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 [https://bugs.python.org/issue?@action=redirect&bpo=22524].)

Windows において、新たに stat_result.st_file_attributes 属性が利用可能です。これは Windows API の GetFileInformationByHandle() から返る BY_HANDLE_FILE_INFORMATION 構造体のメンバ dwFileAttributes に対応します。 (Contributed by Ben Hoyt in bpo-21719 [https://bugs.python.org/issue?@action=redirect&bpo=21719].)

urandom() 関数が、Linux 3.17 以降ではシステムコール getrandom() を、OpenBSD 5.6 以降ではシステムコール getentropy() を使うようになりました。これは /dev/urandom を使う必要性をなくし、潜在的には起こり得たファイル記述子を使い果たすことによる失敗を避けることに繋がります。 (Contributed by Victor Stinner in bpo-22181 [https://bugs.python.org/issue?@action=redirect&bpo=22181].)

New get_blocking() and set_blocking() functions allow getting and setting a file descriptor's blocking mode (O_NONBLOCK.) (Contributed by Victor Stinner in bpo-22054 [https://bugs.python.org/issue?@action=redirect&bpo=22054].)

truncate() と ftruncate() が Windows でサポートされるようになりました。 (Contributed by Steve Dower in bpo-23668 [https://bugs.python.org/issue?@action=redirect&bpo=23668].)

There is a new os.path.commonpath() function returning the longest common sub-path of each passed pathname. Unlike the os.path.commonprefix() function, it always returns a valid path:

>>> os.path.commonprefix(['/usr/lib', '/usr/local/lib'])
'/usr/l'

>>> os.path.commonpath(['/usr/lib', '/usr/local/lib'])
'/usr'

(Contributed by Rafik Draoui and Serhiy Storchaka in bpo-10395 [https://bugs.python.org/issue?@action=redirect&bpo=10395].)

pathlib

The new Path.samefile() method can be used to check whether the path points to the same file as another path, which can be either another Path object, or a string:

>>> import pathlib
>>> p1 = pathlib.Path('/etc/hosts')
>>> p2 = pathlib.Path('/etc/../etc/hosts')
>>> p1.samefile(p2)
True

(Contributed by Vajrasky Kok and Antoine Pitrou in bpo-19775 [https://bugs.python.org/issue?@action=redirect&bpo=19775].)

The Path.mkdir() method now accepts a new optional exist_ok argument to match mkdir -p and os.makedirs() functionality. (Contributed by Berker Peksag in bpo-21539 [https://bugs.python.org/issue?@action=redirect&bpo=21539].)

There is a new Path.expanduser() method to expand ~ and ~user prefixes. (Contributed by Serhiy Storchaka and Claudiu Popa in bpo-19776 [https://bugs.python.org/issue?@action=redirect&bpo=19776].)

A new Path.home() class method can be used to get a Path instance representing the user’s home directory. (Contributed by Victor Salgado and Mayank Tripathi in bpo-19777 [https://bugs.python.org/issue?@action=redirect&bpo=19777].)

New Path.write_text(), Path.read_text(), Path.write_bytes(), Path.read_bytes() methods to simplify read/write operations on files.

The following code snippet will create or rewrite existing file ~/spam42:

>>> import pathlib
>>> p = pathlib.Path('~/spam42')
>>> p.expanduser().write_text('ham')
3

(Contributed by Christopher Welborn in bpo-20218 [https://bugs.python.org/issue?@action=redirect&bpo=20218].)

pickle

Nested objects, such as unbound methods or nested classes, can now be pickled using pickle protocols older than protocol version 4. Protocol version 4 already supports these cases. (Contributed by Serhiy Storchaka in bpo-23611 [https://bugs.python.org/issue?@action=redirect&bpo=23611].)

poplib

A new POP3.utf8() command enables RFC 6856 [https://datatracker.ietf.org/doc/html/rfc6856.html] (Internationalized Email) support, if a POP server supports it. (Contributed by Milan OberKirch in bpo-21804 [https://bugs.python.org/issue?@action=redirect&bpo=21804].)

re

References and conditional references to groups with fixed length are now allowed in lookbehind assertions:

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

(Contributed by Serhiy Storchaka in bpo-9179 [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 [https://bugs.python.org/issue?@action=redirect&bpo=22437].)

The sub() and subn() functions now replace unmatched groups with empty strings instead of raising an exception. (Contributed by Serhiy Storchaka in bpo-1519638 [https://bugs.python.org/issue?@action=redirect&bpo=1519638].)

The re.error exceptions have new attributes, msg, pattern, pos, lineno, and colno, that provide better context information about the error:

>>> re.compile("""
...     (?x)
...     .++
... """)
Traceback (most recent call last):
   ...
sre_constants.error: multiple repeat at position 16 (line 3, column 7)

(Contributed by Serhiy Storchaka in bpo-22578 [https://bugs.python.org/issue?@action=redirect&bpo=22578].)

readline

A new 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 [https://bugs.python.org/issue?@action=redirect&bpo=22940].)

selectors

The new DevpollSelector supports efficient /dev/poll polling on Solaris. (Contributed by Giampaolo Rodola' in bpo-18931 [https://bugs.python.org/issue?@action=redirect&bpo=18931].)

shutil

The move() function now accepts a copy_function argument, allowing, for example, the copy() function to be used instead of the default copy2() if there is a need to ignore file metadata when moving. (Contributed by Claudiu Popa in bpo-19840 [https://bugs.python.org/issue?@action=redirect&bpo=19840].)

The make_archive() function now supports the xztar format. (Contributed by Serhiy Storchaka in bpo-5411 [https://bugs.python.org/issue?@action=redirect&bpo=5411].)

signal

Windows において、 set_wakeup_fd() 関数がソケットハンドルもサポートするようになりました。 (Contributed by Victor Stinner in bpo-22018 [https://bugs.python.org/issue?@action=redirect&bpo=22018].)

Various SIG* constants in the signal module have been converted into Enums. This allows meaningful names to be printed during debugging, instead of integer "magic numbers". (Contributed by Giampaolo Rodola' in bpo-21076 [https://bugs.python.org/issue?@action=redirect&bpo=21076].)

smtpd

Both the SMTPServer and SMTPChannel classes now accept a decode_data keyword argument to determine if the DATA portion of the SMTP transaction is decoded using the "utf-8" codec or is instead provided to the SMTPServer.process_message() method as a byte string. The default is True for backward compatibility reasons, but will change to False in Python 3.6. If decode_data is set to False, the process_message method must be prepared to accept keyword arguments. (Contributed by Maciej Szulik in bpo-19662 [https://bugs.python.org/issue?@action=redirect&bpo=19662].)

The SMTPServer class now advertises the 8BITMIME extension (RFC 6152 [https://datatracker.ietf.org/doc/html/rfc6152.html]) if decode_data has been set True. If the client specifies BODY=8BITMIME on the MAIL command, it is passed to SMTPServer.process_message() via the mail_options keyword. (Contributed by Milan Oberkirch and R. David Murray in bpo-21795 [https://bugs.python.org/issue?@action=redirect&bpo=21795].)

The SMTPServer class now also supports the SMTPUTF8 extension (RFC 6531 [https://datatracker.ietf.org/doc/html/rfc6531.html]: Internationalized Email). If the client specified SMTPUTF8 BODY=8BITMIME on the MAIL command, they are passed to SMTPServer.process_message() via the mail_options keyword. It is the responsibility of the process_message method to correctly handle the SMTPUTF8 data. (Contributed by Milan Oberkirch in bpo-21725 [https://bugs.python.org/issue?@action=redirect&bpo=21725].)

It is now possible to provide, directly or via name resolution, IPv6 addresses in the SMTPServer constructor, and have it successfully connect. (Contributed by Milan Oberkirch in bpo-14758 [https://bugs.python.org/issue?@action=redirect&bpo=14758].)

smtplib

A new SMTP.auth() method provides a convenient way to implement custom authentication mechanisms. (Contributed by Milan Oberkirch in bpo-15014 [https://bugs.python.org/issue?@action=redirect&bpo=15014].)

The 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 [https://bugs.python.org/issue?@action=redirect&bpo=16914].)

Both the SMTP.sendmail() and SMTP.send_message() methods now support RFC 6531 [https://datatracker.ietf.org/doc/html/rfc6531.html] (SMTPUTF8). (Contributed by Milan Oberkirch and R. David Murray in bpo-22027 [https://bugs.python.org/issue?@action=redirect&bpo=22027].)

sndhdr

The what() and whathdr() functions now return a namedtuple(). (Contributed by Claudiu Popa in bpo-18615 [https://bugs.python.org/issue?@action=redirect&bpo=18615].)

socket

Functions with timeouts now use a monotonic clock, instead of a system clock. (Contributed by Victor Stinner in bpo-22043 [https://bugs.python.org/issue?@action=redirect&bpo=22043].)

A new socket.sendfile() method allows sending a file over a socket by using the high-performance os.sendfile() function on UNIX, resulting in uploads being from 2 to 3 times faster than when using plain socket.send(). (Contributed by Giampaolo Rodola' in bpo-17552 [https://bugs.python.org/issue?@action=redirect&bpo=17552].)

The 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 [https://bugs.python.org/issue?@action=redirect&bpo=23853].)

The backlog argument of the socket.listen() method is now optional. By default it is set to SOMAXCONN or to 128, whichever is less. (Contributed by Charles-François Natali in bpo-21455 [https://bugs.python.org/issue?@action=redirect&bpo=21455].)

ssl

メモリ BIO サポート

(Contributed by Geert Jansen in bpo-21965 [https://bugs.python.org/issue?@action=redirect&bpo=21965].)

The new SSLObject class has been added to provide SSL protocol support for cases when the network I/O capabilities of SSLSocket are not necessary or are suboptimal. SSLObject represents an SSL protocol instance, but does not implement any network I/O methods, and instead provides a memory buffer interface. The new 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 SSLSocket's readiness model ("select/poll") is inefficient.

A new SSLContext.wrap_bio() method can be used to create a new SSLObject instance.

Application-Layer Protocol Negotiation Support

(Contributed by Benjamin Peterson in bpo-20188 [https://bugs.python.org/issue?@action=redirect&bpo=20188].)

Where OpenSSL support is present, the ssl module now implements the Application-Layer Protocol Negotiation TLS extension as described in RFC 7301 [https://datatracker.ietf.org/doc/html/rfc7301.html].

The new SSLContext.set_alpn_protocols() can be used to specify which protocols a socket should advertise during the TLS handshake.

The new SSLSocket.selected_alpn_protocol() returns the protocol that was selected during the TLS handshake. The HAS_ALPN flag indicates whether ALPN support is present.

その他の変更

There is a new SSLSocket.version() method to query the actual protocol version in use. (Contributed by Antoine Pitrou in bpo-20421 [https://bugs.python.org/issue?@action=redirect&bpo=20421].)

The SSLSocket class now implements a SSLSocket.sendfile() method. (Contributed by Giampaolo Rodola' in bpo-17552 [https://bugs.python.org/issue?@action=redirect&bpo=17552].)

The SSLSocket.send() method now raises either the ssl.SSLWantReadError or ssl.SSLWantWriteError exception on a non-blocking socket if the operation would block. Previously, it would return 0. (Contributed by Nikolaus Rath in bpo-20951 [https://bugs.python.org/issue?@action=redirect&bpo=20951].)

The cert_time_to_seconds() function now interprets the input time as UTC and not as local time, per RFC 5280 [https://datatracker.ietf.org/doc/html/rfc5280.html]. Additionally, the return value is always an int. (Contributed by Akira Li in bpo-19940 [https://bugs.python.org/issue?@action=redirect&bpo=19940].)

New SSLObject.shared_ciphers() and SSLSocket.shared_ciphers() methods return the list of ciphers sent by the client during the handshake. (Contributed by Benjamin Peterson in bpo-23186 [https://bugs.python.org/issue?@action=redirect&bpo=23186].)

The SSLSocket.do_handshake(), SSLSocket.read(), SSLSocket.shutdown(), and SSLSocket.write() methods of the 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 [https://bugs.python.org/issue?@action=redirect&bpo=23853].)

The match_hostname() function now supports matching of IP addresses. (Contributed by Antoine Pitrou in bpo-23239 [https://bugs.python.org/issue?@action=redirect&bpo=23239].)

sqlite3

The Row class now fully supports the sequence protocol, in particular reversed() iteration and slice indexing. (Contributed by Claudiu Popa in bpo-10203 [https://bugs.python.org/issue?@action=redirect&bpo=10203]; by Lucas Sinclair, Jessica McKellar, and Serhiy Storchaka in bpo-13583 [https://bugs.python.org/issue?@action=redirect&bpo=13583].)

subprocess

新たに run() 関数が追加されました。 run() は指定されたコマンドを実行し CompletedProcess オブジェクトを返します。オブジェクトは終了したプロセスを記述します。新たな API はより一貫的で、古いバージョンとの互換性を必要としない Python コードでサブプロセスを起動するのに推奨される方法です。 (Contributed by Thomas Kluyver in bpo-23342 [https://bugs.python.org/issue?@action=redirect&bpo=23342].)

例:

>>> subprocess.run(["ls", "-l"])  # doesn't capture output
CompletedProcess(args=['ls', '-l'], returncode=0)

>>> subprocess.run("exit 1", shell=True, check=True)
Traceback (most recent call last):
  ...
subprocess.CalledProcessError: Command 'exit 1' returned non-zero exit status 1

>>> subprocess.run(["ls", "-l", "/dev/null"], stdout=subprocess.PIPE)
CompletedProcess(args=['ls', '-l', '/dev/null'], returncode=0,
stdout=b'crw-rw-rw- 1 root root 1, 3 Jan 23 16:23 /dev/null\n')

sys

A new set_coroutine_wrapper() function allows setting a global hook that will be called whenever a coroutine object is created by an async def function. A corresponding get_coroutine_wrapper() can be used to obtain a currently set wrapper. Both functions are provisional, and are intended for debugging purposes only. (Contributed by Yury Selivanov in bpo-24017 [https://bugs.python.org/issue?@action=redirect&bpo=24017].)

A new is_finalizing() function can be used to check if the Python interpreter is shutting down. (Contributed by Antoine Pitrou in bpo-22696 [https://bugs.python.org/issue?@action=redirect&bpo=22696].)

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 [https://bugs.python.org/issue?@action=redirect&bpo=23437].)

tarfile

open() 関数の mode 引数が排他的作成を要求する "x" を受け取るようになりました。 (Contributed by Berker Peksag in bpo-21717 [https://bugs.python.org/issue?@action=redirect&bpo=21717].)

The TarFile.extractall() and TarFile.extract() methods now take a keyword argument numeric_owner. If set to True, the extracted files and directories will be owned by the numeric uid and gid from the tarfile. If set to 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 [https://bugs.python.org/issue?@action=redirect&bpo=23193].)

The TarFile.list() now accepts an optional members keyword argument that can be set to a subset of the list returned by TarFile.getmembers(). (Contributed by Serhiy Storchaka in bpo-21549 [https://bugs.python.org/issue?@action=redirect&bpo=21549].)

threading

Lock.acquire() と RLock.acquire() の両メソッドがタイムアウトの管理に単調時計を使用するようになりました。 (Contributed by Victor Stinner in bpo-22043 [https://bugs.python.org/issue?@action=redirect&bpo=22043].)

time

monotonic() 関数が常に利用出来るようになりました。 (Contributed by Victor Stinner in bpo-22043 [https://bugs.python.org/issue?@action=redirect&bpo=22043].)

timeit

新たなコマンドラインオプション -u 又は --unit=U を使用してタイマーの出力の単位を指定できます。サポートされたオプションは usec, msec, sec です。 (Contributed by Julian Gindi in bpo-18983 [https://bugs.python.org/issue?@action=redirect&bpo=18983].)

timeit() 関数に引数 globals が追加されました。これによりコードが実行される名前空間を指定します。 (Contributed by Ben Roberts in bpo-2527 [https://bugs.python.org/issue?@action=redirect&bpo=2527].)

tkinter

The tkinter._fix module used for setting up the Tcl/Tk environment on Windows has been replaced by a private function in the _tkinter module which makes no permanent changes to environment variables. (Contributed by Zachary Ware in bpo-20035 [https://bugs.python.org/issue?@action=redirect&bpo=20035].)

traceback

New walk_stack() and walk_tb() functions to conveniently traverse frame and traceback objects. (Contributed by Robert Collins in bpo-17911 [https://bugs.python.org/issue?@action=redirect&bpo=17911].)

New lightweight classes: TracebackException, StackSummary, and FrameSummary. (Contributed by Robert Collins in bpo-17911 [https://bugs.python.org/issue?@action=redirect&bpo=17911].)

Both the print_tb() and print_stack() functions now support negative values for the limit argument. (Contributed by Dmitry Kazakov in bpo-22619 [https://bugs.python.org/issue?@action=redirect&bpo=22619].)

types

新たに coroutine() 関数が追加されました。ジェネレータ と ジェネレータ様 オブジェクトを awaitable に変換します。 (Contributed by Yury Selivanov in bpo-24017 [https://bugs.python.org/issue?@action=redirect&bpo=24017].)

新たに型 CoroutineType が追加されました。 async def 関数で作られた coroutine オブジェクトに使われます。 (Contributed by Yury Selivanov in bpo-24400 [https://bugs.python.org/issue?@action=redirect&bpo=24400].)

unicodedata

The unicodedata module now uses data from Unicode 8.0.0 [https://unicode.org/versions/Unicode8.0.0/].

unittest

The TestLoader.loadTestsFromModule() method now accepts a keyword-only argument pattern which is passed to load_tests as the third argument. Found packages are now checked for 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 [https://bugs.python.org/issue?@action=redirect&bpo=16662].)

Unittest discovery errors now are exposed in the TestLoader.errors attribute of the TestLoader instance. (Contributed by Robert Collins in bpo-19746 [https://bugs.python.org/issue?@action=redirect&bpo=19746].)

A new command line option --locals to show local variables in tracebacks. (Contributed by Robert Collins in bpo-22936 [https://bugs.python.org/issue?@action=redirect&bpo=22936].)

unittest.mock

Mock クラスは、次の改善が行われました。

The class constructor has a new unsafe parameter, which causes mock objects to raise AttributeError on attribute names starting with "assert". (Contributed by Kushal Das in bpo-21238 [https://bugs.python.org/issue?@action=redirect&bpo=21238].)

A new Mock.assert_not_called() method to check if the mock object was called. (Contributed by Kushal Das in bpo-21262 [https://bugs.python.org/issue?@action=redirect&bpo=21262].)

The MagicMock class now supports __truediv__(), __divmod__() and __matmul__() operators. (Contributed by Johannes Baiter in bpo-20968 [https://bugs.python.org/issue?@action=redirect&bpo=20968], and Håkan Lövdahl in bpo-23581 [https://bugs.python.org/issue?@action=redirect&bpo=23581] and bpo-23568 [https://bugs.python.org/issue?@action=redirect&bpo=23568].)

It is no longer necessary to explicitly pass create=True to the patch() function when patching builtin names. (Contributed by Kushal Das in bpo-17660 [https://bugs.python.org/issue?@action=redirect&bpo=17660].)

urllib

A new request.HTTPPasswordMgrWithPriorAuth class allows HTTP Basic Authentication credentials to be managed so as to eliminate unnecessary 401 response handling, or to unconditionally send credentials on the first request in order to communicate with servers that return a 404 response instead of a 401 if the Authorization header is not sent. (Contributed by Matej Cepl in bpo-19494 [https://bugs.python.org/issue?@action=redirect&bpo=19494] and Akshit Khurana in bpo-7159 [https://bugs.python.org/issue?@action=redirect&bpo=7159].)

A new quote_via argument for the parse.urlencode() function provides a way to control the encoding of query parts if needed. (Contributed by Samwyse and Arnon Yaari in bpo-13866 [https://bugs.python.org/issue?@action=redirect&bpo=13866].)

The request.urlopen() function accepts an ssl.SSLContext object as a context argument, which will be used for the HTTPS connection. (Contributed by Alex Gaynor in bpo-22366 [https://bugs.python.org/issue?@action=redirect&bpo=22366].)

The parse.urljoin() was updated to use the RFC 3986 [https://datatracker.ietf.org/doc/html/rfc3986.html] semantics for the resolution of relative URLs, rather than RFC 1808 [https://datatracker.ietf.org/doc/html/rfc1808.html] and RFC 2396 [https://datatracker.ietf.org/doc/html/rfc2396.html]. (Contributed by Demian Brecht and Senthil Kumaran in bpo-22118 [https://bugs.python.org/issue?@action=redirect&bpo=22118].)

wsgiref

The headers argument of the headers.Headers class constructor is now optional. (Contributed by Pablo Torres Navarrete and SilentGhost in bpo-5800 [https://bugs.python.org/issue?@action=redirect&bpo=5800].)

xmlrpc

client.ServerProxy クラスが コンテキストマネージャ プロトコルをサポートするようになりました。 (Contributed by Claudiu Popa in bpo-20627 [https://bugs.python.org/issue?@action=redirect&bpo=20627].)

client.ServerProxy コンストラクタは任意の ssl.SSLContext インスタンスを受け取るようになりました。 (Contributed by Alex Gaynor in bpo-22960 [https://bugs.python.org/issue?@action=redirect&bpo=22960].)

xml.sax

SAX パーサは xmlreader.InputSource オブジェクトの文字ストリームをサポートしました。 (Contributed by Serhiy Storchaka in bpo-2175 [https://bugs.python.org/issue?@action=redirect&bpo=2175].)

parseString() が str インスタンスを受け取るようになりました。 (Contributed by Serhiy Storchaka in bpo-10590 [https://bugs.python.org/issue?@action=redirect&bpo=10590].)

zipfile

ZIP output can now be written to unseekable streams. (Contributed by Serhiy Storchaka in bpo-23252 [https://bugs.python.org/issue?@action=redirect&bpo=23252].)

ZipFile.open() メソッドの mode 引数が排他的作成を要求する "x" を受け取るようになりました。 (Contributed by Serhiy Storchaka in bpo-21717 [https://bugs.python.org/issue?@action=redirect&bpo=21717].)

その他のモジュールレベルの変更

Many functions in the mmap, ossaudiodev, socket, ssl, and codecs modules now accept writable bytes-like objects. (Contributed by Serhiy Storchaka in bpo-23001 [https://bugs.python.org/issue?@action=redirect&bpo=23001].)

最適化

The 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 os.scandir() function, which exposes file information from the underlying readdir or FindFirstFile/FindNextFile system calls. (Contributed by Ben Hoyt with help from Victor Stinner in bpo-23605 [https://bugs.python.org/issue?@action=redirect&bpo=23605].)

Construction of bytes(int) (filled by zero bytes) is faster and uses less memory for large objects. calloc() is used instead of malloc() to allocate memory for these objects. (Contributed by Victor Stinner in bpo-21233 [https://bugs.python.org/issue?@action=redirect&bpo=21233].)

Some operations on ipaddress IPv4Network and IPv6Network have been massively sped up, such as subnets(), supernet(), summarize_address_range(), collapse_addresses(). The speed up can range from 3 to 15 times. (Contributed by Antoine Pitrou, Michel Albert, and Markus in bpo-21486 [https://bugs.python.org/issue?@action=redirect&bpo=21486], bpo-21487 [https://bugs.python.org/issue?@action=redirect&bpo=21487], bpo-20826 [https://bugs.python.org/issue?@action=redirect&bpo=20826], bpo-23266 [https://bugs.python.org/issue?@action=redirect&bpo=23266].)

Pickling of ipaddress objects was optimized to produce significantly smaller output. (Contributed by Serhiy Storchaka in bpo-23133 [https://bugs.python.org/issue?@action=redirect&bpo=23133].)

io.BytesIO の多くの操作が 50% から 100% 速くなりました。 (Contributed by Serhiy Storchaka in bpo-15381 [https://bugs.python.org/issue?@action=redirect&bpo=15381] and David Wilson in bpo-22003 [https://bugs.python.org/issue?@action=redirect&bpo=22003].)

The 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 [https://bugs.python.org/issue?@action=redirect&bpo=20416] and bpo-23344 [https://bugs.python.org/issue?@action=redirect&bpo=23344].)

UTF-32 エンコーダが 3 から 7 倍速くなりました。 (Contributed by Serhiy Storchaka in bpo-15027 [https://bugs.python.org/issue?@action=redirect&bpo=15027].)

正規表現のパースが最高で 10% 速くなりました。 (Contributed by Serhiy Storchaka in bpo-19380 [https://bugs.python.org/issue?@action=redirect&bpo=19380].)

The json.dumps() function was optimized to run with ensure_ascii=False as fast as with ensure_ascii=True. (Contributed by Naoki Inada in bpo-23206 [https://bugs.python.org/issue?@action=redirect&bpo=23206].)

The PyObject_IsInstance() and PyObject_IsSubclass() functions have been sped up in the common case that the second argument has type as its metaclass. (Contributed Georg Brandl by in bpo-22540 [https://bugs.python.org/issue?@action=redirect&bpo=22540].)

メソッドのキャッシュが少し改良されました。ベンチマークによっては性能が最高で 5% 向上しました。 (Contributed by Antoine Pitrou in bpo-22847 [https://bugs.python.org/issue?@action=redirect&bpo=22847].)

random モジュールのオブジェクトのメモリ使用量が 64-bit ビルドで 50% 減少しました。 (Contributed by Serhiy Storchaka in bpo-23488 [https://bugs.python.org/issue?@action=redirect&bpo=23488].)

property() ゲッタの呼び出しが最高で 25% 速くなりました。 (Contributed by Joe Jevnik in bpo-23910 [https://bugs.python.org/issue?@action=redirect&bpo=23910].)

fractions.Fraction のインスタンス化が最高で 30% 速くなりました。 (Contributed by Stefan Behnel in bpo-22464 [https://bugs.python.org/issue?@action=redirect&bpo=22464].)

String methods find(), rfind(), split(), partition() and the in string operator are now significantly faster for searching 1-character substrings. (Contributed by Serhiy Storchaka in bpo-23573 [https://bugs.python.org/issue?@action=redirect&bpo=23573].)

ビルドならびに C API の変更

新たな calloc 関数が追加されました:

PyMem_RawCalloc(),

PyMem_Calloc(),

PyObject_Calloc().

(Contributed by Victor Stinner in bpo-21233 [https://bugs.python.org/issue?@action=redirect&bpo=21233].)

新たなエンコーディング/デコーディングヘルパ関数:

Py_DecodeLocale() (_Py_char2wchar() の代わり),

Py_EncodeLocale() (_Py_wchar2char() の代わり).

(Contributed by Victor Stinner in bpo-18395 [https://bugs.python.org/issue?@action=redirect&bpo=18395].)

A new PyCodec_NameReplaceErrors() function to replace the unicode encode error with \N{...} escapes. (Contributed by Serhiy Storchaka in bpo-19676 [https://bugs.python.org/issue?@action=redirect&bpo=19676].)

A new PyErr_FormatV() function similar to PyErr_Format(), but accepts a va_list argument. (Contributed by Antoine Pitrou in bpo-18711 [https://bugs.python.org/issue?@action=redirect&bpo=18711].)

A new PyExc_RecursionError exception. (Contributed by Georg Brandl in bpo-19235 [https://bugs.python.org/issue?@action=redirect&bpo=19235].)

New PyModule_FromDefAndSpec(), PyModule_FromDefAndSpec2(), and PyModule_ExecDef() functions introduced by PEP 489 [https://peps.python.org/pep-0489/] -- multi-phase extension module initialization. (Contributed by Petr Viktorin in bpo-24268 [https://bugs.python.org/issue?@action=redirect&bpo=24268].)

New PyNumber_MatrixMultiply() and PyNumber_InPlaceMatrixMultiply() functions to perform matrix multiplication. (Contributed by Benjamin Peterson in bpo-21176 [https://bugs.python.org/issue?@action=redirect&bpo=21176]. See also PEP 465 [https://peps.python.org/pep-0465/] for details.)

The PyTypeObject.tp_finalize slot is now part of the stable ABI.

Windows builds now require Microsoft Visual C++ 14.0, which is available as part of Visual Studio 2015 [https://visualstudio.microsoft.com/en/vs/older-downloads/#visual-studio-2015-and-other-products].

いくつかのプラットフォームにおいて、拡張モジュールのファイル名にプラットフォームについての情報をタグとして含むようになりました (タグはオプショナルであり、CPython は、タグが含まれていて実行しようとしているプラットフォームとミスマッチな場合にその拡張をロードしようとしない一方で、拡張をそれが含まれていなくてもインポートします):

Linux では拡張モジュールのファイル名は .cpython-<major><minor>m-<architecture>-<os>.pyd で終わります:

<major> は Python バージョンのメジャー番号です。Python 3.5 では 3 です。

<minor> は Python バージョンのマイナー番号です。Python 3.5 では 5 です。

<architecture> は拡張モジュールがどのハードウェアアーキテクチャ向けに動作するようビルドされたのかを表します。32-bit Intel プラットフォーム向けの i386 か 64-bit Intel (及び AMD) プラットフォーム向けの x86_64 がもっとも一般的です。

<os> は原則として linux-gnu ですが、64-bit プラットフォームにおいて 32-bit ABI で動作するようビルドされた拡張モジュールの場合は linux-gnu32 になります (この場合 <architecture> は x86_64 となるでしょう)。

Windows では拡張モジュールのファイル名は <debug>.cp<major><minor>-<platform>.pyd で終わります:

<major> は Python バージョンのメジャー番号です。Python 3.5 では 3 です。

<minor> は Python バージョンのマイナー番号です。Python 3.5 では 5 です。

<platform> は拡張モジュールがどのプラットフォーム向けにビルドされたものなのかを表し、 Win32 用の win32 , Win64 用の win_amd64 , Windows Itanium 64 用の win_ia64 , Windows on ARM 用の win_arm のいずれかです。

デバッグモードでビルドされた場合は <debug> は _d となり、それ以外の場合はブランクです。

OS X プラットフォームでは拡張モジュールのファイル名は -darwin.so で終わります。

他のすべてのプラットフォームでは、拡張モジュールのファイル名は Python 3.4 でのものと同じです。

非推奨

新たなキーワード

async および await を変数、クラス、関数、ならびにモジュールの名前に使用することは推奨されません。それらは Python 3.5 で PEP 492 [https://peps.python.org/pep-0492/] により導入され、Python 3.7 で正式にキーワードになります。

非推奨の Python の挙動

ジェネレータ内で StopIteration 例外を送出すると現在は静かな PendingDeprecationWarning が発生します。これは、Python 3.6 では静かでない非推奨の警告となり、Python 3.7 では RuntimeError を起こします。詳細は PEP 479: Change StopIteration handling inside generators を参照してください。

サポートされないオペレーティングシステム

Windows XP は Microsoft によって既にサポートされていません。このため PEP 11 [https://peps.python.org/pep-0011/] により、CPython 3.5 ではこの OS をもはや公式にはサポートしません。

非推奨の Python モジュール、関数、メソッド

formatter モジュールは完全に非推奨になり、Python 3.6 で削除される予定です。

asyncio.async() 関数は ensure_future() により非推奨になりました。

The smtpd module has in the past always decoded the DATA portion of email messages using the utf-8 codec. This can now be controlled by the new decode_data keyword to SMTPServer. The default value is True, but this default is deprecated. Specify the decode_data keyword with an appropriate value to avoid the deprecation warning.

http.cookies.Morsel オブジェクトの key, value, coded_value に対して直接代入することは非推奨です。 set() メソッドを使うようにしてください。また、 set() のドキュメントされていなかった LegalChars パラメータは非推奨となり、無視されます。

string.Formatter クラスの format() メソッドに対し、キーワード引数 format_string としてフォーマット文字列を渡すことは非推奨となりました。 (Contributed by Serhiy Storchaka in bpo-23671 [https://bugs.python.org/issue?@action=redirect&bpo=23671].)

関数 platform.dist() と platform.linux_distribution() が非推奨となりました。Linux ディストリビューションが自分自身を記述する方法があまりにも多様なため、この機能は外部パッケージに任せることとなりました(訳注: ここでは distro [https://github.com/nir0s/distro] のことを指している)。 (Contributed by Vajrasky Kok and Berker Peksag in bpo-1322 [https://bugs.python.org/issue?@action=redirect&bpo=1322].)

inspect.Signature の、以前からドキュメントされていなかったメソッド from_function と from_builtin は非推奨です。新しい Signature.from_callable() を代わりに使ってください。 (Contributed by Yury Selivanov in bpo-24248 [https://bugs.python.org/issue?@action=redirect&bpo=24248].)

inspect.getargspec() 関数は非推奨となり、Python 3.6 で削除されることが予定されています。 (See bpo-20438 [https://bugs.python.org/issue?@action=redirect&bpo=20438] for details.)

The inspect getfullargspec(), getcallargs(), and formatargspec() functions are deprecated in favor of the inspect.signature() API. (Contributed by Yury Selivanov in bpo-20438 [https://bugs.python.org/issue?@action=redirect&bpo=20438].)

getargvalues() and formatargvalues() functions were inadvertently marked as deprecated with the release of Python 3.5.0.

str のパターンとともに re.LOCALE や re.ASCII フラグを使用することは非推奨となりました。 (Contributed by Serhiy Storchaka in bpo-22407 [https://bugs.python.org/issue?@action=redirect&bpo=22407].)

'\' と ASCII 文字からなる認識出来ない特殊シーケンスが正規表現内と置き換えパターン内で使われた場合に、非推奨警告を出すようになりました。Python 3.6 では禁止されるようになります。 (Contributed by Serhiy Storchaka in bpo-23622 [https://bugs.python.org/issue?@action=redirect&bpo=23622].)

unittest.TestLoader.loadTestsFromModule() メソッドのドキュメントされておらず非公式の use_load_tests デフォルト引数は非推奨となり、無視されます。 (Contributed by Robert Collins and Barry A. Warsaw in bpo-16662 [https://bugs.python.org/issue?@action=redirect&bpo=16662].)

削除

API と機能の削除

時代遅れとなり、以前に既に非推奨となった以下の API と機能が削除されました:

email パッケージの __version__ 属性は削除されました。email パッケージが標準ライブラリとは別々にリリースされていたのは遥か昔の話であり、ここのところ何回かのリリースにいたっては __version__ 文字列が更新されていませんでした。

3.4 で非推奨となっていた ftplib モジュール内の内部クラス Netrc が削除されました。 (Contributed by Matt Chaput in bpo-6623 [https://bugs.python.org/issue?@action=redirect&bpo=6623].)

.pyo ファイルのコンセプトは削除されました。

暫定 asyncio モジュールで 3.4.4 で非推奨となった JoinableQueue は削除されました。 (Contributed by A. Jesse Jiryu Davis in bpo-23464 [https://bugs.python.org/issue?@action=redirect&bpo=23464].)

Python 3.5 への移植

このセクションでは前述の変更とバグフィックスにより必要となるかもしれないコードの変更を列挙します:

Python の挙動の変更

以前のバージョンの Python で、誤って以下の構文を許容してしまっていました:

f(1 for x in [1], *args)
f(1 for x in [1], **kwargs)

Python 3.5 は正しく SyntaxError を投げます。ジェネレータ式は関数への唯一の引数でない場合には、括弧で囲まなければならないのです。(---訳注: 一応。3.5 以前も ff(str(i) for i in range(5), "5") は SyntaxError です。上の例の通り gg(str(i) for i in range(5), *["1", "2"]) や hh(str(i) for i in range(5), **{"k1": "1", "k2": "2"}) が SytaxError ではなかった、という話です。---)

Python API の変更

PEP 475 [https://peps.python.org/pep-0475/]: Python シグナルハンドラが例外を送出しなければ、システムコールがシグナルに中断された場合に、 InterruptedError を送出せずにシステムコールを再試行するようになりました。

Python 3.5 以前は、 time オブジェクトは UTC で深夜を表すときに偽とみなされていました。この挙動は分かりにくく、エラーの元となると考えられ、Python 3.5 で削除されました。全詳細については bpo-13936 [https://bugs.python.org/issue?@action=redirect&bpo=13936] を参照してください。

ssl.SSLSocket.send() メソッドは非ブロッキングソケット使用時にオペレーションがブロックされると、 ssl.SSLWantReadError か ssl.SSLWantWriteError のどちらかを送出するようになりました。以前は 0 を返していました。 (Contributed by Nikolaus Rath in bpo-20951 [https://bugs.python.org/issue?@action=redirect&bpo=20951].)

ジェネレータの __name__ 属性の値として、以前は code オブジェクトの名前から取っていましたが、関数名からセットされるようになりました。code の方が所望の場合は gen.gi_code.co_name から取得してください。ジェネレータは新たに __qualname__ 属性も持つようになりました。これはジェネレータの正規名であり、ジェネレータの表現をする際 (repr(gen)) にこれを用いるようになりました。 (Contributed by Victor Stinner in bpo-21205 [https://bugs.python.org/issue?@action=redirect&bpo=21205].)

The deprecated "strict" mode and argument of HTMLParser, HTMLParser.error(), and the HTMLParserError exception have been removed. (Contributed by Ezio Melotti in bpo-15114 [https://bugs.python.org/issue?@action=redirect&bpo=15114].) The convert_charrefs argument of HTMLParser is now True by default. (Contributed by Berker Peksag in bpo-21047 [https://bugs.python.org/issue?@action=redirect&bpo=21047].)

API の公式な部分とは言えないものの、移植性への考慮のために (つまりテストの修正) に、エラーメッセージの変更に注意を払っておいてください。かつて "'sometype' does not support the buffer protocol" の形だったものが、いまでは "a bytes-like object is required, not 'sometype'" の形になっています。 (Contributed by Ezio Melotti in bpo-16518 [https://bugs.python.org/issue?@action=redirect&bpo=16518].)

既に存在していないディレクトリをカレントディレクトリとして指していた場合に、 find_spec() は以前は FileNotFoundError 例外を送出していましたが、そうではなく None を返却するようになりました。この際 sys.path_importer_cache に None を キャッシュはしません 。これは典型的なケースとは違います(訳注: msg231477 [https://bugs.python.org/issue22834#msg231477])。 (bpo-22834 [https://bugs.python.org/issue?@action=redirect&bpo=22834])

http.client モジュールと http.server モジュールに散らばっていた HTTP ステータスコードと対応するメッセージを、共通の HTTPStatus enum としてまとめ直しました。http.client 、 http.server にあったもとの値も後方互換性のために残してあります。 (Contributed by Demian Brecht in bpo-21793 [https://bugs.python.org/issue?@action=redirect&bpo=21793].)

インポートローダが importlib.machinery.Loader.exec_module() を定義する場合は、同時に create_module() も定義されていることを要求するように変更されました (今のところ DeprecationWarning となりますが、Python 3.6 ではエラーとなります)。ローダが importlib.abc.Loader を継承していれば特にこの変更の影響を受けることはありません。そうでないならば、 None を返すだけの create_module() を定義してください。 (Contributed by Brett Cannon in bpo-23014 [https://bugs.python.org/issue?@action=redirect&bpo=23014].)

re.split() 関数は常に空のパターンマッチを無視してきました。ですからパターン "x*" はパターン "x+" と同じように動作し、パターン "\b" は決して動作しませんでした。今後は re.split() はパターンが空文字列に合致しうる場合に警告を出します。互換性のためには空文字列とはマッチしえないパターンを使ってください(たとえば "x*" ではなく "x+" を使ってください)。空文字列としかマッチしえないパターン(例えば "\b")はエラーとなります。 (Contributed by Serhiy Storchaka in bpo-22818 [https://bugs.python.org/issue?@action=redirect&bpo=22818].)

http.cookies.Morsel 辞書風インターフェイスのそれ自身での一貫性を持たせるようにしました: morsel の比較に key と value を考慮するようにし、 copy() は dict を返さずに Morsel インスタンスを返すようにし、 update() は更新する辞書内のいずれかのキーが不正(訳注: RFC 2109 [https://datatracker.ietf.org/doc/html/rfc2109.html] として不正なキーのことで、update 以外のインターフェイスでは変更前も拒絶される)であれば例外を投げるようにしています。加えて、ドキュメントされていない set() の LegalChars パラメータは非推奨となり、また指定しても無視されます。 (Contributed by Demian Brecht in bpo-2211 [https://bugs.python.org/issue?@action=redirect&bpo=2211].)

PEP 488 [https://peps.python.org/pep-0488/] has removed .pyo files from Python and introduced the optional opt- tag in .pyc file names. The importlib.util.cache_from_source() has gained an optimization parameter to help control the opt- tag. Because of this, the debug_override parameter of the function is now deprecated. .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 .pyo files from previous versions of Python are invalid regardless of this PEP.

The socket module now exports the CAN_RAW_FD_FRAMES constant on linux 3.6 and greater.

RFC 5280 [https://datatracker.ietf.org/doc/html/rfc5280.html] に基づき、 ssl.cert_time_to_seconds() 関数が入力の時刻をローカル時刻ではなく UTC として解釈するようになりました。また、戻り値は常に int となります。 (Contributed by Akira Li in bpo-19940 [https://bugs.python.org/issue?@action=redirect&bpo=19940].)

pygettext.py ツールが POT-Creation-Date ヘッダ内のタイムゾーン形式として、標準の +NNNN 形式を使うようになりました。

smtplib モジュールは以前はデバッグ出力のためにモジュールレベルの stderr 変数を使っていましたが、 sys.stderr を使うようになりました。もしもあなたの(テスト)プログラムが、そのデバッグ出力をキャプチャするためにこのモジュールレベル変数に依存してたのであれば、今後は sys.stderr をキャプチャするようにする必要があります。

str.startswith() と str.endswith() メソッドは空文字列を見つけた場合と完全に範囲外のインデクスが渡された場合に True を返すことはしなくなりました。 (Contributed by Serhiy Storchaka in bpo-24284 [https://bugs.python.org/issue?@action=redirect&bpo=24284].)

inspect.getdoc() 関数が基底クラスから継承したドキュメンテーション文字列を返すようになりました。その継承したドキュメンテーション文字列が相応しいのであれば、もはやそれを繰り返して記述する必要はありません。継承されたそれを抑制するには、空の文字列を記述しなければなりません(もしくは然るべきドキュメンテーションを埋めれば良いです)。この変更は pydoc モジュールと help() 関数の出力に影響します。 (Contributed by Serhiy Storchaka in bpo-15582 [https://bugs.python.org/issue?@action=redirect&bpo=15582].)

ネストされた functools.partial() 呼び出しは平坦化されるようになりました。以前の振る舞いに依存していたのであれば functools.partial() オブジェクトに属性を追加するか、または functools.partial() をサブクラス化することで出来ます。 (--訳注: 後半が意味がある内容を言ってるようには思えません。「以前の振る舞い」とはおそらく partial オブジェクトの func 属性が functools.partial そのものになることを指していて、「似たことをしたければ partial オブジェクトに別の属性を付ければりゃいんじゃね?」程度の無責任な代替案を言ってるだけのような気がします。そもそも後者の「サブクラス化」は出来ないと思いますし。 --) (Contributed by Alexander Belopolsky in bpo-7830 [https://bugs.python.org/issue?@action=redirect&bpo=7830].)

C API の変更

The undocumented format member of the (non-public) PyMemoryViewObject structure has been removed. All extensions relying on the relevant parts in memoryobject.h must be rebuilt.

PyMemAllocator 構造体が PyMemAllocatorEx にリネームされた上で calloc フィールドが追加されました。

Removed non-documented macro PyObject_REPR() which leaked references. Use format character %R in PyUnicode_FromFormat()-like functions to format the repr() of the object. (Contributed by Serhiy Storchaka in bpo-22453 [https://bugs.python.org/issue?@action=redirect&bpo=22453].)

__module__ 属性の欠落は pickle 化とイントロスペクションを壊してしまうので、 __module__ 属性のない組み込み型で DeprecationWarning を引き起こすようにしました。将来これは AttributeError にするかもしれません。(Contributed by Serhiy Storchaka in bpo-20204 [https://bugs.python.org/issue?@action=redirect&bpo=20204].)

As part of the PEP 492 [https://peps.python.org/pep-0492/] implementation, the tp_reserved slot of PyTypeObject was replaced with a tp_as_async slot. Refer to コルーチンオブジェクト for new types, structures and functions.

Notable changes in Python 3.5.4

New make regen-all build target

To simplify cross-compilation, and to ensure that CPython can reliably be compiled without requiring an existing version of Python to already be available, the autotools-based build system no longer attempts to implicitly recompile generated files based on file modification times.

Instead, a new 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 [https://github.com/python/cpython/tree/3.12/Makefile.pre.in] for details.

(Victor Stinner の貢献による bpo-23404 [https://bugs.python.org/issue?@action=redirect&bpo=23404])

Added in version 3.5.4.

Removal of make touch build target

The make touch build target previously used to request implicit regeneration of generated files by updating their modification times has been removed.

It has been replaced by the new make regen-all target.

(Victor Stinner の貢献による bpo-23404 [https://bugs.python.org/issue?@action=redirect&bpo=23404])

バージョン 3.5.4 で変更.

What's New In Python 3.4

著者:

R. David Murray <rdmurray@bitdance.com> (編集者)

この記事では 3.3 と比較した Python 3.4 の新機能を解説します。 Python 3.4 は2014年3月16日にリリースされました。全詳細については 変更履歴 [https://docs.python.jp/3.4/whatsnew/changelog.html] をご覧ください。

参考

PEP 429 [https://peps.python.org/pep-0429/] -- Python 3.4 リリーススケジュール

概要 -- リリースハイライト

新たな文法機能:

Python 3.4 に追加された新しい文法機能はありません。

その他の新しい機能:

pip が常に利用可能であることが保障されるようになりました (PEP 453 [https://peps.python.org/pep-0453/])。

新しく作成されたファイル記述子が継承不可能 （non-inheritable） になりました (PEP 446 [https://peps.python.org/pep-0446/])。

隔離モード (isolated mode) の為のコマンドラインオプション (bpo-16499 [https://bugs.python.org/issue?@action=redirect&bpo=16499])。

非テキストエンコーディングでの Codec 処理の改良 (複数の issue に関係).

インポートシステムのための ModuleSpec 型 (PEP 451 [https://peps.python.org/pep-0451/]). (インポーターの作者に影響します)

marshal フォーマットが よりコンパクトで効率的に なりました (bpo-16475 [https://bugs.python.org/issue?@action=redirect&bpo=16475])。

新たなライブラリモジュール:

asyncio: 非同期 IO のための新たな暫定 API (PEP 3156 [https://peps.python.org/pep-3156/])。

ensurepip: pip インストーラのブートストラップ (PEP 453 [https://peps.python.org/pep-0453/])。

enum: 列挙型のサポート (PEP 435 [https://peps.python.org/pep-0435/])。

pathlib: オブジェクト指向のファイルシステムパス (PEP 428 [https://peps.python.org/pep-0428/])。

selectors: 高水準で効率的な I/O の多重化、select モジュールプリミティブを基にしています (PEP 3156 [https://peps.python.org/pep-3156/] の一部)。

statistics: 基礎的な 数値的に安定な統計ライブラリ (PEP 450 [https://peps.python.org/pep-0450/])。

tracemalloc: Python のメモリ割り当てのトレース (PEP 454 [https://peps.python.org/pep-0454/])。

大幅に改善されたライブラリモジュール:

functools の シングルディスパッチジェネリック関数 (PEP 443 [https://peps.python.org/pep-0443/])。

pickle の新しい プロトコル 4 (PEP 3154 [https://peps.python.org/pep-3154/]).

multiprocessing が Unix で os.fork の使用を避けるオプションを持つようになりました (bpo-8713 [https://bugs.python.org/issue?@action=redirect&bpo=8713])。

email にサブモジュール contentmanager が追加され、また、 Message のサブクラス (EmailMessage) が追加されました。これは MIME 処理を簡単にします 。 (bpo-18891 [https://bugs.python.org/issue?@action=redirect&bpo=18891])

inspect と pydoc が以前よりも遥かに幅広い種類の callable オブジェクトを正しくイントロスペクション出来るようになり、これは Python help() システムを改善することになりました。

ipaddress モジュール API は安定だと宣言されました。

セキュリティの改善:

安全で取り替え可能なハッシュアルゴリズム (PEP 456 [https://peps.python.org/pep-0456/])。

ファイル記述子が子プロセスにリークするのを防ぐために 新しく作成されたファイル記述子が継承不可になりました (PEP 446 [https://peps.python.org/pep-0446/])。

隔離モード (isolated mode) のための新たなコマンドラインオプション (bpo-16499 [https://bugs.python.org/issue?@action=redirect&bpo=16499])。

multiprocessing が Unix で os.fork の使用を避けるオプション を持つようになりました。子プロセスとのデータ共有を避けるため spawn と forkserver はより安全です。

Windows での multiprocessing 子プロセスはもはや、必要なものを除いて親の継承可能なハンドルを継承しません。

新たな関数 hashlib.pbkdf2_hmac() は PKCS#5 パスワードベースの鍵導出関数２ [https://en.wikipedia.org/wiki/PBKDF2] を提供します。

ssl での TLSv1.1、 TLSv1.2 サポート の追加。

ssl での Windows のシステム証明書ストアよりの証明書抽出サポート の追加。

ssl での サーバサイド SNI (Server Name Indication) サポート の追加。

ssl.SSLContext クラスに 多数の改善 がなされました。

SSL をサポートする全ての標準ライブラリモジュールは今や、ホスト名のマッチング (ssl.match_hostname()) と証明書失効リスト (CRLs=certification revocation lists。 ssl.SSLContext.load_verify_locations() 参照) を含むサーバ証明書検証をサポートします。

CPython の実装の改善:

オブジェクトの安全なファイナライゼーション (PEP 442 [https://peps.python.org/pep-0442/])。

PEP 442 [https://peps.python.org/pep-0442/] を活用することで、ほとんどのケースで モジュールのグローバルがファイナライゼーション中に None がセットされることはなくなりました (bpo-18214 [https://bugs.python.org/issue?@action=redirect&bpo=18214])。

設定可能なメモリアロケータ (PEP 445 [https://peps.python.org/pep-0445/])。

Argument Clinic (PEP 436 [https://peps.python.org/pep-0436/])。

以降は、たくさんのほかの小さな改善、CPython での最適化、非推奨リスト、潜在的な移植性問題を含む、ユーザ向けの変更の包括的なリストになっています。

新しい機能

PEP 453: Python インストール時の PIP の明示的なブートストラッピング

デフォルトでの pip のブートストラッピング

新しい ensurepip モジュール(PEP 453 [https://peps.python.org/pep-0453/] で定義されています)は標準のクロスプラットフォームのメカニズムで、Python インストールと仮想環境に pip インストーラをブートストラップします。Python 3.4.0 に含まれる pip のバージョンは pip 1.5.4 で、将来の 3.4.x メンテナンスリリースでは Python のリリース候補の作成時点で入手出来る最新バージョンの pip がバンドルされる予定です。

デフォルトでは pipX , pipX.Y コマンドが全てのプラットフォームに、Python パッケージ pip とその依存物とともにインストールされます(X. Y はインストールされる Python のバージョン)。Windows 実環境と全てのプラットフォームの仮想環境には、バージョンが名前に付与されない pip コマンドもインストールされます。ほかのプラットフォームでは、システムワイドでバージョンが名前に付与されない pip コマンドは、典型的には Python 2 を別途インストールした際のものを指しています。

pyvenv コマンドラインユーティリティと venv モジュールは、仮想環境で pip が使えるようにするために ensurepip モジュールを使います。コマンドラインユーティリティを使う際は pip はデフォルトでインストールされます。 venv モジュールの API を使う際は、 pip のインストールは明示的に要求しなければなりません。

CPython の source builds on POSIX systems では make install, make altinstall コマンドはデフォルトで pip ブートストラップを行います。この振る舞いは configure のオプションを変更して Makefile を作ることで変更できます。

Windows と Mac OS X では CPython インストーラはそれ自身と一緒に pip をデフォルトでインストールするようになっています(ユーザはインストールプロセスで除外するかもしれませんが)。Windows ユーザは pip がコマンドラインからデフォルトで利用可能なように PATH の自動修正するかの選択を求められます。そうしない場合でも Windows のための Python ランチャで py -m pip のようにすれば良いです。

discussed in the PEP [https://www.python.org/dev/peps/pep-0453/#recommendations-for-downstream-distributors] の通りプラットフォームのパッケージャは、プラットフォームでのそれらインストールの単純明快な手段を自身が提供する(普通システムのパッケージマネージャ)からと言う理由で、デフォルトでのこれらコマンドのインストールを選択しないかもしれません。

注釈

Python 2 と Python 3 の共存インストールでの衝突を避けるために、 ensurepip を直接呼び出した場合のデフォルトでは、バージョン付けされた pip3, pip3.4 コマンドだけがインストールされます。バージョン付けのない pip コマンドもインストールしたければ、 --default-pip オプションが必要です。 pyvenv と Windows インストーラは修飾のない pip コマンドがそれら環境で利用可能となるように保障しますし、また、複数の Python がインストールされたシステムで曖昧さを避けようと直接コマンドを呼び出す代わりに、 pip は -m スイッチ経由でいつでも呼び出せます。

ドキュメントの変更

この変更の一部は、 Python モジュールのインストール と Python モジュールの配布 セクションがより手短な始め方として完全にデザインし直されたことと、FAQ ドキュメントです。ほとんどのパッケージングについてのドキュメンテーションは Python Packaging User Guide [https://packaging.python.org] が保守している Python Packaging Authority に移動されて、独立したプロジェクトのドキュメンテーションになっています。

However, as this migration is currently still incomplete, the legacy versions of those guides remaining available as Building C and C++ Extensions with setuptools and Building C and C++ Extensions with setuptools.

参考

PEP 453 [https://peps.python.org/pep-0453/] -- Python インストールの際の明示的なpipのブートストラッピング

PEP は Donald Stufft と Nick Coghlan によって書かれ、Donald Stufft, Nick Coghlan, Martin von Löwis, Ned Deily により実装されました。

PEP 446: 新規作成されたファイル記述子は継承不可

PEP 446 [https://peps.python.org/pep-0446/] により、新規作成するファイル記述子は 継承不可 (non-inheritable) となります。一般的にはこれこそがアプリケーションが望む振る舞いです。新たにプロセスを生成する際に、現在開いているファイルを起こした子プロセスでも開くことは、検出が困難なあらゆるバグや潜在的なセキュリティ問題を引き起こしかねません。

そうはいっても継承することが望ましい場合もあります。それらのケースをサポートするために、以下の新規関数とメソッドが利用出来ます:

os.get_inheritable(), os.set_inheritable()

os.get_handle_inheritable(), os.set_handle_inheritable()

socket.socket.get_inheritable(), socket.socket.set_inheritable()

参考

PEP 446 [https://peps.python.org/pep-0446/] -- 新規作成されたファイル記述子を継承不可にする

PEP written and implemented by Victor Stinner.

Codec 処理の改良

その最初の導入からずっと、 codecs モジュールとはいつなんどきも、型に中立で動的なエンコーディング・デコーディングシステムとして働くものであったのです。そうなのですがその Python テキストモデルとの密接な結合、特に組み込み型 str, bytes, bytearray にある型に制限があるコンビニエンスメソッドのおかげで、歴史的にその本来の意図を曖昧にしてきたのでした。

そんな状況を清く正しくするための重要な一歩として、今ではコンビニエンス関数 codecs.encode(), codecs.decode() が Python 2.7、3.3、3.4 で適切にドキュメントされました。これら関数は codecs モジュールに Python 2.4 からずっと存在している (うえに回帰テストスイートでもずっと網羅してきた) のですが、以前はドキュメントされていなかったわけなので、実行時イントロスペクションでようやく見つけられるというものだったわけです。

str, bytes, bytearray でのコンビニエンスメソッドが Python 3 では Unicode テキストエンコーディングに制限され、Python 2 では basestring <-> basestring 変換に制限されるのとは違うのです。 codecs のコンビニエンス関数は Python 2 と Python 3 の両方で任意のコーデックをサポートするのです。

Python 3.4 では、インタプリタは標準ライブラリで提供している非テキストエンコーディングについて知っています。そして以下のように適宜、それら汎用目的のコンビニエンス関数へユーザを誘導します:

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

関連する変更で、後方互換性を壊すことなくそれが相応しい場合にはいつでも、エンコーディング・デコーディング操作中に起こる例外は、同じ例外型でありエラーを発生させることになった原因コーデックの名前に言及する連鎖例外内に包まれます:

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

そしてついに、ここまで実例で見てきたような的確な誘導による改善が、それ自体は Python 3.2 で復活していた非 Unicode コーデックへのコンビニエンスのエイリアスの復活を可能にしました。(---訳注: Python 3.0 で一度非 Unicode エンコーディングは消滅し、3.2 でそれらコーデックそのものは復活したものの、 Lib/encodings/aliases.py [https://github.com/python/cpython/tree/3.12/Lib/encodings/aliases.py] のマッピングからは除外されたままだった。---) つまり、バイナリデータの 16 進表現エンコードとそのデコード (たとえば、です) は、今ではこう書けるということです:

>>> from codecs import encode, decode
>>> encode(b"hello", "hex")
b'68656c6c6f'
>>> decode(b"68656c6c6f", "hex")
b'hello'

標準ライブラリで提供されるバイナリ変換とテキスト変換は、 バイナリ変換 (Binary Transforms) と テキスト変換 (Text Transforms) に詳細記述されました。

(Contributed by Nick Coghlan in bpo-7475 [https://bugs.python.org/issue?@action=redirect&bpo=7475], bpo-17827 [https://bugs.python.org/issue?@action=redirect&bpo=17827], bpo-17828 [https://bugs.python.org/issue?@action=redirect&bpo=17828] and bpo-19619 [https://bugs.python.org/issue?@action=redirect&bpo=19619].)

PEP 451: インポートシステムのための ModuleSpec 型

PEP 451 [https://peps.python.org/pep-0451/] は、インポート機構がロードに使うモジュールに関する情報 (つまりモジュールの仕様) のカプセル化を提供します。これはインポートの実装とインポート関連 API の両方を単純化するのに役立ちます。この変更は、 いくつかの将来のインポート関連の改善 [https://mail.python.org/pipermail/python-dev/2013-November/130111.html] の足掛かりでもあります。

この PEP による公な側面での変化は完全に後方互換です。さらにそれらは、インポーターの作者以外にとっては透過的であるはずです。鍵となるファインダとローダのメソッドはまだ動作し続けますが非推奨となりました。新しいインポータは PEP に記述された新メソッドを使うべきです。既存のインポータは新メソッドを実装するように更新すべきです。置き換えられるべきメソッドとその代わりとなるメソッドのリストについては 非推奨 を参照してください。

その他の言語変更

Python 言語コアに小さな変更がいくつか行われました:

Unicode データベースを UCD バージョン 6.3 にアップグレードしました。

min() と max() にキーワード専用引数 default が追加されました。これにはイテラブルが要素なしであると評価される場合に返す値を指定出来ます。 (Contributed by Julian Berman in bpo-18111 [https://bugs.python.org/issue?@action=redirect&bpo=18111].)

Module objects are now weakly referenceable.

モジュールの __file__ 属性 (と関連する値) にはデフォルトでは常に絶対パスを含むようになりました。ただし、スクリプトがコマンドラインから相対パスを使って直接実行された際の __main__.__file__ は唯一の例外です。 (Contributed by Brett Cannon in bpo-18416 [https://bugs.python.org/issue?@action=redirect&bpo=18416].)

UTF-16 デコーダ (妥当なサロゲートペアを受け付ける) と UTF-16 エンコーダ (非 BMP 文字のエンコードでサロゲートペアを生成) 以外の、(UTF-7 を除く) 全ての UTF-* コーデックが、エラーハンドラ surrogatepass を使わない限りはエンコーディングとデコーディングの両方でサロゲートペアを拒絶するようになりました。(Contributed by Victor Stinner, Kang-Hao (Kenny) Lu and Serhiy Storchaka in bpo-12892 [https://bugs.python.org/issue?@action=redirect&bpo=12892].)

新規ドイツ語 EBCDIC codec cp273. (Contributed by Michael Bierenfeld and Andrew Kuchling in bpo-1097797 [https://bugs.python.org/issue?@action=redirect&bpo=1097797].)

新規ウクライナ語 codec cp1125. (Contributed by Serhiy Storchaka in bpo-19668 [https://bugs.python.org/issue?@action=redirect&bpo=19668].)

bytes.join() と bytearray.join() が引数として任意のバッファオブジェクトを受け取れるようになりました。 (Contributed by Antoine Pitrou in bpo-15958 [https://bugs.python.org/issue?@action=redirect&bpo=15958].)

int コンストラクタの base 引数に、 __index__ メソッドを持つ任意のオブジェクトを渡せるようになりました。(Contributed by Mark Dickinson in bpo-16772 [https://bugs.python.org/issue?@action=redirect&bpo=16772].) (---訳注: Python API の変更 に同じ bpo-16772 [https://bugs.python.org/issue?@action=redirect&bpo=16772] を発端とする変更が書かれているのでそちらも参照して下さい。 ---)

フレームオブジェクトに、ローカル変数への全ての参照をフレームからクリアするメソッド clear() が追加されました。(Contributed by Antoine Pitrou in bpo-17934 [https://bugs.python.org/issue?@action=redirect&bpo=17934].)

memoryview が Sequence として登録され、また、組み込み関数 reversed() をサポートするようになりました。 (Contributed by Nick Coghlan and Claudiu Popa in bpo-18690 [https://bugs.python.org/issue?@action=redirect&bpo=18690] and bpo-19078 [https://bugs.python.org/issue?@action=redirect&bpo=19078].)

Argument Clinic の導入、 inspect と pydoc になされた他の変更の結果、多くの場合で help() が報告するシグニチャが修正・改善されました。

__length_hint__() が、公式な言語仕様の一部になりました (see PEP 424 [https://peps.python.org/pep-0424/])。 (Contributed by Armin Ronacher in bpo-16148 [https://bugs.python.org/issue?@action=redirect&bpo=16148].)

新たなモジュール

asyncio

asyncio モジュールが追加されました (PEP 3156 [https://peps.python.org/pep-3156/] で定義されています)。これは Python のための標準的で抜き挿し可能なイベントループモデルを、標準ライブラリに信頼出来る非同期 I/O サポートを追加することで提供し、また、ほかのイベントループ実装を標準ライブラリと相互運用することを容易にします。

Python 3.4 では、このモジュールは 暫定 API であるとみなされています。

参考

PEP 3156 [https://peps.python.org/pep-3156/] -- 非同期 IO サポートの再起動: "asyncio" モジュール

PEP written and implementation led by Guido van Rossum. (訳注: PEP タイトルの「Asynchronous IO Support Rebooted: the "asyncio" Module」は PEP 3153 [https://peps.python.org/pep-3153/] の焼き直しのため。)

ensurepip

新規の ensurepip モジュールは PEP 453 [https://peps.python.org/pep-0453/] 実装のための本質的な基盤です。通常はエンドユーザはこのモジュールを弄ぶ必要はありません。ですが、 pip のインストレーションや仮想環境に対する自動ブートストラップを拒否していた場合には、手動でそれをブートストラップするのに使えます。

ensurepip は pip のバンドルされたコピーを含んでいて、これは CPython リリースの最初のリリース候補時点での最新です (このことはメンテナンスリリース、feature リリースの両方に適用されます)。 ensurepip 自身はインターネットアクセスしません。依存パッケージ解決のためのインターネットアクセスを要するならばそれは ensurepip 実行の後の pip で行いますし、 pip そのもののアップグレードも pip 自身で行います。(そのようなアップグレード版 pip は個別のインストールパッケージとみなされて、Python がアンインストールされても削除されないことを付記しておきます。)

このモジュールが「 ensure (保障する) 」を名前に冠するのは、 pip がインストール済みならば何もしないからです。このモジュールは --upgrade オプションを持ちますが、これは既存のインストール版 pip がこのモジュールにバンドルされたコピーよりも古い場合に、バンドルされたコピー版 pip をインストールします。

enum

enum モジュール (PEP 435 [https://peps.python.org/pep-0435/] にて定義) は標準の列挙型実装を提供します。これにより (socket のような) ほかのモジュールが、不透明な整数定数を後方互換を保ったまま列挙値に置き換えることによって、より情報に富むエラーメッセージを提供したり、より良いデバッグサポートを行えるようになります。

参考

PEP 435 [https://peps.python.org/pep-0435/] -- Python 標準ライブラリに enum 型を追加

PEP written by Barry Warsaw, Eli Bendersky and Ethan Furman, implemented by Ethan Furman.

pathlib

新規モジュール pathlib は、異なるオペレーティングシステムごとに適切な意味付けでファイルシステムパスを表現するクラス群を提供しています。パスのクラス群は 純粋パス と 具象パス に分離されています。前者は I/O を伴わない純粋なパス計算操作を提供するもので、後者は純粋パスを派生しますが I/O 操作も提供します。

Python 3.4 では、このモジュールは 暫定 API であるとみなされています。

参考

PEP 428 [https://peps.python.org/pep-0428/] -- pathlib モジュール -- オブジェクト指向のファイルシステムパス

PEP written and implemented by Antoine Pitrou.

selectors

新規モジュール selectors (PEP 3156 [https://peps.python.org/pep-3156/] の一部として作成されました)　は、高水準で効率的な I/O の多重化を行います。これは select モジュールプリミティブに基いています。

statistics

新規モジュール statistics (PEP 450 [https://peps.python.org/pep-0450/] で定義) は統計を扱う中核機能のいくつかを標準ライブラリで直接提供します。このモジュールはデータ系列の平均、中央値、最頻値、分散、標準偏差の計算をサポートします。

参考

PEP 450 [https://peps.python.org/pep-0450/] -- 標準ライブラリに統計モジュールを追加

PEP written and implemented by Steven D'Aprano

tracemalloc

新たな tracemalloc モジュール (PEP 454 [https://peps.python.org/pep-0454/] で定義) は Python が割り当てたメモリブロックをトレースするためのデバッグツールです。以下の情報を提供します:

オブジェクトが割り当てられた場所をトレースする

ファイル名ごと、及び行ごとに割り当てられたメモリブロックの以下の統計を取ります：総サイズ、ブロック数、割り当てられたブロックの平均サイズ

メモリリークを検出するために2つのスナップショットの差を計算します。

参考

PEP 454 [https://peps.python.org/pep-0454/] -- Python メモリ割り当てをトレースするための tracemalloc モジュールの追加

PEP written and implemented by Victor Stinner

改良されたモジュール

abc

新規関数 abc.get_cache_token() は、オブジェクトグラフ内での変化の影響を受けるキャッシュをいつ無効化すれば良いかを知るために使えます。 (Contributed by Łukasz Langa in bpo-16832 [https://bugs.python.org/issue?@action=redirect&bpo=16832].)

新規クラス ABC はそのメタクラスとして ABCMeta を持ちます。この ABC を基底クラスとして使うことは metaclass=abc.ABCMeta を指定するのと本質的に同じ効果を持ちますが、少ないタイプ数で単純に書ける上に読みやすいものになります。(Contributed by Bruno Dupuis in bpo-16049 [https://bugs.python.org/issue?@action=redirect&bpo=16049].)

aifc

The getparams() method now returns a namedtuple rather than a plain tuple. (Contributed by Claudiu Popa in bpo-17818 [https://bugs.python.org/issue?@action=redirect&bpo=17818].)

aifc.open() now supports the context management protocol: when used in a with block, the close() method of the returned object will be called automatically at the end of the block. (Contributed by Serhiy Storchacha in bpo-16486 [https://bugs.python.org/issue?@action=redirect&bpo=16486].)

The writeframesraw() and writeframes() methods now accept any bytes-like object. (Contributed by Serhiy Storchaka in bpo-8311 [https://bugs.python.org/issue?@action=redirect&bpo=8311].)

argparse

FileType クラスが encoding 引数、 errors 引数を受け付けるようになりました。これは open() にそのまま渡されます。 (Contributed by Lucas Maystre in bpo-11175 [https://bugs.python.org/issue?@action=redirect&bpo=11175].)

audioop

audioop now supports 24-bit samples. (Contributed by Serhiy Storchaka in bpo-12866 [https://bugs.python.org/issue?@action=redirect&bpo=12866].)

New byteswap() function converts big-endian samples to little-endian and vice versa. (Contributed by Serhiy Storchaka in bpo-19641 [https://bugs.python.org/issue?@action=redirect&bpo=19641].)

All audioop functions now accept any 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 [https://bugs.python.org/issue?@action=redirect&bpo=16685].)

base64

base64 のエンコード・デコード関数が任意の bytes-like object オブジェクトを受け取れるようになりました。以前は bytes または bytearray インスタンスである必要がありました。 (Contributed by Nick Coghlan in bpo-17839 [https://bugs.python.org/issue?@action=redirect&bpo=17839].)

新規関数 a85encode(), a85decode() は Ascii85 フォーマットの、 b85encode(), b85decode() は git/mercurial の Base85 フォーマットの、バイナリデータのエンコード・バイナリデータへのデコードを提供します。 a85 関数は、Abobe 方言を含む Ascii85 エンコーディングの変種と互換性を持たせるためのオプションを持っています。(Contributed by Martin Morrison, the Mercurial project, Serhiy Storchaka, and Antoine Pitrou in bpo-17618 [https://bugs.python.org/issue?@action=redirect&bpo=17618].)

collections

ChainMap.new_child() メソッドが、チェーンに追加する子マップを指定する m 引数を取るようになりました。これにより、以前は組み込み辞書が必ず maps の先頭になっていましたが、カスタムマッピング型も使えるようになります。(Contributed by Vinay Sajip in bpo-16613 [https://bugs.python.org/issue?@action=redirect&bpo=16613].)

colorsys

RGB --- YIQ 変換の係数の桁数が FCC NTSC version [https://en.wikipedia.org/wiki/YIQ#FCC_version_of_NTSC_standard] に合うように広げられました。結果としての変化は 1% 未満のはずで、また、ほかの処理系での結果とより合致するでしょう。 (Contributed by Brian Landers and Serhiy Storchaka in bpo-14323 [https://bugs.python.org/issue?@action=redirect&bpo=14323].)

contextlib

新規コンテキストマネージャ contextlib.suppress によって、意図して単独ステートメントからの例外を抑制しているというコードの意図をはっきりと読み手に伝えることが出来ます。 (Contributed by Raymond Hettinger in bpo-15806 [https://bugs.python.org/issue?@action=redirect&bpo=15806] and Zero Piraeus in bpo-19266 [https://bugs.python.org/issue?@action=redirect&bpo=19266].)

新規コンテキストマネージャ contextlib.redirect_stdout() は、ユーティリティスクリプトにて、その出力を sys.stdout に書き出す一方でその向き先を変えれない頑固な API の扱いを簡単にしてくれます。これを使うと、 sys.stdout 出力をなにかほかのストリームに振り替えたり、あるいは io.StringIO と組み合わせて文字列化したり出来ます。後者などは特に便利で、たとえば元々はコマンドラインインターフェイスとして実装された関数からの出力を取り込む、などということが出来ます。このコンテキストマネージャはユーティリティスクリプト以外では使わない方が肝要です。というのもこれは sys.stdout の大域的な状態に影響を与えてしまうからです。 (Contributed by Raymond Hettinger in bpo-15805 [https://bugs.python.org/issue?@action=redirect&bpo=15805].)

contextlib ドキュメントにも改善が行われ、コンテキストマネージャを単独で使うのと再利用したり再入可能(リエントラント)するのとの違いについての 議論 が追加されました。

dbm

dbm.open() がコンテキスト管理プロトコルをサポートするようになりました: with ブロックで使うとデータベースオブジェクトの close メソッドがブロックの終了時に自動的に呼び出されます。 (Contributed by Claudiu Popa and Nick Coghlan in bpo-19282 [https://bugs.python.org/issue?@action=redirect&bpo=19282].)

dis

関数 show_code(), dis(), distb(), disassemble() が新たにキーワード専用引数 file を受け取ります。これは出力先を制御します。

dis モジュールはいまでは Instruction クラスを中心に据えて構築されています。これは個々のバイトコード操作の詳細に対し、オブジェクト指向的なアクセスを提供するクラスです。

新規メソッド get_instructions() が、与えた Python コード片についての命令 (インストラクション) ストリームを発行するイテレータを提供します。これを使えば、dis モジュール自身が提供しているのとは違った方法で、バイトコードオブジェクトを調べたり加工するようなプログラムを書くことが出来ます。例えばこのように書けます:

>>> import dis
>>> for instr in dis.get_instructions(lambda x: x + 1):
...     print(instr.opname)
LOAD_FAST
LOAD_CONST
BINARY_ADD
RETURN_VALUE

dis モジュールにある色々な表示ツールが、これらの新しい構成要素でもって書き直されました。

アプリケーションフレンドリな Bytecode クラスも追加されています。これはバイトコードを調べるのに、人が読める形式としてもインストラクション列をイテレートするのにも優しい、オブジェクト指向的な API になっています。 Bytecode コンストラクタは get_instruction() と同じ引数 (と、追加でオプショナルな current_offset) を受け取って、結果のオブジェクトは Instruction オブジェクトを生成するイテレータとして振舞うことが出来ます。このオブジェクトは、 dis にコンストラクタ引数を渡して呼び出すのと等価な dis メソッドも持っていますが、マルチライン文字列で返します:

>>> 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']

Bytecode にはクラスメソッド from_traceback() もあります。トレースバックから Bytecode を構築します。(print(Bytecode.from_traceback(tb).dis()) は distb() を使って distb(tb) とするのと同じです。)

(Contributed by Nick Coghlan, Ryan Kelly and Thomas Kluyver in bpo-11816 [https://bugs.python.org/issue?@action=redirect&bpo=11816] and Claudiu Popa in bpo-17916 [https://bugs.python.org/issue?@action=redirect&bpo=17916].)

新規関数 stack_effect() は与えられた opcode (命令コード) と引数の Python スタックへの effect を計算します。この情報は他からは得られません。 (Contributed by Larry Hastings in bpo-19722 [https://bugs.python.org/issue?@action=redirect&bpo=19722].) (---訳注: PyCompile_OpcodeStackEffect として C API として曝した上で Python からアクセス出来るようにしたものらしいです。 stackdepth_walk での使用箇所 [https://hg.python.org/cpython/file/5fe72b9ed48e/Python/compile.c#l3838] 参照。---)

doctest

A new option flag, FAIL_FAST, halts test running as soon as the first failure is detected. (Contributed by R. David Murray and Daniel Urban in bpo-16522 [https://bugs.python.org/issue?@action=redirect&bpo=16522].)

doctest コマンドラインインターフェイスは argparse を使うようになりました。2 つの新オプション -o と -f が追加されています。 -o によりコマンドラインから doctest オプション を指定することが出来ます。 -f は -o FAIL_FAST の速記法です (unittest CLI でサポートされる似たオプション サポートされる同じオプション に似せるためです)。 (Contributed by R. David Murray in bpo-11390 [https://bugs.python.org/issue?@action=redirect&bpo=11390].)

doctest はいまや、拡張モジュールの __doc__ 文字列から doctest を見つけることが出来ます。 (Contributed by Zachary Ware in bpo-3158 [https://bugs.python.org/issue?@action=redirect&bpo=3158].)

email

as_string() メソッドが、その文字列表現を生成するのに使うデフォルトポリシーを上書き出来る policy 引数を取るようになりました。つまり Message を作り直したり flattern メソッドの書式化パラメータのためだけに generator を使うことなしに、 as_string をより多くの状況で使えるということになります。(Contributed by R. David Murray in bpo-18600 [https://bugs.python.org/issue?@action=redirect&bpo=18600].)

as_bytes() メソッドが追加されました。これは as_string が文字列表現を生成するのと似たやり方で、メッセージの bytes 表現を生成します。これは maxheaderlen 引数を取りませんが、 unixfrom 引数と policy 引数を取ります。 Message の __bytes__() がこれを呼び出すようにしたので、 bytes(mymsg) は今や直感に反しない結果、つまり完全にフォーマットされたメッセージを生成します。(Contributed by R. David Murray in bpo-18600 [https://bugs.python.org/issue?@action=redirect&bpo=18600].)

Message.set_param() メソッドにキーワード引数 replace が追加されました。真を渡すとヘッダリスト内のその位置を変更せずに関連ヘッダを更新します。後方互換のためにデフォルトは False です。 (Contributed by R. David Murray in bpo-18891 [https://bugs.python.org/issue?@action=redirect&bpo=18891].)

サブモジュール contentmanager と policy 属性の content_manager の追加と併せて、 Message の対となる二つのサブクラス (EmailMessage と MIMEPart) が追加されました。全てのドキュメントは、 email の新規 暫定 API の構成要素として追加されたこの新しいモジュールにあります。これらのクラスは、 email メッセージからの内容抽出や挿入を遥かに簡単に行える、数多くの新規メソッドを提供しています。詳細は contentmanager のドキュメントと email: 使用例 を参照してください。これらの API の追加作業により email6 プロジェクトの一部として計画されていた作業は、その大部分が完了しました。現在のところ、暫定 API 状態は Python 3.5 で最後となる予定です (可能性としてはエラー処理あたりのゾーンでは少々の些細な追加は残るかもしれません)。 (Contributed by R. David Murray in bpo-18891 [https://bugs.python.org/issue?@action=redirect&bpo=18891].)

filecmp

clear_cache() 関数が追加されました。 filecmp は os.stat() 情報をキャッシュして最後の比較時点からのファイルの変化をみていますが、このキャッシュをクリアします。これはたとえば、ファイルシステムのタイムスタンプフィールドの解像度未満の時間差で再比較したい場合に使えるでしょう。(Contributed by Mark Levitt in bpo-18149 [https://bugs.python.org/issue?@action=redirect&bpo=18149].)

New module attribute DEFAULT_IGNORES provides the list of directories that are used as the default value for the ignore parameter of the dircmp() function. (Contributed by Eli Bendersky in bpo-15442 [https://bugs.python.org/issue?@action=redirect&bpo=15442].)

functools

新たな partialmethod() デスクリプタは、ちょうど普通の callable に対して partial() がするように、デスクリプタへの引数部分適用を可能にします。この新しいデスクリプタをクラス定義内で使うと、簡単に (partial() インスタンスを含む) 任意の callable を普通のインスタンスメソッドのように振舞わせることも出来ます。(Contributed by Alon Horev and Nick Coghlan in bpo-4331 [https://bugs.python.org/issue?@action=redirect&bpo=4331].)

新たな singledispatch() デコレータは、Python 標準ライブラリにシングルディスパッチのジェネリック関数のサポートを追加します。オブジェクト指向プログラミングは共通データ集合についての複数操作をまとめあげてクラスに押し込めようとしますが、ジェネリック関数は 異なった 種類のデータに対して動作させたい操作の複数実装をひとつにまとめあげる考え方です。(---訳注: ここで「ジェネリック関数」と呼んでいるものを他の言語との類推で理解しようとすると、「呼び出す側目線」では同じで、「呼び出される側」目線では違うかもしれません。例えば C++ ユーザは「template の特殊化」もしくは「型ごとのオーバロード」との類推で理解してください。---)

参考

PEP 443 [https://peps.python.org/pep-0443/] -- シングルディスパッチのジェネリック関数

PEP written and implemented by Łukasz Langa.

total_ordering() now supports a return value of NotImplemented from the underlying comparison function. (Contributed by Katie Miller in bpo-10042 [https://bugs.python.org/issue?@action=redirect&bpo=10042].)

partial() 関数のピュア Python 版が標準ライブラリに追加されました。CPython の場合は C による高速版で置き換えられますが、ほかの Python 実装で利用出来ます。 (Contributed by Brian Thorne in bpo-12428 [https://bugs.python.org/issue?@action=redirect&bpo=12428].)

gc

新規関数 get_stats() は、インタプリタが開始してからの、世代ごと回収統計を持つ辞書の、3 世代ぶんのリストを返します。(Contributed by Antoine Pitrou in bpo-16351 [https://bugs.python.org/issue?@action=redirect&bpo=16351].)

glob

新規関数 escape() は、glob 的な展開がなされないようにして字句通りの合致をするように、ファイル名に含まれる特殊文字をエスケープする手段となります。(Contributed by Serhiy Storchaka in bpo-8402 [https://bugs.python.org/issue?@action=redirect&bpo=8402].)

hashlib

新たな関数 hashlib.pbkdf2_hmac() は PKCS#5 パスワードベースの鍵導出関数２ [https://en.wikipedia.org/wiki/PBKDF2] を提供します。 (Contributed by Christian Heimes in bpo-18582 [https://bugs.python.org/issue?@action=redirect&bpo=18582].)

hashlib のハッシュオブジェクトの name 属性が、公式にサポートされるインターフェイスになりました。これは CPython の hashlib には以前から存在していました (ただしサポートされるハッシュの名前を必ずしも小文字で返してはいませんでした) が、公開インターフェイスとしていなかったために、ほかのいくつかの Python 実装では以前はサポートされていませんでした。(Contributed by Jason R. Coombs in bpo-18532 [https://bugs.python.org/issue?@action=redirect&bpo=18532].)

hmac

hmac は、 new() の key 引数として bytearray と bytes を許容するようになり、また、 new() 関数と update() メソッドの両方への msg パラメータとして、 hashlib モジュールがサポートする任意の型を許容するようになりました。(Contributed by Jonas Borgström in bpo-18240 [https://bugs.python.org/issue?@action=redirect&bpo=18240].)

hmac.new() 関数への digestmod 引数には、hashlib が認識する任意のハッシュダイジェスト名を渡せるようになりました。これとともに、 digestmod のデフォルトとして MD5 を使う現在の振る舞いは非推奨です。将来のバージョンの Python ではこれのデフォルト値はなくなり、指定が必須になります。 (Contributed by Christian Heimes in bpo-17276 [https://bugs.python.org/issue?@action=redirect&bpo=17276].)

block_size 属性と name 属性 (と digest_size 属性の公式ドキュメント) の追加をもって、 hmac モジュールは完全に PEP 247 [https://peps.python.org/pep-0247/] API を遵守するものとなりました。 (Contributed by Christian Heimes in bpo-18775 [https://bugs.python.org/issue?@action=redirect&bpo=18775].)

html

新規関数 unescape() は HTML5 文字参照を対応する Unicode 文字に変換します。 (Contributed by Ezio Melotti in bpo-2927 [https://bugs.python.org/issue?@action=redirect&bpo=2927].)

HTMLParser が新規キーワード引数 convert_charrefs を受け取ります。これが True の場合に、全ての文字参照が自動的に変換されます。後方互換性の問題から今はこのデフォルトを False にしてありますが、将来バージョンの Python でこれを True に変えます。ですから値は明示的にセットしてこの新しい機能を使うように更新しておくと良いです。(Contributed by Ezio Melotti in bpo-13633 [https://bugs.python.org/issue?@action=redirect&bpo=13633].)

HTMLParser の strict 引数が非推奨となりました。 (Contributed by Ezio Melotti in bpo-15114 [https://bugs.python.org/issue?@action=redirect&bpo=15114].)

http

send_error() がオプショナルなパラメータ explain を受け付けるようになりました。指定されると、拡張のエラー説明を提供するにあたって、ハードコードされたデフォルトの代わりに使われます。この拡張のエラー説明は error_message_format 属性を使ってフォーマットされて、エラーレスポンスのメッセージボディとして送信されます。(Contributed by Karl Cow in bpo-12921 [https://bugs.python.org/issue?@action=redirect&bpo=12921].)

http.server の コマンドラインインターフェイス に -b/--bind オプションが追加されました。これは特定のアドレスで listen することを指示します。 (Contributed by Malte Swart in bpo-17764 [https://bugs.python.org/issue?@action=redirect&bpo=17764].) (---訳注: ネットワークプログラミングに詳しい人ほど混乱しそうなので一応。 --bind というオプション名が示すとおり、より正確に表現するなら「ユーザ指定のネットワークインターフェイスに bind」。コミットログの表現「Expose --bind argument for http.server, enable http.server to bind to a user specified network interface.」の方がわかりやすいかと。 ---)

idlelib と IDLE

idlelib は IDLE シェルとエディタを実装するものであってほかのプログラムからインポートされることを意図してはいないので、改善は毎度のリリースごとに行われます。3.3.0 から始まり、また将来の 3.4.x リリースになされる累積的な変更リストは Lib/idlelib/NEWS.txt で読むことが出来ます。このファイルは IDLE で Help ‣ About IDLE からも辿り着けます。

importlib

InspectLoader ABC に新規メソッド source_to_code() が追加されました。ソースデータとパスを受け取り、コードオブジェクトを返します。これのデフォルト実装は compile(data, path, 'exec', dont_inherit=True) と同じです。 (Contributed by Eric Snow and Brett Cannon in bpo-15627 [https://bugs.python.org/issue?@action=redirect&bpo=15627].)

InspectLoader では get_code() メソッドへのデフォルト実装追加も行われました。とはいえ性能面の理由より、通常はデフォルト実装をオーバライドすることが望ましいです。 (Contributed by Brett Cannon in bpo-18072 [https://bugs.python.org/issue?@action=redirect&bpo=18072].)

The reload() function has been moved from imp to importlib as part of the imp module deprecation. (Contributed by Berker Peksag in bpo-18193 [https://bugs.python.org/issue?@action=redirect&bpo=18193].)

importlib.util now has a MAGIC_NUMBER attribute providing access to the bytecode version number. This replaces the get_magic() function in the deprecated imp module. (Contributed by Brett Cannon in bpo-18192 [https://bugs.python.org/issue?@action=redirect&bpo=18192].)

New importlib.util functions cache_from_source() and source_from_cache() replace the same-named functions in the deprecated imp module. (Contributed by Brett Cannon in bpo-18194 [https://bugs.python.org/issue?@action=redirect&bpo=18194].)

importlib ブートストラップ NamespaceLoader が InspectLoader ABC に従うようになりました。つまりこれにより runpy と python -m が名前空間パッケージに対して使えるようになりました。(Contributed by Brett Cannon in bpo-18058 [https://bugs.python.org/issue?@action=redirect&bpo=18058].) (訳注: 3.3 以降の名前空間パッケージについては What's New In Python 3.3 (PEP 420 [https://peps.python.org/pep-0420/]) 参照。)

importlib.util に decode_source() 関数が追加されました。 universal newlines 処理を使って bytes からソースをデコードします。 InspectLoader.get_source() メソッドを実装するのに便利です。

importlib.machinery.ExtensionFileLoader に get_filename() メソッドが追加されました。これは本来実装されるべきものでしたが見落とされていました。(Contributed by Eric Snow in bpo-19152 [https://bugs.python.org/issue?@action=redirect&bpo=19152].)

inspect

inspect モジュールに、ソースコードおよびモジュール・クラス・関数についてのその他情報を手早く表示するための、基礎的な コマンドラインインターフェイス が追加されました。 (Contributed by Claudiu Popa and Nick Coghlan in bpo-18626 [https://bugs.python.org/issue?@action=redirect&bpo=18626].)

新規の unwrap() で、 functools.wraps() (やラッパー関数に __wrapped__ 属性をセットするその他 API) で作られたラッパー関数のチェインを、簡単にほどくことが出来ます。 (Contributed by Daniel Urban, Aaron Iles and Nick Coghlan in bpo-13266 [https://bugs.python.org/issue?@action=redirect&bpo=13266].) (---訳注: 「簡単に」の意味するところについて、 Python API の変更 に記述されている functools.update_wrapper() と functools.wraps() の変更も参照して下さい。---)

新規 enum モジュールが実装されたことを受け inspect モジュールは、カスタム __dir__ メソッドに対する、またメタクラスを介して提供される動的クラス属性に対する、ずっと良いサポートを提供出来るようになりました。 (Contributed by Ethan Furman in bpo-18929 [https://bugs.python.org/issue?@action=redirect&bpo=18929] and bpo-19030 [https://bugs.python.org/issue?@action=redirect&bpo=19030].)

getfullargspec() と getargspec() が signature() API を使うようになりました。このことで、以前より遥かに幅広い callable をサポートするようになっています。それには __signature__ 属性を含むもの、 Argument Clinic で提供されるメタデータを含むもの、あるいは functools.partial() オブジェクト、なども含まれます。 signature() そのものとは違い、今でも getfullargspec(), getargspec() は __wrapped__ 属性を無視し、そして束縛されたメソッドで最初に束縛された引数を報告するので、それが望みでないならば signature() を直接使うようにあなたのコードを更新する必要があります。(Contributed by Yury Selivanov in bpo-17481 [https://bugs.python.org/issue?@action=redirect&bpo=17481].) (---訳注: What's New In Python 3.5 を参照してください。 signature() により getfullargspec() と getargspec() は結果として非推奨となりました。---)

signature() が CPython 関数のダックタイプをサポートするようになりました。これは Cython でコンパイルされた関数をサポートすることになります。 (Contributed by Stefan Behnel and Yury Selivanov in bpo-17159 [https://bugs.python.org/issue?@action=redirect&bpo=17159].) (---訳注: duck type はここでは「 types.FunctionType であることを要求しない」の意味。 _signature_is_functionlike [https://hg.python.org/cpython/file/32a660a52aae/Lib/inspect.py#l1604] 参照。 ---)

ipaddress

ipaddress は Python 3.3 で標準ライブラリに 暫定 API として追加されました。Python 3.4 リリースで、この但し書きは削除されました: ipaddress は今や安定 API とみなされ、今後は通常の標準ライブラリの後方互換性維持要件に従います。

新規のプロパティ is_global は、アドレスが routeable である場合に True を返します。 (Contributed by Peter Moody in bpo-17400 [https://bugs.python.org/issue?@action=redirect&bpo=17400].) (---訳注: リファレンスマニュアルでは routeable という表現ではなく「アドレスがパブリックネットワークに割り当てられている場合」。---)

logging

TimedRotatingFileHandler に atTime パラメータが追加されました。ロールオーバ対象となる日付での時刻を指定します。 (Contributed by Ronald Oussoren in bpo-9556 [https://bugs.python.org/issue?@action=redirect&bpo=9556].)

SocketHandler と DatagramHandler が Unix ドメインソケットをサポートするようになりました (port に None をセットすることで)。 (Contributed by Vinay Sajip in commit ce46195b56a9 [https://hg.python.org/cpython/rev/ce46195b56a9] .)

fileConfig() が fname パラメータとして configparser.RawConfigParser のサブクラスを許容するようになりました。これはロギングの設定がアプリケーション全体の設定の一部に過ぎない場合や、 fileConfig() に渡す前にアプリケーションが設定を修正するような場合でも設定ファイルを使用することを容易にします。(Contributed by Vinay Sajip in bpo-16110 [https://bugs.python.org/issue?@action=redirect&bpo=16110].)

logging.config.listen() 関数経由でソケットから受信したロギング設定データを、処理前に検証出来るようになりました。新規のキーワード引数 verify に検証関数を渡すことで可能です。(Contributed by Vinay Sajip in bpo-15452 [https://bugs.python.org/issue?@action=redirect&bpo=15452].)

marshal

marshal のバージョンが 3 に上げられました。新バージョンを実装しているコードは、intern された文字列をただ一つのコピーだけ記録しておきデシリアライズでその intern を維持するという Python 2 での振舞いを復活させつつ、「ただ一つのコピー」を文字列型のみならず任意のオブジェクト型に (再帰参照の処理も含め) 拡張しています。これは .pyc ファイルのサイズを削減し、また、 .pyc (または .pyo) ファイルからロードされる際にモジュールが占めるメモリ量を削減します。(Contributed by Kristján Valur Jónsson in bpo-16475 [https://bugs.python.org/issue?@action=redirect&bpo=16475], with additional speedups by Antoine Pitrou in bpo-19219 [https://bugs.python.org/issue?@action=redirect&bpo=19219].)

mmap

mmap objects are now weakly referenceable. (Contributed by Valerie Lambert in bpo-4885 [https://bugs.python.org/issue?@action=redirect&bpo=4885].)

multiprocessing

multiprocessing を使ってプロセスを開始する 開始方式 として、Unix において 2 つ、 spawn と forkserver が追加されました。これらはスレッドとプロセスのミックスをより堅牢にし、また、 spawn は multiprocessing が以前から常に Windows で使ってきたセマンティクスと一致します。新規関数の、 get_all_start_methods() はプラットフォームで利用出来るすべての開始方式を報告し、 get_start_method() は現在設定されている開始方式を報告し、 set_start_method() は開始方式を設定します。(Contributed by Richard Oudkerk in bpo-8713 [https://bugs.python.org/issue?@action=redirect&bpo=8713].)

multiprocessing には、子プロセスがどのように作られるかを決定する context のコンセプトが追加されています。新規関数 get_context() は指定した開始方式を使うコンテキストを返します。コンテキストは multiprocessing モジュール自身と同じ API を持っているので、コンテキスト内で操作する Pool や他のオブジェクトを、それを使って作成することが出来ます。コンテキストによって、フレームワークとアプリケーションあるいは同じアプリケーションの別の部分が相互に干渉しあわないようにして multiprocessing を使うことが出来ます。(Contributed by Richard Oudkerk in bpo-18999 [https://bugs.python.org/issue?@action=redirect&bpo=18999].)

昔からの fork 開始方式を除き、子プロセスはもはや必要のないハンドル・ファイル記述子をその親から継承しません。 (part of bpo-8713 [https://bugs.python.org/issue?@action=redirect&bpo=8713]).

multiprocessing が開始方式に spawn または forkserver を使う場合に、子プロセスで適切に __main__ を初期化するために runpy (これが -m スイッチを実装しています) に頼るようになりました。これは、 multiprocessing と -m コマンドラインスイッチ・明示的な相対インポートを組み合わせると子プロセスが不可解に失敗していたような、いくつかの際どい問題を解決します。 (Contributed by Nick Coghlan in bpo-19946 [https://bugs.python.org/issue?@action=redirect&bpo=19946].)

operator

新規関数 length_hint() は、言語仕様となった特殊メソッド __length_hint__() の PEP 424 [https://peps.python.org/pep-0424/] 公式仕様の一環として、それがどのように使われるのかについて詳述する実装を提供します。(Contributed by Armin Ronacher in bpo-16148 [https://bugs.python.org/issue?@action=redirect&bpo=16148].)

参照実装として、また Python 実装の代替として用いることが出来る、 operator モジュールのピュア Python 版が書かれました。 (Contributed by Zachary Ware in bpo-16694 [https://bugs.python.org/issue?@action=redirect&bpo=16694].)

os

新規関数により 継承可能フラグ を制御出来るようになりました。ファイル記述子には os.get_inheritable(), os.set_inheritable() を、Windows のハンドルには os.get_handle_inheritable(), os.set_handle_inheritable() を使います。

関数 cpu_count() が追加されました。これは Python を実行しているプラットフォームで利用可能な CPU 数を返します (決定できない場合は None を返します)。既存の multiprocessing.cpu_count() はこの関数の値を返すようになりました。(Contributed by Trent Nelson, Yogesh Chaudhari, Victor Stinner, and Charles-François Natali in bpo-17914 [https://bugs.python.org/issue?@action=redirect&bpo=17914].)

os.path.samestat() が Windows プラットフォームでも動作するようになりました (また、 os.path.samefile() の実装は Unix と Windows で共有されました)。 (Contributed by Brian Curtin in bpo-11939 [https://bugs.python.org/issue?@action=redirect&bpo=11939].)

os.path.ismount() が Windows において、ドライブルートよりも下にあるマウントポイントを認識するようになりました。 (Contributed by Tim Golden in bpo-9035 [https://bugs.python.org/issue?@action=redirect&bpo=9035].)

os.open() supports two new flags on platforms that provide them, O_PATH (un-opened file descriptor), and 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 [https://bugs.python.org/issue?@action=redirect&bpo=18673] and Benjamin Peterson, respectively.)

pdb

pdb が、ジェネレータ、 yield 、 yield from をより価値ある方法で処理するように強化されました。これは asyncio ベースのプログラムをデバッグする際にとりわけ助けとなります。 (Contributed by Andrew Svetlov and Xavier de Gaye in bpo-16596 [https://bugs.python.org/issue?@action=redirect&bpo=16596].)

pdb から print コマンドは削除され、pdb コマンドラインからの Python print() 関数へのアクセスを取り戻しました。 Python 2 の pdb には print コマンドはなく print の入力は Python 2 の print 文を実行していました。 Python 3 で pdb の p コマンドへのエイリアスとして print を作ったのが間違いでした。 p はその引数の repr を表示するのであって、Python 2 での print コマンドがしていた str を表示するのではありません。さらに悪いことに、Python 3 の pdb print コマンドは Python 3 の print 関数を隠してしまい、 pdb プロンプトからのアクセスを出来なくしていたのでした。 (Contributed by Connor Osborn in bpo-18764 [https://bugs.python.org/issue?@action=redirect&bpo=18764].)

pickle

pickle で新 pickle プロトコル 4 が追加されました (デフォルトにはされていません)。この新プロトコルは、入れ子のクラスや巨大な文字列・コンテナやキーワード専用引数を取る __new__() メソッドを持つクラスなどにまつわるシリアライズの問題など、以前のプロトコルに存在していた数多くの問題を措置しています。ほかにもいくつか効率面での改善が入っています。

参考

PEP 3154 [https://peps.python.org/pep-3154/] -- Pickle プロトコル 4

PEP written by Antoine Pitrou and implemented by Alexandre Vassalotti.

plistlib

plistlib now has an API that is similar to the standard pattern for stdlib serialization protocols, with new load(), dump(), loads(), and dumps() functions. (The older API is now deprecated.) In addition to the already supported XML plist format (FMT_XML), it also now supports the binary plist format (FMT_BINARY). (Contributed by Ronald Oussoren and others in bpo-14455 [https://bugs.python.org/issue?@action=redirect&bpo=14455].)

poplib

poplib に 2 つの新規メソッドが追加されました。 capa() は POP サーバにより公表された機能リストを返します。 stls() は平文 POP3 セッションを、POP サーバがサポートしていれば暗号化された POP3 セッションに切り替えます。 (Contributed by Lorenzo Catucci in bpo-4473 [https://bugs.python.org/issue?@action=redirect&bpo=4473].)

pprint

pprint モジュールの、 PrettyPrinter クラス、 pformat() 関数、 pprint() 関数に、新規オプション compact が追加されました。これは出力方法を制御するもので、今のところのこれの True での振舞いは、個々の (インデントされた) 行を width 幅で出来るだけ多くのシーケンスの要素が収まるように出力します。 (Contributed by Serhiy Storchaka in bpo-19132 [https://bugs.python.org/issue?@action=redirect&bpo=19132].)

長い文字列が Python の普通の行継続構文で折り返されるようになりました。 (Contributed by Antoine Pitrou in bpo-17150 [https://bugs.python.org/issue?@action=redirect&bpo=17150].)

pty

pty.spawn() が None ではなく os.waitpid() からの戻り値から取ったステータス値を返すようになりました。 (Contributed by Gregory P. Smith.)

pydoc

pydoc モジュールがイントロスペクション API inspect.signature() に直接基くようになりました。これによりより幅広く callable オブジェクトのシグニチャ情報を提供出来るようになりました。この変更は、ヘルプ情報表示の際に __wrapped__ 属性も考慮に入れられることも意味しています。(Contributed by Larry Hastings in bpo-19674 [https://bugs.python.org/issue?@action=redirect&bpo=19674].)

pydoc モジュールはもはや既に束縛済みのメソッドでは self パラメータを表示しません。それよりも、与えられた callable の正確な現在のシグニチャを常に表示しようとします。 (Contributed by Larry Hastings in bpo-20710 [https://bugs.python.org/issue?@action=redirect&bpo=20710].)

pydoc に直接なされた変更に加え、背後の inspect モジュールの改善が、カスタム __dir__ メソッドやさまざまなデスクリプタの扱いについての振る舞いの大幅な改善に寄与しました。

組み込み help() は pydoc モジュールに基いているので、上記変更は help() の振る舞いにも影響します。

re

fullmatch() 関数と regex.fullmatch() メソッドが追加されました。これはパターンを合致する文字列の両端に固定します。コード変更や既存の正規表現になにか代わりとなるものを追加したりする際に、末尾に $ を入れ忘れるといった類のバグは気付きにくいものです。これらの関数で、合致すべき終端をはっきり伝えることが出来ます。 (Contributed by Matthew Barnett in bpo-16203 [https://bugs.python.org/issue?@action=redirect&bpo=16203].)

正規表現オブジェクト の repr にパターンとフラグを含めるようになりました。 match オブジェクト の repr に start、end と合致した部分文字列を含むようになりました。 (Contributed by Hugo Lopes Tavares and Serhiy Storchaka in bpo-13592 [https://bugs.python.org/issue?@action=redirect&bpo=13592] and bpo-17087 [https://bugs.python.org/issue?@action=redirect&bpo=17087].)

resource

新規関数 prlimit() は、指定プロセスのリソースリミットの問い合わせとセットを、一度の呼び出しで行えます。カーネルバージョン 2.6.36 以降で glibc 2.13 以降の Linux プラットフォームで利用可能です。 (Contributed by Christian Heimes in bpo-16595 [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: RLIMIT_MSGQUEUE, RLIMIT_NICE, RLIMIT_RTPRIO, RLIMIT_RTTIME, and RLIMIT_SIGPENDING. (Contributed by Christian Heimes in bpo-19324 [https://bugs.python.org/issue?@action=redirect&bpo=19324].)

On FreeBSD version 9 and later, there some new FreeBSD specific constants: RLIMIT_SBSIZE, RLIMIT_SWAP, and RLIMIT_NPTS. (Contributed by Claudiu Popa in bpo-19343 [https://bugs.python.org/issue?@action=redirect&bpo=19343].)

select

epoll がコンテキスト管理プロトコルをサポートするようになりました: with ブロックで使うと close() メソッドがブロックの終了時に自動的に呼び出されます。 (Contributed by Serhiy Storchaka in bpo-16488 [https://bugs.python.org/issue?@action=redirect&bpo=16488].)

devpoll オブジェクトに、メソッド fileno() とメソッド close() 、それに属性 closed が追加されました。 (Contributed by Victor Stinner in bpo-18794 [https://bugs.python.org/issue?@action=redirect&bpo=18794].)

shelve

Shelf がコンテキスト管理プロトコルをサポートするようになりました: with ブロックで使うとブロックの終了時に自動的にクローズされます。 (Contributed by Filip Gruszczyński in bpo-13896 [https://bugs.python.org/issue?@action=redirect&bpo=13896].)

shutil

copyfile() が、コピー元とコピー先が同じファイルの場合に Error の限定されたサブクラスである SameFileError を投げるようになりました。これにより、アプリケーションはこの特定のエラーでそれに相応しいアクションを取れます。 (Contributed by Atsuo Ishimoto and Hynek Schlawack in bpo-1492704 [https://bugs.python.org/issue?@action=redirect&bpo=1492704].)

smtpd

The SMTPServer and SMTPChannel classes now accept a map keyword argument which, if specified, is passed in to 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 [https://bugs.python.org/issue?@action=redirect&bpo=11959].)

smtplib

SMTPException が OSError のサブクラスになりました。これによって、とにかくエラーが起こったのだということにしか関心がないコードが、ソケット階層でのエラーと SMTP プロトコル階層の両エラーを一撃の try/except 文で捕捉出来るようになりました。 (Contributed by Ned Jackson Lovely in bpo-2118 [https://bugs.python.org/issue?@action=redirect&bpo=2118].)

socket

The socket module now supports the CAN_BCM protocol on platforms that support it. (Contributed by Brian Thorne in bpo-15359 [https://bugs.python.org/issue?@action=redirect&bpo=15359].)

ソケットオブジェクトで 継承可能フラグ を制御出来るようになりました。 get_inheritable() で取得し、 set_inheritable() でセットします。

定数値の socket.AF_* と socket.SOCK_* が、新規の enum モジュールを使った列挙値になりました。つまりデバッグなどで魑魅魍魎な整数ではなく徳高い名前で表示されるということです。

The AF_LINK constant is now available on BSD and OSX.

inet_pton() と inet_ntop() が Windows でサポートされるようになりました。 (Contributed by Atsuo Ishimoto in bpo-7171 [https://bugs.python.org/issue?@action=redirect&bpo=7171].)

sqlite3

connect() 関数に新規の真偽値パラメータ uri が追加されました。これを真にセットすると database パラメータを URI として解釈させることが出来ます。 (SQLite の URI のドキュメント [https://www.sqlite.org/uri.html] を参照してください)。 (Contributed by poq in bpo-13773 [https://bugs.python.org/issue?@action=redirect&bpo=13773].)

ssl

PROTOCOL_TLSv1_1 と PROTOCOL_TLSv1_2 (TLSv1.1 と TLSv1.2 のサポート) が追加されました。これらプロトコルのサポートは Python が OpenSSL 1.0.1 以降とリンクしている場合にのみ利用可能です。 (Contributed by Michele Orrù and Antoine Pitrou in bpo-16692 [https://bugs.python.org/issue?@action=redirect&bpo=16692].)

新規関数 create_default_context() は、互換性とセキュリティの間の程よいバランスとなるよう調整された SSLContext を得るための標準手段として追加されました。それらの設定は SSLContext コンストラクタが与えるデフォルトよりも厳しく、そして将来的にセキュリティにおけるベストプラクティスによる要請が変化すれば、事前予告なしで調整されるかもしれません。SSL をサポートする標準ライブラリの使用においての新しいベストプラクティスとして、 SSLContext を得るのには create_default_context() を使うことが推奨です。必要に応じ、対応する標準ライブラリ API の context 引数に渡すためにそれを使うよう修正してください。(Contributed by Christian Heimes in bpo-19689 [https://bugs.python.org/issue?@action=redirect&bpo=19689].)

SSLContext のメソッド load_verify_locations() にオプショナル引数 cadata が追加されました。これには PEM あるいは DER エンコードの証明書を直接指定できます。前者の場合は文字列で、後者では bytes-like object で指定します。(Contributed by Christian Heimes in bpo-18138 [https://bugs.python.org/issue?@action=redirect&bpo=18138].)

関数 get_default_verify_paths() が追加されました。これは set_default_verify_paths() メソッドが OpenSSL デフォルトの cafile と capath をセットするのに使うパスと環境変数から成る名前付きタプルを返します。デフォルトの検証にまつわる問題をデバッグするのに使えるでしょう。(Contributed by Christian Heimes in bpo-18143 [https://bugs.python.org/issue?@action=redirect&bpo=18143].)

SSLContext の新規メソッド cert_store_stats() はロードされた X.509 証明書、 X.509 CA 証明書、証明書失効リスト (crl) を報告し、また、新規メソッド get_ca_certs() はロードされた CA 証明書のリストを返します。(Contributed by Christian Heimes in bpo-18147 [https://bugs.python.org/issue?@action=redirect&bpo=18147].)

If OpenSSL 0.9.8 or later is available, SSLContext has a new attribute verify_flags that can be used to control the certificate verification process by setting it to some combination of the new constants VERIFY_DEFAULT, VERIFY_CRL_CHECK_LEAF, VERIFY_CRL_CHECK_CHAIN, or VERIFY_X509_STRICT. OpenSSL does not do any CRL verification by default. (Contributed by Christien Heimes in bpo-8813 [https://bugs.python.org/issue?@action=redirect&bpo=8813].)

SSLContext の新規メソッド load_default_certs() は、プラットフォームによって異なるデフォルトの場所から “認証局” (CA=certification authority) 証明書ファイル一式をロードします。クライアントがサーバを検証するための TLS web サーバ証明の証明書をロード (purpose=SERVER_AUTH) することも、サーバがクライアント証明書を検証するのに用いる証明書をロード (purpose=CLIENT_AUTH) することも出来ます。(Contributed by Christian Heimes in bpo-19292 [https://bugs.python.org/issue?@action=redirect&bpo=19292].)

Windows だけで利用出来る関数が 2 つ追加されました。 enum_certificates() と enum_crls() で Windows のシステム証明書ストアから、証明書、証明書の情報、CRLs (certification revocation=証明書失効リスト) を抽出出来ます。(Contributed by Christian Heimes in bpo-17134 [https://bugs.python.org/issue?@action=redirect&bpo=17134].)

新規メソッド ssl.SSLContext.set_servername_callback() によるサーバサイド SNI (Server Name Indication) サポートが追加されました。 (Contributed by Daniel Black in bpo-8109 [https://bugs.python.org/issue?@action=redirect&bpo=8109].)

SSLSocket.getpeercert() が返す辞書に X509v3 拡張アイテムを含むようになりました: crlDistributionPoints, caIssuers, OCSP URI。 (Contributed by Christian Heimes in bpo-18379 [https://bugs.python.org/issue?@action=redirect&bpo=18379].)

stat

stat モジュールが C 実装 _stat に基くようになりました。C 実装は、標準化されておらずプラットフォーム依存となる値のほとんどを取り込むために必要とされました。 (Contributed by Christian Heimes in bpo-11016 [https://bugs.python.org/issue?@action=redirect&bpo=11016].)

The module supports new ST_MODE flags, S_IFDOOR, S_IFPORT, and S_IFWHT. (Contributed by Christian Hiemes in bpo-11016 [https://bugs.python.org/issue?@action=redirect&bpo=11016].)

struct

関数 iter_unpack と、コンパイル済フォーマットでのメソッド struct.Struct.iter_unpack() が追加されました。これは、与えられたデータフォーマットの繰り返しインスタンスを含むバッファを逐次的にアンパックします。 (Contributed by Antoine Pitrou in bpo-17804 [https://bugs.python.org/issue?@action=redirect&bpo=17804].)

subprocess

check_output() が input 引数を受け付けるようになりました。これは実行するコマンドにとっての stdin を供給するのに使われます (訳注: run() のドキュメント参照)。 (Contributed by Zack Weinberg in bpo-16624 [https://bugs.python.org/issue?@action=redirect&bpo=16624].)

getstatus() と getstatusoutput() が Windows でも動作するようになりました。ただしこの変更は実際には、不注意で 3.3.4 に対して既に行われました。 (Contributed by Tim Golden in bpo-10197 [https://bugs.python.org/issue?@action=redirect&bpo=10197].)

sunau

The getparams() method now returns a namedtuple rather than a plain tuple. (Contributed by Claudiu Popa in bpo-18901 [https://bugs.python.org/issue?@action=redirect&bpo=18901].)

sunau.open() now supports the context management protocol: when used in a with block, the close method of the returned object will be called automatically at the end of the block. (Contributed by Serhiy Storchaka in bpo-18878 [https://bugs.python.org/issue?@action=redirect&bpo=18878].)

24 ビットサンプルの出力をサポートしました。つまり AU_write.setsampwidth() に 24 ビットに対応する値をセット出来ます。 (Contributed by Serhiy Storchaka in bpo-19261 [https://bugs.python.org/issue?@action=redirect&bpo=19261].)

The writeframesraw() and writeframes() methods now accept any bytes-like object. (Contributed by Serhiy Storchaka in bpo-8311 [https://bugs.python.org/issue?@action=redirect&bpo=8311].)

sys

新規関数 sys.getallocatedblocks() は、現在インタプリタによりアロケートされているブロック数を返します (デフォルトの --with-pymalloc 設定での CPython では、これは PyObject_Malloc() API によるアロケーションです)。これはメモリリークの追跡に、とりわけテストスイートで自動化されている場合はなおさら有用です。 (Contributed by Antoine Pitrou in bpo-13390 [https://bugs.python.org/issue?@action=redirect&bpo=13390].)

Python インタプリタが 対話モード で開始する際に sys モジュールの属性 __interactivehook__ をチェックするようになりました。この属性があると、対話モード開始直前にその設定値が引数なしで呼び出されます。このチェックは PYTHONSTARTUP ファイルが読み込まれたあとで行われるので、そのファイル内でセット出来ます。 site モジュールは readline をサポートするプラットフォームではタブ補完と (~/.python-history への) 履歴保存を有効にする関数を __interactivehook__ にセットします 。この (新たな) 振る舞いがお気に召さなければ、 PYTHONSTARTUP, sitecustomize, usercustomize のいずれかで sys からこの属性を削除 (あるいはほかのなにか callable をセット) してください。 (Contributed by Éric Araujo and Antoine Pitrou in bpo-5845 [https://bugs.python.org/issue?@action=redirect&bpo=5845].)

tarfile

tarfile モジュールはスクリプトや直接 -m で呼ばれた場合、簡単な コマンドラインインターフェイス をサポートするようになりました。これにより tar ファイルアーカイブの作成や解凍が可能です。 (Contributed by Berker Peksag in bpo-13477 [https://bugs.python.org/issue?@action=redirect&bpo=13477].)

textwrap

TextWrapper に 2 つ新しい制御変数が追加されていて、これらは属性値であり、コンストラクタ引数に渡せます。それぞれ max_lines が最大出力行数、 placeholder が max_lines により切り詰める場合に出力の最終行に置くテキストです。これら機能を使った新規のコンビニエンス関数 shorten() が追加されています。これは入力に含まれる全ての空白文字を単一の空白に置き換え、また幅 width に収めて、切り詰める場合は末尾を placeholder (デフォルトで [...]) で置き換えて、単一行で返します。(Contributed by Antoine Pitrou and Serhiy Storchaka in bpo-18585 [https://bugs.python.org/issue?@action=redirect&bpo=18585] and bpo-18725 [https://bugs.python.org/issue?@action=redirect&bpo=18725].)

threading

メインスレッドを表現する Thread オブジェクトを、新規関数 main_thread() で得られるようになりました。通常の条件であればこれは Python インタプリタを開始したスレッドになります。 (Contributed by Andrew Svetlov in bpo-18882 [https://bugs.python.org/issue?@action=redirect&bpo=18882].)

traceback

新規関数 traceback.clear_frames() は、トレースバックオブジェクトを受け取って、それが参照している全てのフレーム内のローカル変数をクリアすることで、メモリ消費量を削減します。 (Contributed by Andrew Kuchling in bpo-1565525 [https://bugs.python.org/issue?@action=redirect&bpo=1565525].)

types

新規デスクリプタ DynamicClassAttribute() は、そのアクセスがインスタンスからの場合には普通に振舞いつつクラスからのアクセスでは クラス の __getattr__ メソッドに振り向ける属性、これを定義する手段を提供します。このことにより、インスタンス上ではアクティブなプロパティを持ち、クラス上では同名の仮想的属性を持つ、といったことが出来ます (Enum がこれの実例になっています)。 (Contributed by Ethan Furman in bpo-19030 [https://bugs.python.org/issue?@action=redirect&bpo=19030].)

urllib

urllib.request が新規クラス DataHandler を介して data: URL をサポートするようになりました。 (Contributed by Mathias Panzenböck in bpo-16423 [https://bugs.python.org/issue?@action=redirect&bpo=16423].)

Request クラスで使われる HTTP メソッドを、サブクラスで method 属性をセットすることにより指定出来るようになりました。 (Contributed by Jason R Coombs in bpo-18978 [https://bugs.python.org/issue?@action=redirect&bpo=18978].) (---訳注: method は 3.3 で追加されたが、コンストラクタに渡されたものが設定されるだけだった。---)

Request オブジェクトは今では再利用可能です: full_url あるいは data 属性などが変更されると、関連する全ての内部プロパティが更新されます。このことによって今や、例えば、 Request オブジェクトを、異なる data 引数での OpenerDirector.open() の複数回呼び出し内で使ったり、あるいは、まっさらから作り直すのではなく Request の url を書き換えて使ったり出来ます。新たに remove_header() メソッドも追加されていて、これは Request からヘッダを取り除きます。 (Contributed by Alexey Kachayev in bpo-16464 [https://bugs.python.org/issue?@action=redirect&bpo=16464], Daniel Wozniak in bpo-17485 [https://bugs.python.org/issue?@action=redirect&bpo=17485], and Damien Brecht and Senthil Kumaran in bpo-17272 [https://bugs.python.org/issue?@action=redirect&bpo=17272].)

HTTPError オブジェクトに、エラーに関係する HTTP レスポンスヘッダへのアクセスを提供する headers 属性が追加されました。 (Contributed by Berker Peksag in bpo-15701 [https://bugs.python.org/issue?@action=redirect&bpo=15701].)

unittest

The TestCase class has a new method, subTest(), that produces a context manager whose with block becomes a "sub-test". This context manager allows a test method to dynamically generate subtests by, say, calling the 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:

class NumbersTest(unittest.TestCase):
    def test_even(self):
        for i in range(6):
            with self.subTest(i=i):
                self.assertEqual(i % 2, 0)

これは 6 つのサブテストとなり、それぞれは unittest 内の冗長出力において、変数名 i とその変数への個々の値 (i=0, i=1, など) からなるラベルで識別されます。この例の完全なバージョンが サブテストを利用して繰り返しテストの区別を付ける にあります。 (Contributed by Antoine Pitrou in bpo-16997 [https://bugs.python.org/issue?@action=redirect&bpo=16997].)

unittest.main() の defaultTest に、テスト名からなるイテラブルを渡せるようになりました。以前は文字列で単一のテスト名を渡せるだけでした。 (Contributed by Jyrki Pulliainen in bpo-15132 [https://bugs.python.org/issue?@action=redirect&bpo=15132].)

テストディスカバリ最中に発生する SkipTest (これはテストファイル内のモジュールレベルで起こせます) を、エラーとしてではなくスキップとして報告するようになりました。 (Contributed by Zach Ware in bpo-16935 [https://bugs.python.org/issue?@action=redirect&bpo=16935].)

discover() が発見したファイルをソートするようになったので、一貫したテスト順でテスト出来ます。 (Contributed by Martin Melin and Jeff Ramnani in bpo-16709 [https://bugs.python.org/issue?@action=redirect&bpo=16709].)

TestSuite がその実行完了次第すぐに、テスト成功していれば、テストへの参照を取り除くようになりました。ガーベージコレクションを行う Python インタプリタ上ではこの振る舞いによって、テストへの参照を保持しているものが他にない場合のテストのガーベージコレクトを可能にします。この振る舞いは TestSuite をサブクラス化して何もしない _removeTestAtIndex を定義することで上書き出来ます。 (Contributed by Tom Wardill, Matt McClure, and Andrew Svetlov in bpo-11798 [https://bugs.python.org/issue?@action=redirect&bpo=11798].)

テストアサーションの新規コンテキストマネージャ assertLogs() が追加されました。これはコードブロックが logging を使ってログメッセージを発行しているか確認します。デフォルトでは任意のロガーからの INFO 以上のプライオリティを持つメッセージを取れますが、ロガー名と最小プライオリティの両方とも指定可能です。コンテキストマネージャからの戻りオブジェクトに対して、ログされた LogRecord とフォーマットされたメッセージの両方あるいはどちらかを問い合わせることが出来ます。 (Contributed by Antoine Pitrou in bpo-18937 [https://bugs.python.org/issue?@action=redirect&bpo=18937].)

テストディスカバリが名前空間パッケージで動作するようになりました。 (Contributed by Claudiu Popa in bpo-17457 [https://bugs.python.org/issue?@action=redirect&bpo=17457].)

unittest.mock オブジェクトが、呼び出しが合致する際に仕様としてのシグニチャを検査するようになりました。これはつまり、以前は位置引数だけの合致だったものが、位置引数と名前の両方で合致できるようになったということです。(Contributed by Antoine Pitrou in bpo-17015 [https://bugs.python.org/issue?@action=redirect&bpo=17015].)

mock_open() オブジェクトに readline メソッドと readlines メソッドが追加されました。 (Contributed by Toshio Kuratomi in bpo-17467 [https://bugs.python.org/issue?@action=redirect&bpo=17467].)

venv

venv に csh と fish シェルの有効化スクリプトが追加されました。 (Contributed by Andrew Svetlov in bpo-15417 [https://bugs.python.org/issue?@action=redirect&bpo=15417].)

EnvBuilder クラスとコンビニエンス関数 create() が新規キーワード引数 with_pip を取るようになりました。デフォルトは False です。これは EnvBuilder が仮想環境に pip がインストールされていることを保証するかどうかを制御します。(Contributed by Nick Coghlan in bpo-19552 [https://bugs.python.org/issue?@action=redirect&bpo=19552] as part of the PEP 453 [https://peps.python.org/pep-0453/] implementation.)

wave

getparams() メソッドがプレインなタプルではなく namedtuple を返すようになりました。 (Contributed by Claudiu Popa in bpo-17487 [https://bugs.python.org/issue?@action=redirect&bpo=17487].)

wave.open() がコンテキスト管理プロトコルをサポートするようになりました。 (Contributed by Claudiu Popa in bpo-17616 [https://bugs.python.org/issue?@action=redirect&bpo=17616].)

wave は シーク不能なファイルへの書き出しが出来るように なりました。 (Contributed by David Jones, Guilherme Polo, and Serhiy Storchaka in bpo-5202 [https://bugs.python.org/issue?@action=redirect&bpo=5202].)

writeframesraw() メソッドと writeframes() メソッドが bytes-like object を受け付けるようになりました。 (Contributed by Serhiy Storchaka in bpo-8311 [https://bugs.python.org/issue?@action=redirect&bpo=8311].)

weakref

新規 WeakMethod クラスは、インスタンスメソッドへの弱参照をシミュレートします。 (Contributed by Antoine Pitrou in bpo-14631 [https://bugs.python.org/issue?@action=redirect&bpo=14631].)

新規クラス finalize は、弱参照自身のライフサイクルを注意深く管理する必要性なしに、オブジェクトがガーベージコレクトされる際に呼び出されるコールバックを登録することを可能にします。 (Contributed by Richard Oudkerk in bpo-15528 [https://bugs.python.org/issue?@action=redirect&bpo=15528].)

ref に関連付いたコールバック (あれば) を、新規属性 __callback__ で取得出来るようになりました。(Contributed by Mark Dickinson in bpo-17643 [https://bugs.python.org/issue?@action=redirect&bpo=17643].)

xml.etree

ノンブロッキングなアプリケーションでの XML ドキュメントの解析に、新規パーサ XMLPullParser を利用出来ます。実例は 非ブロックパースのためのプル API をみてください。 (Contributed by Antoine Pitrou in bpo-17741 [https://bugs.python.org/issue?@action=redirect&bpo=17741].)

xml.etree.ElementTree の関数 tostring() 、tostringlist() と、 ElementTree クラスの write() メソッドに、 キーワード専用引数 の short_empty_elements が追加されました。これはコンテンツを持たない要素を省略形 (<tag />) で書き出すか展開された形 (<tag></tag>) で書き出すかを制御します。(Contributed by Ariel Poliak and Serhiy Storchaka in bpo-14377 [https://bugs.python.org/issue?@action=redirect&bpo=14377].)

zipfile

PyZipFile クラスの writepy() メソッドに filterfunc オプションが追加されました。これはアーカイブにどのディレクトリ・ファイルを加えるのかをコントロールするのに使うことが出来ます。例えばテスト用ファイルをアーカイブから除外する、などということが出来ます。(Contributed by Christian Tismer in bpo-19274 [https://bugs.python.org/issue?@action=redirect&bpo=19274].)

ZipFile クラスと PyZipfile クラスの allowZip64 パラメータのデフォルトが True に変更されました。 (Contributed by William Mallard in bpo-17201 [https://bugs.python.org/issue?@action=redirect&bpo=17201].)

CPython の実装の変更

PEP 445: CPython のメモリアロケータのカスタマイズ

PEP 445 [https://peps.python.org/pep-0445/] は、CPython インタープリタのメモリ割り当てをカスタマイズするために新たな C 水準のインターフェイスを追加しました。

参考

PEP 445 [https://peps.python.org/pep-0445/] -- Python メモリアロケータをカスタマイズするための新 API 追加

PEP written and implemented by Victor Stinner.

PEP 442: オブジェクトの安全なファイナライゼーション

PEP 442 [https://peps.python.org/pep-0442/] は、 CPython でのオブジェクトのファイナライゼーションにまつわる現在の制限と奇癖を取り除きます。これによって、 __del__() メソッドを持つオブジェクトと finally 節を持つジェネレータが、それらが循環参照に含まれる場合もファイナライズ出来ます。(---訳注: ジェネレータの例については bpo-17468 [https://bugs.python.org/issue?@action=redirect&bpo=17468] から派生した bpo-17807 [https://bugs.python.org/issue?@action=redirect&bpo=17807] での修正 changeset 83688:c89febab4648 [https://hg.python.org/cpython/rev/c89febab4648] の Lib/test/test_generators.py に追加されたテスト参照。---)

この変更の一環で、モジュールのグローバルは、ほとんどのケースではインタプリタのシャットダウン中に強制的に None がセットされることはなくなり、代わりに循環ガーベージコレクタの通常のオペレーションに委ねます。このことは、循環 GC が最初に導入されて以来悩みの種だった、普通 __del__ メソッドを巻き込んだ「インタプリタシャットダウン時エラーの類」全体を回避します。(---訳注: bpo-18214 [https://bugs.python.org/issue?@action=redirect&bpo=18214] (superseder for bpo-812369 [https://bugs.python.org/issue?@action=redirect&bpo=812369]), changeset 84936:79e2f5bbc30c [https://hg.python.org/cpython/rev/79e2f5bbc30c/] ---)

参考

PEP 442 [https://peps.python.org/pep-0442/] -- オブジェクトの安全なファイナライゼーション

PEP written and implemented by Antoine Pitrou.

PEP 456: 安全で取り換え可能なハッシュアルゴリズム

PEP 456 [https://peps.python.org/pep-0456/] は、Python のハッシュアルゴリズムで行われた以前のセキュリティ修正作業 --- これは公に曝されている辞書検索に裏打ちされた API が標的になるかもしれない、特定の DOS 攻撃に対処するものです --- に追従するものです (この改善の現在ラウンドの事の起こりについては bpo-14621 [https://bugs.python.org/issue?@action=redirect&bpo=14621] を見てください)。この PEP では、 CPython のハッシュのコードをパッケージャが異なるハッシュアルゴリズムへの差し替えを容易にするために一元化し、そして Python のデフォルト実装としては 64 ビットデータ型を持つプラットフォームで SipHash に乗り換えます。以前の FNV アルゴリズムと比較したどんなパフォーマンスの差異も、些細なものです。

The PEP adds additional fields to the 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.

PEP 436: Argument Clinic

「Argument Clinic」(PEP 436 [https://peps.python.org/pep-0436/]) は CPython ビルドプロセスの新たな鍋の具です。ビルトインと標準ライブラリの拡張モジュールが C で実装されるにあたって、正確なシグニチャを定義し保守管理するプロセスを単純化するのに使えます。

Python 3.4 では既にいくつかの標準ライブラリ拡張モジュールが Argument Clinic を使うように変換されていて、またこれの結果として pydoc と inspect が更新されました。

Python 3.4 メンテナンスリリースでの更新の一部として C で実装されている callable に対して、プログラム的なイントロスペクションのためのシグニチャメタデータの追加が、さらに追加で行われることが期待されています。

注釈

Argument Clinic の PEP は、実装されている状態に対して完全には最新のものとはなっていません。Argument Clinic は Python 3.4 ではサードパーティに向けた公開 API として利用可能とする予定ではないので、このケースではリリース管理者とコア開発チームによって許容出来るとみなされました。

参考

PEP 436 [https://peps.python.org/pep-0436/] -- The Argument Clinic DSL (訳注: DSL=Domain-Specific Language)

PEP written and implemented by Larry Hastings.

その他のビルド並びに C API の変更

PyType_GetSlot() 関数が、安定 ABI に追加されました。これにより、制限 API を使う際に名前の付いた型のスロットから関数ポインタを取り出すことが出来ます。(Contributed by Martin von Löwis in bpo-17162 [https://bugs.python.org/issue?@action=redirect&bpo=17162].) (---訳注: 安定 ABI, 制限 API については What's New In Python 3.2 (PEP 384 [https://peps.python.org/pep-0384/]) を参照。---)

The new 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 [https://bugs.python.org/issue?@action=redirect&bpo=16129].)

文字列引数を変更することのない Python C API のほとんどが、 char * ではなく適切に const char * として宣言されました。 (Contributed by Serhiy Storchaka in bpo-1772673 [https://bugs.python.org/issue?@action=redirect&bpo=1772673].)

Python インタプリタが利用出来ない場合 (例えばクロスコンパイルのシナリオ) であっても使える、シェルで書き直したバージョンの python-config が追加されました。

PyUnicode_FromFormat() が %s, %A, %U, %V, %S, %R についての幅と精度の指定をサポートするようになりました。 (Contributed by Ysj Ray and Victor Stinner in bpo-7330 [https://bugs.python.org/issue?@action=redirect&bpo=7330].)

既存の PyStructSequence_InitType() 関数を補うものとして、 PyStructSequence_InitType2() が追加されました。違いは、これは成功時に 0 、失敗時に -1 を返すことです。

CPython のソースを、最近の GCC と clang のアドレスサニティチェック機能を使ってコンパイル出来るようにしました: 小さなオブジェクト用アロケータで起こっていた偽の警報を黙らせました。 (Contributed by Dhiru Kholia in bpo-18596 [https://bugs.python.org/issue?@action=redirect&bpo=18596].)

Windows ビルドに アドレス空間配置のランダム化 [https://en.wikipedia.org/wiki/Address_space_layout_randomization] と データ実行防止 [https://en.wikipedia.org/wiki/Data_Execution_Prevention] を使うようにしました。 (Contributed by Christian Heimes in bpo-16632 [https://bugs.python.org/issue?@action=redirect&bpo=16632].)

operator.length_hint() と等価な C API 関数 PyObject_LengthHint() が追加されました。 (Contributed by Armin Ronacher in bpo-16148 [https://bugs.python.org/issue?@action=redirect&bpo=16148].)

その他の改善

The python command has a new option, -I, which causes it to run in "isolated mode", which means that sys.path contains neither the script's directory nor the user's site-packages directory, and all PYTHON* environment variables are ignored (it implies both -s and -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 #! line of system scripts. (Contributed by Christian Heimes in bpo-16499 [https://bugs.python.org/issue?@action=redirect&bpo=16499].)

readline をサポートするプラットフォームで、対話インタプリタでの Tab キーでの補完がデフォルトで有効になりました。履歴もデフォルトで有効となり、 ~/.python-history に書き込まれ (そしてそこから読み込まれ) ます。 (Contributed by Antoine Pitrou and Éric Araujo in bpo-5845 [https://bugs.python.org/issue?@action=redirect&bpo=5845].)

Python インタプリタの --version での起動時、標準エラーではなく標準出力にバージョン情報を出力するようになりました (bpo-18338 [https://bugs.python.org/issue?@action=redirect&bpo=18338])。同じ変更は argparse モジュールに対して (bpo-18920 [https://bugs.python.org/issue?@action=redirect&bpo=18920])、また、スクリプトとして呼び出せる機能を持つモジュールに対して (bpo-18922 [https://bugs.python.org/issue?@action=redirect&bpo=18922]) も行われました。

CPython の Windows インストーラが、拡張子を登録する際に PATHEXT に .py を追加するようになりました。これをするとユーザは、 Windows コマンドプロンプトから Python スクリプトを、 .py 拡張子なしでその名前だけタイプして実行出来ます。 (Contributed by Paul Moore in bpo-18569 [https://bugs.python.org/issue?@action=redirect&bpo=18569].)

A new make target coverage-report [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 gcov and lcov [https://ltp.sourceforge.net/coverage/lcov.php].

python 回帰テストスイート への -R オプションが、 sys.getallocatedblocks() を使ったメモリアロケーションのリークもチェックするようになりました。(Contributed by Antoine Pitrou in bpo-13390 [https://bugs.python.org/issue?@action=redirect&bpo=13390].) (---訳注: リファレンスマニュアルにオプション説明はないので、 python -m test --help を参照して下さい。---)

python -m が名前空間パッケージで動くようになりました。

stat モジュールが C で実装されました。これは以前問題であった Python モジュール内で値をハードコードすることなく、定数を C ヘッダファイルから取りこめることを意味しています。(---訳注: bpo-11016 [https://bugs.python.org/issue?@action=redirect&bpo=11016] 、特に msg127114 [https://bugs.python.org/issue11016#msg127114] 以降参照。---)

単一の OS モジュール (POSIX の .so と Windows の .dll) からの複数 Python モジュールのロードを正しく行えるようになりました (以前は黙ってファイル内の最初のモジュールだけが返されていました)。 (Contributed by Václav Šmilauer in bpo-16421 [https://bugs.python.org/issue?@action=redirect&bpo=16421].)

新しい命令コード LOAD_CLASSDEREF が追加されました。これは __prepare__ のある種の使い方で起こりうる、クラス本体内の自由変数のロードでのバグを修正するために導入されました。(Contributed by Benjamin Peterson in bpo-17853 [https://bugs.python.org/issue?@action=redirect&bpo=17853].)

Victor Stinner が、彼の PEP 445 [https://peps.python.org/pep-0445/] ベースの pyfailmalloc ツールを用いて数多くのメモリエラー関連のクラッシュを特定し、そして修正しました。 (bpo-18408 [https://bugs.python.org/issue?@action=redirect&bpo=18408], bpo-18520 [https://bugs.python.org/issue?@action=redirect&bpo=18520])

pyvenv コマンドに、シンボリックリンクがデフォルトのシステムでもそうせずにコピーを使うようにするための --copies オプションが追加されました。 (Contributed by Vinay Sajip in bpo-18807 [https://bugs.python.org/issue?@action=redirect&bpo=18807].)

pyvenv コマンドにはさらに、そうしなければ自動的に仮想環境に pip がブートストラップされてしまうのを抑制するための、 --without-pip オプションが追加されました。(Contributed by Nick Coghlan in bpo-19552 [https://bugs.python.org/issue?@action=redirect&bpo=19552] as part of the PEP 453 [https://peps.python.org/pep-0453/] implementation.)

環境変数 PYTHONIOENCODING の値内で、エンコーディング名を省略出来るようになりました。つまり、デフォルトエンコーディングを変更することなしにエラーハンドラだけをセット出来ます。 (Contributed by Serhiy Storchaka in bpo-18818 [https://bugs.python.org/issue?@action=redirect&bpo=18818].)

bz2、lzma、gzip モジュールの open 関数が x (排他的作成) モードをサポートするようになりました。 (Contributed by Tim Heaney and Vajrasky Kok in bpo-19201 [https://bugs.python.org/issue?@action=redirect&bpo=19201], bpo-19222 [https://bugs.python.org/issue?@action=redirect&bpo=19222], and bpo-19223 [https://bugs.python.org/issue?@action=redirect&bpo=19223].)

大幅な最適化

UTF-32 デコーダが3-4倍速くなりました。 (Contributed by Serhiy Storchaka in bpo-14625 [https://bugs.python.org/issue?@action=redirect&bpo=14625].)

集合に対するハッシュ衝突のコストが削減されました。ハッシュテーブルの個々の検査 (probe) で、ハッシュテーブル全体を通したランダムな検査を行う前に、連続する隣接したキー/ハッシュペアをチェックするようになりました。これは、キャッシュ局所性を利用して衝突解決のコストを減らします。この衝突解決戦略は、リニア検査とオープンアドレッシング法のハイブリッドとして説明できます。追加的なリニア検査の数はデフォルトでは 9 です。この値は、コンパイル時に LINEAR_PROBES を定義することで任意の値に変更できます。リニア検査を完全に無効にするには LINEAR_PROBES=0 を設定してください。 (Contributed by Raymond Hettinger in bpo-18771 [https://bugs.python.org/issue?@action=redirect&bpo=18771].)

インタプリタの起動が約 30% 高速化されました。この速度向上は、いくつかの手段によってもたらされました。インタプリタは起動時により少数のモジュールをロードするようになりました。例えば re, collections, locale モジュール、およびそれらの依存モジュールは、デフォルトではインポートされません。 marshal モジュールは、コンパイルされた Python コードをより高速にロードできるように改善されました。 (Contributed by Antoine Pitrou, Christian Heimes and Victor Stinner in bpo-19219 [https://bugs.python.org/issue?@action=redirect&bpo=19219], bpo-19218 [https://bugs.python.org/issue?@action=redirect&bpo=19218], bpo-19209 [https://bugs.python.org/issue?@action=redirect&bpo=19209], bpo-19205 [https://bugs.python.org/issue?@action=redirect&bpo=19205] and bpo-9548 [https://bugs.python.org/issue?@action=redirect&bpo=9548].)

bz2.BZ2File が大半の場合 Python2 のバージョン以上に速くなりました。lzma.LZMAFile も最適化されました。(Contributed by Serhiy Storchaka and Nadeem Vawda in bpo-16034 [https://bugs.python.org/issue?@action=redirect&bpo=16034].)

random.getrandbits() が (通常使用される) 小さな整数に対して20%-40% 早くなりました。 (Contributed by Serhiy Storchaka in bpo-16674 [https://bugs.python.org/issue?@action=redirect&bpo=16674].)

文字列のストレージ形式を変更したことにより、文字列のピックル化は非常に速くなりました。(Contributed by Victor Stinner and Antoine Pitrou in bpo-15596 [https://bugs.python.org/issue?@action=redirect&bpo=15596].)

io.FileIO.readall() の性能問題が解決されました。これは特に Windows に影響し、 subprocess を通して大量のデータをパイプで渡しているケースでかなり速度向上します。 (Contributed by Richard Oudkerk in bpo-15758 [https://bugs.python.org/issue?@action=redirect&bpo=15758].)

html.escape() が10倍速くなりました。(Contributed by Matt Bryant in bpo-18020 [https://bugs.python.org/issue?@action=redirect&bpo=18020].)

Windows において、 obmalloc で CRT の malloc の代わりにネイティブの VirtualAlloc を使うようになりました。人工的なベンチマーク結果は、メモリー消費が 3% 減ったことを示しています。

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 [https://bugs.python.org/issue?@action=redirect&bpo=18756].)

非推奨

このセクションでは、Python 3.4 で非推奨となり Python 3.5 以降で削除予定となる、様々な API とその他機能性についてをカバーします。(全てではありませんが) ほとんどのケースで、非推奨に対する警告を (たとえば -Wd を使って) 有効にしたインタプリタ起動時、非推奨 API を使うと DeprecationWarning を励起します。

Python API の非推奨項目

As mentioned in PEP 451: インポートシステムのための ModuleSpec 型, a number of importlib methods and functions are deprecated: importlib.find_loader() is replaced by importlib.util.find_spec(); importlib.machinery.PathFinder.find_module() is replaced by importlib.machinery.PathFinder.find_spec(); importlib.abc.MetaPathFinder.find_module() is replaced by importlib.abc.MetaPathFinder.find_spec(); importlib.abc.PathEntryFinder.find_loader() and find_module() are replaced by importlib.abc.PathEntryFinder.find_spec(); all of the xxxLoader ABC load_module methods (importlib.abc.Loader.load_module(), importlib.abc.InspectLoader.load_module(), importlib.abc.FileLoader.load_module(), importlib.abc.SourceLoader.load_module()) should no longer be implemented, instead loaders should implement an exec_module method (importlib.abc.Loader.exec_module(), importlib.abc.InspectLoader.exec_module() importlib.abc.SourceLoader.exec_module()) and let the import system take care of the rest; and importlib.abc.Loader.module_repr(), importlib.util.module_for_loader(), importlib.util.set_loader(), and importlib.util.set_package() are no longer needed because their functions are now handled automatically by the import system.

The imp module is pending deprecation. To keep compatibility with Python 2/3 code bases, the module's removal is currently not scheduled.

formatter モジュールが撤廃保留中で、Python 3.6 での削除が計画されています。

hmac.new() 関数の digestmod がデフォルトで暗黙に MD5 を使う仕様は撤廃されます。Python 3.6 では digestmod 引数には明示的にダイジェスト名かコンストラクタを渡すことが求められます。

ftplib モジュール内の内部クラス Netrc はずっと長いことそのドキュメンテーション文字列内で非推奨であることを謳ってきました。これは今や DeprecationWarning を発行します。Python 3.5 ではこのクラスは完全に削除されます。

subprocess.Popen.wait() の文書化されていない引数 endtime は本来曝してはいけないものでしたので、使用されていないことを願っています。これは非推奨ですし、確実に Python 3.5 では削除されるのではないでしょうか。(---訳注: 3.5 では削除はされませんでしたが、もちろん使用しないでください。これは内部用です。---)

HTMLParser の strict 引数は非推奨です。

plistlib モジュールに追加された load(), dump(), loads(), dumps() により、対応する readPlist(), writePlist(), readPlistFromBytes(), writePlistToBytes() が非推奨となりました。同じく単に bytes コンストラクタを使えば良いので Data() が非推奨となりました。

sysconfig のキー SO は非推奨です。これは EXT_SUFFIX に取って代わられました。

種々の open 関数で受け付けられていた U モードは非推奨となりました。Python 3 ではこれは何も役に立つことはしません。 io.TextIOWrapper (必要ならば)、 newline 引数を適切に使うことによって置き換えられるはずです。

xml.etree.ElementTree.iterparse() の parser 引数と XMLParser() の html 引数が非推奨となりました。後者は (訳注: 第一引数のため) 削除に備えて XMLParser への全ての引数はキーワード引数として渡すようにしてください。

非推奨の機能

IDLE の -n フラグでの実行 (サブプロセスを起こさない) は非推奨となりました。ただし、この機能は bpo-18823 [https://bugs.python.org/issue?@action=redirect&bpo=18823] が解決するまでは削除はされません。

site モジュールは "site-python" ディレクトリが存在すればこれを sys.path に加えていましたが、これは非推奨となりました。 (bpo-19375 [https://bugs.python.org/issue?@action=redirect&bpo=19375])

削除

サポートされなくなったオペレーティングシステム

以下の OS 向けのソースとビルドツールは削除されました。

OS/2 (bpo-16135 [https://bugs.python.org/issue?@action=redirect&bpo=16135])。

Windows 2000 (changeset e52df05b496a [https://hg.python.org/cpython/rev/e52df05b496a])。

COMSPEC が command.com を指している Windows システム (bpo-14470 [https://bugs.python.org/issue?@action=redirect&bpo=14470]).

VMS (bpo-16136 [https://bugs.python.org/issue?@action=redirect&bpo=16136])。

API と機能の削除

時代遅れとなり、以前に既に非推奨となった以下の API と機能が削除されました:

保守されていなかった Misc/TextMate と Misc/vim ディレクトリは削除されました (代わりに何が使えるかの提案は devguide [https://devguide.python.org] をみてください --- 訳注: おそらく Additional Resources [https://devguide.python.org/#additional-resources] に挙げられている wiki [https://wiki.python.org/moin/PythonEditors] を指している ---)。

makefile のマクロ SO は削除されました (これは SHLIB_SUFFIX マクロと EXT_SUFFIX マクロで置き換えられました) (bpo-16754 [https://bugs.python.org/issue?@action=redirect&bpo=16754])。

PyThreadState.tick_counter フィールドは削除されました。これは Python 3.2 で「新しい GIL」が導入された際に意味をなくしていました。 (bpo-19199 [https://bugs.python.org/issue?@action=redirect&bpo=19199]).

PyLoader と PyPycLoader が importlib から削除されました。 (Contributed by Taras Lyapun in bpo-15641 [https://bugs.python.org/issue?@action=redirect&bpo=15641].)

HTTPConnection と HTTPSConnection の strict 引数は削除されました。 HTTP 0.9 スタイルの 「Simple Responses」はもはやサポートされません。

urllib.request.Request の非推奨となっていた getter/setter メソッドの add_data, has_data, get_data, get_type, get_host, get_selector, set_proxy, get_origin_req_host, is_unverifiable は削除されました (代わりに属性アクセスを直接使ってください)。

非推奨の TYPE_INT64 ロードのサポートが marshal から削除されました。 (Contributed by Dan Riti in bpo-15480 [https://bugs.python.org/issue?@action=redirect&bpo=15480].)

inspect.Signature: 位置専用パラメータを示すのに今では正当な名前が必要です。

object 自身の object.__format__() はもはや空でないフォーマット文字列を受け付けず、 TypeError を投げます。空でない文字列を渡すことは既に Python 3.2 で非推奨となっていました。この変更は以前は動作した (そして正しくない) コードが、オブジェクトが __format__ メソッドを得ることで処理に失敗し始めていた状況を防ぐ目的でなされました。この変更が意味することはあなたのコードにとって、それを処理する __format__ メソッドを持たないオブジェクトに s フォーマットコードを使うと TypeError を起こしうるようになった、ということです。背景については bpo-7994 [https://bugs.python.org/issue?@action=redirect&bpo=7994] を参照して下さい。 (---訳注: このパラグラフの中盤が非常にわかりにくい表現で訳者も意味を取りきれていませんが、おそらく Python 2.6/3.0 で動作していた例えば format(1+1j, '10s') が Python 2.7/3.1 で動作しなくなったことを指しているのだと思います。問題にされているのは動作しなくなったことではなくてむしろ動作していたことで、そして object.__format__ が return str(self).__format__(fmt) で実現されていること。このコードでは fmt は何らの意味も持っていませんので、これは一貫性に欠ける要因である、とのことで、「わかりやすく拒絶する」ことが真意であるようです ---)

Python 3.2 で非推奨となった difflib.SequenceMatcher.isbjunk() および difflib.SequenceMatcher.isbpopular() は削除されました: sm が SequenceMatcher であるとして、 x in sm.bjunk と x in sm.bpopular を使うようにしてください。 (bpo-13248 [https://bugs.python.org/issue?@action=redirect&bpo=13248])

コードの整理

pydoc モジュールで、使用されておらず文書化もされていなかった内部的な Scanner クラスが削除されました。

ひどく壊れていた OSX システムで呼ばれる可能性があるのみだった platform モジュールの非公開関数 _mac_ver_lookup, _mac_ver_gstalt, _bcd2str とあわせて、非公開かつ実質的に未使用だった _gestalt モジュールが削除されました。 (see bpo-18393 [https://bugs.python.org/issue?@action=redirect&bpo=18393])

tarfile モジュールの名前空間内に stat 定数群がハードコードでコピーされていましたが、これは削除されました。

Python 3.4 への移植

このセクションでは前述の変更とバグフィックスにより必要となるかもしれないコードの変更を列挙します:

'python' コマンドの挙動の変更

POSIX シェルでは、環境変数 PATH に空の値をセットすることは、何もセットしないことと同じです。ところが PYTHONPATH に空の値をセットすることは、何もセットしないことと まったく同じではありませんでした: PYTHONPATH に空の値をセットすると、 . をセットしたのと同じ意味になっていて、これは PATH での振舞いから類推しようとすると混乱を招くものでした。この振る舞いは PATH での POSIX の慣習に従うように改められました。

CPython インタプリタのデバッグビルド (--with-pydebug) での出力 [X refs, Y blocks] がデフォルトではオフになりました。 -X showrefcount オプション起動で再度有効に出来ます。 (Contributed by Ezio Melotti in bpo-17323 [https://bugs.python.org/issue?@action=redirect&bpo=17323].)

python コマンドとほとんどの標準ライブラリスクリプト (また argparse も) において、 --version が情報出力を stderr ではなく stdout に行うようになりました (issue へのリンクは その他の改善 セクション内参照)。

Python API の変更

importlib.abc 内に定義されている ABC は、無分別に NotImplementedError を投げるのではなく、相応しい例外を投げるかデフォルト値を返すかのどちらかになりました。このことは super() を呼び出して ABC がするがままに任せているコードにのみ影響します。互換性のために、必要であれば NotImplementedError とその投げられる新たな例外の両方を捕捉してください。

モジュール型が __package__ 属性と __loader__ 属性をデフォルトで None で初期化するようになりました。これら属性がセットされたかどうかを後方互換性のある方法で調べるには、たとえば getattr(module, '__loader__', None) is not None のようにしてください。 (bpo-17115 [https://bugs.python.org/issue?@action=redirect&bpo=17115].)

importlib.util.module_for_loader() now sets __loader__ and __package__ unconditionally to properly support reloading. If this is not desired then you will need to set these attributes manually. You can use importlib.util.module_to_load() for module management.

インポートがリロードの際に無条件に関連属性 (例えば __name__, __loader__, __package__, __file__, __cached__) をリセットするようになりました。これは、3.3 以前のリロードの際にモジュールを再発見する振る舞いと同じものを復元するものであるということを注記しておきます。 (bpo-19413 [https://bugs.python.org/issue?@action=redirect&bpo=19413])

凍結パッケージ (frozen package) はもはや __path__ にパッケージ名を含むリストをセットせず、空リストをセットします。この以前の振る舞いは、凍結パッケージと同じ名前を持つディレクトリが存在する場合のサブモジュールのインポートで、インポートシステムが間違ったことを起こしうるものでした。モジュールがパッケージなのかそうでないのかを決める正しい方法は、 hasattr(module, '__path__') を使うことです。 (bpo-18065 [https://bugs.python.org/issue?@action=redirect&bpo=18065])

Frozen modules no longer define a __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 __spec__.location is set to 'frozen', check if the loader is a subclass of importlib.machinery.FrozenImporter, or if Python 2 compatibility is necessary you can use imp.is_frozen().

py_compile.compile() が書き込み先ファイルパスがシンボリックリンクか非レギュラーファイルの場合に FileExistsError を投げるようになりました。これは、警告の役割を果たすためです、インポートがファイルパスの元のファイルタイプが何かによらずに、それらファイルをレギュラーファイルで上書きすることの。

ソースコードをロードしようとして SyntaxError かもしくは UnicodeDecodeError を引き起こした場合に、 importlib.abc.SourceLoader.get_source() はそれを ImportError に読み替えて投げることをしなくなりました。 ImportError はそうあるべきなのに見つからない場合にのみ投げられるべきなので、ソースコードが見つかったけれども正しくない構造である場合の意味にまで及ぶのは、手を伸ばし過ぎで過負荷です。ImportError を捕捉していたコードで今後とも構文エラーとデコーディングの問題を無視したいと望むならば、これら 3 つ全ての例外を捕捉するようにしてください。 (訳注: changeset 84172:e353f64dfd95 [https://hg.python.org/cpython/rev/e353f64dfd95] )

functools.update_wrapper() と functools.wraps() が、たとえその関数も __wrapped__ を持っていたとしても正しくその関数が包まれるように __wrapped__ 属性値をセットするようになりました。つまり __wrapped__ 属性は、以前のようにチェイン内の全ての __wrapped__ 属性が最も内側の関数を参照するのではなく、デコレートされた関数の積み上げを正しくリンクするようになったということです。以前の振る舞いが意図されたものであると思い込んでいたイントロスペクションライブラリの作者は、チェインの中の最初の関数 (__wrapped__ 属性を持たない) にアクセスするのに inspect.unwrap() を使えます。(---訳注: bpo-17482 [https://bugs.python.org/issue?@action=redirect&bpo=17482]. わかりにくいので実例で。中で適切に @wrap を使うデコレータ @deco1、@deco2 があるとして、my_func をこの両方でデコレートするとします。この場合に、Python 3.3 までは my_func.__wrapped__.__wrapped__ が AttributeError になります。今回のこの修正で my_func.__wrapped__.__wrapped__ は期待通りに振舞います。 ---)

inspect.getfullargspec() は、 inspect.signature() を前提とした再実装がなされました。これにより、かつて扱えていたよりも遥かに広い種類の呼び出し可能 (callable) を扱うようになりました (訳注: 例えば open() などは Python 3.3 までは扱えなかった)。Python 3.4 系列の経過のなかで、追加で組み込みや拡張モジュールの callable がシグニチャのメタデータを持つことが期待されています。 inspect.getfullargspec() が非 Python callable で失敗することを前提としたコードは、適宜調整の必要があるかもしれません。

importlib.machinery.PathFinder は sys.path_hooks 内のオブジェクトに、空文字列の場合は現在作業ディレクトリを渡すようになりました。結果の sys.path_importer_cache が決して '' を含まないことになるので、 sys.path に基いて sys.path_importer_cache を巡回しても全てのキーを見つけられません。インタプリタを -m で起動した場合も含め、現在作業ディレクトリ内でインポートされた際のモジュールの __file__ も絶対パスで持つようになりました (ただしスクリプトがコマンドラインから相対パスを使って直接実行された際の __main__.__file__ を除きます (Contributed by Brett Cannon in bpo-18416 [https://bugs.python.org/issue?@action=redirect&bpo=18416]))。 (bpo-18416 [https://bugs.python.org/issue?@action=redirect&bpo=18416])

HTTPConnection と HTTPSConnection から strict 引数が削除されたことは、残りの引数をキーワード引数としてではなく位置引数として使っていたなら意味が変わってしまいます。非推奨警告に注意を払ってきたのであれば、あなたのコードは既に全てのオプショナル引数をキーワードで渡しているはずです。

from __future__ import ... ステートメントの間に文字列が含まれる場合に 常に SyntaxError となるようになりました。以前はモジュールの docstring が先頭にある場合とない場合で振る舞いが違っていて、ない場合にこのエラーが意図せず無視される場合がありました。この修正は CPython を言語仕様に準拠させるものです。Jython と PyPy では既にこれが行われています。 (bpo-17434 [https://bugs.python.org/issue?@action=redirect&bpo=17434])

ssl.SSLSocket.getpeercert() と ssl.SSLSocket.do_handshake() は、 SSLSocket が未接続時に以前は AttributeError を投げていましたが、 ENOTCONN を持った OSError を投げるように改められました。加えて getpeercert() はハンドシェイクが未実施の場合に ValueError を投げるようになりました。

base64.b32decode() が入力文字列が非 b32 文字を含む場合に TypeError ではなく binascii.Error を投げるようになりました。今回のこの TypeError はほか (訳注: if the input is incorrectly padded のとき) の TypeError が置き換えられた際に置き換え忘れられたものでした。 (Contributed by Serhiy Storchaka in bpo-18011 [https://bugs.python.org/issue?@action=redirect&bpo=18011].) 注意: この修正は後方互換性を保てないので本来メンテナンスリリースの Python 3.3 には入るべきではなかったのですが、不注意で Python 3.3.3 にも行われてしまいました。

The file attribute is now automatically closed when the creating cgi.FieldStorage instance is garbage collected. If you were pulling the file object out separately from the cgi.FieldStorage instance and not keeping the instance alive, then you should either store the entire cgi.FieldStorage instance or read the contents of the file before the cgi.FieldStorage instance is garbage collected.

クローズ済みの SSL ソケットに対する read や write 呼び出しで、以前のようなミステリアスな AttributeError ではなく、役に立つ ValueError を投げるようになりました。 (bpo-9177 [https://bugs.python.org/issue?@action=redirect&bpo=9177])

slice.indices() が巨大な値で OverflowError を起こすことはなくなりました。この修正からの流れで slice.indices() は負の値に対して ValueError を投げるようになっています。以前はこれは馬鹿げた値を返していました。 (bpo-14794 [https://bugs.python.org/issue?@action=redirect&bpo=14794])

特殊メソッド __complex__ が複素数ではなく float を返す実装をしているオブジェクトを渡すと cmath 関数ではエラーとなり、 complex コンストラクタでは受け容れられていましたが、これはいずれも TypeError となるように改められました。(bpo-16290 [https://bugs.python.org/issue?@action=redirect&bpo=16290].)

3.2 と 3.3 での int コンストラクタが base パラメータとして誤って float を許容してしまっていました。それをわざわざやっているとも思えないですが、そうしていたなら今後は TypeError になります。 (bpo-16772 [https://bugs.python.org/issue?@action=redirect&bpo=16772])

キーワード専用引数へのデフォルト値が、通常のキーワード引数へのデフォルト値評価の あとで 評価されるようになりました。前ではなく。望むらくは誰一人以前のバギーな振る舞いに頼っちゃうおバカなコードを書いていませんように。願います。 (bpo-16967 [https://bugs.python.org/issue?@action=redirect&bpo=16967])

古いスレッド状態が fork() 後にクリアされるようになりました。これにより、以前は不適切に永遠に生き残ってしまっていたいくつかのシステムリソース (たとえば、スレッドローカル記憶内に維持されたデータベース接続) が解放されるようになります。 (bpo-17094 [https://bugs.python.org/issue?@action=redirect&bpo=17094].)

Parameter names in __annotations__ dicts are now mangled properly, similarly to __kwdefaults__. (Contributed by Yury Selivanov in bpo-20625 [https://bugs.python.org/issue?@action=redirect&bpo=20625].)

hashlib.hash.name が識別子を常に小文字で返すようになりました。以前はいくつかの組み込みハッシュが大文字名を持っていましたが、公式インターフェイスであることから、命名に一貫性を持たせるようにしました。 (bpo-18532 [https://bugs.python.org/issue?@action=redirect&bpo=18532])

unittest.TestSuite がその実行後にテストへの参照を取り除くようになったので、テスト集合を再実行するのに TestSuite を再利用してテストをまとめあげていると、テスト失敗するかもしれません。テストスイートはそのような方法で再利用すべきではありません。そのようなことをすればテスト実行間で状態が残ってしまうので、 unittest 設計の狙いであるテストの独立性を破壊してしまいます。とはいえ、独立性の欠如を受け容れてもいいと思うのであれば、 TestSuite をサブクラス化して何もしない _removeTestAtIndex を定義することで、古い振る舞いは復元出来ます (TestSuite.__iter__() 参照)。 (bpo-11798 [https://bugs.python.org/issue?@action=redirect&bpo=11798])

unittest がコマンドライン解析に argparse を使うようになりました。このことで、以前は動作していた不当なコマンド形式で許されなくなったものがあります。理屈から言えばこれは後方互換性の問題ではないはずです。許されなくなったコマンド形式は意味をなしていなかったものですから、使われていたとは思えません。

関数 re.split(), re.findall(), re.sub() と、 match オブジェクトのメソッド group(), groups() は、操作対象が bytes-like object である場合に常に bytes オブジェクトを返すようになりました。以前は戻り値型は入力型に合わせられていました。戻り値の型がたとえば bytearray になることに依存していたのであれば、コードを修正する必要があります。

audioop functions now raise an error immediately if passed string input, instead of failing randomly later on (bpo-16685 [https://bugs.python.org/issue?@action=redirect&bpo=16685]).

HTMLParser の新規引数 convert_charrefs は現在は後方互換性維持のために False をデフォルトとしていますが、最終的には True がデフォルトになります。あなたのコードでは HTMLParser の全ての呼び出しでこれをキーワード引数として明示することをお勧めします。 (bpo-13633 [https://bugs.python.org/issue?@action=redirect&bpo=13633])

hmac.new() 関数の digestmod 引数からデフォルト値が消える予定です。ので、 hmac.new() 呼び出しは常に digestmod を明示するように修正すべきです。 (bpo-17276 [https://bugs.python.org/issue?@action=redirect&bpo=17276])

sysconfig.get_config_var() にキー SO を渡すことと sysconfig.get_config_vars() の呼び出し結果から SO キーを探すことは非推奨です。このキーは文脈依存の EXT_SUFFIX または SHLIB_SUFFIX で置き換えられるべきです。 (bpo-19555 [https://bugs.python.org/issue?@action=redirect&bpo=19555])

open 系関数にモード U を使っていたコードは修正すべきです。 U は Python 3 では無力であり、いずれはこれの使用は例外を投げるようになる予定です。使う関数に依存しますが、 newline 引数を使うか、あるいは必要であればストリームを TextIOWrapper でラップしてその newline 引数を使うことで、その古い Python 2 の振る舞いと同等なものを実現出来ます。 (bpo-15204 [https://bugs.python.org/issue?@action=redirect&bpo=15204])

スクリプト内から pyvenv を使っていて、pip がインストール されない ことを望むならば、コマンド呼び出しに --without-pip を追加しなければなりません。

indent を明示した場合の json.dump() と json.dumps() のデフォルトの振る舞いが変更されました。要素を区切るカンマが行末に来る場合の後ろに、空白を追加しなくなりました。これはその出力のテストを空白に繊細な比較をすることで行っている場合にだけ問題になります。 (bpo-16333 [https://bugs.python.org/issue?@action=redirect&bpo=16333])

doctest が拡張モジュールの __doc__ 文字列から doctest を見つけるようになったので、doctest のテストディスカバリが拡張モジュールを含んでいてその中で doctest のようにみえるものが含まれていると、テスト実行時にこれまで見かけたことのないテスト失敗を目にするかもしれません。 (bpo-3158 [https://bugs.python.org/issue?@action=redirect&bpo=3158])

collections.abc モジュールが、Python スタートアップの改善の一環で少々リファクタリングが行われました。これの結果として collections は自動で collections.abc をインポートしなくなりました。もしもこの (文書化されていなかった) 暗黙でのインポートに依存していたのであれば、 import collections.abc として明示的にインポートを追加する必要があります。 (bpo-20784 [https://bugs.python.org/issue?@action=redirect&bpo=20784])

C API の変更

いくつかの内部 C API とともに PyEval_EvalFrameEx(), PyObject_Repr(), PyObject_Str() に、現在アクティブな例外を黙殺する状況で使われていないことを確かにするためのデバッグアサーションが仕込まれました。アクティブな例外を捨てることが期待されて望ましいケース (たとえば、既にローカルに PyErr_Fetch() で保存済みであるとか、異なる例外に置き換えることが意図である場合) は、アサーション有効でコンパイルされている Python バージョンで実行して、(直接的・間接的によらず) それら操作呼び出しがそのアサーションを発行するのを、明示的に PyErr_Clear() 呼び出しをすることで潰してください。

PyErr_SetImportError() が msg がセットされていない場合に TypeError をセットするようになりました。以前は例外をセットすることなく NULL を返すだけでした。

PyOS_ReadlineFunctionPointer コールバックは、エラー時に NULL を返すか PyMem_RawMalloc() または PyMem_RawRealloc() でアロケートした文字列を返さなければなりません。 PyMem_Malloc() や PyMem_Realloc() でアロケートした文字列はダメです。 (bpo-16742 [https://bugs.python.org/issue?@action=redirect&bpo=16742])

PyThread_set_key_value() が必ず値をセットするようになりました。Python 3.3 ではこの関数はキーが既存 (で現在値が NULL ポインタでない) の場合には何もしませんでした。

PyFrameObject 構造体のフィールド f_tstate (thread state) が、バグをフィックスするために削除されました: 論拠については bpo-14432 [https://bugs.python.org/issue?@action=redirect&bpo=14432] を参照してください。

3.4.3 の変更

PEP 476: stdlib http クライアントが証明書の検証を行うのをデフォルトで有効化

http.client とこのモジュールを使っている例えば urllib.request や xmlrpc.client が、サーバをプラットフォームが持つ信頼ストアにある CA により署名された証明書で検証し、そのホスト名がリクエストされたホスト名かどうかのチェックをデフォルトで行うようになりました。これは多くのアプリケーションにとって大幅なセキュリティ改善になります。

以前の古い振る舞いが必要なアプリケーションでは、代わりとなるコンテキストを渡せます:

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)

What's New In Python 3.3

この記事では 3.2 と比較した Python 3.3 の新機能を解説します。 Python 3.3 は2012年9月29日にリリースされました。全詳細については 変更履歴 [https://docs.python.jp/3.3/whatsnew/changelog.html] をご覧ください。

参考

PEP 398 [https://peps.python.org/pep-0398/] - Python 3.3 リリーススケジュール

概要 -- リリースハイライト

新たな文法機能:

ジェネレータの委譲. のための新しい yield from 式

str オブジェクト向けの u'unicode' 文法の再適用

新たなライブラリモジュール:

faulthandler (低水準のクラッシュのデバッグを補助する)

ipaddress (IPアドレスとマスクを表す高水準オブジェクト)

lzma (XZ / LZMA アルゴリズムを使用したデータ圧縮)

unittest.mock (テスト向けにシステムの一部をモックオブジェクトで置き換える)

venv (人気の virtualenv パッケージのような、Python virtual environments)

新たな組み込み機能:

I/O 例外階層 の手直し

実装の改善:

インポート機構 を、 importlib を元に書き換え

よりコンパクトな ユニコード文字列.

よりコンパクトな 属性辞書.

ライブラリモジュールの大幅な改善:

decimal モジュールのCによる高速化

email モジュールでのより良いユニコード処理 (暫定版)

セキュリティの改善:

ハッシュのランダム化がデフォルトで有効になりました。

以降はユーザ向けの変更の包括的なリストになっています。

PEP 405: 仮想環境

仮想環境 (virtual environment) は隔離されたPython環境を作成する手助けをします。一方で保守を容易にするために、システム全体のインストールを共有します。仮想環境はそれ自身の site packages (つまりローカルにインストールされたライブラリ) を持ちつつ、任意でシステム全体の site packages と分離できます。このコンセプトと実装は、人気のサードパーティパッケージである virtualenv を元にしていますが、インタプリタコアとの統合による恩恵を受けています。

この PEP はプログラムからのアクセス用の venv モジュールと、コマンドラインからのアクセスと管理向けの pyvenv スクリプトを追加します。Pythonインタプリタは仮想環境のディレクトリツリーの存在を示す pyvenv.cfg をチェックします。

参考

PEP 405 [https://peps.python.org/pep-0405/] - Python Virtual Environments

PEP written by Carl Meyer; implementation by Carl Meyer and Vinay Sajip

PEP 420: 暗黙的な名前空間パッケージ

__init__.py マーカーファイルを必要としないパッケージディレクトリと、複数のモジュールパスをネイティブでサポートします(PEP 420 [https://peps.python.org/pep-0420/] に記載された様々なサードパーティでの名前空間のアプローチに影響されています)

参考

PEP 420 [https://peps.python.org/pep-0420/] - Implicit Namespace Packages

PEP written by Eric V. Smith; implementation by Eric V. Smith and Barry Warsaw

PEP 3118: 新たなメモリビューの実装とバッファプロトコルのドキュメント

PEP 3118 [https://peps.python.org/pep-3118/] の実装が大幅に改善されました。

新しい memoryview 実装が、Py_buffer 構造体内にフィールドを動的にアロケートする際に多数のクラッシュの報告をもたらしていた全ての所有権問題、ライフタイム問題を包括的に解決しました。加えて、不連続もしくは多次元の入力に対してクラッシュしたり誤った結果を返していた多数の関数が修正されました。

memoryview オブジェクトに、 PEP-3118 準拠の getbufferproc() が追加されています (訳注: バッファオブジェクト構造体 (buffer object structure) 参照)。これはコンシューマの要求型をチェックします。多くの新機能が追加されており、これらのほとんどが不連続配列とサブオフセットを持つ配列に完全な一般化をもたらすものです。

ドキュメント が更新され、エキスポータ(提供側)とコンシューマ(利用側)両方についての責務をより明確に詳細化しています。 バッファ要求のフラグ が、基本フラグと組合せフラグでグループ分けされています。不連続配列と多次元の NumPy スタイル行列のメモリレイアウトについて説明されています。

フィーチャー

struct モジュールの構文の全ての native 書式指定文字 をサポートするようになりました ('@' プレフィクスが付いていても良いです)。 (訳注: format 参照。)

いくつかの制限はありますが、 cast() メソッドでフォーマット変更と C-contiguous 配列の形状 (shape) の変更を行うことが出来ます。

任意の配列型で多次元のリスト表現がサポートされるようになっています。

任意の配列型で多次元の比較がサポートされるようになっています。

'B', 'b', 'c' いずれかのフォーマットの hashable な (読み出し専用の) 型の1次元メモリビューもまた、 hashable です。 (Contributed by Antoine Pitrou in bpo-13411 [https://bugs.python.org/issue?@action=redirect&bpo=13411].)

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.

API の変更

最大 次元 は公式に 64 に制限されています。

空の shape, 空の strides, 空の suboffsets を表現するのに以前は None を用いていましたが今ではこれは空のタプルです。

フォーマット 'B' (unsigned bytes) での memoryview 要素へのアクセスは整数を返すようになりました (struct モジュールでの構文に従っています)。bytes オブジェクトが欲しければまずビューを 'c' で cast() しなければなりません。

memoryview どうしの比較は被演算対象の論理構造を使って行うようになり、また、全ての配列要素は値で比較されます。struct モジュールの構文の全てのフォーマット文字でサポートされます。認識出来ないフォーマット文字でのビューは今でも許されていますが、ビューの指す中身によらずこれは常に等しくないとされます。

ほかの変更については、 ビルドならびに C API の変更 と C コードの移植 を参照してください。

(Contributed by Stefan Krah in bpo-10181 [https://bugs.python.org/issue?@action=redirect&bpo=10181].)

参考

PEP 3118 [https://peps.python.org/pep-3118/] - Revising the Buffer Protocol

PEP 393: 文字列の柔軟な表現

Unicode 文字列型が、複数の内部表現 (1、2 または 4 バイトで表現される Unicode 序数(ordinal) の最大値依存) を、表現される文字列内でサポートするように変更されました (訳注: 以前までは Python のビルド時に固定で決めていました)。このことは全てのシステムにおいて、一般のケースでは空間効率の良い表現をしながらも UCS-4 へのフルアクセスを与えます。既存の API との互換性のために複数の表現が並行で存在することになりますが、徐々にこの互換性はなくされていくはずです。

Python 側にはこの変更による不都合は何もないはずです。

C API 側では PEP 393 [https://peps.python.org/pep-0393/] は完全に後方互換です。レガシーな API は最低 5 年は残されるはずです。レガシー API を使うアプリケーションはメモリ削減の効能が完全には得られないか、あるいは最悪の場合には少し余計なメモリを使うかもしれません。これは Python がそれぞれの文字列の二つのバージョン (レガシーなフォーマットと新しい効率的な格納方法) を維持する必要があるかもしれないからです

機能性

PEP 393 [https://peps.python.org/pep-0393/] でなされた変更は以下の通りです:

Python は今や非 BMP 面の文字を含む Unicode コードポイントの完全な範囲 (つまり U+0000 から U+10FFFF まで) を常にサポートします。narrow ビルド / wide ビルドという区別は今では存在していないため、Python は今ではいつでもかつての wide ビルドのように振る舞い、Windows でもこれは例外ではありません。

narrow ビルドとの決別は、それに付き物だった問題も解決しました。例えば:

len() は今では非 BMP 面文字について必ず 1 を返します。つまり len('\U0010FFFF') == 1 です;

サロゲートペアが文字列リテラル内で再結合されることはありません。つまり '\uDBFF\uDFFF' != '\U0010FFFF' です;

非 BMP 面文字を指すインデクスやスライスは期待通りの値を返します。つまり '\U0010FFFF'[0] は今では '\uDBFF' ではなく '\U0010FFFF' を返します;

ほかの全ての標準ライブラリ関数が今では正しく非 BMP コードポイントを処理します。

sys.maxunicode の値は今やいつでも 1114111 (十六進で 0x10FFFF) です。後方互換性のために C API の PyUnicode_GetMax() 関数は今でも 0xFFFF か 0x10FFFF のどちらかを返すようになってはいますが、新しい Unicode API とともには使ってはいけません (see bpo-13054 [https://bugs.python.org/issue?@action=redirect&bpo=13054])。

./configure スクリプトのフラグ --with-wide-unicode は削除されました。

性能およびリソース使用量

Unicode 文字列の記憶域サイズが文字列内のコードポイント最大値に依存するようになったということです:

純粋な ASCII と Latin1 文字列 (U+0000-U+00FF) はコードポイントごとに 1 バイトを占めます;

BMP 文字列 (U+0000-U+FFFF) はコードポイントごとに 2 バイトを占めます;

非 BMP 文字列 (U+10000-U+10FFFF) はコードポイントごとに 4 バイトを占めます。

結局のところほとんどのアプリケーションにとってのこれの効能は、文字列記憶のためのメモリ使用量が激減することで、これは以前の wide unicode ビルドと比較して顕著です。これは多くの場合、インターナショナルな文脈であってもなお純粋な ASCII が使われるであろうことに関係があります。(というのも多くの文字列が人間向けでない言語として格納されるからです。例えば XML フラグメンツや HTTP ヘッダ、JSON エンコードされたデータ、などなど。)同じ理由から、大きなアプリケーションで CPU キャッシュ活用効率を高めるであろうことも期待出来ます。Python 3.3 のメモリ使用は Python 3.2 の 2 倍から 3 倍小さく、また、Python 2.7 よりも少し良いことが Django ベンチマークでわかっています (詳細は PEP をみてください)。

参考

PEP 393 [https://peps.python.org/pep-0393/] - 文字列の柔軟な表現 (Flexible String Representation)

PEP written by Martin von Löwis; implementation by Torsten Becker and Martin von Löwis.

PEP 397: Windows の Python ランチャ

Python 3.3 の Windows インストーラが、ランチャアプリケーションの py をインストールするようになりました。これは Python をバージョンに依存しない方法で起動するのに使われます。

ランチャは *.py ファイルをダブルクリックすると暗黙のうちに呼び出されます。システムにインストールされているのが単一の Python バージョンであれば、そのバージョンがファイルの実行に使われます。複数バージョンがインストールされていればデフォルトでは最新バージョンが使われますが、Python スクリプト内で Unix スタイルの「shebang 行 ( #! )」を含めることでオーバライド出来ます。

ランチャは明示的にコマンドラインから py アプリケーションとして使うことも出来ます。 py の実行は暗黙にスクリプトを起動するバージョン選択のルールに従いますが、与えるコマンドライン引数により狙ったバージョンを選択出来ます (たとえば -3 は Python 2 もインストールされている際に Python 3 を要求し、 -2.6 はもっと新しいバージョンがインストールされている場合に特定の古いバージョンを要求します)。

ランチャに加え、Windows インストーラには新しくインストールする Python をシステムの PATH に追加するオプションが含まれるようになりました。 (Contributed by Brian Curtin in bpo-3561 [https://bugs.python.org/issue?@action=redirect&bpo=3561].)

参考

PEP 397 [https://peps.python.org/pep-0397/] - Python Launcher for Windows

PEP written by Mark Hammond and Martin v. Löwis; implementation by Vinay Sajip.

ランチャのドキュメント: Windows の Python ランチャ

インストーラ PATH の調整: Python 実行ファイルを見つける

PEP 3151: OS および IO 例外階層の手直し

OS エラーが送出する例外の階層が単純化され、粒度が下げられました。

OSError、IOError、EnvironmentError、WindowsError、mmap.error、socket.error、そして select.error の中から適切な例外の型を選ぶのに心配する必要はもうありません。上記の例外の型は全てたった1つ OSError になりました。 OSError 以外の名前は互換性のためにエイリアスとして残されています。

また、特定のエラー条件を捕捉するのが容易になりました。 errno 属性 (または args[0]) の特定の定数を errno モジュールから調べる代わりに、適切な OSError 派生クラスを捕捉することが出来ます。利用可能な派生クラスは以下の通りです:

BlockingIOError

ChildProcessError

ConnectionError

FileExistsError

FileNotFoundError

InterruptedError

IsADirectoryError

NotADirectoryError

PermissionError

ProcessLookupError

TimeoutError

ConnectionError 自身には細かな派生クラスがあります:

BrokenPipeError

ConnectionAbortedError

ConnectionRefusedError

ConnectionResetError

新たな例外のおかげで errno の一般的な使い方を避けることが出来ます。例えば、Python 3.2 向けに書かれた以下のコード:

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

は errno をインポートしたり手動で例外属性を調べたりせずに書くことが出来ます:

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")

参考

PEP 3151 [https://peps.python.org/pep-3151/] - Reworking the OS and IO Exception Hierarchy

PEP written and implemented by Antoine Pitrou

PEP 380: サブジェネレータへの委譲構文

PEP 380 は yield from 式を追加します。これは ジェネレータ に、その操作の一部をほかのジェネレータに委譲するための式です。これによって yield を含んでいるコードのセクションをほかのジェネレータに移動出来るでしょう。加えてサブジェネレータは値を伴って戻ることが出来、その戻り値は委譲した側のジェネレータで使えます。

yield from 式がデザインされた主たる動機はサブジェネレータへの委譲として使うことではありますが、実際には任意のサブイテレータに委譲することも出来ます。

単純なイテレータに対して、 yield from iterable は本質的には for item in iterable: yield item への単なる速記法です:

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

ですが普通のループとは違って yield from ではサブジェネレータは、呼び出し側スコープから send() されたり throw() された値を直接受け取ることができ、また、外側のジェネレータに最終的な値を返せます:

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

この変更を推し進める一番本質にあったものは、たとえ send メソッドや throw メソッドとともに使われることを前提に設計されたジェネレータであっても、大きな関数を複数のサブ関数に分割するのと同じくらいに、ジェネレータを簡単に複数のサブジェネレータに分割出来るようにすることでした。

参考

PEP 380 [https://peps.python.org/pep-0380/] - サブジェネレータへの委譲構文

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

PEP 409: 例外コンテキストの抑制

PEP 409 は、チェインされた例外コンテキストの表示を無効にするための新構文を導入します。これを使えば例外翻訳して投げ直すようなアプリケーションで、エラーメッセージをわかりやすくすることが出来ます:

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

元となる要因例外を抑制する from None を後置しなければ、もとの例外はデフォルトで表示されます:

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

抑制することでデバッグ能力が失われるというわけではなくて、元々の例外コンテキストは利用可能なままです。(例えば介在するライブラリが有益な背後の詳細を不適切に隠してしまっているなど、必要な場合はあるでしょう。)

>>> try:
...     D({}).x
... except AttributeError as exc:
...     print(repr(exc.__context__))
...
KeyError('x',)

参考

PEP 409 [https://peps.python.org/pep-0409/] - 例外コンテキストの抑制

PEP written by Ethan Furman; implemented by Ethan Furman and Nick Coghlan.

PEP 414: 明示的なユニコードリテラル

Unicode を意識する Python アプリケーションが Python 2 で Unicode リテラルを多用しているとしても Python 3 への移行を容易にするために、Python 3.3 では文字列リテラルへの "u" 前置を再びサポートすることにしました。この前置は Python 3 自身では何らの意味も持ちはせず、Python 3 への移行において純粋な機械的変更を要する事項を単に減らすためだけのために提供されます。開発者はもっと重要な意味的変更 (たとえばバイナリとテキストの厳密な区別) に集中すべきなのです。

参考

PEP 414 [https://peps.python.org/pep-0414/] - 明示的なユニコードリテラル

PEP written by Armin Ronacher.

PEP 3155: クラスと関数の正規名

関数オブジェクトとクラスオブジェクトは新たに __qualname__ 属性を持つようになりました。これはモジュールのトップレベルからその定義までの「道のり (path)」を表現するものです。グローバルな関数とクラスについてはこれは __name__ と同じです。ほかの場合にはこれは、実際に定義されている場所についてや、グローバルスコープから如何にしてアクセス可能かについて、もっと良い情報を与えてくれます。

(束縛されていない) メソッドでの例:

>>> class C:
...     def meth(self):
...         pass
...
>>> C.meth.__name__
'meth'
>>> C.meth.__qualname__
'C.meth'

入れ子のクラスでの例:

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

入れ子の関数の例:

>>> def outer():
...     def inner():
...         pass
...     return inner
...
>>> outer().__name__
'inner'
>>> outer().__qualname__
'outer.<locals>.inner'

それらオブジェクトの文字列表現も、この新しくてより正確な情報を含むように変更されています:

>>> str(C.D)
"<class '__main__.C.D'>"
>>> str(C.D.meth)
'<function C.D.meth at 0x7f46b9fe31e0>'

参考

PEP 3155 [https://peps.python.org/pep-3155/] - クラスと関数の正規名 (qualified name)

PEP written and implemented by Antoine Pitrou.

PEP 412: キー共有辞書

オブジェクト属性を記憶するのに使われる辞書が、内部記憶域の一部 (キーとそれに対応するハッシュ値) を互いに共有出来るようになりました。これにより、組み込みでない型のインスタンスをたくさん作るプログラムのメモリ消費が少なくなります。

参考

PEP 412 [https://peps.python.org/pep-0412/] - キー共有辞書

PEP written and implemented by Mark Shannon.

PEP 362: 関数シグニチャオブジェクト

新たに追加された関数 inspect.signature() は、Python 呼び出し可能オブジェクト (callable) を調べることを簡単で直接的なものにしてくれます。幅広い callable をサポートしています:デコレートされているかどうかによらず関数、クラス、 functools.partial() オブジェクト。新たに追加されたクラス群 inspect.Signature, inspect.Parameter, inspect.BoundArguments は、アノテーション、デフォルト値、パラメータの種類、束縛されている引数などのような呼び出しシグニチャについての情報を保持し、これによって、デコレータを書いたりあるいは呼び出しシグニチャや引数を検証したり改訂したりするコードを書くことが、非常に単純になります。

参考

PEP 362 [https://peps.python.org/pep-0362/]: - 関数シグニチャオブジェクト

PEP written by Brett Cannon, Yury Selivanov, Larry Hastings, Jiwon Seo; implemented by Yury Selivanov.

PEP 421: sys.implementation の追加

sys モジュールに新規属性が追加され、これは現在動作中のインタープリタ実装に固有の詳細を公開します。その sys.implementation 属性の手始めの集合として、 name, version, hexversion, cache_tag が定義されています。

sys.implementation の真意は、標準ライブラリによって利用される実装固有の情報を一つの名前空間で一元管理することにあります。このことにより異なる Python 実装が単一の標準ライブラリのコードベースを共有することが、もっとずっと簡単になります。今時点での初期状態では sys.implementation は実装固有データのごく一部を保持しているだけです。標準ライブラリの移植性がもっと高くなるように、徐々にこの比率が変わっていくでしょう。

標準ライブラリの移植性を改善した一例が cache_tag です。Python 3.3 以降は sys.implementation.cache_tag が PEP 3147 [https://peps.python.org/pep-3147/] をサポートするために importlib により使われます。組み込みのインポートシステムのために importlib を使う全ての Python 実装が、モジュールのキャッシュの振る舞いを制御するのに cache_tag を利用できます。

SimpleNamespace

sys.implementation の実現に伴って Python に新たな型 types.SimpleNamespace が導入されることとなりました。 dict のようなマッピングベースの名前空間とは対照的に、 SimpleNamespace は object のような属性ベースです。ですが object とは違って SimpleNamespace インスタンスは書き込み可能です。つまり普通の属性アクセスを通じて名前空間に追加したり削除したり修正したりできます。

参考

PEP 421 [https://peps.python.org/pep-0421/] - sys.implementation の追加

PEP written and implemented by Eric Snow.

インポート実装としての importlib の使用

bpo-2377 [https://bugs.python.org/issue?@action=redirect&bpo=2377] - Replace __import__ w/ importlib.__import__ bpo-13959 [https://bugs.python.org/issue?@action=redirect&bpo=13959] - Re-implement parts of imp in pure Python bpo-14605 [https://bugs.python.org/issue?@action=redirect&bpo=14605] - Make import machinery explicit bpo-14646 [https://bugs.python.org/issue?@action=redirect&bpo=14646] - Require loaders set __loader__ and __package__

__import__() 関数を importlib.__import__() によって実現するようにしました。これは PEP 302 [https://peps.python.org/pep-0302/] の「第二段階」を完了させるものです。この変更には複数の恩恵があります。まず最初にこれはインポートの機構を、C コードの奥深くで暗黙に秘密裏に行うのではなく、より透明化します。このことで、Python 3.3 をサポートする全ての Python VM で単一の実装を用いることが出来るようになり、インポートのセマンティクスにおける VM 固有の逸脱と決別する助けともなります。そしてこれはインポート機構の保守をより容易とし、将来起こりうる進化を促します。

一般のユーザにとっては、セマンティクスにおいて目に見える変化はないはずです。今時点でインポートを操作したりインポート呼び出しをプログラム的に行っている場合は、このドキュメントの Python コードの移植 でカバーしているコードの修正が必要になるかもしれません。

新たな API

この変更による一番大きな恩恵の一つは、インポート文の動作に何が介在するのかについて露になったことです。つまりかつては様々なインポータが暗黙で行っていたことが、今では完全に importlib パッケージの一部として公開されています。

The abstract base classes defined in importlib.abc have been expanded to properly delineate between meta path finders and path entry finders by introducing importlib.abc.MetaPathFinder and importlib.abc.PathEntryFinder, respectively. The old ABC of importlib.abc.Finder is now only provided for backwards-compatibility and does not enforce any method requirements.

In terms of finders, 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 sys.path_hooks.

ローダ (loader) については、新規の抽象基底クラス importlib.abc.FileLoader が、モジュールのコードを格納する機構としてのファイルシステムを使うローダを書く助けとなります。ソースファイルのローダ (importlib.machinery.SourceFileLoader)、ソースを持たないバイトコードのためのローダ (importlib.machinery.SourcelessFileLoader)、そして拡張モジュールのためのローダ (importlib.machinery.ExtensionFileLoader) が今では直接的に利用出来ます。

ImportError には属性 name と path が追加されて、これには提供すべき関連データがある場合にセットされます。インポート失敗時のメッセージも、これまでのようにモジュール名の末尾だけを与えるのではなく、モジュールの完全名を提供するようになりました。

The importlib.invalidate_caches() function will now call the method with the same name on all finders cached in sys.path_importer_cache to help clean up any stored state as necessary.

目に見える変化

潜在的に必要となるかもしれないコード修正については、 Python コードの移植 セクションを参照してください。

importlib によって公開されるものが拡がったことによる、インポートについてのほかの目に見える変化があります。最大の変化は sys.meta_path と sys.path_hooks が、インポートで使われる meta path finder と path entry hook の全てを格納するようになったことです。以前はファインダは直接的に公開されるのではなく、インポートの C コード内に暗黙のものとして隠されていました。このことによって、今では望めば要件に合うようファインダを取り除いたり順序を変えたりといったことが簡単に行えるようになっています。

もう一つの変化は、モジュール生成時に使われたローダを格納する __loader__ 属性を、全てのモジュールが持つようになったことです。 PEP 302 [https://peps.python.org/pep-0302/] はローダの実装においてこの属性をセットすることを必須とするよう更新されました。ですので今後サードパーティのローダが更新されれば、この属性の存在に依存出来るようになります。ですがそのときが来るまでは、インポート処理がモジュールのロードの後処理としてセットします。

さらにローダが PEP 366 [https://peps.python.org/pep-0366/] よりの __package__ 属性を設定することも期待出来るようになりました。繰り返しになりますがインポート処理自身が既にこれを全てのローダで importlib より行っていて、また、インポート処理自身がこの属性をロードの後処理としてセットしています。

None is now inserted into sys.path_importer_cache when no finder can be found on sys.path_hooks. Since imp.NullImporter is not directly exposed on sys.path_hooks it could no longer be relied upon to always be available to use as a value representing no finder found.

全てのほかの変更は、Python 3.3 へのコードの更新の際に考慮すべきセマンティクスの変更に関係しています。ですのでそららについて、このドキュメントの Python コードの移植 セクションを読むべきです。

(Implementation by Brett Cannon)

その他の言語変更

Python 言語コアに小さな変更がいくつか行われました:

Unicode name aliases [http://www.unicode.org/Public/UCD/latest/ucd/NameAliases.txt] と named sequences [http://www.unicode.org/Public/UCD/latest/ucd/NamedSequences.txt] のサポートが追加されました。 unicodedata.lookup() と '\N{...}' の両方が name aliases の解決を行い、 unicodedata.lookup() は named sequences の解決も行います。

(Contributed by Ezio Melotti in bpo-12753 [https://bugs.python.org/issue?@action=redirect&bpo=12753].)

Unicode データベースを UCD バージョン 6.1.0 にアップグレードしました。

range() オブジェクトどうしの等値性比較が、それぞれの range オブジェクトによって生成されるシーケンスの等値性を反映して行われるようになりました (bpo-13201 [https://bugs.python.org/issue?@action=redirect&bpo=13201])。

bytes と bytearray オブジェクトのメソッド count(), find(), rfind(), index(), rindex() が、第一引数に 0 から 255 の整数を受け付けるようになりました。

(Contributed by Petri Lehtinen in bpo-12170 [https://bugs.python.org/issue?@action=redirect&bpo=12170].)

bytes と bytearray オブジェクトのメソッド rjust(), ljust(), center() が、 fill 引数として bytearray を受け付けるようになりました (Contributed by Petri Lehtinen in bpo-12380 [https://bugs.python.org/issue?@action=redirect&bpo=12380].)。

list と bytearray に新規メソッド copy(), clear() が追加されました (bpo-10516 [https://bugs.python.org/issue?@action=redirect&bpo=10516])。これに伴い MutableSequence にも clear() メソッドが追加されました (bpo-11388 [https://bugs.python.org/issue?@action=redirect&bpo=11388])。

raw bytes リテラルとして br"..." だけでなく rb"..." とも書けるようになりました。

(Contributed by Antoine Pitrou in bpo-13748 [https://bugs.python.org/issue?@action=redirect&bpo=13748].)

dict.setdefault() が与えられたキーのルックアップを一度しか行わないようになったので、組み込み型でのこれの使用はアトミックになります。(訳注: 外部観察可能な変化で説明すると、以前はこの呼び出しが、キーの2回の __hash__、__eq__ 呼び出しを引き起こしていたものが、1回になった。)

(Contributed by Filip Gruszczyński in bpo-13521 [https://bugs.python.org/issue?@action=redirect&bpo=13521].)

関数呼び出しが関数シグニチャに合致しない場合のエラーメッセージがかなり改善されました。

(Contributed by Benjamin Peterson.)

細粒度のインポートロック

以前のバージョンの CPython では、常に大域的なインポートロックを当てにしていました。このことは意図せず頭痛の種を持ち込むこと繋がっていました。たとえば、モジュールをインポートすることで副作用として異なるスレッドでのコード実行を引き起こす際に起こる、デッドロックといったことです。不恰好な回避策がときどき採用されてきました。C API 関数 PyImport_ImportModuleNoBlock() などです。

Python 3.3 ではモジュールのインポートでは、モジュール単位でのロックを採用しています。このことによって複数スレッドからの指定モジュールのインポートは (モジュールが不完全な初期化のまま曝されるのを防いで) 正しく直列化されて、前述の頭痛の種は取り除かれています。

(Contributed by Antoine Pitrou in bpo-9260 [https://bugs.python.org/issue?@action=redirect&bpo=9260].)

組み込みの関数と型

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 os.O_CLOEXEC for example. The 'x' mode was added: open for exclusive creation, failing if the file already exists.

print(): flush キーワード引数が追加されました。flush キーワード引数が真の場合ストリームは強制的にフラッシュされます。

hash(): ハッシュのランダム化がデフォルトで有効になりました。 object.__hash__() と環境変数 PYTHONHASHSEED を参照してください。

str 型に casefold() メソッドが追加されました。文字列の casefold されたコピーを返します。casefold された文字列は、大文字小文字に関係ないマッチに使えます。例えば 'ß'.casefold() は 'ss' を返します。

シーケンスについてのドキュメントを大幅に書き換えました。バイナリのシーケンスとテキストのシーケンスについての区別についてより良い説明を加え、また、個々の組み込みシーケンスに関して個別のドキュメントを提供しています (bpo-4966 [https://bugs.python.org/issue?@action=redirect&bpo=4966])。

新たなモジュール

faulthandler

この新規モジュール faulthandler には、異常 (セグメンテーション違反のようなクラッシュ) 時、タイムアウト時、ユーザシグナルの発生時などのタイミングで Python traceback を明示的にダンプするための関数が含まれています。シグナル SIGSEGV, SIGFPE, SIGABRT, SIGBUS, SIGILL に対するフォールトハンドラをインストールするには、 faulthandler.enable() を呼び出してください。インタプリタ開始時点でも有効に出来ます。それには環境変数 PYTHONFAULTHANDLER をセットするか、コマンドラインオプション -X faulthandler を与えます。

Linuxでのセグメンテーションフォールト時の例:

$ 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

ipaddress

新規モジュール ipaddress は、IPv4/IPv6 アドレス、ネットワーク、インターフェース (すなわち固有の IP サブネットで関連付けられる IP アドレス) を表現するオブジェクトを生成したり加工したりするための道具立てを提供します。

(Contributed by Google and Peter Moody in PEP 3144 [https://peps.python.org/pep-3144/].)

lzma

The newly added lzma module provides data compression and decompression using the LZMA algorithm, including support for the .xz and .lzma file formats.

(Contributed by Nadeem Vawda and Per Øyvind Karlsen in bpo-6715 [https://bugs.python.org/issue?@action=redirect&bpo=6715].)

改良されたモジュール

abc

抽象メソッドで構成されるデスクリプタを含む抽象基底クラスのサポートが改善されています。抽象デスクリプタを宣言するために推奨されるアプローチは今後は、動的に更新されるプロパティとして __isabstractmethod__ を提供することです。この結果として、組み込みのデスクリプタが更新されました。

abc.abstractproperty は非推奨となりました。代わりに abc.abstractmethod() に property を渡して使ってください。

abc.abstractclassmethod は非推奨となりました。代わりに abc.abstractmethod() に classmethod を渡して使ってください。

abc.abstractstaticmethod は非推奨となりました。代わりに abc.abstractmethod() に staticmethod を渡して使ってください。

(Contributed by Darren Dale in bpo-11610 [https://bugs.python.org/issue?@action=redirect&bpo=11610].)

abc.ABCMeta.register() が登録されたサブクラスを返すようになりました。つまりクラスデコレータとして使うことができるようになったということです (bpo-10868 [https://bugs.python.org/issue?@action=redirect&bpo=10868])。

array

The array module supports the long long type using q and Q type codes.

(Contributed by Oren Tirosh and Hirokazu Yamamoto in bpo-1172711 [https://bugs.python.org/issue?@action=redirect&bpo=1172711].)

base64

base64 モジュールのモダンなインターフェイスのほうのデコード関数が、ASCII 文字のみで構成された Unicode 文字列を受け付けるようになりました。たとえば base64.b64decode('YWJj') は b'abc' を返します。 (Contributed by Catalin Iacob in bpo-13641 [https://bugs.python.org/issue?@action=redirect&bpo=13641].)

binascii

a2b_ 関数が、バイナリオブジェクトだけでなく ASCII 文字のみで構成された Unicode 文字列を入力として受け付けるようになりました。 (Contributed by Antoine Pitrou in bpo-13637 [https://bugs.python.org/issue?@action=redirect&bpo=13637].)

bz2

bz2 モジュールが最初から書き直されました。その過程で新機能がいくつか追加されました。

新たな bz2.open() 関数: bzip2 で圧縮されたファイルをバイナリかテキストモードで開きます。

bz2.BZ2File が、コンストラクタの fileobj 引数で、任意のファイル様オブジェクトの読み書きが出来るようになりました。

(Contributed by Nadeem Vawda in bpo-5863 [https://bugs.python.org/issue?@action=redirect&bpo=5863].)

bz2.BZ2File と bz2.decompress() が (pbzip2 ツールで生成されたような) マルチストリームの入力を展開出来るようになりました。同時に bz2.BZ2File は、 'a' (追記) モードを使ってこのタイプの圧縮ファイルを作るのに使えるようになりました。

(Contributed by Nir Aides in bpo-1625 [https://bugs.python.org/issue?@action=redirect&bpo=1625].)

bz2.BZ2File が、 io.BufferedIOBase API で規定されているメソッドや属性のうち、 detach() と truncate() を除くすべてを実装するようになりました。

codecs

mbcs コーデックが、全ての Windows バージョンでエラーハンドラ replace と ignore を正しく処理するように書き換えられました。 mbcs コーデックは以前は、エンコードでは replace のみ、デコードでは ignore のみでしたが、これにより全てのエラーハンドラがサポートされます。

新たに Windows のみ用のコーデック cp65001 が追加されました (bpo-13216 [https://bugs.python.org/issue?@action=redirect&bpo=13216])。これは Windows コードページ 65001 (Windows UTF-8, CP_UTF8) です。例えばこれはコンソール出力のコードページが (例えば chcp 65001 コマンドを使って) cp65001 にセットされている場合に sys.stdout で使われます。

マルチバイト CJK デコーダの再同期が高速になりました。これは不正なバイトシーケンスが最初のバイトであれば無視するだけです。例えば b'\xff\n'.decode('gb2312', 'replace') は文字置き換えののちに \n を返すようになっています。

(bpo-12016 [https://bugs.python.org/issue?@action=redirect&bpo=12016])

漸増的 CJK コーデックのエンコーダは以前は encode() メソッド呼び出しのたびにリセットしていましたが、リセットしなくなりました。例えば:

>>> import codecs
>>> encoder = codecs.getincrementalencoder('hz')('strict')
>>> b''.join(encoder.encode(x) for x in '\u52ff\u65bd\u65bc\u4eba\u3002 Bye.')
b'~{NpJ)l6HK!#~} Bye.'

この例の場合は以前の Python では b'~{Np~}~{J)~}~{l6~}~{HK~}~{!#~} Bye.' となっていました。

(bpo-12100 [https://bugs.python.org/issue?@action=redirect&bpo=12100])

unicode_internal コーデックは非推奨となりました。

collections

新たに追加されたクラス ChainMap は、複数のマッピングをひとまとまりに扱えるようにします。 (Written by Raymond Hettinger for bpo-11089 [https://bugs.python.org/issue?@action=redirect&bpo=11089], made public in bpo-11297 [https://bugs.python.org/issue?@action=redirect&bpo=11297].)

抽象基底クラス群は新しいモジュール collections.abc に移動しました。抽象コレクションと具象コレクションを識別しやすくするためです。これをインポートしている既存のコードを維持するために、 ABC の別名群が collections モジュール内に残されています。 (bpo-11085 [https://bugs.python.org/issue?@action=redirect&bpo=11085])

Counter クラスが、単項 + 演算子、単項 - 演算子、インプレイス演算子の +=, -=, |=, &= をサポートするようになりました。(Contributed by Raymond Hettinger in bpo-13121 [https://bugs.python.org/issue?@action=redirect&bpo=13121].)

contextlib

コンテキストマネージャをプログラム的に操作することと、これと類似のクリーンアップの機能性について、ExitStack が今後は確かな基礎を提供します。かつての (非推奨となり削除された) contextlib.nested API とは違って、この新しい API は、コンテキストマネージャがリソースを (たとえばファイルオブジェクトなどを) __init__ メソッドで獲得したのか、あるいは (たとえば threading モジュールからの同期オブジェクトを) __enter__ メソッドで獲得したのかとは無関係に正しく動作するように設計されました。

(bpo-13585 [https://bugs.python.org/issue?@action=redirect&bpo=13585])

crypt

Addition of salt and modular crypt format (hashing method) and the mksalt() function to the crypt module.

(bpo-10924 [https://bugs.python.org/issue?@action=redirect&bpo=10924])

curses

curses モジュールが ncursesw ライブラリとリンクしている場合に、 Unicode 文字列や Unicode 文字が渡されれば Unicode 関数 (例えば waddwstr())、それ以外の場合はバイト列用関数 (例えば waddstr()) を呼び出すようにしました。

Unicode 文字列をエンコードするのに utf-8 ではなく locale のエンコーディングを使うようになりました。(---訳注: bpo-12567 [https://bugs.python.org/issue?@action=redirect&bpo=12567] に対応した説明と思います。とすればこれは ワイド文字を受け取らない C 関数に渡す 際に Unicode をエンコードする際の話。このときに以前は暗黙で utf-8 でエンコードしていたのは「誤りである」ということのようです。 ---)

curses.window クラスに属性 curses.window.encoding が追加されました。

curses.window クラスに get_wch() メソッドが追加されました。これはワイド文字を一つ取得します。

curses モジュールに関数 unget_wch() が追加されました。これはワイド文字をプッシュし、次に get_wch() を呼び出した時にその値が返るようにします。

(Contributed by Iñigo Serna in bpo-6755 [https://bugs.python.org/issue?@action=redirect&bpo=6755].) (---訳注: 最初の2つはおそらく bpo-12567 [https://bugs.python.org/issue?@action=redirect&bpo=12567] --)

datetime

naive な datetime インスタンスと aware な datetime インスタンスの等価比較で、 TypeError を投げずに False を返すようになりました。 (bpo-15006 [https://bugs.python.org/issue?@action=redirect&bpo=15006]).

新規メソッド datetime.datetime.timestamp(): datetime インスタンスに対応する POSIX タイムスタンプを返します。

datetime.datetime.strftime() メソッドが 1000 年よりも前の書式化をサポートしました。(---訳注: What's New in Python 3.2 での変更も参照してみてください。---)

datetime.datetime.astimezone() メソッドを引数なしで呼び出せるようになりました。これは datetime インスタンスをシステムのタイムゾーンに変換します。

decimal

bpo-7652 [https://bugs.python.org/issue?@action=redirect&bpo=7652] - decimal 算術演算の、高速なネイティブ 実装の統合

C-module and libmpdec written by Stefan Krah.

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.

性能向上は、データベースアプリケーションで 10 倍から、数値計算が中心的なアプリケーションで 100 倍まで幅があります。この数字は、 10進数の浮動小数点計算において使われる標準的な精度における期待値です。精度はユーザが変更可能なので、正確な数字は変わる可能性があります。例えば、整数 bignum 計算では、違いはかなりより大きくなるかもしれません。

The following table is meant as an illustration. Benchmarks are available at https://www.bytereef.org/mpdecimal/quickstart.html.

decimal.py

_decimal

speedup

pi

42.02s

0.345s

120x

telco

172.19s

5.68s

30x

psycopg

3.57s

0.29s

12x

フィーチャー

FloatOperation シグナル により、float と Decimal の混合の厳密なセマンティクスを有効に出来ます。(---訳注: 使用例が クイックスタートチュートリアル にあります。---)

If Python is compiled without threads, the C version automatically disables the expensive thread local context machinery. In this case, the variable HAVE_THREADS is set to False.

API の変更

C モジュールはマシンアーキテクチャに依存する以下のコンテキストの制限を持ちます:

32-bit

64-bit

MAX_PREC

425000000

999999999999999999

MAX_EMAX

425000000

999999999999999999

MIN_EMIN

-425000000

-999999999999999999

In the context templates (DefaultContext, BasicContext and ExtendedContext) the magnitude of Emax and Emin has changed to 999999.

decimal.py の Decimal コンストラクタは上記のコンテキスト制限に無知で、任意の指数や精度で正確に変換しようとします。C 版は内部の制限を持っていますので、次の規則が使われます: 可能ならば値は正確に変換され、そうでない場合 InvalidOperation が送出されて結果が NaN となります。後者のケースは丸めあるいは不正確な値を得るために create_decimal() を使うことでいつでも可能です。(---訳注: わかりにくい表現ですがコンテキストで InvalidOperation をトラップしていれば結果が NaN で受け取れて(そうでなければ InvalidOperation が投げられて)、その制御は create_decimal で明示的に行える、ということを言っています。---)

The power function in decimal.py is always correctly rounded. In the C version, it is defined in terms of the correctly rounded exp() and ln() functions, but the final result is only "almost always correctly rounded".

C 版ではシグナルを含む辞書は MutableMapping です。速度的な理由により flags と traps はコンテキストが初期化された時点での MutableMapping を参照し続けます。新たなシグナル辞書を flags に traps 割り当てれば新しい値で更新はされるものの、コンテキストはそれら右辺の辞書を参照しません。

Context を pickle 化するとこれまでとは異なる出力をします。これは Python 版と C 版で共通の交換フォーマットを実現するためです。

Context コンストタクタの引数順が repr() での表示順に合うように改められました。

quantize() メソッドの watchexp パラメータが非推奨となりました。

email

ポリシーフレームワーク

email パッケージに policy フレームワークが追加されました。 Policy は、 email パッケージがどのように振舞うのかを制御するための多数のメソッドとプロパティを持つオブジェクトです。Python 3.3 のための最初のポリシーは Compat32 で、これは Python 3.2 の email パッケージとの後方互換性を提供します。 policy は、 parser によって email メッセージが解析される際、あるいは Message オブジェクトを生成する際、あるいは generator を用いて email がシリアライズする際に指定出来ます。オーバライドしない限りは、 parser に渡されたポリシーは全ての Message オブジェクトと parser が生成したサブオブジェクトに引き継がれます。デフォルトでは generator は、シリアライズしようとする Message オブジェクトのポリシーを使います。デフォルトのポリシーは compat32 です。

すべての policy オブジェクトで実装される制御の最小限のセットは以下です:

max_line_length

Message がシリアライズされる際に各行が持ちうる、linesep 文字(列)を含まない最大の行幅です。デフォルトでは 78 です。

linesep

Message がシリアライズされる際に各行を分割するのに使われる文字です。デフォルトは \n です。

cte_type

7bit または 8bit 。 8bit は Bytes generator に対してのみ適用され、プロトコルが許す場所 (あるいはオリジナルの入力に含まれる場所) には非 ASCII が使われうることを示します。

raise_on_defect

parser が異常を検出した場合に、 Message オブジェクトの defects リストに追加するのではなく例外を送出するようにします。

新たな設定値を持つ新しいポリシーインスタンスは、ポリシーオブジェクトの clone() メソッドを使って作られます。 clone は任意の上記制御値をキーワード引数として受け取ります。この呼び出しで指定されない制御はデフォルトのまま残されます。ですので linesep 文字列として \r\n を使うポリシーをこのようにして作れます:

mypolicy = compat32.clone(linesep='\r\n')

ポリシーは、あなたのアプリケーションが必要とするフォーマットでメッセージを生成するのを簡単にしてくれます。 generator を呼び出す全ての場所で linesep='\r\n' を指定するのを忘れないようにする代わりに、あなたのプログラムが Message オブジェクトを作成するために使う parser あるいは Message がポリシーを要求する一箇所だけで指定すれば良いのです。もちろん一方ではメッセージを複数の形式で生成する必要があれば、 generator 呼び出しのたびにパラメータで指定する必要があります。もしくは、あなた固有のケースのためにカスタムなポリシーを作って、 generator 作成の際にそれを渡すことも出来ます。

新規ヘッダ API を伴った暫定ポリシー

ポリシーフレームワーク単品でもまったくもって価値があるものではありますが、その導入の主たる動機は、それを使わないコードに対しての後方互換を壊さないやり方で、email パッケージに新機能を実現する新しいポリシーを作れるようにすることでした。その新しいポリシーは新規 API を導入するものなので、私たちはそれらを Python 3.3 での 暫定ポリシー としてリリースしました。コア開発者が必要と判断すれば、後方互換性を破壊する (コードの破棄さえも含む) 変更が起こりえます。

その新規ポリシーは EmailPolicy のインスタンス (訳注: email.policy.default や email.policy.SMTP など) です。これには以下の制御が追加されています:

refold_source

parser により解析されたヘッダを、 generator が折り返しし直す (refold) かどうかを制御します。 none, long, all のいずれかを指定します。デフォルトは long で、ソースのヘッダで max_line_length よりも長い行を refold します。 none はどの行も refold しません。 all は全ての行を refold します。

header_factory

name と value を引数に取り、カスタムなヘッダオブジェクトを生成する呼び出し可能 (callable) です。

header_factory が、この新規ポリシーにより提供される新機能の要です。この新規ポリシーの一つが使われると、 Message オブジェクトから抽出されたすべてのヘッダは header_factory で生成されるオブジェクトであり、また、 Message にヘッダをセットする場合のいつでも、それは header_factory で生成されるオブジェクトになります。すべてのその種のヘッダオブジェクトは、ヘッダ名と同名の name 属性を持ちます。アドレスヘッダと日付ヘッダは、ヘッダの解析済み日付にアクセス出来るよう、追加の属性群を持ちます。以下のように使えます:

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

Unicode の display name が、メッセージがシリアライズされる際に自動的に utf-8 (訳注: 実行例の場合は「の MIME ヘッダエンコード」) でエンコードされ、ヘッダに直接アクセスすると Unicode で返ることに気付くと思います。つまり email.header の decode_header() 関数や make_header() 関数を取り扱う必要性を取り除いてくれています。

アドレスを部品から組み立てることも出来ます:

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

Unicode へデコードするのは自動で行われます:

>>> m2 = message_from_string(str(m))
>>> m2['to']
'Éric <foo@example.com>'

メッセージ解析の際、グループと個々のアドレスにアクセスするのにヘッダオブジェクトの addresses 属性と groups 属性を使えます:

>>> 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'),))

要するに新規ポリシーのどれか一つを使うことは、ヘッダ操作をこのようなものにしてくれるということです: あなたのアプリケーションは Unicode 文字列でお仕事をし、email パッケージは Unicode のエンコード/デコードを透過的に行って RFC 標準 Content Transfer Encoding との相互変換をやってのける、と。

その他のAPIの変更

BytesHeaderParser が parser モジュールに追加されました。これは HeaderParser を補足するものであり、また、 bytes API を完全にする (訳注: What's New in Python 3.2 での email の変更内容参照) ものです。

新しいユーティリティ関数:

format_datetime(): datetime を与えると email ヘッダで使われる書式でフォーマットした文字列を生成します。

parsedate_to_datetime(): email ヘッダからの日付文字列を渡すと、 aware な、または naive な datetime に変換します。オフセットが -0000 の場合に naive で返します。

localtime(): 引数なしで呼び出すと、ローカル timezone を使った aware な datetime として現在ローカル時間を返します。aware な datetime を渡して呼び出すと、ローカル timezone を使った aware な datetime に変換します。

ftplib

ftplib.FTP に新しいキーワード引数 source_address が追加されました。 (host, port) の形で指定し、これは外に向かうソケットを作成する際に bind() 呼び出し内でのソースアドレスとして用いられます。 (Contributed by Giampaolo Rodolà in bpo-8594 [https://bugs.python.org/issue?@action=redirect&bpo=8594].)

FTP_TLS クラスに、制御チャネルを平文に戻すための ccc() 関数が追加されました。これは、固定ポートで開くことなく非セキュア FTP で NAT を処理する方法を知っているファイアウォールを利用するのに有用となりえます。(Contributed by Giampaolo Rodolà in bpo-12139 [https://bugs.python.org/issue?@action=redirect&bpo=12139].)

新規メソッド ftplib.FTP.mlsd() は機械で読めるディレクトリリスティングのフォーマットを提供し、 ftplib.FTP.nlst() と ftplib.FTP.dir() に取って代わるものとなりました。(Contributed by Giampaolo Rodolà in bpo-11072 [https://bugs.python.org/issue?@action=redirect&bpo=11072].)

functools

functools.lru_cache() デコレータにキーワード引数 typed を指定出来るようになりました (デフォルトは False です)。これは異なった型の等値比較のキャッシュ値を別々のキャッシュスロットに置くかどうかを決めます。(Contributed by Raymond Hettinger in bpo-13227 [https://bugs.python.org/issue?@action=redirect&bpo=13227].)

gc

ガーベージコレクタが回収前後に呼び出すコールバックを登録出来るようになりました。新規属性 callbacks リストに登録します。

hmac

タイミング解析によるダイジェストに対する サイドチャンネル攻撃 [https://en.wikipedia.org/wiki/Side-channel_attack] からの防御のために、 compare_digest() 関数が追加されました。(Contributed by Nick Coghlan and Christian Heimes in bpo-15061 [https://bugs.python.org/issue?@action=redirect&bpo=15061].)

http

http.server.BaseHTTPRequestHandler がヘッダをバッファするようになり、 end_headers() 呼び出し時に一度に全てをまとめて書き出すようになりました。新規のメソッド flush_headers() は、集積したヘッダを送信する場合の管理に直接使うことが出来ます。(Contributed by Andrew Schaaf in bpo-3709 [https://bugs.python.org/issue?@action=redirect&bpo=3709].)

http.server が正当な HTML 4.01 strict 出力を生成するようになりました。 (Contributed by Ezio Melotti in bpo-13295 [https://bugs.python.org/issue?@action=redirect&bpo=13295].)

http.client.HTTPResponse にメソッド readinto() が追加されました。つまりこのクラスを io.RawIOBase のように扱えるということです。 (Contributed by John Kuhn in bpo-13464 [https://bugs.python.org/issue?@action=redirect&bpo=13464].)

html

html.parser.HTMLParser が壊れたマークアップをエラーなしで解析出来るようになりました。これによりコンストラクタの strict 引数と HTMLParseError 例外が撤廃されました。この壊れたマークアップを解析出来る能力は数多くのバグフィックスからの結果であり、それらは Python 2.7/3.2 の最新バグフィックスリリースでも利用可能です。(Contributed by Ezio Melotti in bpo-15114 [https://bugs.python.org/issue?@action=redirect&bpo=15114], and bpo-14538 [https://bugs.python.org/issue?@action=redirect&bpo=14538], bpo-13993 [https://bugs.python.org/issue?@action=redirect&bpo=13993], bpo-13960 [https://bugs.python.org/issue?@action=redirect&bpo=13960], bpo-13358 [https://bugs.python.org/issue?@action=redirect&bpo=13358], bpo-1745761 [https://bugs.python.org/issue?@action=redirect&bpo=1745761], bpo-755670 [https://bugs.python.org/issue?@action=redirect&bpo=755670], bpo-13357 [https://bugs.python.org/issue?@action=redirect&bpo=13357], bpo-12629 [https://bugs.python.org/issue?@action=redirect&bpo=12629], bpo-1200313 [https://bugs.python.org/issue?@action=redirect&bpo=1200313], bpo-670664 [https://bugs.python.org/issue?@action=redirect&bpo=670664], bpo-13273 [https://bugs.python.org/issue?@action=redirect&bpo=13273], bpo-12888 [https://bugs.python.org/issue?@action=redirect&bpo=12888], bpo-7311 [https://bugs.python.org/issue?@action=redirect&bpo=7311].)

html.entities モジュールに、HTML5 名前付き文字参照と Unicode 文字(列) とを対応付ける html5 辞書が追加されました (例: html5['gt;'] == '>')。この辞書は既に HTMLParser が使っています。 (Contributed by Ezio Melotti in bpo-11113 [https://bugs.python.org/issue?@action=redirect&bpo=11113] and bpo-15156 [https://bugs.python.org/issue?@action=redirect&bpo=15156].)

imaplib

IMAP4_SSL コンストラクタが SSLContext パラメータを受け取るようになりました。これはセキュアなチャネルのパラメータを制御します。

(Contributed by Sijin Joseph in bpo-8808 [https://bugs.python.org/issue?@action=redirect&bpo=8808].)

inspect

getclosurevars() 関数が追加されました。この関数は、指定した関数の関数本体から参照されている現在束縛されている全ての名前と、それら名前が解決された場所 (訳注: globals, builtins など) を報告します。これにより、ステートフルなクロージャに依存するコードをテストするのに、正しい内部状態を検証するのが容易になります。

(Contributed by Meador Inge and Nick Coghlan in bpo-13062 [https://bugs.python.org/issue?@action=redirect&bpo=13062].)

getgeneratorlocals() 関数が追加されました。この関数は、指定したジェネレータのスタックフレーム内のローカル変数の、現在束縛されているものを報告します。これにより、ジェネレータをテストするのに、正しい内部状態を検証するのが容易になります。

(Contributed by Meador Inge in bpo-15153 [https://bugs.python.org/issue?@action=redirect&bpo=15153].)

io

open() 関数に排他的作成に使用する新たな 'x' モードが追加されました。ファイルが既に存在する場合は FileExistsError を送出します。 C11 fopen() の 'x' モードに基づいています。

(Contributed by David Townshend in bpo-12760 [https://bugs.python.org/issue?@action=redirect&bpo=12760].)

TextIOWrapper のコンストラクタにオプショナルな引数 write_through が追加されました。 write_through が True の場合、write() の呼び出しはバッファされないことが保証されます。 TextIOWrapper オブジェクトに書かれた全てのデータは直ちに下層のバイナリ buffer に処理されます。

itertools

accumulate() がユーザ提供二項関数を渡すためのオプショナル引数 func を受け付けるようになりました。

logging

basicConfig() 関数がオプショナルな handlers 引数をサポートするようになりました。これはルートロガーに追加するハンドラ群の イテラブル です。

SysLogHandler クラスに、クラスレベル属性の append_nul が追加されました。これは syslog レコードに NUL (\000) バイトを追加するかどうかを制御します。これはあるデーモンはこれで終端することが必要な一方でほかはメッセージの一部として NUL を通すという、デーモンによって振る舞いが異なることに対応するためです。

math

math モジュールに新たな関数 log2() が追加されました。x の 2 を底とする対数を返します。

(Written by Mark Dickinson in bpo-11888 [https://bugs.python.org/issue?@action=redirect&bpo=11888].)

mmap

read() メソッドの他のファイルライクなオブジェクトとの互換性が増しました。引数が省略されるか None の場合に、ファイルの現在位置からマッピングの末尾までのバイト列を返すようになっています。(Contributed by Petri Lehtinen in bpo-12021 [https://bugs.python.org/issue?@action=redirect&bpo=12021].)

multiprocessing

関数 multiprocessing.connection.wait() が追加されました。これは複数の (接続やソケット、パイプのような) オブジェクトをタイムアウト付きでポーリングします。(Contributed by Richard Oudkerk in bpo-12328 [https://bugs.python.org/issue?@action=redirect&bpo=12328].)

プロセス間で　(訳注: Connection.send() と Connection.recv() で) multiprocessing.Connection オブジェクトを相互に転送出来るようになりました。 (Contributed by Richard Oudkerk in bpo-4892 [https://bugs.python.org/issue?@action=redirect&bpo=4892].)

multiprocessing.Process がキーワード引数 daemon を取るようになりました。これは親プロセスから daemon フラグを継承するデフォルトの振る舞いをオーバライドします (bpo-6064 [https://bugs.python.org/issue?@action=redirect&bpo=6064])。

属性 multiprocessing.Process.sentinel が追加されました。これを用いることで、ふさわしい OS プリミティブ (例えば POSIX システムでの select) を使った一括での複数 Process オブジェクト待ちが可能です。

map() と itertools.starmap() との関係と同じ、既存の multiprocessing.pool.Pool.map() と map_async() に対応する multiprocessing.pool.Pool.starmap() と starmap_async() が追加されました。 (Contributed by Hynek Schlawack in bpo-12708 [https://bugs.python.org/issue?@action=redirect&bpo=12708].)

nntplib

The nntplib.NNTP class now supports the context management protocol to unconditionally consume socket.error exceptions and to close the NNTP connection when done:

>>> 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')
>>>

(Contributed by Giampaolo Rodolà in bpo-9795 [https://bugs.python.org/issue?@action=redirect&bpo=9795].)

os

The os module has a new pipe2() function that makes it possible to create a pipe with O_CLOEXEC or O_NONBLOCK flags set atomically. This is especially useful to avoid race conditions in multi-threaded programs.

os モジュールに sendfile() 関数が追加されました。これはあるファイル (またはソケット) 記述子からのコピーを、効率的な「ゼロコピー」で行います。「ゼロコピー」という言い回しは、これは二つの記述子間でのデータのコピー全てが完全にカーネルによって行われる、という事実について指しています。データコピーにユーザ空間のバッファは使われません。 sendfile() は例えばファイルのダウンロードのような、ディスク上のファイルとネットワークソケット間での効率的なデータコピーに使うことが出来ます。

(Patch submitted by Ross Lagerwall and Giampaolo Rodolà in bpo-10882 [https://bugs.python.org/issue?@action=redirect&bpo=10882].)

シンボリックリンク攻撃や一時ファイル、一時ディレクトリにまつわる問題のような競合状態を避けるには、ファイル名の代わりにファイル記述子を操作することがより信頼出来ます (そして高速でもあります)。 Python 3.3 はファイル記述子で動作するよう既存関数の強化と新規関数の追加を行ないました。 (bpo-4761 [https://bugs.python.org/issue?@action=redirect&bpo=4761], bpo-10755 [https://bugs.python.org/issue?@action=redirect&bpo=10755] and bpo-14626 [https://bugs.python.org/issue?@action=redirect&bpo=14626])

os モジュールの新規関数 fwalk() は walk() と似ていますが、これは訪問するディレクトリを指すファイル記述子も yield します。これは特にシンボリックリンクの競合を避けるために有用です。

関数 access(), chflags(), chmod(), chown(), link(), lstat(), mkdir(), mkfifo(), mknod(), open(), readlink(), remove(), rename(), replace(), rmdir(), stat(), symlink(), unlink(), utime() が、新たな 2 つのオプショナルなキーワード引数のどちらか、または両方をサポートするようになりました。 dir_fd (paths relative to directory descriptors) と follow_symlinks (not following symlinks) です。プラットフォームがそれらパラメータをサポートするかどうかは os.supports_dir_fd と os.supports_follow_symlinks を調べることでわかります。

関数 chdir(), chmod(), chown(), execve(), listdir(), pathconf(), exists(), stat(), statvfs(), utime() が、パス引数としてファイル記述子をサポートするようになりました。これをプラットフォームがサポートするかどうかは os.supports_fd を調べることでわかります。

access() がキーワード引数 effective_ids を受け取るようになりました。これは実 uid/gid の代わりに実効 uid/gid を使ってアクセスチェックを行うように振る舞いを変更します。これをプラットフォームがサポートするかどうかは supports_effective_ids を調べることでわかります。

os モジュールに 2 つの関数が追加されました。 getpriority() と setpriority() です。これらはプロセスのナイス値/優先度 (niceness/priority) を os.nice() と似た方法で取得・設定しますが、現在プロセスだけのものだけではなく全てのプロセスに対して使えるよう拡張されています。

(Patch submitted by Giampaolo Rodolà in bpo-10784 [https://bugs.python.org/issue?@action=redirect&bpo=10784].)

新規関数 os.replace() は変更先の上書きにおいてクロスプラットフォームな方法でファイル名変更を行えます。既存の os.rename() では、変更先が既存のファイルの場合に POSIX では上書き、Windows ではエラーとなります。(Contributed by Antoine Pitrou in bpo-8828 [https://bugs.python.org/issue?@action=redirect&bpo=8828].)

stat 系関数 (stat(), fstat(), lstat()) がファイルのタイムスタンプのナノ秒精度を読み取れるようになりました。これと対となる utime() もファイルのタイムスタンプをナノ秒精度で書き出せるようになりました。 (Contributed by Larry Hastings in bpo-14127 [https://bugs.python.org/issue?@action=redirect&bpo=14127].)

新規関数 os.get_terminal_size() はファイル記述子が接続しているターミナルウィンドウのサイズを取得します。 shutil.get_terminal_size() も参照して下さい。 (Contributed by Zbigniew Jędrzejewski-Szmek in bpo-13609 [https://bugs.python.org/issue?@action=redirect&bpo=13609].)

Linux 拡張属性をサポートするための新たな関数 (bpo-12720 [https://bugs.python.org/issue?@action=redirect&bpo=12720]): getxattr(), listxattr(), removexattr(), setxattr().

スケジューラに対する新たなインターフェイス。これら関数はプロセスに対する OS による CPU 時間割り当てを制御します。新規関数: sched_get_priority_max(), sched_get_priority_min(), sched_getaffinity(), sched_getparam(), sched_getscheduler(), sched_rr_get_interval(), sched_setaffinity(), sched_setparam(), sched_setscheduler(), sched_yield(),

ファイルシステムを制御する新たな関数:

posix_fadvise(): データへアクセスする意思を、パターンを指定して宣言します。これによりカーネルが最適化を行えるようになります。

posix_fallocate(): ファイルを割り当てるに十分なディスクスペースを確保します。

sync(): ディスクへの全ての書き込みを強制します。

追加された新たな POSIX 関数:

lockf(): オープンされたファイル記述子に対して、POSIX ロックの適用、テスト、解除を行います。

pread(): ファイル記述子の指定オフセット位置から読み込みます。ファイルオフセットは変化しません。

pwrite(): ファイル記述子に対し、指定オフセット位置から書き出します。ファイルオフセットは変化しません。

readv(): ファイル記述子からデータを読みこんで複数の書き込み可能なバッファに書き込みます。

truncate(): path に対応するファイルを、サイズが最大で length バイトになるよう切り詰めます。

waitid(): 一つ以上の子プロセスの完了を待ちます。

writev(): buffers の内容をファイル記述子へ書き出します。 buffer は任意のバッファのシーケンスです。

getgrouplist() (bpo-9344 [https://bugs.python.org/issue?@action=redirect&bpo=9344]): 指定したユーザが属するグループ ID のリストを返します。

times() および uname(): 戻り値の型がタプルから属性名のついたタプルライクオブジェクトに変更されました。

いくつかのプラットフォームにおいて、 lseek() 関数で使う追加の定数をサポートするようになりました。 os.SEEK_HOLE や os.SEEK_DATA などです。

New constants RTLD_LAZY, RTLD_NOW, RTLD_GLOBAL, RTLD_LOCAL, RTLD_NODELETE, RTLD_NOLOAD, and RTLD_DEEPBIND are available on platforms that support them. These are for use with the sys.setdlopenflags() function, and supersede the similar constants defined in ctypes and DLFCN. (Contributed by Victor Stinner in bpo-13226 [https://bugs.python.org/issue?@action=redirect&bpo=13226].)

クロスプラットフォームのサポートを簡単にするために、非 Windows 環境でも os.symlink() がキーワード引数 target_is_directory を受け付けるようになりました (単に無視します)。

pdb

Tab キーでの補完がコマンド名だけでなくその引数に対しても使えるようになりました。例えば break コマンドに対しては、関数、ファイル名が補完されます。

(Contributed by Georg Brandl in bpo-14210 [https://bugs.python.org/issue?@action=redirect&bpo=14210])

pickle

pickle.Pickler オブジェクトに pickler ごとのリダクション関数を設定する、オプショナルな dispatch_table 属性が追加されました。

(Contributed by Richard Oudkerk in bpo-14166 [https://bugs.python.org/issue?@action=redirect&bpo=14166].)

pydoc

Tk GUI と serve() 関数は pydoc モジュールから削除されました。 pydoc -g と serve() は Python 3.2 から既に非推奨となっていました。

re

str 正規表現が \u および \U エスケープをサポートしました。

(Contributed by Serhiy Storchaka in bpo-3665 [https://bugs.python.org/issue?@action=redirect&bpo=3665].)

sched

run() が blocking パラメータを取るようになりました。これを偽にセットすると、このメソッドは既に実行予定時間になっているイベント (もしあれば) を実行してすぐに戻ります。これは scheduler を非ブロッキングなアプリケーションで使いたい場合に有用です。 (Contributed by Giampaolo Rodolà in bpo-13449 [https://bugs.python.org/issue?@action=redirect&bpo=13449].) (---訳注: 原文の表現がわかりにくいですが、これは blocking=False 時はスケジュールされた時間になっているタスクがあれば通常は delayfunc を呼び出すところをそうせずに、一番早く次の予定時間に達するタスクの予定時間までの時間差を返します。---)

scheduler クラスをマルチスレッド環境で安全に使えるようになりました。 (Contributed by Josiah Carlson and Giampaolo Rodolà in bpo-8684 [https://bugs.python.org/issue?@action=redirect&bpo=8684].)

scheduler クラスのコンストラクタでのパラメータ timefunc と delayfunc が省略可能になりました。それぞれデフォルトで順に time.time(), time.sleep() が使われます。 (Contributed by Chris Clark in bpo-13245 [https://bugs.python.org/issue?@action=redirect&bpo=13245].)

enter() と enterabs() の argument パラメータが省略可能になりました。 (Contributed by Chris Clark in bpo-13245 [https://bugs.python.org/issue?@action=redirect&bpo=13245].)

enter() と enterabs() が kwargs パラメータを受け付けるようになりました。 (Contributed by Chris Clark in bpo-13245 [https://bugs.python.org/issue?@action=redirect&bpo=13245].)

select

Solaris とその派生プラットフォームにおいて、新規クラス select.devpoll が追加されました。これはハイパフォーマンスな非同期ソケットを /dev/poll 経由で提供するものです。 (Contributed by Jesús Cea Avión in bpo-6397 [https://bugs.python.org/issue?@action=redirect&bpo=6397].)

shlex

The previously undocumented helper function quote from the pipes modules has been moved to the shlex module and documented. quote() properly escapes all characters in a string that might be otherwise given special meaning by the shell.

shutil

新たな関数:

disk_usage(): ディスクの利用状況について、トータル、使用中、空きの容量を返します。 (Contributed by Giampaolo Rodolà in bpo-12442 [https://bugs.python.org/issue?@action=redirect&bpo=12442].)

chown(): 指定された path のユーザ、グループの両方あるいは一方を変更します。ユーザ、グループは名前もしくは数値での ID (uid, gid) で指定します。(Contributed by Sandro Tosi in bpo-12191 [https://bugs.python.org/issue?@action=redirect&bpo=12191].)

shutil.get_terminal_size(): インタプリタが接続しているターミナルウィンドウのサイズを取得します。 (Contributed by Zbigniew Jędrzejewski-Szmek in bpo-13609 [https://bugs.python.org/issue?@action=redirect&bpo=13609].)

copy2() と copystat() がファイルのタイムスタンプを、それをサポートするプラットフォームではナノ秒精度も維持するようになりました。また、Linux ではこれらは「拡張属性 (extended attributes)」もコピーするようになりました。 (Contributed by Larry Hastings in bpo-14127 [https://bugs.python.org/issue?@action=redirect&bpo=14127] and bpo-15238 [https://bugs.python.org/issue?@action=redirect&bpo=15238].)

いくつかの関数がオプショナルな symlinks 引数を取るようになりました。これが真の場合、シンボリックリンクの指す先を解決するのではなくシンボリックそのものに対しての操作をします (そうすることが必要であればシンボリックリンク作成もします)。(Contributed by Hynek Schlawack in bpo-12715 [https://bugs.python.org/issue?@action=redirect&bpo=12715].)

ファイルシステムをまたがったファイルのコピーの際に、 move() がシンボリックリンクを POSIX の move コマンドが行うのと同じやり方で扱うようになりました。つまりターゲットのファイルの中身をコピーするのではなくシンボリックリンクを再作成します。(Contributed by Jonathan Niehof in bpo-9993 [https://bugs.python.org/issue?@action=redirect&bpo=9993].) また、 move() は dst 引数を戻り値として返すようになりました。

os.open() と os.unlink() が新パラメータ dir_fd をサポートしているプラットフォームでは、 rmtree() は今では シンボリックリンク攻撃に耐性を持ちます。 (Contributed by Martin von Löwis and Hynek Schlawack in bpo-4489 [https://bugs.python.org/issue?@action=redirect&bpo=4489].)

signal

signal モジュールに新規関数が追加されました:

pthread_sigmask(): これを呼び出すスレッドにセットされているシグナルマスクを取り出したり変更したりします (Contributed by Jean-Paul Calderone in bpo-8407 [https://bugs.python.org/issue?@action=redirect&bpo=8407]);

pthread_kill(): スレッドにシグナルを送ります;

sigpending(): 保留中のシグナルを調べます;

sigwait(): シグナルを待ちます;

sigwaitinfo(): シグナルを待ちますが、それについての詳細情報を返します;

sigtimedwait(): sigwaitinfo() と似ていますがタイムアウト指定できます。

シグナルハンドラは wakeup ファイル記述子に以前は \0 を書き込んでいましたが、シグナル番号を 1 バイト整数として書き込むようにしました。これにより、一つ以上のシグナルを待った上でどのシグナルが発生したのかあとから調べるといったことが出来ます。

signal.signal() と signal.siginterrupt() は RuntimeError ではなく OSError を投げるようになりました: OSError は errno 属性を持っています。

smtpd

The smtpd module now supports RFC 5321 [https://datatracker.ietf.org/doc/html/rfc5321.html] (extended SMTP) and RFC 1870 [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 EHLO command.

(Initial 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 [https://bugs.python.org/issue?@action=redirect&bpo=8739])

smtplib

クラス SMTP, SMTP_SSL, LMTP に新しいキーワード引数 source_address が追加されました。 (host, port) の形で指定し、これは外に向かうソケットを作成する際に bind() 呼び出し内でのソースアドレスとして用いられます。(Contributed by Paulo Scardine in bpo-11281 [https://bugs.python.org/issue?@action=redirect&bpo=11281].)

SMTP がコンテキスト管理プロトコルをサポートするようになったので SMTP のインスタンスを with 文で使えます。 (Contributed by Giampaolo Rodolà in bpo-11289 [https://bugs.python.org/issue?@action=redirect&bpo=11289].)

SMTP_SSL コンストラクタと starttls() メソッドが SSLContext パラメータを受け取るようになりました。これはセキュアなチャネルのパラメータを制御します。 (Contributed by Kasun Herath in bpo-8809 [https://bugs.python.org/issue?@action=redirect&bpo=8809].)

socket

socket クラスが、前提となるプラットフォームがサポートしていれば従属的なデータを処理する追加のメソッドを公開しました:

sendmsg()

recvmsg()

recvmsg_into()

(Contributed by David Watson in bpo-6560 [https://bugs.python.org/issue?@action=redirect&bpo=6560], based on an earlier patch by Heiko Wundram)

socket クラスが Linux で (https://lwn.net/Articles/253425) PF_CAN プロトコルファミリ (https://en.wikipedia.org/wiki/Socketcan) をサポートしました。

(Contributed by Matthias Fuchs, updated by Tiago Gonçalves in bpo-10141 [https://bugs.python.org/issue?@action=redirect&bpo=10141].)

The socket class now supports the PF_RDS protocol family (https://en.wikipedia.org/wiki/Reliable_Datagram_Sockets and https://oss.oracle.com/projects/rds [https://web.archive.org/web/20130115155505/https://oss.oracle.com/projects/rds/]).

socket クラスが OS X で PF_SYSTEM プロトコルファミリをサポートするようになりました。 (Contributed by Michael Goderbauer in bpo-13777 [https://bugs.python.org/issue?@action=redirect&bpo=13777].)

New function sethostname() allows the hostname to be set on Unix systems if the calling process has sufficient privileges. (Contributed by Ross Lagerwall in bpo-10866 [https://bugs.python.org/issue?@action=redirect&bpo=10866].)

socketserver

BaseServer がオーバライド可能な service_actions() メソッドを持つようになり、これは serve_forever() によりサービスループ内で呼び出されます。 ForkingMixIn がこれをゾンビ化した子プロセスのクリーンアップに使っています。 (Contributed by Justin Warkentin in bpo-11109 [https://bugs.python.org/issue?@action=redirect&bpo=11109].)

sqlite3

sqlite3.Connection の新規のメソッド set_trace_callback() を使うと sqlite3 により処理されるすべての sql コマンドの足跡 (トレース) をキャプチャ出来ます。(Contributed by Torsten Landschoff in bpo-11688 [https://bugs.python.org/issue?@action=redirect&bpo=11688].)

ssl

ssl モジュールに新たに 2 つの乱数生成関数が追加されました:

RAND_bytes(): 暗号学的に強固な擬似乱数バイト列を生成します。

RAND_pseudo_bytes(): 擬似乱数バイト列を生成します。

(Contributed by Victor Stinner in bpo-12049 [https://bugs.python.org/issue?@action=redirect&bpo=12049].)

ssl モジュールがより粒度の細かい例外階層を公開するようになり、これにより様々な種類のエラーを調べることが容易になります。 (Contributed by Antoine Pitrou in bpo-11183 [https://bugs.python.org/issue?@action=redirect&bpo=11183].)

load_cert_chain() が password 引数を受け付けるようになりました。これは秘密鍵が暗号化されている場合に使われます。 (Contributed by Adam Simpkins in bpo-12803 [https://bugs.python.org/issue?@action=redirect&bpo=12803].)

ディフィー・ヘルマン鍵共有の、通常のものと楕円曲線ベースのもの両方が load_dh_params() メソッドと set_ecdh_curve() メソッドを通じてサポートされるようになりました。(Contributed by Antoine Pitrou in bpo-13626 [https://bugs.python.org/issue?@action=redirect&bpo=13626] and bpo-13627 [https://bugs.python.org/issue?@action=redirect&bpo=13627].)

SSL ソケットに新規メソッド get_channel_binding() が追加されました。これは SCRAM-SHA-1-PLUS (訳注: RFC 5802 [https://datatracker.ietf.org/doc/html/rfc5802.html] など参照) のようなある種の認証メカニズムの実装で拡張されることを想定したものです。(Contributed by Jacek Konieczny in bpo-12551 [https://bugs.python.org/issue?@action=redirect&bpo=12551].)

You can query the SSL compression algorithm used by an SSL socket, thanks to its new compression() method. The new attribute OP_NO_COMPRESSION can be used to disable compression. (Contributed by Antoine Pitrou in bpo-13634 [https://bugs.python.org/issue?@action=redirect&bpo=13634].)

ssl.SSLContext.set_npn_protocols() による Next Protocol Negotiation 拡張のサポートが追加されました。 (Contributed by Colin Marc in bpo-14204 [https://bugs.python.org/issue?@action=redirect&bpo=14204].)

属性 library と reason が追加されたので、SSL のエラーは以前よりもっと簡単に調べることが出来るようになりました。(Contributed by Antoine Pitrou in bpo-14837 [https://bugs.python.org/issue?@action=redirect&bpo=14837].)

get_server_certificate() 関数が IPv6 をサポートするようになりました。 (Contributed by Charles-François Natali in bpo-11811 [https://bugs.python.org/issue?@action=redirect&bpo=11811].)

New attribute OP_CIPHER_SERVER_PREFERENCE allows setting SSLv3 server sockets to use the server's cipher ordering preference rather than the client's (bpo-13635 [https://bugs.python.org/issue?@action=redirect&bpo=13635]).

stat

ドキュメントされていなかった tarfile.filemode 関数が stat.filemode() に移動されました。これはファイルモードを '-rwxrwxrwx' 形式の文字列に変換するのに使えます。

(Contributed by Giampaolo Rodolà in bpo-14807 [https://bugs.python.org/issue?@action=redirect&bpo=14807].)

struct

The struct module now supports ssize_t and size_t via the new codes n and N, respectively. (Contributed by Antoine Pitrou in bpo-3163 [https://bugs.python.org/issue?@action=redirect&bpo=3163].)

subprocess

POSIX プラットフォームにおいて、コマンド文字列として bytes オブジェクトを渡せるようになりました。 (Contributed by Victor Stinner in bpo-8513 [https://bugs.python.org/issue?@action=redirect&bpo=8513].)

A new constant DEVNULL allows suppressing output in a platform-independent fashion. (Contributed by Ross Lagerwall in bpo-5870 [https://bugs.python.org/issue?@action=redirect&bpo=5870].)

sys

sys モジュールに、スレッドの実装に関する情報が格納された 名前付きタプル を保持する thread_info が追加されました。 (bpo-11223 [https://bugs.python.org/issue?@action=redirect&bpo=11223])

tarfile

tarfile が lzma モジュールにより lzma エンコーディングをサポートするようになりました (Contributed by Lars Gustäbel in bpo-5689 [https://bugs.python.org/issue?@action=redirect&bpo=5689].)。

tempfile

tempfile.SpooledTemporaryFile の truncate() メソッドが size 引数を受け取るようになりました。 (Contributed by Ryan Kelly in bpo-9957 [https://bugs.python.org/issue?@action=redirect&bpo=9957].)

textwrap

textwrap モジュールに indent() が追加されました。これはテキストのブロック内の選択行に共通のプレフィクスを追加する簡単な方法になります。(bpo-13857 [https://bugs.python.org/issue?@action=redirect&bpo=13857])

threading

いずれもかつてインスタンスを返すファクトリ関数であった threading.Condition, threading.Semaphore, threading.BoundedSemaphore, threading.Event, threading.Timer がクラスになったので、サブクラス化出来るようになりました。 (Contributed by Éric Araujo in bpo-10968 [https://bugs.python.org/issue?@action=redirect&bpo=10968].)

threading.Thread コンストラクタがキーワード引数 daemon を取るようになりました。これは親スレッドから daemon フラグを継承するデフォルトの振る舞いをオーバライドします (bpo-6064 [https://bugs.python.org/issue?@action=redirect&bpo=6064])。

かつての非公開関数 _thread.get_ident が公開関数 threading.get_ident() として利用可能となっています。これは標準ライブラリにおいて多数の _thread モジュールへの直接アクセスを取り除く結果になりました。 _thread.get_ident を使っているサードパーティのコードも同じように、新しく公開化されたインターフェイスに乗り換えるべきです。

time

PEP 418 [https://peps.python.org/pep-0418/] が time モジュールに新たな関数を追加しました:

get_clock_info(): クロックの情報を取得します。

monotonic(): 単調なクロック (逆行しない)、システムクロックの更新の影響を受けません。

perf_counter(): 短期間の計測のために利用可能な最高の解像度を持つパフォーマンスカウンタです。

process_time(): 現在のプロセスの system と user CPU 時間の和です。

その他の新たな関数:

clock_getres(), clock_gettime() and clock_settime() functions with CLOCK_xxx constants. (Contributed by Victor Stinner in bpo-10278 [https://bugs.python.org/issue?@action=redirect&bpo=10278].)

クロスプラットフォーム間での一貫性を改善するために、 sleep() が負の値を渡すと ValueError を投げるように変更されています。以前から POSIX システムではエラーでしたが、Windows の場合に無限に sleep していました。

types

新規クラス types.MappingProxyType の追加: 読み出し専用のマッピングのプロキシです。 (bpo-14386 [https://bugs.python.org/issue?@action=redirect&bpo=14386])

新規関数 types.new_class() と types.prepare_class() は PEP 3115 [https://peps.python.org/pep-3115/] 準拠の動的な型の生成サポートを提供します。(bpo-14588 [https://bugs.python.org/issue?@action=redirect&bpo=14588])

unittest

メソッド assertRaises(), assertRaisesRegex(), assertWarns(), assertWarnsRegex() が、コンテキストマネージャとして使われる際にキーワード引数 msg を受け付けるようになりました。 (Contributed by Ezio Melotti and Winston Ewert in bpo-10775 [https://bugs.python.org/issue?@action=redirect&bpo=10775].)

unittest.TestCase.run() が TestResult オブジェクトを返すようになりました。

urllib

Request クラスが get_method() で使われる method 引数を受け付けるようになりました。これはどの HTTP メソッドが使われるべきかを指定します。例えば以下は 'HEAD' リクエストを送信します:

>>> urlopen(Request('https://www.python.org', method='HEAD'))

(bpo-1673007 [https://bugs.python.org/issue?@action=redirect&bpo=1673007])

webbrowser

webbrowser モジュールがさらに多くの "browsers" をサポートしました: Google Chrome (バージョンと OS 依存で名前が chrome, chromium, chrome-browser, あるいは chromium-browser) と、汎用のランチャ xdg-open (FreeDesktop.org プロジェクトのもの) と gvfs-open (GNOME 3 のデフォルト URI ハンドラ)。 (The former contributed by Arnaud Calmettes in bpo-13620 [https://bugs.python.org/issue?@action=redirect&bpo=13620], the latter by Matthias Klose in bpo-14493 [https://bugs.python.org/issue?@action=redirect&bpo=14493].)

xml.etree.ElementTree

xml.etree.ElementTree モジュールはデフォルトで C 実装による高速版をインポートするようになりました; もう明示的に xml.etree.cElementTree をインポートする必要はありません (cElementTree モジュールは後方互換のために残されますが非推奨となりました)。また、 Element クラスの iter 系のメソッドに最適化が施されました (C で再実装されました)。また、このモジュールのドキュメントは大幅に改善されて、実例が追加され、さらに詳細なリファレンスになりました。

zlib

New attribute 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 [https://bugs.python.org/issue?@action=redirect&bpo=12646].)

New attribute zlib.ZLIB_RUNTIME_VERSION reports the version string of the underlying zlib library that is loaded at runtime. (Contributed by Torsten Landschoff in bpo-12306 [https://bugs.python.org/issue?@action=redirect&bpo=12306].)

最適化

大きな性能向上がありました:

PEP 393 [https://peps.python.org/pep-0393/] により、Unicode 文字列に対する操作が最適化されました:

メモリフットプリントはテキストに依存して 1/2 から 1/4 になりました

ASCII 文字列を UTF-8 にエンコードするのに文字をエンコードする必要はなくなりました、UTF-8 表現は ASCII 表現と共有されます

UTF-8 エンコーダが最適化されました

単一の ASCII 文字を繰り返して ASCII 文字列の部分列を得るのは 4 倍速くなりました

UTF-8 が2倍から4倍速くなりました。UTF-16 のエンコーディングが最大で10倍速くなりました。

(Contributed by Serhiy Storchaka, bpo-14624 [https://bugs.python.org/issue?@action=redirect&bpo=14624], bpo-14738 [https://bugs.python.org/issue?@action=redirect&bpo=14738] and bpo-15026 [https://bugs.python.org/issue?@action=redirect&bpo=15026].)

ビルドならびに C API の変更

Python のビルド過程と C API の変更は以下の通りです:

新しい PEP 3118 [https://peps.python.org/pep-3118/] 関連の関数:

PyMemoryView_FromMemory()

PEP 393 [https://peps.python.org/pep-0393/] により追加された新たな Unicode 型、マクロ、関数:

高水準 API:

PyUnicode_CopyCharacters()

PyUnicode_FindChar()

PyUnicode_GetLength(), PyUnicode_GET_LENGTH

PyUnicode_New()

PyUnicode_Substring()

PyUnicode_ReadChar(), PyUnicode_WriteChar()

低水準 API:

型 Py_UCS1, Py_UCS2, Py_UCS4

構造体 PyASCIIObject と PyCompactUnicodeObject

PyUnicode_READY

PyUnicode_FromKindAndData()

PyUnicode_AsUCS4(), PyUnicode_AsUCS4Copy()

PyUnicode_DATA, PyUnicode_1BYTE_DATA, PyUnicode_2BYTE_DATA, PyUnicode_4BYTE_DATA

PyUnicode_KIND with PyUnicode_Kind enum: PyUnicode_WCHAR_KIND, PyUnicode_1BYTE_KIND, PyUnicode_2BYTE_KIND, PyUnicode_4BYTE_KIND

PyUnicode_READ, PyUnicode_READ_CHAR, PyUnicode_WRITE

PyUnicode_MAX_CHAR_VALUE

PyArg_ParseTuple が c フォーマットとして bytearray を許容するようになりました (bpo-12380 [https://bugs.python.org/issue?@action=redirect&bpo=12380])。

非推奨

サポートされないオペレーティングシステム

保守する者がいないため OS/2 ならびに VMS はもはやサポートされません。

保守の負担のため WIndows 2000 および COMSPEC を command.com に設定している Windows プラットフォームはもはやサポートされません。

3.2 で非推奨だった OSF のサポートが完全に削除されました。

非推奨の Python モジュール、関数、メソッド

object 型そのものの object.__format__() に空でない文字列が渡すことは非推奨となりました。Python 3.4 ではこれは TypeError となります (bpo-9856 [https://bugs.python.org/issue?@action=redirect&bpo=9856])。

PEP 393 [https://peps.python.org/pep-0393/] により、 unicode_internal コーデックは非推奨となりました。UTF-8, UTF-16 (utf-16-le または utf-16-be), あるいは UTF-32 (utf-32-le または utf-32-be) を使ってください。

ftplib.FTP.nlst() および ftplib.FTP.dir(): ftplib.FTP.mlsd() を使ってください

platform.popen(): subprocess モジュールを使ってください。 古い関数を subprocess モジュールで置き換える を是非お読みください (bpo-11377 [https://bugs.python.org/issue?@action=redirect&bpo=11377])。

bpo-13374 [https://bugs.python.org/issue?@action=redirect&bpo=13374]: os モジュールにある Windows のバイト列 API は非推奨となりました。ANSI コードページに依存しないようにしてあらゆるファイル名をサポートするために、バイト列文字列のファイル名ではなく Unicode ファイル名を使ってください。

bpo-13988 [https://bugs.python.org/issue?@action=redirect&bpo=13988]: xml.etree.cElementTree モジュールは非推奨です。利用できる際はいつでも自動的にアクセラレータを使用します。

time.clock() の振る舞いがプラットフォーム依存のため、今後は要件に応じて新たに追加された time.perf_counter() または time.process_time() を使ってください。これらの振る舞いは良く定義されています(well defined)。

os.stat_float_times() 関数は非推奨です。

abc モジュール:

abc.abstractproperty は非推奨となりました。代わりに abc.abstractmethod() に property を渡して使ってください。

abc.abstractclassmethod は非推奨となりました。代わりに abc.abstractmethod() に classmethod を渡して使ってください。

abc.abstractstaticmethod は非推奨となりました。代わりに abc.abstractmethod() に staticmethod を渡して使ってください。

importlib パッケージ:

バイトコードファイルとしての importlib.abc.SourceLoader.path_stats() によりコンパイル時点の修正時刻とソースファイルサイズの両方を格納するようになったので、 importlib.abc.SourceLoader.path_mtime() は非推奨となりました。

C API の非推奨の関数ならびに型

PEP 393 [https://peps.python.org/pep-0393/] で Py_UNICODE は非推奨になり、Python 4 で削除されます。この型を使用している全ての関数は非推奨です。

Unicode functions and methods using Py_UNICODE and Py_UNICODE* types:

PyUnicode_FromUnicode: use PyUnicode_FromWideChar() or PyUnicode_FromKindAndData()

PyUnicode_AS_UNICODE, PyUnicode_AsUnicode(), PyUnicode_AsUnicodeAndSize(): use PyUnicode_AsWideCharString()

PyUnicode_AS_DATA: use PyUnicode_DATA with PyUnicode_READ and PyUnicode_WRITE

PyUnicode_GET_SIZE, PyUnicode_GetSize(): use PyUnicode_GET_LENGTH or PyUnicode_GetLength()

PyUnicode_GET_DATA_SIZE: use PyUnicode_GET_LENGTH(str) * PyUnicode_KIND(str) (only work on ready strings)

PyUnicode_AsUnicodeCopy(): use PyUnicode_AsUCS4Copy() or PyUnicode_AsWideCharString()

PyUnicode_GetMax()

Py_UNICODE* 文字列を操作する関数ならびにマクロ:

Py_UNICODE_strlen(): use PyUnicode_GetLength() or PyUnicode_GET_LENGTH

Py_UNICODE_strcat(): use PyUnicode_CopyCharacters() or PyUnicode_FromFormat()

Py_UNICODE_strcpy(), Py_UNICODE_strncpy(), Py_UNICODE_COPY(): use PyUnicode_CopyCharacters() or PyUnicode_Substring()

Py_UNICODE_strcmp(): use PyUnicode_Compare()

Py_UNICODE_strncmp(): use PyUnicode_Tailmatch()

Py_UNICODE_strchr(), Py_UNICODE_strrchr(): use PyUnicode_FindChar()

Py_UNICODE_FILL(): use PyUnicode_Fill()

Py_UNICODE_MATCH

エンコーダ:

PyUnicode_Encode(): use PyUnicode_AsEncodedObject()

PyUnicode_EncodeUTF7()

PyUnicode_EncodeUTF8(): use PyUnicode_AsUTF8() or PyUnicode_AsUTF8String()

PyUnicode_EncodeUTF32()

PyUnicode_EncodeUTF16()

PyUnicode_EncodeUnicodeEscape() use PyUnicode_AsUnicodeEscapeString()

PyUnicode_EncodeRawUnicodeEscape() use PyUnicode_AsRawUnicodeEscapeString()

PyUnicode_EncodeLatin1(): use PyUnicode_AsLatin1String()

PyUnicode_EncodeASCII(): use PyUnicode_AsASCIIString()

PyUnicode_EncodeCharmap()

PyUnicode_TranslateCharmap()

PyUnicode_EncodeMBCS(): use PyUnicode_AsMBCSString() or PyUnicode_EncodeCodePage() (with CP_ACP code_page)

PyUnicode_EncodeDecimal(), PyUnicode_TransformDecimalToASCII()

非推奨の機能

array モジュールの 'u' 書式化コードは非推奨となりました。Python 4 ではほかの (Py_UNICODE) API と一緒に削除されるでしょう。

Python 3.3 への移植

このセクションでは前述の変更とバグフィックスにより必要となるかもしれないコードの変更を列挙します:

Python コードの移植

ハッシュのランダム化がデフォルトで有効になりました。これを無効にするには環境変数 PYTHONHASHSEED を 0 にセットして下さい。 object.__hash__() メソッドも参照して下さい。

bpo-12326 [https://bugs.python.org/issue?@action=redirect&bpo=12326]: Linux では、 sys.platform はもはやメジャーバージョン番号を含みません。 これは今では常に 'linux' です。以前はこれは Python のビルドに使われた Linux バージョンに依存した 'linux2' や 'linux3' でした。 sys.platform == 'linux2' などとするのではなく、 sys.platform.startswith('linux') とするか、古い Python バージョンのサポートが不要であれば直接的に sys.platform == 'linux' として下さい。

bpo-13847 [https://bugs.python.org/issue?@action=redirect&bpo=13847], bpo-14180 [https://bugs.python.org/issue?@action=redirect&bpo=14180]: time および datetime: タイムスタンプが範囲外の場合に、 ValueError ではなく OverflowError を送出するようになりました。また、C 関数の gmtime() あるいは localtime() が失敗した場合には OSError を送出するようになりました。

インポートで使われるデフォルトのファインダが、特定のディレクトリに何が含まれるのかについてのキャッシュを利用するようになっています。実行中に Python ソースファイルやバイトコードファイルを作ったら、キャッシュをクリアしてファインダが新しく作られたファイルに気付けるように、 importlib.invalidate_caches() を呼ぶ必要があることに注意してください。

ImportError がインポートを試みたモジュール名として完全名を使うようになっています。ImportError のメッセージをチェックする doctest は、モジュール名をその末尾の名前ではなく完全な名前を使うように更新する必要があります。

__import__() の引数 index のデフォルトが -1 ではなく 0 となり、また、もはや負の値はサポートされません。デフォルト値が -1 で残されたのは(訳注: つまり絶対、相対インポートの両方を試みるようにしたのは) PEP 328 [https://peps.python.org/pep-0328/] を実装した際の過失でした。絶対インポートに先立って相対インポートを実行する振る舞いがまだ必要なのであれば、index を 1 にして相対インポートを実行して、その後で index 0 のインポートをするようにしてください。そうなのですが、 __import__() を直接呼び出すのではなく、 importlib.import_module() を使うことが望ましいやり方です。

__import__() の index に、トップレベルモジュールに対して 0 でなく 1 を与えることは今では許されません。例えば __import__('sys', level=1) はエラーです。

Because sys.meta_path and sys.path_hooks now have finders on them by default, you will most likely want to use list.insert() instead of list.append() to add to those lists.

Because None is now inserted into 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 None and imp.NullImporter to be backwards-compatible. This will lead to extra overhead on older versions of Python that re-insert None into sys.path_importer_cache where it represents the use of implicit finders, but semantically it should not change anything.

importlib.abc.Finder no longer specifies a 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 find_loader() first, though, in the case of working with path entry finders.

pkgutil は、内部的に importlib を使うように変更されました。このことは、 PEP 302 [https://peps.python.org/pep-0302/] インポートエミュレーションの古い振る舞いが本物のインポートシステムの振る舞いに合わせるのに失敗していた数多くの特殊ケースの問題を取り除きます。インポートエミュレーションそのものはまだ存在しますが、今では非推奨です。 pkgutil.iter_importers() 関数と pkgutil.walk_packages() 関数は標準インポートフックを特別に扱うので、ファインダの iter_modules() メソッドは標準ではないにも関わらず、まだサポートされます。

email.header.decode_header() によってなされる解析に長い間存在していた RFC 非準拠のバグ (bpo-1079 [https://bugs.python.org/issue?@action=redirect&bpo=1079]) が修正されました。エンコードされたヘッダを Unicode に変換するための標準的なイディオム (str(make_header(decode_header(h))) を使うコードからは変化はみえません。ですが、 decode_header から返される個々のタプル要素を見ているコードでは、 ASCII セクションの前後の空白が ASCII 内に含まれるようになったことがわかります。 make_header は入力文字列に既に存在していなければ ASCII 非 ASCII セクション間に以前と同じく空白を追加するので、 make_header を使ってヘッダを構築するコードは変更なしで動作するはずです。

email.utils.formataddr() は非 ASCII の display name に対し正しい content transfer encoding の扱いをするようになっています。かつての、フォーマット後文字列内に非 ASCII Unicode を維持してしまう誤った振る舞いに依存するすべてのコードは、変更の必要があります。 (bpo-1690608 [https://bugs.python.org/issue?@action=redirect&bpo=1690608])

poplib.POP3.quit() メソッドもほかの全ての poplib のメソッドと同じく、今ではプロトコルエラーを送出し得ます。 quit が poplib.error_proto エラーを送出しないことをあてにしていたコードは、 quit でのエラーが特定のアプリケーションにとって問題となるようであれば、修正の必要があるかもしれません (bpo-11291 [https://bugs.python.org/issue?@action=redirect&bpo=11291])。

Python 2.4 から非推奨となっていた、 email.parser.Parser への strict 引数はついに削除されました。

非推奨となっていたメソッド unittest.TestCase.assertSameElements は削除されました。

非推奨となっていた変数 time.accept2dyear は削除されました。

非推奨となっていた Context._clamp 属性が decimal モジュールから削除されました。以前に既にこれは公開属性 clamp に置き換えられていました (bpo-8540 [https://bugs.python.org/issue?@action=redirect&bpo=8540] 参照)。

文書化されていなかった内部ヘルパクラス SSLFakeFile が smtplib モジュールより削除されました。この機能はずっと以前から socket.socket.makefile() によって直接的に提供されています。

Windows では time.sleep() に負値を与えた場合に無限に眠っていましたが、今ではこれは例外を送出します。POSIX ではこれは以前より常に例外です。

The ast.__version__ constant has been removed. If you need to make decisions affected by the AST version, use sys.version_info to make the decision.

threading モジュールの、非公開クラスをサブクラス化するファクトリ関数を迂回していたコードは、今では公開クラスになったので修正の必要があります。

threading モジュール内の文書化されていなかったデバッグ機構を削除してコードを単純化しました。このことが製品コードに影響することがあってはなりませんが、これと連携していたアプリケーションデバッグフレームワークのケースがありうるので、言及しておきます (bpo-13550 [https://bugs.python.org/issue?@action=redirect&bpo=13550])。

C コードの移植

In the course of changes to the buffer API the undocumented smalltable member of the Py_buffer structure has been removed and the layout of the PyMemoryViewObject has changed.

memoryobject.h あるいは object.h での関係する部分に依存する全ての拡張は、再ビルドが必要です。

PEP 393 により、 Py_UNICODE 型とこの型を使う全ての関数は非推奨となりました (ただし最低 5 年は利用可能なまま保たれます)。Unicode オブジェクトの構築とアクセスに低水準 Unicode API をこれまで使っていて、 PEP 393 [https://peps.python.org/pep-0393/] によって提供されるメモリフットプリント削減の恩恵を受けたければ、新しい Unicode API に乗り換える必要があります。

一方で PyUnicode_Concat() 、 PyUnicode_Join() あるいは PyUnicode_FromFormat() といった高水準関数のみを使ってきたのであれば、あなたのコードは自動的に新しい Unicode 表現に便乗できます。

PyImport_GetMagicNumber() は失敗時に -1 を返すようになりました。

__import__() の level 引数に負値を渡すことはもはや有効ではないので、対応する PyImport_ImportModuleLevel() でも同じです。このことは PyImport_ImportModuleEx() に使われる level の値が -1 ではなく 0 を使うようになったことも意味しています。

C 拡張のビルド

C 拡張のファイル名として認められる範囲が狭められました。滅多に使われてこなかった命名は取りやめられました: POSIX では、 xxxmodule.so, xxxmodule.abi3.so, xxxmodule.cpython-*.so 命名は今後 xxx モジュールの実装とは認識されません。これまでそのようなファイルを作ってきたのであれば、別の命名に乗り換えてください (つまり module 文字列をファイル名から取り除いてください)。

(implemented in bpo-14040 [https://bugs.python.org/issue?@action=redirect&bpo=14040].)

コマンドラインスイッチの変更

-Q コマンドラインスイッチとそれに関係するものは削除されました。 sys.flags.division_warning をチェックしているコードは修正する必要があります。

(bpo-10998 [https://bugs.python.org/issue?@action=redirect&bpo=10998], contributed by Éric Araujo.)

-S スイッチ付きで python を開始すると、 import site がモジュール検索パスにサイト固有のパスを追加しなくなります。以前のバージョンではそれをしていました。

(bpo-11591 [https://bugs.python.org/issue?@action=redirect&bpo=11591], contributed by Carl Meyer with editions by Éric Araujo.)

What's New In Python 3.2

著者:

Raymond Hettinger

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 [https://github.com/python/cpython/blob/076ca6c3c8df3030307e548d9be792ce3c1c6eea/Misc/NEWS] file.

参考

PEP 392 [https://peps.python.org/pep-0392/] - Python 3.2 リリーススケジュール

PEP 384: 安定 ABI の定義

かつて、ある Python バージョンでビルドされた拡張モジュールは、ほかの Python バージョンでは使えないことがありました。特に Windows では、全ての Python 公式リリースごとに、使いたい全ての拡張モジュールを再ビルドする必要がありました。これは、拡張モジュールが Python インタプリタの内部実装に自由にアクセス出来たことからの結果でした。

Python 3.2 より、このことに関する別のアプローチが利用可能になりました。(Py_LIMITED_API を定義することで) 制限された API のみ使うようにする拡張モジュールは、数多くの内部実装を利用出来ない代わりに将来のいくつものリリースで安定であることを約束された API 集合だけ使うことになります。結果として、このモードで 3.2 のためにビルドされた拡張モジュールは 3.3、3.4、…でも動作するでしょう。なお、メモリ構造の詳細を曝すような拡張モジュールでは、相変わらず全ての Python 公式リリースごとに再ビルドする必要があるでしょう。

参考

PEP 384 [https://peps.python.org/pep-0384/] - 安定 ABI の定義

PEP written by Martin von Löwis.

PEP 389: argparse コマンドライン解析モジュール

コマンドライン解析のために、新たに argparse モジュールが optparse の制限を克服するものとして導入されました。optparse には (オプションだけでなく) 位置引数のサポートはなく、サブコマンドも作れず、必須のオプションやその他オプション指定と検証に共通するパターンについてのサポートもありませんでした。

このモジュールはコミュニティにおいて既に広く行き渡っていたサードパーティのモジュールでした。その先駆者たちよりももっと完全な機能性を持ったことで、 argparse モジュールは今ではコマンドライン解析での推奨モジュールとなりました。古いモジュールは、それに依存しているレガシーなコードが大量にあるため、今後も利用可能なまま保たれます。

以下に注釈付きで示したパーサは、有限個の選択肢から選ばせ、 metavar でヘルプ表示を指定し、一つ以上の位置引数があるかを検証し、必須オプションを設けている実例になっています:

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')

コマンド文字列とともにこのパーサを呼び出してみます:

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

このパーサが自動的に作り出したヘルプはこのようになります:

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

argparse 機能でとりわけ素晴らしいのはサブパーサを定義出来ることです。それらはそれぞれ自身固有の引数パターンを持ち、ヘルプ表示をします:

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)

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

参考

PEP 389 [https://peps.python.org/pep-0389/] - 新しいコマンドライン解析モジュール

PEP written by Steven Bethard.

optparse からのアップグレード に optparse との違いが詳しく書かれています。

PEP 391: logging の辞書ベースの設定

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

もっと柔軟な設定をサポートするために、新たに logging.config.dictConfig() が追加されました。これはロギングの設定を通常の Python 辞書で指定します。設定オプションにはフォーマッタ、ハンドラ、フィルタ、そしてロガーが含まれます。以下は設定辞書の動作する実例です:

{"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"]}}

その辞書が conf.json ファイルに格納されているのであれば、コードからこのように呼び出してロード出来ます:

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

参考

PEP 391 [https://peps.python.org/pep-0391/] - logging の辞書ベースの設定

PEP written by Vinay Sajip.

PEP 3148: concurrent.futures モジュール

同時並行性 (concurrency) を生成・管理するコードはトップレベルの新しい名前空間 concurrent に集められることになりました。その最初のメンバーが futures パッケージです。これはスレッドとプロセス管理の統一的な高水準インターフェイスを提供します。

concurrent.futures の設計は Java の java.util.concurrent パッケージに触発されました。そのモデルでは、実行する呼び出しとその結果は Future オブジェクトで表現され、これはスレッド、プロセス、遠隔手続呼び出しの共通的な側面を抽象化しています。そのオブジェクトはステータスのチェック (実行中あるいは完了かどうか)、タイムアウト、キャンセル、コールバックの追加、そして結果や例外へのアクセスをサポートします。

この新モジュールで提供される最も基本となるのが、呼び出しの実行と管理のための 2 つの executor クラスです。これら executor の目標は、これまでにもあった道具立てでの並列呼び出しを、もっと簡単にすることです。リソースプールをお膳立てしたり呼び出しを実行したり、結果のキューを作ったり、あるいはタイムアウトのハンドラを追加したり、スレッドやプロセスや遠隔手続呼び出しの総数を制限したり、といったことを、これらを使えば、その労力を小さく出来ます。

理想的にはそれぞれのアプリケーションは、プロセスとスレッドの制限が確実に管理されるように、複数コンポーネントをまたがって単一の executor を共有すべきです。そうしておけば、個々のコンポーネントがリソース管理についての競合する戦略を持つ場合に起こる設計の難題は解決出来ます。

どちらの executor クラスとも 3 つのメソッドを持つ共通インターフェイスを持ちます。 submit() メソッドは呼び出し可能オブジェクトをスケジュールし、 Future オブジェクトを返します。 map() メソッドは一気に複数の非同期呼び出しをスケジュールします。 shutdown() メソッドはリソースを解放します。これらクラスは context manager なので with 文とともに使うことが出来、現時点で保留中の future が実行を終えた際にリソースが自動的に解放されることを保障出来ます。

以下はファイルコピーを行う 4 つの並列スレッドを実行する、 ThreadPoolExecutor の単純な使用例です:

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')

参考

PEP 3148 [https://peps.python.org/pep-3148/] - Futures -- 計算の非同期な実行

PEP written by Brian Quinlan.

ThreadPoolExecutor の例 はスレッド並列でウェブページを取得する実例コードです。

ProcessPoolExecutor の実例を 並列で素数計算するコード例 として挙げています。

PEP 3147: PYC リポジトリーディレクトリ

バイトコードを .pyc ファイルとしてキャッシュする Python の方法は、複数の Python インタプリタ環境ではうまく働きませんでした。一つのインタプリタがもう一つのインタプリタによって作られたキャッシュファイルに出会うと、そのインタプリタはソースを再コンパイルしてキャッシュファイルを上書きするわけですから、これではキャッシュの価値は台無しです。

「pyc ファイト」問題は、複数バージョンの Python を載せる Linux ディストリビューションにありふれたこととなったよりももっと表立って来ました。これら衝突は Unladen Swallow [https://en.wikipedia.org/wiki/Unladen_Swallow#Project_activity] のような CPython 以外の実装でも起こります。

この問題を解決するために、Python のインポート機構はそれぞれのインタプリタごとに区別された名前を使うように拡張されました。Python 3.2、Python 3.3、 Unladen Swallow でそれぞれ競合するファイル名 "mymodule.pyc" を使うのではなく、それぞれ "mymodule.cpython-32.pyc", "mymodule.cpython-33.pyc", "mymodule.unladen10.pyc" を使うようになりました。同時にこれらの新しいファイルがソースディレクトリを散らかすのを防ぐために、 pyc ファイルはパッケージディレクトリの下の "__pycache__" ディレクトリに収集するようになりました。

ファイル名と格納先ディレクトリは別にして、この新方式にはプログラマ目線での目に見える変化が少しあります:

インポートされたモジュールには属性 __cached__ が追加されて、これにはインポートされたファイルの実際のファイル名を記憶しています:

>>> import collections
>>> collections.__cached__
'c:/py32/lib/__pycache__/collections.cpython-32.pyc'

The tag that is unique to each interpreter is accessible from the imp module:

>>> import imp
>>> imp.get_tag()
'cpython-32'

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

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

py_compile と compileall モジュールはこの新命名規則とターゲットディレクトリを反映するよう更新されました。 compileall のコマンドラインからの起動には新しいオプションが追加されました。 -i はコンパイルするファイルとディレクトリのリストを指定します。 -b はバイトコードファイルを __pycache__ ではなく伝統的な場所に書き出します。

The importlib.abc module has been updated with new abstract base classes for loading bytecode files. The obsolete ABCs, PyLoader and PyPycLoader, have been deprecated (instructions on how to stay Python 3.1 compatible are included with the documentation).

参考

PEP 3147 [https://peps.python.org/pep-3147/] - PYC リポジトリーディレクトリー

PEP written by Barry Warsaw.

PEP 3149: ABI バージョンでタグ付けされた .so ファイル

PYC レポジトリーディレクトリでは複数バイトコードのキャッシュファイルを共存できます。この PEP は共有オブジェクトについての同じようなメカニズムを実装します。それには共通のディレクトリを使い、個々のバージョンごとの名前の区別をします。

共通ディレクトリは "pyshared" です。また、ファイル名は Python 実装 (例えば CPython、PyPy、Jython など)、メジャー・マイナーバージョン番号やオプショナルなビルドフラグ (例えばデバッグビルドでの "d"、 pymalloc ビルドの "m"、ワイド幅 Unicode の "u") を特定することで区別するように命名されます。任意のパッケージ "foo" について、配布パッケージがインストールされるとこれらファイルは例えばこのような具合でしょう:

/usr/share/pyshared/foo.cpython-32m.so
/usr/share/pyshared/foo.cpython-33md.so

Python 自身からこのタグに、 sysconfig モジュールにある関数でアクセス出来ます:

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

参考

PEP 3149 [https://peps.python.org/pep-3149/] - ABI バージョンでタグ付けされた .so ファイル

PEP written by Barry Warsaw.

PEP 3333: Python Web Server Gateway Interface v1.0.1

この情報 PEP は、 WSGI プロトコルによってどのようにバイト列/テキストの問題が処理されるべきかを明確化しています。HTTP プロトコルそのものはバイト列指向であっても、Python 3 にあってほとんど str 型で便利に文字列処理出来るようにすることが挑戦でした。

この PEP では、リクエスト/レスポンスヘッダとメタデータに使われるいわゆる ネイティブ文字列(native strings) と、リクエストとレスポンスのボディに使われる バイト列文字列(byte strings) を区別します。

The native strings are always of type 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 start_response() function. They must follow RFC 2616 [https://datatracker.ietf.org/doc/html/rfc2616.html] with respect to encoding. That is, they must either be ISO-8859-1 characters or use RFC 2047 [https://datatracker.ietf.org/doc/html/rfc2047.html] MIME encoding.

WSGI アプリケーションを Python 2 から移植する開発者は、とりわけ以下に注意してください:

Python 2 でヘッダとしてネイティブ文字列を既に使っているアプリケーションは変更の必要はありません。(---訳注: 原文は「If the app already used strings for headers ...」。native strings としないと意味が通りません。 ---)

そうではなくアプリケーションが出力ヘッダをエンコードしていたり、入力ヘッダをデコードしていたのであれば、ヘッダは Latin-1 に再エンコードする必要があります。たとえば h.encode('utf-8') により utf-8 でエンコードされた出力ヘッダは、バイト列からネイティブ文字列に h.encode('utf-8').decode('latin-1') で変換する必要があります。(---訳注: この原文は h が元々 latin-1 で表現出来る文字セットであることを暗黙で仮定しているようです。---)

Values yielded by an application or sent using the write() method must be byte strings. The start_response() function and environ must use native strings. The two cannot be mixed.

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 wsgiref module has a new function, wsgiref.handlers.read_environ() for transcoding CGI variables from os.environ into native strings and returning a new dictionary.

参考

PEP 3333 [https://peps.python.org/pep-3333/] - Python Web Server Gateway Interface v1.0.1

PEP written by Phillip Eby.

その他の言語変更

Python 言語コアに小さな変更がいくつか行われました:

format() と str.format() のフォーマット文字 # が拡張されました。以前から二進、八進、十六進整数に対して順にそれぞれ '0b', '0o', '0x' を冠する出力をしていましたが、これは浮動小数点数、複素数、 Decimal に対しても処理するようになり、これはあとに続く桁がなくても必ず小数点を出力します。

>>> format(20, '#o')
'0o24'
>>> format(12.34, '#5.0f')
'  12.'

(Suggested by Mark Dickinson and implemented by Eric Smith in bpo-7094 [https://bugs.python.org/issue?@action=redirect&bpo=7094].)

新たに追加された str.format_map() メソッドも既存の str.format() メソッドの能力を拡大します。これは任意の mapping を受け付けます。この新規メソッドは Python の数多くの「辞書的な」オブジェクトとともに文字列書式化を使うことを可能にします。たとえば defaultdict, Shelf, ConfigParser, あるいは dbm などで使えるということです。カスタムな dict のサブクラスと一緒に使うのも便利で、例えばルックアップの前にキーを正規化してみたり、未知のキーを __missing__() メソッドで補ってみたりなど出来ます:

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

(Suggested by Raymond Hettinger and implemented by Eric Smith in bpo-6081 [https://bugs.python.org/issue?@action=redirect&bpo=6081].)

The interpreter can now be started with a quiet option, -q, to prevent the copyright and version information from being displayed in the interactive mode. The option can be introspected using the sys.flags attribute:

$ 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)

(Contributed by Marcin Wojdyr in bpo-1772833 [https://bugs.python.org/issue?@action=redirect&bpo=1772833]).

The hasattr() function works by calling getattr() and detecting whether an exception is raised. This technique allows it to detect methods created dynamically by __getattr__() or __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 AttributeError and let other exceptions pass through:

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

(Discovered by Yury Selivanov and fixed by Benjamin Peterson; bpo-9666 [https://bugs.python.org/issue?@action=redirect&bpo=9666].)

浮動小数点数または複素数に対する str() は repr() 表現と同じになりました。以前は str() 形式のほうが短い表現になっていましたがこれは単に困惑させるものでした。 repr() がデフォルトで可能ななかでの一番短い表現をするようになったので、 str() があえて短い表現を取ろうとする必要性がなくなりました。

>>> import math
>>> repr(math.pi)
'3.141592653589793'
>>> str(math.pi)
'3.141592653589793'

(Proposed and implemented by Mark Dickinson; bpo-9337 [https://bugs.python.org/issue?@action=redirect&bpo=9337].)

memoryview オブジェクトに release() メソッドが追加され、また、これは今ではコンテキストマネージャプロトコルをサポートします。このことにより、オリジナルのオブジェクトからバッファを要求した際に獲得した任意のリソースを、適切な時点で解放できます。

>>> with memoryview(b'abcdefgh') as v:
...     print(v.tolist())
[97, 98, 99, 100, 101, 102, 103, 104]

(Added by Antoine Pitrou; bpo-9757 [https://bugs.python.org/issue?@action=redirect&bpo=9757].)

以前は、入れ子になったブロック内である名前が自由変数として現れる場合、局所名前空間からその名前を削除することは不正でした。

def outer(x):
    def inner():
        return x
    inner()
    del x

これは可能になりました。 except 節の対象が消去されることを思い出せば、 Python 2.6 では動き、Python 3.1 では SyntaxError を送出するこのコードは再び動きます:

def f():
    def print_error():
        print(e)
    try:
        something
    except Exception as e:
        print_error()
        # implicit "del e" here

(bpo-4617 [https://bugs.python.org/issue?@action=redirect&bpo=4617] を参照してください。)

Struct sequence types are now subclasses of tuple. This means that C structures like those returned by os.stat(), time.gmtime(), and sys.version_info now work like a 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:

>>> import sys
>>> isinstance(sys.version_info, tuple)
True
>>> 'Version %d.%d.%d %s(%d)' % sys.version_info
'Version 3.2.0 final(0)'

(Suggested by Arfrever Frehtes Taifersar Arahesis and implemented by Benjamin Peterson in bpo-8413 [https://bugs.python.org/issue?@action=redirect&bpo=8413].)

警告の制御を以前より簡単に出来るようになりました。環境変数 PYTHONWARNINGS を使えば、コマンドラインで -W を使うより簡単です:

$ export PYTHONWARNINGS='ignore::RuntimeWarning::,once::UnicodeWarning::'

(Suggested by Barry Warsaw and implemented by Philip Jenvey in bpo-7301 [https://bugs.python.org/issue?@action=redirect&bpo=7301].)

新たな警告カテゴリ ResourceWarning が追加されました。これはリソース消費やクリーンアップについての潜在的な問題が検出されると発行されます。これは通常のリリースビルドではデフォルトでは黙殺しますが、 warnings モジュールで意味付けを変更 (訳注: 警告フィルタ 参照) するかコマンドラインオプションで有効に出来ます。

A ResourceWarning is issued at interpreter shutdown if the gc.garbage list isn't empty, and if 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.

ResourceWarning は明示的にクローズされなかった file object が破壊される際にも発行されます。そのようなオブジェクトのデアロケータは背後の OS リソース (大抵はファイル記述子) を閉じることを保障はしますが、オブジェクトのデアロケートの遅れは様々な問題を産み落とし、とりわけ Windows でこれは顕著です。コマンドラインからこの警告を有効にするには例えばこのようにします:

$ python -q -Wdefault
>>> f = open("foo", "wb")
>>> del f
__main__:1: ResourceWarning: unclosed file <_io.BufferedWriter name='foo'>

(Added by Antoine Pitrou and Georg Brandl in bpo-10093 [https://bugs.python.org/issue?@action=redirect&bpo=10093] and bpo-477863 [https://bugs.python.org/issue?@action=redirect&bpo=477863].)

range objects now support index and count methods. This is part of an effort to make more objects fully implement the collections.Sequence abstract base class. As a result, the language will have a more uniform API. In addition, range objects now support slicing and negative indices, even with values larger than sys.maxsize. This makes range more interoperable with lists:

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

(Contributed by Daniel Stutzbach in bpo-9213 [https://bugs.python.org/issue?@action=redirect&bpo=9213], by Alexander Belopolsky in bpo-2690 [https://bugs.python.org/issue?@action=redirect&bpo=2690], and by Nick Coghlan in bpo-10889 [https://bugs.python.org/issue?@action=redirect&bpo=10889].)

Py2.x から callable() 組み込み関数が復活しました。この関数は isinstance(x, collections.Callable) のように式内で 抽象基底クラス を使用するよりも、簡潔で可読性の高い手段を提供します:

>>> callable(max)
True
>>> callable(20)
False

(bpo-10518 [https://bugs.python.org/issue?@action=redirect&bpo=10518] を参照してください。)

Python のインポート機構が、パス名に非 ASCII 文字を含むディレクトリにインストールされたモジュールをロードできるようになりました。これはユーザ名に非 ASCII 文字を含むユーザにとっての、ホームディレクトリにまつわる腹立たしい問題を解決しました。

(Required extensive work by Victor Stinner in bpo-9425 [https://bugs.python.org/issue?@action=redirect&bpo=9425].)

新たなモジュール、改良されたモジュール、非推奨のモジュール

Python の標準ライブラリは保守の努力と質の向上を大きく受けています。

The biggest news for Python 3.2 is that the email package, mailbox module, and 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.

標準ライブラリ全体を通じて、エンコーディング問題とテキスト対バイト列問題に関してより注意深い配慮がなされました。とりわけオペレーティングシステムとの連携では、Windows の MBCS エンコーディングやロケールに配慮するエンコーディング、あるいは UTF-8 を使う非 ASCII のデータ交換はより良く行えるようになりました。

もうひとつの目覚しい勝利は、 SSL 接続とセキュリティ証明書サポートの大幅な改善です。

さらに、以前よりももっと多くのクラスが今では context manager を実装し、 with 文を使った便利で信頼出来るリソースのクリーンアップをサポートしています。

email

R. David Murray による多大なる尽力により、Python 3 における email パッケージの適応可能性の問題は、ほとんど修正されました。問題は、email が典型的には str テキストよりも bytes 形式で格納され、読まれることであり、一つの email の中に複数のエンコーディングを含みうることでした。ですから email パッケージは email メッセージの解析と生成を bytes フォーマットで拡張される必要がありました。

新規関数 message_from_bytes(), message_from_binary_file() 、それに新規クラス BytesFeedParser, BytesParser が、バイナリメッセージデータをパースしてモデルオブジェクトに読み込みます。

bytes の入力をモデルに与えると get_payload() は、デフォルトでは 8 ビット の Content-Transfer-Encoding MIME ヘッダをもったメッセージボディをそのヘッダで指定された文字セットを使い、デコードして結果文字列を返します。

bytes の入力をモデルに与えると Generator は、 8 ビット の Content-Transfer-Encoding MIME ヘッダをもったメッセージボディを、 7 ビット の Content-Transfer-Encoding を持つものに変換します。

エンコードされていない非 ASCII バイト列を持つヘッダは 未知の 8 ビット 文字セットを使った RFC 2047 [https://datatracker.ietf.org/doc/html/rfc2047.html] エンコードであると見做されます。

新規クラス BytesGenerator は出力としてバイト列を生成します。これはモデルを構築するのに使った入力にあった非 ASCII データをそのままにし、 8ビットの Content-Transfer-Encoding を持つメッセージボディに含めます。

smtplib モジュールの SMTP クラスが sendmail() メソッドの msg 引数としてバイト列文字列を受け付けるようになりました。新しく追加されたメソッド send_message() は msg 引数に Message オブジェクトを受け付けます。このメソッドは msg にあたえたオブジェクトから from_addr アドレスと to_addrs アドレスを直接取ることが出来ます。

(Proposed and implemented by R. David Murray, bpo-4661 [https://bugs.python.org/issue?@action=redirect&bpo=4661] and bpo-10321 [https://bugs.python.org/issue?@action=redirect&bpo=10321].)

elementtree

The xml.etree.ElementTree package and its xml.etree.cElementTree counterpart have been updated to version 1.3.

有用な関数とメソッドが幾つか新たに追加されました:

xml.etree.ElementTree.fromstringlist()、断片のシーケンスから XML 文書を組み立てます

xml.etree.ElementTree.register_namespace()、大域名前空間接頭辞を登録するのに使用します

xml.etree.ElementTree.tostringlist()、全サブリストを含めた文字列表記に使用します

xml.etree.ElementTree.Element.extend()、ゼロ以上の要素のシークエンスを追加するのに使用します

xml.etree.ElementTree.Element.iterfind()、要素と子要素を検索します

xml.etree.ElementTree.Element.itertext()、要素と子要素を走るテキストイテレータを作成します

xml.etree.ElementTree.TreeBuilder.end()、現在の要素を閉じます

xml.etree.ElementTree.TreeBuilder.doctype()、doctype 定義を処理します

2つのメソッドが非推奨になりました:

xml.etree.ElementTree.getchildren() use list(elem) instead.

xml.etree.ElementTree.getiterator() use Element.iter instead.

For details of the update, see Introducing ElementTree [https://web.archive.org/web/20200703234532/http://effbot.org/zone/elementtree-13-intro.htm] on Fredrik Lundh's website.

(Contributed by Florent Xicluna and Fredrik Lundh, bpo-6472 [https://bugs.python.org/issue?@action=redirect&bpo=6472].)

functools

functools モジュールに関数呼び出しをキャッシュするデコレータが追加されています。 functools.lru_cache() を使うと、同じ結果が期待される場合の外部リソースへの問い合わせ繰り返しを防ぐことができます。

たとえばデータベース問い合わせ関数をキャッシュするデコレータで修飾すれば、人気の検索のデータベースアクセスを省けます:

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

>>> for name in user_requests:
...     get_phone_number(name)        # cached lookup

効果的なキャッシュサイズを選択する助けとなるよう、ラップされた関数はキャッシュの統計を追跡する道具にもなっています:

>>> get_phone_number.cache_info()
CacheInfo(hits=4805, misses=980, maxsize=300, currsize=300)

テーブル phonelist が更新されたのであれば、内容が古くなったキャッシュをクリアできます:

>>> get_phone_number.cache_clear()

(Contributed by Raymond Hettinger and incorporating design ideas from Jim Baker, Miki Tebeka, and Nick Coghlan; see recipe 498245 [https://code.activestate.com/recipes/498245-lru-and-lfu-cache-decorators/], recipe 577479 [https://code.activestate.com/recipes/577479-simple-caching-decorator/], bpo-10586 [https://bugs.python.org/issue?@action=redirect&bpo=10586], and bpo-10593 [https://bugs.python.org/issue?@action=redirect&bpo=10593].)

The functools.wraps() decorator now adds a __wrapped__ attribute pointing to the original callable function. This allows wrapped functions to be introspected. It also copies __annotations__ if defined. And now it also gracefully skips over missing attributes such as __doc__ which might not be defined for the wrapped callable.

上の例の場合、キャッシュは元の関数を復元することで削除できます:

>>> get_phone_number = get_phone_number.__wrapped__    # uncached function

(By Nick Coghlan and Terrence Cole; bpo-9567 [https://bugs.python.org/issue?@action=redirect&bpo=9567], bpo-3445 [https://bugs.python.org/issue?@action=redirect&bpo=3445], and bpo-8814 [https://bugs.python.org/issue?@action=redirect&bpo=8814].)

拡張比較 (rich comparison) メソッドを持つクラスを書く助けとなるよう、新たなデコレータ functools.total_ordering() が追加されました。これは既存の等式と不等式メソッドを使って残りのメソッドを埋めます。

例えば __eq__ と __lt__ を与えると、 total_ordering() は __le__, __gt__, __ge__ を補います:

@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()))

total_ordering デコレータが残りの比較メソッドを自動的に補います。

(Contributed by Raymond Hettinger.)

Python 2 からのプログラムの移植のために使える、 functools.cmp_to_key() 関数が追加されました。これは旧式の比較関数をモダンな key function に変換します:

>>> # locale-aware sort order
>>> sorted(iterable, key=cmp_to_key(locale.strcoll))

ソートの例と簡単なチュートリアルは Sorting Techniques を参照して下さい。

(Contributed by Raymond Hettinger.)

itertools

itertools モジュールに、 APL [https://ja.wikipedia.org/wiki/APL] の scan 演算子や NumPy [http://www.numpy.org/] の accumulate 関数をモデルにした accumulate() が新しく追加されました:

>>> from itertools import accumulate
>>> list(accumulate([8, 2, 50]))
[8, 10, 60]

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

accumulate() の使用例が examples for the random module にあります。

(Contributed by Raymond Hettinger and incorporating design suggestions from Mark Dickinson.)

collections

collections.Counter クラスに 2 つの形式のインプレイス減算が追加されました。 saturating subtraction [https://en.wikipedia.org/wiki/Saturation_arithmetic] (訳注: 結果を [min, max] に収める演算) を行う既存の -= 演算子に加え、新しく追加された subtract() メソッドは通常の減算を行います。前者は要素数に正しか持たない 多重集合 [https://ja.wikipedia.org/wiki/%E5%A4%9A%E9%87%8D%E9%9B%86%E5%90%88] に用いるのに適していて、後者は要素数に負を許容するユースケースにより適しています。

>>> from collections import Counter
>>> tally = Counter(dogs=5, cats=3)
>>> tally -= Counter(dogs=2, cats=8)    # saturating subtraction
>>> tally
Counter({'dogs': 3})

>>> tally = Counter(dogs=5, cats=3)
>>> tally.subtract(dogs=2, cats=8)      # regular subtraction
>>> tally
Counter({'dogs': 3, 'cats': -5})

(Contributed by Raymond Hettinger.)

collections.OrderedDict クラスに move_to_end() メソッド (訳注: 「end」は「端」) が追加されました。これは既存のキーを受け取って、順序付けされたシーケンスの最初の位置か最後の位置に移動します。

デフォルトでは要素は最後の位置に移動します。これはエントリを od[k] = od.pop(k) で入れ替えるのと同じです。

高速な端への移動操作はエントリの並べなおしに便利です。例えば、最も最近使った順序でエントリを年齢付けすることによってアクセス順を追跡するのに、順序付けされた辞書を使えます。

>>> 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']

(Contributed by Raymond Hettinger.)

collections.deque クラスに 2 つのメソッド count() と reverse() が追加されました。これでさらに list との置換可能性が増しました:

>>> 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'])

(Contributed by Raymond Hettinger.)

threading

threading モジュールに新たに同期クラス Barrier が追加されました。これは多重のスレッドに、それら全てが共通のバリアポイントに到達するまで待たせます。バリアは、複数の事前条件を持ったタスクを、その前任タスクの全てが完了するまで走らせたくない場合に有用です。

バリアは任意の数のスレッドに対して使えます。これは Rendezvous [https://en.wikipedia.org/wiki/Synchronous_rendezvous] を一般化したもので、それは 2 つのスレッドに対してのみに定義されていました。

二段階の周期バリアとしての実装なので、 Barrier オブジェクトはループ内での利用に適しています。分けられた filling (満杯にする) 段階と draining (排出する) 段階は、スレッドのどれか一つが元に戻ってバリアに再び入る前に、全てのスレッドが解放 (排出) されることを保障します。バリアはそれぞれの周期のあとに完全にリセットされます。

バリアは例えばこのように使います:

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()

この例ではバリアは、全ての投票所が閉じるまではどの投票サイトでも得票を数えないルールを強制しています。バリアを使ったソリューションが threading.Thread.join() でのそれといかに似ているか気付くと思います。ですがバリアポイントを通過した後に、スレッドは生き続けて (投票を集計する (summarizing ballots) という) 仕事を続けます。

いずれかの前任タスクがハングしたり遅延したりしうるのであれば、バリアを timeout 付きで作ることができます。全ての前任タスクがバリアポイントに到達する前にタイムアウトの期間が経過すると、全ての待機スレッドは解放されて BrokenBarrierError 例外が発生します:

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)

この例ではバリアは、もっと手堅いルールを強制しています。選挙サイトのどれかが午前零時前に終了しなかった場合バリアがタイムアウトし、投票用紙は密封されて後の処理のためのキューに預けられます。

See Barrier Synchronization Patterns [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 [https://greenteapress.com/semaphores/LittleBookOfSemaphores.pdf], section 3.6.

(Contributed by Kristján Valur Jónsson with an API review by Jeffrey Yasskin in bpo-8777 [https://bugs.python.org/issue?@action=redirect&bpo=8777].)

datetime と time

datetime モジュールに新たに timezone 型が追加されています。これは tzinfo インターフェイスを実装し、UTC からの固定オフセットとタイムゾーン名を返します。これによりタイムゾーンを意識する (timezone-aware な) datetime オブジェクトを容易に作れます:

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

さらに、 timedelta オブジェクトは今では float を掛けることができ、 float や int で割ることができます。また、 timedelta オブジェクトは別の timedelta で割ることが出来ます。

datetime.date.strftime() メソッドにはもう 1900 年以降という制限はありません。新しくサポートされる年の範囲は 1000 以上 9999 以下です。

Whenever a two-digit year is used in a time tuple, the interpretation has been governed by time.accept2dyear. The default is True which means that for a two-digit year, the century is guessed according to the POSIX rules governing the %y strptime format.

Starting with Py3.2, use of the century guessing heuristic will emit a DeprecationWarning. Instead, it is recommended that time.accept2dyear be set to False so that large date ranges can be used without guesswork:

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

Several functions now have significantly expanded date ranges. When time.accept2dyear is false, the time.asctime() function will accept any year that fits in a C int, while the time.mktime() and time.strftime() functions will accept the full range supported by the corresponding operating system functions.

(Contributed by Alexander Belopolsky and Victor Stinner in bpo-1289118 [https://bugs.python.org/issue?@action=redirect&bpo=1289118], bpo-5094 [https://bugs.python.org/issue?@action=redirect&bpo=5094], bpo-6641 [https://bugs.python.org/issue?@action=redirect&bpo=6641], bpo-2706 [https://bugs.python.org/issue?@action=redirect&bpo=2706], bpo-1777412 [https://bugs.python.org/issue?@action=redirect&bpo=1777412], bpo-8013 [https://bugs.python.org/issue?@action=redirect&bpo=8013], and bpo-10827 [https://bugs.python.org/issue?@action=redirect&bpo=10827].)

math

math モジュールがアップデートされ、C99 標準に触発されて6つの新たな関数が追加されました。

isfinite() 関数は特殊値を確実に、かつ高速に検出する方法を提供します。通常の数には True を、Nan や Infinity には False を返します:

>>> from math import isfinite
>>> [isfinite(x) for x in (123, 4.56, float('Nan'), float('Inf'))]
[True, True, False, False]

expm1() 関数は小さな x に対しても精度を失うこと (訳注: 桁落ち) なく e**x-1 を計算します。通常、桁落ちは非常に近い数の引き算で起こります。

>>> from math import expm1
>>> expm1(0.013671875)   # more accurate way to compute e**x-1 for a small x
0.013765762467652909

erf() 関数は確率積分、すなわち 誤差関数 [https://ja.wikipedia.org/wiki/%E8%AA%A4%E5%B7%AE%E9%96%A2%E6%95%B0] を返します。 相補誤差関数 erfc() は 1 - erf(x) です:

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

gamma() 関数は階乗を連続的に拡張したものです。詳細は ガンマ関数 [https://ja.wikipedia.org/wiki/%E3%82%AC%E3%83%B3%E3%83%9E%E9%96%A2%E6%95%B0] を参照してください。ガンマ関数は階乗に関係しているため、小さな x でも大きくなります。そのため、ガンマ関数の自然対数を計算する lgamma() 関数があります。

>>> from math import gamma, lgamma
>>> gamma(7.0)           # six factorial
720.0
>>> lgamma(801.0)        # log(800 factorial)
4551.950730698041

(Contributed by Mark Dickinson.)

abc

abc モジュールは abstractclassmethod() と abstractstaticmethod() をサポートしました。

これらのツールによって特定の classmethod() や staticmethod() を実装する必要のある 抽象基底クラス を定義することが出来ます。

class Temperature(metaclass=abc.ABCMeta):
    @abc.abstractclassmethod
    def from_fahrenheit(cls, t):
        ...
    @abc.abstractclassmethod
    def from_celsius(cls, t):
        ...

(Patch submitted by Daniel Urban; bpo-5867 [https://bugs.python.org/issue?@action=redirect&bpo=5867].)

io

io.BytesIO に memoryview() と同様の機能を提供する新たなメソッド getbuffer() が追加されました。このメソッドはコピーせずにデータの編集可能なビューを作成します。バッファのランダムアクセスとスライス記法のサポートはインプレースな編集に適しています:

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

(Contributed by Antoine Pitrou in bpo-5506 [https://bugs.python.org/issue?@action=redirect&bpo=5506].)

reprlib

When writing a __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 list and set handle self-reference by displaying "..." in the recursive part of the representation string.

To help write such __repr__() methods, the reprlib module has a new decorator, recursive_repr(), for detecting recursive calls to __repr__() and substituting a placeholder string instead:

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

(Contributed by Raymond Hettinger in bpo-9826 [https://bugs.python.org/issue?@action=redirect&bpo=9826] and bpo-9840 [https://bugs.python.org/issue?@action=redirect&bpo=9840].)

logging

上記の辞書ベースの設定に加え、logging パッケージには他にも多くの改良があります。

ロギングのドキュメントは 基本チュートリアル 、 上級チュートリアル 、 クックブック により増強されてきました。ロギングについて学習するにはこれらのドキュメントが最速の方法です。

セットアップ関数 logging.basicConfig() に style 引数が追加され、これにより異なる 3 つのタイプの文字列書式化がサポートされます。デフォルトは伝統的な % 書式化を使う "%" で、 str.format() スタイルの "{" 、 string.Template で提供されるシェルスタイルの "$" をセット出来ます。以下の 3 つの設定は等価です:

>>> 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")

If no configuration is set-up before a logging event occurs, there is now a default configuration using a StreamHandler directed to sys.stderr for events of 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 logging.raiseExceptions. The new default handler is stored in logging.lastResort.

フィルタの利用は単純になりました。 Filter オブジェクトを作る代わりに、 True か False を返す任意の Python 呼び出し可能オブジェクトを述語 (predicate) として利用出来ます。

ほかにも柔軟性を高め、設定を単純化する数多くの改善がありました。Python 3.2 での全ての変更についてはモジュールのドキュメントを参照してください。

csv

csv モジュールは新たな方言 unix_dialect をサポートしました。この方言は全フィールドをクォートし、行末を伝統的な Unix 形式の '\n' にします。登録された方言名は unix です。

csv.DictWriter に新たなメソッド writeheader() が追加されました。最初の列をドキュメントのフィールド名に書き出すのに使用します:

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

(New dialect suggested by Jay Talbot in bpo-5975 [https://bugs.python.org/issue?@action=redirect&bpo=5975], and the new method suggested by Ed Abraham in bpo-1537721 [https://bugs.python.org/issue?@action=redirect&bpo=1537721].)

contextlib

新しく追加され、そして少しばかりハートを揺さぶるツール ContextDecorator は、関数デコレータとしての任務も果たす context manager を作るのに役立つものです。

利便性のためにこの新機能は contextmanager() で使われているので、両方の役割をサポートするのにことさら労力は要しません。

基本的なアイディアは、コンテキストマネージャも関数デコレータも、ともに事前アクション・事後アクションラッパーとして使うことが出来るというものです。コンテキストマネージャは with 文を使ったステートメント (文) のグループを包みますし、関数デコレータは関数に取り囲まれたステートメントのグループを包みます。そうです、どちらかの役割で使える事前アクションあるいは事後アクションラッパーを書く必要性は、しばしば起こることです。

たとえば関数やステートメントのグループをロガーで包んで、開始時刻と終了時刻を追跡できるようにするとしばしば便利です。このタスクをこなすために関数デコレータとコンテキストマネージャの両方を書く代わりに、 contextmanager() が単一の定義に両方の能力をもたらしてくれます:

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)

ContextDecorator が使われる前の 3.1 までの contextmanager() では、これはコンテキストマネージャとして使えるだけでした:

with track_entry_and_exit('widget loader'):
    print('Some time consuming activity goes here')
    load_widget()

今ではこれはデコレータとしても使えます:

@track_entry_and_exit('widget loader')
def activity():
    print('Some time consuming activity goes here')
    load_widget()

一つの場所に二重の責務を持たせることには普通ある種の制約を持ち込みます。コンテキストマネージャには普通は with 文で使える値を返せる柔軟性を持ちますが、関数デコレータにはそれに匹敵するものはありません。

上の例の場合は、track_entry_and_exit コンテキストマネージャが、取り囲まれたステートメント本体で使えるロギングのインスタンスを返す綺麗な方法はありません。

(Contributed by Michael Foord in bpo-9110 [https://bugs.python.org/issue?@action=redirect&bpo=9110].)

decimal と fractions

Mark Dickinson は、異なる数値データの型が実際の値が等しい場合は常に同じハッシュ値を持つことを保証する、エレガントで効率的なスキームを作り上げました (bpo-8188 [https://bugs.python.org/issue?@action=redirect&bpo=8188]):

assert hash(Fraction(3, 2)) == hash(1.5) == \
       hash(Decimal("1.5")) == hash(complex(1.5, 0))

Some of the hashing details are exposed through a new attribute, 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:

>>> sys.hash_info
sys.hash_info(width=64, modulus=2305843009213693951, inf=314159, nan=0, imag=1000003)

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

decimal.Decimal コンストラクタに float オブジェクトを直接渡せるようになりました。これにより from_float() メソッドを使う必要はなくなりました (bpo-8257 [https://bugs.python.org/issue?@action=redirect&bpo=8257])。

型違いの比較はいまでは完全にサポートされたので、 Decimal オブジェクトを直接 float や fractions.Fraction と比較出来ます (bpo-2531 [https://bugs.python.org/issue?@action=redirect&bpo=2531] and bpo-8188 [https://bugs.python.org/issue?@action=redirect&bpo=8188])。

同じ変更が fractions.Fraction にもなされたので、 from_float() も from_decimal() も、もはや必要ありません (bpo-8294 [https://bugs.python.org/issue?@action=redirect&bpo=8294]):

>>> from decimal import Decimal
>>> from fractions import Fraction
>>> Decimal(1.1)
Decimal('1.100000000000000088817841970012523233890533447265625')
>>> Fraction(1.1)
Fraction(2476979795053773, 2251799813685248)

Another useful change for the decimal module is that the 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 [https://bugs.python.org/issue?@action=redirect&bpo=8540]).

(Contributed by Mark Dickinson and Raymond Hettinger.)

ftp

ftplib.FTP クラスがコンテキスト管理プロトコルをサポートするようになりました。with ブロックを抜ける際に無条件に FTP 接続をクローズします (クローズ処理で発生する socket.error は無視されます)。:

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

ちなみに mmap.mmap や fileinput.input() のようなほかのファイルライクなオブジェクトも自動クローズするコンテキスト管理プロトコルをサポートするようになっていたりします:

with fileinput.input(files=('log1.txt', 'log2.txt')) as f:
    for line in f:
        process(line)

(Contributed by Tarek Ziadé and Giampaolo Rodolà in bpo-4972 [https://bugs.python.org/issue?@action=redirect&bpo=4972], and by Georg Brandl in bpo-8046 [https://bugs.python.org/issue?@action=redirect&bpo=8046] and bpo-1286 [https://bugs.python.org/issue?@action=redirect&bpo=1286].)

FTP_TLS クラスが context パラメータを受け取れるようになりました。これには ssl.SSLContext オブジェクトを渡します。これは SSL コンフィグレーションオプション、証明書、秘密鍵を単一の (たぶん長生きの) 構造にまとめあげてくれるものです。

(Contributed by Giampaolo Rodolà; bpo-8806 [https://bugs.python.org/issue?@action=redirect&bpo=8806].)

popen

os.popen() ならびに subprocess.Popen() 関数が自動的にファイル記述子を閉じる with 文をサポートしました。

(Contributed by Antoine Pitrou and Brian Curtin in bpo-7461 [https://bugs.python.org/issue?@action=redirect&bpo=7461] and bpo-10554 [https://bugs.python.org/issue?@action=redirect&bpo=10554].)

select

The select module now exposes a new, constant attribute, PIPE_BUF, which gives the minimum number of bytes which are guaranteed not to block when select.select() says a pipe is ready for writing.

>>> import select
>>> select.PIPE_BUF
512

(Available on Unix systems. Patch by Sébastien Sablé in bpo-9862 [https://bugs.python.org/issue?@action=redirect&bpo=9862])

gzip と zipfile

gzip.GzipFile が io.BufferedIOBase 抽象基底クラス を継承しました (truncate() をのぞく)。 peek() メソッドが追加され、シーク不能なファイルオブジェクトならびにゼロ埋めされたファイルオブジェクトをサポートしました。

また、gzip モジュールにより簡便でインメモリな圧縮および解凍を行う compress() ならびに decompress() 関数が追加されました。圧縮や解凍の前に bytes としてエンコードしなければならない点に注意してください:

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

(Contributed by Anand B. Pillai in bpo-3488 [https://bugs.python.org/issue?@action=redirect&bpo=3488]; and by Antoine Pitrou, Nir Aides and Brian Curtin in bpo-9962 [https://bugs.python.org/issue?@action=redirect&bpo=9962], bpo-1675951 [https://bugs.python.org/issue?@action=redirect&bpo=1675951], bpo-7471 [https://bugs.python.org/issue?@action=redirect&bpo=7471] and bpo-2846 [https://bugs.python.org/issue?@action=redirect&bpo=2846].)

Also, the 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 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 [https://bugs.python.org/issue?@action=redirect&bpo=7610].)

tarfile

TarFile クラスは今ではコンテキストマネージャとして使えます。加えて、その add() メソッドに新しいオプション filter が追加されました。これはファイルをアーカイブに追加するかどうかを制御し、また、ファイルのメタデータを編集するのにも使えます。

filter オプションは古くて柔軟性に欠ける exclude パラメータを置き換えるものであり、 exclude は非推奨となりました。 filter を指定する場合は keyword argument として渡さなければなりません。ユーザ指定の filter 関数は TarInfo オブジェクトを受け取り、更新した TarInfo オブジェクトを返すか、あるいはアーカイブから除外したければ None を返してください。

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

(Proposed by Tarek Ziadé and implemented by Lars Gustäbel in bpo-6856 [https://bugs.python.org/issue?@action=redirect&bpo=6856].)

hashlib

hashlib モジュールに、2 つの定数属性が追加されました。全ての実装で利用可能であることが保障されているハッシュアルゴリズムのリストと、現在の実装で利用可能なそれらリストの 2 つです:

>>> 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'}

(Suggested by Carl Chenet in bpo-7418 [https://bugs.python.org/issue?@action=redirect&bpo=7418].)

ast

ast モジュールには、Python リテラル構文を使った式文字列を安全に評価できる、汎用目的の素晴らしい道具が含まれています。その ast.literal_eval() 関数は、悪用されやすい組み込み関数 eval() の安全な代替品として働いてくれます。Python 3.2 はこれのサポート型に bytes と set を加えました。結果サポートする型は全部でこれらになりました: 文字列型、バイト列文字列型、数値型、タプル型、リスト型、辞書型、集合型、真偽値型、None。

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

(Implemented by Benjamin Peterson and Georg Brandl.)

os

ファイル名と環境変数に使われるエンコーディングは OS ごとに様々です。 os モジュールは新たに 2 つの関数 fsencode() と fsdecode() を追加しました。それぞれファイル名のエンコード、デコードを行います:

>>> import os
>>> filename = 'Sehenswürdigkeiten'
>>> os.fsencode(filename)
b'Sehensw\xc3\xbcrdigkeiten'

Some operating systems allow direct access to encoded bytes in the environment. If so, the os.supports_bytes_environ constant will be true.

エンコードされた環境変数への直接アクセス (可能な場合) には、新規関数 os.getenvb() または os.environb を使ってください。これは os.environ のバイト列バージョンです。

(Contributed by Victor Stinner.)

shutil

shutil.copytree() 関数に新たに 2 つのオプションが追加されました:

ignore_dangling_symlinks: symlinks=False とするとこの関数は、ファイルがシンボリックリンクだった場合にリンクそのものではなくそれが指しているファイルをコピーします。 ignore_dangling_symlinks を真にすると、そのファイルが存在しない場合のエラーを無視します。

copy_function: これはファイルをコピーするのに使われる呼び出し可能オブジェクトです。デフォルトでは shutil.copy2() が使われます。

(Contributed by Tarek Ziadé.)

これらに加え、 shutil モジュールは ZIP ファイル、未圧縮の tar ファイル、gzip 圧縮の tar、 bzip 圧縮の tar のための archiving operations を新たにサポートします。また、追加のアーカイブファイルフォーマットを登録する関数もあります (例えば xz 圧縮の tar やカスタムフォーマット)。

そのメインとなるのが make_archive() と unpack_archive() です。デフォルトではカレントディレクトリ (os.chdir() で変えれます) とそのサブディレクトリの両方を処理します。アーカイブファイル名はフルパス名で指定しなければなりません(訳注: これの真偽不明。リファレンスに対応する記述なし)。アーカイブするステップは非破壊的です (つまりオリジナルのファイルは変更されずにそのままにされます)。

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

(Contributed by Tarek Ziadé.)

sqlite3

sqlite3 モジュールが pysqlite バージョン 2.6.0 に更新されました。これには 2 つの新機能があります。

The sqlite3.Connection.in_transit attribute is true if there is an active transaction for uncommitted changes.

sqlite3.Connection.enable_load_extension() メソッドと sqlite3.Connection.load_extension() メソッドにより ".so" ファイルから SQLite 拡張をロードできます。良く知られた拡張の一つとして、SQLite と一緒に配布されている全文検索拡張があります。

(Contributed by R. David Murray and Shashwat Anand; bpo-8845 [https://bugs.python.org/issue?@action=redirect&bpo=8845].)

html

ただ一つの関数 escape() が提供される、新しい html モジュールが導入されました。これは HTML マークアップから予約されている文字をエスケープするのに使います:

>>> import html
>>> html.escape('x > 2 && x < 7')
'x &gt; 2 &amp;&amp; x &lt; 7'

socket

socket モジュールに新たに二つの改善がありました。

ソケットオブジェクトに detach() メソッドが追加されました。これは背後のファイル記述子を閉じることなくソケットをクローズ状態にします。これによりファイル記述子は他の目的に再利用出来ます。 (Added by Antoine Pitrou; bpo-8524 [https://bugs.python.org/issue?@action=redirect&bpo=8524].)

socket.create_connection() がコンテキスト管理プロトコルをサポートするようになりました。with ブロックを抜ける際に無条件にソケットをクローズします (クローズ処理で発生する socket.error は無視されます)。 (Contributed by Giampaolo Rodolà; bpo-9794 [https://bugs.python.org/issue?@action=redirect&bpo=9794].) (---訳注: リファレンスもそうなのですが、「 socket.create_connection() が with をサポート」というのは実態とは違うんじゃないかと思います(この関数のユーザからは同じにみえたとしても)。実際には socket.socket がコンテキストマネージャをサポートしています。 socket.py [https://hg.python.org/cpython/file/3.2/Lib/socket.py] 参照。--)

ssl

ssl モジュールは、セキュアな (暗号化され、認証された) インターネット接続のために共通の要求を満足するための数多くの機能を追加しています:

新規クラス SSLContext は、プロトコル設定や証明書、秘密鍵やそのた色々なオプションのような、永続的 SSL データの容器として働きます。その中のメソッド wrap_socket() を使うと、 SSL コンテキストから SSL ソケットを作れます。

A new function, ssl.match_hostname(), supports server identity verification for higher-level protocols by implementing the rules of HTTPS (from RFC 2818 [https://datatracker.ietf.org/doc/html/rfc2818.html]) which are also suitable for other protocols.

The 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 [https://www.openssl.org/docs/man1.0.2/man1/ciphers.html#CIPHER-LIST-FORMAT].

最新版の OpenSSL にリンクしていれば、 ssl モジュールは TLS プロトコルに対する Server Name Indication 拡張 (訳注: SNI, RFC 4366 [https://datatracker.ietf.org/doc/html/rfc4366.html]) をサポートします。これは単一の IP ポートで異なった証明書を使った複数「バーチャルホスト」をもたらすものです。この拡張はクライアントモードでのみサポートされ、 ssl.SSLContext.wrap_socket() の server_hostname を渡すことで活性化されます。

ssl モジュールに色々オプションが追加されました。例えば OP_NO_SSLv2 は安全でなく時代遅れの SSLv2 を無効にします。

拡張はOpenSSL の全ての暗号とメッセージダイジェストアルゴリズムをロードします。SSL 証明書の中に検証できないものがある場合、"unknown algorithm" エラーを報告します。

The version of OpenSSL being used is now accessible using the module attributes ssl.OPENSSL_VERSION (a string), ssl.OPENSSL_VERSION_INFO (a 5-tuple), and ssl.OPENSSL_VERSION_NUMBER (an integer).

(Contributed by Antoine Pitrou in bpo-8850 [https://bugs.python.org/issue?@action=redirect&bpo=8850], bpo-1589 [https://bugs.python.org/issue?@action=redirect&bpo=1589], bpo-8322 [https://bugs.python.org/issue?@action=redirect&bpo=8322], bpo-5639 [https://bugs.python.org/issue?@action=redirect&bpo=5639], bpo-4870 [https://bugs.python.org/issue?@action=redirect&bpo=4870], bpo-8484 [https://bugs.python.org/issue?@action=redirect&bpo=8484], and bpo-8321 [https://bugs.python.org/issue?@action=redirect&bpo=8321].)

nntp

The 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 nntplib.NNTP_SSL) and explicit (using nntplib.NNTP.starttls()) TLS has also been added.

(Contributed by Antoine Pitrou in bpo-9360 [https://bugs.python.org/issue?@action=redirect&bpo=9360] and Andrew Vant in bpo-1926 [https://bugs.python.org/issue?@action=redirect&bpo=1926].)

certificates

http.client.HTTPSConnection, urllib.request.HTTPSHandler urllib.request.urlopen() はサーバ証明書を証明書認証局 (Certification Authority (CA)) セットと照合するためのオプショナル引数を取るようになりました。これは HTTPS の公共利用で推奨されるものです。(---訳注: これは check_hostname パラメータのことを指していますが、3.4.3 でこれの扱いが変わっているのでリファレンスを注意深く読んで下さい。--)

(Added by Antoine Pitrou, bpo-9003 [https://bugs.python.org/issue?@action=redirect&bpo=9003].)

imaplib

標準 IMAP4 接続での明示的な TLS 使用を新規メソッド imaplib.IMAP4.starttls で出来るようになりました。

(Contributed by Lorenzo M. Catucci and Antoine Pitrou, bpo-4471 [https://bugs.python.org/issue?@action=redirect&bpo=4471].)

http.client

http.client モジュールに数多くの小さな API 改善がなされています。旧式 HTTP 0.9 の単純な応答 (HTTP 0.9 simple responses) はもうサポートされず、また、 strict パラメータは全てのクラスで非推奨となりました。

HTTPConnection クラスと HTTPSConnection クラスが source_address パラメータを取るようになりました。これには HTTP(S) 接続の接続元を表す (host, port) のタプルを渡します。

HTTPSConnection に、証明書検証と HTTPS バーチャルホストのサポートが追加されました。

接続オブジェクトの request() メソッドのオプショナルな body 引数には、リクエストのコンテンツを与えるために file object を渡すことが出来ました。便利のためにこれに iterable も渡すことが出来るようになりました。ただしこの場合は明示的に Content-Length ヘッダを加えなければなりません。この拡張されたインターフェイスは以前よりも遥かに柔軟です。

プロキシサーバ経由で HTTPS 接続を確立するために、新規メソッド set_tunnel() が追加されています。これにより HTTP 接続トンネリングのためのホストとポートをセットします。

http.server の振る舞いと合わせ、HTTP クライアントライブラリもヘッダを ISO-8859-1 (Latin-1) エンコーディングでエンコードするようになりました。これは既に incoming (外から来る方) ヘッダに対して行われていますが、今ではこの振る舞いは incoming、outgoing (外へ向かう方) トラフィックの両方で一貫しています (bpo-10980 [https://bugs.python.org/issue?@action=redirect&bpo=10980] 内の Armin Ronacher による仕事を参照)。

unittest

unittest モジュールに数多くの改善がありました。パッケージに対する test discovery のサポートが追加され、対話プロンプトから実験しやすくなり、新しいメソッドが追加され、テスト失敗時の診断メッセージが改善され、そしてメソッド名がより良いものになりました。

The command-line call python -m unittest can now accept file paths instead of module names for running specific tests (bpo-10620 [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 -t option, a pattern for matching files with -p, and a directory to start discovery with -s:

$ python -m unittest discover -s my_proj_dir -p _test.py

(Contributed by Michael Foord.)

Experimentation at the interactive prompt is now easier because the unittest.TestCase class can now be instantiated without arguments:

>>> from unittest import TestCase
>>> TestCase().assertEqual(pow(2, 3), 8)

(Contributed by Michael Foord.)

unittest モジュールは 2 つの新メソッド assertWarns() と assertWarnsRegex() を持ちます。これらはテストのもとでコードによって所与の警告が発行されるかどうかを検証します:

with self.assertWarns(DeprecationWarning):
    legacy_function('XYZ')

(Contributed by Antoine Pitrou, bpo-9754 [https://bugs.python.org/issue?@action=redirect&bpo=9754].)

もう一つの新メソッド assertCountEqual() は 2 つのイテラブルを比較して、要素の出現回数が同じか (順序に関わらず同じ要素が同じ数だけ出現するかどうか) をテストします:

def test_anagram(self):
    self.assertCountEqual('algorithm', 'logarithm')

(Contributed by Raymond Hettinger.)

unittest モジュールの大事な特長は、テスト失敗時の有意義な診断を生成するよう腐心してくれることです。可能ならば失敗は期待値と実際の出力との差分と一緒に記録されます。これは失敗したテスト実行の解析に特に役に立ちますが、差分は時々とてつもなく大きくもなりますので、新たに追加した属性 maxDiff に差分の最大長をセットすることで表示を制御できるようになりました。

さらにモジュールのメソッド名に数多くのクリーンアップを行いました。

For example, assertRegex() is the new name for assertRegexpMatches() which was misnamed because the test uses re.search(), not 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 re module, and it has unambiguous camel-casing.

(Contributed by Raymond Hettinger and implemented by Ezio Melotti.)

一貫性を向上させるために、長年使用されたメソッドエイリアスが推奨名に対し非推奨になりました:

以前の名前

推奨名

assert_()

assertTrue()

assertEquals()

assertEqual()

assertNotEquals()

assertNotEqual()

assertAlmostEquals()

assertAlmostEqual()

assertNotAlmostEquals()

assertNotAlmostEqual()

Likewise, the TestCase.fail* methods deprecated in Python 3.1 are expected to be removed in Python 3.3.

(Contributed by Ezio Melotti; bpo-9424 [https://bugs.python.org/issue?@action=redirect&bpo=9424].)

The 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 TestCase().assertDictContainsSubset({'a':1, 'b':2}, {'a':1}) would fail.

(Contributed by Raymond Hettinger.)

random

random モジュールの整数メソッドの一様分布の生成が改善されました。以前は int(n*random()) を計算していました。この方法では n が2の冪乗でない限り僅かにバイアスがあります。現在の方法では次の2の冪乗の範囲まで複数の選択肢を作成し、0 <= x < n の範囲に入ったもののみを保持します。影響を受ける関数やメソッドは randrange()、randint()、choice()、shuffle() ならびに sample() です。

(Contributed by Raymond Hettinger; bpo-9025 [https://bugs.python.org/issue?@action=redirect&bpo=9025].)

poplib

POP3_SSL クラスが context パラメータを受け取れるようになりました。これには ssl.SSLContext オブジェクトを渡します。これは SSL コンフィグレーションオプション、証明書、秘密鍵を単一の (たぶん長生きの) 構造にまとめあげてくれるものです。

(Contributed by Giampaolo Rodolà; bpo-8807 [https://bugs.python.org/issue?@action=redirect&bpo=8807].)

asyncore

asyncore.dispatcher now provides a handle_accepted() method returning a (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 handle_accept() and avoids the user to call accept() directly.

(Contributed by Giampaolo Rodolà; bpo-6706 [https://bugs.python.org/issue?@action=redirect&bpo=6706].)

tempfile

tempfile モジュールに新たなコンテキストマネージャ TemporaryDirectory が追加されました。一時ディレクトリの確実な後片付けを容易に行えます:

with tempfile.TemporaryDirectory() as tmpdirname:
    print('created temporary dir:', tmpdirname)

(Contributed by Neil Schemenauer and Nick Coghlan; bpo-5178 [https://bugs.python.org/issue?@action=redirect&bpo=5178].)

inspect

inspect モジュールに新たな関数 getgeneratorstate() が追加されました。これで簡単にジェネレータイテレータの現在状態を識別出来ます (---訳注: generator-iterator という用語を使っている箇所は Python ドキュメント全体通して多くはないのですが 2.x の yield 文 説明中に登場します。ジェネレータと同じ意味です。なお getgeneratorstate はジェネレータでないイテレータには使えません。---):

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

(Contributed by Rodolpho Eckhardt and Nick Coghlan, bpo-10220 [https://bugs.python.org/issue?@action=redirect&bpo=10220].)

動的な属性を活性化することなく検索するのをサポートするために、 inspect モジュールに getattr_static() 関数が追加されました。 hasattr() とは違ってこれは本当に読み出しのみの検索であり、検索中に状態変更しないことが保障されています:

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

(Contributed by Michael Foord.)

pydoc

The pydoc module now provides a much-improved web server interface, as well as a new command-line option -b to automatically open a browser window to display that server:

$ pydoc3.2 -b

(Contributed by Ron Adam; bpo-2001 [https://bugs.python.org/issue?@action=redirect&bpo=2001].)

dis

dis モジュールに、コードを調べるための 2 つの新しい関数 code_info() と show_code() が追加されました。ともに、与えられた関数、メソッド、ソースコード文字列、コードオブジェクトについての詳細なコードオブジェクト情報を提供します。前者はそれを文字列で返し、後者は印字します:

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

また、 dis() 関数が文字列引数を取れるようになり、これによって、よくあるイディオム dis(compile(s, '', 'eval')) は dis(s) で一撃です:

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

要はこれらによって、CPython がどう実装されているか探索してみたり、言語構文が裏方で何をするのか見てみたりすることがより簡単になったということです。

(Contributed by Nick Coghlan in bpo-9147 [https://bugs.python.org/issue?@action=redirect&bpo=9147].)

dbm

All database modules now support the get() and setdefault() methods.

(Suggested by Ray Allen in bpo-9523 [https://bugs.python.org/issue?@action=redirect&bpo=9523].)

ctypes

C ssize_t データ型を表現する新たな型 ctypes.c_ssize_t が追加されました。

site

site モジュールに、Python インストレーションの詳細を報告するのに有益な3つの新たな関数が追加されました。

getsitepackages() は全てのグローバルな site-packages ディレクトリを一覧します。

getuserbase() は、ユーザのデータを格納できるベースディレクトリを報告します。

getusersitepackages() はユーザ固有の site-packages ディレクトリのパスを明らかにします。

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

便宜のために、いくつかの site の機能はコマンドラインから直接アクセス可能です:

$ python -m site --user-base
/Users/raymondhettinger/.local
$ python -m site --user-site
/Users/raymondhettinger/.local/lib/python3.2/site-packages

(Contributed by Tarek Ziadé in bpo-6693 [https://bugs.python.org/issue?@action=redirect&bpo=6693].)

sysconfig

新しい sysconfig モジュールは、プラットフォームやインストレーションごとに変わるインストールパスや環境設定変数への、直接的なアクセスを提供します。

このモジュールはプラットフォームとバージョンの情報へのシンプルなアクセス関数を持っています:

get_platform() は linux-i586 や macosx-10.6-ppc といった値を返します。

get_python_version() は Python バージョンを文字列で "3.2" のように返します。

It also provides access to the paths and variables corresponding to one of seven named schemes used by distutils. Those include posix_prefix, posix_home, posix_user, nt, nt_user, os2, os2_home:

get_paths() は現在のインストールスキームに関するインストールパスを含むディレクトリ名を作ります。

get_config_vars() はプラットフォーム依存変数の辞書を返します。

便利なコマンドラインインターフェースもあります:

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"

(Moved out of Distutils by Tarek Ziadé.)

pdb

pdb デバッガモジュールに数多くのユーザビリティの改善がなされました:

pdb.py は -c オプションで指定した .pdbrc スクリプトファイルを実行できるようになっています。

.pdbrc スクリプトファイルにはデバッグを継続する continue コマンドと next コマンドを含むことができます。

The Pdb class constructor now accepts a nosigint argument.

新コマンド: l(list), ll(long list), source はソースコードを出力します。

新コマンド: display, undisplay は、変更があった場合の式の値の表示/非表示を切り替えます。

新コマンド: interact は現在のスコープで見つかったグローバルおよびローカル名を含む対話型インタプリタを開始します。

ブレイクポイントをブレイクポイント番号指定でクリア出来ます。

(Contributed by Georg Brandl, Antonio Cuni and Ilya Sandler.)

configparser

The configparser module was modified to improve usability and predictability of the default parser and its supported INI syntax. The old ConfigParser class was removed in favor of SafeConfigParser which has in turn been renamed to 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 はマッピングプロトコルにもとづく新しい API を獲得しました:

>>> 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)'

新しい API は旧式 API の上に実装されているので、カスタムなパーサーサブクラスは変更なしで使えるはずです。

config parser によって受け付けられる INI ファイルの構造は今ではカスタマイズ出来ます。ユーザは、オプションと値を区切る代替のデリミタやコメントのプレフィクスを指定でき、 DEFAULT セクションの名前を変えることができ、あるいは補間の構文を切り替えられます。

抜き挿し可能 (pluggable) な補間サポートがあって、これには追加の補間ハンドラ ExtendedInterpolation が含まれています:

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

小さな機能もたくさん導入されています。例えば読み込み操作内でのエンコーディング指定のサポート、取得関数でのフォールバック値の指定、あるいは辞書や文字列から直接的に読むことなどです。

(All changes contributed by Łukasz Langa.)

urllib.parse

数多くのユーザビリティーの改善が urllib.parse モジュールになされました。

urlparse() 関数が RFC 2732 [https://datatracker.ietf.org/doc/html/rfc2732.html] にて記述されている IPv6 [https://ja.wikipedia.org/wiki/IPv6] アドレスをサポートするようになりました:

>>> 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='',
            query='',
            fragment='')

urldefrag() 関数は、今や named tuple を返します:

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

また、 urlencode() 関数はさらに柔軟になり、 query 引数としては文字列とバイト列のどちらも受け付けます。文字列で渡した場合、パラメータ safe, encoding, error がエンコードのために quote_plus() に送られます:

>>> urllib.parse.urlencode([
...      ('type', 'telenovela'),
...      ('name', '¿Dónde Está Elisa?')],
...      encoding='latin-1')
'type=telenovela&name=%BFD%F3nde+Est%E1+Elisa%3F'

ASCII エンコードバイト列の解析 に詳細に書きましたが、全ての urllib.parse 関数は今では ASCII エンコードされたバイト文字列を (通常の文字列と混ぜない限り) 入力として受け付けます。ASCII エンコードされたバイト文字列がパラメータとして与えられると、戻り値の型も ASCII エンコードされたバイト文字列になります:

>>> 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'', query=b'', fragment=b'')

(Work by Nick Coghlan, Dan Mahn, and Senthil Kumaran in bpo-2987 [https://bugs.python.org/issue?@action=redirect&bpo=2987], bpo-5468 [https://bugs.python.org/issue?@action=redirect&bpo=5468], and bpo-9873 [https://bugs.python.org/issue?@action=redirect&bpo=9873].)

mailbox

R. David Murray がコミュニティの調整に尽力したおかげで、 mailbox が Python 3.2 のために修正されました。闘いを挑んだ相手はもともとの mailbox 設計のテキストインターフェイスでした。ですが email メッセージは個々の異なるパートが異なるエンコーディングを持ち得ますから、 bytes が最良の表現です。

解決のためには任意の email メッセージをパースするために、 email パッケージのバイナリサポートが利用されました (---訳注: BytesGenerator や message_from_bytes() など)。また、API の変更も必要となりました。

mailbox.Mailbox オブジェクトの add() メソッドは、今や期待通りにバイナリ入力を受け付けます。

StringIO とテキストファイルでの入力は非推奨となりました。また、文字列での入力は、非 ASCII 文字が使用されていると早々に失敗します。以前は後のほうのステップで email が処理される際にようやく失敗していました。

バイナリ出力のサポートもあります。 get_file() メソッドは今ではバイナリモードのファイルを返します (これまでは不適切にテキストモードが使われていました)。また、新しい get_bytes() メソッドは、指定した key に対応するメッセージの bytes 表現を返します。

今でも古い API の get_string() を使って非バイナリ出力は可能ですが、そのアプローチはあまり役に立ちません。そうではなく Message オブジェクトからメッセージを抽出するか、それらをバイナリ入力からロードするのが最善です。

(Contributed by R. David Murray, with efforts from Steffen Daode Nurpmeso and an initial patch by Victor Stinner in bpo-9124 [https://bugs.python.org/issue?@action=redirect&bpo=9124].)

turtledemo

The demonstration code for the turtle module was moved from the Demo directory to main library. It includes over a dozen sample scripts with lively displays. Being on sys.path, it can now be run directly from the command-line:

$ python -m turtledemo

(Moved from the Demo directory by Alexander Belopolsky in bpo-10199 [https://bugs.python.org/issue?@action=redirect&bpo=10199].)

マルチスレッディング

The mechanism for serializing execution of concurrently running Python threads (generally known as the 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 sys.setswitchinterval(). It currently defaults to 5 milliseconds.

この実装に関するさらなる詳細は python-dev mailing-list message [https://mail.python.org/pipermail/python-dev/2009-October/093321.html] で読むことが出来ます (ただしこのメッセージで言っている "priority requests" は含められませんでした)。

(Contributed by Antoine Pitrou.)

通常のロックと再帰的なロックが、acquire() メソッドでオプションで timeout 引数を受け取るようになりました。 (Contributed by Antoine Pitrou; bpo-7316 [https://bugs.python.org/issue?@action=redirect&bpo=7316].)

同様に、threading.Semaphore.acquire() にも timeout 引数が追加されました。 (Contributed by Torsten Landschoff; bpo-850728 [https://bugs.python.org/issue?@action=redirect&bpo=850728].)

通常のロックと再帰的なロックの獲得に、 Pthreads を使用するプラットフォームでシグナルが割り込めるようになりました。これでロック獲得時にデッドロックしていた Python プログラムは、プロセスに SIGINT (ほとんどのシェルでは Ctrl+C で) を繰り返し送ることで殺せます。(Contributed by Reid Kleckner; bpo-8844 [https://bugs.python.org/issue?@action=redirect&bpo=8844].)

最適化

小さな性能向上が多く追加されました:

Python's peephole optimizer now recognizes patterns such x in {1, 2, 3} as being a test for membership in a set of constants. The optimizer recasts the set as a 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:

extension = name.rpartition('.')[2]
if extension in {'xml', 'html', 'xhtml', 'css'}:
    handle(name)

(Patch and additional tests contributed by Dave Malcolm; bpo-6690 [https://bugs.python.org/issue?@action=redirect&bpo=6690]).

pickle モジュールを用いたデータのシリアライズ・デシリアライズが数倍速くなりました。

(Contributed by Alexandre Vassalotti, Antoine Pitrou and the Unladen Swallow team in bpo-9410 [https://bugs.python.org/issue?@action=redirect&bpo=9410] and bpo-3873 [https://bugs.python.org/issue?@action=redirect&bpo=3873].)

The Timsort algorithm [https://en.wikipedia.org/wiki/Timsort] used in list.sort() and sorted() now runs faster and uses less memory when called with a 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 [https://bugs.python.org/issue?@action=redirect&bpo=9915].)

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 sort_keys argument is true.

(Contributed by Antoine Pitrou in bpo-7451 [https://bugs.python.org/issue?@action=redirect&bpo=7451] and by Raymond Hettinger and Antoine Pitrou in bpo-10314 [https://bugs.python.org/issue?@action=redirect&bpo=10314].)

再帰的ロック (threading.RLock() API により生成) は C で実装されたことにより、以前の純粋な Python 実装より10から15倍速くなり、通常のロックと同じくらいになりました。

(Contributed by Antoine Pitrou; bpo-3001 [https://bugs.python.org/issue?@action=redirect&bpo=3001].)

The fast-search algorithm in stringlib is now used by the split(), rsplit(), splitlines() and replace() methods on bytes, bytearray and str objects. Likewise, the algorithm is also used by rfind(), rindex(), rsplit() and rpartition().

(Patch by Florent Xicluna in bpo-7622 [https://bugs.python.org/issue?@action=redirect&bpo=7622] and bpo-7462 [https://bugs.python.org/issue?@action=redirect&bpo=7462].)

Integer to string conversions now work two "digits" at a time, reducing the number of division and modulo operations.

(bpo-6713 [https://bugs.python.org/issue?@action=redirect&bpo=6713] by Gawain Bolton, Mark Dickinson, and Victor Stinner.)

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 [https://bugs.python.org/issue?@action=redirect&bpo=8685]). The array.repeat() method has a faster implementation (bpo-1569291 [https://bugs.python.org/issue?@action=redirect&bpo=1569291] by Alexander Belopolsky). The BaseHTTPRequestHandler has more efficient buffering (bpo-3709 [https://bugs.python.org/issue?@action=redirect&bpo=3709] by Andrew Schaaf). The operator.attrgetter() function has been sped-up (bpo-10160 [https://bugs.python.org/issue?@action=redirect&bpo=10160] by Christos Georgiou). And ConfigParser loads multi-line arguments a bit faster (bpo-7113 [https://bugs.python.org/issue?@action=redirect&bpo=7113] by Łukasz Langa).

Unicode 文字列型

Python has been updated to Unicode 6.0.0 [https://unicode.org/versions/Unicode6.0.0/]. The update to the standard adds over 2,000 new characters including emoji [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 [https://www.unicode.org/versions/Unicode6.0.0/#Database_Changes].

Codecs

cp720 アラビア DOS エンコードがサポートされました (bpo-1616979 [https://bugs.python.org/issue?@action=redirect&bpo=1616979])。

MBCS エンコーディングはもうエラーハンドラ引数を無視することはありません。デフォルトの strict モードでは、デコード出来ないバイト列に対して UnicodeDecodeError を、エンコードできない文字に対して UnicodeEncodeError を投げます。

MBCS コーデックはエラーハンドラとして、デコードでの 'strict' と 'ignore' 、エンコードでの 'strict' と 'replace' をサポートします。

Python 3.1 での MBCS エンコーディングを模擬したければデコードでは 'ignore' ハンドラを、エンコードでは 'replace' ハンドラを選んでください。

Mac OS X では Python は、コマンドライン引数をロケールのエンコーディングではなく 'utf-8' でデコードします。

tarfile はデフォルトで、Windows では ('mbcs' ではなく) 'utf-8' エンコーディングを使い、また、全ての OS でエラーハンドラ 'surrogateescape' を使います。

ドキュメント

ドキュメントの改善が引き続き行われています。

組み込み関数 のような長大なセクションには先頭にクイックリンクの表が追加されました。 itertools のようなケースでは cheatsheet [https://en.wikipedia.org/wiki/Cheat_sheet] スタイルの表からリンクが張られていて、これで要約がわかりますし、ドキュメント全体を読む必要なく記憶を呼び覚ますことが出来ます。

ある種のケースではピュア Python のソースコードが文書化の助手として便利に働いてくれますので、今では多くのモジュールがソースコードの最新バージョンへのクイックリンクを客演させています。例えば functools モジュールのドキュメントは先頭にこのようにクイックリンクを置いています:

ソースコード Lib/functools.py [https://github.com/python/cpython/tree/3.12/Lib/functools.py].

(Contributed by Raymond Hettinger; see rationale [https://rhettinger.wordpress.com/2011/01/28/open-your-source-more/].)

ドキュメントには今ではもっと実例とレシピが含まれています。特に re モジュールのものには大掛かりなセクション 正規表現の例 があります。同じように itertools では新しい Itertools レシピ で更新され続けます。

datetime モジュールは今ではピュア Python による補助実装を持っています。機能に違いはありません。これは読みやすい代替の実装を提供するだけのものです。

(Contributed by Alexander Belopolsky in bpo-9528 [https://bugs.python.org/issue?@action=redirect&bpo=9528].)

保守されていなかった Demo ディレクトリは削除されました。いくつかのデモはドキュメントに統合され、いくつかは Tools/demo ディレクトリに移動し、ほかのものは一緒に削除されました。

(Contributed by Georg Brandl in bpo-7962 [https://bugs.python.org/issue?@action=redirect&bpo=7962].)

IDLE

IDLE のフォーマットメニューに、ソースコードから末尾の空白を取り除くことが出来るオプションが追加されました。

(Contributed by Raymond Hettinger; bpo-5150 [https://bugs.python.org/issue?@action=redirect&bpo=5150].)

Mac OS X 上の IDLE が Carbon AquaTk と Cocoa AquaTk の両方で動くようになりました。

(Contributed by Kevin Walzer, Ned Deily, and Ronald Oussoren; bpo-6075 [https://bugs.python.org/issue?@action=redirect&bpo=6075].)

コードリポジトリ

In addition to the existing Subversion code repository at https://svn.python.org there is now a Mercurial [https://www.mercurial-scm.org/] repository at https://hg.python.org/.

3.2 のリリース後に、主要なリポジトリを Mercurial に移行する計画があります。この分散バージョン管理システムによってコミュニティメンバが容易に外部 changeset を作成したり共有したりすることが出来ます。詳細は PEP 385 [https://peps.python.org/pep-0385/] を参照してください。

To learn to use the new version control system, see the Quick Start [https://www.mercurial-scm.org/wiki/QuickStart] or the Guide to Mercurial Workflows [https://www.mercurial-scm.org/guide].

ビルドならびに C API の変更

Python のビルド過程と C API の変更は以下の通りです:

スクリプト idle, pydoc, 2to3 が make altinstall 時にバージョン固有のサフィックスを付けてインストールされるようになりました (bpo-10679 [https://bugs.python.org/issue?@action=redirect&bpo=10679])。

Unicode データベースにアクセスする関数 (Py_UNICODE_TOLOWER, Py_UNICODE_ISDECIMAL, ほか) が、たとえ narrow Unicode ビルドであっても full Unicode 範囲を受け付け、返すようになりました。Python から目に見える違いとしては、大きなコードポイントについて unicodedata.numeric() が正しい値を返し、 repr() はより多くの文字を表示可能と考えるようになりました。

(Reported by Bupjoe Lee and fixed by Amaury Forgeot D'Arc; bpo-5127 [https://bugs.python.org/issue?@action=redirect&bpo=5127].)

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 --without-computed-gotos.

(Contributed by Antoine Pitrou; bpo-9203 [https://bugs.python.org/issue?@action=redirect&bpo=9203].)

オプション --with-wctype-functions は削除されました。今では組み込みの Unicode データベースが全ての関数のために使われます。

(Contributed by Amaury Forgeot D'Arc; bpo-9210 [https://bugs.python.org/issue?@action=redirect&bpo=9210].)

ハッシュ値として新しい型 Py_hash_t を使うようになりました。これはポインタと同じサイズになるように定義されています。以前は long 型を使っていましたが、これはいくつかの 64 ビット OS でも 32 ビット長のままでした。この修正の結果、64 ビットポインタでビルドすれば set と dict が 2**32 以上のエントリを持てるようになりました (以前もそのサイズを入れることは出来ましたが、悲劇的なパフォーマンス低下を起こしていました)。

(Suggested by Raymond Hettinger and implemented by Benjamin Peterson; bpo-9778 [https://bugs.python.org/issue?@action=redirect&bpo=9778].)

A new macro 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 [https://bugs.python.org/issue?@action=redirect&bpo=2443]).

A new C API function PySys_SetArgvEx() allows an embedded interpreter to set sys.argv without also modifying sys.path (bpo-5753 [https://bugs.python.org/issue?@action=redirect&bpo=5753]).

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 [https://bugs.python.org/issue?@action=redirect&bpo=8276]).

PyLong_AsLongAndOverflow() の姉妹品の PyLong_AsLongLongAndOverflow() 関数が追加されました。両方とも Python int を C ネイティブの固定幅型に変換しますが、変換が幅に合わないことを検出します (bpo-7767 [https://bugs.python.org/issue?@action=redirect&bpo=7767])。

PyUnicode_CompareWithASCIIString() 関数が、Python 文字列が NUL 終端である場合に「 等しくない 」を返すようになりました。

新しい関数 PyErr_NewExceptionWithDoc() は PyErr_NewException() と似ていますが、ドキュメンテーション文字列を受け付けます。これは C 拡張に、対応するピュア Python と同じ自己文書化 (self-documenting) 能力を与えます (bpo-7033 [https://bugs.python.org/issue?@action=redirect&bpo=7033])。

--with-valgrind オプションとともにコンパイル時、 Valgrind のもとでの実行時に自動的に pymalloc アロケータが無効になるようになりました。ほかの状況では pymalloc は有利ですが、Valgrind 配下での実行時のメモリリーク検出では無効化したほうが良い結果が得られます (bpo-2422 [https://bugs.python.org/issue?@action=redirect&bpo=2422])。

PyArg_Parse 関数から書式文字列 O? が削除されました。これはもう使われていませんし、今まで一度も文書化されたことはありません (bpo-8837 [https://bugs.python.org/issue?@action=redirect&bpo=8837])。

There were a number of other small changes to the C-API. See the Misc/NEWS [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 [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 [https://web.archive.org/web/20101208191259/https://www.activestate.com/activetcl/downloads]. See https://www.python.org/download/mac/tcltk/ for additional details.

Python 3.2 への移植

このセクションでは前述の変更とバグフィックスにより必要となるかもしれないコードの変更を列挙します:

The configparser module has a number of clean-ups. The major change is to replace the old ConfigParser class with long-standing preferred alternative SafeConfigParser. In addition there are a number of smaller incompatibilities:

補間 (interpolation) の構文は今では get() と set() の操作で検証されます。デフォルトの補間スキームでは、パーセント記号を使ったただ二つのトークンのみが正当です: %(name)s と %% 、後者はエスケープされたパーセント記号自身。

set() メソッドと add_section() メソッドは今ではその値が実際に文字列かどうかを検証します。以前はサポートされない型が意図せず持ち込まれる可能性がありました。

単一ソースからのセクションまたはオプションの複製 (重複) に対し、今では DuplicateSectionError もしくは DuplicateOptionError を投げます。以前は重複は黙って以前のエントリを上書きしていました。

インラインコメントは今ではデフォルトで無効なので、 ; 文字を安全に値のなかで使えます。

コメントを字下げ出来るようになっています。このことにより、値が継続行となる場合の後続行の字下げ開始位置に ; または # を置くには、補間を使う必要があります。こうすればコメントのプレフィクス文字が値内に現れて誤ってコメントと解釈されるのを防げます。

"" は今では合法な値なので、もはや自動的に空文字列に変換されることはありません。空文字列のためには行内で "option =" と書いてください。

The nntplib module was reworked extensively, meaning that its APIs are often incompatible with the 3.1 APIs.

bytearray オブジェクトはもうファイル名には使えません。代わりに bytes に変換しなければいけません。

The array.tostring() and array.fromstring() have been renamed to array.tobytes() and array.frombytes() for clarity. The old names have been deprecated. (See bpo-8990 [https://bugs.python.org/issue?@action=redirect&bpo=8990].)

PyArg_Parse*() 系関数:

書式文字列 "t#" の削除: 代わりに "s#" もしくは "s*" を使ってください。

書式文字列 "w" および "w#" の削除: 代わりに "w*" を使ってください。

The PyCObject type, deprecated in 3.1, has been removed. To wrap opaque C pointers in Python objects, the 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.

The sys.setfilesystemencoding() function was removed because it had a flawed design.

random.seed() 関数とメソッドが、salt に文字列やバイト列を与えた場合に内部で sha512 ハッシュ関数を使うようになりました。Python 3.1 シーケンスを再現するのに以前のバージョンの seed が必要であれば、 version 引数を 1 にしてください。 random.seed(s, version=1) のように。

The previously deprecated string.maketrans() function has been removed in favor of the static methods bytes.maketrans() and bytearray.maketrans(). This change solves the confusion around which types were supported by the string module. Now, str, bytes, and bytearray each have their own maketrans and translate methods with intermediate translation tables of the appropriate type.

(Contributed by Georg Brandl; bpo-5675 [https://bugs.python.org/issue?@action=redirect&bpo=5675].)

The previously deprecated contextlib.nested() function has been removed in favor of a plain 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:

with open('mylog.txt') as infile, open('a.out', 'w') as outfile:
    for line in infile:
        if '<critical>' in line:
            outfile.write(line)

(Georg Brandl と Mattias Brändström の貢献; appspot issue 53094 [https://codereview.appspot.com/53094].)

struct.pack() は、文字列パックコード s で bytes のみを許容するようになりました。以前はテキスト引数を受け取って暗黙に UTF-8 でエンコードして bytes に変換していました。特定のエンコーディングを前提にするのは間違っていますし、可変長のエンコーディングは構造体の固定長セグメントへの書き込みで失敗しうるので、これは問題でした。

例えば struct.pack('<6sHHBBB', 'GIF87a', x, y) としているならば、テキストではなく bytes を使うように struct.pack('<6sHHBBB', b'GIF87a', x, y) と書き換えなければなりません。

(Discovered by David Beazley and fixed by Victor Stinner; bpo-10783 [https://bugs.python.org/issue?@action=redirect&bpo=10783].)

パース失敗時に xml.etree.ElementTree クラスが xml.etree.ElementTree.ParseError を投げるようになりました。以前は xml.parsers.expat.ExpatError を投げていました。

浮動小数点数と複素数に対する str() が以前より長い表現をするようになったことで、古いフォーマットに依存する doctest は壊れるかもしれません。

subprocess.Popen の close_fds のデフォルトが、Unix では True になりました。Windows では 3 つの標準ストリームに None がセットされている場合には True 、以外の場合は False になりました。以前は close_fds のデフォルトはいつでも False でした。これは開いているファイル記述子が子プロセスに漏れた場合に解決が難しいバグや競合状態を生み出していました。

レガシーな HTTP 0.9 のサポートが urllib.request と http.client から削除されました。このサポートはサーバサイドではまだ健在です (http.server 内)。

(Contributed by Antoine Pitrou, bpo-10711 [https://bugs.python.org/issue?@action=redirect&bpo=10711].)

タイムアウトモード時の SSL ソケットでタイムアウトした場合に、汎用の SSLError ではなく socket.timeout を投げるようになりました。

(Contributed by Antoine Pitrou, bpo-10272 [https://bugs.python.org/issue?@action=redirect&bpo=10272].)

The misleading functions PyEval_AcquireLock() and PyEval_ReleaseLock() have been officially deprecated. The thread-state aware APIs (such as PyEval_SaveThread() and PyEval_RestoreThread()) should be used instead.

Due to security risks, asyncore.handle_accept() has been deprecated, and a new function, asyncore.handle_accepted(), was added to replace it.

(Contributed by Giampaolo Rodola in bpo-6706 [https://bugs.python.org/issue?@action=redirect&bpo=6706].)

Due to the new GIL implementation, PyEval_InitThreads() cannot be called before Py_Initialize() anymore.

What's New In Python 3.1

著者:

Raymond Hettinger

この記事では 3.0 と比較した Python 3.1 の新機能を解説します。Python 3.1 は2009年6月27日にリリースされました。

PEP 372: 順序付き辞書

通常の Python 辞書は、 key/value ペアを不定の順序でイテレートします。何年にもわたり、いろいろな人が key の挿入順を保存する辞書の別実装を書いてきました。その経験に基づき、新しい OrderedDict クラスが導入されました。

OrderedDict API は通常の辞書と同じインターフェースを提供していますが、 key/value をイテレートするときに key が最初に挿入された順番になることが保証されています。新しいエントリが既存のエントリを上書きした場合は、元の挿入順序が保持されます。エントリを削除して再挿入すると、順序は一番最後に移動します。

標準ライブラリのいくつかのモジュールで、順序付き辞書の利用がサポートされています。configparser モジュールはデフォルトで順序付き辞書を使います。設定ファイルを読み込み、編集した後、元の順序で書きなおすことができます。collections.namedtuple() の _asdict() メソッドは、タプルの順序と同じ順序の順序付き辞書を返すようになりました。json モジュールのデコーダーが OrderedDict をビルドするのをサポートするために、 JSONDecoder クラスのコンストラクタに object_pairs_hook 引数が追加されました。 PyYAML [https://pyyaml.org/] などの外部のライブラリでもサポートされています。

参考

PEP 372 [https://peps.python.org/pep-0372/] - 順序付き辞書

PEP written by Armin Ronacher and Raymond Hettinger. Implementation written by Raymond Hettinger.

順序付き辞書は挿入順序を記憶するので、ソートと組み合わせて使うことで、ソートされた辞書を作れます:

>>> # 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)])

この新しい順序付き辞書は、項目が削除されてもソートされた順序を保持します。しかし、キーが追加されるとき、そのキーは最後に追加され、ソートは保持されません。

PEP 378: 1000区切りのための書式指定子

組み込みの format() 関数と str.format() メソッドが使うミニ言語に、単純でロケールに依存しない 1000 区切りカンマの書式化が追加されました。これによって簡単にプログラムの出力を、その玄人ちっくな見た目を改善してひとさまにとって読みやすいものに出来ます:

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

これをサポートする型は int, float, complex , decimal.Decimal です。

ドットやら空白やらアポストロフィやらあるいはアンダースコアなどの他のセパレータをどうやって指定するかの議論は水面下にありますが、ロケールに従う必要があるアプリケーションは、1000区切りセパレータについていくつかのサポートを既に持っている既存の n 指定子を使うべきです。

参考

PEP 378 [https://peps.python.org/pep-0378/] - 1000区切りのための書式指定子

PEP written by Raymond Hettinger and implemented by Eric Smith and Mark Dickinson.

その他の言語変更

Python 言語コアに小さな変更がいくつか行われました:

__main__.py を含むディレクトと zip アーカイブを、その名前をインタプリタに渡すことで直接実行出来るようになりました。そのディレクトリと zip ファイルは自動的に sys.path エントリの先頭に挿入されます。(Suggestion and initial patch by Andy Chu; revised patch by Phillip J. Eby and Nick Coghlan; bpo-1739468 [https://bugs.python.org/issue?@action=redirect&bpo=1739468].)

int() 型に bit_length メソッドが追加されました。このメソッドはその値を二進数で表現するのに必要なビット数を返します:

>>> n = 37
>>> bin(37)
'0b100101'
>>> n.bit_length()
6
>>> n = 2**123-1
>>> n.bit_length()
123
>>> (n+1).bit_length()
124

(Contributed by Fredrik Johansson, Victor Stinner, Raymond Hettinger, and Mark Dickinson; bpo-3439 [https://bugs.python.org/issue?@action=redirect&bpo=3439].)

format() 文字列のフィールドに自動的に番号が振られるようになりました:

>>> 'Sir {} of {}'.format('Gallahad', 'Camelot')
'Sir Gallahad of Camelot'

以前は、文字列は 'Sir {0} of {1}' のようにフィールドに番号を振らなければなりませんでした。

(Contributed by Eric Smith; bpo-5237 [https://bugs.python.org/issue?@action=redirect&bpo=5237].)

The string.maketrans() function is deprecated and is replaced by new static methods, bytes.maketrans() and bytearray.maketrans(). This change solves the confusion around which types were supported by the string module. Now, str, bytes, and bytearray each have their own maketrans and translate methods with intermediate translation tables of the appropriate type.

(Contributed by Georg Brandl; bpo-5675 [https://bugs.python.org/issue?@action=redirect&bpo=5675].)

with 文のシンタックスは一つの文で複数のコンテキストマネージャを使えるようになりました:

>>> with open('mylog.txt') as infile, open('a.out', 'w') as outfile:
...     for line in infile:
...         if '<critical>' in line:
...             outfile.write(line)

With the new syntax, the contextlib.nested() function is no longer needed and is now deprecated.

(Georg Brandl と Mattias Brändström の貢献; appspot issue 53094 [https://codereview.appspot.com/53094].)

round(x, n) は x が整数の場合、整数を返すようになりました。以前は浮動小数点を返していました:

>>> round(1123, -2)
1100

(Contributed by Mark Dickinson; bpo-4707 [https://bugs.python.org/issue?@action=redirect&bpo=4707].)

Python は浮動小数点数について、その値を変更しない最も短い表現を見つけるのに David Gay のアルゴリズムを使うようになりました。これは二進浮動小数点数にまつわるいくつかの困惑を軽減する助けとなるはずです。

有意な違いは 1.1 のような値ですぐに見て取れます。これは二進浮動小数点数で正確に表現出来ない数です。完全に同じとなるものはありませんから、例えば式 float('1.1') は表現可能な最近接である十六進での 0x1.199999999999ap+0 、十進での 1.100000000000000088817841970012523233890533447265625 として評価されます。その最近接値は昔も今も、後続の浮動小数点数計算で使われます。

何が新しくなったかと言えば、それはその数がどのように表示されるか、です。以前は Python は単純なアプローチを使っていました。値 repr(1.1) は format(1.1, '.17g') として計算され、 '1.1000000000000001' として評価されていました。17 桁を使うことが好都合だったのは、IEEE-754 のもとでは eval(repr(1.1)) がその元の値に正確に戻ることに依存出来たことでした。ですが不都合として、多くの人々がその出力を (二進浮動小数点数表現に本来備わっている制限を Python そのものの問題であると誤解して) 混乱していると理解していました。

新しいアルゴリズムでは repr(1.1) はより賢明で '1.1' を返します。実際的には、これは全ての等価な文字列表現 (前提となる同じ浮動小数点数に戻るもの) を探し、そして一番短い表現を返します。

新アルゴリズムは、可能な限りよりわかりやすい表現を生み出す傾向がありますが、元の値を変更しません。ですから 1.1 + 2.2 != 3.3 は表示がどうであれ、今でも問題です。

新アルゴリズムは根底にある浮動小数点数実装の、ある機能に依存しています。その必要としている機能がないならば、古いアルゴリズムが引き続き使われます。なお、テキストの pickle プロトコルは、このアルゴリズム変更によりクロスプラットフォーム互換が保たれません。

(Contributed by Eric Smith and Mark Dickinson; bpo-1580 [https://bugs.python.org/issue?@action=redirect&bpo=1580])

新たなモジュール、改良されたモジュール、非推奨のモジュール

シーケンスまたはイテラブル内にある一意な要素を数え上げるのに便利な collections.Counter クラスが追加されました:

>>> Counter(['red', 'blue', 'red', 'green', 'blue', 'blue'])
Counter({'blue': 3, 'red': 2, 'green': 1})

(Contributed by Raymond Hettinger; bpo-1696199 [https://bugs.python.org/issue?@action=redirect&bpo=1696199].)

Tk のテーマ付きウィジェットへのアクセスを提供する、新しい tkinter.ttk モジュールが追加されました。 tkinter.ttk の基本的なアイディアは、拡張可能性のためにウィジェットの動作を実装するコードと見た目を記述するコードを分離することです。

(Contributed by Guilherme Polo; bpo-2983 [https://bugs.python.org/issue?@action=redirect&bpo=2983].)

gzip.GzipFile と bz2.BZ2File クラスはコンテキストマネジメントプロトコルをサポートするようになりました:

>>> # Automatically close file after writing
>>> with gzip.GzipFile(filename, "wb") as f:
...     f.write(b"xxx")

(Contributed by Antoine Pitrou.)

decimal モジュールが二進 float から decimal オブジェクトを生成するメソッドをサポートしました。変換は正確ですが時に意外なことがあります:

>>> Decimal.from_float(1.1)
Decimal('1.100000000000000088817841970012523233890533447265625')

長い十進の結果が、 1.1 を記憶するための現実の二進での端数を表しています。 1.1 は二進数で正確に表現出来ないので、端数は十進表現でとても多くの桁数になっています。

(Contributed by Raymond Hettinger and Mark Dickinson.)

itertools に 2 つの関数が追加されました。 itertools.combinations_with_replacement() 関数は、置換 (順列, permutation) や直積 (Cartesian product) を含む組合せ論の 4 つの生成関数のうちの 1 つです。 itertools.compress() 関数は APL [https://ja.wikipedia.org/wiki/APL] の同名機能の模倣品です。また、既存の itertools.count() 関数は新たにオプショナルな step 引数を取るようになり、そして数え方に fractions.Fraction や decimal.Decimal を含む任意の数値型を使えるようになりました。

>>> [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)]

(Contributed by Raymond Hettinger.)

collections.namedtuple() が新たにキーワード引数 rename をサポートし、これにより不正なフィールド名を自動で _0, _1, ... といった位置による名前に変換することが出来ます。これはフィールド名が何か外部ソースに基いて作られる場合に有用です。例えば CSV のヘッダ、SQL のフィールドリスト、あるいはユーザ入力などです:

>>> 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)]

(Contributed by Raymond Hettinger; bpo-1818 [https://bugs.python.org/issue?@action=redirect&bpo=1818].)

re.sub()、re.subn() および re.split() 関数は flags 引数を受け取るようになりました。

(Contributed by Gregory Smith.)

logging を自身では使わずとも使用ライブラリがそうしているようなアプリケーションのために、 logging モジュールが単純な logging.NullHandler を実装しました。null ハンドラをセットアップすることは、 "No handlers could be found for logger foo" のような警告を抑制します。

>>> h = logging.NullHandler()
>>> logging.getLogger("foo").addHandler(h)

(Contributed by Vinay Sajip; bpo-4384 [https://bugs.python.org/issue?@action=redirect&bpo=4384]).

コマンドラインスイッチ -m をサポートしている runpy がパッケージの実行をサポートするようになりました。パッケージ名が与えられると __main__ サブモジュールを探し出して実行します。

(Contributed by Andi Vajda; bpo-4195 [https://bugs.python.org/issue?@action=redirect&bpo=4195].)

pdb モジュールが zipimport (あるいはなにかほかの PEP 302 [https://peps.python.org/pep-0302/] 準拠ローダ) でロードされたモジュールのソースコードにアクセスでき、表示できるようになりました。

(Contributed by Alexander Belopolsky; bpo-4201 [https://bugs.python.org/issue?@action=redirect&bpo=4201].)

functools.partial オブジェクトが pickle 化出来るようになりました。

(Suggested by Antoine Pitrou and Jesse Noller. Implemented by Jack Diederich; bpo-5228 [https://bugs.python.org/issue?@action=redirect&bpo=5228].)

シンボルのための pydoc ヘルプトピックが追加されました。これで対話環境で help('@') などが期待通りの働きをします (---訳注: 実装としては pydoc_data パッケージのこと。 pydoc_data/topics.py に docstring からは生成出来ない、シンボルについてのドキュメントが収められています ---)。

(Contributed by David Laban; bpo-4739 [https://bugs.python.org/issue?@action=redirect&bpo=4739].)

unittest に特定のテストメソッドやテストクラス全体をスキップする仕組みのサポートが追加されました。さらに、この機能はテスト結果を「意図的な失敗」とすることができ、テストが失敗しても TestResult の失敗数にはカウントされなくなります:

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

また例外についてのテストが、 with 文で使えるコンテキストマネージャとして増強されました:

def test_division_by_zero(self):
    with self.assertRaises(ZeroDivisionError):
        x / 0

In addition, several new assertion methods were added including assertSetEqual(), assertDictEqual(), assertDictContainsSubset(), assertListEqual(), assertTupleEqual(), assertSequenceEqual(), assertRaisesRegexp(), assertIsNone(), and assertIsNotNone().

(Contributed by Benjamin Peterson and Antoine Pitrou.)

The io module has three new constants for the seek() method: SEEK_SET, SEEK_CUR, and SEEK_END.

sys.version_info タプルが名前付きタプルになりました。

>>> sys.version_info
sys.version_info(major=3, minor=1, micro=0, releaselevel='alpha', serial=2)

(Contributed by Ross Light; bpo-4285 [https://bugs.python.org/issue?@action=redirect&bpo=4285].)

The nntplib and imaplib modules now support IPv6.

(Contributed by Derek Morr; bpo-1655 [https://bugs.python.org/issue?@action=redirect&bpo=1655] and bpo-1664 [https://bugs.python.org/issue?@action=redirect&bpo=1664].)

pickle を、プロトコル 2 以下を使う際に Python 2.x との相互運用に順応するようにしました。標準ライブラリの再編成はたくさんのオブジェクトへの公式な参照を変えました。例えば Python 2 の __builtin__.set は Python 3 では builtins.set です。この変化は異なる Python バージョン間でのデータ共有の取り組みを複雑にしました。ですが今回のこの修正により、プロトコル 2 以下を選んだ場合は pickler は自動的にロード時もダンプ時も古い Python 2 命名を使うようになります。この再マッピングはデフォルトで有効になりますが、 fix_imports オプションで無効に出来ます:

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

不幸にも、そして避けられないこの変更による副作用は、Python 3.1 によって生成されたプロトコル 2 pickle が Python 3.0 で読めなくなるであろうことです。Python 2.x との互換性を維持するつもりがないのであれば、Python 3.x 実装間でのデータ移行では最新 pickle プロトコルバージョン 3 を使うべきです。

(Contributed by Alexandre Vassalotti and Antoine Pitrou, bpo-6137 [https://bugs.python.org/issue?@action=redirect&bpo=6137].)

新規モジュール importlib が追加されました。 import 文とその相棒の __import__() 関数の、完全で移植性が高いピュア Python 参照実装を提供しています。これはインポートで行う動作の文書化と定義における、確かな前進です。

(Contributed by Brett Cannon.)

最適化

大きな性能向上がありました:

The new I/O library (as defined in PEP 3116 [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 _pyio module.

(Contributed by Amaury Forgeot d'Arc and Antoine Pitrou.)

Added a heuristic so that tuples and dicts containing only untrackable objects are not tracked by the garbage collector. This can reduce the size of collections and therefore the garbage collection overhead on long-running programs, depending on their particular use of datatypes.

(Contributed by Antoine Pitrou, bpo-4688 [https://bugs.python.org/issue?@action=redirect&bpo=4688].)

Enabling a configure option named --with-computed-gotos on compilers that support it (notably: gcc, SunPro, icc), the bytecode evaluation loop is compiled with a new dispatch mechanism which gives speedups of up to 20%, depending on the system, the compiler, and the benchmark.

(Contributed by Antoine Pitrou along with a number of other participants, bpo-4753 [https://bugs.python.org/issue?@action=redirect&bpo=4753]).

UTF-8, UTF-16 ならびに LATIN-1 のデコーディングが2から4倍速くなりました。

(Antoine Pitrou と Amaury Forgeot d'Arc の貢献, bpo-4868 [https://bugs.python.org/issue?@action=redirect&bpo=4868].)

The json module now has a C extension to substantially improve its performance. In addition, the API was modified so that json works only with str, not with bytes. That change makes the module closely match the JSON specification [https://json.org/] which is defined in terms of Unicode.

(Contributed by Bob Ippolito and converted to Py3.1 by Antoine Pitrou and Benjamin Peterson; bpo-4136 [https://bugs.python.org/issue?@action=redirect&bpo=4136].)

Unpickling now interns the attribute names of pickled objects. This saves memory and allows pickles to be smaller.

(Contributed by Jake McGuire and Antoine Pitrou; bpo-5084 [https://bugs.python.org/issue?@action=redirect&bpo=5084].)

IDLE

IDLE のフォーマットメニューに、ソースコードから末尾の空白を取り除くことが出来るオプションが追加されました。

(Contributed by Roger D. Serwy; bpo-5150 [https://bugs.python.org/issue?@action=redirect&bpo=5150].)

ビルドならびに C API の変更

Python のビルド過程と C API の変更は以下の通りです:

整数の内部格納方式が 2**15 ベースと 2**30 ベースのいずれかになりました。これはビルド時に決定されます。以前は常に 2**15 ベースで格納されていました。 2**30 ベースにすると 64 bit マシンでは性能が有意に向上しますが、 32 bit マシンでのベンチマーク結果には向上も低下もあります。そのため、デフォルトでは 64 bit マシンで 2**30 ベースを、 32 bit マシンで 2**15 ベースを使用します。 Unix では新たな configure オプション --enable-big-digits が追加されました。これにより上記のデフォルトを上書き出来ます。

この変更は性能向上以外ではエンドユーザには分からないはずですが、例外が1つあります。テストおよびデバッグ目的で内部形式の情報を提供する sys.int_info が追加されましたが、これにより数字あたりのビット数と各数字の格納に使われる C の型のバイトサイズが分かります:

>>> import sys
>>> sys.int_info
sys.int_info(bits_per_digit=30, sizeof_digit=4)

(Contributed by Mark Dickinson; bpo-4258 [https://bugs.python.org/issue?@action=redirect&bpo=4258].)

PyLong_AsUnsignedLongLong() 関数は負の pylong に対し TypeError ではなく OverflowError を送出するようになりました。

(Contributed by Mark Dickinson and Lisandro Dalcrin; bpo-5175 [https://bugs.python.org/issue?@action=redirect&bpo=5175].)

PyNumber_Int() が非推奨になりました。代わりに PyNumber_Long() を使用してください。

(Contributed by Mark Dickinson; bpo-4910 [https://bugs.python.org/issue?@action=redirect&bpo=4910].)

非推奨の関数 PyOS_ascii_strtod() および PyOS_ascii_atof() を置き換えるために新しく PyOS_string_to_double() 関数が追加されました。

(Contributed by Mark Dickinson; bpo-5914 [https://bugs.python.org/issue?@action=redirect&bpo=5914].)

PyCObject API を置き換えるものとして、 PyCapsule が追加されました。主な違いとしては、新しい型は、型安全に情報を渡すための良く定義されたインターフェースを持ち、また、デストラクタの呼び出しのシグネチャの複雑さが小さくなっています。古い型は問題のある API で、今では非推奨です。

(Contributed by Larry Hastings; bpo-5630 [https://bugs.python.org/issue?@action=redirect&bpo=5630].)

Python 3.1 への移植

このセクションでは前述の変更とバグフィックスにより必要となるかもしれないコードの変更を列挙します:

新しい浮動小数点の文字列表現は既存の doctest に違反する惧れがあります。例えば、

def e():
    '''Compute the base of natural logarithms.

    >>> e()
    2.7182818284590451

    '''
    return sum(1/math.factorial(x) for x in reversed(range(30)))

doctest.testmod()

**********************************************************************
Failed example:
    e()
Expected:
    2.7182818284590451
Got:
    2.718281828459045
**********************************************************************

pickle モジュールがプロトコルバージョン 2 以下で自動的に名前の再対応付けを行うので、Python 3.1 で pickle 化すると Python 3.0 で読めなくなります。一つの解決策はプロトコル 3 を使うことです。もう一つは fix_imports オプションを False にセットすることです。上述の議論を参照してください。

What's New In Python 3.0

著者:

Guido van Rossum

この記事では 2.6 と比較した Python 3.0 での新機能を解説します。 Python 3.0、あるいは "Python 3000"、 "Py3K" は初めて 意図的に後方非互換にした Python のリリースです。 Python 3.0 は2008年12月3日にリリースされました。通常のリリースよりも多くの変更があり、全ての Python ユーザにとって重要です。しかし、変更について理解したら Python に実際にはそれほど変更がないことが分かるでしょう。全体的に見れば、よく知られた悩みの種が概ね解決され、昔の粗雑なものが取り除かれています。

この記事は全ての新機能を完璧な仕様を示そうとはしませんが、便利な概要については説明しようとしています。全詳細については Python 3.0 のドキュメントや、本編で引かれている多くの PEP を参照してください。特定の機能の実装や設計原理について完全に理解したいなら、通常のドキュメントよりも詳しいことが書いてある PEP を見るとよいでしょう。しかし、一旦機能が完全に実装されると、普通 PEP は最新の状態に保たれないことに注意してください。

この文書で全項目に触れるべきなのですが、時間の制約のためそうではありません。いつもの新リリースのように、 ソース配布の Misc/NEWS には些細な変更についても詳細な情報があります。

よくある悩みの種

このセクションは Python 2.5 に慣れていたら躓いてしまいそうな少数の変更の一覧です。

print関数

print 文は print() 関数に置き換えられ、古い print 文の特殊な文法の殆どがキーワード引数で置き換えられています (PEP 3105 [https://peps.python.org/pep-3105/])。 例:

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)!

項目間の区切りをカスタマイズすることもできます。例:

print("There are <", 2**32, "> possibilities!", sep="")

これは以下を出力します :

There are <4294967296> possibilities!

注釈:

print() 関数は、古い print 文の "ソフトスペース" 機能をサポートしません。例えば Python 2.x では、 print "A\n", "B" は "A\nB\n" を出力していましたが、 Python 3.0 では、 print("A\n", "B") は "A\n B\n" を出力します。

最初は、対話モードで古い print x を何回もタイプしてしまうでしょう。代わりに print(x) とタイプするよう再教育してください。

2to3 ソース変換ツールを使うと、すべての print 文が print() 関数呼び出しに自動的に置換されるので、大きなプロジェクトでもさほど問題にならないでしょう。

リストからビューおよびイテレータへ

いくつかの良く使われている API はもはやリストを返しません:

dict の dict.keys(), dict.items() そして dict.values() メソッドはリストの代わりに "views" を返します。 例えば: k = d.keys(); k.sort() は上手く動きません。 代わりに k = sorted(d) を使ってください (これは Python 2.5 でも動作し、効率的です)。

dict.iterkeys()、 dict.iteritems()、 dict.itervalues() メソッドはもうサポートされません。

map() と filter() はイテレータを返します。もしも本物のリストが必要で、全ての入力シーケンスが同じ長さの場合であれば、簡単に直すなら map() を list() で包みます。例えば list(map(...)) という具合。ですがより良いのは、大抵はリスト内包を使うことです (特に元々のコードが lambda を使っている場合)。あるいはコードを、リストを全く必要としないように書き換えましょう。とりわけトリッキーなのは、関数に副作用を起こさせるために呼び出される map() です; この場合確実な変換は普通に for ループを使うことです (そもそもリストを作ること自体が無駄遣いでしょう)。

入力シーケンスの長さが同じとは限らないならば、 map() は最も短いシーケンスが消費されつくすと処理をやめます。Python 2.x での map() 用法と全く互換にするにはシーケンスを itertools.zip_longest() で包んでください。例えば map(func, *sequences) を list(map(func, itertools.zip_longest(*sequences))) とします。

range() は xrange() のように振る舞います。ただし、任意のサイズの値で動作します。 xrange() は削除されました。

zip() はイテレータを返します。

順序比較

Python 3.0 で順序比較のルールが簡単になりました。

順序比較演算子 (<, <=, >=, >) は、そのオペランドが自然な順序づけを持たない場合 TypeError 例外を送出します。 1 < '', 0 > None または len <= len のような式は無効になり、 None < None は False を返す代わりに TypeError を送出します。その結果、 不均一なリスト（訳注：比較不能な型からなる要素が混在するリスト）のソートは意味がなくなりました。 -- 全ての要素は互いに比較できなければなりません。これは == と != 演算子には適用されないことに注意してください: 別々の比較不可能な型のオブジェクトを比較すると常に、互いに等しくないと評価されます。

builtin.sorted() と list.sort() メソッドは比較関数を与える cmp 引数を受け取らなくなりました。 かわりに key 引数を使用してください。 key と reverse 引数は "キーワード専用" となったことに注意してください。

cmp() 関数は廃止され、 __cmp__() 特殊関数はもはやサポートされません。ソートには __lt__() を使用し、 __hash__() には __eq__() を 、必要に応じて他の高級比較 (rich comparison) を使用してください。 (もし cmp() の機能が必要なら、 式 (a > b) - (a < b) を cmp(a, b) の代わに使用できるはずです)

整数

PEP 237 [https://peps.python.org/pep-0237/]: 基本的には、 long は int に改名されました。これは、整数型の唯一の組み込み型になり、 int と名付けられていますが、古い long 型とほぼ同じように振る舞います。

PEP 238 [https://peps.python.org/pep-0238/]: An expression like 1/2 returns a float. Use 1//2 to get the truncating behavior. (The latter syntax has existed for years, at least since Python 2.2.)

整数の上限がなくなったため、sys.maxint 定数は削除されました。しかしながら、通常のリストや文字列の添え字よりも大きい整数として sys.maxsize を使うことができます。 sys.maxsize は実装の "自然な" 整数の大きさに一致し、同じプラットフォームでは (同じビルドオプションなら) 過去のリリースの sys.maxint と普通は同じです。

long 整数の repr() はもはや末尾に L を持ちません。そのため、無条件に "L" を取り除くコードは代わりに最後の数字を取り除いてしまうでしょう。 (代わりに str() を使用してください。)

8進数リテラルが 0720 の形でなくなりました。代わりに 0o720 を使ってください。

Unicode 対 8 ビット、ではなく、テキスト対データに

バイナリと Unicode について知っていると思っている全てが変わりました。

Python 3.0 でのコンセプトは、Unicode 文字列と 8 ビット文字列、という対比ではなくて、 テキスト と (バイナリ) データ の違いと考える、というものです。全てのテキストは Unicode です; 一方で エンコードされた Unicode はバイナリデータとして表現されます。テキストを保持するのに使われる型は str で、データには bytes を使います。2.x での状況との最大の違いは、Python 3.0 でテキストとデータを混ぜようとすれば TypeError となることです。Python 2.x では Unicode と 8 ビット文字列を混ぜたとすれば、8 ビット文字列がたまたま 7 ビット (ASCII) バイトだけから出来ていれば動くし非 ASCII バイトがあれば UnicodeDecodeError となっていたでしょう。この、データ値に依存した振る舞いが、何年にも渡って夥しい数の悲劇を生み出していました。

この変更からの帰結として、Unicode、エンコーディング、あるいはバイナリデータを使うほとんど全てのコードは、原則として修正する必要があると思います。この変更は進歩のための破壊です。というのも 2.x 世界には、エンコードされたテキストとそうでないものをごっちゃにしている膨大な数のバグがあるはずだからです。Python 2.x のうちから準備しておくには、まずは全てのエンコードしていないテキストに unicode を使い、 str はバイナリとエンコードされたデータだけに対して使うことから始めてください。そうしておけば 2to3 ツールがあなたのためにほとんどの仕事をしてくれるでしょう。

Unicode テキストのリテラルに u"..." を使うことはもはやできません。しかし、バイナリーデータのリテラルには b"..." を使わなければなりません。(---訳注: この u"..." は Python 3.3 で再び使えるようになりました。 ---)

str 型と bytes 型を混ぜて使うことは出来ませんから、それらはいつでも明示的に変換しなければいけません。 str から bytes にするには str.encode() を使ってください。そして bytes から str にするには bytes.decode() を使います。それぞれ bytes(s, encoding=...) 、 str(b, encoding=...) を使うことも出来ます。

str がそうであるように、 bytes は immutable です。これとは独立させて mutable 型として、バッファ化されたバイナリデータを保持するための bytearray が用意してあります。 bytes を受け付ける API のほぼ全てが bytearray も許容します。その mutable API は collections.MutableSequence に基づいています。

raw 文字列リテラル内にある全てのバックスラッシュが「字句通り」に解釈されます。つまり '\U' も '\u' も、 raw 文字列内にあっては何ら特別に扱われないということです。例えば r'\u20ac' は Python 3.0 では 6 文字の文字列です。Python 2.x では ur'\u20ac' が単一の「ユーロ」文字であったのにです。(無論この変更は raw 文字列リテラルについてだけのもので、ユーロ文字は Python 3.0 で '\u20ac' です。)

組み込みであった basestring 抽象型なんてものは削除されたのです。 str をお使いなさい。 str と bytes は基底クラスを共有するのを正当化するのに足るほどには、機能的に共通していないのです。 2to3 ツール (後述) は basestring を片っ端から str に置き換えてくれます。

テキストファイルとして開かれたファイル (これは従来どおり open() でのデフォルトのモード) は、 (メモリ内の) 文字列と (ディスクでの) バイト列との写像をするのに、常にエンコーディングを使います。バイナリファイル (モードに b を付けて開いたもの) はメモリ内では常にバイト列を使います。このことで、もしもファイルが誤ったモードやエンコーディングで開かれようとすると、I/O はきっと口やかましく失敗します。こっそり正しくないデータを生み出すのではなく。それに加えて、ファイルを開く際には Unix ユーザでさえもこれからは、 (テキストかバイナリかの) 正しいモードを選択する必要があるということです。プラットフォームにはそれ特有のデフォルトエンコーディングがあります。Unix 的プラットフォームではこれは環境変数 LANG にセットされているかもしれません (あるいは時々ほかのプラットフォーム特有の、ロケールに関係した環境変数にもセットされています)。全てとは言いませんが多くの場合は、システムのデフォルトは UTF-8 です; ですが決してこのデフォルトを当てにすべきではありません。純粋な ASCII テキスト以上のものを読み書きするどんなアプリケーションも、きっとエンコーディングをオーバライド出来る手段を持つべきです。 codecs 内にあるエンコーディングを熟知したストリームを使うことは、今ではもう必要なくなりました。

sys.stdin, sys.stdout, sys.stderr の初期値はいまでは Unicode のみのテキストファイルです (つまりそれらは io.TextIOBase のインスタンスです)。バイト列データをそれらのストリームで読み書きするには、 io.TextIOBase.buffer 属性を使う必要があります。

ファイル名は、API へは (Unicode) 文字列を渡し、 (Unicode) 文字列が返ります。これにはプラットフォーム特有の問題があるかもしれません。というのも、いくつかのプラットフォームではファイル名は任意のバイト文字列だからです。(他方では、Windows ではファイル名はネイティブに Unicode で格納されています。) 次善策として、ほとんどの API (たとえば open() と os モジュール内の多くの関数) はファイル名として、文字列だけでなく bytes を受け付け、そして少しの API は bytes を返すかどうかを要求出来る手段を持っています。それゆえに os.listdir() は引数が bytes インスタンスであれば bytes のリストで返し、 os.getcwdb() はカレントディレクトリを bytes で返します。 os.listdir() が文字列のリストで返す際、適切にデコード出来ないファイル名は UnicodeError とはせずに無視されることにご注意ください。

os.environ や sys.argv のようないくつかのシステム API にも問題がありえます。システムにより利用可能とされるべきバイト列がデフォルトエンコーディングで解釈不能な場合です。環境変数 LANG をセットしてプログラムを再実行することが、おそらく最善のアプローチです。

PEP 3138 [https://peps.python.org/pep-3138/]: 文字列への repr() はもう非 ASCII 文字をエスケープしません。ただし、制御文字、Unicode 標準で印字不可状態のコードポイントは今でもエスケープされます。

PEP 3120 [https://peps.python.org/pep-3120/]: ソースのエンコードのデフォルトが UTF-8 になりました。

PEP 3131 [https://peps.python.org/pep-3131/]: 非 ASCII 文字を識別子として使用することが出来るようになりました。 (そうはいっても標準ライブラリは、コメント内での貢献者の名前以外では ASCII だけのままです。)

StringIO および cStringIO モジュールは廃止されました。その代わり io モジュールをインポートして、テキストやデータには io.StringIO や io.BytesIO を使用してください。

Unicode HOWTO を参照してください。Python 3.0 向けに更新されました。

構文の変更の概要

このセクションは Python 3.0 における全ての 構文の 変更についての簡単な概要です。

新たな構文

PEP 3107 [https://peps.python.org/pep-3107/]: 関数引数と戻り値のアノテーション。これは関数のパラメータと戻り値へのアノテーションを付ける標準的な手段を提供します (訳注: annotation を強いて訳せば「注釈」)。そのようなアノテーションには、実行時に __annotations__ 属性を調べること以外には何の意味付けもされていません。メタクラスやデコレータ、フレームワークを通じた実験を促進することが意図されています。

PEP 3102 [https://peps.python.org/pep-3102/]: キーワード専用引数。パラメータリスト中で *args のあとに現れる名前付きパラメータは、呼び出す際には 必ず キーワード引数の構文を使う必要があります (---訳注: def fun(*a, kw): という定義で fun(1, 2, 3) は NG で fun(1, 2, kw=3) としなければならない。ここまでは 2.x と同じ ---)。この PEP により、可変引数リストを受け取らずにキーワード専用引数だけを許したい場合にそれを主張するために剥き出しの * をパラメータリスト内に書けるようになりました (---訳注: def fun(*, kw): と定義出来る。この定義では fun(kw=1) としてしか呼び出せない。 fun(1) はダメ。---)。

クラス定義内で、基底クラスのリストのあとでキーワード引数が許されるようになりました。これは metaclass を指定するための新しい規約 (次セクション参照) に使われるものですが、 metaclass サポートだけのためだけでなく他の目的に使うことも出来ます。

PEP 3104 [https://peps.python.org/pep-3104/]: nonlocal 文。 nonlocal x を使うと外側の (ただしグローバルでない) スコープから、直接変数を代入することが出来るようになります。 nonlocal は新しく予約語になりました。

PEP 3132 [https://peps.python.org/pep-3132/]: 拡張されたイテレータのアンパック。 a, b, *rest = some_sequence のようなことを書けるようになりました。 *rest, a = stuff も出来ます。 rest オブジェクトは常に (空かもしれなくても) リストです; 右辺には任意のイテラブルを置けます。例えば:

(a, *rest, b) = range(5)

これは a に 0 を、 b に 4 を、そして rest に [1, 2, 3] をセットします。

辞書内包表記: {k: v for k, v in stuff} は dict(stuff) と同じ意味ですが、より柔軟です。 (これは PEP 274 [https://peps.python.org/pep-0274/] で支持されています。)

セットリテラル、例えば {1, 2}。{} は空の辞書であることに注意してください。空のセットには set() を使用してください。セットの内包表記もサポートされました。例えば {x for x in stuff} は set(stuff) と同じ意味ですが、より柔軟です。

新たな8進数リテラル、e.g. 0o720 (2.6 で既にありました)。古い8進数リテラル (0720) は廃止されました。

新たなバイナリリテラル、e.g. 0b1010 (2.6 で既にありました) と、関連する新しい組み込み関数 bin() が導入されました。

b または B で始まるバイトリテラルと、関連する新しい組み込み関数 bytes() が導入されました。

変更された構文

PEP 3109 [https://peps.python.org/pep-3109/] と PEP 3134 [https://peps.python.org/pep-3134/]: 新たな raise 文のシンタックス: raise [expr [from expr]]。以下を参照してください。

as と with は予約語になりました。 (実際には 2.6 から)

True、False、および None が予約語になりました。(2.6 では既に None が部分的に制限されていました)

Change from except exc, var to except exc as var. See PEP 3110 [https://peps.python.org/pep-3110/].

PEP 3115 [https://peps.python.org/pep-3115/]: 新たなメタクラスのシンタックス．以下の;

class C:
    __metaclass__ = M
    ...

代わりに次のようにしてください:

class C(metaclass=M):
    ...

モジュールグローバルの __metaclass__ 変数はもうサポートされません。(これは object を派生しない全てのクラスのデフォルトを簡単に新スタイルクラス化するための「松葉杖」でした。) (---訳注: 「新/旧スタイルクラス」は Python 2.x 固有の概念。Python 2.1 までの旧式クラスと、Python 2.2 で導入された、現在まで続く object を派生する (当時の旧からみた) 新スタイル。Python 2.2 から 2.7 では class Clazz: は (モジュールグローバルの __metaclass__ を使わない限り) object を派生しない旧スタイルクラスでしたが、Python 3.x にはもはや「旧スタイルクラス」がないのでこれは Python 2.2 から 2.7 での class Clazz(object): と同じ意味です。---)

リスト内包表記はもう [... for var in item1, item2, ...] という構文形をサポートしません。代わりに [... for var in (item1, item2, ...)] を使用してください。また、リスト内包表記は異なるセマンティクスを持つことに注意してください。リスト内包表記は list() コンストラクタ内のジェネレータ式の糖衣構文に近く、特にループの制御変数はスコープ外ではもう使用することができません。

ellipsis (...) はどこででも原子的な式として使うことが出来ます。 (以前はスライス内でのみ許されていました。) また、... と書かなければ ならなく なりました。 (以前は文法の些細な偶然により . . . と書くことも出来ました。)

削除された操作

PEP 3113 [https://peps.python.org/pep-3113/]: タプル引数のアンパックが削除されました. def foo(a, (b, c)): ... のように書くことはできません。かわりに def foo(a, b_c): b, c = b_c を使用してください。

バッククオートが削除されました (代わりに repr() を使用してください)。

<> が削除されました (代わりに != を使用してください)。

削除されたキーワード: exec() はキーワードでなくなりましたが、関数として残りました。 (幸運にも関数のシンタックスは 2.x でも許容されています。) また、 exec() はストリーム引数を受け取らなくなりました。exec(f) の代わりに exec(f.read()) を使うことができます。

l または L で終わる整数リテラルはサポートされません。

u or U で始まる文字列リテラルはサポートされません。(---訳注: この u"..." は Python 3.3 で再び使えるようになりました。 ---)

from module import * はモジュールレベルでのみ許され、関数内での使用は許されません。

相対インポートに許される構文は from .[module] import name のみです。 . で始まらない形の全ての import は絶対インポートと解釈されます。 (PEP 328 [https://peps.python.org/pep-0328/])

古い形式のクラスはサポートされません。

Python 2.6 で既にあった変更

おそらく多くのユーザが一足飛びに Python 2.5 から Python 3.0 に移行しようとするでしょうから、このセクションでは、もともとは Python 3.0 のためにデザインされたものの Python 2.6 にバックポートされた新機能について、読者に思い出してもらいましょう。 What's New in Python 2.6 内の対応するセクションにはもっと長い説明が書かれています。

PEP 343: "with" ステートメント. with 文は今では標準機能となったので、 __future__ からインポートする必要はもうありません。 コンテキストマネージャを書く と contextlib モジュール も見てください。

PEP 366: メインモジュールからの明示的相対インポート. -m オプションの有用性を強化します。パッケージ内にあるモジュールを参照している際に関係します。

PEP 370: ユーザごとの site-packages ディレクトリ.

PEP 371: multiprocessing パッケージ.

PEP 3101: 進化版文字列フォーマッティング. 注意: 2.6 の記述では format() メソッドが 8 ビット文字列と Unicode 文字列両方について述べていますが、3.0 では str 型 (Unicode サポートを持ったテキスト文字列) だけがこのメソッドをサポートしています。 bytes 型にはありません。計画では最終的にはこれだけが唯一の文字列フォーマットの API になり、Python 3.1 では % 演算子は非推奨扱いを開始する予定です。(--- 訳注: % 演算子の撤廃は影響が大き過ぎるからか、現実には (ドキュメントでの軽い記述を除き) 実行時に特別に非推奨扱いされることは 3.5 になってさえもいまだありません。 ---)

PEP 3105: print を関数にする. これはもはや標準機能となったので、 __future__ からインポートする必要はありません。詳細はこのドキュメントの上の方に書いてあります。

PEP 3110: 例外処理の変更. The except exc as var syntax is now standard and except exc, var is no longer supported. (Of course, the as var part is still optional.)

PEP 3112: バイトリテラル. 文字列リテラル b"..." 表記 (とそのお仲間 b'...', b"""...""", br"..." など) は今では bytes 型です。

PEP 3116: 新しい I/O ライブラリ. io モジュールが今ではファイル I/O の標準手段です。組み込みの open() は今では io.open() へのエイリアスであり、また、追加のキーワード引数 encoding, errors, newline, closefd を持ちます。不正な mode 引数で IOError ではなく ValueError を投げるようになったことにも注意してください。テキストファイルオブジェクトの背後にあるバイナリファイルオブジェクトには、 f.buffer でアクセスできます。(ただしエンコーディング・デコーディング操作の高速化のために、テキストオブジェクトは自身のバッファを保守管理していることに注意してください。)

PEP 3118: 改訂版バッファプロトコル. 古いビルトインの buffer() は本当になくなりました; 新しいビルトイン memoryview() が (ほぼ) 同様の機能性を提供します。

PEP 3119: 抽象基底クラス. collections モジュール内で定義されている abc モジュールと ABC 群が今では言語においてもっと目立った役割を演じるようになっていて、たとえば dict や list のようなビルトインのコレクション型はそれぞれ collections.MutableMapping と collections.MutableSequence の ABC に従うようになっています。

PEP 3127: 整数リテラルのサポートと文法. 上述のとおり、新しい 8 進数リテラル表現だけが唯一の 8 進数リテラル表現となり、また、バイナリリテラルが追加されました。

PEP 3129: クラスデコレータ.

PEP 3141: 数値の型階層. numbers が、もう一つの新しく ABC を使うモジュールで、Python の「数値塔 (numeric tower)」を定義しています。新しい fractions モジュールが numbers.Rational を実装していることにも注目してください。

ライブラリの変更

時間の制約により、この文書は標準ライブラリの非常に幅広い変更について徹底的に取り上げてはいません。ライブラリの大きな変更については PEP 3108 [https://peps.python.org/pep-3108/] を参照してください。ここでは要約を示します:

多くの古いモジュールは削除されました。 gopherlib (もう使われません) や md5 (hashlib に代替されました) 等のいくつかのモジュールは PEP 4 [https://peps.python.org/pep-0004/] で既に廃止予定でした。他のモジュールは、Irix、BeOS ならびに Mac OS 9 等のプラットフォームでのサポートが打ち切られた (PEP 11 [https://peps.python.org/pep-0011/] 参照) ために削除されました。いくつかのモジュールは使われなかったり、より良い代用品があるため Python 3.0 で削除されました網羅的なリストは PEP 3108 [https://peps.python.org/pep-3108/] を参照してください。

The 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 https://www.jcea.es/programacion/pybsddb.htm.

いくつかのモジュールは PEP 8 [https://peps.python.org/pep-0008/] に従っていないか、その他の理由により名前が変更されました:

以前の名前

新しい名前

_winreg

winreg

ConfigParser

configparser

copy_reg

copyreg

Queue

queue

SocketServer

socketserver

markupbase

_markupbase

repr

reprlib

test.test_support

test.support

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, pickle and 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 pickle / cPickle pair received this treatment. The profile module is on the list for 3.1. The StringIO module has been turned into a class in the io module.

関連のあるモジュールのいくつかはパッケージにまとめられ、ふつうサブモジュール名は単純化されました。結果として以下のようなパッケージが出来ました:

dbm (anydbm, dbhash, dbm, dumbdbm, gdbm, whichdb).

html (HTMLParser, htmlentitydefs).

http (httplib, BaseHTTPServer, CGIHTTPServer, SimpleHTTPServer, Cookie, cookielib).

tkinter (turtle を除く全ての Tkinter 関連のモジュール)。 turtle の対象読者は tkinter にそれほど関心がありません。また、Python 2.6 以降では turtle の機能は大幅に向上しました。

urllib (urllib, urllib2, urlparse, robotparse).

xmlrpc (xmlrpclib, DocXMLRPCServer, SimpleXMLRPCServer).

PEP 3108 [https://peps.python.org/pep-3108/] で取り上げられていない標準ライブラリーの他の変更:

Killed sets. Use the built-in set() class.

sys モジュールの整理: sys.exitfunc(), sys.exc_clear(), sys.exc_type, sys.exc_value, sys.exc_traceback は削除されました。(sys.last_type 等はまだあります。)

array.array 型の整理: read() ならびに write() メソッドは廃止されました。代わりに fromfile() ならびに tofile() を使用してください。また、array 向けの 'c' タイプコードは廃止されました。バイトには 'b' 、Unicode 文字には 'u' を使用してください。

operator モジュールの整理: sequenceIncludes() および isCallable() は削除されました。

Cleanup of the thread module: acquire_lock() and release_lock() are gone; use acquire() and release() instead.

random モジュールの整理: jumpahead() API は削除されました。

The new module is gone.

関数 os.tmpnam()、os.tempnam() および os.tmpfile() は tempfile のため削除されました。

tokenize モジュールはバイトでも機能するように変更されました。メインのエントリポイントは generate_tokens から tokenize.tokenize() になりました。

string.letters and its friends (string.lowercase and string.uppercase) are gone. Use string.ascii_letters etc. instead. (The reason for the removal is that string.letters and friends had locale-specific behavior, which is a bad idea for such attractively named global "constants".)

モジュール __builtin__ が builtins にリネームされました (アンダースコアの削除と 's' の追加)。大半の大域名前空間における __builtins__ 変数は変更されていません。組み込みを変更するには __builtins__ でなく builtins を使わなければなりません。

PEP 3101 [https://peps.python.org/pep-3101/]: 文字列整形の新たなアプローチ

組み込みの新しい文字列書式化操作で、文字列の % 演算子を置き換えるものです。(しかしながら % 演算子はまだサポートされます; Python 3.1 で非推奨となり、将来のいつかの時点で削除されます。) 完全な詳細は PEP 3101 [https://peps.python.org/pep-3101/] をお読み下さい。 (--- 訳注: Python 2.6 で既にあった変更 での対応する記述に書いた訳注を参照。---)

例外に関する変更

例外の送出や捕捉を行う API は整理され、 強力な新機能が追加されました:

PEP 352 [https://peps.python.org/pep-0352/]: 全ての例外は (直接的にまたは間接的に) BaseException を継承しなければなりません。 BaseException は例外階層の根です。これは勧告としては新しくありませんが、BaseException 継承の 要求 は新しいです。 (Python 2.6 は依然として昔のクラスを送出するのを許容しており、捕捉するものについての制限はありません。) 結果として文字列例外は終に本当の意味で、完全になくなりました。

ほとんど全ての例外は、実際は Exception を継承すべきです。 BaseException は最上位で扱われるべき例外、例えば SystemExit や KeyboardInterrupt の基底クラスとしてのみ使われるべきでしす。上記カテゴリーを除く全ての例外を処理するのに推奨されるイディオムは except Exception です。

StandardError は削除されました。

例外はシーケンスとして振る舞わなくなりました。代わりに args 属性を使用してください。

PEP 3109 [https://peps.python.org/pep-3109/]: Raising exceptions. You must now use raise Exception(args) instead of raise Exception, args. Additionally, you can no longer explicitly specify a traceback; instead, if you have to do this, you can assign directly to the __traceback__ attribute (see below).

PEP 3110 [https://peps.python.org/pep-3110/]: 例外の捕捉。 except SomeException, variable ではなく except SomeException as variable としなければなりません。その上 except ブロックがある場合 variable は明示的に削除されます。

PEP 3134 [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 except or 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 __context__ attribute of the secondary exception. Explicit chaining is invoked with this syntax:

raise SecondaryException() from primary_exception

(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 __cause__ attribute of the secondary exception. The traceback printed when an unhandled exception occurs walks the chain of __cause__ and __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.)

PEP 3134 [https://peps.python.org/pep-3134/]: Exception objects now store their traceback as the __traceback__ attribute. This means that an exception object now contains all the information pertaining to an exception, and there are fewer reasons to use sys.exc_info() (though the latter is not removed).

Windows が拡張モジュールのロードに失敗したときの例外メッセージが少し改善しました。例えば、error code 193 は %1 is not a valid Win32 application になりました。文字列は英語でないロケールを扱えるようになりました。

その他の変更

演算子と特殊メソッド

!= は == と逆の結果をかえします（== が NotImplemented を返さなければ）。

「非束縛メソッド (unbound methods)」という概念は言語から削除されました。クラス属性としてのメソッドを参照しても今では普通の関数オブジェクトが得られます。

__getslice__(), __setslice__(), __delslice__() はお亡くなりになりました。構文 a[i:j] は今では a.__getitem__(slice(i, j)) と解釈されます (または代入や削除で使われる場合は順に __setitem__() か __delitem__())。

PEP 3114 [https://peps.python.org/pep-3114/]: next() 標準メソッドは __next__() に改名されました。

__oct__() ならびに __hex__() 特殊メソッドは削除されました。 oct() ならびに hex() は __index__() を使って引数を整数に変換します。

__members__ と __methods__ は削除されました。

The function attributes named func_X have been renamed to use the __X__ form, freeing up these names in the function attribute namespace for user-defined attributes. To wit, func_closure, func_code, func_defaults, func_dict, func_doc, func_globals, func_name were renamed to __closure__, __code__, __defaults__, __dict__, __doc__, __globals__, __name__, respectively.

__nonzero__() is now __bool__().

組み込み

PEP 3135 [https://peps.python.org/pep-3135/]: 新しくなった super() 。今では super() は引数なしで呼び出せます。(これが class 内で定義される通常のインスタンスメソッド内であると仮定して) 正しいクラスとインスタンスが自動的に選択されます。引数ありの場合の super() の振る舞いには変更はありません。

PEP 3111 [https://peps.python.org/pep-3111/]: raw_input() が input() にリネームされました。つまり、新しい input() 関数は sys.stdin から行を読み、末尾の改行を取り除いて返します。入力が時期尚早に終わってしまったら EOFError になります。昔の input() の振る舞いが欲しければ eval(input()) としてください。

新しい組み込み関数 next() が追加されました。 オブジェクトの __next__() メソッドを呼び出します。

round() 関数の丸めの戦略と戻り値の型が変更されました。ど真ん中の場合に、四捨五入ではなく最近接偶数への丸めをするようになりました。(例えば round(2.5) は今では 2 を返します。 3 ではなく。) (---訳注: 丸めモードについては Wikipedia [https://en.wikipedia.org/wiki/Rounding#Tie-breaking] 参照。---) round(x[, n]) は常に浮動小数点数の結果を返す代わりに、 x.__round__([n]) に処理を委譲するようになりました。これは一般的に、単一引数で呼ばれた際に整数を返し、二つの引数で呼ばれた場合は x と同じ型の値として返します。

intern() は sys.intern() に移動しました。

apply() は削除されました。 apply(f, args) の代わりに f(*args) を使用してください。

callable() は削除されました。 callable(f) のかわりに isinstance(f, collections.Callable) を使用してください。 operator.isCallable() も削除されました。

coerce() は削除されました。古い形式のクラスが削除されたため、この関数は必要ありません。

execfile() は削除されました。 execfile(fn) の代わりに exec(open(fn).read()) を使用してください。

Removed the file type. Use open(). There are now several different kinds of streams that open can return in the io module.

reduce() は削除されました。もし本当に必要なら functools.reduce() を使用してください。ほぼ間違いなく for ループのほうがより可読性が高いでしょう。

Removed reload(). Use imp.reload().

dict.has_key() は削除されました -- 代わりに in 演算子を使用してください。

ビルドならびに C API の変更

時間がないため、以下のC APIへの変更点のリストは かなり 不完全です。

Mac OS 9, BeOS, RISCOS, Irix, Tru64 に限らず、いくつものプラットフォームのサポートが打ち切られました。

PEP 3118 [https://peps.python.org/pep-3118/]: 新たなバッファ API。

PEP 3121 [https://peps.python.org/pep-3121/]: 例外モジュールの初期化と最終化

PEP 3123 [https://peps.python.org/pep-3123/]: PyObject_HEAD を標準的な C に一致。

制限付き実行 の C API サポートはこれ以上されません。

PyNumber_Coerce(), PyNumber_CoerceEx(), PyMember_Get(), and PyMember_Set() C APIs are removed.

新たな C API PyImport_ImportModuleNoBlock()、PyImport_ImportModule() のように動きますが、インポートロックでブロックしません (代わりにエラーを返します)。

ブール変換の C 水準のスロットとメソッドがリネームされました: nb_nonzero が nb_bool になりました。

Removed METH_OLDARGS and WITH_CYCLE_GC from the C API.

性能

3.0 の可搬化 (generalization) による正味の結果は、Python 3.0 を pystone ベンチマークすると Python 2.5 より 10% 遅くなる、というものでした。これはどうやら小さい整数についての特殊処理を削除したことに一番大きな要因があるようです。これには改善の余地がありますが、それは 3.0 リリース以降でしょう!

Python 3.0 への移植

(---訳注: 今では独立したクックブック How to port Python 2 Code to Python 3 があるのでそちらをご覧下さい。---) 既存の Python 2.5 や 2.6 のソースコードを Python 3.0 に移植する最良の策は以下の通りです:

(必須:) 優秀なテストカバレッジから始めてください。

Python 2.6 に移植します。Python 2.x を Python 2.(x+1) に移植する普通の作業以上のことをしてはいけません。確実に全てのテストを通してください。

(まだ 2.6 を使います:) コマンドラインに -3 オプションを渡します。これは 3.0 で削除された (または変更された) 機能についての警告発行を有効にします。再びテストスイートを実行して、そして警告が出たコードをそれがなくなるまで修正し、全てのテストをパスさせます。

Run the 2to3 source-to-source translator over your source code tree. (See 2to3 --- Python 2 から 3 への自動コード変換 for more on this tool.) Run the result of the translation under Python 3.0. Manually fix up any remaining issues, fixing problems until all tests pass again.

Python 2.6 と 3.0 両方で変更なしに動作するコードを書こうとすることはお奨め出来ません; それをするととても捻じ曲がったコーディングスタイルを使う必要があるでしょう。例えば print やメタクラスを避けたりとかそんな。Python 2.6 と 3.0 両バージョンともに対するサポートを必要とするライブラリを保守しているのであれば、最良のアプローチは上記スリーステップを修正して、2.6 版のソースコードを編集して 2to3 する、を繰り返すことです。これは 3.0 版のソースコードを編集するより良いです。(---訳注: ここで言っていることは正論なのですが、 2to3 は「Python 3 では動くが Python 2 では動かない (かもしれない)」ものを生成します。2016 時点でも Python 2.7 はかなり元気 (予定では 2020 年までは公式にサポートされる) ですので両バージョン (ただし今だと 2.7 と 3.2 以降) で変更なしで動作するものを必要とすることは、残念ながらまだ多いでしょう (あなたが作っているのがライブラリであるならば)。これについては How to port Python 2 Code to Python 3 に少し書かれています。 ---)

C 拡張を Python 3.0 に移植するには、 Python 3 への拡張モジュール移植 を参照してください。

What's New in Python 2.7

著者:

A.M. Kuchling (amk at amk.ca)

この文書は Python 2.7 の新機能について解説します。Python 2.7 は 2010 年 7 月 3 日にリリースされました。

数値周りの扱いが、浮動小数点数でも Decimal クラスでもいろいろな点で改良されました、標準ライブラリにいくつかの有用な追加が行われました。 unittest モジュールが大幅に改良され、コマンドラインオプション解析の argparse モジュールが追加され、 collections モジュールに便利な OrderedDict と Counter が追加され、他にもたくさんの改良が行われています。

Python 2.7 は 2.x の最終リリースになることが予定されているので、私たちはこのリリースを長期にわたって良いものになるように努力してきました。Python 3 への移植を助けるため、いくつかの新機能が Python 3.x から Python 2.7 に取り込まれています。

このドキュメントは新機能の完全な詳細を提供するのではなくて、簡易な概要を提供することを目的にしています。完全な詳細が知りたければ、 https://docs.python.org の Python 2.7 のドキュメントを参照してください。設計と実装の根拠を理解したい場合は、新機能に関する PEP を参照するか、 https://bugs.python.org に議論したい機能について登録してください。可能な限り、 "What's New in Python" は各変更の bug や patch に対してリンクしています。

Python 2.x の今後

Python 2.7 は 2.x シリーズの最後のメジャーリリースになります。Python のメンテナは既に Python 3.x シリーズへの新機能の開発に焦点をシフトしています。Python 2 は今後もバグフィックスを受け容れ、新しいハードウェアやサポートしている OS のバージョンでのビルドが出来るように保つ一方で、言語や標準ライブラリの新しい完全な機能のリリースは行いません。

しかしながら、Python 2.7 と Python 3 の間の共通の大きなサブセットがあって、その共通サブセットあるいは直接的に Python 3 のものへの移行に伴う多くの変更が安全に自動的に行える一方で、その他の変更(Unicode の扱いに関係するものに顕著ですが)入念な検討を必要とし、移行を有効に行うためには堅牢な回帰テストスイートが望まれることでしょう。

これは Python 2.7 が長期間に渡って依然として有効であり、安定性と、Python 3 がいまだに移植されていないような製品システムのベースプラットフォームのサポートを提供し続けることを意味しています。Python 2.7 シリーズに望まれているライフサイクルについての完全な詳細は、 PEP 373 [https://peps.python.org/pep-0373/] に記述されています。

2.7 が長期的に重要なリリースになるので、いくつかの結論があります:

上述のように、 2.7 リリースは以前の 2.x バージョンに較べて遥かに長期間のメンテナンスとなります。Python 2.7 は現在では、最低でも 2020 年までコア開発チームによって(セキュリティアップデートやほかのバグフィックスの)サポートがなされ続けることが求められています(最初のリリースから 10 年後です。普通であれば 18--24 ヶ月なのに)。

Python 2.7 標準ライブラリが年老いていくに従い、(直接であれ再配布であれ) Python Package Index の効果的な利用が Python 2 ユーザにとってますます重要になっています。さまざまなタスクをこなすありとあらゆるサードパーティパッケージに加え、Python 2 互換の、Python 3 標準ライブラリからバックポートした新しいモジュールや機能を含むパッケージ、Python 3 への移行を容易にするための様々なツールやライブラリが入手出来ます。Python Packaging User Guide [https://packaging.python.org] は Python Package Index からソフトウェアをダウンロード・インストールする際のガイダンスです。

Python 2 を拡張するための望ましいアプローチは現在では Python Package Index に新しいパッケージを公開することである一方で、このアプローチが全てのケースで求められるわけではありません。特にそれがネットワークセキュリティに関係している場合には。PyPI に新規もしくは更新パッケージを公開することでは十分ではない例外的なケースにおいては、Python 2 標準ライブラリに直接新機能を追加するために Python Enhancement Proposal プロセスが使われるでしょう。そのような追加の全てと、それらが追加されたメンテナンスリリースは、下の方の Python 2.7 メンテナンスリリースで追加された新機能 セクションで言及されます。

Python 2 から Python 3 へ乗り換えたいと望むプロジェクトあるいはPython 2 と Python 3 両方のユーザをサポートしたいと願うライブラリやフレームワークの開発者向けに、さまざまなツールやガイドがあります。これらは、相応しいアプローチを決めたりある種複雑な技術的詳細の管理をする手助けとなるでしょう。まず手始めには How to port Python 2 Code to Python 3 HOWTO ガイドをご覧になることをお奨めします。

Deprecation Warnings の扱いの変更

Python 2.7 では開発者向けの警告をデフォルトで抑止するポリシーが取られました。 DeprecationWarning とそれを継承した警告は、指定されない限りは無視され、アプリケーションのユーザーがその警告を見ないですむようになりました。この変更は Python 3.2 ブランチにも適用されました。 (stdlib-sig で討議され、 bpo-7319 [https://bugs.python.org/issue?@action=redirect&bpo=7319] になりました)

以前のリリースでは、 DeprecationWarning メッセージはデフォルトで有効になっており、 Python 開発者に、将来のバージョンの Python でそのコードのどこが動かなくなるかを明確に知らせていました。

しかし、 Python で開発されたアプリケーションの利用者であって開発には携わっていない人がどんどん増えてきました。 DeprecationWarning メッセージはそれらのユーザーには無関係で、彼らをアプリケーションが本当に正しく動いているのか不安にさせ、ユーザーの質問に応えるための開発者の負担も増やしていました。

DeprecationWarning メッセージの表示を有効にするには、 -Wdefault (短い形式: -Wd) スイッチか、Python を実行する前に PYTHONWARNINGS 環境変数を "default" (か、 "d")に設定します。 Python コードから有効にする場合は warnings.simplefilter('default') とします。

unittest モジュールもテスト実行時に自動的に deprecation warnings を有効にします。

Python 3.1 の機能

Python 2.6 は Python 3.0 から多くの機能を取り込み、Python 2.7 は Python 3.1 の新しい機能のいくつかを取り込みました。2.x シリーズは 3.x シリーズへの移行のためのツールを提供し続けています。

Python 2.7 に取り込まれた 3.1 の機能の不完全なリスト:

集合のリテラル文法 ({1,2,3} は mutable set になります)

辞書と集合の内包表記 ({i: i*2 for i in range(3)}).

1つの with 文で複数のコンテキストマネージャを扱えるように。

io ライブラリの新バージョン。パフォーマンスのためにC言語で描き直されています。

PEP 372: collections に順序付き辞書を追加 で解説されている順序付き辞書

PEP 378: 1000区切りのための書式指定子 で解説されている新しい "," フォーマット指定子

memoryview オブジェクト

importlib モジュールの小さいサブセット。 下に説明があります

float x の repr() が多くの場合に短くなりました。これは x に戻せることが保証される最小の10進文字列です。以前のバージョンの Python では、 float(repr(x)) が x になることだけが保証されていました。

float から文字列、文字列から float への変換が正しく丸められるようになりました。 round() 関数も正しく丸めるようになりました。

拡張モジュールが C API を提供するための、 PyCapsule 型

PyLong_AsLongAndOverflow() C API 関数

新しい Python3 モード Warning:

operator.isCallable() と operator.sequenceIncludes() は 3.x ではサポートされず、警告が表示されます。

-3 スイッチは、整数または長整数での古い除算方式を使用した場合に警告を出力するようになる -Qwarn スイッチを有効にするようになりました。

PEP 372: collections に順序付き辞書を追加

通常の Python 辞書は、 key/value ペアを不定の順序でイテレートします。何年にもわたり、いろいろな人が key の挿入順を保存する辞書の別実装を書いてきました。その経験に基づき、 2.7 は collections モジュールに新しい OrderedDict クラスを追加しました。

OrderedDict API は通常の辞書と同じインターフェースを提供していますが、 key/value をイテレートするときに key が最初に挿入された順番になることが保証されています。

>>> from collections import OrderedDict
>>> d = OrderedDict([('first', 1),
...                  ('second', 2),
...                  ('third', 3)])
>>> d.items()
[('first', 1), ('second', 2), ('third', 3)]

新しいエントリが既存のエントリを上書きした場合は、元の挿入順序が保持されます。:

>>> d['second'] = 4
>>> d.items()
[('first', 1), ('second', 4), ('third', 3)]

エントリを削除して再挿入すると、順序は一番最後に移動します。:

>>> del d['second']
>>> d['second'] = 5
>>> d.items()
[('first', 1), ('third', 3), ('second', 5)]

popitem() メソッドは、オプションの last 引数を持ち、でフォルトで True になっています。 last が真の場合、一番最近に追加された key が返され、削除されます。偽の場合、最も古い key が選ばれます:

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

2つの順序付き辞書を比較するときは、key/value だけでなく、挿入順も比較されます。:

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

OrderedDict を通常の辞書と比較すると、挿入順は無視されて単に key/value だけが比較されます。

How does the 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 ConfigParser module uses them by default, meaning that configuration files can now be read, modified, and then written back in their original order.

collections.namedtuple() の _asdict() メソッドは、タプルの順序と同じ順序の順序付き辞書を返すようになりました。

The json module's JSONDecoder class constructor was extended with an object_pairs_hook parameter to allow OrderedDict instances to be built by the decoder. Support was also added for third-party tools like PyYAML [https://pyyaml.org/].

参考

PEP 372 [https://peps.python.org/pep-0372/] - collections に順序付き辞書を追加

PEP written by Armin Ronacher and Raymond Hettinger; implemented by Raymond Hettinger.

PEP 378: 1000区切りのための書式指定子

大きい数値に区切り文字を追加して、18446744073709551616 の代わりに 18,446,744,073,709,551,616 と出力すると、プログラムの出力を読みやすくできます。

これを行う一般的な方法は locale モジュールを使うことで、複数の区切り文字 (北米では "," で、ヨーロッパでは ".") を使ったり、複数のグループの大きさを使うことができます。しかし、 locale の利用方法は複雑ですし、スレッドごとに異なるロケールの出力を行うプログラムでは利用することができません。

そのため、シンプルなカンマによるグループ化機構が str.format() メソッドのミニ言語に追加されました。浮動小数点数をフォーマットする場合、シンプルにカンマを幅と精度の間に置きます。

>>> '{:20,.2f}'.format(18446744073709551616.0)
'18,446,744,073,709,551,616.00'

整数をフォーマットする場合は、幅の後にカンマを追加します。

>>> '{:20,d}'.format(18446744073709551616)
'18,446,744,073,709,551,616'

この機構は全く柔軟性を持っていません。区切り文字は常にカンマですし、グループは常に数字3つになります。カンマ書式機構は locale ほど汎用ではありませんが、手軽に使うことができます。

参考

PEP 378 [https://peps.python.org/pep-0378/] - 1000区切りのための書式指定子

PEP written by Raymond Hettinger; implemented by Eric Smith.

PEP 389: コマンドライン解析のための argparse モジュール

コマンドライン引数の解析のための argparse モジュールが、 optparse モジュールのより強力な代替として追加されました。

This means Python now supports three different modules for parsing command-line arguments: getopt, optparse, and argparse. The getopt module closely resembles the C library's getopt() function, so it remains useful if you're writing a Python prototype that will eventually be rewritten in C. 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 argparse API consistent with optparse's interface was discussed but rejected as too messy and difficult.)

古いバージョンの Python との互換性を気にすること無く新しいスクリプトを書く時は、 optparse の代わりに argparse を使ってください。

以下はこの使用例です:

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__

オーバーライドしない限り、 -h と --help スイッチが自動的に追加され、綺麗にフォーマットした出力を生成します。

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

optparse と同じく、コマンドラインスイッチと引数は、 dest 引数の名前の属性をもったオブジェクトとして返されます。

-> ./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']}

argparse は optparse よりも多くの便利なバリデーションを持っています。引数の正確な数を整数で指定したり、 '*' で0以上の数を指定したり、 '+' で1以上の数を指定したり、 '?' でオプションにしたりできます。トップレベルのパーサーはサブパーサーを持つことができ、 svn commit, svn checkout のように異なるオプションを持ったサブコマンドを定義できます。引数のタイプに FileType を指定することで、自動でファイルを開き、 '-' が指定されたときに標準入出力だと判断することができます。

参考

argparse のドキュメント

argparse モジュールのドキュメント

optparse からのアップグレード

optparse を使うコードを変換する方法を説明した Python のドキュメントの一部

PEP 389 [https://peps.python.org/pep-0389/] - argparse コマンドライン解析モジュール

PEP written and implemented by Steven Bethard.

PEP 391: logging の辞書ベースの設定

logging モジュールは非常に柔軟です。アプリケーションは logging のサブシステムのツリーを定義できます。このツリーの各ロガーはいくつかのメッセージをフィルターし、異なるフォーマットを行い、メッセージを沢山の種類のハンドラーに渡します。

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. logging also supports a 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 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 環境設定のための関数.

以下は、2つのロガー、 root logger と "network" という名前の logger を設定する例です。root logger に送られたメッセージは syslog プロトコルを利用してシステムログに送られ、 "network" logger に送られたメッセージは 1 MB ごとにローテートされる network.log ファイルに書きこまれます。

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')

他にも、 logging モジュールには Vinary Sajip によって実装された 3 つの改良があります。

SysLogHandler クラスは TCP 経由の syslog をサポートします。コンストラクタの socktype 引数は使用するソケットの種類として、 UDP を使う socket.SOCK_DGRAM と TCP を使う socket.SOCK_STREAM のどちらかを取ります。デフォルトはUDPのままです。

Logger インスタンスに getChild() メソッドが追加されました。これは、相対パスで下位の logger を返します。 例えば、 log = getLogger('app') として logger を取得した後、 log.getChild('network.listen') は getLogger('app.network.listen') と同じになります。

The LoggerAdapter class gained an isEnabledFor() method that takes a level and returns whether the underlying logger would process a message of that level of importance.

参考

PEP 391 [https://peps.python.org/pep-0391/] - logging の辞書ベースの設定

PEP written and implemented by Vinay Sajip.

PEP 3106: 辞書 View

辞書の keys(), values(), items() メソッドは Python 3.x では動作が代わり、完全に実体化されたリストの代わりに、 view と呼ばれるオブジェクトを返すようになりました。

It's not possible to change the return values of keys(), values(), and items() in Python 2.7 because too much code would break. Instead the 3.x versions were added under the new names viewkeys(), viewvalues(), and viewitems().

>>> 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])

View はイテレートするだけでなく、set と似た利用をすることもできます。& 演算子で共通部分集合を、| 演算子で話集合を取ることができます。

>>> 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])

view は辞書とその辞書の変化に追随しています。:

>>> vk = d.viewkeys()
>>> vk
dict_keys([0, 130, 10, ..., 250])
>>> d[260] = '&'
>>> vk
dict_keys([0, 130, 260, 10, ..., 250])

ただし、view をイテレートしている間に key の追加や削除ができないことに気を付けてください。:

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

Python 2.x で view メソッドを利用すると、 2to3 が自動的にそれを通常の keys(), values(), items() メソッドに書き換えてくれます。

参考

PEP 3106 [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 [https://bugs.python.org/issue?@action=redirect&bpo=1967].

PEP 3137: memoryview オブジェクト

memoryview オブジェクトは、他のオブジェクトのメモリの内容に対する bytes 型のインターフェースに合わせた view を提供します。

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

view の内容は bytes 型の文字列か整数のリストに変換することができます。

>>> m2.tobytes()
'abcdefghijklmnopqrstuvwxyz'
>>> m2.tolist()
[97, 98, 99, 100, 101, 102, 103, ... 121, 122]
>>>

memoryview オブジェクトは、対象となる背後のオブジェクトが変更可能 (mutable) な場合は、その変更を許可しています。

>>> 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')
>>>

参考

PEP 3137 [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 [https://bugs.python.org/issue?@action=redirect&bpo=2396].

その他の言語変更

Python 言語コアに小さな変更がいくつか行われました:

set リテラルのためのシンタックスが Python 3.x からバックポートされました。内容を波括弧で囲うと mutable set になります。dict リテラルとの区別は、コロンと value が存在しないことで行われます。なので、{} は引き続き空の dict になります。空の set を作るときには set() を使ってください。

>>> {1, 2, 3, 4, 5}
set([1, 2, 3, 4, 5])
>>> set() # empty set
set([])
>>> {}    # empty dict
{}

Backported by Alexandre Vassalotti; bpo-2335 [https://bugs.python.org/issue?@action=redirect&bpo=2335].

dict と set の内包表記も Python 3.x からバックポートされました。list と generator の内包表記を set と dict にも使えるように一般化させています。

>>> {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(['', 'a', 'aa', 'aaa', 'aaaa', 'aaaaa'])

Backported by Alexandre Vassalotti; bpo-2333 [https://bugs.python.org/issue?@action=redirect&bpo=2333].

with 文が1つの文で複数のコンテキストマネージャーを使えるようになりました。コンテキストマネージャーは左から右へ処理され、それぞれが新しい with 文の開始となるように扱われます。つまり:

with A() as a, B() as b:
    ... suite of statements ...

は、以下と同じです

with A() as a:
    with B() as b:
        ... suite of statements ...

The contextlib.nested() function provides a very similar function, so it's no longer necessary and has been deprecated.

(Proposed in https://codereview.appspot.com/53094; implemented by Georg Brandl.)

浮動小数点数と文字列の間の変換がほとんどのプラットフォームで正しく丸められるようになりました。この変換はいろいろな場面で発生します: float 型や complex 型に対する str() 関数の適用、 float や complex コンストラクタ、数値フォーマット、 marshal, pickle, json モジュールを使ってのシリアライズとデシリアライズ、 Python コード中の float や imaginary リテラルの解析、 Decimal から float への変換などです。

これに関連して、浮動小数点数 x の repr() は、 (round-half-to-even 丸めモードで)正しく丸め処理をした場合に元の x に戻せる最小の 10進文字列になりました。以前は x を17桁の10進文字列に丸めていました。

丸めライブラリが、この改善が Windows や gcc, icc, suncc を使った Unix 環境で動かす役目をおっています。このライブラリの正確な動作が保証できない少しの環境があるので、そういったシステムではこのライブラリは利用されません。 sys.float_repr_style が short なら新しいコードが利用されていて、 legacy なら利用されていません。

Implemented by Eric Smith and Mark Dickinson, using David Gay's dtoa.c library; bpo-7117 [https://bugs.python.org/issue?@action=redirect&bpo=7117].

多倍長整数や通常の整数から浮動小数点への変換でも丸め処理が変更され、元の数に一番近い浮動小数点値が返されるようになりました。これは浮動小数点へ完全に変換できる小さい整数では問題になりませんが、桁数に対して精度がどうしても足りない場合に関係します。Python 2.7 はより正確に近似するようになりました。例えば、Python 2.6 では次のように計算されていました:

>>> n = 295147905179352891391
>>> float(n)
2.9514790517935283e+20
>>> n - long(float(n))
65535L

Python 2.7 の浮動小数点への変換結果は元の数値より大きくなりますが、元の値により近くなっています:

>>> n = 295147905179352891391
>>> float(n)
2.9514790517935289e+20
>>> n - long(float(n))
-1L

(Implemented by Mark Dickinson; bpo-3166 [https://bugs.python.org/issue?@action=redirect&bpo=3166].)

この丸めの動作により、整数同士の true division (from __future__ import division) の結果もより正確になりました。 (Also implemented by Mark Dickinson; bpo-1811 [https://bugs.python.org/issue?@action=redirect&bpo=1811].)

Implicit coercion for complex numbers has been removed; the interpreter will no longer ever attempt to call a __coerce__() method on complex objects. (Removed by Meador Inge and Mark Dickinson; bpo-5211 [https://bugs.python.org/issue?@action=redirect&bpo=5211].)

str.format() メソッドは置換フィールドに対する自動ナンバリングをサポートするようになりました。これにより str.format() をより %s と同じように使えるようになりました。

>>> '{}:{}:{}'.format(2009, 04, 'Sunday')
'2009:4:Sunday'
>>> '{}:{}:{day}'.format(2009, 4, day='Sunday')
'2009:4:Sunday'

自動ナンバリングは左のフィールドから右のフィールドへと行われるので、最初の {...} 指定は str.format() メソッドの最初の引数を利用し、次の指定は次の引数を利用します。自動ナンバリングと明示的なナンバリングを混ぜて使うことはできず、全ての置換指定に手動でナンバリングするか、全てを自動ナンバリングに任せなければなりません。ただし、上の例の2つめのように、自動ナンバリングと名前フィールドを混ぜて使うことは可能です。 (Contributed by Eric Smith; bpo-5237 [https://bugs.python.org/issue?@action=redirect&bpo=5237].)

複素数が format() をサポートするようになりました。デフォルトでは右寄せになります。精度やカンマ区切りの指定は、実部と虚部のそれぞれに対して適用されます。アラインの指定は 1.5+3j のような複素数全体に対して適用されます。 (Contributed by Eric Smith; bpo-1588 [https://bugs.python.org/issue?@action=redirect&bpo=1588] and bpo-7988 [https://bugs.python.org/issue?@action=redirect&bpo=7988].)

'F' 書式符号は常に大文字を使って出力するようになり、 'INF' や 'NAN' が出力されるようになりました。 (Contributed by Eric Smith; bpo-3382 [https://bugs.python.org/issue?@action=redirect&bpo=3382].)

A low-level change: the object.__format__() method now triggers a PendingDeprecationWarning if it's passed a format string, because the __format__() method for 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 [https://bugs.python.org/issue?@action=redirect&bpo=7994].)

The int() and long() types gained a bit_length method that returns the number of bits necessary to represent its argument in binary:

>>> n = 37
>>> bin(n)
'0b100101'
>>> n.bit_length()
6
>>> n = 2**123-1
>>> n.bit_length()
123
>>> (n+1).bit_length()
124

(Contributed by Fredrik Johansson and Victor Stinner; bpo-3439 [https://bugs.python.org/issue?@action=redirect&bpo=3439].)

import 文が、絶対インポート (例: from .os import sep)が失敗したときに相対インポートを試さなくなりました。これはバグ修正ですが、いままでたまたま動いていただけの import 文を動かなくしてしまう可能性があります。(Fixed by Meador Inge; bpo-7902 [https://bugs.python.org/issue?@action=redirect&bpo=7902].)

It's now possible for a subclass of the built-in unicode type to override the __unicode__() method. (Implemented by Victor Stinner; bpo-1583863 [https://bugs.python.org/issue?@action=redirect&bpo=1583863].)

bytearray 型の translate() メソッドが第一引数に None を受け入れるようになりました。 (Fixed by Georg Brandl; bpo-4759 [https://bugs.python.org/issue?@action=redirect&bpo=4759].)

When using @classmethod and @staticmethod to wrap methods as class or static methods, the wrapper object now exposes the wrapped function as their __func__ attribute. (Contributed by Amaury Forgeot d'Arc, after a suggestion by George Sakkis; bpo-5982 [https://bugs.python.org/issue?@action=redirect&bpo=5982].)

__slots__ を利用して属性を制限した場合に、設定されていない属性を del したときに AttributeError にならなかったのを修正しました。 (Fixed by Benjamin Peterson; bpo-7604 [https://bugs.python.org/issue?@action=redirect&bpo=7604].)

2つの新しいエンコーディングが追加されました: "cp720" は主にアラビア文字に使われます。 "cp858" は cp850 の一種ですが、ユーロ記号を追加しています。 (CP720 contributed by Alexander Belchenko and Amaury Forgeot d'Arc in bpo-1616979 [https://bugs.python.org/issue?@action=redirect&bpo=1616979]; CP858 contributed by Tim Hatch in bpo-8016 [https://bugs.python.org/issue?@action=redirect&bpo=8016].)

The file object will now set the filename attribute on the IOError exception when trying to open a directory on POSIX platforms (noted by Jan Kaliszewski; bpo-4764 [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 [https://bugs.python.org/issue?@action=redirect&bpo=5677]).

Python の字句解析機は改行をそれ自身に変換するようになりました。それにより、組み込みの compile() 関数がどの改行コードを利用したコードでも受け付けるようになりました。また、コードの終端の改行も不要になりました。

関数宣言中の余分な丸括弧は Python 3.x では不正になりました。つまり、 def f((x)): pass はsyntax errorになります。 Python3 警告モードでは、 Python 2.7 はこの利用方法について警告を出すようになりました。 (Noted by James Lingard; bpo-7362 [https://bugs.python.org/issue?@action=redirect&bpo=7362].)

古いスタイルのクラスのオブジェクトに対して弱参照を作れるようになりました。新スタイルクラスには以前から弱参照を利用できます。(Fixed by Antoine Pitrou; bpo-8268 [https://bugs.python.org/issue?@action=redirect&bpo=8268].)

モジュールオブジェクトがGCされたとき、モジュールの辞書は、他にその辞書への参照を持っているものがない場合にのみクリアされるようになりました。(bpo-7140 [https://bugs.python.org/issue?@action=redirect&bpo=7140]).

インタプリタの変更

新しい環境変数 PYTHONWARNINGS を使って警告を制御できるようになりました。この環境変数には、 -W スイッチに使われる警告の設定を、カンマ区切りの文字列として指定します。 (Contributed by Brian Curtin; bpo-7301 [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 Cookie module into an error. (The exact syntax for setting an environment variable varies across operating systems and shells.)

export PYTHONWARNINGS=all,error:::Cookie:0

最適化

いくつかの場面でパフォーマンスが向上しています。

A new opcode was added to perform the initial setup for with statements, looking up the __enter__() and __exit__() methods. (Contributed by Benjamin Peterson.)

たくさんのオブジェクトを開放せずに確保していくという、よくある使い方の 1つにおいて、GCのパフォーマンスが向上しました。以前はこの場合にGCにかかる時間はオブジェクトの数の2乗に比例していました。現在はフルGCの数は増えたヒープ上のオブジェクトの数に比例しています。新しい方式では、3世代中2世代目に対するGCが10回実行されたうえで、 2世代目から3世代目に移ったオブジェクトの数が3世代目のオブジェクトの数の 10%を超えたときにフルGCが発生します。(Suggested by Martin von Löwis and implemented by Antoine Pitrou; bpo-4074 [https://bugs.python.org/issue?@action=redirect&bpo=4074].)

GCが循環参照になりえないシンプルなコンテナ型の追跡を避けるようになりました。 Python 2.7 では、アトミックな型(整数、文字列など)のみを含むタプルと辞書は追跡されません。推移的に、アトミックな型のみを含むタプルを含む辞書も、同じく追跡されません。これにより、GCによって巡回されチェックされるオブジェクトの数が減るので、 GCのコストを減らすことができます。 (Contributed by Antoine Pitrou; bpo-4688 [https://bugs.python.org/issue?@action=redirect&bpo=4688].)

Long integers are now stored internally either in base 2**15 or in base 2**30, the base being determined at build time. Previously, they were always stored in base 2**15. Using base 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 2**30 on 64-bit machines and base 2**15 on 32-bit machines; on Unix, there's a new configure option --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 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:

>>> import sys
>>> sys.long_info
sys.long_info(bits_per_digit=30, sizeof_digit=4)

(Contributed by Mark Dickinson; bpo-4258 [https://bugs.python.org/issue?@action=redirect&bpo=4258].)

その他の変更により、多倍長整数オブジェクトのサイズは数バイト小さくなりました。 32bit システムでは 2byte, 64bit システムでは 6byte 小さくなりました。 (Contributed by Mark Dickinson; bpo-5260 [https://bugs.python.org/issue?@action=redirect&bpo=5260].)

多倍長整数の除算アルゴリズムが、内部のループの軽量化や乗算からシフト演算への置き換え、不要なイテレーションの削除により高速化されました。いくつかのベンチマークによると、多倍長整数の剰余演算は 50% から 150% 高速化されています。 (Contributed by Mark Dickinson; bpo-5512 [https://bugs.python.org/issue?@action=redirect&bpo=5512].) ビット演算も高速化されています。(initial patch by Gregory Smith; bpo-1087418 [https://bugs.python.org/issue?@action=redirect&bpo=1087418])

% の実装が、左側のオペランドが文字列型かどうかをチェックしてその場合の処理を特殊化しました。これにより文字列に対して % を頻繁に使う、テンプレートライブラリなどのアプリケーションのパフォーマンスが1--3%向上します。 (Implemented by Collin Winter; bpo-5176 [https://bugs.python.org/issue?@action=redirect&bpo=5176].)

if 条件付きのリスト内包表記がより高速なバイトコードにコンパイルされるようになりました。(Patch by Antoine Pitrou, back-ported to 2.7 by Jeffrey Yasskin; bpo-4715 [https://bugs.python.org/issue?@action=redirect&bpo=4715].)

整数や多倍長整数から10進文字列への変換を、任意の基数をサポートした汎用の変換関数を使う代わりに10進数に特殊化した処理を行うことで高速化しました。 (Patch by Gawain Bolton; bpo-6713 [https://bugs.python.org/issue?@action=redirect&bpo=6713].)

The split(), replace(), rindex(), rpartition(), and rsplit() methods of string-like types (strings, Unicode strings, and 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 [https://bugs.python.org/issue?@action=redirect&bpo=7462] and bpo-7622 [https://bugs.python.org/issue?@action=redirect&bpo=7622].)

The pickle and 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 [https://bugs.python.org/issue?@action=redirect&bpo=5084].)

The cPickle module now special-cases dictionaries, nearly halving the time required to pickle them. (Contributed by Collin Winter; bpo-5670 [https://bugs.python.org/issue?@action=redirect&bpo=5670].)

新しいモジュールと改良されたモジュール

全てのリリースに置いて、 Python の標準ライブラリはたくさんの改良とバグ修正がされてきました。ここでは一部の注目に値する変更を、モジュール名で辞書順ソートしてリストアップしています。もっと完全な変更リストが見たければ、ソースツリー内の Misc/NEWS ファイルか、全ての完全な詳細が入っている Subversion のログを参照してください。

bdb モジュールの基底デバッガクラス Bdb に、モジュールをスキップする機能が追加されました。コンストラクタは django.* のような glob スタイルのパターンをもった iterable を引数として受け取ります。デバッガはパターンのどれかにマッチするスタックフレームにステップインしません。 (Contributed by Maru Newby after a suggestion by Senthil Kumaran; bpo-5142 [https://bugs.python.org/issue?@action=redirect&bpo=5142].)

binascii モジュールが buffer API をサポートするようになり、 memoryview インスタンスやその他のバッファオブジェクトともに利用できるようになりました。 (Backported from 3.x by Florent Xicluna; bpo-7703 [https://bugs.python.org/issue?@action=redirect&bpo=7703].)

Updated module: the bsddb module has been updated from 4.7.2devel9 to version 4.8.4 of the pybsddb package [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 [https://bugs.python.org/issue?@action=redirect&bpo=8156]. The pybsddb changelog can be read at https://hg.jcea.es/pybsddb/file/tip/ChangeLog.)

bz2 モジュールの BZ2File がコンテキストマネージャープロトコルをサポートするようになりました。これにより、 with bz2.BZ2File(...) as f: といった書き方ができます。 (Contributed by Hagen Fürstenau; bpo-3860 [https://bugs.python.org/issue?@action=redirect&bpo=3860].)

collections モジュールの新しい Counter クラスは、データの数え上げをするときに便利です。 Counter インスタンスは辞書のように振る舞いますが、キーが存在しなかったときに KeyError 例外を発生させる代わりに 0 を返します。

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

Counter には追加の3つのメソッドがあります。 most_common() はカウントが最も多い N 要素とそのカウントを返します。 elements() はカウントしている要素を、そのカウント数だけ繰り返すイテレータを返します。 subtract() はイテレート可能型を受け取り、その各要素を足すのではなく引いて行きます。引数が辞書か他の Counter だった場合は、そのカウントが引かれます。

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

Contributed by Raymond Hettinger; bpo-1696199 [https://bugs.python.org/issue?@action=redirect&bpo=1696199].

新しいクラス OrderedDict はすでに PEP 372: collections に順序付き辞書を追加 で紹介しました。

メソッドが追加されました。deque データ型の count() メソッドは、引数で指定された x と等しい要素が何個入っているかを返します。 reverse() メソッドは deque 内の要素をインプレースで逆順にします。 deque はまた、最大長を返す読み出し専用の属性 maxlen を持ちます。 (Both features added by Raymond Hettinger.)

namedtuple クラスにオプションの rename 引数が追加されました。 rename が真のとき、複数回現れたり Python の識別子として許可されないために無効なフィールド名があったとき、フィールドのリスト内での場所に基づく有効なフィールド名に置き換えられます。

>>> from collections import namedtuple
>>> T = namedtuple('T', ['field1', '$illegal', 'for', 'field2'], rename=True)
>>> T._fields
('field1', '_1', '_2', 'field2')

(Added by Raymond Hettinger; bpo-1818 [https://bugs.python.org/issue?@action=redirect&bpo=1818].)

Finally, the Mapping abstract base class now returns NotImplemented if a mapping is compared to another type that isn't a Mapping. (Fixed by Daniel Stutzbach; bpo-8729 [https://bugs.python.org/issue?@action=redirect&bpo=8729].)

Constructors for the parsing classes in the ConfigParser module now take an allow_no_value parameter, defaulting to false; if true, options without values will be allowed. For 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'

(Contributed by Mats Kindahl; bpo-7005 [https://bugs.python.org/issue?@action=redirect&bpo=7005].)

Deprecated function: contextlib.nested(), which allows handling more than one context manager with a single with statement, has been deprecated, because the with statement now supports multiple context managers.

The 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 [https://bugs.python.org/issue?@action=redirect&bpo=3924].)

copy モジュールの deepcopy() 関数が、束縛ずみインスタンスメソッドを正しくコピーするようになりました。(Implemented by Robert Collins; bpo-1515 [https://bugs.python.org/issue?@action=redirect&bpo=1515].)

ctypes モジュールが、ポインタとして宣言された引数に対して None が渡された場合常に C の NULL ポインタに変換するようになりました。(Changed by Thomas Heller; bpo-4606 [https://bugs.python.org/issue?@action=redirect&bpo=4606].) 根底の、 libffi ライブラリ [https://sourceware.org/libffi/] がバージョン 3.0.9 にアップデートされ、いくつかのプラットフォームにおけるいろいろな問題が修正されました。(Updated by Matthias Klose; bpo-8142 [https://bugs.python.org/issue?@action=redirect&bpo=8142].)

新しいメソッド: datetime モジュールの timedelta クラスに total_seconds() メソッドが追加されました。これはその期間の秒数を返します。(Contributed by Brian Quinlan; bpo-5788 [https://bugs.python.org/issue?@action=redirect&bpo=5788].)

New method: the Decimal class gained a from_float() class method that performs an exact conversion of a floating-point number to a 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, Decimal.from_float(0.1) returns Decimal('0.1000000000000000055511151231257827021181583404541015625'). (Implemented by Raymond Hettinger; bpo-4796 [https://bugs.python.org/issue?@action=redirect&bpo=4796].)

Comparing instances of 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 Decimal and floating-point in other operations such as addition, since you should be explicitly choosing how to convert between float and Decimal. (Fixed by Mark Dickinson; bpo-2531 [https://bugs.python.org/issue?@action=redirect&bpo=2531].)

Decimal のコンストラクタが浮動小数点数を受け入れるようになりました。 (added by Raymond Hettinger; bpo-8257 [https://bugs.python.org/issue?@action=redirect&bpo=8257]) また、アラビア・インド数字などの、ヨーロッパ以外の Unicode 文字も受け入れるようになりました。 (contributed by Mark Dickinson; bpo-6595 [https://bugs.python.org/issue?@action=redirect&bpo=6595]).

Context クラスのほとんどのメソッドが Decimal インスタンスと同じく整数を受け入れるようになりました。例外は canonical() と is_canonical() メソッドだけです。 (Patch by Juan José Conti; bpo-7633 [https://bugs.python.org/issue?@action=redirect&bpo=7633].)

Decimal インスタンスを文字列の format() メソッドで利用した場合、デフォルトのアライメントが左揃えから、数値型に適した右揃えに変更されました。 (Changed by Mark Dickinson; bpo-6857 [https://bugs.python.org/issue?@action=redirect&bpo=6857].)

signaling NaN (あるいは sNAN) との比較は、暗黙に比較演算に応じて真偽値を返すのではなく、 InvalidOperation 例外を発生させるようになりました。 Quiet NaN (あるいは NAN) はハッシュ可能になりました。 (Fixed by Mark Dickinson; bpo-7279 [https://bugs.python.org/issue?@action=redirect&bpo=7279].)

difflib モジュールの出力が、ファイル名を含むヘッダのセパレータにスペースではなくタブ文字を使うようになり、最近の diff/patch ツールとの互換性が高くなりました。(Fixed by Anatoly Techtonik; bpo-7585 [https://bugs.python.org/issue?@action=redirect&bpo=7585].)

Distutils sdist コマンドが、 MANIFEST.in や setup.py ファイルが変更されていなくても、ユーザーが作成したかもしれない新しいファイルが含まれるようにするために、毎回 MANIFEST ファイルを再生成するようになりました。 (Fixed by Tarek Ziadé; bpo-8688 [https://bugs.python.org/issue?@action=redirect&bpo=8688].)

The doctest module's IGNORE_EXCEPTION_DETAIL flag will now ignore the name of the module containing the exception being tested. (Patch by Lennart Regebro; bpo-7490 [https://bugs.python.org/issue?@action=redirect&bpo=7490].)

The email module's Message class will now accept a Unicode-valued payload, automatically converting the payload to the encoding specified by output_charset. (Added by R. David Murray; bpo-1368247 [https://bugs.python.org/issue?@action=redirect&bpo=1368247].)

Fraction クラスが、コンストラクタの引数として、 1つの float 値、 Decimal インスタンス、 2つの有理数を受け入れるようになりました。(Implemented by Mark Dickinson; rationals added in bpo-5812 [https://bugs.python.org/issue?@action=redirect&bpo=5812], and float/decimal in bpo-8294 [https://bugs.python.org/issue?@action=redirect&bpo=8294].)

fraction と complex 数の間の順序比較演算 (<, <=, >, >=)が TypeError 例外を発生させるようになりました。これは過失を修正し、 Fraction を他の数値型とマッチさせます。

新しいクラス: FTP_TLS が ftplib に追加されました。認証とその後の制御・データ転送をTLSカプセル化することでセキュアなFTP接続を提供します。 (Contributed by Giampaolo Rodola; bpo-2054 [https://bugs.python.org/issue?@action=redirect&bpo=2054].)

バイナリデータのアップロードを行う storbinary() に rest 引数が追加され、アップロードのリスタートができるようになりました。 (patch by Pablo Mouzo; bpo-6845 [https://bugs.python.org/issue?@action=redirect&bpo=6845].)

New class decorator: total_ordering() in the functools module takes a class that defines an __eq__() method and one of __lt__(), __le__(), __gt__(), or __ge__(), and generates the missing comparison methods. Since the __cmp__() method is being deprecated in Python 3.x, this decorator makes it easier to define ordered classes. (Added by Raymond Hettinger; bpo-5479 [https://bugs.python.org/issue?@action=redirect&bpo=5479].)

新しい関数: cmp_to_key() 関数は、古いスタイルの2引数を受け取る比較関数を受け取り、 sorted(), min(), max() などの key 引数に利用できる呼び出し可能オブジェクトを返します。この関数の主な目的は、古いコードを Python 3.x へ対応させるのを手助けすることです。(Added by Raymond Hettinger.)

新しい関数: gc モジュールに is_tracked() 関数が追加されました。渡されたオブジェクトがGCに追跡されている場合に True を、そうでない場合に False を返します。 (Contributed by Antoine Pitrou; bpo-4688 [https://bugs.python.org/issue?@action=redirect&bpo=4688].)

gzip モジュールの GzipFile がコンテキストマネージャープロトコルをサポートしました。 with gzip.GzipFile(...) as f: と書くことができます。(contributed by Hagen Fürstenau; bpo-3860 [https://bugs.python.org/issue?@action=redirect&bpo=3860] また、 io.BufferedIOBase ABC を実装しています。なので、より高速な処理のために io.BufferedReader でラップすることができます。 (contributed by Nir Aides; bpo-7471 [https://bugs.python.org/issue?@action=redirect&bpo=7471]). さらに、コンストラクタにオプションのタイムスタンプを指定することで、 gzip ファイル内の変更時間レコードをオーバーライドすることができるようになりました。 (Contributed by Jacques Frechet; bpo-4272 [https://bugs.python.org/issue?@action=redirect&bpo=4272].)

gzip ファイルフォーマットのファイルは最後にゼロバイトによるパディングができるようになりました。 gzip モジュールは末尾のゼロバイトを消費します。(Fixed by Tadek Pietraszek and Brian Curtin; bpo-2846 [https://bugs.python.org/issue?@action=redirect&bpo=2846].)

New attribute: the hashlib module now has an algorithms attribute containing a tuple naming the supported algorithms. In Python 2.7, hashlib.algorithms contains ('md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512'). (Contributed by Carl Chenet; bpo-7418 [https://bugs.python.org/issue?@action=redirect&bpo=7418].)

The default HTTPResponse class used by the httplib module now supports buffering, resulting in much faster reading of HTTP responses. (Contributed by Kristján Valur Jónsson; bpo-4879 [https://bugs.python.org/issue?@action=redirect&bpo=4879].)

The HTTPConnection and HTTPSConnection classes now support a source_address parameter, a (host, port) 2-tuple giving the source address that will be used for the connection. (Contributed by Eldon Ziegler; bpo-3972 [https://bugs.python.org/issue?@action=redirect&bpo=3972].)

The ihooks module now supports relative imports. Note that ihooks is an older module for customizing imports, superseded by the imputil module added in Python 2.0. (Relative import support added by Neil Schemenauer.)

imaplib モジュールが IPv6 アドレスをサポートするようになりました。 (Contributed by Derek Morr; bpo-1655 [https://bugs.python.org/issue?@action=redirect&bpo=1655].)

inspect モジュールに getcallargs() 関数が追加されました。 callable とその位置引数、キーワード引数を受け取り、 callable のどの仮引数がどの実引数を受け取るかを計算し、引数名から値へマップする辞書を返します。例えば:

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

Contributed by George Sakkis; bpo-3135 [https://bugs.python.org/issue?@action=redirect&bpo=3135].

Updated module: The 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 _pyio module.

One minor resulting change: the io.TextIOBase class now has an errors attribute giving the error setting used for encoding and decoding errors (one of 'strict', 'replace', 'ignore').

io.FileIO クラスは、無効なファイルディスクリプタを渡されたときに OSError を送出するようになりました。(Implemented by Benjamin Peterson; bpo-4991 [https://bugs.python.org/issue?@action=redirect&bpo=4991].) truncate() メソッドは、ファイル位置を保存するようになりました。以前は、ファイル位置を新しいファイルの末尾に変更しました。(Fixed by Pascal Chambon; bpo-6939 [https://bugs.python.org/issue?@action=redirect&bpo=6939].)

新しい関数: itertools.compress(data, selectors) は、2 つのイテレータを取ります。data の要素は、selectors の対応する値が真であれば返されます:

itertools.compress('ABCDEF', [1,0,1,0,1,1]) =>
  A, C, E, F

新しい関数: itertools.combinations_with_replacement(iter, r) は、 iter から、すべての可能な長さ r の要素の組合せを返します。 combinations() とは異なり、生成された組合せに個別の要素が繰り返し出現できます:

itertools.combinations_with_replacement('abc', 2) =>
  ('a', 'a'), ('a', 'b'), ('a', 'c'),
  ('b', 'b'), ('b', 'c'), ('c', 'c')

なお要素は、実際の値ではなく、その入力内での位置に依って一意であるとみなされます。

itertools.count() 関数は、1 以外の値を増分できるように、 step 引数を追加しました。 count() はまた、キーワード引数に対応し、さらに浮動小数点数や Decimal インスタンスのような、非整数の値を使えるようになりました。(Implemented by Raymond Hettinger; bpo-5032 [https://bugs.python.org/issue?@action=redirect&bpo=5032].)

itertools.combinations() および itertools.product() は、以前は入力のイテレート可能オブジェクトより大きい r に ValueError を返していました。これは仕様エラーと認められ、空のイテレータを返すようになりました。(Fixed by Raymond Hettinger; bpo-4816 [https://bugs.python.org/issue?@action=redirect&bpo=4816].)

更新されたモジュール: json モジュールが、エンコーディングやデコーディングを高速化する C 拡張を含んだ、 simplejson パッケージのバージョン 2.0.9 にアップグレードされました。 (Contributed by Bob Ippolito; bpo-4136 [https://bugs.python.org/issue?@action=redirect&bpo=4136].)

新しい collections.OrderedDict 型をサポートするために、 json.load() はオプションとして、任意のオブジェクトリテラルに対して呼び出され、ペアのリストにデコードする object_pairs_hook パラメタを追加しました。(Contributed by Raymond Hettinger; bpo-5381 [https://bugs.python.org/issue?@action=redirect&bpo=5381].)

mailbox モジュールの Maildir クラスは、読み込むディレクトリのタイムスタンプを記録し、その後に更新時刻が変わった場合にのみ再読み込みするようになりました。これは不必要なディレクトリ走査を避けることでパフォーマンスを向上させます。(Fixed by A.M. Kuchling and Antoine Pitrou; bpo-1607951 [https://bugs.python.org/issue?@action=redirect&bpo=1607951], bpo-6896 [https://bugs.python.org/issue?@action=redirect&bpo=6896].)

新しい関数: math モジュールは、誤差関数と相補誤差関数 erf() および erfc() 、 e**x - 1 を exp() から 1 を引くのよりも高い精度で計算する expm1() 、ガンマ関数 gamma() 、そしてガンマ関数の自然対数 lgamma() を追加しました。 (Contributed by Mark Dickinson and nirinA raseliarison; bpo-3366 [https://bugs.python.org/issue?@action=redirect&bpo=3366].)

The multiprocessing module's 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 [https://bugs.python.org/issue?@action=redirect&bpo=5585].)

The 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 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 [https://bugs.python.org/issue?@action=redirect&bpo=6963].)

The nntplib module now supports IPv6 addresses. (Contributed by Derek Morr; bpo-1664 [https://bugs.python.org/issue?@action=redirect&bpo=1664].)

新しい関数: os モジュールは、以下の POSIX システムコールをラップします: real, effective, および saved GID と UID を返す、 getresgid() と getresuid() 、 real, effective, および saved GID と UID を新しく設定する、 setresgid() と setresuid() 、現在のプロセスにグループアクセスリストを初期化する initgroups() 。 (GID/UID functions contributed by Travis H.; bpo-6508 [https://bugs.python.org/issue?@action=redirect&bpo=6508]. Support for initgroups added by Jean-Paul Calderone; bpo-7333 [https://bugs.python.org/issue?@action=redirect&bpo=7333].)

os.fork() 関数は、子プロセス中で import ロックを再初期化するようになりました。これは、Solaris における fork() がスレッドから呼び出された時の問題を修正します。(Fixed by Zsolt Cserna; bpo-7242 [https://bugs.python.org/issue?@action=redirect&bpo=7242].)

os.path モジュールの、 normpath() および abspath() 関数は、Unicode を保存するようになりました。入力パスが Unicode なら、戻り値も Unicode 文字列になります。 (normpath() fixed by Matt Giuca in bpo-5827 [https://bugs.python.org/issue?@action=redirect&bpo=5827]; abspath() fixed by Ezio Melotti in bpo-3426 [https://bugs.python.org/issue?@action=redirect&bpo=3426].)

pydoc モジュールは、Python が使う様々なシンボルのヘルプを追加しました。例えば、 help('<<') や help('@') とできるようになりました。(Contributed by David Laban; bpo-4739 [https://bugs.python.org/issue?@action=redirect&bpo=4739].)

re モジュールの split(), sub(), および subn() は、モジュールの他の関数との一貫性のため、オプションの flags 引数を受け付けるようになりました。 (Added by Gregory P. Smith.)

新しい関数: runpy モジュールの run_path() は、与えられた path 引数のコードを実行します。 path は Python ソースファイルのパス (example.py)、コンパイル済みバイトコードファイル (example.pyc)、ディレクトリ (./package/)、または zip アーカイブ (example.zip) にできます。ディレクトリか zip パスが与えられると、それが sys.path の最初に加えられ、モジュール __main__ が import されます。これは、ディレクトリや zip が __main__.py を含むことを期待します。なければ、他の __main__.py が sys.path の後の部分から import されることがあります。これにより、Python のコマンドラインが明示的なパス名を処理する方法を真似たいようなスクリプトに、 runpy のより多くの機構が利用できるようになります。 (Added by Nick Coghlan; bpo-6816 [https://bugs.python.org/issue?@action=redirect&bpo=6816].)

新しい関数: shutil モジュールの make_archive() は、ファイル名、アーカイブ型 (zip または tar-format)、およびディレクトリパスを取って、そのディレクトリの内容を含むアーカイブを生成します。(Added by Tarek Ziadé.)

shutil の copyfile() および copytree() 関数は、名前付きパイプのコピーを求められたときに SpecialFileError 例外を送出する様になりました。以前は、コードは、名前付きパイプを、通常のファイルのように読み込み用に開いて扱い、いつまでもブロックしていました。 (Fixed by Antoine Pitrou; bpo-3002 [https://bugs.python.org/issue?@action=redirect&bpo=3002].)

signal モジュールは、シグナルハンドラを本当に必要でない限り再インストールしなくなりました。これで、EINTR シグナルを確実に捕えられないバグが修正されました。(Fixed by Charles-Francois Natali; bpo-8354 [https://bugs.python.org/issue?@action=redirect&bpo=8354].)

新しい関数: site モジュールの、新しい関数群は様々なサイトおよびユーザに特有のパスを返します。 getsitepackages() は、全てのグローバル site-packages ディレクトリを含むリストを返します。 getusersitepackages() は、ユーザの site-packages ディレクトリのパスを返します。そして、 getuserbase() は、データの保存に使えるディレクトリへのパスを与える、 USER_BASE 環境変数の値を返します。 (Contributed by Tarek Ziadé; bpo-6693 [https://bugs.python.org/issue?@action=redirect&bpo=6693].)

site モジュールは sitecustomize モジュールが import されたときに例外を報告するようになり、 KeyboardInterrupt 例外が捕捉されて飲み込まれることはなくなりました。 (Fixed by Victor Stinner; bpo-3137 [https://bugs.python.org/issue?@action=redirect&bpo=3137].)

create_connection() 関数は、接続に使われるソースアドレスを与える (host, port) の 2-タプル、 source_address パラメタを追加しました。 (Contributed by Eldon Ziegler; bpo-3972 [https://bugs.python.org/issue?@action=redirect&bpo=3972].)

recv_into() および recvfrom_into() メソッドは、バッファ API をサポートするオブジェクト、最も便利なのは bytearray や memoryview 、に書きこむようになりました。 (Implemented by Antoine Pitrou; bpo-8104 [https://bugs.python.org/issue?@action=redirect&bpo=8104].)

The SocketServer module's TCPServer class now supports socket timeouts and disabling the Nagle algorithm. The disable_nagle_algorithm class attribute defaults to 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 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, handle_timeout() will be called and handle_request() will return. (Contributed by Kristján Valur Jónsson; bpo-6192 [https://bugs.python.org/issue?@action=redirect&bpo=6192] and bpo-6267 [https://bugs.python.org/issue?@action=redirect&bpo=6267].)

更新されたモジュール: sqlite3 モジュールが pysqlite パッケージ [https://github.com/ghaering/pysqlite] のバージョン 2.6.0 にアップデートされました。バージョン 2.6.0 はいくつかのバグ修正を含み、共有ライブラリから SQLite 拡張をロードできるようになりました。拡張を有効にするには enable_load_extension(True) メソッドを呼び出し、そして特定の共有ライブラリをロードするには load_extension() を呼び出してください。 (Updated by Gerhard Häring.)

The ssl module's SSLSocket objects now support the buffer API, which fixed a test suite failure (fix by Antoine Pitrou; bpo-7133 [https://bugs.python.org/issue?@action=redirect&bpo=7133]) and automatically set OpenSSL's SSL_MODE_AUTO_RETRY, which will prevent an error code being returned from recv() operations that trigger an SSL renegotiation (fix by Antoine Pitrou; bpo-8222 [https://bugs.python.org/issue?@action=redirect&bpo=8222]).

The 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 [https://www.openssl.org/docs/man1.0.2/man1/ciphers.html]. (Added by Antoine Pitrou; bpo-8322 [https://bugs.python.org/issue?@action=redirect&bpo=8322].)

その他の変更により、拡張はOpenSSL の全ての暗号とメッセージダイジェストアルゴリズムをロードし、それらすべてが利用できるようにします。SSL 証明書の中には検証できないものもあり、"unknown algorithm" エラーを報告します。 (Reported by Beda Kosata, and fixed by Antoine Pitrou; bpo-8484 [https://bugs.python.org/issue?@action=redirect&bpo=8484].)

The version of OpenSSL being used is now available as the module attributes ssl.OPENSSL_VERSION (a string), ssl.OPENSSL_VERSION_INFO (a 5-tuple), and ssl.OPENSSL_VERSION_NUMBER (an integer). (Added by Antoine Pitrou; bpo-8321 [https://bugs.python.org/issue?@action=redirect&bpo=8321].)

The struct module will no longer silently ignore overflow errors when a value is too large for a particular integer format code (one of bBhHiIlLqQ); it now always raises a struct.error exception. (Changed by Mark Dickinson; bpo-1523 [https://bugs.python.org/issue?@action=redirect&bpo=1523].) The pack() function will also attempt to use __index__() to convert and pack non-integers before trying the __int__() method or reporting an error. (Changed by Mark Dickinson; bpo-8300 [https://bugs.python.org/issue?@action=redirect&bpo=8300].)

新しい関数: subprocess モジュールの check_output() は、指定された引数群でコマンドを実行し、コマンドがエラーを起こさずに実行したらコマンドの出力を文字列として返し、そうでなければ CalledProcessError 例外を送出します。

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

(Contributed by Gregory P. Smith.)

The subprocess module will now retry its internal system calls on receiving an EINTR signal. (Reported by several people; final patch by Gregory P. Smith in bpo-1068268 [https://bugs.python.org/issue?@action=redirect&bpo=1068268].)

新しい関数: symtable モジュールの is_declared_global() は、明示的に global と宣言された引数には真、暗示的に global である引数には偽を返します。(Contributed by Jeremy Hylton.)

syslog モジュールは、識別子として、以前デフォルトであった 'python' の値ではなく、 sys.argv[0] の値を使うようになりました。 (Changed by Sean Reifschneider; bpo-8451 [https://bugs.python.org/issue?@action=redirect&bpo=8451].)

The sys.version_info value is now a named tuple, with attributes named major, minor, micro, releaselevel, and serial. (Contributed by Ross Light; bpo-4285 [https://bugs.python.org/issue?@action=redirect&bpo=4285].)

sys.getwindowsversion() also returns a named tuple, with attributes named major, minor, build, platform, service_pack, service_pack_major, service_pack_minor, suite_mask, and product_type. (Contributed by Brian Curtin; bpo-7766 [https://bugs.python.org/issue?@action=redirect&bpo=7766].)

tarfile モジュールのデフォルトエラー処理が変更され、致命的なエラーを抑制しないようになりました。デフォルトのエラーレベルは以前は 0 で、エラーはメッセージとしてデバッグログに書き込まれるだけでしたが、デバッグログはデフォルトでは活性化されていないため、エラーは顧みられませんでした。デフォルトのエラーレベルは 1 になり、エラーがあれば例外が送出されます。 (Changed by Lars Gustäbel; bpo-7357 [https://bugs.python.org/issue?@action=redirect&bpo=7357].)

tarfile は、tar ファイルに追加される TarInfo オブジェクトのフィルタリングをサポートするようになりました。 add() を呼び出したとき、オプションの呼び出し可能オブジェクトである filter 引数を与えることができます。 filter オブジェクトには、ファイルが追加される度に TarInfo を渡され、これを変形して返せます。このオブジェクトが None を返したら、そのファイルは結果のアーカイブから除かれます。これは既存の exclude 引数より強力で、それゆえこれは非推奨となります。(Added by Lars Gustäbel; bpo-6856 [https://bugs.python.org/issue?@action=redirect&bpo=6856].) TarFile クラスはまた、コンテキストマネージャプロトコルもサポートするようになりました。(Added by Lars Gustäbel; bpo-7232 [https://bugs.python.org/issue?@action=redirect&bpo=7232].)

threading.Event クラスの wait() メソッドは、終了時に内部フラグを返すようになりました。 wait() は内部フラグが真になるまでブロックすることを想定されているため、この関数は通常真を返すことになります。この戻り値は、タイムアウトが与えられ、オペレーションがタイムアウトした時のみ偽になります。 (Contributed by Tim Lesher; bpo-1674032 [https://bugs.python.org/issue?@action=redirect&bpo=1674032].)

unicodedata モジュールに提供される Unicode データベースは、どの文字が数字や空白文字か、または改行を表すかを決定するために、内部で使われるようになりました。このデータベースはまた、 Unihan.txt データファイルからの情報も含みます (patch by Anders Chrigström and Amaury Forgeot d'Arc; bpo-1571184 [https://bugs.python.org/issue?@action=redirect&bpo=1571184])。また、バージョン 5.2.0 にアップデートされました (updated by Florent Xicluna; bpo-8024 [https://bugs.python.org/issue?@action=redirect&bpo=8024])。

The urlparse module's urlsplit() now handles unknown URL schemes in a fashion compliant with RFC 3986 [https://datatracker.ietf.org/doc/html/rfc3986.html]: if the URL is of the form "<something>://...", the text before the :// 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:

>>> import urlparse
>>> urlparse.urlsplit('invented://host/filename?query')
('invented', '', '//host/filename?query', '', '')

Python 2.7 (や Python 2.6.5) は以下を返します:

>>> import urlparse
>>> urlparse.urlsplit('invented://host/filename?query')
('invented', 'host', '/filename?query', '', '')

(Python 2.7 では、これは普通のタプルではなく名前付きタプルを返すので、実際は微妙に異なる出力をします。)

The urlparse module also supports IPv6 literal addresses as defined by RFC 2732 [https://datatracker.ietf.org/doc/html/rfc2732.html] (contributed by Senthil Kumaran; bpo-2987 [https://bugs.python.org/issue?@action=redirect&bpo=2987]).

>>> urlparse.urlparse('http://[1080::8:800:200C:417A]/foo')
ParseResult(scheme='http', netloc='[1080::8:800:200C:417A]',
            path='/foo', params='', query='', fragment='')

新しいクラス: weakref モジュールの WeakSet クラスは、その要素の弱参照だけを保持する集合です。要素は、それを指す参照がなくなり次第除去されます。 (Originally implemented in Python 3.x by Raymond Hettinger, and backported to 2.7 by Michael Foord.)

The xml.etree.ElementTree library, no longer escapes ampersands and angle brackets when outputting an XML processing instruction (which looks like <?xml-stylesheet href="#style1"?>) or comment (which looks like <!-- comment -->). (Patch by Neil Muller; bpo-2746 [https://bugs.python.org/issue?@action=redirect&bpo=2746].)

The XML-RPC client and server, provided by the xmlrpclib and 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 encode_threshold attribute of SimpleXMLRPCRequestHandler, which contains a size in bytes; responses larger than this will be compressed. (Contributed by Kristján Valur Jónsson; bpo-6267 [https://bugs.python.org/issue?@action=redirect&bpo=6267].)

zipfile モジュールの ZipFile は、コンテキストマネジメントプロトコルをサポートし、 with zipfile.ZipFile(...) as f: と書けるようになりました。 (Contributed by Brian Curtin; bpo-5511 [https://bugs.python.org/issue?@action=redirect&bpo=5511].)

zipfile now also supports archiving empty directories and extracts them correctly. (Fixed by Kuba Wieczorek; bpo-4710 [https://bugs.python.org/issue?@action=redirect&bpo=4710].) Reading files out of an archive is faster, and interleaving read() and readline() now works correctly. (Contributed by Nir Aides; bpo-7610 [https://bugs.python.org/issue?@action=redirect&bpo=7610].)

is_zipfile() 関数は、以前受け付けられていたパス名に加え、ファイルオブジェクトも受け付けるようになりました。 (Contributed by Gabriel Genellina; bpo-4756 [https://bugs.python.org/issue?@action=redirect&bpo=4756].)

writestr() メソッドは、 ZipFile コンストラクタで指定されたデフォルトの圧縮メソッドをオーバライドする、オプションの compress_type パラメタを追加しました。 (Contributed by Ronald Oussoren; bpo-6003 [https://bugs.python.org/issue?@action=redirect&bpo=6003].)

新しいモジュール: importlib

Python 3.1 は、根底の Python の import 文のロジックの最実装である importlib パッケージを含みます。 importlib は、Python インタプリタの実装者や、import プロセスに関与する新しいインポータを書きたいと願うユーザにとって便利です。 Python 2.7 は importlib パッケージを完全には含みませんが、代わりに 1 つの関数 import_module() を含む小さなサブセットがあります。

import_module(name, package=None) はモジュールを import します。 name はモジュールまたはパッケージの名前を含む文字列です。 ..utils.errors のように . 文字で始まる文字列を与えることで、相対 import も可能です。相対 import では、 package 引数は必ず与えられなければならず、相対 import のアンカーとして使われるパッケージの名前でなければなりません。 import_module() は、 import されたモジュールを sys.modules に挿入し、モジュールオブジェクトを返すこともします。

ここに例があります:

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

importlib は、Brett Cannon によって実装され、 Python 3.1 に導入されました。

新しいモジュール: sysconfig

sysconfig モジュールが Distutils パッケージから引き抜かれ、新しいトップレベルモジュールになりました。 sysconfig は、Python のビルドプロセスについての以下の情報を得るための関数群を提供しています。コンパイラスイッチ、インストレーションパス、プラットフォーム名、そして Python がソースディレクトリから実行されているかどうかです。

モジュールの関数のいくつかを紹介すると:

get_config_var() は、Python の Makefile と pyconfig.h ファイルから変数を返します。

get_config_vars() は、すべての環境設定変数を含む辞書を返します。

get_path() は、特定のタイプのモジュール、つまり標準ライブラリ、サイト特有のモジュール、プラットフォーム特有のライブフラリなど、への設定されたパスを返します。

is_python_build() は、Python ソースツリーからバイナリを起動していれば真を、そうでなければ偽を返します。

詳細と関数の完全な一覧は sysconfig ドキュメントを参照してください。

Distutils パッケージと sysconfig は Tarek Ziadé によってメンテナンスされていて、彼は Distutils の新世代版を開発するために Distutils2 パッケージ (source repository at https://hg.python.org/distutils2/) も開始しました。

ttk: Tk のテーマ付きウィジェット

Tcl/Tk 8.5 は、基本的な Tk ウィジェットを最実装しながらより自由な外観のカスタマイズが広がり、よりネイティブなプラットフォームのウィジェットに似たテーマ付きウィジェット群を含みます。このウィジェット群は、元は Tile と呼ばれていましたが、Tcl/Tck リリース 8.5 への追加の際に ("themed Tk" を略して) Ttk に改名されました。

To learn more, read the ttk module documentation. You may also wish to read the Tcl/Tk manual page describing the Ttk theme engine, available at https://www.tcl.tk/man/tcl8.5/TkCmd/ttk_intro.html. Some screenshots of the Python/Ttk code in use are at https://code.google.com/archive/p/python-ttk/wikis/Screenshots.wiki.

The tkinter.ttk module was written by Guilherme Polo and added in bpo-2983 [https://bugs.python.org/issue?@action=redirect&bpo=2983]. An alternate version called Tile.py, written by Martin Franklin and maintained by Kevin Walzer, was proposed for inclusion in bpo-2618 [https://bugs.python.org/issue?@action=redirect&bpo=2618], but the authors argued that Guilherme Polo's work was more comprehensive.

更新されたモジュール: unittest

The 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 unittest2 package, from unittest2 [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 [https://pytest.org] or nose [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 test/ subdirectory for any importable test files named test*.py:

python -m unittest discover -s test

詳細は、 unittest モジュールのドキュメントを参照してください。 (Developed in bpo-6001 [https://bugs.python.org/issue?@action=redirect&bpo=6001].)

main() 関数は、その他幾つかの新しいオプションを提供します:

-b や --buffer は、標準出力や標準エラーストリームをそれぞれのテストの間バッファに入れます。テストが通れば、結果の出力は全て捨てられます。失敗したら、バッファに入れられた出力が表示されます。

-c や --catch は、control-C による中断をより上品にします。テストプロセスを即座に中断するのではなく、現在実行中のテストは完了させ、中断までの部分的な結果は報告されます。待ちきれなければ、control-C をもう一度押せば、即座に中断されます。

この control-C ハンドラは、コードがテストされているときや、実行されているテストが独自のシグナルハンドラを定義したとき、シグナルハンドラがすでに設定されていてそして呼び出されたということを知らせることで、問題を起こさないようにします。これがまずいなら、 removeHandler() デコレータを使って、テストが control-C ハンドリングを無効にするべきであると示せます。

-f や --failfast は、テストが失敗したとき、他のテストを続けるのではなく、テストの実行を即座に停止します。 (Suggested by Cliff Dyer and implemented by Michael Foord; bpo-8074 [https://bugs.python.org/issue?@action=redirect&bpo=8074].)

進捗メッセージは、verbose モードで実行したとき、期待された失敗に 'x' を、期待されない成功に 'u' を表示するようになりました。(Contributed by Benjamin Peterson.)

テストケースは、テストをスキップするために SkipTest 例外を送出します。(bpo-1034053 [https://bugs.python.org/issue?@action=redirect&bpo=1034053]).

assertEqual(), assertTrue(), および assertFalse() 失敗のメッセージは、提供する情報量が増えました。 TestCase クラスの longMessage 属性を真に設定すると、失敗時に、標準のエラーメッセージと追加して提供したメッセージの両方が表示されます。(Added by Michael Foord; bpo-5663 [https://bugs.python.org/issue?@action=redirect&bpo=5663].)

assertRaises() メソッドは、実行する呼び出し可能オブジェクトを与えずに呼び出されたとき、コンテキストハンドラを返すようになりました。例えば、こう書くことができます:

with self.assertRaises(KeyError):
    {}['foo']

(Implemented by Antoine Pitrou; bpo-4444 [https://bugs.python.org/issue?@action=redirect&bpo=4444].)

モジュールレベルおよびクラスレベルの設定と、ティアダウンフィクスチャがサポートされました。モジュールは、 setUpModule() および tearDownModule() 関数を含むことができます。クラスは setUpClass() および tearDownClass() メソッドを含むことができ、これらは (@classmethod や透過なものを使って) クラスメソッドとして定義しなければなりません。これらの関数とメソッドは、テストランナーが別のモジュールやクラスのテストケースに切り替えるときに呼び出されます。

メソッド addCleanup() および doCleanups() が追加されました。 addCleanup() で、無条件に呼び出されるクリーンアップ関数を (setUp() が失敗したら setUp() の後に、そうでなければ tearDown() の後に) 追加できるようにします。これにより、テスト中のリソースの配置と解放が簡潔になります。(bpo-5679 [https://bugs.python.org/issue?@action=redirect&bpo=5679]).

より特化したテストを提供するメソッドがいくつか追加されました。これらのメソッドの多くは、Google のエンジニアたちによってそのテストスイートのために書かれました。Gregory P. Smith, Michael Foord, and GvR が、これを unittest の Python 版にマージしました。

assertIsNone() および assertIsNotNone() はひとつの式を取り、その結果が None であるか、またはないかを確かめます。

assertIs() および assertIsNot() は、2 つの値を取り、その評価が同一のオブジェクトであるか、またはないかを確かめます。 (Added by Michael Foord; bpo-2578 [https://bugs.python.org/issue?@action=redirect&bpo=2578].)

assertIsInstance() および assertNotIsInstance() は、結果のオブジェクトが特定のクラス、またはタプルにあるクラスのいずれかのインスタンスであるかを調べます。(Added by Georg Brandl; bpo-7031 [https://bugs.python.org/issue?@action=redirect&bpo=7031].)

assertGreater(), assertGreaterEqual(), assertLess(), および assertLessEqual() は、二つの量を比較します。

assertMultiLineEqual() は 2 つの文字列を比較し、等しくなければ、2 文字列の差分をハイライトする有益な比較を表示します。この比較は、Unicode 文字列が assertEqual() で比較されるときのデフォルトに使われるようになりました。

assertRegexpMatches() and assertNotRegexpMatches() checks whether the first argument is a string matching or not matching the regular expression provided as the second argument (bpo-8038 [https://bugs.python.org/issue?@action=redirect&bpo=8038]).

assertRaisesRegexp() checks whether a particular exception is raised, and then also checks that the string representation of the exception matches the provided regular expression.

assertIn() および assertNotIn() は、 first が second に属するか、または属さないかを調べます。

assertItemsEqual() tests whether two provided sequences contain the same elements.

assertSetEqual() は、2 つの集合が等しいか比較し、エラーの場合のみ、集合間の差分を報告します。

同様に、 assertListEqual() および assertTupleEqual() は、指定された型を比較し、差分を説明しますが、完全な値を表示するとはかぎりません。これらのメソッドは、リストやタプルを assertEqual() で比較するときにデフォルトで使われるようになりました。より一般的には、 assertSequenceEqual() は 2 つのシーケンスを比較し、必要なら両方のシーケンスが特定の型であるかを調べます。

assertDictEqual() compares two dictionaries and reports the differences; it's now used by default when you compare two dictionaries using assertEqual(). assertDictContainsSubset() checks whether all of the key/value pairs in first are found in second.

assertAlmostEqual() and 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.

loadTestsFromName() は、 TestLoader の suiteClass 属性を適切に受け入れます。(Fixed by Mark Roddy; bpo-6866 [https://bugs.python.org/issue?@action=redirect&bpo=6866].)

新しいフックにより、 assertEqual() メソッドを拡張して新しいデータ型を扱わせられます。 addTypeEqualityFunc() メソッドは型オブジェクトと関数を取ります。この関数は、比較される両方のオブジェクトが特定の型であるときに使われます。この関数は、2 つのオブジェクトを比較し、マッチしなければ例外を送出するべきです。この関数が、新しいシーケンス比較メソッドがするように、2 つのオブジェクトがなぜマッチしないのかについて追加の情報を提供するのがいいアイデアです。

unittest.main() はオプションの exit 引数を取るようになりました。偽の場合、 main() は sys.exit() を呼び出さず、これにより対話型インタプリタから main() が使えるようになります。(Contributed by J. Pablo Fernández; bpo-3379 [https://bugs.python.org/issue?@action=redirect&bpo=3379].)

TestResult に、テストランの直前と直後に呼び出される startTestRun() および stopTestRun() が追加されました。 (Contributed by Robert Collins; bpo-5728 [https://bugs.python.org/issue?@action=redirect&bpo=5728].)

これら一連の変更により、 unittest.py は無様に大きくなったので、モジュールはパッケージとなり、コードは複数のファイルに分割されました (by Benjamin Peterson)。これは、モジュールをインポートして使う方法には影響しません。

参考

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

更新されたモジュール: ElementTree 1.3

Python に同梱される ElementTree ライブラリのバージョンが、バージョン 1.3 にアップデートされました。新機能の一部は:

様々な解析関数が、使われる XMLParser インスタンスを与える parser キーワード引数を取るようになりました。これにより、ファイルの内部エンコーディングをオーバーライドできるようになりました:

p = ET.XMLParser(encoding='utf-8')
t = ET.XML("""<root/>""", parser=p)

Errors in parsing XML now raise a ParseError exception, whose instances have a position attribute containing a (line, column) tuple giving the location of the problem.

ElementTree's code for converting trees to a string has been significantly reworked, making it roughly twice as fast in many cases. The ElementTree.write() and Element.write() methods now have a method parameter that can be "xml" (the default), "html", or "text". HTML mode will output empty elements as <empty></empty> instead of <empty/>, and text mode will skip over elements and only output the text chunks. If you set the tag attribute of an element to 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.

名前空間の操作も改善されました。すべての xmlns:<whatever> 宣言は、結果の XML に散らばるのではなく、ルート要素に出力されます。 default_namespace 属性を設定することでデフォルトの名前空間を設定でき、 register_namespace() で新しい接頭辞を登録できます。XML モードでは、XML 宣言を抑制するために真/偽の xml_declaration パラメタを使えます。

新しい Element メソッド: extend() はシーケンスから項目の子に要素を追加します。要素それ自体はシーケンスのように振る舞うので、子をある要素から別の要素に移すのが簡単です:

from xml.etree import ElementTree as ET

t = ET.XML("""<list>
  <item>1</item> <item>2</item>  <item>3</item>
</list>""")
new = ET.XML('<root/>')
new.extend(t)

# Outputs <root><item>1</item>...</root>
print ET.tostring(new)

New Element method: iter() yields the children of the element as a generator. It's also possible to write for child in elem: to loop over an element's children. The existing method getiterator() is now deprecated, as is getchildren() which constructs and returns a list of children.

New Element method: itertext() yields all chunks of text that are descendants of the element. For example:

t = ET.XML("""<list>
  <item>1</item> <item>2</item>  <item>3</item>
</list>""")

# Outputs ['\n  ', '1', ' ', '2', '  ', '3', '\n']
print list(t.itertext())

非推奨: 要素をブール値として使う (すなわち、 if elem:) と、要素が子を持てば真を、子を持たなければ偽を返します。この振る舞いは紛らわしいです -- None は偽、では子を持たない要素は? -- ですから、 FutureWarning を引き起こすようになりました。コードでは、明示するべきです。子の数に興味があるなら len(elem) != 0 と、または elem is not None と書いてください。

Fredrik Lundh develops ElementTree and produced the 1.3 version; you can read his article describing 1.3 at 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 [https://bugs.python.org/issue?@action=redirect&bpo=6472].)

ビルドならびに C API の変更

Python のビルド過程と C API の変更は以下の通りです:

The latest release of the GNU Debugger, GDB 7, can be scripted using Python [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 P-gdb.py and automatically read it. Dave Malcolm contributed a python-gdb.py that adds a number of commands useful when debugging Python itself. For example, py-up and py-down go up or down one Python stack frame, which usually corresponds to several C stack frames. py-print prints the value of a Python variable, and py-bt prints the Python stack trace. (Added as a result of bpo-8032 [https://bugs.python.org/issue?@action=redirect&bpo=8032].)

Python に備え付けの .gdbinit ファイルを使うと、デバッグされているスレッドが GIL をほじしていないとき、2.7 バージョンの "pyo" マクロが正常に動くようになりました。このマクロは、表示の前にこれを取得するようになりました。 (Contributed by Victor Stinner; bpo-3632 [https://bugs.python.org/issue?@action=redirect&bpo=3632].)

Py_AddPendingCall() はスレッドセーフになり、ワーカスレッドがメイン Python スレッドに通知を投入することができるようになりました。これは特に、非同時性の IO 処理に便利です。(Contributed by Kristján Valur Jónsson; bpo-4293 [https://bugs.python.org/issue?@action=redirect&bpo=4293].)

New function: 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 PyCode_New(), which had many more arguments. (Added by Jeffrey Yasskin.)

新しい関数: PyErr_NewExceptionWithDoc() は、既存の PyErr_NewException() と同じように新しい例外クラスを生成しますが、新しい例外クラスの docstring を含む、追加の char * 引数を取ります。(Added by 'lekma' on the Python bug tracker; bpo-7033 [https://bugs.python.org/issue?@action=redirect&bpo=7033].)

新しい関数: PyFrame_GetLineNumber() はフレームオブジェクトを取り、そのフレームが現在実行している行番号を返します。以前は、コードは現在実行しているバイトコード命令のインデクスを得て、それからそのアドレスに対応する行番号を探索する必要がありました。(Added by Jeffrey Yasskin.)

New functions: PyLong_AsLongAndOverflow() and 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 [https://bugs.python.org/issue?@action=redirect&bpo=7528] and bpo-7767 [https://bugs.python.org/issue?@action=redirect&bpo=7767].)

New function: stemming from the rewrite of string-to-float conversion, a new PyOS_string_to_double() function was added. The old PyOS_ascii_strtod() and PyOS_ascii_atof() functions are now deprecated.

New function: PySys_SetArgvEx() sets the value of sys.argv and can optionally update sys.path to include the directory containing the script named by 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, PySys_SetArgv(), would always update 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 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 PySys_SetArgv() and carefully consider whether the application should be using PySys_SetArgvEx() with updatepath set to false.

Security issue reported as CVE-2008-5983 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2008-5983]; discussed in bpo-5753 [https://bugs.python.org/issue?@action=redirect&bpo=5753], and fixed by Antoine Pitrou.

新しいマクロ: Python ヘッダファイルは、以下のマクロを定義しました: Py_ISALNUM, Py_ISALPHA, Py_ISDIGIT, Py_ISLOWER, Py_ISSPACE, Py_ISUPPER, Py_ISXDIGIT, Py_TOLOWER, および Py_TOUPPER 。これらすべての関数は、文字を分類する C の標準マクロと類似ですが、Python は文字をロケールに依らず文字を分析したいときがあるため、現在のロケール設定を無視します。(Added by Eric Smith; bpo-5793 [https://bugs.python.org/issue?@action=redirect&bpo=5793].)

Removed function: 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 [https://bugs.python.org/issue?@action=redirect&bpo=8276].)

New format codes: the PyString_FromFormat(), PyString_FromFormatV(), and PyErr_Format() functions now accept %lld and %llu format codes for displaying C's long long types. (Contributed by Mark Dickinson; bpo-7228 [https://bugs.python.org/issue?@action=redirect&bpo=7228].)

スレッドとプロセスのフォークの間の複雑な相互関係が変更されました。以前は、 os.fork() によって生成された子プロセスは失敗していました。これは、子は動作しているスレッド 1 つだけで生成され、そのスレッドが os.fork() を処理するからです。他のスレッドが、Python のインポートロックのような、ロックを保持していたら、フォークが実行されたとき、ロックは新しいプロセスでも "held" としてマークされたままです。しかし、子プロセスでは、他のスレッドは複製されないため、ロックを解放するものは何もないので、子プロセスは import の実行を続けることができません。

Python 2.7 は、 os.fork() を実行する前に import ロックを取得し、また threading モジュールを使って生成された全てのロックをクリーンアップします。内部ロックを持っていたり、自身で fork() を呼び出したりするような C 拡張モジュールは、このクリーンアップの恩恵を受けません。

(Fixed by Thomas Wouters; bpo-1590864 [https://bugs.python.org/issue?@action=redirect&bpo=1590864].)

The Py_Finalize() function now calls the internal threading._shutdown() function; this prevents some exceptions from being raised when an interpreter shuts down. (Patch by Adam Olsen; bpo-1722344 [https://bugs.python.org/issue?@action=redirect&bpo=1722344].)

When using the PyMemberDef structure to define attributes of a type, Python will no longer let you try to delete or set a T_STRING_INPLACE attribute.

ctypes によって定義されたグローバルシンボルには、 Py または _ctypes が接頭されるようになりました。(Implemented by Thomas Heller; bpo-3102 [https://bugs.python.org/issue?@action=redirect&bpo=3102].)

New configure option: the --with-system-expat switch allows building the pyexpat module to use the system Expat library. (Contributed by Arfrever Frehtes Taifersar Arahesis; bpo-7609 [https://bugs.python.org/issue?@action=redirect&bpo=7609].)

新しい設定オプション: --with-valgrind オプションは、 Valgrind メモリエラー検出器が正しく分析するのが難しい pymalloc アロケータを無効にするようになりました。ですから Valgrind は、メモリリークやオーバーランをより検出できます。 (Contributed by James Henstridge; bpo-2422 [https://bugs.python.org/issue?@action=redirect&bpo=2422].)

新しい設定オプション: --with-dbmliborder= に空の文字列を与えて様々な DBM モジュールを全て無効にできます。 (Added by Arfrever Frehtes Taifersar Arahesis; bpo-6491 [https://bugs.python.org/issue?@action=redirect&bpo=6491].)

configure スクリプトは、ある種の 32-bit Intel チップ上の浮動小数点丸めバグを調べ、 X87_DOUBLE_ROUNDING プリプロセッサ定義を定義します。現在この定義を使うコードはありませんが、使うことを望む人がいたら使えます。(Added by Mark Dickinson; bpo-2937 [https://bugs.python.org/issue?@action=redirect&bpo=2937].)

configure はまた、C++ リンクをサポートする LDCXXSHARED Makefile を設定するようになりました。 (Contributed by Arfrever Frehtes Taifersar Arahesis; bpo-1222585 [https://bugs.python.org/issue?@action=redirect&bpo=1222585].)

ビルドプロセスは、pkg-config サポートに必要なファイルを生成するようになりました。(Contributed by Clinton Roy; bpo-3585 [https://bugs.python.org/issue?@action=redirect&bpo=3585].)

ビルドプロセスは、Subversion 1.7 をサポートするようになりました。 (Contributed by Arfrever Frehtes Taifersar Arahesis; bpo-6094 [https://bugs.python.org/issue?@action=redirect&bpo=6094].)

カプセル

Python 3.1 は、拡張モジュールに C API を提供する新しい C データ型 PyCapsule を追加しました。カプセルは、本質的には C の void * ポインタのホルダであり、モジュール属性として利用できるようになります。例えば、 socket モジュールの API は socket.CAPI として公開されていて、 unicodedata は ucnhash_CAPI を公開しています。その他の拡張はモジュールを import し、辞書にアクセスしてカプセルオブジェクトを取得し、そしてモジュールの様々な API 関数へのポインタの配列を指す void * ポインタを取得できます。

There is an existing data type already used for this, PyCObject, but it doesn't provide type safety. Evil code written in pure Python could cause a segmentation fault by taking a PyCObject from module A and somehow substituting it for the PyCObject in module B. Capsules know their own name, and getting the pointer requires providing the name:

void *vtable;

if (!PyCapsule_IsValid(capsule, "mymodule.CAPI") {
        PyErr_SetString(PyExc_ValueError, "argument type invalid");
        return NULL;
}

vtable = PyCapsule_GetPointer(capsule, "mymodule.CAPI");

vtable が期待どおりのものを指すことが保証されます。異なるカプセルが渡されたら、 PyCapsule_IsValid() は不適合な名前を検知し、偽を返します。これらのオブジェクトの使用について、より詳しい情報は、 拡張モジュールに C API を提供する を参照してください。

Python 2.7 now uses capsules internally to provide various extension-module APIs, but the PyCObject_AsVoidPtr() was modified to handle capsules, preserving compile-time compatibility with the PyCObject interface. Use of PyCObject_AsVoidPtr() will signal a PendingDeprecationWarning, which is silent by default.

Implemented in Python 3.1 and backported to 2.7 by Larry Hastings; discussed in bpo-5630 [https://bugs.python.org/issue?@action=redirect&bpo=5630].

ポート特有の変更: Windows

The msvcrt module now contains some constants from the crtassem.h header file: CRT_ASSEMBLY_VERSION, VC_ASSEMBLY_PUBLICKEYTOKEN, and LIBRARIES_ASSEMBLY_NAME_PREFIX. (Contributed by David Cournapeau; bpo-4365 [https://bugs.python.org/issue?@action=redirect&bpo=4365].)

The _winreg module for accessing the registry now implements the CreateKeyEx() and DeleteKeyEx() functions, extended versions of previously supported functions that take several extra arguments. The DisableReflectionKey(), EnableReflectionKey(), and QueryReflectionKey() were also tested and documented. (Implemented by Brian Curtin: bpo-7347 [https://bugs.python.org/issue?@action=redirect&bpo=7347].)

The new _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 [https://bugs.python.org/issue?@action=redirect&bpo=3582].)

The os.kill() function now works on Windows. The signal value can be the constants CTRL_C_EVENT, CTRL_BREAK_EVENT, or any integer. The first two constants will send Control-C and Control-Break keystroke events to subprocesses; any other value will use the TerminateProcess() API. (Contributed by Miki Tebeka; bpo-1220212 [https://bugs.python.org/issue?@action=redirect&bpo=1220212].)

os.listdir() 関数は、空のパスに対してちゃんと失敗するようになりました。 (Fixed by Hirokazu Yamamoto; bpo-5913 [https://bugs.python.org/issue?@action=redirect&bpo=5913].)

The mimetypes module will now read the MIME database from the Windows registry when initializing. (Patch by Gabriel Genellina; bpo-4969 [https://bugs.python.org/issue?@action=redirect&bpo=4969].)

ポート特有の変更: Mac OS X

追加されたパッケージを、システムインストレーションとユーザがインストールした同じバージョンのコピーで共有するために、 sys.path に /Library/Python/2.7/site-packages が追加されました。 (Changed by Ronald Oussoren; bpo-4865 [https://bugs.python.org/issue?@action=redirect&bpo=4865].)

バージョン 2.7.13 で変更: As of 2.7.13, this change was removed. /Library/Python/2.7/site-packages, the site-packages directory used by the Apple-supplied system Python 2.7 is no longer appended to 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 [https://bugs.python.org/issue?@action=redirect&bpo=28440])

ポート特有の変更: FreeBSD

FreeBSD 7.1's SO_SETFIB constant, used with the socket() methods getsockopt()/setsockopt() to select an alternate routing table, is now available in the socket module. (Added by Kyle VanderBeek; bpo-8235 [https://bugs.python.org/issue?@action=redirect&bpo=8235].)

その他の変更と修正

ベンチマークスクリプトの 2 つ、 iobench および ccbench, が Tools ディレクトリに追加されました。 iobench は、様々な演算を実行している間 open() によって返された組み込みファイル I/O オブジェクトの速度を計測し、 ccbench は、変化する数のスレッドを使っていくつかのタスクを処理するときの計算スループット、スレッド切り替えレイテンシ、IO 処理バンド幅の計測を試みる同時実行ベンチマークです。

Tools/i18n/msgfmt.py スクリプトは、複数の形式の .po ファイルを理解できるようになりました。(Fixed by Martin von Löwis; bpo-5464 [https://bugs.python.org/issue?@action=redirect&bpo=5464].)

When importing a module from a .pyc or .pyo file with an existing .py counterpart, the 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 [https://bugs.python.org/issue?@action=redirect&bpo=1180193].)

regrtest.py スクリプトは、テストを乱順に実行する -r オプションの、ランダムシードに使われる整数を取る --randseed= スイッチを取るようになりました。 -r オプションは、使われたシードも報告します。 (Added by Collin Winter.)

もう一つの regrtest.py スイッチは -j で、いくつのテストを並行して実行するかを指定する整数です。これにより、マルチコア機での合計実行時間を短縮できます。このオプションは、実行時間を長くすることで知られている -R スイッチなど、いくつかの他のオプションと互換です。 (Added by Antoine Pitrou, bpo-6152 [https://bugs.python.org/issue?@action=redirect&bpo=6152].) これはまた、選ばれたテストを失敗するまでループして実行する -F スイッチとも同時に使えます。(Added by Antoine Pitrou; bpo-7312 [https://bugs.python.org/issue?@action=redirect&bpo=7312].)

スクリプトとして実行されるとき、 py_compile.py モジュールは標準入力を読み込んでコンパイルするファイル名のリストとする '-' を引数として受け付けるようになりました。(Contributed by Piotr Ożarowski; bpo-8233 [https://bugs.python.org/issue?@action=redirect&bpo=8233].)

Python 2.7 への移植

このセクションでは前述の変更とバグフィックスにより必要となるかもしれないコードの変更を列挙します:

The range() function processes its arguments more consistently; it will now call __int__() on non-float, non-integer arguments that are supplied to it. (Fixed by Alexander Belopolsky; bpo-1533 [https://bugs.python.org/issue?@action=redirect&bpo=1533].)

文字列 format() メソッドは浮動小数点数および複素数に使われるデフォルトの精度を、 str() で使われる精度に合わせ、小数第 6 位から 12 位に変更しました。 (Changed by Eric Smith; bpo-5920 [https://bugs.python.org/issue?@action=redirect&bpo=5920].)

Because of an optimization for the with statement, the special methods __enter__() and __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 object) and C extension types. (bpo-6101 [https://bugs.python.org/issue?@action=redirect&bpo=6101].)

Due to a bug in Python 2.6, the exc_value parameter to __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 [https://bugs.python.org/issue?@action=redirect&bpo=7853].)

__slots__ を利用して属性を制限した場合に、設定されていない属性を del したときに AttributeError にならなかったのを修正しました。 (Fixed by Benjamin Peterson; bpo-7604 [https://bugs.python.org/issue?@action=redirect&bpo=7604].)

標準ライブラリでは:

年がサポートされている範囲外にはみ出るような datetime インスタンスの演算が、 OverflowError を送出しないことがありました。このようなエラーはより注意深く調べられ、例外を送出するようになりました。(Reported by Mark Leander, patch by Anand B. Pillai and Alexander Belopolsky; bpo-7150 [https://bugs.python.org/issue?@action=redirect&bpo=7150].)

Decimal インスタンスを文字列の format() メソッドに使うとき、デフォルトの揃えは以前は左揃えでした。これは右揃えに変更され、プログラムの出力が変わるかもしれません。(Changed by Mark Dickinson; bpo-6857 [https://bugs.python.org/issue?@action=redirect&bpo=6857].)

signaling NaN (あるいは sNAN) との比較は、暗黙に比較演算に応じて真偽値を返すのではなく、 InvalidOperation 例外を発生させるようになりました。 Quiet NaN (あるいは NAN) はハッシュ可能になりました。 (Fixed by Mark Dickinson; bpo-7279 [https://bugs.python.org/issue?@action=redirect&bpo=7279].)

The xml.etree.ElementTree library no longer escapes ampersands and angle brackets when outputting an XML processing instruction (which looks like <?xml-stylesheet href="#style1"?>) or comment (which looks like <!-- comment -->). (Patch by Neil Muller; bpo-2746 [https://bugs.python.org/issue?@action=redirect&bpo=2746].)

The readline() method of StringIO objects now does nothing when a negative length is requested, as other file-like objects do. (bpo-7348 [https://bugs.python.org/issue?@action=redirect&bpo=7348]).

syslog モジュールは、識別子として、以前デフォルトであった 'python' の値ではなく、 sys.argv[0] の値を使うようになりました。 (Changed by Sean Reifschneider; bpo-8451 [https://bugs.python.org/issue?@action=redirect&bpo=8451].)

tarfile モジュールのデフォルトエラー処理が変更され、致命的なエラーを抑制しないようになりました。デフォルトのエラーレベルは以前は 0 で、エラーはメッセージとしてデバッグログに書き込まれるだけでしたが、デバッグログはデフォルトでは活性化されていないため、エラーは顧みられませんでした。デフォルトのエラーレベルは 1 になり、エラーがあれば例外が送出されます。 (Changed by Lars Gustäbel; bpo-7357 [https://bugs.python.org/issue?@action=redirect&bpo=7357].)

The urlparse module's urlsplit() now handles unknown URL schemes in a fashion compliant with RFC 3986 [https://datatracker.ietf.org/doc/html/rfc3986.html]: if the URL is of the form "<something>://...", the text before the :// 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:

>>> import urlparse
>>> urlparse.urlsplit('invented://host/filename?query')
('invented', '', '//host/filename?query', '', '')

Python 2.7 (や Python 2.6.5) は以下を返します:

>>> import urlparse
>>> urlparse.urlsplit('invented://host/filename?query')
('invented', 'host', '/filename?query', '', '')

(Python 2.7 では、これは普通のタプルではなく名前付きタプルを返すので、実際は微妙に異なる出力をします。)

C 拡張では:

PyArg_Parse* 系統の関数で整数フォーマットコードを使う C 拡張は、 DeprecationWarning を引き起こすのではなく、 TypeError 例外を送出するようになりました。(bpo-5080 [https://bugs.python.org/issue?@action=redirect&bpo=5080])

Use the new PyOS_string_to_double() function instead of the old PyOS_ascii_strtod() and PyOS_ascii_atof() functions, which are now deprecated.

Python を埋め込んだアプリケーションでは:

The PySys_SetArgvEx() function was added, letting applications close a security hole when the existing PySys_SetArgv() function was used. Check whether you're calling PySys_SetArgv() and carefully consider whether the application should be using PySys_SetArgvEx() with updatepath set to false.

Python 2.7 メンテナンスリリースで追加された新機能

Python 2.7 メンテナンスリリースでは、正真正銘それが求められる状況では、新しい機能が追加される場合があります。そのような追加のどんなものでも Python Enhancement Proposal プロセスを通過しなければなりません。Python 3 だけに新しい機能を追加することによっても Python Package Index に公開することによってもいずれでも十分ではないと言えるだけのやむにやまれない理由付けが必要です。

個別の提案は以下にリストしますが、全ての Python 2.7 メンテナンスリリースに追加される新しい -3 警告は除いています。

デバッグモード用の2つの新しい環境変数

In debug mode, the [xxx refs] statistic is not written by default, the PYTHONSHOWREFCOUNT environment variable now must also be set. (Contributed by Victor Stinner; bpo-31733 [https://bugs.python.org/issue?@action=redirect&bpo=31733].)

When Python is compiled with COUNT_ALLOC defined, allocation counts are no longer dumped by default anymore: the 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 [https://bugs.python.org/issue?@action=redirect&bpo=31692].)

Added in version 2.7.15.

PEP 434: IDLE 拡張についての全てのブランチにおける例外的な扱い

PEP 434 [https://peps.python.org/pep-0434/] は、Pythonと一緒に出荷されるIDLE開発環境に変更を加えるための一般的な免除事項を説明します。これは、IDLE の開発者 が Python 2 と 3 のすべてのサポートされているバージョン間でより一貫したユーザーエクスペリエンスを提供するためのものです。

全ての IDLE の変更についての詳細は、個別のリリースについてのNEWS ファイルを参照してください。

PEP 466: Python 2.7 のためのネットワークセキュリティ拡張

PEP 466 [https://peps.python.org/pep-0466/] は、 Python 2.7 メンテナンスリリースに含めることを認められた数多くのネットワークセキュリティ強化についての提案を記述しています。それら変更の最初のものは Python 2.7.7 に初めて登場しました。

Python 2.7.7 に PEP 466 [https://peps.python.org/pep-0466/] 関連で追加された機能:

hmac.compare_digest() が Python 3 からバックポートされました。これにより Python 2 アプリケーションで timing attack resistant comparison operation が利用可能になります (Contributed by Alex Gaynor; bpo-21306 [https://bugs.python.org/issue?@action=redirect&bpo=21306].)

python.org で公開される公式 Windows インストーラのビルドに使う OpenSSL が 1.0.1g にアップグレードされました . (Contributed by Zachary Ware; bpo-21462 [https://bugs.python.org/issue?@action=redirect&bpo=21462].)

Python 2.7.8 に PEP 466 [https://peps.python.org/pep-0466/] 関連で追加された機能:

hashlib.pbkdf2_hmac() が Python 3 からバックポートされました。これにより Python 2 アプリケーションでも、安全なパスワード格納に広範に使うのに相応しいハッシュアルゴリズムが利用できます (Contributed by Alex Gaynor; bpo-21304 [https://bugs.python.org/issue?@action=redirect&bpo=21304].)

OpenSSL 1.0.1h was upgraded for the official Windows installers published on python.org. (Contributed by Zachary Ware in bpo-21671 [https://bugs.python.org/issue?@action=redirect&bpo=21671] for CVE-2014-0224 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-0224].)

Python 2.7.9 に PEP 466 [https://peps.python.org/pep-0466/] 関連で追加された機能:

Python 3.4 の ssl モジュールのほとんどがバックポートされました。つまり ssl は今や、Server Name Indication, TLS1.x 設定, platform certificate store へのアクセス, SSLContext クラス, その他機能が使えます (Contributed by Alex Gaynor and David Reid; bpo-21308 [https://bugs.python.org/issue?@action=redirect&bpo=21308].)

個別の詳細については、モジュールのドキュメンテーション内の "バージョン 2.7.9 で追加" の注釈を参照してください。

os.urandom() は、呼び出しのたびに /dev/urandom を開きなおす代わりに /dev/urandom のファイル記述子をキャッシュするように変更されました。(Contributed by Alex Gaynor; bpo-21305 [https://bugs.python.org/issue?@action=redirect&bpo=21305].)

hashlib.algorithms_guaranteed と hashlib.algorithms_available が Python 3 からバックポートされました。これにより Python 2 アプリケーションが可能な限り最強のハッシュアルゴリズムを選択するのが容易になります (Contributed by Alex Gaynor in bpo-21307 [https://bugs.python.org/issue?@action=redirect&bpo=21307])

PEP 477: Python 2.7 への ensurepip (PEP 453) バックポート

PEP 477 [https://peps.python.org/pep-0477/] が Python 2.7 メンテナンスリリースに PEP 453 [https://peps.python.org/pep-0453/] ensurepip モジュール, それによって可能になるドキュメンテーションの改善を含めることを認め、Python 2.7.9 リリースではじめてお披露目されました。

デフォルトでの pip のブートストラッピング

新しい ensurepip モジュール(PEP 453 [https://peps.python.org/pep-0453/] で定義されています)は標準のクロスプラットフォームのメカニズムで、Python インストールに pip インストーラをブートストラップします。Python 2.7.9 に含まれる pip のバージョンは pip 1.5.6 で、将来の 2.7.x メンテナンスリリースでは Python のリリース候補の作成時点で入手出来る最新バージョンの pip がバンドルされる予定です。

デフォルトでは pip , pipX , pipX.Y コマンドが全てのプラットフォームに、Python パッケージ pip とその依存物とともにインストールされます(X. Y はインストールされる Python のバージョン)。

CPython の source builds on POSIX systems では make install, make altinstall コマンドはデフォルトでは pip ブートストラップを行いません。この振る舞いは configure のオプションを変更して Makefile を作ることで変更できます。

Windows と Mac OS X では CPython インストーラはそれ自身と一緒に pip をデフォルトでインストールするようになっています(ユーザはインストールプロセスで除外するかもしれませんが)。Windows ユーザは pip がコマンドラインからデフォルトで利用可能なように PATH の自動修正するかの選択を求められます。そうしない場合でも Windows のための Python ランチャで py -m pip のようにすれば良いです。

discussed in the PEP [https://www.python.org/dev/peps/pep-0453/#recommendations-for-downstream-distributors] の通りプラットフォームのパッケージャは、プラットフォームでのそれらインストールの単純明快な手段を自身が提供する(普通システムのパッケージマネージャ)からと言う理由で、デフォルトでのこれらコマンドのインストールを選択しないかもしれません。

ドキュメントの変更

この変更の一部は、 Python モジュールのインストール と Python モジュールの配布 セクションがより手短な始め方として完全にデザインし直されたことと、FAQ ドキュメントです。ほとんどのパッケージングについてのドキュメンテーションは Python Packaging User Guide [https://packaging.python.org] が保守している Python Packaging Authority に移動されて、独立したプロジェクトのドキュメンテーションになっています。

However, as this migration is currently still incomplete, the legacy versions of those guides remaining available as Building C and C++ Extensions with setuptools and Building C and C++ Extensions with setuptools.

参考

PEP 453 [https://peps.python.org/pep-0453/] -- Python インストールの際の明示的なpipのブートストラッピング

PEP は Donald Stufft と Nick Coghlan によって書かれ、Donald Stufft, Nick Coghlan, Martin von Löwis, Ned Deily により実装されました。

PEP 476: stdlib http クライアントが証明書の検証を行うのをデフォルトで有効化

PEP 476 [https://peps.python.org/pep-0476/] updated httplib and modules which use it, such as urllib2 and 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.

以前の古い振る舞いが必要なアプリケーションでは、代わりとなるコンテキストを渡せます:

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)

PEP 493: HTTPS verification migration tools for Python 2.7

PEP 493 [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 PYTHONHTTPSVERIFY environment variable may be set to 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 ssl._https_verify_certificates() function can be used to adjust the default behaviour at runtime.

New make regen-all build target

To simplify cross-compilation, and to ensure that CPython can reliably be compiled without requiring an existing version of Python to already be available, the autotools-based build system no longer attempts to implicitly recompile generated files based on file modification times.

Instead, a new 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 [https://github.com/python/cpython/tree/3.12/Makefile.pre.in] for details.

(Victor Stinner の貢献による bpo-23404 [https://bugs.python.org/issue?@action=redirect&bpo=23404])

Added in version 2.7.14.

Removal of make touch build target

The make touch build target previously used to request implicit regeneration of generated files by updating their modification times has been removed.

It has been replaced by the new make regen-all target.

(Victor Stinner の貢献による bpo-23404 [https://bugs.python.org/issue?@action=redirect&bpo=23404])

バージョン 2.7.14 で変更.

謝辞

著者は、以下の方々がこの記事の多くの草稿に提案、修正、そして助力を差し伸べてくださったことに感謝の意を表したいと思います: Nick Coghlan, Philip Jenvey, Ryan Lovett, R. David Murray, Hugh Secker-Walker.

What's New in Python 2.6

著者:

A.M. Kuchling (amk at amk.ca)

This article explains the new features in Python 2.6, released on October 1, 2008. The release schedule is described in PEP 361 [https://peps.python.org/pep-0361/].

Python 2.6 の主要なテーマは、大幅な言語の再設計となる Python 3.0 移行への道筋を準備することです。可能な場合にはいつでも、Python 2.6 は、古い機能や文法を削除することなく既存のコードの互換性を保てるようにしながら、3.0 より新機能と新文法を組み込んでいます。そうすることが出来ない場合には、Python 2.6 は、出来ることを出来るだけ試みました。それには future_builtins モジュールに互換関数を、また、Python 3 でサポートされなくなる用法についての警告を出すための -3 スイッチ を追加しています。

multiprocessing や json といった、いくつか重要な新しいパッケージが標準ライブラリに追加されましたが、Python 3.0 に何らかも関係しない新機能はあまり多くはありません。

Python 2.6 ではさらに、たくさんの改善とバグフィックスがソースコードのありとあらゆる場所に見られます。Python 2.5 から 2.6 の変更ログを手繰ってみると、低く見積もっても、適用されたパッチは 259、フィックスされたバグは 612 にのぼります。

このドキュメントは新機能の完全な詳細を提供するのではなくて、簡易な概要を提供することを目的にしています。完全な詳細が知りたければ、 Python 2.6 のドキュメントを参照してください。設計と実装の根拠を理解したい場合は、新機能に関する PEP を参照してください。可能な限り、 "What’s New in Python" は各変更の bug や patch に対してリンクしています。

Python 3.0

Python 2.6 と 3.0 の開発サイクルは同期していました。両バージョンのアルファ、ベータリリースは同じ日にリリースされています。3.0 の開発は 2.6 の多くの機能に影響を与えました。

Python 3.0 は、2.x シリーズとの互換性を破壊する、広範囲な再設計です。これは、Python 3.0 で動作させるためには既存のコードに何らかの変換が必要なことを意味しています。しかしながら、必ずしも全ての 3.0 での変更が互換性を破壊するわけではありません。新機能が既存のコードの破壊を引き起こさないケースにおいては、それらは 2.6 にバックポートされました。これらについてはこのドキュメントの適切な場所に記載しています。3.0 由来の機能の一部としては以下があります:

オブジェクトを複素数(虚数)に変換する __complex__() メソッド。

例外の捕捉の、これまでとは別の文法の追加: except TypeError as exc 。

組み込み関数 reduce() への別名としての functools.reduce() の追加。

Python 3.0 はいくつかの新しい組み込み関数を追加し、また、いくつかの既存の組み込み関数では意味を変更しています。Python 3.0 での新しい組み込み関数、例えば bin() などは単純に 2.6 に追加されましたが、既存のものはそうせずに、代わりに future_builtins モジュールに 3.0 版のものを追加しています。3.0 と互換性を持ちたいコードでは、必要に応じて from future_builtins import hex, map などとすることが出来ます。

A new command-line switch, -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 sys.py3kwarning, and to C extension code as Py_Py3kWarningFlag.

参考

The 3xxx series of PEPs, which contains proposals for Python 3.0. PEP 3000 [https://peps.python.org/pep-3000/] describes the development process for Python 3.0. Start with PEP 3100 [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.

開発プロセスに関する変更

2.6 の開発の間で、Python 開発プロセスは 2 つの重要な変更を経験しました: SourceForge の課題トラッカーから、カスタイマイズした Roundup インストレーションに乗り換えました。また、ドキュメントは LaTeX から reStructuredText に変換しました。

新しい課題トラッカー: Roundup

もう随分長いこと Python 開発者たちは、SourceForge のバグトラッカーにイライラを高め続けてきました。SourceForge がホストするソリューションには全くカスタマイズの余地がなく、たとえば課題のライフサイクルをカスタマイズ出来ませんでした。

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 [https://www.atlassian.com/software/jira/], Launchpad [https://launchpad.net/], Roundup [https://roundup.sourceforge.io/], and Trac [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.

ボランティアへの呼び掛けののち、新しい Roundup インストレーションが https://bugs.python.org にセットアップされました。Roundup の一つのインストレーションは複数のトラッカーをホスト出来るため、このサーバは今では Jython と Python ウェブサイトのための課題トラッカーもホストしています。間違いなく将来はほかのものもホストするでしょう。可能な場所では、"What's New in Python" のこのエディションでは、それぞれの変更についてのバグ/パッチの Roundup アイテムにリンクします。

Hosting of the Python bug tracker is kindly provided by Upfront Systems [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 https://svn.python.org/view/tracker/importer/ and may be useful to other projects wishing to move from SourceForge to Roundup.

参考

https://bugs.python.org

Python のバグトラッカー。

https://bugs.jython.org:

Jython のバグトラッカー。

https://roundup.sourceforge.io/

Roundup のダウンロードとドキュメント。

https://svn.python.org/view/tracker/importer/

Martin von Löwis の変換スクリプト。

新しいドキュメンテーションフォーマット: Sphinx を使っての reStructuredText

Python のドキュメンテーションは、そのプロジェクトの開始した 1989 年頃より LaTeX を使って書かれてきました。1980 年代と 1990 年代初期は、ほとんどのドキュメンテーションはあとで学習するために印刷されるもので、オンラインで見るものではありませんでした。LaTeX はとても魅惑的な印刷をしてくれるものですから、非常に大変広く広く使われていましたが、一方では、学んだマークアップの基礎的なルールで直裁的に、書いたらそれっきり、というものでもありました。

こんにちにおいてもなお、印刷を命題とする出版において LaTeX は健在といえど、プログラミングの道具立ての風景は変わりました。わたしたちはもはやドキュメンテーションの紙束をプリントアウトはしません。代わりにオンラインでブラウズします。ですから HTML は、サポートすべき最も重要なフォーマットになりました。悲しいかな、 LaTeX から HTML への変換は気が狂うほどに複雑で、Fred L. Drake Jr.、彼は長らく Python ドキュメンテーションのエディターを務めていますが、彼はその変換処理の保守に多大な時間を浪費していたのです。ときおり人々はドキュメンテーションを SGML に変換して、それから XML にすればいいでしょ、と持ちかけるのですが、良い変換を達成することにとらわれて、誰一人として仕事を完遂させようと時間を捧げることはしませんでした。

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 https://www.sphinx-doc.org/.

Sphinx は HTML 出力に集中し、人を惹きつけるスタイルでモダンな HTML を生成します。印刷出力は LaTeX への変換を経由することで健在です。入力のフォーマットは reStructuredText です。これはカスタムな拡張とディレクティブをサポートしているマークアップ文法で、Python コミュニティでは広く使われています。

Sphinx は執筆に使えるスタンドアロンのパッケージです。そして 2 ダースに届かんばかりのプロジェクト (Sphinx ウェブサイトのリスト [https://www.sphinx-doc.org/en/master/examples.html]) が Sphinx をドキュメンテーションツールとして採用しました。

参考

Documenting Python [https://devguide.python.org/documenting/]

Python ドキュメントの書き方について書いています。

Sphinx [https://www.sphinx-doc.org/]

Sphinx ツールチェインのドキュメントとコードです。

Docutils [https://docutils.sourceforge.io]

縁の下の力持ちになっている reStructuredText のパーサとツールセットです。

PEP 343: "with" ステートメント

Python 2.5 では、 'with' 文が from __future__ import with_statement ディレクティブで有効に出来るオプションの機能として追加されました。2.6 では 'with' 文は特別に有効化する必要なく、もういつでもそこにあります。このセクションの残りの部分は "What's New in Python 2.5" の対応するセクションからの丸々コピーですので、2.5 で 'with' 文に馴染んでいるなら読み飛ばしてもらって結構です。

'with' ステートメントは、以前なら後片付けが実行されるのを確実にするために try...finally ブロックを使ったであろうようなコードを、より単純明快にします。このセクションでは、このステートメントの普通の使い方を説明します。続くセクションでは実装の詳細を調べ、このステートメントとともに使うためにオブジェクトをどうやって書けば良いかをお見せします。

'with' ステートメントは基本構造が以下となる制御フロー構造です:

with expression [as variable]:
    with-block

The expression is evaluated, and it should result in an object that supports the context management protocol (that is, has __enter__() and __exit__() methods).

The object's __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 __exit__() method is called, even if the block raised an exception, and can therefore run clean-up code.

いくつかの Python 標準オブジェクトが既にコンテキスト管理プロトコルをサポートしていて、 'with' とともに使えます。ファイルオブジェクトがその一例です:

with open('/etc/passwd', 'r') as f:
    for line in f:
        print line
        ... more processing code ...

このステートメントが実行し終わったあかつきには、 f のファイルオブジェクトは、たとえ for ループが道半ばにして例外と成り果てても、自動的にクローズされます。

注釈

In this case, f is the same object created by open(), because __enter__() returns self.

threading モジュールのロック・条件変数でも 'with' ステートメントの恩恵にあずかれます:

lock = threading.Lock()
with lock:
    # Critical section of code
    ...

ブロックが実行される前にロックが獲得されて、ブロックが完了するやいなや必ず解放されます。

decimal モジュール内の localcontext() 関数は現在の decimal のコンテキスト (計算の望みの精度と丸め特性をカプセル化しています) を保存しておいてあとで元に戻すのを簡単にしてくれます:

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()

コンテキストマネージャを書く

中身を紐解いてみれば、 'with' ステートメントはけっこう入り組んでいます。ほとんどの人にとっては、既存のオブジェクトを 'with' とともに使うだけのことでその詳細を知る必要は無いので、それで良いならこのセクションの残りの部分は読み飛ばして結構です。新しいオブジェクトの作者は基礎となる実装の詳細について知る必要があるので、このまま読み進めるべきです。

コンテキスト管理プロトコルの高度な説明はこんなです:

The expression is evaluated and should result in an object called a "context manager". The context manager must have __enter__() and __exit__() methods.

The context manager's __enter__() method is called. The value returned is assigned to VAR. If no as VAR clause is present, the value is simply discarded.

BLOCK 内のコードが実行されます。

If BLOCK raises an exception, the context manager's __exit__() method is called with three arguments, the exception details (type, value, traceback, the same values returned by sys.exc_info(), which can also be 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 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 'with' statement will never realize anything went wrong.

If BLOCK didn't raise an exception, the __exit__() method is still called, but type, value, and traceback are all None.

例を通じて考えましょう。枝葉末節を含んだ完璧なコードを提示しようとは思いませんが、データベースのためにトランザクションをサポートするのに必要となるメソッドの書き方についてスケッチしてみようと思います。

(データベース用語に不慣れな方へ:データベースへの変更のセットは、トランザクションという単位でグループ化されています。トランザクションは「コミット」される、その意味は、全ての変更がデータベースに書き込まれることです、もしくは「ロールバック」される、この場合全ての変更が捨てられてデータベースが変更されません、この 2 つのいずれかになりえます。詳しくはなにかデータベースの著述を読んで下さい。)

データベース接続を表現するオブジェクトがあると仮定しましょう。私たちの目標は、そのオブジェクトのユーザがこのように書けるようになることです:

db_connection = DatabaseConnection()
with db_connection as cursor:
    cursor.execute('insert into ...')
    cursor.execute('delete from ...')
    # ... more operations ...

トランザクションはブロック内のコードがつつがなく終了すればコミットし、例外が発生すればロールバックすべきです。私が思い描いている DatabaseConnection の基本的なインターフェイスはこんなです:

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"

The __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 as cursor to their 'with' statement to bind the cursor to a variable name.

class DatabaseConnection:
    ...
    def __enter__(self):
        # Code to start a new transaction
        cursor = self.cursor()
        return cursor

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

下記のコード内では実行がメソッドの末尾まで落ちていって、なのでデフォルトの None 返却になります。 None は偽なので、例外は自動的に再送出されます。望むならもっと明示的に、コメントでマークした部分で return 文を書いてもよろしいです:

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

contextlib モジュール

contextlib モジュールは、 'with' ステートメントで使えるオブジェクトを書く際に便利ないくつかの関数とデコレータを提供しています。

The decorator is called 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 yield will be executed as the __enter__() method, and the value yielded will be the method's return value that will get bound to the variable in the 'with' statement's as clause, if any. The code after the yield will be executed in the __exit__() method. Any exception raised in the block will be raised by the yield statement.

このデコレータを使って、前セクションの私たちのデータベースの例はこのように書けます:

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

contextlib モジュールには nested(mgr1, mgr2, ...) 関数もあり、この関数はたくさんのコンテキストマネージャを組み合わせることができて、入れ子の 'with' を書く必要性をなくしてくれます。この例では、単一の 'with' でデータベーストランザクション開始とスレッドのロック獲得の両方をやってのけています:

lock = threading.Lock()
with nested (db_transaction(db), lock) as (cursor, locked):
    ...

最後になりますが、 closing() 関数はその与えた引数をそのまま返して変数に束縛出来るようにし、かつブロックの終了で、与えた引数が持つ .close() を呼び出します:

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)

参考

PEP 343 [https://peps.python.org/pep-0343/] - "with" ステートメント

PEP は Guido van Rossum と Nick Coghlan によって書かれ、Mike Bland、 Guido van Rossum、Neal Norwitz により実装されました。この PEP は 'with' ステートメントによって生成されるコードを見せてくれるので、このステートメントがどうやって動作するのかを知るのに役立ちます。

contextlib モジュールについてのドキュメント。

PEP 366: メインモジュールからの明示的相対インポート

Python のオプション -m で、モジュールをスクリプトとして実行出来ます。パッケージ内のモジュールを実行する際に、相対インポートが正しく動作していませんでした。

Python 2.6 でのそれについてのフィックスは、モジュールに __package__ 属性を追加するというものです。この属性がある場合は相対インポートは __name__ 属性の代わりにこの属性の値からの相対でインポートします。

PEP 302 スタイルのインポーターはその結果 __package__ を必要に応じて設定出来ます。 -m スイッチを実装している runpy モジュールは今はこれをするので、パッケージ内のモジュール実行内の相対インポートは、今では正しく動作します。(--- 訳注: このセクションの言いたいことの結論がわからない方はいないと思いますが、細かいところでこの翻訳を行っている 2015 年ではわからなくなっているところがあるので補足しておきます。 __package__ 属性のくだりですが、現在となっては「2.5 ではこれを設定していなかった」のかどうか簡単には確認は出来ないですが、言語リファレンスによればローダが __package__ をセットするのはオプションだがセットすべき、と書かれています。2.6 で行われたのは、おそらく __package__ の用法が runpy きっかけで整理された、ということではないかと思います。---)

PEP 370: ユーザごとの site-packages ディレクトリ

When you run Python, the module search path sys.path usually includes a directory whose path ends in "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 ではユーザ固有のサイトディレクトリのための決まりを導入しました。ディレクトリはプラットフォームに依存して変わります。

Unix と Mac OS X: ~/.local/

Windows: %APPDATA%/Python

このディレクトリ内にはバージョン固有のサブディレクトリが入ります。Unix/Mac OS では lib/python2.6/site-packages のように、Windows では Python26/site-packages のように。

このデフォルトディレクトリが好きでないなら、この機能をサポートする全ての Python バージョンが使う環境変数 PYTHONUSERBASE にルートディレクトリを指定することで上書き出来ます。Windows ではアプリケーション固有データの場所を環境変数 APPDATA で変更出来ます。また、あなたの Python インストレーションについての site.py ファイルを修正することでも出来ます。

この機能は Python 起動時に -s オプションを付けるか、環境変数 PYTHONNOUSERSITE をセットすることで完全に無効に出来ます。

参考

PEP 370 [https://peps.python.org/pep-0370/] - ユーザごとの site-packages ディレクトリ

PEP 著と実装 Christian Heimes.

PEP 371: multiprocessing パッケージ

新しい multiprocessing により、Python プログラムが新たなプロセスを作成して何か計算を実行させて結果を返させることが出来ます。親と子のプロセスはキューとパイプを使って通信し、ロックとセマフォを使って同期し、単純なデータの配列を共有出来ます。

multiprocessing モジュールは、 threading モジュールがスレッドの代わりにプロセスを使ようになるだけのような、完全な模倣となるよう開始されました。その目標は Python 2.6 へ向かう道のりを経て捨て去られはしましたが、モジュールの一般的なアプローチはそれでも似ています。基礎的なクラスは Process です。これには呼び出し可能オブジェクトと引数のコレクションを渡します。その start() メソッドが渡された呼び出し可能オブジェクトをサブプロセスで実行するので、 is_alive() メソッドを呼び出せばサブプロセスが実行中かを知ることが出来、 join() メソッドでそのプロセスが終了するのを待つことが出来ます。

ここに、サブプロセスが階乗を計算する例を示します。その計算をする関数はヘンテコリンに書かれていて、入力が 4 の倍数だととっても時間がかかるように仕組んであります。

import time
from multiprocessing import Process, Queue

def factorial(queue, N):
    "Compute a factorial."
    # If N is a multiple of 4, this function will take much longer.
    if (N % 4) == 0:
        time.sleep(.05 * N/4)

    # Calculate the result
    fact = 1L
    for i in range(1, N+1):
        fact = fact * i

    # Put the result on the queue
    queue.put(fact)

if __name__ == '__main__':
    queue = Queue()

    N = 5

    p = Process(target=factorial, args=(queue, N))
    p.start()
    p.join()

    result = queue.get()
    print 'Factorial', N, '=', result

Queue が factorial の結果を通信して返すのに使われています。 Queue オブジェクトはグローバル変数に格納されています。子プロセスは、子プロセスが作成された時点のその変数の値を使うことになります; Queue なので、親子はそのオブジェクトを通信のために使うことが出来ます。(プロセス作成後に親がグローバル変数 queue を差し替えても、子の値は左右されませんし、逆もしかりです。)

2 つのほかのクラス Pool と Manager はハイレベルインターフェイスです。 Pool では固定数のワーカープロセスを作ってワーカープロセスにリクエストを配ることが出来ます。 apply() または apply_async() メソッドで単体のリクエストを追加出来、 map() または map_async() メソッドでたくさんのリクエストを追加出来ます。以下のコードでは Pool を使って 5 つのワーカープロセスにリクエストをばら撒き、結果のリストを回収します:

from multiprocessing import Pool

def factorial(N, dictionary):
    "Compute a factorial."
    ...
p = Pool(5)
result = p.map(factorial, range(1, 1000, 10))
for v in result:
    print v

これは以下のような出力をします:

1
39916800
51090942171709440000
8222838654177922817725562880000000
33452526613163807108170062053440751665152000000000
...

もう一方の方のハイレベルインターフェイス Manager クラスは、Python データ構造のマスターコピーを保持出来る、独立したひとつのサーバプロセスを作ります。ほかのプロセスたちは、これらデータ構造の読み書きと修正をプロキシオブジェクトを使って行えます。続く例では、 dict() メソッドを呼ぶことにより共有辞書を作ります; ワーカープロセスはその辞書へ挿入します。(ロックは自動的には行われませんがこの例では問題ではありません。 Manager のメソッドには Lock(), RLock(), Semaphore() メソッドも含まれていて、共有ロックを作るのに使えます。)

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

これはこんな出力をするでしょう:

1 1
11 39916800
21 51090942171709440000
31 8222838654177922817725562880000000
41 33452526613163807108170062053440751665152000000000
51 15511187532873822802242430164693032110632597200169861120000...

参考

multiprocessing モジュールについてのドキュメント。

PEP 371 [https://peps.python.org/pep-0371/] - multiprocessing パッケージの追加

PEP 著 Jesse Noller と Richard Oudkerk; 実装 Richard Oudkerk と Jesse Noller.

PEP 3101 [https://peps.python.org/pep-3101/]: 進化版文字列フォーマッティング

In Python 3.0, the % operator is supplemented by a more powerful string formatting method, format(). Support for the str.format() method has been backported to Python 2.6.

In 2.6, both 8-bit and Unicode strings have a .format() method that treats the string as a template and takes the arguments to be formatted. The formatting template uses curly brackets ({, }) as special characters:

>>> # 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'

波括弧自身は二重に書くことでエスケープ出来ます:

>>> "Empty dict: {{}}".format()
"Empty dict: {}"

フィールド名は、位置引数に対応する整数による {0}, {1}, …、またはキーワード引数に対応する名前です。属性を読み出したり辞書のキーにアクセスするような合成フィールド名(compound field names)も与えることが出来ます:

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

[.mp4] のように辞書スタイルの記法を使う際は文字列の周りを引用符で囲む必要はありません; .mp4 をキーに値のルックアップされます。数値で始まる文字列は整数に変換されます。フォーマット文字列内でこれ以上複雑な表現は書けません。

ここまでは、結果文字列に置き換えられるフィールドを指定する方法について見てきました。フォーマッティングではさらに、コロンに続けて書式指定子を追加することでコントロール可能です。例えば:

>>> # 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'

書式指定子として、ネストによる他フィールド参照が使えます:

>>> fmt = '{0:{1}}'
>>> width = 15
>>> fmt.format('Invoice #1234', width)
'Invoice #1234  '
>>> width = 35
>>> fmt.format('Invoice #1234', width)
'Invoice #1234                      '

望みの幅内でのフィールドの整列を指定可能です:

文字

効果

< (デフォルト)

左寄せ

>

右寄せ

^

中央寄せ

=

(数値型についてのみ) 符号のあとにパディング

書式指定子には体裁のタイプも含めることが出来ます。値をどのようにフォーマットするかです。たとえば浮動小数点数は普通の数値に、あるいは指数形式でフォーマット出来ます:

>>> '{0:g}'.format(3.75)
'3.75'
>>> '{0:e}'.format(3.75)
'3.750000e+00'

たくさんの体裁のタイプを利用出来ます。2.6 ドキュメントの complete list を調べてみてください。以下はその一部です:

b

2進数。出力される数値は2を基数とします。

c

文字。数値を対応するユニコード文字に変換します。

d

10進数。出力される数値は10を基数とします。

o

8進数。出力される数値は8を基数とします。

x

16進数。出力される数値は16を基数とします。 10進で9を超える数字には小文字が使われます。

e

指数表現です。指数を示す 'e' を使った科学的記数法で表示します。

g

汎用フォーマット。数値が大き過ぎない限りは固定小数点表現をしますが、大きい値では 'e' 指数表現に切り替えます。

n

数値です。現在のロケールに合わせて、数値分割文字が挿入されることを除き、 'g' (浮動小数点数の場合) または 'd' (整数の場合) と同じです。

%

パーセンテージです。数値は 100 倍され、固定小数点数フォーマット ('f') でパーセント記号付きで表示されます。

クラスと型は、自身がどのように書式化されるかをコントロールするために __format__() メソッドを定義出来ます。単一の引数として書式指定子を受け取ります:

def __format__(self, format_spec):
    if isinstance(format_spec, unicode):
        return unicode(str(self))
    else:
        return str(self)

ビルトインの format() もあって、単一の値をフォーマット出来ます。これは型の __format__() メソッドを与えられた指定子とともに呼び出します:

>>> format(75.6564, '.2f')
'75.66'

参考

書式指定文字列の文法

リファレンスドキュメント。

PEP 3101 [https://peps.python.org/pep-3101/]: 進化版文字列フォーマッティング

PEP 著 Talin; 実装 Eric Smith。

PEP 3105: print を関数にする

print 文は Python 3.0 では print() 関数になります。 print() が関数になることで、 def print(...) やなにかほかの場所からの新しい関数をインポートするなどの方法で置き換え可能になります。

Python 2.6 では __future__ インポートで 言語構文としての print を取り除き、関数形式のものを代わりに使えるように出来ます。たとえば:

>>> from __future__ import print_function
>>> print('# of entries', len(dictionary), file=sys.stderr)

この新しい関数のシグネチャは以下の通りです:

def print(*args, sep=' ', end='\n', file=None)

パラメータは以下のとおりです:

args: 出力される値を指定する位置引数リスト。

sep: 引数リスト args を出力するのに使われる区切り文字。

end: 引数リスト args を全て出力したあとに出力するテキスト。

file: 出力が送られるファイルオブジェクト。

参考

PEP 3105 [https://peps.python.org/pep-3105/] - print を関数にする

Georg Brandl 著の PEP。

PEP 3110: 例外処理の変更

Python プログラマが時折やらかしてしまう誤りの一つにこんなのがあります:

try:
    ...
except TypeError, ValueError:  # Wrong!
    ...

このコードの作者はきっと TypeError 例外と ValueError 例外の両方とっつかまえてやろうと思ったのでしょうが、このコードは実際にはちょっと違ったことをします: TypeError を捕捉したらこれを "ValueError" というローカル名の例外オブジェクトに束縛します…。 ValueError 例外は決して捕捉されません。正しくは、例外のタプルで指定します:

try:
    ...
except (TypeError, ValueError):
    ...

こんなことが起こってしまうのは、ここではカンマの使用が曖昧だからです: それ、解析木内で 2 つのノードを示すのかな、タプルな単一ノードかしら?

Python 3.0 はカンマからワード "as" に置き換えてこの曖昧さをなくします。例外を捕捉して例外オブジェクトを exc に記憶するには、こう書かなければなりません:

try:
    ...
except TypeError as exc:
    ...

Python 3.0 は "as" の使用のみをサポートするようになるので、最初の例は 2 つの異なる例外を捕捉するものとして翻訳されます。Python 2.6 ではカンマも "as" もサポートするので、既存のコードはそのまま動作します。新たに 2.6 で実行される Python コードを書くならば、 "as" の使用を勧めます。

参考

PEP 3110 [https://peps.python.org/pep-3110/] - Python 3000 での例外の捕捉

PEP 著と実装 Collin Winter.

PEP 3112: バイトリテラル

Python 3.0 は Unicode を言語の基本文字列型として採用し、8 ビットリテラルは異なった記法で指示します。それには b'string' とするか、 bytes のコンストラクタを用います。前方互換のために、Python 2.6 は str 型に対する別名として bytes を追加のうえで、 b'' 記法もサポートします。

2.6 の str 型は 3.0 の bytes 型とは色んな意味で違います; 一番顕著なのは、コンストラクタがまったく異なることです。3.0 での bytes([65, 66, 67]) は 3 つのバイトで ABC を構築しますが、2.6 での bytes([65, 66, 67]) は引数のリストを str() で文字列化した 12 バイト文字列を返します。

2.6 での bytes の主な使いみちはオブジェクトの型のテストに isinstance(x, bytes) とすることでしょう。またこれは、 2.x コードが文字列として ASCII 文字と 8 ビットバイトのどちらを意図しているのか知ることが出来ない 2to3 コンバータの助けになります; あなたは今や bytes と str の区別を、あなたの意図を正確に表現するのに使えます。そして結果のコードは Python 3.0 で正しいものに修正されるでしょう。

全ての文字列リテラルを Unicode 文字列としてしまう __future__ インポートもあります。これは Unicode 文字を含むのに \u エスケープシーケンスを使えることを意味します。

from __future__ import unicode_literals

s = ('\u751f\u3080\u304e\u3000\u751f\u3054'
     '\u3081\u3000\u751f\u305f\u307e\u3054')

print len(s)               # 12 Unicode characters

At the C level, Python 3.0 will rename the existing 8-bit string type, called PyStringObject in Python 2.x, to PyBytesObject. Python 2.6 uses #define to support using the names PyBytesObject(), PyBytes_Check(), PyBytes_FromStringAndSize(), and all the other functions and macros used with strings.

bytes 型のインスタンスは単に文字列と同じで immutable です。 bytearray 型が、バイト列を mutable シーケンスとして格納するものとして新しく追加されました:

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

bytearray は startswith()/endswith(), find()/rfind() のような文字列型のほとんどのメソッド、 append(), pop(), reverse() のようなリストのいくつかのメソッドをサポートします。

>>> b = bytearray('ABC')
>>> b.append('d')
>>> b.append(ord('e'))
>>> b
bytearray(b'ABCde')

対応する C API もあります。 PyByteArray_FromObject(), PyByteArray_FromStringAndSize() や色々その他関数です。

参考

PEP 3112 [https://peps.python.org/pep-3112/] - Python 3000 でのバイトリテラル

PEP 著 Jason Orendorff; 2.6 へのバックポート Christian Heimes.

PEP 3116: 新しい I/O ライブラリ

Python ビルトインのファイルオブジェクトはたくさんのメソッドをサポートしていますが、ファイルライクなオブジェクトは必ずしもそのすべてをサポートする必要はありません。ファイルのまねごとをするオブジェクトは大抵 read() と write() をサポートしますが、 readline() はサポートしないかもしれません、例えば。Python 3.0 は io モジュールに、階層化された I/O ライブラリを導入しています。それは基礎的な読み書き操作からバッファリング機能とテキスト処理を分離しています。

io モジュールによって提供される抽象基底クラスには 3 つのレベルがあります:

RawIOBase は剥き身の I/O 操作を定義します: read(), readinto(), write(), seek(), tell(), truncate(), close() 。このクラスのほとんどのメソッドが多くの場合単一のシステムコールに対応するでしょう。 readable(), writable(), seekable() メソッドも利用可能で、オブジェクトでどの操作が許されるのかを知るのに使えます。

Python 3.0 はこのクラスのファイルとソケットに対する具象実装を持っていますが、Python 2.6 はファイル、ソケットオブジェクトのこの方法での再構築はしていません。

BufferedIOBase はデータをメモリにバッファすることでシステムコール使用回数を減らし、I/O 処理をより効率的に行うための抽象基底クラスです。 RawIOBase の全てのメソッドをサポートし、追加で基底の剥き身のオブジェクトを保持する raw 属性を持ちます。

5 つの具象クラスがこの ABC を実装しています。 BufferedWriter と BufferedReader はランダムアクセスのための seek() を持ち、書き込み専用または読み出し専用の用途をサポートするオブジェクトのためのものです。 BufferedRandom オブジェクトはこれらと同じ前提のストリームでの読み書きアクセスをサポートし、 BufferedRWPair は、TTY のような、連続していないデータのストリームの上で読み書き操作両方を演じるオブジェクトのためのものです。 BytesIO クラスはインメモリのバッファ上での読み、書き、シークをサポートします。

TextIOBase: 文字列 (忘れないで、Python 3.0 では文字列は Unicode になります) の読み書き関数を提供し、 universal newlines をサポートします。 TextIOBase は readline() メソッドをサポートし、また、オブジェクトを渡るイテレーションをサポートします。

2 つの具象実装があります。 TextIOWrapper はバッファ化 I/O オブジェクトをラップし、テキスト I/O の全てのメソッドをサポートし、追加で元となるオブジェクトへのアクセスのための buffer 属性を持ちます。 StringIO はディスクへの一切の書き込みをせずに単純にメモリ内に全てをバッファします。

(In Python 2.6, io.StringIO is implemented in pure Python, so it's pretty slow. You should therefore stick with the existing StringIO module or cStringIO for now. At some point Python 3.0's io module will be rewritten into C for speed, and perhaps the C implementation will be backported to the 2.x releases.)

Python 2.6 では根底にある実装が io モジュールのクラスの上に組み立てられるようには再構築されていません (訳注: Python HowTo の移植ガイドにも触れられている通り、2.7 も同じです)。このモジュールは 3.0 への前方互換のコードを書くのを容易にするために、また、開発者たちがバッファリング I/O とテキスト I/O を自身で書く労力を省くために提供されています。

参考

PEP 3116 [https://peps.python.org/pep-3116/] - 新しい I/O

PEP 著: Daniel Stutzbach, Mike Verdone, Guido van Rossum. 実装: Guido van Rossum, Georg Brandl, Walter Doerwald, Jeremy Hylton, Martin von Loewis, Tony Löwis, ほか.

PEP 3118: 改訂版バッファプロトコル

バッファプロトコルは Python 型にその内部表現へのポインタをやりとりさせる、C レベル API です。例えば、メモリマップドファイルは文字のバッファとして見ることが出来ます。そしてこれは re のようなほかのモジュールが、それを文字列として扱って検索するようなことを許します。

バッファプロトコルの主なユーザは NumPy のような数値演算パッケージで、それらは呼び出し元がより遅い API を経由することなく直接的に行列にデータを書き込むことが出来るように、行列の内部表現を曝しています。この PEP は NumPy 開発の経験を踏まえてバッファプロトコルを更新するもので、行列の形状を表明したり、メモリ領域をロックしたりするような多数の新機能を追加します。

最重要の新規 C API 関数は PyObject_GetBuffer(PyObject *obj, Py_buffer *view, int flags) で、これはオブジェクトを受け取って、フラグをセットし、 Py_buffer 構造体にオブジェクトのメモリ表現についての情報を埋めます。オブジェクトはこの操作を、外部の呼び出し元がその内容を修正している間所定のメモリをロックするのに使えます。ですので対応する操作 PyBuffer_Release(Py_buffer *view) があり、これで外部呼出し元が処理を終えたことを表明します。

PyObject_GetBuffer() への flags 引数は返されるメモリについての制約条件を指定します。いくつかの例として:

PyBUF_WRITABLE indicates that the memory must be writable.

PyBUF_LOCK requests a read-only or exclusive lock on the memory.

PyBUF_C_CONTIGUOUS and PyBUF_F_CONTIGUOUS requests a C-contiguous (last dimension varies the fastest) or Fortran-contiguous (first dimension varies the fastest) array layout.

PyArg_ParseTuple() のための 2 つの新しい書式化コード s* と z* は、パラメータとしてロックされたバッファオブジェクトを返します。

参考

PEP 3118 [https://peps.python.org/pep-3118/] - 改訂版バッファプロトコル

PEP 著: Travis Oliphant, Carl Banks; 実装: Travis Oliphant.

PEP 3119: 抽象基底クラス

ある種のオブジェクト指向言語、たとえば Java などは、クラスが持つメソッドの集合やサポートするアクセスプロトコルを宣言するための「インターフェイス」をサポートしています。抽象基底クラス (ABCs=Abstract Base Classes)は Python でのこれと等価な機能です。ABC サポートは、 ABCMeta と呼ばれるメタクラスを含む abc モジュール、ビルトイン isinstance() と issubclass() のそのメタクラスについての特殊処理、それに Python 開発者が広範囲にわたって使えると考えた基礎的な ABCs のコレクションから成ります。たぶん将来のバージョンの Python ではもっとたくさんの ABCs が追加されると思います。

あなたがなにか特別なクラスを持っていて、辞書スタイルのアクセスをサポートするのか知りたいとしましょう。「辞書スタイル」ってなんでしょうね、それにしても。たぶんアイテムにアクセスするのに obj[1] が使えるでしょう。それは obj[2] = value のように値をセットするのも含まれるでしょうね? あるいは keys(), values(), items() メソッドを持ちますかね? iterkeys() みたいな列挙系はいかがでしょう? copy() と update() は? オブジェクトを巡回するのに iter() で出来ます?

Python 2.6 の collections モジュールには、この手の区別を表現出来るたくさんの ABCs が含まれています。 Iterable は __iter__() を定義したクラスを示し、 Container は __contains__() メソッドを定義していて、なので x in y 式をサポートしていることを意味します。アイテム取得、アイテムセット、 keys(), values(), items() という品揃えの基礎的な辞書インターフェイスは MutableMapping ABC で定義されています。

あなた自身のクラスを特定の ABC から派生して、ABC のインターフェイスをサポートすることを示せます:

import collections

class Storage(collections.MutableMapping):
    ...

別の方法としては、望みの ABC から派生するのではなく、その ABC の register() メソッドを呼び出して登録することでも出来ます:

import collections

class Storage:
    ...

collections.MutableMapping.register(Storage)

あなたが書くクラスでは ABC から派生するのが、たぶん綺麗で良いと思います。既存の型やクラスを記述出来る新しい ABC が書けた場合や、なにかサードパーティのクラスが実装する ABC を宣言したい場合などには register() メソッドが有用です。例えば、 PrintableType ABC を定義したのなら、今がそのとき、です:

# Register Python's types
PrintableType.register(int)
PrintableType.register(float)
PrintableType.register(str)

クラスは ABC が規定するセマンティクスに従うべきですが、Python はそれをチェックは出来ません；その ABC の要求を理解してコードを適切に実装するのはクラスの作者任せです。

オブジェクトが特定のインターフェイスをサポートするかどうかをチェックするのには、今やこう書けます:

def func(d):
    if not isinstance(d, collections.MutableMapping):
        raise ValueError("Mapping object expected, not %r" % d)

これからはたくさんのこのようなチェックをしなければならないのだ、この例のように、などとは思わないように。Python は至極ダックタイピングな流儀なのであって明示的な型チェックは決してされませんし、コードは単純にオブジェクトのメソッドを、それらメソッドがそこにあるはずで、なければ例外になるのを信じて呼ぶだけです。ABC についてのチェックには分別を持ち、それが絶対的に必要な場合にだけそうするようにしましょう。

あなた自身の ABCs を書くには、クラス定義内のメタクラスとして abc.ABCMeta を使います:

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

上の Drawable ABC では、 draw_doubled() メソッドがオブジェクトをその 2 倍のサイズで描画しますが、 Drawable で示されたほかのメソッドのやり方で実現されるのでしょう。この ABC を実装するクラスは draw_doubled() のそれ自身の実装を提供する必要はないわけですが、実装しても良いです。一方 draw() の実装は必要です。その ABC が役に立つ汎用的な実装が提供出来ていないので。

draw() のような、実装が必須のメソッドに対して @abstractmethod デコレータを適用することが出来ます; Python はそのメソッドを実装しないクラスに例外を喰らわせます。サブクラスにそのメソッドが欠けていたとしても、インスタンスを実際に作ろうと試みてはじめて例外となることに注意しましょう:

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

抽象データ属性を @abstractproperty を使って宣言出来ます:

from abc import abstractproperty
...

@abstractproperty
def readonly(self):
   return self._x

この場合サブクラスは readonly() プロパティを定義することが必須です。

参考

PEP 3119 [https://peps.python.org/pep-3119/] - 抽象基底クラスの導入

PEP は Guido van Rossum と Talin によって著され、Guido van Rossum により実装されています。Python 2.6 へのバックポートは Benjamin Aranguren と Alex Martelli により行われました。

PEP 3127: 整数リテラルのサポートと文法

Python 3.0 は octal (基数 8: 8 進数) 整数リテラルの構文を変更し、先行するゼロの代わりに "0o" または "0O" (「ゼロオー」)としています。また、 binary (基数 2: 2 進数) 整数リテラルのサポートを追加し、これは "0b" または "0B" で指示します。

Python 2.6 は先行するゼロの形式での 8 進数サポートをやめませんが、 "0o" と "0b" は追加サポートします:

>>> 0o21, 2*8 + 1
(17, 17)
>>> 0b101111
47

ビルトイン関数 oct() はまだ先行ゼロ形式での表現を返します。新しいビルトイン関数 bin() は数値の 2 進数表現を返します:

>>> oct(42)
'052'
>>> future_builtins.oct(42)
'0o52'
>>> bin(173)
'0b10101101'

ビルトイン int(), long() が、基数 8 か 0 を要求された場合の "0o" プレフィクス、基数 2 か 0 を要求された場合の "0b" プレフィクスをそれぞれ許容するようになりました(基数 base = 0 は文字列から基数を決めるべきであることを指示します):

>>> int ('0o52', 0)
42
>>> int('1101', 2)
13
>>> int('0b1101', 2)
13
>>> int('0b1101', 0)
13

参考

PEP 3127 [https://peps.python.org/pep-3127/] - 整数リテラルのサポートと文法

PEP 著 Patrick Maupin、2.6 へのバックポートは Eric Smith による。

PEP 3129: クラスデコレータ

デコレータが拡張されて関数だけでなクラスにも使えるようになりました。今やこのように書くのは合法です:

@foo
@bar
class A:
  pass

これは次と等価です:

class A:
  pass

A = foo(bar(A))

参考

PEP 3129 [https://peps.python.org/pep-3129/] - クラスデコレータ

PEP 著 Collin Winter.

PEP 3141: 数値の型階層

Python 3.0 では Scheme の numeric tower に触発された、いくつかの数値型のための抽象基底クラスを追加しています。これらのクラスは numbers モジュール として 2.6 にバックポートされています。

一番てっぺんの汎用 ABC が Number です。これには何の演算も含まれず、オブジェクトがなんらか数値であることをチェックするためだけにあります。 isinstance(obj, Number) として使えます。

Complex は Number のサブクラスです。複素数は基礎的な追加の演算の加算、減算、積算、除算、累乗に耐えるとともに、実数部と虚数部の抽出と共役数の取得が出来ます。Python のビルトインの complex 型は Complex を実装しています。

Real は Complex から更に派生し、実数のみで動作する演算を追加しています: floor(), trunc(), 丸め, divmod, floor division, 比較、です。

Rational 数は Real からの派生で、プロパティ numerator, denominator を持ち、浮動小数点数への変換が出来ます。Python 2.6 は単純な有理数クラス Fraction を fractions モジュールに追加しています。(Rational ではなく Fraction なのは、 numbers.Rational と名前が衝突するのを避けるためです。)

Integral 数は Rational からの派生で、シフト演算 <<, >> が出来て、 & や | のようなビット演算で混ぜ合わせることができて、また、配列のインデクスとスライスの境界として使えます。

Python 3.0 では、その PEP は少し既存のビルトイン round(), math.floor(), math.ceil() を再定義していて、また、Python 2.6 にバックポートされている新しい math.trunc() を追加しています。 math.trunc() はゼロに向かう方向の丸めで、引数とゼロの間で一番近い Integral を返します。

参考

PEP 3141 [https://peps.python.org/pep-3141/] - 数値の型階層

PEP 著: Jeffrey Yasskin.

Guile マニュアルの Scheme's numerical tower [https://www.gnu.org/software/guile/manual/html_node/Numerical-Tower.html#Numerical-Tower] 。

Scheme's number datatypes [https://conservatory.scheme.org/schemers/Documents/Standards/R5RS/HTML/r5rs-Z-H-9.html#%_sec_6.2] from the R5RS Scheme specification.

fractions モジュール

数値型階層を埋めるべく、 fractions モジュールが有理数クラスを提供しています。有理数は分子(numerator)と分母(denominator)で構成される分数としてその値を格納し、浮動小数点数では近似しか出来ない 2/3 のような数を正確に表現出来ます。

Fraction のコンストラクタは 2 つの Integral 値を取り、それらはそれぞれ結果の分数の分子と分母になります。:

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

浮動小数点数を有理数に変換するのに、浮動小数点数型に as_integer_ratio() メソッドが追加されています。これはそれを評価して分数の分子と分母を返します:

>>> (2.5) .as_integer_ratio()
(5, 2)
>>> (3.1415) .as_integer_ratio()
(7074029114692207L, 2251799813685248L)
>>> (1./3) .as_integer_ratio()
(6004799503160661L, 18014398509481984L)

1./3 のような浮動小数点数で近似にしかならない値は、近似して単純化されたりはしないことに注意してください; その分数は浮動小数点数に 正確に 合うように試みられます。

fractions モジュールは、ずっと長い間 Python の Demo/classes/ ディレクトリにいた Sjoerd Mullender による実装に基いています。この実装が Jeffrey Yasskin によって大幅に更新されました。

その他の言語変更

Python 言語コアに小さな変更がいくつか行われました:

__main__.py を含んだディレクトリ名と zip アーカイブ名をインタプリタに渡して直接実行出来るようになりました。そのディレクトリと zip アーカイブは自動的に sys.path エントリの先頭に追加されます。(Suggestion and initial patch by Andy Chu, subsequently revised by Phillip J. Eby and Nick Coghlan; bpo-1739468 [https://bugs.python.org/issue?@action=redirect&bpo=1739468].)

hasattr() 関数は __getattr__() メソッドが例外を起こすと何か失敗したのだと仮定して、全て捕捉して無視して False を返していました。ですがそのロジックは KeyboardInterrupt と SystemExit まで捕まえるべきではなかったのです。Python 2.6 では hasattr() はもはやそれら例外に出会ってもそれを捨てません。 (Fixed by Benjamin Peterson; bpo-2196 [https://bugs.python.org/issue?@action=redirect&bpo=2196].)

** 構文を使ってキーワード引数を許容する関数を呼び出すのに、もう Python 辞書を使う必要はありません; 任意のマッピングプロトコルをサポートするオブジェクトで今では動作します:

>>> def f(**kw):
...    print sorted(kw)
...
>>> ud=UserDict.UserDict()
>>> ud['a'] = 1
>>> ud['b'] = 'string'
>>> f(**ud)
['a', 'b']

(Contributed by Alexander Belopolsky; bpo-1686487 [https://bugs.python.org/issue?@action=redirect&bpo=1686487].)

同時に、 *args 引数のあとでキーワード引数を与える関数呼び出しも今では合法です。:

>>> def f(*args, **kw):
...     print args, kw
...
>>> f(1,2,3, *(4,5,6), keyword=13)
(1, 2, 3, 4, 5, 6) {'keyword': 13}

以前はこれは構文エラーになっていました。 (Contributed by Amaury Forgeot d'Arc; bpo-3473 [https://bugs.python.org/issue?@action=redirect&bpo=3473].)

新しいビルトイン next(iterator, [default]) は指定したイテレータより次のアイテムを返します。 iterator が使い果たされている場合、 default 引数が与えられていれがこれを、そうでなければ StopIteration 例外を起こします。 (Backported in bpo-2719 [https://bugs.python.org/issue?@action=redirect&bpo=2719].)

タプルがリストと同じく index() と count() メソッドを持つようになっています:

>>> t = (0,1,2,3,4,0,1,2)
>>> t.index(3)
3
>>> t.count(0)
2

(Contributed by Raymond Hettinger)

ビルトイン型が拡張スライス構文をサポートするために改善されています。色々な (start, stop, step) 組み合わせを受け付けます。以前はこれのサポートは限定的で、ものによっては動作しませんでした。 (Implemented by Thomas Wouters.)

property に getter, setter, deleter が追加されています。取得関数(getter)、設定関数(setter)、削除関数(deleter)を既存のプロパティに追加するための便利なショートカットとして使えるデコレータです。これらはこのように使えます:

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

ビルトインの set 型のいくつかのメソッドが複数イテラブルを受け付けるようになっています: intersection(), intersection_update(), union(), update(), difference(), difference_update() です。

>>> s=set('1234567890')
>>> s.intersection('abc123', 'cdf246')  # Intersection between all inputs
set(['2'])
>>> s.difference('246', '789')
set(['1', '0', '3', '5'])

(Contributed by Raymond Hettinger.)

たくさんの浮動小数点数機能が追加されました。 float() 関数は文字列 nan を IEEE 754 非数 (Not A Number) 値に変換し、 +inf と -inf は正あるいは負の無限大に変換します。これは IEEE 754 セマンティクスのあらゆるプラットフォームで動作します。 (Contributed by Christian Heimes; bpo-1635 [https://bugs.python.org/issue?@action=redirect&bpo=1635].)

ほか math モジュールに isinf() と isnan() が追加されています; 浮動小数点数が、前者は無限大ならば、後者は非数ならばそれぞれ真を返します。 (bpo-1640 [https://bugs.python.org/issue?@action=redirect&bpo=1640])

浮動小数点数を 16 進表記文字列に変換する変換関数が追加されています (bpo-3008 [https://bugs.python.org/issue?@action=redirect&bpo=3008])。これら関数は 10 進と 2 進との間の変換で起こる丸め誤差を持ち込まずに浮動小数点数と文字列表現の相互変換をします。浮動小数点数は文字列表現を返す hex() メソッドを持ち、また、 float.fromhex() メソッドが文字列から浮動小数点数に戻します:

>>> a = 3.75
>>> a.hex()
'0x1.e000000000000p+1'
>>> float.fromhex('0x1.e000000000000p+1')
3.75
>>> b=1./3
>>> b.hex()
'0x1.5555555555555p-2'

数に関する繊細さ: 符号付ゼロ (-0 と +0) をサポートするシステムで 2 つの浮動小数点数から複素数を作る際に、 complex() コンストラクタがゼロの符号を維持するようになりました。 (Fixed by Mark T. Dickinson; bpo-1507 [https://bugs.python.org/issue?@action=redirect&bpo=1507].)

__hash__() メソッドを親クラスから継承するクラスは、ハッシュ出来ないことを示すのに __hash__ = None をセット出来ます。これにより hash(obj) は TypeError を起こし、そのクラスは Hashable ABC を実装していないことを示します。

__cmp__() か __eq__() を定義するのにその比較にオブジェクトの身元ではなくその値を使ったならば、あなたはこれをすべきです。全てのオブジェクトはその値として id(obj) を使うデフォルトのハッシュ化メソッドを持っています。親クラスから継承した __hash__() を削除する整理された方法はありません。ですのでオーバライドとしての None の代入が実装されました。 C API のレベルでは、拡張は tp_hash に PyObject_HashNotImplemented() をセット出来ます。 (Fixed by Nick Coghlan and Amaury Forgeot d'Arc; bpo-2235 [https://bugs.python.org/issue?@action=redirect&bpo=2235].)

GeneratorExit 例外が Exception ではなく BaseException のサブクラスになっています。 except Exception: をする例外ハンドラが意図せず GeneratorExit 捕捉してしまうことがなくなります。 (Contributed by Chad Austin; bpo-1537 [https://bugs.python.org/issue?@action=redirect&bpo=1537].)

ジェネレータオブジェクトが、そのジェネレータを返すオリジナルのコードオブジェクトを参照する gi_code 属性を持つようになりました。 (Contributed by Collin Winter; bpo-1473257 [https://bugs.python.org/issue?@action=redirect&bpo=1473257].)

ビルトイン関数 compile() が位置引数だけでなくキーワード引数も受け付けるようになりました。 (Contributed by Thomas Wouters; bpo-1444529 [https://bugs.python.org/issue?@action=redirect&bpo=1444529].)

complex() コンストラクタが括弧で囲まれた複素数表現文字列を受け付けるようになっています。 complex(repr(cplx)) で元に戻せるということです。例えば complex('(3+4j)') は今では値 (3+4j) を返します。 (bpo-1491866 [https://bugs.python.org/issue?@action=redirect&bpo=1491866])

文字列の translate() メソッドが変形テーブルパラメータとして None を受け付けるようになりました。そのまま同じものを返す変形として扱われます。これにより文字を削除する操作を実行するのが簡単になります。 (Contributed by Bengt Richter and implemented by Raymond Hettinger; bpo-1193128 [https://bugs.python.org/issue?@action=redirect&bpo=1193128].)

ビルトインの dir() 関数が、受け取ったオブジェクトの __dir__() メソッドをチェックするようになりました。このメソッドはそのオブジェクトで妥当な属性名を含む文字列のリストを返さなければなりません。これにより dir() が生成する値を制御出来ます。 __getattr__() や __getattribute__() メソッドを使うオブジェクトはこれを使うことで、約束するつもりの擬似属性を公表出来ます。 (bpo-1591665 [https://bugs.python.org/issue?@action=redirect&bpo=1591665])

Instance method objects have new attributes for the object and function comprising the method; the new synonym for im_self is __self__, and im_func is also available as __func__. The old names are still supported in Python 2.6, but are gone in 3.0.

目立たない変更: locals() 関数を class ステートメント内で使う際、結果の辞書はもはや自由変数を返しません。(この場合、自由変数は class ステートメント内で参照される変数で、クラスの属性ではありません。)

最適化

warnings モジュールが C で書き直されました。これにより警告をパーサから発行出来、また、インタプリタの起動が高速化しています。 (Contributed by Neal Norwitz and Brett Cannon; bpo-1631171 [https://bugs.python.org/issue?@action=redirect&bpo=1631171].)

型オブジェクトがメソッドのキャッシュを持つようになっています。これは個別のクラスについての正しいメソッド実装を見つけるのに必要な仕事を減らします。いったんキャッシュされれば、インタプリタは呼び出さなければならない正しいメソッドを知るために基底クラス群を横断しなくてもよくなります。基底クラスやクラス自身が修正されれば、Python の動的な振る舞いの面においても正しくあり続けなければならないので、キャッシュはクリアされます。 (Original optimization implemented by Armin Rigo, updated for Python 2.6 by Kevin Jacobs; bpo-1700288 [https://bugs.python.org/issue?@action=redirect&bpo=1700288].)

デフォルトではこの変更は、Python コアに含まれる型のみに適用されます。拡張モジュールは必ずしもこのキャッシュに互換ではなく、拡張モジュールはメソッドキャッシュを有効にするために、モジュールの tp_flags フィールドに明示的に Py_TPFLAGS_HAVE_VERSION_TAG を追加しなければなりません。(このメソッドキャッシュに対して互換であるためには、拡張モジュールのコードは、それが実装するどんな型についても tp_dict メンバに直接アクセスしたり修正したりしてはなりません。ほとんどのモジュールはこれをしていませんが、Python インタプリタがそれを検知することは出来ません。 bpo-1878 [https://bugs.python.org/issue?@action=redirect&bpo=1878] にいくらかの議論がありますので参照してください。)

キーワード引数を使う関数呼び出しが、素早くポインタで比較することで顕著に高速化しています。これは常に文字列丸ごとを比較する時間を省きます。 (Contributed by Raymond Hettinger, after an initial implementation by Antoine Pitrou; bpo-1819 [https://bugs.python.org/issue?@action=redirect&bpo=1819].)

struct モジュールの全ての関数が C で書き換えられました。「Need For Speed スプリント」での作業の成果です。 (Contributed by Raymond Hettinger.)

いくつかの標準ビルトイン型が、その型オブジェクトにビットをセットするようになりました。これは、オブジェクトがそれら型のサブクラスの一つであるかどうかのチェックするのを高速化します。 (Contributed by Neal Norwitz.)

Unicode 文字列が、空白文字と改行を検出するためのコードにより高速な実装を使うようになりました; split() メソッドでおよそ 25% の速度向上、 splitlines() メソッドでは 35% です。(Contributed by Antoine Pitrou.) Unicode 文字列データのために pymalloc を使うことでメモリ使用が減りました。

The with statement now stores the __exit__() method on the stack, producing a small speedup. (Implemented by Jeffrey Yasskin.)

メモリ使用を減らすために、一番作られたオブジェクトをガーベージコレクトする際に、ガーベージコレクタが内部のフリーリストをクリアするようになりました。これはオペレーティングシステムにすぐに返されます。

インタプリタの変更

Python のほかの実装で使うために、2 つのコマンドラインオプションが予約されました。 -J スイッチは Jython 固有のオプションのために予約されました。前提となる JVM に渡すスイッチなどに使います。 -X スイッチは個別の Python 実装、たとえば CPython、Jython や IronPython のために予約されました。Python 2.6 でどちらかのオプションが使われると、インタプリタはそのオプションは現在使われていないことを報告します。

Python インタプリタに -B スイッチを渡すか、インタプリタ実行前に環境変数 PYTHONDONTWRITEBYTECODE をセットするかのどちらかで、 .pyc や .pyo が作られないようにすることが出来るようになりました。この設定は Python プログラムから sys.dont_write_bytecode 変数として利用可能で、Python コードはこの変数を変更してインタプリタの振る舞いを変えることが出来ます。 (Contributed by Neal Norwitz and Georg Brandl.)

標準入力、標準出力、標準エラー出力に使うエンコーディングを、インタプリタ起動前に環境変数 PYTHONIOENCODING を設定することで指定出来るようになりました。値は <encoding> または <encoding>:<errorhandler> 形式の文字列でなければなりません。 encoding 部分はエンコーディングの名前で、例えば utf-8 や latin-1 です; 省略可能な errorhandler 部分はエンコーディングによって処理出来ない文字に対して何をするのかを指定するもので、 "error", "ignore", "replace" のどれかです。 (Contributed by Martin von Löwis.)

新しいモジュールと改良されたモジュール

全てのリリースに置いて、 Python の標準ライブラリはたくさんの改良とバグ修正がされてきました。ここでは一部の注目に値する変更を、モジュール名で辞書順ソートしてリストアップしています。もっと完全な変更リストが見たければ、ソースツリー内の Misc/NEWS ファイルか、全ての完全な詳細が入っている Subversion のログを参照してください。

The asyncore and asynchat modules are being actively maintained again, and a number of patches and bugfixes were applied. (Maintained by Josiah Carlson; see bpo-1736190 [https://bugs.python.org/issue?@action=redirect&bpo=1736190] for one patch.)

bsddb モジュールは新しいメンテナ Jesús Cea Avión を得て、パッケージは今ではスタンドアロンのパッケージとして入手可能です。パッケージのウェブページは www.jcea.es/programacion/pybsddb.htm [https://www.jcea.es/programacion/pybsddb.htm] です。このモジュールは Python 3.0 では標準ライブラリからは削除される予定です。というのも、これの更新ペースは Python のそれよりも遥かに頻繁だからです。

bsddb.dbshelve モジュールは pickle 化で、プロトコル 1 に制限するのではなく利用出来る一番高いプロトコルバージョンを使うようになりました。(Contributed by W. Barnes.)

The 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 [https://bugs.python.org/issue?@action=redirect&bpo=1817].)

The parse_qs() and parse_qsl() functions have been relocated from the cgi module to the urlparse module. The versions still available in the cgi module will trigger PendingDeprecationWarning messages in 2.6 (bpo-600362 [https://bugs.python.org/issue?@action=redirect&bpo=600362]).

cmath モジュールに大掛かりな改訂が行われました。Mark Dickinson と Christian Heimes による貢献です。5 つの新しい関数が追加されました:

polar() は複素数を極形式 (polar form) に変換し、複素数の絶対値 (modulus) と偏角 (argument) を返します。

rect() はその逆で、絶対値と偏角から対応する複素数に戻します。

phase() は複素数の偏角 (angle とも呼ばれています) を返します。

isnan() はその引数の実数部か虚数部のどちらかが NaN であれば真を返します。

isinf() はその引数の実数部か虚数部のどちらかが無限大であれば真を返します。

その改訂では、 cmath モジュールの数値的安定性も改善されました。全ての関数で、結果の実数部、虚数部は最小精度単位で少しの範囲内で、可能な限り正確です。詳細は bpo-1381 [https://bugs.python.org/issue?@action=redirect&bpo=1381] を見てください。 asinh(), atanh():, atan() に対する分岐截線 (branch cut) も修正されています。(--- 訳注: units of least precision に対する枯れた訳語はないようなので最小精度単位としていますが仮数部の最下位ビットのことです。ので、within a few ulps は下位数ビットという意味。分岐截線 (branch cut) は一般的な訳語かどうかはわかりませんが、wikipedia から採りました。---)

そのモジュールのテストは大変拡大しました; およそ 2000 の新たなテストケースが数学関数群を鍛え上げます。

IEEE 754 プラットフォームでは cmath モジュールは、IEEE 754 の特殊値と浮動小数点例外を、C99 標準の付録 'G' での一貫性のある方法で処理するようになりました。

A new data type in the collections module: 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:

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

Several places in the standard library that returned tuples have been modified to return namedtuple() instances. For example, the Decimal.as_tuple() method now returns a named tuple with sign, digits, and exponent fields.

(Contributed by Raymond Hettinger.)

collections モジュールのもう一つの変更は、 deque 型が省略可能な maxlen パラメータをサポートするようになったことです; 与えられると、 deque のサイズが要素数 maxlen を超えないように制限されます。お腹いっぱいの deque にさらに要素を追加すると、古いものから捨てられます。

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

(Contributed by Raymond Hettinger.)

The Cookie module's Morsel objects now support an httponly attribute. In some browsers. cookies with this attribute set cannot be accessed or manipulated by JavaScript code. (Contributed by Arvin Schnell; bpo-1638033 [https://bugs.python.org/issue?@action=redirect&bpo=1638033].)

curses モジュールの新しい window メソッド chgat() は、一行での指定数ぶん文字の表示属性を変更します。 (Contributed by Fabian Kreutz.)

# Boldface text starting at y=0,x=21
# and affecting the rest of the line.
stdscr.chgat(0, 21, curses.A_BOLD)

curses.textpad モジュールの Textbox クラスが上書きモードのほかに挿入モード編集をサポートするようになりました。挿入モードは Textbox インスタンス構築時に insert_mode パラメータを真にすることで有効になります。

datetime モジュールの strftime() メソッドが %f 書式化コードをサポートするようになりました。これはオブジェクトのマイクロ秒をミリ秒としてゼロ埋めで 6 桁で展開します。 (---訳注: 言葉だけだとどうしても伝わりにくいですが、フィールドとしてミリ秒を持たずにマイクロ秒を持っている datetime で「秒.ミリ秒」という表記をするのにマイクロ秒精度まで表示するのが目的です。ですので 654 ミリ秒が「654000」と書式化されますし、32 ミリ秒は「032000」です。---) (Contributed by Skip Montanaro; bpo-1158 [https://bugs.python.org/issue?@action=redirect&bpo=1158].)

The decimal module was updated to version 1.66 of the General Decimal Specification [https://speleotrove.com/decimal/decarith.html]. New features include some methods for some basic mathematical functions such as exp() and log10():

>>> Decimal(1).exp()
Decimal("2.718281828459045235360287471")
>>> Decimal("2.7182818").ln()
Decimal("0.9999999895305022877376682436")
>>> Decimal(1000).log10()
Decimal("3")

Decimal クラスの as_tuple() メソッドが sign, digits, exponent フィールドを持った名前付きタプルを返すようになりました。

(Implemented by Facundo Batista and Mark Dickinson. Named tuple support added by Raymond Hettinger.)

difflib モジュールの SequenceMatcher クラスが、マッチを a, b, size 属性を持つ名前付きタプルで返すようになりました。 (Contributed by Raymond Hettinger.)

ftplib.FTP クラスのコンストラクタと connect() メソッドに省略可能 timeout パラメータが追加されました。タイムアウトを秒で指定します。(Added by Facundo Batista.) また、 FTP クラスの storbinary() と storlines() メソッドが callback パラメータを新たに受け取ります。これはデータが送信されたあとでデータの各ブロックごとに呼び出されます。 (Contributed by Phil Schwartz; bpo-1221598 [https://bugs.python.org/issue?@action=redirect&bpo=1221598].)

ビルトイン関数の reduce() が functools モジュールでも利用可能です。Python 3.0 ではビルトイン関数は削除されて functools のものだけが使えます; 現在のところ 2.x シリーズでビルトイン版を削除する計画はありません。 (Patched by Christian Heimes; bpo-1739906 [https://bugs.python.org/issue?@action=redirect&bpo=1739906].) (---訳注: 2.7 でも削除されていません。使用を検出するには -3 オプションなどで警告をチェックしてください。 ---)

可能な場合には、 getpass モジュールはプロンプトメッセージ出力とパスワードの読み取りに /dev/tty を使うようになりました。利用出来ない場合は標準エラー出力と標準入力が使われます。端末に入力パスワードがエコーされるかもしれない場合、プロンプト表示の前に警告が出力されます。 (Contributed by Gregory P. Smith.)

glob.glob() 関数が、Unicode パスが使われるかディレクトリ内に Unicode ファイル名がマッチすると Unicode ファイル名を返すようになりました。 (bpo-1001604 [https://bugs.python.org/issue?@action=redirect&bpo=1001604])

heapq モジュールの新しい関数 merge(iter1, iter2, ...) は、任意の数のソートされたデータを返すイテラブルを取り、全てのイテラブルの内容をソートされた順に返す新しいジェネレータを返します (---訳注: 誤解を招く表現なので補足しておきますが、入力のイテレータはソート済みであることを「仮定」し、出力のジェネレータは「入力が主張している」順序に従うだけです。入力がソートされていなくても並べ替えられるわけではありません。リファレンスにはここはきちんと書かれています。---)。例えば:

>>> list(heapq.merge([1, 3, 5, 9], [2, 8, 16]))
[1, 2, 3, 5, 8, 9, 16]

もう一つの新たな関数 heappushpop(heap, item) は、 item を heap に push した後、pop を行って heap から最初の要素を返します。この一続きの動作を heappush() に引き続いて heappop() を別々に呼び出すよりも効率的に実行します。

heapq は以前使っていた「以下(<=)」比較ではなく「より小さい(<)」比較だけを使って実装されています。これにより heapq に格納する型の要件が list.sort() メソッドに合致します。 (Contributed by Raymond Hettinger.)

An optional timeout parameter, specifying a timeout measured in seconds, was added to the httplib.HTTPConnection and HTTPSConnection class constructors. (Added by Facundo Batista.)

getmoduleinfo() や getargs() のようなほとんどの inspect モジュール関数が、名前付きタプルを返すようになりました。タプルのように振る舞うだけでなく、属性でアクセスすることも出来ます。 (Contributed by Raymond Hettinger.)

モジュールには isgenerator(), isgeneratorfunction(), isabstract() を含むいくつかの新しい関数が追加されています。

itertools モジュールにいくつかの関数が追加されています。

izip_longest(iter1, iter2, ...[, fillvalue]) はそれぞれの要素群からタプルを生成します; イテラブルの要素数がほかのものより短ければ欠落値として fillvalue が埋められます。例えば:

>>> tuple(itertools.izip_longest([1,2,3], [1,2,3,4,5]))
((1, 1), (2, 2), (3, 3), (None, 4), (None, 5))

product(iter1, iter2, ..., [repeat=N]) は与えたイテラブルの直積 (Cartesian product)、つまりそれぞれのイテラブルから返るその要素たちの全てのありうる組み合わせを含むタプルの集合を返します。:

>>> 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)]

省略可能 repeat キーワード引数が与えられると、イテラブルが一つであればこれが N 個、複数あればそのセットが N 回与えられたとみなします。単一のイテラブルに対しては N 要素タプルのリストで返ります:

>>> 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)]

2 つのイテラブルであれば 2N 要素タプルのリストで返ります:

>>> 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)]

combinations(iterable, r) は、入力 iterable の要素からなる長さ r の部分列を返します (---訳注: 数学の初等組み合わせ論の「組合せ (combination)」 ---):

>>> 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')]

permutations(iter[, r]) は入力 iterable の長さ r の順列を返します。 r が指定されなければ、イテラブルが生成する全要素数がデフォルトで使われます (---訳注: 数学の初等組み合わせ論の「順列 (sequence without repetition)」または群論や組合せ論の「置換 (permutation)」。リファレンスでは訳出で置換も順列も両方出てきていますが、高校教育で習う用語で「順列」が伝わりやすいのでここでは「順列」としています。 ---):

>>> 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)]

itertools.chain(*iterables) は itertools に元々いたものですが、新しい構築方法が出来ました。Python 2.6 では、 itertools.chain.from_iterable(iterable) でほかのイテラブルを返す単一のイテラブルを取り、 chain() は、最初のイテラブルからの全要素、次のイテラブルからの全要素、…、のように返します:

>>> list(itertools.chain.from_iterable([[1,2,3], [4,5,6]]))
[1, 2, 3, 4, 5, 6]

(All contributed by Raymond Hettinger.)

logging モジュールの FileHandler クラスとそのサブクラスの WatchedFileHandler, RotatingFileHandler, TimedRotatingFileHandler がそのコンストラクタで省略可能 delay パラメータを受け取るようになりました。 delay が真の場合、ログファイルのオープンは最初の emit() が呼び出されるまで延期されます。 (Contributed by Vinay Sajip.)

TimedRotatingFileHandler ではコンストラクタに utc パラメータも取るようになっています。これが真の場合、 when='midnight' などの切り替え時刻判定とその生成ファイル名に UTC が使われます。

いくつかの新しい関数が math モジュールに追加されました:

isinf() と isnan() は与えられた浮動小数点数が、順に、(正または負の) 無限大であるかどうか、非数 (NaN=Not a Number) であるかどうかを返します。

copysign() は IEEE 754 数の符号ビットをコピーします。 x の絶対値と y の符号ビットを組み合わせたものを返します。例えば math.copysign(1, -0.0) は -1.0 を返します。 (Contributed by Christian Heimes.)

factorial() は階乗を計算します。 (Contributed by Raymond Hettinger; bpo-2138 [https://bugs.python.org/issue?@action=redirect&bpo=2138].)

fsum() はイテラブルからの数列を、部分和の計算を通じて精度の損失を避けながら積み上げた合計の計算をします。 (Contributed by Jean Brouwers, Raymond Hettinger, and Mark Dickinson; bpo-2819 [https://bugs.python.org/issue?@action=redirect&bpo=2819].)

acosh(), asinh(), atanh() は逆双曲線関数を計算します。

log1p() は 1+x の自然対数 (底 e の対数) を返します。

trunc() はゼロに向かう方向に丸めを行い、与えられた引数とゼロに最も近い Integral を返します。これは PEP 3141: 数値の型階層 のバックポートの一部として追加されました。

math モジュールは、特に浮動小数点例外と IEEE 754 の特殊値の処理において、プラットフォーム間に渡る振る舞いの一貫性をさらに高めるように改善されました。

可能な場合にはいつでもこのモジュールは 754 の特殊値について、C99 標準の勧告に従います。例えば、 sqrt(-1.) は今ではほとんど全てのプラットフォームで ValueError となるはずで、 sqrt(float('NaN')) は全ての IEEE 754 プラットフォームで NaN を返すはずです。C99 標準の付録 'F' で 'divide-by-zero' または 'invalid' を伝えることを勧告している箇所では Python は ValueError を投げます。C99 標準の付録 'F' で 'overflow' を伝えることを勧告している箇所では Python は OverflowError を投げます。 (See bpo-711019 [https://bugs.python.org/issue?@action=redirect&bpo=711019] and bpo-1640 [https://bugs.python.org/issue?@action=redirect&bpo=1640].)

(Contributed by Christian Heimes and Mark Dickinson.)

mmap オブジェクトに rfind() メソッドが追加されています。部分文字列の検索を、末尾から後ろ向きに検索します。 find() には新しい引数 end パラメータが追加されていて、検索対象の終了位置を指定することが出来ます。 (Contributed by John Lenton.)

operator モジュールに methodcaller() 関数が追加されています。名前と省略可能な引数を与えると、渡したその任意の引数でその名前の関数を呼び出す呼び出し可能オブジェクトを返します。例えば:

>>> # Equivalent to lambda s: s.replace('old', 'new')
>>> replacer = operator.methodcaller('replace', 'old', 'new')
>>> replacer('old wine in old bottles')
'new wine in new bottles'

(Contributed by Georg Brandl, after a suggestion by Gregory Petrosyan.)

attrgetter() 関数がドット付きの名前を受け付け、対応する属性ルックアップをするようになりました:

>>> inst_name = operator.attrgetter(
...        '__class__.__name__')
>>> inst_name('')
'str'
>>> inst_name(help)
'_Helper'

(Contributed by Georg Brandl, after a suggestion by Barry Warsaw.)

os モジュールがいくつか新しくシステムコールをラップしています。開いたファイルについて、 fchmod(fd, mode) はモードを変更し、 fchown(fd, uid, gid) は所有権を変更し、 lchmod(path, mode) はシンボリックリンクのモードを変更します。 (Contributed by Georg Brandl and Christian Heimes.)

chflags() と lchflags() は対応するシステムコール (利用可能であれば) へのラッパーで、ファイルのフラグを変更します。そのフラグ値についての定数が stat モジュールに定義されています; いくつかの取りうる値には、ファイルが変更されるべきではないことを伝える UF_IMMUTABLE 、ファイルにはデータの追記のみが可能であることを伝える UF_APPEND 、があります。 (Contributed by M. Levinson.)

os.closerange(low, high) は効率よく全ての low から high のファイルデスクリプタをクローズします。全てのエラーは無視されます。それと high はクローズ対象ではないです。この関数は既に subprocess モジュールがプロセスを開始するのを高速化するために使われています。 (Contributed by Georg Brandl; bpo-1663329 [https://bugs.python.org/issue?@action=redirect&bpo=1663329].)

os.environ オブジェクトの clear() メソッドが、オブジェクトのキーから取り除くだけでなく os.unsetenv() を使って環境変数を未設定にするようになりました。 (Contributed by Martin Horcicka; bpo-1181 [https://bugs.python.org/issue?@action=redirect&bpo=1181].)

os.walk() 関数に followlinks パラメータが追加されています。これを真にすると、シンボリックリンクが指す相手のディレクトリを渡り歩くようになります。後方互換のためにこのパラメータのデフォルトは偽です。なお、親ディレクトリを指すシンボリックリンクなど参照が循環していると、無限再帰に陥りますので注意してください。 (bpo-1273829 [https://bugs.python.org/issue?@action=redirect&bpo=1273829])

os.path モジュールの splitext() 関数が、先行するピリオドで分割しないように変更されています。これにより Unix のドットファイルの処理結果がよくなります。例えば os.path.splitext('.ipython') は ('', '.ipython') ではなく ('.ipython', '') を返すようになっています。 (bpo-1115886 [https://bugs.python.org/issue?@action=redirect&bpo=1115886])

新規関数 os.path.relpath(path, start='.') は、与えられれば start からの、与えられなければカレントディレクトリからの、目的地 path への相対パスを返します。 (Contributed by Richard Barran; bpo-1339796 [https://bugs.python.org/issue?@action=redirect&bpo=1339796].)

Windows において、 os.path.expandvars() が "%var%" 形式の記述に環境変数を展開し、 "~user" にユーザのホームディレクトリのパスを展開するようになりました。 (Contributed by Josiah Carlson; bpo-957650 [https://bugs.python.org/issue?@action=redirect&bpo=957650].) (---訳注: "~user" は実在した仕様かわかりません。2.7 に該当する実装もコメントも docstring もリファレンスもありませんし、当然この振る舞いは現在実在していません。---)

pdb モジュールで提供される Python デバッガに新たなコマンドが追加されました: "run" はデバッグ対象の Python プログラムを再起動します。またオプションとして、対象プログラムに与えるコマンドライン引数を渡せます。 (Contributed by Rocky Bernstein; bpo-1393667 [https://bugs.python.org/issue?@action=redirect&bpo=1393667].)

トレースバックのデバッグを開始するのに使われる pdb.post_mortem() が、トレースバックが与えられない場合に sys.exc_info() からの戻り値のトレースバックを使うようになりました。 (Contributed by Facundo Batista; bpo-1106316 [https://bugs.python.org/issue?@action=redirect&bpo=1106316].)

pickletools モジュールに optimize() 関数が追加されました。これは pickle を含んだ文字列を受け取って、未使用 opcode を削除の上で同じデータ構造を含んだより小さい pickle を返します。 (Contributed by Raymond Hettinger.)

pkgutil モジュールに get_data() 関数が追加されました。これはインストールされている Python パッケージに含まれるリソースファイルの内容を返します。例えば:

>>> import pkgutil
>>> print pkgutil.get_data('test', 'exception_hierarchy.txt')
BaseException
 +-- SystemExit
 +-- KeyboardInterrupt
 +-- GeneratorExit
 +-- Exception
      +-- StopIteration
      +-- StandardError
 ...

(Contributed by Paul Moore; bpo-2439 [https://bugs.python.org/issue?@action=redirect&bpo=2439].)

pyexpat モジュールの Parser オブジェクトで、 buffer_size 属性の設定により文字データの保持に使うバッファのサイズを変更出来るようになりました。 (Contributed by Achim Gaedke; bpo-1137 [https://bugs.python.org/issue?@action=redirect&bpo=1137].)

Queue モジュールが、エントリを違った順序で取り出すような queue の変種をサポートするようになっています。 PriorityQueue クラスはキューアイテムをヒープで格納し、それを優先順で取り出します。 LifoQueue クラスは、最後にエントリに追加されたものを最初に取り出します。つまり stack のように振舞うということです。 (Contributed by Raymond Hettinger.)

random モジュールの Random が、今では 32 ビットシステムで pickle 出来、64 ビットシステムで unpickle 出来、逆も出来ます。残念ながらこの変更は Python 2.6 の Random オブジェクトを以前の Python で正しく unpickle 出来ないことを意味します。 (Contributed by Shawn Ligocki; bpo-1727780 [https://bugs.python.org/issue?@action=redirect&bpo=1727780].)

新たな triangular(low, high, mode) は、三角分布 (triangular distribution) に従う乱数を生成します。 mode は分布内の最頻値で、返却値は high を含まない low と high の間です。 (Contributed by Wladmir van der Laan and Raymond Hettinger; bpo-1681432 [https://bugs.python.org/issue?@action=redirect&bpo=1681432].)

re モジュールによって実行される長い正規表現検索が届けられるシグナルをチェックするようになり、これにより多大な時間を要する検索を中断出来るようになります。 (Contributed by Josh Hoyt and Ralf Schmitt; bpo-846388 [https://bugs.python.org/issue?@action=redirect&bpo=846388].) (---訳注: 原文を忠実に訳すとわかりにくいですが、単に C のレベルでシグナルハンドラを仕掛けたので Python が割り込める、というのがここで言っていることです。本質的には「長い」や「時間のかかる」はあまり関係ないです。---)

正規表現モジュールは、小さな正規表現固有仮想マシン用のバイトコードをコンパイルすることで実装されています。信頼出来ないコードにより、悪意あるバイトコード文字列を直接作って破滅させることが出来ます。ですので、2.6 では正規表現バイトコードの検証をするようにしてあります。(Contributed by Guido van Rossum from work for Google App Engine; bpo-3487 [https://bugs.python.org/issue?@action=redirect&bpo=3487].)

rlcompleter モジュールの Completer.complete() メソッドが名前の評価時に引き起こされた例外を無視するようになりました。 (Fixed by Lorenz Quack; bpo-2250 [https://bugs.python.org/issue?@action=redirect&bpo=2250].)

sched モジュールの scheduler インスタンスが読み出し専用の queue 属性を持つようになりました。これはスケジューラのキュー内容を名前付きタプル (time, priority, action, argument) で返します。 (Contributed by Raymond Hettinger; bpo-1861 [https://bugs.python.org/issue?@action=redirect&bpo=1861].)

The select module now has wrapper functions for the Linux epoll() and BSD kqueue() system calls. modify() method was added to the existing poll objects; 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 [https://bugs.python.org/issue?@action=redirect&bpo=1657].)

shutil.copytree() が省略可能引数 ignore を取るようになっています。呼び出し可能オブジェクトを渡します。この呼び出し可能オブジェクトはそれぞれのディレクトリパスとその内容リストを受け取って、コピーせずに無視したい名前のリストを返します。

shutil モジュールでは同時に、この新たなパラメータのために使える ignore_patterns() も提供しています。 ignore_patterns() は任意の数の glob スタイルのパターンを取り、これらパターンに合致する任意のファイルとディレクトリを無視する呼び出し可能オブジェクトを返します。以下は、 .svn ディレクトリと '~' で終わるファイル名を持つ Emacs のバックアップファイルをスキップしてディレクトリコピーをする例です:

shutil.copytree('Doc/library', '/tmp/library',
                ignore=shutil.ignore_patterns('*~', '.svn'))

(Contributed by Tarek Ziadé; bpo-2663 [https://bugs.python.org/issue?@action=redirect&bpo=2663].)

Tkinter や GTK+ などのような場所で、シグナルハンドリングと GUI 処理のイベントループを組み合わせることは、長い間悩みの種でした; ほとんどのソフトウェアはポーリングを行って、わずかばかりの時間で起き上がっては GUI イベントが起きていないかチェックするハメになっています。 signal モジュールが、これをより効率的に行えるようにしました。 signal.set_wakeup_fd(fd) でファイルデスクリプタをセットすると、イベント受信時にファイルデスクリプタにバイトが書き込まれます。 C レベルの関数 PySignal_SetWakeupFd() もあります。同じくファイルデスクリプタを渡します。

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 set_wakeup_fd(), and the readable descriptor will be added to the list of descriptors monitored by the event loop via select() or poll(). On receiving a signal, a byte will be written and the main event loop will be woken up, avoiding the need to poll.

(Contributed by Adam Olsen; bpo-1583 [https://bugs.python.org/issue?@action=redirect&bpo=1583].)

siginterrupt() 関数が Python コードから利用可能になりました。対象シグナルがシステムコールを中断出来るかどうかを変更出来ます。 (Contributed by Ralf Schmitt.)

setitimer(), getitimer() 関数も追加されています (利用可能であれば)。 setitimer() は、指定時間経過後に処理にシグナルを届けます。時間は「壁時計時間 (wall-clock time)」(訳注: リファレンスでは「実時間」と表現している)、「プロセスの実行時間 (consumed process time)」、またはプロセス + システム時間の組合せで指定します。(Contributed by Guilherme Polo; bpo-2240 [https://bugs.python.org/issue?@action=redirect&bpo=2240].)

smtplib モジュールが、 SMTP_SSL クラスの追加によって SMTP over SSL をサポートするようになっています。このクラスは既存の SMTP と同じインターフェイスです。(Contributed by Monty Taylor.) 両方のクラスのコンストラクタでは新たに省略可能な timeout パラメータを取ります。最初に接続を試みる際のタイムアウト値を秒で指定します。(Contributed by Facundo Batista.)

LMTP プロトコル (RFC 2033 [https://datatracker.ietf.org/doc/html/rfc2033.html]) 実装もモジュールに追加されています。LMTP はメールキューを管理しないエージェント間で e-mail を転送する際に、SMTP の代わりに使われます。(LMTP implemented by Leif Hedstrom; bpo-957003 [https://bugs.python.org/issue?@action=redirect&bpo=957003].)

SMTP.starttls() は今や RFC 3207 [https://datatracker.ietf.org/doc/html/rfc3207.html] 遵守であり、TLS ネゴシエーション自身で得たのでないサーバから得られるいかなる知識も記憶しません。(Patch contributed by Bill Fenner; bpo-829951 [https://bugs.python.org/issue?@action=redirect&bpo=829951].)

The socket module now supports TIPC (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 [https://bugs.python.org/issue?@action=redirect&bpo=1646].)

新規の create_connection() 関数はアドレスを取り、省略可能なタイムアウト値を使って接続を行い、接続されたソケットオブジェクトを返します。この関数は同時に、アドレスのタイプを調べて IPv4 と IPv6 の相応しい方を使って接続します。あなたのコードが socket(socket.AF_INET, ...) を使う代わりに create_connection() に乗り換えることは、それが IPv6 対応で必要なこと全て、となるでしょう。

The base classes in the SocketServer module now support calling a handle_timeout() method after a span of inactivity specified by the server's timeout attribute. (Contributed by Michael Pomraning.) The 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 [https://bugs.python.org/issue?@action=redirect&bpo=742598], bpo-1193577 [https://bugs.python.org/issue?@action=redirect&bpo=1193577].)

Gerhard Häring により保守されている sqlite3 モジュールが、Python 2.5 時のバージョン 2.3.2 からバージョン 2.4.1 に更新されました。

The struct module now supports the C99 _Bool type, using the format character '?'. (Contributed by David Remahl.)

The Popen objects provided by the subprocess module now have terminate(), kill(), and send_signal() methods. On Windows, send_signal() only supports the SIGTERM signal, and all these methods are aliases for the Win32 API function TerminateProcess(). (Contributed by Christian Heimes.)

sys モジュールに新たに追加された変数 float_info は、 float.h に由来するプラットフォームの浮動小数点数サポートについての情報を含んだオブジェクトです。このオブジェクトの属性としては、 mant_dig (仮数部の桁数)、 epsilon (1.0 と、それより大きい表現可能な最小値との差)などがあります。 (Contributed by Christian Heimes; bpo-1534 [https://bugs.python.org/issue?@action=redirect&bpo=1534].)

もう一つの新たな変数 dont_write_bytecode は Python がモジュールインポート時に .pyc や .pyo を作るかどうかを制御します。この変数が真ならば、コンパイル済みファイルは作られません。この変数は Python インタプリタを -B スイッチ付きで起動するか環境変数 PYTHONDONTWRITEBYTECODE をセットすることで初期設定されます。Python コードはこのあとでこの変数の値を変更することで、バイトコードファイルを作るかどうかを制御出来ます。 (Contributed by Neal Norwitz and Georg Brandl.)

Python インタプリタに与えられたコマンドライン引数についての情報を、 sys.flags として利用可能な名前付きタプルで知ることが出来ます。例えば Python が冗長モードで起動された場合は verbose 属性は真となり、デバッグモードでは debug 属性が真、などです。これら属性は全て読み出し専用です。 (Contributed by Christian Heimes.)

新しい関数 getsizeof() が追加されました。 Python オブジェクトを受け取り、そのオブジェクトが利用しているメモリサイズをバイト単位で返します。ビルトインオブジェクトは正確な結果を返しますが、サードパーティの拡張は正確な値を返さないかもしれません。その場合 __sizeof__() メソッドを定義してオブジェクトのサイズを返すことができます。 (Robert Schuppenies による貢献. bpo-2898 [https://bugs.python.org/issue?@action=redirect&bpo=2898])

現在動作中のプロファイラとトレーサーを、 sys.getprofile() と sys.gettrace() で知ることが出来るようになりました。 (Contributed by Georg Brandl; bpo-1648 [https://bugs.python.org/issue?@action=redirect&bpo=1648].)

tarfile モジュールが、既にサポートされている POSIX.1-1988 (ustar) と GNU tar フォーマットに加えて、POSIX.1-2001 (pax) をサポートするようになりました。デフォルトは GNU tar です; これと違うフォーマットでファイルを開くには format パラメータで指定します:

tar = tarfile.open("output.tar", "w",
                   format=tarfile.PAX_FORMAT)

新しい encoding と errors パラメータはエンコーディングと文字変換のエラー処理方法を指定します。 'strict', 'ignore', 'replace' は Python の 3 つの標準エラー処理です; 'utf-8' は特殊で、不正な文字を、それの UTF-8 表現に置き換えます。(文字変換は、PAX フォーマットが Unicode ファイル名をサポートするために現れ、デフォルトは UTF-8 エンコーディングです。)

The TarFile.add() method now accepts an 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 add() and to the names of files in recursively added directories.

(All changes contributed by Lars Gustäbel).

An optional timeout parameter was added to the telnetlib.Telnet class constructor, specifying a timeout measured in seconds. (Added by Facundo Batista.)

tempfile.NamedTemporaryFile クラスは普通はこれが作った一時ファイルを、ファイルクローズ時に削除します。この振る舞いを、コンストラクタのパラメータに delete=False を渡すことで変更出来るようになりました。 (Contributed by Damien Miller; bpo-1537850 [https://bugs.python.org/issue?@action=redirect&bpo=1537850].)

新しいクラス SpooledTemporaryFile は一時ファイルのように振舞いますが、そのデータは最大サイズを超えるまではメモリ内に格納されます。その制限を超えると、その内容がディスク上の一時ファイルに書き込まれます。 (Contributed by Dustin J. Mitchell.)

NamedTemporaryFile と SpooledTemporaryFile のともにコンテキストマネージャとして動作しますので、 with tempfile.NamedTemporaryFile() as tmp: ... のように書くことが出来ます。 (Contributed by Alexander Belopolsky; bpo-2021 [https://bugs.python.org/issue?@action=redirect&bpo=2021].)

The test.test_support module gained a number of context managers useful for writing tests. EnvironmentVarGuard() is a context manager that temporarily changes environment variables and automatically restores them to their old values.

もう一つのコンテキストマネージャ TransientResource は、利用出来るかもしれないし出来ないかもしれないリソースの呼び出しを包むことが出来ます; 指定した例外リストを捕捉して無視します(---訳注: この紹介、良くないと思うのと、多分著者が誤解してます。確かに属性名/属性値を特定してこれに一致する場合にだけ例外を受け取るためのものなので、一致しないものは無視、という事実には反しませんが、「狙った例外は受け取る(ResourceDenied)」でもあるはずです。「期待した例外が発生する」ことをテストしたいでしょう、「期待しない例外はテストには関係ない」であるとともに。それとリファレンスと docstring によれば「指定した例外と属性に合致する場合に ResourceDenied」と言っているので、やはり事実とは反しています。---)。例えば、ネットワークのテストでは外部のウェブサイトとの接続時の特定の失敗を無視するでしょう:

with test_support.TransientResource(IOError,
                                errno=errno.ETIMEDOUT):
    f = urllib.urlopen('https://sf.net')
    ...

最後に、 check_warnings() は warning モジュールの警告フィルタをリセットして、全ての引き起こされる警告メッセージを記録するオブジェクトを返します (bpo-3781 [https://bugs.python.org/issue?@action=redirect&bpo=3781]):

with test_support.check_warnings() as wrec:
    warnings.simplefilter("always")
    # ... code that triggers a warning ...
    assert str(wrec.message) == "function is outdated"
    assert len(wrec.warnings) == 1, "Multiple warnings raised"

(Contributed by Brett Cannon.)

The textwrap module can now preserve existing whitespace at the beginnings and ends of the newly created lines by specifying drop_whitespace=False as an argument:

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

(Contributed by Dwayne Bailey; bpo-1581073 [https://bugs.python.org/issue?@action=redirect&bpo=1581073].)

threading モジュールの API が、 setDaemon(), isDaemon() メソッドではなく daemon のようにプロパティを使うように変更中です。また、いくつかのメソッドはキャメルケースではなくアンダースコアスタイルに名前変更されています; 例えば activeCount() メソッドは active_count() にリネームされます。2.6 と 3.0 の両バージョンのモジュールは同じプロパティとリネームされたメソッドをサポートしますが、古いメソッドは削除されません。古い API が Python 3.x で撤廃するのがいつになるのかは未定です; 2.x バージョンでは削除されないでしょう。 (Carried out by several people, most notably Benjamin Peterson.) (--- 訳注: 3.5 でもこの状態は続いたままです。今でもキャメルケーススタイルのメソッドが使えます。ですが、もちろん新しい名前を使うべきです。---)

threading モジュールの Thread オブジェクトに ident プロパティが追加されています。スレッドの識別子を非ゼロの整数で返します。 (Contributed by Gregory P. Smith; bpo-2871 [https://bugs.python.org/issue?@action=redirect&bpo=2871].)

timeit モジュールが、計測されるステートメントとセットアップコードとして、文字列だけでなく呼び出し可能オブジェクトを渡せるようになりました。 Timer インスタンスを作成する 2 つの便利関数が追加されています: repeat(stmt, setup, time, repeat, number) と timeit(stmt, setup, time, number) で、インスタンスを作成して対応するメソッドを呼びます。 (Contributed by Erik Demaine; bpo-1533909 [https://bugs.python.org/issue?@action=redirect&bpo=1533909].)

Tkinter モジュールが、オプションとしてリストとタプルを受け付けるようになっています。Tcl/Tk へは空白区切りの文字列にして渡されます。 (Contributed by Guilherme Polo; bpo-2906 [https://bugs.python.org/issue?@action=redirect&bpo=2906].)

タートルグラフィックスのための turtle モジュールが Gregor Lingl により大幅に拡張されました。モジュールの新しい機能は次の通りです:

亀の移動と回転のアニメーションの改善。

新しい delay() メソッド、 tracer() メソッド、 speed() メソッドを使って亀の動きをコントロールできるようになりました。

亀に新しい姿を設定できたり、新しい座標系を定義できるようになりました。

亀に、動作を巻き戻せる undo() メソッドが増えました。

マウスやキーボードからの入力イベントに反応するための簡易なサポートが入り、簡単なゲームを書けるようになりました。

turtle.cfg を使って、turtle の画面の起動時の見た目をカスタマイズできるようになりました。

モジュールの docstring が、他の言語に翻訳された docstring に置き換えられるようになりました。

(bpo-1513695 [https://bugs.python.org/issue?@action=redirect&bpo=1513695])

An optional timeout parameter was added to the urllib.urlopen function and the urllib.ftpwrapper class constructor, as well as the urllib2.urlopen function. The parameter specifies a timeout measured in seconds. For example:

>>> u = urllib2.urlopen("http://slow.example.com",
                        timeout=3)
Traceback (most recent call last):
  ...
urllib2.URLError: <urlopen error timed out>
>>>

(Added by Facundo Batista.)

unicodedata モジュールで提供される Unicode データベースが、バージョン 5.1.0 に更新されました。 (Updated by Martin von Löwis; bpo-3811 [https://bugs.python.org/issue?@action=redirect&bpo=3811].)

warnings モジュールの formatwarning() と showwarning() に省略可能な line 引数が追加されました。ソースコードの行番号を与えることが出来ます。 (Added as part of bpo-1631171 [https://bugs.python.org/issue?@action=redirect&bpo=1631171], which re-implemented part of the warnings module in C code.)

新しい関数 catch_warnings() はコンテキストマネージャで、テスト目的で警告フィルタを一時的に変更して元に戻すのに使えます。 (bpo-3781 [https://bugs.python.org/issue?@action=redirect&bpo=3781]).

The XML-RPC SimpleXMLRPCServer and DocXMLRPCServer classes can now be prevented from immediately opening and binding to their socket by passing False as the bind_and_activate constructor parameter. This can be used to modify the instance's allow_reuse_address attribute before calling the server_bind() and server_activate() methods to open the socket and begin listening for connections. (Contributed by Peter Parente; bpo-1599845 [https://bugs.python.org/issue?@action=redirect&bpo=1599845].)

SimpleXMLRPCServer はさらに _send_traceback_header 属性を持つようになりました。真の場合、例外とフォーマットされたトレースバックが HTTP ヘッダ "X-Exception" と "X-Traceback" として返ります。この機能はデバッグのみに使い、製品のサーバには使ってはなりません。トレースバックには剥き出しのパスワードが含まれるかもしれず、あるいはほかの何か企業秘密だったり国家秘密だったりするような繊細な情報満載かもしれないのです。 (Contributed by Alan McIntyre as part of his project for Google's Summer of Code 2007.)

The xmlrpclib module no longer automatically converts datetime.date and datetime.time to the xmlrpclib.DateTime type; the conversion semantics were not necessarily correct for all applications. Code using xmlrpclib should convert date and time instances. (bpo-1330538 [https://bugs.python.org/issue?@action=redirect&bpo=1330538]) The code can also handle dates before 1900 (contributed by Ralf Schmitt; bpo-2014 [https://bugs.python.org/issue?@action=redirect&bpo=2014]) and 64-bit integers represented by using <i8> in XML-RPC responses (contributed by Riku Lindblad; bpo-2985 [https://bugs.python.org/issue?@action=redirect&bpo=2985]).

zipfile モジュールの ZipFile クラスに extract() メソッドと extractall() メソッドが追加されました。アーカイブ内の、それぞれ単一ファイル、全てのファイルを、カレントディレクトリか指定のディレクトリに展開します:

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()

(Contributed by Alan McIntyre; bpo-467924 [https://bugs.python.org/issue?@action=redirect&bpo=467924].)

open(), read(), extract() メソッドはファイル名か ZipInfo オブジェクトのどちらかを受け取れるようになっています。これは誤って重複したファイル名を含んでいるアーカイブで有用でしょう。 (Contributed by Graham Horler; bpo-1775025 [https://bugs.python.org/issue?@action=redirect&bpo=1775025].)

最後に、 zipfile がアーカイブするファイルのファイル名として Unicode の使用をサポートするようになりました。 (Contributed by Alexey Borzenkov; bpo-1734346 [https://bugs.python.org/issue?@action=redirect&bpo=1734346].) (---訳注: リファレンスに注意事項として書かれていますが、zip ファイルのファイル名標準は存在しないのでこれは問題を起こすことがあります。---)

ast モジュール

ast モジュールは Python コードの抽象構文木 (Abstract Syntax Tree) 表現を提供します。また、Armin Ronacher は共通タスクを実行するさまざまなヘルパー関数を寄稿しました。これらは HTML テンプレートパッケージであるとか、コードアナライザ、などなどの、Python コードを処理するツールで有用となるでしょう。

parse() 関数は式を受け取り AST を返します。 dump() 関数はツリー表現をデバッギングに相応しい出力をします:

import ast

t = ast.parse("""
d = {}
for i in 'abcdefghijklm':
    d[i + i] = ord(i) - ord('a') + 1
print d
""")
print ast.dump(t)

これの出力は深くネストされたツリーです:

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)
 ])

literal_eval() メソッドは、文字列またはリテラル式を表現する AST を受け取り解析と評価を行い、結果の値を返します。リテラル式は、文字列、数値、辞書などのみを含む Python 式で、文や関数呼び出しを含みません。もしもあなたに式を評価する必要があって、だけれども eval() を呼び出すことによるセキュリティリスクを許容出来ないということであれば、 literal_eval() がそれを安全に処理してくれます:

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

モジュールには、AST を横断し、修正するための NodeVisitor と NodeTransformer クラス、例えば行番号の変更などの共通的な変形を行う関数群が含まれています。

future_builtins モジュール

Python 3.0 はビルトイン関数のレポジトリにたくさんの変更を加えていて、そのほとんどが互換性を破壊するため Python 2.x シリーズには導入出来ません。 future_builtins モジュールは 3.0 互換コードを書くのにインポート出来る 3.0 互換関数セットです。

このモジュールに今のところ含まれるのは:

ascii(obj): 2.x の repr() と同じことをします。Python 3.0 では repr() は Unicode 文字列を返すようになっていて、一方 ascii() は純粋な ASCII バイト文字列を返します。

filter(predicate, iterable), map(func, iterable1, ...): 3.0 と同じようにイテレータを返し、これは 2.x のビルトインがリストで返すのとは違っています。

hex(value), oct(value): __hex__() と __oct__() メソッドを呼び出すのではなく、 __index__() メソッドを呼び出した結果を hexadecimal または octal に変換します。こちらのバージョンの oct() は新しい 0o 記法で返却します。

json モジュール: JavaScript オブジェクト記法

新しい json モジュールは、JSON (Javascript Object Notation) と Python 型のエンコーディング、デコーディングをサポートします。JSON は軽量なデータ交換フォーマットで、頻繁にウェブアプリケーションで使われます。JSON の詳細情報は http://www.json.org にあります。

json モジュールはほとんどのビルトイン型のデコーディングとエンコーディングサポートを備えています。以下の例は辞書のエンコードとデコードをしています:

>>> import json
>>> data = {"spam": "foo", "parrot": 42}
>>> in_json = json.dumps(data) # Encode the data
>>> in_json
'{"parrot": 42, "spam": "foo"}'
>>> json.loads(in_json) # Decode into a Python object
{"spam": "foo", "parrot": 42}

ほかの何か型をサポートするのに独自のエンコーダ、デコーダを書くことも出来ます。JSON 文字列の pretty-printing もサポートされています。

json (もともと simplejson と呼ばれていました) は Bob Ippolito によって書かれました。

plistlib モジュール: プロパティリストパーサ

.plist フォーマットは Mac OS X で一般的に使われ、基本的なデータ型(数値、文字列、リスト、辞書)を XML ベースのフォーマットにシリアライズして格納します。データ型の XML-RPC シリアライズに似ています。

Mac OS X で主に使われるとはいえ、そのフォーマットはまったく Mac 固有ではなくその Python 実装は Python がサポートするあらゆるプラットフォームで動作するので、plistlib は標準ライブラリに昇格しました。

モジュールを使うのは単純です:

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)

ctypes の強化

Thomas Heller は ctypes モジュールの保守と拡張を続けました。

ctypes は今では C99 bool 型を表す c_bool データ型をサポートします。 (Contributed by David Remahl; bpo-1649190 [https://bugs.python.org/issue?@action=redirect&bpo=1649190].)

ctypes の string, buffer, array 型が拡張スライスインデクス構文をサポートするように改善され、 (start, stop, step) の色々な組み合わせが使えます。 (Implemented by Thomas Wouters.)

全ての ctypes データ型が from_buffer(), from_buffer_copy() メソッドをサポートするようになりました。これは与えられた buffer オブジェクトに基く ctypes インスタンスを作ります。 from_buffer_copy() はそのオブジェクトの内容をコピーし、 from_buffer() はその同じメモリ領域を共有します。

新しい呼び出しの慣例は、 ctypes にそれぞれのラップされた呼び出しの発生時に errno あるいは Win32 LastError 変数をクリアすることを伝えることです。 (Implemented by Thomas Heller; bpo-1798 [https://bugs.python.org/issue?@action=redirect&bpo=1798].)

Unix errno 変数を関数呼び出し後に抽出できるようになっています。ラップされた関数を作る際、 use_errno=True を DLL() 関数へのキーワード引数として渡すことが出来、それによりモジュールレベル関数の set_errno() と get_errno() を、 errno 値を設定・取得するのに呼び出せます。

Win32 LastError は DLL(), OleDLL(), WinDLL() 関数で同じようにサポートされています。同じように use_last_error=True を与え、モジュールレベル関数 set_last_error() と get_last_error() を使います。

ctypes インスタンスへのポインタを抽出にするのに使われる byref() 関数が、省略可能な offset パラメータを受け取るようになりました。これは返されるポインタに追加されるバイト数です。

SSL サポートの改善

Bill Janssen は Python 2.6 の Secure Sockets Layer サポートを大掛かりに改善しました。行われたのは新モジュール ssl の追加です。これは OpenSSL [https://www.openssl.org/] ライブラリの上に構築されています。この新しいモジュールはプロトコルのネゴシエイトのさらなる制御、X.509 証明書の使用、そして SSL サーバ (クライアントの対語としての) を Python で書くためのより良いサポートを提供しています。既存の socket モジュールにある SSL サポートは削除されずにそのまま使えますが、Python 3.0 では削除されます。

この新たなモジュールを使うには、まず最初にいつものやり方で TCP コネクションを作らなければなりません。そしてその上でそれを ssl.wrap_socket() 関数に渡します (---訳注: 2.7.9 ではさらに進化した SSLContext.wrap_socket が使えます ---)。証明書が必要かどうかを指定することが出来、証明書の情報を getpeercert() メソッドで取得することも出来ます。

参考

ssl モジュールについてのドキュメント。

非推奨と削除

文字列を例外として送出することは出来なくなりました。これをすると TypeError を起こします。

Changes to the Exception interface as dictated by PEP 352 [https://peps.python.org/pep-0352/] continue to be made. For 2.6, the message attribute is being deprecated in favor of the args attribute.

(3.0 警告モード) Python 3.0 はたくさんの時代遅れのモジュールを削除し、ほかのものも名前変更するような標準ライブラリの再編成が特色となります。Python 2.6 を 3.0 警告モードで動かすと、それらがインポートされる際に警告が励起されます。

The list of deprecated modules is: audiodev, bgenlocations, buildtools, bundlebuilder, Canvas, compiler, dircache, dl, fpformat, gensuitemodule, ihooks, imageop, imgfile, linuxaudiodev, mhlib, mimetools, multifile, new, pure, statvfs, sunaudiodev, test.testall, and toaiff.

The gopherlib module has been removed.

The MimeWriter module and mimify module have been deprecated; use the email package instead.

The md5 module has been deprecated; use the hashlib module instead.

The posixfile module has been deprecated; fcntl.lockf() provides better locking.

The popen2 module has been deprecated; use the subprocess module.

The rgbimg module has been removed.

The sets module has been deprecated; it's better to use the built-in set and frozenset types.

The sha module has been deprecated; use the hashlib module instead.

ビルドならびに C API の変更

Python のビルド過程と C API の変更は以下の通りです:

Python now must be compiled with C89 compilers (after 19 years!). This means that the Python source tree has dropped its own implementations of memmove() and strerror(), which are in the C89 standard library.

Python 2.6 は Microsoft Visual Studio 2008 (version 9.0) でビルド出来ます。そしてこれが新しいデフォルトコンパイラです。 PCbuild ディレクトリのビルドファイルを参照して下さい。 (Implemented by Christian Heimes.)

Mac OS X では、Python 2.6 は 4 種類のユニバーサルビルドでコンパイル出来ます。 configure スクリプトは --with-universal-archs=[32-bit|64-bit|all] スイッチを取って、32-bit アーキテクチャ (x86, PowerPC), 64-bit (x86-64 and PPC-64), あるいは両方のバイナリをビルド出来ます。 (Contributed by Ronald Oussoren.)

A new function added in Python 2.6.6, PySys_SetArgvEx(), sets the value of sys.argv and can optionally update sys.path to include the directory containing the script named by 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, PySys_SetArgv(), would always update 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 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 PySys_SetArgv() and carefully consider whether the application should be using 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 PySys_SetArgv() alone and call PyRun_SimpleString("sys.path.pop(0)\n") afterwards to discard the first sys.path component.

Security issue reported as CVE-2008-5983 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2008-5983]; discussed in gh-50003 [https://github.com/python/cpython/issues/50003], and fixed by Antoine Pitrou.

BerkeleyDB モジュールが C API オブジェクトを公開しています。 bsddb.db.api として利用可能です。このモジュールは bsddb モジュールを自身の独自の目的で使いたいほかの C 拡張で使えます。 (Contributed by Duncan Grisby.)

PEP 3118 改訂版バッファプロトコル で前述の新しいバッファインターフェイスのために、 PyObject_GetBuffer() と PyBuffer_Release() とほか少しの関数が追加されました。

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 PyFile_IncUseCount() and PyFile_DecUseCount() functions. File objects can't be closed unless the reference count is zero. PyFile_IncUseCount() should be called while the GIL is still held, before carrying out an I/O operation using the FILE * pointer, and PyFile_DecUseCount() should be called immediately after the GIL is re-acquired. (Contributed by Antoine Pitrou and Gregory P. Smith.)

異なるスレッドから同時にモジュールをインポートすることでデッドロックが発生することはなくなりました; 今では ImportError になります。新たな API 関数 PyImport_ImportModuleNoBlock() は最初に sys.modules を探し、インポートロック獲得後にインポートしようと試みます。インポートロックが他のスレッドにより獲得されていれば ImportError が発生します。(Contributed by Christian Heimes.)

いくつかの関数が、プラットフォームの浮動小数点サポートについての情報を返します。 PyFloat_GetMax() は浮動小数点数で表現出来る最大値を返し、 PyFloat_GetMin() は正の最小値を返します。 PyFloat_GetInfo() は float.h からの情報を含むオブジェクトを返し、これには "mant_dig" (仮数部桁数)、 "epsilon" (1.0 とそれより大きい表現可能な最小値との差)やほかのいくつかの情報を含みます。 (Contributed by Christian Heimes; bpo-1534 [https://bugs.python.org/issue?@action=redirect&bpo=1534].)

PyComplex_AsCComplex() を使う C 関数とメソッドが __complex__() メソッドを持つ引数を受け付けるようになっています。特に、 cmath モジュールにある関数は、このメソッドを持つオブジェクトを受け付けます。これは Python 3.0 での変更のバックポートです。 (Contributed by Mark Dickinson; bpo-1675423 [https://bugs.python.org/issue?@action=redirect&bpo=1675423].)

Python C API に 2 つの大文字小文字を区別しない文字列比較関数 PyOS_stricmp(char*, char*) と PyOS_strnicmp(char*, char*, Py_ssize_t) が追加されました。 (Contributed by Christian Heimes; bpo-1635 [https://bugs.python.org/issue?@action=redirect&bpo=1635].)

多くの C 拡張が、 init* 関数内でモジュール辞書に整数と文字列定数を追加するために独自の小さなマクロを定義しています。 Python 2.6 ではついにモジュールに値を追加する標準マクロを定義しました。 PyModule_AddStringMacro と PyModule_AddIntMacro() です。 (Contributed by Christian Heimes.)

Some macros were renamed in both 3.0 and 2.6 to make it clearer that they are macros, not functions. Py_Size() became Py_SIZE(), Py_Type() became Py_TYPE(), and Py_Refcnt() became Py_REFCNT(). The mixed-case macros are still available in Python 2.6 for backward compatibility. (bpo-1629 [https://bugs.python.org/issue?@action=redirect&bpo=1629])

Distutils は C 拡張を、デバッグバージョンの Python 実行時に別のディレクトリにビルドするようになりました。 (Contributed by Collin Winter; bpo-1530959 [https://bugs.python.org/issue?@action=redirect&bpo=1530959].)

いくつかの基本データ型、例えば数値や文字列型は、あとで再利用されるオブジェクトのフリーリスト(---訳注: メモリ管理での alloc/free の free。---)を内部的に管理しています。それらデータ構造はこのフリーリストに関して、命名規約に従うようにしました; その変数名は常に free_list 、カウンタは常に numfree 、そしてマクロ Py<typename>_MAXFREELIST が必ず定義されます。

新たに追加された Makefile のターゲット "make patchcheck" は、Python ソースツリーに対してパッチを作る準備をします: 修正された .py ファイル全てに含まれる末尾の余分な空白を取り除き、ドキュメンテーションが変更されているかをチェックし、そして Misc/ACKS と Misc/NEWS が更新されているかどうかを報告します。 (Contributed by Brett Cannon.)

もう一つの新しいターゲット "make profile-opt" は、GCC の profile-guided 最適化を使った Python バイナリをビルドします。これは Python をプロファイリングを有効にしてビルドし、プロファイル結果のセットを得るためのテストスイートを実施し、そして最適化のためにそれら結果を使ってビルドします。 (Contributed by Gregory P. Smith.)

ポート特有の変更: Windows

Windows 95, 98, ME, NT4 のサポートはとりやめられました。 Python 2.6 は最低でも Windows 2000 SP4 が必要です。

Windows での新しいデフォルトコンパイラが Visual Studio 2008 (version 9.0) になっています。Visual Studio 2003 (version 7.1) と 2005 (version 8.0) のビルドディレクトリは PC/ に移動しました。新しい PCbuild ディレクトリは X64, デバッグビルド、Profile Guided Optimization (PGO) をサポートしています。PGO ビルドは通常ビルドに較べておよそ 10% 高速化になります。 (Contributed by Christian Heimes with help from Amaury Forgeot d'Arc and Martin von Löwis.)

The msvcrt module now supports both the normal and wide char variants of the console I/O API. The getwch() function reads a keypress and returns a Unicode value, as does the getwche() function. The putwch() function takes a Unicode character and writes it to the console. (Contributed by Christian Heimes.)

os.path.expandvars() は "%var%" 形式を環境変数で置換し、 "~user" をユーザのホームディレクトリパスに置換します(---訳注: 上のほうの訳注参照。---)。 (Contributed by Josiah Carlson; bpo-957650 [https://bugs.python.org/issue?@action=redirect&bpo=957650].)

The socket module's socket objects now have an ioctl() method that provides a limited interface to the WSAIoctl() system interface.

The _winreg module now has a function, ExpandEnvironmentStrings(), that expands environment variable references such as %NAME% in an input string. The handle objects provided by this module now support the context protocol, so they can be used in with statements. (Contributed by Christian Heimes.)

_winreg also has better support for x64 systems, exposing the DisableReflectionKey(), EnableReflectionKey(), and QueryReflectionKey() functions, which enable and disable registry reflection for 32-bit processes running on 64-bit systems. (bpo-1753245 [https://bugs.python.org/issue?@action=redirect&bpo=1753245])

The msilib module's Record object gained GetInteger() and GetString() methods that return field values as an integer or a string. (Contributed by Floris Bruynooghe; bpo-2125 [https://bugs.python.org/issue?@action=redirect&bpo=2125].)

ポート特有の変更: Mac OS X

Python をフレームワークビルドでコンパイルする際に、 configure スクリプトに --with-framework-name オプションでフレームワーク名を指定出来るようになりました。

The macfs module has been removed. This in turn required the macostools.touched() function to be removed because it depended on the macfs module. (bpo-1490190 [https://bugs.python.org/issue?@action=redirect&bpo=1490190])

Many other Mac OS modules have been deprecated and will be removed in Python 3.0: _builtinSuites, aepack, aetools, aetypes, applesingle, appletrawmain, appletrunner, argvemulator, Audio_mac, autoGIL, Carbon, cfmfile, CodeWarrior, ColorPicker, EasyDialogs, Explorer, Finder, FrameWork, findertools, ic, icglue, icopen, macerrors, MacOS, macfs, macostools, macresource, MiniAEFrame, Nav, Netscape, OSATerminology, pimp, PixMapWrapper, StdSuites, SystemEvents, Terminal, and terminalcommand.

ポート特有の変更: IRIX

A number of old IRIX-specific modules were deprecated and will be removed in Python 3.0: al and AL, cd, cddb, cdplayer, CL and cl, DEVICE, ERRNO, FILE, FL and fl, flp, fm, GET, GLWS, GL and gl, IN, IOCTL, jpeg, panelparser, readcd, SV and sv, torgb, videoreader, and WAIT.

Python 2.6 への移植

このセクションでは前述の変更とバグフィックスにより必要となるかもしれないコードの変更を列挙します:

ハッシュ化をサポートしないクラスはその定義内でその事実を示すために、 __hash__ = None をセットすべきです。

文字列を例外として送出することは出来なくなりました。これをすると TypeError を起こします。

collections.deque の __init__() メソッドが、イテラブルから要素を追加する前に全ての deque の既存の内容をクリアするようになっています。この変更は list.__init__() の振る舞いと一致します(---訳注: 当たり前のことにしか思えないのですが詳細がわかりません。これ以前のバージョンでは deque はシングルトンのように振舞っていたのでしょうか。---)。

object.__init__() は以前は任意の引数とキーワード引数を受け取り、そして無視していました。Python 2.6 ではもうこれは許されません。 TypeError を起こします。これは結果的に object の対応するメソッドを呼ぶ(おそらく super() を介して) __init__() メソッドに影響します。 bpo-1683368 [https://bugs.python.org/issue?@action=redirect&bpo=1683368] の議論を参照して下さい。

Decimal のコンストラクタは今では先頭と末尾の空白が含まれる文字列を許容します。以前は InvalidOperation となっていました。他方で、 Context オブジェクトの create_decimal() メソッドは余分な空白を明示的に拒絶するようになり、 ConversionSyntax を投げます。

実装上の誤り(事故)で、ビルトインの __import__() 関数にファイルパスを渡すと指定したファイルをインポート出来ていました。しかしながらこれは決して意図した振る舞いではありませんでした。実装は今ではこのケースを明示的にチェックし、 ImportError を起こします。

C API: PyImport_Import() と PyImport_ImportModule() 関数がデフォルトで、相対インポートではなく絶対インポートをするようになっています。これはほかのモジュールをインポートする C 拡張に影響します。

C API: ハッシュされるべきではない拡張データ型は、 tp_hash スロットを PyObject_HashNotImplemented() と定義すべきです。

socket モジュールの例外 socket.error が IOError 派生になっています。以前は StandardError のサブクラスではありませんでしたが今は IOError を通じてそれのサブクラスです。 (Implemented by Gregory P. Smith; bpo-1706815 [https://bugs.python.org/issue?@action=redirect&bpo=1706815].)

The xmlrpclib module no longer automatically converts datetime.date and datetime.time to the xmlrpclib.DateTime type; the conversion semantics were not necessarily correct for all applications. Code using xmlrpclib should convert date and time instances. (bpo-1330538 [https://bugs.python.org/issue?@action=redirect&bpo=1330538])

(3.0 警告モード) Exception クラスはスライスやインデクスアクセスで警告を出します; Exception のタプルのような振る舞いはのちに取り除かれます。

(3.0 警告モード) 2 つの辞書や 2 つの比較メソッドを実装しないオブジェクトの不等号比較は警告されます。 dict1 == dict2 はまだ動作しますが、 dict1 < dict2 はのちに取り除かれます。

Python のスコープルールの実装の詳細であるセル間の比較も、警告を引き起こします。なぜならこれは、3.0 ではそのような比較は完全に禁止されているからです。

Python を埋め込んだアプリケーションでは:

The PySys_SetArgvEx() function was added in Python 2.6.6, letting applications close a security hole when the existing PySys_SetArgv() function was used. Check whether you're calling PySys_SetArgv() and carefully consider whether the application should be using PySys_SetArgvEx() with updatepath set to false.

謝辞

著者は提案の申し出や修正、様々なこの記事の草稿の助けをしてくれた以下の人々に感謝します: Georg Brandl, Steve Brown, Nick Coghlan, Ralph Corderoy, Jim Jewett, Kent Johnson, Chris Lambacher, Martin Michlmayr, Antoine Pitrou, Brian Warner.

What's New in Python 2.5

著者:

A.M. Kuchling

This article explains the new features in Python 2.5. The final release of Python 2.5 is scheduled for August 2006; PEP 356 [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 (xml.etree), the SQLite database module (sqlite), and the ctypes module for calling C functions.

言語の変更の意義は、中程度のものです。いくつかの心地よい機能が入りましたが、そのほとんどの機能は毎日使うというものでもありません。条件式(conditional expressions)がついに言語に追加されました。ちょっと変わった文法です。 PEP 308: 条件式 (Conditional Expressions) のセクションを参照してください。新しい 'with' 文は後始末のコードを書くのを簡単にします(PEP 343: "with" ステートメント セクション)。ジェネレータに値を返すことが出来るようになりました(PEP 342: ジェネレータの新機能 セクション)。インポートが、絶対パス、相対パスのどちらかで可視に出来るようになりました(PEP 328: 絶対インポート、相対インポート セクション)。例外ハンドリングのいくつかの境界のケースで、より良いハンドリングを行えるようになりました(PEP 341: try/except/finally の一体化 セクション)。これらのどの改善も価値が高いですが、それらは言語機能を限定的に改善するものであって、いずれも Python のセマンティクスを広範に修正するものではありません。

言語とライブラリの追加と同様に、ほかの改善とバグフィックスもソースツリー全体に渡っています。SVN 変更ログを検索すると、Python 2.4 から 2.5 の間で適用されたパッチは 353、フィックスされたバグは 458 ありました(ともに少なく見積もってです)。

このドキュメントは新機能の完全な詳細を提供するのではなくて、変更について、役に立つ実例を使った簡易な概要を提供することを目的にしています。完全な詳細が知りたければ常に、 https://docs.python.org の Python 2.6 のドキュメントを参照すべきです。設計と実装の根拠を理解したい場合は、新機能に関する PEP を参照してください。可能な限り、 "What’s New in Python" は各変更の bug や patch に対してリンクしています。

このドキュメントについてのコメント、提案と誤りの報告は歓迎です。著者に電子メールを送るか、または Python バグトラッカーにバグをあげてください。

PEP 308: 条件式 (Conditional Expressions)

もう長いことずっと、人々は条件式を書くための手段を要望し続けてきました。それは Boolean 値が真か偽かによって値 A または B を返す式です。条件式により以下と同じ効果を持つ単一行代入式を書くことが出来ます:

if condition:
    x = true_value
else:
    x = false_value

構文についての退屈で終わりのない議論が python-dev と comp.lang.python の両方で続いてきました。投票では、大半は何らかの形で条件式を望んでいることを示していましたが、明らかな過半数によって支持される構文はありませんでした。候補には C の cond ? true_v : false_v や if cond then true_v else false_v を含む、ほか 16 のバリエーションがありました。

Guido van Rossum は結果として意外な構文を選択しました:

x = true_value if condition else false_value

評価はこれでも既存の Boolean 式のように遅延的であり、評価順は少々前後します。真ん中の condition はまさに最初に評価されるのであって、 true_value 式はその condition が真の場合にのみ評価されます。同じように false_value は condition が偽の場合にのみ評価されるのです。

この構文は奇妙で退行しているようにも思えます; どうして condition が 真ん中 にあって C の c ? x : y のように前にないのでしょう? この決定は、標準ライブラリ内のモジュールにその新構文を適用し、結果のコードをどう読むかを見ることでチェックされました。条件式が使われる多くの場合で、一つの値はどうやら「一般の場合」で一つの値は「例外的な場合」のようで、条件を満たさないことが稀な場合にのみ使われていました。条件の構文はこのパターンで少しばかり明快さを増します:

contents = ((doc + '\n') if doc else '')

私には上記ステートメントはこう読めます。「 contents は普通は doc+'\n' の値に代入される。ただし時々 doc が空になる。その特別な場合には空の値が代入されるのだ」。私は普通と普通でないのが明らかでない場合に頻繁に条件式を使うとは思いません。

言語が条件式に括弧を必要とすべきかどうかに関していくつか議論がありました。決定は Python 言語文法として括弧は 必要ない とされましたが、スタイルの問題としては私は常に括弧を付けるべきと思います。以下 2 つの例を考えてみてください:

# First version -- no parens
level = 1 if logging else 0

# Second version -- with parens
level = (1 if logging else 0)

最初の版の場合、私は読者の目はおそらくステートメントを「level = 1」「if logging」「else 0」にグループ化すると思います。そして condition は level への代入が行われるのかどうかを決めるのだ、と考えるであろうと。後者の版は読みやすいです、少なくとも私の意見では。代入はいつでも行われることも、選択が 2 つの値の間で起こることもはっきりしますから。

括弧を含めるもう一つの理由があります: 少し奇妙なリスト内包とラムダの組合せが、不完全な条件式になることがあります。 PEP 308 [https://peps.python.org/pep-0308/] にいくつかの例があるので見てください。条件式の周りをいつでも括弧で囲むなら、このケースにぶち当たることもありません。

参考

PEP 308 [https://peps.python.org/pep-0308/] - 条件式 (Conditional Expressions)

PEP 著 Guido van Rossum と Raymond D. Hettinger; 実装 Thomas Wouters.

PEP 309: 関数の部分適用

functools モジュールは、関数型スタイルのプログラミングのためのツールを含むことを意図したものです。

このモジュールには一つの有用なツールとして、 partial() 関数があります。関数型スタイルでプログラムを書くのに、あなたはときおり、いくつかのパラメータを持つ関数に一部パラメータを埋めたものを作りたくなります。Python 関数 f(a, b, c) を考えてみましょう; f(1, b, c) と等価な g(b, c) を作れたら、と思うわけです。これは「関数の部分適用」と呼ばれています。

partial() は (function, arg1, arg2, ... kwarg1=value1, kwarg2=value2) という引数を取ります。できあがったオブジェクトは呼び出し可能オブジェクトですので、それを呼べば、引数の埋まった function を実行したのと同じことになります。

以下にあるのは、小さいけれども現実的な一つの例です:

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')

もうひとつ、PyGTK を使うプログラムからの例をみてみましょう。いま、「コンテキスト依存」のポップアップメニューを動的に構築しようとしています。そのメニューオプションから提供されるコールバックは、 open_item() メソッドの部分適用版で、その最初の引数が適用済みです:

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

functools モジュールのもう一つの関数は update_wrapper(wrapper, wrapped) で、より良く振舞うデコレータを書くのに役立ちます。 update_wrapper() は包まれるほうの名前、モジュール、ドキュメンテーション文字列属性をラッパー関数にコピーすることで、トレースバックを理解しやすくします。たとえばこう書けます:

def my_decorator(f):
    def wrapper(*args, **kwds):
        print 'Calling decorated function'
        return f(*args, **kwds)
    functools.update_wrapper(wrapper, f)
    return wrapper

wraps() は、ラップされる関数についての情報をコピーするために、あなた自身のデコレータ内で使えるデコレータです。先の例はこのようにも書けます:

def my_decorator(f):
    @functools.wraps(f)
    def wrapper(*args, **kwds):
        print 'Calling decorated function'
        return f(*args, **kwds)
    return wrapper

参考

PEP 309 [https://peps.python.org/pep-0309/] - 関数の部分適用

PEP の提案と著: Peter Harris; 実装: Hye-Shik Chang と Nick Coghlan, また、適応物が Raymond Hettinger により。 (---訳注: この PEP のタイトルに違和感を憶える人は多いと思います。functools のテリトリが「関数型スタイルのサポート」にあるのに。部分引数サポートのためのパッチが最終的に関数型スタイルに行き着いた (正確には、「partial のような高階関数を置く場所として functools という場所を使いましょう、partial から始めましょう」というのが提案の趣旨)、という経緯がこのタイトルに反映しています。---)

PEP 314: Metadata for Python Software Packages v1.1

Distutils にいくつかの単純な依存性解決サポートが追加されました。 setup() 関数に requires, provides, obsoletes キーワードパラメータが追加されています。 sdist コマンドでソース配布物をビルドする際に、依存性についての情報が PKG-INFO ファイルに記録されます。

もう一つ追加されたキーワードパラメータ download_url は、パッケージのソースコードの URL をセットします。これによりパッケージインデクス内のエントリを探し出すことが出来、パッケージの依存性を決めることが出来、必要パッケージをダウンロード出来ます:

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),
     )

Python Package Index (https://pypi.org) へのもう一つの新たな拡張は、パッケージについてのソースコードとバイナリアーカイブの保存についてです。新たな Distutils コマンド upload は、レポジトリへパッケージをアップロードします。

パッケージがアップロードされる前には、Distutils sdist コマンドを使って配布物をビルド可能でなければなりません。それさえ出来ていれば、 python setup.py upload がパッケージを PyPI アーカイブに追加してくれます。追加で、パッケージに GPG 署名出来ます。これには --sign オプションと --identity オプションを使います。

パッケージのアップロードは Martin von Löwis と Richard Jones により実装されました。

参考

PEP 314 [https://peps.python.org/pep-0314/] - Metadata for Python Software Packages v1.1

PEP 提案と著 A.M. Kuchling、 Richard Jones、 Fred Drake; 実装 Richard Jones と Fred Drake.

PEP 328: 絶対インポート、相対インポート

The simpler part of PEP 328 [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 from ... import ... statement, making it easier to import many different names.

より複雑なほうは Python 2.5 で実装されました: モジュールのインポートにおいて、それが絶対インポートなのかパッケージ相対のインポートなのかを指定出来るようにする、というものです。将来のバージョンの Python では絶対インポートをデフォルトにする方向に向かう予定です。

いま、あなたは以下のようなパッケージディレクトリを持っているとします:

pkg/
pkg/__init__.py
pkg/main.py
pkg/string.py

pkg パッケージがモジュール pkg.main とサブモジュール pkg.string を持っています。

main.py のなかの人、になってみましょう。 import string 文を実行すると、何が起こるでしょうか? Python 2.4 とそれ以前のバージョンでは、相対インポートとして実行するためにパッケージのディレクトリ内のものを最初に探し、 pkg/string.py を発見してそのファイル内容を pkg.string モジュールであるとしてインポートし、そのモジュールは pkg.main モジュール内の名前空間で、名前 string に束縛されます。

よろしいでしょう。欲しいものが pkg.string であるならば。ですが欲しいのは Python 標準ライブラリモジュールの string なのだとしたら? pkg.string を無視して標準モジュールを探す綺麗な方法はありません; 一般的に、 sys.modules の中身から探す必要がありました。これはちょっとばかり美しくありません。Holger Krekel の py.std パッケージは標準ライブラリからモジュールをインポートするのに import py; py.std.string.join() と、よりこぎれいな方法を与えてくれますが、そのパッケージは全ての Python インストレーションでの利用が可能にはなっていません。

相対インポートに頼ったコードを読むことは、より不明瞭でもあります。読者は string と pkg.string のどちらを使おうとしているのかについて、混乱するだろうからです。Python ユーザはすぐに、彼らのパッケージのサブモジュール名が標準ライブラリモジュールの名前と被らないようにすることを学びますが、あなたのサブモジュール名が将来のバージョンの Python に追加される新しいモジュールで使われる名前にならないようにすることは出来ません。

Python 2.5 では import の振る舞いを、 from __future__ import absolute_import ディレクティブを使うことによって絶対インポートに切り替えられます。この絶対インポートの振る舞いは将来バージョンの Python でデフォルトになります(おそらく Python 2.7 で)。(訳注: ご承知のとおり Python 2.7 でもこれはデフォルトとはなっていません。Python 3.x への移行のためにも 2.5 - 2.7 では from __future__ import absolute_import を使うべきです。) 絶対インポートをデフォルトにしてしまえば、 import string はいつでも標準ライブラリ版を見つけます。ユーザは可能な限り絶対インポートを使い始めるべきで、あなたのコードでは from pkg import string と書き始めることが望まれます。

相対インポートは、 from ... import 形式を使う際にモジュール名の前にピリオドを付ければまだ可能です:

# Import names from pkg.string
from .string import name1, name2
# Import pkg.string
from . import string

これは現在のパッケージからの相対で string モジュールをインポートしますので、 pkg.main 内ではこれは、 name1 と name2 を pkg.string からインポートするでしょう。加えて、先行する複数ピリオドは、現在のパッケージの親からの相対インポートを実行します。例えば、 A.B.C モジュール内のコードはこのように出来ます:

from . import D                 # Imports A.B.D
from .. import E                # Imports A.E
from ..F import G               # Imports A.F.G

このピリオドによる書き方は import modname 形式のインポート文では使えず、 from ... import 形式でのみ使えます。

参考

PEP 328 [https://peps.python.org/pep-0328/] - マルチラインインポートと、絶対/相対インポート

PEP 著 Aahz; 実装 Thomas Wouters。

https://pylib.readthedocs.io/

Holger Krekel による py ライブラリで、 py.std パッケージを含みます。

PEP 338 - モジュールをスクリプトとして実行する

Python 2.4 で追加されたモジュールをスクリプトとして実行するための -m スイッチが、少し能力を高めました。Python インタプリタ内での C 実装に代わり、これの実現には新しいモジュール runpy を使うようになっています。

runpy モジュールはインポートのメカニズムをより洗練された方法で実装しているので、今では pychecker.checker のようにパッケージ内のモジュールも実行出来ます。このモジュールは異なるインポートメカニズム、例えば zipimport モジュールもサポートします。このことにより、 sys.path に .zip アーカイブのパスを追加して、 -m スイッチでアーカイブ内のコードを実行する、といったことも出来ます。

参考

PEP 338 [https://peps.python.org/pep-0338/] - モジュールをスクリプトとして実行する

PEP 著と実装 Nick Coghlan.

PEP 341: try/except/finally の一体化

Until Python 2.5, the try statement came in two flavours. You could use a finally block to ensure that code is always executed, or one or more except blocks to catch specific exceptions. You couldn't combine both except blocks and a 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 はいくらかの時間 Java での作業に時間を割きました。それは except ブロックと finally ブロックを組み合わせるのと等価なものをサポートしています。そしてこの作業が、このステートメントがどういう意味であるべきかを明らかにしたのです。Python 2.5 では、あなたは今ではこう書くことが出来ます:

try:
    block-1 ...
except Exception1:
    handler-1 ...
except Exception2:
    handler-2 ...
else:
    else-block
finally:
    final-block

block-1 内のコードが実行されます。そのコードが例外を投げた場合、個々の except ブロックがテストされます: その例外が Exception1 クラスであれば、 handler-1 が実行されます; そうでない場合で Exception2 クラスであれば、 handler-2 が実行されます、以下同文。例外が起こらなければ、 else-block が実行されます。

以前に何が起こったのかに拠らず、コードブロック完了時やどれかの例外が処理されれば final-block が実行されます。例外ハンドラ内や else-block でエラーが起こったり、 新しく例外を投げる場合でさえ、 final-block 内のコードはそれでも実行されます。

参考

PEP 341 [https://peps.python.org/pep-0341/] - try-except と try-finally を一体化する

PEP 著 Georg Brandl; 実装 Thomas Lee。

PEP 342: ジェネレータの新機能

Python 2.5 は、ジェネレータ に向けて 値を渡すための単純な手段を追加しました。Python 2.3 でジェネレータが導入された時点ではジェネレータが出来たのは出力だけでした。いったんジェネレータのコードが呼び出されてイテレータが作られたあとは、新しい情報をそのジェネレータ関数の再開位置に渡す手段はありませんでした。ヤクザな解決法としては、ジェネレータがグローバル変数を見るようにしたり、ミュータブルなオブジェクトを渡しておいて呼び出し元であとからそれを変更したり、といったものがありました。

基本的なジェネレータについて思い出してもらいましょう、単純な例はこんなです:

def counter (maximum):
    i = 0
    while i < maximum:
        yield i
        i += 1

When you call counter(10), the result is an iterator that returns the values from 0 up to 9. On encountering the 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 next() method, picking up after the yield statement.

In Python 2.3, yield was a statement; it didn't return any value. In 2.5, yield is now an expression, returning a value that can be assigned to a variable or otherwise operated on:

val = (yield i)

戻り値に何かする際は、 yield 式の周りには括弧は付けておいたほうがいいと思います、この例でのように。括弧はべつに必要はないのですが、どんな場合に必要かを憶えるよりは、いつでも付けるのが簡単でしょう。

(PEP 342 [https://peps.python.org/pep-0342/] がその規則を正確に説明していますが、それによると yield 式は、代入式で右辺のトップレベルにあるとき以外はいつも括弧を付ける必要があります。つまり val = yield i とは書けますが、 val = (yield i) + 12 のように演算子があるときは括弧を使わなくてはいけません。)

Values are sent into a generator by calling its send(value) method. The generator's code is then resumed and the yield expression returns the specified value. If the regular next() method is called, the yield returns None.

以下は前のと同じ例ですが、内部カウンタの値の変更を許す修正をしました:

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

そしてカウンタ変更の例がこちらです:

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

yield が None を返すことはよくあるのですから、そうなっていないかどうか必ずチェックしておくべきです。ジェネレータ関数を再開するために使うメソッドが send() しかないのだと確信してるのでない限り、式の値をそのまま使ってはいけません。

ジェネレータには、 send() のほかにも新しいメソッドが二つあります

throw(type, value=None, traceback=None) はジェネレータ内で例外を投げるために使います; その例外はジェネレータの実行が停止したところの yield 式によって投げられます。

close() はジェネレータ内で GeneratorExit 例外を投げてイテレートを終了させます。この例外を受け取ったジェネレータのコードは GeneratorExit か StopIteration を投げなくてはいけません; この例外を捕捉して何かほかのことをしようとするのは規則違反であり、 RuntimeError を引き起こします; 関数が何かほかの例外を投げると、その例外は呼び出し元に伝播します。 close() はジェネレータのガーベージコレクトによっても呼ばれます。

GeneratorExit が起こったときにクリーンアップ作業をする必要があるなら、 GeneratorExit を捕捉するのではなく try: ... finaly: するようお勧めします。

これらの変更の合わせ技で、ジェネレータは情報の一方的な生産者から、生産者かつ消費者という存在に変貌を遂げたのです。

ジェネレータは コルーチン という、より一般化された形式のサブルーチンにもなります。サブルーチンは一カ所 (関数の冒頭) から入って別の一カ所 (return 文) から出るだけですが、コルーチンはいろいろな場所 (yield 文) から入ったり出たり再開したりできるのです。わたしたちは Python でコルーチンを効果的に使うためのパターンを理解する必要があります。

The addition of the close() method has one side effect that isn't obvious. 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 try...finally statements in generators can now be guaranteed to work; the finally clause will now always get a chance to run. The syntactic restriction that you couldn't mix yield statements with a try...finally suite has therefore been removed. This seems like a minor bit of language trivia, but using generators and try...finally is actually necessary in order to implement the with statement described by PEP 343 [https://peps.python.org/pep-0343/]. I'll look at this new statement in the following section.

もう一つさらに深遠なこの変更の効果: 以前はジェネレータの gi_frame 属性は常にフレームオブジェクトでした。今では gi_frame は、ジェネレータが使い果たされた場合に None になります。

参考

PEP 342 [https://peps.python.org/pep-0342/] - 拡張されたジェネレータを用いたコルーチン

PEP は Guido van Rossum と Phillip J. Eby によって書かれ、Phillip J. Eby によって実装されました。コルーチンとしてのジェネレータの用法のいくつかの手が込んだ例が含まれています。

この機能の初期バージョンは Raymond Hettinger による PEP 288 [https://peps.python.org/pep-0288/] と Samuele Pedroni による PEP 325 [https://peps.python.org/pep-0325/] で提案されました。

https://en.wikipedia.org/wiki/Coroutine

コルーチンに関する WikiPedia エントリ。

https://web.archive.org/web/20160321211320/http://www.sidhe.org/~dan/blog/archives/000178.html

Dan Sugalski による、Perl の視点からみたコルーチンの説明です。

PEP 343: "with" ステートメント

'with' ステートメントは、以前なら後片付けが実行されるのを確実にするために try...finally ブロックを使ったであろうようなコードを、より単純明快にします。このセクションでは、このステートメントの普通の使い方を説明します。続くセクションでは実装の詳細を調べ、このステートメントとともに使うためにオブジェクトをどうやって書けば良いかをお見せします。

'with' ステートメントは基本構造が以下となる新しい制御フロー構造です:

with expression [as variable]:
    with-block

The expression is evaluated, and it should result in an object that supports the context management protocol (that is, has __enter__() and __exit__() methods.

The object's __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 __exit__() method is called, even if the block raised an exception, and can therefore run clean-up code.

Python 2.5 でこのステートメントを有効にするには、以下のディレクティブをあなたのモジュールに追加する必要があります:

from __future__ import with_statement

Python 2.6 ではこれは常に有効になります。

いくつかの Python 標準オブジェクトが既にコンテキスト管理プロトコルをサポートしていて、 'with' とともに使えます。ファイルオブジェクトがその一例です:

with open('/etc/passwd', 'r') as f:
    for line in f:
        print line
        ... more processing code ...

このステートメントが実行し終わったあかつきには、 f のファイルオブジェクトは、たとえ for ループが道半ばにして例外と成り果てても、自動的にクローズされます。

注釈

In this case, f is the same object created by open(), because __enter__() returns self.

threading モジュールのロック・条件変数でも 'with' ステートメントの恩恵にあずかれます:

lock = threading.Lock()
with lock:
    # Critical section of code
    ...

ブロックが実行される前にロックが獲得されて、ブロックが完了するやいなや必ず解放されます。

decimal モジュール内の新しい localcontext() 関数は現在の decimal のコンテキスト (計算の望みの精度と丸め特性をカプセル化しています) を保存しておいてあとで元に戻すのを簡単にしてくれます:

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()

コンテキストマネージャを書く

中身を紐解いてみれば、 'with' ステートメントはけっこう入り組んでいます。ほとんどの人にとっては、既存のオブジェクトを 'with' とともに使うだけのことでその詳細を知る必要は無いので、それで良いならこのセクションの残りの部分は読み飛ばして結構です。新しいオブジェクトの作者は基礎となる実装の詳細について知る必要があるので、このまま読み進めるべきです。

コンテキスト管理プロトコルの高度な説明はこんなです:

The expression is evaluated and should result in an object called a "context manager". The context manager must have __enter__() and __exit__() methods.

The context manager's __enter__() method is called. The value returned is assigned to VAR. If no 'as VAR' clause is present, the value is simply discarded.

BLOCK 内のコードが実行されます。

BLOCK が例外を起こした場合、コンテキストマネージャの __exit__ メソッドが 3 つの引数とともに呼び出されます。これは例外の詳細です (type, value, traceback, これは sys.exc_info() が返す値と同じで、例外が起こらなければ None です)。そのメソッドの戻り値は例外を再送出するかどうかを制御します: 全ての偽の値ではその例外が再送出され、 True では揉み消します。例外を揉み消すなど滅多なことでは欲しいと思わないでしょう。もしそうしてしまったら、 'with' ステートメントを含んだコードの作者は何か間違ったことが起こったことに決して気付かないですから。

If BLOCK didn't raise an exception, the __exit__() method is still called, but type, value, and traceback are all None.

例を通じて考えましょう。枝葉末節を含んだ完璧なコードを提示しようとは思いませんが、データベースのためにトランザクションをサポートするのに必要となるメソッドの書き方についてスケッチしてみようと思います。

(データベース用語に不慣れな方へ:データベースへの変更のセットは、トランザクションという単位でグループ化されています。トランザクションは「コミット」される、その意味は、全ての変更がデータベースに書き込まれることです、もしくは「ロールバック」される、この場合全ての変更が捨てられてデータベースが変更されません、この 2 つのいずれかになりえます。詳しくはなにかデータベースの著述を読んで下さい。)

データベース接続を表現するオブジェクトがあると仮定しましょう。私たちの目標は、そのオブジェクトのユーザがこのように書けるようになることです:

db_connection = DatabaseConnection()
with db_connection as cursor:
    cursor.execute('insert into ...')
    cursor.execute('delete from ...')
    # ... more operations ...

トランザクションはブロック内のコードがつつがなく終了すればコミットし、例外が発生すればロールバックすべきです。私が思い描いている DatabaseConnection の基本的なインターフェイスはこんなです:

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"

The __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 as cursor to their 'with' statement to bind the cursor to a variable name.

class DatabaseConnection:
    ...
    def __enter__ (self):
        # Code to start a new transaction
        cursor = self.cursor()
        return cursor

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

下記のコード内では実行がメソッドの末尾まで落ちていって、なのでデフォルトの None 返却になります。 None は偽なので、例外は自動的に再送出されます。望むならもっと明示的に、コメントでマークした部分で return 文を書いてもよろしいです:

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

contextlib モジュール

新しい contextlib モジュールは、 'with' ステートメントで使えるオブジェクトを書く際に便利ないくつかの関数とデコレータを提供しています。

The decorator is called 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 yield will be executed as the __enter__() method, and the value yielded will be the method's return value that will get bound to the variable in the 'with' statement's as clause, if any. The code after the yield will be executed in the __exit__() method. Any exception raised in the block will be raised by the yield statement.

このデコレータを使って、前セクションの私たちのデータベースの例はこのように書けます:

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

contextlib モジュールには nested(mgr1, mgr2, ...) 関数もあり、この関数はたくさんのコンテキストマネージャを組み合わせることができて、入れ子の 'with' を書く必要性をなくしてくれます。この例では、単一の 'with' でデータベーストランザクション開始とスレッドのロック獲得の両方をやってのけています:

lock = threading.Lock()
with nested (db_transaction(db), lock) as (cursor, locked):
    ...

最後になりますが、 closing(object) 関数は object をそのまま返して変数に束縛出来るようにし、かつブロックの終了で、与えた引数が持つ object.close を呼び出します:

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)

参考

PEP 343 [https://peps.python.org/pep-0343/] - "with" ステートメント

PEP は Guido van Rossum と Nick Coghlan によって書かれ、Mike Bland、 Guido van Rossum、Neal Norwitz により実装されました。この PEP は 'with' ステートメントによって生成されるコードを見せてくれるので、このステートメントがどうやって動作するのかを知るのに役立ちます。

contextlib モジュールについてのドキュメント。

PEP 352: 例外の新スタイルクラス化

例外クラスは、今では旧スタイルクラスだけではなく新スタイルクラスになれます。組み込みの Exception クラスと全ての標準組み込み例外 (NameError, ValueError, など) が今では新スタイルクラスです。

例外の継承階層が少し再編成されました。2.5 では継承関係はこのようになっています (---訳注: 2.6 ではさらに GeneratorExit が Exception ではなく BaseExceotion の直接の子になり、これは 3.x でも引き継がれています。---):

BaseException       # New in Python 2.5
|- KeyboardInterrupt
|- SystemExit
|- Exception
   |- (all other current built-in exceptions)

この再編成が行われたのは、人々がしばしばプログラムのエラーを示す例外すべてを捕捉したがるからです。 KeyboardInterrupt と SystemExit はエラーではありませんが、普通は Control-C をユーザが叩いたか、コードが sys.exit() を呼び出したかのような明示的なアクションを表します。剥き出しの except: はまさに全ての例外を捕捉しますから、一般に、再送出のために KeyboardInterrupt と SystemExit はリストする必要があります。お決まりのパターンはこんなです:

try:
    ...
except (KeyboardInterrupt, SystemExit):
    raise
except:
    # Log error...
    # Continue running program...

Python 2.5 では同じ結果を得るのにもう except Exception と書いても良いです。これは普通はエラーを示す例外全てを捕捉しつつも KeyboardInterrupt と SystemExit は置き去りにします。無論かつてまでのバージョン同様、剥き身の except: は全例外を捕捉します。

Python 3.0 での目標は、例外として raise される全てのクラスが BaseException からの、もしくは BaseException のある子孫であることを要求することであり、Python 2.x シリーズの将来のリリースにおいてはこの制約の強制を始めるかもしれません。ですからあなたの全ての例外は、今からすぐに Exception 派生にするのが肝要です。捕捉例外を特定しない except: は Python 3.0 から取り除かれるべきであることが提案されていますが、Guido van Rossum はこれをどうするかまだ決めていません。 (---訳注: 2.7 では raise は「新スタイルクラスであれば」 BaseException 派生であることを要求されますが、旧スタイルクラスであればなんでも許されてしまう点ではあまり変わっていません。これについての警告は -3 などで受けることが出来ます。Python 3.0 でようやく全ての例外が BaseException 派生であることが強制されるようになりました。 また、 except: は 3.4 でも残っています。---)

例外として文字列を raise "Error occurred" として raise することは Python 2.5 では非推奨であり警告を引き起こします。その目的は、あと少しのリリースで文字列例外を削除することです。 (---訳注: 2.6 以降の What's New では明示的に書かれてはいませんが、2.7 では警告ではなくエラーです。---)

参考

PEP 352 [https://peps.python.org/pep-0352/] - 例外のためのスーパークラス

PEP 著: Brett Cannon と Guido van Rossum; 実装: Brett Cannon.

PEP 353: 添え字型に ssize_t を使う

A wide-ranging change to Python's C API, using a new 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 2**31 - 1 = 2147483647 items. (There are actually a few different programming models that 64-bit C compilers can use -- see https://unix.org/version2/whatsnew/lp64_wp.html for a discussion -- but the most commonly available model leaves int as 32 bits.)

2147483647 に要素数が制限されることは 32 ビットプラットフォームではあまり重大でもありません。その長さ制限を喰らう前にメモリを使い果たすでしょうから。それぞれのリストアイテムは、ポインタのための領域 (4 バイト) をアイテムを表現する PyObject に余分に必要とします。2147483647*4 は既に 32 ビットのアドレス空間が含められるバイト数を超えています。(---訳注: 意味不明。何か誤解があるような…? 4 バイトは 2147483647 (符号付きとして 2^31 - 1) でしょう。4 を掛ける説明なんかここでまったくされていない。なぜ掛ける? それと要素のインデクシングとアイテムの必要領域は議論には無関係なのでは?---)

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

この変更は C 拡張モジュールの著者に大変大きく影響します。Python 文字列とリストやタプルのようなコンテナ型は、そのサイズを表すのに Py_ssize_t を使うようになっています。 PyList_Size() のような関数は Py_ssize_t を返します。拡張モジュール内のコードでは、ですので、ある程度の変数の Py_ssize_t への変更が必要でしょう。

The PyArg_ParseTuple() and Py_BuildValue() functions have a new conversion code, n, for Py_ssize_t. PyArg_ParseTuple()'s s# and t# still output int by default, but you can define the macro PY_SSIZE_T_CLEAN before including Python.h to make them return Py_ssize_t.

PEP 353 [https://peps.python.org/pep-0353/] には、拡張の著者が読んで学ぶべき 64 ビットプラットフォームサポートについてのセクションがあります。

参考

PEP 353 [https://peps.python.org/pep-0353/] - 添え字型に ssize_t を使う

PEP 著と実装 Martin von Löwis.

PEP 357: '__index__' メソッド

NumPy 開発者たちは、新しい特殊メソッド、 __index__() を追加することによってしか解決できない問題を抱えていました。スライスの表現 [start:stop:step] を使う際、 start, stop, step は全て整数か長整数でなければなりません。NumPy は様々な特殊化された整数型を持っていて、符号なし、符号付きの 8、16、32、64 ビットに対応していますが、それらをスライスの添え字に使う手段はありませんでした。

スライシングに既存の __int__() メソッドをそのまま使うことは出来ません。それらは整数への型変換を実装するのにも使われるからです。スライシングが __int__() を使ったとすれば、浮動小数点数でさえスライスの添え字として使うことが合法になりますが、それは明らかに望む振る舞いではありません。

その代わりに新しい特殊メソッド __index__() が追加されました。これは引数を取らずに、スライスの添え字として使われる整数を返します。例えば:

class C:
    def __index__ (self):
        return self.value

戻り値は Python 整数または長整数でなければなりません。インタプリタは戻り値が正しいかどうかをチェックし、要求に合わない場合に TypeError を送出します。

A corresponding nb_index slot was added to the C-level PyNumberMethods structure to let C extensions implement this protocol. PyNumber_Index(obj) can be used in extension code to call the __index__() function and retrieve its result.

参考

PEP 357 [https://peps.python.org/pep-0357/] - スライシングのために任意のオブジェクトを使えるようにする

PEP 著と実装 Travis Oliphant.

その他の言語変更

以下が、Python 2.5 言語コアに加えられた全ての変更点です。

dict 型に新たなフックが追加されています。サブクラスが、辞書に含まれないキーに対してデフォルトを提供出来るようにするものです。キーが見つからない場合、辞書の __missing__(key) メソッドが呼ばれます。このフックは collections モジュール内の新しいクラス defaultdict で使われています。続く例は存在しないキーに対してゼロを返す辞書を定義しています:

class zerodict (dict):
    def __missing__ (self, key):
        return 0

d = zerodict({1:1, 2:2})
print d[1], d[2]   # Prints 1, 2
print d[3], d[4]   # Prints 0, 0

8 ビット文字列、Unicode ともに、ありがちなユースケースを単純化する partition(sep) と rpartition(sep) が追加されました。

文字列のスライスに使うために find(S) メソッドを使ってインデクスを得るのだけれども、やりたいのはそのセパレータ(S)の前後の部分文字列を得ることだ、といったことはしょっちゅう必要になります。partition(sep) はこのパターンのコードを、一撃、に圧縮してくれます。これはセパレータ前の部分文字列、セパレータ自身、セパレータ後の部分文字列の 3 要素タプルを返します。セパレータが含まれない場合は、返却値の最初の要素に文字列全体が、残り2つは空文字列で返ります。rpartition(sep) もほぼ同じことをしますがセパレータの検索をお尻から始めます。 r は逆順('reverse')を表します。

いくつかの例です:

>>> ('http://www.python.org').partition('://')
('http', '://', 'www.python.org')
>>> ('file:/usr/share/doc/index.html').partition('://')
('file:/usr/share/doc/index.html', '', '')
>>> (u'Subject: a quick question').partition(':')
(u'Subject', u':', u' a quick question')
>>> 'www.python.org'.rpartition('.')
('www.python', '.', 'org')
>>> 'www.python.org'.rpartition(':')
('', '', 'www.python.org')

(Implemented by Fredrik Lundh following a suggestion by Raymond Hettinger.)

文字列型の startswith() と endswith() メソッドが、チェックされる文字列のタプルを受け容れるようになりました:

def is_image_file (filename):
    return filename.endswith(('.gif', '.jpg', '.tiff'))

(Implemented by Georg Brandl following a suggestion by Tom Lynn.)

ビルトイン関数 min() と max() に、 sort() における key に似たキーワード引数 key が追加されました。このパラメータには関数を与えます。これは一つの引数を取り、リスト内の全ての値に対して呼び出されます; min()/max() はこの関数を全要素に適用したもののなかでの最小値/最大値を返します。例えば、リスト中の最長の文字列を探すにはこのように出来ます:

L = ['medium', 'longest', 'short']
# Prints 'longest'
print max(L, key=len)
# Prints 'short', because lexicographically 'short' has the largest value
print max(L)

(Contributed by Steven Bethard and Raymond Hettinger.)

2 つの新たなビルトイン関数 any() と all() は、イテレータがいくつか真を含むかどうかを評価します。 any() はイテレータのいずれかが返す値が真と評価される場合に True を返し、そうでなければ False を返します。 all() はイテレータが返す値の評価が真のみの場合に True を返します。 (Suggested by Guido van Rossum, and implemented by Raymond Hettinger.)

クラスの __hash__() メソッドが返す値として、長整数と整数のどちらでも良くなりました。長整数が返されれば、その値のハッシュから取られます。以前のバージョンではこれは普通の整数であることが要求されていましたが、2.5 ではビルトイン関数 id() が変更されて常に非負数が返り、ユーザはしばしば __hash__() 内で id(self) を使うようです (これはお奨めしませんが)。 (---訳注: 不思議な論法で意味がわかりません。id が非負を返すとなぜユーザは __hash__ の実装に使おうとするのか? ユーザがそれをしてしまうのは単にデフォルト実装がそうだから、というだけではないかと思います。__cmp__, __eq__ が「身元」以外の意味を使って比較を行うならば、 __cmp__ で id を使うのはシンプルに「ダメ」でしょう。--)

モジュールのデフォルトエンコーディングが ASCII になりました(訳注: Python 3 からはデフォルトは utf-8 (PEP 3120))。8 ビット文字を含んでいるのにエンコーディング宣言がないモジュールが構文エラーになるようになりました。Python 2.4 では構文エラーとはならず警告でした。モジュールのエンコーディングをする方法については PEP 263 [https://peps.python.org/pep-0263/] を参照してください; 例えば、ソースコードの先頭付近にこのような行を追加することで出来ます:

# -*- coding: latin1 -*-

Unicode 文字列とデフォルトの ASCII エンコーディングで Unicode に変換出来ない 8 ビット文字列との比較を試みると、新しい警告 UnicodeWarning が引き起こされるようになっています。比較結果は偽です:

>>> chr(128) == unichr(128)   # Can't convert chr(128) to Unicode
__main__:1: UnicodeWarning: Unicode equal comparison failed
  to convert both arguments to Unicode - interpreting them
  as being unequal
False
>>> chr(127) == unichr(127)   # chr(127) can be converted
True

以前はこれは UnicodeDecodeError を起こしていましたので、2.5 でのこれは辞書のアクセス時に悩ましい問題をもたらしました。キーとして使われている unichr(128) や chr(128) を探そうとすると UnicodeDecodeError 例外が起こっていたでしょう。2.5 での、 辞書を実装している dictobject.c のほかの変更により、これは揉み消すのではなく、引き続き例外を起こします(訳注: 原文では this exception といっているので UnicodeDecodeError が起こるように読めるのですが、2.5 時点での振る舞いは確認出来ていませんが 2.7 では UnicodeWarning とともに KeyError が発生する、のようになるはずです。2.6 以降の What's New でのこれに関する言及はありませんが変更があったのかもしれません)。

この種の比較で例外を起こすのは完全に正しいことではあるものの、その変更はコードを破壊するかもしれないので、必要に応じて警告に出来るよう導入されたのが UnicodeWarning です。

(Implemented by Marc-André Lemburg.)

Python プログラマがよくしでかす間違いとして、パッケージディレクトリに __init__.py を入れ忘れる、というものがあります。この間違いのデバッグはややこしく、大抵 Python を -v スイッチ付きで起動して、パス検索全てをログ出力するハメになります。Python 2.5 ではパッケージディレクトリに __init__.py がないことが検出されると新たに ImportWarning 警告を出すようになりました。デフォルトではこの警告は黙って無視されます; これを出したければ、 -Wd スイッチをつけて Python を起動してください。(Implemented by Thomas Wouters.)

クラス定義において、基底クラスのリストを空リストに出来るようになっています(訳注: object を派生しないので結果として旧スタイルクラスになります)。例えば以下は今や合法です:

class C():
    pass

(Implemented by Brett Cannon.)

対話的なインタプリタの変更

対話的なインタプリタ内では、 quit と exit はずっと、立ち去ろうと(quit しようと)試みてそうタイプしてしまうユーザにとってある種有用な文字列になっていました:

>>> quit
'Use Ctrl-D (i.e. EOF) to exit.'

Python 2.5 でも quit と exit はそれ自身そのような文字列を生成はしますが、同時に「呼び出す」ことが出来るオブジェクトになっています。初心者が思わず quit() や exit() してしまった場合、今では彼らが期待する通りにインタプリタが終了します。 (Implemented by Georg Brandl.)

Python 実行形式ファイルが標準的な長い形式の --help と --version を受け付けるようになりました。Windows の場合はヘルプメッセージを出力するのに /? オプションも受け付けます。(Implemented by Georg Brandl.)

最適化

この最適化のいくつかは、2006年5月21日から28日にかけてアイスランドのレイキャビクで開催されたイベント、NeedForSpeed sprintで開発されました。このスプリントはCPythonの実装のスピードアップに焦点を当て、EWT LLCが資金を提供し、CCP Gamesが現地でサポートしました。 このスプリントで追加された最適化については、以下のリストで特別にマークしています。

Python 2.4 が導入されたとき、組み込みの set と frozenset 型は Python の辞書型の上に構築されたものでした。 Python 2.5 では、内部データ構造がセットを実装するためにカスタマイズされ、その結果、セットのメモリ使用量は3分の1になり、多少高速化されました。(Raymond Hettinger による実装。)

部分文字列の検索、文字列の分割、文字マップのエンコードとデコードなど、いくつかの Unicode 操作の速度が改善されました。 (部分文字列の検索と分割は、NeedForSpeed スプリントで Fredrik Lundh と Andrew Dalke が追加しました。部分文字列の検索と分割の改良は、NeedForSpeed sprintでFredrik LundhとAndrew Dalkeによって追加されました。文字マップは Walter Dörwald と Martin von Löwis によって改善されました。)

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

It's now illegal to mix iterating over a file with for line in file and calling the file object's read()/readline()/readlines() methods. Iteration uses an internal buffer and the 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 ValueError from the read*() method. (Implemented by Thomas Wouters.)

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

re モジュールは、システムの malloc() と free() の代わりに Python のアロケータ関数に切り替えることで、1～2%のスピードアップを達成しました。(NeedForSpeed sprintにてJack Diederichによるコントリビュート)

コードジェネレータの peephole オプティマイザは式の中で簡単な定数の折りたたみを実行するようになりました。 a = 2+3 のように書くと、コードジェネレータは算術演算を行い、 a = 5 に対応するコードを生成します。 (Raymond Hettinger による提案と実装。)

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

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

Importing now caches the paths tried, recording whether they exist or not so that the interpreter makes fewer open() and stat() calls on startup. (Contributed by Martin von Löwis and Georg Brandl.)

新たなモジュール、改良されたモジュール、削除されたモジュール

標準ライブラリは Python 2.5 で数多くの拡張とバグフィックスを行っています。ここでは注目に値する変更をモジュール名の辞書順で列挙します。変更についてのもっと完全なリストが見たければソースツリーの Misc/NEWS を調べるか、全ての詳細について SVN ログに目を通してみてください。

The audioop module now supports the a-LAW encoding, and the code for u-LAW encoding has been improved. (Contributed by Lars Immisch.)

codecs モジュールに漸増的コーデックのサポートが追加されています。 codec.lookup() 関数がタプルではなく CodecInfo を返すようになっています。 CodecInfo のインスタンスは後方互換性を維持するために 4 要素タプルのように振舞うだけでなく、属性 encode, decode, incrementalencoder, incrementaldecoder, streamwriter, streamreader を持ちます。漸増的コーデックは入力を受け取って出力するのを複数チャンクに分けて行えます; 出力は非漸増的コーデックに一回で入力全体を渡したものと同じになります。詳細は codecs モジュールのドキュメントを参照して下さい。 (Designed and implemented by Walter Dörwald.)

collections モジュールに新たに追加された defaultdict 型は、標準 dict のサブクラスです。この新しい型はほとんど辞書と同じに振る舞い、ただし、キーを要求された際にそのキーが存在していなかった場合に、自動的に辞書にデフォルト値を追加します。

defaultdict のコンストラクタの最初の引数は、キーが要求されて存在しない場合に呼び出されるファクトリ関数です。ファクトリ関数は引数を取りません。つまりこれに該当する list() や int() のようなビルトイン型のコンストラクタも使えます。例えば、その頭文字を基準に語の索引をこのように作ることが出来ます:

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)

index を出力するとこんな具合です:

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']}

(Contributed by Guido van Rossum.)

collections モジュールで提供されている両端キュー (double-ended queue) 型 deque に、キュー内で最初に現れる value を削除するメソッド remove(value) メソッドが追加されています。 value が見つからなければ ValueError が送出されます。 (Contributed by Raymond Hettinger.)

新規モジュール: contextlib モジュールには 'with' ステートメントで使えるヘルパ関数が含まれています。詳細は contextlib モジュール をみてください。

新規モジュール: cProfile モジュールは既存の profile モジュールの C 実装で、遥かに小さなオーバヘッドで実行出来ます。モジュールのインターフェイスは profile と同じです: 関数をプロファイルするのには cProfile.run('main()') と実行し、プロファイル結果をファイルに書き出すなど出来ます。これは Hotshot プロファイラとして知られるものではないですが (これも C で書かれてますが profile モジュールのインターフェイスとは別物です)、将来バージョンの Python で保守が続けられる予定です。(Contributed by Armin Rigo.)

また、プロファイラによる計測データの解析のための pstats モジュールが、 Stats コンストラクタの stream 引数による直接ファイル出力に対応しました。 (Contributed by Skip Montanaro.)

The 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 csv.field_size_limit(new_limit) function; omitting the new_limit argument will return the currently set limit. The reader class now has a line_num attribute that counts the number of physical lines read from the source; records can span multiple physical lines, so line_num is not the same as the number of records read.

CSV パーサは引用符内のマルチラインをより厳密に扱うようになっています。以前は、引用符で囲まれたフィールドが改行文字(newline)で終了することなく終端すると、改行文字が返却フィールドに追加されていました。この振る舞いはフィールドに復帰文字(carriage return)を含んだファイルを読み込む際に問題だったため、改行文字を挿入することなくフィールドを返すように変更されました。このことにより、フィールド内に埋め込まれた改行文字が重要な場合、入力は改行文字が保存される方法で行分割されるはずです。(---訳注: リファレンスも含めこの説明の表現がわかりにくいです。行指向で読み込む場合改行コードのモード(NL, CR NL, CR)依存で「物理行が終了した」とみなされるわけですが、このモード依存(CR 時)の振る舞いがなくなった、ということです。---)

(Contributed by Skip Montanaro and Andrew McNamara.)

The datetime class in the datetime module now has a strptime(string, format) method for parsing date strings, contributed by Josh Spoerri. It uses the same format characters as time.strptime() and time.strftime():

from datetime import datetime

ts = datetime.strptime('10:13:15 2006-03-07',
                       '%H:%M:%S %Y-%m-%d')

difflib モジュールのメソッド SequenceMatcher.get_matching_blocks() が、合致するサブシーケンスを記述するブロックについて、最小範囲リストを返すよう保障するようになりました。以前は時折 2 つのリストエントリに合致要素ブロックが分割されることがありました。(Enhancement by Tim Peters.)

doctest モジュールに、実行されるべきものから例を守る SKIP オプションが追加されています。これは、読者のための使用例として意図しているけれども実際のテストケースとして意図していないようなコードスニペットのために用意されました。

testfile() 関数と DocFileSuite にファイルのエンコーディングを指定するための encoding パラメータが追加されました。これにより docstring 内に非 ASCII 文字列を含むテストが簡単になります。(Contributed by Bjorn Tillenius.)

email パッケージがバージョン 4.0 にアップデートされました (Contributed by Barry Warsaw.)

The fileinput module was made more flexible. Unicode filenames are now supported, and a mode parameter that defaults to "r" was added to the input() function to allow opening files in binary or universal newlines mode. Another new parameter, openhook, lets you use a function other than open() to open the input files. Once you're iterating over the set of files, the FileInput object's new fileno() returns the file descriptor for the currently opened file. (Contributed by Georg Brandl.)

gc モジュールに、新しい関数 get_count() が追加されています。これは GC 3 世代についての現在の検出を含む 3 要素タプルを返します。これはガーベージコレクタの決算情報です; これらの数が指定された閾値に到達すると、ガーベージコレクトのスイープが起こります。既存の gc.collect() 関数は省略可能な generation 引数を取るようになっていて、これはどの世代を検出するかを指定する 0、1、2 です。 (Contributed by Barry Warsaw.)

heapq モジュールの nsmallest() 関数と nlargest() 関数がキーワードパラメータ key をサポートするようになっています。これは min()/max() 関数と sort() メソッドで提供されているものと似たものです。例えば:

>>> 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']

(Contributed by Raymond Hettinger.)

itertools.islice() 関数が start と step として None を受け付けるようになっています。これは slice オブジェクトとの互換性を高めるもので、つまり以下のように書くことが出来ます:

s = slice(5)     # Create slice object
itertools.islice(iterable, s.start, s.stop, s.step)

(Contributed by Raymond Hettinger.)

locale モジュールの format() 関数が更新され、2 つの関数 format_string() と currency() が追加されました。

format() 関数の val パラメータは以前は一つ以上の %文字指定子が現れる文字列が許されていました; 今はこのパラメータは正確に一つの %文字指定子を含む、周りに囲むテキストのない文字列でなければなりません。省略可能な monetary パラメータも追加されています。これが True の場合、通貨の書式化の 3 桁ごとに区切るセパレータに、ロケールのルールを使います。

複数 %文字指定子を含む文字列をフォーマットするには、 format() のように働き、任意のテキストと %文字指定子を混ぜた文字列をサポートする新しい format_string() 関数を使ってください。

現在ロケール設定に関連した数字を書式化する currency() 関数も追加されています。

(Contributed by Georg Brandl.)

mailbox モジュールでは、メールボックスについてそれを読むことに加えて修正出来る能力を追加するための、大々的な書き換えが行われています。 mbox, MH, Maildir を含む新しいクラス群はメールボックス読み込みに使われますが、メッセージ追加のための add(message) 、削除の remove(key) 、ロック/アンロックのための lock()/unlock() も持っています。続く例は maildir 形式から mbox 形式に変換する例です:

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)

(Contributed by Gregory K. Johnson. Funding was provided by Google's 2005 Summer of Code.)

New module: the msilib module allows creating Microsoft Installer .msi files and CAB files. Some support for reading the .msi database is also included. (Contributed by Martin von Löwis.)

The nis module now supports accessing domains other than the system default domain by supplying a domain argument to the nis.match() and nis.maps() functions. (Contributed by Ben Bell.)

operator モジュールの itemgetter() 関数と attrgetter() 関数が複数フィールドをサポートするようになりました。 operator.attrgetter('a', 'b') のように呼び出すと、 a と b 属性を取り出す関数を返します。この新機能と sort() メソッドの key パラメータを組み合わせると、複数フィールドでのリストのソートが簡単になります。

optparse モジュールが Optik ライブラリのバージョン 1.5.1 に更新されました。 OptionParser クラスに epilog 属性と destroy() メソッドが追加されています。前者はヘルプメッセージのあとに出力される文字列です。後者はオブジェクトによって作られた循環参照を破棄します。 (Contributed by Greg Ward.)

os モジュールに多数の変更がありました。 stat_float_times 値のデフォルトが真となっていて、これはつまり os.stat() が時刻の値を浮動小数点数で返すということです。(ただし必ずしも os.stat() が秒の端数が正確な値を返すという意味ではありません; 全てのシステムがそのような精度をサポートしてはいません。)

Constants named os.SEEK_SET, os.SEEK_CUR, and os.SEEK_END have been added; these are the parameters to the os.lseek() function. Two new constants for locking are os.O_SHLOCK and os.O_EXLOCK.

2 つの新しい関数 wait3() と wait4() が追加されています。これらは waitpid() 関数に似ています。これは子プロセスが終了するのを待ってプロセス ID とその終了コードを返しますが、 wait3() と wait4() は追加の情報を返します。 wait3() はプロセス ID を入力に取りませんので任意の子プロセス終了を待ち、 resource.getrusage() 関数から返る process-id, exit-status, resource-usage の 3 要素タプルを返します。 wait4(pid) はプロセス ID を取ります。 (Contributed by Chad J. Schroeder.)

FreeBSD では、 os.stat() 関数がナノ秒精度の時刻を返し、また、返却オブジェクトが st_gen と st_birthtime を持つようになっています。 st_flags 属性も、プラットフォームがサポートされている場合には利用可能です。 (Contributed by Antti Louko and Diego Pettenò.)

pdb モジュールで提供される Python デバッガが、ブレイクポイントに到達して実行が停止する際に実行するコマンドのリストを記憶するようになりました。ブレイクポイント #1 を作ったら、 commands 1 を入力し、実行するコマンド群を入力し、 end でリストを終えます。コマンドリストには continue や next のような実行再開コマンドを含めることが出来ます。 (Contributed by Grégoire Dooms.)

The pickle and cPickle modules no longer accept a return value of None from the __reduce__() method; the method must return a tuple of arguments instead. The ability to return None was deprecated in Python 2.4, so this completes the removal of the feature.

The pkgutil module, containing various utility functions for finding packages, was enhanced to support PEP 302 [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.)

Marc-André Lemburg による pybench ベンチマークスイートが Tools/pybench ディレクトリに含まれるようになりました。pybench スイートは、広く使われている pystone.py プログラムの改善版で、インタプリタの速度についてのより詳しい計測を行います。 pystone.py のように多くの異なる演算を実行したり単独の数字に縮退する代わりに、これは関数コール、タプルのスライス、メソッドの検索、数値演算のような特定の演算を計測します。 (---訳注: Tools についての言及すべてに共通することですが、原則として Tools は「全て」を入手する手段はソースコード配布を利用することだけです。インストールされるものはプラットフォーム依存や linux であればディストリビュータによっても変わります。顕著なのは Windows で、Tools 配下のものはごく限られたものだけがインストールされます。pybench もソースコード配布物にのみ含まれ、Windows 公式インストーラではインストールされません。なお、 pystone.py は Lib/test 内にあります。---)

pyexpat モジュールが使う Expat パーサをバージョン 2.0 にしました。 (Contributed by Trent Mick.)

The Queue class provided by the Queue module gained two new methods. 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, task_done(), to signal that processing for an item has been completed. (Contributed by Raymond Hettinger.)

古い regex, regsub モジュール、これは Python 2.0 からずっと非推奨になっていましたが、ついに削除されました。ほかにも、 statcache, tzparse, whrandom が削除されています。

dircmp や ni といった石器時代のモジュールを大事にしまっていた lib-old ディレクトリも削除されました。 lib-old がデフォルトで sys.path に含まれることはなかったので、あなたが明示的にそれを sys.path に入れてこなかった限り、この削除はあなたには関係ないでしょう。

rlcompleter モジュールが readline モジュールのインポートに依存しないようになりました。これにより非 Unix プラットフォームで動作するようになりました。 (Patch from Robert Kiendl.)

The SimpleXMLRPCServer and DocXMLRPCServer classes now have a rpc_paths attribute that constrains XML-RPC operations to a limited set of URL paths; the default is to allow only '/' and '/RPC2'. Setting rpc_paths to None or an empty tuple disables this path checking.

The socket module now supports 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 https://www.linuxjournal.com/article/7356. In Python code, netlink addresses are represented as a tuple of 2 integers, (pid, group_mask).

ソケットオブジェクトの 2 つの新たなメソッド、 recv_into(buffer), recvfrom_into(buffer) は、受信データを、文字列データとして返す代わりにバッファプロトコルをサポートするオブジェクトに書き込みます。このことにより、受信データを直接 array やメモリマップドファイルに置けます。

ソケットオブジェクトには getfamily(), gettype(), getproto() アクセッサメソッドも追加されています。それぞれソケットについてのアドレスファミリ、タイプ、プロトコルを取得します。

New module: the spwd module provides functions for accessing the shadow password database on systems that support shadow passwords.

pack(), unpack() メソッドでフォーマット文字列を Struct オブジェクトにコンパイルすることで、 struct がより高速になっています。これは re モジュールでコンパイル済み正規表現オブジェクトを作れるのに似ています。モジュールレベルの pack(), unpack() 関数もそのまま使えます; それらは Struct オブジェクトを作ってキャッシュします。あるいは Struct インスタンスを直接使えます:

s = struct.Struct('ih3s')

data = s.pack(1972, 187, 'abc')
year, number, name = s.unpack(data)

You can also pack and unpack data to and from buffer objects directly using the pack_into(buffer, offset, v1, v2, ...) and unpack_from(buffer, offset) methods. This lets you store data directly into an array or a memory-mapped file.

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

Python デベロッパは 2.5 開発プロセスの間で CVS から Subversion に移行しました。ビルドバージョンについての正確な情報は sys.subversion により取得可能で、これは 3 要素タプル (interpreter-name, branch-name, revision-range) です。例えば執筆時点では 2.5 で ('CPython', 'trunk', '45313:45315') を返します。 (---訳注: Python 3.2 から 3.3 にかけて、開発が Mercurial に移行していて、これは 2.7 メンテナンスリリースの間にあたります。今(3.6 dev 時点)では全て Mercurial に移行しており、 sys.subversion は今では意味のある値は返しません。3.3 からは既に sys.subversion は削除されています。---)

この情報は C 拡張から Py_GetBuildInfo() 関数を使っても得ることが出来ます。これはビルド情報についての文字列を返し、例えば "trunk:45355:45356M, Apr 13 2006, 07:42:19" のような値です。 (Contributed by Barry Warsaw.)

もう一つの新規関数 sys._current_frames() は、実行スレッドについての現在スタックフレームを、各スレッドの識別子がキーの辞書として返します。辞書の値は、関数が呼ばれた時点のそのスレッドで現在アクティブになっているスタックフレームの一番上です。(Contributed by Tim Peters.)

tarfile モジュールの TarFile クラスに extractall() メソッドが追加されました。アーカイブから全てのメンバをカレントディレクトリに抽出します。抽出ターゲットとして別のディレクトリも指定できますし、アーカイブメンバのサブセットのみ解凍することも出来ます。

ストリームモードで開く tarfile に使われる圧縮を、モード 'r|*' を使って自動で検出出来るようになっています。 (Contributed by Lars Gustäbel.)

threading モジュールで、新しいスレッドを作る際に使われるスタックサイズを設定出来るようになりました。 stack_size([*size*]) 関数は現在構成されているスタックサイズを返し、省略可能引数 size パラメータを与えると新しい値を設定します。全てのプラットフォームがスタックサイズ変更をサポートしているわけではなく、Windows、POSIX スレッド、OS/2 で可能です。 (Contributed by Andrew MacIntyre.)

The 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 unicodedata.ucd_3_2_0.

新モジュール: uuid モジュールは RFC 4122 [https://datatracker.ietf.org/doc/html/rfc4122.html] による UUID (universally unique identifiers) を生成します。その RFC ではいくつかの異なる UUID のバージョンを定義しており、文字列から生成するもの、システム特性から生成するもの、純粋に乱数から生成するものがあります。このモジュールでは UUID クラスと uuid1(), uuid3(), uuid4(), uuid5() 関数を持っていて、それら異なったバージョンの UUID を生成します。(UUID バージョン 2 は RFC 4122 [https://datatracker.ietf.org/doc/html/rfc4122.html] にありませんのでこのモジュールにもないです)

>>> 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')

(Contributed by Ka-Ping Yee.)

weakref モジュールの WeakKeyDictionary 型と WeakValueDictionary 型に、辞書内に含まれる弱参照を巡回する新たなメソッドが追加されています。 iterkeyrefs() と keyrefs() が WeakKeyDictionary に追加され、 itervaluerefs() と valuerefs() が WeakValueDictionary に追加されました。(Contributed by Fred L. Drake, Jr.)

The webbrowser module received a number of enhancements. It's now usable as a script with python -m webbrowser, taking a URL as the argument; there are a number of switches to control the behaviour (-n for a new browser window, -t for a new tab). New module-level functions, open_new() and open_new_tab(), were added to support this. The module's 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.)

The xmlrpclib module now supports returning datetime objects for the XML-RPC date type. Supply use_datetime=True to the loads() function or the Unmarshaller class to enable this feature. (Contributed by Skip Montanaro.)

zipfile モジュールが ZIP64 バージョンのフォーマットをサポートしました。これで 4GiB を超える zip 書庫を作れ、4GiB を超えるファイルを書庫に含めることが出来ます。 (Contributed by Ronald Oussoren.)

zlib モジュールの Compress , Decompress オブジェクトが copy() メソッドをサポートするようになりました。オブジェクトの内部状態を複製して新しい Compress あるいは Decompress オブジェクトを返します。 (Contributed by Chris AtLee.)

ctypes パッケージ

The ctypes package, written by Thomas Heller, has been added to the standard library. ctypes lets you call arbitrary functions in shared libraries or DLLs. Long-time users may remember the dl module, which provides functions for loading shared libraries and calling functions in them. The ctypes package is much fancier.

シェアドライブラリや DLL をロードするには、 CDLL クラスのインスタンスを、その名前かパスを渡して構築します。構築したら、 CDLL オブジェクトの属性にアクセスすることで任意の関数呼び出しが出来ます:

import ctypes

libc = ctypes.CDLL('libc.so.6')
result = libc.printf("Line of output\n")

Type constructors for the various C types are provided: c_int(), c_float(), c_double(), c_char_p() (equivalent to char*), and so forth. Unlike Python's types, the C versions are all mutable; you can assign to their 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.)

C 関数がメモリ領域を更新するものである場合、Python 文字列に c_char_p() を使うべきではありません。 Python 文字列は immutable であることを前提としているからです; この規則を犯すことは頭を掻き毟るバグを引き起こすでしょう。更新可能なメモリ領域が必要な場合は create_string_buffer() を使います:

s = "this is a string"
buf = ctypes.create_string_buffer(s)
libc.strfry(buf)

C 関数はデフォルトでは整数を返すと仮定されますが、関数オブジェクトの restype 属性をセットすることでこれを変更出来ます:

>>> libc.atof('2.71828')
-1783957616
>>> libc.atof.restype = ctypes.c_double
>>> libc.atof('2.71828')
2.71828

ctypes also provides a wrapper for Python's C API as the 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 py_object() type constructor that will create a PyObject* pointer. A simple usage:

import ctypes

d = {}
ctypes.pythonapi.PyObject_SetItem(ctypes.py_object(d),
          ctypes.py_object("abc"),  ctypes.py_object(1))
# d is now {'abc', 1}.

py_object() を使うことを忘れないように; 怠るとセグメンテーション違反と相成る、はず。

ctypes が周辺ライブラリとして登場してしばらく経ちますが、ctypes が存在していることに依存できないとなれば人々はまだハードコードされた拡張モジュールを書いて配布します。 ctypes が Python 中核に含められた今、おそらく開発者たちは、拡張モジュールの代わりに ctypes を介してアクセスするライブラリの上に Python ラッパーを書き始めるでしょう,

参考

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.

ctypes モジュールについてのドキュメント。

ElementTree パッケージ

XML 処理のための、Fredrik Lundh の ElementTree ライブラリのサブセットが、標準ライブラリに xml.etree として追加されました。利用可能なモジュールは ElementTree 1.2.6 よりの ElementTree, ElementPath, ElementInclude です。 C 実装 cElementTree モジュールも含まれています。

The rest of this section will provide a brief overview of using ElementTree. Full documentation for ElementTree is available at https://web.archive.org/web/20201124024954/http://effbot.org/zone/element-index.htm.

ElementTree は XML ドキュメントを、要素ノードのツリーとして表現します。ドキュメントのテキストコンテントは text 属性と tail 属性に格納されます (これが ElementTree と Document Object Model (DOM) との一番大きな違いです; DOM 内ではノードの数多くの型があります。 TextNode はその一つです。)

最も一般的に使う解析関数は parse() です。これは (ファイル名が含まれるとみなされる) 文字列またはファイルのようなオブジェクトを受け取って、 ElementTree インスタンスを返します:

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)

ElementTree インスタンスを手にしてしまえば、あとはルートの Element ノードを得るために getroot() を呼び出せます。

文字列リテラルを受け取って (ElementTree ではなく) Element ノードを返す XML() 関数 もあります。この関数を使えば、簡単に XML リテラルを使って XML 断片からツリーを組み上げることが綺麗に出来ます:

svg = ET.XML("""<svg width="10px" version="1.0">
             </svg>""")
svg.set('height', '320px')
svg.append(elem1)

個々の XML 要素はいくつかの辞書のような、いくつかのリストのようなメソッドをサポートしています。辞書的な操作は属性値のアクセスに使い、リスト的な操作は子ノードのアクセスに使います。

演算

結果

elem[n]

n 番目の子要素を返す。

elem[m:n]

m 番目から n 番目までの子要素を返す(---訳注: n は含まない---)。

len(elem)

子要素数を返す。

list(elem)

子要素のリストを返す。

elem.append(elem2)

elem2 を子として追加する。

elem.insert(index, elem2)

指定された位置に elem2 を挿入する。

del elem[n]

n 番目の子要素を削除する。

elem.keys()

属性名のリストを返す。

elem.get(name)

属性 name の値を返す。

elem.set(name, value)

属性 name に新しい値をセットする。

elem.attrib

属性を含んだ辞書を取り出す。

del elem.attrib[name]

属性 name を削除する。

コメントと処理命令 (processing instruction=PI) も、 Element ノードで表現されます。ノードがコメントあるいは処理命令であるかをチェックするにはこのようにします:

if elem.tag is ET.Comment:
    ...
elif elem.tag is ET.ProcessingInstruction:
    ...

XML 出力を生成するには ElementTree.write() メソッドを呼び出す必要があります。 parse() のように、文字列もしくはファイルのようなオブジェクトを渡せます:

# Encoding is US-ASCII
tree.write('output.xml')

# Encoding is UTF-8
f = open('output.xml', 'w')
tree.write(f, encoding='utf-8')

(警告: 出力に使われるデフォルトエンコーディングは ASCII です。一般的な XML での作業では要素名に任意の Unicode 文字を含められるので、ASCII エンコーディングはあまり役に立ちません。要素名に 127 より大きなどんな文字が含まれても例外となりますので。ですから任意の Unicode 文字を扱うために UTF-8 のようなエンコーディングを指定するのが吉です。)

このセクションでは ElementTree インターフェイスのほんの一部しか記載していません。さらに詳しい情報については、パッケージの公式ドキュメントを参照して下さい。

参考

https://web.archive.org/web/20201124024954/http://effbot.org/zone/element-index.htm

ElementTree の公式ドキュメント

hashlib パッケージ

A new hashlib module, written by Gregory P. Smith, has been added to replace the md5 and sha modules. 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 md5 and 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.

# 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

ハッシュオブジェクトを作ってしまえばあとはそのメソッドは以前と同じです: update(string) は指定された文字列を現在のダイジェスト状態にハッシュ更新し、 digest() と hexdigest() は結果のダイジェスト値をバイナリ文字列・16進数表記文字列として返し、 copy() はダイジェスト状態を複製して新たなハッシュオブジェクトを作ります。

参考

hashlib モジュールについてのドキュメント。

sqlite3 パッケージ

The pysqlite module (https://www.pysqlite.org), a wrapper for the SQLite embedded database, has been added to the standard library under the package name sqlite3.

SQLite は、軽量なディスク上のデータベースを提供する C ライブラリです。別のサーバプロセスを用意する必要なく、 SQL クエリー言語の非標準的な一種を使用してデータベースにアクセスできます。一部のアプリケーションは内部データ保存に SQLite を使えます。また、SQLite を使ってアプリケーションのプロトタイプを作り、その後そのコードを PostgreSQL や Oracle のような大規模データベースに移植するということも可能です。

pysqlite は Gerhard Häring によって書かれ、 PEP 249 [https://peps.python.org/pep-0249/] に記述された DB-API 2.0 仕様に準拠した SQL インターフェースを提供するものです。

ソースコードから Python をビルドする場合は注意してください。Python ソースツリーは SQLite コードを含まずラッパーモジュールのみを含んでいます。Python ビルド前に SQLite ライブラリとヘッダをインストールする必要があります。必要ヘッダが利用可能となっていればモジュールはビルドされます。

このモジュールを使うには、最初にデータベースを表す Connection オブジェクトを作ります。ここではデータはファイル /tmp/example に格納されているものとします。

conn = sqlite3.connect('/tmp/example')

特別な名前である :memory: を使うと RAM 上にデータベースを作ることもできます。

Connection があれば、 Cursor オブジェクトを作りその execute() メソッドを呼んで SQL コマンドを実行することができます:

c = conn.cursor()

# Create table
c.execute('''create table stocks
(date text, trans text, symbol text,
 qty real, price real)''')

# Insert a row of data
c.execute("""insert into stocks
          values ('2006-01-05','BUY','RHAT',100,35.14)""")

たいてい、SQL 操作は Python 変数の値を使う必要があります。この時、クエリーを Python の文字列操作を使って構築することは、安全とは言えないので、すべきではありません。そのようなことをするとプログラムが SQL インジェクション攻撃に対し脆弱になりかねません。

代わりに、DB-API のパラメータ割り当てを使います。 ? を変数の値を使いたいところに埋めておきます。その上で、値のタプルをカーソルの execute() メソッドの第2引数として引き渡します。(他のデータベースモジュールでは変数の場所を示すのに %s や :1 などの異なった表記を用いることがあります。) 例を示します:

# 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)

SELECT 文を実行した後データを取得する方法は3つありどれを使っても構いません。一つはカーソルをイテレータ (iterator) として扱う、一つはカーソルの fetchone() メソッドを呼んで一致した内の一行を取得する、もう一つは fetchall() メソッドを呼んで一致した全ての行のリストとして受け取る、という3つです。

以下の例ではイテレータの形を使います:

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

SQLite でサポートされる SQL 方言についてもっと詳しく知りたければ、 http://www.sqlite.org を参照して下さい。

参考

https://www.pysqlite.org

pysqlite のウェブページ。

https://www.sqlite.org

SQLite のウェブページ。ここの文書ではサポートされる SQL 方言の文法と使えるデータ型を説明しています。

sqlite3 モジュールについてのドキュメント。

PEP 249 [https://peps.python.org/pep-0249/] - Database API Specification 2.0

Marc-Andre Lemburg により書かれた PEP。

wsgiref パッケージ

Web Server Gateway Interface (WSGI) v1.0 は、 Web サーバと Python で記述された Web アプリケーションとの標準インターフェースであり、 PEP 333 [https://peps.python.org/pep-0333/] で定義されています。 wsgiref パッケージは WSGI 仕様のリファレンス実装です。

パッケージには WSGI アプリケーションとして動作する基礎的な HTTP サーバが含まれています; このサーバは製品ユースではないデバッグ目的に有用です。サーバをセットアップするには僅か数行で済みます:

from wsgiref import simple_server

wsgi_app = ...

host = ''
port = 8000
httpd = simple_server.make_server(host, port, wsgi_app)
httpd.serve_forever()

参考

https://web.archive.org/web/20160331090247/http://wsgi.readthedocs.org/en/latest/

WSGI 関連のリソースについて集約しているウェブサイト。

PEP 333 [https://peps.python.org/pep-0333/] - Python Web Server Gateway Interface v1.0

PEP 著 Phillip J. Eby.

ビルドならびに C API の変更

Python のビルド過程と C API の変更は以下の通りです:

Python ソースツリーは CVS から Subversion に変換されました。この複雑な移行手続きは Martin von Löwis によって指揮されつつがなく遂行されました。この手続きは PEP 347 [https://peps.python.org/pep-0347/] にて開発されました。

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 https://scan.coverity.com for the statistics.

The largest change to the C API came from PEP 353 [https://peps.python.org/pep-0353/], which modifies the interpreter to use a Py_ssize_t type definition instead of int. See the earlier section PEP 353: 添え字型に ssize_t を使う for a discussion of this change.

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 compile() built-in and specifying _ast.PyCF_ONLY_AST as the value of the flags parameter:

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]

No official documentation has been written for the AST code yet, but PEP 339 [https://peps.python.org/pep-0339/] discusses the design. To start learning about the code, read the definition of the various AST nodes in Parser/Python.asdl. A Python script reads this file and generates a set of C structure definitions in Include/Python-ast.h. The PyParser_ASTFromString() and PyParser_ASTFromFile(), defined in 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 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.

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, PyMem_Malloc(), PyMem_Realloc(), and PyMem_Free() are one family that allocates raw memory, while PyObject_Malloc(), PyObject_Realloc(), and 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 malloc() and free() functions. This meant it didn't matter if you got things wrong and allocated memory with the PyMem function but freed it with the 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.

ビルトインの集合型のために公式の C API が作られました。新しく作るのには PySet_New() か PyFrozenSet_New() を、要素の追加には PySet_Add() 、削除には PySet_Discard() 、 PySet_Contains() と PySet_Size() で集合オブジェクトの状態を調べます。 (Contributed by Raymond Hettinger.)

C コードから Python インタプリタの正確なリビジョンについての情報を取得出来るようになりました。 Py_GetBuildInfo() 関数を呼び出すことでビルド情報についての文字列が "trunk:45355:45356M, Apr 13 2006, 07:42:19" のように返ります。 (Contributed by Barry Warsaw.)

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. Py_LOCAL(type) declares the function as returning a value of the specified type and uses a fast-calling qualifier. Py_LOCAL_INLINE(type) does the same thing and also requests the function be inlined. If macro PY_LOCAL_AGGRESSIVE is defined before 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.)

PyErr_NewException(name, base, dict) が base 引数としてベースクラスのタプルを受け付けるようになりました。 (Contributed by Georg Brandl.)

The PyErr_Warn() function for issuing warnings is now deprecated in favour of 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 PyErr_WarnEx(), 2 is the function above that, and so forth. (Added by Neal Norwitz.)

CPython は今でも C で書かれていますが、コードは C++ コンパイラでもエラーなしでコンパイル出来るようになりました。 (Implemented by Anthony Baxter, Martin von Löwis, Skip Montanaro.)

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

range = PyObject_CallFunction((PyObject*) &PyRange_Type, "lll",
                              start, stop, step);

ポート特有の変更

MacOS X (10.3 以上): モジュールの動的ロードに、MacOS 固有の関数ではなく dlopen() 関数を使うようになりました。

MacOS X: an --enable-universalsdk switch was added to the 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 [https://bugs.python.org/issue?@action=redirect&bpo=2573].)

Windows: .dll はもはや拡張モジュールのファイル拡張子としてはサポートされません。これからは .pyd だけが拡張モジュールとして検索されるファイル拡張子です。

Python 2.5 への移植

このセクションでは前述の変更により必要となるかもしれないコードの変更を列挙します:

ASCII がモジュールのデフォルトエンコーディングになっています(訳注: Python 3 からはデフォルトは utf-8 (PEP 3120))。8 ビット文字を含んでいるのにエンコーディング宣言がないモジュールが構文エラーになるようになりました。Python 2.4 では構文エラーとはならず警告でした。

以前はジェネレータの gi_frame 属性は常にフレームオブジェクトでしたが、 PEP 342: ジェネレータの新機能 で説明した PEP 342 [https://peps.python.org/pep-0342/] での変更により、 gi_frame は None になりえます。

Unicode 文字列とデフォルトの ASCII エンコーディングで Unicode に変換出来ない 8 ビット文字列との比較を試みると、新しい警告 UnicodeWarning が引き起こされるようになっています。以前はそのような比較では UnicodeDecodeError 例外を起こしていました。

ライブラリ: csv モジュールは引用符内のマルチラインをより厳密に扱うようになっています。フィールド内に改行を埋め込んでいるファイルがある場合は、その入力は改行文字を残すやり方で行分解されるはずです。

ライブラリ: locale モジュールの format() 関数は、以前は %文字指定子が一つを超えてさえいなければ任意の文字列を受け付けていたかもしれませんが、Python 2.5 からは正確に一つの、ほかに周りをテキストで囲まれていない %文字指定子でなければなりません。

Library: The pickle and cPickle modules no longer accept a return value of None from the __reduce__() method; the method must return a tuple of arguments instead. The modules also no longer accept the deprecated bin keyword parameter.

Library: The SimpleXMLRPCServer and DocXMLRPCServer classes now have a rpc_paths attribute that constrains XML-RPC operations to a limited set of URL paths; the default is to allow only '/' and '/RPC2'. Setting rpc_paths to None or an empty tuple disables this path checking.

C API: Many functions now use 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 PEP 353: 添え字型に ssize_t を使う for a discussion of this change.

C API: The obmalloc changes mean that you must be careful to not mix usage of the PyMem_* and PyObject_* families of functions. Memory allocated with one family's *_Malloc must be freed with the corresponding family's *_Free function.

謝辞

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.

What's New in Python 2.4

著者:

A.M. Kuchling

この文書は 2005 年 3 月 30 日にリリースされた Python 2.4.1 の新機能について解説します。

Python 2.4 は、真ん中サイズ、のリリースです。急進的だった Python 2.2 ほどには多くの変更をしていませんが、保守的だった 2.3 よりは多くの機能を導入しています。新しい言語機能で最も重要なのが、関数デコレータとジェネレータ式です。ほかのほとんどの変更は標準ライブラリに対するものです。

Python 2.3 から 2.4 の CVS 変更ログによれば、適用されたパッチは 481、フィックスされたバグは 502 ありました。ともに、少なく見積もって、です。

このドキュメントは個々の新機能の完全な詳細を提供するのではなくて、簡易な概要を提供することを目的にしています。完全な詳細が知りたければ、 Python ライブラリリファレンス、Python リファレンスマニュアルのような Python 2.4 のドキュメントを参照してください。多くの場合個別の新機能についての実装の説明やデザインの根拠については PEP に託されています。

PEP 218: ビルトインの集合オブジェクト

Python 2.3 では sets モジュールを導入しました。集合データ型の C 実装が Python コアに新たに、2 つの新しいビルトイン型 set(iterable) と frozenset(iterable) として追加されています。これらは要素が集合に属しているかのメンバシップテスト、シーケンスからの重複の削除、それに和集合 (union)、共通集合 (intersection)、 差 (difference)、対称差 (symmetric difference) といった数学演算を高速に行います:

>>> 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'])
>>> ''.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'])

frozenset() 型は set() の immutable 版です。 immutable かつハッシュ可能なので、辞書のキーやほかの set のメンバとして使えるでしょう。

2.3 で追加された sets モジュールは標準ライブラリに残されていて、 Set や ImmutableSet をサブクラス化したければ便利かもしれません。今のところこれを撤廃する予定はありません。(---訳注: sets モジュールは 2.6 で非推奨となっています。---)

参考

PEP 218 [https://peps.python.org/pep-0218/] - 集合オブジェクト型をビルトインに追加する

元々は Greg Wilson によって提案され、完全な実装は Raymond Hettinger によってなされました。

PEP 237: 長整数と整数を一体化していく

この PEP の非常に長期に渡る移行は Python 2.2 に始まり、Python 2.4 でさらにもう一歩前進しています。2.3 では int/long の一体化後に異なる振る舞いをする整数演算をすると FutureWarning 警告を出して、結果の値は (プラットフォーム依存で) 32 ビットまたは 64 ビットに制限していました。2.4 ではこれらの式はもう警告は出さず、代わりにいつでも(2.3 とは違った)長整数となる結果をはじき出します。

問題を起こしうる式は主として左シフトで、そして長い 16 進リテラルと 8 進リテラルです。例えば 2 << 32 は 2.3 では警告とともに 32 ビットプラットフォームでは結果は 0 になります。Python 2.4 ではこの式は正しい答えの 8589934592 になります。

参考

PEP 237 [https://peps.python.org/pep-0237/] - 長整数と整数を一体化していく

オリジナルの PEP は Moshe Zadka と GvR (Guido van Rossum) によって書かれました。.2.4 での変更については Kalle Svensson によって実装されました。

PEP 289: ジェネレータ式

The iterator feature introduced in Python 2.2 and the 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:

links = [link for link in get_all_links() if not link.followed]
for link in links:
    ...

こうではなく

for link in get_all_links():
    if link.followed:
        continue
    ...

最初の形の方が簡潔でおそらく読みやすいですが、扱っているのがとても多くのリンクオブジェクトであるならば、全てのリンクオブジェクトが一気にメモリに載らないように二つ目の形で書く必要がありました。

ジェネレータ式はリスト内包と似た動作をしますが、リスト全体を実体化しません; 代わりにそれは、要素を一つずつ返すジェネレータを返します。上述の例はこう書けます:

links = (link for link in get_all_links() if not link.followed)
for link in links:
    ...

上の例でのように、ジェネレータ式は常に括弧の中に書かなければなりません。関数呼び出しを囲む括弧もそれに含まれるので、関数にそのまま渡すイテレータを作りたければこれで良いです:

print sum(obj.count for obj in list_all_objects())

ジェネレータ式はリスト内包とは色々小さい点で違います。最も顕著なのはループ変数 (上の例での obj) がジェネレータ式の外からアクセス不能なことです。リスト内包はループの制御変数が最後に代入された値で残ります; 将来のバージョンの Python では、この振る舞いはリスト内包がこの点でジェネレータ式と同じになるように変更されます。 (---訳注: Python 2.7 でもリスト内包のこの振る舞いは変わっておらず、警告ともなりません。制御変数が内包のスコープ外で可視でなくなったのは Python 3.0 からです。---)

参考

PEP 289 [https://peps.python.org/pep-0289/] - ジェネレータ式

Raymond Hettinger によって提案され、Hye-Shik Chang に導かれた早期の尽力によって Jiwon Seo により実装されました。

PEP 292: より単純な文字列置換 (string substitution)

標準ライブラリに、文字列を変数で置換するための代替メカニズムをもたらす新しいくつかのクラスが追加されました; この置換のスタイルは、訓練されていないユーザがテンプレートを編集する必要があるようなアプリケーションにとって、より良いものでしょう。

変数置換を名前で行うためのいつもの方法は % 演算子です:

>>> '%(page)i: %(title)s' % {'page':2, 'title': 'The Best of Times'}
'2: The Best of Times'

テンプレート文字列を書くのに、閉じ括弧のあとの i や s を忘れやすいです。これはそのテンプレートが Python モジュール内にあるなら大問題でもありません。コードを実行し、「サポートされないフォーマット文字 (unsupported format character)」な ValueError を喰らい、問題を直すだけのことです。ですが、例えば Mailman のようなアプリケーションを考えてみてください。テンプレート文字列や翻訳は、Python 言語について承知していないユーザが編集するのです。フォーマット文字列の構文はそのようなユーザに説明するには複雑で、彼らが間違いをやらかした場合には、親切なフィードバックを彼らに与えるのは難しいのです。

PEP 292 は string モジュールに Template クラスを追加します。これは置換を指示するのに $ を使います:

>>> import string
>>> t = string.Template('$page: $title')
>>> t.substitute({'page':2, 'title': 'The Best of Times'})
'2: The Best of Times'

辞書にキーが見つからない場合、 substitute() メソッドは KeyError を送出します。 safe_substitute() メソッドもあり、これはキー不在を無視します:

>>> t = string.Template('$page: $title')
>>> t.safe_substitute({'page':3})
'3: $title'

参考

PEP 292 [https://peps.python.org/pep-0292/] - より単純な文字列置換 (string substitution)

Barry Warsaw 著、実装

PEP 318: 関数とメソッドのためのデコレータ

Python 2.2 は Python オブジェクトモデルを静的メソッド、クラスメソッドを追加することで拡張はしましたが、それらを定義する新たな手段を提供するような Python 構文の拡張はしませんでした。このため、 def でメソッドは普通に書いたのち、新型メソッドとしての関数へ仕立て上げる staticmethod() または classmethod() にその結果のメソッドを渡す、という手順を取る必要がありました。このような具合でした:

class C:
   def meth (cls):
       ...

   meth = classmethod(meth)   # Rebind name to wrapped-up class method

メソッドがとても長かったりすると、関数のボディの後ろの classmethod() 呼び出しは見失ったり忘れたりしやすいものでした。

そのような定義をもっと読みやすくするために何か構文を追加する、という意図は常にありましたが、2.2 のリリース時点では良い構文は明らかではありませんでした。本日時点でさえ いまだ 明らかとは言えませんが、ユーザは静的メソッドとクラスメソッドを簡単に手にする手段を注文し続けています; 新たな構文的機能はこの要求に合うように追加されました。

この新たな機能は「関数デコレータ (function decorators)」と呼ばれます。この名前は classmethod(), staticmethod(), とその仲間たちが関数オブジェクトに追加的な情報を保存することから着想を得たものです; それらは関数をより多くの詳細で デコレート (修飾) している というわけです。

記法は Java より拝借して '@' 文字を指示子として使います。この新たな構文を使うと、上記の例はこのように書けます:

class C:

   @classmethod
   def meth (cls):
       ...

@classmethod は meth=classmethod(meth) 代入の速記法です。より一般的には、このように書けば…:

@A
@B
@C
def f ():
    ...

これはデコレータ前史の以下コードと等価です:

def f(): ...
f = A(B(C(f)))

デコレータは関数定義の前になければなりません。一行ごとに一つのデコレータです。 def ステートメントと同じ行にあってはダメです。つまり @A def f(): ... は不正です。モジュールレベルかクラス内の関数定義のみをデコレート出来ます; クラス定義はデコレート出来ません。(--- 訳注: クラス定義のデコレータは Python 2.6 で追加されました (PEP 3129) 。---)

デコレータはただの関数です。引数としてデコレートされる関数を取り、同じ関数か何か新しいオブジェクトを返すだけの。結果がほかのデコレータ適用されるの出ない限りは、デコレータの戻り値は呼び出し可能である必要はありません (普通はそうですが)。あなた自身のデコレータを書くのは簡単です。続く単純な例は、関数オブジェクトに単に属性をセットするだけのものです:

>>> def deco(func):
...    func.attr = 'decorated'
...    return func
...
>>> @deco
... def f(): pass
...
>>> f
<function f at 0x402ef0d4>
>>> f.attr
'decorated'
>>>

もう少しだけ現実的な例として、続く例ではデコレータに、与えられた引数が整数かどうかチェックさせてみます:

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

PEP 318 [https://peps.python.org/pep-0318/] にある例はこのアイディアのもっと凝った版が含まれていて、それは要求型の指定と戻り値のチェックの両方が出来ます。

デコレータ関数は引数を取ることが出来ます。引数が与えられた場合、あなたのデコレータ関数はそれら引数のみで呼び出され、そして新しいデコレータを返さなければなりません; この関数は単一の関数を取らなければならず、前述のように関数を返さなければなりません。言い換えると、 @A @B @C(args) はこうなります:

def f(): ...
_deco = C(args)
f = A(B(_deco(f)))

これが正しいと理解するには少しばかり頭をひねる必要がありますが、難しすぎることはありません。

A small related change makes the 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.

参考

PEP 318 [https://peps.python.org/pep-0318/] - 関数、メソッド、クラスのためのデコレータ

Kevin D. Smith, Jim Jewett, Skip Montanaro により著されました。数多くの人々が関数デコレータ実装のパッチを書きましたが、実際にチェックインされたものは Mark Russell が書いた #979728 でした。

https://wiki.python.org/moin/PythonDecoratorLibrary

数多くのデコレータ例を含む Wiki ページ。

PEP 322: 逆順のイテレーション

新しいビルトイン関数 reversed(seq) は、シーケンスを受け取って、シーケンスの要素を逆順にループするイテレータを返します:

>>> for i in reversed(xrange(1,4)):
...    print i
...
3
2
1

range(1,4)[::-1] のようにする拡張スライスでのやり方に比較して reversed() は読みやすく、実行が高速で、大体の場合はメモリ使用が少なく済みます。

reversed() は任意のイテレータは受け付けず、シーケンスのみ受け付けることに注意してください。イテレータを逆順にしたければ、最初に list() でリストに変換してください:

>>> input = open('/etc/passwd', 'r')
>>> for line in reversed(list(input)):
...   print line
...
root:*:0:0:System Administrator:/var/root:/bin/tcsh
  ...

参考

PEP 322 [https://peps.python.org/pep-0322/] - 逆順のイテレーション

Raymond Hettinger 著、実装.

PEP 324: 新しい subprocess モジュール

The standard library provides a number of ways to execute a subprocess, offering different features and different levels of complexity. 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 popen2 module offers classes that can capture standard output and standard error from the subprocess, but the naming is confusing. The subprocess module cleans this up, providing a unified interface that offers all the features you might need.

Instead of popen2's collection of classes, subprocess contains a single class called subprocess.Popen whose constructor supports a number of different keyword arguments.

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

args は普通は文字列のシーケンスで、サブプロセスとして実行するプログラムへの引数群となります。 (shell 引数が真の場合は args はシェルに解釈を任せるために渡す文字列に出来、つまりこの場合 os.system() と同じことをします。)

stdin, stdout, stderr はサブプロセスの入力・出力・エラーのストリームを指定します。ファイルオブジェクトかファイル記述子を渡すことが出来ます。あるいは定数 subprocess.PIPE を渡してサブプロセスと親とのパイプを作成することが出来ます。

コンストラクタには多くの便利なオプションがあります:

close_fds はサブプロセス実行前に全てのファイル記述子をクローズすることを要求します。

cwd はサブプロセスを実行する作業ディレクトリを指定します (デフォルトは親の作業ディレクトリです)。

env は環境変数を指定する辞書です。

preexec_fn は子が開始する前に呼び出される関数です。

universal_newlines で、子の入出力を、Python の universal newlines 機能で開きます。

Popen インスタンスを作ってしまえば、あとはサブプロセスが終了するまで停止するために wait() メソッド呼び出すことが出来、停止することなく終了をチェックするのに poll() メソッドを呼び出すことが出来、あるいは communicate(data) を呼び出して、子の標準入力に data を送信することが出来ます。 communicate(data) はサブプロセスが送信する標準出力と標準エラー出力を読み込み、タプル (stdout_data, stderr_data) を返します。

call() は Popen コンストラクタにその引数を流し込むショートカットで、コマンドが終了するまで待ち、サブプロセスの終了コードを返します。これは os.system() に対する安全な置き換えとなりえます:

sts = subprocess.call(['dpkg', '-i', '/tmp/new-package.deb'])
if sts == 0:
    # Success
    ...
else:
    # dpkg returned an error
    ...

コマンドはシェルを使うことなく呼び出されます。もしシェルを本当に使いたいのであればキーワード引数として shell=True を与えた上でシーケンスの代わりに文字列を与えることが出来ます:

sts = subprocess.call('dpkg -i /tmp/new-package.deb', shell=True)

PEP にはシェルと Python コードの様々な例が採られていて、シェルスクリプトをいかにして subprocess を用いて Python コードに変換するかを示しています。PEP のこのセクションを読むことを強くお勧めします。

参考

PEP 324 [https://peps.python.org/pep-0324/] - subprocess - プロセスのための新たなモジュール

Fredrik Lundh 他によるサポートによって、Peter Åstrand により PEP 著と実装が行われました。

PEP 327: Decimal データ型

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 Decimal type can represent these fractions accurately, up to a user-specified precision limit.

なぜ Decimal が必要なのか?

浮動小数点数が使う表現方法に起因する制約があります。浮動小数点数は 3 つの構成要素から成ります:

符号(sign)。正または負。

仮数部(mantissa)。一桁の 2 進値に端数部が続きます。例えば 2 進数で 1.01 は 1 + 0/2 + 1/4 で 10 進表記で 1.25 です。

指数部(exponent)。小数点がその数値のどこに位置するかを表します。

例えば 1.25 は、正の符号を持ち、仮数部の値は (2 進数で) 1.01 で、指数部は 0 です (小数点は移動の必要がありません)。5 は同じ符号と仮数部を持ち、指数部は、仮数部が 4 倍なので 2 (2 を底とする 2 の 冪乗) です; 1.25 * 4 は 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 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.

ときどきあなたはこの不正確さを、数値を表示する際に目にするでしょう:

>>> 1.1
1.1000000000000001

この不正確さは数値を表示する際にいつでも目に見えるわけではありません。浮動小数点数から文字列への変換が C ライブラリによって提供されていて、C ライブラリのほとんどが賢明な出力を生成しようと頑張っているからです。それが表示されないにしても、不正確さはそれでも存在していて、後続の計算への誤差が大きくなりえます。

多くのアプリケーションではこれは重要ではありません。モニタにプロットして表示するのに 1.1 と 1.1000000000000001 の差は小さすぎて見えません。大抵は出力を一定の桁位置までに制限して出力するものですし、2 やら 3 やら 8 桁などの位置で丸めたりすれば誤差は決して露わにはなりません。ですがそれが重要なアプリケーションにとっては、あなた自身のカスタム数学ルーチンのための実装作業は膨大になります。

こうして Decimal 型が作られました。

Decimal 型

新しいモジュール decimal が Python 標準ライブラリに追加されました。これには 2 つのクラス Decimal, Context を含みます。 Decimal インスタンスは数値を表現し、 Context インスタンスは、精度やデフォルトの丸めモードなどのさまざまな設定をまとめるのに使われます。

Decimal のインスタンスは普通の Python 整数や浮動小数点数のように immutable です。 Decimal のインスタンスは整数や文字列から構築出来ます:

>>> import decimal
>>> decimal.Decimal(1972)
Decimal("1972")
>>> decimal.Decimal("1.1")
Decimal("1.1")

符号(sign)、10進数値のタプルで表した仮数部(mantissa)、指数部(exponent)を含んだタプルを渡すことも出来ます:

>>> decimal.Decimal((1, (1, 4, 7, 5), -2))
Decimal("-14.75")

注意: 符号ビットは負符号の有無なので、 0 が正、1 が負です。

浮動小数点数からの変換は少々問題です: 1.1 を表現する浮動小数点数は 10 進数値の正確な 1.1 に変換すべきでしょうか、それとも 1.1 が持つどんな不正確さもそのまま持ち込むべきでしょうか? 決定は、問題をはぐらかして、その種の変換を API の範疇外とする、というものでした。代わりにあなたは浮動小数点数を望みの精度で文字列に変換して、その文字列を Decimal コンストラクタに渡す必要があります:

>>> f = 1.1
>>> decimal.Decimal(str(f))
Decimal("1.1")
>>> decimal.Decimal('%.12f' % f)
Decimal("1.100000000000")

いったん Decimal を手にしてしまえばあとは普通の数学演算が使えます。制約の一つ: べき乗には整数の指数しか使えません:

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

Decimal インスタンスと整数は混ぜて使えますが、浮動小数点数とは出来ません:

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

Decimal 数を math, cmath モジュールで使うことは出来ますが、演算実行前にその場で浮動小数点数に変換されて、結果精度と正確性を失う可能性があります。戻り値は普通の浮動小数点数であって Decimal ではありません:

>>> import math, cmath
>>> d = decimal.Decimal('123456789012.345')
>>> math.sqrt(d)
351364.18288201344
>>> cmath.sqrt(-d)
351364.18288201344j

Decimal インスタンスは Decimal インスタンスを返す sqrt() メソッドを持っていますが、三角関数のようななにかほかのことが必要な場合は、それらを実装する必要があるでしょう。:

>>> d.sqrt()
Decimal("351364.1828820134592177245001")

Context 型

Context クラスのインスタンスは decimal 演算についてのいくつかの設定をカプセル化しています:

prec は精度で、小数桁数です。

rounding は丸めのモードを指定します。 decimal にはこの値に渡せる定数が定義されています: ROUND_DOWN, ROUND_CEILING, ROUND_HALF_EVEN, それに色々。

traps は特定のエラー状態に出会った場合に何が起こるべきかを指定する辞書です: 例外を発生させるか値を返すかどちらかです。いくつかのエラー状態の例としては、ゼロ除算、精度損失、オーバーフローがあります。

スレッドローカルなデフォルトのコンテキストを、 getcontext() を呼び出すことで利用出来ます; デフォルトの精度、丸めモード、トラップ処理に代えてこのコンテキストのプロパティを変更出来ます。続く例はデフォルトコンテキストの精度を変更する効果についてお見せします:

>>> 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")

エラー状態の場合のデフォルトアクションを選択出来ます; モジュールは無限大(infinity)あるいは非数(not-a-number: NaN)を返すか、例外を投げるかです:

>>> 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")
>>>

Context インスタンスは to_eng_string(), to_sci_string() のような、数値の書式化のための色々なメソッドも持っています。

さらに詳しく知りたければ decimal モジュールのドキュメントを読んで下さい。これには簡単に始められるチュートリアルとリファレンスが入っています。

参考

PEP 327 [https://peps.python.org/pep-0327/] - Decimal データ型

Facundo Batista によって著され、Facundo Batista, Eric Price, Raymond Hettinger, Aahz, Tim Peters らによって実装されました。

http://www.lahey.com/float.htm

この記事は浮動小数点数の不正確さが起こりうるたくさんの問題について、Fortran コードを使って解説しています。

http://speleotrove.com/decimal/

10 進数ベースの表現についての記述です(訳注: decimal-based は小数ベースとも 10 進数ベースとも取れるのですが、後者にしておきました)。この表現方法は標準として提案されていて、この Python の decimal 型の基礎になっています。この題材の多くが Rexx 言語設計者である Mike Cowlishaw によって著されました。

PEP 328: マルチラインインポート

言語の変更の一つは小さな文法的な微調整で、モジュールからたくさんの名前をインポートするのを簡単にするためのものです。 from module import names 文において、 names はカンマ区切りのシーケンスです。シーケンスがとても長くなった場合、同じモジュールからのインポート文を何度も書くか、行末をバックスラッシュでエスケープするかするでしょう、このように:

from SimpleXMLRPCServer import SimpleXMLRPCServer,\
            SimpleXMLRPCRequestHandler,\
            CGIXMLRPCRequestHandler,\
            resolve_dotted_attribute

Python 2.4 での文法的な変更は、単純に names を丸括弧で囲んでも良い、とするだけのものです。Python は丸括弧内の改行を無視しますので、バックスラッシュはもう必要ありません:

from SimpleXMLRPCServer import (SimpleXMLRPCServer,
                                SimpleXMLRPCRequestHandler,
                                CGIXMLRPCRequestHandler,
                                resolve_dotted_attribute)

その PEP は、全ての import 文が絶対インポートであること、相対インポートであることを示すには . 文字で開始すること、の提案もしています。PEP のこの部分は Python 2.4 では実装されていませんが、 Python 2.5 向けには完了しています。

参考

PEP 328 [https://peps.python.org/pep-0328/] - マルチラインインポートと、絶対/相対インポート

Aahz 著. Multi-line imports は Dima Dorfman により実装。

PEP 331: Locale に依存しない Float/String 変換

locale モジュールにより、Python ソフトウェアは特定の国や言語の地域化をする色々な変換や表示の変換を選択出来ます。ところがこのモジュールは、数値ロケールを変更しないように気を配らなければなりませんでした。というのも Python 内の色んな関数実装が、数値ロケールが 'C' ロケールにセットされたままであることを必要としていたからです。しばしばこれは、コードが C ライブラリの atof() 関数を使っていることに原因がありました。

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.

この PEP に記述された解法は、ロケール設定を無視して ASCII のみの変換を実施する 3 つの新しい Python API 関数を追加することです:

PyOS_ascii_strtod(str, ptr) and PyOS_ascii_atof(str, ptr) both convert a string to a C double.

PyOS_ascii_formatd(buffer, buf_len, format, d) converts a double to an ASCII string.

The code for these functions came from the GLib library (https://developer-old.gnome.org/glib/2.26/), whose developers kindly relicensed the relevant functions and donated them to the Python Software Foundation. The locale module can now change the numeric locale, letting extensions such as GTK+ produce the correct results.

参考

PEP 331 [https://peps.python.org/pep-0331/] - Locale に依存しない Float/String 変換

Christian R. Reis 著, 実装 Gustavo Carneiro.

その他の言語変更

以下が、Python 2.4 言語コアに加えられた全ての変更点です。

関数とメソッドのためのデコレータが追加されました。 (PEP 318 [https://peps.python.org/pep-0318/]).

ビルトインの set() 型と frozenset() 型が追加されました (PEP 218 [https://peps.python.org/pep-0218/])。ほか新たなビルトイン関数 reversed(seq) 関数が追加されました (PEP 322 [https://peps.python.org/pep-0322/])。

ジェネレータ式が追加されました (PEP 289 [https://peps.python.org/pep-0289/]).

いくらかの数値式は、もう 32 ビットや 64 ビットに制限されません (PEP 237 [https://peps.python.org/pep-0237/]).

from module import names ステートメントにおいて、 names を括弧で囲むことが出来るようになりました (PEP 328 [https://peps.python.org/pep-0328/]).

dict.update() メソッドが dict コンストラクタと同じ形式の引数を取れるようになりました。これには任意のマッピング、キー/値ペアのイテラブルとキーワード引数を含みます。 (Contributed by Raymond Hettinger.)

文字列の ljust(), rjust(), center() メソッドで空白以外の埋め文字を省略可能引数で指定出来るようになりました。 (Contributed by Raymond Hettinger.)

ほかに、文字列には rsplit() メソッドも追加されています。これは split() メソッドと似た動きをしますが、後ろから順に分割します (Contributed by Sean Reifschneider.)

>>> 'www.python.org'.split('.', 1)
['www', 'python.org']
'www.python.org'.rsplit('.', 1)
['www.python', 'org']

リストの sort() メソッドに 3 つのキーワード引数 cmp, key, reverse が追加されています。これらパラメータは sort() のある種の用法を単純にします。これらは全て省略可能です。

cmp パラメータには比較関数を渡します。これは 2 つのパラメータを取り、パラメータの比較結果に応じて -1, 0, +1 のいずれかを返します。この関数はリストのソートに使われます。これまでの sort() に唯一許されていたのがこの cmp パラメータでした。

key には単一パラメータ関数を渡します。これはリスト要素を受け取り、要素の比較キーを返す関数です。リストはその比較キーを使ってソートされます。続く例はリストを大文字小文字区別なく並び替えます:

>>> 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']

例の最後のものは cmp パラメータを使っています。これが大文字小文字区別のない並び替えの昔ながらの方法です。むろん動きます。が、 key パラメータでのやり方より遅いです。 cmp では lower() メソッド呼び出しが比較ごとなので要素ごとに 2 回呼び出すことになりますが、 key だと呼び出しはそれぞれの要素ごとに lower() 呼び出しを一回だけで済ませられます。

単純なキー関数や比較関数には、しばしば lambda 関数を避けて非束縛メソッドを使えます。例えば上記の大文字小文字によらない並べ替えはこのように書くのが最善です:

>>> L.sort(key=str.lower)
>>> L
['A', 'b', 'c', 'D']

最後の reverse パラメータはブーリアン値を取ります。真ならばリストは逆順にソートされます。 L.sort(); L.reverse() と書く代わりにこれからは L.sort(reverse=True) と書けます。

ソートの結果がステーブル(安定)であることが保障されるようになりました。つまり 2 つの要素が同列である場合、入力と同じ順序が保たれます。例えば人物リストを名前でソートしたのちに年齢でソートすると結果は、年齢でソートされていますが同年齢の人物は名前順です。

(All changes to sort() contributed by Raymond Hettinger.)

新たに追加されたビルトイン関数 sorted(iterable) はインプレイスなメソッド list.sort() と似た振る舞いをしますが、式内で使えます。違いは:

入力には任意のイテラブルを取れます;

新しく構築されたコピーをソートし、オリジナルは無傷のままにします; そして

式として新しいソート済みコピーを返します。

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

(Contributed by Raymond Hettinger.)

整数演算はもはや OverflowWarning は引き起こしません。 OverflowWarning 警告は Python 2.5 で撤廃されます。

インタプリタに新たに -m スイッチが加わりました。これは名前を取り、 sys.path にある対応するモジュールを検索し、そしてそのモジュールをスクリプトとして実行します。たとえば Python プロファイラを python -m profile で起動することが出来るようになりました。 (Contributed by Nick Coghlan.)

eval(expr, globals, locals) 関数と execfile(filename, globals, locals) 関数、 exec 文が locals パラメータに任意のマッピング型を受け取れるようになりました。以前は正規の Python 辞書である必要がありました。 (Contributed by Raymond Hettinger.)

ビルトイン関数の zip() と itertools.izip() が引数なしで呼ばれた場合に空リストを返すようになりました。以前は TypeError 例外でした。これにより可変引数リストをこなしやすくなります:

>>> def transpose(array):
...    return zip(*array)
...
>>> transpose([(1,2,3), (4,5,6)])
[(1, 4), (2, 5), (3, 6)]
>>> transpose([])
[]

(Contributed by Raymond Hettinger.)

Encountering a failure while importing a module no longer leaves a partially initialized module object in 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.)

None が定数になっています。 None という名前に新しい値を割り当てようとするコードは、今では構文エラーになります。 (Contributed by Raymond Hettinger.)

最適化

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 keys(), values(), items(), iterkeys(), itervalues(), and iteritems(). (Contributed by Raymond Hettinger.)

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 realloc(). List comprehensions also benefit. list.extend() was also optimized and no longer converts its argument into a temporary list before extending the base list. (Contributed by Raymond Hettinger.)

list(), tuple(), map(), filter(), and zip() now run several times faster with non-sequence arguments that supply a __len__() method. (Contributed by Raymond Hettinger.)

The methods list.__getitem__(), dict.__getitem__(), and dict.__contains__() are now implemented as method_descriptor objects rather than wrapper_descriptor objects. This form of access doubles their performance and makes them more suitable for use as arguments to functionals: map(mydict.__getitem__, keylist). (Contributed by Raymond Hettinger.)

Added a new opcode, LIST_APPEND, that simplifies the generated bytecode for list comprehensions and speeds them up by about a third. (Contributed by Raymond Hettinger.)

The peephole bytecode optimizer has been improved to produce shorter, faster bytecode; remarkably, the resulting bytecode is more readable. (Enhanced by Raymond Hettinger.)

String concatenations in statements of the form s = s + "abc" and 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 join() method of strings is still recommended when you want to efficiently glue a large number of strings together. (Contributed by Armin Rigo.)

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

新たなモジュール、改良されたモジュール、非推奨のモジュール

いつものように、Python の標準ライブラリには数多くの拡張とバグ修正がありました。ここでは最も注目に値する変更について、モジュールの辞書順に列挙します。変更の完全なリストについてはソースツリーの Misc/NEWS を調べるか、あるいは全ての詳細について CVS ログに目を通してみてください。

The asyncore module's 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.

The base64 module now has more complete RFC 3548 [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.)

bisect モジュールが性能改善のために C 実装を使うようになりました。 (Contributed by Dmitry Vasiliev.)

Hye-Shik Chang によって保守されている東アジアのコーデックの CJKCodecs コレクションが Python 2.4 に統合されました。新たなエンコーディングは:

Chinese (PRC): gb2312, gbk, gb18030, big5hkscs, hz

Chinese (ROC): big5, cp950

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

Korean: cp949, euc-kr, johab, iso-2022-kr

ほか、新たなエンコーディングが追加されています: HP Roman8, ISO_8859-11, ISO_8859-16, PCTP-154, TIS-620.

UTF-8, UTF-16 コーデックが部分的な入力を受け取った場合により上手に処理するようになりました。以前は StreamReader クラスは不足データを読み出そうと試みるために、それがストリームからデコード処理を再開することを不可能にしていました。 read() メソッドは今ではそのとき読めているデータを返し、次の呼び出しで以前の読み残しのデコード処理から再開します。(Implemented by Walter Dörwald.)

There is a new collections module for various specialized collection datatypes. Currently it contains just one type, deque, a double-ended queue that supports efficiently adding and removing elements from either end:

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

Queue や threading のようないくつかのモジュールで、 collections.deque を生かして性能改善を成し遂げています。 (Contributed by Raymond Hettinger.)

The ConfigParser classes have been enhanced slightly. The read() method now returns a list of the files that were successfully parsed, and the set() method raises TypeError if passed a value argument that isn't a string. (Contributed by John Belmonte and David Goodger.)

curses モジュールが ncurses 拡張の use_default_colors() をサポートするようになりました。透明性をサポートするターミナルを持つプラットフォームならば、このことで透明背景に出来ます。 (Contributed by Jörg Lehmann.)

difflib モジュールに HtmlDiff クラスが追加されています。これは対象テキストをサイドバイサイドで視覚化する HTML テーブルを作ります。 (Contributed by Dan Gass.)

email パッケージがバージョン 3.0 に更新されています。多くの非推奨だった API が削除され、Python 2.3 以前のバージョンへのサポートが削除されています。パッケージのバージョン 3.0 は MIME メッセージについての漸増的な新パーサを使います。これは email.FeedParser モジュールで利用可能です。この新パーサはメモリ内に全てのメッセージを読み込んでおく必要がなく、メッセージが不正であっても例外は投げません; 代わりにメッセージの全ての問題についてを defect 属性に記録します。 (Developed by Anthony Baxter, Barry Warsaw, Thomas Wouters, and others.)

heapq モジュールは C に変換されました。性能改善は 10 倍となり、モジュールはより大きなデータを扱うのに相応しいものになりました。加えて、モジュールには新しく 2 つの関数が追加されました。それは nlargest() と nsmallest() で、データセット内の大きいものから N 番目まで、小さいものから N 番目までを、高価な完全なソートを要することなく取り出すのに使います。(Contributed by Raymond Hettinger.)

The httplib module now contains constants for HTTP status codes defined in various HTTP-related RFC documents. Constants have names such as OK, CREATED, CONTINUE, and MOVED_PERMANENTLY; use pydoc to get a full list. (Contributed by Andrew Eland.)

imaplib モジュールが IMAP の THREAD コマンドをサポートするようになりました。 (contributed by Yves Dionne) また、 deleteacl() メソッドと myrights() メソッドが追加されました。 (contributed by Arnaud Mazin).

itertools モジュールに groupby(iterable[, *func*]) 関数が追加されました。 iterable は何か要素のストリームを返すものをイテレート出来るもので、省略可能な func パラメータは要素を取ってキー値を返す関数です。省略されればキーは要素自身です。 groupby() は要素群をキー値の合致ごとサブシーケンスにグループ化して、キー値とサブシーケンスに対するイテレータを組とする 2 要素タプルのシリーズを返します。

例をお見せするのが早いでしょう。ここでは key 関数は単に数値が偶数か奇数かを返すだけです。 groupby() の結果は偶数または奇数の一連の流れを返します:

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

groupby() は典型的にはソート済み入力に使います。 groupby() のロジックは除外、数え上げ、重複要素の特定を手軽に行う Unix の uniq フィルタに似ています:

>>> 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)]

(Contributed by Hye-Shik Chang.)

itertools には tee(iterator, N) という新たな関数も追加されています。これは iterator の、独立した N 個の複製イテレータを返します。 N は省略されればデフォルトは 2 です。:

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

tee() がイテレータから返される値のコピーを維持する必要があることに注意してください。最悪の場合はそれら全てを維持する必要があるかもしれません。ですのでこれは長丁場の入力に対して、先行するイテレータが後続のイテレータの遥か先を突っ走れる場合には注意深く使わなければなりません。その分断が大きいようであれば、 list() を代わりに使うほうが良いかもしれません。イテレータたちが相互に近い場所を追跡する場合は tee() は理想的です。ブックマーク、ウィンドウ処理、あるいは先読みイテレータといったものに適用出来るのではないでしょうか。 (Contributed by Raymond Hettinger.)

A number of functions were added to the locale module, such as bind_textdomain_codeset() to specify a particular encoding and a family of l*gettext() functions that return messages in the chosen encoding. (Contributed by Gustavo Niemeyer.)

logging パッケージの basicConfig() 関数に、ログ設定を簡単にするいくつかのキーワード引数が追加されました。デフォルトの振る舞いはログメッセージを標準エラー出力に出力することですが、様々なキーワード引数でログを特定のファイルに書いたり、ログのフォーマットを変えたり、ロギングのレベルを変えたり出来ます。例えば:

import logging
logging.basicConfig(filename='/var/log/application.log',
    level=0,  # Log all messages
    format='%(levelname):%(process):%(thread):%(message)')

ほかの logging パッケージへの追加としては、 便利メソッド log(level, msg) や、ログファイルを時間間隔でローテートするクラス TimedRotatingFileHandler などがあります。モジュールには元々 RotatingFileHandler が含まれており、こちらはファイルが特定のサイズを超過した場合にローテートするものです。両クラスとも新しく導出された BaseRotatingHandler 基底クラスから派生していて、これはまた別のローテートするハンドラを実装するのに使えます。

(Changes implemented by Vinay Sajip.)

marshal モジュールが、データ構造のアンパックで内部化した文字列を共有するようになりました。これはある種の pickle 文字列のサイズを切り詰めるでしょうが、主要な効能は .pyc ファイルが顕著に小さくなることです。(Contributed by Martin von Löwis.)

The nntplib module's NNTP class gained description() and descriptions() methods to retrieve newsgroup descriptions for a single group or for a range of groups. (Contributed by Jürgen A. Erhard.)

operator モジュールに 2 つの関数 attrgetter(attr) と itemgetter(index) が追加されています。両関数ともに、単一引数を取ってそれに対応する属性かアイテムを返す呼び出し可能オブジェクトを返します。これら呼び出し可能オブジェクトは map() や sorted() とともに使う際の優れたデータ抽出器になります。例えば:

>>> L = [('c', 2), ('d', 1), ('a', 4), ('b', 3)]
>>> map(operator.itemgetter(0), L)
['c', 'd', 'a', 'b']
>>> map(operator.itemgetter(1), L)
[2, 1, 4, 3]
>>> sorted(L, key=operator.itemgetter(1)) # Sort list by second tuple item
[('d', 1), ('c', 2), ('b', 3), ('a', 4)]

(Contributed by Raymond Hettinger.)

optparse モジュールが色々更新されました。モジュールはメッセージを gettext.gettext() を通して Optik のヘルプとエラーメッセージを国際化するのを可能にしています。オプションのヘルプメッセージは文字列 '%default' を含めることが出来るようになっており、これはオプションのデフォルト値に置換されます。(Contributed by Greg Ward.)

The long-term plan is to deprecate the rfc822 module in some future Python release in favor of the email package. To this end, the email.Utils.formatdate function has been changed to make it usable as a replacement for rfc822.formatdate(). You may want to write new e-mail processing code with this in mind. (Change implemented by Anthony Baxter.)

os モジュールに urandom(n) が追加されました。これは n バイトの乱数データを含む文字列を返します。この関数はプラットフォーム固有の乱数発生源にアクセスします。例えば Linux での /dev/urandom や Windows での CryptoAPI です。 (Contributed by Trevor Perrin.)

もう一つの新規関数 os.path.lexists(path) は path によって指定されたファイルがそれがシンボリックリンクかどうかによらず、存在している場合に真を返します。これは、既存の os.path.exists(path) 関数が path がシンボリックリンクでその指し先が存在しない場合に偽を返すのとは異なります。 (Contributed by Beni Cherniavsky.)

os モジュールの下層にある posix モジュールに getsid() 関数が追加されました。 (Contributed by J. Raynor.)

poplib モジュールが POP over SSL をサポートするようになりました. (Contributed by Hector Urtubia.)

profile モジュールが C 拡張の関数をプロファイル出来るようになりました。 (Contributed by Nick Bastin.)

random モジュールに、 getrandbits(N) 関数が追加されました。 N ビット長の長整数を返します。既存の randrange() メソッドは getrandbits() を適切な場所で使うようになり、任意の大きな乱数値生成をより効果的にしています。 (Contributed by Raymond Hettinger.)

re モジュールの正規表現言語が拡張されて、単純な条件式 (?(group)A|B) を書けるようになっています。 group は数値グループ ID か正規表現内で (?P<group>...) で定義したグループ名のどちらかです。指定したグループが合致した場合は、正規表現パターン A が文字列に対してテストされ、そうでなければパターン B が代わりに試されます。(Contributed by Gustavo Niemeyer.)

re モジュールはもう再帰をすることはありません。Gustavo Niemeyer による膨大な量の仕事のおかげです。再帰する正規表現エンジンでは、ある種のパターンでは大量の C スタック空間を消費し、スタックのオーバーフローを起こすことがありました。例えば表現 (a|b)+ が文字 a から成る 3 万バイトの文字列に対してマッチすると、一文字ごとに一つのスタックフレームを消費していました。Python 2.3 ではスタックオーバーフローのチェックを試みて RuntimeError を投げようとしましたが、ある種のパターンではチェックをすり抜けてしまって、運が悪いとセグメンテーション違反を起こしていました。Python 2.4 の正規表現エンジンではこのパターンと問題を起こすことなくマッチ出来ます。

signal モジュールで、 signal.signal() へのパラメータのエラーチェックを厳しくしています。例えば SIGKILL シグナルへのハンドラはセット出来ません。以前のバージョンの Python ではこれを黙って受け容れていましたが、2.4 では RuntimeError を投げます。

socket モジュールに 2 つ新しい関数が追加されています。 socketpair() 関数は接続したソケットのペアを返し、 getservbyport(port) は与えたポート番号からサービス名を探して返します。(Contributed by Dave Cole and Barry Warsaw.)

sys.exitfunc() 関数は非推奨となりました。コードは既存の atexit モジュールを使うべきです。これは複数の終了関数呼び出しを正しく処理出来ます。結果的には sys.exitfunc() は純粋に atexit のみから使われる内部インターフェイスとなるでしょう。

tarfile モジュールがデフォルトで GNU フォーマットを生成するようになっています。 (Contributed by Lars Gustäbel.)

threading モジュールで、スレッドローカルなデータのサポートについて、品の良い単純な方法でサポート出来ました。モジュールは local クラスを持っており、その属性値は異なるスレッドごとにローカルになります:

import threading

data = threading.local()
data.number = 42
data.url = ('www.python.org', 80)

この場合他のスレッドは number 属性、 url 属性に自身の値を代入、抽出出来ます。 local クラスは属性初期化であるとかメソッドの追加のためにサブクラス化することも出来ます。 (Contributed by Jim Fulton.)

timeit モジュールはループを計測中は周期的なガーベージコレクションを自動で無効化するようになりました。この変更により、繰り返しの計測の比較がやりやすくなります。 (Contributed by Raymond Hettinger.)

weakref モジュールがサポートするオブジェクトが非常に幅広くなりました。これには Python 関数、クラスインスタンス, set, frozenset, deque, array と正規表現パターンオブジェクトが含まれます。(Contributed by Raymond Hettinger.)

The xmlrpclib module now supports a multi-call extension for transmitting multiple XML-RPC calls in a single HTTP operation. (Contributed by Brian Quinlan.)

mpz, rotor, xreadlines モジュールは削除されました。

cookielib

The cookielib library supports client-side handling for HTTP cookies, mirroring the 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.

セッションを跨いでクッキーを記憶するために、2 つのクッキー瓶実装が提供されています。一つは Netscape フォーマットでクッキーを記憶するのでアプリケーションは Mozilla か Lynx のクッキーファイルを使え、もう一つは Perl の libwww ライブラリと同じフォーマットでクッキーを記憶します。

urllib2 has been changed to interact with cookielib: HTTPCookieProcessor manages a cookie jar that is used when accessing URLs.

このモジュールは John J. Lee により寄稿されました。

doctest

Edward Loper と Tim Peters のおかげにより、 doctest モジュールに注目に値するリファクタリングが入りました。テストはこれまで通り単純に doctest.testmod() を実行するすることで行えますが、リファクタリングはモジュールの操作をカスタマイズする色々な手段を提供してくれます。

新規クラス DocTestFinder は指定したオブジェクトの docstring からテストを抽出します:

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)

新規クラス DocTestRunner はテストを個々に実行し、結果の要約を生成出来ます:

runner = doctest.DocTestRunner()
for t in tests:
    tried, failed = runner.run(t)

runner.summarize(verbose=1)

上の例はこのような出力を生成します:

1 items passed all tests:
   2 tests in f
2 tests in 1 items.
2 passed and 0 failed.
Test passed.

DocTestRunner は実際の出力と結果の期待値の比較に、 OutputChecker のインスタンスを使います。このクラスはその振る舞いをカスタマイズする色々なフラグを取ります。意欲的なユーザであれば OutputChecker の完全な新しいサブクラスも書けます。

デフォルトの出力チェッカーは多くのお手軽機能を持っています。例えば doctest.ELLIPSIS オプションフラグは、出力の期待値内での省略記号 (...) と任意文字列を一致するとみなし、瑣末な部分が変化するような出力に簡単に適合するように出来ます:

def o (n):
    """>>> o(1)
<__main__.C instance at 0x...>
>>>
"""

もう一つの特殊文字列 <BLANKLINE> は空行に合致します:

def p (n):
    """>>> p(1)
<BLANKLINE>
>>>
"""

もう一つの新機能は出力の diff スタイル出力で、オプションフラグに doctest.REPORT_UDIFF (unified diffs), doctest.REPORT_CDIFF (context diffs), doctest.REPORT_NDIFF (delta-style) を指定することで利用出来ます。例えば以下があるとして:

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

Running the above function's tests with doctest.REPORT_UDIFF specified, you get the following output:

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

ビルドならびに C API の変更

Python のビルド過程と C API の変更は以下の通りです:

拡張関数からの戻り値として一般的に使うための 3 つの便利なマクロが追加されています: Py_RETURN_NONE, Py_RETURN_TRUE, Py_RETURN_FALSE (Contributed by Brett Cannon.)

Another new macro, Py_CLEAR, decreases the reference count of obj and sets obj to the null pointer. (Contributed by Jim Fulton.)

新規関数 PyTuple_Pack(N, obj1, obj2, ..., objN) は Python オブジェクトの可変長引数リストからタプルを構築します。 (Contributed by Raymond Hettinger.)

新規関数 PyDict_Contains(d, k) は、処理内で起こる例外のマスキングなしでの高速なルックアップを実装しています。 (Contributed by Raymond Hettinger.)

The Py_IS_NAN(X) macro returns 1 if its float or double argument X is a NaN. (Contributed by Tim Peters.)

C code can avoid unnecessary locking by using the new 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.)

新規関数 PyArg_VaParseTupleAndKeywords() は PyArg_ParseTupleAndKeywords() と同じですが、たくさんの引数の代わりに va_list を取ることだけが違います。(Contributed by Greg Chapman.)

A new method flag, METH_COEXIST, allows a function defined in slots to co-exist with a PyCFunction having the same name. This can halve the access time for a method such as set.__contains__(). (Contributed by Raymond Hettinger.)

Python can now be built with additional profiling for the interpreter itself, intended as an aid to people developing the Python core. Providing --enable-profiling to the configure script will let you profile the interpreter with gprof, and providing the --with-tsc switch enables profiling using the Pentium's Time-Stamp-Counter register. Note that the --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.)

The tracebackobject type has been renamed to PyTracebackObject.

ポート特有の変更

Windows ポートは MSVC++ 6 と 7.1 でビルド出来ます。 (Contributed by Martin von Löwis.)

Python 2.4 への移植

このセクションでは前述の変更により必要となるかもしれないコードの変更を列挙します:

大き過ぎる値を持つ左シフトと 16 進/ 8 進定数が FutureWarning を引き起こした上で 32 ビットまたは 64 ビットに制限される、という振る舞いはもうしません。代わりに長整数を返します。

整数演算はもはや OverflowWarning は引き起こしません。 OverflowWarning 警告は Python 2.5 で撤廃されます。

ビルトイン関数の zip() と itertools.izip() が引数なしで呼ばれた場合に、 TypeError 例外を起こすのではなく空リストを返すようになりました。

You can no longer compare the date and datetime instances provided by the datetime module. Two instances of different classes will now always be unequal, and relative comparisons (<, >) will raise a TypeError.

dircache.listdir() now passes exceptions to the caller instead of returning empty lists.

LexicalHandler.startDTD() はパブリックでシステムの ID を間違った順序で受け取っていました。これは修正されました; この間違った順序に依存したアプリケーションは修正しなければなりません。

fcntl.ioctl() は mutate_flag 引数が省略されて問題に関係がある場合は警告を出します。

tarfile モジュールがデフォルトで GNU フォーマットを生成するようになっています。

Encountering a failure while importing a module no longer leaves a partially initialized module object in sys.modules.

None が定数になっています。 None という名前に新しい値を割り当てようとするコードは、今では構文エラーになります。

signals.signal() 関数は、ある種の不正な値では RuntimeError を投げるようになっています。以前はこれらエラーは黙って通していました。例えばもう SIGKILL へはハンドラは渡せません。

謝辞

著者は提案の申し出や修正、様々なこの記事の草稿の助けをしてくれた以下の人々に感謝します: Koray Can, Hye-Shik Chang, Michael Dyck, Raymond Hettinger, Brian Hurt, Hamish Lawson, Fredrik Lundh, Sean Reifschneider, Sadruddin Rejeb.

What's New in Python 2.3

著者:

A.M. Kuchling

この文書は Python 2.3 の新機能について解説します。Python 2.3 は 2003 年 7 月 29 日にリリースされました。

Python 2.3 の主要なテーマは、2.2 で追加されたいくつかの機能を磨くこと、言語中核に小さいながらも有用な種々の拡張をすること、そして標準ライブラリの拡充です。ひとつ前のバージョンで導入された新しいオブジェクトモデルは、18 ヶ月に渡るバグフィックスと新スタイルクラスの性能改善をもたらした最適化の努力の恩恵を受けました。 sum(), enumerate() のような、新たなビルトイン関数が少し追加されました。 in 演算子がサブストリングの検索に使えるようになりました (例えば "ab" in "abc" は True を返します)。

たくさんのライブラリ新機能…、Boolean、 set、 heap、 日付/時刻データ型、ZIP 形式アーカイブからのモジュールインポート、待ち望まれていた Python カタログのためのメタデータサポート、更新されたバージョンの IDLE、ロギングメッセージのためのモジュール、テキストの折り返し、CSV ファイルの解析、コマンドラインオプションの処理、BerkeleyDB データベースの使用…、新機能、強化機能のリストは長大になります。

このドキュメントは個々の新機能の完全な詳細を提供するのではなくて、簡易な概要を提供することを目的にしています。完全な詳細が知りたければ、 Python ライブラリリファレンス、Python リファレンスマニュアルのような Python 2.4 のドキュメントを参照してください。設計と実装の根拠を理解したい場合は、新機能に関する PEP を参照してください。

PEP 218: 標準の集合データ型

(---訳注: イキナリですが、あなたが今これを「Python の歴史を知る」もしくは「初登場時の熱量高い紹介」を読みたくて読んでいるのでない限りは、もしくは本当に今 2.3 を使う必要があれば別ですが、このモジュールは 2.4 で既にビルトインで置き換えられ、2.6 では非推奨となり、3.0 では削除されています。ので、集合型について知りたければここよりも 2.4 のビルトインの方から読んだ方が良いです。---) --- 新しいモジュール sets には、集合データ型の実装が含まれています。 Set クラスは mutable の集合のためのクラスで、メンバの追加と削除が出来ます。 ImmutableSet は変更できない集合のためのクラスなので、ImmutableSet のインスタンスを辞書のキーとして利用出来ます。集合型は辞書の上に構築されているので、集合内の要素はハッシュ可能でなければなりません。

単純な使用例です:

>>> 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])
>>>

和集合 (union) と共通集合 (intersection) は union() と intersection() メソッドで計算出来ます; 別の記法として、ビット演算子 & と | も使えます。変更可能な集合ではこれらのインプレイス版 union_update() と intersection_update() も使えます:

>>> S1 = sets.Set([1,2,3])
>>> S2 = sets.Set([4,5,6])
>>> S1.union(S2)
Set([1, 2, 3, 4, 5, 6])
>>> S1 | S2                  # Alternative notation
Set([1, 2, 3, 4, 5, 6])
>>> S1.intersection(S2)
Set([])
>>> S1 & S2                  # Alternative notation
Set([])
>>> S1.union_update(S2)
>>> S1
Set([1, 2, 3, 4, 5, 6])
>>>

2 つの集合の対称差 (symmetric difference) を取ることも出来ます。これは、union から intersection を除いた全要素を取ります。別の言い方をすれば、対称差とは、正確に一つの集合だけに含まれる全要素、ということです。ほかと同じくビット演算子の記法 (^) が使え、インプレイスバージョンは見苦しい名前の symmetric_difference_update() です:

>>> 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])
>>>

issubset() と issuperset() メソッドも使えます。これはある集合が部分集合、上位集合であるかとうかをチェックします:

>>> S1 = sets.Set([1,2,3])
>>> S2 = sets.Set([2,3])
>>> S2.issubset(S1)
True
>>> S1.issubset(S2)
False
>>> S1.issuperset(S2)
True
>>>

参考

PEP 218 [https://peps.python.org/pep-0218/] - 集合オブジェクト型をビルトインに追加する

PEP 著 Greg V. Wilson. 実装: Greg V. Wilson, Alex Martelli, GvR. (---訳注: PEPそのものは 2.4 のビルトイン型 set, frozenset の追加と同じものですが、2.3 ではモジュールとして追加され、2.4 でビルトイン版が追加され、2.6 でモジュール版が非推奨となった、という流れです。---)

PEP 255: 単純なジェネレータ

Python 2.2 では、ジェネレータが from __future__ import generators ディレクティブで有効に出来るオプションの機能として追加されました。2.3 ではジェネレータは特別に有効化する必要なく、もうキーワード yield として、いつでもそこにあります。このセクションの残りの部分は "What's New in Python 2.2" のジェネレータの記述からの丸々コピーですので、2.2 のときに読んだなら読み飛ばしてもらって結構です。

Python や C の標準的な関数コールについては、よくご存じに違いありません。関数を呼ぶと、ローカル変数を作るプライベートな名前空間ができますね。その関数が return 文まで来ると、ローカル変数が破壊されてから、返り値が呼び出し元に返ります。次に同じ関数をもう一度呼ぶと、新しいプライベート名前空間に新規のローカル変数が作られるのです。しかし、関数を出るときにローカル変数を捨てなければどうなるでしょうか。その出ていったところから関数を続行できたとしたら、どうでしょう。これこそジェネレータが提供する機能です; すなわち、ジェネレータは続行できる関数と考えることができます。

ジェネレータ関数の最も単純な例です:

def generate_ints(N):
    for i in range(N):
        yield i

新しいキーワード yield がジェネレータのために導入されました。 yield ステートメントを含むどんな関数もジェネレータ関数です; Python バイトコードコンパイラはこれを検知し、関数が特別に扱われるように翻訳します。 (---訳注: Python 2.5 の PEP 342 も参照して下さい。この 2.2 で導入時点の yield はステートメントではなく式に変更されています。---)

ジェネレータ関数を呼び出すと、単一の値の代わりにイテレータプロトコルに対応したオブジェクトを返します。上の例で yield を実行したとき、ジェネレータは return 文のようにして i の値を生成します。 yield と return 文の大きな違いは、 yield に到達した段階でジェネレータの実行状態が一時停止になって、ローカル変数が保存される点です。次回そのジェネレータの .next() メソッドを呼ぶと、 yield の直後から関数が実行を再開します。(複雑な理由により、 yield は try...finally の try ブロック内に含めることは許されていません; PEP 255 [https://peps.python.org/pep-0255/] に yield と例外の相互作用についての詳細説明がありますので参照して下さい。) --- (---訳注: Python 2.5 の PEP 342 で try...finally 内に置けないという制約はなくなりました。また、 try...finally の try 、とここであえて特定しているのは、同じく 2.5 の PEP 341 によって try/except/finally の一体化されるまでは、 finally の try と except の try が別物だったからです。---)

上記の generate_ints() ジェネレータはこんな具合に使います:

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

同じく for i in generate_ints(5) や a,b,c = generate_ints(3) といった書き方もできます。

ジェネレータ関数内で return 文は、引数を付けずに、処理の終わりを知らせるためにだけ使うことができます; return を実行したあとは、もうそのジェネレータが値を返すことはできません。ジェネレータ関数の中では、 return 5 などと値を付けた return は構文エラーです。ジェネレータの出力が終わったことを示すには、ほかにも、手動で StopIteration を投げてもいいですし、関数の最後まで実行するだけでも同じことになります。(---訳注: Python 2.7 まではジェネレータ内での戻り値のある return 5 は構文エラーになりますが、少なくとも Python 3.4 で構文エラーとはなりません。単に無視されます。リファレンスに言及されていない振舞いなので、何かの事故かもしれません。いずれにせよジェネレータ内では Python 3 でも return で値は戻せません。---)

自分でクラスを書いて、ジェネレータで言うところのローカル変数をインスタンス変数として全部保管しておけば、同じ効果を得ることは可能です。たとえば整数のリストを返すのは、 self.count を 0 にして、 next() メソッドが self.count をインクリメントして返すようにすればできます。しかしながら、ある程度複雑なジェネレータになってくると、同じことをするクラスを書くのは格段にややこしいことになります。 Lib/test/test_generators.py にはもっと面白い例がたくさん含まれています。一番単純な一つは、ジェネレータを再帰的に使ってツリーを順繰りに横断する実装をするこれです (---訳注: ジェネレータは現在の最新 3.5 までの間に 2 度大きな機能強化が行われているのですが、一つが 2.5 での PEP 342 でこれは yield 「に」値を戻せるようにするものです。もう一つが 3.3 での PEP 380 で、これはサブジェネレータへの委譲 yield from <subgen> の追加でした。ですのでこの 3.3 からの yield from を使うと下記例はもっとスッキリ書けます。---):

# 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

ほかにも Lib/test/test_generators.py には、N-Queens 問題 (N×N コマのチェス盤に、互いに攻撃できないような配置で N 個のクイーンを置く) やナイト・ツアー (N×N 盤の全コマをナイトが一度ずつ通るような経路を探す) の解を出す例が入っています。

ジェネレータの発想はほかのプログラミング言語、特に Icon (https://www2.cs.arizona.edu/icon/) から着想しています。Icon ではジェネレータが言語の中枢になっています。Icon では、あらゆる式と関数がジェネレータのように振舞います。 https://www2.cs.arizona.edu/icon/docs/ipd266.htm の "Icon プログラミング言語の概要" の一つの例が、これがどのようなものであるのかを教えてくれます:

sentence := "Store it in the neighboring harbor"
if (i := find("or", sentence)) > 5 then write(i)

Icon では find() 関数は部分文字列 "or" が見つかる位置 3, 23, 33 を返します。 if 文内では i には最初 3 が代入されますが、これは 3 より小さいので比較は失敗し、Icon は次の値 23 を取り出します。 23 は 5 より大きいので比較は成功し、コードは 23 をスクリーンに表示します。

Python では Icon がそうするほどにはジェネレータを中心的概念に置きません。ジェネレータは Python 言語中核の新たな一面ではありますが、それらを学ぶのも使うのも誰しも行うべきだというものでもなく、そしてこれで解決できない何か問題があれば、忘れてしまっても良いものです。Icon と比較した特筆すべき Python インターフェイスの機能はジェネレータの状態が具象オブジェクト (イテレータ) で表現されることであり、それは他の関数に渡せますし、データ構造に記憶しておくことも出来ます。(---訳注: ジェネレータについてかなり控えめなのは、この時点で著者は将来の拡張を既に見据えていたから? かもしれませんね。PEP 342 と PEP 380 により今やジェネレータはこの頃より遥かに高機能になっており、今ではきっと「こんなものなくても困らない」なんて Python 使いはいないでしょう。---)

参考

PEP 255 [https://peps.python.org/pep-0255/] - 単純なジェネレータ

Neil Schemenauer, Tim Peters, Magnus Lie Hetland により著されました。実装のほとんどは Neil Schemenauer と Tim Peters により行われ、 Python Labs クルーにより他の修正が行われました。

PEP 263: ソースコードのエンコーディング

Python ソースファイルで、異なる文字セットエンコーディングを宣言出来るようになりました。エンコーディングはソースコードの 1 行目か 2 行目に特殊形式のコメントを含めることで宣言出来ます。 UTF-8 ファイルであればこのように宣言出来ます:

#!/usr/bin/env python
# -*- coding: UTF-8 -*-

このエンコーディング宣言がなければ、デフォルトの 7 ビット ASCII エンコーディングが使われます(訳注: Python 3 からはデフォルトは utf-8 (PEP 3120))。8 ビット文字を含んでいるのにエンコーディング宣言がないモジュールの実行やインポートを行うと、 Python 2.3 では DeprecationWarning を引き起こします; 2.4 ではこれは構文エラーになる予定です(訳注: 実際には 2.4 ではこれは実現せず、2.5 から)。

エンコーディング宣言は Unicode 文字列リテラルにのみ影響します。それらは指定したエンコーディングで Unicode 文字列に変換されます。Python 識別子は今でも ASCII 文字列に制限されていることに注意してください。ですから普通の英数字範囲外の文字を変数名に使うことは出来ません。

参考

PEP 263 [https://peps.python.org/pep-0263/] - Python ソースコードのエンコーディングを定義する

Marc-André Lemburg、 Martin von Löwis 著; Suzuki Hisao、 Martin von Löwis 実装.

PEP 273: Zip アーカイブからモジュールをインポートする

新たなモジュール zipimport が、ZIP フォーマットの書庫からモジュールのインポートをサポートします。 zipimport を明示的にインポートする必要はありません; sys.path に ZIP 形式書庫が追加されるとそれは自動的にインポートされます。例えば:

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

sys.path には今や ZIP 書庫のファイル名も入れることが出来ます。ZIP アーカイブ内にはどんなファイルを置いてもかまいませんが、import できるのは *.py, *.pyc, *.pyo だけです。書庫に *.py だけが含まれる場合には、Python は書庫を修正して対応する *.pyc を作るなどということはしないので、 *.pyc ファイルを含まない ZIP 書庫からのインポートはやや遅いかもしれません。

書庫内のパスをサブディレクトリ以下のみインポートするように指定出来ます; 例えば、パス /tmp/example.zip/lib/ はその書庫内の lib/ サブディレクトリだけからインポートします。

参考

PEP 273 [https://peps.python.org/pep-0273/] - Zip アーカイブからモジュールをインポートする

このモジュールの実装も行った、James C. Ahlstrom による PEP です。 Python 2.3 は PEP 273 [https://peps.python.org/pep-0273/] の仕様に従っていますが、 Just van Rossum の書いた、 PEP 302 [https://peps.python.org/pep-0302/] に記述されているインポートフックによる実装を使っています。その新しいインポートフックについては PEP 302: 新たなインポートフック をみてください。

PEP 277: Windows NT での Unicode ファイル名サポート

Windows NT, 2000, XP では、ファイルシステムはファイル名として Unicode 文字列を使います。伝統的に Python はファイル名をバイト文字列として表現してきましたが、それはアクセス出来ないファイル名を表してしまう場合があって、不十分でした。

Python はいまや (ファイルシステムの制約の範囲内での) 任意の Unicode 文字列を open() 組み込み関数をはじめとするファイル名が期待される全ての関数で許容します。 os.listdir() に Unicode 文字列が渡されれば、Python は今では Unicode 文字列のリストを返します。新しい関数 os.getcwdu() は Unicode 文字列でカレントディレクトリを返します(訳注: ちなみに Python 3 での Unicode 周りの大改造に伴いこの関数はなくなり、代わりに「あえてバイト列のほうを返す」 が追加されています(os.getcwdu() がもはや Unicode を返すので)。)。

ファイル名のバイト文字列はいまでも動きます。Windows 版 Python は透過的にそれらを Unicode に mbcs エンコーディングを使って変換します。

ほかのシステムでもファイル名の Unicode は許容されますが、システムに渡す前にバイト文字列に変換され、 UnicodeError 例外を引き起こすかもしれません。アプリケーションは任意の Unicode 文字列がファイル名に許されるかどうかを、ブーリアン値 os.path.supports_unicode_filenames をチェックすることでテスト出来ます。

MacOS では、 os.listdir() は Unicode ファイル名を返すようになっているでしょう。

参考

PEP 277 [https://peps.python.org/pep-0277/] - Windows NT での Unicode ファイル名サポート

Neil Hodgson 著; 実装 Neil Hodgson, Martin von Löwis, Mark Hammond。

PEP 278: Universal Newline サポート

今日では 3 つの主要なオペレーティングシステムが使われています。 Microsoft Windows, Apple の Macintosh OS, さまざまな Unix 派生系です。テキストファイルの行終端マークに使う文字がこれら 3 つ全てでそれぞれ違っていることが、クロスプラットフォームのための仕事における小さな苛立ちです。 Unix が使うのはラインフィード (ASCII 文字 10), MacOS が使うのはキャリッジリターン (ASCII 文字 13), Windows に至ってはキャリッジリターンとラインフィード 2 文字のシーケンスを使います。

Python のファイルオブジェクトが、動作しているプラットフォームに従わない行終端変換をサポートするようになりました。ファイルのオープンにモード 'U' や 'rU' を使うと、 universal newlines モードを使った読み込みとしてファイルを開きます。これで read(), readline() などのファイルメソッドが、 3 つどの行終端でも '\n' という文字列に翻訳して返すようになります。

universal newline サポートはモジュールのインポートと execfile() 関数でのファイル実行にも使われます。これで 3 つ全てのオペレーティングシステム間で行終端変換の必要なく Python モジュールを共有出来ます。

この機能は Python をソースからビルドする際に configure スクリプトに --without-universal-newlines スイッチ を付けることで無効に出来ます。

参考

PEP 278 [https://peps.python.org/pep-0278/] : Universal Newline サポート

Jack Jansen 著、実装

PEP 279: enumerate()

新たな組み込み関数 enumerate() はある種のループ処理を少し簡潔にするものです。 thing がイテレータかシーケンスだとして、 enumerate(thing) は (0, thing[0]), (1, thing[1]), (2, thing[2]), … を生成するイテレータを返します。

リストの全てを変更するためのよくあるイディオムはこのようなものでしょう:

for i in range(len(L)):
    item = L[i]
    # ... compute some result based on item ...
    L[i] = result

これは enumerate() を使ってこのように書き換えることが出来ます:

for i, item in enumerate(L):
    # ... compute some result based on item ...
    L[i] = result

参考

PEP 279 [https://peps.python.org/pep-0279/] - 組み込み関数 enumerate()

Raymond D. Hettinger 著、実装.

PEP 282: ロギングパッケージ

ログ記録のための標準パッケージ logging が Python 2.3 に追加されています。それはログ出力生成の強力で柔軟なメカニズムを提供し、フィルタと加工を色々な方法で行えます。標準フォーマットで書く設定ファイルで、プログラムのロギングの振る舞いを制御出来ます。ログレコードを標準エラー出力やファイルやソケット、システムログへの送信、あるいは e-mail 送信するようなハンドラが Python に含まれています。もちろん、あなた自身のハンドラクラスを書くことも出来ます。

Logger が最も重要なクラスです。ほとんどのアプリケーションコードは一つかそれ以上の Logger オブジェクトを扱い、それぞれ一つはそのアプリケーションの特定のサブシステムで使われるでしょう。それぞれの Logger は名前で識別され、名前は . をコンポーネントのセパレータとして使う階層で体系化されます。例えば、 server, server.auth, server.network といった名前の Logger インスタンスを持つといった具合です。この例の後ろ 2 つは階層で server の下にあります。 server への冗長性を見つけた場合や server メッセージを直接異なるハンドラに向けた場合、変更は server.auth と server.network へのログ記録にも適用されるということです。全てのほかのロガーの親となる、ルート Logger もあります。

単純な用法のために、 logging パッケージはいくつかの便利関数を含んでいて、これは常にルートログを使います:

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')

これは以下のような出力をします:

WARNING:root:Warning:config file server.conf not found
ERROR:root:Error occurred
CRITICAL:root:Critical error -- shutting down

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 setLevel() method on the root logger.

Notice the warning() call's use of string formatting operators; all of the functions for logging messages take the arguments (msg, arg1, arg2, ...) and log the string resulting from msg % (arg1, arg2, ...).

There's also an 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.

def f():
    try:    1/0
    except: logging.exception('Problem recorded')

f()

これは以下のような出力をします:

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

多少なりとも高度なプログラムでは、ルートロガー以上のロガーを使うでしょう。 getLogger(name) 関数は特定のロガーを取得するのに使います。その時点で存在していなければ、作成されます。 getLogger(None) はルートロガーを返します。:

log = logging.getLogger('server')
 ...
log.info('Listening on port %i', port)
 ...
log.critical('Disk full')
 ...

Log records are usually propagated up the hierarchy, so a message logged to server.auth is also seen by server and root, but a Logger can prevent this by setting its propagate attribute to False.

There are more classes provided by the logging package that can be customized. When a Logger instance is told to log a message, it creates a LogRecord instance that is sent to any number of different Handler instances. Loggers and handlers can also have an attached list of filters, and each filter can cause the LogRecord to be ignored or can modify the record before passing it along. When they're finally output, LogRecord instances are converted to text by a Formatter class. All of these classes can be replaced by your own specially written classes.

これら全ての機能で logging パッケージは最も複雑なアプリケーションでさえ、十分な柔軟性を提供しているはずです。ここではそれら機能の不完全な概要しか示しませんでしたので、全ての詳細はパッケージのドキュメントを参照してください。 PEP 282 [https://peps.python.org/pep-0282/] を読むことも助けになるでしょう。(---訳注: 今ではクックブックもあるのでそちらもどうぞ。---)

参考

PEP 282 [https://peps.python.org/pep-0282/] - ログシステム

PEP 著: Vinay Sajip と Trent Mick; 実装: Vinay Sajip.

PEP 285: Boolean 型

A Boolean type was added to Python 2.3. Two new constants were added to the __builtin__ module, True and False. (True and 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.)

この新しい型の型オブジェクトの名前は bool です; これのコンストラクタは任意の Python 値を取り、 True または False に変換します:

>>> bool(1)
True
>>> bool(0)
False
>>> bool([])
False
>>> bool( (1,) )
True

標準ライブラリモジュールとビルトイン関数のほとんどが、そうすべきときには Boolean を返すように変更されました:

>>> obj = []
>>> hasattr(obj, 'append')
True
>>> isinstance(obj, list)
True
>>> isinstance(obj, tuple)
False

Python の Boolean はコードを明快にすることを主たる目標として追加されました。例えばあなたがコードを読んでいて return 1 に出くわした場合、あなたは考えるはずです。この 1 は、真偽としての真値なのであろうか、それともインデクスだろうか、はたまた何かほかの数量に掛ける係数だろうか、と。 return True であればその意味するところはかなり明らかです。

Python の Boolean は、厳格な型チェックを目的として追加された のではありません 。Pascal のようなとても厳格な言語では、Boolean の数学演算も阻むでしょうし、 if ステートメントの式が必ず Boolean の結果に評価されなければならないことを要求するでしょう。 Python はこの厳しさを今持ちませんし、 PEP 285 [https://peps.python.org/pep-0285/] が名言するように、未来永劫持つことはありません。このことは、 if ステートメントにこれからも任意の式を書けることを意味しますし、リストやらタプルやら何かほかのデタラメなオブジェクトに評価されるものでも良いことを意味します。Boolean 型は int クラスのサブクラスであって、Boolean の算術演算はこれからも動作します:

>>> True + 1
2
>>> False + 1
1
>>> False * 75
0
>>> True * 75
75

True と False はぶっちゃけて言えば…: これらは整数値 1 と 0 の別名だけれども唯一異なるのは str() と repr() が '1' と '0' ではなく 'True' と 'False' を返すことだけである。

参考

PEP 285 [https://peps.python.org/pep-0285/] - 真偽値型の追加

Guido van Rossum 著、実装

PEP 293: コーデックエラーを処理するコールバック

Unicode 文字列をバイト文字列にエンコードする際には、エンコード出来ない文字に出会うことがあります。いまのところ Python は、そのエラー処理として "strict" (UnicodeError を発生させる)、 "ignore" (その文字をスキップする)、 "replace" (出力文字列ではクエッションマークに置換する)、のいずれか一つを指定出来て、 "strict" がデフォルトの振る舞いになっています。その種のエラーのために、ほかの代わりとなる処理が望ましいかもしれません。例えば XML や HTML の実体参照に置き換えるなどの。

Python は今や、異なる処理戦略を追加する柔軟なフレームワークを手にしました。新しいエラーハンドラを codecs.register_error() で追加出来、コーデックは codecs.lookup_error() を使ってそのエラーハンドラにアクセス出来ます。等価な C API も C で書かれたコーデックのために追加されています。エラーハンドラは、変換すべき文字列、そのエラーが検出されたその文字列内での位置、ターゲットエンコーディングのような必要な状態情報を受け取ります。ハンドラは例外を投げるか、置換文字列を返せます。

このフレームワークを使って 2 つのエラーハンドラが実装されました: "backslashreplace" はエンコード出来ない文字をバックスラッシュで引用し、 "xmlcharrefreplace" は XML 文字参照を発行します。

参考

PEP 293 [https://peps.python.org/pep-0293/] - コーデックエラーを処理するコールバック

Walter Dörwald 著、実装

PEP 301: パッケージインデクスと、 Distutils のためのメタデータ

長い間要望されてきた Python カタログのサポートが 2.3 で初登場です。

カタログの心臓部は Distutils の新コマンド register です。 python setup.py register を実行すると、名前、バージョン、メンテナ、説明、ライセンスのようなパッケージ記述のメタデータを収集して、中央カタログサーバに送信します。結果のカタログは https://pypi.org で利用可能です。

To make the catalog a bit more useful, a new optional classifiers keyword argument has been added to the Distutils setup() function. A list of Trove [http://catb.org/~esr/trove/]-style strings can be supplied to help classify the software.

以下は setup.py に分類指定子 (classifier) を記述する例です。 Distutils の古いバージョンと互換になるように書いています。:

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)

classifier の完全なリストは python setup.py register --list-classifiers と実行することで得ることが出来ます。

参考

PEP 301 [https://peps.python.org/pep-0301/] - パッケージインデクスと、 Distutils のためのメタデータ

Richard Jones 著、実装

PEP 302: 新たなインポートフック

カスタムなインポートフックを書くことは、Python 1.3 で ihooks モジュールが導入されたその日からずっと可能でした。それでも本当のところそれで幸せになった人は誰一人いません。それで新しいインポートフックを書くのが難しくてとっ散らかっていたからです。 imputil と iu モジュール のような代わりとなる色々な提案がありましたが、そのいずれも多くの賛同を得ることが出来たものはありませんし、そのいずれもが簡単に C コードから使うことが出来ませんでした。

PEP 302 [https://peps.python.org/pep-0302/] はその先駆者、特に Gordon McMillan の iu モジュールからアイディアを借りています。3 つの新たなアイテムが sys モジュールに追加されています:

sys.path_hooks は呼び出し可能オブジェクトのリストです。ほとんどの場合クラスになるでしょう。それぞれの呼び出し可能オブジェクトは、パスを含む文字列を受け取って、このパスからインポートを処理するインポーターオブジェクトを返すか、このパスを処理出来なければ ImportError を送出します。

sys.path_importer_cache はそれぞれのパスごとのインポーターオブジェクトをキャッシュしますので、 sys.path_hooks は個々のパスを一回だけ横断すれば良いことになります。

sys.meta_path は sys.path がチェックされる前に横断させるインポーターオブジェクトのリストです(訳注: ここだけ読むとわかりにくいですがライブラリリファレンスを読めばわかります)。このリストは初期状態で空ですが、ユーザコードがオブジェクトをそれに追加出来ます。追加のビルトインと凍結モジュールを、このリストにオブジェクトを追加することによってインポートさせることが出来ます。

インポーターオブジェクトは一つのメソッド find_module(fullname, path=None) を持たなければなりません。 fullname はモジュールかパッケージの名前です。例えば string や distutils.core です。 find_module() メソッドは一つのメソッド load_module(fullname) を持つローダーオブジェクトを返さなければなりません。 load_module(fullname) では対応するモジュールオブジェクトを生成して返します。

Python の新しいインポートのロジックは、なので、擬似コードで示すとだいたいこんな感じです (少し単純化しています; 完全な詳細は PEP 302 [https://peps.python.org/pep-0302/] 参照):

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

参考

PEP 302 [https://peps.python.org/pep-0302/] - 新たなインポートフック

Just van Rossum、Paul Moore 著、実装 Just van Rossum。

PEP 305: カンマ区切り形式ファイル

カンマ区切りファイルは、データベースやスプレッドシートからのエキスポートのために頻繁に使われるフォーマットです。Python 2.3 はカンマ区切りファイルのパーサを追加しました。

カンマ区切りフォーマットは、ぱっと見で、簡単そうに見えます:

Costs,150,200,3.95

行を読んで line.split(','): これほどに簡単なものはあるだろうか、って? ですが、文字列データ内にカンマを含んだりすると、コトは複雑になります:

"Costs",150,200,3.95,"Includes taxes, shipping, and sundry items"

デカくて醜い正規表現でこれをパース出来るでしょうが、新登場の csv を使えば遥かに単純になります:

import csv

input = open('datafile', 'rb')
reader = csv.reader(input)
for line in reader:
    print line

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

カンマ区切りファイルの異なった方言を定義して登録出来ます。今のところ 2 つの方言があって、両者とも Microsoft Excel で使われるものです。独立している csv.writer はタプルやリストの連続から、デリミタを含む文字列は引用符で囲みつつカンマ区切りファイルを生成します。

参考

PEP 305 [https://peps.python.org/pep-0305/] - CSV File API

PEP 著と実装: Kevin Altis, Dave Cole, Andrew McNamara, Skip Montanaro, Cliff Wells.

PEP 307: Pickle の機能拡張

The pickle and 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; PEP 307 [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.

解決方法として、新しい pickle プロトコルが発明されました。 pickle.dumps() 関数はずっと長い間、テキストとするのかバイナリとするのかについてはサポートしていました。2.3 ではこのフラグは Boolean から整数に再定義されました: 0 は旧式のテキストモード pickle フォーマット、1 が同じく旧式のバイナリフォーマット、そして 2 が今回の 2.3 から特有のフォーマットです。新しく追加された定数 pickle.HIGHEST_PROTOCOL を指定すると、最も望ましいものが選択されます。

Unpickling is no longer considered a safe operation. 2.2's pickle provided hooks for trying to prevent unsafe classes from being unpickled (specifically, a __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: __getstate__(), __setstate__(), and __getnewargs__(). Consult PEP 307 [https://peps.python.org/pep-0307/] for the full semantics of these methods.

pickle をもっとさらに圧縮する方法として、pickle されるクラスの身元特定のために長い文字列を使う代わりに整数コードを使えるようになっています。Python Software Foundation は標準コードのリストを保守しています; プライベート使用のためのコード範囲もあります。現在のところ指定されているコードはありません。

参考

PEP 307 [https://peps.python.org/pep-0307/] - pickle プロトコルの拡張

著、実装: Guido van Rossum と Tim Peters

拡張スライス

Python 1.4 以来ずっと、スライシングの構文は省略可能な 3 つ目の引数 "step" またの名を "stride" 、をサポートしていたのです。例えばこれらは全て合法な Python 構文です: L[1:10:2], L[:-1:1], L[::-1] 。これはこの 3 つ目の引数を大々的に使う Numerical Python 開発者によって要望されたことで Python に追加されたものですが、Python ビルトインのリスト、タプル、文字列といったシーケンス型がこの機能をサポートすることはなく、これを試みると TypeError を起こしていました。Michael Hudson がこの不徹底を修正するパッチを寄稿しました。

例えば、今やリストの偶数番目要素を簡単に取り出せます:

>>> L = range(10)
>>> L[::2]
[0, 2, 4, 6, 8]

負の値では、同じリストの逆順コピーを作るように動作します:

>>> L[::-1]
[9, 8, 7, 6, 5, 4, 3, 2, 1, 0]

これはタプル、配列、文字列に対しても使えます:

>>> s='abcd'
>>> s[::2]
'ac'
>>> s[::-1]
'dcba'

リストや配列のような mutable なシーケンスに対して、拡張スライスを代入や削除に使えますが、拡張スライスと普通のスライスではいくつかの違いがあります。普通のスライスで代入を行えば、シーケンスの長さを変更出来ます (---訳注: 念のため。Python 3 の range は list を直接返す関数ではなくジェネレータなので、以下例は a = list(range(3)) などとしないと動作しません。続く例でも同じです。---):

>>> a = range(3)
>>> a
[0, 1, 2]
>>> a[1:3] = [4, 5, 6]
>>> a
[0, 4, 5, 6]

拡張スライスにはこの柔軟性はありません。拡張スライスを代入に使う際は、ステートメントの右辺のリストは、置換されるスライスとしての要素数と同数でなければなりません:

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

削除はもっと素直です:

>>> a = range(4)
>>> a
[0, 1, 2, 3]
>>> a[::2]
[0, 2]
>>> del a[::2]
>>> a
[1, 3]

One can also now pass slice objects to the __getitem__() methods of the built-in sequences:

>>> range(10).__getitem__(slice(0, 5, 2))
[0, 2, 4]

あるいは直接 slice オブジェクトを添え字に使えます:

>>> range(10)[slice(0, 5, 2)]
[0, 2, 4]

To simplify implementing sequences that support extended slicing, slice objects now have a method indices(length) which, given the length of a sequence, returns a (start, stop, step) tuple that can be passed directly to range(). 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:

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)

ところでこの例からは、ビルトインの slice オブジェクトが今では slice 型という型オブジェクトで、もう関数ではないことがわかるでしょう。これは、Python 2.2 で int, str などに対して行われた同じ目的の修正と一貫しています。

その他の言語変更

以下が、Python 2.3 言語コアに加えられた全ての変更点です。

yield 文がこのドキュメントの PEP 255: 単純なジェネレータ で述べた通り、キーワードになっています。

新たな組み込み関数 enumerate() が追加されました。このドキュメントの PEP 279: enumerate() で述べた通りです。

新たな定数 True, False がビルトイン bool 型の追加に伴い追加されました。このドキュメントの PEP 285: Boolean 型 で述べた通りです。

int() 型コンストラクタは、文字列や浮動小数点数を整数に収める際、それがとても大き場合に OverflowError を投げるのではなく長整数を返すようになっています。これは isinstance(int(expression), int) が偽を返すかもしれないという逆説的な結果をもたらし得ますが、これが実際に問題を起こすとはあまり思えません。

ビルトイン型が拡張スライス構文をサポートするようになりました。このドキュメントの 拡張スライス で述べた通りです。

新規組み込み関数 sum(iterable, start=0) はイテラブル オブジェクト内の数値アイテムを足し込んで総和を返します。 sum() は数値しか受け付けませんので、文字列群を連結するのには使えません。 (Contributed by Alex Martelli.)

list.insert(pos, value) で value を先頭に追加するのに pos に負数が使われてきました。この振る舞いはスライスのインデクシングとの一貫性のために変更されました。つまり pos が -1 の場合は最終要素の前への追加、などとなります。

list.index(value) はリスト内から value を探してそのインデクスを返しますが、オプショナルな start と stop 引数を取って、リストの部分列からの検索が可能になりました。

辞書の新たなメソッド pop(key[, *default*]) は、 key に対応する値を返して辞書からそのキー/値ペアを取り除きます。辞書内にそのキーが不在であれば、 default が指定されていればそれを、そうでなければ KeyError を投げます。:

>>> 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
{}
>>>

また、新しいメソッド dict.fromkeys(iterable, value) は、与えられたイテレータ iterable からキーを取り出しつつ全ての値を value にセットすることで構築します。 value のデフォルトは None です。

(Patches contributed by Raymond Hettinger.)

また、 dict() コンストラクタは小さな辞書を簡単に構築出来るよう、キーワード引数を受け付けるようになりました:

>>> dict(red=1, blue=2, green=3, black=4)
{'blue': 2, 'black': 4, 'green': 3, 'red': 1}

(Contributed by Just van Rossum.)

assert ステートメントが __debug__ フラグをチェックすることはもうありません。このため、 __debug__ に代入することによってアサーションを無効にすることは出来ません。Python を -O スイッチで起動により全てのアサーションが実行されない点は、以前と変わりません。

ほとんどの型オブジェクトが今では呼び出し可能であり、なので関数、クラス、モジュールのようなオブジェクトを新たに構築するのにそれを使えます。 (new モジュールはこれにより将来のバージョンの Python で撤廃される可能性があります。 types モジュール内の型オブジェクトが使えるからです。 ---訳注: 2.6 で実際に撤廃されています。---) 例えば、新規モジュールオブジェクトは以下コードで構築出来ます:

>>> import types
>>> m = types.ModuleType('abc','docstring')
>>> m
<module 'abc' (built-in)>
>>> m.__doc__
'docstring'

新たな警告 PendingDeprecationWarning が、将来廃止される予定のある機能であることを示すために追加されました。この警告はデフォルトで 出力されません 。将来において廃止される予定の機能の使用をチェックするにはコマンドラインから -Walways::PendingDeprecationWarning:: を与えるか、 warnings.filterwarnings() を使います。

文字列ベースの例外、例えば raise "Error occurred" のようなもの、これは廃止のための過程を開始しています。文字列を例外として投げると PendingDeprecationWarning が発行されます。

None を変数名に使うと SyntaxWarning 警告を出すようになっています。将来バージョンの Python では None はキーワードになります。

The xreadlines() method of file objects, introduced in Python 2.1, is no longer necessary because files now behave as their own iterator. xreadlines() was originally introduced as a faster way to loop over all the lines in a file, but now you can simply write for line in file_obj. File objects also have a new read-only 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.

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" [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 The Python 2.3 Method Resolution Order, or read the thread on python-dev starting with the message at 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.

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 sys.setcheckinterval(N). The limit can be retrieved with the new sys.getcheckinterval() function.

マイナーですが広範囲に渡る変更として、拡張型の名前の変更があります。Python と一緒に含まれるモジュールで定義される拡張型の名前が、モジュール名と '.' が型名に前置されるようになりました。例えば、Python 2.2 ではソケットオブジェクトを作って __class__ を出力すると、このような出力だったでしょう:

>>> s = socket.socket()
>>> s.__class__
<type 'socket'>

2.3 ではこうなります:

>>> s.__class__
<type '_socket.socket'>

注意すべきであった旧スタイル・新スタイルクラスの非互換性が取り除かれました。今では新スタイルクラスの属性 __name__ と __bases__ に代入出来ます。 __bases__ に代入できるものについてのいくつかの、インスタンスの __class__ 属性への代入に関連する制限に従った制限事項はあります。

文字列に関する変更

in 演算子が文字列に対して違った振る舞いをするようになりました。以前は X と Y が文字列の場合の X in Y は、 X は単一文字でなければなりませんでした。これが X はどんな長さでも良くなり、 X in Y は X が Y のサブストリングであれば True を返すように変更されました。 X が空文字列の場合は結果は常に True になります。

>>> 'ab' in 'abcd'
True
>>> 'ad' in 'abcd'
False
>>> '' in 'abcd'
True

これはサブストリングの開始位置を教えてくれるわけではないので、その情報が必要であれば find() 文字列メソッドを使ってください。

strip(), lstrip(), rstrip() に、剥ぎ取る文字を指定する省略可能な引数が追加されています。デフォルトは従来通り全ての空白文字を削除します。:

>>> '   abc '.strip()
'abc'
>>> '><><abc<><><>'.strip('<>')
'abc'
>>> '><><abc<><><>\n'.strip('<>')
'abc<><><>\n'
>>> u'\u4000\u4001abc\u4000'.strip(u'\u4000')
u'\u4001abc'
>>>

(Suggested by Simon Brunning and implemented by Walter Dörwald.)

The startswith() and endswith() string methods now accept negative numbers for the start and end parameters.

Another new string method is zfill(), originally a function in the string module. zfill() pads a numeric string with zeros on the left until it's the specified width. Note that the % operator is still more flexible and powerful than zfill().

>>> '45'.zfill(4)
'0045'
>>> '12345'.zfill(4)
'12345'
>>> 'goofy'.zfill(6)
'0goofy'

(Contributed by Walter Dörwald.)

A new type object, basestring, has been added. Both 8-bit strings and Unicode strings inherit from this type, so isinstance(obj, basestring) will return True for either kind of string. It's a completely abstract type, so you can't create basestring instances.

内部化した文字列はもう不死身ではないので、内部辞書からの参照が、参照している唯一のものとなれば、普通にガーベージコレクト対象となります。 (Implemented by Oren Tirosh.)

最適化

The creation of new-style class instances has been made much faster; they're now faster than classic classes!

The sort() method of list objects has been extensively rewritten by Tim Peters, and the implementation is significantly faster.

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²) required for the grade-school multiplication algorithm. (Original patch by Christopher A. Craig, and significantly reworked by Tim Peters.)

The SET_LINENO opcode is now gone. This may provide a small speed increase, depending on your compiler's idiosyncrasies. See section その他の変更と修正 for a longer explanation. (Removed by Michael Hudson.)

xrange() objects now have their own iterator, making for i in xrange(n) slightly faster than for i in range(n). (Patch by Raymond Hettinger.)

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

The net result of the 2.3 optimizations is that Python 2.3 runs the pystone benchmark around 25% faster than Python 2.2.

新たなモジュール、改良されたモジュール、非推奨のモジュール

いつものように、Python の標準ライブラリには数多くの拡張とバグ修正がありました。ここでは最も注目に値する変更について、モジュールの辞書順に列挙します。変更の完全なリストについてはソースツリーの Misc/NEWS を調べるか、あるいは全ての詳細について CVS ログに目を通してみてください。

array モジュールが 'u' フォーマット文字を使った Unicode 文字の配列をサポートするようになっています。配列はまた、 += 代入演算子を使ってほかの配列内容を加算すること、 *= 演算子を使って配列を繰り返すことが可能になっています。(Contributed by Jason Orendorff.)

bsddb モジュールが PyBSDDB [https://pybsddb.sourceforge.net] バージョン 4.1.6 によって置き換えられています。これは BerkeleyDB のトランザクションの機能へのより完全なインターフェースを提供します。

古いバージョンのモジュールは bsddb185 にリネームされて、自動的にはビルドされません。有効にするには Modules/Setup を編集する必要があります。新しい bsddb パッケージは古いモジュールと互換となるように意図されていますので、何か非互換を見つけたらファイルのバグを確認してください。Python 2.3 へのアップグレードの際、前提となる BerkeleyDB ライブラリの新バージョンでインタープリタがコンパイルされるならば、ほぼ確実にあなたのデータベースは新バージョンに変換しなければならないでしょう。ソース配布物の Tools/scripts ディレクトリの db2pickle.py と pickle2db.py スクリプトを使って、これをかなり簡単に行うことが出来ます。もし既に PyBSDDB パッケージを使っていて bsddb3 としてインポートしているならば、 bsddb をインポートするように import 文を変更する必要があります。

新規の bz2 モジュールは bz2 データ圧縮ライブラリへのインターフェイスです。bz2 圧縮データは普通 zlib 圧縮データよりも小さくなります。 (Contributed by Gustavo Niemeyer.)

標準の日付時刻型が datetime モジュールとして追加されています。詳細はこのドキュメントの下の方に記述してありますのでそちらを参照して下さい。

The Distutils 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 sampmodule.c includes the header file sample.h, you would create the Extension object like this:

ext = Extension("samp",
                sources=["sampmodule.c"],
                depends=["sample.h"])

sample.h を修正するとモジュールは再コンパイルされます。 (Contributed by Jeremy Hylton.)

Other minor changes to Distutils: it now checks for the CC, CFLAGS, CPP, LDFLAGS, and CPPFLAGS environment variables, using them to override the settings in Python's configuration (contributed by Robert Weber).

Previously the 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 DocTestSuite() function creates a unittest.TestSuite object from a set of doctest tests.

新しい関数 gc.get_referents(object) は object により参照されている全てのオブジェクトのリストを返します。

The getopt module gained a new function, gnu_getopt(), that supports the same arguments as the existing getopt() function but uses GNU-style scanning mode. The existing 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:

>>> getopt.getopt(['-f', 'filename', 'output', '-v'], 'f:v')
([('-f', 'filename')], ['output', '-v'])
>>> getopt.gnu_getopt(['-f', 'filename', 'output', '-v'], 'f:v')
([('-f', 'filename'), ('-v', '')], ['output'])

(Contributed by Peter Åstrand.)

モジュール grp, pwd, resource では拡張されたタプルを返すようになりました:

>>> import grp
>>> g = grp.getgrnam('amk')
>>> g.gr_name, g.gr_gid
('amk', 500)

gzip モジュールが 2 GiB を超えるファイルを扱えるようになっています。

The new 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, heap[k] <= heap[2*k+1] and 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 https://xlinux.nist.gov/dads//HTML/priorityque.html for more information about the priority queue data structure.)

The heapq module provides heappush() and 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:

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

(Contributed by Kevin O'Connor.)

The IDLE integrated development environment has been updated using the code from the IDLEfork project (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 reload() operations. IDLE's core code has been incorporated into the standard library as the idlelib package.

imaplib モジュールが IMAP over SSL をサポートするようになりました. (Contributed by Piers Lauder and Tino Lange.)

The itertools contains a number of useful functions for use with iterators, inspired by various functions provided by the ML and Haskell languages. For example, itertools.ifilter(predicate, iterator) returns all elements in the iterator for which the function predicate() returns True, and itertools.repeat(obj, N) returns 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.)

math module の 2 つの新規関数 degrees(rads) と radians(degs) は、ラジアンと度の間の変換を行います。 math モジュールの math.sin() や math.cos() などは常にラジアンでの入力が必要です。 math.log() 関数には底を指定するオプショナルの base 引数が追加されていて、 e と 10 でない底の対数を計算するのが簡単になりました。 (Contributed by Raymond Hettinger.)

Several new POSIX functions (getpgid(), killpg(), lchown(), loadavg(), major(), makedev(), minor(), and mknod()) were added to the posix module that underlies the os module. (Contributed by Gustavo Niemeyer, Geert Jansen, and Denis S. Otkidach.)

In the os module, the *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 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 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 os.stat_float_times() is invoked to enable float return values:

>>> os.stat("/tmp").st_mtime
1034791200
>>> os.stat_float_times(True)
>>> os.stat("/tmp").st_mtime
1034791200.6335014

Python 2.4 では、浮動小数点数を返すのがデフォルトとなります。

アプリケーション開発者は、この機能を有効にするのは、全ての自身のライブラリが浮動小数点数のタイムスタンプで正しく動作するか、タプル API を使用する場合のみにしてください。使うのであればこの機能は、都度都度有効にしようとせずにアプリケーションレベルで有効にすべきです。

optparse モジュールに新たなコマンドライン引数パーサが追加されました。これはオプション値を特定の Python 型に変換することが出来、また、自動的に使用例メッセージを生成します。詳細はこのドキュメントの続くセクションを参照して下さい。

The old and never-documented linuxaudiodev module has been deprecated, and a new version named 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.)

実行中のプラットフォームについての色々な特性を決定する数多くの関数を含む、新規 platform モジュールが追加されました。アーキテクチャ、CPU タイプ、Windows の OS バージョンや Linux ディストリビューションのバージョンなどを取得できます。(Contributed by Marc-André Lemburg.)

The parser objects provided by the 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 buffer_text attribute to True will enable buffering.

The sample(population, k) function was added to the random module. population is a sequence or xrange object containing the elements of a population, and sample() chooses k elements from the population without replacing chosen elements. k can be any value up to len(population). For 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]

random が C で実装された新しいアルゴリズムのメルセンヌ・ツイスタを使うようになりました。これは以前のアルゴリズムよりも高速で、より広く研究されています。

(All changes contributed by Raymond Hettinger.)

The readline module also gained a number of new functions: get_history_item(), get_current_history_length(), and redisplay().

The rexec and Bastion modules have been declared dead, and attempts to import them will fail with a RuntimeError. New-style classes provide new ways to break out of the restricted execution environment provided by rexec, and no one has interest in fixing them or time to do so. If you have applications using 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 rexec module in those versions. To repeat: if you're using rexec, stop using it immediately.)

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

shutil モジュールに move(src, dest) が追加されており、これはファイルまたはディレクトリを新しい場所へ再帰的に移動します。

Support for more advanced POSIX signal handling was added to the signal but then removed again as it proved impossible to make it work reliably across platforms.

socket モジュールがタイムアウトをサポートするようになりました。ソケットオブジェクトの settimeout(t) メソッドに t 秒を与えることで行えます。これに続くソケット操作が t 秒を超えて完了しない場合には操作は中断し、 socket.timeout 例外を投げます。

オリジナルのタイムアウト実装は Tim O'Malley によりなされました。Michael Gilfix がこれを Python socket モジュールに統合し、長い長いレビューに導きました。コードがチェックインされたのち、Guido van Rossum はそれを部分的に書き換えました。(これは協調的開発プロセスの好例です。)

Windows での socket モジュールの Secure Sockets Layer (SSL) サポートが始まりました。

The value of the C PYTHON_API_VERSION macro is now exposed at the Python level as sys.api_version. The current exception can be cleared by calling the new sys.exc_clear() function.

新モジュール tarfile で tar 形式のアーカイブファイルの読み書きが出来ます。 (Contributed by Lars Gustäbel.)

The new textwrap module contains functions for wrapping strings containing paragraphs of text. The 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 fill(text, width) function returns a single string, reformatted to fit into lines no longer than the chosen width. (As you can guess, fill() is built on top of wrap(). For 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.
>>>

The module also contains a TextWrapper class that actually implements the text wrapping strategy. Both the TextWrapper class and the wrap() and 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.)

The thread and threading modules now have companion modules, dummy_thread and dummy_threading, that provide a do-nothing implementation of the 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:

try:
    import threading as _threading
except ImportError:
    import dummy_threading as _threading

In this example, _threading is used as the module name to make it clear that the module being used is not necessarily the actual threading module. Code can call functions and use classes in _threading whether or not threads are supported, avoiding an 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.

time モジュールの strptime() 関数は長いこと混乱の元でした。それがプラットフォームの C 関数 strptime() を使い、異なったプラットフォームごとに時折おかしなバグを持っていたからです。Brett Cannon は pure Python で、全てのプラットフォームで全く同じに振舞うように書き直した実装を寄稿しました。

新規モジュール timeit は、Python コードの断片 (スニペット) を実行するのにかかる時間を計測します。ファイル timeit.py は直接コマンドラインから実行出来ますし、モジュールの Timer クラスをインポートして直接使うことも出来ます。以下に、空の Unicode 文字列を追加することによって 8 ビット文字列を Unicode に変換するのと unicode() 関数を使うのとでいずれが高速なのかを把握するための短い例をお見せします:

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]

Tix モジュールに色々バグ修正がなされ、Tix パッケージの現在バージョンに更新されました。

Tkinter モジュールがスレッドを有効化した Tcl で動作するようになりました。Tcl のスレッドモデルは、ウィジットはそれが作られたスレッドからのみアクセスされることを必要とします。ほかのスレッドからのアクセスは Tcl を混乱させます。ある特定の Tcl インターフェイスでは、 Tkinter はウィジットがコマンドの纏め上げによって異なるスレッドからアクセスされる際に、正しいスレッドに向けて結果を待つことで自動的にこれを避けるようになりました。それ以外のインターフェイスでは自動で処理は出来ませんが、 Tkinter はそのようなアクセス時に最低でもそれが問題とわかるよう例外を送出するようになっています。この変更についての詳細な説明は https://mail.python.org/pipermail/python-dev/2002-December/031107.html をみてください。(Implemented by Martin von Löwis.)

_tkinter を介した Tcl メソッド呼び出しは今では文字列だけを返すのではありません。代わりに Tcl は対応する Python の等価なオブジェクトに変換されたオブジェクトを返します。Python に等価なものがなければ _tkinter.Tcl_Obj で包んで返します。この振る舞いは tkapp オブジェクトの wantobjects() メソッドで制御出来ます。

(ほとんどの Tkinter アプリケーションがそうするように) Tkinter モジュールを通して _tkinter を使う際、この機能は常に有効になります。これは互換性の問題を引き起こさないはずです。 Tkinter は可能な場合には文字列を Python 型に常に変換していたからです。

何か非互換性を見つけたら古い振る舞いに戻せます。最初の tkapp オブジェクトを生成する前に Tkinter モジュールの wantobjects 変数に偽をセットしてください:

import Tkinter
Tkinter.wantobjects = 0

ここで説明した変更によって何かアプリケーションの破壊があれば、バグとして報告してください。

UserDict モジュールに新しく DictMixin クラスが追加されました。既に最小限のマッピングインターフェースを持っているクラスのために、全ての辞書メソッドを定義します。これは、 shelve モジュール内のクラスのような、辞書に置換可能である必要があるクラスの記述を大幅に単純化します。

クラスがメソッド __getitem__(), __setitem__(), __delitem__(), keys() を定義している場合にはいつでも、スーパークラスとして mix-in を追加すると完全な辞書インターフェースになります。例えば:

>>> 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']

(Contributed by Raymond Hettinger.)

The DOM implementation in xml.dom.minidom can now generate XML output in a particular encoding by providing an optional encoding argument to the toxml() and toprettyxml() methods of DOM nodes.

xmlrpclib モジュールが、 Python の None のような nil データを処理するための XML-RPC 拡張をサポートするようになりました。 nil 値は XML-RPC 応答のアンマーシャルでいつでもサポートされます。 None を含んだリクエストを生成するためには、 Marshaller のインスタンスを生成する際に allow_none パラメータに真を与えなければなりません。

新規モジュール DocXMLRPCServer は、セルフ-ドキュメンティング XML-RPC サーバを書くのに使えます。実際のところをみるためにはデモモード (つまりプログラムとして) 実行してみてください。ウェブブラウザを RPC サーバに向ければ pydoc スタイルのドキュメントを生成します。xmlrpclib をサーバに向ければ実際のメソッドを呼び出せます。(Contributed by Brian Quinlan.)

internationalized domain names (RFC 3454, 3490, 3491, 3492) のサポートが追加されました。Unicode ドメイン名とその名前の ASCII 互換エンコーディング (ACE=ASCII-compatible encoding) の間の変換をするのに "idna" エンコーディングを使用出来ます:

>{}>{}> u"www.Alliancefrançaise.nu".encode("idna")
'www.xn--alliancefranaise-npb.nu'

socket モジュールも、C ライブラリに渡す前に Unicode ホスト名を ACE バージョンに透過的に変換するように拡張されています。 httplib や ftplib のようなホスト名を扱うモジュールも Unicode ホスト名をサポートしています; httplib は HTTP Host ヘッダをドメイン名の ACE 版を使って送信します。 urllib は URL の path 部分が ASCII のみである限り、非 ASCII ホスト名を持つ Unicode URL をサポートします

この変更の実装のために、 stringprep モジュール、 mkstringprep ツール、 punycode エンコーディングが追加されました。

日付時刻型

タイムスタンプとして使うのに相応しい日付と時刻の型が datetime モジュールとして追加されました。これら型は異なるカレンダであるとか多くの洒落た機能をサポートはせずに、時刻表現の基礎だけに集中するものです。

3 つの基礎となるクラスがあり、 date は年・月・日を表現し、 time は時・分・秒を、 datetime が date と time の両方の属性すべてを持ちます。また、 timedelta は 2 つの時刻の差を表現し、タイムゾーンのロジックは抽象クラス tzinfo から派生したクラスにより実装されます。

You can create instances of date and time by either supplying keyword arguments to the appropriate constructor, e.g. datetime.date(year=1972, month=10, day=15), or by using one of a number of class methods. For example, the today() class method returns the current local date.

構築後の日付時刻クラスのインスタンスは全て immutable です。オブジェクトから書式文字列を生成する数多くのメソッドがあります:

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

The replace() method allows modifying one or more fields of a date or datetime instance, returning a new instance:

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

インスタンスは比較可能で、ハッシュ出来、文字列に変換出来ます (結果は isoformat() メソッドのものと同じです)。 と datetime はお互いに減算演算が可能で、 timedelta インスタンスを加算することも出来ます。最も大きな不足機能としては、文字列を解析して date や datetime へ戻すための標準ライブラリサポートはありません。(---訳注: 2 点。「比較可能」の意味は 2.3 から 2.4 で意味が変わっています。2.4 で date と datetime の比較は出来なくなりました。2.3 では出来ていました。文字列からの datetime 構築は 2.5 で strptime() が追加されています。---)

さらに詳しい情報については、モジュールのリファレンスドキュメントを参照してください。 (Contributed by Tim Peters.)

optparse モジュール

getopt モジュールはコマンドライン引数の単純な解析を提供しています。新規に追加された optparse モジュール (元々 Optik と呼ばれていたものです) は Unix の慣習に従ったもっと念入りなコマンドライン解析を行い、自動的に --help のための出力をし、異なったオプションに対して異なったアクションを実行出来ます。 (---訳注: 2.7 以降は optparse よりも新しい argparse を使ってください。---)

OptionParser インスタンスを作ることから始め、プログラムのオプションがどんなであるかそれに対して教えてやります:

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')

コマンドラインの解析は parse_args() メソッドを呼び出すことで行います

options, args = op.parse_args(sys.argv[1:])
print options
print args

これは、全てのオプションの値を含んだオブジェクトと残った引数を含む文字列リストを返します。

色々な引数でこのスクリプトを実行すれば、あなたの期待するように動きます。この例での length 引数が自動的に整数に変換されることに注目してください。

$ ./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}>
[]
$

ヘルプメッセージはあなたのために自動生成されます:

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

さらに詳しいことはモジュールのドキュメントを参照して下さい。

Optik は Getopt SIG の読者からの示唆を受けてGreg Ward により書かれました。

Pymalloc: 特殊化されたオブジェクトアロケータ

Pymalloc は Vladimir Marangozov により書かれ Python 2.1 で追加された、特殊化されたオブジェクトアロケータです。Pymalloc は典型的な Python プログラムでのアロケーションのパターンにおいて、システムの malloc() よりも高速で省メモリであることを意図したものです。このアロケータは C の malloc() 関数を大きなメモリプールを得るのに使い、それより小さなメモリ要求はこれらプールで実現しています。

2.1 と 2.2 ではこの機能は実験的な位置付けでありデフォルトでは有効ではありませんでした。これを有効にするには Python コンパイル時に configure スクリプトに --with-pymalloc オプションを明示的に与える必要がありました。2.3 では pymalloc はさらに拡張され、また、デフォルトで有効になりました。逆にこれを無効にするのに --without-pymalloc を与える必要があります。

この変更は Python で書いたコードからは見えませんが、 pymalloc は C 拡張内のバグを露にするかもしれません。C 拡張の著者は pymalloc を有効にしてテストすべきです。というのも、ある種の正しくないコードが実行時にコアダンプしうるからです。

問題を起こすとりわけ一般的な誤りが一つあります。Python の C API 内には数多くのメモリアロケーション関数がありますが、これは以前は単に C ライブラリの malloc() と free() への別名であり、何かの間違いでミスマッチな関数呼び出しをしても、誤りは気付かれないものでした。今回のこのオブジェクトアロケータを有効化すると、これら関数は malloc() と free() への別名ではまったくなくて、メモリ解放に誤った関数を呼び出すとコアダンプし得ます。例えば PyObject_Malloc() を使って獲得したメモリは free() ではなく PyObject_Free() を使って解放する必要があります。Python に含まれるいくつかのモジュールがまさにこれに抵触し、修正の必要がありました。間違いなく多くのサードパーティモジュールが同じ問題を抱えているでしょう。

この変更の一環として、メモリアロケーションのためのこんがらかった複数インターフェイスが統合されて 2 つの API ファミリになりました。一方のファミリで獲得されたメモリは他方の関数で操作されることは許されません。一方のファミリはメモリの塊を獲得するためのもので、もう一方は Python オブジェクトの獲得に特殊化されたものです。

何某かの区別のないメモリの塊を獲得・解放するのには「生メモリ」ファミリを使います: PyMem_Malloc(), PyMem_Realloc(), PyMem_Free().

「オブジェクトメモリ」ファミリは上述の pymalloc 機構へのインターフェイスであり、多数の「小さな」獲得をするための特化がされています: PyObject_Malloc(), PyObject_Realloc(), PyObject_Free().

Python オブジェクトの獲得と解放には「オブジェクト」ファミリ PyObject_New, PyObject_NewVar, PyObject_Del() を使います。

Tim Peters による多大な仕事のおかげで、 2.3 の pymalloc はデバッグ機能も提供しています。これはメモリの上書き、二重解放に関して、拡張モジュールとインタプリタ自身について検出出来ます。このサポートを有効にするには configure スクリプトにオプション --with-pydebug を与えて Python インタプリタをデバッグバージョンとしてコンパイルしてください。

拡張の著者のために、Python 2.3 のソースとともにヘッダファイル Misc/pymemcompat.h が配布されています。これは Python 拡張に 2.3 インターフェイスでのメモリ獲得を使えるようにするもので、1.5.2 以降の全てのバージョンに対してコンパイル可能です。Python のソース配布物からファイルをコピーして、あなたの拡張ソースにバンドル出来ます。

参考

https://hg.python.org/cpython/file/default/Objects/obmalloc.c

pymalloc 実装に関する完全な詳細については Python ソースコード内の Objects/obmalloc.c ファイルの先頭のコメントを参照してください。上のファイルへのリンクは python.org の SVN ブラウザを指しています。

ビルドならびに C API の変更

Python のビルド過程と C API の変更は以下の通りです:

ガーベージコレクションで使われている循環の検出実装が安定であることがわかったため、必須とすることになりました。Python をこれなしでコンパイルすることはもう出来ません。 configure スクリプトの --with-cycle-gc スイッチは削除されました。

Python がオプショナルでシェアドライブラリ (libpython2.3.so) としてビルド可能になりました。Python の configure スクリプトに --enable-shared オプションを与えることで可能です。 (Contributed by Ondrej Palkovsky.)

マクロ DL_EXPORT と DL_IMPORT が非推奨となっています。Python コアが一般的にマクロ PyAPI_FUNC と PyAPI_DATA を使うのに対し、Python 拡張モジュールの初期化関数が新規マクロ PyMODINIT_FUNC を使って宣言されなければならなくなりました。

configure スクリプトに --without-doc-strings オプションを与えることで、ビルトイン関数とモジュールが docstring を持たないインタプリタとしてコンパイル出来るようになりました。これは Python の実行形式ファイルを 10% 小さくしますが、もちろん Python ビルトインのヘルプが取得できないことにもなります。 (Contributed by Gustavo Niemeyer.)

PyArg_NoArgs() マクロが非推奨となったので、これを使っているコードは修正しなければなりません。Python 2.2 以降ではメソッド定義テーブルでは引数を持たず、引数チェックを省けることを示すのに METH_NOARGS フラグが使えます。2.2 以前の Python バージョンとの互換性が重要な場合には PyArg_ParseTuple(args, "") を代わりに使えますが、 METH_NOARGS を使うより遅いです。

PyArg_ParseTuple() に符号なし整数の色々なサイズのためのフォーマット文字が追加されました: unsigned char のための B, unsigned short int のための H, unsigned int のための I, unsigned long long のための K。

新規関数 PyObject_DelItemString(mapping, char *key) が PyObject_DelItem(mapping, PyString_New(key)) の速記法として追加されました。

ファイルオブジェクトの内部文字列バッファの管理が変更されて、必要な場合には指数関数的に増やすようになりました。 Lib/test/test_bufio.py 内のベンチマークテストの結果での速度向上は大幅なものです (ある一つの計測では 57 秒から 1.7 秒になりました)。

It's now possible to define class and static methods for a C extension type by setting either the METH_CLASS or METH_STATIC flags in a method's PyMethodDef structure.

Python は Expat XML パーサのソースコードのコピーを丸抱えするようになり、これにより Expat のシステムのバージョンやローカルにインストールされたものへの依存がなくなっています。

あなたの拡張内で型オブジェクトを動的にアロケートする場合、 __module__ 属性と __name__ 属性に関係したルールの変更に注意してください。手短かに言えば、その型の辞書に '__module__' キーを含むよう保障する際に、モジュール名をピリオドで繋げて型名の一部となるようにすることは、期待した効果は持たなくなりました。さらなる詳細については API のリファレンスかソースを読んで下さい。

ポート特有の変更

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; fork() and 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 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 (http://www.atheos.cx/), GNU/Hurd, and OpenVMS.

その他の変更と修正

いつものように、たくさんのほかの改善とバグフィックスがソースツリー全体に渡って散らばっています。CVS 変更ログを検索すると、Python 2.2 から 2.3 にかけて適用されたパッチは 523、バグ修正は 514 ありました。いずれも少なく見積もって、です。

ほかの、さらに特筆すべき変更のいくつかを挙げます:

環境変数 PYTHONINSPECT をセットしておくと、Python インタプリタが Python プログラム実行後に対話モードに入ります。これは Python を -i で起動するのと同じです。環境変数は Python インタプリタ実行前にセットするか、Python プログラムのその実行の一部としてセットすることが出来ます。

regrtest.py スクリプトで「foo を除く全てのリソース」とする手段が出来ました。 -u オプションにリソース名を渡すのにハイフン ('-') を前置すると「このリソースを除く」ことを意味します。例えば '-uall,-bsddb' は bsddb を除く全てのリソースを有効にするのに使えます。

ドキュメントのビルドに使われるツールは今では Unix 同様に Cygwin でも動作します。

SET_LINENO 命令コード (opcode) は削除されました。彼方の昔に戻れば、この命令コードはトレースバック内で行番号を生成し、トレース関数をサポートするのに必要でした (例えば pdb のために)。Python 1.5 より、トレースバック内の行番号は "python -O" で働くための異なったメカニズムを用いて計算で求められてきました。2.3 のためには Michael Hudson がトレース関数を呼ぶのに決定する似た方法を実装しましたので、 SET_LINENO の必要性は完全になくなりました。

Python コードから何か異なる結果を見つけるのは、 -O なしで Python を実行する際のわずかなスピードアップを別とすれば、困難かもしれません。

フレームオブジェクトの f_lineno フィールドにアクセスしている C 拡張は、代わりに PyCode_Addr2Line(f->f_code, f->f_lasti) を呼び出すべきです。これは以前の Python バージョンでも "python -O" のもとでコードが動作するのにも望ましい効果を持つでしょう。

気の利いた新機能としては、トレース関数は、今ではフレームオブジェクトの f_lineno 属性を、次に実行される行に変更してセットします。 pdb デバッガにはこの新機能の恩恵を受けて jump コマンドが追加されています。 (Implemented by Richie Hindle.)

Python 2.3 への移植

このセクションでは前述の変更により必要となるかもしれないコードの変更を列挙します:

yield は今では常にキーワードです。変数名として使っていたならば、別の名前を選ぶ必要があります。

文字列 X と Y について、 X in Y は X が一文字以上の場合でも動作するようになりました。

int() 型コンストラクタは、文字列や浮動小数点数を整数に収める際、それがとても大き場合に OverflowError を投げるのではなく長整数を返すようになっています。

8 ビット文字を含んだ Unicode 文字列をソースコードに埋め込む場合、ファイルのエンコーディング (UTF-8, Latin-1, あるいはほか何か) を、ファイルの先頭のコメントに宣言しなければなりません。 PEP 263: ソースコードのエンコーディング を参照してください。

_tkinter を介した Tcl メソッド呼び出しは今では文字列だけを返すのではありません。代わりに Tcl は対応する Python の等価なオブジェクトに変換されたオブジェクトを返します。Python に等価なものがなければ _tkinter.Tcl_Obj で包んで返します。

0xffffffff のような大きな値の 8 進、16 進リテラルで FutureWarning が発行されます。2.3 ではこれは 32 ビットの値に格納されて結果は負の値になりますが、Python 2.4 ではこれは正の長整数になります。

この警告の修正をする方法が少しだけあります。本当に正の値が欲しいのであれば L をリテラルの最後に付けて下さい。32 ビット分だけの下位ビットセットで 32 ビット整数を取り出したいのであれば、また、 ~(1 << 31) のような式を使ってきたのであれば、おそらく全ビットをセットすることから始めて上位ビットをクリアするのが最も簡明です。例えば最上位ビット (ビット 31) を単にクリアするには 0xffffffffL &~(1L<<31) と書けます。(---訳注: 2 点。Python 3 サポートを検討するならば L は付けないように。2.4 以降は警告もなしに長整数になりますし。もう一点はこのパラグラフ全体について。根本的に警告への対処の話をしてるようで後半はほとんど本質でない話をしているので意味不明な文章になっています。本当に 2.3 を使わなければならないのでない限り、この文章を真面目に理解しようとしなくとも良いと思います(本質的な措置は L を付けることしかない、2.3 では)。---)

__debug__ に代入することでアサーションを無効にすることは出来なくなりました。

Distutils の setup() 関数に depends のような色々な新しいキーワード引数が追加されています。Distutils の古いバージョンでは未知のキーワードを渡すと処理を中断してしまいます。新旧で動作させなければならないのであれば、 setup.py 内で get_distutil_options() 関数の有無をチェックし、それらをサポートするバージョンの Distutils でのみ新しいキーワード引数を使うようにしてください:

from distutils import core

kw = {'sources': 'foo.c', ...}
if hasattr(core, 'get_distutil_options'):
    kw['depends'] = ['foo.h']
ext = Extension(**kw)

None を変数名に使うと SyntaxWarning 警告を出すようになっています。

Python と一緒に含まれるモジュールで定義される拡張型の名前にモジュール名と '.' が型名の頭に付くようになっています。

謝辞

著者は提案の申し出や修正、様々なこの記事の草稿の助けをしてくれた以下の人々に感謝します: 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.

What's New in Python 2.2

著者:

A.M. Kuchling

はじめに

この文書は 2002 年 10 月 14 日にリリースされた Python 2.2.2 の新機能について解説します。Python 2.2.2 は 2001 年 12 月 21 日にリリースされた Python 2.2 のバグフィックスリリースです。

Python 2.2 は「クリーンアップリリース」と考えることが出来ます。ジェネレータやイテレータのように、完全に書き直されたいくつかの機能があります。ほとんどのその変更は著しくて以前とはかけ離れたものとなりましたが、これは言語設計の不品行と暗黒面を綺麗に掃除することを目的としています。

このドキュメントは個々の新機能の完全な詳細を提供するのではなくて、簡易な概要を提供することを目的にしています。完全な詳細が知りたければ、Python ライブラリリファレンス [https://docs.python.org/2.2/lib/lib.html] 、Python リファレンスマニュアル [https://docs.python.org/2.2/ref/ref.html] のような Python 2.2 のドキュメントを参照すべきです。設計と実装の根拠を理解したい場合は、新機能に関する PEP を参照してください。

PEP 252 と PEP 253: 型とクラスについての変更

最大にして広範に影響が及ぶ Python 2.2 の変更は、 オブジェクトとクラスの Python モデルについてのものです。変更は後方互換であるはずなので、あなたのコードは変更なしで動きそうです。ですがその変更は、いくつかの素晴らしい能力を発揮させます。この、本記事中において最も長くて複雑なセクションについて始める前に、変更の概要を提供し、いくつかの所感を提示しておこうと思います。

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

Python 2.2 はこれを修正し、また、その過程においていくつかの心躍る新機能を追加しました。簡単に要約します:

あなたはリストのような組み込み型をサブクラス化出来ます。整数でさえ出来ます。そしてあなたのサブクラスは、元の型を要求している全ての場所で動作します。

以前より使えたインスタンスメソッド加え、静的メソッド、クラスメソッドを今や定義出来ます。

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

slots を使って、インスタンスの適正な属性を特定の集合に制限できます。これはタイプミスに対する安全装置にも出来ますし、将来のバージョンの Python では今よりも最適化される可能性があります。

一部のユーザはこれら全ての変更に懸念を表明しました。そうだね、彼らは言います、新しい機能はかっこいいし昔の Python では出来なかった全ての芸当の役に立つさ、だけどさ、それって言語をより複雑にするよなぁ。一部の人々はずっと常に、Python が単純さを保つことを提言してきました。そして彼らはその単純さが失われると感じたのです。

個人的に私は、それらは心配には及ばない、と思っています。多くのそれら新機能は随分と秘伝的で、あなたはそれらに気付く必要もないままたくさんの Python コードを書けます。単純なクラスを書くことはかつてよりも難しいということはなく、実際にそれを必要としない限りは、秘伝をわざわざ学習することも教育することも必要ありません。以前ならば C 言語からでしか可能でなかったようなある種の複雑なタスクは、いまやピュアな python から出来て、私には何もかもが良い方向に思えます。

この記事では全てのショーケースの品を陳列しようとはしませんし、将来の拡張のために必要な小さな変更は説明しません。代わりにこのセクションではおおまかなアウトラインを描きます。Python 2.2 の新しいオブジェクトモデルの追加的な情報源については、 関連リンク を参照してください。

旧と新クラス

まず、 Python 2.2 は本当に 2 種類のクラスを持っているのだ、ということを知る必要があります: クラシック、あるいは旧スタイルクラス、と、新スタイルクラスです。旧スタイルクラスのモデルは、以前のバージョンのクラスモデルと完全に同じものです。このセクションに記述する全ての新機能は、全て新スタイルクラスだけに適用されるものです。この逸脱が未来永劫続くことは望まれていません; 最終的には旧スタイルクラスは撤廃されます。たぶん Python 3.0 で。

では、新スタイルクラスは、どうやって定義すればいいのでしょう? 答えは、既存の新スタイルクラスをサブクラス化することです。たとえば整数、リスト、辞書やファイルでさえも、ほとんどの Python 組み込み型は今では新スタイルクラスです。 object という名の新スタイルクラスは全ての組み込み型の基底クラスとして既に追加されていて、相応しい組み込み型がなければ単に object をサブクラス化すれば良いです:

class C(object):
    def __init__ (self):
        ...
    ...

This means that 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 __metaclass__ --- see PEP 253 [https://peps.python.org/pep-0253/] for the details --- but it's easier to just subclass object.)

組み込み型(ビルトイン型)のための型オブジェクトは、クレバーなトリックを使って名付けられた組み込み(ビルトイン)として利用可能です。Python は既に組み込み関数 int(), float(), str() を持っていました。2.2 にはその関数はなくなり、型オブジェクトは呼び出されるとファクトリとして振舞います:

>>> int
<type 'int'>
>>> int('123')
123

To make the set of types complete, new type objects such as dict() and file() have been added. Here's a more interesting example, adding a lock() method to file objects:

class LockableFile(file):
    def lock (self, operation, length=0, start=0, whence=0):
        import fcntl
        return fcntl.lockf(self.fileno(), operation,
                           length, start, whence)

The now-obsolete posixfile module contained a class that emulated all of a file object's methods and also added a 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 LockableFile.

デスクリプタ

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 __members__ and __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 __dict__ of an object, but when class inheritance or an arbitrary __getattr__() hook were in use this could still be inaccurate.

その新しいクラスモデルの根底にあったひとつの大きな着想は、 descriptors を使ったオブジェクトの属性を記述する API を正式なものにしてしまうことです。デスクリプタは属性の値を記述し、それがメソッドなのかフィールドなのかを伝えます。デスククリプタ API によって、静的メソッドとクラスメソッドが、より風変わりなコンストラクタとともに可能となりました。

属性デスクリプタはクラスオブジェクト内部に棲息するオブジェクトで、それ自身のいくつかの属性を持っています:

__name__ は属性の名前です。

__doc__ is the attribute's docstring.

__get__(object) は object から属性値を取り出すメソッドです。

__set__(object, value) は object の属性に value をセットするメソッドです。

__delete__(object, value) は object の value 属性を削除します。

例えば、あなたが obj.x と書いたときに Python が実際に行うことは以下です:

descriptor = obj.__class__.x
descriptor.__get__(obj)

For methods, 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:

class C(object):
    def f(arg1, arg2):
        ...
    f = staticmethod(f)

    def g(cls, arg1, arg2):
        ...
    g = classmethod(g)

The staticmethod() function takes the function 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 (def static f, defstatic f(), or something like that) but no such syntax has been defined yet; that's been left for future versions of Python.

スロットとプロパティのような新機能がさらに新種のデスクリプタとして実装され、また、何か奇抜なデスクリプタクラスを書くことは難しくはありません。例えば、Eiffel 言語スタイルのメソッドに対する事前条件・事後条件を書くことを可能とするデスクリプタクラスを書けるかもしれません。それを使ったクラスはきっとこう定義出来るでしょう:

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)

Note that a person using the new 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 eiffelmethod() or the ZODB or whatever, but most users will just write code on top of the resulting libraries and ignore the implementation details.

多重継承: ダイヤモンドルール

多重継承は名前解決のルールの変更を経てより有用なものになっています。クラスのこのようなセットを考えてみましょう (ダイアグラムは Guido van Rossum による PEP 253 [https://peps.python.org/pep-0253/] より):

      class A:
        ^ ^  def save(self): ...
       /   \
      /     \
     /       \
    /         \
class B     class C:
    ^         ^  def save(self): ...
     \       /
      \     /
       \   /
        \ /
      class D

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 D.save() will search the classes D, B, and then A, where save() would be found and returned. C.save() would never be found at all. This is bad, because if C's save() method is saving some internal state specific to C, not calling it will result in that state never getting saved.

新スタイルクラスはちょっと説明するのに複雑な違ったアルゴリズムを使い、この状況では正しいことをします(Python 2.3 ではこのアルゴリズムはさらに変更されて、ほとんどのケースで同じ結果となり、本当に複雑な継承グラフの場合にもっと有用な結果となりました)。

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 [D, B, A, C, A].

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 [D, B, C, A] after dropping duplicates.

Following this rule, referring to D.save() will return 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, 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 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, D's save() method would look like this:

class D (B,C):
    def save (self):
        # Call superclass .save()
        super(D, self).save()
        # Save D's private information here
        ...

super() は super(class) や super(class1, class2) のように呼ばれれば非束縛のスーパークラスオブジェクトも返せますが、これはあまり役には立たないでしょう。

属性アクセス

A fair number of sophisticated Python classes define hooks for attribute access using __getattr__(); most commonly this is done for convenience, to make code more readable by automatically mapping an attribute access such as obj.parent into a method call such as obj.get_parent. Python 2.2 adds some new ways of controlling attribute access.

まず、 __getattr__(attr_name) は新スタイルクラスにおいてもなおサポートされ、変更はありません。これまで同様に、 obj.foo アクセスが試みられて、インスタンスの辞書に foo 名の属性が見つからなければ呼び出されます。

New-style classes also support a new method, __getattribute__(attr_name). The difference between the two methods is that __getattribute__() is always called whenever any attribute is accessed, while the old __getattr__() is only called if 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 __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 __dict__. __getattr__() methods also end up being called by Python when it checks for other methods such as __repr__() or __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.

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 size attribute that's computed, but also settable, you could write:

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")

That is certainly clearer and easier to write than a pair of __getattr__()/__setattr__() methods that check for the size attribute and handle it specially while retrieving all other attributes from the instance's __dict__. Accesses to 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.

もう一つ最後、新しいクラス属性 __slots__ を使うと、オブジェクトで参照出来る属性リストを制約することが出来ます。Python オブジェクトは普通非常に動的で、どんなときにもインスタンスに対して単に obj.new_attr=1 とするだけで新しい属性を定義出来ます。新スタイルクラスは __slots__ という名前のクラス属性を定義出来、これにより適正な属性名集合を特定の集合に制限出来ます。実例をみるのが早いです:

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

__slots__ リストに含めなかった属性への代入を試みて AttributeError になっていることに注目してください。

関連リンク

このセクションは新機能について、あなたがプログラミングを始める説明としては十分な簡単な概要だけ示しました。ですが、多くの詳細は、単純化したり無視しています。もっと完全な光景を眺めたければ、どこに行けば良いでしょうか?

The デスクリプタ ガイド 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.

次です。2 つの関連する PEP、 PEP 252 [https://peps.python.org/pep-0252/], PEP 253 [https://peps.python.org/pep-0253/] があります。 PEP 252 [https://peps.python.org/pep-0252/] は "型をもっとクラスに似せる(Making Types Look More Like Classes)" というタイトルで、デスクリプタ API についてカバーしています。 PEP 253 [https://peps.python.org/pep-0253/] は "組み込み型のサブタイプ化(Subtyping Built-in Types)" というタイトルで、組み込み型のサブタイプを可能とするための型オブジェクトの変更について記述しています。 PEP 253 [https://peps.python.org/pep-0253/] は 252 よりも複雑な PEP で、型とメタ型で必要な説明のいくつかのポイントでは、あなたの脳味噌は爆発するかもしれないです。どちらの PEP も、著・実装ともに、Zope Corp. チームの残りのメンバーからのかなりの支援を受けて、Guido van Rossum によって書かれました。

最後ですが、究極の権威があります: ソースコードです。型ハンドリングのほとんどの機構は Objects/typeobject.c 内にあります。ただしこれに頼るのは、python-list や python-dev へ質問を投稿することを含むほかの全ての手段を使い果たしたのちの最後の手段にしてください。

PEP 234: イテレータ

2.2 でのもう一つの重要な追加は、C と Python レベル両方に対するイテレーションインターフェイスです。オブジェクトが呼び出し元からどのように反復されるのか定義出来ます。

In Python versions up to 2.1, the usual way to make for item in obj work is to define a __getitem__() method that looks something like this:

def __getitem__(self, index):
    return <next item>

__getitem__() is more properly used to define an indexing operation on an object so that you can write obj[5] to retrieve the sixth element. It's a bit misleading when you're using this only to support 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 __getitem__() calls will be made with index incrementing by one each time. In other words, the presence of the __getitem__() method doesn't mean that using file[5] to randomly access the sixth element will work, though it really should.

In Python 2.2, iteration can be implemented separately, and __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, iter(obj) or iter(C, sentinel), is used to get an iterator. iter(obj) returns an iterator for the object obj, while 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 __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 self. In particular, iterators will usually be their own iterators. Extension types implemented in C can implement a tp_iter function in order to return an iterator, and extension types that want to behave as iterators can define a tp_iternext function.

それでは、結局のところイテレータは実際どんなでしょうか? これに必要なメソッドは一つ、 next() です (---訳注: Python 3 で __next__ に変更されています---)。これは引数を取らず、次の値を返します。返すべき値がなくなったら、 next() 呼び出しは StopIteration 例外を送出しなければなりません:

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

In 2.2, Python's for statement no longer expects a sequence; it expects something for which iter() will return an iterator. For backward compatibility and convenience, an iterator is automatically constructed for sequences that don't implement __iter__() or a tp_iter slot, so 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:

>>> L = [1,2,3]
>>> i = iter(L)
>>> a,b,c = i
>>> a,b,c
(1, 2, 3)

いくつかの Python の基礎型には既にイテレータのサポートが追加されています。辞書に対して iter() を呼び出すと、キーの反復をするイテレータが返ります:

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

That's just the default behaviour. If you want to iterate over keys, values, or key/value pairs, you can explicitly call the iterkeys(), itervalues(), or iteritems() methods to get an appropriate iterator. In a minor related change, the in operator now works on dictionaries, so key in dict is now equivalent to dict.has_key(key).

ファイルもイテレータを提供しています。これはファイルに読むべき行がなくなるまで readline() を呼び出すもので、つまりファイルを行ごとに読み出すのにこのように書けるわけです:

for line in file:
    # do something for each line
    ...

イテレータは前進しか出来ないことに注意してください; 前の要素を取り出す手段もなければ、イテレータをリセットしたりコピーしたりといったことも出来ません。イテレータオブジェクトにそのような追加の能力を持たせることは出来ますが、イテレータプロトコルが規定するのは next() メソッドのみです。

参考

PEP 234 [https://peps.python.org/pep-0234/]: イテレータ

著: Ka-Ping Yee と GvR (Guido van Rossum); 実装: Python Labs クルー, 主に GvR と Tim Peters.

PEP 255: 単純なジェネレータ

ジェネレータはもう一つの新機能で、これはイテレータの導入と連携するものです。

Python や C の標準的な関数コールについては、よくご存じに違いありません。関数を呼ぶと、ローカル変数を作るプライベートな名前空間ができますね。その関数が return 文まで来ると、ローカル変数が破壊されてから、返り値が呼び出し元に返ります。次に同じ関数をもう一度呼ぶと、新しいプライベート名前空間に新規のローカル変数が作られるのです。しかし、関数を出るときにローカル変数を捨てなければどうなるでしょうか。その出ていったところから関数を続行できたとしたら、どうでしょう。これこそジェネレータが提供する機能です; すなわち、ジェネレータは続行できる関数と考えることができます。

ジェネレータ関数の最も単純な例です:

def generate_ints(N):
    for i in range(N):
        yield i

新しいキーワード yield がジェネレータのために導入されました。 yield ステートメントを含むどんな関数もジェネレータ関数です; Python バイトコードコンパイラはこれを検知し、関数が特別に扱われるように翻訳します。新たなキーワードの導入なので、ジェネレータを使えるようにするには from __future__ import generators ステートメントをモジュールソースコードの先頭付近に含めなければなりません。Python 2.3 ではこのステートメントは不要になります。(---訳注: Python 2.5 の PEP 342 も参照して下さい。この 2.2 で導入時点の yield はステートメントではなく式に変更されています。---)

ジェネレータ関数を呼び出すと、単一の値の代わりにイテレータプロトコルに対応したオブジェクトを返します。上の例で yield を実行したとき、ジェネレータは return 文のようにして i の値を生成します。 yield と return 文の大きな違いは、 yield に到達した段階でジェネレータの実行状態が一時停止になって、ローカル変数が保存される点です。次回そのジェネレータの .next() メソッドを呼ぶと、 yield の直後から関数が実行を再開します。(複雑な理由により、 yield は try...finally の try ブロック内に含めることは許されていません; PEP 255 [https://peps.python.org/pep-0255/] に yield と例外の相互作用についての詳細説明がありますので参照して下さい。) --- (---訳注: Python 2.5 の PEP 342 で try...finally 内に置けないという制約はなくなりました。また、 try...finally の try 、とここであえて特定しているのは、同じく 2.5 の PEP 341 によって try/except/finally の一体化されるまでは、 finally の try と except の try が別物だったからです。---)

上記の generate_ints() ジェネレータはこんな具合に使います:

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

同じく for i in generate_ints(5) や a,b,c = generate_ints(3) といった書き方もできます。

ジェネレータ関数内で return 文は、引数を付けずに、処理の終わりを知らせるためにだけ使うことができます; return を実行したあとは、もうそのジェネレータが値を返すことはできません。ジェネレータ関数の中では、 return 5 などと値を付けた return は構文エラーです。ジェネレータの出力が終わったことを示すには、ほかにも、手動で StopIteration を投げてもいいですし、関数の最後まで実行するだけでも同じことになります。(---訳注: Python 2.7 まではジェネレータ内での戻り値のある return 5 は構文エラーになりますが、少なくとも Python 3.4 で構文エラーとはなりません。単に無視されます。リファレンスに言及されていない振舞いなので、何かの事故かもしれません。いずれにせよジェネレータ内では Python 3 でも return で値は戻せません。---)

自分でクラスを書いて、ジェネレータで言うところのローカル変数をインスタンス変数として全部保管しておけば、同じ効果を得ることは可能です。たとえば整数のリストを返すのは、 self.count を 0 にして、 next() メソッドが self.count をインクリメントして返すようにすればできます。しかしながら、ある程度複雑なジェネレータになってくると、同じことをするクラスを書くのは格段にややこしいことになります。 Lib/test/test_generators.py にはもっと面白い例がたくさん含まれています。一番単純な一つは、ジェネレータを再帰的に使ってツリーを順繰りに横断する実装をするこれです (---訳注: ジェネレータは現在の最新 3.5 までの間に 2 度大きな機能強化が行われているのですが、一つが 2.5 での PEP 342 でこれは yield 「に」値を戻せるようにするものです。もう一つが 3.3 での PEP 380 で、これはサブジェネレータへの委譲 yield from <subgen> の追加でした。ですのでこの 3.3 からの yield from を使うと下記例はもっとスッキリ書けます。---):

# 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

ほかにも Lib/test/test_generators.py には、N-Queens 問題 (N×N コマのチェス盤に、互いに攻撃できないような配置で N 個のクイーンを置く) やナイト・ツアー (N×N 盤の全コマをナイトが一度ずつ通るような経路を探す) の解を出す例が入っています。

ジェネレータの発想はほかのプログラミング言語、特に Icon (https://www2.cs.arizona.edu/icon/) から着想しています。Icon ではジェネレータが言語の中枢になっています。Icon では、あらゆる式と関数がジェネレータのように振舞います。 https://www2.cs.arizona.edu/icon/docs/ipd266.htm の "Icon プログラミング言語の概要" の一つの例が、これがどのようなものであるのかを教えてくれます:

sentence := "Store it in the neighboring harbor"
if (i := find("or", sentence)) > 5 then write(i)

Icon では find() 関数は部分文字列 "or" が見つかる位置 3, 23, 33 を返します。 if 文内では i には最初 3 が代入されますが、これは 3 より小さいので比較は失敗し、Icon は次の値 23 を取り出します。 23 は 5 より大きいので比較は成功し、コードは 23 をスクリーンに表示します。

Python では Icon がそうするほどにはジェネレータを中心的概念に置きません。ジェネレータは Python 言語中核の新たな一面ではありますが、それらを学ぶのも使うのも誰しも行うべきだというものでもなく、そしてこれで解決できない何か問題があれば、忘れてしまっても良いものです。Icon と比較した特筆すべき Python インターフェイスの機能はジェネレータの状態が具象オブジェクト (イテレータ) で表現されることであり、それは他の関数に渡せますし、データ構造に記憶しておくことも出来ます。(---訳注: ジェネレータについてかなり控えめなのは、この時点で著者は将来の拡張を既に見据えていたから? かもしれませんね。PEP 342 と PEP 380 により今やジェネレータはこの頃より遥かに高機能になっており、今ではきっと「こんなものなくても困らない」なんて Python 使いはいないでしょう。---)

参考

PEP 255 [https://peps.python.org/pep-0255/] - 単純なジェネレータ

Neil Schemenauer, Tim Peters, Magnus Lie Hetland により著されました。実装のほとんどは Neil Schemenauer と Tim Peters により行われ、 Python Labs クルーにより他の修正が行われました。

PEP 237: 長整数と整数を一体化していく

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 2**32 bytes, the 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 'abc'[1L:] would raise a TypeError exception with the message 'slice index must be int'.

Python 2.2 は必要に応じて short 整数を長整数に値をシフトします。 'L' サフィックスは長整数リテラルを示すのにはもはや不要です。今ではコンパイラは相応しい型を選べます。('L' サフィックスは将来の Python 2.x では非推奨となり、Python 2.4 では警告となり、おそらく Python 3.0 では削除されます。 --- 訳注: Python 3 で 'L' が廃止されて、付けると構文エラーになるようになったのは事実です。ですが少なくとも Python 2.7 では -3 でも -Qwarnall でも警告とならないので注意してください。Python 2 系を使っていて Python 3 との互換性を持ちたいならば、 2.2 以降では 'L' は付けるべきではありません。 --- ) かつて OverflowError となっていたような多くの演算が、今ではその結果として長整数を返します。例えば:

>>> 1234567890123
1234567890123L
>>> 2 ** 64
18446744073709551616L

ほとんどのケースで、今や整数と長整数は同じものとして扱われるでしょう。 type() ビルトインで今でも区別出来ますが、ほとんど必要ないでしょう (--- 訳注: Python 3 では本当にこの2つの区別がなくなったので、当然区別出来ません。Python 3 系への移行を考えている Python 2 コードは、両者の区別に頼らないようにするべきです。 ---)。

参考

PEP 237 [https://peps.python.org/pep-0237/] - 長整数と整数を一体化していく

Moshe Zadka と Guido van Rossum 著、実装 (ほぼ) Guido van Rossum.。

PEP 238: 除算演算子を変更していく

Python 2.2 の変更で最も物議を醸すものが、Python 誕生時からずっとそうであり続けた古い設計の欠陥、これを修正するための取り組み開始の予兆です。現在の Python の除算演算子 / は 2 つの整数引数に対して C 言語の除算演算子のように振舞います: 端数部があれば切り捨てて整数を結果として返します。例えば 3/2 は 1.5 ではなく 1 で、 (-1)/2 は -0.5 ではなく -1 です。Python の動的型付けにより演算対象の型がなんなのかを容易には決定できないくせに 2 つの演算対象の型に依存するので、除算の結果は予想に反したものとなりうるのです。

(議論の的となるのはこれが 本当の 設計の欠陥なのかどうかと、果たしてこれを修正することで既存のコードを破壊する価値はあるのかどうかです。それは python-dev での終わりのない議論を巻き起こし、2001 年 7 月には comp.lang.python への辛辣な投稿の嵐に突入しました。私はここではどちらかの側に立って説きつけるつもりはなく、Python 2.2 で何が実現したのかを記述することだけに専念します。PEP 238 [https://peps.python.org/pep-0238/] にはその主張と反対意見の要約が書かれていますので、そちらをお読みください。)

この変更がコードを破壊しうるために、導入は大変ゆっくり少しずつ進められていきます。Python 2.2 が移行を始めますが、切り替えは Python 3.0 になるまで達成させられることはありません。

まず最初に、いくつか PEP 238 [https://peps.python.org/pep-0238/] から用語を借りることにします。 "真の除算 (True division)" とは、プログラマでない人々が一番馴染みのある除算です。 3/2 は 1.5、1/4 は 0.25、などなど。 "切り捨て除算 (Floor division)" は、整数の被演算子が与えられたときの Python の / 演算子が現在やっていることで、結果は真の除算の結果の値の小数点以下を小さくなる方向へ丸めたものです。 "クラシック除算 (Classic division)" は現在の / の混合した振る舞いを指します。演算対象が整数同士であれば切り捨て除算の結果となり、一方が浮動小数点数であれば真の除算の結果となる振る舞いです。

以下が 2.2 で導入される変更です:

新しい演算子 // が floor division の演算子です。(いえーい、これって C++ コメントのシンボルに似てるね、なんてことは私たちは知っています。) // は演算対象の型がなんであれ いつでも floor division を実行しますので、 1 // 2 は 0、 1.0 // 2.0 も 0.0 です。

// は Python 2.2 でいつでも使えます; __future__ を使って有効化するなんてことは必要ないです。

from __future__ import division をモジュールに import することで、 / 演算子が真の除算 (true division) の結果を返すように変更されるので、 1/2 は 0.5 になります。 __future__ 文なしでは / はクラシック除算 (classic division) のままです。 / が持つデフォルトの意味は Python 3.0 になるまで変更されません。

Classes can define methods called __truediv__() and __floordiv__() to overload the two division operators. At the C level, there are also slots in the PyNumberMethods structure so extension types can define the two operators.

Python 2.2 は、コードが変更後の除算セマンティクスで動作するかどうかをテストするコマンドライン引数をサポートします。 -Q warn で python を実行すると、除算が二つの整数に適用されている箇所全てで警告します。除算の意味変更の影響を受ける箇所の特定と修正に使えるでしょう。デフォルトでは、Python 2.2 は警告なしで単純に classic division を実行します; その警告がデフォルトになるのは Python 2.3 からです。

参考

PEP 238 [https://peps.python.org/pep-0238/] - 除算演算子を変更していく

Moshe Zadka と Guido van Rossum 著、実装 Guido van Rossum.。

Unicode の変更

Python の Unicode サポートが 2.2 で少し拡張されています。Unicode 文字列は普通は 16 ビット符号なし整数としての UCS-2 で格納されます。Python 2.2 は内部エンコーディングとして 32 ビット符号なし整数の UCS-4 を使うようにもコンパイル出来ます。これは configure スクリプトに --enable-unicode=ucs4 オプションを与えることで行います。(--disable-unicode を与えることで完全に Unicode サポートを無効にすることも出来ます。)

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 unichr() function is expanded accordingly. Using an interpreter compiled to use UCS-2 (a "narrow Python"), values greater than 65535 will still cause unichr() to raise a ValueError exception. This is all described in PEP 261 [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 encode() method to convert the string to a selected encoding such as UTF-8 or Latin-1. A symmetric decode([*encoding*]) method has been added to 8-bit strings (though not to Unicode strings) in 2.2. decode() assumes that the string is in the specified encoding and decodes it, returning whatever is returned by the codec.

この新たなインターフェイスに相乗りする形で、 Unicode には無関係のタスクのためのコーデックが追加されました。例えば uu エンコーディング、 MIME の base64 エンコーディング、 zlib モジュールでの圧縮のためのエンコーディングが追加されています:

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

To convert a class instance to Unicode, a __unicode__() method can be defined by a class, analogous to __str__().

encode(), decode(), and __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.

参考

PEP 261 [https://peps.python.org/pep-0261/] - 'wide' Unicode 文字のサポート

Paul Prescod 著。 (---訳注: この What's New セクションと PEP 内容は 2.x ではずっと有効ですが、3.x で大幅に変わっていて逐一補足出来ないほど大きく違っています。変更の概要についてはクックブックの「Python 2 から Python 3 への移植」がわかりやすいと思います。---)

PEP 227: 入れ子状のスコープ

Python 2.1 では、静的にネストされたスコープが from __future__ import nested_scopes ディレクティブで有効に出来るオプションの機能として追加されました。2.2 では入れ子のスコープには特別に有効化する必要なく、もういつでもそこにあります。このセクションの残りの部分は "What's New in Python 2.1" の入れ子のスコープの記述からの丸々コピーですので、2.1 のときに読んだなら読み飛ばしてもらって結構です。

Python2.1 で導入され、2.2 で完成した最も大きな変更点は Python のスコープルールです。Python2.0では、ある指定された時点である変数の名前を検索するために多くても3つの名前空間、つまりローカル、モジュールレベル、ビルトイン名前空間しか使われませんでした。このことは直感的な期待と一致せずしばしば人々を驚かせました。例えば、入れ子になった再帰関数の定義は動きません:

def f():
    ...
    def g(value):
        ...
        return g(value-1) + 1
    ...

The function g() will always raise a NameError exception, because the binding of the name 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 lambda expression clumsier, and this was a problem in practice. In code which uses lambda you can often find local variables being copied by passing them as the default values of arguments.

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

過度な関数型スタイルで書かれた Python コードの可読性は、結果的にはひどく苦痛を感じるものですね。

Python 2.2 の最も重要な変更点は、この問題を解決するために静的なスコープが追加されたことです。最初の効果として、 name=name という例ではデフォルトの引数は必要ありません。簡単に言えば、指定された引数名が関数内の値に割り当てられない場合(def 、 class または import ステートメントの割り当てによって)、変数の参照は外側のスコープのローカル名前空間で検索されます。ルールや実装の詳細は PEP で参照できます。

この変更は、同じ変数名がモジュールレベルと関数の定義が含まれている関数内のローカルの両方で変数名として使用されているコードで、互換性の問題を引き起こす可能性があります。ですがむしろ気にしなくてよいでしょう。そのようなコードはそもそも最初から相当こんがらかっているので。

この変更の副作用の一つは、 from module import * と exec の両ステートメントが特定の条件下の関数スコープ内で不正となることです。 Python のリファレンスマニュアルははじめからずっと from module import * はトップレベルモジュールでのみ合法であると言ってきましたが、以前の CPython インタプリタはこれを一度も強制していませんでした。入れ子になったスコープ実装の一環として、Python のソースをバイトコードに変換するコンパイラは、内包されたスコープ内の変数にアクセスするために別のコードを生成する必要があります。 from module import *, exec はコンパイラにこれを理解することを不可能にしてしまいます。なぜならそれらはコンパイル時にはわからないローカル名前空間に名前を追加するからです。それゆえ、もし関数が関数定義を含んだり自由な変数に lambda の語句を含んだりする場合、コンパイラは SyntaxError 例外を上げて知らせます。

前述した説明を少し明確にするため、例を挙げます:

x = 1
def f():
    # The next line is a syntax error
    exec 'x=2'
    def g():
        return x

Line 4 containing the exec statement is a syntax error, since exec would define a new local variable named x whose value should be accessed by g().

これは実際には大した制約でもないはずです。 exec が Python コードで使われるのは稀です(使われているとしたら大抵どこか貧弱な設計であることの証)。

参考

PEP 227 [https://peps.python.org/pep-0227/] - 静的に入れ子になったスコープ

Jeremy Hylton著、実装

新しいモジュールと改良されたモジュール

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

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)'}, ... ]

The SimpleXMLRPCServer module makes it easy to create straightforward XML-RPC servers. See http://xmlrpc.scripting.com/ for more information about XML-RPC.

新しい hmac モジュールは、 RFC 2104 [https://datatracker.ietf.org/doc/html/rfc2104.html] で記述される HMAC アルゴリズムを実装します 。 (Contributed by Gerhard Häring.)

Several functions that originally returned lengthy tuples now return pseudo-sequences that still behave like tuples but also have mnemonic attributes such as memberst_mtime or tm_year. The enhanced functions include stat(), fstat(), statvfs(), and fstatvfs() in the os module, and localtime(), gmtime(), and strptime() in the time module.

例えば旧式のタプルでファイルサイズを得るには file_size = os.stat(filename)[stat.ST_SIZE] のように書くしかありませんでしたが、今ではもっとわかりやすい file_size = os.stat(filename).st_size のように書くことが出来ます。

この機能のオリジナルのパッチは Nick Mathewson により寄稿されました。

Python プロファイラが大幅に改造されて、出力の色々な間違いが修正されました。 (Contributed by Fred L. Drake, Jr. and Tim Peters.)

socket モジュールを IPv6 サポート付きでコンパイル可能になりました。Python の configure スクリプトに --enable-ipv6 オプションを与えてください。(Contributed by Jun-ichiro "itojun" Hagino.)

Two new format characters were added to the struct module for 64-bit integers on platforms that support the C long long type. q is for a signed 64-bit integer, and Q is for an unsigned one. The value is returned in Python's long integer type. (Contributed by Tim Peters.)

インタプリタの対話モードに新たに help() ビルトインが追加されています。これは Python 2.1 で導入された pydoc モジュールを用いて対話的なヘルプを提供します。 help(object) で object について手に入る任意のヘルプを表示します。 help() を引数なしで起動するとオンラインのヘルプユーティリティに入ります。ここから関数名やクラス名、モジュール名をタイプすることで、それらのヘルプテキストを読むことが出来ます。 (Contributed by Guido van Rossum, using Ka-Ping Yee's pydoc module.)

Various bugfixes and performance improvements have been made to the SRE engine underlying the re module. For example, the re.sub() and 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 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.)

smtplib モジュールに RFC 2487 [https://datatracker.ietf.org/doc/html/rfc2487.html] 「Secure SMTP over TLS」のサポートが追加されました。これにより Python プログラムとメール転送エージェント間でのメッセージの暗号化された SMTP トラフィックが可能になりました。 smtplib は SMTP 認証もサポートしています。 (Contributed by Gerhard Häring.)

Piers Lauder によって保守されている imaplib モジュールに新たに多くの拡張のサポートが追加されました: RFC 2342 [https://datatracker.ietf.org/doc/html/rfc2342.html] で定義されている NAMESPACE 拡張、 SORT、 GETACL、 SETACL。(Contributed by Anthony Baxter and Michel Pelletier.)

The rfc822 module's parsing of email addresses is now compliant with RFC 2822 [https://datatracker.ietf.org/doc/html/rfc2822.html], an update to RFC 822 [https://datatracker.ietf.org/doc/html/rfc822.html]. (The module's name is not going to be changed to rfc2822.) A new package, email, has also been added for parsing and generating e-mail messages. (Contributed by Barry Warsaw, and arising out of his work on Mailman.)

The difflib module now contains a new Differ class for producing human-readable lists of changes (a "delta") between two sequences of lines of text. There are also two generator functions, ndiff() and 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.)

New constants ascii_letters, ascii_lowercase, and ascii_uppercase were added to the string module. There were several modules in the standard library that used string.letters to mean the ranges A-Za-z, but that assumption is incorrect when locales are in use, because string.letters varies depending on the set of legal characters defined by the current locale. The buggy modules have all been fixed to use ascii_letters instead. (Reported by an unknown person; fixed by Fred L. Drake, Jr.)

The mimetypes module now makes it easier to use alternative MIME-type databases by the addition of a MimeTypes class, which takes a list of filenames to be parsed. (Contributed by Fred L. Drake, Jr.)

A Timer class was added to the threading module that allows scheduling an activity to happen at some future time. (Contributed by Itamar Shtull-Trauring.)

インタプリタの変更と修正

Python 拡張モジュールを書いたり、インタプリタの埋め込みをしたり、あるいは単にインタプリタそのものをハックしたりするために C レベルでインタプリタを扱う人々以外には影響しないいくつかの変更があります。Python コードを書くだけであればここに記述する変更は、あなたに関係するものは全くありません。

プロファイルとトレースの関数が C で実装されました。Python ベースのものと比較して圧倒的に高速に操作出来、プロファイルとトレースのオーバヘッドを削減するはずです。これは Python の開発環境の著者に朗報でしょう。2 つの C 関数、 PyEval_SetProfile() と PyEval_SetTrace() が Python API に追加されました。既存の sys.setprofile() 関数、 sys.settrace() 関数はそのまま存在し、単純に新規 C レベル関数を使うように修正されました。 (Contributed by Fred L. Drake, Jr.)

もうひとつ、主として Python デバッガ、開発ツールの実装者にとって興味深い低レベル API が追加されています。 PyInterpreterState_Head() と PyInterpreterState_Next() は呼び出し可能オブジェクトに、存在しているインタプリタのオブジェクト全てを渡り歩かせます。 PyInterpreterState_ThreadHead() と PyThreadState_Next() は与えられたインタプリタについてのスレッド状態全てに渡るループを可能にしています。 (Contributed by David Beazley.)

ガーベージコレクタの C レベルインターフェイスが変更されています。これはガーベージコレクションをサポートする拡張型を書いたり、関数の利用誤りのデバッグをするのを簡単にします。多数の関数が少々これまでとは異なったセマンティクスを持つので、関数群がリネームされました。旧 API を使う拡張はこれまで通りコンパイルは出来ますが、ガーベージコレクションには参加 出来ません 。このため 2.2 のためにはかなり高優先度で更新を検討すべきです。

拡張モジュールを新 API でアップグレードするには、以下のステップを実施してください:

Rename Py_TPFLAGS_GC to Py_TPFLAGS_HAVE_GC.

オブジェクトのアロケートには PyObject_GC_New() または PyObject_GC_NewVar() を使ってください。

そしてオブジェクトのデアロケートには PyObject_GC_Del() を使ってください。

Rename PyObject_GC_Init() to PyObject_GC_Track() and PyObject_GC_Fini() to PyObject_GC_UnTrack().

Remove PyGC_HEAD_SIZE from object size calculations.

Remove calls to PyObject_AS_GC() and PyObject_FROM_GC().

PyArg_ParseTuple() に新たな書式化シーケンス et が追加されました。 et はパラメータとエンコーディング名の両方を取りパラメータを与えられたエンコーディングで変換しますが、パラメータが Unicode である場合には変換し、8 ビット文字列である場合にはこれが既に望みのものであることと仮定してそのままにします。このことは es 書式化文字が 8 ビット文字列は Python デフォルトの ASCII エンコーディングであると仮定して新たに与えられたエンコーディングで変換するのとは違っています。 (Contributed by M.-A. Lemburg, and used for the MBCS support on Windows described in the following section.)

A different argument parsing function, 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 PyObject* variables that will be filled in with argument values.

Two new flags METH_NOARGS and 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 METH_VARARGS. Also, the old METH_OLDARGS style of writing C methods is now officially deprecated.

Two new wrapper functions, PyOS_snprintf() and PyOS_vsnprintf() were added to provide cross-platform implementations for the relatively new snprintf() and vsnprintf() C lib APIs. In contrast to the standard sprintf() and vsprintf() functions, the Python versions check the bounds of the buffer used to protect against buffer overruns. (Contributed by M.-A. Lemburg.)

_PyTuple_Resize() 関数の未使用パラメータを取り除いたので、今後は 3 つではなく 2 つのパラメータを取ります。3 つ目の引数は一度も使われることはなかったため、Python 2.2 以前のコードからの移植時には単純に捨てることが出来ます。

その他の変更と修正

いつものように、たくさんのほかの改善とバグフィックスがソースツリー全体に渡って散らばっています。CVS 変更ログを検索すると、Python 2.1 から 2.2 にかけて適用されたパッチは 527、バグ修正は 683、2.2.1 で適用されたパッチは 139、バグ修正は 143、2.2.2 で適用されたパッチは 106、バグ修正は 82。いずれも少なく見積もって、です。

ほかの、さらに特筆すべき変更のいくつかを挙げます:

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 --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 /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 setup.py. People who want to experiment with these modules can uncomment them manually.

キーワード引数を取らないビルトイン関数にそれを渡すと、メッセージ "function takes no keyword arguments" を伴う TypeError 例外を励起するようになりました。

Python 2.1 で拡張モジュールとして追加された弱参照は、今では Python 中核の一部です。これは新スタイルクラスの実装のために使われるからです。このため weakref モジュールにいた ReferenceError 例外をビルトイン例外に移動しました。

Tim Peters による新しいスクリプト Tools/scripts/cleanfuture.py は、Python ソースコードから自動的に廃止された __future__ 文を削除します。

ビルトイン関数 compile() に flags 引数が追加され、これにより __future__ ステートメントの振る舞いが、IDLE 内やほかの開発環境内にある模擬的なシェル内で正しく準拠するようになりました。この変更は PEP 264 [https://peps.python.org/pep-0264/] に記述されています。 (Contributed by Michael Hudson.)

Python 1.6 で導入された新ライセンスは GPL 互換ではありませんでした。2.2 ライセンスのためにいくつか小さな字句的修正によりこれをフィックスし、GPL プログラム内に Python を埋め込むことが再び合法になりました。Python そのものは GPL ではなく、かつても今後も BSD ライセンスに本質的に等価なものであることに注意してください。このライセンスの変更は Python 2.0.1 リリース、2.1.1 リリースにも適用されました。

Windows において Unicode ファイル名がある場合に、Python はそれを Microsoft ファイル API を使うことで MBCS 文字列に変換するようになりました。MBCS はそのファイル API によって明示的に使われるので、デフォルトのエンコーディングとして Python が ASCII を選択するのは苛立たしいことがわかりました。Unix においては locale.nl_langinfo(CODESET) が利用可能であればロケールの文字セットが使われます。 (Windows support was contributed by Mark Hammond with assistance from Marc-André Lemburg. Unix support was added by Martin von Löwis.)

Windows でのラージファイルのサポートが有効になりました。 (Contributed by Tim Peters.)

Tools/scripts/ftpmirror.py スクリプトが、もしあれば、 .netrc ファイルを読むようになりました。 (Contributed by Mike Romberg.)

Some features of the object returned by the xrange() function are now deprecated, and trigger warnings when they're accessed; they'll disappear in Python 2.3. xrange objects tried to pretend they were full sequence types by supporting slicing, sequence multiplication, and the in operator, but these features were rarely used and therefore buggy. The tolist() method and the start, stop, and step attributes are also being deprecated. At the C level, the fourth argument to the PyRange_New() function, repeat, has also been deprecated.

辞書実装に対するパッチの束がありました。ほとんどが、辞書にこっそりとそのハッシュ値を変更するオブジェクトを含んでいたり、それが含まれる辞書を変更する場合に潜在的にコアダンプしていたことに対する修正です。Michael Hudson がコアダンプするケースを見つけて python-dev に穏やかなリズムで報告している間に Tim Peters がバグをフィックスし、 Michael がまた別のケースを見つけ、ということを繰り返しました。

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

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

ファイル名が .pyw で終わるものが Windows でインポート出来るようになりました。 .pyw は Windows のみのものであり、スクリプトが PYTHON.EXE ではなく PYTHONW.EXE を使って実行されることを示すのに使われます。これは出力のために DOS コンソールがポップアップしてしまうのを避けるのに使われます。このパッチはそのようなスクリプトを、それがモジュールとしても利用可能であるケースでインポート出来るようにします。 (Implemented by David Bolen.)

Python が C の dlopen() 関数を拡張モジュールのロードに用いるプラットフォームにおいて、 dlopen() で使われるフラグを sys.getdlopenflags() 関数と sys.setdlopenflags() 関数でセット出来るようになりました。 (Contributed by Bram Stolk.)

組み込み関数 pow() はもはや浮動小数点数の際の 3 番目の引数をサポートしません。 pow(x, y, z) は (x**y) % z を返しますが、浮動小数点の場合はこれは決して役には立ちません。最終結果はプラットフォーム依存で予測不可能なものになります。 pow(2.0, 8.0, 7.0) のような呼び出しは、 TypeError 例外を発生させるようにしました。

謝辞

著者は提案の申し出や修正、様々なこの記事の草稿の助けをしてくれた以下の人々に感謝します: 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.

What's New in Python 2.1

著者:

A.M. Kuchling

はじめに

この記事はPython 2.1の新機能について説明します。Python 2.1には Python 2.0ほど多くの変更点はありませんが、楽しい驚きがあります。2.1はPythonの拡張計画（PEP）を使い動かす最初のリリースであり、大きい変更点のほとんどは、より詳細なドキュメントや変更のための設計原理を提供するPEPに付随しています。この記事は新機能について網羅していませんが、Pythonプログラマのための新機能について概要を示します。特に興味のある任意の新機能の詳細については、Python 2.1ドキュメントか特定のPEPを参照してください。

Python開発チームの最近の目標の一つとして新しいリリースのペースを上げており、一つのリリースにつき6～9ヶ月ごとにリリースしています。2.1はこの速いペースになって出てきた最初のリリースで、初のアルファ版は、2.0の最終版がリリースされた3ヶ月後の1月に登場しました。

Python 2.1の最終版は2001年4月17日に作成されました。

PEP 227: 入れ子状のスコープ

Python2.1における最も大きな変更点はPythonのスコープルールです。Python2.0では、ある指定された時点である変数の名前を検索するために多くても3つの名前空間、つまりローカル、モジュールレベル、ビルトイン名前空間しか使われませんでした。このことは直感的な期待と一致せずしばしば人々を驚かせました。例えば、入れ子になった再帰関数の定義は動きません:

def f():
    ...
    def g(value):
        ...
        return g(value-1) + 1
    ...

The function g() will always raise a NameError exception, because the binding of the name 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 lambda expression clumsier, and this was a problem in practice. In code which uses lambda you can often find local variables being copied by passing them as the default values of arguments.

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

過度な関数型スタイルで書かれた Python コードの可読性は、結果的にはひどく苦痛を感じるものですね。

Python 2.1の最も重要な変更点は、この問題を解決するために静的なスコープが追加されたことです。最初の効果として、name=name という例ではデフォルトの引数は必要ありません。簡単に言えば、指定された引数名が関数内の値に割り当てられない場合(def、class または import ステートメントの割り当てによって)、変数の参照は外側のスコープのローカル名前空間で検索されます。ルールや実装の詳細はPEPで参照できます。

この変更は、同じ変数名がモジュールレベルと関数の定義が含まれている関数内のローカルの両方で変数名として使用されているコードで、互換性の問題を引き起こす可能性があります。ですがむしろ気にしなくてよいでしょう。そのようなコードはそもそも最初から相当こんがらかっているので。

この変更の副作用の一つは、 from module import * と exec の両ステートメントが特定の条件下の関数スコープ内で不正となることです。 Python のリファレンスマニュアルははじめからずっと from module import * はトップレベルモジュールでのみ合法であると言ってきましたが、以前の CPython インタプリタはこれを一度も強制していませんでした。入れ子になったスコープ実装の一環として、Python のソースをバイトコードに変換するコンパイラは、内包されたスコープ内の変数にアクセスするために別のコードを生成する必要があります。 from module import *, exec はコンパイラにこれを理解することを不可能にしてしまいます。なぜならそれらはコンパイル時にはわからないローカル名前空間に名前を追加するからです。それゆえ、もし関数が関数定義を含んだり自由な変数に lambda の語句を含んだりする場合、コンパイラは SyntaxError 例外を上げて知らせます。

前述した説明を少し明確にするため、例を挙げます:

x = 1
def f():
    # The next line is a syntax error
    exec 'x=2'
    def g():
        return x

Line 4 containing the exec statement is a syntax error, since exec would define a new local variable named x whose value should be accessed by g().

これは実際には大した制約でもないはずです。 exec が Python コードで使われるのは稀です(使われているとしたら大抵どこか貧弱な設計であることの証)。

互換性の問題が考慮されて、入れ子のスコープは段階的導入につながりました; Python 2.1 ではそれらはデフォルトで有効になっていませんが、 PEP 236 [https://peps.python.org/pep-0236/] に記載されているように、future 文を使用してモジュール内でオンにすることができます。(PEP 236 [https://peps.python.org/pep-0236/] の更なる議論について、続くセクションを参照してください。) Python 2.2では入れ子になったスコープがデフォルトになり、それをオフにする方法はありませんが、ユーザは 2.1 の全ライフタイムを通して、導入の結果起きるあらゆる破損を修正し続けるでしょう。

参考

PEP 227 [https://peps.python.org/pep-0227/] - 静的に入れ子になったスコープ

Jeremy Hylton著、実装

PEP 236: __future__ 指示文

ネストされたスコープへのこの対応は、リリース 2.1 ではコードを壊すことの危険性について広く懸念されており、 Pythoneer 達に保守的なアプローチを選ばせるには十分でした。このアプローチは、必須とするリリース N+1 に対する、 リリース N でのオプション機能として有効化という序奏、というものです。

この構文は __future__ という名の予約モジュールを使う from...import ステートメントを使用します。ネストしたスコープは以下のステートメントで有効にできます。

from __future__ import nested_scopes

普通 の import ステートメントに見えますが、実は違います; このような未来のステートメントが置かれる場所には厳格なルールがあります。これらはモジュールの冒頭にしか置けませんし、必ず何らかのPythonコードや正規の import ステートメントの前になければなりません。それと言うのもこのようなステートメントは、Pythonのバイトコードコンパイラがコードを解析し、バイトコードを生成する方法に影響しますので、生成されるバイトコードとなるステートメントの前になくてはならないのです。

参考

PEP 236 [https://peps.python.org/pep-0236/] - バック・トゥ・ザ・ __future__

Tim Peter著、Jeremy Hylton主実装

PEP 207: 拡張比較

In earlier versions, Python's support for implementing comparisons on user-defined classes and extension types was quite simple. Classes could implement a __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.

Python2.1で、このニーズを満たすために拡張比較が追加されました。Pythonのクラスは、<、<=、>、>=、==、!= の各演算を個別にオーバーロードできます。この新しい特殊メソッドの名前は:

演算

メソッド名

<

__lt__()

<=

__le__()

>

__gt__()

>=

__ge__()

==

__eq__()

!=

__ne__()

(特殊メソッドはFortranの .LT. や .LE. 等々の演算子にちなんで命名されています。プログラマはほぼ確実にこれらの名前を熟知していますので、覚えやすいでしょう。)

これらの特殊メソッドは method(self, other) の形式になっており、self が演算子の左辺、other が右辺のオブジェクトになります。例えば、式 A < B は A.__lt__(B) を呼び出します。

これらの特殊メソッドは何でも、つまり真偽値や行列、リストや他のPython オブジェクトを返せます。もし比較が不可能であったり、矛盾していたり、意味がない場合は、代わりに例外を上げることができます。

The built-in 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 "<", "<=", ">", ">=", "==", or "!=". If called without the optional third argument, 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.

C プログラマにとって興味深い関連する変更があります。型オブジェクトに新しい tp_richcmp スロットと、この拡張された比較を行うAPIが追加されました。ここではC APIについて言及しませんが、あながた関連する関数のリストを見たければ、 PEP 207 [https://peps.python.org/pep-0207/] かバージョン2.1のC APIドキュメントを参照してください。

参考

PEP 207 [https://peps.python.org/pep-0207/]: 拡張比較

David Ascher によるかつての仕事に大きく拠りますが Guido van Rossum によって著され、実装されました。

PEP 230: 警告フレームワーク

10 年の間に、Python は途中で廃止されたモジュールと機能の特定の番号を蓄積してきました。どれだけのコードが活用されているか知る術はないので、機能を削除して問題ないか把握することは困難です。その機能に依存するプログラムは一つもないかもしれませんし、たくさんあるかもしれません。より構造化された方法で古い機能を削除できるようにするために、警告のフレームワークが追加されました。Python の開発者がある機能を取り除きたいときは、まずは Python の次のバージョンで警告を引き起こします。続く Python バージョンで開発者はその機能を削除出来、ユーザは古い機能の使用を取り除くために Python リリースサイクル一つ丸々使えます。

Python 2.1 はこのスキームで使われる警告フレームワークを追加します。また、警告の表示機能や表示させたくない警告を除外する機能を提供する、 warnings モジュールを追加します。サードパーティーのモジュールはまた、彼らがサポート対象外にしたい古い機能を非推奨と知らしめるのにこのフレームワークを利用できます。

For example, in Python 2.1 the regex module is deprecated, so importing it causes a warning to be printed:

>>> import regex
__main__:1: DeprecationWarning: the regex module
         is deprecated; please use the re module
>>>

警告は warnings.warn() 関数を呼び出すことで発行できます:

warnings.warn("feature X no longer supported")

最初のパラメータは警告メッセージです。任意追加のパラメータは、特定の警告カテゴリを指定するために利用することができます。

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 regex module and not want to spare the time to convert it to use the re module right now. The warning can be suppressed by calling

import warnings
warnings.filterwarnings(action = 'ignore',
                        message='.*regex module is deprecated',
                        category=DeprecationWarning,
                        module = '__main__')

This adds a filter that will apply only to warnings of the class DeprecationWarning triggered in the __main__ module, and applies a regular expression to only match the message about the 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).

関数は、警告を発行するための Python の C API にも追加されました。詳細については PEP 230 または Python の API ドキュメントを参照してください。

参考

PEP 5 [https://peps.python.org/pep-0005/] - 言語の進化のためのガイドライン

Python から古い機能を削除する時に従うべき手順を示すため、 Paul Prescod により書かれました。当 PEP に記載された方針は正式に採用されていませんが、最終的な方針も Prescod の提案とおそらくさほど違いはないでしょう。

PEP 230 [https://peps.python.org/pep-0230/] - 警告フレームワーク

Guido van Rossum 著、実装

PEP 229: 新しいビルドシステム

Python のコンパイル時、ユーザはソースツリーの中に入って、様々な追加モジュールを有効にするために Modules/Setup ファイルを編集しなければなりませんでした; デフォルトのセットは比較的小さくて、ほとんどの Unix プラットフォームで、コンパイルするモジュールを制限しています。これは、特に Linux に顕著ですが、たくさんの追加機能を持った Unix プラットフォームでは、Python インストレーションはしばしば、そう出来るのに有用なモジュールを全く含まない、といったことが起こることを意味しています。

Python 2.0 は、配布と拡張のインストールをするためのモジュールのセットである Distutils を追加しました。Python 2.1 では Distutils を、たくさんの拡張モジュールの標準ライブラリを、サポートする機器かどうかを自動検出してコンパイルするのに使っています。これが Python インストレーションをより簡単に、より機能的とするものであることが期待されています。

モジュールを有効化するために Modules/Setup を編集する必要性の代わりに、Python ソースツリーのトップレベルディレクトリにある setup.py スクリプトがビルド時に実行され、システムのモジュールとヘッダファイルを調べることによって、どのモジュールが有効に出来るのかを検出しようと試みます。モジュールが Modules/Setup 内でそう構成されていれば、 setup.py スクリプトはそのモジュールをコンパイルしようとはせずに Modules/Setup ファイル内容に従います。これは特定のプラットフォームで必要となるヘンチクリンなコマンドラインフラグやライブラリフラグを特定する手段も与えてくれます。

もう一つの大きなビルド機構の変更点は Neil Schemenauer による再構成で、今や Python は、トップディレクトリと Python/, Parser/, Objects/, Modules/ サブディレクトリにあった別々の Makefile が再帰的にビルドする代わりに、再帰をしないトップレベルの単一 makefile を使うようになっています。このことで Python のビルドは速くなり、 Makefile をもてあそぶのが単純明快になっています。

参考

PEP 229 [https://peps.python.org/pep-0229/] - Distutils を使った Python のビルド

A.M. Kuchling 著、実装

PEP 205: 弱参照

weakref モジュールを通して利用出来る弱参照(weak references)は、ささやかですが有用な、Python プログラマの道具箱に新たに加わったデータ型です。

オブジェクトへの参照(辞書内やリスト内を思い浮かべてください)を記憶しておくということは、オブジェクトを生き永らえさせるという副作用を持っています。少しばかりの、この振る舞いが望ましくない特殊なケースがあります。オブジェクトのキャッシュがその最もありがちな一つで、もう一つはツリーのようなデータ構造での循環参照です。

例えば、他の関数 f(x) の結果を、その関数の引数と結果を辞書に格納することでキャッシュするメモライジング関数を考えてみましょう。

_cache = {}
def memoize(x):
    if _cache.has_key(x):
        return _cache[x]

    retval = f(x)

    # Cache the returned object
    _cache[x] = retval

    return retval

This version works for simple things such as integers, but it has a side effect; the _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 f() returns an object, or a data structure that takes up a lot of memory, this can be a problem.

弱参照は、オブジェクトをその時間を超えて生き永らえさせたくないキャッシュの実装のための手段を提供します。オブジェクトがアクセス出来るのが弱参照からのみである場合、そのオブジェクトは解放されて、その弱参照は参照しているそのオブジェクトがもはや存在しないことを表明します。オブジェクト obj への弱参照を作るには、 wr = weakref.ref(obj) とします。参照されているオブジェクトは、それがあたかも関数であったかのように弱参照を「コール」することで得ます: wr() 。それは参照されたオブジェクトを返すか、もう存在していないのであれば None を返します。

This makes it possible to write a memoize() function whose cache doesn't keep objects alive, by storing weak references in the cache.

_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

The 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 weakref.ReferenceError exception to be raised.

proxy = weakref.proxy(obj)
proxy.attr   # Equivalent to obj.attr
proxy.meth() # Equivalent to obj.meth()
del obj
proxy.attr   # raises weakref.ReferenceError

参考

PEP 205 [https://peps.python.org/pep-0205/] - 弱参照

Fred L. Drake, Jr. 著、実装

PEP 232: 関数の属性

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

ついに関数に、任意の属性をセットし、取り出すことが出来るようになりました。普通の Python 構文で出来ます:

def f(): pass

f.publish = 1
f.secure = 1
f.grammar = "A ::= B (C D)*"

The dictionary containing attributes can be accessed as the function's __dict__. Unlike the __dict__ attribute of class instances, in functions you can actually assign a new dictionary to __dict__, though the new value is restricted to a regular Python dictionary; you can't be tricky and set it to a UserDict instance, or any other random object that behaves like a mapping.

参考

PEP 232 [https://peps.python.org/pep-0232/] - 関数の属性

Barry Warsaw 著、実装

PEP 235: 大文字小文字を区別しないプラットフォームでのモジュールの読み込み

いくつかのオペレーティングシステムは、大小文字区別に無関心なファイルシステムを持っています。MacOS と Windows がその代表例です。それらシステムにおいてはファイル名 FILE.PY と file.py の区別が出来ません。たとえそれが元のファイル名を尊重して格納出来たとしてもです(それらは大小文字維持、でもあります)。

Python 2.1 では import 文が、case-insensitive (大小文字に無関心)なプラットフォームで case-sensitivity (大小文字への繊細さ)をシミュレートして動作します。Python は今や、まずはデフォルトで case-sensitive なマッチによる検索をし、それで見つからなければ ImportError を投げます。ですから import file は FILE.PY をインポートしません。case-insensitive マッチングは Python インタプリタ開始前に環境変数 PYTHONCASEOK をセットすることで要求出来ます。

PEP 217: 対話モード用 Display Hook

Python インタプリタを対話的に使う際には、コマンドの出力結果表示にはビルトインの repr() 関数が使われます。Python 2.1 ではこの repr() の代わりに呼び出される呼び出し可能オブジェクトを、 sys.displayhook() 変数にセット出来ます。たとえば特別な pretty- printing 関数をセット出来ます:

>>> # Create a recursive data structure
... L = [1,2,3]
>>> L.append(L)
>>> L # Show Python's default output
[1, 2, 3, [...]]
>>> # Use pprint.pprint() as the display function
... import sys, pprint
>>> sys.displayhook = pprint.pprint
>>> L
[1, 2, 3,  <Recursion on list with id=135143996>]
>>>

参考

PEP 217 [https://peps.python.org/pep-0217/] - Display Hook の対話的な使用

Moshe Zadka 著、実装

PEP 208: 新しい型強制モデル

数値強制が C レベルでどのようになされるかについての修正は、とても大きなものでした。これは Python の C 拡張の著者にのみ影響し、数値操作をサポートする拡張型を書くのをより柔軟にするものです。

拡張型はその PyTypeObject 構造体に、新しい型強制モデルをサポートすることを示すために Py_TPFLAGS_CHECKTYPES フラグをセット出来るようになりました。そのような拡張型内では、数値的スロット関数は 2 つの引数が同じ型であることを仮定しなくなります。代わりに、2 つの引数が異なる型を渡せて、内部的に型変換を実行出来ます。スロット関数にそれが処理出来ない型が渡された場合は、それが失敗であることを表すために Py_NotImplemented シングルトン値への参照を返せます。この場合他の数値関数が試されて、おそらく操作を実行出来ます。それでも Py_NotImplemented を返すなら TypeError が送出されます。Python で書かれた数値メソッドも Py_NotImplemented を返せます。この場合インタプリタはメソッドが存在しないものとして振舞います。 (おそらく TypeError が投げられたり、オブジェクトのほかの数値メソッドが試されます。)

参考

PEP 208 [https://peps.python.org/pep-0208/] - 型強制モデルの手直し

Neil Schemenauer により著され、実装されましたが、大変多くを Marc-André Lemburg による以前の仕事に拠っています。C レベルで今では数値操作がどのように処理されるようになったかの細かい点を理解したければ、これを読んで下さい。

PEP 241: Pythonソフトウェアパッケージのためのメタデータ

Python ユーザーからのよくある苦情としては、存在するすべての Python モジュールの一覧がないということです。T. Middleton's の www.vex.net/parnassus/ にあった Vaults of Parnassus (2009年2月に停止、Internet Archive Wayback Machine <https://web.archive.org/web/20090130140102/http://www.vex.net/parnassus/>`_ で閲覧可) が最大のものでしたが、ソフトウェアの登録は任意だったため、多くの人は登録しませんでした。

この問題をどうにかするための最初の小さな一歩として、Distutils の sdist コマンドを使ってパッケージ化する Python ソフトウェアに PKG-INFO と名付けられたファイルを含むようにしました。これには名前、バージョン、著者 (カタログ化の用語ではメタデータ) のような情報を含んでいます。 PEP 241 [https://peps.python.org/pep-0241/] が PKG-INFO ファイルに持てるフィールドの完全なリストを記述しています。Python 2.1 を使ったソフトウェアをパッケージ化し始めた人々によってパッケージがどんどんメタデータを含み、自動的なカタログ化システムを構築し、それを実験することが出来るようになります。その結果の経験により、おそらく本当に良いカタログを設計出来、Python 2.2 でそのサポートを構築出来るでしょう。例えば Distutils の sdist コマンドと bdist_* コマンド群はあなたのパッケージをカタログサーバに自動的にアップロードする upload オプションをサポート出来るでしょう。

PKG-INFO を含んだパッケージの作成は Python 2.1 を使っていなくても開始することが出来ます。Distutils の新しいリリースが以前のバージョンの Python ユーザ向けにも作られているからです。Distutils のバージョン 1.0.2 が、多数のバグフィックスや拡張とともに、 PEP 241 [https://peps.python.org/pep-0241/] の変更を含んでいます。これは https://www.python.org/community/sigs/current/distutils-sig/ にある Distutils SIG から入手可能です。

参考

PEP 241 [https://peps.python.org/pep-0241/] - Pythonソフトウェアパッケージのためのメタデータ

A.M. Kuchling 著、実装

PEP 243 [https://peps.python.org/pep-0243/] - レポジトリアップロードモジュールのメカニズム

Sean Reifschneider により著されました。このドラフト PEP は中央サーバに Python パッケージをアップロードする機構について提案しています。

新しいモジュールと改良されたモジュール

Ka-Ping Yee contributed two new modules: inspect.py, a module for getting information about live Python code, and pydoc.py, a module for interactively converting docstrings to HTML or text. As a bonus, Tools/scripts/pydoc, which is now automatically installed, uses pydoc.py to display documentation given a Python module, package, or class name. For example, pydoc xml.dom displays the following:

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

pydoc には TK ベースの対話的ヘルプブラウザも含まれています。 pydoc はすぐに病みつきになります。お試しあれ。

Two different modules for unit testing were added to the standard library. The 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 https://pyunit.sourceforge.net/ for more information about PyUnit.

The difflib module contains a class, 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 diff program, and in fact the sample program Tools/scripts/ndiff.py demonstrates how to write such a script.

curses.panel はパネルライブラリへのラッパーであり、ncurses と SYSV curses の一部であり、 Thomas Gellekum により寄稿されました。パネルライブラリは深さ(depth)の追加機能を持つウィンドウを提供しています。ウィンドウは深さ順での高い方、低い方に移動出来、パネルライブラリはパネルがどこで重なるか、区域のどちらが可視かを理解します。

The PyXML package has gone through a few releases since Python 2.0, and Python 2.1 includes an updated version of the 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 minidom module.

Ka-Ping Yee は未捕捉の例外を処理するもうひとつのフックも寄稿しました。 sys.excepthook() には呼び出し可能オブジェクトをセット出来ます。例外がどの try...except にも捕捉されない場合に、例外は sys.excepthook() に通されて、そこで好きなことを何でも出来ます。9 回目の Python カンファレンスにおいて、Ping はこのフックを使ったアプリケーションのデモを行いました。そこでは、スタックフレームを列挙するだけでなくそれぞれのフレームでの関数の引数とローカル変数の列挙も行う拡張トレースバックの表示をしていました。

Various functions in the time module, such as asctime() and 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, time.asctime() can be used, instead of the lengthier time.asctime(time.localtime(time.time())) that was previously required.

この変更は Thomas Wouters により提案され、実装されました。

ftplib モジュールがデフォルトでパッシブモードでファイルを取得するようになりました。これはパッシブモードがファイアウォール配下ではより良く動作するようだからです。この要望は Debian のバグトラッキングシステムから起こりました。ほかの Debian パッケージがファイル取得に ftplib を使い、ファイアウォールの元で動作しなかったのです。このことが誰かの問題になるとは思えません。Netscape のデフォルトがパッシブモードですし、苦情を言う人々も稀でした。ですがもしもパッシブモードがあなたのアプリケーションやネットワーク構成にとって不適切である場合には、FTP オブジェクトの set_pasv(0) を呼び出して、パッシブモードを無効にしてください。

socket モジュールに、Grant Edwards により寄稿された、生のソケットへのアクセスのサポートが追加されました。

pstats モジュールに、Python プログラムの時間計測プロファイルを表示する単純な対話的統計ブラウザが含まれるようになり、これはモジュールがスクリプトとして実行された場合に呼び出されます。Eric S. Raymond によって寄稿されました。

実装依存の関数ですが sys._getframe([depth]) が、現在の呼び出しスタックより、指定したフレームオブジェクトを返すものとして追加されました。 sys._getframe() は呼び出しスタックの一番上のフレームを返します。オプショナルな整数引数 depth を与えると、関数はスタックの一番上から下 depth ぶんの呼び出しのフレームを返します。例えば sys._getframe(1) は呼び出し元のフレームオブジェクトを返します。

この関数は CPython のみに含まれ、 Jython や .NET 実装にはありません。デバッグのためだけに用い、製品コード内にこれを書いてしまう誘惑に打ち克ってください。

その他の変更と修正

短めのリリースサイクルだったため Python 2.1 では比較的少ない変更でした。CVS 変更ログの検索では 117 のパッチ適用と 136 のバグフィックスが見つかります。ともに少なく見積もっています。いくつかの注目に値する変更を紹介します:

A specialized object allocator is now optionally available, that should be faster than the system malloc() and have less memory overhead. The allocator uses C's malloc() function to get large pools of memory, and then fulfills smaller memory requests from these pools. It can be enabled by providing the --with-pymalloc option to the configure script; see 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 malloc() and 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 malloc() and free() any more, and calling the wrong function to free memory will get you a core dump. For example, if memory was allocated using PyMem_New, it has to be freed using PyMem_Del(), not 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.

オブジェクトアロケータは Vladimir Marangozov により寄稿されました。

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 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 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, xreadlines(), is similar to the existing xrange() built-in. 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 readlines() method does. You'd use it like this:

for line in sys.stdin.xreadlines():
    # ... do something for each line ...
    ...

ライン I/O の変更についての詳しい説明は、 https://mail.python.org/pipermail/python-dev/2001-January/ にある 2001 年 1 月 1--15 日の python-dev のまとめをご覧ください。

A new method, 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. D.popitem() removes a random (key, value) pair from the dictionary 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.

from module import * を使ってインポートする際にインポートされる名前を制御出来るようになりました。インポートされるべき名前のリストを含む __all__ 属性を定義することでこれを行えます。一つのよくある不平が、 sys や string のように、ほかのモジュールをモジュールがインポートする場合に、 from module import * がインポートしているモジュールの名前空間内にそれらを追加することです。これをフィックスするには、 __all__ に公開名を単に列挙します:

# List public names
__all__ = ['Database', 'open']

このパッチのより厳密な版が最初に示唆されて Ben Wolfson により実装されましたが、python-dev でのいくつかの議論を経てからより弱い最終版がチェックインされました。

文字列に repr() を適用するとこれまでは表示出来ない文字について、8 進エスケープが使われていました。例えば改行コードは '\012' でした。これは Python の起源である C に追従した名残ですが、こんにちでは普段使いで 8 進エスケープが使われることは非常に少なくなりました。Ka-Ping Yee が 8 進の代わりに 16 進を使いつつ相応の文字には \n, \t, \r などのエスケープを使うよう示唆し、この新しい書式化を実装しました。

コンパイル時点で検出される構文エラーがエラーとなったファイル名と行番号を含む例外を送出できるようになり、またこれによりコンパイラの再編成という喜ばしい副作用がありました。Jeremy Hylton により達成されました。

C extensions which import other modules have been changed to use 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.

Unicode 文字データベースのサイズが Fredrik Lundh のおかげでさらに 340K だけ小さくなりました。

いくつかの新たなポートの寄与: MacOS X (by Steven Majewski), Cygwin (by Jason Tishler); RISCOS (by Dietmar Schwertberger); Unixware 7 (by Billy G. Allie).

そしてよくあるマイナーなバグフィックス、マイナーなメモリリーク、ドキュメンテーション文字列の編集やほかの微調整があり、全てを列挙するには長過ぎます。もし見たいのであれば、CVS ログで完全な詳細を読んで下さい。

謝辞

著者は提案の申し出や修正、様々なこの記事の草稿の助けをしてくれた以下の人々に感謝します: Graeme Cross, David Goodger, Jay Graves, Michael Hudson, Marc-André Lemburg, Fredrik Lundh, Neil Schemenauer, Thomas Wouters.

What's New in Python 2.0

著者:

A.M. Kuchling and Moshe Zadka

はじめに

新 Python リリース、バージョン 2.0 は、2000 年 10 月 16 日にリリースされました。この記事では 2.0 のエキサイティングな新機能をカバーし、いくつかの有用な変更点をハイライトし、少しの、コードの書き換えを要する互換性のない変更点について指摘します。

Python の開発は、リリースとリリースの間で止まることはなく、バグフィックスと改善はとめどなく、日夜提出されます。多くのマイナーフィックス、少しの最適化、ドキュメンテーション文字列の追加、より良いエラーメッセージが 2.0 に仲間入りしました。これら全てを列挙するのは不可能ですが、それは確かに大事でしょう、全てのリストを見たければ、公に入手可能な CVS ログを調べてください。この前進は、今やバグ修正に日々を費やすことで報酬を受け取って PythonLabs のために働く 5 人の開発者、それと SourceForge に移行した結果改善されたコミュニケーションのおかげです。

Python 1.6 はいかがですか?

Python 1.6 は「推定的義務」の Python リリースと考えることが出来ます。2000 年 5 月にコア開発チームが CNRI を離れたあと、CNRI は Python にかかる作業全てが CNRI で実施されることを含む 1.6 リリースが作成されることをリクエストしました。それゆえ Python 1.6 は、最も重要な新機能としての Unicode サポートを含む、2000 年 5 月の CVS ツリーの状態と同等です。開発はもちろん 5 月以降も継続されましたので、1.6 ツリーは Python 2.0 との前方互換を保障するために少しの修正を受け取りました。1.6 はですから、Python の進化の一部であり、側枝ではありません。

では、あなたは Python 1.6 に興味を示すべきでしょうか? おそらく答えはノーです。1.6final と 2.0beta1 のリリースは同じ日に行われ (2000 年 9 月 5 日)、Python 2.0 のファイナライズはその一ヶ月かそこらで行われるよう計画されました。もしあなたが保守すべきアプリケーションを持っているならば、1.6 への移行には少しばかりコードの破壊を伴うようです。つまりその修正を行い、一ヶ月の間に 2.0 への移行による別の破壊ラウンドがやってきます。直接 2.0 に移行したほうが良いでしょう。このドキュメントに記載する、ほとんどの面白い機能は 2.0 のみのものであり、なぜならほとんどの作業は、5 月から 9 月の間に行われたからなのです。

新しい開発プロセス

Python 2.0 における最も重要な変化はコードに対するものではまったくなくて、Python がどのように開発されるのかについてでしょう: 2000 年 5 月に Python 開発者たちは、ソースコード格納、バグ報告の追跡、パッチ提出の待ち行列管理のための SourceForge によって利用出来るようになったツールの使用を始めました。Python 2.0 ではバグ報告やパッチの提出には、Python プロジェクトページで利用可能なバグトラッキングとパッチ管理ツールを使ってください。 https://sourceforge.net/projects/python/ にあります(訳注: 2015 年現在の状況は What's New in Python 2.6 参照)。

SourceForge で現在ホストされているサービスの中で最も重要なのは Python CVS ツリーで、Python のソースコードを含む、バージョンコントロールされたレポジトリです。以前までは、CVS ツリーへの書き込み許可を持つ人々が 7 人ほどいて、全てのパッチはその中の一人が精査とチェックをする必要がありました。明らかにこれはスケーラブルではありませんでした。CVS ツリーを SourceForge に移動することで、より多くの人々に書き込み許可を与えることが可能になりました; 2000 年 9 月時点で、27 人の人々が変更をチェックイン出来るようになっていました。これは 4 倍の増加です。これは大規模な変更、これまでであれば小さなコア開発グループによるフィルタを経由しなければならないために試みられなかったような、大規模な変更を可能にしています。例えばある日 Peter Schneider-Kamp は K&R C 互換を落としてしまうことを思い立ち、Python の C ソースを ANSI C に変換しました。python-dev メーリングリストでの承認を得たのち、彼は立て続けにチェックインを開始しておよそ一週間ほどで終わらせ、ほかの開発者たちも手助けに参加し、そして作業は完了しました。書き込み許可が 5 人だけだったならば、おそらくそのタスクはこう見做されたでしょう:「素晴らしい。けれども時間と労力に見合わない」。そして決して実現することはなかったことでしょう。

SourceForge のサービスを使うことへのシフトは、開発の目覚しいスピードアップをもたらしました。パッチはいまや、提出され、コメントされ、提出者以外の別人によって改定されて戻ってきて、などなどが、パッチがチェックインの価値があると判断されるまで行われています。バグは唯一つの中央保管庫で追跡され、修正には特定の誰かを割り当てることが出来、そして私たちはオープンバグを進捗の指標として考えることが出来ます。これは代償なしでは達成しませんでした; 開発者には今や以前よりもたくさんの処理すべき電子メールがあり、より多くメーリングリストに追従しなければならず、そして新しい環境のための特別なツールを要しました。例えば、SourceForge はデフォルトでパッチ提出とバグ報告を電子メールで通知しますが、これは全く助けにならないもので、Ka-Ping Yee はもっと有用なメッセージを送信するための HTML スクリーンスクレイパを書きました。

簡単にコードを追加出来るようになったことは、当初少し苦痛を大きくしました。例えばコードが不十分なままだったり、開発グループからのはっきりとした承諾のないままチェックインされたりするといったことです。浮上してきた承認プロセスは、Apache グループが使っているようなものにいくらか似たものです。開発者たちは +1, +0, -0, -1 というふうにパッチに投票できます; +1 と -1 は承諾、却下を表し、+0 と -0 は、開発者は変更にほとんど興味がないけれどもやや肯定、否定の傾向であることを意味します。Apache モデルからの最も大きな違いは、投票行為は本質的に助言であって、優しい終身独裁者 Guido van Rossum 侯に大衆の民意を伝えるものであることです。彼は投票結果をそれでも無視出来ますし、コミュニティが異論を唱えようが変更を承認したり却下したり出来ます。

実際のパッチの作成は新機能の追加での最後のステップであり、通常、良いデザインを工面する前のタスクと容易に比較出来ます。一方で新機能についての議論はしばしばメーリングリストでの長大なスレッドを巻き起こし、議論に追いつくのが大変になり、そして誰も python-dev の投稿全てを読めません。それゆえに、Python 拡張提案 (Python Enhancement Proposals: PEPs)を書く、相対的に形式ばったプロセスが、始動しました。インターネットの RFC をモデルにしたものです。PEPs は新機能提案を記述した草案文書であり、コミュニティの合意として提案が承認されるか却下されるまで継続的に改定されます。 PEP 1 [https://peps.python.org/pep-0001/] の導入部、"PEP の目的とガイドライン" から引用します:

PEP は Python Enhancement Proposal を意味します。PEP は、Python コミュニティに対して情報を提供する、あるいは Python の新機能について記述する設計文書です。PEP は、機能についての技術的な仕様とその機能の論拠(理論)を簡潔に伝えるべきです。

私たちは PEP が新機能提案にかかる、コミュニティによる問題提起の集積と Python になされる設計決断の文書化のための最上位の機構となることを意図しています。PEP の著者にはコミュニティ内の合意形成を行うこと、反対意見を文書化することの責務があります。

PEP の編集に関するプロセス、様式、体裁についての詳細が PEP 1 [https://peps.python.org/pep-0001/] の残りの部分に書かれています。PEPs は SourceForge 上の Python CVS ツリーで営まれますが Python 2.0 配布物の一部ではなく、 https://peps.python.org/ で HTML 形式で利用可能です。2000 年 9 月時点で PEP 201 [https://peps.python.org/pep-0201/] の "Lockstep Iteration" から PEP 225 の "Elementwise/Objectwise Operators" までの 25 の PEP があります。

Unicode 文字列型

Python 2.0 での最大の新機能は新しい基礎データ型、Unicode 文字列です。Unicode は文字を表現するのに ASCII で使用される 8 ビット数の代わりに 16 ビットを使います。これによって 65,536 の個別の文字がサポート出来ます。(---訳注: Unicode の扱いはまず Python 2.2 で UCS4 が使えるように拡張され(つまり 32 ビットに拡張)、Python 3 では Unicode が唯一の文字列型に変更されています。後者の変更点は非常に大きいですが、クックブックの「Python 2 から Python 3 への移植」に比較的よくまとめられています。---)

最終的な Unicode サポートに関するインターフェイスは、python-dev メーリングリストにおける数え切れない、時として嵐のような議論を経て、Fredrik Lundh によって実装された Unicode 文字列型に基づいて、ほとんどが Marc-André Lemburg によって実装されました。インターフェイスについての詳細な説明は PEP 100 [https://peps.python.org/pep-0100/] 「Python Unicode の統合」に記述されました。今ここでは、Unicode インターフェイスについて、一番重要な点を単純にカバーするだけにしましょう。

Python ソースコード内では Unicode 文字列は u"string" のように書きます。任意の Unicode 文字は新しく追加されたエスケープシーケンスで書きます。 \uHHHH のように書き、 HHHH は 0000 から FFFF までの 4 桁の 16 進表記数です。以前からあるエスケープシーケンス \xHH も使えますし、8 進表記も、 \777 で表現される U+01FF までの文字に使えます。

Unicode 文字列は普通の文字列と全く似ていて、 immutable なシーケンス型です。添え字でアクセス出来、スライス出来ますが、インプレイスに変更することは出来ません。Unicode 文字列は encode( [encoding] ) メソッドを持っていて、これは望みのエンコーディングでエンコードした 8 ビット文字列を返します。エンコーディングは文字列で名前付けられていて、例えば 'ascii', 'utf-8', 'iso-8859-1' のようなものです。コーデック API は、新しいエンコーディングを実装し、Python プログラム全体を通して利用可能となるよう登録するために定義されています。エンコーディングが指定されない場合はデフォルトのエンコーディングは普通 7 ビット ASCII ですが、Python インストレーションにおいて、 site.py のカスタマイズ版内で sys.setdefaultencoding(encoding) を呼び出すことで変更出来ます。

8 ビット文字列と Unicode 文字列を結合すると常に、デフォルトの ASCII エンコーディングを使って Unicode に型変換されます。 'a' + u'bc' の結果は u'abc' になります。

新たなビルトイン関数が追加され、既存のビルトイン関数も Unicode サポートのために修正されました:

unichr(ch) は Unicode におけるコードが整数 ch になるような文字 1 文字からなる Unicode 文字列を返します。

u が 1 文字の通常文字あるいは Unicode 文字として、 ord(u) はコードを整数で返します。

unicode(string [, encoding] [, errors] ) は、8 ビット文字列から Unicode 文字列を作ります。 encoding は使用するエンコーディング名の文字列です。 errors パラメータは、現在エンコーディングにおいて不正な文字の扱いを指示します; これに値として 'strict' を渡すと全てのエンコーディングエラーに対し、例外を引き起こします。 'ignore' を渡すとエラーは黙って無視されます。 'replace' を渡すと、全ての問題ケースで、公式な置き換え文字である U+FFFD に置き換えます。

exec 文や　eval(), getattr(), setattr() のような色々なビルトインも、普通の文字列同様に Unicode 文字列を受け付けるようになりました。(この修正をするプロセスをいくつかのビルトインで忘れている可能性もあります。文字列を受け取るものが Unicode を全く受け取らないビルトインを見つけたら、バグとして報告してください。)

新規モジュール unicodedata は、Unicode 文字の特性へのインターフェイスを提供します。例えば unicodedata.category(u'A') は 2 文字の文字列 'Lu' を返しますが、これは、 'L' が letter を、 'u' が uppercase を表します。 unicodedata.bidirectional(u'\u0660') は 'AN' を返し、これは U+0660 が Arabic Number であることを表します。

codecs モジュールには、既存のエンコーディングをルックアップする関数、新しいエンコーディングを登録する関数が含まれます。新しいエンコーディングを実装したいと思うのでない限りは、一番使うことになるのは codecs.lookup(encoding) でしょう。これは 4 要素のタプルを返します: (encode_func, decode_func, stream_reader, stream_writer) 。

encode_func は、Unicode 文字列を受け取って 2 要素タプル (string, length) を返す関数です。 string は、与えられたエンコーディングで Unicode 文字列を変換した部分 (おそらく全体) を含む 8 ビット文字列で、 length は何文字の Unicode 文字列が変換されたかを伝えます。

decode_func は encode_func の対となる関数で、8 ビット文字列を受け取って、2 要素のタプル (ustring, length) を返します。 ustring が結果の Unicode 文字列で、整数 length が、8 ビット文字列何文字が消費されたかを表します。

stream_reader is a class that supports decoding input from a stream. stream_reader(file_obj) returns an object that supports the read(), readline(), and readlines() methods. These methods will all translate from the given encoding and return Unicode strings.

stream_writer, similarly, is a class that supports encoding output to a stream. stream_writer(file_obj) returns an object that supports the write() and writelines() methods. These methods expect Unicode strings, translating them to the given encoding on output.

例えば以下のコードは Unicode 文字列を UTF-8 でエンコーディングしてファイルに書きます:

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()

そして以下コードではファイルから UTF-8 で読めます:

input = UTF8_streamreader( open( '/tmp/output', 'rb') )
print repr(input.read())
input.close()

re モジュールでは Unicode 対応した正規表現が利用可能で、これは新しい根底となる SRE なる実装から成り、Secret Labs AB の Fredrik Lundh によって書かれました。

Python コンパイラに全ての文字列リテラルを Unicode 文字列として解釈させるための -U コマンドラインオプションが追加されました。これはあなたの Python コードのテストと将来の保障を意図しています。というのも、将来の Python バージョンでは 8 ビット文字列のサポートがなくなって、Unicode 文字列だけとなる予定だからです。 (---訳注: ここで言っている将来バージョンとは、結果的には Python 3 になりました。What's New での明記はないのですが -U オプションは Python 2.7 時点では存在していません。ですが同じことは 2.6 以降では from __future__ import unicode_literals で出来ます。 ---)

リストの内包表記

リストというのは Python の主要なデータ型で、多くのプログラムがリストをいつかは操るものです。リストの操作での 2 つのよくある操作は、それらについてループし、あるいは特定の基準に合致したものを取り出すか個々の要素にある関数を適用するかする、といったものです。例えば文字列のリストが与えられた場合、特定の部分文字列を含む全ての文字列を引き抜いたり、あるいは各行から末尾の空白を取り除いたりしたいでしょう。

既にあった map() 関数、 filter() 関数がこの目的のためには使えますが、それらにはその引数の一つに関数が必要です。何か既存のビルトイン関数で直接渡せるものがあればよいのですが、これがない場合その必要とされる仕事をする小さな関数を作る必要があって、また、Python のスコープ規則によって、その小さな関数が何かほかの情報を必要とする場合に醜いものになります。前パラグラフでの最初の例を考えましょう。指定の部分文字列を含む文字列リストから全てを探す例です。このように書けるでしょう:

# 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)

Python のスコープ規則のために、 lambda 式で作っている匿名関数にデフォルト引数を使い、これに検索対象の部分文字列を渡しています。リスト内包表記はこれを明快にします:

sublist = [ s for s in L if string.find(s, S) != -1 ]

リスト内包表記は以下の形式を持ちます:

[ expression for expr in sequence1
             for expr2 in sequence2 ...
             for exprN in sequenceN
             if condition ]

for...in 節はイテレートするシーケンスを含みます。シーケンス群は同じ長さである必要はありません。それらは並列でイテレートされる のではなく 左から右の順で周ります。続くパラグラフでもっとわかりやすく説明します。生成されるリストの要素は一連の expression の値となります。最後の if 節はオプショナルです。これがあれば expression は condition が真の場合にのみ評価・追加されます。

セマンティクスについてとてもわかりやすく説明しておきましょう。リスト内包は以下の Python コードと等価です:

for expr1 in sequence1:
    for expr2 in sequence2:
    ...
        for exprN in sequenceN:
             if (condition):
                  # Append the value of
                  # the expression to the
                  # resulting list.

つまり、複数の for...in 節があって if がないときの最終出力は、長さが各シーケンス長の積に等しくなるということです。長さ 3 のリスト二つなら、出力リストの長さは 9 要素です:

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)]

Python の文法に曖昧さを紛れ込ませないように、expression でタプルを作るなら括弧で囲わなくてはなりません。下にあるリスト内包表記で、最初のは構文エラーですが、二番目は有効です:

# Syntax error
[ x,y for x in seq1 for y in seq2]
# Correct
[ (x,y) for x in seq1 for y in seq2]

リスト内包表記のアイディアは、もともとは関数型プログラミング言語 Haskell (https://www.haskell.org) に由来しています。Greg Ewing が Python にこれを追加することを最も実際的に主張し、彼が最初のリスト内包のパッチを書きました。それは傍目には終わりのない議論が python-dev メーリングリストにて続き、Skip Montanaro によって最新に保たれました。

累算代入 (Augmented Assignment)

累算代入はもう一つの長らく待ち望まれた機能であり、Python 2.0 に追加されました。累算代入演算子には +=, -=, *= などがあります。例えばステートメント a += 2 は変数 a に 2 を加算し、これはちょっとだけ長い記述 a = a + 2 と同じです。

The full list of supported assignment operators is +=, -=, *=, /=, %=, **=, &=, |=, ^=, >>=, and <<=. Python classes can override the augmented assignment operators by defining methods named __iadd__(), __isub__(), etc. For example, the following Number class stores a number and supports using += to create a new instance with an incremented value.

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

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

累算代入演算子は最初に C 言語で導入されて、 awk, C++, Java, Perl, PHP といった C から派生した言語のほとんどでサポートされています。累算代入のパッチは Thomas Wouters により実装されました。

文字列メソッド

Until now string-manipulation functionality was in the string module, which was usually a front-end for the strop module written in C. The addition of Unicode posed a difficulty for the 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 string.replace(), which takes 3 string arguments, that means eight possible permutations, and correspondingly complicated code.

代わりに、Python 2.0 は問題を文字列型に押し込み、文字列操作機能が 8 ビット文字列と Unicode 文字列の両方のメソッドを通じて利用可能としました。

>>> 'andrew'.capitalize()
'Andrew'
>>> 'hostname'.replace('os', 'linux')
'hlinuxtname'
>>> 'moshe'.find('sh')
2

変わらない一つのこと、華やかなエイプリルフールのジョークではありませんが、それは Python 文字列が immutable だということです。ですので文字列メソッドは新しい文字列を返し、それが操作する文字列を変更しません。

古い string モジュールはまだ後方互換性のために残されますが、それはほとんど新たな文字列メソッドへのフロントエンドとして振舞います。

Two methods which have no parallel in pre-2.0 versions, although they did exist in JPython for quite some time, are startswith() and endswith(). s.startswith(t) is equivalent to s[:len(t)] == t, while s.endswith(t) is equivalent to s[-len(t):] == t.

One other method which deserves special mention is join(). The join() method of a string receives one parameter, a sequence of strings, and is equivalent to the string.join() function from the old string module, with the arguments reversed. In other words, s.join(seq) is equivalent to the old string.join(seq, s).

循環参照のガベージコレクション

Python の C 実装は、ガーベージコレクションの実装に参照カウントを使っています。全ての Python オブジェクトは自身を参照している数を維持していて、参照が作成されたり破壊されたりするカウントを調整しています。参照カウントがゼロになればそのオブジェクトにはもはや到達可能ではありません。あなたはそれにアクセスするためのオブジェクトへの参照を持つ必要がありますが、カウントがゼロならば参照はもはや存在しないということです。

参照カウントはある種望ましい特徴を持っています。それは理解しやすく、実装しやすく、結果としての実装の移植性は高く、かなり高速であり、そして、独自のメモリ処理方式を実装しているようなほかのライブラリと共にでも良く振舞います。参照カウントの主要な問題点は、それが時々、オブジェクトにはもう到達不能であることに気付かないので、結果としてメモリリークを引き起こすことです。これは参照の循環がある場合に発生します。

最も単純な循環について考えてみます。クラスインスタンスが自身への参照を持つ場合です:

instance = SomeClass()
instance.myself = instance

上の例の 2 行のコードが実行された後では、 instance の参照カウントは 2 です。参照の一つ目は 'instance' と名付けられた変数からのもので、もう一つの参照は、インスタンスの myself 属性から来るものです。

このあとに続くコードが del instance だとしたら、何が起こるでしょうか? instance の参照カウントは 1 減るので参照カウントは 1 になります。 myself 属性内の参照はいまだ存在します。けれどもインスタンスはもう Python コードからは到達不能ですから、本来削除出来るはずです。お互いを参照しあうならばいくつものオブジェクトが循環に参加しえるので、結果それら全てのオブジェクトはリークしてしまいます。

Python 2.0 はこの問題を、循環検出アルゴリズムを周期的に実行することによりフィックスします。そのアルゴリズムは、到達不能な循環を探して関係するオブジェクトを削除します。新しく追加された gc モジュールは、ガーベージコレクションを実行する関数、デバッグのための統計情報を取得する関数、コレクタのパラメータを調整する関数を提供します。

循環検出アルゴリズムの実行はいくらかの時間がかかるので、結果として多少の追加的なオーバヘッドがかかるでしょう。2.0 を使って循環のコレクションの経験を積んだのちに、 Python 2.1 では注意深い調整によりオーバヘッドを最小に出来ることが望まれています。今のところパフォーマンスの損失がいかほどなのかは明らかではありません。これはこれのベンチマークがトリッキーであり、プログラムがどれだけの頻度でオブジェクトを構築・破棄するのかに大きく依存するからです。循環の検出は Python コンパイル時に無効に出来ます。もしもあなたが小さな速度のペナルティでさえも許容出来ないであるとか、あるいは循環のコレクションがバギーであることを疑うのであれば、 configure スクリプト実行時に --without-cycle-gc スイッチを与えることでそうすることが出来ます。 (---訳注: Python 2.3 でこの循環参照の GC は必須となり、 --without-cycle-gc 、 --with-cycle-gc での有無効化は撤廃されました。---)

何人かの人々がこの問題に体当たりで取り組み、解決に対する貢献をしました。循環検出アプローチの初期の実装は、Toby Kelsey により書かれました。現在のアルゴリズムは CNRI を訪れている間に Eric Tiedemann によって提案されて、Guido van Rossum と Neil Schemenauer が別々の 2 つの実装を書いて、あとで Neil によって統合されたものです。そこに至るまでにもほかの数多くの人々によって提案がなされました。python-dev メーリングリストの 2000 年 3 月のアーカイブに、これに関するほとんどの議論が含まれています。特にタイトルが "Reference cycle collection for Python" と "Finalization again" のスレッドです。

その他の言語コアの変更

Python 文法とビルトイン関数について、色々マイナーな変更がなされました。影響が広範囲に及ぶものは一つもありませんが、手軽で便利なものです。

言語のマイナー変更

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 apply() built-in function: apply(f, args, kw) calls the function f() with the argument tuple args and the keyword arguments in the dictionary kw. apply() is the same in 2.0, but thanks to a patch from Greg Ewing, f(*args, **kw) is a shorter and clearer way to achieve the same effect. This syntax is symmetrical with the syntax for defining functions:

def f(*args, **kw):
    # args is a tuple of positional args,
    # kw is a dictionary of keyword args
    ...

The print statement can now have its output directed to a file-like object by following the print with >> file, similar to the redirection operator in Unix shells. Previously you'd either have to use the write() method of the file-like object, which lacks the convenience and simplicity of print, or you could assign a new value to sys.stdout and then restore the old value. For sending output to standard error, it's much easier to write this:

print >> sys.stderr, "Warning: action field not supplied"

import module as name または from module import name as othername という構文を使って、インポートするモジュールの名前をリネーム出来るようになりました。パッチは Thomas Wouters が投稿しました。

% 演算子を使う際に新しい書式化スタイルが利用可能です; '%r' はその引数の repr() を挿入します。これは対称性の検討からも考えられました。今の場合は既存の '%s' が引数の str() を挿入することに呼応するものです。例えば '%r %s' % ('abc', 'abc') は文字列 'abc' abc を返します。

Previously there was no way to implement a class that overrode Python's built-in in operator and implemented a custom version. 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 IndexError is encountered. Moshe Zadka contributed a patch which adds a __contains__() magic method for providing a custom implementation for in. Additionally, new built-in objects written in C can define what in means for them via a new slot in the sequence protocol.

以前のバージョンの Python では、オブジェクトの削除に再帰するアルゴリズムを使っていました。データ構造が深くネストしている場合、インタプリタが C のスタックを使い果たしてクラッシュしていました。Christian Tismer はこの問題をフィックスする削除ロジックに書き直しました。これに関係する注目すべきものとしては、再帰するオブジェクトの比較が無限再帰してクラッシュしていたのを、Jeremy Hylton が書き直してクラッシュしないようにして、有用な結果を生成するようにしたことです。例えば以下コード:

a = []
b = []
a.append(a)
b.append(b)

The comparison 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 cmp(a,b) would always produce an answer, even if a user-defined __cmp__() method encountered an error, since the resulting exception would simply be silently swallowed.

Work has been done on porting Python to 64-bit Windows on the Itanium processor, mostly by Trent Mick of ActiveState. (Confusingly, sys.platform is still '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 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.

変数に値が割り当てられる前にローカル変数を参照するコードにおいて、 NameError 例外はよく混乱するものであり、この欠点を軽減する試みがなされました。例えば下に挙げるコードは print 文で 1.5.2 と 2.0 の両方で例外が発生しますが、1.5.2 は NameError 例外が、2.0 では新規の例外 UnboundLocalError が投げられます。 UnboundLocalError は NameError のサブクラスですので NameError が投げられることを想定する既存のコードはそのまま動作するはずです。:

def f():
    print "i=",i
    i = i + 1
f()

2 つの新規例外 TabError と IndentationError が導入されました。これらはともに SyntaxError のサブクラスで、Python コードに不適切なインデントが見つかると送出されます。

ビルトイン関数の変更

新しいビルトイン関数 zip(seq1, seq2, ...) が追加されました。 zip() はタプルのリストを返します。それぞれは、引数のシーケンスのそれぞれの i 番目要素たちを含むタプルです。 zip() と map(None, seq1, seq2) の違いは、 map() はシーケンスが同じ長さを持たない場合に None が埋められるのに対し、 zip() は返すリストの長さを、引数のシーケンスの最も短い長さに切り詰めます。

The int() and long() functions now accept an optional "base" parameter when the first argument is a string. int('123', 10) returns 123, while int('123', 16) returns 291. int(123, 16) raises a TypeError exception with the message "can't convert non-string with explicit base".

sys モジュールに、これまでより詳細なバージョン情報を持つ変数が追加されました。 sys.version_info はタプル (major, minor, micro, level, serial) です。例えば仮に 2.0.1beta1 というバージョンだったとすれば、 sys.version_info は (2, 0, 1, 'beta', 1) となるでしょう。 level は "alpha" や "beta" といった文字列で、最終リリースでは "final" です。(---訳注: Python 2.7 で名前付きタプルになっています。また、その属性名では level ではなく releaselevel です。---)

Dictionaries have an odd new method, setdefault(key, default), which behaves similarly to the existing get() method. However, if the key is missing, setdefault() both returns the value of default as get() would do, and also inserts it into the dictionary as the value for key. Thus, the following lines of code:

if dict.has_key( key ): return dict[key]
else:
    dict[key] = []
    return dict[key]

は、単一の return dict.setdefault(key, []) ステートメントだけで書けます。

再帰の暴走を C のスタックが埋め尽くされてコアダンプしたり GPF (訳注: General Protection Fault) する前に捕捉するために、インタプリタは最大の再帰の深さをセットします。以前まではこの制限は Python コンパイル時点で決めてしまっていましたが、2.0 では最大の再帰の深さは sys.getrecursionlimit() と sys.setrecursionlimit() を使って読み取れ、修正出来ます。このデフォルトは 1000 です。また、当該プラットフォームでのおよその最大値は、新たに追加されたスクリプト Misc/find_recursionlimit.py を実行することで知ることが出来ます。

Python 2.0 への移植

新しい Python リリースは以前のリリースとの互換性を保つために苦心していますし、その記録はかなり良くなされてきました。ですがいくつかの変更に関しては、大抵は大きな誤りであると判明した初期デザインを修正するという理由で、後方互換性を破壊することを必ずしも回避せずに有用性が検討されています。このセクションでは Python 2.0 において、古い Python コードを破壊するかもしれない変更点について列挙します。

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 append() and insert(). In earlier versions of Python, if L is a list, L.append( 1,2 ) appends the tuple (1,2) to the list. In Python 2.0 this causes a 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: 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 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 Objects/listobject.c and define the preprocessor symbol NO_STRICT_LIST_APPEND to preserve the old behaviour; this isn't recommended.

socket モジュールのいくつかの関数についてはまだこの方法が許されています。例えば、 socket.connect( ('hostname', 25) ) が正しい形式なのですが、 socket.connect('hostname', 25) も動作します。socket.connect_ex と socket.bind も同じようにおおらかです。2.0alpha1 がそれら関数を厳しくしたのですが、ドキュメントが実際には複数引数を取る形式で誤って書かれたために、多くの人々がその厳しくなったチェックに違反してしまうコードを書いてしまいました。GvR はその変更を、市民たちの反応を受けて元に戻し、 socket モジュールについてはドキュメントは修正されて、複数引数形式は非推奨としてマークするに留められました。将来バージョンの Python においてこれはもう一度厳しく なります 。 (---訳注: What's New からは読み取れませんが少なくとも 2.7 では単一引数でしか渡せません。つまり明示的にタプルにして渡す必要があります。---)

文字列リテラル内の \x エスケープは、正確に 2 桁の 16 進表記文字になりました。以前は 'x' に続く 16 進表記文字全てを消費して最後の 8 ビットを使っていたため、 \x123456 は \x56 と同じでした。

例外 AttributeError と NameError がよりフレンドリなエラーメッセージを持つようになっています。それらのテキストは 'Spam' instance has no attribute 'eggs' や name 'eggs' is not defined のようなものになります。以前まではエラーメッセージは存在しない属性名 eggs だけでしたので、この事実に便乗して書かれたコードは 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 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 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; 3L * 'abc' produces 'abcabcabc', and (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 seek() method of file objects, and in the formats supported by the % operator (%d, %i, %x, etc.). For example, "%d" % 2L**64 will produce the string 18446744073709551616.

一番微妙な長整数についての変更は、長整数を str() してももはや末尾の 'L' 文字が付かないことです。 repr() では今でも付くのにも関わらずです。 'L' は長整数を普通の整数と全く同じように印字したい多くの人々を悩ませてきました。それを各々自分なりの手段で取り除く必要があったからです。これはもう 2.0 では問題でなくなりましたが、 'L' が付くことをあてにして str(longval)[:-1] とするコードが今度は数値の最後の桁を失ってしまいます。

Taking the repr() of a float now uses a different formatting precision than str(). repr() uses %.17g format string for C's sprintf(), while str() uses %.12g as before. The effect is that repr() may occasionally show more decimal places than str(), for certain numbers. For example, the number 8.1 can't be represented exactly in binary, so repr(8.1) is '8.0999999999999996', while str(8.1) is '8.1'.

The -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 exceptions module containing the standard exceptions was translated from Python to a built-in C module, written by Barry Warsaw and Fredrik Lundh.

拡張と埋め込みについての変更

いくつかの変更点については覆いが被されていて、C 拡張モジュールや大きなアプリケーションでの Python インタプリタの埋め込みを書く人々からしか見えないものです。Python C API を扱う必要がないのであれば、このセクションは読み飛ばして差し支えありません。

Python C API のバージョン番号がインクリメントされたので、1.5.2 でコンパイルされた C 拡張は 2.0 で動作させるために再コンパイルしなければなりません。Windows では Python 1.5.x でビルドされたサードパーティ拡張を Python 2.0 でインポートすることは、Windows の DLL の仕組みのために、出来ません。その場合 Python は例外を投げ、インポートは失敗します。(---訳注: この文章、おかしなことを言っているので一応…。おそらく「Windows の一般市民は C コンパイラを持っていない」ことが著者の頭にあって、手が滑っているのだと思います。DLL の動作の仕組みが問題となるのは事実ですが、本質的には Windows 云々はあまり関係ないです。API が変わるか ABI が変わるならプラットフォームに関係なくリコンパイルは常に必要です。 ---)

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 isinstance() and issubclass(). This means you no longer have to remember to write code such as if type(obj) == myExtensionClass, but can use the more natural if isinstance(obj, myExtensionClass).

Python/importdl.c ファイルが多くの異なるプラットフォームの動的ロードをサポートするのに大量の #ifdef だらけになっていたのを、Greg Stein が掃除して再編成しました。 importdl.c は今ではとても小さくなり、プラットフォーム依存のコードは Python/dynload_*.c ファイル群の束にそれぞれ移動しました。もう一つの掃除。include/ ディレクトリ内で色々な移植性のためのハックを施すためのたくさんの my*.h ファイルたちが、単一の Include/pyport.h にマージされました。

Vladimir Marangozov の手による、待ち望まれた malloc の再編成が完了しました。これは Python インタプリタが C 標準の malloc() の代わりにカスタムアロケータを使うことを容易にするものです。ドキュメントについては Include/pymem.h と Include/objimpl.h のコメントを読んで下さい。インターフェイスが決着するまでの間の長い長い議論については python.org の 'patches' と 'python-dev' リストのウェブアーカイブをみてください。(---訳注: この件についての続きの話が What's New in Python 2.3 に Pymalloc として少しわかりやすく記述されています。---)

MacOS の GUSI 開発環境の最近のバージョンは POSIX スレッドをサポートしています。ですので Python の POSIX スレッディングのサポートは今では Macintosh で動作します。ユーザ空間での GNU pth ライブラリを使ったスレッディングサポートも寄稿されました。

Windows でのスレッディングサポートも拡張されました。Windows は、競合があるケースでのみカーネルオブジェクトを使うスレッドロックをサポートしています。競合がない普通のケースではそれらはより単純な関数を使い、これは段違いに高速です。NT での Python 1.5.2 版でスレッド化すると、非スレッド版の 2 倍遅くなりますが、2.0 に変えるとその差はたった 10% です。これらの改善は Yakov Markovitch の貢献によるものです。

Python 2.0 のソースが ANSI C プロトタイプだけを使うようになったので、Python のコンパイルには ANSI C コンパイラが必須になりました。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 2**16 to 2**32.

Three new convenience functions intended for adding constants to a module's dictionary at module initialization time were added: PyModule_AddObject(), PyModule_AddIntConstant(), and 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.

Unix スタイルのシグナルハンドラへのラッパーAPIが追加されました。 PyOS_getsig() でシグナルハンドラを取得し、 PyOS_setsig() で新しいハンドラをセットします。

Distutils: モジュールの簡単インストール

Python 2.0 以前は、モジュールのインストールは退屈な作業でした -- Python がどこにインストールされているかや拡張モジュールのコンパイルに必要なオプションを自動的に知る方法はありませんでした。ソフトウェアの作者は Makefile と設定ファイル群の編集という大変な労力を要する儀式を通過しなければならないのに、それは実際には Unix だけのためであって Windows と MacOS のサポートを置き去りにするものでした。Python ユーザは全く異なったインストール命令に直面していました。それは拡張パッケージごとに異なり、Python インストールをある種つまらない作業としていました。

The SIG for distribution utilities, shepherded by Greg Ward, has created the Distutils, a system to make package installation much easier. They form the 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 "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.

Distutils を使うには setup.py スクリプトを書く必要があります。単純なケースでは、ソフトウェアが .py ファイルだけを含む場合、最小限の setup.py は数行足らずで書けます:

from distutils.core import setup
setup (name = "foo", version = "1.0",
       py_modules = ["module1", "module2"])

setup.py ファイルは、ソフトウェアが少しのパッケージで構成される場合はこれより大きく複雑になることはありません:

from distutils.core import setup
setup (name = "foo", version = "1.0",
       packages = ["package", "package.subpackage"])

C 拡張が最も複雑なケースになりえます。以下は PyXML パッケージからもってきた例です:

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 ] )

Distutils ではソース配布物、バイナリ配布物の作成の面倒もみてくれます。 "sdist" コマンドは "python setup.py sdist" を実行することで起動し、これは foo-1.0.tar.gz のようなソース配布物を作ります。新しいコマンドを作るのは難しくありません。コマンド "bdist_rpm" と "bdist_wininst" が既に寄稿されていて、各々 RPM 配布物の作成、Windows インストーラの作成を行います。Debian パッケージや Solaris の .pkg のようなほかの配布フォーマットを作成するコマンドについての開発ステージは様々です。

これら全ては、 Python ドキュメントの基本的なセットとして追加されたマニュアル Python モジュールの配布 にドキュメントされています。

XML モジュール

Python 1.5.2 included a simple XML parser in the form of the 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 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 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.

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 startElement() and endElement() methods are called for every starting and end tag encountered by the parser, the characters() method is called for every chunk of character data, and so forth.

イベントドリブンのアプローチはドキュメント全体をいっときにメモリに持たなくて良い点で有利であり、ドキュメントが本当に巨大であるものを処理する際にはこれは重要です。ですが SAX ハンドラクラスを記述することは、ドキュメント構造を変更しようとする場合にはある種入り組んだものとなって、とても複雑になりえます。

以下の小さな実例プログラムでは、全ての開始・終了タグでメッセージを印字するハンドラを定義して、ファイル hamlet.xml をそのハンドラを使ってパースしています:

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' )

For more information, consult the Python documentation, or the XML HOWTO at https://pyxml.sourceforge.net/topics/howto/xml-howto.html.

DOM サポート

The Document Object Model is a tree-based representation for an XML document. A top-level Document instance is the root of the tree, and has a single child which is the top-level Element instance. This 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.

DOM は XML ドキュメントを修正するのに有用です。というのも DOM ツリーは作成出来、新規ノードを追加したりサブツリーを再編成したりすることで修正出来、出力として新たな XML ドキュメントを生成出来るからです。DOM ツリーを手動で構築して XML に変換することも出来ます。これにより単純に <tag1>...</tag1> をファイルに書くよりも柔軟性の高い方法で XML 出力を生成出来ます。

The DOM implementation included with Python lives in the xml.dom.minidom module. It's a lightweight implementation of the Level 1 DOM with support for XML namespaces. The parse() and parseString() convenience functions are provided for generating a DOM tree:

from xml.dom import minidom
doc = minidom.parse('hamlet.xml')

doc is a Document instance. Document, like all the other DOM classes such as Element and Text, is a subclass of the Node base class. All the nodes in a DOM tree therefore support certain common methods, such as 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, Element and Document instances have a method to find all child elements with a given tag name. Continuing from the previous 2-line example:

perslist = doc.getElementsByTagName( 'PERSONA' )
print perslist[0].toxml()
print perslist[1].toxml()

Hamlet XML ファイルに対して上の例は以下のような出力をします:

<PERSONA>CLAUDIUS, king of Denmark. </PERSONA>
<PERSONA>HAMLET, son to the late, and nephew to the present king.</PERSONA>

ドキュメントのルートエレメントは doc.documentElement として取得出来、その子は簡単に、ノードを削除したり追加したりすることで修正出来ます:

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] )

Again, I will refer you to the Python documentation for a complete listing of the different Node classes and their various methods.

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 https://www.python.org/community/sigs/current/xml-sig. The PyXML distribution also used the package name xml. If you've written programs that used PyXML, you're probably wondering about its compatibility with the 2.0 xml package.

結論として、Python 2.0 の xml パッケージは PyXML と互換性がありません。ですが、直近バージョンの PyXML をインストールすることで互換性を持たせることができます。 多くのアプリケーションは Python 2.0 に含まれる XML サポートで十分ですが、より複雑なアプリケーションは完全なPyXML パッケージをインストールする必要があります。 インストールされた PyXML バージョン 0.6.0 以上は、Python に同梱されている xml パッケージを置き換え、標準パッケージの厳密なスーパーセットとなり、多くの追加機能が追加されます。 PyXML の追加機能には次のようなものがあります。

4DOM, a full DOM implementation from FourThought, Inc.

The xmlproc validating parser, written by Lars Marius Garshol.

The sgmlop parser accelerator module, written by Fredrik Lundh.

更新されたモジュール

Lots of improvements and bugfixes were made to Python's extensive standard library; some of the affected modules include readline, ConfigParser, cgi, calendar, posix, readline, xmllib, aifc, chunk wave, random, shelve, and nntplib. Consult the CVS logs for the exact patch-by-patch details.

Brian Gallew contributed OpenSSL support for the 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 Modules/Setup to include SSL support, which adds an additional function to the socket module: socket.ssl(socket, keyfile, certfile), which takes a socket object and returns an SSL socket. The httplib and urllib modules were also changed to support https:// URLs, though no one has implemented FTP or SMTP over SSL.

The httplib module has been rewritten by Greg Stein to support HTTP/1.1.

Backward compatibility with the 1.5 version of httplib is provided, though using HTTP/1.1 features such as pipelining will require rewriting code to use a different set of interfaces.

The 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 create_line and create_polygon much faster, especially when using lots of coordinates.

curses モジュールが、Oliver Andrich による拡張版をもとに大規模に拡張され、ncurses と SYSV curses からの多くの追加機能、例えば色付きの表示、別の文字集合サポート、パッド、マウスサポートなどをサポートするようになりました。このことは、モジュールが BSD curses だけしか持っていない OS とは互換性が無いことを意味しますが、現在メンテナンスされている OS でそういう類のものは無さそうです。

2.0 の Unicode サポートについて前述したように、 re モジュールで提供される正規表現の根底となる実装が変更されました。SRE は新しい正規表現エンジンで、Fredrik Lundh によって書かれ、部分的に Hewlett Packard 社により寄贈されました。これは 8 ビット文字列と Unicode 文字列両方に合致するようサポートされています。

新しいモジュール

数多くのモジュールが新しく追加されました。ここではそれらを短い説明とともに列挙するだけにします。特定のモジュールの詳細は 2.0 のドキュメントを調べてください。

atexit: Python インタプリタが終了する前に呼び出す関数を登録します。これまで sys.exitfunc に直接セットしてきたコードは atexit モジュールを代わりに用いるように修正してください。 atexit をインポートし、 atexit.register() で終了時に呼び出す関数を登録します。(Contributed by Skip Montanaro.)

codecs, encodings, unicodedata: Added as part of the new Unicode support.

filecmp: Supersedes the old cmp, cmpcache and dircmp modules, which have now become deprecated. (Contributed by Gordon MacMillan and Moshe Zadka.)

gettext: このモジュールは Python プログラムに、GNU gettext メッセージカタログライブラリへのインターフェイスを提供することで国際化 (I18N=internationalization) と地域化 (L10N=localization) サポートをもたらします。 (Integrated by Barry Warsaw, from separate contributions by Martin von Löwis, Peter Funk, and James Henstridge.)

linuxaudiodev: Support for the /dev/audio device on Linux, a twin to the existing sunaudiodev module. (Contributed by Peter Bosch, with fixes by Jeremy Hylton.)

mmap: Windows、Unix 両方でのメモリマップドファイルへのインターフェイスです。ファイル内容をメモリに直接マッピング出来、それは mutable な文字列であるかのように振る舞い、これにより読み書き出来ます。それらは例えば re モジュールのような普通は文字列を期待するような関数にさえも渡せます。(Contributed by Sam Rushing, with some extensions by A.M. Kuchling.)

pyexpat: An interface to the Expat XML parser. (Contributed by Paul Prescod.)

robotparser: Parse a 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 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.)

tabnanny: Python ソースコードが曖昧なインデントになっていないかをチェックするモジュール/スクリプトです。 (Contributed by Tim Peters.)

UserString: A base class useful for deriving objects that behave like strings.

webbrowser: 指定した URL で、プラットフォームに依存しない方法でウェブブラウザを起動するモジュールです。個々のプラットフォームにおいて様々なブラウザが特定の順序で試されます。ユーザはどのブラウザを起動するかを環境変数 BROWSER をセットすることで変更出来ます。(元々は Eric S. Raymond による urllib への、同じ機能追加をするパッチに触発されましたが、最終的なモジュールは Fred Drake が元々 Tools/idle/BrowserControl.py として実装したものに由来し、Fred が標準ライブラリに適合させました。)

_winreg: An interface to the Windows registry. _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. _winreg was written by Bill Tutt and Mark Hammond.

zipfile: ZIP 形式アーカイブの読み書きのためのモジュールです。DOS/Windows での PKZIP や Unix での zip により生成されるアーカイブで、 gzip 形式とは混同しないで下さい (こちらは gzip モジュールによってサポートされています)。(Contributed by James C. Ahlstrom.)

imputil: A module that provides a simpler way for writing customized import hooks, in comparison to the existing ihooks module. (Implemented by Greg Stein, with much discussion on python-dev along the way.)

IDLE の改善

IDLE は公式の Python のクロスプラットフォームな IDE で、 Tkinter を使って書かれています。Python 2.0 では IDLE 0.6 を含めました。これは多くの新機能追加と改善がなされています。以下はその一部です:

UI の、特にシンタックスハイライトと自動インデントの領域において、改善と最適化がなされました。

クラスブラウザで、例えばモジュール内のトップレベル関数のような、より多くの情報をみることが出来るようになりました。

タブ幅をユーザ制御出来るようになりました。既存の Python ファイルを操作する際には、IDLE は自動的にインデントの慣習を検知してそれに合わせます。

色々なプラットフォームでブラウザの呼び出しがサポートされています。これを使って、ブラウザで Python ドキュメントを開きます。

IDLE がコマンドラインを持つようになりました。これは普通の Python インタプリタに大きく似せてあります。

色々な場所でコンテキストヘルプが出るようになっています。

IDLE は今ではパッケージとしてインストール出来ます。

エディタウィンドウ内では、下部に行/桁を表示するようになっています。

新たな 3 つのキーストロークコマンド: モジュールのチェック (Alt-F5)、モジュールのインポート (F5)、スクリプト実行 (Ctrl-F5).

削除されたモジュール、非推奨となったモジュール

A few modules have been dropped because they're obsolete, or because there are now better ways to do the same thing. The 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 lib-old subdirectory: cmp, cmpcache, dircmp, dump, find, grep, packmail, poly, util, whatsound, zmod. If you have code which relies on a module that's been moved to lib-old, you can simply add that directory to sys.path to get them back, but you're encouraged to update any code that uses these modules.

謝辞

著者は提案の申し出や修正、様々なこの記事の草稿の助けをしてくれた以下の人々に感謝します: 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.

変更履歴

Python next

Release date: XXXX-XX-XX

Security

gh-118486 [https://github.com/python/cpython/issues/118486]: os.mkdir() on Windows now accepts mode of 0o700 to restrict the new directory to the current user. This fixes CVE-2024-4030 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-4030] affecting tempfile.mkdtemp() in scenarios where the base temporary directory is more permissive than the default.

gh-116741 [https://github.com/python/cpython/issues/116741]: Update bundled libexpat to 2.6.2

gh-117233 [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 hashlib to be used with libraries that do not to support every algorithm that upstream OpenSSL does.

Core and Builtins

gh-118513 [https://github.com/python/cpython/issues/118513]: Fix incorrect 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.

gh-118164 [https://github.com/python/cpython/issues/118164]: Break a loop between the Python implementation of the 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.

gh-118272 [https://github.com/python/cpython/issues/118272]: Fix bug where generator.close does not free the generator frame's locals.

gh-116767 [https://github.com/python/cpython/issues/116767]: Fix crash in compiler on 'async with' that has many context managers.

gh-117894 [https://github.com/python/cpython/issues/117894]: Prevent agen.aclose() objects being re-used after .throw().

gh-117881 [https://github.com/python/cpython/issues/117881]: prevent concurrent access to an async generator via athrow().throw() or asend().throw()

gh-115874 [https://github.com/python/cpython/issues/115874]: Fixed a possible segfault during garbage collection of _asyncio.FutureIter objects

Library

gh-58933 [https://github.com/python/cpython/issues/58933]: Make pdb return to caller frame correctly when f_trace of the caller frame is not set

gh-118164 [https://github.com/python/cpython/issues/118164]: The Python implementation of the decimal module could appear to hang in relatively small power cases (like 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 10**precision (which could be effectively too large to compute).

gh-118404 [https://github.com/python/cpython/issues/118404]: Fix inspect.signature() for non-comparable callables.

gh-118314 [https://github.com/python/cpython/issues/118314]: Fix an edge case in binascii.a2b_base64() strict mode, where excessive padding is not detected when no padding is necessary.

gh-118042 [https://github.com/python/cpython/issues/118042]: Fix an unraisable exception in telnetlib.Telnet.__del__() when the __init__() method was not called.

gh-118221 [https://github.com/python/cpython/issues/118221]: Fix a bug where sqlite3.iterdump() could fail if a custom row factory was used. Patch by Erlend Aasland.

gh-118013 [https://github.com/python/cpython/issues/118013]: Fix regression introduced in gh-103193 [https://github.com/python/cpython/issues/103193] that meant that calling inspect.getattr_static() on an instance would cause a strong reference to that instance's class to persist in an internal cache in the 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 getattr_static(), but the function should still be signficantly faster than it was in Python 3.11. Patch by Alex Waygood.

gh-90848 [https://github.com/python/cpython/issues/90848]: Fixed unittest.mock.create_autospec() to configure parent mock with keyword arguments.

gh-118168 [https://github.com/python/cpython/issues/118168]: Fix incorrect argument substitution when typing.Unpack is used with the builtin tuple. typing.Unpack now raises TypeError when used with certain invalid types. Patch by Jelle Zijlstra.

gh-118033 [https://github.com/python/cpython/issues/118033]: Fix dataclasses.dataclass() not creating a __weakref__ slot when subclassing typing.Generic.

gh-117535 [https://github.com/python/cpython/issues/117535]: Do not try to get the source line for made up file name "sys" in warnings.

gh-114053 [https://github.com/python/cpython/issues/114053]: Fix erroneous NameError when calling typing.get_type_hints() on a class that made use of PEP 695 [https://peps.python.org/pep-0695/] type parameters in a module that had from __future__ import annotations at the top of the file. Patch by Alex Waygood.

gh-117995 [https://github.com/python/cpython/issues/117995]: Don't raise DeprecationWarning when a sequence of parameters is used to bind indexed, nameless placeholders. See also gh-100668 [https://github.com/python/cpython/issues/100668].

gh-80361 [https://github.com/python/cpython/issues/80361]: Fix TypeError in email.Message.get_payload() when the charset is RFC 2231 [https://datatracker.ietf.org/doc/html/rfc2231.html] encoded.

gh-86650 [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).

gh-117691 [https://github.com/python/cpython/issues/117691]: Improve the error messages emitted by tarfile deprecation warnings relating to PEP 706. If a filter argument is not provided to extract() or extractall, the deprecation warning now points to the line in the user's code where the relevant function was called. Patch by Alex Waygood.

gh-77102 [https://github.com/python/cpython/issues/77102]: site module now parses .pth file with UTF-8 first, and locale encoding if UnicodeDecodeError happened. It supported only locale encoding before.

gh-117692 [https://github.com/python/cpython/issues/117692]: Fixes a bug when doctest.DocTestFinder was failing on wrapped builtin_function_or_method.

gh-117566 [https://github.com/python/cpython/issues/117566]: ipaddress.IPv6Address.is_loopback() will now return True for IPv4-mapped loopback addresses, i.e. addresses in the ::ffff:127.0.0.0/104 address space.

gh-117503 [https://github.com/python/cpython/issues/117503]: Fix support of non-ASCII user names in bytes paths in os.path.expanduser() on Posix.

gh-117313 [https://github.com/python/cpython/issues/117313]: Only treat '\n', '\r' and '\r\n' as line separators in re-folding the email messages. Preserve control characters '\v', '\f', '\x1c', '\x1d' and '\x1e' and Unicode line separators '\x85', '\u2028' and '\u2029' as is.

gh-113171 [https://github.com/python/cpython/issues/113171]: Fixed various false positives and false negatives in

ipaddress.IPv4Address.is_private (see these docs for details)

ipaddress.IPv4Address.is_global

ipaddress.IPv6Address.is_private

ipaddress.IPv6Address.is_global

Also in the corresponding ipaddress.IPv4Network and ipaddress.IPv6Network attributes.

gh-103956 [https://github.com/python/cpython/issues/103956]: Fix lack of newline characters in trace module output when line tracing is enabled but source code line for current frame is not available.

gh-87106 [https://github.com/python/cpython/issues/87106]: Fixed handling in inspect.signature.bind() of keyword arguments having the same name as positional-only arguments when a variadic keyword argument (e.g. **kwargs) is present.

bpo-40943 [https://bugs.python.org/issue?@action=redirect&bpo=40943]: Fix several IndexError when parse emails with truncated Message-ID, address, routes, etc, e.g. example@.

bpo-30988 [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.

gh-67693 [https://github.com/python/cpython/issues/67693]: Fix urllib.parse.urlunparse() and urllib.parse.urlunsplit() for URIs with path starting with multiple slashes and no authority. Based on patch by Ashwin Ramaswami.

bpo-15010 [https://bugs.python.org/issue?@action=redirect&bpo=15010]: unittest.TestLoader.discover() now saves the original value of unittest.TestLoader._top_level_dir and restores it at the end of the call.

Documentation

gh-117928 [https://github.com/python/cpython/issues/117928]: The minimum Sphinx version required for the documentation is now 6.2.1.

gh-91565 [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.

Windows

gh-118347 [https://github.com/python/cpython/issues/118347]: Fixes launcher updates not being installed.

gh-115009 [https://github.com/python/cpython/issues/115009]: Update Windows installer to use SQLite 3.45.3.

gh-90329 [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.

macOS

gh-115009 [https://github.com/python/cpython/issues/115009]: Update macOS installer to use SQLite 3.45.3.

IDLE

bpo-34774 [https://bugs.python.org/issue?@action=redirect&bpo=34774]: Use user-selected color theme for Help => IDLE Doc.

C API

gh-117534 [https://github.com/python/cpython/issues/117534]: Improve validation logic in the C implementation of datetime.fromisoformat() to better handle invalid years. Patch by Vlad Efanov.

Python 3.12.3 final

Release date: 2024-04-09

Security

gh-115398 [https://github.com/python/cpython/issues/115398]: Allow controlling Expat >=2.6.0 reparse deferral (CVE-2023-52425 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-52425]) by adding five new methods:

xml.etree.ElementTree.XMLParser.flush()

xml.etree.ElementTree.XMLPullParser.flush()

xml.parsers.expat.xmlparser.GetReparseDeferralEnabled()

xml.parsers.expat.xmlparser.SetReparseDeferralEnabled()

xml.sax.expatreader.ExpatParser.flush()

gh-115399 [https://github.com/python/cpython/issues/115399]: Update bundled libexpat to 2.6.0

gh-115243 [https://github.com/python/cpython/issues/115243]: Fix possible crashes in collections.deque.index() when the deque is concurrently modified.

gh-114572 [https://github.com/python/cpython/issues/114572]: ssl.SSLContext.cert_store_stats() and ssl.SSLContext.get_ca_certs() now correctly lock access to the certificate store, when the ssl.SSLContext is shared across multiple threads.

Core and Builtins

gh-109120 [https://github.com/python/cpython/issues/109120]: Added handle of incorrect star expressions, e.g f(3, *). Patch by Grigoryev Semyon

gh-99108 [https://github.com/python/cpython/issues/99108]: Updated the hashlib built-in HACL* project [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.

gh-116735 [https://github.com/python/cpython/issues/116735]: For INSTRUMENTED_CALL_FUNCTION_EX, set arg0 to sys.monitoring.MISSING instead of None for CALL event.

gh-113964 [https://github.com/python/cpython/issues/113964]: Starting new threads and process creation through os.fork() are now only prevented once all non-daemon threads exit.

gh-116604 [https://github.com/python/cpython/issues/116604]: Respect the status of the garbage collector when indirect calls are made via PyErr_CheckSignals() and the evaluation breaker. Patch by Pablo Galindo

gh-116626 [https://github.com/python/cpython/issues/116626]: Ensure INSTRUMENTED_CALL_FUNCTION_EX always emits CALL

gh-116296 [https://github.com/python/cpython/issues/116296]: Fix possible refleak in object.__reduce__() internal error handling.

gh-116034 [https://github.com/python/cpython/issues/116034]: Fix location of the error on a failed assertion.

gh-115823 [https://github.com/python/cpython/issues/115823]: Properly calculate error ranges in the parser when raising SyntaxError exceptions caused by invalid byte sequences. Patch by Pablo Galindo

gh-112087 [https://github.com/python/cpython/issues/112087]: For an empty reverse iterator for list will be reduced to reversed(). Patch by Donghee Na.

gh-115154 [https://github.com/python/cpython/issues/115154]: Fix a bug that was causing the tokenize.untokenize() function to handle unicode named literals incorrectly. Patch by Pablo Galindo

gh-114828 [https://github.com/python/cpython/issues/114828]: Fix compilation crashes in uncommon code examples using super() inside a comprehension in a class body.

gh-115011 [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 __index__() method as for int.

gh-112215 [https://github.com/python/cpython/issues/112215]: Change the C recursion limits to more closely reflect the underlying platform limits.

gh-96497 [https://github.com/python/cpython/issues/96497]: Fix incorrect resolution of mangled class variables used in assignment expressions in comprehensions.

Library

gh-117467 [https://github.com/python/cpython/issues/117467]: Preserve mailbox ownership when rewriting in mailbox.mbox.flush(). Patch by Tony Mountifield.

gh-117310 [https://github.com/python/cpython/issues/117310]: Fixed an unlikely early & extra Py_DECREF triggered crash in ssl when creating a new _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 SSL_CTX_set_cipher_list() API.

gh-117178 [https://github.com/python/cpython/issues/117178]: Fix regression in lazy loading of self-referential modules, introduced in gh-114781 [https://github.com/python/cpython/issues/114781].

gh-117084 [https://github.com/python/cpython/issues/117084]: Fix zipfile extraction for directory entries with the name containing backslashes on Windows.

gh-117110 [https://github.com/python/cpython/issues/117110]: Fix a bug that prevents subclasses of typing.Any to be instantiated with arguments. Patch by Chris Fu.

gh-90872 [https://github.com/python/cpython/issues/90872]: On Windows, subprocess.Popen.wait() no longer calls WaitForSingleObject() with a negative timeout: pass 0 ms if the timeout is negative. Patch by Victor Stinner.

gh-116957 [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.

gh-90095 [https://github.com/python/cpython/issues/90095]: Ignore empty lines and comments in .pdbrc

gh-116764 [https://github.com/python/cpython/issues/116764]: Restore support of None and other false values in urllib.parse functions parse_qs() and parse_qsl(). Also, they now raise a TypeError for non-zero integers and non-empty sequences.

gh-116811 [https://github.com/python/cpython/issues/116811]: In PathFinder.invalidate_caches, delegate to MetadataPathFinder.invalidate_caches.

gh-116600 [https://github.com/python/cpython/issues/116600]: Fix repr() for global Flag members.

gh-116484 [https://github.com/python/cpython/issues/116484]: Change automatically generated tkinter.Checkbutton widget names to avoid collisions with automatically generated tkinter.ttk.Checkbutton widget names within the same parent widget.

gh-116401 [https://github.com/python/cpython/issues/116401]: Fix blocking os.fwalk() and shutil.rmtree() on opening named pipe.

gh-116143 [https://github.com/python/cpython/issues/116143]: Fix a race in pydoc _start_server, eliminating a window in which _start_server can return a thread that is "serving" but without a docserver set.

gh-116325 [https://github.com/python/cpython/issues/116325]: typing: raise SyntaxError instead of AttributeError on forward references as empty strings.

gh-90535 [https://github.com/python/cpython/issues/90535]: Fix support of interval values > 1 in logging.TimedRotatingFileHandler for when='MIDNIGHT' and when='Wx'.

gh-115978 [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 (https://github.com/bytecodealliance/wasmtime/issues/7830).

gh-88352 [https://github.com/python/cpython/issues/88352]: Fix the computation of the next rollover time in the logging.TimedRotatingFileHandler handler. computeRollover() now always returns a timestamp larger than the specified time and works correctly during the DST change. 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.

gh-87115 [https://github.com/python/cpython/issues/87115]: Set __main__.__spec__ to None when running a script with pdb

gh-76511 [https://github.com/python/cpython/issues/76511]: Fix UnicodeEncodeError in 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 replace error handler.

gh-116040 [https://github.com/python/cpython/issues/116040]: [Enum] fix by-value calls when second value is falsey; e.g. Cardinal(1, 0)

gh-75988 [https://github.com/python/cpython/issues/75988]: Fixed unittest.mock.create_autospec() to pass the call through to the wrapped object to return the real result.

gh-115881 [https://github.com/python/cpython/issues/115881]: Fix issue where ast.parse() would incorrectly flag conditional context managers (such as with (x() if y else z()): ...) as invalid syntax if feature_version=(3, 8) was passed. This reverts changes to the grammar made as part of gh-94949 [https://github.com/python/cpython/issues/94949].

gh-115886 [https://github.com/python/cpython/issues/115886]: Fix silent truncation of the name with an embedded null character in multiprocessing.shared_memory.SharedMemory.

gh-115809 [https://github.com/python/cpython/issues/115809]: Improve algorithm for computing which rolled-over log files to delete in logging.TimedRotatingFileHandler. It is now reliable for handlers without namer and with arbitrary deterministic namer that leaves the datetime part in the file name unmodified.

gh-74668 [https://github.com/python/cpython/issues/74668]: urllib.parse functions parse_qs() and parse_qsl() now support bytes arguments containing raw and percent-encoded non-ASCII data.

gh-67044 [https://github.com/python/cpython/issues/67044]: csv.writer() now always quotes or escapes '\r' and '\n', regardless of lineterminator value.

gh-115712 [https://github.com/python/cpython/issues/115712]: csv.writer() now quotes empty fields if delimiter is a space and skipinitialspace is true and raises exception if quoting is not possible.

gh-112364 [https://github.com/python/cpython/issues/112364]: Fixed ast.unparse() to handle format_spec with ", ' or \\. Patched by Frank Hoffmann.

gh-111358 [https://github.com/python/cpython/issues/111358]: Fix a bug in asyncio.BaseEventLoop.shutdown_default_executor() to ensure the timeout passed to the coroutine behaves as expected.

gh-115618 [https://github.com/python/cpython/issues/115618]: Fix improper decreasing the reference count for None argument in property methods getter(), setter() and deleter().

gh-115570 [https://github.com/python/cpython/issues/115570]: A DeprecationWarning is no longer omitted on access to the __doc__ attributes of the deprecated typing.io and typing.re pseudo-modules.

gh-112006 [https://github.com/python/cpython/issues/112006]: Fix inspect.unwrap() for types with the __wrapper__ data descriptor.

gh-101293 [https://github.com/python/cpython/issues/101293]: Support callables with the __call__() method and types with __new__() and __init__() methods set to class methods, static methods, bound methods, partial functions, and other types of methods and descriptors in inspect.Signature.from_callable().

gh-115392 [https://github.com/python/cpython/issues/115392]: Fix a bug in doctest where incorrect line numbers would be reported for decorated functions.

gh-114563 [https://github.com/python/cpython/issues/114563]: Fix several format() bugs when using the C implementation of Decimal: * memory leak in some rare cases when using the z format option (coerce negative 0) * incorrect output when applying the z format option to type F (fixed-point with capital NAN / INF) * incorrect output when applying the # format option (alternate form)

gh-115197 [https://github.com/python/cpython/issues/115197]: urllib.request no longer resolves the hostname before checking it against the system's proxy bypass list on macOS and Windows.

gh-115165 [https://github.com/python/cpython/issues/115165]: Most exceptions are now ignored when attempting to set the __orig_class__ attribute on objects returned when calling typing generic aliases (including generic aliases created using typing.Annotated). Previously only AttributeError was ignored. Patch by Dave Shawley.

gh-115133 [https://github.com/python/cpython/issues/115133]: Fix tests for XMLPullParser with Expat 2.6.0.

gh-115059 [https://github.com/python/cpython/issues/115059]: io.BufferedRandom.read1() now flushes the underlying write buffer.

gh-79382 [https://github.com/python/cpython/issues/79382]: Trailing ** no longer allows to match files and non-existing paths in recursive glob().

gh-114071 [https://github.com/python/cpython/issues/114071]: Support tuple subclasses using auto() for enum member value.

gh-114763 [https://github.com/python/cpython/issues/114763]: Protect modules loaded with importlib.util.LazyLoader from race conditions when multiple threads try to access attributes before the loading is complete.

gh-97959 [https://github.com/python/cpython/issues/97959]: Fix rendering class methods, bound methods, method and function aliases in 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.

gh-112281 [https://github.com/python/cpython/issues/112281]: Allow creating union of types for typing.Annotated with unhashable metadata.

gh-111775 [https://github.com/python/cpython/issues/111775]: Fix importlib.resources.simple.ResourceHandle.open() for text mode, added missed stream argument.

gh-90095 [https://github.com/python/cpython/issues/90095]: Make .pdbrc and -c work with any valid pdb commands.

gh-107155 [https://github.com/python/cpython/issues/107155]: Fix incorrect output of help(x) where x is a lambda function, which has an __annotations__ dictionary attribute with a "return" key.

gh-105866 [https://github.com/python/cpython/issues/105866]: Fixed _get_slots bug which caused error when defining dataclasses with slots and a weakref_slot.

gh-60346 [https://github.com/python/cpython/issues/60346]: Fix ArgumentParser inconsistent with parse_known_args.

gh-100985 [https://github.com/python/cpython/issues/100985]: Update HTTPSConnection to consistently wrap IPv6 Addresses when using a proxy.

gh-100884 [https://github.com/python/cpython/issues/100884]: email: fix misfolding of comma in address-lists over multiple lines in combination with unicode encoding.

gh-95782 [https://github.com/python/cpython/issues/95782]: Fix io.BufferedReader.tell(), io.BufferedReader.seek(), _pyio.BufferedReader.tell(), io.BufferedRandom.tell(), io.BufferedRandom.seek() and _pyio.BufferedRandom.tell() being able to return negative offsets.

gh-96310 [https://github.com/python/cpython/issues/96310]: Fix a traceback in argparse when all options in a mutually exclusive group are suppressed.

gh-93205 [https://github.com/python/cpython/issues/93205]: Fixed a bug in 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.

bpo-44865 [https://bugs.python.org/issue?@action=redirect&bpo=44865]: Add missing call to localization function in argparse.

bpo-43952 [https://bugs.python.org/issue?@action=redirect&bpo=43952]: Fix multiprocessing.connection.Listener.accept() to accept empty bytes as authkey. Not accepting empty bytes as key causes it to hang indefinitely.

bpo-42125 [https://bugs.python.org/issue?@action=redirect&bpo=42125]: linecache: get module name from __spec__ if available. This allows getting source code for the __main__ module when a custom loader is used.

gh-66543 [https://github.com/python/cpython/issues/66543]: Make 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.

bpo-33775 [https://bugs.python.org/issue?@action=redirect&bpo=33775]: Add 'default' and 'version' help text for localization in argparse.

Documentation

gh-115399 [https://github.com/python/cpython/issues/115399]: Document CVE-2023-52425 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-52425] of Expat <2.6.0 under "XML vulnerabilities".

gh-115233 [https://github.com/python/cpython/issues/115233]: Fix an example for LoggerAdapter in the Logging Cookbook.

Tests

gh-83434 [https://github.com/python/cpython/issues/83434]: Disable JUnit XML output (--junit-xml=FILE command line option) in regrtest when hunting for reference leaks (-R option). Patch by Victor Stinner.

gh-117187 [https://github.com/python/cpython/issues/117187]: Fix XML tests for vanilla Expat <2.6.0.

gh-116333 [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.

gh-115979 [https://github.com/python/cpython/issues/115979]: Update test_importlib so that it passes under WASI SDK 21.

gh-112536 [https://github.com/python/cpython/issues/112536]: Add --tsan to test.regrtest for running TSAN tests in reasonable execution times. Patch by Donghee Na.

gh-116307 [https://github.com/python/cpython/issues/116307]: Added import helper isolated_modules as CleanImport does not remove modules imported during the context. Use it in importlib.resources tests to avoid leaving mod around to impede importlib.metadata tests.

gh-115720 [https://github.com/python/cpython/issues/115720]: Leak tests (-R, --huntrleaks) now show a summary of the number of leaks found in each iteration.

gh-115122 [https://github.com/python/cpython/issues/115122]: Add --bisect option to regrtest test runner: run failed tests with test.bisect_cmd to identify failing tests. Patch by Victor Stinner.

gh-115596 [https://github.com/python/cpython/issues/115596]: Fix ProgramPriorityTests in test_os permanently changing the process priority.

Build

gh-116313 [https://github.com/python/cpython/issues/116313]: Get WASI builds to work under wasmtime 18 w/ WASI 0.2/preview2 primitives.

gh-116117 [https://github.com/python/cpython/issues/116117]: Backport libb2's PR #42 to fix compiling CPython on 32-bit Windows with clang-cl.

gh-115167 [https://github.com/python/cpython/issues/115167]: Avoid vendoring vcruntime140_threads.dll when building with Visual Studio 2022 version 17.8.

gh-112536 [https://github.com/python/cpython/issues/112536]: Add support for thread sanitizer (TSAN)

Windows

gh-117267 [https://github.com/python/cpython/issues/117267]: Ensure DirEntry.stat().st_ctime behaves consistently with os.stat() during the deprecation period of st_ctime by containing the same value as st_birthtime. After the deprecation period, st_ctime will be the metadata change time (or unavailable through DirEntry), and only st_birthtime will contain the creation time.

gh-116773 [https://github.com/python/cpython/issues/116773]: Fix instances of <_overlapped.Overlapped object at 0xXXX> still has pending operation at deallocation, the process may crash.

gh-91227 [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.

gh-115554 [https://github.com/python/cpython/issues/115554]: The installer now has more strict rules about updating the Windows の 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.

gh-115543 [https://github.com/python/cpython/issues/115543]: Windows の Python ランチャ can now detect Python 3.13 when installed from the Microsoft Store, and will install Python 3.12 by default when PYLAUNCHER_ALLOW_INSTALL is set.

gh-115049 [https://github.com/python/cpython/issues/115049]: Fixes py.exe launcher failing when run as users without user profiles.

gh-115009 [https://github.com/python/cpython/issues/115009]: Update Windows installer to use SQLite 3.45.1.

IDLE

gh-88516 [https://github.com/python/cpython/issues/88516]: On macOS show a proxy icon in the title bar of editor windows to match platform behaviour.

Tools/Demos

gh-113516 [https://github.com/python/cpython/issues/113516]: Don't set LDSHARED when building for WASI.

C API

gh-117021 [https://github.com/python/cpython/issues/117021]: Fix integer overflow in PyLong_AsPid() on non-Windows 64-bit platforms.

gh-116869 [https://github.com/python/cpython/issues/116869]: Make the C API compatible with -Werror=declaration-after-statement compiler flag again. Patch by Victor Stinner.

Python 3.12.2 final

Release date: 2024-02-06

Security

gh-113659 [https://github.com/python/cpython/issues/113659]: Skip .pth files with names starting with a dot or hidden file attribute.

Core and Builtins

gh-114887 [https://github.com/python/cpython/issues/114887]: Changed socket type validation in create_datagram_endpoint() to accept all non-stream sockets. This fixes a regression in compatibility with raw sockets.

gh-114388 [https://github.com/python/cpython/issues/114388]: Fix a RuntimeWarning emitted when assign an integer-like value that is not an instance of int to an attribute that corresponds to a C struct member of type T_UINT and T_ULONG. Fix a double RuntimeWarning emitted when assign a negative integer value to an attribute that corresponds to a C struct member of type T_UINT.

gh-113703 [https://github.com/python/cpython/issues/113703]: Fix a regression in the codeop module that was causing it to incorrectly identify incomplete f-strings. Patch by Pablo Galindo

gh-89811 [https://github.com/python/cpython/issues/89811]: Check for a valid tp_version_tag before performing bytecode specializations that rely on this value being usable.

gh-113602 [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

gh-113297 [https://github.com/python/cpython/issues/113297]: Fix segfault in the compiler on with statement with 19 context managers.

gh-106905 [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 ast.parse(). In 3.12 a change to when garbage collection can be triggered prevented the race condition from occurring.

gh-112943 [https://github.com/python/cpython/issues/112943]: Correctly compute end column offsets for multiline tokens in the tokenize module. Patch by Pablo Galindo

gh-112716 [https://github.com/python/cpython/issues/112716]: Fix SystemError in the import statement and in __reduce__() methods of builtin types when __builtins__ is not a dict.

gh-94606 [https://github.com/python/cpython/issues/94606]: Fix UnicodeEncodeError when 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.

Library

gh-114965 [https://github.com/python/cpython/issues/114965]: Update bundled pip to 24.0

gh-114959 [https://github.com/python/cpython/issues/114959]: tarfile no longer ignores errors when trying to extract a directory on top of a file.

gh-109475 [https://github.com/python/cpython/issues/109475]: Fix support of explicit option value "--" in argparse (e.g. --option=--).

gh-110190 [https://github.com/python/cpython/issues/110190]: Fix ctypes structs with array on Windows ARM64 platform by setting MAX_STRUCT_SIZE to 32 in stgdict. Patch by Diego Russo

gh-113280 [https://github.com/python/cpython/issues/113280]: Fix a leak of open socket in rare cases when error occurred in ssl.SSLSocket creation.

gh-77749 [https://github.com/python/cpython/issues/77749]: email.policy.EmailPolicy.fold() now always encodes non-ASCII characters in headers if utf8 is false.

gh-114492 [https://github.com/python/cpython/issues/114492]: Make the result of termios.tcgetattr() reproducible on Alpine Linux. Previously it could leave a random garbage in some fields.

gh-113267 [https://github.com/python/cpython/issues/113267]: Revert changes in gh-106584 [https://github.com/python/cpython/issues/106584] which made calls of TestResult methods startTest() and stopTest() unbalanced.

gh-75128 [https://github.com/python/cpython/issues/75128]: Ignore an OSError in asyncio.BaseEventLoop.create_server() when IPv6 is available but the interface cannot actually support it.

gh-114257 [https://github.com/python/cpython/issues/114257]: Dismiss the FileNotFound error in ctypes.util.find_library() and just return None on Linux.

gh-114328 [https://github.com/python/cpython/issues/114328]: The tty.setcbreak() and new 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 stty(1) manual pages.

gh-101438 [https://github.com/python/cpython/issues/101438]: Avoid reference cycle in ElementTree.iterparse. The iterator returned by 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.

gh-104522 [https://github.com/python/cpython/issues/104522]: 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.

gh-114149 [https://github.com/python/cpython/issues/114149]: Enum: correctly handle tuple subclasses in custom __new__.

gh-109534 [https://github.com/python/cpython/issues/109534]: Fix a reference leak in asyncio.selector_events.BaseSelectorEventLoop when SSL handshakes fail. Patch contributed by Jamie Phan.

gh-114077 [https://github.com/python/cpython/issues/114077]: Fix possible OverflowError in socket.socket.sendfile() when pass count larger than 2 GiB on 32-bit platform.

gh-114014 [https://github.com/python/cpython/issues/114014]: Fixed a bug in fractions.Fraction where an invalid string using d in the decimals part creates a different error compared to other invalid letters/characters. Patch by Jeremiah Gabriel Pascual.

gh-113951 [https://github.com/python/cpython/issues/113951]: Fix the behavior of tag_unbind() methods of tkinter.Text and tkinter.Canvas classes with three arguments. Previously, 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.

gh-113877 [https://github.com/python/cpython/issues/113877]: Fix tkinter method winfo_pathname() on 64-bit Windows.

gh-113661 [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.

gh-113781 [https://github.com/python/cpython/issues/113781]: Silence unraisable AttributeError when warnings are emitted during Python finalization.

gh-112932 [https://github.com/python/cpython/issues/112932]: Restore the ability for zipfile to extractall from zip files with a "/" directory entry in them as is commonly added to zips by some wiki or bug tracker data exporters.

gh-113594 [https://github.com/python/cpython/issues/113594]: Fix UnicodeEncodeError in email when re-fold lines that contain unknown-8bit encoded part followed by non-unknown-8bit encoded part.

gh-113538 [https://github.com/python/cpython/issues/113538]: In 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.

gh-85567 [https://github.com/python/cpython/issues/85567]: Fix resource warnings for unclosed files in pickle and pickletools command line interfaces.

gh-101225 [https://github.com/python/cpython/issues/101225]: Increase the backlog for multiprocessing.connection.Listener objects created by multiprocessing.manager and multiprocessing.resource_sharer to significantly reduce the risk of getting a connection refused error when creating a multiprocessing.connection.Connection to them.

gh-113543 [https://github.com/python/cpython/issues/113543]: Make sure that webbrowser.MacOSXOSAScript sends webbrowser.open audit event.

gh-113028 [https://github.com/python/cpython/issues/113028]: When a second reference to a string appears in the input to 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.

gh-113421 [https://github.com/python/cpython/issues/113421]: Fix multiprocessing logger for %(filename)s.

gh-111784 [https://github.com/python/cpython/issues/111784]: Fix segfaults in the _elementtree module. Fix first segfault during deallocation of _elementtree.XMLParser instances by keeping strong reference to pyexpat module in module state for capsule lifetime. Fix second segfault which happens in the same deallocation process by keeping strong reference to _elementtree module in XMLParser structure for _elementtree module lifetime.

gh-113407 [https://github.com/python/cpython/issues/113407]: Fix import of unittest.mock when CPython is built without docstrings.

gh-113320 [https://github.com/python/cpython/issues/113320]: Fix regression in Python 3.12 where Protocol classes that were not marked as runtime-checkable would be unnecessarily introspected, potentially causing exceptions to be raised if the protocol had problematic members. Patch by Alex Waygood.

gh-113358 [https://github.com/python/cpython/issues/113358]: Fix rendering tracebacks for exceptions with a broken __getattr__.

gh-113214 [https://github.com/python/cpython/issues/113214]: Fix an AttributeError during asyncio SSL protocol aborts in SSL-over-SSL scenarios.

gh-113246 [https://github.com/python/cpython/issues/113246]: Update bundled pip to 23.3.2.

gh-113199 [https://github.com/python/cpython/issues/113199]: Make http.client.HTTPResponse.read1 and http.client.HTTPResponse.readline close IO after reading all data when content length is known. Patch by Illia Volochii.

gh-113188 [https://github.com/python/cpython/issues/113188]: Fix shutil.copymode() and shutil.copystat() on Windows. Previously they worked differenly 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.

gh-61648 [https://github.com/python/cpython/issues/61648]: Detect line numbers of properties in doctests.

gh-112559 [https://github.com/python/cpython/issues/112559]: signal.signal() and signal.getsignal() no longer call repr on callable handlers. asyncio.run() and asyncio.Runner.run() no longer call repr on the task results. Patch by Yilei Yang.

gh-110190 [https://github.com/python/cpython/issues/110190]: Fix ctypes structs with array on PPC64LE platform by setting MAX_STRUCT_SIZE to 64 in stgdict. Patch by Diego Russo.

gh-79429 [https://github.com/python/cpython/issues/79429]: Ignore FileNotFoundError when remove a temporary directory in the multiprocessing finalizer.

gh-81194 [https://github.com/python/cpython/issues/81194]: Fix a crash in socket.if_indextoname() with specific value (UINT_MAX). Fix an integer overflow in socket.if_indextoname() on 64-bit non-Windows platforms.

gh-112343 [https://github.com/python/cpython/issues/112343]: Improve handling of pdb convenience variables to avoid replacing string contents.

gh-111615 [https://github.com/python/cpython/issues/111615]: Fix a regression caused by a fix to gh-93162 [https://github.com/python/cpython/issues/93162] whereby you couldn't configure a QueueHandler without specifying handlers.

gh-111049 [https://github.com/python/cpython/issues/111049]: Fix crash during garbage collection of the io.BytesIO buffer object.

gh-110345 [https://github.com/python/cpython/issues/110345]: Show the Tcl/Tk patchlevel (rather than version) in tkinter._test().

gh-109858 [https://github.com/python/cpython/issues/109858]: Protect zipfile from "quoted-overlap" zipbomb. It now raises BadZipFile when try to read an entry that overlaps with other entry or central directory.

gh-114440 [https://github.com/python/cpython/issues/114440]: On Windows, closing the connection writer when cleaning up a broken multiprocessing.Queue queue is now done for all queues, rather than only in concurrent.futures manager thread. This can prevent a deadlock when a multiprocessing worker process terminates without cleaning up. This completes the backport of patches by Victor Stinner and Serhiy Storchaka.

gh-38807 [https://github.com/python/cpython/issues/38807]: Fix race condition in trace. Instead of checking if a directory exists and creating it, directly call os.makedirs() with the kwarg exist_ok=True.

gh-75705 [https://github.com/python/cpython/issues/75705]: Set unixfrom envelope in mailbox.mbox and mailbox.MMDF.

gh-106233 [https://github.com/python/cpython/issues/106233]: Fix stacklevel in InvalidTZPathWarning during zoneinfo module import.

gh-105102 [https://github.com/python/cpython/issues/105102]: Allow ctypes.Union to be nested in ctypes.Structure when the system endianness is the opposite of the classes.

gh-104282 [https://github.com/python/cpython/issues/104282]: Fix null pointer dereference in lzma._decode_filter_properties() due to improper handling of BCJ filters with properties of zero length. Patch by Radislav Chugunov.

gh-102512 [https://github.com/python/cpython/issues/102512]: When os.fork() is called from a foreign thread (aka _DummyThread), the type of the thread in a child process is changed to _MainThread. Also changed its name and daemonic status, it can be now joined.

bpo-35928 [https://bugs.python.org/issue?@action=redirect&bpo=35928]: io.TextIOWrapper now correctly handles the decoding buffer after read() and write().

bpo-26791 [https://bugs.python.org/issue?@action=redirect&bpo=26791]: 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.

bpo-36959 [https://bugs.python.org/issue?@action=redirect&bpo=36959]: Fix some error messages for invalid ISO format string combinations in strptime() that referred to directives not contained in the format string. Patch by Gordon P. Hemsley.

bpo-18060 [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.

Documentation

gh-110746 [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.

gh-95649 [https://github.com/python/cpython/issues/95649]: Document that the asyncio module contains code taken from v0.16.0 of the uvloop project [https://github.com/MagicStack/uvloop/tree/v0.16.0], as well as the required MIT licensing information.

Tests

gh-109980 [https://github.com/python/cpython/issues/109980]: Fix test_tarfile_vs_tar in test_shutil for macOS, where system tar can include more information in the archive than shutil.make_archive.

gh-105089 [https://github.com/python/cpython/issues/105089]: Fix 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 zinfo.external_attr

bpo-40648 [https://bugs.python.org/issue?@action=redirect&bpo=40648]: Test modes that file can get with chmod() on Windows.

Build

gh-112305 [https://github.com/python/cpython/issues/112305]: Fixed the check-clean-src step performed on out of tree builds to detect errant $(srcdir)/Python/frozen_modules/*.h files and recommend appropriate source tree cleanup steps to get a working build again.

gh-112867 [https://github.com/python/cpython/issues/112867]: Fix the build for the case that WITH_PYMALLOC_RADIX_TREE=0 set.

bpo-11102 [https://bugs.python.org/issue?@action=redirect&bpo=11102]: The os.major(), os.makedev(), and os.minor() functions are now available on HP-UX v3.

bpo-36351 [https://bugs.python.org/issue?@action=redirect&bpo=36351]: Do not set ipv6type when cross-compiling.

Windows

gh-109991 [https://github.com/python/cpython/issues/109991]: Update Windows build to use OpenSSL 3.0.13.

gh-111239 [https://github.com/python/cpython/issues/111239]: Update Windows builds to use zlib v1.3.1.

gh-100107 [https://github.com/python/cpython/issues/100107]: The py.exe launcher will no longer attempt to run the Microsoft Store redirector when launching a script containing a /usr/bin/env shebang

gh-114096 [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.

gh-111877 [https://github.com/python/cpython/issues/111877]: os.stat() calls were returning incorrect time values for files that could not be accessed directly.

gh-113009 [https://github.com/python/cpython/issues/113009]: multiprocessing: On Windows, fix a race condition in Process.terminate(): no longer set the returncode attribute to always call WaitForSingleObject() in Process.wait(). Previously, sometimes the process was still running after TerminateProcess() even if GetExitCodeProcess() is not STILL_ACTIVE. Patch by Victor Stinner.

gh-87868 [https://github.com/python/cpython/issues/87868]: Correctly sort and remove duplicate environment variables in _winapi.CreateProcess().

bpo-37308 [https://bugs.python.org/issue?@action=redirect&bpo=37308]: Fix mojibake in mmap.mmap when using a non-ASCII tagname argument on Windows.

macOS

gh-115009 [https://github.com/python/cpython/issues/115009]: Update macOS installer to use SQLite 3.45.1.

gh-109991 [https://github.com/python/cpython/issues/109991]: Update macOS installer to use OpenSSL 3.0.13.

gh-110459 [https://github.com/python/cpython/issues/110459]: Running configure ... --with-openssl-rpath=X/Y/Z no longer fails to detect OpenSSL on macOS.

gh-74573 [https://github.com/python/cpython/issues/74573]: Document that 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)

gh-65701 [https://github.com/python/cpython/issues/65701]: The freeze tool doesn't work with framework builds of Python. Document this and bail out early when running the tool with such a build.

gh-108269 [https://github.com/python/cpython/issues/108269]: Set 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.

gh-102362 [https://github.com/python/cpython/issues/102362]: Make sure the result of sysconfig.get_plaform() includes at least a major and minor versions, even if MACOSX_DEPLOYMENT_TARGET is set to only a major version during build to match the format expected by pip.

gh-110017 [https://github.com/python/cpython/issues/110017]: Disable a signal handling stress test on macOS due to a bug in macOS (FB13453490).

gh-110820 [https://github.com/python/cpython/issues/110820]: Make sure the preprocessor definitions for ALIGNOF_MAX_ALIGN_T, SIZEOF_LONG_DOUBLE and HAVE_GCC_ASM_FOR_X64 are correct for Universal 2 builds on macOS.

IDLE

gh-96905 [https://github.com/python/cpython/issues/96905]: In idlelib code, stop redefining built-ins 'dict' and 'object'.

gh-72284 [https://github.com/python/cpython/issues/72284]: Improve the lists of features, editor key bindings, and shell key bingings in the IDLE doc.

gh-113903 [https://github.com/python/cpython/issues/113903]: Fix rare failure of test.test_idle, in test_configdialog.

gh-113729 [https://github.com/python/cpython/issues/113729]: Fix the "Help -> IDLE Doc" menu bug in 3.11.7 and 3.12.1.

gh-113269 [https://github.com/python/cpython/issues/113269]: Fix test_editor hang on macOS Catalina.

gh-112898 [https://github.com/python/cpython/issues/112898]: Fix processing unsaved files when quitting IDLE on macOS.

gh-103820 [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.

bpo-13586 [https://bugs.python.org/issue?@action=redirect&bpo=13586]: Enter the selected text when opening the "Replace" dialog.

Tools/Demos

gh-109991 [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.

gh-115015 [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 METH_METHOD | METH_FASTCALL | METH_KEYWORDS calling convention. Only the positional parameter count was checked; any keyword argument passed would be silently accepted.

Python 3.12.1 final

Release date: 2023-12-07

Core and Builtins

gh-112125 [https://github.com/python/cpython/issues/112125]: Fix None.__ne__(None) returning NotImplemented instead of False

gh-112625 [https://github.com/python/cpython/issues/112625]: Fixes a bug where a bytearray object could be cleared while iterating over an argument in the bytearray.join() method that could result in reading memory after it was freed.

gh-105967 [https://github.com/python/cpython/issues/105967]: Workaround a bug in Apple's macOS platform zlib library where zlib.crc32() and binascii.crc32() could produce incorrect results on multi-gigabyte inputs. Including when using zipfile on zips containing large data.

gh-112356 [https://github.com/python/cpython/issues/112356]: Stopped erroneously deleting a LOAD_NULL bytecode instruction when optimized twice.

gh-111058 [https://github.com/python/cpython/issues/111058]: Change coro.cr_frame/gen.gi_frame to return None after the coroutine/generator has been closed. This fixes a bug where getcoroutinestate() and getgeneratorstate() return the wrong state for a closed coroutine/generator.

gh-112388 [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

gh-112387 [https://github.com/python/cpython/issues/112387]: Fix error positions for decoded strings with backwards tokenize errors. Patch by Pablo Galindo

gh-112367 [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

gh-112243 [https://github.com/python/cpython/issues/112243]: Don't include comments in f-string debug expressions. Patch by Pablo Galindo

gh-112266 [https://github.com/python/cpython/issues/112266]: Change docstrings of __dict__ and __weakref__.

gh-111654 [https://github.com/python/cpython/issues/111654]: Fix runtime crash when some error happens in opcode LOAD_FROM_DICT_OR_DEREF.

gh-109181 [https://github.com/python/cpython/issues/109181]: Speed up Traceback object creation by lazily compute the line number. Patch by Pablo Galindo

gh-102388 [https://github.com/python/cpython/issues/102388]: Fix a bug where iso2022_jp_3 and iso2022_jp_2004 codecs read out of bounds

gh-111366 [https://github.com/python/cpython/issues/111366]: Fix an issue in the codeop that was causing SyntaxError exceptions raised in the presence of invalid syntax to not contain precise error messages. Patch by Pablo Galindo

gh-111380 [https://github.com/python/cpython/issues/111380]: Fix a bug that was causing SyntaxWarning to appear twice when parsing if invalid syntax is encountered later. Patch by Pablo galindo

gh-94438 [https://github.com/python/cpython/issues/94438]: Fix a regression that prevented jumping across is None and is not None when debugging. Patch by Savannah Ostrowski.

gh-110938 [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

gh-109894 [https://github.com/python/cpython/issues/109894]: Fixed crash due to improperly initialized static MemoryError in subinterpreter.

gh-110782 [https://github.com/python/cpython/issues/110782]: Fix crash when typing.TypeVar is constructed with a keyword argument. Patch by Jelle Zijlstra.

gh-110696 [https://github.com/python/cpython/issues/110696]: Fix incorrect error message for invalid argument unpacking. Patch by Pablo Galindo

gh-110543 [https://github.com/python/cpython/issues/110543]: Fix regression in Python 3.12 where 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.

gh-110514 [https://github.com/python/cpython/issues/110514]: Add PY_THROW to sys.setprofile() events

gh-110455 [https://github.com/python/cpython/issues/110455]: Guard assert(tstate->thread_id > 0) with #ifndef HAVE_PTHREAD_STUBS. This allows for for pydebug builds to work under WASI which (currently) lacks thread support.

gh-110259 [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

gh-110237 [https://github.com/python/cpython/issues/110237]: Fix missing error checks for calls to PyList_Append in _PyEval_MatchClass.

gh-109889 [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.

gh-109853 [https://github.com/python/cpython/issues/109853]: sys.path[0] is now set correctly for subinterpreters.

gh-105716 [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.

gh-109793 [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.

gh-109596 [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

gh-109351 [https://github.com/python/cpython/issues/109351]: Fix crash when compiling an invalid AST involving a named (walrus) expression.

gh-109216 [https://github.com/python/cpython/issues/109216]: Fix possible memory leak in BUILD_MAP.

gh-109207 [https://github.com/python/cpython/issues/109207]: Fix a SystemError in __repr__ of symtable entry object.

gh-109179 [https://github.com/python/cpython/issues/109179]: Fix bug where the C traceback display drops notes from SyntaxError.

gh-109052 [https://github.com/python/cpython/issues/109052]: Use the base opcode when comparing code objects to avoid interference from instrumentation

gh-88943 [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.

gh-106931 [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.

Library

gh-79325 [https://github.com/python/cpython/issues/79325]: Fix an infinite recursion error in tempfile.TemporaryDirectory() cleanup on Windows.

gh-112645 [https://github.com/python/cpython/issues/112645]: Remove deprecation error on passing onerror to shutil.rmtree().

gh-112618 [https://github.com/python/cpython/issues/112618]: Fix a caching bug relating to typing.Annotated. Annotated[str, True] is no longer identical to Annotated[str, 1].

gh-112334 [https://github.com/python/cpython/issues/112334]: Fixed a performance regression in 3.12's subprocess on Linux where it would no longer use the fast-path vfork() system call when it should have due to a logic bug, instead always falling back to the safe but slower fork().

Also fixed a related 3.12 security regression: If a value of extra_groups=[] was passed to subprocess.Popen or related APIs, the underlying setgroups(0, NULL) system call to clear the groups list would not be made in the child process prior to exec(). This has been assigned CVE-2023-6507 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-6507].

This was identified via code inspection in the process of fixing the first bug.

gh-110190 [https://github.com/python/cpython/issues/110190]: Fix ctypes structs with array on Arm platform by setting MAX_STRUCT_SIZE to 32 in stgdict. Patch by Diego Russo.

gh-112578 [https://github.com/python/cpython/issues/112578]: Fix a spurious RuntimeWarning when executing the zipfile module.

gh-112509 [https://github.com/python/cpython/issues/112509]: Fix edge cases that could cause a key to be present in both the __required_keys__ and __optional_keys__ attributes of a typing.TypedDict. Patch by Jelle Zijlstra.

gh-112414 [https://github.com/python/cpython/issues/112414]: Fix regression in Python 3.12 where calling repr() on a module that had been imported using a custom loader could fail with AttributeError. Patch by Alex Waygood.

gh-112358 [https://github.com/python/cpython/issues/112358]: Revert change to struct.Struct initialization that broke some cases of subclassing.

gh-94722 [https://github.com/python/cpython/issues/94722]: Fix bug where comparison between instances of DocTest fails if one of them has None as its lineno.

gh-112105 [https://github.com/python/cpython/issues/112105]: Make readline.set_completer_delims() work with libedit

gh-111942 [https://github.com/python/cpython/issues/111942]: Fix SystemError in the TextIOWrapper constructor with non-encodable "errors" argument in non-debug mode.

gh-109538 [https://github.com/python/cpython/issues/109538]: Issue warning message instead of having RuntimeError be displayed when event loop has already been closed at StreamWriter.__del__().

gh-111942 [https://github.com/python/cpython/issues/111942]: Fix crashes in io.TextIOWrapper.reconfigure() when pass invalid arguments, e.g. non-string encoding.

gh-111460 [https://github.com/python/cpython/issues/111460]: curses: restore wide character support (including curses.unget_wch() and get_wch()) on macOS, which was unavailable due to a regression in Python 3.12.

gh-103791 [https://github.com/python/cpython/issues/103791]: contextlib.suppress now supports suppressing exceptions raised as part of a BaseExceptionGroup, in addition to the recent support for ExceptionGroup.

gh-111804 [https://github.com/python/cpython/issues/111804]: Remove posix.fallocate() under WASI as the underlying posix_fallocate() is not available in WASI preview2.

gh-111841 [https://github.com/python/cpython/issues/111841]: Fix truncating arguments on an embedded null character in os.putenv() and os.unsetenv() on Windows.

gh-111541 [https://github.com/python/cpython/issues/111541]: Fix doctest for SyntaxError not-builtin subclasses.

gh-110894 [https://github.com/python/cpython/issues/110894]: Call loop exception handler for exceptions in client_connected_cb of asyncio.start_server() so that applications can handle it. Patch by Kumar Aditya.

gh-111531 [https://github.com/python/cpython/issues/111531]: Fix reference leaks in bind_class() and bind_all() methods of tkinter widgets.

gh-111356 [https://github.com/python/cpython/issues/111356]: Added io.text_encoding(), io.DEFAULT_BUFFER_SIZE, and io.IncrementalNewlineDecoder to io.__all__.

gh-111342 [https://github.com/python/cpython/issues/111342]: Fixed typo in math.sumprod().

gh-68166 [https://github.com/python/cpython/issues/68166]: Remove mention of not supported "vsapi" element type in tkinter.ttk.Style.element_create(). Add tests for element_create() and other ttk.Style methods. Add examples for element_create() in the documentation.

gh-75666 [https://github.com/python/cpython/issues/75666]: Fix the behavior of tkinter widget's unbind() method with two arguments. Previously, 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.

gh-79033 [https://github.com/python/cpython/issues/79033]: Another attempt at fixing 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.)

gh-111295 [https://github.com/python/cpython/issues/111295]: Fix time not checking for errors when initializing.

gh-111253 [https://github.com/python/cpython/issues/111253]: Add error checking during _socket module init.

gh-111251 [https://github.com/python/cpython/issues/111251]: Fix _blake2 not checking for errors when initializing.

gh-111174 [https://github.com/python/cpython/issues/111174]: Fix crash in io.BytesIO.getbuffer() called repeatedly for empty BytesIO.

gh-111187 [https://github.com/python/cpython/issues/111187]: Postpone removal version for locale.getdefaultlocale() to Python 3.15.

gh-111159 [https://github.com/python/cpython/issues/111159]: Fix doctest output comparison for exceptions with notes.

gh-110910 [https://github.com/python/cpython/issues/110910]: Fix invalid state handling in asyncio.TaskGroup and asyncio.Timeout. They now raise proper RuntimeError if they are improperly used and are left in consistent state after this.

gh-111092 [https://github.com/python/cpython/issues/111092]: Make turtledemo run without default root enabled.

gh-110488 [https://github.com/python/cpython/issues/110488]: Fix a couple of issues in pathlib.PurePath.with_name(): a single dot was incorrectly considered a valid name, and in PureWindowsPath, a name with an NTFS alternate data stream, like a:b, was incorrectly considered invalid.

gh-110392 [https://github.com/python/cpython/issues/110392]: Fix tty.setraw() and tty.setcbreak(): previously they returned partially modified list of the original tty attributes. tty.cfmakeraw() and tty.cfmakecbreak() now make a copy of the list of special characters before modifying it.

gh-110590 [https://github.com/python/cpython/issues/110590]: Fix a bug in _sre.compile() where TypeError would be overwritten by OverflowError when the code argument was a list of non-ints.

gh-65052 [https://github.com/python/cpython/issues/65052]: Prevent pdb from crashing when trying to display undisplayable objects

gh-110519 [https://github.com/python/cpython/issues/110519]: Deprecation warning about non-integer number in gettext now alwais refers to the line in the user code where gettext function or method is used. Previously it could refer to a line in gettext code.

gh-110395 [https://github.com/python/cpython/issues/110395]: Ensure that select.kqueue() objects correctly appear as closed in forked children, to prevent operations on an invalid file descriptor.

gh-110378 [https://github.com/python/cpython/issues/110378]: contextmanager() and asynccontextmanager() context managers now close an invalid underlying generator object that yields more then one value.

gh-110365 [https://github.com/python/cpython/issues/110365]: Fix termios.tcsetattr() bug that was overwritting existing errors during parsing integers from term list.

gh-109653 [https://github.com/python/cpython/issues/109653]: Fix a Python 3.12 regression in the import time of random. Patch by Alex Waygood.

gh-110196 [https://github.com/python/cpython/issues/110196]: Add __reduce__ method to IPv6Address in order to keep scope_id

gh-110036 [https://github.com/python/cpython/issues/110036]: On Windows, multiprocessing Popen.terminate() now catchs PermissionError and get the process exit code. If the process is still running, raise again the PermissionError. Otherwise, the process terminated as expected: store its exit code. Patch by Victor Stinner.

gh-110038 [https://github.com/python/cpython/issues/110038]: Fixed an issue that caused KqueueSelector.select() to not return all the ready events in some cases when a file descriptor is registered for both read and write.

gh-109631 [https://github.com/python/cpython/issues/109631]: re functions such as re.findall(), re.split(), re.search() and re.sub() which perform short repeated matches can now be interrupted by user.

gh-109747 [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.

gh-109818 [https://github.com/python/cpython/issues/109818]: Fix reprlib.recursive_repr() not copying __type_params__ from decorated function.

gh-109047 [https://github.com/python/cpython/issues/109047]: 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 RuntimeError. Catch the exception and call terminate_broken() in this case. Patch by Victor Stinner.

gh-109782 [https://github.com/python/cpython/issues/109782]: Ensure the signature of os.path.isdir() is identical on all platforms. Patch by Amin Alaee.

gh-109590 [https://github.com/python/cpython/issues/109590]: shutil.which() will prefer files with an extension in PATHEXT if the given mode includes os.X_OK on win32. If no PATHEXT match is found, a file without an extension in PATHEXT can be returned. This change will have shutil.which() act more similarly to previous behavior in Python 3.11.

gh-109786 [https://github.com/python/cpython/issues/109786]: Fix possible reference leaks and crash when re-enter the __next__() method of itertools.pairwise.

gh-109593 [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.

gh-109613 [https://github.com/python/cpython/issues/109613]: Fix os.stat() and 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.

gh-109375 [https://github.com/python/cpython/issues/109375]: The pdb alias command now prevents registering aliases without arguments.

gh-107219 [https://github.com/python/cpython/issues/107219]: Fix a race condition in 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.

gh-50644 [https://github.com/python/cpython/issues/50644]: Attempts to pickle or create a shallow or deep copy of 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.

gh-108987 [https://github.com/python/cpython/issues/108987]: Fix _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.

gh-108791 [https://github.com/python/cpython/issues/108791]: Improved error handling in pdb command line interface, making it produce more concise error messages.

gh-105829 [https://github.com/python/cpython/issues/105829]: Fix concurrent.futures.ProcessPoolExecutor deadlock

gh-106584 [https://github.com/python/cpython/issues/106584]: Fix exit code for unittest if all tests are skipped. Patch by Egor Eliseev.

gh-102956 [https://github.com/python/cpython/issues/102956]: Fix returning of empty byte strings after seek in zipfile module

gh-84867 [https://github.com/python/cpython/issues/84867]: unittest.TestLoader no longer loads test cases from exact unittest.TestCase and unittest.FunctionTestCase classes.

gh-91133 [https://github.com/python/cpython/issues/91133]: Fix a bug in tempfile.TemporaryDirectory cleanup, which now no longer dereferences symlinks when working around file system permission errors.

gh-73561 [https://github.com/python/cpython/issues/73561]: Omit the interface scope from an IPv6 address when used as Host header by http.client.

gh-86826 [https://github.com/python/cpython/issues/86826]: 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.

bpo-43153 [https://bugs.python.org/issue?@action=redirect&bpo=43153]: On Windows, tempfile.TemporaryDirectory previously masked a PermissionError with NotADirectoryError during directory cleanup. It now correctly raises PermissionError if errors are not ignored. Patch by Andrei Kulakov and Ken Jin.

bpo-35332 [https://bugs.python.org/issue?@action=redirect&bpo=35332]: The shutil.rmtree() function now ignores errors when calling os.close() when ignore_errors is True, and os.close() no longer retried after error.

bpo-41422 [https://bugs.python.org/issue?@action=redirect&bpo=41422]: Fixed memory leaks of pickle.Pickler and pickle.Unpickler involving cyclic references via the internal memo mapping.

bpo-40262 [https://bugs.python.org/issue?@action=redirect&bpo=40262]: The ssl.SSLSocket.recv_into() method no longer requires the buffer argument to implement __len__ and supports buffers with arbitrary item size.

Documentation

gh-111699 [https://github.com/python/cpython/issues/111699]: Relocate smtpd deprecation notice to its own section rather than under locale in What's New in Python 3.12 document

gh-108826 [https://github.com/python/cpython/issues/108826]: dis module command-line interface is now mentioned in documentation.

Tests

gh-112769 [https://github.com/python/cpython/issues/112769]: The tests now correctly compare zlib version when zlib.ZLIB_RUNTIME_VERSION contains non-integer suffixes. For example zlib-ng defines the version as 1.3.0.zlib-ng.

gh-110367 [https://github.com/python/cpython/issues/110367]: Make regrtest --verbose3 option compatible with --huntrleaks -jN options. The ./python -m test -j1 -R 3:3 --verbose3 command now works as expected. Patch by Victor Stinner.

gh-111165 [https://github.com/python/cpython/issues/111165]: Remove no longer used functions run_unittest() and run_doctest() from the test.support module.

gh-110932 [https://github.com/python/cpython/issues/110932]: Fix regrtest if the SOURCE_DATE_EPOCH environment variable is defined: use the variable value as the random seed. Patch by Victor Stinner.

gh-110995 [https://github.com/python/cpython/issues/110995]: test_gdb: Fix detection of gdb built without Python scripting support. Patch by Victor Stinner.

gh-110918 [https://github.com/python/cpython/issues/110918]: Test case matching patterns specified by options --match, --ignore, --matchfile and --ignorefile are now tested in the order of specification, and the last match determines whether the test case be run or ignored.

gh-110647 [https://github.com/python/cpython/issues/110647]: Fix test_stress_modifying_handlers() of test_signal. Patch by Victor Stinner.

gh-103053 [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.

gh-110167 [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.

gh-110388 [https://github.com/python/cpython/issues/110388]: Add tests for tty.

gh-81002 [https://github.com/python/cpython/issues/81002]: Add tests for termios.

gh-110267 [https://github.com/python/cpython/issues/110267]: Add tests for pickling and copying PyStructSequence objects. Patched by Xuehai Pan.

gh-110031 [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.

gh-110088 [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 CLOCK_RES to test_asyncio.utils. Patch by Victor Stinner.

gh-109974 [https://github.com/python/cpython/issues/109974]: Fix race conditions in test_threading lock tests. Wait until a condition is met rather than using time.sleep() with a hardcoded number of seconds. Patch by Victor Stinner.

gh-110033 [https://github.com/python/cpython/issues/110033]: Fix test_interprocess_signal() of test_signal. Make sure that the subprocess.Popen object is deleted before the test raising an exception in a signal handler. Otherwise, Popen.__del__() can get the exception which is logged as Exception ignored in: ... and the test fails. Patch by Victor Stinner.

gh-109594 [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 ot not. Keep the second future which does not complete before wait() timeout. Patch by Victor Stinner.

gh-109972 [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.

gh-103053 [https://github.com/python/cpython/issues/103053]: Skip test_freeze_simple_script() of test_tools.test_freeze if Python is built with ./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.

gh-109580 [https://github.com/python/cpython/issues/109580]: Skip 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.

gh-104736 [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 Backtrace stopped: frame did not save the PC is found. Patch by Victor Stinner.

gh-108927 [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.

Build

gh-112088 [https://github.com/python/cpython/issues/112088]: Add Tools/build/regen-configure.sh script to regenerate the configure with an Ubuntu container image. The quay.io/tiran/cpython_autoconf:271 container image (tiran/cpython_autoconf [https://github.com/tiran/cpython_autoconf]) is no longer used. Patch by Victor Stinner.

gh-111046 [https://github.com/python/cpython/issues/111046]: For wasi-threads, memory is now exported to fix compatibility issues with some wasm runtimes.

gh-103053 [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.

gh-109191 [https://github.com/python/cpython/issues/109191]: Fix compile error when building with recent versions of libedit.

Windows

gh-111856 [https://github.com/python/cpython/issues/111856]: Fixes fstat() on file systems that do not support file ID requests. This includes FAT32 and exFAT.

gh-111293 [https://github.com/python/cpython/issues/111293]: Fix os.DirEntry.inode dropping higher 64 bits of a file id on some filesystems on Windows.

gh-110913 [https://github.com/python/cpython/issues/110913]: WindowsConsoleIO now correctly chunks large buffers without splitting up UTF-8 sequences.

gh-110437 [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.

gh-109286 [https://github.com/python/cpython/issues/109286]: Update Windows installer to use SQLite 3.43.1.

macOS

gh-109981 [https://github.com/python/cpython/issues/109981]: Use /dev/fd on macOS to determine the number of open files in test.support.os_helper.fd_count to avoid a crash with "guarded" file descriptors when probing for open files.

gh-110950 [https://github.com/python/cpython/issues/110950]: Update macOS installer to include an upstream Tcl/Tk fix for the Secure coding is not enabled for restorable state! warning encountered in Tkinter on macOS 14 Sonoma.

gh-111015 [https://github.com/python/cpython/issues/111015]: Ensure that IDLE.app and Python Launcher.app are installed with appropriate permissions on macOS builds.

gh-109286 [https://github.com/python/cpython/issues/109286]: Update macOS installer to use SQLite 3.43.1.

gh-71383 [https://github.com/python/cpython/issues/71383]: Update macOS installer to include an upstream Tcl/Tk fix for the ttk::ThemeChanged error encountered in Tkinter.

gh-92603 [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 tkinter.Tk() instance is destroyed.

IDLE

bpo-35668 [https://bugs.python.org/issue?@action=redirect&bpo=35668]: Add docstrings to the IDLE debugger module. Fix two bugs: initialize Idb.botframe (should be in Bdb); in Idb.in_rpc_code, check whether prev_frame is None before trying to use it. Greatly expand test_debugger.

C API

gh-106560 [https://github.com/python/cpython/issues/106560]: Fix redundant declarations in the public C API. Declare PyBool_Type and PyLong_Type only once. Patch by Victor Stinner.

gh-112438 [https://github.com/python/cpython/issues/112438]: Fix support of format units "es", "et", "es#", and "et#" in nested tuples in PyArg_ParseTuple()-like functions.

gh-109521 [https://github.com/python/cpython/issues/109521]: PyImport_GetImporter() now sets RuntimeError if it fails to get sys.path_hooks or 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.

Python 3.12.0 final

Release date: 2023-10-02

Core and Builtins

gh-109823 [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.

gh-109719 [https://github.com/python/cpython/issues/109719]: Fix missing jump target labels when compiler reorders cold/warm blocks.

gh-109627 [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.

Library

gh-110045 [https://github.com/python/cpython/issues/110045]: Update the symtable module to support the new scopes introduced by PEP 695 [https://peps.python.org/pep-0695/].

Documentation

gh-109209 [https://github.com/python/cpython/issues/109209]: The minimum Sphinx version required for the documentation is now 4.2.

Windows

gh-109991 [https://github.com/python/cpython/issues/109991]: Update Windows build to use OpenSSL 3.0.11.

macOS

gh-109991 [https://github.com/python/cpython/issues/109991]: Update macOS installer to use OpenSSL 3.0.11.

Tools/Demos

gh-109991 [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.

Python 3.12.0 release candidate 3

Release date: 2023-09-18

Core and Builtins

gh-109496 [https://github.com/python/cpython/issues/109496]: On a Python built in debug mode, Py_DECREF() now calls _Py_NegativeRefcount() if the object is a dangling pointer to deallocated memory: memory filled with 0xDD "dead byte" by the debug hook on memory allocators. The fix is to check the reference count before checking for _Py_IsImmortal(). Patch by Victor Stinner.

gh-109371 [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

gh-105658 [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.

gh-109219 [https://github.com/python/cpython/issues/109219]: Fix compiling type param scopes that use a name which is also free in an inner scope.

gh-109341 [https://github.com/python/cpython/issues/109341]: Fix crash when compiling an invalid AST involving a ast.TypeAlias.

gh-109195 [https://github.com/python/cpython/issues/109195]: Fix source location for the LOAD_* instruction preceding a LOAD_SUPER_ATTR to load the super global (or shadowing variable) so that it encompasses only the name super and not the following parentheses.

gh-109118 [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.

gh-109114 [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

gh-109118 [https://github.com/python/cpython/issues/109118]: Fix interpreter crash when a NameError is raised inside the type parameters of a generic class.

gh-108976 [https://github.com/python/cpython/issues/108976]: Fix crash that occurs after de-instrumenting a code object in a monitoring callback.

gh-108732 [https://github.com/python/cpython/issues/108732]: Make iteration variables of module- and class-scoped comprehensions visible to pdb and other tools that use frame.f_locals again.

gh-108959 [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

Library

gh-108682 [https://github.com/python/cpython/issues/108682]: Enum: require names=() or type=... to create an empty enum using the functional syntax.

gh-108843 [https://github.com/python/cpython/issues/108843]: Fix an issue in ast.unparse() when unparsing f-strings containing many quote types.

Documentation

gh-102823 [https://github.com/python/cpython/issues/102823]: Document the return type of x // y when x and y have type float.

Tests

gh-109396 [https://github.com/python/cpython/issues/109396]: Fix 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.

gh-104736 [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 Backtrace stopped: frame did not save the PC is found. Patch by Victor Stinner.

gh-109237 [https://github.com/python/cpython/issues/109237]: Fix test_site.test_underpth_basic() when the working directory contains at least one non-ASCII character: encode the ._pth file to UTF-8 and enable the UTF-8 Mode to use UTF-8 for the child process stdout. Patch by Victor Stinner.

gh-109230 [https://github.com/python/cpython/issues/109230]: Fix 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.

gh-109015 [https://github.com/python/cpython/issues/109015]: Fix test_asyncio, test_imaplib and test_socket tests on FreeBSD if the TCP blackhole is enabled (sysctl net.inet.tcp.blackhole). Skip the few tests which failed with ETIMEDOUT which such non standard configuration. Currently, the FreeBSD GCP image enables TCP and UDP blackhole [https://reviews.freebsd.org/D41751] (sysctl net.inet.tcp.blackhole=2 and sysctl net.inet.udp.blackhole=1). Patch by Victor Stinner.

gh-91960 [https://github.com/python/cpython/issues/91960]: Skip test_gdb if gdb is unable to retrieve Python frame objects: if a frame is <optimized out>. When Python is built with "clang -Og", gdb can fail to retrive the frame parameter of _PyEval_EvalFrameDefault(). In this case, tests like py_bt() are likely to fail. Without getting access to Python frames, python-gdb.py is mostly clueless on retrieving the Python traceback. Moreover, test_gdb is no longer skipped on macOS if Python is built with Clang. Patch by Victor Stinner.

gh-108962 [https://github.com/python/cpython/issues/108962]: Skip test_tempfile.test_flags() if chflags() fails with "OSError: [Errno 45] Operation not supported" (ex: on FreeBSD 13). Patch by Victor Stinner.

gh-108851 [https://github.com/python/cpython/issues/108851]: Fix 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.

gh-108851 [https://github.com/python/cpython/issues/108851]: Add get_recursion_available() and get_recursion_depth() functions to the test.support module. Patch by Victor Stinner.

gh-108834 [https://github.com/python/cpython/issues/108834]: Add --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.

gh-108834 [https://github.com/python/cpython/issues/108834]: Rename regrtest --verbose2 option (-w) to --rerun. Keep --verbose2 as a deprecated alias. Patch by Victor Stinner.

gh-108834 [https://github.com/python/cpython/issues/108834]: When regrtest reruns failed tests in verbose mode (./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 -jN option is used to run tests in parallel. Patch by Victor Stinner.

gh-103186 [https://github.com/python/cpython/issues/103186]: Suppress and assert expected RuntimeWarnings in test_sys_settrace.py

Build

gh-108740 [https://github.com/python/cpython/issues/108740]: Fix a race condition in make regen-all. The 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.

Python 3.12.0 release candidate 2

Release date: 2023-09-05

Security

gh-108310 [https://github.com/python/cpython/issues/108310]: Fixed an issue where instances of 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 CVE-2023-40217 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-40217] by Aapo Oksman. Patch by Gregory P. Smith.

gh-107774 [https://github.com/python/cpython/issues/107774]: PEP 669 specifies that 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.

Core and Builtins

gh-108520 [https://github.com/python/cpython/issues/108520]: Fix multiprocessing.synchronize.SemLock.__setstate__() to properly initialize multiprocessing.synchronize.SemLock._is_fork_ctx. This fixes a regression when passing a SemLock accross nested processes.

Rename multiprocessing.synchronize.SemLock.is_fork_ctx to multiprocessing.synchronize.SemLock._is_fork_ctx to avoid exposing it as public API.

gh-108654 [https://github.com/python/cpython/issues/108654]: Restore locals shadowed by an inlined comprehension if the comprehension raises an exception.

gh-108487 [https://github.com/python/cpython/issues/108487]: Change an assert that would cause a spurious crash in a devious case that should only trigger deoptimization.

gh-106176 [https://github.com/python/cpython/issues/106176]: Use a 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.

gh-107901 [https://github.com/python/cpython/issues/107901]: Fix missing line number on JUMP_BACKWARD at the end of a for loop.

gh-108390 [https://github.com/python/cpython/issues/108390]: Raise an exception when setting a non-local event (RAISE, EXCEPTION_HANDLED, etc.) in sys.monitoring.set_local_events.

Fixes crash when tracing in recursive calls to Python classes.

gh-91051 [https://github.com/python/cpython/issues/91051]: Fix abort / segfault when using all eight type watcher slots, on platforms where char is signed by default.

gh-107724 [https://github.com/python/cpython/issues/107724]: In pre-release versions of 3.12, up to rc1, the sys.monitoring callback function for the PY_THROW event was missing the third, exception argument. That is now fixed.

gh-107080 [https://github.com/python/cpython/issues/107080]: Trace refs builds (--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.

gh-77377 [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.

Library

gh-108469 [https://github.com/python/cpython/issues/108469]: ast.unparse() now supports new f-string syntax introduced in Python 3.12. Note that the f-string quotes are reselected for simplicity under the new syntax. (Patch by Steven Sun)

gh-108682 [https://github.com/python/cpython/issues/108682]: Enum: raise TypeError if super().__new__() is called from a custom __new__.

gh-108295 [https://github.com/python/cpython/issues/108295]: Fix crashes related to use of weakrefs on typing.TypeVar.

gh-64662 [https://github.com/python/cpython/issues/64662]: Fix support for virtual tables in sqlite3.Connection.iterdump(). Patch by Aviv Palivoda.

gh-108111 [https://github.com/python/cpython/issues/108111]: Fix a regression introduced in gh-101251 [https://github.com/python/cpython/issues/101251] for 3.12, resulting in an incorrect offset calculation in gzip.GzipFile.seek().

gh-105736 [https://github.com/python/cpython/issues/105736]: Harmonized the pure Python version of OrderedDict with the C version. Now, both versions set up their internal state in __new__. Formerly, the pure Python version did the set up in __init__.

gh-108083 [https://github.com/python/cpython/issues/108083]: Fix bugs in the constructor of sqlite3.Connection and sqlite3.Connection.close() where exceptions could be leaked. Patch by Erlend E. Aasland.

gh-107963 [https://github.com/python/cpython/issues/107963]: Fix multiprocessing.set_forkserver_preload() to check the given list of modules names. Patch by Donghee Na.

gh-106242 [https://github.com/python/cpython/issues/106242]: Fixes os.path.normpath() to handle embedded null characters without truncating the path.

gh-107913 [https://github.com/python/cpython/issues/107913]: Fix possible losses of errno and winerror values in OSError exceptions if they were cleared or modified by the cleanup code before creating the exception object.

gh-107845 [https://github.com/python/cpython/issues/107845]: 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 LinkOutsideDestinationError.

gh-107805 [https://github.com/python/cpython/issues/107805]: Fix signatures of module-level generated functions in turtle.

gh-107715 [https://github.com/python/cpython/issues/107715]: Fix doctest.DocTestFinder.find() in presence of class names with special characters. Patch by Gertjan van Zwieten.

gh-100814 [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.

gh-106684 [https://github.com/python/cpython/issues/106684]: Close asyncio.StreamWriter when it is not closed by application leading to memory leaks. Patch by Kumar Aditya.

gh-107396 [https://github.com/python/cpython/issues/107396]: tarfiles; Fixed use before assignment of self.exception for gzip decompression

gh-106052 [https://github.com/python/cpython/issues/106052]: re module: fix the matching of possessive quantifiers in the case of a subpattern containing backtracking.

gh-100061 [https://github.com/python/cpython/issues/100061]: Fix a bug that causes wrong matches for regular expressions with possessive qualifier.

gh-99203 [https://github.com/python/cpython/issues/99203]: Restore following CPython <= 3.10.5 behavior of shutil.make_archive(): do not create an empty archive if root_dir is not a directory, and, in that case, raise FileNotFoundError or NotADirectoryError regardless of format choice. Beyond the brought-back behavior, the function may now also raise these exceptions in dry_run mode.

Documentation

gh-105052 [https://github.com/python/cpython/issues/105052]: Update timeit doc to specify that time in seconds is just the default.

Tests

gh-89392 [https://github.com/python/cpython/issues/89392]: Removed support of test_main() function in tests. They now always use normal unittest test runner.

gh-108388 [https://github.com/python/cpython/issues/108388]: Convert test_concurrent_futures to a package of 7 sub-tests. Patch by Victor Stinner.

gh-108388 [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.

gh-105776 [https://github.com/python/cpython/issues/105776]: Fix test_cppext when the C compiler command -std=c11 option: remove -std= options from the compiler command. Patch by Victor Stinner.

gh-107178 [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.

Build

gh-63760 [https://github.com/python/cpython/issues/63760]: Fix Solaris build: no longer redefine the gethostname() function. Solaris defines the function since 2005. Patch by Victor Stinner, original patch by Jakub Kulík.

gh-107814 [https://github.com/python/cpython/issues/107814]: When calling find_python.bat with -q it did not properly silence the output of nuget. That is now fixed.

Windows

gh-107565 [https://github.com/python/cpython/issues/107565]: Update Windows build to use OpenSSL 3.0.10.

gh-106242 [https://github.com/python/cpython/issues/106242]: Fixes realpath() to behave consistently when passed a path containing an embedded null character on Windows. In strict mode, it now raises OSError instead of the unexpected ValueError, and in non-strict mode will make the path absolute.

gh-106844 [https://github.com/python/cpython/issues/106844]: Fix integer overflow and truncating by the null character in _winapi.LCMapStringEx() which affects ntpath.normcase().

macOS

gh-107565 [https://github.com/python/cpython/issues/107565]: Update macOS installer to use OpenSSL 3.0.10.

Tools/Demos

gh-107565 [https://github.com/python/cpython/issues/107565]: Update multissltests and GitHub CI workflows to use OpenSSL 1.1.1v, 3.0.10, and 3.1.2.

gh-95065 [https://github.com/python/cpython/issues/95065]: Argument Clinic now supports overriding automatically generated signature by using directive @text_signature.

C API

gh-107916 [https://github.com/python/cpython/issues/107916]: C API functions PyErr_SetFromErrnoWithFilename(), PyErr_SetExcFromWindowsErrWithFilename() and PyErr_SetFromWindowsErrWithFilename() save now the error code before calling PyUnicode_DecodeFSDefault().

gh-107915 [https://github.com/python/cpython/issues/107915]: Such C API functions as PyErr_SetString(), PyErr_Format(), 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.

gh-107810 [https://github.com/python/cpython/issues/107810]: Improve DeprecationWarning for uses of PyType_Spec with metaclasses that have custom tp_new.

Python 3.12.0 release candidate 1

Release date: 2023-08-05

Security

gh-102988 [https://github.com/python/cpython/issues/102988]: Reverted the email.utils security improvement change released in 3.12beta4 that unintentionally caused email.utils.getaddresses to fail to parse email addresses with a comma in the quoted name field. See gh-106669 [https://github.com/python/cpython/issues/106669].

gh-102509 [https://github.com/python/cpython/issues/102509]: Start initializing ob_digit during creation of PyLongObject objects. Patch by Illia Volochii.

Core and Builtins

gh-107263 [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 list.__repr__ and json.dumps to handle all the inputs that they could prior to 3.12

gh-104432 [https://github.com/python/cpython/issues/104432]: Fix potential unaligned memory access on C APIs involving returned sequences of char * pointers within the grp and socket modules. These were revealed using a -fsaniziter=alignment build on ARM macOS. Patch by Christopher Chavez.

gh-106898 [https://github.com/python/cpython/issues/106898]: Add the exception as the third argument to PY_UNIND callbacks in sys.monitoring. This makes the PY_UNWIND callback consistent with the other exception hanlding callbacks.

gh-106895 [https://github.com/python/cpython/issues/106895]: Raise a ValueError when a monitoring callback funtion returns DISABLE for events that cannot be disabled locally.

gh-106897 [https://github.com/python/cpython/issues/106897]: Add a RERAISE event to sys.monitoring, which occurs when an exception is reraised, either explicitly by a plain raise statement, or implicitly in an except or finally block.

gh-104621 [https://github.com/python/cpython/issues/104621]: Unsupported modules now always fail to be imported.

gh-106917 [https://github.com/python/cpython/issues/106917]: Fix classmethod-style super() method calls (i.e., where the second argument to super(), or the implied second argument drawn from self/cls in the case of zero-arg super, is a type) when the target of the call is not a classmethod.

gh-105699 [https://github.com/python/cpython/issues/105699]: Python no longer crashes due an infrequent race when initialzing per-interpreter interned strings. The crash would manifest when the interpreter was finalized.

gh-105699 [https://github.com/python/cpython/issues/105699]: Python no longer crashes due to an infrequent race in setting Py_FileSystemDefaultEncoding and Py_FileSystemDefaultEncodeErrors (both deprecated), when simultaneously initializing two isolated subinterpreters. Now they are only set during runtime initialization.

gh-106092 [https://github.com/python/cpython/issues/106092]: Fix a segmentation fault caused by a use-after-free bug in frame_dealloc when the trashcan delays the deallocation of a PyFrameObject.

gh-106719 [https://github.com/python/cpython/issues/106719]: No longer suppress arbitrary errors in the __annotations__ getter and setter in the type and module types.

gh-106723 [https://github.com/python/cpython/issues/106723]: Propagate frozen_modules to multiprocessing spawned process interpreters.

gh-105235 [https://github.com/python/cpython/issues/105235]: Prevent out-of-bounds memory access during mmap.find() calls.

Library

gh-107077 [https://github.com/python/cpython/issues/107077]: Seems that in some conditions, OpenSSL will return SSL_ERROR_SYSCALL instead of SSL_ERROR_SSL when a certification verification has failed, but the error parameters will still contain ERR_LIB_SSL and SSL_R_CERTIFICATE_VERIFY_FAILED. We are now detecting this situation and raising the appropiate ssl.SSLCertVerificationError. Patch by Pablo Galindo

gh-107576 [https://github.com/python/cpython/issues/107576]: Fix types.get_original_bases() to only return __orig_bases__ if it is present on cls directly. Patch by James Hilton-Balfe.

gh-46376 [https://github.com/python/cpython/issues/46376]: Prevent memory leak and use-after-free when using pointers to pointers with ctypes

gh-62519 [https://github.com/python/cpython/issues/62519]: Make gettext.pgettext() search plural definitions when translation is not found.

gh-83006 [https://github.com/python/cpython/issues/83006]: Document behavior of shutil.disk_usage() for non-mounted filesystems on Unix.

gh-106186 [https://github.com/python/cpython/issues/106186]: Do not report MultipartInvariantViolationDefect defect when the email.parser.Parser class is used to parse emails with headersonly=True.

gh-105002 [https://github.com/python/cpython/issues/105002]: Fix invalid result from PurePath.relative_to() method when attempting to walk a ".." segment in other with walk_up enabled. A ValueError exception is now raised in this case.

gh-106831 [https://github.com/python/cpython/issues/106831]: Fix potential missing NULL check of d2i_SSL_SESSION result in _ssl.c.

gh-106774 [https://github.com/python/cpython/issues/106774]: Update the bundled copy of pip to version 23.2.1.

gh-106752 [https://github.com/python/cpython/issues/106752]: Fixed several bugs in zipfile.Path, including: in Path.match, Windows separators are no longer honored (and never were meant to be); Fixed name/suffix/suffixes/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.

gh-106602 [https://github.com/python/cpython/issues/106602]: Add __copy__ and __deepcopy__ in enum

gh-106530 [https://github.com/python/cpython/issues/106530]: Revert a change to colorsys.rgb_to_hls() that caused division by zero for certain almost-white inputs. Patch by Terry Jan Reedy.

gh-106403 [https://github.com/python/cpython/issues/106403]: Instances of typing.TypeVar, typing.ParamSpec, typing.ParamSpecArgs, typing.ParamSpecKwargs, and typing.TypeVarTuple once again support weak references, fixing a regression introduced in Python 3.12.0 beta 1. Patch by Jelle Zijlstra.

gh-106350 [https://github.com/python/cpython/issues/106350]: Detect possible memory allocation failure in the libtommath function mp_init() used by the _tkinter module.

gh-106263 [https://github.com/python/cpython/issues/106263]: Fix crash when calling repr with a manually constructed SignalDict object. Patch by Charlie Zhao.

gh-105626 [https://github.com/python/cpython/issues/105626]: Change the default return value of http.client.HTTPConnection.get_proxy_response_headers() to be None and not {}.

bpo-18319 [https://bugs.python.org/issue?@action=redirect&bpo=18319]: Ensure gettext(msg) retrieve translations even if a plural form exists. In other words: gettext(msg) == ngettext(msg, '', 1).

Documentation

gh-107305 [https://github.com/python/cpython/issues/107305]: Add documentation for PyInterpreterConfig and Py_NewInterpreterFromConfig(). Also clarify some of the nearby docs relative to per-interpreter GIL.

gh-107008 [https://github.com/python/cpython/issues/107008]: Document the curses module variables LINES and COLS.

gh-106948 [https://github.com/python/cpython/issues/106948]: Add a number of standard external names to nitpick_ignore.

gh-54738 [https://github.com/python/cpython/issues/54738]: Add documentation on how to localize the argparse module.

Tests

gh-107237 [https://github.com/python/cpython/issues/107237]: test_logging: Fix test_udp_reconnection() by increasing the timeout from 100 ms to 5 minutes (LONG_TIMEOUT). Patch by Victor Stinner.

gh-106714 [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.

gh-104090 [https://github.com/python/cpython/issues/104090]: Avoid creating a reference to the test object in collectedDurations().

gh-106752 [https://github.com/python/cpython/issues/106752]: Moved tests for zipfile.Path into Lib/test/test_zipfile/_path. Made zipfile._path a package.

Build

gh-106881 [https://github.com/python/cpython/issues/106881]: Check for linux/limits.h before including it in Modules/posixmodule.c.

gh-106962 [https://github.com/python/cpython/issues/106962]: Detect MPI compilers in configure.

gh-101538 [https://github.com/python/cpython/issues/101538]: Add experimental wasi-threads support. Patch by Takashi Yamamoto.

Windows

gh-99079 [https://github.com/python/cpython/issues/99079]: Update Windows build to use OpenSSL 3.0.9

macOS

gh-99079 [https://github.com/python/cpython/issues/99079]: Update macOS installer to use OpenSSL 3.0.9.

Tools/Demos

gh-106970 [https://github.com/python/cpython/issues/106970]: Fix bugs in the Argument Clinic destination <name> clear command; the destination buffers would never be cleared, and the destination directive parser would simply continue to the fault handler after processing the command. Patch by Erlend E. Aasland.

gh-103186 [https://github.com/python/cpython/issues/103186]: freeze now fetches CONFIG_ARGS from the original CPython instance the Makefile uses to call utility scripts. Patch by Ijtaba Hussain.

C API

gh-107226 [https://github.com/python/cpython/issues/107226]: PyModule_AddObjectRef() is now only available in the limited API version 3.10 or later.

Python 3.12.0 beta 4

Release date: 2023-07-11

Security

gh-102988 [https://github.com/python/cpython/issues/102988]: CVE-2023-27043 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-27043]: Prevent email.utils.parseaddr() and email.utils.getaddresses() from returning the realname portion of an invalid RFC2822 email header in the email address portion of the 2-tuple returned after being parsed by email._parseaddr.AddressList.

Core and Builtins

gh-106396 [https://github.com/python/cpython/issues/106396]: When the format specification of an f-string expression is empty, the parser now generates an empty ast.JoinedStr node for it instead of an one-element ast.JoinedStr with an empty string ast.Constant.

gh-106145 [https://github.com/python/cpython/issues/106145]: Make end_lineno and end_col_offset required on type_param ast nodes.

gh-105979 [https://github.com/python/cpython/issues/105979]: Fix crash in _imp.get_frozen_object() due to improper exception handling.

gh-98931 [https://github.com/python/cpython/issues/98931]: Ensure custom SyntaxError error messages are raised for invalid imports with multiple targets. Patch by Pablo Galindo

gh-105908 [https://github.com/python/cpython/issues/105908]: Fixed bug where gh-99111 [https://github.com/python/cpython/issues/99111] breaks future import barry_as_FLUFL in the Python REPL.

gh-105340 [https://github.com/python/cpython/issues/105340]: Include the comprehension iteration variable in locals() inside a module- or class-scope comprehension.

gh-105486 [https://github.com/python/cpython/issues/105486]: Change the repr of ParamSpec list of args in types.GenericAlias.

gh-101006 [https://github.com/python/cpython/issues/101006]: Improve error handling when read marshal data.

Library

gh-106524 [https://github.com/python/cpython/issues/106524]: Fix crash in _sre.template() with templates containing invalid group indices.

gh-106510 [https://github.com/python/cpython/issues/106510]: Improve debug output for atomic groups in regular expressions.

gh-106503 [https://github.com/python/cpython/issues/106503]: Fix ref cycle in asyncio._SelectorSocketTransport by removing _write_ready in close.

gh-105497 [https://github.com/python/cpython/issues/105497]: Fix flag mask inversion when unnamed flags exist.

gh-90876 [https://github.com/python/cpython/issues/90876]: Prevent multiprocessing.spawn from failing to import in environments where sys.executable is None. This regressed in 3.11 with the addition of support for path-like objects in multiprocessing.

gh-106292 [https://github.com/python/cpython/issues/106292]: Check for an instance-dict cached value in the __get__() method of functools.cached_property(). This better matches the pre-3.12 behavior and improves compatibility for users subclassing functools.cached_property() and adding a __set__() method.

gh-106330 [https://github.com/python/cpython/issues/106330]: Fix incorrect matching of empty paths in pathlib.PurePath.match(). This bug was introduced in Python 3.12.0 beta 1.

gh-102541 [https://github.com/python/cpython/issues/102541]: Make pydoc.doc catch bad module ImportError when output stream is not None.

gh-106152 [https://github.com/python/cpython/issues/106152]: Added PY_THROW event hook for cProfile for generators

gh-106075 [https://github.com/python/cpython/issues/106075]: Added asyncio.taskgroups.__all__ to asyncio.__all__ for export in star imports.

gh-105987 [https://github.com/python/cpython/issues/105987]: Fix crash due to improper reference counting in asyncio eager task factory internal routines.

gh-105974 [https://github.com/python/cpython/issues/105974]: Fix bug where a typing.Protocol class that had one or more non-callable members would raise TypeError when issubclass() was called against it, even if it defined a custom __subclasshook__ method. The behaviour in Python 3.11 and lower -- which has now been restored -- was not to raise TypeError in these situations if a custom __subclasshook__ method was defined. Patch by Alex Waygood.

gh-96145 [https://github.com/python/cpython/issues/96145]: Reverted addition of json.AttrDict.

gh-105497 [https://github.com/python/cpython/issues/105497]: Fix flag inversion when alias/mask members exist.

gh-104554 [https://github.com/python/cpython/issues/104554]: Add RTSPS scheme support in urllib.parse

gh-94777 [https://github.com/python/cpython/issues/94777]: Fix hanging multiprocessing ProcessPoolExecutor when a child process crashes while data is being written in the call queue.

Documentation

gh-106232 [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.

Tests

gh-101634 [https://github.com/python/cpython/issues/101634]: When running the Python test suite with -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.

Build

gh-106118 [https://github.com/python/cpython/issues/106118]: Fix compilation for platforms without O_CLOEXEC. The issue was introduced with Python 3.12b1 in gh-103295 [https://github.com/python/cpython/issues/103295]. Patch by Erlend Aasland.

gh-104692 [https://github.com/python/cpython/issues/104692]: Include commoninstall as a prerequisite for bininstall

This ensures that commoninstall is completed before bininstall is started when parallel builds are used (make -j install), and so the python3 symlink is only installed after all standard library modules are installed.

Tools/Demos

gh-106359 [https://github.com/python/cpython/issues/106359]: Argument Clinic now explicitly forbids "kwarg splats" in function calls used as annotations.

C API

gh-105227 [https://github.com/python/cpython/issues/105227]: The new PyType_GetDict() provides the dictionary for the given type object that is normally exposed by cls.__dict__. Normally it's sufficient to use tp_dict, but for the static builtin types tp_dict is now always NULL. PyType_GetDict() provides the correct dict object instead.

Python 3.12.0 beta 3

Release date: 2023-06-19

Core and Builtins

gh-105840 [https://github.com/python/cpython/issues/105840]: Fix possible crashes when specializing function calls with too many __defaults__.

gh-105831 [https://github.com/python/cpython/issues/105831]: Fix an f-string bug, where using a debug expression (the = 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.

gh-105800 [https://github.com/python/cpython/issues/105800]: Correctly issue SyntaxWarning in f-strings if invalid sequences are used. Patch by Pablo Galindo

gh-105587 [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.

gh-105564 [https://github.com/python/cpython/issues/105564]: Don't include artificil newlines in the line attribute of tokens in the APIs of the tokenize module. Patch by Pablo Galindo

gh-105549 [https://github.com/python/cpython/issues/105549]: Tokenize separately NUMBER and NAME tokens that are not ambiguous. Patch by Pablo Galindo.

gh-105588 [https://github.com/python/cpython/issues/105588]: Fix an issue that could result in crashes when compiling malformed ast nodes.

gh-105375 [https://github.com/python/cpython/issues/105375]: Fix bugs in the builtins module where exceptions could end up being overwritten.

gh-105375 [https://github.com/python/cpython/issues/105375]: Fix bug in the compiler where an exception could end up being overwritten.

gh-105375 [https://github.com/python/cpython/issues/105375]: Improve error handling in PyUnicode_BuildEncodingMap() where an exception could end up being overwritten.

gh-105435 [https://github.com/python/cpython/issues/105435]: Fix spurious newline character if file ends on a comment without a newline. Patch by Pablo Galindo

gh-105390 [https://github.com/python/cpython/issues/105390]: Correctly raise tokenize.TokenError exceptions instead of SyntaxError for tokenize errors such as incomplete input. Patch by Pablo Galindo

gh-104812 [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 (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.

Library

gh-105808 [https://github.com/python/cpython/issues/105808]: Fix a regression introduced in gh-101251 [https://github.com/python/cpython/issues/101251] for 3.12, causing gzip.GzipFile.flush() to not flush the compressor (nor pass along the zip_mode argument).

gh-104799 [https://github.com/python/cpython/issues/104799]: Enable ast.unparse() to unparse function and class definitions created without the new type_params field from PEP 695 [https://peps.python.org/pep-0695/]. Patch by Jelle Zijlstra.

gh-105745 [https://github.com/python/cpython/issues/105745]: Fix webbrowser.Konqueror.open method.

gh-105375 [https://github.com/python/cpython/issues/105375]: Fix a bug in _Unpickler_SetInputStream() where an exception could end up being overwritten in case of failure.

gh-105375 [https://github.com/python/cpython/issues/105375]: Fix bugs in sys where exceptions could end up being overwritten because of deferred error handling.

gh-105605 [https://github.com/python/cpython/issues/105605]: Harden pyexpat error handling during module initialisation to prevent exceptions from possibly being overwritten, and objects from being dereferenced twice.

gh-105375 [https://github.com/python/cpython/issues/105375]: Fix bug in decimal where an exception could end up being overwritten.

gh-105375 [https://github.com/python/cpython/issues/105375]: Fix bugs in _datetime where exceptions could be overwritten in case of module initialisation failure.

gh-105375 [https://github.com/python/cpython/issues/105375]: Fix bugs in _ssl initialisation which could lead to leaked references and overwritten exceptions.

gh-105375 [https://github.com/python/cpython/issues/105375]: Fix a bug in array.array where an exception could end up being overwritten.

gh-105375 [https://github.com/python/cpython/issues/105375]: Fix bugs in _ctypes where exceptions could end up being overwritten.

gh-105375 [https://github.com/python/cpython/issues/105375]: Fix a bug in the posix module where an exception could be overwritten.

gh-105375 [https://github.com/python/cpython/issues/105375]: Fix bugs in _elementtree where exceptions could be overwritten.

gh-105375 [https://github.com/python/cpython/issues/105375]: Fix bugs in zoneinfo where exceptions could be overwritten.

gh-105375 [https://github.com/python/cpython/issues/105375]: Fix bugs in errno where exceptions could be overwritten.

gh-105375 [https://github.com/python/cpython/issues/105375]: Fix bugs in pickle where exceptions could be overwritten.

gh-105375 [https://github.com/python/cpython/issues/105375]: Fix a bug in sqlite3 where an exception could be overwritten in the collation callback.

gh-105332 [https://github.com/python/cpython/issues/105332]: Revert pickling method from by-name back to by-value.

gh-104310 [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 allowing_all_extensions to _incompatible_extension_module_restrictions. The default for the "disable_check" argument has change from True to False, to better match the new function name.

gh-104996 [https://github.com/python/cpython/issues/104996]: Improve performance of pathlib.PurePath initialisation by deferring joining of paths when multiple arguments are given.

gh-102541 [https://github.com/python/cpython/issues/102541]: Hide traceback in help() prompt, when import failed.

Tests

gh-105084 [https://github.com/python/cpython/issues/105084]: When the Python build is configured --with-wheel-pkg-dir, tests requiring the setuptools and wheel wheels will search for the wheels in WHEEL_PKG_DIR.

Windows

gh-105436 [https://github.com/python/cpython/issues/105436]: Ensure that an empty environment block is terminated by two null characters, as is required by Windows.

C API

gh-105375 [https://github.com/python/cpython/issues/105375]: Fix a bug in PyErr_WarnExplicit() where an exception could end up being overwritten if the API failed internally.

gh-105603 [https://github.com/python/cpython/issues/105603]: We've renamed the new (in 3.12) PyInterpreterConfig.own_gil to PyInterpreterConfig.gil and changed the meaning of the value from "bool" to an integer with supported values of PyInterpreterConfig_DEFAULT_GIL, PyInterpreterConfig_SHARED_GIL, and PyInterpreterConfig_OWN_GIL. The default is "shared".

gh-105387 [https://github.com/python/cpython/issues/105387]: In the limited C API version 3.12, Py_INCREF() and Py_DECREF() functions are now implemented as opaque function calls to hide implementation details. Patch by Victor Stinner.

gh-103968 [https://github.com/python/cpython/issues/103968]: PyType_FromMetaclass() now allows metaclasses with tp_new set to NULL.

Python 3.12.0 beta 2

Release date: 2023-06-06

Security

gh-103142 [https://github.com/python/cpython/issues/103142]: The version of OpenSSL used in our binary builds has been upgraded to 1.1.1u to address several CVEs.

gh-99108 [https://github.com/python/cpython/issues/99108]: Refresh our new HACL* built-in hashlib code from upstream. Built-in SHA2 should be faster and an issue with SHA3 on 32-bit platforms is fixed.

Core and Builtins

gh-105259 [https://github.com/python/cpython/issues/105259]: Don't include newline character for trailing NEWLINE tokens emitted in the tokenize module. Patch by Pablo Galindo

gh-105324 [https://github.com/python/cpython/issues/105324]: Fix the main function of the tokenize module when reading from sys.stdin. Patch by Pablo Galindo

gh-98963 [https://github.com/python/cpython/issues/98963]: Restore the ability for a subclass of property to define __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 AttributeError where there had not previously been one was disruptive to existing code.

gh-105194 [https://github.com/python/cpython/issues/105194]: Do not escape with backslashes f-string format specifiers. Patch by Pablo Galindo

gh-105162 [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.

gh-105164 [https://github.com/python/cpython/issues/105164]: Ensure annotations are set up correctly if the only annotation in a block is within a match block. Patch by Jelle Zijlstra.

gh-104799 [https://github.com/python/cpython/issues/104799]: Attributes of ast nodes that are lists now default to the empty list if omitted. This means that some code that previously raised TypeError when the AST node was used will now proceed with the empty list instead. Patch by Jelle Zijlstra.

gh-105035 [https://github.com/python/cpython/issues/105035]: Fix super() calls on types with custom tp_getattro implementation (e.g. meta-types.)

gh-105017 [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.

gh-105013 [https://github.com/python/cpython/issues/105013]: Fix handling of multiline parenthesized lambdas in inspect.getsource(). Patch by Pablo Galindo

gh-105017 [https://github.com/python/cpython/issues/105017]: Do not include an additional final NL token when parsing files having CRLF lines. Patch by Marta Gómez.

gh-104976 [https://github.com/python/cpython/issues/104976]: Ensure that trailing DEDENT tokenize.TokenInfo objects emitted by the tokenize module are reported as in Python 3.11. Patch by Pablo Galindo

gh-104972 [https://github.com/python/cpython/issues/104972]: Ensure that the line attribute in tokenize.TokenInfo objects in the tokenize module are always correct. Patch by Pablo Galindo

gh-104955 [https://github.com/python/cpython/issues/104955]: Fix signature for the new __release_buffer__() slot. Patch by Jelle Zijlstra.

gh-104690 [https://github.com/python/cpython/issues/104690]: Starting new threads and process creation through os.fork() during interpreter shutdown (such as from atexit handlers) is no longer supported. It can lead to race condition between the main Python runtime thread freeing thread states while internal 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.

gh-104879 [https://github.com/python/cpython/issues/104879]: Fix crash when accessing the __module__ attribute of type aliases defined outside a module. Patch by Jelle Zijlstra.

gh-104825 [https://github.com/python/cpython/issues/104825]: Tokens emitted by the tokenize module do not include an implicit \n character in the line attribute anymore. Patch by Pablo Galindo

Library

gh-105280 [https://github.com/python/cpython/issues/105280]: Fix bug where isinstance([], collections.abc.Mapping) could evaluate to True if garbage collection happened at the wrong time. The bug was caused by changes to the implementation of typing.Protocol in Python 3.12.

gh-105239 [https://github.com/python/cpython/issues/105239]: Fix longstanding bug where issubclass(object, typing.Protocol) would evaluate to True in some edge cases. Patch by Alex Waygood.

gh-105080 [https://github.com/python/cpython/issues/105080]: Fixed inconsistent signature on derived classes for inspect.signature()

gh-105144 [https://github.com/python/cpython/issues/105144]: Fix a recent regression in the typing module. The regression meant that doing class Foo(X, typing.Protocol), where X was a class that had abc.ABCMeta as its metaclass, would then cause subsequent isinstance(1, X) calls to erroneously raise TypeError. Patch by Alex Waygood.

gh-105113 [https://github.com/python/cpython/issues/105113]: Improve performance of pathlib.PurePath.match() by compiling an re.Pattern object for the entire pattern.

gh-101588 [https://github.com/python/cpython/issues/101588]: Deprecate undocumented copy/deepcopy/pickle support for itertools.

gh-103631 [https://github.com/python/cpython/issues/103631]: Fix pathlib.PurePosixPath(pathlib.PureWindowsPath(...)) not converting path separators to restore 3.11 compatible behavior.

gh-104947 [https://github.com/python/cpython/issues/104947]: Make comparisons between pathlib.PureWindowsPath objects consistent across Windows and Posix to match 3.11 behavior.

gh-104935 [https://github.com/python/cpython/issues/104935]: Fix bugs with the interaction between typing.runtime_checkable() and typing.Generic that were introduced by the PEP 695 [https://peps.python.org/pep-0695/] implementation. Patch by Jelle Zijlstra.

gh-104874 [https://github.com/python/cpython/issues/104874]: Document the __name__ and __supertype__ attributes of typing.NewType. Patch by Jelle Zijlstra.

gh-104799 [https://github.com/python/cpython/issues/104799]: Adjust the location of the (see PEP 695 [https://peps.python.org/pep-0695/]) type_params field on ast.ClassDef, ast.AsyncFunctionDef, and ast.FunctionDef to better preserve backward compatibility. Patch by Jelle Zijlstra

gh-104797 [https://github.com/python/cpython/issues/104797]: Allow typing.Protocol classes to inherit from collections.abc.Buffer. Patch by Jelle Zijlstra.

gh-104372 [https://github.com/python/cpython/issues/104372]: On Linux where subprocess can use the 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 exec() outcome. This prevents spawning a binary from a slow filesystem from blocking the rest of the application.

gh-99108 [https://github.com/python/cpython/issues/99108]: We now release the GIL around built-in hashlib computations of reasonable size for the SHA families and MD5 hash functions, matching what our OpenSSL backed hash computations already does.

gh-104399 [https://github.com/python/cpython/issues/104399]: Prepare the _tkinter module for building with Tcl 9.0 and future libtommath by replacing usage of deprecated functions mp_to_unsigned_bin_n() and mp_unsigned_bin_size() when necessary.

gh-102024 [https://github.com/python/cpython/issues/102024]: Reduce calls of _idle_semaphore.release() in concurrent.futures.thread._worker().

Documentation

gh-89455 [https://github.com/python/cpython/issues/89455]: Add missing documentation for the max_group_depth and max_group_width parameters and the exceptions attribute of the traceback.TracebackException class.

gh-89412 [https://github.com/python/cpython/issues/89412]: Add missing documentation for the end_lineno and end_offset attributes of the traceback.TracebackException class.

gh-104943 [https://github.com/python/cpython/issues/104943]: Remove mentions of old Python versions in typing.NamedTuple.

Build

gh-90005 [https://github.com/python/cpython/issues/90005]: Fix a regression in configure where we could end up unintentionally linking with libbsd.

gh-89886 [https://github.com/python/cpython/issues/89886]: Autoconf 2.71 and aclocal 1.16.4 is now required to regenerate !configure.

Windows

gh-105146 [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.

gh-103646 [https://github.com/python/cpython/issues/103646]: When installed from the Microsoft Store, 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 pip is passed an option that conflicts with --user.

gh-88745 [https://github.com/python/cpython/issues/88745]: Improve performance of shutil.copy2() by using the operating system's CopyFile2 function. This may result in subtle changes to metadata copied along with some files, bringing them in line with normal OS behavior.

gh-104820 [https://github.com/python/cpython/issues/104820]: Fixes stat() and related functions on file systems that do not support file ID requests. This includes FAT32 and exFAT.

gh-104803 [https://github.com/python/cpython/issues/104803]: Add os.path.isdevdrive() to detect whether a path is on a Windows Dev Drive. Returns False on platforms that do not support Dev Drive, and is absent on non-Windows platforms.

macOS

gh-103142 [https://github.com/python/cpython/issues/103142]: Update macOS installer to use OpenSSL 1.1.1u.

IDLE

gh-104719 [https://github.com/python/cpython/issues/104719]: Remove IDLE's modification of tokenize.tabsize and test other uses of tokenize data and methods.

C API

gh-105115 [https://github.com/python/cpython/issues/105115]: PyTypeObject.tp_bases (and tp_mro) for builtin static types are now shared by all interpreters, whereas in 3.12-beta1 they were stored on PyInterpreterState. Also note that now the tuples are immortal objects.

gh-105071 [https://github.com/python/cpython/issues/105071]: Add PyUnstable_Exc_PrepReraiseStar to the unstable C api to expose the implementation of except*.

gh-104668 [https://github.com/python/cpython/issues/104668]: Don't call PyOS_InputHook or 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).

Python 3.12.0 beta 1

Release date: 2023-05-22

Security

gh-99889 [https://github.com/python/cpython/issues/99889]: Fixed a security in flaw in uu.decode() that could allow for directory traversal based on the input if no out_file was specified.

gh-104049 [https://github.com/python/cpython/issues/104049]: Do not expose the local on-disk location in directory indexes produced by http.client.SimpleHTTPRequestHandler.

gh-99108 [https://github.com/python/cpython/issues/99108]: Upgrade built-in hashlib SHA3 implementation to a verified implementation from the HACL* project. Used when OpenSSL is not present or lacks SHA3.

gh-102153 [https://github.com/python/cpython/issues/102153]: urllib.parse.urlsplit() now strips leading C0 control and space characters following the specification for URLs defined by WHATWG in response to CVE-2023-24329 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-24329]. Patch by Illia Volochii.

Core and Builtins

gh-102856 [https://github.com/python/cpython/issues/102856]: Implement PEP 701 changes in the tokenize module. Patch by Marta Gómez Macías and Pablo Galindo Salgado

gh-104615 [https://github.com/python/cpython/issues/104615]: Fix wrong ordering of assignments in code like a, a = x, y. Contributed by Carl Meyer.

gh-104572 [https://github.com/python/cpython/issues/104572]: Improve syntax error message for invalid constructs in PEP 695 [https://peps.python.org/pep-0695/] contexts and in annotations when from __future__ import annotations is active.

gh-104482 [https://github.com/python/cpython/issues/104482]: Fix three error handling bugs in ast.c's validation of pattern matching statements.

gh-102818 [https://github.com/python/cpython/issues/102818]: Do not add a frame to the traceback in the sys.setprofile and 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.

gh-104405 [https://github.com/python/cpython/issues/104405]: Fix an issue where some bytecode instructions could ignore PEP 523 [https://peps.python.org/pep-0523/] when "inlining" calls.

gh-103082 [https://github.com/python/cpython/issues/103082]: Change behavior of sys.monitoring.events.LINE events in 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 sys.settrace. This should ease porting of tools from 3.11 to 3.12.

gh-104263 [https://github.com/python/cpython/issues/104263]: Fix 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 Py_INFINITY matching C99's INFINITY, and refactor internals to rely on C99's NAN and INFINITY macros instead of hard-coding bit patterns for infinities and NaNs. Thanks Sebastian Berg.

gh-99113 [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 Py_MOD_PER_INTERPRETER_GIL_SUPPORTED as the value for the 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.

gh-99113 [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 Py_NewInterpreter() are not affected. To get an interpreter with its own GIL, call Py_NewInterpreterFromConfig().

gh-104108 [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 Py_mod_multiple_interpreters module def slot. A value of 0 means the module does not support them. 1 means it does. The default is 1.

gh-104142 [https://github.com/python/cpython/issues/104142]: Fix an issue where list or tuple repetition could fail to respect PEP 683 [https://peps.python.org/pep-0683/].

gh-104078 [https://github.com/python/cpython/issues/104078]: Improve the performance of PyObject_HasAttrString()

gh-104066 [https://github.com/python/cpython/issues/104066]: Improve the performance of hasattr() for module objects with a missing attribute.

gh-104028 [https://github.com/python/cpython/issues/104028]: Reduce object creation while calling callback function from gc. Patch by Donghee Na.

gh-104018 [https://github.com/python/cpython/issues/104018]: Disallow the "z" format specifier in %-format of bytes objects.

gh-102213 [https://github.com/python/cpython/issues/102213]: Fix performance loss when accessing an object's attributes with __getattr__ defined.

gh-103895 [https://github.com/python/cpython/issues/103895]: Improve handling of edge cases in showing 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.

gh-103907 [https://github.com/python/cpython/issues/103907]: Don't modify the refcounts of known immortal objects (True, False, and None) in the main interpreter loop.

gh-103899 [https://github.com/python/cpython/issues/103899]: Provide a helpful hint in the TypeError message when accidentally calling a module object that has a callable attribute of the same name (such as dis.dis() or datetime.datetime).

gh-103845 [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.

gh-103763 [https://github.com/python/cpython/issues/103763]: Implement PEP 695 [https://peps.python.org/pep-0695/], adding syntactic support for generic classes, generic functions, and type aliases.

A new type X = ... syntax is added for type aliases, which resolves at runtime to an instance of the new class typing.TypeAliasType. The value is lazily evaluated and is accessible through the .__value__ attribute. This is implemented as a new AST node ast.TypeAlias.

New syntax (class X[T]: ..., def func[T](): ...) is added for defining generic functions and classes. This is implemented as a new type_params attribute on the AST nodes for classes and functions. This node holds instances of the new AST classes ast.TypeVar, ast.ParamSpec, and ast.TypeVarTuple.

typing.TypeVar, typing.ParamSpec, typing.ParamSpecArgs, typing.ParamSpecKwargs, typing.TypeVarTuple, and typing.Generic are now implemented in C rather than Python.

There are new bytecode instructions LOAD_LOCALS, LOAD_CLASSDICT_OR_GLOBAL, and LOAD_CLASSDICT_OR_DEREF to support correct resolution of names in class namespaces.

Patch by Eric Traut, Larry Hastings, and Jelle Zijlstra.

gh-103801 [https://github.com/python/cpython/issues/103801]: Adds three minor linting fixes to the wasm module caught that were caught by ruff.

gh-103793 [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 get_name is called. This makes asyncio benchmarks up to 5% faster.

gh-102310 [https://github.com/python/cpython/issues/102310]: Change the error range for invalid bytes literals.

gh-103590 [https://github.com/python/cpython/issues/103590]: Do not wrap a single exception raised from a try-except* construct in an ExceptionGroup.

gh-103650 [https://github.com/python/cpython/issues/103650]: Change the perf map format to remove the '0x' prefix from the addresses

gh-102856 [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.

gh-100530 [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.

gh-101517 [https://github.com/python/cpython/issues/101517]: Fix bug in line numbers of instructions emitted for except*.

gh-103492 [https://github.com/python/cpython/issues/103492]: Clarify SyntaxWarning with literal is comparison by specifying which literal is problematic, since comparisons using is with e.g. None and bool literals are idiomatic.

gh-87729 [https://github.com/python/cpython/issues/87729]: Add LOAD_SUPER_ATTR (and a specialization for super().method()) to speed up super().method() and super().attr. This makes 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.

gh-103488 [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.

gh-82012 [https://github.com/python/cpython/issues/82012]: The bitwise inversion operator (~) on bool is deprecated. It returns the bitwise inversion of the underlying int representation such that bool(~True) == True, which can be confusing. Use not for logical negation of bools. In the rare case that you really need the bitwise inversion of the underlying int, convert to int explicitly ~int(x).

gh-77757 [https://github.com/python/cpython/issues/77757]: Exceptions raised in a typeobject's __set_name__ method are no longer wrapped by a RuntimeError. Context information is added to the exception as a PEP 678 [https://peps.python.org/pep-0678/] note.

gh-103333 [https://github.com/python/cpython/issues/103333]: AttributeError now retains the name attribute when pickled and unpickled.

gh-103242 [https://github.com/python/cpython/issues/103242]: Migrate set_ecdh_curve() method not to use deprecated OpenSSL APIs. Patch by Donghee Na.

gh-103323 [https://github.com/python/cpython/issues/103323]: We've replaced our use of _PyRuntime.tstate_current with a thread-local variable. This is a fairly low-level implementation detail, and there should be no change in behavior.

gh-84436 [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.

gh-102700 [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.

gh-103082 [https://github.com/python/cpython/issues/103082]: Implement PEP 669 [https://peps.python.org/pep-0669/] Low Impact Monitoring for CPython.

gh-88691 [https://github.com/python/cpython/issues/88691]: Reduce the number of inline CACHE entries for CALL.

gh-102500 [https://github.com/python/cpython/issues/102500]: Make the buffer protocol accessible in Python code using the new __buffer__ and __release_buffer__ magic methods. See PEP 688 [https://peps.python.org/pep-0688/] for details. Patch by Jelle Zijlstra.

gh-97933 [https://github.com/python/cpython/issues/97933]: PEP 709 [https://peps.python.org/pep-0709/]: inline list, dict and set comprehensions to improve performance and reduce bytecode size.

gh-99184 [https://github.com/python/cpython/issues/99184]: Bypass instance attribute access of __name__ in repr of weakref.ref.

gh-98003 [https://github.com/python/cpython/issues/98003]: Complex function calls are now faster and consume no C stack space.

bpo-39610 [https://bugs.python.org/issue?@action=redirect&bpo=39610]: len() for 0-dimensional memoryview objects (such as memoryview(ctypes.c_uint8(42))) now raises a TypeError. Previously this returned 1, which was not consistent with mem_0d[0] raising an IndexError.

bpo-31821 [https://bugs.python.org/issue?@action=redirect&bpo=31821]: Fix pause_reading() to work when called from connection_made() in asyncio.

Library

gh-104600 [https://github.com/python/cpython/issues/104600]: functools.update_wrapper() now sets the __type_params__ attribute (added by PEP 695 [https://peps.python.org/pep-0695/]).

gh-104340 [https://github.com/python/cpython/issues/104340]: When an asyncio pipe protocol loses its connection due to an error, and the caller doesn't await wait_closed() on the corresponding StreamWriter, don't log a warning about an exception that was never retrieved. After all, according to the StreamWriter.close() docs, the wait_closed() call is optional ("not mandatory").

gh-104555 [https://github.com/python/cpython/issues/104555]: Fix issue where an issubclass() check comparing a class X against a runtime-checkable protocol Y with non-callable members would not cause TypeError to be raised if an isinstance() call had previously been made comparing an instance of X to 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.

gh-104372 [https://github.com/python/cpython/issues/104372]: Refactored the _posixsubprocess internals to avoid Python C API usage between fork and exec when marking pass_fds= file descriptors inheritable.

gh-104484 [https://github.com/python/cpython/issues/104484]: Added case_sensitive argument to pathlib.PurePath.match()

gh-75367 [https://github.com/python/cpython/issues/75367]: Fix data descriptor detection in inspect.getattr_static().

gh-104536 [https://github.com/python/cpython/issues/104536]: Fix a race condition in the internal multiprocessing.process cleanup logic that could manifest as an unintended AttributeError when calling process.close().

gh-103857 [https://github.com/python/cpython/issues/103857]: Update datetime deprecations' stracktrace to point to the calling line

gh-101520 [https://github.com/python/cpython/issues/101520]: Move the core functionality of the tracemalloc module in the Python/ folder, leaving just the module wrapper in Modules/.

gh-104392 [https://github.com/python/cpython/issues/104392]: Remove undocumented and unused _paramspec_tvars attribute from some classes in typing.

gh-102613 [https://github.com/python/cpython/issues/102613]: Fix issue where pathlib.Path.glob() raised RecursionError when walking deep directory trees.

gh-103000 [https://github.com/python/cpython/issues/103000]: Improve performance of dataclasses.asdict() for the common case where dict_factory is dict. Patch by David C Ellis.

gh-104301 [https://github.com/python/cpython/issues/104301]: Allow leading whitespace in disambiguated statements in pdb.

gh-104139 [https://github.com/python/cpython/issues/104139]: Teach urllib.parse.unsplit() to retain the "//" when assembling itms-services://?action=generate-bugs style Apple Platform Deployment [https://support.apple.com/en-gb/guide/deployment/depce7cefc4d/web] URLs.

gh-104307 [https://github.com/python/cpython/issues/104307]: socket.getnameinfo() now releases the GIL while contacting the DNS server

gh-104310 [https://github.com/python/cpython/issues/104310]: Users may now use importlib.util.allowing_all_extensions() (a context manager) to temporarily disable the strict compatibility checks for importing extension modules in subinterpreters.

gh-87695 [https://github.com/python/cpython/issues/87695]: Fix issue where pathlib.Path.glob() raised OSError when it encountered a symlink to an overly long path.

gh-104265 [https://github.com/python/cpython/issues/104265]: Prevent possible crash by disallowing instantiation of the _csv.Reader and _csv.Writer types. The regression was introduced in 3.10.0a4 with PR 23224 (bpo-14935 [https://bugs.python.org/issue?@action=redirect&bpo=14935]). Patch by Radislav Chugunov.

gh-102613 [https://github.com/python/cpython/issues/102613]: Improve performance of pathlib.Path.glob() when expanding recursive wildcards ("**") by merging adjacent wildcards and de-duplicating results only when necessary.

gh-65772 [https://github.com/python/cpython/issues/65772]: Remove unneeded comments and code in turtle.py.

gh-90208 [https://github.com/python/cpython/issues/90208]: Fixed issue where pathlib.Path.glob() returned incomplete results when it encountered a PermissionError. This method now suppresses all OSError exceptions, except those raised from calling is_dir() on the top-level path.

gh-104144 [https://github.com/python/cpython/issues/104144]: Optimize asyncio.TaskGroup when using asyncio.eager_task_factory(). Skip scheduling a done callback if a TaskGroup task completes eagerly.

gh-104144 [https://github.com/python/cpython/issues/104144]: Optimize asyncio.gather() when using asyncio.eager_task_factory() to complete eagerly if all fututres completed eagerly. Avoid scheduling done callbacks for futures that complete eagerly.

gh-104114 [https://github.com/python/cpython/issues/104114]: Fix issue where pathlib.Path.glob() returns paths using the case of non-wildcard segments for corresponding path segments, rather than the real filesystem case.

gh-104104 [https://github.com/python/cpython/issues/104104]: Improve performance of pathlib.Path.glob() by using re.IGNORECASE to implement case-insensitive matching.

gh-104102 [https://github.com/python/cpython/issues/104102]: Improve performance of pathlib.Path.glob() when evaluating patterns that contain '../' segments.

gh-103822 [https://github.com/python/cpython/issues/103822]: Update the return type of weekday to the newly added Day attribute

gh-103629 [https://github.com/python/cpython/issues/103629]: Update the repr of typing.Unpack according to PEP 692 [https://peps.python.org/pep-0692/].

gh-103963 [https://github.com/python/cpython/issues/103963]: Make dis display the names of the args for CALL_INTRINSIC_*.

gh-104035 [https://github.com/python/cpython/issues/104035]: Do not ignore user-defined __getstate__ and __setstate__ methods for slotted frozen dataclasses.

gh-103987 [https://github.com/python/cpython/issues/103987]: In mmap, fix several bugs that could lead to access to memory-mapped files after they have been invalidated.

gh-103977 [https://github.com/python/cpython/issues/103977]: Improve import time of platform module.

gh-88773 [https://github.com/python/cpython/issues/88773]: Added turtle.teleport() to the turtle module to move a turtle to a new point without tracing a line, visible or invisible. Patch by Liam Gersten.

gh-103935 [https://github.com/python/cpython/issues/103935]: Use io.open_code() for files to be executed instead of raw open()

gh-68968 [https://github.com/python/cpython/issues/68968]: Fixed garbled output of assertEqual() when an input lacks final newline.

gh-100370 [https://github.com/python/cpython/issues/100370]: Fix potential OverflowError in sqlite3.Connection.blobopen() for 32-bit builds. Patch by Erlend E. Aasland.

gh-102628 [https://github.com/python/cpython/issues/102628]: Substitute CTRL-D with CTRL-Z in sqlite3 CLI banner when running on Windows.

gh-103636 [https://github.com/python/cpython/issues/103636]: Module-level attributes January and February are deprecated from calendar.

gh-103583 [https://github.com/python/cpython/issues/103583]: Isolate _multibytecodec and codecs extension modules. Patches by Erlend E. Aasland.

gh-103848 [https://github.com/python/cpython/issues/103848]: Add checks to ensure that [ bracketed ] hosts found by urllib.parse.urlsplit() are of IPv6 or IPvFuture format.

gh-103872 [https://github.com/python/cpython/issues/103872]: Update the bundled copy of pip to version 23.1.2.

gh-99944 [https://github.com/python/cpython/issues/99944]: Make dis display the value of oparg of KW_NAMES.

gh-74940 [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.

gh-103861 [https://github.com/python/cpython/issues/103861]: Fix zipfile.Zipfile creating invalid zip files when force_zip64 was used to add files to them. Patch by Carey Metcalfe.

gh-103857 [https://github.com/python/cpython/issues/103857]: Deprecated datetime.datetime.utcnow() and datetime.datetime.utcfromtimestamp(). (Patch by Paul Ganssle)

gh-103839 [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.

gh-103791 [https://github.com/python/cpython/issues/103791]: contextlib.suppress now supports suppressing exceptions raised as part of an ExceptionGroup. If other exceptions exist on the group, they are re-raised in a group that does not contain the suppressed exceptions.

gh-90750 [https://github.com/python/cpython/issues/90750]: Use datetime.datetime.fromisocalendar() in the implementation of datetime.datetime.strptime(), which should now accept only valid ISO dates. (Patch by Paul Ganssle)

gh-103685 [https://github.com/python/cpython/issues/103685]: Prepare tkinter.Menu.index() for Tk 8.7 so that it does not raise TclError: expected integer but got "" when it should return None.

gh-81403 [https://github.com/python/cpython/issues/81403]: urllib.request.CacheFTPHandler no longer raises URLError if a cached FTP instance is reused. ftplib's endtransfer method calls voidresp to drain the connection to handle FTP instance reuse properly.

gh-103699 [https://github.com/python/cpython/issues/103699]: Add __orig_bases__ to non-generic TypedDicts, call-based TypedDicts, and call-based NamedTuples. Other TypedDicts and NamedTuples already had the attribute.

gh-103693 [https://github.com/python/cpython/issues/103693]: Add convenience variable feature to pdb

gh-92248 [https://github.com/python/cpython/issues/92248]: Deprecate type, choices, and metavar parameters of argparse.BooleanOptionalAction.

gh-89415 [https://github.com/python/cpython/issues/89415]: Add socket constants for source-specific multicast. Patch by Reese Hyde.

gh-103673 [https://github.com/python/cpython/issues/103673]: socketserver gains ForkingUnixStreamServer and ForkingUnixDatagramServer classes. Patch by Jay Berry.

gh-103636 [https://github.com/python/cpython/issues/103636]: Added Enum for months and days in the calendar module.

gh-84976 [https://github.com/python/cpython/issues/84976]: Create a new Lib/_pydatetime.py file that defines the Python version of the datetime module, and make 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 import datetime unnecessarily.

gh-103596 [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.

gh-103584 [https://github.com/python/cpython/issues/103584]: Updated importlib.metadata with changes from importlib_metadata 5.2 through 6.5.0, including: Support installed-files.txt for Distribution.files when present. PackageMetadata now stipulates an additional get method allowing for easy querying of metadata keys that may not be present. packages_distributions now honors packages and modules with Python modules that not .py sources (e.g. .pyc, .so). Expand protocol for PackageMetadata.get_all to match the upstream implementation of email.message.Message.get_all in python/typeshed#9620. Deprecated use of Distribution without defining abstract methods. Deprecated expectation that PackageMetadata.__getitem__ will return None for missing keys. In the future, it will raise a KeyError.

gh-103578 [https://github.com/python/cpython/issues/103578]: Fixed a bug where pdb crashes when reading source file with different encoding by replacing io.open() with io.open_code(). The new method would also call into the hook set by PyFile_SetOpenCodeHook().

gh-103556 [https://github.com/python/cpython/issues/103556]: Now creating inspect.Signature objects with positional-only parameter with a default followed by a positional-or-keyword parameter without one is impossible.

gh-103559 [https://github.com/python/cpython/issues/103559]: Update the bundled copy of pip to version 23.1.1.

gh-103548 [https://github.com/python/cpython/issues/103548]: Improve performance of pathlib.Path.absolute() and cwd() by joining paths only when necessary. Also improve performance of pathlib.PurePath.is_absolute() on Posix by skipping path parsing and normalization.

gh-103538 [https://github.com/python/cpython/issues/103538]: Remove _tkinter module code guarded by definition of the 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.

gh-103533 [https://github.com/python/cpython/issues/103533]: Update cProfile to use PEP 669 API

gh-103525 [https://github.com/python/cpython/issues/103525]: Fix misleading exception message when mixed str and bytes arguments are supplied to pathlib.PurePath and Path.

gh-103489 [https://github.com/python/cpython/issues/103489]: Add getconfig() and setconfig() to Connection to make configuration changes to a database connection. Patch by Erlend E. Aasland.

gh-103365 [https://github.com/python/cpython/issues/103365]: Set default Flag boundary to STRICT and fix bitwise operations.

gh-103472 [https://github.com/python/cpython/issues/103472]: Avoid a potential ResourceWarning in http.client.HTTPConnection by closing the proxy / tunnel's CONNECT response explicitly.

gh-103462 [https://github.com/python/cpython/issues/103462]: Fixed an issue with using writelines() in asyncio to send very large payloads that exceed the amount of data that can be written in one call to socket.socket.send() or socket.socket.sendmsg(), resulting in the remaining buffer being left unwritten.

gh-103449 [https://github.com/python/cpython/issues/103449]: Fix a bug in doc string generation in dataclasses.dataclass().

gh-103092 [https://github.com/python/cpython/issues/103092]: Isolate _collections (apply PEP 687 [https://peps.python.org/pep-0687/]). Patch by Erlend E. Aasland.

gh-103357 [https://github.com/python/cpython/issues/103357]: Added support for logging.Formatter defaults parameter to logging.config.dictConfig() and logging.config.fileConfig(). Patch by Bar Harel.

gh-103092 [https://github.com/python/cpython/issues/103092]: Adapt the winreg extension module to PEP 687 [https://peps.python.org/pep-0687/].

gh-74690 [https://github.com/python/cpython/issues/74690]: The performance of isinstance() checks against 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 typing module have been refactored, including typing._ProtocolMeta.__instancecheck__, typing._is_callable_members_only, and typing._get_protocol_attrs. Patches by Alex Waygood.

gh-74690 [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 "What's new in Python 3.12" for more details.

gh-103256 [https://github.com/python/cpython/issues/103256]: Fixed a bug that caused hmac to raise an exception when the requested hash algorithm was not available in OpenSSL despite being available separately as part of 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 hmac.digest(b'K', b'M', 'sha3_256').

gh-102778 [https://github.com/python/cpython/issues/102778]: Support sys.last_exc in idlelib.

gh-103285 [https://github.com/python/cpython/issues/103285]: Improve performance of ast.get_source_segment().

gh-103225 [https://github.com/python/cpython/issues/103225]: Fix a bug in pdb when displaying line numbers of module-level source code.

gh-103092 [https://github.com/python/cpython/issues/103092]: Adapt the msvcrt extension module to PEP 687 [https://peps.python.org/pep-0687/].

gh-103092 [https://github.com/python/cpython/issues/103092]: Adapt the winsound extension module to PEP 687 [https://peps.python.org/pep-0687/].

gh-93910 [https://github.com/python/cpython/issues/93910]: Remove deprecation of enum memmber.member access.

gh-102978 [https://github.com/python/cpython/issues/102978]: Fixes unittest.mock.patch() not enforcing function signatures for methods decorated with @classmethod or @staticmethod when patch is called with autospec=True.

gh-103092 [https://github.com/python/cpython/issues/103092]: Isolate _socket (apply PEP 687 [https://peps.python.org/pep-0687/]). Patch by Erlend E. Aasland.

gh-100479 [https://github.com/python/cpython/issues/100479]: Add pathlib.PurePath.with_segments(), which creates a path object from arguments. This method is called whenever a derivative path is created, such as from pathlib.PurePath.parent. Subclasses may override this method to share information between path objects.

gh-103220 [https://github.com/python/cpython/issues/103220]: Fix issue where os.path.join() added a slash when joining onto an incomplete UNC drive with a trailing slash on Windows.

gh-103204 [https://github.com/python/cpython/issues/103204]: Fixes 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.

gh-75586 [https://github.com/python/cpython/issues/75586]: Fix various Windows-specific issues with shutil.which.

gh-103193 [https://github.com/python/cpython/issues/103193]: Improve performance of inspect.getattr_static(). Patch by Alex Waygood.

gh-103176 [https://github.com/python/cpython/issues/103176]: sys._current_exceptions() now returns a mapping from thread-id to an exception instance, rather than to a (typ, exc, tb) tuple.

gh-103143 [https://github.com/python/cpython/issues/103143]: Polish the help messages and docstrings of pdb.

gh-103015 [https://github.com/python/cpython/issues/103015]: Add entrypoint keyword-only parameter to sqlite3.Connection.load_extension(), for overriding the SQLite extension entry point. Patch by Erlend E. Aasland.

gh-103000 [https://github.com/python/cpython/issues/103000]: Improve performance of dataclasses.astuple() and dataclasses.asdict() in cases where the contents are common Python types.

gh-102953 [https://github.com/python/cpython/issues/102953]: The extraction methods in tarfile, and 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 Extraction filters for details.

gh-97696 [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.

gh-81079 [https://github.com/python/cpython/issues/81079]: Add case_sensitive keyword-only argument to pathlib.Path.glob() and rglob().

gh-101819 [https://github.com/python/cpython/issues/101819]: Isolate the io extension module by applying PEP 687 [https://peps.python.org/pep-0687/]. Patch by Kumar Aditya, Victor Stinner, and Erlend E. Aasland.

gh-91896 [https://github.com/python/cpython/issues/91896]: Deprecate collections.abc.ByteString

gh-101362 [https://github.com/python/cpython/issues/101362]: Speed up pathlib.Path construction by omitting the path anchor from the internal list of path parts.

gh-102114 [https://github.com/python/cpython/issues/102114]: Functions in the 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.

gh-62432 [https://github.com/python/cpython/issues/62432]: The 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.

gh-78079 [https://github.com/python/cpython/issues/78079]: Fix incorrect normalization of UNC device path roots, and partial UNC share path roots, in pathlib.PurePath. Pathlib no longer appends a trailing slash to such paths.

gh-85984 [https://github.com/python/cpython/issues/85984]: Add tty.cfmakeraw() and tty.cfmakecbreak() to tty and modernize, the behavior of tty.setraw() and tty.setcbreak() to use POSIX.1-2017 Chapter 11 "General Terminal Interface" flag masks by default.

gh-101688 [https://github.com/python/cpython/issues/101688]: Implement types.get_original_bases() to provide further introspection for types.

gh-101640 [https://github.com/python/cpython/issues/101640]: argparse.ArgumentParser now catches errors when writing messages, such as when sys.stderr is None. Patch by Oleg Iarygin.

gh-83861 [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.

gh-89550 [https://github.com/python/cpython/issues/89550]: Decrease execution time of some gzip file writes by 15% by adding more appropriate buffering.

gh-95299 [https://github.com/python/cpython/issues/95299]: Remove the bundled setuptools wheel from ensurepip, and stop installing setuptools in environments created by venv.

gh-99353 [https://github.com/python/cpython/issues/99353]: Respect the http.client.HTTPConnection .debuglevel flag in urllib.request.AbstractHTTPHandler when its constructor parameter debuglevel is not set. And do the same for *HTTPS*.

gh-98040 [https://github.com/python/cpython/issues/98040]: Remove the long-deprecated imp module.

gh-97850 [https://github.com/python/cpython/issues/97850]: Deprecate pkgutil.find_loader() and pkgutil.get_loader() in favor of importlib.util.find_spec().

gh-94473 [https://github.com/python/cpython/issues/94473]: Flatten arguments in tkinter.Canvas.coords(). It now accepts not only x1, y1, x2, y2, ... and [x1, y1, x2, y2, ...], but also (x1, y1), (x2, y2), ... and [(x1, y1), (x2, y2), ...].

gh-98040 [https://github.com/python/cpython/issues/98040]: Remove more deprecated importlib APIs: find_loader(), find_module(), importlib.abc.Finder, pkgutil.ImpImporter, pkgutil.ImpLoader.

gh-96522 [https://github.com/python/cpython/issues/96522]: Fix potential deadlock in pty.spawn()

gh-96534 [https://github.com/python/cpython/issues/96534]: Support divert(4) added in FreeBSD 14.

gh-87474 [https://github.com/python/cpython/issues/87474]: Fix potential file descriptor leaks in subprocess.Popen.

gh-94906 [https://github.com/python/cpython/issues/94906]: Support multiple steps in math.nextafter(). Patch by Shantanu Jain and Matthias Gorgens.

gh-51574 [https://github.com/python/cpython/issues/51574]: Make tempfile.mkdtemp() return absolute paths when its dir parameter is relative.

gh-94518 [https://github.com/python/cpython/issues/94518]: Convert private _posixsubprocess.fork_exec() to use Argument Clinic.

gh-92184 [https://github.com/python/cpython/issues/92184]: When creating zip files using zipfile, os.altsep, if not None, will always be treated as a path separator even when it is not /. Patch by Carey Metcalfe.

bpo-46797 [https://bugs.python.org/issue?@action=redirect&bpo=46797]: Deprecation warnings are now emitted for ast.Num, ast.Bytes, ast.Str, ast.NameConstant and ast.Ellipsis. These have been documented as deprecated since Python 3.8, and will be removed in Python 3.14.

bpo-44844 [https://bugs.python.org/issue?@action=redirect&bpo=44844]: Enables webbrowser to detect and launch Microsoft Edge browser.

bpo-45606 [https://bugs.python.org/issue?@action=redirect&bpo=45606]: Fixed the bug in 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 (**). With this change, a dangling symlink will be found in both cases.

bpo-23041 [https://bugs.python.org/issue?@action=redirect&bpo=23041]: Add QUOTE_STRINGS and QUOTE_NOTNULL to the suite of csv module quoting styles.

bpo-24964 [https://bugs.python.org/issue?@action=redirect&bpo=24964]: Added http.client.HTTPConnection.get_proxy_response_headers() that provides access to the HTTP headers on a proxy server response to the CONNECT request.

bpo-17258 [https://bugs.python.org/issue?@action=redirect&bpo=17258]: multiprocessing now supports stronger HMAC algorithms for inter-process connection authentication rather than only HMAC-MD5.

bpo-39744 [https://bugs.python.org/issue?@action=redirect&bpo=39744]: Make asyncio.subprocess.Process.communicate() close the subprocess's stdin even when called with input=None.

bpo-22708 [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.

Documentation

gh-67056 [https://github.com/python/cpython/issues/67056]: Document that the effect of registering or unregistering an atexit cleanup function from within a registered cleanup function is undefined.

gh-103629 [https://github.com/python/cpython/issues/103629]: Mention the new way of typing **kwargs with Unpack and TypedDict introduced in PEP 692 [https://peps.python.org/pep-0692/].

gh-48241 [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.

gh-86094 [https://github.com/python/cpython/issues/86094]: Add support for Unicode Path Extra Field in ZipFile. Patch by Yeojin Kim and Andrea Giudiceandrea

gh-99202 [https://github.com/python/cpython/issues/99202]: Fix extension type from documentation for compiling in C++20 mode

Tests

gh-104494 [https://github.com/python/cpython/issues/104494]: Update test_pack_configure_in and test_place_configure_in for changes to error message formatting in Tk 8.7.

gh-104461 [https://github.com/python/cpython/issues/104461]: Run test_configure_screen on X11 only, since the DISPLAY environment variable and -screen option for toplevels are not useful on Tk for Win32 or Aqua.

gh-86275 [https://github.com/python/cpython/issues/86275]: Added property-based tests to the zoneinfo tests, along with stubs for the hypothesis interface. (Patch by Paul Ganssle)

gh-103329 [https://github.com/python/cpython/issues/103329]: Regression tests for the behaviour of unittest.mock.PropertyMock were added.

gh-102795 [https://github.com/python/cpython/issues/102795]: fix use of poll in test_epoll's test_control_and_wait

gh-75729 [https://github.com/python/cpython/issues/75729]: Fix the os.spawn* tests failing on Windows when the working directory or interpreter path contains spaces.

Build

gh-101282 [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 BOLT_INSTRUMENT_FLAGS and BOLT_APPLY_FLAGS configure variables.

gh-99017 [https://github.com/python/cpython/issues/99017]: PYTHON_FOR_REGEN now require Python 3.10 or newer.

gh-104490 [https://github.com/python/cpython/issues/104490]: Define .PHONY / virtual make targets consistently and properly.

gh-104106 [https://github.com/python/cpython/issues/104106]: Add gcc fallback of mkfifoat/mknodat for macOS. Patch by Donghee Na.

gh-103532 [https://github.com/python/cpython/issues/103532]: The TKINTER_PROTECT_LOADTK macro is no longer defined or used in the _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 [https://github.com/python/cpython/issues/91152].

gh-99069 [https://github.com/python/cpython/issues/99069]: Extended workaround defining static_assert when missing from the libc headers to all clang and gcc builds. In particular, this fixes building on macOS <= 10.10.

gh-100220 [https://github.com/python/cpython/issues/100220]: Changed the default value of the SHELL Makefile variable from /bin/sh to /bin/sh -e to ensure that complex recipes correctly fail after an error. Previously, make install could fail to install some files and yet return a successful result.

gh-90656 [https://github.com/python/cpython/issues/90656]: Add platform triplets for 64-bit LoongArch:

loongarch64-linux-gnusf

loongarch64-linux-gnuf32

loongarch64-linux-gnu

Patch by Zhang Na.

Windows

gh-104623 [https://github.com/python/cpython/issues/104623]: Update Windows installer to use SQLite 3.42.0.

gh-82814 [https://github.com/python/cpython/issues/82814]: Fix a potential [Errno 13] Permission denied when using shutil.copystat() within Windows Subsystem for Linux (WSL) on a mounted filesystem by adding errno.EACCES to the list of ignored errors within the internal implementation.

gh-103088 [https://github.com/python/cpython/issues/103088]: Fix virtual environment activate script having incorrect line endings for Cygwin.

gh-103088 [https://github.com/python/cpython/issues/103088]: Fixes venvs not working in bash on Windows across different disks

gh-102997 [https://github.com/python/cpython/issues/102997]: Update Windows installer to use SQLite 3.41.2.

gh-88013 [https://github.com/python/cpython/issues/88013]: Fixed a bug where TypeError was raised when calling ntpath.realpath() with a bytes parameter in some cases.

macOS

gh-99834 [https://github.com/python/cpython/issues/99834]: Update macOS installer to Tcl/Tk 8.6.13.

gh-104623 [https://github.com/python/cpython/issues/104623]: Update macOS installer to SQLite 3.42.0.

gh-103545 [https://github.com/python/cpython/issues/103545]: Add os.PRIO_DARWIN_THREAD, os.PRIO_DARWIN_PROCESS, os.PRIO_DARWIN_BG and os.PRIO_DARWIN_NONUI. These can be used with os.setpriority to run the process at a lower priority and make use of the efficiency cores on Apple Silicon systems.

gh-104180 [https://github.com/python/cpython/issues/104180]: Support reading SOCKS proxy configuration from macOS System Configuration. Patch by Sam Schott.

gh-60436 [https://github.com/python/cpython/issues/60436]: update curses textbox to additionally handle backspace using the curses.ascii.DEL key press.

gh-102997 [https://github.com/python/cpython/issues/102997]: Update macOS installer to SQLite 3.41.2.

IDLE

gh-104499 [https://github.com/python/cpython/issues/104499]: Fix completions for Tk Aqua 8.7 (currently blank).

gh-104496 [https://github.com/python/cpython/issues/104496]: About prints both tcl and tk versions if different (expected someday).

gh-88496 [https://github.com/python/cpython/issues/88496]: Fix IDLE test hang on macOS.

Tools/Demos

gh-104389 [https://github.com/python/cpython/issues/104389]: Argument Clinic C converters now accept the unused keyword, for wrapping a parameter with Py_UNUSED. Patch by Erlend E. Aasland.

C API

gh-101291 [https://github.com/python/cpython/issues/101291]: Added unstable C API for extracting the value of "compact" integers: PyUnstable_Long_IsCompact() and PyUnstable_Long_CompactValue().

gh-104109 [https://github.com/python/cpython/issues/104109]: We've added Py_NewInterpreterFromConfig() and 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).

gh-103968 [https://github.com/python/cpython/issues/103968]: PyType_FromSpec() and its variants now allow creating classes whose metaclass overrides tp_new. The tp_new is ignored. This behavior is deprecated and will be disallowed in 3.14+. The new PyType_FromMetaclass() already disallows it.

gh-103743 [https://github.com/python/cpython/issues/103743]: Add PyUnstable_Object_GC_NewWithExtraData() function that can be used to allocate additional memory after an object for data not managed by Python.

gh-103295 [https://github.com/python/cpython/issues/103295]: Introduced PyUnstable_WritePerfMapEntry(), PyUnstable_PerfMapState_Init() and PyUnstable_PerfMapState_Fini(). These allow extension modules (JIT compilers in particular) to write to perf-map files in a thread safe manner. The Python support for the Linux perf profiler also uses these APIs to write entries in the perf-map file.

gh-103509 [https://github.com/python/cpython/issues/103509]: Added C API for extending types whose instance memory layout is opaque: PyType_Spec.basicsize can now be zero or negative, PyObject_GetTypeData() can be used to get subclass-specific data, and Py_TPFLAGS_ITEMS_AT_END can be used to safely extend variable-size objects. See PEP 697 [https://peps.python.org/pep-0697/] for details.

gh-103091 [https://github.com/python/cpython/issues/103091]: Add a new C-API function to eagerly assign a version tag to a PyTypeObject: PyUnstable_Type_AssignVersionTag().

gh-101408 [https://github.com/python/cpython/issues/101408]: PyObject_GC_Resize should calculate preheader size if needed. Patch by Donghee Na.

gh-98836 [https://github.com/python/cpython/issues/98836]: Add support of more formatting options (left aligning, octals, uppercase hexadecimals, intmax_t, ptrdiff_t, wchar_t C strings, variable width and precision) in PyUnicode_FromFormat() and PyUnicode_FromFormatV().

gh-96803 [https://github.com/python/cpython/issues/96803]: Add unstable C-API functions to get the code object, lasti and line number from the internal _PyInterpreterFrame in the limited API. The functions are:

PyCodeObject * PyUnstable_InterpreterFrame_GetCode(struct _PyInterpreterFrame *frame)

int PyUnstable_InterpreterFrame_GetLasti(struct _PyInterpreterFrame *frame)

int PyUnstable_InterpreterFrame_GetLine(struct _PyInterpreterFrame *frame)

Python 3.12.0 alpha 7

Release date: 2023-04-04

Core and Builtins

gh-102192 [https://github.com/python/cpython/issues/102192]: Deprecated _PyErr_ChainExceptions in favour of _PyErr_ChainExceptions1.

gh-89987 [https://github.com/python/cpython/issues/89987]: Reduce the number of inline CACHE entries for BINARY_SUBSCR.

gh-102859 [https://github.com/python/cpython/issues/102859]: Removed JUMP_IF_FALSE_OR_POP and JUMP_IF_TRUE_OR_POP instructions.

gh-101975 [https://github.com/python/cpython/issues/101975]: Fixed stacktop value on tracing entries to avoid corruption on garbage collection.

gh-102778 [https://github.com/python/cpython/issues/102778]: Add sys.last_exc and deprecate sys.last_type, sys.last_value and sys.last_traceback, which hold the same information in its legacy form.

gh-100982 [https://github.com/python/cpython/issues/100982]: Replace all occurrences of COMPARE_AND_BRANCH with COMPARE_OP.

gh-102701 [https://github.com/python/cpython/issues/102701]: Fix overflow when creating very large dict.

gh-102755 [https://github.com/python/cpython/issues/102755]: Add PyErr_DisplayException() which takes just an exception instance, to replace the legacy PyErr_Display() which takes the (typ, exc, tb) triplet.

gh-102594 [https://github.com/python/cpython/issues/102594]: Add note to exception raised in PyErr_SetObject when normalization fails.

gh-90997 [https://github.com/python/cpython/issues/90997]: Shrink the number of inline CACHE entries used by LOAD_GLOBAL.

gh-102491 [https://github.com/python/cpython/issues/102491]: Improve import time of platform by removing IronPython version parsing. The IronPython version parsing was not functional (see https://github.com/IronLanguages/ironpython3/issues/1667).

gh-101291 [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.

gh-102397 [https://github.com/python/cpython/issues/102397]: Fix segfault from race condition in signal handling during garbage collection. Patch by Kumar Aditya.

gh-102406 [https://github.com/python/cpython/issues/102406]: codecs encoding/decoding errors now get the context information (which operation and which codecs) attached as PEP 678 [https://peps.python.org/pep-0678/] notes instead of through chaining a new instance of the exception.

gh-102281 [https://github.com/python/cpython/issues/102281]: Fix potential nullptr dereference and use of uninitialized memory in fileutils. Patch by Max Bachmann.

gh-102300 [https://github.com/python/cpython/issues/102300]: Reuse operands with refcount of 1 in float specializations of BINARY_OP.

gh-102213 [https://github.com/python/cpython/issues/102213]: Fix performance loss when accessing an object's attributes with __getattr__ defined.

gh-102255 [https://github.com/python/cpython/issues/102255]: Improve build support for the Xbox. Patch by Max Bachmann.

gh-102027 [https://github.com/python/cpython/issues/102027]: Fix SSE2 and SSE3 detection in _blake2 internal module. Patch by Max Bachmann.

gh-101865 [https://github.com/python/cpython/issues/101865]: Deprecate co_lnotab in code objects, schedule it for removal in Python 3.14

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Adapt _pickle to PEP 687 [https://peps.python.org/pep-0687/]. Patch by Mohamed Koubaa and Erlend Aasland.

Library

gh-103085 [https://github.com/python/cpython/issues/103085]: Pure python locale.getencoding() will not warn deprecation.

gh-103068 [https://github.com/python/cpython/issues/103068]: It's no longer possible to register conditional breakpoints in Pdb that raise SyntaxError. Patch by Tian Gao.

gh-102549 [https://github.com/python/cpython/issues/102549]: Don't ignore exceptions in member type creation.

gh-103056 [https://github.com/python/cpython/issues/103056]: Ensure final _generate_next_value_ is a staticmethod.

gh-103046 [https://github.com/python/cpython/issues/103046]: Display current line label correctly in dis when show_caches is False and lasti points to a CACHE entry.

gh-102433 [https://github.com/python/cpython/issues/102433]: isinstance() checks against runtime-checkable protocols now use inspect.getattr_static() rather than hasattr() to lookup whether attributes exist. This means that descriptors and __getattr__() methods are no longer unexpectedly evaluated during 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.

gh-103023 [https://github.com/python/cpython/issues/103023]: It's no longer possible to register expressions to display in Pdb that raise SyntaxError. Patch by Tian Gao.

gh-102947 [https://github.com/python/cpython/issues/102947]: Improve traceback when dataclasses.fields() is called on a non-dataclass. Patch by Alex Waygood

gh-102780 [https://github.com/python/cpython/issues/102780]: The asyncio.Timeout context manager now works reliably even when performing cleanup due to task cancellation. Previously it could raise a CancelledError instead of an TimeoutError in such cases.

gh-102871 [https://github.com/python/cpython/issues/102871]: Remove support for obsolete browsers from webbrowser. Removed browsers include Grail, Mosaic, Netscape, Galeon, Skipstone, Iceape, Firebird, and Firefox versions 35 and below.

gh-102839 [https://github.com/python/cpython/issues/102839]: Improve performance of math.log() arguments handling by removing the argument clinic.

gh-102828 [https://github.com/python/cpython/issues/102828]: Add the onexc arg to shutil.rmtree(), which is like onerror but expects an exception instance rather than an exc_info tuple. Deprecate onerror.

gh-88965 [https://github.com/python/cpython/issues/88965]: typing: Fix a bug relating to substitution in custom classes generic over a ParamSpec. Previously, if the ParamSpec was substituted with a parameters list that itself contained a TypeVar, the TypeVar in the parameters list could not be subsequently substituted. This is now fixed.

Patch by Nikita Sobolev.

gh-76846 [https://github.com/python/cpython/issues/76846]: Fix issue where __new__() and __init__() methods of pathlib.PurePath and Path subclasses were not called in some circumstances.

gh-78530 [https://github.com/python/cpython/issues/78530]: asyncio.wait() now accepts generators yielding tasks. Patch by Kumar Aditya.

gh-102748 [https://github.com/python/cpython/issues/102748]: asyncio.iscoroutine() now returns False for generators as asyncio does not support legacy generator-based coroutines. Patch by Kumar Aditya.

gh-102670 [https://github.com/python/cpython/issues/102670]: Optimized fmean(), correlation(), covariance(), and linear_regression() using the new math.sumprod() function.

gh-102615 [https://github.com/python/cpython/issues/102615]: Typing: Improve the repr of generic aliases for classes generic over a ParamSpec. (Use square brackets to represent a parameter list.)

gh-100112 [https://github.com/python/cpython/issues/100112]: asyncio.Task.get_coro() now always returns a coroutine when wrapping an awaitable object. Patch by Kumar Aditya.

gh-102578 [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 __setattr__ and __delattr__ for frozen dataclasses, this previously had a time complexity of O(n). It now has a time complexity of O(1).

gh-102519 [https://github.com/python/cpython/issues/102519]: Add os.listdrives(), os.listvolumes() and os.listmounts() functions on Windows for enumerating drives, volumes and mount points

gh-74468 [https://github.com/python/cpython/issues/74468]: Attribute name of the extracted tarfile file object now holds filename of itself rather than of the archive it is contained in. Patch by Oleg Iarygin.

gh-102378 [https://github.com/python/cpython/issues/102378]: Private helper method inspect._signature_strip_non_python_syntax will no longer strip / from the input string.

gh-79940 [https://github.com/python/cpython/issues/79940]: Add inspect.getasyncgenstate() and inspect.getasyncgenlocals(). Patch by Thomas Krennwallner.

gh-102103 [https://github.com/python/cpython/issues/102103]: Add module argument to dataclasses.make_dataclass() and make classes produced by it pickleable.

gh-102069 [https://github.com/python/cpython/issues/102069]: Fix __weakref__ descriptor generation for custom dataclasses.

gh-102038 [https://github.com/python/cpython/issues/102038]: Skip a stat in site if we have already found a pyvenv.cfg

gh-98886 [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 dataclasses.

gh-101673 [https://github.com/python/cpython/issues/101673]: Fix a pdb bug where ll clears the changes to local variables.

gh-101313 [https://github.com/python/cpython/issues/101313]: Added -h and --help arguments to the webbrowser CLI

gh-100372 [https://github.com/python/cpython/issues/100372]: ssl.SSLContext.load_verify_locations() no longer incorrectly accepts some cases of trailing data when parsing DER.

gh-89727 [https://github.com/python/cpython/issues/89727]: Fix pathlib.Path.walk RecursionError on deep directory trees by rewriting it using iteration instead of recursion.

gh-100131 [https://github.com/python/cpython/issues/100131]: Added an optional delete keyword argument to tempfile.TemporaryDirectory.

gh-48330 [https://github.com/python/cpython/issues/48330]: Added --durations command line option, showing the N slowest test cases. unittest.TextTestRunner and unittest.TextTestResult constructors accept a new durations keyword argument. Subclasses should take this into account or accept **kwargs. Added unittest.TestResult.addDuration() method and unittest.TestResult.collectedDurations attribute.

(Contributed by Giampaolo Rodola)

gh-98169 [https://github.com/python/cpython/issues/98169]: Fix dataclasses.astuple() crash when collections.defaultdict is present in the attributes.

gh-96931 [https://github.com/python/cpython/issues/96931]: Fix incorrect results from ssl.SSLSocket.shared_ciphers()

gh-95495 [https://github.com/python/cpython/issues/95495]: When built against OpenSSL 3.0, the ssl module had a bug where it reported unauthenticated EOFs (i.e. without close_notify) as a clean TLS-level EOF. It now raises SSLEOFError, matching the behavior in previous versions of OpenSSL. The options attribute on SSLContext also no longer includes OP_IGNORE_UNEXPECTED_EOF by default. This option may be set to specify the previous OpenSSL 3.0 behavior.

gh-94684 [https://github.com/python/cpython/issues/94684]: Now uuid.uuid3() and uuid.uuid5() functions support bytes objects as their name argument.

gh-94440 [https://github.com/python/cpython/issues/94440]: Fix a concurrent.futures.process bug where ProcessPoolExecutor shutdown could hang after a future has been quickly submitted and canceled.

gh-72346 [https://github.com/python/cpython/issues/72346]: Added deprecation warning to isdst parameter of email.utils.localtime().

bpo-36305 [https://bugs.python.org/issue?@action=redirect&bpo=36305]: Fix handling of Windows filenames that resemble drives, such as ./a:b, in pathlib.

Documentation

gh-103112 [https://github.com/python/cpython/issues/103112]: Add docstring to http.client.HTTPResponse.read() to fix pydoc output.

Tests

gh-102980 [https://github.com/python/cpython/issues/102980]: Improve test coverage on pdb.

gh-102537 [https://github.com/python/cpython/issues/102537]: Adjust the error handling strategy in test_zoneinfo.TzPathTest.python_tzpath_context. Patch by Paul Ganssle.

gh-101377 [https://github.com/python/cpython/issues/101377]: Improved test_locale_calendar_formatweekday of calendar.

Build

gh-102973 [https://github.com/python/cpython/issues/102973]: Add a dev container (along with accompanying Dockerfile) for development purposes.

gh-102711 [https://github.com/python/cpython/issues/102711]: Fix -Wstrict-prototypes compiler warnings.

Windows

gh-102690 [https://github.com/python/cpython/issues/102690]: Update webbrowser to fall back to Microsoft Edge instead of Internet Explorer.

gh-99726 [https://github.com/python/cpython/issues/99726]: Improves correctness of stat results for Windows, and uses faster API when available

Tools/Demos

gh-102809 [https://github.com/python/cpython/issues/102809]: Misc/gdbinit was removed.

C API

gh-102013 [https://github.com/python/cpython/issues/102013]: Add a new (unstable) C-API function for iterating over GC'able objects using a callback: PyUnstable_VisitObjects.

Python 3.12.0 alpha 6

Release date: 2023-03-07

Security

gh-99108 [https://github.com/python/cpython/issues/99108]: Replace builtin hashlib implementations of MD5 and SHA1 with verified ones from the HACL* project.

gh-101727 [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 CVE-2023-0286 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-0286], CVE-2022-4303 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-4303], and CVE-2022-4303 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-4303] per the OpenSSL 2023-02-07 security advisory [https://www.openssl.org/news/secadv/20230207.txt].

gh-99108 [https://github.com/python/cpython/issues/99108]: Replace the builtin hashlib implementations of SHA2-384 and SHA2-512 originally from LibTomCrypt with formally verified, side-channel resistant code from the HACL* [https://github.com/hacl-star/hacl-star/] project. The builtins remain a fallback only used when OpenSSL does not provide them.

gh-101283 [https://github.com/python/cpython/issues/101283]: subprocess.Popen now uses a safer approach to find cmd.exe when launching with shell=True. Patch by Eryk Sun, based on a patch by Oleg Iarygin.

Core and Builtins

gh-102493 [https://github.com/python/cpython/issues/102493]: Fix regression in semantics of normalisation in PyErr_SetObject.

gh-102416 [https://github.com/python/cpython/issues/102416]: Do not memoize incorrectly automatically generated loop rules in the parser. Patch by Pablo Galindo.

gh-102356 [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.

gh-102336 [https://github.com/python/cpython/issues/102336]: Cleanup Windows 7 specific special handling. Patch by Max Bachmann.

gh-102250 [https://github.com/python/cpython/issues/102250]: Fixed a segfault occurring when the interpreter calls a __bool__ method that raises.

gh-102126 [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.

gh-102027 [https://github.com/python/cpython/issues/102027]: Use GetCurrentProcessId on Windows when getpid is unavailable. Patch by Max Bachmann.

gh-102056 [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.

gh-100982 [https://github.com/python/cpython/issues/100982]: Restrict the scope of the FOR_ITER_RANGE instruction to the scope of the original FOR_ITER instruction, to allow instrumentation.

gh-101967 [https://github.com/python/cpython/issues/101967]: Fix possible segfault in positional_only_passed_as_keyword function, when new list created.

gh-101952 [https://github.com/python/cpython/issues/101952]: Fix possible segfault in BUILD_SET opcode, when new set created.

gh-74895 [https://github.com/python/cpython/issues/74895]: socket.getaddrinfo no longer raises OverflowError for 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 socket.gaierror SAI_SERVICE may occur instead, or no error at all as not all platform C libraries generate an error.

gh-101799 [https://github.com/python/cpython/issues/101799]: Add CALL_INTRINSIC_2 and use it instead of PREP_RERAISE_STAR.

gh-101857 [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.

gh-84783 [https://github.com/python/cpython/issues/84783]: Make the slice object hashable. Patch by Will Bradshaw and Furkan Onder.

gh-87849 [https://github.com/python/cpython/issues/87849]: Change the SEND instruction to leave the receiver on the stack. This allows the specialized form of SEND to skip the chain of C calls and jump directly to the RESUME in the generator or coroutine.

gh-101765 [https://github.com/python/cpython/issues/101765]: Fix SystemError / segmentation fault in iter __reduce__ when internal access of builtins.__dict__ keys mutates the iter object.

gh-101430 [https://github.com/python/cpython/issues/101430]: Update tracemalloc to handle presize of object properly. Patch by Donghee Na.

gh-101696 [https://github.com/python/cpython/issues/101696]: Invalidate type version tag in _PyStaticType_Dealloc for static types, avoiding bug where a false cache hit could crash the interpreter. Patch by Kumar Aditya.

gh-101632 [https://github.com/python/cpython/issues/101632]: Adds a new RETURN_CONST instruction.

gh-100719 [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.

gh-98627 [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 Py_NewInterpreter().

Library

gh-102302 [https://github.com/python/cpython/issues/102302]: Micro-optimise hashing of inspect.Parameter, reducing the time it takes to hash an instance by around 40%.

gh-101979 [https://github.com/python/cpython/issues/101979]: Fix a bug where parentheses in the metavar argument to argparse.ArgumentParser.add_argument() were dropped. Patch by Yeojin Kim.

gh-91038 [https://github.com/python/cpython/issues/91038]: platform.platform() now has boolean default arguments.

gh-81652 [https://github.com/python/cpython/issues/81652]: Add mmap.MAP_ALIGNED_SUPER FreeBSD and mmap.MAP_CONCEAL OpenBSD constants to mmap. Patch by Yeojin Kim.

gh-102179 [https://github.com/python/cpython/issues/102179]: Fix os.dup2() error message for negative fds.

gh-101961 [https://github.com/python/cpython/issues/101961]: For the binary mode, fileinput.hookcompressed() doesn't set the encoding value even if the value is None. Patch by Gihwan Kim.

gh-101936 [https://github.com/python/cpython/issues/101936]: The default value of fp becomes io.BytesIO if HTTPError is initialized without a designated fp parameter. Patch by Long Vo.

gh-101566 [https://github.com/python/cpython/issues/101566]: In zipfile, sync Path with zipp 3.14 [https://zipp.readthedocs.io/en/latest/history.html#v3-14-0], including fix for extractall on the underlying zipfile after being wrapped in Path.

gh-97930 [https://github.com/python/cpython/issues/97930]: Apply changes from importlib_resources 5.12 [https://importlib-resources.readthedocs.io/en/latest/history.html#v5-12-0], including fix for MultiplexedPath to support directories in multiple namespaces (python/importlib_resources#265).

gh-101997 [https://github.com/python/cpython/issues/101997]: Upgrade pip wheel bundled with ensurepip (pip 23.0.1)

gh-99108 [https://github.com/python/cpython/issues/99108]: The built-in extension modules for hashlib SHA2 algorithms, used when OpenSSL does not provide them, now live in a single internal _sha2 module instead of separate _sha256 and _sha512 modules.

gh-101892 [https://github.com/python/cpython/issues/101892]: Callable iterators no longer raise SystemError when the callable object exhausts the iterator but forgets to either return a sentinel value or raise StopIteration.

gh-87634 [https://github.com/python/cpython/issues/87634]: Remove locking behavior from functools.cached_property().

gh-97786 [https://github.com/python/cpython/issues/97786]: Fix potential undefined behaviour in corner cases of floating-point-to-time conversions.

gh-101517 [https://github.com/python/cpython/issues/101517]: Fixed bug where bdb looks up the source line with linecache with a lineno=None, which causes it to fail with an unhandled exception.

gh-101773 [https://github.com/python/cpython/issues/101773]: Optimize fractions.Fraction for small components. The private argument _normalize of the fractions.Fraction constructor has been removed.

gh-101693 [https://github.com/python/cpython/issues/101693]: In sqlite3.Cursor.execute(), DeprecationWarning is now emitted when named placeholders are used together with parameters supplied as a sequence instead of as a dict. Starting from Python 3.14, using named placeholders with parameters supplied as a sequence will raise a ProgrammingError. Patch by Erlend E. Aasland.

gh-101446 [https://github.com/python/cpython/issues/101446]: Change repr of collections.OrderedDict to use regular dictionary formating instead of pairs of keys and values.

gh-101362 [https://github.com/python/cpython/issues/101362]: Speed up pathlib.PurePath construction by handling arguments more uniformly. When a pathlib.Path argument is supplied, we use its string representation rather than joining its parts with os.path.join().

gh-101362 [https://github.com/python/cpython/issues/101362]: Speed up pathlib.PurePath construction by calling os.path.join() only when two or more arguments are given.

gh-101362 [https://github.com/python/cpython/issues/101362]: Speed up pathlib.Path construction by running the path flavour compatibility check only when pathlib is imported.

gh-85984 [https://github.com/python/cpython/issues/85984]: Refactored the implementation of pty.fork() to use os.login_tty().

A DeprecationWarning is now raised by pty.master_open() and pty.slave_open(). They were undocumented and deprecated long long ago in the docstring in favor of pty.openpty().

gh-101561 [https://github.com/python/cpython/issues/101561]: Add a new decorator typing.override(). See PEP 698 [https://peps.python.org/pep-0698/] for details. Patch by Steven Troxler.

gh-63301 [https://github.com/python/cpython/issues/63301]: Set exit code when tabnanny CLI exits on error.

gh-101360 [https://github.com/python/cpython/issues/101360]: Fix anchor matching in pathlib.PureWindowsPath.match(). Path and pattern anchors are now matched with fnmatch, just like other path parts. This allows patterns such as "*:/Users/*" to be matched.

gh-101277 [https://github.com/python/cpython/issues/101277]: Remove global state from itertools module (PEP 687 [https://peps.python.org/pep-0687/]). Patches by Erlend E. Aasland.

gh-100809 [https://github.com/python/cpython/issues/100809]: Fix handling of drive-relative paths (like 'C:' and 'C:foo') in pathlib.Path.absolute(). This method now uses the OS API to retrieve the correct current working directory for the drive.

gh-99138 [https://github.com/python/cpython/issues/99138]: Apply PEP 687 [https://peps.python.org/pep-0687/] to zoneinfo. Patch by Erlend E. Aasland.

gh-96764 [https://github.com/python/cpython/issues/96764]: asyncio.wait_for() now uses asyncio.timeout() as its underlying implementation. Patch by Kumar Aditya.

gh-88233 [https://github.com/python/cpython/issues/88233]: Correctly preserve "extra" fields in zipfile regardless of their ordering relative to a zip64 "extra."

bpo-23224 [https://bugs.python.org/issue?@action=redirect&bpo=23224]: Fix segfaults when creating lzma.LZMADecompressor and bz2.BZ2Decompressor objects without calling __init__(), and fix leakage of locks and internal buffers when calling the __init__() methods of lzma.LZMADecompressor, lzma.LZMACompressor, bz2.BZ2Compressor, and bz2.BZ2Decompressor objects multiple times.

Documentation

gh-85417 [https://github.com/python/cpython/issues/85417]: Update cmath documentation to clarify behaviour on branch cuts.

gh-97725 [https://github.com/python/cpython/issues/97725]: Fix asyncio.Task.print_stack() description for file=None. Patch by Oleg Iarygin.

Tests

gh-102019 [https://github.com/python/cpython/issues/102019]: Fix deadlock on shutdown if test_current_{exception,frames} fails. Patch by Jacob Bower.

gh-85984 [https://github.com/python/cpython/issues/85984]: Utilize new "winsize" functions from termios in pty tests.

gh-89792 [https://github.com/python/cpython/issues/89792]: test_tools now copies up to 10x less source data to a temporary directory during the 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.

Build

gh-99942 [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.

gh-99942 [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.

gh-100221 [https://github.com/python/cpython/issues/100221]: Fix creating install directories in make sharedinstall if they exist outside DESTDIR already.

gh-96821 [https://github.com/python/cpython/issues/96821]: Explicitly mark C extension modules that need defined signed integer overflow, and add a configure option --with-strict-overflow. Patch by Matthias Görgens and Shantanu Jain.

Windows

gh-102344 [https://github.com/python/cpython/issues/102344]: Implement winreg.QueryValue using QueryValueEx and winreg.SetValue using SetValueEx. Patch by Max Bachmann.

gh-101881 [https://github.com/python/cpython/issues/101881]: Handle read and write operations on non-blocking pipes properly on Windows.

gh-101881 [https://github.com/python/cpython/issues/101881]: Add support for the os.get_blocking() and os.set_blocking() functions on Windows.

gh-101849 [https://github.com/python/cpython/issues/101849]: Ensures installer will correctly upgrade existing py.exe launcher installs.

gh-101763 [https://github.com/python/cpython/issues/101763]: Updates copy of libffi bundled with Windows installs to 3.4.4.

gh-101759 [https://github.com/python/cpython/issues/101759]: Update Windows installer to SQLite 3.40.1.

gh-101614 [https://github.com/python/cpython/issues/101614]: Correctly handle extensions built against debug binaries that reference python3_d.dll.

gh-101196 [https://github.com/python/cpython/issues/101196]: The functions os.path.isdir, os.path.isfile, os.path.islink and os.path.exists are now 13% to 28% faster on Windows, by making fewer Win32 API calls.

macOS

gh-101759 [https://github.com/python/cpython/issues/101759]: Update macOS installer to SQLite 3.40.1.

C API

gh-101907 [https://github.com/python/cpython/issues/101907]: Removes use of non-standard C++ extension in public header files.

gh-99293 [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.

gh-101578 [https://github.com/python/cpython/issues/101578]: Add PyErr_GetRaisedException() and 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 PyErr_Fetch() and PyErr_Restore(). This is less error prone and a bit more efficient.

Add PyException_GetArgs() and PyException_SetArgs() as convenience functions for retrieving and modifying the args passed to the exception's constructor.

gh-91744 [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 PEP 689 [https://peps.python.org/pep-0689/] for details.

Python 3.12.0 alpha 5

Release date: 2023-02-07

Security

gh-99108 [https://github.com/python/cpython/issues/99108]: Replace the builtin hashlib implementations of SHA2-224 and SHA2-256 originally from LibTomCrypt with formally verified, side-channel resistant code from the HACL* [https://github.com/hacl-star/hacl-star/] project. The builtins remain a fallback only used when OpenSSL does not provide them.

Core and Builtins

gh-92173 [https://github.com/python/cpython/issues/92173]: Fix the defs and kwdefs arguments to PyEval_EvalCodeEx() and a reference leak in that function.

gh-59956 [https://github.com/python/cpython/issues/59956]: The GILState API is now partially compatible with subinterpreters. Previously, PyThreadState_GET() and PyGILState_GetThisThreadState() would get out of sync, causing inconsistent behavior and crashes.

gh-101400 [https://github.com/python/cpython/issues/101400]: Fix wrong lineno in exception message on continue or break which are not in a loop. Patch by Donghee Na.

gh-101372 [https://github.com/python/cpython/issues/101372]: Fix is_normalized() to properly handle the UCD 3.2.0 cases. Patch by Donghee Na.

gh-101266 [https://github.com/python/cpython/issues/101266]: Fix sys.getsizeof() reporting for int subclasses.

gh-101291 [https://github.com/python/cpython/issues/101291]: Refactor the PyLongObject struct into a normal Python object header and a PyLongValue struct.

gh-101046 [https://github.com/python/cpython/issues/101046]: Fix a possible memory leak in the parser when raising MemoryError. Patch by Pablo Galindo

gh-101037 [https://github.com/python/cpython/issues/101037]: Fix potential memory underallocation issue for instances of int subclasses with value zero.

gh-100762 [https://github.com/python/cpython/issues/100762]: Record the (virtual) exception block depth in the oparg of YIELD_VALUE. Use this to avoid the expensive throw() when closing generators (and coroutines) that can be closed trivially.

gh-100982 [https://github.com/python/cpython/issues/100982]: Adds a new 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.

gh-100942 [https://github.com/python/cpython/issues/100942]: Fixed segfault in property.getter/setter/deleter that occurred when a property subclass overrode the __new__ method to return a non-property instance.

gh-100923 [https://github.com/python/cpython/issues/100923]: Remove the mask cache entry for the COMPARE_OP instruction and embed the mask into the oparg.

gh-100892 [https://github.com/python/cpython/issues/100892]: Fix race while iterating over thread states in clearing threading.local. Patch by Kumar Aditya.

gh-91351 [https://github.com/python/cpython/issues/91351]: Fix a case where re-entrant imports could corrupt the import deadlock detection code and cause a KeyError to be raised out of 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)

gh-100726 [https://github.com/python/cpython/issues/100726]: Optimize construction of range object for medium size integers.

gh-100712 [https://github.com/python/cpython/issues/100712]: Added option to build cpython with specialization disabled, by setting ENABLE_SPECIALIZATION=False in opcode, followed by make regen-all.

bpo-32780 [https://bugs.python.org/issue?@action=redirect&bpo=32780]: Inter-field padding is now inserted into the PEP3118 format strings obtained from ctypes.Structure objects, reflecting their true representation in memory.

Library

gh-101541 [https://github.com/python/cpython/issues/101541]: [Enum] - fix psuedo-flag creation

gh-101570 [https://github.com/python/cpython/issues/101570]: Upgrade pip wheel bundled with ensurepip (pip 23.0)

gh-101323 [https://github.com/python/cpython/issues/101323]: Fix a bug where errors where not thrown by zlib._ZlibDecompressor if encountered during decompressing.

gh-101317 [https://github.com/python/cpython/issues/101317]: Add ssl_shutdown_timeout parameter for asyncio.StreamWriter.start_tls().

gh-101326 [https://github.com/python/cpython/issues/101326]: Fix regression when passing None as second or third argument to FutureIter.throw.

gh-92123 [https://github.com/python/cpython/issues/92123]: Adapt the _elementtree extension module to multi-phase init (PEP 489 [https://peps.python.org/pep-0489/]). Patches by Erlend E. Aasland.

gh-100795 [https://github.com/python/cpython/issues/100795]: Avoid potential unexpected freeaddrinfo call (double free) in socket when when a libc getaddrinfo() implementation leaves garbage in an output pointer when returning an error. Original patch by Sergey G. Brester.

gh-101143 [https://github.com/python/cpython/issues/101143]: Remove unused references to TimerHandle in asyncio.base_events.BaseEventLoop._add_callback.

gh-101144 [https://github.com/python/cpython/issues/101144]: Make zipfile.Path.open() and zipfile.Path.read_text() also accept 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 TypeError.

gh-94518 [https://github.com/python/cpython/issues/94518]: Group-related variables of _posixsubprocess module are renamed to stress that supplimentary group affinity is added to a fork, not replace the inherited ones. Patch by Oleg Iarygin.

gh-101015 [https://github.com/python/cpython/issues/101015]: Fix typing.get_type_hints() on '*tuple[...]' and *tuple[...]. It must not drop the Unpack part.

gh-101000 [https://github.com/python/cpython/issues/101000]: Add os.path.splitroot(), which splits a path into a 3-item tuple (drive, root, tail). This new function is used by pathlib to improve the performance of path construction by up to a third.

gh-100573 [https://github.com/python/cpython/issues/100573]: Fix a Windows asyncio bug with named pipes where a client doing os.stat() on the pipe would cause an error in the server that disabled serving future requests.

gh-39615 [https://github.com/python/cpython/issues/39615]: warnings.warn() now has the ability to skip stack frames based on code filename prefix rather than only a numeric stacklevel via the new skip_file_prefixes keyword argument.

gh-100750 [https://github.com/python/cpython/issues/100750]: pass encoding kwarg to subprocess in platform

gh-100160 [https://github.com/python/cpython/issues/100160]: Emit a deprecation warning in asyncio.DefaultEventLoopPolicy.get_event_loop() if there is no current event loop set and it decides to create one.

gh-96290 [https://github.com/python/cpython/issues/96290]: Fix handling of partial and invalid UNC drives in ntpath.splitdrive(), and in ntpath.normpath() on non-Windows systems. Paths such as '\server' and '\' are now considered by splitdrive() to contain only a drive, and consequently are not modified by normpath() on non-Windows systems. The behaviour of normpath() on Windows systems is unaffected, as native OS APIs are used. Patch by Eryk Sun, with contributions by Barney Gale.

gh-99952 [https://github.com/python/cpython/issues/99952]: Fix a reference undercounting issue in ctypes.Structure with from_param() results larger than a C pointer.

gh-67790 [https://github.com/python/cpython/issues/67790]: Add float-style formatting support for fractions.Fraction instances.

gh-99266 [https://github.com/python/cpython/issues/99266]: Preserve more detailed error messages in ctypes.

gh-86682 [https://github.com/python/cpython/issues/86682]: Ensure runtime-created collections have the correct module name using the newly added (internal) sys._getframemodulename().

gh-88597 [https://github.com/python/cpython/issues/88597]: uuid now has a command line interface. Try python -m uuid -h.

gh-60580 [https://github.com/python/cpython/issues/60580]: ctypes.wintypes.BYTE definition changed from c_byte to c_ubyte to match Windows SDK. Patch by Anatoly Techtonik and Oleg Iarygin.

gh-94518 [https://github.com/python/cpython/issues/94518]: _posixsubprocess now initializes all UID and GID variables using a reserved -1 value instead of a separate flag. Patch by Oleg Iarygin.

bpo-38941 [https://bugs.python.org/issue?@action=redirect&bpo=38941]: The xml.etree.ElementTree module now emits DeprecationWarning when testing the truth value of an xml.etree.ElementTree.Element. Before, the Python implementation emitted FutureWarning, and the C implementation emitted nothing.

bpo-40077 [https://bugs.python.org/issue?@action=redirect&bpo=40077]: Convert elementtree types to heap types. Patch by Erlend E. Aasland.

bpo-29847 [https://bugs.python.org/issue?@action=redirect&bpo=29847]: Fix a bug where pathlib.Path accepted and ignored keyword arguments. Patch provided by Yurii Karabas.

gh-77772 [https://github.com/python/cpython/issues/77772]: ctypes.CDLL, ctypes.OleDLL, ctypes.WinDLL, and ctypes.PyDLL now accept path-like objects as their name argument. Patch by Robert Hoelzl.

Documentation

gh-88324 [https://github.com/python/cpython/issues/88324]: Reword subprocess to emphasize default behavior of stdin, stdout, and stderr arguments. Remove inaccurate statement about child file handle inheritance.

Tests

gh-101334 [https://github.com/python/cpython/issues/101334]: test_tarfile has been updated to pass when run as a high UID.

Build

gh-101282 [https://github.com/python/cpython/issues/101282]: Update BOLT configration not to use depreacted usage of --split functions. Patch by Donghee Na.

gh-101522 [https://github.com/python/cpython/issues/101522]: Allow overriding Windows dependencies versions and paths using MSBuild properties.

gh-77532 [https://github.com/python/cpython/issues/77532]: Minor fixes to allow building with PlatformToolset=ClangCL on Windows.

gh-101152 [https://github.com/python/cpython/issues/101152]: In accordance with PEP 699 [https://peps.python.org/pep-0699/], the ma_version_tag field in 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.

gh-100340 [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.

gh-101060 [https://github.com/python/cpython/issues/101060]: Conditionally add -fno-reorder-blocks-and-partition in configure. Effectively fixes --enable-bolt when using Clang, as this appears to be a GCC-only flag.

gh-98705 [https://github.com/python/cpython/issues/98705]: __bool__ is defined in AIX system header files which breaks the build in AIX, so undefine it.

gh-98636 [https://github.com/python/cpython/issues/98636]: Fix a regression in detecting gdbm_compat library for the _gdbm module build.

gh-96305 [https://github.com/python/cpython/issues/96305]: _aix_support now uses a simple code to get platform details rather than the now non-existent _bootsubprocess during bootstrap.

Windows

gh-101543 [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.

gh-101467 [https://github.com/python/cpython/issues/101467]: The py.exe launcher now correctly filters when only a single runtime is installed. It also correctly handles prefix matches on tags so that -3.1 does not match 3.11, but would still match 3.1-32.

gh-99834 [https://github.com/python/cpython/issues/99834]: Updates bundled copy of Tcl/Tk to 8.6.13.0

gh-101135 [https://github.com/python/cpython/issues/101135]: Restore ability to launch older 32-bit versions from the py.exe launcher when both 32-bit and 64-bit installs of the same version are available.

gh-82052 [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.

gh-100320 [https://github.com/python/cpython/issues/100320]: Ensures the 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.

gh-100247 [https://github.com/python/cpython/issues/100247]: Restores support for the py.exe launcher finding shebang commands in its configuration file using the full command name.

Python 3.12.0 alpha 4

Release date: 2023-01-10

Core and Builtins

gh-100776 [https://github.com/python/cpython/issues/100776]: Fix misleading default value in input()'s __text_signature__.

gh-99005 [https://github.com/python/cpython/issues/99005]: Remove UNARY_POSITIVE, ASYNC_GEN_WRAP and LIST_TO_TUPLE, replacing them with intrinsics.

gh-99005 [https://github.com/python/cpython/issues/99005]: Add new CALL_INTRINSIC_1 instruction. Remove IMPORT_STAR, PRINT_EXPR and STOPITERATION_ERROR, replacing them with the CALL_INTRINSIC_1 instruction.

gh-100288 [https://github.com/python/cpython/issues/100288]: Remove the LOAD_ATTR_METHOD_WITH_DICT specialized instruction. Stats show it is not useful.

gh-100720 [https://github.com/python/cpython/issues/100720]: Added _PyFrame_NumSlotsForCodeObject, which returns the number of slots needed in a frame for a given code object.

gh-100719 [https://github.com/python/cpython/issues/100719]: Removed the co_nplaincellvars field from the code object, as it is redundant.

gh-100637 [https://github.com/python/cpython/issues/100637]: Fix int.__sizeof__() calculation to include the 1-element ob_digit array for 0 and False.

gh-100649 [https://github.com/python/cpython/issues/100649]: Update the native_thread_id field of PyThreadState after fork.

gh-100126 [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.

gh-87447 [https://github.com/python/cpython/issues/87447]: Fix SyntaxError on comprehension rebind checking with names that are not actually redefined.

Now reassigning b in [(b := 1) for a, b.prop in some_iter] is allowed. Reassigning a is still disallowed as per PEP 572 [https://peps.python.org/pep-0572/].

gh-100268 [https://github.com/python/cpython/issues/100268]: Add int.is_integer() to improve duck type compatibility between int and float.

gh-100425 [https://github.com/python/cpython/issues/100425]: Improve the accuracy of sum() with compensated summation.

gh-100374 [https://github.com/python/cpython/issues/100374]: Fix incorrect result and delay in socket.getfqdn(). Patch by Dominic Socular.

gh-100357 [https://github.com/python/cpython/issues/100357]: Convert vars, dir, next, getattr, and iter to argument clinic.

gh-100117 [https://github.com/python/cpython/issues/100117]: Improve the output of codeobject.co_lines() by emitting only one entry for each line range.

gh-90043 [https://github.com/python/cpython/issues/90043]: Handle NaNs when specializing COMPARE_OP for float values.

gh-100222 [https://github.com/python/cpython/issues/100222]: Redefine the _Py_CODEUNIT typedef as a union to describe its layout to the C compiler, avoiding type punning and improving clarity.

gh-99955 [https://github.com/python/cpython/issues/99955]: Internal compiler functions (in compile.c) now consistently return -1 on error and 0 on success.

gh-100188 [https://github.com/python/cpython/issues/100188]: The BINARY_SUBSCR_LIST_INT and BINARY_SUBSCR_TUPLE_INT instructions are no longer used for negative integers because those instructions always miss when encountering negative integers.

gh-99110 [https://github.com/python/cpython/issues/99110]: Initialize frame->previous in frameobject.c to fix a segmentation fault when accessing frames created by PyFrame_New().

gh-94155 [https://github.com/python/cpython/issues/94155]: Improved the hashing algorithm for code objects, mitigating some hash collisions.

gh-99540 [https://github.com/python/cpython/issues/99540]: None now hashes to a constant value. This is not a requirements change.

gh-100143 [https://github.com/python/cpython/issues/100143]: When built with --enable-pystats, stats collection is now off by default. To enable it early at startup, pass the -Xpystats flag. Stats are now always dumped, even if switched off.

gh-100146 [https://github.com/python/cpython/issues/100146]: Improve BUILD_LIST opcode so that it works similarly to the 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 _PyList_FromArraySteal().

gh-100110 [https://github.com/python/cpython/issues/100110]: Specialize FOR_ITER for tuples.

gh-100050 [https://github.com/python/cpython/issues/100050]: Honor existing errors obtained when searching for mismatching parentheses in the tokenizer. Patch by Pablo Galindo

gh-92216 [https://github.com/python/cpython/issues/92216]: Improve the performance of hasattr() for type objects with a missing attribute.

gh-99582 [https://github.com/python/cpython/issues/99582]: Freeze zipimport module into _bootstrap_python.

gh-99554 [https://github.com/python/cpython/issues/99554]: Pack debugging location tables more efficiently during bytecode compilation.

gh-98522 [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.

gh-94603 [https://github.com/python/cpython/issues/94603]: Improve performance of list.pop for small lists.

gh-89051 [https://github.com/python/cpython/issues/89051]: Add ssl.OP_LEGACY_SERVER_CONNECT

bpo-32782 [https://bugs.python.org/issue?@action=redirect&bpo=32782]: ctypes arrays of length 0 now report a correct itemsize when a memoryview is constructed from them, rather than always giving a value of 0.

Library

gh-100833 [https://github.com/python/cpython/issues/100833]: Speed up math.fsum() by removing defensive volatile qualifiers.

gh-100805 [https://github.com/python/cpython/issues/100805]: Modify random.choice() implementation to once again work with NumPy arrays.

gh-100813 [https://github.com/python/cpython/issues/100813]: Add socket.IP_PKTINFO constant.

gh-100792 [https://github.com/python/cpython/issues/100792]: Make email.message.Message.__contains__() twice as fast.

gh-91851 [https://github.com/python/cpython/issues/91851]: Microoptimizations for fractions.Fraction.__round__(), fractions.Fraction.__ceil__() and fractions.Fraction.__floor__().

gh-90104 [https://github.com/python/cpython/issues/90104]: Avoid RecursionError on repr if a dataclass field definition has a cyclic reference.

gh-100689 [https://github.com/python/cpython/issues/100689]: Fix crash in pyexpat by statically allocating PyExpat_CAPI capsule.

gh-100740 [https://github.com/python/cpython/issues/100740]: Fix unittest.mock.Mock not respecting the spec for attribute names prefixed with assert.

gh-91219 [https://github.com/python/cpython/issues/91219]: Change SimpleHTTPRequestHandler to support subclassing to provide a different set of index file names instead of using __init__ parameters.

gh-100690 [https://github.com/python/cpython/issues/100690]: Mock objects which are not unsafe will now raise an AttributeError when accessing an attribute that matches the name of an assertion but without the prefix assert_, e.g. accessing called_once instead of assert_called_once. This is in addition to this already happening for accessing attributes with prefixes assert, assret, asert, aseert, and assrt.

gh-89727 [https://github.com/python/cpython/issues/89727]: Simplify and optimize os.walk() by using isinstance() checks to check the top of the stack.

gh-100485 [https://github.com/python/cpython/issues/100485]: Add math.sumprod() to compute the sum of products.

gh-86508 [https://github.com/python/cpython/issues/86508]: Fix asyncio.open_connection() to skip binding to local addresses of different family. Patch by Kumar Aditya.

gh-97930 [https://github.com/python/cpython/issues/97930]: 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 package to anchor with a compatibility shim for those passing by keyword. Additionally, the new anchor parameter is now optional and will default to the caller's module.

gh-100585 [https://github.com/python/cpython/issues/100585]: Fixed a bug where importlib.resources.as_file was leaving file pointers open

gh-100562 [https://github.com/python/cpython/issues/100562]: Improve performance of pathlib.Path.absolute() by nearly 2x. This comes at the cost of a performance regression in pathlib.Path.cwd(), which is generally used less frequently in user code.

gh-100519 [https://github.com/python/cpython/issues/100519]: Small simplification of http.cookiejar.eff_request_host() that improves readability and better matches the RFC wording.

gh-100287 [https://github.com/python/cpython/issues/100287]: Fix the interaction of unittest.mock.seal() with unittest.mock.AsyncMock.

gh-100488 [https://github.com/python/cpython/issues/100488]: Add Fraction.is_integer() to check whether a fractions.Fraction is an integer. This improves duck type compatibility with float and int.

gh-100474 [https://github.com/python/cpython/issues/100474]: http.server now checks that an index page is actually a regular file before trying to serve it. This avoids issues with directories named index.html.

gh-100363 [https://github.com/python/cpython/issues/100363]: Speed up asyncio.get_running_loop() by removing redundant getpid checks. Patch by Kumar Aditya.

gh-78878 [https://github.com/python/cpython/issues/78878]: Fix crash when creating an instance of _ctypes.CField.

gh-100348 [https://github.com/python/cpython/issues/100348]: Fix ref cycle in asyncio._SelectorSocketTransport by removing _read_ready_cb in close.

gh-100344 [https://github.com/python/cpython/issues/100344]: Provide C implementation for asyncio.current_task() for a 4x-6x speedup.

gh-100272 [https://github.com/python/cpython/issues/100272]: Fix JSON serialization of OrderedDict. It now preserves the order of keys.

gh-83076 [https://github.com/python/cpython/issues/83076]: Instantiation of Mock() and AsyncMock() is now 3.8x faster.

gh-100234 [https://github.com/python/cpython/issues/100234]: Set a default value of 1.0 for the lambd parameter in random.expovariate().

gh-100228 [https://github.com/python/cpython/issues/100228]: A DeprecationWarning may be raised when os.fork() or 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.

gh-100039 [https://github.com/python/cpython/issues/100039]: Improve signatures for enums and flags.

gh-100133 [https://github.com/python/cpython/issues/100133]: Fix regression in asyncio where a subprocess would sometimes lose data received from pipe.

bpo-44592 [https://bugs.python.org/issue?@action=redirect&bpo=44592]: Fixes inconsistent handling of case sensitivity of extrasaction arg in csv.DictWriter.

gh-100098 [https://github.com/python/cpython/issues/100098]: Fix tuple subclasses being cast to tuple when used as enum values.

gh-85432 [https://github.com/python/cpython/issues/85432]: Rename the fmt parameter of the pure-Python implementation of datetime.time.strftime() to format. Rename the t parameter of 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.

gh-98778 [https://github.com/python/cpython/issues/98778]: Update HTTPError to be initialized properly, even if the fp is None. Patch by Donghee Na.

gh-99925 [https://github.com/python/cpython/issues/99925]: Unify error messages in JSON serialization between json.dumps(float('nan'), allow_nan=False) and json.dumps(float('nan'), allow_nan=False, indent=<SOMETHING>). Now both include the representation of the value that could not be serialized.

gh-89727 [https://github.com/python/cpython/issues/89727]: Fix issue with os.walk() where a RecursionError would occur on deep directory structures by adjusting the implementation of os.walk() to be iterative instead of recursive.

gh-94943 [https://github.com/python/cpython/issues/94943]: Add データクラスのサポート to the Enum __repr__(). When inheriting from a dataclass, only show the field names in the value section of the member repr(), and not the dataclass' class name.

gh-83035 [https://github.com/python/cpython/issues/83035]: Fix inspect.getsource() handling of decorator calls with nested parentheses.

gh-99576 [https://github.com/python/cpython/issues/99576]: Fix .save() method for LWPCookieJar and MozillaCookieJar: saved file was not truncated on repeated save.

gh-94912 [https://github.com/python/cpython/issues/94912]: Add inspect.markcoroutinefunction() decorator which manually marks a function as a coroutine for the benefit of iscoroutinefunction().

gh-99509 [https://github.com/python/cpython/issues/99509]: Add PEP 585 [https://peps.python.org/pep-0585/] support for multiprocessing.queues.Queue.

gh-99482 [https://github.com/python/cpython/issues/99482]: Remove Jython partial compatibility code from several stdlib modules.

gh-99433 [https://github.com/python/cpython/issues/99433]: Fix doctest failure on types.MethodWrapperType in modules.

gh-85267 [https://github.com/python/cpython/issues/85267]: Several improvements to inspect.signature()'s handling of __text_signature. - Fixes a case where inspect.signature() dropped parameters - Fixes a case where inspect.signature() raised tokenize.TokenError - Allows inspect.signature() to understand defaults involving binary operations of constants - inspect.signature() is documented as only raising TypeError or ValueError, but sometimes raised RuntimeError. These cases now raise ValueError - Removed a dead code path

gh-91166 [https://github.com/python/cpython/issues/91166]: asyncio is optimized to avoid excessive copying when writing to socket and use sendmsg() if the platform supports it. Patch by Kumar Aditya.

gh-98030 [https://github.com/python/cpython/issues/98030]: Add missing TCP socket options from Linux: TCP_MD5SIG, TCP_THIN_LINEAR_TIMEOUTS, TCP_THIN_DUPACK, TCP_REPAIR, TCP_REPAIR_QUEUE, TCP_QUEUE_SEQ, TCP_REPAIR_OPTIONS, TCP_TIMESTAMP, TCP_CC_INFO, TCP_SAVE_SYN, TCP_SAVED_SYN, TCP_REPAIR_WINDOW, TCP_FASTOPEN_CONNECT, TCP_ULP, TCP_MD5SIG_EXT, TCP_FASTOPEN_KEY, TCP_FASTOPEN_NO_COOKIE, TCP_ZEROCOPY_RECEIVE, TCP_INQ, TCP_TX_DELAY.

gh-88500 [https://github.com/python/cpython/issues/88500]: Reduced the memory usage of urllib.parse.unquote() and urllib.parse.unquote_to_bytes() on large values.

gh-96127 [https://github.com/python/cpython/issues/96127]: inspect.signature was raising TypeError on call with mock objects. Now it correctly returns (*args, **kwargs) as infered signature.

gh-95882 [https://github.com/python/cpython/issues/95882]: Fix a 3.11 regression in asynccontextmanager(), which caused it to propagate exceptions with incorrect tracebacks and fix a 3.11 regression in contextmanager(), which caused it to propagate exceptions with incorrect tracebacks for StopIteration.

gh-78707 [https://github.com/python/cpython/issues/78707]: Deprecate passing more than one positional argument to pathlib.PurePath.relative_to() and is_relative_to().

gh-92122 [https://github.com/python/cpython/issues/92122]: Fix reStructuredText syntax errors in docstrings in the enum module.

gh-91851 [https://github.com/python/cpython/issues/91851]: Optimize the Fraction arithmetics for small components.

bpo-24132 [https://bugs.python.org/issue?@action=redirect&bpo=24132]: Make pathlib.PurePath and Path subclassable (private to start). Previously, attempting to instantiate a subclass resulted in an AttributeError being raised. Patch by Barney Gale.

bpo-40447 [https://bugs.python.org/issue?@action=redirect&bpo=40447]: Accept os.PathLike (such as pathlib.Path) in the stripdir arguments of compileall.compile_file() and compileall.compile_dir().

bpo-36880 [https://bugs.python.org/issue?@action=redirect&bpo=36880]: Fix a reference counting issue when a ctypes callback with return type py_object returns None, which could cause crashes.

Documentation

gh-100616 [https://github.com/python/cpython/issues/100616]: Document existing attr parameter to curses.window.vline() function in curses.

gh-100472 [https://github.com/python/cpython/issues/100472]: Remove claim in documentation that the stripdir, prependdir and limit_sl_dest parameters of compileall.compile_dir() and compileall.compile_file() could be bytes.

bpo-25377 [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)

Tests

gh-100454 [https://github.com/python/cpython/issues/100454]: Start running SSL tests with OpenSSL 3.1.0-beta1.

gh-100086 [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.

gh-93018 [https://github.com/python/cpython/issues/93018]: Make two tests forgiving towards host system libexpat with backported security fixes applied.

Build

gh-100540 [https://github.com/python/cpython/issues/100540]: Removed the --with-system-ffi configure option; 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 pkg-config to find libffi and never setting -DUSING_APPLE_OS_LIBFFI. Now on Darwin platforms configure will first check for the OS libffi and then fall back to the same processing as other platforms if it is not found.

gh-88267 [https://github.com/python/cpython/issues/88267]: Avoid exporting Python symbols in linked Windows applications when the core is built as static.

bpo-41916 [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.

Windows

gh-100180 [https://github.com/python/cpython/issues/100180]: Update Windows installer to OpenSSL 1.1.1s

gh-99191 [https://github.com/python/cpython/issues/99191]: Use _MSVC_LANG >= 202002L instead of less-precise _MSC_VER >=1929 to more accurately test for C++20 support in PC/_wmimodule.cpp.

gh-79218 [https://github.com/python/cpython/issues/79218]: Define MS_WIN64 for Mingw-w64 64bit, fix cython compilation failure.

gh-99941 [https://github.com/python/cpython/issues/99941]: Ensure that asyncio.Protocol.data_received() receives an immutable bytes object (as documented), instead of bytearray.

bpo-43984 [https://bugs.python.org/issue?@action=redirect&bpo=43984]: winreg.SetValueEx() now leaves the target value untouched in the case of conversion errors. Previously, -1 would be written in case of such errors.

bpo-34816 [https://bugs.python.org/issue?@action=redirect&bpo=34816]: hasattr(ctypes.windll, 'nonexistant') now returns False instead of raising OSError.

macOS

gh-100180 [https://github.com/python/cpython/issues/100180]: Update macOS installer to OpenSSL 1.1.1s

gh-100540 [https://github.com/python/cpython/issues/100540]: Removed obsolete dlfcn.h shim from the _ctypes extension module, which has not been necessary since Mac OS X 10.2.

Tools/Demos

bpo-45256 [https://bugs.python.org/issue?@action=redirect&bpo=45256]: Fix a bug that caused an AttributeError to be raised in python-gdb.py when py-locals is used without a frame.

gh-100342 [https://github.com/python/cpython/issues/100342]: Add missing NULL check for possible allocation failure in *args parsing in Argument Clinic.

C API

gh-99947 [https://github.com/python/cpython/issues/99947]: Raising SystemError on import will now have its cause be set to the original unexpected exception.

gh-99240 [https://github.com/python/cpython/issues/99240]: In argument parsing, after deallocating newly allocated memory, reset its pointer to NULL.

gh-98724 [https://github.com/python/cpython/issues/98724]: The Py_CLEAR, Py_SETREF and 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.

Python 3.12.0 alpha 3

Release date: 2022-12-06

Security

gh-100001 [https://github.com/python/cpython/issues/100001]: 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 http.server BaseHTTPRequestHandler .log_message method to replace control characters with a \xHH hex escape before printing.

gh-87604 [https://github.com/python/cpython/issues/87604]: Avoid publishing list of active per-interpreter audit hooks via the gc module

Core and Builtins

gh-99891 [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

gh-91054 [https://github.com/python/cpython/issues/91054]: Add PyCode_AddWatcher() and PyCode_ClearWatcher() APIs to register callbacks to receive notification on creation and destruction of code objects.

gh-99729 [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.

gh-99708 [https://github.com/python/cpython/issues/99708]: Fix bug where compiler crashes on an if expression with an empty body block.

gh-99578 [https://github.com/python/cpython/issues/99578]: Fix a reference bug in _imp.create_builtin() after the creation of the first sub-interpreter for modules builtins and sys. Patch by Victor Stinner.

gh-99581 [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 caracter from a file that is as long as the available tokenizer buffer. Patch by Pablo galindo

gh-99553 [https://github.com/python/cpython/issues/99553]: Fix bug where an ExceptionGroup subclass can wrap a BaseException.

gh-99547 [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.

gh-99370 [https://github.com/python/cpython/issues/99370]: Fix zip path for venv created from a non-installed python on POSIX platforms.

gh-99377 [https://github.com/python/cpython/issues/99377]: Add audit events for thread creation and clear operations.

gh-98686 [https://github.com/python/cpython/issues/98686]: Remove the BINARY_OP_GENERIC and COMPARE_OP_GENERIC "specializations".

gh-99298 [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 PyType_Ready() called on them yet.

gh-99127 [https://github.com/python/cpython/issues/99127]: Allow some features of syslog to the main interpreter only. Patch by Donghee Na.

gh-91053 [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.

gh-90994 [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 foo(a=). - A value is assigned to a star argument, eg foo(*args=[0]). - A value is assigned to a double-star keyword argument, eg foo(**kwarg={'a': 0}).

bpo-45026 [https://bugs.python.org/issue?@action=redirect&bpo=45026]: Optimize the range object iterator. It is now smaller, faster iteration of ranges containing large numbers. Smaller pickles, faster unpickling.

bpo-31718 [https://bugs.python.org/issue?@action=redirect&bpo=31718]: Raise ValueError instead of SystemError when methods of uninitialized io.IncrementalNewlineDecoder objects are called. Patch by Oren Milman.

bpo-38031 [https://bugs.python.org/issue?@action=redirect&bpo=38031]: Fix a possible assertion failure in io.FileIO when the opener returns an invalid file descriptor.

Library

gh-100001 [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 ambiguious as to if it is a hex replacement we put in or the characters r"x" came through in the original request line.

gh-99957 [https://github.com/python/cpython/issues/99957]: Add frozen_default parameter to typing.dataclass_transform().

gh-79033 [https://github.com/python/cpython/issues/79033]: Fix asyncio.Server.wait_closed() to actually do what the docs promise -- wait for all existing connections to complete, after closing the server.

gh-51524 [https://github.com/python/cpython/issues/51524]: Fix bug when calling trace.CoverageResults with valid infile.

gh-99645 [https://github.com/python/cpython/issues/99645]: Fix a bug in handling class cleanups in unittest.TestCase. Now addClassCleanup() uses separate lists for different TestCase subclasses, and doClassCleanups() only cleans up the particular class.

gh-99508 [https://github.com/python/cpython/issues/99508]: Fix TypeError in Lib/importlib/_bootstrap_external.py while calling _imp.source_hash().

gh-66285 [https://github.com/python/cpython/issues/66285]: Fix asyncio to not share event loop and signal wakeupfd in forked processes. Patch by Kumar Aditya.

gh-97001 [https://github.com/python/cpython/issues/97001]: Release the GIL when calling termios APIs to avoid blocking threads.

gh-92647 [https://github.com/python/cpython/issues/92647]: Use final status of an enum to determine lookup or creation branch of functional API.

gh-99388 [https://github.com/python/cpython/issues/99388]: Add loop_factory parameter to asyncio.run() to allow specifying a custom event loop factory. Patch by Kumar Aditya.

gh-99341 [https://github.com/python/cpython/issues/99341]: Fix ast.increment_lineno() to also cover ast.TypeIgnore when changing line numbers.

gh-99382 [https://github.com/python/cpython/issues/99382]: Check the number of arguments in substitution in user generics containing a TypeVarTuple and one or more TypeVar.

gh-99379 [https://github.com/python/cpython/issues/99379]: Fix substitution of ParamSpec followed by TypeVarTuple in generic aliases.

gh-99344 [https://github.com/python/cpython/issues/99344]: Fix substitution of TypeVarTuple and ParamSpec together in user generics.

gh-99284 [https://github.com/python/cpython/issues/99284]: Remove _use_broken_old_ctypes_structure_semantics_ old untested and undocumented hack from ctypes.

gh-99201 [https://github.com/python/cpython/issues/99201]: Fix IndexError when initializing the config variables on Windows if HAVE_DYNAMIC_LOADING is not set.

gh-99240 [https://github.com/python/cpython/issues/99240]: Fix double-free bug in Argument Clinic str_converter by extracting memory clean up to a new post_parsing section.

gh-64490 [https://github.com/python/cpython/issues/64490]: Fix refcount error when arguments are packed to tuple in Argument Clinic.

gh-99029 [https://github.com/python/cpython/issues/99029]: pathlib.PurePath.relative_to() now treats naked Windows drive paths as relative. This brings its behaviour in line with other parts of pathlib.

gh-98253 [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.

gh-98458 [https://github.com/python/cpython/issues/98458]: Fix infinite loop in unittest when a self-referencing chained exception is raised

gh-93453 [https://github.com/python/cpython/issues/93453]: asyncio.get_event_loop() and many other asyncio functions like asyncio.ensure_future(), asyncio.shield() or asyncio.gather(), and also the get_event_loop() method of asyncio.BaseDefaultEventLoopPolicy now raise a 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. DeprecationWarning is no longer emitted if there is no running event loop but the current event loop was set.

gh-97966 [https://github.com/python/cpython/issues/97966]: On uname_result, restored expectation that _fields and _asdict would include all six properties including processor.

gh-98248 [https://github.com/python/cpython/issues/98248]: Provide informative error messages in struct.pack() when its integral arguments are not in range.

gh-98108 [https://github.com/python/cpython/issues/98108]: zipfile.Path is now pickleable if its initialization parameters were pickleable (e.g. for file system paths).

gh-98098 [https://github.com/python/cpython/issues/98098]: Created packages from zipfile and test_zipfile modules, separating zipfile.Path functionality.

gh-82836 [https://github.com/python/cpython/issues/82836]: Fix is_private properties in the ipaddress module. Previously non-private networks (0.0.0.0/0) would return True from this method; now they correctly return False.

gh-96828 [https://github.com/python/cpython/issues/96828]: Add an OP_ENABLE_KTLS option for enabling the use of the kernel TLS (kTLS). Patch by Illia Volochii.

gh-88863 [https://github.com/python/cpython/issues/88863]: To avoid apparent memory leaks when 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.

gh-91078 [https://github.com/python/cpython/issues/91078]: TarFile.next() now returns None when called on an empty tarfile.

bpo-47220 [https://bugs.python.org/issue?@action=redirect&bpo=47220]: Document the optional callback parameter of WeakMethod. Patch by Géry Ogam.

bpo-44817 [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().

bpo-41260 [https://bugs.python.org/issue?@action=redirect&bpo=41260]: Rename the fmt parameter of the pure Python implementation of datetime.date.strftime() to format.

bpo-15999 [https://bugs.python.org/issue?@action=redirect&bpo=15999]: All built-in functions now accept arguments of any type instead of just bool and int for boolean parameters.

Documentation

gh-99931 [https://github.com/python/cpython/issues/99931]: Use sphinxext-opengraph [https://sphinxext-opengraph.readthedocs.io/] to generate OpenGraph metadata [https://ogp.me/].

gh-89682 [https://github.com/python/cpython/issues/89682]: Reworded docstring of the default __contains__ to clarify that it returns a bool.

gh-88330 [https://github.com/python/cpython/issues/88330]: Improved the description of what a resource is in importlib.resources docs.

gh-92892 [https://github.com/python/cpython/issues/92892]: Document that calling variadic functions with ctypes requires special care on macOS/arm64 (and possibly other platforms).

bpo-41825 [https://bugs.python.org/issue?@action=redirect&bpo=41825]: Restructured the documentation for the os.wait* family of functions, and improved the docs for os.waitid() with more explanation of the possible argument constants.

Tests

gh-99892 [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.

gh-99934 [https://github.com/python/cpython/issues/99934]: Correct test_marsh on (32 bit) x86: test_deterministic sets was failing.

gh-99741 [https://github.com/python/cpython/issues/99741]: We've implemented multi-phase init (PEP 489/630/687) for the internal (for testing) _xxsubinterpreters module.

gh-99659 [https://github.com/python/cpython/issues/99659]: Optional big memory tests in test_sqlite3 now catch the correct sqlite.DataError exception type in case of too large strings and/or blobs passed.

gh-99593 [https://github.com/python/cpython/issues/99593]: Cover the Unicode C API with tests.

gh-96002 [https://github.com/python/cpython/issues/96002]: Add functional test for Argument Clinic.

Build

gh-99086 [https://github.com/python/cpython/issues/99086]: Fix -Wimplicit-int, -Wstrict-prototypes, and -Wimplicit-function-declaration compiler warnings in configure checks.

gh-99337 [https://github.com/python/cpython/issues/99337]: Fix a compilation issue with GCC 12 on macOS.

gh-99289 [https://github.com/python/cpython/issues/99289]: Add a COMPILEALL_OPTS variable in Makefile to override compileall options (default: -j0) in make install. Also merged the compileall commands into a single command building .pyc files for the all optimization levels (0, 1, 2) at once. Patch by Victor Stinner.

gh-98872 [https://github.com/python/cpython/issues/98872]: Fix a possible fd leak in Programs/_freeze_module.c introduced in Python 3.11.

gh-88226 [https://github.com/python/cpython/issues/88226]: Always define TARGET_* labels in Python/ceval.c, even if USE_COMPUTED_GOTOS is disabled. This allows breakpoints to be set at those labels in (for instance) gdb.

Windows

gh-99345 [https://github.com/python/cpython/issues/99345]: Use faster initialization functions to detect install location for Windows Store package

gh-98629 [https://github.com/python/cpython/issues/98629]: Fix initialization of sys.version and sys._git on Windows

gh-99442 [https://github.com/python/cpython/issues/99442]: Fix handling in Windows の Python ランチャ when argv[0] does not include a file extension.

bpo-40882 [https://bugs.python.org/issue?@action=redirect&bpo=40882]: Fix a memory leak in multiprocessing.shared_memory.SharedMemory on Windows.

macOS

gh-87235 [https://github.com/python/cpython/issues/87235]: On macOS python3 /dev/fd/9 9</path/to/script.py failed for any script longer than a couple of bytes.

gh-98940 [https://github.com/python/cpython/issues/98940]: Fix Mac/Extras.install.py file filter bug.

Tools/Demos

gh-64490 [https://github.com/python/cpython/issues/64490]: Argument Clinic varargs bugfixes

Fix out-of-bounds error in _PyArg_UnpackKeywordsWithVararg().

Fix incorrect check which allowed more than one varargs in clinic.py.

Fix miscalculation of noptargs in generated code.

Do not generate noptargs when there is a vararg argument and no optional argument.

C API

gh-98680 [https://github.com/python/cpython/issues/98680]: PyBUF_* constants were marked as part of Limited API of Python 3.11+. These were available in 3.11.0 with Py_LIMITED_API defined for 3.11, and are necessary to use the buffer API.

gh-99612 [https://github.com/python/cpython/issues/99612]: Fix PyUnicode_DecodeUTF8Stateful() for ASCII-only data: *consumed was not set.

gh-47146 [https://github.com/python/cpython/issues/47146]: The structmember.h header is deprecated. Its non-deprecated contents are now available just by including Python.h, with a Py_ prefix added if it was missing. (Deprecated contents are T_OBJECT, T_NONE, and no-op flags.) Patch by Petr Viktorin, based on earlier work by Alexander Belopolsky and Matthias Braun.

Python 3.12.0 alpha 2

Release date: 2022-11-14

Security

gh-98433 [https://github.com/python/cpython/issues/98433]: The IDNA codec decoder used on DNS hostnames by socket or 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 urllib http 3xx 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 RFC 3454 [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 RFC 5894 [https://datatracker.ietf.org/doc/html/rfc5894.html] section 6 and RFC 3491 [https://datatracker.ietf.org/doc/html/rfc3491.html].

gh-98739 [https://github.com/python/cpython/issues/98739]: Update bundled libexpat to 2.5.0

Core and Builtins

gh-81057 [https://github.com/python/cpython/issues/81057]: The docs clearly say that PyImport_Inittab, PyImport_AppendInittab(), and PyImport_ExtendInittab() should not be used after Py_Initialize() has been called. We now enforce this for the two functions. Additionally, the runtime now uses an internal copy of PyImport_Inittab, to guard against modification.

gh-99298 [https://github.com/python/cpython/issues/99298]: Fix an issue that could potentially cause incorrect error handling for some bytecode instructions.

gh-99254 [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).

gh-99205 [https://github.com/python/cpython/issues/99205]: Fix an issue that prevented PyThreadState and PyInterpreterState memory from being freed properly.

gh-81057 [https://github.com/python/cpython/issues/81057]: The 18 global C variables holding the state of the allocators have been moved to _PyRuntimeState. This is a strictly internal change with no change in behavior.

gh-99181 [https://github.com/python/cpython/issues/99181]: Fix failure in except* with unhashable exceptions.

gh-99204 [https://github.com/python/cpython/issues/99204]: Fix calculation of 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>").

gh-96055 [https://github.com/python/cpython/issues/96055]: Update faulthandler to emit an error message with the proper unexpected signal number. Patch by Donghee Na.

gh-99153 [https://github.com/python/cpython/issues/99153]: Fix location of SyntaxError for a try block with both except and except*.

gh-98686 [https://github.com/python/cpython/issues/98686]: Merge the adaptive opcode logic into each instruction's unquickened variant, and merge the logic in EXTENDED_ARG_QUICK into EXTENDED_ARG. With these changes, the quickening that happens at code object creation is now only responsible for initializing warmup counters and inserting superinstructions.

gh-99103 [https://github.com/python/cpython/issues/99103]: Fix the error reporting positions of specialized traceback anchors when the source line contains Unicode characters.

gh-99139 [https://github.com/python/cpython/issues/99139]: Improve the error suggestion for NameError exceptions for instances. Now if a 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 self.<NAME> instead of the closest match in the method scope. Patch by Pablo Galindo

gh-98401 [https://github.com/python/cpython/issues/98401]: Octal escapes with value larger than 0o377 (ex: "\477"), deprecated in Python 3.11, now produce a SyntaxWarning, instead of DeprecationWarning. In a future Python version they will be eventually a SyntaxError. Patch by Victor Stinner.

gh-98401 [https://github.com/python/cpython/issues/98401]: A backslash-character pair that is not a valid escape sequence now generates a SyntaxWarning, instead of DeprecationWarning. For example, re.compile("\d+\.\d+") now emits a SyntaxWarning ("\d" is an invalid escape sequence), use raw strings for regular expression: re.compile(r"\d+\.\d+"). In a future Python version, SyntaxError will eventually be raised, instead of SyntaxWarning. Patch by Victor Stinner.

gh-96793 [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.

gh-98931 [https://github.com/python/cpython/issues/98931]: Improve the SyntaxError error message when the user types import x from y instead of from y import x. Patch by Pablo Galindo

gh-98852 [https://github.com/python/cpython/issues/98852]: Fix subscription of type aliases containing bare generic types or types like TypeVar: for example tuple[A, T][int] and tuple[TypeVar, T][int], where A is a generic type, and T is a type variable.

gh-98925 [https://github.com/python/cpython/issues/98925]: Lower the recursion depth for marshal on WASI to support (in-development) wasmtime 2.0.

gh-98783 [https://github.com/python/cpython/issues/98783]: Fix multiple crashes in debug mode when str subclasses are used instead of str itself.

gh-98811 [https://github.com/python/cpython/issues/98811]: Use complete source locations to simplify detection of __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.

gh-96793 [https://github.com/python/cpython/issues/96793]: Add specialization of FOR_ITER for generators. Saves multiple layers of dispatch and checking to get from the FOR_ITER instruction in the caller to the RESUME in the generator.

gh-98762 [https://github.com/python/cpython/issues/98762]: Fix source locations of match sub-patterns.

gh-98586 [https://github.com/python/cpython/issues/98586]: Added the methods PyObject_Vectorcall() and PyObject_VectorcallMethod() to the Limited API along with the auxiliary macro constant PY_VECTORCALL_ARGUMENTS_OFFSET.

The availability of these functions enables more efficient PEP 590 [https://peps.python.org/pep-0590/] vector calls from binary extension modules that avoid argument boxing/unboxing overheads.

gh-99257 [https://github.com/python/cpython/issues/99257]: Fix an issue where member descriptors (such as those for __slots__) could behave incorrectly or crash instead of raising a TypeError when accessed via an instance of an invalid type.

gh-93143 [https://github.com/python/cpython/issues/93143]: Rather than changing co_code, the interpreter will now display a RuntimeWarning and assign None to any fast locals that are left unbound after jumps or del statements executed while tracing.

gh-96421 [https://github.com/python/cpython/issues/96421]: When calling into Python code from C code, through PyEval_EvalFrameEx() or a related C-API function, a shim frame in inserted into the call stack. This occurs in the _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 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 RETURN_VALUE, YIELD_VALUE, and RETURN_GENERATOR, which now clear the frame.

gh-98415 [https://github.com/python/cpython/issues/98415]: Fix detection of MAC addresses for uuid on certain OSs. Patch by Chaim Sanders

gh-98686 [https://github.com/python/cpython/issues/98686]: Quicken all code objects, and specialize adaptive bytecode instructions more aggressively.

gh-92119 [https://github.com/python/cpython/issues/92119]: Print exception class name instead of its string representation when raising errors from ctypes calls.

gh-91058 [https://github.com/python/cpython/issues/91058]: ImportError raised from failed from <module> import <name> now include suggestions for the value of <name> based on the available names in <module>. Patch by Pablo Galindo

gh-96793 [https://github.com/python/cpython/issues/96793]: The FOR_ITER now leaves the iterator on the stack on termination of the loop. This is to assist specialization of loops for generators.

gh-90716 [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.

gh-95389 [https://github.com/python/cpython/issues/95389]: Expose ETH_P_ALL and some of the ETHERTYPE_* constants in socket. Patch by Noam Cohen.

gh-93696 [https://github.com/python/cpython/issues/93696]: Allow pdb to locate source for frozen modules in the standard library.

Library

gh-99418 [https://github.com/python/cpython/issues/99418]: Fix bug in urllib.parse.urlparse() that causes URL schemes that begin with a digit, a plus sign, or a minus sign to be parsed incorrectly.

gh-94597 [https://github.com/python/cpython/issues/94597]: Deprecate asyncio.AbstractChildWatcher to be removed in Python 3.14. Patch by Kumar Aditya.

gh-99305 [https://github.com/python/cpython/issues/99305]: Improve performance of secrets.token_hex().

gh-74044 [https://github.com/python/cpython/issues/74044]: Fixed bug where inspect.signature() reported incorrect arguments for decorated methods.

gh-99275 [https://github.com/python/cpython/issues/99275]: Fix SystemError in ctypes when exception was not set during __initsubclass__.

gh-99277 [https://github.com/python/cpython/issues/99277]: Remove older version of _SSLProtocolTransport.get_write_buffer_limits in asyncio.sslproto

gh-99248 [https://github.com/python/cpython/issues/99248]: fix negative numbers failing in verify()

gh-99155 [https://github.com/python/cpython/issues/99155]: Fix statistics.NormalDist pickle with 0 and 1 protocols.

gh-93464 [https://github.com/python/cpython/issues/93464]: enum.auto() is now correctly activated when combined with other assignment values. E.g. ONE = auto(), 'some text' will now evaluate as (1, 'some text').

gh-99134 [https://github.com/python/cpython/issues/99134]: Update the bundled copy of pip to version 22.3.1.

gh-92584 [https://github.com/python/cpython/issues/92584]: Remove the distutils package. It was deprecated in Python 3.10 by PEP 632 [https://peps.python.org/pep-0632/] "Deprecate distutils module". For projects still using distutils and cannot be updated to something else, the setuptools project can be installed: it still provides distutils. Patch by Victor Stinner.

gh-98999 [https://github.com/python/cpython/issues/98999]: Now _pyio is consistent with _io in raising ValueError when executing methods over closed buffers.

gh-83004 [https://github.com/python/cpython/issues/83004]: Clean up refleak on failed module initialisation in _zoneinfo

gh-83004 [https://github.com/python/cpython/issues/83004]: Clean up refleaks on failed module initialisation in _pickle

gh-83004 [https://github.com/python/cpython/issues/83004]: Clean up refleak on failed module initialisation in _io.

gh-98897 [https://github.com/python/cpython/issues/98897]: Fix memory leak in math.dist() when both points don't have the same dimension. Patch by Kumar Aditya.

gh-98878 [https://github.com/python/cpython/issues/98878]: Use the frame bound builtins when offering a name suggestion in traceback to prevent crashing when __builtins__ is not a dict.

gh-98139 [https://github.com/python/cpython/issues/98139]: In importlib._bootstrap, enhance namespace package repr to <module 'x' (namespace) from ['path']>.

gh-90352 [https://github.com/python/cpython/issues/90352]: Fix _SelectorDatagramTransport to inherit from DatagramTransport in asyncio. Patch by Kumar Aditya.

gh-98793 [https://github.com/python/cpython/issues/98793]: Fix argument typechecks in _overlapped.WSAConnect() and _overlapped.Overlapped.WSASendTo() functions.

gh-98744 [https://github.com/python/cpython/issues/98744]: Prevent crashing in traceback when retrieving the byte-offset for some source files that contain certain unicode characters.

gh-98740 [https://github.com/python/cpython/issues/98740]: Fix internal error in the re module which in very rare circumstances prevented compilation of a regular expression containing a conditional expression without the "else" branch.

gh-98703 [https://github.com/python/cpython/issues/98703]: Fix asyncio.StreamWriter.drain() to call protocol.connection_lost callback only once on Windows.

gh-98624 [https://github.com/python/cpython/issues/98624]: Add a mutex to unittest.mock.NonCallableMock to protect concurrent access to mock attributes.

gh-98658 [https://github.com/python/cpython/issues/98658]: The array.array class now supports subscripting, making it a generic type.

gh-98284 [https://github.com/python/cpython/issues/98284]: Improved TypeError message for undefined abstract methods of a abc.ABC instance. The names of the missing methods are surrounded by single-quotes to highlight them.

gh-96151 [https://github.com/python/cpython/issues/96151]: Allow BUILTINS to be a valid field name for frozen dataclasses.

gh-98086 [https://github.com/python/cpython/issues/98086]: Make sure patch.dict() can be applied on async functions.

gh-72719 [https://github.com/python/cpython/issues/72719]: Remove modules asyncore and asynchat, which were deprecated by PEP 594 [https://peps.python.org/pep-0594/].

gh-96192 [https://github.com/python/cpython/issues/96192]: Fix handling of bytes path-like objects in os.ismount().

gh-94172 [https://github.com/python/cpython/issues/94172]: ftplib: Remove the FTP_TLS.ssl_version class attribute: use the context parameter instead. Patch by Victor Stinner

gh-94172 [https://github.com/python/cpython/issues/94172]: Remove the keyfile and certfile parameters from the ftplib, imaplib, poplib and smtplib modules, and the key_file, cert_file and check_hostname parameters from the http.client module, all deprecated since Python 3.6. Use the context parameter (ssl_context in imaplib) instead. Patch by Victor Stinner.

gh-83638 [https://github.com/python/cpython/issues/83638]: Add the autocommit attribute to sqlite3.Connection and the autocommit parameter to sqlite3.connect() to control PEP 249 [https://peps.python.org/pep-0249/]-compliant transaction handling. Patch by Erlend E. Aasland.

gh-92452 [https://github.com/python/cpython/issues/92452]: Fixed a race condition that could cause sysconfig.get_config_var() to incorrectly return None in multi-threaded programs.

gh-91803 [https://github.com/python/cpython/issues/91803]: Fix an error when using a method of objects mocked with unittest.mock.create_autospec() after it was sealed with unittest.mock.seal() function.

bpo-38523 [https://bugs.python.org/issue?@action=redirect&bpo=38523]: shutil.copytree() now applies the ignore_dangling_symlinks argument recursively.

bpo-40358 [https://bugs.python.org/issue?@action=redirect&bpo=40358]: Add walk_up argument in pathlib.PurePath.relative_to().

bpo-36267 [https://bugs.python.org/issue?@action=redirect&bpo=36267]: Fix IndexError in argparse.ArgumentParser when a store_true action is given an explicit argument.

Documentation

gh-98832 [https://github.com/python/cpython/issues/98832]: Changes wording of docstring for pathlib.Path.iterdir().

gh-97966 [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.

Tests

gh-98903 [https://github.com/python/cpython/issues/98903]: The Python test suite now fails wit exit code 4 if no tests ran. It should help detecting typos in test names and test methods.

gh-98713 [https://github.com/python/cpython/issues/98713]: Fix a bug in the typing tests where a test relying on CPython-specific implementation details was not decorated with @cpython_only and was not skipped on other implementations.

gh-87390 [https://github.com/python/cpython/issues/87390]: Add tests for star-unpacking with PEP 646, and some other miscellaneous PEP 646 tests.

gh-96853 [https://github.com/python/cpython/issues/96853]: Added explicit coverage of Py_Initialize (and hence Py_InitializeEx) back to the embedding tests (all other embedding tests migrated to Py_InitializeFromConfig in Python 3.11)

bpo-34272 [https://bugs.python.org/issue?@action=redirect&bpo=34272]: Some C API tests were moved into the new Lib/test/test_capi/ directory.

Build

gh-99086 [https://github.com/python/cpython/issues/99086]: Fix -Wimplicit-int compiler warning in configure check for PTHREAD_SCOPE_SYSTEM.

gh-99016 [https://github.com/python/cpython/issues/99016]: Fix build with PYTHON_FOR_REGEN=python3.8.

gh-97731 [https://github.com/python/cpython/issues/97731]: Specify the full path to the source location for make docclean (needed for cross-builds).

gh-98949 [https://github.com/python/cpython/issues/98949]: Drop unused build dependency on readelf.

gh-98989 [https://github.com/python/cpython/issues/98989]: Use python3.11, if available, for regeneration and freezing.

gh-98831 [https://github.com/python/cpython/issues/98831]: Add new tooling, in 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 Python/bytecodes.c, in the form of a custom DSL (under development) [https://github.com/faster-cpython/ideas/blob/main/3.12/interpreter_definition.md]. The tooling reads this file and writes Python/generated_cases.c.h, which is then included by Python/ceval.c to provide most of the cases of the main interpreter switch.

gh-98817 [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.

gh-98776 [https://github.com/python/cpython/issues/98776]: Fix make regen-test-levenshtein for out-of-tree builds.

gh-98707 [https://github.com/python/cpython/issues/98707]: Don't use vendored libmpdec headers if --with-system-libmpdec is passed to configure. Don't use vendored libexpat headers if --with-system-expat is passed to configure.

Windows

gh-98689 [https://github.com/python/cpython/issues/98689]: Update Windows builds to zlib v1.2.13. v1.2.12 has CVE-2022-37434 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-37434], but the vulnerable inflateGetHeader API is not used by Python.

gh-98790 [https://github.com/python/cpython/issues/98790]: Assumes that a missing DLLs directory means that standard extension modules are in the executable's directory.

gh-98745 [https://github.com/python/cpython/issues/98745]: Update py.exe launcher to install 3.11 by default and 3.12 on request.

gh-98692 [https://github.com/python/cpython/issues/98692]: Fix the Windows の Python ランチャ ignoring unrecognized shebang lines instead of treating them as local paths

gh-94328 [https://github.com/python/cpython/issues/94328]: Update Windows installer to use SQLite 3.39.4.

macOS

gh-94328 [https://github.com/python/cpython/issues/94328]: Update macOS installer to SQLite 3.39.4.

C API

gh-98724 [https://github.com/python/cpython/issues/98724]: The Py_CLEAR, Py_SETREF and 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.

gh-98978 [https://github.com/python/cpython/issues/98978]: Fix use-after-free in Py_SetPythonHome(NULL), Py_SetProgramName(NULL) and _Py_SetProgramFullPath(NULL) function calls. Issue reported by Benedikt Reinartz. Patch by Victor Stinner.

gh-98410 [https://github.com/python/cpython/issues/98410]: Add getbufferproc and releasebufferproc to the stable API.

gh-98610 [https://github.com/python/cpython/issues/98610]: Some configurable capabilities of sub-interpreters have changed. They always allow subprocesses (subprocess) now, whereas before subprocesses could be optionally disallowed for a sub-interpreter. Instead 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 _Py_NewInterpreterFromConfig(), which isn't a public API. They do not affect the main interpreter, nor Py_NewInterpreter().

gh-98608 [https://github.com/python/cpython/issues/98608]: A _PyInterpreterConfig has been added and _Py_NewInterpreter() has been renamed to _Py_NewInterpreterFromConfig(). The "isolated_subinterpreters" argument is now a granular config that captures the previous behavior. Note that this is all "private" API.

gh-96853 [https://github.com/python/cpython/issues/96853]: Py_InitializeEx now correctly calls 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)

gh-91248 [https://github.com/python/cpython/issues/91248]: Add PyFrame_GetVar() and PyFrame_GetVarString() functions to get a frame variable by its name. Patch by Victor Stinner.

Python 3.12.0 alpha 1

Release date: 2022-10-25

Security

gh-97616 [https://github.com/python/cpython/issues/97616]: Fix multiplying a list by an integer (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.

gh-97514 [https://github.com/python/cpython/issues/97514]: On Linux the 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 "forkserver" start method is affected.

Abstract sockets have no permissions and could allow any user on the system in the same network namespace [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 CVE-2022-42919 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-42919].

gh-87389 [https://github.com/python/cpython/issues/87389]: http.server: Fix an open redirection vulnerability in the HTTP server when an URI path starts with //. Vulnerability discovered, and initial fix proposed, by Hamza Avvan.

gh-79096 [https://github.com/python/cpython/issues/79096]: LWPCookieJar and MozillaCookieJar create files with file mode 600 instead of 644 (Microsoft Windows is not affected)

gh-92888 [https://github.com/python/cpython/issues/92888]: Fix memoryview use after free when accessing the backing buffer in certain cases.

gh-68966 [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).

Core and Builtins

gh-98374 [https://github.com/python/cpython/issues/98374]: Suppress ImportError for invalid query for help() command. Patch by Donghee Na.

gh-98461 [https://github.com/python/cpython/issues/98461]: Fix source location in bytecode for list, set and dict comprehensions as well as generator expressions.

gh-98354 [https://github.com/python/cpython/issues/98354]: Added unicode check for name attribute of spec argument passed in _imp.create_builtin() function.

gh-98398 [https://github.com/python/cpython/issues/98398]: Fix source location of 'assert' bytecodes.

gh-98390 [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.

gh-98254 [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 NameError is raised to the top level. Patch by Pablo Galindo

gh-97997 [https://github.com/python/cpython/issues/97997]: Add running column offset to the tokenizer state to avoid calculating AST column information with pointer arithmetic.

gh-97973 [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.

gh-96078 [https://github.com/python/cpython/issues/96078]: os.sched_yield() now release the GIL while calling sched_yield(2). Patch by Donghee Na.

gh-97955 [https://github.com/python/cpython/issues/97955]: Migrate zoneinfo to Argument Clinic.

gh-97912 [https://github.com/python/cpython/issues/97912]: The compiler now avoids quadratic behavior when finding which instructions should use the LOAD_FAST_CHECK opcode.

gh-97002 [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.

gh-97943 [https://github.com/python/cpython/issues/97943]: Bugfix: PyFunction_GetAnnotations() should return a borrowed reference. It was returning a new reference.

gh-97922 [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 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.

gh-65961 [https://github.com/python/cpython/issues/65961]: When __package__ is different than __spec__.parent, raise a DeprecationWarning instead of ImportWarning.

Also remove importlib.util.set_package() which was scheduled for removal.

gh-97850 [https://github.com/python/cpython/issues/97850]: Long deprecated, module_repr() should now be completely eradicated.

gh-86298 [https://github.com/python/cpython/issues/86298]: In cases where warnings.warn_explicit() consults the module's loader, an DeprecationWarning is issued when m.__loader__ differs from m.__spec__.loader.

gh-97779 [https://github.com/python/cpython/issues/97779]: Ensure that all Python frame objects are backed by "complete" frames.

gh-91052 [https://github.com/python/cpython/issues/91052]: Add API for subscribing to modification events on selected dictionaries.

gh-97752 [https://github.com/python/cpython/issues/97752]: Fix possible data corruption or crashes when accessing the f_back member of newly-created generator or coroutine frames.

gh-97591 [https://github.com/python/cpython/issues/97591]: Fixed a missing incref/decref pair in Exception.__setstate__(). Patch by Ofey Chan.

gh-97670 [https://github.com/python/cpython/issues/97670]: Remove the sys.getdxp() function and the Tools/scripts/analyze_dxp.py script. DXP stands for "dynamic execution pairs". They were related to DYNAMIC_EXECUTION_PROFILE and DXPAIRS macros which have been removed in Python 3.11. Python can now be built with ./configure --enable-pystats to gather statistics on Python opcodes. Patch by Victor Stinner.

gh-94526 [https://github.com/python/cpython/issues/94526]: Fix the Python path configuration used to initialized 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.

gh-96670 [https://github.com/python/cpython/issues/96670]: The parser now raises SyntaxError when parsing source code containing null bytes. Patch by Pablo Galindo

gh-96975 [https://github.com/python/cpython/issues/96975]: Fix a crash occurring when PyEval_GetFrame() is called while the topmost Python frame is in a partially-initialized state.

gh-96848 [https://github.com/python/cpython/issues/96848]: Fix command line parsing: reject -X int_max_str_digits option with no value (invalid) when the PYTHONINTMAXSTRDIGITS environment variable is set to a valid limit. Patch by Victor Stinner.

gh-95921 [https://github.com/python/cpython/issues/95921]: Fix overly-broad source position information for chained comparisons used as branching conditions.

gh-96821 [https://github.com/python/cpython/issues/96821]: Fix undefined behaviour in audioop.c.

gh-96821 [https://github.com/python/cpython/issues/96821]: Fix undefined behaviour in _testcapimodule.c.

gh-95778 [https://github.com/python/cpython/issues/95778]: When ValueError is raised if an integer is larger than the limit, mention the sys.set_int_max_str_digits() function in the error message. Patch by Victor Stinner.

gh-96387 [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.

gh-96864 [https://github.com/python/cpython/issues/96864]: Fix a possible assertion failure, fatal error, or SystemError if a line tracing event raises an exception while opcode tracing is enabled.

gh-95778 [https://github.com/python/cpython/issues/95778]: The PyLong_FromString function was refactored to make it more maintainable and extensible.

gh-96678 [https://github.com/python/cpython/issues/96678]: Fix undefined behaviour in C code of null pointer arithmetic.

gh-96754 [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.

gh-90997 [https://github.com/python/cpython/issues/90997]: Improve the performance of reading and writing inline bytecode caches on some platforms.

gh-96751 [https://github.com/python/cpython/issues/96751]: Remove dead code from CALL_FUNCTION_EX opcode.

gh-90751 [https://github.com/python/cpython/issues/90751]: memoryview now supports half-floats. Patch by Donghee Na and Antoine Pitrou.

gh-96678 [https://github.com/python/cpython/issues/96678]: Fix case of undefined behavior in ceval.c

gh-64373 [https://github.com/python/cpython/issues/64373]: Convert _functools to argument clinic.

gh-96641 [https://github.com/python/cpython/issues/96641]: Do not expose KeyWrapper in _functools.

gh-96636 [https://github.com/python/cpython/issues/96636]: Ensure that tracing, 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 __del__ method or interrupt.

gh-96572 [https://github.com/python/cpython/issues/96572]: Fix use after free in trace refs build mode. Patch by Kumar Aditya.

gh-96611 [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.

gh-96612 [https://github.com/python/cpython/issues/96612]: Make sure that incomplete frames do not show up in tracemalloc traces.

gh-90230 [https://github.com/python/cpython/issues/90230]: Fix compiler warnings and test failures when building with --enable-pystats.

gh-96587 [https://github.com/python/cpython/issues/96587]: Correctly raise SyntaxError on exception groups (PEP 654 [https://peps.python.org/pep-0654/]) on python versions prior to 3.11

gh-96569 [https://github.com/python/cpython/issues/96569]: Remove two cases of undefined behavoir, by adding NULL checks.

gh-96582 [https://github.com/python/cpython/issues/96582]: Fix possible NULL pointer dereference in _PyThread_CurrentFrames. Patch by Kumar Aditya.

gh-91079 [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.

gh-93911 [https://github.com/python/cpython/issues/93911]: Fix an issue that could prevent LOAD_ATTR from specializing properly when accessing properties.

gh-96348 [https://github.com/python/cpython/issues/96348]: Emit a DeprecationWarning when throw(), throw() or athrow() are called with more than one argument.

gh-95196 [https://github.com/python/cpython/issues/95196]: Disable incorrect pickling of the C implemented classmethod descriptors.

gh-96364 [https://github.com/python/cpython/issues/96364]: Fix text signatures of list.__getitem__ and dict.__getitem__.

gh-96352 [https://github.com/python/cpython/issues/96352]: Fix AttributeError missing name and obj attributes in object.__getattribute__(). Patch by Philip Georgi.

gh-93554 [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:

POP_JUMP_IF_TRUE BACKWARD_TARGET becomes POP_JUMP_IF_FALSE NEXT_BLOCK; JUMP BACKWARD_TARGET.

All the directed conditional jump opcodes were removed: POP_JUMP_FORWARD_IF_TRUE, POP_JUMP_BACKWARD_IF_TRUE, POP_JUMP_FORWARD_IF_FALSE, POP_JUMP_BACKWARD_IF_FALSE, POP_JUMP_FORWARD_IF_NONE, POP_JUMP_BACKWARD_IF_NONE, POP_JUMP_FORWARD_IF_NOT_NONE, POP_JUMP_BACKWARD_IF_NOT_NONE.

The corresponding opcodes without direction are no longer pseudo-instructions, and they implement the forward conditional jumps.

gh-96268 [https://github.com/python/cpython/issues/96268]: Loading a file with invalid UTF-8 will now report the broken character at the correct location.

gh-96237 [https://github.com/python/cpython/issues/96237]: The internal field _PyInterpreterFrame.f_func is renamed to _PyInterpreterFrame.f_funcobj and may be any object. The f_globals and f_builtin fields may hold junk values.

It is safest to treat the _PyInterpreterFrame struct as opaque.

gh-96187 [https://github.com/python/cpython/issues/96187]: Fixed a bug that caused _PyCode_GetExtra to return garbage for negative indexes. Patch by Pablo Galindo

gh-96143 [https://github.com/python/cpython/issues/96143]: Add a new -X perf Python command line option as well as sys.activate_stack_trampoline() and sys.deactivate_stack_trampoline() function in the sys module that allows to set/unset the interpreter in a way that the Linux perf profiler can detect Python calls. The new 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.

gh-96071 [https://github.com/python/cpython/issues/96071]: Fix a deadlock in PyGILState_Ensure() when allocating new thread state. Patch by Kumar Aditya.

gh-96046 [https://github.com/python/cpython/issues/96046]: PyType_Ready() now initializes 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.

gh-96005 [https://github.com/python/cpython/issues/96005]: On WASI ENOTCAPABLE is now mapped to PermissionError. The errno modules exposes the new error number. getpath.py now ignores PermissionError when it cannot open landmark files pybuilddir.txt and pyenv.cfg.

gh-93678 [https://github.com/python/cpython/issues/93678]: Added test a harness for direct unit tests of the compiler's optimization stage. The _testinternalcapi.optimize_cfg() function runs the optimiser on a sequence of instructions. The CfgOptimizationTestCase class in test.support has utilities for invoking the optimizer and checking the output.

gh-95245 [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.

gh-90997 [https://github.com/python/cpython/issues/90997]: Compile virtual try/except blocks to handle exceptions raised during close() or throw() calls through a suspended frame.

gh-95977 [https://github.com/python/cpython/issues/95977]: Optimized calling __get__() with vectorcall. Patch by Kumar Aditya.

gh-91210 [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.

gh-95922 [https://github.com/python/cpython/issues/95922]: Fixed bug where the compiler's eliminate_empty_basic_blocks function ignores the last block of the code unit.

gh-95818 [https://github.com/python/cpython/issues/95818]: Skip over incomplete frames in PyThreadState_GetFrame().

gh-95876 [https://github.com/python/cpython/issues/95876]: Fix format string in _PyPegen_raise_error_known_location that can lead to memory corruption on some 64bit systems. The function was building a tuple with i (int) instead of n (Py_ssize_t) for Py_ssize_t arguments.

gh-95605 [https://github.com/python/cpython/issues/95605]: Fix misleading contents of error message when converting an all-whitespace string to float.

gh-95150 [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.

gh-91146 [https://github.com/python/cpython/issues/91146]: Reduce allocation size of list from str.split() and str.rsplit(). Patch by Donghee Na and Inada Naoki.

gh-87092 [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.

gh-95355 [https://github.com/python/cpython/issues/95355]: _PyPegen_Parser_New now properly detects token memory allocation errors. Patch by Honglin Zhu.

gh-90081 [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.

gh-95324 [https://github.com/python/cpython/issues/95324]: Emit a warning in debug mode if an object does not call PyObject_GC_UnTrack() before deallocation. Patch by Pablo Galindo.

gh-95245 [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.

gh-93678 [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.

gh-95185 [https://github.com/python/cpython/issues/95185]: Prevented crashes in the AST constructor when compiling some absurdly long expressions like "+0"*1000000. RecursionError is now raised instead. Patch by Pablo Galindo

gh-93351 [https://github.com/python/cpython/issues/93351]: ast.AST node positions are now validated when provided to compile() and other related functions. If invalid positions are detected, a ValueError will be raised.

gh-94438 [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 f_lineno attribute of frame objects. In some cases, this could cause inconsistent internal state, resulting in a hard crash of the interpreter.

gh-95060 [https://github.com/python/cpython/issues/95060]: Undocumented PyCode_Addr2Location function now properly returns when addrq argument is less than zero.

gh-95113 [https://github.com/python/cpython/issues/95113]: Replace all EXTENDED_ARG_QUICK instructions with basic 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.

gh-91409 [https://github.com/python/cpython/issues/91409]: Fix incorrect source location info caused by certain optimizations in the bytecode compiler.

gh-95023 [https://github.com/python/cpython/issues/95023]: Implement os.setns() and os.unshare() for Linux. Patch by Noam Cohen.

gh-94036 [https://github.com/python/cpython/issues/94036]: Fix incorrect source location info for some multi-line attribute accesses and method calls.

gh-94938 [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 __eq__ and __hash__. Previously it could cause SystemError or other undesired behavior.

gh-94996 [https://github.com/python/cpython/issues/94996]: ast.parse() will no longer parse function definitions with positional-only params when passed feature_version less than (3, 8). Patch by Shantanu Jain.

gh-94739 [https://github.com/python/cpython/issues/94739]: Allow jumping within, out of, and across exception handlers in the debugger.

gh-94949 [https://github.com/python/cpython/issues/94949]: ast.parse() will no longer parse parenthesized context managers when passed feature_version less than (3, 9). Patch by Shantanu Jain.

gh-94947 [https://github.com/python/cpython/issues/94947]: ast.parse() will no longer parse assignment expressions when passed feature_version less than (3, 8). Patch by Shantanu Jain.

gh-91256 [https://github.com/python/cpython/issues/91256]: Ensures the program name is known for help text during interpreter startup.

gh-94869 [https://github.com/python/cpython/issues/94869]: Fix the column offsets for some expressions in multi-line f-strings ast nodes. Patch by Pablo Galindo.

gh-94893 [https://github.com/python/cpython/issues/94893]: Fix an issue where frame object manipulations could corrupt inline bytecode caches.

gh-94822 [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.

gh-91153 [https://github.com/python/cpython/issues/91153]: Fix an issue where a bytearray item assignment could crash if it's resized by the new value's __index__() method.

gh-90699 [https://github.com/python/cpython/issues/90699]: Fix reference counting bug in bool.__repr__(). Patch by Kumar Aditya.

gh-94694 [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.

gh-93252 [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.

gh-94215 [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.

gh-92228 [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.

gh-94485 [https://github.com/python/cpython/issues/94485]: Line number of a module's RESUME instruction is set to 0 as specified in PEP 626 [https://peps.python.org/pep-0626/].

gh-94438 [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.

gh-91719 [https://github.com/python/cpython/issues/91719]: Reload opcode when raising unknown opcode error in the interpreter main loop, for C compilers to generate dispatching code independently.

gh-94329 [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.

gh-94360 [https://github.com/python/cpython/issues/94360]: Fixed a tokenizer crash when reading encoded files with syntax errors from stdin with non utf-8 encoded text. Patch by Pablo Galindo

gh-88116 [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 INT_MIN. Patch by Pablo Galindo

gh-94262 [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.

gh-94192 [https://github.com/python/cpython/issues/94192]: Fix error for dictionary literals with invalid expression as value.

gh-87995 [https://github.com/python/cpython/issues/87995]: types.MappingProxyType instances are now hashable if the underlying mapping is hashable.

gh-93883 [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.

gh-94163 [https://github.com/python/cpython/issues/94163]: Add BINARY_SLICE and STORE_SLICE instructions for more efficient handling and better specialization of slicing operations, where the slice is explicit in the source code.

gh-94021 [https://github.com/python/cpython/issues/94021]: Fix unreachable code warning in Python/specialize.c.

gh-93911 [https://github.com/python/cpython/issues/93911]: Specialize LOAD_ATTR for objects with custom __getattribute__.

gh-93955 [https://github.com/python/cpython/issues/93955]: Improve performance of attribute lookups on objects with custom __getattribute__ and __getattr__. Patch by Ken Jin.

gh-93911 [https://github.com/python/cpython/issues/93911]: Specialize LOAD_ATTR for property() attributes.

gh-93678 [https://github.com/python/cpython/issues/93678]: Refactor compiler optimisation code so that it no longer needs the struct assembler and 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.

gh-93841 [https://github.com/python/cpython/issues/93841]: When built with -enable-pystats, sys._stats_on(), sys._stats_off(), sys._stats_clear() and sys._stats_dump() functions have been added to enable gathering stats for parts of programs.

gh-93516 [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.

gh-93516 [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.

gh-89828 [https://github.com/python/cpython/issues/89828]: types.GenericAlias no longer relays the __class__ attribute. For example, isinstance(list[int], type) no longer returns True.

gh-93678 [https://github.com/python/cpython/issues/93678]: Refactor the compiler to reduce boilerplate and repetition.

gh-93671 [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

gh-93662 [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.

gh-93461 [https://github.com/python/cpython/issues/93461]: importlib.invalidate_caches() now drops entries from sys.path_importer_cache with a relative path as name. This solves a caching issue when a process changes its current working directory.

FileFinder no longer inserts a dot in the path, e.g. /egg/./spam is now /egg/spam.

gh-93621 [https://github.com/python/cpython/issues/93621]: Change order of bytecode instructions emitted for with and async with to reduce the number of entries in the exception table.

gh-93533 [https://github.com/python/cpython/issues/93533]: Reduce the size of the inline cache for LOAD_METHOD by 2 bytes.

gh-93444 [https://github.com/python/cpython/issues/93444]: Removed redundant fields from the compiler's basicblock struct: b_nofallthrough, b_exit, b_return. They can be easily calculated from the opcode of the last instruction of the block.

gh-93429 [https://github.com/python/cpython/issues/93429]: LOAD_METHOD instruction has been removed. It was merged back into LOAD_ATTR.

gh-93418 [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=".

gh-93382 [https://github.com/python/cpython/issues/93382]: Cache the result of PyCode_GetCode() function to restore the O(1) lookup of the co_code attribute.

gh-93359 [https://github.com/python/cpython/issues/93359]: Ensure that custom ast nodes without explicit end positions can be compiled. Patch by Pablo Galindo.

gh-93356 [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.

gh-93354 [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.

gh-93283 [https://github.com/python/cpython/issues/93283]: Improve error message for invalid syntax of conversion character in f-string expressions.

gh-93345 [https://github.com/python/cpython/issues/93345]: Fix a crash in substitution of a TypeVar in nested generic alias after TypeVarTuple.

gh-93223 [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.

gh-84694 [https://github.com/python/cpython/issues/84694]: The --experimental-isolated-subinterpreters configure option and EXPERIMENTAL_ISOLATED_SUBINTERPRETERS macro have been removed.

gh-91924 [https://github.com/python/cpython/issues/91924]: Fix __lltrace__ debug feature if the stdout encoding is not UTF-8. Patch by Victor Stinner.

gh-93040 [https://github.com/python/cpython/issues/93040]: Wraps unused parameters in Objects/obmalloc.c with Py_UNUSED.

gh-93143 [https://github.com/python/cpython/issues/93143]: Avoid NULL checks for uninitialized local variables by determining at compile time which variables must be initialized.

gh-93061 [https://github.com/python/cpython/issues/93061]: Backward jumps after async for loops are no longer given dubious line numbers.

gh-93065 [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 [https://github.com/MagicStack/immutables/issues/84] for more details.

gh-93012 [https://github.com/python/cpython/issues/93012]: Added the new function PyType_FromMetaclass(), which generalizes the existing 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, PyType_FromMetaclass() is available in the Limited API, which provides a path towards migrating more binding tools onto the Stable ABI.

gh-93021 [https://github.com/python/cpython/issues/93021]: Fix the __text_signature__ for __get__() methods implemented in C. Patch by Jelle Zijlstra.

gh-89914 [https://github.com/python/cpython/issues/89914]: The operand of the YIELD_VALUE instruction is set to the stack depth. This is done to help frame handling on yield and may assist debuggers.

gh-92955 [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.

gh-92930 [https://github.com/python/cpython/issues/92930]: Fixed a crash in _pickle.c from mutating collections during __reduce__ or persistent_id.

gh-90690 [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.

gh-92914 [https://github.com/python/cpython/issues/92914]: Always round the allocated size for lists up to the nearest even number.

gh-92858 [https://github.com/python/cpython/issues/92858]: Improve error message for some suites with syntax error before ':'

gh-90473 [https://github.com/python/cpython/issues/90473]: Decrease default recursion limit on WASI to address limited call stack size.

gh-92804 [https://github.com/python/cpython/issues/92804]: Fix memory leak in memoryview iterator as it was not finalized at exit. Patch by Kumar Aditya.

gh-92777 [https://github.com/python/cpython/issues/92777]: Specialize LOAD_METHOD for objects with lazy dictionaries. Patch by Ken Jin.

gh-92658 [https://github.com/python/cpython/issues/92658]: Add support for connecting and binding to Hyper-V sockets on Windows Hyper-V hosts and guests.

gh-92236 [https://github.com/python/cpython/issues/92236]: Remove spurious "LINE" event when starting a generator or coroutine, visible tracing functions implemented in C.

gh-91102 [https://github.com/python/cpython/issues/91102]: _warnings.warn_explicit() is ported to Argument Clinic.

gh-92619 [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).

gh-88750 [https://github.com/python/cpython/issues/88750]: The deprecated debug build only PYTHONTHREADDEBUG environment variable no longer does anything.

gh-92261 [https://github.com/python/cpython/issues/92261]: Fix hang when trying to iterate over a typing.Union.

gh-91432 [https://github.com/python/cpython/issues/91432]: Specialized the FOR_ITER opcode using the PEP 659 machinery

gh-91399 [https://github.com/python/cpython/issues/91399]: Removed duplicate '{0, 0, 0, 0, 0, 0}' entry in 'Objects/unicodetype_db.h'.

gh-91578 [https://github.com/python/cpython/issues/91578]: Updates the error message for abstract class.

bpo-47091 [https://bugs.python.org/issue?@action=redirect&bpo=47091]: Improve performance of repetition of list and tuple by using memcpy to copy data and performing the reference increments in one step.

bpo-46142 [https://bugs.python.org/issue?@action=redirect&bpo=46142]: Make --help output shorter by moving some info to the new --help-env and --help-xoptions command-line options. Also add --help-all option to print complete usage.

bpo-42316 [https://bugs.python.org/issue?@action=redirect&bpo=42316]: Document some places where an assignment expression needs parentheses.

Library

gh-89237 [https://github.com/python/cpython/issues/89237]: Fix hang on Windows in subprocess.wait_closed() in asyncio with ProactorEventLoop. Patch by Kumar Aditya.

gh-97928 [https://github.com/python/cpython/issues/97928]: tkinter.Text.count() raises now an exception for options starting with "-" instead of silently ignoring them.

gh-98393 [https://github.com/python/cpython/issues/98393]: The os module no longer accepts bytes-like paths, like bytearray and memoryview types: only the exact bytes type is accepted for bytes strings. Patch by Victor Stinner.

gh-98363 [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.

gh-98331 [https://github.com/python/cpython/issues/98331]: Update the bundled copies of pip and setuptools to versions 22.3 and 65.5.0 respectively.

gh-98307 [https://github.com/python/cpython/issues/98307]: A createSocket() method was added to SysLogHandler.

gh-96035 [https://github.com/python/cpython/issues/96035]: Fix bug in urllib.parse.urlparse() that causes certain port numbers containing whitespace, underscores, plus and minus signs, or non-ASCII digits to be incorrectly accepted.

gh-98257 [https://github.com/python/cpython/issues/98257]: Make sys.setprofile() and sys.settrace() functions reentrant. They can no long fail with: RuntimeError("Cannot install a trace function while another trace function is being installed"). Patch by Victor Stinner.

gh-98251 [https://github.com/python/cpython/issues/98251]: Allow venv to pass along PYTHON* variables to ensurepip and pip when they do not impact path resolution

gh-94597 [https://github.com/python/cpython/issues/94597]: Deprecated asyncio.AbstractEventLoopPolicy.get_child_watcher() and asyncio.AbstractEventLoopPolicy.set_child_watcher() methods to be removed in Python 3.14. Patch by Kumar Aditya.

gh-98178 [https://github.com/python/cpython/issues/98178]: On macOS, fix a crash in syslog.syslog() in multi-threaded applications. On macOS, the libc syslog() function is not thread-safe, so syslog.syslog() no longer releases the GIL to call it. Patch by Victor Stinner.

gh-44098 [https://github.com/python/cpython/issues/44098]: Release the GIL when creating mmap.mmap objects on Unix.

gh-87730 [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.

gh-94597 [https://github.com/python/cpython/issues/94597]: The child watcher classes MultiLoopChildWatcher, FastChildWatcher and SafeChildWatcher are deprecated and will be removed in Python 3.14. Patch by Kumar Aditya.

gh-98023 [https://github.com/python/cpython/issues/98023]: Change default child watcher to PidfdChildWatcher on Linux systems which supports it. Patch by Kumar Aditya.

gh-90985 [https://github.com/python/cpython/issues/90985]: Earlier in 3.11 we deprecated asyncio.Task.cancel("message"). We realized we were too harsh, and have undeprecated it.

gh-65961 [https://github.com/python/cpython/issues/65961]: Do not rely solely on __cached__ on modules; code will also support __spec__.cached.

gh-97646 [https://github.com/python/cpython/issues/97646]: Replace deprecated application/javascript with text/javascript in mimetypes. See RFC 9239 [https://datatracker.ietf.org/doc/html/rfc9239.html]. Patch by Noam Cohen.

gh-97930 [https://github.com/python/cpython/issues/97930]: Apply changes from importlib_resources 5.8 and 5.9: Traversable.joinpath provides a concrete implementation. as_file now supports directories of resources.

gh-97850 [https://github.com/python/cpython/issues/97850]: Remove deprecated importlib.util.set_loader() and importlib.util.module_for_loader() from importlib.util.

gh-97837 [https://github.com/python/cpython/issues/97837]: Change deprecate warning message in unittest from

It is deprecated to return a value!=None

to

It is deprecated to return a value that is not None from a test case

gh-97825 [https://github.com/python/cpython/issues/97825]: Fixes AttributeError when subprocess.check_output() is used with argument input=None and either of the arguments encoding or errors are used.

gh-97008 [https://github.com/python/cpython/issues/97008]: NameError and AttributeError spelling suggestions provided since gh-82711 [https://github.com/python/cpython/issues/82711] are now also emitted by the pure Python traceback module. Tests for those suggestions now exercise both implementations to ensure they are equivalent. Patch by Carl Friedrich Bolz-Tereick and Łukasz Langa.

gh-97799 [https://github.com/python/cpython/issues/97799]: dataclass now uses inspect.get_annotations() to examine the annotations on class objects.

gh-97781 [https://github.com/python/cpython/issues/97781]: Removed deprecated interfaces in importlib.metadata (entry points accessed as dictionary, implicit dictionary construction of sequence of EntryPoint objects, mutablility of EntryPoints result, access of entry point by index). entry_points now has a simpler, more straightforward API (returning EntryPoints).

gh-96827 [https://github.com/python/cpython/issues/96827]: Avoid spurious tracebacks from asyncio when default executor cleanup is delayed until after the event loop is closed (e.g. as the result of a keyboard interrupt).

gh-95534 [https://github.com/python/cpython/issues/95534]: gzip.GzipFile.read() reads 10% faster.

gh-97592 [https://github.com/python/cpython/issues/97592]: Avoid a crash in the C version of asyncio.Future.remove_done_callback() when an evil argument is passed.

gh-97639 [https://github.com/python/cpython/issues/97639]: Remove tokenize.NL check from tabnanny.

gh-97545 [https://github.com/python/cpython/issues/97545]: Make Semaphore run faster.

gh-73588 [https://github.com/python/cpython/issues/73588]: Fix generation of the default name of 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.

gh-96865 [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>

gh-97005 [https://github.com/python/cpython/issues/97005]: Update bundled libexpat to 2.4.9

gh-85760 [https://github.com/python/cpython/issues/85760]: Fix race condition in asyncio where process_exited() called before the pipe_data_received() leading to inconsistent output. Patch by Kumar Aditya.

gh-96704 [https://github.com/python/cpython/issues/96704]: Pass the correct contextvars.Context when a asyncio exception handler is called on behalf of a task or callback handle. This adds a new Task method, get_context, and also a new 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.

gh-96819 [https://github.com/python/cpython/issues/96819]: Fixed check in multiprocessing.resource_tracker that guarantees that the length of a write to a pipe is not greater than PIPE_BUF.

gh-95865 [https://github.com/python/cpython/issues/95865]: Reduce urllib.parse.quote_from_bytes() memory use on large values.

Contributed by Dennis Sweeney.

gh-96741 [https://github.com/python/cpython/issues/96741]: Corrected type annotation for dataclass attribute pstats.FunctionProfile.ncalls to be str.

gh-96734 [https://github.com/python/cpython/issues/96734]: Update unicodedata database to Unicode 15.0.0.

gh-96735 [https://github.com/python/cpython/issues/96735]: Fix undefined behaviour in struct.unpack().

gh-46412 [https://github.com/python/cpython/issues/46412]: Improve performance of bool(db) for large ndb/gdb databases. Previously this would call len(db) which would iterate over all keys -- the answer (empty or not) is known after the first key.

gh-96652 [https://github.com/python/cpython/issues/96652]: Fix the faulthandler implementation of faulthandler.register(signal, chain=True) if the sigaction() function is not available: don't call the previous signal handler if it's NULL. Patch by Victor Stinner.

gh-68163 [https://github.com/python/cpython/issues/68163]: Correct conversion of numbers.Rational's to float.

gh-96538 [https://github.com/python/cpython/issues/96538]: Speed up bisect.bisect() functions by taking advantage of type-stability.

gh-96465 [https://github.com/python/cpython/issues/96465]: Fraction hashes are now cached.

gh-96079 [https://github.com/python/cpython/issues/96079]: In typing, fix missing field name and incorrect __module__ in _AnnotatedAlias.

gh-96415 [https://github.com/python/cpython/issues/96415]: Remove types._cell_factory from module namespace.

gh-95987 [https://github.com/python/cpython/issues/95987]: Fix repr of Any subclasses.

gh-96388 [https://github.com/python/cpython/issues/96388]: Work around missing socket functions in socket's __repr__.

gh-96385 [https://github.com/python/cpython/issues/96385]: Fix TypeVarTuple.__typing_prepare_subst__. TypeError was not raised when using more than one TypeVarTuple, like [*T, *V] in type alias substitutions.

gh-96142 [https://github.com/python/cpython/issues/96142]: Add match_args, kw_only, slots, and weakref_slot to _DataclassParams.

gh-96073 [https://github.com/python/cpython/issues/96073]: In inspect, fix overeager replacement of "typing." in formatting annotations.

gh-89258 [https://github.com/python/cpython/issues/89258]: Added a getChildren() method to logging.Logger, to get the immediate child loggers of a logger.

gh-96346 [https://github.com/python/cpython/issues/96346]: Use double caching for compiled RE patterns.

gh-96349 [https://github.com/python/cpython/issues/96349]: Fixed a minor performance regression in threading.Event.__init__()

gh-90467 [https://github.com/python/cpython/issues/90467]: Fix asyncio.streams.StreamReaderProtocol to keep a strong reference to the created task, so that it's not garbage collected

gh-96172 [https://github.com/python/cpython/issues/96172]: Fix a bug in unicodedata: east_asian_width used to return the wrong value for unassigned characters; and for yet unassigned, but reserved characters.

gh-96159 [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.

gh-96175 [https://github.com/python/cpython/issues/96175]: Fix unused localName parameter in the Attr class in xml.dom.minidom.

gh-96145 [https://github.com/python/cpython/issues/96145]: Add AttrDict to JSON module for use with object_hook.

gh-96052 [https://github.com/python/cpython/issues/96052]: Fix handling compiler warnings (SyntaxWarning and DeprecationWarning) in codeop.compile_command() when checking for incomplete input. Previously it emitted warnings and raised a SyntaxError. Now it always returns None for incomplete input without emitting any warnings.

gh-96125 [https://github.com/python/cpython/issues/96125]: Fix incorrect condition that causes sys.thread_info.name to be wrong on pthread platforms.

gh-96019 [https://github.com/python/cpython/issues/96019]: Fix a bug in the makeunicodedata.py script leading to about 13 KiB of space saving in the unicodedata module, specifically the character decomposition data.

gh-95463 [https://github.com/python/cpython/issues/95463]: Remove an incompatible change from bpo-28080 [https://bugs.python.org/issue?@action=redirect&bpo=28080] that caused a regression that ignored the utf8 in ZipInfo.flag_bits. Patch by Pablo Galindo.

gh-69142 [https://github.com/python/cpython/issues/69142]: Add %:z strftime format code (generates tzoffset with colons as separator), see strftime() と strptime() の振る舞い.

gh-95899 [https://github.com/python/cpython/issues/95899]: Fix asyncio.Runner to call asyncio.set_event_loop() only once to avoid calling attach_loop() multiple times on child watchers. Patch by Kumar Aditya.

gh-95736 [https://github.com/python/cpython/issues/95736]: Fix unittest.IsolatedAsyncioTestCase to set event loop before calling setup functions. Patch by Kumar Aditya.

gh-95865 [https://github.com/python/cpython/issues/95865]: Speed up urllib.parse.quote_from_bytes() by replacing a list comprehension with map().

gh-95861 [https://github.com/python/cpython/issues/95861]: Add support for computing Spearman's correlation coefficient to the existing statistics.correlation() function.

gh-95804 [https://github.com/python/cpython/issues/95804]: Fix logging shutdown handler so it respects MemoryHandler.flushOnClose.

gh-95704 [https://github.com/python/cpython/issues/95704]: When a task catches asyncio.CancelledError and raises some other error, the other error should generally not silently be suppressed.

gh-95149 [https://github.com/python/cpython/issues/95149]: The HTTPStatus enum offers a couple of properties to indicate the HTTP status category e.g. HTTPStatus.OK.is_success.

gh-95609 [https://github.com/python/cpython/issues/95609]: Update bundled pip to 22.2.2.

gh-95289 [https://github.com/python/cpython/issues/95289]: Fix asyncio.TaskGroup to propagate exception when asyncio.CancelledError was replaced with another exception by a context manger. Patch by Kumar Aditya and Guido van Rossum.

gh-94909 [https://github.com/python/cpython/issues/94909]: Fix incorrect joining of relative Windows paths with drives in pathlib.PurePath initializer.

gh-95385 [https://github.com/python/cpython/issues/95385]: Faster json.dumps() when sorting of keys is not requested (default).

gh-83901 [https://github.com/python/cpython/issues/83901]: Improve Signature.bind error message for missing keyword-only arguments.

gh-95339 [https://github.com/python/cpython/issues/95339]: Update bundled pip to 22.2.1.

gh-95045 [https://github.com/python/cpython/issues/95045]: Fix GC crash when deallocating _lsprof.Profiler by untracking it before calling any callbacks. Patch by Kumar Aditya.

gh-95231 [https://github.com/python/cpython/issues/95231]: Fail gracefully if EPERM or ENOSYS is raised when loading crypt methods. This may happen when trying to load MD5 on a Linux kernel with FIPS enabled.

gh-95097 [https://github.com/python/cpython/issues/95097]: Fix asyncio.run() for asyncio.Task implementations without uncancel() method. Patch by Kumar Aditya.

gh-95087 [https://github.com/python/cpython/issues/95087]: Fix IndexError in parsing invalid date in the email module.

gh-95199 [https://github.com/python/cpython/issues/95199]: Upgrade bundled setuptools to 63.2.0.

gh-95194 [https://github.com/python/cpython/issues/95194]: Upgrade bundled pip to 22.2.

gh-93899 [https://github.com/python/cpython/issues/93899]: Fix check for existence of os.EFD_CLOEXEC, os.EFD_NONBLOCK and os.EFD_SEMAPHORE flags on older kernel versions where these flags are not present. Patch by Kumar Aditya.

gh-95166 [https://github.com/python/cpython/issues/95166]: Fix concurrent.futures.Executor.map() to cancel the currently waiting on future on an error - e.g. TimeoutError or KeyboardInterrupt.

gh-95132 [https://github.com/python/cpython/issues/95132]: Fix a sqlite3 regression where *args and **kwds were incorrectly relayed from connect() to the Connection factory. The regression was introduced in 3.11a1 with PR 24421 (gh-85128 [https://github.com/python/cpython/issues/85128]). Patch by Erlend E. Aasland.

gh-93157 [https://github.com/python/cpython/issues/93157]: Fix fileinput module didn't support errors option when inplace is true.

gh-91212 [https://github.com/python/cpython/issues/91212]: Fixed flickering of the turtle window when the tracer is turned off. Patch by Shin-myoung-serp.

gh-95077 [https://github.com/python/cpython/issues/95077]: Add deprecation warning for enum member.member access (e.g. Color.RED.BLUE). Remove EnumMeta.__getattr__.

gh-95109 [https://github.com/python/cpython/issues/95109]: Ensure that timeouts scheduled with asyncio.Timeout that have already expired are delivered promptly.

gh-95105 [https://github.com/python/cpython/issues/95105]: wsgiref.types.InputStream.__iter__() should return Iterator[bytes], not Iterable[bytes]. Patch by Shantanu Jain.

gh-95066 [https://github.com/python/cpython/issues/95066]: Replaced assert with exception in ast.parse(), when feature_version has an invalid major version. Patch by Shantanu Jain.

gh-77617 [https://github.com/python/cpython/issues/77617]: Add sqlite3 command-line interface. Patch by Erlend Aasland.

gh-95005 [https://github.com/python/cpython/issues/95005]: Replace _PyAccu with _PyUnicodeWriter in JSON encoder and StringIO and remove the _PyAccu implementation.

gh-90085 [https://github.com/python/cpython/issues/90085]: Remove -c/--clock and -t/--time CLI options of timeit. The options had been deprecated since Python 3.3 and the functionality was removed in Python 3.7. Patch by Shantanu Jain.

gh-94857 [https://github.com/python/cpython/issues/94857]: Fix refleak in _io.TextIOWrapper.reconfigure. Patch by Kumar Aditya.

gh-94821 [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".

gh-94736 [https://github.com/python/cpython/issues/94736]: Fix crash when deallocating an instance of a subclass of _multiprocessing.SemLock. Patch by Kumar Aditya.

gh-81620 [https://github.com/python/cpython/issues/81620]: Add random.binomialvariate().

gh-74116 [https://github.com/python/cpython/issues/74116]: Allow asyncio.StreamWriter.drain() to be awaited concurrently by multiple tasks. Patch by Kumar Aditya.

gh-87822 [https://github.com/python/cpython/issues/87822]: When called with capture_locals=True, the traceback module functions swallow exceptions raised from calls to 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).

gh-88050 [https://github.com/python/cpython/issues/88050]: Fix asyncio subprocess transport to kill process cleanly when process is blocked and avoid RuntimeError when loop is closed. Patch by Kumar Aditya.

gh-94637 [https://github.com/python/cpython/issues/94637]: SSLContext.set_default_verify_paths() now releases the GIL around SSL_CTX_set_default_verify_paths call. The function call performs I/O and CPU intensive work.

gh-94309 [https://github.com/python/cpython/issues/94309]: Deprecate aliases typing.Hashable and typing.Sized

gh-92546 [https://github.com/python/cpython/issues/92546]: An undocumented python -m pprint benchmark is moved into pprint suite of pyperformance. Patch by Oleg Iarygin.

gh-94607 [https://github.com/python/cpython/issues/94607]: Fix subclassing complex generics with type variables in typing. Previously an error message saying Some type variables ... are not listed in Generic[...] was shown. typing no longer populates __parameters__ with the __parameters__ of a Python class.

gh-94619 [https://github.com/python/cpython/issues/94619]: Remove the long-deprecated module_repr() from importlib.

gh-93910 [https://github.com/python/cpython/issues/93910]: The ability to access the other values of an enum on an enum (e.g. Color.RED.BLUE) has been restored in order to fix a performance regression.

gh-93896 [https://github.com/python/cpython/issues/93896]: Fix asyncio.run() and unittest.IsolatedAsyncioTestCase to always the set event loop as it was done in Python 3.10 and earlier. Patch by Kumar Aditya.

gh-94343 [https://github.com/python/cpython/issues/94343]: Allow setting the attributes of reprlib.Repr during object initialization

gh-94382 [https://github.com/python/cpython/issues/94382]: Port static types of _multiprocessing module to heap types. Patch by Kumar Aditya.

gh-78724 [https://github.com/python/cpython/issues/78724]: Fix crash in struct.Struct when it was not completely initialized by initializing it in __new__(). Patch by Kumar Aditya.

gh-94510 [https://github.com/python/cpython/issues/94510]: Re-entrant calls to sys.setprofile() and sys.settrace() now raise RuntimeError. Patch by Pablo Galindo.

gh-92336 [https://github.com/python/cpython/issues/92336]: Fix bug where linecache.getline() fails on bad files with UnicodeDecodeError or SyntaxError. It now returns an empty string as per the documentation.

gh-94398 [https://github.com/python/cpython/issues/94398]: Once a 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.

gh-94383 [https://github.com/python/cpython/issues/94383]: xml.etree: Remove the ElementTree.Element.copy() method of the pure Python implementation, deprecated in Python 3.10, use the copy.copy() function instead. The C implementation of xml.etree has no copy() method, only a __copy__() method. Patch by Victor Stinner.

gh-94379 [https://github.com/python/cpython/issues/94379]: zipimport: Remove find_loader() and find_module() methods, deprecated in Python 3.10: use the find_spec() method instead. See PEP 451 [https://peps.python.org/pep-0451/] for the rationale. Patch by Victor Stinner.

gh-94352 [https://github.com/python/cpython/issues/94352]: shlex.split(): Passing None for s argument now raises an exception, rather than reading sys.stdin. The feature was deprecated in Python 3.9. Patch by Victor Stinner.

gh-94318 [https://github.com/python/cpython/issues/94318]: Strip trailing spaces in pydoc text output.

gh-89988 [https://github.com/python/cpython/issues/89988]: Fix memory leak in pickle.Pickler when looking up dispatch_table. Patch by Kumar Aditya.

gh-90016 [https://github.com/python/cpython/issues/90016]: Deprecate sqlite3 default adapters and converters. Patch by Erlend E. Aasland.

gh-94254 [https://github.com/python/cpython/issues/94254]: Fixed types of struct module to be immutable. Patch by Kumar Aditya.

gh-93259 [https://github.com/python/cpython/issues/93259]: Now raise ValueError when None or an empty string are passed to Distribution.from_name (and other callers).

gh-74696 [https://github.com/python/cpython/issues/74696]: shutil.make_archive() now passes the root_dir argument to custom archivers which support it.

gh-94216 [https://github.com/python/cpython/issues/94216]: The 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).

gh-93096 [https://github.com/python/cpython/issues/93096]: Removed undocumented python -m codecs. Use python -m unittest test.test_codecs.EncodedFileTest instead.

gh-94207 [https://github.com/python/cpython/issues/94207]: Made _struct.Struct GC-tracked in order to fix a reference leak in the _struct module.

gh-93096 [https://github.com/python/cpython/issues/93096]: Removed undocumented -t argument of python -m base64. Use python -m unittest test.test_base64.LegacyBase64TestCase.test_encodebytes instead.

gh-94226 [https://github.com/python/cpython/issues/94226]: Remove the locale.format() function, deprecated in Python 3.7: use locale.format_string() instead. Patch by Victor Stinner.

gh-94199 [https://github.com/python/cpython/issues/94199]: Remove the ssl.match_hostname() function. The ssl.match_hostname() was deprecated in Python 3.7. OpenSSL performs hostname matching since Python 3.7, Python no longer uses the ssl.match_hostname() function. Patch by Victor Stinner.

gh-94214 [https://github.com/python/cpython/issues/94214]: Document the context object used in the venv.EnvBuilder class, and add the new environment's library path to it.

gh-94199 [https://github.com/python/cpython/issues/94199]: Remove the ssl.wrap_socket() function, deprecated in Python 3.7: instead, create a ssl.SSLContext object and call its ssl.SSLContext.wrap_socket method. Any package that still uses ssl.wrap_socket() is broken and insecure. The function neither sends a SNI TLS extension nor validates server hostname. Code is subject to CWE-295 [https://cwe.mitre.org/data/definitions/295.html] Improper Certificate Validation. Patch by Victor Stinner.

gh-94199 [https://github.com/python/cpython/issues/94199]: Remove the ssl.RAND_pseudo_bytes() function, deprecated in Python 3.6: use os.urandom() or ssl.RAND_bytes() instead. Patch by Victor Stinner.

gh-94199 [https://github.com/python/cpython/issues/94199]: hashlib: Remove the pure Python implementation of hashlib.pbkdf2_hmac(), deprecated in Python 3.10. Python 3.10 and newer requires OpenSSL 1.1.1 (PEP 644 [https://peps.python.org/pep-0644/]): this OpenSSL version provides a C implementation of pbkdf2_hmac() which is faster. Patch by Victor Stinner.

gh-94196 [https://github.com/python/cpython/issues/94196]: gzip: Remove the filename attribute of gzip.GzipFile, deprecated since Python 2.6, use the name attribute instead. In write mode, the filename attribute added '.gz' file extension if it was not present. Patch by Victor Stinner.

gh-94182 [https://github.com/python/cpython/issues/94182]: run the 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

gh-94169 [https://github.com/python/cpython/issues/94169]: Remove io.OpenWrapper and _pyio.OpenWrapper, deprecated in Python 3.10: just use open() instead. The open() (io.open()) function is a built-in function. Since Python 3.10, _pyio.open() is also a static method. Patch by Victor Stinner.

gh-91742 [https://github.com/python/cpython/issues/91742]: Fix pdb crash after jump caused by a null pointer dereference. Patch by Kumar Aditya.

gh-94101 [https://github.com/python/cpython/issues/94101]: Manual instantiation of ssl.SSLSession objects is no longer allowed as it lead to misconfigured instances that crashed the interpreter when attributes where accessed on them.

gh-84753 [https://github.com/python/cpython/issues/84753]: inspect.iscoroutinefunction(), inspect.isgeneratorfunction(), and inspect.isasyncgenfunction() now properly return True for duck-typed function-like objects like instances of unittest.mock.AsyncMock.

This makes inspect.iscoroutinefunction() consistent with the behavior of asyncio.iscoroutinefunction(). Patch by Mehdi ABAAKOUK.

gh-94028 [https://github.com/python/cpython/issues/94028]: Fix a regression in the 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.

gh-93973 [https://github.com/python/cpython/issues/93973]: Add keyword argument all_errors to asyncio.create_connection so that multiple connection errors can be raised as an ExceptionGroup.

gh-93963 [https://github.com/python/cpython/issues/93963]: Officially deprecate from importlib.abc classes moved to importlib.resources.abc.

gh-93858 [https://github.com/python/cpython/issues/93858]: Prevent error when activating venv in nested fish instances.

gh-93820 [https://github.com/python/cpython/issues/93820]: Pickle enum.Flag by name.

gh-93847 [https://github.com/python/cpython/issues/93847]: Fix repr of enum of generic aliases.

gh-91404 [https://github.com/python/cpython/issues/91404]: Revert the re memory leak when a match is terminated by a signal or memory allocation failure as the implemented fix caused a major performance regression.

gh-83499 [https://github.com/python/cpython/issues/83499]: Fix double closing of file description in tempfile.

gh-93820 [https://github.com/python/cpython/issues/93820]: Fixed a regression when copy.copy()-ing enum.Flag with multiple flag members.

gh-79512 [https://github.com/python/cpython/issues/79512]: Fixed names and __module__ value of weakref classes ReferenceType, ProxyType, CallableProxyType. It makes them pickleable.

gh-91389 [https://github.com/python/cpython/issues/91389]: Fix an issue where dis utilities could report missing or incorrect position information in the presence of CACHE entries.

gh-93626 [https://github.com/python/cpython/issues/93626]: Set __future__.annotations to have a None mandatoryRelease to indicate that it is currently 'TBD'.

gh-90473 [https://github.com/python/cpython/issues/90473]: Emscripten and WASI have no home directory and cannot provide PEP 370 [https://peps.python.org/pep-0370/] user site directory.

gh-90494 [https://github.com/python/cpython/issues/90494]: copy.copy() and copy.deepcopy() now always raise a TypeError if __reduce__() returns a tuple with length 6 instead of silently ignore the 6th item or produce incorrect result.

gh-90549 [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).

gh-93521 [https://github.com/python/cpython/issues/93521]: Fixed a case where dataclasses would try to add __weakref__ into the __slots__ for a dataclass that specified weakref_slot=True when it was already defined in one of its bases. This resulted in a TypeError upon the new class being created.

gh-79579 [https://github.com/python/cpython/issues/79579]: sqlite3 now correctly detects DML queries with leading comments. Patch by Erlend E. Aasland.

gh-93421 [https://github.com/python/cpython/issues/93421]: Update sqlite3.Cursor.rowcount when a DML statement has run to completion. This fixes the row count for SQL queries like UPDATE ... RETURNING. Patch by Erlend E. Aasland.

gh-93475 [https://github.com/python/cpython/issues/93475]: Expose FICLONE and FICLONERANGE constants in fcntl. Patch by Illia Volochii.

gh-93370 [https://github.com/python/cpython/issues/93370]: Deprecate sqlite3.version and sqlite3.version_info.

gh-91810 [https://github.com/python/cpython/issues/91810]: Suppress writing an XML declaration in open files in ElementTree.write() with encoding='unicode' and xml_declaration=None.

gh-91162 [https://github.com/python/cpython/issues/91162]: Support splitting of unpacked arbitrary-length tuple over TypeVar and TypeVarTuple parameters. For example:

A[T, *Ts][*tuple[int, ...]] -> A[int, *tuple[int, ...]]

A[*Ts, T][*tuple[int, ...]] -> A[*tuple[int, ...], int]

gh-93353 [https://github.com/python/cpython/issues/93353]: Fix the importlib.resources.as_file() context manager to remove the temporary file if destroyed late during Python finalization: keep a local reference to the os.remove() function. Patch by Victor Stinner.

gh-83658 [https://github.com/python/cpython/issues/83658]: Make multiprocessing.Pool raise an exception if maxtasksperchild is not None or a positive int.

gh-93312 [https://github.com/python/cpython/issues/93312]: Add os.PIDFD_NONBLOCK flag to open a file descriptor for a process with os.pidfd_open() in non-blocking mode. Patch by Kumar Aditya.

gh-88123 [https://github.com/python/cpython/issues/88123]: Implement Enum.__contains__ that returns True or False to replace the deprecated behaviour that would sometimes raise a TypeError.

gh-93297 [https://github.com/python/cpython/issues/93297]: Make asyncio task groups prevent child tasks from being GCed

gh-85308 [https://github.com/python/cpython/issues/85308]: Changed argparse.ArgumentParser to use filesystem encoding and error handler instead of default text encoding to read arguments from file (e.g. fromfile_prefix_chars option). This change affects Windows; argument file should be encoded with UTF-8 instead of ANSI Codepage.

gh-93156 [https://github.com/python/cpython/issues/93156]: Accessing the pathlib.PurePath.parents sequence of an absolute path using negative index values produced incorrect results.

gh-93162 [https://github.com/python/cpython/issues/93162]: Add the ability for logging.config.dictConfig() to usefully configure QueueHandler and QueueListener as a pair, and add logging.getHandlerByName() and logging.getHandlerNames() APIs to allow access to handlers by name.

gh-93243 [https://github.com/python/cpython/issues/93243]: The smtpd module was removed per the schedule in PEP 594 [https://peps.python.org/pep-0594/].

gh-92886 [https://github.com/python/cpython/issues/92886]: Replace assert statements with raise AssertionError() in BaseHandler so that the tested behaviour is maintained running with optimizations (-O).

gh-90155 [https://github.com/python/cpython/issues/90155]: Fix broken asyncio.Semaphore when acquire is cancelled.

gh-90817 [https://github.com/python/cpython/issues/90817]: The locale.resetlocale() function is deprecated and will be removed in Python 3.13. Use locale.setlocale(locale.LC_ALL, "") instead. Patch by Victor Stinner.

gh-91513 [https://github.com/python/cpython/issues/91513]: Added taskName attribute to logging module for use with asyncio tasks.

gh-74696 [https://github.com/python/cpython/issues/74696]: shutil.make_archive() no longer temporarily changes the current working directory during creation of standard .zip or tar archives.

gh-92728 [https://github.com/python/cpython/issues/92728]: The re.template() function and the corresponding re.TEMPLATE and 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.

gh-93033 [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.

gh-89973 [https://github.com/python/cpython/issues/89973]: Fix re.error raised in fnmatch if the pattern contains a character range with upper bound lower than lower bound (e.g. [c-a]). Now such ranges are interpreted as empty ranges.

gh-93044 [https://github.com/python/cpython/issues/93044]: No longer convert the database argument of sqlite3.connect() to bytes before passing it to the factory.

gh-93010 [https://github.com/python/cpython/issues/93010]: In a very special case, the email package tried to append the nonexistent InvalidHeaderError to the defect list. It should have been InvalidHeaderDefect.

gh-92986 [https://github.com/python/cpython/issues/92986]: Fix ast.unparse() when ImportFrom.level is None

gh-92932 [https://github.com/python/cpython/issues/92932]: Now dis() and get_instructions() handle operand values for instructions prefixed by EXTENDED_ARG_QUICK. Patch by Sam Gross and Donghee Na.

gh-92675 [https://github.com/python/cpython/issues/92675]: Fix venv.ensure_directories() to accept pathlib.Path arguments in addition to str paths. Patch by David Foster.

gh-87901 [https://github.com/python/cpython/issues/87901]: Removed the encoding argument from os.popen() that was added in 3.11b1.

gh-91922 [https://github.com/python/cpython/issues/91922]: Fix function sqlite.connect() and the sqlite.Connection constructor on non-UTF-8 locales. Also, they now support bytes paths non-decodable with the current FS encoding.

gh-92869 [https://github.com/python/cpython/issues/92869]: Added c_time_t to ctypes, which has the same size as the time_t type in C.

gh-92839 [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 None.

gh-90473 [https://github.com/python/cpython/issues/90473]: subprocess now fails early on Emscripten and WASI platforms to work around missing os.pipe() on WASI.

gh-89325 [https://github.com/python/cpython/issues/89325]: Removed many old deprecated unittest features: TestCase method aliases, undocumented and broken TestCase method assertDictContainsSubset, undocumented TestLoader.loadTestsFromModule parameter use_load_tests, and an underscored alias of the TextTestResult class.

gh-92734 [https://github.com/python/cpython/issues/92734]: Allow multi-element reprs emitted by reprlib to be pretty-printed using configurable indentation.

gh-92671 [https://github.com/python/cpython/issues/92671]: Fixed ast.unparse() for empty tuples in the assignment target context.

gh-91581 [https://github.com/python/cpython/issues/91581]: utcfromtimestamp() no longer attempts to resolve 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 datetime.min. Patch by Paul Ganssle.

gh-86388 [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.

gh-90385 [https://github.com/python/cpython/issues/90385]: Add pathlib.Path.walk() as an alternative to os.walk().

gh-92550 [https://github.com/python/cpython/issues/92550]: Fix pathlib.Path.rglob() for empty pattern.

gh-92591 [https://github.com/python/cpython/issues/92591]: Allow logging filters to return a logging.LogRecord instance so that filters attached to logging.Handlers can enrich records without side effects on other handlers.

gh-92445 [https://github.com/python/cpython/issues/92445]: Fix a bug in argparse where nargs="*" would raise an error instead of returning an empty list when 0 arguments were supplied if choice was also defined in parser.add_argument.

gh-92547 [https://github.com/python/cpython/issues/92547]: Remove undocumented sqlite3 features deprecated in Python 3.10:

sqlite3.enable_shared_cache()

sqlite3.OptimizedUnicode

Patch by Erlend E. Aasland.

gh-92530 [https://github.com/python/cpython/issues/92530]: Fix an issue that occurred after interrupting threading.Condition.notify().

gh-92531 [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.

gh-84131 [https://github.com/python/cpython/issues/84131]: The pathlib.Path deprecated method link_to has been removed. Use 3.10's hardlink_to() method instead as its semantics are consistent with that of symlink_to().

gh-89336 [https://github.com/python/cpython/issues/89336]: Removed configparser module APIs: the SafeConfigParser class alias, the ParsingError.filename property and parameter, and the ConfigParser.readfp method, all of which were deprecated since Python 3.2.

gh-92391 [https://github.com/python/cpython/issues/92391]: Add __class_getitem__() to csv.DictReader and csv.DictWriter, allowing them to be parameterized at runtime. Patch by Marc Mueller.

gh-91968 [https://github.com/python/cpython/issues/91968]: Add SO_RTABLE and SO_USER_COOKIE constants to socket.

gh-91810 [https://github.com/python/cpython/issues/91810]: ElementTree method write() and function tostring() now use the text file's encoding ("UTF-8" if not available) instead of locale encoding in XML declaration when encoding="unicode" is specified.

gh-81790 [https://github.com/python/cpython/issues/81790]: os.path.splitdrive() now understands DOS device paths with UNC links (beginning \\?\UNC\). Contributed by Barney Gale.

gh-91760 [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.

gh-90622 [https://github.com/python/cpython/issues/90622]: Worker processes for concurrent.futures.ProcessPoolExecutor are no longer spawned on demand (a feature added in 3.9) when the multiprocessing context start method is "fork" as that can lead to deadlocks in the child processes due to a fork happening while threads are running.

gh-91577 [https://github.com/python/cpython/issues/91577]: Move imports in SharedMemory methods to module level so that they can be executed late in python finalization.

gh-91581 [https://github.com/python/cpython/issues/91581]: Remove an unhandled error case in the C implementation of calls to 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.

gh-91539 [https://github.com/python/cpython/issues/91539]: Improve performance of urllib.request.getproxies_environment when there are many environment variables

gh-91524 [https://github.com/python/cpython/issues/91524]: Speed up the regular expression substitution (functions re.sub() and re.subn() and corresponding re.Pattern methods) for replacement strings containing group references by 2--3 times.

gh-91447 [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 None.

gh-91456 [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.

bpo-47231 [https://bugs.python.org/issue?@action=redirect&bpo=47231]: Fixed an issue with inconsistent trailing slashes in tarfile longname directories.

bpo-39064 [https://bugs.python.org/issue?@action=redirect&bpo=39064]: zipfile.ZipFile now raises zipfile.BadZipFile instead of ValueError when reading a corrupt zip file in which the central directory offset is negative.

bpo-41287 [https://bugs.python.org/issue?@action=redirect&bpo=41287]: Fix handling of the doc argument in subclasses of property().

gh-90005 [https://github.com/python/cpython/issues/90005]: ctypes dependency libffi is now detected with pkg-config.

bpo-32547 [https://bugs.python.org/issue?@action=redirect&bpo=32547]: The constructors for DictWriter and DictReader now coerce the fieldnames argument to a list if it is an iterator.

bpo-35540 [https://bugs.python.org/issue?@action=redirect&bpo=35540]: Fix dataclasses.asdict() crash when collections.defaultdict is present in the attributes.

bpo-47063 [https://bugs.python.org/issue?@action=redirect&bpo=47063]: Add an index_pages parameter to support using non-default index page names.

bpo-47025 [https://bugs.python.org/issue?@action=redirect&bpo=47025]: Drop support for bytes on sys.path.

bpo-46951 [https://bugs.python.org/issue?@action=redirect&bpo=46951]: Order the contents of zipapp archives, to make builds more reproducible.

bpo-42777 [https://bugs.python.org/issue?@action=redirect&bpo=42777]: Implement pathlib.Path.is_mount() for Windows paths.

bpo-46755 [https://bugs.python.org/issue?@action=redirect&bpo=46755]: In QueueHandler, clear stack_info from LogRecord to prevent stack trace from being written twice.

bpo-45393 [https://bugs.python.org/issue?@action=redirect&bpo=45393]: Fix the formatting for await x and not x in the operator precedence table when using the help() system.

bpo-46642 [https://bugs.python.org/issue?@action=redirect&bpo=46642]: Improve error message when trying to subclass an instance of typing.TypeVar, typing.ParamSpec, typing.TypeVarTuple, etc. Based on patch by Gregory Beauregard.

bpo-46364 [https://bugs.python.org/issue?@action=redirect&bpo=46364]: Restrict use of sockets instead of pipes for stdin of subprocesses created by asyncio to AIX platform only.

bpo-28249 [https://bugs.python.org/issue?@action=redirect&bpo=28249]: Set doctest.DocTest.lineno to None when object does not have __doc__.

bpo-46197 [https://bugs.python.org/issue?@action=redirect&bpo=46197]: Fix ensurepip environment isolation for subprocess running pip.

bpo-45924 [https://bugs.python.org/issue?@action=redirect&bpo=45924]: Fix asyncio incorrect traceback when future's exception is raised multiple times. Patch by Kumar Aditya.

bpo-45046 [https://bugs.python.org/issue?@action=redirect&bpo=45046]: Add support of context managers in unittest: methods enterContext() and enterClassContext() of class TestCase, method enterAsyncContext() of class IsolatedAsyncioTestCase and function unittest.enterModuleContext().

bpo-44173 [https://bugs.python.org/issue?@action=redirect&bpo=44173]: Enable fast seeking of uncompressed unencrypted zipfile.ZipExtFile

bpo-42627 [https://bugs.python.org/issue?@action=redirect&bpo=42627]: Fix incorrect parsing of Windows registry proxy settings

bpo-42047 [https://bugs.python.org/issue?@action=redirect&bpo=42047]: Add threading.get_native_id() support for DragonFly BSD. Patch by David Carlier.

bpo-14243 [https://bugs.python.org/issue?@action=redirect&bpo=14243]: The tempfile.NamedTemporaryFile function has a new optional parameter delete_on_close

bpo-41246 [https://bugs.python.org/issue?@action=redirect&bpo=41246]: Give the same callback function for when the overlapped operation is done to the functions recv, recv_into, recvfrom, sendto, send and sendfile inside IocpProactor.

bpo-39264 [https://bugs.python.org/issue?@action=redirect&bpo=39264]: Fixed collections.UserDict.get() to not call __missing__() when a value is not found. This matches the behavior of dict. Patch by Bar Harel.

bpo-38693 [https://bugs.python.org/issue?@action=redirect&bpo=38693]: importlib now uses f-strings internally instead of str.format.

bpo-38267 [https://bugs.python.org/issue?@action=redirect&bpo=38267]: Add timeout parameter to asyncio.loop.shutdown_default_executor(). The default value is None, which means the executor will be given an unlimited amount of time. When called from asyncio.Runner or asyncio.run(), the default timeout is 5 minutes.

bpo-34828 [https://bugs.python.org/issue?@action=redirect&bpo=34828]: sqlite3.Connection.iterdump() now handles databases that use AUTOINCREMENT in one or more tables.

bpo-32990 [https://bugs.python.org/issue?@action=redirect&bpo=32990]: Support reading wave files with the WAVE_FORMAT_EXTENSIBLE format in the wave module.

bpo-26253 [https://bugs.python.org/issue?@action=redirect&bpo=26253]: Allow adjustable compression level for tarfile streams in tarfile.open().

Documentation

gh-85525 [https://github.com/python/cpython/issues/85525]: Remove extra row

gh-86404 [https://github.com/python/cpython/issues/86404]: Deprecated tools make suspicious and rstlint.py are now removed. They have been replaced by sphinx-lint [https://pypi.org/project/sphinx-lint/].

gh-97741 [https://github.com/python/cpython/issues/97741]: Fix ! in c domain ref target syntax via a conf.py patch, so it works as intended to disable ref target resolution.

gh-96432 [https://github.com/python/cpython/issues/96432]: Fraction literals now support whitespace around the forward slash, Fraction('2 / 3').

gh-96098 [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.

gh-95957 [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.

gh-95588 [https://github.com/python/cpython/issues/95588]: Clarified the conflicting advice given in the ast documentation about 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 literal_eval is safe.

gh-91207 [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.

gh-95454 [https://github.com/python/cpython/issues/95454]: Replaced incorrectly written true/false values in documentiation. Patch by Robert O'Shea

gh-95451 [https://github.com/python/cpython/issues/95451]: Update library documentation with availability information on WebAssembly platforms wasm32-emscripten and wasm32-wasi.

gh-95415 [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.

gh-94321 [https://github.com/python/cpython/issues/94321]: Document the PEP 246 [https://peps.python.org/pep-0246/] style protocol type sqlite3.PrepareProtocol.

gh-86128 [https://github.com/python/cpython/issues/86128]: Document a limitation in ThreadPoolExecutor where its exit handler is executed before any handlers in atexit.

gh-61162 [https://github.com/python/cpython/issues/61162]: Clarify sqlite3 behavior when 接続(connection)コンテキストマネージャの使い方.

gh-87260 [https://github.com/python/cpython/issues/87260]: Align sqlite3 argument specs with the actual implementation.

gh-86986 [https://github.com/python/cpython/issues/86986]: The minimum Sphinx version required to build the documentation is now 3.2.

gh-88831 [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.

gh-86438 [https://github.com/python/cpython/issues/86438]: Clarify that -W and PYTHONWARNINGS are matched literally and case-insensitively, rather than as regular expressions, in warnings.

gh-93031 [https://github.com/python/cpython/issues/93031]: Update tutorial introduction output to use 3.10+ SyntaxError invalid range.

gh-92240 [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

bpo-47161 [https://bugs.python.org/issue?@action=redirect&bpo=47161]: Document that pathlib.PurePath does not collapse initial double slashes because they denote UNC paths.

bpo-40838 [https://bugs.python.org/issue?@action=redirect&bpo=40838]: Document that inspect.getdoc(), inspect.getmodule(), and inspect.getsourcefile() might return None.

bpo-43689 [https://bugs.python.org/issue?@action=redirect&bpo=43689]: The Differ documentation now also mentions other whitespace characters, which make it harder to understand the diff output.

bpo-38056 [https://bugs.python.org/issue?@action=redirect&bpo=38056]: Overhaul the エラーハンドラ documentation in codecs.

bpo-13553 [https://bugs.python.org/issue?@action=redirect&bpo=13553]: Document tkinter.Tk args.

Tests

gh-95027 [https://github.com/python/cpython/issues/95027]: On Windows, when the Python test suite is run with the -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.

gh-96624 [https://github.com/python/cpython/issues/96624]: Fixed the failure of repeated runs of test.test_unittest caused by side effects in test_dotted_but_module_not_loaded.

gh-95243 [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.

gh-95573 [https://github.com/python/cpython/issues/95573]: Lib/test/test_asyncio/test_ssl.py [https://github.com/python/cpython/tree/3.12/Lib/test/test_asyncio/test_ssl.py] exposed a bug in the macOS kernel where intense concurrent load on non-blocking sockets occasionally causes 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.

gh-95280 [https://github.com/python/cpython/issues/95280]: Fix problem with test_ssl test_get_ciphers on systems that require perfect forward secrecy (PFS) ciphers.

gh-95212 [https://github.com/python/cpython/issues/95212]: Make multiprocessing test case test_shared_memory_recreate parallel-safe.

gh-95218 [https://github.com/python/cpython/issues/95218]: Move tests for importlib.resources into test_importlib.resources.

gh-93963 [https://github.com/python/cpython/issues/93963]: Updated tests to use preferred location for importlib.resources ABCs.

gh-94675 [https://github.com/python/cpython/issues/94675]: Add a regression test for re exponentional slowdown when using rjsmin.

gh-91330 [https://github.com/python/cpython/issues/91330]: Added more tests for dataclasses to cover behavior with data descriptor-based fields.

gh-94208 [https://github.com/python/cpython/issues/94208]: test_ssl is now checking for supported TLS version and protocols in more tests.

gh-94315 [https://github.com/python/cpython/issues/94315]: Tests now check for DAC override capability instead of relying on os.geteuid().

gh-54781 [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.

gh-93839 [https://github.com/python/cpython/issues/93839]: Move Lib/ctypes/test/ to Lib/test/test_ctypes/. Patch by Victor Stinner.

gh-93951 [https://github.com/python/cpython/issues/93951]: In test_bdb.StateTestCase.test_skip, avoid including auxiliary importers.

gh-93957 [https://github.com/python/cpython/issues/93957]: Provide nicer error reporting from subprocesses in test_venv.EnsurePipTest.test_with_pip.

gh-93884 [https://github.com/python/cpython/issues/93884]: Add test cases for PyNumber_ToBase() that take a large number or a non-int object as parameter.

gh-93852 [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 OSError("AF_UNIX path too long") if the temporary directory (the TMPDIR environment variable) is too long. Patch by Victor Stinner.

gh-93353 [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.

gh-84461 [https://github.com/python/cpython/issues/84461]: run_tests.py now handles cross compiling env vars correctly and pass HOSTRUNNER to regression tests.

gh-93616 [https://github.com/python/cpython/issues/93616]: test_modulefinder now creates a temporary directory in ModuleFinderTest.setUp() instead of module scope.

gh-93575 [https://github.com/python/cpython/issues/93575]: Fix issue with test_unicode test_raiseMemError. The test case now use test.support.calcobjsize to calculate size of PyUnicode structs. sys.getsizeof() may return different size when string has UTF-8 memory.

gh-90473 [https://github.com/python/cpython/issues/90473]: WASI does not have a chmod(2) syscall. os.chmod() is now a dummy function on WASI. Skip all tests that depend on working os.chmod().

gh-90473 [https://github.com/python/cpython/issues/90473]: Skip tests on WASI that require symlinks with absolute paths.

gh-57539 [https://github.com/python/cpython/issues/57539]: Increase calendar test coverage for calendar.LocaleTextCalendar.formatweekday().

gh-90473 [https://github.com/python/cpython/issues/90473]: Skip symlink tests on WASI. wasmtime uses openat2(2) with RESOLVE_BENEATH flag, which prevents symlinks with absolute paths.

gh-89858 [https://github.com/python/cpython/issues/89858]: Fix test_embed for out-of-tree builds. Patch by Kumar Aditya.

gh-92886 [https://github.com/python/cpython/issues/92886]: Fixing tests that fail when running with optimizations (-O) in test_imaplib.py.

gh-92886 [https://github.com/python/cpython/issues/92886]: Fixing tests that fail when running with optimizations (-O) in test_zipimport.py

gh-92886 [https://github.com/python/cpython/issues/92886]: Fixing tests that fail when running with optimizations (-O) in test_py_compile.py

gh-92886 [https://github.com/python/cpython/issues/92886]: Fixing tests that fail when running with optimizations (-O) in test_sys_settrace.py.

gh-92886 [https://github.com/python/cpython/issues/92886]: Fixing tests that fail when running with optimizations (-O) in _test_multiprocessing.py

gh-92670 [https://github.com/python/cpython/issues/92670]: Skip 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.

gh-92514 [https://github.com/python/cpython/issues/92514]: Remove unused test.support.BasicTestRunner. Patch by Jelle Zijlstra.

bpo-47016 [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.

Build

gh-96761 [https://github.com/python/cpython/issues/96761]: Fix the build process of clang compiler for _bootstrap_python if LTO optimization is applied. Patch by Matthias Görgens and Donghee Na.

gh-96883 [https://github.com/python/cpython/issues/96883]: wasm32-emscripten builds for browsers now include concurrent.futures for asyncio and unittest.mock.

gh-85936 [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.

gh-96729 [https://github.com/python/cpython/issues/96729]: Ensure that Windows releases built with Tools\msi\buildrelease.bat are upgradable to and from official Python releases.

gh-96269 [https://github.com/python/cpython/issues/96269]: Shared module targets now depend on new MODULE_DEPS variable, which includes EXPORTSYMS. This fixes a build order issue on unsupported AIX platform.

gh-84461 [https://github.com/python/cpython/issues/84461]: wasm32-emscripten platform no longer builds resource module, getresuid(), getresgid(), and their setters. The APIs are stubs and not functional.

gh-95973 [https://github.com/python/cpython/issues/95973]: Add a new --with-dsymutil configure option to link debug information in macOS. Patch by Pablo Galindo.

gh-90536 [https://github.com/python/cpython/issues/90536]: Use the BOLT post-link optimizer to improve performance, particularly on medium-to-large applications.

gh-93744 [https://github.com/python/cpython/issues/93744]: Remove the configure --with-cxx-main build option: it didn't work for many years. Remove the MAINCC variable from configure and Makefile. Patch by Victor Stinner.

gh-94801 [https://github.com/python/cpython/issues/94801]: Fix a regression in configure script that caused some header checks to ignore custom CPPFLAGS. The regression was introduced in gh-94802 [https://github.com/python/cpython/issues/94802].

gh-95145 [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.

gh-95174 [https://github.com/python/cpython/issues/95174]: Python now detects missing dup function in WASI and works around some missing errno, select, and socket constants.

gh-95174 [https://github.com/python/cpython/issues/95174]: Python now skips missing socket functions and methods on WASI. WASI can only create sockets from existing fd / accept and has no netdb.

gh-95085 [https://github.com/python/cpython/issues/95085]: Platforms wasm32-unknown-emscripten and wasm32-unknown-wasi have been promoted to PEP 11 [https://peps.python.org/pep-0011/] tier 3 platform support.

gh-94847 [https://github.com/python/cpython/issues/94847]: Fixed _decimal module build issue on GCC when compiling with LTO and pydebug. Debug builds no longer force inlining of functions.

gh-94841 [https://github.com/python/cpython/issues/94841]: Fix the possible performance regression of PyObject_Free() compiled with MSVC version 1932.

gh-94801 [https://github.com/python/cpython/issues/94801]: configure now uses custom flags like ZLIB_CFLAGS and ZLIB_LIBS when searching for headers and libraries.

gh-94773 [https://github.com/python/cpython/issues/94773]: deepfreeze.py now supports code object with frozensets that contain incompatible, unsortable types.

gh-94682 [https://github.com/python/cpython/issues/94682]: Build and test with OpenSSL 1.1.1q

gh-90005 [https://github.com/python/cpython/issues/90005]: Dependencies of readline and curses module are now detected in configure script with pkg-config. Only ncurses / ncursesw are detected automatically. The old curses library is not configured automatically. Workaround for missing termcap or tinfo library has been removed.

gh-90005 [https://github.com/python/cpython/issues/90005]: Fix building _ctypes extension without pkg-config.

gh-90005 [https://github.com/python/cpython/issues/90005]: _dbm module dependencies are now detected by configure.

gh-94404 [https://github.com/python/cpython/issues/94404]: 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.

gh-93939 [https://github.com/python/cpython/issues/93939]: C extension modules are now built by configure and make instead of distutils and setup.py.

gh-93939 [https://github.com/python/cpython/issues/93939]: The 2to3, idle, and pydoc scripts are now generated and installed by Makefile instead of setup.py.

gh-94280 [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.

gh-93584 [https://github.com/python/cpython/issues/93584]: Address race condition in Makefile when installing a PGO build. All test and install targets now depend on all target.

gh-93491 [https://github.com/python/cpython/issues/93491]: configure now detects and reports PEP 11 [https://peps.python.org/pep-0011/] support tiers.

gh-69093 [https://github.com/python/cpython/issues/69093]: Fix Modules/Setup.stdlib.in rule for _sqlite3 extension.

gh-93207 [https://github.com/python/cpython/issues/93207]: va_start() with two parameters, like va_start(args, format), is now required to build Python. va_start() is no longer called with a single parameter. Patch by Kumar Aditya.

gh-93202 [https://github.com/python/cpython/issues/93202]: Python now always use the %zu and %zd printf formats to format a size_t or Py_ssize_t number. Building Python 3.12 requires a C11 compiler, so these printf formats are now always supported. Patch by Victor Stinner.

gh-90473 [https://github.com/python/cpython/issues/90473]: Disable pymalloc and increase stack size on wasm32-wasi.

bpo-34449 [https://bugs.python.org/issue?@action=redirect&bpo=34449]: Drop invalid compiler switch -fPIC for HP aCC on HP-UX. Patch by Michael Osipov.

Windows

gh-98360 [https://github.com/python/cpython/issues/98360]: Fixes multiprocessing spawning child processes on Windows from a virtual environment to ensure that child processes that also use multiprocessing to spawn more children will recognize that they are in a virtual environment.

gh-98414 [https://github.com/python/cpython/issues/98414]: Fix py.exe launcher handling of -V:<company>/ option when default preferences have been set in environment variables or configuration files.

gh-97728 [https://github.com/python/cpython/issues/97728]: Fix possible crashes caused by the use of uninitialized variables when pass invalid arguments in os.system() on Windows and in Windows-specific modules (like winreg).

gh-90989 [https://github.com/python/cpython/issues/90989]: Made Windows の Python ランチャ install per-user by default (unless an all users install already exists), and clarify some text in the installer.

gh-97649 [https://github.com/python/cpython/issues/97649]: The Tools directory is no longer installed on Windows

gh-96965 [https://github.com/python/cpython/issues/96965]: Update libffi to 3.4.3

gh-96577 [https://github.com/python/cpython/issues/96577]: Fixes a potential buffer overrun in msilib.

gh-96559 [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.

gh-94781 [https://github.com/python/cpython/issues/94781]: Fix pcbuild.proj to clean previous instances of output files in Python\deepfreeze and Python\frozen_modules directories on Windows. Patch by Charlie Zhao.

gh-89545 [https://github.com/python/cpython/issues/89545]: Updates platform code getting the Windows version to use native Windows Management Instrumentation (WMI) queries to determine OS version, type, and architecture.

gh-95733 [https://github.com/python/cpython/issues/95733]: Make certain requirements of the Windows Store package optional to allow installing on earlier updates of Windows.

gh-95656 [https://github.com/python/cpython/issues/95656]: Enable the enable_load_extension() sqlite3 API.

gh-95587 [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.

gh-94399 [https://github.com/python/cpython/issues/94399]: Restores the behaviour of Windows の Python ランチャ for /usr/bin/env shebang lines, which will now search PATH for an executable matching the given command. If none is found, the usual search process is used.

gh-95445 [https://github.com/python/cpython/issues/95445]: Fixes the unsuccessful removal of the HTML document directory when uninstalling with Windows msi.

gh-95359 [https://github.com/python/cpython/issues/95359]: Fix Windows の Python ランチャ handling of py.ini commands (it was incorrectly expecting a py_ prefix on keys) and crashes when reading per-user configuration file.

gh-95285 [https://github.com/python/cpython/issues/95285]: Fix Windows の Python ランチャ handling of command lines where it is only passed a short executable name.

gh-90844 [https://github.com/python/cpython/issues/90844]: Allow virtual environments to correctly launch when they have spaces in the path.

gh-94772 [https://github.com/python/cpython/issues/94772]: Fix incorrect handling of shebang lines in py.exe launcher

gh-94018 [https://github.com/python/cpython/issues/94018]: zipfile will now remove trailing spaces from path components when extracting files on Windows.

gh-93824 [https://github.com/python/cpython/issues/93824]: Drag and drop of files onto Python files in Windows Explorer has been enabled for Windows ARM64.

gh-43414 [https://github.com/python/cpython/issues/43414]: os.get_terminal_size() now attempts to read the size from any provided handle, rather than only supporting file descriptors 0, 1 and 2.

gh-92817 [https://github.com/python/cpython/issues/92817]: Ensures that py.exe will prefer an active virtual environment over default tags specified with environment variables or through a py.ini file.

gh-92984 [https://github.com/python/cpython/issues/92984]: Explicitly disable incremental linking for non-Debug builds

gh-92841 [https://github.com/python/cpython/issues/92841]: asyncio no longer throws RuntimeError: Event loop is closed on interpreter exit after asynchronous socket activity. Patch by Oleg Iarygin.

bpo-46907 [https://bugs.python.org/issue?@action=redirect&bpo=46907]: Update Windows installer to use SQLite 3.38.4.

gh-91061 [https://github.com/python/cpython/issues/91061]: Accept os.PathLike for the argument to winsound.PlaySound

bpo-42658 [https://bugs.python.org/issue?@action=redirect&bpo=42658]: Support native Windows case-insensitive path comparisons by using LCMapStringEx instead of str.lower() in ntpath.normcase(). Add LCMapStringEx to the _winapi module.

bpo-38704 [https://bugs.python.org/issue?@action=redirect&bpo=38704]: Prevent installation on unsupported Windows versions.

macOS

gh-97897 [https://github.com/python/cpython/issues/97897]: The macOS 13 SDK includes support for the mkfifoat and mknodat system calls. Using the dir_fd option with either os.mkfifo() or 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.

IDLE

gh-97527 [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.

gh-65802 [https://github.com/python/cpython/issues/65802]: Document handling of extensions in Save As dialogs.

gh-95191 [https://github.com/python/cpython/issues/95191]: Include prompts when saving Shell (interactive input and output).

gh-95511 [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.

gh-95471 [https://github.com/python/cpython/issues/95471]: In the Edit menu, move Select All and add a new separator.

gh-95411 [https://github.com/python/cpython/issues/95411]: Enable using IDLE's module browser with .pyw files.

gh-89610 [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.

Tools/Demos

gh-68686 [https://github.com/python/cpython/issues/68686]: Remove ptags and eptags scripts.

gh-97681 [https://github.com/python/cpython/issues/97681]: Remove the Tools/demo/ directory which contained old demo scripts. A copy can be found in the old-demos project [https://github.com/gvanrossum/old-demos]. Patch by Victor Stinner.

gh-97669 [https://github.com/python/cpython/issues/97669]: Remove outdated example scripts of the Tools/scripts/ directory. A copy can be found in the old-demos project [https://github.com/gvanrossum/old-demos]. Patch by Victor Stinner.

gh-95853 [https://github.com/python/cpython/issues/95853]: The wasm_build.py script now pre-builds Emscripten ports, checks for broken EMSDK versions, and warns about pkg-config env vars.

gh-95853 [https://github.com/python/cpython/issues/95853]: The new tool Tools/wasm/wasm_builder.py automates configure, compile, and test steps for building CPython on WebAssembly platforms.

gh-95731 [https://github.com/python/cpython/issues/95731]: Fix handling of module docstrings in Tools/i18n/pygettext.py.

gh-93939 [https://github.com/python/cpython/issues/93939]: Add script Tools/scripts/check_modules.py to check and validate builtin and shared extension modules. The script also handles Modules/Setup and will eventually replace setup.py.

gh-94538 [https://github.com/python/cpython/issues/94538]: Fix Argument Clinic output to custom file destinations. Patch by Erlend E. Aasland.

gh-94430 [https://github.com/python/cpython/issues/94430]: Allow parameters named module and self with custom C names in Argument Clinic. Patch by Erlend E. Aasland

gh-86087 [https://github.com/python/cpython/issues/86087]: The Tools/scripts/parseentities.py script used to parse HTML4 entities has been removed.

C API

gh-98393 [https://github.com/python/cpython/issues/98393]: The PyUnicode_FSDecoder() function no longer accepts bytes-like paths, like bytearray and memoryview types: only the exact bytes type is accepted for bytes strings. Patch by Victor Stinner.

gh-91051 [https://github.com/python/cpython/issues/91051]: Add PyType_Watch() and related APIs to allow callbacks on PyType_Modified().

gh-95756 [https://github.com/python/cpython/issues/95756]: Lazily create and cache co_ attributes for better performance for code getters.

gh-96512 [https://github.com/python/cpython/issues/96512]: Configuration for the integer string conversion length limitation now lives in the PyConfig C API struct.

gh-95589 [https://github.com/python/cpython/issues/95589]: Extensions classes that set tp_dictoffset and tp_weaklistoffset lose the support for multiple inheritance, but are now safe. Extension classes should use Py_TPFLAGS_MANAGED_DICT and Py_TPFLAGS_MANAGED_WEAKREF instead.

gh-95781 [https://github.com/python/cpython/issues/95781]: An unrecognized format character in PyUnicode_FromFormat() and PyUnicode_FromFormatV() now sets a 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.

gh-92678 [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.

gh-92678 [https://github.com/python/cpython/issues/92678]: Support C extensions using managed dictionaries by setting the Py_TPFLAGS_MANAGED_DICT flag.

gh-93274 [https://github.com/python/cpython/issues/93274]: API for implementing vectorcall (Py_TPFLAGS_HAVE_VECTORCALL, PyVectorcall_NARGS() and PyVectorcall_Call()) was added to the limited API and stable ABI.

gh-95504 [https://github.com/python/cpython/issues/95504]: Fix sign placement when specifying width or precision in PyUnicode_FromFormat() and PyUnicode_FromFormatV(). Patch by Philip Georgi.

gh-93012 [https://github.com/python/cpython/issues/93012]: The Py_TPFLAGS_HAVE_VECTORCALL flag is now removed from a class when the class's __call__() method is reassigned. This makes vectorcall safe to use with mutable types (i.e. heap types without the immutable flag). Mutable types that do not override tp_call now inherit the Py_TPFLAGS_HAVE_VECTORCALL flag.

gh-95388 [https://github.com/python/cpython/issues/95388]: Creating immutable types with mutable bases is deprecated and is planned to be disabled in Python 3.14.

gh-92678 [https://github.com/python/cpython/issues/92678]: Adds unstable C-API functions _PyObject_VisitManagedDict and _PyObject_ClearManagedDict to allow C extensions to allow the VM to manage their object's dictionaries.

gh-94936 [https://github.com/python/cpython/issues/94936]: Added PyCode_GetVarnames(), PyCode_GetCellvars() and PyCode_GetFreevars() for accessing co_varnames, co_cellvars and co_freevars respectively via the C API.

gh-94930 [https://github.com/python/cpython/issues/94930]: Fix SystemError raised when PyArg_ParseTupleAndKeywords() is used with # in (...) but without PY_SSIZE_T_CLEAN defined.

gh-94731 [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. -Wold-style-cast or -Wzero-as-null-pointer-constant options for g++.

gh-93937 [https://github.com/python/cpython/issues/93937]: The following frame functions and type are now directly available with #include <Python.h>, it's no longer needed to add #include <frameobject.h>:

PyFrame_Check()

PyFrame_GetBack()

PyFrame_GetBuiltins()

PyFrame_GetGenerator()

PyFrame_GetGlobals()

PyFrame_GetLasti()

PyFrame_GetLocals()

PyFrame_Type

Patch by Victor Stinner.

gh-91321 [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.

gh-91731 [https://github.com/python/cpython/issues/91731]: Avoid defining the static_assert when compiling with C++ 11, where this is a keyword and redefining it can lead to undefined behavior. Patch by Pablo Galindo

gh-89546 [https://github.com/python/cpython/issues/89546]: PyType_FromMetaclass() (and other PyType_From* functions) now check that offsets and the base class's tp_basicsize fit in the new class's tp_basicsize.

gh-93503 [https://github.com/python/cpython/issues/93503]: Add two new public functions to the public C-API, PyEval_SetProfileAllThreads() and 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 threading module (threading.setprofile_all_threads() and threading.settrace_all_threads()) that allow to do the same from Python. Patch by Pablo Galindo

gh-93442 [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.

gh-93466 [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.

gh-92898 [https://github.com/python/cpython/issues/92898]: Fix C++ compiler warnings when casting function arguments to PyObject*. Patch by Serge Guelton.

gh-93103 [https://github.com/python/cpython/issues/93103]: Deprecate global configuration variables, like Py_IgnoreEnvironmentFlag, in the documentation: the Py_InitializeFromConfig() API should be instead. Patch by Victor Stinner.

gh-77782 [https://github.com/python/cpython/issues/77782]: Deprecate global configuration variable like Py_IgnoreEnvironmentFlag: the Py_InitializeFromConfig() API should be instead. Patch by Victor Stinner.

gh-92913 [https://github.com/python/cpython/issues/92913]: Ensures changes to PyConfig.module_search_paths are ignored unless PyConfig.module_search_paths_set is set

gh-92781 [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.

gh-92651 [https://github.com/python/cpython/issues/92651]: Remove the token.h header file. There was never any public tokenizer C API. The token.h header file was only designed to be used by Python internals. Patch by Victor Stinner.

gh-92536 [https://github.com/python/cpython/issues/92536]: Remove legacy Unicode APIs based on Py_UNICODE*.

gh-85858 [https://github.com/python/cpython/issues/85858]: Remove the PyUnicode_InternImmortal() function and the SSTATE_INTERNED_IMMORTAL macro. Patch by Victor Stinner.

gh-92193 [https://github.com/python/cpython/issues/92193]: Add new function PyFunction_SetVectorcall() to the C API which sets the vectorcall field of a given PyFunctionObject.

Warning: extensions using this API must preserve the behavior of the unaltered function!

gh-59121 [https://github.com/python/cpython/issues/59121]: Fixed an assert that prevented PyRun_InteractiveOne from providing tracebacks when parsing from the provided FD.

bpo-45383 [https://bugs.python.org/issue?@action=redirect&bpo=45383]: The 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.

Python 3.11.0 beta 1

Release date: 2022-05-06

Security

gh-57684 [https://github.com/python/cpython/issues/57684]: Add the -P command line option and the PYTHONSAFEPATH environment variable to not prepend a potentially unsafe path to sys.path. Patch by Victor Stinner.

Core and Builtins

gh-89519 [https://github.com/python/cpython/issues/89519]: Chaining classmethod descriptors (introduced in bpo-19072 [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.

gh-92345 [https://github.com/python/cpython/issues/92345]: pymain_run_python() now imports readline and rlcompleter before sys.path is extended to include the current working directory of an interactive interpreter. Non-interactive interpreters are not affected.

bpo-43857 [https://bugs.python.org/issue?@action=redirect&bpo=43857]: Improve the AttributeError message when deleting a missing attribute. Patch by Géry Ogam.

gh-92245 [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.

gh-92203 [https://github.com/python/cpython/issues/92203]: Add a closure keyword-only parameter to 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 None, and it must be None if the code object doesn't refer to any free variables.

gh-91173 [https://github.com/python/cpython/issues/91173]: Disable frozen modules in debug builds. Patch by Kumar Aditya.

gh-92114 [https://github.com/python/cpython/issues/92114]: Improve error message when subscript a type with __class_getitem__ set to None.

gh-92112 [https://github.com/python/cpython/issues/92112]: Fix crash triggered by an evil custom mro() on a metaclass.

gh-92063 [https://github.com/python/cpython/issues/92063]: The PRECALL_METHOD_DESCRIPTOR_FAST_WITH_KEYWORDS instruction now ensures methods are called only on objects of the correct type.

gh-92031 [https://github.com/python/cpython/issues/92031]: Deoptimize statically allocated code objects during Py_FINALIZE() so that future _PyCode_Quicken calls always start with unquickened code.

gh-92036 [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.

gh-92032 [https://github.com/python/cpython/issues/92032]: The interpreter can now autocomplete soft keywords, as of now match, case, and _ (wildcard pattern) from PEP 634 [https://peps.python.org/pep-0634/].

gh-87999 [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.

gh-91869 [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.

gh-91603 [https://github.com/python/cpython/issues/91603]: Speed up types.UnionType instantiation. Based on patch provided by Yurii Karabas.

gh-89373 [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.

gh-91632 [https://github.com/python/cpython/issues/91632]: Fix a minor memory leak at exit: release the memory of the generic_alias_iterator type. Patch by Donghee Na.

gh-81548 [https://github.com/python/cpython/issues/81548]: Octal escapes with value larger than 0o377 now produce a DeprecationWarning. In a future Python version they will be a SyntaxWarning and eventually a SyntaxError.

bpo-43950 [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

gh-91102 [https://github.com/python/cpython/issues/91102]: Use Argument Clinic for EncodingMap. Patch by Oleg Iarygin.

gh-91636 [https://github.com/python/cpython/issues/91636]: Fixed a crash in a garbage-collection edge-case, in which a PyFunction_Type.tp_clear function could leave a python function object in an inconsistent state.

gh-91603 [https://github.com/python/cpython/issues/91603]: Speed up isinstance() and issubclass() checks for types.UnionType. Patch by Yurii Karabas.

gh-91625 [https://github.com/python/cpython/issues/91625]: Fixed a bug in which adaptive opcodes ignored any preceding EXTENDED_ARGs on specialization failure.

gh-78607 [https://github.com/python/cpython/issues/78607]: The LLTRACE special build now looks for the name __lltrace__ defined in module globals, rather than the name __ltrace__, which had been introduced as a typo.

gh-91576 [https://github.com/python/cpython/issues/91576]: Speed up iteration of ascii strings by 50%. Patch by Kumar Aditya.

gh-89279 [https://github.com/python/cpython/issues/89279]: Improve interpreter performance on Windows by inlining a few specific macros.

gh-91502 [https://github.com/python/cpython/issues/91502]: Add a new _PyFrame_IsEntryFrame() API function, to check if a PyFrameObject is an entry frame. Patch by Pablo Galindo.

gh-91266 [https://github.com/python/cpython/issues/91266]: Refactor the bytearray strip methods strip, lstrip and rstrip to use a common implementation.

gh-91479 [https://github.com/python/cpython/issues/91479]: Replaced the __note__ field of BaseException (added in an earlier version of 3.11) with the final design of PEP 678 [https://peps.python.org/pep-0678/]. Namely, BaseException gets an add_note() method, and its __notes__ field is created when necessary.

gh-46055 [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.

gh-91462 [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.

gh-89455 [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 [https://bugs.python.org/issue?@action=redirect&bpo=45292] exception groups work.

gh-91421 [https://github.com/python/cpython/issues/91421]: Fix a potential integer overflow in _Py_DecodeUTF8Ex.

gh-91428 [https://github.com/python/cpython/issues/91428]: Add static const char *const _PyOpcode_OpName[256] = {...}; to 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.

bpo-47120 [https://bugs.python.org/issue?@action=redirect&bpo=47120]: Make POP_JUMP_IF_TRUE, POP_JUMP_IF_FALSE, POP_JUMP_IF_NONE and POP_JUMP_IF_NOT_NONE virtual, mapping to new relative jump opcodes.

bpo-45317 [https://bugs.python.org/issue?@action=redirect&bpo=45317]: Add internal documentation explaining design of new (for 3.11) frame stack.

bpo-47197 [https://bugs.python.org/issue?@action=redirect&bpo=47197]: ctypes used to mishandle void return types, so that for instance a function declared like ctypes.CFUNCTYPE(None, ctypes.c_int) would be called with signature int f(int) instead of 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.

bpo-47120 [https://bugs.python.org/issue?@action=redirect&bpo=47120]: Make opcodes JUMP_IF_TRUE_OR_POP and JUMP_IF_FALSE_OR_POP relative rather than absolute.

bpo-47177 [https://bugs.python.org/issue?@action=redirect&bpo=47177]: Replace the f_lasti member of the internal _PyInterpreterFrame structure with a prev_instr pointer, which reduces overhead in the main interpreter loop. The f_lasti attribute of Python-layer frame objects is preserved for backward-compatibility.

bpo-46961 [https://bugs.python.org/issue?@action=redirect&bpo=46961]: Integer mod/remainder operations, including the three-argument form of pow(), now consistently return ints from the global small integer cache when applicable.

bpo-46962 [https://bugs.python.org/issue?@action=redirect&bpo=46962]: Classes and functions that unconditionally declared their docstrings ignoring the --without-doc-strings compilation flag no longer do so.

The classes affected are ctypes.UnionType, pickle.PickleBuffer, testcapi.RecursingInfinitelyError, and types.GenericAlias.

The functions affected are 24 methods in ctypes.

Patch by Oleg Iarygin.

bpo-46942 [https://bugs.python.org/issue?@action=redirect&bpo=46942]: Use Argument Clinic for the types.MethodType constructor. Patch by Oleg Iarygin.

bpo-46764 [https://bugs.python.org/issue?@action=redirect&bpo=46764]: Fix wrapping bound methods with @classmethod

bpo-43464 [https://bugs.python.org/issue?@action=redirect&bpo=43464]: Optimize set.intersection() for non-set arguments.

bpo-46721 [https://bugs.python.org/issue?@action=redirect&bpo=46721]: Optimize set.issuperset() for non-set argument.

bpo-46509 [https://bugs.python.org/issue?@action=redirect&bpo=46509]: Add type-specialized versions of the Py_DECREF(), and use them for float, int, str, bool, and None to avoid pointer-chasing at runtime where types are known at C compile time.

bpo-46045 [https://bugs.python.org/issue?@action=redirect&bpo=46045]: Do not use POSIX semaphores on NetBSD

bpo-36819 [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.

bpo-34093 [https://bugs.python.org/issue?@action=redirect&bpo=34093]: marshal.dumps() uses FLAG_REF for all interned strings. This makes output more deterministic and helps reproducible build.

bpo-26579 [https://bugs.python.org/issue?@action=redirect&bpo=26579]: Added object.__getstate__ which provides the default implementation of the __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.

Library

gh-87901 [https://github.com/python/cpython/issues/87901]: Add the encoding parameter to os.popen().

gh-90997 [https://github.com/python/cpython/issues/90997]: Fix an issue where dis utilities may interpret populated inline cache entries as valid instructions.

gh-92332 [https://github.com/python/cpython/issues/92332]: Deprecate typing.Text (removal of the class is currently not planned). Patch by Alex Waygood.

Deprecate nested classes in enum definitions becoming members -- in 3.13 they will be normal classes; add member and nonmember functions to allow control over results now.

gh-92356 [https://github.com/python/cpython/issues/92356]: Fixed a performance regression in ctypes function calls.

gh-90997 [https://github.com/python/cpython/issues/90997]: Show the actual named values stored in inline caches when show_caches=True is passed to dis utilities.

gh-92301 [https://github.com/python/cpython/issues/92301]: Prefer close_range() to iterating over procfs for file descriptor closing in subprocess for better performance.

gh-67248 [https://github.com/python/cpython/issues/67248]: Sort the miscellaneous topics in Cmd.do_help()

gh-92210 [https://github.com/python/cpython/issues/92210]: Port socket.__init__ to Argument Clinic. Patch by Cinder.

gh-80010 [https://github.com/python/cpython/issues/80010]: Add support for generalized ISO 8601 parsing to datetime.datetime.fromisoformat(), datetime.date.fromisoformat() and datetime.time.fromisoformat(). Patch by Paul Ganssle.

gh-92118 [https://github.com/python/cpython/issues/92118]: Fix a 3.11 regression in contextmanager(), which caused it to propagate exceptions with incorrect tracebacks.

gh-90887 [https://github.com/python/cpython/issues/90887]: Adding COPYFILE_STAT, COPYFILE_ACL and COPYFILE_XATTR constants for os.fcopyfile() available in macOs.

gh-91215 [https://github.com/python/cpython/issues/91215]: For @dataclass, add weakref_slot. The new parameter defaults to False. If true, and if slots=True, add a slot named "__weakref__", which will allow instances to be weakref'd. Contributed by Eric V. Smith

gh-85984 [https://github.com/python/cpython/issues/85984]: New function os.login_tty() for Unix.

gh-92128 [https://github.com/python/cpython/issues/92128]: Add __class_getitem__() to logging.LoggerAdapter and logging.StreamHandler, allowing them to be parameterized at runtime. Patch by Alex Waygood.

gh-92049 [https://github.com/python/cpython/issues/92049]: Forbid pickling constants re._constants.SUCCESS etc. Previously, pickling did not fail, but the result could not be unpickled.

gh-92062 [https://github.com/python/cpython/issues/92062]: inspect.Parameter now raises ValueError if name is a keyword, in addition to the existing check that it is an identifier.

gh-87390 [https://github.com/python/cpython/issues/87390]: Add an __unpacked__ attribute to types.GenericAlias. Patch by Jelle Zijlstra.

gh-88089 [https://github.com/python/cpython/issues/88089]: Add support for generic typing.NamedTuple.

gh-91996 [https://github.com/python/cpython/issues/91996]: New http.HTTPMethod enum to represent all the available HTTP request methods in a convenient way

gh-91984 [https://github.com/python/cpython/issues/91984]: Modified test strings in test_argparse.py to not contain trailing spaces before end of line.

gh-91952 [https://github.com/python/cpython/issues/91952]: Add encoding="locale" support to TextIOWrapper.reconfigure().

gh-91954 [https://github.com/python/cpython/issues/91954]: Add encoding and errors arguments to subprocess.getoutput() and subprocess.getstatusoutput().

bpo-47029 [https://bugs.python.org/issue?@action=redirect&bpo=47029]: Always close the read end of the pipe used by multiprocessing.Queue after the last write of buffered data to the write end of the pipe to avoid BrokenPipeError at garbage collection and at multiprocessing.Queue.close() calls. Patch by Géry Ogam.

gh-91928 [https://github.com/python/cpython/issues/91928]: Add datetime.UTC alias for datetime.timezone.utc.

Patch by Kabir Kwatra.

gh-68966 [https://github.com/python/cpython/issues/68966]: The mailcap module is now deprecated and will be removed in Python 3.13. See PEP 594 [https://peps.python.org/pep-0594/] for the rationale and the mimetypes module for an alternative. Patch by Victor Stinner.

gh-91401 [https://github.com/python/cpython/issues/91401]: Provide a way to disable subprocess use of vfork() just in case it is ever needed and document the existing mechanism for posix_spawn().

gh-64783 [https://github.com/python/cpython/issues/64783]: Fix signal.NSIG value on FreeBSD to accept signal numbers greater than 32, like signal.SIGRTMIN and signal.SIGRTMAX. Patch by Victor Stinner.

gh-91910 [https://github.com/python/cpython/issues/91910]: Add missing f prefix to f-strings in error messages from the multiprocessing and asyncio modules.

gh-91860 [https://github.com/python/cpython/issues/91860]: Add typing.dataclass_transform(), implementing PEP 681 [https://peps.python.org/pep-0681/]. Patch by Jelle Zijlstra.

gh-91832 [https://github.com/python/cpython/issues/91832]: Add required attribute to argparse.Action repr output.

gh-91827 [https://github.com/python/cpython/issues/91827]: In the tkinter module add method info_patchlevel() which returns the exact version of the Tcl library as a named tuple similar to sys.version_info.

gh-84461 [https://github.com/python/cpython/issues/84461]: Add --enable-wasm-pthreads to enable pthreads support for WASM builds. Emscripten/node no longer has threading enabled by default. Include additional file systems.

gh-91821 [https://github.com/python/cpython/issues/91821]: Fix unstable test_from_tuple test in test_decimal.py.

gh-91217 [https://github.com/python/cpython/issues/91217]: Deprecate the xdrlib module.

gh-91217 [https://github.com/python/cpython/issues/91217]: Deprecate the uu module.

gh-91760 [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.

gh-84461 [https://github.com/python/cpython/issues/84461]: Add provisional sys._emscripten_info named tuple with build-time and run-time information about Emscripten platform.

gh-90623 [https://github.com/python/cpython/issues/90623]: signal.raise_signal() and os.kill() now check immediately for pending signals. Patch by Victor Stinner.

gh-91734 [https://github.com/python/cpython/issues/91734]: Fix OSS audio support on Solaris.

gh-90633 [https://github.com/python/cpython/issues/90633]: Include the passed value in the exception thrown by typing.assert_never(). Patch by Jelle Zijlstra.

gh-91700 [https://github.com/python/cpython/issues/91700]: Compilation of regular expression containing a conditional expression (?(group)...) now raises an appropriate re.error if the group number refers to not defined group. Previously an internal RuntimeError was raised.

gh-91231 [https://github.com/python/cpython/issues/91231]: Add an optional keyword shutdown_timeout parameter to the multiprocessing.BaseManager constructor. Kill the process if terminate() takes longer than the timeout. Patch by Victor Stinner.

gh-91621 [https://github.com/python/cpython/issues/91621]: Fix typing.get_type_hints() for collections.abc.Callable. Patch by Shantanu Jain.

gh-90568 [https://github.com/python/cpython/issues/90568]: Parsing \N escapes of Unicode Named Character Sequences in a regular expression raises now re.error instead of TypeError.

gh-91670 [https://github.com/python/cpython/issues/91670]: Remove deprecated SO config variable in sysconfig.

gh-91217 [https://github.com/python/cpython/issues/91217]: Deprecate the telnetlib module.

gh-91217 [https://github.com/python/cpython/issues/91217]: Deprecate the sunau module.

gh-91217 [https://github.com/python/cpython/issues/91217]: Deprecate the spwd module.

gh-91217 [https://github.com/python/cpython/issues/91217]: Deprecate the sndhdr module, as well as inline needed functionality for email.mime.MIMEAudio.

gh-91616 [https://github.com/python/cpython/issues/91616]: re module, fix fullmatch() mismatch when using Atomic Grouping or Possessive Quantifiers.

gh-91217 [https://github.com/python/cpython/issues/91217]: Deprecate the 'pipes' module.

gh-91217 [https://github.com/python/cpython/issues/91217]: Deprecate the ossaudiodev module.

bpo-47256 [https://bugs.python.org/issue?@action=redirect&bpo=47256]: re module, limit the maximum capturing group to 1,073,741,823 in 64-bit build, this increases the depth of backtracking.

gh-91217 [https://github.com/python/cpython/issues/91217]: Deprecate the nis module.

gh-91595 [https://github.com/python/cpython/issues/91595]: Fix the comparison of character and integer inside Tools.gdb.libpython.write_repr(). Patch by Yu Liu.

gh-74166 [https://github.com/python/cpython/issues/74166]: Add option to raise all errors from create_connection() in an 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.

gh-91487 [https://github.com/python/cpython/issues/91487]: Optimize asyncio UDP speed, over 100 times faster when transferring a large file.

gh-91575 [https://github.com/python/cpython/issues/91575]: Update case-insensitive matching in the re module to the latest Unicode version.

gh-90622 [https://github.com/python/cpython/issues/90622]: In concurrent.futures.process.ProcessPoolExecutor disallow the "fork" multiprocessing start method when the new 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 mp_context was supplied.

gh-89022 [https://github.com/python/cpython/issues/89022]: In sqlite3, SQLITE_MISUSE result codes are now mapped to InterfaceError instead of ProgrammingError. Also, more accurate exceptions are raised when binding parameters fail. Patch by Erlend E. Aasland.

gh-91526 [https://github.com/python/cpython/issues/91526]: Stop calling os.device_encoding(file.fileno()) in TextIOWrapper. It was complex, never documented, and didn't work for most cases. (Patch by Inada Naoki.)

gh-88116 [https://github.com/python/cpython/issues/88116]: Change the frame-related functions in the inspect module to return a regular object (that is backwards compatible with the old tuple-like interface) that include the extended PEP 657 [https://peps.python.org/pep-0657/] position information (end line number, column and end column). The affected functions are: inspect.getframeinfo(), inspect.getouterframes(), inspect.getinnerframes(), inspect.stack() and inspect.trace(). Patch by Pablo Galindo.

gh-69093 [https://github.com/python/cpython/issues/69093]: Add indexing and slicing support to sqlite3.Blob. Patch by Aviv Palivoda and Erlend E. Aasland.

gh-69093 [https://github.com/python/cpython/issues/69093]: Add context manager support to sqlite3.Blob. Patch by Aviv Palivoda and Erlend E. Aasland.

gh-91217 [https://github.com/python/cpython/issues/91217]: Deprecate nntplib.

gh-91217 [https://github.com/python/cpython/issues/91217]: Deprecate msilib.

gh-91404 [https://github.com/python/cpython/issues/91404]: Improve the performance of re matching by using computed gotos (or "threaded code") on supported platforms and removing expensive pointer indirections.

gh-91217 [https://github.com/python/cpython/issues/91217]: Deprecate the imghdr module.

gh-91217 [https://github.com/python/cpython/issues/91217]: Deprecate the crypt module.

gh-91276 [https://github.com/python/cpython/issues/91276]: Make space for longer opcodes in dis output.

bpo-47000 [https://bugs.python.org/issue?@action=redirect&bpo=47000]: Make TextIOWrapper uses locale encoding when encoding="locale" is specified even in UTF-8 mode.

gh-91230 [https://github.com/python/cpython/issues/91230]: warnings.catch_warnings() now accepts arguments for warnings.simplefilter(), providing a more concise way to locally ignore warnings or convert them to errors.

gh-91217 [https://github.com/python/cpython/issues/91217]: Deprecate the chunk module.

Add the TCP_CONNECTION_INFO option (available on macOS) to socket.

bpo-47260 [https://bugs.python.org/issue?@action=redirect&bpo=47260]: Fix os.closerange() potentially being a no-op in a Linux seccomp sandbox.

bpo-47087 [https://bugs.python.org/issue?@action=redirect&bpo=47087]: Implement typing.Required and typing.NotRequired (PEP 655 [https://peps.python.org/pep-0655/]). Patch by David Foster and Jelle Zijlstra.

bpo-47061 [https://bugs.python.org/issue?@action=redirect&bpo=47061]: Deprecate cgi and cgitb.

bpo-47061 [https://bugs.python.org/issue?@action=redirect&bpo=47061]: Deprecate audioop.

bpo-47000 [https://bugs.python.org/issue?@action=redirect&bpo=47000]: Add locale.getencoding() to get the current locale encoding. It is similar to locale.getpreferredencoding(False) but ignores the Python UTF-8 Mode.

bpo-42012 [https://bugs.python.org/issue?@action=redirect&bpo=42012]: Add wsgiref.types, containing WSGI-specific types for static type checking.

bpo-47227 [https://bugs.python.org/issue?@action=redirect&bpo=47227]: Suppress expression chaining for more re parsing errors.

bpo-47211 [https://bugs.python.org/issue?@action=redirect&bpo=47211]: Remove undocumented and never working function re.template() and flag re.TEMPLATE. This was later reverted in 3.11.0b2 and deprecated instead.

bpo-47135 [https://bugs.python.org/issue?@action=redirect&bpo=47135]: decimal.localcontext() now accepts context attributes via keyword arguments

bpo-43323 [https://bugs.python.org/issue?@action=redirect&bpo=43323]: Fix errors in the email module if the charset itself contains undecodable/unencodable characters.

bpo-46841 [https://bugs.python.org/issue?@action=redirect&bpo=46841]: Disassembly of quickened code.

bpo-46681 [https://bugs.python.org/issue?@action=redirect&bpo=46681]: Forward gzip.compress() compresslevel to zlib.

bpo-45100 [https://bugs.python.org/issue?@action=redirect&bpo=45100]: Add typing.get_overloads() and typing.clear_overloads(). Patch by Jelle Zijlstra.

bpo-44807 [https://bugs.python.org/issue?@action=redirect&bpo=44807]: typing.Protocol no longer silently replaces __init__() methods defined on subclasses. Patch by Adrian Garcia Badaracco.

bpo-46787 [https://bugs.python.org/issue?@action=redirect&bpo=46787]: Fix concurrent.futures.ProcessPoolExecutor exception memory leak

bpo-46720 [https://bugs.python.org/issue?@action=redirect&bpo=46720]: Add support for path-like objects to multiprocessing.set_executable() for Windows to be on a par with Unix-like systems. Patch by Géry Ogam.

bpo-46696 [https://bugs.python.org/issue?@action=redirect&bpo=46696]: Add SO_INCOMING_CPU constant to socket.

bpo-46053 [https://bugs.python.org/issue?@action=redirect&bpo=46053]: Fix OSS audio support on NetBSD.

bpo-45639 [https://bugs.python.org/issue?@action=redirect&bpo=45639]: image/avif and image/webp were added to mimetypes.

bpo-46285 [https://bugs.python.org/issue?@action=redirect&bpo=46285]: Add command-line option -p/--protocol to module 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 http.server). Patch by Géry Ogam.

bpo-44791 [https://bugs.python.org/issue?@action=redirect&bpo=44791]: Accept ellipsis as the last argument of typing.Concatenate.

bpo-46547 [https://bugs.python.org/issue?@action=redirect&bpo=46547]: Remove variables leaking into pydoc.Helper class namespace.

bpo-46415 [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.

bpo-46075 [https://bugs.python.org/issue?@action=redirect&bpo=46075]: CookieJar with DefaultCookiePolicy now can process cookies from localhost with domain=localhost explicitly specified in Set-Cookie header.

bpo-45995 [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.

bpo-26175 [https://bugs.python.org/issue?@action=redirect&bpo=26175]: Fully implement the io.BufferedIOBase or io.TextIOBase interface for tempfile.SpooledTemporaryFile objects. This lets them work correctly with higher-level layers (like compression modules). Patch by Carey Metcalfe.

bpo-45138 [https://bugs.python.org/issue?@action=redirect&bpo=45138]: Fix a regression in the 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 [https://bugs.python.org/issue?@action=redirect&bpo=40318]. Patch by Erlend E. Aasland.

bpo-44863 [https://bugs.python.org/issue?@action=redirect&bpo=44863]: Allow TypedDict subclasses to also include Generic as a base class in class based syntax. Thereby allowing the user to define a generic TypedDict, just like a user-defined generic but with TypedDict semantics.

bpo-44587 [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.

bpo-43827 [https://bugs.python.org/issue?@action=redirect&bpo=43827]: All positional-or-keyword parameters to ABCMeta.__new__ are now positional-only to avoid conflicts with keyword arguments to be passed to __init_subclass__().

bpo-43218 [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.

bpo-38435 [https://bugs.python.org/issue?@action=redirect&bpo=38435]: Add a process_group parameter to subprocess.Popen to help move more things off of the unsafe preexec_fn parameter.

bpo-42066 [https://bugs.python.org/issue?@action=redirect&bpo=42066]: Fix cookies getting sorted in CookieJar.__iter__() which is an extra behavior and not mentioned in RFC 2965 or Netscape cookie protocol. Now the cookies in CookieJar follows the order of the Set-Cookie header. Patch by Iman Kermani.

bpo-40617 [https://bugs.python.org/issue?@action=redirect&bpo=40617]: Add create_window_function() to sqlite3.Connection for creating aggregate window functions. Patch by Erlend E. Aasland.

bpo-40676 [https://bugs.python.org/issue?@action=redirect&bpo=40676]: Convert csv to use Argument Clinic for csv.field_size_limit(), csv.get_dialect(), csv.unregister_dialect() and csv.list_dialects().

bpo-39716 [https://bugs.python.org/issue?@action=redirect&bpo=39716]: Raise an ArgumentError when the same subparser name is added twice to an argparse.ArgumentParser. This is consistent with the (default) behavior when the same option string is added twice to an ArgumentParser.

bpo-36073 [https://bugs.python.org/issue?@action=redirect&bpo=36073]: Raise ProgrammingError instead of segfaulting on recursive usage of cursors in sqlite3 converters. Patch by Sergey Fedoseev.

bpo-34975 [https://bugs.python.org/issue?@action=redirect&bpo=34975]: Adds a start_tls() method to StreamWriter, which upgrades the connection with TLS using the given SSLContext.

bpo-22276 [https://bugs.python.org/issue?@action=redirect&bpo=22276]: Path methods glob() and rglob() return only directories if pattern ends with a pathname components separator (/ or sep). Patch by Eisuke Kawashima.

bpo-24905 [https://bugs.python.org/issue?@action=redirect&bpo=24905]: Add blobopen() to sqlite3.Connection. sqlite3.Blob allows incremental I/O operations on blobs. Patch by Aviv Palivoda and Erlend E. Aasland.

Documentation

gh-91888 [https://github.com/python/cpython/issues/91888]: Add a new gh role to the documentation to link to GitHub issues.

gh-91783 [https://github.com/python/cpython/issues/91783]: Document security issues concerning the use of the function shutil.unpack_archive()

gh-91547 [https://github.com/python/cpython/issues/91547]: Remove "Undocumented modules" page.

gh-91298 [https://github.com/python/cpython/issues/91298]: In importlib.resources.abc, refined the documentation of the Traversable Protocol, applying changes from importlib_resources 5.7.1.

bpo-44347 [https://bugs.python.org/issue?@action=redirect&bpo=44347]: Clarify the meaning of dirs_exist_ok, a kwarg of shutil.copytree().

bpo-36329 [https://bugs.python.org/issue?@action=redirect&bpo=36329]: Remove 'make -C Doc serve' in favour of 'make -C Doc htmlview'

bpo-47189 [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.

bpo-38668 [https://bugs.python.org/issue?@action=redirect&bpo=38668]: Update the introduction to documentation for os.path to remove warnings that became irrelevant after the implementations of PEP 383 [https://peps.python.org/pep-0383/] and PEP 529 [https://peps.python.org/pep-0529/].

bpo-47115 [https://bugs.python.org/issue?@action=redirect&bpo=47115]: The documentation now lists which members of C structs are part of the Limited API/Stable ABI.

bpo-46962 [https://bugs.python.org/issue?@action=redirect&bpo=46962]: All docstrings in code snippets are now wrapped into PyDoc_STR to follow the guideline of PEP 7's Documentation Strings paragraph [https://www.python.org/dev/peps/pep-0007/#documentation-strings]. Patch by Oleg Iarygin.

bpo-26792 [https://bugs.python.org/issue?@action=redirect&bpo=26792]: Improve the docstrings of runpy.run_module() and runpy.run_path(). Original patch by Andrew Brezovsky.

Tests

gh-92169 [https://github.com/python/cpython/issues/92169]: Use warnings_helper.import_deprecated() to import deprecated modules uniformly in tests. Patch by Hugo van Kemenade.

gh-84461 [https://github.com/python/cpython/issues/84461]: When multiprocessing is enabled, libregrtest can now use a Python executable other than sys.executable via the --python flag.

gh-91904 [https://github.com/python/cpython/issues/91904]: Fix initialization of PYTHONREGRTEST_UNICODE_GUARD which prevented running regression tests on non-UTF-8 locale.

gh-91752 [https://github.com/python/cpython/issues/91752]: Added @requires_zlib to test.test_tools.test_freeze.TestFreeze.

gh-91607 [https://github.com/python/cpython/issues/91607]: Fix test_concurrent_futures to test the correct multiprocessing start method context in several cases where the test logic mixed this up.

bpo-40280 [https://bugs.python.org/issue?@action=redirect&bpo=40280]: Threading tests are now skipped on WASM targets without pthread support.

bpo-47109 [https://bugs.python.org/issue?@action=redirect&bpo=47109]: Test for ctypes.macholib.dyld, ctypes.macholib.dylib, and ctypes.macholib.framework are brought from manual pre-unittest times to ctypes.test location and structure. Patch by Oleg Iarygin.

bpo-29890 [https://bugs.python.org/issue?@action=redirect&bpo=29890]: Add tests for ipaddress.IPv4Interface and ipaddress.IPv6Interface construction with tuple arguments. Original patch and tests by louisom.

Build

gh-89452 [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.

gh-91731 [https://github.com/python/cpython/issues/91731]: Python is now built with -std=c11 compiler option, rather than -std=c99. Patch by Victor Stinner.

bpo-47152 [https://bugs.python.org/issue?@action=redirect&bpo=47152]: Add script and make target for generating sre_constants.h.

bpo-47103 [https://bugs.python.org/issue?@action=redirect&bpo=47103]: Windows PGInstrument builds now copy a required DLL into the output directory, making it easier to run the profile stage of a PGO build.

Windows

bpo-46907 [https://bugs.python.org/issue?@action=redirect&bpo=46907]: Update Windows installer to use SQLite 3.38.3.

bpo-47239 [https://bugs.python.org/issue?@action=redirect&bpo=47239]: Fixed --list and --list-paths output for Windows の Python ランチャ when used in an active virtual environment.

bpo-46907 [https://bugs.python.org/issue?@action=redirect&bpo=46907]: Update Windows installer to use SQLite 3.38.2.

bpo-46785 [https://bugs.python.org/issue?@action=redirect&bpo=46785]: Fix race condition between os.stat() and unlinking a file on Windows, by using errors codes returned by FindFirstFileW() when appropriate in win32_xstat_impl.

bpo-40859 [https://bugs.python.org/issue?@action=redirect&bpo=40859]: Update Windows build to use xz-5.2.5

macOS

bpo-46907 [https://bugs.python.org/issue?@action=redirect&bpo=46907]: Update macOS installer to SQLite 3.38.4.

Tools/Demos

gh-91583 [https://github.com/python/cpython/issues/91583]: Fix regression in the code generated by Argument Clinic for functions with the defining_class parameter.

gh-91575 [https://github.com/python/cpython/issues/91575]: Add script Tools/scripts/generate_re_casefix.py and the make target regen-re for generating additional data for case-insensitive matching according to the current Unicode version.

gh-91551 [https://github.com/python/cpython/issues/91551]: Remove the ancient Pynche color editor. It has moved to https://gitlab.com/warsaw/pynche

C API

gh-88279 [https://github.com/python/cpython/issues/88279]: Deprecate the C functions: PySys_SetArgv(), PySys_SetArgvEx(), PySys_SetPath(). Patch by Victor Stinner.

gh-92154 [https://github.com/python/cpython/issues/92154]: Added the PyCode_GetCode() function. This function does the equivalent of the Python code getattr(code_object, 'co_code').

gh-92173 [https://github.com/python/cpython/issues/92173]: Fix the closure argument to PyEval_EvalCodeEx().

gh-91320 [https://github.com/python/cpython/issues/91320]: Fix C++ compiler warnings about "old-style cast" (g++ -Wold-style-cast) in the Python C API. Use C++ reinterpret_cast<> and static_cast<> casts when the Python C API is used in C++. Patch by Victor Stinner.

gh-80527 [https://github.com/python/cpython/issues/80527]: Mark functions as deprecated by PEP 623 [https://peps.python.org/pep-0623/]: PyUnicode_AS_DATA(), PyUnicode_AS_UNICODE(), PyUnicode_GET_DATA_SIZE(), PyUnicode_GET_SIZE(). Patch by Victor Stinner.

gh-91768 [https://github.com/python/cpython/issues/91768]: Py_REFCNT(), Py_TYPE(), Py_SIZE() and Py_IS_TYPE() functions argument type is now PyObject*, rather than const PyObject*. Patch by Victor Stinner.

gh-91020 [https://github.com/python/cpython/issues/91020]: Add PyBytes_Type.tp_alloc to initialize PyBytesObject.ob_shash for bytes subclasses.

bpo-40421 [https://bugs.python.org/issue?@action=redirect&bpo=40421]: Add PyFrame_GetLasti C-API function to access frame object's f_lasti attribute safely from C code.

bpo-35134 [https://bugs.python.org/issue?@action=redirect&bpo=35134]: Remove the Include/code.h header file. C extensions should only include the main <Python.h> header file. Patch by Victor Stinner.

bpo-47169 [https://bugs.python.org/issue?@action=redirect&bpo=47169]: PyOS_CheckStack() is now exported in the Stable ABI on Windows.

bpo-47169 [https://bugs.python.org/issue?@action=redirect&bpo=47169]: PyThread_get_thread_native_id() is excluded from the stable ABI on platforms where it doesn't exist (like Solaris).

bpo-46343 [https://bugs.python.org/issue?@action=redirect&bpo=46343]: Added PyErr_GetHandledException() and PyErr_SetHandledException() as simpler alternatives to PyErr_GetExcInfo() and PyErr_SetExcInfo().

They are included in the stable ABI.

Python 3.11.0 alpha 7

Release date: 2022-04-05

Core and Builtins

bpo-47212 [https://bugs.python.org/issue?@action=redirect&bpo=47212]: Raise IndentationError instead of SyntaxError for a bare except with no following indent. Improve SyntaxError locations for an un-parenthesized generator used as arguments. Patch by Matthieu Dartiailh.

bpo-47186 [https://bugs.python.org/issue?@action=redirect&bpo=47186]: Replace JUMP_IF_NOT_EG_MATCH by CHECK_EG_MATCH + jump.

bpo-47176 [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.

bpo-47186 [https://bugs.python.org/issue?@action=redirect&bpo=47186]: Replace JUMP_IF_NOT_EXC_MATCH by CHECK_EXC_MATCH + jump.

bpo-47120 [https://bugs.python.org/issue?@action=redirect&bpo=47120]: Replace the absolute jump opcode JUMP_NO_INTERRUPT by the relative JUMP_BACKWARD_NO_INTERRUPT.

bpo-46841 [https://bugs.python.org/issue?@action=redirect&bpo=46841]: Avoid unnecessary allocations when comparing code objects.

bpo-47182 [https://bugs.python.org/issue?@action=redirect&bpo=47182]: Fix a crash when using a named unicode character like "\N{digit nine}" after the main interpreter has been initialized a second time.

bpo-47162 [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 PY_CALL_TRAMPOLINE to enable call trampolines.

bpo-46775 [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 OSError. Patch by Donghee Na.

bpo-47129 [https://bugs.python.org/issue?@action=redirect&bpo=47129]: Improve error messages in f-string syntax errors concerning empty expressions.

bpo-47117 [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.

bpo-47127 [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.

bpo-47120 [https://bugs.python.org/issue?@action=redirect&bpo=47120]: Replaced JUMP_ABSOLUTE by the relative jump JUMP_BACKWARD.

bpo-42197 [https://bugs.python.org/issue?@action=redirect&bpo=42197]: PyFrame_FastToLocalsWithError() and PyFrame_LocalsToFast() are no longer called during profiling nor tracing. C code can access the f_locals attribute of PyFrameObject by calling PyFrame_GetLocals().

bpo-47070 [https://bugs.python.org/issue?@action=redirect&bpo=47070]: Improve performance of array_inplace_repeat by reducing the number of invocations of memcpy. Refactor the repeat and inplace repeat methods of array, bytes, bytearray and unicodeobject to use the common _PyBytes_Repeat.

bpo-47053 [https://bugs.python.org/issue?@action=redirect&bpo=47053]: Reduce de-optimization in the specialized BINARY_OP_INPLACE_ADD_UNICODE opcode.

bpo-47045 [https://bugs.python.org/issue?@action=redirect&bpo=47045]: Remove the f_state field from the _PyInterpreterFrame struct. Add the owner field to the _PyInterpreterFrame struct to make ownership explicit to simplify clearing and deallocing frames and generators.

bpo-46968 [https://bugs.python.org/issue?@action=redirect&bpo=46968]: Check for the existence of the "sys/auxv.h" header in faulthandler to avoid compilation problems in systems where this header doesn't exist. Patch by Pablo Galindo

bpo-46329 [https://bugs.python.org/issue?@action=redirect&bpo=46329]: Use low bit of LOAD_GLOBAL to indicate whether to push a NULL before the global. Helps streamline the call sequence a bit.

bpo-46841 [https://bugs.python.org/issue?@action=redirect&bpo=46841]: Quicken bytecode in-place by storing it as part of the corresponding PyCodeObject.

bpo-47012 [https://bugs.python.org/issue?@action=redirect&bpo=47012]: Speed up iteration of bytes and bytearray by 30%. Patch by Kumar Aditya.

bpo-47009 [https://bugs.python.org/issue?@action=redirect&bpo=47009]: Improved the performance of list.append() and list comprehensions by optimizing for the common case, where no resize is needed. Patch by Dennis Sweeney.

bpo-47005 [https://bugs.python.org/issue?@action=redirect&bpo=47005]: Improve performance of bytearray_repeat and bytearray_irepeat by reducing the number of invocations of memcpy.

bpo-46829 [https://bugs.python.org/issue?@action=redirect&bpo=46829]: Deprecate passing a message into asyncio.Future.cancel() and asyncio.Task.cancel()

bpo-46993 [https://bugs.python.org/issue?@action=redirect&bpo=46993]: Speed up bytearray creation from list and tuple by 40%. Patch by Kumar Aditya.

bpo-39829 [https://bugs.python.org/issue?@action=redirect&bpo=39829]: Removed the __len__() call when initializing a list and moved initializing to list_extend. Patch by Jeremiah Pascual.

bpo-46944 [https://bugs.python.org/issue?@action=redirect&bpo=46944]: Speed up throwing exception in generator with METH_FASTCALL calling convention. Patch by Kumar Aditya.

bpo-46841 [https://bugs.python.org/issue?@action=redirect&bpo=46841]: Modify STORE_SUBSCR to use an inline cache entry (rather than its oparg) as an adaptive counter.

bpo-46841 [https://bugs.python.org/issue?@action=redirect&bpo=46841]: Use inline caching for PRECALL and CALL, and remove the internal machinery for managing the (now unused) non-inline caches.

bpo-46881 [https://bugs.python.org/issue?@action=redirect&bpo=46881]: Statically allocate and initialize the latin1 characters.

bpo-46838 [https://bugs.python.org/issue?@action=redirect&bpo=46838]: Improve syntax errors for incorrect function definitions. Patch by Pablo Galindo

bpo-43721 [https://bugs.python.org/issue?@action=redirect&bpo=43721]: Fix docstrings of getter, setter, and deleter to clarify that they create a new copy of the property.

bpo-43224 [https://bugs.python.org/issue?@action=redirect&bpo=43224]: Make grammar changes required for PEP 646.

Library

bpo-47208 [https://bugs.python.org/issue?@action=redirect&bpo=47208]: Allow vendors to override CTYPES_MAX_ARGCOUNT.

bpo-23689 [https://bugs.python.org/issue?@action=redirect&bpo=23689]: re module: fix memory leak when a match is terminated by a signal or memory allocation failure. Patch by Ma Lin.

bpo-47167 [https://bugs.python.org/issue?@action=redirect&bpo=47167]: Allow overriding a future compliance check in asyncio.Task.

bpo-47151 [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.

bpo-47152 [https://bugs.python.org/issue?@action=redirect&bpo=47152]: Convert the re module into a package. Deprecate modules sre_compile, sre_constants and sre_parse.

bpo-4833 [https://bugs.python.org/issue?@action=redirect&bpo=4833]: Add ZipFile.mkdir()

bpo-27929 [https://bugs.python.org/issue?@action=redirect&bpo=27929]: Fix asyncio.loop.sock_connect() to only resolve names for socket.AF_INET or socket.AF_INET6 families. Resolution may not make sense for other families, like socket.AF_BLUETOOTH and socket.AF_UNIX.

bpo-14265 [https://bugs.python.org/issue?@action=redirect&bpo=14265]: Adds the fully qualified test name to unittest output

bpo-47061 [https://bugs.python.org/issue?@action=redirect&bpo=47061]: Deprecate the aifc module.

bpo-39622 [https://bugs.python.org/issue?@action=redirect&bpo=39622]: Handle Ctrl+C in asyncio programs to interrupt the main task.

bpo-47101 [https://bugs.python.org/issue?@action=redirect&bpo=47101]: 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.

bpo-47099 [https://bugs.python.org/issue?@action=redirect&bpo=47099]: All URLError exception messages raised in urllib.request.URLopener now contain a colon between ftp error and the rest of the message. Previously, open_ftp() missed the colon. Patch by Oleg Iarygin.

bpo-47099 [https://bugs.python.org/issue?@action=redirect&bpo=47099]: Exception chaining is changed from Exception.with_traceback()/sys.exc_info() to PEP 3134 [https://peps.python.org/pep-3134/]. Patch by Oleg Iarygin.

bpo-47095 [https://bugs.python.org/issue?@action=redirect&bpo=47095]: hashlib's internal _blake2 module now prefers libb2 from https://www.blake2.net/ over Python's vendored copy of blake2.

bpo-47098 [https://bugs.python.org/issue?@action=redirect&bpo=47098]: The Keccak Code Package for hashlib's internal _sha3 module has been replaced with tiny_sha3. The module is used as fallback when Python is built without OpenSSL.

bpo-47088 [https://bugs.python.org/issue?@action=redirect&bpo=47088]: Implement typing.LiteralString, part of PEP 675 [https://peps.python.org/pep-0675/]. Patch by Jelle Zijlstra.

bpo-42885 [https://bugs.python.org/issue?@action=redirect&bpo=42885]: Optimize re.search(), re.split(), re.findall(), re.finditer() and re.sub() for regular expressions starting with \A or ^.

bpo-23691 [https://bugs.python.org/issue?@action=redirect&bpo=23691]: Protect the re.finditer() iterator from re-entering.

bpo-47067 [https://bugs.python.org/issue?@action=redirect&bpo=47067]: Optimize calling GenericAlias objects by using PEP 590 [https://peps.python.org/pep-0590/] vectorcall and by replacing PyObject_SetAttrString with PyObject_SetAttr.

bpo-28080 [https://bugs.python.org/issue?@action=redirect&bpo=28080]: Add the metadata_encoding parameter in the zipfile.ZipFile constructor and the --metadata-encoding option in the zipfile CLI to allow reading zipfiles using non-standard codecs to encode the filenames within the archive.

bpo-47000 [https://bugs.python.org/issue?@action=redirect&bpo=47000]: Make io.text_encoding() returns "utf-8" when UTF-8 mode is enabled.

bpo-42369 [https://bugs.python.org/issue?@action=redirect&bpo=42369]: Fix thread safety of zipfile._SharedFile.tell() to avoid a "zipfile.BadZipFile: Bad CRC-32 for file" exception when reading a ZipFile from multiple threads.

bpo-38256 [https://bugs.python.org/issue?@action=redirect&bpo=38256]: Fix 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 binascii.crc32() release the GIL when computing on larger inputs as zlib.crc32() and hashlib do.

This also boosts performance on Windows as it now uses the zlib crc32 implementation for 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.

bpo-47066 [https://bugs.python.org/issue?@action=redirect&bpo=47066]: Global inline flags (e.g. (?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.

bpo-39394 [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.

bpo-433030 [https://bugs.python.org/issue?@action=redirect&bpo=433030]: Add support of atomic grouping ((?>...)) and possessive quantifiers (*+, ++, ?+, {m,n}+) in regular expressions.

bpo-47062 [https://bugs.python.org/issue?@action=redirect&bpo=47062]: Implement asyncio.Runner context manager.

bpo-46382 [https://bugs.python.org/issue?@action=redirect&bpo=46382]: dataclass() slots=True now correctly omits slots already defined in base classes. Patch by Arie Bovenberg.

bpo-47057 [https://bugs.python.org/issue?@action=redirect&bpo=47057]: Use FASTCALL convention for FutureIter.throw()

bpo-47061 [https://bugs.python.org/issue?@action=redirect&bpo=47061]: Deprecate the various modules listed by PEP 594 [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

bpo-34790 [https://bugs.python.org/issue?@action=redirect&bpo=34790]: Remove passing coroutine objects to asyncio.wait().

bpo-47039 [https://bugs.python.org/issue?@action=redirect&bpo=47039]: Normalize repr() of asyncio future and task objects.

bpo-2604 [https://bugs.python.org/issue?@action=redirect&bpo=2604]: Fix bug where doctests using globals would fail when run multiple times.

bpo-45150 [https://bugs.python.org/issue?@action=redirect&bpo=45150]: Add hashlib.file_digest() helper for efficient hashing of file object.

bpo-34861 [https://bugs.python.org/issue?@action=redirect&bpo=34861]: Made cumtime the default sorting key for cProfile

bpo-45997 [https://bugs.python.org/issue?@action=redirect&bpo=45997]: Fix asyncio.Semaphore re-aquiring FIFO order.

bpo-47022 [https://bugs.python.org/issue?@action=redirect&bpo=47022]: The asynchat, asyncore and 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 (PEP 594 [https://peps.python.org/pep-0594/]).

bpo-43253 [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.

bpo-40280 [https://bugs.python.org/issue?@action=redirect&bpo=40280]: select.select() now passes NULL to select for each empty fdset.

bpo-47004 [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.

bpo-46998 [https://bugs.python.org/issue?@action=redirect&bpo=46998]: Allow subclassing of typing.Any. Patch by Shantanu Jain.

bpo-46995 [https://bugs.python.org/issue?@action=redirect&bpo=46995]: Deprecate missing asyncio.Task.set_name() for third-party task implementations, schedule making it mandatory in Python 3.13.

bpo-46994 [https://bugs.python.org/issue?@action=redirect&bpo=46994]: Accept explicit contextvars.Context in asyncio.create_task() and asyncio.loop.create_task().

bpo-46981 [https://bugs.python.org/issue?@action=redirect&bpo=46981]: typing.get_args(typing.Tuple[()]) now returns () instead of ((),).

bpo-46968 [https://bugs.python.org/issue?@action=redirect&bpo=46968]: Add os.sysconf_names['SC_MINSIGSTKSZ'].

bpo-46985 [https://bugs.python.org/issue?@action=redirect&bpo=46985]: Upgrade pip wheel bundled with ensurepip (pip 22.0.4)

bpo-46968 [https://bugs.python.org/issue?@action=redirect&bpo=46968]: faulthandler: On Linux 5.14 and newer, dynamically determine size of signal handler stack size CPython allocates using 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.

bpo-46917 [https://bugs.python.org/issue?@action=redirect&bpo=46917]: The math.nan value is now always available. Patch by Victor Stinner.

bpo-46955 [https://bugs.python.org/issue?@action=redirect&bpo=46955]: Expose asyncio.base_events.Server as asyncio.Server. Patch by Stefan Zabka.

bpo-23325 [https://bugs.python.org/issue?@action=redirect&bpo=23325]: The signal module no longer assumes that SIG_IGN and SIG_DFL are small int singletons.

bpo-46932 [https://bugs.python.org/issue?@action=redirect&bpo=46932]: Update bundled libexpat to 2.4.7

bpo-46933 [https://bugs.python.org/issue?@action=redirect&bpo=46933]: The pwd module is now optional. os.path.expanduser() returns the path when the pwd module is not available.

bpo-40059 [https://bugs.python.org/issue?@action=redirect&bpo=40059]: PEP 680 [https://peps.python.org/pep-0680/], the tomllib module. Adds support for parsing TOML.

bpo-464471 [https://bugs.python.org/issue?@action=redirect&bpo=464471]: asyncio.timeout() and asyncio.timeout_at() context managers added. Patch by Tin Tvrtković and Andrew Svetlov.

bpo-46805 [https://bugs.python.org/issue?@action=redirect&bpo=46805]: Added raw datagram socket functions for asyncio: sock_sendto(), sock_recvfrom() and sock_recvfrom_into().

bpo-46644 [https://bugs.python.org/issue?@action=redirect&bpo=46644]: No longer require valid typeforms to be callable. This allows typing.Annotated to wrap typing.ParamSpecArgs and dataclasses.InitVar. Patch by Gregory Beauregard.

bpo-46581 [https://bugs.python.org/issue?@action=redirect&bpo=46581]: Brings ParamSpec propagation for GenericAlias in line with Concatenate (and others).

bpo-45413 [https://bugs.python.org/issue?@action=redirect&bpo=45413]: Define posix_venv and nt_venv 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 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, sysconfig.get_default_scheme() and sysconfig.get_preferred_scheme() with key="prefix" returns venv.

bpo-43224 [https://bugs.python.org/issue?@action=redirect&bpo=43224]: Implement support for PEP 646 in typing.py.

bpo-43224 [https://bugs.python.org/issue?@action=redirect&bpo=43224]: Allow unpacking types.GenericAlias objects, e.g. *tuple[int, str].

bpo-46557 [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.

bpo-41370 [https://bugs.python.org/issue?@action=redirect&bpo=41370]: typing.get_type_hints() now supports evaluating strings as forward references in PEP 585 generic aliases.

bpo-46607 [https://bugs.python.org/issue?@action=redirect&bpo=46607]: Add DeprecationWarning to LegacyInterpolation, deprecated in the docstring since Python 3.2. Will be removed in Python 3.13. Use BasicInterpolation or ExtendedInterpolation instead.

bpo-26120 [https://bugs.python.org/issue?@action=redirect&bpo=26120]: pydoc now excludes __future__ imports from the module's data items.

bpo-46480 [https://bugs.python.org/issue?@action=redirect&bpo=46480]: Add typing.assert_type(). Patch by Jelle Zijlstra.

bpo-46421 [https://bugs.python.org/issue?@action=redirect&bpo=46421]: Fix a unittest issue where if the command was invoked as python -m unittest and the filename(s) began with a dot (.), a ValueError is returned.

bpo-46245 [https://bugs.python.org/issue?@action=redirect&bpo=46245]: Add optional parameter dir_fd in shutil.rmtree().

bpo-22859 [https://bugs.python.org/issue?@action=redirect&bpo=22859]: usageExit() is marked deprecated, to be removed in 3.13.

bpo-46170 [https://bugs.python.org/issue?@action=redirect&bpo=46170]: Improve the error message when you try to subclass an instance of typing.NewType.

bpo-40296 [https://bugs.python.org/issue?@action=redirect&bpo=40296]: Fix supporting generic aliases in pydoc.

bpo-20392 [https://bugs.python.org/issue?@action=redirect&bpo=20392]: Fix inconsistency with uppercase file extensions in MimeTypes.guess_type(). Patch by Kumar Aditya.

bpo-46030 [https://bugs.python.org/issue?@action=redirect&bpo=46030]: Add LOCAL_CREDS, LOCAL_CREDS_PERSISTENT and SCM_CREDS2 FreeBSD constants to the socket module.

bpo-44439 [https://bugs.python.org/issue?@action=redirect&bpo=44439]: Fix .write() method of a member file in ZipFile, when the input data is an object that supports the buffer protocol, the file length may be wrong.

bpo-45171 [https://bugs.python.org/issue?@action=redirect&bpo=45171]: Fix handling of the stacklevel argument to logging functions in the logging module so that it is consistent across all logging functions and, as advertised, similar to the stacklevel argument used in warn().

bpo-24959 [https://bugs.python.org/issue?@action=redirect&bpo=24959]: Fix bug where unittest sometimes drops frames from tracebacks of exceptions raised in tests.

bpo-44859 [https://bugs.python.org/issue?@action=redirect&bpo=44859]: Raise more accurate and PEP 249 [https://peps.python.org/pep-0249/] compatible exceptions in sqlite3.

Raise InterfaceError instead of ProgrammingError for SQLITE_MISUSE errors.

Don't overwrite BufferError with ValueError when conversion to BLOB fails.

Raise ProgrammingError instead of Warning if user tries to execute() more than one SQL statement.

Raise ProgrammingError instead of ValueError if an SQL query contains null characters.

bpo-44493 [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.

bpo-41930 [https://bugs.python.org/issue?@action=redirect&bpo=41930]: Add serialize() and deserialize() support to sqlite3. Patch by Erlend E. Aasland.

bpo-33178 [https://bugs.python.org/issue?@action=redirect&bpo=33178]: Added ctypes.BigEndianUnion and ctypes.LittleEndianUnion classes, as originally documented in the library docs but not yet implemented.

bpo-43352 [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*

bpo-35859 [https://bugs.python.org/issue?@action=redirect&bpo=35859]: re module, fix a few bugs about capturing group. In rare cases, capturing group gets an incorrect string. Patch by Ma Lin.

Documentation

bpo-45099 [https://bugs.python.org/issue?@action=redirect&bpo=45099]: Document internal asyncio API.

bpo-47126 [https://bugs.python.org/issue?@action=redirect&bpo=47126]: Update PEP URLs to PEP 676 [https://peps.python.org/pep-0676/]'s new canonical form.

bpo-47040 [https://bugs.python.org/issue?@action=redirect&bpo=47040]: Clarified the old Python versions compatibility note of binascii.crc32() / zlib.adler32() / zlib.crc32() functions.

bpo-46033 [https://bugs.python.org/issue?@action=redirect&bpo=46033]: Clarify for statement execution in its doc.

bpo-45790 [https://bugs.python.org/issue?@action=redirect&bpo=45790]: Adjust inaccurate phrasing in 拡張の型の定義: チュートリアル about the ob_base field and the macros used to access its contents.

bpo-42340 [https://bugs.python.org/issue?@action=redirect&bpo=42340]: Document that in some circumstances KeyboardInterrupt may cause the code to enter an inconsistent state. Provided a sample workaround to avoid it if needed.

bpo-41233 [https://bugs.python.org/issue?@action=redirect&bpo=41233]: Link the errnos referenced in Doc/library/exceptions.rst to their respective section in Doc/library/errno.rst, and vice versa. Previously this was only done for EINTR and InterruptedError. Patch by Yan "yyyyyyyan" Orestes.

Tests

bpo-47205 [https://bugs.python.org/issue?@action=redirect&bpo=47205]: Skip test for sched_getaffinity() and sched_setaffinity() error case on FreeBSD.

bpo-46126 [https://bugs.python.org/issue?@action=redirect&bpo=46126]: Restore 'descriptions' when running tests internally.

bpo-47104 [https://bugs.python.org/issue?@action=redirect&bpo=47104]: Rewrite asyncio.to_thread() tests to use unittest.IsolatedAsyncioTestCase.

bpo-40280 [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.

bpo-47037 [https://bugs.python.org/issue?@action=redirect&bpo=47037]: Skip strftime("%4Y") feature test on Windows. It can cause an assertion error in debug builds.

bpo-46587 [https://bugs.python.org/issue?@action=redirect&bpo=46587]: Skip tests if platform's strftime does not support non-portable glibc extensions.

bpo-47015 [https://bugs.python.org/issue?@action=redirect&bpo=47015]: A test case for os.sendfile() is converted from deprecated asyncore (see PEP 594 [https://peps.python.org/pep-0594/]) to asyncio. Patch by Oleg Iarygin.

Build

bpo-40280 [https://bugs.python.org/issue?@action=redirect&bpo=40280]: Add configure option --enable-wasm-dynamic-linking to enable dlopen and MAIN_MODULE / SIDE_MODULE on wasm32-emscripten.

bpo-46023 [https://bugs.python.org/issue?@action=redirect&bpo=46023]: makesetup now detects and skips all duplicated module definitions. The first entry wins.

bpo-40280 [https://bugs.python.org/issue?@action=redirect&bpo=40280]: Add SOABI wasm32-emscripten for Emscripten and wasm32-wasi for WASI on 32bit WASM as well as wasm64 counter parts.

bpo-47032 [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.

bpo-47024 [https://bugs.python.org/issue?@action=redirect&bpo=47024]: Update OpenSSL to 1.1.1n for macOS installers and all Windows builds.

bpo-46996 [https://bugs.python.org/issue?@action=redirect&bpo=46996]: The tkinter package now requires Tcl/Tk version 8.5.12 or newer.

bpo-46973 [https://bugs.python.org/issue?@action=redirect&bpo=46973]: Add regen-configure make target to regenerate configure script with Christian's container image quay.io/tiran/cpython_autoconf:269.

bpo-46917 [https://bugs.python.org/issue?@action=redirect&bpo=46917]: Building Python now requires support of IEEE 754 floating point numbers. Patch by Victor Stinner.

bpo-45774 [https://bugs.python.org/issue?@action=redirect&bpo=45774]: configure now verifies that all SQLite C APIs needed for the sqlite3 extension module are found.

Windows

bpo-47194 [https://bugs.python.org/issue?@action=redirect&bpo=47194]: Update zlib to v1.2.12 to resolve CVE-2018-25032 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-25032].

bpo-47171 [https://bugs.python.org/issue?@action=redirect&bpo=47171]: Enables installing the py.exe launcher on Windows ARM64.

bpo-46566 [https://bugs.python.org/issue?@action=redirect&bpo=46566]: Upgraded Windows の Python ランチャ to support a new -V:company/tag argument for full PEP 514 [https://peps.python.org/pep-0514/] support and to detect ARM64 installs. The -64 suffix on arguments is deprecated, but still selects any non-32-bit install. Setting PYLAUNCHER_ALLOW_INSTALL and specifying a version that is not installed will attempt to install the requested version from the Microsoft Store.

bpo-47086 [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 .chm file.

bpo-46907 [https://bugs.python.org/issue?@action=redirect&bpo=46907]: Update Windows installer to use SQLite 3.38.1.

bpo-44549 [https://bugs.python.org/issue?@action=redirect&bpo=44549]: Update bzip2 to 1.0.8 in Windows builds to mitigate CVE-2016-3189 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-3189] and CVE-2019-12900 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-12900].

bpo-46948 [https://bugs.python.org/issue?@action=redirect&bpo=46948]: Prevent CVE-2022-26488 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-26488] by ensuring the Add to PATH option in the Windows installer uses the correct path when being repaired.

macOS

bpo-46890 [https://bugs.python.org/issue?@action=redirect&bpo=46890]: Fix a regression in the setting of sys._base_executable in framework builds, and thereby fix a regression in venv virtual environments with such builds.

bpo-46907 [https://bugs.python.org/issue?@action=redirect&bpo=46907]: Update macOS installer to SQLite 3.38.1.

Tools/Demos

bpo-40280 [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.

C API

bpo-40421 [https://bugs.python.org/issue?@action=redirect&bpo=40421]: Add PyFrame_GetBuiltins, PyFrame_GetGenerator and PyFrame_GetGlobals C-API functions to access frame object attributes safely from C code.

bpo-46850 [https://bugs.python.org/issue?@action=redirect&bpo=46850]: Move the private _PyFrameEvalFunction type, and private _PyInterpreterState_GetEvalFrameFunc() and _PyInterpreterState_SetEvalFrameFunc() functions to the internal C API. The _PyFrameEvalFunction callback function type now uses the _PyInterpreterFrame type which is part of the internal C API. Patch by Victor Stinner.

bpo-46850 [https://bugs.python.org/issue?@action=redirect&bpo=46850]: Move the private undocumented _PyEval_EvalFrameDefault() function to the internal C API. The function now uses the _PyInterpreterFrame type which is part of the internal C API. Patch by Victor Stinner.

bpo-46850 [https://bugs.python.org/issue?@action=redirect&bpo=46850]: Remove the private undocumented function _PyEval_CallTracing() from the C API. Call the public sys.call_tracing() function instead. Patch by Victor Stinner.

bpo-46850 [https://bugs.python.org/issue?@action=redirect&bpo=46850]: Remove the private undocumented function _PyEval_GetCoroutineOriginTrackingDepth() from the C API. Call the public sys.get_coroutine_origin_tracking_depth() function instead. Patch by Victor Stinner.

bpo-46850 [https://bugs.python.org/issue?@action=redirect&bpo=46850]: Remove the following private undocumented functions from the C API:

_PyEval_GetAsyncGenFirstiter()

_PyEval_GetAsyncGenFinalizer()

_PyEval_SetAsyncGenFirstiter()

_PyEval_SetAsyncGenFinalizer()

Call the public sys.get_asyncgen_hooks() and sys.set_asyncgen_hooks() functions instead. Patch by Victor Stinner.

bpo-46987 [https://bugs.python.org/issue?@action=redirect&bpo=46987]: Remove private functions _PySys_GetObjectId() and _PySys_SetObjectId(). Patch by Donghee Na.

bpo-46906 [https://bugs.python.org/issue?@action=redirect&bpo=46906]: Add new functions to pack and unpack C double (serialize and deserialize): PyFloat_Pack2(), PyFloat_Pack4(), PyFloat_Pack8(), PyFloat_Unpack2(), PyFloat_Unpack4() and PyFloat_Unpack8(). Patch by Victor Stinner.

Python 3.11.0 alpha 6

Release date: 2022-03-07

Core and Builtins

bpo-46940 [https://bugs.python.org/issue?@action=redirect&bpo=46940]: Avoid overriding AttributeError metadata information for nested attribute access calls. Patch by Pablo Galindo.

bpo-46927 [https://bugs.python.org/issue?@action=redirect&bpo=46927]: Include the type's name in the error message for subscripting non-generic types.

bpo-46921 [https://bugs.python.org/issue?@action=redirect&bpo=46921]: Support vectorcall for super(). Patch by Ken Jin.

bpo-46841 [https://bugs.python.org/issue?@action=redirect&bpo=46841]: Fix incorrect handling of inline cache entries when specializing BINARY_OP.

bpo-46841 [https://bugs.python.org/issue?@action=redirect&bpo=46841]: Use an oparg to simplify the construction of helpful error messages in GET_AWAITABLE.

bpo-46903 [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

bpo-46841 [https://bugs.python.org/issue?@action=redirect&bpo=46841]: Add more detailed specialization failure stats for COMPARE_OP followed by EXTENDED_ARG.

bpo-46891 [https://bugs.python.org/issue?@action=redirect&bpo=46891]: Fix bug introduced during 3.11alpha where subclasses of types.ModuleType with __slots__ were not initialized correctly, resulting in an interpreter crash.

bpo-46841 [https://bugs.python.org/issue?@action=redirect&bpo=46841]: Use inline caching for LOAD_ATTR, LOAD_METHOD, and STORE_ATTR.

bpo-46841 [https://bugs.python.org/issue?@action=redirect&bpo=46841]: Use inline cache for BINARY_SUBSCR.

bpo-46841 [https://bugs.python.org/issue?@action=redirect&bpo=46841]: Use inline caching for COMPARE_OP.

bpo-46864 [https://bugs.python.org/issue?@action=redirect&bpo=46864]: Deprecate PyBytesObject.ob_shash. It will be removed in Python 3.13.

bpo-46841 [https://bugs.python.org/issue?@action=redirect&bpo=46841]: Use inline caching for UNPACK_SEQUENCE.

bpo-46845 [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, sys.getsizeof(dict.fromkeys("abcdefg")) becomes 272 bytes from 352 bytes on 64bit platform.

bpo-46841 [https://bugs.python.org/issue?@action=redirect&bpo=46841]: Use inline cache for LOAD_GLOBAL.

bpo-46852 [https://bugs.python.org/issue?@action=redirect&bpo=46852]: Rename the private undocumented float.__set_format__() method to float.__setformat__() to fix a typo introduced in Python 3.7. The method is only used by test_float. Patch by Victor Stinner.

bpo-46852 [https://bugs.python.org/issue?@action=redirect&bpo=46852]: Remove the undocumented private float.__set_format__() method, previously known as 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.

bpo-40116 [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.

bpo-46712 [https://bugs.python.org/issue?@action=redirect&bpo=46712]: Share global string identifiers in deep-frozen modules.

bpo-46430 [https://bugs.python.org/issue?@action=redirect&bpo=46430]: Fix memory leak in interned strings of deep-frozen modules.

bpo-46841 [https://bugs.python.org/issue?@action=redirect&bpo=46841]: Store BINARY_OP caches inline using a new CACHE instruction.

bpo-45107 [https://bugs.python.org/issue?@action=redirect&bpo=45107]: Specialize LOAD_METHOD for instances with a dict.

bpo-44337 [https://bugs.python.org/issue?@action=redirect&bpo=44337]: Reduce the memory usage of specialized LOAD_ATTR and STORE_ATTR instructions.

bpo-46729 [https://bugs.python.org/issue?@action=redirect&bpo=46729]: Add number of sub-exceptions to BaseException.__str__().

bpo-45885 [https://bugs.python.org/issue?@action=redirect&bpo=45885]: Don't un-adapt COMPARE_OP when collecting specialization stats.

bpo-46329 [https://bugs.python.org/issue?@action=redirect&bpo=46329]: Fix specialization stats gathering for PRECALL instructions.

bpo-46794 [https://bugs.python.org/issue?@action=redirect&bpo=46794]: Bump up the libexpat version into 2.4.6

bpo-46823 [https://bugs.python.org/issue?@action=redirect&bpo=46823]: Implement a specialized combined opcode LOAD_FAST__LOAD_ATTR_INSTANCE_VALUE. Patch by Dennis Sweeney.

bpo-46820 [https://bugs.python.org/issue?@action=redirect&bpo=46820]: Fix parsing a numeric literal immediately (without spaces) followed by "not in" keywords, like in 1not in x. Now the parser only emits a warning, not a syntax error.

bpo-46329 [https://bugs.python.org/issue?@action=redirect&bpo=46329]: Move KW_NAMES before PRECALL instruction in call sequence. Change operand of CALL to match PRECALL for easier specialization.

bpo-46808 [https://bugs.python.org/issue?@action=redirect&bpo=46808]: Remove the NEXT_BLOCK macro from compile.c, and make the compiler automatically generate implicit blocks when they are needed.

bpo-46329 [https://bugs.python.org/issue?@action=redirect&bpo=46329]: Add 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. PRECALL_FUNCTION and PRECALL_METHOD are merged into a single PRECALL instruction.

There is no change in semantics.

bpo-46762 [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.

bpo-46730 [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.

bpo-46724 [https://bugs.python.org/issue?@action=redirect&bpo=46724]: Make sure that all backwards jumps use the JUMP_ABSOLUTE instruction, rather than JUMP_FORWARD with an argument of (2**32)+offset.

bpo-46732 [https://bugs.python.org/issue?@action=redirect&bpo=46732]: Correct the docstring for the __bool__() method. Patch by Jelle Zijlstra.

bpo-46072 [https://bugs.python.org/issue?@action=redirect&bpo=46072]: Add more detailed specialization failure statistics for BINARY_OP.

bpo-46707 [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.

bpo-46323 [https://bugs.python.org/issue?@action=redirect&bpo=46323]: 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.

bpo-45923 [https://bugs.python.org/issue?@action=redirect&bpo=45923]: Add a quickened form of RESUME that skips quickening checks.

bpo-46702 [https://bugs.python.org/issue?@action=redirect&bpo=46702]: Specialize UNPACK_SEQUENCE for tuple and list unpackings.

bpo-46072 [https://bugs.python.org/issue?@action=redirect&bpo=46072]: Opcode pair stats are now gathered with --enable-pystats. Defining DYNAMIC_EXECUTION_PROFILE or DXPAIRS no longer has any effect.

bpo-46675 [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.

bpo-40479 [https://bugs.python.org/issue?@action=redirect&bpo=40479]: Add a missing call to va_end() in Modules/_hashopenssl.c.

bpo-46323 [https://bugs.python.org/issue?@action=redirect&bpo=46323]: Use PyObject_Vectorcall() while calling ctypes callback function. Patch by Donghee Na.

bpo-46615 [https://bugs.python.org/issue?@action=redirect&bpo=46615]: When iterating over sets internally in 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.

bpo-45828 [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).

bpo-30496 [https://bugs.python.org/issue?@action=redirect&bpo=30496]: Fixed a minor portability issue in the implementation of PyLong_FromLong(), and added a fast path for single-digit integers to PyLong_FromLongLong().

Library

bpo-25707 [https://bugs.python.org/issue?@action=redirect&bpo=25707]: Fixed a file leak in xml.etree.ElementTree.iterparse() when the iterator is not exhausted. Patch by Jacob Walls.

bpo-46877 [https://bugs.python.org/issue?@action=redirect&bpo=46877]: Export unittest.doModuleCleanups() in unittest. Patch by Kumar Aditya.

bpo-46848 [https://bugs.python.org/issue?@action=redirect&bpo=46848]: For performance, use the optimized string-searching implementations from find() and rfind() for find() and rfind().

bpo-46736 [https://bugs.python.org/issue?@action=redirect&bpo=46736]: SimpleHTTPRequestHandler now uses HTML5 grammar. Patch by Donghee Na.

bpo-44886 [https://bugs.python.org/issue?@action=redirect&bpo=44886]: Inherit asyncio proactor datagram transport from asyncio.DatagramTransport.

bpo-46827 [https://bugs.python.org/issue?@action=redirect&bpo=46827]: Support UDP sockets in asyncio.loop.sock_connect() for selector-based event loops. Patch by Thomas Grainger.

bpo-46811 [https://bugs.python.org/issue?@action=redirect&bpo=46811]: Make test suite support Expat >=2.4.5

bpo-46252 [https://bugs.python.org/issue?@action=redirect&bpo=46252]: Raise TypeError if ssl.SSLSocket is passed to transport-based APIs.

bpo-46784 [https://bugs.python.org/issue?@action=redirect&bpo=46784]: Fix libexpat symbols collisions with user dynamically loaded or statically linked libexpat in embedded Python.

bpo-46786 [https://bugs.python.org/issue?@action=redirect&bpo=46786]: The HTML serialisation in xml.etree.ElementTree now writes embed, source, track and wbr as empty tags, as defined in HTML 5.

bpo-39327 [https://bugs.python.org/issue?@action=redirect&bpo=39327]: shutil.rmtree() can now work with VirtualBox shared folders when running from the guest operating-system.

bpo-45390 [https://bugs.python.org/issue?@action=redirect&bpo=45390]: Propagate asyncio.CancelledError message from inner task to outer awaiter.

bpo-46756 [https://bugs.python.org/issue?@action=redirect&bpo=46756]: Fix a bug in urllib.request.HTTPPasswordMgr.find_user_password() and urllib.request.HTTPPasswordMgrWithPriorAuth.is_authenticated() which allowed to bypass authorization. For example, access to URI example.org/foobar was allowed if the user was authorized for URI example.org/foo.

bpo-46737 [https://bugs.python.org/issue?@action=redirect&bpo=46737]: random.gauss() and random.normalvariate() now have default arguments.

bpo-46752 [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().

bpo-46724 [https://bugs.python.org/issue?@action=redirect&bpo=46724]: Fix dis behavior on negative jump offsets.

bpo-46333 [https://bugs.python.org/issue?@action=redirect&bpo=46333]: The __repr__() method of typing.ForwardRef now includes the module parameter of typing.ForwardRef when it is set.

bpo-46643 [https://bugs.python.org/issue?@action=redirect&bpo=46643]: In typing.get_type_hints(), support evaluating stringified ParamSpecArgs and ParamSpecKwargs annotations. Patch by Gregory Beauregard.

bpo-45863 [https://bugs.python.org/issue?@action=redirect&bpo=45863]: When the 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.

bpo-46066 [https://bugs.python.org/issue?@action=redirect&bpo=46066]: Deprecate kwargs-based syntax for typing.TypedDict definitions. It had confusing semantics when specifying totality, and was largely unused. Patch by Jingchen Ye.

bpo-46676 [https://bugs.python.org/issue?@action=redirect&bpo=46676]: Make typing.ParamSpec args and kwargs equal to themselves. Patch by Gregory Beauregard.

bpo-46323 [https://bugs.python.org/issue?@action=redirect&bpo=46323]: ctypes.CFUNCTYPE() and ctypes.WINFUNCTYPE() now fail to create the type if its _argtypes_ member contains too many arguments. Previously, the error was only raised when calling a function. Patch by Victor Stinner.

bpo-46672 [https://bugs.python.org/issue?@action=redirect&bpo=46672]: Fix NameError in asyncio.gather() when initial type check fails.

bpo-46659 [https://bugs.python.org/issue?@action=redirect&bpo=46659]: The calendar.LocaleTextCalendar and calendar.LocaleHTMLCalendar classes now use locale.getlocale(), instead of using locale.getdefaultlocale(), if no locale is specified. Patch by Victor Stinner.

bpo-46659 [https://bugs.python.org/issue?@action=redirect&bpo=46659]: The locale.getdefaultlocale() function is deprecated and will be removed in Python 3.13. Use locale.setlocale(), locale.getpreferredencoding(False) and locale.getlocale() functions instead. Patch by Victor Stinner.

bpo-46655 [https://bugs.python.org/issue?@action=redirect&bpo=46655]: In typing.get_type_hints(), support evaluating bare stringified TypeAlias annotations. Patch by Gregory Beauregard.

bpo-45948 [https://bugs.python.org/issue?@action=redirect&bpo=45948]: Fixed a discrepancy in the C implementation of the xml.etree.ElementTree module. Now, instantiating an xml.etree.ElementTree.XMLParser with a target=None keyword provides a default xml.etree.ElementTree.TreeBuilder target as the Python implementation does.

bpo-46626 [https://bugs.python.org/issue?@action=redirect&bpo=46626]: Expose Linux's IP_BIND_ADDRESS_NO_PORT option in socket.

bpo-46521 [https://bugs.python.org/issue?@action=redirect&bpo=46521]: Fix a bug in the codeop module that was incorrectly identifying invalid code involving string quotes as valid code.

bpo-46571 [https://bugs.python.org/issue?@action=redirect&bpo=46571]: Improve 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.

bpo-46400 [https://bugs.python.org/issue?@action=redirect&bpo=46400]: expat: Update libexpat from 2.4.1 to 2.4.4

bpo-46556 [https://bugs.python.org/issue?@action=redirect&bpo=46556]: Deprecate undocumented support for using a pathlib.Path object as a context manager.

bpo-46534 [https://bugs.python.org/issue?@action=redirect&bpo=46534]: Implement PEP 673 [https://peps.python.org/pep-0673/] typing.Self. Patch by James Hilton-Balfe.

bpo-46522 [https://bugs.python.org/issue?@action=redirect&bpo=46522]: Make various module __getattr__ AttributeErrors more closely match a typical AttributeError

bpo-46475 [https://bugs.python.org/issue?@action=redirect&bpo=46475]: Add typing.Never and typing.assert_never(). Patch by Jelle Zijlstra.

bpo-46333 [https://bugs.python.org/issue?@action=redirect&bpo=46333]: The __eq__() and __hash__() methods of typing.ForwardRef now honor the module parameter of typing.ForwardRef. Forward references from different modules are now differentiated.

bpo-46246 [https://bugs.python.org/issue?@action=redirect&bpo=46246]: Add missing __slots__ to importlib.metadata.DeprecatedList. Patch by Arie Bovenberg.

bpo-46232 [https://bugs.python.org/issue?@action=redirect&bpo=46232]: The ssl module now handles certificates with bit strings in DN correctly.

bpo-46195 [https://bugs.python.org/issue?@action=redirect&bpo=46195]: typing.get_type_hints() no longer adds Optional to parameters with None as a default. This aligns to changes to PEP 484 in https://github.com/python/peps/pull/689

bpo-31369 [https://bugs.python.org/issue?@action=redirect&bpo=31369]: Add RegexFlag to re.__all__ and documented it. Add NOFLAG to indicate no flags being set.

bpo-45898 [https://bugs.python.org/issue?@action=redirect&bpo=45898]: ctypes no longer defines ffi_type_* symbols in cfield.c. The symbols have been provided by libffi for over a decade.

bpo-44953 [https://bugs.python.org/issue?@action=redirect&bpo=44953]: Calling operator.itemgetter objects and operator.attrgetter objects is now faster due to use of the vectorcall calling convention.

bpo-44289 [https://bugs.python.org/issue?@action=redirect&bpo=44289]: Fix an issue with is_tarfile() method when using fileobj argument: position in the fileobj was advanced forward which made it unreadable with tarfile.TarFile.open().

bpo-44011 [https://bugs.python.org/issue?@action=redirect&bpo=44011]: Reimplement SSL/TLS support in asyncio, borrow the implementation from uvloop library.

bpo-41086 [https://bugs.python.org/issue?@action=redirect&bpo=41086]: Make the configparser.ConfigParser constructor raise TypeError if the interpolation parameter is not of type configparser.Interpolation

bpo-29418 [https://bugs.python.org/issue?@action=redirect&bpo=29418]: Implement inspect.ismethodwrapper() and fix inspect.isroutine() for cases where methodwrapper is given. Patch by Hakan Çelik.

bpo-14156 [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

Documentation

bpo-42238 [https://bugs.python.org/issue?@action=redirect&bpo=42238]: Doc/tools/rstlint.py has moved to its own repository and is now packaged on PyPI as sphinx-lint.

Tests

bpo-46913 [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.

bpo-46760 [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.

bpo-46708 [https://bugs.python.org/issue?@action=redirect&bpo=46708]: Prevent default asyncio event loop policy modification warning after test_asyncio execution.

bpo-46678 [https://bugs.python.org/issue?@action=redirect&bpo=46678]: The function make_legacy_pyc in Lib/test/support/import_helper.py no longer fails when PYTHONPYCACHEPREFIX is set to a directory on a different device from where tempfiles are stored.

bpo-46623 [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.

Build

bpo-46860 [https://bugs.python.org/issue?@action=redirect&bpo=46860]: Respect --with-suffix when building on case-insensitive file systems.

bpo-46656 [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.

bpo-46656 [https://bugs.python.org/issue?@action=redirect&bpo=46656]: Building Python now requires support for floating point Not-a-Number (NaN): remove the Py_NO_NAN macro. Patch by Victor Stinner.

bpo-46640 [https://bugs.python.org/issue?@action=redirect&bpo=46640]: Building Python now requires a C99 <math.h> header file providing a NAN constant, or the __builtin_nan() built-in function. Patch by Victor Stinner.

bpo-46608 [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 is_package field to _frozen. Patch by Kumar Aditya.

bpo-40280 [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.

bpo-46430 [https://bugs.python.org/issue?@action=redirect&bpo=46430]: Intern strings in deep-frozen modules. Patch by Kumar Aditya.

Windows

bpo-46744 [https://bugs.python.org/issue?@action=redirect&bpo=46744]: The default all users install directory for ARM64 is now under the native Program Files folder, rather than Program Files (Arm) which is intended for ARM (32-bit) files.

bpo-46567 [https://bugs.python.org/issue?@action=redirect&bpo=46567]: Adds Tcl and Tk support for Windows ARM64. This also adds IDLE to the installation.

bpo-46638 [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).

IDLE

bpo-46630 [https://bugs.python.org/issue?@action=redirect&bpo=46630]: Make query dialogs on Windows start with a cursor in the entry box.

bpo-45447 [https://bugs.python.org/issue?@action=redirect&bpo=45447]: Apply IDLE syntax highlighting to .pyi files. Patch by Alex Waygood and Terry Jan Reedy.

C API

bpo-46748 [https://bugs.python.org/issue?@action=redirect&bpo=46748]: Python's public headers no longer import <stdbool.h>, leaving code that embeds/extends Python free to define bool, true and false.

bpo-46836 [https://bugs.python.org/issue?@action=redirect&bpo=46836]: Move the PyFrameObject type definition (struct _frame) to the internal C API pycore_frame.h header file. Patch by Victor Stinner.

bpo-45459 [https://bugs.python.org/issue?@action=redirect&bpo=45459]: Rename Include/buffer.h header file to Include/pybuffer.h to avoid conflicts with projects having an existing buffer.h header file. Patch by Victor Stinner.

bpo-45412 [https://bugs.python.org/issue?@action=redirect&bpo=45412]: Remove the HAVE_PY_SET_53BIT_PRECISION macro (moved to the internal C API). Patch by Victor Stinner.

bpo-46613 [https://bugs.python.org/issue?@action=redirect&bpo=46613]: Added function PyType_GetModuleByDef(), which allows access to module state when a method's defining class is not available.

Python 3.11.0 alpha 5

Release date: 2022-02-03

Core and Builtins

bpo-45773 [https://bugs.python.org/issue?@action=redirect&bpo=45773]: Remove two invalid "peephole" optimizations from the bytecode compiler.

bpo-46564 [https://bugs.python.org/issue?@action=redirect&bpo=46564]: Do not create frame objects when creating super object. Patch by Kumar Aditya.

bpo-45885 [https://bugs.python.org/issue?@action=redirect&bpo=45885]: Added more fined-grained specialization failure stats regarding the COMPARE_OP bytecode.

bpo-44977 [https://bugs.python.org/issue?@action=redirect&bpo=44977]: The delegation of int() to __trunc__() is now deprecated. Calling int(a) when type(a) implements __trunc__() but not __int__() or __index__() now raises a DeprecationWarning.

bpo-46458 [https://bugs.python.org/issue?@action=redirect&bpo=46458]: Reorder code emitted by the compiler for a try-except block so that the else block's code immediately follows the try body (without a jump). This is more optimal for the happy path.

bpo-46527 [https://bugs.python.org/issue?@action=redirect&bpo=46527]: Allow passing iterable as a keyword argument to enumerate() again. Patch by Jelle Zijlstra.

bpo-46528 [https://bugs.python.org/issue?@action=redirect&bpo=46528]: Replace several stack manipulation instructions (DUP_TOP, DUP_TOP_TWO, ROT_TWO, ROT_THREE, ROT_FOUR, and ROT_N) with new COPY and SWAP instructions.

bpo-46329 [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: PRECALL; CALL. Calls with named arguments are implemented as a sequence of three instructions: PRECALL; KW_NAMES; CALL. There are two different PRECALL instructions: PRECALL_FUNTION and PRECALL_METHOD. The latter pairs with LOAD_METHOD.

This partition into pre-call and call allows better specialization, and thus better performance ultimately.

There is no change in semantics.

bpo-46503 [https://bugs.python.org/issue?@action=redirect&bpo=46503]: Fix an assert when parsing some invalid N escape sequences in f-strings.

bpo-46431 [https://bugs.python.org/issue?@action=redirect&bpo=46431]: Improve error message on invalid calls to BaseExceptionGroup.__new__().

bpo-46476 [https://bugs.python.org/issue?@action=redirect&bpo=46476]: Fix memory leak in code objects generated by deepfreeze. Patch by Kumar Aditya.

bpo-46481 [https://bugs.python.org/issue?@action=redirect&bpo=46481]: Speed up calls to weakref.ref.__call__() by using the PEP 590 [https://peps.python.org/pep-0590/] vectorcall calling convention. Patch by Donghee Na.

bpo-46417 [https://bugs.python.org/issue?@action=redirect&bpo=46417]: Fix a race condition on setting a type __bases__ attribute: the internal function add_subclass() now gets the PyTypeObject.tp_subclasses member after calling PyWeakref_NewRef() which can trigger a garbage collection which can indirectly modify PyTypeObject.tp_subclasses. Patch by Victor Stinner.

bpo-46417 [https://bugs.python.org/issue?@action=redirect&bpo=46417]: 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.

bpo-43683 [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 YIELD_VALUE instruction.

bpo-46407 [https://bugs.python.org/issue?@action=redirect&bpo=46407]: Optimize some modulo operations in Objects/longobject.c. Patch by Jeremiah Vivian.

bpo-46409 [https://bugs.python.org/issue?@action=redirect&bpo=46409]: Add new 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 JUMP_NO_INTERRUPT bytecode that acts like JUMP_ABSOLUTE, but does not check for interrupts.

bpo-46406 [https://bugs.python.org/issue?@action=redirect&bpo=46406]: The integer division // 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 2**30.

bpo-46383 [https://bugs.python.org/issue?@action=redirect&bpo=46383]: Fix invalid signature of _zoneinfo's module_free function to resolve a crash on wasm32-emscripten platform.

bpo-46361 [https://bugs.python.org/issue?@action=redirect&bpo=46361]: Ensure that "small" integers created by int.from_bytes() and decimal.Decimal are properly cached.

bpo-46161 [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.

bpo-46028 [https://bugs.python.org/issue?@action=redirect&bpo=46028]: Fixes calculation of sys._base_executable when inside a virtual environment that uses symlinks with different binary names than the base environment provides.

bpo-46091 [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

bpo-30512 [https://bugs.python.org/issue?@action=redirect&bpo=30512]: Add CAN Socket support for NetBSD.

bpo-46045 [https://bugs.python.org/issue?@action=redirect&bpo=46045]: Do not use POSIX semaphores on NetBSD

bpo-44024 [https://bugs.python.org/issue?@action=redirect&bpo=44024]: Improve the TypeError message for non-string second arguments passed to the built-in functions getattr() and hasattr(). Patch by Géry Ogam.

Library

bpo-46624 [https://bugs.python.org/issue?@action=redirect&bpo=46624]: Restore support for non-integer arguments of random.randrange() and random.randint().

bpo-46591 [https://bugs.python.org/issue?@action=redirect&bpo=46591]: Make the IDLE doc URL on the About IDLE dialog clickable.

bpo-46565 [https://bugs.python.org/issue?@action=redirect&bpo=46565]: Remove loop variables that are leaking into modules' namespaces.

bpo-46553 [https://bugs.python.org/issue?@action=redirect&bpo=46553]: In typing.get_type_hints(), support evaluating bare stringified ClassVar annotations. Patch by Gregory Beauregard.

bpo-46544 [https://bugs.python.org/issue?@action=redirect&bpo=46544]: Don't leak x & uspace intermediate vars in textwrap.TextWrapper.

bpo-46487 [https://bugs.python.org/issue?@action=redirect&bpo=46487]: Add the get_write_buffer_limits method to asyncio.transports.WriteTransport and to the SSL transport.

bpo-45173 [https://bugs.python.org/issue?@action=redirect&bpo=45173]: Note the configparser deprecations will be removed in Python 3.12.

bpo-45162 [https://bugs.python.org/issue?@action=redirect&bpo=45162]: The deprecated unittest APIs removed in 3.11a1 have been temporarily restored to be removed in 3.12 while cleanups in external projects go in.

bpo-46539 [https://bugs.python.org/issue?@action=redirect&bpo=46539]: In typing.get_type_hints(), support evaluating stringified ClassVar and Final annotations inside Annotated. Patch by Gregory Beauregard.

bpo-46510 [https://bugs.python.org/issue?@action=redirect&bpo=46510]: Add missing test for types.TracebackType and types.FrameType. Calculate them directly from the caught exception without calling sys.exc_info().

bpo-46491 [https://bugs.python.org/issue?@action=redirect&bpo=46491]: Allow typing.Annotated to wrap typing.Final and typing.ClassVar. Patch by Gregory Beauregard.

bpo-46483 [https://bugs.python.org/issue?@action=redirect&bpo=46483]: Remove __class_getitem__() from pathlib.PurePath as this class was not supposed to be generic.

bpo-46436 [https://bugs.python.org/issue?@action=redirect&bpo=46436]: Fix command-line option -d/--directory in module http.server which is ignored when combined with command-line option --cgi. Patch by Géry Ogam.

bpo-41403 [https://bugs.python.org/issue?@action=redirect&bpo=41403]: Make mock.patch() raise a TypeError with a relevant error message on invalid arg. Previously it allowed a cryptic AttributeError to escape.

bpo-46474 [https://bugs.python.org/issue?@action=redirect&bpo=46474]: In importlib.metadata.EntryPoint.pattern, avoid potential REDoS by limiting ambiguity in consecutive whitespace.

bpo-46474 [https://bugs.python.org/issue?@action=redirect&bpo=46474]: Removed private method from importlib.metadata.Path. Sync with importlib_metadata 4.10.0.

bpo-46470 [https://bugs.python.org/issue?@action=redirect&bpo=46470]: Remove unused branch from typing._remove_dups_flatten

bpo-46469 [https://bugs.python.org/issue?@action=redirect&bpo=46469]: asyncio generic classes now return types.GenericAlias in __class_getitem__ instead of the same class.

bpo-41906 [https://bugs.python.org/issue?@action=redirect&bpo=41906]: Support passing filter instances in the filters values of handlers and loggers in the dictionary passed to logging.config.dictConfig().

bpo-46422 [https://bugs.python.org/issue?@action=redirect&bpo=46422]: Use dis.Positions in dis.Instruction instead of a regular tuple.

bpo-46434 [https://bugs.python.org/issue?@action=redirect&bpo=46434]: pdb now gracefully handles help when __doc__ is missing, for example when run with pregenerated optimized .pyc files.

bpo-43869 [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.

bpo-46414 [https://bugs.python.org/issue?@action=redirect&bpo=46414]: Add typing.reveal_type(). Patch by Jelle Zijlstra.

bpo-40280 [https://bugs.python.org/issue?@action=redirect&bpo=40280]: subprocess now imports Windows-specific imports when msvcrt module is available, and POSIX-specific imports on all other platforms. This gives a clean exception when _posixsubprocess is not available (e.g. Emscripten browser target).

bpo-40066 [https://bugs.python.org/issue?@action=redirect&bpo=40066]: IntEnum, IntFlag, and StrEnum use the mixed-in type for their str() and format() output.

bpo-46316 [https://bugs.python.org/issue?@action=redirect&bpo=46316]: Optimize pathlib.Path.iterdir() by removing an unnecessary check for special entries.

bpo-29688 [https://bugs.python.org/issue?@action=redirect&bpo=29688]: Document pathlib.Path.absolute() (which has always existed).

bpo-43012 [https://bugs.python.org/issue?@action=redirect&bpo=43012]: The pathlib module's obsolete and internal _Accessor class has been removed to prepare the terrain for upcoming enhancements to the module.

bpo-46258 [https://bugs.python.org/issue?@action=redirect&bpo=46258]: Speed up math.isqrt() for small positive integers by replacing two division steps with a lookup table.

bpo-46242 [https://bugs.python.org/issue?@action=redirect&bpo=46242]: Improve error message when creating a new enum.Enum type subclassing an existing Enum with _member_names_ using enum.Enum.__call__().

bpo-43118 [https://bugs.python.org/issue?@action=redirect&bpo=43118]: Fix a bug in inspect.signature() that was causing it to fail on some subclasses of classes with a __text_signature__ referencing module globals. Patch by Weipeng Hong.

bpo-26552 [https://bugs.python.org/issue?@action=redirect&bpo=26552]: Fixed case where failing asyncio.ensure_future() did not close the coroutine. Patch by Kumar Aditya.

bpo-21987 [https://bugs.python.org/issue?@action=redirect&bpo=21987]: Fix an issue with tarfile.TarFile.getmember() getting a directory name with a trailing slash.

bpo-46124 [https://bugs.python.org/issue?@action=redirect&bpo=46124]: Update zoneinfo to rely on importlib.resources traversable API.

bpo-46103 [https://bugs.python.org/issue?@action=redirect&bpo=46103]: Now inspect.getmembers() only gets __bases__ attribute from class type. Patch by Weipeng Hong.

bpo-46080 [https://bugs.python.org/issue?@action=redirect&bpo=46080]: Fix exception in argparse help text generation if a argparse.BooleanOptionalAction argument's default is argparse.SUPPRESS and it has help specified. Patch by Felix Fontein.

bpo-44791 [https://bugs.python.org/issue?@action=redirect&bpo=44791]: Fix substitution of ParamSpec in Concatenate with different parameter expressions. Substitution with a list of types returns now a tuple of types. Substitution with Concatenate returns now a Concatenate with concatenated lists of arguments.

Documentation

bpo-46463 [https://bugs.python.org/issue?@action=redirect&bpo=46463]: Fixes escape4chm.py script used when building the CHM documentation file

Tests

bpo-43478 [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 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.

bpo-46616 [https://bugs.python.org/issue?@action=redirect&bpo=46616]: Ensures test_importlib.test_windows cleans up registry keys after completion.

bpo-44359 [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.

bpo-46600 [https://bugs.python.org/issue?@action=redirect&bpo=46600]: Fix test_gdb.test_pycfunction() for Python built with clang -Og. Tolerate inlined functions in the gdb traceback. Patch by Victor Stinner.

bpo-46542 [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.

bpo-46576 [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.

bpo-46542 [https://bugs.python.org/issue?@action=redirect&bpo=46542]: Fix test_json tests checking for RecursionError: modify these tests to use support.infinite_recursion(). Patch by Victor Stinner.

bpo-13886 [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.

bpo-40280 [https://bugs.python.org/issue?@action=redirect&bpo=40280]: Add test.support.requires_fork() decorators to mark tests that require a working os.fork().

bpo-40280 [https://bugs.python.org/issue?@action=redirect&bpo=40280]: Add test.support.requires_subprocess() decorator to mark tests which require working subprocess module or os.spawn*. The wasm32-emscripten platform has no support for processes.

bpo-46126 [https://bugs.python.org/issue?@action=redirect&bpo=46126]: Disable 'descriptions' when running tests internally.

Build

bpo-46602 [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.

bpo-46600 [https://bugs.python.org/issue?@action=redirect&bpo=46600]: Fix the test checking if the C compiler supports -Og option in the ./configure script to also use -Og on clang which supports it. Patch by Victor Stinner.

bpo-38472 [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.

bpo-46513 [https://bugs.python.org/issue?@action=redirect&bpo=46513]: configure no longer uses AC_C_CHAR_UNSIGNED macro and pyconfig.h no longer defines reserved symbol __CHAR_UNSIGNED__.

bpo-46471 [https://bugs.python.org/issue?@action=redirect&bpo=46471]: Use global singletons for single byte bytes objects in deepfreeze.

bpo-46443 [https://bugs.python.org/issue?@action=redirect&bpo=46443]: Deepfreeze now uses cached small integers as it saves some space for common small integers.

bpo-46429 [https://bugs.python.org/issue?@action=redirect&bpo=46429]: Merge all deep-frozen files into one for space savings. Patch by Kumar Aditya.

bpo-45569 [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 --enable-big-digits=15 option to the configure script, or by defining PYLONG_BITS_IN_DIGIT in pyconfig.h.

bpo-45925 [https://bugs.python.org/issue?@action=redirect&bpo=45925]: Update Windows installer to use SQLite 3.37.2.

bpo-43112 [https://bugs.python.org/issue?@action=redirect&bpo=43112]: Detect musl libc as a separate SOABI (tagged as linux-musl).

Windows

bpo-33125 [https://bugs.python.org/issue?@action=redirect&bpo=33125]: The traditional EXE/MSI based installer for Windows is now available for ARM64

bpo-46362 [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.

bpo-44934 [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 PATH instead of at the start.

macOS

bpo-45925 [https://bugs.python.org/issue?@action=redirect&bpo=45925]: Update macOS installer to SQLite 3.37.2.

IDLE

bpo-45296 [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.

C API

bpo-40170 [https://bugs.python.org/issue?@action=redirect&bpo=40170]: Remove the PyHeapType_GET_MEMBERS() macro. It was exposed in the public C API by mistake, it must only be used by Python internally. Use the PyTypeObject.tp_members member instead. Patch by Victor Stinner.

bpo-40170 [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.

bpo-46433 [https://bugs.python.org/issue?@action=redirect&bpo=46433]: The internal function _PyType_GetModuleByDef now correctly handles inheritance patterns involving static types.

bpo-45459 [https://bugs.python.org/issue?@action=redirect&bpo=45459]: Py_buffer and various Py_buffer related functions are now part of the limited API and stable ABI.

bpo-14916 [https://bugs.python.org/issue?@action=redirect&bpo=14916]: Fixed bug in the tokenizer that prevented PyRun_InteractiveOne from parsing from the provided FD.

Python 3.11.0 alpha 4

Release date: 2022-01-13

Core and Builtins

bpo-46070 [https://bugs.python.org/issue?@action=redirect&bpo=46070]: Py_EndInterpreter() now explicitly untracks all objects currently tracked by the GC. Previously, if an object was used later by another interpreter, calling PyObject_GC_UnTrack() on the object crashed if the previous or the next object of the PyGC_Head structure became a dangling pointer. Patch by Victor Stinner.

bpo-46347 [https://bugs.python.org/issue?@action=redirect&bpo=46347]: Fix memory leak in PyEval_EvalCodeEx.

bpo-46339 [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

bpo-46331 [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.

bpo-46314 [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.

bpo-46289 [https://bugs.python.org/issue?@action=redirect&bpo=46289]: ASDL declaration of FormattedValue has changed to reflect conversion field is not optional.

bpo-46297 [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.

bpo-46237 [https://bugs.python.org/issue?@action=redirect&bpo=46237]: Fix the line number of tokenizer errors inside f-strings. Patch by Pablo Galindo.

bpo-46263 [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.

bpo-46006 [https://bugs.python.org/issue?@action=redirect&bpo=46006]: Fix a regression when a type method like __init__() is modified in a subinterpreter. Fix a regression in _PyUnicode_EqualToASCIIId() and type 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.

bpo-45923 [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.

bpo-46208 [https://bugs.python.org/issue?@action=redirect&bpo=46208]: Fix the regression of os.path.normpath("A/../../B") not returning expected "../B" but "B".

bpo-46240 [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

bpo-46009 [https://bugs.python.org/issue?@action=redirect&bpo=46009]: Remove the GEN_START opcode.

bpo-46235 [https://bugs.python.org/issue?@action=redirect&bpo=46235]: Certain sequence multiplication operations like [0] * 1_000 are now faster due to reference-counting optimizations. Patch by Dennis Sweeney.

bpo-46221 [https://bugs.python.org/issue?@action=redirect&bpo=46221]: PREP_RERAISE_STAR no longer pushes lasti to the stack.

bpo-46202 [https://bugs.python.org/issue?@action=redirect&bpo=46202]: Remove POP_EXCEPT_AND_RERAISE and replace it by an equivalent sequence of other opcodes.

bpo-46085 [https://bugs.python.org/issue?@action=redirect&bpo=46085]: Fix iterator cache mechanism of OrderedDict.

bpo-46055 [https://bugs.python.org/issue?@action=redirect&bpo=46055]: Speed up shifting operation involving integers less than PyLong_BASE. Patch by Xinhang Xu.

bpo-46110 [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

bpo-46107 [https://bugs.python.org/issue?@action=redirect&bpo=46107]: Fix bug where ExceptionGroup.split() and ExceptionGroup.subgroup() did not copy the exception group's __note__ field to the parts.

bpo-45711 [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 exc_value field, exc_type and exc_traceback have been removed as their values can be derived from exc_value.

bpo-44525 [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 CALL_FUNCTION, CALL_FUNCTION_KW, CALL_METHOD and CALL_METHOD_KW.

Adds CALL_NO_KW and CALL_KW call instructions, and PRECALL_METHOD prefix for pairing with LOAD_METHOD.

bpo-46039 [https://bugs.python.org/issue?@action=redirect&bpo=46039]: Remove the YIELD_FROM instruction and replace it with the SEND instruction which performs the same operation, but without the loop.

bpo-45635 [https://bugs.python.org/issue?@action=redirect&bpo=45635]: The code called from _PyErr_Display() was refactored to improve error handling. It now exits immediately upon an unrecoverable error.

bpo-46054 [https://bugs.python.org/issue?@action=redirect&bpo=46054]: Fix parser error when parsing non-utf8 characters in source files. Patch by Pablo Galindo.

bpo-46042 [https://bugs.python.org/issue?@action=redirect&bpo=46042]: Improve the location of the caret in SyntaxError exceptions emitted by the symbol table. Patch by Pablo Galindo.

bpo-46049 [https://bugs.python.org/issue?@action=redirect&bpo=46049]: Ensure ._pth files work as intended on platforms other than Windows.

bpo-46048 [https://bugs.python.org/issue?@action=redirect&bpo=46048]: Fixes parsing of ._pth files on startup so that single-character paths are correctly read.

bpo-37971 [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.

bpo-46031 [https://bugs.python.org/issue?@action=redirect&bpo=46031]: Add POP_JUMP_IF_NOT_NONE and POP_JUMP_IF_NONE opcodes to speed up conditional jumps.

bpo-45654 [https://bugs.python.org/issue?@action=redirect&bpo=45654]: Deepfreeze runpy, patch by Kumar Aditya.

bpo-46025 [https://bugs.python.org/issue?@action=redirect&bpo=46025]: Fix a crash in the atexit module involving functions that unregister themselves before raising exceptions. Patch by Pablo Galindo.

bpo-46000 [https://bugs.python.org/issue?@action=redirect&bpo=46000]: Improve compatibility of the curses module with NetBSD curses.

bpo-44525 [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 range(x), list(x), and specifically type(obj).

bpo-42918 [https://bugs.python.org/issue?@action=redirect&bpo=42918]: Fix bug where the built-in compile() function did not always raise a SyntaxError when passed multiple statements in 'single' mode. Patch by Weipeng Hong.

bpo-45953 [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.

bpo-45292 [https://bugs.python.org/issue?@action=redirect&bpo=45292]: Complete the PEP 654 [https://peps.python.org/pep-0654/] implementation: add except*.

bpo-43413 [https://bugs.python.org/issue?@action=redirect&bpo=43413]: Revert changes in set.__init__. Subclass of set needs to define a __init__() method if it defines a __new__() method with additional keyword parameters.

bpo-43931 [https://bugs.python.org/issue?@action=redirect&bpo=43931]: Added the Py_Version constant which bears the same value as PY_VERSION_HEX. Patch by Gabriele N. Tornetta.

Library

bpo-46342 [https://bugs.python.org/issue?@action=redirect&bpo=46342]: The @typing.final decorator now sets the __final__ attribute on the decorated object to allow runtime introspection. Patch by Jelle Zijlstra.

bpo-46328 [https://bugs.python.org/issue?@action=redirect&bpo=46328]: Added the sys.exception() method which returns the active exception instance.

bpo-46307 [https://bugs.python.org/issue?@action=redirect&bpo=46307]: Add string.Template.is_valid() and string.Template.get_identifiers() methods.

bpo-46306 [https://bugs.python.org/issue?@action=redirect&bpo=46306]: Assume that types.CodeType always has types.CodeType.co_firstlineno in doctest.

bpo-40479 [https://bugs.python.org/issue?@action=redirect&bpo=40479]: Fix hashlib usedforsecurity option to work correctly with OpenSSL 3.0.0 in FIPS mode.

bpo-46070 [https://bugs.python.org/issue?@action=redirect&bpo=46070]: Fix possible segfault when importing the asyncio module from different sub-interpreters in parallel. Patch by Erlend E. Aasland.

bpo-46244 [https://bugs.python.org/issue?@action=redirect&bpo=46244]: Removed __slots__ from typing.ParamSpec and typing.TypeVar. They served no purpose. Patch by Arie Bovenberg.

bpo-46278 [https://bugs.python.org/issue?@action=redirect&bpo=46278]: Reflect context argument in AbstractEventLoop.call_*() methods. Loop implementations already support it.

bpo-46269 [https://bugs.python.org/issue?@action=redirect&bpo=46269]: Remove special-casing of __new__ in enum.Enum.__dir__().

bpo-46266 [https://bugs.python.org/issue?@action=redirect&bpo=46266]: Improve day constants in calendar.

Now all constants (MONDAY ... SUNDAY) are documented, tested, and added to __all__.

bpo-46257 [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.

bpo-41011 [https://bugs.python.org/issue?@action=redirect&bpo=41011]: Added two new variables to pyvenv.cfg which is generated by venv module: executable for the executable and command for the command line used to create the environment.

bpo-46239 [https://bugs.python.org/issue?@action=redirect&bpo=46239]: Improve error message when importing asyncio.windows_events on non-Windows.

bpo-46238 [https://bugs.python.org/issue?@action=redirect&bpo=46238]: Reuse _winapi constants in asyncio.windows_events.

bpo-46222 [https://bugs.python.org/issue?@action=redirect&bpo=46222]: Adding SF_NOCACHE sendfile constant for FreeBSD for the posixmodule.

bpo-37295 [https://bugs.python.org/issue?@action=redirect&bpo=37295]: Add fast path for 0 <= k <= n <= 67 for math.comb().

bpo-46176 [https://bugs.python.org/issue?@action=redirect&bpo=46176]: Adding the MAP_STACK constant for the mmap module.

bpo-43424 [https://bugs.python.org/issue?@action=redirect&bpo=43424]: Deprecate webbrowser.MacOSXOSAScript._name and use name instead.

bpo-45321 [https://bugs.python.org/issue?@action=redirect&bpo=45321]: Added missing error codes to module xml.parsers.expat.errors.

bpo-46125 [https://bugs.python.org/issue?@action=redirect&bpo=46125]: Refactor tests to test traversable API directly. Includes changes from importlib 5.4.0.

bpo-46118 [https://bugs.python.org/issue?@action=redirect&bpo=46118]: Moved importlib.resources and its related functionality to a package.

bpo-37578 [https://bugs.python.org/issue?@action=redirect&bpo=37578]: Add include_hidden parameter to glob() and iglob() to match hidden files and directories when using special characters like *, **, ? and [].

bpo-20369 [https://bugs.python.org/issue?@action=redirect&bpo=20369]: concurrent.futures.wait() no longer blocks forever when given duplicate Futures. Patch by Kumar Aditya.

bpo-46105 [https://bugs.python.org/issue?@action=redirect&bpo=46105]: Honor spec when generating requirement specs with urls and extras (importlib_metadata 4.8.3).

bpo-44893 [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.

bpo-22815 [https://bugs.python.org/issue?@action=redirect&bpo=22815]: Print unexpected successes together with failures and errors in summary in unittest.TextTestResult.

bpo-22047 [https://bugs.python.org/issue?@action=redirect&bpo=22047]: Calling add_argument_group() on an argument group is deprecated. Calling add_argument_group() or 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.

bpo-26952 [https://bugs.python.org/issue?@action=redirect&bpo=26952]: argparse raises ValueError with clear message when trying to render usage for an empty mutually exclusive group. Previously it raised a cryptic IndexError.

bpo-45615 [https://bugs.python.org/issue?@action=redirect&bpo=45615]: Functions in the traceback module raise TypeError rather than AttributeError when an exception argument is not of type BaseException.

bpo-16594 [https://bugs.python.org/issue?@action=redirect&bpo=16594]: Add allow allow_reuse_port flag in socketserver.

bpo-27718 [https://bugs.python.org/issue?@action=redirect&bpo=27718]: Fix help for the signal module. Some functions (e.g. signal() and getsignal()) were omitted.

bpo-46032 [https://bugs.python.org/issue?@action=redirect&bpo=46032]: The registry() method of 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. typing.List[int]) or caused an error at calling time (e.g. list[int]).

bpo-46014 [https://bugs.python.org/issue?@action=redirect&bpo=46014]: Add ability to use typing.Union and types.UnionType as dispatch argument to functools.singledispatch. Patch provided by Yurii Karabas.

bpo-27062 [https://bugs.python.org/issue?@action=redirect&bpo=27062]: Add __all__ to inspect, patch by Kumar Aditya.

bpo-46018 [https://bugs.python.org/issue?@action=redirect&bpo=46018]: Ensure that math.expm1() does not raise on underflow.

bpo-46016 [https://bugs.python.org/issue?@action=redirect&bpo=46016]: Adding F_DUP2FD and F_DUP2FD_CLOEXEC constants from FreeBSD into the fcntl module.

bpo-45755 [https://bugs.python.org/issue?@action=redirect&bpo=45755]: typing generic aliases now reveal the class attributes of the original generic class when passed to dir(). This was the behavior up to Python 3.6, but was changed in 3.7-3.9.

bpo-45874 [https://bugs.python.org/issue?@action=redirect&bpo=45874]: The empty query string, consisting of no query arguments, is now handled correctly in urllib.parse.parse_qsl. This caused problems before when strict parsing was enabled.

bpo-44674 [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.

bpo-23882 [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.

bpo-25066 [https://bugs.python.org/issue?@action=redirect&bpo=25066]: Added a __repr__() method to multiprocessing.Event objects, patch by Kumar Aditya.

bpo-45643 [https://bugs.python.org/issue?@action=redirect&bpo=45643]: Added signal.SIGSTKFLT on platforms where this signal is defined.

bpo-44092 [https://bugs.python.org/issue?@action=redirect&bpo=44092]: Fetch across rollback no longer raises InterfaceError. Instead we leave it to the SQLite library to handle these cases. Patch by Erlend E. Aasland.

bpo-42413 [https://bugs.python.org/issue?@action=redirect&bpo=42413]: Replace concurrent.futures.TimeoutError and asyncio.TimeoutError with builtin TimeoutError, keep these names as deprecated aliases.

Documentation

bpo-46196 [https://bugs.python.org/issue?@action=redirect&bpo=46196]: Document method cmd.Cmd.columnize().

bpo-46120 [https://bugs.python.org/issue?@action=redirect&bpo=46120]: State that | is preferred for readability over Union in the typing docs.

bpo-46109 [https://bugs.python.org/issue?@action=redirect&bpo=46109]: Extracted importlib.resources and importlib.resources.abc documentation into separate files.

bpo-19737 [https://bugs.python.org/issue?@action=redirect&bpo=19737]: Update the documentation for the globals() function.

Tests

bpo-46296 [https://bugs.python.org/issue?@action=redirect&bpo=46296]: Add a test case for enum with _use_args_ == True and _member_type_ == object.

bpo-46205 [https://bugs.python.org/issue?@action=redirect&bpo=46205]: Fix hang in runtest_mp due to race condition

bpo-46263 [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.

bpo-46262 [https://bugs.python.org/issue?@action=redirect&bpo=46262]: Cover ValueError path in tests for enum.Flag._missing_().

bpo-46150 [https://bugs.python.org/issue?@action=redirect&bpo=46150]: Now fakename in test_pathlib.PosixPathTest.test_expanduser is checked to be non-existent.

bpo-46129 [https://bugs.python.org/issue?@action=redirect&bpo=46129]: Rewrite asyncio.locks tests with unittest.IsolatedAsyncioTestCase usage.

bpo-23819 [https://bugs.python.org/issue?@action=redirect&bpo=23819]: Fixed asyncio tests in python optimized mode. Patch by Kumar Aditya.

bpo-46114 [https://bugs.python.org/issue?@action=redirect&bpo=46114]: Fix test case for OpenSSL 3.0.1 version. OpenSSL 3.0 uses 0xMNN00PP0L.

Build

bpo-44133 [https://bugs.python.org/issue?@action=redirect&bpo=44133]: When Python is configured with --without-static-libpython, the Python static library (libpython.a) is no longer built. Patch by Victor Stinner.

bpo-44133 [https://bugs.python.org/issue?@action=redirect&bpo=44133]: When Python is built without --enable-shared, the 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 Py_FrozenMain() function. Patch by Victor Stinner.

bpo-40280 [https://bugs.python.org/issue?@action=redirect&bpo=40280]: The configure script has a new option --with-emscripten-target to select browser or node as Emscripten build target.

bpo-46315 [https://bugs.python.org/issue?@action=redirect&bpo=46315]: Added and fixed #ifdef HAVE_FEATURE checks for functionality that is not available on WASI platform.

bpo-45723 [https://bugs.python.org/issue?@action=redirect&bpo=45723]: Fixed a regression in configure check for select.epoll().

bpo-46263 [https://bugs.python.org/issue?@action=redirect&bpo=46263]: configure no longer sets MULTIARCH on FreeBSD platforms.

bpo-46106 [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.

bpo-46088 [https://bugs.python.org/issue?@action=redirect&bpo=46088]: Automatically detect or install bootstrap Python runtime when building from Visual Studio.

bpo-46072 [https://bugs.python.org/issue?@action=redirect&bpo=46072]: Add a --with-pystats configure option to turn on internal statistics gathering.

bpo-40280 [https://bugs.python.org/issue?@action=redirect&bpo=40280]: A new directory Tools/wasm contains WebAssembly-related helpers like config.site override for wasm32-emscripten, wasm assets generator to bundle the stdlib, and a README.

bpo-46023 [https://bugs.python.org/issue?@action=redirect&bpo=46023]: makesetup no longer builds extensions that have been marked as disabled. This allows users to disable modules in Modules/Setup.local.

bpo-45949 [https://bugs.python.org/issue?@action=redirect&bpo=45949]: Use pure Python freeze_module for all but importlib bootstrap files. --with-freeze-module configure option is no longer needed for cross builds.

Windows

bpo-46217 [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.

macOS

bpo-40477 [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.

C API

bpo-46236 [https://bugs.python.org/issue?@action=redirect&bpo=46236]: Fix a bug in PyFunction_GetAnnotations() that caused it to return a tuple instead of a dict.

bpo-46140 [https://bugs.python.org/issue?@action=redirect&bpo=46140]: PyBuffer_GetPointer(), PyBuffer_FromContiguous(), PyBuffer_ToContiguous() and PyMemoryView_FromBuffer() now take buffer info by const Py_buffer * instead of Py_buffer *, as they do not need mutability. PyBuffer_FromContiguous() also now takes the source buffer as const void *, and similarly PyBuffer_GetPointer() takes the strides as const Py_ssize_t *.

bpo-45855 [https://bugs.python.org/issue?@action=redirect&bpo=45855]: Document that the no_block argument to PyCapsule_Import() is a no-op now.

bpo-45855 [https://bugs.python.org/issue?@action=redirect&bpo=45855]: Replaced deprecated usage of PyImport_ImportModuleNoBlock() with PyImport_ImportModule() in stdlib modules. Patch by Kumar Aditya.

bpo-46007 [https://bugs.python.org/issue?@action=redirect&bpo=46007]: The 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.

Python 3.11.0 alpha 3

Release date: 2021-12-08

Core and Builtins

bpo-46009 [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 gen_func().send(0) is equivalent to gen_func().throw(TypeError(...) which exhausts the generator. In 3.10.2 onward, the behavior has been reverted to that of 3.9.

bpo-46004 [https://bugs.python.org/issue?@action=redirect&bpo=46004]: Fix the SyntaxError location for errors involving for loops with invalid targets. Patch by Pablo Galindo

bpo-45711 [https://bugs.python.org/issue?@action=redirect&bpo=45711]: _PyErr_ChainStackItem() no longer normalizes exc_info (including setting the traceback on the exception instance) because exc_info is always normalized.

bpo-45607 [https://bugs.python.org/issue?@action=redirect&bpo=45607]: The __note__ field was added to BaseException. It is None by default but can be set to a string which is added to the exception's traceback.

bpo-45947 [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.

bpo-45915 [https://bugs.python.org/issue?@action=redirect&bpo=45915]: is_valid_fd now uses faster fcntl(fd, F_GETFD) on Linux, macOS, and Windows.

bpo-44530 [https://bugs.python.org/issue?@action=redirect&bpo=44530]: Reverts a change to the code.__new__ audit event from an earlier prerelease.

bpo-42268 [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

bpo-45711 [https://bugs.python.org/issue?@action=redirect&bpo=45711]: The three values of exc_info are now always consistent with each other. In particular, the type and traceback fields are now derived from the exception instance. This impacts the return values of sys.exc_info() and PyErr_GetExcInfo() if the exception instance is modified while the exception is handled, as well as PyErr_SetExcInfo(), which now ignores the type and traceback arguments provided to it.

bpo-45727 [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

bpo-45885 [https://bugs.python.org/issue?@action=redirect&bpo=45885]: Specialized the COMPARE_OP opcode using the PEP 659 machinery.

bpo-45786 [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.

bpo-45614 [https://bugs.python.org/issue?@action=redirect&bpo=45614]: Fix traceback display for exceptions with invalid module name.

bpo-45813 [https://bugs.python.org/issue?@action=redirect&bpo=45813]: Fix crash when calling coro.cr_frame.clear() after coroutine has been freed.

bpo-45811 [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

bpo-45848 [https://bugs.python.org/issue?@action=redirect&bpo=45848]: Allow the parser to obtain error lines directly from encoded files. Patch by Pablo Galindo

bpo-45709 [https://bugs.python.org/issue?@action=redirect&bpo=45709]: Restore behavior from 3.10 when tracing an exception raised within a with statement.

bpo-44525 [https://bugs.python.org/issue?@action=redirect&bpo=44525]: Adds new COPY_FREE_VARS opcode, to make copying of free variables from function to frame explicit. Helps optimization of calls to Python function.

bpo-45829 [https://bugs.python.org/issue?@action=redirect&bpo=45829]: Specialize BINARY_SUBSCR for classes with a __getitem__ method implemented in Python

bpo-45826 [https://bugs.python.org/issue?@action=redirect&bpo=45826]: Fixed a crash when calling .with_traceback(None) on NameError. This occurs internally in unittest.TestCase.assertRaises().

bpo-45822 [https://bugs.python.org/issue?@action=redirect&bpo=45822]: Fixed a bug in the parser that was causing it to not respect PEP 263 [https://peps.python.org/pep-0263/] coding cookies when no flags are provided. Patch by Pablo Galindo

bpo-45820 [https://bugs.python.org/issue?@action=redirect&bpo=45820]: Fix a segfault when the parser fails without reading any input. Patch by Pablo Galindo

bpo-45636 [https://bugs.python.org/issue?@action=redirect&bpo=45636]: Simplify the implementation of BINARY_OP by indexing into an array of function pointers (rather than switching on the oparg).

bpo-42540 [https://bugs.python.org/issue?@action=redirect&bpo=42540]: Fix crash when os.fork() is called with an active non-default memory allocator.

bpo-45738 [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.

bpo-45636 [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.

bpo-45753 [https://bugs.python.org/issue?@action=redirect&bpo=45753]: Make recursion checks a bit more efficient by tracking amount of calls left before overflow.

bpo-45773 [https://bugs.python.org/issue?@action=redirect&bpo=45773]: Fix a compiler hang when attempting to optimize certain jump patterns.

bpo-45764 [https://bugs.python.org/issue?@action=redirect&bpo=45764]: The parser now gives a better error message when leaving out the opening parenthesis ( after a def-statement:

>>> def f:
  File "<stdin>", line 1
    def f:
         ^
SyntaxError: expected '('

bpo-45609 [https://bugs.python.org/issue?@action=redirect&bpo=45609]: Specialized the STORE_SUBSCR opcode using the PEP 659 machinery.

bpo-45636 [https://bugs.python.org/issue?@action=redirect&bpo=45636]: Replace all numeric BINARY_* and INPLACE_* instructions with a single BINARY_OP implementation.

bpo-45582 [https://bugs.python.org/issue?@action=redirect&bpo=45582]: Path calculation (known as getpath) has been reimplemented as a frozen Python module. This should have no visible impact, but may affect calculation of all paths referenced in sys and sysconfig.

bpo-45450 [https://bugs.python.org/issue?@action=redirect&bpo=45450]: Improve the syntax error message for parenthesized arguments. Patch by Pablo Galindo.

Library

bpo-27946 [https://bugs.python.org/issue?@action=redirect&bpo=27946]: Fix possible crash when getting an attribute of xml.etree.ElementTree.Element simultaneously with replacing the attrib dict.

bpo-45711 [https://bugs.python.org/issue?@action=redirect&bpo=45711]: Make asyncio normalize exceptions as soon as they are captured with PyErr_Fetch(), and before they are stored as an exc_info triplet. This brings asyncio in line with the rest of the codebase, where an exc_info triplet is always normalized.

bpo-23819 [https://bugs.python.org/issue?@action=redirect&bpo=23819]: Replaced asserts with exceptions in asyncio, patch by Kumar Aditya.

bpo-13236 [https://bugs.python.org/issue?@action=redirect&bpo=13236]: unittest.TextTestResult and unittest.TextTestRunner flush now the output stream more often.

bpo-45917 [https://bugs.python.org/issue?@action=redirect&bpo=45917]: Added math.exp2():, which returns 2 raised to the power of x.

bpo-37658 [https://bugs.python.org/issue?@action=redirect&bpo=37658]: Fix issue when on certain conditions asyncio.wait_for() may allow a coroutine to complete successfully, but fail to return the result, potentially causing memory leaks or other issues.

bpo-45876 [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

bpo-44649 [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.

bpo-45803 [https://bugs.python.org/issue?@action=redirect&bpo=45803]: Added missing kw_only parameter to dataclasses.make_dataclass().

bpo-45837 [https://bugs.python.org/issue?@action=redirect&bpo=45837]: The turtle.RawTurtle.settiltangle() is deprecated since Python 3.1, it now emits a deprecation warning and will be removed in Python 3.13.

Use turtle.RawTurtle.tiltangle() instead.

turtle.RawTurtle.tiltangle() was earlier incorrectly marked as deprecated, its docstring has been corrected.

Patch by Hugo van Kemenade.

bpo-45831 [https://bugs.python.org/issue?@action=redirect&bpo=45831]: 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.

bpo-45828 [https://bugs.python.org/issue?@action=redirect&bpo=45828]: sqlite C callbacks now use unraisable exceptions if callback tracebacks are enabled. Patch by Erlend E. Aasland.

bpo-41735 [https://bugs.python.org/issue?@action=redirect&bpo=41735]: Fix thread lock in zlib.Decompress.flush() method before PyObject_GetBuffer.

bpo-45235 [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.

bpo-45754 [https://bugs.python.org/issue?@action=redirect&bpo=45754]: Fix a regression in Python 3.11a1 and 3.11a2 where sqlite3 incorrectly would use SQLITE_LIMIT_LENGTH when checking SQL statement lengths. Now, SQLITE_LIMIT_SQL_LENGTH is used. Patch by Erlend E. Aasland.

bpo-45766 [https://bugs.python.org/issue?@action=redirect&bpo=45766]: Added proportional option to statistics.linear_regression().

bpo-45765 [https://bugs.python.org/issue?@action=redirect&bpo=45765]: In importlib.metadata, fix distribution discovery for an empty path.

bpo-45757 [https://bugs.python.org/issue?@action=redirect&bpo=45757]: Fix bug where dis produced an incorrect oparg when EXTENDED_ARG is followed by an opcode that does not use its argument.

bpo-45644 [https://bugs.python.org/issue?@action=redirect&bpo=45644]: In-place JSON file formatting using python3 -m json.tool infile infile now works correctly, previously it left the file empty. Patch by Chris Wesseling.

bpo-45703 [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 sys.path location while the program is running, calling the importlib.invalidate_caches() function will now also guarantee the new module is noticed.

bpo-45535 [https://bugs.python.org/issue?@action=redirect&bpo=45535]: Improve output of dir() with Enums.

bpo-45664 [https://bugs.python.org/issue?@action=redirect&bpo=45664]: Fix types.resolve_bases() and types.new_class() for types.GenericAlias instance as a base.

bpo-45663 [https://bugs.python.org/issue?@action=redirect&bpo=45663]: Fix dataclasses.is_dataclass() for dataclasses which are subclasses of types.GenericAlias.

bpo-45662 [https://bugs.python.org/issue?@action=redirect&bpo=45662]: Fix the repr of dataclasses.InitVar with a type alias to the built-in class, e.g. InitVar[list[int]].

bpo-43137 [https://bugs.python.org/issue?@action=redirect&bpo=43137]: Launch GNOME web browsers via gio tool instead of obsolete gvfs-open

bpo-45429 [https://bugs.python.org/issue?@action=redirect&bpo=45429]: On Windows, time.sleep() now uses a waitable timer which supports high-resolution timers. Patch by Donghee Na and Eryk Sun.

bpo-37295 [https://bugs.python.org/issue?@action=redirect&bpo=37295]: Optimize math.comb() and math.perm().

bpo-45514 [https://bugs.python.org/issue?@action=redirect&bpo=45514]: Deprecated legacy functions in importlib.resources.

bpo-45507 [https://bugs.python.org/issue?@action=redirect&bpo=45507]: Add tests for truncated/missing trailers in gzip.decompress implementation.

bpo-45359 [https://bugs.python.org/issue?@action=redirect&bpo=45359]: Implement PEP 585 [https://peps.python.org/pep-0585/] for graphlib.TopologicalSorter.

bpo-44733 [https://bugs.python.org/issue?@action=redirect&bpo=44733]: Add max_tasks_per_child to 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.

bpo-28806 [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.

bpo-43498 [https://bugs.python.org/issue?@action=redirect&bpo=43498]: Avoid a possible "RuntimeError: dictionary changed size during iteration" when adjusting the process count of ProcessPoolExecutor.

bpo-42158 [https://bugs.python.org/issue?@action=redirect&bpo=42158]: Add MIME types for N-quads, N-triples, Notation3 and TriG to mimetypes.

bpo-30533 [https://bugs.python.org/issue?@action=redirect&bpo=30533]: Add inspect.getmembers_static() , it return all members without triggering dynamic lookup via the descriptor protocol. Patch by Weipeng Hong.

Documentation

bpo-42238 [https://bugs.python.org/issue?@action=redirect&bpo=42238]: make -C Doc suspicious will be removed soon in favor of make -C Doc check, mark it as deprecated.

bpo-45840 [https://bugs.python.org/issue?@action=redirect&bpo=45840]: Improve cross-references in the documentation for the data model.

bpo-45640 [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.

bpo-45788 [https://bugs.python.org/issue?@action=redirect&bpo=45788]: Link doc for sys.prefix to sysconfig doc on installation paths.

bpo-45772 [https://bugs.python.org/issue?@action=redirect&bpo=45772]: socket.socket documentation is corrected to a class from a function.

bpo-45392 [https://bugs.python.org/issue?@action=redirect&bpo=45392]: Update the docstring of the type built-in to remove a redundant line and to mention keyword arguments for the constructor.

bpo-45250 [https://bugs.python.org/issue?@action=redirect&bpo=45250]: Update the documentation to note that CPython does not consistently require iterators to define __iter__.

bpo-25381 [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.

bpo-43905 [https://bugs.python.org/issue?@action=redirect&bpo=43905]: Expanded astuple() and asdict() docs, warning about deepcopy being applied and providing a workaround.

Tests

bpo-45695 [https://bugs.python.org/issue?@action=redirect&bpo=45695]: Out-of-tree builds with a read-only source directory are now tested by CI.

bpo-19460 [https://bugs.python.org/issue?@action=redirect&bpo=19460]: Add new Test for Lib/email/mime/nonmultipart.py::MIMENonMultipart.

bpo-45835 [https://bugs.python.org/issue?@action=redirect&bpo=45835]: Fix race condition in test_queue tests with multiple "feeder" threads.

bpo-45783 [https://bugs.python.org/issue?@action=redirect&bpo=45783]: The test for the freeze tool now handles file moves and deletions.

bpo-45745 [https://bugs.python.org/issue?@action=redirect&bpo=45745]: Remove the --findleaks command line option of regrtest: use the --fail-env-changed option instead. Since Python 3.7, it was a deprecated alias to the --fail-env-changed option.

bpo-45701 [https://bugs.python.org/issue?@action=redirect&bpo=45701]: Add tests with tuple type with functools.lru_cache() to test_functools.

Build

bpo-44035 [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.

bpo-45950 [https://bugs.python.org/issue?@action=redirect&bpo=45950]: The build system now uses a _bootstrap_python interpreter for freezing and deepfreezing again. To speed up build process the build tools _bootstrap_python and _freeze_module are no longer build with LTO.

bpo-45881 [https://bugs.python.org/issue?@action=redirect&bpo=45881]: The configure script now accepts --with-build-python and --with-freeze-module options to make cross compiling easier.

bpo-40280 [https://bugs.python.org/issue?@action=redirect&bpo=40280]: Emscripten platform now uses .wasm suffix by default.

bpo-40280 [https://bugs.python.org/issue?@action=redirect&bpo=40280]: Disable unusable core extension modules on WASM/Emscripten targets.

bpo-40280 [https://bugs.python.org/issue?@action=redirect&bpo=40280]: configure now checks for socket shutdown function. The check makes it possible to disable SYS_shutdown with ac_cv_func_shutdown=no in CONFIG_SITE.

bpo-40280 [https://bugs.python.org/issue?@action=redirect&bpo=40280]: configure now checks for functions fork1, getegid, geteuid, getgid, getppid, getuid, opendir, pipe, system, wait, ttyname.

bpo-33393 [https://bugs.python.org/issue?@action=redirect&bpo=33393]: Update config.guess to 2021-06-03 and config.sub to 2021-08-14. Makefile now has an update-config target to make updating more convenient.

bpo-45866 [https://bugs.python.org/issue?@action=redirect&bpo=45866]: 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.

bpo-40280 [https://bugs.python.org/issue?@action=redirect&bpo=40280]: configure now accepts machine wasm32 or wasm64 and OS wasi or emscripten for cross building, e.g. wasm32-unknown-emscripten, wasm32-wasi, or wasm32-unknown-wasi.

bpo-41498 [https://bugs.python.org/issue?@action=redirect&bpo=41498]: Python now compiles on platforms without sigset_t. Several functions in signal are not available when sigset_t is missing.

Based on patch by Roman Yurchak for pyodide.

bpo-45881 [https://bugs.python.org/issue?@action=redirect&bpo=45881]: setup.py now uses CC from environment first to discover multiarch and cross compile paths.

bpo-45886 [https://bugs.python.org/issue?@action=redirect&bpo=45886]: The _freeze_module program path can now be overridden on the command line, e.g. make FREEZE_MODULE=../x86_64/Program/_freeze_module.

bpo-45873 [https://bugs.python.org/issue?@action=redirect&bpo=45873]: Get rid of the _bootstrap_python build step. The deepfreeze.py script is now run using $(PYTHON_FOR_REGEN) which can be Python 3.7 or newer (on Windows, 3.8 or newer).

bpo-45847 [https://bugs.python.org/issue?@action=redirect&bpo=45847]: Port builtin hashlib extensions to PY_STDLIB_MOD macro and addext().

bpo-45723 [https://bugs.python.org/issue?@action=redirect&bpo=45723]: Add autoconf helpers for saving and restoring environment variables:

SAVE_ENV: Save $CFLAGS, $LDFLAGS, $LIBS, and $CPPFLAGS.

RESTORE_ENV: Restore $CFLAGS, $LDFLAGS, $LIBS, and $CPPFLAGS.

WITH_SAVE_ENV([SCRIPT]): Run SCRIPT wrapped with SAVE_ENV and RESTORE_ENV.

Patch by Erlend E. Aasland.

bpo-45573 [https://bugs.python.org/issue?@action=redirect&bpo=45573]: Mandatory core modules, that are required to bootstrap Python, are now in Modules/Setup.bootstrap.

bpo-45573 [https://bugs.python.org/issue?@action=redirect&bpo=45573]: configure now creates Modules/Setup.stdlib with conditionally enabled/disabled extension module lines. The file is not used, yet.

bpo-45573 [https://bugs.python.org/issue?@action=redirect&bpo=45573]: configure now uses a unified format to set state, compiler flags, and linker flags in Makefile. The new macro PY_STDLIB_MOD sets three variables that are consumed by Modules/Setup and setup.py.

bpo-45816 [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.

bpo-45800 [https://bugs.python.org/issue?@action=redirect&bpo=45800]: Settings for pyexpat C extension are now detected by configure. The bundled expat library is built in Makefile.

bpo-45798 [https://bugs.python.org/issue?@action=redirect&bpo=45798]: Settings for decimal internal C extension are now detected by configure. The bundled libmpdec library is built in Makefile.

bpo-45723 [https://bugs.python.org/issue?@action=redirect&bpo=45723]: configure has a new option --with-pkg-config to disable or require pkg-config.

bpo-45774 [https://bugs.python.org/issue?@action=redirect&bpo=45774]: The build dependencies for sqlite3 are now detected by configure and pkg-config. Patch by Erlend E. Aasland.

bpo-45763 [https://bugs.python.org/issue?@action=redirect&bpo=45763]: The build dependencies for zlib, bz2, and lzma are now detected by configure.

bpo-45747 [https://bugs.python.org/issue?@action=redirect&bpo=45747]: gdbm and dbm build dependencies are now detected by configure.

bpo-45743 [https://bugs.python.org/issue?@action=redirect&bpo=45743]: On macOS, the build system no longer passes search_paths_first to the linker. The flag has been the default since Xcode 4 / macOS 10.6.

bpo-45723 [https://bugs.python.org/issue?@action=redirect&bpo=45723]: configure.ac is now compatible with autoconf 2.71. Deprecated checks STDC_HEADERS and AC_HEADER_TIME have been removed.

bpo-45723 [https://bugs.python.org/issue?@action=redirect&bpo=45723]: configure now prints a warning when pkg-config is missing.

bpo-45731 [https://bugs.python.org/issue?@action=redirect&bpo=45731]: configure --enable-loadable-sqlite-extensions is now handled by new PY_SQLITE_ENABLE_LOAD_EXTENSION macro instead of logic in setup.py.

bpo-45723 [https://bugs.python.org/issue?@action=redirect&bpo=45723]: configure.ac now uses custom helper macros and AC_CACHE_CHECK to simplify and speed up configure runs.

bpo-45696 [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.

bpo-45561 [https://bugs.python.org/issue?@action=redirect&bpo=45561]: Run smelly.py tool from $(srcdir).

Windows

bpo-46105 [https://bugs.python.org/issue?@action=redirect&bpo=46105]: Fixed calculation of sys.path in a venv on Windows.

bpo-45901 [https://bugs.python.org/issue?@action=redirect&bpo=45901]: When installed through the Microsoft Store and set as the default app for *.py files, command line arguments will now be passed to Python when invoking a script without explicitly launching Python (that is, script.py args rather than python script.py args).

bpo-45616 [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.

bpo-45850 [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.

bpo-45732 [https://bugs.python.org/issue?@action=redirect&bpo=45732]: Updates bundled Tcl/Tk to 8.6.12.

bpo-45720 [https://bugs.python.org/issue?@action=redirect&bpo=45720]: Internal reference to shlwapi.dll was dropped to help improve startup time. This DLL will no longer be loaded at the start of every Python process.

macOS

bpo-45732 [https://bugs.python.org/issue?@action=redirect&bpo=45732]: Update python.org macOS installer to use Tcl/Tk 8.6.12.

C API

bpo-39026 [https://bugs.python.org/issue?@action=redirect&bpo=39026]: Fix Python.h to build C extensions with Xcode: remove a relative include from Include/cpython/pystate.h.

Python 3.11.0 alpha 2

Release date: 2021-11-05

Core and Builtins

bpo-45716 [https://bugs.python.org/issue?@action=redirect&bpo=45716]: Improve the SyntaxError message when using True, None or False as keywords in a function call. Patch by Pablo Galindo.

bpo-45688 [https://bugs.python.org/issue?@action=redirect&bpo=45688]: sys.stdlib_module_names now contains the macOS-specific module _scproxy.

bpo-45379 [https://bugs.python.org/issue?@action=redirect&bpo=45379]: Clarify ImportError message when we try to explicitly import a frozen module but frozen modules are disabled.

bpo-44525 [https://bugs.python.org/issue?@action=redirect&bpo=44525]: Specialize simple calls to Python functions (no starargs, keyword dict, or closure)

bpo-45530 [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 値の比較 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.

bpo-45526 [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.

bpo-30570 [https://bugs.python.org/issue?@action=redirect&bpo=30570]: Fixed a crash in issubclass() from infinite recursion when searching pathological __bases__ tuples.

bpo-45521 [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.

bpo-45494 [https://bugs.python.org/issue?@action=redirect&bpo=45494]: Fix parser crash when reporting errors involving invalid continuation characters. Patch by Pablo Galindo.

bpo-45445 [https://bugs.python.org/issue?@action=redirect&bpo=45445]: Python now fails to initialize if it finds an invalid -X option in the command line. Patch by Pablo Galindo.

bpo-45340 [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.

bpo-45408 [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.

bpo-29410 [https://bugs.python.org/issue?@action=redirect&bpo=29410]: Add SipHash13 for string hash algorithm and use it by default.

bpo-45385 [https://bugs.python.org/issue?@action=redirect&bpo=45385]: Fix reference leak from descr_check. Patch by Donghee Na.

bpo-45367 [https://bugs.python.org/issue?@action=redirect&bpo=45367]: Specialized the BINARY_MULTIPLY opcode to BINARY_MULTIPLY_INT and BINARY_MULTIPLY_FLOAT using the PEP 659 machinery.

bpo-21736 [https://bugs.python.org/issue?@action=redirect&bpo=21736]: Frozen stdlib modules now have __file__ to the .py file they would otherwise be loaded from, if possible. For packages, __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 __file__ is not guaranteed to exist. None of this affects non-stdlib frozen modules nor, for now, frozen modules imported using PyImport_ImportFrozenModule(). Also, at the moment co_filename is not updated for the module.

bpo-45020 [https://bugs.python.org/issue?@action=redirect&bpo=45020]: For frozen stdlib modules, record the original module name as module.__spec__.loader_state.origname. If the value is different than module.__spec__.name then the module was defined as an alias in Tools/scripts/freeze_modules.py. If it is None then the module comes from a source file outside the stdlib.

bpo-45324 [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.

bpo-45292 [https://bugs.python.org/issue?@action=redirect&bpo=45292]: Implement PEP 654 [https://peps.python.org/pep-0654/]. Add ExceptionGroup and BaseExceptionGroup. Update traceback display code.

bpo-40116 [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.

bpo-44050 [https://bugs.python.org/issue?@action=redirect&bpo=44050]: Extensions that indicate they use global state (by setting m_size to -1) can again be used in multiple interpreters. This reverts to behavior of Python 3.8.

bpo-44525 [https://bugs.python.org/issue?@action=redirect&bpo=44525]: Setup initial specialization infrastructure for the CALL_FUNCTION opcode. Implemented initial specializations for C function calls:

CALL_FUNCTION_BUILTIN_O for METH_O flag.

CALL_FUNCTION_BUILTIN_FAST for METH_FASTCALL flag without keywords.

CALL_FUNCTION_LEN for len(o).

CALL_FUNCTION_ISINSTANCE for isinstance(o, t).

bpo-44511 [https://bugs.python.org/issue?@action=redirect&bpo=44511]: Improve the generated bytecode for class and mapping patterns.

bpo-43706 [https://bugs.python.org/issue?@action=redirect&bpo=43706]: Speed up calls to enumerate() by using the PEP 590 [https://peps.python.org/pep-0590/] vectorcall calling convention. Patch by Donghee Na.

Library

bpo-45679 [https://bugs.python.org/issue?@action=redirect&bpo=45679]: Fix caching of multi-value typing.Literal. Literal[True, 2] is no longer equal to Literal[1, 2].

bpo-42064 [https://bugs.python.org/issue?@action=redirect&bpo=42064]: Convert sqlite3 to multi-phase initialisation (PEP 489). Patches by Erlend E. Aasland.

bpo-45438 [https://bugs.python.org/issue?@action=redirect&bpo=45438]: Fix typing.Signature string representation for generic builtin types.

bpo-45613 [https://bugs.python.org/issue?@action=redirect&bpo=45613]: sqlite3 now sets sqlite3.threadsafety based on the default threading mode the underlying SQLite library has been compiled with. Patch by Erlend E. Aasland.

bpo-45574 [https://bugs.python.org/issue?@action=redirect&bpo=45574]: Fix warning about print_escape being unused.

bpo-45581 [https://bugs.python.org/issue?@action=redirect&bpo=45581]: sqlite3.connect() now correctly raises MemoryError if the underlying SQLite API signals memory error. Patch by Erlend E. Aasland.

bpo-45557 [https://bugs.python.org/issue?@action=redirect&bpo=45557]: pprint.pprint() now handles underscore_numbers correctly. Previously it was always setting it to False.

bpo-44019 [https://bugs.python.org/issue?@action=redirect&bpo=44019]: Add operator.call() to operator.__all__. Patch by Kreusada.

bpo-42174 [https://bugs.python.org/issue?@action=redirect&bpo=42174]: shutil.get_terminal_size() now falls back to sane values if the column or line count are 0.

bpo-35673 [https://bugs.python.org/issue?@action=redirect&bpo=35673]: Improve the introspectability of the __loader__ attribute for namespace packages. importlib.machinery.NamespaceLoader is now public, and implements the importlib.abc.InspectLoader interface. _NamespaceLoader is kept for backward compatibility.

bpo-45515 [https://bugs.python.org/issue?@action=redirect&bpo=45515]: Add references to zoneinfo in the datetime documentation, mostly replacing outdated references to dateutil.tz. Change by Paul Ganssle.

bpo-45475 [https://bugs.python.org/issue?@action=redirect&bpo=45475]: Reverted optimization of iterating gzip.GzipFile, bz2.BZ2File, and lzma.LZMAFile (see bpo-43787 [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.

bpo-45489 [https://bugs.python.org/issue?@action=redirect&bpo=45489]: Update ForwardRef to support | operator. Patch by Donghee Na.

bpo-42222 [https://bugs.python.org/issue?@action=redirect&bpo=42222]: Removed deprecated support for float arguments in randrange().

bpo-45428 [https://bugs.python.org/issue?@action=redirect&bpo=45428]: Fix a regression in py_compile when reading filenames from standard input.

bpo-45467 [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.

bpo-45461 [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.

bpo-45239 [https://bugs.python.org/issue?@action=redirect&bpo=45239]: Fixed email.utils.parsedate_tz() crashing with UnboundLocalError on certain invalid input instead of returning None. Patch by Ben Hoyt.

bpo-45417 [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.

bpo-45249 [https://bugs.python.org/issue?@action=redirect&bpo=45249]: Fix the behaviour of traceback.print_exc() when displaying the caret when the end_offset in the exception is set to 0. Patch by Pablo Galindo

bpo-45416 [https://bugs.python.org/issue?@action=redirect&bpo=45416]: Fix use of asyncio.Condition with explicit asyncio.Lock objects, which was a regression due to removal of explicit loop arguments. Patch by Joongi Kim.

bpo-20028 [https://bugs.python.org/issue?@action=redirect&bpo=20028]: Empty escapechar/quotechar is not allowed when initializing csv.Dialect. Patch by Vajrasky Kok and Donghee Na.

bpo-44904 [https://bugs.python.org/issue?@action=redirect&bpo=44904]: Fix bug in the doctest module that caused it to fail if a docstring included an example with a classmethod property. Patch by Alex Waygood.

bpo-45406 [https://bugs.python.org/issue?@action=redirect&bpo=45406]: Make inspect.getmodule() catch FileNotFoundError raised by inspect.getabsfile(), and return None to indicate that the module could not be determined.

bpo-45411 [https://bugs.python.org/issue?@action=redirect&bpo=45411]: Add extensions for files containing subtitles - .srt & .vtt - to the mimetypes.py module.

bpo-10716 [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 ServerHTMLDoc which now uses the CSS too. cgitb now relies less on pydoc (as it can't use the CSS file).

bpo-27580 [https://bugs.python.org/issue?@action=redirect&bpo=27580]: Add support of null characters in csv.

bpo-45262 [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

bpo-45386 [https://bugs.python.org/issue?@action=redirect&bpo=45386]: Make xmlrpc.client more robust to C runtimes where the underlying C strftime function results in a ValueError when testing for year formatting options.

bpo-20028 [https://bugs.python.org/issue?@action=redirect&bpo=20028]: Improve error message of csv.Dialect when initializing. Patch by Vajrasky Kok and Donghee Na.

bpo-45343 [https://bugs.python.org/issue?@action=redirect&bpo=45343]: Update bundled pip to 21.2.4 and setuptools to 58.1.0

bpo-45328 [https://bugs.python.org/issue?@action=redirect&bpo=45328]: Fixed http.client.HTTPConnection to work properly in OSs that don't support the TCP_NODELAY socket option.

bpo-45243 [https://bugs.python.org/issue?@action=redirect&bpo=45243]: Add setlimit() and getlimit() to sqlite3.Connection for setting and getting SQLite limits by connection basis. Patch by Erlend E. Aasland.

bpo-45320 [https://bugs.python.org/issue?@action=redirect&bpo=45320]: Removed from the inspect module:

the getargspec function, deprecated since Python 3.0;

use inspect.signature() or inspect.getfullargspec() instead.

the formatargspec function, deprecated since Python 3.5; use the inspect.signature() function and Signature object directly.

the undocumented Signature.from_builtin and Signature.from_function functions, deprecated since Python 3.5; use the Signature.from_callable() method instead.

Patch by Hugo van Kemenade.

bpo-45192 [https://bugs.python.org/issue?@action=redirect&bpo=45192]: Fix the tempfile._infer_return_type function so that the dir argument of the tempfile functions accepts an object implementing the os.PathLike protocol.

Patch by Kyungmin Lee.

bpo-45160 [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.

bpo-25625 [https://bugs.python.org/issue?@action=redirect&bpo=25625]: Added non parallel-safe chdir() context manager to change the current working directory and then restore it on exit. Simple wrapper around chdir().

bpo-24139 [https://bugs.python.org/issue?@action=redirect&bpo=24139]: Add support for SQLite extended result codes in sqlite3.Error. Patch by Erlend E. Aasland.

bpo-24444 [https://bugs.python.org/issue?@action=redirect&bpo=24444]: Fixed an error raised in argparse help display when help for an option is set to 1+ blank spaces or when choices arg is an empty container.

bpo-44547 [https://bugs.python.org/issue?@action=redirect&bpo=44547]: Implement Fraction.__int__, so that a fractions.Fraction instance f passes an isinstance(f, typing.SupportsInt) check.

bpo-40321 [https://bugs.python.org/issue?@action=redirect&bpo=40321]: Adds support for HTTP 308 redirects to urllib. See RFC 7538 [https://datatracker.ietf.org/doc/html/rfc7538.html] for details. Patch by Jochem Schulenklopper.

bpo-41374 [https://bugs.python.org/issue?@action=redirect&bpo=41374]: Ensure that socket.TCP_* constants are exposed on Cygwin 3.1.6 and greater.

bpo-35970 [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.

Documentation

bpo-45726 [https://bugs.python.org/issue?@action=redirect&bpo=45726]: Improve documentation for functools.singledispatch() and functools.singledispatchmethod.

bpo-45680 [https://bugs.python.org/issue?@action=redirect&bpo=45680]: Amend the docs on GenericAlias objects to clarify that non-container classes can also implement __class_getitem__. Patch contributed by Alex Waygood.

bpo-45618 [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.

bpo-45655 [https://bugs.python.org/issue?@action=redirect&bpo=45655]: Add a new "relevant PEPs" section to the top of the documentation for the typing module. Patch by Alex Waygood.

bpo-45604 [https://bugs.python.org/issue?@action=redirect&bpo=45604]: Add level argument to multiprocessing.log_to_stderr function docs.

bpo-45516 [https://bugs.python.org/issue?@action=redirect&bpo=45516]: Add protocol description to the importlib.abc.TraversableResources documentation.

bpo-45464 [https://bugs.python.org/issue?@action=redirect&bpo=45464]: Mention in the documentation of Built-in Exceptions that inheriting from multiple exception types in a single subclass is not recommended due to possible memory layout incompatibility.

bpo-45449 [https://bugs.python.org/issue?@action=redirect&bpo=45449]: Add note about PEP 585 [https://peps.python.org/pep-0585/] in collections.abc.

bpo-45516 [https://bugs.python.org/issue?@action=redirect&bpo=45516]: Add protocol description to the importlib.abc.Traversable documentation.

bpo-20692 [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.

Tests

bpo-45678 [https://bugs.python.org/issue?@action=redirect&bpo=45678]: Add tests for scenarios in which functools.singledispatchmethod is stacked on top of a method that has already been wrapped by two other decorators. Patch by Alex Waygood.

bpo-45578 [https://bugs.python.org/issue?@action=redirect&bpo=45578]: Add tests for dis.distb()

bpo-45678 [https://bugs.python.org/issue?@action=redirect&bpo=45678]: Add tests to ensure that functools.singledispatchmethod correctly wraps the attributes of the target function.

bpo-45668 [https://bugs.python.org/issue?@action=redirect&bpo=45668]: PGO tests now pass when Python is built without test extension modules.

bpo-45577 [https://bugs.python.org/issue?@action=redirect&bpo=45577]: Add subtests for all pickle protocols in test_zoneinfo.

bpo-45566 [https://bugs.python.org/issue?@action=redirect&bpo=45566]: Fix test_frozen_pickle in test_dataclasses to check all pickle versions.

bpo-43592 [https://bugs.python.org/issue?@action=redirect&bpo=43592]: 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.

bpo-39679 [https://bugs.python.org/issue?@action=redirect&bpo=39679]: Add more test cases for @functools.singledispatchmethod when combined with @classmethod or @staticmethod.

bpo-45410 [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.

bpo-45402 [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.

bpo-45403 [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.

bpo-45400 [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.

bpo-10572 [https://bugs.python.org/issue?@action=redirect&bpo=10572]: Rename sqlite3 tests from test_sqlite to test_sqlite3, and relocate them to Lib/test/test_sqlite3. Patch by Erlend E. Aasland.

Build

bpo-43158 [https://bugs.python.org/issue?@action=redirect&bpo=43158]: setup.py now uses values from configure script to build the _uuid extension module. Configure now detects util-linux's libuuid, too.

bpo-45666 [https://bugs.python.org/issue?@action=redirect&bpo=45666]: Fix warning of swprintf and %s usage in _testembed.c

bpo-45548 [https://bugs.python.org/issue?@action=redirect&bpo=45548]: Modules/Setup and Modules/makesetup have been improved. The Setup file now contains working rules for all extensions. Outdated comments have been removed. Rules defined by makesetup track dependencies correctly.

bpo-45548 [https://bugs.python.org/issue?@action=redirect&bpo=45548]: The math and cmath implementation now require a C99 compatible libm and no longer ship with workarounds for missing acosh, asinh, atanh, expm1, and log1p functions.

bpo-45595 [https://bugs.python.org/issue?@action=redirect&bpo=45595]: setup.py and makesetup now track build dependencies on all Python header files and module specific header files.

bpo-45571 [https://bugs.python.org/issue?@action=redirect&bpo=45571]: Modules/Setup now use PY_CFLAGS_NODIST instead of PY_CFLAGS to compile shared modules.

bpo-45570 [https://bugs.python.org/issue?@action=redirect&bpo=45570]: pyexpat and _elementtree no longer define obsolete macros HAVE_EXPAT_CONFIG_H and USE_PYEXPAT_CAPI. XML_POOR_ENTROPY is now defined in expat_config.h.

bpo-43974 [https://bugs.python.org/issue?@action=redirect&bpo=43974]: setup.py no longer defines Py_BUILD_CORE_MODULE. Instead every module, that uses the internal API, defines the macro.

bpo-45548 [https://bugs.python.org/issue?@action=redirect&bpo=45548]: Fill in missing entries in Modules/Setup.

bpo-45532 [https://bugs.python.org/issue?@action=redirect&bpo=45532]: Update sys.version to use main as fallback information. Patch by Jeong YunWon.

bpo-45536 [https://bugs.python.org/issue?@action=redirect&bpo=45536]: The 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.

bpo-45221 [https://bugs.python.org/issue?@action=redirect&bpo=45221]: Fixed regression in handling of LDFLAGS and CPPFLAGS options where argparse.parse_known_args() could interpret an option as one of the built-in command line argument, for example -h for help.

bpo-45440 [https://bugs.python.org/issue?@action=redirect&bpo=45440]: Building Python now requires a C99 <math.h> header file providing the following functions: copysign(), hypot(), isfinite(), isinf(), isnan(), round(). Patch by Victor Stinner.

bpo-45405 [https://bugs.python.org/issue?@action=redirect&bpo=45405]: Prevent internal configure error when running configure with recent versions of non-Apple clang. Patch by David Bohman.

bpo-45433 [https://bugs.python.org/issue?@action=redirect&bpo=45433]: Avoid linking libpython with libcrypt.

Windows

bpo-43652 [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.

bpo-45337 [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.

bpo-43851 [https://bugs.python.org/issue?@action=redirect&bpo=43851]: Build SQLite SQLITE_OMIT_AUTOINIT on Windows. Patch by Erlend E. Aasland.

macOS

bpo-44828 [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.

IDLE

bpo-45495 [https://bugs.python.org/issue?@action=redirect&bpo=45495]: Add context keywords 'case' and 'match' to completions list.

C API

bpo-29103 [https://bugs.python.org/issue?@action=redirect&bpo=29103]: 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.

bpo-45522 [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.

bpo-35134 [https://bugs.python.org/issue?@action=redirect&bpo=35134]: Exclude PyWeakref_GET_OBJECT() from the limited C API. It never worked since the PyWeakReference structure is opaque in the limited C API.

bpo-35081 [https://bugs.python.org/issue?@action=redirect&bpo=35081]: Move the interpreteridobject.h header file from Include/ to Include/internal/. It only provides private functions. Patch by Victor Stinner.

bpo-35134 [https://bugs.python.org/issue?@action=redirect&bpo=35134]: The non-limited API files cellobject.h, classobject.h, context.h, funcobject.h, genobject.h and longintrepr.h have been moved to the Include/cpython directory. Moreover, the eval.h header file was removed. These files must not be included directly, as they are already included in Python.h: Include Files. If they have been included directly, consider including Python.h instead. Patch by Victor Stinner.

bpo-45474 [https://bugs.python.org/issue?@action=redirect&bpo=45474]: The following items are no longer available when Py_LIMITED_API is defined:

PyMarshal_WriteLongToFile()

PyMarshal_WriteObjectToFile()

PyMarshal_ReadObjectFromString()

PyMarshal_WriteObjectToString()

the Py_MARSHAL_VERSION macro

These are not part of the limited API.

Patch by Victor Stinner.

bpo-45434 [https://bugs.python.org/issue?@action=redirect&bpo=45434]: Remove the pystrhex.h header file. It only contains private functions. C extensions should only include the main <Python.h> header file. Patch by Victor Stinner.

bpo-45440 [https://bugs.python.org/issue?@action=redirect&bpo=45440]: Remove the Py_FORCE_DOUBLE() macro. It was used by the Py_IS_INFINITY() macro. Patch by Victor Stinner.

bpo-45434 [https://bugs.python.org/issue?@action=redirect&bpo=45434]: <Python.h> no longer includes the header files <stdlib.h>, <stdio.h>, <errno.h> and <string.h> when the Py_LIMITED_API macro is set to 0x030b0000 (Python 3.11) or higher. C extensions should explicitly include the header files after #include <Python.h>. Patch by Victor Stinner.

bpo-41123 [https://bugs.python.org/issue?@action=redirect&bpo=41123]: Remove Py_UNICODE_COPY() and Py_UNICODE_FILL() macros, deprecated since Python 3.3. Use PyUnicode_CopyCharacters() or memcpy() (wchar_t* string), and PyUnicode_Fill() functions instead. Patch by Victor Stinner.

bpo-45412 [https://bugs.python.org/issue?@action=redirect&bpo=45412]: Remove the following math macros using the errno variable:

Py_ADJUST_ERANGE1()

Py_ADJUST_ERANGE2()

Py_OVERFLOWED()

Py_SET_ERANGE_IF_OVERFLOW()

Py_SET_ERRNO_ON_MATH_ERROR()

Patch by Victor Stinner.

bpo-45395 [https://bugs.python.org/issue?@action=redirect&bpo=45395]: Custom frozen modules (the array set to 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.

bpo-43760 [https://bugs.python.org/issue?@action=redirect&bpo=43760]: Add new PyThreadState_EnterTracing(), and PyThreadState_LeaveTracing() functions to the limited C API to suspend and resume tracing and profiling. Patch by Victor Stinner.

bpo-44220 [https://bugs.python.org/issue?@action=redirect&bpo=44220]: PyStructSequence_UnnamedField is added to the Stable ABI.

Python 3.11.0 alpha 1

Release date: 2021-10-05

Security

bpo-42278 [https://bugs.python.org/issue?@action=redirect&bpo=42278]: Replaced usage of tempfile.mktemp() with TemporaryDirectory to avoid a potential race condition.

bpo-44600 [https://bugs.python.org/issue?@action=redirect&bpo=44600]: Fix incorrect line numbers while tracing some failed patterns in match statements. Patch by Charles Burkland.

bpo-41180 [https://bugs.python.org/issue?@action=redirect&bpo=41180]: Add auditing events to the marshal module, and stop raising 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 .pyc files.

bpo-44394 [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 CVE-2013-0340 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2013-0340] "Billion Laughs" vulnerability. This copy is most used on Windows and macOS.

bpo-43124 [https://bugs.python.org/issue?@action=redirect&bpo=43124]: Made the internal putcmd function in smtplib sanitize input for presence of \r and \n characters to avoid (unlikely) command injection.

bpo-44022 [https://bugs.python.org/issue?@action=redirect&bpo=44022]: http.client now avoids infinitely reading potential HTTP headers after a 100 Continue status response from the server.

Core and Builtins

bpo-43760 [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.

bpo-45061 [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.

bpo-24076 [https://bugs.python.org/issue?@action=redirect&bpo=24076]: sum() was further optimised for summing up single digit integers.

bpo-45190 [https://bugs.python.org/issue?@action=redirect&bpo=45190]: Update Unicode databases to Unicode 14.0.0.

bpo-45167 [https://bugs.python.org/issue?@action=redirect&bpo=45167]: Fix deepcopying of types.GenericAlias objects.

bpo-45155 [https://bugs.python.org/issue?@action=redirect&bpo=45155]: int.to_bytes() and int.from_bytes() now take a default value of "big" for the byteorder argument. int.to_bytes() also takes a default value of 1 for the length argument.

bpo-44219 [https://bugs.python.org/issue?@action=redirect&bpo=44219]: Release the GIL while performing isatty system calls on arbitrary file descriptors. In particular, this affects os.isatty(), os.device_encoding() and io.TextIOWrapper. By extension, io.open() in text mode is also affected. This change solves a deadlock in os.isatty(). Patch by Vincent Michel in bpo-44219 [https://bugs.python.org/issue?@action=redirect&bpo=44219].

bpo-44959 [https://bugs.python.org/issue?@action=redirect&bpo=44959]: Added fallback to extension modules with '.sl' suffix on HP-UX

bpo-45121 [https://bugs.python.org/issue?@action=redirect&bpo=45121]: Fix issue where Protocol.__init__ raises RecursionError when it's called directly or via super(). Patch provided by Yurii Karabas.

bpo-44348 [https://bugs.python.org/issue?@action=redirect&bpo=44348]: The deallocator function of the BaseException type now uses the trashcan mechanism to prevent stack overflow. For example, when a RecursionError instance is raised, it can be linked to another RecursionError through the __context__ attribute or the __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.

bpo-45123 [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.

bpo-1514420 [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.

bpo-41031 [https://bugs.python.org/issue?@action=redirect&bpo=41031]: Match C and Python code formatting of unprintable exceptions and exceptions in the __main__ module.

bpo-37330 [https://bugs.python.org/issue?@action=redirect&bpo=37330]: open(), io.open(), codecs.open() and fileinput.FileInput no longer accept 'U' ("universal newline") in the file mode. This flag was deprecated since Python 3.3. Patch by Victor Stinner.

bpo-45083 [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 traceback module was using qualname already).

bpo-34561 [https://bugs.python.org/issue?@action=redirect&bpo=34561]: List sorting now uses the merge-ordering strategy from Munro and Wild's powersort(). Unlike the former strategy, this is provably near-optimal in the entropy of the distribution of run lengths. Most uses of 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.

bpo-45056 [https://bugs.python.org/issue?@action=redirect&bpo=45056]: Compiler now removes trailing unused constants from co_consts.

bpo-45020 [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).

bpo-45012 [https://bugs.python.org/issue?@action=redirect&bpo=45012]: In posix, release GIL during stat(), lstat(), and fstatat() syscalls made by os.DirEntry.stat(). Patch by Stanisław Skonieczny.

bpo-45018 [https://bugs.python.org/issue?@action=redirect&bpo=45018]: Fixed pickling of range iterators that iterated for over 2**32 times.

bpo-45000 [https://bugs.python.org/issue?@action=redirect&bpo=45000]: A SyntaxError is now raised when trying to delete __debug__. Patch by Donghee Na.

bpo-44963 [https://bugs.python.org/issue?@action=redirect&bpo=44963]: Implement send() and throw() methods for anext_awaitable objects. Patch by Pablo Galindo.

bpo-44962 [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

bpo-24234 [https://bugs.python.org/issue?@action=redirect&bpo=24234]: Implement the __bytes__() special method on the bytes type, so a bytes object b passes an isinstance(b, typing.SupportsBytes) check.

bpo-24234 [https://bugs.python.org/issue?@action=redirect&bpo=24234]: Implement the __complex__() special method on the complex type, so a complex number z passes an isinstance(z, typing.SupportsComplex) check.

bpo-44954 [https://bugs.python.org/issue?@action=redirect&bpo=44954]: Fixed a corner case bug where the result of float.fromhex('0x.8p-1074') was rounded the wrong way.

bpo-44947 [https://bugs.python.org/issue?@action=redirect&bpo=44947]: Refine the syntax error for trailing commas in import statements. Patch by Pablo Galindo.

bpo-44945 [https://bugs.python.org/issue?@action=redirect&bpo=44945]: Specialize the BINARY_ADD instruction using the PEP 659 machinery. Adds five new instructions:

BINARY_ADD_ADAPTIVE

BINARY_ADD_FLOAT

BINARY_ADD_INT

BINARY_ADD_UNICODE

BINARY_ADD_UNICODE_INPLACE_FAST

bpo-44929 [https://bugs.python.org/issue?@action=redirect&bpo=44929]: Fix some edge cases of enum.Flag string representation in the REPL. Patch by Pablo Galindo.

bpo-44914 [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.

bpo-44698 [https://bugs.python.org/issue?@action=redirect&bpo=44698]: Restore behaviour of complex exponentiation with integer-valued exponent of type float or complex.

bpo-44895 [https://bugs.python.org/issue?@action=redirect&bpo=44895]: A debug variable PYTHONDUMPREFSFILE is added for creating a dump file which is generated by --with-trace-refs. Patch by Donghee Na.

bpo-44900 [https://bugs.python.org/issue?@action=redirect&bpo=44900]: Add five superinstructions for PEP 659 quickening:

LOAD_FAST LOAD_FAST

STORE_FAST LOAD_FAST

LOAD_FAST LOAD_CONST

LOAD_CONST LOAD_FAST

STORE_FAST STORE_FAST

bpo-44889 [https://bugs.python.org/issue?@action=redirect&bpo=44889]: Initial implementation of adaptive specialization of LOAD_METHOD. The following specialized forms were added:

LOAD_METHOD_CACHED

LOAD_METHOD_MODULE

LOAD_METHOD_CLASS

bpo-44890 [https://bugs.python.org/issue?@action=redirect&bpo=44890]: Specialization stats are always collected in debug builds.

bpo-44885 [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

bpo-44878 [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.

bpo-44878 [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.

bpo-44874 [https://bugs.python.org/issue?@action=redirect&bpo=44874]: Deprecate the old trashcan macros (Py_TRASHCAN_SAFE_BEGIN/Py_TRASHCAN_SAFE_END). They should be replaced by the new macros Py_TRASHCAN_BEGIN and Py_TRASHCAN_END.

bpo-44872 [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).

bpo-33930 [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.

bpo-25782 [https://bugs.python.org/issue?@action=redirect&bpo=25782]: Fix bug where PyErr_SetObject hangs when the current exception has a cycle in its context chain.

bpo-44856 [https://bugs.python.org/issue?@action=redirect&bpo=44856]: Fix reference leaks in the error paths of update_bases() and __build_class__. Patch by Pablo Galindo.

bpo-44826 [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:

STORE_ATTR_SLOT

STORE_ATTR_SPLIT_KEYS

STORE_ATTR_WITH_HINT

bpo-44838 [https://bugs.python.org/issue?@action=redirect&bpo=44838]: Fixed a bug that was causing the parser to raise an incorrect custom SyntaxError for invalid 'if' expressions. Patch by Pablo Galindo.

bpo-44821 [https://bugs.python.org/issue?@action=redirect&bpo=44821]: Create instance dictionaries (__dict__) eagerly, to improve regularity of object layout and assist specialization.

bpo-44792 [https://bugs.python.org/issue?@action=redirect&bpo=44792]: Improve syntax errors for if expressions. Patch by Miguel Brito

bpo-34013 [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

bpo-44732 [https://bugs.python.org/issue?@action=redirect&bpo=44732]: Rename types.Union to types.UnionType.

bpo-44725 [https://bugs.python.org/issue?@action=redirect&bpo=44725]: Expose specialization stats in python via _opcode.get_specialization_stats().

bpo-44717 [https://bugs.python.org/issue?@action=redirect&bpo=44717]: Improve AttributeError on circular imports of submodules.

bpo-44698 [https://bugs.python.org/issue?@action=redirect&bpo=44698]: Fix undefined behaviour in complex object exponentiation.

bpo-44653 [https://bugs.python.org/issue?@action=redirect&bpo=44653]: Support typing types in parameter substitution in the union type.

bpo-44676 [https://bugs.python.org/issue?@action=redirect&bpo=44676]: Add ability to serialise types.Union objects. Patch provided by Yurii Karabas.

bpo-44633 [https://bugs.python.org/issue?@action=redirect&bpo=44633]: Parameter substitution of the union type with wrong types now raises TypeError instead of returning NotImplemented.

bpo-44661 [https://bugs.python.org/issue?@action=redirect&bpo=44661]: Update property_descr_set to use vectorcall if possible. Patch by Donghee Na.

bpo-44662 [https://bugs.python.org/issue?@action=redirect&bpo=44662]: Add __module__ to types.Union. This also fixes types.Union issues with typing.Annotated. Patch provided by Yurii Karabas.

bpo-44655 [https://bugs.python.org/issue?@action=redirect&bpo=44655]: Include the name of the type in unset __slots__ attribute errors. Patch by Pablo Galindo

bpo-44655 [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

bpo-44646 [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.

bpo-44636 [https://bugs.python.org/issue?@action=redirect&bpo=44636]: Collapse union of equal types. E.g. the result of int | int is now int. Fix comparison of the union type with non-hashable objects. E.g. int | str == {} no longer raises a TypeError.

bpo-44611 [https://bugs.python.org/issue?@action=redirect&bpo=44611]: On Windows, os.urandom(): uses BCryptGenRandom API instead of CryptGenRandom API which is deprecated from Microsoft Windows API. Patch by Donghee Na.

bpo-44635 [https://bugs.python.org/issue?@action=redirect&bpo=44635]: Convert None to type(None) in the union type constructor.

bpo-26280 [https://bugs.python.org/issue?@action=redirect&bpo=26280]: Implement adaptive specialization for BINARY_SUBSCR

Three specialized forms of BINARY_SUBSCR are added:

BINARY_SUBSCR_LIST_INT

BINARY_SUBSCR_TUPLE_INT

BINARY_SUBSCR_DICT

bpo-44589 [https://bugs.python.org/issue?@action=redirect&bpo=44589]: Mapping patterns in match statements with two or more equal literal keys will now raise a SyntaxError at compile-time.

bpo-44606 [https://bugs.python.org/issue?@action=redirect&bpo=44606]: Fix __instancecheck__ and __subclasscheck__ for the union type.

bpo-42073 [https://bugs.python.org/issue?@action=redirect&bpo=42073]: The @classmethod decorator can now wrap other classmethod-like descriptors.

bpo-41972 [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.

bpo-44590 [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.

bpo-44584 [https://bugs.python.org/issue?@action=redirect&bpo=44584]: The threading debug (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.

bpo-43895 [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.

bpo-44490 [https://bugs.python.org/issue?@action=redirect&bpo=44490]: typing now searches for type parameters in types.Union objects. get_type_hints will also properly resolve annotations with nested types.Union objects. Patch provided by Yurii Karabas.

bpo-43950 [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 PEP 657 [https://peps.python.org/pep-0657/].

bpo-44562 [https://bugs.python.org/issue?@action=redirect&bpo=44562]: Remove uses of PyObject_GC_Del() in error path when initializing types.GenericAlias.

bpo-41486 [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.

bpo-43908 [https://bugs.python.org/issue?@action=redirect&bpo=43908]: Heap types with the Py_TPFLAGS_IMMUTABLETYPE flag can now inherit the PEP 590 [https://peps.python.org/pep-0590/] vectorcall protocol. Previously, this was only possible for static types. Patch by Erlend E. Aasland.

bpo-44553 [https://bugs.python.org/issue?@action=redirect&bpo=44553]: Implement GC methods for types.Union to break reference cycles and prevent memory leaks.

bpo-44490 [https://bugs.python.org/issue?@action=redirect&bpo=44490]: Add __parameters__ attribute and __getitem__ operator to types.Union. Patch provided by Yurii Karabas.

bpo-44523 [https://bugs.python.org/issue?@action=redirect&bpo=44523]: Remove the pass-through for hash() of 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.

bpo-44483 [https://bugs.python.org/issue?@action=redirect&bpo=44483]: Fix a crash in types.Union objects when creating a union of an object with bad __module__ field.

bpo-44486 [https://bugs.python.org/issue?@action=redirect&bpo=44486]: Modules will always have a dictionary, even when created by types.ModuleType.__new__()

bpo-44472 [https://bugs.python.org/issue?@action=redirect&bpo=44472]: Fix ltrace functionality when exceptions are raised. Patch by Pablo Galindo

bpo-12022 [https://bugs.python.org/issue?@action=redirect&bpo=12022]: A TypeError is now raised instead of an AttributeError in with and async with statements for objects which do not support the context manager or asynchronous context manager protocols correspondingly.

bpo-44297 [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.

bpo-44456 [https://bugs.python.org/issue?@action=redirect&bpo=44456]: Improve the syntax error when mixing positional and keyword patterns. Patch by Pablo Galindo.

bpo-44409 [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.

bpo-44396 [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.

bpo-44376 [https://bugs.python.org/issue?@action=redirect&bpo=44376]: Exact integer exponentiation (like i**2 or pow(i, 2)) with a small exponent is much faster, due to reducing overhead in such cases.

bpo-44313 [https://bugs.python.org/issue?@action=redirect&bpo=44313]: Directly imported objects and modules (through import and from import statements) don't generate LOAD_METHOD/CALL_METHOD for directly accessed objects on their namespace. They now use the regular LOAD_ATTR/CALL_FUNCTION.

bpo-44338 [https://bugs.python.org/issue?@action=redirect&bpo=44338]: Implement adaptive specialization for LOAD_GLOBAL

Two specialized forms of LOAD_GLOBAL are added:

LOAD_GLOBAL_MODULE

LOAD_GLOBAL_BUILTIN

bpo-44368 [https://bugs.python.org/issue?@action=redirect&bpo=44368]: Improve syntax errors for invalid "as" targets. Patch by Pablo Galindo

bpo-44349 [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.

bpo-44337 [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:

LOAD_ATTR_SLOT

LOAD_ATTR_SPLIT_KEYS

LOAD_ATTR_WITH_HINT

LOAD_ATTR_MODULE

bpo-44335 [https://bugs.python.org/issue?@action=redirect&bpo=44335]: Fix a regression when identifying incorrect characters in syntax errors. Patch by Pablo Galindo

bpo-43693 [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.

bpo-44317 [https://bugs.python.org/issue?@action=redirect&bpo=44317]: Improve tokenizer error with improved locations. Patch by Pablo Galindo.

bpo-44304 [https://bugs.python.org/issue?@action=redirect&bpo=44304]: Fix a crash in the sqlite3 module that happened when the garbage collector clears sqlite.Statement objects. Patch by Pablo Galindo

bpo-44305 [https://bugs.python.org/issue?@action=redirect&bpo=44305]: Improve error message for try blocks without except or finally blocks. Patch by Pablo Galindo.

bpo-43413 [https://bugs.python.org/issue?@action=redirect&bpo=43413]: Constructors of subclasses of some builtin classes (e.g. tuple, list, frozenset) no longer accept arbitrary keyword arguments. [reverted in 3.11a4] Subclass of set can now define a __new__() method with additional keyword parameters without overriding also __init__().

bpo-43667 [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.

bpo-43693 [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.

bpo-44232 [https://bugs.python.org/issue?@action=redirect&bpo=44232]: Fix a regression in type() when a metaclass raises an exception. The C function 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.

bpo-44201 [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

bpo-43693 [https://bugs.python.org/issue?@action=redirect&bpo=43693]: PyCodeObject gained co_fastlocalnames and co_fastlocalkinds as the authoritative source of fast locals info. Marshaled code objects have changed accordingly.

bpo-44184 [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.

bpo-44187 [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.

bpo-44180 [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

bpo-44168 [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

bpo-44156 [https://bugs.python.org/issue?@action=redirect&bpo=44156]: String caches in compile.c are now subinterpreter compatible.

bpo-44143 [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.

bpo-44032 [https://bugs.python.org/issue?@action=redirect&bpo=44032]: Move 'fast' locals and other variables from the frame object to a per-thread datastack.

bpo-44114 [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.

bpo-44110 [https://bugs.python.org/issue?@action=redirect&bpo=44110]: Improve str.__getitem__() error message

bpo-26110 [https://bugs.python.org/issue?@action=redirect&bpo=26110]: Add CALL_METHOD_KW opcode to speed up method calls with keyword arguments. Idea originated from PyPy. A side effect is executing CALL_METHOD is now branchless in the evaluation loop.

bpo-28307 [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.

bpo-43149 [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

bpo-43822 [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.

bpo-40222 [https://bugs.python.org/issue?@action=redirect&bpo=40222]: "Zero cost" exception handling.

Uses a lookup table to determine how to handle exceptions.

Removes SETUP_FINALLY and POP_TOP block instructions, eliminating the runtime overhead of try statements.

Reduces the size of the frame object by about 60%.

Patch by Mark Shannon

bpo-43918 [https://bugs.python.org/issue?@action=redirect&bpo=43918]: Document the signature and default argument in the docstring of the new anext builtin.

bpo-43833 [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.

bpo-43879 [https://bugs.python.org/issue?@action=redirect&bpo=43879]: Add native_thread_id to PyThreadState. Patch by Gabriele N. Tornetta.

bpo-43693 [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.

bpo-17792 [https://bugs.python.org/issue?@action=redirect&bpo=17792]: More accurate error messages for access of unbound locals or free vars.

bpo-28146 [https://bugs.python.org/issue?@action=redirect&bpo=28146]: Fix a confusing error message in str.format().

bpo-11105 [https://bugs.python.org/issue?@action=redirect&bpo=11105]: When compiling ast.AST objects with recursive references through compile(), the interpreter doesn't crash anymore instead it raises a RecursionError.

bpo-39091 [https://bugs.python.org/issue?@action=redirect&bpo=39091]: Fix crash when using passing a non-exception to a generator's throw() method. Patch by Noah Oxer

bpo-33346 [https://bugs.python.org/issue?@action=redirect&bpo=33346]: Asynchronous comprehensions are now allowed inside comprehensions in asynchronous functions. Outer comprehensions implicitly become asynchronous.

Library

bpo-45371 [https://bugs.python.org/issue?@action=redirect&bpo=45371]: Fix clang rpath issue in distutils. The UnixCCompiler now uses correct clang option to add a runtime library directory (rpath) to a shared library.

bpo-45329 [https://bugs.python.org/issue?@action=redirect&bpo=45329]: Fix freed memory access in pyexpat.xmlparser when building it with an installed expat library <= 2.2.0.

bpo-41710 [https://bugs.python.org/issue?@action=redirect&bpo=41710]: On Unix, if the sem_clockwait() function is available in the C library (glibc 2.30 and newer), the threading.Lock.acquire() method now uses the monotonic clock (time.CLOCK_MONOTONIC) for the timeout, rather than using the system clock (time.CLOCK_REALTIME), to not be affected by system clock changes. Patch by Victor Stinner.

bpo-1596321 [https://bugs.python.org/issue?@action=redirect&bpo=1596321]: Fix the threading._shutdown() function when the threading module was imported first from a thread different than the main thread: no longer log an error at Python exit.

bpo-45274 [https://bugs.python.org/issue?@action=redirect&bpo=45274]: Fix a race condition in the Thread.join() method of the 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.

bpo-21302 [https://bugs.python.org/issue?@action=redirect&bpo=21302]: In Unix operating systems, time.sleep() now uses the nanosleep() function, if clock_nanosleep() is not available but nanosleep() is available. nanosleep() allows to sleep with nanosecond precision.

bpo-21302 [https://bugs.python.org/issue?@action=redirect&bpo=21302]: On Windows, time.sleep() now uses a waitable timer which has a resolution of 100 nanoseconds (10⁻⁷ seconds). Previously, it had a resolution of 1 millisecond (10⁻³ seconds). Patch by Benjamin Szőke and Victor Stinner.

bpo-45238 [https://bugs.python.org/issue?@action=redirect&bpo=45238]: Fix unittest.IsolatedAsyncioTestCase.debug(): it runs now asynchronous methods and callbacks.

bpo-36674 [https://bugs.python.org/issue?@action=redirect&bpo=36674]: unittest.TestCase.debug() raises now a unittest.SkipTest if the class or the test method are decorated with the skipping decorator.

bpo-45235 [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.

bpo-45183 [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().

bpo-45234 [https://bugs.python.org/issue?@action=redirect&bpo=45234]: Fixed a regression in copyfile(), copy(), copy2() raising FileNotFoundError when source is a directory, which should raise IsADirectoryError

bpo-45228 [https://bugs.python.org/issue?@action=redirect&bpo=45228]: Fix stack buffer overflow in parsing J1939 network address.

bpo-45225 [https://bugs.python.org/issue?@action=redirect&bpo=45225]: use map function instead of genexpr in capwords.

bpo-42135 [https://bugs.python.org/issue?@action=redirect&bpo=42135]: Fix typo: 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.

bpo-20524 [https://bugs.python.org/issue?@action=redirect&bpo=20524]: Improves error messages on .format() operation for str, float, int, and complex. New format now shows the problematic pattern and the object type.

bpo-45168 [https://bugs.python.org/issue?@action=redirect&bpo=45168]: Change dis.dis() output to omit op arg values that cannot be resolved due to co_consts, co_names etc not being provided. Previously the oparg itself was repeated in the value field, which is not useful and can be confusing.

bpo-21302 [https://bugs.python.org/issue?@action=redirect&bpo=21302]: In Unix operating systems, time.sleep() now uses the clock_nanosleep() function, if available, which allows to sleep for an interval specified with nanosecond precision.

bpo-45173 [https://bugs.python.org/issue?@action=redirect&bpo=45173]: Remove from the configparser module: the SafeConfigParser class, the filename property of the ParsingError class, the readfp() method of the ConfigParser class, deprecated since Python 3.2.

Patch by Hugo van Kemenade.

bpo-44987 [https://bugs.python.org/issue?@action=redirect&bpo=44987]: Pure ASCII strings are now normalized in constant time by unicodedata.normalize(). Patch by Donghee Na.

bpo-35474 [https://bugs.python.org/issue?@action=redirect&bpo=35474]: Calling mimetypes.guess_all_extensions() with strict=False no longer affects the result of the following call with strict=True. Also, mutating the returned list no longer affects the global state.

bpo-45166 [https://bugs.python.org/issue?@action=redirect&bpo=45166]: typing.get_type_hints() now works with Final wrapped in ForwardRef.

bpo-45162 [https://bugs.python.org/issue?@action=redirect&bpo=45162]: Remove many old deprecated unittest features:

"fail*" and "assert*" aliases of TestCase methods.

Broken from start TestCase method assertDictContainsSubset().

Ignored <unittest.TestLoader.loadTestsFromModule> TestLoader.loadTestsFromModule() parameter use_load_tests.

Old alias _TextTestResult of TextTestResult.

bpo-38371 [https://bugs.python.org/issue?@action=redirect&bpo=38371]: Remove the deprecated split() method of _tkinter.TkappType. Patch by Erlend E. Aasland.

bpo-20499 [https://bugs.python.org/issue?@action=redirect&bpo=20499]: Improve the speed and accuracy of statistics.pvariance().

bpo-45132 [https://bugs.python.org/issue?@action=redirect&bpo=45132]: Remove __getitem__() methods of xml.dom.pulldom.DOMEventStream, wsgiref.util.FileWrapper and fileinput.FileInput, deprecated since Python 3.9.

Patch by Hugo van Kemenade.

bpo-45129 [https://bugs.python.org/issue?@action=redirect&bpo=45129]: Due to significant security concerns, the reuse_address parameter of asyncio.loop.create_datagram_endpoint(), disabled in Python 3.9, is now entirely removed. This is because of the behavior of the socket option SO_REUSEADDR in UDP.

Patch by Hugo van Kemenade.

bpo-45124 [https://bugs.python.org/issue?@action=redirect&bpo=45124]: The bdist_msi command, deprecated in Python 3.9, is now removed.

Use bdist_wheel (wheel packages) instead.

Patch by Hugo van Kemenade.

bpo-30856 [https://bugs.python.org/issue?@action=redirect&bpo=30856]: unittest.TestResult methods addFailure(), addError(), addSkip() and 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.

bpo-45034 [https://bugs.python.org/issue?@action=redirect&bpo=45034]: Changes how error is formatted for struct.pack with 'H' and 'h' modes and too large / small numbers. Now it shows the actual numeric limits, while previously it was showing arithmetic expressions.

bpo-25894 [https://bugs.python.org/issue?@action=redirect&bpo=25894]: 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.

bpo-45081 [https://bugs.python.org/issue?@action=redirect&bpo=45081]: Fix issue when dataclasses that inherit from typing.Protocol subclasses have wrong __init__. Patch provided by Yurii Karabas.

bpo-45085 [https://bugs.python.org/issue?@action=redirect&bpo=45085]: The binhex module, deprecated in Python 3.9, is now removed. The following binascii functions, deprecated in Python 3.9, are now also removed:

a2b_hqx(), b2a_hqx();

rlecode_hqx(), rledecode_hqx().

The binascii.crc_hqx() function remains available.

Patch by Victor Stinner.

bpo-40360 [https://bugs.python.org/issue?@action=redirect&bpo=40360]: The lib2to3 package is now deprecated and may not be able to parse Python 3.10 or newer. See the PEP 617 [https://peps.python.org/pep-0617/] (New PEG parser for CPython). Patch by Victor Stinner.

bpo-45075 [https://bugs.python.org/issue?@action=redirect&bpo=45075]: Rename traceback.StackSummary.format_frame() to 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.

bpo-31299 [https://bugs.python.org/issue?@action=redirect&bpo=31299]: Add option to completely drop frames from a traceback by returning None from a format_frame() override.

bpo-41620 [https://bugs.python.org/issue?@action=redirect&bpo=41620]: run() now always return a TestResult instance. Previously it returned None if the test class or method was decorated with a skipping decorator.

bpo-45021 [https://bugs.python.org/issue?@action=redirect&bpo=45021]: Fix a potential deadlock at shutdown of forked children when using concurrent.futures module

bpo-43913 [https://bugs.python.org/issue?@action=redirect&bpo=43913]: Fix bugs in cleaning up classes and modules in unittest:

Functions registered with addModuleCleanup() were not called unless the user defines tearDownModule() in their test module.

Functions registered with addClassCleanup() were not called if tearDownClass is set to None.

Buffering in TestResult did not work with functions registered with addClassCleanup() and addModuleCleanup().

Errors in functions registered with addClassCleanup() and addModuleCleanup() were not handled correctly in buffered and debug modes.

Errors in setUpModule() and functions registered with addModuleCleanup() were reported in wrong order.

And several lesser bugs.

bpo-45030 [https://bugs.python.org/issue?@action=redirect&bpo=45030]: Fix integer overflow in pickling and copying the range iterator.

bpo-45001 [https://bugs.python.org/issue?@action=redirect&bpo=45001]: Made email date parsing more robust against malformed input, namely a whitespace-only Date: header. Patch by Wouter Bolsterlee.

bpo-45010 [https://bugs.python.org/issue?@action=redirect&bpo=45010]: Remove support of special method __div__ in unittest.mock. It is not used in Python 3.

bpo-39218 [https://bugs.python.org/issue?@action=redirect&bpo=39218]: Improve accuracy of variance calculations by using x*x instead of x**2.

bpo-43613 [https://bugs.python.org/issue?@action=redirect&bpo=43613]: Improve the speed of gzip.compress() and gzip.decompress() by compressing and decompressing at once in memory instead of in a streamed fashion.

bpo-37596 [https://bugs.python.org/issue?@action=redirect&bpo=37596]: Ensure that set and frozenset objects are always marshalled reproducibly.

bpo-44019 [https://bugs.python.org/issue?@action=redirect&bpo=44019]: A new function operator.call has been added, such that operator.call(obj, *args, **kwargs) == obj(*args, **kwargs).

bpo-42255 [https://bugs.python.org/issue?@action=redirect&bpo=42255]: webbrowser.MacOSX is deprecated and will be removed in Python 3.13. It is untested and undocumented and also not used by webbrowser itself. Patch by Donghee Na.

bpo-44955 [https://bugs.python.org/issue?@action=redirect&bpo=44955]: Method stopTestRun() is now always called in pair with method startTestRun() for TestResult objects implicitly created in run(). Previously it was not called for test methods and classes decorated with a skipping decorator.

bpo-39039 [https://bugs.python.org/issue?@action=redirect&bpo=39039]: tarfile.open raises ReadError when a zlib error occurs during file extraction.

bpo-44935 [https://bugs.python.org/issue?@action=redirect&bpo=44935]: subprocess on Solaris now also uses os.posix_spawn() for better performance.

bpo-44911 [https://bugs.python.org/issue?@action=redirect&bpo=44911]: IsolatedAsyncioTestCase will no longer throw an exception while cancelling leaked tasks. Patch by Bar Harel.

bpo-41322 [https://bugs.python.org/issue?@action=redirect&bpo=41322]: Added 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).

bpo-44524 [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.

bpo-38956 [https://bugs.python.org/issue?@action=redirect&bpo=38956]: argparse.BooleanOptionalAction's default value is no longer printed twice when used with argparse.ArgumentDefaultsHelpFormatter.

bpo-44860 [https://bugs.python.org/issue?@action=redirect&bpo=44860]: Fix the posix_user scheme in sysconfig to not depend on sys.platlibdir.

bpo-44859 [https://bugs.python.org/issue?@action=redirect&bpo=44859]: Improve error handling in sqlite3 and raise more accurate exceptions.

MemoryError is now raised instead of sqlite3.Warning when memory is not enough for encoding a statement to UTF-8 in Connection.__call__() and Cursor.execute().

UnicodEncodeError is now raised instead of sqlite3.Warning when the statement contains surrogate characters in Connection.__call__() and Cursor.execute().

TypeError is now raised instead of ValueError for non-string script argument in Cursor.executescript().

ValueError is now raised for script containing the null character instead of truncating it in Cursor.executescript().

Correctly handle exceptions raised when getting boolean value of the result of the progress handler.

Add many tests covering different corner cases.

bpo-44581 [https://bugs.python.org/issue?@action=redirect&bpo=44581]: Upgrade bundled pip to 21.2.3 and setuptools to 57.4.0

bpo-44849 [https://bugs.python.org/issue?@action=redirect&bpo=44849]: Fix the os.set_inheritable() function on FreeBSD 14 for file descriptor opened with the O_PATH flag: ignore the EBADF error on ioctl(), fallback on the fcntl() implementation. Patch by Victor Stinner.

bpo-44605 [https://bugs.python.org/issue?@action=redirect&bpo=44605]: The @functools.total_ordering() decorator now works with metaclasses.

bpo-44524 [https://bugs.python.org/issue?@action=redirect&bpo=44524]: Fixed an issue wherein the __name__ and __qualname__ attributes of subscribed specialforms could be None.

bpo-44839 [https://bugs.python.org/issue?@action=redirect&bpo=44839]: MemoryError raised in user-defined functions will now produce a MemoryError in sqlite3. OverflowError will now be converted to DataError. Previously OperationalError was produced in these cases.

bpo-44822 [https://bugs.python.org/issue?@action=redirect&bpo=44822]: sqlite3 user-defined functions and aggregators returning strings with embedded NUL characters are no longer truncated. Patch by Erlend E. Aasland.

bpo-44801 [https://bugs.python.org/issue?@action=redirect&bpo=44801]: Ensure that the ParamSpec variable in Callable can only be substituted with a parameters expression (a list of types, an ellipsis, ParamSpec or Concatenate).

bpo-44806 [https://bugs.python.org/issue?@action=redirect&bpo=44806]: Non-protocol subclasses of typing.Protocol ignore now the __init__ method inherited from protocol base classes.

bpo-27275 [https://bugs.python.org/issue?@action=redirect&bpo=27275]: collections.OrderedDict.popitem() and collections.OrderedDict.pop() no longer call __getitem__ and __delitem__ methods of the OrderedDict subclasses.

bpo-44793 [https://bugs.python.org/issue?@action=redirect&bpo=44793]: Fix checking the number of arguments when subscribe a generic type with ParamSpec parameter.

bpo-44784 [https://bugs.python.org/issue?@action=redirect&bpo=44784]: In importlib.metadata tests, override warnings behavior under expected DeprecationWarnings (importlib_metadata 4.6.3).

bpo-44667 [https://bugs.python.org/issue?@action=redirect&bpo=44667]: The tokenize.tokenize() doesn't incorrectly generate a 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 NL token. Patch by Pablo Galindo

bpo-44771 [https://bugs.python.org/issue?@action=redirect&bpo=44771]: Added importlib.simple module implementing adapters from a low-level resources reader interface to a TraversableResources interface. Legacy API (path, contents, ...) is now supported entirely by the .files() API with a compatibility shim supplied for resource loaders without that functionality. Feature parity with importlib_resources 5.2.

bpo-44752 [https://bugs.python.org/issue?@action=redirect&bpo=44752]: rcompleter does not call getattr() on property objects to avoid the side-effect of evaluating the corresponding method.

bpo-44747 [https://bugs.python.org/issue?@action=redirect&bpo=44747]: Refactor usage of sys._getframe in typing module. Patch provided by Yurii Karabas.

bpo-42378 [https://bugs.python.org/issue?@action=redirect&bpo=42378]: Fixes the issue with log file being overwritten when logging.FileHandler is used in atexit with filemode set to 'w'. Note this will cause the message in atexit not being logged if the log stream is already closed due to shutdown of logging.

bpo-44720 [https://bugs.python.org/issue?@action=redirect&bpo=44720]: weakref.proxy objects referencing non-iterators now raise TypeError rather than dereferencing the null tp_iternext slot and crashing.

bpo-44704 [https://bugs.python.org/issue?@action=redirect&bpo=44704]: The implementation of collections.abc.Set._hash() now matches that of frozenset.__hash__().

bpo-44666 [https://bugs.python.org/issue?@action=redirect&bpo=44666]: Fixed issue in compileall.compile_file() when sys.stdout is redirected. Patch by Stefan Hölzl.

bpo-44688 [https://bugs.python.org/issue?@action=redirect&bpo=44688]: sqlite3.Connection.create_collation() now accepts non-ASCII collation names. Patch by Erlend E. Aasland.

bpo-44690 [https://bugs.python.org/issue?@action=redirect&bpo=44690]: Adopt binacii.a2b_base64's strict mode in base64.b64decode.

bpo-42854 [https://bugs.python.org/issue?@action=redirect&bpo=42854]: Fixed a bug in the _ssl module that was throwing OverflowError when using _ssl._SSLSocket.write() and _ssl._SSLSocket.read() for a big value of the len parameter. Patch by Pablo Galindo

bpo-44686 [https://bugs.python.org/issue?@action=redirect&bpo=44686]: Replace unittest.mock._importer with pkgutil.resolve_name.

bpo-44353 [https://bugs.python.org/issue?@action=redirect&bpo=44353]: Make NewType.__call__ faster by implementing it in C. Patch provided by Yurii Karabas.

bpo-44682 [https://bugs.python.org/issue?@action=redirect&bpo=44682]: Change the pdb commands directive to disallow setting commands for an invalid breakpoint and to display an appropriate error.

bpo-44353 [https://bugs.python.org/issue?@action=redirect&bpo=44353]: Refactor typing.NewType from function into callable class. Patch provided by Yurii Karabas.

bpo-44678 [https://bugs.python.org/issue?@action=redirect&bpo=44678]: Added a separate error message for discontinuous padding in binascii.a2b_base64 strict mode.

bpo-44524 [https://bugs.python.org/issue?@action=redirect&bpo=44524]: Add missing __name__ and __qualname__ attributes to typing module classes. Patch provided by Yurii Karabas.

bpo-40897 [https://bugs.python.org/issue?@action=redirect&bpo=40897]: Give priority to using the current class constructor in inspect.signature(). Patch by Weipeng Hong.

bpo-44638 [https://bugs.python.org/issue?@action=redirect&bpo=44638]: Add a reference to the zipp project and hint as to how to use it.

bpo-44648 [https://bugs.python.org/issue?@action=redirect&bpo=44648]: Fixed wrong error being thrown by inspect.getsource() when examining a class in the interactive session. Instead of TypeError, it should be OSError with appropriate error message.

bpo-44608 [https://bugs.python.org/issue?@action=redirect&bpo=44608]: Fix memory leak in _tkinter._flatten() if it is called with a sequence or set, but not list or tuple.

bpo-44594 [https://bugs.python.org/issue?@action=redirect&bpo=44594]: Fix an edge case of ExitStack and AsyncExitStack exception chaining. They will now match with block behavior when __context__ is explicitly set to None when the exception is in flight.

bpo-42799 [https://bugs.python.org/issue?@action=redirect&bpo=42799]: In fnmatch, the cache size for compiled regex patterns (functools.lru_cache()) was bumped up from 256 to 32768, affecting functions: fnmatch.fnmatch(), fnmatch.fnmatchcase(), fnmatch.filter().

bpo-41928 [https://bugs.python.org/issue?@action=redirect&bpo=41928]: Update shutil.copyfile() to raise FileNotFoundError instead of confusing IsADirectoryError when a path ending with a os.path.sep does not exist; shutil.copy() and shutil.copy2() are also affected.

bpo-44569 [https://bugs.python.org/issue?@action=redirect&bpo=44569]: Added the StackSummary.format_frame() function in traceback. This allows users to customize the way individual lines are formatted in tracebacks without re-implementing logic to handle recursive tracebacks.

bpo-44566 [https://bugs.python.org/issue?@action=redirect&bpo=44566]: handle StopIteration subclass raised from @contextlib.contextmanager generator

bpo-44558 [https://bugs.python.org/issue?@action=redirect&bpo=44558]: Make the implementation consistency of indexOf() between C and Python versions. Patch by Donghee Na.

bpo-41249 [https://bugs.python.org/issue?@action=redirect&bpo=41249]: Fixes TypedDict to work with typing.get_type_hints() and postponed evaluation of annotations across modules.

bpo-44554 [https://bugs.python.org/issue?@action=redirect&bpo=44554]: Refactor argument processing in pdb.main() to simplify detection of errors in input loading and clarify behavior around module or script invocation.

bpo-34798 [https://bugs.python.org/issue?@action=redirect&bpo=34798]: Break up paragraph about pprint.PrettyPrinter construction parameters to make it easier to read.

bpo-44539 [https://bugs.python.org/issue?@action=redirect&bpo=44539]: Added support for recognizing JPEG files without JFIF or Exif markers.

bpo-44461 [https://bugs.python.org/issue?@action=redirect&bpo=44461]: Fix bug with pdb's handling of import error due to a package which does not have a __main__ module

bpo-43625 [https://bugs.python.org/issue?@action=redirect&bpo=43625]: Fix a bug in the detection of CSV file headers by csv.Sniffer.has_header() and improve documentation of same.

bpo-44516 [https://bugs.python.org/issue?@action=redirect&bpo=44516]: Update vendored pip to 21.1.3

bpo-42892 [https://bugs.python.org/issue?@action=redirect&bpo=42892]: Fixed an exception thrown while parsing a malformed multipart email by email.message.EmailMessage.

bpo-44468 [https://bugs.python.org/issue?@action=redirect&bpo=44468]: typing.get_type_hints() now finds annotations in classes and base classes with unexpected __module__. Previously, it skipped those MRO elements.

bpo-44491 [https://bugs.python.org/issue?@action=redirect&bpo=44491]: Allow clearing the sqlite3 authorizer callback by passing None to set_authorizer(). Patch by Erlend E. Aasland.

bpo-43977 [https://bugs.python.org/issue?@action=redirect&bpo=43977]: Set the proper Py_TPFLAGS_MAPPING and Py_TPFLAGS_SEQUENCE flags for subclasses created before a parent has been registered as a collections.abc.Mapping or collections.abc.Sequence.

bpo-44482 [https://bugs.python.org/issue?@action=redirect&bpo=44482]: Fix very unlikely resource leak in glob in alternate Python implementations.

bpo-44466 [https://bugs.python.org/issue?@action=redirect&bpo=44466]: The faulthandler module now detects if a fatal error occurs during a garbage collector collection. Patch by Victor Stinner.

bpo-44471 [https://bugs.python.org/issue?@action=redirect&bpo=44471]: A TypeError is now raised instead of an AttributeError in contextlib.ExitStack.enter_context() and contextlib.AsyncExitStack.enter_async_context() for objects which do not support the context manager or asynchronous context manager protocols correspondingly.

bpo-44404 [https://bugs.python.org/issue?@action=redirect&bpo=44404]: tkinter's after() method now supports callables without the __name__ attribute.

bpo-41546 [https://bugs.python.org/issue?@action=redirect&bpo=41546]: Make pprint (like the builtin print) not attempt to write to stdout when it is None.

bpo-44458 [https://bugs.python.org/issue?@action=redirect&bpo=44458]: BUFFER_BLOCK_SIZE is now declared static, to avoid linking collisions when bz2, lmza or zlib are statically linked.

bpo-44464 [https://bugs.python.org/issue?@action=redirect&bpo=44464]: Remove exception for flake8 in deprecated importlib.metadata interfaces. Sync with importlib_metadata 4.6.

bpo-44446 [https://bugs.python.org/issue?@action=redirect&bpo=44446]: Take into account that lineno might be None in traceback.FrameSummary.

bpo-44439 [https://bugs.python.org/issue?@action=redirect&bpo=44439]: Fix in bz2.BZ2File.write() / lzma.LZMAFile.write() methods, when the input data is an object that supports the buffer protocol, the file length may be wrong.

bpo-44434 [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.

bpo-42972 [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 Py_TPFLAGS_HAVE_GC flag. Patch by Victor Stinner.

bpo-44422 [https://bugs.python.org/issue?@action=redirect&bpo=44422]: The threading.enumerate() function now uses a reentrant lock to prevent a hang on reentrant call. Patch by Victor Stinner.

bpo-38291 [https://bugs.python.org/issue?@action=redirect&bpo=38291]: Importing typing.io or typing.re now prints a DeprecationWarning.

bpo-37880 [https://bugs.python.org/issue?@action=redirect&bpo=37880]: argparse actions store_const and append_const each receive a default value of None when the const kwarg is not provided. Previously, this raised a TypeError.

bpo-44389 [https://bugs.python.org/issue?@action=redirect&bpo=44389]: Fix deprecation of ssl.OP_NO_TLSv1_3

bpo-27827 [https://bugs.python.org/issue?@action=redirect&bpo=27827]: pathlib.PureWindowsPath.is_reserved() now identifies a greater range of reserved filenames, including those with trailing spaces or colons.

bpo-44395 [https://bugs.python.org/issue?@action=redirect&bpo=44395]: Fix as_string() to pass unixfrom properly. Patch by Donghee Na.

bpo-34266 [https://bugs.python.org/issue?@action=redirect&bpo=34266]: Handle exceptions from parsing the arg of pdb's run/restart command.

bpo-44362 [https://bugs.python.org/issue?@action=redirect&bpo=44362]: Improve ssl module's deprecation messages, error reporting, and documentation for deprecations.

bpo-44342 [https://bugs.python.org/issue?@action=redirect&bpo=44342]: [Enum] Change pickling from by-value to by-name.

bpo-44356 [https://bugs.python.org/issue?@action=redirect&bpo=44356]: [Enum] Allow multiple data-type mixins if they are all the same.

bpo-44351 [https://bugs.python.org/issue?@action=redirect&bpo=44351]: Restore back parse_makefile() in distutils.sysconfig because it behaves differently than the similar implementation in sysconfig.

bpo-35800 [https://bugs.python.org/issue?@action=redirect&bpo=35800]: smtpd.MailmanProxy is now removed as it is unusable without an external module, mailman. Patch by Donghee Na.

bpo-44357 [https://bugs.python.org/issue?@action=redirect&bpo=44357]: Added a function that returns cube root of the given number math.cbrt()

bpo-44339 [https://bugs.python.org/issue?@action=redirect&bpo=44339]: Change math.pow(±0.0, -math.inf) to return inf instead of raising ValueError. This brings the special-case handling of math.pow into compliance with the IEEE 754 standard.

bpo-44242 [https://bugs.python.org/issue?@action=redirect&bpo=44242]: Remove missing flag check from Enum creation and move into a verify decorator.

bpo-44246 [https://bugs.python.org/issue?@action=redirect&bpo=44246]: In importlib.metadata, restore compatibility in the result from Distribution.entry_points (EntryPoints) to honor expectations in older implementations and issuing deprecation warnings for these cases: A. EntryPoints objects are once again mutable, allowing for sort() and other list-based mutation operations. Avoid deprecation warnings by casting to a mutable sequence (e.g. list(dist.entry_points).sort()). B. EntryPoints results once again allow for access by index. To avoid deprecation warnings, cast the result to a Sequence first (e.g. tuple(dist.entry_points)[0]).

bpo-44246 [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.

bpo-43858 [https://bugs.python.org/issue?@action=redirect&bpo=43858]: Added a function that returns a copy of a dict of logging levels: logging.getLevelNamesMapping()

bpo-44260 [https://bugs.python.org/issue?@action=redirect&bpo=44260]: The random.Random constructor no longer reads system entropy without need.

bpo-44254 [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.

bpo-44258 [https://bugs.python.org/issue?@action=redirect&bpo=44258]: Support PEP 515 for Fraction's initialization from string.

bpo-44235 [https://bugs.python.org/issue?@action=redirect&bpo=44235]: Remove deprecated functions in the gettext. Patch by Donghee Na.

bpo-38693 [https://bugs.python.org/issue?@action=redirect&bpo=38693]: Prefer f-strings to .format in importlib.resources.

bpo-33693 [https://bugs.python.org/issue?@action=redirect&bpo=33693]: Importlib.metadata now prefers f-strings to .format.

bpo-44241 [https://bugs.python.org/issue?@action=redirect&bpo=44241]: Incorporate minor tweaks from importlib_metadata 4.1: SimplePath protocol, support for Metadata 2.2.

bpo-43216 [https://bugs.python.org/issue?@action=redirect&bpo=43216]: Remove the @asyncio.coroutine decorator enabling legacy generator-based coroutines to be compatible with async/await code; remove 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.

bpo-44210 [https://bugs.python.org/issue?@action=redirect&bpo=44210]: Make importlib.metadata._meta.PackageMetadata public.

bpo-43643 [https://bugs.python.org/issue?@action=redirect&bpo=43643]: Declare readers.MultiplexedPath.name as a property per the spec.

bpo-27334 [https://bugs.python.org/issue?@action=redirect&bpo=27334]: The sqlite3 context manager now performs a rollback (thus releasing the database lock) if commit failed. Patch by Luca Citi and Erlend E. Aasland.

bpo-4928 [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

bpo-44154 [https://bugs.python.org/issue?@action=redirect&bpo=44154]: Optimize fractions.Fraction pickling for large components.

bpo-33433 [https://bugs.python.org/issue?@action=redirect&bpo=33433]: For IPv4 mapped IPv6 addresses (RFC 4291 [https://datatracker.ietf.org/doc/html/rfc4291.html] Section 2.5.5.2), the 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.

bpo-44150 [https://bugs.python.org/issue?@action=redirect&bpo=44150]: Add optional weights argument to statistics.fmean().

bpo-44142 [https://bugs.python.org/issue?@action=redirect&bpo=44142]: ast.unparse() will now drop the redundant parentheses when tuples used as assignment targets (e.g in for loops).

bpo-44145 [https://bugs.python.org/issue?@action=redirect&bpo=44145]: hmac computations were not releasing the GIL while calling the OpenSSL HMAC_Update C API (a new feature in 3.9). This unintentionally prevented parallel computation as other hashlib algorithms support.

bpo-44095 [https://bugs.python.org/issue?@action=redirect&bpo=44095]: zipfile.Path now supports zipfile.Path.stem, zipfile.Path.suffixes, and zipfile.Path.suffix attributes.

bpo-44077 [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 socket.IP_RECVTOS.

bpo-37788 [https://bugs.python.org/issue?@action=redirect&bpo=37788]: Fix a reference leak when a Thread object is never joined.

bpo-38908 [https://bugs.python.org/issue?@action=redirect&bpo=38908]: Subclasses of typing.Protocol which only have data variables declared will now raise a TypeError when checked with isinstance unless they are decorated with runtime_checkable(). Previously, these checks passed silently. Patch provided by Yurii Karabas.

bpo-44098 [https://bugs.python.org/issue?@action=redirect&bpo=44098]: typing.ParamSpec will no longer be found in the __parameters__ of most typing generics except in valid use locations specified by PEP 612 [https://peps.python.org/pep-0612/]. This prevents incorrect usage like typing.List[P][int]. This change means incorrect usage which may have passed silently in 3.10 beta 1 and earlier will now error.

bpo-44089 [https://bugs.python.org/issue?@action=redirect&bpo=44089]: Allow subclassing csv.Error in 3.10 (it was allowed in 3.9 and earlier but was disallowed in early versions of 3.10).

bpo-44081 [https://bugs.python.org/issue?@action=redirect&bpo=44081]: ast.unparse() now doesn't use redundant spaces to separate lambda and the : if there are no parameters.

bpo-44061 [https://bugs.python.org/issue?@action=redirect&bpo=44061]: Fix regression in previous release when calling pkgutil.iter_modules() with a list of pathlib.Path objects

bpo-44059 [https://bugs.python.org/issue?@action=redirect&bpo=44059]: Register the SerenityOS Browser in the webbrowser module.

bpo-36515 [https://bugs.python.org/issue?@action=redirect&bpo=36515]: The hashlib module no longer does unaligned memory accesses when compiled for ARM platforms.

bpo-40465 [https://bugs.python.org/issue?@action=redirect&bpo=40465]: Remove random module features deprecated in Python 3.9.

bpo-44018 [https://bugs.python.org/issue?@action=redirect&bpo=44018]: random.seed() no longer mutates bytearray inputs.

bpo-38352 [https://bugs.python.org/issue?@action=redirect&bpo=38352]: Add IO, BinaryIO, TextIO, Match, and Pattern to typing.__all__. Patch by Jelle Zijlstra.

bpo-44002 [https://bugs.python.org/issue?@action=redirect&bpo=44002]: urllib.parse now uses functool.lru_cache() for its internal URL splitting and quoting caches instead of rolling its own like its the '90s.

The undocumented internal urllib.parse Quoted class API is now deprecated, for removal in 3.14.

bpo-43972 [https://bugs.python.org/issue?@action=redirect&bpo=43972]: When http.server.SimpleHTTPRequestHandler sends a 301 (Moved Permanently) for a directory path not ending with /, add a Content-Length: 0 header. This improves the behavior for certain clients.

bpo-28528 [https://bugs.python.org/issue?@action=redirect&bpo=28528]: Fix a bug in pdb where checkline() raises AttributeError if it is called after reset().

bpo-43853 [https://bugs.python.org/issue?@action=redirect&bpo=43853]: Improved string handling for sqlite3 user-defined functions and aggregates:

It is now possible to pass strings with embedded null characters to UDFs

Conversion failures now correctly raise MemoryError

Patch by Erlend E. Aasland.

bpo-43666 [https://bugs.python.org/issue?@action=redirect&bpo=43666]: AIX: 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.

bpo-43650 [https://bugs.python.org/issue?@action=redirect&bpo=43650]: Fix MemoryError in shutil.unpack_archive() which fails inside shutil._unpack_zipfile() on large files. Patch by Igor Bolshakov.

bpo-43612 [https://bugs.python.org/issue?@action=redirect&bpo=43612]: 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 zlib.compressobj. It also provides a faster alternative to gzip.compress when wbits=31 is used.

bpo-43392 [https://bugs.python.org/issue?@action=redirect&bpo=43392]: 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 importlib.import_module() and importlib.__import__().

bpo-43318 [https://bugs.python.org/issue?@action=redirect&bpo=43318]: Fix a bug where pdb does not always echo cleared breakpoints.

bpo-43234 [https://bugs.python.org/issue?@action=redirect&bpo=43234]: Prohibit passing non-concurrent.futures.ThreadPoolExecutor executors to loop.set_default_executor() following a deprecation in Python 3.8. Patch by Illia Volochii.

bpo-43232 [https://bugs.python.org/issue?@action=redirect&bpo=43232]: Prohibit previously deprecated potentially disruptive operations on asyncio.trsock.TransportSocket. Patch by Illia Volochii.

bpo-30077 [https://bugs.python.org/issue?@action=redirect&bpo=30077]: Added support for Apple's aifc/sowt pseudo-compression

bpo-42971 [https://bugs.python.org/issue?@action=redirect&bpo=42971]: Add definition of errno.EQFULL for platforms that define this constant (such as macOS).

bpo-43086 [https://bugs.python.org/issue?@action=redirect&bpo=43086]: Added a new optional strict_mode parameter to binascii.a2b_base64. When scrict_mode is set to 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.

bpo-43024 [https://bugs.python.org/issue?@action=redirect&bpo=43024]: Improve the help signature of traceback.print_exception(), traceback.format_exception() and traceback.format_exception_only().

bpo-33809 [https://bugs.python.org/issue?@action=redirect&bpo=33809]: Add the traceback.TracebackException.print() method which prints the formatted exception information.

bpo-42862 [https://bugs.python.org/issue?@action=redirect&bpo=42862]: sqlite3 now utilizes 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.

bpo-41818 [https://bugs.python.org/issue?@action=redirect&bpo=41818]: Soumendra Ganguly: add termios.tcgetwinsize(), termios.tcsetwinsize().

bpo-40497 [https://bugs.python.org/issue?@action=redirect&bpo=40497]: subprocess.check_output() now raises ValueError when the invalid keyword argument check is passed by user code. Previously such use would fail later with a TypeError. Patch by Rémi Lapeyre.

bpo-37449 [https://bugs.python.org/issue?@action=redirect&bpo=37449]: ensurepip now uses importlib.resources.files() traversable APIs

bpo-40956 [https://bugs.python.org/issue?@action=redirect&bpo=40956]: Use Argument Clinic in sqlite3. Patches by Erlend E. Aasland.

bpo-41730 [https://bugs.python.org/issue?@action=redirect&bpo=41730]: DeprecationWarning is now raised when importing tkinter.tix, which has been deprecated in documentation since Python 3.6.

bpo-20684 [https://bugs.python.org/issue?@action=redirect&bpo=20684]: Remove unused _signature_get_bound_param function from inspect - by Anthony Sottile.

bpo-41402 [https://bugs.python.org/issue?@action=redirect&bpo=41402]: Fix email.message.EmailMessage.set_content() when called with binary data and 7bit content transfer encoding.

bpo-32695 [https://bugs.python.org/issue?@action=redirect&bpo=32695]: The compresslevel and preset keyword arguments of tarfile.open() are now both documented and tested.

bpo-41137 [https://bugs.python.org/issue?@action=redirect&bpo=41137]: Use utf-8 encoding while reading .pdbrc files. Patch by Srinivas Reddy Thatiparthy

bpo-24391 [https://bugs.python.org/issue?@action=redirect&bpo=24391]: Improved reprs of threading synchronization objects: Semaphore, BoundedSemaphore, Event and Barrier.

bpo-5846 [https://bugs.python.org/issue?@action=redirect&bpo=5846]: Deprecated the following unittest functions, scheduled for removal in Python 3.13:

findTestCases()

makeSuite()

getTestCaseNames()

Use TestLoader methods instead:

unittest.TestLoader.loadTestsFromModule()

unittest.TestLoader.loadTestsFromTestCase()

unittest.TestLoader.getTestCaseNames()

Patch by Erlend E. Aasland.

bpo-40563 [https://bugs.python.org/issue?@action=redirect&bpo=40563]: Support pathlike objects on dbm/shelve. Patch by Hakan Çelik and Henry-Joseph Audéoud.

bpo-34990 [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.

bpo-39549 [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.

bpo-37022 [https://bugs.python.org/issue?@action=redirect&bpo=37022]: pdb now displays exceptions from repr() with its p and pp commands.

bpo-38840 [https://bugs.python.org/issue?@action=redirect&bpo=38840]: Fix test___all__ on platforms lacking a shared memory implementation.

bpo-39359 [https://bugs.python.org/issue?@action=redirect&bpo=39359]: Add one missing check that the password is a bytes object for an encrypted zipfile.

bpo-38741 [https://bugs.python.org/issue?@action=redirect&bpo=38741]: configparser: using ']' inside a section header will no longer cut the section name short at the ']'

bpo-38415 [https://bugs.python.org/issue?@action=redirect&bpo=38415]: Added missing behavior to contextlib.asynccontextmanager() to match contextlib.contextmanager() so decorated functions can themselves be decorators.

bpo-30256 [https://bugs.python.org/issue?@action=redirect&bpo=30256]: Pass multiprocessing BaseProxy argument manager_owned through AutoProxy.

bpo-27513 [https://bugs.python.org/issue?@action=redirect&bpo=27513]: email.utils.getaddresses() now accepts email.header.Header objects along with string values. Patch by Zackery Spytz.

bpo-16379 [https://bugs.python.org/issue?@action=redirect&bpo=16379]: Add SQLite error code and name to sqlite3 exceptions. Patch by Aviv Palivoda, Daniel Shahaf, and Erlend E. Aasland.

bpo-26228 [https://bugs.python.org/issue?@action=redirect&bpo=26228]: pty.spawn no longer hangs on FreeBSD, macOS, and Solaris.

bpo-33349 [https://bugs.python.org/issue?@action=redirect&bpo=33349]: lib2to3 now recognizes async generators everywhere.

bpo-29298 [https://bugs.python.org/issue?@action=redirect&bpo=29298]: Fix TypeError when required subparsers without dest do not receive arguments. Patch by Anthony Sottile.

Documentation

bpo-45216 [https://bugs.python.org/issue?@action=redirect&bpo=45216]: Remove extra documentation listing methods in difflib. It was rendering twice in pydoc and was outdated in some places.

bpo-45024 [https://bugs.python.org/issue?@action=redirect&bpo=45024]: 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 special methods. Patch by Raymond Hettinger.

bpo-44957 [https://bugs.python.org/issue?@action=redirect&bpo=44957]: Promote PEP 604 union syntax by using it where possible. Also, mention X | Y more prominently in section about Union and mention X | None at all in section about Optional.

bpo-16580 [https://bugs.python.org/issue?@action=redirect&bpo=16580]: Added code equivalents for the int.to_bytes() and int.from_bytes() methods, as well as tests ensuring that these code equivalents are valid.

bpo-44903 [https://bugs.python.org/issue?@action=redirect&bpo=44903]: Removed the 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 [https://wiki.python.org/moin/GuiProgramming].

bpo-33479 [https://bugs.python.org/issue?@action=redirect&bpo=33479]: Tkinter documentation has been greatly expanded with new "Architecture" and "Threading model" sections.

bpo-36700 [https://bugs.python.org/issue?@action=redirect&bpo=36700]: base64 RFC references were updated to point to RFC 4648 [https://datatracker.ietf.org/doc/html/rfc4648.html]; a section was added to point users to the new "security considerations" section of the RFC.

bpo-44740 [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.

bpo-44693 [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.

bpo-35183 [https://bugs.python.org/issue?@action=redirect&bpo=35183]: Add typical examples to os.path.splitext docs

bpo-30511 [https://bugs.python.org/issue?@action=redirect&bpo=30511]: Clarify that shutil.make_archive() is not thread-safe due to reliance on changing the current working directory.

bpo-44561 [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".

bpo-44651 [https://bugs.python.org/issue?@action=redirect&bpo=44651]: Delete entry "coercion" in Doc/glossary.rst for its outdated definition.

bpo-42958 [https://bugs.python.org/issue?@action=redirect&bpo=42958]: Updated the docstring and docs of filecmp.cmp() to be more accurate and less confusing especially in respect to shallow arg.

bpo-44631 [https://bugs.python.org/issue?@action=redirect&bpo=44631]: Refactored the repr() code of the _Environ (os module).

bpo-44613 [https://bugs.python.org/issue?@action=redirect&bpo=44613]: importlib.metadata is no longer provisional.

bpo-44558 [https://bugs.python.org/issue?@action=redirect&bpo=44558]: Match the docstring and python implementation of countOf() to the behavior of its c implementation.

bpo-44544 [https://bugs.python.org/issue?@action=redirect&bpo=44544]: List all kwargs for textwrap.wrap(), textwrap.fill(), and textwrap.shorten(). Now, there are nav links to attributes of TextWrap, which makes navigation much easier while minimizing duplication in the documentation.

bpo-38062 [https://bugs.python.org/issue?@action=redirect&bpo=38062]: Clarify that atexit uses equality comparisons internally.

bpo-40620 [https://bugs.python.org/issue?@action=redirect&bpo=40620]: Convert examples in tutorial controlflow.rst section 4.3 to be interpreter-demo style.

bpo-43066 [https://bugs.python.org/issue?@action=redirect&bpo=43066]: Added a warning to zipfile docs: filename arg with a leading slash may cause archive to be un-openable on Windows systems.

bpo-39452 [https://bugs.python.org/issue?@action=redirect&bpo=39452]: Rewrote Doc/library/__main__.rst. Broadened scope of the document to explicitly discuss and differentiate between __main__.py in packages versus the __name__ == '__main__' expression (and the idioms that surround it).

bpo-13814 [https://bugs.python.org/issue?@action=redirect&bpo=13814]: In the Design FAQ, answer "Why don't generators support the with statement?"

bpo-27752 [https://bugs.python.org/issue?@action=redirect&bpo=27752]: Documentation of csv.Dialect is more descriptive.

bpo-44453 [https://bugs.python.org/issue?@action=redirect&bpo=44453]: Fix documentation for the return type of sysconfig.get_path().

bpo-44392 [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 Py_GenericAlias and Py_GenericAliasType.

bpo-38291 [https://bugs.python.org/issue?@action=redirect&bpo=38291]: Mark typing.io and typing.re as deprecated since Python 3.8 in the documentation. They were never properly supported by type checkers.

bpo-44322 [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.

bpo-42392 [https://bugs.python.org/issue?@action=redirect&bpo=42392]: Document the deprecation and removal of the loop parameter for many functions and classes in asyncio.

bpo-44195 [https://bugs.python.org/issue?@action=redirect&bpo=44195]: Corrected references to TraversableResources in docs. There is no TraversableReader.

bpo-41963 [https://bugs.python.org/issue?@action=redirect&bpo=41963]: Document that ConfigParser strips off comments when reading configuration files.

bpo-44072 [https://bugs.python.org/issue?@action=redirect&bpo=44072]: Correct where in the numeric ABC hierarchy ** support is added, i.e., in numbers.Complex, not numbers.Integral.

bpo-43558 [https://bugs.python.org/issue?@action=redirect&bpo=43558]: Add the remark to dataclasses documentation that the __init__() of any base class has to be called in __post_init__(), along with a code example.

bpo-44025 [https://bugs.python.org/issue?@action=redirect&bpo=44025]: Clarify when '_' in match statements is a keyword, and when not.

bpo-41706 [https://bugs.python.org/issue?@action=redirect&bpo=41706]: Fix docs about how methods like __add__ are invoked when evaluating operator expressions.

bpo-41621 [https://bugs.python.org/issue?@action=redirect&bpo=41621]: Document that collections.defaultdict parameter default_factory defaults to None and is positional-only.

bpo-41576 [https://bugs.python.org/issue?@action=redirect&bpo=41576]: document BaseException in favor of bare except

bpo-21760 [https://bugs.python.org/issue?@action=redirect&bpo=21760]: The description for __file__ fixed. Patch by Furkan Onder

bpo-39498 [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.

bpo-33479 [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,

Tests

bpo-40173 [https://bugs.python.org/issue?@action=redirect&bpo=40173]: Fix test.support.import_helper.import_fresh_module().

bpo-45280 [https://bugs.python.org/issue?@action=redirect&bpo=45280]: Add a test case for empty typing.NamedTuple.

bpo-45269 [https://bugs.python.org/issue?@action=redirect&bpo=45269]: Cover case when invalid markers type is supplied to c_make_encoder.

bpo-45128 [https://bugs.python.org/issue?@action=redirect&bpo=45128]: Fix test_multiprocessing_fork failure due to test_logging and sys.modules manipulation.

bpo-45209 [https://bugs.python.org/issue?@action=redirect&bpo=45209]: Fix UserWarning: resource_tracker warning in _test_multiprocessing._TestSharedMemory.test_shared_memory_cleaned_after_process_termination

bpo-45185 [https://bugs.python.org/issue?@action=redirect&bpo=45185]: Enables TestEnumerations test cases in test_ssl suite.

bpo-45195 [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.

bpo-45156 [https://bugs.python.org/issue?@action=redirect&bpo=45156]: Fixes infinite loop on unittest.mock.seal() of mocks created by create_autospec().

bpo-45125 [https://bugs.python.org/issue?@action=redirect&bpo=45125]: Improves pickling tests and docs of SharedMemory and SharableList objects.

bpo-44860 [https://bugs.python.org/issue?@action=redirect&bpo=44860]: Update test_sysconfig.test_user_similar() for the posix_user scheme: platlib doesn't use sys.platlibdir. Patch by Victor Stinner.

bpo-45052 [https://bugs.python.org/issue?@action=redirect&bpo=45052]: WithProcessesTestSharedMemory.test_shared_memory_basics test was ignored, because 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 size of SharedMemory is not ever guaranteed to be the same. It is decided by the platform.

bpo-44895 [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.

bpo-45042 [https://bugs.python.org/issue?@action=redirect&bpo=45042]: Fixes that test classes decorated with @hashlib_helper.requires_hashdigest were skipped all the time.

bpo-25130 [https://bugs.python.org/issue?@action=redirect&bpo=25130]: Add calls of gc.collect() in tests to support PyPy.

bpo-45011 [https://bugs.python.org/issue?@action=redirect&bpo=45011]: Made tests relying on the _asyncio C extension module optional to allow running on alternative Python implementations. Patch by Serhiy Storchaka.

bpo-44949 [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.

bpo-44891 [https://bugs.python.org/issue?@action=redirect&bpo=44891]: Tests were added to clarify id() is preserved when obj * 1 is used on str and bytes objects. Patch by Nikita Sobolev.

bpo-44852 [https://bugs.python.org/issue?@action=redirect&bpo=44852]: Add ability to wholesale silence DeprecationWarnings while running the regression test suite.

bpo-40928 [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.

bpo-44734 [https://bugs.python.org/issue?@action=redirect&bpo=44734]: Fixed floating point precision issue in turtle tests.

bpo-44708 [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.

bpo-42095 [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.

bpo-44647 [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.

bpo-44515 [https://bugs.python.org/issue?@action=redirect&bpo=44515]: Adjust recently added contextlib tests to avoid assuming the use of a refcounted GC

bpo-44287 [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 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.

bpo-44451 [https://bugs.python.org/issue?@action=redirect&bpo=44451]: Reset DeprecationWarning filters in test.test_importlib.test_metadata_api.APITests.test_entry_points_by_index to avoid StopIteration error if DeprecationWarnings are ignored.

bpo-44363 [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.

bpo-44364 [https://bugs.python.org/issue?@action=redirect&bpo=44364]: Add non integral tests for math.sqrt() function.

bpo-43921 [https://bugs.python.org/issue?@action=redirect&bpo=43921]: Fix test_ssl.test_wrong_cert_tls13(): use suppress_ragged_eofs=False, since read() can raise ssl.SSLEOFError on Windows. Patch by Victor Stinner.

bpo-43921 [https://bugs.python.org/issue?@action=redirect&bpo=43921]: Fix test_pha_required_nocert() of test_ssl: catch two more EOF cases (when the recv() method returns an empty string). Patch by Victor Stinner.

bpo-44131 [https://bugs.python.org/issue?@action=redirect&bpo=44131]: Add test_frozenmain to test_embed to test the Py_FrozenMain() C function. Patch by Victor Stinner.

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Ignore error string case in test_file_not_exists().

bpo-42083 [https://bugs.python.org/issue?@action=redirect&bpo=42083]: Add test to check that PyStructSequence_NewType accepts a PyStructSequence_Desc with doc field set to NULL.

bpo-35753 [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.

bpo-30256 [https://bugs.python.org/issue?@action=redirect&bpo=30256]: Add test for nested queues when using multiprocessing shared objects AutoProxy[Queue] inside ListProxy and DictProxy

Build

bpo-45220 [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 DefaultWindowsSDKVersion environment variable before building.

bpo-45020 [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.

bpo-45188 [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.

bpo-45163 [https://bugs.python.org/issue?@action=redirect&bpo=45163]: Fixes Haiku platform build.

bpo-45067 [https://bugs.python.org/issue?@action=redirect&bpo=45067]: The ncurses function extended_color_content was introduced in 2017

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

bpo-45019 [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.

bpo-44340 [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.

bpo-44535 [https://bugs.python.org/issue?@action=redirect&bpo=44535]: Enable building using a Visual Studio 2022 install on Windows.

bpo-43298 [https://bugs.python.org/issue?@action=redirect&bpo=43298]: Improved error message when building without a Windows SDK installed.

bpo-44381 [https://bugs.python.org/issue?@action=redirect&bpo=44381]: The Windows build now accepts EnableControlFlowGuard set to guard to enable CFG.

bpo-41282 [https://bugs.python.org/issue?@action=redirect&bpo=41282]: Fix broken make install that caused standard library extension modules to be unnecessarily and incorrectly rebuilt during the install phase of cpython.

Windows

bpo-45375 [https://bugs.python.org/issue?@action=redirect&bpo=45375]: Fixes an assertion failure due to searching for the standard library in unnormalised paths.

bpo-45022 [https://bugs.python.org/issue?@action=redirect&bpo=45022]: Update Windows release to include libffi 3.4.2

bpo-45007 [https://bugs.python.org/issue?@action=redirect&bpo=45007]: Update to OpenSSL 1.1.1l in Windows build

bpo-44848 [https://bugs.python.org/issue?@action=redirect&bpo=44848]: Upgrade Windows installer to use SQLite 3.36.0.

bpo-44572 [https://bugs.python.org/issue?@action=redirect&bpo=44572]: Avoid consuming standard input in the platform module

bpo-44582 [https://bugs.python.org/issue?@action=redirect&bpo=44582]: Accelerate speed of mimetypes initialization using a native implementation of the registry scan.

bpo-41299 [https://bugs.python.org/issue?@action=redirect&bpo=41299]: Fix 16 milliseconds jitter when using timeouts in threading, such as with threading.Lock.acquire() or threading.Condition.wait().

bpo-42686 [https://bugs.python.org/issue?@action=redirect&bpo=42686]: Build sqlite3 with math functions enabled. Patch by Erlend E. Aasland.

bpo-40263 [https://bugs.python.org/issue?@action=redirect&bpo=40263]: This is a follow-on bug from https://bugs.python.org/issue26903. Once that is applied we run into an off-by-one assertion problem. The assert was not correct.

macOS

bpo-45007 [https://bugs.python.org/issue?@action=redirect&bpo=45007]: Update macOS installer builds to use OpenSSL 1.1.1l.

bpo-34602 [https://bugs.python.org/issue?@action=redirect&bpo=34602]: When building CPython on macOS with ./configure --with-undefined-behavior-sanitizer --with-pydebug, the stack size is now quadrupled to allow for the entire test suite to pass.

bpo-44848 [https://bugs.python.org/issue?@action=redirect&bpo=44848]: Update macOS installer to use SQLite 3.36.0.

bpo-44689 [https://bugs.python.org/issue?@action=redirect&bpo=44689]: 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, find_library was not able to find macOS system libraries when running on Big Sur due to changes in how system libraries are stored.

bpo-41972 [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.

bpo-43109 [https://bugs.python.org/issue?@action=redirect&bpo=43109]: Allow --with-lto configure option to work with Apple-supplied Xcode or Command Line Tools.

bpo-34932 [https://bugs.python.org/issue?@action=redirect&bpo=34932]: Add socket.TCP_KEEPALIVE support for macOS. Patch by Shane Harvey.

IDLE

bpo-45296 [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.

bpo-45193 [https://bugs.python.org/issue?@action=redirect&bpo=45193]: Make completion boxes appear on Ubuntu again.

bpo-40128 [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.

bpo-33962 [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.

bpo-40468 [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.

bpo-41611 [https://bugs.python.org/issue?@action=redirect&bpo=41611]: Avoid uncaught exceptions in AutoCompleteWindow.winconfig_event().

bpo-41611 [https://bugs.python.org/issue?@action=redirect&bpo=41611]: Fix IDLE sometimes freezing upon tab-completion on macOS.

bpo-44010 [https://bugs.python.org/issue?@action=redirect&bpo=44010]: Highlight the new match statement's soft keywords: match, case, and _. However, this highlighting is not perfect and will be incorrect in some rare cases, including some _-s in case patterns.

bpo-44026 [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.

Tools/Demos

bpo-44786 [https://bugs.python.org/issue?@action=redirect&bpo=44786]: Fix a warning in regular expression in the c-analyzer script.

bpo-44967 [https://bugs.python.org/issue?@action=redirect&bpo=44967]: pydoc now returns a non-zero status code when a module cannot be found.

bpo-44978 [https://bugs.python.org/issue?@action=redirect&bpo=44978]: Allow the Argument Clinic tool to handle __complex__ special methods.

bpo-43425 [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

bpo-44074 [https://bugs.python.org/issue?@action=redirect&bpo=44074]: Make patchcheck automatically detect the correct base branch name (previously it was hardcoded to 'master')

bpo-20291 [https://bugs.python.org/issue?@action=redirect&bpo=20291]: Added support for variadic positional parameters in Argument Clinic.

C API

bpo-41710 [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.

bpo-44687 [https://bugs.python.org/issue?@action=redirect&bpo=44687]: BufferedReader.peek() no longer raises ValueError when the entire file has already been buffered.

bpo-45116 [https://bugs.python.org/issue?@action=redirect&bpo=45116]: Add the 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.

bpo-45094 [https://bugs.python.org/issue?@action=redirect&bpo=45094]: Add the Py_NO_INLINE macro to disable inlining on a function. Patch by Victor Stinner.

bpo-45061 [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. Patch by Victor Stinner.

bpo-42035 [https://bugs.python.org/issue?@action=redirect&bpo=42035]: Add a new PyType_GetQualName() function to get type's qualified name.

bpo-41103 [https://bugs.python.org/issue?@action=redirect&bpo=41103]: Reverts removal of the old buffer protocol because they are part of stable ABI.

bpo-44751 [https://bugs.python.org/issue?@action=redirect&bpo=44751]: Remove crypt.h include from the public Python.h header.

bpo-42747 [https://bugs.python.org/issue?@action=redirect&bpo=42747]: The Py_TPFLAGS_HAVE_VERSION_TAG type flag now does nothing. The 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.

bpo-44530 [https://bugs.python.org/issue?@action=redirect&bpo=44530]: Added the co_qualname to the PyCodeObject structure to propagate the qualified name from the compiler to code objects.

Patch by Gabriele N. Tornetta

bpo-44441 [https://bugs.python.org/issue?@action=redirect&bpo=44441]: Py_RunMain() now resets PyImport_Inittab to its initial value at exit. It must be possible to call PyImport_AppendInittab() or PyImport_ExtendInittab() at each Python initialization. Patch by Victor Stinner.

bpo-39947 [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:

_PyTrash_deposit_object()

_PyTrash_destroy_chain()

_PyTrash_thread_deposit_object()

_PyTrash_thread_destroy_chain()

The trashcan C API was never usable with the limited C API, since old trashcan macros accessed directly PyThreadState members like _tstate->trash_delete_nesting, whereas the PyThreadState structure is opaque in the limited C API.

Exclude also the PyTrash_UNWIND_LEVEL constant from the C API.

Patch by Victor Stinner.

bpo-40939 [https://bugs.python.org/issue?@action=redirect&bpo=40939]: Removed documentation for the removed PyParser_* C API.

bpo-43795 [https://bugs.python.org/issue?@action=redirect&bpo=43795]: The list in 限定版APIの内容 now shows the public name PyFrameObject rather than _frame. The non-existing entry _node no longer appears in the list.

bpo-44378 [https://bugs.python.org/issue?@action=redirect&bpo=44378]: Py_IS_TYPE() no longer uses Py_TYPE() to avoid a compiler warning: no longer cast const PyObject* to PyObject*. Patch by Victor Stinner.

bpo-39573 [https://bugs.python.org/issue?@action=redirect&bpo=39573]: Convert the Py_TYPE() and Py_SIZE() macros to static inline functions. The Py_SET_TYPE() and Py_SET_SIZE() functions must now be used to set an object type and size. Patch by Victor Stinner.

bpo-44263 [https://bugs.python.org/issue?@action=redirect&bpo=44263]: The PyType_Ready() function now raises an error if a type is defined with the Py_TPFLAGS_HAVE_GC flag set but has no traverse function (PyTypeObject.tp_traverse). Patch by Victor Stinner.

bpo-43795 [https://bugs.python.org/issue?@action=redirect&bpo=43795]: The undocumented function Py_FrozenMain() is removed from the Limited API.

bpo-44113 [https://bugs.python.org/issue?@action=redirect&bpo=44113]: Deprecate the following functions to configure the Python initialization:

PySys_AddWarnOptionUnicode()

PySys_AddWarnOption()

PySys_AddXOption()

PySys_HasWarnOptions()

Py_SetPath()

Py_SetProgramName()

Py_SetPythonHome()

Py_SetStandardStreamEncoding()

_Py_SetProgramFullPath()

Use the new PyConfig API of the Python Initialization Configuration instead (PEP 587 [https://peps.python.org/pep-0587/]).

bpo-44094 [https://bugs.python.org/issue?@action=redirect&bpo=44094]: Remove PyErr_SetFromErrnoWithUnicodeFilename(), PyErr_SetFromWindowsErrWithUnicodeFilename(), and PyErr_SetExcFromWindowsErrWithUnicodeFilename(). They are not documented and have been deprecated since Python 3.3.

bpo-43795 [https://bugs.python.org/issue?@action=redirect&bpo=43795]: PyCodec_Unregister() is now properly exported as a function in the Windows Stable ABI DLL.

bpo-44029 [https://bugs.python.org/issue?@action=redirect&bpo=44029]: Remove deprecated Py_UNICODE APIs: PyUnicode_Encode, PyUnicode_EncodeUTF7, PyUnicode_EncodeUTF8, PyUnicode_EncodeUTF16, PyUnicode_EncodeUTF32, PyUnicode_EncodeLatin1, PyUnicode_EncodeMBCS, PyUnicode_EncodeDecimal, PyUnicode_EncodeRawUnicodeEscape, PyUnicode_EncodeCharmap, PyUnicode_EncodeUnicodeEscape, PyUnicode_TransformDecimalToASCII, PyUnicode_TranslateCharmap, PyUnicodeEncodeError_Create, PyUnicodeTranslateError_Create. See PEP 393 [https://peps.python.org/pep-0393/] and PEP 624 [https://peps.python.org/pep-0624/] for reference.

bpo-42035 [https://bugs.python.org/issue?@action=redirect&bpo=42035]: Add a new PyType_GetName() function to get type's short name.

Python 3.10.0 beta 1

Release date: 2021-05-03

Security

bpo-43434 [https://bugs.python.org/issue?@action=redirect&bpo=43434]: Creating sqlite3.Connection objects now also produces sqlite3.connect and sqlite3.connect/handle auditing events. Previously these events were only produced by sqlite3.connect() calls. Patch by Erlend E. Aasland.

bpo-43998 [https://bugs.python.org/issue?@action=redirect&bpo=43998]: The 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. SSLContext defaults to minimum protocol version TLS 1.2. Settings are based on Hynek Schlawack's research.

bpo-43882 [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 urllib.parse() now removes ASCII newlines and tabs from URLs, preventing such attacks.

bpo-43472 [https://bugs.python.org/issue?@action=redirect&bpo=43472]: Ensures interpreter-level audit hooks receive the cpython.PyInterpreterState_New event when called through the _xxsubinterpreters module.

bpo-43362 [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.

bpo-43762 [https://bugs.python.org/issue?@action=redirect&bpo=43762]: Add audit events for sqlite3.connect/handle(), sqlite3.Connection.enable_load_extension(), and sqlite3.Connection.load_extension(). Patch by Erlend E. Aasland.

bpo-43756 [https://bugs.python.org/issue?@action=redirect&bpo=43756]: Add new audit event glob.glob/2 to incorporate the new root_dir and dir_fd arguments added to glob.glob() and glob.iglob().

bpo-36384 [https://bugs.python.org/issue?@action=redirect&bpo=36384]: 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 socket.inet_aton() treats leading zeros as octal notation. glibc implementation of modern inet_pton() does not accept any leading zeros. For a while the ipaddress module used to accept ambiguous leading zeros.

bpo-43075 [https://bugs.python.org/issue?@action=redirect&bpo=43075]: Fix Regular Expression Denial of Service (ReDoS) vulnerability in 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.

bpo-42800 [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.

bpo-37363 [https://bugs.python.org/issue?@action=redirect&bpo=37363]: Add audit events to the http.client module.

Core and Builtins

bpo-43977 [https://bugs.python.org/issue?@action=redirect&bpo=43977]: Prevent classes being both a sequence and a mapping when pattern matching.

bpo-43977 [https://bugs.python.org/issue?@action=redirect&bpo=43977]: Use tp_flags on the class object to determine if the subject is a sequence or mapping when pattern matching. Avoids the need to import collections.abc when pattern matching.

bpo-43892 [https://bugs.python.org/issue?@action=redirect&bpo=43892]: Restore proper validation of complex literal value patterns when parsing match blocks.

bpo-43933 [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 __exit__.

bpo-43933 [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.

bpo-43963 [https://bugs.python.org/issue?@action=redirect&bpo=43963]: Importing the _signal module in a subinterpreter has no longer side effects.

bpo-42739 [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 PyLineTable_InitAddressRange. This makes the handling of line number tables more robust in some circumstances.

bpo-43908 [https://bugs.python.org/issue?@action=redirect&bpo=43908]: Make re types immutable. Patch by Erlend E. Aasland.

bpo-43908 [https://bugs.python.org/issue?@action=redirect&bpo=43908]: Make the array.array type immutable. Patch by Erlend E. Aasland.

bpo-43901 [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.

bpo-43892 [https://bugs.python.org/issue?@action=redirect&bpo=43892]: Match patterns now use new dedicated AST nodes (MatchValue, MatchSingleton, MatchSequence, MatchStar, MatchMapping, MatchClass) rather than reusing expression AST nodes. MatchAs and MatchOr are now defined as pattern nodes rather than as expression nodes. Patch by Nick Coghlan.

bpo-42725 [https://bugs.python.org/issue?@action=redirect&bpo=42725]: Usage of await/yield/yield from and named expressions within an annotation is now forbidden when PEP 563 is activated.

bpo-43754 [https://bugs.python.org/issue?@action=redirect&bpo=43754]: When performing structural pattern matching (PEP 634 [https://peps.python.org/pep-0634/]), captured names are now left unbound until the entire pattern has matched successfully.

bpo-42737 [https://bugs.python.org/issue?@action=redirect&bpo=42737]: Annotations for complex targets (everything beside simple names) no longer cause any runtime effects with from __future__ import annotations.

bpo-43914 [https://bugs.python.org/issue?@action=redirect&bpo=43914]: SyntaxError exceptions raised by the interpreter will highlight the full error range of the expression that consistutes the syntax error itself, instead of just where the problem is detected. Patch by Pablo Galindo.

bpo-38605 [https://bugs.python.org/issue?@action=redirect&bpo=38605]: Revert making 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: https://mail.python.org/archives/list/python-dev@python.org/thread/CLVXXPQ2T2LQ5MP2Y53VVQFCXYWQJHKZ/. Patch by Pablo Galindo.

bpo-43475 [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.

bpo-43859 [https://bugs.python.org/issue?@action=redirect&bpo=43859]: Improve the error message for IndentationError exceptions. Patch by Pablo Galindo

bpo-41323 [https://bugs.python.org/issue?@action=redirect&bpo=41323]: Constant tuple folding in bytecode optimizer now reuses tuple in constant table.

bpo-43846 [https://bugs.python.org/issue?@action=redirect&bpo=43846]: Data stack usage is much reduced for large literal and call expressions.

bpo-38530 [https://bugs.python.org/issue?@action=redirect&bpo=38530]: When printing NameError raised by the interpreter, PyErr_Display() will offer suggestions of similar variable names in the function that the exception was raised from. Patch by Pablo Galindo

bpo-43823 [https://bugs.python.org/issue?@action=redirect&bpo=43823]: Improve syntax errors for invalid dictionary literals. Patch by Pablo Galindo.

bpo-43822 [https://bugs.python.org/issue?@action=redirect&bpo=43822]: Improve syntax errors in the parser for missing commas between expressions. Patch by Pablo Galindo.

bpo-43798 [https://bugs.python.org/issue?@action=redirect&bpo=43798]: ast.alias nodes now include source location metadata attributes e.g. lineno, col_offset.

bpo-43797 [https://bugs.python.org/issue?@action=redirect&bpo=43797]: Improve SyntaxError error messages for invalid comparisons. Patch by Pablo Galindo.

bpo-43760 [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.

bpo-43682 [https://bugs.python.org/issue?@action=redirect&bpo=43682]: Static methods (@staticmethod) and class methods (@classmethod) now inherit the method attributes (__module__, __name__, __qualname__, __doc__, __annotations__) and have a new __wrapped__ attribute. Patch by Victor Stinner.

bpo-43751 [https://bugs.python.org/issue?@action=redirect&bpo=43751]: Fixed a bug where anext(ait, default) would erroneously return None.

bpo-42128 [https://bugs.python.org/issue?@action=redirect&bpo=42128]: __match_args__ is no longer allowed to be a list.

bpo-43683 [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.

bpo-43105 [https://bugs.python.org/issue?@action=redirect&bpo=43105]: Importlib now resolves relative paths when creating module spec objects from file locations.

bpo-43682 [https://bugs.python.org/issue?@action=redirect&bpo=43682]: Static methods (@staticmethod) are now callable as regular functions. Patch by Victor Stinner.

bpo-42609 [https://bugs.python.org/issue?@action=redirect&bpo=42609]: Prevented crashes in the AST validator and optimizer when compiling some absurdly long expressions like "+0"*1000000. RecursionError is now raised instead.

bpo-38530 [https://bugs.python.org/issue?@action=redirect&bpo=38530]: When printing AttributeError, PyErr_Display() will offer suggestions of similar attribute names in the object that the exception was raised from. Patch by Pablo Galindo

Library

bpo-44015 [https://bugs.python.org/issue?@action=redirect&bpo=44015]: In @dataclass(), raise a TypeError if KW_ONLY is specified more than once.

bpo-25478 [https://bugs.python.org/issue?@action=redirect&bpo=25478]: Added a total() method to collections.Counter() to compute the sum of the counts.

bpo-43733 [https://bugs.python.org/issue?@action=redirect&bpo=43733]: Change netrc.netrc to use UTF-8 encoding before using locale encoding.

bpo-43979 [https://bugs.python.org/issue?@action=redirect&bpo=43979]: Removed an unnecessary list comprehension before looping from urllib.parse.parse_qsl(). Patch by Christoph Zwerschke and Donghee Na.

bpo-43993 [https://bugs.python.org/issue?@action=redirect&bpo=43993]: Update bundled pip to 21.1.1.

bpo-43957 [https://bugs.python.org/issue?@action=redirect&bpo=43957]: [Enum] Deprecate TypeError when non-member is used in a containment check; In 3.12 True or False will be returned instead, and containment will return True if the value is either a member of that enum or one of its members' value.

bpo-42904 [https://bugs.python.org/issue?@action=redirect&bpo=42904]: For backwards compatibility with previous minor versions of Python, if typing.get_type_hints() receives no namespace dictionary arguments, typing.get_type_hints() will search through the global then local namespaces during evaluation of stringized type annotations (string forward references) inside a class.

bpo-43945 [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.

bpo-41139 [https://bugs.python.org/issue?@action=redirect&bpo=41139]: Deprecate undocumented cgi.log() API.

bpo-43937 [https://bugs.python.org/issue?@action=redirect&bpo=43937]: Fixed the turtle module working with non-default root window.

bpo-43930 [https://bugs.python.org/issue?@action=redirect&bpo=43930]: Update bundled pip to 21.1 and setuptools to 56.0.0

bpo-43907 [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.

bpo-43926 [https://bugs.python.org/issue?@action=redirect&bpo=43926]: In importlib.metadata, provide a uniform interface to Description, allow for any field to be encoded with multiline values, remove continuation lines from multiline values, and add a .json property for easy access to the PEP 566 JSON-compatible form. Sync with importlib_metadata 4.0.

bpo-43920 [https://bugs.python.org/issue?@action=redirect&bpo=43920]: OpenSSL 3.0.0: load_verify_locations() now returns a consistent error message when cadata contains no valid certificate.

bpo-43607 [https://bugs.python.org/issue?@action=redirect&bpo=43607]: urllib can now convert Windows paths with \\?\ prefixes into URL paths.

bpo-43817 [https://bugs.python.org/issue?@action=redirect&bpo=43817]: Add 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. inspect.get_annotations() can also correctly un-stringize stringized annotations.

inspect.signature(), inspect.from_callable(), and inspect.from_function() now call inspect.get_annotations() to retrieve annotations. This means inspect.signature() and inspect.from_callable() can now un-stringize stringized annotations, too.

bpo-43284 [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.

bpo-42854 [https://bugs.python.org/issue?@action=redirect&bpo=42854]: The ssl module now uses SSL_read_ex and 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.

bpo-42333 [https://bugs.python.org/issue?@action=redirect&bpo=42333]: Port _ssl extension module to multiphase initialization.

bpo-43880 [https://bugs.python.org/issue?@action=redirect&bpo=43880]: 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.

bpo-41559 [https://bugs.python.org/issue?@action=redirect&bpo=41559]: PEP 612 [https://peps.python.org/pep-0612/] is now implemented purely in Python; builtin types.GenericAlias objects no longer include typing.ParamSpec in __parameters__ (with the exception of collections.abc.Callable's GenericAlias). This means previously invalid uses of ParamSpec (such as list[P]) which worked in earlier versions of Python 3.10 alpha, will now raise TypeError during substitution.

bpo-43867 [https://bugs.python.org/issue?@action=redirect&bpo=43867]: The multiprocessing Server class now explicitly catches SystemExit and closes the client connection in this case. It happens when the Server.serve_client() method reaches the end of file (EOF).

bpo-40443 [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.

bpo-43820 [https://bugs.python.org/issue?@action=redirect&bpo=43820]: Remove an unneeded copy of the namespace passed to dataclasses.make_dataclass().

bpo-43787 [https://bugs.python.org/issue?@action=redirect&bpo=43787]: Add __iter__() method to bz2.BZ2File, gzip.GzipFile, and lzma.LZMAFile. It makes iterating them about 2x faster. Patch by Inada Naoki.

bpo-43680 [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().

bpo-43680 [https://bugs.python.org/issue?@action=redirect&bpo=43680]: The Python _pyio.open() function becomes a static method to behave as 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, _pyio.OpenWrapper() becomes a simple alias to _pyio.open(). Patch by Victor Stinner.

bpo-41515 [https://bugs.python.org/issue?@action=redirect&bpo=41515]: Fix KeyError raised in typing.get_type_hints() due to synthetic modules that don't appear in sys.modules.

bpo-43776 [https://bugs.python.org/issue?@action=redirect&bpo=43776]: When subprocess.Popen args are provided as a string or as pathlib.Path, the Popen instance repr now shows the right thing.

bpo-42248 [https://bugs.python.org/issue?@action=redirect&bpo=42248]: [Enum] ensure exceptions raised in _missing__ are released

bpo-43744 [https://bugs.python.org/issue?@action=redirect&bpo=43744]: fix issue with enum member name matching the start of a private variable name

bpo-43772 [https://bugs.python.org/issue?@action=redirect&bpo=43772]: Fixed the return value of TypeVar.__ror__. Patch by Jelle Zijlstra.

bpo-43764 [https://bugs.python.org/issue?@action=redirect&bpo=43764]: Add match_args parameter to @dataclass decorator to allow suppression of __match_args__ generation.

bpo-43799 [https://bugs.python.org/issue?@action=redirect&bpo=43799]: OpenSSL 3.0.0: define OPENSSL_API_COMPAT 1.1.1 to suppress deprecation warnings. Python requires OpenSSL 1.1.1 APIs.

bpo-43478 [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 autospec=True or be the subject of a create_autospec(...) call. 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.

bpo-43794 [https://bugs.python.org/issue?@action=redirect&bpo=43794]: Add ssl.OP_IGNORE_UNEXPECTED_EOF constants (OpenSSL 3.0.0)

bpo-43785 [https://bugs.python.org/issue?@action=redirect&bpo=43785]: Improve 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 gzip and lzma have always been. Patch by Inada Naoki.

bpo-43789 [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.

bpo-43788 [https://bugs.python.org/issue?@action=redirect&bpo=43788]: The header files for ssl error codes are now OpenSSL version-specific. Exceptions will now show correct reason and library codes. The make_ssl_data.py script has been rewritten to use OpenSSL's text file with error codes.

bpo-43766 [https://bugs.python.org/issue?@action=redirect&bpo=43766]: Implement PEP 647 [https://peps.python.org/pep-0647/] in the typing module by adding TypeGuard.

bpo-25264 [https://bugs.python.org/issue?@action=redirect&bpo=25264]: os.path.realpath() now accepts a strict keyword-only argument. When set to True, OSError is raised if a path doesn't exist or a symlink loop is encountered.

bpo-43780 [https://bugs.python.org/issue?@action=redirect&bpo=43780]: In importlib.metadata, incorporate changes from importlib_metadata 3.10: Add mtime-based caching during distribution discovery. Flagged use of dict result from entry_points() as deprecated.

The P.args and P.kwargs attributes of typing.ParamSpec are now instances of the new classes typing.ParamSpecArgs and typing.ParamSpecKwargs, which enables a more useful repr(). Patch by Jelle Zijlstra.

bpo-43731 [https://bugs.python.org/issue?@action=redirect&bpo=43731]: Add an encoding parameter logging.fileConfig().

bpo-43712 [https://bugs.python.org/issue?@action=redirect&bpo=43712]: Add encoding and errors parameters to fileinput.input() and fileinput.FileInput.

bpo-38659 [https://bugs.python.org/issue?@action=redirect&bpo=38659]: A simple_enum decorator is added to the enum module to convert a normal class into an Enum. test_simple_enum added to test simple enums against a corresponding normal Enum. Standard library modules updated to use simple_enum.

bpo-43764 [https://bugs.python.org/issue?@action=redirect&bpo=43764]: Fix an issue where __match_args__ generation could fail for some dataclasses.

bpo-43752 [https://bugs.python.org/issue?@action=redirect&bpo=43752]: Fix sqlite3 regression for zero-sized blobs with converters, where b"" was returned instead of None. The regression was introduced by PR 24723. Patch by Erlend E. Aasland.

bpo-43655 [https://bugs.python.org/issue?@action=redirect&bpo=43655]: tkinter dialog windows are now recognized as dialogs by window managers on macOS and X Window.

bpo-43723 [https://bugs.python.org/issue?@action=redirect&bpo=43723]: The following threading methods are now deprecated and should be replaced:

currentThread => threading.current_thread()

activeCount => threading.active_count()

Condition.notifyAll => threading.Condition.notify_all()

Event.isSet => threading.Event.is_set()

Thread.setName => threading.Thread.name

thread.getName => threading.Thread.name

Thread.isDaemon => threading.Thread.daemon

Thread.setDaemon => threading.Thread.daemon

Patch by Jelle Zijlstra.

bpo-2135 [https://bugs.python.org/issue?@action=redirect&bpo=2135]: Deprecate find_module() and find_loader() implementations in importlib and zipimport.

bpo-43534 [https://bugs.python.org/issue?@action=redirect&bpo=43534]: turtle.textinput() and turtle.numinput() create now a transient window working on behalf of the canvas window.

bpo-43532 [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__.

bpo-43522 [https://bugs.python.org/issue?@action=redirect&bpo=43522]: Fix problem with hostname_checks_common_name. OpenSSL does not copy hostflags from struct SSL_CTX to struct SSL.

bpo-8978 [https://bugs.python.org/issue?@action=redirect&bpo=8978]: Improve error message for tarfile.open() when lzma / bz2 are unavailable. Patch by Anthony Sottile.

bpo-42967 [https://bugs.python.org/issue?@action=redirect&bpo=42967]: Allow bytes separator argument in urllib.parse.parse_qs and urllib.parse.parse_qsl when parsing str query strings. Previously, this raised a TypeError.

bpo-43296 [https://bugs.python.org/issue?@action=redirect&bpo=43296]: Improve sqlite3 error handling: sqlite3_value_blob() errors that set SQLITE_NOMEM now raise MemoryError. Patch by Erlend E. Aasland.

bpo-43312 [https://bugs.python.org/issue?@action=redirect&bpo=43312]: New functions sysconfig.get_preferred_scheme() and sysconfig.get_default_scheme() are added to query a platform for its preferred "user", "home", and "prefix" (default) scheme names.

bpo-43265 [https://bugs.python.org/issue?@action=redirect&bpo=43265]: Improve sqlite3.Connection.backup() error handling. The error message for non-existent target database names is now unknown database <database name> instead of SQL logic error. Patch by Erlend E. Aasland.

bpo-41282 [https://bugs.python.org/issue?@action=redirect&bpo=41282]: Install schemes in distutils.command.install are now loaded from sysconfig.

bpo-41282 [https://bugs.python.org/issue?@action=redirect&bpo=41282]: distutils.sysconfig has been merged to sysconfig.

bpo-43176 [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.

bpo-43080 [https://bugs.python.org/issue?@action=redirect&bpo=43080]: pprint now has support for dataclasses.dataclass. Patch by Lewis Gaul.

bpo-39950 [https://bugs.python.org/issue?@action=redirect&bpo=39950]: Add pathlib.Path.hardlink_to() method that supersedes link_to(). The new method has the same argument order as symlink_to().

bpo-42904 [https://bugs.python.org/issue?@action=redirect&bpo=42904]: typing.get_type_hints() now checks the local namespace of a class when evaluating PEP 563 [https://peps.python.org/pep-0563/] annotations inside said class.

bpo-42269 [https://bugs.python.org/issue?@action=redirect&bpo=42269]: Add slots parameter to dataclasses.dataclass decorator to automatically generate __slots__ for class. Patch provided by Yurii Karabas.

bpo-39529 [https://bugs.python.org/issue?@action=redirect&bpo=39529]: Deprecated use of asyncio.get_event_loop() without running event loop. Emit deprecation warning for asyncio functions which implicitly create a Future or Task objects if there is no running event loop and no explicit loop argument is passed: ensure_future(), wrap_future(), gather(), shield(), as_completed() and constructors of Future, Task, StreamReader, StreamReaderProtocol.

bpo-18369 [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.

bpo-41486 [https://bugs.python.org/issue?@action=redirect&bpo=41486]: Use a new output buffer management code for bz2 / lzma / zlib modules, and add .readall() function to _compression.DecompressReader class. These bring some performance improvements. Patch by Ma Lin.

bpo-31870 [https://bugs.python.org/issue?@action=redirect&bpo=31870]: The ssl.get_server_certificate() function now has a timeout parameter.

bpo-41735 [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.

bpo-36470 [https://bugs.python.org/issue?@action=redirect&bpo=36470]: Fix dataclasses with InitVars and replace(). Patch by Claudiu Popa.

bpo-40849 [https://bugs.python.org/issue?@action=redirect&bpo=40849]: Expose X509_V_FLAG_PARTIAL_CHAIN ssl flag

bpo-35114 [https://bugs.python.org/issue?@action=redirect&bpo=35114]: ssl.RAND_status() now returns a boolean value (as documented) instead of 1 or 0.

bpo-39906 [https://bugs.python.org/issue?@action=redirect&bpo=39906]: pathlib.Path.stat() and chmod() now accept a follow_symlinks keyword-only argument for consistency with corresponding functions in the os module.

bpo-39899 [https://bugs.python.org/issue?@action=redirect&bpo=39899]: os.path.expanduser() now refuses to guess Windows home directories if the basename of current user's home directory does not match their username.

pathlib.Path.expanduser() and home() now consistently raise RuntimeError exception when a home directory cannot be resolved. Previously a KeyError exception could be raised on Windows when the "USERNAME" environment variable was unset.

bpo-36076 [https://bugs.python.org/issue?@action=redirect&bpo=36076]: Added SNI support to ssl.get_server_certificate().

bpo-38490 [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.

bpo-33731 [https://bugs.python.org/issue?@action=redirect&bpo=33731]: Provide a locale.localize() function, which converts a normalized number string into a locale format.

bpo-32745 [https://bugs.python.org/issue?@action=redirect&bpo=32745]: Fix a regression in the handling of ctypes' ctypes.c_wchar_p type: embedded null characters would cause a ValueError to be raised. Patch by Zackery Spytz.

Documentation

bpo-43987 [https://bugs.python.org/issue?@action=redirect&bpo=43987]: Add "Annotations Best Practices" document as a new HOWTO.

bpo-43977 [https://bugs.python.org/issue?@action=redirect&bpo=43977]: Document the new Py_TPFLAGS_MAPPING and Py_TPFLAGS_SEQUENCE type flags.

bpo-43959 [https://bugs.python.org/issue?@action=redirect&bpo=43959]: The documentation on the PyContextVar C-API was clarified.

bpo-43938 [https://bugs.python.org/issue?@action=redirect&bpo=43938]: Update dataclasses documentation to express that FrozenInstanceError is derived from AttributeError.

bpo-43778 [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.

bpo-43755 [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 if clause in comprehensions and generator expressions since Python 3.9.

bpo-43739 [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.

Tests

bpo-43961 [https://bugs.python.org/issue?@action=redirect&bpo=43961]: Fix test_logging.test_namer_rotator_inheritance() on Windows: use os.replace() rather than os.rename(). Patch by Victor Stinner.

bpo-43842 [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.

bpo-43843 [https://bugs.python.org/issue?@action=redirect&bpo=43843]: 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 threading.excepthook(). Use --fail-env-changed option to mark the test as failed. Patch by Victor Stinner.

bpo-43811 [https://bugs.python.org/issue?@action=redirect&bpo=43811]: Tests multiple OpenSSL versions on GitHub Actions. Use ccache to speed up testing.

bpo-43791 [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.

Build

bpo-43567 [https://bugs.python.org/issue?@action=redirect&bpo=43567]: Improved generated code refresh (AST/tokens/opcodes/keywords) on Windows.

bpo-43669 [https://bugs.python.org/issue?@action=redirect&bpo=43669]: Implement PEP 644 [https://peps.python.org/pep-0644/]. Python now requires OpenSSL 1.1.1 or newer.

Windows

bpo-35306 [https://bugs.python.org/issue?@action=redirect&bpo=35306]: Adds additional arguments to os.startfile() function.

bpo-43538 [https://bugs.python.org/issue?@action=redirect&bpo=43538]: Avoid raising errors from pathlib.Path.exists() when passed an invalid filename.

bpo-38822 [https://bugs.python.org/issue?@action=redirect&bpo=38822]: Fixed os.stat() failing on inaccessible directories with a trailing slash, rather than falling back to the parent directory's metadata. This implicitly affected os.path.exists() and os.path.isdir().

bpo-26227 [https://bugs.python.org/issue?@action=redirect&bpo=26227]: Fixed decoding of host names in socket.gethostbyaddr() and socket.gethostbyname_ex().

bpo-40432 [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.

bpo-43745 [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.

bpo-43652 [https://bugs.python.org/issue?@action=redirect&bpo=43652]: Update Tcl and Tk to 8.6.11 in Windows installer.

bpo-43492 [https://bugs.python.org/issue?@action=redirect&bpo=43492]: Upgrade Windows installer to use SQLite 3.35.5.

bpo-30555 [https://bugs.python.org/issue?@action=redirect&bpo=30555]: Fix WindowsConsoleIO errors in the presence of fd redirection. Patch by Segev Finer.

macOS

bpo-42119 [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 /System/Library, /System/IOSSupport, and /usr other than /usr/local. Previously, anything under /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 /System. Paths in /Library were also incorrectly treated as SDK locations.

bpo-43568 [https://bugs.python.org/issue?@action=redirect&bpo=43568]: Drop support for MACOSX_DEPLOYMENT_TARGET < 10.3

bpo-44009 [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.

bpo-43851 [https://bugs.python.org/issue?@action=redirect&bpo=43851]: Build SQLite with SQLITE_OMIT_AUTOINIT on macOS. Patch by Erlend E. Aasland.

bpo-43492 [https://bugs.python.org/issue?@action=redirect&bpo=43492]: Update macOS installer to use SQLite 3.35.4.

bpo-42235 [https://bugs.python.org/issue?@action=redirect&bpo=42235]: Mac/BuildScript/build-installer.py will now use "--enable-optimizations" and --with-lto when building on macOS 10.15 or later.

IDLE

bpo-37903 [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.

bpo-43981 [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

bpo-37892 [https://bugs.python.org/issue?@action=redirect&bpo=37892]: Indent IDLE Shell input with spaces instead of tabs

bpo-43655 [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.

bpo-37903 [https://bugs.python.org/issue?@action=redirect&bpo=37903]: IDLE's shell now shows prompts in a separate side-bar.

C API

bpo-43916 [https://bugs.python.org/issue?@action=redirect&bpo=43916]: Add a new Py_TPFLAGS_DISALLOW_INSTANTIATION type flag to disallow creating type instances. Patch by Victor Stinner.

bpo-43774 [https://bugs.python.org/issue?@action=redirect&bpo=43774]: Remove the now unused PYMALLOC_DEBUG macro. Debug hooks on memory allocators are now installed by default if Python is built in debug mode (if Py_DEBUG macro is defined). Moreover, they can now be used on Python build in release mode (ex: using PYTHONMALLOC=debug environment variable).

bpo-43962 [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.

bpo-28254 [https://bugs.python.org/issue?@action=redirect&bpo=28254]: Add new C-API functions to control the state of the garbage collector: PyGC_Enable(), PyGC_Disable(), PyGC_IsEnabled(), corresponding to the functions in the gc module.

bpo-43908 [https://bugs.python.org/issue?@action=redirect&bpo=43908]: Introduce Py_TPFLAGS_IMMUTABLETYPE flag for immutable type objects, and modify PyType_Ready() to set it for static types. Patch by Erlend E. Aasland.

bpo-43795 [https://bugs.python.org/issue?@action=redirect&bpo=43795]: PyMem_Calloc() is now available in the limited C API (Py_LIMITED_API).

bpo-43868 [https://bugs.python.org/issue?@action=redirect&bpo=43868]: PyOS_ReadlineFunctionPointer() is no longer exported by limited C API headers and by python3.dll on Windows. Like any function that takes FILE*, it is not part of the stable ABI.

bpo-43795 [https://bugs.python.org/issue?@action=redirect&bpo=43795]: Stable ABI and limited API definitions are generated from a central manifest (PEP 652 [https://peps.python.org/pep-0652/]).

bpo-43753 [https://bugs.python.org/issue?@action=redirect&bpo=43753]: Add the Py_Is(x, y) function to test if the x object is the y object, the same as x is y in Python. Add also the Py_IsNone(), Py_IsTrue(), Py_IsFalse() functions to test if an object is, respectively, the None singleton, the True singleton or the False singleton. Patch by Victor Stinner.

Python 3.10.0 alpha 7

Release date: 2021-04-05

Security

bpo-42988 [https://bugs.python.org/issue?@action=redirect&bpo=42988]: CVE-2021-3426 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-3426]: Remove the getfile feature of the 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.

bpo-43285 [https://bugs.python.org/issue?@action=redirect&bpo=43285]: 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 trust_server_pasv_ipv4_address attribute on their ftplib.FTP instances to True to re-enable it.

bpo-43439 [https://bugs.python.org/issue?@action=redirect&bpo=43439]: Add audit hooks for gc.get_objects(), gc.get_referrers() and gc.get_referents(). Patch by Pablo Galindo.

Core and Builtins

bpo-27129 [https://bugs.python.org/issue?@action=redirect&bpo=27129]: Update CPython bytecode magic number.

bpo-43672 [https://bugs.python.org/issue?@action=redirect&bpo=43672]: Raise ImportWarning when calling find_loader().

bpo-43660 [https://bugs.python.org/issue?@action=redirect&bpo=43660]: Fix crash that happens when replacing sys.stderr with a callable that can remove the object while an exception is being printed. Patch by Pablo Galindo.

bpo-27129 [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.

bpo-40645 [https://bugs.python.org/issue?@action=redirect&bpo=40645]: Fix reference leak in the _hashopenssl extension. Patch by Pablo Galindo.

bpo-42134 [https://bugs.python.org/issue?@action=redirect&bpo=42134]: Calls to find_module() by the import system now raise ImportWarning.

bpo-41064 [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.

bpo-43575 [https://bugs.python.org/issue?@action=redirect&bpo=43575]: Speed up calls to map() by using the PEP 590 [https://peps.python.org/pep-0590/] vectorcall calling convention. Patch by Donghee Na.

bpo-42137 [https://bugs.python.org/issue?@action=redirect&bpo=42137]: The import system now prefers using __spec__ for ModuleType.__repr__ over module_repr().

bpo-43452 [https://bugs.python.org/issue?@action=redirect&bpo=43452]: Added micro-optimizations to _PyType_Lookup() to improve cache lookup performance in the common case of cache hits.

bpo-43555 [https://bugs.python.org/issue?@action=redirect&bpo=43555]: Report the column offset for SyntaxError for invalid line continuation characters. Patch by Pablo Galindo.

bpo-43517 [https://bugs.python.org/issue?@action=redirect&bpo=43517]: Fix misdetection of circular imports when using from pkg.mod import attr, which caused false positives in non-trivial multi-threaded code.

bpo-43497 [https://bugs.python.org/issue?@action=redirect&bpo=43497]: Emit SyntaxWarnings for assertions with tuple constants, this is a regression introduced in python3.7

bpo-39316 [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.

bpo-35883 [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 Py_DecodeLocale() function now escapes byte sequences which would be decoded as Unicode characters outside the [U+0000; U+10ffff] range.

bpo-43410 [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

bpo-43406 [https://bugs.python.org/issue?@action=redirect&bpo=43406]: Fix a possible race condition where PyErr_CheckSignals tries to execute a non-Python signal handler.

bpo-42128 [https://bugs.python.org/issue?@action=redirect&bpo=42128]: Add __match_args__ to struct sequence objects. Patch by Pablo Galindo.

bpo-43390 [https://bugs.python.org/issue?@action=redirect&bpo=43390]: CPython now sets the SA_ONSTACK flag in 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 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.

bpo-43287 [https://bugs.python.org/issue?@action=redirect&bpo=43287]: Speed up calls to filter() by using the PEP 590 [https://peps.python.org/pep-0590/] vectorcall calling convention. Patch by Donghee Na.

bpo-37448 [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: -DWITH_PYMALLOC_RADIX_TREE=0.

Co-authored-by: Tim Peters <tim.peters@gmail.com>

bpo-29988 [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 __exit__() is always called in with statements, even for interrupts.

Library

bpo-43720 [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.

bpo-43433 [https://bugs.python.org/issue?@action=redirect&bpo=43433]: xmlrpc.client.ServerProxy no longer ignores query and fragment in the URL of the server.

bpo-31956 [https://bugs.python.org/issue?@action=redirect&bpo=31956]: The index() method of array.array now has optional start and stop parameters.

bpo-40066 [https://bugs.python.org/issue?@action=redirect&bpo=40066]: Enum: adjust repr() to show only enum and member name (not value, nor angle brackets) and str() to show only member name. Update and improve documentation to match.

bpo-42136 [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.

bpo-35930 [https://bugs.python.org/issue?@action=redirect&bpo=35930]: Raising an exception raised in a "future" instance will create reference cycles.

bpo-41369 [https://bugs.python.org/issue?@action=redirect&bpo=41369]: Finish updating the vendored libmpdec to version 2.5.1. Patch by Stefan Krah.

bpo-43422 [https://bugs.python.org/issue?@action=redirect&bpo=43422]: Revert the _decimal C API which was added in bpo-41324 [https://bugs.python.org/issue?@action=redirect&bpo=41324].

bpo-43577 [https://bugs.python.org/issue?@action=redirect&bpo=43577]: Fix deadlock when using ssl.SSLContext debug callback with ssl.SSLContext.sni_callback().

bpo-43571 [https://bugs.python.org/issue?@action=redirect&bpo=43571]: It's now possible to create MPTCP sockets with IPPROTO_MPTCP

bpo-43542 [https://bugs.python.org/issue?@action=redirect&bpo=43542]: image/heic and image/heif were added to mimetypes.

bpo-40645 [https://bugs.python.org/issue?@action=redirect&bpo=40645]: The hmac module now uses OpenSSL's HMAC implementation when digestmod argument is a hash name or builtin hash function.

bpo-43510 [https://bugs.python.org/issue?@action=redirect&bpo=43510]: Implement PEP 597 [https://peps.python.org/pep-0597/]: Add EncodingWarning warning, -X warn_default_encoding option, PYTHONWARNDEFAULTENCODING environment variable and encoding="locale" argument value.

bpo-43521 [https://bugs.python.org/issue?@action=redirect&bpo=43521]: ast.unparse can now render NaNs and empty sets.

bpo-42914 [https://bugs.python.org/issue?@action=redirect&bpo=42914]: pprint.pprint() gains a new boolean underscore_numbers optional argument to emit integers with thousands separated by an underscore character for improved readability (for example 1_000_000 instead of 1000000).

bpo-41361 [https://bugs.python.org/issue?@action=redirect&bpo=41361]: rotate() calls are now slightly faster due to faster argument parsing.

bpo-43423 [https://bugs.python.org/issue?@action=redirect&bpo=43423]: subprocess.communicate() no longer raises an IndexError when there is an empty stdout or stderr IO buffer during a timeout on Windows.

bpo-27820 [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.

bpo-43445 [https://bugs.python.org/issue?@action=redirect&bpo=43445]: Add frozen modules to sys.stdlib_module_names. For example, add "_frozen_importlib" and "_frozen_importlib_external" names.

bpo-43245 [https://bugs.python.org/issue?@action=redirect&bpo=43245]: Add keyword arguments support to ChainMap.new_child().

bpo-29982 [https://bugs.python.org/issue?@action=redirect&bpo=29982]: Add optional parameter ignore_cleanup_errors to tempfile.TemporaryDirectory() and allow multiple cleanup() attempts. Contributed by C.A.M. Gerlach.

bpo-43428 [https://bugs.python.org/issue?@action=redirect&bpo=43428]: Include changes from importlib_metadata 3.7 [https://importlib-metadata.readthedocs.io/en/latest/history.html#v3-7-0]:

Performance enhancements to distribution discovery.

entry_points only returns unique distributions.

Introduces new EntryPoints object for containing a set of entry points with convenience methods for selecting entry points by group or name. 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.

bpo-43332 [https://bugs.python.org/issue?@action=redirect&bpo=43332]: Improves the networking efficiency of http.client when using a proxy via set_tunnel(). Fewer small send calls are made during connection setup.

bpo-43420 [https://bugs.python.org/issue?@action=redirect&bpo=43420]: Improve performance of fractions.Fraction arithmetics for large components. Contributed by Sergey B. Kirpichev.

bpo-43356 [https://bugs.python.org/issue?@action=redirect&bpo=43356]: Allow passing a signal number to _thread.interrupt_main().

bpo-43399 [https://bugs.python.org/issue?@action=redirect&bpo=43399]: Fix ElementTree.extend not working on iterators when using the Python implementation

bpo-43369 [https://bugs.python.org/issue?@action=redirect&bpo=43369]: Improve sqlite3 error handling: If sqlite3_column_text() and sqlite3_column_blob() set SQLITE_NOMEM, MemoryError is now raised. Patch by Erlend E. Aasland.

bpo-43368 [https://bugs.python.org/issue?@action=redirect&bpo=43368]: Fix a regression introduced in PR 24562, where an empty bytestring was fetched as None instead of b'' in sqlite3. Patch by Mariusz Felisiak.

bpo-41282 [https://bugs.python.org/issue?@action=redirect&bpo=41282]: Fixed stacklevel of DeprecationWarning emitted from import distutils.

bpo-42129 [https://bugs.python.org/issue?@action=redirect&bpo=42129]: importlib.resources now honors namespace packages, merging resources from each location in the namespace as introduced in importlib_resources 3.2 and including incidental changes through 5.0.3.

bpo-43295 [https://bugs.python.org/issue?@action=redirect&bpo=43295]: datetime.datetime.strptime() now raises ValueError instead of IndexError when matching 'z' with the %z format specifier.

bpo-43125 [https://bugs.python.org/issue?@action=redirect&bpo=43125]: Return empty string if base64mime.body_encode receive empty bytes

bpo-43084 [https://bugs.python.org/issue?@action=redirect&bpo=43084]: curses.window.enclose() returns now True or False (as was documented) instead of 1 or 0.

bpo-42994 [https://bugs.python.org/issue?@action=redirect&bpo=42994]: Add MIME types for opus, AAC, 3gpp and 3gpp2

bpo-14678 [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.

bpo-42782 [https://bugs.python.org/issue?@action=redirect&bpo=42782]: Fail fast in shutil.move() to avoid creating destination directories on failure.

bpo-40066 [https://bugs.python.org/issue?@action=redirect&bpo=40066]: Enum's repr() and str() have changed: repr() is now EnumClass.MemberName and str() is MemberName. Additionally, stdlib Enum's whose contents are available as module attributes, such as RegexFlag.IGNORECASE, have their repr() as module.name, e.g. re.IGNORECASE.

bpo-26053 [https://bugs.python.org/issue?@action=redirect&bpo=26053]: Fixed bug where the pdb interactive run command echoed the args from the shell command line, even if those have been overridden at the pdb prompt.

bpo-24160 [https://bugs.python.org/issue?@action=redirect&bpo=24160]: Fixed bug where breakpoints did not persist across multiple debugger sessions in pdb's interactive mode.

bpo-40701 [https://bugs.python.org/issue?@action=redirect&bpo=40701]: When the 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 tempfile.gettempdir() and tempfile.gettempdirb() functions always return str and bytes respectively.

bpo-39342 [https://bugs.python.org/issue?@action=redirect&bpo=39342]: Expose X509_V_FLAG_ALLOW_PROXY_CERTS as VERIFY_ALLOW_PROXY_CERTS to allow proxy certificate validation as explained in https://www.openssl.org/docs/man1.1.1/man7/proxy-certificates.html.

bpo-31861 [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).

Documentation

bpo-43199 [https://bugs.python.org/issue?@action=redirect&bpo=43199]: Answer "Why is there no goto?" in the Design and History FAQ.

bpo-43407 [https://bugs.python.org/issue?@action=redirect&bpo=43407]: Clarified that a result from time.monotonic(), time.perf_counter(), time.process_time(), or time.thread_time() can be compared with the result from any following call to the same function - not just the next immediate call.

bpo-43354 [https://bugs.python.org/issue?@action=redirect&bpo=43354]: Fix type documentation for Fault.faultCode; the type has to be int instead of str.

bpo-41933 [https://bugs.python.org/issue?@action=redirect&bpo=41933]: Clarified wording of s * n in the Common Sequence Operations

Tests

bpo-37945 [https://bugs.python.org/issue?@action=redirect&bpo=37945]: Fix test_getsetlocale_issue1813() of test_locale: skip the test if setlocale() fails. Patch by Victor Stinner.

bpo-41561 [https://bugs.python.org/issue?@action=redirect&bpo=41561]: Add workaround for Ubuntu's custom OpenSSL security level policy.

Build

bpo-43179 [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.

bpo-43631 [https://bugs.python.org/issue?@action=redirect&bpo=43631]: Update macOS, Windows, and CI to OpenSSL 1.1.1k.

bpo-43617 [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.

bpo-43466 [https://bugs.python.org/issue?@action=redirect&bpo=43466]: The configure script now supports --with-openssl-rpath option.

bpo-43372 [https://bugs.python.org/issue?@action=redirect&bpo=43372]: Use _freeze_importlib to generate code for the __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 [https://bugs.python.org/issue?@action=redirect&bpo=42246], commit 877df851. Update the code and the expected code sizes in ctypes test_frozentable.

Windows

bpo-43440 [https://bugs.python.org/issue?@action=redirect&bpo=43440]: Build sqlite3 with the R*Tree module enabled. Patch by Erlend E. Aasland.

IDLE

bpo-42225 [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.

C API

bpo-43688 [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 Py_DEBUG macro is defined). In the limited C API, the Py_INCREF() and Py_DECREF() functions are now implemented as opaque function calls, rather than accessing directly the PyObject.ob_refcnt member, if Python is built in debug mode and the Py_LIMITED_API macro targets Python 3.10 or newer. It became possible to support the limited C API in debug mode because the PyObject structure is the same in release and debug mode since Python 3.8 (see bpo-36465 [https://bugs.python.org/issue?@action=redirect&bpo=36465]).

The limited C API is still not supported in the --with-trace-refs special build (Py_TRACE_REFS macro).

Patch by Victor Stinner.

bpo-43244 [https://bugs.python.org/issue?@action=redirect&bpo=43244]: Remove the pyarena.h header file with functions:

PyArena_New()

PyArena_Free()

PyArena_Malloc()

PyArena_AddPyObject()

These functions were undocumented, excluded from the limited C API, and were only used internally by the compiler. Patch by Victor Stinner.

bpo-43244 [https://bugs.python.org/issue?@action=redirect&bpo=43244]: Remove the compiler and parser functions using struct _mod type, because the public AST C API was removed:

PyAST_Compile()

PyAST_CompileEx()

PyAST_CompileObject()

PyFuture_FromAST()

PyFuture_FromASTObject()

PyParser_ASTFromFile()

PyParser_ASTFromFileObject()

PyParser_ASTFromFilename()

PyParser_ASTFromString()

PyParser_ASTFromStringObject()

These functions were undocumented and excluded from the limited C API. Patch by Victor Stinner.

bpo-43244 [https://bugs.python.org/issue?@action=redirect&bpo=43244]: Remove ast.h, asdl.h, and 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 Py and so could create names conflicts. For example, Python-ast.h defined a Yield macro which was conflict with the Yield name used by the Windows <winbase.h> header. Use the Python ast module instead. Patch by Victor Stinner.

bpo-43541 [https://bugs.python.org/issue?@action=redirect&bpo=43541]: Fix a PyEval_EvalCodeEx() regression: fix reference counting on builtins. Patch by Victor Stinner.

bpo-43244 [https://bugs.python.org/issue?@action=redirect&bpo=43244]: Remove the symtable.h header file and the undocumented functions:

PyST_GetScope()

PySymtable_Build()

PySymtable_BuildObject()

PySymtable_Free()

Py_SymtableString()

Py_SymtableStringObject()

The Py_SymtableString() function was part the stable ABI by mistake but it could not be used, because the symtable.h header file was excluded from the limited C API.

The Python symtable module remains available and is unchanged.

Patch by Victor Stinner.

bpo-43244 [https://bugs.python.org/issue?@action=redirect&bpo=43244]: Remove the PyAST_Validate() function. It is no longer possible to build a AST object (mod_ty type) with the public C API. The function was already excluded from the limited C API (PEP 384 [https://peps.python.org/pep-0384/]). Patch by Victor Stinner.

Python 3.10.0 alpha 6

Release date: 2021-03-01

Security

bpo-42967 [https://bugs.python.org/issue?@action=redirect&bpo=42967]: Fix web cache poisoning vulnerability by defaulting the query args separator to &, and allowing the user to choose a custom separator.

Core and Builtins

bpo-43321 [https://bugs.python.org/issue?@action=redirect&bpo=43321]: Fix SystemError raised when PyArg_Parse*() is used with # but without PY_SSIZE_T_CLEAN defined.

bpo-36346 [https://bugs.python.org/issue?@action=redirect&bpo=36346]: PyArg_Parse*() functions now emits DeprecationWarning when u or Z format is used. See PEP 623 [https://peps.python.org/pep-0623/] for detail.

bpo-43277 [https://bugs.python.org/issue?@action=redirect&bpo=43277]: Add a new PySet_CheckExact() function to the C-API to check if an object is an instance of set but not an instance of a subtype. Patch by Pablo Galindo.

bpo-42990 [https://bugs.python.org/issue?@action=redirect&bpo=42990]: The types.FunctionType constructor now inherits the current builtins if the globals dictionary has no "__builtins__" key, rather than using {"None": None} as builtins: same behavior as eval() and exec() functions. Defining a function with def function(...): ... in Python is not affected, globals cannot be overridden with this syntax: it also inherits the current builtins. Patch by Victor Stinner.

bpo-42990 [https://bugs.python.org/issue?@action=redirect&bpo=42990]: Functions have a new __builtins__ attribute which is used to look for builtin symbols when a function is executed, instead of looking into __globals__['__builtins__']. Patch by Mark Shannon and Victor Stinner.

bpo-43149 [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.

bpo-43121 [https://bugs.python.org/issue?@action=redirect&bpo=43121]: Fixed an incorrect SyntaxError message for missing comma in literals. Patch by Pablo Galindo.

bpo-42819 [https://bugs.python.org/issue?@action=redirect&bpo=42819]: 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 readline.read_init_file(). The Python REPL has not implemented bracketed paste support. Also, bracketed mode writes the "\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 readline.parse_and_bind("set enable-bracketed-paste on"). Patch by Dustin Rodrigues.

bpo-42808 [https://bugs.python.org/issue?@action=redirect&bpo=42808]: Simple calls to type(object) are now faster due to the vectorcall calling convention. Patch by Dennis Sweeney.

bpo-42217 [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.

bpo-41972 [https://bugs.python.org/issue?@action=redirect&bpo=41972]: Substring search functions such as str1 in str2 and str2.find(str1) now sometimes use the "Two-Way" string comparison algorithm to avoid quadratic behavior on long strings.

bpo-42128 [https://bugs.python.org/issue?@action=redirect&bpo=42128]: Implement PEP 634 [https://peps.python.org/pep-0634/] (structural pattern matching). Patch by Brandt Bucher.

bpo-40692 [https://bugs.python.org/issue?@action=redirect&bpo=40692]: In the concurrent.futures.ProcessPoolExecutor, validate that multiprocess.synchronize() is available on a given platform and rely on that check in the concurrent.futures test suite so we can run tests that are unrelated to ProcessPoolExecutor on those platforms.

bpo-38302 [https://bugs.python.org/issue?@action=redirect&bpo=38302]: If object.__ipow__() returns NotImplemented, the operator will correctly fall back to object.__pow__() and object.__rpow__() as expected.

Library

bpo-43316 [https://bugs.python.org/issue?@action=redirect&bpo=43316]: The 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.

bpo-43317 [https://bugs.python.org/issue?@action=redirect&bpo=43317]: Set the chunk size for the gzip module main function to io.DEFAULT_BUFFER_SIZE. This is slightly faster than the 1024 bytes constant that was used previously.

bpo-43146 [https://bugs.python.org/issue?@action=redirect&bpo=43146]: Handle None in single-arg versions of print_exception() and format_exception().

bpo-43260 [https://bugs.python.org/issue?@action=redirect&bpo=43260]: Fix TextIOWrapper can not flush internal buffer forever after very large text is written.

bpo-43258 [https://bugs.python.org/issue?@action=redirect&bpo=43258]: Prevent needless allocation of sqlite3 aggregate function context when no rows match an aggregate query. Patch by Erlend E. Aasland.

bpo-43251 [https://bugs.python.org/issue?@action=redirect&bpo=43251]: Improve sqlite3 error handling: sqlite3_column_name() failures now result in MemoryError. Patch by Erlend E. Aasland.

bpo-40956 [https://bugs.python.org/issue?@action=redirect&bpo=40956]: Fix segfault in sqlite3.Connection.backup() if no argument was provided. The regression was introduced by PR 23838. Patch by Erlend E. Aasland.

bpo-43172 [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 readline.get_begidx() and readline.get_endidx() behavior based on libreadline vs libedit use.

bpo-43163 [https://bugs.python.org/issue?@action=redirect&bpo=43163]: Fix a bug in codeop that was causing it to not ask for more input when multi-line snippets have unclosed parentheses. Patch by Pablo Galindo

bpo-43162 [https://bugs.python.org/issue?@action=redirect&bpo=43162]: deprecate unsupported ability to access enum members as attributes of other enum members

bpo-43146 [https://bugs.python.org/issue?@action=redirect&bpo=43146]: Fix recent regression in None argument handling in traceback module functions.

bpo-43102 [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.

bpo-43106 [https://bugs.python.org/issue?@action=redirect&bpo=43106]: Added O_EVTONLY, O_FSYNC, O_SYMLINK and O_NOFOLLOW_ANY for macOS. Patch by Donghee Na.

bpo-42960 [https://bugs.python.org/issue?@action=redirect&bpo=42960]: Adds resource.RLIMIT_KQUEUES constant from FreeBSD to the resource module.

bpo-42151 [https://bugs.python.org/issue?@action=redirect&bpo=42151]: Make the pure Python implementation of xml.etree.ElementTree behave the same as the C implementation (_elementree) regarding default attribute values (by not setting specified_attributes=1).

bpo-29753 [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.

Documentation

bpo-27646 [https://bugs.python.org/issue?@action=redirect&bpo=27646]: Clarify that 'yield from <expr>' works with any iterable, not just iterators.

bpo-36346 [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 PEP 623 [https://peps.python.org/pep-0623/] for detail.

Tests

bpo-43288 [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.

Build

bpo-43174 [https://bugs.python.org/issue?@action=redirect&bpo=43174]: Windows build now uses /utf-8 compiler option.

bpo-43103 [https://bugs.python.org/issue?@action=redirect&bpo=43103]: Add a new configure --without-static-libpython option to not build the libpythonMAJOR.MINOR.a static library and not install the python.o object file.

bpo-13501 [https://bugs.python.org/issue?@action=redirect&bpo=13501]: The configure script can now use libedit instead of readline with the command line option --with-readline=editline.

bpo-42603 [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 /{System/,}Library/Frameworks. If both exist and the latter is preferred, the appropriate --with-tcltk-* configuration options need to be explicitly set.

bpo-39448 [https://bugs.python.org/issue?@action=redirect&bpo=39448]: Add the "regen-frozen" makefile target that regenerates the code for the frozen __hello__ module.

Windows

bpo-43155 [https://bugs.python.org/issue?@action=redirect&bpo=43155]: PyCMethod_New() is now present in python3.lib.

macOS

bpo-41837 [https://bugs.python.org/issue?@action=redirect&bpo=41837]: Update macOS installer build to use OpenSSL 1.1.1j.

IDLE

bpo-43283 [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.

C API

bpo-43278 [https://bugs.python.org/issue?@action=redirect&bpo=43278]: Always put compiler and system information on the first line of the REPL welcome message.

bpo-43270 [https://bugs.python.org/issue?@action=redirect&bpo=43270]: Remove the private _PyErr_OCCURRED() macro: use the public PyErr_Occurred() function instead.

bpo-35134 [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: Include Files.

bpo-35134 [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: Include Files.

bpo-40170 [https://bugs.python.org/issue?@action=redirect&bpo=40170]: PyExceptionClass_Name() is now always declared as a function, in order to hide implementation details. The macro accessed PyTypeObject.tp_name directly. Patch by Erlend E. Aasland.

bpo-43239 [https://bugs.python.org/issue?@action=redirect&bpo=43239]: The PyCFunction_New() function is now exported in the ABI when compiled with -fvisibility=hidden.

bpo-40170 [https://bugs.python.org/issue?@action=redirect&bpo=40170]: PyIter_Check() is now always declared as a function, in order to hide implementation details. The macro accessed PyTypeObject.tp_iternext directly. Patch by Erlend E. Aasland.

bpo-40170 [https://bugs.python.org/issue?@action=redirect&bpo=40170]: Convert PyDescr_IsData() macro to a function to hide implementation details: The macro accessed PyTypeObject.tp_descr_set directly. Patch by Erlend E. Aasland.

bpo-43181 [https://bugs.python.org/issue?@action=redirect&bpo=43181]: Convert PyObject_TypeCheck() macro to a static inline function. Patch by Erlend E. Aasland.

Python 3.10.0 alpha 5

Release date: 2021-02-02

Security

bpo-42938 [https://bugs.python.org/issue?@action=redirect&bpo=42938]: Avoid static buffers when computing the repr of ctypes.c_double and ctypes.c_longdouble values.

Core and Builtins

bpo-42990 [https://bugs.python.org/issue?@action=redirect&bpo=42990]: Refactor the PyEval_ family of functions.

An new function _PyEval_Vector is added to simplify calls to Python from C.

_PyEval_EvalCodeWithName is removed

PyEval_EvalCodeEx is retained as part of the API, but is not used internally

bpo-38631 [https://bugs.python.org/issue?@action=redirect&bpo=38631]: Replace Py_FatalError() calls in the compiler with regular SystemError exceptions. Patch by Victor Stinner.

bpo-42997 [https://bugs.python.org/issue?@action=redirect&bpo=42997]: Improve error message for missing ":" before blocks. Patch by Pablo Galindo.

bpo-43017 [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.

bpo-42986 [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.

bpo-40176 [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.

bpo-42927 [https://bugs.python.org/issue?@action=redirect&bpo=42927]: The inline cache for LOAD_ATTR now also optimizes access to attributes defined by __slots__. This makes reading such attribute up to 30% faster.

bpo-42864 [https://bugs.python.org/issue?@action=redirect&bpo=42864]: Improve error messages in the parser when parentheses are not closed. Patch by Pablo Galindo.

bpo-42924 [https://bugs.python.org/issue?@action=redirect&bpo=42924]: Fix 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 bytearray to a shorter byte string).

bpo-42882 [https://bugs.python.org/issue?@action=redirect&bpo=42882]: Fix the _PyUnicode_FromId() function (_Py_IDENTIFIER(var) API) when Py_Initialize() / Py_Finalize() is called multiple times: preserve _PyRuntime.unicode_ids.next_index value.

bpo-42827 [https://bugs.python.org/issue?@action=redirect&bpo=42827]: Fix a crash when working out the error line of a SyntaxError in some multi-line expressions.

bpo-42823 [https://bugs.python.org/issue?@action=redirect&bpo=42823]: frame.f_lineno is correct even if frame.f_trace is set to True

bpo-37324 [https://bugs.python.org/issue?@action=redirect&bpo=37324]: Remove deprecated aliases to コレクション抽象基底クラス from the collections module.

bpo-41994 [https://bugs.python.org/issue?@action=redirect&bpo=41994]: Fixed possible leak in import when sys.modules is not a dict.

bpo-27772 [https://bugs.python.org/issue?@action=redirect&bpo=27772]: In string formatting, preceding the width field by '0' no longer affects the default alignment for strings.

Library

bpo-43108 [https://bugs.python.org/issue?@action=redirect&bpo=43108]: Fixed a reference leak in the curses module. Patch by Pablo Galindo

bpo-43077 [https://bugs.python.org/issue?@action=redirect&bpo=43077]: Update the bundled pip to 21.0.1 and setuptools to 52.0.0.

bpo-41282 [https://bugs.python.org/issue?@action=redirect&bpo=41282]: Deprecate distutils in documentation and add warning on import.

bpo-43014 [https://bugs.python.org/issue?@action=redirect&bpo=43014]: Improve performance of tokenize by 20-30%. Patch by Anthony Sottile.

bpo-42323 [https://bugs.python.org/issue?@action=redirect&bpo=42323]: Fix math.nextafter() for NaN on AIX.

bpo-42955 [https://bugs.python.org/issue?@action=redirect&bpo=42955]: Add sys.stdlib_module_names, containing the list of the standard library module names. Patch by Victor Stinner.

bpo-42944 [https://bugs.python.org/issue?@action=redirect&bpo=42944]: Fix random.Random.sample when counts argument is not None.

bpo-42934 [https://bugs.python.org/issue?@action=redirect&bpo=42934]: Use TracebackException's new compact param in TestResult to reduce time and memory consumed by traceback formatting.

bpo-42931 [https://bugs.python.org/issue?@action=redirect&bpo=42931]: Add randbytes() to random.__all__.

bpo-38250 [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.

bpo-42877 [https://bugs.python.org/issue?@action=redirect&bpo=42877]: Added the compact parameter to the constructor of traceback.TracebackException to reduce time and memory for use cases that only need to call TracebackException.format() and TracebackException.format_exception_only().

bpo-42923 [https://bugs.python.org/issue?@action=redirect&bpo=42923]: The Py_FatalError() function and the faulthandler module now dump the list of extension modules on a fatal error.

bpo-42848 [https://bugs.python.org/issue?@action=redirect&bpo=42848]: Removed recursion from TracebackException to allow it to handle long exception chains.

bpo-42901 [https://bugs.python.org/issue?@action=redirect&bpo=42901]: [Enum] move member creation from EnumMeta.__new__ to _proto_member.__set_name__, allowing members to be created and visible in __init_subclass__.

bpo-42780 [https://bugs.python.org/issue?@action=redirect&bpo=42780]: Fix os.set_inheritable() for O_PATH file descriptors on Linux.

bpo-42866 [https://bugs.python.org/issue?@action=redirect&bpo=42866]: Fix a reference leak in the getcodec() function of CJK codecs. Patch by Victor Stinner.

bpo-42846 [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 (PEP 489 [https://peps.python.org/pep-0489/]). Patch by Victor Stinner.

bpo-42851 [https://bugs.python.org/issue?@action=redirect&bpo=42851]: remove __init_subclass__ support for Enum members

bpo-42834 [https://bugs.python.org/issue?@action=redirect&bpo=42834]: Make internal caches of the _json module compatible with subinterpreters.

bpo-41748 [https://bugs.python.org/issue?@action=redirect&bpo=41748]: Fix HTMLParser parsing rules for element attributes containing commas with spaces. Patch by Karl Dubost.

bpo-40810 [https://bugs.python.org/issue?@action=redirect&bpo=40810]: Require SQLite 3.7.15 or newer. Patch by Erlend E. Aasland.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Convert the _multibytecodec extension module (CJK codecs) to multi-phase initialization (PEP 489 [https://peps.python.org/pep-0489/]). Patch by Erlend E. Aasland.

bpo-42802 [https://bugs.python.org/issue?@action=redirect&bpo=42802]: The distutils bdist_wininst command deprecated in Python 3.8 has been removed. The distutils bdist_wheel command is now recommended to distribute binary packages on Windows.

bpo-24464 [https://bugs.python.org/issue?@action=redirect&bpo=24464]: The undocumented built-in function 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.

bpo-42384 [https://bugs.python.org/issue?@action=redirect&bpo=42384]: Make pdb populate sys.path[0] exactly the same as regular python execution.

bpo-42383 [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.

bpo-42005 [https://bugs.python.org/issue?@action=redirect&bpo=42005]: Fix CLI of cProfile and profile to catch BrokenPipeError.

bpo-41604 [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.

bpo-41149 [https://bugs.python.org/issue?@action=redirect&bpo=41149]: Allow executing callables that have a boolean value of False when passed to Threading.thread as the target. Patch contributed by Barney Stratford.

bpo-38307 [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.

bpo-39273 [https://bugs.python.org/issue?@action=redirect&bpo=39273]: The BUTTON5_* constants are now exposed in the curses module if available.

bpo-33289 [https://bugs.python.org/issue?@action=redirect&bpo=33289]: Correct call to tkinter.colorchooser to return RGB triplet of ints instead of floats. Patch by Cheryl Sabella.

Documentation

bpo-40304 [https://bugs.python.org/issue?@action=redirect&bpo=40304]: Fix doc for type(name, bases, dict). Patch by Boris Verkhovskiy and Éric Araujo.

bpo-42811 [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.)

Tests

bpo-40823 [https://bugs.python.org/issue?@action=redirect&bpo=40823]: Use unittest.TestLoader().loadTestsFromTestCase() instead of unittest.makeSuite() in sqlite3 tests. Patch by Erlend E. Aasland.

bpo-40810 [https://bugs.python.org/issue?@action=redirect&bpo=40810]: In sqlite3, fix CheckTraceCallbackContent for SQLite pre 3.7.15.

Build

bpo-43031 [https://bugs.python.org/issue?@action=redirect&bpo=43031]: Pass --timeout=$(TESTTIMEOUT) option to the default profile task ./python -m test --pgo command.

bpo-36143 [https://bugs.python.org/issue?@action=redirect&bpo=36143]: make regen-all now also runs regen-keyword. Patch by Victor Stinner.

bpo-42874 [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).

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Add library search path by wr-cc in add_cross_compiling_paths() for VxWorks.

bpo-42856 [https://bugs.python.org/issue?@action=redirect&bpo=42856]: Add --with-wheel-pkg-dir=PATH option to the ./configure script. If specified, the ensurepip module looks for setuptools and 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 /usr/share/python-wheels/ directory and don't install the ensurepip._bundled package.

Windows

bpo-41837 [https://bugs.python.org/issue?@action=redirect&bpo=41837]: Updated Windows installer to include OpenSSL 1.1.1i

bpo-42584 [https://bugs.python.org/issue?@action=redirect&bpo=42584]: Upgrade Windows installer to use SQLite 3.34.0.

macOS

bpo-42504 [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.

IDLE

bpo-43008 [https://bugs.python.org/issue?@action=redirect&bpo=43008]: Make IDLE invoke sys.excepthook() in normal, 2-process mode. Patch by Ken Hilton.

bpo-33065 [https://bugs.python.org/issue?@action=redirect&bpo=33065]: Fix problem debugging user classes with __repr__ method.

bpo-23544 [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.

bpo-32631 [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.

C API

bpo-42979 [https://bugs.python.org/issue?@action=redirect&bpo=42979]: When Python is built in debug mode (with C assertions), calling a type slot like sq_length (__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.

bpo-43030 [https://bugs.python.org/issue?@action=redirect&bpo=43030]: Fixed a compiler warning in Py_UNICODE_ISSPACE() on platforms with signed wchar_t.

Python 3.10.0 alpha 4

Release date: 2021-01-04

Core and Builtins

bpo-42814 [https://bugs.python.org/issue?@action=redirect&bpo=42814]: Fix undefined behavior in Objects/genericaliasobject.c.

bpo-42806 [https://bugs.python.org/issue?@action=redirect&bpo=42806]: Fix the column offsets for f-strings ast nodes surrounded by parentheses and for nodes that spawn multiple lines. Patch by Pablo Galindo.

bpo-40631 [https://bugs.python.org/issue?@action=redirect&bpo=40631]: Fix regression where a single parenthesized starred expression was a valid assignment target.

bpo-27794 [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.

bpo-42745 [https://bugs.python.org/issue?@action=redirect&bpo=42745]: Make the type attribute lookup cache per-interpreter. Patch by Victor Stinner.

bpo-42246 [https://bugs.python.org/issue?@action=redirect&bpo=42246]: Jumps to jumps are not eliminated when it would break PEP 626.

bpo-42246 [https://bugs.python.org/issue?@action=redirect&bpo=42246]: Make sure that the f_lasti and f_lineno attributes of a frame are set correctly when an exception is raised or re-raised. Required for PEP 626.

bpo-32381 [https://bugs.python.org/issue?@action=redirect&bpo=32381]: The coding cookie (ex: # coding: latin1) is now ignored in the command passed to the -c command line option. Patch by Victor Stinner.

bpo-30858 [https://bugs.python.org/issue?@action=redirect&bpo=30858]: Improve error location in expressions that contain assignments. Patch by Pablo Galindo and Lysandros Nikolaou.

bpo-42615 [https://bugs.python.org/issue?@action=redirect&bpo=42615]: Remove jump commands made redundant by the deletion of unreachable bytecode blocks

bpo-42639 [https://bugs.python.org/issue?@action=redirect&bpo=42639]: Make the atexit module state per-interpreter. It is now safe have more than one atexit module instance. Patch by Donghee Na and Victor Stinner.

bpo-32381 [https://bugs.python.org/issue?@action=redirect&bpo=32381]: Fix encoding name when running a .pyc file on Windows: PyRun_SimpleFileExFlags() now uses the correct encoding to decode the filename.

bpo-42195 [https://bugs.python.org/issue?@action=redirect&bpo=42195]: The __args__ of the parameterized generics for typing.Callable and collections.abc.Callable are now consistent. The __args__ for collections.abc.Callable are now flattened while typing.Callable's have not changed. To allow this change, types.GenericAlias can now be subclassed and collections.abc.Callable's __class_getitem__ will now return a subclass of types.GenericAlias. Tests for typing were also updated to not subclass things like Callable[..., T] as that is not a valid base class. Finally, both Callables no longer validate their argtypes, in Callable[[argtypes], resulttype] to prepare for PEP 612 [https://peps.python.org/pep-0612/]. Patch by Ken Jin.

bpo-40137 [https://bugs.python.org/issue?@action=redirect&bpo=40137]: Convert functools module to use PyType_FromModuleAndSpec().

bpo-40077 [https://bugs.python.org/issue?@action=redirect&bpo=40077]: Convert array to use heap types, and establish module state for these.

bpo-42008 [https://bugs.python.org/issue?@action=redirect&bpo=42008]: Fix _random.Random() seeding.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port the pyexpat extension module to multi-phase initialization (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-40521 [https://bugs.python.org/issue?@action=redirect&bpo=40521]: Make the Unicode dictionary of interned strings compatible with subinterpreters. Patch by Victor Stinner.

bpo-39465 [https://bugs.python.org/issue?@action=redirect&bpo=39465]: Make _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.

Library

bpo-42257 [https://bugs.python.org/issue?@action=redirect&bpo=42257]: Handle empty string in variable executable in platform.libc_ver()

bpo-42772 [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.

bpo-42759 [https://bugs.python.org/issue?@action=redirect&bpo=42759]: Fixed equality comparison of tkinter.Variable and tkinter.font.Font. Objects which belong to different Tcl interpreters are now always different, even if they have the same name.

bpo-42756 [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.

bpo-23328 [https://bugs.python.org/issue?@action=redirect&bpo=23328]: Allow / character in username, password fields on _PROXY envars.

bpo-42740 [https://bugs.python.org/issue?@action=redirect&bpo=42740]: typing.get_args() and typing.get_origin() now support PEP 604 [https://peps.python.org/pep-0604/] union types and PEP 612 [https://peps.python.org/pep-0612/] additions to Callable.

bpo-42655 [https://bugs.python.org/issue?@action=redirect&bpo=42655]: subprocess extra_groups is now correctly passed into setgroups() system call.

bpo-42727 [https://bugs.python.org/issue?@action=redirect&bpo=42727]: EnumMeta.__prepare__ now accepts **kwds to properly support __init_subclass__

bpo-38308 [https://bugs.python.org/issue?@action=redirect&bpo=38308]: Add optional weights to statistics.harmonic_mean().

bpo-42721 [https://bugs.python.org/issue?@action=redirect&bpo=42721]: When simple query dialogs (tkinter.simpledialog), message boxes (tkinter.messagebox) or color choose dialog (tkinter.colorchooser) are created without arguments master and parent, and the default root window is not yet created, and 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.

bpo-25246 [https://bugs.python.org/issue?@action=redirect&bpo=25246]: Optimized collections.deque.remove().

bpo-35728 [https://bugs.python.org/issue?@action=redirect&bpo=35728]: Added a root parameter to tkinter.font.nametofont().

bpo-15303 [https://bugs.python.org/issue?@action=redirect&bpo=15303]: tkinter supports now widgets with boolean value False.

bpo-42681 [https://bugs.python.org/issue?@action=redirect&bpo=42681]: Fixed range checks for color and pair numbers in curses.

bpo-42685 [https://bugs.python.org/issue?@action=redirect&bpo=42685]: Improved placing of simple query windows in Tkinter (such as 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.

bpo-9694 [https://bugs.python.org/issue?@action=redirect&bpo=9694]: Argparse help no longer uses the confusing phrase, "optional arguments". It uses "options" instead.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port the _thread extension module to the multiphase initialization API (PEP 489 [https://peps.python.org/pep-0489/]) and convert its static types to heap types.

bpo-37961 [https://bugs.python.org/issue?@action=redirect&bpo=37961]: Fix crash in tracemalloc.Traceback.__repr__() (regressed in Python 3.9).

bpo-42630 [https://bugs.python.org/issue?@action=redirect&bpo=42630]: tkinter functions and constructors which need a default root window raise now RuntimeError with descriptive message instead of obscure AttributeError or NameError if it is not created yet or cannot be created automatically.

bpo-42639 [https://bugs.python.org/issue?@action=redirect&bpo=42639]: atexit._run_exitfuncs() now logs callback exceptions using sys.unraisablehook, rather than logging them directly into sys.stderr and raise the last exception.

bpo-42644 [https://bugs.python.org/issue?@action=redirect&bpo=42644]: logging.disable will now validate the types and value of its parameter. It also now accepts strings representing the levels (as does logging.setLevel) instead of only the numerical values.

bpo-42639 [https://bugs.python.org/issue?@action=redirect&bpo=42639]: At Python exit, if a callback registered with atexit.register() fails, its exception is now logged. Previously, only some exceptions were logged, and the last exception was always silently ignored.

bpo-36541 [https://bugs.python.org/issue?@action=redirect&bpo=36541]: Fixed lib2to3.pgen2 to be able to parse PEP-570 positional only argument syntax.

bpo-42382 [https://bugs.python.org/issue?@action=redirect&bpo=42382]: In importlib.metadata: - EntryPoint objects now expose a .dist object referencing the Distribution when constructed from a Distribution. - Add support for package discovery under package normalization rules. - The object returned by metadata() now has a formally defined protocol called PackageMetadata with declared support for the .get_all() method. - Synced with importlib_metadata 3.3.

bpo-41877 [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.

bpo-39717 [https://bugs.python.org/issue?@action=redirect&bpo=39717]: [tarfile] update nested exception raising to use from None or from e

bpo-41877 [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.

bpo-41559 [https://bugs.python.org/issue?@action=redirect&bpo=41559]: Implemented PEP 612 [https://peps.python.org/pep-0612/]: added ParamSpec and Concatenate to typing. Patch by Ken Jin.

bpo-42385 [https://bugs.python.org/issue?@action=redirect&bpo=42385]: StrEnum: fix _generate_next_value_ to return a str

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Define THREAD_STACK_SIZE for VxWorks.

bpo-34750 [https://bugs.python.org/issue?@action=redirect&bpo=34750]: [Enum] _EnumDict.update() is now supported.

bpo-42517 [https://bugs.python.org/issue?@action=redirect&bpo=42517]: Enum: private names do not become members / do not generate errors -- they remain normal attributes

bpo-42678 [https://bugs.python.org/issue?@action=redirect&bpo=42678]: Enum: call __init_subclass__ after members have been added

bpo-28964 [https://bugs.python.org/issue?@action=redirect&bpo=28964]: ast.literal_eval() adds line number information (if available) in error message for malformed nodes.

bpo-42470 [https://bugs.python.org/issue?@action=redirect&bpo=42470]: random.sample() no longer warns on a sequence which is also a set.

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: posixpath.expanduser() returns the input path unchanged if user home directory is None on VxWorks.

bpo-42388 [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.

bpo-34463 [https://bugs.python.org/issue?@action=redirect&bpo=34463]: Fixed discrepancy between traceback and the interpreter in formatting of SyntaxError with lineno not set (traceback was changed to match interpreter).

bpo-42393 [https://bugs.python.org/issue?@action=redirect&bpo=42393]: Raise OverflowError instead of silent truncation in socket.ntohs() and socket.htons(). Silent truncation was deprecated in Python 3.7. Patch by Erlend E. Aasland

bpo-42222 [https://bugs.python.org/issue?@action=redirect&bpo=42222]: Harmonized random.randrange() argument handling to match range().

The integer test and conversion in randrange() now uses operator.index().

Non-integer arguments to randrange() are deprecated.

The ValueError is deprecated in favor of a TypeError.

It now runs a little faster than before.

(Contributed by Raymond Hettinger and Serhiy Storchaka.)

bpo-42163 [https://bugs.python.org/issue?@action=redirect&bpo=42163]: Restore compatibility for uname_result around deepcopy and _replace.

bpo-42090 [https://bugs.python.org/issue?@action=redirect&bpo=42090]: zipfile.Path.joinpath now accepts arbitrary arguments, same as pathlib.Path.joinpath.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port the _csv module to the multi-phase initialization API (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-42059 [https://bugs.python.org/issue?@action=redirect&bpo=42059]: typing.TypedDict types created using the alternative call-style syntax now correctly respect the total keyword argument when setting their __required_keys__ and __optional_keys__ class attributes.

bpo-41960 [https://bugs.python.org/issue?@action=redirect&bpo=41960]: Add globalns and localns parameters to the inspect.signature() and inspect.Signature.from_callable().

bpo-41907 [https://bugs.python.org/issue?@action=redirect&bpo=41907]: fix format() behavior for IntFlag

bpo-41891 [https://bugs.python.org/issue?@action=redirect&bpo=41891]: Ensure asyncio.wait_for waits for task completion

bpo-24792 [https://bugs.python.org/issue?@action=redirect&bpo=24792]: Fixed bug where zipimporter sometimes reports an incorrect cause of import errors.

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Fix site and sysconfig modules for VxWorks RTOS which has no home directories.

bpo-41462 [https://bugs.python.org/issue?@action=redirect&bpo=41462]: Add os.set_blocking() support for VxWorks RTOS.

bpo-40219 [https://bugs.python.org/issue?@action=redirect&bpo=40219]: Lowered tkinter.ttk.LabeledScale dummy widget to prevent hiding part of the content label.

bpo-37193 [https://bugs.python.org/issue?@action=redirect&bpo=37193]: Fixed memory leak in socketserver.ThreadingMixIn introduced in Python 3.7.

bpo-39068 [https://bugs.python.org/issue?@action=redirect&bpo=39068]: Fix initialization race condition in a85encode() and b85encode() in base64. Patch by Brandon Stansbury.

Documentation

bpo-17140 [https://bugs.python.org/issue?@action=redirect&bpo=17140]: Add documentation for the multiprocessing.pool.ThreadPool class.

bpo-34398 [https://bugs.python.org/issue?@action=redirect&bpo=34398]: Prominently feature listings from the glossary in documentation search results. Patch by Ammar Askar.

Tests

bpo-42794 [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.

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Skip some asyncio tests on VxWorks.

bpo-42641 [https://bugs.python.org/issue?@action=redirect&bpo=42641]: Enhance 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.

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Skip some tests in _test_all_chown_common() on VxWorks.

bpo-42199 [https://bugs.python.org/issue?@action=redirect&bpo=42199]: Fix bytecode helper assertNotInBytecode.

bpo-41443 [https://bugs.python.org/issue?@action=redirect&bpo=41443]: Add more attribute checking in test_posix.py

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Disable os.popen and impacted tests on VxWorks

bpo-41439 [https://bugs.python.org/issue?@action=redirect&bpo=41439]: Port test_ssl and test_uuid to VxWorks RTOS.

Build

bpo-42692 [https://bugs.python.org/issue?@action=redirect&bpo=42692]: Fix __builtin_available check on older compilers. Patch by Joshua Root.

bpo-27640 [https://bugs.python.org/issue?@action=redirect&bpo=27640]: Added --disable-test-modules option to the configure script: don't build nor install test modules. Patch by Xavier de Gaye, Thomas Petazzoni and Peixing Xin.

bpo-42604 [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".

bpo-42598 [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.

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Enable libpython3.so for VxWorks.

bpo-29076 [https://bugs.python.org/issue?@action=redirect&bpo=29076]: Add fish shell support to macOS installer.

macOS

bpo-42361 [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).

bpo-41837 [https://bugs.python.org/issue?@action=redirect&bpo=41837]: Update macOS installer build to use OpenSSL 1.1.1i.

bpo-42584 [https://bugs.python.org/issue?@action=redirect&bpo=42584]: Update macOS installer to use SQLite 3.34.0.

Tools/Demos

bpo-42726 [https://bugs.python.org/issue?@action=redirect&bpo=42726]: Fixed Python 3 compatibility issue with gdb/libpython.py handling of attribute dictionaries.

bpo-42613 [https://bugs.python.org/issue?@action=redirect&bpo=42613]: Fix freeze.py tool to use the prope config and library directories. Patch by Victor Stinner.

C API

bpo-42591 [https://bugs.python.org/issue?@action=redirect&bpo=42591]: Export the Py_FrozenMain() function: fix a Python 3.9.0 regression. Python 3.9 uses -fvisibility=hidden and the function was not exported explicitly and so not exported.

bpo-32381 [https://bugs.python.org/issue?@action=redirect&bpo=32381]: Remove the private _Py_fopen() function which is no longer needed. Use _Py_wfopen() or _Py_fopen_obj() instead. Patch by Victor Stinner.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port resource extension module to module state

bpo-42111 [https://bugs.python.org/issue?@action=redirect&bpo=42111]: Update the xxlimited module to be a better example of how to use the limited C API.

bpo-40052 [https://bugs.python.org/issue?@action=redirect&bpo=40052]: Fix an alignment build warning/error in function PyVectorcall_Function(). Patch by Andreas Schneider, Antoine Pitrou and Petr Viktorin.

Python 3.10.0 alpha 3

Release date: 2020-12-07

Security

bpo-40791 [https://bugs.python.org/issue?@action=redirect&bpo=40791]: Add volatile to the accumulator variable in hmac.compare_digest, making constant-time-defeating optimizations less likely.

Core and Builtins

bpo-42576 [https://bugs.python.org/issue?@action=redirect&bpo=42576]: types.GenericAlias will now raise a 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.

bpo-42536 [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 garbage collector:

collections.OrderedDict.items()

dict.items()

enumerate()

functools.reduce()

itertools.combinations()

itertools.combinations_with_replacement()

itertools.permutations()

itertools.product()

itertools.zip_longest()

zip()

Previously, they could have become untracked by a prior garbage collection. Patch by Brandt Bucher.

bpo-42500 [https://bugs.python.org/issue?@action=redirect&bpo=42500]: Improve handling of exceptions near recursion limit. Converts a number of Fatal Errors in RecursionErrors.

bpo-42246 [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.

bpo-42435 [https://bugs.python.org/issue?@action=redirect&bpo=42435]: Speed up comparison of bytes objects with non-bytes objects when option -b is specified. Speed up comparison of bytarray objects with non-buffer object.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port the _warnings extension module to the multi-phase initialization API (PEP 489 [https://peps.python.org/pep-0489/]). Patch by Victor Stinner.

bpo-41686 [https://bugs.python.org/issue?@action=redirect&bpo=41686]: On Windows, the SIGINT event, _PyOS_SigintEvent(), is now created even if Python is configured to not install signal handlers (if PyConfig.install_signal_handlers equals to 0, or Py_InitializeEx(0)).

bpo-42381 [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.

bpo-42202 [https://bugs.python.org/issue?@action=redirect&bpo=42202]: Change function parameters annotations internal representation to tuple of strings. Patch provided by Yurii Karabas.

bpo-42374 [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.

bpo-42316 [https://bugs.python.org/issue?@action=redirect&bpo=42316]: Allow an unparenthesized walrus in subscript indexes.

bpo-42349 [https://bugs.python.org/issue?@action=redirect&bpo=42349]: Make sure that the compiler front-end produces a well-formed control flow graph. Be be more aggressive in the compiler back-end, as it is now safe to do so.

bpo-42296 [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.

bpo-42332 [https://bugs.python.org/issue?@action=redirect&bpo=42332]: types.GenericAlias objects can now be the targets of weakrefs.

bpo-42282 [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.

bpo-42266 [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.

bpo-40077 [https://bugs.python.org/issue?@action=redirect&bpo=40077]: Convert queue to use heap types.

bpo-42246 [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.

bpo-40077 [https://bugs.python.org/issue?@action=redirect&bpo=40077]: Convert mmap to use heap types.

bpo-42233 [https://bugs.python.org/issue?@action=redirect&bpo=42233]: Allow GenericAlias objects to use union type expressions. This allows expressions like list[int] | dict[float, str] where previously a TypeError would have been thrown. This also fixes union type expressions not de-duplicating GenericAlias objects. (Contributed by Ken Jin in bpo-42233 [https://bugs.python.org/issue?@action=redirect&bpo=42233].)

bpo-26131 [https://bugs.python.org/issue?@action=redirect&bpo=26131]: The import system triggers a ImportWarning when it falls back to using load_module().

Library

bpo-5054 [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.

bpo-42562 [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.

bpo-17735 [https://bugs.python.org/issue?@action=redirect&bpo=17735]: inspect.findsource() now raises OSError instead of IndexError when 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.

bpo-42116 [https://bugs.python.org/issue?@action=redirect&bpo=42116]: Fix handling of trailing comments by inspect.getsource().

bpo-42532 [https://bugs.python.org/issue?@action=redirect&bpo=42532]: Remove unexpected call of __bool__ when passing a spec_arg argument to a Mock.

bpo-38200 [https://bugs.python.org/issue?@action=redirect&bpo=38200]: Added itertools.pairwise()

bpo-41818 [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.

bpo-42487 [https://bugs.python.org/issue?@action=redirect&bpo=42487]: ChainMap.__iter__ no longer calls __getitem__ on underlying maps

bpo-42482 [https://bugs.python.org/issue?@action=redirect&bpo=42482]: 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.

bpo-41818 [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.

bpo-42392 [https://bugs.python.org/issue?@action=redirect&bpo=42392]: Remove loop parameter from asyncio.subprocess and asyncio.tasks functions. Patch provided by Yurii Karabas.

bpo-42392 [https://bugs.python.org/issue?@action=redirect&bpo=42392]: Remove loop parameter from asyncio.open_connection and asyncio.start_server functions. Patch provided by Yurii Karabas.

bpo-28468 [https://bugs.python.org/issue?@action=redirect&bpo=28468]: Add platform.freedesktop_os_release() function to parse freedesktop.org os-release files.

bpo-42299 [https://bugs.python.org/issue?@action=redirect&bpo=42299]: Removed the 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.

bpo-26131 [https://bugs.python.org/issue?@action=redirect&bpo=26131]: Deprecate zipimport.zipimporter.load_module() in favour of exec_module().

bpo-41818 [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.

bpo-42392 [https://bugs.python.org/issue?@action=redirect&bpo=42392]: Remove loop parameter from __init__ in all asyncio.locks and asyncio.Queue classes. Patch provided by Yurii Karabas.

bpo-15450 [https://bugs.python.org/issue?@action=redirect&bpo=15450]: Make filecmp.dircmp respect subclassing. Now the filecmp.dircmp.subdirs behaves as expected when subclassing dircmp.

bpo-42413 [https://bugs.python.org/issue?@action=redirect&bpo=42413]: The exception socket.timeout is now an alias of TimeoutError.

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Support signal module on VxWorks.

bpo-42406 [https://bugs.python.org/issue?@action=redirect&bpo=42406]: We fixed an issue in pickle.whichmodule in which importing multiprocessing could change the how pickle identifies which module an object belongs to, potentially breaking the unpickling of those objects.

bpo-42403 [https://bugs.python.org/issue?@action=redirect&bpo=42403]: Simplify the importlib external bootstrap code: importlib._bootstrap_external now uses regular imports to import builtin modules. When it is imported, the builtin __import__() function is already fully working and so can be used to import builtin modules like sys. Patch by Victor Stinner.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Convert _sre module types to heap types (PEP 384). Patch by Erlend E. Aasland.

bpo-42375 [https://bugs.python.org/issue?@action=redirect&bpo=42375]: subprocess module update for DragonFlyBSD support.

bpo-41713 [https://bugs.python.org/issue?@action=redirect&bpo=41713]: Port the _signal extension module to the multi-phase initialization API (PEP 489 [https://peps.python.org/pep-0489/]). Patch by Victor Stinner and Mohamed Koubaa.

bpo-37205 [https://bugs.python.org/issue?@action=redirect&bpo=37205]: time.time(), time.perf_counter() and time.monotonic() functions can no longer fail with a Python fatal error, instead raise a regular Python exception on failure.

bpo-42328 [https://bugs.python.org/issue?@action=redirect&bpo=42328]: Fixed tkinter.ttk.Style.map(). The function accepts now the representation of the default state as empty sequence (as returned by Style.map()). The structure of the result is now the same on all platform and does not depend on the value of wantobjects.

bpo-42345 [https://bugs.python.org/issue?@action=redirect&bpo=42345]: Fix various issues with typing.Literal parameter handling (flatten, deduplicate, use type to cache key). Patch provided by Yurii Karabas.

bpo-37205 [https://bugs.python.org/issue?@action=redirect&bpo=37205]: time.perf_counter() on Windows and 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 time.perf_counter_ns() and time.monotonic_ns() added in Python 3.7 to avoid this precision loss.

bpo-42318 [https://bugs.python.org/issue?@action=redirect&bpo=42318]: Fixed support of non-BMP characters in tkinter on macOS.

bpo-42350 [https://bugs.python.org/issue?@action=redirect&bpo=42350]: Fix the 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.

bpo-42333 [https://bugs.python.org/issue?@action=redirect&bpo=42333]: Port _ssl extension module to heap types.

bpo-42014 [https://bugs.python.org/issue?@action=redirect&bpo=42014]: The onerror callback from shutil.rmtree now receives correct function when os.open fails.

bpo-42237 [https://bugs.python.org/issue?@action=redirect&bpo=42237]: Fix os.sendfile() on illumos.

bpo-42308 [https://bugs.python.org/issue?@action=redirect&bpo=42308]: Add threading.__excepthook__ to allow retrieving the original value of threading.excepthook() in case it is set to a broken or a different value. Patch by Mario Corchero.

bpo-42131 [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().

bpo-41877 [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.

bpo-42264 [https://bugs.python.org/issue?@action=redirect&bpo=42264]: sqlite3.OptimizedUnicode has been undocumented and obsolete since Python 3.3, when it was made an alias to str. It is now deprecated, scheduled for removal in Python 3.12.

bpo-42251 [https://bugs.python.org/issue?@action=redirect&bpo=42251]: Added threading.gettrace() and threading.getprofile() to retrieve the functions set by threading.settrace() and threading.setprofile() respectively. Patch by Mario Corchero.

bpo-42249 [https://bugs.python.org/issue?@action=redirect&bpo=42249]: Fixed writing binary Plist files larger than 4 GiB.

bpo-42236 [https://bugs.python.org/issue?@action=redirect&bpo=42236]: On Unix, the os.device_encoding() function now returns 'UTF-8' rather than the device encoding if the Python UTF-8 Mode is enabled.

bpo-41754 [https://bugs.python.org/issue?@action=redirect&bpo=41754]: webbrowser: Ignore NotADirectoryError when calling xdg-settings.

bpo-42183 [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.

bpo-42140 [https://bugs.python.org/issue?@action=redirect&bpo=42140]: Improve asyncio.wait function to create the futures set just one time.

bpo-42133 [https://bugs.python.org/issue?@action=redirect&bpo=42133]: Update various modules in the stdlib to fall back on __spec__.loader when __loader__ isn't defined on a module.

bpo-26131 [https://bugs.python.org/issue?@action=redirect&bpo=26131]: The load_module() methods found in importlib now trigger a DeprecationWarning.

bpo-39825 [https://bugs.python.org/issue?@action=redirect&bpo=39825]: Windows: Change sysconfig.get_config_var('EXT_SUFFIX') to the expected full platform_tag.extension format. Previously it was hard-coded to .pyd, now it is compatible with distutils.sysconfig and will result in something like .cp38-win_amd64.pyd. This brings windows into conformance with the other platforms.

bpo-26389 [https://bugs.python.org/issue?@action=redirect&bpo=26389]: The traceback.format_exception(), traceback.format_exception_only(), and traceback.print_exception() functions can now take an exception object as a positional-only argument.

bpo-41889 [https://bugs.python.org/issue?@action=redirect&bpo=41889]: Enum: fix regression involving inheriting a multiply inherited enum

bpo-41861 [https://bugs.python.org/issue?@action=redirect&bpo=41861]: Convert sqlite3 to use heap types (PEP 384). Patch by Erlend E. Aasland.

bpo-40624 [https://bugs.python.org/issue?@action=redirect&bpo=40624]: Added support for the XPath != operator in xml.etree

bpo-28850 [https://bugs.python.org/issue?@action=redirect&bpo=28850]: Fix pprint.PrettyPrinter.format() overrides being ignored for contents of small containers. The pprint._safe_repr() function was removed.

bpo-41625 [https://bugs.python.org/issue?@action=redirect&bpo=41625]: Expose the splice() as os.splice() in the os module. Patch by Pablo Galindo

bpo-34215 [https://bugs.python.org/issue?@action=redirect&bpo=34215]: Clarify the error message for asyncio.IncompleteReadError when expected is None.

bpo-41543 [https://bugs.python.org/issue?@action=redirect&bpo=41543]: Add async context manager support for contextlib.nullcontext.

bpo-21041 [https://bugs.python.org/issue?@action=redirect&bpo=21041]: pathlib.PurePath.parents now supports negative indexing. Patch contributed by Yaroslav Pankovych.

bpo-41332 [https://bugs.python.org/issue?@action=redirect&bpo=41332]: Added missing connect_accepted_socket() method to asyncio.AbstractEventLoop.

bpo-12800 [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.

bpo-40968 [https://bugs.python.org/issue?@action=redirect&bpo=40968]: urllib.request and http.client now send http/1.1 ALPN extension during TLS handshake when no custom context is supplied.

bpo-41001 [https://bugs.python.org/issue?@action=redirect&bpo=41001]: Add os.eventfd() to provide a low level interface for Linux's event notification file descriptor.

bpo-40816 [https://bugs.python.org/issue?@action=redirect&bpo=40816]: Add AsyncContextDecorator to contextlib to support async context manager as a decorator.

bpo-40550 [https://bugs.python.org/issue?@action=redirect&bpo=40550]: Fix time-of-check/time-of-action issue in subprocess.Popen.send_signal.

bpo-39411 [https://bugs.python.org/issue?@action=redirect&bpo=39411]: Add an is_async identifier to pyclbr's Function objects. Patch by Batuhan Taskaya

bpo-35498 [https://bugs.python.org/issue?@action=redirect&bpo=35498]: Add slice support to pathlib.PurePath.parents.

Documentation

bpo-42238 [https://bugs.python.org/issue?@action=redirect&bpo=42238]: Tentative to deprecate make suspicious by first removing it from the CI and documentation builds, but keeping it around for manual uses.

bpo-42153 [https://bugs.python.org/issue?@action=redirect&bpo=42153]: Fix the URL for the IMAP protocol documents.

bpo-41028 [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.

Tests

bpo-41473 [https://bugs.python.org/issue?@action=redirect&bpo=41473]: Re-enable test_gdb on gdb 9.2 and newer: https://bugzilla.redhat.com/show_bug.cgi?id=1866884 bug is fixed in gdb 10.1.

bpo-42553 [https://bugs.python.org/issue?@action=redirect&bpo=42553]: Fix test_asyncio.test_call_later() race condition: don't measure asyncio performance in the call_later() unit test. The test failed randomly on the CI.

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Fix test_netrc on VxWorks: create temporary directories using temp_cwd().

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: skip test_getaddrinfo_ipv6_scopeid_symbolic and test_getnameinfo_ipv6_scopeid_symbolic on VxWorks

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: skip test_test of test_mailcap on VxWorks

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: add shell requirement for test_pipes

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: skip some tests related to fifo on VxWorks

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Fix test_doctest.py failures for VxWorks.

bpo-40754 [https://bugs.python.org/issue?@action=redirect&bpo=40754]: Include _testinternalcapi module in Windows installer for test suite

bpo-41561 [https://bugs.python.org/issue?@action=redirect&bpo=41561]: test_ssl: skip test_min_max_version_mismatch when TLS 1.0 is not available

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Fix os module failures for VxWorks RTOS.

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Fix fifo test cases for VxWorks RTOS.

Build

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: remove libnet dependency from detect_socket() for VxWorks

bpo-42398 [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.

bpo-41617 [https://bugs.python.org/issue?@action=redirect&bpo=41617]: Fix building pycore_bitutils.h internal header on old clang version without __builtin_bswap16() (ex: Xcode 4.6.3 on Mac OS X 10.7). Patch by Joshua Root and Victor Stinner.

bpo-38823 [https://bugs.python.org/issue?@action=redirect&bpo=38823]: It is no longer possible to build the _ctypes extension module without wchar_t type: remove CTYPES_UNICODE macro. Anyway, the wchar_t type is required to build Python. Patch by Victor Stinner.

bpo-42087 [https://bugs.python.org/issue?@action=redirect&bpo=42087]: Support was removed for AIX 5.3 and below. See bpo-40680 [https://bugs.python.org/issue?@action=redirect&bpo=40680].

bpo-40998 [https://bugs.python.org/issue?@action=redirect&bpo=40998]: Addressed three compiler warnings found by undefined behavior sanitizer (ubsan).

Windows

bpo-42120 [https://bugs.python.org/issue?@action=redirect&bpo=42120]: Remove macro definition of copysign (to _copysign) in headers.

bpo-38506 [https://bugs.python.org/issue?@action=redirect&bpo=38506]: The Windows launcher now properly handles Python 3.10 when listing installed Python versions.

macOS

bpo-42504 [https://bugs.python.org/issue?@action=redirect&bpo=42504]: Fix build on macOS Big Sur when MACOSX_DEPLOYMENT_TARGET=11

bpo-41116 [https://bugs.python.org/issue?@action=redirect&bpo=41116]: Ensure distutils.unixxcompiler.find_library_file can find system provided libraries on macOS 11.

bpo-41100 [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.

bpo-42232 [https://bugs.python.org/issue?@action=redirect&bpo=42232]: Added Darwin specific madvise options to mmap module.

bpo-38443 [https://bugs.python.org/issue?@action=redirect&bpo=38443]: The --enable-universalsdk and --with-universal-archs options for the configure script now check that the specified architectures can be used.

IDLE

bpo-42508 [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.

bpo-42426 [https://bugs.python.org/issue?@action=redirect&bpo=42426]: Fix reporting offset of the RE error in searchengine.

bpo-42415 [https://bugs.python.org/issue?@action=redirect&bpo=42415]: Get docstrings for IDLE calltips more often by using inspect.getdoc.

Tools/Demos

bpo-42212 [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.

bpo-36310 [https://bugs.python.org/issue?@action=redirect&bpo=36310]: Allow Tools/i18n/pygettext.py to detect calls to gettext in f-strings.

C API

bpo-42423 [https://bugs.python.org/issue?@action=redirect&bpo=42423]: The PyType_FromSpecWithBases() and PyType_FromModuleAndSpec() functions now accept a single class as the bases argument.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port select extension module to multiphase initialization (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _posixsubprocess extension module to multiphase initialization (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _posixshmem extension module to multiphase initialization (PEP 489 [https://peps.python.org/pep-0489/])

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _struct extension module to multiphase initialization (PEP 489 [https://peps.python.org/pep-0489/])

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port spwd extension module to multiphase initialization (PEP 489 [https://peps.python.org/pep-0489/])

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port gc extension module to multiphase initialization (PEP 489 [https://peps.python.org/pep-0489/])

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _queue extension module to multiphase initialization (PEP 489 [https://peps.python.org/pep-0489/])

bpo-39573 [https://bugs.python.org/issue?@action=redirect&bpo=39573]: Convert Py_TYPE() and 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: Py_TYPE(obj) = type; and Py_SIZE(obj) = size;.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port symtable extension module to multiphase initialization (PEP 489 [https://peps.python.org/pep-0489/])

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port grp and pwd extension modules to multiphase initialization (PEP 489 [https://peps.python.org/pep-0489/])

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _random extension module to multiphase initialization (PEP 489 [https://peps.python.org/pep-0489/])

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _hashlib extension module to multiphase initialization (PEP 489 [https://peps.python.org/pep-0489/])

bpo-41713 [https://bugs.python.org/issue?@action=redirect&bpo=41713]: Removed the undocumented PyOS_InitInterrupts() function. Initializing Python already implicitly installs signal handlers: see PyConfig.install_signal_handlers. Patch by Victor Stinner.

bpo-40170 [https://bugs.python.org/issue?@action=redirect&bpo=40170]: The Py_TRASHCAN_BEGIN macro no longer accesses PyTypeObject attributes, but now can get the condition by calling the new private _PyTrash_cond() function which hides implementation details.

bpo-42260 [https://bugs.python.org/issue?@action=redirect&bpo=42260]: Py_GetPath(), Py_GetPrefix(), Py_GetExecPrefix(), Py_GetProgramFullPath(), Py_GetPythonHome() and Py_GetProgramName() functions now return NULL if called before Py_Initialize() (before Python is initialized). Use the new Python Initialization Configuration API to get the Python Path Configuration.. Patch by Victor Stinner.

bpo-42260 [https://bugs.python.org/issue?@action=redirect&bpo=42260]: The PyConfig_Read() function now only parses PyConfig.argv arguments once: PyConfig.parse_argv is set to 2 after arguments are parsed. Since Python arguments are strippped from PyConfig.argv, parsing arguments twice would parse the application options as Python options.

bpo-42262 [https://bugs.python.org/issue?@action=redirect&bpo=42262]: Added Py_NewRef() and Py_XNewRef() functions to increment the reference count of an object and return the object. Patch by Victor Stinner.

bpo-42260 [https://bugs.python.org/issue?@action=redirect&bpo=42260]: When Py_Initialize() is called twice, the second call now updates more sys attributes for the configuration, rather than only sys.argv. Patch by Victor Stinner.

bpo-41832 [https://bugs.python.org/issue?@action=redirect&bpo=41832]: The PyType_FromModuleAndSpec() function now accepts NULL tp_doc slot.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Added PyModule_AddObjectRef() function: similar to PyModule_AddObject() but don't steal a reference to the value on success. Patch by Victor Stinner.

bpo-42171 [https://bugs.python.org/issue?@action=redirect&bpo=42171]: The METH_FASTCALL calling convention is added to the limited API. The functions PyModule_AddType(), PyType_FromModuleAndSpec(), PyType_GetModule() and PyType_GetModuleState() are added to the limited API on Windows.

bpo-42085 [https://bugs.python.org/issue?@action=redirect&bpo=42085]: Add dedicated entry to PyAsyncMethods for sending values

bpo-41073 [https://bugs.python.org/issue?@action=redirect&bpo=41073]: PyType_GetSlot() can now accept static types.

bpo-30459 [https://bugs.python.org/issue?@action=redirect&bpo=30459]: PyList_SET_ITEM(), PyTuple_SET_ITEM() and PyCell_SET() macros can no longer be used as l-value or r-value. For example, x = PyList_SET_ITEM(a, b, c) and PyList_SET_ITEM(a, b, c) = x now fail with a compiler error. It prevents bugs like if (PyList_SET_ITEM (a, b, c) < 0) ... test. Patch by Zackery Spytz and Victor Stinner.

Python 3.10.0 alpha 2

Release date: 2020-11-03

Security

bpo-42103 [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.

bpo-42051 [https://bugs.python.org/issue?@action=redirect&bpo=42051]: The 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.

Core and Builtins

bpo-42236 [https://bugs.python.org/issue?@action=redirect&bpo=42236]: If the nl_langinfo(CODESET) function returns an empty string, Python now uses UTF-8 as the filesystem encoding. Patch by Victor Stinner.

bpo-42218 [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.

bpo-42214 [https://bugs.python.org/issue?@action=redirect&bpo=42214]: Fixed a possible crash in the PEG parser when checking for the '!=' token in the barry_as_flufl rule. Patch by Pablo Galindo.

bpo-42206 [https://bugs.python.org/issue?@action=redirect&bpo=42206]: Propagate and raise the errors caused by PyAST_Validate() in the parser.

bpo-41796 [https://bugs.python.org/issue?@action=redirect&bpo=41796]: The ast module internal state is now per interpreter. Patch by Victor Stinner.

bpo-42143 [https://bugs.python.org/issue?@action=redirect&bpo=42143]: Fix handling of errors during creation of PyFunctionObject, which resulted in operations on uninitialized memory. Patch by Yonatan Goldschmidt.

bpo-41659 [https://bugs.python.org/issue?@action=redirect&bpo=41659]: Fix a bug in the parser, where a curly brace following a primary didn't fail immediately. This led to invalid expressions like a {b} to throw a SyntaxError with a wrong offset, or invalid expressions ending with a curly brace like a { to not fail immediately in the REPL.

bpo-42150 [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.

bpo-42123 [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.

bpo-42093 [https://bugs.python.org/issue?@action=redirect&bpo=42093]: The LOAD_ATTR instruction now uses new "per opcode cache" mechanism and it is about 36% faster now. Patch by Pablo Galindo and Yury Selivanov.

bpo-42030 [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.

bpo-41984 [https://bugs.python.org/issue?@action=redirect&bpo=41984]: The garbage collector now tracks all user-defined classes. Patch by Brandt Bucher.

bpo-41993 [https://bugs.python.org/issue?@action=redirect&bpo=41993]: Fixed potential issues with removing not completely initialized module from sys.modules when import fails.

bpo-41979 [https://bugs.python.org/issue?@action=redirect&bpo=41979]: Star-unpacking is now allowed for with item's targets in the PEG parser.

bpo-41974 [https://bugs.python.org/issue?@action=redirect&bpo=41974]: Removed special methods __int__, __float__, __floordiv__, __mod__, __divmod__, __rfloordiv__, __rmod__ and __rdivmod__ of the complex class. They always raised a TypeError.

bpo-41902 [https://bugs.python.org/issue?@action=redirect&bpo=41902]: Micro optimization when compute sq_item and mp_subscript of range. Patch by Donghee Na.

bpo-41894 [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.

bpo-41902 [https://bugs.python.org/issue?@action=redirect&bpo=41902]: Micro optimization for range.index if step is 1. Patch by Donghee Na.

bpo-41435 [https://bugs.python.org/issue?@action=redirect&bpo=41435]: Add 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.

bpo-38605 [https://bugs.python.org/issue?@action=redirect&bpo=38605]: Enable from __future__ import annotations (PEP 563 [https://peps.python.org/pep-0563/]) by default. The values found in __annotations__ dicts are now strings, e.g. {"x": "int"} instead of {"x": int}.

Library

bpo-35455 [https://bugs.python.org/issue?@action=redirect&bpo=35455]: On Solaris, thread_time() is now implemented with gethrvtime() because clock_gettime(CLOCK_THREAD_CPUTIME_ID) is not always available. Patch by Jakub Kulik.

bpo-42233 [https://bugs.python.org/issue?@action=redirect&bpo=42233]: The repr() of typing types containing Generic Alias Types previously did not show the parameterized types in the GenericAlias. They have now been changed to do so.

bpo-29566 [https://bugs.python.org/issue?@action=redirect&bpo=29566]: binhex.binhex() consistently writes macOS 9 line endings.

bpo-26789 [https://bugs.python.org/issue?@action=redirect&bpo=26789]: The logging.FileHandler class now keeps a reference to the builtin open() function to be able to open or reopen the file during Python finalization. Fix errors like: NameError: name 'open' is not defined. Patch by Victor Stinner.

bpo-42157 [https://bugs.python.org/issue?@action=redirect&bpo=42157]: Removed the unicodedata.ucnhash_CAPI attribute which was an internal PyCapsule object. The related private _PyUnicode_Name_CAPI structure was moved to the internal C API. Patch by Victor Stinner.

bpo-42157 [https://bugs.python.org/issue?@action=redirect&bpo=42157]: Convert the unicodedata extension module to the multiphase initialization API (PEP 489 [https://peps.python.org/pep-0489/]) and convert the unicodedata.UCD static type to a heap type. Patch by Mohamed Koubaa and Victor Stinner.

bpo-42146 [https://bugs.python.org/issue?@action=redirect&bpo=42146]: Fix memory leak in subprocess.Popen() in case an uid (gid) specified in user (group, extra_groups) overflows uid_t (gid_t).

bpo-42103 [https://bugs.python.org/issue?@action=redirect&bpo=42103]: InvalidFileException and RecursionError are now the only errors caused by loading malformed binary Plist file (previously ValueError and TypeError could be raised in some specific cases).

bpo-41490 [https://bugs.python.org/issue?@action=redirect&bpo=41490]: In importlib.resources, .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.

bpo-41052 [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.

bpo-42089 [https://bugs.python.org/issue?@action=redirect&bpo=42089]: In importlib.metadata.PackageNotFoundError, make reference to the package metadata being missing to improve the user experience.

bpo-41491 [https://bugs.python.org/issue?@action=redirect&bpo=41491]: plistlib: fix parsing XML plists with hexadecimal integer values

bpo-42065 [https://bugs.python.org/issue?@action=redirect&bpo=42065]: Fix an incorrectly formatted error from _codecs.charmap_decode() when called with a mapped value outside the range of valid Unicode code points. PR by Max Bernstein.

bpo-41966 [https://bugs.python.org/issue?@action=redirect&bpo=41966]: Fix pickling pure Python datetime.time subclasses. Patch by Dean Inwood.

bpo-19270 [https://bugs.python.org/issue?@action=redirect&bpo=19270]: 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.

bpo-28660 [https://bugs.python.org/issue?@action=redirect&bpo=28660]: textwrap.wrap() now attempts to break long words after hyphens when break_long_words=True and break_on_hyphens=True.

bpo-35823 [https://bugs.python.org/issue?@action=redirect&bpo=35823]: Use vfork() instead of fork() for subprocess.Popen() on Linux to improve performance in cases where it is deemed safe.

bpo-42043 [https://bugs.python.org/issue?@action=redirect&bpo=42043]: Add support for zipfile.Path inheritance. zipfile.Path.is_file() now returns False for non-existent names. zipfile.Path objects now expose a .filename attribute and rely on that to resolve .name and .parent when the Path object is at the root of the zipfile.

bpo-42021 [https://bugs.python.org/issue?@action=redirect&bpo=42021]: Fix possible ref leaks in sqlite3 module init.

bpo-39101 [https://bugs.python.org/issue?@action=redirect&bpo=39101]: Fixed tests using IsolatedAsyncioTestCase from hanging on BaseExceptions.

bpo-41976 [https://bugs.python.org/issue?@action=redirect&bpo=41976]: Fixed a bug that was causing ctypes.util.find_library() to return None when triying to locate a library in an environment when gcc>=9 is available and ldconfig is not. Patch by Pablo Galindo

bpo-41943 [https://bugs.python.org/issue?@action=redirect&bpo=41943]: Fix bug where TestCase.assertLogs doesn't correctly filter messages by level.

bpo-41923 [https://bugs.python.org/issue?@action=redirect&bpo=41923]: Implement PEP 613 [https://peps.python.org/pep-0613/], introducing typing.TypeAlias annotation.

bpo-41905 [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.

bpo-23706 [https://bugs.python.org/issue?@action=redirect&bpo=23706]: Added newline parameter to pathlib.Path.write_text().

bpo-41876 [https://bugs.python.org/issue?@action=redirect&bpo=41876]: Tkinter font class repr uses font name

bpo-41831 [https://bugs.python.org/issue?@action=redirect&bpo=41831]: str() for the type attribute of the tkinter.Event object always returns now the numeric code returned by Tk instead of the name of the event type.

bpo-39337 [https://bugs.python.org/issue?@action=redirect&bpo=39337]: encodings.normalize_encoding() now ignores non-ASCII characters.

bpo-41747 [https://bugs.python.org/issue?@action=redirect&bpo=41747]: Ensure all methods that generated from dataclasses.dataclass() objects now have the proper __qualname__ attribute referring to the class they belong to. Patch by Batuhan Taskaya.

bpo-30681 [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

bpo-41586 [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.

bpo-41229 [https://bugs.python.org/issue?@action=redirect&bpo=41229]: Add contextlib.aclosing for deterministic cleanup of async generators which is analogous to contextlib.closing for non-async generators. Patch by Joongi Kim and John Belmonte.

bpo-16396 [https://bugs.python.org/issue?@action=redirect&bpo=16396]: Allow ctypes.wintypes to be imported on non-Windows systems.

bpo-4356 [https://bugs.python.org/issue?@action=redirect&bpo=4356]: Add a key function to the bisect module.

bpo-40592 [https://bugs.python.org/issue?@action=redirect&bpo=40592]: shutil.which() now ignores empty entries in PATHEXT instead of treating them as a match.

bpo-40492 [https://bugs.python.org/issue?@action=redirect&bpo=40492]: Fix --outfile for cProfile / profile not writing the output file in the original directory when the program being profiled changes the working directory. PR by Anthony Sottile.

bpo-34204 [https://bugs.python.org/issue?@action=redirect&bpo=34204]: The shelve module now uses pickle.DEFAULT_PROTOCOL by default instead of pickle protocol 3.

bpo-27321 [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.

bpo-38976 [https://bugs.python.org/issue?@action=redirect&bpo=38976]: The 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.

Documentation

bpo-42061 [https://bugs.python.org/issue?@action=redirect&bpo=42061]: Document __format__ functionality for IP addresses.

bpo-41910 [https://bugs.python.org/issue?@action=redirect&bpo=41910]: Document the default implementation of object.__eq__.

bpo-42010 [https://bugs.python.org/issue?@action=redirect&bpo=42010]: Clarify that subscription expressions are also valid for certain classes and types in the standard library, and for user-defined classes and types if the classmethod __class_getitem__() is provided.

bpo-41805 [https://bugs.python.org/issue?@action=redirect&bpo=41805]: Documented generic alias type and types.GenericAlias. Also added an entry in glossary for generic types.

bpo-39693 [https://bugs.python.org/issue?@action=redirect&bpo=39693]: Fix tarfile's extractfile documentation

bpo-39416 [https://bugs.python.org/issue?@action=redirect&bpo=39416]: Document some restrictions on the default string representations of numeric classes.

Tests

bpo-41739 [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.

bpo-41970 [https://bugs.python.org/issue?@action=redirect&bpo=41970]: Avoid a test failure in test_lib2to3 if the module has already imported at the time the test executes. Patch by Pablo Galindo.

bpo-41944 [https://bugs.python.org/issue?@action=redirect&bpo=41944]: Tests for CJK codecs no longer call eval() on content received via HTTP.

bpo-41306 [https://bugs.python.org/issue?@action=redirect&bpo=41306]: Fixed a failure in test_tk.test_widgets.ScaleTest happening when executing the test with Tk 8.6.10.

Build

bpo-38980 [https://bugs.python.org/issue?@action=redirect&bpo=38980]: Add -fno-semantic-interposition to both the compile and link line when building with --enable-optimizations. Patch by Victor Stinner and Pablo Galindo.

Windows

bpo-38439 [https://bugs.python.org/issue?@action=redirect&bpo=38439]: Updates the icons for IDLE in the Windows Store package.

bpo-38252 [https://bugs.python.org/issue?@action=redirect&bpo=38252]: Use 8-byte step to detect ASCII sequence in 64-bit Windows build.

bpo-39107 [https://bugs.python.org/issue?@action=redirect&bpo=39107]: Update Tcl and Tk to 8.6.10 in Windows installer.

bpo-41557 [https://bugs.python.org/issue?@action=redirect&bpo=41557]: Update Windows installer to use SQLite 3.33.0.

bpo-38324 [https://bugs.python.org/issue?@action=redirect&bpo=38324]: Avoid Unicode errors when accessing certain locale data on Windows.

macOS

bpo-41471 [https://bugs.python.org/issue?@action=redirect&bpo=41471]: Ignore invalid prefix lengths in system proxy excludes.

IDLE

bpo-33987 [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.

bpo-40511 [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.

bpo-38439 [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.

C API

bpo-42157 [https://bugs.python.org/issue?@action=redirect&bpo=42157]: The private _PyUnicode_Name_CAPI structure of the PyCapsule API unicodedata.ucnhash_CAPI has been moved to the internal C API. Patch by Victor Stinner.

bpo-42015 [https://bugs.python.org/issue?@action=redirect&bpo=42015]: Fix potential crash in deallocating method objects when dynamically allocated PyMethodDef's lifetime is managed through the self argument of a PyCFunction.

bpo-40423 [https://bugs.python.org/issue?@action=redirect&bpo=40423]: The subprocess module and os.closerange will now use the close_range(low, high, flags) syscall when it is available for more efficient closing of ranges of descriptors.

bpo-41845 [https://bugs.python.org/issue?@action=redirect&bpo=41845]: PyObject_GenericGetDict() is available again in the limited API when targeting 3.10 or later.

bpo-40422 [https://bugs.python.org/issue?@action=redirect&bpo=40422]: Add _Py_closerange function to provide performant closing of a range of file descriptors.

bpo-41986 [https://bugs.python.org/issue?@action=redirect&bpo=41986]: Py_FileSystemDefaultEncodeErrors and Py_UTF8Mode are available again in limited API.

bpo-41756 [https://bugs.python.org/issue?@action=redirect&bpo=41756]: Add PyIter_Send function to allow sending value into generator/coroutine/iterator without raising StopIteration exception to signal return.

bpo-41784 [https://bugs.python.org/issue?@action=redirect&bpo=41784]: Added PyUnicode_AsUTF8AndSize to the limited C API.

Python 3.10.0 alpha 1

Release date: 2020-10-05

Security

bpo-41304 [https://bugs.python.org/issue?@action=redirect&bpo=41304]: Fixes python3x._pth being ignored on Windows, caused by the fix for bpo-29778 [https://bugs.python.org/issue?@action=redirect&bpo=29778] (CVE-2020-15801 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-15801]).

bpo-41162 [https://bugs.python.org/issue?@action=redirect&bpo=41162]: Audit hooks are now cleared later during finalization to avoid missing events.

bpo-29778 [https://bugs.python.org/issue?@action=redirect&bpo=29778]: Ensure python3.dll is loaded from correct locations when Python is embedded (CVE-2020-15523 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-15523]).

bpo-41004 [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).

bpo-39603 [https://bugs.python.org/issue?@action=redirect&bpo=39603]: Prevent http header injection by rejecting control characters in http.client.putrequest(...).

Core and Builtins

bpo-41909 [https://bugs.python.org/issue?@action=redirect&bpo=41909]: Fixed stack overflow in issubclass() and isinstance() when getting the __bases__ attribute leads to infinite recursion.

bpo-41922 [https://bugs.python.org/issue?@action=redirect&bpo=41922]: Speed up calls to reversed() by using the PEP 590 [https://peps.python.org/pep-0590/] vectorcall calling convention. Patch by Donghee Na.

bpo-41873 [https://bugs.python.org/issue?@action=redirect&bpo=41873]: Calls to float() are now faster due to the vectorcall calling convention. Patch by Dennis Sweeney.

bpo-41870 [https://bugs.python.org/issue?@action=redirect&bpo=41870]: Speed up calls to bool() by using the PEP 590 [https://peps.python.org/pep-0590/] vectorcall calling convention. Patch by Donghee Na.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port the _bisect module to the multi-phase initialization API (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-39934 [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.

bpo-41780 [https://bugs.python.org/issue?@action=redirect&bpo=41780]: Fix __dir__() of types.GenericAlias. Patch by Batuhan Taskaya.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port the _lsprof extension module to multi-phase initialization (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port the cmath extension module to multi-phase initialization (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port the _scproxy extension module to multi-phase initialization (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port the termios extension module to multi-phase initialization (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Convert the _sha256 extension module types to heap types.

bpo-41690 [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.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port the _overlapped extension module to multi-phase initialization (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port the _curses_panel extension module to multi-phase initialization (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port the _opcode extension module to multi-phase initialization (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-41681 [https://bugs.python.org/issue?@action=redirect&bpo=41681]: Fixes the wrong error description in the error raised by using 2 , in format string in f-string and str.format().

bpo-41675 [https://bugs.python.org/issue?@action=redirect&bpo=41675]: The implementation of signal.siginterrupt() now uses sigaction() (if it is available in the system) instead of the deprecated siginterrupt(). Patch by Pablo Galindo.

bpo-41670 [https://bugs.python.org/issue?@action=redirect&bpo=41670]: Prevent line trace being skipped on platforms not compiled with USE_COMPUTED_GOTOS. Fixes issue where some lines nested within a try-except block were not being traced on Windows.

bpo-41654 [https://bugs.python.org/issue?@action=redirect&bpo=41654]: Fix a crash that occurred when destroying subclasses of MemoryError. Patch by Pablo Galindo.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port the zlib extension module to multi-phase initialization (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-41631 [https://bugs.python.org/issue?@action=redirect&bpo=41631]: The _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 __import__() function to implement lazy import, whereas Python expected that import _ast always return a fully initialized _ast module.

bpo-40077 [https://bugs.python.org/issue?@action=redirect&bpo=40077]: Convert _operator to use PyType_FromSpec().

bpo-1653741 [https://bugs.python.org/issue?@action=redirect&bpo=1653741]: Port _sha3 to multi-phase init. Convert static types to heap types.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port the _blake2 extension module to the multi-phase initialization API (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-41533 [https://bugs.python.org/issue?@action=redirect&bpo=41533]: Free the stack allocated in va_build_stack if do_mkstack fails and the stack is not a small_stack.

bpo-41531 [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.

bpo-41525 [https://bugs.python.org/issue?@action=redirect&bpo=41525]: The output of python --help contains now only ASCII characters.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port the _sha1, _sha512, and _md5 extension modules to multi-phase initialization API (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-41431 [https://bugs.python.org/issue?@action=redirect&bpo=41431]: Optimize dict_merge() for copying dict (e.g. dict(d) and {}.update(d)).

bpo-41428 [https://bugs.python.org/issue?@action=redirect&bpo=41428]: Implement PEP 604. This supports (int | str) etc. in place of Union[str, int].

bpo-41340 [https://bugs.python.org/issue?@action=redirect&bpo=41340]: Removed fallback implementation for strdup.

bpo-38156 [https://bugs.python.org/issue?@action=redirect&bpo=38156]: Handle interrupts that come after EOF correctly in PyOS_StdioReadline.

bpo-41342 [https://bugs.python.org/issue?@action=redirect&bpo=41342]: round() with integer argument is now faster (9--60%).

bpo-41334 [https://bugs.python.org/issue?@action=redirect&bpo=41334]: Constructors str(), bytes() and bytearray() are now faster (around 30--40% for small objects).

bpo-41295 [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.

bpo-41323 [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.

bpo-41247 [https://bugs.python.org/issue?@action=redirect&bpo=41247]: Always cache the running loop holder when running asyncio.set_running_loop.

bpo-41252 [https://bugs.python.org/issue?@action=redirect&bpo=41252]: Fix incorrect refcounting in _ssl.c's _servername_callback().

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port multiprocessing to multi-phase initialization

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port winapi to multiphase initialization

bpo-41215 [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.

bpo-41218 [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.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port faulthandler to multiphase initialization.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port sha256 to multiphase initialization

bpo-41175 [https://bugs.python.org/issue?@action=redirect&bpo=41175]: Guard against a NULL pointer dereference within bytearrayobject triggered by the bytearray() + bytearray() operation.

bpo-41100 [https://bugs.python.org/issue?@action=redirect&bpo=41100]: add arm64 to the allowable Mac OS arches in mpdecimal.h

bpo-41094 [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.

bpo-39960 [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.

bpo-41084 [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 SyntaxError.

bpo-40521 [https://bugs.python.org/issue?@action=redirect&bpo=40521]: Empty frozensets are no longer singletons.

bpo-41076 [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.

bpo-41056 [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)

bpo-41061 [https://bugs.python.org/issue?@action=redirect&bpo=41061]: Fix incorrect expressions and asserts in hashtable code and tests.

bpo-41052 [https://bugs.python.org/issue?@action=redirect&bpo=41052]: Opt out serialization/deserialization for _random.Random

bpo-40939 [https://bugs.python.org/issue?@action=redirect&bpo=40939]: Rename PyPegen* functions to PyParser*, so that we can remove the old set of PyParser* functions that were using the old parser, but keep everything backwards-compatible.

bpo-35975 [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.

bpo-40939 [https://bugs.python.org/issue?@action=redirect&bpo=40939]: Remove the remaining files from the old parser and the symbol module.

bpo-40077 [https://bugs.python.org/issue?@action=redirect&bpo=40077]: Convert _bz2 to use PyType_FromSpec().

bpo-41006 [https://bugs.python.org/issue?@action=redirect&bpo=41006]: The 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.

bpo-40636 [https://bugs.python.org/issue?@action=redirect&bpo=40636]: zip() now supports PEP 618 [https://peps.python.org/pep-0618/]'s strict parameter, which raises a ValueError if the arguments are exhausted at different lengths. Patch by Brandt Bucher.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _gdbm to multiphase initialization.

bpo-40985 [https://bugs.python.org/issue?@action=redirect&bpo=40985]: Fix a bug that caused the 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.

bpo-40958 [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.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _dbm to multiphase initialization.

bpo-40957 [https://bugs.python.org/issue?@action=redirect&bpo=40957]: Fix refleak in _Py_fopen_obj() when PySys_Audit() fails

bpo-40950 [https://bugs.python.org/issue?@action=redirect&bpo=40950]: Add a state to the nis module (PEP 3121 [https://peps.python.org/pep-3121/]) and apply the multiphase initialization. Patch by Donghee Na.

bpo-40947 [https://bugs.python.org/issue?@action=redirect&bpo=40947]: The Python Path Configuration now takes PyConfig.platlibdir in account.

bpo-40939 [https://bugs.python.org/issue?@action=redirect&bpo=40939]: Remove the old parser, the parser module and all associated support code, command-line options and environment variables. Patch by Pablo Galindo.

bpo-40847 [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 NEWLINE token was emitted. The old parser was working around the issue, but the new parser threw a SyntaxError for valid input due to this. For example, an empty line following a line continuation character was interpreted as a SyntaxError.

bpo-40890 [https://bugs.python.org/issue?@action=redirect&bpo=40890]: Each dictionary view now has a mapping attribute that provides a types.MappingProxyType wrapping the original dictionary. Patch contributed by Dennis Sweeney.

bpo-40889 [https://bugs.python.org/issue?@action=redirect&bpo=40889]: Improved the performance of symmetric difference operations on dictionary item views. Patch by Dennis Sweeney.

bpo-40904 [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 (f"{yield}"). Patch by Pablo Galindo

bpo-40903 [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 p=p=. Patch by Pablo Galindo

bpo-40880 [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.

bpo-40883 [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

bpo-40870 [https://bugs.python.org/issue?@action=redirect&bpo=40870]: Raise ValueError when validating custom AST's where the constants True, False and None are used within a ast.Name node.

bpo-40854 [https://bugs.python.org/issue?@action=redirect&bpo=40854]: Allow overriding sys.platlibdir via a new PYTHONPLATLIBDIR environment variable.

bpo-40826 [https://bugs.python.org/issue?@action=redirect&bpo=40826]: Fix GIL usage in PyOS_Readline(): lock the GIL to set an exception and pass the Python thread state when checking if there is a pending signal.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port fcntl to multiphase initialization.

bpo-19468 [https://bugs.python.org/issue?@action=redirect&bpo=19468]: Delete unnecessary instance check in importlib.reload(). Patch by Furkan Önder.

bpo-40824 [https://bugs.python.org/issue?@action=redirect&bpo=40824]: Unexpected errors in calling the __iter__ method are no longer masked by TypeError in the in operator and functions contains(), indexOf() and countOf() of the operator module.

bpo-40792 [https://bugs.python.org/issue?@action=redirect&bpo=40792]: Attributes start, stop and step of the range object now always has exact type int. Previously, they could have been an instance of a subclass of int.

bpo-40780 [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.

bpo-38964 [https://bugs.python.org/issue?@action=redirect&bpo=38964]: When there's a SyntaxError in the expression part of an fstring, the filename attribute of the SyntaxError gets correctly set to the name of the file the fstring resides in.

bpo-40750 [https://bugs.python.org/issue?@action=redirect&bpo=40750]: Support the "-d" debug flag in the new PEG parser. Patch by Pablo Galindo

bpo-40217 [https://bugs.python.org/issue?@action=redirect&bpo=40217]: Instances of types created with 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.

bpo-39573 [https://bugs.python.org/issue?@action=redirect&bpo=39573]: Py_TYPE() is changed to the inline static function. Patch by Donghee Na.

bpo-40696 [https://bugs.python.org/issue?@action=redirect&bpo=40696]: Fix a hang that can arise after generator.throw() due to a cycle in the exception context chain.

bpo-40521 [https://bugs.python.org/issue?@action=redirect&bpo=40521]: Each interpreter now its has own free lists, singletons and caches:

Free lists: float, tuple, list, dict, frame, context, asynchronous generator, MemoryError.

Singletons: empty tuple, empty bytes string, empty Unicode string, single byte character, single Unicode (latin1) character.

Slice cache.

They are no longer shared by all interpreters.

bpo-40679 [https://bugs.python.org/issue?@action=redirect&bpo=40679]: Certain TypeError messages about missing or extra arguments now include the function's qualified name. Patch by Dennis Sweeney.

bpo-29590 [https://bugs.python.org/issue?@action=redirect&bpo=29590]: Make the stack trace correct after calling generator.throw() on a generator that has yielded from a yield from.

bpo-4022 [https://bugs.python.org/issue?@action=redirect&bpo=4022]: Improve performance of generators by not raising internal StopIteration.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port mmap to multiphase initialization.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _lzma to multiphase initialization.

bpo-37999 [https://bugs.python.org/issue?@action=redirect&bpo=37999]: Builtin and extension functions that take integer arguments no longer accept Decimals, Fractions and other objects that can be converted to integers only with a loss (e.g. that have the __int__() method but do not have the __index__() method).

bpo-29882 [https://bugs.python.org/issue?@action=redirect&bpo=29882]: Add int.bit_count(), counting the number of ones in the binary representation of an integer. Patch by Niklas Fiekas.

bpo-36982 [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 curses.has_extended_color_support() to indicate whether extended color support is provided by the underlying ncurses library.

bpo-19569 [https://bugs.python.org/issue?@action=redirect&bpo=19569]: Add the private macros _Py_COMP_DIAG_PUSH, _Py_COMP_DIAG_IGNORE_DEPR_DECLS, and _Py_COMP_DIAG_POP.

bpo-26680 [https://bugs.python.org/issue?@action=redirect&bpo=26680]: The int type now supports the x.is_integer() method for compatibility with float.

Library

bpo-41900 [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.

bpo-41887 [https://bugs.python.org/issue?@action=redirect&bpo=41887]: Strip leading spaces and tabs on ast.literal_eval(). Also document stripping of spaces and tabs for eval().

bpo-41773 [https://bugs.python.org/issue?@action=redirect&bpo=41773]: Note in documentation that random.choices() doesn't support non-finite weights, raise ValueError when given non-finite weights.

bpo-41840 [https://bugs.python.org/issue?@action=redirect&bpo=41840]: Fix a bug in the symtable module that was causing module-scope global variables to not be reported as both local and global. Patch by Pablo Galindo.

bpo-41842 [https://bugs.python.org/issue?@action=redirect&bpo=41842]: Add codecs.unregister() function to unregister a codec search function.

bpo-40564 [https://bugs.python.org/issue?@action=redirect&bpo=40564]: In 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.

bpo-40670 [https://bugs.python.org/issue?@action=redirect&bpo=40670]: More reliable validation of statements in timeit.Timer. It now accepts "empty" statements (only whitespaces and comments) and rejects misindentent statements.

bpo-41833 [https://bugs.python.org/issue?@action=redirect&bpo=41833]: The threading.Thread constructor now uses the target name if the target argument is specified but the name argument is omitted.

bpo-41817 [https://bugs.python.org/issue?@action=redirect&bpo=41817]: fix tkinter.EventType Enum so all members are strings, and none are tuples

bpo-41810 [https://bugs.python.org/issue?@action=redirect&bpo=41810]: types.EllipsisType, types.NotImplementedType and types.NoneType have been reintroduced, providing a new set of types readily interpretable by static type checkers.

bpo-41815 [https://bugs.python.org/issue?@action=redirect&bpo=41815]: Fix SQLite3 segfault when backing up closed database. Patch contributed by Peter David McCormick.

bpo-41816 [https://bugs.python.org/issue?@action=redirect&bpo=41816]: StrEnum added: it ensures that all members are already strings or string candidates

bpo-41517 [https://bugs.python.org/issue?@action=redirect&bpo=41517]: fix bug allowing Enums to be extended via multiple inheritance

bpo-39587 [https://bugs.python.org/issue?@action=redirect&bpo=39587]: use the correct mix-in data type when constructing Enums

bpo-41792 [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 [https://github.com/python/typing/issues/751].

bpo-41789 [https://bugs.python.org/issue?@action=redirect&bpo=41789]: Honor object overrides in Enum class creation (specifically, __str__, __repr__, __format__, and __reduce_ex__).

bpo-32218 [https://bugs.python.org/issue?@action=redirect&bpo=32218]: enum.Flag and enum.IntFlag members are now iterable.

bpo-39651 [https://bugs.python.org/issue?@action=redirect&bpo=39651]: Fix a race condition in the call_soon_threadsafe() method of asyncio.ProactorEventLoop: do nothing if the self-pipe socket has been closed.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port the mashal extension module to the multi-phase initialization API (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port the _string extension module to the multi-phase initialization API (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-41732 [https://bugs.python.org/issue?@action=redirect&bpo=41732]: Added an iterator to memoryview.

bpo-41720 [https://bugs.python.org/issue?@action=redirect&bpo=41720]: Fixed turtle.Vec2D.__rmul__() for arguments which are not int or float.

bpo-41696 [https://bugs.python.org/issue?@action=redirect&bpo=41696]: Fix handling of debug mode in asyncio.run(). This allows setting PYTHONASYNCIODEBUG or -X dev to enable asyncio debug mode when using asyncio.run().

bpo-41687 [https://bugs.python.org/issue?@action=redirect&bpo=41687]: Fix implementation of sendfile to be compatible with Solaris.

bpo-41662 [https://bugs.python.org/issue?@action=redirect&bpo=41662]: No longer override exceptions raised in __len__() of a sequence of parameters in sqlite3 with ProgrammingError.

bpo-39010 [https://bugs.python.org/issue?@action=redirect&bpo=39010]: Restarting a ProactorEventLoop on Windows no longer logs spurious ConnectionResetErrors.

bpo-41638 [https://bugs.python.org/issue?@action=redirect&bpo=41638]: ProgrammingError message for absent parameter in sqlite3 contains now the name of the parameter instead of its index when parameters are supplied as a dict.

bpo-41662 [https://bugs.python.org/issue?@action=redirect&bpo=41662]: Fixed crash when mutate list of parameters during iteration in sqlite3.

bpo-41513 [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.

bpo-41609 [https://bugs.python.org/issue?@action=redirect&bpo=41609]: The pdb whatis command correctly reports instance methods as 'Method' rather than 'Function'.

bpo-39994 [https://bugs.python.org/issue?@action=redirect&bpo=39994]: Fixed pprint's handling of dict subclasses that override __repr__.

bpo-32751 [https://bugs.python.org/issue?@action=redirect&bpo=32751]: When cancelling the task due to a timeout, 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.

bpo-37658 [https://bugs.python.org/issue?@action=redirect&bpo=37658]: asyncio.wait_for() now properly handles races between cancellation of itself and the completion of the wrapped awaitable.

bpo-40782 [https://bugs.python.org/issue?@action=redirect&bpo=40782]: Change the method asyncio.AbstractEventLoop.run_in_executor to not be a coroutine.

bpo-41520 [https://bugs.python.org/issue?@action=redirect&bpo=41520]: Fix codeop regression that prevented turning compile warnings into errors.

bpo-41528 [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

bpo-41513 [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.

bpo-41503 [https://bugs.python.org/issue?@action=redirect&bpo=41503]: Fixed a race between setTarget and flush in logging.handlers.MemoryHandler.

bpo-41497 [https://bugs.python.org/issue?@action=redirect&bpo=41497]: Fix potential UnicodeDecodeError in dis module.

bpo-41467 [https://bugs.python.org/issue?@action=redirect&bpo=41467]: On Windows, fix asyncio recv_into() return value when the socket/pipe is closed (BrokenPipeError): return 0 rather than an empty byte string (b'').

bpo-41425 [https://bugs.python.org/issue?@action=redirect&bpo=41425]: Make tkinter doc example runnable.

bpo-41421 [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.

bpo-41440 [https://bugs.python.org/issue?@action=redirect&bpo=41440]: Add os.cpu_count() support for VxWorks RTOS.

bpo-41316 [https://bugs.python.org/issue?@action=redirect&bpo=41316]: Fix the tarfile module to write only basename of TAR file to GZIP compression header.

bpo-41384 [https://bugs.python.org/issue?@action=redirect&bpo=41384]: Raise TclError instead of TypeError when an unknown option is passed to tkinter.OptionMenu.

bpo-41317 [https://bugs.python.org/issue?@action=redirect&bpo=41317]: Use add_done_callback() in asyncio.loop.sock_accept() to unsubscribe reader early on cancellation.

bpo-41364 [https://bugs.python.org/issue?@action=redirect&bpo=41364]: Reduce import overhead of uuid.

bpo-35328 [https://bugs.python.org/issue?@action=redirect&bpo=35328]: Set the environment variable VIRTUAL_ENV_PROMPT at venv activation.

bpo-41341 [https://bugs.python.org/issue?@action=redirect&bpo=41341]: Recursive evaluation of typing.ForwardRef in get_type_hints.

bpo-41344 [https://bugs.python.org/issue?@action=redirect&bpo=41344]: Prevent creating shared_memory.SharedMemory objects with size=0.

bpo-41333 [https://bugs.python.org/issue?@action=redirect&bpo=41333]: collections.OrderedDict.pop() is now 2 times faster.

bpo-41288 [https://bugs.python.org/issue?@action=redirect&bpo=41288]: Unpickling invalid NEWOBJ_EX opcode with the C implementation raises now UnpicklingError instead of crashing.

bpo-39017 [https://bugs.python.org/issue?@action=redirect&bpo=39017]: Avoid infinite loop when reading specially crafted TAR files using the tarfile module (CVE-2019-20907 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-20907]).

bpo-41273 [https://bugs.python.org/issue?@action=redirect&bpo=41273]: Speed up any transport using _ProactorReadPipeTransport by calling recv_into instead of recv, thus not creating a new buffer for each recv call in the transport's read loop.

bpo-41235 [https://bugs.python.org/issue?@action=redirect&bpo=41235]: Fix the error handling in ssl.SSLContext.load_dh_params().

bpo-41207 [https://bugs.python.org/issue?@action=redirect&bpo=41207]: In distutils.spawn, restore expectation that DistutilsExecError is raised when the command is not found.

bpo-29727 [https://bugs.python.org/issue?@action=redirect&bpo=29727]: Register array.array as a MutableSequence. Patch by Pablo Galindo.

bpo-39168 [https://bugs.python.org/issue?@action=redirect&bpo=39168]: Remove the __new__ method of typing.Generic.

bpo-41194 [https://bugs.python.org/issue?@action=redirect&bpo=41194]: Fix a crash in the _ast module: it can no longer be loaded more than once. It now uses a global state rather than a module state.

bpo-41195 [https://bugs.python.org/issue?@action=redirect&bpo=41195]: Add read-only ssl.SSLContext.security_level attribute to retrieve the context's security level.

bpo-41193 [https://bugs.python.org/issue?@action=redirect&bpo=41193]: The write_history() atexit function of the readline completer now ignores any OSError to ignore error if the filesystem is read-only, instead of only ignoring FileNotFoundError and PermissionError.

bpo-41182 [https://bugs.python.org/issue?@action=redirect&bpo=41182]: selector: use DefaultSelector based upon implementation

bpo-41161 [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.

bpo-40874 [https://bugs.python.org/issue?@action=redirect&bpo=40874]: The decimal module now requires libmpdec-2.5.0.

bpo-41138 [https://bugs.python.org/issue?@action=redirect&bpo=41138]: Fixed the trace module CLI for Python source files with non-UTF-8 encoding.

bpo-31082 [https://bugs.python.org/issue?@action=redirect&bpo=31082]: Use the term "iterable" in the docstring for functools.reduce().

bpo-40521 [https://bugs.python.org/issue?@action=redirect&bpo=40521]: Remove freelist from collections.deque().

bpo-31938 [https://bugs.python.org/issue?@action=redirect&bpo=31938]: Fix default-value signatures of several functions in the select module - by Anthony Sottile.

bpo-41068 [https://bugs.python.org/issue?@action=redirect&bpo=41068]: Fixed reading files with non-ASCII names from ZIP archive directly after writing them.

bpo-41058 [https://bugs.python.org/issue?@action=redirect&bpo=41058]: pdb.find_function() now correctly determines the source file encoding.

bpo-41056 [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)

bpo-41056 [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)

bpo-41056 [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)

bpo-41048 [https://bugs.python.org/issue?@action=redirect&bpo=41048]: mimetypes.read_mime_types() function reads the rule file using UTF-8 encoding, not the locale encoding. Patch by Srinivas Reddy Thatiparthy.

bpo-41043 [https://bugs.python.org/issue?@action=redirect&bpo=41043]: Fixed the use of glob() in the stdlib: literal part of the path is now always correctly escaped.

bpo-41025 [https://bugs.python.org/issue?@action=redirect&bpo=41025]: Fixed an issue preventing the C implementation of zoneinfo.ZoneInfo from being subclassed.

bpo-35018 [https://bugs.python.org/issue?@action=redirect&bpo=35018]: Add the xml.sax.handler.LexicalHandler class that is present in other SAX XML implementations.

bpo-41002 [https://bugs.python.org/issue?@action=redirect&bpo=41002]: Improve performance of HTTPResponse.read with a given amount. Patch by Bruce Merry.

bpo-40448 [https://bugs.python.org/issue?@action=redirect&bpo=40448]: ensurepip now disables the use of pip cache when installing the bundled versions of pip and setuptools. Patch by Krzysztof Konopko.

bpo-40967 [https://bugs.python.org/issue?@action=redirect&bpo=40967]: Removed asyncio.Task.current_task() and asyncio.Task.all_tasks(). Patch contributed by Rémi Lapeyre.

bpo-40924 [https://bugs.python.org/issue?@action=redirect&bpo=40924]: Ensure 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.

bpo-40955 [https://bugs.python.org/issue?@action=redirect&bpo=40955]: Fix a minor memory leak in subprocess module when extra_groups was specified.

bpo-40855 [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.

bpo-40939 [https://bugs.python.org/issue?@action=redirect&bpo=40939]: Use the new PEG parser when generating the stdlib keyword module.

bpo-23427 [https://bugs.python.org/issue?@action=redirect&bpo=23427]: Add sys.orig_argv attribute: the list of the original command line arguments passed to the Python executable.

bpo-33689 [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.

bpo-40884 [https://bugs.python.org/issue?@action=redirect&bpo=40884]: Added a defaults parameter to logging.Formatter, to allow specifying default values for custom fields. Patch by Asaf Alon and Bar Harel.

bpo-40876 [https://bugs.python.org/issue?@action=redirect&bpo=40876]: Clarify error message in the csv module.

bpo-39791 [https://bugs.python.org/issue?@action=redirect&bpo=39791]: Refresh importlib.metadata from importlib_metadata 1.6.1.

bpo-40807 [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.

bpo-32604 [https://bugs.python.org/issue?@action=redirect&bpo=32604]: Fix reference leak in the select module when the module is imported in a subinterpreter.

bpo-39791 [https://bugs.python.org/issue?@action=redirect&bpo=39791]: Built-in loaders (SourceFileLoader and ZipImporter) now supply TraversableResources implementations for ResourceReader, and the fallback function has been removed.

bpo-39314 [https://bugs.python.org/issue?@action=redirect&bpo=39314]: rlcompleter.Completer and the standard Python shell now close the parenthesis for functions that take no arguments. Patch contributed by Rémi Lapeyre.

bpo-17005 [https://bugs.python.org/issue?@action=redirect&bpo=17005]: The topological sort functionality that was introduced initially in the functools module has been moved to a new graphlib module to better accommodate the new tools and keep the original scope of the functools module. Patch by Pablo Galindo

bpo-40834 [https://bugs.python.org/issue?@action=redirect&bpo=40834]: Fix truncate when sending str object with_xxsubinterpreters.channel_send.

bpo-40755 [https://bugs.python.org/issue?@action=redirect&bpo=40755]: Add rich comparisons to collections.Counter().

bpo-26407 [https://bugs.python.org/issue?@action=redirect&bpo=26407]: Unexpected errors in calling the __iter__ method are no longer masked by TypeError in csv.reader(), csv.writer.writerow() and csv.writer.writerows().

bpo-39384 [https://bugs.python.org/issue?@action=redirect&bpo=39384]: Fixed email.contentmanager to allow set_content() to set a null string.

bpo-40744 [https://bugs.python.org/issue?@action=redirect&bpo=40744]: The 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.

bpo-40777 [https://bugs.python.org/issue?@action=redirect&bpo=40777]: Initialize PyDateTime_IsoCalendarDateType.tp_base at run-time to avoid errors on some compilers.

bpo-38488 [https://bugs.python.org/issue?@action=redirect&bpo=38488]: Update ensurepip to install pip 20.1.1 and setuptools 47.1.0.

bpo-40792 [https://bugs.python.org/issue?@action=redirect&bpo=40792]: The result of operator.index() now always has exact type int. Previously, the result could have been an instance of a subclass of int.

bpo-40767 [https://bugs.python.org/issue?@action=redirect&bpo=40767]: 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.

bpo-40791 [https://bugs.python.org/issue?@action=redirect&bpo=40791]: hashlib.compare_digest() uses OpenSSL's CRYPTO_memcmp() function when OpenSSL is available.

bpo-40795 [https://bugs.python.org/issue?@action=redirect&bpo=40795]: 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 PyErr_Print().

bpo-16995 [https://bugs.python.org/issue?@action=redirect&bpo=16995]: Add base64.b32hexencode() and base64.b32hexdecode() to support the Base32 Encoding with Extended Hex Alphabet.

bpo-30008 [https://bugs.python.org/issue?@action=redirect&bpo=30008]: Fix ssl code to be compatible with OpenSSL 1.1.x builds that use no-deprecated and --api=1.1.0.

bpo-30064 [https://bugs.python.org/issue?@action=redirect&bpo=30064]: Fix asyncio loop.sock_* race condition issue

bpo-40759 [https://bugs.python.org/issue?@action=redirect&bpo=40759]: Deprecate the symbol module.

bpo-40756 [https://bugs.python.org/issue?@action=redirect&bpo=40756]: The second argument (extra) of LoggerAdapter.__init__ now defaults to None.

bpo-37129 [https://bugs.python.org/issue?@action=redirect&bpo=37129]: Add a new os.RWF_APPEND flag for os.pwritev().

bpo-40737 [https://bugs.python.org/issue?@action=redirect&bpo=40737]: Fix possible reference leak for sqlite3 initialization.

bpo-40726 [https://bugs.python.org/issue?@action=redirect&bpo=40726]: Handle cases where the end_lineno is None on ast.increment_lineno().

bpo-40698 [https://bugs.python.org/issue?@action=redirect&bpo=40698]: distutils upload creates SHA2-256 and Blake2b-256 digests. MD5 digests is skipped if platform blocks MD5.

bpo-40695 [https://bugs.python.org/issue?@action=redirect&bpo=40695]: hashlib no longer falls back to builtin hash implementations when OpenSSL provides a hash digest and the algorithm is blocked by security policy.

bpo-9216 [https://bugs.python.org/issue?@action=redirect&bpo=9216]: hashlib.new() passed usedforsecurity to OpenSSL EVP constructor _hashlib.new(). test_hashlib and test_smtplib handle strict security policy better.

bpo-40614 [https://bugs.python.org/issue?@action=redirect&bpo=40614]: ast.parse() will not parse self documenting expressions in f-strings when passed feature_version is less than (3, 8).

bpo-40626 [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.

bpo-25920 [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, socket.getaddrinfo() no longer uses an internal lock to prevent race conditions when calling 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 socket.getaddrinfo(). The lock was also used on FreeBSD older than 5.3, OpenBSD older than 201311 and NetBSD older than 4.

bpo-40671 [https://bugs.python.org/issue?@action=redirect&bpo=40671]: Prepare _hashlib for PEP 489 [https://peps.python.org/pep-0489/] and use PyModule_AddType().

bpo-32309 [https://bugs.python.org/issue?@action=redirect&bpo=32309]: Added a new coroutine 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 run_in_executor() that can directly take keyword arguments.

bpo-36543 [https://bugs.python.org/issue?@action=redirect&bpo=36543]: Restored the deprecated xml.etree.cElementTree module.

bpo-40611 [https://bugs.python.org/issue?@action=redirect&bpo=40611]: MAP_POPULATE constant has now been added to the list of exported mmap module flags.

bpo-39881 [https://bugs.python.org/issue?@action=redirect&bpo=39881]: PEP 554 for use in the test suite. (Patch By Joannah Nanjekye)

bpo-13097 [https://bugs.python.org/issue?@action=redirect&bpo=13097]: ctypes now raises an ArgumentError when a callback is invoked with more than 1024 arguments.

bpo-39385 [https://bugs.python.org/issue?@action=redirect&bpo=39385]: A new test assertion context-manager, unittest.assertNoLogs() will ensure a given block of code emits no log messages using the logging module. Contributed by Kit Yan Choi.

bpo-23082 [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.

bpo-40318 [https://bugs.python.org/issue?@action=redirect&bpo=40318]: Use SQLite3 trace v2 API, if it is available.

bpo-40105 [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.

bpo-40084 [https://bugs.python.org/issue?@action=redirect&bpo=40084]: Fix Enum.__dir__: dir(Enum.member) now includes attributes as well as methods.

bpo-31122 [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

bpo-39728 [https://bugs.python.org/issue?@action=redirect&bpo=39728]: fix default _missing_ so a duplicate ValueError is not set as the __context__ of the original ValueError.

bpo-39244 [https://bugs.python.org/issue?@action=redirect&bpo=39244]: Fixed multiprocessing.context.get_all_start_methods to properly return the default method first on macOS.

bpo-39040 [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.

bpo-38731 [https://bugs.python.org/issue?@action=redirect&bpo=38731]: Add --quiet option to command-line interface of py_compile. Patch by Gregory Schevchenko.

bpo-35714 [https://bugs.python.org/issue?@action=redirect&bpo=35714]: struct.error is now raised if there is a null character in a struct format string.

bpo-38144 [https://bugs.python.org/issue?@action=redirect&bpo=38144]: Added the root_dir and dir_fd parameters in glob.glob().

bpo-26543 [https://bugs.python.org/issue?@action=redirect&bpo=26543]: Fix IMAP4.noop() when debug mode is enabled (ex: imaplib.Debug = 3).

bpo-12178 [https://bugs.python.org/issue?@action=redirect&bpo=12178]: csv.writer() now correctly escapes escapechar when input contains escapechar. Patch by Catalin Iacob, Berker Peksag, and Itay Elbirt.

bpo-36290 [https://bugs.python.org/issue?@action=redirect&bpo=36290]: AST nodes are now raising TypeError on conflicting keyword arguments. Patch contributed by Rémi Lapeyre.

bpo-33944 [https://bugs.python.org/issue?@action=redirect&bpo=33944]: Added site.py site-packages tracing in verbose mode.

bpo-35078 [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

bpo-29620 [https://bugs.python.org/issue?@action=redirect&bpo=29620]: assertWarns() no longer raises a RuntimeException when accessing a module's __warningregistry__ causes importation of a new module, or when a new module is imported in another thread. Patch by Kernc.

bpo-31844 [https://bugs.python.org/issue?@action=redirect&bpo=31844]: Remove ParserBase.error() method from the private and undocumented _markupbase module. html.parser.HTMLParser is the only subclass of ParserBase and its error() implementation was deprecated in Python 3.4 and removed in Python 3.5.

bpo-34226 [https://bugs.python.org/issue?@action=redirect&bpo=34226]: Fix cgi.parse_multipart without content_length. Patch by Roger Duran

bpo-33660 [https://bugs.python.org/issue?@action=redirect&bpo=33660]: Fix pathlib.PosixPath to resolve a relative path located on the root directory properly.

bpo-28557 [https://bugs.python.org/issue?@action=redirect&bpo=28557]: Improve the error message for a misbehaving rawio.readinto

bpo-26680 [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.

bpo-26680 [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.

Documentation

bpo-41428 [https://bugs.python.org/issue?@action=redirect&bpo=41428]: Add documentation for PEP 604 [https://peps.python.org/pep-0604/] (Allow writing union types as X | Y).

bpo-41774 [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".

bpo-35293 [https://bugs.python.org/issue?@action=redirect&bpo=35293]: Fix RemovedInSphinx40Warning when building the documentation. Patch by Donghee Na.

bpo-37149 [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.

bpo-41726 [https://bugs.python.org/issue?@action=redirect&bpo=41726]: Update the refcounts info of PyType_FromModuleAndSpec.

bpo-41624 [https://bugs.python.org/issue?@action=redirect&bpo=41624]: Fix the signature of typing.Coroutine.

bpo-40204 [https://bugs.python.org/issue?@action=redirect&bpo=40204]: Enable Sphinx 3.2 c_allow_pre_v3 option and disable c_warn_on_allowed_pre_v3 option to make the documentation compatible with Sphinx 2 and Sphinx 3.

bpo-41045 [https://bugs.python.org/issue?@action=redirect&bpo=41045]: Add documentation for debug feature of f-strings.

bpo-41314 [https://bugs.python.org/issue?@action=redirect&bpo=41314]: Changed the release when from __future__ import annotations becomes the default from 4.0 to 3.10 (following a change in PEP 563).

bpo-40979 [https://bugs.python.org/issue?@action=redirect&bpo=40979]: Refactored typing.rst, arranging more than 70 classes, functions, and decorators into new sub-sections.

bpo-40552 [https://bugs.python.org/issue?@action=redirect&bpo=40552]: Fix in tutorial section 4.2. Code snippet is now correct.

bpo-39883 [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.

bpo-37703 [https://bugs.python.org/issue?@action=redirect&bpo=37703]: Updated Documentation to comprehensively elaborate on the behaviour of gather.cancel()

Tests

bpo-41939 [https://bugs.python.org/issue?@action=redirect&bpo=41939]: Fix test_site.test_license_exists_at_url(): call urllib.request.urlcleanup() to reset the global urllib.request._opener. Patch by Victor Stinner.

bpo-41731 [https://bugs.python.org/issue?@action=redirect&bpo=41731]: Make test_cmd_line_script pass with option '-vv'.

bpo-41602 [https://bugs.python.org/issue?@action=redirect&bpo=41602]: Add tests for SIGINT handling in the runpy module.

bpo-41521 [https://bugs.python.org/issue?@action=redirect&bpo=41521]: test.support: Rename blacklist parameter of check__all__() to not_exported.

bpo-41477 [https://bugs.python.org/issue?@action=redirect&bpo=41477]: Make ctypes optional in test_genericalias.

bpo-41085 [https://bugs.python.org/issue?@action=redirect&bpo=41085]: Fix integer overflow in the array.array.index() method on 64-bit Windows for index larger than 2**31.

bpo-41069 [https://bugs.python.org/issue?@action=redirect&bpo=41069]: test.support.TESTFN and the current directory for tests when run via test.regrtest contain now non-ascii characters if possible.

bpo-38377 [https://bugs.python.org/issue?@action=redirect&bpo=38377]: On Linux, skip tests using multiprocessing if the current user cannot create a file in /dev/shm/ directory. Add the skip_if_broken_multiprocessing_synchronize() function to the test.support module.

bpo-41009 [https://bugs.python.org/issue?@action=redirect&bpo=41009]: Fix use of support.require_{linux|mac|freebsd}_version() decorators as class decorator.

bpo-41003 [https://bugs.python.org/issue?@action=redirect&bpo=41003]: Fix test_copyreg when numpy is installed: test.pickletester now saves/restores warnings filters when importing numpy, to ignore filters installed by numpy.

bpo-40964 [https://bugs.python.org/issue?@action=redirect&bpo=40964]: Disable remote imaplib tests, host cyrus.andrew.cmu.edu is blocking incoming connections.

bpo-40927 [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.

bpo-17258 [https://bugs.python.org/issue?@action=redirect&bpo=17258]: Skip some multiprocessing tests when MD5 hash digest is blocked.

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Increase LOOPBACK_TIMEOUT to 10 for VxWorks RTOS.

bpo-38169 [https://bugs.python.org/issue?@action=redirect&bpo=38169]: Increase code coverage for SharedMemory and ShareableList

bpo-34401 [https://bugs.python.org/issue?@action=redirect&bpo=34401]: Make test_gdb properly run on HP-UX. Patch by Michael Osipov.

Build

bpo-38249 [https://bugs.python.org/issue?@action=redirect&bpo=38249]: Update Py_UNREACHABLE to use __builtin_unreachable() if only the compiler is able to use it. Patch by Donghee Na.

bpo-41617 [https://bugs.python.org/issue?@action=redirect&bpo=41617]: Fix pycore_bitutils.h header file to support old clang versions: __builtin_bswap16() is not available in LLVM clang 3.0.

bpo-40204 [https://bugs.python.org/issue?@action=redirect&bpo=40204]: Pin Sphinx version to 2.3.1 in Doc/Makefile.

bpo-36020 [https://bugs.python.org/issue?@action=redirect&bpo=36020]: The C99 functions snprintf() and vsnprintf() are now required to build Python.

bpo-40684 [https://bugs.python.org/issue?@action=redirect&bpo=40684]: make install now uses the PLATLIBDIR variable for the destination lib-dynload/ directory when ./configure --with-platlibdir is used.

bpo-40683 [https://bugs.python.org/issue?@action=redirect&bpo=40683]: Fixed an issue where the zoneinfo module and its tests were not included when Python is installed with make.

Windows

bpo-41744 [https://bugs.python.org/issue?@action=redirect&bpo=41744]: Fixes automatic import of props file when using the Nuget package.

bpo-41627 [https://bugs.python.org/issue?@action=redirect&bpo=41627]: The user site directory for 32-bit now includes a -32 suffix to distinguish it from the 64-bit interpreter's directory.

bpo-41526 [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).

bpo-41492 [https://bugs.python.org/issue?@action=redirect&bpo=41492]: Fixes the description that appears in UAC prompts.

bpo-40948 [https://bugs.python.org/issue?@action=redirect&bpo=40948]: Improve post-install message to direct people to the "py" command.

bpo-41412 [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.

bpo-40741 [https://bugs.python.org/issue?@action=redirect&bpo=40741]: Update Windows release to include SQLite 3.32.3.

bpo-41142 [https://bugs.python.org/issue?@action=redirect&bpo=41142]: msilib now supports creating CAB files with non-ASCII file path and adding files with non-ASCII file path to them.

bpo-41074 [https://bugs.python.org/issue?@action=redirect&bpo=41074]: Fixed support of non-ASCII names in functions msilib.OpenDatabase() and msilib.init_database() and non-ASCII SQL in method msilib.Database.OpenView().

bpo-41039 [https://bugs.python.org/issue?@action=redirect&bpo=41039]: Stable ABI redirection DLL (python3.dll) now uses #pragma comment(linker) for re-exporting.

bpo-40164 [https://bugs.python.org/issue?@action=redirect&bpo=40164]: Updates Windows OpenSSL to 1.1.1g

bpo-39631 [https://bugs.python.org/issue?@action=redirect&bpo=39631]: Changes the registered MIME type for .py files on Windows to text/x-python instead of text/plain.

bpo-40677 [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.

bpo-37556 [https://bugs.python.org/issue?@action=redirect&bpo=37556]: Extend py.exe help to mention overrides via venv, shebang, environmental variables & ini files.

macOS

bpo-41557 [https://bugs.python.org/issue?@action=redirect&bpo=41557]: Update macOS installer to use SQLite 3.33.0.

bpo-39580 [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.

bpo-41100 [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.

bpo-40741 [https://bugs.python.org/issue?@action=redirect&bpo=40741]: Update macOS installer to use SQLite 3.32.3.

bpo-41005 [https://bugs.python.org/issue?@action=redirect&bpo=41005]: fixed an XDG settings issue not allowing macos to open browser in webbrowser.py

bpo-40741 [https://bugs.python.org/issue?@action=redirect&bpo=40741]: Update macOS installer to use SQLite 3.32.2.

IDLE

bpo-41775 [https://bugs.python.org/issue?@action=redirect&bpo=41775]: Use 'IDLE Shell' as shell title

bpo-35764 [https://bugs.python.org/issue?@action=redirect&bpo=35764]: Rewrite the Calltips doc section.

bpo-40181 [https://bugs.python.org/issue?@action=redirect&bpo=40181]: In calltips, stop reminding that '/' marks the end of positional-only arguments.

bpo-41468 [https://bugs.python.org/issue?@action=redirect&bpo=41468]: Improve IDLE run crash error message (which users should never see).

bpo-41373 [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.

bpo-41300 [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.

bpo-37765 [https://bugs.python.org/issue?@action=redirect&bpo=37765]: Add keywords to module name completion list. Rewrite Completions section of IDLE doc.

bpo-41152 [https://bugs.python.org/issue?@action=redirect&bpo=41152]: The encoding of stdin, stdout and stderr in IDLE is now always UTF-8.

bpo-41144 [https://bugs.python.org/issue?@action=redirect&bpo=41144]: Make Open Module open a special module such as os.path.

bpo-39885 [https://bugs.python.org/issue?@action=redirect&bpo=39885]: Make context menu Cut and Copy work again when right-clicking within a selection.

bpo-40723 [https://bugs.python.org/issue?@action=redirect&bpo=40723]: Make test_idle pass when run after import.

C API

bpo-41936 [https://bugs.python.org/issue?@action=redirect&bpo=41936]: Removed undocumented macros Py_ALLOW_RECURSION and Py_END_ALLOW_RECURSION and the recursion_critical field of the PyInterpreterState structure.

bpo-41692 [https://bugs.python.org/issue?@action=redirect&bpo=41692]: The PyUnicode_InternImmortal() function is now deprecated and will be removed in Python 3.12: use PyUnicode_InternInPlace() instead. Patch by Victor Stinner.

bpo-41842 [https://bugs.python.org/issue?@action=redirect&bpo=41842]: Add PyCodec_Unregister() function to unregister a codec search function.

bpo-41834 [https://bugs.python.org/issue?@action=redirect&bpo=41834]: Remove the _Py_CheckRecursionLimit variable: it has been replaced by ceval.recursion_limit of the PyInterpreterState structure. Patch by Victor Stinner.

bpo-41689 [https://bugs.python.org/issue?@action=redirect&bpo=41689]: Types created with PyType_FromSpec() now make any signature in their tp_doc slot accessible from __text_signature__.

bpo-41524 [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.

bpo-41324 [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.

bpo-30155 [https://bugs.python.org/issue?@action=redirect&bpo=30155]: Add PyDateTime_DATE_GET_TZINFO() and PyDateTime_TIME_GET_TZINFO() macros for accessing the tzinfo attributes of datetime.datetime and datetime.time objects.

bpo-40170 [https://bugs.python.org/issue?@action=redirect&bpo=40170]: Revert PyType_HasFeature() change: it reads again directly the PyTypeObject.tp_flags member when the limited C API is not used, rather than always calling PyType_GetFlags() which hides implementation details.

bpo-41123 [https://bugs.python.org/issue?@action=redirect&bpo=41123]: Remove PyUnicode_AsUnicodeCopy.

bpo-41123 [https://bugs.python.org/issue?@action=redirect&bpo=41123]: Removed PyLong_FromUnicode().

bpo-41123 [https://bugs.python.org/issue?@action=redirect&bpo=41123]: Removed PyUnicode_GetMax().

bpo-41123 [https://bugs.python.org/issue?@action=redirect&bpo=41123]: Removed Py_UNICODE_str* functions manipulating Py_UNICODE* strings.

bpo-41103 [https://bugs.python.org/issue?@action=redirect&bpo=41103]: PyObject_AsCharBuffer(), PyObject_AsReadBuffer(), PyObject_CheckReadBuffer(), and PyObject_AsWriteBuffer() are removed. Please migrate to new buffer protocol; PyObject_GetBuffer() and PyBuffer_Release().

bpo-36346 [https://bugs.python.org/issue?@action=redirect&bpo=36346]: Raises DeprecationWarning for PyUnicode_FromUnicode(NULL, size) and PyUnicode_FromStringAndSize(NULL, size) with size > 0.

bpo-36346 [https://bugs.python.org/issue?@action=redirect&bpo=36346]: Mark Py_UNICODE_COPY, Py_UNICODE_FILL, PyUnicode_WSTR_LENGTH, PyUnicode_FromUnicode, PyUnicode_AsUnicode, and PyUnicode_AsUnicodeAndSize as deprecated in C. Remove Py_UNICODE_MATCH which was deprecated and broken since Python 3.3.

bpo-40989 [https://bugs.python.org/issue?@action=redirect&bpo=40989]: The PyObject_INIT() and PyObject_INIT_VAR() macros become aliases to, respectively, PyObject_Init() and PyObject_InitVar() functions.

bpo-36020 [https://bugs.python.org/issue?@action=redirect&bpo=36020]: On Windows, #include "pyerrors.h" no longer defines snprintf and vsnprintf macros.

bpo-40943 [https://bugs.python.org/issue?@action=redirect&bpo=40943]: The PY_SSIZE_T_CLEAN macro must now be defined to use PyArg_ParseTuple() and Py_BuildValue() formats which use #: es#, et#, s#, u#, y#, z#, U# and Z#. See Parsing arguments and building values and the PEP 353 [https://peps.python.org/pep-0353/].

bpo-40910 [https://bugs.python.org/issue?@action=redirect&bpo=40910]: Export explicitly the 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 -fvisibility=hidden.

bpo-40724 [https://bugs.python.org/issue?@action=redirect&bpo=40724]: Allow defining buffer slots in type specs.

bpo-40679 [https://bugs.python.org/issue?@action=redirect&bpo=40679]: Fix a _PyEval_EvalCode() crash if qualname argument is NULL.

bpo-40839 [https://bugs.python.org/issue?@action=redirect&bpo=40839]: Calling PyDict_GetItem() without GIL held had been allowed for historical reason. It is no longer allowed.

bpo-40826 [https://bugs.python.org/issue?@action=redirect&bpo=40826]: PyOS_InterruptOccurred() now fails with a fatal error if it is called with the GIL released.

bpo-40792 [https://bugs.python.org/issue?@action=redirect&bpo=40792]: The result of PyNumber_Index() now always has exact type int. Previously, the result could have been an instance of a subclass of int.

bpo-39573 [https://bugs.python.org/issue?@action=redirect&bpo=39573]: Convert Py_REFCNT() and Py_SIZE() macros to static inline functions. They cannot be used as l-value anymore: use Py_SET_REFCNT() and 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 PyObject structure.

bpo-40703 [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".

bpo-39583 [https://bugs.python.org/issue?@action=redirect&bpo=39583]: Remove superfluous "extern C" declarations from Include/cpython/*.h.

Python 3.9.0 beta 1

Release date: 2020-05-19

Security

bpo-40501 [https://bugs.python.org/issue?@action=redirect&bpo=40501]: uuid no longer uses ctypes to load libuuid or rpcrt4.dll at runtime.

Core and Builtins

bpo-40663 [https://bugs.python.org/issue?@action=redirect&bpo=40663]: Correctly generate annotations where parentheses are omitted but required (e.g: Type[(str, int, *other))].

bpo-40596 [https://bugs.python.org/issue?@action=redirect&bpo=40596]: Fixed str.isidentifier() for non-canonicalized strings containing non-BMP characters on Windows.

bpo-40593 [https://bugs.python.org/issue?@action=redirect&bpo=40593]: Improved syntax errors for invalid characters in source code.

bpo-40585 [https://bugs.python.org/issue?@action=redirect&bpo=40585]: Fixed a bug when using codeop.compile_command() that was causing exceptions to be swallowed with the new parser. Patch by Pablo Galindo

bpo-40566 [https://bugs.python.org/issue?@action=redirect&bpo=40566]: Apply PEP 573 [https://peps.python.org/pep-0573/] to abc.

bpo-40502 [https://bugs.python.org/issue?@action=redirect&bpo=40502]: Initialize n->n_col_offset. (Patch by Joannah Nanjekye)

bpo-40527 [https://bugs.python.org/issue?@action=redirect&bpo=40527]: Fix command line argument parsing: no longer write errors multiple times into stderr.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port errno to multiphase initialization (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-40523 [https://bugs.python.org/issue?@action=redirect&bpo=40523]: Add pass-throughs for hash() and reversed() to weakref.proxy objects. Patch by Pablo Galindo.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port syslog to multiphase initialization (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-40246 [https://bugs.python.org/issue?@action=redirect&bpo=40246]: Reporting a specialised error message for invalid string prefixes, which was introduced in bpo-40246 [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 bg="#d00" if clear else"#fca" were failing to parse, which is not an acceptable breakage on such short notice.

bpo-40417 [https://bugs.python.org/issue?@action=redirect&bpo=40417]: Fix imp module deprecation warning when PyImport_ReloadModule is called. Patch by Robert Rouhani.

bpo-40408 [https://bugs.python.org/issue?@action=redirect&bpo=40408]: Fixed support of nested type variables in GenericAlias (e.g. list[list[T]]).

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _stat module to multiphase initialization (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-29587 [https://bugs.python.org/issue?@action=redirect&bpo=29587]: Enable implicit exception chaining when calling generator.throw().

bpo-40328 [https://bugs.python.org/issue?@action=redirect&bpo=40328]: Add tools for generating mappings headers for CJKCodecs.

bpo-40228 [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

bpo-38880 [https://bugs.python.org/issue?@action=redirect&bpo=38880]: Added the ability to list interpreters associated with channel ends in the internal subinterpreters module.

bpo-37986 [https://bugs.python.org/issue?@action=redirect&bpo=37986]: Improve performance of PyLong_FromDouble() for values that fit into long.

Library

bpo-40662 [https://bugs.python.org/issue?@action=redirect&bpo=40662]: Fixed ast.get_source_segment() for ast nodes that have incomplete location information. Patch by Irit Katriel.

bpo-40665 [https://bugs.python.org/issue?@action=redirect&bpo=40665]: Convert bisect to use Argument Clinic.

bpo-40536 [https://bugs.python.org/issue?@action=redirect&bpo=40536]: Added the available_timezones() function to the zoneinfo module. Patch by Paul Ganssle.

bpo-40645 [https://bugs.python.org/issue?@action=redirect&bpo=40645]: The hmac.HMAC exposes internal implementation details. The attributes digest_cons, inner, and outer are deprecated and will be removed in the future.

bpo-40645 [https://bugs.python.org/issue?@action=redirect&bpo=40645]: The internal module _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.

bpo-40637 [https://bugs.python.org/issue?@action=redirect&bpo=40637]: Builtin hash modules can now be disabled or selectively enabled with configure --with-builtin-hashlib-hashes=sha3,blake1 or --without-builtin-hashlib-hashes.

bpo-37630 [https://bugs.python.org/issue?@action=redirect&bpo=37630]: The hashlib module can now use SHA3 hashes and SHAKE XOF from OpenSSL when available.

bpo-40479 [https://bugs.python.org/issue?@action=redirect&bpo=40479]: The hashlib now compiles with OpenSSL 3.0.0-alpha2.

bpo-40257 [https://bugs.python.org/issue?@action=redirect&bpo=40257]: Revert changes to inspect.getdoc().

bpo-40607 [https://bugs.python.org/issue?@action=redirect&bpo=40607]: When cancelling a task due to timeout, asyncio.wait_for() will now propagate the exception if an error happens during cancellation. Patch by Roman Skurikhin.

bpo-40612 [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.

bpo-40597 [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.

bpo-40571 [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).

bpo-40503 [https://bugs.python.org/issue?@action=redirect&bpo=40503]: PEP 615 [https://peps.python.org/pep-0615/], the zoneinfo module. Adds support for the IANA time zone database.

bpo-40397 [https://bugs.python.org/issue?@action=redirect&bpo=40397]: Removed attributes __args__ and __parameters__ from special generic aliases like typing.List (not subscripted).

bpo-40549 [https://bugs.python.org/issue?@action=redirect&bpo=40549]: Convert posixmodule.c ("posix" or "nt" module) to the multiphase initialization (PEP 489).

bpo-31033 [https://bugs.python.org/issue?@action=redirect&bpo=31033]: Add a msg argument to Future.cancel() and Task.cancel().

bpo-40541 [https://bugs.python.org/issue?@action=redirect&bpo=40541]: Added an optional counts parameter to random.sample().

bpo-40515 [https://bugs.python.org/issue?@action=redirect&bpo=40515]: The ssl and 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.

bpo-31033 [https://bugs.python.org/issue?@action=redirect&bpo=31033]: When a asyncio.Task is cancelled, the exception traceback now chains all the way back to where the task was first interrupted.

bpo-40504 [https://bugs.python.org/issue?@action=redirect&bpo=40504]: functools.lru_cache() objects can now be the targets of weakrefs.

bpo-40559 [https://bugs.python.org/issue?@action=redirect&bpo=40559]: Fix possible memory leak in the C implementation of asyncio.Task.

bpo-40480 [https://bugs.python.org/issue?@action=redirect&bpo=40480]: fnmatch.fnmatch() could take exponential time in the presence of multiple * pattern characters. This was repaired by generating more elaborate regular expressions to avoid futile backtracking.

bpo-40495 [https://bugs.python.org/issue?@action=redirect&bpo=40495]: compileall is now able to use hardlinks to prevent duplicates in a case when .pyc files for different optimization levels have the same content.

bpo-40457 [https://bugs.python.org/issue?@action=redirect&bpo=40457]: The ssl module now support OpenSSL builds without TLS 1.0 and 1.1 methods.

bpo-40355 [https://bugs.python.org/issue?@action=redirect&bpo=40355]: Improve error reporting in ast.literal_eval() in the presence of malformed ast.Dict nodes instead of silently ignoring any non-conforming elements. Patch by Curtis Bucher.

bpo-40465 [https://bugs.python.org/issue?@action=redirect&bpo=40465]: Deprecated the optional random argument to random.shuffle().

bpo-40459 [https://bugs.python.org/issue?@action=redirect&bpo=40459]: platform.win32_ver() now produces correct ptype strings instead of empty strings.

bpo-39435 [https://bugs.python.org/issue?@action=redirect&bpo=39435]: The first argument of pickle.loads() is now positional-only.

bpo-39305 [https://bugs.python.org/issue?@action=redirect&bpo=39305]: Update nntplib to merge nntplib.NNTP and nntplib._NNTPBase. Patch by Donghee Na.

bpo-32494 [https://bugs.python.org/issue?@action=redirect&bpo=32494]: Update dbm.gnu to use gdbm_count if possible when calling len(). Patch by Donghee Na.

bpo-40453 [https://bugs.python.org/issue?@action=redirect&bpo=40453]: Add isolated=True keyword-only parameter to _xxsubinterpreters.create(). An isolated subinterpreter cannot spawn threads, spawn a child process or call os.fork().

bpo-40286 [https://bugs.python.org/issue?@action=redirect&bpo=40286]: Remove _random.Random.randbytes(): the C implementation of randbytes(). Implement the method in Python to ease subclassing: randbytes() now directly reuses getrandbits().

bpo-40394 [https://bugs.python.org/issue?@action=redirect&bpo=40394]: Added default arguments to difflib.SequenceMatcher.find_longest_match().

bpo-39995 [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.

bpo-30966 [https://bugs.python.org/issue?@action=redirect&bpo=30966]: Process.shutdown(wait=True) of concurrent.futures now closes explicitly the result queue.

bpo-30966 [https://bugs.python.org/issue?@action=redirect&bpo=30966]: Add a new close() method to the SimpleQueue class to explicitly close the queue.

bpo-39966 [https://bugs.python.org/issue?@action=redirect&bpo=39966]: Revert bpo-25597 [https://bugs.python.org/issue?@action=redirect&bpo=25597]. unittest.mock.MagicMock with wraps' set uses default return values for magic methods.

bpo-39791 [https://bugs.python.org/issue?@action=redirect&bpo=39791]: Added files() function to importlib.resources with support for subdirectories in package data, matching backport in importlib_resources 1.5.

bpo-40375 [https://bugs.python.org/issue?@action=redirect&bpo=40375]: imaplib.IMAP4.unselect() is added. Patch by Donghee Na.

bpo-40389 [https://bugs.python.org/issue?@action=redirect&bpo=40389]: repr() now returns typing.Optional[T] when called for typing.Union of two types, one of which is NoneType.

bpo-40291 [https://bugs.python.org/issue?@action=redirect&bpo=40291]: Add support for CAN_J1939 sockets (available on Linux 5.4+)

bpo-40273 [https://bugs.python.org/issue?@action=redirect&bpo=40273]: types.MappingProxyType is now reversible.

bpo-39075 [https://bugs.python.org/issue?@action=redirect&bpo=39075]: The repr for types.SimpleNamespace is now insertion ordered rather than alphabetical.

bpo-40192 [https://bugs.python.org/issue?@action=redirect&bpo=40192]: On AIX, thread_time() is now implemented with thread_cputime() which has nanosecond resolution, rather than clock_gettime(CLOCK_THREAD_CPUTIME_ID) which has a resolution of 10 milliseconds. Patch by Batuhan Taskaya.

bpo-40025 [https://bugs.python.org/issue?@action=redirect&bpo=40025]: Raise TypeError when _generate_next_value_ is defined after members. Patch by Ethan Onstott.

bpo-39058 [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.

bpo-24416 [https://bugs.python.org/issue?@action=redirect&bpo=24416]: The isocalendar() methods of datetime.date and datetime.datetime now return a named tuple instead of a tuple.

Documentation

bpo-34790 [https://bugs.python.org/issue?@action=redirect&bpo=34790]: Add version of removal for explicit passing of coros to asyncio.wait()'s documentation

bpo-40561 [https://bugs.python.org/issue?@action=redirect&bpo=40561]: Provide docstrings for webbrowser open functions.

bpo-40499 [https://bugs.python.org/issue?@action=redirect&bpo=40499]: Mention that asyncio.wait() requires a non-empty set of awaitables.

bpo-39705 [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.

bpo-39435 [https://bugs.python.org/issue?@action=redirect&bpo=39435]: Fix an incorrect signature for pickle.loads() in the docs

Tests

bpo-40055 [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.

bpo-40436 [https://bugs.python.org/issue?@action=redirect&bpo=40436]: test_gdb and test.pythoninfo now check gdb command exit code.

Build

bpo-40653 [https://bugs.python.org/issue?@action=redirect&bpo=40653]: Move _dirnameW out of HAVE_SYMLINK to fix a potential compiling issue.

bpo-40514 [https://bugs.python.org/issue?@action=redirect&bpo=40514]: Add --with-experimental-isolated-subinterpreters build option to configure: better isolate subinterpreters, experimental build mode.

Windows

bpo-40650 [https://bugs.python.org/issue?@action=redirect&bpo=40650]: Include winsock2.h in pytime.c for timeval.

bpo-40458 [https://bugs.python.org/issue?@action=redirect&bpo=40458]: Increase reserved stack space to prevent overflow crash on Windows.

bpo-39148 [https://bugs.python.org/issue?@action=redirect&bpo=39148]: Add IPv6 support to asyncio datagram endpoints in ProactorEventLoop. Change the raised exception for unknown address families to ValueError as it's not coming from Windows API.

macOS

bpo-34956 [https://bugs.python.org/issue?@action=redirect&bpo=34956]: When building Python on macOS from source, _tkinter now links with non-system Tcl and Tk frameworks if they are installed in /Library/Frameworks, as had been the case on older releases of macOS. If a macOS SDK is explicitly configured, by using --enable-universalsdk= or -isysroot, only the SDK itself is searched. The default behavior can still be overridden with --with-tcltk-includes and --with-tcltk-libs.

bpo-35569 [https://bugs.python.org/issue?@action=redirect&bpo=35569]: Expose RFC 3542 IPv6 socket options.

Tools/Demos

bpo-40479 [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.

bpo-40431 [https://bugs.python.org/issue?@action=redirect&bpo=40431]: Fix a syntax typo in turtledemo that now raises a SyntaxError.

bpo-40163 [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.

C API

bpo-39465 [https://bugs.python.org/issue?@action=redirect&bpo=39465]: Remove the _PyUnicode_ClearStaticStrings() function from the C API.

bpo-38787 [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.

bpo-40545 [https://bugs.python.org/issue?@action=redirect&bpo=40545]: Declare _PyErr_GetTopmostException() with PyAPI_FUNC() to properly export the function in the C API. The function remains private (_Py) prefix.

bpo-40412 [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.

bpo-40429 [https://bugs.python.org/issue?@action=redirect&bpo=40429]: The PyThreadState_GetFrame() function now returns a strong reference to the frame.

bpo-40428 [https://bugs.python.org/issue?@action=redirect&bpo=40428]: Remove the following functions from the C API. Call PyGC_Collect() explicitly to free all free lists.

PyAsyncGen_ClearFreeLists()

PyContext_ClearFreeList()

PyDict_ClearFreeList()

PyFloat_ClearFreeList()

PyFrame_ClearFreeList()

PyList_ClearFreeList()

PySet_ClearFreeList()

PyTuple_ClearFreeList()

bpo-40421 [https://bugs.python.org/issue?@action=redirect&bpo=40421]: New PyFrame_GetBack() function: get the frame next outer frame.

bpo-40421 [https://bugs.python.org/issue?@action=redirect&bpo=40421]: New PyFrame_GetCode() function: return a borrowed reference to the frame code.

bpo-40217 [https://bugs.python.org/issue?@action=redirect&bpo=40217]: Ensure that instances of types created with PyType_FromSpecWithBases() will visit its class object when traversing references in the garbage collector (implemented as an extension of the provided tp_traverse). Patch by Pablo Galindo.

bpo-38787 [https://bugs.python.org/issue?@action=redirect&bpo=38787]: Module C state is now accessible from C-defined heap type methods (PEP 573 [https://peps.python.org/pep-0573/]). Patch by Marcel Plch and Petr Viktorin.

Python 3.9.0 alpha 6

Release date: 2020-04-27

Security

bpo-40121 [https://bugs.python.org/issue?@action=redirect&bpo=40121]: Fixes audit events raised on creating a new socket.

bpo-39073 [https://bugs.python.org/issue?@action=redirect&bpo=39073]: Disallow CR or LF in email.headerregistry.Address arguments to guard against header injection attacks.

bpo-39503 [https://bugs.python.org/issue?@action=redirect&bpo=39503]: CVE-2020-8492 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-8492]: The AbstractBasicAuthHandler class of the 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.

Core and Builtins

bpo-40313 [https://bugs.python.org/issue?@action=redirect&bpo=40313]: Improve the performance of bytes.hex().

bpo-40334 [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 -X oldparser or PYTHONOLDPARSER=1. In Python 3.10 we will remove the old parser completely, including the parser module (already deprecated) and anything that depends on it.

bpo-40267 [https://bugs.python.org/issue?@action=redirect&bpo=40267]: Fix the tokenizer to display the correct error message, when there is a SyntaxError on the last input character and no newline follows. It used to be unexpected EOF while parsing, while it should be invalid syntax.

bpo-39522 [https://bugs.python.org/issue?@action=redirect&bpo=39522]: Correctly unparse explicit u prefix for strings when postponed evaluation for annotations activated. Patch by Batuhan Taskaya.

bpo-40246 [https://bugs.python.org/issue?@action=redirect&bpo=40246]: Report a specialized error message, invalid string prefix, when the tokenizer encounters a string with an invalid prefix.

bpo-40082 [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.

bpo-37388 [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().

bpo-40077 [https://bugs.python.org/issue?@action=redirect&bpo=40077]: Fix possible refleaks in _json, memo of PyScannerObject should be traversed.

bpo-37207 [https://bugs.python.org/issue?@action=redirect&bpo=37207]: Speed up calls to dict() by using the PEP 590 [https://peps.python.org/pep-0590/] vectorcall calling convention.

bpo-40141 [https://bugs.python.org/issue?@action=redirect&bpo=40141]: Add column and line information to ast.keyword nodes. Patch by Pablo Galindo.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port resource to multiphase initialization (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port math to multiphase initialization (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _uuid module to multiphase initialization (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-40077 [https://bugs.python.org/issue?@action=redirect&bpo=40077]: Convert json module to use PyType_FromSpec().

bpo-40067 [https://bugs.python.org/issue?@action=redirect&bpo=40067]: Improve the error message for multiple star expressions in an assignment. Patch by Furkan Onder

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _functools module to multiphase initialization (PEP 489). Patch by Paulo Henrique Silva.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port operator module to multiphase initialization (PEP 489). Patch by Paulo Henrique Silva.

bpo-20526 [https://bugs.python.org/issue?@action=redirect&bpo=20526]: Fix PyThreadState_Clear(). PyThreadState.frame is a borrowed reference, not a strong reference: PyThreadState_Clear() must not call Py_CLEAR(tstate->frame).

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port time module to multiphase initialization (PEP 489 [https://peps.python.org/pep-0489/]). Patch by Paulo Henrique Silva.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _weakref extension module to multiphase initialization (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-40020 [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.

bpo-39939 [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 PEP 616 [https://peps.python.org/pep-0616/] for a full description. Patch by Dennis Sweeney.

bpo-39481 [https://bugs.python.org/issue?@action=redirect&bpo=39481]: Implement PEP 585. This supports list[int], tuple[str, ...] etc.

bpo-32894 [https://bugs.python.org/issue?@action=redirect&bpo=32894]: Support unparsing of infinity numbers in postponed annotations. Patch by Batuhan Taşkaya.

bpo-37207 [https://bugs.python.org/issue?@action=redirect&bpo=37207]: Speed up calls to list() by using the PEP 590 [https://peps.python.org/pep-0590/] vectorcall calling convention. Patch by Mark Shannon.

Library

bpo-40398 [https://bugs.python.org/issue?@action=redirect&bpo=40398]: typing.get_args() now always returns an empty tuple for special generic aliases.

bpo-40396 [https://bugs.python.org/issue?@action=redirect&bpo=40396]: Functions typing.get_origin(), typing.get_args() and typing.get_type_hints() support now generic aliases like list[int].

bpo-38061 [https://bugs.python.org/issue?@action=redirect&bpo=38061]: Optimize the subprocess module on FreeBSD using closefrom(). A single close(fd) syscall is cheap, but when sysconf(_SC_OPEN_MAX) is high, the loop calling 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): https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=242274

bpo-38061 [https://bugs.python.org/issue?@action=redirect&bpo=38061]: On FreeBSD, os.closerange(fd_low, fd_high) now calls closefrom(fd_low) if fd_high is greater than or equal to sysconf(_SC_OPEN_MAX).

Initial patch by Ed Maste (emaste), Conrad Meyer (cem), Kyle Evans (kevans) and Kubilay Kocak (koobs): https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=242274

bpo-40360 [https://bugs.python.org/issue?@action=redirect&bpo=40360]: The lib2to3 module is pending deprecation due to PEP 617 [https://peps.python.org/pep-0617/].

bpo-40138 [https://bugs.python.org/issue?@action=redirect&bpo=40138]: Fix the Windows implementation of os.waitpid() for exit code larger than INT_MAX >> 8. The exit status is now interpreted as an unsigned number.

bpo-39942 [https://bugs.python.org/issue?@action=redirect&bpo=39942]: Set "__main__" as the default module name when "__name__" is missing in typing.TypeVar. Patch by Weipeng Hong.

bpo-40275 [https://bugs.python.org/issue?@action=redirect&bpo=40275]: The logging package is now imported lazily in unittest only when the assertLogs() assertion is used.

bpo-40275 [https://bugs.python.org/issue?@action=redirect&bpo=40275]: The asyncio package is now imported lazily in unittest only when the IsolatedAsyncioTestCase class is used.

bpo-40330 [https://bugs.python.org/issue?@action=redirect&bpo=40330]: In ShareableList.__setitem__(), check the size of a new string item after encoding it to utf-8, not before.

bpo-40148 [https://bugs.python.org/issue?@action=redirect&bpo=40148]: Added pathlib.Path.with_stem() to create a new Path with the stem replaced.

bpo-40325 [https://bugs.python.org/issue?@action=redirect&bpo=40325]: Deprecated support for set objects in random.sample().

bpo-40257 [https://bugs.python.org/issue?@action=redirect&bpo=40257]: Improved help for the typing module. Docstrings are now shown for all special forms and special generic aliases (like Union and List). Using help() with generic alias like List[int] will show the help for the correspondent concrete type (list in this case).

bpo-40257 [https://bugs.python.org/issue?@action=redirect&bpo=40257]: 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 pydoc the documentation string is now shown not only for class, function, method etc, but for any object that has its own __doc__ attribute.

bpo-40287 [https://bugs.python.org/issue?@action=redirect&bpo=40287]: Fixed SpooledTemporaryFile.seek() to return the position.

bpo-40290 [https://bugs.python.org/issue?@action=redirect&bpo=40290]: Added zscore() to statistics.NormalDist().

bpo-40282 [https://bugs.python.org/issue?@action=redirect&bpo=40282]: Allow random.getrandbits(0) to succeed and to return 0.

bpo-40286 [https://bugs.python.org/issue?@action=redirect&bpo=40286]: Add random.randbytes() function and random.Random.randbytes() method to generate random bytes.

bpo-40277 [https://bugs.python.org/issue?@action=redirect&bpo=40277]: collections.namedtuple() now provides a human-readable repr for its field accessors.

bpo-40270 [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 json_object.

bpo-29255 [https://bugs.python.org/issue?@action=redirect&bpo=29255]: Wait in KqueueSelector.select when no fds are registered

bpo-40260 [https://bugs.python.org/issue?@action=redirect&bpo=40260]: Ensure modulefinder uses io.open_code() and respects coding comments.

bpo-40234 [https://bugs.python.org/issue?@action=redirect&bpo=40234]: Allow again to spawn daemon threads in subinterpreters (revert change which denied them).

bpo-39207 [https://bugs.python.org/issue?@action=redirect&bpo=39207]: Workers in 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.

bpo-40091 [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.

bpo-40149 [https://bugs.python.org/issue?@action=redirect&bpo=40149]: Implement traverse and clear slots in _abc._abc_data type.

bpo-40208 [https://bugs.python.org/issue?@action=redirect&bpo=40208]: Remove deprecated symtable.SymbolTable.has_exec().

bpo-40196 [https://bugs.python.org/issue?@action=redirect&bpo=40196]: Fix a bug in the symtable module that was causing incorrectly report global variables as local. Patch by Pablo Galindo.

bpo-40190 [https://bugs.python.org/issue?@action=redirect&bpo=40190]: Add support for _SC_AIX_REALMEM to posix.sysconf().

bpo-40182 [https://bugs.python.org/issue?@action=redirect&bpo=40182]: Removed the _field_types attribute of the typing.NamedTuple class.

bpo-36517 [https://bugs.python.org/issue?@action=redirect&bpo=36517]: Multiple inheritance with typing.NamedTuple now raises an error instead of silently ignoring other types.

bpo-40126 [https://bugs.python.org/issue?@action=redirect&bpo=40126]: Fixed reverting multiple patches in unittest.mock. Patcher's __exit__() is now never called if its __enter__() is failed. Returning true from __exit__() silences now the exception.

bpo-40094 [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."

bpo-40108 [https://bugs.python.org/issue?@action=redirect&bpo=40108]: Improve the error message when triying to import a module using runpy and incorrectly using the ".py" extension at the end of the module name. Patch by Pablo Galindo.

bpo-40094 [https://bugs.python.org/issue?@action=redirect&bpo=40094]: Add os.waitstatus_to_exitcode() function: convert a wait status to an exit code.

bpo-40089 [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.

bpo-40089 [https://bugs.python.org/issue?@action=redirect&bpo=40089]: Add a private _at_fork_reinit() method to _thread.Lock, _thread.RLock, threading.RLock and threading.Condition classes: reinitialize the lock at fork in the child process, reset the lock to the unlocked state. Rename also the private _reset_internal_locks() method of threading.Event to _at_fork_reinit().

bpo-25780 [https://bugs.python.org/issue?@action=redirect&bpo=25780]: Expose CAN_RAW_JOIN_FILTERS in the socket module.

bpo-39503 [https://bugs.python.org/issue?@action=redirect&bpo=39503]: AbstractBasicAuthHandler of urllib.request now parses all WWW-Authenticate HTTP headers and accepts multiple challenges per header: use the realm of the first Basic challenge.

bpo-39812 [https://bugs.python.org/issue?@action=redirect&bpo=39812]: Removed daemon threads from concurrent.futures by adding an internal 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.

bpo-40050 [https://bugs.python.org/issue?@action=redirect&bpo=40050]: Fix importlib._bootstrap_external: avoid creating a new winreg builtin module if it's already available in sys.modules, and remove redundant imports.

bpo-40014 [https://bugs.python.org/issue?@action=redirect&bpo=40014]: Fix os.getgrouplist(): if getgrouplist() function fails because the group list is too small, retry with a larger group list. On failure, the glibc implementation of getgrouplist() sets ngroups to the total number of groups. For other implementations, double the group list size.

bpo-40017 [https://bugs.python.org/issue?@action=redirect&bpo=40017]: Add time.CLOCK_TAI constant if the operating system support it.

bpo-40016 [https://bugs.python.org/issue?@action=redirect&bpo=40016]: In re docstring, clarify the relationship between inline and argument compile flags.

bpo-39953 [https://bugs.python.org/issue?@action=redirect&bpo=39953]: Update internal table of OpenSSL error codes in the ssl module.

bpo-36144 [https://bugs.python.org/issue?@action=redirect&bpo=36144]: Added PEP 584 [https://peps.python.org/pep-0584/] operators to weakref.WeakValueDictionary.

bpo-36144 [https://bugs.python.org/issue?@action=redirect&bpo=36144]: Added PEP 584 [https://peps.python.org/pep-0584/] operators to weakref.WeakKeyDictionary.

bpo-38891 [https://bugs.python.org/issue?@action=redirect&bpo=38891]: Fix linear runtime behaviour of the __getitem__ and __setitem__ methods in multiprocessing.shared_memory.ShareableList. This avoids quadratic performance when iterating a ShareableList. Patch by Thomas Krennwallner.

bpo-39682 [https://bugs.python.org/issue?@action=redirect&bpo=39682]: Remove undocumented support for closing a pathlib.Path object via its context manager. The context manager magic methods remain, but they are now a no-op, making Path objects immutable.

bpo-36144 [https://bugs.python.org/issue?@action=redirect&bpo=36144]: Added PEP 584 [https://peps.python.org/pep-0584/] operators (| and |=) to collections.ChainMap.

bpo-39011 [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.

bpo-38410 [https://bugs.python.org/issue?@action=redirect&bpo=38410]: Properly handle sys.audit() failures in sys.set_asyncgen_hooks().

bpo-36541 [https://bugs.python.org/issue?@action=redirect&bpo=36541]: lib2to3 now recognizes named assignment expressions (the walrus operator, :=)

bpo-35967 [https://bugs.python.org/issue?@action=redirect&bpo=35967]: In platform, delay the invocation of 'uname -p' until the processor attribute is requested.

bpo-35113 [https://bugs.python.org/issue?@action=redirect&bpo=35113]: 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.

bpo-33262 [https://bugs.python.org/issue?@action=redirect&bpo=33262]: Deprecate passing None as an argument for shlex.split()'s s parameter. Patch by Zackery Spytz.

bpo-31758 [https://bugs.python.org/issue?@action=redirect&bpo=31758]: Prevent crashes when using an uninitialized _elementtree.XMLParser object. Patch by Oren Milman.

Documentation

bpo-27635 [https://bugs.python.org/issue?@action=redirect&bpo=27635]: The pickle documentation incorrectly claimed that __new__ isn't called by default when unpickling.

bpo-39879 [https://bugs.python.org/issue?@action=redirect&bpo=39879]: Updated データモデル docs to include dict() insertion order preservation. Patch by Furkan Onder and Samy Lahfa.

bpo-38387 [https://bugs.python.org/issue?@action=redirect&bpo=38387]: Document PyDoc_STRVAR macro in the C-API reference.

bpo-13743 [https://bugs.python.org/issue?@action=redirect&bpo=13743]: Some methods within xml.dom.minidom.Element class are now better documented.

Tests

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Set expected default encoding in test_c_locale_coercion.py for VxWorks RTOS.

bpo-40162 [https://bugs.python.org/issue?@action=redirect&bpo=40162]: Update Travis CI configuration to OpenSSL 1.1.1f.

bpo-40146 [https://bugs.python.org/issue?@action=redirect&bpo=40146]: Update OpenSSL to 1.1.1f in Azure Pipelines.

bpo-40094 [https://bugs.python.org/issue?@action=redirect&bpo=40094]: Add test.support.wait_process() function.

bpo-40003 [https://bugs.python.org/issue?@action=redirect&bpo=40003]: test.bisect_cmd now copies Python command line options like -O or -W. Moreover, emit a warning if test.bisect_cmd is used with -w/--verbose2 option.

bpo-39380 [https://bugs.python.org/issue?@action=redirect&bpo=39380]: Add the encoding in ftplib.FTP and ftplib.FTP_TLS to the constructor as keyword-only and change the default from latin-1 to utf-8 to follow RFC 2640 [https://datatracker.ietf.org/doc/html/rfc2640.html].

bpo-39793 [https://bugs.python.org/issue?@action=redirect&bpo=39793]: Use the same domain when testing make_msgid. Patch by Batuhan Taskaya.

bpo-1812 [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.

Build

bpo-38360 [https://bugs.python.org/issue?@action=redirect&bpo=38360]: Support single-argument form of macOS -isysroot flag.

bpo-40158 [https://bugs.python.org/issue?@action=redirect&bpo=40158]: Fix CPython MSBuild Properties in NuGet Package (build/native/python.props)

bpo-38527 [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.

Windows

bpo-40164 [https://bugs.python.org/issue?@action=redirect&bpo=40164]: Updates Windows to OpenSSL 1.1.1f

bpo-8901 [https://bugs.python.org/issue?@action=redirect&bpo=8901]: Ignore the Windows registry when the -E option is used.

macOS

bpo-38329 [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.

bpo-40164 [https://bugs.python.org/issue?@action=redirect&bpo=40164]: Update macOS installer builds to use OpenSSL 1.1.1g.

IDLE

bpo-38439 [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.

bpo-38689 [https://bugs.python.org/issue?@action=redirect&bpo=38689]: IDLE will no longer freeze when inspect.signature fails when fetching a calltip.

Tools/Demos

bpo-40385 [https://bugs.python.org/issue?@action=redirect&bpo=40385]: Removed the checkpyc.py tool. Please see compileall without force mode as a potential alternative.

bpo-40179 [https://bugs.python.org/issue?@action=redirect&bpo=40179]: Fixed translation of #elif in Argument Clinic.

bpo-40094 [https://bugs.python.org/issue?@action=redirect&bpo=40094]: Fix which.py script exit code: it now uses os.waitstatus_to_exitcode() to convert os.system() exit status into an exit code.

C API

bpo-40241 [https://bugs.python.org/issue?@action=redirect&bpo=40241]: Move the PyGC_Head structure to the internal C API.

bpo-40170 [https://bugs.python.org/issue?@action=redirect&bpo=40170]: Convert PyObject_IS_GC() macro to a function to hide implementation details.

bpo-40241 [https://bugs.python.org/issue?@action=redirect&bpo=40241]: Add the functions PyObject_GC_IsTracked() and 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.

bpo-40170 [https://bugs.python.org/issue?@action=redirect&bpo=40170]: The PyObject_NEW() macro becomes an alias to the PyObject_New() macro, and the PyObject_NEW_VAR() macro becomes an alias to the PyObject_NewVar() macro, to hide implementation details. They no longer access directly the PyTypeObject.tp_basicsize member.

bpo-40170 [https://bugs.python.org/issue?@action=redirect&bpo=40170]: PyType_HasFeature() now always calls PyType_GetFlags() to hide implementation details. Previously, it accessed directly the PyTypeObject.tp_flags member when the limited C API was not used.

bpo-40170 [https://bugs.python.org/issue?@action=redirect&bpo=40170]: Convert the PyObject_GET_WEAKREFS_LISTPTR() macro to a function to hide implementation details: the macro accessed directly to the PyTypeObject.tp_weaklistoffset member.

bpo-40170 [https://bugs.python.org/issue?@action=redirect&bpo=40170]: Convert PyObject_CheckBuffer() macro to a function to hide implementation details: the macro accessed directly the PyTypeObject.tp_as_buffer member.

bpo-40170 [https://bugs.python.org/issue?@action=redirect&bpo=40170]: Always declare PyIndex_Check() as an opaque function to hide implementation details: remove PyIndex_Check() macro. The macro accessed directly the PyTypeObject.tp_as_number member.

bpo-39947 [https://bugs.python.org/issue?@action=redirect&bpo=39947]: Add PyThreadState_GetID() function: get the unique identifier of a Python thread state.

Python 3.9.0 alpha 5

Release date: 2020-03-23

Security

bpo-38576 [https://bugs.python.org/issue?@action=redirect&bpo=38576]: Disallow control characters in hostnames in http.client, addressing CVE-2019-18348 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-18348]. Such potentially malicious header injection URLs now cause a InvalidURL to be raised.

Core and Builtins

bpo-40010 [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 (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.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _weakref extension module to multiphase initialization (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _collections module to multiphase initialization (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-40010 [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.

bpo-39984 [https://bugs.python.org/issue?@action=redirect&bpo=39984]: If 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.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _heapq module to multiphase initialization.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port itertools module to multiphase initialization (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-37207 [https://bugs.python.org/issue?@action=redirect&bpo=37207]: Speed up calls to frozenset() by using the PEP 590 [https://peps.python.org/pep-0590/] vectorcall calling convention. Patch by Donghee Na.

bpo-39984 [https://bugs.python.org/issue?@action=redirect&bpo=39984]: subinterpreters: Move _PyRuntimeState.ceval.tracing_possible to PyInterpreterState.ceval.tracing_possible: each interpreter now has its own variable.

bpo-37207 [https://bugs.python.org/issue?@action=redirect&bpo=37207]: Speed up calls to set() by using the PEP 590 [https://peps.python.org/pep-0590/] vectorcall calling convention. Patch by Donghee Na.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _statistics module to multiphase initialization (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-39968 [https://bugs.python.org/issue?@action=redirect&bpo=39968]: Use inline function to replace extension modules' get_module_state macros.

bpo-39965 [https://bugs.python.org/issue?@action=redirect&bpo=39965]: Correctly raise SyntaxError if await is used inside non-async functions and PyCF_ALLOW_TOP_LEVEL_AWAIT is set (like in the asyncio REPL). Patch by Pablo Galindo.

bpo-39562 [https://bugs.python.org/issue?@action=redirect&bpo=39562]: Allow executing asynchronous comprehensions on the top level when the PyCF_ALLOW_TOP_LEVEL_AWAIT flag is given. Patch by Batuhan Taskaya.

bpo-37207 [https://bugs.python.org/issue?@action=redirect&bpo=37207]: Speed up calls to tuple() by using the PEP 590 [https://peps.python.org/pep-0590/] vectorcall calling convention. Patch by Donghee Na.

bpo-38373 [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.

bpo-39926 [https://bugs.python.org/issue?@action=redirect&bpo=39926]: Update Unicode database to Unicode version 13.0.0.

bpo-19466 [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.

bpo-38894 [https://bugs.python.org/issue?@action=redirect&bpo=38894]: Fix a bug that was causing incomplete results when calling 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.

bpo-39877 [https://bugs.python.org/issue?@action=redirect&bpo=39877]: Fix PyEval_RestoreThread() random crash at exit with daemon threads. It now accesses the _PyRuntime variable directly instead of using tstate->interp->runtime, since tstate can be a dangling pointer after Py_Finalize() has been called. Moreover, the daemon thread now exits before trying to take the GIL.

bpo-39871 [https://bugs.python.org/issue?@action=redirect&bpo=39871]: Fix a possible SystemError in math.{atan2,copysign,remainder}() when the first argument cannot be converted to a float. Patch by Zackery Spytz.

bpo-39776 [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).

bpo-39778 [https://bugs.python.org/issue?@action=redirect&bpo=39778]: Fixed a crash due to incorrect handling of weak references in collections.OrderedDict classes. Patch by Pablo Galindo.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port audioop extension module to multiphase initialization (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-39702 [https://bugs.python.org/issue?@action=redirect&bpo=39702]: Relax decorator grammar restrictions to allow any valid expression (PEP 614 [https://peps.python.org/pep-0614/]).

bpo-38091 [https://bugs.python.org/issue?@action=redirect&bpo=38091]: Tweak import deadlock detection code to not deadlock itself.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _locale extension module to multiphase initialization (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-39087 [https://bugs.python.org/issue?@action=redirect&bpo=39087]: Optimize PyUnicode_AsUTF8() and PyUnicode_AsUTF8AndSize() slightly when they need to create internal UTF-8 cache.

bpo-39520 [https://bugs.python.org/issue?@action=redirect&bpo=39520]: Fix unparsing of ext slices with no items (foo[:,]). Patch by Batuhan Taskaya.

bpo-39220 [https://bugs.python.org/issue?@action=redirect&bpo=39220]: Do not optimize annotations if 'from __future__ import annotations' is used. Patch by Pablo Galindo.

bpo-35712 [https://bugs.python.org/issue?@action=redirect&bpo=35712]: Using NotImplemented in a boolean context has been deprecated. Patch contributed by Josh Rosenberg.

bpo-22490 [https://bugs.python.org/issue?@action=redirect&bpo=22490]: Don't leak environment variable __PYVENV_LAUNCHER__ into the interpreter session on macOS.

Library

bpo-39830 [https://bugs.python.org/issue?@action=redirect&bpo=39830]: Add zipfile.Path to __all__ in the zipfile module.

bpo-40000 [https://bugs.python.org/issue?@action=redirect&bpo=40000]: Improved error messages for validation of ast.Constant nodes. Patch by Batuhan Taskaya.

bpo-39999 [https://bugs.python.org/issue?@action=redirect&bpo=39999]: __module__ of the AST node classes is now set to "ast" instead of "_ast". Added docstrings for dummy AST node classes and deprecated attributes.

bpo-39991 [https://bugs.python.org/issue?@action=redirect&bpo=39991]: uuid.getnode() now skips IPv6 addresses with the same string length than a MAC address (17 characters): only use MAC addresses.

bpo-39988 [https://bugs.python.org/issue?@action=redirect&bpo=39988]: Deprecated ast.AugLoad and ast.AugStore node classes because they are no longer used.

bpo-39656 [https://bugs.python.org/issue?@action=redirect&bpo=39656]: Ensure bin/python3.# is always present in virtual environments on POSIX platforms - by Anthony Sottile.

bpo-39969 [https://bugs.python.org/issue?@action=redirect&bpo=39969]: Deprecated ast.Param node class because it's no longer used. Patch by Batuhan Taskaya.

bpo-39360 [https://bugs.python.org/issue?@action=redirect&bpo=39360]: Ensure all workers exit when finalizing a 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 multiprocessing.Pool.terminate. Patch by Batuhan Taskaya and Pablo Galindo.

bpo-35370 [https://bugs.python.org/issue?@action=redirect&bpo=35370]: sys.settrace(), sys.setprofile() and _lsprof.Profiler.enable() now properly report PySys_Audit() error if "sys.setprofile" or "sys.settrace" audit event is denied.

bpo-39936 [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.

bpo-36144 [https://bugs.python.org/issue?@action=redirect&bpo=36144]: collections.OrderedDict now implements | and |= (PEP 584 [https://peps.python.org/pep-0584/]).

bpo-39652 [https://bugs.python.org/issue?@action=redirect&bpo=39652]: The column name found in sqlite3.Cursor.description is now truncated on the first '[' only if the PARSE_COLNAMES option is set.

bpo-39915 [https://bugs.python.org/issue?@action=redirect&bpo=39915]: Ensure unittest.mock.AsyncMock.await_args_list has call objects in the order of awaited arguments instead of using unittest.mock.Mock.call_args which has the last value of the call. Patch by Karthikeyan Singaravelan.

bpo-36144 [https://bugs.python.org/issue?@action=redirect&bpo=36144]: Updated os.environ and os.environb to support PEP 584 [https://peps.python.org/pep-0584/]'s merge (|) and update (|=) operators.

bpo-38662 [https://bugs.python.org/issue?@action=redirect&bpo=38662]: The ensurepip module now invokes pip via the runpy module. Hence it is no longer tightly coupled with the internal API of the bundled pip version, allowing easier updates to a newer pip version both internally and for distributors.

bpo-38075 [https://bugs.python.org/issue?@action=redirect&bpo=38075]: Fix the random.Random.seed() method when a bool is passed as the seed.

bpo-39916 [https://bugs.python.org/issue?@action=redirect&bpo=39916]: More reliable use of os.scandir() in Path.glob(). It no longer emits a ResourceWarning when interrupted.

bpo-39850 [https://bugs.python.org/issue?@action=redirect&bpo=39850]: multiprocessing now supports abstract socket addresses (if abstract sockets are supported in the running platform). When creating arbitrary addresses (like when default-constructing 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.

bpo-36287 [https://bugs.python.org/issue?@action=redirect&bpo=36287]: 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. Constant.kind is set to None).

bpo-39889 [https://bugs.python.org/issue?@action=redirect&bpo=39889]: Fixed ast.unparse() for extended slices containing a single element (e.g. a[i:j,]). Remove redundant tuples when index with a tuple (e.g. a[i, j]).

bpo-39828 [https://bugs.python.org/issue?@action=redirect&bpo=39828]: Fix json.tool to catch BrokenPipeError. Patch by Donghee Na.

bpo-13487 [https://bugs.python.org/issue?@action=redirect&bpo=13487]: Avoid a possible "RuntimeError: dictionary changed size during iteration" from inspect.getmodule() when it tried to loop through sys.modules.

bpo-39674 [https://bugs.python.org/issue?@action=redirect&bpo=39674]: Revert "bpo-37330 [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.

bpo-28577 [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.

bpo-39826 [https://bugs.python.org/issue?@action=redirect&bpo=39826]: Add getConnection method to logging HTTPHandler to enable custom connections.

bpo-39763 [https://bugs.python.org/issue?@action=redirect&bpo=39763]: Reimplement distutils.spawn.spawn function with the subprocess module.

bpo-39794 [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.

bpo-36144 [https://bugs.python.org/issue?@action=redirect&bpo=36144]: collections.defaultdict now implements | (PEP 584 [https://peps.python.org/pep-0584/]).

bpo-39517 [https://bugs.python.org/issue?@action=redirect&bpo=39517]: Fix runpy.run_path() when using pathlike objects

bpo-39775 [https://bugs.python.org/issue?@action=redirect&bpo=39775]: Change inspect.Signature.parameters back to collections.OrderedDict. This was changed to dict in Python 3.9.0a4.

bpo-39678 [https://bugs.python.org/issue?@action=redirect&bpo=39678]: Refactor queue_manager in concurrent.futures.ProcessPoolExecutor to make it easier to maintain.

bpo-39764 [https://bugs.python.org/issue?@action=redirect&bpo=39764]: Fix AttributeError when calling get_stack on a PyAsyncGenObject Task

bpo-39769 [https://bugs.python.org/issue?@action=redirect&bpo=39769]: The compileall.compile_dir() function's ddir parameter and the compileall command line flag -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.

bpo-36144 [https://bugs.python.org/issue?@action=redirect&bpo=36144]: types.MappingProxyType objects now support the merge (|) operator from PEP 584 [https://peps.python.org/pep-0584/].

bpo-38691 [https://bugs.python.org/issue?@action=redirect&bpo=38691]: The importlib module now ignores the PYTHONCASEOK environment variable when the -E or -I command line options are being used.

bpo-39719 [https://bugs.python.org/issue?@action=redirect&bpo=39719]: Remove tempfile.SpooledTemporaryFile.softspace() as files no longer have the softspace attribute in Python 3. Patch by Shantanu.

bpo-39667 [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.

bpo-39638 [https://bugs.python.org/issue?@action=redirect&bpo=39638]: Keep ASDL signatures in the docstrings for AST nodes. Patch by Batuhan Taskaya

bpo-39639 [https://bugs.python.org/issue?@action=redirect&bpo=39639]: Deprecated ast.Suite node class because it's no longer used. Patch by Batuhan Taskaya.

bpo-39609 [https://bugs.python.org/issue?@action=redirect&bpo=39609]: Add thread_name_prefix to default asyncio executor

bpo-39548 [https://bugs.python.org/issue?@action=redirect&bpo=39548]: Fix handling of header in urllib.request.AbstractDigestAuthHandler when the optional qop parameter is not present.

bpo-39509 [https://bugs.python.org/issue?@action=redirect&bpo=39509]: HTTP status codes 103 EARLY_HINTS and 425 TOO_EARLY are added to http.HTTPStatus. Patch by Donghee Na.

bpo-39507 [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.

bpo-39495 [https://bugs.python.org/issue?@action=redirect&bpo=39495]: Remove default value from attrs parameter of xml.etree.ElementTree.TreeBuilder.start() for consistency between Python and C implementations.

bpo-38971 [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.

bpo-38641 [https://bugs.python.org/issue?@action=redirect&bpo=38641]: Added starred expressions support to return and yield statements for lib2to3. Patch by Vlad Emelianov.

bpo-37534 [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: https://www.w3.org/TR/xml/#sec-prolog-dtd).

bpo-34788 [https://bugs.python.org/issue?@action=redirect&bpo=34788]: Add support for scoped IPv6 addresses to ipaddress. Patch by Oleksandr Pavliuk.

bpo-34822 [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. ast classes Index and ExtSlice are considered deprecated and will be removed in future Python versions. In the meantime, Index(value) now returns a value itself, ExtSlice(slices) returns Tuple(slices, Load()).

Documentation

bpo-39868 [https://bugs.python.org/issue?@action=redirect&bpo=39868]: Updated the Language Reference for PEP 572 [https://peps.python.org/pep-0572/].

bpo-13790 [https://bugs.python.org/issue?@action=redirect&bpo=13790]: Change 'string' to 'specification' in format doc.

bpo-17422 [https://bugs.python.org/issue?@action=redirect&bpo=17422]: The language reference no longer restricts default class namespaces to dicts only.

bpo-39530 [https://bugs.python.org/issue?@action=redirect&bpo=39530]: Fix misleading documentation about mixed-type numeric comparisons.

bpo-39718 [https://bugs.python.org/issue?@action=redirect&bpo=39718]: Update token documentation to reflect additions in Python 3.8

bpo-39677 [https://bugs.python.org/issue?@action=redirect&bpo=39677]: Changed operand name of MAKE_FUNCTION from argc to flags for module dis

Tests

bpo-40019 [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.

bpo-27807 [https://bugs.python.org/issue?@action=redirect&bpo=27807]: test_site.test_startup_imports() is now skipped if a path of sys.path contains a .pth file.

bpo-26067 [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.

bpo-39855 [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.

Build

bpo-39761 [https://bugs.python.org/issue?@action=redirect&bpo=39761]: Fix build with DTrace but without additional DFLAGS.

bpo-39763 [https://bugs.python.org/issue?@action=redirect&bpo=39763]: setup.py now uses a basic implementation of the subprocess module if the subprocess module is not available: before required C extension modules are built.

bpo-1294959 [https://bugs.python.org/issue?@action=redirect&bpo=1294959]: Add --with-platlibdir option to the configure script: name of the platform-specific library directory, stored in the new 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 "lib" on most platforms. On Fedora and SuSE, it is equal to "lib64" on 64-bit platforms. Patch by Jan Matějek, Matěj Cepl, Charalampos Stratakis and Victor Stinner.

Windows

bpo-39930 [https://bugs.python.org/issue?@action=redirect&bpo=39930]: Ensures the required vcruntime140.dll is included in install packages.

bpo-39847 [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 threading) around 49-day uptime.

bpo-38597 [https://bugs.python.org/issue?@action=redirect&bpo=38597]: distutils will no longer statically link 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.

bpo-38380 [https://bugs.python.org/issue?@action=redirect&bpo=38380]: Update Windows builds to use SQLite 3.31.1

bpo-39789 [https://bugs.python.org/issue?@action=redirect&bpo=39789]: Update Windows release build machines to Visual Studio 2019 (MSVC 14.2).

bpo-34803 [https://bugs.python.org/issue?@action=redirect&bpo=34803]: Package for nuget.org now includes repository reference and bundled icon image.

macOS

bpo-38380 [https://bugs.python.org/issue?@action=redirect&bpo=38380]: Update macOS builds to use SQLite 3.31.1

IDLE

bpo-27115 [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.

bpo-39885 [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.

bpo-39852 [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.

bpo-39781 [https://bugs.python.org/issue?@action=redirect&bpo=39781]: Selecting code context lines no longer causes a jump.

Tools/Demos

bpo-36184 [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.

bpo-38080 [https://bugs.python.org/issue?@action=redirect&bpo=38080]: Added support to fix getproxies in the lib2to3.fixes.fix_urllib module. Patch by José Roberto Meza Cabrera.

C API

bpo-40024 [https://bugs.python.org/issue?@action=redirect&bpo=40024]: Add PyModule_AddType() helper function: add a type to a module. Patch by Donghee Na.

bpo-39946 [https://bugs.python.org/issue?@action=redirect&bpo=39946]: Remove _PyRuntime.getframe hook and remove _PyThreadState_GetFrame macro which was an alias to _PyRuntime.getframe. They were only exposed by the internal C API. Remove also PyThreadFrameGetter type.

bpo-39947 [https://bugs.python.org/issue?@action=redirect&bpo=39947]: Add PyThreadState_GetFrame() function: get the current frame of a Python thread state.

bpo-37207 [https://bugs.python.org/issue?@action=redirect&bpo=37207]: Add _PyArg_NoKwnames helper function. Patch by Donghee Na.

bpo-39947 [https://bugs.python.org/issue?@action=redirect&bpo=39947]: Add PyThreadState_GetInterpreter(): get the interpreter of a Python thread state.

bpo-39947 [https://bugs.python.org/issue?@action=redirect&bpo=39947]: Add PyInterpreterState_Get() function to the limited C API.

bpo-35370 [https://bugs.python.org/issue?@action=redirect&bpo=35370]: If PySys_Audit() fails in PyEval_SetProfile() or PyEval_SetTrace(), log the error as an unraisable exception.

bpo-39947 [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.

bpo-39947 [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.

bpo-39884 [https://bugs.python.org/issue?@action=redirect&bpo=39884]: PyDescr_NewMethod() and PyCFunction_NewEx() now include the method name in the SystemError "bad call flags" error message to ease debug.

bpo-39877 [https://bugs.python.org/issue?@action=redirect&bpo=39877]: Deprecated PyEval_InitThreads() and PyEval_ThreadsInitialized(). Calling PyEval_InitThreads() now does nothing.

bpo-38249 [https://bugs.python.org/issue?@action=redirect&bpo=38249]: Py_UNREACHABLE is now implemented with __builtin_unreachable() and analogs in release mode.

bpo-38643 [https://bugs.python.org/issue?@action=redirect&bpo=38643]: PyNumber_ToBase() now raises a SystemError instead of crashing when called with invalid base.

bpo-39882 [https://bugs.python.org/issue?@action=redirect&bpo=39882]: The Py_FatalError() function is replaced with a macro which logs automatically the name of the current function, unless the Py_LIMITED_API macro is defined.

bpo-39824 [https://bugs.python.org/issue?@action=redirect&bpo=39824]: Extension modules: m_traverse, m_clear and m_free functions of 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 (Py_mod_exec function). More precisely, these functions are not called if m_size is greater than 0 and the module state (as returned by PyModule_GetState()) is NULL.

Extension modules without module state (m_size <= 0) are not affected.

bpo-38913 [https://bugs.python.org/issue?@action=redirect&bpo=38913]: Fixed segfault in Py_BuildValue() called with a format containing "#" and undefined PY_SSIZE_T_CLEAN whwn an exception is set.

bpo-38500 [https://bugs.python.org/issue?@action=redirect&bpo=38500]: Add a private API to get and set the frame evaluation function: add _PyInterpreterState_GetEvalFrameFunc() and _PyInterpreterState_SetEvalFrameFunc() C functions. The _PyFrameEvalFunction function type now takes a tstate parameter.

Python 3.9.0 alpha 4

Release date: 2020-02-25

Security

bpo-39184 [https://bugs.python.org/issue?@action=redirect&bpo=39184]: Add audit events to functions in fcntl, msvcrt, os, resource, shutil, signal and syslog.

bpo-39401 [https://bugs.python.org/issue?@action=redirect&bpo=39401]: Avoid unsafe DLL load at startup on Windows 7 and earlier.

bpo-39184 [https://bugs.python.org/issue?@action=redirect&bpo=39184]: Add audit events to command execution functions in os and pty modules.

Core and Builtins

bpo-39382 [https://bugs.python.org/issue?@action=redirect&bpo=39382]: Fix a use-after-free in the single inheritance path of issubclass(), when the __bases__ of an object has a single reference, and so does its first item. Patch by Yonatan Goldschmidt.

bpo-39573 [https://bugs.python.org/issue?@action=redirect&bpo=39573]: Update clinic tool to use Py_IS_TYPE(). Patch by Donghee Na.

bpo-39619 [https://bugs.python.org/issue?@action=redirect&bpo=39619]: Enable use of os.chroot() on HP-UX systems.

bpo-39573 [https://bugs.python.org/issue?@action=redirect&bpo=39573]: Add Py_IS_TYPE() static inline function to check whether the object o type is type.

bpo-39606 [https://bugs.python.org/issue?@action=redirect&bpo=39606]: Fix regression caused by fix for bpo-39386 [https://bugs.python.org/issue?@action=redirect&bpo=39386], that prevented calling aclose on an async generator that had already been closed or exhausted.

bpo-39579 [https://bugs.python.org/issue?@action=redirect&bpo=39579]: Change the ending column offset of Attribute nodes constructed in ast_for_dotted_name to point at the end of the current node and not at the end of the last NAME node.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _crypt extension module to multiphase initialization (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _contextvars extension module to multiphase initialization (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-39510 [https://bugs.python.org/issue?@action=redirect&bpo=39510]: Fix segfault in readinto() method on closed BufferedReader.

bpo-39502 [https://bugs.python.org/issue?@action=redirect&bpo=39502]: Fix time.localtime() on 64-bit AIX to support years before 1902 and after 2038. Patch by M Felt.

bpo-39492 [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.

bpo-39453 [https://bugs.python.org/issue?@action=redirect&bpo=39453]: Fixed a possible crash in list.__contains__() when a list is changed during comparing items. Patch by Donghee Na.

bpo-39434 [https://bugs.python.org/issue?@action=redirect&bpo=39434]: floor division of float operation now has a better performance. Also the message of ZeroDivisionError for this operation is updated. Patch by Donghee Na.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _codecs extension module to multiphase initialization (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _bz2 extension module to multiphase initialization (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _abc extension module to multiphase initialization (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-39320 [https://bugs.python.org/issue?@action=redirect&bpo=39320]: Replace two complex bytecodes for building dicts with two simpler ones. The new bytecodes DICT_MERGE and DICT_UPDATE have been added The old bytecodes BUILD_MAP_UNPACK and BUILD_MAP_UNPACK_WITH_CALL have been removed.

bpo-39219 [https://bugs.python.org/issue?@action=redirect&bpo=39219]: Syntax errors raised in the tokenizer now always set correct "text" and "offset" attributes.

bpo-36051 [https://bugs.python.org/issue?@action=redirect&bpo=36051]: Drop the GIL during large bytes.join operations. Patch by Bruce Merry.

bpo-38960 [https://bugs.python.org/issue?@action=redirect&bpo=38960]: Fix DTrace build issues on FreeBSD. Patch by David Carlier.

bpo-37207 [https://bugs.python.org/issue?@action=redirect&bpo=37207]: Speed up calls to range() by about 30%, by using the PEP 590 vectorcall calling convention. Patch by Mark Shannon.

bpo-36144 [https://bugs.python.org/issue?@action=redirect&bpo=36144]: dict (and collections.UserDict) objects now support PEP 584's merge (|) and update (|=) operators. Patch by Brandt Bucher.

bpo-32856 [https://bugs.python.org/issue?@action=redirect&bpo=32856]: Optimized the idiom for assignment a temporary variable in comprehensions. Now for y in [expr] in comprehensions is as fast as a simple assignment y = expr.

Library

bpo-30566 [https://bugs.python.org/issue?@action=redirect&bpo=30566]: Fix IndexError when trying to decode an invalid string with punycode codec.

bpo-39649 [https://bugs.python.org/issue?@action=redirect&bpo=39649]: Remove obsolete check for __args__ in bdb.Bdb.format_stack_entry.

bpo-39648 [https://bugs.python.org/issue?@action=redirect&bpo=39648]: Expanded math.gcd() and math.lcm() to handle multiple arguments.

bpo-39681 [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.

bpo-35950 [https://bugs.python.org/issue?@action=redirect&bpo=35950]: Raise io.UnsupportedOperation in io.BufferedReader.truncate() when it is called on a read-only io.BufferedReader instance.

bpo-39479 [https://bugs.python.org/issue?@action=redirect&bpo=39479]: Add math.lcm() function: least common multiple.

bpo-39674 [https://bugs.python.org/issue?@action=redirect&bpo=39674]: Revert "Do not expose abstract collection classes in the collections module" change (bpo-25988 [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.

bpo-39104 [https://bugs.python.org/issue?@action=redirect&bpo=39104]: Fix hanging ProcessPoolExcutor on shutdown(wait=False) when a task has failed pickling.

bpo-39627 [https://bugs.python.org/issue?@action=redirect&bpo=39627]: Fixed TypedDict totality check for inherited keys.

bpo-39474 [https://bugs.python.org/issue?@action=redirect&bpo=39474]: Fixed starting position of AST for expressions like (a)(b), (a)[b] and (a).b.

bpo-21016 [https://bugs.python.org/issue?@action=redirect&bpo=21016]: The pydoc and trace modules now use the sysconfig module to get the path to the Python standard library, to support uncommon installation path like /usr/lib64/python3.9/ on Fedora. Patch by Jan Matějek.

bpo-39590 [https://bugs.python.org/issue?@action=redirect&bpo=39590]: Collections.deque now holds strong references during deque.__contains__ and deque.count, fixing crashes.

bpo-39586 [https://bugs.python.org/issue?@action=redirect&bpo=39586]: The distutils bdist_msi command is deprecated in Python 3.9, use bdist_wheel (wheel packages) instead.

bpo-39595 [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 [https://importlib-metadata.readthedocs.io/en/latest/history.html#v1-5-0].

bpo-39350 [https://bugs.python.org/issue?@action=redirect&bpo=39350]: Fix regression in fractions.Fraction if the numerator and/or the denominator is an int subclass. The math.gcd() function is now used to normalize the numerator and denominator. math.gcd() always return a int type. Previously, the GCD type depended on numerator and denominator.

bpo-39567 [https://bugs.python.org/issue?@action=redirect&bpo=39567]: Added audit for os.walk(), os.fwalk(), pathlib.Path.glob() and pathlib.Path.rglob().

bpo-39559 [https://bugs.python.org/issue?@action=redirect&bpo=39559]: Remove unused, undocumented argument getters from uuid.getnode()

bpo-38149 [https://bugs.python.org/issue?@action=redirect&bpo=38149]: sys.audit() is now called only once per call of glob.glob() and glob.iglob().

bpo-39546 [https://bugs.python.org/issue?@action=redirect&bpo=39546]: Fix a regression in ArgumentParser where allow_abbrev=False was ignored for long options that used a prefix character other than "-".

bpo-39450 [https://bugs.python.org/issue?@action=redirect&bpo=39450]: Striped whitespace from docstring before returning it from unittest.case.shortDescription().

bpo-12915 [https://bugs.python.org/issue?@action=redirect&bpo=12915]: A new function resolve_name has been added to the pkgutil module. This resolves a string of the form 'a.b.c.d' or 'a.b:c.d' to an object. In the example, a.b is a package/module and c.d is an object within that package/module reached via recursive attribute access.

bpo-39353 [https://bugs.python.org/issue?@action=redirect&bpo=39353]: The binascii.crc_hqx() function is no longer deprecated.

bpo-39493 [https://bugs.python.org/issue?@action=redirect&bpo=39493]: Mark typing.IO.closed as a property

bpo-39491 [https://bugs.python.org/issue?@action=redirect&bpo=39491]: Add typing.Annotated and include_extras parameter to typing.get_type_hints() as part of PEP 593 [https://peps.python.org/pep-0593/]. Patch by Till Varoquaux, documentation by Till Varoquaux and Konstantin Kashin.

bpo-39485 [https://bugs.python.org/issue?@action=redirect&bpo=39485]: Fix a bug in unittest.mock.create_autospec() that would complain about the wrong number of arguments for custom descriptors defined in an extension module returning functions.

bpo-38932 [https://bugs.python.org/issue?@action=redirect&bpo=38932]: Mock fully resets child objects on reset_mock(). Patch by Vegard Stikbakke

bpo-39082 [https://bugs.python.org/issue?@action=redirect&bpo=39082]: Allow AsyncMock to correctly patch static/class methods

bpo-39432 [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.

bpo-18819 [https://bugs.python.org/issue?@action=redirect&bpo=18819]: Omit devmajor and devminor fields for non-device files in tarfile archives, enabling bit-for-bit compatibility with GNU tar(1).

bpo-39349 [https://bugs.python.org/issue?@action=redirect&bpo=39349]: Added a new cancel_futures parameter to 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.

bpo-39274 [https://bugs.python.org/issue?@action=redirect&bpo=39274]: bool(fraction.Fraction) now returns a boolean even if (numerator != 0) does not return a boolean (ex: numpy number).

bpo-34793 [https://bugs.python.org/issue?@action=redirect&bpo=34793]: Remove support for with (await asyncio.lock): and with (yield from asyncio.lock):. The same is correct for asyncio.Condition and asyncio.Semaphore.

bpo-25597 [https://bugs.python.org/issue?@action=redirect&bpo=25597]: Ensure, if wraps is supplied to 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.

bpo-36350 [https://bugs.python.org/issue?@action=redirect&bpo=36350]: inspect.Signature.parameters and inspect.BoundArguments.arguments are now dicts instead of OrderedDicts. Patch contributed by Rémi Lapeyre.

bpo-35727 [https://bugs.python.org/issue?@action=redirect&bpo=35727]: Fix sys.exit() and sys.exit(None) exit code propagation when used in multiprocessing.Process.

bpo-32173 [https://bugs.python.org/issue?@action=redirect&bpo=32173]: * Add lazycache function to __all__. * Use dict.clear to clear the cache. * Refactoring getline function and checkcache function.

Documentation

bpo-17422 [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.

bpo-39572 [https://bugs.python.org/issue?@action=redirect&bpo=39572]: Updated documentation of total flag of TypedDict.

bpo-39654 [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.

bpo-39153 [https://bugs.python.org/issue?@action=redirect&bpo=39153]: Clarify refcounting semantics for the following functions: - PyObject_SetItem - PyMapping_SetItemString - PyDict_SetItem - PyDict_SetItemString

bpo-39392 [https://bugs.python.org/issue?@action=redirect&bpo=39392]: Explain that when filling with turtle, overlap regions may be left unfilled.

bpo-39369 [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.

bpo-9056 [https://bugs.python.org/issue?@action=redirect&bpo=9056]: Include subsection in TOC for PDF version of docs.

Tests

bpo-38325 [https://bugs.python.org/issue?@action=redirect&bpo=38325]: Skip tests on non-BMP characters of test_winconsoleio.

bpo-39502 [https://bugs.python.org/issue?@action=redirect&bpo=39502]: Skip test_zipfile.test_add_file_after_2107() if time.localtime() fails with OverflowError. It is the case on AIX 6.1 for example.

Build

bpo-39489 [https://bugs.python.org/issue?@action=redirect&bpo=39489]: Remove COUNT_ALLOCS special build.

Windows

bpo-39553 [https://bugs.python.org/issue?@action=redirect&bpo=39553]: Delete unused code related to SxS manifests.

bpo-39439 [https://bugs.python.org/issue?@action=redirect&bpo=39439]: Honor the Python path when a virtualenv is active on Windows.

bpo-39393 [https://bugs.python.org/issue?@action=redirect&bpo=39393]: Improve the error message when attempting to load a DLL with unresolved dependencies.

bpo-38883 [https://bugs.python.org/issue?@action=redirect&bpo=38883]: home() and expanduser() on Windows now prefer USERPROFILE and no longer use HOME, which is not normally set for regular user accounts. This makes them again behave like os.path.expanduser(), which was changed to ignore HOME in 3.8, see bpo-36264 [https://bugs.python.org/issue?@action=redirect&bpo=36264].

bpo-39185 [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)

IDLE

bpo-39663 [https://bugs.python.org/issue?@action=redirect&bpo=39663]: Add tests for pyparse find_good_parse_start().

bpo-39600 [https://bugs.python.org/issue?@action=redirect&bpo=39600]: In the font configuration window, remove duplicated font names.

bpo-30780 [https://bugs.python.org/issue?@action=redirect&bpo=30780]: Add remaining configdialog tests for buttons and highlights and keys tabs.

bpo-39388 [https://bugs.python.org/issue?@action=redirect&bpo=39388]: IDLE Settings Cancel button now cancels pending changes

bpo-38792 [https://bugs.python.org/issue?@action=redirect&bpo=38792]: Close an IDLE shell calltip if a KeyboardInterrupt or shell restart occurs. Patch by Zackery Spytz.

C API

bpo-35081 [https://bugs.python.org/issue?@action=redirect&bpo=35081]: Move the bytes_methods.h header file to the internal C API as pycore_bytes_methods.h: it only contains private symbols (prefixed by _Py), except of the PyDoc_STRVAR_shared() macro.

bpo-35081 [https://bugs.python.org/issue?@action=redirect&bpo=35081]: Move the dtoa.h header file to the internal C API as pycore_dtoa.h: it only contains private functions (prefixed by _Py). The math and cmath modules must now be compiled with the Py_BUILD_CORE macro defined.

bpo-39573 [https://bugs.python.org/issue?@action=redirect&bpo=39573]: Add Py_SET_SIZE() function to set the size of an object.

bpo-39500 [https://bugs.python.org/issue?@action=redirect&bpo=39500]: PyUnicode_IsIdentifier() does not call Py_FatalError() anymore if the string is not ready.

bpo-39573 [https://bugs.python.org/issue?@action=redirect&bpo=39573]: Add Py_SET_TYPE() function to set the type of an object.

bpo-39573 [https://bugs.python.org/issue?@action=redirect&bpo=39573]: Add a Py_SET_REFCNT() function to set the reference counter of an object.

bpo-39542 [https://bugs.python.org/issue?@action=redirect&bpo=39542]: Convert PyType_HasFeature(), PyType_Check() and PyType_CheckExact() macros to static inline functions.

bpo-39542 [https://bugs.python.org/issue?@action=redirect&bpo=39542]: In the limited C API, PyObject_INIT() and PyObject_INIT_VAR() are now defined as aliases to PyObject_Init() and 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: _Py_NewReference(), _Py_ForgetReference(), _PyTraceMalloc_NewReference() and _Py_GetRefTotal().

bpo-39542 [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.

bpo-39511 [https://bugs.python.org/issue?@action=redirect&bpo=39511]: The PyThreadState_Clear() function now calls the PyThreadState.on_delete callback. Previously, that happened in PyThreadState_Delete().

bpo-38076 [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

bpo-39245 [https://bugs.python.org/issue?@action=redirect&bpo=39245]: The Vectorcall API (PEP 590) was made public, adding the functions PyObject_Vectorcall, PyObject_VectorcallMethod, PyVectorcall_Function, PyObject_CallOneArg, PyObject_CallMethodNoArgs, PyObject_CallMethodOneArg, PyObject_FastCallDict, and the flag Py_TPFLAGS_HAVE_VECTORCALL.

Python 3.9.0 alpha 3

Release date: 2020-01-24

Core and Builtins

bpo-39427 [https://bugs.python.org/issue?@action=redirect&bpo=39427]: Document all possibilities for the -X options in the command line help section. Patch by Pablo Galindo.

bpo-39421 [https://bugs.python.org/issue?@action=redirect&bpo=39421]: Fix possible crashes when operating with the functions in the heapq module and custom comparison operators.

bpo-39386 [https://bugs.python.org/issue?@action=redirect&bpo=39386]: Prevent double awaiting of async iterator.

bpo-17005 [https://bugs.python.org/issue?@action=redirect&bpo=17005]: Add functools.TopologicalSorter to the functools module to offers functionality to perform topological sorting of graphs. Patch by Pablo Galindo, Tim Peters and Larry Hastings.

bpo-39320 [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:

BUILD_LIST_UNPACK

BUILD_TUPLE_UNPACK

BUILD_SET_UNPACK

BUILD_TUPLE_UNPACK_WITH_CALL

The following three bytecodes have been added:

LIST_TO_TUPLE

LIST_EXTEND

SET_UPDATE

bpo-39336 [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.

bpo-39322 [https://bugs.python.org/issue?@action=redirect&bpo=39322]: Added a new function gc.is_finalized() to check if an object has been finalized by the garbage collector. Patch by Pablo Galindo.

bpo-39048 [https://bugs.python.org/issue?@action=redirect&bpo=39048]: Improve the displayed error message when incorrect types are passed to async with statements by looking up the __aenter__() special method before the __aexit__() special method when entering an asynchronous context manager. Patch by Géry Ogam.

bpo-39235 [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).

bpo-39209 [https://bugs.python.org/issue?@action=redirect&bpo=39209]: Correctly handle multi-line tokens in interactive mode. Patch by Pablo Galindo.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _json extension module to multiphase initialization (PEP 489 [https://peps.python.org/pep-0489/]).

bpo-39216 [https://bugs.python.org/issue?@action=redirect&bpo=39216]: Fix constant folding optimization for positional only arguments - by Anthony Sottile.

bpo-39215 [https://bugs.python.org/issue?@action=redirect&bpo=39215]: Fix SystemError when nested function has annotation on positional-only argument - by Anthony Sottile.

bpo-39200 [https://bugs.python.org/issue?@action=redirect&bpo=39200]: Correct the error message when calling the min() or max() with no arguments. Patch by Donghee Na.

bpo-39200 [https://bugs.python.org/issue?@action=redirect&bpo=39200]: Correct the error message when trying to construct range objects with no arguments. Patch by Pablo Galindo.

bpo-39166 [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.

bpo-39114 [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.

bpo-39156 [https://bugs.python.org/issue?@action=redirect&bpo=39156]: Split the COMPARE_OP bytecode instruction into four distinct instructions.

COMPARE_OP for rich comparisons

IS_OP for 'is' and 'is not' tests

CONTAINS_OP for 'in' and 'is not' tests

JUMP_IF_NOT_EXC_MATCH for checking exceptions in 'try-except' statements.

This improves the clarity of the interpreter and should provide a modest speedup.

bpo-38588 [https://bugs.python.org/issue?@action=redirect&bpo=38588]: Fix possible crashes in dict and list when calling PyObject_RichCompareBool().

bpo-13601 [https://bugs.python.org/issue?@action=redirect&bpo=13601]: By default, sys.stderr is line-buffered now, even if stderr is redirected to a file. You can still make sys.stderr unbuffered by passing the -u command-line option or setting the PYTHONUNBUFFERED environment variable.

(Contributed by Jendrik Seipp in bpo-13601 [https://bugs.python.org/issue?@action=redirect&bpo=13601].)

bpo-38610 [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 PyObject_RichCompareBool().

bpo-32021 [https://bugs.python.org/issue?@action=redirect&bpo=32021]: Include brotli .br encoding in mimetypes encodings_map

Library

bpo-39430 [https://bugs.python.org/issue?@action=redirect&bpo=39430]: Fixed race condition in lazy imports in tarfile.

bpo-39413 [https://bugs.python.org/issue?@action=redirect&bpo=39413]: The os.unsetenv() function is now also available on Windows.

bpo-39390 [https://bugs.python.org/issue?@action=redirect&bpo=39390]: Fixed a regression with the ignore callback of shutil.copytree(). The argument types are now str and List[str] again.

bpo-39395 [https://bugs.python.org/issue?@action=redirect&bpo=39395]: The os.putenv() and os.unsetenv() functions are now always available.

bpo-39406 [https://bugs.python.org/issue?@action=redirect&bpo=39406]: If setenv() C function is available, os.putenv() is now implemented with setenv() instead of putenv(), so Python doesn't have to handle the environment variable memory.

bpo-39396 [https://bugs.python.org/issue?@action=redirect&bpo=39396]: Fix math.nextafter(-0.0, +0.0) on AIX 7.1.

bpo-29435 [https://bugs.python.org/issue?@action=redirect&bpo=29435]: Allow tarfile.is_tarfile() to be used with file and file-like objects, like zipfile.is_zipfile(). Patch by William Woodruff.

bpo-39377 [https://bugs.python.org/issue?@action=redirect&bpo=39377]: Removed encoding option from json.loads(). It has been deprecated since Python 3.1.

bpo-39389 [https://bugs.python.org/issue?@action=redirect&bpo=39389]: Write accurate compression level metadata in gzip archives, rather than always signaling maximum compression.

bpo-39366 [https://bugs.python.org/issue?@action=redirect&bpo=39366]: The previously deprecated xpath() and xgtitle() methods of nntplib.NNTP have been removed.

bpo-39357 [https://bugs.python.org/issue?@action=redirect&bpo=39357]: Remove the buffering parameter of bz2.BZ2File. Since Python 3.0, it was ignored and using it was emitting DeprecationWarning. Pass an open file object, to control how the file is opened. The compresslevel parameter becomes keyword-only.

bpo-39353 [https://bugs.python.org/issue?@action=redirect&bpo=39353]: Deprecate binhex4 and hexbin4 standards. Deprecate the binhex module and the following binascii functions: b2a_hqx(), a2b_hqx(), rlecode_hqx(), rledecode_hqx(), crc_hqx().

bpo-39351 [https://bugs.python.org/issue?@action=redirect&bpo=39351]: Remove base64.encodestring() and base64.decodestring(), aliases deprecated since Python 3.1: use base64.encodebytes() and base64.decodebytes() instead.

bpo-39350 [https://bugs.python.org/issue?@action=redirect&bpo=39350]: Remove fractions.gcd() function, deprecated since Python 3.5 (bpo-22486 [https://bugs.python.org/issue?@action=redirect&bpo=22486]): use math.gcd() instead.

bpo-39329 [https://bugs.python.org/issue?@action=redirect&bpo=39329]: LMTP constructor now has an optional timeout parameter. Patch by Donghee Na.

bpo-39313 [https://bugs.python.org/issue?@action=redirect&bpo=39313]: Add a new exec_function option (--exec-function in the CLI) to RefactoringTool for making exec a function. Patch by Batuhan Taskaya.

bpo-39259 [https://bugs.python.org/issue?@action=redirect&bpo=39259]: FTP_TLS and FTP_TLS now raise a ValueError if the given timeout for their constructor is zero to prevent the creation of a non-blocking socket. Patch by Donghee Na.

bpo-39259 [https://bugs.python.org/issue?@action=redirect&bpo=39259]: SMTP and SMTP_SSL now raise a ValueError if the given timeout for their constructor is zero to prevent the creation of a non-blocking socket. Patch by Donghee Na.

bpo-39310 [https://bugs.python.org/issue?@action=redirect&bpo=39310]: Add math.ulp(): return the value of the least significant bit of a float.

bpo-39297 [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).

bpo-39259 [https://bugs.python.org/issue?@action=redirect&bpo=39259]: NNTP and NNTP_SSL now raise a ValueError if the given timeout for their constructor is zero to prevent the creation of a non-blocking socket. Patch by Donghee Na.

bpo-38901 [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.

bpo-39288 [https://bugs.python.org/issue?@action=redirect&bpo=39288]: Add math.nextafter(): return the next floating-point value after x towards y.

bpo-39259 [https://bugs.python.org/issue?@action=redirect&bpo=39259]: POP3 and POP3_SSL now raise a ValueError if the given timeout for their constructor is zero to prevent the creation of a non-blocking socket. Patch by Donghee Na.

bpo-39242 [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 NNTP news reader server and nntplib tests.

bpo-35292 [https://bugs.python.org/issue?@action=redirect&bpo=35292]: Proxy the SimpleHTTPRequestHandler.guess_type to mimetypes.guess_type so the mimetypes.init is called lazily to avoid unnecessary costs when http.server module is imported.

bpo-39239 [https://bugs.python.org/issue?@action=redirect&bpo=39239]: The select.epoll.unregister() method no longer ignores the EBADF error.

bpo-38907 [https://bugs.python.org/issue?@action=redirect&bpo=38907]: In http.server script, restore binding to IPv4 on Windows.

bpo-39152 [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.

bpo-39198 [https://bugs.python.org/issue?@action=redirect&bpo=39198]: If an exception were to be thrown in Logger.isEnabledFor (say, by asyncio timeouts or stopit) , the logging global lock may not be released appropriately, resulting in deadlock. This change wraps that block of code with try...finally to ensure the lock is released.

bpo-39191 [https://bugs.python.org/issue?@action=redirect&bpo=39191]: Perform a check for running loop before starting a new task in loop.run_until_complete() to fail fast; it prevents the side effect of new task spawning before exception raising.

bpo-38871 [https://bugs.python.org/issue?@action=redirect&bpo=38871]: Correctly parenthesize filter-based statements that contain lambda expressions in lib2to3. Patch by Donghee Na.

bpo-39142 [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.

bpo-39158 [https://bugs.python.org/issue?@action=redirect&bpo=39158]: ast.literal_eval() now supports empty sets.

bpo-39129 [https://bugs.python.org/issue?@action=redirect&bpo=39129]: Fix import path for asyncio.TimeoutError

bpo-39057 [https://bugs.python.org/issue?@action=redirect&bpo=39057]: urllib.request.proxy_bypass_environment() now ignores leading dots and no longer ignores a trailing newline.

bpo-39056 [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.

bpo-39055 [https://bugs.python.org/issue?@action=redirect&bpo=39055]: base64.b64decode() with validate=True raises now a binascii.Error if the input ends with a single \n.

bpo-21600 [https://bugs.python.org/issue?@action=redirect&bpo=21600]: Fix mock.patch.stopall() to stop active patches that were created with mock.patch.dict().

bpo-39019 [https://bugs.python.org/issue?@action=redirect&bpo=39019]: Implement dummy __class_getitem__ for tempfile.SpooledTemporaryFile.

bpo-39019 [https://bugs.python.org/issue?@action=redirect&bpo=39019]: Implement dummy __class_getitem__ for subprocess.Popen, subprocess.CompletedProcess

bpo-38914 [https://bugs.python.org/issue?@action=redirect&bpo=38914]: Adjusted the wording of the warning issued by distutils' check command when the author and maintainer fields are supplied but no corresponding e-mail field (author_email or maintainer_email) is found. The wording now reflects the fact that these fields are suggested, but not required. Patch by Juergen Gmach.

bpo-38878 [https://bugs.python.org/issue?@action=redirect&bpo=38878]: Fixed __subclasshook__ of os.PathLike to return a correct result upon inheritance. Patch by Bar Harel.

bpo-38615 [https://bugs.python.org/issue?@action=redirect&bpo=38615]: IMAP4 and IMAP4_SSL now have an optional timeout parameter for their constructors. Also, the open() method now has an optional timeout parameter with this change. The overridden methods of IMAP4_SSL and IMAP4_stream were applied to this change. Patch by Donghee Na.

bpo-35182 [https://bugs.python.org/issue?@action=redirect&bpo=35182]: Fixed 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.

bpo-38630 [https://bugs.python.org/issue?@action=redirect&bpo=38630]: On Unix, 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 subprocess.Popen.returncode attribute is still None, and the pid has been reassigned (recycled) to a new different process.

bpo-38536 [https://bugs.python.org/issue?@action=redirect&bpo=38536]: Removes trailing space in formatted currency with international=True and a locale with symbol following value. E.g. locale.currency(12.34, international=True) returned '12,34 EUR ' instead of '12,34 EUR'.

bpo-38473 [https://bugs.python.org/issue?@action=redirect&bpo=38473]: Use signature from inner mock for autospecced methods attached with unittest.mock.attach_mock(). Patch by Karthikeyan Singaravelan.

bpo-38361 [https://bugs.python.org/issue?@action=redirect&bpo=38361]: Fixed an issue where ident could include a leading path separator when syslog.openlog() was called without arguments.

bpo-38293 [https://bugs.python.org/issue?@action=redirect&bpo=38293]: Add copy.copy() and copy.deepcopy() support to property() objects.

bpo-37958 [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.

bpo-28367 [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

Documentation

bpo-39381 [https://bugs.python.org/issue?@action=redirect&bpo=39381]: Mention in docs that asyncio.get_event_loop() implicitly creates new event loop only if called from the main thread.

bpo-38918 [https://bugs.python.org/issue?@action=redirect&bpo=38918]: Add an entry for __module__ in the "function" & "method" sections of the inspect docs' 型とメンバー table.

bpo-3530 [https://bugs.python.org/issue?@action=redirect&bpo=3530]: In the ast module documentation, fix a misleading NodeTransformer example and add advice on when to use the fix_missing_locations function.

Build

bpo-39395 [https://bugs.python.org/issue?@action=redirect&bpo=39395]: On non-Windows platforms, the setenv() and unsetenv() functions are now required to build Python.

bpo-39160 [https://bugs.python.org/issue?@action=redirect&bpo=39160]: Updated the documentation in ./configure --help to show default values, reference documentation where required and add additional explanation where needed.

bpo-39144 [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.

IDLE

bpo-39050 [https://bugs.python.org/issue?@action=redirect&bpo=39050]: Make IDLE Settings dialog Help button work again.

bpo-34118 [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.

bpo-32989 [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.

C API

bpo-39372 [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: _PyBytes_InsertThousandsGroupingLocale, _PyBytes_InsertThousandsGrouping, _Py_InitializeFromArgs, _Py_InitializeFromWideArgs, _PyFloat_Repr, _PyFloat_Digits, _PyFloat_DigitsInit, PyFrame_ExtendStack, _PyAIterWrapper_Type, PyNullImporter_Type, PyCmpWrapper_Type, PySortWrapper_Type, PyNoArgsFunction.

bpo-39164 [https://bugs.python.org/issue?@action=redirect&bpo=39164]: Add a private _PyErr_GetExcInfo() function to retrieve exception information of the specified Python thread state.

Python 3.9.0 alpha 2

Release date: 2019-12-18

Security

bpo-38945 [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.

bpo-37228 [https://bugs.python.org/issue?@action=redirect&bpo=37228]: Due to significant security concerns, the reuse_address parameter of asyncio.loop.create_datagram_endpoint() is no longer supported. This is because of the behavior of SO_REUSEADDR in UDP. For more details, see the documentation for loop.create_datagram_endpoint(). (Contributed by Kyle Stanley, Antoine Pitrou, and Yury Selivanov in bpo-37228 [https://bugs.python.org/issue?@action=redirect&bpo=37228].)

bpo-38804 [https://bugs.python.org/issue?@action=redirect&bpo=38804]: Fixes a ReDoS vulnerability in http.cookiejar. Patch by Ben Caller.

Core and Builtins

bpo-39028 [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.

bpo-39080 [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.

bpo-39031 [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.

bpo-20443 [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.

bpo-39008 [https://bugs.python.org/issue?@action=redirect&bpo=39008]: PySys_Audit() now requires Py_ssize_t to be used for size arguments in the format string, regardless of whether PY_SSIZE_T_CLEAN was defined at include time.

bpo-38673 [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.

bpo-38922 [https://bugs.python.org/issue?@action=redirect&bpo=38922]: Calling replace on a code object now raises the code.__new__ audit event.

bpo-38920 [https://bugs.python.org/issue?@action=redirect&bpo=38920]: Add audit hooks for when sys.excepthook() and sys.unraisablehook() are invoked.

bpo-38892 [https://bugs.python.org/issue?@action=redirect&bpo=38892]: Improve documentation for audit events table and functions.

bpo-38852 [https://bugs.python.org/issue?@action=redirect&bpo=38852]: Set the thread stack size to 8 Mb for debug builds on android platforms.

bpo-38858 [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 NSMALLNEGINTS and NSMALLPOSINTS macros: macros should now be modified manually in pycore_pystate.h header file.

bpo-36854 [https://bugs.python.org/issue?@action=redirect&bpo=36854]: The garbage collector state becomes per interpreter (PyInterpreterState.gc), rather than being global (_PyRuntimeState.gc).

bpo-38835 [https://bugs.python.org/issue?@action=redirect&bpo=38835]: The PyFPE_START_PROTECT() and PyFPE_END_PROTECT() macros are empty: they have been doing nothing for the last year, so stop using them.

bpo-38328 [https://bugs.python.org/issue?@action=redirect&bpo=38328]: Sped up the creation time of constant list and set displays. Patch by Brandt Bucher.

bpo-38707 [https://bugs.python.org/issue?@action=redirect&bpo=38707]: MainThread.native_id is now correctly reset in child processes spawned using multiprocessing.Process, instead of retaining the parent's value.

bpo-38629 [https://bugs.python.org/issue?@action=redirect&bpo=38629]: Added __floor__ and __ceil__ methods to float object. Patch by Batuhan Taşkaya.

bpo-27145 [https://bugs.python.org/issue?@action=redirect&bpo=27145]: int + int and int - int operators can now return small integer singletons. Patch by hongweipeng.

bpo-38021 [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.

bpo-35409 [https://bugs.python.org/issue?@action=redirect&bpo=35409]: Ignore GeneratorExit exceptions when throwing an exception into the aclose coroutine of an asynchronous generator.

bpo-33387 [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.

Library

bpo-39033 [https://bugs.python.org/issue?@action=redirect&bpo=39033]: Fix NameError in zipimport. Patch by Karthikeyan Singaravelan.

bpo-39022 [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.

bpo-39006 [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.

bpo-38708 [https://bugs.python.org/issue?@action=redirect&bpo=38708]: Fix a potential IndexError in email parser when parsing an empty msg-id.

bpo-38698 [https://bugs.python.org/issue?@action=redirect&bpo=38698]: Add a new InvalidMessageID token to email parser to represent invalid Message-ID headers. Also, add defects when there is remaining value after parsing the header.

bpo-38994 [https://bugs.python.org/issue?@action=redirect&bpo=38994]: Implement __class_getitem__ for os.PathLike, pathlib.Path.

bpo-38979 [https://bugs.python.org/issue?@action=redirect&bpo=38979]: Return class from ContextVar.__class_getitem__ to simplify subclassing.

bpo-38978 [https://bugs.python.org/issue?@action=redirect&bpo=38978]: Implement __class_getitem__ on asyncio objects (Future, Task, Queue). Patch by Batuhan Taskaya.

bpo-38916 [https://bugs.python.org/issue?@action=redirect&bpo=38916]: array.array: Remove tostring() and fromstring() methods. They were aliases to tobytes() and frombytes(), deprecated since Python 3.2.

bpo-38986 [https://bugs.python.org/issue?@action=redirect&bpo=38986]: Make repr of C accelerated TaskWakeupMethWrapper the same as of pure Python version.

bpo-38982 [https://bugs.python.org/issue?@action=redirect&bpo=38982]: Fix asyncio PidfdChildWatcher: handle waitpid() error. If waitpid() is called elsewhere, waitpid() call fails with 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.

bpo-38529 [https://bugs.python.org/issue?@action=redirect&bpo=38529]: Drop too noisy asyncio warning about deletion of a stream without explicit .close() call.

bpo-27413 [https://bugs.python.org/issue?@action=redirect&bpo=27413]: Added ability to pass through ensure_ascii options to json.dumps in the json.tool command-line interface.

bpo-38634 [https://bugs.python.org/issue?@action=redirect&bpo=38634]: The readline module now detects if Python is linked to libedit at runtime on all platforms. Previously, the check was only done on macOS.

bpo-33684 [https://bugs.python.org/issue?@action=redirect&bpo=33684]: Fix json.tool failed to read a JSON file with non-ASCII characters when locale encoding is not UTF-8.

bpo-38698 [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 UnboundLocalError on parsing an invalid value. Patch by Claudiu Popa.

bpo-38927 [https://bugs.python.org/issue?@action=redirect&bpo=38927]: Use python -m pip instead of pip to upgrade dependencies in venv.

bpo-26730 [https://bugs.python.org/issue?@action=redirect&bpo=26730]: Fix SpooledTemporaryFile.rollover() might corrupt the file when it is in text mode. Patch by Serhiy Storchaka.

bpo-38881 [https://bugs.python.org/issue?@action=redirect&bpo=38881]: random.choices() now raises a ValueError when all the weights are zero.

bpo-38876 [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 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 BINGET or LONG_BINGET load from the memo, leading to a KeyError as the determined index was bogus. Patch by Claudiu Popa.

bpo-38688 [https://bugs.python.org/issue?@action=redirect&bpo=38688]: Calling func: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.

bpo-38863 [https://bugs.python.org/issue?@action=redirect&bpo=38863]: Improve is_cgi() function in http.server, which enables processing the case that cgi directory is a child of another directory other than root.

bpo-37838 [https://bugs.python.org/issue?@action=redirect&bpo=37838]: typing.get_type_hints() properly handles functions decorated with functools.wraps().

bpo-38870 [https://bugs.python.org/issue?@action=redirect&bpo=38870]: Expose ast.unparse() as a function of the ast module that can be used to unparse an ast.AST object and produce a string with code that would produce an equivalent ast.AST object when parsed. Patch by Pablo Galindo and Batuhan Taskaya.

bpo-38859 [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.

bpo-38857 [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.

bpo-38834 [https://bugs.python.org/issue?@action=redirect&bpo=38834]: typing.TypedDict subclasses now track which keys are optional using the __required_keys__ and __optional_keys__ attributes, to enable runtime validation by downstream projects. Patch by Zac Hatfield-Dodds.

bpo-38821 [https://bugs.python.org/issue?@action=redirect&bpo=38821]: Fix unhandled exceptions in argparse when internationalizing error messages for arguments with nargs set to special (non-integer) values. Patch by Federico Bond.

bpo-38820 [https://bugs.python.org/issue?@action=redirect&bpo=38820]: Make Python compatible with OpenSSL 3.0.0. ssl.SSLSocket.getpeercert() no longer returns IPv6 addresses with a trailing new line.

bpo-38811 [https://bugs.python.org/issue?@action=redirect&bpo=38811]: Fix an unhandled exception in pathlib when os.link() is missing. Patch by Toke Høiland-Jørgensen.

bpo-38686 [https://bugs.python.org/issue?@action=redirect&bpo=38686]: Added support for multiple qop values in urllib.request.AbstractDigestAuthHandler.

bpo-38712 [https://bugs.python.org/issue?@action=redirect&bpo=38712]: Add the Linux-specific signal.pidfd_send_signal() function, which allows sending a signal to a process identified by a file descriptor rather than a pid.

bpo-38348 [https://bugs.python.org/issue?@action=redirect&bpo=38348]: Add -i and --indent (indentation level), and --no-type-comments (type comments) command line options to ast parsing tool.

bpo-37523 [https://bugs.python.org/issue?@action=redirect&bpo=37523]: Change zipfile.ZipExtFile to raise 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.

bpo-38045 [https://bugs.python.org/issue?@action=redirect&bpo=38045]: Improve the performance of enum._decompose() in enum. Patch by hongweipeng.

bpo-36820 [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 __traceback__ attribute. Patch by Mario Corchero.

bpo-36406 [https://bugs.python.org/issue?@action=redirect&bpo=36406]: Handle namespace packages in doctest. Patch by Karthikeyan Singaravelan.

bpo-34776 [https://bugs.python.org/issue?@action=redirect&bpo=34776]: Fix dataclasses to support forward references in type annotations

bpo-20928 [https://bugs.python.org/issue?@action=redirect&bpo=20928]: ElementTree supports recursive XInclude processing. Patch by Stefan Behnel.

bpo-29636 [https://bugs.python.org/issue?@action=redirect&bpo=29636]: Add whitespace options for formatting JSON with the json.tool CLI. The following mutually exclusive options are now supported: --indent for setting the indent level in spaces; --tab for indenting with tabs; --no-indent for suppressing newlines; and --compact for suppressing all whitespace. The default behavior remains the same as --indent=4.

Documentation

bpo-38928 [https://bugs.python.org/issue?@action=redirect&bpo=38928]: Correct when venv's upgrade_dependencies() and --upgrade-deps are added.

bpo-38899 [https://bugs.python.org/issue?@action=redirect&bpo=38899]: Update documentation to state that to activate virtual environments under fish one should use source, not . as documented at https://fishshell.com/docs/current/cmds/source.html.

bpo-22377 [https://bugs.python.org/issue?@action=redirect&bpo=22377]: Improves documentation of the values that datetime.datetime.strptime() accepts for %Z. Patch by Karl Dubost.

Tests

bpo-38546 [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.

bpo-38546 [https://bugs.python.org/issue?@action=redirect&bpo=38546]: Multiprocessing and concurrent.futures tests now stop the resource tracker process when tests complete.

bpo-38614 [https://bugs.python.org/issue?@action=redirect&bpo=38614]: Replace hardcoded timeout constants in tests with new test.support constants: LOOPBACK_TIMEOUT, INTERNET_TIMEOUT, SHORT_TIMEOUT and 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.

bpo-38547 [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.

bpo-38992 [https://bugs.python.org/issue?@action=redirect&bpo=38992]: Fix a test for math.fsum() that was failing due to constant folding.

bpo-38991 [https://bugs.python.org/issue?@action=redirect&bpo=38991]: test.support: run_python_until_end(), assert_python_ok() and assert_python_failure() functions no longer strip whitespaces from stderr. Remove test.support.strip_python_stderr() function.

bpo-38965 [https://bugs.python.org/issue?@action=redirect&bpo=38965]: Fix test_faulthandler on GCC 10. Use the "volatile" keyword in faulthandler._stack_overflow() to prevent tail call optimization on any compiler, rather than relying on compiler specific pragma.

bpo-38875 [https://bugs.python.org/issue?@action=redirect&bpo=38875]: test_capi: trashcan tests now require the test "cpu" resource.

bpo-38841 [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.

bpo-38692 [https://bugs.python.org/issue?@action=redirect&bpo=38692]: Skip the test_posix.test_pidfd_open() test if os.pidfd_open() fails with a PermissionError. This situation can happen in a Linux sandbox using a syscall whitelist which doesn't allow the pidfd_open() syscall yet.

bpo-38839 [https://bugs.python.org/issue?@action=redirect&bpo=38839]: Fix some unused functions in tests. Patch by Adam Johnson.

bpo-38669 [https://bugs.python.org/issue?@action=redirect&bpo=38669]: Raise TypeError when passing target as a string with unittest.mock.patch.object().

bpo-37957 [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.

Build

bpo-37404 [https://bugs.python.org/issue?@action=redirect&bpo=37404]: asyncio now raises TypeError when calling incompatible methods with an ssl.SSLSocket socket. Patch by Ido Michael.

bpo-36500 [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.

Windows

bpo-39007 [https://bugs.python.org/issue?@action=redirect&bpo=39007]: Add auditing events to functions in winreg.

bpo-33125 [https://bugs.python.org/issue?@action=redirect&bpo=33125]: Add support for building and releasing Windows ARM64 packages.

macOS

bpo-37931 [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 import posix. Patch by Benoît Hudson.

IDLE

bpo-38944 [https://bugs.python.org/issue?@action=redirect&bpo=38944]: Escape key now closes IDLE completion windows. Patch by Johnny Najera.

bpo-38943 [https://bugs.python.org/issue?@action=redirect&bpo=38943]: Fix IDLE autocomplete windows not always appearing on some systems. Patch by Johnny Najera.

bpo-38862 [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.

bpo-38636 [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.

C API

bpo-38896 [https://bugs.python.org/issue?@action=redirect&bpo=38896]: Remove PyUnicode_ClearFreeList() function: the Unicode free list has been removed in Python 3.3.

bpo-37340 [https://bugs.python.org/issue?@action=redirect&bpo=37340]: Remove PyMethod_ClearFreeList() and PyCFunction_ClearFreeList() functions: the free lists of bound method objects have been removed.

bpo-38835 [https://bugs.python.org/issue?@action=redirect&bpo=38835]: Exclude PyFPE_START_PROTECT() and PyFPE_END_PROTECT() macros of pyfpe.h from Py_LIMITED_API (stable API).

Python 3.9.0 alpha 1

Release date: 2019-11-19

Security

bpo-38722 [https://bugs.python.org/issue?@action=redirect&bpo=38722]: runpy now uses io.open_code() to open code files. Patch by Jason Killen.

bpo-38622 [https://bugs.python.org/issue?@action=redirect&bpo=38622]: Add additional audit events for the ctypes module.

bpo-38418 [https://bugs.python.org/issue?@action=redirect&bpo=38418]: Fixes audit event for os.system() to be named os.system.

bpo-38243 [https://bugs.python.org/issue?@action=redirect&bpo=38243]: Escape the server title of xmlrpc.server.DocXMLRPCServer when rendering the document page as HTML. (Contributed by Donghee Na in bpo-38243 [https://bugs.python.org/issue?@action=redirect&bpo=38243].)

bpo-38174 [https://bugs.python.org/issue?@action=redirect&bpo=38174]: Update vendorized expat library version to 2.2.8, which resolves CVE-2019-15903 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-15903].

bpo-37764 [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.

bpo-37461 [https://bugs.python.org/issue?@action=redirect&bpo=37461]: Fix an infinite loop when parsing specially crafted email headers. Patch by Abhilash Raj.

bpo-37363 [https://bugs.python.org/issue?@action=redirect&bpo=37363]: Adds audit events for the range of supported run commands (see コマンドラインと環境).

bpo-37463 [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'.

bpo-37363 [https://bugs.python.org/issue?@action=redirect&bpo=37363]: Adds audit events for ensurepip, ftplib, glob, imaplib, nntplib, pdb, poplib, shutil, smtplib, sqlite3, subprocess, telnetlib, tempfile and webbrowser, as well as os.listdir(), os.scandir() and breakpoint().

bpo-37364 [https://bugs.python.org/issue?@action=redirect&bpo=37364]: io.open_code() is now used when reading .pth files.

bpo-34631 [https://bugs.python.org/issue?@action=redirect&bpo=34631]: Updated OpenSSL to 1.1.1c in Windows installer

bpo-34155 [https://bugs.python.org/issue?@action=redirect&bpo=34155]: Fix parsing of invalid email addresses with more than one @ (e.g. a@b@c.com.) to not return the part before 2nd @ as valid email address. Patch by maxking & jpic.

Core and Builtins

bpo-38631 [https://bugs.python.org/issue?@action=redirect&bpo=38631]: Replace Py_FatalError() call with a regular RuntimeError exception in float.__getformat__().

bpo-38639 [https://bugs.python.org/issue?@action=redirect&bpo=38639]: Optimized math.floor(), math.ceil() and math.trunc() for floats.

bpo-38640 [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.

bpo-38613 [https://bugs.python.org/issue?@action=redirect&bpo=38613]: Optimized some set operations (e.g. |, ^, and -) of dict_keys. d.keys() | other was slower than set(d) | other but they are almost same performance for now.

bpo-28029 [https://bugs.python.org/issue?@action=redirect&bpo=28029]: "".replace("", s, n) now returns s instead of an empty string for all non-zero n. There are similar changes for bytes and bytearray objects.

bpo-38535 [https://bugs.python.org/issue?@action=redirect&bpo=38535]: Fixed line numbers and column offsets for AST nodes for calls without arguments in decorators.

bpo-38525 [https://bugs.python.org/issue?@action=redirect&bpo=38525]: Fix a segmentation fault when using reverse iterators of empty dict objects. Patch by Donghee Na and Inada Naoki.

bpo-38465 [https://bugs.python.org/issue?@action=redirect&bpo=38465]: bytearray, array and mmap objects allow now to export more than 2**31 buffers at a time.

bpo-38469 [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.

bpo-38437 [https://bugs.python.org/issue?@action=redirect&bpo=38437]: Activate the GC_DEBUG macro for debug builds of the interpreter (when Py_DEBUG is set). Patch by Pablo Galindo.

bpo-38379 [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.

bpo-38379 [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 collect() and 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.

bpo-38392 [https://bugs.python.org/issue?@action=redirect&bpo=38392]: In debug mode, PyObject_GC_Track() now calls tp_traverse() of the object type to ensure that the object is valid: test that objects visited by tp_traverse() are valid.

bpo-38210 [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 [https://bugs.python.org/issue?@action=redirect&bpo=38210].)

bpo-38402 [https://bugs.python.org/issue?@action=redirect&bpo=38402]: Check the error from the system's underlying crypt or crypt_r.

bpo-37474 [https://bugs.python.org/issue?@action=redirect&bpo=37474]: On FreeBSD, Python no longer calls fedisableexcept() at startup to control the floating point control mode. The call became useless since FreeBSD 6: it became the default mode.

bpo-38006 [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.

bpo-38317 [https://bugs.python.org/issue?@action=redirect&bpo=38317]: Fix warnings options priority: PyConfig.warnoptions has the highest priority, as stated in the PEP 587 [https://peps.python.org/pep-0587/].

bpo-38310 [https://bugs.python.org/issue?@action=redirect&bpo=38310]: Predict BUILD_MAP_UNPACK_WITH_CALL -> CALL_FUNCTION_EX opcode pairs in the main interpreter loop. Patch by Brandt Bucher.

bpo-36871 [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.

bpo-11410 [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.

bpo-38219 [https://bugs.python.org/issue?@action=redirect&bpo=38219]: Optimized the dict constructor and the update() method for the case when the argument is a dict.

bpo-38236 [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.

bpo-38013 [https://bugs.python.org/issue?@action=redirect&bpo=38013]: Allow to call async_generator_athrow().throw(...) even for non-started async generator helper. It fixes annoying warning at the end of asyncio.run() call.

bpo-38124 [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.

bpo-38116 [https://bugs.python.org/issue?@action=redirect&bpo=38116]: The select module is now PEP-384 compliant and no longer has static state

bpo-38113 [https://bugs.python.org/issue?@action=redirect&bpo=38113]: ast module updated to PEP-384 and all statics removed

bpo-38076 [https://bugs.python.org/issue?@action=redirect&bpo=38076]: The struct module is now PEP-384 compatible

bpo-38075 [https://bugs.python.org/issue?@action=redirect&bpo=38075]: The random module is now PEP-384 compatible

bpo-38074 [https://bugs.python.org/issue?@action=redirect&bpo=38074]: zlib module made PEP-384 compatible

bpo-38073 [https://bugs.python.org/issue?@action=redirect&bpo=38073]: Make pwd extension module PEP-384 compatible

bpo-38072 [https://bugs.python.org/issue?@action=redirect&bpo=38072]: grp module made PEP-384 compatible

bpo-38069 [https://bugs.python.org/issue?@action=redirect&bpo=38069]: Make _posixsubprocess PEP-384 compatible

bpo-38071 [https://bugs.python.org/issue?@action=redirect&bpo=38071]: Make termios extension module PEP-384 compatible

bpo-38005 [https://bugs.python.org/issue?@action=redirect&bpo=38005]: Fixed comparing and creating of InterpreterID and ChannelID.

bpo-36946 [https://bugs.python.org/issue?@action=redirect&bpo=36946]: Fix possible signed integer overflow when handling slices. Patch by hongweipeng.

bpo-37994 [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.

bpo-8425 [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ù).

bpo-37966 [https://bugs.python.org/issue?@action=redirect&bpo=37966]: The implementation of 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.

bpo-37947 [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.

bpo-37812 [https://bugs.python.org/issue?@action=redirect&bpo=37812]: The CHECK_SMALL_INT macro used inside Object/longobject.c has been replaced with an explicit return at each call site.

bpo-37751 [https://bugs.python.org/issue?@action=redirect&bpo=37751]: Fix codecs.lookup() to normalize the encoding name the same way than encodings.normalize_encoding(), except that codecs.lookup() also converts the name to lower case.

bpo-37830 [https://bugs.python.org/issue?@action=redirect&bpo=37830]: Fixed compilation of break and continue in the finally block when the corresponding try block contains return with a non-constant value.

bpo-20490 [https://bugs.python.org/issue?@action=redirect&bpo=20490]: Improve import error message for partially initialized module on circular from imports - by Anthony Sottile.

bpo-37840 [https://bugs.python.org/issue?@action=redirect&bpo=37840]: Fix handling of negative indices in sq_item of bytearray. Patch by Sergey Fedoseev.

bpo-37802 [https://bugs.python.org/issue?@action=redirect&bpo=37802]: Slightly improve performance of PyLong_FromUnsignedLong(), PyLong_FromUnsignedLongLong() and PyLong_FromSize_t(). Patch by Sergey Fedoseev.

bpo-37409 [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.

bpo-32912 [https://bugs.python.org/issue?@action=redirect&bpo=32912]: Reverted bpo-32912 [https://bugs.python.org/issue?@action=redirect&bpo=32912]: emitting SyntaxWarning instead of DeprecationWarning for invalid escape sequences in string and bytes literals.

bpo-37757 [https://bugs.python.org/issue?@action=redirect&bpo=37757]: PEP 572 [https://peps.python.org/pep-0572/]: As described in the PEP, assignment expressions now raise SyntaxError when their interaction with comprehension scoping results in an ambiguous target scope.

The TargetScopeError subclass originally proposed by the PEP has been removed in favour of just raising regular syntax errors for the disallowed cases.

bpo-36279 [https://bugs.python.org/issue?@action=redirect&bpo=36279]: Fix potential use of uninitialized memory in os.wait3().

bpo-36311 [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.

bpo-34880 [https://bugs.python.org/issue?@action=redirect&bpo=34880]: The assert statement now works properly if the AssertionError exception is being shadowed. Patch by Zackery Spytz.

bpo-37340 [https://bugs.python.org/issue?@action=redirect&bpo=37340]: Removed object cache (free_list) for bound method objects. Temporary bound method objects are less used than before thanks to the LOAD_METHOD opcode and the _PyObject_VectorcallMethod C API.

bpo-37648 [https://bugs.python.org/issue?@action=redirect&bpo=37648]: Fixed minor inconsistency in list.__contains__(), 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 ==.

bpo-37444 [https://bugs.python.org/issue?@action=redirect&bpo=37444]: Update differing exception between builtins.__import__() and importlib.__import__().

bpo-37619 [https://bugs.python.org/issue?@action=redirect&bpo=37619]: When adding a wrapper descriptor from one class to a different class (for example, setting __add__ = str.__add__ on an int subclass), an exception is correctly raised when the operator is called.

bpo-37593 [https://bugs.python.org/issue?@action=redirect&bpo=37593]: Swap the positions of the posonlyargs and args parameters in the constructor of ast.parameters nodes.

bpo-37543 [https://bugs.python.org/issue?@action=redirect&bpo=37543]: Optimized pymalloc for non PGO build.

bpo-37537 [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().

bpo-37467 [https://bugs.python.org/issue?@action=redirect&bpo=37467]: Fix sys.excepthook() and PyErr_Display() if a filename is a bytes string. For example, for a SyntaxError exception where the filename attribute is a bytes string.

bpo-37433 [https://bugs.python.org/issue?@action=redirect&bpo=37433]: Fix SyntaxError indicator printing too many spaces for multi-line strings - by Anthony Sottile.

bpo-37417 [https://bugs.python.org/issue?@action=redirect&bpo=37417]: bytearray.extend() now correctly handles errors that arise during iteration. Patch by Brandt Bucher.

bpo-37414 [https://bugs.python.org/issue?@action=redirect&bpo=37414]: The undocumented sys.callstats() function has been removed. Since Python 3.7, it was deprecated and always returned None. It required a special build option CALL_PROFILE which was already removed in Python 3.7.

bpo-37392 [https://bugs.python.org/issue?@action=redirect&bpo=37392]: Remove sys.getcheckinterval() and sys.setcheckinterval() functions. They were deprecated since Python 3.2. Use sys.getswitchinterval() and sys.setswitchinterval() instead. Remove also check_interval field of the PyInterpreterState structure.

bpo-37388 [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: open(), str.encode() and 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.

bpo-37348 [https://bugs.python.org/issue?@action=redirect&bpo=37348]: Optimized decoding short ASCII string with UTF-8 and ascii codecs. b"foo".decode() is about 15% faster. Patch by Inada Naoki.

bpo-24214 [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.

bpo-37330 [https://bugs.python.org/issue?@action=redirect&bpo=37330]: open(), io.open(), codecs.open() and fileinput.FileInput no longer accept 'U' ("universal newline") in the file mode. This flag was deprecated since Python 3.3.

bpo-35224 [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 {k: v for ...}, k will be evaluated before v.

bpo-37316 [https://bugs.python.org/issue?@action=redirect&bpo=37316]: Fix the PySys_Audit() call in mmap.mmap.

bpo-37300 [https://bugs.python.org/issue?@action=redirect&bpo=37300]: Remove an unnecessary Py_XINCREF in classobject.c.

bpo-37269 [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.

bpo-20443 [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.

bpo-37257 [https://bugs.python.org/issue?@action=redirect&bpo=37257]: Python's small object allocator (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.

bpo-37231 [https://bugs.python.org/issue?@action=redirect&bpo=37231]: The dispatching of type slots to special methods (for example calling __mul__ when doing x * y) has been made faster.

bpo-36974 [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.

bpo-37213 [https://bugs.python.org/issue?@action=redirect&bpo=37213]: Handle correctly negative line offsets in the peephole optimizer. Patch by Pablo Galindo.

bpo-37219 [https://bugs.python.org/issue?@action=redirect&bpo=37219]: Remove erroneous optimization for empty set differences.

bpo-15913 [https://bugs.python.org/issue?@action=redirect&bpo=15913]: Implement PyBuffer_SizeFromFormat() function (previously documented but not implemented): call struct.calcsize(). Patch by Joannah Nanjekye.

bpo-36922 [https://bugs.python.org/issue?@action=redirect&bpo=36922]: Slot functions optimize any callable with Py_TPFLAGS_METHOD_DESCRIPTOR instead of only instances of function.

bpo-36974 [https://bugs.python.org/issue?@action=redirect&bpo=36974]: The slot tp_vectorcall_offset is inherited unconditionally to support super().__call__() when the base class uses vectorcall.

bpo-37160 [https://bugs.python.org/issue?@action=redirect&bpo=37160]: threading.get_native_id() now also supports NetBSD.

bpo-37077 [https://bugs.python.org/issue?@action=redirect&bpo=37077]: Add threading.get_native_id() support for AIX. Patch by M. Felt

bpo-36781 [https://bugs.python.org/issue?@action=redirect&bpo=36781]: sum() has been optimized for boolean values.

bpo-34556 [https://bugs.python.org/issue?@action=redirect&bpo=34556]: Add --upgrade-deps to venv module. Patch by Cooper Ry Lees

bpo-20523 [https://bugs.python.org/issue?@action=redirect&bpo=20523]: pdb.Pdb supports ~/.pdbrc in Windows 7. Patch by Tim Hopper and Dan Lidral-Porter.

bpo-35551 [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.

bpo-19072 [https://bugs.python.org/issue?@action=redirect&bpo=19072]: The classmethod decorator can now wrap other descriptors such as property objects. Adapted from a patch written by Graham Dumpleton.

bpo-27575 [https://bugs.python.org/issue?@action=redirect&bpo=27575]: Improve speed of dictview intersection by directly using set intersection logic. Patch by David Su.

bpo-30773 [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.

Library

bpo-36589 [https://bugs.python.org/issue?@action=redirect&bpo=36589]: The curses.update_lines_cols() function now returns None instead of 1 on success.

bpo-38807 [https://bugs.python.org/issue?@action=redirect&bpo=38807]: Update TypeError messages for os.path.join() to include os.PathLike objects as acceptable input types.

bpo-38724 [https://bugs.python.org/issue?@action=redirect&bpo=38724]: Add a repr for subprocess.Popen objects. Patch by Andrey Doroschenko.

bpo-38786 [https://bugs.python.org/issue?@action=redirect&bpo=38786]: pydoc now recognizes and parses HTTPS URLs. Patch by python273.

bpo-38785 [https://bugs.python.org/issue?@action=redirect&bpo=38785]: Prevent asyncio from crashing if parent __init__ is not called from a constructor of object derived from asyncio.Future.

bpo-38723 [https://bugs.python.org/issue?@action=redirect&bpo=38723]: pdb now uses io.open_code() to trigger auditing events.

bpo-27805 [https://bugs.python.org/issue?@action=redirect&bpo=27805]: Allow opening pipes and other non-seekable files in append mode with open().

bpo-38438 [https://bugs.python.org/issue?@action=redirect&bpo=38438]: Simplify the argparse usage message for nargs="*".

bpo-38761 [https://bugs.python.org/issue?@action=redirect&bpo=38761]: WeakSet is now registered as a collections.abc.MutableSet.

bpo-38716 [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.

bpo-38713 [https://bugs.python.org/issue?@action=redirect&bpo=38713]: Add os.P_PIDFD constant, which may be passed to os.waitid() to wait on a Linux process file descriptor.

bpo-38692 [https://bugs.python.org/issue?@action=redirect&bpo=38692]: Add asyncio.PidfdChildWatcher, a Linux-specific child watcher implementation that polls process file descriptors.

bpo-38692 [https://bugs.python.org/issue?@action=redirect&bpo=38692]: Expose the Linux pidfd_open syscall as os.pidfd_open().

bpo-38602 [https://bugs.python.org/issue?@action=redirect&bpo=38602]: Added constants F_OFD_GETLK, F_OFD_SETLK and F_OFD_SETLKW to the fcntl module. Patch by Donghee Na.

bpo-38334 [https://bugs.python.org/issue?@action=redirect&bpo=38334]: Fixed seeking backward on an encrypted zipfile.ZipExtFile.

bpo-38312 [https://bugs.python.org/issue?@action=redirect&bpo=38312]: Add curses.get_escdelay(), curses.set_escdelay(), curses.get_tabsize(), and curses.set_tabsize() functions - by Anthony Sottile.

bpo-38586 [https://bugs.python.org/issue?@action=redirect&bpo=38586]: Now fileConfig() correctly sets the .name of handlers loaded.

bpo-38565 [https://bugs.python.org/issue?@action=redirect&bpo=38565]: Add new cache_parameters() method for functools.lru_cache() to better support pickling.

bpo-34679 [https://bugs.python.org/issue?@action=redirect&bpo=34679]: asynci.ProactorEventLoop.close() now only calls signal.set_wakeup_fd() in the main thread.

bpo-31202 [https://bugs.python.org/issue?@action=redirect&bpo=31202]: The case the result of pathlib.WindowsPath.glob() matches now the case of the pattern for literal parts.

bpo-36321 [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.

bpo-38521 [https://bugs.python.org/issue?@action=redirect&bpo=38521]: Fixed erroneous equality comparison in statistics.NormalDist().

bpo-38493 [https://bugs.python.org/issue?@action=redirect&bpo=38493]: Added CLD_KILLED and CLD_STOPPED for si_code. Patch by Donghee Na.

bpo-38478 [https://bugs.python.org/issue?@action=redirect&bpo=38478]: Fixed a bug in 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.

bpo-33604 [https://bugs.python.org/issue?@action=redirect&bpo=33604]: Fixed hmac.new and 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.

bpo-38378 [https://bugs.python.org/issue?@action=redirect&bpo=38378]: Parameters out and in of os.sendfile() was renamed to out_fd and in_fd.

bpo-38417 [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.

bpo-38449 [https://bugs.python.org/issue?@action=redirect&bpo=38449]: Revert PR 15522, which introduces a regression in mimetypes.guess_type() due to improper handling of filenames as urls.

bpo-38431 [https://bugs.python.org/issue?@action=redirect&bpo=38431]: Fix __repr__ method for dataclasses.InitVar to support typing objects, patch by Samuel Colvin.

bpo-38109 [https://bugs.python.org/issue?@action=redirect&bpo=38109]: Add missing stat.S_IFDOOR, stat.S_IFPORT, stat.S_IFWHT, stat.S_ISDOOR(), stat.S_ISPORT(), and stat.S_ISWHT() values to the Python implementation of stat.

bpo-38422 [https://bugs.python.org/issue?@action=redirect&bpo=38422]: Clarify docstrings of pathlib suffix(es)

bpo-38405 [https://bugs.python.org/issue?@action=redirect&bpo=38405]: Nested subclasses of typing.NamedTuple are now pickleable.

bpo-38332 [https://bugs.python.org/issue?@action=redirect&bpo=38332]: Prevent KeyError thrown by _encoded_words.decode() when given an encoded-word with invalid content-type encoding from propagating all the way to email.message.get().

bpo-38371 [https://bugs.python.org/issue?@action=redirect&bpo=38371]: Deprecated the split() method in _tkinter.TkappType in favour of the splitlist() method which has more consistent and predictable behavior.

bpo-38341 [https://bugs.python.org/issue?@action=redirect&bpo=38341]: Add smtplib.SMTPNotSupportedError to the smtplib exported names.

bpo-38319 [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)

bpo-38242 [https://bugs.python.org/issue?@action=redirect&bpo=38242]: Revert the new asyncio Streams API

bpo-13153 [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).

bpo-38019 [https://bugs.python.org/issue?@action=redirect&bpo=38019]: Correctly handle pause/resume reading of closed asyncio unix pipe.

bpo-38163 [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).

bpo-38161 [https://bugs.python.org/issue?@action=redirect&bpo=38161]: Removes _AwaitEvent from AsyncMock.

bpo-38216 [https://bugs.python.org/issue?@action=redirect&bpo=38216]: Allow the rare code that wants to send invalid http requests from the http.client library a way to do so. The fixes for bpo-30458 [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.

bpo-28286 [https://bugs.python.org/issue?@action=redirect&bpo=28286]: Deprecate opening GzipFile for writing implicitly. Always specify the mode argument for writing.

bpo-38108 [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.

bpo-38265 [https://bugs.python.org/issue?@action=redirect&bpo=38265]: Update the length parameter of os.pread() to accept Py_ssize_t instead of int.

bpo-38112 [https://bugs.python.org/issue?@action=redirect&bpo=38112]: compileall has a higher default recursion limit and new command-line arguments for path manipulation, symlinks handling, and multiple optimization levels.

bpo-38248 [https://bugs.python.org/issue?@action=redirect&bpo=38248]: asyncio: Fix inconsistent immediate Task cancellation

bpo-38237 [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.

bpo-34002 [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.

bpo-38191 [https://bugs.python.org/issue?@action=redirect&bpo=38191]: Constructors of NamedTuple and TypedDict types now accept arbitrary keyword argument names, including "cls", "self", "typename", "_typename", "fields" and "_fields".

bpo-38155 [https://bugs.python.org/issue?@action=redirect&bpo=38155]: Add __all__ to datetime. Patch by Tahia Khan.

bpo-38185 [https://bugs.python.org/issue?@action=redirect&bpo=38185]: Fixed case-insensitive string comparison in sqlite3.Row indexing.

bpo-38136 [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.

bpo-37828 [https://bugs.python.org/issue?@action=redirect&bpo=37828]: Fix default mock name in unittest.mock.Mock.assert_called() exceptions. Patch by Abraham Toriz Cruz.

bpo-38175 [https://bugs.python.org/issue?@action=redirect&bpo=38175]: Fix a memory leak in comparison of sqlite3.Row objects.

bpo-33936 [https://bugs.python.org/issue?@action=redirect&bpo=33936]: _hashlib no longer calls obsolete OpenSSL initialization function with OpenSSL 1.1.0+.

bpo-34706 [https://bugs.python.org/issue?@action=redirect&bpo=34706]: Preserve subclassing in inspect.Signature.from_callable.

bpo-38153 [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.

bpo-38115 [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.

bpo-38148 [https://bugs.python.org/issue?@action=redirect&bpo=38148]: Add slots to asyncio transport classes, which can reduce memory usage.

bpo-38142 [https://bugs.python.org/issue?@action=redirect&bpo=38142]: The _hashlib OpenSSL wrapper extension module is now PEP-384 compliant.

bpo-9216 [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.

bpo-36991 [https://bugs.python.org/issue?@action=redirect&bpo=36991]: Fixes a potential incorrect AttributeError exception escaping ZipFile.extract() in some unsupported input error situations.

bpo-38134 [https://bugs.python.org/issue?@action=redirect&bpo=38134]: Remove obsolete copy of PBKDF2_HMAC_fast. All supported OpenSSL versions contain a fast implementation.

bpo-38132 [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.

bpo-38008 [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 collections.abc module

bpo-34037 [https://bugs.python.org/issue?@action=redirect&bpo=34037]: For asyncio, add a new coroutine loop.shutdown_default_executor(). The new coroutine provides an API to schedule an executor shutdown that waits on the threadpool to finish closing. Also, asyncio.run() has been updated to utilize the new coroutine. Patch by Kyle Stanley.

bpo-37405 [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.

bpo-38121 [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.

bpo-38110 [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.

bpo-38093 [https://bugs.python.org/issue?@action=redirect&bpo=38093]: Fixes AsyncMock so it doesn't crash when used with AsyncContextManagers or AsyncIterators.

bpo-37488 [https://bugs.python.org/issue?@action=redirect&bpo=37488]: Add warning to datetime.utctimetuple(), datetime.utcnow() and datetime.utcfromtimestamp() .

bpo-35640 [https://bugs.python.org/issue?@action=redirect&bpo=35640]: Allow passing a path-like object as directory argument to the http.server.SimpleHTTPRequestHandler class. Patch by Géry Ogam.

bpo-38086 [https://bugs.python.org/issue?@action=redirect&bpo=38086]: Update importlib.metadata with changes from importlib_metadata 0.21 [https://gitlab.com/python-devs/importlib_metadata/blob/0.21/importlib_metadata/docs/changelog.rst].

bpo-37251 [https://bugs.python.org/issue?@action=redirect&bpo=37251]: Remove __code__ check in AsyncMock that incorrectly evaluated function specs as async objects but failed to evaluate classes with __await__ but no __code__ attribute defined as async objects.

bpo-38037 [https://bugs.python.org/issue?@action=redirect&bpo=38037]: Fix reference counters in the signal module.

bpo-38066 [https://bugs.python.org/issue?@action=redirect&bpo=38066]: Hide internal asyncio.Stream methods: feed_eof(), feed_data(), set_exception() and set_transport().

bpo-38059 [https://bugs.python.org/issue?@action=redirect&bpo=38059]: inspect.py now uses sys.exit() instead of exit()

bpo-38049 [https://bugs.python.org/issue?@action=redirect&bpo=38049]: Added command-line interface for the ast module.

bpo-37953 [https://bugs.python.org/issue?@action=redirect&bpo=37953]: In typing, improved the __hash__ and __eq__ methods for ForwardReferences.

bpo-38026 [https://bugs.python.org/issue?@action=redirect&bpo=38026]: Fixed inspect.getattr_static() used isinstance while it should avoid dynamic lookup.

bpo-35923 [https://bugs.python.org/issue?@action=redirect&bpo=35923]: Update importlib.machinery.BuiltinImporter to use loader._ORIGIN instead of a hardcoded value. Patch by Donghee Na.

bpo-38010 [https://bugs.python.org/issue?@action=redirect&bpo=38010]: In importlib.metadata sync with importlib_metadata 0.20, clarifying behavior of files() and fixing issue where only one requirement was returned for requires() on dist-info packages.

bpo-38006 [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.

bpo-37995 [https://bugs.python.org/issue?@action=redirect&bpo=37995]: Added the indent option to ast.dump() which allows it to produce a multiline indented output.

bpo-34410 [https://bugs.python.org/issue?@action=redirect&bpo=34410]: Fixed a crash in the tee() iterator when re-enter it. RuntimeError is now raised in this case.

bpo-37140 [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.

bpo-37587 [https://bugs.python.org/issue?@action=redirect&bpo=37587]: _json.scanstring is now up to 3x faster when there are many backslash escaped characters in the JSON string.

bpo-37834 [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.

bpo-10978 [https://bugs.python.org/issue?@action=redirect&bpo=10978]: Semaphores and BoundedSemaphores can now release more than one waiting thread at a time.

bpo-37972 [https://bugs.python.org/issue?@action=redirect&bpo=37972]: Subscripts to the unittest.mock.call objects now receive the same chaining mechanism as any other custom attributes, so that the following usage no longer raises a TypeError:

call().foo().__getitem__('bar')

Patch by blhsing

bpo-37965 [https://bugs.python.org/issue?@action=redirect&bpo=37965]: Fix C compiler warning caused by distutils.ccompiler.CCompiler.has_function.

bpo-37964 [https://bugs.python.org/issue?@action=redirect&bpo=37964]: Add F_GETPATH command to fcntl.

bpo-37960 [https://bugs.python.org/issue?@action=redirect&bpo=37960]: repr() of buffered and text streams now silences only expected exceptions when get the value of "name" and "mode" attributes.

bpo-37961 [https://bugs.python.org/issue?@action=redirect&bpo=37961]: Add a total_nframe field to the traces collected by the tracemalloc module. This field indicates the original number of frames before it was truncated.

bpo-37951 [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.

bpo-36205 [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.

bpo-37950 [https://bugs.python.org/issue?@action=redirect&bpo=37950]: Fix ast.dump() when call with incompletely initialized node.

bpo-34679 [https://bugs.python.org/issue?@action=redirect&bpo=34679]: Restores instantiation of Windows IOCP event loops from the non-main thread.

bpo-36917 [https://bugs.python.org/issue?@action=redirect&bpo=36917]: Add default implementation of the ast.NodeVisitor.visit_Constant() method which emits a deprecation warning and calls corresponding methods visit_Num(), visit_Str(), etc.

bpo-37798 [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

bpo-26589 [https://bugs.python.org/issue?@action=redirect&bpo=26589]: Added a new status code to the http module: 451 UNAVAILABLE_FOR_LEGAL_REASONS

bpo-37915 [https://bugs.python.org/issue?@action=redirect&bpo=37915]: Fix a segmentation fault that appeared when comparing instances of datetime.timezone and datetime.tzinfo objects. Patch by Pablo Galindo.

bpo-32554 [https://bugs.python.org/issue?@action=redirect&bpo=32554]: Deprecate having random.seed() call hash on arbitrary types.

bpo-9938 [https://bugs.python.org/issue?@action=redirect&bpo=9938]: Add optional keyword argument exit_on_error for ArgumentParser.

bpo-37851 [https://bugs.python.org/issue?@action=redirect&bpo=37851]: The faulthandler module no longer allocates its alternative stack at Python startup. Now the stack is only allocated at the first faulthandler usage.

bpo-32793 [https://bugs.python.org/issue?@action=redirect&bpo=32793]: Fix a duplicated debug message when smtplib.SMTP.connect() is called.

bpo-37885 [https://bugs.python.org/issue?@action=redirect&bpo=37885]: venv: Don't generate unset variable warning on deactivate.

bpo-37868 [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.

bpo-37811 [https://bugs.python.org/issue?@action=redirect&bpo=37811]: Fix socket module's socket.connect(address) function being unable to establish connection in case of interrupted system call. The problem was observed on all OSes which poll(2) system call can take only non-negative integers and -1 as a timeout value.

bpo-37863 [https://bugs.python.org/issue?@action=redirect&bpo=37863]: Optimizations for Fraction.__hash__ suggested by Tim Peters.

bpo-21131 [https://bugs.python.org/issue?@action=redirect&bpo=21131]: Fix faulthandler.register(chain=True) stack. faulthandler now allocates a dedicated stack of SIGSTKSZ*2 bytes, instead of just SIGSTKSZ bytes. Calling the previous signal handler in faulthandler signal handler uses more than SIGSTKSZ bytes of stack memory on some platforms.

bpo-37798 [https://bugs.python.org/issue?@action=redirect&bpo=37798]: Add C fastpath for statistics.NormalDist.inv_cdf() Patch by Donghee Na

bpo-37804 [https://bugs.python.org/issue?@action=redirect&bpo=37804]: Remove the deprecated method threading.Thread.isAlive(). Patch by Donghee Na.

bpo-37819 [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.

bpo-14465 [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.

bpo-37810 [https://bugs.python.org/issue?@action=redirect&bpo=37810]: Fix difflib ? hint in diff output when dealing with tabs. Patch by Anthony Sottile.

bpo-37772 [https://bugs.python.org/issue?@action=redirect&bpo=37772]: In zipfile.Path, when adding implicit dirs, ensure that ancestral directories are added and that duplicates are excluded.

bpo-18578 [https://bugs.python.org/issue?@action=redirect&bpo=18578]: Renamed and documented test.bytecode_helper as test.support.bytecode_helper. Patch by Joannah Nanjekye.

bpo-37785 [https://bugs.python.org/issue?@action=redirect&bpo=37785]: Fix xgettext warnings in argparse.

bpo-34488 [https://bugs.python.org/issue?@action=redirect&bpo=34488]: writelines() method of io.BytesIO is now slightly faster when many small lines are passed. Patch by Sergey Fedoseev.

bpo-37449 [https://bugs.python.org/issue?@action=redirect&bpo=37449]: ensurepip now uses importlib.resources.read_binary() to read data instead of pkgutil.get_data(). Patch by Joannah Nanjekye.

bpo-28292 [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.

bpo-18049 [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

bpo-37742 [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'.

bpo-37738 [https://bugs.python.org/issue?@action=redirect&bpo=37738]: Fix the implementation of curses addch(str, color_pair): pass the color pair to setcchar(), instead of always passing 0 as the color pair.

bpo-37723 [https://bugs.python.org/issue?@action=redirect&bpo=37723]: Fix performance regression on regular expression parsing with huge character sets. Patch by Yann Vaginay.

bpo-35943 [https://bugs.python.org/issue?@action=redirect&bpo=35943]: The function PyImport_GetModule() now ensures any module it returns is fully initialized. Patch by Joannah Nanjekye.

bpo-32178 [https://bugs.python.org/issue?@action=redirect&bpo=32178]: Fix IndexError in email package when trying to parse invalid address fields starting with :.

bpo-37268 [https://bugs.python.org/issue?@action=redirect&bpo=37268]: The parser module is deprecated and will be removed in future versions of Python.

bpo-11953 [https://bugs.python.org/issue?@action=redirect&bpo=11953]: Completing WSA* error codes in socket.

bpo-37685 [https://bugs.python.org/issue?@action=redirect&bpo=37685]: Fixed comparisons of datetime.timedelta and datetime.timezone.

bpo-37697 [https://bugs.python.org/issue?@action=redirect&bpo=37697]: Synchronize importlib.metadata with importlib_metadata 0.19 [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.

bpo-37695 [https://bugs.python.org/issue?@action=redirect&bpo=37695]: Correct curses.unget_wch() error message. Patch by Anthony Sottile.

bpo-37689 [https://bugs.python.org/issue?@action=redirect&bpo=37689]: Add is_relative_to() in PurePath to determine whether or not one path is relative to another.

bpo-29553 [https://bugs.python.org/issue?@action=redirect&bpo=29553]: Fixed argparse.ArgumentParser.format_usage() for mutually exclusive groups. Patch by Andrew Nester.

bpo-37691 [https://bugs.python.org/issue?@action=redirect&bpo=37691]: Let math.dist() accept coordinates as sequences (or iterables) rather than just tuples.

bpo-37685 [https://bugs.python.org/issue?@action=redirect&bpo=37685]: Fixed __eq__, __lt__ etc implementations in some classes. They now return NotImplemented for unsupported type of the other operand. This allows the other operand to play role (for example the equality comparison with ANY will return True).

bpo-37354 [https://bugs.python.org/issue?@action=redirect&bpo=37354]: Make Activate.ps1 Powershell script static to allow for signing it.

bpo-37664 [https://bugs.python.org/issue?@action=redirect&bpo=37664]: Update wheels bundled with ensurepip (pip 19.2.3 and setuptools 41.2.0)

bpo-37663 [https://bugs.python.org/issue?@action=redirect&bpo=37663]: Bring consistency to venv shell activation scripts by always using __VENV_PROMPT__.

bpo-37642 [https://bugs.python.org/issue?@action=redirect&bpo=37642]: Allowed the pure Python implementation of 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

bpo-36161 [https://bugs.python.org/issue?@action=redirect&bpo=36161]: In posix, use ttyname_r instead of ttyname for thread safety.

bpo-36324 [https://bugs.python.org/issue?@action=redirect&bpo=36324]: Make internal attributes for statistics.NormalDist() private.

bpo-37555 [https://bugs.python.org/issue?@action=redirect&bpo=37555]: Fix NonCallableMock._call_matcher returning tuple instead of _Call object when self._spec_signature exists. Patch by Elizabeth Uselton

bpo-29446 [https://bugs.python.org/issue?@action=redirect&bpo=29446]: Make from tkinter import * import only the expected objects.

bpo-16970 [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

bpo-34443 [https://bugs.python.org/issue?@action=redirect&bpo=34443]: Exceptions from enum now use the __qualname of the enum class in the exception message instead of the __name__.

bpo-37491 [https://bugs.python.org/issue?@action=redirect&bpo=37491]: Fix IndexError when parsing email headers with unexpectedly ending bare-quoted string value. Patch by Abhilash Raj.

bpo-37587 [https://bugs.python.org/issue?@action=redirect&bpo=37587]: Make json.loads faster for long strings. (Patch by Marco Paolini)

bpo-18378 [https://bugs.python.org/issue?@action=redirect&bpo=18378]: Recognize "UTF-8" as a valid value for LC_CTYPE in locale._parse_localename.

bpo-37579 [https://bugs.python.org/issue?@action=redirect&bpo=37579]: Return NotImplemented in Python implementation of __eq__ for timedelta and time when the other object being compared is not of the same type to match C implementation. Patch by Karthikeyan Singaravelan.

bpo-21478 [https://bugs.python.org/issue?@action=redirect&bpo=21478]: Record calls to parent when autospecced object is attached to a mock using unittest.mock.attach_mock(). Patch by Karthikeyan Singaravelan.

bpo-37531 [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.

bpo-37482 [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.

bpo-36993 [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.

bpo-37502 [https://bugs.python.org/issue?@action=redirect&bpo=37502]: pickle.loads() no longer raises TypeError when the buffers argument is set to None

bpo-37520 [https://bugs.python.org/issue?@action=redirect&bpo=37520]: Correct behavior for zipfile.Path.parent when the path object identifies a subdirectory.

bpo-18374 [https://bugs.python.org/issue?@action=redirect&bpo=18374]: Fix the .col_offset attribute of nested ast.BinOp instances which had a too large value in some situations.

bpo-37424 [https://bugs.python.org/issue?@action=redirect&bpo=37424]: Fixes a possible hang when using a timeout on 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.

bpo-37421 [https://bugs.python.org/issue?@action=redirect&bpo=37421]: Fix multiprocessing.util.get_temp_dir() finalizer: clear also the 'tempdir' configuration of the current process, so next call to get_temp_dir() will create a new temporary directory, rather than reusing the removed temporary directory.

bpo-37481 [https://bugs.python.org/issue?@action=redirect&bpo=37481]: The distutils bdist_wininst command is deprecated in Python 3.8, use bdist_wheel (wheel packages) instead.

bpo-37479 [https://bugs.python.org/issue?@action=redirect&bpo=37479]: When Enum.__str__ is overridden in a derived class, the override will be used by Enum.__format__ regardless of whether mixin classes are present.

bpo-37440 [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.

bpo-37437 [https://bugs.python.org/issue?@action=redirect&bpo=37437]: Update vendorized expat version to 2.2.7.

bpo-37428 [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.

bpo-37420 [https://bugs.python.org/issue?@action=redirect&bpo=37420]: os.sched_setaffinity() now correctly handles errors that arise during iteration over its mask argument. Patch by Brandt Bucher.

bpo-37412 [https://bugs.python.org/issue?@action=redirect&bpo=37412]: The os.getcwdb() function now uses the UTF-8 encoding on Windows, rather than the ANSI code page: see PEP 529 [https://peps.python.org/pep-0529/] for the rationale. The function is no longer deprecated on Windows.

bpo-37406 [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.

bpo-29412 [https://bugs.python.org/issue?@action=redirect&bpo=29412]: Fix IndexError in parsing a header value ending unexpectedly. Patch by Abhilash Raj.

bpo-36546 [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.

bpo-37394 [https://bugs.python.org/issue?@action=redirect&bpo=37394]: Fix a bug that was causing the queue module to fail if the accelerator module was not available. Patch by Pablo Galindo.

bpo-37376 [https://bugs.python.org/issue?@action=redirect&bpo=37376]: pprint now has support for types.SimpleNamespace. Patch by Carl Bordum Hansen.

bpo-26967 [https://bugs.python.org/issue?@action=redirect&bpo=26967]: An ArgumentParser with allow_abbrev=False no longer disables grouping of short flags, such as -vv, but only disables abbreviation of long flags as documented. Patch by Zac Hatfield-Dodds.

bpo-37212 [https://bugs.python.org/issue?@action=redirect&bpo=37212]: unittest.mock.call() now preserves the order of keyword arguments in repr output. Patch by Karthikeyan Singaravelan.

bpo-37372 [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.

bpo-37345 [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 hasattr(socket, 'IPPROTO_UDPLITE') and there are constants defined for each of the values needed: socket.IPPROTO_UDPLITE, UDPLITE_SEND_CSCOV, and UDPLITE_RECV_CSCOV. Patch by Gabe Appleton.

bpo-37358 [https://bugs.python.org/issue?@action=redirect&bpo=37358]: Optimized functools.partial by using vectorcall.

bpo-37347 [https://bugs.python.org/issue?@action=redirect&bpo=37347]: sqlite3.Connection.create_aggregate(), sqlite3.Connection.create_function(), sqlite3.Connection.set_authorizer(), sqlite3.Connection.set_progress_handler() 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.

bpo-37163 [https://bugs.python.org/issue?@action=redirect&bpo=37163]: The obj argument of dataclasses.replace() is positional-only now.

bpo-37085 [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.

bpo-37328 [https://bugs.python.org/issue?@action=redirect&bpo=37328]: HTMLParser.unescape is removed. It was undocumented and deprecated since Python 3.4.

bpo-37305 [https://bugs.python.org/issue?@action=redirect&bpo=37305]: Add .webmanifest -> application/manifest+json to list of recognized file types and content type headers

bpo-37320 [https://bugs.python.org/issue?@action=redirect&bpo=37320]: aifc.openfp() alias to aifc.open(), sunau.openfp() alias to sunau.open(), and wave.openfp() alias to wave.open() have been removed. They were deprecated since Python 3.7.

bpo-37315 [https://bugs.python.org/issue?@action=redirect&bpo=37315]: Deprecated accepting floats with integral value (like 5.0) in math.factorial().

bpo-37312 [https://bugs.python.org/issue?@action=redirect&bpo=37312]: _dummy_thread and dummy_threading modules have been removed. These modules were deprecated since Python 3.7 which requires threading support.

bpo-33972 [https://bugs.python.org/issue?@action=redirect&bpo=33972]: Email with single part but content-type set to multipart/* doesn't raise AttributeError anymore.

bpo-37280 [https://bugs.python.org/issue?@action=redirect&bpo=37280]: Use threadpool for reading from file for sendfile fallback mode.

bpo-37279 [https://bugs.python.org/issue?@action=redirect&bpo=37279]: Fix asyncio sendfile support when sendfile sends extra data in fallback mode.

bpo-19865 [https://bugs.python.org/issue?@action=redirect&bpo=19865]: ctypes.create_unicode_buffer() now also supports non-BMP characters on platforms with 16-bit wchar_t (for example, Windows and AIX).

bpo-37266 [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.

bpo-37210 [https://bugs.python.org/issue?@action=redirect&bpo=37210]: Allow pure Python implementation of pickle to work even when the C _pickle module is unavailable.

bpo-21872 [https://bugs.python.org/issue?@action=redirect&bpo=21872]: Fix 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.

bpo-35922 [https://bugs.python.org/issue?@action=redirect&bpo=35922]: Fix RobotFileParser.crawl_delay() and RobotFileParser.request_rate() to return None rather than raise AttributeError when no relevant rule is defined in the robots.txt file. Patch by Rémi Lapeyre.

bpo-35766 [https://bugs.python.org/issue?@action=redirect&bpo=35766]: Change the format of feature_version to be a (major, minor) tuple.

bpo-36607 [https://bugs.python.org/issue?@action=redirect&bpo=36607]: Eliminate RuntimeError raised by asyncio.all_tasks() if internal tasks weak set is changed by another thread during iteration.

bpo-18748 [https://bugs.python.org/issue?@action=redirect&bpo=18748]: _pyio.IOBase destructor now does nothing if getting the closed attribute fails to better mimic _io.IOBase finalizer.

bpo-36402 [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.

bpo-37206 [https://bugs.python.org/issue?@action=redirect&bpo=37206]: Default values which cannot be represented as Python objects no longer improperly represented as None in function signatures.

bpo-37111 [https://bugs.python.org/issue?@action=redirect&bpo=37111]: Added encoding and errors keyword parameters to logging.basicConfig.

bpo-12144 [https://bugs.python.org/issue?@action=redirect&bpo=12144]: Ensure cookies with expires attribute are handled in CookieJar.make_cookies().

bpo-34886 [https://bugs.python.org/issue?@action=redirect&bpo=34886]: Fix an unintended ValueError from subprocess.run() when checking for conflicting input and stdin or capture_output and stdout or stderr args when they were explicitly provided but with None values within a passed in **kwargs dict rather than as passed directly by name. Patch contributed by Rémi Lapeyre.

bpo-37173 [https://bugs.python.org/issue?@action=redirect&bpo=37173]: The exception message for inspect.getfile() now correctly reports the passed class rather than the builtins module.

bpo-37178 [https://bugs.python.org/issue?@action=redirect&bpo=37178]: Give math.perm() a one argument form that means the same as math.factorial().

bpo-37178 [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.

bpo-37165 [https://bugs.python.org/issue?@action=redirect&bpo=37165]: Converted _collections._count_elements to use the Argument Clinic.

bpo-34767 [https://bugs.python.org/issue?@action=redirect&bpo=34767]: Do not always create a collections.deque in asyncio.Lock.

bpo-37158 [https://bugs.python.org/issue?@action=redirect&bpo=37158]: Speed-up statistics.fmean() by switching from a function to a generator.

bpo-34282 [https://bugs.python.org/issue?@action=redirect&bpo=34282]: Remove Enum._convert method, deprecated in 3.8.

bpo-37150 [https://bugs.python.org/issue?@action=redirect&bpo=37150]: argparse._ActionsContainer.add_argument now throws error, if someone accidentally pass FileType class object instead of instance of FileType as type argument.

bpo-28724 [https://bugs.python.org/issue?@action=redirect&bpo=28724]: The socket module now has the socket.send_fds() and socket.recv.fds() methods. Contributed by Joannah Nanjekye, Shinya Okano and Victor Stinner.

bpo-35621 [https://bugs.python.org/issue?@action=redirect&bpo=35621]: Support running asyncio subprocesses when execution event loop in a thread on UNIX.

bpo-36520 [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.

bpo-30835 [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.

bpo-31163 [https://bugs.python.org/issue?@action=redirect&bpo=31163]: pathlib.Path instance's rename and replace methods now return the new Path instance.

bpo-25068 [https://bugs.python.org/issue?@action=redirect&bpo=25068]: urllib.request.ProxyHandler now lowercases the keys of the passed dictionary.

bpo-26185 [https://bugs.python.org/issue?@action=redirect&bpo=26185]: Fix repr() on empty ZipInfo object. Patch by Mickaël Schoentgen.

bpo-21315 [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.

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Port test_datetime to VxWorks: skip zoneinfo tests on VxWorks

bpo-35805 [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.

bpo-36871 [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.

bpo-35070 [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.

bpo-31783 [https://bugs.python.org/issue?@action=redirect&bpo=31783]: Fix race condition in ThreadPoolExecutor when worker threads are created during interpreter shutdown.

bpo-36582 [https://bugs.python.org/issue?@action=redirect&bpo=36582]: Fix UserString.encode() to correctly return bytes rather than a UserString instance.

bpo-32424 [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

bpo-36564 [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

bpo-36543 [https://bugs.python.org/issue?@action=redirect&bpo=36543]: Removed methods Element.getchildren(), Element.getiterator() and ElementTree.getiterator() and the xml.etree.cElementTree module.

bpo-36409 [https://bugs.python.org/issue?@action=redirect&bpo=36409]: Remove the old plistlib API deprecated in Python 3.4

bpo-36302 [https://bugs.python.org/issue?@action=redirect&bpo=36302]: distutils sorts source file lists so that Extension .so files build more reproducibly by default

bpo-36250 [https://bugs.python.org/issue?@action=redirect&bpo=36250]: Ignore ValueError from signal with interaction in non-main thread.

bpo-36046 [https://bugs.python.org/issue?@action=redirect&bpo=36046]: Added user, group and extra_groups parameters to the subprocess.Popen constructor. Patch by Patrick McLean.

bpo-32627 [https://bugs.python.org/issue?@action=redirect&bpo=32627]: Fix compile error when _uuid headers conflicting included.

bpo-35800 [https://bugs.python.org/issue?@action=redirect&bpo=35800]: Deprecate smtpd.MailmanProxy ready for future removal.

bpo-35168 [https://bugs.python.org/issue?@action=redirect&bpo=35168]: shlex.shlex.punctuation_chars is now a read-only property.

bpo-8538 [https://bugs.python.org/issue?@action=redirect&bpo=8538]: Add support for boolean actions like --foo and --no-foo to argparse. Patch contributed by Rémi Lapeyre.

bpo-20504 [https://bugs.python.org/issue?@action=redirect&bpo=20504]: Fixes a bug in cgi module when a multipart/form-data request has no Content-Length header.

bpo-25988 [https://bugs.python.org/issue?@action=redirect&bpo=25988]: The abstract base classes in collections.abc no longer are exposed in the regular collections module.

bpo-11122 [https://bugs.python.org/issue?@action=redirect&bpo=11122]: Distutils won't check for rpmbuild in specified paths only.

bpo-34775 [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.

bpo-34749 [https://bugs.python.org/issue?@action=redirect&bpo=34749]: binascii.a2b_base64() is now up to 2 times faster. Patch by Sergey Fedoseev.

bpo-34519 [https://bugs.python.org/issue?@action=redirect&bpo=34519]: Add additional aliases for HP Roman 8. Patch by Michael Osipov.

bpo-28009 [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.

bpo-30618 [https://bugs.python.org/issue?@action=redirect&bpo=30618]: Add readlink(). Patch by Girts Folkmanis.

bpo-32498 [https://bugs.python.org/issue?@action=redirect&bpo=32498]: Made urllib.parse.unquote() accept bytes in addition to strings. Patch by Stein Karlsen.

bpo-33348 [https://bugs.python.org/issue?@action=redirect&bpo=33348]: lib2to3 now recognizes expressions after * and ** like in f(*[] or []).

bpo-32689 [https://bugs.python.org/issue?@action=redirect&bpo=32689]: Update shutil.move() function to allow for Path objects to be used as source argument. Patch by Emily Morehouse and Maxwell "5.13b" McKinnon.

bpo-32820 [https://bugs.python.org/issue?@action=redirect&bpo=32820]: Added __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.

bpo-27657 [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").

bpo-4963 [https://bugs.python.org/issue?@action=redirect&bpo=4963]: Fixed non-deterministic behavior related to mimetypes extension mapping and module reinitialization.

Documentation

bpo-21767 [https://bugs.python.org/issue?@action=redirect&bpo=21767]: Explicitly mention abc support in functools.singledispatch

bpo-38816 [https://bugs.python.org/issue?@action=redirect&bpo=38816]: Provides more details about the interaction between fork() and CPython's runtime, focusing just on the C-API. This includes cautions about where fork() should and shouldn't be called.

bpo-38351 [https://bugs.python.org/issue?@action=redirect&bpo=38351]: Modernize email examples from %-formatting to f-strings.

bpo-38778 [https://bugs.python.org/issue?@action=redirect&bpo=38778]: Document the fact that RuntimeError is raised if os.fork() is called in a subinterpreter.

bpo-38592 [https://bugs.python.org/issue?@action=redirect&bpo=38592]: Add Brazilian Portuguese to the language switcher at Python Documentation website.

bpo-38294 [https://bugs.python.org/issue?@action=redirect&bpo=38294]: Add list of no-longer-escaped chars to re.escape documentation

bpo-38053 [https://bugs.python.org/issue?@action=redirect&bpo=38053]: Modernized the plistlib documentation

bpo-26868 [https://bugs.python.org/issue?@action=redirect&bpo=26868]: Fix example usage of PyModule_AddObject() to properly handle errors.

bpo-36797 [https://bugs.python.org/issue?@action=redirect&bpo=36797]: Fix a dead link in the distutils API Reference.

bpo-37977 [https://bugs.python.org/issue?@action=redirect&bpo=37977]: Warn more strongly and clearly about pickle insecurity

bpo-37979 [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

bpo-12707 [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

bpo-37937 [https://bugs.python.org/issue?@action=redirect&bpo=37937]: Mention frame.f_trace in sys.settrace() docs.

bpo-37878 [https://bugs.python.org/issue?@action=redirect&bpo=37878]: Make PyThreadState_DeleteCurrent() Internal.

bpo-37759 [https://bugs.python.org/issue?@action=redirect&bpo=37759]: Beginning edits to Whatsnew 3.8

bpo-37726 [https://bugs.python.org/issue?@action=redirect&bpo=37726]: Stop recommending getopt in the tutorial for command line argument parsing and promote argparse.

bpo-32910 [https://bugs.python.org/issue?@action=redirect&bpo=32910]: Remove implementation-specific behaviour of how venv's Deactivate works.

bpo-37256 [https://bugs.python.org/issue?@action=redirect&bpo=37256]: Fix wording of arguments for Request in urllib.request

bpo-37284 [https://bugs.python.org/issue?@action=redirect&bpo=37284]: Add a brief note to indicate that any new sys.implementation required attributes must go through the PEP process.

bpo-30088 [https://bugs.python.org/issue?@action=redirect&bpo=30088]: Documented that mailbox.Maildir constructor doesn't attempt to verify the maildir folder layout correctness. Patch by Sviatoslav Sydorenko.

bpo-37521 [https://bugs.python.org/issue?@action=redirect&bpo=37521]: Fix 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.

bpo-37456 [https://bugs.python.org/issue?@action=redirect&bpo=37456]: Slash ('/') is now part of syntax.

bpo-37487 [https://bugs.python.org/issue?@action=redirect&bpo=37487]: Fix PyList_GetItem index description to include 0.

bpo-37149 [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.

bpo-37478 [https://bugs.python.org/issue?@action=redirect&bpo=37478]: Added possible exceptions to the description of os.chdir().

bpo-34903 [https://bugs.python.org/issue?@action=redirect&bpo=34903]: Documented that in datetime.datetime.strptime(), the leading zero in some two-digit formats is optional. Patch by Mike Gleen.

bpo-36260 [https://bugs.python.org/issue?@action=redirect&bpo=36260]: Add decompression pitfalls to zipfile module documentation.

bpo-37004 [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.

bpo-36960 [https://bugs.python.org/issue?@action=redirect&bpo=36960]: Restructured the datetime docs in the interest of making them more user-friendly and improving readability. Patch by Brad Solomon.

bpo-36487 [https://bugs.python.org/issue?@action=redirect&bpo=36487]: Make C-API docs clear about what the "main" interpreter is.

bpo-23460 [https://bugs.python.org/issue?@action=redirect&bpo=23460]: The documentation for decimal string formatting using the :g specifier has been updated to reflect the correct exponential notation cutoff point. Original patch contributed by Tuomas Suutari.

bpo-35803 [https://bugs.python.org/issue?@action=redirect&bpo=35803]: Document and test that tempfile functions may accept a path-like object for the dir argument. Patch by Anthony Sottile.

bpo-33944 [https://bugs.python.org/issue?@action=redirect&bpo=33944]: Added a note about the intended use of code in .pth files.

bpo-34293 [https://bugs.python.org/issue?@action=redirect&bpo=34293]: Fix the Doc/Makefile regarding PAPER environment variable and PDF builds

bpo-25237 [https://bugs.python.org/issue?@action=redirect&bpo=25237]: Add documentation for tkinter modules

Tests

bpo-38614 [https://bugs.python.org/issue?@action=redirect&bpo=38614]: Fix test_communicate() of test_asyncio.test_subprocess: use support.LONG_TIMEOUT (5 minutes), instead of just 1 minute.

bpo-38614 [https://bugs.python.org/issue?@action=redirect&bpo=38614]: Add timeout constants to test.support: LOOPBACK_TIMEOUT, INTERNET_TIMEOUT, SHORT_TIMEOUT and LONG_TIMEOUT.

bpo-38502 [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 os.setsid() and os.killpg() functions are available.

bpo-35998 [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.

bpo-38470 [https://bugs.python.org/issue?@action=redirect&bpo=38470]: Fix test_compileall.test_compile_dir_maxlevels() on Windows without long path support: only create 3 subdirectories instead of between 20 and 100 subdirectories.

bpo-37531 [https://bugs.python.org/issue?@action=redirect&bpo=37531]: On timeout, regrtest no longer attempts to call 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.

bpo-38239 [https://bugs.python.org/issue?@action=redirect&bpo=38239]: Fix test_gdb for Link Time Optimization (LTO) builds.

bpo-38275 [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.

bpo-38271 [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.

bpo-38270 [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.

bpo-37123 [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.

bpo-38212 [https://bugs.python.org/issue?@action=redirect&bpo=38212]: Multiprocessing tests: increase test_queue_feeder_donot_stop_onexc() timeout from 1 to 60 seconds.

bpo-38117 [https://bugs.python.org/issue?@action=redirect&bpo=38117]: Test with OpenSSL 1.1.1d

bpo-38018 [https://bugs.python.org/issue?@action=redirect&bpo=38018]: Increase code coverage for multiprocessing.shared_memory.

bpo-37805 [https://bugs.python.org/issue?@action=redirect&bpo=37805]: Add tests for json.dump(..., skipkeys=True). Patch by Donghee Na.

bpo-37531 [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().

bpo-37876 [https://bugs.python.org/issue?@action=redirect&bpo=37876]: Add tests for ROT-13 codec.

bpo-36833 [https://bugs.python.org/issue?@action=redirect&bpo=36833]: Added tests for PyDateTime_xxx_GET_xxx() macros of the C API of the datetime module. Patch by Joannah Nanjekye.

bpo-37558 [https://bugs.python.org/issue?@action=redirect&bpo=37558]: Fix test_shared_memory_cleaned_after_process_termination name handling

bpo-37526 [https://bugs.python.org/issue?@action=redirect&bpo=37526]: Add test.support.catch_threading_exception(): context manager catching threading.Thread exception using threading.excepthook().

bpo-37421 [https://bugs.python.org/issue?@action=redirect&bpo=37421]: test_concurrent_futures now explicitly stops the ForkServer instance if it's running.

bpo-37421 [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.

bpo-37421 [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.

bpo-37421 [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().

bpo-37421 [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.

bpo-37421 [https://bugs.python.org/issue?@action=redirect&bpo=37421]: multiprocessing tests now explicitly call _run_finalizers() to immediately remove temporary directories created by tests.

bpo-37421 [https://bugs.python.org/issue?@action=redirect&bpo=37421]: urllib.request tests now call urlcleanup() to remove temporary files created by urlretrieve() tests and to clear the _opener global variable set by urlopen() and functions calling indirectly urlopen().

bpo-37472 [https://bugs.python.org/issue?@action=redirect&bpo=37472]: Remove Lib/test/outstanding_bugs.py.

bpo-37199 [https://bugs.python.org/issue?@action=redirect&bpo=37199]: Fix test failures when IPv6 is unavailable or disabled.

bpo-19696 [https://bugs.python.org/issue?@action=redirect&bpo=19696]: Replace deprecated method "random.choose" with "random.choice" in "test_pkg_import.py".

bpo-37335 [https://bugs.python.org/issue?@action=redirect&bpo=37335]: Remove no longer necessary code from c locale coercion tests

bpo-37421 [https://bugs.python.org/issue?@action=redirect&bpo=37421]: Fix test_shutil to no longer leak temporary files.

bpo-37411 [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).

bpo-37400 [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().

bpo-37359 [https://bugs.python.org/issue?@action=redirect&bpo=37359]: Add --cleanup option to python3 -m test to remove test_python_* directories of previous failed jobs. Add "make cleantest" to run python3 -m test --cleanup.

bpo-37362 [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.

bpo-35998 [https://bugs.python.org/issue?@action=redirect&bpo=35998]: Avoid TimeoutError in test_asyncio: test_start_tls_server_1()

bpo-37278 [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.

bpo-37261 [https://bugs.python.org/issue?@action=redirect&bpo=37261]: Fix test.support.catch_unraisable_exception(): its __exit__() method now ignores unraisable exception raised when clearing its unraisable attribute.

bpo-37069 [https://bugs.python.org/issue?@action=redirect&bpo=37069]: regrtest now uses 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 python3 -m test --fail-env-changed to catch unraisable exceptions in tests.

bpo-37252 [https://bugs.python.org/issue?@action=redirect&bpo=37252]: Fix assertions in test_close and test_events_mask_overflow devpoll tests.

bpo-37169 [https://bugs.python.org/issue?@action=redirect&bpo=37169]: Rewrite _PyObject_IsFreed() unit tests.

bpo-37153 [https://bugs.python.org/issue?@action=redirect&bpo=37153]: test_venv.test_multiprocessing() now explicitly calls pool.terminate() to wait until the pool completes.

bpo-34001 [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.

bpo-36919 [https://bugs.python.org/issue?@action=redirect&bpo=36919]: Make test_source_encoding.test_issue2301 implementation independent. The test will work now for both CPython and IronPython.

bpo-30202 [https://bugs.python.org/issue?@action=redirect&bpo=30202]: Update test.test_importlib.test_abc to test find_spec().

bpo-28009 [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

bpo-34596 [https://bugs.python.org/issue?@action=redirect&bpo=34596]: Fallback to a default reason when unittest.skip() is uncalled. Patch by Naitree Zhu.

Build

bpo-38809 [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.

bpo-38684 [https://bugs.python.org/issue?@action=redirect&bpo=38684]: Fix _hashlib build when Blake2 is disabled, but OpenSSL supports it.

bpo-38468 [https://bugs.python.org/issue?@action=redirect&bpo=38468]: Misc/python-config.in now uses getvar() for all still existing sysconfig.get_config_var() calls. Patch by Joannah Nanjekye.

bpo-37415 [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.

bpo-38301 [https://bugs.python.org/issue?@action=redirect&bpo=38301]: In Solaris family, we must be sure to use -D_REENTRANT. Patch by Jesús Cea Avión.

bpo-36002 [https://bugs.python.org/issue?@action=redirect&bpo=36002]: Locate llvm-profdata and llvm-ar binaries using AC_PATH_TOOL rather than AC_PATH_TARGET_TOOL.

bpo-37936 [https://bugs.python.org/issue?@action=redirect&bpo=37936]: The .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.

bpo-37760 [https://bugs.python.org/issue?@action=redirect&bpo=37760]: The 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 str and by the unicodedata module, now handles each character's data as a dataclass with named attributes, rather than a length-18 list of different fields.

bpo-37936 [https://bugs.python.org/issue?@action=redirect&bpo=37936]: The .gitignore file no longer applies to any files that are in fact tracked in the Git repository. Patch by Greg Price.

bpo-37725 [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".

bpo-37707 [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.

bpo-36044 [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.

bpo-37468 [https://bugs.python.org/issue?@action=redirect&bpo=37468]: make install no longer installs wininst-*.exe files used by distutils bdist_wininst: bdist_wininst only works on Windows.

bpo-37189 [https://bugs.python.org/issue?@action=redirect&bpo=37189]: Many PyRun_XXX() functions like PyRun_String() were no longer exported in libpython38.dll by mistake. Export them again to fix the ABI compatibility.

bpo-25361 [https://bugs.python.org/issue?@action=redirect&bpo=25361]: Enables use of SSE2 instructions in Windows 32-bit build.

bpo-36210 [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

Windows

bpo-38589 [https://bugs.python.org/issue?@action=redirect&bpo=38589]: Fixes HTML Help shortcut when Windows is not installed to C drive

bpo-38453 [https://bugs.python.org/issue?@action=redirect&bpo=38453]: Ensure ntpath.realpath() correctly resolves relative paths.

bpo-38519 [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.

bpo-38492 [https://bugs.python.org/issue?@action=redirect&bpo=38492]: Remove pythonw.exe dependency on the Microsoft C++ runtime.

bpo-38344 [https://bugs.python.org/issue?@action=redirect&bpo=38344]: Fix error message in activate.bat

bpo-38359 [https://bugs.python.org/issue?@action=redirect&bpo=38359]: Ensures pyw.exe launcher reads correct registry key.

bpo-38355 [https://bugs.python.org/issue?@action=redirect&bpo=38355]: Fixes ntpath.realpath failing on sys.executable.

bpo-38117 [https://bugs.python.org/issue?@action=redirect&bpo=38117]: Update bundled OpenSSL to 1.1.1d

bpo-38092 [https://bugs.python.org/issue?@action=redirect&bpo=38092]: Reduce overhead when using multiprocessing in a Windows virtual environment.

bpo-38133 [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.

bpo-38114 [https://bugs.python.org/issue?@action=redirect&bpo=38114]: The pip.ini is no longer included in the Nuget package.

bpo-32592 [https://bugs.python.org/issue?@action=redirect&bpo=32592]: Set Windows 8 as the minimum required version for API support

bpo-36634 [https://bugs.python.org/issue?@action=redirect&bpo=36634]: os.cpu_count() now returns active processors rather than maximum processors.

bpo-36634 [https://bugs.python.org/issue?@action=redirect&bpo=36634]: venv activate.bat now works when the existing variables contain double quote characters.

bpo-38081 [https://bugs.python.org/issue?@action=redirect&bpo=38081]: Prevent error calling os.path.realpath() on 'NUL'.

bpo-38087 [https://bugs.python.org/issue?@action=redirect&bpo=38087]: Fix case sensitivity in test_pathlib and test_ntpath.

bpo-38088 [https://bugs.python.org/issue?@action=redirect&bpo=38088]: Fixes distutils not finding vcruntime140.dll with only the v142 toolset installed.

bpo-37283 [https://bugs.python.org/issue?@action=redirect&bpo=37283]: Ensure command-line and unattend.xml setting override previously detected states in Windows installer.

bpo-38030 [https://bugs.python.org/issue?@action=redirect&bpo=38030]: Fixes os.stat() failing for block devices on Windows

bpo-38020 [https://bugs.python.org/issue?@action=redirect&bpo=38020]: Fixes potential crash when calling os.readlink() (or indirectly through realpath()) on a file that is not a supported link.

bpo-37705 [https://bugs.python.org/issue?@action=redirect&bpo=37705]: Improve the implementation of winerror_to_errno().

bpo-37549 [https://bugs.python.org/issue?@action=redirect&bpo=37549]: os.dup() no longer fails for standard streams on Windows 7.

bpo-1311 [https://bugs.python.org/issue?@action=redirect&bpo=1311]: The nul file on Windows now returns True from exists() and a valid result from os.stat() with S_IFCHR set.

bpo-9949 [https://bugs.python.org/issue?@action=redirect&bpo=9949]: Enable support for following symlinks in os.realpath().

bpo-37834 [https://bugs.python.org/issue?@action=redirect&bpo=37834]: Treat all name surrogate reparse points on Windows in os.lstat() and other reparse points as regular files in os.stat().

bpo-36266 [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 _PyImport_FindSharedFuncptrWindows(). Patch by Srinivas Nyayapati.

bpo-25172 [https://bugs.python.org/issue?@action=redirect&bpo=25172]: Trying to import the crypt module on Windows will result in an ImportError with a message explaining that the module isn't supported on Windows. On other platforms, if the underlying _crypt module is not available, the ImportError will include a message explaining the problem.

bpo-37778 [https://bugs.python.org/issue?@action=redirect&bpo=37778]: Fixes the icons used for file associations to the Microsoft Store package.

bpo-37734 [https://bugs.python.org/issue?@action=redirect&bpo=37734]: Fix use of registry values to launch Python from Microsoft Store app.

bpo-37702 [https://bugs.python.org/issue?@action=redirect&bpo=37702]: Fix memory leak on Windows in creating an SSLContext object or running urllib.request.urlopen('https://...').

bpo-37672 [https://bugs.python.org/issue?@action=redirect&bpo=37672]: Switch Windows Store package's pip to use bundled pip.ini instead of PIP_USER variable.

bpo-10945 [https://bugs.python.org/issue?@action=redirect&bpo=10945]: Officially drop support for creating bdist_wininst installers on non-Windows systems.

bpo-37445 [https://bugs.python.org/issue?@action=redirect&bpo=37445]: Include the FORMAT_MESSAGE_IGNORE_INSERTS flag in FormatMessageW() calls.

bpo-37369 [https://bugs.python.org/issue?@action=redirect&bpo=37369]: Fixes path for sys.executable when running from the Microsoft Store.

bpo-37380 [https://bugs.python.org/issue?@action=redirect&bpo=37380]: Don't collect unfinished processes with subprocess._active on Windows to cleanup later. Patch by Ruslan Kuprieiev.

bpo-37351 [https://bugs.python.org/issue?@action=redirect&bpo=37351]: Removes libpython38.a from standard Windows distribution.

bpo-35360 [https://bugs.python.org/issue?@action=redirect&bpo=35360]: Update Windows builds to use SQLite 3.28.0.

bpo-37267 [https://bugs.python.org/issue?@action=redirect&bpo=37267]: On Windows, os.dup() no longer creates an inheritable fd when handling a character file.

bpo-36779 [https://bugs.python.org/issue?@action=redirect&bpo=36779]: Ensure time.tzname is correct on Windows when the active code page is set to CP_UTF7 or CP_UTF8.

bpo-32587 [https://bugs.python.org/issue?@action=redirect&bpo=32587]: Make winreg.REG_MULTI_SZ support zero-length strings.

bpo-28269 [https://bugs.python.org/issue?@action=redirect&bpo=28269]: Replace use of strcasecmp() for the system function _stricmp(). Patch by Minmin Gong.

bpo-36590 [https://bugs.python.org/issue?@action=redirect&bpo=36590]: Add native Bluetooth RFCOMM support to socket module.

macOS

bpo-38117 [https://bugs.python.org/issue?@action=redirect&bpo=38117]: Updated OpenSSL to 1.1.1d in macOS installer.

bpo-38089 [https://bugs.python.org/issue?@action=redirect&bpo=38089]: Move Azure Pipelines to latest VM versions and make macOS tests optional

bpo-18049 [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.

bpo-34602 [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.

bpo-35360 [https://bugs.python.org/issue?@action=redirect&bpo=35360]: Update macOS installer to use SQLite 3.28.0.

bpo-34631 [https://bugs.python.org/issue?@action=redirect&bpo=34631]: Updated OpenSSL to 1.1.1c in macOS installer.

IDLE

bpo-26353 [https://bugs.python.org/issue?@action=redirect&bpo=26353]: Stop adding newline when saving an IDLE shell window.

bpo-4630 [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.

bpo-38598 [https://bugs.python.org/issue?@action=redirect&bpo=38598]: Do not try to compile IDLE shell or output windows

bpo-36698 [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 errors field to the standard streams.

bpo-35379 [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.

bpo-38183 [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.

bpo-38077 [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.

bpo-38041 [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.

bpo-35771 [https://bugs.python.org/issue?@action=redirect&bpo=35771]: To avoid occasional spurious test_idle failures on slower machines, increase the hover_delay in test_tooltip.

bpo-37824 [https://bugs.python.org/issue?@action=redirect&bpo=37824]: Properly handle user input warnings in IDLE shell. Cease turning SyntaxWarnings into SyntaxErrors.

bpo-37929 [https://bugs.python.org/issue?@action=redirect&bpo=37929]: IDLE Settings dialog now closes properly when there is no shell window.

bpo-37902 [https://bugs.python.org/issue?@action=redirect&bpo=37902]: Add mousewheel scrolling for IDLE module, path, and stack browsers. Patch by George Zhang.

bpo-37849 [https://bugs.python.org/issue?@action=redirect&bpo=37849]: Fixed completions list appearing too high or low when shown above the current line.

bpo-36419 [https://bugs.python.org/issue?@action=redirect&bpo=36419]: Refactor IDLE autocomplete and improve testing.

bpo-37748 [https://bugs.python.org/issue?@action=redirect&bpo=37748]: Reorder the Run menu. Put the most common choice, Run Module, at the top.

bpo-37692 [https://bugs.python.org/issue?@action=redirect&bpo=37692]: Improve highlight config sample with example shell interaction and better labels for shell elements.

bpo-37628 [https://bugs.python.org/issue?@action=redirect&bpo=37628]: Settings dialog no longer expands with font size.

bpo-37627 [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.

bpo-33610 [https://bugs.python.org/issue?@action=redirect&bpo=33610]: Fix code context not showing the correct context when first toggled on.

bpo-37530 [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.

bpo-27452 [https://bugs.python.org/issue?@action=redirect&bpo=27452]: Cleanup config.py by inlining RemoveFile and simplifying the handling of file in CreateConfigHandlers.

bpo-37325 [https://bugs.python.org/issue?@action=redirect&bpo=37325]: Fix tab focus traversal order for help source and custom run dialogs.

bpo-37321 [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.

bpo-17535 [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.

bpo-26806 [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.

bpo-37177 [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.

bpo-37039 [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.

bpo-35763 [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.

bpo-5680 [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.

bpo-36390 [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.

Tools/Demos

bpo-38118 [https://bugs.python.org/issue?@action=redirect&bpo=38118]: Update Valgrind suppression file to ignore a false alarm in PyUnicode_Decode() when using GCC builtin strcmp().

bpo-38347 [https://bugs.python.org/issue?@action=redirect&bpo=38347]: pathfix.py: Assume all files that end on '.py' are Python scripts when working recursively.

bpo-37803 [https://bugs.python.org/issue?@action=redirect&bpo=37803]: pdb's --help and --version long options now work.

bpo-37942 [https://bugs.python.org/issue?@action=redirect&bpo=37942]: Improve ArgumentClinic converter for floats.

bpo-37704 [https://bugs.python.org/issue?@action=redirect&bpo=37704]: Remove Tools/scripts/h2py.py: use cffi to access a C API in Python.

bpo-37675 [https://bugs.python.org/issue?@action=redirect&bpo=37675]: 2to3 now works when run from a zipped standard library.

bpo-37034 [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.

bpo-37064 [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.

C API

bpo-37633 [https://bugs.python.org/issue?@action=redirect&bpo=37633]: Re-export some function compatibility wrappers for macros in pythonrun.h.

bpo-38644 [https://bugs.python.org/issue?@action=redirect&bpo=38644]: Provide Py_EnterRecursiveCall() and 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 PyThreadState.recursion_depth field. Remove _Py_CheckRecursionLimit from the stable ABI.

bpo-38650 [https://bugs.python.org/issue?@action=redirect&bpo=38650]: The global variable PyStructSequence_UnnamedField is now a constant and refers to a constant string.

bpo-38540 [https://bugs.python.org/issue?@action=redirect&bpo=38540]: Fixed possible leak in PyArg_Parse() and similar functions for format units "es#" and "et#" when the macro PY_SSIZE_T_CLEAN is not defined.

bpo-38395 [https://bugs.python.org/issue?@action=redirect&bpo=38395]: Fix a crash in 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.

bpo-36389 [https://bugs.python.org/issue?@action=redirect&bpo=36389]: The _PyObject_CheckConsistency() function is now also available in release mode. For example, it can be used to debug a crash in the visit_decref() function of the GC.

bpo-38266 [https://bugs.python.org/issue?@action=redirect&bpo=38266]: Revert the removal of PyThreadState_DeleteCurrent() with documentation.

bpo-38303 [https://bugs.python.org/issue?@action=redirect&bpo=38303]: Update audioop extension module to use the stable ABI (PEP-384). Patch by Tyler Kieft.

bpo-38234 [https://bugs.python.org/issue?@action=redirect&bpo=38234]: Py_SetPath() now sets sys.executable to the program full path (Py_GetProgramFullPath()) rather than to the program name (Py_GetProgramName()).

bpo-38234 [https://bugs.python.org/issue?@action=redirect&bpo=38234]: Python ignored arguments passed to Py_SetPath(), Py_SetPythonHome() and Py_SetProgramName(): fix Python initialization to use specified arguments.

bpo-38205 [https://bugs.python.org/issue?@action=redirect&bpo=38205]: The Py_UNREACHABLE() macro now calls Py_FatalError().

bpo-38140 [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

bpo-15088 [https://bugs.python.org/issue?@action=redirect&bpo=15088]: The C function PyGen_NeedsFinalizing has been removed. It was not documented, tested or used anywhere within CPython after the implementation of PEP 442 [https://peps.python.org/pep-0442/]. Patch by Joannah Nanjekye. (Patch by Joannah Nanjekye)

bpo-36763 [https://bugs.python.org/issue?@action=redirect&bpo=36763]: Options added by PySys_AddXOption() are now handled the same way than PyConfig.xoptions and command line -X options.

bpo-37926 [https://bugs.python.org/issue?@action=redirect&bpo=37926]: Fix a crash in PySys_SetArgvEx(0, NULL, 0).

bpo-37879 [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

bpo-37645 [https://bugs.python.org/issue?@action=redirect&bpo=37645]: Add _PyObject_FunctionStr() to get a user-friendly string representation of a function-like object. Patch by Jeroen Demeyer.

bpo-29548 [https://bugs.python.org/issue?@action=redirect&bpo=29548]: The functions PyEval_CallObject, PyEval_CallFunction, PyEval_CallMethod and PyEval_CallObjectWithKeywords are deprecated. Use PyObject_Call() and its variants instead.

bpo-37151 [https://bugs.python.org/issue?@action=redirect&bpo=37151]: PyCFunction_Call is now a deprecated alias of PyObject_Call().

bpo-37540 [https://bugs.python.org/issue?@action=redirect&bpo=37540]: The vectorcall protocol now requires that the caller passes only strings as keyword names.

bpo-37207 [https://bugs.python.org/issue?@action=redirect&bpo=37207]: The vectorcall protocol is now enabled for type objects: set tp_vectorcall to a vectorcall function to be used instead of tp_new and tp_init when calling the class itself.

bpo-21120 [https://bugs.python.org/issue?@action=redirect&bpo=21120]: Exclude Python-ast.h, ast.h and asdl.h from the limited API.

bpo-37483 [https://bugs.python.org/issue?@action=redirect&bpo=37483]: Add new function _PyObject_CallOneArg for calling an object with one positional argument.

bpo-36763 [https://bugs.python.org/issue?@action=redirect&bpo=36763]: Add PyConfig_SetWideStringList() function.

bpo-37337 [https://bugs.python.org/issue?@action=redirect&bpo=37337]: Add fast functions for calling methods: _PyObject_VectorcallMethod(), _PyObject_CallMethodNoArgs() and _PyObject_CallMethodOneArg().

bpo-28805 [https://bugs.python.org/issue?@action=redirect&bpo=28805]: The METH_FASTCALL calling convention has been documented.

bpo-37221 [https://bugs.python.org/issue?@action=redirect&bpo=37221]: The new function PyCode_NewWithPosOnlyArgs() allows to create code objects like PyCode_New(), but with an extra posonlyargcount parameter for indicating the number of positonal-only arguments.

bpo-37215 [https://bugs.python.org/issue?@action=redirect&bpo=37215]: Fix dtrace issue introduce by bpo-36842 [https://bugs.python.org/issue?@action=redirect&bpo=36842]

bpo-37194 [https://bugs.python.org/issue?@action=redirect&bpo=37194]: Add a new public 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, PyObject_CallFunctionObjArgs(func, NULL) allocates 960 bytes on the stack per call, whereas PyObject_CallNoArgs(func) only allocates 624 bytes per call.

bpo-37170 [https://bugs.python.org/issue?@action=redirect&bpo=37170]: Fix the cast on error in PyLong_AsUnsignedLongLongMask().

bpo-35381 [https://bugs.python.org/issue?@action=redirect&bpo=35381]: Convert posixmodule.c statically allocated types DirEntryType and ScandirIteratorType to heap-allocated types.

bpo-34331 [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).

Python 3.8.0 beta 1

Release date: 2019-06-04

Security

bpo-35907 [https://bugs.python.org/issue?@action=redirect&bpo=35907]: CVE-2019-9948 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-9948]: Avoid file reading by disallowing local-file:// and local_file:// URL schemes in URLopener().open() and URLopener().retrieve() of urllib.request.

bpo-33529 [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.

bpo-33164 [https://bugs.python.org/issue?@action=redirect&bpo=33164]: Updated blake2 implementation which uses secure memset implementation provided by platform.

Core and Builtins

bpo-35814 [https://bugs.python.org/issue?@action=redirect&bpo=35814]: Allow unpacking in the right hand side of annotated assignments. In particular, t: Tuple[int, ...] = x, y, *z is now allowed.

bpo-37126 [https://bugs.python.org/issue?@action=redirect&bpo=37126]: All structseq objects are now tracked by the garbage collector. Patch by Pablo Galindo.

bpo-37122 [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.

bpo-20092 [https://bugs.python.org/issue?@action=redirect&bpo=20092]: Constructors of int, float and complex will now use the __index__() special method, if available and the corresponding method __int__(), __float__() or __complex__() is not available.

bpo-37087 [https://bugs.python.org/issue?@action=redirect&bpo=37087]: Add native thread ID (TID) support to OpenBSD.

bpo-26219 [https://bugs.python.org/issue?@action=redirect&bpo=26219]: Implemented per opcode cache mechanism and LOAD_GLOBAL instruction use it. LOAD_GLOBAL is now about 40% faster. Contributed by Yury Selivanov, and Inada Naoki.

bpo-37072 [https://bugs.python.org/issue?@action=redirect&bpo=37072]: Fix crash in PyAST_FromNodeObject() when flags is NULL.

bpo-37029 [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 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.

bpo-26423 [https://bugs.python.org/issue?@action=redirect&bpo=26423]: Fix possible overflow in wrap_lenfunc() when sizeof(long) < sizeof(Py_ssize_t) (e.g., 64-bit Windows).

bpo-37050 [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).

bpo-22385 [https://bugs.python.org/issue?@action=redirect&bpo=22385]: The bytes.hex, bytearray.hex, and memoryview.hex methods as well as the binascii.hexlify and b2a_hex functions now have the ability to include an optional separator between hex bytes. This functionality was inspired by MicroPython's hexlify implementation.

bpo-26836 [https://bugs.python.org/issue?@action=redirect&bpo=26836]: Add os.memfd_create().

bpo-37032 [https://bugs.python.org/issue?@action=redirect&bpo=37032]: Added new replace() method to the code type (types.CodeType).

bpo-37007 [https://bugs.python.org/issue?@action=redirect&bpo=37007]: Implement socket.if_nameindex(), socket.if_nametoindex(), and socket.if_indextoname() on Windows.

bpo-36829 [https://bugs.python.org/issue?@action=redirect&bpo=36829]: PyErr_WriteUnraisable() now creates a traceback object if there is no current traceback. Moreover, call PyErr_NormalizeException() and PyException_SetTraceback() to normalize the exception value. Ignore any error.

bpo-36878 [https://bugs.python.org/issue?@action=redirect&bpo=36878]: Only accept text after # type: ignore if the first character is ASCII. This is to disallow things like # type: ignoreé.

bpo-36878 [https://bugs.python.org/issue?@action=redirect&bpo=36878]: Store text appearing after a # type: ignore comment in the AST. For example a type ignore like # type: ignore[E1000] will have the string "[E1000]" stored in its AST node.

bpo-2180 [https://bugs.python.org/issue?@action=redirect&bpo=2180]: Treat line continuation at EOF as a SyntaxError by Anthony Sottile.

bpo-36907 [https://bugs.python.org/issue?@action=redirect&bpo=36907]: Fix a crash when calling a C function with a keyword dict (f(**kwargs)) and changing the dict kwargs while that function is running.

bpo-36946 [https://bugs.python.org/issue?@action=redirect&bpo=36946]: Fix possible signed integer overflow when handling slices.

bpo-36826 [https://bugs.python.org/issue?@action=redirect&bpo=36826]: Add NamedExpression kind support to ast_unparse.c

bpo-1875 [https://bugs.python.org/issue?@action=redirect&bpo=1875]: A 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.

bpo-36027 [https://bugs.python.org/issue?@action=redirect&bpo=36027]: Allow computation of modular inverses via three-argument pow: the second argument is now permitted to be negative in the case where the first and third arguments are relatively prime.

bpo-36861 [https://bugs.python.org/issue?@action=redirect&bpo=36861]: Update the Unicode database to version 12.1.0.

bpo-28866 [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.

bpo-36851 [https://bugs.python.org/issue?@action=redirect&bpo=36851]: The FrameType stack is now correctly cleaned up if the execution ends with a return and the stack is not empty.

bpo-34616 [https://bugs.python.org/issue?@action=redirect&bpo=34616]: The compile() builtin functions now support the ast.PyCF_ALLOW_TOP_LEVEL_AWAIT flag, which allow to compile sources that contains top-level await, async with or async for. This is useful to evaluate async-code from with an already async functions; for example in a custom REPL.

bpo-36842 [https://bugs.python.org/issue?@action=redirect&bpo=36842]: Implement PEP 578, adding sys.audit, io.open_code and related APIs.

bpo-27639 [https://bugs.python.org/issue?@action=redirect&bpo=27639]: Correct return type for UserList slicing operations. Patch by Michael Blahay, Erick Cervantes, and vaultah

bpo-36737 [https://bugs.python.org/issue?@action=redirect&bpo=36737]: Move PyRuntimeState.warnings into per-interpreter state (via "module state").

bpo-36793 [https://bugs.python.org/issue?@action=redirect&bpo=36793]: Removed __str__ implementations from builtin types bool, int, float, complex and few classes from the standard library. They now inherit __str__() from object.

bpo-36817 [https://bugs.python.org/issue?@action=redirect&bpo=36817]: Add a = feature f-strings for debugging. This can precede !s, !r, or !a. It produces the text of the expression, followed by an equal sign, followed by the repr of the value of the expression. So f'{3*9+15=}' would be equal to the string '3*9+15=42'. If = is specified, the default conversion is set to !r, unless a format spec is given, in which case the formatting behavior is unchanged, and __format__ will be used.

bpo-24048 [https://bugs.python.org/issue?@action=redirect&bpo=24048]: Save the live exception during import.c's remove_module().

bpo-27987 [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.

bpo-36601 [https://bugs.python.org/issue?@action=redirect&bpo=36601]: A long-since-meaningless check for getpid() == main_pid was removed from Python's internal C signal handler.

bpo-36594 [https://bugs.python.org/issue?@action=redirect&bpo=36594]: Fix incorrect use of %p in format strings. Patch by Zackery Spytz.

bpo-36045 [https://bugs.python.org/issue?@action=redirect&bpo=36045]: builtins.help() now prefixes async for async functions.

bpo-36084 [https://bugs.python.org/issue?@action=redirect&bpo=36084]: Add native thread ID (TID) to threading.Thread objects (supported platforms: Windows, FreeBSD, Linux, macOS)

bpo-36035 [https://bugs.python.org/issue?@action=redirect&bpo=36035]: Added fix for broken symlinks in combination with pathlib

bpo-35983 [https://bugs.python.org/issue?@action=redirect&bpo=35983]: Added new trashcan macros to deal with a double deallocation that could occur when the tp_dealloc of a subclass calls the tp_dealloc of a base class and that base class uses the trashcan mechanism. Patch by Jeroen Demeyer.

bpo-20602 [https://bugs.python.org/issue?@action=redirect&bpo=20602]: Do not clear sys.flags and sys.float_info during shutdown. Patch by Zackery Spytz.

bpo-26826 [https://bugs.python.org/issue?@action=redirect&bpo=26826]: Expose copy_file_range() as a low level API in the os module.

bpo-32388 [https://bugs.python.org/issue?@action=redirect&bpo=32388]: Remove cross-version binary compatibility requirement in tp_flags.

bpo-31862 [https://bugs.python.org/issue?@action=redirect&bpo=31862]: Port binascii to PEP 489 multiphase initialization. Patch by Marcel Plch.

Library

bpo-37128 [https://bugs.python.org/issue?@action=redirect&bpo=37128]: Added math.perm().

bpo-37120 [https://bugs.python.org/issue?@action=redirect&bpo=37120]: Add SSLContext.num_tickets to control the number of TLSv1.3 session tickets.

bpo-12202 [https://bugs.python.org/issue?@action=redirect&bpo=12202]: Fix the error handling in msilib.SummaryInformation.GetProperty(). Patch by Zackery Spytz.

bpo-26835 [https://bugs.python.org/issue?@action=redirect&bpo=26835]: The fcntl module now contains file sealing constants for sealing of memfds.

bpo-29262 [https://bugs.python.org/issue?@action=redirect&bpo=29262]: Add get_origin() and get_args() introspection helpers to typing module.

bpo-12639 [https://bugs.python.org/issue?@action=redirect&bpo=12639]: msilib.Directory.start_component() no longer fails if keyfile is not None.

bpo-36999 [https://bugs.python.org/issue?@action=redirect&bpo=36999]: Add the asyncio.Task.get_coro() method to publicly expose the tasks's coroutine object.

bpo-35246 [https://bugs.python.org/issue?@action=redirect&bpo=35246]: Make asyncio.create_subprocess_exec() accept path-like arguments.

bpo-35279 [https://bugs.python.org/issue?@action=redirect&bpo=35279]: Change default max_workers of ThreadPoolExecutor from cpu_count() * 5 to min(32, cpu_count() + 4). Previous value was unreasonably large on many cores machines.

bpo-37076 [https://bugs.python.org/issue?@action=redirect&bpo=37076]: _thread.start_new_thread() now logs uncaught exception raised by the function using sys.unraisablehook(), rather than sys.excepthook(), so the hook gets access to the function which raised the exception.

bpo-33725 [https://bugs.python.org/issue?@action=redirect&bpo=33725]: On macOS, the multiprocessing module now uses spawn start method by default.

bpo-37054 [https://bugs.python.org/issue?@action=redirect&bpo=37054]: Fix destructor _pyio.BytesIO and _pyio.TextIOWrapper: initialize their _buffer attribute as soon as possible (in the class body), because it's used by __del__() which calls close().

bpo-37058 [https://bugs.python.org/issue?@action=redirect&bpo=37058]: PEP 544: Add Protocol and @runtime_checkable to the typing module.

bpo-36933 [https://bugs.python.org/issue?@action=redirect&bpo=36933]: The functions sys.set_coroutine_wrapper and sys.get_coroutine_wrapper that were deprecated and marked for removal in 3.8 have been removed.

bpo-37047 [https://bugs.python.org/issue?@action=redirect&bpo=37047]: Handle late binding and attribute access in unittest.mock.AsyncMock setup for autospeccing. Document newly implemented async methods in unittest.mock.MagicMock.

bpo-37049 [https://bugs.python.org/issue?@action=redirect&bpo=37049]: PEP 589: Add TypedDict to the typing module.

bpo-37046 [https://bugs.python.org/issue?@action=redirect&bpo=37046]: PEP 586: Add Literal to the typing module.

bpo-37045 [https://bugs.python.org/issue?@action=redirect&bpo=37045]: PEP 591: Add Final qualifier and @final decorator to the typing module.

bpo-37035 [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.

bpo-37001 [https://bugs.python.org/issue?@action=redirect&bpo=37001]: symtable.symtable() now accepts the same input types for source code as the built-in compile() function. Patch by Dino Viehland.

bpo-37028 [https://bugs.python.org/issue?@action=redirect&bpo=37028]: Implement asyncio REPL

bpo-37027 [https://bugs.python.org/issue?@action=redirect&bpo=37027]: Return safe to use proxy socket object from transport.get_extra_info('socket')

bpo-32528 [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.

bpo-1230540 [https://bugs.python.org/issue?@action=redirect&bpo=1230540]: Add a new threading.excepthook() function which handles uncaught threading.Thread.run() exception. It can be overridden to control how uncaught threading.Thread.run() exceptions are handled.

bpo-36996 [https://bugs.python.org/issue?@action=redirect&bpo=36996]: Handle unittest.mock.patch() used as a decorator on async functions.

bpo-37008 [https://bugs.python.org/issue?@action=redirect&bpo=37008]: Add support for calling next() with the mock resulting from unittest.mock.mock_open()

bpo-27737 [https://bugs.python.org/issue?@action=redirect&bpo=27737]: Allow whitespace only header encoding in email.header - by Batuhan Taskaya

bpo-36969 [https://bugs.python.org/issue?@action=redirect&bpo=36969]: PDB command args now display positional only arguments. Patch contributed by Rémi Lapeyre.

bpo-36969 [https://bugs.python.org/issue?@action=redirect&bpo=36969]: PDB command args now display keyword only arguments. Patch contributed by Rémi Lapeyre.

bpo-36983 [https://bugs.python.org/issue?@action=redirect&bpo=36983]: Add missing names to typing.__all__: ChainMap, ForwardRef, OrderedDict - by Anthony Sottile.

bpo-36972 [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 hex(), oct() and bin().

bpo-32972 [https://bugs.python.org/issue?@action=redirect&bpo=32972]: Implement unittest.IsolatedAsyncioTestCase to help testing asyncio-based code.

bpo-36952 [https://bugs.python.org/issue?@action=redirect&bpo=36952]: fileinput.input() and 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.

bpo-36952 [https://bugs.python.org/issue?@action=redirect&bpo=36952]: Starting with Python 3.3, importing ABCs from collections is deprecated, and import should be done from collections.abc. Still being able to import from collections was marked for removal in 3.8, but has been delayed to 3.9; documentation and DeprecationWarning clarified.

bpo-36949 [https://bugs.python.org/issue?@action=redirect&bpo=36949]: Implement __repr__ for WeakSet objects.

bpo-36948 [https://bugs.python.org/issue?@action=redirect&bpo=36948]: Fix NameError in urllib.request.URLopener.retrieve(). Patch by Karthikeyan Singaravelan.

bpo-33524 [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).

bpo-24564 [https://bugs.python.org/issue?@action=redirect&bpo=24564]: shutil.copystat() now ignores errno.EINVAL on os.setxattr() which may occur when copying files on filesystems without extended attributes support.

Original patch by Giampaolo Rodola, updated by Ying Wang.

bpo-36888 [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

bpo-36921 [https://bugs.python.org/issue?@action=redirect&bpo=36921]: Deprecate @coroutine for sake of async def.

bpo-25652 [https://bugs.python.org/issue?@action=redirect&bpo=25652]: Fix bug in __rmod__ of UserString - by Batuhan Taskaya.

bpo-36916 [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.

bpo-36889 [https://bugs.python.org/issue?@action=redirect&bpo=36889]: Introduce asyncio.Stream class that merges asyncio.StreamReader and asyncio.StreamWriter functionality. asyncio.Stream can work in readonly, writeonly and readwrite modes. Provide asyncio.connect(), asyncio.connect_unix(), asyncio.connect_read_pipe() and asyncio.connect_write_pipe() factories to open asyncio.Stream connections. Provide asyncio.StreamServer and UnixStreamServer to serve servers with asyncio.Stream API. Modify asyncio.create_subprocess_shell() and asyncio.create_subprocess_exec() to use asyncio.Stream instead of deprecated StreamReader and StreamWriter. Deprecate asyncio.StreamReader and asyncio.StreamWriter. Deprecate usage of private classes, e.g. asyncio.FlowControlMixing and asyncio.StreamReaderProtocol outside of asyncio package.

bpo-36845 [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.

bpo-23378 [https://bugs.python.org/issue?@action=redirect&bpo=23378]: Add an extend action to argparser.

bpo-36867 [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.

bpo-23896 [https://bugs.python.org/issue?@action=redirect&bpo=23896]: Adds a grammar to lib2to3.pygram that contains exec as a function not as statement.

bpo-36895 [https://bugs.python.org/issue?@action=redirect&bpo=36895]: The function time.clock() was deprecated in 3.3 in favor of time.perf_counter() and marked for removal in 3.8, it has removed.

bpo-35545 [https://bugs.python.org/issue?@action=redirect&bpo=35545]: Fix asyncio discarding IPv6 scopes when ensuring hostname resolutions internally

bpo-36887 [https://bugs.python.org/issue?@action=redirect&bpo=36887]: Add new function math.isqrt() to compute integer square roots.

bpo-34632 [https://bugs.python.org/issue?@action=redirect&bpo=34632]: Introduce the importlib.metadata module with (provisional) support for reading metadata from third-party packages.

bpo-36878 [https://bugs.python.org/issue?@action=redirect&bpo=36878]: When using type_comments=True in ast.parse, treat # 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 # type: ignore[E1000].

bpo-36778 [https://bugs.python.org/issue?@action=redirect&bpo=36778]: cp65001 encoding (Windows code page 65001) becomes an alias to utf_8 encoding.

bpo-36867 [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.

bpo-30262 [https://bugs.python.org/issue?@action=redirect&bpo=30262]: The Cache and Statement objects of the sqlite3 module are not exposed to the user. Patch by Aviv Palivoda.

bpo-24538 [https://bugs.python.org/issue?@action=redirect&bpo=24538]: In 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.

bpo-36829 [https://bugs.python.org/issue?@action=redirect&bpo=36829]: Add new 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 (gc.collect()).

bpo-36832 [https://bugs.python.org/issue?@action=redirect&bpo=36832]: Introducing zipfile.Path, a pathlib-compatible wrapper for traversing zip files.

bpo-36814 [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.

bpo-33110 [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.

bpo-26903 [https://bugs.python.org/issue?@action=redirect&bpo=26903]: Limit max_workers in ProcessPoolExecutor to 61 to work around a WaitForMultipleObjects limitation.

bpo-36813 [https://bugs.python.org/issue?@action=redirect&bpo=36813]: Fix QueueListener to call queue.task_done() upon stopping. Patch by Bar Harel.

bpo-36806 [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.

bpo-36802 [https://bugs.python.org/issue?@action=redirect&bpo=36802]: Provide both sync and async calls for StreamWriter.write() and StreamWriter.close()

bpo-36801 [https://bugs.python.org/issue?@action=redirect&bpo=36801]: Properly handle SSL connection closing in asyncio StreamWriter.drain() call.

bpo-36785 [https://bugs.python.org/issue?@action=redirect&bpo=36785]: Implement PEP 574 (pickle protocol 5 with out-of-band buffers).

bpo-36772 [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.

bpo-6584 [https://bugs.python.org/issue?@action=redirect&bpo=6584]: Add a BadGzipFile exception to the gzip module.

bpo-36748 [https://bugs.python.org/issue?@action=redirect&bpo=36748]: Optimized write buffering in C implementation of TextIOWrapper. Writing ASCII string to TextIOWrapper with ascii, latin1, or utf-8 encoding is about 20% faster. Patch by Inada Naoki.

bpo-8138 [https://bugs.python.org/issue?@action=redirect&bpo=8138]: Don't mark wsgiref.simple_server.SimpleServer as multi-threaded since wsgiref.simple_server.WSGIServer is single-threaded.

bpo-22640 [https://bugs.python.org/issue?@action=redirect&bpo=22640]: py_compile.compile() now supports silent mode. Patch by Joannah Nanjekye

bpo-29183 [https://bugs.python.org/issue?@action=redirect&bpo=29183]: Fix double exceptions in wsgiref.handlers.BaseHandler by calling its close() method only when no exception is raised.

bpo-36548 [https://bugs.python.org/issue?@action=redirect&bpo=36548]: Improved the repr of regular expression flags.

bpo-36542 [https://bugs.python.org/issue?@action=redirect&bpo=36542]: The signature of Python functions can now be overridden by specifying the __text_signature__ attribute.

bpo-36533 [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.

bpo-35252 [https://bugs.python.org/issue?@action=redirect&bpo=35252]: Throw a TypeError instead of an AssertionError when using an invalid type annotation with singledispatch.

bpo-35900 [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 __setstate__ method.

bpo-35900 [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 reducer_override

bpo-36368 [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

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Fix mmap fail for VxWorks

bpo-27497 [https://bugs.python.org/issue?@action=redirect&bpo=27497]: csv.DictWriter.writeheader() now returns the return value of the underlying csv.Writer.writerow() method. Patch contributed by Ashish Nitin Patil.

bpo-36239 [https://bugs.python.org/issue?@action=redirect&bpo=36239]: Parsing .mo files now ignores comments starting and ending with #-#-#-#-#.

bpo-26707 [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.

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Add posix module support for VxWorks.

bpo-35125 [https://bugs.python.org/issue?@action=redirect&bpo=35125]: Asyncio: Remove inner callback on outer cancellation in shield

bpo-35721 [https://bugs.python.org/issue?@action=redirect&bpo=35721]: Fix asyncio.SelectorEventLoop.subprocess_exec() leaks file descriptors if Popen fails and called with stdin=subprocess.PIPE. Patch by Niklas Fiekas.

bpo-31855 [https://bugs.python.org/issue?@action=redirect&bpo=31855]: unittest.mock.mock_open() results now respects the argument of read([size]). Patch contributed by Rémi Lapeyre.

bpo-35431 [https://bugs.python.org/issue?@action=redirect&bpo=35431]: Implement 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.

bpo-26660 [https://bugs.python.org/issue?@action=redirect&bpo=26660]: Fixed permission errors in TemporaryDirectory clean up. Previously TemporaryDirectory.cleanup() failed when non-writeable or non-searchable files or directories were created inside a temporary directory.

bpo-34271 [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.

bpo-26467 [https://bugs.python.org/issue?@action=redirect&bpo=26467]: Added AsyncMock to support using unittest to mock asyncio coroutines. Patch by Lisa Roach.

bpo-33569 [https://bugs.python.org/issue?@action=redirect&bpo=33569]: dataclasses.InitVar: Exposes the type used to create the init var.

bpo-34424 [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.

bpo-34303 [https://bugs.python.org/issue?@action=redirect&bpo=34303]: Performance of functools.reduce() is slightly improved. Patch by Sergey Fedoseev.

bpo-33361 [https://bugs.python.org/issue?@action=redirect&bpo=33361]: Fix a bug in codecs.StreamRecoder where seeking might leave old data in a buffer and break subsequent read calls. Patch by Ammar Askar.

bpo-22454 [https://bugs.python.org/issue?@action=redirect&bpo=22454]: The shlex module now exposes shlex.join(), the inverse of shlex.split(). Patch by Bo Bayles.

bpo-31922 [https://bugs.python.org/issue?@action=redirect&bpo=31922]: asyncio.AbstractEventLoop.create_datagram_endpoint(): Do not connect UDP socket when broadcast is allowed. This allows to receive replies after a UDP broadcast.

bpo-24882 [https://bugs.python.org/issue?@action=redirect&bpo=24882]: Change ThreadPoolExecutor to use existing idle threads before spinning up new ones.

bpo-31961 [https://bugs.python.org/issue?@action=redirect&bpo=31961]: Added support for bytes and path-like objects in subprocess.Popen() on Windows. The args parameter now accepts a path-like object if shell is False and a sequence containing bytes and path-like objects. The executable parameter now accepts a bytes and path-like object. The cwd parameter now accepts a bytes object. Based on patch by Anders Lorentsen.

bpo-33123 [https://bugs.python.org/issue?@action=redirect&bpo=33123]: pathlib.Path.unlink now accepts a missing_ok parameter to avoid a FileNotFoundError from being raised. Patch by Robert Buchholz.

bpo-32941 [https://bugs.python.org/issue?@action=redirect&bpo=32941]: Allow mmap.mmap objects to access the madvise() system call (through mmap.mmap.madvise()).

bpo-22102 [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.

bpo-32515 [https://bugs.python.org/issue?@action=redirect&bpo=32515]: trace.py can now run modules via python3 -m trace -t --module module_name

bpo-32299 [https://bugs.python.org/issue?@action=redirect&bpo=32299]: Changed unittest.mock.patch.dict() to return the patched dictionary when used as context manager. Patch by Vadim Tsander.

bpo-27141 [https://bugs.python.org/issue?@action=redirect&bpo=27141]: Added a __copy__() to collections.UserList and collections.UserDict in order to correctly implement shallow copying of the objects. Patch by Bar Harel.

bpo-31829 [https://bugs.python.org/issue?@action=redirect&bpo=31829]: \r, \0 and \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.

bpo-23395 [https://bugs.python.org/issue?@action=redirect&bpo=23395]: _thread.interrupt_main() now avoids setting the Python error status if the SIGINT signal is ignored or not handled by Python.

Documentation

bpo-36896 [https://bugs.python.org/issue?@action=redirect&bpo=36896]: Clarify that some types have unstable constructor signature between Python versions.

bpo-36686 [https://bugs.python.org/issue?@action=redirect&bpo=36686]: Improve documentation of the stdin, stdout, and stderr arguments of the 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.

bpo-36984 [https://bugs.python.org/issue?@action=redirect&bpo=36984]: Improve version added references in typing module - by Anthony Sottile.

bpo-36868 [https://bugs.python.org/issue?@action=redirect&bpo=36868]: What's new now mentions SSLContext.hostname_checks_common_name instead of SSLContext.host_flags.

bpo-35924 [https://bugs.python.org/issue?@action=redirect&bpo=35924]: Add a note to the curses.addstr() documentation to warn that multiline strings can cause segfaults because of an ncurses bug.

bpo-36783 [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.

bpo-36797 [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.

bpo-22865 [https://bugs.python.org/issue?@action=redirect&bpo=22865]: Add detail to the documentation on the pty.spawn function.

bpo-35397 [https://bugs.python.org/issue?@action=redirect&bpo=35397]: Remove deprecation and document urllib.parse.unwrap(). Patch contributed by Rémi Lapeyre.

bpo-32995 [https://bugs.python.org/issue?@action=redirect&bpo=32995]: Added the context variable in glossary.

bpo-33519 [https://bugs.python.org/issue?@action=redirect&bpo=33519]: Clarify that copy() is not part of the MutableSequence ABC.

bpo-33482 [https://bugs.python.org/issue?@action=redirect&bpo=33482]: Make codecs.StreamRecoder.writelines take a list of bytes.

bpo-25735 [https://bugs.python.org/issue?@action=redirect&bpo=25735]: Added documentation for func factorial to indicate that returns integer values

bpo-20285 [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.)

Tests

bpo-37069 [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 test.support.catch_unraisable_exception() rather than test.support.captured_stderr().

bpo-37098 [https://bugs.python.org/issue?@action=redirect&bpo=37098]: Fix test_memfd_create on older Linux Kernels.

bpo-37081 [https://bugs.python.org/issue?@action=redirect&bpo=37081]: Test with OpenSSL 1.1.1c

bpo-36829 [https://bugs.python.org/issue?@action=redirect&bpo=36829]: Add test.support.catch_unraisable_exception(): context manager catching unraisable exception using sys.unraisablehook().

bpo-36915 [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).

bpo-36719 [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.

bpo-36816 [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.

bpo-35925 [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.

bpo-36782 [https://bugs.python.org/issue?@action=redirect&bpo=36782]: Add tests for several C API functions in the datetime module. Patch by Edison Abahurire.

bpo-36342 [https://bugs.python.org/issue?@action=redirect&bpo=36342]: Fix test_multiprocessing in test_venv if platform lacks functioning sem_open.

Build

bpo-36721 [https://bugs.python.org/issue?@action=redirect&bpo=36721]: To embed Python into an application, a new --embed option must be passed to python3-config --libs --embed to get -lpython3.8 (link the application to libpython). To support both 3.8 and older, try python3-config --libs --embed first and fallback to python3-config --libs (without --embed) if the previous command fails.

Add a pkg-config python-3.8-embed module to embed Python into an application: pkg-config python-3.8-embed --libs includes -lpython3.8. To support both 3.8 and older, try pkg-config python-X.Y-embed --libs first and fallback to pkg-config python-X.Y --libs (without --embed) if the previous command fails (replace X.Y with the Python version).

On the other hand, pkg-config python3.8 --libs no longer contains -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.

bpo-36786 [https://bugs.python.org/issue?@action=redirect&bpo=36786]: "make install" now runs compileall in parallel.

Windows

bpo-36965 [https://bugs.python.org/issue?@action=redirect&bpo=36965]: include of STATUS_CONTROL_C_EXIT without depending on MSC compiler

bpo-35926 [https://bugs.python.org/issue?@action=redirect&bpo=35926]: Update to OpenSSL 1.1.1b for Windows.

bpo-29883 [https://bugs.python.org/issue?@action=redirect&bpo=29883]: Add Windows support for UDP transports for the Proactor Event Loop. Patch by Adam Meily.

bpo-33407 [https://bugs.python.org/issue?@action=redirect&bpo=33407]: The Py_DEPRECATED() macro has been implemented for MSVC.

macOS

bpo-36231 [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.

IDLE

bpo-35610 [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 [https://bugs.python.org/issue?@action=redirect&bpo=31858].

bpo-37038 [https://bugs.python.org/issue?@action=redirect&bpo=37038]: Make idlelib.run runnable; add test clause.

bpo-36958 [https://bugs.python.org/issue?@action=redirect&bpo=36958]: Print any argument other than None or int passed to SystemExit or sys.exit().

bpo-36807 [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.

bpo-32411 [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.

Tools/Demos

bpo-37053 [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.

C API

bpo-36763 [https://bugs.python.org/issue?@action=redirect&bpo=36763]: Implement the PEP 587 [https://peps.python.org/pep-0587/] "Python Initialization Configuration".

bpo-36379 [https://bugs.python.org/issue?@action=redirect&bpo=36379]: Fix crashes when attempting to use the modulo parameter when __ipow__ is implemented in C.

bpo-37107 [https://bugs.python.org/issue?@action=redirect&bpo=37107]: Update PyObject_CallMethodObjArgs() and _PyObject_CallMethodIdObjArgs to use _PyObject_GetMethod to avoid creating a bound method object in many cases. Patch by Michael J. Sullivan.

bpo-36974 [https://bugs.python.org/issue?@action=redirect&bpo=36974]: Implement PEP 590 [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.

bpo-36763 [https://bugs.python.org/issue?@action=redirect&bpo=36763]: Py_Main() now returns the exitcode rather than calling Py_Exit(exitcode) when calling PyErr_Print() if the current exception type is SystemExit.

bpo-36922 [https://bugs.python.org/issue?@action=redirect&bpo=36922]: Add new type flag Py_TPFLAGS_METHOD_DESCRIPTOR for objects behaving like unbound methods. These are objects supporting the optimization given by the LOAD_METHOD/CALL_METHOD opcodes. See PEP 590.

bpo-36728 [https://bugs.python.org/issue?@action=redirect&bpo=36728]: The PyEval_ReInitThreads() function has been removed from the C API. It should not be called explicitly: use PyOS_AfterFork_Child() instead.

Python 3.8.0 alpha 4

Release date: 2019-05-06

Security

bpo-36742 [https://bugs.python.org/issue?@action=redirect&bpo=36742]: Fixes mishandling of pre-normalization characters in urlsplit().

bpo-30458 [https://bugs.python.org/issue?@action=redirect&bpo=30458]: Address CVE-2019-9740 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=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.

bpo-35755 [https://bugs.python.org/issue?@action=redirect&bpo=35755]: shutil.which() now uses os.confstr("CS_PATH") if available and if the PATH environment variable is not set. Remove also the current directory from posixpath.defpath. On Unix, shutil.which() and the subprocess module no longer search the executable in the current directory if the PATH environment variable is not set.

Core and Builtins

bpo-36722 [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.

bpo-32849 [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.

bpo-36623 [https://bugs.python.org/issue?@action=redirect&bpo=36623]: Remove parser headers and related function declarations that lack implementations after the removal of pgen.

bpo-20180 [https://bugs.python.org/issue?@action=redirect&bpo=20180]: dict.pop() is now up to 33% faster thanks to Argument Clinic. Patch by Inada Naoki.

bpo-36611 [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 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 PYMEM_DEBUG_SERIALNO defined to get back the field.

bpo-36588 [https://bugs.python.org/issue?@action=redirect&bpo=36588]: On AIX, sys.platform doesn't contain the major version anymore. Always return 'aix', instead of 'aix3' .. 'aix7'. Since older Python versions include the version number, it is recommended to always use sys.platform.startswith('aix'). Contributed by M. Felt.

bpo-36549 [https://bugs.python.org/issue?@action=redirect&bpo=36549]: Change str.capitalize to use titlecase for the first character instead of uppercase.

bpo-36540 [https://bugs.python.org/issue?@action=redirect&bpo=36540]: Implement PEP 570 [https://peps.python.org/pep-0570/] (Python positional-only parameters). Patch by Pablo Galindo.

bpo-36475 [https://bugs.python.org/issue?@action=redirect&bpo=36475]: PyEval_AcquireLock() and PyEval_AcquireThread() now terminate the current thread if called while the interpreter is finalizing, making them consistent with PyEval_RestoreThread(), Py_END_ALLOW_THREADS(), and PyGILState_Ensure().

bpo-36504 [https://bugs.python.org/issue?@action=redirect&bpo=36504]: Fix signed integer overflow in _ctypes.c's PyCArrayType_new().

bpo-20844 [https://bugs.python.org/issue?@action=redirect&bpo=20844]: Fix running script with encoding cookie and LF line ending may fail on Windows.

bpo-24214 [https://bugs.python.org/issue?@action=redirect&bpo=24214]: Fixed support of the surrogatepass error handler in the UTF-8 incremental decoder.

bpo-36452 [https://bugs.python.org/issue?@action=redirect&bpo=36452]: Changing dict keys during iteration of the dict itself, keys(), values(), or items() will now be detected in certain corner cases where keys are deleted/added so that the number of keys isn't changed. A RuntimeError will be raised after len(dict) iterations. Contributed by Thomas Perl.

bpo-36459 [https://bugs.python.org/issue?@action=redirect&bpo=36459]: Fix a possible double PyMem_FREE() due to tokenizer.c's tok_nextc().

bpo-36433 [https://bugs.python.org/issue?@action=redirect&bpo=36433]: Fixed TypeError message in classmethoddescr_call.

bpo-36430 [https://bugs.python.org/issue?@action=redirect&bpo=36430]: Fix a possible reference leak in itertools.count().

bpo-36440 [https://bugs.python.org/issue?@action=redirect&bpo=36440]: Include node names in ParserError messages, instead of numeric IDs. Patch by A. Skrobov.

bpo-36143 [https://bugs.python.org/issue?@action=redirect&bpo=36143]: Regenerate keyword from the Grammar and Tokens file using pgen. Patch by Pablo Galindo.

bpo-18372 [https://bugs.python.org/issue?@action=redirect&bpo=18372]: Add missing PyObject_GC_Track() calls in the pickle module. Patch by Zackery Spytz.

Library

bpo-35952 [https://bugs.python.org/issue?@action=redirect&bpo=35952]: Fix pythoninfo when the compiler is missing.

bpo-28238 [https://bugs.python.org/issue?@action=redirect&bpo=28238]: The .find*() methods of xml.etree.ElementTree can now search for wildcards like {*}tag and {ns}* that match a tag in any namespace or all tags in a namespace. Patch by Stefan Behnel.

bpo-26978 [https://bugs.python.org/issue?@action=redirect&bpo=26978]: pathlib.path.link_to() is now implemented. It creates a hard link pointing to a path.

bpo-1613500 [https://bugs.python.org/issue?@action=redirect&bpo=1613500]: fileinput.FileInput now uses the input file mode to correctly set the output file mode (previously it was hardcoded to 'w') when inplace=True is passed to its constructor.

bpo-36734 [https://bugs.python.org/issue?@action=redirect&bpo=36734]: Fix compilation of faulthandler.c on HP-UX. Initialize stack_t current_stack to zero using memset().

bpo-13611 [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.

bpo-36669 [https://bugs.python.org/issue?@action=redirect&bpo=36669]: Add missing matrix multiplication operator support to weakref.proxy.

bpo-36676 [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.

bpo-36673 [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.

bpo-36650 [https://bugs.python.org/issue?@action=redirect&bpo=36650]: The C version of functools.lru_cache() was treating calls with an empty **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.

bpo-28552 [https://bugs.python.org/issue?@action=redirect&bpo=28552]: Fix distutils.sysconfig if sys.executable is None or an empty string: use os.getcwd() to initialize project_base. Fix also the distutils build command: don't use sys.executable if it is None or an empty string.

bpo-35755 [https://bugs.python.org/issue?@action=redirect&bpo=35755]: shutil.which() and distutils.spawn.find_executable now use os.confstr("CS_PATH") if available instead of os.defpath, if the PATH environment variable is not set. Moreover, don't use os.confstr("CS_PATH") nor os.defpath if the PATH environment variable is set to an empty string.

bpo-25430 [https://bugs.python.org/issue?@action=redirect&bpo=25430]: improve performance of IPNetwork.__contains__()

bpo-30485 [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.

bpo-36613 [https://bugs.python.org/issue?@action=redirect&bpo=36613]: Fix asyncio wait() not removing callback if exception

bpo-36598 [https://bugs.python.org/issue?@action=redirect&bpo=36598]: Fix isinstance check for Mock objects with spec when the code is executed under tracing. Patch by Karthikeyan Singaravelan.

bpo-18748 [https://bugs.python.org/issue?@action=redirect&bpo=18748]: In development mode (-X dev) and in debug build, the io.IOBase destructor now logs close() exceptions. These exceptions are silent by default in release mode.

bpo-36575 [https://bugs.python.org/issue?@action=redirect&bpo=36575]: The _lsprof module now uses internal timer same to time.perf_counter() by default. 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 perf_counter() is monotonic. Patch by Inada Naoki.

bpo-33461 [https://bugs.python.org/issue?@action=redirect&bpo=33461]: json.loads now emits DeprecationWarning when encoding option is specified. Patch by Matthias Bussonnier.

bpo-36559 [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.

bpo-17561 [https://bugs.python.org/issue?@action=redirect&bpo=17561]: Set backlog=None as the default for socket.create_server.

bpo-34373 [https://bugs.python.org/issue?@action=redirect&bpo=34373]: Fix time.mktime() error handling on AIX for year before 1970.

bpo-36232 [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.

bpo-36546 [https://bugs.python.org/issue?@action=redirect&bpo=36546]: Add statistics.quantiles()

bpo-36050 [https://bugs.python.org/issue?@action=redirect&bpo=36050]: Optimized http.client.HTTPResponse.read() for large response. Patch by Inada Naoki.

bpo-36522 [https://bugs.python.org/issue?@action=redirect&bpo=36522]: If debuglevel is set to >0 in http.client, print all values for headers with multiple values for the same header name. Patch by Matt Houglum.

bpo-36492 [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.

bpo-27181 [https://bugs.python.org/issue?@action=redirect&bpo=27181]: Add statistics.geometric_mean().

bpo-30427 [https://bugs.python.org/issue?@action=redirect&bpo=30427]: os.path.normcase() relies on os.fspath() to check the type of its argument. Redundant checks have been removed from its posixpath.normcase() and ntpath.normcase() implementations. Patch by Wolfgang Maier.

bpo-36385 [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.

bpo-36434 [https://bugs.python.org/issue?@action=redirect&bpo=36434]: Errors during writing to a ZIP file no longer prevent to properly close it.

bpo-36407 [https://bugs.python.org/issue?@action=redirect&bpo=36407]: Fixed wrong indentation writing for CDATA section in xml.dom.minidom. Patch by Vladimir Surjaninov.

bpo-36326 [https://bugs.python.org/issue?@action=redirect&bpo=36326]: inspect.getdoc() can now find docstrings for member objects when __slots__ is a dictionary.

bpo-36366 [https://bugs.python.org/issue?@action=redirect&bpo=36366]: Calling stop() on an unstarted or stopped unittest.mock.patch() object will now return None instead of raising RuntimeError, making the method idempotent. Patch by Karthikeyan Singaravelan.

bpo-36348 [https://bugs.python.org/issue?@action=redirect&bpo=36348]: The imap.IMAP4.logout() method no longer ignores silently arbitrary exceptions.

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Add time module support and fix test_time failures for VxWorks.

bpo-36227 [https://bugs.python.org/issue?@action=redirect&bpo=36227]: Added support for keyword arguments default_namespace and xml_declaration in functions ElementTree.tostring() and ElementTree.tostringlist().

bpo-36004 [https://bugs.python.org/issue?@action=redirect&bpo=36004]: Added new alternate constructors datetime.date.fromisocalendar() and datetime.datetime.fromisocalendar(), which construct date objects from ISO year, week number and weekday; these are the inverse of each class's isocalendar method. Patch by Paul Ganssle.

bpo-35936 [https://bugs.python.org/issue?@action=redirect&bpo=35936]: modulefinder no longer depends on the deprecated imp module, and the initializer for modulefinder.ModuleFinder now has immutable default arguments. Patch by Brandt Bucher.

bpo-35376 [https://bugs.python.org/issue?@action=redirect&bpo=35376]: modulefinder correctly handles modules that have the same name as a bad package. Patch by Brandt Bucher.

bpo-17396 [https://bugs.python.org/issue?@action=redirect&bpo=17396]: modulefinder no longer crashes when encountering syntax errors in followed imports. Patch by Brandt Bucher.

bpo-35934 [https://bugs.python.org/issue?@action=redirect&bpo=35934]: Added create_server() and 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 [https://bugs.python.org/issue?@action=redirect&bpo=17561].)

bpo-23078 [https://bugs.python.org/issue?@action=redirect&bpo=23078]: Add support for classmethod() and staticmethod() to unittest.mock.create_autospec(). Initial patch by Felipe Ochoa.

bpo-35416 [https://bugs.python.org/issue?@action=redirect&bpo=35416]: Fix potential resource warnings in distutils. Patch by Mickaël Schoentgen.

bpo-25451 [https://bugs.python.org/issue?@action=redirect&bpo=25451]: Add transparency methods to tkinter.PhotoImage. Patch by Zackery Spytz.

bpo-35082 [https://bugs.python.org/issue?@action=redirect&bpo=35082]: Don't return deleted attributes when calling dir on a unittest.mock.Mock.

bpo-34547 [https://bugs.python.org/issue?@action=redirect&bpo=34547]: wsgiref.handlers.BaseHandler now handles abrupt client connection terminations gracefully. Patch by Petter Strandmark.

bpo-31658 [https://bugs.python.org/issue?@action=redirect&bpo=31658]: xml.sax.parse() now supports path-like. Patch by Mickaël Schoentgen.

bpo-34139 [https://bugs.python.org/issue?@action=redirect&bpo=34139]: Remove stale unix datagram socket before binding

bpo-33530 [https://bugs.python.org/issue?@action=redirect&bpo=33530]: Implemented Happy Eyeballs in asyncio.create_connection(). Added two new arguments, happy_eyeballs_delay and interleave, to specify Happy Eyeballs behavior.

bpo-33291 [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.

bpo-31310 [https://bugs.python.org/issue?@action=redirect&bpo=31310]: Fix the multiprocessing.semaphore_tracker so it is reused by child processes

bpo-31292 [https://bugs.python.org/issue?@action=redirect&bpo=31292]: Fix setup.py check --restructuredtext for files containing include directives.

Documentation

bpo-36625 [https://bugs.python.org/issue?@action=redirect&bpo=36625]: Remove obsolete comments from docstrings in fractions.Fraction

bpo-30840 [https://bugs.python.org/issue?@action=redirect&bpo=30840]: Document relative imports

bpo-36523 [https://bugs.python.org/issue?@action=redirect&bpo=36523]: Add docstring for io.IOBase.writelines().

bpo-36425 [https://bugs.python.org/issue?@action=redirect&bpo=36425]: New documentation translation: Simplified Chinese [https://docs.python.org/zh-cn/].

bpo-36345 [https://bugs.python.org/issue?@action=redirect&bpo=36345]: Avoid the duplication of code from Tools/scripts/serve.py in using the literalinclude directive for the basic wsgiref-based web server in the documentation of wsgiref. Contributed by Stéphane Wirtel.

bpo-36345 [https://bugs.python.org/issue?@action=redirect&bpo=36345]: Using the code of the Tools/scripts/serve.py script as an example in the wsgiref documentation. Contributed by Stéphane Wirtel.

bpo-36157 [https://bugs.python.org/issue?@action=redirect&bpo=36157]: Added documentation for PyInterpreterState_Main().

bpo-33043 [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.

bpo-35581 [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.

bpo-33832 [https://bugs.python.org/issue?@action=redirect&bpo=33832]: Add glossary entry for 'magic method'.

bpo-32913 [https://bugs.python.org/issue?@action=redirect&bpo=32913]: Added re.Match.groupdict example to regex HOWTO.

Tests

bpo-36719 [https://bugs.python.org/issue?@action=redirect&bpo=36719]: regrtest now always detects uncollectable objects. Previously, the check was only enabled by --findleaks. The check now also works with -jN/--multiprocess N. --findleaks becomes a deprecated alias to --fail-env-changed.

bpo-36725 [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.

bpo-36454 [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.

bpo-32424 [https://bugs.python.org/issue?@action=redirect&bpo=32424]: Improve test coverage for xml.etree.ElementTree. Patch by Gordon P. Hemsley.

bpo-32424 [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.

bpo-36635 [https://bugs.python.org/issue?@action=redirect&bpo=36635]: Add a new _testinternalcapi module to test the internal C API.

bpo-36629 [https://bugs.python.org/issue?@action=redirect&bpo=36629]: Fix test_imap4_host_default_value() of test_imaplib: catch also errno.ENETUNREACH error.

bpo-36611 [https://bugs.python.org/issue?@action=redirect&bpo=36611]: Fix test_sys.test_getallocatedblocks() when tracemalloc is enabled.

bpo-36560 [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.

bpo-36565 [https://bugs.python.org/issue?@action=redirect&bpo=36565]: Fix reference hunting (python3 -m test -R 3:3) when Python has no built-in abc module.

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Port test_resource to VxWorks: skip tests cases setting RLIMIT_FSIZE and RLIMIT_CPU.

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Fix test_tabnanny on VxWorks: adjust ENOENT error message.

bpo-36436 [https://bugs.python.org/issue?@action=redirect&bpo=36436]: Fix _testcapi.pymem_buffer_overflow(): handle memory allocation failure.

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Fix test_utf8_mode on VxWorks: Python always use UTF-8 on VxWorks.

bpo-36341 [https://bugs.python.org/issue?@action=redirect&bpo=36341]: Fix tests that may fail with PermissionError upon calling bind() on AF_UNIX sockets.

Build

bpo-36747 [https://bugs.python.org/issue?@action=redirect&bpo=36747]: Remove the stale scriptsinstall Makefile target.

bpo-21536 [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, libpython must not be loaded with RTLD_LOCAL, but RTLD_GLOBAL instead. Previously, using RTLD_LOCAL, it was already not possible to load C extensions which were not linked to libpython, such as C extensions of the standard library built by the *shared* section of Modules/Setup.

distutils, python-config and python-config.py have been modified.

bpo-36707 [https://bugs.python.org/issue?@action=redirect&bpo=36707]: ./configure --with-pymalloc no longer adds the m flag to SOABI (sys.implementation.cache_tag). Enabling or disabling pymalloc has no impact on the ABI.

bpo-36635 [https://bugs.python.org/issue?@action=redirect&bpo=36635]: Change PyAPI_FUNC(type), PyAPI_DATA(type) and PyMODINIT_FUNC macros of pyport.h when Py_BUILD_CORE_MODULE is defined. The Py_BUILD_CORE_MODULE define must be now be used to build a C extension as a dynamic library accessing Python internals: export the PyInit_xxx() function in DLL exports on Windows.

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Don't build the _crypt extension on VxWorks.

bpo-36618 [https://bugs.python.org/issue?@action=redirect&bpo=36618]: Add -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 CFLAGS and not just CFLAGS_NODIST, since third party C extensions can have the same issue.

bpo-36605 [https://bugs.python.org/issue?@action=redirect&bpo=36605]: make tags and make TAGS now also parse Modules/_io/*.c and Modules/_io/*.h.

bpo-36465 [https://bugs.python.org/issue?@action=redirect&bpo=36465]: Release builds and debug builds are now ABI compatible: defining the Py_DEBUG macro no longer implies the Py_TRACE_REFS macro, which introduces the only ABI incompatibility. The Py_TRACE_REFS macro, which adds the sys.getobjects() function and the PYTHONDUMPREFS environment variable, can be set using the new ./configure --with-trace-refs build option.

bpo-36577 [https://bugs.python.org/issue?@action=redirect&bpo=36577]: setup.py now correctly reports missing OpenSSL headers and libraries again.

bpo-36544 [https://bugs.python.org/issue?@action=redirect&bpo=36544]: Fix regression introduced in bpo-36146 [https://bugs.python.org/issue?@action=redirect&bpo=36146] refactoring setup.py

bpo-36508 [https://bugs.python.org/issue?@action=redirect&bpo=36508]: python-config --ldflags no longer includes flags of the LINKFORSHARED variable. The LINKFORSHARED variable must only be used to build executables.

bpo-36503 [https://bugs.python.org/issue?@action=redirect&bpo=36503]: Remove references to "aix3" and "aix4". Patch by M. Felt.

Windows

bpo-35920 [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.

bpo-36649 [https://bugs.python.org/issue?@action=redirect&bpo=36649]: Remove trailing spaces for registry keys when installed via the Store.

bpo-34144 [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.

bpo-36509 [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.

bpo-35941 [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.

bpo-36441 [https://bugs.python.org/issue?@action=redirect&bpo=36441]: Fixes creating a venv when debug binaries are installed.

bpo-36085 [https://bugs.python.org/issue?@action=redirect&bpo=36085]: Enable better DLL resolution on Windows by using safe DLL search paths and adding os.add_dll_directory().

bpo-36010 [https://bugs.python.org/issue?@action=redirect&bpo=36010]: Add the venv standard library module to the nuget distribution for Windows.

bpo-29515 [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

bpo-35947 [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.

bpo-34060 [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.

bpo-31512 [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.

macOS

bpo-34602 [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 [https://bugs.python.org/issue?@action=redirect&bpo=18075] which forced a non-default stack size when building the interpreter executable on macOS.

IDLE

bpo-36429 [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.

Tools/Demos

bpo-14546 [https://bugs.python.org/issue?@action=redirect&bpo=14546]: Fix the argument handling in Tools/scripts/lll.py.

C API

bpo-36763 [https://bugs.python.org/issue?@action=redirect&bpo=36763]: Fix memory leak in Py_SetStandardStreamEncoding(): release memory if the function is called twice.

bpo-36641 [https://bugs.python.org/issue?@action=redirect&bpo=36641]: PyDoc_VAR(name) and PyDoc_STRVAR(name, str) now create static const char name[] instead of static char name[]. Patch by Inada Naoki.

bpo-36389 [https://bugs.python.org/issue?@action=redirect&bpo=36389]: Change the value of CLEANBYTE, DEADDYTE and FORBIDDENBYTE internal constants used by debug hooks on Python memory allocators (PyMem_SetupDebugHooks() function). Byte patterns 0xCB, 0xDB and 0xFB have been replaced with 0xCD, 0xDD and 0xFD to use the same values than Windows CRT debug malloc() and free().

bpo-36443 [https://bugs.python.org/issue?@action=redirect&bpo=36443]: Since Python 3.7.0, calling Py_DecodeLocale() before Py_Initialize() produces mojibake if the 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 _Py_PreInitialize() API with _PyPreConfig.

bpo-36025 [https://bugs.python.org/issue?@action=redirect&bpo=36025]: Fixed an accidental change to the datetime C API where the arguments to the PyDate_FromTimestamp() function were incorrectly interpreted as a single timestamp rather than an arguments tuple, which causes existing code to start raising TypeError. The backwards-incompatible change was only present in alpha releases of Python 3.8. Patch by Paul Ganssle.

bpo-35810 [https://bugs.python.org/issue?@action=redirect&bpo=35810]: Modify 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

Python 3.8.0 alpha 3

Release date: 2019-03-25

Security

bpo-36216 [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.

bpo-35121 [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 http.cookiejar.DefaultCookiePolicy policy. Patch by Karthikeyan Singaravelan.

Core and Builtins

bpo-36421 [https://bugs.python.org/issue?@action=redirect&bpo=36421]: Fix a possible double decref in _ctypes.c's PyCArrayType_new().

bpo-36412 [https://bugs.python.org/issue?@action=redirect&bpo=36412]: Fix a possible crash when creating a new dictionary.

bpo-36398 [https://bugs.python.org/issue?@action=redirect&bpo=36398]: Fix a possible crash in structseq_repr().

bpo-36256 [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.

bpo-36365 [https://bugs.python.org/issue?@action=redirect&bpo=36365]: repr(structseq) is no longer limited to 512 bytes.

bpo-36374 [https://bugs.python.org/issue?@action=redirect&bpo=36374]: Fix a possible null pointer dereference in merge_consts_recursive(). Patch by Zackery Spytz.

bpo-36236 [https://bugs.python.org/issue?@action=redirect&bpo=36236]: At Python initialization, the current directory is no longer prepended to sys.path if it has been removed.

bpo-36352 [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.

bpo-36301 [https://bugs.python.org/issue?@action=redirect&bpo=36301]: Python initialization now fails if decoding pybuilddir.txt configuration file fails at startup.

bpo-36333 [https://bugs.python.org/issue?@action=redirect&bpo=36333]: Fix leak in _PyRuntimeState_Fini. Contributed by Stéphane Wirtel.

bpo-36332 [https://bugs.python.org/issue?@action=redirect&bpo=36332]: The builtin compile() can now handle AST objects that contain assignment expressions. Patch by Pablo Galindo.

bpo-36282 [https://bugs.python.org/issue?@action=redirect&bpo=36282]: Improved error message for too much positional arguments in some builtin functions.

bpo-30040 [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 dict.clear(). And empty dict creation and deletion is about 2x faster. Patch by Inada Naoki.

bpo-36262 [https://bugs.python.org/issue?@action=redirect&bpo=36262]: Fix an unlikely memory leak on conversion from string to float in the function _Py_dg_strtod() used by float(str), complex(str), pickle.load(), marshal.load(), etc.

bpo-36252 [https://bugs.python.org/issue?@action=redirect&bpo=36252]: Update Unicode databases to version 12.0.0.

bpo-36218 [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.

bpo-36188 [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

bpo-36124 [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.

bpo-35975 [https://bugs.python.org/issue?@action=redirect&bpo=35975]: Add a feature_version flag to ast.parse() (documented) and compile() (hidden) that allows tweaking the parser to support older versions of the grammar. In particular, if feature_version is 5 or 6, the hacks for the async and 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 NAME tokens that the parser driver recognizes.)

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Use UTF-8 as the system encoding on VxWorks.

bpo-36048 [https://bugs.python.org/issue?@action=redirect&bpo=36048]: The __index__() special method will be used instead of __int__() for implicit conversion of Python numbers to C integers. Using the __int__() method in implicit conversions has been deprecated.

bpo-35808 [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.

Library

bpo-36401 [https://bugs.python.org/issue?@action=redirect&bpo=36401]: The class documentation created by pydoc now has a separate section for readonly properties.

bpo-36320 [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.

bpo-34745 [https://bugs.python.org/issue?@action=redirect&bpo=34745]: Fix asyncio ssl memory issues caused by circular references

bpo-36324 [https://bugs.python.org/issue?@action=redirect&bpo=36324]: Add method to statistics.NormalDist for computing the inverse cumulative normal distribution.

bpo-36321 [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.

bpo-36297 [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.

bpo-36298 [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.

bpo-36268 [https://bugs.python.org/issue?@action=redirect&bpo=36268]: Switch the default format used for writing tars with tarfile to the modern POSIX.1-2001 pax standard, from the vendor-specific GNU. Contributed by C.A.M. Gerlach.

bpo-36285 [https://bugs.python.org/issue?@action=redirect&bpo=36285]: Fix integer overflows in the array module. Patch by Stephan Hohe.

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Add _signal module support for VxWorks.

bpo-36272 [https://bugs.python.org/issue?@action=redirect&bpo=36272]: logging does not silently ignore RecursionError anymore. Patch contributed by Rémi Lapeyre.

bpo-36280 [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.

bpo-35931 [https://bugs.python.org/issue?@action=redirect&bpo=35931]: The pdb debug command now gracefully handles all exceptions.

bpo-36251 [https://bugs.python.org/issue?@action=redirect&bpo=36251]: Fix format strings used for stderrprinter and re.Match reprs. Patch by Stephan Hohe.

bpo-36235 [https://bugs.python.org/issue?@action=redirect&bpo=36235]: Fix CFLAGS in customize_compiler() of distutils.sysconfig: when the CFLAGS environment variable is defined, don't override CFLAGS variable with the OPT variable anymore. Initial patch written by David Malcolm.

bpo-35807 [https://bugs.python.org/issue?@action=redirect&bpo=35807]: Update ensurepip to install pip 19.0.3 and setuptools 40.8.0.

bpo-36139 [https://bugs.python.org/issue?@action=redirect&bpo=36139]: Release GIL when closing mmap objects.

bpo-36179 [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.

bpo-36169 [https://bugs.python.org/issue?@action=redirect&bpo=36169]: Add overlap() method to statistics.NormalDist. Computes the overlapping coefficient for two normal distributions.

bpo-36103 [https://bugs.python.org/issue?@action=redirect&bpo=36103]: Default buffer size used by shutil.copyfileobj() is changed from 16 KiB to 64 KiB on non-Windows platform to reduce system call overhead. Contributed by Inada Naoki.

bpo-36130 [https://bugs.python.org/issue?@action=redirect&bpo=36130]: Fix pdb with skip=... when stepping into a frame without a __name__ global. Patch by Anthony Sottile.

bpo-35652 [https://bugs.python.org/issue?@action=redirect&bpo=35652]: shutil.copytree(copy_function=...) erroneously pass DirEntry instead of a path string.

bpo-35178 [https://bugs.python.org/issue?@action=redirect&bpo=35178]: Ensure custom warnings.formatwarning() function can receive line as positional argument. Based on patch by Tashrif Billah.

bpo-36106 [https://bugs.python.org/issue?@action=redirect&bpo=36106]: Resolve potential name clash with libm's sinpi(). Patch by Dmitrii Pasechnik.

bpo-36091 [https://bugs.python.org/issue?@action=redirect&bpo=36091]: Clean up reference to async generator in Lib/types. Patch by Henry Chen.

bpo-36043 [https://bugs.python.org/issue?@action=redirect&bpo=36043]: FileCookieJar supports path-like object. Contributed by Stéphane Wirtel

bpo-35899 [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.

bpo-21269 [https://bugs.python.org/issue?@action=redirect&bpo=21269]: Add args and kwargs properties to mock call objects. Contributed by Kumar Akshay.

bpo-30670 [https://bugs.python.org/issue?@action=redirect&bpo=30670]: 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 pprint.pprint, pprint.pformat and pprint.PrettyPrinter. Contributed by Rémi Lapeyre.

bpo-35843 [https://bugs.python.org/issue?@action=redirect&bpo=35843]: Implement __getitem__ for _NamespacePath. Patch by Anthony Sottile.

bpo-35802 [https://bugs.python.org/issue?@action=redirect&bpo=35802]: Clean up code which checked presence of os.stat / os.lstat / os.chmod which are always present. Patch by Anthony Sottile.

bpo-35715 [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

bpo-35493 [https://bugs.python.org/issue?@action=redirect&bpo=35493]: Use multiprocessing.connection.wait() instead of polling each 0.2 seconds for worker updates in multiprocessing.Pool. Patch by Pablo Galindo.

bpo-35661 [https://bugs.python.org/issue?@action=redirect&bpo=35661]: Store the venv prompt in pyvenv.cfg.

bpo-35121 [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.

bpo-21478 [https://bugs.python.org/issue?@action=redirect&bpo=21478]: Calls to a child function created with unittest.mock.create_autospec() should propagate to the parent. Patch by Karthikeyan Singaravelan.

bpo-35198 [https://bugs.python.org/issue?@action=redirect&bpo=35198]: Fix C++ extension compilation on AIX

Documentation

bpo-36329 [https://bugs.python.org/issue?@action=redirect&bpo=36329]: Declare the path of the Python binary for the usage of Tools/scripts/serve.py when executing make -C Doc/ serve. Contributed by Stéphane Wirtel

bpo-36138 [https://bugs.python.org/issue?@action=redirect&bpo=36138]: Improve documentation about converting datetime.timedelta to scalars.

bpo-21314 [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

Tests

bpo-36234 [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.

bpo-29571 [https://bugs.python.org/issue?@action=redirect&bpo=29571]: Fix test_re.test_locale_flag(): use locale.getpreferredencoding() rather than locale.getlocale() to get the locale encoding. With some locales, locale.getlocale() returns the wrong encoding.

bpo-36123 [https://bugs.python.org/issue?@action=redirect&bpo=36123]: Fix race condition in test_socket.

Build

bpo-36356 [https://bugs.python.org/issue?@action=redirect&bpo=36356]: Fix leaks that led to build failure when configured with address sanitizer.

bpo-36146 [https://bugs.python.org/issue?@action=redirect&bpo=36146]: Add TEST_EXTENSIONS constant to setup.py to allow to not build test extensions like _testcapi.

bpo-36146 [https://bugs.python.org/issue?@action=redirect&bpo=36146]: Fix setup.py on macOS: only add /usr/include/ffi to include directories of _ctypes, not for all extensions.

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Enable build system to cross-build for VxWorks RTOS.

Windows

bpo-36312 [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.

bpo-36264 [https://bugs.python.org/issue?@action=redirect&bpo=36264]: Don't honor POSIX HOME in os.path.expanduser on windows. Patch by Anthony Sottile.

bpo-24643 [https://bugs.python.org/issue?@action=redirect&bpo=24643]: Fix name collisions due to #define timezone _timezone in PC/pyconfig.h.

IDLE

bpo-36405 [https://bugs.python.org/issue?@action=redirect&bpo=36405]: Use dict unpacking in idlelib.

bpo-36396 [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.

bpo-36176 [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).

bpo-23205 [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.

bpo-23216 [https://bugs.python.org/issue?@action=redirect&bpo=23216]: Add docstrings to IDLE search modules.

bpo-36152 [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.

bpo-32129 [https://bugs.python.org/issue?@action=redirect&bpo=32129]: Avoid blurry IDLE application icon on macOS with Tk 8.6. Patch by Kevin Walzer.

bpo-36096 [https://bugs.python.org/issue?@action=redirect&bpo=36096]: Refactor class variables to instance variables in colorizer.

bpo-30348 [https://bugs.python.org/issue?@action=redirect&bpo=30348]: Increase test coverage of idlelib.autocomplete by 30%. Patch by Louie Lu

Tools/Demos

bpo-35132 [https://bugs.python.org/issue?@action=redirect&bpo=35132]: Fix py-list and py-bt commands of python-gdb.py on gdb7.

bpo-32217 [https://bugs.python.org/issue?@action=redirect&bpo=32217]: Fix freeze script on Windows.

C API

bpo-36381 [https://bugs.python.org/issue?@action=redirect&bpo=36381]: Raise DeprecationWarning when '#' formats are used for building or parsing values without PY_SSIZE_T_CLEAN.

bpo-36142 [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.

Python 3.8.0 alpha 2

Release date: 2019-02-25

Core and Builtins

bpo-36052 [https://bugs.python.org/issue?@action=redirect&bpo=36052]: Raise a SyntaxError when assigning a value to __debug__ with the Assignment Operator. Contributed by Stéphane Wirtel and Pablo Galindo.

bpo-36012 [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.

bpo-35942 [https://bugs.python.org/issue?@action=redirect&bpo=35942]: The error message emitted when returning invalid types from __fspath__ in interfaces that allow passing PathLike objects has been improved and now it does explain the origin of the error.

bpo-36016 [https://bugs.python.org/issue?@action=redirect&bpo=36016]: gc.get_objects can now receive an optional parameter indicating a generation to get objects from. Patch by Pablo Galindo.

bpo-1054041 [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.

bpo-35992 [https://bugs.python.org/issue?@action=redirect&bpo=35992]: Fix __class_getitem__() not being called on a class with a custom non-subscriptable metaclass.

bpo-35993 [https://bugs.python.org/issue?@action=redirect&bpo=35993]: Fix a crash on fork when using subinterpreters. Contributed by Stéphane Wirtel

bpo-35991 [https://bugs.python.org/issue?@action=redirect&bpo=35991]: Fix a potential double free in Modules/_randommodule.c.

bpo-35961 [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.

bpo-35911 [https://bugs.python.org/issue?@action=redirect&bpo=35911]: Enable the creation of cell objects by adding a cell.__new__ method, and expose the type cell in Lib/types.py under the name CellType. Patch by Pierre Glaser.

bpo-12822 [https://bugs.python.org/issue?@action=redirect&bpo=12822]: Use monotonic clock for pthread_cond_timedwait when pthread_condattr_setclock and CLOCK_MONOTONIC are available.

bpo-15248 [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.

bpo-35886 [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).

bpo-31506 [https://bugs.python.org/issue?@action=redirect&bpo=31506]: Clarify the errors reported when object.__new__ and object.__init__ receive more than one argument. Contributed by Sanyam Khurana.

bpo-35724 [https://bugs.python.org/issue?@action=redirect&bpo=35724]: Signal-handling is now guaranteed to happen relative to the main interpreter.

bpo-33608 [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.

bpo-33989 [https://bugs.python.org/issue?@action=redirect&bpo=33989]: Fix a possible crash in list.sort() when sorting objects with ob_type->tp_richcompare == NULL. Patch by Zackery Spytz.

Library

bpo-35512 [https://bugs.python.org/issue?@action=redirect&bpo=35512]: 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.

bpo-36018 [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.

bpo-35904 [https://bugs.python.org/issue?@action=redirect&bpo=35904]: Added statistics.fmean() as a faster, floating point variant of the existing mean() function.

bpo-35918 [https://bugs.python.org/issue?@action=redirect&bpo=35918]: Removed broken has_key method from multiprocessing.managers.SyncManager.dict. Contributed by Rémi Lapeyre.

bpo-18283 [https://bugs.python.org/issue?@action=redirect&bpo=18283]: Add support for bytes to shutil.which().

bpo-35960 [https://bugs.python.org/issue?@action=redirect&bpo=35960]: Fix dataclasses.field() throwing away empty mapping objects passed as metadata.

bpo-35500 [https://bugs.python.org/issue?@action=redirect&bpo=35500]: Write expected and actual call parameters on separate lines in unittest.mock.Mock.assert_called_with() assertion errors. Contributed by Susan Su.

bpo-35931 [https://bugs.python.org/issue?@action=redirect&bpo=35931]: The pdb debug command now gracefully handles syntax errors.

bpo-24209 [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.

bpo-35321 [https://bugs.python.org/issue?@action=redirect&bpo=35321]: Set __spec__.origin of _frozen_importlib to frozen so that it matches the behavior of _frozen_importlib_external. Patch by Nina Zakharenko.

bpo-35378 [https://bugs.python.org/issue?@action=redirect&bpo=35378]: Fix a reference issue inside 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.

bpo-34294 [https://bugs.python.org/issue?@action=redirect&bpo=34294]: re module, fix wrong capturing groups in rare cases. re.search(), re.findall(), 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.

bpo-35615 [https://bugs.python.org/issue?@action=redirect&bpo=35615]: weakref: Fix a RuntimeError when copying a WeakKeyDictionary or a WeakValueDictionary, due to some keys or values disappearing while iterating.

bpo-35606 [https://bugs.python.org/issue?@action=redirect&bpo=35606]: Implement math.prod() as analogous function to sum() that returns the product of a 'start' value (default: 1) times an iterable of numbers. Patch by Pablo Galindo.

bpo-32417 [https://bugs.python.org/issue?@action=redirect&bpo=32417]: Performing arithmetic between datetime.datetime subclasses and datetime.timedelta now returns an object of the same type as the datetime.datetime subclass. As a result, datetime.datetime.astimezone() and alternate constructors like datetime.datetime.now() and datetime.fromtimestamp() called with a tz argument now also retain their subclass.

bpo-35153 [https://bugs.python.org/issue?@action=redirect&bpo=35153]: Add headers optional keyword-only parameter to xmlrpc.client.ServerProxy, xmlrpc.client.Transport and xmlrpc.client.SafeTransport. Patch by Cédric Krier.

bpo-34572 [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.

Documentation

bpo-36083 [https://bugs.python.org/issue?@action=redirect&bpo=36083]: Fix formatting of --check-hash-based-pycs options in the manpage Synopsis.

bpo-36007 [https://bugs.python.org/issue?@action=redirect&bpo=36007]: Bump minimum sphinx version to 1.8. Patch by Anthony Sottile.

bpo-22062 [https://bugs.python.org/issue?@action=redirect&bpo=22062]: Update documentation and docstrings for pathlib. Original patch by Mike Short.

Tests

bpo-27313 [https://bugs.python.org/issue?@action=redirect&bpo=27313]: Avoid test_ttk_guionly ComboboxTest failure with macOS Cocoa Tk.

bpo-36019 [https://bugs.python.org/issue?@action=redirect&bpo=36019]: Add test.support.TEST_HTTP_URL and replace references of http://www.example.com by this new constant. Contributed by Stéphane Wirtel.

bpo-36037 [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.

bpo-35798 [https://bugs.python.org/issue?@action=redirect&bpo=35798]: Added test.support.check_syntax_warning().

bpo-35505 [https://bugs.python.org/issue?@action=redirect&bpo=35505]: Make test_imap4_host_default_value independent on whether the local IMAP server is running.

bpo-35917 [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)

bpo-35704 [https://bugs.python.org/issue?@action=redirect&bpo=35704]: Skip 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)

bpo-34720 [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.

Windows

bpo-35976 [https://bugs.python.org/issue?@action=redirect&bpo=35976]: Added ARM build support to Windows build files in PCBuild.

bpo-35692 [https://bugs.python.org/issue?@action=redirect&bpo=35692]: pathlib no longer raises when checking file and directory existence on drives that are not ready

bpo-35872 [https://bugs.python.org/issue?@action=redirect&bpo=35872]: Uses the base Python executable when invoking venv in a virtual environment

bpo-35873 [https://bugs.python.org/issue?@action=redirect&bpo=35873]: Prevents venv paths being inherited by child processes

bpo-35299 [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

IDLE

bpo-24310 [https://bugs.python.org/issue?@action=redirect&bpo=24310]: IDLE -- Document settings dialog font tab sample.

bpo-35833 [https://bugs.python.org/issue?@action=redirect&bpo=35833]: Revise IDLE doc for control codes sent to Shell. Add a code example block.

bpo-35689 [https://bugs.python.org/issue?@action=redirect&bpo=35689]: Add docstrings and unittests for colorizer.py.

Python 3.8.0 alpha 1

Release date: 2019-02-03

Security

bpo-35746 [https://bugs.python.org/issue?@action=redirect&bpo=35746]: CVE-2019-5010 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=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.

bpo-34812 [https://bugs.python.org/issue?@action=redirect&bpo=34812]: The -I command line option (run Python in isolated mode) is now also copied by the multiprocessing and distutils modules when spawning child processes. Previously, only -E and -s options (enabled by -I) were copied.

bpo-34791 [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.

bpo-17239 [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.

bpo-34623 [https://bugs.python.org/issue?@action=redirect&bpo=34623]: CVE-2018-14647 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-14647]: The C accelerated _elementtree module now initializes hash randomization salt from _Py_HashSecret instead of libexpat's default CSPRNG.

bpo-34405 [https://bugs.python.org/issue?@action=redirect&bpo=34405]: Updated to OpenSSL 1.1.0i for Windows builds.

bpo-33871 [https://bugs.python.org/issue?@action=redirect&bpo=33871]: Fixed sending the part of the file in os.sendfile() on macOS. Using the trailers argument could cause sending more bytes from the input file than was specified.

bpo-32533 [https://bugs.python.org/issue?@action=redirect&bpo=32533]: Fixed thread-safety of error handling in _ssl.

bpo-33136 [https://bugs.python.org/issue?@action=redirect&bpo=33136]: Harden ssl module against LibreSSL CVE-2018-8970 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-8970]. X509_VERIFY_PARAM_set1_host() is called with an explicit namelen. A new test ensures that NULL bytes are not allowed.

bpo-33001 [https://bugs.python.org/issue?@action=redirect&bpo=33001]: Minimal fix to prevent buffer overrun in os.symlink on Windows

bpo-32981 [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 CVE-2018-1060 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-1060] and CVE-2018-1061 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-1061]. Patch by Jamie Davis.

bpo-28414 [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.

Core and Builtins

bpo-35877 [https://bugs.python.org/issue?@action=redirect&bpo=35877]: Make parenthesis optional for named expressions in while statement. Patch by Karthikeyan Singaravelan.

bpo-35814 [https://bugs.python.org/issue?@action=redirect&bpo=35814]: Allow same right hand side expressions in annotated assignments as in normal ones. In particular, x: Tuple[int, int] = 1, 2 (without parentheses on the right) is now allowed.

bpo-35766 [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](https://github.com/python/typed_ast).

bpo-35713 [https://bugs.python.org/issue?@action=redirect&bpo=35713]: Reorganize Python initialization to get working exceptions and sys.stderr earlier.

bpo-33416 [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.

bpo-35720 [https://bugs.python.org/issue?@action=redirect&bpo=35720]: Fixed a minor memory leak in pymain_parse_cmdline_impl function in Modules/main.c

bpo-35634 [https://bugs.python.org/issue?@action=redirect&bpo=35634]: func(**kwargs) will now raise an error when kwargs is a mapping containing multiple entries with the same key. An error was already raised when other keyword arguments are passed before **kwargs since Python 3.6.

bpo-35623 [https://bugs.python.org/issue?@action=redirect&bpo=35623]: Fix a crash when sorting very long lists. Patch by Stephan Hohe.

bpo-35214 [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.

bpo-35560 [https://bugs.python.org/issue?@action=redirect&bpo=35560]: Fix an assertion error in 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.

bpo-35552 [https://bugs.python.org/issue?@action=redirect&bpo=35552]: Format characters %s and %V in PyUnicode_FromFormat() and %s in PyBytes_FromFormat() no longer read memory past the limit if precision is specified.

bpo-35504 [https://bugs.python.org/issue?@action=redirect&bpo=35504]: Fix segfaults and SystemErrors when deleting certain attributes. Patch by Zackery Spytz.

bpo-35504 [https://bugs.python.org/issue?@action=redirect&bpo=35504]: Fixed a SystemError when delete the characters_written attribute of an OSError.

bpo-35494 [https://bugs.python.org/issue?@action=redirect&bpo=35494]: Improved syntax error messages for unbalanced parentheses in f-string.

bpo-35444 [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.

bpo-35436 [https://bugs.python.org/issue?@action=redirect&bpo=35436]: Fix various issues with memory allocation error handling. Patch by Zackery Spytz.

bpo-35423 [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.

bpo-35357 [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.

bpo-35372 [https://bugs.python.org/issue?@action=redirect&bpo=35372]: Fixed the code page decoder for input longer than 2 GiB containing undecodable bytes.

bpo-35336 [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".

bpo-31241 [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.

bpo-33954 [https://bugs.python.org/issue?@action=redirect&bpo=33954]: For str.format(), float.__format__() and complex.__format__() methods for non-ASCII decimal point when using the "n" formatter.

bpo-35269 [https://bugs.python.org/issue?@action=redirect&bpo=35269]: Fix a possible segfault involving a newly created coroutine. Patch by Zackery Spytz.

bpo-35224 [https://bugs.python.org/issue?@action=redirect&bpo=35224]: Implement PEP 572 [https://peps.python.org/pep-0572/] (assignment expressions). Patch by Emily Morehouse.

bpo-32492 [https://bugs.python.org/issue?@action=redirect&bpo=32492]: Speed up namedtuple() attribute access by 1.6x using a C fast-path for the name descriptors. Patch by Pablo Galindo.

bpo-35214 [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 '\N'. It would read one byte beyond the end of the memory allocation.

bpo-35214 [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.

bpo-35193 [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.

bpo-35169 [https://bugs.python.org/issue?@action=redirect&bpo=35169]: Improved error messages for forbidden assignments.

bpo-34022 [https://bugs.python.org/issue?@action=redirect&bpo=34022]: Fix handling of hash-based bytecode files in zipimport. Patch by Elvis Pranskevichus.

bpo-28401 [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.

bpo-29341 [https://bugs.python.org/issue?@action=redirect&bpo=29341]: Clarify in the docstrings of os methods that path-like objects are also accepted as input parameters.

bpo-35050 [https://bugs.python.org/issue?@action=redirect&bpo=35050]: socket: Fix off-by-one bug in length check for AF_ALG name and type.

bpo-29743 [https://bugs.python.org/issue?@action=redirect&bpo=29743]: Raise ValueError instead of OverflowError in case of a negative _length_ in a ctypes.Array subclass. Also raise TypeError instead of AttributeError for non-integer _length_. Original patch by Oren Milman.

bpo-16806 [https://bugs.python.org/issue?@action=redirect&bpo=16806]: Fix lineno and col_offset for multi-line string tokens.

bpo-35029 [https://bugs.python.org/issue?@action=redirect&bpo=35029]: SyntaxWarning raised as an exception at code generation time will be now replaced with a SyntaxError for better error reporting.

bpo-34983 [https://bugs.python.org/issue?@action=redirect&bpo=34983]: Expose symtable.Symbol.is_nonlocal() in the symtable module. Patch by Pablo Galindo.

bpo-34974 [https://bugs.python.org/issue?@action=redirect&bpo=34974]: bytes and bytearray constructors no longer convert unexpected exceptions (e.g. MemoryError and KeyboardInterrupt) to TypeError.

bpo-34939 [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.

bpo-34973 [https://bugs.python.org/issue?@action=redirect&bpo=34973]: Fixed crash in bytes() when the list argument is mutated while it is iterated.

bpo-34876 [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 def, async def and 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.

bpo-34879 [https://bugs.python.org/issue?@action=redirect&bpo=34879]: Fix a possible null pointer dereference in bytesobject.c. Patch by Zackery Spytz.

bpo-34784 [https://bugs.python.org/issue?@action=redirect&bpo=34784]: Fix the implementation of PyStructSequence_NewType in order to create heap allocated StructSequences.

bpo-32912 [https://bugs.python.org/issue?@action=redirect&bpo=32912]: A SyntaxWarning is now emitted instead of a DeprecationWarning for invalid escape sequences in string and bytes literals.

bpo-34854 [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.

bpo-34850 [https://bugs.python.org/issue?@action=redirect&bpo=34850]: The compiler now produces a SyntaxWarning when identity checks (is and 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 (== and !=) instead.

bpo-34824 [https://bugs.python.org/issue?@action=redirect&bpo=34824]: Fix a possible null pointer dereference in Modules/_ssl.c. Patch by Zackery Spytz.

bpo-30156 [https://bugs.python.org/issue?@action=redirect&bpo=30156]: The C function property_descr_get() uses a "cached" tuple to optimize function calls. But this tuple can be discovered in debug mode with sys.getobjects(). Remove the optimization, it's not really worth it and it causes 3 different crashes last years.

bpo-34762 [https://bugs.python.org/issue?@action=redirect&bpo=34762]: Fix contextvars C API to use PyObject* pointer types.

bpo-34751 [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.

bpo-34735 [https://bugs.python.org/issue?@action=redirect&bpo=34735]: Fix a memory leak in Modules/timemodule.c. Patch by Zackery Spytz.

bpo-34683 [https://bugs.python.org/issue?@action=redirect&bpo=34683]: Fixed a bug where some SyntaxError error pointed to locations that were off-by-one.

bpo-34651 [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.

bpo-34653 [https://bugs.python.org/issue?@action=redirect&bpo=34653]: Remove unused function PyParser_SimpleParseStringFilename.

bpo-32236 [https://bugs.python.org/issue?@action=redirect&bpo=32236]: Warn that line buffering is not supported if open() is called with binary mode and buffering=1.

bpo-34641 [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, f((keyword)=arg) is now disallowed.

bpo-34637 [https://bugs.python.org/issue?@action=redirect&bpo=34637]: Make the start argument to sum() visible as a keyword argument.

bpo-1621 [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.

bpo-34588 [https://bugs.python.org/issue?@action=redirect&bpo=34588]: Fix an off-by-one in the recursive call pruning feature of traceback formatting.

bpo-34485 [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, "").

bpo-34485 [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).

bpo-34485 [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".

bpo-34485 [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.

bpo-34527 [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".

bpo-34527 [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.

bpo-34403 [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).

bpo-34523 [https://bugs.python.org/issue?@action=redirect&bpo=34523]: The Python filesystem encoding is now read earlier during the Python initialization.

bpo-12458 [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.

bpo-34408 [https://bugs.python.org/issue?@action=redirect&bpo=34408]: Prevent a null pointer dereference and resource leakage in PyInterpreterState_New().

bpo-34400 [https://bugs.python.org/issue?@action=redirect&bpo=34400]: Fix undefined behavior in parsetok.c. Patch by Zackery Spytz.

bpo-33073 [https://bugs.python.org/issue?@action=redirect&bpo=33073]: Added as_integer_ratio to ints to make them more interoperable with floats.

bpo-34377 [https://bugs.python.org/issue?@action=redirect&bpo=34377]: Update valgrind suppression list to use _PyObject_Free/_PyObject_Realloc instead of PyObject_Free/PyObject_Realloc.

bpo-34353 [https://bugs.python.org/issue?@action=redirect&bpo=34353]: Added the "socket" option in the stat.filemode() Python implementation to match the C implementation.

bpo-34320 [https://bugs.python.org/issue?@action=redirect&bpo=34320]: Fix dict(od) didn't copy iteration order of OrderedDict.

bpo-34113 [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.

bpo-34100 [https://bugs.python.org/issue?@action=redirect&bpo=34100]: Compiler now merges constants in tuples and frozensets recursively. Code attributes like co_names are merged too.

bpo-34151 [https://bugs.python.org/issue?@action=redirect&bpo=34151]: Performance of list concatenation, repetition and slicing operations is slightly improved. Patch by Sergey Fedoseev.

bpo-34170 [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.

bpo-33237 [https://bugs.python.org/issue?@action=redirect&bpo=33237]: Improved AttributeError message for partially initialized module.

bpo-34149 [https://bugs.python.org/issue?@action=redirect&bpo=34149]: Fix min and max functions to get default behavior when key is None.

bpo-34125 [https://bugs.python.org/issue?@action=redirect&bpo=34125]: Profiling of unbound built-in methods now works when **kwargs is given.

bpo-34141 [https://bugs.python.org/issue?@action=redirect&bpo=34141]: Optimized pickling atomic types (None, bool, int, float, bytes, str).

bpo-34126 [https://bugs.python.org/issue?@action=redirect&bpo=34126]: Fix crashes when profiling certain invalid calls of unbound methods. Patch by Jeroen Demeyer.

bpo-24618 [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.

bpo-34068 [https://bugs.python.org/issue?@action=redirect&bpo=34068]: In io.IOBase.close(), ensure that the closed attribute is not set with a live exception. Patch by Zackery Spytz and Serhiy Storchaka.

bpo-34087 [https://bugs.python.org/issue?@action=redirect&bpo=34087]: Fix buffer overflow while converting unicode to numeric values.

bpo-34080 [https://bugs.python.org/issue?@action=redirect&bpo=34080]: Fixed a memory leak in the compiler when it raised some uncommon errors during tokenizing.

bpo-34066 [https://bugs.python.org/issue?@action=redirect&bpo=34066]: Disabled interruption by Ctrl-C between calling open() and entering a with block in with open().

bpo-34042 [https://bugs.python.org/issue?@action=redirect&bpo=34042]: Fix dict.copy() to maintain correct total refcount (as reported by sys.gettotalrefcount()).

bpo-33418 [https://bugs.python.org/issue?@action=redirect&bpo=33418]: Fix potential memory leak in function object when it creates reference cycle.

bpo-33985 [https://bugs.python.org/issue?@action=redirect&bpo=33985]: Implement contextvars.ContextVar.name attribute.

bpo-33956 [https://bugs.python.org/issue?@action=redirect&bpo=33956]: Update vendored Expat library copy to version 2.2.5.

bpo-24596 [https://bugs.python.org/issue?@action=redirect&bpo=24596]: Decref the module object in PyRun_SimpleFileExFlags() before calling PyErr_Print(). Patch by Zackery Spytz.

bpo-33451 [https://bugs.python.org/issue?@action=redirect&bpo=33451]: Close directly executed pyc files before calling PyEval_EvalCode().

bpo-1617161 [https://bugs.python.org/issue?@action=redirect&bpo=1617161]: The hash of 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 ModuleType and MethodWrapperType instances (methods of user-defined classes and some methods of built-in classes like str.__add__) now depend on the hash and equality of the identity of __self__ instead of its value. MethodWrapperType instances no longer support ordering.

bpo-33824 [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.

bpo-33803 [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.

bpo-33738 [https://bugs.python.org/issue?@action=redirect&bpo=33738]: Seven macro incompatibilities with the Limited API were fixed, and the macros PyIter_Check(), PyIndex_Check() and PyExceptionClass_Name() were added as functions. A script for automatic macro checks was added.

bpo-33786 [https://bugs.python.org/issue?@action=redirect&bpo=33786]: Fix asynchronous generators to handle GeneratorExit in athrow() correctly

bpo-30167 [https://bugs.python.org/issue?@action=redirect&bpo=30167]: PyRun_SimpleFileExFlags removes __cached__ from module in addition to __file__.

bpo-33706 [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!

bpo-33597 [https://bugs.python.org/issue?@action=redirect&bpo=33597]: Reduce PyGC_Head size from 3 words to 2 words.

bpo-30654 [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.

bpo-33622 [https://bugs.python.org/issue?@action=redirect&bpo=33622]: Fixed a leak when the garbage collector fails to add an object with the __del__ method or referenced by it into the gc.garbage list. PyGC_Collect() can now be called when an exception is set and preserves it.

bpo-33462 [https://bugs.python.org/issue?@action=redirect&bpo=33462]: Make dict and dict views reversible. Patch by Rémi Lapeyre.

bpo-23722 [https://bugs.python.org/issue?@action=redirect&bpo=23722]: A RuntimeError is now raised when the custom metaclass doesn't provide the __classcell__ entry in the namespace passed to type.__new__. A DeprecationWarning was emitted in Python 3.6--3.7.

bpo-33499 [https://bugs.python.org/issue?@action=redirect&bpo=33499]: Add PYTHONPYCACHEPREFIX environment variable and -X pycache_prefix command-line option to set an alternate root directory for writing module bytecode cache files.

bpo-25711 [https://bugs.python.org/issue?@action=redirect&bpo=25711]: The zipimport module has been rewritten in pure Python.

bpo-33509 [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.

bpo-31849 [https://bugs.python.org/issue?@action=redirect&bpo=31849]: Fix signed/unsigned comparison warning in pyhash.c.

bpo-33475 [https://bugs.python.org/issue?@action=redirect&bpo=33475]: Fixed miscellaneous bugs in converting annotations to strings and optimized parentheses in the string representation.

bpo-20104 [https://bugs.python.org/issue?@action=redirect&bpo=20104]: Added support for the setpgroup, resetids, setsigmask, setsigdef and scheduler parameters of posix_spawn. Patch by Pablo Galindo.

bpo-33391 [https://bugs.python.org/issue?@action=redirect&bpo=33391]: Fix a leak in set_symmetric_difference().

bpo-33363 [https://bugs.python.org/issue?@action=redirect&bpo=33363]: Raise a SyntaxError for async with and async for statements outside of async functions.

bpo-28055 [https://bugs.python.org/issue?@action=redirect&bpo=28055]: Fix unaligned accesses in siphash24(). Patch by Rolf Eike Beer.

bpo-33128 [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.

bpo-33331 [https://bugs.python.org/issue?@action=redirect&bpo=33331]: Modules imported last are now cleared first at interpreter shutdown.

bpo-33312 [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.

bpo-33305 [https://bugs.python.org/issue?@action=redirect&bpo=33305]: Improved syntax error messages for invalid numerical literals.

bpo-33306 [https://bugs.python.org/issue?@action=redirect&bpo=33306]: Improved syntax error messages for unbalanced parentheses.

bpo-33234 [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.

bpo-33270 [https://bugs.python.org/issue?@action=redirect&bpo=33270]: Intern the names for all anonymous code objects. Patch by Zackery Spytz.

bpo-30455 [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 Grammar/Tokens.

bpo-33176 [https://bugs.python.org/issue?@action=redirect&bpo=33176]: Add a toreadonly() method to memoryviews.

bpo-33231 [https://bugs.python.org/issue?@action=redirect&bpo=33231]: Fix potential memory leak in normalizestring().

bpo-33205 [https://bugs.python.org/issue?@action=redirect&bpo=33205]: Change dict growth function from round_up_to_power_2(used*2+hashtable_size/2) to round_up_to_power_2(used*3). Previously, dict is shrinked only when used == 0. Now dict has more chance to be shrinked.

bpo-29922 [https://bugs.python.org/issue?@action=redirect&bpo=29922]: Improved error messages in 'async with' when __aenter__() or __aexit__() return non-awaitable object.

bpo-33199 [https://bugs.python.org/issue?@action=redirect&bpo=33199]: Fix ma_version_tag in dict implementation is uninitialized when copying from key-sharing dict.

bpo-33053 [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)

bpo-33138 [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".

bpo-33018 [https://bugs.python.org/issue?@action=redirect&bpo=33018]: Improve consistency of errors raised by issubclass() when called with a non-class and an abstract base class as the first and second arguments, respectively. Patch by Josh Bronson.

bpo-33083 [https://bugs.python.org/issue?@action=redirect&bpo=33083]: math.factorial no longer accepts arguments that are not int-like. Patch by Pablo Galindo.

bpo-33041 [https://bugs.python.org/issue?@action=redirect&bpo=33041]: Added new opcode END_ASYNC_FOR and fixes the following issues:

Setting global StopAsyncIteration no longer breaks async for loops.

Jumping into an async for loop is now disabled.

Jumping out of an async for loop no longer corrupts the stack.

bpo-25750 [https://bugs.python.org/issue?@action=redirect&bpo=25750]: Fix rare Python crash due to bad refcounting in type_getattro() if a descriptor deletes itself from the class. Patch by Jeroen Demeyer.

bpo-33041 [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.

bpo-33026 [https://bugs.python.org/issue?@action=redirect&bpo=33026]: Fixed jumping out of "with" block by setting f_lineno.

bpo-33005 [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.

bpo-32911 [https://bugs.python.org/issue?@action=redirect&bpo=32911]: Due to unexpected compatibility issues discovered during downstream beta testing, reverted bpo-29463 [https://bugs.python.org/issue?@action=redirect&bpo=29463]. 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.

bpo-17288 [https://bugs.python.org/issue?@action=redirect&bpo=17288]: Prevent jumps from 'return' and 'exception' trace events.

bpo-32946 [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.

bpo-32932 [https://bugs.python.org/issue?@action=redirect&bpo=32932]: Make error message more revealing when there are non-str objects in __all__.

bpo-32925 [https://bugs.python.org/issue?@action=redirect&bpo=32925]: Optimized iterating and containing test for literal lists consisting of non-constants: x in [a, b] and for x in [a, b]. The case of all constant elements already was optimized.

bpo-32889 [https://bugs.python.org/issue?@action=redirect&bpo=32889]: Update Valgrind suppression list to account for the rename of Py_ADDRESS_IN_RANG to address_in_range.

bpo-32836 [https://bugs.python.org/issue?@action=redirect&bpo=32836]: Don't use temporary variables in cases of list/dict/set comprehensions

bpo-31356 [https://bugs.python.org/issue?@action=redirect&bpo=31356]: Remove the new API added in bpo-31356 [https://bugs.python.org/issue?@action=redirect&bpo=31356] (gc.ensure_disabled() context manager).

bpo-32305 [https://bugs.python.org/issue?@action=redirect&bpo=32305]: For namespace packages, ensure that both __file__ and __spec__.origin are set to None.

bpo-32303 [https://bugs.python.org/issue?@action=redirect&bpo=32303]: Make sure __spec__.loader matches __loader__ for namespace packages.

bpo-32711 [https://bugs.python.org/issue?@action=redirect&bpo=32711]: Fix the warning messages for Python/ast_unparse.c. Patch by Stéphane Wirtel

bpo-32583 [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.

bpo-32489 [https://bugs.python.org/issue?@action=redirect&bpo=32489]: A continue statement is now allowed in the finally clause.

bpo-17611 [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 break, continue and return.

Removed opcodes BREAK_LOOP, CONTINUE_LOOP, SETUP_LOOP and SETUP_EXCEPT. Added new opcodes ROT_FOUR, BEGIN_FINALLY and CALL_FINALLY and POP_FINALLY. Changed the behavior of END_FINALLY and WITH_CLEANUP_START.

bpo-32285 [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.

bpo-10544 [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.

bpo-32117 [https://bugs.python.org/issue?@action=redirect&bpo=32117]: Iterable unpacking is now allowed without parentheses in yield and return statements, e.g. yield 1, 2, 3, *rest. Thanks to David Cuthbert for the change and Jordan Chapman for added tests.

bpo-31902 [https://bugs.python.org/issue?@action=redirect&bpo=31902]: Fix the col_offset attribute for ast nodes ast.AsyncFor, ast.AsyncFunctionDef, and ast.AsyncWith. Previously, col_offset pointed to the keyword after async.

bpo-25862 [https://bugs.python.org/issue?@action=redirect&bpo=25862]: Fix assertion failures in the tell() method of io.TextIOWrapper. Patch by Zackery Spytz.

bpo-21983 [https://bugs.python.org/issue?@action=redirect&bpo=21983]: Fix a crash in ctypes.cast() in case the type argument is a ctypes structured data type. Patch by Eryk Sun and Oren Milman.

bpo-31577 [https://bugs.python.org/issue?@action=redirect&bpo=31577]: Fix a crash in os.utime() in case of a bad ns argument. Patch by Oren Milman.

bpo-29832 [https://bugs.python.org/issue?@action=redirect&bpo=29832]: Remove references to 'getsockaddrarg' from various socket error messages. Patch by Oren Milman.

Library

bpo-35845 [https://bugs.python.org/issue?@action=redirect&bpo=35845]: Add 'order' parameter to memoryview.tobytes().

bpo-35864 [https://bugs.python.org/issue?@action=redirect&bpo=35864]: The _asdict() method for collections.namedtuple now returns a regular dict instead of an OrderedDict.

bpo-35537 [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)

bpo-35847 [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.

bpo-35813 [https://bugs.python.org/issue?@action=redirect&bpo=35813]: Shared memory submodule added to multiprocessing to avoid need for serialization between processes

bpo-35780 [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.

bpo-35537 [https://bugs.python.org/issue?@action=redirect&bpo=35537]: os.posix_spawn() and os.posix_spawnp() now have a setsid parameter.

bpo-23846 [https://bugs.python.org/issue?@action=redirect&bpo=23846]: asyncio.ProactorEventLoop now catches and logs send errors when the self-pipe is full.

bpo-34323 [https://bugs.python.org/issue?@action=redirect&bpo=34323]: asyncio: Enhance IocpProactor.close() log: wait 1 second before the first log, then log every second. Log also the number of seconds since close() was called.

bpo-35674 [https://bugs.python.org/issue?@action=redirect&bpo=35674]: Add a new os.posix_spawnp() function. Patch by Joannah Nanjekye.

bpo-35733 [https://bugs.python.org/issue?@action=redirect&bpo=35733]: ast.Constant(boolean) no longer an instance of ast.Num. Patch by Anthony Sottile.

bpo-35726 [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.

bpo-35719 [https://bugs.python.org/issue?@action=redirect&bpo=35719]: Sped up multi-argument math functions atan2(), copysign(), remainder() and hypot() by 1.3--2.5 times.

bpo-35717 [https://bugs.python.org/issue?@action=redirect&bpo=35717]: Fix KeyError exception raised when using enums and compile. Patch contributed by Rémi Lapeyre.

bpo-35699 [https://bugs.python.org/issue?@action=redirect&bpo=35699]: Fixed detection of Visual Studio Build Tools 2017 in distutils

bpo-32710 [https://bugs.python.org/issue?@action=redirect&bpo=32710]: Fix memory leaks in asyncio ProactorEventLoop on overlapped operation failure.

bpo-35702 [https://bugs.python.org/issue?@action=redirect&bpo=35702]: The time.CLOCK_UPTIME_RAW constant is now available for macOS 10.12.

bpo-32710 [https://bugs.python.org/issue?@action=redirect&bpo=32710]: Fix a memory leak in asyncio in the ProactorEventLoop when ReadFile() or WSASend() overlapped operation fail immediately: release the internal buffer.

bpo-35682 [https://bugs.python.org/issue?@action=redirect&bpo=35682]: Fix asyncio.ProactorEventLoop.sendfile(): don't attempt to set the result of an internal future if it's already done.

bpo-35283 [https://bugs.python.org/issue?@action=redirect&bpo=35283]: Add a deprecated warning for the threading.Thread.isAlive() method. Patch by Donghee Na.

bpo-35664 [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).

bpo-35643 [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.

bpo-35619 [https://bugs.python.org/issue?@action=redirect&bpo=35619]: Improved support of custom data descriptors in help() and pydoc.

bpo-28503 [https://bugs.python.org/issue?@action=redirect&bpo=28503]: The crypt module now internally uses the crypt_r() library function instead of crypt() when available.

bpo-35614 [https://bugs.python.org/issue?@action=redirect&bpo=35614]: Fixed help() on metaclasses. Patch by Sanyam Khurana.

bpo-35568 [https://bugs.python.org/issue?@action=redirect&bpo=35568]: Expose raise(signum) as raise_signal

bpo-35588 [https://bugs.python.org/issue?@action=redirect&bpo=35588]: The floor division and modulo operations and the divmod() function on fractions.Fraction types are 2--4x faster. Patch by Stefan Behnel.

bpo-35585 [https://bugs.python.org/issue?@action=redirect&bpo=35585]: Speed-up building enums by value, e.g. http.HTTPStatus(200).

bpo-30561 [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.

bpo-35537 [https://bugs.python.org/issue?@action=redirect&bpo=35537]: The subprocess module can now use the os.posix_spawn() function in some cases for better performance.

bpo-35526 [https://bugs.python.org/issue?@action=redirect&bpo=35526]: Delaying the 'joke' of barry_as_FLUFL.mandatory to Python version 4.0

bpo-35523 [https://bugs.python.org/issue?@action=redirect&bpo=35523]: Remove ctypes callback workaround: no longer create a callback at startup. Avoid SELinux alert on import ctypes and import uuid.

bpo-31784 [https://bugs.python.org/issue?@action=redirect&bpo=31784]: uuid.uuid1() now calls time.time_ns() rather than int(time.time() * 1e9).

bpo-35513 [https://bugs.python.org/issue?@action=redirect&bpo=35513]: TextTestRunner of unittest.runner now uses time.perf_counter() rather than time.time() to measure the execution time of a test: time.time() can go backwards, whereas time.perf_counter() is monotonic.

bpo-35502 [https://bugs.python.org/issue?@action=redirect&bpo=35502]: Fixed reference leaks in xml.etree.ElementTree.TreeBuilder in case of unfinished building of the tree (in particular when an error was raised during parsing XML).

bpo-35348 [https://bugs.python.org/issue?@action=redirect&bpo=35348]: Make platform.architecture() parsing of file command output more reliable: add the -b option to the file command to omit the filename, force the usage of the C locale, and search also the "shared object" pattern.

bpo-35491 [https://bugs.python.org/issue?@action=redirect&bpo=35491]: multiprocessing: Add Pool.__repr__() and enhance BaseProcess.__repr__() (add pid and parent pid) to ease debugging. Pool state constant values are now strings instead of integers, for example RUN value becomes 'RUN' instead of 0.

bpo-35477 [https://bugs.python.org/issue?@action=redirect&bpo=35477]: multiprocessing.Pool.__enter__() now fails if the pool is not running: with pool: fails if used more than once.

bpo-31446 [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.

bpo-35471 [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.

bpo-23057 [https://bugs.python.org/issue?@action=redirect&bpo=23057]: Unblock Proactor event loop when keyboard interrupt is received on Windows

bpo-35052 [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.

bpo-20239 [https://bugs.python.org/issue?@action=redirect&bpo=20239]: Allow repeated assignment deletion of unittest.mock.Mock attributes. Patch by Pablo Galindo.

bpo-17185 [https://bugs.python.org/issue?@action=redirect&bpo=17185]: Set __signature__ on mock for inspect to get signature. Patch by Karthikeyan Singaravelan.

bpo-35445 [https://bugs.python.org/issue?@action=redirect&bpo=35445]: Memory errors during creating posix.environ no longer ignored.

bpo-35415 [https://bugs.python.org/issue?@action=redirect&bpo=35415]: Validate fileno= argument to socket.socket().

bpo-35424 [https://bugs.python.org/issue?@action=redirect&bpo=35424]: multiprocessing.Pool destructor now emits ResourceWarning if the pool is still running.

bpo-35330 [https://bugs.python.org/issue?@action=redirect&bpo=35330]: When a Mock instance was used to wrap an object, if 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.

bpo-35346 [https://bugs.python.org/issue?@action=redirect&bpo=35346]: Drop Mac OS 9 and Rhapsody support from the platform module. Rhapsody last release was in 2000. Mac OS 9 last release was in 2001.

bpo-10496 [https://bugs.python.org/issue?@action=redirect&bpo=10496]: check_environ() of distutils.utils now catches KeyError on calling pwd.getpwuid(): don't create the HOME environment variable in this case.

bpo-10496 [https://bugs.python.org/issue?@action=redirect&bpo=10496]: posixpath.expanduser() now returns the input path unchanged if the 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 site module if the current user doesn't exist in the password database (if the user has no home directory).

bpo-35389 [https://bugs.python.org/issue?@action=redirect&bpo=35389]: platform.libc_ver() now uses os.confstr('CS_GNU_LIBC_VERSION') if available and the executable parameter is not set.

bpo-35394 [https://bugs.python.org/issue?@action=redirect&bpo=35394]: Add empty slots to asyncio abstract protocols.

bpo-35310 [https://bugs.python.org/issue?@action=redirect&bpo=35310]: Fix a bug in 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. select.select() will now always return empty lists if a timeout has occurred. Patch by Oran Avraham.

bpo-35380 [https://bugs.python.org/issue?@action=redirect&bpo=35380]: Enable TCP_NODELAY on Windows for proactor asyncio event loop.

bpo-35341 [https://bugs.python.org/issue?@action=redirect&bpo=35341]: Add generic version of collections.OrderedDict to the typing module. Patch by Ismo Toijala.

bpo-35371 [https://bugs.python.org/issue?@action=redirect&bpo=35371]: Fixed possible crash in os.utime() on Windows when pass incorrect arguments.

bpo-35346 [https://bugs.python.org/issue?@action=redirect&bpo=35346]: platform.uname() now redirects stderr to os.devnull when running external programs like cmd /c ver.

bpo-35066 [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 '%'.

bpo-35345 [https://bugs.python.org/issue?@action=redirect&bpo=35345]: The function platform.popen has been removed, it was deprecated since Python 3.3: use os.popen() instead.

bpo-35344 [https://bugs.python.org/issue?@action=redirect&bpo=35344]: On macOS, platform.platform() now uses platform.mac_ver(), if it returns a non-empty release string, to get the macOS version rather than the darwin version.

bpo-35312 [https://bugs.python.org/issue?@action=redirect&bpo=35312]: Make lib2to3.pgen2.parse.ParseError round-trip pickle-able. Patch by Anthony Sottile.

bpo-35308 [https://bugs.python.org/issue?@action=redirect&bpo=35308]: Fix regression in webbrowser where default browsers may be preferred over browsers in the BROWSER environment variable.

bpo-24746 [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.

bpo-28604 [https://bugs.python.org/issue?@action=redirect&bpo=28604]: locale.localeconv() now sets temporarily the LC_CTYPE locale to the LC_MONETARY locale if the two locales are different and monetary strings are non-ASCII. This temporary change affects other threads.

bpo-35277 [https://bugs.python.org/issue?@action=redirect&bpo=35277]: Update ensurepip to install pip 18.1 and setuptools 40.6.2.

bpo-24209 [https://bugs.python.org/issue?@action=redirect&bpo=24209]: Adds IPv6 support when invoking http.server directly.

bpo-35226 [https://bugs.python.org/issue?@action=redirect&bpo=35226]: Recursively check arguments when testing for equality of unittest.mock.call objects and add note that tracking of parameters used to create ancestors of mocks in mock_calls is not possible.

bpo-29564 [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.

bpo-35189 [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

bpo-30064 [https://bugs.python.org/issue?@action=redirect&bpo=30064]: Use add_done_callback() in sock_* asyncio API to unsubscribe reader/writer early on calcellation.

bpo-35186 [https://bugs.python.org/issue?@action=redirect&bpo=35186]: Removed the "built with" comment added when setup.py upload is used with either bdist_rpm or bdist_dumb.

bpo-35152 [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.

bpo-35062 [https://bugs.python.org/issue?@action=redirect&bpo=35062]: Fix incorrect parsing of _io.IncrementalNewlineDecoder's translate argument.

bpo-35065 [https://bugs.python.org/issue?@action=redirect&bpo=35065]: Remove StreamReaderProtocol._untrack_reader. The call to _untrack_reader is currently performed too soon, causing the protocol to forget about the reader before connection_lost can run and feed the EOF to the reader.

bpo-34160 [https://bugs.python.org/issue?@action=redirect&bpo=34160]: ElementTree and minidom now preserve the attribute order specified by the user.

bpo-35079 [https://bugs.python.org/issue?@action=redirect&bpo=35079]: Improve difflib.SequenceManager.get_matching_blocks doc by adding 'non-overlapping' and changing '!=' to '<'.

bpo-33710 [https://bugs.python.org/issue?@action=redirect&bpo=33710]: Deprecated l*gettext() functions and methods in the 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 l*gettext() functions and methods.

bpo-35017 [https://bugs.python.org/issue?@action=redirect&bpo=35017]: socketserver.BaseServer.serve_forever() now exits immediately if it's shutdown() method is called while it is polling for new events.

bpo-35024 [https://bugs.python.org/issue?@action=redirect&bpo=35024]: importlib no longer logs wrote <bytecode path> redundantly after (created|could not create) <bytecode path> is already logged. Patch by Quentin Agren.

bpo-35047 [https://bugs.python.org/issue?@action=redirect&bpo=35047]: unittest.mock now includes mock calls in exception messages if assert_not_called, assert_called_once, or assert_called_once_with fails. Patch by Petter Strandmark.

bpo-31047 [https://bugs.python.org/issue?@action=redirect&bpo=31047]: Fix ntpath.abspath regression where it didn't remove a trailing separator on Windows. Patch by Tim Graham.

bpo-35053 [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).

bpo-31553 [https://bugs.python.org/issue?@action=redirect&bpo=31553]: Add the --json-lines option to json.tool. Patch by hongweipeng.

bpo-34794 [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.

bpo-34909 [https://bugs.python.org/issue?@action=redirect&bpo=34909]: Enum: fix grandchildren subclassing when parent mixed with concrete data types.

bpo-35022 [https://bugs.python.org/issue?@action=redirect&bpo=35022]: unittest.mock.MagicMock now supports the __fspath__ method (from os.PathLike).

bpo-35008 [https://bugs.python.org/issue?@action=redirect&bpo=35008]: Fixed references leaks when call the __setstate__() method of xml.etree.ElementTree.Element in the C implementation for already initialized element.

bpo-23420 [https://bugs.python.org/issue?@action=redirect&bpo=23420]: Verify the value for the parameter '-s' of the cProfile CLI. Patch by Robert Kuska

bpo-33947 [https://bugs.python.org/issue?@action=redirect&bpo=33947]: dataclasses now handle recursive reprs without raising RecursionError.

bpo-34890 [https://bugs.python.org/issue?@action=redirect&bpo=34890]: Make inspect.iscoroutinefunction(), inspect.isgeneratorfunction() and inspect.isasyncgenfunction() work with functools.partial(). Patch by Pablo Galindo.

bpo-34521 [https://bugs.python.org/issue?@action=redirect&bpo=34521]: Use socket.CMSG_SPACE() to calculate ancillary data size instead of socket.CMSG_LEN() in multiprocessing.reduction.recvfds() as RFC 3542 [https://datatracker.ietf.org/doc/html/rfc3542.html] requires the use of the former for portable applications.

bpo-31522 [https://bugs.python.org/issue?@action=redirect&bpo=31522]: The mailbox.mbox.get_string function from_ parameter can now successfully be set to a non-default value.

bpo-34970 [https://bugs.python.org/issue?@action=redirect&bpo=34970]: Protect tasks weak set manipulation in asyncio.all_tasks()

bpo-34969 [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).

bpo-16965 [https://bugs.python.org/issue?@action=redirect&bpo=16965]: The 2to3 execfile fixer now opens the file with mode 'rb'. Patch by Zackery Spytz.

bpo-34966 [https://bugs.python.org/issue?@action=redirect&bpo=34966]: 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.

bpo-34926 [https://bugs.python.org/issue?@action=redirect&bpo=34926]: mimetypes.MimeTypes.guess_type() now accepts path-like object in addition to url strings. Patch by Mayank Asthana.

bpo-23831 [https://bugs.python.org/issue?@action=redirect&bpo=23831]: Add moveto() method to the tkinter.Canvas widget. Patch by Juliette Monsel.

bpo-34941 [https://bugs.python.org/issue?@action=redirect&bpo=34941]: Methods find(), findtext() and findall() of the Element class in the xml.etree.ElementTree module are now able to find children which are instances of Element subclasses.

bpo-32680 [https://bugs.python.org/issue?@action=redirect&bpo=32680]: smtplib.SMTP objects now always have a sock attribute present

bpo-34769 [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.

bpo-34936 [https://bugs.python.org/issue?@action=redirect&bpo=34936]: Fix TclError in tkinter.Spinbox.selection_element(). Patch by Juliette Monsel.

bpo-34829 [https://bugs.python.org/issue?@action=redirect&bpo=34829]: Add methods selection_from, selection_range, selection_present and selection_to to the tkinter.Spinbox for consistency with the tkinter.Entry widget. Patch by Juliette Monsel.

bpo-34911 [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.

bpo-34922 [https://bugs.python.org/issue?@action=redirect&bpo=34922]: Fixed integer overflow in the digest() and hexdigest() methods for the SHAKE algorithm in the hashlib module.

bpo-34925 [https://bugs.python.org/issue?@action=redirect&bpo=34925]: 25% speedup in argument parsing for the functions in the bisect module.

bpo-34900 [https://bugs.python.org/issue?@action=redirect&bpo=34900]: Fixed unittest.TestCase.debug() when used to call test methods with subtests. Patch by Bruno Oliveira.

bpo-34844 [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.

bpo-34897 [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.

bpo-34871 [https://bugs.python.org/issue?@action=redirect&bpo=34871]: Fix inspect module polluted sys.modules when parsing __text_signature__ of callable.

bpo-34898 [https://bugs.python.org/issue?@action=redirect&bpo=34898]: Add mtime argument to gzip.compress for reproducible output. Patch by Guo Ci Teo.

bpo-28441 [https://bugs.python.org/issue?@action=redirect&bpo=28441]: On Cygwin and MinGW, ensure that sys.executable always includes the full filename in the path, including the .exe suffix (unless it is a symbolic link).

bpo-34866 [https://bugs.python.org/issue?@action=redirect&bpo=34866]: Adding max_num_fields to cgi.FieldStorage to make DOS attacks harder by limiting the number of MiniFieldStorage objects created by FieldStorage.

bpo-34711 [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.

bpo-34872 [https://bugs.python.org/issue?@action=redirect&bpo=34872]: Fix self-cancellation in C implementation of asyncio.Task

bpo-34849 [https://bugs.python.org/issue?@action=redirect&bpo=34849]: Don't log waiting for 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.

bpo-34022 [https://bugs.python.org/issue?@action=redirect&bpo=34022]: The SOURCE_DATE_EPOCH environment variable no longer overrides the value of the invalidation_mode argument to py_compile.compile(), and determines its default value instead.

bpo-34819 [https://bugs.python.org/issue?@action=redirect&bpo=34819]: Use a monotonic clock to compute timeouts in Executor.map() and as_completed(), in order to prevent timeouts from deviating when the system clock is adjusted.

bpo-34758 [https://bugs.python.org/issue?@action=redirect&bpo=34758]: Add .wasm -> application/wasm to list of recognized file types and content type headers

bpo-34789 [https://bugs.python.org/issue?@action=redirect&bpo=34789]: xml.sax.make_parser() now accepts any iterable as its parser_list argument. Patch by Andrés Delfino.

bpo-34334 [https://bugs.python.org/issue?@action=redirect&bpo=34334]: In QueueHandler, clear exc_text from LogRecord to prevent traceback from being written twice.

bpo-34687 [https://bugs.python.org/issue?@action=redirect&bpo=34687]: On Windows, asyncio now uses ProactorEventLoop, instead of SelectorEventLoop, by default.

bpo-5950 [https://bugs.python.org/issue?@action=redirect&bpo=5950]: Support reading zip files with archive comments in zipimport.

bpo-32892 [https://bugs.python.org/issue?@action=redirect&bpo=32892]: The parser now represents all constants as ast.Constant instead of using specific constant AST types (Num, Str, Bytes, NameConstant and Ellipsis). These classes are considered deprecated and will be removed in future Python versions.

bpo-34728 [https://bugs.python.org/issue?@action=redirect&bpo=34728]: Add deprecation warning when loop is used in methods: asyncio.sleep, asyncio.wait and asyncio.wait_for.

bpo-34738 [https://bugs.python.org/issue?@action=redirect&bpo=34738]: ZIP files created by distutils will now include entries for directories.

bpo-34659 [https://bugs.python.org/issue?@action=redirect&bpo=34659]: Add an optional initial argument to itertools.accumulate().

bpo-29577 [https://bugs.python.org/issue?@action=redirect&bpo=29577]: Support multiple mixin classes when creating Enums.

bpo-34670 [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.

bpo-32718 [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.

bpo-31177 [https://bugs.python.org/issue?@action=redirect&bpo=31177]: Fix bug that prevented using reset_mock on mock instances with deleted attributes

bpo-34672 [https://bugs.python.org/issue?@action=redirect&bpo=34672]: Add a workaround, so the 'Z' time.strftime() specifier on the musl C library can work in some cases.

bpo-34666 [https://bugs.python.org/issue?@action=redirect&bpo=34666]: Implement asyncio.StreamWriter.awrite and asyncio.StreamWriter.aclose() coroutines. Methods are needed for providing a consistent stream API with control flow switched on by default.

bpo-6721 [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.

bpo-34658 [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.

bpo-34652 [https://bugs.python.org/issue?@action=redirect&bpo=34652]: Ensure os.lchmod() is never defined on Linux.

bpo-34638 [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 close() call.

bpo-34536 [https://bugs.python.org/issue?@action=redirect&bpo=34536]: Enum._missing_: raise ValueError if None returned and TypeError if non-member is returned.

bpo-34636 [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)

bpo-24412 [https://bugs.python.org/issue?@action=redirect&bpo=24412]: Add addModuleCleanup() and addClassCleanup() to unittest to support cleanups for setUpModule() and setUpClass(). Patch by Lisa Roach.

bpo-34630 [https://bugs.python.org/issue?@action=redirect&bpo=34630]: Don't log SSL certificate errors in asyncio code (connection error logging is skipped already).

bpo-32490 [https://bugs.python.org/issue?@action=redirect&bpo=32490]: Prevent filename duplication in subprocess exception messages. Patch by Zackery Spytz.

bpo-34363 [https://bugs.python.org/issue?@action=redirect&bpo=34363]: dataclasses.asdict() and .astuple() now handle namedtuples correctly.

bpo-34625 [https://bugs.python.org/issue?@action=redirect&bpo=34625]: Update vendorized expat library version to 2.2.6.

bpo-32270 [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.

bpo-34622 [https://bugs.python.org/issue?@action=redirect&bpo=34622]: Create a dedicated asyncio.CancelledError, asyncio.InvalidStateError and asyncio.TimeoutError exception classes. Inherit them from corresponding exceptions from concurrent.futures package. Extract asyncio exceptions into a separate file.

bpo-34610 [https://bugs.python.org/issue?@action=redirect&bpo=34610]: Fixed iterator of multiprocessing.managers.DictProxy.

bpo-34421 [https://bugs.python.org/issue?@action=redirect&bpo=34421]: Fix distutils logging for non-ASCII strings. This caused installation issues on Windows.

bpo-34604 [https://bugs.python.org/issue?@action=redirect&bpo=34604]: Fix possible mojibake in the error message of pwd.getpwnam and grp.getgrnam using string representation because of invisible characters or trailing whitespaces. Patch by William Grzybowski.

bpo-30977 [https://bugs.python.org/issue?@action=redirect&bpo=30977]: Make uuid.UUID use __slots__ to reduce its memory footprint. Based on original patch by Wouter Bolsterlee.

bpo-34574 [https://bugs.python.org/issue?@action=redirect&bpo=34574]: OrderedDict iterators are not exhausted during pickling anymore. Patch by Sergey Fedoseev.

bpo-8110 [https://bugs.python.org/issue?@action=redirect&bpo=8110]: Refactored subprocess to check for Windows-specific modules rather than sys.platform == 'win32'.

bpo-34530 [https://bugs.python.org/issue?@action=redirect&bpo=34530]: distutils.spawn.find_executable() now falls back on os.defpath if the PATH environment variable is not set.

bpo-34563 [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 2**31-1).

bpo-34558 [https://bugs.python.org/issue?@action=redirect&bpo=34558]: Correct typo in Lib/ctypes/_aix.py

bpo-34282 [https://bugs.python.org/issue?@action=redirect&bpo=34282]: Move Enum._convert to EnumMeta._convert_ and fix enum members getting shadowed by parent attributes.

bpo-22872 [https://bugs.python.org/issue?@action=redirect&bpo=22872]: When the queue is closed, ValueError is now raised by multiprocessing.Queue.put() and multiprocessing.Queue.get() instead of AssertionError and OSError, respectively. Patch by Zackery Spytz.

bpo-34515 [https://bugs.python.org/issue?@action=redirect&bpo=34515]: Fix parsing non-ASCII identifiers in lib2to3.pgen2.tokenize (PEP 3131 [https://peps.python.org/pep-3131/]).

bpo-13312 [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.

bpo-34472 [https://bugs.python.org/issue?@action=redirect&bpo=34472]: Improved compatibility for streamed files in zipfile. Previously an optional signature was not being written and certain ZIP applications were not supported. Patch by Silas Sewell.

bpo-34454 [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.

bpo-6700 [https://bugs.python.org/issue?@action=redirect&bpo=6700]: Fix inspect.getsourcelines for module level frames/tracebacks. Patch by Vladimir Matveev.

bpo-34171 [https://bugs.python.org/issue?@action=redirect&bpo=34171]: Running the trace module no longer creates the trace.cover file.

bpo-34441 [https://bugs.python.org/issue?@action=redirect&bpo=34441]: Fix crash when an ABC-derived class with invalid __subclasses__ is passed as the second argument to issubclass(). Patch by Alexey Izbyshev.

bpo-34427 [https://bugs.python.org/issue?@action=redirect&bpo=34427]: Fix infinite loop in a.extend(a) for MutableSequence subclasses.

bpo-34412 [https://bugs.python.org/issue?@action=redirect&bpo=34412]: Make signal.strsignal() work on HP-UX. Patch by Michael Osipov.

bpo-20849 [https://bugs.python.org/issue?@action=redirect&bpo=20849]: shutil.copytree now accepts a new dirs_exist_ok keyword argument. Patch by Josh Bronson.

bpo-31715 [https://bugs.python.org/issue?@action=redirect&bpo=31715]: Associate .mjs file extension with application/javascript MIME Type.

bpo-34384 [https://bugs.python.org/issue?@action=redirect&bpo=34384]: os.readlink() now accepts path-like and bytes objects on Windows.

bpo-22602 [https://bugs.python.org/issue?@action=redirect&bpo=22602]: The UTF-7 decoder now raises UnicodeDecodeError for ill-formed sequences starting with "+" (as specified in RFC 2152). Patch by Zackery Spytz.

bpo-2122 [https://bugs.python.org/issue?@action=redirect&bpo=2122]: The mmap.flush() method now returns None on success, raises an exception on error under all platforms.

bpo-34341 [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.

bpo-34333 [https://bugs.python.org/issue?@action=redirect&bpo=34333]: Fix %-formatting in pathlib.PurePath.with_suffix() when formatting an error message.

bpo-18540 [https://bugs.python.org/issue?@action=redirect&bpo=18540]: The imaplib.IMAP4 and imaplib.IMAP4_SSL classes now resolve to the local host IP correctly when the default value of host parameter ('') is used.

bpo-26502 [https://bugs.python.org/issue?@action=redirect&bpo=26502]: Implement traceback.FrameSummary.__len__() method to preserve compatibility with the old tuple API.

bpo-34318 [https://bugs.python.org/issue?@action=redirect&bpo=34318]: assertRaises(), assertRaisesRegex(), assertWarns() and 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.

bpo-9372 [https://bugs.python.org/issue?@action=redirect&bpo=9372]: Deprecate __getitem__() methods of xml.dom.pulldom.DOMEventStream, wsgiref.util.FileWrapper and fileinput.FileInput.

bpo-33613 [https://bugs.python.org/issue?@action=redirect&bpo=33613]: Fix a race condition in multiprocessing.semaphore_tracker when the tracker receives SIGINT before it can register signal handlers for ignoring it.

bpo-34248 [https://bugs.python.org/issue?@action=redirect&bpo=34248]: Report filename in the exception raised when the database file cannot be opened by dbm.gnu.open() and dbm.ndbm.open() due to OS-related error. Patch by Zsolt Cserna.

bpo-33089 [https://bugs.python.org/issue?@action=redirect&bpo=33089]: Add math.dist() to compute the Euclidean distance between two points.

bpo-34246 [https://bugs.python.org/issue?@action=redirect&bpo=34246]: smtplib.SMTP.send_message() no longer modifies the content of the mail_options argument. Patch by Pablo S. Blum de Aguiar.

bpo-31047 [https://bugs.python.org/issue?@action=redirect&bpo=31047]: Fix ntpath.abspath for invalid paths on windows. Patch by Franz Woellert.

bpo-32321 [https://bugs.python.org/issue?@action=redirect&bpo=32321]: Add pure Python fallback for functools.reduce. Patch by Robert Wright.

bpo-34270 [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 (get_name() and set_name()) and is visible in the repr() output. An initial name can also be set using the new name keyword argument to asyncio.create_task() or the create_task() method of the event loop. If no initial name is set, the default Task implementation generates a name like Task-1 using a monotonic counter.

bpo-34263 [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.

bpo-34035 [https://bugs.python.org/issue?@action=redirect&bpo=34035]: Fix several AttributeError in zipfile seek() methods. Patch by Mickaël Schoentgen.

bpo-32215 [https://bugs.python.org/issue?@action=redirect&bpo=32215]: Fix performance regression in sqlite3 when a DML statement appeared in a different line than the rest of the SQL query.

bpo-34075 [https://bugs.python.org/issue?@action=redirect&bpo=34075]: Deprecate passing non-ThreadPoolExecutor instances to AbstractEventLoop.set_default_executor().

bpo-34251 [https://bugs.python.org/issue?@action=redirect&bpo=34251]: Restore msilib.Win64 to preserve backwards compatibility since it's already used by distutils' bdist_msi command.

bpo-19891 [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.

bpo-33089 [https://bugs.python.org/issue?@action=redirect&bpo=33089]: Enhanced math.hypot() to support more than two dimensions.

bpo-34228 [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.

bpo-13041 [https://bugs.python.org/issue?@action=redirect&bpo=13041]: Use shutil.get_terminal_size() to calculate the terminal width correctly in the argparse.HelpFormatter class. Initial patch by Zbyszek Jędrzejewski-Szmek.

bpo-34213 [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".

bpo-34052 [https://bugs.python.org/issue?@action=redirect&bpo=34052]: sqlite3.Connection.create_aggregate(), sqlite3.Connection.create_function(), sqlite3.Connection.set_authorizer(), 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.

bpo-34197 [https://bugs.python.org/issue?@action=redirect&bpo=34197]: Attributes skipinitialspace, doublequote and strict of the dialect attribute of the csv reader are now bool instances instead of integers 0 or 1.

bpo-32788 [https://bugs.python.org/issue?@action=redirect&bpo=32788]: Errors other than TypeError raised in methods __adapt__() and __conform__() in the sqlite3 module are now propagated to the user.

bpo-21446 [https://bugs.python.org/issue?@action=redirect&bpo=21446]: The reload fixer now uses importlib.reload() instead of deprecated imp.reload().

bpo-940286 [https://bugs.python.org/issue?@action=redirect&bpo=940286]: pydoc's Helper.showtopic() method now prints the cross references of a topic correctly.

bpo-34164 [https://bugs.python.org/issue?@action=redirect&bpo=34164]: base64.b32decode() could raise UnboundLocalError or OverflowError for incorrect padding. Now it always raises base64.Error in these cases.

bpo-33729 [https://bugs.python.org/issue?@action=redirect&bpo=33729]: Fixed issues with arguments parsing in hashlib.

bpo-34097 [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 strict_timestamps parameter at the cost of setting the timestamp to the limit.

bpo-34108 [https://bugs.python.org/issue?@action=redirect&bpo=34108]: Remove extraneous CR in 2to3 refactor.

bpo-34070 [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 buffering=-1.

bpo-27494 [https://bugs.python.org/issue?@action=redirect&bpo=27494]: Reverted bpo-27494 [https://bugs.python.org/issue?@action=redirect&bpo=27494]. 2to3 rejects now a trailing comma in generator expressions.

bpo-33967 [https://bugs.python.org/issue?@action=redirect&bpo=33967]: functools.singledispatch now raises TypeError instead of IndexError when no positional arguments are passed.

bpo-34041 [https://bugs.python.org/issue?@action=redirect&bpo=34041]: Add the parameter deterministic to the sqlite3.Connection.create_function() method. Patch by Sergey Fedoseev.

bpo-34056 [https://bugs.python.org/issue?@action=redirect&bpo=34056]: Ensure the loader shim created by imp.load_module always returns bytes from its get_data() function. This fixes using imp.load_module with PEP 552 [https://peps.python.org/pep-0552/] hash-based pycs.

bpo-34054 [https://bugs.python.org/issue?@action=redirect&bpo=34054]: The multiprocessing module now uses the monotonic clock time.monotonic() instead of the system clock time.time() to implement timeout.

bpo-34043 [https://bugs.python.org/issue?@action=redirect&bpo=34043]: Optimize tarfile uncompress performance about 15% when gzip is used.

bpo-34044 [https://bugs.python.org/issue?@action=redirect&bpo=34044]: subprocess.Popen now copies the startupinfo argument to leave it unchanged: it will modify the copy, so that the same STARTUPINFO object can be used multiple times.

bpo-34010 [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.

bpo-34019 [https://bugs.python.org/issue?@action=redirect&bpo=34019]: webbrowser: Correct the arguments passed to Opera Browser when opening a new URL using the webbrowser module. Patch by Bumsik Kim.

bpo-34003 [https://bugs.python.org/issue?@action=redirect&bpo=34003]: csv.DictReader now creates dicts instead of OrderedDicts. Patch by Michael Selik.

bpo-33978 [https://bugs.python.org/issue?@action=redirect&bpo=33978]: Closed existing logging handlers before reconfiguration via fileConfig and dictConfig. Patch by Karthikeyan Singaravelan.

bpo-14117 [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.

bpo-33974 [https://bugs.python.org/issue?@action=redirect&bpo=33974]: Fixed passing lists and tuples of strings containing special characters ", \, {, } and \n as options to ttk widgets.

bpo-27500 [https://bugs.python.org/issue?@action=redirect&bpo=27500]: Fix getaddrinfo to resolve IPv6 addresses correctly.

bpo-24567 [https://bugs.python.org/issue?@action=redirect&bpo=24567]: Improve random.choices() to handle subnormal input weights that could occasionally trigger an IndexError.

bpo-33871 [https://bugs.python.org/issue?@action=redirect&bpo=33871]: Fixed integer overflow in os.readv(), os.writev(), os.preadv() and os.pwritev() and in os.sendfile() with headers or trailers arguments (on BSD-based OSes and macOS).

bpo-25007 [https://bugs.python.org/issue?@action=redirect&bpo=25007]: Add copy.copy() and copy.deepcopy() support to zlib compressors and decompressors. Patch by Zackery Spytz.

bpo-33929 [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.

bpo-33899 [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.

bpo-33897 [https://bugs.python.org/issue?@action=redirect&bpo=33897]: Added a 'force' keyword argument to logging.basicConfig().

bpo-33695 [https://bugs.python.org/issue?@action=redirect&bpo=33695]: shutil.copytree() uses os.scandir() function and all copy functions depending from it use cached 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 os.stat() syscalls is reduced by 38% making shutil.copytree() especially faster on network filesystems. (Contributed by Giampaolo Rodola' in bpo-33695 [https://bugs.python.org/issue?@action=redirect&bpo=33695].)

bpo-33916 [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.

bpo-32568 [https://bugs.python.org/issue?@action=redirect&bpo=32568]: Make select.epoll() and its documentation consistent regarding sizehint and flags.

bpo-33833 [https://bugs.python.org/issue?@action=redirect&bpo=33833]: Fixed bug in asyncio where ProactorSocketTransport logs AssertionError if force closed during write.

bpo-33663 [https://bugs.python.org/issue?@action=redirect&bpo=33663]: Convert content length to string before putting to header.

bpo-33721 [https://bugs.python.org/issue?@action=redirect&bpo=33721]: os.path functions that return a boolean result like exists(), lexists(), isdir(), isfile(), islink(), and ismount(), and pathlib.Path methods that return a boolean result like exists(), is_dir(), is_file(), is_mount(), is_symlink(), is_block_device(), is_char_device(), is_fifo(), is_socket() now return False instead of raising ValueError or its subclasses UnicodeEncodeError and UnicodeDecodeError for paths that contain characters or bytes unrepresentable at the OS level.

bpo-26544 [https://bugs.python.org/issue?@action=redirect&bpo=26544]: Fixed implementation of platform.libc_ver(). It almost always returned version '2.9' for glibc.

bpo-33843 [https://bugs.python.org/issue?@action=redirect&bpo=33843]: Remove deprecated cgi.escape, cgi.parse_qs and cgi.parse_qsl.

bpo-33842 [https://bugs.python.org/issue?@action=redirect&bpo=33842]: Remove tarfile.filemode which is deprecated since Python 3.3.

bpo-30167 [https://bugs.python.org/issue?@action=redirect&bpo=30167]: Prevent site.main() exception if PYTHONSTARTUP is set. Patch by Steve Weber.

bpo-33805 [https://bugs.python.org/issue?@action=redirect&bpo=33805]: Improve error message of dataclasses.replace() when an InitVar is not specified

bpo-33687 [https://bugs.python.org/issue?@action=redirect&bpo=33687]: Fix the call to os.chmod() for uu.decode() if a mode is given or decoded. Patch by Timo Furrer.

bpo-33812 [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.

bpo-32108 [https://bugs.python.org/issue?@action=redirect&bpo=32108]: In configparser, don't clear section when it is assigned to itself.

bpo-27397 [https://bugs.python.org/issue?@action=redirect&bpo=27397]: Make email module properly handle invalid-length base64 strings.

bpo-33578 [https://bugs.python.org/issue?@action=redirect&bpo=33578]: Implement multibyte encoder/decoder state methods

bpo-30805 [https://bugs.python.org/issue?@action=redirect&bpo=30805]: Avoid race condition with debug logging

bpo-33476 [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

bpo-33694 [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.

bpo-32493 [https://bugs.python.org/issue?@action=redirect&bpo=32493]: Correct test for uuid_enc_be availability in configure.ac. Patch by Michael Felt.

bpo-33792 [https://bugs.python.org/issue?@action=redirect&bpo=33792]: Add asyncio.WindowsSelectorEventLoopPolicy and asyncio.WindowsProactorEventLoopPolicy.

bpo-33274 [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.

bpo-33778 [https://bugs.python.org/issue?@action=redirect&bpo=33778]: Update unicodedata's database to Unicode version 11.0.0.

bpo-33165 [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.

bpo-33770 [https://bugs.python.org/issue?@action=redirect&bpo=33770]: improve base64 exception message for encoded inputs of invalid length

bpo-33769 [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.

bpo-33767 [https://bugs.python.org/issue?@action=redirect&bpo=33767]: The concatenation (+) and repetition (*) sequence operations now raise TypeError instead of SystemError when performed on mmap.mmap objects. Patch by Zackery Spytz.

bpo-33734 [https://bugs.python.org/issue?@action=redirect&bpo=33734]: asyncio/ssl: Fix AttributeError, increase default handshake timeout

bpo-31014 [https://bugs.python.org/issue?@action=redirect&bpo=31014]: Fixed creating a controller for webbrowser when a user specifies a path to an entry in the BROWSER environment variable. Based on patch by John Still.

bpo-2504 [https://bugs.python.org/issue?@action=redirect&bpo=2504]: Add gettext.pgettext() and variants.

bpo-33197 [https://bugs.python.org/issue?@action=redirect&bpo=33197]: Add description property for _ParameterKind

bpo-32751 [https://bugs.python.org/issue?@action=redirect&bpo=32751]: When cancelling the task due to a timeout, asyncio.wait_for() will now wait until the cancellation is complete.

bpo-32684 [https://bugs.python.org/issue?@action=redirect&bpo=32684]: Fix gather to propagate cancellation of itself even with return_exceptions.

bpo-33654 [https://bugs.python.org/issue?@action=redirect&bpo=33654]: Support protocol type switching in SSLTransport.set_protocol().

bpo-33674 [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().

bpo-33671 [https://bugs.python.org/issue?@action=redirect&bpo=33671]: shutil.copyfile(), shutil.copy(), shutil.copy2(), shutil.copytree() and shutil.move() use platform-specific fast-copy syscalls on Linux and macOS in order to copy the file more efficiently. On Windows shutil.copyfile() uses a bigger default buffer size (1 MiB instead of 16 KiB) and a memoryview()-based variant of 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 [https://bugs.python.org/issue?@action=redirect&bpo=25427].)

bpo-33674 [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.

bpo-31647 [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.

bpo-32610 [https://bugs.python.org/issue?@action=redirect&bpo=32610]: Make asyncio.all_tasks() return only pending tasks.

bpo-32410 [https://bugs.python.org/issue?@action=redirect&bpo=32410]: Avoid blocking on file IO in sendfile fallback code

bpo-33469 [https://bugs.python.org/issue?@action=redirect&bpo=33469]: Fix RuntimeError after closing loop that used run_in_executor

bpo-33672 [https://bugs.python.org/issue?@action=redirect&bpo=33672]: Fix Task.__repr__ crash with Cython's bogus coroutines

bpo-33654 [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.

bpo-33652 [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.

bpo-32493 [https://bugs.python.org/issue?@action=redirect&bpo=32493]: Fixed uuid.uuid1() on FreeBSD.

bpo-33238 [https://bugs.python.org/issue?@action=redirect&bpo=33238]: Add InvalidStateError to concurrent.futures. Future.set_result and Future.set_exception now raise InvalidStateError if the futures are not pending or running. Patch by Jason Haydaman.

bpo-33618 [https://bugs.python.org/issue?@action=redirect&bpo=33618]: Finalize and document preliminary and experimental TLS 1.3 support with OpenSSL 1.1.1

bpo-33625 [https://bugs.python.org/issue?@action=redirect&bpo=33625]: Release GIL on grp.getgrnam, grp.getgrgid, pwd.getpwnam and pwd.getpwuid if reentrant variants of these functions are available. Patch by William Grzybowski.

bpo-33623 [https://bugs.python.org/issue?@action=redirect&bpo=33623]: Fix possible SIGSGV when asyncio.Future is created in __del__

bpo-11874 [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.

bpo-30877 [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.

bpo-33604 [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).

bpo-33582 [https://bugs.python.org/issue?@action=redirect&bpo=33582]: Emit a deprecation warning for inspect.formatargspec

bpo-21145 [https://bugs.python.org/issue?@action=redirect&bpo=21145]: Add functools.cached_property decorator, for computed properties cached for the life of the instance.

bpo-33570 [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.

bpo-28556 [https://bugs.python.org/issue?@action=redirect&bpo=28556]: Do not simplify arguments to typing.Union. Now Union[Manager, Employee] is not simplified to Employee at runtime. Such simplification previously caused several bugs and limited possibilities for introspection.

bpo-12486 [https://bugs.python.org/issue?@action=redirect&bpo=12486]: tokenize.generate_tokens() is now documented as a public API to tokenize unicode strings. It was previously present but undocumented.

bpo-33540 [https://bugs.python.org/issue?@action=redirect&bpo=33540]: Add a new block_on_close class attribute to ForkingMixIn and ThreadingMixIn classes of socketserver.

bpo-33548 [https://bugs.python.org/issue?@action=redirect&bpo=33548]: tempfile._candidate_tempdir_list should consider common TEMP locations

bpo-33109 [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 [https://bugs.python.org/issue?@action=redirect&bpo=26510] in 3.7.0a2.

bpo-33541 [https://bugs.python.org/issue?@action=redirect&bpo=33541]: Remove unused private method _strptime.LocaleTime.__pad (a.k.a. _LocaleTime__pad).

bpo-33536 [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.

bpo-33542 [https://bugs.python.org/issue?@action=redirect&bpo=33542]: Prevent uuid.get_node from using a DUID instead of a MAC on Windows. Patch by Zvi Effron

bpo-26819 [https://bugs.python.org/issue?@action=redirect&bpo=26819]: Fix race condition with ReadTransport.resume_reading in Windows proactor event loop.

Fix failure in typing.get_type_hints() when ClassVar was provided as a string forward reference.

bpo-33516 [https://bugs.python.org/issue?@action=redirect&bpo=33516]: unittest.mock.MagicMock now supports the __round__ magic method.

bpo-28612 [https://bugs.python.org/issue?@action=redirect&bpo=28612]: Added support for Site Maps to urllib's RobotFileParser as RobotFileParser.site_maps(). Patch by Lady Red, based on patch by Peter Wirtz.

bpo-28167 [https://bugs.python.org/issue?@action=redirect&bpo=28167]: Remove platform.linux_distribution, which was deprecated since 3.5.

bpo-33504 [https://bugs.python.org/issue?@action=redirect&bpo=33504]: Switch the default dictionary implementation for configparser from collections.OrderedDict to the standard dict type.

bpo-33505 [https://bugs.python.org/issue?@action=redirect&bpo=33505]: Optimize asyncio.ensure_future() by reordering if checks: 1.17x faster.

bpo-33497 [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.

bpo-29235 [https://bugs.python.org/issue?@action=redirect&bpo=29235]: The cProfile.Profile class can now be used as a context manager. Patch by Scott Sanderson.

bpo-33495 [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.

bpo-26103 [https://bugs.python.org/issue?@action=redirect&bpo=26103]: Correct inspect.isdatadescriptor to look for __set__ or __delete__. Patch by Aaron Hall.

bpo-29209 [https://bugs.python.org/issue?@action=redirect&bpo=29209]: Removed the doctype() method and the html parameter of the constructor of XMLParser. The doctype() method defined in a subclass will no longer be called. Deprecated methods getchildren() and getiterator() in the ElementTree module emit now a DeprecationWarning instead of PendingDeprecationWarning.

bpo-33453 [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").

bpo-28556 [https://bugs.python.org/issue?@action=redirect&bpo=28556]: Minor fixes in typing module: add annotations to NamedTuple.__new__, pass *args and **kwds in Generic.__new__. Original PRs by Paulius Šarka and Chad Dombrova.

bpo-33365 [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 http.client. Patch by Marco Strigl.

bpo-20087 [https://bugs.python.org/issue?@action=redirect&bpo=20087]: Updated alias mapping with glibc 2.27 supported locales.

bpo-33422 [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.

bpo-28167 [https://bugs.python.org/issue?@action=redirect&bpo=28167]: The function platform.linux_distribution and platform.dist now trigger a DeprecationWarning and have been marked for removal in Python 3.8

bpo-33281 [https://bugs.python.org/issue?@action=redirect&bpo=33281]: Fix ctypes.util.find_library regression on macOS.

bpo-33311 [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.

bpo-27300 [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.

bpo-32933 [https://bugs.python.org/issue?@action=redirect&bpo=32933]: unittest.mock.mock_open() now supports iteration over the file contents. Patch by Tony Flury.

bpo-33217 [https://bugs.python.org/issue?@action=redirect&bpo=33217]: Raise TypeError when looking up non-Enum objects in Enum classes and Enum members.

bpo-33197 [https://bugs.python.org/issue?@action=redirect&bpo=33197]: Update error message when constructing invalid inspect.Parameters Patch by Donghee Na.

bpo-33383 [https://bugs.python.org/issue?@action=redirect&bpo=33383]: Fixed crash in the get() method of the dbm.ndbm database object when it is called with a single argument.

bpo-33375 [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.

bpo-33336 [https://bugs.python.org/issue?@action=redirect&bpo=33336]: imaplib now allows MOVE command in IMAP4.uid() (RFC 6851: IMAP MOVE Extension) and potentially as a name of supported method of IMAP4 object.

bpo-32455 [https://bugs.python.org/issue?@action=redirect&bpo=32455]: Added jump parameter to dis.stack_effect().

bpo-27485 [https://bugs.python.org/issue?@action=redirect&bpo=27485]: Rename and deprecate undocumented functions in urllib.parse().

bpo-33332 [https://bugs.python.org/issue?@action=redirect&bpo=33332]: Add signal.valid_signals() to expose the POSIX sigfillset() functionality.

bpo-33251 [https://bugs.python.org/issue?@action=redirect&bpo=33251]: ConfigParser.items() was fixed so that key-value pairs passed in via vars() are not included in the resulting output.

bpo-33329 [https://bugs.python.org/issue?@action=redirect&bpo=33329]: Fix multiprocessing regression on newer glibcs

bpo-33334 [https://bugs.python.org/issue?@action=redirect&bpo=33334]: dis.stack_effect() now supports all defined opcodes including NOP and EXTENDED_ARG.

bpo-991266 [https://bugs.python.org/issue?@action=redirect&bpo=991266]: Fix quoting of the Comment attribute of http.cookies.SimpleCookie.

bpo-33131 [https://bugs.python.org/issue?@action=redirect&bpo=33131]: Upgrade bundled version of pip to 10.0.1.

bpo-33308 [https://bugs.python.org/issue?@action=redirect&bpo=33308]: Fixed a crash in the parser module when converting an ST object to a tree of tuples or lists with line_info=False and col_info=True.

bpo-23403 [https://bugs.python.org/issue?@action=redirect&bpo=23403]: lib2to3 now uses pickle protocol 4 for pre-computed grammars.

bpo-33266 [https://bugs.python.org/issue?@action=redirect&bpo=33266]: lib2to3 now recognizes rf'...' strings.

bpo-11594 [https://bugs.python.org/issue?@action=redirect&bpo=11594]: Ensure line-endings are respected when using lib2to3.

bpo-33254 [https://bugs.python.org/issue?@action=redirect&bpo=33254]: Have importlib.resources.contents() and importlib.abc.ResourceReader.contents() return an iterable instead of an iterator.

bpo-33265 [https://bugs.python.org/issue?@action=redirect&bpo=33265]: contextlib.ExitStack and contextlib.AsyncExitStack now use a method instead of a wrapper function for exit callbacks.

bpo-33263 [https://bugs.python.org/issue?@action=redirect&bpo=33263]: Fix FD leak in _SelectorSocketTransport Patch by Vlad Starostin.

bpo-33256 [https://bugs.python.org/issue?@action=redirect&bpo=33256]: Fix display of <module> call in the html produced by cgitb.html(). Patch by Stéphane Blondon.

bpo-33144 [https://bugs.python.org/issue?@action=redirect&bpo=33144]: random.Random() and its subclassing mechanism got optimized to check only once at class/subclass instantiation time whether its getrandbits() method can be relied on by other methods, including randrange(), for the generation of arbitrarily large random integers. Patch by Wolfgang Maier.

bpo-33185 [https://bugs.python.org/issue?@action=redirect&bpo=33185]: Fixed regression when running pydoc with the -m switch. (The regression was introduced in 3.7.0b3 by the resolution of bpo-33053 [https://bugs.python.org/issue?@action=redirect&bpo=33053])

This fix also changed pydoc to add os.getcwd() to sys.path when necessary, rather than adding ".".

bpo-29613 [https://bugs.python.org/issue?@action=redirect&bpo=29613]: Added support for the SameSite cookie flag to the http.cookies module.

bpo-33169 [https://bugs.python.org/issue?@action=redirect&bpo=33169]: Delete entries of None in sys.path_importer_cache when importlib.machinery.invalidate_caches() is called.

bpo-33203 [https://bugs.python.org/issue?@action=redirect&bpo=33203]: random.Random.choice() now raises IndexError for empty sequences consistently even when called from subclasses without a getrandbits() implementation.

bpo-33224 [https://bugs.python.org/issue?@action=redirect&bpo=33224]: Update difflib.mdiff() for PEP 479 [https://peps.python.org/pep-0479/]. Convert an uncaught StopIteration in a generator into a return-statement.

bpo-33209 [https://bugs.python.org/issue?@action=redirect&bpo=33209]: End framing at the end of C implementation of pickle.Pickler.dump().

bpo-32861 [https://bugs.python.org/issue?@action=redirect&bpo=32861]: The urllib.robotparser's __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.

bpo-23403 [https://bugs.python.org/issue?@action=redirect&bpo=23403]: DEFAULT_PROTOCOL in pickle was bumped to 4. Protocol 4 is described in PEP 3154 [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.

bpo-20104 [https://bugs.python.org/issue?@action=redirect&bpo=20104]: Improved error handling and fixed a reference leak in os.posix_spawn().

bpo-33106 [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.

bpo-33175 [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.

bpo-32380 [https://bugs.python.org/issue?@action=redirect&bpo=32380]: Create functools.singledispatchmethod to support generic single dispatch on descriptors and methods.

bpo-33141 [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__.

bpo-33096 [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.

bpo-32873 [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.

bpo-33134 [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.

bpo-33127 [https://bugs.python.org/issue?@action=redirect&bpo=33127]: The ssl module now compiles with LibreSSL 2.7.1.

bpo-32505 [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.

bpo-33078 [https://bugs.python.org/issue?@action=redirect&bpo=33078]: Fix the failure on OSX caused by the tests relying on sem_getvalue

bpo-33116 [https://bugs.python.org/issue?@action=redirect&bpo=33116]: Add 'Field' to dataclasses.__all__.

bpo-32896 [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.

bpo-33100 [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.

bpo-32953 [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.

bpo-33097 [https://bugs.python.org/issue?@action=redirect&bpo=33097]: Raise RuntimeError when executor.submit is called during interpreter shutdown.

bpo-32968 [https://bugs.python.org/issue?@action=redirect&bpo=32968]: Modulo and floor division involving Fraction and float should return float.

bpo-33061 [https://bugs.python.org/issue?@action=redirect&bpo=33061]: Add missing NoReturn to __all__ in typing.py

bpo-33078 [https://bugs.python.org/issue?@action=redirect&bpo=33078]: Fix the size handling in multiprocessing.Queue when a pickling error occurs.

bpo-33064 [https://bugs.python.org/issue?@action=redirect&bpo=33064]: lib2to3 now properly supports trailing commas after *args and **kwargs in function signatures.

bpo-33056 [https://bugs.python.org/issue?@action=redirect&bpo=33056]: FIX properly close leaking fds in concurrent.futures.ProcessPoolExecutor.

bpo-33021 [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.

bpo-31804 [https://bugs.python.org/issue?@action=redirect&bpo=31804]: Avoid failing in multiprocessing.Process if the standard streams are closed or None at exit.

bpo-33034 [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 urlparse() and urlsplit(). Patch by Matt Eaton.

bpo-30249 [https://bugs.python.org/issue?@action=redirect&bpo=30249]: Improve struct.unpack_from() exception messages for problems with the buffer size and offset.

bpo-33037 [https://bugs.python.org/issue?@action=redirect&bpo=33037]: Skip sending/receiving data after SSL transport closing.

bpo-27683 [https://bugs.python.org/issue?@action=redirect&bpo=27683]: Fix a regression in ipaddress that result of hosts() is empty when the network is constructed by a tuple containing an integer mask and only 1 bit left for addresses.

bpo-22674 [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).

bpo-32999 [https://bugs.python.org/issue?@action=redirect&bpo=32999]: Fix C implementation of ABC.__subclasscheck__(cls, subclass) crashed when subclass is not a type object.

bpo-33009 [https://bugs.python.org/issue?@action=redirect&bpo=33009]: Fix inspect.signature() for single-parameter partialmethods.

bpo-32969 [https://bugs.python.org/issue?@action=redirect&bpo=32969]: Expose several missing constants in zlib and fix corresponding documentation.

bpo-32056 [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 aifc, wave and sunau.

bpo-32970 [https://bugs.python.org/issue?@action=redirect&bpo=32970]: Improved disassembly of the MAKE_FUNCTION instruction.

bpo-32844 [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.

bpo-32960 [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.

bpo-32713 [https://bugs.python.org/issue?@action=redirect&bpo=32713]: Fixed tarfile.itn handling of out-of-bounds float values. Patch by Joffrey Fuhrer.

bpo-32257 [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.

bpo-32951 [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.

bpo-32929 [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.

bpo-32947 [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.

bpo-32146 [https://bugs.python.org/issue?@action=redirect&bpo=32146]: Document the interaction between frozen executables and the spawn and forkserver start methods in multiprocessing.

bpo-30622 [https://bugs.python.org/issue?@action=redirect&bpo=30622]: The ssl module now detects missing NPN support in LibreSSL.

bpo-32922 [https://bugs.python.org/issue?@action=redirect&bpo=32922]: dbm.open() now encodes filename with the filesystem encoding rather than default encoding.

bpo-32759 [https://bugs.python.org/issue?@action=redirect&bpo=32759]: Free unused arenas in multiprocessing.heap.

bpo-32859 [https://bugs.python.org/issue?@action=redirect&bpo=32859]: In os.dup2, don't check every call whether the dup3 syscall exists or not.

bpo-32556 [https://bugs.python.org/issue?@action=redirect&bpo=32556]: nt._getfinalpathname, nt._getvolumepathname and nt._getdiskusage now correctly convert from bytes.

bpo-21060 [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".

bpo-32857 [https://bugs.python.org/issue?@action=redirect&bpo=32857]: In tkinter, after_cancel(None) now raises a ValueError instead of canceling the first scheduled function. Patch by Cheryl Sabella.

bpo-32852 [https://bugs.python.org/issue?@action=redirect&bpo=32852]: Make sure sys.argv remains as a list when running trace.

bpo-31333 [https://bugs.python.org/issue?@action=redirect&bpo=31333]: _abc module is added. It is a speedup module with C implementations for various functions and methods in abc. Creating an ABC subclass and calling isinstance or 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 _abc_registry, _abc_cache, and _abc_negative_cache. There are three debugging helper methods that can be used instead _dump_registry, _abc_registry_clear, and _abc_caches_clear.

bpo-32841 [https://bugs.python.org/issue?@action=redirect&bpo=32841]: Fixed asyncio.Condition issue which silently ignored cancellation after notifying and cancelling a conditional lock. Patch by Bar Harel.

bpo-32819 [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.

bpo-19675 [https://bugs.python.org/issue?@action=redirect&bpo=19675]: multiprocessing.Pool no longer leaks processes if its initialization fails.

bpo-32394 [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.

bpo-31787 [https://bugs.python.org/issue?@action=redirect&bpo=31787]: Fixed refleaks of __init__() methods in various modules. (Contributed by Oren Milman)

bpo-30157 [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.

bpo-30688 [https://bugs.python.org/issue?@action=redirect&bpo=30688]: Added support of \N{name} escapes in regular expressions. Based on patch by Jonathan Eunice.

bpo-32792 [https://bugs.python.org/issue?@action=redirect&bpo=32792]: collections.ChainMap() preserves the order of the underlying mappings.

bpo-32775 [https://bugs.python.org/issue?@action=redirect&bpo=32775]: 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.

bpo-32622 [https://bugs.python.org/issue?@action=redirect&bpo=32622]: Implement native fast sendfile for Windows proactor event loop.

bpo-32777 [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.

bpo-32647 [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.

bpo-32749 [https://bugs.python.org/issue?@action=redirect&bpo=32749]: A dbm.dumb database opened with flags 'r' is now read-only. dbm.dumb.open() with flags 'r' and 'w' no longer creates a database if it does not exist.

bpo-32741 [https://bugs.python.org/issue?@action=redirect&bpo=32741]: Implement asyncio.TimerHandle.when() method.

bpo-32691 [https://bugs.python.org/issue?@action=redirect&bpo=32691]: Use mod_spec.parent when running modules with pdb

bpo-32734 [https://bugs.python.org/issue?@action=redirect&bpo=32734]: Fixed asyncio.Lock() safety issue which allowed acquiring and locking the same lock multiple times, without it being free. Patch by Bar Harel.

bpo-32727 [https://bugs.python.org/issue?@action=redirect&bpo=32727]: Do not include name field in SMTP envelope from address. Patch by Stéphane Wirtel

bpo-31453 [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 https://web.archive.org/web/20180309043602/https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_set_min_proto_version.html feature.

bpo-24334 [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.

bpo-31848 [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.

bpo-32585 [https://bugs.python.org/issue?@action=redirect&bpo=32585]: Add Ttk spinbox widget to tkinter.ttk. Patch by Alan D Moore.

bpo-32512 [https://bugs.python.org/issue?@action=redirect&bpo=32512]: profile CLI accepts -m module_name as an alternative to script path.

bpo-8525 [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.

bpo-31639 [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 -m to cope with web browsers pre-opening sockets.

bpo-29877 [https://bugs.python.org/issue?@action=redirect&bpo=29877]: compileall: import ProcessPoolExecutor only when needed, preventing hangs on low resource platforms

bpo-32221 [https://bugs.python.org/issue?@action=redirect&bpo=32221]: Various functions returning tuple containing IPv6 addresses now omit %scope part since the same information is already encoded in scopeid tuple item. Especially this speeds up socket.recvfrom() when it receives multicast packet since useless resolving of network interface name is omitted.

bpo-32147 [https://bugs.python.org/issue?@action=redirect&bpo=32147]: binascii.unhexlify() is now up to 2 times faster. Patch by Sergey Fedoseev.

bpo-30693 [https://bugs.python.org/issue?@action=redirect&bpo=30693]: The TarFile class now recurses directories in a reproducible way.

bpo-30693 [https://bugs.python.org/issue?@action=redirect&bpo=30693]: The ZipFile class now recurses directories in a reproducible way.

bpo-31680 [https://bugs.python.org/issue?@action=redirect&bpo=31680]: Added curses.ncurses_version.

bpo-31908 [https://bugs.python.org/issue?@action=redirect&bpo=31908]: Fix output of cover files for trace module command-line tool. Previously emitted cover files only when --missing option was used. Patch by Michael Selik.

bpo-31608 [https://bugs.python.org/issue?@action=redirect&bpo=31608]: Raise a TypeError instead of crashing if a collections.deque subclass returns a non-deque from __new__. Patch by Oren Milman.

bpo-31425 [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.

bpo-22005 [https://bugs.python.org/issue?@action=redirect&bpo=22005]: Implemented unpickling instances of datetime, date and time pickled by Python 2. encoding='latin1' should be used for successful decoding.

bpo-27645 [https://bugs.python.org/issue?@action=redirect&bpo=27645]: sqlite3.Connection now exposes a backup method, if the underlying SQLite library is at version 3.6.11 or higher. Patch by Lele Gaifax.

bpo-16865 [https://bugs.python.org/issue?@action=redirect&bpo=16865]: Support arrays >=2GiB in ctypes. Patch by Segev Finer.

bpo-31508 [https://bugs.python.org/issue?@action=redirect&bpo=31508]: Removed support of arguments in tkinter.ttk.Treeview.selection. It was deprecated in 3.6. Use specialized methods like selection_set for changing the selection.

bpo-29456 [https://bugs.python.org/issue?@action=redirect&bpo=29456]: Fix bugs in hangul normalization: u1176, u11a7 and u11c3

Documentation

bpo-21257 [https://bugs.python.org/issue?@action=redirect&bpo=21257]: Document http.client.parse_headers().

bpo-34764 [https://bugs.python.org/issue?@action=redirect&bpo=34764]: Improve example of iter() with 2nd sentinel argument.

bpo-35564 [https://bugs.python.org/issue?@action=redirect&bpo=35564]: Explicitly set master_doc variable in conf.py for compliance with Sphinx 2.0

bpo-35511 [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.

bpo-10536 [https://bugs.python.org/issue?@action=redirect&bpo=10536]: Enhance the gettext docs. Patch by Éric Araujo

bpo-35089 [https://bugs.python.org/issue?@action=redirect&bpo=35089]: Remove mention of typing.io and typing.re. Their types should be imported from typing directly.

bpo-35038 [https://bugs.python.org/issue?@action=redirect&bpo=35038]: Fix the documentation about an unexisting f_restricted attribute in the frame object. Patch by Stéphane Wirtel

bpo-35042 [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.

bpo-35044 [https://bugs.python.org/issue?@action=redirect&bpo=35044]: Fix the documentation with the role exc for the appropriated exception. Patch by Stéphane Wirtel

bpo-35035 [https://bugs.python.org/issue?@action=redirect&bpo=35035]: Rename documentation for email.utils to email.utils.rst.

bpo-34967 [https://bugs.python.org/issue?@action=redirect&bpo=34967]: Use app.add_object_type() instead of the deprecated Sphinx function app.description_unit()

bpo-34913 [https://bugs.python.org/issue?@action=redirect&bpo=34913]: Add documentation about the new command line interface of the gzip module.

bpo-32174 [https://bugs.python.org/issue?@action=redirect&bpo=32174]: chm document displays non-ASCII characters properly on some MBCS Windows systems.

bpo-11233 [https://bugs.python.org/issue?@action=redirect&bpo=11233]: Create availability directive for documentation. Original patch by Georg Brandl.

bpo-34790 [https://bugs.python.org/issue?@action=redirect&bpo=34790]: Document how passing coroutines to asyncio.wait() can be confusing.

bpo-34552 [https://bugs.python.org/issue?@action=redirect&bpo=34552]: Make clear that == operator sometimes is equivalent to is. The <, <=, > and >= operators are only defined where they make sense.

bpo-28617 [https://bugs.python.org/issue?@action=redirect&bpo=28617]: Fixed info in the stdtypes docs concerning the types that support membership tests.

bpo-20177 [https://bugs.python.org/issue?@action=redirect&bpo=20177]: Migrate datetime.date.fromtimestamp to Argument Clinic. Patch by Tim Hoffmann.

bpo-34065 [https://bugs.python.org/issue?@action=redirect&bpo=34065]: Fix wrongly written basicConfig documentation markup syntax

bpo-33460 [https://bugs.python.org/issue?@action=redirect&bpo=33460]: replaced ellipsis with correct error codes in tutorial chapter 3.

bpo-33847 [https://bugs.python.org/issue?@action=redirect&bpo=33847]: Add '@' operator entry to index.

bpo-33409 [https://bugs.python.org/issue?@action=redirect&bpo=33409]: Clarified the relationship between PEP 538 [https://peps.python.org/pep-0538/]'s PYTHONCOERCECLOCALE and PEP 540's PYTHONUTF8 mode.

bpo-33197 [https://bugs.python.org/issue?@action=redirect&bpo=33197]: Add versionadded tag to the documentation of ParameterKind.description

bpo-17045 [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.

bpo-33736 [https://bugs.python.org/issue?@action=redirect&bpo=33736]: Improve the documentation of asyncio.open_connection(), asyncio.start_server() and their UNIX socket counterparts.

bpo-23859 [https://bugs.python.org/issue?@action=redirect&bpo=23859]: Document that asyncio.wait() does not cancel its futures on timeout.

bpo-32436 [https://bugs.python.org/issue?@action=redirect&bpo=32436]: Document PEP 567 [https://peps.python.org/pep-0567/] changes to asyncio.

bpo-33604 [https://bugs.python.org/issue?@action=redirect&bpo=33604]: Update HMAC md5 default to a DeprecationWarning, bump removal to 3.8.

bpo-33594 [https://bugs.python.org/issue?@action=redirect&bpo=33594]: Document getargspec, from_function and from_builtin as deprecated in their respective docstring, and include version since deprecation in DeprecationWarning message.

bpo-33503 [https://bugs.python.org/issue?@action=redirect&bpo=33503]: Fix broken pypi link

bpo-33421 [https://bugs.python.org/issue?@action=redirect&bpo=33421]: Add missing documentation for typing.AsyncContextManager.

bpo-33487 [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.

bpo-33378 [https://bugs.python.org/issue?@action=redirect&bpo=33378]: Add Korean language switcher for https://docs.python.org/3/

bpo-33276 [https://bugs.python.org/issue?@action=redirect&bpo=33276]: Clarify that the __path__ attribute on modules cannot be just any value.

bpo-33201 [https://bugs.python.org/issue?@action=redirect&bpo=33201]: Modernize documentation for writing C extension types.

bpo-33195 [https://bugs.python.org/issue?@action=redirect&bpo=33195]: Deprecate Py_UNICODE usage in c-api/arg document. Py_UNICODE related APIs are deprecated since Python 3.3, but it is missed in the document.

bpo-33126 [https://bugs.python.org/issue?@action=redirect&bpo=33126]: Document PyBuffer_ToContiguous().

bpo-27212 [https://bugs.python.org/issue?@action=redirect&bpo=27212]: Modify documentation for the islice() recipe to consume initial values up to the start index.

bpo-28247 [https://bugs.python.org/issue?@action=redirect&bpo=28247]: Update zipapp documentation to describe how to make standalone applications.

bpo-18802 [https://bugs.python.org/issue?@action=redirect&bpo=18802]: Documentation changes for ipaddress. Patch by Jon Foster and Berker Peksag.

bpo-27428 [https://bugs.python.org/issue?@action=redirect&bpo=27428]: Update documentation to clarify that WindowsRegistryFinder implements MetaPathFinder. (Patch by Himanshu Lakhara)

bpo-28124 [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.

bpo-17232 [https://bugs.python.org/issue?@action=redirect&bpo=17232]: Clarify docs for -O and -OO. Patch by Terry Reedy.

bpo-32436 [https://bugs.python.org/issue?@action=redirect&bpo=32436]: Add documentation for the contextvars module (PEP 567).

bpo-32800 [https://bugs.python.org/issue?@action=redirect&bpo=32800]: Update link to w3c doc for xml default namespaces.

bpo-11015 [https://bugs.python.org/issue?@action=redirect&bpo=11015]: Update test.support documentation.

bpo-32613 [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.

bpo-8722 [https://bugs.python.org/issue?@action=redirect&bpo=8722]: Document __getattr__() behavior when property get() method raises AttributeError.

bpo-32614 [https://bugs.python.org/issue?@action=redirect&bpo=32614]: Modify RE examples in documentation to use raw strings to prevent DeprecationWarning and add text to REGEX HOWTO to highlight the deprecation.

bpo-20709 [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

bpo-32722 [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

bpo-31972 [https://bugs.python.org/issue?@action=redirect&bpo=31972]: Improve docstrings for pathlib.PurePath subclasses.

bpo-30607 [https://bugs.python.org/issue?@action=redirect&bpo=30607]: Use the externalized python-docs-theme package when building the documentation.

bpo-8243 [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.

bpo-32337 [https://bugs.python.org/issue?@action=redirect&bpo=32337]: Update documentation related with dict order.

bpo-25041 [https://bugs.python.org/issue?@action=redirect&bpo=25041]: Document AF_PACKET in the socket module.

bpo-31432 [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.

Tests

bpo-35772 [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.

bpo-35045 [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.

bpo-32710 [https://bugs.python.org/issue?@action=redirect&bpo=32710]: test_asyncio/test_sendfile.py now resets the event loop policy using tearDownModule() as done in other tests, to prevent a warning when running tests on Windows.

bpo-33717 [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().

bpo-35488 [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.

bpo-31731 [https://bugs.python.org/issue?@action=redirect&bpo=31731]: Fix a race condition in 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.

bpo-35424 [https://bugs.python.org/issue?@action=redirect&bpo=35424]: Fix test_multiprocessing_main_handling: use multiprocessing.Pool with a context manager and then explicitly join the pool.

bpo-35519 [https://bugs.python.org/issue?@action=redirect&bpo=35519]: Rename test.bisect module to test.bisect_cmd to avoid conflict with bisect module when running directly a test like ./python Lib/test/test_xmlrpc.py.

bpo-35513 [https://bugs.python.org/issue?@action=redirect&bpo=35513]: Replace time.time() with time.monotonic() in tests to measure time delta.

bpo-34279 [https://bugs.python.org/issue?@action=redirect&bpo=34279]: test.support.run_unittest() no longer raise 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.

bpo-35412 [https://bugs.python.org/issue?@action=redirect&bpo=35412]: Add testcase to test_future4: check unicode literal.

bpo-26704 [https://bugs.python.org/issue?@action=redirect&bpo=26704]: Added test demonstrating double-patching of an instance method. Patch by Anthony Sottile.

bpo-33725 [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.

bpo-35352 [https://bugs.python.org/issue?@action=redirect&bpo=35352]: Modify test_asyncio to use the certificate set from the test directory.

bpo-35317 [https://bugs.python.org/issue?@action=redirect&bpo=35317]: Fix mktime() overflow error in test_email: run test_localtime_daylight_true_dst_true() and test_localtime_daylight_false_dst_true() with a specific timezone.

bpo-21263 [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

bpo-34279 [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.

bpo-34962 [https://bugs.python.org/issue?@action=redirect&bpo=34962]: make docstest in Doc now passes., and is enforced in CI

bpo-23596 [https://bugs.python.org/issue?@action=redirect&bpo=23596]: Use argparse for the command line of the gzip module. Patch by Antony Lee

bpo-34537 [https://bugs.python.org/issue?@action=redirect&bpo=34537]: Fix test_gdb.test_strings() when LC_ALL=C and GDB was compiled with Python 3.6 or earlier.

bpo-34587 [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.

bpo-34661 [https://bugs.python.org/issue?@action=redirect&bpo=34661]: Fix test_shutil if unzip doesn't support -t.

bpo-34200 [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.

bpo-34569 [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.

bpo-34594 [https://bugs.python.org/issue?@action=redirect&bpo=34594]: Fix usage of hardcoded errno values in the tests.

bpo-34579 [https://bugs.python.org/issue?@action=redirect&bpo=34579]: Fix test_embed for AIX Patch by Michael Felt

bpo-34542 [https://bugs.python.org/issue?@action=redirect&bpo=34542]: Use 3072 RSA keys and SHA-256 signature for test certs and keys.

bpo-11193 [https://bugs.python.org/issue?@action=redirect&bpo=11193]: Remove special condition for AIX in test_subprocess.test_undecodable_env

bpo-34347 [https://bugs.python.org/issue?@action=redirect&bpo=34347]: Fix test_utf8_mode.test_cmd_line for AIX

bpo-34490 [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')

bpo-34391 [https://bugs.python.org/issue?@action=redirect&bpo=34391]: Fix ftplib test for TLS 1.3 by reading from data socket.

bpo-11192 [https://bugs.python.org/issue?@action=redirect&bpo=11192]: Fix test_socket on AIX 6.1 and later IPv6 zone id supports only supported by inet_pton6_zone(). Switch to runtime-based platform.system() to establish current platform rather than build-time based sys.platform()

bpo-34399 [https://bugs.python.org/issue?@action=redirect&bpo=34399]: Update all RSA keys and DH params to use at least 2048 bits.

bpo-34373 [https://bugs.python.org/issue?@action=redirect&bpo=34373]: Fix test_mktime and test_pthread_getcpuclickid tests for AIX Add range checking for _PyTime_localtime for AIX Patch by Michael Felt

bpo-11191 [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)

Improved an error message when mock assert_has_calls fails.

bpo-33746 [https://bugs.python.org/issue?@action=redirect&bpo=33746]: Fix test_unittest when run in verbose mode.

bpo-33901 [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.

bpo-33873 [https://bugs.python.org/issue?@action=redirect&bpo=33873]: Fix a bug in 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).

bpo-33562 [https://bugs.python.org/issue?@action=redirect&bpo=33562]: Check that a global asyncio event loop policy is not left behind by any tests.

bpo-33655 [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.

bpo-32962 [https://bugs.python.org/issue?@action=redirect&bpo=32962]: Fixed test_gdb when Python is compiled with flags -mcet -fcf-protection -O0.

bpo-33358 [https://bugs.python.org/issue?@action=redirect&bpo=33358]: Fix test_embed.test_pre_initialization_sys_options() when the interpreter is built with --enable-shared.

bpo-32872 [https://bugs.python.org/issue?@action=redirect&bpo=32872]: Avoid regrtest compatibility issue with namespace packages.

bpo-32517 [https://bugs.python.org/issue?@action=redirect&bpo=32517]: Fix failing test_asyncio on macOS 10.12.2+ due to transport of KqueueSelector loop was not being closed.

bpo-32663 [https://bugs.python.org/issue?@action=redirect&bpo=32663]: Making sure the SMTPUTF8SimTests class of tests gets run in test_smtplib.py.

bpo-27643 [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

bpo-19417 [https://bugs.python.org/issue?@action=redirect&bpo=19417]: Add test_bdb.py.

bpo-31809 [https://bugs.python.org/issue?@action=redirect&bpo=31809]: Add tests to verify connection with secp ECDH curves.

Build

bpo-34691 [https://bugs.python.org/issue?@action=redirect&bpo=34691]: The _contextvars module is now built into the core Python library on Windows.

bpo-35683 [https://bugs.python.org/issue?@action=redirect&bpo=35683]: Improved Azure Pipelines build steps and now verifying layouts correctly

bpo-35642 [https://bugs.python.org/issue?@action=redirect&bpo=35642]: Remove asynciomodule.c from pythoncore.vcxproj

bpo-35550 [https://bugs.python.org/issue?@action=redirect&bpo=35550]: Fix incorrect Solaris #ifdef checks to look for __sun && __SVR4 instead of sun when compiling.

bpo-35499 [https://bugs.python.org/issue?@action=redirect&bpo=35499]: make profile-opt no longer replaces CFLAGS_NODIST with CFLAGS. It now adds profile-guided optimization (PGO) flags to CFLAGS_NODIST: existing CFLAGS_NODIST flags are kept.

bpo-35257 [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.

bpo-35351 [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.

bpo-35139 [https://bugs.python.org/issue?@action=redirect&bpo=35139]: Fix a compiler error when statically linking pyexpat in Modules/Setup.

bpo-35059 [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.

bpo-35011 [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.

bpo-28015 [https://bugs.python.org/issue?@action=redirect&bpo=28015]: Have --with-lto works correctly with clang.

bpo-34765 [https://bugs.python.org/issue?@action=redirect&bpo=34765]: Update the outdated install-sh file to the latest revision from automake v1.16.1

bpo-34585 [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.

bpo-34710 [https://bugs.python.org/issue?@action=redirect&bpo=34710]: Fixed SSL module build with OpenSSL & pedantic CFLAGS.

bpo-34582 [https://bugs.python.org/issue?@action=redirect&bpo=34582]: Add JUnit XML output for regression tests and update Azure DevOps builds.

bpo-34081 [https://bugs.python.org/issue?@action=redirect&bpo=34081]: Make Sphinx warnings as errors in the Docs Makefile.

bpo-34555 [https://bugs.python.org/issue?@action=redirect&bpo=34555]: Fix for case where it was not possible to have both HAVE_LINUX_VM_SOCKETS_H and HAVE_SOCKADDR_ALG be undefined.

bpo-33015 [https://bugs.python.org/issue?@action=redirect&bpo=33015]: Fix an undefined behaviour in the pthread implementation of PyThread_start_new_thread(): add a function wrapper to always return NULL.

bpo-34245 [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.

bpo-34121 [https://bugs.python.org/issue?@action=redirect&bpo=34121]: Fix detection of C11 atomic support on clang.

bpo-32430 [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.

bpo-30345 [https://bugs.python.org/issue?@action=redirect&bpo=30345]: Add -g to LDFLAGS when compiling with LTO to get debug symbols.

bpo-5755 [https://bugs.python.org/issue?@action=redirect&bpo=5755]: Move -Wstrict-prototypes option to CFLAGS_NODIST from OPT. This option emitted annoying warnings when building extension modules written in C++.

bpo-33614 [https://bugs.python.org/issue?@action=redirect&bpo=33614]: Ensures module definition files for the stable ABI on Windows are correctly regenerated.

bpo-33648 [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.

bpo-33522 [https://bugs.python.org/issue?@action=redirect&bpo=33522]: Enable CI builds on Visual Studio Team Services at https://python.visualstudio.com/cpython

bpo-33512 [https://bugs.python.org/issue?@action=redirect&bpo=33512]: configure's check for "long double" has been simplified

bpo-33483 [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.

bpo-33394 [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.

bpo-33393 [https://bugs.python.org/issue?@action=redirect&bpo=33393]: Update config.guess and config.sub files.

bpo-33377 [https://bugs.python.org/issue?@action=redirect&bpo=33377]: Add new triplets for mips r6 and riscv variants (used in extension suffixes).

bpo-32232 [https://bugs.python.org/issue?@action=redirect&bpo=32232]: By default, modules configured in Modules/Setup are no longer built with -DPy_BUILD_CORE. Instead, modules that specifically need that preprocessor definition include it in their individual entries.

bpo-33182 [https://bugs.python.org/issue?@action=redirect&bpo=33182]: The embedding tests can once again be built with clang 6.0

bpo-33163 [https://bugs.python.org/issue?@action=redirect&bpo=33163]: Upgrade pip to 9.0.3 and setuptools to v39.0.1.

bpo-33012 [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.

bpo-32898 [https://bugs.python.org/issue?@action=redirect&bpo=32898]: Fix the python debug build when using COUNT_ALLOCS.

bpo-29442 [https://bugs.python.org/issue?@action=redirect&bpo=29442]: Replace optparse with argparse in setup.py

Windows

bpo-35890 [https://bugs.python.org/issue?@action=redirect&bpo=35890]: Fix API calling consistency of GetVersionEx and wcstok.

bpo-32560 [https://bugs.python.org/issue?@action=redirect&bpo=32560]: The py launcher now forwards its STARTUPINFO structure to child processes.

bpo-35854 [https://bugs.python.org/issue?@action=redirect&bpo=35854]: Fix EnvBuilder and --symlinks in venv on Windows

bpo-35811 [https://bugs.python.org/issue?@action=redirect&bpo=35811]: Avoid propagating venv settings when launching via py.exe

bpo-35797 [https://bugs.python.org/issue?@action=redirect&bpo=35797]: Fix default executable used by the multiprocessing module

bpo-35758 [https://bugs.python.org/issue?@action=redirect&bpo=35758]: Allow building on ARM with MSVC.

bpo-29734 [https://bugs.python.org/issue?@action=redirect&bpo=29734]: Fix handle leaks in os.stat on Windows.

bpo-35596 [https://bugs.python.org/issue?@action=redirect&bpo=35596]: Use unchecked PYCs for the embeddable distro to avoid zipimport restrictions.

bpo-35596 [https://bugs.python.org/issue?@action=redirect&bpo=35596]: Fix vcruntime140.dll being added to embeddable distro multiple times.

bpo-35402 [https://bugs.python.org/issue?@action=redirect&bpo=35402]: Update Windows build to use Tcl and Tk 8.6.9

bpo-35401 [https://bugs.python.org/issue?@action=redirect&bpo=35401]: Updates Windows build to OpenSSL 1.1.0j

bpo-34977 [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.

bpo-34977 [https://bugs.python.org/issue?@action=redirect&bpo=34977]: Adds support for building a Windows App Store package

bpo-35067 [https://bugs.python.org/issue?@action=redirect&bpo=35067]: Remove _distutils_findvs module and use vswhere.exe instead.

bpo-32557 [https://bugs.python.org/issue?@action=redirect&bpo=32557]: Allow shutil.disk_usage to take a file path on Windows

bpo-34770 [https://bugs.python.org/issue?@action=redirect&bpo=34770]: Fix a possible null pointer dereference in pyshellext.cpp.

bpo-34603 [https://bugs.python.org/issue?@action=redirect&bpo=34603]: Fix returning structs from functions produced by MSVC

bpo-34581 [https://bugs.python.org/issue?@action=redirect&bpo=34581]: Guard MSVC-specific code in socketmodule.c with #ifdef _MSC_VER.

bpo-34532 [https://bugs.python.org/issue?@action=redirect&bpo=34532]: Fixes exit code of list version arguments for py.exe.

bpo-34062 [https://bugs.python.org/issue?@action=redirect&bpo=34062]: Fixed the '--list' and '--list-paths' arguments for the py.exe launcher

bpo-34225 [https://bugs.python.org/issue?@action=redirect&bpo=34225]: Ensure INCLUDE and LIB directories do not end with a backslash.

bpo-34011 [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.

bpo-34006 [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.

bpo-31546 [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.

bpo-30237 [https://bugs.python.org/issue?@action=redirect&bpo=30237]: Output error when ReadConsole is canceled by CancelSynchronousIo instead of crashing.

bpo-33895 [https://bugs.python.org/issue?@action=redirect&bpo=33895]: GIL is released while calling functions that acquire Windows loader lock.

bpo-33720 [https://bugs.python.org/issue?@action=redirect&bpo=33720]: Reduces maximum marshal recursion depth on release builds.

bpo-29097 [https://bugs.python.org/issue?@action=redirect&bpo=29097]: Fix bug where datetime.fromtimestamp() erroneously throws an OSError on Windows for values between 0 and 86400. Patch by Ammar Askar.

bpo-33316 [https://bugs.python.org/issue?@action=redirect&bpo=33316]: PyThread_release_lock always fails

bpo-33184 [https://bugs.python.org/issue?@action=redirect&bpo=33184]: Update Windows installer to use OpenSSL 1.1.0h.

bpo-32890 [https://bugs.python.org/issue?@action=redirect&bpo=32890]: Fix usage of GetLastError() instead of errno in os.execve() and os.truncate().

bpo-33016 [https://bugs.python.org/issue?@action=redirect&bpo=33016]: Fix potential use of uninitialized memory in nt._getfinalpathname

bpo-32903 [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.

bpo-32901 [https://bugs.python.org/issue?@action=redirect&bpo=32901]: Update Tcl and Tk versions to 8.6.8

bpo-31966 [https://bugs.python.org/issue?@action=redirect&bpo=31966]: Fixed WindowsConsoleIO.write() for writing empty data.

bpo-32409 [https://bugs.python.org/issue?@action=redirect&bpo=32409]: Ensures activate.bat can handle Unicode contents.

bpo-32457 [https://bugs.python.org/issue?@action=redirect&bpo=32457]: Improves handling of denormalized executable path when launching Python.

bpo-32370 [https://bugs.python.org/issue?@action=redirect&bpo=32370]: Use the correct encoding for ipconfig output in the uuid module. Patch by Segev Finer.

bpo-29248 [https://bugs.python.org/issue?@action=redirect&bpo=29248]: Fix os.readlink() on Windows, which was mistakenly treating the PrintNameOffset field of the reparse data buffer as a number of characters instead of bytes. Patch by Craig Holmquist and SSE4.

bpo-1104 [https://bugs.python.org/issue?@action=redirect&bpo=1104]: Correctly handle string length in msilib.SummaryInfo.GetProperty() to prevent it from truncating the last character.

macOS

bpo-35401 [https://bugs.python.org/issue?@action=redirect&bpo=35401]: Update macOS installer to use OpenSSL 1.1.0j.

bpo-35025 [https://bugs.python.org/issue?@action=redirect&bpo=35025]: Properly guard the use of the CLOCK_GETTIME et al. macros in timemodule on macOS.

bpo-24658 [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.

bpo-34405 [https://bugs.python.org/issue?@action=redirect&bpo=34405]: Update to OpenSSL 1.1.0i for macOS installer builds.

bpo-33635 [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.

bpo-13631 [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.

bpo-33184 [https://bugs.python.org/issue?@action=redirect&bpo=33184]: Update macOS installer build to use OpenSSL 1.1.0h.

bpo-32726 [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.

bpo-32901 [https://bugs.python.org/issue?@action=redirect&bpo=32901]: Update macOS 10.9+ installer to Tcl/Tk 8.6.8.

bpo-31903 [https://bugs.python.org/issue?@action=redirect&bpo=31903]: In _scproxy, drop the GIL when calling into SystemConfiguration to avoid deadlocks.

IDLE

bpo-35770 [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.

bpo-35769 [https://bugs.python.org/issue?@action=redirect&bpo=35769]: Change IDLE's new file name from 'Untitled' to 'untitled'

bpo-35660 [https://bugs.python.org/issue?@action=redirect&bpo=35660]: Fix imports in idlelib.window.

bpo-35641 [https://bugs.python.org/issue?@action=redirect&bpo=35641]: Proper format calltip when the function has no docstring.

bpo-33987 [https://bugs.python.org/issue?@action=redirect&bpo=33987]: Use ttk Frame for ttk widgets.

bpo-34055 [https://bugs.python.org/issue?@action=redirect&bpo=34055]: Fix erroneous 'smart' indents and newlines in IDLE Shell.

bpo-35591 [https://bugs.python.org/issue?@action=redirect&bpo=35591]: Find Selection now works when selection not found.

bpo-35196 [https://bugs.python.org/issue?@action=redirect&bpo=35196]: Speed up squeezer line counting.

bpo-35598 [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.

bpo-28097 [https://bugs.python.org/issue?@action=redirect&bpo=28097]: Add Previous/Next History entries to Shell menu.

bpo-35208 [https://bugs.python.org/issue?@action=redirect&bpo=35208]: Squeezer now properly counts wrapped lines before newlines.

bpo-35555 [https://bugs.python.org/issue?@action=redirect&bpo=35555]: Gray out Code Context menu entry when it's not applicable.

bpo-35521 [https://bugs.python.org/issue?@action=redirect&bpo=35521]: Document the IDLE editor code context feature. Add some internal references within the IDLE doc.

bpo-22703 [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.

bpo-35213 [https://bugs.python.org/issue?@action=redirect&bpo=35213]: Where appropriate, use 'macOS' in idlelib.

bpo-34864 [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".

bpo-34864 [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.

bpo-35202 [https://bugs.python.org/issue?@action=redirect&bpo=35202]: Remove unused imports from lib/idlelib

bpo-33000 [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.

bpo-23220 [https://bugs.python.org/issue?@action=redirect&bpo=23220]: Explain how IDLE's Shell displays output.

bpo-35099 [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 sys.stdxxx objects.

bpo-35097 [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.

bpo-35093 [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.

bpo-35088 [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.

bpo-35087 [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.

bpo-34548 [https://bugs.python.org/issue?@action=redirect&bpo=34548]: Use configured color theme for read-only text views.

bpo-1529353 [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".

bpo-34047 [https://bugs.python.org/issue?@action=redirect&bpo=34047]: Fixed mousewheel scrolling direction on macOS.

bpo-34275 [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.

bpo-34120 [https://bugs.python.org/issue?@action=redirect&bpo=34120]: Fix unresponsiveness after closing certain windows and dialogs.

bpo-33975 [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.

bpo-33905 [https://bugs.python.org/issue?@action=redirect&bpo=33905]: Add test for idlelib.stackview.StackBrowser.

bpo-33924 [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.

bpo-33906 [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.

bpo-33917 [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.

bpo-33904 [https://bugs.python.org/issue?@action=redirect&bpo=33904]: IDLE: In rstrip, rename class RstripExtension as Rstrip

bpo-33907 [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.

bpo-33856 [https://bugs.python.org/issue?@action=redirect&bpo=33856]: Add "help" in the welcome message of IDLE

bpo-33839 [https://bugs.python.org/issue?@action=redirect&bpo=33839]: IDLE: refactor ToolTip and CallTip and add documentation and tests

bpo-33855 [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.

bpo-33656 [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.

bpo-33768 [https://bugs.python.org/issue?@action=redirect&bpo=33768]: Clicking on a context line moves that line to the top of the editor window.

bpo-33763 [https://bugs.python.org/issue?@action=redirect&bpo=33763]: IDLE: Use read-only text widget for code context instead of label widget.

bpo-33664 [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.

bpo-33679 [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.

bpo-33642 [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.

bpo-33628 [https://bugs.python.org/issue?@action=redirect&bpo=33628]: IDLE: Cleanup codecontext.py and its test.

bpo-33564 [https://bugs.python.org/issue?@action=redirect&bpo=33564]: IDLE's code context now recognizes async as a block opener.

bpo-21474 [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.

bpo-33204 [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.

bpo-32984 [https://bugs.python.org/issue?@action=redirect&bpo=32984]: Set __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, -s runs a file named in environmental variable IDLESTARTUP or PYTHONSTARTUP; -r file runs file. Python sets __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 -n option.

bpo-32940 [https://bugs.python.org/issue?@action=redirect&bpo=32940]: Simplify and rename StringTranslatePseudoMapping in pyparse.

bpo-32916 [https://bugs.python.org/issue?@action=redirect&bpo=32916]: Change str to code in pyparse.

bpo-32905 [https://bugs.python.org/issue?@action=redirect&bpo=32905]: Remove unused code in pyparse module.

bpo-32874 [https://bugs.python.org/issue?@action=redirect&bpo=32874]: Add tests for pyparse.

bpo-32837 [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.

bpo-32826 [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.

bpo-32831 [https://bugs.python.org/issue?@action=redirect&bpo=32831]: Add docstrings and tests for codecontext.

bpo-32765 [https://bugs.python.org/issue?@action=redirect&bpo=32765]: Update configdialog General tab docstring to add new widgets to the widget list.

Tools/Demos

bpo-35884 [https://bugs.python.org/issue?@action=redirect&bpo=35884]: Add a benchmark script for timing various ways to access variables: Tools/scripts/var_access_benchmark.py.

bpo-34989 [https://bugs.python.org/issue?@action=redirect&bpo=34989]: python-gdb.py now handles errors on computing the line number of a Python frame.

bpo-20260 [https://bugs.python.org/issue?@action=redirect&bpo=20260]: Argument Clinic now has non-bitwise unsigned int converters.

bpo-32962 [https://bugs.python.org/issue?@action=redirect&bpo=32962]: python-gdb now catches UnicodeDecodeError exceptions when calling string().

bpo-32962 [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.

bpo-33189 [https://bugs.python.org/issue?@action=redirect&bpo=33189]: pygettext.py now recognizes only literal strings as docstrings and translatable strings, and rejects bytes literals and f-string expressions.

bpo-31920 [https://bugs.python.org/issue?@action=redirect&bpo=31920]: Fixed handling directories as arguments in the pygettext script. Based on patch by Oleg Krasnikov.

bpo-29673 [https://bugs.python.org/issue?@action=redirect&bpo=29673]: Fix pystackv and pystack gdbinit macros.

bpo-25427 [https://bugs.python.org/issue?@action=redirect&bpo=25427]: Remove the pyvenv script in favor of python3 -m venv in order to lower confusion as to what Python interpreter a virtual environment will be created for.

bpo-32885 [https://bugs.python.org/issue?@action=redirect&bpo=32885]: Add an -n flag for Tools/scripts/pathfix.py to disable automatic backup creation (files with ~ suffix).

bpo-32222 [https://bugs.python.org/issue?@action=redirect&bpo=32222]: Fix pygettext not extracting docstrings for functions with type annotated arguments. Patch by Toby Harradine.

bpo-31583 [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.

C API

bpo-35713 [https://bugs.python.org/issue?@action=redirect&bpo=35713]: The PyByteArray_Init() and 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.

bpo-33817 [https://bugs.python.org/issue?@action=redirect&bpo=33817]: Fixed _PyBytes_Resize() for empty bytes objects.

bpo-35322 [https://bugs.python.org/issue?@action=redirect&bpo=35322]: Fix memory leak in PyUnicode_EncodeLocale() and PyUnicode_EncodeFSDefault() on error handling.

bpo-35059 [https://bugs.python.org/issue?@action=redirect&bpo=35059]: The following C macros have been converted to static inline functions: Py_INCREF(), Py_DECREF(), Py_XINCREF(), Py_XDECREF(), PyObject_INIT(), PyObject_INIT_VAR().

bpo-35296 [https://bugs.python.org/issue?@action=redirect&bpo=35296]: make install now also installs the internal API: Include/internal/*.h header files.

bpo-35081 [https://bugs.python.org/issue?@action=redirect&bpo=35081]: Internal APIs surrounded by #ifdef Py_BUILD_CORE have been moved from Include/*.h headers to new header files Include/internal/pycore_*.h.

bpo-35259 [https://bugs.python.org/issue?@action=redirect&bpo=35259]: Conditionally declare Py_FinalizeEx() (new in 3.6) based on Py_LIMITED_API. Patch by Arthur Neufeld.

bpo-35081 [https://bugs.python.org/issue?@action=redirect&bpo=35081]: The _PyObject_GC_TRACK() and _PyObject_GC_UNTRACK() macros have been removed from the public C API.

bpo-35134 [https://bugs.python.org/issue?@action=redirect&bpo=35134]: Creation of a new Include/cpython/ subdirectory.

bpo-34725 [https://bugs.python.org/issue?@action=redirect&bpo=34725]: Adds _Py_SetProgramFullPath so embedders may override sys.executable

bpo-34910 [https://bugs.python.org/issue?@action=redirect&bpo=34910]: Ensure that PyObject_Print() always returns -1 on error. Patch by Zackery Spytz.

bpo-34523 [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.

bpo-34193 [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'.

bpo-34127 [https://bugs.python.org/issue?@action=redirect&bpo=34127]: Return grammatically correct error message based on argument count. Patch by Karthikeyan Singaravelan.

bpo-23927 [https://bugs.python.org/issue?@action=redirect&bpo=23927]: Fixed SystemError in PyArg_ParseTupleAndKeywords() when the w* format unit is used for optional parameter.

bpo-32455 [https://bugs.python.org/issue?@action=redirect&bpo=32455]: Added PyCompile_OpcodeStackEffectWithJump().

bpo-34008 [https://bugs.python.org/issue?@action=redirect&bpo=34008]: Py_Main() can again be called after Py_Initialize(), as in Python 3.6.

bpo-32500 [https://bugs.python.org/issue?@action=redirect&bpo=32500]: Fixed error messages for PySequence_Size(), PySequence_GetItem(), PySequence_SetItem() and PySequence_DelItem() called with a mapping and PyMapping_Size() called with a sequence.

bpo-33818 [https://bugs.python.org/issue?@action=redirect&bpo=33818]: PyExceptionClass_Name() will now return const char * instead of char *.

bpo-33042 [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.

bpo-32374 [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

bpo-30863 [https://bugs.python.org/issue?@action=redirect&bpo=30863]: PyUnicode_AsWideChar() and PyUnicode_AsWideCharString() no longer cache the wchar_t* representation of string objects.

Python 3.7.0 final

Release date: 2018-06-27

Library

bpo-33851 [https://bugs.python.org/issue?@action=redirect&bpo=33851]: Fix ast.get_docstring() for a node that lacks a docstring.

C API

bpo-33932 [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.

Python 3.7.0 release candidate 1

Release date: 2018-06-12

Core and Builtins

bpo-33803 [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.

bpo-33706 [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!

bpo-30654 [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.

bpo-31849 [https://bugs.python.org/issue?@action=redirect&bpo=31849]: Fix signed/unsigned comparison warning in pyhash.c.

Library

bpo-30167 [https://bugs.python.org/issue?@action=redirect&bpo=30167]: Prevent site.main() exception if PYTHONSTARTUP is set. Patch by Steve Weber.

bpo-33812 [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.

bpo-30805 [https://bugs.python.org/issue?@action=redirect&bpo=30805]: Avoid race condition with debug logging

bpo-33694 [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.

bpo-32493 [https://bugs.python.org/issue?@action=redirect&bpo=32493]: Correct test for uuid_enc_be availability in configure.ac. Patch by Michael Felt.

bpo-33792 [https://bugs.python.org/issue?@action=redirect&bpo=33792]: Add asyncio.WindowsSelectorEventLoopPolicy and asyncio.WindowsProactorEventLoopPolicy.

bpo-33778 [https://bugs.python.org/issue?@action=redirect&bpo=33778]: Update unicodedata's database to Unicode version 11.0.0.

bpo-33770 [https://bugs.python.org/issue?@action=redirect&bpo=33770]: improve base64 exception message for encoded inputs of invalid length

bpo-33769 [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.

bpo-33767 [https://bugs.python.org/issue?@action=redirect&bpo=33767]: The concatenation (+) and repetition (*) sequence operations now raise TypeError instead of SystemError when performed on mmap.mmap objects. Patch by Zackery Spytz.

bpo-33734 [https://bugs.python.org/issue?@action=redirect&bpo=33734]: asyncio/ssl: Fix AttributeError, increase default handshake timeout

bpo-11874 [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.

bpo-33582 [https://bugs.python.org/issue?@action=redirect&bpo=33582]: Emit a deprecation warning for inspect.formatargspec

Documentation

bpo-33409 [https://bugs.python.org/issue?@action=redirect&bpo=33409]: Clarified the relationship between PEP 538 [https://peps.python.org/pep-0538/]'s PYTHONCOERCECLOCALE and PEP 540's PYTHONUTF8 mode.

bpo-33736 [https://bugs.python.org/issue?@action=redirect&bpo=33736]: Improve the documentation of asyncio.open_connection(), asyncio.start_server() and their UNIX socket counterparts.

bpo-31432 [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.

Build

bpo-5755 [https://bugs.python.org/issue?@action=redirect&bpo=5755]: Move -Wstrict-prototypes option to CFLAGS_NODIST from OPT. This option emitted annoying warnings when building extension modules written in C++.

Windows

bpo-33720 [https://bugs.python.org/issue?@action=redirect&bpo=33720]: Reduces maximum marshal recursion depth on release builds.

IDLE

bpo-33656 [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.

bpo-33768 [https://bugs.python.org/issue?@action=redirect&bpo=33768]: Clicking on a context line moves that line to the top of the editor window.

bpo-33763 [https://bugs.python.org/issue?@action=redirect&bpo=33763]: IDLE: Use read-only text widget for code context instead of label widget.

bpo-33664 [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.

bpo-33679 [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.

bpo-33642 [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.

Python 3.7.0 beta 5

Release date: 2018-05-30

Core and Builtins

bpo-33622 [https://bugs.python.org/issue?@action=redirect&bpo=33622]: Fixed a leak when the garbage collector fails to add an object with the __del__ method or referenced by it into the gc.garbage list. PyGC_Collect() can now be called when an exception is set and preserves it.

bpo-33509 [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.

bpo-20104 [https://bugs.python.org/issue?@action=redirect&bpo=20104]: The new 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.

bpo-33475 [https://bugs.python.org/issue?@action=redirect&bpo=33475]: Fixed miscellaneous bugs in converting annotations to strings and optimized parentheses in the string representation.

bpo-33391 [https://bugs.python.org/issue?@action=redirect&bpo=33391]: Fix a leak in set_symmetric_difference().

bpo-28055 [https://bugs.python.org/issue?@action=redirect&bpo=28055]: Fix unaligned accesses in siphash24(). Patch by Rolf Eike Beer.

bpo-32911 [https://bugs.python.org/issue?@action=redirect&bpo=32911]: Due to unexpected compatibility issues discovered during downstream beta testing, reverted bpo-29463 [https://bugs.python.org/issue?@action=redirect&bpo=29463]. 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.

bpo-21983 [https://bugs.python.org/issue?@action=redirect&bpo=21983]: Fix a crash in ctypes.cast() in case the type argument is a ctypes structured data type. Patch by Eryk Sun and Oren Milman.

Library

bpo-32751 [https://bugs.python.org/issue?@action=redirect&bpo=32751]: When cancelling the task due to a timeout, asyncio.wait_for() will now wait until the cancellation is complete.

bpo-32684 [https://bugs.python.org/issue?@action=redirect&bpo=32684]: Fix gather to propagate cancellation of itself even with return_exceptions.

bpo-33654 [https://bugs.python.org/issue?@action=redirect&bpo=33654]: Support protocol type switching in SSLTransport.set_protocol().

bpo-33674 [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().

bpo-33674 [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.

bpo-31647 [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.

bpo-32610 [https://bugs.python.org/issue?@action=redirect&bpo=32610]: Make asyncio.all_tasks() return only pending tasks.

bpo-32410 [https://bugs.python.org/issue?@action=redirect&bpo=32410]: Avoid blocking on file IO in sendfile fallback code

bpo-33469 [https://bugs.python.org/issue?@action=redirect&bpo=33469]: Fix RuntimeError after closing loop that used run_in_executor

bpo-33672 [https://bugs.python.org/issue?@action=redirect&bpo=33672]: Fix Task.__repr__ crash with Cython's bogus coroutines

bpo-33654 [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.

bpo-33652 [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.

bpo-32493 [https://bugs.python.org/issue?@action=redirect&bpo=32493]: Fixed uuid.uuid1() on FreeBSD.

bpo-33618 [https://bugs.python.org/issue?@action=redirect&bpo=33618]: Finalize and document preliminary and experimental TLS 1.3 support with OpenSSL 1.1.1

bpo-33623 [https://bugs.python.org/issue?@action=redirect&bpo=33623]: Fix possible SIGSGV when asyncio.Future is created in __del__

bpo-30877 [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.

bpo-33570 [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.

bpo-28556 [https://bugs.python.org/issue?@action=redirect&bpo=28556]: Do not simplify arguments to typing.Union. Now Union[Manager, Employee] is not simplified to Employee at runtime. Such simplification previously caused several bugs and limited possibilities for introspection.

bpo-33540 [https://bugs.python.org/issue?@action=redirect&bpo=33540]: Add a new block_on_close class attribute to ForkingMixIn and ThreadingMixIn classes of socketserver.

bpo-33548 [https://bugs.python.org/issue?@action=redirect&bpo=33548]: tempfile._candidate_tempdir_list should consider common TEMP locations

bpo-33109 [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 [https://bugs.python.org/issue?@action=redirect&bpo=26510] in 3.7.0a2.

bpo-33536 [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.

bpo-33542 [https://bugs.python.org/issue?@action=redirect&bpo=33542]: Prevent uuid.get_node from using a DUID instead of a MAC on Windows. Patch by Zvi Effron

bpo-26819 [https://bugs.python.org/issue?@action=redirect&bpo=26819]: Fix race condition with ReadTransport.resume_reading in Windows proactor event loop.

Fix failure in typing.get_type_hints() when ClassVar was provided as a string forward reference.

bpo-33505 [https://bugs.python.org/issue?@action=redirect&bpo=33505]: Optimize asyncio.ensure_future() by reordering if checks: 1.17x faster.

bpo-33497 [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.

bpo-33495 [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.

bpo-33453 [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").

bpo-28556 [https://bugs.python.org/issue?@action=redirect&bpo=28556]: Minor fixes in typing module: add annotations to NamedTuple.__new__, pass *args and **kwds in Generic.__new__. Original PRs by Paulius Šarka and Chad Dombrova.

bpo-20087 [https://bugs.python.org/issue?@action=redirect&bpo=20087]: Updated alias mapping with glibc 2.27 supported locales.

bpo-33422 [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.

bpo-28167 [https://bugs.python.org/issue?@action=redirect&bpo=28167]: The function platform.linux_distribution and platform.dist now trigger a DeprecationWarning and have been marked for removal in Python 3.8

bpo-33197 [https://bugs.python.org/issue?@action=redirect&bpo=33197]: Update error message when constructing invalid inspect.Parameters Patch by Donghee Na.

bpo-33263 [https://bugs.python.org/issue?@action=redirect&bpo=33263]: Fix FD leak in _SelectorSocketTransport Patch by Vlad Starostin.

bpo-32861 [https://bugs.python.org/issue?@action=redirect&bpo=32861]: The urllib.robotparser's __str__ representation now includes wildcard entries and the "Crawl-delay" and "Request-rate" fields. Patch by Michael Lazar.

bpo-32257 [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.

bpo-16865 [https://bugs.python.org/issue?@action=redirect&bpo=16865]: Support arrays >=2GiB in ctypes. Patch by Segev Finer.

Documentation

bpo-23859 [https://bugs.python.org/issue?@action=redirect&bpo=23859]: Document that asyncio.wait() does not cancel its futures on timeout.

bpo-32436 [https://bugs.python.org/issue?@action=redirect&bpo=32436]: Document PEP 567 [https://peps.python.org/pep-0567/] changes to asyncio.

bpo-33604 [https://bugs.python.org/issue?@action=redirect&bpo=33604]: Update HMAC md5 default to a DeprecationWarning, bump removal to 3.8.

bpo-33503 [https://bugs.python.org/issue?@action=redirect&bpo=33503]: Fix broken pypi link

bpo-33421 [https://bugs.python.org/issue?@action=redirect&bpo=33421]: Add missing documentation for typing.AsyncContextManager.

Tests

bpo-33655 [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.

bpo-32604 [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.

Build

bpo-33614 [https://bugs.python.org/issue?@action=redirect&bpo=33614]: Ensures module definition files for the stable ABI on Windows are correctly regenerated.

bpo-33522 [https://bugs.python.org/issue?@action=redirect&bpo=33522]: Enable CI builds on Visual Studio Team Services at https://python.visualstudio.com/cpython

bpo-33012 [https://bugs.python.org/issue?@action=redirect&bpo=33012]: Add -Wno-cast-function-type for gcc 8 for silencing warnings about function casts like casting to PyCFunction in method definition lists.

macOS

bpo-13631 [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.

IDLE

bpo-33628 [https://bugs.python.org/issue?@action=redirect&bpo=33628]: IDLE: Cleanup codecontext.py and its test.

bpo-33564 [https://bugs.python.org/issue?@action=redirect&bpo=33564]: IDLE's code context now recognizes async as a block opener.

bpo-32831 [https://bugs.python.org/issue?@action=redirect&bpo=32831]: Add docstrings and tests for codecontext.

Python 3.7.0 beta 4

Release date: 2018-05-02

Core and Builtins

bpo-33363 [https://bugs.python.org/issue?@action=redirect&bpo=33363]: Raise a SyntaxError for async with and async for statements outside of async functions.

bpo-33128 [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.

bpo-33312 [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.

bpo-33231 [https://bugs.python.org/issue?@action=redirect&bpo=33231]: Fix potential memory leak in normalizestring().

bpo-33205 [https://bugs.python.org/issue?@action=redirect&bpo=33205]: Change dict growth function from round_up_to_power_2(used*2+hashtable_size/2) to round_up_to_power_2(used*3). Previously, dict is shrinked only when used == 0. Now dict has more chance to be shrinked.

bpo-29922 [https://bugs.python.org/issue?@action=redirect&bpo=29922]: Improved error messages in 'async with' when __aenter__() or __aexit__() return non-awaitable object.

bpo-33199 [https://bugs.python.org/issue?@action=redirect&bpo=33199]: Fix ma_version_tag in dict implementation is uninitialized when copying from key-sharing dict.

Library

bpo-33281 [https://bugs.python.org/issue?@action=redirect&bpo=33281]: Fix ctypes.util.find_library regression on macOS.

bpo-33383 [https://bugs.python.org/issue?@action=redirect&bpo=33383]: Fixed crash in the get() method of the dbm.ndbm database object when it is called with a single argument.

bpo-33329 [https://bugs.python.org/issue?@action=redirect&bpo=33329]: Fix multiprocessing regression on newer glibcs

bpo-991266 [https://bugs.python.org/issue?@action=redirect&bpo=991266]: Fix quoting of the Comment attribute of http.cookies.SimpleCookie.

bpo-33131 [https://bugs.python.org/issue?@action=redirect&bpo=33131]: Upgrade bundled version of pip to 10.0.1.

bpo-33308 [https://bugs.python.org/issue?@action=redirect&bpo=33308]: Fixed a crash in the parser module when converting an ST object to a tree of tuples or lists with line_info=False and col_info=True.

bpo-33266 [https://bugs.python.org/issue?@action=redirect&bpo=33266]: lib2to3 now recognizes rf'...' strings.

bpo-11594 [https://bugs.python.org/issue?@action=redirect&bpo=11594]: Ensure line-endings are respected when using lib2to3.

bpo-33254 [https://bugs.python.org/issue?@action=redirect&bpo=33254]: Have importlib.resources.contents() and importlib.abc.ResourceReader.contents() return an iterable instead of an iterator.

bpo-33256 [https://bugs.python.org/issue?@action=redirect&bpo=33256]: Fix display of <module> call in the html produced by cgitb.html(). Patch by Stéphane Blondon.

bpo-33185 [https://bugs.python.org/issue?@action=redirect&bpo=33185]: Fixed regression when running pydoc with the -m switch. (The regression was introduced in 3.7.0b3 by the resolution of bpo-33053 [https://bugs.python.org/issue?@action=redirect&bpo=33053]) This fix also changed pydoc to add os.getcwd() to sys.path when necessary, rather than adding ".".

bpo-33169 [https://bugs.python.org/issue?@action=redirect&bpo=33169]: Delete entries of None in sys.path_importer_cache when importlib.machinery.invalidate_caches() is called.

bpo-33217 [https://bugs.python.org/issue?@action=redirect&bpo=33217]: Deprecate looking up non-Enum objects in Enum classes and Enum members (will raise TypeError in 3.8+).

bpo-33203 [https://bugs.python.org/issue?@action=redirect&bpo=33203]: random.Random.choice() now raises IndexError for empty sequences consistently even when called from subclasses without a getrandbits() implementation.

bpo-33224 [https://bugs.python.org/issue?@action=redirect&bpo=33224]: Update difflib.mdiff() for PEP 479 [https://peps.python.org/pep-0479/]. Convert an uncaught StopIteration in a generator into a return-statement.

bpo-33209 [https://bugs.python.org/issue?@action=redirect&bpo=33209]: End framing at the end of C implementation of pickle.Pickler.dump().

bpo-20104 [https://bugs.python.org/issue?@action=redirect&bpo=20104]: Improved error handling and fixed a reference leak in os.posix_spawn().

bpo-33175 [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.

bpo-33097 [https://bugs.python.org/issue?@action=redirect&bpo=33097]: Raise RuntimeError when executor.submit is called during interpreter shutdown.

bpo-31908 [https://bugs.python.org/issue?@action=redirect&bpo=31908]: Fix output of cover files for trace module command-line tool. Previously emitted cover files only when --missing option was used. Patch by Michael Selik.

Documentation

bpo-33378 [https://bugs.python.org/issue?@action=redirect&bpo=33378]: Add Korean language switcher for https://docs.python.org/3/

bpo-33276 [https://bugs.python.org/issue?@action=redirect&bpo=33276]: Clarify that the __path__ attribute on modules cannot be just any value.

bpo-33201 [https://bugs.python.org/issue?@action=redirect&bpo=33201]: Modernize documentation for writing C extension types.

bpo-33195 [https://bugs.python.org/issue?@action=redirect&bpo=33195]: Deprecate Py_UNICODE usage in c-api/arg document. Py_UNICODE related APIs are deprecated since Python 3.3, but it is missed in the document.

bpo-8243 [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.

bpo-32337 [https://bugs.python.org/issue?@action=redirect&bpo=32337]: Update documentation related with dict order.

Tests

bpo-33358 [https://bugs.python.org/issue?@action=redirect&bpo=33358]: Fix test_embed.test_pre_initialization_sys_options() when the interpreter is built with --enable-shared.

Build

bpo-33394 [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.

bpo-33393 [https://bugs.python.org/issue?@action=redirect&bpo=33393]: Update config.guess and config.sub files.

bpo-33377 [https://bugs.python.org/issue?@action=redirect&bpo=33377]: Add new triplets for mips r6 and riscv variants (used in extension suffixes).

bpo-32232 [https://bugs.python.org/issue?@action=redirect&bpo=32232]: By default, modules configured in Modules/Setup are no longer built with -DPy_BUILD_CORE. Instead, modules that specifically need that preprocessor definition include it in their individual entries.

bpo-33182 [https://bugs.python.org/issue?@action=redirect&bpo=33182]: The embedding tests can once again be built with clang 6.0

Windows

bpo-33184 [https://bugs.python.org/issue?@action=redirect&bpo=33184]: Update Windows installer to use OpenSSL 1.1.0h.

macOS

bpo-33184 [https://bugs.python.org/issue?@action=redirect&bpo=33184]: Update macOS installer build to use OpenSSL 1.1.0h.

IDLE

bpo-21474 [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.

bpo-33204 [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.

Tools/Demos

bpo-33189 [https://bugs.python.org/issue?@action=redirect&bpo=33189]: pygettext.py now recognizes only literal strings as docstrings and translatable strings, and rejects bytes literals and f-string expressions.

bpo-31920 [https://bugs.python.org/issue?@action=redirect&bpo=31920]: Fixed handling directories as arguments in the pygettext script. Based on patch by Oleg Krasnikov.

bpo-29673 [https://bugs.python.org/issue?@action=redirect&bpo=29673]: Fix pystackv and pystack gdbinit macros.

bpo-31583 [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.

Python 3.7.0 beta 3

Release date: 2018-03-29

Security

bpo-33136 [https://bugs.python.org/issue?@action=redirect&bpo=33136]: Harden ssl module against LibreSSL CVE-2018-8970 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-8970]. X509_VERIFY_PARAM_set1_host() is called with an explicit namelen. A new test ensures that NULL bytes are not allowed.

bpo-33001 [https://bugs.python.org/issue?@action=redirect&bpo=33001]: Minimal fix to prevent buffer overrun in os.symlink on Windows

bpo-32981 [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 CVE-2018-1060 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-1060] and CVE-2018-1061 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-1061]. Patch by Jamie Davis.

Core and Builtins

bpo-33053 [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)

bpo-33018 [https://bugs.python.org/issue?@action=redirect&bpo=33018]: Improve consistency of errors raised by issubclass() when called with a non-class and an abstract base class as the first and second arguments, respectively. Patch by Josh Bronson.

bpo-33041 [https://bugs.python.org/issue?@action=redirect&bpo=33041]: Fixed jumping when the function contains an async for loop.

bpo-33026 [https://bugs.python.org/issue?@action=redirect&bpo=33026]: Fixed jumping out of "with" block by setting f_lineno.

bpo-33005 [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.

bpo-17288 [https://bugs.python.org/issue?@action=redirect&bpo=17288]: Prevent jumps from 'return' and 'exception' trace events.

bpo-32836 [https://bugs.python.org/issue?@action=redirect&bpo=32836]: Don't use temporary variables in cases of list/dict/set comprehensions

Library

bpo-33141 [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__.

bpo-33096 [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.

bpo-32873 [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.

bpo-33134 [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.

bpo-33127 [https://bugs.python.org/issue?@action=redirect&bpo=33127]: The ssl module now compiles with LibreSSL 2.7.1.

bpo-32505 [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.

bpo-33078 [https://bugs.python.org/issue?@action=redirect&bpo=33078]: Fix the failure on OSX caused by the tests relying on sem_getvalue

bpo-33116 [https://bugs.python.org/issue?@action=redirect&bpo=33116]: Add 'Field' to dataclasses.__all__.

bpo-32896 [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.

bpo-33100 [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.

bpo-32953 [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.

bpo-33061 [https://bugs.python.org/issue?@action=redirect&bpo=33061]: Add missing NoReturn to __all__ in typing.py

bpo-33078 [https://bugs.python.org/issue?@action=redirect&bpo=33078]: Fix the size handling in multiprocessing.Queue when a pickling error occurs.

bpo-33064 [https://bugs.python.org/issue?@action=redirect&bpo=33064]: lib2to3 now properly supports trailing commas after *args and **kwargs in function signatures.

bpo-33056 [https://bugs.python.org/issue?@action=redirect&bpo=33056]: FIX properly close leaking fds in concurrent.futures.ProcessPoolExecutor.

bpo-33021 [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.

bpo-31804 [https://bugs.python.org/issue?@action=redirect&bpo=31804]: Avoid failing in multiprocessing.Process if the standard streams are closed or None at exit.

bpo-33037 [https://bugs.python.org/issue?@action=redirect&bpo=33037]: Skip sending/receiving data after SSL transport closing.

bpo-27683 [https://bugs.python.org/issue?@action=redirect&bpo=27683]: Fix a regression in ipaddress that result of hosts() is empty when the network is constructed by a tuple containing an integer mask and only 1 bit left for addresses.

bpo-32999 [https://bugs.python.org/issue?@action=redirect&bpo=32999]: Fix C implementation of ABC.__subclasscheck__(cls, subclass) crashed when subclass is not a type object.

bpo-33009 [https://bugs.python.org/issue?@action=redirect&bpo=33009]: Fix inspect.signature() for single-parameter partialmethods.

bpo-32969 [https://bugs.python.org/issue?@action=redirect&bpo=32969]: Expose several missing constants in zlib and fix corresponding documentation.

bpo-32056 [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 aifc, wave and sunau.

bpo-32844 [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.

bpo-32857 [https://bugs.python.org/issue?@action=redirect&bpo=32857]: In tkinter, after_cancel(None) now raises a ValueError instead of canceling the first scheduled function. Patch by Cheryl Sabella.

bpo-31639 [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 -m to cope with web browsers pre-opening sockets.

bpo-27645 [https://bugs.python.org/issue?@action=redirect&bpo=27645]: sqlite3.Connection now exposes a backup method, if the underlying SQLite library is at version 3.6.11 or higher. Patch by Lele Gaifax.

Documentation

bpo-33126 [https://bugs.python.org/issue?@action=redirect&bpo=33126]: Document PyBuffer_ToContiguous().

bpo-27212 [https://bugs.python.org/issue?@action=redirect&bpo=27212]: Modify documentation for the islice() recipe to consume initial values up to the start index.

bpo-28247 [https://bugs.python.org/issue?@action=redirect&bpo=28247]: Update zipapp documentation to describe how to make standalone applications.

bpo-18802 [https://bugs.python.org/issue?@action=redirect&bpo=18802]: Documentation changes for ipaddress. Patch by Jon Foster and Berker Peksag.

bpo-27428 [https://bugs.python.org/issue?@action=redirect&bpo=27428]: Update documentation to clarify that WindowsRegistryFinder implements MetaPathFinder. (Patch by Himanshu Lakhara)

Tests

bpo-32872 [https://bugs.python.org/issue?@action=redirect&bpo=32872]: Avoid regrtest compatibility issue with namespace packages.

bpo-32517 [https://bugs.python.org/issue?@action=redirect&bpo=32517]: Fix failing test_asyncio on macOS 10.12.2+ due to transport of KqueueSelector loop was not being closed.

bpo-19417 [https://bugs.python.org/issue?@action=redirect&bpo=19417]: Add test_bdb.py.

Build

bpo-33163 [https://bugs.python.org/issue?@action=redirect&bpo=33163]: Upgrade pip to 9.0.3 and setuptools to v39.0.1.

Windows

bpo-33016 [https://bugs.python.org/issue?@action=redirect&bpo=33016]: Fix potential use of uninitialized memory in nt._getfinalpathname

bpo-32903 [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.

macOS

bpo-32726 [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.

IDLE

bpo-32984 [https://bugs.python.org/issue?@action=redirect&bpo=32984]: Set __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, -s runs a file named in environmental variable IDLESTARTUP or PYTHONSTARTUP; -r file runs file. Python sets __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 -n option.

bpo-32940 [https://bugs.python.org/issue?@action=redirect&bpo=32940]: Simplify and rename StringTranslatePseudoMapping in pyparse.

Tools/Demos

bpo-32885 [https://bugs.python.org/issue?@action=redirect&bpo=32885]: Add an -n flag for Tools/scripts/pathfix.py to disable automatic backup creation (files with ~ suffix).

C API

bpo-33042 [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.

bpo-32374 [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

Python 3.7.0 beta 2

Release date: 2018-02-27

Security

bpo-28414 [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.

Core and Builtins

bpo-32889 [https://bugs.python.org/issue?@action=redirect&bpo=32889]: Update Valgrind suppression list to account for the rename of Py_ADDRESS_IN_RANG to address_in_range.

bpo-31356 [https://bugs.python.org/issue?@action=redirect&bpo=31356]: Remove the new API added in bpo-31356 [https://bugs.python.org/issue?@action=redirect&bpo=31356] (gc.ensure_disabled() context manager).

bpo-32305 [https://bugs.python.org/issue?@action=redirect&bpo=32305]: For namespace packages, ensure that both __file__ and __spec__.origin are set to None.

bpo-32303 [https://bugs.python.org/issue?@action=redirect&bpo=32303]: Make sure __spec__.loader matches __loader__ for namespace packages.

bpo-32711 [https://bugs.python.org/issue?@action=redirect&bpo=32711]: Fix the warning messages for Python/ast_unparse.c. Patch by Stéphane Wirtel

bpo-32583 [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.

Library

bpo-32960 [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.

bpo-32713 [https://bugs.python.org/issue?@action=redirect&bpo=32713]: Fixed tarfile.itn handling of out-of-bounds float values. Patch by Joffrey Fuhrer.

bpo-32951 [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.

bpo-32929 [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.

bpo-32947 [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.

bpo-30622 [https://bugs.python.org/issue?@action=redirect&bpo=30622]: The ssl module now detects missing NPN support in LibreSSL.

bpo-32922 [https://bugs.python.org/issue?@action=redirect&bpo=32922]: dbm.open() now encodes filename with the filesystem encoding rather than default encoding.

bpo-32859 [https://bugs.python.org/issue?@action=redirect&bpo=32859]: In os.dup2, don't check every call whether the dup3 syscall exists or not.

bpo-32556 [https://bugs.python.org/issue?@action=redirect&bpo=32556]: nt._getfinalpathname, nt._getvolumepathname and nt._getdiskusage now correctly convert from bytes.

bpo-25988 [https://bugs.python.org/issue?@action=redirect&bpo=25988]: Emit a DeprecationWarning when using or importing an ABC directly from collections rather than from collections.abc.

bpo-21060 [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".

bpo-32852 [https://bugs.python.org/issue?@action=redirect&bpo=32852]: Make sure sys.argv remains as a list when running trace.

bpo-31333 [https://bugs.python.org/issue?@action=redirect&bpo=31333]: _abc module is added. It is a speedup module with C implementations for various functions and methods in abc. Creating an ABC subclass and calling isinstance or 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 _abc_registry, _abc_cache, and _abc_negative_cache. There are three debugging helper methods that can be used instead _dump_registry, _abc_registry_clear, and _abc_caches_clear.

bpo-32841 [https://bugs.python.org/issue?@action=redirect&bpo=32841]: Fixed asyncio.Condition issue which silently ignored cancellation after notifying and cancelling a conditional lock. Patch by Bar Harel.

bpo-32819 [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.

bpo-32394 [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.

bpo-31787 [https://bugs.python.org/issue?@action=redirect&bpo=31787]: Fixed refleaks of __init__() methods in various modules. (Contributed by Oren Milman)

bpo-30157 [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.

bpo-32792 [https://bugs.python.org/issue?@action=redirect&bpo=32792]: collections.ChainMap() preserves the order of the underlying mappings.

bpo-32775 [https://bugs.python.org/issue?@action=redirect&bpo=32775]: 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.

bpo-32622 [https://bugs.python.org/issue?@action=redirect&bpo=32622]: Implement native fast sendfile for Windows proactor event loop.

bpo-32777 [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.

bpo-32647 [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.

bpo-32741 [https://bugs.python.org/issue?@action=redirect&bpo=32741]: Implement asyncio.TimerHandle.when() method.

bpo-32691 [https://bugs.python.org/issue?@action=redirect&bpo=32691]: Use mod_spec.parent when running modules with pdb

bpo-32734 [https://bugs.python.org/issue?@action=redirect&bpo=32734]: Fixed asyncio.Lock() safety issue which allowed acquiring and locking the same lock multiple times, without it being free. Patch by Bar Harel.

bpo-32727 [https://bugs.python.org/issue?@action=redirect&bpo=32727]: Do not include name field in SMTP envelope from address. Patch by Stéphane Wirtel

bpo-31453 [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 https://web.archive.org/web/20180309043602/https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_set_min_proto_version.html feature.

bpo-24334 [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.

bpo-31848 [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.

bpo-32585 [https://bugs.python.org/issue?@action=redirect&bpo=32585]: Add Ttk spinbox widget to tkinter.ttk. Patch by Alan D Moore.

bpo-32221 [https://bugs.python.org/issue?@action=redirect&bpo=32221]: Various functions returning tuple containing IPv6 addresses now omit %scope part since the same information is already encoded in scopeid tuple item. Especially this speeds up socket.recvfrom() when it receives multicast packet since useless resolving of network interface name is omitted.

bpo-30693 [https://bugs.python.org/issue?@action=redirect&bpo=30693]: The TarFile class now recurses directories in a reproducible way.

bpo-30693 [https://bugs.python.org/issue?@action=redirect&bpo=30693]: The ZipFile class now recurses directories in a reproducible way.

Documentation

bpo-28124 [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.

bpo-17232 [https://bugs.python.org/issue?@action=redirect&bpo=17232]: Clarify docs for -O and -OO. Patch by Terry Reedy.

bpo-32436 [https://bugs.python.org/issue?@action=redirect&bpo=32436]: Add documentation for the contextvars module (PEP 567).

bpo-32800 [https://bugs.python.org/issue?@action=redirect&bpo=32800]: Update link to w3c doc for xml default namespaces.

bpo-11015 [https://bugs.python.org/issue?@action=redirect&bpo=11015]: Update test.support documentation.

bpo-8722 [https://bugs.python.org/issue?@action=redirect&bpo=8722]: Document __getattr__() behavior when property get() method raises AttributeError.

bpo-32614 [https://bugs.python.org/issue?@action=redirect&bpo=32614]: Modify RE examples in documentation to use raw strings to prevent DeprecationWarning and add text to REGEX HOWTO to highlight the deprecation.

bpo-31972 [https://bugs.python.org/issue?@action=redirect&bpo=31972]: Improve docstrings for pathlib.PurePath subclasses.

Tests

bpo-31809 [https://bugs.python.org/issue?@action=redirect&bpo=31809]: Add tests to verify connection with secp ECDH curves.

Build

bpo-32898 [https://bugs.python.org/issue?@action=redirect&bpo=32898]: Fix the python debug build when using COUNT_ALLOCS.

Windows

bpo-32901 [https://bugs.python.org/issue?@action=redirect&bpo=32901]: Update Tcl and Tk versions to 8.6.8

bpo-31966 [https://bugs.python.org/issue?@action=redirect&bpo=31966]: Fixed WindowsConsoleIO.write() for writing empty data.

bpo-32409 [https://bugs.python.org/issue?@action=redirect&bpo=32409]: Ensures activate.bat can handle Unicode contents.

bpo-32457 [https://bugs.python.org/issue?@action=redirect&bpo=32457]: Improves handling of denormalized executable path when launching Python.

bpo-32370 [https://bugs.python.org/issue?@action=redirect&bpo=32370]: Use the correct encoding for ipconfig output in the uuid module. Patch by Segev Finer.

bpo-29248 [https://bugs.python.org/issue?@action=redirect&bpo=29248]: Fix os.readlink() on Windows, which was mistakenly treating the PrintNameOffset field of the reparse data buffer as a number of characters instead of bytes. Patch by Craig Holmquist and SSE4.

macOS

bpo-32901 [https://bugs.python.org/issue?@action=redirect&bpo=32901]: Update macOS 10.9+ installer to Tcl/Tk 8.6.8.

IDLE

bpo-32916 [https://bugs.python.org/issue?@action=redirect&bpo=32916]: Change str to code in pyparse.

bpo-32905 [https://bugs.python.org/issue?@action=redirect&bpo=32905]: Remove unused code in pyparse module.

bpo-32874 [https://bugs.python.org/issue?@action=redirect&bpo=32874]: Add tests for pyparse.

bpo-32837 [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.

bpo-32826 [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.

bpo-32765 [https://bugs.python.org/issue?@action=redirect&bpo=32765]: Update configdialog General tab docstring to add new widgets to the widget list.

Tools/Demos

bpo-32222 [https://bugs.python.org/issue?@action=redirect&bpo=32222]: Fix pygettext not extracting docstrings for functions with type annotated arguments. Patch by Toby Harradine.

Python 3.7.0 beta 1

Release date: 2018-01-30

Core and Builtins

bpo-32703 [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.

bpo-32650 [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.

bpo-28685 [https://bugs.python.org/issue?@action=redirect&bpo=28685]: Optimize list.sort() and sorted() by using type specialized comparisons when possible.

bpo-32685 [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.

bpo-32697 [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.

bpo-32690 [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.

bpo-32677 [https://bugs.python.org/issue?@action=redirect&bpo=32677]: Add .isascii() method to str, bytes and bytearray. It can be used to test that string contains only ASCII characters.

bpo-32670 [https://bugs.python.org/issue?@action=redirect&bpo=32670]: Enforce PEP 479 [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.

bpo-32591 [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.

bpo-31368 [https://bugs.python.org/issue?@action=redirect&bpo=31368]: Expose preadv and pwritev system calls in the os module. Patch by Pablo Galindo

bpo-32544 [https://bugs.python.org/issue?@action=redirect&bpo=32544]: hasattr(obj, name) and getattr(obj, name, default) are about 4 times faster than before when name is not found and obj doesn't override __getattr__ or __getattribute__.

bpo-26163 [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.

bpo-32550 [https://bugs.python.org/issue?@action=redirect&bpo=32550]: Remove the STORE_ANNOTATION bytecode.

bpo-20104 [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)

bpo-24340 [https://bugs.python.org/issue?@action=redirect&bpo=24340]: Fixed estimation of the code stack size.

bpo-32436 [https://bugs.python.org/issue?@action=redirect&bpo=32436]: Implement PEP 567 [https://peps.python.org/pep-0567/] Context Variables.

bpo-18533 [https://bugs.python.org/issue?@action=redirect&bpo=18533]: repr() on a dict containing its own values() or items() no longer raises RecursionError; OrderedDict similarly. Instead, use ..., as for other recursive structures. Patch by Ben North.

bpo-20891 [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.

bpo-32028 [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.

bpo-31179 [https://bugs.python.org/issue?@action=redirect&bpo=31179]: Make dict.copy() up to 5.5 times faster.

bpo-31113 [https://bugs.python.org/issue?@action=redirect&bpo=31113]: Get rid of recursion in the compiler for normal control flow.

Library

bpo-25988 [https://bugs.python.org/issue?@action=redirect&bpo=25988]: Deprecate exposing the contents of collections.abc in the regular collections module.

bpo-31429 [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.

bpo-30306 [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.

bpo-21417 [https://bugs.python.org/issue?@action=redirect&bpo=21417]: Added support for setting the compression level for zipfile.ZipFile.

bpo-32251 [https://bugs.python.org/issue?@action=redirect&bpo=32251]: Implement asyncio.BufferedProtocol (provisional API).

bpo-32513 [https://bugs.python.org/issue?@action=redirect&bpo=32513]: In dataclasses, allow easier overriding of dunder methods without specifying decorator parameters.

bpo-32660 [https://bugs.python.org/issue?@action=redirect&bpo=32660]: termios makes available FIONREAD, FIONCLEX, FIOCLEX, FIOASYNC and FIONBIO also under Solaris/derivatives.

bpo-27931 [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.

bpo-32659 [https://bugs.python.org/issue?@action=redirect&bpo=32659]: Under Solaris and derivatives, os.stat_result provides a st_fstype attribute.

bpo-32662 [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().

bpo-32391 [https://bugs.python.org/issue?@action=redirect&bpo=32391]: Implement asyncio.StreamWriter.wait_closed() and asyncio.StreamWriter.is_closing() methods

bpo-32643 [https://bugs.python.org/issue?@action=redirect&bpo=32643]: Make Task._step, Task._wakeup and Future._schedule_callbacks methods private.

bpo-32630 [https://bugs.python.org/issue?@action=redirect&bpo=32630]: Refactor decimal module to use contextvars to store decimal context.

bpo-32622 [https://bugs.python.org/issue?@action=redirect&bpo=32622]: Add asyncio.AbstractEventLoop.sendfile() method.

bpo-32304 [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.

bpo-32502 [https://bugs.python.org/issue?@action=redirect&bpo=32502]: uuid.uuid1 no longer raises an exception if a 64-bit hardware address is encountered.

bpo-32596 [https://bugs.python.org/issue?@action=redirect&bpo=32596]: concurrent.futures imports ThreadPoolExecutor and ProcessPoolExecutor lazily (using PEP 562 [https://peps.python.org/pep-0562/]). It makes import asyncio about 15% faster because asyncio uses only ThreadPoolExecutor by default.

bpo-31801 [https://bugs.python.org/issue?@action=redirect&bpo=31801]: Add _ignore_ to Enum so temporary variables can be used during class construction without being turned into members.

bpo-32576 [https://bugs.python.org/issue?@action=redirect&bpo=32576]: Use queue.SimpleQueue() in places where it can be invoked from a weakref callback.

bpo-32574 [https://bugs.python.org/issue?@action=redirect&bpo=32574]: Fix memory leak in asyncio.Queue, when the queue has limited size and it is full, the cancelation of queue.put() can cause a memory leak. Patch by: José Melero.

bpo-32521 [https://bugs.python.org/issue?@action=redirect&bpo=32521]: The nis module is now compatible with new libnsl and headers location.

bpo-32467 [https://bugs.python.org/issue?@action=redirect&bpo=32467]: collections.abc.ValuesView now inherits from collections.abc.Collection.

bpo-32473 [https://bugs.python.org/issue?@action=redirect&bpo=32473]: Improve ABCMeta._dump_registry() output readability

bpo-32102 [https://bugs.python.org/issue?@action=redirect&bpo=32102]: New argument capture_output for subprocess.run

bpo-32521 [https://bugs.python.org/issue?@action=redirect&bpo=32521]: glibc has removed Sun RPC. Use replacement libtirpc headers and library in nis module.

bpo-32493 [https://bugs.python.org/issue?@action=redirect&bpo=32493]: UUID module fixes build for FreeBSD/OpenBSD

bpo-32503 [https://bugs.python.org/issue?@action=redirect&bpo=32503]: Pickling with protocol 4 no longer creates too small frames.

bpo-29237 [https://bugs.python.org/issue?@action=redirect&bpo=29237]: Create enum for pstats sorting options

bpo-32454 [https://bugs.python.org/issue?@action=redirect&bpo=32454]: Add close(fd) function to the socket module.

bpo-25942 [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.

bpo-32433 [https://bugs.python.org/issue?@action=redirect&bpo=32433]: The hmac module now has hmac.digest(), which provides an optimized HMAC digest.

bpo-28134 [https://bugs.python.org/issue?@action=redirect&bpo=28134]: Sockets now auto-detect family, type and protocol from file descriptor by default.

bpo-32404 [https://bugs.python.org/issue?@action=redirect&bpo=32404]: Fix bug where datetime.datetime.fromtimestamp() did not call __new__ in datetime.datetime subclasses.

bpo-32403 [https://bugs.python.org/issue?@action=redirect&bpo=32403]: Improved speed of datetime.date and datetime.datetime alternate constructors.

bpo-32228 [https://bugs.python.org/issue?@action=redirect&bpo=32228]: Ensure that truncate() preserves the file position (as reported by tell()) after writes longer than the buffer size.

bpo-32410 [https://bugs.python.org/issue?@action=redirect&bpo=32410]: Implement loop.sock_sendfile for asyncio event loop.

bpo-22908 [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.

bpo-32373 [https://bugs.python.org/issue?@action=redirect&bpo=32373]: Add socket.getblocking() method.

bpo-32248 [https://bugs.python.org/issue?@action=redirect&bpo=32248]: Add importlib.resources and importlib.abc.ResourceReader as the unified API for reading resources contained within packages. Loaders wishing to support resource reading must implement the get_resource_reader() method. File-based and zipimport-based loaders both implement these APIs. importlib.abc.ResourceLoader is deprecated in favor of these new APIs.

bpo-32320 [https://bugs.python.org/issue?@action=redirect&bpo=32320]: collections.namedtuple() now supports default values.

bpo-29302 [https://bugs.python.org/issue?@action=redirect&bpo=29302]: Add contextlib.AsyncExitStack. Patch by Alexander Mohr and Ilya Kulakov.

bpo-31961 [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 path-like object. If args is given as a sequence, it's first element can now be a path-like object as well.

bpo-31900 [https://bugs.python.org/issue?@action=redirect&bpo=31900]: The locale.localeconv() function now sets temporarily the LC_CTYPE locale to the LC_NUMERIC locale to decode decimal_point and thousands_sep byte strings if they are non-ASCII or longer than 1 byte, and the LC_NUMERIC locale is different than the LC_CTYPE locale. This temporary change affects other threads. Same change for the str.format() method when formatting a number (int, float, float and subclasses) with the n type (ex: '{:n}'.format(1234)).

bpo-31853 [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.

bpo-31399 [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.

bpo-14976 [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().

Documentation

bpo-32724 [https://bugs.python.org/issue?@action=redirect&bpo=32724]: Add references to some commands in the documentation of Pdb. Patch by Stéphane Wirtel

bpo-32649 [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.

bpo-17799 [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.

Tests

bpo-32721 [https://bugs.python.org/issue?@action=redirect&bpo=32721]: Fix test_hashlib to not fail if the _md5 module is not built.

bpo-28414 [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 [https://bugs.python.org/issue?@action=redirect&bpo=31399] has landed. IDNA 2008 are still broken.

bpo-32604 [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.

bpo-32602 [https://bugs.python.org/issue?@action=redirect&bpo=32602]: Add test certs and test for ECDSA cert and EC/RSA dual mode.

bpo-32549 [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.

Build

bpo-32635 [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.

bpo-32598 [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.

bpo-32593 [https://bugs.python.org/issue?@action=redirect&bpo=32593]: Drop support of FreeBSD 9 and older.

bpo-29708 [https://bugs.python.org/issue?@action=redirect&bpo=29708]: If the SOURCE_DATE_EPOCH environment variable is set, py_compile will always create hash-based .pyc files.

Windows

bpo-32588 [https://bugs.python.org/issue?@action=redirect&bpo=32588]: Create standalone _distutils_findvs module and add missing _queue module to installer.

bpo-29911 [https://bugs.python.org/issue?@action=redirect&bpo=29911]: Ensure separate Modify and Uninstall buttons are displayed.

bpo-32507 [https://bugs.python.org/issue?@action=redirect&bpo=32507]: Use app-local UCRT install rather than the proper update for old versions of Windows.

macOS

bpo-32726 [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.

bpo-28440 [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.

C API

bpo-32681 [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

bpo-10381 [https://bugs.python.org/issue?@action=redirect&bpo=10381]: Add C API access to the datetime.timezone constructor and datetime.timzone.UTC singleton.

Python 3.7.0 alpha 4

Release date: 2018-01-08

Core and Builtins

bpo-31975 [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.

bpo-32226 [https://bugs.python.org/issue?@action=redirect&bpo=32226]: __class_getitem__ is now an automatic class method.

bpo-32399 [https://bugs.python.org/issue?@action=redirect&bpo=32399]: Add AIX uuid library support for RFC4122 using uuid_create() in libc.a

bpo-32390 [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 [https://bugs.python.org/issue?@action=redirect&bpo=32143]). Original patch by Michael Felt.

bpo-32379 [https://bugs.python.org/issue?@action=redirect&bpo=32379]: Make MRO computation faster when a class inherits from a single base.

bpo-32259 [https://bugs.python.org/issue?@action=redirect&bpo=32259]: The error message of a TypeError raised when unpack non-iterable is now more specific.

bpo-27169 [https://bugs.python.org/issue?@action=redirect&bpo=27169]: The __debug__ constant is now optimized out at compile time. This fixes also bpo-22091 [https://bugs.python.org/issue?@action=redirect&bpo=22091].

bpo-32329 [https://bugs.python.org/issue?@action=redirect&bpo=32329]: The -R option now turns on hash randomization when the PYTHONHASHSEED environment variable is set to 0. Previously, the option was ignored. Moreover, sys.flags.hash_randomization is now properly set to 0 when hash randomization is turned off by PYTHONHASHSEED=0.

bpo-30416 [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.

bpo-32282 [https://bugs.python.org/issue?@action=redirect&bpo=32282]: Fix an unnecessary ifdef in the include of VersionHelpers.h in socketmodule on Windows.

bpo-30579 [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.

bpo-32260 [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.

bpo-31506 [https://bugs.python.org/issue?@action=redirect&bpo=31506]: Improve the error message logic for object.__new__ and object.__init__. Patch by Sanyam Khurana.

bpo-20361 [https://bugs.python.org/issue?@action=redirect&bpo=20361]: -b and -bb now inject 'default::BytesWarning' and error::BytesWarning entries into sys.warnoptions, ensuring that they take precedence over any other warning filters configured via the -W option or the PYTHONWARNINGS environment variable.

bpo-32230 [https://bugs.python.org/issue?@action=redirect&bpo=32230]: -X dev now injects a 'default' entry into sys.warnoptions, ensuring that it behaves identically to actually passing -Wdefault at the command line.

bpo-29240 [https://bugs.python.org/issue?@action=redirect&bpo=29240]: Add a new UTF-8 mode: implementation of the PEP 540 [https://peps.python.org/pep-0540/].

bpo-32226 [https://bugs.python.org/issue?@action=redirect&bpo=32226]: PEP 560 [https://peps.python.org/pep-0560/]: Add support for __mro_entries__ and __class_getitem__. Implemented by Ivan Levkivskyi.

bpo-32225 [https://bugs.python.org/issue?@action=redirect&bpo=32225]: PEP 562 [https://peps.python.org/pep-0562/]: Add support for module __getattr__ and __dir__. Implemented by Ivan Levkivskyi.

bpo-31901 [https://bugs.python.org/issue?@action=redirect&bpo=31901]: The atexit module now has its callback stored per interpreter.

bpo-31650 [https://bugs.python.org/issue?@action=redirect&bpo=31650]: Implement PEP 552 [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.

bpo-29469 [https://bugs.python.org/issue?@action=redirect&bpo=29469]: Move constant folding from bytecode layer to AST layer. Original patch by Eugene Toder.

Library

bpo-32506 [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.

bpo-32279 [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().

bpo-32278 [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.

bpo-32499 [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.

bpo-32468 [https://bugs.python.org/issue?@action=redirect&bpo=32468]: Improve frame repr() to mention filename, code name and current line number.

bpo-23749 [https://bugs.python.org/issue?@action=redirect&bpo=23749]: asyncio: Implement loop.start_tls()

bpo-32441 [https://bugs.python.org/issue?@action=redirect&bpo=32441]: Return the new file descriptor (i.e., the second argument) from os.dup2. Previously, None was always returned.

bpo-32422 [https://bugs.python.org/issue?@action=redirect&bpo=32422]: functools.lru_cache uses less memory (3 words for each cached key) and takes about 1/3 time for cyclic GC.

bpo-31721 [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.

bpo-32415 [https://bugs.python.org/issue?@action=redirect&bpo=32415]: asyncio: Add Task.get_loop() and Future.get_loop()

bpo-26133 [https://bugs.python.org/issue?@action=redirect&bpo=26133]: Don't unsubscribe signals in asyncio UNIX event loop on interpreter shutdown.

bpo-32363 [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.

bpo-32357 [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.

bpo-32356 [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.

bpo-32355 [https://bugs.python.org/issue?@action=redirect&bpo=32355]: Optimize asyncio.gather(); now up to 15% faster.

bpo-32351 [https://bugs.python.org/issue?@action=redirect&bpo=32351]: Use fastpath in asyncio.sleep if delay<0 (2x boost)

bpo-32348 [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.

bpo-32331 [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.

bpo-32248 [https://bugs.python.org/issue?@action=redirect&bpo=32248]: Add importlib.abc.ResourceReader as an ABC for loaders to provide a unified API for reading resources contained within packages. Also add importlib.resources as the port of importlib_resources.

bpo-32311 [https://bugs.python.org/issue?@action=redirect&bpo=32311]: Implement asyncio.create_task(coro) shortcut

bpo-32327 [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.

bpo-32323 [https://bugs.python.org/issue?@action=redirect&bpo=32323]: urllib.parse.urlsplit() does not convert zone-id (scope) to lower case for scoped IPv6 addresses in hostnames now.

bpo-32302 [https://bugs.python.org/issue?@action=redirect&bpo=32302]: Fix bdist_wininst of distutils for CRT v142: it binary compatible with CRT v140.

bpo-29711 [https://bugs.python.org/issue?@action=redirect&bpo=29711]: Fix stop_serving in asyncio proactor loop kill all listening servers

bpo-32308 [https://bugs.python.org/issue?@action=redirect&bpo=32308]: re.sub() now replaces empty matches adjacent to a previous non-empty match.

bpo-29970 [https://bugs.python.org/issue?@action=redirect&bpo=29970]: Abort asyncio SSLProtocol connection if handshake not complete within 10 seconds.

bpo-32314 [https://bugs.python.org/issue?@action=redirect&bpo=32314]: Implement asyncio.run().

bpo-17852 [https://bugs.python.org/issue?@action=redirect&bpo=17852]: Revert incorrect fix based on misunderstanding of _Py_PyAtExit() semantics.

bpo-32296 [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.

bpo-32250 [https://bugs.python.org/issue?@action=redirect&bpo=32250]: Implement asyncio.current_task() and asyncio.all_tasks(). Add helpers intended to be used by alternative task implementations: asyncio._register_task, asyncio._enter_task, asyncio._leave_task and asyncio._unregister_task. Deprecate asyncio.Task.current_task() and asyncio.Task.all_tasks().

bpo-32255 [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.

bpo-32277 [https://bugs.python.org/issue?@action=redirect&bpo=32277]: Raise NotImplementedError instead of SystemError on platforms where chmod(..., follow_symlinks=False) is not supported. Patch by Anthony Sottile.

bpo-30050 [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.

bpo-29137 [https://bugs.python.org/issue?@action=redirect&bpo=29137]: The 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.

bpo-32273 [https://bugs.python.org/issue?@action=redirect&bpo=32273]: Move asyncio.test_utils to test.test_asyncio.

bpo-32272 [https://bugs.python.org/issue?@action=redirect&bpo=32272]: Remove asyncio.async() function.

bpo-32269 [https://bugs.python.org/issue?@action=redirect&bpo=32269]: Add asyncio.get_running_loop() function.

bpo-32265 [https://bugs.python.org/issue?@action=redirect&bpo=32265]: All class and static methods of builtin types now are correctly classified by inspect.classify_class_attrs() and grouped in pydoc ouput. Added types.ClassMethodDescriptorType for unbound class methods of builtin types.

bpo-32253 [https://bugs.python.org/issue?@action=redirect&bpo=32253]: Deprecate yield from lock, await lock, with (yield from lock) and with await lock for asyncio synchronization primitives.

bpo-22589 [https://bugs.python.org/issue?@action=redirect&bpo=22589]: Changed MIME type of .bmp from 'image/x-ms-bmp' to 'image/bmp'

bpo-32193 [https://bugs.python.org/issue?@action=redirect&bpo=32193]: Convert asyncio to use async/await syntax. Old styled yield from is still supported too.

bpo-32206 [https://bugs.python.org/issue?@action=redirect&bpo=32206]: Add support to run modules with pdb

bpo-32227 [https://bugs.python.org/issue?@action=redirect&bpo=32227]: functools.singledispatch now supports registering implementations using type annotations.

bpo-15873 [https://bugs.python.org/issue?@action=redirect&bpo=15873]: Added new alternate constructors datetime.datetime.fromisoformat(), datetime.time.fromisoformat() and datetime.date.fromisoformat() as the inverse operation of each classes's respective isoformat methods.

bpo-32199 [https://bugs.python.org/issue?@action=redirect&bpo=32199]: The getnode() ip getter now uses 'ip link' instead of 'ip link list'.

bpo-32143 [https://bugs.python.org/issue?@action=redirect&bpo=32143]: os.statvfs() includes the f_fsid field from statvfs(2)

bpo-26439 [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

bpo-31993 [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.

bpo-27456 [https://bugs.python.org/issue?@action=redirect&bpo=27456]: Ensure TCP_NODELAY is set on Linux. Tests by Victor Stinner.

bpo-31778 [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.

bpo-31802 [https://bugs.python.org/issue?@action=redirect&bpo=31802]: Importing native path module (posixpath, ntpath) now works even if the os module still is not imported.

bpo-30241 [https://bugs.python.org/issue?@action=redirect&bpo=30241]: Add contextlib.AbstractAsyncContextManager. Patch by Jelle Zijlstra.

bpo-31699 [https://bugs.python.org/issue?@action=redirect&bpo=31699]: Fix deadlocks in concurrent.futures.ProcessPoolExecutor when task arguments or results cause pickling or unpickling errors. This should make sure that calls to the ProcessPoolExecutor API always eventually return.

bpo-15216 [https://bugs.python.org/issue?@action=redirect&bpo=15216]: TextIOWrapper.reconfigure() supports changing encoding, errors, and newline.

Documentation

bpo-32418 [https://bugs.python.org/issue?@action=redirect&bpo=32418]: Add get_loop() method to Server and AbstractServer classes.

Tests

bpo-32252 [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.

bpo-32002 [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.

Windows

bpo-19764 [https://bugs.python.org/issue?@action=redirect&bpo=19764]: Implement support for subprocess.Popen(close_fds=True) on Windows. Patch by Segev Finer.

Tools/Demos

bpo-24960 [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.

C API

bpo-32030 [https://bugs.python.org/issue?@action=redirect&bpo=32030]: Py_Initialize() doesn't reset the memory allocators to default if the PYTHONMALLOC environment variable is not set.

bpo-29084 [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.

bpo-32264 [https://bugs.python.org/issue?@action=redirect&bpo=32264]: Moved the pygetopt.h header into internal/, since it has no public APIs.

bpo-32241 [https://bugs.python.org/issue?@action=redirect&bpo=32241]: Py_SetProgramName() and Py_SetPythonHome() now take the const wchar * arguments instead of wchar *.

Python 3.7.0 alpha 3

Release date: 2017-12-05

Core and Builtins

bpo-32176 [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.

bpo-10544 [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.

bpo-32137 [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.

bpo-32096 [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().

bpo-32043 [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.

bpo-32023 [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.

bpo-32012 [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.

bpo-28180 [https://bugs.python.org/issue?@action=redirect&bpo=28180]: A new internal _Py_SetLocaleFromEnv(category) helper function has been added in order to improve the consistency of behaviour across different libc implementations (e.g. Android doesn't support setting the locale from the environment by default).

bpo-31949 [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 2**31 traceback items on Windows. Fixed output errors handling.

bpo-30696 [https://bugs.python.org/issue?@action=redirect&bpo=30696]: Fix the interactive interpreter looping endlessly when no memory.

bpo-20047 [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.

bpo-21720 [https://bugs.python.org/issue?@action=redirect&bpo=21720]: BytesWarning no longer emitted when the fromlist argument of __import__() or the __all__ attribute of the module contain bytes instances.

bpo-31845 [https://bugs.python.org/issue?@action=redirect&bpo=31845]: Environment variables are once more read correctly at interpreter startup.

bpo-28936 [https://bugs.python.org/issue?@action=redirect&bpo=28936]: Ensure that lexically first syntax error involving a parameter and global or nonlocal is detected first at a given scope. Patch by Ivan Levkivskyi.

bpo-31825 [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.

bpo-31618 [https://bugs.python.org/issue?@action=redirect&bpo=31618]: The per-frame tracing logic added in 3.7a1 has been altered so that frame->f_lineno is updated before either "line" or "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 f_trace_lines and f_trace_opcodes are enabled, line events now occur first.

bpo-28603 [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.

bpo-31786 [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.

bpo-31781 [https://bugs.python.org/issue?@action=redirect&bpo=31781]: Prevent crashes when calling methods of an uninitialized zipimport.zipimporter object. Patch by Oren Milman.

bpo-30399 [https://bugs.python.org/issue?@action=redirect&bpo=30399]: Standard repr() of BaseException with a single argument no longer contains redundant trailing comma.

bpo-31626 [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.

bpo-30817 [https://bugs.python.org/issue?@action=redirect&bpo=30817]: PyErr_PrintEx() clears now the ignored exception that may be raised by _PySys_SetObjectId(), for example when no memory.

Library

bpo-28556 [https://bugs.python.org/issue?@action=redirect&bpo=28556]: Two minor fixes for typing module: allow shallow copying instances of generic classes, improve interaction of __init_subclass__ with generics. Original PRs by Ivan Levkivskyi.

bpo-32214 [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.

bpo-27240 [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 [https://bugs.python.org/issue?@action=redirect&bpo=30788], bpo-31831 [https://bugs.python.org/issue?@action=redirect&bpo=31831], and bpo-32182 [https://bugs.python.org/issue?@action=redirect&bpo=32182]. In particular, RFC2231 folding is now done correctly.

bpo-32186 [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.

bpo-32101 [https://bugs.python.org/issue?@action=redirect&bpo=32101]: Add sys.flags.dev_mode flag

bpo-32154 [https://bugs.python.org/issue?@action=redirect&bpo=32154]: The asyncio.windows_utils.socketpair() function has been removed: use directly socket.socketpair() which is available on all platforms since Python 3.5 (before, it wasn't available on Windows). asyncio.windows_utils.socketpair() was just an alias to socket.socketpair on Python 3.5 and newer.

bpo-32089 [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.

bpo-32107 [https://bugs.python.org/issue?@action=redirect&bpo=32107]: 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 uuid.uuid1(). If only locally administered MAC addresses are available, the first such one found is returned.

bpo-23033 [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 ssl.match_hostname(). Patch by Mandeep Singh.

bpo-12239 [https://bugs.python.org/issue?@action=redirect&bpo=12239]: Make msilib.SummaryInformation.GetProperty() return None when the value of property is VT_EMPTY. Initial patch by Mark Mc Mahon.

bpo-28334 [https://bugs.python.org/issue?@action=redirect&bpo=28334]: Use os.path.expanduser() to find the ~/.netrc file in netrc.netrc. If it does not exist, FileNotFoundError is raised. Patch by Dimitri Merejkowsky.

bpo-32121 [https://bugs.python.org/issue?@action=redirect&bpo=32121]: Made tracemalloc.Traceback behave more like the traceback module, sorting the frames from oldest to most recent. Traceback.format() now accepts negative limit, truncating the result to the abs(limit) oldest frames. To get the old behaviour, one can use the new most_recent_first argument to Traceback.format(). (Patch by Jesse Bakker.)

bpo-31325 [https://bugs.python.org/issue?@action=redirect&bpo=31325]: Fix wrong usage of collections.namedtuple() in the RobotFileParser.parse() method. Initial patch by Robin Wellner.

bpo-12382 [https://bugs.python.org/issue?@action=redirect&bpo=12382]: msilib.OpenDatabase() now raises a better exception message when it couldn't open or create an MSI file. Initial patch by William Tisäter.

bpo-19610 [https://bugs.python.org/issue?@action=redirect&bpo=19610]: setup() now warns about invalid types for some fields. The distutils.dist.Distribution class now warns when classifiers, keywords and platforms fields are not specified as a list or a string.

bpo-32071 [https://bugs.python.org/issue?@action=redirect&bpo=32071]: Added the -k command-line option to python -m unittest to run only tests that match the given pattern(s).

bpo-10049 [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.

bpo-28684 [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).

bpo-32110 [https://bugs.python.org/issue?@action=redirect&bpo=32110]: codecs.StreamReader.read(n) now returns not more than n characters/bytes for non-negative n. This makes it compatible with read() methods of other file-like objects.

bpo-27535 [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.

bpo-32088 [https://bugs.python.org/issue?@action=redirect&bpo=32088]: warnings: When Python is build is debug mode (Py_DEBUG), DeprecationWarning, PendingDeprecationWarning and ImportWarning warnings are now displayed by default.

bpo-1647489 [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.

bpo-25054 [https://bugs.python.org/issue?@action=redirect&bpo=25054]: Added support of splitting on a pattern that could match an empty string.

bpo-32072 [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.

bpo-32069 [https://bugs.python.org/issue?@action=redirect&bpo=32069]: Drop legacy SSL transport from asyncio, ssl.MemoryBIO is always used anyway.

bpo-32066 [https://bugs.python.org/issue?@action=redirect&bpo=32066]: asyncio: Support pathlib.Path in create_unix_connection; sock arg should be optional

bpo-32046 [https://bugs.python.org/issue?@action=redirect&bpo=32046]: Updates 2to3 to convert from operator.isCallable(obj) to callable(obj). Patch by Donghee Na.

bpo-32018 [https://bugs.python.org/issue?@action=redirect&bpo=32018]: inspect.signature should follow PEP 8 [https://peps.python.org/pep-0008/], if the parameter has an annotation and a default value. Patch by Donghee Na.

bpo-32025 [https://bugs.python.org/issue?@action=redirect&bpo=32025]: Add time.thread_time() and time.thread_time_ns()

bpo-32037 [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.

bpo-32034 [https://bugs.python.org/issue?@action=redirect&bpo=32034]: Make asyncio.IncompleteReadError and LimitOverrunError pickleable.

bpo-32015 [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.

bpo-32011 [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.

bpo-28369 [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.

bpo-31976 [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.

bpo-31985 [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.

bpo-21862 [https://bugs.python.org/issue?@action=redirect&bpo=21862]: cProfile command line now accepts -m module_name as an alternative to script path. Patch by Sanyam Khurana.

bpo-31970 [https://bugs.python.org/issue?@action=redirect&bpo=31970]: Reduce performance overhead of asyncio debug mode.

bpo-31843 [https://bugs.python.org/issue?@action=redirect&bpo=31843]: database argument of sqlite3.connect() now accepts a path-like object, instead of just a string.

bpo-31945 [https://bugs.python.org/issue?@action=redirect&bpo=31945]: Add Configurable blocksize to HTTPConnection and HTTPSConnection for improved upload throughput. Patch by Nir Soffer.

bpo-31943 [https://bugs.python.org/issue?@action=redirect&bpo=31943]: Add a cancelled() method to asyncio.Handle. Patch by Marat Sharafutdinov.

bpo-9678 [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.

bpo-30057 [https://bugs.python.org/issue?@action=redirect&bpo=30057]: Fix potential missed signal in signal.signal().

bpo-31933 [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.

bpo-21423 [https://bugs.python.org/issue?@action=redirect&bpo=21423]: Add an initializer argument to {Process,Thread}PoolExecutor

bpo-31927 [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.

bpo-27666 [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.

bpo-31917 [https://bugs.python.org/issue?@action=redirect&bpo=31917]: Add 3 new clock identifiers: time.CLOCK_BOOTTIME, time.CLOCK_PROF and time.CLOCK_UPTIME.

bpo-31897 [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.

bpo-25720 [https://bugs.python.org/issue?@action=redirect&bpo=25720]: Fix the method for checking pad state of curses WINDOW. Patch by Masayuki Yamamoto.

bpo-31893 [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.

bpo-31891 [https://bugs.python.org/issue?@action=redirect&bpo=31891]: Fixed building the curses module on NetBSD.

bpo-31884 [https://bugs.python.org/issue?@action=redirect&bpo=31884]: added required constants to subprocess module for setting priority on windows

bpo-28281 [https://bugs.python.org/issue?@action=redirect&bpo=28281]: Remove year (1-9999) limits on the Calendar.weekday() function. Patch by Mark Gollahon.

bpo-31702 [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.

bpo-30639 [https://bugs.python.org/issue?@action=redirect&bpo=30639]: inspect.getfile() no longer computes the repr of unknown objects to display in an error message, to protect against badly behaved custom reprs.

bpo-30768 [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 PEP 475 [https://peps.python.org/pep-0475/].

bpo-31854 [https://bugs.python.org/issue?@action=redirect&bpo=31854]: Add mmap.ACCESS_DEFAULT constant.

bpo-31834 [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.

bpo-28292 [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.

bpo-28564 [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.

bpo-28416 [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.

bpo-31653 [https://bugs.python.org/issue?@action=redirect&bpo=31653]: Don't release the GIL if we can acquire a multiprocessing semaphore immediately.

bpo-28326 [https://bugs.python.org/issue?@action=redirect&bpo=28326]: Fix multiprocessing.Process when stdout and/or stderr is closed or None.

bpo-20825 [https://bugs.python.org/issue?@action=redirect&bpo=20825]: Add subnet_of and superset_of containment tests to ipaddress.IPv6Network and ipaddress.IPv4Network. Patch by Michel Albert and Cheryl Sabella.

bpo-31827 [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.

bpo-31756 [https://bugs.python.org/issue?@action=redirect&bpo=31756]: Add a subprocess.Popen(text=False) keyword argument to subprocess functions to be more explicit about when the library should attempt to decode outputs into text. Patch by Andrew Clegg.

bpo-31819 [https://bugs.python.org/issue?@action=redirect&bpo=31819]: Add AbstractEventLoop.sock_recv_into().

bpo-31457 [https://bugs.python.org/issue?@action=redirect&bpo=31457]: If nested log adapters are used, the inner process() methods are no longer omitted.

bpo-31457 [https://bugs.python.org/issue?@action=redirect&bpo=31457]: The manager property on LoggerAdapter objects is now properly settable.

bpo-31806 [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.

bpo-31803 [https://bugs.python.org/issue?@action=redirect&bpo=31803]: time.clock() and time.get_clock_info('clock') now emit a DeprecationWarning warning.

bpo-31800 [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.

bpo-28603 [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.

bpo-30541 [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.

bpo-31784 [https://bugs.python.org/issue?@action=redirect&bpo=31784]: Implement the PEP 564 [https://peps.python.org/pep-0564/], add new 6 new functions with nanosecond resolution to the time module: clock_gettime_ns(), clock_settime_ns(), monotonic_ns(), perf_counter_ns(), process_time_ns(), time_ns().

bpo-30143 [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.

bpo-31770 [https://bugs.python.org/issue?@action=redirect&bpo=31770]: Prevent a crash when calling the __init__() method of a sqlite3.Cursor object more than once. Patch by Oren Milman.

bpo-31764 [https://bugs.python.org/issue?@action=redirect&bpo=31764]: Prevent a crash in sqlite3.Cursor.close() in case the Cursor object is uninitialized. Patch by Oren Milman.

bpo-31752 [https://bugs.python.org/issue?@action=redirect&bpo=31752]: Fix possible crash in timedelta constructor called with custom integers.

bpo-31620 [https://bugs.python.org/issue?@action=redirect&bpo=31620]: an empty asyncio.Queue now doesn't leak memory when queue.get pollers timeout

bpo-31690 [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.

bpo-30349 [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).

bpo-31664 [https://bugs.python.org/issue?@action=redirect&bpo=31664]: Added support for the Blowfish hashing in the crypt module.

bpo-31632 [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.

bpo-15037 [https://bugs.python.org/issue?@action=redirect&bpo=15037]: Added a workaround for getkey() in curses for ncurses 5.7 and earlier.

bpo-31307 [https://bugs.python.org/issue?@action=redirect&bpo=31307]: Allow use of bytes objects for arguments to configparser.ConfigParser.read(). Patch by Vincent Michel.

bpo-31334 [https://bugs.python.org/issue?@action=redirect&bpo=31334]: Fix poll.poll([timeout]) in the select module for arbitrary negative timeouts on all OSes where it can only be a non-negative integer or -1. Patch by Riccardo Coccioli.

bpo-31310 [https://bugs.python.org/issue?@action=redirect&bpo=31310]: multiprocessing's semaphore tracker should be launched again if crashed.

bpo-31308 [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.

bpo-31245 [https://bugs.python.org/issue?@action=redirect&bpo=31245]: Added support for AF_UNIX socket in asyncio create_datagram_endpoint.

bpo-30553 [https://bugs.python.org/issue?@action=redirect&bpo=30553]: Add HTTP/2 status code 421 (Misdirected Request) to http.HTTPStatus. Patch by Vitor Pereira.

Documentation

bpo-32105 [https://bugs.python.org/issue?@action=redirect&bpo=32105]: Added asyncio.BaseEventLoop.connect_accepted_socket versionadded marker.

Tests

bpo-31380 [https://bugs.python.org/issue?@action=redirect&bpo=31380]: Skip test_httpservers test_undecodable_file on macOS: fails on APFS.

bpo-31705 [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.

bpo-32138 [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.

bpo-32136 [https://bugs.python.org/issue?@action=redirect&bpo=32136]: The runtime embedding tests have been split out from Lib/test/test_capi.py into a new Lib/test/test_embed.py file.

bpo-28668 [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.

bpo-32126 [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.

bpo-31174 [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.

Build

bpo-28538 [https://bugs.python.org/issue?@action=redirect&bpo=28538]: Revert the previous changes, the if_nameindex structure is defined by Unified Headers.

bpo-28762 [https://bugs.python.org/issue?@action=redirect&bpo=28762]: Revert the last commit, the F_LOCK macro is defined by Android Unified Headers.

bpo-29040 [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.

bpo-32059 [https://bugs.python.org/issue?@action=redirect&bpo=32059]: detect_modules() in setup.py now also searches the sysroot paths when cross-compiling.

bpo-31957 [https://bugs.python.org/issue?@action=redirect&bpo=31957]: Fixes Windows SDK version detection when building for Windows.

bpo-31609 [https://bugs.python.org/issue?@action=redirect&bpo=31609]: Fixes quotes in PCbuild/clean.bat

bpo-31934 [https://bugs.python.org/issue?@action=redirect&bpo=31934]: Abort the build when building out of a not clean source tree.

bpo-31926 [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.

bpo-28791 [https://bugs.python.org/issue?@action=redirect&bpo=28791]: Update Windows builds to use SQLite 3.21.0.

bpo-28791 [https://bugs.python.org/issue?@action=redirect&bpo=28791]: Update OS X installer to use SQLite 3.21.0.

bpo-28643 [https://bugs.python.org/issue?@action=redirect&bpo=28643]: Record profile-opt build progress with stamp files.

bpo-31866 [https://bugs.python.org/issue?@action=redirect&bpo=31866]: Finish removing support for AtheOS.

Windows

bpo-1102 [https://bugs.python.org/issue?@action=redirect&bpo=1102]: Return None when View.Fetch() returns ERROR_NO_MORE_ITEMS instead of raising MSIError. Initial patch by Anthony Tuininga.

bpo-31944 [https://bugs.python.org/issue?@action=redirect&bpo=31944]: Fixes Modify button in Apps and Features dialog.

bpo-20486 [https://bugs.python.org/issue?@action=redirect&bpo=20486]: Implement the Database.Close() method to help closing MSI database objects.

bpo-31857 [https://bugs.python.org/issue?@action=redirect&bpo=31857]: Make the behavior of USE_STACKCHECK deterministic in a multi-threaded environment.

macOS

bpo-31392 [https://bugs.python.org/issue?@action=redirect&bpo=31392]: Update macOS installer to use OpenSSL 1.0.2m

IDLE

bpo-32207 [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.

bpo-32164 [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.

bpo-32100 [https://bugs.python.org/issue?@action=redirect&bpo=32100]: IDLE: Fix old and new bugs in pathbrowser; improve tests. Patch mostly by Cheryl Sabella.

bpo-31858 [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.

bpo-31860 [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

bpo-31836 [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.

bpo-28603 [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.

bpo-13802 [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.

Tools/Demos

bpo-32159 [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.

bpo-30722 [https://bugs.python.org/issue?@action=redirect&bpo=30722]: Make redemo work with Python 3.6 and newer versions. Also, remove the LOCALE option since it doesn't work with string patterns in Python 3. Patch by Christoph Sarnowski.

C API

bpo-20891 [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.

bpo-32125 [https://bugs.python.org/issue?@action=redirect&bpo=32125]: The Py_UseClassExceptionsFlag flag has been removed. It was deprecated and wasn't used anymore since Python 2.0.

bpo-25612 [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.

bpo-23699 [https://bugs.python.org/issue?@action=redirect&bpo=23699]: Add Py_RETURN_RICHCOMPARE macro to reduce boilerplate code in rich comparison functions.

bpo-30697 [https://bugs.python.org/issue?@action=redirect&bpo=30697]: The PyExc_RecursionErrorInst singleton is removed and 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 [https://bugs.python.org/issue?@action=redirect&bpo=22898].

Python 3.7.0 alpha 2

Release date: 2017-10-16

Core and Builtins

bpo-31558 [https://bugs.python.org/issue?@action=redirect&bpo=31558]: 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().

bpo-31642 [https://bugs.python.org/issue?@action=redirect&bpo=31642]: Restored blocking "from package import module" by setting sys.modules["package.module"] to None.

bpo-31708 [https://bugs.python.org/issue?@action=redirect&bpo=31708]: Allow use of asynchronous generator expressions in synchronous functions.

bpo-31709 [https://bugs.python.org/issue?@action=redirect&bpo=31709]: Drop support of asynchronous __aiter__.

bpo-30404 [https://bugs.python.org/issue?@action=redirect&bpo=30404]: The -u option now makes the stdout and stderr streams unbuffered rather than line-buffered.

bpo-31619 [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.

bpo-31602 [https://bugs.python.org/issue?@action=redirect&bpo=31602]: Fix an assertion failure in zipimporter.get_source() in case of a bad zlib.decompress(). Patch by Oren Milman.

bpo-31592 [https://bugs.python.org/issue?@action=redirect&bpo=31592]: Fixed an assertion failure in Python parser in case of a bad unicodedata.normalize(). Patch by Oren Milman.

bpo-31588 [https://bugs.python.org/issue?@action=redirect&bpo=31588]: Raise a TypeError with a helpful error message when class creation fails due to a metaclass with a bad __prepare__() method. Patch by Oren Milman.

bpo-31574 [https://bugs.python.org/issue?@action=redirect&bpo=31574]: Importlib was instrumented with two dtrace probes to profile import timing.

bpo-31566 [https://bugs.python.org/issue?@action=redirect&bpo=31566]: Fix an assertion failure in _warnings.warn() in case of a bad __name__ global. Patch by Oren Milman.

bpo-31506 [https://bugs.python.org/issue?@action=redirect&bpo=31506]: Improved the error message logic for object.__new__ and object.__init__.

bpo-31505 [https://bugs.python.org/issue?@action=redirect&bpo=31505]: Fix an assertion failure in json, in case _json.make_encoder() received a bad encoder() argument. Patch by Oren Milman.

bpo-31492 [https://bugs.python.org/issue?@action=redirect&bpo=31492]: Fix assertion failures in case of failing to import from a module with a bad __name__ attribute, and in case of failing to access an attribute of such a module. Patch by Oren Milman.

bpo-31478 [https://bugs.python.org/issue?@action=redirect&bpo=31478]: Fix an assertion failure in _random.Random.seed() in case the argument has a bad __abs__() method. Patch by Oren Milman.

bpo-31336 [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.

bpo-31415 [https://bugs.python.org/issue?@action=redirect&bpo=31415]: Add -X importtime option to show how long each import takes. It can be used to optimize application's startup time. Support the PYTHONPROFILEIMPORTTIME as an equivalent way to enable this.

bpo-31410 [https://bugs.python.org/issue?@action=redirect&bpo=31410]: Optimized calling wrapper and classmethod descriptors.

bpo-31353 [https://bugs.python.org/issue?@action=redirect&bpo=31353]: PEP 553 [https://peps.python.org/pep-0553/] - Add a new built-in called breakpoint() which calls sys.breakpointhook(). By default this imports pdb and calls pdb.set_trace(), but users may override sys.breakpointhook() to call whatever debugger they want. The original value of the hook is saved in sys.__breakpointhook__.

bpo-17852 [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.

bpo-31315 [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.

bpo-31311 [https://bugs.python.org/issue?@action=redirect&bpo=31311]: Fix a crash in the __setstate__() method of ctypes._CData, in case of a bad __dict__. Patch by Oren Milman.

bpo-31293 [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.

bpo-31285 [https://bugs.python.org/issue?@action=redirect&bpo=31285]: Fix an assertion failure in warnings.warn_explicit, when the return value of the received loader's get_source() has a bad splitlines() method. Patch by Oren Milman.

bpo-30406 [https://bugs.python.org/issue?@action=redirect&bpo=30406]: Make async and await proper keywords, as specified in PEP 492 [https://peps.python.org/pep-0492/].

Library

bpo-30058 [https://bugs.python.org/issue?@action=redirect&bpo=30058]: Fixed buffer overflow in select.kqueue.control().

bpo-31672 [https://bugs.python.org/issue?@action=redirect&bpo=31672]: idpattern in string.Template matched some non-ASCII characters. Now it uses -i regular expression local flag to avoid non-ASCII characters.

bpo-31701 [https://bugs.python.org/issue?@action=redirect&bpo=31701]: On Windows, faulthandler.enable() now ignores MSC and COM exceptions.

bpo-31728 [https://bugs.python.org/issue?@action=redirect&bpo=31728]: Prevent crashes in _elementtree due to unsafe cleanup of Element.text and Element.tail. Patch by Oren Milman.

bpo-31671 [https://bugs.python.org/issue?@action=redirect&bpo=31671]: Now re.compile() converts passed RegexFlag to normal int object before compiling. bm_regex_compile benchmark shows 14% performance improvements.

bpo-30397 [https://bugs.python.org/issue?@action=redirect&bpo=30397]: The types of compiled regular objects and match objects are now exposed as re.Pattern and re.Match. This adds information in pydoc output for the re module.

bpo-31675 [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.

bpo-31673 [https://bugs.python.org/issue?@action=redirect&bpo=31673]: Fixed typo in the name of Tkinter's method adderrorinfo().

bpo-31648 [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.

bpo-30806 [https://bugs.python.org/issue?@action=redirect&bpo=30806]: Fix the string representation of a netrc object.

bpo-31638 [https://bugs.python.org/issue?@action=redirect&bpo=31638]: Add optional argument compressed to zipapp.create_archive, and add option --compress to the command line interface of zipapp.

bpo-25351 [https://bugs.python.org/issue?@action=redirect&bpo=25351]: Avoid venv activate failures with undefined variables

bpo-20519 [https://bugs.python.org/issue?@action=redirect&bpo=20519]: Avoid ctypes use (if possible) and improve import time for uuid.

bpo-28293 [https://bugs.python.org/issue?@action=redirect&bpo=28293]: The regular expression cache is no longer completely dumped when it is full.

bpo-31596 [https://bugs.python.org/issue?@action=redirect&bpo=31596]: Added pthread_getcpuclockid() to the time module

bpo-27494 [https://bugs.python.org/issue?@action=redirect&bpo=27494]: Make 2to3 accept a trailing comma in generator expressions. For example, set(x for x in [],) is now allowed.

bpo-30347 [https://bugs.python.org/issue?@action=redirect&bpo=30347]: Stop crashes when concurrently iterate over itertools.groupby() iterators.

bpo-30346 [https://bugs.python.org/issue?@action=redirect&bpo=30346]: An iterator produced by itertools.groupby() iterator now becomes exhausted after advancing the groupby iterator.

bpo-31556 [https://bugs.python.org/issue?@action=redirect&bpo=31556]: Cancel asyncio.wait_for future faster if timeout <= 0

bpo-31540 [https://bugs.python.org/issue?@action=redirect&bpo=31540]: Allow passing a context object in concurrent.futures.ProcessPoolExecutor constructor. Also, free job resources in concurrent.futures.ProcessPoolExecutor earlier to improve memory usage when a worker waits for new jobs.

bpo-31516 [https://bugs.python.org/issue?@action=redirect&bpo=31516]: threading.current_thread() should not return a dummy thread at shutdown.

bpo-31525 [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.

bpo-26510 [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 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.)

bpo-27541 [https://bugs.python.org/issue?@action=redirect&bpo=27541]: Reprs of subclasses of some collection and iterator classes (bytearray, array.array, collections.deque, collections.defaultdict, itertools.count, itertools.repeat) now contain actual type name instead of hardcoded names of the base class.

bpo-31351 [https://bugs.python.org/issue?@action=redirect&bpo=31351]: python -m ensurepip now exits with non-zero exit code if pip bootstrapping has failed.

bpo-31389 [https://bugs.python.org/issue?@action=redirect&bpo=31389]: pdb.set_trace() now takes an optional keyword-only argument header. If given, this is printed to the console just before debugging begins.

Documentation

bpo-31537 [https://bugs.python.org/issue?@action=redirect&bpo=31537]: Fix incorrect usage of get_history_length in readline documentation example code. Patch by Brad Smith.

bpo-30085 [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.

Build

bpo-31696 [https://bugs.python.org/issue?@action=redirect&bpo=31696]: Improve compiler version information in sys.version when Python is built with Clang.

bpo-31625 [https://bugs.python.org/issue?@action=redirect&bpo=31625]: Stop using ranlib on static libraries. Instead, we assume ar supports the 's' flag.

bpo-31624 [https://bugs.python.org/issue?@action=redirect&bpo=31624]: Remove support for BSD/OS.

bpo-22140 [https://bugs.python.org/issue?@action=redirect&bpo=22140]: Prevent double substitution of prefix in python-config.sh.

bpo-31569 [https://bugs.python.org/issue?@action=redirect&bpo=31569]: Correct PCBuild/ case to PCbuild/ in build scripts and documentation.

bpo-31536 [https://bugs.python.org/issue?@action=redirect&bpo=31536]: Avoid wholesale rebuild after make regen-all if nothing changed.

IDLE

bpo-31460 [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.

bpo-31649 [https://bugs.python.org/issue?@action=redirect&bpo=31649]: IDLE - Make _htest, _utest parameters keyword only.

bpo-31559 [https://bugs.python.org/issue?@action=redirect&bpo=31559]: Remove test order dependence in idle_test.test_browser.

bpo-31459 [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.

bpo-31500 [https://bugs.python.org/issue?@action=redirect&bpo=31500]: Default fonts now are scaled on HiDPI displays.

bpo-1612262 [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.

C API

bpo-28280 [https://bugs.python.org/issue?@action=redirect&bpo=28280]: Make PyMapping_Keys(), PyMapping_Values() and PyMapping_Items() always return a list (rather than a list or a tuple). Patch by Oren Milman.

bpo-31532 [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()

bpo-25658 [https://bugs.python.org/issue?@action=redirect&bpo=25658]: Implement PEP 539 [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.

Python 3.7.0 alpha 1

Release date: 2017-09-19

Security

bpo-29781 [https://bugs.python.org/issue?@action=redirect&bpo=29781]: SSLObject.version() now correctly returns None when handshake over BIO has not been performed yet.

bpo-29505 [https://bugs.python.org/issue?@action=redirect&bpo=29505]: Add fuzz tests for float(str), int(str), unicode(str); for oss-fuzz.

bpo-30947 [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.

bpo-30730 [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.

bpo-30694 [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: CVE-2017-9233 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-9233] (External entity infinite loop DoS), CVE-2016-9063 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-9063] (Integer overflow, re-fix), CVE-2016-0718 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-0718] (Fix regression bugs from 2.2.0's fix to CVE-2016-0718 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-0718]) and CVE-2012-0876 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2012-0876] (Counter hash flooding with SipHash). Note: the CVE-2016-5300 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=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 XML_SetHashSalt().

bpo-30500 [https://bugs.python.org/issue?@action=redirect&bpo=30500]: Fix urllib.parse.splithost() to correctly parse fragments. For example, splithost('//127.0.0.1#@evil.com/') now correctly returns the 127.0.0.1 host, instead of treating @evil.com as the host in an authentication (login@host).

bpo-29591 [https://bugs.python.org/issue?@action=redirect&bpo=29591]: Update expat copy from 2.1.1 to 2.2.0 to get fixes of CVE-2016-0718 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-0718] and CVE-2016-4472 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-4472]. See https://sourceforge.net/p/expat/bugs/537/ for more information.

Core and Builtins

bpo-31490 [https://bugs.python.org/issue?@action=redirect&bpo=31490]: Fix an assertion failure in ctypes class definition, in case the class has an attribute whose name is specified in _anonymous_ but not in _fields_. Patch by Oren Milman.

bpo-31471 [https://bugs.python.org/issue?@action=redirect&bpo=31471]: Fix an assertion failure in subprocess.Popen() on Windows, in case the env argument has a bad keys() method. Patch by Oren Milman.

bpo-31418 [https://bugs.python.org/issue?@action=redirect&bpo=31418]: Fix an assertion failure in PyErr_WriteUnraisable() in case of an exception with a bad __module__ attribute. Patch by Oren Milman.

bpo-31416 [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.

bpo-28411 [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.

bpo-28411 [https://bugs.python.org/issue?@action=redirect&bpo=28411]: Switch to the abstract API when dealing with PyInterpreterState.modules. This allows later support for all dict subclasses and other Mapping implementations. Also add a PyImport_GetModule() function to reduce a bunch of duplicated code.

bpo-31411 [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.

bpo-31344 [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: f_trace_lines (True by default) to turn off per-line trace events; and f_trace_opcodes (False by default) to turn on per-opcode trace events.

bpo-31373 [https://bugs.python.org/issue?@action=redirect&bpo=31373]: Fix several possible instances of undefined behavior due to floating-point demotions.

bpo-30465 [https://bugs.python.org/issue?@action=redirect&bpo=30465]: Location information (lineno and 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).

bpo-30860 [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.

bpo-31347 [https://bugs.python.org/issue?@action=redirect&bpo=31347]: Fix possible undefined behavior in _PyObject_FastCall_Prepend.

bpo-31343 [https://bugs.python.org/issue?@action=redirect&bpo=31343]: Include sys/sysmacros.h for major(), minor(), and makedev(). GNU C libray plans to remove the functions from sys/types.h.

bpo-31291 [https://bugs.python.org/issue?@action=redirect&bpo=31291]: Fix an assertion failure in zipimport.zipimporter.get_data on Windows, when the return value of pathname.replace('/','\\') isn't a string. Patch by Oren Milman.

bpo-31271 [https://bugs.python.org/issue?@action=redirect&bpo=31271]: Fix an assertion failure in the write() method of io.TextIOWrapper, when the encoder doesn't return a bytes object. Patch by Oren Milman.

bpo-31243 [https://bugs.python.org/issue?@action=redirect&bpo=31243]: Fix a crash in some methods of io.TextIOWrapper, when the decoder's state is invalid. Patch by Oren Milman.

bpo-30721 [https://bugs.python.org/issue?@action=redirect&bpo=30721]: print now shows correct usage hint for using Python 2 redirection syntax. Patch by Sanyam Khurana.

bpo-31070 [https://bugs.python.org/issue?@action=redirect&bpo=31070]: Fix a race condition in importlib _get_module_lock().

bpo-30747 [https://bugs.python.org/issue?@action=redirect&bpo=30747]: Add a non-dummy implementation of _Py_atomic_store and _Py_atomic_load on MSVC.

bpo-31095 [https://bugs.python.org/issue?@action=redirect&bpo=31095]: Fix potential crash during GC caused by tp_dealloc which doesn't call PyObject_GC_UnTrack().

bpo-31071 [https://bugs.python.org/issue?@action=redirect&bpo=31071]: Avoid masking original TypeError in call with * unpacking when other arguments are passed.

bpo-30978 [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.

bpo-30808 [https://bugs.python.org/issue?@action=redirect&bpo=30808]: Use _Py_atomic API for concurrency-sensitive signal state.

bpo-30876 [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.

bpo-30703 [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).

bpo-30765 [https://bugs.python.org/issue?@action=redirect&bpo=30765]: Avoid blocking in pthread_mutex_lock() when PyThread_acquire_lock() is asked not to block.

bpo-31161 [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.

bpo-30814 [https://bugs.python.org/issue?@action=redirect&bpo=30814]: Fixed a race condition when import a submodule from a package.

bpo-30736 [https://bugs.python.org/issue?@action=redirect&bpo=30736]: The internal unicodedata database has been upgraded to Unicode 10.0.

bpo-30604 [https://bugs.python.org/issue?@action=redirect&bpo=30604]: Move co_extra_freefuncs from per-thread to per-interpreter to avoid crashes.

bpo-30597 [https://bugs.python.org/issue?@action=redirect&bpo=30597]: print now shows expected input in custom error message when used as a Python 2 statement. Patch by Sanyam Khurana.

bpo-30682 [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'").

bpo-30501 [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.

bpo-28180 [https://bugs.python.org/issue?@action=redirect&bpo=28180]: Implement PEP 538 [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.

bpo-30486 [https://bugs.python.org/issue?@action=redirect&bpo=30486]: Allows setting cell values for __closure__. Patch by Lisa Roach.

bpo-30537 [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

bpo-25324 [https://bugs.python.org/issue?@action=redirect&bpo=25324]: Tokens needed for parsing in Python moved to C. COMMENT, NL and ENCODING. This way the tokens and tok_names in the token module don't get changed when you import the tokenize module.

bpo-29104 [https://bugs.python.org/issue?@action=redirect&bpo=29104]: Fixed parsing backslashes in f-strings.

bpo-27945 [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.

bpo-25794 [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.

bpo-30039 [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.

bpo-28974 [https://bugs.python.org/issue?@action=redirect&bpo=28974]: object.__format__(x, '') is now equivalent to str(x) rather than format(str(self), '').

bpo-30024 [https://bugs.python.org/issue?@action=redirect&bpo=30024]: Circular imports involving absolute imports with binding a submodule to a name are now supported.

bpo-12414 [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.

bpo-29839 [https://bugs.python.org/issue?@action=redirect&bpo=29839]: len() now raises ValueError rather than OverflowError if __len__() returned a large negative integer.

bpo-11913 [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.

bpo-29914 [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.

bpo-29949 [https://bugs.python.org/issue?@action=redirect&bpo=29949]: Fix memory usage regression of set and frozenset object.

bpo-29935 [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.

bpo-29816 [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.

bpo-24821 [https://bugs.python.org/issue?@action=redirect&bpo=24821]: Fixed the slowing down to 25 times in the searching of some unlucky Unicode characters.

bpo-29102 [https://bugs.python.org/issue?@action=redirect&bpo=29102]: Add a unique ID to PyInterpreterState. This makes it easier to identify each subinterpreter.

bpo-29894 [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.

bpo-29859 [https://bugs.python.org/issue?@action=redirect&bpo=29859]: Show correct error messages when any of the pthread_* calls in thread_pthread.h fails.

bpo-29849 [https://bugs.python.org/issue?@action=redirect&bpo=29849]: Fix a memory leak when an ImportError is raised during from import.

bpo-28856 [https://bugs.python.org/issue?@action=redirect&bpo=28856]: Fix an oversight that %b format for bytes should support objects follow the buffer protocol.

bpo-29723 [https://bugs.python.org/issue?@action=redirect&bpo=29723]: The sys.path[0] initialization change for bpo-29139 [https://bugs.python.org/issue?@action=redirect&bpo=29139] caused a regression by revealing an inconsistency in how sys.path is initialized when executing __main__ from a zipfile, directory, or other import location. The interpreter now consistently avoids ever adding the import location's parent directory to sys.path, and ensures no other sys.path entries are inadvertently modified when inserting the import location named on the command line.

bpo-29568 [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.

bpo-29714 [https://bugs.python.org/issue?@action=redirect&bpo=29714]: Fix a regression that bytes format may fail when containing zero bytes inside.

bpo-29695 [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.

bpo-28893 [https://bugs.python.org/issue?@action=redirect&bpo=28893]: Set correct __cause__ for errors about invalid awaitables returned from __aiter__ and __anext__.

bpo-28876 [https://bugs.python.org/issue?@action=redirect&bpo=28876]: bool(range) works even if len(range) raises OverflowError.

bpo-29683 [https://bugs.python.org/issue?@action=redirect&bpo=29683]: Fixes to memory allocation in _PyCode_SetExtra. Patch by Brian Coleman.

bpo-29684 [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.

bpo-28598 [https://bugs.python.org/issue?@action=redirect&bpo=28598]: Support __rmod__ for subclasses of str being called before str.__mod__. Patch by Martijn Pieters.

bpo-29607 [https://bugs.python.org/issue?@action=redirect&bpo=29607]: Fix stack_effect computation for CALL_FUNCTION_EX. Patch by Matthieu Dartiailh.

bpo-29602 [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.

bpo-29347 [https://bugs.python.org/issue?@action=redirect&bpo=29347]: Fixed possibly dereferencing undefined pointers when creating weakref objects.

bpo-29463 [https://bugs.python.org/issue?@action=redirect&bpo=29463]: Add docstring field to Module, ClassDef, FunctionDef, and AsyncFunctionDef ast nodes. docstring is not first stmt in their body anymore. It affects co_firstlineno and co_lnotab of code object for module and class. (Reverted in bpo-32911 [https://bugs.python.org/issue?@action=redirect&bpo=32911].)

bpo-29438 [https://bugs.python.org/issue?@action=redirect&bpo=29438]: Fixed use-after-free problem in key sharing dict.

bpo-29546 [https://bugs.python.org/issue?@action=redirect&bpo=29546]: Set the 'path' and 'name' attribute on ImportError for from ... import ....

bpo-29546 [https://bugs.python.org/issue?@action=redirect&bpo=29546]: Improve from-import error message with location

bpo-29478 [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.

bpo-29319 [https://bugs.python.org/issue?@action=redirect&bpo=29319]: Prevent RunMainFromImporter overwriting sys.path[0].

bpo-29337 [https://bugs.python.org/issue?@action=redirect&bpo=29337]: Fixed possible BytesWarning when compare the code objects. Warnings could be emitted at compile time.

bpo-29327 [https://bugs.python.org/issue?@action=redirect&bpo=29327]: Fixed a crash when pass the iterable keyword argument to sorted().

bpo-29034 [https://bugs.python.org/issue?@action=redirect&bpo=29034]: Fix memory leak and use-after-free in os module (path_converter).

bpo-29159 [https://bugs.python.org/issue?@action=redirect&bpo=29159]: Fix regression in bytes(x) when x.__index__() raises Exception.

bpo-29049 [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.

bpo-28927 [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.

bpo-28932 [https://bugs.python.org/issue?@action=redirect&bpo=28932]: Do not include <sys/random.h> if it does not exist.

bpo-25677 [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.

bpo-29000 [https://bugs.python.org/issue?@action=redirect&bpo=29000]: Fixed bytes formatting of octals with zero padding in alternate form.

bpo-18896 [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.

bpo-28596 [https://bugs.python.org/issue?@action=redirect&bpo=28596]: The preferred encoding is UTF-8 on Android. Patch written by Chi Hsuan Yen.

bpo-22257 [https://bugs.python.org/issue?@action=redirect&bpo=22257]: Clean up interpreter startup (see PEP 432 [https://peps.python.org/pep-0432/]).

bpo-26919 [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.

bpo-28991 [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.

bpo-28147 [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.

bpo-28739 [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.

bpo-28512 [https://bugs.python.org/issue?@action=redirect&bpo=28512]: Fixed setting the offset attribute of SyntaxError by PyErr_SyntaxLocationEx() and PyErr_SyntaxLocationObject().

bpo-28918 [https://bugs.python.org/issue?@action=redirect&bpo=28918]: Fix the cross compilation of xxlimited when Python has been built with Py_DEBUG defined.

bpo-23722 [https://bugs.python.org/issue?@action=redirect&bpo=23722]: Rather than silently producing a class that doesn't support zero-argument super() in methods, failing to pass the new __classcell__ namespace entry up to type.__new__ now results in a DeprecationWarning and a class that supports zero-argument super().

bpo-28797 [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.

bpo-28799 [https://bugs.python.org/issue?@action=redirect&bpo=28799]: Remove the PyEval_GetCallStats() function and deprecate the untested and undocumented sys.callstats() function. Remove the CALL_PROFILE special build: use the sys.setprofile() function, cProfile or profile to profile function calls.

bpo-12844 [https://bugs.python.org/issue?@action=redirect&bpo=12844]: More than 255 arguments can now be passed to a function.

bpo-28782 [https://bugs.python.org/issue?@action=redirect&bpo=28782]: Fix a bug in the implementation yield from when checking if the next instruction is YIELD_FROM. Regression introduced by WORDCODE (bpo-26647 [https://bugs.python.org/issue?@action=redirect&bpo=26647]).

bpo-28774 [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).

bpo-28731 [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%.

bpo-28532 [https://bugs.python.org/issue?@action=redirect&bpo=28532]: Show sys.version when -V option is supplied twice.

bpo-27100 [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.

bpo-28746 [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.

bpo-26920 [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.

bpo-28648 [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.

bpo-28665 [https://bugs.python.org/issue?@action=redirect&bpo=28665]: Improve speed of the STORE_DEREF opcode by 40%.

bpo-19398 [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.

bpo-28621 [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.

bpo-28580 [https://bugs.python.org/issue?@action=redirect&bpo=28580]: Optimize iterating split table values. Patch by Xiang Zhang.

bpo-28583 [https://bugs.python.org/issue?@action=redirect&bpo=28583]: PyDict_SetDefault didn't combine split table when needed. Patch by Xiang Zhang.

bpo-28128 [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.

bpo-28509 [https://bugs.python.org/issue?@action=redirect&bpo=28509]: dict.update() no longer allocate unnecessary large memory.

bpo-28426 [https://bugs.python.org/issue?@action=redirect&bpo=28426]: Fixed potential crash in PyUnicode_AsDecodedObject() in debug build.

bpo-28517 [https://bugs.python.org/issue?@action=redirect&bpo=28517]: Fixed of-by-one error in the peephole optimizer that caused keeping unreachable code.

bpo-28214 [https://bugs.python.org/issue?@action=redirect&bpo=28214]: Improved exception reporting for problematic __set_name__ attributes.

bpo-23782 [https://bugs.python.org/issue?@action=redirect&bpo=23782]: Fixed possible memory leak in _PyTraceback_Add() and exception loss in PyTraceBack_Here().

bpo-28183 [https://bugs.python.org/issue?@action=redirect&bpo=28183]: Optimize and cleanup dict iteration.

bpo-26081 [https://bugs.python.org/issue?@action=redirect&bpo=26081]: Added C implementation of asyncio.Future. Original patch by Yury Selivanov.

bpo-28379 [https://bugs.python.org/issue?@action=redirect&bpo=28379]: Added sanity checks and tests for PyUnicode_CopyCharacters(). Patch by Xiang Zhang.

bpo-28376 [https://bugs.python.org/issue?@action=redirect&bpo=28376]: The type of long range iterator is now registered as Iterator. Patch by Oren Milman.

bpo-28376 [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.

bpo-26906 [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.

bpo-18287 [https://bugs.python.org/issue?@action=redirect&bpo=18287]: PyType_Ready() now checks that tp_name is not NULL. Original patch by Niklas Koep.

bpo-24098 [https://bugs.python.org/issue?@action=redirect&bpo=24098]: Fixed possible crash when AST is changed in process of compiling it.

bpo-28201 [https://bugs.python.org/issue?@action=redirect&bpo=28201]: Dict reduces possibility of 2nd conflict in hash table when hashes have same lower bits.

bpo-28350 [https://bugs.python.org/issue?@action=redirect&bpo=28350]: String constants with null character no longer interned.

bpo-26617 [https://bugs.python.org/issue?@action=redirect&bpo=26617]: Fix crash when GC runs during weakref callbacks.

bpo-27942 [https://bugs.python.org/issue?@action=redirect&bpo=27942]: String constants now interned recursively in tuples and frozensets.

bpo-28289 [https://bugs.python.org/issue?@action=redirect&bpo=28289]: ImportError.__init__ now resets not specified attributes.

bpo-21578 [https://bugs.python.org/issue?@action=redirect&bpo=21578]: Fixed misleading error message when ImportError called with invalid keyword args.

bpo-28203 [https://bugs.python.org/issue?@action=redirect&bpo=28203]: Fix incorrect type in complex(1.0, {2:3}) error message. Patch by Soumya Sharma.

bpo-28086 [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.

bpo-28214 [https://bugs.python.org/issue?@action=redirect&bpo=28214]: Now __set_name__ is looked up on the class instead of the instance.

bpo-27955 [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.

bpo-28192 [https://bugs.python.org/issue?@action=redirect&bpo=28192]: Don't import readline in isolated mode.

bpo-27441 [https://bugs.python.org/issue?@action=redirect&bpo=27441]: Remove some redundant assignments to ob_size in longobject.c. Thanks Oren Milman.

bpo-27222 [https://bugs.python.org/issue?@action=redirect&bpo=27222]: Clean up redundant code in long_rshift function. Thanks Oren Milman.

Upgrade internal unicode databases to Unicode version 9.0.0.

bpo-28131 [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.

bpo-28126 [https://bugs.python.org/issue?@action=redirect&bpo=28126]: Replace Py_MEMCPY with memcpy(). Visual Studio can properly optimize memcpy().

bpo-28120 [https://bugs.python.org/issue?@action=redirect&bpo=28120]: Fix dict.pop() for splitted dictionary when trying to remove a "pending key" (Not yet inserted in split-table). Patch by Xiang Zhang.

bpo-26182 [https://bugs.python.org/issue?@action=redirect&bpo=26182]: Raise DeprecationWarning when async and await keywords are used as variable/attribute/class/function name.

bpo-26182 [https://bugs.python.org/issue?@action=redirect&bpo=26182]: Fix a refleak in code that raises DeprecationWarning.

bpo-28721 [https://bugs.python.org/issue?@action=redirect&bpo=28721]: Fix asynchronous generators aclose() and athrow() to handle StopAsyncIteration propagation properly.

bpo-26110 [https://bugs.python.org/issue?@action=redirect&bpo=26110]: Speed-up method calls: add LOAD_METHOD and CALL_METHOD opcodes.

Library

bpo-31499 [https://bugs.python.org/issue?@action=redirect&bpo=31499]: xml.etree: Fix a crash when a parser is part of a reference cycle.

bpo-31482 [https://bugs.python.org/issue?@action=redirect&bpo=31482]: random.seed() now works with bytes in version=1

bpo-28556 [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 globalns was specified by the caller).

bpo-28556 [https://bugs.python.org/issue?@action=redirect&bpo=28556]: Speed improvements to the typing module. Original PRs by Ivan Levkivskyi and Mitar.

bpo-31544 [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().

bpo-31234 [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.

bpo-31457 [https://bugs.python.org/issue?@action=redirect&bpo=31457]: LoggerAdapter objects can now be nested.

bpo-31431 [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.

bpo-31233 [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().

bpo-28638 [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.)

bpo-31400 [https://bugs.python.org/issue?@action=redirect&bpo=31400]: Improves SSL error handling to avoid losing error numbers.

bpo-27629 [https://bugs.python.org/issue?@action=redirect&bpo=27629]: Make return types of SSLContext.wrap_bio() and SSLContext.wrap_socket() customizable.

bpo-28958 [https://bugs.python.org/issue?@action=redirect&bpo=28958]: ssl.SSLContext() now uses OpenSSL error information when a context cannot be instantiated.

bpo-28182 [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.

bpo-27340 [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.

bpo-14191 [https://bugs.python.org/issue?@action=redirect&bpo=14191]: A new function argparse.ArgumentParser.parse_intermixed_args provides the ability to parse command lines where there user intermixes options and positional arguments.

bpo-31178 [https://bugs.python.org/issue?@action=redirect&bpo=31178]: Fix string concatenation bug in rare error path in the subprocess module

bpo-31350 [https://bugs.python.org/issue?@action=redirect&bpo=31350]: Micro-optimize asyncio._get_running_loop() to become up to 10% faster.

bpo-31170 [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): https://github.com/libexpat/libexpat/issues/115

bpo-29136 [https://bugs.python.org/issue?@action=redirect&bpo=29136]: Add TLS 1.3 cipher suites and OP_NO_TLSv1_3.

bpo-1198569 [https://bugs.python.org/issue?@action=redirect&bpo=1198569]: string.Template subclasses can optionally define braceidpattern if they want to specify different placeholder patterns inside and outside the braces. If None (the default) it falls back to idpattern.

bpo-31326 [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.

bpo-27144 [https://bugs.python.org/issue?@action=redirect&bpo=27144]: The map() and as_completed() iterators in concurrent.futures now avoid keeping a reference to yielded objects.

bpo-31281 [https://bugs.python.org/issue?@action=redirect&bpo=31281]: Fix fileinput.FileInput(files, inplace=True) when files contain pathlib.Path objects.

bpo-10746 [https://bugs.python.org/issue?@action=redirect&bpo=10746]: Fix ctypes producing wrong PEP 3118 [https://peps.python.org/pep-3118/] type codes for integer types.

bpo-27584 [https://bugs.python.org/issue?@action=redirect&bpo=27584]: AF_VSOCK has been added to the socket interface which allows communication between virtual machines and their host.

bpo-22536 [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.

bpo-29741 [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.

bpo-31249 [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.

bpo-31247 [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.

bpo-23835 [https://bugs.python.org/issue?@action=redirect&bpo=23835]: configparser: reading defaults in the ConfigParser() constructor is now using 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.

bpo-31238 [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.

bpo-5001 [https://bugs.python.org/issue?@action=redirect&bpo=5001]: Many asserts in multiprocessing are now more informative, and some error types have been changed to more specific ones.

bpo-31109 [https://bugs.python.org/issue?@action=redirect&bpo=31109]: Convert zipimport to use Argument Clinic.

bpo-30102 [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.

bpo-18966 [https://bugs.python.org/issue?@action=redirect&bpo=18966]: Non-daemonic threads created by a multiprocessing.Process are now joined on child exit.

bpo-31183 [https://bugs.python.org/issue?@action=redirect&bpo=31183]: dis now works with asynchronous generator and coroutine objects. Patch by George Collins based on diagnosis by Luciano Ramalho.

bpo-5001 [https://bugs.python.org/issue?@action=redirect&bpo=5001]: There are a number of uninformative asserts in the 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 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).

bpo-31185 [https://bugs.python.org/issue?@action=redirect&bpo=31185]: Fixed miscellaneous errors in asyncio speedup module.

bpo-31151 [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.

bpo-31072 [https://bugs.python.org/issue?@action=redirect&bpo=31072]: Add an include_file parameter to zipapp.create_archive()

bpo-24700 [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.

bpo-31135 [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.

bpo-31107 [https://bugs.python.org/issue?@action=redirect&bpo=31107]: Fix copyreg._slotnames() mangled attribute calculation for classes whose name begins with an underscore. Patch by Shane Harvey.

bpo-31080 [https://bugs.python.org/issue?@action=redirect&bpo=31080]: Allow logging.config.fileConfig to accept kwargs and/or args.

bpo-30897 [https://bugs.python.org/issue?@action=redirect&bpo=30897]: pathlib.Path objects now include an is_mount() method (only implemented on POSIX). This is similar to os.path.ismount(p). Patch by Cooper Ry Lees.

bpo-31061 [https://bugs.python.org/issue?@action=redirect&bpo=31061]: Fixed a crash when using asyncio and threads.

bpo-30987 [https://bugs.python.org/issue?@action=redirect&bpo=30987]: Added support for CAN ISO-TP protocol in the socket module.

bpo-30522 [https://bugs.python.org/issue?@action=redirect&bpo=30522]: Added a setStream method to logging.StreamHandler to allow the stream to be set after creation.

bpo-30502 [https://bugs.python.org/issue?@action=redirect&bpo=30502]: Fix handling of long oids in ssl. Based on patch by Christian Heimes.

bpo-5288 [https://bugs.python.org/issue?@action=redirect&bpo=5288]: Support tzinfo objects with sub-minute offsets.

bpo-30919 [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.

bpo-26732 [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.

bpo-29403 [https://bugs.python.org/issue?@action=redirect&bpo=29403]: Fix unittest.mock's autospec to not fail on method-bound builtin functions. Patch by Aaron Gallagher.

bpo-30961 [https://bugs.python.org/issue?@action=redirect&bpo=30961]: Fix decrementing a borrowed reference in tracemalloc.

bpo-19896 [https://bugs.python.org/issue?@action=redirect&bpo=19896]: Fix multiprocessing.sharedctypes to recognize typecodes 'q' and 'Q'.

bpo-30946 [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.

bpo-25684 [https://bugs.python.org/issue?@action=redirect&bpo=25684]: Change ttk.OptionMenu radiobuttons to be unique across instances of OptionMenu.

bpo-30886 [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.

bpo-29854 [https://bugs.python.org/issue?@action=redirect&bpo=29854]: Fix segfault in readline when using readline's history-size option. Patch by Nir Soffer.

bpo-30794 [https://bugs.python.org/issue?@action=redirect&bpo=30794]: Added multiprocessing.Process.kill method to terminate using the SIGKILL signal on Unix.

bpo-30319 [https://bugs.python.org/issue?@action=redirect&bpo=30319]: socket.close() now ignores ECONNRESET error.

bpo-30828 [https://bugs.python.org/issue?@action=redirect&bpo=30828]: Fix out of bounds write in asyncio.CFuture.remove_done_callback().

bpo-30302 [https://bugs.python.org/issue?@action=redirect&bpo=30302]: Use keywords in the repr of datetime.timedelta.

bpo-30807 [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.

bpo-30441 [https://bugs.python.org/issue?@action=redirect&bpo=30441]: Fix bug when modifying os.environ while iterating over it

bpo-29585 [https://bugs.python.org/issue?@action=redirect&bpo=29585]: Avoid importing sysconfig from site to improve startup speed. Python startup is about 5% faster on Linux and 30% faster on macOS.

bpo-29293 [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.

bpo-30532 [https://bugs.python.org/issue?@action=redirect&bpo=30532]: Fix email header value parser dropping folding white space in certain cases.

bpo-30596 [https://bugs.python.org/issue?@action=redirect&bpo=30596]: Add a close() method to multiprocessing.Process.

bpo-9146 [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.

bpo-29169 [https://bugs.python.org/issue?@action=redirect&bpo=29169]: Update zlib to 1.2.11.

bpo-30119 [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.

bpo-30879 [https://bugs.python.org/issue?@action=redirect&bpo=30879]: os.listdir() and os.scandir() now emit bytes names when called with bytes-like argument.

bpo-30746 [https://bugs.python.org/issue?@action=redirect&bpo=30746]: Prohibited the '=' character in environment variable names in os.putenv() and os.spawn*().

bpo-30664 [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().

bpo-21071 [https://bugs.python.org/issue?@action=redirect&bpo=21071]: struct.Struct.format type is now str instead of bytes.

bpo-29212 [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".

bpo-29755 [https://bugs.python.org/issue?@action=redirect&bpo=29755]: Fixed the lgettext() family of functions in the gettext module. They now always return bytes.

bpo-30616 [https://bugs.python.org/issue?@action=redirect&bpo=30616]: Functional API of enum allows to create empty enums. Patched by Donghee Na

bpo-30038 [https://bugs.python.org/issue?@action=redirect&bpo=30038]: Fix race condition between signal delivery and wakeup file descriptor. Patch by Nathaniel Smith.

bpo-23894 [https://bugs.python.org/issue?@action=redirect&bpo=23894]: lib2to3 now recognizes rb'...' and f'...' strings.

bpo-24744 [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.

bpo-24484 [https://bugs.python.org/issue?@action=redirect&bpo=24484]: Avoid race condition in multiprocessing cleanup.

bpo-30589 [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.

bpo-28994 [https://bugs.python.org/issue?@action=redirect&bpo=28994]: The traceback no longer displayed for SystemExit raised in a callback registered by atexit.

bpo-30508 [https://bugs.python.org/issue?@action=redirect&bpo=30508]: Don't log exceptions if Task/Future "cancel()" method was called.

bpo-30645 [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.

bpo-11822 [https://bugs.python.org/issue?@action=redirect&bpo=11822]: The dis.dis() function now is able to disassemble nested code objects.

bpo-30624 [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'.

bpo-30595 [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.

bpo-28556 [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

bpo-30605 [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.

bpo-29870 [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.

bpo-29743 [https://bugs.python.org/issue?@action=redirect&bpo=29743]: Closing transport during handshake process leaks open socket. Patch by Nikolay Kim

bpo-27585 [https://bugs.python.org/issue?@action=redirect&bpo=27585]: Fix waiter cancellation in asyncio.Lock. Patch by Mathieu Sornay.

bpo-30014 [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'.

bpo-30418 [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.

bpo-30463 [https://bugs.python.org/issue?@action=redirect&bpo=30463]: Addded empty __slots__ to abc.ABC. This allows subclassers to deny __dict__ and __weakref__ creation. Patch by Aaron Hall.

bpo-30520 [https://bugs.python.org/issue?@action=redirect&bpo=30520]: Loggers are now pickleable.

bpo-30557 [https://bugs.python.org/issue?@action=redirect&bpo=30557]: faulthandler now correctly filters and displays exception codes on Windows

bpo-30526 [https://bugs.python.org/issue?@action=redirect&bpo=30526]: Add TextIOWrapper.reconfigure() and a TextIOWrapper.write_through attribute.

bpo-30245 [https://bugs.python.org/issue?@action=redirect&bpo=30245]: Fix possible overflow when organize struct.pack_into error message. Patch by Yuan Liu.

bpo-30378 [https://bugs.python.org/issue?@action=redirect&bpo=30378]: Fix the problem that logging.handlers.SysLogHandler cannot handle IPv6 addresses.

bpo-16500 [https://bugs.python.org/issue?@action=redirect&bpo=16500]: Allow registering at-fork handlers.

bpo-30470 [https://bugs.python.org/issue?@action=redirect&bpo=30470]: Deprecate invalid ctypes call protection on Windows. Patch by Mariatta Wijaya.

bpo-30414 [https://bugs.python.org/issue?@action=redirect&bpo=30414]: multiprocessing.Queue._feed background running thread do not break from main loop on exception.

bpo-30003 [https://bugs.python.org/issue?@action=redirect&bpo=30003]: Fix handling escape characters in HZ codec. Based on patch by Ma Lin.

bpo-30149 [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.

bpo-30436 [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).

bpo-30301 [https://bugs.python.org/issue?@action=redirect&bpo=30301]: Fix AttributeError when using SimpleQueue.empty() under spawn and forkserver start methods.

bpo-30375 [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.

bpo-30329 [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.

bpo-29196 [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.

bpo-9850 [https://bugs.python.org/issue?@action=redirect&bpo=9850]: The macpath is now deprecated and will be removed in Python 3.8.

bpo-30299 [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.

bpo-30048 [https://bugs.python.org/issue?@action=redirect&bpo=30048]: Fixed Task.cancel() can be ignored when the task is running coroutine and the coroutine returned without any more await.

bpo-30266 [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 [https://bugs.python.org/issue?@action=redirect&bpo=25958]. Patch by Jelle Zijlstra.

bpo-30340 [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.

bpo-30298 [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. '(?i)(?s)...'). In verbose mode whitespaces and comments now are allowed before and between inline modifiers (e.g. '(?x) (?i) (?s)...').

bpo-30285 [https://bugs.python.org/issue?@action=redirect&bpo=30285]: Optimized case-insensitive matching and searching of regular expressions.

bpo-29990 [https://bugs.python.org/issue?@action=redirect&bpo=29990]: Fix range checking in GB18030 decoder. Original patch by Ma Lin.

bpo-29979 [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.

bpo-30243 [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.

bpo-30215 [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.

bpo-30185 [https://bugs.python.org/issue?@action=redirect&bpo=30185]: Avoid KeyboardInterrupt tracebacks in forkserver helper process when Ctrl-C is received.

bpo-30103 [https://bugs.python.org/issue?@action=redirect&bpo=30103]: binascii.b2a_uu() and uu.encode() now support using '`' as zero instead of space.

bpo-28556 [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.

bpo-30205 [https://bugs.python.org/issue?@action=redirect&bpo=30205]: Fix getsockname() for unbound AF_UNIX sockets on Linux.

bpo-30228 [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).

bpo-30190 [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')

bpo-30101 [https://bugs.python.org/issue?@action=redirect&bpo=30101]: Add support for curses.A_ITALIC.

bpo-29822 [https://bugs.python.org/issue?@action=redirect&bpo=29822]: inspect.isabstract() now works during __init_subclass__. Patch by Nate Soares.

bpo-29960 [https://bugs.python.org/issue?@action=redirect&bpo=29960]: Preserve generator state when _random.Random.setstate() raises an exception. Patch by Bryan Olson.

bpo-30070 [https://bugs.python.org/issue?@action=redirect&bpo=30070]: Fixed leaks and crashes in errors handling in the parser module.

bpo-22352 [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.

bpo-30061 [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().

bpo-30218 [https://bugs.python.org/issue?@action=redirect&bpo=30218]: Fix PathLike support for shutil.unpack_archive. Patch by Jelle Zijlstra.

bpo-10076 [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).

bpo-30068 [https://bugs.python.org/issue?@action=redirect&bpo=30068]: _io._IOBase.readlines will check if it's closed first when hint is present.

bpo-29694 [https://bugs.python.org/issue?@action=redirect&bpo=29694]: Fixed race condition in pathlib mkdir with flags parents=True. Patch by Armin Rigo.

bpo-29692 [https://bugs.python.org/issue?@action=redirect&bpo=29692]: Fixed arbitrary unchaining of RuntimeError exceptions in contextlib.contextmanager. Patch by Siddharth Velankar.

bpo-26187 [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 [https://bugs.python.org/issue?@action=redirect&bpo=9303]. Patch by Aviv Palivoda.

bpo-30017 [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.

bpo-29998 [https://bugs.python.org/issue?@action=redirect&bpo=29998]: Pickling and copying ImportError now preserves name and path attributes.

bpo-29995 [https://bugs.python.org/issue?@action=redirect&bpo=29995]: re.escape() now escapes only regex special characters.

bpo-29962 [https://bugs.python.org/issue?@action=redirect&bpo=29962]: Add math.remainder operation, implementing remainder as specified in IEEE 754.

bpo-29649 [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.

bpo-29654 [https://bugs.python.org/issue?@action=redirect&bpo=29654]: Support If-Modified-Since HTTP header (browser cache). Patch by Pierre Quentel.

bpo-29931 [https://bugs.python.org/issue?@action=redirect&bpo=29931]: Fixed comparison check for ipaddress.ip_interface objects. Patch by Sanjay Sundaresan.

bpo-29953 [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.

bpo-29942 [https://bugs.python.org/issue?@action=redirect&bpo=29942]: Fix a crash in itertools.chain.from_iterable when encountering long runs of empty iterables.

bpo-10030 [https://bugs.python.org/issue?@action=redirect&bpo=10030]: Sped up reading encrypted ZIP files by 2 times.

bpo-29204 [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.

bpo-27863 [https://bugs.python.org/issue?@action=redirect&bpo=27863]: Fixed multiple crashes in ElementTree caused by race conditions and wrong types.

bpo-25996 [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().

bpo-28699 [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.

bpo-23890 [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.

bpo-29901 [https://bugs.python.org/issue?@action=redirect&bpo=29901]: The zipapp module now supports general path-like objects, not just pathlib.Path.

bpo-25803 [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.

bpo-29861 [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.

bpo-19930 [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.

bpo-29884 [https://bugs.python.org/issue?@action=redirect&bpo=29884]: faulthandler: Restore the old sigaltstack during teardown. Patch by Christophe Zeitouny.

bpo-25455 [https://bugs.python.org/issue?@action=redirect&bpo=25455]: Fixed crashes in repr of recursive buffered file-like objects.

bpo-29800 [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.

bpo-8256 [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.

bpo-28692 [https://bugs.python.org/issue?@action=redirect&bpo=28692]: Using non-integer value for selecting a plural form in gettext is now deprecated.

bpo-26121 [https://bugs.python.org/issue?@action=redirect&bpo=26121]: Use C library implementation for math functions erf() and erfc().

bpo-29619 [https://bugs.python.org/issue?@action=redirect&bpo=29619]: os.stat() and os.DirEntry.inode() now convert inode (st_ino) using unsigned integers.

bpo-28298 [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.

bpo-29645 [https://bugs.python.org/issue?@action=redirect&bpo=29645]: Speed up importing the webbrowser module. webbrowser.register() is now thread-safe.

bpo-28231 [https://bugs.python.org/issue?@action=redirect&bpo=28231]: The zipfile module now accepts path-like objects for external paths.

bpo-26915 [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.

bpo-28682 [https://bugs.python.org/issue?@action=redirect&bpo=28682]: Added support for bytes paths in os.fwalk().

bpo-29728 [https://bugs.python.org/issue?@action=redirect&bpo=29728]: Add new socket.TCP_NOTSENT_LOWAT (Linux 3.12) constant. Patch by Nathaniel J. Smith.

bpo-29623 [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.

bpo-9303 [https://bugs.python.org/issue?@action=redirect&bpo=9303]: Migrate sqlite3 module to _v2 API. Patch by Aviv Palivoda.

bpo-28963 [https://bugs.python.org/issue?@action=redirect&bpo=28963]: Fix out of bound iteration in asyncio.Future.remove_done_callback implemented in C.

bpo-29704 [https://bugs.python.org/issue?@action=redirect&bpo=29704]: asyncio.subprocess.SubprocessStreamProtocol no longer closes before all pipes are closed.

bpo-29271 [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.

bpo-29703 [https://bugs.python.org/issue?@action=redirect&bpo=29703]: Fix asyncio to support instantiation of new event loops in child processes.

bpo-29615 [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.

bpo-7769 [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.

bpo-29376 [https://bugs.python.org/issue?@action=redirect&bpo=29376]: Fix assertion error in threading._DummyThread.is_alive().

bpo-28624 [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.

bpo-28518 [https://bugs.python.org/issue?@action=redirect&bpo=28518]: Start a transaction implicitly before a DML statement. Patch by Aviv Palivoda.

bpo-29742 [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.

bpo-16285 [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.

bpo-29532 [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.

bpo-29110 [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.

bpo-22807 [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.

bpo-29576 [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.

bpo-29534 [https://bugs.python.org/issue?@action=redirect&bpo=29534]: Fixed different behaviour of Decimal.from_float() for _decimal and _pydecimal. Thanks Andrew Nester.

bpo-10379 [https://bugs.python.org/issue?@action=redirect&bpo=10379]: locale.format_string now supports the 'monetary' keyword argument, and locale.format is deprecated.

bpo-29851 [https://bugs.python.org/issue?@action=redirect&bpo=29851]: importlib.reload() now raises ModuleNotFoundError if the module lacks a spec.

bpo-28556 [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.

bpo-29100 [https://bugs.python.org/issue?@action=redirect&bpo=29100]: Fix datetime.fromtimestamp() regression introduced in Python 3.6.0: check minimum and maximum years.

bpo-29416 [https://bugs.python.org/issue?@action=redirect&bpo=29416]: Prevent infinite loop in pathlib.Path.mkdir

bpo-29444 [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.

bpo-29377 [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.

bpo-29218 [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.

bpo-29368 [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.

bpo-29338 [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.

bpo-29335 [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).

bpo-29290 [https://bugs.python.org/issue?@action=redirect&bpo=29290]: Fix a regression in argparse that help messages would wrap at non-breaking spaces.

bpo-28735 [https://bugs.python.org/issue?@action=redirect&bpo=28735]: Fixed the comparison of mock.MagickMock with mock.ANY.

bpo-29197 [https://bugs.python.org/issue?@action=redirect&bpo=29197]: Removed deprecated function ntpath.splitunc().

bpo-29210 [https://bugs.python.org/issue?@action=redirect&bpo=29210]: Removed support of deprecated argument "exclude" in tarfile.TarFile.add().

bpo-29219 [https://bugs.python.org/issue?@action=redirect&bpo=29219]: Fixed infinite recursion in the repr of uninitialized ctypes.CDLL instances.

bpo-29192 [https://bugs.python.org/issue?@action=redirect&bpo=29192]: Removed deprecated features in the http.cookies module.

bpo-29193 [https://bugs.python.org/issue?@action=redirect&bpo=29193]: A format string argument for string.Formatter.format() is now positional-only.

bpo-29195 [https://bugs.python.org/issue?@action=redirect&bpo=29195]: Removed support of deprecated undocumented keyword arguments in methods of regular expression objects.

bpo-28969 [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.

bpo-20804 [https://bugs.python.org/issue?@action=redirect&bpo=20804]: The unittest.mock.sentinel attributes now preserve their identity when they are copied or pickled.

bpo-29142 [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.

bpo-28961 [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.

bpo-15812 [https://bugs.python.org/issue?@action=redirect&bpo=15812]: inspect.getframeinfo() now correctly shows the first line of a context. Patch by Sam Breese.

bpo-28985 [https://bugs.python.org/issue?@action=redirect&bpo=28985]: Update authorizer constants in sqlite3 module. Patch by Dingyuan Wang.

bpo-29079 [https://bugs.python.org/issue?@action=redirect&bpo=29079]: Prevent infinite loop in pathlib.resolve() on Windows

bpo-13051 [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.

bpo-9770 [https://bugs.python.org/issue?@action=redirect&bpo=9770]: curses.ascii predicates now work correctly with negative integers.

bpo-28427 [https://bugs.python.org/issue?@action=redirect&bpo=28427]: old keys should not remove new values from WeakValueDictionary when collecting from another thread.

bpo-28923 [https://bugs.python.org/issue?@action=redirect&bpo=28923]: Remove editor artifacts from Tix.py.

bpo-28871 [https://bugs.python.org/issue?@action=redirect&bpo=28871]: Fixed a crash when deallocate deep ElementTree.

bpo-19542 [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.

bpo-20191 [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.

bpo-16255 [https://bugs.python.org/issue?@action=redirect&bpo=16255]: subprocess.Popen uses /system/bin/sh on Android as the shell, instead of /bin/sh.

bpo-28779 [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.

bpo-26937 [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.

bpo-28847 [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).

bpo-27030 [https://bugs.python.org/issue?@action=redirect&bpo=27030]: Unknown escapes consisting of '\' and an ASCII letter in re.sub() replacement templates regular expressions now are errors.

bpo-28835 [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.

bpo-27172 [https://bugs.python.org/issue?@action=redirect&bpo=27172]: To assist with upgrades from 2.7, the previously documented deprecation of inspect.getfullargspec() has been reversed. This decision may be revisited again after the Python 2.7 branch is no longer officially supported.

bpo-28740 [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.

bpo-26273 [https://bugs.python.org/issue?@action=redirect&bpo=26273]: Add new socket.TCP_CONGESTION (Linux 2.6.13) and socket.TCP_USER_TIMEOUT (Linux 2.6.37) constants. Patch written by Omar Sandoval.

bpo-28752 [https://bugs.python.org/issue?@action=redirect&bpo=28752]: Restored the __reduce__() methods of datetime objects.

bpo-28727 [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 [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).

bpo-20572 [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.

bpo-25659 [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.

bpo-28548 [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.

bpo-19717 [https://bugs.python.org/issue?@action=redirect&bpo=19717]: Makes Path.resolve() succeed on paths that do not exist. Patch by Vajrasky Kok

bpo-28563 [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.

bpo-28387 [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.

bpo-27517 [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.

bpo-28549 [https://bugs.python.org/issue?@action=redirect&bpo=28549]: Fixed segfault in curses's addch() with ncurses6.

bpo-28449 [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.

bpo-23262 [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.

bpo-24241 [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

bpo-27939 [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.

bpo-28255 [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.

bpo-28255 [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.

bpo-20491 [https://bugs.python.org/issue?@action=redirect&bpo=20491]: The textwrap.TextWrapper class now honors non-breaking spaces. Based on patch by Kaarle Ritvanen.

bpo-28353 [https://bugs.python.org/issue?@action=redirect&bpo=28353]: os.fwalk() no longer fails on broken links.

bpo-28430 [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).

bpo-27025 [https://bugs.python.org/issue?@action=redirect&bpo=27025]: Generated names for Tkinter widgets now start by the "!" prefix for readability.

bpo-25464 [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.

bpo-28488 [https://bugs.python.org/issue?@action=redirect&bpo=28488]: shutil.make_archive() no longer adds entry "./" to ZIP archive.

bpo-25953 [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.

bpo-28469 [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.

bpo-28115 [https://bugs.python.org/issue?@action=redirect&bpo=28115]: Command-line interface of the zipfile module now uses argparse. Added support of long options.

bpo-18219 [https://bugs.python.org/issue?@action=redirect&bpo=18219]: Optimize csv.DictWriter for large number of columns. Patch by Mariatta Wijaya.

bpo-28448 [https://bugs.python.org/issue?@action=redirect&bpo=28448]: Fix C implemented asyncio.Future didn't work on Windows.

bpo-23214 [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.

bpo-28480 [https://bugs.python.org/issue?@action=redirect&bpo=28480]: Fix error building socket module when multithreading is disabled.

bpo-28240 [https://bugs.python.org/issue?@action=redirect&bpo=28240]: timeit: remove -c/--clock and -t/--time command line options which were deprecated since Python 3.3.

bpo-28240 [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.

bpo-28240 [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.

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 [https://github.com/pypa/setuptools/issues/100] for rationale.

bpo-24452 [https://bugs.python.org/issue?@action=redirect&bpo=24452]: Make webbrowser support Chrome on Mac OS X. Patch by Ned Batchelder.

bpo-20766 [https://bugs.python.org/issue?@action=redirect&bpo=20766]: Fix references leaked by pdb in the handling of SIGINT handlers.

bpo-27998 [https://bugs.python.org/issue?@action=redirect&bpo=27998]: Fixed bytes path support in os.scandir() on Windows. Patch by Eryk Sun.

bpo-28317 [https://bugs.python.org/issue?@action=redirect&bpo=28317]: The disassembler now decodes FORMAT_VALUE argument.

bpo-28380 [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.

bpo-28229 [https://bugs.python.org/issue?@action=redirect&bpo=28229]: lzma module now supports pathlib.

bpo-28321 [https://bugs.python.org/issue?@action=redirect&bpo=28321]: Fixed writing non-BMP characters with binary format in plistlib.

bpo-28225 [https://bugs.python.org/issue?@action=redirect&bpo=28225]: bz2 module now supports pathlib. Initial patch by Ethan Furman.

bpo-28227 [https://bugs.python.org/issue?@action=redirect&bpo=28227]: gzip now supports pathlib. Patch by Ethan Furman.

bpo-28332 [https://bugs.python.org/issue?@action=redirect&bpo=28332]: Deprecated silent truncations in socket.htons and socket.ntohs. Original patch by Oren Milman.

bpo-27358 [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.

bpo-28257 [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.

bpo-28322 [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.

bpo-28228 [https://bugs.python.org/issue?@action=redirect&bpo=28228]: imghdr now supports pathlib.

bpo-28226 [https://bugs.python.org/issue?@action=redirect&bpo=28226]: compileall now supports pathlib.

bpo-28314 [https://bugs.python.org/issue?@action=redirect&bpo=28314]: Fix function declaration (C flags) for the getiterator() method of xml.etree.ElementTree.Element.

bpo-28148 [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.

bpo-28253 [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.

bpo-28275 [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.

bpo-27897 [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.

bpo-18844 [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.

bpo-18893 [https://bugs.python.org/issue?@action=redirect&bpo=18893]: Fix invalid exception handling in Lib/ctypes/macholib/dyld.py. Patch by Madison May.

bpo-27611 [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.

bpo-27348 [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.

bpo-25651 [https://bugs.python.org/issue?@action=redirect&bpo=25651]: Allow false values to be used for msg parameter of subTest().

bpo-27778 [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.

bpo-28200 [https://bugs.python.org/issue?@action=redirect&bpo=28200]: Fix memory leak on Windows in the os module (fix path_converter() function).

bpo-25400 [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.

bpo-27932 [https://bugs.python.org/issue?@action=redirect&bpo=27932]: Prevent memory leak in win32_ver().

Fix UnboundLocalError in socket._sendfile_use_sendfile.

bpo-28075 [https://bugs.python.org/issue?@action=redirect&bpo=28075]: Check for ERROR_ACCESS_DENIED in Windows implementation of os.stat(). Patch by Eryk Sun.

bpo-22493 [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.

bpo-25270 [https://bugs.python.org/issue?@action=redirect&bpo=25270]: Prevent codecs.escape_encode() from raising SystemError when an empty bytestring is passed.

bpo-28181 [https://bugs.python.org/issue?@action=redirect&bpo=28181]: Get antigravity over HTTPS. Patch by Kaartic Sivaraam.

bpo-25895 [https://bugs.python.org/issue?@action=redirect&bpo=25895]: Enable WebSocket URL schemes in urllib.parse.urljoin. Patch by Gergely Imreh and Markus Holtermann.

bpo-28114 [https://bugs.python.org/issue?@action=redirect&bpo=28114]: Fix a crash in parse_envlist() when env contains byte strings. Patch by Eryk Sun.

bpo-27599 [https://bugs.python.org/issue?@action=redirect&bpo=27599]: Fixed buffer overrun in binascii.b2a_qp() and binascii.a2b_qp().

bpo-27906 [https://bugs.python.org/issue?@action=redirect&bpo=27906]: Fix socket accept exhaustion during high TCP traffic. Patch by Kevin Conway.

bpo-28174 [https://bugs.python.org/issue?@action=redirect&bpo=28174]: Handle when SO_REUSEPORT isn't properly supported. Patch by Seth Michael Larson.

bpo-26654 [https://bugs.python.org/issue?@action=redirect&bpo=26654]: Inspect functools.partial in asyncio.Handle.__repr__. Patch by iceboy.

bpo-26909 [https://bugs.python.org/issue?@action=redirect&bpo=26909]: Fix slow pipes IO in asyncio. Patch by INADA Naoki.

bpo-28176 [https://bugs.python.org/issue?@action=redirect&bpo=28176]: Fix callbacks race in asyncio.SelectorLoop.sock_connect.

bpo-27759 [https://bugs.python.org/issue?@action=redirect&bpo=27759]: Fix selectors incorrectly retain invalid file descriptors. Patch by Mark Williams.

bpo-28325 [https://bugs.python.org/issue?@action=redirect&bpo=28325]: Remove vestigial MacOS 9 macurl2path module and its tests.

bpo-28368 [https://bugs.python.org/issue?@action=redirect&bpo=28368]: Refuse monitoring processes if the child watcher has no loop attached. Patch by Vincent Michel.

bpo-28369 [https://bugs.python.org/issue?@action=redirect&bpo=28369]: Raise RuntimeError when transport's FD is used with add_reader, add_writer, etc.

bpo-28370 [https://bugs.python.org/issue?@action=redirect&bpo=28370]: Speedup asyncio.StreamReader.readexactly. Patch by Коренберг Марк.

bpo-28371 [https://bugs.python.org/issue?@action=redirect&bpo=28371]: Deprecate passing asyncio.Handles to run_in_executor.

bpo-28372 [https://bugs.python.org/issue?@action=redirect&bpo=28372]: Fix asyncio to support formatting of non-python coroutines.

bpo-28399 [https://bugs.python.org/issue?@action=redirect&bpo=28399]: Remove UNIX socket from FS before binding. Patch by Коренберг Марк.

bpo-27972 [https://bugs.python.org/issue?@action=redirect&bpo=27972]: Prohibit Tasks to await on themselves.

bpo-24142 [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.

bpo-29581 [https://bugs.python.org/issue?@action=redirect&bpo=29581]: ABCMeta.__new__ now accepts **kwargs, allowing abstract base classes to use keyword parameters in __init_subclass__. Patch by Nate Soares.

bpo-25532 [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.

bpo-30177 [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.

Documentation

bpo-31294 [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.

bpo-21649 [https://bugs.python.org/issue?@action=redirect&bpo=21649]: Add RFC 7525 and Mozilla server side TLS links to SSL documentation.

bpo-31128 [https://bugs.python.org/issue?@action=redirect&bpo=31128]: Allow the pydoc server to bind to arbitrary hostnames.

bpo-30803 [https://bugs.python.org/issue?@action=redirect&bpo=30803]: Clarify doc on truth value testing. Original patch by Peter Thomassen.

bpo-30176 [https://bugs.python.org/issue?@action=redirect&bpo=30176]: Add missing attribute related constants in curses documentation.

bpo-30052 [https://bugs.python.org/issue?@action=redirect&bpo=30052]: the link targets for bytes() and bytearray() are now their respective type definitions, rather than the corresponding builtin function entries. Use bytes and 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.

bpo-26985 [https://bugs.python.org/issue?@action=redirect&bpo=26985]: Add missing info of code object in inspect documentation.

bpo-19824 [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 [https://bugs.python.org/issue?@action=redirect&bpo=20314], bpo-12518 [https://bugs.python.org/issue?@action=redirect&bpo=12518])

bpo-28929 [https://bugs.python.org/issue?@action=redirect&bpo=28929]: Link the documentation to its source file on GitHub.

bpo-25008 [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.

bpo-26355 [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.

bpo-29349 [https://bugs.python.org/issue?@action=redirect&bpo=29349]: Fix Python 2 syntax in code for building the documentation.

bpo-23722 [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 __classcell__ handling needed for custom metaclasses to fully support PEP 487 [https://peps.python.org/pep-0487/] and zero-argument super().

bpo-28513 [https://bugs.python.org/issue?@action=redirect&bpo=28513]: Documented command-line interface of zipfile.

Tests

bpo-29639 [https://bugs.python.org/issue?@action=redirect&bpo=29639]: test.support.HOST is now "localhost", a new HOSTv4 constant has been added for your 127.0.0.1 needs, similar to the existing HOSTv6 constant.

bpo-31320 [https://bugs.python.org/issue?@action=redirect&bpo=31320]: Silence traceback in test_ssl

bpo-31346 [https://bugs.python.org/issue?@action=redirect&bpo=31346]: Prefer PROTOCOL_TLS_CLIENT and PROTOCOL_TLS_SERVER protocols for SSLContext.

bpo-25674 [https://bugs.python.org/issue?@action=redirect&bpo=25674]: Remove sha256.tbs-internet.com ssl test

bpo-30715 [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.

bpo-30822 [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.

bpo-30695 [https://bugs.python.org/issue?@action=redirect&bpo=30695]: Add the set_nomemory(start, stop) and remove_mem_hooks() functions to the _testcapi module.

bpo-30357 [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.

bpo-30197 [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.

bpo-24932 [https://bugs.python.org/issue?@action=redirect&bpo=24932]: Use proper command line parsing in _testembed

bpo-28950 [https://bugs.python.org/issue?@action=redirect&bpo=28950]: Disallow -j0 to be combined with -T/-l in regrtest command line arguments.

bpo-28683 [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.

bpo-26936 [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.

bpo-28666 [https://bugs.python.org/issue?@action=redirect&bpo=28666]: Now test.support.rmtree is able to remove unwritable or unreadable directories.

bpo-23839 [https://bugs.python.org/issue?@action=redirect&bpo=23839]: Various caches now are cleared before running every test file.

bpo-26944 [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.

bpo-28409 [https://bugs.python.org/issue?@action=redirect&bpo=28409]: regrtest: fix the parser of command line arguments.

bpo-28217 [https://bugs.python.org/issue?@action=redirect&bpo=28217]: Adds _testconsole module to test console input.

bpo-26939 [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.

Build

bpo-31354 [https://bugs.python.org/issue?@action=redirect&bpo=31354]: Allow --with-lto to be used on all builds, not just make profile-opt.

bpo-31370 [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.

bpo-31341 [https://bugs.python.org/issue?@action=redirect&bpo=31341]: Per PEP 11 [https://peps.python.org/pep-0011/], support for the IRIX operating system was removed.

bpo-30854 [https://bugs.python.org/issue?@action=redirect&bpo=30854]: Fix compile error when compiling --without-threads. Patch by Masayuki Yamamoto.

bpo-30687 [https://bugs.python.org/issue?@action=redirect&bpo=30687]: Locate msbuild.exe on Windows when building rather than vcvarsall.bat

bpo-20210 [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.

bpo-29941 [https://bugs.python.org/issue?@action=redirect&bpo=29941]: Add --with-assertions configure flag to explicitly enable C assert() checks. Defaults to off. --with-pydebug implies --with-assertions.

bpo-28787 [https://bugs.python.org/issue?@action=redirect&bpo=28787]: Fix out-of-tree builds of Python when configured with --with--dtrace.

bpo-29243 [https://bugs.python.org/issue?@action=redirect&bpo=29243]: Prevent unnecessary rebuilding of Python during make test, make install and some other make targets when configured with --enable-optimizations.

bpo-23404 [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 make touch with make regen-all.

bpo-29643 [https://bugs.python.org/issue?@action=redirect&bpo=29643]: Fix --enable-optimization didn't work.

bpo-27593 [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.

bpo-29572 [https://bugs.python.org/issue?@action=redirect&bpo=29572]: Update Windows build and OS X installers to use OpenSSL 1.0.2k.

bpo-27659 [https://bugs.python.org/issue?@action=redirect&bpo=27659]: Prohibit implicit C function declarations: use -Werror=implicit-function-declaration when possible (GCC and Clang, but it depends on the compiler version). Patch written by Chi Hsuan Yen.

bpo-29384 [https://bugs.python.org/issue?@action=redirect&bpo=29384]: Remove old Be OS helper scripts.

bpo-26851 [https://bugs.python.org/issue?@action=redirect&bpo=26851]: Set Android compilation and link flags.

bpo-28768 [https://bugs.python.org/issue?@action=redirect&bpo=28768]: Fix implicit declaration of function _setmode. Patch by Masayuki Yamamoto

bpo-29080 [https://bugs.python.org/issue?@action=redirect&bpo=29080]: Removes hard dependency on hg.exe from PCBuild/build.bat

bpo-23903 [https://bugs.python.org/issue?@action=redirect&bpo=23903]: Added missed names to PC/python3.def.

bpo-28762 [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.

bpo-28538 [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.

bpo-20211 [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.

bpo-28849 [https://bugs.python.org/issue?@action=redirect&bpo=28849]: Do not define sys.implementation._multiarch on Android.

bpo-10656 [https://bugs.python.org/issue?@action=redirect&bpo=10656]: Fix out-of-tree building on AIX. Patch by Tristan Carel and Michael Haubenwallner.

bpo-26359 [https://bugs.python.org/issue?@action=redirect&bpo=26359]: Rename --with-optimiations to --enable-optimizations.

bpo-28444 [https://bugs.python.org/issue?@action=redirect&bpo=28444]: Fix missing extensions modules when cross compiling.

bpo-28208 [https://bugs.python.org/issue?@action=redirect&bpo=28208]: Update Windows build and OS X installers to use SQLite 3.14.2.

bpo-28248 [https://bugs.python.org/issue?@action=redirect&bpo=28248]: Update Windows build and OS X installers to use OpenSSL 1.0.2j.

bpo-21124 [https://bugs.python.org/issue?@action=redirect&bpo=21124]: Fix building the _struct module on Cygwin by passing NULL instead of &PyType_Type to PyVarObject_HEAD_INIT. Patch by Masayuki Yamamoto.

bpo-13756 [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.

bpo-21085 [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.

bpo-28258 [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.

bpo-26661 [https://bugs.python.org/issue?@action=redirect&bpo=26661]: setup.py now detects system libffi with multiarch wrapper.

bpo-27979 [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.

bpo-15819 [https://bugs.python.org/issue?@action=redirect&bpo=15819]: Remove redundant include search directory option for building outside the source tree.

bpo-28676 [https://bugs.python.org/issue?@action=redirect&bpo=28676]: Prevent missing 'getentropy' declaration warning on macOS. Patch by Gareth Rees.

Windows

bpo-31392 [https://bugs.python.org/issue?@action=redirect&bpo=31392]: Update Windows build to use OpenSSL 1.1.0f

bpo-30389 [https://bugs.python.org/issue?@action=redirect&bpo=30389]: Adds detection of Visual Studio 2017 to distutils on Windows.

bpo-31358 [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.

bpo-31340 [https://bugs.python.org/issue?@action=redirect&bpo=31340]: Change to building with MSVC v141 (included with Visual Studio 2017)

bpo-30581 [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.

bpo-30916 [https://bugs.python.org/issue?@action=redirect&bpo=30916]: Pre-build OpenSSL, Tcl and Tk and include the binaries in the build.

bpo-30731 [https://bugs.python.org/issue?@action=redirect&bpo=30731]: Add a missing xmlns to python.manifest so that it matches the schema.

bpo-30291 [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.

bpo-30362 [https://bugs.python.org/issue?@action=redirect&bpo=30362]: Adds list options (-0, -0p) to py.exe launcher. Contributed by Steve Barnes.

bpo-23451 [https://bugs.python.org/issue?@action=redirect&bpo=23451]: Fix socket deprecation warnings in socketmodule.c. Patch by Segev Finer.

bpo-30450 [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 py -3.6), NuGet is used to download a copy of 32-bit Python.

bpo-29579 [https://bugs.python.org/issue?@action=redirect&bpo=29579]: Removes readme.txt from the installer.

bpo-25778 [https://bugs.python.org/issue?@action=redirect&bpo=25778]: winreg does not truncate string correctly (Patch by Eryk Sun)

bpo-28896 [https://bugs.python.org/issue?@action=redirect&bpo=28896]: Deprecate WindowsRegistryFinder and disable it by default

bpo-28522 [https://bugs.python.org/issue?@action=redirect&bpo=28522]: Fixes mishandled buffer reallocation in getpathp.c

bpo-28402 [https://bugs.python.org/issue?@action=redirect&bpo=28402]: Adds signed catalog files for stdlib on Windows.

bpo-28333 [https://bugs.python.org/issue?@action=redirect&bpo=28333]: Enables Unicode for ps1/ps2 and input() prompts. (Patch by Eryk Sun)

bpo-28251 [https://bugs.python.org/issue?@action=redirect&bpo=28251]: Improvements to help manuals on Windows.

bpo-28110 [https://bugs.python.org/issue?@action=redirect&bpo=28110]: launcher.msi has different product codes between 32-bit and 64-bit

bpo-28161 [https://bugs.python.org/issue?@action=redirect&bpo=28161]: Opening CON for write access fails

bpo-28162 [https://bugs.python.org/issue?@action=redirect&bpo=28162]: WindowsConsoleIO readall() fails if first line starts with Ctrl+Z

bpo-28163 [https://bugs.python.org/issue?@action=redirect&bpo=28163]: WindowsConsoleIO fileno() passes wrong flags to _open_osfhandle

bpo-28164 [https://bugs.python.org/issue?@action=redirect&bpo=28164]: _PyIO_get_console_type fails for various paths

bpo-28137 [https://bugs.python.org/issue?@action=redirect&bpo=28137]: Renames Windows path file to ._pth

bpo-28138 [https://bugs.python.org/issue?@action=redirect&bpo=28138]: Windows ._pth file should allow import site

IDLE

bpo-31493 [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.

bpo-31488 [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.

bpo-31477 [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.

bpo-31480 [https://bugs.python.org/issue?@action=redirect&bpo=31480]: IDLE - make tests pass with zzdummy extension disabled by default.

bpo-31421 [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.

bpo-31414 [https://bugs.python.org/issue?@action=redirect&bpo=31414]: IDLE -- fix tk entry box tests by deleting first. Adding to an int entry is not the same as deleting and inserting because int('') will fail.

bpo-31051 [https://bugs.python.org/issue?@action=redirect&bpo=31051]: Rearrange IDLE configdialog GenPage into Window, Editor, and Help sections.

bpo-30617 [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.

bpo-31287 [https://bugs.python.org/issue?@action=redirect&bpo=31287]: IDLE - Do not modify tkinter.message in test_configdialog.

bpo-27099 [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.

bpo-31206 [https://bugs.python.org/issue?@action=redirect&bpo=31206]: IDLE: Factor HighPage(Frame) class from ConfigDialog. Patch by Cheryl Sabella.

bpo-31001 [https://bugs.python.org/issue?@action=redirect&bpo=31001]: Add tests for configdialog highlight tab. Patch by Cheryl Sabella.

bpo-31205 [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.

bpo-31130 [https://bugs.python.org/issue?@action=redirect&bpo=31130]: IDLE -- stop leaks in test_configdialog. Initial patch by Victor Stinner.

bpo-31002 [https://bugs.python.org/issue?@action=redirect&bpo=31002]: Add tests for configdialog keys tab. Patch by Cheryl Sabella.

bpo-19903 [https://bugs.python.org/issue?@action=redirect&bpo=19903]: IDLE: Calltips use inspect.signature instead of inspect.getfullargspec. This improves calltips for builtins converted to use Argument Clinic. Patch by Louie Lu.

bpo-31083 [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.

bpo-31050 [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.

bpo-31004 [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.

bpo-30781 [https://bugs.python.org/issue?@action=redirect&bpo=30781]: IDLE - Use ttk widgets in ConfigDialog. Patches by Terry Jan Reedy and Cheryl Sabella.

bpo-31060 [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.

bpo-30853 [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%.

bpo-31003 [https://bugs.python.org/issue?@action=redirect&bpo=31003]: IDLE: Add more tests for General tab.

bpo-30993 [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.

bpo-30981 [https://bugs.python.org/issue?@action=redirect&bpo=30981]: IDLE -- Add more configdialog font page tests.

bpo-28523 [https://bugs.python.org/issue?@action=redirect&bpo=28523]: IDLE: replace 'colour' with 'color' in configdialog.

bpo-30917 [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.

bpo-30934 [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.

bpo-30913 [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.

bpo-30899 [https://bugs.python.org/issue?@action=redirect&bpo=30899]: IDLE: Add tests for ConfigParser subclasses in config. Patch by Louie Lu.

bpo-30881 [https://bugs.python.org/issue?@action=redirect&bpo=30881]: IDLE: Add docstrings to browser.py. Patch by Cheryl Sabella.

bpo-30851 [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.

bpo-30870 [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.

bpo-8231 [https://bugs.python.org/issue?@action=redirect&bpo=8231]: IDLE: call config.IdleConf.GetUserCfgDir only once.

bpo-30779 [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.

bpo-30777 [https://bugs.python.org/issue?@action=redirect&bpo=30777]: IDLE: configdialog - Add docstrings and fix comments. Patch by Cheryl Sabella.

bpo-30495 [https://bugs.python.org/issue?@action=redirect&bpo=30495]: IDLE: Improve textview with docstrings, PEP8 names, and more tests. Patch by Cheryl Sabella.

bpo-30723 [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.

bpo-30674 [https://bugs.python.org/issue?@action=redirect&bpo=30674]: IDLE: add docstrings to grep module. Patch by Cheryl Sabella

bpo-21519 [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.

bpo-29910 [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 return 'break' for this and other potential conflicts between IDLE and default key bindings.

bpo-30728 [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 import * with specific imports. Patches by Cheryl Sabella.

bpo-6739 [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.

bpo-15786 [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.

bpo-25514 [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.

bpo-30642 [https://bugs.python.org/issue?@action=redirect&bpo=30642]: Fix reference leaks in IDLE tests. Patches by Louie Lu and Terry Jan Reedy.

bpo-30495 [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.

bpo-30290 [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.

bpo-30303 [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.

bpo-29071 [https://bugs.python.org/issue?@action=redirect&bpo=29071]: IDLE colors f-string prefixes (but not invalid ur prefixes).

bpo-28572 [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.

Tools/Demos

bpo-30983 [https://bugs.python.org/issue?@action=redirect&bpo=30983]: gdb integration commands (py-bt, etc.) work on optimized shared builds now, too. PEP 523 [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.

bpo-29748 [https://bugs.python.org/issue?@action=redirect&bpo=29748]: Added the slice index converter in Argument Clinic.

bpo-24037 [https://bugs.python.org/issue?@action=redirect&bpo=24037]: Argument Clinic now uses the converter bool(accept={int}) rather than int for semantical booleans. This avoids repeating the default value for Python and C and will help in converting to bool in future.

bpo-29367 [https://bugs.python.org/issue?@action=redirect&bpo=29367]: python-gdb.py now supports also method-wrapper (wrapperobject) objects.

bpo-28023 [https://bugs.python.org/issue?@action=redirect&bpo=28023]: Fix python-gdb.py didn't support new dict implementation.

bpo-15369 [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 https://github.com/python/pyperformance which is more reliable and includes a portable version of pybench working on Python 2 and Python 3.

bpo-28102 [https://bugs.python.org/issue?@action=redirect&bpo=28102]: The zipfile module CLI now prints usage to stderr. Patch by Stephen J. Turnbull.

C API

bpo-31338 [https://bugs.python.org/issue?@action=redirect&bpo=31338]: Added the 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.

bpo-30832 [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.

bpo-30708 [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.

bpo-16500 [https://bugs.python.org/issue?@action=redirect&bpo=16500]: Deprecate PyOS_AfterFork() and add PyOS_BeforeFork(), PyOS_AfterFork_Parent() and PyOS_AfterFork_Child().

bpo-6532 [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".

bpo-27867 [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().

bpo-29083 [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.

bpo-28769 [https://bugs.python.org/issue?@action=redirect&bpo=28769]: The result of PyUnicode_AsUTF8AndSize() and PyUnicode_AsUTF8() is now of type const char * rather of char *.

bpo-29058 [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.

bpo-28822 [https://bugs.python.org/issue?@action=redirect&bpo=28822]: The index parameters start and end of PyUnicode_FindChar() are now adjusted to behave like str[start:end].

bpo-28808 [https://bugs.python.org/issue?@action=redirect&bpo=28808]: PyUnicode_CompareWithASCIIString() now never raises exceptions.

bpo-28761 [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 const char * rather of char *.

bpo-28748 [https://bugs.python.org/issue?@action=redirect&bpo=28748]: Private variable _Py_PackageContext is now of type const char * rather of char *.

bpo-19569 [https://bugs.python.org/issue?@action=redirect&bpo=19569]: Compiler warnings are now emitted if use most of deprecated functions.

bpo-28426 [https://bugs.python.org/issue?@action=redirect&bpo=28426]: Deprecated undocumented functions PyUnicode_AsEncodedObject(), PyUnicode_AsDecodedObject(), PyUnicode_AsDecodedUnicode() and PyUnicode_AsEncodedUnicode().

Python 3.6.6 final

Release date: 2018-06-27

There were no new changes in version 3.6.6.

Python 3.6.6 release candidate 1

Release date: 2018-06-11

Core and Builtins

bpo-33786 [https://bugs.python.org/issue?@action=redirect&bpo=33786]: Fix asynchronous generators to handle GeneratorExit in athrow() correctly

bpo-30654 [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.

bpo-33622 [https://bugs.python.org/issue?@action=redirect&bpo=33622]: Fixed a leak when the garbage collector fails to add an object with the __del__ method or referenced by it into the gc.garbage list. PyGC_Collect() can now be called when an exception is set and preserves it.

bpo-31849 [https://bugs.python.org/issue?@action=redirect&bpo=31849]: Fix signed/unsigned comparison warning in pyhash.c.

bpo-33391 [https://bugs.python.org/issue?@action=redirect&bpo=33391]: Fix a leak in set_symmetric_difference().

bpo-28055 [https://bugs.python.org/issue?@action=redirect&bpo=28055]: Fix unaligned accesses in siphash24(). Patch by Rolf Eike Beer.

bpo-33231 [https://bugs.python.org/issue?@action=redirect&bpo=33231]: Fix potential memory leak in normalizestring().

bpo-29922 [https://bugs.python.org/issue?@action=redirect&bpo=29922]: Improved error messages in 'async with' when __aenter__() or __aexit__() return non-awaitable object.

bpo-33199 [https://bugs.python.org/issue?@action=redirect&bpo=33199]: Fix ma_version_tag in dict implementation is uninitialized when copying from key-sharing dict.

bpo-33041 [https://bugs.python.org/issue?@action=redirect&bpo=33041]: Fixed jumping when the function contains an async for loop.

bpo-32282 [https://bugs.python.org/issue?@action=redirect&bpo=32282]: Fix an unnecessary ifdef in the include of VersionHelpers.h in socketmodule on Windows.

bpo-21983 [https://bugs.python.org/issue?@action=redirect&bpo=21983]: Fix a crash in ctypes.cast() in case the type argument is a ctypes structured data type. Patch by Eryk Sun and Oren Milman.

Library

bpo-30167 [https://bugs.python.org/issue?@action=redirect&bpo=30167]: Prevent site.main() exception if PYTHONSTARTUP is set. Patch by Steve Weber.

bpo-33812 [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.

bpo-30805 [https://bugs.python.org/issue?@action=redirect&bpo=30805]: Avoid race condition with debug logging

bpo-33767 [https://bugs.python.org/issue?@action=redirect&bpo=33767]: The concatenation (+) and repetition (*) sequence operations now raise TypeError instead of SystemError when performed on mmap.mmap objects. Patch by Zackery Spytz.

bpo-32684 [https://bugs.python.org/issue?@action=redirect&bpo=32684]: Fix gather to propagate cancellation of itself even with return_exceptions.

bpo-33674 [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.

bpo-31647 [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.

bpo-33672 [https://bugs.python.org/issue?@action=redirect&bpo=33672]: Fix Task.__repr__ crash with Cython's bogus coroutines

bpo-33469 [https://bugs.python.org/issue?@action=redirect&bpo=33469]: Fix RuntimeError after closing loop that used run_in_executor

bpo-11874 [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.

bpo-30877 [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.

bpo-33548 [https://bugs.python.org/issue?@action=redirect&bpo=33548]: tempfile._candidate_tempdir_list should consider common TEMP locations

bpo-33542 [https://bugs.python.org/issue?@action=redirect&bpo=33542]: Prevent uuid.get_node from using a DUID instead of a MAC on Windows. Patch by Zvi Effron

bpo-26819 [https://bugs.python.org/issue?@action=redirect&bpo=26819]: Fix race condition with ReadTransport.resume_reading in Windows proactor event loop.

bpo-28556 [https://bugs.python.org/issue?@action=redirect&bpo=28556]: Minor fixes in typing module: add annotations to NamedTuple.__new__, pass *args and **kwds in Generic.__new__. Original PRs by Paulius Šarka and Chad Dombrova.

bpo-20087 [https://bugs.python.org/issue?@action=redirect&bpo=20087]: Updated alias mapping with glibc 2.27 supported locales.

bpo-33422 [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.

bpo-33197 [https://bugs.python.org/issue?@action=redirect&bpo=33197]: Update error message when constructing invalid inspect.Parameters Patch by Donghee Na.

bpo-33383 [https://bugs.python.org/issue?@action=redirect&bpo=33383]: Fixed crash in the get() method of the dbm.ndbm database object when it is called with a single argument.

bpo-33329 [https://bugs.python.org/issue?@action=redirect&bpo=33329]: Fix multiprocessing regression on newer glibcs

bpo-991266 [https://bugs.python.org/issue?@action=redirect&bpo=991266]: Fix quoting of the Comment attribute of http.cookies.SimpleCookie.

bpo-33131 [https://bugs.python.org/issue?@action=redirect&bpo=33131]: Upgrade bundled version of pip to 10.0.1.

bpo-33308 [https://bugs.python.org/issue?@action=redirect&bpo=33308]: Fixed a crash in the parser module when converting an ST object to a tree of tuples or lists with line_info=False and col_info=True.

bpo-33263 [https://bugs.python.org/issue?@action=redirect&bpo=33263]: Fix FD leak in _SelectorSocketTransport Patch by Vlad Starostin.

bpo-33256 [https://bugs.python.org/issue?@action=redirect&bpo=33256]: Fix display of <module> call in the html produced by cgitb.html(). Patch by Stéphane Blondon.

bpo-33203 [https://bugs.python.org/issue?@action=redirect&bpo=33203]: random.Random.choice() now raises IndexError for empty sequences consistently even when called from subclasses without a getrandbits() implementation.

bpo-33224 [https://bugs.python.org/issue?@action=redirect&bpo=33224]: Update difflib.mdiff() for PEP 479 [https://peps.python.org/pep-0479/]. Convert an uncaught StopIteration in a generator into a return-statement.

bpo-33209 [https://bugs.python.org/issue?@action=redirect&bpo=33209]: End framing at the end of C implementation of pickle.Pickler.dump().

bpo-32861 [https://bugs.python.org/issue?@action=redirect&bpo=32861]: The urllib.robotparser's __str__ representation now includes wildcard entries and the "Crawl-delay" and "Request-rate" fields. Patch by Michael Lazar.

bpo-33096 [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.

bpo-33127 [https://bugs.python.org/issue?@action=redirect&bpo=33127]: The ssl module now compiles with LibreSSL 2.7.1.

bpo-33021 [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.

bpo-27683 [https://bugs.python.org/issue?@action=redirect&bpo=27683]: Fix a regression in ipaddress that result of hosts() is empty when the network is constructed by a tuple containing an integer mask and only 1 bit left for addresses.

bpo-32844 [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.

bpo-31908 [https://bugs.python.org/issue?@action=redirect&bpo=31908]: Fix output of cover files for trace module command-line tool. Previously emitted cover files only when --missing option was used. Patch by Michael Selik.

bpo-31457 [https://bugs.python.org/issue?@action=redirect&bpo=31457]: If nested log adapters are used, the inner process() methods are no longer omitted.

bpo-16865 [https://bugs.python.org/issue?@action=redirect&bpo=16865]: Support arrays >=2GiB in ctypes. Patch by Segev Finer.

bpo-31238 [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.

Documentation

bpo-33503 [https://bugs.python.org/issue?@action=redirect&bpo=33503]: Fix broken pypi link

bpo-33421 [https://bugs.python.org/issue?@action=redirect&bpo=33421]: Add missing documentation for typing.AsyncContextManager.

bpo-33378 [https://bugs.python.org/issue?@action=redirect&bpo=33378]: Add Korean language switcher for https://docs.python.org/3/

bpo-33276 [https://bugs.python.org/issue?@action=redirect&bpo=33276]: Clarify that the __path__ attribute on modules cannot be just any value.

bpo-33201 [https://bugs.python.org/issue?@action=redirect&bpo=33201]: Modernize documentation for writing C extension types.

bpo-33195 [https://bugs.python.org/issue?@action=redirect&bpo=33195]: Deprecate Py_UNICODE usage in c-api/arg document. Py_UNICODE related APIs are deprecated since Python 3.3, but it is missed in the document.

bpo-33126 [https://bugs.python.org/issue?@action=redirect&bpo=33126]: Document PyBuffer_ToContiguous().

bpo-27212 [https://bugs.python.org/issue?@action=redirect&bpo=27212]: Modify documentation for the islice() recipe to consume initial values up to the start index.

bpo-28247 [https://bugs.python.org/issue?@action=redirect&bpo=28247]: Update zipapp documentation to describe how to make standalone applications.

bpo-18802 [https://bugs.python.org/issue?@action=redirect&bpo=18802]: Documentation changes for ipaddress. Patch by Jon Foster and Berker Peksag.

bpo-27428 [https://bugs.python.org/issue?@action=redirect&bpo=27428]: Update documentation to clarify that WindowsRegistryFinder implements MetaPathFinder. (Patch by Himanshu Lakhara)

bpo-8243 [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.

bpo-31432 [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.

Tests

bpo-33655 [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.

bpo-19417 [https://bugs.python.org/issue?@action=redirect&bpo=19417]: Add test_bdb.py.

Build

bpo-5755 [https://bugs.python.org/issue?@action=redirect&bpo=5755]: Move -Wstrict-prototypes option to CFLAGS_NODIST from OPT. This option emitted annoying warnings when building extension modules written in C++.

bpo-33614 [https://bugs.python.org/issue?@action=redirect&bpo=33614]: Ensures module definition files for the stable ABI on Windows are correctly regenerated.

bpo-33522 [https://bugs.python.org/issue?@action=redirect&bpo=33522]: Enable CI builds on Visual Studio Team Services at https://python.visualstudio.com/cpython

bpo-33012 [https://bugs.python.org/issue?@action=redirect&bpo=33012]: Add -Wno-cast-function-type for gcc 8 for silencing warnings about function casts like casting to PyCFunction in method definition lists.

bpo-33394 [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.

Windows

bpo-33184 [https://bugs.python.org/issue?@action=redirect&bpo=33184]: Update Windows installer to OpenSSL 1.0.2o.

macOS

bpo-33184 [https://bugs.python.org/issue?@action=redirect&bpo=33184]: Update macOS installer build to use OpenSSL 1.0.2o.

IDLE

bpo-33656 [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.

bpo-33768 [https://bugs.python.org/issue?@action=redirect&bpo=33768]: Clicking on a context line moves that line to the top of the editor window.

bpo-33763 [https://bugs.python.org/issue?@action=redirect&bpo=33763]: IDLE: Use read-only text widget for code context instead of label widget.

bpo-33664 [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.

bpo-33679 [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.

bpo-33642 [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.

bpo-33628 [https://bugs.python.org/issue?@action=redirect&bpo=33628]: IDLE: Cleanup codecontext.py and its test.

bpo-33564 [https://bugs.python.org/issue?@action=redirect&bpo=33564]: IDLE's code context now recognizes async as a block opener.

bpo-29706 [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.

bpo-21474 [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.

bpo-33204 [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.

bpo-32831 [https://bugs.python.org/issue?@action=redirect&bpo=32831]: Add docstrings and tests for codecontext.

Tools/Demos

bpo-33189 [https://bugs.python.org/issue?@action=redirect&bpo=33189]: pygettext.py now recognizes only literal strings as docstrings and translatable strings, and rejects bytes literals and f-string expressions.

bpo-31920 [https://bugs.python.org/issue?@action=redirect&bpo=31920]: Fixed handling directories as arguments in the pygettext script. Based on patch by Oleg Krasnikov.

bpo-29673 [https://bugs.python.org/issue?@action=redirect&bpo=29673]: Fix pystackv and pystack gdbinit macros.

bpo-32885 [https://bugs.python.org/issue?@action=redirect&bpo=32885]: Add an -n flag for Tools/scripts/pathfix.py to disable automatic backup creation (files with ~ suffix).

bpo-31583 [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.

C API

bpo-32374 [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

Python 3.6.5 final

Release date: 2018-03-28

Tests

bpo-32872 [https://bugs.python.org/issue?@action=redirect&bpo=32872]: Avoid regrtest compatibility issue with namespace packages.

Build

bpo-33163 [https://bugs.python.org/issue?@action=redirect&bpo=33163]: Upgrade pip to 9.0.3 and setuptools to v39.0.1.

Python 3.6.5 release candidate 1

Release date: 2018-03-13

Security

bpo-33001 [https://bugs.python.org/issue?@action=redirect&bpo=33001]: Minimal fix to prevent buffer overrun in os.symlink on Windows

bpo-32981 [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 CVE-2018-1060 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-1060] and CVE-2018-1061 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-1061]. Patch by Jamie Davis.

Core and Builtins

bpo-33026 [https://bugs.python.org/issue?@action=redirect&bpo=33026]: Fixed jumping out of "with" block by setting f_lineno.

bpo-17288 [https://bugs.python.org/issue?@action=redirect&bpo=17288]: Prevent jumps from 'return' and 'exception' trace events.

bpo-32889 [https://bugs.python.org/issue?@action=redirect&bpo=32889]: Update Valgrind suppression list to account for the rename of Py_ADDRESS_IN_RANG to address_in_range.

bpo-32650 [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.

bpo-32685 [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.

bpo-32583 [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.

bpo-26163 [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.

bpo-27169 [https://bugs.python.org/issue?@action=redirect&bpo=27169]: The __debug__ constant is now optimized out at compile time. This fixes also bpo-22091 [https://bugs.python.org/issue?@action=redirect&bpo=22091].

bpo-32329 [https://bugs.python.org/issue?@action=redirect&bpo=32329]: sys.flags.hash_randomization is now properly set to 0 when hash randomization is turned off by PYTHONHASHSEED=0.

bpo-30416 [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.

bpo-18533 [https://bugs.python.org/issue?@action=redirect&bpo=18533]: repr() on a dict containing its own values() or items() no longer raises RecursionError; OrderedDict similarly. Instead, use ..., as for other recursive structures. Patch by Ben North.

bpo-32028 [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.

bpo-32137 [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.

Library

bpo-33064 [https://bugs.python.org/issue?@action=redirect&bpo=33064]: lib2to3 now properly supports trailing commas after *args and **kwargs in function signatures.

bpo-31804 [https://bugs.python.org/issue?@action=redirect&bpo=31804]: Avoid failing in multiprocessing.Process if the standard streams are closed or None at exit.

bpo-33037 [https://bugs.python.org/issue?@action=redirect&bpo=33037]: Skip sending/receiving data after SSL transport closing.

bpo-30353 [https://bugs.python.org/issue?@action=redirect&bpo=30353]: Fix ctypes pass-by-value for structs on 64-bit Cygwin/MinGW.

bpo-33009 [https://bugs.python.org/issue?@action=redirect&bpo=33009]: Fix inspect.signature() for single-parameter partialmethods.

bpo-32969 [https://bugs.python.org/issue?@action=redirect&bpo=32969]: Expose several missing constants in zlib and fix corresponding documentation.

bpo-32713 [https://bugs.python.org/issue?@action=redirect&bpo=32713]: Fixed tarfile.itn handling of out-of-bounds float values. Patch by Joffrey Fuhrer.

bpo-30622 [https://bugs.python.org/issue?@action=redirect&bpo=30622]: The ssl module now detects missing NPN support in LibreSSL.

bpo-32922 [https://bugs.python.org/issue?@action=redirect&bpo=32922]: dbm.open() now encodes filename with the filesystem encoding rather than default encoding.

bpo-32859 [https://bugs.python.org/issue?@action=redirect&bpo=32859]: In os.dup2, don't check every call whether the dup3 syscall exists or not.

bpo-21060 [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".

bpo-32857 [https://bugs.python.org/issue?@action=redirect&bpo=32857]: In tkinter, after_cancel(None) now raises a ValueError instead of canceling the first scheduled function. Patch by Cheryl Sabella.

bpo-32852 [https://bugs.python.org/issue?@action=redirect&bpo=32852]: Make sure sys.argv remains as a list when running trace.

bpo-32841 [https://bugs.python.org/issue?@action=redirect&bpo=32841]: Fixed asyncio.Condition issue which silently ignored cancellation after notifying and cancelling a conditional lock. Patch by Bar Harel.

bpo-31787 [https://bugs.python.org/issue?@action=redirect&bpo=31787]: Fixed refleaks of __init__() methods in various modules. (Contributed by Oren Milman)

bpo-30157 [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.

bpo-32394 [https://bugs.python.org/issue?@action=redirect&bpo=32394]: socket: Remove TCP_FASTOPEN, TCP_KEEPCNT flags on older version Windows during run-time.

bpo-32777 [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.

bpo-32647 [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.

bpo-32734 [https://bugs.python.org/issue?@action=redirect&bpo=32734]: Fixed asyncio.Lock() safety issue which allowed acquiring and locking the same lock multiple times, without it being free. Patch by Bar Harel.

bpo-32727 [https://bugs.python.org/issue?@action=redirect&bpo=32727]: Do not include name field in SMTP envelope from address. Patch by Stéphane Wirtel

bpo-27931 [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.

bpo-32304 [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.

bpo-32502 [https://bugs.python.org/issue?@action=redirect&bpo=32502]: uuid.uuid1 no longer raises an exception if a 64-bit hardware address is encountered.

bpo-31848 [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.

bpo-32555 [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.

bpo-32521 [https://bugs.python.org/issue?@action=redirect&bpo=32521]: The nis module is now compatible with new libnsl and headers location.

bpo-32473 [https://bugs.python.org/issue?@action=redirect&bpo=32473]: Improve ABCMeta._dump_registry() output readability

bpo-32521 [https://bugs.python.org/issue?@action=redirect&bpo=32521]: glibc has removed Sun RPC. Use replacement libtirpc headers and library in nis module.

bpo-32228 [https://bugs.python.org/issue?@action=redirect&bpo=32228]: Ensure that truncate() preserves the file position (as reported by tell()) after writes longer than the buffer size.

bpo-26133 [https://bugs.python.org/issue?@action=redirect&bpo=26133]: Don't unsubscribe signals in asyncio UNIX event loop on interpreter shutdown.

bpo-32185 [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.

bpo-32323 [https://bugs.python.org/issue?@action=redirect&bpo=32323]: urllib.parse.urlsplit() does not convert zone-id (scope) to lower case for scoped IPv6 addresses in hostnames now.

bpo-32302 [https://bugs.python.org/issue?@action=redirect&bpo=32302]: Fix bdist_wininst of distutils for CRT v142: it binary compatible with CRT v140.

bpo-32255 [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.

bpo-32277 [https://bugs.python.org/issue?@action=redirect&bpo=32277]: Raise NotImplementedError instead of SystemError on platforms where chmod(..., follow_symlinks=False) is not supported. Patch by Anthony Sottile.

bpo-32199 [https://bugs.python.org/issue?@action=redirect&bpo=32199]: The getnode() ip getter now uses 'ip link' instead of 'ip link list'.

bpo-27456 [https://bugs.python.org/issue?@action=redirect&bpo=27456]: Ensure TCP_NODELAY is set on Linux. Tests by Victor Stinner.

bpo-31900 [https://bugs.python.org/issue?@action=redirect&bpo=31900]: The locale.localeconv() function now sets temporarily the LC_CTYPE locale to the LC_NUMERIC locale to decode decimal_point and thousands_sep byte strings if they are non-ASCII or longer than 1 byte, and the LC_NUMERIC locale is different than the LC_CTYPE locale. This temporary change affects other threads. Same change for the str.format() method when formatting a number (int, float, float and subclasses) with the n type (ex: '{:n}'.format(1234)).

bpo-31802 [https://bugs.python.org/issue?@action=redirect&bpo=31802]: Importing native path module (posixpath, ntpath) now works even if the os module still is not imported.

Documentation

bpo-17232 [https://bugs.python.org/issue?@action=redirect&bpo=17232]: Clarify docs for -O and -OO. Patch by Terry Reedy.

bpo-32800 [https://bugs.python.org/issue?@action=redirect&bpo=32800]: Update link to w3c doc for xml default namespaces.

bpo-8722 [https://bugs.python.org/issue?@action=redirect&bpo=8722]: Document __getattr__() behavior when property get() method raises AttributeError.

bpo-32614 [https://bugs.python.org/issue?@action=redirect&bpo=32614]: Modify RE examples in documentation to use raw strings to prevent DeprecationWarning and add text to REGEX HOWTO to highlight the deprecation.

bpo-31972 [https://bugs.python.org/issue?@action=redirect&bpo=31972]: Improve docstrings for pathlib.PurePath subclasses.

bpo-17799 [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.

Tests

bpo-32517 [https://bugs.python.org/issue?@action=redirect&bpo=32517]: Fix failing test_asyncio on macOS 10.12.2+ due to transport of KqueueSelector loop was not being closed.

bpo-32721 [https://bugs.python.org/issue?@action=redirect&bpo=32721]: Fix test_hashlib to not fail if the _md5 module is not built.

bpo-32252 [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.

bpo-31518 [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.

Build

bpo-32635 [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.

Windows

bpo-33016 [https://bugs.python.org/issue?@action=redirect&bpo=33016]: Fix potential use of uninitialized memory in nt._getfinalpathname

bpo-32903 [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.

bpo-31966 [https://bugs.python.org/issue?@action=redirect&bpo=31966]: Fixed WindowsConsoleIO.write() for writing empty data.

bpo-32409 [https://bugs.python.org/issue?@action=redirect&bpo=32409]: Ensures activate.bat can handle Unicode contents.

bpo-32457 [https://bugs.python.org/issue?@action=redirect&bpo=32457]: Improves handling of denormalized executable path when launching Python.

bpo-32370 [https://bugs.python.org/issue?@action=redirect&bpo=32370]: Use the correct encoding for ipconfig output in the uuid module. Patch by Segev Finer.

bpo-29248 [https://bugs.python.org/issue?@action=redirect&bpo=29248]: Fix os.readlink() on Windows, which was mistakenly treating the PrintNameOffset field of the reparse data buffer as a number of characters instead of bytes. Patch by Craig Holmquist and SSE4.

bpo-32588 [https://bugs.python.org/issue?@action=redirect&bpo=32588]: Create standalone _distutils_findvs module.

macOS

bpo-32726 [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.

IDLE

bpo-32984 [https://bugs.python.org/issue?@action=redirect&bpo=32984]: Set __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, -s runs a file named in environmental variable IDLESTARTUP or PYTHONSTARTUP; -r file runs file. Python sets __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 -n option.

bpo-32940 [https://bugs.python.org/issue?@action=redirect&bpo=32940]: Simplify and rename StringTranslatePseudoMapping in pyparse.

bpo-32916 [https://bugs.python.org/issue?@action=redirect&bpo=32916]: Change str to code in pyparse.

bpo-32905 [https://bugs.python.org/issue?@action=redirect&bpo=32905]: Remove unused code in pyparse module.

bpo-32874 [https://bugs.python.org/issue?@action=redirect&bpo=32874]: Add tests for pyparse.

bpo-32837 [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.

bpo-32826 [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.

bpo-32765 [https://bugs.python.org/issue?@action=redirect&bpo=32765]: Update configdialog General tab docstring to add new widgets to the widget list.

Tools/Demos

bpo-24960 [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.

bpo-32222 [https://bugs.python.org/issue?@action=redirect&bpo=32222]: Fix pygettext not extracting docstrings for functions with type annotated arguments. Patch by Toby Harradine.

C API

bpo-29084 [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.

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.

Python 3.6.4 release candidate 1

Release date: 2017-12-05

Core and Builtins

bpo-32176 [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.

bpo-31949 [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 2**31 traceback items on Windows. Fixed output errors handling.

bpo-30696 [https://bugs.python.org/issue?@action=redirect&bpo=30696]: Fix the interactive interpreter looping endlessly when no memory.

bpo-20047 [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.

bpo-31852 [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.

bpo-21720 [https://bugs.python.org/issue?@action=redirect&bpo=21720]: BytesWarning no longer emitted when the fromlist argument of __import__() or the __all__ attribute of the module contain bytes instances.

bpo-31825 [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.

bpo-28603 [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.

bpo-31786 [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.

bpo-31642 [https://bugs.python.org/issue?@action=redirect&bpo=31642]: Restored blocking "from package import module" by setting sys.modules["package.module"] to None.

bpo-31626 [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.

bpo-31619 [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.

bpo-31592 [https://bugs.python.org/issue?@action=redirect&bpo=31592]: Fixed an assertion failure in Python parser in case of a bad unicodedata.normalize(). Patch by Oren Milman.

bpo-31588 [https://bugs.python.org/issue?@action=redirect&bpo=31588]: Raise a TypeError with a helpful error message when class creation fails due to a metaclass with a bad __prepare__() method. Patch by Oren Milman.

bpo-31566 [https://bugs.python.org/issue?@action=redirect&bpo=31566]: Fix an assertion failure in _warnings.warn() in case of a bad __name__ global. Patch by Oren Milman.

bpo-31505 [https://bugs.python.org/issue?@action=redirect&bpo=31505]: Fix an assertion failure in json, in case _json.make_encoder() received a bad encoder() argument. Patch by Oren Milman.

bpo-31492 [https://bugs.python.org/issue?@action=redirect&bpo=31492]: Fix assertion failures in case of failing to import from a module with a bad __name__ attribute, and in case of failing to access an attribute of such a module. Patch by Oren Milman.

bpo-31490 [https://bugs.python.org/issue?@action=redirect&bpo=31490]: Fix an assertion failure in ctypes class definition, in case the class has an attribute whose name is specified in _anonymous_ but not in _fields_. Patch by Oren Milman.

bpo-31478 [https://bugs.python.org/issue?@action=redirect&bpo=31478]: Fix an assertion failure in _random.Random.seed() in case the argument has a bad __abs__() method. Patch by Oren Milman.

bpo-31315 [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.

bpo-31311 [https://bugs.python.org/issue?@action=redirect&bpo=31311]: Fix a crash in the __setstate__() method of ctypes._CData, in case of a bad __dict__. Patch by Oren Milman.

bpo-31293 [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.

bpo-31285 [https://bugs.python.org/issue?@action=redirect&bpo=31285]: Fix an assertion failure in warnings.warn_explicit, when the return value of the received loader's get_source() has a bad splitlines() method. Patch by Oren Milman.

bpo-30817 [https://bugs.python.org/issue?@action=redirect&bpo=30817]: PyErr_PrintEx() clears now the ignored exception that may be raised by _PySys_SetObjectId(), for example when no memory.

Library

bpo-28556 [https://bugs.python.org/issue?@action=redirect&bpo=28556]: Two minor fixes for typing module: allow shallow copying instances of generic classes, improve interaction of __init_subclass__ with generics. Original PRs by Ivan Levkivskyi.

bpo-27240 [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 [https://bugs.python.org/issue?@action=redirect&bpo=30788], bpo-31831 [https://bugs.python.org/issue?@action=redirect&bpo=31831], and bpo-32182 [https://bugs.python.org/issue?@action=redirect&bpo=32182]. In particular, RFC2231 folding is now done correctly.

bpo-32186 [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.

bpo-12239 [https://bugs.python.org/issue?@action=redirect&bpo=12239]: Make msilib.SummaryInformation.GetProperty() return None when the value of property is VT_EMPTY. Initial patch by Mark Mc Mahon.

bpo-31325 [https://bugs.python.org/issue?@action=redirect&bpo=31325]: Fix wrong usage of collections.namedtuple() in the RobotFileParser.parse() method. Initial patch by Robin Wellner.

bpo-12382 [https://bugs.python.org/issue?@action=redirect&bpo=12382]: msilib.OpenDatabase() now raises a better exception message when it couldn't open or create an MSI file. Initial patch by William Tisäter.

bpo-32110 [https://bugs.python.org/issue?@action=redirect&bpo=32110]: codecs.StreamReader.read(n) now returns not more than n characters/bytes for non-negative n. This makes it compatible with read() methods of other file-like objects.

bpo-32072 [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.

bpo-32034 [https://bugs.python.org/issue?@action=redirect&bpo=32034]: Make asyncio.IncompleteReadError and LimitOverrunError pickleable.

bpo-32015 [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.

bpo-32011 [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.

bpo-31970 [https://bugs.python.org/issue?@action=redirect&bpo=31970]: Reduce performance overhead of asyncio debug mode.

bpo-9678 [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.

bpo-30057 [https://bugs.python.org/issue?@action=redirect&bpo=30057]: Fix potential missed signal in signal.signal().

bpo-31933 [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.

bpo-31927 [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.

bpo-27666 [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.

bpo-31897 [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.

bpo-25720 [https://bugs.python.org/issue?@action=redirect&bpo=25720]: Fix the method for checking pad state of curses WINDOW. Patch by Masayuki Yamamoto.

bpo-31893 [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.

bpo-31891 [https://bugs.python.org/issue?@action=redirect&bpo=31891]: Fixed building the curses module on NetBSD.

bpo-28416 [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.

bpo-28326 [https://bugs.python.org/issue?@action=redirect&bpo=28326]: Fix multiprocessing.Process when stdout and/or stderr is closed or None.

bpo-31457 [https://bugs.python.org/issue?@action=redirect&bpo=31457]: If nested log adapters are used, the inner process() methods are no longer omitted.

bpo-31457 [https://bugs.python.org/issue?@action=redirect&bpo=31457]: The manager property on LoggerAdapter objects is now properly settable.

bpo-31806 [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.

bpo-28603 [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.

bpo-30058 [https://bugs.python.org/issue?@action=redirect&bpo=30058]: Fixed buffer overflow in select.kqueue.control().

bpo-31770 [https://bugs.python.org/issue?@action=redirect&bpo=31770]: Prevent a crash when calling the __init__() method of a sqlite3.Cursor object more than once. Patch by Oren Milman.

bpo-31672 [https://bugs.python.org/issue?@action=redirect&bpo=31672]: idpattern in string.Template matched some non-ASCII characters. Now it uses -i regular expression local flag to avoid non-ASCII characters.

bpo-31764 [https://bugs.python.org/issue?@action=redirect&bpo=31764]: Prevent a crash in sqlite3.Cursor.close() in case the Cursor object is uninitialized. Patch by Oren Milman.

bpo-31752 [https://bugs.python.org/issue?@action=redirect&bpo=31752]: Fix possible crash in timedelta constructor called with custom integers.

bpo-31701 [https://bugs.python.org/issue?@action=redirect&bpo=31701]: On Windows, faulthandler.enable() now ignores MSC and COM exceptions.

bpo-31728 [https://bugs.python.org/issue?@action=redirect&bpo=31728]: Prevent crashes in _elementtree due to unsafe cleanup of Element.text and Element.tail. Patch by Oren Milman.

bpo-31620 [https://bugs.python.org/issue?@action=redirect&bpo=31620]: an empty asyncio.Queue now doesn't leak memory when queue.get pollers timeout

bpo-31632 [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.

bpo-31675 [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.

bpo-31673 [https://bugs.python.org/issue?@action=redirect&bpo=31673]: Fixed typo in the name of Tkinter's method adderrorinfo().

bpo-30806 [https://bugs.python.org/issue?@action=redirect&bpo=30806]: Fix the string representation of a netrc object.

bpo-15037 [https://bugs.python.org/issue?@action=redirect&bpo=15037]: Added a workaround for getkey() in curses for ncurses 5.7 and earlier.

bpo-25351 [https://bugs.python.org/issue?@action=redirect&bpo=25351]: Avoid venv activate failures with undefined variables

bpo-25532 [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.

bpo-30347 [https://bugs.python.org/issue?@action=redirect&bpo=30347]: Stop crashes when concurrently iterate over itertools.groupby() iterators.

bpo-31516 [https://bugs.python.org/issue?@action=redirect&bpo=31516]: threading.current_thread() should not return a dummy thread at shutdown.

bpo-31351 [https://bugs.python.org/issue?@action=redirect&bpo=31351]: python -m ensurepip now exits with non-zero exit code if pip bootstrapping has failed.

bpo-31482 [https://bugs.python.org/issue?@action=redirect&bpo=31482]: random.seed() now works with bytes in version=1

bpo-31334 [https://bugs.python.org/issue?@action=redirect&bpo=31334]: Fix poll.poll([timeout]) in the select module for arbitrary negative timeouts on all OSes where it can only be a non-negative integer or -1. Patch by Riccardo Coccioli.

bpo-31310 [https://bugs.python.org/issue?@action=redirect&bpo=31310]: multiprocessing's semaphore tracker should be launched again if crashed.

bpo-31308 [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.

Documentation

bpo-32105 [https://bugs.python.org/issue?@action=redirect&bpo=32105]: Added asyncio.BaseEventLoop.connect_accepted_socket versionadded marker.

bpo-31537 [https://bugs.python.org/issue?@action=redirect&bpo=31537]: Fix incorrect usage of get_history_length in readline documentation example code. Patch by Brad Smith.

bpo-30085 [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.

Tests

bpo-31380 [https://bugs.python.org/issue?@action=redirect&bpo=31380]: Skip test_httpservers test_undecodable_file on macOS: fails on APFS.

bpo-31705 [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.

bpo-31174 [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.

bpo-30695 [https://bugs.python.org/issue?@action=redirect&bpo=30695]: Add the set_nomemory(start, stop) and remove_mem_hooks() functions to the _testcapi module.

Build

bpo-32059 [https://bugs.python.org/issue?@action=redirect&bpo=32059]: detect_modules() in setup.py now also searches the sysroot paths when cross-compiling.

bpo-31957 [https://bugs.python.org/issue?@action=redirect&bpo=31957]: Fixes Windows SDK version detection when building for Windows.

bpo-31609 [https://bugs.python.org/issue?@action=redirect&bpo=31609]: Fixes quotes in PCbuild/clean.bat

bpo-31934 [https://bugs.python.org/issue?@action=redirect&bpo=31934]: Abort the build when building out of a not clean source tree.

bpo-31926 [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.

bpo-28791 [https://bugs.python.org/issue?@action=redirect&bpo=28791]: Update Windows builds to use SQLite 3.21.0.

bpo-28791 [https://bugs.python.org/issue?@action=redirect&bpo=28791]: Update OS X installer to use SQLite 3.21.0.

bpo-22140 [https://bugs.python.org/issue?@action=redirect&bpo=22140]: Prevent double substitution of prefix in python-config.sh.

bpo-31536 [https://bugs.python.org/issue?@action=redirect&bpo=31536]: Avoid wholesale rebuild after make regen-all if nothing changed.

Windows

bpo-1102 [https://bugs.python.org/issue?@action=redirect&bpo=1102]: Return None when View.Fetch() returns ERROR_NO_MORE_ITEMS instead of raising MSIError. Initial patch by Anthony Tuininga.

bpo-31944 [https://bugs.python.org/issue?@action=redirect&bpo=31944]: Fixes Modify button in Apps and Features dialog.

macOS

bpo-31392 [https://bugs.python.org/issue?@action=redirect&bpo=31392]: Update macOS installer to use OpenSSL 1.0.2m

IDLE

bpo-32207 [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.

bpo-32164 [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.

bpo-32100 [https://bugs.python.org/issue?@action=redirect&bpo=32100]: IDLE: Fix old and new bugs in pathbrowser; improve tests. Patch mostly by Cheryl Sabella.

bpo-31858 [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.

bpo-31860 [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

bpo-31836 [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.

bpo-28603 [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.

bpo-13802 [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.

bpo-31460 [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.

bpo-31649 [https://bugs.python.org/issue?@action=redirect&bpo=31649]: IDLE - Make _htest, _utest parameters keyword only.

bpo-31559 [https://bugs.python.org/issue?@action=redirect&bpo=31559]: Remove test order dependence in idle_test.test_browser.

bpo-31459 [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.

bpo-31500 [https://bugs.python.org/issue?@action=redirect&bpo=31500]: Default fonts now are scaled on HiDPI displays.

bpo-1612262 [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.

Tools/Demos

bpo-30722 [https://bugs.python.org/issue?@action=redirect&bpo=30722]: Make redemo work with Python 3.6 and newer versions. Also, remove the LOCALE option since it doesn't work with string patterns in Python 3. Patch by Christoph Sarnowski.

C API

bpo-20891 [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.

bpo-31532 [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()

bpo-30697 [https://bugs.python.org/issue?@action=redirect&bpo=30697]: The PyExc_RecursionErrorInst singleton is removed and 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 [https://bugs.python.org/issue?@action=redirect&bpo=22898].

Python 3.6.3 final

Release date: 2017-10-03

Library

bpo-31641 [https://bugs.python.org/issue?@action=redirect&bpo=31641]: Re-allow arbitrary iterables in concurrent.futures.as_completed(). Fixes regression in 3.6.3rc1.

Build

bpo-31662 [https://bugs.python.org/issue?@action=redirect&bpo=31662]: Fix typos in Windows uploadrelease.bat script. Fix Windows Doc build issues in Doc/make.bat.

bpo-31423 [https://bugs.python.org/issue?@action=redirect&bpo=31423]: Fix building the PDF documentation with newer versions of Sphinx.

Python 3.6.3 release candidate 1

Release date: 2017-09-18

Security

bpo-29781 [https://bugs.python.org/issue?@action=redirect&bpo=29781]: SSLObject.version() now correctly returns None when handshake over BIO has not been performed yet.

bpo-30947 [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.

Core and Builtins

bpo-31471 [https://bugs.python.org/issue?@action=redirect&bpo=31471]: Fix an assertion failure in subprocess.Popen() on Windows, in case the env argument has a bad keys() method. Patch by Oren Milman.

bpo-31418 [https://bugs.python.org/issue?@action=redirect&bpo=31418]: Fix an assertion failure in PyErr_WriteUnraisable() in case of an exception with a bad __module__ attribute. Patch by Oren Milman.

bpo-31416 [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.

bpo-31411 [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.

bpo-31373 [https://bugs.python.org/issue?@action=redirect&bpo=31373]: Fix several possible instances of undefined behavior due to floating-point demotions.

bpo-30465 [https://bugs.python.org/issue?@action=redirect&bpo=30465]: Location information (lineno and 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).

bpo-31343 [https://bugs.python.org/issue?@action=redirect&bpo=31343]: Include sys/sysmacros.h for major(), minor(), and makedev(). GNU C libray plans to remove the functions from sys/types.h.

bpo-31291 [https://bugs.python.org/issue?@action=redirect&bpo=31291]: Fix an assertion failure in zipimport.zipimporter.get_data on Windows, when the return value of pathname.replace('/','\\') isn't a string. Patch by Oren Milman.

bpo-31271 [https://bugs.python.org/issue?@action=redirect&bpo=31271]: Fix an assertion failure in the write() method of io.TextIOWrapper, when the encoder doesn't return a bytes object. Patch by Oren Milman.

bpo-31243 [https://bugs.python.org/issue?@action=redirect&bpo=31243]: Fix a crash in some methods of io.TextIOWrapper, when the decoder's state is invalid. Patch by Oren Milman.

bpo-30721 [https://bugs.python.org/issue?@action=redirect&bpo=30721]: print now shows correct usage hint for using Python 2 redirection syntax. Patch by Sanyam Khurana.

bpo-31070 [https://bugs.python.org/issue?@action=redirect&bpo=31070]: Fix a race condition in importlib _get_module_lock().

bpo-31095 [https://bugs.python.org/issue?@action=redirect&bpo=31095]: Fix potential crash during GC caused by tp_dealloc which doesn't call PyObject_GC_UnTrack().

bpo-31071 [https://bugs.python.org/issue?@action=redirect&bpo=31071]: Avoid masking original TypeError in call with * unpacking when other arguments are passed.

bpo-30978 [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.

bpo-30808 [https://bugs.python.org/issue?@action=redirect&bpo=30808]: Use _Py_atomic API for concurrency-sensitive signal state.

bpo-30876 [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.

bpo-30703 [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).

bpo-30765 [https://bugs.python.org/issue?@action=redirect&bpo=30765]: Avoid blocking in pthread_mutex_lock() when PyThread_acquire_lock() is asked not to block.

bpo-31161 [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.

bpo-30814 [https://bugs.python.org/issue?@action=redirect&bpo=30814]: Fixed a race condition when import a submodule from a package.

bpo-30597 [https://bugs.python.org/issue?@action=redirect&bpo=30597]: print now shows expected input in custom error message when used as a Python 2 statement. Patch by Sanyam Khurana.

Library

bpo-31499 [https://bugs.python.org/issue?@action=redirect&bpo=31499]: xml.etree: Fix a crash when a parser is part of a reference cycle.

bpo-28556 [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 globalns was specified by the caller).

bpo-28556 [https://bugs.python.org/issue?@action=redirect&bpo=28556]: Speed improvements to the typing module. Original PRs by Ivan Levkivskyi and Mitar.

bpo-31544 [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().

bpo-31234 [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.

bpo-31457 [https://bugs.python.org/issue?@action=redirect&bpo=31457]: LoggerAdapter objects can now be nested.

bpo-31400 [https://bugs.python.org/issue?@action=redirect&bpo=31400]: Improves SSL error handling to avoid losing error numbers.

bpo-28958 [https://bugs.python.org/issue?@action=redirect&bpo=28958]: ssl.SSLContext() now uses OpenSSL error information when a context cannot be instantiated.

bpo-27340 [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.

bpo-31178 [https://bugs.python.org/issue?@action=redirect&bpo=31178]: Fix string concatenation bug in rare error path in the subprocess module

bpo-31350 [https://bugs.python.org/issue?@action=redirect&bpo=31350]: Micro-optimize asyncio._get_running_loop() to become up to 10% faster.

bpo-31170 [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): https://github.com/libexpat/libexpat/issues/115

bpo-29136 [https://bugs.python.org/issue?@action=redirect&bpo=29136]: Add TLS 1.3 cipher suites and OP_NO_TLSv1_3.

bpo-29212 [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".

bpo-9146 [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.

bpo-27144 [https://bugs.python.org/issue?@action=redirect&bpo=27144]: The map() and as_completed() iterators in concurrent.futures now avoid keeping a reference to yielded objects.

bpo-10746 [https://bugs.python.org/issue?@action=redirect&bpo=10746]: Fix ctypes producing wrong PEP 3118 [https://peps.python.org/pep-3118/] type codes for integer types.

bpo-22536 [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.

bpo-31249 [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.

bpo-31247 [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.

bpo-30102 [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.

bpo-31185 [https://bugs.python.org/issue?@action=redirect&bpo=31185]: Fixed miscellaneous errors in asyncio speedup module.

bpo-31135 [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.

bpo-31107 [https://bugs.python.org/issue?@action=redirect&bpo=31107]: Fix copyreg._slotnames() mangled attribute calculation for classes whose name begins with an underscore. Patch by Shane Harvey.

bpo-31061 [https://bugs.python.org/issue?@action=redirect&bpo=31061]: Fixed a crash when using asyncio and threads.

bpo-30502 [https://bugs.python.org/issue?@action=redirect&bpo=30502]: Fix handling of long oids in ssl. Based on patch by Christian Heimes.

bpo-30119 [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.

bpo-30595 [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.

bpo-29403 [https://bugs.python.org/issue?@action=redirect&bpo=29403]: Fix unittest.mock's autospec to not fail on method-bound builtin functions. Patch by Aaron Gallagher.

bpo-30961 [https://bugs.python.org/issue?@action=redirect&bpo=30961]: Fix decrementing a borrowed reference in tracemalloc.

bpo-25684 [https://bugs.python.org/issue?@action=redirect&bpo=25684]: Change ttk.OptionMenu radiobuttons to be unique across instances of OptionMenu.

bpo-30886 [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.

bpo-29854 [https://bugs.python.org/issue?@action=redirect&bpo=29854]: Fix segfault in readline when using readline's history-size option. Patch by Nir Soffer.

bpo-30319 [https://bugs.python.org/issue?@action=redirect&bpo=30319]: socket.close() now ignores ECONNRESET error.

bpo-30828 [https://bugs.python.org/issue?@action=redirect&bpo=30828]: Fix out of bounds write in asyncio.CFuture.remove_done_callback().

bpo-30807 [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.

bpo-30441 [https://bugs.python.org/issue?@action=redirect&bpo=30441]: Fix bug when modifying os.environ while iterating over it

bpo-30532 [https://bugs.python.org/issue?@action=redirect&bpo=30532]: Fix email header value parser dropping folding white space in certain cases.

bpo-30879 [https://bugs.python.org/issue?@action=redirect&bpo=30879]: os.listdir() and os.scandir() now emit bytes names when called with bytes-like argument.

bpo-30746 [https://bugs.python.org/issue?@action=redirect&bpo=30746]: Prohibited the '=' character in environment variable names in os.putenv() and os.spawn*().

bpo-29755 [https://bugs.python.org/issue?@action=redirect&bpo=29755]: Fixed the lgettext() family of functions in the gettext module. They now always return bytes.

Documentation

bpo-31294 [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.

bpo-21649 [https://bugs.python.org/issue?@action=redirect&bpo=21649]: Add RFC 7525 and Mozilla server side TLS links to SSL documentation.

bpo-30803 [https://bugs.python.org/issue?@action=redirect&bpo=30803]: Clarify doc on truth value testing. Original patch by Peter Thomassen.

Tests

bpo-31320 [https://bugs.python.org/issue?@action=redirect&bpo=31320]: Silence traceback in test_ssl

bpo-25674 [https://bugs.python.org/issue?@action=redirect&bpo=25674]: Remove sha256.tbs-internet.com ssl test

bpo-30715 [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.

bpo-30822 [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.

Build

bpo-30854 [https://bugs.python.org/issue?@action=redirect&bpo=30854]: Fix compile error when compiling --without-threads. Patch by Masayuki Yamamoto.

Windows

bpo-30389 [https://bugs.python.org/issue?@action=redirect&bpo=30389]: Adds detection of Visual Studio 2017 to distutils on Windows.

bpo-31340 [https://bugs.python.org/issue?@action=redirect&bpo=31340]: Change to building with MSVC v141 (included with Visual Studio 2017)

bpo-30581 [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.

bpo-30731 [https://bugs.python.org/issue?@action=redirect&bpo=30731]: Add a missing xmlns to python.manifest so that it matches the schema.

IDLE

bpo-31493 [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.

bpo-31488 [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.

bpo-31477 [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.

bpo-31480 [https://bugs.python.org/issue?@action=redirect&bpo=31480]: IDLE - make tests pass with zzdummy extension disabled by default.

bpo-31421 [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.

bpo-31414 [https://bugs.python.org/issue?@action=redirect&bpo=31414]: IDLE -- fix tk entry box tests by deleting first. Adding to an int entry is not the same as deleting and inserting because int('') will fail.

bpo-31051 [https://bugs.python.org/issue?@action=redirect&bpo=31051]: Rearrange IDLE configdialog GenPage into Window, Editor, and Help sections.

bpo-30617 [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.

bpo-31287 [https://bugs.python.org/issue?@action=redirect&bpo=31287]: IDLE - Do not modify tkinter.message in test_configdialog.

bpo-27099 [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.

bpo-31206 [https://bugs.python.org/issue?@action=redirect&bpo=31206]: IDLE: Factor HighPage(Frame) class from ConfigDialog. Patch by Cheryl Sabella.

bpo-31001 [https://bugs.python.org/issue?@action=redirect&bpo=31001]: Add tests for configdialog highlight tab. Patch by Cheryl Sabella.

bpo-31205 [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.

bpo-31130 [https://bugs.python.org/issue?@action=redirect&bpo=31130]: IDLE -- stop leaks in test_configdialog. Initial patch by Victor Stinner.

bpo-31002 [https://bugs.python.org/issue?@action=redirect&bpo=31002]: Add tests for configdialog keys tab. Patch by Cheryl Sabella.

bpo-19903 [https://bugs.python.org/issue?@action=redirect&bpo=19903]: IDLE: Calltips use inspect.signature instead of inspect.getfullargspec. This improves calltips for builtins converted to use Argument Clinic. Patch by Louie Lu.

bpo-31083 [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.

bpo-31050 [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.

bpo-31004 [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.

bpo-30781 [https://bugs.python.org/issue?@action=redirect&bpo=30781]: IDLE - Use ttk widgets in ConfigDialog. Patches by Terry Jan Reedy and Cheryl Sabella.

bpo-31060 [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.

bpo-30853 [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%.

bpo-31003 [https://bugs.python.org/issue?@action=redirect&bpo=31003]: IDLE: Add more tests for General tab.

bpo-30993 [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.

bpo-30981 [https://bugs.python.org/issue?@action=redirect&bpo=30981]: IDLE -- Add more configdialog font page tests.

bpo-28523 [https://bugs.python.org/issue?@action=redirect&bpo=28523]: IDLE: replace 'colour' with 'color' in configdialog.

bpo-30917 [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.

bpo-30934 [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.

bpo-30913 [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.

bpo-30899 [https://bugs.python.org/issue?@action=redirect&bpo=30899]: IDLE: Add tests for ConfigParser subclasses in config. Patch by Louie Lu.

bpo-30881 [https://bugs.python.org/issue?@action=redirect&bpo=30881]: IDLE: Add docstrings to browser.py. Patch by Cheryl Sabella.

bpo-30851 [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.

bpo-30870 [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.

bpo-8231 [https://bugs.python.org/issue?@action=redirect&bpo=8231]: IDLE: call config.IdleConf.GetUserCfgDir only once.

bpo-30779 [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.

bpo-30777 [https://bugs.python.org/issue?@action=redirect&bpo=30777]: IDLE: configdialog - Add docstrings and fix comments. Patch by Cheryl Sabella.

bpo-30495 [https://bugs.python.org/issue?@action=redirect&bpo=30495]: IDLE: Improve textview with docstrings, PEP8 names, and more tests. Patch by Cheryl Sabella.

bpo-30723 [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.

bpo-30674 [https://bugs.python.org/issue?@action=redirect&bpo=30674]: IDLE: add docstrings to grep module. Patch by Cheryl Sabella

bpo-21519 [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.

bpo-29910 [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 return 'break' for this and other potential conflicts between IDLE and default key bindings.

bpo-30728 [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 import * with specific imports. Patches by Cheryl Sabella.

bpo-6739 [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.

Tools/Demos

bpo-30983 [https://bugs.python.org/issue?@action=redirect&bpo=30983]: gdb integration commands (py-bt, etc.) work on optimized shared builds now, too. PEP 523 [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.

Python 3.6.2 final

Release date: 2017-07-17

No changes since release candidate 2

Python 3.6.2 release candidate 2

Release date: 2017-07-07

Security

bpo-30730 [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.

bpo-30694 [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: CVE-2017-9233 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-9233] (External entity infinite loop DoS), CVE-2016-9063 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-9063] (Integer overflow, re-fix), CVE-2016-0718 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-0718] (Fix regression bugs from 2.2.0's fix to CVE-2016-0718 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-0718]) and CVE-2012-0876 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2012-0876] (Counter hash flooding with SipHash). Note: the CVE-2016-5300 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=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 XML_SetHashSalt().

bpo-30500 [https://bugs.python.org/issue?@action=redirect&bpo=30500]: Fix urllib.parse.splithost() to correctly parse fragments. For example, splithost('//127.0.0.1#@evil.com/') now correctly returns the 127.0.0.1 host, instead of treating @evil.com as the host in an authentication (login@host).

Python 3.6.2 release candidate 1

Release date: 2017-06-17

Security

bpo-29591 [https://bugs.python.org/issue?@action=redirect&bpo=29591]: Update expat copy from 2.1.1 to 2.2.0 to get fixes of CVE-2016-0718 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-0718] and CVE-2016-4472 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-4472]. See https://sourceforge.net/p/expat/bugs/537/ for more information.

Core and Builtins

bpo-30682 [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'").

bpo-30604 [https://bugs.python.org/issue?@action=redirect&bpo=30604]: Move co_extra_freefuncs to not be per-thread to avoid crashes

bpo-29104 [https://bugs.python.org/issue?@action=redirect&bpo=29104]: Fixed parsing backslashes in f-strings.

bpo-27945 [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.

bpo-25794 [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.

bpo-30039 [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.

bpo-12414 [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.

bpo-29949 [https://bugs.python.org/issue?@action=redirect&bpo=29949]: Fix memory usage regression of set and frozenset object.

bpo-29935 [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.

bpo-29859 [https://bugs.python.org/issue?@action=redirect&bpo=29859]: Show correct error messages when any of the pthread_* calls in thread_pthread.h fails.

bpo-28876 [https://bugs.python.org/issue?@action=redirect&bpo=28876]: bool(range) works even if len(range) raises OverflowError.

bpo-29600 [https://bugs.python.org/issue?@action=redirect&bpo=29600]: Fix wrapping coroutine return values in StopIteration.

bpo-28856 [https://bugs.python.org/issue?@action=redirect&bpo=28856]: Fix an oversight that %b format for bytes should support objects follow the buffer protocol.

bpo-29714 [https://bugs.python.org/issue?@action=redirect&bpo=29714]: Fix a regression that bytes format may fail when containing zero bytes inside.

bpo-29478 [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.

Library

bpo-30616 [https://bugs.python.org/issue?@action=redirect&bpo=30616]: Functional API of enum allows to create empty enums. Patched by Donghee Na

bpo-30038 [https://bugs.python.org/issue?@action=redirect&bpo=30038]: Fix race condition between signal delivery and wakeup file descriptor. Patch by Nathaniel Smith.

bpo-23894 [https://bugs.python.org/issue?@action=redirect&bpo=23894]: lib2to3 now recognizes rb'...' and f'...' strings.

bpo-23890 [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.

bpo-30149 [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.

bpo-30645 [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.

bpo-29931 [https://bugs.python.org/issue?@action=redirect&bpo=29931]: Fixed comparison check for ipaddress.ip_interface objects. Patch by Sanjay Sundaresan.

bpo-30605 [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.

bpo-24484 [https://bugs.python.org/issue?@action=redirect&bpo=24484]: Avoid race condition in multiprocessing cleanup (#2159)

bpo-28994 [https://bugs.python.org/issue?@action=redirect&bpo=28994]: The traceback no longer displayed for SystemExit raised in a callback registered by atexit.

bpo-30508 [https://bugs.python.org/issue?@action=redirect&bpo=30508]: Don't log exceptions if Task/Future "cancel()" method was called.

bpo-28556 [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

bpo-29870 [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.

bpo-29743 [https://bugs.python.org/issue?@action=redirect&bpo=29743]: Closing transport during handshake process leaks open socket. Patch by Nikolay Kim

bpo-27585 [https://bugs.python.org/issue?@action=redirect&bpo=27585]: Fix waiter cancellation in asyncio.Lock. Patch by Mathieu Sornay.

bpo-30418 [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.

bpo-29822 [https://bugs.python.org/issue?@action=redirect&bpo=29822]: inspect.isabstract() now works during __init_subclass__. Patch by Nate Soares.

bpo-29581 [https://bugs.python.org/issue?@action=redirect&bpo=29581]: ABCMeta.__new__ now accepts **kwargs, allowing abstract base classes to use keyword parameters in __init_subclass__. Patch by Nate Soares.

bpo-30557 [https://bugs.python.org/issue?@action=redirect&bpo=30557]: faulthandler now correctly filters and displays exception codes on Windows

bpo-30378 [https://bugs.python.org/issue?@action=redirect&bpo=30378]: Fix the problem that logging.handlers.SysLogHandler cannot handle IPv6 addresses.

bpo-29960 [https://bugs.python.org/issue?@action=redirect&bpo=29960]: Preserve generator state when _random.Random.setstate() raises an exception. Patch by Bryan Olson.

bpo-30414 [https://bugs.python.org/issue?@action=redirect&bpo=30414]: multiprocessing.Queue._feed background running thread do not break from main loop on exception.

bpo-30003 [https://bugs.python.org/issue?@action=redirect&bpo=30003]: Fix handling escape characters in HZ codec. Based on patch by Ma Lin.

bpo-30301 [https://bugs.python.org/issue?@action=redirect&bpo=30301]: Fix AttributeError when using SimpleQueue.empty() under spawn and forkserver start methods.

bpo-30329 [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.

bpo-30375 [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.

bpo-30048 [https://bugs.python.org/issue?@action=redirect&bpo=30048]: Fixed Task.cancel() can be ignored when the task is running coroutine and the coroutine returned without any more await.

bpo-30266 [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 [https://bugs.python.org/issue?@action=redirect&bpo=25958]. Patch by Jelle Zijlstra.

bpo-30298 [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. '(?i)(?s)...'). In verbose mode whitespaces and comments now are allowed before and between inline modifiers (e.g. '(?x) (?i) (?s)...').

bpo-29990 [https://bugs.python.org/issue?@action=redirect&bpo=29990]: Fix range checking in GB18030 decoder. Original patch by Ma Lin.

bpo-26293 [https://bugs.python.org/issue?@action=redirect&bpo=26293]: Change resulted because of zipfile breakage. (See also: bpo-29094 [https://bugs.python.org/issue?@action=redirect&bpo=29094])

bpo-30243 [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.

bpo-30185 [https://bugs.python.org/issue?@action=redirect&bpo=30185]: Avoid KeyboardInterrupt tracebacks in forkserver helper process when Ctrl-C is received.

bpo-28556 [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.

bpo-30205 [https://bugs.python.org/issue?@action=redirect&bpo=30205]: Fix getsockname() for unbound AF_UNIX sockets on Linux.

bpo-30070 [https://bugs.python.org/issue?@action=redirect&bpo=30070]: Fixed leaks and crashes in errors handling in the parser module.

bpo-30061 [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().

bpo-30017 [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.

bpo-30068 [https://bugs.python.org/issue?@action=redirect&bpo=30068]: _io._IOBase.readlines will check if it's closed first when hint is present.

bpo-29694 [https://bugs.python.org/issue?@action=redirect&bpo=29694]: Fixed race condition in pathlib mkdir with flags parents=True. Patch by Armin Rigo.

bpo-29692 [https://bugs.python.org/issue?@action=redirect&bpo=29692]: Fixed arbitrary unchaining of RuntimeError exceptions in contextlib.contextmanager. Patch by Siddharth Velankar.

bpo-29998 [https://bugs.python.org/issue?@action=redirect&bpo=29998]: Pickling and copying ImportError now preserves name and path attributes.

bpo-29953 [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.

bpo-29942 [https://bugs.python.org/issue?@action=redirect&bpo=29942]: Fix a crash in itertools.chain.from_iterable when encountering long runs of empty iterables.

bpo-27863 [https://bugs.python.org/issue?@action=redirect&bpo=27863]: Fixed multiple crashes in ElementTree caused by race conditions and wrong types.

bpo-28699 [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.

bpo-25803 [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.

bpo-29861 [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.

bpo-29884 [https://bugs.python.org/issue?@action=redirect&bpo=29884]: faulthandler: Restore the old sigaltstack during teardown. Patch by Christophe Zeitouny.

bpo-25455 [https://bugs.python.org/issue?@action=redirect&bpo=25455]: Fixed crashes in repr of recursive buffered file-like objects.

bpo-29800 [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.

bpo-29742 [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.

bpo-8256 [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.

bpo-28298 [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.

bpo-28231 [https://bugs.python.org/issue?@action=redirect&bpo=28231]: The zipfile module now accepts path-like objects for external paths.

bpo-26915 [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.

bpo-29615 [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.

bpo-30177 [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.

IDLE

bpo-15786 [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.

bpo-25514 [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.

bpo-30642 [https://bugs.python.org/issue?@action=redirect&bpo=30642]: Fix reference leaks in IDLE tests. Patches by Louie Lu and Terry Jan Reedy.

bpo-30495 [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.

bpo-30290 [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.

bpo-30303 [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.

C API

bpo-27867 [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.

Build

bpo-29941 [https://bugs.python.org/issue?@action=redirect&bpo=29941]: Add --with-assertions configure flag to explicitly enable C assert() checks. Defaults to off. --with-pydebug implies --with-assertions.

bpo-28787 [https://bugs.python.org/issue?@action=redirect&bpo=28787]: Fix out-of-tree builds of Python when configured with --with--dtrace.

bpo-29243 [https://bugs.python.org/issue?@action=redirect&bpo=29243]: Prevent unnecessary rebuilding of Python during make test, make install and some other make targets when configured with --enable-optimizations.

bpo-23404 [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 make touch with make regen-all.

bpo-29643 [https://bugs.python.org/issue?@action=redirect&bpo=29643]: Fix --enable-optimization didn't work.

Documentation

bpo-30176 [https://bugs.python.org/issue?@action=redirect&bpo=30176]: Add missing attribute related constants in curses documentation.

bpo-30052 [https://bugs.python.org/issue?@action=redirect&bpo=30052]: the link targets for bytes() and bytearray() are now their respective type definitions, rather than the corresponding builtin function entries. Use bytes and 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.

bpo-26985 [https://bugs.python.org/issue?@action=redirect&bpo=26985]: Add missing info of code object in inspect documentation.

Tools/Demos

bpo-29367 [https://bugs.python.org/issue?@action=redirect&bpo=29367]: python-gdb.py now supports also method-wrapper (wrapperobject) objects.

Tests

bpo-30357 [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.

bpo-30197 [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.

Windows

bpo-30687 [https://bugs.python.org/issue?@action=redirect&bpo=30687]: Locate msbuild.exe on Windows when building rather than vcvarsall.bat

bpo-30450 [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 py -3.6), NuGet is used to download a copy of 32-bit Python.

Python 3.6.1 final

Release date: 2017-03-21

Core and Builtins

bpo-29723 [https://bugs.python.org/issue?@action=redirect&bpo=29723]: The sys.path[0] initialization change for bpo-29139 [https://bugs.python.org/issue?@action=redirect&bpo=29139] caused a regression by revealing an inconsistency in how sys.path is initialized when executing __main__ from a zipfile, directory, or other import location. The interpreter now consistently avoids ever adding the import location's parent directory to sys.path, and ensures no other sys.path entries are inadvertently modified when inserting the import location named on the command line.

Build

bpo-27593 [https://bugs.python.org/issue?@action=redirect&bpo=27593]: fix format of git information used in sys.version

Fix incompatible comment in python.h

Python 3.6.1 release candidate 1

Release date: 2017-03-04

Core and Builtins

bpo-28893 [https://bugs.python.org/issue?@action=redirect&bpo=28893]: Set correct __cause__ for errors about invalid awaitables returned from __aiter__ and __anext__.

bpo-29683 [https://bugs.python.org/issue?@action=redirect&bpo=29683]: Fixes to memory allocation in _PyCode_SetExtra. Patch by Brian Coleman.

bpo-29684 [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.

bpo-28598 [https://bugs.python.org/issue?@action=redirect&bpo=28598]: Support __rmod__ for subclasses of str being called before str.__mod__. Patch by Martijn Pieters.

bpo-29607 [https://bugs.python.org/issue?@action=redirect&bpo=29607]: Fix stack_effect computation for CALL_FUNCTION_EX. Patch by Matthieu Dartiailh.

bpo-29602 [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.

bpo-29347 [https://bugs.python.org/issue?@action=redirect&bpo=29347]: Fixed possibly dereferencing undefined pointers when creating weakref objects.

bpo-29438 [https://bugs.python.org/issue?@action=redirect&bpo=29438]: Fixed use-after-free problem in key sharing dict.

bpo-29319 [https://bugs.python.org/issue?@action=redirect&bpo=29319]: Prevent RunMainFromImporter overwriting sys.path[0].

bpo-29337 [https://bugs.python.org/issue?@action=redirect&bpo=29337]: Fixed possible BytesWarning when compare the code objects. Warnings could be emitted at compile time.

bpo-29327 [https://bugs.python.org/issue?@action=redirect&bpo=29327]: Fixed a crash when pass the iterable keyword argument to sorted().

bpo-29034 [https://bugs.python.org/issue?@action=redirect&bpo=29034]: Fix memory leak and use-after-free in os module (path_converter).

bpo-29159 [https://bugs.python.org/issue?@action=redirect&bpo=29159]: Fix regression in bytes(x) when x.__index__() raises Exception.

bpo-28932 [https://bugs.python.org/issue?@action=redirect&bpo=28932]: Do not include <sys/random.h> if it does not exist.

bpo-25677 [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.

bpo-29000 [https://bugs.python.org/issue?@action=redirect&bpo=29000]: Fixed bytes formatting of octals with zero padding in alternate form.

bpo-26919 [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.

bpo-28991 [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.

bpo-28739 [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.

bpo-28512 [https://bugs.python.org/issue?@action=redirect&bpo=28512]: Fixed setting the offset attribute of SyntaxError by PyErr_SyntaxLocationEx() and PyErr_SyntaxLocationObject().

bpo-28918 [https://bugs.python.org/issue?@action=redirect&bpo=28918]: Fix the cross compilation of xxlimited when Python has been built with Py_DEBUG defined.

bpo-28731 [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%.

Library

bpo-29169 [https://bugs.python.org/issue?@action=redirect&bpo=29169]: Update zlib to 1.2.11.

bpo-29623 [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.

bpo-28963 [https://bugs.python.org/issue?@action=redirect&bpo=28963]: Fix out of bound iteration in asyncio.Future.remove_done_callback implemented in C.

bpo-29704 [https://bugs.python.org/issue?@action=redirect&bpo=29704]: asyncio.subprocess.SubprocessStreamProtocol no longer closes before all pipes are closed.

bpo-29271 [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.

bpo-29703 [https://bugs.python.org/issue?@action=redirect&bpo=29703]: Fix asyncio to support instantiation of new event loops in child processes.

bpo-29376 [https://bugs.python.org/issue?@action=redirect&bpo=29376]: Fix assertion error in threading._DummyThread.is_alive().

bpo-28624 [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.

bpo-28518 [https://bugs.python.org/issue?@action=redirect&bpo=28518]: Start a transaction implicitly before a DML statement. Patch by Aviv Palivoda.

bpo-29532 [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.

bpo-29110 [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.

bpo-28556 [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.

bpo-29100 [https://bugs.python.org/issue?@action=redirect&bpo=29100]: Fix datetime.fromtimestamp() regression introduced in Python 3.6.0: check minimum and maximum years.

bpo-29519 [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.

bpo-29416 [https://bugs.python.org/issue?@action=redirect&bpo=29416]: Prevent infinite loop in pathlib.Path.mkdir

bpo-29444 [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.

bpo-29335 [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).

bpo-29290 [https://bugs.python.org/issue?@action=redirect&bpo=29290]: Fix a regression in argparse that help messages would wrap at non-breaking spaces.

bpo-28735 [https://bugs.python.org/issue?@action=redirect&bpo=28735]: Fixed the comparison of mock.MagickMock with mock.ANY.

bpo-29316 [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.

bpo-29219 [https://bugs.python.org/issue?@action=redirect&bpo=29219]: Fixed infinite recursion in the repr of uninitialized ctypes.CDLL instances.

bpo-29011 [https://bugs.python.org/issue?@action=redirect&bpo=29011]: Fix an important omission by adding Deque to the typing module.

bpo-28969 [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.

bpo-29142 [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.

bpo-28961 [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.

bpo-29203 [https://bugs.python.org/issue?@action=redirect&bpo=29203]: functools.lru_cache() now respects PEP 468 [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.

bpo-15812 [https://bugs.python.org/issue?@action=redirect&bpo=15812]: inspect.getframeinfo() now correctly shows the first line of a context. Patch by Sam Breese.

bpo-29094 [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.

bpo-29085 [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.

bpo-29061 [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.

bpo-29079 [https://bugs.python.org/issue?@action=redirect&bpo=29079]: Prevent infinite loop in pathlib.resolve() on Windows

bpo-13051 [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.

bpo-29119 [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.

bpo-9770 [https://bugs.python.org/issue?@action=redirect&bpo=9770]: curses.ascii predicates now work correctly with negative integers.

bpo-28427 [https://bugs.python.org/issue?@action=redirect&bpo=28427]: old keys should not remove new values from WeakValueDictionary when collecting from another thread.

bpo-28923 [https://bugs.python.org/issue?@action=redirect&bpo=28923]: Remove editor artifacts from Tix.py.

bpo-29055 [https://bugs.python.org/issue?@action=redirect&bpo=29055]: Neaten-up empty population error on random.choice() by suppressing the upstream exception.

bpo-28871 [https://bugs.python.org/issue?@action=redirect&bpo=28871]: Fixed a crash when deallocate deep ElementTree.

bpo-19542 [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.

bpo-20191 [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.

bpo-28779 [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.

bpo-28847 [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.

bpo-26937 [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.

IDLE

bpo-29071 [https://bugs.python.org/issue?@action=redirect&bpo=29071]: IDLE colors f-string prefixes (but not invalid ur prefixes).

bpo-28572 [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.

Windows

bpo-29579 [https://bugs.python.org/issue?@action=redirect&bpo=29579]: Removes readme.txt from the installer

bpo-29326 [https://bugs.python.org/issue?@action=redirect&bpo=29326]: Ignores blank lines in ._pth files (Patch by Alexey Izbyshev)

bpo-28164 [https://bugs.python.org/issue?@action=redirect&bpo=28164]: Correctly handle special console filenames (patch by Eryk Sun)

bpo-29409 [https://bugs.python.org/issue?@action=redirect&bpo=29409]: Implement PEP 529 [https://peps.python.org/pep-0529/] for io.FileIO (Patch by Eryk Sun)

bpo-29392 [https://bugs.python.org/issue?@action=redirect&bpo=29392]: Prevent crash when passing invalid arguments into msvcrt module.

bpo-25778 [https://bugs.python.org/issue?@action=redirect&bpo=25778]: winreg does not truncate string correctly (Patch by Eryk Sun)

bpo-28896 [https://bugs.python.org/issue?@action=redirect&bpo=28896]: Deprecate WindowsRegistryFinder and disable it by default.

C API

bpo-27867 [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.

bpo-29083 [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.

bpo-29058 [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.

Documentation

bpo-28929 [https://bugs.python.org/issue?@action=redirect&bpo=28929]: Link the documentation to its source file on GitHub.

bpo-25008 [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.

bpo-26355 [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.

bpo-29349 [https://bugs.python.org/issue?@action=redirect&bpo=29349]: Fix Python 2 syntax in code for building the documentation.

Tests

bpo-28087 [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.

bpo-29571 [https://bugs.python.org/issue?@action=redirect&bpo=29571]: to match the behaviour of the re.LOCALE flag, test_re.test_locale_flag now uses 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)

bpo-28950 [https://bugs.python.org/issue?@action=redirect&bpo=28950]: Disallow -j0 to be combined with -T/-l in regrtest command line arguments.

bpo-28683 [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.

bpo-26939 [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.

Build

bpo-27593 [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.

bpo-29572 [https://bugs.python.org/issue?@action=redirect&bpo=29572]: Update Windows build and OS X installers to use OpenSSL 1.0.2k.

bpo-26851 [https://bugs.python.org/issue?@action=redirect&bpo=26851]: Set Android compilation and link flags.

bpo-28768 [https://bugs.python.org/issue?@action=redirect&bpo=28768]: Fix implicit declaration of function _setmode. Patch by Masayuki Yamamoto

bpo-29080 [https://bugs.python.org/issue?@action=redirect&bpo=29080]: Removes hard dependency on hg.exe from PCBuild/build.bat

bpo-23903 [https://bugs.python.org/issue?@action=redirect&bpo=23903]: Added missed names to PC/python3.def.

bpo-28762 [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.

bpo-28538 [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.

bpo-20211 [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.

bpo-28849 [https://bugs.python.org/issue?@action=redirect&bpo=28849]: Do not define sys.implementation._multiarch on Android.

Python 3.6.0 final

Release date: 2016-12-23

No changes since release candidate 2

Python 3.6.0 release candidate 2

Release date: 2016-12-16

Core and Builtins

bpo-28147 [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.

bpo-28990 [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)

Tools/Demos

bpo-28770 [https://bugs.python.org/issue?@action=redirect&bpo=28770]: Fix python-gdb.py for fastcalls.

Windows

bpo-28896 [https://bugs.python.org/issue?@action=redirect&bpo=28896]: Deprecate WindowsRegistryFinder.

Build

bpo-28898 [https://bugs.python.org/issue?@action=redirect&bpo=28898]: Prevent gdb build errors due to HAVE_LONG_LONG redefinition.

Python 3.6.0 release candidate 1

Release date: 2016-12-06

Core and Builtins

bpo-23722 [https://bugs.python.org/issue?@action=redirect&bpo=23722]: Rather than silently producing a class that doesn't support zero-argument super() in methods, failing to pass the new __classcell__ namespace entry up to type.__new__ now results in a DeprecationWarning and a class that supports zero-argument super().

bpo-28797 [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.

bpo-28782 [https://bugs.python.org/issue?@action=redirect&bpo=28782]: Fix a bug in the implementation yield from when checking if the next instruction is YIELD_FROM. Regression introduced by WORDCODE (bpo-26647 [https://bugs.python.org/issue?@action=redirect&bpo=26647]).

Library

bpo-27030 [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.

bpo-28835 [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.

bpo-27172 [https://bugs.python.org/issue?@action=redirect&bpo=27172]: To assist with upgrades from 2.7, the previously documented deprecation of inspect.getfullargspec() has been reversed. This decision may be revisited again after the Python 2.7 branch is no longer officially supported.

bpo-26273 [https://bugs.python.org/issue?@action=redirect&bpo=26273]: Add new socket.TCP_CONGESTION (Linux 2.6.13) and socket.TCP_USER_TIMEOUT (Linux 2.6.37) constants. Patch written by Omar Sandoval.

bpo-24142 [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.

bpo-28843 [https://bugs.python.org/issue?@action=redirect&bpo=28843]: Fix asyncio C Task to handle exceptions __traceback__.

C API

bpo-28808 [https://bugs.python.org/issue?@action=redirect&bpo=28808]: PyUnicode_CompareWithASCIIString() now never raises exceptions.

Documentation

bpo-23722 [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 __classcell__ handling needed for custom metaclasses to fully support PEP 487 [https://peps.python.org/pep-0487/] and zero-argument super().

Tools/Demos

bpo-28023 [https://bugs.python.org/issue?@action=redirect&bpo=28023]: Fix python-gdb.py didn't support new dict implementation.

Python 3.6.0 beta 4

Release date: 2016-11-21

Core and Builtins

bpo-28532 [https://bugs.python.org/issue?@action=redirect&bpo=28532]: Show sys.version when -V option is supplied twice.

bpo-27100 [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.

bpo-28746 [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.

bpo-26920 [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.

bpo-28648 [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.

bpo-19398 [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.

bpo-28665 [https://bugs.python.org/issue?@action=redirect&bpo=28665]: Improve speed of the STORE_DEREF opcode by 40%.

bpo-28583 [https://bugs.python.org/issue?@action=redirect&bpo=28583]: PyDict_SetDefault didn't combine split table when needed. Patch by Xiang Zhang.

bpo-27243 [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.

bpo-26182 [https://bugs.python.org/issue?@action=redirect&bpo=26182]: Fix a refleak in code that raises DeprecationWarning.

bpo-28721 [https://bugs.python.org/issue?@action=redirect&bpo=28721]: Fix asynchronous generators aclose() and athrow() to handle StopAsyncIteration propagation properly.

Library

bpo-28752 [https://bugs.python.org/issue?@action=redirect&bpo=28752]: Restored the __reduce__() methods of datetime objects.

bpo-28727 [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 [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).

bpo-20572 [https://bugs.python.org/issue?@action=redirect&bpo=20572]: The subprocess.Popen.wait method's undocumented endtime parameter now raises a DeprecationWarning.

bpo-25659 [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.

bpo-19717 [https://bugs.python.org/issue?@action=redirect&bpo=19717]: Makes Path.resolve() succeed on paths that do not exist. Patch by Vajrasky Kok

bpo-28563 [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.

bpo-28387 [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.

bpo-28600 [https://bugs.python.org/issue?@action=redirect&bpo=28600]: Optimize loop.call_soon.

bpo-28613 [https://bugs.python.org/issue?@action=redirect&bpo=28613]: Fix get_event_loop() return the current loop if called from coroutines/callbacks.

bpo-28634 [https://bugs.python.org/issue?@action=redirect&bpo=28634]: Fix asyncio.isfuture() to support unittest.Mock.

bpo-26081 [https://bugs.python.org/issue?@action=redirect&bpo=26081]: Fix refleak in _asyncio.Future.__iter__().throw.

bpo-28639 [https://bugs.python.org/issue?@action=redirect&bpo=28639]: Fix inspect.isawaitable to always return bool Patch by Justin Mayfield.

bpo-28652 [https://bugs.python.org/issue?@action=redirect&bpo=28652]: Make loop methods reject socket kinds they do not support.

bpo-28653 [https://bugs.python.org/issue?@action=redirect&bpo=28653]: Fix a refleak in functools.lru_cache.

bpo-28703 [https://bugs.python.org/issue?@action=redirect&bpo=28703]: Fix asyncio.iscoroutinefunction to handle Mock objects.

bpo-28704 [https://bugs.python.org/issue?@action=redirect&bpo=28704]: Fix create_unix_server to support Path-like objects (PEP 519).

bpo-28720 [https://bugs.python.org/issue?@action=redirect&bpo=28720]: Add collections.abc.AsyncGenerator.

Documentation

bpo-28513 [https://bugs.python.org/issue?@action=redirect&bpo=28513]: Documented command-line interface of zipfile.

Tests

bpo-28666 [https://bugs.python.org/issue?@action=redirect&bpo=28666]: Now test.support.rmtree is able to remove unwritable or unreadable directories.

bpo-23839 [https://bugs.python.org/issue?@action=redirect&bpo=23839]: Various caches now are cleared before running every test file.

Build

bpo-10656 [https://bugs.python.org/issue?@action=redirect&bpo=10656]: Fix out-of-tree building on AIX. Patch by Tristan Carel and Michael Haubenwallner.

bpo-26359 [https://bugs.python.org/issue?@action=redirect&bpo=26359]: Rename --with-optimiations to --enable-optimizations.

bpo-28676 [https://bugs.python.org/issue?@action=redirect&bpo=28676]: Prevent missing 'getentropy' declaration warning on macOS. Patch by Gareth Rees.

Python 3.6.0 beta 3

Release date: 2016-10-31

Core and Builtins

bpo-28128 [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.

bpo-28509 [https://bugs.python.org/issue?@action=redirect&bpo=28509]: dict.update() no longer allocate unnecessary large memory.

bpo-28426 [https://bugs.python.org/issue?@action=redirect&bpo=28426]: Fixed potential crash in PyUnicode_AsDecodedObject() in debug build.

bpo-28517 [https://bugs.python.org/issue?@action=redirect&bpo=28517]: Fixed of-by-one error in the peephole optimizer that caused keeping unreachable code.

bpo-28214 [https://bugs.python.org/issue?@action=redirect&bpo=28214]: Improved exception reporting for problematic __set_name__ attributes.

bpo-23782 [https://bugs.python.org/issue?@action=redirect&bpo=23782]: Fixed possible memory leak in _PyTraceback_Add() and exception loss in PyTraceBack_Here().

bpo-28471 [https://bugs.python.org/issue?@action=redirect&bpo=28471]: Fix "Python memory allocator called without holding the GIL" crash in socket.setblocking.

Library

bpo-27517 [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.

bpo-28549 [https://bugs.python.org/issue?@action=redirect&bpo=28549]: Fixed segfault in curses's addch() with ncurses6.

bpo-28449 [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.

bpo-23262 [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.

bpo-27939 [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.

bpo-18844 [https://bugs.python.org/issue?@action=redirect&bpo=18844]: The various ways of specifying weights for random.choices() now produce the same result sequences.

bpo-28255 [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.

bpo-20491 [https://bugs.python.org/issue?@action=redirect&bpo=20491]: The textwrap.TextWrapper class now honors non-breaking spaces. Based on patch by Kaarle Ritvanen.

bpo-28353 [https://bugs.python.org/issue?@action=redirect&bpo=28353]: os.fwalk() no longer fails on broken links.

bpo-28430 [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).

bpo-27025 [https://bugs.python.org/issue?@action=redirect&bpo=27025]: Generated names for Tkinter widgets now start by the "!" prefix for readability.

bpo-25464 [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.

bpo-28488 [https://bugs.python.org/issue?@action=redirect&bpo=28488]: shutil.make_archive() no longer adds entry "./" to ZIP archive.

bpo-25953 [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.

bpo-18219 [https://bugs.python.org/issue?@action=redirect&bpo=18219]: Optimize csv.DictWriter for large number of columns. Patch by Mariatta Wijaya.

bpo-28448 [https://bugs.python.org/issue?@action=redirect&bpo=28448]: Fix C implemented asyncio.Future didn't work on Windows.

bpo-28480 [https://bugs.python.org/issue?@action=redirect&bpo=28480]: Fix error building socket module when multithreading is disabled.

bpo-24452 [https://bugs.python.org/issue?@action=redirect&bpo=24452]: Make webbrowser support Chrome on Mac OS X.

bpo-20766 [https://bugs.python.org/issue?@action=redirect&bpo=20766]: Fix references leaked by pdb in the handling of SIGINT handlers.

bpo-28492 [https://bugs.python.org/issue?@action=redirect&bpo=28492]: Fix how StopIteration exception is raised in _asyncio.Future.

bpo-28500 [https://bugs.python.org/issue?@action=redirect&bpo=28500]: Fix asyncio to handle async gens GC from another thread.

bpo-26923 [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.

bpo-26796 [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.

bpo-28544 [https://bugs.python.org/issue?@action=redirect&bpo=28544]: Implement asyncio.Task in C.

Windows

bpo-28522 [https://bugs.python.org/issue?@action=redirect&bpo=28522]: Fixes mishandled buffer reallocation in getpathp.c

Build

bpo-28444 [https://bugs.python.org/issue?@action=redirect&bpo=28444]: Fix missing extensions modules when cross compiling.

bpo-28208 [https://bugs.python.org/issue?@action=redirect&bpo=28208]: Update Windows build and OS X installers to use SQLite 3.14.2.

bpo-28248 [https://bugs.python.org/issue?@action=redirect&bpo=28248]: Update Windows build and OS X installers to use OpenSSL 1.0.2j.

Tests

bpo-26944 [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.

bpo-28409 [https://bugs.python.org/issue?@action=redirect&bpo=28409]: regrtest: fix the parser of command line arguments.

Python 3.6.0 beta 2

Release date: 2016-10-10

Core and Builtins

bpo-28183 [https://bugs.python.org/issue?@action=redirect&bpo=28183]: Optimize and cleanup dict iteration.

bpo-26081 [https://bugs.python.org/issue?@action=redirect&bpo=26081]: Added C implementation of asyncio.Future. Original patch by Yury Selivanov.

bpo-28379 [https://bugs.python.org/issue?@action=redirect&bpo=28379]: Added sanity checks and tests for PyUnicode_CopyCharacters(). Patch by Xiang Zhang.

bpo-28376 [https://bugs.python.org/issue?@action=redirect&bpo=28376]: The type of long range iterator is now registered as Iterator. Patch by Oren Milman.

bpo-28376 [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.

bpo-28376 [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.

bpo-26906 [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.

bpo-18287 [https://bugs.python.org/issue?@action=redirect&bpo=18287]: PyType_Ready() now checks that tp_name is not NULL. Original patch by Niklas Koep.

bpo-24098 [https://bugs.python.org/issue?@action=redirect&bpo=24098]: Fixed possible crash when AST is changed in process of compiling it.

bpo-28201 [https://bugs.python.org/issue?@action=redirect&bpo=28201]: Dict reduces possibility of 2nd conflict in hash table when hashes have same lower bits.

bpo-28350 [https://bugs.python.org/issue?@action=redirect&bpo=28350]: String constants with null character no longer interned.

bpo-26617 [https://bugs.python.org/issue?@action=redirect&bpo=26617]: Fix crash when GC runs during weakref callbacks.

bpo-27942 [https://bugs.python.org/issue?@action=redirect&bpo=27942]: String constants now interned recursively in tuples and frozensets.

bpo-21578 [https://bugs.python.org/issue?@action=redirect&bpo=21578]: Fixed misleading error message when ImportError called with invalid keyword args.

bpo-28203 [https://bugs.python.org/issue?@action=redirect&bpo=28203]: Fix incorrect type in complex(1.0, {2:3}) error message. Patch by Soumya Sharma.

bpo-28086 [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.

bpo-28214 [https://bugs.python.org/issue?@action=redirect&bpo=28214]: Now __set_name__ is looked up on the class instead of the instance.

bpo-27955 [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.

bpo-28192 [https://bugs.python.org/issue?@action=redirect&bpo=28192]: Don't import readline in isolated mode.

Upgrade internal unicode databases to Unicode version 9.0.0.

bpo-28131 [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.

bpo-28126 [https://bugs.python.org/issue?@action=redirect&bpo=28126]: Replace Py_MEMCPY with memcpy(). Visual Studio can properly optimize memcpy().

bpo-28120 [https://bugs.python.org/issue?@action=redirect&bpo=28120]: Fix dict.pop() for splitted dictionary when trying to remove a "pending key" (Not yet inserted in split-table). Patch by Xiang Zhang.

bpo-26182 [https://bugs.python.org/issue?@action=redirect&bpo=26182]: Raise DeprecationWarning when async and await keywords are used as variable/attribute/class/function name.

Library

bpo-27998 [https://bugs.python.org/issue?@action=redirect&bpo=27998]: Fixed bytes path support in os.scandir() on Windows. Patch by Eryk Sun.

bpo-28317 [https://bugs.python.org/issue?@action=redirect&bpo=28317]: The disassembler now decodes FORMAT_VALUE argument.

bpo-26293 [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.

bpo-28380 [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.

bpo-27181 [https://bugs.python.org/issue?@action=redirect&bpo=27181]: remove statistics.geometric_mean and defer until 3.7.

bpo-28229 [https://bugs.python.org/issue?@action=redirect&bpo=28229]: lzma module now supports pathlib.

bpo-28321 [https://bugs.python.org/issue?@action=redirect&bpo=28321]: Fixed writing non-BMP characters with binary format in plistlib.

bpo-28225 [https://bugs.python.org/issue?@action=redirect&bpo=28225]: bz2 module now supports pathlib. Initial patch by Ethan Furman.

bpo-28227 [https://bugs.python.org/issue?@action=redirect&bpo=28227]: gzip now supports pathlib. Patch by Ethan Furman.

bpo-27358 [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.

bpo-28257 [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.

bpo-28322 [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.

bpo-28228 [https://bugs.python.org/issue?@action=redirect&bpo=28228]: imghdr now supports pathlib.

bpo-28226 [https://bugs.python.org/issue?@action=redirect&bpo=28226]: compileall now supports pathlib.

bpo-28314 [https://bugs.python.org/issue?@action=redirect&bpo=28314]: Fix function declaration (C flags) for the getiterator() method of xml.etree.ElementTree.Element.

bpo-28148 [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.

bpo-28253 [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.

bpo-28275 [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.

bpo-27897 [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.

bpo-18844 [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.

bpo-18893 [https://bugs.python.org/issue?@action=redirect&bpo=18893]: Fix invalid exception handling in Lib/ctypes/macholib/dyld.py. Patch by Madison May.

bpo-27611 [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.

bpo-27348 [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.

bpo-25651 [https://bugs.python.org/issue?@action=redirect&bpo=25651]: Allow false values to be used for msg parameter of subTest().

bpo-27778 [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.

bpo-28200 [https://bugs.python.org/issue?@action=redirect&bpo=28200]: Fix memory leak on Windows in the os module (fix path_converter() function).

bpo-25400 [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.

bpo-27932 [https://bugs.python.org/issue?@action=redirect&bpo=27932]: Prevent memory leak in win32_ver().

Fix UnboundLocalError in socket._sendfile_use_sendfile.

bpo-28075 [https://bugs.python.org/issue?@action=redirect&bpo=28075]: Check for ERROR_ACCESS_DENIED in Windows implementation of os.stat(). Patch by Eryk Sun.

bpo-22493 [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.

bpo-25270 [https://bugs.python.org/issue?@action=redirect&bpo=25270]: Prevent codecs.escape_encode() from raising SystemError when an empty bytestring is passed.

bpo-28181 [https://bugs.python.org/issue?@action=redirect&bpo=28181]: Get antigravity over HTTPS. Patch by Kaartic Sivaraam.

bpo-25895 [https://bugs.python.org/issue?@action=redirect&bpo=25895]: Enable WebSocket URL schemes in urllib.parse.urljoin. Patch by Gergely Imreh and Markus Holtermann.

bpo-28114 [https://bugs.python.org/issue?@action=redirect&bpo=28114]: Fix a crash in parse_envlist() when env contains byte strings. Patch by Eryk Sun.

bpo-27599 [https://bugs.python.org/issue?@action=redirect&bpo=27599]: Fixed buffer overrun in binascii.b2a_qp() and binascii.a2b_qp().

bpo-27906 [https://bugs.python.org/issue?@action=redirect&bpo=27906]: Fix socket accept exhaustion during high TCP traffic. Patch by Kevin Conway.

bpo-28174 [https://bugs.python.org/issue?@action=redirect&bpo=28174]: Handle when SO_REUSEPORT isn't properly supported. Patch by Seth Michael Larson.

bpo-26654 [https://bugs.python.org/issue?@action=redirect&bpo=26654]: Inspect functools.partial in asyncio.Handle.__repr__. Patch by iceboy.

bpo-26909 [https://bugs.python.org/issue?@action=redirect&bpo=26909]: Fix slow pipes IO in asyncio. Patch by INADA Naoki.

bpo-28176 [https://bugs.python.org/issue?@action=redirect&bpo=28176]: Fix callbacks race in asyncio.SelectorLoop.sock_connect.

bpo-27759 [https://bugs.python.org/issue?@action=redirect&bpo=27759]: Fix selectors incorrectly retain invalid file descriptors. Patch by Mark Williams.

bpo-28368 [https://bugs.python.org/issue?@action=redirect&bpo=28368]: Refuse monitoring processes if the child watcher has no loop attached. Patch by Vincent Michel.

bpo-28369 [https://bugs.python.org/issue?@action=redirect&bpo=28369]: Raise RuntimeError when transport's FD is used with add_reader, add_writer, etc.

bpo-28370 [https://bugs.python.org/issue?@action=redirect&bpo=28370]: Speedup asyncio.StreamReader.readexactly. Patch by Коренберг Марк.

bpo-28371 [https://bugs.python.org/issue?@action=redirect&bpo=28371]: Deprecate passing asyncio.Handles to run_in_executor.

bpo-28372 [https://bugs.python.org/issue?@action=redirect&bpo=28372]: Fix asyncio to support formatting of non-python coroutines.

bpo-28399 [https://bugs.python.org/issue?@action=redirect&bpo=28399]: Remove UNIX socket from FS before binding. Patch by Коренберг Марк.

bpo-27972 [https://bugs.python.org/issue?@action=redirect&bpo=27972]: Prohibit Tasks to await on themselves.

Windows

bpo-28402 [https://bugs.python.org/issue?@action=redirect&bpo=28402]: Adds signed catalog files for stdlib on Windows.

bpo-28333 [https://bugs.python.org/issue?@action=redirect&bpo=28333]: Enables Unicode for ps1/ps2 and input() prompts. (Patch by Eryk Sun)

bpo-28251 [https://bugs.python.org/issue?@action=redirect&bpo=28251]: Improvements to help manuals on Windows.

bpo-28110 [https://bugs.python.org/issue?@action=redirect&bpo=28110]: launcher.msi has different product codes between 32-bit and 64-bit

bpo-28161 [https://bugs.python.org/issue?@action=redirect&bpo=28161]: Opening CON for write access fails

bpo-28162 [https://bugs.python.org/issue?@action=redirect&bpo=28162]: WindowsConsoleIO readall() fails if first line starts with Ctrl+Z

bpo-28163 [https://bugs.python.org/issue?@action=redirect&bpo=28163]: WindowsConsoleIO fileno() passes wrong flags to _open_osfhandle

bpo-28164 [https://bugs.python.org/issue?@action=redirect&bpo=28164]: _PyIO_get_console_type fails for various paths

bpo-28137 [https://bugs.python.org/issue?@action=redirect&bpo=28137]: Renames Windows path file to ._pth

bpo-28138 [https://bugs.python.org/issue?@action=redirect&bpo=28138]: Windows ._pth file should allow import site

C API

bpo-28426 [https://bugs.python.org/issue?@action=redirect&bpo=28426]: Deprecated undocumented functions PyUnicode_AsEncodedObject(), PyUnicode_AsDecodedObject(), PyUnicode_AsDecodedUnicode() and PyUnicode_AsEncodedUnicode().

Build

bpo-28258 [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.

bpo-26661 [https://bugs.python.org/issue?@action=redirect&bpo=26661]: setup.py now detects system libffi with multiarch wrapper.

bpo-15819 [https://bugs.python.org/issue?@action=redirect&bpo=15819]: Remove redundant include search directory option for building outside the source tree.

Tests

bpo-28217 [https://bugs.python.org/issue?@action=redirect&bpo=28217]: Adds _testconsole module to test console input.

Python 3.6.0 beta 1

Release date: 2016-09-12

Core and Builtins

bpo-23722 [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.

bpo-25221 [https://bugs.python.org/issue?@action=redirect&bpo=25221]: Fix corrupted result from PyLong_FromLong(0) when Python is compiled with NSMALLPOSINTS = 0.

bpo-27080 [https://bugs.python.org/issue?@action=redirect&bpo=27080]: Implement formatting support for PEP 515 [https://peps.python.org/pep-0515/]. Initial patch by Chris Angelico.

bpo-27199 [https://bugs.python.org/issue?@action=redirect&bpo=27199]: In tarfile, expose copyfileobj bufsize to improve throughput. Patch by Jason Fried.

bpo-27948 [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 f'\x7b"hi"\x7d'.

bpo-28046 [https://bugs.python.org/issue?@action=redirect&bpo=28046]: Remove platform-specific directories from sys.path.

bpo-28071 [https://bugs.python.org/issue?@action=redirect&bpo=28071]: Add early-out for differencing from an empty set.

bpo-25758 [https://bugs.python.org/issue?@action=redirect&bpo=25758]: Prevents zipimport from unnecessarily encoding a filename (patch by Eryk Sun)

bpo-25856 [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.

bpo-27213 [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.

bpo-26331 [https://bugs.python.org/issue?@action=redirect&bpo=26331]: Implement tokenizing support for PEP 515 [https://peps.python.org/pep-0515/]. Patch by Georg Brandl.

bpo-27999 [https://bugs.python.org/issue?@action=redirect&bpo=27999]: Make "global after use" a SyntaxError, and ditto for nonlocal. Patch by Ivan Levkivskyi.

bpo-28003 [https://bugs.python.org/issue?@action=redirect&bpo=28003]: Implement PEP 525 [https://peps.python.org/pep-0525/] -- Asynchronous Generators.

bpo-27985 [https://bugs.python.org/issue?@action=redirect&bpo=27985]: Implement PEP 526 [https://peps.python.org/pep-0526/] -- Syntax for Variable Annotations. Patch by Ivan Levkivskyi.

bpo-26058 [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.

bpo-27364 [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.

bpo-27350 [https://bugs.python.org/issue?@action=redirect&bpo=27350]: dict implementation is changed like PyPy. It is more compact and preserves insertion order. (Concept developed by Raymond Hettinger and patch by Inada Naoki.)

bpo-27911 [https://bugs.python.org/issue?@action=redirect&bpo=27911]: Remove unnecessary error checks in exec_builtin_or_dynamic().

bpo-27078 [https://bugs.python.org/issue?@action=redirect&bpo=27078]: Added BUILD_STRING opcode. Optimized f-strings evaluation.

bpo-17884 [https://bugs.python.org/issue?@action=redirect&bpo=17884]: Python now requires systems with inttypes.h and stdint.h

bpo-27961 [https://bugs.python.org/issue?@action=redirect&bpo=27961]: Require platforms to support long long. Python hasn't compiled without long long for years, so this is basically a formality.

bpo-27355 [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.

Implement PEP 523 [https://peps.python.org/pep-0523/].

bpo-27870 [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.

bpo-25402 [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.

bpo-27214 [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.

bpo-27506 [https://bugs.python.org/issue?@action=redirect&bpo=27506]: Support passing the bytes/bytearray.translate() "delete" argument by keyword.

bpo-27812 [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().

bpo-27811 [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.

bpo-27587 [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.

bpo-27792 [https://bugs.python.org/issue?@action=redirect&bpo=27792]: The modulo operation applied to bool and other int subclasses now always returns an int. Previously the return type depended on the input values. Patch by Xiang Zhang.

bpo-26984 [https://bugs.python.org/issue?@action=redirect&bpo=26984]: int() now always returns an instance of exact int.

bpo-25604 [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.

bpo-24254 [https://bugs.python.org/issue?@action=redirect&bpo=24254]: Make class definition namespace ordered by default.

bpo-27662 [https://bugs.python.org/issue?@action=redirect&bpo=27662]: Fix an overflow check in List_New: the original code was checking against Py_SIZE_MAX instead of the correct upper bound of Py_SSIZE_T_MAX. Patch by Xiang Zhang.

bpo-27782 [https://bugs.python.org/issue?@action=redirect&bpo=27782]: Multi-phase extension module import now correctly allows the m_methods field to be used to add module level functions to instances of non-module types returned from Py_create_mod. Patch by Xiang Zhang.

bpo-27936 [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.

bpo-27487 [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.

bpo-27157 [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.

bpo-27558 [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.

bpo-28008 [https://bugs.python.org/issue?@action=redirect&bpo=28008]: Implement PEP 530 [https://peps.python.org/pep-0530/] -- asynchronous comprehensions.

bpo-27942 [https://bugs.python.org/issue?@action=redirect&bpo=27942]: Fix memory leak in codeobject.c

Library

bpo-28732 [https://bugs.python.org/issue?@action=redirect&bpo=28732]: Fix crash in os.spawnv() with no elements in args

bpo-28485 [https://bugs.python.org/issue?@action=redirect&bpo=28485]: Always raise ValueError for negative compileall.compile_dir(workers=...) parameter, even when multithreading is unavailable.

bpo-28037 [https://bugs.python.org/issue?@action=redirect&bpo=28037]: Use sqlite3_get_autocommit() instead of setting Connection->inTransaction manually.

bpo-25283 [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().

bpo-24454 [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)".

bpo-10740 [https://bugs.python.org/issue?@action=redirect&bpo=10740]: sqlite3 no longer implicitly commit an open transaction before DDL statements.

bpo-17941 [https://bugs.python.org/issue?@action=redirect&bpo=17941]: Add a module parameter to collections.namedtuple().

bpo-22493 [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.

bpo-26885 [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.

bpo-28070 [https://bugs.python.org/issue?@action=redirect&bpo=28070]: Fixed parsing inline verbose flag in regular expressions.

bpo-19500 [https://bugs.python.org/issue?@action=redirect&bpo=19500]: Add client-side SSL session resumption to the ssl module.

bpo-28022 [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.

bpo-28043 [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.

bpo-24693 [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.

bpo-17909 [https://bugs.python.org/issue?@action=redirect&bpo=17909]: json.load and json.loads now support binary input encoded as UTF-8, UTF-16 or UTF-32. Patch by Serhiy Storchaka.

bpo-27137 [https://bugs.python.org/issue?@action=redirect&bpo=27137]: the pure Python fallback implementation of 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.

Fix possible integer overflows and crashes in the mmap module with unusual usage patterns.

bpo-1703178 [https://bugs.python.org/issue?@action=redirect&bpo=1703178]: Fix the ability to pass the --link-objects option to the distutils build_ext command.

bpo-28019 [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.

bpo-18401 [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.

bpo-25969 [https://bugs.python.org/issue?@action=redirect&bpo=25969]: Update the lib2to3 grammar to handle the unpacking generalizations added in 3.5.

bpo-14977 [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.

bpo-28082 [https://bugs.python.org/issue?@action=redirect&bpo=28082]: Convert re flag constants to IntFlag.

bpo-28025 [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.

bpo-23591 [https://bugs.python.org/issue?@action=redirect&bpo=23591]: Add Flag, IntFlag, and auto() to enum module.

bpo-433028 [https://bugs.python.org/issue?@action=redirect&bpo=433028]: Added support of modifier spans in regular expressions.

bpo-24594 [https://bugs.python.org/issue?@action=redirect&bpo=24594]: Validates persist parameter when opening MSI database

bpo-17582 [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.)

bpo-28047 [https://bugs.python.org/issue?@action=redirect&bpo=28047]: Fixed calculation of line length used for the base64 CTE in the new email policies.

bpo-27576 [https://bugs.python.org/issue?@action=redirect&bpo=27576]: Fix call order in OrderedDict.__init__().

email.generator.DecodedGenerator now supports the policy keyword.

bpo-28027 [https://bugs.python.org/issue?@action=redirect&bpo=28027]: Remove undocumented modules from Lib/plat-*: IN, CDROM, DLFCN, TYPES, CDIO, and STROPTS.

bpo-27445 [https://bugs.python.org/issue?@action=redirect&bpo=27445]: Don't pass str(_charset) to MIMEText.set_payload(). Patch by Claude Paroz.

bpo-24277 [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.

bpo-22450 [https://bugs.python.org/issue?@action=redirect&bpo=22450]: urllib now includes an Accept: */* header among the default headers. This makes the results of REST API requests more consistent and predictable especially when proxy servers are involved.

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.

bpo-28005 [https://bugs.python.org/issue?@action=redirect&bpo=28005]: Allow ImportErrors in encoding implementation to propagate.

bpo-26667 [https://bugs.python.org/issue?@action=redirect&bpo=26667]: Support path-like objects in importlib.util.

bpo-27570 [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.

bpo-22233 [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.

bpo-27331 [https://bugs.python.org/issue?@action=redirect&bpo=27331]: The email.mime classes now all accept an optional policy keyword.

bpo-27988 [https://bugs.python.org/issue?@action=redirect&bpo=27988]: Fix email iter_attachments incorrect mutation of payload list.

bpo-16113 [https://bugs.python.org/issue?@action=redirect&bpo=16113]: Add SHA-3 and SHAKE support to hashlib module.

Eliminate a tautological-pointer-compare warning in _scproxy.c.

bpo-27776 [https://bugs.python.org/issue?@action=redirect&bpo=27776]: The 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 PEP 524 [https://peps.python.org/pep-0524/].

bpo-27778 [https://bugs.python.org/issue?@action=redirect&bpo=27778]: Expose the Linux getrandom() syscall as a new os.getrandom() function. This change is part of the PEP 524 [https://peps.python.org/pep-0524/].

bpo-27691 [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.

bpo-18844 [https://bugs.python.org/issue?@action=redirect&bpo=18844]: Add random.choices().

bpo-25761 [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.

bpo-26798 [https://bugs.python.org/issue?@action=redirect&bpo=26798]: Add BLAKE2 (blake2b and blake2s) to hashlib.

bpo-26032 [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.

bpo-25596 [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.

bpo-27928 [https://bugs.python.org/issue?@action=redirect&bpo=27928]: Add scrypt (password-based key derivation function) to hashlib module (requires OpenSSL 1.1.0).

bpo-27850 [https://bugs.python.org/issue?@action=redirect&bpo=27850]: Remove 3DES from ssl module's default cipher list to counter measure sweet32 attack (CVE-2016-2183 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-2183]).

bpo-27766 [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).

bpo-25387 [https://bugs.python.org/issue?@action=redirect&bpo=25387]: Check return value of winsound.MessageBeep.

bpo-27866 [https://bugs.python.org/issue?@action=redirect&bpo=27866]: Add SSLContext.get_ciphers() method to get a list of all enabled ciphers.

bpo-27744 [https://bugs.python.org/issue?@action=redirect&bpo=27744]: Add AF_ALG (Linux Kernel crypto) to socket module.

bpo-26470 [https://bugs.python.org/issue?@action=redirect&bpo=26470]: Port ssl and hashlib module to OpenSSL 1.1.0.

bpo-11620 [https://bugs.python.org/issue?@action=redirect&bpo=11620]: Fix support for SND_MEMORY in winsound.PlaySound. Based on a patch by Tim Lesher.

bpo-11734 [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.

bpo-27919 [https://bugs.python.org/issue?@action=redirect&bpo=27919]: Deprecated extra_path distribution option in distutils packaging.

bpo-23229 [https://bugs.python.org/issue?@action=redirect&bpo=23229]: Add new cmath constants: cmath.inf and cmath.nan to match math.inf and math.nan, and also cmath.infj and cmath.nanj to match the format used by complex repr.

bpo-27842 [https://bugs.python.org/issue?@action=redirect&bpo=27842]: The csv.DictReader now returns rows of type OrderedDict. (Contributed by Steve Holden.)

Remove support for passing a file descriptor to os.access. It never worked but previously didn't raise.

bpo-12885 [https://bugs.python.org/issue?@action=redirect&bpo=12885]: Fix error when distutils encounters symlink.

bpo-27881 [https://bugs.python.org/issue?@action=redirect&bpo=27881]: Fixed possible bugs when setting sqlite3.Connection.isolation_level. Based on patch by Xiang Zhang.

bpo-27861 [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.

bpo-19884 [https://bugs.python.org/issue?@action=redirect&bpo=19884]: Avoid spurious output on OS X with Gnu Readline.

bpo-27706 [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.

bpo-10513 [https://bugs.python.org/issue?@action=redirect&bpo=10513]: Fix a regression in Connection.commit(). Statements should not be reset after a commit.

bpo-12319 [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.

A new version of typing.py from https://github.com/python/typing: - Collection (only for 3.6) (bpo-27598 [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)

bpo-27832 [https://bugs.python.org/issue?@action=redirect&bpo=27832]: Make _normalize parameter to Fraction constructor keyword-only, so that Fraction(2, 3, 4) now raises TypeError.

bpo-27539 [https://bugs.python.org/issue?@action=redirect&bpo=27539]: Fix unnormalised Fraction.__pow__ result in the case of negative exponent and negative base.

bpo-21718 [https://bugs.python.org/issue?@action=redirect&bpo=21718]: cursor.description is now available for queries using CTEs.

bpo-27819 [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.

bpo-2466 [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.

bpo-9998 [https://bugs.python.org/issue?@action=redirect&bpo=9998]: On Linux, ctypes.util.find_library now looks in LD_LIBRARY_PATH for shared libraries.

bpo-27573 [https://bugs.python.org/issue?@action=redirect&bpo=27573]: exit message for code.interact is now configurable.

bpo-27930 [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.

bpo-6766 [https://bugs.python.org/issue?@action=redirect&bpo=6766]: Distributed reference counting added to multiprocessing to support nesting of shared values / proxy objects.

bpo-21201 [https://bugs.python.org/issue?@action=redirect&bpo=21201]: Improves readability of multiprocessing error message. Thanks to Wojciech Walczak for patch.

asyncio: Add set_protocol / get_protocol to Transports.

bpo-27456 [https://bugs.python.org/issue?@action=redirect&bpo=27456]: asyncio: Set TCP_NODELAY by default.

IDLE

bpo-15308 [https://bugs.python.org/issue?@action=redirect&bpo=15308]: Add 'interrupt execution' (^C) to Shell menu. Patch by Roger Serwy, updated by Bayard Randel.

bpo-27922 [https://bugs.python.org/issue?@action=redirect&bpo=27922]: Stop IDLE tests from 'flashing' gui widgets on the screen.

bpo-27891 [https://bugs.python.org/issue?@action=redirect&bpo=27891]: Consistently group and sort imports within idlelib modules.

bpo-17642 [https://bugs.python.org/issue?@action=redirect&bpo=17642]: add larger font sizes for classroom projection.

Add version to title of IDLE help window.

bpo-25564 [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.

bpo-27821 [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.

C API

bpo-26900 [https://bugs.python.org/issue?@action=redirect&bpo=26900]: Excluded underscored names and other private API from limited API.

bpo-26027 [https://bugs.python.org/issue?@action=redirect&bpo=26027]: Add support for path-like objects in PyUnicode_FSConverter() & PyUnicode_FSDecoder().

Tests

bpo-27427 [https://bugs.python.org/issue?@action=redirect&bpo=27427]: Additional tests for the math module. Patch by Francisco Couzo.

bpo-27953 [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.

bpo-26040 [https://bugs.python.org/issue?@action=redirect&bpo=26040]: Improve test_math and test_cmath coverage and rigour. Patch by Jeff Allen.

bpo-27787 [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.

Build

bpo-27566 [https://bugs.python.org/issue?@action=redirect&bpo=27566]: Fix clean target in freeze makefile (patch by Lisa Roach)

bpo-27705 [https://bugs.python.org/issue?@action=redirect&bpo=27705]: Update message in validate_ucrtbase.py

bpo-27976 [https://bugs.python.org/issue?@action=redirect&bpo=27976]: Deprecate building _ctypes with the bundled copy of libffi on non-OSX UNIX platforms.

bpo-27983 [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.

bpo-21590 [https://bugs.python.org/issue?@action=redirect&bpo=21590]: Support for DTrace and SystemTap probes.

bpo-26307 [https://bugs.python.org/issue?@action=redirect&bpo=26307]: The profile-opt build now applies PGO to the built-in modules.

bpo-26359 [https://bugs.python.org/issue?@action=redirect&bpo=26359]: Add the --with-optimizations flag to turn on LTO and PGO build support when available.

bpo-27917 [https://bugs.python.org/issue?@action=redirect&bpo=27917]: Set platform triplets for Android builds.

bpo-25825 [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.

Update OS X installer to use SQLite 3.14.1 and XZ 5.2.2.

bpo-21122 [https://bugs.python.org/issue?@action=redirect&bpo=21122]: Fix LTO builds on OS X.

bpo-17128 [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.

Tools/Demos

bpo-27952 [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.

Windows

bpo-28065 [https://bugs.python.org/issue?@action=redirect&bpo=28065]: Update xz dependency to 5.2.2 and build it from source.

bpo-25144 [https://bugs.python.org/issue?@action=redirect&bpo=25144]: Ensures TargetDir is set before continuing with custom install.

bpo-1602 [https://bugs.python.org/issue?@action=redirect&bpo=1602]: Windows console doesn't input or print Unicode (PEP 528)

bpo-27781 [https://bugs.python.org/issue?@action=redirect&bpo=27781]: Change file system encoding on Windows to UTF-8 (PEP 529)

bpo-27731 [https://bugs.python.org/issue?@action=redirect&bpo=27731]: Opt-out of MAX_PATH on Windows 10

bpo-6135 [https://bugs.python.org/issue?@action=redirect&bpo=6135]: Adds encoding and errors parameters to subprocess.

bpo-27959 [https://bugs.python.org/issue?@action=redirect&bpo=27959]: Adds oem encoding, alias ansi to mbcs, move aliasmbcs to codec lookup.

bpo-27982 [https://bugs.python.org/issue?@action=redirect&bpo=27982]: The functions of the winsound module now accept keyword arguments.

bpo-20366 [https://bugs.python.org/issue?@action=redirect&bpo=20366]: Build full text search support into SQLite on Windows.

bpo-27756 [https://bugs.python.org/issue?@action=redirect&bpo=27756]: Adds new icons for Python files and processes on Windows. Designs by Cherry Wang.

bpo-27883 [https://bugs.python.org/issue?@action=redirect&bpo=27883]: Update sqlite to 3.14.1.0 on Windows.

Python 3.6.0 alpha 4

Release date: 2016-08-15

Core and Builtins

bpo-27704 [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.

bpo-26823 [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.

bpo-27574 [https://bugs.python.org/issue?@action=redirect&bpo=27574]: Decreased an overhead of parsing keyword arguments in functions implemented with using Argument Clinic.

bpo-22557 [https://bugs.python.org/issue?@action=redirect&bpo=22557]: Now importing already imported modules is up to 2.5 times faster.

bpo-17596 [https://bugs.python.org/issue?@action=redirect&bpo=17596]: Include <wincrypt.h> to help with Min GW building.

bpo-17599 [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.

bpo-27507 [https://bugs.python.org/issue?@action=redirect&bpo=27507]: Add integer overflow check in bytearray.extend(). Patch by Xiang Zhang.

bpo-27581 [https://bugs.python.org/issue?@action=redirect&bpo=27581]: Don't rely on wrapping for overflow check in PySequence_Tuple(). Patch by Xiang Zhang.

bpo-1621 [https://bugs.python.org/issue?@action=redirect&bpo=1621]: Avoid signed integer overflow in list and tuple operations. Patch by Xiang Zhang.

bpo-27419 [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__.

bpo-27083 [https://bugs.python.org/issue?@action=redirect&bpo=27083]: Respect the PYTHONCASEOK environment variable under Windows.

bpo-27514 [https://bugs.python.org/issue?@action=redirect&bpo=27514]: Make having too many statically nested blocks a SyntaxError instead of SystemError.

bpo-27366 [https://bugs.python.org/issue?@action=redirect&bpo=27366]: Implemented PEP 487 [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.

Library

bpo-26027 [https://bugs.python.org/issue?@action=redirect&bpo=26027]: Add PEP 519 [https://peps.python.org/pep-0519/]/__fspath__() support to the os and os.path modules. Includes code from Jelle Zijlstra. (See also: bpo-27524 [https://bugs.python.org/issue?@action=redirect&bpo=27524])

bpo-27598 [https://bugs.python.org/issue?@action=redirect&bpo=27598]: Add Collections to collections.abc. Patch by Ivan Levkivskyi, docs by Neil Girdhar.

bpo-25958 [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.

bpo-16764 [https://bugs.python.org/issue?@action=redirect&bpo=16764]: Support keyword arguments to zlib.decompress(). Patch by Xiang Zhang.

bpo-27736 [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 [https://bugs.python.org/issue?@action=redirect&bpo=27038] in 3.6.0a3. Patch by Xiang Zhang.

bpo-25628 [https://bugs.python.org/issue?@action=redirect&bpo=25628]: The verbose and rename parameters for collections.namedtuple are now keyword-only.

bpo-12345 [https://bugs.python.org/issue?@action=redirect&bpo=12345]: Add mathematical constant tau to math and cmath. See also PEP 628 [https://peps.python.org/pep-0628/].

bpo-26823 [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.

bpo-27664 [https://bugs.python.org/issue?@action=redirect&bpo=27664]: Add to concurrent.futures.thread.ThreadPoolExecutor() the ability to specify a thread name prefix.

bpo-27181 [https://bugs.python.org/issue?@action=redirect&bpo=27181]: Add geometric_mean and harmonic_mean to statistics module.

bpo-27573 [https://bugs.python.org/issue?@action=redirect&bpo=27573]: code.interact now prints an message when exiting.

bpo-6422 [https://bugs.python.org/issue?@action=redirect&bpo=6422]: Add autorange method to timeit.Timer objects.

bpo-27773 [https://bugs.python.org/issue?@action=redirect&bpo=27773]: Correct some memory management errors server_hostname in _ssl.wrap_socket().

bpo-26750 [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.

bpo-26754 [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.

bpo-26800 [https://bugs.python.org/issue?@action=redirect&bpo=26800]: Undocumented support of general bytes-like objects as paths in os functions is now deprecated.

bpo-26981 [https://bugs.python.org/issue?@action=redirect&bpo=26981]: Add _order_ compatibility shim to enum.Enum for Python 2/3 code bases.

bpo-27661 [https://bugs.python.org/issue?@action=redirect&bpo=27661]: Added tzinfo keyword argument to datetime.combine.

In the curses module, raise an error if window.getstr() or window.instr() is passed a negative value.

bpo-27783 [https://bugs.python.org/issue?@action=redirect&bpo=27783]: Fix possible usage of uninitialized memory in operator.methodcaller.

bpo-27774 [https://bugs.python.org/issue?@action=redirect&bpo=27774]: Fix possible Py_DECREF on unowned object in _sre.

bpo-27760 [https://bugs.python.org/issue?@action=redirect&bpo=27760]: Fix possible integer overflow in binascii.b2a_qp.

bpo-27758 [https://bugs.python.org/issue?@action=redirect&bpo=27758]: Fix possible integer overflow in the _csv module for large record lengths.

bpo-27568 [https://bugs.python.org/issue?@action=redirect&bpo=27568]: Prevent HTTPoxy attack (CVE-2016-1000110 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-1000110]). Ignore the HTTP_PROXY variable when REQUEST_METHOD environment is set, which indicates that the script is in CGI mode.

bpo-7063 [https://bugs.python.org/issue?@action=redirect&bpo=7063]: Remove dead code from the "array" module's slice handling. Patch by Chuck.

bpo-27656 [https://bugs.python.org/issue?@action=redirect&bpo=27656]: Do not assume sched.h defines any SCHED_* constants.

bpo-27130 [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.

bpo-24773 [https://bugs.python.org/issue?@action=redirect&bpo=24773]: Implemented PEP 495 [https://peps.python.org/pep-0495/] (Local Time Disambiguation).

Expose the EPOLLEXCLUSIVE constant (when it is defined) in the select module.

bpo-27567 [https://bugs.python.org/issue?@action=redirect&bpo=27567]: Expose the EPOLLRDHUP and POLLRDHUP constants in the select module.

bpo-1621 [https://bugs.python.org/issue?@action=redirect&bpo=1621]: Avoid signed int negation overflow in the "audioop" module.

bpo-27533 [https://bugs.python.org/issue?@action=redirect&bpo=27533]: Release GIL in nt._isdir

bpo-17711 [https://bugs.python.org/issue?@action=redirect&bpo=17711]: Fixed unpickling by the persistent ID with protocol 0. Original patch by Alexandre Vassalotti.

bpo-27522 [https://bugs.python.org/issue?@action=redirect&bpo=27522]: Avoid an unintentional reference cycle in email.feedparser.

bpo-27512 [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.

IDLE

bpo-27714 [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.

bpo-27621 [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.

bpo-27620 [https://bugs.python.org/issue?@action=redirect&bpo=27620]: Escape key now closes Query box as cancelled.

bpo-27609 [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.

bpo-27609 [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.

bpo-25507 [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.

bpo-27173 [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.

bpo-27452 [https://bugs.python.org/issue?@action=redirect&bpo=27452]: add line counter and crc to IDLE configHandler test dump.

Tests

bpo-25805 [https://bugs.python.org/issue?@action=redirect&bpo=25805]: Skip a test in test_pkgutil as needed that doesn't work when __name__ == __main__. Patch by SilentGhost.

bpo-27472 [https://bugs.python.org/issue?@action=redirect&bpo=27472]: Add test.support.unix_shell as the path to the default shell.

bpo-27369 [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.

bpo-27594 [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.

Windows

bpo-27647 [https://bugs.python.org/issue?@action=redirect&bpo=27647]: Update bundled Tcl/Tk to 8.6.6.

bpo-27610 [https://bugs.python.org/issue?@action=redirect&bpo=27610]: Adds PEP 514 [https://peps.python.org/pep-0514/] metadata to Windows installer

bpo-27469 [https://bugs.python.org/issue?@action=redirect&bpo=27469]: Adds a shell extension to the launcher so that drag and drop works correctly.

bpo-27309 [https://bugs.python.org/issue?@action=redirect&bpo=27309]: Enables proper Windows styles in python[w].exe manifest.

Build

bpo-27713 [https://bugs.python.org/issue?@action=redirect&bpo=27713]: Suppress spurious build warnings when updating importlib's bootstrap files. Patch by Xiang Zhang

bpo-25825 [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.

bpo-27453 [https://bugs.python.org/issue?@action=redirect&bpo=27453]: CPP invocation in configure must use CPPFLAGS. Patch by Chi Hsuan Yen.

bpo-27641 [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.

bpo-26662 [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.

bpo-10910 [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.

Python 3.6.0 alpha 3

Release date: 2016-07-11

Security

bpo-27278 [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.

bpo-22636 [https://bugs.python.org/issue?@action=redirect&bpo=22636]: Avoid shell injection problems with ctypes.util.find_library().

Core and Builtins

bpo-27473 [https://bugs.python.org/issue?@action=redirect&bpo=27473]: Fixed possible integer overflow in bytes and bytearray concatenations. Patch by Xiang Zhang.

bpo-23034 [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.

bpo-27443 [https://bugs.python.org/issue?@action=redirect&bpo=27443]: __length_hint__() of bytearray iterators no longer return a negative integer for a resized bytearray.

bpo-27007 [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.

Library

bpo-26844 [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.

bpo-23804 [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.

bpo-27466 [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.

bpo-21708 [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.

bpo-26721 [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.

bpo-22115 [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.

bpo-26243 [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.

bpo-27038 [https://bugs.python.org/issue?@action=redirect&bpo=27038]: Expose the DirEntry type as os.DirEntry. Code patch by Jelle Zijlstra.

bpo-27186 [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.

bpo-18726 [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.

bpo-27319 [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.

bpo-27079 [https://bugs.python.org/issue?@action=redirect&bpo=27079]: Fixed curses.ascii functions isblank(), iscntrl() and ispunct().

bpo-27294 [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.

bpo-27177 [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.

bpo-26754 [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.

bpo-26536 [https://bugs.python.org/issue?@action=redirect&bpo=26536]: socket.ioctl now supports SIO_LOOPBACK_FAST_PATH. Patch by Daniel Stokes.

bpo-27048 [https://bugs.python.org/issue?@action=redirect&bpo=27048]: Prevents distutils failing on Windows when environment variables contain non-ASCII characters

bpo-27330 [https://bugs.python.org/issue?@action=redirect&bpo=27330]: Fixed possible leaks in the ctypes module.

bpo-27238 [https://bugs.python.org/issue?@action=redirect&bpo=27238]: Got rid of bare excepts in the turtle module. Original patch by Jelle Zijlstra.

bpo-27122 [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 PEP 479 [https://peps.python.org/pep-0479/] bug described in issue25782.

bpo-16864 [https://bugs.python.org/issue?@action=redirect&bpo=16864]: sqlite3.Cursor.lastrowid now supports REPLACE statement. Initial patch by Alex LordThorsen.

bpo-26386 [https://bugs.python.org/issue?@action=redirect&bpo=26386]: Fixed ttk.TreeView selection operations with item id's containing spaces.

bpo-8637 [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).

bpo-16182 [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.

bpo-27392 [https://bugs.python.org/issue?@action=redirect&bpo=27392]: Add loop.connect_accepted_socket(). Patch by Jim Fulton.

IDLE

bpo-27477 [https://bugs.python.org/issue?@action=redirect&bpo=27477]: IDLE search dialogs now use ttk widgets.

bpo-27173 [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.

bpo-27452 [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.

bpo-27452 [https://bugs.python.org/issue?@action=redirect&bpo=27452]: add line counter and crc to IDLE configHandler test dump.

bpo-27380 [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.

bpo-27372 [https://bugs.python.org/issue?@action=redirect&bpo=27372]: Test_idle no longer changes the locale.

bpo-27365 [https://bugs.python.org/issue?@action=redirect&bpo=27365]: Allow non-ascii chars in IDLE NEWS.txt, for contributor names.

bpo-27245 [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.

bpo-24137 [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.

bpo-27310 [https://bugs.python.org/issue?@action=redirect&bpo=27310]: Fix IDLE.app failure to launch on OS X due to vestigial import.

C API

bpo-26754 [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.

Build

bpo-28066 [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.

bpo-27442 [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'.

bpo-27434 [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.

bpo-26930 [https://bugs.python.org/issue?@action=redirect&bpo=26930]: Update Windows builds to use OpenSSL 1.0.2h.

bpo-23968 [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.

Don't use largefile support for GNU/Hurd.

Tools/Demos

bpo-27332 [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.

bpo-27418 [https://bugs.python.org/issue?@action=redirect&bpo=27418]: Fixed Tools/importbench/importbench.py.

Documentation

bpo-19489 [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.

bpo-27285 [https://bugs.python.org/issue?@action=redirect&bpo=27285]: Update documentation to reflect the deprecation of pyvenv and normalize on the term "virtual environment". Patch by Steve Piercy.

Tests

bpo-27027 [https://bugs.python.org/issue?@action=redirect&bpo=27027]: Added test.support.is_android that is True when this is an Android build.

Python 3.6.0 alpha 2

Release date: 2016-06-13

Security

bpo-26556 [https://bugs.python.org/issue?@action=redirect&bpo=26556]: Update expat to 2.1.1, fixes CVE-2015-1283 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1283].

Fix TLS stripping vulnerability in smtplib, CVE-2016-0772 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-0772]. Reported by Team Oststrom.

bpo-26839 [https://bugs.python.org/issue?@action=redirect&bpo=26839]: On Linux, os.urandom() now calls getrandom() with GRND_NONBLOCK to fall back on reading /dev/urandom if the urandom entropy pool is not initialized yet. Patch written by Colm Buckley.

Core and Builtins

bpo-27095 [https://bugs.python.org/issue?@action=redirect&bpo=27095]: Simplified MAKE_FUNCTION and removed MAKE_CLOSURE opcodes. Patch by Demur Rumed.

bpo-27190 [https://bugs.python.org/issue?@action=redirect&bpo=27190]: Raise NotSupportedError if sqlite3 is older than 3.3.1. Patch by Dave Sawyer.

bpo-27286 [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.

bpo-27140 [https://bugs.python.org/issue?@action=redirect&bpo=27140]: Added BUILD_CONST_KEY_MAP opcode.

bpo-27186 [https://bugs.python.org/issue?@action=redirect&bpo=27186]: Add support for os.PathLike objects to open() (part of PEP 519 [https://peps.python.org/pep-0519/]).

bpo-27066 [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.

bpo-26983 [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.

bpo-27097 [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.

bpo-26647 [https://bugs.python.org/issue?@action=redirect&bpo=26647]: Python interpreter now uses 16-bit wordcode instead of bytecode. Patch by Demur Rumed.

bpo-23275 [https://bugs.python.org/issue?@action=redirect&bpo=23275]: Allow assigning to an empty target list in round brackets: () = iterable.

bpo-27243 [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.

Library

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.

bpo-27025 [https://bugs.python.org/issue?@action=redirect&bpo=27025]: Generated names for Tkinter widgets are now more meaningful and recognizable.

bpo-25455 [https://bugs.python.org/issue?@action=redirect&bpo=25455]: Fixed crashes in repr of recursive ElementTree.Element and functools.partial objects.

bpo-27294 [https://bugs.python.org/issue?@action=redirect&bpo=27294]: Improved repr for Tkinter event objects.

bpo-20508 [https://bugs.python.org/issue?@action=redirect&bpo=20508]: Improve exception message of IPv{4,6}Network.__getitem__. Patch by Gareth Rees.

bpo-21386 [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.

bpo-27029 [https://bugs.python.org/issue?@action=redirect&bpo=27029]: Removed deprecated support of universal newlines mode from ZipFile.open().

bpo-27030 [https://bugs.python.org/issue?@action=redirect&bpo=27030]: Unknown escapes consisting of '\' and an ASCII letter in regular expressions now are errors. The re.LOCALE flag now can be used only with bytes patterns.

bpo-27186 [https://bugs.python.org/issue?@action=redirect&bpo=27186]: Add os.PathLike support to DirEntry (part of PEP 519 [https://peps.python.org/pep-0519/]). Initial patch by Jelle Zijlstra.

bpo-20900 [https://bugs.python.org/issue?@action=redirect&bpo=20900]: distutils register command now decodes HTTP responses correctly. Initial patch by ingrid.

bpo-27186 [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.

bpo-27186 [https://bugs.python.org/issue?@action=redirect&bpo=27186]: Add support for os.PathLike objects to os.fsencode() and os.fsdecode() (part of PEP 519 [https://peps.python.org/pep-0519/]).

bpo-27186 [https://bugs.python.org/issue?@action=redirect&bpo=27186]: Introduce os.PathLike and os.fspath() (part of PEP 519 [https://peps.python.org/pep-0519/]).

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 PEP 492 [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).

bpo-25738 [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.

bpo-21313 [https://bugs.python.org/issue?@action=redirect&bpo=21313]: Fix the "platform" module to tolerate when sys.version contains truncated build information.

bpo-23883 [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.

bpo-27164 [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.

bpo-24291 [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.

bpo-21272 [https://bugs.python.org/issue?@action=redirect&bpo=21272]: Use _sysconfigdata.py to initialize distutils.sysconfig.

bpo-19611 [https://bugs.python.org/issue?@action=redirect&bpo=19611]: inspect now reports the implicit .0 parameters generated by the compiler for comprehension and generator expression scopes as if they were positional-only parameters called implicit0. Patch by Jelle Zijlstra.

bpo-26809 [https://bugs.python.org/issue?@action=redirect&bpo=26809]: Add __all__ to string. Patch by Emanuel Barry.

bpo-26373 [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.

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.

bpo-27167 [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.

bpo-25931 [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().

bpo-21776 [https://bugs.python.org/issue?@action=redirect&bpo=21776]: distutils.upload now correctly handles HTTPError. Initial patch by Claudiu Popa.

bpo-26526 [https://bugs.python.org/issue?@action=redirect&bpo=26526]: Replace custom parse tree validation in the parser module with a simple DFA validator.

bpo-27114 [https://bugs.python.org/issue?@action=redirect&bpo=27114]: Fix SSLContext._load_windows_store_certs fails with PermissionError

bpo-18383 [https://bugs.python.org/issue?@action=redirect&bpo=18383]: Avoid creating duplicate filters when using filterwarnings and simplefilter. Based on patch by Alex Shkop.

bpo-23026 [https://bugs.python.org/issue?@action=redirect&bpo=23026]: winreg.QueryValueEx() now return an integer for REG_QWORD type.

bpo-26741 [https://bugs.python.org/issue?@action=redirect&bpo=26741]: subprocess.Popen destructor now emits a ResourceWarning warning if the child process is still running.

bpo-27056 [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.

bpo-21271 [https://bugs.python.org/issue?@action=redirect&bpo=21271]: New keyword only parameters in reset_mock call.

IDLE

bpo-5124 [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.

bpo-24750 [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.

bpo-24759 [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.

bpo-27239 [https://bugs.python.org/issue?@action=redirect&bpo=27239]: idlelib.macosx.isXyzTk functions initialize as needed.

bpo-27262 [https://bugs.python.org/issue?@action=redirect&bpo=27262]: move Aqua unbinding code, which enable context menus, to macosx.

bpo-24759 [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.

bpo-27196 [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

bpo-20567 [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.

bpo-24225 [https://bugs.python.org/issue?@action=redirect&bpo=24225]: Update idlelib/README.txt with new file names and event handlers.

bpo-27156 [https://bugs.python.org/issue?@action=redirect&bpo=27156]: Remove obsolete code not used by IDLE.

bpo-27117 [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.

bpo-24225 [https://bugs.python.org/issue?@action=redirect&bpo=24225]: Rename many idlelib/*.py and 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.

bpo-26673 [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.

bpo-21939 [https://bugs.python.org/issue?@action=redirect&bpo=21939]: Add test for IDLE's percolator. Original patch by Saimadhav Heblikar.

bpo-21676 [https://bugs.python.org/issue?@action=redirect&bpo=21676]: Add test for IDLE's replace dialog. Original patch by Saimadhav Heblikar.

bpo-18410 [https://bugs.python.org/issue?@action=redirect&bpo=18410]: Add test for IDLE's search dialog. Original patch by Westley Martínez.

bpo-21703 [https://bugs.python.org/issue?@action=redirect&bpo=21703]: Add test for undo delegator. Patch mostly by Saimadhav Heblikar .

bpo-27044 [https://bugs.python.org/issue?@action=redirect&bpo=27044]: Add ConfigDialog.remove_var_callbacks to stop memory leaks.

bpo-23977 [https://bugs.python.org/issue?@action=redirect&bpo=23977]: Add more asserts to test_delegator.

Documentation

bpo-16484 [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.

bpo-24136 [https://bugs.python.org/issue?@action=redirect&bpo=24136]: Document the new PEP 448 [https://peps.python.org/pep-0448/] unpacking syntax of 3.5.

bpo-22558 [https://bugs.python.org/issue?@action=redirect&bpo=22558]: Add remaining doc links to source code for Python-coded modules. Patch by Yoni Lavi.

Tests

bpo-25285 [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.

bpo-25285 [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.

Windows

bpo-27064 [https://bugs.python.org/issue?@action=redirect&bpo=27064]: The py.exe launcher now defaults to Python 3. The Windows launcher py.exe no longer prefers an installed Python 2 version over Python 3 by default when used interactively.

bpo-17500 [https://bugs.python.org/issue?@action=redirect&bpo=17500]: Remove unused and outdated icons. (See also: https://github.com/python/pythondotorg/issues/945)

Build

bpo-27229 [https://bugs.python.org/issue?@action=redirect&bpo=27229]: Fix the cross-compiling pgen rule for in-tree builds. Patch by Xavier de Gaye.

bpo-26930 [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.

C API

bpo-27186 [https://bugs.python.org/issue?@action=redirect&bpo=27186]: Add the PyOS_FSPath() function (part of PEP 519 [https://peps.python.org/pep-0519/]).

bpo-26282 [https://bugs.python.org/issue?@action=redirect&bpo=26282]: PyArg_ParseTupleAndKeywords() now supports positional-only parameters.

Tools/Demos

bpo-26282 [https://bugs.python.org/issue?@action=redirect&bpo=26282]: Argument Clinic now supports positional-only and keyword parameters in the same function.

Python 3.6.0 alpha 1

Release date: 2016-05-16

Security

bpo-26657 [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.

bpo-26313 [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.

bpo-25939 [https://bugs.python.org/issue?@action=redirect&bpo=25939]: On Windows open the cert store readonly in ssl.enum_certificates.

Core and Builtins

bpo-20041 [https://bugs.python.org/issue?@action=redirect&bpo=20041]: Fixed TypeError when frame.f_trace is set to None. Patch by Xavier de Gaye.

bpo-26168 [https://bugs.python.org/issue?@action=redirect&bpo=26168]: Fixed possible refleaks in failing Py_BuildValue() with the "N" format unit.

bpo-26991 [https://bugs.python.org/issue?@action=redirect&bpo=26991]: Fix possible refleak when creating a function with annotations.

bpo-27039 [https://bugs.python.org/issue?@action=redirect&bpo=27039]: Fixed bytearray.remove() for values greater than 127. Based on patch by Joe Jevnik.

bpo-23640 [https://bugs.python.org/issue?@action=redirect&bpo=23640]: int.from_bytes() no longer bypasses constructors for subclasses.

bpo-27005 [https://bugs.python.org/issue?@action=redirect&bpo=27005]: Optimized the float.fromhex() class method for exact float. It is now 2 times faster.

bpo-18531 [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.

bpo-26811 [https://bugs.python.org/issue?@action=redirect&bpo=26811]: gc.get_objects() no longer contains a broken tuple with NULL pointer.

bpo-20120 [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.

bpo-26249 [https://bugs.python.org/issue?@action=redirect&bpo=26249]: Memory functions of the PyMem_Malloc() domain (PYMEM_DOMAIN_MEM) now use the pymalloc allocator rather than system malloc(). Applications calling PyMem_Malloc() without holding the GIL can now crash: use PYTHONMALLOC=debug environment variable to validate the usage of memory allocators in your application.

bpo-26802 [https://bugs.python.org/issue?@action=redirect&bpo=26802]: Optimize function calls only using unpacking like func(*tuple) (no other positional argument, no keyword): avoid copying the tuple. Patch written by Joe Jevnik.

bpo-26659 [https://bugs.python.org/issue?@action=redirect&bpo=26659]: Make the builtin slice type support cycle collection.

bpo-26718 [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!

bpo-27138 [https://bugs.python.org/issue?@action=redirect&bpo=27138]: Fix the doc comment for FileFinder.find_spec().

bpo-27147 [https://bugs.python.org/issue?@action=redirect&bpo=27147]: Mention PEP 420 [https://peps.python.org/pep-0420/] in the importlib docs.

bpo-25339 [https://bugs.python.org/issue?@action=redirect&bpo=25339]: PYTHONIOENCODING now has priority over locale in setting the error handler for stdin and stdout.

bpo-26494 [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.

bpo-26574 [https://bugs.python.org/issue?@action=redirect&bpo=26574]: Optimize bytes.replace(b'', b'.') and bytearray.replace(b'', b'.'). Patch written by Josh Snider.

bpo-26581 [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.

bpo-19711 [https://bugs.python.org/issue?@action=redirect&bpo=19711]: Add tests for reloading namespace packages.

bpo-21099 [https://bugs.python.org/issue?@action=redirect&bpo=21099]: Switch applicable importlib tests to use PEP 451 [https://peps.python.org/pep-0451/] API.

bpo-26563 [https://bugs.python.org/issue?@action=redirect&bpo=26563]: Debug hooks on Python memory allocators now raise a fatal error if functions of the PyMem_Malloc() family are called without holding the GIL.

bpo-26564 [https://bugs.python.org/issue?@action=redirect&bpo=26564]: On error, the debug hooks on Python memory allocators now use the tracemalloc module to get the traceback where a memory block was allocated.

bpo-26558 [https://bugs.python.org/issue?@action=redirect&bpo=26558]: The debug hooks on Python memory allocator PyObject_Malloc() now detect when functions are called without holding the GIL.

bpo-26516 [https://bugs.python.org/issue?@action=redirect&bpo=26516]: Add PYTHONMALLOC environment variable to set the Python memory allocators and/or install debug hooks.

bpo-26516 [https://bugs.python.org/issue?@action=redirect&bpo=26516]: The PyMem_SetupDebugHooks() function can now also be used on Python compiled in release mode.

bpo-26516 [https://bugs.python.org/issue?@action=redirect&bpo=26516]: The 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.

bpo-26516 [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.

bpo-26464 [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.

bpo-22836 [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.

bpo-26302 [https://bugs.python.org/issue?@action=redirect&bpo=26302]: Correct behavior to reject comma as a legal character for cookie names.

bpo-26136 [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.

bpo-26204 [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, 1.0 is now ignored in def f(): 1.0.

bpo-4806 [https://bugs.python.org/issue?@action=redirect&bpo=4806]: Avoid masking the original TypeError exception when using star (*) unpacking in function calls. Based on patch by Hagen Fürstenau and Daniel Urban.

bpo-26146 [https://bugs.python.org/issue?@action=redirect&bpo=26146]: Add a new kind of AST node: ast.Constant. It can be used by external AST optimizers, but the compiler does not emit directly such node.

bpo-23601 [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.)

bpo-18018 [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.

bpo-25843 [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, f1, f2 = lambda: 1, lambda: 1.0 is now correctly compiled to two different functions: f1() returns 1 (int) and f2() returns 1.0 (float), even if 1 and 1.0 are equal.

bpo-26107 [https://bugs.python.org/issue?@action=redirect&bpo=26107]: The format of the co_lnotab attribute of code objects changes to support negative line number delta.

bpo-26154 [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.

bpo-25791 [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.

bpo-22995 [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.

bpo-25961 [https://bugs.python.org/issue?@action=redirect&bpo=25961]: Disallowed null characters in the type name.

bpo-25973 [https://bugs.python.org/issue?@action=redirect&bpo=25973]: Fix segfault when an invalid nonlocal statement binds a name starting with two underscores.

bpo-22995 [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.

bpo-20440 [https://bugs.python.org/issue?@action=redirect&bpo=20440]: Massive replacing unsafe attribute setting code with special macro Py_SETREF.

bpo-25766 [https://bugs.python.org/issue?@action=redirect&bpo=25766]: Special method __bytes__() now works in str subclasses.

bpo-25421 [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.

bpo-25709 [https://bugs.python.org/issue?@action=redirect&bpo=25709]: Fixed problem with in-place string concatenation and utf-8 cache.

bpo-5319 [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.

bpo-25485 [https://bugs.python.org/issue?@action=redirect&bpo=25485]: telnetlib.Telnet is now a context manager.

bpo-24097 [https://bugs.python.org/issue?@action=redirect&bpo=24097]: Fixed crash in object.__reduce__() if slot name is freed inside __getattr__.

bpo-24731 [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.

bpo-25630 [https://bugs.python.org/issue?@action=redirect&bpo=25630]: Fix a possible segfault during argument parsing in functions that accept filesystem paths.

bpo-23564 [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.

bpo-25388 [https://bugs.python.org/issue?@action=redirect&bpo=25388]: Fixed tokenizer crash when processing undecodable source code with a null byte.

bpo-25462 [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.

bpo-22995 [https://bugs.python.org/issue?@action=redirect&bpo=22995]: Default implementation of __reduce__ and __reduce_ex__ now rejects builtin types with not defined __new__.

bpo-24802 [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.

bpo-25555 [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.

bpo-24726 [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.

bpo-25449 [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.

bpo-25395 [https://bugs.python.org/issue?@action=redirect&bpo=25395]: Fixed crash when highly nested OrderedDict structures were garbage collected.

bpo-25401 [https://bugs.python.org/issue?@action=redirect&bpo=25401]: Optimize bytes.fromhex() and bytearray.fromhex(): they are now between 2x and 3.5x faster.

bpo-25399 [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.

bpo-25274 [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.

bpo-24402 [https://bugs.python.org/issue?@action=redirect&bpo=24402]: Fix input() to prompt to the redirected stdout when sys.stdout.fileno() fails.

bpo-25349 [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.

bpo-24806 [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.

bpo-25301 [https://bugs.python.org/issue?@action=redirect&bpo=25301]: The UTF-8 decoder is now up to 15 times as fast for error handlers: ignore, replace and surrogateescape.

bpo-24848 [https://bugs.python.org/issue?@action=redirect&bpo=24848]: Fixed a number of bugs in UTF-7 decoding of misformed data.

bpo-25267 [https://bugs.python.org/issue?@action=redirect&bpo=25267]: The UTF-8 encoder is now up to 75 times as fast for error handlers: ignore, replace, surrogateescape, surrogatepass. Patch co-written with Serhiy Storchaka.

bpo-25280 [https://bugs.python.org/issue?@action=redirect&bpo=25280]: Import trace messages emitted in verbose (-v) mode are no longer formatted twice.

bpo-25227 [https://bugs.python.org/issue?@action=redirect&bpo=25227]: Optimize ASCII and latin1 encoders with the surrogateescape error handler: the encoders are now up to 3 times as fast. Initial patch written by Serhiy Storchaka.

bpo-25003 [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.

bpo-9232 [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.

bpo-24965 [https://bugs.python.org/issue?@action=redirect&bpo=24965]: Implement PEP 498 [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.

bpo-26478 [https://bugs.python.org/issue?@action=redirect&bpo=26478]: Fix semantic bugs when using binary operators with dictionary views and tuples.

bpo-26171 [https://bugs.python.org/issue?@action=redirect&bpo=26171]: Fix possible integer overflow and heap corruption in zipimporter.get_data().

bpo-25660 [https://bugs.python.org/issue?@action=redirect&bpo=25660]: Fix TAB key behaviour in REPL with readline.

bpo-26288 [https://bugs.python.org/issue?@action=redirect&bpo=26288]: Optimize PyLong_AsDouble.

bpo-26289 [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 [https://bugs.python.org/issue?@action=redirect&bpo=26315])

bpo-25887 [https://bugs.python.org/issue?@action=redirect&bpo=25887]: Raise a RuntimeError when a coroutine object is awaited more than once.

Library

bpo-27057 [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.

bpo-27014 [https://bugs.python.org/issue?@action=redirect&bpo=27014]: Fix infinite recursion using typing.py. Thanks to Kalle Tuure!

bpo-27031 [https://bugs.python.org/issue?@action=redirect&bpo=27031]: Removed dummy methods in Tkinter widget classes: tk_menuBar() and tk_bindForTraversal().

bpo-14132 [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.

bpo-17214 [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.

bpo-27033 [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.

bpo-27034 [https://bugs.python.org/issue?@action=redirect&bpo=27034]: Removed deprecated class asynchat.fifo.

bpo-26870 [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.

bpo-26039 [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.

bpo-26892 [https://bugs.python.org/issue?@action=redirect&bpo=26892]: Honor debuglevel flag in urllib.request.HTTPHandler. Patch contributed by Chi Hsuan Yen.

bpo-22274 [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.

bpo-26807 [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.

bpo-25745 [https://bugs.python.org/issue?@action=redirect&bpo=25745]: Fixed leaking a userptr in curses panel destructor.

bpo-26977 [https://bugs.python.org/issue?@action=redirect&bpo=26977]: Removed unnecessary, and ignored, call to sum of squares helper in statistics.pvariance.

bpo-26002 [https://bugs.python.org/issue?@action=redirect&bpo=26002]: Use bisect in statistics.median instead of a linear search. Patch by Upendra Kuma.

bpo-25974 [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.

bpo-26996 [https://bugs.python.org/issue?@action=redirect&bpo=26996]: Add secrets module as described in PEP 506 [https://peps.python.org/pep-0506/].

bpo-26881 [https://bugs.python.org/issue?@action=redirect&bpo=26881]: The modulefinder module now supports extended opcode arguments.

bpo-23815 [https://bugs.python.org/issue?@action=redirect&bpo=23815]: Fixed crashes related to directly created instances of types in _tkinter and curses.panel modules.

bpo-17765 [https://bugs.python.org/issue?@action=redirect&bpo=17765]: weakref.ref() no longer silently ignores keyword arguments. Patch by Georg Brandl.

bpo-26873 [https://bugs.python.org/issue?@action=redirect&bpo=26873]: xmlrpc now raises ResponseError on unsupported type tags instead of silently return incorrect result.

bpo-26915 [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.

bpo-26711 [https://bugs.python.org/issue?@action=redirect&bpo=26711]: Fixed the comparison of plistlib.Data with other types.

bpo-24114 [https://bugs.python.org/issue?@action=redirect&bpo=24114]: Fix an uninitialized variable in ctypes.util. The bug only occurs on SunOS when the ctypes implementation searches for the crle program. Patch by Xiang Zhang. Tested on SunOS by Kees Bos.

bpo-26864 [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.

bpo-24902 [https://bugs.python.org/issue?@action=redirect&bpo=24902]: Print server URL on http.server startup. Initial patch by Felix Kaiser.

bpo-25788 [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.

bpo-26634 [https://bugs.python.org/issue?@action=redirect&bpo=26634]: recursive_repr() now sets __qualname__ of wrapper. Patch by Xiang Zhang.

bpo-26804 [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.

bpo-26837 [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().

bpo-26041 [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.

bpo-26822 [https://bugs.python.org/issue?@action=redirect&bpo=26822]: itemgetter, attrgetter and methodcaller objects no longer silently ignore keyword arguments.

bpo-26733 [https://bugs.python.org/issue?@action=redirect&bpo=26733]: Disassembling a class now disassembles class and static methods. Patch by Xiang Zhang.

bpo-26801 [https://bugs.python.org/issue?@action=redirect&bpo=26801]: Fix error handling in shutil.get_terminal_size(), catch AttributeError instead of NameError. Patch written by Emanuel Barry.

bpo-24838 [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.

bpo-26717 [https://bugs.python.org/issue?@action=redirect&bpo=26717]: Stop encoding Latin-1-ized WSGI paths with UTF-8. Patch by Anthony Sottile.

bpo-26782 [https://bugs.python.org/issue?@action=redirect&bpo=26782]: Add STARTUPINFO to subprocess.__all__ on Windows.

bpo-26404 [https://bugs.python.org/issue?@action=redirect&bpo=26404]: Add context manager to socketserver. Patch by Aviv Palivoda.

bpo-26735 [https://bugs.python.org/issue?@action=redirect&bpo=26735]: Fix os.urandom() on Solaris 11.3 and newer when reading more than 1,024 bytes: call getrandom() multiple times with a limit of 1024 bytes per call.

bpo-26585 [https://bugs.python.org/issue?@action=redirect&bpo=26585]: Eliminate http.server._quote_html() and use html.escape(quote=False). Patch by Xiang Zhang.

bpo-26685 [https://bugs.python.org/issue?@action=redirect&bpo=26685]: Raise OSError if closing a socket fails.

bpo-16329 [https://bugs.python.org/issue?@action=redirect&bpo=16329]: Add .webm to mimetypes.types_map. Patch by Giampaolo Rodola'.

bpo-13952 [https://bugs.python.org/issue?@action=redirect&bpo=13952]: Add .csv to mimetypes.types_map. Patch by Geoff Wilson.

bpo-26587 [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).

bpo-25609 [https://bugs.python.org/issue?@action=redirect&bpo=25609]: Introduce contextlib.AbstractContextManager and typing.ContextManager.

bpo-26709 [https://bugs.python.org/issue?@action=redirect&bpo=26709]: Fixed Y2038 problem in loading binary PLists.

bpo-23735 [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.

bpo-25951 [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.

bpo-26586 [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.

bpo-26676 [https://bugs.python.org/issue?@action=redirect&bpo=26676]: Added missing XMLPullParser to ElementTree.__all__.

bpo-22854 [https://bugs.python.org/issue?@action=redirect&bpo=22854]: Change BufferedReader.writable() and BufferedWriter.readable() to always return False.

bpo-26492 [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.

bpo-26641 [https://bugs.python.org/issue?@action=redirect&bpo=26641]: doctest.DocFileTest and doctest.testfile() now support packages (module splitted into multiple directories) for the package parameter.

bpo-25195 [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.

bpo-26644 [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().

bpo-23804 [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.

bpo-26616 [https://bugs.python.org/issue?@action=redirect&bpo=26616]: Fixed a bug in datetime.astimezone() method.

bpo-26637 [https://bugs.python.org/issue?@action=redirect&bpo=26637]: The importlib module now emits an ImportError rather than a TypeError if __import__() is tried during the Python shutdown process but sys.path is already cleared (set to None).

bpo-21925 [https://bugs.python.org/issue?@action=redirect&bpo=21925]: warnings.formatwarning() now catches exceptions when calling linecache.getline() and tracemalloc.get_object_traceback() to be able to log ResourceWarning emitted late during the Python shutdown process.

bpo-23848 [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).

bpo-26530 [https://bugs.python.org/issue?@action=redirect&bpo=26530]: Add C functions _PyTraceMalloc_Track() and _PyTraceMalloc_Untrack() to track memory blocks using the tracemalloc module. Add _PyTraceMalloc_GetTraceback() to get the traceback of an object.

bpo-26588 [https://bugs.python.org/issue?@action=redirect&bpo=26588]: The _tracemalloc now supports tracing memory allocations of multiple address spaces (domains).

bpo-24266 [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.

bpo-26590 [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.

bpo-18787 [https://bugs.python.org/issue?@action=redirect&bpo=18787]: spwd.getspnam() now raises a PermissionError if the user doesn't have privileges.

bpo-26560 [https://bugs.python.org/issue?@action=redirect&bpo=26560]: Avoid potential ValueError in BaseHandler.start_response. Initial patch by Peter Inglesby.

bpo-26567 [https://bugs.python.org/issue?@action=redirect&bpo=26567]: Add a new function PyErr_ResourceWarning() function to pass the destroyed object. Add a source attribute to warnings.WarningMessage. Add warnings._showwarnmsg() which uses tracemalloc to get the traceback where source object was allocated.

bpo-26569 [https://bugs.python.org/issue?@action=redirect&bpo=26569]: Fix pyclbr.readmodule() and pyclbr.readmodule_ex() to support importing packages.

bpo-26499 [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.

bpo-25320 [https://bugs.python.org/issue?@action=redirect&bpo=25320]: Handle sockets in directories unittest discovery is scanning. Patch from Victor van den Elzen.

bpo-16181 [https://bugs.python.org/issue?@action=redirect&bpo=16181]: cookiejar.http2time() now returns None if year is higher than datetime.MAXYEAR.

bpo-26513 [https://bugs.python.org/issue?@action=redirect&bpo=26513]: Fixes platform module detection of Windows Server

bpo-23718 [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.

bpo-26323 [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.

bpo-20589 [https://bugs.python.org/issue?@action=redirect&bpo=20589]: Invoking Path.owner() and Path.group() on Windows now raise NotImplementedError instead of ImportError.

bpo-26177 [https://bugs.python.org/issue?@action=redirect&bpo=26177]: Fixed the keys() method for Canvas and Scrollbar widgets.

bpo-15068 [https://bugs.python.org/issue?@action=redirect&bpo=15068]: Got rid of excessive buffering in fileinput. The bufsize parameter is now deprecated and ignored.

bpo-19475 [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.

bpo-2202 [https://bugs.python.org/issue?@action=redirect&bpo=2202]: Fix UnboundLocalError in AbstractDigestAuthHandler.get_algorithm_impls. Initial patch by Mathieu Dupuy.

bpo-26167 [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.

bpo-25718 [https://bugs.python.org/issue?@action=redirect&bpo=25718]: Fixed pickling and copying the accumulate() iterator with total is None.

bpo-26475 [https://bugs.python.org/issue?@action=redirect&bpo=26475]: Fixed debugging output for regular expressions with the (?x) flag.

bpo-26482 [https://bugs.python.org/issue?@action=redirect&bpo=26482]: Allowed pickling recursive dequeues.

bpo-26335 [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.

bpo-26457 [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.

bpo-26385 [https://bugs.python.org/issue?@action=redirect&bpo=26385]: Remove the file if the internal open() call in NamedTemporaryFile() fails. Patch by Silent Ghost.

bpo-26402 [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.

bpo-25913 [https://bugs.python.org/issue?@action=redirect&bpo=25913]: Leading <~ is optional now in base64.a85decode() with adobe=True. Patch by Swati Jaiswal.

bpo-26186 [https://bugs.python.org/issue?@action=redirect&bpo=26186]: Remove an invalid type check in importlib.util.LazyLoader.

bpo-26367 [https://bugs.python.org/issue?@action=redirect&bpo=26367]: importlib.__import__() raises ImportError like builtins.__import__() when level is specified but without an accompanying package specified.

bpo-26309 [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.

bpo-23430 [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.

bpo-25995 [https://bugs.python.org/issue?@action=redirect&bpo=25995]: os.walk() no longer uses FDs proportional to the tree depth.

bpo-25994 [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.

bpo-23992 [https://bugs.python.org/issue?@action=redirect&bpo=23992]: multiprocessing: make MapResult not fail-fast upon exception.

bpo-26243 [https://bugs.python.org/issue?@action=redirect&bpo=26243]: Support keyword arguments to zlib.compress(). Patch by Aviv Palivoda.

bpo-26117 [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.

bpo-25949 [https://bugs.python.org/issue?@action=redirect&bpo=25949]: __dict__ for an OrderedDict instance is now created only when needed.

bpo-25911 [https://bugs.python.org/issue?@action=redirect&bpo=25911]: Restored support of bytes paths in os.walk() on Windows.

bpo-26045 [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.

bpo-26039 [https://bugs.python.org/issue?@action=redirect&bpo=26039]: Added zipfile.ZipInfo.from_file() and zipinfo.ZipInfo.is_dir(). Patch by Thomas Kluyver.

bpo-12923 [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.

bpo-25945 [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.

bpo-26202 [https://bugs.python.org/issue?@action=redirect&bpo=26202]: copy.deepcopy() now correctly copies range() objects with non-atomic attributes.

bpo-23076 [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.

bpo-19883 [https://bugs.python.org/issue?@action=redirect&bpo=19883]: Fixed possible integer overflows in zipimport.

bpo-26227 [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.

bpo-26099 [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.

bpo-26147 [https://bugs.python.org/issue?@action=redirect&bpo=26147]: xmlrpc now works with strings not encodable with used non-UTF-8 encoding.

bpo-25935 [https://bugs.python.org/issue?@action=redirect&bpo=25935]: Garbage collector now breaks reference loops with OrderedDict.

bpo-16620 [https://bugs.python.org/issue?@action=redirect&bpo=16620]: Fixed AttributeError in msilib.Directory.glob().

bpo-26013 [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).

bpo-26129 [https://bugs.python.org/issue?@action=redirect&bpo=26129]: Deprecated accepting non-integers in grp.getgrgid().

bpo-25850 [https://bugs.python.org/issue?@action=redirect&bpo=25850]: Use cross-compilation by default for 64-bit Windows.

bpo-25822 [https://bugs.python.org/issue?@action=redirect&bpo=25822]: Add docstrings to the fields of urllib.parse results. Patch contributed by Swati Jaiswal.

bpo-22642 [https://bugs.python.org/issue?@action=redirect&bpo=22642]: Convert trace module option parsing mechanism to argparse. Patch contributed by SilentGhost.

bpo-24705 [https://bugs.python.org/issue?@action=redirect&bpo=24705]: Fix sysconfig._parse_makefile not expanding ${} vars appearing before $() vars.

bpo-26069 [https://bugs.python.org/issue?@action=redirect&bpo=26069]: Remove the deprecated apis in the trace module.

bpo-22138 [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.

bpo-25672 [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.

bpo-26012 [https://bugs.python.org/issue?@action=redirect&bpo=26012]: Don't traverse into symlinks for ** pattern in pathlib.Path.[r]glob().

bpo-24120 [https://bugs.python.org/issue?@action=redirect&bpo=24120]: Ignore PermissionError when traversing a tree with pathlib.Path.[r]glob(). Patch by Ulrich Petri.

bpo-21815 [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.

bpo-25447 [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).

bpo-25971 [https://bugs.python.org/issue?@action=redirect&bpo=25971]: Optimized creating Fractions from floats by 2 times and from Decimals by 3 times.

bpo-25802 [https://bugs.python.org/issue?@action=redirect&bpo=25802]: Document as deprecated the remaining implementations of importlib.abc.Loader.load_module().

bpo-25928 [https://bugs.python.org/issue?@action=redirect&bpo=25928]: Add Decimal.as_integer_ratio().

bpo-25447 [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).

bpo-25768 [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.

bpo-24103 [https://bugs.python.org/issue?@action=redirect&bpo=24103]: Fixed possible use after free in ElementTree.XMLPullParser.

bpo-25860 [https://bugs.python.org/issue?@action=redirect&bpo=25860]: os.fwalk() no longer skips remaining directories when error occurs. Original patch by Samson Lee.

bpo-25914 [https://bugs.python.org/issue?@action=redirect&bpo=25914]: Fixed and simplified OrderedDict.__sizeof__.

bpo-25869 [https://bugs.python.org/issue?@action=redirect&bpo=25869]: Optimized deepcopying ElementTree; it is now 20 times faster.

bpo-25873 [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.

bpo-25902 [https://bugs.python.org/issue?@action=redirect&bpo=25902]: Fixed various refcount issues in ElementTree iteration.

bpo-22227 [https://bugs.python.org/issue?@action=redirect&bpo=22227]: The TarFile iterator is reimplemented using generator. This implementation is simpler that using class.

bpo-25638 [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.

bpo-25761 [https://bugs.python.org/issue?@action=redirect&bpo=25761]: Improved detecting errors in broken pickle data.

bpo-25717 [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.

bpo-24903 [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.

bpo-25764 [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.

bpo-25771 [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.

bpo-6478 [https://bugs.python.org/issue?@action=redirect&bpo=6478]: _strptime's regexp cache now is reset after changing timezone with time.tzset().

bpo-14285 [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.

bpo-19771 [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 *.pyc file).

bpo-25177 [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.

bpo-25718 [https://bugs.python.org/issue?@action=redirect&bpo=25718]: Fixed copying object with state with boolean value is false.

bpo-10131 [https://bugs.python.org/issue?@action=redirect&bpo=10131]: Fixed deep copying of minidom documents. Based on patch by Marian Ganisin.

bpo-7990 [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.

bpo-25725 [https://bugs.python.org/issue?@action=redirect&bpo=25725]: Fixed a reference leak in pickle.loads() when unpickling invalid data including tuple instructions.

bpo-25663 [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.

bpo-25688 [https://bugs.python.org/issue?@action=redirect&bpo=25688]: Fixed file leak in ElementTree.iterparse() raising an error.

bpo-23914 [https://bugs.python.org/issue?@action=redirect&bpo=23914]: Fixed SystemError raised by unpickler on broken pickle data.

bpo-25691 [https://bugs.python.org/issue?@action=redirect&bpo=25691]: Fixed crash on deleting ElementTree.Element attributes.

bpo-25624 [https://bugs.python.org/issue?@action=redirect&bpo=25624]: ZipFile now always writes a ZIP_STORED header for directory entries. Patch by Dingyuan Wang.

bpo-25626 [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.

bpo-25583 [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.

bpo-25593 [https://bugs.python.org/issue?@action=redirect&bpo=25593]: Change semantics of EventLoop.stop() in asyncio.

bpo-6973 [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.

bpo-23883 [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.

bpo-25590 [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.

bpo-25498 [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.

bpo-25584 [https://bugs.python.org/issue?@action=redirect&bpo=25584]: Added "escape" to the __all__ list in the glob module.

bpo-25584 [https://bugs.python.org/issue?@action=redirect&bpo=25584]: Fixed recursive glob() with patterns starting with **.

bpo-25446 [https://bugs.python.org/issue?@action=redirect&bpo=25446]: Fix regression in smtplib's AUTH LOGIN support.

bpo-18010 [https://bugs.python.org/issue?@action=redirect&bpo=18010]: Fix the pydoc web server's module search function to handle exceptions from importing packages.

bpo-25554 [https://bugs.python.org/issue?@action=redirect&bpo=25554]: Got rid of circular references in regular expression parsing.

bpo-18973 [https://bugs.python.org/issue?@action=redirect&bpo=18973]: Command-line interface of the calendar module now uses argparse instead of optparse.

bpo-25510 [https://bugs.python.org/issue?@action=redirect&bpo=25510]: fileinput.FileInput.readline() now returns b'' instead of '' at the end if the FileInput was opened with binary mode. Patch by Ryosuke Ito.

bpo-25503 [https://bugs.python.org/issue?@action=redirect&bpo=25503]: Fixed inspect.getdoc() for inherited docstrings of properties. Original patch by John Mark Vandenberg.

bpo-25515 [https://bugs.python.org/issue?@action=redirect&bpo=25515]: Always use os.urandom as a source of randomness in uuid.uuid4.

bpo-21827 [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.

bpo-25447 [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).

bpo-25390 [https://bugs.python.org/issue?@action=redirect&bpo=25390]: typing: Don't crash on Union[str, Pattern].

bpo-25441 [https://bugs.python.org/issue?@action=redirect&bpo=25441]: asyncio: Raise error from drain() when socket is closed.

bpo-25410 [https://bugs.python.org/issue?@action=redirect&bpo=25410]: Cleaned up and fixed minor bugs in C implementation of OrderedDict.

bpo-25411 [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.

Move the imp module from a PendingDeprecationWarning to DeprecationWarning.

bpo-25407 [https://bugs.python.org/issue?@action=redirect&bpo=25407]: Remove mentions of the formatter module being removed in Python 3.6.

bpo-25406 [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.

bpo-25382 [https://bugs.python.org/issue?@action=redirect&bpo=25382]: pickletools.dis() now outputs implicit memo index for the MEMOIZE opcode.

bpo-25357 [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.

bpo-24164 [https://bugs.python.org/issue?@action=redirect&bpo=24164]: Objects that need calling __new__ with keyword arguments, can now be pickled using pickle protocols older than protocol version 4.

bpo-25364 [https://bugs.python.org/issue?@action=redirect&bpo=25364]: zipfile now works in threads disabled builds.

bpo-25328 [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.

bpo-16099 [https://bugs.python.org/issue?@action=redirect&bpo=16099]: RobotFileParser now supports Crawl-delay and Request-rate extensions. Patch by Nikolay Bogoychev.

bpo-25316 [https://bugs.python.org/issue?@action=redirect&bpo=25316]: distutils raises OSError instead of DistutilsPlatformError when MSVC is not installed.

bpo-25380 [https://bugs.python.org/issue?@action=redirect&bpo=25380]: Fixed protocol for the STACK_GLOBAL opcode in pickletools.opcodes.

bpo-23972 [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.

bpo-25304 [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.

bpo-25232 [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.

bpo-24657 [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.

bpo-25287 [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.

bpo-23600 [https://bugs.python.org/issue?@action=redirect&bpo=23600]: Default implementation of tzinfo.fromutc() was returning wrong results in some cases.

bpo-25203 [https://bugs.python.org/issue?@action=redirect&bpo=25203]: Failed readline.set_completer_delims() no longer left the module in inconsistent state.

bpo-25011 [https://bugs.python.org/issue?@action=redirect&bpo=25011]: rlcompleter now omits private and special attribute names unless the prefix starts with underscores.

bpo-25209 [https://bugs.python.org/issue?@action=redirect&bpo=25209]: rlcompleter now can add a space or a colon after completed keyword.

bpo-22241 [https://bugs.python.org/issue?@action=redirect&bpo=22241]: timezone.utc name is now plain 'UTC', not 'UTC-00:00'.

bpo-23517 [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).

bpo-23552 [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.

bpo-24633 [https://bugs.python.org/issue?@action=redirect&bpo=24633]: site-packages/README -> README.txt.

bpo-24879 [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.

bpo-24874 [https://bugs.python.org/issue?@action=redirect&bpo=24874]: Improve speed of itertools.cycle() and make its pickle more compact.

Fix crash in itertools.cycle.__setstate__() when the first argument wasn't a list.

bpo-20059 [https://bugs.python.org/issue?@action=redirect&bpo=20059]: urllib.parse raises ValueError on all invalid ports. Patch by Martin Panter.

bpo-24360 [https://bugs.python.org/issue?@action=redirect&bpo=24360]: Improve __repr__ of argparse.Namespace() for invalid identifiers. Patch by Matthias Bussonnier.

bpo-23426 [https://bugs.python.org/issue?@action=redirect&bpo=23426]: run_setup was broken in distutils. Patch from Alexander Belopolsky.

bpo-13938 [https://bugs.python.org/issue?@action=redirect&bpo=13938]: 2to3 converts StringTypes to a tuple. Patch from Mark Hammond.

bpo-2091 [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.

bpo-8585 [https://bugs.python.org/issue?@action=redirect&bpo=8585]: improved tests for zipimporter2. Patch from Mark Lawrence.

bpo-18622 [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.

bpo-24426 [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.

bpo-23661 [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

bpo-13248 [https://bugs.python.org/issue?@action=redirect&bpo=13248]: Remove deprecated inspect.getmoduleinfo function.

bpo-25578 [https://bugs.python.org/issue?@action=redirect&bpo=25578]: Fix (another) memory leak in SSLSocket.getpeercer().

bpo-25530 [https://bugs.python.org/issue?@action=redirect&bpo=25530]: Disable the vulnerable SSLv3 protocol by default when creating ssl.SSLContext.

bpo-25569 [https://bugs.python.org/issue?@action=redirect&bpo=25569]: Fix memory leak in SSLSocket.getpeercert().

bpo-25471 [https://bugs.python.org/issue?@action=redirect&bpo=25471]: Sockets returned from accept() shouldn't appear to be nonblocking.

bpo-25319 [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.

Skip getaddrinfo if host is already resolved. Patch by A. Jesse Jiryu Davis.

bpo-26050 [https://bugs.python.org/issue?@action=redirect&bpo=26050]: Add asyncio.StreamReader.readuntil() method. Patch by Марк Коренберг.

bpo-25924 [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.

bpo-26406 [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.

bpo-26848 [https://bugs.python.org/issue?@action=redirect&bpo=26848]: Fix asyncio/subprocess.communicate() to handle empty input. Patch by Jack O'Connor.

bpo-27040 [https://bugs.python.org/issue?@action=redirect&bpo=27040]: Add loop.get_exception_handler method

bpo-27041 [https://bugs.python.org/issue?@action=redirect&bpo=27041]: asyncio: Add loop.create_future method

IDLE

bpo-20640 [https://bugs.python.org/issue?@action=redirect&bpo=20640]: Add tests for idlelib.configHelpSourceEdit. Patch by Saimadhav Heblikar.

In the 'IDLE-console differences' section of the IDLE doc, clarify how running with IDLE affects sys.modules and the standard streams.

bpo-25507 [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.

bpo-25905 [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'.

bpo-15348 [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.

bpo-24455 [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.

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.

bpo-24750 [https://bugs.python.org/issue?@action=redirect&bpo=24750]: Improve the appearance of the IDLE editor window status bar. Patch by Mark Roseman.

bpo-25313 [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.

bpo-24782 [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.

bpo-22726 [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.

bpo-24820 [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.

bpo-25224 [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'.

bpo-24820 [https://bugs.python.org/issue?@action=redirect&bpo=24820]: Users can now set breakpoint colors in Settings -> Custom Highlighting. Original patch by Mark Roseman.

bpo-24972 [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.

bpo-24570 [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.

bpo-24988 [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.

bpo-24801 [https://bugs.python.org/issue?@action=redirect&bpo=24801]: Make right-click for context menu work on Mac Aqua. Patch by Mark Roseman.

bpo-25173 [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.

bpo-25198 [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.

bpo-25225 [https://bugs.python.org/issue?@action=redirect&bpo=25225]: Condense and rewrite Idle doc section on text colors.

bpo-21995 [https://bugs.python.org/issue?@action=redirect&bpo=21995]: Explain some differences between IDLE and console Python.

bpo-22820 [https://bugs.python.org/issue?@action=redirect&bpo=22820]: Explain need for print when running file from Idle editor.

bpo-25224 [https://bugs.python.org/issue?@action=redirect&bpo=25224]: Doc: augment Idle feature list and no-subprocess section.

bpo-25219 [https://bugs.python.org/issue?@action=redirect&bpo=25219]: Update doc for Idle command line options. Some were missing and notes were not correct.

bpo-24861 [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__.

bpo-25199 [https://bugs.python.org/issue?@action=redirect&bpo=25199]: Idle: add synchronization comments for future maintainers.

bpo-16893 [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.

bpo-24199 [https://bugs.python.org/issue?@action=redirect&bpo=24199]: Deprecate unused idlelib.idlever with possible removal in 3.6.

bpo-24790 [https://bugs.python.org/issue?@action=redirect&bpo=24790]: Remove extraneous code (which also create 2 & 3 conflicts).

Documentation

bpo-26736 [https://bugs.python.org/issue?@action=redirect&bpo=26736]: Used HTTPS for external links in the documentation if possible.

bpo-6953 [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.

bpo-23606 [https://bugs.python.org/issue?@action=redirect&bpo=23606]: Adds note to ctypes documentation regarding cdll.msvcrt.

bpo-24952 [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.

bpo-26014 [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

Tests

bpo-21916 [https://bugs.python.org/issue?@action=redirect&bpo=21916]: Added tests for the turtle module. Patch by ingrid, Gregory Loyse and Jelle Zijlstra.

bpo-26295 [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.

bpo-26523 [https://bugs.python.org/issue?@action=redirect&bpo=26523]: The multiprocessing thread pool (multiprocessing.dummy.Pool) was untested.

bpo-26015 [https://bugs.python.org/issue?@action=redirect&bpo=26015]: Added new tests for pickling iterators of mutable sequences.

bpo-26325 [https://bugs.python.org/issue?@action=redirect&bpo=26325]: Added test.support.check_no_resource_warning() to check that no ResourceWarning is emitted.

bpo-25940 [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.

bpo-25616 [https://bugs.python.org/issue?@action=redirect&bpo=25616]: Tests for OrderedDict are extracted from test_collections into separate file test_ordered_dict.

bpo-25449 [https://bugs.python.org/issue?@action=redirect&bpo=25449]: Added tests for OrderedDict subclasses.

bpo-25188 [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.

bpo-22806 [https://bugs.python.org/issue?@action=redirect&bpo=22806]: Add python -m test --list-tests command to list tests.

bpo-18174 [https://bugs.python.org/issue?@action=redirect&bpo=18174]: python -m test --huntrleaks ... now also checks for leak of file descriptors. Patch written by Richard Oudkerk.

bpo-25260 [https://bugs.python.org/issue?@action=redirect&bpo=25260]: Fix python -m test --coverage on Windows. Remove the list of ignored directories.

PCbuild\rt.bat now accepts an unlimited number of arguments to pass along to regrtest.py. Previously there was a limit of 9.

bpo-26583 [https://bugs.python.org/issue?@action=redirect&bpo=26583]: Skip test_timestamp_overflow in test_import if bytecode files cannot be written.

Build

bpo-21277 [https://bugs.python.org/issue?@action=redirect&bpo=21277]: Don't try to link _ctypes with a ffi_convenience library.

bpo-26884 [https://bugs.python.org/issue?@action=redirect&bpo=26884]: Fix linking extension modules for cross builds. Patch by Xavier de Gaye.

bpo-26932 [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.

bpo-22359 [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.

bpo-21668 [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.

bpo-25702 [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.

bpo-26624 [https://bugs.python.org/issue?@action=redirect&bpo=26624]: Adds validation of ucrtbase[d].dll version with warning for old versions.

bpo-17603 [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.

bpo-26079 [https://bugs.python.org/issue?@action=redirect&bpo=26079]: Fixing the build output folder for tix-8.4.3.6. Patch by Bjoern Thiel.

bpo-26465 [https://bugs.python.org/issue?@action=redirect&bpo=26465]: Update Windows builds to use OpenSSL 1.0.2g.

bpo-25348 [https://bugs.python.org/issue?@action=redirect&bpo=25348]: Added --pgo and --pgo-job arguments to PCbuild\build.bat for building with Profile-Guided Optimization. The old PCbuild\build_pgo.bat script is removed.

bpo-25827 [https://bugs.python.org/issue?@action=redirect&bpo=25827]: Add support for building with ICC to configure, including a new --with-icc flag.

bpo-25696 [https://bugs.python.org/issue?@action=redirect&bpo=25696]: Fix installation of Python on UNIX with make -j9.

bpo-24986 [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.

bpo-24421 [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.

bpo-26465 [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.

bpo-26268 [https://bugs.python.org/issue?@action=redirect&bpo=26268]: Update Windows builds to use OpenSSL 1.0.2f.

bpo-25136 [https://bugs.python.org/issue?@action=redirect&bpo=25136]: Support Apple Xcode 7's new textual SDK stub libraries.

bpo-24324 [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.

Windows

bpo-27053 [https://bugs.python.org/issue?@action=redirect&bpo=27053]: Updates make_zip.py to correctly generate library ZIP file.

bpo-26268 [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).

bpo-26071 [https://bugs.python.org/issue?@action=redirect&bpo=26071]: bdist_wininst created binaries fail to start and find 32bit Python

bpo-26073 [https://bugs.python.org/issue?@action=redirect&bpo=26073]: Update the list of magic numbers in launcher

bpo-26065 [https://bugs.python.org/issue?@action=redirect&bpo=26065]: Excludes venv from library when generating embeddable distro.

bpo-25022 [https://bugs.python.org/issue?@action=redirect&bpo=25022]: Removed very outdated PC/example_nt/ directory.

Tools/Demos

bpo-26799 [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.

bpo-26271 [https://bugs.python.org/issue?@action=redirect&bpo=26271]: Fix the Freeze tool to properly use flags passed through configure. Patch by Daniel Shaulov.

bpo-26489 [https://bugs.python.org/issue?@action=redirect&bpo=26489]: Add dictionary unpacking support to Tools/parser/unparse.py. Patch by Guo Ci Teo.

bpo-26316 [https://bugs.python.org/issue?@action=redirect&bpo=26316]: Fix variable name typo in Argument Clinic.

bpo-25440 [https://bugs.python.org/issue?@action=redirect&bpo=25440]: Fix output of python-config --extension-suffix.

bpo-25154 [https://bugs.python.org/issue?@action=redirect&bpo=25154]: The pyvenv script has been deprecated in favour of python3 -m venv.

C API

bpo-26312 [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.

bpo-26198 [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.

Python 3.5.5 final

Release date: 2018-02-04

There were no new changes in version 3.5.5.

Python 3.5.5 release candidate 1

Release date: 2018-01-23

Security

bpo-32551 [https://bugs.python.org/issue?@action=redirect&bpo=32551]: The sys.path[0] initialization change for bpo-29139 [https://bugs.python.org/issue?@action=redirect&bpo=29139] caused a regression by revealing an inconsistency in how sys.path is initialized when executing __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 sys.path, and ensures no other sys.path entries are inadvertently modified when inserting the import location named on the command line. (Originally reported as bpo-29723 [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)

bpo-30657 [https://bugs.python.org/issue?@action=redirect&bpo=30657]: Fixed possible integer overflow in PyBytes_DecodeEscape, CVE-2017-1000158 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-1000158]. Original patch by Jay Bosamiya; rebased to Python 3 by Miro Hrončok.

bpo-30947 [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.

Core and Builtins

bpo-31095 [https://bugs.python.org/issue?@action=redirect&bpo=31095]: Fix potential crash during GC caused by tp_dealloc which doesn't call PyObject_GC_UnTrack().

Library

bpo-32072 [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.

bpo-31170 [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): https://github.com/libexpat/libexpat/issues/115

Python 3.5.4 final

Release date: 2017-08-07

Library

bpo-30119 [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.

Python 3.5.4 release candidate 1

Release date: 2017-07-23

Security

bpo-30730 [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.

bpo-30694 [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: CVE-2017-9233 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-9233] (External entity infinite loop DoS), CVE-2016-9063 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-9063] (Integer overflow, re-fix), CVE-2016-0718 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-0718] (Fix regression bugs from 2.2.0's fix to CVE-2016-0718 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-0718]) and CVE-2012-0876 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2012-0876] (Counter hash flooding with SipHash). Note: the CVE-2016-5300 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=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 XML_SetHashSalt().

bpo-30500 [https://bugs.python.org/issue?@action=redirect&bpo=30500]: Fix urllib.parse.splithost() to correctly parse fragments. For example, splithost('//127.0.0.1#@evil.com/') now correctly returns the 127.0.0.1 host, instead of treating @evil.com as the host in an authentication (login@host).

bpo-29591 [https://bugs.python.org/issue?@action=redirect&bpo=29591]: Update expat copy from 2.1.1 to 2.2.0 to get fixes of CVE-2016-0718 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-0718] and CVE-2016-4472 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-4472]. See https://sourceforge.net/p/expat/bugs/537/ for more information.

Core and Builtins

bpo-30876 [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.

bpo-30765 [https://bugs.python.org/issue?@action=redirect&bpo=30765]: Avoid blocking in pthread_mutex_lock() when PyThread_acquire_lock() is asked not to block.

bpo-27945 [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.

bpo-25794 [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.

bpo-29935 [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.

bpo-28876 [https://bugs.python.org/issue?@action=redirect&bpo=28876]: bool(range) works even if len(range) raises OverflowError.

bpo-29600 [https://bugs.python.org/issue?@action=redirect&bpo=29600]: Fix wrapping coroutine return values in StopIteration.

bpo-29537 [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.

bpo-28598 [https://bugs.python.org/issue?@action=redirect&bpo=28598]: Support __rmod__ for subclasses of str being called before str.__mod__. Patch by Martijn Pieters.

bpo-29602 [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.

bpo-29347 [https://bugs.python.org/issue?@action=redirect&bpo=29347]: Fixed possibly dereferencing undefined pointers when creating weakref objects.

bpo-29438 [https://bugs.python.org/issue?@action=redirect&bpo=29438]: Fixed use-after-free problem in key sharing dict.

bpo-29319 [https://bugs.python.org/issue?@action=redirect&bpo=29319]: Prevent RunMainFromImporter overwriting sys.path[0].

bpo-29337 [https://bugs.python.org/issue?@action=redirect&bpo=29337]: Fixed possible BytesWarning when compare the code objects. Warnings could be emitted at compile time.

bpo-29478 [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.

Library

bpo-29403 [https://bugs.python.org/issue?@action=redirect&bpo=29403]: Fix unittest.mock's autospec to not fail on method-bound builtin functions. Patch by Aaron Gallagher.

bpo-30961 [https://bugs.python.org/issue?@action=redirect&bpo=30961]: Fix decrementing a borrowed reference in tracemalloc.

bpo-30886 [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.

bpo-29854 [https://bugs.python.org/issue?@action=redirect&bpo=29854]: Fix segfault in readline when using readline's history-size option. Patch by Nir Soffer.

bpo-30807 [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.

bpo-30441 [https://bugs.python.org/issue?@action=redirect&bpo=30441]: Fix bug when modifying os.environ while iterating over it

bpo-30532 [https://bugs.python.org/issue?@action=redirect&bpo=30532]: Fix email header value parser dropping folding white space in certain cases.

bpo-29169 [https://bugs.python.org/issue?@action=redirect&bpo=29169]: Update zlib to 1.2.11.

bpo-30879 [https://bugs.python.org/issue?@action=redirect&bpo=30879]: os.listdir() and os.scandir() now emit bytes names when called with bytes-like argument.

bpo-30746 [https://bugs.python.org/issue?@action=redirect&bpo=30746]: Prohibited the '=' character in environment variable names in os.putenv() and os.spawn*().

bpo-29755 [https://bugs.python.org/issue?@action=redirect&bpo=29755]: Fixed the lgettext() family of functions in the gettext module. They now always return bytes.

bpo-30645 [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.

bpo-23890 [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.

bpo-30149 [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.

bpo-29931 [https://bugs.python.org/issue?@action=redirect&bpo=29931]: Fixed comparison check for ipaddress.ip_interface objects. Patch by Sanjay Sundaresan.

bpo-24484 [https://bugs.python.org/issue?@action=redirect&bpo=24484]: Avoid race condition in multiprocessing cleanup.

bpo-28994 [https://bugs.python.org/issue?@action=redirect&bpo=28994]: The traceback no longer displayed for SystemExit raised in a callback registered by atexit.

bpo-30508 [https://bugs.python.org/issue?@action=redirect&bpo=30508]: Don't log exceptions if Task/Future "cancel()" method was called.

bpo-28556 [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

bpo-29870 [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.

bpo-29743 [https://bugs.python.org/issue?@action=redirect&bpo=29743]: Closing transport during handshake process leaks open socket. Patch by Nikolay Kim

bpo-27585 [https://bugs.python.org/issue?@action=redirect&bpo=27585]: Fix waiter cancellation in asyncio.Lock. Patch by Mathieu Sornay.

bpo-30418 [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.

bpo-30378 [https://bugs.python.org/issue?@action=redirect&bpo=30378]: Fix the problem that logging.handlers.SysLogHandler cannot handle IPv6 addresses.

bpo-29960 [https://bugs.python.org/issue?@action=redirect&bpo=29960]: Preserve generator state when _random.Random.setstate() raises an exception. Patch by Bryan Olson.

bpo-30414 [https://bugs.python.org/issue?@action=redirect&bpo=30414]: multiprocessing.Queue._feed background running thread do not break from main loop on exception.

bpo-30003 [https://bugs.python.org/issue?@action=redirect&bpo=30003]: Fix handling escape characters in HZ codec. Based on patch by Ma Lin.

bpo-30301 [https://bugs.python.org/issue?@action=redirect&bpo=30301]: Fix AttributeError when using SimpleQueue.empty() under spawn and forkserver start methods.

bpo-30329 [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.

bpo-30375 [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.

bpo-30048 [https://bugs.python.org/issue?@action=redirect&bpo=30048]: Fixed Task.cancel() can be ignored when the task is running coroutine and the coroutine returned without any more await.

bpo-29990 [https://bugs.python.org/issue?@action=redirect&bpo=29990]: Fix range checking in GB18030 decoder. Original patch by Ma Lin.

bpo-26293 [https://bugs.python.org/issue?@action=redirect&bpo=26293]: Change resulted because of zipfile breakage. (See also: bpo-29094 [https://bugs.python.org/issue?@action=redirect&bpo=29094])

bpo-30243 [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.

bpo-30185 [https://bugs.python.org/issue?@action=redirect&bpo=30185]: Avoid KeyboardInterrupt tracebacks in forkserver helper process when Ctrl-C is received.

bpo-28556 [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.

bpo-30205 [https://bugs.python.org/issue?@action=redirect&bpo=30205]: Fix getsockname() for unbound AF_UNIX sockets on Linux.

bpo-30070 [https://bugs.python.org/issue?@action=redirect&bpo=30070]: Fixed leaks and crashes in errors handling in the parser module.

bpo-30061 [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().

bpo-30068 [https://bugs.python.org/issue?@action=redirect&bpo=30068]: _io._IOBase.readlines will check if it's closed first when hint is present.

bpo-29694 [https://bugs.python.org/issue?@action=redirect&bpo=29694]: Fixed race condition in pathlib mkdir with flags parents=True. Patch by Armin Rigo.

bpo-29692 [https://bugs.python.org/issue?@action=redirect&bpo=29692]: Fixed arbitrary unchaining of RuntimeError exceptions in contextlib.contextmanager. Patch by Siddharth Velankar.

bpo-29998 [https://bugs.python.org/issue?@action=redirect&bpo=29998]: Pickling and copying ImportError now preserves name and path attributes.

bpo-29942 [https://bugs.python.org/issue?@action=redirect&bpo=29942]: Fix a crash in itertools.chain.from_iterable when encountering long runs of empty iterables.

bpo-27863 [https://bugs.python.org/issue?@action=redirect&bpo=27863]: Fixed multiple crashes in ElementTree caused by race conditions and wrong types.

bpo-28699 [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.

bpo-25803 [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.

bpo-29861 [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.

bpo-29884 [https://bugs.python.org/issue?@action=redirect&bpo=29884]: faulthandler: Restore the old sigaltstack during teardown. Patch by Christophe Zeitouny.

bpo-25455 [https://bugs.python.org/issue?@action=redirect&bpo=25455]: Fixed crashes in repr of recursive buffered file-like objects.

bpo-29800 [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.

bpo-29742 [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.

bpo-8256 [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.

bpo-28298 [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.

bpo-29615 [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.

bpo-29704 [https://bugs.python.org/issue?@action=redirect&bpo=29704]: asyncio.subprocess.SubprocessStreamProtocol no longer closes before all pipes are closed.

bpo-29703 [https://bugs.python.org/issue?@action=redirect&bpo=29703]: Fix asyncio to support instantiation of new event loops in child processes.

bpo-29376 [https://bugs.python.org/issue?@action=redirect&bpo=29376]: Fix assertion error in threading._DummyThread.is_alive().

bpo-29110 [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.

bpo-28961 [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.

bpo-29532 [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.

bpo-28556 [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.

bpo-29100 [https://bugs.python.org/issue?@action=redirect&bpo=29100]: Fix datetime.fromtimestamp() regression introduced in Python 3.6.0: check minimum and maximum years.

bpo-29519 [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.

bpo-29416 [https://bugs.python.org/issue?@action=redirect&bpo=29416]: Prevent infinite loop in pathlib.Path.mkdir

bpo-29444 [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.

bpo-29335 [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).

bpo-29290 [https://bugs.python.org/issue?@action=redirect&bpo=29290]: Fix a regression in argparse that help messages would wrap at non-breaking spaces.

bpo-28735 [https://bugs.python.org/issue?@action=redirect&bpo=28735]: Fixed the comparison of mock.MagickMock with mock.ANY.

bpo-29011 [https://bugs.python.org/issue?@action=redirect&bpo=29011]: Fix an important omission by adding Deque to the typing module.

bpo-29219 [https://bugs.python.org/issue?@action=redirect&bpo=29219]: Fixed infinite recursion in the repr of uninitialized ctypes.CDLL instances.

bpo-28969 [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.

bpo-29142 [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.

Documentation

bpo-30176 [https://bugs.python.org/issue?@action=redirect&bpo=30176]: Add missing attribute related constants in curses documentation.

bpo-26985 [https://bugs.python.org/issue?@action=redirect&bpo=26985]: Add missing info of code object in inspect documentation.

bpo-28929 [https://bugs.python.org/issue?@action=redirect&bpo=28929]: Link the documentation to its source file on GitHub.

bpo-25008 [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.

bpo-26355 [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.

bpo-29349 [https://bugs.python.org/issue?@action=redirect&bpo=29349]: Fix Python 2 syntax in code for building the documentation.

Tests

bpo-30822 [https://bugs.python.org/issue?@action=redirect&bpo=30822]: Fix regrtest command line parser to allow passing -u extralargefile to run test_zipfile64.

bpo-30383 [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 [https://bugs.python.org/issue?@action=redirect&bpo=30523]), --matchfile (load a list of test filters from a text file, bpo-30540 [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 [https://bugs.python.org/issue?@action=redirect&bpo=30675]).

bpo-30357 [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.

bpo-28087 [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.

bpo-30197 [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.

bpo-29571 [https://bugs.python.org/issue?@action=redirect&bpo=29571]: to match the behaviour of the re.LOCALE flag, test_re.test_locale_flag now uses 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)

Build

bpo-29243 [https://bugs.python.org/issue?@action=redirect&bpo=29243]: Prevent unnecessary rebuilding of Python during make test, make install and some other make targets when configured with --enable-optimizations.

bpo-23404 [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 make touch with make regen-all.

bpo-29643 [https://bugs.python.org/issue?@action=redirect&bpo=29643]: Fix --enable-optimization didn't work.

Windows

bpo-30687 [https://bugs.python.org/issue?@action=redirect&bpo=30687]: Locate msbuild.exe on Windows when building rather than vcvarsall.bat

bpo-29392 [https://bugs.python.org/issue?@action=redirect&bpo=29392]: Prevent crash when passing invalid arguments into msvcrt module.

C API

bpo-27867 [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.

bpo-29083 [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.

Python 3.5.3 final

Release date: 2017-01-17

There were no code changes between 3.5.3rc1 and 3.5.3 final.

Python 3.5.3 release candidate 1

Release date: 2017-01-02

Security

bpo-27278 [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.

bpo-22636 [https://bugs.python.org/issue?@action=redirect&bpo=22636]: Avoid shell injection problems with ctypes.util.find_library().

Core and Builtins

bpo-29073 [https://bugs.python.org/issue?@action=redirect&bpo=29073]: bytearray formatting no longer truncates on first null byte.

bpo-28932 [https://bugs.python.org/issue?@action=redirect&bpo=28932]: Do not include <sys/random.h> if it does not exist.

bpo-28147 [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.

bpo-25677 [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.

bpo-29000 [https://bugs.python.org/issue?@action=redirect&bpo=29000]: Fixed bytes formatting of octals with zero padding in alternate form.

bpo-28512 [https://bugs.python.org/issue?@action=redirect&bpo=28512]: Fixed setting the offset attribute of SyntaxError by PyErr_SyntaxLocationEx() and PyErr_SyntaxLocationObject().

bpo-28991 [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.

bpo-28648 [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.

bpo-19398 [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.

bpo-28426 [https://bugs.python.org/issue?@action=redirect&bpo=28426]: Fixed potential crash in PyUnicode_AsDecodedObject() in debug build.

bpo-23782 [https://bugs.python.org/issue?@action=redirect&bpo=23782]: Fixed possible memory leak in _PyTraceback_Add() and exception loss in PyTraceBack_Here().

bpo-28379 [https://bugs.python.org/issue?@action=redirect&bpo=28379]: Added sanity checks and tests for PyUnicode_CopyCharacters(). Patch by Xiang Zhang.

bpo-28376 [https://bugs.python.org/issue?@action=redirect&bpo=28376]: The type of long range iterator is now registered as Iterator. Patch by Oren Milman.

bpo-28376 [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.

bpo-26906 [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.

bpo-18287 [https://bugs.python.org/issue?@action=redirect&bpo=18287]: PyType_Ready() now checks that tp_name is not NULL. Original patch by Niklas Koep.

bpo-24098 [https://bugs.python.org/issue?@action=redirect&bpo=24098]: Fixed possible crash when AST is changed in process of compiling it.

bpo-28350 [https://bugs.python.org/issue?@action=redirect&bpo=28350]: String constants with null character no longer interned.

bpo-26617 [https://bugs.python.org/issue?@action=redirect&bpo=26617]: Fix crash when GC runs during weakref callbacks.

bpo-27942 [https://bugs.python.org/issue?@action=redirect&bpo=27942]: String constants now interned recursively in tuples and frozensets.

bpo-21578 [https://bugs.python.org/issue?@action=redirect&bpo=21578]: Fixed misleading error message when ImportError called with invalid keyword args.

bpo-28203 [https://bugs.python.org/issue?@action=redirect&bpo=28203]: Fix incorrect type in error message from complex(1.0, {2:3}). Patch by Soumya Sharma.

bpo-27955 [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.

bpo-28131 [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.

bpo-25221 [https://bugs.python.org/issue?@action=redirect&bpo=25221]: Fix corrupted result from PyLong_FromLong(0) when Python is compiled with NSMALLPOSINTS = 0.

bpo-25758 [https://bugs.python.org/issue?@action=redirect&bpo=25758]: Prevents zipimport from unnecessarily encoding a filename (patch by Eryk Sun)

bpo-28189 [https://bugs.python.org/issue?@action=redirect&bpo=28189]: dictitems_contains no longer swallows compare errors. (Patch by Xiang Zhang)

bpo-27812 [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().

bpo-27811 [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.

bpo-27587 [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.

bpo-26020 [https://bugs.python.org/issue?@action=redirect&bpo=26020]: set literal evaluation order did not match documented behaviour.

bpo-27782 [https://bugs.python.org/issue?@action=redirect&bpo=27782]: Multi-phase extension module import now correctly allows the m_methods field to be used to add module level functions to instances of non-module types returned from Py_create_mod. Patch by Xiang Zhang.

bpo-27936 [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.

bpo-27487 [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.

bpo-27558 [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.

bpo-27419 [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.

bpo-27083 [https://bugs.python.org/issue?@action=redirect&bpo=27083]: Respect the PYTHONCASEOK environment variable under Windows.

bpo-27514 [https://bugs.python.org/issue?@action=redirect&bpo=27514]: Make having too many statically nested blocks a SyntaxError instead of SystemError.

bpo-27473 [https://bugs.python.org/issue?@action=redirect&bpo=27473]: Fixed possible integer overflow in bytes and bytearray concatenations. Patch by Xiang Zhang.

bpo-27507 [https://bugs.python.org/issue?@action=redirect&bpo=27507]: Add integer overflow check in bytearray.extend(). Patch by Xiang Zhang.

bpo-27581 [https://bugs.python.org/issue?@action=redirect&bpo=27581]: Don't rely on wrapping for overflow check in PySequence_Tuple(). Patch by Xiang Zhang.

bpo-27443 [https://bugs.python.org/issue?@action=redirect&bpo=27443]: __length_hint__() of bytearray iterators no longer return a negative integer for a resized bytearray.

bpo-27942 [https://bugs.python.org/issue?@action=redirect&bpo=27942]: Fix memory leak in codeobject.c

Library

bpo-15812 [https://bugs.python.org/issue?@action=redirect&bpo=15812]: inspect.getframeinfo() now correctly shows the first line of a context. Patch by Sam Breese.

bpo-29094 [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.

bpo-13051 [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.

bpo-29119 [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.

bpo-9770 [https://bugs.python.org/issue?@action=redirect&bpo=9770]: curses.ascii predicates now work correctly with negative integers.

bpo-28427 [https://bugs.python.org/issue?@action=redirect&bpo=28427]: old keys should not remove new values from WeakValueDictionary when collecting from another thread.

bpo-28923 [https://bugs.python.org/issue?@action=redirect&bpo=28923]: Remove editor artifacts from Tix.py.

bpo-28871 [https://bugs.python.org/issue?@action=redirect&bpo=28871]: Fixed a crash when deallocate deep ElementTree.

bpo-19542 [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.

bpo-20191 [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.

bpo-28779 [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.

bpo-28847 [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.

bpo-25659 [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.

bpo-28732 [https://bugs.python.org/issue?@action=redirect&bpo=28732]: Fix crash in os.spawnv() with no elements in args

bpo-28485 [https://bugs.python.org/issue?@action=redirect&bpo=28485]: Always raise ValueError for negative compileall.compile_dir(workers=...) parameter, even when multithreading is unavailable.

bpo-28387 [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.

bpo-27517 [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.

bpo-28549 [https://bugs.python.org/issue?@action=redirect&bpo=28549]: Fixed segfault in curses's addch() with ncurses6.

bpo-28449 [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.

bpo-23262 [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.

bpo-27939 [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.

bpo-28255 [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.

bpo-20491 [https://bugs.python.org/issue?@action=redirect&bpo=20491]: The textwrap.TextWrapper class now honors non-breaking spaces. Based on patch by Kaarle Ritvanen.

bpo-28353 [https://bugs.python.org/issue?@action=redirect&bpo=28353]: os.fwalk() no longer fails on broken links.

bpo-25464 [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.

bpo-28488 [https://bugs.python.org/issue?@action=redirect&bpo=28488]: shutil.make_archive() no longer add entry "./" to ZIP archive.

bpo-24452 [https://bugs.python.org/issue?@action=redirect&bpo=24452]: Make webbrowser support Chrome on Mac OS X.

bpo-20766 [https://bugs.python.org/issue?@action=redirect&bpo=20766]: Fix references leaked by pdb in the handling of SIGINT handlers.

bpo-26293 [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.

bpo-28321 [https://bugs.python.org/issue?@action=redirect&bpo=28321]: Fixed writing non-BMP characters with binary format in plistlib.

bpo-28322 [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.

Fix possible integer overflows and crashes in the mmap module with unusual usage patterns.

bpo-1703178 [https://bugs.python.org/issue?@action=redirect&bpo=1703178]: Fix the ability to pass the --link-objects option to the distutils build_ext command.

bpo-28253 [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.

bpo-28275 [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.

bpo-27897 [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.

bpo-18893 [https://bugs.python.org/issue?@action=redirect&bpo=18893]: Fix invalid exception handling in Lib/ctypes/macholib/dyld.py. Patch by Madison May.

bpo-27611 [https://bugs.python.org/issue?@action=redirect&bpo=27611]: Fixed support of default root window in the tkinter.tix module.

bpo-27348 [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.

bpo-25651 [https://bugs.python.org/issue?@action=redirect&bpo=25651]: Allow false values to be used for msg parameter of subTest().

bpo-27932 [https://bugs.python.org/issue?@action=redirect&bpo=27932]: Prevent memory leak in win32_ver().

Fix UnboundLocalError in socket._sendfile_use_sendfile.

bpo-28075 [https://bugs.python.org/issue?@action=redirect&bpo=28075]: Check for ERROR_ACCESS_DENIED in Windows implementation of os.stat(). Patch by Eryk Sun.

bpo-25270 [https://bugs.python.org/issue?@action=redirect&bpo=25270]: Prevent codecs.escape_encode() from raising SystemError when an empty bytestring is passed.

bpo-28181 [https://bugs.python.org/issue?@action=redirect&bpo=28181]: Get antigravity over HTTPS. Patch by Kaartic Sivaraam.

bpo-25895 [https://bugs.python.org/issue?@action=redirect&bpo=25895]: Enable WebSocket URL schemes in urllib.parse.urljoin. Patch by Gergely Imreh and Markus Holtermann.

bpo-27599 [https://bugs.python.org/issue?@action=redirect&bpo=27599]: Fixed buffer overrun in binascii.b2a_qp() and binascii.a2b_qp().

bpo-19003 [https://bugs.python.org/issue?@action=redirect&bpo=19003]: m email.generator now replaces only \r and/or \n line endings, per the RFC, instead of all unicode line endings.

bpo-28019 [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.

bpo-25969 [https://bugs.python.org/issue?@action=redirect&bpo=25969]: Update the lib2to3 grammar to handle the unpacking generalizations added in 3.5.

bpo-14977 [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.

bpo-24594 [https://bugs.python.org/issue?@action=redirect&bpo=24594]: Validates persist parameter when opening MSI database

bpo-17582 [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.)

bpo-28047 [https://bugs.python.org/issue?@action=redirect&bpo=28047]: Fixed calculation of line length used for the base64 CTE in the new email policies.

bpo-27445 [https://bugs.python.org/issue?@action=redirect&bpo=27445]: Don't pass str(_charset) to MIMEText.set_payload(). Patch by Claude Paroz.

bpo-22450 [https://bugs.python.org/issue?@action=redirect&bpo=22450]: urllib now includes an Accept: */* header among the default headers. This makes the results of REST API requests more consistent and predictable especially when proxy servers are involved.

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.

bpo-27570 [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.

bpo-22233 [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.

bpo-27988 [https://bugs.python.org/issue?@action=redirect&bpo=27988]: Fix email iter_attachments incorrect mutation of payload list.

bpo-27691 [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.

bpo-27850 [https://bugs.python.org/issue?@action=redirect&bpo=27850]: Remove 3DES from ssl module's default cipher list to counter measure sweet32 attack (CVE-2016-2183 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-2183]).

bpo-27766 [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).

bpo-26470 [https://bugs.python.org/issue?@action=redirect&bpo=26470]: Port ssl and hashlib module to OpenSSL 1.1.0.

Remove support for passing a file descriptor to os.access. It never worked but previously didn't raise.

bpo-12885 [https://bugs.python.org/issue?@action=redirect&bpo=12885]: Fix error when distutils encounters symlink.

bpo-27881 [https://bugs.python.org/issue?@action=redirect&bpo=27881]: Fixed possible bugs when setting sqlite3.Connection.isolation_level. Based on patch by Xiang Zhang.

bpo-27861 [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.

bpo-19884 [https://bugs.python.org/issue?@action=redirect&bpo=19884]: Avoid spurious output on OS X with Gnu Readline.

bpo-27706 [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.

bpo-10513 [https://bugs.python.org/issue?@action=redirect&bpo=10513]: Fix a regression in Connection.commit(). Statements should not be reset after a commit.

A new version of typing.py from https://github.com/python/typing: Collection (only for 3.6) (bpo-27598 [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).

bpo-27539 [https://bugs.python.org/issue?@action=redirect&bpo=27539]: Fix unnormalised Fraction.__pow__ result in the case of negative exponent and negative base.

bpo-21718 [https://bugs.python.org/issue?@action=redirect&bpo=21718]: cursor.description is now available for queries using CTEs.

bpo-2466 [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.

bpo-27773 [https://bugs.python.org/issue?@action=redirect&bpo=27773]: Correct some memory management errors server_hostname in _ssl.wrap_socket().

bpo-26750 [https://bugs.python.org/issue?@action=redirect&bpo=26750]: unittest.mock.create_autospec() now works properly for subclasses of property() and other data descriptors.

In the curses module, raise an error if window.getstr() or window.instr() is passed a negative value.

bpo-27783 [https://bugs.python.org/issue?@action=redirect&bpo=27783]: Fix possible usage of uninitialized memory in operator.methodcaller.

bpo-27774 [https://bugs.python.org/issue?@action=redirect&bpo=27774]: Fix possible Py_DECREF on unowned object in _sre.

bpo-27760 [https://bugs.python.org/issue?@action=redirect&bpo=27760]: Fix possible integer overflow in binascii.b2a_qp.

bpo-27758 [https://bugs.python.org/issue?@action=redirect&bpo=27758]: Fix possible integer overflow in the _csv module for large record lengths.

bpo-27568 [https://bugs.python.org/issue?@action=redirect&bpo=27568]: Prevent HTTPoxy attack (CVE-2016-1000110 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-1000110]). Ignore the HTTP_PROXY variable when REQUEST_METHOD environment is set, which indicates that the script is in CGI mode.

bpo-27656 [https://bugs.python.org/issue?@action=redirect&bpo=27656]: Do not assume sched.h defines any SCHED_* constants.

bpo-27130 [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.

bpo-27533 [https://bugs.python.org/issue?@action=redirect&bpo=27533]: Release GIL in nt._isdir

bpo-17711 [https://bugs.python.org/issue?@action=redirect&bpo=17711]: Fixed unpickling by the persistent ID with protocol 0. Original patch by Alexandre Vassalotti.

bpo-27522 [https://bugs.python.org/issue?@action=redirect&bpo=27522]: Avoid an unintentional reference cycle in email.feedparser.

bpo-26844 [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.

bpo-23804 [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.

bpo-27466 [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.

bpo-26664 [https://bugs.python.org/issue?@action=redirect&bpo=26664]: Fix activate.fish by removing mis-use of $.

bpo-22115 [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.

Fix a scoping issue in importlib.util.LazyLoader which triggered an UnboundLocalError when lazy-loading a module that was already put into sys.modules.

bpo-27079 [https://bugs.python.org/issue?@action=redirect&bpo=27079]: Fixed curses.ascii functions isblank(), iscntrl() and ispunct().

bpo-26754 [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.

bpo-27048 [https://bugs.python.org/issue?@action=redirect&bpo=27048]: Prevents distutils failing on Windows when environment variables contain non-ASCII characters

bpo-27330 [https://bugs.python.org/issue?@action=redirect&bpo=27330]: Fixed possible leaks in the ctypes module.

bpo-27238 [https://bugs.python.org/issue?@action=redirect&bpo=27238]: Got rid of bare excepts in the turtle module. Original patch by Jelle Zijlstra.

bpo-27122 [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 PEP 479 [https://peps.python.org/pep-0479/] bug described in issue25782.

bpo-26386 [https://bugs.python.org/issue?@action=redirect&bpo=26386]: Fixed ttk.TreeView selection operations with item id's containing spaces.

bpo-16182 [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.

bpo-27392 [https://bugs.python.org/issue?@action=redirect&bpo=27392]: Add loop.connect_accepted_socket(). Patch by Jim Fulton.

bpo-27930 [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.

bpo-21201 [https://bugs.python.org/issue?@action=redirect&bpo=21201]: Improves readability of multiprocessing error message. Thanks to Wojciech Walczak for patch.

bpo-27456 [https://bugs.python.org/issue?@action=redirect&bpo=27456]: asyncio: Set TCP_NODELAY by default.

bpo-27906 [https://bugs.python.org/issue?@action=redirect&bpo=27906]: Fix socket accept exhaustion during high TCP traffic. Patch by Kevin Conway.

bpo-28174 [https://bugs.python.org/issue?@action=redirect&bpo=28174]: Handle when SO_REUSEPORT isn't properly supported. Patch by Seth Michael Larson.

bpo-26654 [https://bugs.python.org/issue?@action=redirect&bpo=26654]: Inspect functools.partial in asyncio.Handle.__repr__. Patch by iceboy.

bpo-26909 [https://bugs.python.org/issue?@action=redirect&bpo=26909]: Fix slow pipes IO in asyncio. Patch by INADA Naoki.

bpo-28176 [https://bugs.python.org/issue?@action=redirect&bpo=28176]: Fix callbacks race in asyncio.SelectorLoop.sock_connect.

bpo-27759 [https://bugs.python.org/issue?@action=redirect&bpo=27759]: Fix selectors incorrectly retain invalid file descriptors. Patch by Mark Williams.

bpo-28368 [https://bugs.python.org/issue?@action=redirect&bpo=28368]: Refuse monitoring processes if the child watcher has no loop attached. Patch by Vincent Michel.

bpo-28369 [https://bugs.python.org/issue?@action=redirect&bpo=28369]: Raise RuntimeError when transport's FD is used with add_reader, add_writer, etc.

bpo-28370 [https://bugs.python.org/issue?@action=redirect&bpo=28370]: Speedup asyncio.StreamReader.readexactly. Patch by Коренберг Марк.

bpo-28371 [https://bugs.python.org/issue?@action=redirect&bpo=28371]: Deprecate passing asyncio.Handles to run_in_executor.

bpo-28372 [https://bugs.python.org/issue?@action=redirect&bpo=28372]: Fix asyncio to support formatting of non-python coroutines.

bpo-28399 [https://bugs.python.org/issue?@action=redirect&bpo=28399]: Remove UNIX socket from FS before binding. Patch by Коренберг Марк.

bpo-27972 [https://bugs.python.org/issue?@action=redirect&bpo=27972]: Prohibit Tasks to await on themselves.

bpo-26923 [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.

bpo-26796 [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.

bpo-28600 [https://bugs.python.org/issue?@action=redirect&bpo=28600]: Optimize loop.call_soon().

bpo-28613 [https://bugs.python.org/issue?@action=redirect&bpo=28613]: Fix get_event_loop() return the current loop if called from coroutines/callbacks.

bpo-28639 [https://bugs.python.org/issue?@action=redirect&bpo=28639]: Fix inspect.isawaitable to always return bool Patch by Justin Mayfield.

bpo-28652 [https://bugs.python.org/issue?@action=redirect&bpo=28652]: Make loop methods reject socket kinds they do not support.

bpo-28653 [https://bugs.python.org/issue?@action=redirect&bpo=28653]: Fix a refleak in functools.lru_cache.

bpo-28703 [https://bugs.python.org/issue?@action=redirect&bpo=28703]: Fix asyncio.iscoroutinefunction to handle Mock objects.

bpo-24142 [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.

bpo-28990 [https://bugs.python.org/issue?@action=redirect&bpo=28990]: Fix SSL hanging if connection is closed before handshake completed. (Patch by HoHo-Ho)

IDLE

bpo-15308 [https://bugs.python.org/issue?@action=redirect&bpo=15308]: Add 'interrupt execution' (^C) to Shell menu. Patch by Roger Serwy, updated by Bayard Randel.

bpo-27922 [https://bugs.python.org/issue?@action=redirect&bpo=27922]: Stop IDLE tests from 'flashing' gui widgets on the screen.

Add version to title of IDLE help window.

bpo-25564 [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.

bpo-27714 [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.

bpo-25507 [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.

bpo-27452 [https://bugs.python.org/issue?@action=redirect&bpo=27452]: add line counter and crc to IDLE configHandler test dump.

bpo-27365 [https://bugs.python.org/issue?@action=redirect&bpo=27365]: Allow non-ascii chars in IDLE NEWS.txt, for contributor names.

bpo-27245 [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.

C API

bpo-28808 [https://bugs.python.org/issue?@action=redirect&bpo=28808]: PyUnicode_CompareWithASCIIString() now never raises exceptions.

bpo-26754 [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.

Documentation

bpo-28513 [https://bugs.python.org/issue?@action=redirect&bpo=28513]: Documented command-line interface of zipfile.

Tests

bpo-28950 [https://bugs.python.org/issue?@action=redirect&bpo=28950]: Disallow -j0 to be combined with -T/-l/-M in regrtest command line arguments.

bpo-28666 [https://bugs.python.org/issue?@action=redirect&bpo=28666]: Now test.support.rmtree is able to remove unwritable or unreadable directories.

bpo-23839 [https://bugs.python.org/issue?@action=redirect&bpo=23839]: Various caches now are cleared before running every test file.

bpo-28409 [https://bugs.python.org/issue?@action=redirect&bpo=28409]: regrtest: fix the parser of command line arguments.

bpo-27787 [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.

bpo-27369 [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.

Tools/Demos

bpo-27952 [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.

bpo-27332 [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.

bpo-27418 [https://bugs.python.org/issue?@action=redirect&bpo=27418]: Fixed Tools/importbench/importbench.py.

Windows

bpo-28251 [https://bugs.python.org/issue?@action=redirect&bpo=28251]: Improvements to help manuals on Windows.

bpo-28110 [https://bugs.python.org/issue?@action=redirect&bpo=28110]: launcher.msi has different product codes between 32-bit and 64-bit

bpo-25144 [https://bugs.python.org/issue?@action=redirect&bpo=25144]: Ensures TargetDir is set before continuing with custom install.

bpo-27469 [https://bugs.python.org/issue?@action=redirect&bpo=27469]: Adds a shell extension to the launcher so that drag and drop works correctly.

bpo-27309 [https://bugs.python.org/issue?@action=redirect&bpo=27309]: Enabled proper Windows styles in python[w].exe manifest.

Build

bpo-29080 [https://bugs.python.org/issue?@action=redirect&bpo=29080]: Removes hard dependency on hg.exe from PCBuild/build.bat

bpo-23903 [https://bugs.python.org/issue?@action=redirect&bpo=23903]: Added missed names to PC/python3.def.

bpo-10656 [https://bugs.python.org/issue?@action=redirect&bpo=10656]: Fix out-of-tree building on AIX. Patch by Tristan Carel and Michael Haubenwallner.

bpo-26359 [https://bugs.python.org/issue?@action=redirect&bpo=26359]: Rename --with-optimiations to --enable-optimizations.

bpo-28444 [https://bugs.python.org/issue?@action=redirect&bpo=28444]: Fix missing extensions modules when cross compiling.

bpo-28248 [https://bugs.python.org/issue?@action=redirect&bpo=28248]: Update Windows build and OS X installers to use OpenSSL 1.0.2j.

bpo-28258 [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.

bpo-26661 [https://bugs.python.org/issue?@action=redirect&bpo=26661]: setup.py now detects system libffi with multiarch wrapper.

bpo-28066 [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.

bpo-15819 [https://bugs.python.org/issue?@action=redirect&bpo=15819]: Remove redundant include search directory option for building outside the source tree.

bpo-27566 [https://bugs.python.org/issue?@action=redirect&bpo=27566]: Fix clean target in freeze makefile (patch by Lisa Roach)

bpo-27705 [https://bugs.python.org/issue?@action=redirect&bpo=27705]: Update message in validate_ucrtbase.py

bpo-27983 [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.

bpo-26307 [https://bugs.python.org/issue?@action=redirect&bpo=26307]: The profile-opt build now applies PGO to the built-in modules.

bpo-26359 [https://bugs.python.org/issue?@action=redirect&bpo=26359]: Add the --with-optimizations configure flag.

bpo-27713 [https://bugs.python.org/issue?@action=redirect&bpo=27713]: Suppress spurious build warnings when updating importlib's bootstrap files. Patch by Xiang Zhang

bpo-25825 [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.

bpo-27453 [https://bugs.python.org/issue?@action=redirect&bpo=27453]: CPP invocation in configure must use CPPFLAGS. Patch by Chi Hsuan Yen.

bpo-27641 [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.

bpo-26662 [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.

bpo-10910 [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.

bpo-28676 [https://bugs.python.org/issue?@action=redirect&bpo=28676]: Prevent missing 'getentropy' declaration warning on macOS. Patch by Gareth Rees.

Python 3.5.2 final

Release date: 2016-06-26

Core and Builtins

bpo-26930 [https://bugs.python.org/issue?@action=redirect&bpo=26930]: Update Windows builds to use OpenSSL 1.0.2h.

Tests

bpo-26867 [https://bugs.python.org/issue?@action=redirect&bpo=26867]: Ubuntu's openssl OP_NO_SSLv3 is forced on by default; fix test.

IDLE

bpo-27365 [https://bugs.python.org/issue?@action=redirect&bpo=27365]: Allow non-ascii in idlelib/NEWS.txt - minimal part for 3.5.2.

Python 3.5.2 release candidate 1

Release date: 2016-06-12

Security

bpo-26556 [https://bugs.python.org/issue?@action=redirect&bpo=26556]: Update expat to 2.1.1, fixes CVE-2015-1283 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1283].

Fix TLS stripping vulnerability in smtplib, CVE-2016-0772 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-0772]. Reported by Team Oststrom.

bpo-26839 [https://bugs.python.org/issue?@action=redirect&bpo=26839]: On Linux, os.urandom() now calls getrandom() with GRND_NONBLOCK to fall back on reading /dev/urandom if the urandom entropy pool is not initialized yet. Patch written by Colm Buckley.

bpo-26657 [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.

bpo-26313 [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.

bpo-25939 [https://bugs.python.org/issue?@action=redirect&bpo=25939]: On Windows open the cert store readonly in ssl.enum_certificates.

Core and Builtins

bpo-27066 [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.

bpo-20041 [https://bugs.python.org/issue?@action=redirect&bpo=20041]: Fixed TypeError when frame.f_trace is set to None. Patch by Xavier de Gaye.

bpo-26168 [https://bugs.python.org/issue?@action=redirect&bpo=26168]: Fixed possible refleaks in failing Py_BuildValue() with the "N" format unit.

bpo-26991 [https://bugs.python.org/issue?@action=redirect&bpo=26991]: Fix possible refleak when creating a function with annotations.

bpo-27039 [https://bugs.python.org/issue?@action=redirect&bpo=27039]: Fixed bytearray.remove() for values greater than 127. Patch by Joe Jevnik.

bpo-23640 [https://bugs.python.org/issue?@action=redirect&bpo=23640]: int.from_bytes() no longer bypasses constructors for subclasses.

bpo-26811 [https://bugs.python.org/issue?@action=redirect&bpo=26811]: gc.get_objects() no longer contains a broken tuple with NULL pointer.

bpo-20120 [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.

bpo-26659 [https://bugs.python.org/issue?@action=redirect&bpo=26659]: Make the builtin slice type support cycle collection.

bpo-26718 [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!

bpo-25339 [https://bugs.python.org/issue?@action=redirect&bpo=25339]: PYTHONIOENCODING now has priority over locale in setting the error handler for stdin and stdout.

bpo-26494 [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.

bpo-26581 [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.

bpo-26464 [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.

bpo-22836 [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.

bpo-26302 [https://bugs.python.org/issue?@action=redirect&bpo=26302]: Correct behavior to reject comma as a legal character for cookie names.

bpo-4806 [https://bugs.python.org/issue?@action=redirect&bpo=4806]: Avoid masking the original TypeError exception when using star (*) unpacking in function calls. Based on patch by Hagen Fürstenau and Daniel Urban.

bpo-27138 [https://bugs.python.org/issue?@action=redirect&bpo=27138]: Fix the doc comment for FileFinder.find_spec().

bpo-26154 [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.

bpo-26194 [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.

bpo-25843 [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, f1, f2 = lambda: 1, lambda: 1.0 is now correctly compiled to two different functions: f1() returns 1 (int) and f2() returns 1.0 (int), even if 1 and 1.0 are equal.

bpo-22995 [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.

bpo-25961 [https://bugs.python.org/issue?@action=redirect&bpo=25961]: Disallowed null characters in the type name.

bpo-25973 [https://bugs.python.org/issue?@action=redirect&bpo=25973]: Fix segfault when an invalid nonlocal statement binds a name starting with two underscores.

bpo-22995 [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.

bpo-20440 [https://bugs.python.org/issue?@action=redirect&bpo=20440]: Massive replacing unsafe attribute setting code with special macro Py_SETREF.

bpo-25766 [https://bugs.python.org/issue?@action=redirect&bpo=25766]: Special method __bytes__() now works in str subclasses.

bpo-25421 [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.

bpo-25709 [https://bugs.python.org/issue?@action=redirect&bpo=25709]: Fixed problem with in-place string concatenation and utf-8 cache.

bpo-27147 [https://bugs.python.org/issue?@action=redirect&bpo=27147]: Mention PEP 420 [https://peps.python.org/pep-0420/] in the importlib docs.

bpo-24097 [https://bugs.python.org/issue?@action=redirect&bpo=24097]: Fixed crash in object.__reduce__() if slot name is freed inside __getattr__.

bpo-24731 [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.

bpo-26478 [https://bugs.python.org/issue?@action=redirect&bpo=26478]: Fix semantic bugs when using binary operators with dictionary views and tuples.

bpo-26171 [https://bugs.python.org/issue?@action=redirect&bpo=26171]: Fix possible integer overflow and heap corruption in zipimporter.get_data().

bpo-25660 [https://bugs.python.org/issue?@action=redirect&bpo=25660]: Fix TAB key behaviour in REPL with readline.

bpo-25887 [https://bugs.python.org/issue?@action=redirect&bpo=25887]: Raise a RuntimeError when a coroutine object is awaited more than once.

bpo-27243 [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.

Library

bpo-21386 [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.

bpo-20900 [https://bugs.python.org/issue?@action=redirect&bpo=20900]: distutils register command now decodes HTTP responses correctly. Initial patch by ingrid.

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 PEP 492 [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).

bpo-25738 [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.

bpo-21313 [https://bugs.python.org/issue?@action=redirect&bpo=21313]: Fix the "platform" module to tolerate when sys.version contains truncated build information.

bpo-27164 [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.

bpo-24291 [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.

bpo-26809 [https://bugs.python.org/issue?@action=redirect&bpo=26809]: Add __all__ to string. Patch by Emanuel Barry.

bpo-26373 [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.

bpo-21776 [https://bugs.python.org/issue?@action=redirect&bpo=21776]: distutils.upload now correctly handles HTTPError. Initial patch by Claudiu Popa.

bpo-27114 [https://bugs.python.org/issue?@action=redirect&bpo=27114]: Fix SSLContext._load_windows_store_certs fails with PermissionError

bpo-18383 [https://bugs.python.org/issue?@action=redirect&bpo=18383]: Avoid creating duplicate filters when using filterwarnings and simplefilter. Based on patch by Alex Shkop.

bpo-27057 [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.

bpo-27014 [https://bugs.python.org/issue?@action=redirect&bpo=27014]: Fix infinite recursion using typing.py. Thanks to Kalle Tuure!

bpo-14132 [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.

bpo-17214 [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.

bpo-26892 [https://bugs.python.org/issue?@action=redirect&bpo=26892]: Honor debuglevel flag in urllib.request.HTTPHandler. Patch contributed by Chi Hsuan Yen.

bpo-22274 [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.

bpo-26807 [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.

bpo-25745 [https://bugs.python.org/issue?@action=redirect&bpo=25745]: Fixed leaking a userptr in curses panel destructor.

bpo-26977 [https://bugs.python.org/issue?@action=redirect&bpo=26977]: Removed unnecessary, and ignored, call to sum of squares helper in statistics.pvariance.

bpo-26881 [https://bugs.python.org/issue?@action=redirect&bpo=26881]: The modulefinder module now supports extended opcode arguments.

bpo-23815 [https://bugs.python.org/issue?@action=redirect&bpo=23815]: Fixed crashes related to directly created instances of types in _tkinter and curses.panel modules.

bpo-17765 [https://bugs.python.org/issue?@action=redirect&bpo=17765]: weakref.ref() no longer silently ignores keyword arguments. Patch by Georg Brandl.

bpo-26873 [https://bugs.python.org/issue?@action=redirect&bpo=26873]: xmlrpc now raises ResponseError on unsupported type tags instead of silently return incorrect result.

bpo-26711 [https://bugs.python.org/issue?@action=redirect&bpo=26711]: Fixed the comparison of plistlib.Data with other types.

bpo-24114 [https://bugs.python.org/issue?@action=redirect&bpo=24114]: Fix an uninitialized variable in ctypes.util. The bug only occurs on SunOS when the ctypes implementation searches for the crle program. Patch by Xiang Zhang. Tested on SunOS by Kees Bos.

bpo-26864 [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.

bpo-26634 [https://bugs.python.org/issue?@action=redirect&bpo=26634]: recursive_repr() now sets __qualname__ of wrapper. Patch by Xiang Zhang.

bpo-26804 [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.

bpo-26837 [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().

bpo-26041 [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.

bpo-26822 [https://bugs.python.org/issue?@action=redirect&bpo=26822]: itemgetter, attrgetter and methodcaller objects no longer silently ignore keyword arguments.

bpo-26733 [https://bugs.python.org/issue?@action=redirect&bpo=26733]: Disassembling a class now disassembles class and static methods. Patch by Xiang Zhang.

bpo-26801 [https://bugs.python.org/issue?@action=redirect&bpo=26801]: Fix error handling in shutil.get_terminal_size(), catch AttributeError instead of NameError. Patch written by Emanuel Barry.

bpo-24838 [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.

bpo-26717 [https://bugs.python.org/issue?@action=redirect&bpo=26717]: Stop encoding Latin-1-ized WSGI paths with UTF-8. Patch by Anthony Sottile.

bpo-26735 [https://bugs.python.org/issue?@action=redirect&bpo=26735]: Fix os.urandom() on Solaris 11.3 and newer when reading more than 1,024 bytes: call getrandom() multiple times with a limit of 1024 bytes per call.

bpo-16329 [https://bugs.python.org/issue?@action=redirect&bpo=16329]: Add .webm to mimetypes.types_map. Patch by Giampaolo Rodola'.

bpo-13952 [https://bugs.python.org/issue?@action=redirect&bpo=13952]: Add .csv to mimetypes.types_map. Patch by Geoff Wilson.

bpo-26709 [https://bugs.python.org/issue?@action=redirect&bpo=26709]: Fixed Y2038 problem in loading binary PLists.

bpo-23735 [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.

bpo-26586 [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.

bpo-22854 [https://bugs.python.org/issue?@action=redirect&bpo=22854]: Change BufferedReader.writable() and BufferedWriter.readable() to always return False.

bpo-25195 [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.

bpo-26644 [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().

bpo-23804 [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.

bpo-26616 [https://bugs.python.org/issue?@action=redirect&bpo=26616]: Fixed a bug in datetime.astimezone() method.

bpo-21925 [https://bugs.python.org/issue?@action=redirect&bpo=21925]: warnings.formatwarning() now catches exceptions on linecache.getline(...) to be able to log ResourceWarning emitted late during the Python shutdown process.

bpo-24266 [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.

bpo-26560 [https://bugs.python.org/issue?@action=redirect&bpo=26560]: Avoid potential ValueError in BaseHandler.start_response. Initial patch by Peter Inglesby.

bpo-26569 [https://bugs.python.org/issue?@action=redirect&bpo=26569]: Fix pyclbr.readmodule() and pyclbr.readmodule_ex() to support importing packages.

bpo-26499 [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.

bpo-25320 [https://bugs.python.org/issue?@action=redirect&bpo=25320]: Handle sockets in directories unittest discovery is scanning. Patch from Victor van den Elzen.

bpo-16181 [https://bugs.python.org/issue?@action=redirect&bpo=16181]: cookiejar.http2time() now returns None if year is higher than datetime.MAXYEAR.

bpo-26513 [https://bugs.python.org/issue?@action=redirect&bpo=26513]: Fixes platform module detection of Windows Server

bpo-23718 [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.

bpo-20589 [https://bugs.python.org/issue?@action=redirect&bpo=20589]: Invoking Path.owner() and Path.group() on Windows now raise NotImplementedError instead of ImportError.

bpo-26177 [https://bugs.python.org/issue?@action=redirect&bpo=26177]: Fixed the keys() method for Canvas and Scrollbar widgets.

bpo-15068 [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.

bpo-2202 [https://bugs.python.org/issue?@action=redirect&bpo=2202]: Fix UnboundLocalError in AbstractDigestAuthHandler.get_algorithm_impls. Initial patch by Mathieu Dupuy.

bpo-25718 [https://bugs.python.org/issue?@action=redirect&bpo=25718]: Fixed pickling and copying the accumulate() iterator with total is None.

bpo-26475 [https://bugs.python.org/issue?@action=redirect&bpo=26475]: Fixed debugging output for regular expressions with the (?x) flag.

bpo-26457 [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.

bpo-26385 [https://bugs.python.org/issue?@action=redirect&bpo=26385]: Remove the file if the internal open() call in NamedTemporaryFile() fails. Patch by Silent Ghost.

bpo-26402 [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.

bpo-25913 [https://bugs.python.org/issue?@action=redirect&bpo=25913]: Leading <~ is optional now in base64.a85decode() with adobe=True. Patch by Swati Jaiswal.

bpo-26186 [https://bugs.python.org/issue?@action=redirect&bpo=26186]: Remove an invalid type check in importlib.util.LazyLoader.

bpo-26367 [https://bugs.python.org/issue?@action=redirect&bpo=26367]: importlib.__import__() raises SystemError like builtins.__import__() when level is specified but without an accompanying package specified.

bpo-26309 [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.

bpo-25995 [https://bugs.python.org/issue?@action=redirect&bpo=25995]: os.walk() no longer uses FDs proportional to the tree depth.

bpo-26117 [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.

bpo-25911 [https://bugs.python.org/issue?@action=redirect&bpo=25911]: Restored support of bytes paths in os.walk() on Windows.

bpo-26045 [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.

bpo-12923 [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.

bpo-25945 [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.

bpo-26202 [https://bugs.python.org/issue?@action=redirect&bpo=26202]: copy.deepcopy() now correctly copies range() objects with non-atomic attributes.

bpo-23076 [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.

bpo-19883 [https://bugs.python.org/issue?@action=redirect&bpo=19883]: Fixed possible integer overflows in zipimport.

bpo-26227 [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.

bpo-26147 [https://bugs.python.org/issue?@action=redirect&bpo=26147]: xmlrpc now works with strings not encodable with used non-UTF-8 encoding.

bpo-25935 [https://bugs.python.org/issue?@action=redirect&bpo=25935]: Garbage collector now breaks reference loops with OrderedDict.

bpo-16620 [https://bugs.python.org/issue?@action=redirect&bpo=16620]: Fixed AttributeError in msilib.Directory.glob().

bpo-26013 [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).

bpo-25850 [https://bugs.python.org/issue?@action=redirect&bpo=25850]: Use cross-compilation by default for 64-bit Windows.

bpo-17633 [https://bugs.python.org/issue?@action=redirect&bpo=17633]: Improve zipimport's support for namespace packages.

bpo-24705 [https://bugs.python.org/issue?@action=redirect&bpo=24705]: Fix sysconfig._parse_makefile not expanding ${} vars appearing before $() vars.

bpo-22138 [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.

bpo-25672 [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.

bpo-26012 [https://bugs.python.org/issue?@action=redirect&bpo=26012]: Don't traverse into symlinks for ** pattern in pathlib.Path.[r]glob().

bpo-24120 [https://bugs.python.org/issue?@action=redirect&bpo=24120]: Ignore PermissionError when traversing a tree with pathlib.Path.[r]glob(). Patch by Ulrich Petri.

bpo-25447 [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).

bpo-25447 [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).

bpo-24103 [https://bugs.python.org/issue?@action=redirect&bpo=24103]: Fixed possible use after free in ElementTree.XMLPullParser.

bpo-25860 [https://bugs.python.org/issue?@action=redirect&bpo=25860]: os.fwalk() no longer skips remaining directories when error occurs. Original patch by Samson Lee.

bpo-25914 [https://bugs.python.org/issue?@action=redirect&bpo=25914]: Fixed and simplified OrderedDict.__sizeof__.

bpo-25902 [https://bugs.python.org/issue?@action=redirect&bpo=25902]: Fixed various refcount issues in ElementTree iteration.

bpo-25717 [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.

bpo-24903 [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.

bpo-25764 [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.

bpo-6478 [https://bugs.python.org/issue?@action=redirect&bpo=6478]: _strptime's regexp cache now is reset after changing timezone with time.tzset().

bpo-14285 [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.

bpo-19771 [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 *.pyc file).

bpo-25177 [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.

bpo-25718 [https://bugs.python.org/issue?@action=redirect&bpo=25718]: Fixed copying object with state with boolean value is false.

bpo-10131 [https://bugs.python.org/issue?@action=redirect&bpo=10131]: Fixed deep copying of minidom documents. Based on patch by Marian Ganisin.

bpo-25725 [https://bugs.python.org/issue?@action=redirect&bpo=25725]: Fixed a reference leak in pickle.loads() when unpickling invalid data including tuple instructions.

bpo-25663 [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.

bpo-25688 [https://bugs.python.org/issue?@action=redirect&bpo=25688]: Fixed file leak in ElementTree.iterparse() raising an error.

bpo-23914 [https://bugs.python.org/issue?@action=redirect&bpo=23914]: Fixed SystemError raised by unpickler on broken pickle data.

bpo-25691 [https://bugs.python.org/issue?@action=redirect&bpo=25691]: Fixed crash on deleting ElementTree.Element attributes.

bpo-25624 [https://bugs.python.org/issue?@action=redirect&bpo=25624]: ZipFile now always writes a ZIP_STORED header for directory entries. Patch by Dingyuan Wang.

Skip getaddrinfo if host is already resolved. Patch by A. Jesse Jiryu Davis.

bpo-26050 [https://bugs.python.org/issue?@action=redirect&bpo=26050]: Add asyncio.StreamReader.readuntil() method. Patch by Марк Коренберг.

bpo-25924 [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.

bpo-26406 [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.

bpo-26848 [https://bugs.python.org/issue?@action=redirect&bpo=26848]: Fix asyncio/subprocess.communicate() to handle empty input. Patch by Jack O'Connor.

bpo-27040 [https://bugs.python.org/issue?@action=redirect&bpo=27040]: Add loop.get_exception_handler method

bpo-27041 [https://bugs.python.org/issue?@action=redirect&bpo=27041]: asyncio: Add loop.create_future method

bpo-27223 [https://bugs.python.org/issue?@action=redirect&bpo=27223]: asyncio: Fix _read_ready and _write_ready to respect _conn_lost. Patch by Łukasz Langa.

bpo-22970 [https://bugs.python.org/issue?@action=redirect&bpo=22970]: asyncio: Fix inconsistency cancelling Condition.wait. Patch by David Coles.

IDLE

bpo-5124 [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.

bpo-24759 [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.

bpo-27196 [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

bpo-20567 [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.

bpo-27117 [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.

bpo-26673 [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.

bpo-21939 [https://bugs.python.org/issue?@action=redirect&bpo=21939]: Add test for IDLE's percolator. Original patch by Saimadhav Heblikar.

bpo-21676 [https://bugs.python.org/issue?@action=redirect&bpo=21676]: Add test for IDLE's replace dialog. Original patch by Saimadhav Heblikar.

bpo-18410 [https://bugs.python.org/issue?@action=redirect&bpo=18410]: Add test for IDLE's search dialog. Original patch by Westley Martínez.

bpo-21703 [https://bugs.python.org/issue?@action=redirect&bpo=21703]: Add test for IDLE's undo delegator. Original patch by Saimadhav Heblikar .

bpo-27044 [https://bugs.python.org/issue?@action=redirect&bpo=27044]: Add ConfigDialog.remove_var_callbacks to stop memory leaks.

bpo-23977 [https://bugs.python.org/issue?@action=redirect&bpo=23977]: Add more asserts to test_delegator.

bpo-20640 [https://bugs.python.org/issue?@action=redirect&bpo=20640]: Add tests for idlelib.configHelpSourceEdit. Patch by Saimadhav Heblikar.

In the 'IDLE-console differences' section of the IDLE doc, clarify how running with IDLE affects sys.modules and the standard streams.

bpo-25507 [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.

bpo-25905 [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'.

Documentation

bpo-19489 [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.

bpo-24136 [https://bugs.python.org/issue?@action=redirect&bpo=24136]: Document the new PEP 448 [https://peps.python.org/pep-0448/] unpacking syntax of 3.5.

bpo-26736 [https://bugs.python.org/issue?@action=redirect&bpo=26736]: Used HTTPS for external links in the documentation if possible.

bpo-6953 [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.

bpo-23606 [https://bugs.python.org/issue?@action=redirect&bpo=23606]: Adds note to ctypes documentation regarding cdll.msvcrt.

bpo-25500 [https://bugs.python.org/issue?@action=redirect&bpo=25500]: Fix documentation to not claim that __import__ is searched for in the global scope.

bpo-26014 [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

Tests

bpo-21916 [https://bugs.python.org/issue?@action=redirect&bpo=21916]: Added tests for the turtle module. Patch by ingrid, Gregory Loyse and Jelle Zijlstra.

bpo-26523 [https://bugs.python.org/issue?@action=redirect&bpo=26523]: The multiprocessing thread pool (multiprocessing.dummy.Pool) was untested.

bpo-26015 [https://bugs.python.org/issue?@action=redirect&bpo=26015]: Added new tests for pickling iterators of mutable sequences.

bpo-26325 [https://bugs.python.org/issue?@action=redirect&bpo=26325]: Added test.support.check_no_resource_warning() to check that no ResourceWarning is emitted.

bpo-25940 [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.

bpo-25616 [https://bugs.python.org/issue?@action=redirect&bpo=25616]: Tests for OrderedDict are extracted from test_collections into separate file test_ordered_dict.

bpo-26583 [https://bugs.python.org/issue?@action=redirect&bpo=26583]: Skip test_timestamp_overflow in test_import if bytecode files cannot be written.

Build

bpo-26884 [https://bugs.python.org/issue?@action=redirect&bpo=26884]: Fix linking extension modules for cross builds. Patch by Xavier de Gaye.

bpo-22359 [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.

bpo-27229 [https://bugs.python.org/issue?@action=redirect&bpo=27229]: Fix the cross-compiling pgen rule for in-tree builds. Patch by Xavier de Gaye.

bpo-21668 [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.

bpo-25702 [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.

bpo-26624 [https://bugs.python.org/issue?@action=redirect&bpo=26624]: Adds validation of ucrtbase[d].dll version with warning for old versions.

bpo-17603 [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.

bpo-26079 [https://bugs.python.org/issue?@action=redirect&bpo=26079]: Fixing the build output folder for tix-8.4.3.6. Patch by Bjoern Thiel.

bpo-26465 [https://bugs.python.org/issue?@action=redirect&bpo=26465]: Update Windows builds to use OpenSSL 1.0.2g.

bpo-24421 [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.

bpo-25348 [https://bugs.python.org/issue?@action=redirect&bpo=25348]: Added --pgo and --pgo-job arguments to PCbuild\build.bat for building with Profile-Guided Optimization. The old PCbuild\build_pgo.bat script is now deprecated, and simply calls PCbuild\build.bat --pgo %*.

bpo-25827 [https://bugs.python.org/issue?@action=redirect&bpo=25827]: Add support for building with ICC to configure, including a new --with-icc flag.

bpo-25696 [https://bugs.python.org/issue?@action=redirect&bpo=25696]: Fix installation of Python on UNIX with make -j9.

bpo-26930 [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.

bpo-26268 [https://bugs.python.org/issue?@action=redirect&bpo=26268]: Update Windows builds to use OpenSSL 1.0.2f.

bpo-25136 [https://bugs.python.org/issue?@action=redirect&bpo=25136]: Support Apple Xcode 7's new textual SDK stub libraries.

bpo-24324 [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.

Windows

bpo-27053 [https://bugs.python.org/issue?@action=redirect&bpo=27053]: Updates make_zip.py to correctly generate library ZIP file.

bpo-26268 [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).

bpo-26071 [https://bugs.python.org/issue?@action=redirect&bpo=26071]: bdist_wininst created binaries fail to start and find 32bit Python

bpo-26073 [https://bugs.python.org/issue?@action=redirect&bpo=26073]: Update the list of magic numbers in launcher

bpo-26065 [https://bugs.python.org/issue?@action=redirect&bpo=26065]: Excludes venv from library when generating embeddable distro.

bpo-17500 [https://bugs.python.org/issue?@action=redirect&bpo=17500]: Remove unused and outdated icons. (See also: https://github.com/python/pythondotorg/issues/945)

Tools/Demos

bpo-26799 [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.

bpo-26271 [https://bugs.python.org/issue?@action=redirect&bpo=26271]: Fix the Freeze tool to properly use flags passed through configure. Patch by Daniel Shaulov.

bpo-26489 [https://bugs.python.org/issue?@action=redirect&bpo=26489]: Add dictionary unpacking support to Tools/parser/unparse.py. Patch by Guo Ci Teo.

bpo-26316 [https://bugs.python.org/issue?@action=redirect&bpo=26316]: Fix variable name typo in Argument Clinic.

Python 3.5.1 final

Release date: 2015-12-06

Core and Builtins

bpo-25709 [https://bugs.python.org/issue?@action=redirect&bpo=25709]: Fixed problem with in-place string concatenation and utf-8 cache.

Windows

bpo-25715 [https://bugs.python.org/issue?@action=redirect&bpo=25715]: Python 3.5.1 installer shows wrong upgrade path and incorrect logic for launcher detection.

Python 3.5.1 release candidate 1

Release date: 2015-11-22

Core and Builtins

bpo-25630 [https://bugs.python.org/issue?@action=redirect&bpo=25630]: Fix a possible segfault during argument parsing in functions that accept filesystem paths.

bpo-23564 [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.

bpo-25388 [https://bugs.python.org/issue?@action=redirect&bpo=25388]: Fixed tokenizer crash when processing undecodable source code with a null byte.

bpo-25462 [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.

bpo-22995 [https://bugs.python.org/issue?@action=redirect&bpo=22995]: Default implementation of __reduce__ and __reduce_ex__ now rejects builtin types with not defined __new__.

bpo-25555 [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.

bpo-24802 [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.

bpo-24726 [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.

bpo-25449 [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.

bpo-25395 [https://bugs.python.org/issue?@action=redirect&bpo=25395]: Fixed crash when highly nested OrderedDict structures were garbage collected.

bpo-25274 [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.

bpo-24402 [https://bugs.python.org/issue?@action=redirect&bpo=24402]: Fix input() to prompt to the redirected stdout when sys.stdout.fileno() fails.

bpo-24806 [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.

bpo-24848 [https://bugs.python.org/issue?@action=redirect&bpo=24848]: Fixed a number of bugs in UTF-7 decoding of misformed data.

bpo-25280 [https://bugs.python.org/issue?@action=redirect&bpo=25280]: Import trace messages emitted in verbose (-v) mode are no longer formatted twice.

bpo-25003 [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.

bpo-25182 [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.

bpo-25131 [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.

bpo-25150 [https://bugs.python.org/issue?@action=redirect&bpo=25150]: Hide the private _Py_atomic_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.

Library

bpo-25626 [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.

bpo-25583 [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.

bpo-25593 [https://bugs.python.org/issue?@action=redirect&bpo=25593]: Change semantics of EventLoop.stop() in asyncio.

bpo-6973 [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.

bpo-25590 [https://bugs.python.org/issue?@action=redirect&bpo=25590]: In the Readline completer, only call getattr() once per attribute.

bpo-25498 [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.

bpo-25584 [https://bugs.python.org/issue?@action=redirect&bpo=25584]: Added "escape" to the __all__ list in the glob module.

bpo-25584 [https://bugs.python.org/issue?@action=redirect&bpo=25584]: Fixed recursive glob() with patterns starting with **.

bpo-25446 [https://bugs.python.org/issue?@action=redirect&bpo=25446]: Fix regression in smtplib's AUTH LOGIN support.

bpo-18010 [https://bugs.python.org/issue?@action=redirect&bpo=18010]: Fix the pydoc web server's module search function to handle exceptions from importing packages.

bpo-25554 [https://bugs.python.org/issue?@action=redirect&bpo=25554]: Got rid of circular references in regular expression parsing.

bpo-25510 [https://bugs.python.org/issue?@action=redirect&bpo=25510]: fileinput.FileInput.readline() now returns b'' instead of '' at the end if the FileInput was opened with binary mode. Patch by Ryosuke Ito.

bpo-25503 [https://bugs.python.org/issue?@action=redirect&bpo=25503]: Fixed inspect.getdoc() for inherited docstrings of properties. Original patch by John Mark Vandenberg.

bpo-25515 [https://bugs.python.org/issue?@action=redirect&bpo=25515]: Always use os.urandom as a source of randomness in uuid.uuid4.

bpo-21827 [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.

bpo-25447 [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).

bpo-25390 [https://bugs.python.org/issue?@action=redirect&bpo=25390]: typing: Don't crash on Union[str, Pattern].

bpo-25441 [https://bugs.python.org/issue?@action=redirect&bpo=25441]: asyncio: Raise error from drain() when socket is closed.

bpo-25410 [https://bugs.python.org/issue?@action=redirect&bpo=25410]: Cleaned up and fixed minor bugs in C implementation of OrderedDict.

bpo-25411 [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.

bpo-25407 [https://bugs.python.org/issue?@action=redirect&bpo=25407]: Remove mentions of the formatter module being removed in Python 3.6.

bpo-25406 [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.

bpo-25364 [https://bugs.python.org/issue?@action=redirect&bpo=25364]: zipfile now works in threads disabled builds.

bpo-25328 [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.

bpo-25316 [https://bugs.python.org/issue?@action=redirect&bpo=25316]: distutils raises OSError instead of DistutilsPlatformError when MSVC is not installed.

bpo-25380 [https://bugs.python.org/issue?@action=redirect&bpo=25380]: Fixed protocol for the STACK_GLOBAL opcode in pickletools.opcodes.

bpo-23972 [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.

bpo-25304 [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.

bpo-25232 [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.

bpo-24657 [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.

bpo-24483 [https://bugs.python.org/issue?@action=redirect&bpo=24483]: C implementation of functools.lru_cache() now calculates key's hash only once.

bpo-22958 [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.

bpo-22609 [https://bugs.python.org/issue?@action=redirect&bpo=22609]: Constructor of collections.UserDict now accepts the self keyword argument.

bpo-25111 [https://bugs.python.org/issue?@action=redirect&bpo=25111]: Fixed comparison of traceback.FrameSummary.

bpo-25262 [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.

bpo-25034 [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.

bpo-25233 [https://bugs.python.org/issue?@action=redirect&bpo=25233]: Rewrite the guts of asyncio.Queue and asyncio.Semaphore to be more understandable and correct.

bpo-25203 [https://bugs.python.org/issue?@action=redirect&bpo=25203]: Failed readline.set_completer_delims() no longer left the module in inconsistent state.

bpo-23600 [https://bugs.python.org/issue?@action=redirect&bpo=23600]: Default implementation of tzinfo.fromutc() was returning wrong results in some cases.

bpo-23329 [https://bugs.python.org/issue?@action=redirect&bpo=23329]: Allow the ssl module to be built with older versions of LibreSSL.

Prevent overflow in _Unpickler_Read.

bpo-25047 [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.

bpo-25135 [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.

bpo-19143 [https://bugs.python.org/issue?@action=redirect&bpo=19143]: platform module now reads Windows version from kernel32.dll to avoid compatibility shims.

bpo-25092 [https://bugs.python.org/issue?@action=redirect&bpo=25092]: Fix datetime.strftime() failure when errno was already set to EINVAL.

bpo-23517 [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.

bpo-25155 [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.

bpo-25108 [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.

bpo-25118 [https://bugs.python.org/issue?@action=redirect&bpo=25118]: Fix a regression of Python 3.5.0 in os.waitpid() on Windows.

bpo-24684 [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.

bpo-25060 [https://bugs.python.org/issue?@action=redirect&bpo=25060]: Correctly compute stack usage of the BUILD_MAP opcode.

bpo-24857 [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.

bpo-23144 [https://bugs.python.org/issue?@action=redirect&bpo=23144]: Make sure that HTMLParser.feed() returns all the data, even when convert_charrefs is True.

bpo-24982 [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.

bpo-25019 [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.

bpo-16180 [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.

bpo-24891 [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.

bpo-24992 [https://bugs.python.org/issue?@action=redirect&bpo=24992]: Fix error handling and a race condition (related to garbage collection) in collections.OrderedDict constructor.

bpo-24881 [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.

bpo-25578 [https://bugs.python.org/issue?@action=redirect&bpo=25578]: Fix (another) memory leak in SSLSocket.getpeercer().

bpo-25530 [https://bugs.python.org/issue?@action=redirect&bpo=25530]: Disable the vulnerable SSLv3 protocol by default when creating ssl.SSLContext.

bpo-25569 [https://bugs.python.org/issue?@action=redirect&bpo=25569]: Fix memory leak in SSLSocket.getpeercert().

bpo-25471 [https://bugs.python.org/issue?@action=redirect&bpo=25471]: Sockets returned from accept() shouldn't appear to be nonblocking.

bpo-25319 [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.

bpo-21112 [https://bugs.python.org/issue?@action=redirect&bpo=21112]: Fix regression in unittest.expectedFailure on subclasses. Patch from Berker Peksag.

bpo-24764 [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.

bpo-24913 [https://bugs.python.org/issue?@action=redirect&bpo=24913]: Fix overrun error in deque.index(). Found by John Leitch and Bryce Darling.

bpo-24774 [https://bugs.python.org/issue?@action=redirect&bpo=24774]: Fix docstring in http.server.test. Patch from Chiu-Hsiang Hsu.

bpo-21159 [https://bugs.python.org/issue?@action=redirect&bpo=21159]: Improve message in configparser.InterpolationMissingOptionError. Patch from Łukasz Langa.

bpo-20362 [https://bugs.python.org/issue?@action=redirect&bpo=20362]: Honour TestCase.longMessage correctly in assertRegex. Patch from Ilia Kurenkov.

bpo-23572 [https://bugs.python.org/issue?@action=redirect&bpo=23572]: Fixed functools.singledispatch on classes with false metaclasses. Patch by Ethan Furman.

asyncio: ensure_future() now accepts awaitable objects.

IDLE

bpo-15348 [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.

bpo-24455 [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.

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.

bpo-24750 [https://bugs.python.org/issue?@action=redirect&bpo=24750]: Improve the appearance of the IDLE editor window status bar. Patch by Mark Roseman.

bpo-25313 [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.

bpo-24782 [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.

bpo-22726 [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.

bpo-24820 [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.

bpo-25224 [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'.

bpo-24820 [https://bugs.python.org/issue?@action=redirect&bpo=24820]: Users can now set breakpoint colors in Settings -> Custom Highlighting. Original patch by Mark Roseman.

bpo-24972 [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.

bpo-24570 [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.

bpo-24988 [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.

bpo-24801 [https://bugs.python.org/issue?@action=redirect&bpo=24801]: Make right-click for context menu work on Mac Aqua. Patch by Mark Roseman.

bpo-25173 [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.

bpo-25198 [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.

bpo-25225 [https://bugs.python.org/issue?@action=redirect&bpo=25225]: Condense and rewrite Idle doc section on text colors.

bpo-21995 [https://bugs.python.org/issue?@action=redirect&bpo=21995]: Explain some differences between IDLE and console Python.

bpo-22820 [https://bugs.python.org/issue?@action=redirect&bpo=22820]: Explain need for print when running file from Idle editor.

bpo-25224 [https://bugs.python.org/issue?@action=redirect&bpo=25224]: Doc: augment Idle feature list and no-subprocess section.

bpo-25219 [https://bugs.python.org/issue?@action=redirect&bpo=25219]: Update doc for Idle command line options. Some were missing and notes were not correct.

bpo-24861 [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__.

bpo-25199 [https://bugs.python.org/issue?@action=redirect&bpo=25199]: Idle: add synchronization comments for future maintainers.

bpo-16893 [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.

bpo-24199 [https://bugs.python.org/issue?@action=redirect&bpo=24199]: Deprecate unused idlelib.idlever with possible removal in 3.6.

bpo-24790 [https://bugs.python.org/issue?@action=redirect&bpo=24790]: Remove extraneous code (which also create 2 & 3 conflicts).

Documentation

bpo-22558 [https://bugs.python.org/issue?@action=redirect&bpo=22558]: Add remaining doc links to source code for Python-coded modules. Patch by Yoni Lavi.

bpo-12067 [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.

bpo-24952 [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.

bpo-23725 [https://bugs.python.org/issue?@action=redirect&bpo=23725]: Overhaul tempfile docs. Note deprecated status of mktemp. Patch from Zbigniew Jędrzejewski-Szmek.

bpo-24808 [https://bugs.python.org/issue?@action=redirect&bpo=24808]: Update the types of some PyTypeObject fields. Patch by Joseph Weston.

bpo-22812 [https://bugs.python.org/issue?@action=redirect&bpo=22812]: Fix unittest discovery examples. Patch from Pam McA'Nulty.

Tests

bpo-25449 [https://bugs.python.org/issue?@action=redirect&bpo=25449]: Added tests for OrderedDict subclasses.

bpo-25099 [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).

bpo-23919 [https://bugs.python.org/issue?@action=redirect&bpo=23919]: Prevents assert dialogs appearing in the test suite.

PCbuild\rt.bat now accepts an unlimited number of arguments to pass along to regrtest.py. Previously there was a limit of 9.

Build

bpo-24915 [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.

bpo-24910 [https://bugs.python.org/issue?@action=redirect&bpo=24910]: Windows MSIs now have unique display names.

bpo-24986 [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.

Windows

bpo-25450 [https://bugs.python.org/issue?@action=redirect&bpo=25450]: Updates shortcuts to start Python in installation directory.

bpo-25164 [https://bugs.python.org/issue?@action=redirect&bpo=25164]: Changes default all-users install directory to match per-user directory.

bpo-25143 [https://bugs.python.org/issue?@action=redirect&bpo=25143]: Improves installer error messages for unsupported platforms.

bpo-25163 [https://bugs.python.org/issue?@action=redirect&bpo=25163]: Display correct directory in installer when using non-default settings.

bpo-25361 [https://bugs.python.org/issue?@action=redirect&bpo=25361]: Disables use of SSE2 instructions in Windows 32-bit build

bpo-25089 [https://bugs.python.org/issue?@action=redirect&bpo=25089]: Adds logging to installer for case where launcher is not selected on upgrade.

bpo-25165 [https://bugs.python.org/issue?@action=redirect&bpo=25165]: Windows uninstallation should not remove launcher if other versions remain

bpo-25112 [https://bugs.python.org/issue?@action=redirect&bpo=25112]: py.exe launcher is missing icons

bpo-25102 [https://bugs.python.org/issue?@action=redirect&bpo=25102]: Windows installer does not precompile for -O or -OO.

bpo-25081 [https://bugs.python.org/issue?@action=redirect&bpo=25081]: Makes Back button in installer go back to upgrade page when upgrading.

bpo-25091 [https://bugs.python.org/issue?@action=redirect&bpo=25091]: Increases font size of the installer.

bpo-25126 [https://bugs.python.org/issue?@action=redirect&bpo=25126]: Clarifies that the non-web installer will download some components.

bpo-25213 [https://bugs.python.org/issue?@action=redirect&bpo=25213]: Restores requestedExecutionLevel to manifest to disable UAC virtualization.

bpo-25022 [https://bugs.python.org/issue?@action=redirect&bpo=25022]: Removed very outdated PC/example_nt/ directory.

Tools/Demos

bpo-25440 [https://bugs.python.org/issue?@action=redirect&bpo=25440]: Fix output of python-config --extension-suffix.

Python 3.5.0 final

Release date: 2015-09-13

Build

bpo-25071 [https://bugs.python.org/issue?@action=redirect&bpo=25071]: Windows installer should not require TargetDir parameter when installing quietly.

Python 3.5.0 release candidate 4

Release date: 2015-09-09

Library

bpo-25029 [https://bugs.python.org/issue?@action=redirect&bpo=25029]: Fixes MemoryError in test_strptime.

Build

bpo-25027 [https://bugs.python.org/issue?@action=redirect&bpo=25027]: Reverts partial-static build options and adds vcruntime140.dll to Windows installation.

Python 3.5.0 release candidate 3

Release date: 2015-09-07

Core and Builtins

bpo-24305 [https://bugs.python.org/issue?@action=redirect&bpo=24305]: Prevent import subsystem stack frames from being counted by the warnings.warn(stacklevel=) parameter.

bpo-24912 [https://bugs.python.org/issue?@action=redirect&bpo=24912]: Prevent __class__ assignment to immutable built-in objects.

bpo-24975 [https://bugs.python.org/issue?@action=redirect&bpo=24975]: Fix AST compilation for PEP 448 [https://peps.python.org/pep-0448/] syntax.

Library

bpo-24917 [https://bugs.python.org/issue?@action=redirect&bpo=24917]: time_strftime() buffer over-read.

bpo-24748 [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.

bpo-24635 [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.

bpo-24989 [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.

bpo-24913 [https://bugs.python.org/issue?@action=redirect&bpo=24913]: Fix overrun error in deque.index(). Found by John Leitch and Bryce Darling.

Python 3.5.0 release candidate 2

Release date: 2015-08-25

Core and Builtins

bpo-24769 [https://bugs.python.org/issue?@action=redirect&bpo=24769]: Interpreter now starts properly when dynamic loading is disabled. Patch by Petr Viktorin.

bpo-21167 [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.

bpo-24492 [https://bugs.python.org/issue?@action=redirect&bpo=24492]: A "package" lacking a __name__ attribute when trying to perform a from .. import ... statement will trigger an ImportError instead of an AttributeError.

Library

bpo-24847 [https://bugs.python.org/issue?@action=redirect&bpo=24847]: Removes vcruntime140.dll dependency from Tcl/Tk.

bpo-24839 [https://bugs.python.org/issue?@action=redirect&bpo=24839]: platform._syscmd_ver raises DeprecationWarning

bpo-24867 [https://bugs.python.org/issue?@action=redirect&bpo=24867]: Fix Task.get_stack() for 'async def' coroutines

Python 3.5.0 release candidate 1

Release date: 2015-08-09

Core and Builtins

bpo-24667 [https://bugs.python.org/issue?@action=redirect&bpo=24667]: Resize odict in all cases that the underlying dict resizes.

Library

bpo-24824 [https://bugs.python.org/issue?@action=redirect&bpo=24824]: Signatures of codecs.encode() and codecs.decode() now are compatible with pydoc.

bpo-24634 [https://bugs.python.org/issue?@action=redirect&bpo=24634]: Importing uuid should not try to load libc on Windows

bpo-24798 [https://bugs.python.org/issue?@action=redirect&bpo=24798]: _msvccompiler.py doesn't properly support manifests

bpo-4395 [https://bugs.python.org/issue?@action=redirect&bpo=4395]: Better testing and documentation of binary operators. Patch by Martin Panter.

bpo-23973 [https://bugs.python.org/issue?@action=redirect&bpo=23973]: Update typing.py from GitHub repo.

bpo-23004 [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.

bpo-23888 [https://bugs.python.org/issue?@action=redirect&bpo=23888]: Handle fractional time in cookie expiry. Patch by ssh.

bpo-23652 [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.

bpo-22932 [https://bugs.python.org/issue?@action=redirect&bpo=22932]: Fix timezones in email.utils.formatdate. Patch from Dmitry Shachnev.

bpo-23779 [https://bugs.python.org/issue?@action=redirect&bpo=23779]: imaplib raises TypeError if authenticator tries to abort. Patch from Craig Holmquist.

bpo-23319 [https://bugs.python.org/issue?@action=redirect&bpo=23319]: Fix ctypes.BigEndianStructure, swap correctly bytes. Patch written by Matthieu Gautier.

bpo-23254 [https://bugs.python.org/issue?@action=redirect&bpo=23254]: Document how to close the TCPServer listening socket. Patch from Martin Panter.

bpo-19450 [https://bugs.python.org/issue?@action=redirect&bpo=19450]: Update Windows and OS X installer builds to use SQLite 3.8.11.

bpo-17527 [https://bugs.python.org/issue?@action=redirect&bpo=17527]: Add PATCH to wsgiref.validator. Patch from Luca Sbardella.

bpo-24791 [https://bugs.python.org/issue?@action=redirect&bpo=24791]: Fix grammar regression for call syntax: 'g(*a or b)'.

IDLE

bpo-23672 [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.

bpo-24745 [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 'fontxxx' entries from [Editor Window]. Patch by Mark Roseman.

bpo-21192 [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.

bpo-13884 [https://bugs.python.org/issue?@action=redirect&bpo=13884]: Idle menus. Remove tearoff lines. Patch by Roger Serwy.

Documentation

bpo-24129 [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.

bpo-20769 [https://bugs.python.org/issue?@action=redirect&bpo=20769]: Improve reload() docs. Patch by Dorian Pula.

bpo-23589 [https://bugs.python.org/issue?@action=redirect&bpo=23589]: Remove duplicate sentence from the FAQ. Patch by Yongzhi Pan.

bpo-24729 [https://bugs.python.org/issue?@action=redirect&bpo=24729]: Correct IO tutorial to match implementation regarding encoding parameter to open function.

Tests

bpo-24751 [https://bugs.python.org/issue?@action=redirect&bpo=24751]: When running regrtest with the -w command line option, a test run is no longer marked as a failure if all tests succeed when re-run.

Python 3.5.0 beta 4

Release date: 2015-07-26

Core and Builtins

bpo-23573 [https://bugs.python.org/issue?@action=redirect&bpo=23573]: Restored optimization of bytes.rfind() and bytearray.rfind() for single-byte argument on Linux.

bpo-24569 [https://bugs.python.org/issue?@action=redirect&bpo=24569]: Make PEP 448 [https://peps.python.org/pep-0448/] dictionary evaluation more consistent.

bpo-24583 [https://bugs.python.org/issue?@action=redirect&bpo=24583]: Fix crash when set is mutated while being updated.

bpo-24407 [https://bugs.python.org/issue?@action=redirect&bpo=24407]: Fix crash when dict is mutated while being updated.

bpo-24619 [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.

bpo-24687 [https://bugs.python.org/issue?@action=redirect&bpo=24687]: Plug refleak on SyntaxError in function parameters annotations.

bpo-15944 [https://bugs.python.org/issue?@action=redirect&bpo=15944]: memoryview: Allow arbitrary formats when casting to bytes. Patch by Martin Panter.

Library

bpo-23441 [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.

bpo-24683 [https://bugs.python.org/issue?@action=redirect&bpo=24683]: Fixed crashes in _json functions called with arguments of inappropriate type.

bpo-21697 [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.

bpo-14373 [https://bugs.python.org/issue?@action=redirect&bpo=14373]: Fixed segmentation fault when gc.collect() is called during constructing lru_cache (C implementation).

bpo-24695 [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.

bpo-24620 [https://bugs.python.org/issue?@action=redirect&bpo=24620]: Random.setstate() now validates the value of state last element.

bpo-22485 [https://bugs.python.org/issue?@action=redirect&bpo=22485]: Fixed an issue that caused inspect.getsource to return incorrect results on nested functions.

bpo-22153 [https://bugs.python.org/issue?@action=redirect&bpo=22153]: Improve unittest docs. Patch from Martin Panter and evilzero.

bpo-24580 [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.

bpo-24206 [https://bugs.python.org/issue?@action=redirect&bpo=24206]: Fixed __eq__ and __ne__ methods of inspect classes.

bpo-24631 [https://bugs.python.org/issue?@action=redirect&bpo=24631]: Fixed regression in the timeit module with multiline setup.

bpo-18622 [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.

bpo-23661 [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

bpo-24608 [https://bugs.python.org/issue?@action=redirect&bpo=24608]: chunk.Chunk.read() now always returns bytes, not str.

bpo-18684 [https://bugs.python.org/issue?@action=redirect&bpo=18684]: Fixed reading out of the buffer in the re module.

bpo-24259 [https://bugs.python.org/issue?@action=redirect&bpo=24259]: tarfile now raises a ReadError if an archive is truncated inside a data segment.

bpo-15014 [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.

bpo-24669 [https://bugs.python.org/issue?@action=redirect&bpo=24669]: Fix inspect.getsource() for 'async def' functions. Patch by Kai Groner.

bpo-24688 [https://bugs.python.org/issue?@action=redirect&bpo=24688]: ast.get_docstring() for 'async def' functions.

Build

bpo-24603 [https://bugs.python.org/issue?@action=redirect&bpo=24603]: Update Windows builds and OS X 10.5 installer to use OpenSSL 1.0.2d.

Python 3.5.0 beta 3

Release date: 2015-07-05

Core and Builtins

bpo-24467 [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.

Upgrade to Unicode 8.0.0.

bpo-24345 [https://bugs.python.org/issue?@action=redirect&bpo=24345]: Add Py_tp_finalize slot for the stable ABI.

bpo-24400 [https://bugs.python.org/issue?@action=redirect&bpo=24400]: Introduce a distinct type for PEP 492 [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.

bpo-24450 [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.

bpo-19235 [https://bugs.python.org/issue?@action=redirect&bpo=19235]: Add new RecursionError exception. Patch by Georg Brandl.

Library

bpo-21750 [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.

bpo-24552 [https://bugs.python.org/issue?@action=redirect&bpo=24552]: Fix use after free in an error case of the _pickle module.

bpo-24514 [https://bugs.python.org/issue?@action=redirect&bpo=24514]: tarfile now tolerates number fields consisting of only whitespace.

bpo-19176 [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.

bpo-20387 [https://bugs.python.org/issue?@action=redirect&bpo=20387]: Restore semantic round-trip correctness in tokenize/untokenize for tab-indented blocks.

bpo-24456 [https://bugs.python.org/issue?@action=redirect&bpo=24456]: Fixed possible buffer over-read in adpcm2lin() and lin2adpcm() functions of the audioop module.

bpo-24336 [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.

bpo-24522 [https://bugs.python.org/issue?@action=redirect&bpo=24522]: Fix possible integer overflow in json accelerator module.

bpo-24489 [https://bugs.python.org/issue?@action=redirect&bpo=24489]: ensure a previously set C errno doesn't disturb cmath.polar().

bpo-24408 [https://bugs.python.org/issue?@action=redirect&bpo=24408]: Fixed AttributeError in measure() and metrics() methods of tkinter.Font.

bpo-14373 [https://bugs.python.org/issue?@action=redirect&bpo=14373]: C implementation of functools.lru_cache() now can be used with methods.

bpo-24347 [https://bugs.python.org/issue?@action=redirect&bpo=24347]: Set KeyError if PyDict_GetItemWithError returns NULL.

bpo-24348 [https://bugs.python.org/issue?@action=redirect&bpo=24348]: Drop superfluous incref/decref.

bpo-24359 [https://bugs.python.org/issue?@action=redirect&bpo=24359]: Check for changed OrderedDict size during iteration.

bpo-24368 [https://bugs.python.org/issue?@action=redirect&bpo=24368]: Support keyword arguments in OrderedDict methods.

bpo-24362 [https://bugs.python.org/issue?@action=redirect&bpo=24362]: Simplify the C OrderedDict fast nodes resize logic.

bpo-24377 [https://bugs.python.org/issue?@action=redirect&bpo=24377]: Fix a ref leak in OrderedDict.__repr__.

bpo-24369 [https://bugs.python.org/issue?@action=redirect&bpo=24369]: Defend against key-changes during iteration.

Tests

bpo-24373 [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 [https://bugs.python.org/issue?@action=redirect&bpo=16690] for details)

Documentation

bpo-24458 [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.

bpo-24351 [https://bugs.python.org/issue?@action=redirect&bpo=24351]: Clarify what is meant by "identifier" in the context of string.Template instances.

Build

bpo-24432 [https://bugs.python.org/issue?@action=redirect&bpo=24432]: Update Windows builds and OS X 10.5 installer to use OpenSSL 1.0.2c.

Python 3.5.0 beta 2

Release date: 2015-05-31

Core and Builtins

bpo-24284 [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.

bpo-24115 [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.

bpo-24328 [https://bugs.python.org/issue?@action=redirect&bpo=24328]: Fix importing one character extension modules.

bpo-11205 [https://bugs.python.org/issue?@action=redirect&bpo=11205]: In dictionary displays, evaluate the key before the value.

bpo-24285 [https://bugs.python.org/issue?@action=redirect&bpo=24285]: Fixed regression that prevented importing extension modules from inside packages. Patch by Petr Viktorin.

Library

bpo-23247 [https://bugs.python.org/issue?@action=redirect&bpo=23247]: Fix a crash in the StreamWriter.reset() of CJK codecs.

bpo-24270 [https://bugs.python.org/issue?@action=redirect&bpo=24270]: Add math.isclose() and cmath.isclose() functions as per PEP 485 [https://peps.python.org/pep-0485/]. Contributed by Chris Barker and Tal Einat.

bpo-5633 [https://bugs.python.org/issue?@action=redirect&bpo=5633]: Fixed timeit when the statement is a string and the setup is not.

bpo-24326 [https://bugs.python.org/issue?@action=redirect&bpo=24326]: Fixed audioop.ratecv() with non-default weightB argument. Original patch by David Moore.

bpo-16991 [https://bugs.python.org/issue?@action=redirect&bpo=16991]: Add a C implementation of OrderedDict.

bpo-23934 [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.

Python 3.5.0 beta 1

Release date: 2015-05-24

Core and Builtins

bpo-24276 [https://bugs.python.org/issue?@action=redirect&bpo=24276]: Fixed optimization of property descriptor getter.

bpo-24268 [https://bugs.python.org/issue?@action=redirect&bpo=24268]: PEP 489: Multi-phase extension module initialization. Patch by Petr Viktorin.

bpo-23955 [https://bugs.python.org/issue?@action=redirect&bpo=23955]: Add pyvenv.cfg option to suppress registry/environment lookup for generating sys.path on Windows.

bpo-24257 [https://bugs.python.org/issue?@action=redirect&bpo=24257]: Fixed system error in the comparison of faked types.SimpleNamespace.

bpo-22939 [https://bugs.python.org/issue?@action=redirect&bpo=22939]: Fixed integer overflow in iterator object. Patch by Clement Rouault.

bpo-23985 [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.

bpo-24102 [https://bugs.python.org/issue?@action=redirect&bpo=24102]: Fixed exception type checking in standard error handlers.

bpo-15027 [https://bugs.python.org/issue?@action=redirect&bpo=15027]: The UTF-32 encoder is now 3x to 7x faster.

bpo-23290 [https://bugs.python.org/issue?@action=redirect&bpo=23290]: Optimize set_merge() for cases where the target is empty. (Contributed by Serhiy Storchaka.)

bpo-2292 [https://bugs.python.org/issue?@action=redirect&bpo=2292]: PEP 448: Additional Unpacking Generalizations.

bpo-24096 [https://bugs.python.org/issue?@action=redirect&bpo=24096]: Make warnings.warn_explicit more robust against mutation of the warnings.filters list.

bpo-23996 [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.

bpo-23910 [https://bugs.python.org/issue?@action=redirect&bpo=23910]: Optimize property() getter calls. Patch by Joe Jevnik.

bpo-23911 [https://bugs.python.org/issue?@action=redirect&bpo=23911]: Move path-based importlib bootstrap code to a separate frozen module.

bpo-24192 [https://bugs.python.org/issue?@action=redirect&bpo=24192]: Fix namespace package imports.

bpo-24022 [https://bugs.python.org/issue?@action=redirect&bpo=24022]: Fix tokenizer crash when processing undecodable source code.

bpo-9951 [https://bugs.python.org/issue?@action=redirect&bpo=9951]: Added a hex() method to bytes, bytearray, and memoryview.

bpo-22906 [https://bugs.python.org/issue?@action=redirect&bpo=22906]: PEP 479: Change StopIteration handling inside generators.

bpo-24017 [https://bugs.python.org/issue?@action=redirect&bpo=24017]: PEP 492: Coroutines with async and await syntax.

Library

bpo-14373 [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.

bpo-24230 [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).

bpo-22189 [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.

bpo-24244 [https://bugs.python.org/issue?@action=redirect&bpo=24244]: Prevents termination when an invalid format string is encountered on Windows in strftime.

bpo-23973 [https://bugs.python.org/issue?@action=redirect&bpo=23973]: PEP 484: Add the typing module.

bpo-23086 [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.

bpo-20035 [https://bugs.python.org/issue?@action=redirect&bpo=20035]: Replaced the tkinter._fix module used for setting up the Tcl/Tk environment on Windows with a private function in the _tkinter module that makes no permanent changes to the environment.

bpo-24257 [https://bugs.python.org/issue?@action=redirect&bpo=24257]: Fixed segmentation fault in sqlite3.Row constructor with faked cursor type.

bpo-15836 [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.

bpo-9858 [https://bugs.python.org/issue?@action=redirect&bpo=9858]: Add missing method stubs to _io.RawIOBase. Patch by Laura Rupprecht.

bpo-22955 [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.

bpo-22107 [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.

bpo-23780 [https://bugs.python.org/issue?@action=redirect&bpo=23780]: Improved error message in os.path.join() with single argument.

bpo-6598 [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.

bpo-24091 [https://bugs.python.org/issue?@action=redirect&bpo=24091]: Fixed various crashes in corner cases in C implementation of ElementTree.

bpo-21931 [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.

bpo-13866 [https://bugs.python.org/issue?@action=redirect&bpo=13866]: quote_via argument added to urllib.parse.urlencode.

bpo-20098 [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.

bpo-24211 [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.

bpo-16314 [https://bugs.python.org/issue?@action=redirect&bpo=16314]: Added support for the LZMA compression in distutils.

bpo-21804 [https://bugs.python.org/issue?@action=redirect&bpo=21804]: poplib now supports RFC 6856 (UTF8).

bpo-18682 [https://bugs.python.org/issue?@action=redirect&bpo=18682]: Optimized pprint functions for builtin scalar types.

bpo-22027 [https://bugs.python.org/issue?@action=redirect&bpo=22027]: smtplib now supports RFC 6531 (SMTPUTF8).

bpo-23488 [https://bugs.python.org/issue?@action=redirect&bpo=23488]: Random generator objects now consume 2x less memory on 64-bit.

bpo-1322 [https://bugs.python.org/issue?@action=redirect&bpo=1322]: platform.dist() and platform.linux_distribution() functions are now deprecated. Initial patch by Vajrasky Kok.

bpo-22486 [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.

bpo-24064 [https://bugs.python.org/issue?@action=redirect&bpo=24064]: Property() docstrings are now writeable. (Patch by Berker Peksag.)

bpo-22681 [https://bugs.python.org/issue?@action=redirect&bpo=22681]: Added support for the koi8_t encoding.

bpo-22682 [https://bugs.python.org/issue?@action=redirect&bpo=22682]: Added support for the kz1048 encoding.

bpo-23796 [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.

bpo-21795 [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.

bpo-24155 [https://bugs.python.org/issue?@action=redirect&bpo=24155]: optimize heapq.heapify() for better cache performance when heapifying large lists.

bpo-21800 [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.

bpo-20274 [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.

bpo-20274 [https://bugs.python.org/issue?@action=redirect&bpo=20274]: Remove ignored and erroneous "kwargs" parameters from three METH_VARARGS methods on _sqlite.Connection.

bpo-24134 [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.

bpo-24018 [https://bugs.python.org/issue?@action=redirect&bpo=24018]: Add a collections.abc.Generator abstract base class. Contributed by Stefan Behnel.

bpo-23880 [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).

bpo-22619 [https://bugs.python.org/issue?@action=redirect&bpo=22619]: Added negative limit support in the traceback module. Based on patch by Dmitry Kazakov.

bpo-24094 [https://bugs.python.org/issue?@action=redirect&bpo=24094]: Fix possible crash in json.encode with poorly behaved dict subclasses.

bpo-9246 [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.

bpo-17445 [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).

bpo-23917 [https://bugs.python.org/issue?@action=redirect&bpo=23917]: Fall back to sequential compilation when ProcessPoolExecutor doesn't exist. Patch by Claudiu Popa.

bpo-23008 [https://bugs.python.org/issue?@action=redirect&bpo=23008]: Fixed resolving attributes with boolean value is False in pydoc.

Fix asyncio issue 235: LifoQueue and PriorityQueue's put didn't increment unfinished tasks (this bug was introduced when JoinableQueue was merged with Queue).

bpo-23908 [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.

bpo-23728 [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.

bpo-23887 [https://bugs.python.org/issue?@action=redirect&bpo=23887]: urllib.error.HTTPError now has a proper repr() representation. Patch by Berker Peksag.

asyncio: New event loop APIs: set_task_factory() and get_task_factory().

asyncio: async() function is deprecated in favour of ensure_future().

bpo-24178 [https://bugs.python.org/issue?@action=redirect&bpo=24178]: asyncio.Lock, Condition, Semaphore, and BoundedSemaphore support new 'async with' syntax. Contributed by Yury Selivanov.

bpo-24179 [https://bugs.python.org/issue?@action=redirect&bpo=24179]: Support 'async for' for asyncio.StreamReader. Contributed by Yury Selivanov.

bpo-24184 [https://bugs.python.org/issue?@action=redirect&bpo=24184]: Add AsyncIterator and AsyncIterable ABCs to collections.abc. Contributed by Yury Selivanov.

bpo-22547 [https://bugs.python.org/issue?@action=redirect&bpo=22547]: Implement informative __repr__ for inspect.BoundArguments. Contributed by Yury Selivanov.

bpo-24190 [https://bugs.python.org/issue?@action=redirect&bpo=24190]: Implement inspect.BoundArgument.apply_defaults() method. Contributed by Yury Selivanov.

bpo-20691 [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.

bpo-24248 [https://bugs.python.org/issue?@action=redirect&bpo=24248]: Deprecate inspect.Signature.from_function() and inspect.Signature.from_builtin().

bpo-23898 [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.

bpo-24298 [https://bugs.python.org/issue?@action=redirect&bpo=24298]: Fix inspect.signature() to correctly unwrap wrappers around bound methods.

IDLE

bpo-23184 [https://bugs.python.org/issue?@action=redirect&bpo=23184]: remove unused names and imports in idlelib. Initial patch by Al Sweigart.

Tests

bpo-21520 [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.

bpo-9517 [https://bugs.python.org/issue?@action=redirect&bpo=9517]: Move script_helper into the support package. Patch by Christie Wilson.

Documentation

bpo-22155 [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.

bpo-24029 [https://bugs.python.org/issue?@action=redirect&bpo=24029]: Document the name binding behavior for submodule imports.

bpo-24077 [https://bugs.python.org/issue?@action=redirect&bpo=24077]: Fix typo in man page for -I command option: -s, not -S

Tools/Demos

bpo-24000 [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.

bpo-24001 [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.

bpo-23330 [https://bugs.python.org/issue?@action=redirect&bpo=23330]: h2py now supports arbitrary filenames in #include.

bpo-24031 [https://bugs.python.org/issue?@action=redirect&bpo=24031]: make patchcheck now supports git checkouts, too.

Python 3.5.0 alpha 4

Release date: 2015-04-19

Core and Builtins

bpo-22980 [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 PEP 3149 [https://peps.python.org/pep-3149/]-style information.

bpo-22631 [https://bugs.python.org/issue?@action=redirect&bpo=22631]: Added Linux-specific socket constant CAN_RAW_FD_FRAMES. Patch courtesy of Joe Jevnik.

bpo-23731 [https://bugs.python.org/issue?@action=redirect&bpo=23731]: Implement PEP 488 [https://peps.python.org/pep-0488/]: removal of .pyo files.

bpo-23726 [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.

bpo-23309 [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.

bpo-22977 [https://bugs.python.org/issue?@action=redirect&bpo=22977]: Fixed formatting Windows error messages on Wine. Patch by Martin Panter.

bpo-23466 [https://bugs.python.org/issue?@action=redirect&bpo=23466]: %c, %o, %x, and %X in bytes formatting now raise TypeError on non-integer input.

bpo-24044 [https://bugs.python.org/issue?@action=redirect&bpo=24044]: Fix possible null pointer dereference in list.sort in out of memory conditions.

bpo-21354 [https://bugs.python.org/issue?@action=redirect&bpo=21354]: PyCFunction_New function is exposed by python DLL again.

Library

bpo-23840 [https://bugs.python.org/issue?@action=redirect&bpo=23840]: tokenize.open() now closes the temporary binary file on error to fix a resource warning.

bpo-16914 [https://bugs.python.org/issue?@action=redirect&bpo=16914]: new debuglevel 2 in smtplib adds timestamps to debug output.

bpo-7159 [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 [https://bugs.python.org/issue?@action=redirect&bpo=19494] and supersedes that change.

bpo-23703 [https://bugs.python.org/issue?@action=redirect&bpo=23703]: Fix a regression in urljoin() introduced in 901e4e52b20a. Patch by Demian Brecht.

bpo-4254 [https://bugs.python.org/issue?@action=redirect&bpo=4254]: Adds _curses.update_lines_cols(). Patch by Arnon Yaari

bpo-19933 [https://bugs.python.org/issue?@action=redirect&bpo=19933]: Provide default argument for ndigits in round. Patch by Vajrasky Kok.

bpo-23193 [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.

bpo-23342 [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.

bpo-21217 [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.

bpo-24521 [https://bugs.python.org/issue?@action=redirect&bpo=24521]: Fix possible integer overflows in the pickle module.

bpo-22931 [https://bugs.python.org/issue?@action=redirect&bpo=22931]: Allow '[' and ']' in cookie values.

The keywords attribute of functools.partial is now always a dictionary.

bpo-23811 [https://bugs.python.org/issue?@action=redirect&bpo=23811]: Add missing newline to the PyCompileError error message. Patch by Alex Shkop.

bpo-21116 [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.

bpo-22982 [https://bugs.python.org/issue?@action=redirect&bpo=22982]: Improve BOM handling when seeking to multiple positions of a writable text file.

bpo-23464 [https://bugs.python.org/issue?@action=redirect&bpo=23464]: Removed deprecated asyncio JoinableQueue.

bpo-23529 [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.

bpo-21859 [https://bugs.python.org/issue?@action=redirect&bpo=21859]: Added Python implementation of io.FileIO.

bpo-23865 [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.

bpo-23400 [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.

bpo-10838 [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 from subprocess import *.

bpo-23411 [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.

bpo-23881 [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.

bpo-23853 [https://bugs.python.org/issue?@action=redirect&bpo=23853]: 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.

bpo-22721 [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.

bpo-15133 [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.

bpo-10590 [https://bugs.python.org/issue?@action=redirect&bpo=10590]: xml.sax.parseString() now supports string argument.

bpo-23338 [https://bugs.python.org/issue?@action=redirect&bpo=23338]: Fixed formatting ctypes error messages on Cygwin. Patch by Makoto Kato.

bpo-15582 [https://bugs.python.org/issue?@action=redirect&bpo=15582]: inspect.getdoc() now follows inheritance chains.

bpo-2175 [https://bugs.python.org/issue?@action=redirect&bpo=2175]: SAX parsers now support a character stream of InputSource object.

bpo-16840 [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.

bpo-23834 [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.

bpo-23618 [https://bugs.python.org/issue?@action=redirect&bpo=23618]: socket.socket.connect() now waits until the connection completes instead of raising InterruptedError if the connection is interrupted by signals, signal handlers don't raise an exception and the socket is blocking or has a timeout. socket.socket.connect() still raise InterruptedError for non-blocking sockets.

bpo-21526 [https://bugs.python.org/issue?@action=redirect&bpo=21526]: Tkinter now supports new boolean type in Tcl 8.5.

bpo-23836 [https://bugs.python.org/issue?@action=redirect&bpo=23836]: Fix the faulthandler module to handle reentrant calls to its signal handlers.

bpo-23838 [https://bugs.python.org/issue?@action=redirect&bpo=23838]: linecache now clears the cache and returns an empty result on MemoryError.

bpo-10395 [https://bugs.python.org/issue?@action=redirect&bpo=10395]: Added os.path.commonpath(). Implemented in posixpath and ntpath. Based on patch by Rafik Draoui.

bpo-23611 [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.

bpo-13583 [https://bugs.python.org/issue?@action=redirect&bpo=13583]: sqlite3.Row now supports slice indexing.

bpo-18473 [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.

bpo-23485 [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 PEP 475 [https://peps.python.org/pep-0475/].

bpo-23752 [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.

bpo-23704 [https://bugs.python.org/issue?@action=redirect&bpo=23704]: collections.deque() objects now support __add__, __mul__, and __imul__().

bpo-23171 [https://bugs.python.org/issue?@action=redirect&bpo=23171]: csv.Writer.writerow() now supports arbitrary iterables.

bpo-23745 [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.

bpo-22117 [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.

bpo-23310 [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.

Build

bpo-23817 [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".

bpo-23501 [https://bugs.python.org/issue?@action=redirect&bpo=23501]: Argument Clinic now generates code into separate files by default.

Tests

bpo-23799 [https://bugs.python.org/issue?@action=redirect&bpo=23799]: Added test.support.start_threads() for running and cleaning up multiple threads.

bpo-22390 [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.

Tools/Demos

bpo-18128 [https://bugs.python.org/issue?@action=redirect&bpo=18128]: pygettext now uses standard +NNNN format in the POT-Creation-Date header.

bpo-23935 [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.

bpo-23944 [https://bugs.python.org/issue?@action=redirect&bpo=23944]: Argument Clinic now wraps long impl prototypes at column 78.

bpo-20586 [https://bugs.python.org/issue?@action=redirect&bpo=20586]: Argument Clinic now ensures that functions without docstrings have signatures.

bpo-23492 [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.

bpo-23500 [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.

C API

bpo-23998 [https://bugs.python.org/issue?@action=redirect&bpo=23998]: PyImport_ReInitLock() now checks for lock allocation error

Python 3.5.0 alpha 3

Release date: 2015-03-28

Core and Builtins

bpo-23573 [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).

bpo-23753 [https://bugs.python.org/issue?@action=redirect&bpo=23753]: Python doesn't support anymore platforms without stat() or fstat(), these functions are always required.

bpo-23681 [https://bugs.python.org/issue?@action=redirect&bpo=23681]: The -b option now affects comparisons of bytes with int.

bpo-23632 [https://bugs.python.org/issue?@action=redirect&bpo=23632]: Memoryviews now allow tuple indexing (including for multi-dimensional memoryviews).

bpo-23192 [https://bugs.python.org/issue?@action=redirect&bpo=23192]: Fixed generator lambdas. Patch by Bruno Cauet.

bpo-23629 [https://bugs.python.org/issue?@action=redirect&bpo=23629]: Fix the default __sizeof__ implementation for variable-sized objects.

Library

bpo-14260 [https://bugs.python.org/issue?@action=redirect&bpo=14260]: The groupindex attribute of regular expression pattern object now is non-modifiable mapping.

bpo-23792 [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.

bpo-23775 [https://bugs.python.org/issue?@action=redirect&bpo=23775]: pprint() of OrderedDict now outputs the same representation as repr().

bpo-23765 [https://bugs.python.org/issue?@action=redirect&bpo=23765]: Removed IsBadStringPtr calls in ctypes

bpo-22364 [https://bugs.python.org/issue?@action=redirect&bpo=22364]: Improved some re error messages using regex for hints.

bpo-23742 [https://bugs.python.org/issue?@action=redirect&bpo=23742]: ntpath.expandvars() no longer loses unbalanced single quotes.

bpo-21717 [https://bugs.python.org/issue?@action=redirect&bpo=21717]: The zipfile.ZipFile.open function now supports 'x' (exclusive creation) mode.

bpo-21802 [https://bugs.python.org/issue?@action=redirect&bpo=21802]: The reader in BufferedRWPair now is closed even when closing writer failed in BufferedRWPair.close().

bpo-23622 [https://bugs.python.org/issue?@action=redirect&bpo=23622]: Unknown escapes in regular expressions that consist of '\' and ASCII letter now raise a deprecation warning and will be forbidden in Python 3.6.

bpo-23671 [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.

bpo-23502 [https://bugs.python.org/issue?@action=redirect&bpo=23502]: The pprint module now supports mapping proxies.

bpo-17530 [https://bugs.python.org/issue?@action=redirect&bpo=17530]: pprint now wraps long bytes objects and bytearrays.

bpo-22687 [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.

bpo-4727 [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.

bpo-23491 [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).

bpo-23657 [https://bugs.python.org/issue?@action=redirect&bpo=23657]: Avoid explicit checks for str in zipapp, adding support for pathlib.Path objects as arguments.

bpo-23688 [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.

bpo-23252 [https://bugs.python.org/issue?@action=redirect&bpo=23252]: Added support for writing ZIP files to unseekable streams.

bpo-23647 [https://bugs.python.org/issue?@action=redirect&bpo=23647]: Increase imaplib's MAXLINE to accommodate modern mailbox sizes.

bpo-23539 [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.

bpo-22351 [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.

bpo-23704 [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.

bpo-23715 [https://bugs.python.org/issue?@action=redirect&bpo=23715]: signal.sigwaitinfo() and 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.

bpo-23001 [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.

bpo-23646 [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).

bpo-23136 [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.

bpo-23700 [https://bugs.python.org/issue?@action=redirect&bpo=23700]: Iterator of NamedTemporaryFile now keeps a reference to NamedTemporaryFile instance. Patch by Bohuslav Kabrda.

bpo-22903 [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.

bpo-22181 [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.

bpo-2211 [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.

bpo-18983 [https://bugs.python.org/issue?@action=redirect&bpo=18983]: Allow selection of output units in timeit. Patch by Julian Gindi.

bpo-23631 [https://bugs.python.org/issue?@action=redirect&bpo=23631]: Fix traceback.format_list when a traceback has been mutated.

bpo-23568 [https://bugs.python.org/issue?@action=redirect&bpo=23568]: Add rdivmod support to MagicMock() objects. Patch by Håkan Lövdahl.

bpo-2052 [https://bugs.python.org/issue?@action=redirect&bpo=2052]: Add charset parameter to HtmlDiff.make_file().

bpo-23668 [https://bugs.python.org/issue?@action=redirect&bpo=23668]: Support os.truncate and os.ftruncate on Windows.

bpo-23138 [https://bugs.python.org/issue?@action=redirect&bpo=23138]: Fixed parsing cookies with absent keys or values in cookiejar. Patch by Demian Brecht.

bpo-23051 [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.

bpo-23581 [https://bugs.python.org/issue?@action=redirect&bpo=23581]: Add matmul support to MagicMock. Patch by Håkan Lövdahl.

bpo-23566 [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.

bpo-22928 [https://bugs.python.org/issue?@action=redirect&bpo=22928]: Disabled HTTP header injections in http.client. Original patch by Demian Brecht.

bpo-23615 [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.

bpo-23605 [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.

Build

bpo-23585 [https://bugs.python.org/issue?@action=redirect&bpo=23585]: make patchcheck will ensure the interpreter is built.

Tests

bpo-23583 [https://bugs.python.org/issue?@action=redirect&bpo=23583]: Added tests for standard IO streams in IDLE.

bpo-22289 [https://bugs.python.org/issue?@action=redirect&bpo=22289]: Prevent test_urllib2net failures due to ftp connection timeout.

Tools/Demos

bpo-22826 [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).

Python 3.5.0 alpha 2

Release date: 2015-03-09

Core and Builtins

bpo-23571 [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.

Library

bpo-22524 [https://bugs.python.org/issue?@action=redirect&bpo=22524]: New os.scandir() function, part of the PEP 471 [https://peps.python.org/pep-0471/]: "os.scandir() function -- a better and faster directory iterator". Patch written by Ben Hoyt.

bpo-23103 [https://bugs.python.org/issue?@action=redirect&bpo=23103]: Reduced the memory consumption of IPv4Address and IPv6Address.

bpo-21793 [https://bugs.python.org/issue?@action=redirect&bpo=21793]: BaseHTTPRequestHandler again logs response code as numeric, not as stringified enum. Patch by Demian Brecht.

bpo-23476 [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.

bpo-23576 [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.

bpo-23504 [https://bugs.python.org/issue?@action=redirect&bpo=23504]: Added an __all__ to the types module.

bpo-23563 [https://bugs.python.org/issue?@action=redirect&bpo=23563]: Optimized utility functions in urllib.parse.

bpo-7830 [https://bugs.python.org/issue?@action=redirect&bpo=7830]: Flatten nested functools.partial.

bpo-20204 [https://bugs.python.org/issue?@action=redirect&bpo=20204]: Added the __module__ attribute to _tkinter classes.

bpo-19980 [https://bugs.python.org/issue?@action=redirect&bpo=19980]: Improved help() for non-recognized strings. help('') now shows the help on str. help('help') now shows the help on help(). Original patch by Mark Lawrence.

bpo-23521 [https://bugs.python.org/issue?@action=redirect&bpo=23521]: Corrected pure python implementation of timedelta division. Eliminated OverflowError from timedelta * float for some floats; Corrected rounding in timedelta true division.

bpo-21619 [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.

bpo-22936 [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.

bpo-15955 [https://bugs.python.org/issue?@action=redirect&bpo=15955]: Add an option to limit the output size in bz2.decompress(). Patch by Nikolaus Rath.

bpo-6639 [https://bugs.python.org/issue?@action=redirect&bpo=6639]: Module-level turtle functions no longer raise TclError after closing the window.

bpo-814253 [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 [https://bugs.python.org/issue?@action=redirect&bpo=9179])

bpo-23215 [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.

bpo-5700 [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.

bpo-23374 [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).

bpo-23481 [https://bugs.python.org/issue?@action=redirect&bpo=23481]: Remove RC4 from the SSL module's default cipher list.

bpo-21548 [https://bugs.python.org/issue?@action=redirect&bpo=21548]: Fix pydoc.synopsis() and pydoc.apropos() on modules with empty docstrings.

bpo-22885 [https://bugs.python.org/issue?@action=redirect&bpo=22885]: Fixed arbitrary code execution vulnerability in the dbm.dumb module. Original patch by Claudiu Popa.

bpo-23239 [https://bugs.python.org/issue?@action=redirect&bpo=23239]: ssl.match_hostname() now supports matching of IP addresses.

bpo-23146 [https://bugs.python.org/issue?@action=redirect&bpo=23146]: Fix mishandling of absolute Windows paths with forward slashes in pathlib.

bpo-23096 [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.

bpo-19105 [https://bugs.python.org/issue?@action=redirect&bpo=19105]: pprint now more efficiently uses free space at the right.

bpo-14910 [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.

bpo-21717 [https://bugs.python.org/issue?@action=redirect&bpo=21717]: tarfile.open() now supports 'x' (exclusive creation) mode.

bpo-23344 [https://bugs.python.org/issue?@action=redirect&bpo=23344]: marshal.dumps() is now 20-25% faster on average.

bpo-20416 [https://bugs.python.org/issue?@action=redirect&bpo=20416]: marshal.dumps() with protocols 3 and 4 is now 40-50% faster on average.

bpo-23421 [https://bugs.python.org/issue?@action=redirect&bpo=23421]: Fixed compression in tarfile CLI. Patch by wdv4758h.

bpo-23367 [https://bugs.python.org/issue?@action=redirect&bpo=23367]: Fix possible overflows in the unicodedata module.

bpo-23361 [https://bugs.python.org/issue?@action=redirect&bpo=23361]: Fix possible overflow in Windows subprocess creation code.

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.

bpo-19705 [https://bugs.python.org/issue?@action=redirect&bpo=19705]: turtledemo now has a visual sorting algorithm demo. Original patch from Jason Yeo.

bpo-23801 [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.

Build

bpo-23445 [https://bugs.python.org/issue?@action=redirect&bpo=23445]: pydebug builds now use "gcc -Og" where possible, to make the resulting executable faster.

bpo-23686 [https://bugs.python.org/issue?@action=redirect&bpo=23686]: Update OS X 10.5 installer build to use OpenSSL 1.0.2a.

C API

bpo-20204 [https://bugs.python.org/issue?@action=redirect&bpo=20204]: Deprecation warning is now raised for builtin types without the __module__ attribute.

Windows

bpo-23465 [https://bugs.python.org/issue?@action=redirect&bpo=23465]: Implement PEP 486 [https://peps.python.org/pep-0486/] - Make the Python Launcher aware of virtual environments. Patch by Paul Moore.

bpo-23437 [https://bugs.python.org/issue?@action=redirect&bpo=23437]: Make user scripts directory versioned on Windows. Patch by Paul Moore.

Python 3.5.0 alpha 1

Release date: 2015-02-08

Core and Builtins

bpo-23285 [https://bugs.python.org/issue?@action=redirect&bpo=23285]: PEP 475 - EINTR handling.

bpo-22735 [https://bugs.python.org/issue?@action=redirect&bpo=22735]: Fix many edge cases (including crashes) involving custom mro() implementations.

bpo-22896 [https://bugs.python.org/issue?@action=redirect&bpo=22896]: Avoid using PyObject_AsCharBuffer(), PyObject_AsReadBuffer() and PyObject_AsWriteBuffer().

bpo-21295 [https://bugs.python.org/issue?@action=redirect&bpo=21295]: Revert some changes (bpo-16795 [https://bugs.python.org/issue?@action=redirect&bpo=16795]) to AST line numbers and column offsets that constituted a regression.

bpo-22986 [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.

bpo-15859 [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.

bpo-21408 [https://bugs.python.org/issue?@action=redirect&bpo=21408]: The default __ne__() now returns NotImplemented if __eq__() returned NotImplemented. Original patch by Martin Panter.

bpo-23321 [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.

bpo-22286 [https://bugs.python.org/issue?@action=redirect&bpo=22286]: The "backslashreplace" error handlers now works with decoding and translating.

bpo-23253 [https://bugs.python.org/issue?@action=redirect&bpo=23253]: Delay-load ShellExecute[AW] in os.startfile for reduced startup overhead on Windows.

bpo-22038 [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.

bpo-20284 [https://bugs.python.org/issue?@action=redirect&bpo=20284]: %-interpolation (aka printf) formatting added for bytes and bytearray.

bpo-23048 [https://bugs.python.org/issue?@action=redirect&bpo=23048]: Fix jumping out of an infinite while loop in the pdb.

bpo-20335 [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.

bpo-22834 [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.

bpo-22869 [https://bugs.python.org/issue?@action=redirect&bpo=22869]: Move the interpreter startup & shutdown code to a new dedicated pylifecycle.c module

bpo-22847 [https://bugs.python.org/issue?@action=redirect&bpo=22847]: Improve method cache efficiency.

bpo-22335 [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.

bpo-22653 [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.

bpo-22643 [https://bugs.python.org/issue?@action=redirect&bpo=22643]: Fix integer overflow in Unicode case operations (upper, lower, title, swapcase, casefold).

bpo-17636 [https://bugs.python.org/issue?@action=redirect&bpo=17636]: Circular imports involving relative imports are now supported.

bpo-22604 [https://bugs.python.org/issue?@action=redirect&bpo=22604]: Fix assertion error in debug mode when dividing a complex number by (nan+0j).

bpo-21052 [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.

bpo-16518 [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.

bpo-22470 [https://bugs.python.org/issue?@action=redirect&bpo=22470]: Fixed integer overflow issues in "backslashreplace", "xmlcharrefreplace", and "surrogatepass" error handlers.

bpo-22540 [https://bugs.python.org/issue?@action=redirect&bpo=22540]: speed up PyObject_IsInstance and PyObject_IsSubclass in the common case that the second argument has metaclass type.

bpo-18711 [https://bugs.python.org/issue?@action=redirect&bpo=18711]: Add a new PyErr_FormatV function, similar to PyErr_Format but accepting a va_list argument.

bpo-22520 [https://bugs.python.org/issue?@action=redirect&bpo=22520]: Fix overflow checking when generating the repr of a unicode object.

bpo-22519 [https://bugs.python.org/issue?@action=redirect&bpo=22519]: Fix overflow checking in PyBytes_Repr.

bpo-22518 [https://bugs.python.org/issue?@action=redirect&bpo=22518]: Fix integer overflow issues in latin-1 encoding.

bpo-16324 [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.

bpo-1764286 [https://bugs.python.org/issue?@action=redirect&bpo=1764286]: Fix inspect.getsource() to support decorated functions. Patch by Claudiu Popa.

bpo-18554 [https://bugs.python.org/issue?@action=redirect&bpo=18554]: os.__all__ includes posix functions.

bpo-21391 [https://bugs.python.org/issue?@action=redirect&bpo=21391]: Use os.path.abspath in the shutil module.

bpo-11471 [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.

bpo-22215 [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.

bpo-22258 [https://bugs.python.org/issue?@action=redirect&bpo=22258]: Fix the internal function set_inheritable() on Illumos. This platform exposes the function ioctl(FIOCLEX), but calling it fails with errno is ENOTTY: "Inappropriate ioctl for device". set_inheritable() now falls back to the slower fcntl() (F_GETFD and then F_SETFD).

bpo-21389 [https://bugs.python.org/issue?@action=redirect&bpo=21389]: Displaying the __qualname__ of the underlying function in the repr of a bound method.

bpo-22206 [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.

bpo-20184 [https://bugs.python.org/issue?@action=redirect&bpo=20184]: Argument Clinic based signature introspection added for 30 of the builtin functions.

bpo-22116 [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.

bpo-22077 [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.

bpo-20179 [https://bugs.python.org/issue?@action=redirect&bpo=20179]: Apply Argument Clinic to bytes and bytearray. Patch by Tal Einat.

bpo-22082 [https://bugs.python.org/issue?@action=redirect&bpo=22082]: Clear interned strings in slotdefs.

Upgrade Unicode database to Unicode 7.0.0.

bpo-21897 [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.

bpo-21205 [https://bugs.python.org/issue?@action=redirect&bpo=21205]: Add a new __qualname__ attribute to generator, the qualified name, and use it in the representation of a generator (repr(gen)). The default name of the generator (__name__ attribute) is now get from the function instead of the code. Use gen.gi_code.co_name to get the name of the code.

bpo-21669 [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.

bpo-21642 [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 else keyword (e.g. True if 42else False) to be valid syntax.

bpo-21523 [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.

bpo-21418 [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).

bpo-21425 [https://bugs.python.org/issue?@action=redirect&bpo=21425]: Fix flushing of standard streams in the interactive interpreter.

bpo-21435 [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.

bpo-21377 [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.

bpo-20355 [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.

bpo-21274 [https://bugs.python.org/issue?@action=redirect&bpo=21274]: Define PATH_MAX for GNU/Hurd in Python/pythonrun.c.

bpo-20904 [https://bugs.python.org/issue?@action=redirect&bpo=20904]: Support setting FPU precision on m68k.

bpo-21209 [https://bugs.python.org/issue?@action=redirect&bpo=21209]: Fix sending tuples to custom generator objects with the yield from syntax.

bpo-21193 [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.

bpo-21176 [https://bugs.python.org/issue?@action=redirect&bpo=21176]: PEP 465: Add the '@' operator for matrix multiplication.

bpo-21134 [https://bugs.python.org/issue?@action=redirect&bpo=21134]: Fix segfault when str is called on an uninitialized UnicodeEncodeError, UnicodeDecodeError, or UnicodeTranslateError object.

bpo-19537 [https://bugs.python.org/issue?@action=redirect&bpo=19537]: Fix PyUnicode_DATA() alignment under m68k. Patch by Andreas Schwab.

bpo-20929 [https://bugs.python.org/issue?@action=redirect&bpo=20929]: Add a type cast to avoid shifting a negative number.

bpo-20731 [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.

bpo-20637 [https://bugs.python.org/issue?@action=redirect&bpo=20637]: Key-sharing now also works for instance dictionaries of subclasses. Patch by Peter Ingebretson.

bpo-8297 [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.

bpo-19995 [https://bugs.python.org/issue?@action=redirect&bpo=19995]: %c, %o, %x, and %X now raise TypeError on non-integer input.

bpo-19655 [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.

bpo-12546 [https://bugs.python.org/issue?@action=redirect&bpo=12546]: Allow \x00 to be used as a fill character when using str, int, float, and complex __format__ methods.

bpo-20480 [https://bugs.python.org/issue?@action=redirect&bpo=20480]: Add ipaddress.reverse_pointer. Patch by Leon Weber.

bpo-13598 [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.

bpo-8931 [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.

bpo-23165 [https://bugs.python.org/issue?@action=redirect&bpo=23165]: Perform overflow checks before allocating memory in the _Py_char2wchar function.

Library

bpo-23399 [https://bugs.python.org/issue?@action=redirect&bpo=23399]: pyvenv creates relative symlinks where possible.

bpo-20289 [https://bugs.python.org/issue?@action=redirect&bpo=20289]: cgi.FieldStorage() now supports the context management protocol.

bpo-13128 [https://bugs.python.org/issue?@action=redirect&bpo=13128]: Print response headers for CONNECT requests when debuglevel > 0. Patch by Demian Brecht.

bpo-15381 [https://bugs.python.org/issue?@action=redirect&bpo=15381]: Optimized io.BytesIO to make less allocations and copyings.

bpo-22818 [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.

bpo-23099 [https://bugs.python.org/issue?@action=redirect&bpo=23099]: Closing io.BytesIO with exported buffer is rejected now to prevent corrupting exported buffer.

bpo-23326 [https://bugs.python.org/issue?@action=redirect&bpo=23326]: Removed __ne__ implementations. Since fixing default __ne__ implementation in bpo-21408 [https://bugs.python.org/issue?@action=redirect&bpo=21408] they are redundant.

bpo-23363 [https://bugs.python.org/issue?@action=redirect&bpo=23363]: Fix possible overflow in itertools.permutations.

bpo-23364 [https://bugs.python.org/issue?@action=redirect&bpo=23364]: Fix possible overflow in itertools.product.

bpo-23366 [https://bugs.python.org/issue?@action=redirect&bpo=23366]: Fixed possible integer overflow in itertools.combinations.

bpo-23369 [https://bugs.python.org/issue?@action=redirect&bpo=23369]: Fixed possible integer overflow in _json.encode_basestring_ascii.

bpo-23353 [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.

bpo-14099 [https://bugs.python.org/issue?@action=redirect&bpo=14099]: Restored support of writing ZIP files to tellable but non-seekable streams.

bpo-14099 [https://bugs.python.org/issue?@action=redirect&bpo=14099]: Writing to ZipFile and reading multiple ZipExtFiles is threadsafe now.

bpo-19361 [https://bugs.python.org/issue?@action=redirect&bpo=19361]: JSON decoder now raises JSONDecodeError instead of ValueError.

bpo-18518 [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").

bpo-23094 [https://bugs.python.org/issue?@action=redirect&bpo=23094]: Fixed readline with frames in Python implementation of pickle.

bpo-23268 [https://bugs.python.org/issue?@action=redirect&bpo=23268]: Fixed bugs in the comparison of ipaddress classes.

bpo-21408 [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.

bpo-19996 [https://bugs.python.org/issue?@action=redirect&bpo=19996]: email.feedparser.FeedParser now handles (malformed) headers with no key rather than assuming the body has started.

bpo-20188 [https://bugs.python.org/issue?@action=redirect&bpo=20188]: Support Application-Layer Protocol Negotiation (ALPN) in the ssl module.

bpo-23133 [https://bugs.python.org/issue?@action=redirect&bpo=23133]: Pickling of ipaddress objects now produces more compact and portable representation.

bpo-23248 [https://bugs.python.org/issue?@action=redirect&bpo=23248]: Update ssl error codes from latest OpenSSL git master.

bpo-23266 [https://bugs.python.org/issue?@action=redirect&bpo=23266]: Much faster implementation of ipaddress.collapse_addresses() when there are many non-consecutive addresses.

bpo-23098 [https://bugs.python.org/issue?@action=redirect&bpo=23098]: 64-bit dev_t is now supported in the os module.

bpo-21817 [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.

bpo-15955 [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.

bpo-23250 [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.

bpo-23063 [https://bugs.python.org/issue?@action=redirect&bpo=23063]: In the distutils' check command, fix parsing of reST with code or code-block directives.

bpo-23209 [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 [https://bugs.python.org/issue?@action=redirect&bpo=23225])

bpo-17911 [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.

bpo-17911 [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.

bpo-19777 [https://bugs.python.org/issue?@action=redirect&bpo=19777]: Provide a home() classmethod on Path objects. Contributed by Victor Salgado and Mayank Tripathi.

bpo-23206 [https://bugs.python.org/issue?@action=redirect&bpo=23206]: Make json.dumps(..., ensure_ascii=False) as fast as the default case of ensure_ascii=True. Patch by Naoki Inada.

bpo-23185 [https://bugs.python.org/issue?@action=redirect&bpo=23185]: Add math.inf and math.nan constants.

bpo-23186 [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.

bpo-23143 [https://bugs.python.org/issue?@action=redirect&bpo=23143]: Remove compatibility with OpenSSLs older than 0.9.8.

bpo-23132 [https://bugs.python.org/issue?@action=redirect&bpo=23132]: Improve performance and introspection support of comparison methods created by functool.total_ordering.

bpo-19776 [https://bugs.python.org/issue?@action=redirect&bpo=19776]: Add an expanduser() method on Path objects.

bpo-23112 [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.

bpo-21793 [https://bugs.python.org/issue?@action=redirect&bpo=21793]: Added http.HTTPStatus enums (i.e. HTTPStatus.OK, HTTPStatus.NOT_FOUND). Patch by Demian Brecht.

bpo-23093 [https://bugs.python.org/issue?@action=redirect&bpo=23093]: In the io, module allow more operations to work on detached streams.

bpo-23111 [https://bugs.python.org/issue?@action=redirect&bpo=23111]: In the ftplib, make ssl.PROTOCOL_SSLv23 the default protocol version.

bpo-22585 [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.

bpo-19104 [https://bugs.python.org/issue?@action=redirect&bpo=19104]: pprint now produces evaluable output for wrapped strings.

bpo-23071 [https://bugs.python.org/issue?@action=redirect&bpo=23071]: Added missing names to codecs.__all__. Patch by Martin Panter.

bpo-22783 [https://bugs.python.org/issue?@action=redirect&bpo=22783]: Pickling now uses the NEWOBJ opcode instead of the NEWOBJ_EX opcode if possible.

bpo-15513 [https://bugs.python.org/issue?@action=redirect&bpo=15513]: Added a __sizeof__ implementation for pickle classes.

bpo-19858 [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.

bpo-22095 [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.

bpo-23016 [https://bugs.python.org/issue?@action=redirect&bpo=23016]: A warning no longer produces an AttributeError when the program is run with pythonw.exe.

bpo-21775 [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.

bpo-1218234 [https://bugs.python.org/issue?@action=redirect&bpo=1218234]: Fix inspect.getsource() to load updated source of reloaded module. Initial patch by Berker Peksag.

bpo-21740 [https://bugs.python.org/issue?@action=redirect&bpo=21740]: Support wrapped callables in doctest. Patch by Claudiu Popa.

bpo-23009 [https://bugs.python.org/issue?@action=redirect&bpo=23009]: Make sure selectors.EpollSelector.select() works when no FD is registered.

bpo-22959 [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.

bpo-22696 [https://bugs.python.org/issue?@action=redirect&bpo=22696]: Add function sys.is_finalizing() to know about interpreter shutdown.

bpo-16043 [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 CVE-2013-1753 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2013-1753].

bpo-14099 [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.

bpo-22966 [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.

bpo-21971 [https://bugs.python.org/issue?@action=redirect&bpo=21971]: Update turtledemo doc and add module to the index.

bpo-21032 [https://bugs.python.org/issue?@action=redirect&bpo=21032]: Fixed socket leak if HTTPConnection.getresponse() fails. Original patch by Martin Panter.

bpo-22407 [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.

bpo-22902 [https://bugs.python.org/issue?@action=redirect&bpo=22902]: The "ip" command is now used on Linux to determine MAC address in uuid.getnode(). Pach by Bruno Cauet.

bpo-22960 [https://bugs.python.org/issue?@action=redirect&bpo=22960]: Add a context argument to xmlrpclib.ServerProxy constructor.

bpo-22389 [https://bugs.python.org/issue?@action=redirect&bpo=22389]: Add contextlib.redirect_stderr().

bpo-21356 [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.

bpo-22915 [https://bugs.python.org/issue?@action=redirect&bpo=22915]: SAX parser now supports files opened with file descriptor or bytes path.

bpo-22609 [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.

bpo-22940 [https://bugs.python.org/issue?@action=redirect&bpo=22940]: Add readline.append_history_file.

bpo-19676 [https://bugs.python.org/issue?@action=redirect&bpo=19676]: Added the "namereplace" error handler.

bpo-22788 [https://bugs.python.org/issue?@action=redirect&bpo=22788]: Add context parameter to logging.handlers.HTTPHandler.

bpo-22921 [https://bugs.python.org/issue?@action=redirect&bpo=22921]: Allow SSLContext to take the hostname parameter even if OpenSSL doesn't support SNI.

bpo-22894 [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.

bpo-22796 [https://bugs.python.org/issue?@action=redirect&bpo=22796]: HTTP cookie parsing is now stricter, in order to protect against potential injection attacks.

bpo-22370 [https://bugs.python.org/issue?@action=redirect&bpo=22370]: Windows detection in pathlib is now more robust.

bpo-22841 [https://bugs.python.org/issue?@action=redirect&bpo=22841]: Reject coroutines in asyncio add_signal_handler(). Patch by Ludovic.Gasc.

bpo-19494 [https://bugs.python.org/issue?@action=redirect&bpo=19494]: Added urllib.request.HTTPBasicPriorAuthHandler. Patch by Matej Cepl.

bpo-22578 [https://bugs.python.org/issue?@action=redirect&bpo=22578]: Added attributes to the re.error class.

bpo-22849 [https://bugs.python.org/issue?@action=redirect&bpo=22849]: Fix possible double free in the io.TextIOWrapper constructor.

bpo-12728 [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.

bpo-22821 [https://bugs.python.org/issue?@action=redirect&bpo=22821]: Fixed fcntl() with integer argument on 64-bit big-endian platforms.

bpo-21650 [https://bugs.python.org/issue?@action=redirect&bpo=21650]: Add an --sort-keys option to json.tool CLI.

bpo-22824 [https://bugs.python.org/issue?@action=redirect&bpo=22824]: Updated reprlib output format for sets to use set literals. Patch contributed by Berker Peksag.

bpo-22824 [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.

bpo-22406 [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.

bpo-17293 [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.

bpo-22769 [https://bugs.python.org/issue?@action=redirect&bpo=22769]: Fixed ttk.Treeview.tag_has() when called without arguments.

bpo-22417 [https://bugs.python.org/issue?@action=redirect&bpo=22417]: Verify certificates by default in httplib (PEP 476).

bpo-22775 [https://bugs.python.org/issue?@action=redirect&bpo=22775]: Fixed unpickling of http.cookies.SimpleCookie with protocol 2 and above. Patch by Tim Graham.

bpo-22776 [https://bugs.python.org/issue?@action=redirect&bpo=22776]: Brought excluded code into the scope of a try block in SysLogHandler.emit().

bpo-22665 [https://bugs.python.org/issue?@action=redirect&bpo=22665]: Add missing get_terminal_size and SameFileError to shutil.__all__.

bpo-6623 [https://bugs.python.org/issue?@action=redirect&bpo=6623]: Remove deprecated Netrc class in the ftplib module. Patch by Matt Chaput.

bpo-17381 [https://bugs.python.org/issue?@action=redirect&bpo=17381]: Fixed handling of case-insensitive ranges in regular expressions.

bpo-22410 [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.

bpo-22759 [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.

bpo-8876 [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.

bpo-22217 [https://bugs.python.org/issue?@action=redirect&bpo=22217]: Implemented reprs of classes in the zipfile module.

bpo-22457 [https://bugs.python.org/issue?@action=redirect&bpo=22457]: Honour load_tests in the start_dir of discovery.

bpo-18216 [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.

bpo-13918 [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.

bpo-22676 [https://bugs.python.org/issue?@action=redirect&bpo=22676]: Make the pickling of global objects which don't have a __module__ attribute less slow.

bpo-18853 [https://bugs.python.org/issue?@action=redirect&bpo=18853]: Fixed ResourceWarning in shlex.__nain__.

bpo-9351 [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.

bpo-7559 [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.

bpo-19746 [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 errors attribute on TestLoader exposes these non-fatal errors encountered during discovery.

bpo-21991 [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.

bpo-22638 [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.

bpo-22641 [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.

bpo-17401 [https://bugs.python.org/issue?@action=redirect&bpo=17401]: Include closefd in io.FileIO repr.

bpo-21338 [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.

bpo-20152 [https://bugs.python.org/issue?@action=redirect&bpo=20152]: Convert the array and cmath modules to Argument Clinic.

bpo-18643 [https://bugs.python.org/issue?@action=redirect&bpo=18643]: Add socket.socketpair() on Windows.

bpo-22435 [https://bugs.python.org/issue?@action=redirect&bpo=22435]: Fix a file descriptor leak when socketserver bind fails.

bpo-13096 [https://bugs.python.org/issue?@action=redirect&bpo=13096]: Fixed segfault in CTypes POINTER handling of large values.

bpo-11694 [https://bugs.python.org/issue?@action=redirect&bpo=11694]: Raise ConversionError in xdrlib as documented. Patch by Filip Gruszczyński and Claudiu Popa.

bpo-19380 [https://bugs.python.org/issue?@action=redirect&bpo=19380]: Optimized parsing of regular expressions.

bpo-1519638 [https://bugs.python.org/issue?@action=redirect&bpo=1519638]: Now unmatched groups are replaced with empty strings in re.sub() and re.subn().

bpo-18615 [https://bugs.python.org/issue?@action=redirect&bpo=18615]: sndhdr.what/whathdr now return a namedtuple.

bpo-22462 [https://bugs.python.org/issue?@action=redirect&bpo=22462]: Fix pyexpat's creation of a dummy frame to make it appear in exception tracebacks.

bpo-21965 [https://bugs.python.org/issue?@action=redirect&bpo=21965]: Add support for in-memory SSL to the ssl module. Patch by Geert Jansen.

bpo-21173 [https://bugs.python.org/issue?@action=redirect&bpo=21173]: Fix len() on a WeakKeyDictionary when .clear() was called with an iterator alive.

bpo-11866 [https://bugs.python.org/issue?@action=redirect&bpo=11866]: Eliminated race condition in the computation of names for new threads.

bpo-21905 [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.

bpo-11271 [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.

bpo-21883 [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.

bpo-22219 [https://bugs.python.org/issue?@action=redirect&bpo=22219]: The zipfile module CLI now adds entries for directories (including empty directories) in ZIP file.

bpo-22449 [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.

bpo-22508 [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.

bpo-20076 [https://bugs.python.org/issue?@action=redirect&bpo=20076]: Added non derived UTF-8 aliases to locale aliases table.

bpo-20079 [https://bugs.python.org/issue?@action=redirect&bpo=20079]: Added locales supported in glibc 2.18 to locale alias table.

bpo-20218 [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.

bpo-22396 [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.

bpo-22517 [https://bugs.python.org/issue?@action=redirect&bpo=22517]: When an io.BufferedRWPair object is deallocated, clear its weakrefs.

bpo-22437 [https://bugs.python.org/issue?@action=redirect&bpo=22437]: Number of capturing groups in regular expression is no longer limited by 100.

bpo-17442 [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.

bpo-23392 [https://bugs.python.org/issue?@action=redirect&bpo=23392]: Added tests for marshal C API that works with FILE*.

bpo-10510 [https://bugs.python.org/issue?@action=redirect&bpo=10510]: distutils register and upload methods now use HTML standards compliant CRLF line endings.

bpo-9850 [https://bugs.python.org/issue?@action=redirect&bpo=9850]: Fixed macpath.join() for empty first component. Patch by Oleg Oshmyan.

bpo-5309 [https://bugs.python.org/issue?@action=redirect&bpo=5309]: distutils' build and build_ext commands now accept a -j option to enable parallel building of extension modules.

bpo-22448 [https://bugs.python.org/issue?@action=redirect&bpo=22448]: Improve canceled timer handles cleanup to prevent unbound memory usage. Patch by Joshua Moore-Oliva.

bpo-22427 [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.

bpo-22362 [https://bugs.python.org/issue?@action=redirect&bpo=22362]: Forbidden ambiguous octal escapes out of range 0-0o377 in regular expressions.

bpo-20912 [https://bugs.python.org/issue?@action=redirect&bpo=20912]: Now directories added to ZIP file have correct Unix and MS-DOS directory attributes.

bpo-21866 [https://bugs.python.org/issue?@action=redirect&bpo=21866]: ZipFile.close() no longer writes ZIP64 central directory records if allowZip64 is false.

bpo-22278 [https://bugs.python.org/issue?@action=redirect&bpo=22278]: Fix urljoin problem with relative urls, a regression observed after changes to issue22118 were submitted.

bpo-22415 [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.

bpo-22423 [https://bugs.python.org/issue?@action=redirect&bpo=22423]: Unhandled exception in thread no longer causes unhandled AttributeError when sys.stderr is None.

bpo-21332 [https://bugs.python.org/issue?@action=redirect&bpo=21332]: Ensure that bufsize=1 in subprocess.Popen() selects line buffering, rather than block buffering. Patch by Akira Li.

bpo-21091 [https://bugs.python.org/issue?@action=redirect&bpo=21091]: Fix API bug: email.message.EmailMessage.is_attachment is now a method.

bpo-21079 [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.

bpo-22247 [https://bugs.python.org/issue?@action=redirect&bpo=22247]: Add NNTPError to nntplib.__all__.

bpo-22366 [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.

bpo-4180 [https://bugs.python.org/issue?@action=redirect&bpo=4180]: The warnings registries are now reset when the filters are modified.

bpo-22419 [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.

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.

bpo-20537 [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.

bpo-22384 [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.

bpo-22168 [https://bugs.python.org/issue?@action=redirect&bpo=22168]: Prevent turtle AttributeError with non-default Canvas on OS X.

bpo-21147 [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.

bpo-13968 [https://bugs.python.org/issue?@action=redirect&bpo=13968]: The glob module now supports recursive search in subdirectories using the ** pattern.

bpo-21951 [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.

bpo-21951 [https://bugs.python.org/issue?@action=redirect&bpo=21951]: Tkinter now most likely raises MemoryError instead of crash if the memory allocation fails.

bpo-22338 [https://bugs.python.org/issue?@action=redirect&bpo=22338]: Fix a crash in the json module on memory allocation failure.

bpo-12410 [https://bugs.python.org/issue?@action=redirect&bpo=12410]: imaplib.IMAP4 now supports the context management protocol. Original patch by Tarek Ziadé.

bpo-21270 [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.

bpo-16662 [https://bugs.python.org/issue?@action=redirect&bpo=16662]: load_tests() is now unconditionally run when it is present in a package's __init__.py. TestLoader.loadTestsFromModule() still accepts use_load_tests, but it is deprecated and ignored. A new keyword-only attribute pattern is added and documented. Patch given by Robert Collins, tweaked by Barry Warsaw.

bpo-22226 [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().

bpo-19524 [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.

bpo-20421 [https://bugs.python.org/issue?@action=redirect&bpo=20421]: Add a .version() method to SSL sockets exposing the actual protocol version in use.

bpo-19546 [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.

bpo-22051 [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.

bpo-21933 [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.

bpo-21597 [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.

bpo-18132 [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.

bpo-22043 [https://bugs.python.org/issue?@action=redirect&bpo=22043]: time.monotonic() is now always available. threading.Lock.acquire(), threading.RLock.acquire() and socket operations now use a monotonic clock, instead of the system clock, when a timeout is used.

bpo-21527 [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.

bpo-22216 [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.

bpo-22098 [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.

bpo-22185 [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.

bpo-22287 [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).

bpo-22182 [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.

The webbrowser module now uses subprocess's start_new_session=True rather than a potentially risky preexec_fn=os.setsid call.

bpo-22042 [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.

bpo-16808 [https://bugs.python.org/issue?@action=redirect&bpo=16808]: inspect.stack() now returns a named tuple instead of a tuple. Patch by Daniel Shahaf.

bpo-22236 [https://bugs.python.org/issue?@action=redirect&bpo=22236]: Fixed Tkinter images copying operations in NoDefaultRoot mode.

bpo-2527 [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.

bpo-22118 [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.

bpo-21549 [https://bugs.python.org/issue?@action=redirect&bpo=21549]: Added the "members" parameter to TarFile.list().

bpo-19628 [https://bugs.python.org/issue?@action=redirect&bpo=19628]: Allow compileall recursion depth to be specified with a -r option.

bpo-15696 [https://bugs.python.org/issue?@action=redirect&bpo=15696]: Add a __sizeof__ implementation for mmap objects on Windows.

bpo-22068 [https://bugs.python.org/issue?@action=redirect&bpo=22068]: Avoided reference loops with Variables and Fonts in Tkinter.

bpo-22165 [https://bugs.python.org/issue?@action=redirect&bpo=22165]: SimpleHTTPRequestHandler now supports undecodable file names.

bpo-15381 [https://bugs.python.org/issue?@action=redirect&bpo=15381]: Optimized line reading in io.BytesIO.

bpo-8797 [https://bugs.python.org/issue?@action=redirect&bpo=8797]: Raise HTTPError on failed Basic Authentication immediately. Initial patch by Sam Bull.

bpo-20729 [https://bugs.python.org/issue?@action=redirect&bpo=20729]: Restored the use of lazy iterkeys()/itervalues()/iteritems() in the mailbox module.

bpo-21448 [https://bugs.python.org/issue?@action=redirect&bpo=21448]: Changed FeedParser feed() to avoid O(n²) behavior when parsing long line. Original patch by Raymond Hettinger.

bpo-22184 [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.

bpo-17923 [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.

bpo-21725 [https://bugs.python.org/issue?@action=redirect&bpo=21725]: Added support for RFC 6531 (SMTPUTF8) in smtpd.

bpo-22176 [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.

bpo-5411 [https://bugs.python.org/issue?@action=redirect&bpo=5411]: Added support for the "xztar" format in the shutil module.

bpo-21121 [https://bugs.python.org/issue?@action=redirect&bpo=21121]: Don't force 3rd party C extensions to be built with -Werror=declaration-after-statement.

bpo-21975 [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.

bpo-20170 [https://bugs.python.org/issue?@action=redirect&bpo=20170]: Convert posixmodule to use Argument Clinic.

bpo-21539 [https://bugs.python.org/issue?@action=redirect&bpo=21539]: Add an exists_ok argument to Pathlib.mkdir() to mimic mkdir -p and os.makedirs() functionality. When true, ignore FileExistsErrors. Patch by Berker Peksag.

bpo-22127 [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).

bpo-21047 [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.

Add an __all__ to html.entities.

bpo-15114 [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.

bpo-22085 [https://bugs.python.org/issue?@action=redirect&bpo=22085]: Dropped support of Tk 8.3 in Tkinter.

bpo-21580 [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.

bpo-22003 [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.

bpo-22018 [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.

bpo-22054 [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.

bpo-17172 [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.

bpo-21704 [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.

bpo-20173 [https://bugs.python.org/issue?@action=redirect&bpo=20173]: Convert sha1, sha256, sha512 and md5 to ArgumentClinic. Patch by Vajrasky Kok.

Fix repr(_socket.socket) on Windows 64-bit: don't fail with OverflowError on closed socket. repr(socket.socket) already works fine.

bpo-22033 [https://bugs.python.org/issue?@action=redirect&bpo=22033]: Reprs of most Python implemented classes now contain actual class name instead of hardcoded one.

bpo-21947 [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.

bpo-16133 [https://bugs.python.org/issue?@action=redirect&bpo=16133]: The asynchat.async_chat.handle_read() method now ignores BlockingIOError exceptions.

bpo-22044 [https://bugs.python.org/issue?@action=redirect&bpo=22044]: Fixed premature DECREF in call_tzinfo_method. Patch by Tom Flanagan.

bpo-19884 [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 "\033[1034h" into stdout. This sequence is used on some terminal (ex: TERM=xterm-256color") to enable support of 8 bit characters.

bpo-4350 [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.

bpo-6167 [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.

bpo-15275 [https://bugs.python.org/issue?@action=redirect&bpo=15275]: Clean up and speed up the ntpath module.

bpo-21888 [https://bugs.python.org/issue?@action=redirect&bpo=21888]: plistlib's load() and loads() now work if the fmt parameter is specified.

bpo-22032 [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.

bpo-22031 [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...".

bpo-22018 [https://bugs.python.org/issue?@action=redirect&bpo=22018]: signal.set_wakeup_fd() now raises an OSError instead of a ValueError on fstat() failure.

bpo-21044 [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.

bpo-21966 [https://bugs.python.org/issue?@action=redirect&bpo=21966]: Respect -q command-line option when code module is ran.

bpo-19076 [https://bugs.python.org/issue?@action=redirect&bpo=19076]: Don't pass the redundant 'file' argument to self.error().

bpo-16382 [https://bugs.python.org/issue?@action=redirect&bpo=16382]: Improve exception message of warnings.warn() for bad category. Initial patch by Phil Elson.

bpo-21932 [https://bugs.python.org/issue?@action=redirect&bpo=21932]: os.read() now uses a 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.

bpo-21942 [https://bugs.python.org/issue?@action=redirect&bpo=21942]: Fixed source file viewing in pydoc's server mode on Windows.

bpo-11259 [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.

bpo-12523 [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

bpo-21707 [https://bugs.python.org/issue?@action=redirect&bpo=21707]: Add missing kwonlyargcount argument to ModuleFinder.replace_paths_in_code().

bpo-20639 [https://bugs.python.org/issue?@action=redirect&bpo=20639]: calling Path.with_suffix('') allows removing the suffix again. Patch by July Tikhonov.

bpo-21714 [https://bugs.python.org/issue?@action=redirect&bpo=21714]: Disallow the construction of invalid paths using Path.with_name(). Original patch by Antony Lee.

bpo-15014 [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.

bpo-21151 [https://bugs.python.org/issue?@action=redirect&bpo=21151]: Fixed a segfault in the winreg module when None is passed as a REG_BINARY value to SetValueEx. Patch by John Ehresman.

bpo-21090 [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.

bpo-5800 [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.

bpo-21781 [https://bugs.python.org/issue?@action=redirect&bpo=21781]: ssl.RAND_add() now supports strings longer than 2 GB.

bpo-21679 [https://bugs.python.org/issue?@action=redirect&bpo=21679]: Prevent extraneous fstat() calls during open(). Patch by Bohuslav Kabrda.

bpo-21863 [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.

bpo-11453 [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.

bpo-21858 [https://bugs.python.org/issue?@action=redirect&bpo=21858]: Better handling of Python exceptions in the sqlite3 module.

bpo-21476 [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.

bpo-20295 [https://bugs.python.org/issue?@action=redirect&bpo=20295]: imghdr now recognizes OpenEXR format images.

bpo-21729 [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.

bpo-21491 [https://bugs.python.org/issue?@action=redirect&bpo=21491]: socketserver: Fix a race condition in child processes reaping.

bpo-21719 [https://bugs.python.org/issue?@action=redirect&bpo=21719]: Added the st_file_attributes field to os.stat_result on Windows.

bpo-21832 [https://bugs.python.org/issue?@action=redirect&bpo=21832]: Require named tuple inputs to be exact strings.

bpo-21722 [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.

bpo-21723 [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.

bpo-21711 [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).

bpo-17552 [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'.

bpo-18039 [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.

bpo-21326 [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.

bpo-21766 [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.

bpo-21310 [https://bugs.python.org/issue?@action=redirect&bpo=21310]: Fixed possible resource leak in failed open().

bpo-21256 [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.

bpo-21677 [https://bugs.python.org/issue?@action=redirect&bpo=21677]: Fixed chaining nonnormalized exceptions in io close() methods.

bpo-11709 [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.

bpo-21515 [https://bugs.python.org/issue?@action=redirect&bpo=21515]: tempfile.TemporaryFile now uses os.O_TMPFILE flag is available.

bpo-13223 [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.

bpo-21463 [https://bugs.python.org/issue?@action=redirect&bpo=21463]: In urllib.request, fix pruning of the FTP cache.

bpo-21618 [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.

bpo-20383 [https://bugs.python.org/issue?@action=redirect&bpo=20383]: Introduce importlib.util.module_from_spec() as the preferred way to create a new module.

bpo-21552 [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.

bpo-14315 [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.

bpo-13742 [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.)

bpo-21402 [https://bugs.python.org/issue?@action=redirect&bpo=21402]: tkinter.ttk now works when default root window is not set.

bpo-3015 [https://bugs.python.org/issue?@action=redirect&bpo=3015]: _tkinter.create() now creates tkapp object with wantobject=1 by default.

bpo-10203 [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.

bpo-18807 [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.

bpo-20197 [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.

bpo-21513 [https://bugs.python.org/issue?@action=redirect&bpo=21513]: Speedup some properties of IP addresses (IPv4Address, IPv6Address) such as .is_private or .is_multicast.

bpo-21137 [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.

bpo-21538 [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.

bpo-21455 [https://bugs.python.org/issue?@action=redirect&bpo=21455]: Add a default backlog to socket.listen().

bpo-21525 [https://bugs.python.org/issue?@action=redirect&bpo=21525]: Most Tkinter methods which accepted tuples now accept lists too.

bpo-22166 [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

bpo-22236 [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.

bpo-10744 [https://bugs.python.org/issue?@action=redirect&bpo=10744]: Fix PEP 3118 [https://peps.python.org/pep-3118/] format strings on ctypes objects with a nontrivial shape.

bpo-20826 [https://bugs.python.org/issue?@action=redirect&bpo=20826]: Optimize ipaddress.collapse_addresses().

bpo-21487 [https://bugs.python.org/issue?@action=redirect&bpo=21487]: Optimize ipaddress.summarize_address_range() and ipaddress.{IPv4Network,IPv6Network}.subnets().

bpo-21486 [https://bugs.python.org/issue?@action=redirect&bpo=21486]: Optimize parsing of netmasks in ipaddress.IPv4Network and ipaddress.IPv6Network.

bpo-13916 [https://bugs.python.org/issue?@action=redirect&bpo=13916]: Disallowed the surrogatepass error handler for non UTF-* encodings.

bpo-20998 [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.

bpo-21075 [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.

bpo-19775 [https://bugs.python.org/issue?@action=redirect&bpo=19775]: Add a samefile() method to pathlib Path objects. Initial patch by Vajrasky Kok.

bpo-21226 [https://bugs.python.org/issue?@action=redirect&bpo=21226]: Set up modules properly in PyImport_ExecCodeModuleObject (and friends).

bpo-21398 [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.

bpo-16531 [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.

bpo-21156 [https://bugs.python.org/issue?@action=redirect&bpo=21156]: importlib.abc.InspectLoader.source_to_code() is now a staticmethod.

bpo-21424 [https://bugs.python.org/issue?@action=redirect&bpo=21424]: Simplified and optimized heaqp.nlargest() and nmsmallest() to make fewer tuple comparisons.

bpo-21396 [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.

bpo-18314 [https://bugs.python.org/issue?@action=redirect&bpo=18314]: Unlink now removes junctions on Windows. Patch by Kim Gräsman

bpo-21088 [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.

bpo-21407 [https://bugs.python.org/issue?@action=redirect&bpo=21407]: _decimal: The module now supports function signatures.

bpo-10650 [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.

bpo-21469 [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().

bpo-19414 [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.

bpo-21421 [https://bugs.python.org/issue?@action=redirect&bpo=21421]: Add __slots__ to the MappingViews ABC. Patch by Josh Rosenberg.

bpo-21101 [https://bugs.python.org/issue?@action=redirect&bpo=21101]: Eliminate double hashing in the C speed-up code for collections.Counter().

bpo-21321 [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.

bpo-21057 [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.

bpo-20951 [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.

bpo-13248 [https://bugs.python.org/issue?@action=redirect&bpo=13248]: removed previously deprecated asyncore.dispatcher __getattr__ cheap inheritance hack.

bpo-9815 [https://bugs.python.org/issue?@action=redirect&bpo=9815]: assertRaises now tries to clear references to local variables in the exception's traceback.

bpo-19940 [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.

bpo-13204 [https://bugs.python.org/issue?@action=redirect&bpo=13204]: Calling sys.flags.__new__ would crash the interpreter, now it raises a TypeError.

bpo-19385 [https://bugs.python.org/issue?@action=redirect&bpo=19385]: Make operations on a closed dbm.dumb database always raise the same exception.

bpo-21207 [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.

bpo-21291 [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.

bpo-21127 [https://bugs.python.org/issue?@action=redirect&bpo=21127]: Path objects can now be instantiated from str subclass instances (such as numpy.str_).

bpo-15002 [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.

bpo-12220 [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.

bpo-21068 [https://bugs.python.org/issue?@action=redirect&bpo=21068]: The ssl.PROTOCOL* constants are now enum members.

bpo-21276 [https://bugs.python.org/issue?@action=redirect&bpo=21276]: posixmodule: Don't define USE_XATTRS on KFreeBSD and the Hurd.

bpo-21262 [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.

bpo-21238 [https://bugs.python.org/issue?@action=redirect&bpo=21238]: New keyword argument unsafe to Mock. It raises AttributeError incase of an attribute startswith assert or assret.

bpo-20896 [https://bugs.python.org/issue?@action=redirect&bpo=20896]: ssl.get_server_certificate() now uses PROTOCOL_SSLv23, not PROTOCOL_SSLv3, for maximum compatibility.

bpo-21239 [https://bugs.python.org/issue?@action=redirect&bpo=21239]: patch.stopall() didn't work deterministically when the same name was patched more than once.

bpo-21203 [https://bugs.python.org/issue?@action=redirect&bpo=21203]: Updated fileConfig and dictConfig to remove inconsistencies. Thanks to Jure Koren for the patch.

bpo-21222 [https://bugs.python.org/issue?@action=redirect&bpo=21222]: Passing name keyword argument to mock.create_autospec now works.

bpo-21197 [https://bugs.python.org/issue?@action=redirect&bpo=21197]: Add lib64 -> lib symlink in venvs on 64-bit non-OS X POSIX.

bpo-17498 [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.

bpo-17826 [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.

bpo-7776 [https://bugs.python.org/issue?@action=redirect&bpo=7776]: Fix Host: header and reconnection when using http.client.HTTPConnection.set_tunnel(). Patch by Nikolaus Rath.

bpo-20968 [https://bugs.python.org/issue?@action=redirect&bpo=20968]: unittest.mock.MagicMock now supports division. Patch by Johannes Baiter.

bpo-21529 [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: CVE-2014-4616 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-4616])

bpo-21169 [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.

bpo-21171 [https://bugs.python.org/issue?@action=redirect&bpo=21171]: Fixed undocumented filter API of the rot13 codec. Patch by Berker Peksag.

bpo-20539 [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.

bpo-21172 [https://bugs.python.org/issue?@action=redirect&bpo=21172]: isinstance check relaxed from dict to collections.Mapping.

bpo-21155 [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.

bpo-21136 [https://bugs.python.org/issue?@action=redirect&bpo=21136]: Avoid unnecessary normalization of Fractions resulting from power and other operations. Patch by Raymond Hettinger.

bpo-17621 [https://bugs.python.org/issue?@action=redirect&bpo=17621]: Introduce importlib.util.LazyLoader.

bpo-21076 [https://bugs.python.org/issue?@action=redirect&bpo=21076]: signal module constants were turned into enums. Patch by Giampaolo Rodola'.

bpo-20636 [https://bugs.python.org/issue?@action=redirect&bpo=20636]: Improved the repr of Tkinter widgets.

bpo-19505 [https://bugs.python.org/issue?@action=redirect&bpo=19505]: The items, keys, and values views of OrderedDict now support reverse iteration using reversed().

bpo-21149 [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.

bpo-21058 [https://bugs.python.org/issue?@action=redirect&bpo=21058]: Fix a leak of file descriptor in tempfile.NamedTemporaryFile(), close the file descriptor if io.open() fails

bpo-21200 [https://bugs.python.org/issue?@action=redirect&bpo=21200]: Return None from pkgutil.get_loader() when __spec__ is missing.

bpo-21013 [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.

bpo-20145 [https://bugs.python.org/issue?@action=redirect&bpo=20145]: assertRaisesRegex and assertWarnsRegex now raise a TypeError if the second argument is not a string or compiled regex.

bpo-20633 [https://bugs.python.org/issue?@action=redirect&bpo=20633]: Replace relative import by absolute import.

bpo-20980 [https://bugs.python.org/issue?@action=redirect&bpo=20980]: Stop wrapping exception when using ThreadPool.

bpo-21082 [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.

bpo-20990 [https://bugs.python.org/issue?@action=redirect&bpo=20990]: Fix issues found by pyflakes for multiprocessing.

bpo-21015 [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".

bpo-21000 [https://bugs.python.org/issue?@action=redirect&bpo=21000]: Improve the command-line interface of json.tool.

bpo-20995 [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.

bpo-20884 [https://bugs.python.org/issue?@action=redirect&bpo=20884]: Don't assume that __file__ is defined on importlib.__init__.

bpo-21499 [https://bugs.python.org/issue?@action=redirect&bpo=21499]: Ignore __builtins__ in several test_importlib.test_api tests.

bpo-20627 [https://bugs.python.org/issue?@action=redirect&bpo=20627]: xmlrpc.client.ServerProxy is now a context manager.

bpo-19165 [https://bugs.python.org/issue?@action=redirect&bpo=19165]: The formatter module now raises DeprecationWarning instead of PendingDeprecationWarning.

bpo-13936 [https://bugs.python.org/issue?@action=redirect&bpo=13936]: Remove the ability of datetime.time instances to be considered false in boolean contexts.

bpo-18931 [https://bugs.python.org/issue?@action=redirect&bpo=18931]: selectors module now supports /dev/poll on Solaris. Patch by Giampaolo Rodola'.

bpo-19977 [https://bugs.python.org/issue?@action=redirect&bpo=19977]: When the LC_TYPE locale is the POSIX locale (C locale), sys.stdin and sys.stdout are now using the surrogateescape error handler, instead of the strict error handler.

bpo-20574 [https://bugs.python.org/issue?@action=redirect&bpo=20574]: Implement incremental decoder for cp65001 code (Windows code page 65001, Microsoft UTF-8).

bpo-20879 [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.

bpo-19157 [https://bugs.python.org/issue?@action=redirect&bpo=19157]: Include the broadcast address in the usuable hosts for IPv6 in ipaddress.

bpo-11599 [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.

bpo-4931 [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.

bpo-20875 [https://bugs.python.org/issue?@action=redirect&bpo=20875]: Prevent possible gzip "'read' is not defined" NameError. Patch by Claudiu Popa.

bpo-11558 [https://bugs.python.org/issue?@action=redirect&bpo=11558]: email.message.Message.attach now returns a more useful error message if attach is called on a message for which is_multipart is False.

bpo-20283 [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.

bpo-20778 [https://bugs.python.org/issue?@action=redirect&bpo=20778]: Fix modulefinder to work with bytecode-only modules.

bpo-20791 [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.

bpo-19748 [https://bugs.python.org/issue?@action=redirect&bpo=19748]: On AIX, time.mktime() now raises an OverflowError for year outsize range [1902; 2037].

bpo-19573 [https://bugs.python.org/issue?@action=redirect&bpo=19573]: inspect.signature: Use enum for parameter kind constants.

bpo-20726 [https://bugs.python.org/issue?@action=redirect&bpo=20726]: inspect.signature: Make Signature and Parameter picklable.

bpo-17373 [https://bugs.python.org/issue?@action=redirect&bpo=17373]: Add inspect.Signature.from_callable method.

bpo-20378 [https://bugs.python.org/issue?@action=redirect&bpo=20378]: Improve repr of inspect.Signature and inspect.Parameter.

bpo-20816 [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.

bpo-20817 [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.

bpo-6676 [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)

bpo-21117 [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.

bpo-20334 [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.

bpo-15916 [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

bpo-21209 [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.

asyncio: Add gi_{frame,running,code} properties to CoroWrapper (upstream bpo-163 [https://bugs.python.org/issue?@action=redirect&bpo=163]).

bpo-21311 [https://bugs.python.org/issue?@action=redirect&bpo=21311]: Avoid exception in _osx_support with non-standard compiler configurations. Patch by John Szakmeister.

bpo-11571 [https://bugs.python.org/issue?@action=redirect&bpo=11571]: Ensure that the turtle window becomes the topmost window when launched on OS X.

bpo-21801 [https://bugs.python.org/issue?@action=redirect&bpo=21801]: Validate that __signature__ is None or an instance of Signature.

bpo-21923 [https://bugs.python.org/issue?@action=redirect&bpo=21923]: Prevent AttributeError in distutils.sysconfig.customize_compiler due to possible uninitialized _config_vars.

bpo-21323 [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 [https://bugs.python.org/issue?@action=redirect&bpo=19435]. Patch by Zach Byrne.

bpo-22733 [https://bugs.python.org/issue?@action=redirect&bpo=22733]: Fix ffi_prep_args not zero-extending argument values correctly on 64-bit Windows.

bpo-23302 [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.

IDLE

bpo-20577 [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.

bpo-16893 [https://bugs.python.org/issue?@action=redirect&bpo=16893]: Update Idle doc chapter to match current Idle and add new information.

bpo-3068 [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.

bpo-16233 [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.

bpo-4832 [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.

bpo-21986 [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.

bpo-17390 [https://bugs.python.org/issue?@action=redirect&bpo=17390]: Adjust Editor window title; remove 'Python', move version to end.

bpo-14105 [https://bugs.python.org/issue?@action=redirect&bpo=14105]: Idle debugger breakpoints no longer disappear when inserting or deleting lines.

bpo-17172 [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.

bpo-21765 [https://bugs.python.org/issue?@action=redirect&bpo=21765]: Add support for non-ascii identifiers to HyperParser.

bpo-21940 [https://bugs.python.org/issue?@action=redirect&bpo=21940]: Add unittest for WidgetRedirector. Initial patch by Saimadhav Heblikar.

bpo-18592 [https://bugs.python.org/issue?@action=redirect&bpo=18592]: Add unittest for SearchDialogBase. Patch by Phil Webster.

bpo-21694 [https://bugs.python.org/issue?@action=redirect&bpo=21694]: Add unittest for ParenMatch. Patch by Saimadhav Heblikar.

bpo-21686 [https://bugs.python.org/issue?@action=redirect&bpo=21686]: add unittest for HyperParser. Original patch by Saimadhav Heblikar.

bpo-12387 [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.

bpo-21695 [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.

bpo-18910 [https://bugs.python.org/issue?@action=redirect&bpo=18910]: Add unittest for textView. Patch by Phil Webster.

bpo-18292 [https://bugs.python.org/issue?@action=redirect&bpo=18292]: Add unittest for AutoExpand. Patch by Saihadhav Heblikar.

bpo-18409 [https://bugs.python.org/issue?@action=redirect&bpo=18409]: Add unittest for AutoComplete. Patch by Phil Webster.

bpo-21477 [https://bugs.python.org/issue?@action=redirect&bpo=21477]: htest.py - Improve framework, complete set of tests. Patches by Saimadhav Heblikar

bpo-18104 [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.

bpo-21139 [https://bugs.python.org/issue?@action=redirect&bpo=21139]: Change default paragraph width to 72, the PEP 8 [https://peps.python.org/pep-0008/] recommendation.

bpo-21284 [https://bugs.python.org/issue?@action=redirect&bpo=21284]: Paragraph reformat test passes after user changes reformat width.

bpo-17654 [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.

bpo-23180 [https://bugs.python.org/issue?@action=redirect&bpo=23180]: Rename IDLE "Windows" menu item to "Window". Patch by Al Sweigart.

Build

bpo-15506 [https://bugs.python.org/issue?@action=redirect&bpo=15506]: Use standard PKG_PROG_PKG_CONFIG autoconf macro in the configure script.

bpo-22935 [https://bugs.python.org/issue?@action=redirect&bpo=22935]: Allow the ssl module to be compiled if openssl doesn't support SSL 3.

bpo-22592 [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.

bpo-22591 [https://bugs.python.org/issue?@action=redirect&bpo=22591]: Drop support of MS-DOS, especially of the DJGPP compiler (MS-DOS port of GCC).

bpo-16537 [https://bugs.python.org/issue?@action=redirect&bpo=16537]: Check whether self.extensions is empty in setup.py. Patch by Jonathan Hosmer.

bpo-22359 [https://bugs.python.org/issue?@action=redirect&bpo=22359]: Remove incorrect uses of recursive make. Patch by Jonas Wagner.

bpo-21958 [https://bugs.python.org/issue?@action=redirect&bpo=21958]: Define HAVE_ROUND when building with Visual Studio 2013 and above. Patch by Zachary Turner.

bpo-18093 [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.

bpo-15759 [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.

bpo-21141 [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 PCbuild\build_ssl.py script has been re-written and re-named to 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.

bpo-21037 [https://bugs.python.org/issue?@action=redirect&bpo=21037]: Add a build option to enable AddressSanitizer support.

bpo-19962 [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.

bpo-21285 [https://bugs.python.org/issue?@action=redirect&bpo=21285]: Refactor and fix curses configure check to always search in a ncursesw directory.

bpo-15234 [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.

bpo-17861 [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.

bpo-20644 [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.

bpo-20022 [https://bugs.python.org/issue?@action=redirect&bpo=20022]: Eliminate use of deprecated bundlebuilder in OS X builds.

bpo-15968 [https://bugs.python.org/issue?@action=redirect&bpo=15968]: Incorporated Tcl, Tk, and Tix builds into the Windows build solution.

bpo-17095 [https://bugs.python.org/issue?@action=redirect&bpo=17095]: Fix Modules/Setup shared support.

bpo-21811 [https://bugs.python.org/issue?@action=redirect&bpo=21811]: Anticipated fixes to support OS X versions > 10.9.

bpo-21166 [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.

bpo-18096 [https://bugs.python.org/issue?@action=redirect&bpo=18096]: Fix library order returned by python-config.

bpo-17219 [https://bugs.python.org/issue?@action=redirect&bpo=17219]: Add library build dir for Python extension cross-builds.

bpo-22919 [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.

bpo-21236 [https://bugs.python.org/issue?@action=redirect&bpo=21236]: Build _msi.pyd with cabinet.lib instead of fci.lib

bpo-17128 [https://bugs.python.org/issue?@action=redirect&bpo=17128]: Use private version of OpenSSL for OS X 10.5+ installer.

C API

bpo-14203 [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.

bpo-22445 [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.

bpo-22079 [https://bugs.python.org/issue?@action=redirect&bpo=22079]: PyType_Ready() now checks that statically allocated type has no dynamically allocated bases.

bpo-22453 [https://bugs.python.org/issue?@action=redirect&bpo=22453]: Removed non-documented macro PyObject_REPR().

bpo-18395 [https://bugs.python.org/issue?@action=redirect&bpo=18395]: Rename _Py_char2wchar() to Py_DecodeLocale(), rename _Py_wchar2char() to Py_EncodeLocale(), and document these functions.

bpo-21233 [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 calloc() instead of malloc() for large objects which is faster and use less memory.

bpo-20942 [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().

Documentation

bpo-19548 [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.

bpo-22394 [https://bugs.python.org/issue?@action=redirect&bpo=22394]: Doc/Makefile now supports make venv PYTHON=../python to create a venv for generating the documentation, e.g., make html PYTHON=venv/bin/python3.

bpo-21514 [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.

bpo-21777 [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.

bpo-6916 [https://bugs.python.org/issue?@action=redirect&bpo=6916]: undocument deprecated asynchat.fifo class.

bpo-17386 [https://bugs.python.org/issue?@action=redirect&bpo=17386]: Expanded functionality of the Doc/make.bat script to make it much more comparable to Doc/Makefile.

bpo-21312 [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.

bpo-21043 [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.

bpo-20765 [https://bugs.python.org/issue?@action=redirect&bpo=20765]: Add missing documentation for PurePath.with_name() and PurePath.with_suffix().

bpo-19407 [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.

bpo-19697 [https://bugs.python.org/issue?@action=redirect&bpo=19697]: Document cases where __main__.__spec__ is None.

Tests

bpo-18982 [https://bugs.python.org/issue?@action=redirect&bpo=18982]: Add tests for CLI of the calendar module.

bpo-19548 [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.

bpo-22838 [https://bugs.python.org/issue?@action=redirect&bpo=22838]: All test_re tests now work with unittest test discovery.

bpo-22173 [https://bugs.python.org/issue?@action=redirect&bpo=22173]: Update lib2to3 tests to use unittest test discovery.

bpo-16000 [https://bugs.python.org/issue?@action=redirect&bpo=16000]: Convert test_curses to use unittest.

bpo-21456 [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.

bpo-20746 [https://bugs.python.org/issue?@action=redirect&bpo=20746]: Fix test_pdb to run in refleak mode (-R). Patch by Xavier de Gaye.

bpo-22060 [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.

bpo-22104 [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().

bpo-22111 [https://bugs.python.org/issue?@action=redirect&bpo=22111]: Assorted cleanups in test_imaplib. Patch by Milan Oberkirch.

bpo-22002 [https://bugs.python.org/issue?@action=redirect&bpo=22002]: Added 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.

bpo-21976 [https://bugs.python.org/issue?@action=redirect&bpo=21976]: Fix test_ssl to accept LibreSSL version strings. Thanks to William Orr.

bpo-21918 [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.

bpo-9554 [https://bugs.python.org/issue?@action=redirect&bpo=9554]: Use modern unittest features in test_argparse. Initial patch by Denver Coneybeare and Radu Voicilas.

bpo-20155 [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.

bpo-19493 [https://bugs.python.org/issue?@action=redirect&bpo=19493]: Refactored the ctypes test package to skip tests explicitly rather than silently.

bpo-18492 [https://bugs.python.org/issue?@action=redirect&bpo=18492]: All resources are now allowed when tests are not run by regrtest.py.

bpo-21634 [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.

bpo-21605 [https://bugs.python.org/issue?@action=redirect&bpo=21605]: Added tests for Tkinter images.

bpo-21493 [https://bugs.python.org/issue?@action=redirect&bpo=21493]: Added test for ntpath.expanduser(). Original patch by Claudiu Popa.

bpo-19925 [https://bugs.python.org/issue?@action=redirect&bpo=19925]: Added tests for the spwd module. Original patch by Vajrasky Kok.

bpo-21522 [https://bugs.python.org/issue?@action=redirect&bpo=21522]: Added Tkinter tests for Listbox.itemconfigure(), PanedWindow.paneconfigure(), and Menu.entryconfigure().

bpo-17756 [https://bugs.python.org/issue?@action=redirect&bpo=17756]: Fix test_code test when run from the installed location.

bpo-17752 [https://bugs.python.org/issue?@action=redirect&bpo=17752]: Fix distutils tests when run from the installed location.

bpo-18604 [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.

bpo-21275 [https://bugs.python.org/issue?@action=redirect&bpo=21275]: Fix a socket test on KFreeBSD.

bpo-21223 [https://bugs.python.org/issue?@action=redirect&bpo=21223]: Pass test_site/test_startup_imports when some of the extensions are built as builtins.

bpo-20635 [https://bugs.python.org/issue?@action=redirect&bpo=20635]: Added tests for Tk geometry managers.

Add test case for freeze.

bpo-20743 [https://bugs.python.org/issue?@action=redirect&bpo=20743]: Fix a reference leak in test_tcl.

bpo-21097 [https://bugs.python.org/issue?@action=redirect&bpo=21097]: Move test_namespace_pkgs into test_importlib.

bpo-21503 [https://bugs.python.org/issue?@action=redirect&bpo=21503]: Use test_both() consistently in test_importlib.

bpo-20939 [https://bugs.python.org/issue?@action=redirect&bpo=20939]: Avoid various network test failures due to new redirect of http://www.python.org/ to https://www.python.org: use http://www.example.com instead.

bpo-20668 [https://bugs.python.org/issue?@action=redirect&bpo=20668]: asyncio tests no longer rely on tests.txt file. (Patch by Vajrasky Kok)

bpo-21093 [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.

bpo-22770 [https://bugs.python.org/issue?@action=redirect&bpo=22770]: Prevent some Tk segfaults on OS X when running gui tests.

bpo-23211 [https://bugs.python.org/issue?@action=redirect&bpo=23211]: Workaround test_logging failure on some OS X 10.6 systems.

bpo-23345 [https://bugs.python.org/issue?@action=redirect&bpo=23345]: Prevent test_ssl failures with large OpenSSL patch level values (like 0.9.8zc).

Tools/Demos

bpo-22314 [https://bugs.python.org/issue?@action=redirect&bpo=22314]: pydoc now works when the LINES environment variable is set.

bpo-22615 [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.

bpo-20076 [https://bugs.python.org/issue?@action=redirect&bpo=20076]: The makelocalealias.py script no longer ignores UTF-8 mapping.

bpo-20079 [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.

bpo-22201 [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.

bpo-22120 [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.)

bpo-18974 [https://bugs.python.org/issue?@action=redirect&bpo=18974]: Tools/scripts/diff.py now uses argparse instead of optparse.

bpo-21906 [https://bugs.python.org/issue?@action=redirect&bpo=21906]: Make Tools/scripts/md5sum.py work in Python 3. Patch by Zachary Ware.

bpo-21629 [https://bugs.python.org/issue?@action=redirect&bpo=21629]: Fix Argument Clinic's "--converters" feature.

Add support for yield from to 2to3.

Add support for the PEP 465 [https://peps.python.org/pep-0465/] matrix multiplication operator to 2to3.

bpo-16047 [https://bugs.python.org/issue?@action=redirect&bpo=16047]: Fix module exception list and __file__ handling in freeze. Patch by Meador Inge.

bpo-11824 [https://bugs.python.org/issue?@action=redirect&bpo=11824]: Consider ABI tags in freeze. Patch by Meador Inge.

bpo-20535 [https://bugs.python.org/issue?@action=redirect&bpo=20535]: PYTHONWARNING no longer affects the run_tests.py script. Patch by Arfrever Frehtes Taifersar Arahesis.

Windows

bpo-23260 [https://bugs.python.org/issue?@action=redirect&bpo=23260]: Update Windows installer

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.

bpo-17896 [https://bugs.python.org/issue?@action=redirect&bpo=17896]: The Windows build scripts now expect external library sources to be in PCbuild\..\externals rather than PCbuild\..\...

bpo-17717 [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.

bpo-21907 [https://bugs.python.org/issue?@action=redirect&bpo=21907]: Improved the batch scripts provided for building Python.

bpo-22644 [https://bugs.python.org/issue?@action=redirect&bpo=22644]: The bundled version of OpenSSL has been updated to 1.0.1j.

bpo-10747 [https://bugs.python.org/issue?@action=redirect&bpo=10747]: Use versioned labels in the Windows start menu. Patch by Olive Kilburn.

bpo-22980 [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.

(For information about older versions, consult the HISTORY file.)

Python チュートリアル

Python は強力で、学びやすいプログラミング言語です。効率的な高レベルデータ構造と、シンプルで効果的なオブジェクト指向プログラミング機構を備えています。 Python は、洗練された文法・動的なデータ型付け・インタープリタであることなどから、スクリプティングや高速アプリケーション開発(Rapid Application Development: RAD)に理想的なプログラミング言語となっています。

Python Web サイト(https://www.python.org) は、 Python インタープリタと標準ライブラリのソースコードと、主要プラットフォームごとにコンパイル済みのバイナリファイルを無料で配布しています。また、Python ウェブサイトには、無料のサードパーティモジュールやプログラム、ツール、ドキュメントなども紹介しています。

Python インタプリタは、簡単に C/C++ 言語などで実装された関数やデータ型を組み込み、拡張できます。また、アプリケーションのカスタマイズを行う、拡張言語としても適しています。

このチュートリアルは、Python 言語の基本的な概念と機能を、形式ばらずに紹介します。読むだけではなく、Pythonインタープリタで実際にサンプルを実行すると理解が深まりますが、サンプルはそれぞれ独立していますので、ただ読むだけでも良いでしょう。

標準オブジェクトやモジュールの詳細は、 Python 標準ライブラリ を参照してください。 また、正式な言語定義は、 Python 言語リファレンス にあります。 C 言語や C++ 言語で拡張モジュールを書くなら、 Python インタプリタの拡張と埋め込み や Python/C API リファレンスマニュアル を参照してください。Python の解説書も販売されています。

このチュートリアルは、Python全体を対象とした、包括的な解説書ではありません。よく使われる機能に限っても、全ては紹介していません。その代わり、このチュートリアルでは、Pythonのもっとも特徴的な機能を中心に紹介して、この言語の持ち味や、スタイルを感じられるようにしています。このチュートリアルを読み終えると、Python のモジュールやプログラムを読み書きできるようになっているでしょう。また、Python 標準ライブラリ のさまざまな Python ライブラリモジュールを、詳しく調べられるようになっているはずです。

用語集 にも目を通しておくと良いでしょう。

1. やる気を高めよう

2. Python インタプリタを使う

2.1. インタプリタを起動する

2.1.1. 引数の受け渡し

2.1.2. 対話モード

2.2. インタプリタとその環境

2.2.1. ソースコードの文字コード

3. 形式ばらない Python の紹介

3.1. Python を電卓として使う

3.1.1. 数

3.1.2. テキスト

3.1.3. リスト型 (list)

3.2. プログラミングへの第一歩

4. その他の制御フローツール

4.1. if 文

4.2. for 文

4.3. range() 関数

4.4. break 文と continue 文とループの else 節

4.5. pass 文

4.6. match 文

4.7. 関数を定義する

4.8. 関数定義についてもう少し

4.8.1. デフォルトの引数値

4.8.2. キーワード引数

4.8.3. 特殊なパラメータ

4.8.3.1. 位置またはキーワード引数

4.8.3.2. 位置専用引数

4.8.3.3. キーワード専用引数

4.8.3.4. 関数の例

4.8.3.5. 要約

4.8.4. 任意引数リスト

4.8.5. 引数リストのアンパック

4.8.6. ラムダ式

4.8.7. ドキュメンテーション文字列

4.8.8. 関数のアノテーション

4.9. 間奏曲: コーディングスタイル

5. データ構造

5.1. リスト型についてもう少し

5.1.1. リストをスタックとして使う

5.1.2. リストをキューとして使う

5.1.3. リストの内包表記

5.1.4. ネストしたリストの内包表記

5.2. del 文

5.3. タプルとシーケンス

5.4. 集合型

5.5. 辞書型 (dictionary)

5.6. ループのテクニック

5.7. 条件についてもう少し

5.8. シーケンスとその他の型の比較

6. モジュール

6.1. モジュールについてもうすこし

6.1.1. モジュールをスクリプトとして実行する

6.1.2. モジュール検索パス

6.1.3. "コンパイル" された Python ファイル

6.2. 標準モジュール

6.3. dir() 関数

6.4. パッケージ

6.4.1. パッケージから * を import する

6.4.2. パッケージ内参照

6.4.3. 複数ディレクトリ中のパッケージ

7. 入力と出力

7.1. 出力を見やすくフォーマットする

7.1.1. フォーマット済み文字列リテラル

7.1.2. 文字列の format() メソッド

7.1.3. 文字列の手作業でのフォーマット

7.1.4. 古い文字列書式設定方法

7.2. ファイルを読み書きする

7.2.1. ファイルオブジェクトのメソッド

7.2.2. json による構造化されたデータの保存

8. エラーと例外

8.1. 構文エラー

8.2. 例外

8.3. 例外を処理する

8.4. 例外を送出する

8.5. 例外の連鎖

8.6. ユーザー定義例外

8.7. クリーンアップ動作を定義する

8.8. 定義済みクリーンアップ処理

8.9. 複数の関連しない例外の送出と処理

8.10. ノートによって例外を充実させる

9. クラス

9.1. 名前とオブジェクトについて

9.2. Python のスコープと名前空間

9.2.1. スコープと名前空間の例

9.3. クラス初見

9.3.1. クラス定義の構文

9.3.2. クラスオブジェクト

9.3.3. インスタンスオブジェクト

9.3.4. メソッドオブジェクト

9.3.5. クラスとインスタンス変数

9.4. いろいろな注意点

9.5. 継承

9.5.1. 多重継承

9.6. プライベート変数

9.7. 残りのはしばし

9.8. イテレータ (iterator)

9.9. ジェネレータ (generator)

9.10. ジェネレータ式

10. 標準ライブラリミニツアー

10.1. OSへのインターフェース

10.2. ファイルのワイルドカード表記

10.3. コマンドライン引数

10.4. エラー出力のリダイレクトとプログラムの終了

10.5. 文字列のパターンマッチング

10.6. 数学

10.7. インターネットへのアクセス

10.8. 日付と時刻

10.9. データ圧縮

10.10. パフォーマンスの計測

10.11. 品質管理

10.12. バッテリー同梱

11. 標準ライブラリミニツアー --- その 2

11.1. 出力のフォーマット

11.2. 文字列テンプレート

11.3. バイナリデータレコードの操作

11.4. マルチスレッディング

11.5. ログ記録

11.6. 弱参照

11.7. リスト操作のためのツール

11.8. 10 進浮動小数演算

12. 仮想環境とパッケージ

12.1. はじめに

12.2. 仮想環境の作成

12.3. pip を使ったパッケージ管理

13. さあ何を？

14. 対話入力編集と履歴置換

14.1. タブ補完と履歴編集

14.2. 対話的インタープリタの代替

15. 浮動小数点演算、その問題と制限

15.1. 表現エラー

16. 付録

16.1. 対話モード

16.1.1. エラー処理

16.1.2. 実行可能な Python スクリプト

16.1.3. 対話モード用の起動時実行ファイル

16.1.4. カスタマイズ用モジュール

1. やる気を高めよう

コンピュータを使っていろいろな作業をしていると、自動化したい作業が出てくるでしょう。たとえば、たくさんのテキストファイルで検索-置換操作を行いたい、大量の写真ファイルを込み入ったやりかたでファイル名を整理して変更したり、などです。ちょっとした専用のデータベースや、何か専用のGUIアプリケーション、シンプルなゲームを作りたいかもしれません。

あなたがプロのソフト開発者として、C/C++/Java ライブラリを扱う必要があるけども、通常の編集/コンパイル/テスト/再コンパイルのサイクルを遅すぎると感じているかもしれません。上記ライブラリのためのテストを書くことにうんざりしているかもしれません。または、拡張言語を持つアプリケーションを書いているなら、そのために新しい言語一式の設計と実装をしたくないでしょう。

Pythonはそんなあなたのための言語です。

そういった処理は、Unix シェルスクリプトや Windows バッチファイルで書くこともできます。しかし、シェルスクリプトはファイル操作やテキストデータの操作には向いていますが、GUIアプリケーションやゲームにはむいていません。C/C++/Java プログラムを書くこともできますが、最初の試し書きだけでもかなりの時間がかかってしまいます。Pythonはもっと簡単に利用でき、Windows、macOS、そして Unix オペレーティングシステムで動作し、あなたの仕事をすばやく片付ける助けになるでしょう。

Python は簡単に利用できますが、本物のプログラミング言語であり、シェルスクリプトやバッチファイルよりも多くの機構があり、大きなプログラムの開発にも適しています。一方では、Python は C よりたくさんのエラーチェックを実行時に行っており、また可変長配列や辞書などの高級な型を組込みで持つ 超高級言語(very-high-level language) です。Python は Awk や Perl などよりも汎用的なデータ型を備えており、より多くの領域で利用できます。また、Pythonはこれらの言語と比べても、少なくとも同じぐらいには簡単です。

Python では、プログラムをモジュールに分割して、他の Python プログラムで再利用できます。Python には膨大な標準モジュールが付属していて、プログラムを作る上での基盤として、あるいは Python プログラミングを学ぶためのサンプルとして利用できます。標準モジュールには、ファイル I/O、システムコール、ソケットといった機能や、Tk のようなグラフィカルユーザインターフェースツールキットを使うためのインターフェイスなども提供しています。

Python はインタプリタ言語です。コンパイルやリンクの必要がないので、プログラムを開発する際にかなりの時間を節約できます。インタプリタは対話的にも使えるので、言語の様々な機能について実験してみたり、書き捨てのプログラムを書いたり、ボトムアップでプログラムを開発する際に、関数をテストしたりといったことが簡単にできます。便利な電卓にもなります。

Python では、とてもコンパクトで読みやすいプログラムを書けます。Python で書かれたプログラムは大抵、同じ機能の C 言語, C++ 言語や Java のプログラムよりもはるかに短くなります。これには以下のようないくつかの理由があります:

高レベルのデータ型によって、複雑な操作を一つの実行文で表現できます。

実行文のグループ化を、グループの開始や終了の括弧ではなくインデントで行えます。

変数や引数の宣言が不要です。

Python には 拡張性 があります: C 言語でプログラムを書く方法を知っているなら、簡単に新たな組み込み関数やモジュールを、簡単にインタプリタに追加できます。これによって、いちばん時間のかかる処理を高速化したり、ベンダ特有のグラフィクスライブラリなどの、 バイナリ形式でしか手に入らないライブラリを Python にリンクしたりできます。その気になれば、Python インタプリタを C で書かれたアプリケーションにリンクして、アプリケーションに対する拡張言語や命令言語としても使えます。

ところで、この言語は BBC のショー番組、"モンティパイソンの空飛ぶサーカス (Monty Python's Flying Circus)" から取ったもので、爬虫類とは関係ありません。このドキュメントでは、モンティパイソンの寸劇への参照が許可されているだけでなく、むしろ推奨されています！

さて、皆さんはもう Python にワクワクして、もうちょっと詳しく調べてみたくなったはずです。プログラミング言語を習得する最良の方法は使ってみることですから、このチュートリアルではみなさんが読んだ内容を Python インタプリタで試してみることをおすすめします。

次の章では、まずインタプリタの使い方を説明します。これはわかりきった内容かもしれませんが、後に説明する例題を試してみる上で不可欠なことです。

チュートリアルの残りの部分では、Python プログラム言語と実行システムの様々な機能を例題を交えて紹介します。単純な式、実行文、データ型から始めて、関数とモジュールを経て、最後には例外処理やユーザ定義クラスといったやや高度な概念にも触れます。

2. Python インタプリタを使う

2.1. インタプリタを起動する

The Python interpreter is usually installed as /usr/local/bin/python3.12 on those machines where it is available; putting /usr/local/bin in your Unix shell's search path makes it possible to start it by typing the command:

python3.12

[1] どのディレクトリに Python インタプリタをインストールするかはインストール時に選択できるので、インタプリタは他のディレクトリにあるかもしれません; 身近な Python に詳しい人か、システム管理者に聞いてみてください。 (例えば、その他の場所としては /usr/local/python が一般的です。)

On Windows machines where you have installed Python from the Microsoft Store, the python3.12 command will be available. If you have the py.exe launcher installed, you can use the py command. See 補足: 環境変数の設定 for other ways to launch Python.

ファイル終端文字 (Unixでは Control-D 、DOS や Windows では Control-Z) を一次プロンプト (訳注: '>>>' のこと) に入力すると、インタプリタが終了ステータス 0 で終了します。もしこの操作がうまく働かないなら、コマンド: quit() と入力すればインタプリタを終了できます。

GNU Readline [https://tiswww.case.edu/php/chet/readline/rltop.html] ライブラリをサポートしているシステム上では、対話的行編集やヒストリ置換、コード補完のインタプリタの行編集機能が利用できます。コマンドライン編集機能がサポートされているかを最も手っ取り早く調べる方法は、おそらく最初に表示された Python プロンプトに Control-P を入力してみることでしょう。ビープ音が鳴るなら、コマンドライン編集機能があります。編集キーについての解説は付録 対話入力編集と履歴置換 を参照してください。何も起こらないように見えるか、 ^P がエコーバックされるなら、コマンドライン編集機能は利用できません。この場合、現在編集中の行から文字を削除するにはバックスペースを使うしかありません。

インタプリタは Unix シェルと同じように使えます。標準入力が端末に接続された状態では、コマンドを対話的に読み込んで実行します。ファイル名を引数に指定するか、python3 < filename のように標準入力ファイルとして指定すると、インタプリタはファイルから スクリプト を読み込んで実行します。

インタプリタを python -c command [arg] ... のように起動する方法もあります。この形式では、シェルの -c オプションと同じように、 command に指定した文を実行します。 Python 文には、スペースなどのシェルにとって特殊な意味をもつ文字がしばしば含まれるので、 command 全体をクォート(訳注: ')で囲っておいたほうが良いでしょう。

Python のモジュールには、スクリプトとしても便利に使えるものがあります。 python -m module [arg] ... のように起動すると、 module のソースファイルを、フルパスを指定して起動したかのように実行できます。

スクリプトファイルを使用する場合、スクリプトの実行が完了した後、そのまま対話モードに入れると便利なことがあります。これには -i をスクリプト名の前に追加します。

全てのコマンドラインオプションは コマンドラインと環境 で説明されています。

2.1.1. 引数の受け渡し

スクリプト名と引数を指定してインタプリタを起動した場合、スクリプト名やスクリプト名以後に指定した引数は、文字列のリストに変換されて sys モジュールの argv 変数に格納されます。 import sys とすることでこのリストにアクセスできます。 sys.argv には少なくとも一つ要素が入っています。スクリプト名も引数も指定しなければ、 sys.argv[0] は空の文字列になります。スクリプト名の代わりに '-' (標準入力を意味します) を指定すると、 sys.argv[0] は '-' になります。 -c command を使うと、 sys.argv[0] は '-c' になります。 -m module を使った場合、 sys.argv[0] はモジュールのフルパスになります。 Python インタープリタは、-c command や -m module の後ろに指定したオプションは無視します。無視された引数は、sys.argv を使って command や module から参照できます。

2.1.2. 対話モード

インタプリタが命令を端末 (tty) やコマンドプロンプトから読み取っている場合、インタプリタは 対話モード (interactive mode) で動作しているといいます。このモードでは、インタプリタは 一次プロンプト (primary prompt) を表示して、ユーザにコマンドを入力するよう促します。一次プロンプトは普通、三つの「大なり記号」 (>>>) です。継続行では、インタプリタは 二次プロンプト (secondary prompt) を表示します。二次プロンプトは、デフォルトでは三つのドット (...) です。インタプリタは、最初のプロンプトを出す前にバージョン番号と著作権表示から始まる起動メッセージを出力します:

$ python3.12
Python 3.12 (default, April 4 2022, 09:25:04)
[GCC 10.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>

継続行は、複数行の構文を入力するときに使います。例えば、 if 文は継続行を使用します

>>> the_world_is_flat = True
>>> if the_world_is_flat:
...     print("Be careful not to fall off!")
...
Be careful not to fall off!

対話モードについての詳細は 対話モード を参照してください。

2.2. インタプリタとその環境

2.2.1. ソースコードの文字コード

デフォルトでは、Python のソースコードは UTF-8 でエンコードされているものとして扱われます。UTF-8 では、世界中のほとんどの言語の文字を、同時に文字列リテラル、識別子、コメントなどに書けます。--- ただし、標準ライブラリは識別子に ASCII 文字のみを利用していて、その他のポータブルなコードもその慣習に従うべきです。それらの文字を正しく表示するためには、エディターはそのファイルが UTF-8 である事を識別して、そのファイルに含まれている文字を全てサポートしたフォントを使わなければなりません。

デフォルトエンコーディング以外のエンコーディングを使用するには、ファイルの 先頭 の行に特別なコメントを追加しなければなりません。書式は以下の通りです:

# -*- coding: encoding -*-

encoding には、Python が codecs でサポートしている有効なエンコーディングを指定します。

例えば、Windows-1252 エンコーディングを使用するには、ソースコードファイルの先頭行は下記のようにします:

# -*- coding: cp1252 -*-

ソースコードが UNIX "shebang" 行 で始まる場合には、先頭行 のルールは当てはまりません。この場合には、エンコーディングの宣言はファイルの2行目に追加します。例えば以下のようになります:

#!/usr/bin/env python3
# -*- coding: cp1252 -*-

脚注

[1]

Unixでは、Python 3.x インタープリタの実行ファイルはデフォルトでは python という名前ではインストールされません。同時にインストールされた Python 2.x 実行ファイルと衝突させないためです。

3. 形式ばらない Python の紹介

以下のサンプルでは、入力と出力はプロンプト (>>> や ...) の有無で区別します: 例を実際に試す場合は、プロンプトが表示されているときに、サンプル中のプロンプトから後ろの内容全てを入力します。

コード例の枠の右上にある >>> をクリックすると、プロンプトと出力の表示をトグルできます。コード例のプロンプトと出力を非表示にすると、簡単にインタープリタの入力にコピー&ペーストができます。

このマニュアルにあるサンプルの多くは、対話プロンプトで入力されるものでもコメントを含んでいます。 Python におけるコメント文は、ハッシュ文字 # で始まり、物理行の終わりまで続きます。コメントは行の先頭にも、空白やコードの後にも書くことができますが、文字列リテラルの内部に置くことはできません。文字列リテラル中のハッシュ文字はただのハッシュ文字です。コメントはコードを明快にするためのものであり、Pythonはコメントを解釈しません。なので、サンプルコードを実際に入力して試して見るときは、コメントを省いても大丈夫です。

いくつかの例です:

# this is the first comment
spam = 1  # and this is the second comment
          # ... and now a third!
text = "# This is not a comment because it's inside quotes."

3.1. Python を電卓として使う

それでは、簡単な Python コマンドをいくつか試してみましょう。インタプリタを起動して、一次プロンプト、 >>> が現れるのを待ちます。 (そう長くはかからないはずです)

3.1.1. 数

インタプリタは、簡単な電卓のように動作します: 式を入力すると、その結果が表示されます。式の文法は素直なものです: 演算子 + 、 - 、 * 、 / によって算術演算を行うことができ、丸括弧 (()) をグループ化に使うことができます。例えば:

>>> 2 + 2
4
>>> 50 - 5*6
20
>>> (50 - 5*6) / 4
5.0
>>> 8 / 5  # division always returns a floating point number
1.6

整数 (例えば、 2 、 4 、 20) は int 型であり、小数部を持つ数 (例えば、 5.0 、 1.6) は float 型です。数値型については後のチュートリアルでさらに見ていきます。

除算 (/) は常に浮動小数点数を返します。 // 演算子は 整数除算 を行い、整数値を返します; 剰余は、% で求めます。:

>>> 17 / 3  # classic division returns a float
5.666666666666667
>>>
>>> 17 // 3  # floor division discards the fractional part
5
>>> 17 % 3  # the % operator returns the remainder of the division
2
>>> 5 * 3 + 2  # floored quotient * divisor + remainder
17

Python では、冪乗を計算するのに ** 演算子が使えます [1]:

>>> 5 ** 2  # 5 squared
25
>>> 2 ** 7  # 2 to the power of 7
128

等号 (=) は変数に値を代入するときに使います。代入を行っても、結果は出力されず、次の入力プロンプトが表示されます。:

>>> width = 20
>>> height = 5 * 9
>>> width * height
900

変数が "定義" されていない (つまり値が代入されていない) 場合、その変数を使おうとするとエラーが発生します:

>>> n  # try to access an undefined variable
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'n' is not defined

浮動小数点を完全にサポートしています。演算対象の値(オペランド)に複数の型が入り混じっている場合、演算子は整数のオペランドを浮動小数点型に変換します:

>>> 4 * 3.75 - 1
14.0

対話モードでは、最後に表示された結果は変数 _ に代入されます。このことを利用すると、Python を電卓として使うときに、計算を連続して行う作業が多少楽になります。以下に例を示します:

>>> tax = 12.5 / 100
>>> price = 100.50
>>> price * tax
12.5625
>>> price + _
113.0625
>>> round(_, 2)
113.06

この変数には読取りだけを行い、明示的な代入を行ってはいけません --- そんなことをすれば、同じ名前で別のローカル変数が生成され、元の特別な動作をする組み込み変数を覆い隠してしておかしなことになってしまうかもしれません。

int と float に加え、 Python は Decimal や Fraction などの他の数値型もサポートしています。 複素数 も組み込み型としてサポートしており、 j もしくは J 接尾辞を使って虚部を示します (例: 3+5j)。

3.1.2. テキスト

Python は数値だけでなくテキスト (いわゆる「文字列」である str 型によって表現されます) を扱うことができます。 ! のような文字や rabbit のような単語、 Paris のような名前、 Got your back. ような文もすべて文字列です。文字列はシングルクォート ('...') またはダブルクォート ("...") で囲み、どちらを使っても違いはありません [2] 。

>>> 'spam eggs'  # single quotes
'spam eggs'
>>> "Paris rabbit got your back :)! Yay!"  # double quotes
'Paris rabbit got your back :)! Yay!'
>>> '1975'  # digits and numerals enclosed in quotes are also strings
'1975'

クォートの中でクォートを使いたい場合、 \ を前に付け加えることで「エスケープ」をする必要があります。もしくは、文字列で使用したいクォートとは別の方のクォートで囲むこともできます。

>>> 'doesn\'t'  # use \' to escape the single quote...
"doesn't"
>>> "doesn't"  # ...or use double quotes instead
"doesn't"
>>> '"Yes," they said.'
'"Yes," they said.'
>>> "\"Yes,\" they said."
'"Yes," they said.'
>>> '"Isn\'t," they said.'
'"Isn\'t," they said.'

Python シェルでは、文字列を定義するときと文字列が出力されるときでは見え方が異なることがあります。 print() 関数を使うと、両端のクォートがなくなり、エスケープされた文字や特殊文字が表示されるため、より読みやすい形で出力できます。

>>> s = 'First line.\nSecond line.'  # \n means newline
>>> s  # without print(), special characters are included in the string
'First line.\nSecond line.'
>>> print(s)  # with print(), special characters are interpreted, so \n produces new line
First line.
Second line.

\ に続く文字を特殊文字として解釈されたくない場合は、最初の引用符の前に r を付けた raw strings が使えます:

>>> print('C:\some\name')  # here \n means newline!
C:\some
ame
>>> print(r'C:\some\name')  # note the r before the quote
C:\some\name

raw文字列には微妙な面があります: raw文字列は奇数個の```` 文字では終了できません。詳細と解決方法については the FAQ entry を参照してください。

文字列リテラルは複数行にまたがって書けます。1 つの方法は三連引用符 ("""...""" や '''...''') を使うことです。改行文字は自動的に文字列に含まれますが、行末に \ を付けることで含めないようにすることもできます。次の例:

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

文字列は + 演算子で連結させる (くっつけて一つにする) ことができ、* 演算子で反復させることができます:

>>> # 3 times 'un', followed by 'ium'
>>> 3 * 'un' + 'ium'
'unununium'

連続して並んでいる複数の 文字列リテラル (つまり、引用符に囲われた文字列) は、自動的に連結されます。

>>> 'Py' 'thon'
'Python'

この機能は、長い文字列を改行したいときにとても役に立ちます:

>>> text = ('Put several strings within parentheses '
...         'to have them joined together.')
>>> text
'Put several strings within parentheses to have them joined together.'

これは 2 つのリテラルどうしに対してのみ働き、変数や式には働きません:

>>> prefix = 'Py'
>>> prefix 'thon'  # can't concatenate a variable and a string literal
  File "<stdin>", line 1
    prefix 'thon'
           ^^^^^^
SyntaxError: invalid syntax
>>> ('un' * 3) 'ium'
  File "<stdin>", line 1
    ('un' * 3) 'ium'
               ^^^^^
SyntaxError: invalid syntax

変数どうしや変数とリテラルを連結したい場合は、+ を使ってください:

>>> prefix + 'thon'
'Python'

文字列は インデックス (添字) を指定して文字を取得できます。最初の文字のインデックスは 0 になります。文字を表す、専用のデータ型は用意されていません; 文字とは、単に長さが 1 の文字列です:

>>> word = 'Python'
>>> word[0]  # character in position 0
'P'
>>> word[5]  # character in position 5
'n'

インデックスには、負の値も指定できまます。この場合、右から数えていきます:

>>> word[-1]  # last character
'n'
>>> word[-2]  # second-last character
'o'
>>> word[-6]
'P'

-0 は 0 と区別できないので、負のインデックスは -1 から始まります。

インデクス表記に加え、 スライス もサポートされています。インデクス表記は個々の文字を取得するのに使いますが、 スライス を使うと部分文字列を取得することができます:

>>> word[0:2]  # characters from position 0 (included) to 2 (excluded)
'Py'
>>> word[2:5]  # characters from position 2 (included) to 5 (excluded)
'tho'

スライスのインデックスには、便利なデフォルト値があります; 最初のインデックスを省略すると、0 と見なされます。二番め のインデックスを省略すると、スライスする文字列のサイズとみなされます。

>>> word[:2]   # character from the beginning to position 2 (excluded)
'Py'
>>> word[4:]   # characters from position 4 (included) to the end
'on'
>>> word[-2:]  # characters from the second-last (included) to the end
'on'

開始値は常に含まれ、終了値は常に含まれないことに注意してください。なので s[:i] + s[i:] は常に s と等しくなります:

>>> word[:2] + word[2:]
'Python'
>>> word[:4] + word[4:]
'Python'

スライスの使い方をおぼえる良い方法は、インデックスが文字と文字の あいだ (between) を指しており、最初の文字の左端が 0 になっていると考えることです。そうすると、 n 文字からなる文字列中の最後の文字の右端はインデックス n となります。例えばこうです:

 +---+---+---+---+---+---+
 | P | y | t | h | o | n |
 +---+---+---+---+---+---+
 0   1   2   3   4   5   6
-6  -5  -4  -3  -2  -1

1行目の数字は文字列の 0 から 6 までのインデックスの位置を示しています; 2行目は対応する負のインデックスを示しています。i から j までのスライスは、それぞれ i と付いた境界から j と付いた境界までの全ての文字から成っています。

正のインデックスの場合、スライスされたシーケンスの長さは、スライスの両端のインデックスが範囲内にあるかぎり、インデックス間の差になります。例えば、 word[1:3] の長さは 2 になります。

大き過ぎるインデックスを使おうとするとエラーが発生します:

>>> word[42]  # the word only has 6 characters
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
IndexError: string index out of range

しかし、スライスで範囲外のインデックスを使ったときは、上手く対応して扱ってくれます:

>>> word[4:42]
'on'
>>> word[42:]
''

Python の文字列は変更できません -- つまり 不変 です。従って、文字列のインデックスで指定したある場所に代入を行うとエラーが発生します:

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

元の文字列と別の文字列が必要な場合は、新しく文字列を作成してください:

>>> 'J' + word[1:]
'Jython'
>>> word[:2] + 'py'
'Pypy'

組込み関数 len() は文字列の長さ (length) を返します:

>>> s = 'supercalifragilisticexpialidocious'
>>> len(s)
34

参考

テキストシーケンス型 --- str

文字列は代表的な シーケンス型 で、シーケンス型でサポートされている共通の操作をサポートしています。

文字列メソッド

文字列は、基本的な変換や検索を行うための数多くのメソッドをサポートしています。

f-strings

式の埋め込みをサポートした文字列リテラル

書式指定文字列の文法

str.format() を使った文字列のフォーマットについての情報があります。

printf 形式の文字列書式化

文字列が % 演算子の左オペランドである場合に呼び出される古いフォーマット操作について、詳しく記述されています。

3.1.3. リスト型 (list)

Pythonは多くの 複合 (compound) データ型を備えており、複数の値をまとめるのに使われます。最も汎用性が高いのは リスト (list) で、コンマ区切りの値 (要素) の並びを角括弧で囲んだものとして書き表されます。リストは異なる型の要素を含むこともありますが、通常は同じ型の要素のみを持ちます。

>>> squares = [1, 4, 9, 16, 25]
>>> squares
[1, 4, 9, 16, 25]

文字列 (や他の全ての組み込みの シーケンス 型) のように、リストはインデックスやスライスができます:

>>> squares[0]  # indexing returns the item
1
>>> squares[-1]
25
>>> squares[-3:]  # slicing returns a new list
[9, 16, 25]

リストは、リストの連結などもサポートしています:

>>> squares + [36, 49, 64, 81, 100]
[1, 4, 9, 16, 25, 36, 49, 64, 81, 100]

不変 な文字列とは違って、リストは 可変 型ですので、要素を入れ替えられます:

>>> cubes = [1, 8, 27, 65, 125]  # something's wrong here
>>> 4 ** 3  # the cube of 4 is 64, not 65!
64
>>> cubes[3] = 64  # replace the wrong value
>>> cubes
[1, 8, 27, 64, 125]

list.append() を使って、リストの末尾に新しい要素を追加できます (このメソッドについては後で詳しく見ていきます):

>>> cubes.append(216)  # add the cube of 6
>>> cubes.append(7 ** 3)  # and the cube of 7
>>> cubes
[1, 8, 27, 64, 125, 216, 343]

単純な代入ではPythonは決してデータをコピーしません。リストを変数に代入すると、その変数は 既存のリスト を参照します。ある変数を通してリストに任意の変更を行うと、そのリストを参照したすべての他の変数を通して確認できます。:

>>> rgb = ["Red", "Green", "Blue"]
>>> rgba = rgb
>>> id(rgb) == id(rgba)  # they reference the same object
True
>>> rgba.append("Alph")
>>> rgb
["Red", "Green", "Blue", "Alph"]

全てのスライス操作は、指定された要素を含む新しいリストを返します。例えば、次のスライスは、リストの 浅いコピー を返します。:

>>> correct_rgba = rgba[:]
>>> correct_rgba[-1] = "Alpha"
>>> correct_rgba
["Red", "Green", "Blue", "Alpha"]
>>> rgba
["Red", "Green", "Blue", "Alph"]

スライスには、代入もできます。スライスの代入で、リストのサイズを変更したり、全てを削除したりもできます:

>>> letters = ['a', 'b', 'c', 'd', 'e', 'f', 'g']
>>> letters
['a', 'b', 'c', 'd', 'e', 'f', 'g']
>>> # replace some values
>>> letters[2:5] = ['C', 'D', 'E']
>>> letters
['a', 'b', 'C', 'D', 'E', 'f', 'g']
>>> # now remove them
>>> letters[2:5] = []
>>> letters
['a', 'b', 'f', 'g']
>>> # clear the list by replacing all the elements with an empty list
>>> letters[:] = []
>>> letters
[]

組込み関数 len() はリストにも使えます:

>>> letters = ['a', 'b', 'c', 'd']
>>> len(letters)
4

リストを入れ子 (ほかのリストを含むリストを造る) にできます。例えば:

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

3.2. プログラミングへの第一歩

もちろん、2 たす 2 よりももっと複雑な課題にも Python を使えます。例えば、Fibonacci series [https://en.wikipedia.org/wiki/Fibonacci_sequence] の先頭の部分列は次のように書けます:

>>> # Fibonacci series:
... # the sum of two elements defines the next
... a, b = 0, 1
>>> while a < 10:
...     print(a)
...     a, b = b, a+b
...
0
1
1
2
3
5
8

上の例では、いくつか新しい機能を使用しています。

最初の行には 複数同時の代入 (multiple assignment) が入っています: 変数 a と b は、それぞれ同時に新しい値 0 と 1 になっています。この代入は、最後の行でも使われています。代入文では、まず右辺の式がすべて評価され、次に代入が行われます。右辺の式は、左から右へと順番に評価されます。

while は、条件 (ここでは `` a < 10``) が真である限り実行を繰り返し (ループし) ます。Python では、C 言語と同様に、ゼロでない整数値は真となり、ゼロは偽です。条件式には、文字列値やリスト値なども使えます。それ以外のシーケンスも、条件式として使用できます。長さが 1 以上のシーケンスは真で、空のシーケンスは偽になります。サンプルで使われている条件テストはシンプルな比較です。標準的な比較演算子は C 言語と同様です: すなわち、 < (より小さい)、 > (より大きい)、 == (等しい)、 <= (より小さいか等しい)、 >= (より大きいか等しい)、および != (等しくない)、です。

ループの 本体 (body) は、 インデント (indent, 字下げ) されています: インデントは Python において、実行文をグループにまとめる方法です。対話的プロンプトでは、インデントされた各行を入力するにはタブや (複数個の) スペースを使わなければなりません。実用的には、もっと複雑な処理を入力する場合はテキストエディタを使うことになるでしょう。 ほとんどのテキストエディタは、自動インデント機能を持っています。複合文を対話的に入力するときには、入力完了のしるしとして最後に空行を入力します。これは、パーザはどれが最後の行を入力なのか、判断できないためです。基本的なブロック内では、全ての行は同じだけインデントされていなければならないので注意してください。

print() 関数は、与えられた引数の値を書き出します。これは (前に電卓の例でやったような) 単に出力したい式を書くのとは、複数の引数や浮動小数点量や文字列に対する扱い方が違います。print() 関数では、文字列は引用符無しで出力され、要素の間に空白が挿入されて、このように出力の書式が整えられます:

>>> i = 256*256
>>> print('The value of i is', i)
The value of i is 65536

キーワード引数 end を使うと、出力の末尾に改行文字を出力しないようにしたり、別の文字列を末尾に出力したりできます:

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

脚注

[1]

** は - より優先順位が高いので、-3**2 は -(3**2) と解釈され、計算結果は -9 になります。これを避けて 9 を得たければ、(-3)**2 と書きます。

[2]

他の言語と違って、\n のような特殊文字は、単引用符 ('...') と二重引用符 ("...") で同じ意味を持ちます。両者の唯一の違いは、単引用符で囲われた箇所では " をエスケープする必要がない (ただし \' はエスケープする必要がある) ことで、逆もまた同様です。

4. その他の制御フローツール

前章で紹介した while 文の他にも、 Python にはいくつか制御フローツールがあり、本章で説明します。

4.1. if 文

おそらく最もおなじみの文型は if 文でしょう。例えば:

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

ゼロ個以上の elif 部を使うことができ、 else 部を付けることもできます。キーワード 'elif' は 'else if' を短くしたもので、過剰なインデントを避けるのに役立ちます。一連の if ... elif ... elif ... は、他の言語における switch 文や case 文の代用となります。

いくつかの定数と同じ値かを比較する場合や、特定の型や属性かを確認する場合には、match 文が便利です。詳細は match 文 を参照してください。

4.2. for 文

Python の for 文は、読者が C 言語や Pascal 言語で使いなれているかもしれない for 文とは少し違います。 (Pascal のように) 常に算術型の数列にわたる反復を行ったり、 (C のように) 繰返しステップと停止条件を両方ともユーザが定義できるようにするのとは違い、Python の for 文は、任意のシーケンス型 (リストまたは文字列) にわたって反復を行います。反復の順番はシーケンス中に要素が現れる順番です。例えば:

>>> # Measure some strings:
... words = ['cat', 'window', 'defenestrate']
>>> for w in words:
...     print(w, len(w))
...
cat 3
window 6
defenestrate 12

コレクションオブジェクトの値を反復処理をしているときに、そのコレクションオブジェクトを変更するコードは理解するのが面倒になり得ます。そうするよりも、コレクションオブジェクトのコピーに対して反復処理をするか、新しいコレクションオブジェクトを作成する方が通常は理解しやすいです:

# Create a sample collection
users = {'Hans': 'active', 'Éléonore': 'inactive', '景太郎': 'active'}

# Strategy:  Iterate over a copy
for user, status in users.copy().items():
    if status == 'inactive':
        del users[user]

# Strategy:  Create a new collection
active_users = {}
for user, status in users.items():
    if status == 'active':
        active_users[user] = status

4.3. range() 関数

数列にわたって反復を行う必要がある場合、組み込み関数 range() が便利です。この関数は算術型の数列を生成します:

>>> for i in range(5):
...     print(i)
...
0
1
2
3
4

指定した終端値は生成されるシーケンスには入りません。range(10) は 10 個の値を生成し、長さ 10 のシーケンスにおける各項目のインデクスとなります。range を別の数から開始したり、他の増加量 (負でも; 増加量は時に 'ステップ(step)' と呼ばれることもあります) を指定することもできます:

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

あるシーケンスにわたってインデクスで反復を行うには、 range() と len() を次のように組み合わせられます:

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

しかし、多くの場合は enumerate() 関数を使う方が便利です。 ループのテクニック を参照してください。

range を直接出力すると変なことになります:

>>> range(10)
range(0, 10)

range() が返すオブジェクトは、いろいろな点でリストであるかのように振る舞いますが、本当はリストではありません。これは、イテレートした時に望んだ数列の連続した要素を返すオブジェクトです。しかし実際にリストを作るわけではないので、スペースの節約になります。

このようなオブジェクトは イテラブル と呼ばれます。これらは関数や構成物のターゲットとして、あるだけの項目を逐次与えるのに適しています。 for 文がそのような構成物であることはすでに見てきており、イテラブルを受け取る関数の例には sum() があります:

>>> sum(range(4))  # 0 + 1 + 2 + 3
6

この後には、イテラブルを返したりイテラブルを引数で受け取るいくつかの関数が出てきます。 データ構造 では、 list() についてより詳しく説明します。

4.4. break 文と continue 文とループの else 節

break 文は、その break 文を内包している最も内側にある for 文または while 文から抜け出すことができます。

for 文と while 文では else 節を書くことができます。

for 文の場合、 else 節はループ処理の最後の回が実行されたあとに実行されます。

while 文の場合は、ループ条件が偽となったあとに実行されます。

どちらのループ文でも、 break によってループ処理が終了したときは else 節は**実行されません**。

その例として、素数を探索する for 文を以下に示します:

>>> for n in range(2, 10):
...     for x in range(2, n):
...         if n % x == 0:
...             print(n, 'equals', x, '*', n//x)
...             break
...     else:
...         # loop fell through without finding a factor
...         print(n, 'is a prime number')
...
2 is a prime number
3 is a prime number
4 equals 2 * 2
5 is a prime number
6 equals 2 * 3
7 is a prime number
8 equals 2 * 4
9 equals 3 * 3

(そう、これは正しいコードです。よく見てください: else 節は if 文 ではなく 、 for ループに属しています。)

ループの else 句は、 if 文の else よりも try 文の else に似ています。 try 文の else 句は例外が発生しなかった時に実行され、ループの else 句は break されなかった場合に実行されます。 try 文と例外についての詳細は 例外を処理する を参照してください。

continue 文も C 言語から借りてきたもので、ループの次のイテレーションを実行します:

>>> for num in range(2, 10):
...     if num % 2 == 0:
...         print("Found an even number", num)
...         continue
...     print("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

4.5. pass 文

pass 文は何もしません。 pass は、文を書くことが構文上要求されているが、プログラム上何の動作もする必要がない時に使われます:

>>> while True:
...     pass  # Busy-wait for keyboard interrupt (Ctrl+C)
...

これは最小のクラスを作るときによく使われる方法です:

>>> class MyEmptyClass:
...     pass
...

pass のもう 1 つの使い道は、新しいコードを書いているときの関数や条件文の仮置きの本体としてです。こうすることで、より抽象的なレベルで考え続けられます。 pass は何事も無く無視されます

>>> def initlog(*args):
...     pass   # Remember to implement this!
...

4.6. match 文

match 文は1つの式を指定し、その値と次に続く1つ以上のcaseブロックに指定されたパターンを比較します。この機能はCやJava、JavaScript(や他の多数の言語)のswitch文と表面的には似ていますが、RustやHaskellのパターンマッチングにより似ています。最初にマッチしたパターンのみが実行され、コンポーネント(シーケンスの要素やオブジェクトの属性)から値を取り出して変数に代入することもできます。

最も単純な形式は、対象の値に対して1つ以上のリテラルです:

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"

最後のブロックについて: 変数名 _ は ワイルドカード の働きをし、マッチに絶対失敗しません。マッチするケースがない場合は、そのブロックも実行されません。

複数のリテラルを | ("or")を使用して組み合わせて1つのパターンにできます:

case 401 | 403 | 404:
    return "Not allowed"

パターンはアンパック代入ができ、変数に結びつけられます:

# 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")

このコードは注意して見てください！最初のパターンには2つのリテラルがあり、上で示したリテラルパターンの拡張と考えることができます。しかし次の2つのパターンはリテラルと変数の組み合わせのため、対象(point)から値を取り出して変数に 結びつけ ます。 4番目のパターンは2つの値を取り込みます。これは、アンパック代入 (x, y) = point と概念的に似ています。

データを構造化するためにクラスを使っている場合は、クラス名の後ろにコンストラクターのように引数のリストを指定できます。属性の値は変数に取り込まれます。

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")

いくつかの組み込みクラスでは位置引数が使用でき、属性の順番を提供します(例: データクラス)。クラスの __match_args__ 特殊属性によって、パターンの中で属性の明確な位置を定義することもできます。("x", "y")が設定された場合、以下のすべてのパターンは等価です(すべて属性 y が var 変数に結びつけられます):

Point(1, var)
Point(1, y=var)
Point(x=1, y=var)
Point(y=var, x=1)

おすすめのパターンの読み方は、パターンが、代入文の左辺に配置するものを拡張した形式であるとみなすことです。これにより、どの変数になにが代入されるかが分かります。単独の名前（上記の var など）だけがマッチ文で値が代入されます。ドット付きの名前（foo.bar など）、属性名（上記の x=、y= など ）、クラス名（名前の後ろの "(...)" によって判別される。上記の Point など）には値は代入されません。

パターンはいくらでも入れ子 (ネスト) にすることができます。例えば、 __match_args__ を追加した Point クラスのリストに対して次のようにマッチを行うことができます:

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")

パターンに if 節を追加できます。これは "ガード" と呼ばれます。ガードがfalseの場合、match は次のcaseブロックの処理に移動します。ガードを評価する前に値が取り込まれることに注意してください:

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")

この文のその他のいくつか重要な特徴:

アンパック代入のように、タプルとリストのパターンでは正確に同じ意味で、任意のシーケンスと一致します。重要な例外として、イテレーターや文字列ではマッチしません。

シーケンスパターンは拡張アンパックをサポート: [x, y, *rest] と (x, y, *rest) はアンパック代入として同じように動作します。* のあとの変数名は _ でもよく、そのため (x, y, *_) は最低でも2つのアイテムを持つシーケンスにマッチし、残りのアイテムは変数に結びつけられません。

マッピングパターン: {"bandwidth": b, "latency": l} は辞書から "bandwidth" と "latency" の値を取り込みます。シーケンスパターンとは異なり、それ以外のキーは無視されます。アンパッキングのような **rest もサポートされています（しかし、 **_ は冗長なため禁止されています）。

サブパターンでは as キーワードを使用して値を取り込みます:

case (Point(x1, y1), Point(x2, y2) as p2): ...

この例では入力から2番目の要素を p2 として取り込みます（入力が2つのポイントのシーケンスである場合）

ほとんどのリテラルは同一性を比較しますが、シングルトンの True、False、None では識別値を比較します。

パターンには名前を付けた定数が使用できます。値を取り込む変数としてと解釈することを防ぐために、ドット付きの変数名にする必要があります。

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 :(")

より詳細な説明と追加の例は PEP 636 [https://peps.python.org/pep-0636/] にチュートリアル形式で記述してあります。

4.7. 関数を定義する

フィボナッチ数列 (Fibonacci series) を任意の上限値まで書き出すような関数を作成できます:

>>> def fib(n):    # write Fibonacci series up to n
...     """Print a Fibonacci series up to n."""
...     a, b = 0, 1
...     while a < n:
...         print(a, end=' ')
...         a, b = b, a+b
...     print()
...
>>> # Now call the function we just defined:
... fib(2000)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597

def は関数の 定義 (definition) を導くキーワードです。 def の後には、関数名と仮引数を丸括弧で囲んだリストを続けなければなりません。関数の実体を構成する実行文は次の行から始め、インデントされていなければなりません。

関数の本体の記述する文の最初の行は文字列リテラルにすることもできます。その場合、この文字列は関数のドキュメンテーション文字列 (documentation string)、または docstring と呼ばれます。 (docstring については ドキュメンテーション文字列 でさらに扱っています。) ドキュメンテーション文字列を使ったツールには、オンライン文書や印刷文書を自動的に生成したり、ユーザが対話的にコードから直接閲覧できるようにするものがあります。自分が書くコードにドキュメンテーション文字列を入れるのはよい習慣です。書く癖をつけてください。

関数を 実行 (execution) するとき、関数のローカル変数のために使われる新たなシンボルテーブル (symbol table) が用意されます。もっと正確にいうと、関数内で変数への代入を行うと、その値はすべてこのローカルなシンボルテーブルに記憶されます。一方、変数の参照を行うと、まずローカルなシンボルテーブルが検索され、次にさらに外側の関数のローカルなシンボルテーブルを検索し、その後グローバルなシンボルテーブルを調べ、最後に組み込みの名前テーブルを調べます。従って、関数の中では (グローバル変数が global 文で指定されていたり、外側の関数の変数が nonlocal 文で指定されていない限り) グローバル変数や外側の関数の変数に直接値を代入できませんが、参照することはできます。

関数を呼び出す際の実際の引数 (実引数) は、関数が呼び出されるときに関数のローカルなシンボルテーブル内に取り込まれます。そうすることで、実引数は 値渡し (call by value) で関数に渡されることになります (ここでの 値 (value) とは常にオブジェクトへの 参照(reference) をいい、オブジェクトの値そのものではありません) [1]。ある関数がほかの関数を呼び出すときや、自身を再帰的に呼び出すときには、新たな呼び出しのためにローカルなシンボルテーブルが新たに作成されます。

関数の定義を行うと、関数名は関数オブジェクトとともに現在のシンボルテーブル内に取り入れられます。インタープリタはその名前が指すオブジェクトをユーザ定義関数 (user-defined function) として認識します。他の名前も同じ関数オブジェクトを指すことができ、またその関数にアクセスするために使用することができます:

>>> fib
<function fib at 10042ed0>
>>> f = fib
>>> f(100)
0 1 1 2 3 5 8 13 21 34 55 89

他の言語出身の人からは、 fib は値を返さないので関数ではなく手続き (procedure) だと異論があるかもしれませんね。技術的に言えば、実際には return 文を持たない関数もややつまらない値ですが値を返しています。この値は None と呼ばれます (これは組み込みの名前です)。 None だけを書き出そうとすると、インタプリタは通常出力を抑制します。本当に出力したいのなら、以下のように print() を使うと見ることができます:

>>> fib(0)
>>> print(fib(0))
None

フィボナッチ数列の数からなるリストを出力する代わりに、値を返すような関数を書くのは簡単です:

>>> def fib2(n):  # return Fibonacci series up to n
...     """Return a list containing the Fibonacci series up to n."""
...     result = []
...     a, b = 0, 1
...     while a < n:
...         result.append(a)    # see below
...         a, b = b, a+b
...     return result
...
>>> f100 = fib2(100)    # call it
>>> f100                # write the result
[0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]

この例は Python の新しい機能を示しています:

return 文では、関数から一つ値を返します。 return の引数となる式がない場合、 None が返ります。関数が終了したときにも None が返ります。

result.append(a) という文で、 result オブジェクトの*メソッド* が呼び出されます。メソッドとは、オブジェクトに「属する」関数のことであり、 obj.methodname と表されます。ここで、 obj は何らかのオブジェクト (式の場合もあります) であり、 methodname はそのオブジェクトの型で定義されたメソッド名です。色々な型がそれぞれ独自のメソッドを定義しています。異なる型が同じ名前のメソッドを持つことも可能であり、どちらの方のものであるかという曖昧さは生まれません。 (*クラス*を使って独自の型やメソッドを自分で定義することもできます。参照: クラス) 例にある append() メソッドは、リストオブジェクトに対して定義されているもので、リストの末尾に新しい要素を追加します。この例では result = result + [a] と等価ですが、計算効率の上ではベターです。

4.8. 関数定義についてもう少し

可変個の引数を伴う関数を定義することもできます。引数の定義方法には 3 つの形式があり、それらを組み合わせることができます。

4.8.1. デフォルトの引数値

もっとも便利なのは、一つ以上の引数に対してデフォルトの値を指定する形式です。この形式を使うと、定義されている引数より少ない個数の引数で呼び出せる関数を作成します:

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)

この関数はいくつかの方法で呼び出せます:

必須の引数のみ与える: ask_ok('Do you really want to quit?')

一つのオプション引数を与える: ask_ok('OK to overwrite the file?', 2)

全ての引数を与える: ask_ok('OK to overwrite the file?', 2, 'Come on, only yes or no!')

この例では in キーワードが導入されています。このキーワードはシーケンスが特定の値を含んでいるかどうか調べるのに使われます。

デフォルト値は、関数が定義された時点で、関数を 定義している 側のスコープ (scope) で評価されるので

i = 5

def f(arg=i):
    print(arg)

i = 6
f()

は 5 を出力します。

重要な警告: デフォルト値は 1 度だけしか評価されません。デフォルト値がリストや辞書のような変更可能なオブジェクトの時にはその影響がでます。例えば以下の関数は、後に続く関数呼び出しで関数に渡されている引数を累積します:

def f(a, L=[]):
    L.append(a)
    return L

print(f(1))
print(f(2))
print(f(3))

このコードは、以下を出力します

[1]
[1, 2]
[1, 2, 3]

後続の関数呼び出しでデフォルト値を共有したくなければ、代わりに以下のように関数を書くことができます:

def f(a, L=None):
    if L is None:
        L = []
    L.append(a)
    return L

4.8.2. キーワード引数

関数を kwarg=value という形式の キーワード引数 を使って呼び出すこともできます。例えば、以下の関数:

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, "!")

は、必須引数 (voltage) とオプション引数 (state、action、type) を受け付けます。この関数は以下のいずれかの方法で呼び出せます:

parrot(1000)                                          # 1 positional argument
parrot(voltage=1000)                                  # 1 keyword argument
parrot(voltage=1000000, action='VOOOOOM')             # 2 keyword arguments
parrot(action='VOOOOOM', voltage=1000000)             # 2 keyword arguments
parrot('a million', 'bereft of life', 'jump')         # 3 positional arguments
parrot('a thousand', state='pushing up the daisies')  # 1 positional, 1 keyword

が、以下の呼び出しは不適切です:

parrot()                     # required argument missing
parrot(voltage=5.0, 'dead')  # non-keyword argument after a keyword argument
parrot(110, voltage=220)     # duplicate value for the same argument
parrot(actor='John Cleese')  # unknown keyword argument

関数の呼び出しにおいて、キーワード引数は位置引数の後でなければなりません。渡されるキーワード引数は全て、関数で受け付けられる引数のいずれかに対応していなければならず (例えば、actor はこの parrot 関数の引数として適切ではありません)、順序は重要ではありません。これはオプションでない引数でも同様です (例えば、parrot(voltage=1000) も適切です)。いかなる引数も値を複数回は受け取れません。この制限により失敗する例は:

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

仮引数の最後に **name の形式のものがあると、それまでの仮引数に対応したものを除くすべてのキーワード引数が入った辞書 (マッピング型 --- dict を参照) を受け取ります。 **name は *name の形式をとる、仮引数のリストを超えた位置引数の入った タプル を受け取る引数 (次の小節で述べます) と組み合わせられます。 (*name は **name より前になければなりません)。例えば、ある関数の定義を以下のようにすると:

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])

呼び出しは以下のようになり:

cheeseshop("Limburger", "It's very runny, sir.",
           "It's really very, VERY runny, sir.",
           shopkeeper="Michael Palin",
           client="John Cleese",
           sketch="Cheese Shop Sketch")

もちろん以下のように出力されます:

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

なお、複数のキーワード引数を与えた場合に、それらが出力される順序は、関数呼び出しで与えられた順序と同じになります。

4.8.3. 特殊なパラメータ

デフォルトでは、引数は位置またはキーワードによる明示で Python 関数に渡されます。可読性とパフォーマンスのために、その引数が位置、位置またはキーワード、キーワードのどれで渡されるかを開発者が判定するのに関数定義だけを見ればよいように、引数の渡され方を制限することには意味があります。

関数定義は次のようになります:

def f(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2):
      -----------    ----------     ----------
        |             |                  |
        |        Positional or keyword   |
        |                                - Keyword only
         -- Positional only

ここで、/ と * はオプションです。使用された場合、これらの記号は、引数が関数に渡される方法、すなわち、位置専用、位置またはキーワード、キーワード専用、といった引数の種類を示します。キーワード引数は、名前付き引数とも呼ばれます。

4.8.3.1. 位置またはキーワード引数

関数定義に / も * もない場合は、引数は位置またはキーワードで関数に渡されます。

4.8.3.2. 位置専用引数

これをもう少し詳しく見てみると、特定の引数を 位置専用 と印を付けられます。位置専用 の場合、引数の順序が重要であり、キーワードで引数を渡せません。位置専用引数は / （スラッシュ）の前に配置されます。 / は、位置専用引数を残りの引数から論理的に分離するために使用されます。関数定義に / がない場合、位置専用引数はありません。

/ の後の引数は、 位置またはキーワード 、もしくは、 キーワード専用 です。

4.8.3.3. キーワード専用引数

引数をキーワード引数で渡す必要があることを示す キーワード専用 として引数をマークするには、引数リストの最初の キーワード専用 引数の直前に * を配置します。

4.8.3.4. 関数の例

/ および * といったマーカーに注意を払って、次の関数定義の例を見てください:

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

最も馴染みのある形式の最初の関数定義 standard_arg は、呼び出し規約に制限を設けておらず、引数は位置またはキーワードで渡されます:

>>> standard_arg(2)
2

>>> standard_arg(arg=2)
2

2番目の関数の pos_only_arg は、 / が関数定義にあるので、引数は位置専用になります:

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

3番目の関数 kwd_only_args は、関数定義に * があるので、引数はキーワード専用になります:

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

そして最後の関数は3つの引数の種類を一つの関数定義の中で使用しています:

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

最後に、位置引数 name と name をキーとして持つ **kwds の間に潜在的な衝突がある関数定義を考えてみましょう。

def foo(name, **kwds):
    return 'name' in kwds

キーワードに 'name' を入れても、先頭の引数と同じになってしまうため、この関数が True を返すような呼び出しの方法はありません。例えば、次のようになってしまいます:

>>> foo(1, **{'name': 2})
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: foo() got multiple values for argument 'name'
>>>

しかし位置専用を示す / を使用すれば可能になります。 name は位置引数として、そして 'name' はキーワード引数のキーワードとして認識されるからです:

>>> def foo(name, /, **kwds):
...     return 'name' in kwds
...
>>> foo(1, **{'name': 2})
True

言い換えると、位置専用引数であれば、その名前を **kwds の中で使用しても、曖昧にならないということです。

4.8.3.5. 要約

使用例で、関数定義でどの種類の引数を使うかべきかがわかると思います:

def f(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2):

ガイドとしては、

もし引数の名前をユーザーに知らせる必要がないなら、位置専用引数を使用しましょう。これは引数の名前がユーザーにとって意味がなく、関数が呼ばれたときの引数の順序が問題であり、または、位置引数と任意のキーワードを使用する必要がある場合に便利です。

引数の名前に意味があり、それにより関数の定義がより明らかになる、または、ユーザーが引数の順番に縛られることを避けたほうがいいと考えるのなら、キーワード専用引数を使用しましょう。

APIの場合、将来引数の名前が変更された場合にAPIの変更ができなくなることを防ぐために、位置専用引数を使用しましょう。

4.8.4. 任意引数リスト

最後に、最も使うことの少ない選択肢として、関数が任意の個数の引数で呼び出せるよう指定する方法があります。これらの引数はタプル (タプルとシーケンス を参照) に格納されます。可変個の引数の前に、ゼロ個かそれ以上の引数があっても構いません。

def write_multiple_items(file, separator, *args):
    file.write(separator.join(args))

通常このような 可変 引数は、関数に渡される入力引数の残りを全て掬い取るために、仮引数リストの最後に置かれます。 *args 引数の後にある仮引数は 'キーワード専用' 引数で、位置引数ではなくキーワード引数としてのみ使えることを意味します。

>>> def concat(*args, sep="/"):
...     return sep.join(args)
...
>>> concat("earth", "mars", "venus")
'earth/mars/venus'
>>> concat("earth", "mars", "venus", sep=".")
'earth.mars.venus'

4.8.5. 引数リストのアンパック

引数がすでにリストやタプルになっていて、個別な位置引数を要求する関数呼び出しに渡すためにアンパックする必要がある場合には、逆の状況が起こります。例えば、組み込み関数 range() は引数 start と stop を別に与える必要があります。個別に引数を与えることができない場合、関数呼び出しを * 演算子を使って書き、リストやタプルから引数をアンパックします:

>>> list(range(3, 6))            # normal call with separate arguments
[3, 4, 5]
>>> args = [3, 6]
>>> list(range(*args))            # call with arguments unpacked from a list
[3, 4, 5]

同じやりかたで、** オペレータを使って辞書でもキーワード引数を渡すことができます:

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

4.8.6. ラムダ式

キーワード lambda を使うと、名前のない小さな関数を生成できます。例えば lambda a, b: a+b は、二つの引数の和を返す関数です。ラムダ式の関数は、関数オブジェクトが要求されている場所にならどこでも使うことができます。ラムダ式は、構文上単一の式に制限されています。意味付け的には、ラムダ形式は単に通常の関数定義に構文的な糖衣をかぶせたものに過ぎません。入れ子構造になった関数定義と同様、ラムダ式もそれを取り囲むスコープから変数を参照することができます:

>>> def make_incrementor(n):
...     return lambda x: x + n
...
>>> f = make_incrementor(42)
>>> f(0)
42
>>> f(1)
43

上記の例は、関数を返すところでラムダ式を使っています。もう1つの例では、ちょっとした関数を引数として渡すのに使っています:

>>> 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')]

4.8.7. ドキュメンテーション文字列

ドキュメンテーション文字列については、その内容と書式に関する慣習をいくつか挙げます。

最初の行は、常に対象物の目的を短く簡潔にまとめたものでなくてはなりません。簡潔に書くために、対象物の名前や型を明示する必要はありません。名前や型は他の方法でも得られるからです (名前がたまたま関数の演算内容を記述する動詞である場合は例外です)。最初の行は大文字で始まり、ピリオドで終わっていなければなりません。

ドキュメンテーション文字列中にさらに記述すべき行がある場合、二行目は空行にし、まとめの行と残りの記述部分を視覚的に分離します。つづく行は一つまたはそれ以上の段落で、対象物の呼び出し規約や副作用について記述します。

Python のパーザは複数行にわたる Python 文字列リテラルからインデントを剥ぎ取らないので、ドキュメントを処理するツールでは必要に応じてインデントを剥ぎ取らなければなりません。この処理は以下の規約に従って行います。最初の行の 後にある 空行でない最初の行が、ドキュメント全体のインデントの量を決めます。(最初の行は通常、文字列を開始するクオートに隣り合っているので、インデントが文字列リテラル中に現れないためです。) このインデント量と "等価な" 空白が、文字列のすべての行頭から剥ぎ取られます。インデントの量が少ない行を書いてはならないのですが、もしそういう行があると、先頭の空白すべてが剥ぎ取られます。インデントの空白の大きさが等しいかどうかは、タブ文字を (通常は 8 文字のスペースとして) 展開した後に調べられます。

以下に複数行のドキュメンテーション文字列の例を示します:

>>> def my_function():
...     """Do nothing, but document it.
...
...     No, really, it doesn't do anything.
...     """
...     pass
...
>>> print(my_function.__doc__)
Do nothing, but document it.

    No, really, it doesn't do anything.

4.8.8. 関数のアノテーション

関数アノテーション はユーザ定義関数で使用される型についての完全にオプションなメタデータ情報です (詳細は PEP 3107 [https://peps.python.org/pep-3107/] と PEP 484 [https://peps.python.org/pep-0484/] を参照してください)。

アノテーション は、関数の __annotations__ 属性に辞書として格納され、関数の他の部分には影響しません。パラメータアノテーションは、パラメータ名のあとのコロンと式で定義され、その式の評価結果がアノテーションとなります。戻り値アノテーションは、パラメータリストと def 文の終わりを表すコロンの間で、 -> の後ろに式を書くことで定義されます。次の例では、必須引数と任意引数、戻り値にアノテーションが付与されています:

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

4.9. 間奏曲: コーディングスタイル

これからより長くより複雑な Python のコードを書いていくので、そろそろ コーディングスタイル について語っても良い頃です。ほとんどの言語は様々なスタイルで書け (もっと簡潔に言えば フォーマットでき)、スタイルによって読み易さが異なります。他人にとって読み易いコードにしようとするのはどんなときでも良い考えであり、良いコーディングスタイルを採用することが非常に強力な助けになります。

Python には、ほとんどのプロジェクトが守っているスタイルガイドとして PEP 8 [https://peps.python.org/pep-0008/] があります。それは非常に読み易く目に優しいコーディングスタイルを推奨しています。全ての Python 開発者はある時点でそれを読むべきです。ここに最も重要な点を抜き出しておきます:

インデントには空白 4 つを使い、タブは使わないこと。

空白 4 つは (深くネストできる) 小さいインデントと (読み易い) 大きいインデントのちょうど中間に当たります。タブは混乱させるので、使わずにおくのが良いです。

ソースコードの幅が 79 文字を越えないように行を折り返すこと。

こうすることで小さいディスプレイを使っているユーザも読み易くなり、大きなディスプレイではソースコードファイルを並べることもできるようになります。

関数やクラスや関数内の大きめのコードブロックの区切りに空行を使うこと。

可能なら、コメントは行に独立で書くこと。

docstring を使うこと。

演算子の前後とコンマの後には空白を入れ、括弧類のすぐ内側には空白を入れないこと: a = f(1, 2) + g(3, 4)。

クラスや関数に一貫性のある名前を付けること。慣習では UpperCamelCase をクラス名に使い、 lowercase_with_underscores を関数名やメソッド名に使います。常に self をメソッドの第 1 引数の名前 (クラスやメソッドについては クラス初見 を見よ) として使うこと。

あなたのコードを世界中で使ってもらうつもりなら、風変りなエンコーディングは使わないこと。どんな場合でも、Python のデフォルト UTF-8 またはプレーン ASCII が最も上手くいきます。

同様に、ほんの少しでも他の言語を話す人がコードを読んだりメンテナンスする可能性があるのであれば、非 ASCII 文字も識別子に使うべきではありません。

脚注

[1]

実のところ、オブジェクトへの参照渡し (call by object reference) という言ったほうがより正確です。というのは、変更可能なオブジェクトが渡されると、呼び出された側の関数がオブジェクトに行った変更 (例えばリストに挿入された要素) はすべて、関数の呼び出し側にも反映されるからです。

5. データ構造

この章では、すでに学んだことについてより詳しく説明するとともに、いくつか新しいことを追加します。

5.1. リスト型についてもう少し

リストデータ型には、他にもいくつかメソッドがあります。リストオブジェクトのすべてのメソッドを以下に示します:

list.append(x)

リストの末尾に要素を一つ追加します。a[len(a):] = [x] と等価です。

list.extend(iterable)

イテラブルのすべての要素を対象のリストに追加し、リストを拡張します。a[len(a):] = iterable と等価です。

list.insert(i, x)

指定した位置に要素を挿入します。第 1 引数は、リストのインデクスで、そのインデクスを持つ要素の直前に挿入が行われます。従って、 a.insert(0, x) はリストの先頭に挿入を行います。また a.insert(len(a), x) は a.append(x) と等価です。

list.remove(x)

リスト中で x と等しい値を持つ最初の要素を削除します。該当する要素がなければ ValueError が送出されます。

list.pop([i])

指定された位置の要素をリストから取り除き、それを返します。インデックスが指定されていない場合、 a.pop() はリスト末尾の要素を取り除いて返します。リストが空であるか、インデックスがリストの範囲外の場合は、IndexError を送出します。

list.clear()

リスト中の全ての要素を削除します。del a[:] と等価です。

list.index(x[, start[, end]])

リスト中で x と等しい値を持つ最初の要素の位置をゼロから始まる添字で返します。 該当する要素がなければ ValueError が送出されます。

任意の引数である start と end はスライス記法として解釈され、リストの探索範囲を指定できます。返される添字は、start 引数からの相対位置ではなく、リスト全体の先頭からの位置になります。

list.count(x)

リストでの x の出現回数を返します。

list.sort(*, key=None, reverse=False)

リストの項目を、インプレース演算 (in place、元のデータを演算結果で置き換えるやりかた) でソートします。引数はソート方法のカスタマイズに使えます。 sorted() の説明を参照してください。

list.reverse()

リストの要素を、インプレース演算で逆順にします。

list.copy()

リストの浅い (shallow) コピーを返します。a[:] と等価です。

以下にリストのメソッドをほぼ全て使った例を示します:

>>> fruits = ['orange', 'apple', 'pear', 'banana', 'kiwi', 'apple', 'banana']
>>> fruits.count('apple')
2
>>> fruits.count('tangerine')
0
>>> fruits.index('banana')
3
>>> fruits.index('banana', 4)  # Find next banana starting at position 4
6
>>> fruits.reverse()
>>> fruits
['banana', 'apple', 'kiwi', 'banana', 'pear', 'apple', 'orange']
>>> fruits.append('grape')
>>> fruits
['banana', 'apple', 'kiwi', 'banana', 'pear', 'apple', 'orange', 'grape']
>>> fruits.sort()
>>> fruits
['apple', 'apple', 'banana', 'banana', 'grape', 'kiwi', 'orange', 'pear']
>>> fruits.pop()
'pear'

insert, remove, sort などのリストを操作するメソッドの戻り値が表示されていないことに気が付いたかもしれません。これらのメソッドは None を返しています。[1] これは Python の変更可能なデータ構造全てについての設計上の原則となっています。

Another thing you might notice is that not all data can be sorted or compared. For instance, [None, 'hello', 10] doesn't sort because integers can't be compared to strings and None can't be compared to other types. Also, there are some types that don't have a defined ordering relation. For example, 3+4j < 5+7j isn't a valid comparison.

5.1.1. リストをスタックとして使う

リスト型のメソッドのおかげで、簡単にリストをスタックとして使えます。スタックでは、最後に追加された要素が最初に取り出されます ("last-in, first-out")。スタックの一番上に要素を追加するには append() を使います。スタックの一番上から要素を取り出すには pop() をインデックスを指定せずに使います。例えば以下のようにします:

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

5.1.2. リストをキューとして使う

リストをキュー (queue) として使うことも可能です。この場合、最初に追加した要素を最初に取り出します ("first-in, first-out")。しかし、リストでは効率的にこの目的を達成することが出来ません。追加（append）や取り出し（pop）をリストの末尾に対して行うと速いのですが、挿入（insert）や取り出し（pop）をリストの先頭に対して行うと遅くなってしまいます（他の要素をひとつずつずらす必要があるからです）。

キューの実装には、 collections.deque を使うと良いでしょう。このクラスは良く設計されていて、高速な追加（append）と取り出し（pop）を両端に対して実現しています。例えば以下のようにします:

>>> from collections import deque
>>> queue = deque(["Eric", "John", "Michael"])
>>> queue.append("Terry")           # Terry arrives
>>> queue.append("Graham")          # Graham arrives
>>> queue.popleft()                 # The first to arrive now leaves
'Eric'
>>> queue.popleft()                 # The second to arrive now leaves
'John'
>>> queue                           # Remaining queue in order of arrival
deque(['Michael', 'Terry', 'Graham'])

5.1.3. リストの内包表記

リスト内包表記はリストを生成する簡潔な手段を提供しています。主な利用場面は、あるシーケンスや iterable (イテレート可能オブジェクト) のそれぞれの要素に対してある操作を行った結果を要素にしたリストを作ったり、ある条件を満たす要素だけからなる部分シーケンスを作成することです。

例えば、次のような平方のリストを作りたいとします:

>>> squares = []
>>> for x in range(10):
...     squares.append(x**2)
...
>>> squares
[0, 1, 4, 9, 16, 25, 36, 49, 64, 81]

これはループが終了した後にも存在する x という名前の変数を作る (または上書きする) ことに注意してください。以下のようにして平方のリストをいかなる副作用もなく計算することができます:

squares = list(map(lambda x: x**2, range(10)))

もしくは、以下でも同じです:

squares = [x**2 for x in range(10)]

これはより簡潔で読みやすいです。

リスト内包表記は、括弧の中の 式、 for 句、そして0個以上の for か if 句で構成されます。リスト内包表記の実行結果は、 for と if 句のコンテキスト中で式を評価した結果からなる新しいリストです。例えば、次のリスト内包表記は2つのリストの要素から、違うもの同士をペアにします。

>>> [(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)]

これは次のコードと等価です:

>>> 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)]

for と if 文が両方のコードで同じ順序になっていることに注目してください。

式がタプルの場合 (例: 上の例で式が (x, y) の場合) は、タプルに円括弧が必要です。

>>> vec = [-4, -2, 0, 2, 4]
>>> # create a new list with the values doubled
>>> [x*2 for x in vec]
[-8, -4, 0, 4, 8]
>>> # filter the list to exclude negative numbers
>>> [x for x in vec if x >= 0]
[0, 2, 4]
>>> # apply a function to all the elements
>>> [abs(x) for x in vec]
[4, 2, 0, 2, 4]
>>> # call a method on each element
>>> freshfruit = ['  banana', '  loganberry ', 'passion fruit  ']
>>> [weapon.strip() for weapon in freshfruit]
['banana', 'loganberry', 'passion fruit']
>>> # create a list of 2-tuples like (number, square)
>>> [(x, x**2) for x in range(6)]
[(0, 0), (1, 1), (2, 4), (3, 9), (4, 16), (5, 25)]
>>> # the tuple must be parenthesized, otherwise an error is raised
>>> [x, x**2 for x in range(6)]
  File "<stdin>", line 1
    [x, x**2 for x in range(6)]
     ^^^^^^^
SyntaxError: did you forget parentheses around the comprehension target?
>>> # flatten a list using a listcomp with two 'for'
>>> vec = [[1,2,3], [4,5,6], [7,8,9]]
>>> [num for elem in vec for num in elem]
[1, 2, 3, 4, 5, 6, 7, 8, 9]

リスト内包表記の式には、複雑な式や関数呼び出しのネストができます:

>>> from math import pi
>>> [str(round(pi, i)) for i in range(1, 6)]
['3.1', '3.14', '3.142', '3.1416', '3.14159']

5.1.4. ネストしたリストの内包表記

リスト内包表記中の最初の式は任意の式なので、そこに他のリスト内包表記を書くこともできます。

次の、長さ4のリスト3つからなる、3x4 の matrix について考えます:

>>> matrix = [
...     [1, 2, 3, 4],
...     [5, 6, 7, 8],
...     [9, 10, 11, 12],
... ]

次のリスト内包表記は、matrix の行と列を入れ替えます:

>>> [[row[i] for row in matrix] for i in range(4)]
[[1, 5, 9], [2, 6, 10], [3, 7, 11], [4, 8, 12]]

前の節で見たように、内側のリスト内包表記は、続く for のコンテキストの中で評価されます。そのため、この例は次のコードと等価です:

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

これをもう一度変換すると、次のコードと等価になります:

>>> transposed = []
>>> for i in range(4):
...     # the following 3 lines implement the nested listcomp
...     transposed_row = []
...     for row in matrix:
...         transposed_row.append(row[i])
...     transposed.append(transposed_row)
...
>>> transposed
[[1, 5, 9], [2, 6, 10], [3, 7, 11], [4, 8, 12]]

実際には複雑な流れの式よりも組み込み関数を使う方が良いです。この場合 zip() 関数が良い仕事をしてくれるでしょう:

>>> list(zip(*matrix))
[(1, 5, 9), (2, 6, 10), (3, 7, 11), (4, 8, 12)]

この行にあるアスタリスクの詳細については 引数リストのアンパック を参照してください。

5.2. del 文

リストから要素を削除する際、値を指定する代わりにインデックスを指定する方法があります。それが del 文です。これは pop() メソッドと違い、値を返しません。 del 文はリストからスライスを除去したり、リスト全体を削除することもできます(以前はスライスに空のリストを代入して行っていました)。例えば以下のようにします:

>>> 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
[]

del は変数全体の削除にも使えます:

>>> del a

この文の後で名前 a を参照すると、(別の値を a に代入するまで) エラーになります。 del の別の用途についてはまた後で取り上げます。

5.3. タプルとシーケンス

リストや文字列には、インデクスやスライスを使った演算のように、数多くの共通の性質があることを見てきました。これらは シーケンス (sequence) データ型 (シーケンス型 --- list, tuple, range を参照) の二つの例です。 Python はまだ進歩の過程にある言語なので、他のシーケンスデータ型が追加されるかもしれません。標準のシーケンス型はもう一つあります: タプル (tuple) 型です。

タプルはコンマで区切られたいくつかの値からなります。例えば以下のように書きます:

>>> t = 12345, 54321, 'hello!'
>>> t[0]
12345
>>> t
(12345, 54321, 'hello!')
>>> # Tuples may be nested:
... u = t, (1, 2, 3, 4, 5)
>>> u
((12345, 54321, 'hello!'), (1, 2, 3, 4, 5))
>>> # Tuples are immutable:
... t[0] = 88888
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: 'tuple' object does not support item assignment
>>> # but they can contain mutable objects:
... v = ([1, 2, 3], [3, 2, 1])
>>> v
([1, 2, 3], [3, 2, 1])

ご覧のとおり、タプルの表示には常に丸括弧がついていて、タプルのネストが正しく解釈されるようになっています。タプルを書くときは必ずしも丸括弧で囲まなくてもいいですが、(タプルが大きな式の一部だった場合は) 丸括弧が必要な場合もあります。タプルの要素を代入することはできません。しかし、タプルにリストのような変更可能型を含めることはできます。

タプルはリストと似ていますが、たいてい異なる場面と異なる目的で利用されます。タプルは 不変 で、複数の型の要素からなることもあり、要素はアンパック(この節の後半に出てきます)操作やインデックス (あるいは namedtuples の場合は属性)でアクセスすることが多いです。一方、リストは 可変 で、要素はたいてい同じ型のオブジェクトであり、たいていイテレートによってアクセスします。

問題は 0 個または 1 個の項目からなるタプルの構築です。これらの操作を行うため、構文には特別な細工がされています。空のタプルは空の丸括弧ペアで構築できます。一つの要素を持つタプルは、値の後ろにコンマを続ける (単一の値を丸括弧で囲むだけでは不十分です) ことで構築できます。美しくはないけれども、効果的です。例えば以下のようにします:

>>> empty = ()
>>> singleton = 'hello',    # <-- note trailing comma
>>> len(empty)
0
>>> len(singleton)
1
>>> singleton
('hello',)

文 t = 12345, 54321, 'hello!' は タプルのパック (tuple packing) の例です。値 12345, 54321, 'hello!' が一つのタプルにパックされます。逆の演算も可能です:

>>> x, y, z = t

この操作は、シーケンスのアンパック (sequence unpacking) とでも呼ぶべきもので、右辺には全てのシーケンス型を使うことができます。シーケンスのアンパックでは、等号の左辺に列挙されている変数が、右辺のシーケンスの長さと同じ数だけあることが要求されます。複数同時の代入が実はタプルのパックとシーケンスのアンパックを組み合わせたものに過ぎないことに注意してください。

5.4. 集合型

Python には、 集合 (set) を扱うためのデータ型もあります。集合とは、重複する要素をもたない、順序づけられていない要素の集まりです。 Set オブジェクトは、和 (union)、積 (intersection)、差 (difference)、対称差 (symmetric difference)といった数学的な演算もサポートしています。

中括弧、または set() 関数は set を生成するために使用することができます。注: 空集合を作成するためには set() を使用しなければなりません ({} ではなく)。後者は空の辞書を作成します。辞書は次のセクションで議論するデータ構造です。

簡単なデモンストレーションを示します:

>>> basket = {'apple', 'orange', 'apple', 'pear', 'orange', 'banana'}
>>> print(basket)                      # show that duplicates have been removed
{'orange', 'banana', 'pear', 'apple'}
>>> 'orange' in basket                 # fast membership testing
True
>>> 'crabgrass' in basket
False

>>> # Demonstrate set operations on unique letters from two words
...
>>> a = set('abracadabra')
>>> b = set('alacazam')
>>> a                                  # unique letters in a
{'a', 'r', 'b', 'c', 'd'}
>>> a - b                              # letters in a but not in b
{'r', 'd', 'b'}
>>> a | b                              # letters in a or b or both
{'a', 'c', 'r', 'd', 'b', 'm', 'z', 'l'}
>>> a & b                              # letters in both a and b
{'a', 'c'}
>>> a ^ b                              # letters in a or b but not both
{'r', 'd', 'b', 'm', 'z', 'l'}

リスト内包 と同様に、 set 内包もサポートされています:

>>> a = {x for x in 'abracadabra' if x not in 'abc'}
>>> a
{'r', 'd'}

5.5. 辞書型 (dictionary)

もう一つ、有用な型が Python に組み込まれています。それは 辞書 (dictionary) (マッピング型 --- dict を参照)です。辞書は他の言語にも "連想記憶 (associated memory)" や "連想配列 (associative array)" という名前で存在することがあります。ある範囲の数でインデックス化されているシーケンスと異なり、辞書は キー (key) でインデックス化されています。このキーは何らかの変更不能な型になります。文字列、数値は常にキーにすることができます。タプルは、文字列、数値、その他のタプルのみを含む場合はキーにすることができます。直接、あるいは間接的に変更可能なオブジェクトを含むタプルはキーにできません。リストをキーとして使うことはできません。これは、リストにスライスやインデックス指定の代入を行ったり、 append() や extend() のようなメソッドを使うと、インプレースで変更することができるためです。

辞書は キー(key): 値(value) のペアの集合であり、キーが (辞書の中で)一意でなければならない、と考えるとよいでしょう。波括弧 (brace) のペア: {} は空の辞書を生成します。カンマで区切られた key: value のペアを波括弧ペアの間に入れると、辞書の初期値となる key: value が追加されます; この表現方法は出力時に辞書が書き出されるのと同じ方法です。

辞書での主な操作は、ある値を何らかのキーを付けて記憶することと、キーを指定して値を取り出すことです。 del で key: value のペアを削除することもできます。すでに使われているキーを使って値を記憶すると、以前そのキーに関連づけられていた値は忘れ去られてしまいます。存在しないキーを使って値を取り出そうとするとエラーになります。

辞書オブジェクトに対し list(d) を実行すると、辞書で使われている全てのキーからなるリストをキーが挿入された順番で返します (ソートされたリストが欲しい場合は、代わりに sorted(d) を使ってください)。ある単一のキーが辞書にあるかどうか調べるには、 in キーワードを使います。

以下に、辞書を使った簡単な例を示します:

>>> tel = {'jack': 4098, 'sape': 4139}
>>> tel['guido'] = 4127
>>> tel
{'jack': 4098, 'sape': 4139, 'guido': 4127}
>>> tel['jack']
4098
>>> del tel['sape']
>>> tel['irv'] = 4127
>>> tel
{'jack': 4098, 'guido': 4127, 'irv': 4127}
>>> list(tel)
['jack', 'guido', 'irv']
>>> sorted(tel)
['guido', 'irv', 'jack']
>>> 'guido' in tel
True
>>> 'jack' not in tel
False

dict() コンストラクタは、キーと値のペアのタプルを含むリストから辞書を生成します:

>>> dict([('sape', 4139), ('guido', 4127), ('jack', 4098)])
{'sape': 4139, 'guido': 4127, 'jack': 4098}

さらに、辞書内包表現を使って、任意のキーと値のペアから辞書を作れます:

>>> {x: x**2 for x in (2, 4, 6)}
{2: 4, 4: 16, 6: 36}

キーが単純な文字列の場合、キーワード引数を使って定義する方が単純な場合もあります:

>>> dict(sape=4139, guido=4127, jack=4098)
{'sape': 4139, 'guido': 4127, 'jack': 4098}

5.6. ループのテクニック

辞書に対してループを行う際、 items() メソッドを使うと、キーとそれに対応する値を同時に取り出せます。

>>> knights = {'gallahad': 'the pure', 'robin': 'the brave'}
>>> for k, v in knights.items():
...     print(k, v)
...
gallahad the pure
robin the brave

シーケンスにわたるループを行う際、 enumerate() 関数を使うと、要素のインデックスと要素を同時に取り出すことができます。

>>> for i, v in enumerate(['tic', 'tac', 'toe']):
...     print(i, v)
...
0 tic
1 tac
2 toe

二つまたはそれ以上のシーケンス型を同時にループするために、関数 zip() を使って各要素をひと組みにすることができます。

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

シーケンスを逆方向に渡ってループするには、まずシーケンスの範囲を順方向に指定し、次いで関数 reversed() を呼び出します。

>>> for i in reversed(range(1, 10, 2)):
...     print(i)
...
9
7
5
3
1

シーケンスをソートされた順序でループするには、 sorted() 関数を使います。この関数は元の配列を変更せず、ソート済みの新たな配列を返します。

>>> basket = ['apple', 'orange', 'apple', 'pear', 'orange', 'banana']
>>> for i in sorted(basket):
...     print(i)
...
apple
apple
banana
orange
orange
pear

シーケンスに set() を使うと、重複要素が除去されます。シーケンスに set() を使った上で、 sorted() を使うという組み合わせ方は、順番が整列されているシーケンスで、同一要素に 1 度のみループでアクセスする慣用的な方法です。

>>> basket = ['apple', 'orange', 'apple', 'pear', 'orange', 'banana']
>>> for f in sorted(set(basket)):
...     print(f)
...
apple
banana
orange
pear

ときどきループ内でリストを変更したい誘惑に駆られるでしょうが、代わりに新しいリストを作ってしまうほうがより簡単で安全なことが、ままあります

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

5.7. 条件についてもう少し

while や if 文で使った条件 (condition) には、値の比較だけでなく、他の演算子も使うことができます。

比較演算子 in および not in は、ある値があるコンテナーの中に存在するか (または存在しないか) どうかを確認するメンバーシップテストです。演算子 is および is not は、二つのオブジェクトが実際に同じオブジェクトであるかどうかを調べます。全ての比較演算子は同じ優先順位を持っており、ともに数値演算子よりも低い優先順位となります。

比較は連結させることができます。例えば、 a < b == c は、 a が b より小さく、かつ b と c が等しいかどうかをテストします。

ブール演算子 and や or で比較演算を組み合わせることができます。そして、比較演算 (あるいは何らかのブール式) の結果の否定は not でとれます。これらの演算子は全て、比較演算子よりも低い優先順位になっています。 A and not B or C と (A and (not B)) or C が等価になるように、ブール演算子の中で、 not の優先順位が最も高く、 or が最も低くなっています。もちろん、丸括弧を使えば望みの組み合わせを表現できます。

ブール演算子 and と or は、いわゆる 短絡 (short-circuit) 演算子です。これらの演算子の引数は左から右へと順に評価され、結果が確定した時点で評価を止めます。例えば、 A と C は真で B が偽のとき、 A and B and C は式 C を評価しません。一般に、短絡演算子の戻り値をブール値ではなくて一般的な値として用いると、値は最後に評価された引数になります。

比較や他のブール式の結果を変数に代入することもできます。例えば、

>>> string1, string2, string3 = '', 'Trondheim', 'Hammer Dance'
>>> non_null = string1 or string2 or string3
>>> non_null
'Trondheim'

Pythonでは、Cとは異なり、式の中での代入は セイウチ演算子 := を使用して明示的に行う必要があることに注意してください。これにより、 == が意図されていたところに = を入力してしまうという、Cプログラムで発生する一般的なクラスの問題を回避できます。

5.8. シーケンスとその他の型の比較

概して、シーケンスオブジェクトは、同じシーケンス型の他のオブジェクトと比較できます。比較には 辞書的な (lexicographical) 順序が用いられます。まず、最初の二つの要素を比較し、その値が等しくなければその時点で比較結果が決まります。等しければ次の二つの要素を比較し、以降シーケンスの要素が尽きるまで続けます。比較しようとする二つの要素がいずれも同じシーケンス型であれば、そのシーケンス間での辞書比較を再帰的に行います。二つのシーケンスの全ての要素の比較結果が等しくなれば、シーケンスは等しいとみなされます。片方のシーケンスがもう一方の先頭部分にあたる部分シーケンスならば、短い方のシーケンスが小さいシーケンスとみなされます。文字列に対する辞書的な順序づけには、個々の文字ごとに ASCII 順序を用います。以下に、同じ型のオブジェクトを持つシーケンス間での比較を行った例を示します:

(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)

違う型のオブジェクト同士を < や > で比較することも、それらのオブジェクトが適切な比較メソッドを提供しているのであれば許可されます。例えば、異なる数値型同士の比較では、その数値によって比較が行われます。例えば、 0 と 0.0 は等価です。一方、適切な比較順序がない場合は、インタープリターは TypeError 例外を発生させます。

脚注

[1]

他の言語では変更可能なオブジェクトを返して、d->insert("a")->remove("b")->sort(); のようなメソッドチェインを許している場合もあります。

6. モジュール

Python インタプリタを終了させ、再び起動すると、これまでに行ってきた定義 (関数や変数) は失われています。ですから、より長いプログラムを書きたいなら、テキストエディタを使ってインタプリタへの入力を用意しておき、手作業の代わりにファイルを入力に使って動作させるとよいでしょう。この作業を スクリプト (script) の作成と言います。プログラムが長くなるにつれ、メンテナンスを楽にするために、スクリプトをいくつかのファイルに分割したくなるかもしれません。また、いくつかのプログラムで書いてきた便利な関数について、その定義をコピーすることなく個々のプログラムで使いたいと思うかもしれません。

こういった要求をサポートするために、Python では定義をファイルに書いておき、スクリプトの中やインタプリタの対話インスタンス上で使う方法があります。このファイルを モジュール (module) と呼びます。モジュールにある定義は、他のモジュールや main モジュール (実行のトップレベルや電卓モードでアクセスできる変数の集まりを指します) に import (取り込み) することができます。

モジュールは Python の定義や文が入ったファイルです。ファイル名はモジュール名に接尾語 .py がついたものになります。モジュールの中では、(文字列の) モジュール名をグローバル変数 __name__ で取得できます。例えば、お気に入りのテキストエディタを使って、現在のディレクトリに以下の内容のファイル fibo.py を作成してみましょう:

# Fibonacci numbers module

def fib(n):    # write Fibonacci series up to n
    a, b = 0, 1
    while a < n:
        print(a, end=' ')
        a, b = b, a+b
    print()

def fib2(n):   # return Fibonacci series up to n
    result = []
    a, b = 0, 1
    while a < n:
        result.append(a)
        a, b = b, a+b
    return result

次に Python インタプリタに入り、モジュールを以下のコマンドで import しましょう:

>>> import fibo

この操作では、fibo で定義された関数の名前を直接現在の namespace (詳細は Python のスコープと名前空間 を参照してください)に追加することはありません。単にモジュール名 fibo だけを名前空間に追加します。関数にはモジュール名を使ってアクセスします:

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

関数を度々使うのなら、ローカルな名前に代入できます:

>>> fib = fibo.fib
>>> fib(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

6.1. モジュールについてもうすこし

モジュールには、関数定義に加えて実行文を入れることができます。これらの実行文はモジュールを初期化するためのものです。これらの実行文は、インポート文の中で 最初に モジュール名が見つかったときにだけ実行されます。[1] (ファイルがスクリプトとして実行される場合も実行されます。)

各々のモジュールは、自分のプライベートな名前空間を持っていて、モジュールで定義されている関数はこのテーブルをグローバルな名前空間として使います。したがって、モジュールの作者は、ユーザのグローバル変数と偶然的な衝突が起こる心配をせずに、グローバルな変数をモジュールで使うことができます。一方、自分が行っている操作をきちんと理解していれば、モジュール内の関数を参照するのと同じ表記法 modname.itemname で、モジュールのグローバル変数をいじることもできます。

モジュールは他のモジュールをインポートできます。 import 文はモジュール（さらに言えばスクリプトでも）の先頭に置きますが、これは慣習であって必須ではありません。インポートされたモジュール名は、モジュールのトップレベル（関数やクラスの外）に書いてあれば、モジュールのグローバルな名前空間に置かれます。

import 文には、あるモジュール内の名前を、import を実行しているモジュールの名前空間内に直接取り込むという変型があります。例えば:

>>> from fibo import fib, fib2
>>> fib(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

この操作は、import の対象となるモジュール名をローカルな名前空間内に取り入れることはありません (従って上の例では、 fibo は定義されません)。

モジュールで定義されている名前を全て import するという変型もあります:

>>> from fibo import *
>>> fib(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

この書き方ではアンダースコア (_) で始まるものを除いてすべての名前をインポートします。殆どの場面で、Python プログラマーはこの書き方を使いません。未知の名前がインタープリターに読み込まれ、定義済みの名前を上書きしてしまう可能性があるからです。

一般的には、モジュールやパッケージから * を import するというやり方には賛同できません。というのは、この操作を行うとしばしば可読性に乏しいコードになるからです。しかし、対話セッションでキータイプの量を減らすために使うのは構わないでしょう。

モジュール名の後に as が続いていた場合は、 as の後ろの名前を直接、インポートされたモジュールが束縛します。

>>> import fibo as fib
>>> fib.fib(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

これは実質的には import fibo と同じ方法でモジュールをインポートしていて、唯一の違いはインポートしたモジュールが fib という名前で取り扱えるようになっていることです。

このインポート方法は from が付いていても使え、同じ効果が得られます:

>>> from fibo import fib as fibonacci
>>> fibonacci(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

注釈

実行効率上の理由で、各モジュールはインタープリタの 1 セッションごとに 1 回だけ import されます。従って、モジュールを修正した場合には、インタープリタを再起動させなければなりません -- もしくは、その場で手直ししてテストしたいモジュールが 1 つだった場合には、例えば import importlib; importlib.reload(modulename) のように importlib.reload() を使ってください。

6.1.1. モジュールをスクリプトとして実行する

Python モジュールを

python fibo.py <arguments>

と実行すると、__name__ に __main__ が設定されている点を除いて import したときと同じようにモジュール内のコードが実行されます。つまりモジュールの末尾に:

if __name__ == "__main__":
    import sys
    fib(int(sys.argv[1]))

このコードを追加することで、このファイルが import できるモジュールであると同時にスクリプトとしても使えるようになります。なぜならモジュールが "main" ファイルとして起動されたときだけ、コマンドラインを解釈するコードが実行されるからです:

$ python fibo.py 50
0 1 1 2 3 5 8 13 21 34

モジュールが import された場合は、そのコードは実行されません:

>>> import fibo
>>>

この方法はモジュールに便利なユーザインターフェースを提供したり、テストのために (スクリプトをモジュールとして起動しテストスイートを実行して) 使われます。

6.1.2. モジュール検索パス

spam という名前のモジュールをインポートするとき、インタープリタはまずその名前の組み込みモジュールを探します。モジュール名の一覧は sys.builtin_module_names にあります。見つからなかった場合は、 spam.py という名前のファイルを sys.path にあるディレクトリのリストから探します。 sys.path は以下の場所に初期化されます:

入力されたスクリプトのあるディレクトリ (あるいはファイルが指定されなかったときはカレントディレクトリ)。

PYTHONPATH (ディレクトリ名のリスト。シェル変数の PATH と同じ構文)。

インストール方法に依存したデフォルト（慣例として site-packages ディレクトリーが含まれ、site モジュールによって処理される）。

詳細は The initialization of the sys.path module search path を参照してください。

注釈

シンボリックリンクをサポートするファイルシステム上では、入力されたスクリプトのあるディレクトリはシンボリックリンクをたどった後に計算されます。言い換えるとシンボリックリンクを含むディレクトリはモジュール検索パスに追加 されません。

初期化された後、 Python プログラムは sys.path を修正することができます。スクリプトファイルを含むディレクトリが検索パスの先頭、標準ライブラリパスよりも前に追加されます。なので、ライブラリのディレクトリにあるファイルよりも、そのディレクトリにある同じ名前のスクリプトが優先してインポートされます。これは、標準ライブラリを意図して置き換えているのでない限りは間違いのもとです。より詳しい情報は 標準モジュール を参照してください。

6.1.3. "コンパイル" された Python ファイル

モジュールの読み込みを高速化するため、Python はコンパイル済みの各モジュールを __pycache__ ディレクトリの module.version.pyc ファイルとしてキャッシュします。ここで version はコンパイルされたファイルのフォーマットを表すもので、一般的には Python のバージョン番号です。例えば、CPython のリリース 3.3 の、コンパイル済みの spam.py は __pycache__/spam.cpython-33.pyc としてキャッシュされるでしょう。この命名の慣習により、Python の異なる複数のリリースやバージョンのコンパイル済みモジュールが共存できます。

Python はソースの変更日時をコンパイル済みのものと比較し、コンパイル済みのものが最新でなくなり再コンパイルが必要になっていないかを確認します。これは完全に自動で処理されます。また、コンパイル済みモジュールはプラットフォーム非依存なため、アーキテクチャの異なるシステム間で同一のライブラリを共有することもできます。

Python は2つの場合にキャッシュのチェックを行いません。ひとつは、コマンドラインから直接モジュールが読み込まれた場合で、常に再コンパイルされ、結果を保存することはありません。2つめは、ソース・モジュールのない場合で、キャッシュの確認を行いません。ソースのない (コンパイル済みのもののみの) 配布をサポートするには、コンパイル済みモジュールはソース・ディレクトリになくてはならず、ソース・ディレクトリにソース・モジュールがあってはいけません。

エキスパート向けのTips:

コンパイル済みモジュールのサイズを小さくするために、Python コマンドに -O または -OO スイッチを使うことができます。-O スイッチは assert ステートメントを除去し、-OO スイッチは assert ステートメントと __doc__ 文字列を除去します。いくつかのプログラムはこれらの除去されるものに依存している可能性があるため、自分が何をしているかを理解しているときに限ってこれらのオプションを使うべきです。"最適化" されたモジュールは opt- タグを持ち、通常のコンパイル済みモジュールよりサイズが小さくなります。将来のリリースでは最適化の影響が変わる可能性があります。

.pyc ファイルや .pyo ファイルから読み出されたとしても、プログラムは .py ファイルから読み出されたときより何ら高速に動作するわけではありません。.pyc ファイルで高速化されるのは、読み込みにかかる時間だけです。

compileall モジュールを使ってディレクトリ内の全てのモジュールに対して .pyc ファイルを作ることができます。

この処理に関する詳細は、判定のフローチャートを含めて、PEP 3147 [https://peps.python.org/pep-3147/] に記載されています。

6.2. 標準モジュール

Python は標準モジュールライブラリを同梱していて、別の Python ライブラリリファレンスというドキュメントで解説しています。幾つかのモジュールは言語のコアにはアクセスしないものの、効率や、システムコールなどOSの機能を利用するために、インタープリター内部にビルトインされています。そういったモジュールセットはまたプラットフォームに依存した構成オプションです。例えば、 winreg モジュールは Windows システムでのみ提供されています。 1つ注目に値するモジュールとして、 sys モジュールは、全ての Python インタープリターにビルトインされています。 sys.ps1 と sys.ps2 という変数は一次プロンプトと二次プロンプトに表示する文字列を定義しています:

>>> import sys
>>> sys.ps1
'>>> '
>>> sys.ps2
'... '
>>> sys.ps1 = 'C> '
C> print('Yuck!')
Yuck!
C>

これらの二つの変数は、インタプリタが対話モードにあるときだけ定義されています。

変数 sys.path は文字列からなるリストで、インタプリタがモジュールを検索するときのパスを決定します。 sys.path は環境変数 PYTHONPATH から得たデフォルトパスに、 PYTHONPATH が設定されていなければ組み込みのデフォルト値に設定されます。標準的なリスト操作で変更することができます:

>>> import sys
>>> sys.path.append('/ufs/guido/lib/python')

6.3. dir() 関数

組込み関数 dir() は、あるモジュールがどんな名前を定義しているか調べるために使われます。 dir() はソートされた文字列のリストを返します:

>>> 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']

引数がなければ、 dir() は現在定義している名前を列挙します:

>>> a = [1, 2, 3, 4, 5]
>>> import fibo
>>> fib = fibo.fib
>>> dir()
['__builtins__', '__name__', 'a', 'fib', 'fibo', 'sys']

変数、モジュール、関数、その他の、すべての種類の名前をリストすることに注意してください。

dir() は、組込みの関数や変数の名前はリストしません。これらの名前からなるリストが必要なら、標準モジュール builtins で定義されています:

>>> 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']

6.4. パッケージ

パッケージ (package) は、Python のモジュール名前空間を "ドット付きモジュール名" を使って構造化する手段です。例えば、モジュール名 A.B は、 A というパッケージのサブモジュール B を表します。ちょうど、モジュールを利用すると、別々のモジュールの著者が互いのグローバル変数名について心配しなくても済むようになるのと同じように、ドット付きモジュール名を利用すると、 NumPy や Pillow のように複数モジュールからなるパッケージの著者が、互いのモジュール名について心配しなくても済むようになります。

音声ファイルや音声データを一様に扱うためのモジュールのコレクション ("パッケージ") を設計したいと仮定しましょう。 音声ファイルには多くの異なった形式がある (通常は拡張子、 例えば .wav, .aiff, .au などで認識されます) ので、増え続ける様々なファイル形式を相互変換するモジュールを、 作成したりメンテナンスしたりする必要があるかもしれません。 また、 音声データに対して実行したい様々な独自の操作 (ミキシング、 エコーの追加、 イコライザ関数の適用、 人工的なステレオ効果の作成など) があるかもしれません。 そうなると、 こうした操作を実行するモジュールを果てしなく書くことになるでしょう。 以下に (階層的なファイルシステムで表現した) パッケージの構造案を示します:

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

パッケージを import する際、 Python は sys.path 上のディレクトリを検索して、トップレベルのパッケージの入ったサブディレクトリを探します。

ファイルを含むディレクトリをパッケージとしてPython に扱わせるには、ファイル __init__.py が必要です(より高度な機能 namespace package を使う場合を除く)。これにより、 string のようなよくある名前のディレクトリにより、モジュール検索パスの後の方で見つかる正しいモジュールが意図せず隠蔽されてしまうのを防ぐためです。最も簡単なケースでは __init__.py はただの空ファイルで構いませんが、 __init__.py ではパッケージのための初期化コードを実行したり、後述の __all__ 変数を設定してもかまいません。

パッケージのユーザは、個々のモジュールをパッケージから import することができます。例えば:

import sound.effects.echo

この操作はサブモジュール sound.effects.echo をロードします。このモジュールは、以下のように完全な名前で参照しなければなりません。

sound.effects.echo.echofilter(input, output, delay=0.7, atten=4)

サブモジュールを import するもう一つの方法を示します:

from sound.effects import echo

これもサブモジュール echo をロードし、パッケージ名なしで利用可能にします。なのでこう使えます:

echo.echofilter(input, output, delay=0.7, atten=4)

さらにもう一つのバリエーションとして、必要な関数や変数を直接 import する方法があります:

from sound.effects.echo import echofilter

また、これもサブモジュール echo をロードしますが、 echofilter() 関数を直接利用可能にします:

echofilter(input, output, delay=0.7, atten=4)

from package import item を使う場合、 item はパッケージ package のサブモジュール (またはサブパッケージ) でもかまいませんし、関数やクラス、変数のような、 package で定義されている別の名前でもかまわないことに注意してください。 import 文はまず、 item がパッケージ内で定義されているかどうか調べます。定義されていなければ、 item はモジュール名であると仮定して、モジュールをロードしようと試みます。もしモジュールが見つからなければ、 ImportError が送出されます。

反対に、 import item.subitem.subsubitem のような構文を使った場合、最後の subsubitem を除く各要素はパッケージでなければなりません。最後の要素はモジュールかパッケージにできますが、一つ前の要素で定義されているクラスや関数や変数にはできません。

6.4.1. パッケージから * を import する

それでは、ユーザが from sound.effects import * と書いたら、どうなるのでしょうか？理想的には、何らかの方法でファイルシステムが調べられ、そのパッケージにどんなサブモジュールがあるかを調べ上げ、全てを import する、という処理を望むことでしょう。これには長い時間がかかってしまうこともありますし、あるサブモジュールを import することで、そのモジュールが明示的に import されたときのみ発生して欲しい副作用が起きてしまうかもしれません。

唯一の解決策は、パッケージの作者にパッケージの索引を明示的に提供させる というものです。 import 文の使う規約は、パッケージの __init__.py コードに __all__ という名前のリストが定義されていれば、 from package import * が現れたときに import すべきモジュール名のリストとして使う、というものです。 パッケージの新バージョンがリリースされるときにリストを最新の状態に更新するのは パッケージの作者の責任となります。 自分のパッケージから * を import するという使い方が考えられないならば、 パッケージの作者はこの使い方をサポートしないことにしてもかまいません。 例えば、ファイル sound/effects/__init__.py には、次のような コードを入れてもよいかもしれません:

__all__ = ["echo", "surround", "reverse"]

これが意味するのは、 from sound.effects import * とすると、名前の挙がった 3つのサブモジュールが sound.effects パッケージから import される、ということです。

注意点として、サブモジュールはローカルな名前で隠されることがあります。例として、 reverse 関数を sound/effects/__init__.py に足すと、 from sound.effects import * では echo と surround の２サブモジュールだけ import されます。 reverse サブモジュールは import されません 。それはローカルに定義された reverse 関数で隠されたので:

__all__ = [
    "echo",      # refers to the 'echo.py' file
    "surround",  # refers to the 'surround.py' file
    "reverse",   # !!! refers to the 'reverse' function now !!!
]

def reverse(msg: str):  # <-- this name shadows the 'reverse.py' submodule
    return msg[::-1]    #     in the case of a 'from sound.effects import *'

もしも __all__ が定義されていなければ、実行文 from sound.effects import * は、パッケージ sound.effects の全てのサブモジュールを現在の名前空間の中へ import しません 。この文は単に(場合によっては初期化コード __init__.py を実行して) パッケージ sound.effects が import されたということを確認し、そのパッケージで定義されている名前を全て import するだけです。 import される名前には、 __init__.py で定義された名前 (と、明示的にロードされたサブモジュール) が含まれます。パッケージのサブモジュールで、以前の import 文で明示的にロードされたものも含みます。以下のコードを考えてください:

import sound.effects.echo
import sound.effects.surround
from sound.effects import *

上の例では、 echo と surround モジュールが現在の名前空間に import されます。これらのモジュールは from...import 文が実行された際に sound.effects 内で定義されているからです。 (この機構は __all__ が定義されているときにも働きます。)

特定のモジュールでは import * を使ったときに、特定のパターンに従った名前のみを公開 (export) するように設計されてはいますが、それでもやはり製品のコードでは良いことではないと考えます。

from package import specific_submodule を使っても何も問題はないことに留意してください！実際この表記法は、import を行うモジュールが他のパッケージと同じ名前を持つサブモジュールを使わなければならない場合を除いて推奨される方式です。

6.4.2. パッケージ内参照

パッケージが (前述の例の sound パッケージのように) サブパッケージの集まりに構造化されている場合、絶対 import を使って兄弟関係にあるパッケージを参照できます。例えば、モジュール sound.filters.vocoder で sound.effects パッケージの echo モジュールが必要な場合、 from sound.effects import echo が使えます。

また、明示的な相対importを from module import name の形式の import 文で利用できます。この明示的な相対 import では、先頭のドットで現在および親パッケージを指定します。 surround モジュールの例では、以下のように記述できます:

from . import echo
from .. import formats
from ..filters import equalizer

相対 import は現在のモジュール名をベースにすることに注意してください。メインモジュールの名前は常に "__main__" なので、Python アプリケーションのメインモジュールとして利用されることを意図しているモジュールでは絶対 import を利用するべきです。

6.4.3. 複数ディレクトリ中のパッケージ

パッケージはもう一つ特別な属性として __path__ をサポートしています。この属性は、パッケージの __init__.py 中のコードが実行されるよりも前に、 __init__.py の収められているディレクトリ名の入ったリストになるよう初期化されます。この変数は変更することができます。変更を加えると、以降そのパッケージに入っているモジュールやサブパッケージの検索に影響します。

この機能はほとんど必要にはならないのですが、パッケージ内存在するモジュール群を拡張するために使うことができます。

脚注

[1]

実際には、関数定義も '実行' される '文' です。モジュールレベルの関数定義を実行すると、関数名はモジュールのグローバルな名前空間に追加されます。

7. 入力と出力

プログラムの出力方法にはいくつかの種類があります。データを人間が読める形で出力することもあれば、将来使うためにファイルに書くこともあります。この章では、こうした幾つかの出力の方法について話します。

7.1. 出力を見やすくフォーマットする

これまでに、値を出力する二つの方法: 式文 (expression statement) と print() 関数が出てきました。 (第三はファイルオブジェクトの write() メソッドを使う方法です。標準出力を表すファイルは sys.stdout で参照できます。詳細はライブラリリファレンスを参照してください。)

単に空白区切りで値を並べただけの出力よりも、フォーマットを制御したいと思うことはよくあることでしょう。出力をフォーマットする方法はいくつかあります。

フォーマット済み文字列リテラル を使うには、開き引用符や三重の開き引用符の前に f あるいは F を付けて文字列を始めます。この文字列の内側では、文字 { と文字 } の間に Python の式が書け、その式から変数やリテラル値が参照できます。

>>> year = 2016
>>> event = 'Referendum'
>>> f'Results of the {year} {event}'
'Results of the 2016 Referendum'

文字列の str.format() メソッドは、もう少し手間がかかります。ここでも { と } を使って変数に代入する場所の印を付けて、細かいフォーマットの指示を出せますが、フォーマットされる対象の情報を与える必要があります。

>>> yes_votes = 42_572_654
>>> no_votes = 43_132_495
>>> percentage = yes_votes / (yes_votes + no_votes)
>>> '{:-9} YES votes  {:2.2%}'.format(yes_votes, percentage)
' 42572654 YES votes  49.67%'

最後に、文字列のスライス操作や結合操作を使い、全ての文字列を自分で処理し、思い通りのレイアウトを作成できます。文字列型には、文字列の間隔を調整して指定されたカラム幅に揃えるのに便利な操作を行うメソッドがいくつかあります。

凝った出力である必要は無いけれど、デバッグ目的で変数をすばやく表示したいときは、 repr() 関数か str() 関数でどんな値も文字列に変換できます。

str() 関数は値の人間に読める表現を返すためのもので、 repr() 関数はインタープリタに読める (あるいは同値となる構文がない場合は必ず SyntaxError になるような) 表現を返すためのものです。人間が読むのに適した特定の表現を持たないオブジェクトにおいては、 str() は repr() と同じ値を返します。数値や、リストや辞書を始めとするデータ構造など、多くの値がどちらの関数に対しても同じ表現を返します。一方、文字列は、2つの異なる表現を持っています。

いくつかの例です:

>>> s = 'Hello, world.'
>>> str(s)
'Hello, world.'
>>> repr(s)
"'Hello, world.'"
>>> str(1/7)
'0.14285714285714285'
>>> x = 10 * 3.25
>>> y = 200 * 200
>>> s = 'The value of x is ' + repr(x) + ', and y is ' + repr(y) + '...'
>>> print(s)
The value of x is 32.5, and y is 40000...
>>> # The repr() of a string adds string quotes and backslashes:
... hello = 'hello, world\n'
>>> hellos = repr(hello)
>>> print(hellos)
'hello, world\n'
>>> # The argument to repr() may be any Python object:
... repr((x, y, ('spam', 'eggs')))
"(32.5, 40000, ('spam', 'eggs'))"

string モジュールの Template クラスも、文字列中の値を置換する別の方法を提供しています。 $x のようなプレースホルダーを使い、その箇所と辞書にある値を置き換えますが、使えるフォーマット方式はとても少ないです。

7.1.1. フォーマット済み文字列リテラル

フォーマット済み文字リテラル (短くして f-string とも呼びます) では、文字列の頭に f か F を付け、式を {expression} と書くことで、 Python の式の値を文字列の中に入れ込めます。

オプションのフォーマット指定子を式の後ろに付けられます。このフォーマット指定子によって値のフォーマット方式を制御できます。次の例では、円周率πを小数点以下3桁に丸めてフォーマットしています:

>>> import math
>>> print(f'The value of pi is approximately {math.pi:.3f}.')
The value of pi is approximately 3.142.

':' の後ろに整数をつけると、そのフィールドの最小の文字幅を指定できます。この機能は縦を揃えるのに便利です。

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

他の修飾子は、フォーマットする前に値を変換するのに使えます。 '!a' は ascii() を、 '!s' は str() を、 '!r' は repr() を適用します:

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

= 指定子を使用すると式を展開して、式、イコール記、式を評価した文字列表現、の形式で表示されます。

>>> bugs = 'roaches'
>>> count = 13
>>> area = 'living room'
>>> print(f'Debugging {bugs=} {count=} {area=}')
Debugging bugs='roaches' count=13 area='living room'

= 指定子の詳細については self-documenting expressions を参照してください。 フォーマットについての仕様は 書式指定ミニ言語仕様 のリファレンスガイドを参照してください。

7.1.2. 文字列の format() メソッド

str.format() メソッドの基本的な使い方は次のようなものです:

>>> print('We are the {} who say "{}!"'.format('knights', 'Ni'))
We are the knights who say "Ni!"

括弧とその中の文字(これをフォーマットフィールドと呼びます)は、 str.format() メソッドに渡されたオブジェクトに置換されます。括弧の中の数字は str.format() メソッドに渡されたオブジェクトの位置を表すのに使えます。

>>> print('{0} and {1}'.format('spam', 'eggs'))
spam and eggs
>>> print('{1} and {0}'.format('spam', 'eggs'))
eggs and spam

str.format() メソッドにキーワード引数が渡された場合、その値はキーワード引数の名前によって参照されます。

>>> print('This {food} is {adjective}.'.format(
...       food='spam', adjective='absolutely horrible'))
This spam is absolutely horrible.

順序引数とキーワード引数を組み合わせて使うこともできます:

>>> print('The story of {0}, {1}, and {other}.'.format('Bill', 'Manfred',
...                                                    other='Georg'))
The story of Bill, Manfred, and Georg.

もしも長い書式文字列があり、それを分割したくない場合には、変数を引数の位置ではなく変数の名前で参照できるとよいでしょう。これは、辞書を引数に渡して、角括弧 '[]' を使って辞書のキーを参照することで可能です。

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

辞書 table を ** 記法を使ってキーワード引数として渡す方法もあります。

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

全てのローカルな変数が入った辞書を返す組み込み関数 vars() と組み合わせると特に便利です。

例として、下のコード行は与えられた整数とその2乗と3乗がきちんと揃った列を生成します:

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

str.format() による文字列書式設定の完全な解説は、 書式指定文字列の文法 を参照してください。

7.1.3. 文字列の手作業でのフォーマット

次は 2 乗と 3 乗の値からなる同じ表を手作業でフォーマットしたものです:

>>> for x in range(1, 11):
...     print(repr(x).rjust(2), repr(x*x).rjust(3), end=' ')
...     # Note use of 'end' on previous line
...     print(repr(x*x*x).rjust(4))
...
 1   1    1
 2   4    8
 3   9   27
 4  16   64
 5  25  125
 6  36  216
 7  49  343
 8  64  512
 9  81  729
10 100 1000

(各カラムの間のスペース一個分は print() の動作で追加されていることに注意してください。 print() は常に引数間に空白を追加します。)

文字列オブジェクトの str.rjust() メソッドは、指定された幅のフィールド内に文字列が右寄せで入るように左側に空白を追加します。同様のメソッドとして、 str.ljust() と str.center() があります。これらのメソッドは何か出力を行うわけではなく、ただ新しい文字列を返します。入力文字列が長すぎる場合、文字列を切り詰めることはせず、値をそのまま返します。この仕様のためにカラムのレイアウトが滅茶苦茶になるかもしれませんが、嘘の値が代わりに書き出されるよりはましです。 (本当に切り詰めを行いたいのなら、全てのカラムに x.ljust(n)[:n] のようにスライス表記を加えることもできます。)

もう一つのメソッド、 str.zfill() は、数値文字列の左側をゼロ詰めします。このメソッドは正と負の符号を正しく扱います:

>>> '12'.zfill(5)
'00012'
>>> '-3.14'.zfill(7)
'-003.14'
>>> '3.14159265359'.zfill(5)
'3.14159265359'

7.1.4. 古い文字列書式設定方法

% 演算子 (剰余) は文字列のフォーマットでも使えます。 'string' % values という文字列が与えられた場合、string の中の % 部分はゼロあるいは values の余りの要素に置換えられます。この操作は文字列補間として知られています。例えば:

>>> import math
>>> print('The value of pi is approximately %5.3f.' % math.pi)
The value of pi is approximately 3.142.

より詳しい情報は printf 形式の文字列書式化 にあります。

7.2. ファイルを読み書きする

open() は file object を返します。大抵、 open(filename, mode, encoding=None) のように2つの位置引数と1つのキーワード引数を伴って呼び出されます。

>>> f = open('workfile', 'w', encoding="utf-8")

最初の引数はファイル名の入った文字列です。二つめの引数も文字列で、ファイルをどのように使うかを示す数個の文字が入っています。 mode は、ファイルが読み出し専用なら 'r' 、書き込み専用 (同名の既存のファイルがあれば消去されます) なら 'w' とします。 'a' はファイルを追記用に開きます。ファイルに書き込まれた内容は自動的にファイルの終端に追加されます。 'r+' はファイルを読み書き両用に開きます。 mode 引数は省略可能で、省略された場合には 'r' であると仮定します。

通常、ファイルはテキストモード (text mode) で開かれ、特定の エンコーディング でエンコードされたファイルに対して文字列を読み書きします。エンコーディング が指定されなければ、デフォルトはプラットフォーム依存です(open() を参照してください)。UTF-8は現在の事実上の標準のため、異なるエンコーディングを指定したい場合以外は encoding="utf-8" の指定がおすすめです。モードに 'b' をつけるとファイルを binary mode で開きます。バイナリーモードでのデータは bytes オブジェクトで読み書きします。ファイルをバイナリーモードで開くときは エンコーディング は指定できません。

テキストモードの読み取りでは、プラットフォーム固有の行末記号 (Unix では \n 、Windows では \r\n) をただの \n に変換するのがデフォルトの動作です。テキストモードの書き込みでは、 \n が出てくる箇所をプラットフォーム固有の行末記号に戻すのがデフォルトの動作です。この裏で行われるファイルデータの変換はテキストファイルには上手く働きますが、 JPEG ファイルや EXE ファイルのようなバイナリデータを破壊する恐れがあります。そのようなファイルを読み書きする場合には注意して、バイナリモードを使うようにしてください。

ファイルオブジェクトを扱うときに with キーワードを使うのは良い習慣です。その利点は、処理中に例外が発生しても必ず最後にファイルをちゃんと閉じることです。 with を使うと、同じことを try-finally ブロックを使って書くよりずっと簡潔に書けます:

>>> with open('workfile', encoding="utf-8") as f:
...     read_data = f.read()

>>> # We can check that the file has been automatically closed.
>>> f.closed
True

もし with キーワードを使用しない場合は、ファイルを閉じ、このファイルのために利用されたシステムのリソースを直ちに解放するために f.close() を呼び出してください。

警告

f.write() を with キーワードや f.close() を使わずに呼び出した場合、プログラムが正常に終了した場合でも、 f.write() の実引数がディスクに完全に 書き込まれないことがあります 。

with 文や f.close() の呼び出しによって閉じられた後にファイルオブジェクトを使おうとするとそこで処理が失敗します。:

>>> f.close()
>>> f.read()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: I/O operation on closed file.

7.2.1. ファイルオブジェクトのメソッド

この節の以降の例は、 f というファイルオブジェクトが既に生成されているものと仮定します。

ファイルの内容を読み出すには、 f.read(size) を呼び出します。このメソッドはある量のデータを読み出して、文字列 (テキストモードの場合) か bytes オブジェクト (バイナリーモードの場合) として返します。 size はオプションの数値引数です。 size が省略されたり負の数であった場合、ファイルの内容全てを読み出して返します。ただし、ファイルがマシンのメモリの二倍の大きさもある場合にはどうなるかわかりません。 size が負でない数ならば、最大で (テキストモードの場合) size 文字、(バイナリモードの場合) size バイトを読み出して返します。ファイルの終端にすでに達していた場合、 f.read() は空の文字列 ('') を返します。

>>> f.read()
'This is the entire file.\n'
>>> f.read()
''

f.readline() はファイルから 1 行だけを読み取ります。改行文字 (\n) は読み出された文字列の終端に残ります。改行が省略されるのは、ファイルが改行で終わっていない場合の最終行のみです。これは、戻り値があいまいでないようにするためです; f.readline() が空の文字列を返したら、ファイルの終端に達したことが分かります。一方、空行は '\n'、すなわち改行 1 文字だけからなる文字列で表現されます。

>>> f.readline()
'This is the first line of the file.\n'
>>> f.readline()
'Second line of the file\n'
>>> f.readline()
''

ファイルから複数行を読み取るには、ファイルオブジェクトに対してループを書く方法があります。この方法はメモリを効率的に使え、高速で、簡潔なコードになります:

>>> for line in f:
...     print(line, end='')
...
This is the first line of the file.
Second line of the file

ファイルのすべての行をリスト形式で読み取りたいなら、list(f) や f.readlines() を使うこともできます。

f.write(string) は、string の内容をファイルに書き込み、書き込まれた文字数を返します。

>>> f.write('This is a test\n')
15

オブジェクトの他の型は、書き込む前に変換しなければなりません -- 文字列 (テキストモード) と bytes オブジェクト (バイナリーモード) のいずれかです:

>>> value = ('the answer', 42)
>>> s = str(value)  # convert the tuple to string
>>> f.write(s)
18

f.tell() は、ファイルオブジェクトのファイル中における現在の位置を示す整数を返します。ファイル中の現在の位置は、バイナリモードではファイルの先頭からのバイト数で、テキストモードでは不明瞭な値で表されます。

ファイルオブジェクトの位置を変更するには、f.seek(offset, whence) を使います。ファイル位置は基準点 (reference point) にオフセット値 offset を足して計算されます。参照点は whence 引数で選びます。whence の値が 0 ならばファイルの 先頭から測り、1 ならば現在のファイル位置を使い、2 ならばファイルの終端を参照点として使います。whence は省略することができ、デフォルトの値は 0、すなわち参照点としてファイルの先頭を使います。

>>> f = open('workfile', 'rb+')
>>> f.write(b'0123456789abcdef')
16
>>> f.seek(5)      # Go to the 6th byte in the file
5
>>> f.read(1)
b'5'
>>> f.seek(-3, 2)  # Go to the 3rd byte before the end
13
>>> f.read(1)
b'd'

テキストファイル (mode 文字列に b を付けなかった場合) では、ファイルの先頭からの相対位置に対するシークだけが許可されています (例外として、seek(0, 2) でファイルの末尾へのシークは可能です)。また、唯一の有効な offset 値は f.tell() から返された値か、0 のいずれかです。それ以外の offset 値は未定義の振る舞いを引き起こします。

ファイルオブジェクトには、他にも isatty() や truncate() といった、あまり使われないメソッドがあります。ファイルオブジェクトについての完全なガイドは、ライブラリリファレンスを参照してください。

7.2.2. json による構造化されたデータの保存

文字列は簡単にファイルに読み書きできます。数値の場合には少し努力が必要です。というのも、 read() メソッドは文字列しか返さないため、 int() のような関数にその文字列を渡して、たとえば文字列 '123' のような文字列を、数値 123 に変換しなくてはならないからです。もっと複雑なデータ型、例えば入れ子になったリストや辞書の場合、手作業でのパースやシリアライズは困難になります。

ユーザが毎回コードを書いたりデバッグしたりして複雑なデータ型をファイルに保存するかわりに、Python では一般的なデータ交換形式である JSON (JavaScript Object Notation) [https://json.org] を使うことができます。この標準モジュール json は、Python のデータ 階層を取り、文字列表現に変換します。この処理は シリアライズ (serializing) と呼ばれます。文字列表現からデータを再構築することは、デシリアライズ (deserializing) と呼ばれます。シリアライズされてからデシリアライズされるまでの間に、オブジェクトの文字列表現はファイルやデータの形で保存したり、ネットワークを通じて離れたマシンに送ったりすることができます。

注釈

JSON 形式は現代的なアプリケーションでデータをやりとりする際によく使われます。多くのプログラマーが既に JSON に詳しいため、JSON はデータの相互交換をする場合の良い選択肢です。

オブジェクト x があり、その JSON 形式の文字列表現を見るには、単純な1行のコードを書くだけです:

>>> import json
>>> x = [1, 'simple', 'list']
>>> json.dumps(x)
'[1, "simple", "list"]'

dumps() に似た関数に、dump() があり、こちらは単純にオブジェクトを text file にシリアライズします。f が書き込み用に開かれた text file だとすると、次のように書くことができます:

json.dump(x, f)

逆にデシリアライズするには、f が読み込み用に開かれた binary file か text file だとすると、次のようになります:

x = json.load(f)

注釈

JSONファイルは必ずUTF-8でエンコードします。JSONファイルを text file として読み込み、書き込みで開くときには、 encoding="utf-8" を指定します。

このような単純なシリアライズをする手法は、リストや辞書を扱うことはできますが、任意のクラス・インスタンスを JSON にシリアライズするにはもう少し努力しなくてはなりません。json モジュールのリファレンスにこれについての解説があります。

参考

pickle - pickle モジュール

JSON とは対照的に、 pickle は任意の複雑な Python オブジェクトをシリアライズ可能なプロトコルです。しかし、Python に特有のプロトコルで、他の言語で記述されたアプリケーションと通信するのには使えません。さらに、デフォルトでは安全でなく、信頼できない送信元から送られてきた、スキルのある攻撃者によって生成された pickle データをデシリアライズすると、攻撃者により任意のコードが実行されてしまいます。

8. エラーと例外

これまでエラーメッセージについては簡単に触れるだけでしたが、チュートリアル中の例を自分で試していたら、実際にいくつかのエラーメッセージを見ていることでしょう。エラーには (少なくとも) 二つのはっきり異なる種類があります。それは 構文エラー (syntax error) と 例外 (exception) です。

8.1. 構文エラー

構文エラーは構文解析エラー (parsing error) としても知られており、Python を勉強している間に最もよく遭遇する問題の一つでしょう:

>>> while True print('Hello world')
  File "<stdin>", line 1
    while True print('Hello world')
               ^^^^^
SyntaxError: invalid syntax

パーサは違反の起きている行を表示し、小さな「矢印」を表示して、行中でエラーが検出されたトークンを示します。エラーは指し示された 前の トークンが存在しないために発生する可能性があります。上記の例では、エラーは関数 print() で検出されています。コロン (':') がその前に無いからです。入力がスクリプトから来ている場合は、どこを見ればよいか分かるようにファイル名と行番号が出力されます。

8.2. 例外

たとえ文や式が構文的に正しくても、実行しようとしたときにエラーが発生するかもしれません。実行中に検出されたエラーは 例外 (exception) と呼ばれ、常に致命的とは限りません。これから、Python プログラムで例外をどのように扱うかを学んでいきます。ほとんどの例外はプログラムで処理されず、以下に示されるようなメッセージになります:

>>> 10 * (1/0)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ZeroDivisionError: division by zero
>>> 4 + spam*3
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'spam' is not defined
>>> '2' + 2
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: can only concatenate str (not "int") to str

エラーメッセージの最終行は何が起こったかを示しています。例外は様々な型 (type) で起こり、その型がエラーメッセージの一部として出力されます。上の例での型は ZeroDivisionError, NameError, TypeError です。例外型として出力される文字列は、発生した例外の組み込み名です。これは全ての組み込み例外について成り立ちますが、ユーザ定義の例外では (成り立つようにするのは有意義な慣習ですが) 必ずしも成り立ちません。標準例外の名前は組み込みの識別子です (予約語ではありません)。

残りの行は例外の詳細で、その例外の型と何が起きたかに依存します。

エラーメッセージの先頭部分では、例外が発生した実行コンテキスト (context) を、スタックのトレースバック (stack traceback) の形式で示しています。一般には、この部分にはソースコード行をリストしたトレースバックが表示されます。しかし、標準入力から読み取られたコードは表示されません。

組み込み例外 には、組み込み例外とその意味がリストされています。

8.3. 例外を処理する

例外を選別して処理するようなプログラムを書くことができます。以下の例を見てください。この例では、有効な文字列が入力されるまでユーザに入力を促しますが、ユーザがプログラムに (Control-C か、またはオペレーティングシステムがサポートしている何らかのキーを使って) 割り込みをかけてプログラムを中断させることができるようにしています。ユーザが生成した割り込みは、 KeyboardInterrupt 例外が送出されることで通知されるということに注意してください。

>>> while True:
...     try:
...         x = int(input("Please enter a number: "))
...         break
...     except ValueError:
...         print("Oops!  That was no valid number.  Try again...")
...

try 文は下記のように動作します。

まず、 try 節 (try clause) (キーワード try と except の間の文) が実行されます。

何も例外が発生しなければ、 except 節 をスキップして try 文の実行を終えます。

try 節内の実行中に例外が発生すると、その節の残りは飛ばされます。次に、例外型が except キーワードの後に指定されている例外に一致する場合、except 節が実行された後、 try/except ブロックの後ろへ実行が継続されます。

もしも except 節 で指定された例外と一致しない例外が発生すると、その例外は try 文の外側に渡されます。例外に対するハンドラ (handler、処理部) がどこにもなければ、 処理されない例外 (unhandled exception) となり、エラーメッセージを出して実行を停止します。

一つの try 文には複数の except 節 が付けられ、別々の例外に対するハンドラを指定できます。多くとも一つのハンドラしか実行されません。ハンドラは対応する try 節 内で発生した例外だけを処理し、同じ try 節内の別の例外ハンドラで起きた例外は処理しません。 except 節 では丸括弧で囲ったタプルという形で複数の例外を指定できます。例えば次のようにします:

... except (RuntimeError, TypeError, NameError):
...     pass

except 節 内のクラスは、そのクラスや派生クラスのインスタンスである例外とマッチします（その逆はありません --- 派生クラスが書かれた except節 は、その基底クラスのインスタンスにはマッチしません）。例えば、次のコードは B, C, D の順に出力されます:

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")

except 節 が逆に並んでいた場合 (except B が最初にくる場合)、 B, B, B と出力されるはずだったことに注意してください --- 最初に一致した except 節 が駆動されるのです。

例外が発生するとき、例外は関連付けられた値を持つことができます。この値は例外の 引数 (arguments) とも呼ばれます。引数の有無および引数の型は、例外の型に依存します。

except節は例外名の後に変数を指定できます。その変数は例外インスタンスに紐付けられ、一般的には引数を保持する args 属性を持ちます。利便性のため、組み込み例外型には __str__() が定義されており、明示的に .args を参照せずとも すべての引数を表示できます。

>>> try:
...     raise Exception('spam', 'eggs')
... except Exception as inst:
...     print(type(inst))    # the exception type
...     print(inst.args)     # arguments stored in .args
...     print(inst)          # __str__ allows args to be printed directly,
...                          # but may be overridden in exception subclasses
...     x, y = inst.args     # unpack args
...     print('x =', x)
...     print('y =', y)
...
<class 'Exception'>
('spam', 'eggs')
('spam', 'eggs')
x = spam
y = eggs

例外の __str__() 出力は、処理されない例外のメッセージ末尾 ('詳細') として表示されます。

BaseException はすべての例外に共通する基底クラスです。そのサブクラスの一つである Exception は、致命的でない例外すべての基底クラスです。 Exception のサブクラスではない例外は、一般的にプログラムが終了することを示すために使われているため処理されません。例えば、sys.exit() によって送出される SystemExit や、ユーザーがプログラムを中断させたいときに送出される KeyboardInterrupt があります。

Exception はほぼすべての例外を捕捉するワイルドカードとして使えます。しかし良い例外処理の手法とは、処理対象の例外の型をできる限り詳細に書き、予期しない例外はそのまま伝わるようにすることです。

Exception に対する最も一般的な例外処理のパターンでは、例外を表示あるいはログ出力してから再度送出します(呼び出し側でも例外を処理できるようにします):

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

try ... except 文には、オプションで else 節 (else clause) を設けることができます。 else 節を設ける場合、全ての except 節よりも後ろに置かなければなりません。 else 節は try 節 で全く例外が送出されなかったときに実行されるコードを書くのに役立ちます。例えば次のようにします:

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()

追加のコードを付け加えるのは try 節よりも else 節の方がよいでしょう。なぜなら、そうすることで try ... except 文で保護されたコードから送出されたもの以外の例外を過って捕捉してしまうという事態を避けられるからです。

例外ハンドラは、try 節 の直接内側で発生した例外を処理するだけではなくその try 節 から (たとえ間接的にでも) 呼び出された関数の内部で発生した例外も処理します。例えば:

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

8.4. 例外を送出する

raise 文を使って、特定の例外を発生させることができます。例えば:

>>> raise NameError('HiThere')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: HiThere

raise の唯一の引数は送出される例外を指し示します。これは例外インスタンスか例外クラス(BaseException を継承したクラス、たとえば Exception やそのサブクラス)でなければなりません。例外クラスが渡された場合は、引数無しのコンストラクタが呼び出され、暗黙的にインスタンス化されます:

raise ValueError  # shorthand for 'raise ValueError()'

例外が発生したかどうかを判定したいだけで、その例外を処理するつもりがなければ、単純な形式の raise 文を使って例外を再送出させることができます:

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

8.5. 例外の連鎖

except 節の中で未処理の例外が発生した場合、その未処理の例外は処理された例外のエラーメッセージに含まれます:

>>> try:
...     open("database.sqlite")
... except OSError:
...     raise RuntimeError("unable to handle error")
...
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
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>
RuntimeError: unable to handle error

ある例外が他の例外から直接影響されていることを示すために、raise 文にオプションの from 句を指定します:

# exc must be exception instance or None.
raise RuntimeError from exc

これは例外を変換するときに便利です。例えば:

>>> 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>
  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>
RuntimeError: Failed to open database

また、自動的な例外の連鎖を無効にするには from None を指定します。

>>> try:
...     open('database.sqlite')
... except OSError:
...     raise RuntimeError from None
...
Traceback (most recent call last):
  File "<stdin>", line 4, in <module>
RuntimeError

例外の連鎖の仕組みに関して、詳しくは 組み込み例外 を参照してください。

8.6. ユーザー定義例外

プログラム上で新しい例外クラスを作成することで、独自の例外を指定することができます (Python のクラスについては クラス 参照)。例外は、典型的に Exception クラスから、直接または間接的に派生したものです。

例外クラスでは、普通のクラスができることなら何でも定義することができますが、通常は単純なものにしておきます。大抵は、いくつかの属性だけを提供し、例外が発生したときにハンドラがエラーに関する情報を取り出せるようにする程度にとどめます。

ほとんどの例外は、標準の例外の名前付けと同様に、"Error" で終わる名前で定義されています。

多くの標準モジュールでは、モジュールで定義されている関数内で発生する可能性のあるエラーを報告させるために、独自の例外を定義しています。

8.7. クリーンアップ動作を定義する

try 文にはもう一つオプションの節があります。この節はクリーンアップ動作を定義するためのもので、どんな状況でも必ず実行されます。例を示します:

>>> try:
...     raise KeyboardInterrupt
... finally:
...     print('Goodbye, world!')
...
Goodbye, world!
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
KeyboardInterrupt

もし finally 節がある場合、 try 文が終わる前の最後の処理を、 finally 節が実行します。 try 文が例外を発生させるか否かに関わらず、 finally 節は実行されます。以下では、例外が発生するという更に複雑なケースを議論します:

もし try 文の実行中に例外が発生したら、その例外は except 節によって処理されるでしょう。もしその例外が except 節によって処理されなければ、 finally 節が実行された後に、その例外が再送出されます。

except 節または else 節の実行中に例外が発生することがあり得ます。その場合も、 finally 節が実行された後に例外が再送出されます。

finally 節で break、continue または return 文が実行された場合、例外は再送出されません。

もし try 文が break 文、 continue 文または return 文のいずれかに達すると、その break 文、 continue 文または return 文の実行の直前に finally 節が実行されます。

もし finally 節が return 文を含む場合、返される値は try 節の return 文ではなく、finally 節の return 文によるものになります。

例えば:

>>> def bool_return():
...     try:
...         return True
...     finally:
...         return False
...
>>> bool_return()
False

より複雑な例:

>>> 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>
  File "<stdin>", line 3, in divide
TypeError: unsupported operand type(s) for /: 'str' and 'str'

見てわかるとおり、 finally 節はどの場合にも実行されています。文字列で割り算をすることで発生した TypeError は except 節で処理されていないので、 finally 節実行後に再度送出されています。

実世界のアプリケーションでは、 finally 節は(ファイルやネットワーク接続などの)外部リソースを、利用が成功したかどうかにかかわらず解放するために便利です。

8.8. 定義済みクリーンアップ処理

オブジェクトのなかには、その利用の成否にかかわらず、不要になった際に実行される標準的なクリーンアップ処理が定義されているものがあります。以下の、ファイルをオープンして内容を画面に表示する例をみてください。

for line in open("myfile.txt"):
    print(line, end="")

このコードの問題点は、コードの実行が終わった後に不定の時間ファイルを開いたままでいることです。これは単純なスクリプトでは問題になりませんが、大きなアプリケーションでは問題になりえます。 with 文はファイルのようなオブジェクトが常に、即座に正しくクリーンアップされることを保証します。

with open("myfile.txt") as f:
    for line in f:
        print(line, end="")

この文が実行されたあとで、たとえ行の処理中に問題があったとしても、ファイル f は常に close されます。ファイルなどの、定義済みクリーンアップ処理を持つオブジェクトについては、それぞれのドキュメントで示されます。

8.9. 複数の関連しない例外の送出と処理

いくつか発生した例外の報告が必要な状況があります。並列処理のフレームワークでは、複数のタスクが平行して失敗することがたびたびあります。他にも最初の例外を送出するよりも、処理を継続して複数の例外を集約した方が望ましいユースケースもあります。

組み込みの ExceptionGroup は例外インスタンスのリストをまとめ、同時に送出できるようにします。ExceptionGroupも例外なので、他の例外と同じように捕捉できます。:

>>> 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>
  |   File "<stdin>", line 3, in f
  | ExceptionGroup: there were problems
  +-+---------------- 1 ----------------
    | OSError: error 1
    +---------------- 2 ----------------
    | SystemError: error 2
    +------------------------------------
>>> try:
...     f()
... except Exception as e:
...     print(f'caught {type(e)}: e')
...
caught <class 'ExceptionGroup'>: e
>>>

except の代わりに except* を使用すると、グループの中にある特定の型に一致した例外だけを選択して処理できます。以下の例では、ネストした例外グループに対して各 except* 節で特定の型の例外を取り出し、それ以外の例外は他の節に伝えられ、最終的に例外が送出されます。:

>>> 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>
  |   File "<stdin>", line 2, in f
  | ExceptionGroup: group1
  +-+---------------- 1 ----------------
    | ExceptionGroup: group2
    +-+---------------- 1 ----------------
      | RecursionError: 4
      +------------------------------------
>>>

例外グループの中に含める例外は、型ではなくインスタンスである必要があることに注意してください。これは一般的に、以下のパターンようにプログラムで送出された複数の例外を捕捉することが多いためです。:

>>> excs = []
... for test in tests:
...     try:
...         test.run()
...     except Exception as e:
...         excs.append(e)
...
>>> if excs:
...    raise ExceptionGroup("Test Failures", excs)
...

8.10. ノートによって例外を充実させる

例外を送出するために生成するときに、通常は発生したエラーを説明する情報で初期化されます。例外を受け取ったあとに情報を追加すると便利な場合があります。この目的のために、例外は add_note(note) メソッドを持ちます。このメソッドは文字列を受け取り、例外のノートのリストに追加します。標準のトレースバックでは例外の後に、全てのノートが追加した順番に出力されます。:

>>> 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>
TypeError: bad type
Add some information
Add some more information
>>>

たとえば、複数の例外を1つの例外グループにまとめるときに、各エラーのコンテキスト情報を追加したい場合があります。以下のグループ内の各例外が持つノートは、エラーがいつ発生したかを示しています。:

>>> 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>
  | ExceptionGroup: We have some problems (3 sub-exceptions)
  +-+---------------- 1 ----------------
    | Traceback (most recent call last):
    |   File "<stdin>", line 3, in <module>
    |   File "<stdin>", line 2, in f
    | OSError: operation failed
    | Happened in Iteration 1
    +---------------- 2 ----------------
    | Traceback (most recent call last):
    |   File "<stdin>", line 3, in <module>
    |   File "<stdin>", line 2, in f
    | OSError: operation failed
    | Happened in Iteration 2
    +---------------- 3 ----------------
    | Traceback (most recent call last):
    |   File "<stdin>", line 3, in <module>
    |   File "<stdin>", line 2, in f
    | OSError: operation failed
    | Happened in Iteration 3
    +------------------------------------
>>>

9. クラス

クラスはデータと機能を組み合わせる方法を提供します。新規にクラスを作成することで、新しいオブジェクトの 型 を作成し、その型を持つ新しい インスタンス が作れます。クラスのそれぞれのインスタンスは自身の状態を保持する属性を持てます。クラスのインスタンスは、その状態を変更するための (そのクラスが定義する) メソッドも持てます。

Python は、他のプログラミング言語と比較して、最小限の構文と意味付けを使ってクラスを言語に追加しています。Python のクラスは、C++ と Modula-3 のクラスメカニズムを混ぜたものです。Python のクラス機構はオブジェクト指向プログラミングの標準的な機能を全て提供しています。クラスの継承メカニズムは、複数の基底クラスを持つことができ、派生クラスで基底クラスの任意のメソッドをオーバライドすることができます。メソッドでは、基底クラスのメソッドを同じ名前で呼び出すことができます。オブジェクトには任意の種類と数のデータを格納することができます。モジュールと同じく、クラス機構も Python の動的な性質に従うように設計されています。クラスは実行時に生成され、生成後に変更することができます。

C++ の用語で言えば、通常のクラスメンバ (データメンバも含む) は (プライベート変数 に書かれている例外を除いて) public であり、メンバ関数はすべて 仮想関数(virtual) です。 Modula-3 にあるような、オブジェクトのメンバをメソッドから参照するための短縮した記法は使えません: メソッド関数の宣言では、オブジェクト自体を表す第一引数を明示しなければなりません。第一引数のオブジェクトはメソッド呼び出しの際に暗黙の引数として渡されます。 Smalltalk に似て、クラスはそれ自体がオブジェクトです。そのため、 import や名前変更といった操作が可能です。 C++ や Modula-3 と違って、ユーザーは組込み型を基底クラスにして拡張を行えます。また、C++ とは同じで Modula-3 とは違う点として、特別な構文を伴うほとんどの組み込み演算子 (算術演算子 (arithmetic operator) や添字表記) はクラスインスタンスで使うために再定義できます。

(クラスに関して普遍的な用語定義がないので、 Smalltalk と C++ の用語を場合に応じて使っていくことにします。 C++ よりも Modula-3 の方がオブジェクト指向の意味論が Python に近いので、 Modula-3 の用語を使いたいのですが、ほとんどの読者は Modula-3 についてしらないでしょうから。)

9.1. 名前とオブジェクトについて

オブジェクトには個体性があり、同一のオブジェクトに(複数のスコープから) 複数の名前を割り当てることができます。この機能は他の言語では別名づけ(alias) として知られています。 Python を一見しただけでは、別名づけの重要性は分からないことが多く、変更不能な基本型 (数値、文字列、タプル)を扱うときには無視して差し支えありません。しかしながら、別名付けは、リストや辞書や他の多くの型など、変更可能な型を扱う Python コード上で驚くべき効果があります。別名付けはいくつかの点でポインタのように振舞い、このことは通常はプログラムに利するように使われます。例えば、オブジェクトの受け渡しは、実装上はポインタが渡されるだけなのでコストの低い操作になります。また、関数があるオブジェクトを引数として渡されたとき、関数の呼び出し側からオブジェクトに対する変更を見ることができます --- これにより、 Pascal にあるような二つの引数渡し機構をもつ必要をなくしています。

9.2. Python のスコープと名前空間

クラスを紹介する前に、Python のスコープのルールについてあることを話しておかなければなりません。クラス定義は巧みなトリックを名前空間に施すので、何が起こっているのかを完全に理解するには、スコープと名前空間がどのように動作するかを理解する必要があります。ちなみに、この問題に関する知識は全ての Python プログラマにとって有用です。

まず定義から始めましょう。

名前空間 (namespace) とは、名前からオブジェクトへの対応付け (mapping) です。ほとんどの名前空間は、現状では Python の辞書として実装されていますが、そのことは通常は (パフォーマンス以外では) 目立つことはないし、将来は変更されるかもしれません。名前空間の例には、組込み名の集合 (abs() 等の関数や組込み例外名)、モジュール内のグローバルな名前、関数を呼び出したときのローカルな名前があります。オブジェクトの属性からなる集合もまた、ある意味では名前空間です。名前空間について知っておくべき重要なことは、異なった名前空間にある名前の間には全く関係がないということです。例えば、二つの別々のモジュールの両方で関数 maximize という関数を定義することができ、定義自体は混同されることはありません --- モジュールのユーザは名前の前にモジュール名をつけなければなりません。

ところで、 属性 という言葉は、ドットに続く名前すべてに対して使っています --- 例えば式 z.real で、 real はオブジェクト z の属性です。厳密にいえば、モジュール内の名前に対する参照は属性の参照です。式 modname.funcname では、 modname はあるモジュールオブジェクトで、 funcname はその属性です。この場合には、モジュールの属性とモジュールの中で定義されているグローバル名の間には、直接的な対応付けがされます。これらの名前は同じ名前空間を共有しているのです！ [1]

属性は読取り専用にも、書込み可能にもできます。書込み可能であれば、属性に代入することができます。モジュール属性は書込み可能で、 modname.the_answer = 42 と書くことができます。書込み可能な属性は、 del 文で削除することもできます。例えば、 del modname.the_answer は、 modname で指定されたオブジェクトから属性 the_answer を除去します。

名前空間は様々な時点で作成され、その寿命も様々です。組み込みの名前が入った名前空間は Python インタプリタが起動するときに作成され、決して削除されることはありません。モジュールのグローバルな名前空間は、モジュール定義が読み込まれたときに作成されます。通常、モジュールの名前空間は、インタプリタが終了するまで残ります。インタプリタのトップレベルで実行された文は、スクリプトファイルから読み出されたものでも対話的に読み出されたものでも、 __main__ という名前のモジュールの一部分であるとみなされるので、独自の名前空間を持つことになります。 (組み込みの名前は実際にはモジュール内に存在します。そのモジュールは builtins と呼ばれています。)

関数のローカルな名前空間は、関数が呼び出されたときに作成され、関数から戻ったときや、関数内で例外が送出され、かつ関数内で処理されなかった場合に削除されます。 (実際には、忘れられる、と言ったほうが起きていることをよく表しています。) もちろん、再帰呼出しのときには、各々の呼び出しで各自のローカルな名前空間があります。

スコープ (scope) とは、ある名前空間が直接アクセスできるような、 Python プログラムのテキスト上の領域です。 "直接アクセス可能" とは、修飾なしに (訳注: spam.egg ではなく単に egg のように) 名前を参照した際に、その名前空間から名前を見つけようと試みることを意味します。

スコープは静的に決定されますが、動的に使用されます。実行中はいつでも、直接名前空間にアクセス可能な、3つまたは4つの入れ子になったスコープがあります:

最初に探される、最も内側のスコープは、ローカルな名前を持っています。

外側の(enclosing)関数のスコープは、近いほうから順に探され、ローカルでもグローバルでもない名前を持っています。

次のスコープは、現在のモジュールのグローバルな名前を持っています。

一番外側の(最後に検索される)スコープはビルトイン名を持っています。

名前が global と宣言されている場合、その名前に対する参照や代入は全て、モジュールのグローバルな名前の入った最後から2番目のスコープに対して直接行われます。最内スコープの外側にある変数に再束縛するには、 nonlocal 文が使えます。nonlocal と宣言されなかった変数は、全て読み出し専用となります (そのような変数に対する書き込みは、単に 新しい ローカル変数をもっとも内側のスコープで作成し、外部のスコープの値は変化しません)。

通常、ローカルスコープは (プログラムテキスト上の) 現在の関数のローカルな名前を参照します。関数の外側では、ローカルスコープはグローバルな名前空間と同じ名前空間、モジュールの名前空間を参照します。クラス定義では、ローカルスコープの中にもう一つ名前空間が置かれます。

スコープはテキスト上で決定されていると理解することが重要です。モジュール内で定義される関数のグローバルなスコープは、関数がどこから呼び出されても、どんな別名をつけて呼び出されても、そのモジュールの名前空間になります。反対に、実際の名前の検索は実行時に動的に行われます --- とはいえ、言語の定義は、"コンパイル" 時の静的な名前解決の方向に進化しているので、動的な名前解決に頼ってはいけません！ (事実、ローカルな変数は既に静的に決定されています。)

Python の特徴として、global や nonlocal 文が有効でない場合は、名前に対する参照は常に最も内側のスコープに対して有効になります。代入はデータをコピーしません。オブジェクトを名前に束縛するだけです。削除も同様で、del x は、ローカルスコープの名前空間から x に対する拘束を取り除きます。つまるところ、新しい名前を与えるようなすべての操作は、ローカルスコープを使って行われます。 import 文、関数の定義は、モジュールや関数名をローカルスコープの名前に拘束します。

global 文を使うと、特定の変数がグローバルスコープに存在し、そこで再束縛されることを指示できます。 nonlocal 文は、特定の変数が外側のスコープに存在し、そこで再束縛されることを指示します。

9.2.1. スコープと名前空間の例

異なるスコープと名前空間がどのように参照されるか、また global および nonlocal が変数の束縛にどう影響するか、この例で実演します:

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)

このコード例の出力は:

After local assignment: test spam
After nonlocal assignment: nonlocal spam
After global assignment: nonlocal spam
In global scope: global spam

このとおり、(デフォルトの) ローカルな 代入は scope_test 上の spam への束縛を変更しませんでした。 nonlocal 代入は scope_test 上の spam への束縛を変更し、 global 代入はモジュールレベルの束縛を変更しました。

またここから、 global 代入の前には spam に何も束縛されていなかったことも分かります。

9.3. クラス初見

クラスでは、新しい構文を少しと、三つの新たなオブジェクト型、そして新たな意味付けをいくつか取り入れています。

9.3.1. クラス定義の構文

クラス定義の最も単純な形式は、次のようになります:

class ClassName:
    <statement-1>
    .
    .
    .
    <statement-N>

関数定義 (def 文) と同様、クラス定義が効果をもつにはまず実行しなければなりません。 (クラス定義を if 文の分岐先や関数内部に置くことも、考え方としてはありえます。)

実際には、クラス定義の内側にある文は、通常は関数定義になりますが、他の文を書くこともでき、それが役に立つこともあります --- これについては後で述べます。クラス内の関数定義は通常、メソッドの呼び出し規約で決められた独特の形式の引数リストを持ちます --- これについても後で述べます。

クラス定義に入ると、新たな名前空間が作成され、ローカルな名前空間として使われます --- 従って、ローカルな変数に対する全ての代入はこの新たな名前空間に入ります。特に、関数定義を行うと、新たな関数の名前はこの名前空間に結び付けられます。

クラス定義から普通に (定義の終端に到達して) 抜けると、 クラスオブジェクト (class object) が生成されます。クラスオブジェクトは、基本的にはクラス定義で作成された名前空間の内容をくるむラッパー (wrapper) です。クラスオブジェクトについては次の節で詳しく学ぶことにします。 (クラス定義に入る前に有効だった) 元のローカルスコープが復帰し、生成されたクラスオブジェクトは復帰したローカルスコープにクラス定義のヘッダで指定した名前 (上の例では ClassName) で結び付けられます。

9.3.2. クラスオブジェクト

クラスオブジェクトでは２種類の演算、属性参照とインスタンス生成をサポートしています。

属性参照 (attribute reference) は、Python におけるすべての属性参照で使われている標準的な構文、 obj.name を使います。クラスオブジェクトが生成された際にクラスの名前空間にあった名前すべてが有効な属性名です。従って、以下のようなクラス定義では:

class MyClass:
    """A simple example class"""
    i = 12345

    def f(self):
        return 'hello world'

MyClass.i と MyClass.f は有効な属性参照であり、それぞれ整数と関数オブジェクトを返します。クラス属性も代入できるため、代入により MyClass.i の値を変えられます。 __doc__ も有効な属性で、そのクラスに属しているドキュメンテーション文字列(docstring) 、この場合は "A simple example class" を返します。

クラスの インスタンス化 (instantiation) には関数記法を使います。クラスオブジェクトのことを、クラスの新しいインスタンスを返す、引数のない関数のように扱ってください。上記クラスで例示すると:

x = MyClass()

は、クラスの新しい インスタンス (instance) を生成し、そのオブジェクトをローカル変数 x へ代入します。

インスタンス化操作 (クラスオブジェクトの "呼出し") では、空のオブジェクトが作られます。多くのクラスでは、特定の初期状態にカスタマイズされたオブジェクトを作りたいです。そのために、クラスには __init__() という名前の特殊メソッドを定義できます。例えば次のようにします:

def __init__(self):
    self.data = []

クラスが __init__() メソッドを定義している場合、クラスをインスタンス化すると、新しく作られたクラスインスタンスに対して自動的に __init__() を呼び出します。 従って この例では、新たな初期済みインスタンスを次のようにして得られます:

x = MyClass()

もちろん、より大きな柔軟性を持たせるために、 __init__() メソッドに複数の引数をもたせることができます。その場合、次の例のように、クラスのインスタンス化操作に渡された引数は __init__() に渡されます。例えば、

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

9.3.3. インスタンスオブジェクト

ところで、インスタンスオブジェクトを使うと何ができるのでしょうか？インスタンスオブジェクトが理解できる唯一の操作は、属性の参照です。有効な属性名には (データ属性およびメソッドの) 二種類あります。

データ属性 (data attribute) は、 Smalltalk の "インスタンス変数" や C++の "データメンバ" に相当します。データ属性を宣言する必要はありません。ローカル変数と同様に、これらの属性は最初に代入された時点で湧き出てきます。例えば、上で生成した MyClass のインスタンス x に対して、次のコードを実行すると、跡を残さず値 16 を印字します:

x.counter = 1
while x.counter < 10:
    x.counter = x.counter * 2
print(x.counter)
del x.counter

もうひとつのインスタンス属性は メソッド (method) です。メソッドとは、オブジェクトに "属している" 関数のことです。(Python では、メソッドという用語はクラスインスタンスだけのものではありません。オブジェクト型にもメソッドを持つことができます。例えば、リストオブジェクトには、 append, insert, remove, sort などといったメソッドがあります。とはいえ、以下では特に明記しない限り、クラスのインスタンスオブジェクトのメソッドだけを意味するものとして使うことにします。)

インスタンスオブジェクトで有効なメソッド名は、そのクラスによります。定義により、クラスの全ての関数オブジェクトである属性がインスタンスオブジェクトの妥当なメソッド名に決まります。従って、例では、MyClass.f は関数なので、x.f はメソッドの参照として有効です。しかし、MyClass.i は関数ではないので、x.i はメソッドの参照として有効ではありません。x.f は MyClass.f と同じものではありません --- 関数オブジェクトではなく、メソッドオブジェクト (method object) です。

9.3.4. メソッドオブジェクト

普通、メソッドはバインドされた直後に呼び出されます:

x.f()

この MyClass の例では、文字列 'hello world' が返されます。しかし、必ずしもすぐメソッドを呼び出さなければならないわけではありません。 x.f はメソッドオブジェクトであり、どこかに入れておいて後で呼び出すことができます。例えば次のコードは:

xf = x.f
while True:
    print(xf())

hello world を時が終わるまで印字し続けるでしょう。

メソッドが呼び出されるときには実際には何が起きているのでしょうか？ f() の関数定義では引数を一つ指定していたにもかかわらず、上の例では x.f() が引数なしで呼び出されています。引数はどうなったのでしょうか？たしか、引数が必要な関数を引数無しで呼び出すと、 Python が例外を送出するはずです --- たとえその引数が実際には使われなくても…。

もう答は想像できているかもしれませんね: メソッドについて特別なこととして、インスタンスオブジェクトが関数の第1引数として渡されます。例では、 x.f() という呼び出しは、 MyClass.f(x) と厳密に等価なものです。一般に、 n 個の引数リストもったメソッドの呼出しは、そのメソッドのインスタンスオブジェクトを最初の引数の前に挿入した引数リストで、メソッドに対応する関数を呼び出すことと等価です。

一般的に、メソッドは以下のように動作します。インスタンスの非データ属性が参照されたときは、そのインスタンスのクラスが検索されます。その名前が有効なクラス属性を表している関数オブジェクトなら、インスタンスオブジェクトと関数オブジェクトの両方への参照がメソッドオブジェクトにパックされます。メソッドオブジェクトが引数リストと共に呼び出されるとき、インスタンスオブジェクトと渡された引数リストから新しい引数リストを作成して、元の関数オブジェクトを新しい引数リストで呼び出します。

9.3.5. クラスとインスタンス変数

一般的に、インスタンス変数はそれぞれのインスタンスについて固有のデータのためのもので、クラス変数はそのクラスのすべてのインスタンスによって共有される属性やメソッドのためのものです:

class Dog:

    kind = 'canine'         # class variable shared by all instances

    def __init__(self, name):
        self.name = name    # instance variable unique to each instance

>>> d = Dog('Fido')
>>> e = Dog('Buddy')
>>> d.kind                  # shared by all dogs
'canine'
>>> e.kind                  # shared by all dogs
'canine'
>>> d.name                  # unique to d
'Fido'
>>> e.name                  # unique to e
'Buddy'

名前とオブジェクトについて で議論したように、共有データはリストや辞書のような mutable オブジェクトが関与すると驚くべき効果を持ち得ます。例えば、以下のコードの tricks リストはクラス変数として使われるべきではありません、なぜならたった一つのリストがすべての Dog インスタンスによって共有されることになり得るからです:

class Dog:

    tricks = []             # mistaken use of a class variable

    def __init__(self, name):
        self.name = name

    def add_trick(self, trick):
        self.tricks.append(trick)

>>> d = Dog('Fido')
>>> e = Dog('Buddy')
>>> d.add_trick('roll over')
>>> e.add_trick('play dead')
>>> d.tricks                # unexpectedly shared by all dogs
['roll over', 'play dead']

このクラスの正しい設計ではインスタンス変数を代わりに使用するべきです:

class Dog:

    def __init__(self, name):
        self.name = name
        self.tricks = []    # creates a new empty list for each dog

    def add_trick(self, trick):
        self.tricks.append(trick)

>>> d = Dog('Fido')
>>> e = Dog('Buddy')
>>> d.add_trick('roll over')
>>> e.add_trick('play dead')
>>> d.tricks
['roll over']
>>> e.tricks
['play dead']

9.4. いろいろな注意点

インスタンスとクラスの両方で同じ属性名が使用されている場合、属性検索はインスタンスが優先されます。

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

データ属性は、メソッドから参照できると同時に、通常のオブジェクトのユーザ ("クライアント") からも参照できます。言い換えると、クラスは純粋な抽象データ型として使うことができません。実際、 Python では、データ隠蔽を補強するための機構はなにもありません --- データの隠蔽はすべて規約に基づいています。 (逆に、C 言語で書かれた Python の実装では実装の詳細を完全に隠蔽し、必要に応じてオブジェクトへのアクセスを制御できます。この機構は C 言語で書かれた Python 拡張で使うことができます。)

クライアントはデータ属性を注意深く扱うべきです --- クライアントは、メソッドが維持しているデータ属性の不変式を踏みにじり、台無しにするかもしれません。クライアントは、名前の衝突が回避されている限り、メソッドの有効性に影響を及ぼすことなくインスタンスに独自の属性を追加することができる、ということに注意してください --- ここでも、名前付けの規約は頭痛の種を無くしてくれます。

メソッドの中から、データ属性を (または別のメソッドも！) 参照するための短縮された記法はありません。私は、この仕様がメソッドの可読性を高めていると感じています。あるメソッドを眺めているときにローカルな変数とインスタンス変数をはっきり区別できるからです。

よく、メソッドの最初の引数を self と呼びます。この名前付けは単なる慣習でしかありません。 self という名前は、 Python では何ら特殊な意味を持ちません。とはいえ、この慣行に従わないと、コードは他の Python プログラマにとってやや読みにくいものとなります。また、 クラスブラウザ (class browser) プログラムがこの慣行をあてにして書かれているかもしれません。

クラス属性である関数オブジェクトはいずれも、そのクラスのインスタンスのためのメソッドを定義しています。関数定義は、テキスト上でクラス定義の中に入っている必要はありません。関数オブジェクトをクラスのローカルな変数の中に代入するのも OK です。例えば以下のコードのようにします:

# Function defined outside the class
def f1(self, x, y):
    return min(x, x+y)

class C:
    f = f1

    def g(self):
        return 'hello world'

    h = g

これで、 f 、 g 、および h は、すべて C の属性であり関数オブジェクトを参照しています。従って、これらは、すべて C のインスタンスのメソッドとなります --- h は g と全く等価です。これを実践しても、大抵は単にプログラムの読者に混乱をもたらすだけなので注意してください。

メソッドは、 self 引数のメソッド属性を使って、他のメソッドを呼び出すことができます:

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)

メソッドは、通常の関数と同じようにしてグローバルな名前を参照します。あるメソッドに関するグローバルスコープは、その定義を含むモジュールです。(クラスはグローバルなスコープとして用いられることはありません。) メソッドでグローバルなデータを使う良い理由はほとんどありませんが、グローバルなスコープを使うべき場面は多々あります。一つ挙げると、メソッド内から、グローバルなスコープに import された関数やモジュールや、そのモジュール中で定義された関数やクラスを使うことができます。通常、メソッドの入っているクラス自体はグローバルなスコープ内で定義されています。次の節では、メソッドが自分のクラスを参照する理由として正当なものを見てみましょう。

個々の値はオブジェクトなので、 クラス (型 とも言います) を持っています。それは object.__class__ に保持されています。

9.5. 継承

言うまでもなく、継承の概念をサポートしない言語機能は "クラス" と呼ぶに値しません。派生クラス (derived class) を定義する構文は次のようになります:

class DerivedClassName(BaseClassName):
    <statement-1>
    .
    .
    .
    <statement-N>

基底クラス (base class) の名前 BaseClassName は、派生クラス定義の入っているスコープからアクセスできる名前空間で定義されていなければなりません。基底クラス名のかわりに任意の式を入れることもできます。これは次の例のように、基底クラスが別モジュールで定義されているときに便利なことがあります:

class DerivedClassName(modname.BaseClassName):

派生クラス定義の実行は、基底クラスの場合と同じように進められます。クラスオブジェクトが構築される時、基底クラスが記憶されます。記憶された基底クラスは、属性参照を解決するために使われます。要求された属性がクラスに見つからなかった場合、基底クラスに検索が進みます。この規則は、基底クラスが他の何らかのクラスから派生したものであった場合、再帰的に適用されます。

派生クラスのインスタンス化では、特別なことは何もありません。 DerivedClassName() はクラスの新たなインスタンスを生成します。メソッドの参照は次のようにして解決されます。まず対応するクラス属性が検索されます。検索は、必要に応じ、基底クラス連鎖を下って行われ、検索の結果として何らかの関数オブジェクトがもたらされた場合、メソッド参照は有効なものとなります。

派生クラスは基底クラスのメソッドを上書き (override) することができます。メソッドは同じオブジェクトの別のメソッドを呼び出す際に何ら特殊な権限を持ちません。このため、ある基底クラスのメソッドが、同じ基底クラスで定義されているもう一つのメソッド呼び出しを行っている場合、派生クラスで上書きされた何らかのメソッドが呼び出されることになるかもしれません。 (C++ プログラマへ: Python では、すべてのメソッドは事実上 virtual です。)

派生クラスで上書きしているメソッドでは、基底クラスの同名のメソッドを置き換えるのではなく、拡張したいのかもしれません。基底クラスのメソッドを直接呼び出す簡単な方法があります。単に BaseClassName.methodname(self, arguments) を呼び出すだけです。この仕様は、場合によってはクライアントでも役に立ちます。 (この呼び出し方が動作するのは、基底クラスがグローバルスコープの BaseClassName という名前でアクセスできるときだけです。)

Python には継承に関係する 2 つの組み込み関数があります:

isinstance() を使うとインスタンスの型が調べられます。 isinstance(obj, int) は obj.__class__ が int や int の派生クラスの場合に限り True になります。

issubclass() を使うとクラスの継承関係が調べられます。 bool は int のサブクラスなので issubclass(bool, int) は True です。しかし、 float は int のサブクラスではないので issubclass(float, int) は False です。

9.5.1. 多重継承

Python では、多重継承 (multiple inheritance) の形式もサポートしています。複数の基底クラスをもつクラス定義は次のようになります:

class DerivedClassName(Base1, Base2, Base3):
    <statement-1>
    .
    .
    .
    <statement-N>

ほとんどのシンプルな多重継承において、親クラスから継承される属性の検索は、深さ優先で、左から右に、そして継承の階層の中で同じクラスが複数出てくる（訳注: ダイアモンド継承と呼ばれます）場合に２度探索をしない、と考えることができます。なので、ある属性が DerivedClassName で見つからない場合、まず Base1 から検索され、そして（再帰的に） Base1 の基底クラスから検索され、それでも見つからなかった場合は Base2 から検索される、といった具合になります。

実際には、それよりもう少しだけ複雑です。協調的な super() の呼び出しのためにメソッドの解決順序は動的に変更されます。このアプローチは他の多重継承のある言語で call-next-method として知られており、単一継承しかない言語の super 呼び出しよりも強力です。

動的順序付けが必要なのは、すべての多重継承で１つ以上のダイヤモンド継承 (少なくとも 1 つの祖先クラスに対して最下位クラスから到達する経路が複数ある状態) が見られるためです。例えば、全ての新形式のクラスは object を継承しているので、どの多重継承でも object への到達経路が複数あります。基底クラスが複数回アクセスされないようにするために、動的アルゴリズムで検索順序を線形化します。それは、各クラスで指定されている左から右への順序は崩さず、各々の祖先クラスを一度だけ呼び出し、かつ単調になる (つまり祖先クラスの検索順序に影響を与えずにクラスをサブクラス化できる) ように行います。まとめると、これらの特徴のおかげで信頼性と拡張性のある多重継承したクラスを設計することができるのです。詳細は、 The Python 2.3 Method Resolution Order を見てください。

9.6. プライベート変数

オブジェクトの中からしかアクセス出来ない "プライベート" インスタンス変数は、 Python にはありません。しかし、ほとんどの Python コードが従っている慣習があります。アンダースコアで始まる名前 (例えば _spam) は、 (関数であれメソッドであれデータメンバであれ) 非 public なAPIとして扱います。これらは、予告なく変更されるかもしれない実装の詳細として扱われるべきです。

クラスのプライベートメンバについて適切なユースケース(特にサブクラスで定義された名前との衝突を避ける場合)があるので、名前マングリング (name mangling) と呼ばれる、限定されたサポート機構があります。 __spam (先頭に二個以上の下線文字、末尾に一個以下の下線文字) という形式の識別子は、 _classname__spam へとテキスト置換されるようになりました。ここで classname は、現在のクラス名から先頭の下線文字をはぎとった名前になります。このような難号化 (mangle) は、識別子の文法的な位置にかかわらず行われるので、クラス定義内に現れた識別子全てに対して実行されます。

名前マングリングは、サブクラスが内部のメソッド呼び出しを壊さずにメソッドをオーバーライドするのに便利です。例えば:

class Mapping:
    def __init__(self, iterable):
        self.items_list = []
        self.__update(iterable)

    def update(self, iterable):
        for item in iterable:
            self.items_list.append(item)

    __update = update   # private copy of original update() method

class MappingSubclass(Mapping):

    def update(self, keys, values):
        # provides new signature for update()
        # but does not break __init__()
        for item in zip(keys, values):
            self.items_list.append(item)

上の例は、もし仮に MappingSubclass に __update 識別子を実装したとしてもきちんと動きます。その理由は、 Mapping クラスではその識別子を _Mapping__update に、 MappingSubclass クラスでは _MappingSubclass__update にそれぞれ置き換えるからです。

難号化の規則は主に不慮の事故を防ぐためのものだということに注意してください; 確信犯的な方法で、プライベートとされている変数にアクセスしたり変更することは依然として可能なのです。デバッガのような特殊な状況では、この仕様は便利ですらあります。

exec() や eval() へ渡されたコードでは、呼出し元のクラス名を現在のクラスと見なさないことに注意してください。この仕様は global 文の効果と似ており、その効果もまた同様に、バイトコンパイルされたコードに制限されています。同じ制約が getattr() と setattr() と delattr() にも適用されます。また、__dict__ を直接参照するときにも適用されます。

9.7. 残りのはしばし

Pascal の "レコード (record)" や、C 言語の "構造体 (struct)" のような、名前つきのデータ要素を一まとめにするデータ型があると便利なことがあります。慣用的な手法として、この目的のために dataclasses を使用します。

from dataclasses import dataclass

@dataclass
class Employee:
    name: str
    dept: str
    salary: int

>>> john = Employee('john', 'computer lab', 1000)
>>> john.dept
'computer lab'
>>> john.salary
1000

ある特定の抽象データ型を要求する Python コードの断片に、そのデータ型のメソッドをエミュレーションするクラスを代わりに渡すことができます。例えば、ファイルオブジェクトから何らかのデータを構築する関数がある場合、 read() と readline() を持つクラスを定義して、ファイルではなく文字列バッファからデータを取得するようにしておき、引数として渡すことができます。

Instance method objects にも属性があります。 m.__self__ はメソッド m() の属しているインスタンスオブジェクトで、m.__func__ はそのメソッドに対応する function object です。

9.8. イテレータ (iterator)

すでに気づいているでしょうが、 for 文を使うとほとんどのコンテナオブジェクトにわたってループを行うことができます:

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='')

こういう要素へのアクセス方法は明確で簡潔で使い易いものです。イテレータの活用は Python へ広く行き渡り、統一感を持たせています。裏では for 文はコンテナオブジェクトに対して iter() 関数を呼んでいます。関数は、コンテナの中の要素に1つずつアクセスする __next__() メソッドが定義されているイテレータオブジェクトを返します。これ以上要素が無い場合は、 __next__() メソッドは StopIteration 例外を送出し、その通知を受け for ループは終了します。組み込みの next() 関数を使って __next__() メソッドを直接呼ぶこともできます; この例は関数がどう働くのかを示しています:

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

イテレータプロトコルの裏にある仕組みを観察していれば、自作のクラスにイテレータとしての振舞いを追加するのは簡単です。 __next__() メソッドを持つオブジェクトを返す __iter__() メソッドを定義するのです。クラスが __next__() メソッドを定義している場合、 __iter__() メソッドは単に self を返すことも可能です:

class Reverse:
    """Iterator for looping over a sequence backwards."""
    def __init__(self, data):
        self.data = data
        self.index = len(data)

    def __iter__(self):
        return self

    def __next__(self):
        if self.index == 0:
            raise StopIteration
        self.index = self.index - 1
        return self.data[self.index]

>>> rev = Reverse('spam')
>>> iter(rev)
<__main__.Reverse object at 0x00A1DB50>
>>> for char in rev:
...     print(char)
...
m
a
p
s

9.9. ジェネレータ (generator)

ジェネレータ は、イテレータを作成するための簡潔で強力なツールです。ジェネレータは通常の関数のように書かれますが、何らかのデータを返すときには yield 文を使います。そのジェネレータに対して next() が呼び出されるたびに、ジェネレータは以前に中断した処理を再開します (ジェネレータは、全てのデータ値と最後にどの文が実行されたかを記憶しています)。以下の例を見れば、ジェネレータがとても簡単に作成できることがわかります:

def reverse(data):
    for index in range(len(data)-1, -1, -1):
        yield data[index]

>>> for char in reverse('golf'):
...     print(char)
...
f
l
o
g

ジェネレータでできることは、前の節で解説したクラスを使ったイテレータでも実現できます。ジェネレータの定義がコンパクトになるのは __iter__() メソッドと __next__() メソッドが自動で作成されるからです。

ジェネレータのもう一つの重要な機能は、呼び出しごとにローカル変数と実行状態が自動的に保存されるということです。これにより、 self.index や self.data といったインスタンス変数を使ったアプローチよりも簡単に関数を書くことができるようになります。

メソッドを自動生成したりプログラムの実行状態を自動保存するほかに、ジェネレータは終了時に自動的に StopIteration を送出します。これらの機能を組み合わせると、通常の関数を書くのと同じ労力で、簡単にイテレータを生成できます。

9.10. ジェネレータ式

単純なジェネレータなら式として簡潔にコーディングできます。その式はリスト内包表記に似た構文を使いますが、角括弧ではなく丸括弧で囲います。ジェネレータ式は、関数の中でジェネレータをすぐに使いたいような状況のために用意されています。ジェネレータ式は完全なジェネレータの定義よりコンパクトですが、ちょっと融通の効かないところがあります。同じ内容を返すリスト内包表記よりはメモリに優しいことが多いという利点があります。

例:

>>> sum(i*i for i in range(10))                 # sum of squares
285

>>> xvec = [10, 20, 30]
>>> yvec = [7, 5, 3]
>>> sum(x*y for x,y in zip(xvec, yvec))         # dot product
260

>>> unique_words = set(word for line in page  for word in line.split())

>>> valedictorian = max((student.gpa, student.name) for student in graduates)

>>> data = 'golf'
>>> list(data[i] for i in range(len(data)-1, -1, -1))
['f', 'l', 'o', 'g']

脚注

[1]

例外が一つあります。モジュールオブジェクトには、秘密の読取り専用の属性 __dict__ があり、モジュールの名前空間を実装するために使われている辞書を返します; __dict__ という名前は属性ですが、グローバルな名前ではありません。この属性を利用すると名前空間の実装に対する抽象化を侵すことになるので、プログラムを検死するデバッガのような用途に限るべきです。

10. 標準ライブラリミニツアー

10.1. OSへのインターフェース

os モジュールは、オペレーティングシステムと対話するための多くの関数を提供しています:

>>> import os
>>> os.getcwd()      # Return the current working directory
'C:\\Python312'
>>> os.chdir('/server/accesslogs')   # Change current working directory
>>> os.system('mkdir today')   # Run the command mkdir in the system shell
0

from os import * ではなく、 import os 形式を使うようにしてください。そうすることで、動作が大きく異なる組み込み関数 open() が os.open() で遮蔽されるのを避けられます。

組み込み関数 dir() および help() は、 os のような大規模なモジュールで作業をするときに、対話的な操作上の助けになります:

>>> import os
>>> dir(os)
<returns a list of all module functions>
>>> help(os)
<returns an extensive manual page created from the module's docstrings>

ファイルやディレクトリの日常的な管理作業のために、より簡単に使える高水準のインターフェースが shutil モジュールで提供されています:

>>> import shutil
>>> shutil.copyfile('data.db', 'archive.db')
'archive.db'
>>> shutil.move('/build/executables', 'installdir')
'installdir'

10.2. ファイルのワイルドカード表記

glob モジュールでは、ディレクトリのワイルドカード検索からファイルのリストを生成するための関数を提供しています:

>>> import glob
>>> glob.glob('*.py')
['primes.py', 'random.py', 'quote.py']

10.3. コマンドライン引数

一般的なユーティリティスクリプトでは、よくコマンドライン引数を扱う必要があります。コマンドライン引数は モジュールの argv 属性にリストとして保存されています。例として以下の demo.py ファイルを見てみましょう:

# File demo.py
import sys
print(sys.argv)

以下は、コマンドライン上で python demo.py one two three と実行した時の出力です:

['demo.py', 'one', 'two', 'three']

argparse モジュールは、コマンドライン引数を処理するための更に洗練された仕組みを提供します。次のスクリプトは1つ以上のファイル名を抽出し、オプションで行数を表示します。

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)

コマンドラインで python top.py --lines=5 alpha.txt beta.txt を実行すると、上のスクリプトは args.lines を 5 、 args.filenames を ['alpha.txt', 'beta.txt'] に設定します。

10.4. エラー出力のリダイレクトとプログラムの終了

sys モジュールには、 stdin, stdout, stderr を表す属性も存在します。 stderr は、警告やエラーメッセージを出力して、 stdout がリダイレクトされた場合でも読めるようにするために便利です:

>>> sys.stderr.write('Warning, log file not found starting a new one\n')
Warning, log file not found starting a new one

sys.exit() は、スクリプトを終了させるもっとも直接的な方法です。

10.5. 文字列のパターンマッチング

re モジュールでは、より高度な文字列処理のための正規表現を提供しています。正規表現は複雑な一致検索や操作に対して簡潔で最適化された解決策を提供します:

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

最小限の機能だけが必要なら、読みやすくデバッグしやすい文字列メソッドの方がお勧めです:

>>> 'tea for too'.replace('too', 'two')
'tea for two'

10.6. 数学

math モジュールは、浮動小数点演算のための C 言語ライブラリ関数にアクセスする手段を提供しています:

>>> import math
>>> math.cos(math.pi / 4)
0.70710678118654757
>>> math.log(1024, 2)
10.0

random モジュールは、乱数に基づいた要素選択のためのツールを提供しています:

>>> import random
>>> random.choice(['apple', 'pear', 'banana'])
'apple'
>>> random.sample(range(100), 10)   # sampling without replacement
[30, 83, 16, 4, 8, 81, 41, 50, 18, 33]
>>> random.random()    # random float
0.17970987693706186
>>> random.randrange(6)    # random integer chosen from range(6)
4

statistics モジュールは数値データの基礎的な統計的特性（平均、中央値、分散等）を計算します:

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

SciPy プロジェクト <https://scipy.org> は数値処理のための多くのモジュールを提供しています。

10.7. インターネットへのアクセス

インターネットにアクセスしたりインターネットプロトコルを処理したりするための多くのモジュールがあります。最も単純な2つのモジュールは、 URL からデータを取得するための urllib.request と、メールを送るための smtplib です:

>>> from urllib.request import urlopen
>>> with urlopen('http://worldtimeapi.org/api/timezone/etc/UTC.txt') as response:
...     for line in response:
...         line = line.decode()             # Convert bytes to a str
...         if line.startswith('datetime'):
...             print(line.rstrip())         # Remove trailing newline
...
datetime: 2022-01-01T01:36:47.689215+00:00

>>> import smtplib
>>> server = smtplib.SMTP('localhost')
>>> server.sendmail('soothsayer@example.org', 'jcaesar@example.org',
... """To: jcaesar@example.org
... From: soothsayer@example.org
...
... Beware the Ides of March.
... """)
>>> server.quit()

(2つ目の例は localhost でメールサーバーが動いている必要があることに注意してください。)

10.8. 日付と時刻

datetime モジュールは、日付や時刻を操作するためのクラスを、単純な方法と複雑な方法の両方で提供しています。日付や時刻に対する算術がサポートされている一方、実装では出力のフォーマットや操作のための効率的なデータメンバ抽出に重点を置いています。このモジュールでは、タイムゾーンに対応したオブジェクトもサポートしています。

>>> # dates are easily constructed and formatted
>>> from datetime import date
>>> now = date.today()
>>> now
datetime.date(2003, 12, 2)
>>> now.strftime("%m-%d-%y. %d %b %Y is a %A on the %d day of %B.")
'12-02-03. 02 Dec 2003 is a Tuesday on the 02 day of December.'

>>> # dates support calendar arithmetic
>>> birthday = date(1964, 7, 31)
>>> age = now - birthday
>>> age.days
14368

10.9. データ圧縮

一般的なデータアーカイブと圧縮形式は、以下のようなモジュールによって直接的にサポートされます: zlib, gzip, bz2, lzma, zipfile, tarfile。

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

10.10. パフォーマンスの計測

Python ユーザの中には、同じ問題を異なったアプローチで解いた際の相対的なパフォーマンスについて知りたいという深い興味を持っている人がいます。Python は、そういった疑問に即座に答える計測ツールを提供しています。

例えば、引数の入れ替え操作に対して、伝統的なアプローチの代わりにタプルのパックやアンパックを使ってみたいと思うかもしれません。 timeit モジュールを使えば、パフォーマンスがほんの少し良いことがすぐに分かります:

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

timeit では小さい粒度を提供しているのに対し、 profile や pstats モジュールではより大きなコードブロックにおいて律速となる部分を判定するためのツールを提供しています。

10.11. 品質管理

高い品質のソフトウェアを開発するための一つのアプローチは、各関数に対して開発と同時にテストを書き、開発の過程で頻繁にテストを走らせるというものです。

doctest モジュールでは、モジュールを検索してプログラムの docstring に埋め込まれたテストの評価を行うためのツールを提供しています。テストの作り方は単純で、典型的な呼び出し例とその結果を docstring にカット&ペーストするだけです。この作業は、ユーザに使用例を与えるという意味でドキュメントの情報を増やすと同時に、ドキュメントに書かれているコードが正しい事を確認できるようになります:

def average(values):
    """Computes the arithmetic mean of a list of numbers.

    >>> print(average([20, 30, 70]))
    40.0
    """
    return sum(values) / len(values)

import doctest
doctest.testmod()   # automatically validate the embedded tests

unittest モジュールは doctest モジュールほど気楽に使えるものではありませんが、より網羅的なテストセットを別のファイルで管理することができます:

import unittest

class TestStatisticalFunctions(unittest.TestCase):

    def test_average(self):
        self.assertEqual(average([20, 30, 70]), 40.0)
        self.assertEqual(round(average([1, 5, 7]), 1), 4.3)
        with self.assertRaises(ZeroDivisionError):
            average([])
        with self.assertRaises(TypeError):
            average(20, 30, 70)

unittest.main()  # Calling from the command line invokes all tests

10.12. バッテリー同梱

Python には "バッテリー同梱 (batteries included)" 哲学があります。この哲学は、洗練され、安定した機能を持つ Python の膨大なパッケージ群に如実に表れています。例えば:

xmlrpc.client および xmlrpc.server モジュールは、遠隔手続き呼び出し (remote procedure call) を全く大したことのない作業に変えてしまいます。モジュール名とは違い、XML を扱うための直接的な知識は必要ありません。

email パッケージは、MIME やその他の RFC 2822 [https://datatracker.ietf.org/doc/html/rfc2822.html] に基づくメッセージ文書を含む電子メールメッセージを管理するためのライブラリです。実際にメッセージを送信したり受信したりする smtplib や poplib と違って、email パッケージには (添付文書を含む) 複雑なメッセージ構造の構築やデコードを行ったり、インターネット標準のエンコードやヘッダプロトコルの実装を行ったりするための完全なツールセットを備えています。

json パッケージはこの一般的なデータ交換形式のパースをロバストにサポートしています。csv モジュールはデータベースや表計算で一般的にサポートされている CSV ファイルを直接読み書きするのをサポートしています。xml.etree.ElementTree、xml.dom ならびに xml.sax パッケージは XML の処理をサポートしています。総合すると、これらのモジュールによって Python アプリケーションと他のツールの間でとても簡単にデータを受け渡すことが出来ます。

sqlite3 モジュールは SQLite データベースライブラリのラッパーです。若干非標準の SQL シンタックスを用いて更新や接続出来る永続的なデータベースを提供します。

国際化に関する機能は、 gettext, locale, codecs パッケージといったモジュール群でサポートされています。

11. 標準ライブラリミニツアー --- その 2

ツアーの第2部では、プロフェッショナルプログラミングを支えるもっと高度なモジュールをカバーします。ここで挙げるモジュールは、小さなスクリプトの開発ではほとんど使いません。

11.1. 出力のフォーマット

reprlib モジュールは、大きなコンテナや、深くネストしたコンテナを省略して表示するバージョンの repr() を提供しています:

>>> import reprlib
>>> reprlib.repr(set('supercalifragilisticexpialidocious'))
"{'a', 'c', 'd', 'e', 'f', 'g', ...}"

pprint モジュールは、組み込み型やユーザ定義型をわかりやすく表示するための洗練された制御手段を提供しています。表示結果が複数行にわたる場合は、 "pretty printer" と呼ばれるものが改行やインデントを追加して、データ構造がより明確になるように印字します:

>>> import pprint
>>> t = [[[['black', 'cyan'], 'white', ['green', 'red']], [['magenta',
...     'yellow'], 'blue']]]
...
>>> pprint.pprint(t, width=30)
[[[['black', 'cyan'],
   'white',
   ['green', 'red']],
  [['magenta', 'yellow'],
   'blue']]]

textwrap モジュールは、段落で構成された文章を、指定したスクリーン幅にぴったり収まるように調整します:

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

locale モジュールは、文化により異なるデータ表現形式のデータベースにアクセスします。 locale の format() 関数の grouping 属性を使えば、数値を適切な桁区切り文字によりグループ化された形式に変換できます:

>>> import locale
>>> locale.setlocale(locale.LC_ALL, 'English_United States.1252')
'English_United States.1252'
>>> conv = locale.localeconv()          # get a mapping of conventions
>>> x = 1234567.8
>>> locale.format_string("%d", x, grouping=True)
'1,234,567'
>>> locale.format_string("%s%.*f", (conv['currency_symbol'],
...                      conv['frac_digits'], x), grouping=True)
'$1,234,567.80'

11.2. 文字列テンプレート

string モジュールには、柔軟で、エンドユーザが簡単に編集できる簡単な構文を備えた Template クラスが入っています。このクラスを使うと、ユーザがアプリケーションを修正することなしにアプリケーションの出力をカスタマイズできるようになります。

テンプレートでは、$ と有効な Python 識別子名 (英数字とアンダースコア) からなるプレースホルダ名を使います。プレースホルダの周りを {} で囲えば、プレースホルダの後ろにスペースを挟まず、英数文字を続けることができます。$$ のようにすると、$ 自体をエスケープできます:

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

substitute() メソッドは、プレースホルダに相当する値が辞書やキーワード引数にない場合に KeyError を送出します。メールマージ機能のようなアプリケーションの場合、ユーザが入力するデータは不完全なことがあるので、欠落したデータがあるとプレースホルダをそのままにして出力する safe_substitute() メソッドを使う方が適切かもしれません:

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

区切り文字はデフォルトは $ ですが、Template のサブクラスを派生すると変更することができます。例えば、画像ブラウザ用に一括で名前を変更するユーティリティを作っていたとして、現在の日付や画像のシーケンス番号、ファイル形式といったプレースホルダにパーセント記号を使うことにしたら、次のようになります:

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

テンプレートのもう一つの用途は、複数ある出力フォーマットからのプログラムロジックの分離です。これにより、XMLファイル用、プレーンテキストのレポート用、HTMLのwebレポート用のテンプレートに、同じプログラムロジックから値を埋め込むことができます。

11.3. バイナリデータレコードの操作

struct モジュールでは、様々な長さのバイナリレコード形式を操作する pack() や unpack() といった関数を提供しています。 以下の例では、 zipfile モジュールを使わずに、ZIP ファイルのヘッダ情報を巡回する方法を示しています。"H" と "I" というパック符号は、それぞれ2バイトと4バイトの符号無し 整数を表しています。 "<" は、そのパック符号が standard サイズであり、バイトオーダーがリトルエンディアンであることを示しています:

import struct

with open('myfile.zip', 'rb') as f:
    data = f.read()

start = 0
for i in range(3):                      # show the first 3 file headers
    start += 14
    fields = struct.unpack('<IIIHH', data[start:start+16])
    crc32, comp_size, uncomp_size, filenamesize, extra_size = fields

    start += 16
    filename = data[start:start+filenamesize]
    start += filenamesize
    extra = data[start:start+extra_size]
    print(filename, hex(crc32), comp_size, uncomp_size)

    start += extra_size + comp_size     # skip to the next header

11.4. マルチスレッディング

スレッド処理 (threading) とは、順序的な依存関係にない複数のタスクを分割するテクニックです。スレッドは、ユーザの入力を受け付けつつ、背後で別のタスクを動かすようなアプリケーションの応答性を高めます。同じような使用例として、I/O を別のスレッドの計算処理と並列して動作させるというものがあります。

以下のコードでは、高水準のモジュール threading でメインのプログラムを動かしながら背後で別のタスクを動作させられるようにする方法を示しています:

import threading, zipfile

class AsyncZip(threading.Thread):
    def __init__(self, infile, outfile):
        threading.Thread.__init__(self)
        self.infile = infile
        self.outfile = outfile

    def run(self):
        f = zipfile.ZipFile(self.outfile, 'w', zipfile.ZIP_DEFLATED)
        f.write(self.infile)
        f.close()
        print('Finished background zip of:', self.infile)

background = AsyncZip('mydata.txt', 'myarchive.zip')
background.start()
print('The main program continues to run in foreground.')

background.join()    # Wait for the background task to finish
print('Main program waited until background was done.')

マルチスレッドアプリケーションを作る上で最も難しい問題は、データやリソースを共有するスレッド間の調整 (coordination)です。この問題を解決するため、threading モジュールではロックやイベント、状態変数、セマフォといった数々の同期プリミティブを提供しています。

こうしたツールは強力な一方、ちょっとした設計上の欠陥で再現困難な問題を引き起こすことがあります。したがって、タスク間調整では queue モジュールを使って他の複数のスレッドからのリクエストを一つのスレッドに送り込み、一つのリソースへのアクセスをできるだけ一つのスレッドに集中させるほうが良いでしょう。スレッド間の通信や調整に Queue オブジェクトを使うと、設計が容易になり、可読性が高まり、信頼性が増します。

11.5. ログ記録

logging モジュールでは、数多くの機能をそなえた柔軟性のあるログ記録システムを提供しています。最も簡単な使い方では、ログメッセージをファイルや sys.stderr に送信します:

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')

これは以下の出力を生成します:

WARNING:root:Warning:config file server.conf not found
ERROR:root:Error occurred
CRITICAL:root:Critical error -- shutting down

デフォルトでは、info() と debug() による出力は抑制され、出力は標準エラーに送信されます。選択可能な送信先には、email、データグラム、ソケット、HTTP サーバへの送信などがあります。新たにフィルタを作成すると、DEBUG、INFO、WARNING、ERROR、CRITICAL といったメッセージのプライオリティによって異なる送信先を選択することができます。

ログ記録システムは Python から直接設定することもできますし、アプリケーションを変更しなくてもカスタマイズできるよう、ユーザが編集可能な設定ファイルによって設定することもできます。

11.6. 弱参照

Python は自動的にメモリを管理します (ほとんどのオブジェクトは参照カウント方式で管理し、 ガベージコレクション で循環参照を除去します)。オブジェクトに対する最後の参照がなくなってしばらくするとメモリは解放されます。

このようなアプローチはほとんどのアプリケーションでうまく動作しますが、中にはオブジェクトをどこか別の場所で利用している間だけ追跡しておきたい場合もあります。残念ながら、オブジェクトを追跡するだけでオブジェクトに対する恒久的な参照を作ることになってしまいます。 weakref モジュールでは、オブジェクトへの参照を作らずに追跡するためのツールを提供しています。弱参照オブジェクトが不要になると、弱参照 (weakref) テーブルから自動的に除去され、コールバック関数がトリガされます。弱参照を使う典型的な応用例には、作成コストの大きいオブジェクトのキャッシュがあります:

>>> import weakref, gc
>>> class A:
...     def __init__(self, value):
...         self.value = value
...     def __repr__(self):
...         return str(self.value)
...
>>> a = A(10)                   # create a reference
>>> d = weakref.WeakValueDictionary()
>>> d['primary'] = a            # does not create a reference
>>> d['primary']                # fetch the object if it is still alive
10
>>> del a                       # remove the one reference
>>> gc.collect()                # run garbage collection right away
0
>>> d['primary']                # entry was automatically removed
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
    d['primary']                # entry was automatically removed
  File "C:/python312/lib/weakref.py", line 46, in __getitem__
    o = self.data[key]()
KeyError: 'primary'

11.7. リスト操作のためのツール

多くのデータ構造は、組み込みリスト型を使った実装で事足ります。とはいえ、時には組み込みリストとは違うパフォーマンス上のトレードオフを持つような実装が必要になこともあります。

array (配列) モジュールでは、array() オブジェクトを提供しています。配列はリストに似ていますが、同じ形式のデータだけが保存でき、よりコンパクトに保存されます。以下の例では、通常 1 要素あたり 16 バイトを必要とする Python 整数型のリストの 代りに、2 バイトの符号無しの 2 進数 (タイプコード "H") の配列を使っています:

>>> from array import array
>>> a = array('H', [4000, 10, 700, 22222])
>>> sum(a)
26932
>>> a[1:3]
array('H', [10, 700])

collections モジュールでは、deque() オブジェクトを提供しています。リスト型に似ていますが、データの追加と左端からの取り出しが速く、その一方で中間にある値の参照は遅くなります。こうしたオブジェクトはキューや木構造の幅優先探索の実装に向いています:

>>> from collections import deque
>>> d = deque(["task1", "task2", "task3"])
>>> d.append("task4")
>>> print("Handling", d.popleft())
Handling task1

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)

リストの代わりの実装以外にも、標準ライブラリにはソート済みのリストを操作するための関数を備えた bisect のようなツールも提供しています:

>>> 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')]

heapq モジュールは、通常のリストでヒープを実装するための関数を提供しています。ヒープでは、最も低い値をもつエントリがつねにゼロの位置に配置されます。ヒープは、毎回リストをソートすることなく、最小の値をもつ要素に繰り返しアクセスするようなアプリケーションで便利です:

>>> from heapq import heapify, heappop, heappush
>>> data = [1, 3, 5, 7, 9, 2, 4, 6, 8, 0]
>>> heapify(data)                      # rearrange the list into heap order
>>> heappush(data, -5)                 # add a new entry
>>> [heappop(data) for i in range(3)]  # fetch the three smallest entries
[-5, 0, 1]

11.8. 10 進浮動小数演算

decimal モジュールでは、 10 進浮動小数の算術演算をサポートする Decimal データ型を提供しています。組み込みの 2 進浮動小数の実装である float に比べて、このクラスがとりわけ便利なのは、以下の場合です

財務アプリケーションやその他の正確な10進表記が必要なアプリケーション、

精度の制御、

法的または規制上の理由に基づく値丸めの制御、

有効桁数の追跡が必要になる場合

ユーザが手計算の結果と同じ演算結果を期待するようなアプリケーション。

例えば、70 セントの電話代にかかる 5% の税金を計算しようとすると、10 進の浮動小数点値と 2 進の浮動小数点値では違う結果になってしまいます。計算結果を四捨五入してセント単位にしようとすると、以下のように違いがはっきり現れます:

>>> from decimal import *
>>> round(Decimal('0.70') * Decimal('1.05'), 2)
Decimal('0.74')
>>> round(.70 * 1.05, 2)
0.73

上の例で、Decimal を使った計算では、末尾桁のゼロが保存されており、有効数字2桁の被乗数から自動的に有効数字を 4 桁と判断しています。Decimal は手計算と 同じ方法で計算を行い、2 進浮動小数が 10 進小数成分を正確に表現できないことに よって起きる問題を回避しています。

Decimal クラスは厳密な値を表現できるため、2 進浮動小数点数では 期待通りに計算できないような剰余の計算や等値テストも実現できます:

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

decimal モジュールを使うと、必要なだけの精度で算術演算を行えます:

>>> getcontext().prec = 36
>>> Decimal(1) / Decimal(7)
Decimal('0.142857142857142857142857142857142857')

12. 仮想環境とパッケージ

12.1. はじめに

Python アプリケーションはよく標準ライブラリ以外のパッケージやモジュールを利用します。またアプリケーションがあるバグ修正を必要としていたり、過去のバージョンのインターフェイスに依存しているために、ライブラリの特定のバージョンを必要とすることもあります。

そのため、1つのインストールされたPythonが全てのアプリケーションの要求に対応することは不可能です。もしアプリケーションAがあるモジュールのバージョン 1.0 を要求していて、別のアプリケーションBが同じモジュールのバージョン 2.0 を要求している場合、2つの要求は衝突していて、1.0 と 2.0 のどちらかのバージョンをインストールしても片方のアプリケーションが動きません。

この問題の解決策は 仮想環境 を作ることです。仮想環境とは、特定のバージョンの Python と幾つかの追加パッケージを含んだ Python インストールを構成するディレクトリです。

別のアプリケーションはそれぞれ別の仮想環境を使うことができます。先の例にあった要求の衝突を解決する場合、アプリケーションAが固有の仮想環境を持ってそこにライブラリのバージョン 1.0 をインストールし、アプリケーションBが持つ別の仮想環境にライブラリのバージョン 2.0 をインストールすることができます。そしてアプリケーションBがライブラリのバージョンを 3.0 に更新することを要求する場合も、アプリケーションAに影響しません。

12.2. 仮想環境の作成

仮想環境の作成と管理を行うためのモジュールが venv です。 venv は通常利用可能なもっとも新しいバージョンの Python をインストールします。複数のバージョンの Python がインストールされている場合、 python3 のように利用したいバージョンを指定して実行することで Python バージョンを選択できます。

仮想環境を作るには、仮想環境を置くディレクトリを決めて、 そのディレクトリのパスを指定して、 venv をスクリプトとして実行します:

python -m venv tutorial-env

これは tutorial-env ディレクトリがなければ作成して、その中に Python インタプリタ、その他関連するファイルのコピーを含むサブディレクトリを作ります。

仮想環境の一般的なディレクトリの場所は .venv です。この名前は、通常はシェルで隠されているため、ディレクトリが存在する理由を説明する名前を付けても、邪魔にはなりません。また、一部のツールでサポートされている .env 環境変数定義ファイルによるクラッシュも防止します。

仮想環境を作ったら、それを有効化する必要があります。

Windows の場合:

tutorial-env\Scripts\activate

Unix や Mac OS の場合:

source tutorial-env/bin/activate

(このスクリプトは bash shell で書かれています。 csh や fish を利用している場合、代わりに利用できる activate.csh と activate.fish スクリプトがあります。)

仮想環境を有効化すると、シェルのプロンプトに利用中の仮想環境が表示されるようになり、python を実行するとその仮想環境の Python を実行するようになります:

$ source ~/envs/tutorial-env/bin/activate
(tutorial-env) $ python
Python 3.5.1 (default, May  6 2016, 10:59:36)
  ...
>>> import sys
>>> sys.path
['', '/usr/local/lib/python35.zip', ...,
'~/envs/tutorial-env/lib/python3.5/site-packages']
>>>

仮想環境を無効化するには、ターミナルに:

deactivate

と入力します。

12.3. pip を使ったパッケージ管理

　pip と呼ばれるプログラムでパッケージをインストール、アップグレード、削除することができます。デフォルトでは pip は Python Package Index [https://pypi.org] からパッケージをインストールします。ブラウザを使って Python Package Index を閲覧することができます。

pip は "install" 、 "uninstall" 、 "freeze" など、いくつかのサブコマンドを持っています。 (pip の完全なドキュメントは Python モジュールのインストール ガイドを参照してください。)

パッケージ名を指定してそのパッケージの最新版をインストールすることができます:

(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

パッケージ名のあとに == とバージョン番号を付けることで、特定のバージョンのパッケージをインストールすることもできます:

(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

同じコマンドを再び実行した場合、pip は要求されたバージョンがインストール済みだと表示して何もしません。別のバージョン番号を指定すればそのバージョンをインストールしますし、python -m pip install --upgrade を実行すればそのパッケージを最新版に更新します:

(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

python -m pip uninstall コマンドに削除するパッケージ名を1つ以上指定します。

python -m pip show は指定されたパッケージの情報を表示します:

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

python -m pip list は仮想環境にインストールされた全てのパッケージを表示します:

(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)

python -m pip freeze はインストールされたパッケージ一覧を、python -m pip install が解釈するフォーマットで生成します。一般的な慣習として、このリストを requirements.txt というファイルに保存します:

(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

requirements.txt をバージョン管理システムにコミットして、アプリケーションの一部として配布することができます。ユーザーは必要なパッケージを install -r でインストールできます:

(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

pip にはたくさんのオプションがあります。 pip の完全なドキュメントは Python モジュールのインストール を参照してください。パッケージを作成してそれを Python Package Index で公開したい場合、 Python packaging user guide [https://packaging.python.org/en/latest/tutorials/packaging-projects/] を参照してください。

13. さあ何を？

このチュートリアルを読んだことで、おそらく Python を使ってみようという関心はますます強くなったことでしょう --- 現実世界の問題を解決するために、Python を適用してみたくなったはずです。さて、それではどこで勉強をしたらよいのでしょうか？

このチュートリアルは Python のドキュメンテーションセットの一部です。セットの中の他のドキュメンテーションをいくつか紹介します:

Python 標準ライブラリ:

このマニュアルをざっと眺めておくと便利です。このマニュアルは型、関数、標準ライブラリのモジュールについての完全なリファレンスです。標準的なPython配布物は たくさんの 追加コードを含んでいます。Unix メールボックスの読み込み、HTTPによるドキュメント取得、乱数の生成、コマンドラインオプションの構文解析、データ圧縮やその他たくさんのタスクのためのモジュールがあります。ライブラリリファレンスをざっと見ることで、何が利用できるかのイメージをつかむことができます。

Python モジュールのインストール は、他のPythonユーザによって書かれた追加モジュールをどうやってインストールするかを説明しています。

Python 言語リファレンス: Pythonの文法とセマンティクスを詳しく説明しています。読むのは大変ですが、言語の完全なガイドとして有用です。

さらなる Python に関するリソース:

https://www.python.org: 有名なPythonのWebサイト。コードやドキュメント、Pythonに関するWebページへのポインターを含んでいます。

https://docs.python.org: Pythonドキュメントへの素早いアクセスを提供します。

https://pypi.org: Python パッケージインデックス、以前は Cheese Shop [1] という愛称でも呼ばれていました。これは、ユーザ作成のダウンロードできる Python モジュールの索引です。コードのリリースをしたら、ここに登録することで他の人が見つけられます。

https://code.activestate.com/recipes/langs/python/: Python クックブックはコード例、モジュール、実用的なスクリプトの巨大なコレクションです。主要なものは同名の本Python Cookbook (O'Reilly & Associates, ISBN 0-596-00797-3)に収録されています。

https://pyvideo.org は学会やユーザグループの会合から Python 関連のビデオのリンクを集めています。

https://scipy.org: Scientific Python プロジェクトは配列の高速な計算・操作モジュールに加え、線形代数、フーリエ変換、非線形ソルバー、乱数分布、統計分析などの多くのパッケージを提供しています。

Python 関連の質問や問題の報告については、ニュースグループ comp.lang.python に投稿するか、またはメーリングリスト python-list@python.org に送ることができます。ニュースグループとメーリングリストはゲートウェイされます。したがって、片方に投稿されたメッセージは、もう片方へ自動的に転送されます。質問(と回答)、新しい機能の提案、新しいモジュールの発表などで、1日に数百通の投稿があります。メーリングリストのアーカイブは https://mail.python.org/pipermail/ で利用可能です。

投稿の前に、必ず よくある質問 (FAQとも呼ばれます) のリストをチェックしてください。 FAQ は繰り返し取り上げられる多くの質問に答えています。あなたの問題に対する解決が既に含まれているかもしれません。

脚注

[1]

"Cheese Shop" は Monty Python のスケッチです: お客さんがチーズ屋に入ったけれど、彼が求めたチーズはどれも無いとclerkが言った。

14. 対話入力編集と履歴置換

いくつかのバージョンの Python インタプリタでは、Korn シェルや GNU Bash シェルに見られる機能に似た、現在の入力行に対する編集機能や履歴置換機能をサポートしています。この機能は様々な編集スタイルをサポートしている、GNU Readline [https://tiswww.case.edu/php/chet/readline/rltop.html] ライブラリを使って実装されています。このライブラリには独自のドキュメントがあり、ここでそれを繰り返すつもりはありません。

14.1. タブ補完と履歴編集

変数とモジュール名の補完はインタプリタの起動時に 自動的に有効化されます 。 従って Tab キーは補完機能を呼び出し、Python の文の名前、現在のローカル変数、および利用可能なモジュール名を検索します。 string.a のようなドットで区切られた式については、最後の '.' までの式を評価し、結果として得られたオブジェクトの属性から補完候補を示します。 __getattr__() メソッドを持ったオブジェクトが式に含まれている場合、 __getattr__() がアプリケーション定義のコードを実行するかもしれないので注意してください。デフォルトの設定ではあなたのユーザーディレクトリの .python_history という名前のファイルに履歴を保存します。 履歴は次回の対話的なインタプリタのセッションで再び利用することができます。

14.2. 対話的インタープリタの代替

この機能は、初期の版のインタープリタに比べれば大きな進歩です。とはいえ、まだいくつかの要望が残されています。例えば、行を継続するときに正しいインデントが提示されたら快適でしょう (パーサは次の行でインデントトークンが必要かどうかを知っています)。補完機構がインタープリタのシンボルテーブルを使ってもよいかもしれません。括弧やクォートなどの対応をチェックする (あるいは指示する) コマンドも有用でしょう。

より優れた対話的インタープリタの代替の一つに IPython [https://ipython.org/] があります。このインタープリタは、様々なところで使われていて、タブ補完、オブジェクト探索や先進的な履歴管理といった機能を持っています。他のアプリケーションにカスタマイズされたり、組込まれこともあります。別の優れたインタラクティブ環境としては bpython [https://bpython-interpreter.org/] があります。

15. 浮動小数点演算、その問題と制限

浮動小数点数はコンピューターのハードウェア上は2進数(binary)の分数で表されます。たとえば、10進数 の分数では 0.625 は 6/10 + 2/100 + 5/1000 という値を持ち、2進数 の分数では 0.101 は 1/2 + 0/4 + 1/8 という値を持ちます。この2つの分数はまったく同じ値を持ち、唯一異なる点は1つ目が10進数の分数で書かれており、2つ目は2進数の分数で書かれているということです。

残念なことに、ほとんどの小数は 2 進法の分数として正確に表わすことができません。その結果、一般に、入力した 10 進の浮動小数点数は、 2 進法の浮動小数点数で近似された後、実際にマシンに記憶されます。

最初は基数 10 を使うと問題を簡単に理解できます。分数 1/3 を考えてみましょう。分数 1/3 は、基数 10 の分数として、以下のように近似することができます:

0.3

さらに正確な近似は、

0.33

さらに正確な近似は、

0.333

となり、以後同様です。何個桁数を増やして書こうが、結果は決して厳密な 1/3 にはなりません。しかし、少しづつ正確な近似にはなっていくでしょう。

同様に、基数を 2 とした表現で何桁使おうとも、10 進数の 0.1 は基数を 2 とした小数で正確に表現することはできません。基数 2 では、1/10 は循環小数 (repeating fraction) となります

0.0001100110011001100110011001100110011001100110011...

どこか有限の桁で止めると、近似値を得ることになります。近年の殆どのコンピュータでは float 型は、最上位ビットから数えて最初の 53 ビットを分子、2 の冪乗を分母とした、二進小数で近似されます。1/10 の場合は、二進小数は 3602879701896397 / 2 ** 55 となります。これは、1/10 に近いですが、厳密に同じ値ではありません。

値が表示される方法のために、ほとんどのユーザは、近似に気づきません。Python はマシンに格納されている二進近似値の10進小数での近似値を表示するので、格納されている値が元の10進小数の近似値でしか無いことを忘れがちです。ほとんどのマシンで、もし Python が2進数で近似された 0.1 の近似値をそのまま10進数で表示していたら、その結果は次のようになったでしょう:

>>> 0.1
0.1000000000000000055511151231257827021181583404541015625

これは、ほとんどの人が必要と感じるよりも多すぎる桁数です。なので、Python は丸めた値を表示することで、桁数を扱いやすい範囲にとどめます:

>>> 1 / 10
0.1

表示された結果が正確に 1/10 であるように見えたとしても、実際に格納されている値は最も近く表現できる二進小数であるということだけは覚えておいてください。

幾つかの異なる10進数の値が、同じ2進有理数の近似値を共有しています。例えば、0.1 と 0.10000000000000001 と 0.1000000000000000055511151231257827021181583404541015625 はどれも 3602879701896397 / 2 ** 55 に近似されます。同じ近似値を共有しているので、どの10進数の値も eval(repr(x)) == x という条件を満たしたまま同じように表示されます。

昔の Python は、プロンプトと repr() ビルトイン関数は 17 桁の有効数字を持つ 0.10000000000000001 のような10進数の値を選んで表示していました。 Python 3.1 からは、ほとんどの場面で 0.1 のような最も短い桁数の10進数の値を選ぶようになりました。

この動作は2進数の浮動小数点にとってはごく自然なものです。これは Python のバグではありませんし、あなたのコードのバグでもありません。ハードウェアの浮動小数点演算をサポートしている全ての言語で同じ種類の問題を見つけることができます (いくつかの言語ではデフォルトの、あるいはどの出力モードを選んでも、この差を 表示 しないかもしれませんが)。

よりよい出力のために、文字列フォーマットを利用して有効桁数を制限した10進数表現を得ることができます:

>>> format(math.pi, '.12g')  # give 12 significant digits
'3.14159265359'

>>> format(math.pi, '.2f')   # give 2 digits after the point
'3.14'

>>> repr(math.pi)
'3.141592653589793'

これが、実際のコンピューター上の値の 表示 を丸めているだけの、いわば錯覚だということを認識しておいてください。

もう一つの錯覚を紹介します。例えば、0.1 が正確には 1/10 ではないために、それを3回足した値もまた正確には 0.3 ではありません:

>>> 0.1 + 0.1 + 0.1 == 0.3
False

0.1 はこれ以上 1/10 に近くなることができない値で、 0.3 もまた 3/10 に一番近い値なので、 round() 関数を使って計算前に丸めを行なっても意味がありません:

>>> round(0.1, 1) + round(0.1, 1) + round(0.1, 1) == round(0.3, 1)
False

数値を意図した正確な値に近づけることはできませんが、 math.isclose() 関数は不正確な値を比べるのに便利です:

>>> math.isclose(0.1 + 0.1 + 0.1, 0.3)
True

あるいは、 round() 関数を粗い近似値比較に使うこともできます:

>>> round(math.pi, ndigits=2) == round(22 / 7, ndigits=2)
True

このように2進数の浮動小数点の演算には多くの驚きがあります。「0.1」の問題について詳しい説明は、「表現エラー」セクションで行います。2進数の浮動小数点の仕組みと、実際によく遭遇する問題各種についての分かりやすい概要は、 Examples of Floating Point Problems [https://jvns.ca/blog/2023/01/13/examples-of-floating-point-problems/] を参照してください。その他よくある驚きの より詳細な説明は The Perils of Floating Point [http://www.indowsway.com/floatingpoint.htm] も参照してください。

究極的にいうと、"容易な答えはありません"。ですが、浮動小数点数のことを過度に警戒しないでください！ Python の float 型操作におけるエラーは浮動小数点処理ハードウェアから受けついたものであり、ほとんどのマシン上では一つの演算あたり高々 2**53 分の 1 です。この誤差はほとんどの作業で充分以上のものですが、浮動小数点演算は 10 進の演算ではなく、浮動小数点の演算を新たに行うと、新たな丸め誤差の影響を受けることを心にとどめておいてください。

異常なケースが存在する一方で、普段の浮動小数点演算の利用では、単に最終的な結果の値を必要な 10 進の桁数に丸めて表示するのなら、最終的には期待通りの結果を得ることになるでしょう。たいては str() で十分ですが、きめ細かな制御をしたければ、 書式指定文字列の文法 にある str.format() メソッドのフォーマット仕様を参照してください。

正確な10進数表現が必要となるような場合には、 decimal モジュールを利用してみてください。このモジュールは会計アプリケーションや高精度の計算が求められるアプリケーションに適した、10進数の計算を実装しています。

別の正確な計算方法として、 fractions モジュールが有理数に基づく計算を実装しています (1/3 のような数を正確に表すことができます)。

あなたが浮動小数点演算のヘビーユーザーなら、SciPy プロジェクトが提供している NumPy パッケージやその他の数学用パッケージを調べてみるべきです。 <https://scipy.org> を参照してください。

Python は 本当に float の正確な値が必要なレアケースに対応するためのツールを提供しています。 float.as_integer_ratio() メソッドは float の値を有理数として表現します:

>>> x = 3.14159
>>> x.as_integer_ratio()
(3537115888337719, 1125899906842624)

この分数は正確なので、元の値を完全に復元することができます:

>>> x == 3537115888337719 / 1125899906842624
True

float.hex() メソッドは float の値を16進数で表現します。この値もコンピューターが持っている正確な値を表現できます:

>>> x.hex()
'0x1.921f9f01b866ep+1'

この正確な16進数表現はもとの float 値を正確に復元するために使うことができます:

>>> x == float.fromhex('0x1.921f9f01b866ep+1')
True

この16進数表現は正確なので、値を (プラットフォームにも依存せず) バージョンの異なるPython 間でやり取りしたり、他のこのフォーマットをサポートした言語 (Java や C99 など) と正確にやり取りするのに利用することができます。

別の便利なツールとして、合計処理における精度のロスを緩和してくれる sum() 関数があります。これは累計加算中の丸めに拡張精度を使います。これにより、誤差が最終的な合計値に影響を与えるまで蓄積されなくなり、結果が改善されます:

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

math.fsum() はさらに進んで、累計の加算時に「失われた桁」をすべて追跡し、結果の丸めは一度だけです。これは sum() より遅いものの、大きな入力がほとんど相殺され、最終的な合計がゼロに近くなるような珍しいケースでは、より正確です:

>>> arr = [-0.10430216751806065, -266310978.67179024, 143401161448607.16,
...        -143401161400469.7, 266262841.31058735, -0.003244936839808227]
>>> float(sum(map(Fraction, arr)))   # Exact summation with single rounding
8.042173697819788e-13
>>> math.fsum(arr)                   # Single rounding
8.042173697819788e-13
>>> sum(arr)                         # Multiple roundings in extended precision
8.042178034628478e-13
>>> total = 0.0
>>> for x in arr:
...     total += x                   # Multiple roundings in standard precision
...
>>> total                            # Straight addition has no correct digits!
-0.0051575902860057365

15.1. 表現エラー

この章では、"0.1" の例について詳細に説明し、このようなケースに対してどのようにすれば正確な分析を自分で行えるかを示します。ここでは、 2 進法表現の浮動小数点数についての基礎的な知識があるものとして話を進めます。

表現エラー(Representation error)は、いくつかの (実際にはほとんどの) 10 進の小数が 2 進法 (基数 2)の分数として表現できないという事実に関係しています。これは Python (あるいは Perl, C, C++, Java, Fortran. およびその他多く) が期待通りの正確な 10 進数を表示できない主要な理由です。

なぜそうなるのでしょう？ 1/10 は２進法の小数で厳密に表現できません。少なくとも2000年以降、ほぼすべてのマシンは IEEE 754 2進数の浮動小数点演算を用いており、ほぼすべてのプラットフォームでは Python の浮動小数点を IEEE 754 binary64 "倍精度 (double precision)" 値に対応付けます。 IEEE 754 binary64 値は 53 ビットの精度を持つため、計算機に入力を行おうとすると、可能な限り 0.1 を最も近い値の分数に変換し、J/2**N の形式にしようと努力します。J はちょうど 53 ビットの精度の整数です。

1 / 10 ~= J / (2**N)

を書き直すと

J ~= 2**N / 10

となります。 J は厳密に 53 ビットの精度を持っている (>= 2**52 だが < 2**53 ) ことを思い出すと、 N として最適な値は 56 になります:

>>> 2**52 <=  2**56 // 10  < 2**53
True

すなわち、56 は J をちょうど 53 ビットの精度のままに保つ N の唯一の値です。J の取りえる値はその商を丸めたものです:

>>> q, r = divmod(2**56, 10)
>>> r
6

剰余が 10 の半分以上なので、最良の近似は切り上げて丸めたものになります。:

>>> q+1
7205759403792794

従って、IEEE 754の倍精度における 1/10 の取りえる最良の近似は:

7205759403792794 / 2 ** 56

分子と分母を2で割って分数を小さくします:

3602879701896397 / 2 ** 55

丸めたときに切り上げたので、この値は実際には 1/10 より少し大きいことに注目してください。もし切り捨てをした場合は、商は 1/10 よりもわずかに小さくなります。どちらにしろ 厳密な 1/10 ではありません！

つまり、計算機は 1/10 を "理解する" ことは決してありません。計算機が理解できるのは、上記のような厳密な分数であり、IEEE 754 の倍精度浮動小数点数で得られるもっともよい近似は以下になります:

>>> 0.1 * 2 ** 55
3602879701896397.0

この分数に 10**55 を掛ければ、55 桁の十進数の値を見ることができます:

>>> 3602879701896397 * 10 ** 55 // 2 ** 55
1000000000000000055511151231257827021181583404541015625

これは、計算機が記憶している正確な数値が、10 進数値 0.1000000000000000055511151231257827021181583404541015625 にほぼ等しいということです。多くの言語 (古いバージョンの Python を含む) では、完全な 10 進値を表示するのではなく、結果を有効数字 17 桁に丸めます:

>>> format(0.1, '.17f')
'0.10000000000000001'

fractions モジュールと decimal モジュールを使うとこれらの計算を簡単に行えます:

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

16. 付録

16.1. 対話モード

16.1.1. エラー処理

エラーが発生すると、インタープリタはエラーメッセージとスタックトレースを表示します。対話モードでは、それから元のプロンプトに戻ります; ファイルから実行した場合は、スタックトレースを表示してゼロ以外の終了ステータスで終了します（try 文の except 節で処理された例外は、ここでいうエラーにはあたりません。）一部のエラーは無条件に致命的であり、ゼロ以外の終了ステータスで終了します; これは内部の不整合やある種のメモリ不足の場合に適用されます。エラーメッセージは全て標準エラー出力に書き込まれます; これに対して、通常は実行した命令から出力される内容は標準出力に書き込まれます。

割り込み文字 (interrupt character、普通は Control-C か Delete) を一次または二次プロンプトに対してタイプすると、入力が取り消されて一次プロンプトに戻ります。 [1] コマンドの実行中に割り込み文字をタイプすると KeyboardInterrupt 例外が送出されます。この例外は try 文で処理できます。

16.1.2. 実行可能な Python スクリプト

BSD 風の Unix システムでは、Python スクリプトはシェルスクリプトのように直接実行可能にできます。これを行うには、以下の行

#!/usr/bin/env python3

(ここではインタプリタがユーザの PATH 上にあると仮定しています) をスクリプトの先頭に置き、スクリプトファイルに実行可能モードを設定します。 #! はファイルの最初の２文字でなければなりません。プラットフォームによっては、この最初の行を終端する改行文字が Windows 形式 ('\r\n') ではなく、 Unix形式('\n')でなければならないことがあります。ハッシュまたはポンド文字、すなわち '#' は、Python ではコメントを書き始めるために使われていることに注意してください。

chmod コマンドを使えば、スクリプトに実行モードや実行権限を与えることができます。

$ chmod +x myscript.py

Windows では、"実行モード" のような概念はありません。Python のインストーラーは自動的に .py ファイルを python.exe に関連付けるので、Python ファイルをダブルクリックするとそれをスクリプトとして実行します。.pyw 拡張子も(訳注: pythonw.exe に)関連付けられ、通常コンソールウィンドウを抑制して実行します。

16.1.3. 対話モード用の起動時実行ファイル

Python を対話的に使うときには、インタプリタが起動する度に実行される何らかの標準的なコマンドがあると便利なことがよくあります。これを行うには、 PYTHONSTARTUP と呼ばれる環境変数を、インタプリタ起動時に実行されるコマンドが入ったファイル名に設定します。この機能は Unix シェルの .profile に似ています。

このファイルは対話セッションのときだけ読み出されます。 Python がコマンドをスクリプトから読み出しているときや、 /dev/tty がコマンドの入力元として明示的に指定されている(この場合対話的セッションのように動作します) わけではない 場合にはこのファイルは読み出されません。ファイル内のコマンドは、対話的コマンドが実行される名前空間と同じ名前空間内で実行されます。このため、ファイル内で定義されていたり import されたオブジェクトは、そのまま対話セッション内で使うことができます。また、このファイル内で sys.ps1 や sys.ps2 を変更して、プロンプトを変更することもできます。

もし現在のディレクトリから追加でスタートアップファイルを読み出したいのなら、グローバルのスタートアップファイルの中に if os.path.isfile('.pythonrc.py'): exec(open('.pythonrc.py').read()) のようなプログラムを書くことができます。スクリプト中でスタートアップファイルを使いたいのなら、以下のようにしてスクリプト中で明示的に実行しなければなりません:

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)

16.1.4. カスタマイズ用モジュール

Python はユーザーが Python をカスタマイズするための2つのフック、 sitecustomize と usercustomize を提供しています。これがどのように動作しているかを知るには、まずはユーザーの site-packages ディレクトリの場所を見つける必要があります。Python を起動して次のコードを実行してください:

>>> import site
>>> site.getusersitepackages()
'/home/user/.local/lib/python3.x/site-packages'

usercustomize.py をそのディレクトリに作成して、そこでやりたいことをすべて書くことができます。このファイルは自動インポートを無効にする -s オプションを使わない限り、全ての Python の起動時に実行されます。

sitecustomize モジュールも同じように動作しますが、一般的にコンピューターの管理者によって、グローバルの site-packages ディレクトリに作成され、 usercustomize より先にインポートされます。詳細は site モジュールのドキュメントを参照してください。

脚注

[1]

GNU Readline パッケージに関する問題のせいで妨げられることがあります。

Python のセットアップと利用

このドキュメントでは 異なるプラットフォームでのPython環境のセットアップの一般的な方法、インタプリタの起動とPythonでの作業を楽にする方法を説明します。

1. コマンドラインと環境

1.1. コマンドライン

1.1.1. インターフェイスオプション

1.1.2. 一般オプション

1.1.3. その他のオプション

1.1.4. 使うべきでないオプション

1.2. 環境変数

1.2.1. デバッグモード変数

2. Unix プラットフォームで Python を使う

2.1. 最新バージョンの Python の取得とインストール

2.1.1. Linux

2.1.2. FreeBSD と OpenBSD

2.2. Python のビルド

2.3. Python に関係するパスとファイル

2.4. その他

2.5. Custom OpenSSL

3. Python を構成する

3.1. Build Requirements

3.2. 生成されるファイル

3.2.1. 構成スクリプト

3.3. Configureオプション

3.3.1. 一般的なオプション

3.3.2. WebAssembly オプション

3.3.3. インストールオプション

3.3.4. パフォーマンスに関するオプション

3.3.5. Python Debug Build

3.3.6. Debug options

3.3.7. Linker options

3.3.8. Libraries options

3.3.9. Security Options

3.3.10. macOS のオプション

3.3.11. クロスコンパイルのオプション

3.4. Python Build System

3.4.1. Main files of the build system

3.4.2. Main build steps

3.4.3. Main Makefile targets

3.4.4. C extensions

3.5. Compiler and linker flags

3.5.1. Preprocessor flags

3.5.2. Compiler flags

3.5.3. Linker flags

4. Windows で Python を使う

4.1. 完全版インストーラ

4.1.1. インストール手順

4.1.2. MAX_PATH の制限を除去する

4.1.3. インストーラの GUI なしでインストールする

4.1.4. ダウンロード不要なインストール

4.1.5. インストール後の変更

4.2. Microsoft ストアパッケージ

4.2.1. 既知の問題

4.2.1.1. Redirection of local data, registry, and temporary paths

4.3. nuget.org パッケージ

4.4. 埋め込み可能なパッケージ

4.4.1. Python アプリケーション

4.4.2. Python の埋め込み

4.5. 別のバンドル

4.6. Python を構成する

4.6.1. 補足: 環境変数の設定

4.6.2. Python 実行ファイルを見つける

4.7. UTF-8 モード

4.8. Windows の Python ランチャ

4.8.1. 最初に

4.8.1.1. コマンドラインから起動する

4.8.1.2. 仮想環境 (Virtual environments)

4.8.1.3. スクリプトから起動する

4.8.1.4. ファイルの関連付けから起動する

4.8.2. シェバン (shebang) 行

4.8.3. シェバン行の引数

4.8.4. カスタマイズ

4.8.4.1. INI ファイルによるカスタマイズ

4.8.4.2. デフォルトのPythonバージョンのカスタマイズ

4.8.5. 診断

4.8.6. Dry Run

4.8.7. Install on demand

4.8.8. Return codes

4.9. モジュールの検索

4.10. 追加のモジュール

4.10.1. PyWin32

4.10.2. cx_Freeze

4.11. Windows 上で Python をコンパイルする

4.12. ほかのプラットフォーム

5. Mac で Python を使う

5.1. Getting and Installing Python

5.1.1. Python スクリプトの実行方法

5.1.2. GUI でスクリプトを実行

5.1.3. Configuration

5.2. IDE

5.3. 追加の Python パッケージのインストール

5.4. GUI プログラミング

5.5. Distributing Python Applications

5.6. 他のリソース

6. エディタと IDE

1. コマンドラインと環境

CPython インタプリタはコマンドラインと環境を読み取って様々な設定を行ないます。

CPython 実装の詳細: 他の実装のコマンドラインスキームは CPython とは異なります。さらなる情報は 別のPythonの実装 を参照してください。

1.1. コマンドライン

Python を起動するとき、以下のうち任意のオプションを指定できます:

python [-bBdEhiIOqsSuvVWx?] [-c command | -m module-name | script | - ] [args]

もちろん、もっとも一般的な利用方法は、単純にスクリプトを起動することです:

python myscript.py

1.1.1. インターフェイスオプション

インタプリタのインターフェイスは UNIX シェルのものに似ていますが、より多くの起動方法を提供しています:

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 Ctrl-D on UNIX or Ctrl-Z, Enter on Windows) is read.

ファイル名引数か、標準入力としてファイルを渡された場合、そのファイルからスクリプトを読み込んで実行します。

ディレクトリ名を引数に受け取った場合、そのディレクトリから適切な名前のスクリプトファイルを読み込んで実行します。

-c コマンド オプションを利用して起動された場合、 コマンド として渡された Python の文を実行します。 コマンド の部分には改行で区切られた複数行を指定することもできます。行の先頭の空白文字は Python 文の重要要素です！

-m モジュール名 として Python モジュールパスにあるモジュールを指定された場合、そのモジュールをスクリプトとして実行します。

非インタラクティブモードでは、入力の全体が実行前にパースされます。

インタプリタによって消費されるオプションリストが終了したあと、継続する全ての引数は sys.argv に渡ります。 -- ただし、添字 0 の先頭要素(sys.argv[0]) はプログラムのソース自体を示す文字列です。

-c <command>

command 内の Python コードを実行します。 command は改行によって区切られた1行以上の文です。通常のモジュールのコードと同じく、行頭の空白文字は意味を持ちます。

このオプションが指定された場合、 sys.argv の最初の要素は "-c" になり、カレントディレクトリが sys.path の先頭に追加されます (そのディレクトリにあるモジュールをトップレベルモジュールとして import 出来るようになります)。

引数 command を指定して 監査イベント cpython.run_command を送出します。

-m <module-name>

sys.path から指定されたモジュール名のモジュールを探し、その内容を __main__ モジュールとして実行します。

引数は module 名なので、拡張子 (.py) を含めてはいけません。モジュール名は有効な Python の絶対モジュール名 (absolute module name) であるべきですが、実装がそれを強制しているとは限りません (例えば、ハイフンを名前に含める事を許可するかもしれません)。

パッケージ名 (名前空間パッケージも含む) でも構いません。通常のモジュールの代わりにパッケージ名が与えられた場合、インタプリタは <pkg>.__main__ を main モジュールとして実行します。この挙動はスクリプト引数として渡されたディレクトリや zip ファイルをインタプリタが処理するのと意図的に同じにしています。

注釈

このオプションは組み込みモジュールや C で書かれた拡張モジュールには利用できません。 Python モジュールファイルを持っていないからです。しかし、コンパイル済みのモジュールは、たとえ元のソースファイルがなくても利用可能です。

このオプションが指定された場合、 sys.argv の最初の要素はモジュールファイルのフルパスになります (モジュールファイルを検索している間、最初の要素は "-m" に設定されます)。 -c オプションと同様に、カレントディレクトリが sys.path の先頭に追加されます。

-I option can be used to run the script in isolated mode where sys.path contains neither the current directory nor the user's site-packages directory. All PYTHON* environment variables are ignored, too.

多くの標準ライブラリモジュールにはスクリプトとして実行された時のためのコードがあります。例えば、 timeit モジュールは次のように実行可能です:

python -m timeit -s "setup here" "benchmarked code here"
python -m timeit -h # for details

引数 module-name を指定して 監査イベント cpython.run_module を送出します。

参考

runpy.run_module()

Python コードで直接使える等価な機能

PEP 338 [https://peps.python.org/pep-0338/] - モジュールをスクリプトとして実行する

バージョン 3.1 で変更: __main__ サブモジュールを実行するパッケージ名が提供されました。

バージョン 3.4 で変更: 名前空間パッケージもサポートされました

-

標準入力 (sys.stdin) からコマンドを読み込みます。標準入力がターミナルだった場合、暗黙的に -i オプションが指定されます。

このオプションが指定された場合、 sys.argv の最初の要素は "-" で、カレントディレクトリが sys.path の先頭に追加されます。

引数無しで 監査イベント cpython.run_stdin を送出します。

<script>

script 内の Python コードを実行します。 script は、Python ファイル、 __main__.py ファイルがあるディレクトリ、 __main__.py ファイルがある zip ファイルのいずれかの、ファイルシステム上の (絶対または相対) パスでなければなりません。

このオプションが指定された場合、 sys.argv の最初の要素はコマンドラインで指定されたスクリプト名になります。

スクリプト名が Python ファイルを直接指定していた場合、そのファイルを含むディレクトリが sys.path の先頭に追加され、そのファイルは __main__ モジュールとして実行されます。

スクリプト名がディレクトリか zip ファイルを指定していた場合、スクリプト名が sys.path に追加され、その中の __main__.py ファイルが __main__ モジュールとして実行されます。

-I option can be used to run the script in isolated mode where sys.path contains neither the script's directory nor the user's site-packages directory. All PYTHON* environment variables are ignored, too.

引数 filename を指定して 監査イベント cpython.run_file を送出します。

参考

runpy.run_path()

Python コードで直接使える等価な機能

インターフェイスオプションが与えられなかった場合、-i が暗黙的に指定され、sys.argv[0] が空の文字列 ("") になり、 現在のディレクトリが sys.path の先頭に追加されます。また、利用可能であればタブ補完と履歴編集が自動的に有効かされます (readline の設定 を参照してください)。

参考

インタプリタを起動する

バージョン 3.4 で変更: タブ補完と履歴の編集が自動的に有効化されます。

1.1.2. 一般オプション

-?

-h

--help

Print a short description of all command line options and corresponding environment variables and exit.

--help-env

Print a short description of Python-specific environment variables and exit.

Added in version 3.11.

--help-xoptions

Print a description of implementation-specific -X options and exit.

Added in version 3.11.

--help-all

Print complete usage information and exit.

Added in version 3.11.

-V

--version

Python のバージョン番号を表示して終了します。出力の例:

Python 3.8.0b2+

2つ指定すると、次のようにより多くのビルドの情報を表示します:

Python 3.8.0b2+ (3.8:0c076caaa8, Apr 20 2019, 21:55:00)
[GCC 6.2.0 20161005]

Added in version 3.6: -VV オプション。

1.1.3. その他のオプション

-b

Issue a warning when converting bytes or bytearray to str without specifying encoding or comparing bytes or bytearray with str or bytes with int. Issue an error when the option is given twice (-bb).

バージョン 3.5 で変更: Affects also comparisons of bytes with int.

-B

与えられた場合、Python はソースモジュールのインポート時に .pyc ファイルの作成を試みません。 PYTHONDONTWRITEBYTECODE 環境変数も参照してください。

--check-hash-based-pycs default|always|never

Control the validation behavior of hash-based .pyc files. See キャッシュされたバイトコードの無効化. When set to default, checked and unchecked hash-based bytecode cache files are validated according to their default semantics. When set to always, all hash-based .pyc files, whether checked or unchecked, are validated against their corresponding source file. When set to never, hash-based .pyc files are not validated against their corresponding source files.

The semantics of timestamp-based .pyc files are unaffected by this option.

-d

Turn on parser debugging output (for expert only). See also the PYTHONDEBUG environment variable.

This option requires a debug build of Python, otherwise it's ignored.

-E

Ignore all PYTHON* environment variables, e.g. PYTHONPATH and PYTHONHOME, that might be set.

See also the -P and -I (isolated) options.

-i

最初の引数にスクリプトが指定された場合や -c オプションが利用された場合、 sys.stdin がターミナルに出力されない場合も含めて、スクリプトかコマンドを実行した後にインタラクティブモードに入ります。 PYTHONSTARTUP ファイルは読み込みません。

このオプションはグローバル変数や、スクリプトが例外を発生させるときにそのスタックトレースを調べるのに便利です。 PYTHONINSPECT も参照してください。

-I

Python を隔離モードで実行します。-E、-P、および -s オプションも暗黙的に指定されます。

In isolated mode sys.path contains neither the script's directory nor the user's site-packages directory. All PYTHON* environment variables are ignored, too. Further restrictions may be imposed to prevent the user from injecting malicious code.

Added in version 3.4.

-O

Remove assert statements and any code conditional on the value of __debug__. Augment the filename for compiled (bytecode) files by adding .opt-1 before the .pyc extension (see PEP 488 [https://peps.python.org/pep-0488/]). See also PYTHONOPTIMIZE.

バージョン 3.5 で変更: PEP 488 [https://peps.python.org/pep-0488/] に従って .pyc ファイル名を変更します。

-OO

Do -O and also discard docstrings. Augment the filename for compiled (bytecode) files by adding .opt-2 before the .pyc extension (see PEP 488 [https://peps.python.org/pep-0488/]).

バージョン 3.5 で変更: PEP 488 [https://peps.python.org/pep-0488/] に従って .pyc ファイル名を変更します。

-P

Don't prepend a potentially unsafe path to sys.path:

python -m module command line: Don't prepend the current working directory.

python script.py command line: Don't prepend the script's directory. If it's a symbolic link, resolve symbolic links.

python -c code and python (REPL) command lines: Don't prepend an empty string, which means the current working directory.

See also the PYTHONSAFEPATH environment variable, and -E and -I (isolated) options.

Added in version 3.11.

-q

インタラクティブモードでも copyright とバージョンのメッセージを表示しません。

Added in version 3.2.

-R

Turn on hash randomization. This option only has an effect if the PYTHONHASHSEED environment variable is set to 0, since hash randomization is enabled by default.

On previous versions of Python, this option turns on hash randomization, so that the __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²) complexity. See http://ocert.org/advisories/ocert-2011-003.html for details.

PYTHONHASHSEED によってハッシュシードの固定値を秘密にすることが出来ます。

Added in version 3.2.3.

バージョン 3.7 で変更: このオプションが無視されなくなりました.

-s

ユーザのサイトパッケージのディレクトリ を sys.path に追加しません。

See also PYTHONNOUSERSITE.

参考

PEP 370 [https://peps.python.org/pep-0370/] -- ユーザごとの site-packages ディレクトリ

-S

site モジュールの import と、そのモジュールが行なっていた site ごとの sys.path への操作を無効にします。後で site を明示的に import しても、これらの操作は実行されません (実行したい場合は、 site.main() を呼び出してください)。

-u

Force the stdout and stderr streams to be unbuffered. This option has no effect on the stdin stream.

PYTHONUNBUFFERED も参照してください。

バージョン 3.7 で変更: The text layer of the stdout and stderr streams now is unbuffered.

-v

モジュールが初期化されるたびにメッセージを出力し、それがどこ (ファイル名やビルトインモジュール) からロードされたのかを表示します。二回与えられた場合 (-vv) は、モジュールを検索するときにチェックしたファイルごとにメッセージを出力します。また、終了時のモジュールクリーンアップに関する情報も提供します。

バージョン 3.10 で変更: The site module reports the site-specific paths and .pth files being processed.

PYTHONVERBOSE も参照してください。

-W arg

警告制御。 Python の警告機構はデフォルトでは警告メッセージを 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):

-Wdefault  # Warn once per call location
-Werror    # Convert to exceptions
-Walways   # Warn every time
-Wmodule   # Warn once per calling module
-Wonce     # Warn once per Python process
-Wignore   # Never warn

The action names can be abbreviated as desired and the interpreter will resolve them to the appropriate action name. For example, -Wi is the same as -Wignore.

引数の完全形は次のようになります:

action:message:category:module:lineno

Empty fields match all values; trailing empty fields may be omitted. For example -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: 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.

複数の -W オプションを指定することができます。警告が1つ以上のオプションとマッチしたときは、最後にマッチしたオプションのアクションが有効になります。不正な -W オプションは無視されます (最初の警告が発生したときに、不正なオプションに対する警告メッセージが表示されます)。

Warnings can also be controlled using the PYTHONWARNINGS environment variable and from within a Python program using the warnings module. For example, the warnings.filterwarnings() function can be used to use a regular expression on the warning message.

詳しくは 警告フィルタ と Describing Warning Filters を参照してください。

-x

Unix 以外の形式の #!cmd を使うために、ソースの最初の行をスキップします。これは、DOS専用のハックのみを目的としています。

-X

様々な実装固有のオプションのために予約されています。現在のところ CPython は以下の値を定義しています:

-X faulthandler to enable faulthandler. See also PYTHONFAULTHANDLER.

Added in version 3.3.

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

Added in version 3.4.

-X tracemalloc to start tracing Python memory allocations using the tracemalloc module. By default, only the most recent frame is stored in a traceback of a trace. Use -X tracemalloc=NFRAME to start tracing with a traceback limit of NFRAME frames. See tracemalloc.start() and PYTHONTRACEMALLOC for more information.

Added in version 3.4.

-X int_max_str_digits configures the integer string conversion length limitation. See also PYTHONINTMAXSTRDIGITS.

Added in version 3.11.

-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 python3 -X importtime -c 'import asyncio'. See also PYTHONPROFILEIMPORTTIME.

Added in version 3.7.

-X dev: enable Python Development Mode, introducing additional runtime checks that are too expensive to be enabled by default. See also PYTHONDEVMODE.

Added in version 3.7.

-X utf8 enables the Python UTF-8 Mode. -X utf8=0 explicitly disables Python UTF-8 Mode (even when it would otherwise activate automatically). See also PYTHONUTF8.

Added in version 3.7.

-X pycache_prefix=PATH enables writing .pyc files to a parallel tree rooted at the given directory instead of to the code tree. See also PYTHONPYCACHEPREFIX.

Added in version 3.8.

-X warn_default_encoding issues a EncodingWarning when the locale-specific default encoding is used for opening files. See also PYTHONWARNDEFAULTENCODING.

Added in version 3.10.

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

Added in version 3.11.

-X frozen_modules determines whether or not frozen modules are ignored by the import machinery. A value of "on" means they get imported and "off" means they are ignored. The default is "on" if this is an installed Python (the normal case). If it's under development (running from the source tree) then the default is "off". Note that the "importlib_bootstrap" and "importlib_bootstrap_external" frozen modules are always used, even if this flag is set to "off".

Added in version 3.11.

-X perf enables support for the Linux perf profiler. When this option is provided, the 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 PYTHONPERFSUPPORT and Python support for the Linux perf profiler.

Added in version 3.12.

任意の値を渡し、 sys._xoptions 辞書から取り出すことも出来ます。

Added in version 3.2.

バージョン 3.9 で変更: Removed the -X showalloccount option.

バージョン 3.10 で変更: Removed the -X oldparser option.

1.1.4. 使うべきでないオプション

-J

Jython [https://www.jython.org/] のために予約されています。

1.2. 環境変数

以下の環境変数は Python の挙動に影響します。環境変数は -E や -I 以外のコマンドラインスイッチの前に処理されます。衝突したときにコマンドラインスイッチが環境変数をオーバーライドするのは慣例です。

PYTHONHOME

標準 Python ライブラリの場所を変更します。デフォルトでは、ライブラリは prefix/lib/pythonversion と exec_prefix/lib/pythonversion から検索されます。ここで、 prefix と exec_prefix はインストール依存のディレクトリで、両方共デフォルトでは /usr/local です。

PYTHONHOME が1つのディレクトリに設定されている場合、その値は prefix と exec_prefix の両方を置き換えます。それらに別々の値を指定したい場合は、 PYTHONHOME を prefix:exec_prefix のように指定します。

PYTHONPATH

モジュールファイルのデフォルトの検索パスを追加します。この環境変数のフォーマットはシェルの PATH と同じで、 os.pathsep (Unix ならコロン、 Windows ならセミコロン) で区切られた1つ以上のディレクトリパスです。存在しないディレクトリは警告なしに無視されます。

通常のディレクトリに加えて、 PYTHONPATH のエントリはピュアPython モジュール(ソース形式でもコンパイルされた形式でも) を含む zip ファイルを参照することもできます。拡張モジュールは zip ファイルの中から import することはできません。

デフォルトの検索パスはインストール依存ですが、通常は prefix/lib/pythonversion で始まります。 (上の PYTHONHOME を参照してください。) これは 常に PYTHONPATH に追加されます。

上の インターフェイスオプション で説明されているように、追加の検索パスディレクトリが PYTHONPATH の手前に追加されます。検索パスは Python プログラムから sys.path 変数として操作することができます。

PYTHONSAFEPATH

If this is set to a non-empty string, don't prepend a potentially unsafe path to sys.path: see the -P option for details.

Added in version 3.11.

PYTHONPLATLIBDIR

If this is set to a non-empty string, it overrides the sys.platlibdir value.

Added in version 3.9.

PYTHONSTARTUP

この変数が読み込み可能なファイル名の場合、対話モードで最初のプロンプトが表示される前にそのファイルの Python コマンドが実行されます。ファイル内で定義されているオブジェクトやインポートされたオブジェクトを対話セッションで修飾せずに使用するために、ファイルは対話的なコマンドと同じ名前空間で実行されます。このファイルの中で、プロンプト sys.ps1 や sys.ps2、ならびにフック sys.__interactivehook__ も変更できます。

引数 filename を指定して 監査イベント cpython.run_startup を送出します。

PYTHONOPTIMIZE

この変数に空でない文字列を設定するのは -O オプションを指定するのと等価です。整数を設定した場合、 -O を複数回指定したのと同じになります。

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 sys.breakpointhook() which itself is called by built-in 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 sys.breakpointhook() to do nothing but return immediately.

Added in version 3.7.

PYTHONDEBUG

この変数に空でない文字列を設定するのは -d オプションを指定するのと等価です。整数を指定した場合、 -d を複数回指定したのと同じになります。

This environment variable requires a debug build of Python, otherwise it's ignored.

PYTHONINSPECT

この変数に空でない文字列を設定するのは -i オプションを指定するのと等価です。

この変数は Python コードから os.environ を使って変更して、プログラム終了時のインスペクトモードを強制することができます。

PYTHONUNBUFFERED

この変数に空でない文字列を設定するのは -u オプションを指定するのと等価です。

PYTHONVERBOSE

この変数に空でない文字列を設定するのは -v オプションを指定するのと等価です。整数を設定した場合、 -v を複数回指定したのと同じになります。

PYTHONCASEOK

この環境変数が設定されている場合、 Python は import 文で大文字/小文字を区別しません。 これは Windows と macOS でのみ動作します。

PYTHONDONTWRITEBYTECODE

この変数に空でない文字列を設定した場合、 Python はソースモジュールのインポート時に .pyc ファイルを作成しようとはしなくなります。 -B オプションを指定するのと等価です。

PYTHONPYCACHEPREFIX

If this is set, Python will write .pyc files in a mirror directory tree at this path, instead of in __pycache__ directories within the source tree. This is equivalent to specifying the -X pycache_prefix=PATH option.

Added in version 3.8.

PYTHONHASHSEED

この変数が設定されていない場合や random に設定された場合、乱数値が str、bytes オブジェクトのハッシュのシードに使われます。

PYTHONHASHSEED が整数値に設定された場合、その値はハッシュランダム化が扱う型の hash() 生成の固定シードに使われます。

その目的は再現性のあるハッシュを可能にすることです。例えばインタープリタ自身の自己テストや Python プロセスのクラスタでハッシュ値を共有するのに用います。

整数は [0,4294967295] の十進数でなければなりません。0 を指定するとハッシュランダム化は無効化されます。

Added in version 3.2.3.

PYTHONINTMAXSTRDIGITS

If this variable is set to an integer, it is used to configure the interpreter's global integer string conversion length limitation.

Added in version 3.11.

PYTHONIOENCODING

この変数がインタープリタ実行前に設定されていた場合、encodingname:errorhandler という文法で標準入力/標準出力/標準エラー出力のエンコードを上書きします。 encodingname と :errorhandler の部分はどちらも任意で、str.encode() と同じ意味を持ちます。

標準エラー出力の場合、:errorhandler の部分は無視されます; ハンドラは常に 'backslashreplace' です。

バージョン 3.4 で変更: encodingname の部分が任意になりました。

バージョン 3.6 で変更: On Windows, the encoding specified by this variable is ignored for interactive console buffers unless PYTHONLEGACYWINDOWSSTDIO is also specified. Files and pipes redirected through the standard streams are not affected.

PYTHONNOUSERSITE

この環境変数が設定されている場合、 Python は ユーザ site-packages ディレクトリ を sys.path に追加しません。

参考

PEP 370 [https://peps.python.org/pep-0370/] -- ユーザごとの site-packages ディレクトリ

PYTHONUSERBASE

Defines the user base directory, which is used to compute the path of the user site-packages directory and installation paths for python -m pip install --user.

参考

PEP 370 [https://peps.python.org/pep-0370/] -- ユーザごとの site-packages ディレクトリ

PYTHONEXECUTABLE

この環境変数が設定された場合、 sys.argv[0] に、C ランタイムから取得した値の代わりにこの環境変数の値が設定されます。macOS でのみ動作します。

PYTHONWARNINGS

This is equivalent to the -W option. If set to a comma separated string, it is equivalent to specifying -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):

PYTHONWARNINGS=default  # Warn once per call location
PYTHONWARNINGS=error    # Convert to exceptions
PYTHONWARNINGS=always   # Warn every time
PYTHONWARNINGS=module   # Warn once per calling module
PYTHONWARNINGS=once     # Warn once per Python process
PYTHONWARNINGS=ignore   # Never warn

詳しくは 警告フィルタ と Describing Warning Filters を参照してください。

PYTHONFAULTHANDLER

If this environment variable is set to a non-empty string, faulthandler.enable() is called at startup: install a handler for SIGSEGV, SIGFPE, SIGABRT, SIGBUS and SIGILL signals to dump the Python traceback. This is equivalent to -X faulthandler option.

Added in version 3.3.

PYTHONTRACEMALLOC

If this environment variable is set to a non-empty string, start tracing Python memory allocations using the tracemalloc module. The value of the variable is the maximum number of frames stored in a traceback of a trace. For example, PYTHONTRACEMALLOC=1 stores only the most recent frame. See the tracemalloc.start() function for more information. This is equivalent to setting the -X tracemalloc option.

Added in version 3.4.

PYTHONPROFILEIMPORTTIME

If this environment variable is set to a non-empty string, Python will show how long each import takes. This is equivalent to setting the -X importtime option.

Added in version 3.7.

PYTHONASYNCIODEBUG

この環境変数が空でない文字列に設定された場合、asyncio モジュールの デバッグモード が有効化されます。

Added in version 3.4.

PYTHONMALLOC

Set the Python memory allocators and/or install debug hooks.

Set the family of memory allocators used by Python:

default: use the default memory allocators.

malloc: use the malloc() function of the C library for all domains (PYMEM_DOMAIN_RAW, PYMEM_DOMAIN_MEM, PYMEM_DOMAIN_OBJ).

pymalloc: use the pymalloc allocator for PYMEM_DOMAIN_MEM and PYMEM_DOMAIN_OBJ domains and use the malloc() function for the PYMEM_DOMAIN_RAW domain.

Install debug hooks:

debug: install debug hooks on top of the default memory allocators.

malloc_debug: same as malloc but also install debug hooks.

pymalloc_debug: same as pymalloc but also install debug hooks.

Added in version 3.6.

バージョン 3.7 で変更: Added the "default" allocator.

PYTHONMALLOCSTATS

空でない文字列に設定されると、Python は新たなオブジェクトアリーナが生成される時と、シャットダウン時に pymalloc メモリアロケータ の統計情報を表示します。

This variable is ignored if the PYTHONMALLOC environment variable is used to force the malloc() allocator of the C library, or if Python is configured without 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.

PYTHONLEGACYWINDOWSFSENCODING

If set to a non-empty string, the default 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 sys._enablelegacywindowsfsencoding().

利用可能な環境: Windows 。

Added in version 3.6: より詳しくは PEP 529 [https://peps.python.org/pep-0529/] を参照してください。

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.

利用可能な環境: Windows 。

Added in version 3.6.

PYTHONCOERCECLOCALE

If set to the value 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 0), the LC_ALL locale override environment variable is also not set, and the current locale reported for the LC_CTYPE category is either the default C locale, or else the explicitly ASCII-based POSIX locale, then the Python CLI will attempt to configure the following locales for the LC_CTYPE category in the order listed before loading the interpreter runtime:

C.UTF-8

C.utf8

UTF-8

If setting one of these locale categories succeeds, then the 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 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 locale.getdefaultlocale()).

Configuring one of these locales (either explicitly or via the above implicit locale coercion) automatically enables the surrogateescape error handler for sys.stdin and sys.stdout (sys.stderr continues to use backslashreplace as it does in any other locale). This stream handling behavior can be overridden using PYTHONIOENCODING as usual.

For debugging purposes, setting PYTHONCOERCECLOCALE=warn will cause Python to emit warning messages on 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, PYTHONUTF8 will still activate by default in legacy ASCII-based locales. Both features must be disabled in order to force the interpreter to use ASCII instead of UTF-8 for system interfaces.

利用可能な環境: Unix。

Added in version 3.7: より詳しくは PEP 538 [https://peps.python.org/pep-0538/] を参照をしてください。

PYTHONDEVMODE

If this environment variable is set to a non-empty string, enable Python Development Mode, introducing additional runtime checks that are too expensive to be enabled by default. This is equivalent to setting the -X dev option.

Added in version 3.7.

PYTHONUTF8

If set to 1, enable the Python UTF-8 Mode.

If set to 0, disable the Python UTF-8 Mode.

Setting any other non-empty string causes an error during interpreter initialisation.

Added in version 3.7.

PYTHONWARNDEFAULTENCODING

If this environment variable is set to a non-empty string, issue a EncodingWarning when the locale-specific default encoding is used.

詳細は Opt-in EncodingWarning を参照してください。

Added in version 3.10.

PYTHONNODEBUGRANGES

If this variable is set, it disables the inclusion of the tables mapping extra location information (end line, start column offset and end column offset) to every instruction in code objects. This is useful when smaller code objects and pyc files are desired as well as suppressing the extra visual location indicators when the interpreter displays tracebacks.

Added in version 3.11.

PYTHONPERFSUPPORT

If this variable is set to a nonzero value, it enables support for the Linux perf profiler so Python calls can be detected by it.

If set to 0, disable Linux perf profiler support.

See also the -X perf command-line option and Python support for the Linux perf profiler.

Added in version 3.12.

1.2.1. デバッグモード変数

PYTHONDUMPREFS

設定された場合、 Python はインタプリタのシャットダウン後に残っているオブジェクトと参照カウントをダンプします。

Need Python configured with the --with-trace-refs build option.

PYTHONDUMPREFSFILE=FILENAME

If set, Python will dump objects and reference counts still alive after shutting down the interpreter into a file called FILENAME.

Need Python configured with the --with-trace-refs build option.

Added in version 3.11.

2. Unix プラットフォームで Python を使う

2.1. 最新バージョンの Python の取得とインストール

2.1.1. Linux

ほとんどの Linux ディストリビューションでは Python はプリインストールされており、それ以外でもパッケージとして利用可能です。しかし、ディストリビューションのパッケージでは利用したい機能が使えない場合があります。最新版の Python をソースから簡単にコンパイルすることができます。

Python がプリインストールされておらず、リポジトリにも無い場合、ディストリビューション用のパッケージを簡単につくることができます。以下のリンクを参照してください:

参考

https://www.debian.org/doc/manuals/maint-guide/first.en.html

Debian ユーザー向け

https://en.opensuse.org/Portal:Packaging

OpenSuse ユーザー向け

https://docs.fedoraproject.org/en-US/package-maintainers/Packaging_Tutorial_GNU_Hello/

Fedora ユーザー向け

https://slackbook.org/html/package-management-making-packages.html

Slackware ユーザー向け

2.1.2. FreeBSD と OpenBSD

FreeBSD ユーザーが Python パッケージを追加するには次のようにしてください:

pkg install python3

OpenBSD ユーザーが Python パッケージを追加するには次のようにしてください:

pkg_add -r python

pkg_add ftp://ftp.openbsd.org/pub/OpenBSD/4.2/packages/<insert your architecture here>/python-<version>.tgz

例えば、i386 ユーザーが Python 2.5.1 を取得するには次のようにします:

pkg_add ftp://ftp.openbsd.org/pub/OpenBSD/4.2/packages/i386/python-2.5.1p2.tgz

2.2. Python のビルド

CPython を自分でコンパイルしたい場合は、まず ソース [https://www.python.org/downloads/source/] を入手します。最新リリース版のソースをダウンロード、あるいはソースリポジトリから新しく クローン [https://devguide.python.org/setup/#get-the-source-code] を作成してください。(パッチの作成に貢献したい場合はクローンが必要になるでしょう。)

ビルド手順は通常のコマンドで行います

./configure
make
make install

Configure のオプション や特定の Unix プラットフォームにおける注意点は Python ソースツリーのルートにある README.rst [https://github.com/python/cpython/tree/3.12/README.rst] に細かく記載されています。

警告

make install は python3 バイナリを上書きまたはリンクを破壊してしまうかもしれません。そのため、make install の代わりに exec_prefix/bin/pythonversion のみインストールする make altinstall が推奨されています。

2.3. Python に関係するパスとファイル

これらはローカルインストールの慣例に応じて変化します; prefix と exec_prefix はインストール状況に依存していて、GNU ソフトウェアによって解釈されます; この二つは同じである場合があります。

例えば、ほとんどの Linux システムでは、両方のデフォルトが /usr です。

ファイル/ディレクトリ

意味

exec_prefix/bin/python3

インタプリタの推奨される場所

prefix/lib/pythonversion, exec_prefix/lib/pythonversion

標準モジュールを格納するディレクトリの、推奨される場所。

prefix/include/pythonversion, exec_prefix/include/pythonversion

Python 拡張や Python の埋込みに必要となる include ファイルを格納するディレクトリの推奨される場所。

2.4. その他

Python スクリプトを Unix で簡単に使うためには、例えば次のようにしてスクリプトを実行可能ファイルにし、

$ chmod +x script

適切な shebang 行をスクリプトの先頭に置きます。たいていの場合良い方法は

#!/usr/bin/env python3

で、PATH 全体から Python インタープリターを探します。しかし、いくつかの Unix は env コマンドを持たないので、インタープリターのパスを /usr/bin/python3 のようにハードコードしなければならないかもしれません。

シェルコマンドを Python スクリプトから使うには、 subprocess モジュールを参照してください。

2.5. Custom OpenSSL

To use your vendor's OpenSSL configuration and system trust store, locate the directory with openssl.cnf file or symlink in /etc. On most distribution the file is either in /etc/ssl or /etc/pki/tls. The directory should also contain a cert.pem file and/or a certs directory.

$ find /etc/ -name openssl.cnf -printf "%h\n"
/etc/ssl

Download, build, and install OpenSSL. Make sure you use install_sw and not install. The install_sw target does not override openssl.cnf.

$ 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

Build Python with custom OpenSSL (see the configure --with-openssl and --with-openssl-rpath options)

$ 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

注釈

Patch releases of OpenSSL have a backwards compatible ABI. You don't need to recompile Python to update OpenSSL. It's sufficient to replace the custom OpenSSL installation with a newer version.

3. Python を構成する

3.1. Build Requirements

Features required to build CPython:

A C11 [https://en.cppreference.com/w/c/11] compiler. Optional C11 features [https://en.wikipedia.org/wiki/C11_(C_standard_revision)#Optional_features] are not required.

Support for IEEE 754 [https://en.wikipedia.org/wiki/IEEE_754] floating point numbers and floating point Not-a-Number (NaN) [https://en.wikipedia.org/wiki/NaN#Floating_point].

Support for threads.

OpenSSL 1.1.1 or newer for the ssl and hashlib modules.

On Windows, Microsoft Visual Studio 2017 or later is required.

バージョン 3.5 で変更: On Windows, Visual Studio 2015 or later is required.

バージョン 3.6 で変更: Selected C99 features are now required, like <stdint.h> and static inline functions.

バージョン 3.7 で変更: Thread support and OpenSSL 1.0.2 are now required.

バージョン 3.10 で変更: OpenSSL 1.1.1 is now required.

バージョン 3.11 で変更: C11 compiler, IEEE 754 and NaN support are now required. On Windows, Visual Studio 2017 or later is required.

See also PEP 7 [https://peps.python.org/pep-0007/] "Style Guide for C Code" and PEP 11 [https://peps.python.org/pep-0011/] "CPython platform support".

3.2. 生成されるファイル

To reduce build dependencies, Python source code contains multiple generated files. Commands to regenerate all generated files:

make regen-all
make regen-stdlib-module-names
make regen-limited-abi
make regen-configure

The Makefile.pre.in file documents generated files, their inputs, and tools used to regenerate them. Search for regen-* make targets.

3.2.1. 構成スクリプト

The make regen-configure command regenerates the aclocal.m4 file and the configure script using the 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:

autoreconf -ivf -Werror

The generated files can change depending on the exact autoconf-archive, aclocal and pkg-config versions.

3.3. Configureオプション

List all ./configure script options using:

./configure --help

Pythonのソース配布の中の Misc/SpecialBuilds.txt も参照してください。

3.3.1. 一般的なオプション

--enable-loadable-sqlite-extensions

Support loadable extensions in the _sqlite extension module (default is no) of the sqlite3 module.

sqlite3 モジュールの sqlite3.Connection.enable_load_extension() メソッドを参照してください。

Added in version 3.6.

--disable-ipv6

IPv6サポートを無効にします(サポートされている場合はデフォルトで有効)、 socket モジュールを参照してください。

--enable-big-digits=[15|30]

Python int の桁の大きさをビット単位で定義します: 15ビットまたは30ビットです。

デフォルトでは、桁の大きさは30です。

PYLONG_BITS_IN_DIGIT を 15 または 30 に定義します。

sys.int_info.bits_per_digit を参照してください。

--with-suffix=SUFFIX

Python の実行ファイルの接頭辞を SUFFIX に設定します。

デフォルトの接尾辞は、 Windows と macOS では .exe ( python.exe 実行ファイル)、 Emscripten node では .js 、 Emscripten browser では .html 、 WASI では .wasm 、その他のプラットフォームでは空文字列になります ( python 実行ファイル)。

バージョン 3.11 で変更: WASM プラットフォームのデフォルトの接頭辞は、 .js 、 .html 、 .wasm のうちの1つです。

--with-tzpath=<list of absolute paths separated by pathsep>

デフォルトのタイムゾーン検索パスを zoneinfo.TZPATH に設定します。zoneinfo モジュールの Compile-time configuration を参照してください。

デフォルト: /usr/share/zoneinfo:/usr/lib/zoneinfo:/usr/share/lib/zoneinfo:/etc/zoneinfo

os.pathsep パスセパレータを参照してください。

Added in version 3.9.

--without-decimal-contextvar

コルーチンローカルコンテキスト(デフォルト)ではなく、スレッドローカルコンテキストを使用して _decimal 拡張モジュールをビルドします。 decimal モジュールを参照してください。

decimal.HAVE_CONTEXTVAR および contextvars モジュールを参照してください。

Added in version 3.9.

--with-dbmliborder=<list of backend names>

dbm モジュールの DB バックエンドをチェックする順序をオーバーライドします。

有効な値は、バックエンド名をコロン( : )で区切った文字列です:

ndbm;

gdbm;

bdb。

--without-c-locale-coercion

UTF-8 ベースのロケールへの C ロケールの強制を無効にします(デフォルトで有効)。

PY_COERCE_C_LOCALE マクロは定義しないでください。

PYTHONCOERCECLOCALE および PEP 538 [https://peps.python.org/pep-0538/] を参照してください。

--without-freelists

Disable all freelists except the empty tuple singleton.

Added in version 3.11.

--with-platlibdir=DIRNAME

Python のライブラリディレクトリ名(デフォルトは lib )。

Fedora と SuSE は64ビットプラットフォームで lib64 を使用します。

sys.platlibdir を参照してください。

Added in version 3.9.

--with-wheel-pkg-dir=PATH

ensurepip モジュールが使用する wheel パッケージのディレクトリです(デフォルトはなし)。

Linux ディストリビューションのパッケージングポリシーの中には、依存関係をバンドルすることを推奨しているものがあります。例えば、 Fedora は wheel パッケージを /usr/share/python-wheels/ ディレクトリにインストールし、 ensurepip._bundled パッケージはインストールしません。

Added in version 3.10.

--with-pkg-config=[check|yes|no]

configure がビルドの依存関係を検出するために pkg-config を使用するかどうかを設定します。

check (デフォルト): pkg-config はオプションです。

yes : pkg-config は必須です。

no : pkg-config が存在しても、 configure は使用しません。

Added in version 3.11.

--enable-pystats

Turn on internal statistics gathering.

The statistics will be dumped to a arbitrary (probably unique) file in /tmp/py_stats/, or C:\temp\py_stats\ on Windows. If that directory does not exist, results will be printed on stdout.

統計情報を読むには Tools/scripts/summarize_stats.py を使用してください。

Added in version 3.11.

3.3.2. WebAssembly オプション

--with-emscripten-target=[browser|node]

wasm32-emscripten のビルドフレーバーを設定します。

browser (デフォルト): 最小限の stdlib 、デフォルトの MEMFS をプリロードします。

node: NODERAWFS と pthread をサポートします。

Added in version 3.11.

--enable-wasm-dynamic-linking

WASM のダイナミックリンクサポートをオンにします。

ダイナミックリンクにより dlopen が可能になります。デッドコードの排除や機能追加に制限があるため、実行ファイルのファイルサイズが大きくなります。

Added in version 3.11.

--enable-wasm-pthreads

WASM の pthreads サポートをオンにします。

Added in version 3.11.

3.3.3. インストールオプション

--prefix=PREFIX

アーキテクチャに依存しないファイルを PREFIX にインストールします。Unix の場合、デフォルトは /usr/local です。

この値は、実行時に sys.prefix を使って取得することができます。

例として、 --prefix="$HOME/.local/" を使用すると、 Python をそのホームディレクトリにインストールすることができます。

--exec-prefix=EPREFIX

アーキテクチャ依存のファイルを EPREFIX にインストールします。デフォルトは --prefix です。

この値は、実行時に sys.exec_prefix を使って取得することができます。

--disable-test-modules

test パッケージや _testcapi 拡張モジュール(デフォルトでビルド、インストールされます)のようなテストモジュールをビルド、インストールしないようにします。

Added in version 3.10.

--with-ensurepip=[upgrade|install|no]

Python のインストール時に実行される ensurepip コマンドを選択します:

upgrade (デフォルト): python -m ensurepip --altinstall --upgrade コマンドを実行します。

install: python -m ensurepip --altinstall コマンドを実行します。

no: ensurepip を実行しない;

Added in version 3.6.

3.3.4. パフォーマンスに関するオプション

Configuring Python using --enable-optimizations --with-lto (PGO + LTO) is recommended for best performance. The experimental --enable-bolt flag can also be used to improve performance.

--enable-optimizations

PROFILE_TASK を使用して Profile Guided Optimization (PGO) を有効にします(デフォルトでは無効です)。

Cコンパイラの Clang では、 PGO のために llvm-profdata プログラムが必要です。macOS では、 GCC もこれを必要とします: GCC は macOS の Clang のエイリアスにすぎません。

Disable also semantic interposition in libpython if --enable-shared and GCC is used: add -fno-semantic-interposition to the compiler and linker flags.

注釈

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 -Wno-profile-instr-unprofiled to CFLAGS.

Added in version 3.6.

バージョン 3.10 で変更: GCC で -fno-semantic-interposition を使用する。

PROFILE_TASK

Environment variable used in the Makefile: Python command line arguments for the PGO generation task.

デフォルト: -m test --pgo --timeout=$(TESTTIMEOUT)

Added in version 3.8.

--with-lto=[full|thin|no|yes]

Enable Link Time Optimization (LTO) in any build (disabled by default).

The C compiler Clang requires llvm-ar for LTO (ar on macOS), as well as an LTO-aware linker (ld.gold or lld).

Added in version 3.6.

Added in version 3.11: To use ThinLTO feature, use --with-lto=thin on Clang.

バージョン 3.12 で変更: Use ThinLTO as the default optimization policy on Clang if the compiler accepts the flag.

--enable-bolt

Enable usage of the BOLT post-link binary optimizer [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 llvm-bolt and 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 BOLT_INSTRUMENT_FLAGS and BOLT_APPLY_FLAGS configure variables can be defined to override the default set of arguments for llvm-bolt to instrument and apply BOLT data to binaries, respectively.

Added in version 3.12.

--with-computed-gotos

Enable computed gotos in evaluation loop (enabled by default on supported compilers).

--without-pymalloc

Disable the specialized Python memory allocator pymalloc (enabled by default).

See also PYTHONMALLOC environment variable.

--without-doc-strings

Disable static documentation strings to reduce the memory footprint (enabled by default). Documentation strings defined in Python are not affected.

Don't define the WITH_DOC_STRINGS macro.

See the PyDoc_STRVAR() macro.

--enable-profiling

Enable C-level code profiling with gprof (disabled by default).

--with-strict-overflow

Add -fstrict-overflow to the C compiler flags (by default we add -fno-strict-overflow instead).

3.3.5. Python Debug Build

A debug build is Python built with the --with-pydebug configure option.

Effects of a debug build:

Display all warnings by default: the list of default warning filters is empty in the warnings module.

Add d to sys.abiflags.

Add sys.gettotalrefcount() function.

Add -X showrefcount command line option.

Add -d command line option and PYTHONDEBUG environment variable to debug the parser.

Add support for the __lltrace__ variable: enable low-level tracing in the bytecode evaluation loop if the variable is defined.

Install debug hooks on memory allocators to detect buffer overflow and other memory errors.

Define Py_DEBUG and Py_REF_DEBUG macros.

Add runtime checks: code surrounded by #ifdef Py_DEBUG and #endif. Enable assert(...) and _PyObject_ASSERT(...) assertions: don't set the NDEBUG macro (see also the --with-assertions configure option). Main runtime checks:

Add sanity checks on the function arguments.

Unicode and int objects are created with their memory filled with a pattern to detect usage of uninitialized objects.

Ensure that functions which can clear or replace the current exception are not called with an exception raised.

Check that deallocator functions don't change the current exception.

The garbage collector (gc.collect() function) runs some basic checks on objects consistency.

The Py_SAFE_DOWNCAST() macro checks for integer underflow and overflow when downcasting from wide types to narrow types.

See also the Python Development Mode and the --with-trace-refs configure option.

バージョン 3.8 で変更: Release builds and debug builds are now ABI compatible: defining the Py_DEBUG macro no longer implies the Py_TRACE_REFS macro (see the --with-trace-refs option), which introduces the only ABI incompatibility.

3.3.6. Debug options

--with-pydebug

Build Python in debug mode: define the Py_DEBUG macro (disabled by default).

--with-trace-refs

Enable tracing references for debugging purpose (disabled by default).

Effects:

Define the Py_TRACE_REFS macro.

Add sys.getobjects() function.

Add PYTHONDUMPREFS environment variable.

This build is not ABI compatible with release build (default build) or debug build (Py_DEBUG and Py_REF_DEBUG macros).

Added in version 3.8.

--with-assertions

Build with C assertions enabled (default is no): assert(...); and _PyObject_ASSERT(...);.

If set, the NDEBUG macro is not defined in the OPT compiler variable.

See also the --with-pydebug option (debug build) which also enables assertions.

Added in version 3.6.

--with-valgrind

Enable Valgrind support (default is no).

--with-dtrace

Enable DTrace support (default is no).

See Instrumenting CPython with DTrace and SystemTap.

Added in version 3.6.

--with-address-sanitizer

Enable AddressSanitizer memory error detector, asan (default is no).

Added in version 3.6.

--with-memory-sanitizer

Enable MemorySanitizer allocation error detector, msan (default is no).

Added in version 3.6.

--with-undefined-behavior-sanitizer

Enable UndefinedBehaviorSanitizer undefined behaviour detector, ubsan (default is no).

Added in version 3.6.

3.3.7. Linker options

--enable-shared

Enable building a shared Python library: libpython (default is no).

--without-static-libpython

Do not build libpythonMAJOR.MINOR.a and do not install python.o (built and enabled by default).

Added in version 3.10.

3.3.8. Libraries options

--with-libs='lib1 ...'

Link against additional libraries (default is no).

--with-system-expat

Build the pyexpat module using an installed expat library (default is no).

--with-system-libmpdec

Build the _decimal extension module using an installed mpdec library, see the decimal module (default is no).

Added in version 3.3.

--with-readline=editline

Use editline library for backend of the readline module.

Define the WITH_EDITLINE macro.

Added in version 3.10.

--without-readline

Don't build the readline module (built by default).

Don't define the HAVE_LIBREADLINE macro.

Added in version 3.10.

--with-libm=STRING

Override libm math library to STRING (default is system-dependent).

--with-libc=STRING

Override libc C library to STRING (default is system-dependent).

--with-openssl=DIR

Root of the OpenSSL directory.

Added in version 3.7.

--with-openssl-rpath=[no|auto|DIR]

Set runtime library directory (rpath) for OpenSSL libraries:

no (default): don't set rpath;

auto: auto-detect rpath from --with-openssl and pkg-config;

DIR: set an explicit rpath.

Added in version 3.10.

3.3.9. Security Options

--with-hash-algorithm=[fnv|siphash13|siphash24]

Select hash algorithm for use in Python/pyhash.c:

siphash13 (default);

siphash24;

fnv.

Added in version 3.4.

Added in version 3.11: siphash13 is added and it is the new default.

--with-builtin-hashlib-hashes=md5,sha1,sha256,sha512,sha3,blake2

Built-in hash modules:

md5;

sha1;

sha256;

sha512;

sha3 (with shake);

blake2.

Added in version 3.9.

--with-ssl-default-suites=[python|openssl|STRING]

Override the OpenSSL default cipher suites string:

python (default): use Python's preferred selection;

openssl: leave OpenSSL's defaults untouched;

STRING: use a custom string

See the ssl module.

Added in version 3.7.

バージョン 3.10 で変更: The settings python and STRING also set TLS 1.2 as minimum protocol version.

3.3.10. macOS のオプション

See Mac/README.rst.

--enable-universalsdk

--enable-universalsdk=SDKDIR

Create a universal binary build. SDKDIR specifies which macOS SDK should be used to perform the build (default is no).

--enable-framework

--enable-framework=INSTALLDIR

Create a Python.framework rather than a traditional Unix install. Optional INSTALLDIR specifies the installation path (default is no).

--with-universal-archs=ARCH

Specify the kind of universal binary that should be created. This option is only valid when --enable-universalsdk is set.

オプション:

universal2;

32-bit;

64-bit;

3-way;

intel;

intel-32;

intel-64;

all。

--with-framework-name=FRAMEWORK

Specify the name for the python framework on macOS only valid when --enable-framework is set (default: Python).

3.3.11. クロスコンパイルのオプション

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.

--build=BUILD

configure for building on BUILD, usually guessed by config.guess.

--host=HOST

cross-compile to build programs to run on HOST (target platform)

--with-build-python=path/to/python

path to build python binary for cross compiling

Added in version 3.11.

CONFIG_SITE=file

An environment variable that points to a file with configure overrides.

Example config.site file:

# config.site-aarch64
ac_cv_buggy_getaddrinfo=no
ac_cv_file__dev_ptmx=yes
ac_cv_file__dev_ptc=no

クロスコンパイルの例:

CONFIG_SITE=config.site-aarch64 ../configure \
    --build=x86_64-pc-linux-gnu \
    --host=aarch64-unknown-linux-gnu \
    --with-build-python=../x86_64/python

3.4. Python Build System

3.4.1. Main files of the build system

configure.ac => configure;

Makefile.pre.in => Makefile (created by configure);

pyconfig.h (created by configure);

Modules/Setup: C extensions built by the Makefile using Module/makesetup shell script;

3.4.2. Main build steps

C files (.c) are built as object files (.o).

A static libpython library (.a) is created from objects files.

python.o and the static libpython library are linked into the final python program.

C extensions are built by the Makefile (see Modules/Setup).

3.4.3. Main Makefile targets

make: Build Python with the standard library.

make platform:: build the python program, but don't build the standard library extension modules.

make profile-opt: build Python using Profile Guided Optimization (PGO). You can use the configure --enable-optimizations option to make this the default target of the make command (make all or just make).

make buildbottest: Build Python and run the Python test suite, the same way than buildbots test Python. Set TESTTIMEOUT variable (in seconds) to change the test timeout (1200 by default: 20 minutes).

make install: Build and install Python.

make regen-all: Regenerate (almost) all generated files; make regen-stdlib-module-names and autoconf must be run separately for the remaining generated files.

make clean: Remove built files.

make distclean: Same than make clean, but remove also files created by the configure script.

3.4.4. C extensions

Some C extensions are built as built-in modules, like the sys module. They are built with the Py_BUILD_CORE_BUILTIN macro defined. Built-in modules have no __file__ attribute:

>>> 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__'

Other C extensions are built as dynamic libraries, like the _asyncio module. They are built with the Py_BUILD_CORE_MODULE macro defined. Example on Linux x86-64:

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

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 *shared* marker are built as dynamic libraries.

The PyAPI_FUNC(), PyAPI_DATA() and PyMODINIT_FUNC macros of Include/exports.h are defined differently depending if the Py_BUILD_CORE_MODULE macro is defined:

Use Py_EXPORTED_SYMBOL if the Py_BUILD_CORE_MODULE is defined

Use Py_IMPORTED_SYMBOL otherwise.

If the Py_BUILD_CORE_BUILTIN macro is used by mistake on a C extension built as a shared library, its PyInit_xxx() function is not exported, causing an ImportError on import.

3.5. Compiler and linker flags

Options set by the ./configure script and environment variables and used by Makefile.

3.5.1. Preprocessor flags

CONFIGURE_CPPFLAGS

Value of CPPFLAGS variable passed to the ./configure script.

Added in version 3.6.

CPPFLAGS

(Objective) C/C++ preprocessor flags, e.g. -Iinclude_dir if you have headers in a nonstandard directory include_dir.

Both CPPFLAGS and LDFLAGS need to contain the shell's value to be able to build extension modules using the directories specified in the environment variables.

BASECPPFLAGS

Added in version 3.4.

PY_CPPFLAGS

Extra preprocessor flags added for building the interpreter object files.

Default: $(BASECPPFLAGS) -I. -I$(srcdir)/Include $(CONFIGURE_CPPFLAGS) $(CPPFLAGS).

Added in version 3.2.

3.5.2. Compiler flags

CC

C compiler command.

Example: gcc -pthread.

CXX

C++ compiler command.

Example: g++ -pthread.

CFLAGS

C compiler flags.

CFLAGS_NODIST

CFLAGS_NODIST is used for building the interpreter and stdlib C extensions. Use it when a compiler flag should not be part of CFLAGS once Python is installed (gh-65320 [https://github.com/python/cpython/issues/65320]).

In particular, CFLAGS should not contain:

the compiler flag -I (for setting the search path for include files). The -I flags are processed from left to right, and any flags in CFLAGS would take precedence over user- and package-supplied -I flags.

hardening flags such as -Werror because distributions cannot control whether packages installed by users conform to such heightened standards.

Added in version 3.5.

COMPILEALL_OPTS

Options passed to the compileall command line when building PYC files in make install. Default: -j0.

Added in version 3.12.

EXTRA_CFLAGS

Extra C compiler flags.

CONFIGURE_CFLAGS

Value of CFLAGS variable passed to the ./configure script.

Added in version 3.2.

CONFIGURE_CFLAGS_NODIST

Value of CFLAGS_NODIST variable passed to the ./configure script.

Added in version 3.5.

BASECFLAGS

Base compiler flags.

OPT

Optimization flags.

CFLAGS_ALIASING

Strict or non-strict aliasing flags used to compile Python/dtoa.c.

Added in version 3.7.

CCSHARED

Compiler flags used to build a shared library.

For example, -fPIC is used on Linux and on BSD.

CFLAGSFORSHARED

Extra C flags added for building the interpreter object files.

Default: $(CCSHARED) when --enable-shared is used, or an empty string otherwise.

PY_CFLAGS

Default: $(BASECFLAGS) $(OPT) $(CONFIGURE_CFLAGS) $(CFLAGS) $(EXTRA_CFLAGS).

PY_CFLAGS_NODIST

Default: $(CONFIGURE_CFLAGS_NODIST) $(CFLAGS_NODIST) -I$(srcdir)/Include/internal.

Added in version 3.5.

PY_STDMODULE_CFLAGS

C flags used for building the interpreter object files.

Default: $(PY_CFLAGS) $(PY_CFLAGS_NODIST) $(PY_CPPFLAGS) $(CFLAGSFORSHARED).

Added in version 3.7.

PY_CORE_CFLAGS

Default: $(PY_STDMODULE_CFLAGS) -DPy_BUILD_CORE.

Added in version 3.2.

PY_BUILTIN_MODULE_CFLAGS

Compiler flags to build a standard library extension module as a built-in module, like the posix module.

Default: $(PY_STDMODULE_CFLAGS) -DPy_BUILD_CORE_BUILTIN.

Added in version 3.8.

PURIFY

Purify command. Purify is a memory debugger program.

Default: empty string (not used).

3.5.3. Linker flags

LINKCC

Linker command used to build programs like python and _testembed.

Default: $(PURIFY) $(CC).

CONFIGURE_LDFLAGS

Value of LDFLAGS variable passed to the ./configure script.

Avoid assigning CFLAGS, LDFLAGS, etc. so users can use them on the command line to append to these values without stomping the pre-set values.

Added in version 3.2.

LDFLAGS_NODIST

LDFLAGS_NODIST is used in the same manner as CFLAGS_NODIST. Use it when a linker flag should not be part of LDFLAGS once Python is installed (gh-65320 [https://github.com/python/cpython/issues/65320]).

In particular, LDFLAGS should not contain:

the compiler flag -L (for setting the search path for libraries). The -L flags are processed from left to right, and any flags in LDFLAGS would take precedence over user- and package-supplied -L flags.

CONFIGURE_LDFLAGS_NODIST

Value of LDFLAGS_NODIST variable passed to the ./configure script.

Added in version 3.8.

LDFLAGS

Linker flags, e.g. -Llib_dir if you have libraries in a nonstandard directory lib_dir.

Both CPPFLAGS and LDFLAGS need to contain the shell's value to be able to build extension modules using the directories specified in the environment variables.

LIBS

Linker flags to pass libraries to the linker when linking the Python executable.

Example: -lrt.

LDSHARED

Command to build a shared library.

Default: @LDSHARED@ $(PY_LDFLAGS).

BLDSHARED

Command to build libpython shared library.

Default: @BLDSHARED@ $(PY_CORE_LDFLAGS).

PY_LDFLAGS

Default: $(CONFIGURE_LDFLAGS) $(LDFLAGS).

PY_LDFLAGS_NODIST

Default: $(CONFIGURE_LDFLAGS_NODIST) $(LDFLAGS_NODIST).

Added in version 3.8.

PY_CORE_LDFLAGS

Linker flags used for building the interpreter object files.

Added in version 3.8.

4. Windows で Python を使う

このドキュメントは、 Python を Microsoft Windows で使うときに知っておくべき、 Windows 固有の動作についての概要を伝えることを目的としています。

Unlike most Unix systems and services, Windows does not include a system supported installation of Python. To make Python available, the CPython team has compiled Windows installers with every release [https://www.python.org/downloads/] for many years. These installers are primarily intended to add a per-user installation of Python, with the core interpreter and library being used by a single user. The installer is also able to install for all users of a single machine, and a separate ZIP file is available for application-local distributions.

PEP 11 [https://peps.python.org/pep-0011/] で明記しているとおり Python のリリースは、Microsoft が延長サポート期間であるとしている Windows プラットフォームのみをサポートします。つまり Python 3.12 は Windows 8.1 とそれより新しい Windows をサポートするということです。 Windows 7 サポートが必要な場合は、Python 3.8 をインストールしてください。

Windows で使えるインストーラには多くの様々なものがあり、それぞれが利点と欠点を持っています。

完全版インストーラ には全てのコンポーネントが含まれており、 Python を使う開発者がどんな種類のプロジェクトでも最適な選択肢です。

Microsoft ストアパッケージ は、スクリプトやパッケージの実行、 IDLE の使用やその他開発環境に適したシンプルな構成の Python です。 Windows 10 以上が求められはしますが、他のプログラムを壊すことなく安全にインストールできます。 Python やそのツールを起動する多くの便利なコマンドも提供しています。

nuget.org パッケージ は、継続的インテグレーションのための軽量なインストール構成です。これは Python パッケージのビルドやスクリプトの実行にも使えますが、アップデート可能ではなく、ユーザーインターフェイスツールもありません。

埋め込み可能なパッケージ は、他の大きなアプリケーションに埋め込むのに適した、 Python の最小パッケージです。

4.1. 完全版インストーラ

4.1.1. インストール手順

ダウンロードできる Python 3.12 のインストーラは 4 つあります。インタプリタの 32 ビット版、64 ビット版がそれぞれ 2 つずつあります。 WEB インストーラ は最初のダウンロードサイズは小さく、必要なコンポーネントはインストーラ実行時に必要に応じて自動的にダウンロードします。オフラインインストーラ にはデフォルトインストールに必要なコンポーネントが含まれていて、インターネット接続はオプショナルな機能のためにだけに必要となります。インストール時にダウンロードを避けるほかの方法については ダウンロード不要なインストール を参照して下さい。

インストーラを開始すると、2つの選択肢からひとつを選べます:

"Install Now" を選択した場合:

管理者権限は 不要です (ただし C ランタイムライブラリのシステム更新が必要であったり、 Windows の Python ランチャ をすべてのユーザ向けにインストールする場合は必要です)。

Python はあなたのユーザディレクトリにインストールされます。

Windows の Python ランチャ はこのインストールウィザード最初のページの下部のチェックボックス指定に従ってインストールされます。

標準ライブラリ、テストスイート、ランチャ、pip がインストールされます。

このインストールウィザード最初の下部のチェックボックスをチェックすれば、環境変数 PATH にインストールディレクトリが追加されます。

ショートカットはカレントユーザだけに可視になります。

"Customize installation" を選択すると、インストール場所、その他オプションやインストール後のアクションの変更などのインストールの有りようを選べます。デバッグシンボルやデバッグバイナリをインストールするならこちらを選択する必要があるでしょう。

すべてのユーザのためのインストールのためには "Customize installation" を選んでください。この場合:

管理者資格か承認が必要かもしれません。

Python は Program Files ディレクトリにインストールされます。

Windows の Python ランチャ は Windows ディレクトリにインストールされます。

オプショナルな機能はインストール中に選択できます。

標準ライブラリをバイトコードにプリコンパイルできます。

そう選択すれば、インストールディレクトリはシステム環境変数 PATH に追加されます。

ショートカットがすべてのユーザで利用できるようになります。

4.1.2. MAX_PATH の制限を除去する

Windows は歴史的にパスの長さが 260 文字に制限されています。つまり、これより長いパスは解決できず結果としてエラーになるということです。

Windows の最新版では、この制限は約 32,000 文字まで拡張できます。管理者が、グループポリシーの "Win32 の長いパスを有効にする (Enable Win32 long paths)" を有効にするか、レジストリキー HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem の LongPathsEnabled の値を 1 に設定する必要があります。

This allows the open() function, the os module and most other path functionality to accept and return paths longer than 260 characters.

これらのオプションを変更したら、それ以上の設定は必要ありません。

バージョン 3.6 で変更: Python で長いパスのサポートが可能になりました。

4.1.3. インストーラの GUI なしでインストールする

インストーラの GUI で利用できるすべてのオプションは、コマンドラインからも指定できます。これによりユーザとの対話なしで数多くの機器に同じインストールを行うような、スクリプト化されたインストールを行うことができます。ちょっとしたデフォルトの変更のために、GUI を抑制することなしにこれらコマンドラインオプションをセットすることもできます。

The following options (found by executing the installer with /?) can be passed into the installer:

名前

説明

/passive

to display progress without requiring user interaction

/quiet

to install/uninstall without displaying any UI

/simple

to prevent user customization

/uninstall

to remove Python (without confirmation)

/layout [ディレクトリ]

to pre-download all components

/log [ファイル名]

to specify log files location

ほかのすべてのオプションは name=value の形で渡します。value は大抵 0 で機能を無効化、 1 で機能を有効化、であるとかパスの指定です。利用可能なオプションの完全なリストは以下の通りです。

名前

説明

デフォルト

InstallAllUsers

システムワイドなインストールを実行する。

0

TargetDir

インストール先ディレクトリ。

InstallAllUsers に基いて選択されます。

DefaultAllUsersTargetDir

すべてのユーザ向けインストールのためのデフォルトインストール先ディレクトリ。

%ProgramFiles%\Python X.Y または %ProgramFiles(x86)%\Python X.Y

DefaultJustForMeTargetDir

自分一人用インストールのためのデフォルトインストール先ディレクトリ。

%LocalAppData%\Programs\Python\PythonXY または %LocalAppData%\Programs\Python\PythonXY-32 または %LocalAppData%\Programs\Python\PythonXY-64

DefaultCustomTargetDir

カスタムインストールディレクトリとしてデフォルトで GUI に表示される値。

(空)

AssociateFiles

ランチャもインストールする場合に、ファイルの関連付けを行う。

1

CompileAll

すべての .py ファイルをバイトコンパイルして .pyc を作る。

0

PrependPath

Prepend install and Scripts directories to PATH and add .PY to PATHEXT

0

AppendPath

Append install and Scripts directories to PATH and add .PY to PATHEXT

0

Shortcuts

インストールするインタプリタ、ドキュメント、IDLE へのショートカットを作る。

1

Include_doc

Python マニュアルをインストールする。

1

Include_debug

デバッグバイナリをインストールする。

0

Include_dev

Install developer headers and libraries. Omitting this may lead to an unusable installation.

1

Include_exe

Install python.exe and related files. Omitting this may lead to an unusable installation.

1

Include_launcher

Windows の Python ランチャ をインストールする。

1

InstallLauncherAllUsers

Installs the launcher for all users. Also requires Include_launcher to be set to 1

1

Include_lib

Install standard library and extension modules. Omitting this may lead to an unusable installation.

1

Include_pip

バンドル版の pip と setuptools をインストールする。

1

Include_symbols

デバッグシンボル (*.pdb) をインストールする。

0

Include_tcltk

Tcl/Tk サポートと IDLE をインストールする。

1

Include_test

標準ライブラリのテストスイートをインストールする。

1

Include_tools

ユーティリティスクリプトをインストールする。

1

LauncherOnly

ランチャのみをインストールする。これは他のほとんどのオプションを上書きします。

0

SimpleInstall

最大限のインストーラ GUI を無効にする。

0

SimpleInstallDescription

単純化されたインストーラ GUI を使う際に表示するカスタムメッセージ。

(空)

例えばデフォルトでシステムワイドな Python インストレーションを静かに行うには、以下コマンドを使えます (コマンドプロンプトより):

python-3.9.0.exe /quiet InstallAllUsers=1 PrependPath=1 Include_test=0

テストスイートなしの Python のパーソナルなコピーのインストールをユーザに簡単に行わせるには、以下コマンドのショートカットを作れば良いです。これはインストーラの最初のページを単純化して表示し、また、カスタマイズできないようにします:

python-3.9.0.exe InstallAllUsers=0 Include_launcher=0 Include_test=0
    SimpleInstall=1 SimpleInstallDescription="Just for me, no test suite."

(ランチャのインストールを省略するとファイルの関連付けも省略されるので、これはランチャインストールを含めたシステムワイドなインストールをした場合のユーザごとインストールに限った場合のお勧めです。)

上でリストしたオプションは、実行ファイルと同じ場所の unattend.xml と名付けられたファイルで与えることもできます。このファイルはオプションとその値のリストを指定します。値がアトリビュートとして与えられた場合、それは数値であれば数値に変換されます。エレメントテキストで与える場合は常に文字列のままです。以下は、先の例と同じオプションをセットするファイルの実例です:

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

4.1.4. ダウンロード不要なインストール

Python のいくつかの機能は最初にダウンロードしたインストーラには含まれていないため、それらの機能をインストールしようと選択するとインターネット接続が必要になります。インターネット接続が必要にならないように、全てのコンポーネントをすぐにできる限りダウンロードして、完全な 配置構成 (layout) を作成し、どんな機能が選択されたかに関わらず、それ以上インターネット接続を必要がないようにします。この方法のダウンロードサイズは必要以上に大きくなるかもしれませんが、たくさんの回数インストールしようとする場合には、ローカルにキャッシュされたコピーを持つことはとても有用です。

コマンドプロンプトから以下のコマンドを実行して、必要なファイルをできる限り全てダウンロードします。 python-3.9.0.exe 部分は実際のインストーラの名前に置き換え、同名のファイルどうしの衝突が起こらないように、個別のディレクトリ内に配置構成を作るのを忘れないようにしてください。

python-3.9.0.exe /layout [optional target directory]

進捗表示を隠すのに /quiet オプションを指定することもできます。

4.1.5. インストール後の変更

いったん Python がインストールされたら、Windows のシステム機能の「プログラムと機能」ツールから機能の追加や削除ができます。Python のエントリを選択して「アンインストールと変更」を選ぶことで、インストーラをメンテナンスモードで開きます。

インストーラ GUI で "Modify" を選ぶと、チェックボックスの選択を変えることで機能の追加削除ができます - チェックボックスの選択を変えなければ、何かがインストールされたり削除されたりはしません。いくつかのオプションはこのモードでは変更することはできません。インストールディレクトリなどです。それらを変えたいのであれば、完全に削除してから再インストールする必要があります。

"Repair" では、現在の設定で本来インストールされるべきすべてのファイルを検証し、削除されていたり更新されていたりするファイルを修正します。

"Uninstall" は Python を完全に削除します。「プログラムと機能」内の自身のエントリを持つ Windows の Python ランチャ の例外が起こります。

4.2. Microsoft ストアパッケージ

Added in version 3.7.2.

Microsoft ストアパッケージは、例えば生徒が主に対話型で使うことを意図した簡単にインストールできる Python インタプリタです。

このパッケージをインストールするには、最新の Windows 10 のアップデートになっていることを確認し、 Microsoft ストアアプリで "Python 3.12" と検索します。選んだアプリが Python Software Foundation が公開したものであることを確認して、インストールします。

警告

Python は常に Microsoft ストアで無料で利用できます。もしお金を払うように要求されたなら、正しいパッケージを選んでいません。

インストールした後は、スタートメニューから Python を見付けて起動するでしょう。あるいは、 python とタイプしてコマンドプロンプトや PowerShell のセッションから使えるでしょう。さらに、 pip や idle とタイプして pip あるいは IDLE を利用できます。 IDLE はスタートメニューからも見付けられます。

All three commands are also available with version number suffixes, for example, as python3.exe and python3.x.exe as well as python.exe (where 3.x is the specific version you want to launch, such as 3.12). Open "Manage App Execution Aliases" through Start to select which version of Python is associated with each command. It is recommended to make sure that pip and idle are consistent with whichever version of python is selected.

仮想環境は python -m venv で作成し、有効化して普通に使えます。

既に別のバージョンの Python をインストールして PATH 変数に追加してある場合は、 Microsoft ストアのものではない python.exe として使えます。新しくインストールした Python にアクセスするには、 python3.exe あるいは python3.x.exe として使えます。

The py.exe launcher will detect this Python installation, but will prefer installations from the traditional installer.

Python を除去するには、「設定」を開き「アプリと機能」を使うか、「スタート」にある Python を右クリックしてアンインストールします。アンインストールでは、この Python に直接インストールした全てのパッケージが除去されますが、仮想環境はどれも除去されません。

4.2.1. 既知の問題

4.2.1.1. Redirection of local data, registry, and temporary paths

Microsoft ストアアプリの制限により、 Python スクリプトには TEMP やレジストリのような共有の場所への完全な書き込み権限は無いでしょう。その代わり、個人用のところへ書き込みます。スクリプトで共有の場所で変更しなければならない場合は、完全版のインストーラでインストールする必要があります。

At runtime, Python will use a private copy of well-known Windows folders and the registry. For example, if the environment variable %APPDATA% is c:\Users\<user>\AppData\, then when writing to C:\Users\<user>\AppData\Local will write to C:\Users\<user>\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.8_qbz5n2kfra8p0\LocalCache\Local\.

When reading files, Windows will return the file from the private folder, or if that does not exist, the real Windows directory. For example reading C:\Windows\System32 returns the contents of C:\Windows\System32 plus the contents of C:\Program Files\WindowsApps\package_name\VFS\SystemX86.

You can find the real path of any existing file using os.path.realpath():

>>> import os
>>> test_file = 'C:\\Users\\example\\AppData\\Local\\test.txt'
>>> os.path.realpath(test_file)
'C:\\Users\\example\\AppData\\Local\\Packages\\PythonSoftwareFoundation.Python.3.8_qbz5n2kfra8p0\\LocalCache\\Local\\test.txt'

When writing to the Windows Registry, the following behaviors exist:

Reading from HKLM\\Software is allowed and results are merged with the registry.dat file in the package.

Writing to HKLM\\Software is not allowed if the corresponding key/value exists, i.e. modifying existing keys.

Writing to HKLM\\Software is allowed as long as a corresponding key/value does not exist in the package and the user has the correct access permissions.

For more detail on the technical basis for these limitations, please consult Microsoft's documentation on packaged full-trust apps, currently available at docs.microsoft.com/en-us/windows/msix/desktop/desktop-to-uwp-behind-the-scenes [https://docs.microsoft.com/en-us/windows/msix/desktop/desktop-to-uwp-behind-the-scenes]

4.3. nuget.org パッケージ

Added in version 3.5.2.

nuget.org パッケージはサイズを縮小した Python 環境で、システム全体で使える Python が無い継続的インテグレーションやビルドシステムで使うことを意図しています。 nuget は ".NET のためのパッケージマネージャ" ですが、ビルド時に使うツールを含んだパッケージに対しても非常に上手く動作します。

nuget の使用方法についての最新の情報を得るには nuget.org [https://www.nuget.org/] に行ってください。ここから先は Python 開発者にとって十分な要約です。

nuget.exe コマンドラインツールは、例えば curl や PowerShell を使って https://aka.ms/nugetclidl から直接ダウンロードできるでしょう。このツールを次のように使って、 64 bit あるいは 32 bit のマシン向けの最新バージョンの Python がインストールできます:

nuget.exe install python -ExcludeVersion -OutputDirectory .
nuget.exe install pythonx86 -ExcludeVersion -OutputDirectory .

特定のバージョンを選択するには、 -Version 3.x.y を追加してください。出力ディレクトリは . から変更されることがあり、パッケージはサブディレクトリにインストールされます。デフォルトではサブディレクトリはパッケージと同じ名前になり、 -ExcludeVersion オプションを付けないとこの名前はインストールされたバージョンを含みます。サブディレクトリの中にはインストールされた Python を含んでいる tools ディレクトリがあります:

# 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

一般的には、 nuget パッケージはアップグレードできず、より新しいバージョンは横並びにインストールされ、フルパスで参照されます。そうする代わりに、手動で直接パッケージを削除し、再度インストールすることもできます。多くの CI システムは、ビルド間でファイルを保存しておかない場合、この作業を自動的に行います。

tools ディレクトリと同じ場所に build\native ディレクトリがあります。このディレクトリは、インストールされた Python を参照する C++ プロジェクトで使える MSBuild プロパティファイル python.props を含みます。ここに設定を入れると自動的にヘッダを使い、ビルド時にライプラリをインポートします。

The package information pages on nuget.org are www.nuget.org/packages/python [https://www.nuget.org/packages/python] for the 64-bit version and www.nuget.org/packages/pythonx86 [https://www.nuget.org/packages/pythonx86] for the 32-bit version.

4.4. 埋め込み可能なパッケージ

Added in version 3.5.

埋め込み用の配布 (embedded distribution) は、最小限の Python 環境を含んだ ZIP ファイルです。これは、エンドユーザから直接的にアクセスされるのではなく何かアプリケーションの一部として動作することを意図したものです。

展開されると、埋め込み用の配布は、環境変数、システムレジストリの設定、インストールされているパッケージといったユーザのシステムから (ほぼ) 完全に独立しています。 ZIP 内には標準ライブラリがプリコンパイルにより最適化された .pyc として含まれ、また、 python3.dll, python37.dll, python.exe, pythonw.exe のすべてが入っています。(IDLE のようなすべての依存物を含む) Tcl/tk、pip、Python ドキュメントは含まれていません。

注釈

埋め込み用配布には Microsoft C Runtime [https://docs.microsoft.com/en-US/cpp/windows/latest-supported-vc-redist#visual-studio-2015-2017-2019-and-2022] は含まれません。これを提供するのはアプリケーションのインストーラの責務です。そのランタイムは既に以前にユーザのシステムにインストール済みかもしれませんし、Windows Update により自動で更新されているかもしれません。このことはシステムディレクトリに ucrtbase.dll があるか探せばわかります。

サードパーティのパッケージはアプリケーションのインストーラによって、埋め込み用配布と同じ場所にインストールされるべきです。通常の Python インストレーションのように依存性管理に pip を使うことは、この配布ではサポートされません。ですが、ちょっとした注意を払えば、自動更新のために pip を含めて利用することはできるかもしれません。一般的には、ユーザに更新を提供する前に開発者が新しいバージョンとの互換性を保証できるよう、サードパーティーのパッケージはアプリケーションの一部として扱われるべきです ("vendoring")。

この配布の 2 つのお勧めできるユースケースを、以下で説明します。

4.4.1. Python アプリケーション

Python で記述された、必ずしもユーザにその事実を意識させる必要のないアプリケーションです。埋め込み用配布はこのケースで、インストールパッケージ内に Python のプライベートバージョンを含めるのに使えるでしょう。その事実がどのように透過的であるべきかに依存して (あるいは逆に、どのようにプロフェッショナルにみえるべきか)、2 つの選択肢があります。

ランチャとなる特別な実行ファイルを使うことはちょっとしたコーディングを必要としますが、ユーザにとっては最も透過的なユーザ体験となります。カスタマイズされたランチャでは、何もしなければ Python で実行されるプログラムの明白な目印はありません; アイコンはカスタマイズし、会社名やバージョン情報を指定し、ファイルの関連付けがそれに相応しく振舞うようにできます。ほとんどのケースではカスタムランチャは、ハードコードされたコマンドライン文字列で単純に Py_Main を呼び出すので済むはずです。

より簡単なアプローチは、 python.exe または pythonw.exe を必要なコマンドライン引数とともに直接呼び出すバッチファイルかショートカットを提供することです。この場合、そのアプリケーションは実際の名前ではなく Python であるようにみえるので、ほかに動作している Python プロセスやファイルの関連付けと区別するのにユーザが困るかもしれません。

後者のアプローチではパッケージは、パス上で利用可能であることを保証するために、Python 実行ファイルと同じディレクトリにインストールされるべきです。特別なランチャの場合はアプリケーション起動前に検索パスを指定する機会があるので、パッケージはほかの場所に配置できます。

4.4.2. Python の埋め込み

ネイティブコードで書かれ、時々スクリプト言語のようなものを必要とするようなアプリケーションです。Python 埋め込み用の配布はこの目的に使えます。一般的に、アプリケーションの大半がネイティブコード内にあり、一部が python.exe を呼び出すか、直接的に python3.dll を使います。どちらのケースでも、ロード可能な Python インタプリタを提供するのには、埋め込み用の配布を展開してアプリケーションのインストレーションのサブディレクトリに置くことで十分です。

アプリケーションが使うパッケージは、インタプリタ初期化前に検索パスを指定する機会があるので、任意の場所にインストールできます。また、埋め込み用配布を使うのと通常の Python インストレーションを使うのとでの根本的な違いはありません。

4.5. 別のバンドル

標準の CPython の配布物の他に、追加の機能を持っている修正されたパッケージがあります。以下は人気のあるバージョンとそのキーとなる機能です:

ActivePython [https://www.activestate.com/products/python/]

マルチプラットフォーム互換のインストーラー、ドキュメント、 PyWin32

Anaconda [https://www.anaconda.com/download/]

人気のある (numpy, scipy や pandas のような) 科学系モジュールと、パッケージマネージャ conda 。

Enthought Deployment Manager [https://www.enthought.com/edm/]

"The Next Generation Python Environment and Package Manager".

Previously Enthought provided Canopy, but it reached end of life in 2016 [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].

WinPython [https://winpython.github.io/]

ビルド済みの科学系パッケージと、パッケージのビルドのためのツールを含む、Windows 固有のディストリビューション。

これらパッケージは Python や他のライブラリの最新バージョンが含まれるとは限りませんし、コア Python チームはこれらを保守もしませんしサポートもしませんのでご理解ください。

4.6. Python を構成する

コマンドプロンプトより便利に Python を実行するために、Windows のデフォルトの環境変数をいくつか変えたいと思うかもしれません。インストーラは PATH と PATHEXT 変数を構成させるオプションを提供してはいますが、これは単独のシステムワイドなインストレーションの場合にだけ頼りになるものです。もしもあなたが定常的に複数バージョンの Python を使うのであれば、 Windows の Python ランチャ の利用を検討してください。

4.6.1. 補足: 環境変数の設定

Windows では、環境変数を恒久的にユーザレベルとシステムレベルの両方で設定でき、あるいはコマンドプロンプトから一時的にも設定できます。

一時的に環境変数を設定するには、コマンドプロンプトを開き set コマンドを使います:

C:\>set PATH=C:\Program Files\Python 3.9;%PATH%
C:\>set PYTHONPATH=%PYTHONPATH%;C:\My_python_lib
C:\>python

これらの変更は、以降に実行される同じコンソール内で実行される任意のコマンドに適用され、また、そのコンソールから開始するすべてのアプリケーションに引き継がれます。

パーセント記号で変数名を囲んだものは既存の変数の値で展開されるので、新しい値を最初にも最後にも追加することができます。 python.exe が入っているディレクトリを PATH に追加することは、Python の適切なバージョンが起動するように保証するための一般的な方法です。

デフォルトの環境変数を恒久的に変更するには、「スタート」をクリックして検索ボックスで「環境変数を編集」を検索するか、(コンピュータのプロパティなどから) システムの詳細設定 を開いて 環境変数の設定 ボタンをクリックしてください。これで立ち上がるダイアログで、ユーザ環境変数とシステム環境変数を追加したり修正したりできます。システム変数を変更するにはあなたのマシンへの制限のないアクセス (つまり管理者権限) が必要です。

注釈

Windows はシステム変数の 後ろに ユーザ変数を結合します。この振る舞いにより PATH の修正時に期待とは異なる結果になることがあります。

The PYTHONPATH variable is used by all versions of Python, so you should not permanently configure it unless the listed paths only include code that is compatible with all of your installed Python versions.

参考

https://learn.microsoft.com/ja-jp/windows/win32/procthread/environment-variables

Windows の環境変数の概要

https://learn.microsoft.com/ja-jp/windows-server/administration/windows-commands/set_1

一時的に環境変数を変更するための set コマンドについて

https://learn.microsoft.com/ja-jp/windows-server/administration/windows-commands/setx

恒久的に環境変数を変更するための setx コマンドについて。

4.6.2. Python 実行ファイルを見つける

バージョン 3.5 で変更.

自動的に作成される Python インタープリタのスタートメニュー項目を使うだけでなく、Python をコマンドプロンプトから起動したいと思うかもしれません。インストーラにはそのための設定を行うオプションがあります。

インストーラの最初のページに "Add Python to PATH" というラベルのオプションがあり、これを選択するとインストーラはインストール場所を環境変数 PATH に追加します。 Scripts\ フォルダの場所も追加されます。これによりコマンドプロンプトから python とタイプしてインタプリタを起動したり、 pip とタイプしてパッケージインストーラを起動したりできます。コマンドラインからの起動なので、スクリプトをコマンドライン引数付きで起動することもできます。コマンドライン の文章を参照して下さい。

インストール時にこのオプションを有効にしていなかったとしても、インストーラを再度実行して「Modify」を選んで、それを有効にし直せます。あるいはそうせずとも、 PATH 変数は手動で修正できます。 補足: 環境変数の設定 を参照してください。環境変数 PATH には Python インストールディレクトリを含む必要があります。ほかのエントリとはセミコロンで区切って繋いでください。これの実例は以下のようになります (以下最初の 2 つのエントリは既に存在しているものと仮定しています):

C:\WINDOWS\system32;C:\WINDOWS;C:\Program Files\Python 3.9

4.7. UTF-8 モード

Added in version 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. 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 Python UTF-8 Mode to change the default text encoding to UTF-8. You can enable the Python UTF-8 Mode via the -X utf8 command line option, or the PYTHONUTF8=1 environment variable. See PYTHONUTF8 for enabling UTF-8 mode, and 補足: 環境変数の設定 for how to modify environment variables.

When the Python UTF-8 Mode is enabled, you can still use the system encoding (the ANSI Code Page) via the "mbcs" codec.

Note that adding 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 -X utf8 command line option.

注釈

Even when UTF-8 mode is disabled, Python uses UTF-8 by default on Windows for:

Console I/O including standard I/O (see PEP 528 [https://peps.python.org/pep-0528/] for details).

The filesystem encoding (see PEP 529 [https://peps.python.org/pep-0529/] for details).

4.8. Windows の Python ランチャ

Added in version 3.3.

Windows の Python ランチャは、異なる Python のバージョンの位置の特定と実行を助けるユーティリティです。スクリプト (またはコマンドライン) で特定の Python のバージョンの設定を与えられると、位置を特定し、そのバージョンを実行します。

環境変数 PATH による方法と違って、このランチャは Python の一番適切なバージョンを、正しく選択します。このランチャはシステムワイドなものよりもユーザごとのインストレーションの方を優先し、また、新しくインストールされた順よりも言語のバージョンを優先します。

ランチャのオリジナルの仕様は PEP 397 [https://peps.python.org/pep-0397/] にあります。

4.8.1. 最初に

4.8.1.1. コマンドラインから起動する

バージョン 3.6 で変更.

System-wide installations of Python 3.3 and later will put the launcher on your 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:

py

インストールされている最新バージョンの Python が起動するはずです。通常どおりに終了することもできますし、追加のコマンドライン引数を指定して直接 Python に渡すこともできます。

If you have multiple versions of Python installed (e.g., 3.7 and 3.12) you will have noticed that Python 3.12 was started - to launch Python 3.7, try the command:

py -3.7

If you want the latest version of Python 2 you have installed, try the command:

py -2

If you see the following error, you do not have the launcher installed:

'py' is not recognized as an internal or external command,
operable program or batch file.

The command:

py --list

displays the currently installed version(s) of Python.

The -x.y argument is the short form of the -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 PEP 514 [https://peps.python.org/pep-0514/] will be discoverable. The --list command lists all available runtimes using the -V: format.

When using the -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:

# 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

The short form of the argument (-3) only ever selects from core Python releases, and not other distributions. However, the longer form (-V:3) will select from any.

The Company is matched on the full string, case-insenitive. The Tag is matched oneither the full string, or a prefix, provided the next character is a dot or a hyphen. This allows -V:3.1 to match 3.1-32, but not 3.10. Tags are sorted using numerical ordering (3.10 is newer than 3.1), but are compared using text (-V:3.01 does not match 3.1).

4.8.1.2. 仮想環境 (Virtual environments)

Added in version 3.5.

(標準ライブラリの venv モジュールか外部ツール virtualenv で作った) 仮想環境がアクティブな状態で Python の明示的なバージョンを指定せずにランチャを起動すると、ランチャはグローバルなインタプリタではなくその仮想環境のものを実行します。グローバルなほうのインタプリタを実行するには、仮想環境の動作を停止するか、または明示的にグローバルな Python バージョンを指定してください。

4.8.1.3. スクリプトから起動する

テスト用の Python スクリプトを作成しましょう。hello.py という名前で以下の内容のファイルを作成してください

#! python
import sys
sys.stdout.write("hello from Python %s\n" % (sys.version,))

hello.py が存在するディレクトリで、下記コマンドを実行してください:

py hello.py

インストールされている最新の Python 2.x のバージョン番号が表示されるはずです。では、1行目を以下のように変更してみてください:

#! python3

コマンドを再実行すると、今度は最新の Python 3.x の情報が表示されるはずです。これまでのコマンドラインの例と同様に、より細かいバージョン修飾子を指定することもできます。Python 3.7 がインストールされている場合、最初の行を #! python3.7 に変更すると、3.7 のバージョン情報が表示されるはずです。

コマンドからの呼び出しとは異なり、後ろに何もつかない "python" はインストールされている Python2.x の最新バージョンを利用することに注意してください。これは後方互換性と、 python が一般的に Python 2 を指すUnix との互換性のためです。

4.8.1.4. ファイルの関連付けから起動する

インストール時に、ランチャは Python ファイル (すなわち .py, .pyw, .pyc ファイル) に関連付けられたはずです。そのため、これらのファイルを Windows のエクスプローラーでダブルクリックした際はランチャが使われ、上で述べたのと同じ機能を使ってスクリプトが使われるべきバージョンを指定できるようになります。

このことによる重要な利点は、単一のランチャが先頭行の内容によって複数の Python バージョンを同時にサポートできることです。

4.8.2. シェバン (shebang) 行

スクリプトファイルの先頭の行が #! で始まっている場合は、その行はシェバン (shebang) 行として知られています。 Linux や他の Unix 系 OS はこうした行をもともとサポートしているため、それらのシステムでは、スクリプトがどのように実行されるかを示すために広く使われます。 Windows の Python ランチャは、Windows 上の Python スクリプトが同じ機能を使用できるようにし、上の例ではそれらの機能の使用法を示しています。

Python スクリプトのシェバン行を Unix-Windows 間で移植可能にするため、このランチャは、どのインタプリタが使われるかを指定するための大量の '仮想' コマンドをサポートしています。サポートされる仮想コマンドには以下のものがあります:

/usr/bin/env

/usr/bin/python

/usr/local/bin/python

python

具体的に、もしスクリプトの1行目が

#! /usr/bin/python

The default Python 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 /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. /usr/bin/python3.7-32 will request usage of the 32-bit python 3.7.

Added in version 3.7: python ランチャの 3.7 からは、末尾に "-64" を付けて 64-bit 版を要求できます。さらに、マイナーバージョン無しのメジャーバージョンとアーキテクチャだけ (例えば、 /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 -V:TAG argument with the complete tag.

The /usr/bin/env form of shebang line has one further special property. Before looking for installed Python interpreters, this form will search the executable PATH for a Python executable matching the name provided as the first argument. This corresponds to the behaviour of the Unix env program, which performs a PATH search. If an executable matching the first argument after the env command cannot be found, but the argument starts with python, it will be handled as described for the other virtual commands. The environment variable PYLAUNCHER_NO_SEARCH_PATH may be set (to any value) to skip this search of PATH.

Shebang lines that do not match any of these patterns are looked up in the [commands] section of the launcher's .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).

[commands]
/bin/xpython=C:\Program Files\XPython\python.exe

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.

4.8.3. シェバン行の引数

シェバン行では Python インタプリタに渡される追加の引数を指定することもできます。たとえば、シェバン行に以下のように書かれているとしましょう:

#! /usr/bin/python -v

この場合、Python は -v オプション付きで起動するでしょう

4.8.4. カスタマイズ

4.8.4.1. INI ファイルによるカスタマイズ

ランチャは2つの .ini ファイルを探しに行きます。具体的には、現在のユーザーのアプリケーションデータディレクトリ (%LOCALAPPDATA% または $env:LocalAppData) の py.ini と、ランチャと同じディレクトリにある py.ini です。'コンソール' 版のランチャ (つまり py.exe) と 'Windows' 版のランチャ (つまり pyw.exe) は同一の .ini ファイルを使用します。

"application data" ディレクトリで指定された設定は、実行ファイルの隣にあるものより優先されます。そのため、ランチャの隣にある .ini ファイルへの書き込みアクセスができないユーザは、グローバルな .ini ファイル内のコマンドを上書き (override) できます。

4.8.4.2. デフォルトのPythonバージョンのカスタマイズ

どのバージョンの Python をコマンドで使用するかを定めるため、バージョン修飾子がコマンドに含められることがあります。バージョン修飾子はメジャーバージョン番号で始まり、オプションのピリオド ('.') とマイナーバージョン指定子がそれに続きます。さらに、 "-32" や "-64" を追記して 32-bit あるいは 64-bit のどちらの実装が要求されるかを指示できます。

たとえば、#!python というシェバン行はバージョン修飾子を含みませんが、#!python3 はメジャーバージョンを指定するバージョン修飾子を含みます。

コマンドにバージョン修飾子が見つからない場合、環境変数 PY_PYTHON を設定して、デフォルトのバージョン修飾子を指定できます。設定されていない場合、デフォルト値は "3" です。この変数には "3", "3.7", "3.7-32", "3.7-64" のような任意の値をコマンドラインから指定できます。 ("-64" オプションは Python 3.7 以降のランチャでしか使えないことに注意してください。)

マイナーバージョン修飾子が見つからない場合、環境変数 PY_PYTHON{major} (ここで {major} は、上記で決定された現在のメジャーバージョン修飾子) を設定して完全なバージョンを指定することができます。そういったオプションが見つからなければ、ランチャはインストール済みの Python バージョンを列挙して、見つかったそのメジャーバージョン向けマイナーリリースのうち最新のものを使用します。保証されているわけではありませんが、通常はそのメジャーバージョン系で最も後にインストールしたバージョンになります。

64-bit Windows で、同一の (major.minor) Python バージョンの 32-bit と 64-bit の両方の実装がインストールされていた場合、64-bit バージョンのほうが常に優先されます。これはランチャが 32-bit と 64-bit のどちらでも言えることで、32-bit のランチャは、指定されたバージョンが使用可能であれば、64-bit の Python を優先して実行します。これは、どのバージョンが PC にインストールされているかのみでランチャの挙動を予見でき、それらがインストールされた順番に関係なくなる (つまり最後にインストールされた Python とランチャが 32-bit か 64-bit かを知らなくともよい) ようにするためです。上に記したとおり、オプションの "-32", "-64" サフィックスでこの挙動を変更できます。

例:

関連するオプションが設定されていない場合、python および python2 コマンドはインストールされている最新の Python 2.x バージョンを使用し、python3 コマンドはインストールされている最新の Python 3.x を使用します。

python3.7 コマンドは、バージョンが完全に指定されているため、全くオプションを参照しません。

PY_PYTHON=3 の場合、python および python3 コマンドはともにインストールされている最新の Python 3 を使用します。

PY_PYTHON=3.7-32 の場合、python コマンドは 32-bit 版の 3.7 を使用しますが、python3 コマンドはインストールされている最新の Python を使用します (メジャーバージョンが指定されているため、PY_PYTHON は全く考慮されません。)

PY_PYTHON=3 で PY_PYTHON3=3.7 の場合、python および python3 はどちらも 3.7 を使用します

環境変数に加え、同じ設定をランチャが使う INI ファイルで構成することができます。INI ファイルの該当するセクションは [defaults] と呼ばれ、キー名は環境変数のキー名から PY_ という接頭辞を取ったものと同じです (INI ファイルのキー名は大文字小文字を区別しないことにご注意ください)。環境変数の内容は INI ファイルでの指定を上書きします。

例えば:

PY_PYTHON=3.7 と設定することは、INI ファイルに下記が含まれることと等価です:

[defaults]
python=3.7

PY_PYTHON=3 と PY_PYTHON3=3.7 を設定することは、INI ファイルに下記が含まれることと等価です:

[defaults]
python=3
python3=3.7

4.8.5. 診断

If an environment variable 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.

4.8.6. Dry Run

If an environment variable 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.

4.8.7. Install on demand

If an environment variable 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 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 PYLAUNCHER_DRYRUN).

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

名前

値

説明

RC_BAD_VENV_CFG

107

A pyvenv.cfg was found but is corrupt.

RC_CREATE_PROCESS

101

Failed to launch Python.

RC_INSTALLING

111

An install was started, but the command will need to be re-run after it completes.

RC_INTERNAL_ERROR

109

Unexpected error. Please report a bug.

RC_NO_COMMANDLINE

108

Unable to obtain command line from the operating system.

RC_NO_PYTHON

103

Unable to locate the requested version.

RC_NO_VENV_CFG

106

A pyvenv.cfg was required but not found.

4.9. モジュールの検索

These notes supplement the description at The initialization of the sys.path module search path with detailed Windows notes.

._pth ファイルが見付からなかったときは、 Windows では sys.path は次のように設定されます:

最初に空のエントリが追加されます。これはカレントディレクトリを指しています。

その次に、 PYTHONPATH 環境変数が存在するとき、 環境変数 で解説されているように追加されます。 Windows ではドライブ識別子 (C:\ など)と区別するために、この環境変数に含まれるパスの区切り文字はセミコロンでなければならない事に注意してください。

追加で "アプリケーションのパス" を HKEY_CURRENT_USER か HKEY_LOCAL_MACHINE の中の \SOFTWARE\Python\PythonCore{version}\PythonPath のサブキーとして登録することができます。サブキーはデフォルト値としてセミコロンで区切られたパス文字列を持つことができ、書くパスが sys.path に追加されます。 (既存のインストーラーはすべて HKLM しか利用しないので、 HKCU は通常空です)

PYTHONHOME が設定されている場合、それが "Python Home" として扱われます。それ以外の場合、 "Python Home" を推定するために Python の実行ファイルのパスから "目印ファイル" (Lib\os.py または pythonXY.zip) が探されます。 Python home が見つかった場合、そこからいくつかのサブディレクトリ (Lib, plat-win など) が sys.path に追加されます。見つからなかった場合、コアとなる Python path はレジストリに登録された PythonPath から構築されます。

Python Home が見つからず、環境変数 PYTHONPATH が指定されず、レジストリエントリが見つからなかった場合、関連するデフォルトのパスが利用されます (例: .\Lib;.\plat-win など)。

メインの実行ファイルと同じ場所か一つ上のディレクトリに pyvenv.cfg がある場合、以下の異なった規則が適用されます:

PYTHONHOME が設定されておらず、 home が絶対パスの場合、home 推定の際メインの実行ファイルから推定するのではなくこのパスを使います。

結果としてこうなります:

python.exe かそれ以外の Python ディレクトリにある .exe ファイルを実行したとき (インストールされている場合でも PCbuild から直接実行されている場合でも) core path が利用され、レジストリ内の core path は無視されます。それ以外のレジストリの "application paths" は常に読み込まれます。

Python が他の .exe ファイル (他のディレクトリに存在する場合や、COM経由で組み込まれる場合など) にホストされている場合は、 "Python Home" は推定されず、レジストリにある core path が利用されます。それ以外のレジストリの "application paths" は常に読み込まれます。

Python がその home を見つけられず、レジストリの値もない場合 (これはいくつかのとてもおかしなインストレーションセットアップの凍結された .exe)、パスは最小限のデフォルトとして相対パスが使われます。

自身のアプリケーションや配布物に Python をバンドルしたい場合には、以下の助言 (のいずれかまたは組合せ) によりほかのインストレーションとの衝突を避けることができます:

Include a ._pth file alongside your executable containing the directories to include. This will ignore paths listed in the registry and environment variables, and also ignore site unless import site is listed.

If you are loading python3.dll or python37.dll in your own executable, explicitly call Py_SetPath() or (at least) Py_SetProgramName() before Py_Initialize().

自身のアプリケーションから python.exe を起動する前に、 PYTHONPATH をクリアしたり上書きし、 PYTHONHOME をセットしてください。

If you cannot use the previous suggestions (for example, you are a distribution that allows people to run python.exe directly), ensure that the landmark file (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.)

これらはシステムワイドにインストールされたファイルが、あなたのアプリケーションにバンドルされた標準ライブラリのコピーに優先しないようにします。これをしなければあなたのアプリケーションのユーザは、何かしら問題を抱えるかもしれません。上で列挙した最初の提案が最善です。ほかのものはレジストリ内の非標準のパスやユーザの site-packages の影響を少し受けやすいからです。

バージョン 3.6 で変更: Add ._pth file support and removes applocal option from pyvenv.cfg.

バージョン 3.6 で変更: Add pythonXX.zip as a potential landmark when directly adjacent to the executable.

バージョン 3.6 で非推奨: Modules specified in the registry under Modules (not PythonPath) may be imported by importlib.machinery.WindowsRegistryFinder. This finder is enabled on Windows in 3.6.0 and earlier, but may need to be explicitly added to sys.meta_path in the future.

4.10. 追加のモジュール

Python は全プラットフォーム互換を目指していますが、 Windows にしかないユニークな機能もあります。標準ライブラリと外部のライブラリの両方で、幾つかのモジュールと、そういった機能を使うためのスニペットがあります。

Windows 固有の標準モジュールは、 MS Windows 固有のサービス に書かれています。

4.10.1. PyWin32

The PyWin32 [https://pypi.org/project/PyWin32/] module by Mark Hammond is a collection of modules for advanced Windows-specific support. This includes utilities for:

Component Object Model [https://docs.microsoft.com/en-us/windows/win32/com/component-object-model--com--portal] (COM)

Win32 API 呼び出し

レジストリ

イベントログ

Microsoft Foundation Classes [https://docs.microsoft.com/en-us/cpp/mfc/mfc-desktop-applications] (MFC) ユーザーインターフェイス

PythonWin [https://web.archive.org/web/20060524042422/https://www.python.org/windows/pythonwin/] は PyWin32 に付属している、サンプルのMFCアプリケーションです。これはビルトインのデバッガを含む、組み込み可能なIDEです。

参考

Win32 How Do I...? [http://timgolden.me.uk/python/win32_how_do_i.html]

by Tim Golden

Python and COM [https://www.boddie.org.uk/python/COM.html]

by David and Paul Boddie

4.10.2. cx_Freeze

cx_Freeze [https://cx-freeze.readthedocs.io/en/latest/] wraps Python scripts into executable Windows programs (*.exe files). When you have done this, you can distribute your application without requiring your users to install Python.

4.11. Windows 上で Python をコンパイルする

CPython を自分でコンパイルしたい場合、最初にすべきことは ソース [https://www.python.org/downloads/source/] を取得することです。最新リリース版のソースか、新しい チェックアウト [https://devguide.python.org/setup/#get-the-source-code] をダウンロードできます。

ソースツリーには Microsoft Visual Studio でのビルドのソリューションファイルとプロジェクトファイルが含まれていて、これが公式の Python リリースに使われているコンパイラです。これらファイルは PCbuild ディレクトリ内にあります。

ビルドプロセスについての一般的な情報は、PCbuild/readme.txt にあります。

拡張モジュールについては、 Windows 上での C および C++ 拡張モジュールのビルド を参照してください。

4.12. ほかのプラットフォーム

Python の継続的な開発の中で、過去にサポートされていた幾つかのプラットフォームが (ユーザーや開発者の不足のために) サポートされなくなっています。すべてのサポートされないプラットフォームについての詳細は PEP 11 [https://peps.python.org/pep-0011/] をチェックしてください。

Windows CE [https://pythonce.sourceforge.net/] is no longer supported [https://github.com/python/cpython/issues/71542] since Python 3 (if it ever was).

The Cygwin [https://cygwin.com/] installer offers to install the Python interpreter [https://cygwin.com/packages/summary/python3.html] as well

コンパイル済みインストーラが提供されているプラットフォームについての詳細な情報は Python for Windows [https://www.python.org/downloads/windows/] を参照してください。

5. Mac で Python を使う

著者:

Bob Savage <bobsavage@mac.com>

Python on a Mac running macOS is in principle very similar to Python on any other Unix platform, but there are a number of additional features such as the integrated development environment (IDE) and the Package Manager that are worth pointing out.

5.1. Getting and Installing Python

macOS used to come with Python 2.7 pre-installed between versions 10.8 and 12.3 [https://developer.apple.com/documentation/macos-release-notes/macos-12_3-release-notes#Python]. You are invited to install the most recent version of Python 3 from the Python website [https://www.python.org/downloads/macos/]. A current "universal2 binary" build of Python, which runs natively on the Mac's new Apple Silicon and legacy Intel processors, is available there.

インストールを行うといくつかのものが手に入ります:

A Python 3.12 folder in your Applications folder. In here you find IDLE, the development environment that is a standard part of official Python distributions; and Python Launcher, which handles double-clicking Python scripts from the Finder.

A framework /Library/Frameworks/Python.framework, which includes the Python executable and libraries. The installer adds this location to your shell path. To uninstall Python, you can remove these three things. A symlink to the Python executable is placed in /usr/local/bin/.

注釈

On macOS 10.8-12.3, the Apple-provided build of Python is installed in /System/Library/Frameworks/Python.framework and /usr/bin/python, respectively. You should never modify or delete these, as they are Apple-controlled and are used by Apple- or third-party software. Remember that if you choose to install a newer Python version from python.org, you will have two different but functional Python installations on your computer, so it will be important that your paths and usages are consistent with what you want to do.

IDLE includes a Help menu that allows you to access Python documentation. If you are completely new to Python you should start reading the tutorial introduction in that document.

もし他の Unix プラットフォームで Python を使い慣れている場合には Unix シェルからの Python スクリプトの実行についての節を読むことをおすすめします。

5.1.1. Python スクリプトの実行方法

Your best way to get started with Python on macOS is through the IDLE integrated development environment; see section IDE and use the Help menu when the IDE is running.

If you want to run Python scripts from the Terminal window command line or from the Finder you first need an editor to create your script. macOS comes with a number of standard Unix command line editors, vim nano among them. If you want a more Mac-like editor, BBEdit from Bare Bones Software (see https://www.barebones.com/products/bbedit/index.html) are good choices, as is TextMate (see https://macromates.com). Other editors include MacVim (https://macvim.org) and Aquamacs (https://aquamacs.org).

ターミナルからスクリプトを実行するには /usr/local/bin がシェルのパスに含まれていることを確認してください。

Finder からスクリプトを実行するのには 2 つの方法があります:

Drag it to Python Launcher.

Select Python Launcher as the default application to open your script (or any .py script) through the finder Info window and double-click it. Python Launcher has various preferences to control how your script is launched. Option-dragging allows you to change these for one invocation, or use its Preferences menu to change things globally.

5.1.2. GUI でスクリプトを実行

古いバージョンの Python には、気を付けておかないといけない macOS の癖があります: Aqua ウィンドウマネージャとやりとりをする (別の言い方をすると GUI を持つ) プログラムは特別な方法で実行する必要があります。そのようなスクリプトを実行するには python ではなく pythonw を使ってください。

Python 3.9 では、 python と pythonw のどちらでも使えます。

5.1.3. Configuration

Python on macOS honors all standard Unix environment variables such as PYTHONPATH, but setting these variables for programs started from the Finder is non-standard as the Finder does not read your .profile or .cshrc at startup. You need to create a file ~/.MacOSX/environment.plist. See Apple's Technical Q&A QA1067 [https://developer.apple.com/library/archive/qa/qa1067/_index.html] for details.

For more information on installation Python packages, see section 追加の Python パッケージのインストール.

5.2. IDE

Python ships with the standard IDLE development environment. A good introduction to using IDLE can be found at https://www.hashcollision.org/hkn/python/idle_intro/index.html.

5.3. 追加の Python パッケージのインストール

This section has moved to the Python Packaging User Guide [https://packaging.python.org/en/latest/tutorials/installing-packages/].

5.4. GUI プログラミング

Python で Mac 上の GUI アプリケーションをビルドする方法がいくつかあります。

PyObjC is a Python binding to Apple's Objective-C/Cocoa framework, which is the foundation of most modern Mac development. Information on PyObjC is available from pyobjc [https://pypi.org/project/pyobjc/].

Python 標準の GUI ツールキットは、クロスプラットフォームの Tk ツールキット (https://www.tcl.tk) 上に構築された tkinter です。 Tk の Aqua ネイティブバージョンは Apple が macOS にバンドルしており、最新バージョンは https://www.activestate.com からダウンロードおよびインストールできます; またソースからビルドすることもできます。

A number of alternative macOS GUI toolkits are available:

PySide [https://www.qt.io/qt-for-python]: Official Python bindings to the Qt GUI toolkit [https://qt.io].

PyQt [https://riverbankcomputing.com/software/pyqt/intro]: Alternative Python bindings to Qt.

Kivy [https://kivy.org]: A cross-platform GUI toolkit that supports desktop and mobile platforms.

Toga [https://toga.readthedocs.io]: Part of the BeeWare Project [https://beeware.org]; supports desktop, mobile, web and console apps.

wxPython [https://www.wxpython.org]: A cross-platform toolkit that supports desktop operating systems.

5.5. Distributing Python Applications

A range of tools exist for converting your Python code into a standalone distributable application:

py2app [https://pypi.org/project/py2app/]: Supports creating macOS .app bundles from a Python project.

Briefcase [https://briefcase.readthedocs.io]: Part of the BeeWare Project [https://beeware.org]; a cross-platform packaging tool that supports creation of .app bundles on macOS, as well as managing signing and notarization.

PyInstaller [https://pyinstaller.org/]: A cross-platform packaging tool that creates a single file or folder as a distributable artifact.

5.6. 他のリソース

The Pythonmac-SIG mailing list is an excellent support resource for Python users and developers on the Mac:

https://www.python.org/community/sigs/current/pythonmac-sig/

他の役に立つリソースは MacPython wiki です:

https://wiki.python.org/moin/MacPython

6. エディタと IDE

Python プログラミング言語をサポートする IDE はたくさんあります。多くのエディタや IDE にはシンタックスハイライト機能、デバッグツール、 PEP 8 [https://peps.python.org/pep-0008/] チェック機能があります。

包括的な一覧を見るには、 Python Editors [https://wiki.python.org/moin/PythonEditors] や Integrated Development Environments [https://wiki.python.org/moin/IntegratedDevelopmentEnvironments] を訪れてください。

Python 言語リファレンス

このリファレンスマニュアルでは、Python 言語の文法と、 "コアとなるセマンティクス" について記述します。このマニュアルはそっけない書き方かもしれませんが、正確さと完全さを優先しています。必須でない組み込みオブジェクト型や組み込み関数、組み込みモジュールに関するセマンティクスは、 Python 標準ライブラリ で述べられています。形式ばらない Python 言語入門には、 Python チュートリアル を参照してください。 C 言語あるいはC++プログラマ向けには、このマニュアルとは別に二つのマニュアルがあります。 Python インタプリタの拡張と埋め込み では、Python 拡張モジュールを書くための高レベルな様式について述べています。また、 Python/C API リファレンスマニュアル では、C/C++ プログラマが利用できるインターフェースについて詳細に記述しています。

1. はじめに

1.1. 別のPythonの実装

1.2. 本マニュアルにおける表記法

2. 字句解析

2.1. 行構造

2.2. その他のトークン

2.3. 識別子 (identifier) およびキーワード (keyword)

2.4. リテラル

2.5. 演算子

2.6. デリミタ (delimiter)

3. データモデル

3.1. オブジェクト、値、および型

3.2. 標準型の階層

3.3. 特殊メソッド名

3.4. コルーチン

4. 実行モデル

4.1. プログラムの構造

4.2. 名前づけと束縛 (naming and binding)

4.3. 例外

5. インポートシステム

5.1. importlib

5.2. パッケージ

5.3. 検索

5.4. ロード

5.5. パスベース・ファインダー

5.6. 標準のインポートシステムを置き換える

5.7. Package Relative Imports

5.8. __main__ に対する特別な考慮

5.9. 参考資料

6. 式 (expression)

6.1. 算術変換 (arithmetic conversion)

6.2. アトム、原子的要素 (atom)

6.3. プライマリ

6.4. Await 式

6.5. べき乗演算 (power operator)

6.6. 単項算術演算とビット単位演算 (unary arithmetic and bitwise operation)

6.7. 二項算術演算 (binary arithmetic operation)

6.8. シフト演算 (shifting operation)

6.9. ビット単位演算の二項演算 (binary bitwise operation)

6.10. 比較

6.11. ブール演算 (boolean operation)

6.12. 代入式

6.13. 条件式 (Conditional Expressions)

6.14. ラムダ (lambda)

6.15. 式のリスト

6.16. 評価順序

6.17. 演算子の優先順位

7. 単純文 (simple statement)

7.1. 式文 (expression statement)

7.2. 代入文 (assignment statement)

7.3. assert 文

7.4. pass 文

7.5. del 文

7.6. return 文

7.7. yield 文

7.8. raise 文

7.9. break 文

7.10. continue 文

7.11. import 文

7.12. global 文

7.13. nonlocal 文

7.14. The type statement

8. 複合文 (compound statement)

8.1. if 文

8.2. while 文

8.3. for 文

8.4. try 文

8.5. with 文

8.6. match 文

8.7. 関数定義

8.8. クラス定義

8.9. コルーチン

8.10. Type parameter lists

9. トップレベル要素

9.1. 完全な Python プログラム

9.2. ファイル入力

9.3. 対話的入力

9.4. 式入力

10. 完全な文法仕様

1. はじめに

このリファレンスマニュアルは、Python プログラミング言語自体に関する記述です。チュートリアルとして書かれたものではありません。

私は本マニュアルをできるだけ正確に書こうとする一方で、文法や字句解析以外の全てについて、形式化された仕様記述ではなく英語を使うことにしました。そうすることで、このドキュメントが平均的な読者にとってより読みやすくなっているはずですが、ややあいまいな部分も残っていることでしょう。従って、もし読者のあなたが火星から来ている人で、このドキュメントだけから Python を再度実装しようとしているのなら、色々と推測しなければならないことがあり、実際にはおそらく全く別の言語を実装する羽目になるでしょう。逆に、あなたが Python を利用しており、Python 言語のある特定の領域において、厳密な規則が何か疑問に思った場合、その答えはこのドキュメントで確実に見つけられることでしょう。もしより形式化された言語定義をお望みなら、あなたの時間を提供していただいてかまいません --- もしくは、クローン生成装置でも発明してください :-)。

実装に関する詳細を言語リファレンスのドキュメントに載せすぎるのは危険なことです --- 実装は変更されるかもしれず、同じ言語でも異なる実装は異なった動作をするかもしれないからです。一方、CPython が広く使われている一つの Python 実装 (別の実装も支持され続けていますが) なので、特定のクセについては、特に実装によって何らかの制限が加えられている場合には、触れておく価値があります。従って、このテキスト全体にわたって短い "実装に関する注釈 (imprementation notes)" がちりばめられています。

Python 実装はいずれも、数々の組み込みモジュールと標準モジュールが付属します。それらについては、 Python 標準ライブラリ でドキュメント化されています。いくつかの組み込みモジュールについては、言語定義と重要なかかわりをもっているときについて触れています。

1.1. 別のPythonの実装

Pythonの実装としては、群を抜いて有名な実装がひとつ存在しています。それ以外の実装に関しても、特定のユーザ間で興味が持たれています。

よく知られている実装には以下のものがあります:

CPython

これは最も保守されている初代のPython実装で、C言語で書かれています。ほとんどの場合、言語の新機能がいち早く実装されます。

Jython

Javaで実装されたPythonです。この実装はJavaアプリケーションのためのスクリプト言語として、もしくはJavaクラスライブラリを使ったアプリケーションを作成するために使用することができます。また、Javaライブラリのテストを作成するためにもしばしば使用されています。さらなる情報については the Jython website [https://www.jython.org/] を参照してください。

Python for .NET

この実装は内部ではCPythonを使用していますが、 .NETアプリケーションによって管理されているので、 .NETライブラリを参照することが可能です。この実装はBrian Lloydによって作成されました。さらなる情報については、 Python for .NET home page [https://pythonnet.github.io/] を参照してください。

IronPython

.NETでPythonを使用するためのもう一つの実装です。Python.NETとは異なり、完全にILを生成することができるPythonの実装あり、直接Pythonコードを.NETアセンブリにコンパイルします。これはJythonの初代の開発者であるJim Huguninによって作られました。さらなる情報については the IronPython website [https://ironpython.net/] を参照してください。

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 [https://www.pypy.org/].

これらの各実装はこのマニュアルで文書化された言語とは多少異なっている、もしくは、標準のPythonドキュメントと何処が異なっているかを定めた情報が公開されているでしょう。あなたが使用している実装上で、代替手段を使う必要があるかどうかを判断するためには、各実装の仕様書を参照してください。

1.2. 本マニュアルにおける表記法

The descriptions of lexical analysis and syntax use a modified Backus–Naur form (BNF) [https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form] grammar notation. This uses the following style of definition:

name      ::=  lc_letter (lc_letter | "_")*
lc_letter ::=  "a"..."z"

最初の行は、name が lc_letter の後ろにゼロ個またはそれ以上の lc_letter とアンダースコアが続いたものであることを示しています。そして、lc_letter は 'a' から 'z' までの何らかの文字一字であることを示します。 (この規則は、このドキュメントに記述されている字句規則と構文規則において定義されている名前 (name) で一貫して使われています)。

各規則は name (規則によって定義されているものの名前) と ::= から始まります。垂直線 (|) は、複数の選択項目を分かち書きするときに使います; この記号は、この記法において最も結合優先度の低い演算子です。アスタリスク (*) は、直前にくる要素のゼロ個以上の繰り返しを表します; 同様に、プラス (+) は一個以上の繰り返しで、角括弧 ([ ]) に囲われた字句は、字句がゼロ個か一個出現する (別の言い方をすれば、囲いの中の字句はオプションである) ことを示します。* および + 演算子の結合範囲は可能な限り狭くなっています; 字句のグループ化には丸括弧を使います。リテラル文字列はクオートで囲われます。空白はトークンを分割しているときのみ意味を持ちます。規則は通常、一行中に収められています; 多数の選択肢のある規則は、最初の行につづいて、垂直線の後ろに各々別の行として記述されます。

(上の例のような) 字句定義では、他に二つの慣習が使われています: 三つのドットで区切られている二つのリテラル文字は、二つの文字の ASCII 文字コードにおける (包含的な) 範囲から文字を一字選ぶことを示します。各カッコ中の字句 (<...>) は、定義済みのシンボルを記述する非形式的なやりかたです; 例えば、'制御文字' を書き表す必要があるときなどに使われることがあります。

字句と構文規則の定義の間で使われている表記はほとんど同じですが、その意味には大きな違いがあります: 字句定義は入力ソース中の個々の文字を取り扱いますが、構文定義は字句解析で生成された一連のトークンを取り扱います。次節 ("字句解析") における BNF はすべて字句定義のためのものです; それ以降の章では、構文定義のために使っています。

2. 字句解析

Python で書かれたプログラムは パーザ (parser) に読み込まれます。パーザへの入力は、 字句解析器 (lexical analyzer) によって生成された一連の トークン (token) からなります。この章では、字句解析器がファイルをトークン列に分解する方法について解説します。

Python はプログラムテキストを Unicode コードポイントとして読み込みます。ソースファイルのエンコーディングはエンコーディング宣言で与えられ、デフォルトは UTF-8 です。詳細は PEP 3120 [https://peps.python.org/pep-3120/] を参照してください。ソースファイルがデコードできなければ、 SyntaxError が送出されます。

2.1. 行構造

Python プログラムは多数の 論理行 (logical lines) に分割されます。

2.1.1. 論理行 (logical line)

論理行の終端は、トークン NEWLINE で表されます。構文上許されている場合 (複合文: compound statement 中の実行文: statement) を除いて、実行文は論理行間にまたがることはできません。論理行は一行またはそれ以上の 物理行(physical line) からなり、物理行の末尾には明示的または非明示的な 行連結(line joining) 規則が続きます。

2.1.2. 物理行 (physical line)

物理行とは、行終端コードで区切られた文字列のことです。ソースファイルやソース文字列では、各プラットフォームごとの標準の行終端コードを使用することができます。 Unix形式ではASCII LF (行送り: linefeed)文字、 Windows形式ではASCII 配列の CR LF (復帰: return に続いて行送り) 、 Macintosh形式ではASCII CR (復帰) 文字です。これら全ての形式のコードは、違うプラットフォームでも等しく使用することができます。入力の末尾も、最後の物理行の暗黙的な終端としての役割を果たします。

Pythonに埋め込む場合には、標準のC言語の改行文字の変換規則 (ASCII LFを表現した文字コード \n が行終端となります) に従って、 Python APIにソースコードを渡す必要があります。

2.1.3. コメント (Comments)

コメントは文字列リテラル内に入っていないハッシュ文字 (#) から始まり、同じ物理行の末端で終わります。非明示的な行継続規則が適用されていない限り、コメントは論理行を終端させます。コメントは構文上無視されます。

2.1.4. エンコード宣言 (encoding declaration)

Python スクリプト中の一行目か二行目にあるコメントが正規表現 coding[=:]\s*([-\w.]+) にマッチする場合、コメントはエンコード宣言として処理されます; この表現の最初のグループがソースコードファイルのエンコードを指定します。エンコード宣言は自身の行になければなりません。二行目にある場合、一行目もコメントのみの行でなければなりません。エンコード宣言式として推奨する形式は

# -*- coding: <encoding-name> -*-

これは GNU Emacs で認識できます。または

# vim:fileencoding=<encoding-name>

これは、Bram Moolenar による 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 (b'xefxbbxbf') is ignored rather than being a syntax error.

エンコーディングが宣言される場合、そのエンコーディング名は Python によって認識できなければなりません (標準エンコーディング を参照してください)。宣言されたエンコーディングは、例えば文字列リテラル、コメント、識別子などの、全ての字句解析に使われます。

2.1.5. 明示的な行継続

二つまたはそれ以上の物理行を論理行としてつなげるためには、バックスラッシュ文字 (\) を使って以下のようにします: 物理行が文字列リテラルやコメント中の文字でないバックスラッシュで終わっている場合、後続する行とつなげて一つの論理行を構成し、バックスラッシュおよびバックスラッシュの後ろにある行末文字を削除します。例えば:

if 1900 < year < 2100 and 1 <= month <= 12 \
   and 1 <= day <= 31 and 0 <= hour < 24 \
   and 0 <= minute < 60 and 0 <= second < 60:   # Looks like a valid date
        return 1

バックスラッシュで終わる行にはコメントを入れることはできません。また、バックスラッシュを使ってコメントを継続することはできません。バックスラッシュが文字列リテラル中にある場合を除き、バックスラッシュの後ろにトークンを継続することはできません (すなわち、物理行内の文字列リテラル以外のトークンをバックスラッシュを使って分断することはできません)。上記以外の場所では、文字列リテラル外にあるバックスラッシュはどこにあっても不正となります。

2.1.6. 非明示的な行継続

丸括弧 (parentheses)、角括弧 (square bracket) 、および波括弧 (curly brace) 内の式は、バックスラッシュを使わずに一行以上の物理行に分割することができます。例えば:

month_names = ['Januari', 'Februari', 'Maart',      # These are the
               'April',   'Mei',      'Juni',       # Dutch names
               'Juli',    'Augustus', 'September',  # for the months
               'Oktober', 'November', 'December']   # of the year

非明示的に継続された行にはコメントを含めることができます。継続行のインデントは重要ではありません。空の継続行を書くことができます。非明示的な継続行中には、NEWLINE トークンは存在しません。非明示的な行の継続は、三重クオートされた文字列 (下記参照) でも発生します; この場合には、コメントを含めることができません。

2.1.7. 空行

スペース、タブ、フォームフィード、およびコメントのみを含む論理行は無視されます (すなわち、NEWLINE トークンは生成されません)。文を対話的に入力している際には、空行の扱いは行読み込み-評価-出力 (read-eval-print) ループの実装によって異なることがあります。標準的な対話的インタプリタの実装では、完全な空行でできた論理行 (すなわち、空白文字もコメントも全く含まない空行) は、複数行からなる文の終端を示します。

2.1.8. インデント

論理行の行頭にある、先頭の空白 (スペースおよびタブ) の連なりは、その行のインデントレベルを計算するために使われます。インデントレベルは、実行文のグループ化方法を決定するために用いられます。

タブは (左から右の方向に) 1 つにつき 8 つのスペースで置き換えられ、置き換え後の文字数は 8 の倍数になります (Unix で使われている規則と同じになるよう意図されています)。そして、最初の非空白文字までのスペースの総数が、その行のインデントを決定します。インデントは、バックスラッシュで複数の物理行に分割できません; 最初のバックスラッシュまでの空白がインデントを決定します。

ソースファイルがタブとスペースを混在させ、その意味づけがタブのスペース換算数に依存するようなら、インデントは不合理なものとして却下されます。その場合は TabError が送出されます。

プラットフォーム間の互換性に関する注意: 非 UNIX プラットフォームにおけるテキストエディタの性質上、一つのソースファイル内でタブとインデントを混在させて使うのは賢明ではありません。また、プラットフォームによっては、最大インデントレベルを明示的に制限しているかもしれません。

フォームフィード文字が行の先頭にあっても構いません; フォームフィード文字は上のインデントレベル計算時には無視されます。フォームフィード文字が先頭の空白中の他の場所にある場合、その影響は未定義です (例えば、スペースの数を 0 にリセットするかもしれません)。

連続する行における各々のインデントレベルは、 INDENT および DEDENT トークンを生成するために使われます。トークンの生成はスタックを用いて以下のように行われます。

ファイル中の最初の行を読み出す前に、スタックにゼロが一つ積まれ (push され) ます; このゼロは決して除去 (pop) されることはありません。スタックの先頭に積まれてゆく数字は、常にスタックの末尾から先頭にかけて厳密に増加するようになっています。各論理行の開始位置において、その行のインデントレベル値がスタックの先頭の値と比較されます。値が等しければ何もしません。インデントレベル値がスタック上の値よりも大きければ、インデントレベル値はスタックに積まれ、INDENT トークンが一つ生成されます。インデントレベル値がスタック上の値よりも小さい場合、その値はスタック内のいずれかの値と 等しくなければなりません ; スタック上のインデントレベル値よりも大きい値はすべて除去され、値が一つ除去されるごとに DEDENT トークンが一つ生成されます。ファイルの末尾では、スタックに残っているゼロより大きい値は全て除去され、値が一つ除去されるごとに DEDENT トークンが一つ生成されます。

以下の例に正しく (しかし当惑させるように) インデントされた Python コードの一部を示します:

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

以下の例は、様々なインデントエラーになります:

 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

(実際は、最初の 3 つのエラーはパーザによって検出されます; 最後のエラーのみが字句解析器で見つかります --- return r のインデントは、スタックから逐次除去されていくどのインデントレベル値とも一致しません)

2.1.9. トークン間の空白

論理行の先頭や文字列の内部にある場合を除き、空白文字であるスペース、タブ、およびフォームフィードは、トークンを分割するために自由に利用することができます。二つのトークンを並べて書くと別のトークンとしてみなされてしまうような場合には、トークンの間に空白が必要となります (例えば、ab は一つのトークンですが、 a b は二つのトークンとなります)。

2.2. その他のトークン

NEWLINE、INDENT、および DEDENT の他、以下のトークンのカテゴリ: 識別子 (identifier), キーワード(keyword), リテラル, 演算子 (operator), デリミタ (delimiter) が存在します。空白文字 (上で述べた行終端文字以外) はトークンではありませんが、トークンを区切る働きがあります。トークンの解析にあいまいさが生じた場合、トークンは左から右に読んで不正でないトークンを構築できる最長の文字列を含むように構築されます。

2.3. 識別子 (identifier) およびキーワード (keyword)

識別子 (または 名前 (name)) は、以下の字句定義で記述されます。

Python における識別子の構文は、Unicode 標準仕様添付書類 UAX-31 に基づき、詳細と変更点は以下で定義します。詳しくは PEP 3131 [https://peps.python.org/pep-3131/] を参照してください。

ASCII 範囲 (U+0001..U+007F) 内では、識別子として有効な文字は Python 2.x におけるものと同じです。大文字と小文字の A から Z、アンダースコア _、先頭の文字を除く数字 0 から 9 です。

Python 3.0 は、さらに ASCII 範囲外から文字を導入します (PEP 3131 [https://peps.python.org/pep-3131/] を参照してください。)。これらの文字については、分類は unicodedata モジュールに含まれる Unicode Character Database の版を使います。

識別子の長さには制限がありません。大小文字は区別されます。

identifier   ::=  xid_start xid_continue*
id_start     ::=  <all characters in general categories Lu, Ll, Lt, Lm, Lo, Nl, the underscore, and characters with the Other_ID_Start property>
id_continue  ::=  <all characters in id_start, plus characters in the categories Mn, Mc, Nd, Pc and others with the Other_ID_Continue property>
xid_start    ::=  <all characters in id_start whose NFKC normalization is in "id_start xid_continue*">
xid_continue ::=  <all characters in id_continue whose NFKC normalization is in "id_continue*">

上で言及した Unicode カテゴリコードは以下を表します:

Lu - 大文字 (uppercase letters)

Ll - 小文字 (lowercase letters)

Lt - 先頭が大文字 (titlecase letters)

Lm - 修飾文字 (modifier letters)

Lo - その他の文字 (other letters)

Nl - 数値を表す文字 (letter numbers)

Mn - 字幅のない記号 (nonspacing marks)

Mc - 字幅のある結合記号 (spacing combining marks)

Nd - 10 進数字 (decimal numbers)

Pc - 連結用句読記号 (connector punctuations)

Other_ID_Start - explicit list of characters in PropList.txt [https://www.unicode.org/Public/15.0.0/ucd/PropList.txt] to support backwards compatibility

Other_ID_Continue - 同様

すべての識別子は、解析中は正規化形式 NFKC に変換されます。識別子間の比較は NFKC に基づきます。

A non-normative HTML file listing all valid identifier characters for Unicode 15.0.0 can be found at https://www.unicode.org/Public/15.0.0/ucd/DerivedCoreProperties.txt

2.3.1. キーワード (keyword)

以下の識別子は、予約語、または Python 言語における キーワード (keyword) として使われ、通常の識別子として使うことはできません。キーワードは厳密に下記の通りに綴らなければなりません:

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

2.3.2. ソフトキーワード

Added in version 3.10.

Some identifiers are only reserved under specific contexts. These are known as soft keywords. The identifiers match, case, type and _ can syntactically act as keywords in certain contexts, but this distinction is done at the parser level, not when tokenizing.

As soft keywords, their use in the grammar is possible while still preserving compatibility with existing code that uses these names as identifier names.

match, case, and _ are used in the match statement. type is used in the type statement.

バージョン 3.12 で変更: type is now a soft keyword.

2.3.3. 予約済みの識別子種 (reserved classes of identifiers)

ある種の (キーワードを除く) 識別子には、特殊な意味があります。これらの識別子種は、先頭や末尾にあるアンダースコア文字のパターンで区別されます:

_*

Not imported by from module import *.

_

In a case pattern within a match statement, _ is a soft keyword that denotes a wildcard.

Separately, the interactive interpreter makes the result of the last evaluation available in the variable _. (It is stored in the builtins module, alongside built-in functions like print.)

Elsewhere, _ is a regular identifier. It is often used to name "special" items, but it is not special to Python itself.

注釈

名前 _ は、しばしば国際化 (internationalization) と共に用いられます; この慣習についての詳しい情報は、 gettext を参照してください。

It is also commonly used for unused variables.

__*__

システムで定義された (system-defined) 名前です。非公式には"dunder"な名前と呼ばれます(訳注: double underscoresの略)。これらの名前はインタープリタと (標準ライブラリを含む) 実装上で定義されています。 現行のシステムでの名前は 特殊メソッド名 などで話題に挙げられています。 Python の将来のバージョンではより多くの名前が定義されることになります。このドキュメントで明記されている用法に従わない、 あらゆる __*__ の名前は、いかなるコンテキストにおける利用でも、警告無く損害を引き起こすことがあります。

__*

クラスプライベート (class-private) な名前です。このカテゴリに属する名前は、クラス定義のコンテキスト上で用いられた場合、基底クラスと派生クラスの "プライベートな" 属性間で名前衝突が起こるのを防ぐために書き直されます。 識別子 (identifier、または名前 (name)) を参照してください。

2.4. リテラル

リテラル (literal) とは、いくつかの組み込み型の定数を表記したものです。

2.4.1. 文字列およびバイト列リテラル

文字列リテラルは以下の字句定義で記述されます:

stringliteral   ::=  [stringprefix](shortstring | longstring)
stringprefix    ::=  "r" | "u" | "R" | "U" | "f" | "F"
                     | "fr" | "Fr" | "fR" | "FR" | "rf" | "rF" | "Rf" | "RF"
shortstring     ::=  "'" shortstringitem* "'" | '"' shortstringitem* '"'
longstring      ::=  "'''" longstringitem* "'''" | '"""' longstringitem* '"""'
shortstringitem ::=  shortstringchar | stringescapeseq
longstringitem  ::=  longstringchar | stringescapeseq
shortstringchar ::=  <any source character except "\" or newline or the quote>
longstringchar  ::=  <any source character except "\">
stringescapeseq ::=  "\" <any source character>

bytesliteral   ::=  bytesprefix(shortbytes | longbytes)
bytesprefix    ::=  "b" | "B" | "br" | "Br" | "bR" | "BR" | "rb" | "rB" | "Rb" | "RB"
shortbytes     ::=  "'" shortbytesitem* "'" | '"' shortbytesitem* '"'
longbytes      ::=  "'''" longbytesitem* "'''" | '"""' longbytesitem* '"""'
shortbytesitem ::=  shortbyteschar | bytesescapeseq
longbytesitem  ::=  longbyteschar | bytesescapeseq
shortbyteschar ::=  <any ASCII character except "\" or newline or the quote>
longbyteschar  ::=  <any ASCII character except "\">
bytesescapeseq ::=  "\" <any ASCII character>

上記の生成規則で示されていない文法的な制限が一つあります。リテラルの stringprefix や bytesprefix と残りの部分の間に空白を入れてはならないことです。ソースコード文字セット (source character set) はエンコーディング宣言で定義されます。エンコーディング宣言がなければ UTF-8 です。節 エンコード宣言 (encoding declaration) を参照してください。

In plain English: Both types of literals can be enclosed in matching single quotes (') or double quotes ("). They can also be enclosed in matching groups of three single or double quotes (these are generally referred to as triple-quoted strings). The backslash (\) character is used to give special meaning to otherwise ordinary characters like n, which means 'newline' when escaped (\n). It can also be used to escape characters that otherwise have a special meaning, such as newline, backslash itself, or the quote character. See escape sequences below for examples.

バイト列リテラルには、常に 'b' や 'B' が接頭します。これらによって、 str 型ではなく bytes 型のインスタンスが作成されます。バイト列リテラルは ASCII 文字のみ含むことができます。 128 以上の数値を持つバイトはエスケープして表されなければなりません。

文字列リテラルとバイト列リテラルの両方は、任意で文字 'r' または 'R' をプレフィックスに持つことができます; そのような文字列は raw strings と呼ばれ、バックスラッシュをリテラル文字として扱います。その結果、文字列リテラルでは raw 文字列中の '\U' と '\u' のエスケープは特別扱いされません。 Python 2.x の raw unicode リテラルが Python 3.x とは異なる振る舞いをするため、 'ur' 構文はサポートされません。

Added in version 3.3: raw バイト列リテラルの 'rb' プレフィックスが 'br' の同義語として追加されました。

Python 2.x と 3.x 両対応のコードベースのメンテナンスを単純化するために、レガシー unicode リテラル (u'value') のサポートが再び導入されました。詳細は PEP 414 [https://peps.python.org/pep-0414/] を参照してください。

'f' または 'F' の接頭辞が付いた文字列リテラルはフォーマット済み文字列リテラル（ formatted string literal ）です。詳細については フォーマット済み文字列リテラル を参照してください。接頭辞の 'f' は 'r' と組み合わせられますが、 'b' や 'u' と組み合わせることはできません。つまりフォーマット済みの raw 文字列リテラルは可ですが、フォーマット済みのバイト列リテラルは不可です。

三重クオートリテラル中には、三連のエスケープされないクオート文字でリテラルを終端してしまわないかぎり、エスケープされていない改行やクオートを書くことができます (さらに、それらはそのまま文字列中に残ります)。(ここでいう "クオート" とは、文字列の囲みを開始するときに使った文字を示し、' か " のいずれかです。)

2.4.1.1. Escape sequences

'r' または 'R' 接頭文字がつかないかぎり、文字列またはバイト列リテラル中のエスケープシーケンスは標準 C で使われているのと同様の法則にしたがって解釈されます。以下に Python で認識されるエスケープシーケンスを示します:

エスケープシーケンス

意味

注釈

\<newline>

バックスラッシュと改行文字が無視されます

(1)

\\

バックスラッシュ (\)

\'

一重引用符 (')

\"

二重引用符 (")

\a

ASCII 端末ベル (BEL)

\b

ASCII バックスペース (BS)

\f

ASCII フォームフィード (FF)

\n

ASCII 行送り (LF)

\r

ASCII 復帰 (CR)

\t

ASCII 水平タブ (TAB)

\v

ASCII 垂直タブ (VT)

\ooo

8 進数値 ooo を持つ文字

(2,4)

\xhh

16 進数値 hh を持つ文字

(3,4)

文字列でのみ認識されるエスケープシーケンスは以下のとおりです:

エスケープシーケンス

意味

注釈

\N{name}

Unicode データベース中で name という名前の文字

(5)

\uxxxx

16-bit の十六進値 xxxx を持つ文字

(6)

\Uxxxxxxxx

32-bit の十六進値 xxxxxxxx を持つ文字

(7)

注釈:

A backslash can be added at the end of a line to ignore the newline:

>>> 'This string will not include \
... backslashes or newline characters.'
'This string will not include backslashes or newline characters.'

The same result can be achieved using triple-quoted strings, or parentheses and string literal concatenation.

標準 C と同じく、最大で 3 桁の 8 進数まで受理します。

バージョン 3.11 で変更: Octal escapes with value larger than 0o377 produce a DeprecationWarning.

バージョン 3.12 で変更: Octal escapes with value larger than 0o377 produce a SyntaxWarning. In a future Python version they will be eventually a SyntaxError.

標準 C とは違い、ちょうど 2 桁の 16 進数しか受理されません。

バイト列リテラル中では、十六進および八進エスケープは与えられた値のバイトを表します。文字列リテラル中では、エスケープ文字は与えられた値を持つ Unicode 文字を表します。

バージョン 3.3 で変更: name aliases [1] に対するサポートが追加されました。

ちょうど 4 桁の 16 進数しか受理されません。

あらゆるユニコード文字はこのようにしてエンコードすることができます。正確に8文字の16進数字が必要です。

標準の C とは違い、認識されなかったエスケープシーケンスはすべて、そのまま文字列中に残ります。すなわち、バックスラッシュも結果中に残ります。(この挙動はデバッグの際に便利です: エスケープシーケンスが誤入力されたら、その出力結果が失敗しているのが分かりやすくなります。) 文字列中でのみ認識されるエスケープシーケンスは、バイト列リテラルには、認識されないエスケープシーケンスとして分類されるので注意してください。

バージョン 3.6 で変更: Unrecognized escape sequences produce a DeprecationWarning.

バージョン 3.12 で変更: Unrecognized escape sequences produce a SyntaxWarning. In a future Python version they will be eventually a SyntaxError.

raw リテラルでも、引用符はバックスラッシュでエスケープできますが、バックスラッシュ自体も文字列に残ります; 例えば、r"\"" は有効な文字列リテラルで、バックスラッシュと二重引用符からなる文字列を表します; r"\" は無効な文字列リテラルです (raw リテラルを奇数個連なったバックスラッシュで終わらせることはできません)。具体的には、(バックスラッシュが直後のクオート文字をエスケープしてしまうので) raw文字列を単一のバックスラッシュで終わらせることはできません さらに、バックスラッシュの直後に改行がきても、行継続を意味する のではなく、リテラルの一部であるそれら二つの文字として解釈されます。

2.4.2. 文字列リテラルの結合 (concatenation)

文字列やバイト列リテラルは、互いに異なる引用符を使っていても (空白文字で区切っても) 複数隣接させることができます。これは各々の文字列を結合するのと同じ意味を持ちます。したがって、"hello" 'world' は "helloworld" と同じです。この機能を使うと、バックスラッシュを減らしたり、長い文字列を手軽に分離して複数行にまたがらせたり、あるいは部分文字列ごとにコメントを追加することさえできます。例えば:

re.compile("[A-Za-z_]"       # letter or underscore
           "[A-Za-z0-9_]*"   # letter, digit or underscore
          )

この機能は文法レベルで定義されていますが、スクリプトをコンパイルする際の処理として実現されることに注意してください。実行時に文字列表現を結合したければ、 '+' 演算子を使わなければなりません。また、リテラルの結合においては、結合する各要素に異なる引用符形式を使ったり (raw 文字列と三重引用符を混ぜることさえできます) 、フォーマット済み文字列リテラルと通常の文字列リテラルを結合したりすることもできますので注意してください。

2.4.3. f-strings

Added in version 3.6.

フォーマット済み文字列リテラル（ formatted string literal ）または f-string は、接頭辞 'f' または 'F' の付いた文字列リテラルです。これらの文字列には、波括弧 {} で区切られた式である置換フィールドを含めることができます。他の文字列リテラルの場合は内容が常に一定で変わることが無いのに対して、フォーマット済み文字列リテラルは実行時に式として評価されます。

エスケープシーケンスは通常の文字列リテラルと同様にデコードされます (ただしリテラルが raw 文字列でもある場合は除きます) 。エスケープシーケンスをデコードした後は、文字列の内容は次の文法で解釈されます:

f_string          ::=  (literal_char | "{{" | "}}" | replacement_field)*
replacement_field ::=  "{" f_expression ["="] ["!" conversion] [":" format_spec] "}"
f_expression      ::=  (conditional_expression | "*" or_expr)
                         ("," conditional_expression | "," "*" or_expr)* [","]
                       | yield_expression
conversion        ::=  "s" | "r" | "a"
format_spec       ::=  (literal_char | replacement_field)*
literal_char      ::=  <any code point except "{", "}" or NULL>

文字列のうち、波括弧で囲まれた部分以外は文字通り解釈されます。ただし、二重波括弧 '{{' および '}}' は単一の波括弧に置き換えられます。単一の開き波括弧 '{' は置換フィールドの始まりを意味し、その中身は Python の式で始まります。(デバッグ時に便利な機能として) 式のテキストと、評価後の値との両者を表示したい場合には、式の後に等号 '=' を加えてください。その後ろには、感嘆符 '!' によって導入される変換フィールドを続けることができます。さらに、':' に続いて書式指定子を追加できます。置換フィールドは単一の閉じ波括弧 '}' で終わります。

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 lambda and assignment expressions := 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 # inside a replacement field is a comment (even closing braces and quotes). In that case, replacement fields must be closed in a different line.

>>> f"abc{a # This is a comment }"
... + 3}"
'abc5'

バージョン 3.7 で変更: Python 3.7 より前のバージョンでは、await 式および async for 句を含む内包表記は、実装に伴う問題の都合により許されていませんでした。

バージョン 3.12 で変更: Prior to Python 3.12, comments were not allowed inside f-string replacement fields.

等号 '=' が指定されたとき、出力文字列は、式のテキスト表現、等号 '='、および評価された式を含みます。開き波括弧 '{' の直後、式の中、および '=' の後に含まれる空白文字はすべて保存されます。書式指定子が存在しない限り、'=' を指定した場合は、式に対して repr() を適用した結果が出力になります。一方、書式指定子が存在する場合は、変換フィールドで '!r' が指定されていない限り、デフォルトで str() が適用されます。

Added in version 3.8: 等号 '='。

もし変換フィールドが指定されていた場合、式の評価結果はフォーマットの前に変換されます。変換 '!s' は str() を、 '!r' は repr() を、そして '!a' は ascii() を呼び出します。

The result is then formatted using the format() protocol. The format specifier is passed to the __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 format specifiers, but may not include more deeply nested replacement fields. The format specifier mini-language is the same as that used by the str.format() method.

フォーマット済み文字列リテラルは他の文字列リテラルと結合できますが、置換フィールドを複数のリテラルに分割して書くことはできません。

フォーマット済み文字列リテラルの例をいくつか挙げます:

>>> 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" '

Reusing the outer f-string quoting type inside a replacement field is permitted:

>>> a = dict(x=2)
>>> f"abc {a["x"]} def"
'abc 2 def'

バージョン 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:

>>> a = ["a", "b", "c"]
>>> print(f"List a contains:\n{"\n".join(a)}")
List a contains:
a
b
c

バージョン 3.12 で変更: Prior to Python 3.12, backslashes were not permitted inside an f-string replacement field.

フォーマット済み文字列リテラルは、たとえ式を含んでいなかったとしても、 docstring としては使えません。

>>> def foo():
...     f"Not a docstring"
...
>>> foo.__doc__ is None
True

フォーマット済み文字列リテラルを Python に追加した提案 PEP 498 [https://peps.python.org/pep-0498/] も参照してください。また関連する文字列フォーマットの仕組みを使っている str.format() も参照してください。

2.4.4. 数値リテラル

数値リテラルには 3 種類あります。整数 (integer)、浮動小数点数 (floating point number)、虚数(imaginary numbers) です。複素数リテラルは存在しません。(複素数は実数と虚数の和として作れます)。

数値リテラルには符号が含まれていないことに注意してください; -1 のような句は、実際には単項演算子 (unary operator) '-' とリテラル 1 を組み合わせたものです。

2.4.5. 整数リテラル

整数リテラルは以下の字句定義で記述されます:

integer      ::=  decinteger | bininteger | octinteger | hexinteger
decinteger   ::=  nonzerodigit (["_"] digit)* | "0"+ (["_"] "0")*
bininteger   ::=  "0" ("b" | "B") (["_"] bindigit)+
octinteger   ::=  "0" ("o" | "O") (["_"] octdigit)+
hexinteger   ::=  "0" ("x" | "X") (["_"] hexdigit)+
nonzerodigit ::=  "1"..."9"
digit        ::=  "0"..."9"
bindigit     ::=  "0" | "1"
octdigit     ::=  "0"..."7"
hexdigit     ::=  digit | "a"..."f" | "A"..."F"

値がメモリ上に収まるかどうかという問題を除けば、整数リテラルには長さの制限がありません。

アンダースコアはリテラルの値を判断するにあたって無視されます。そのためアンダースコアを使って数字をグループ化することで読みやすくできます。アンダースコアは数字と数字の間に 1 つだけ、あるいは 0x のような基数指定の直後に 1 つだけ挿入できます。

なお、非 0 の十進数の先頭には 0 を付けられません。これは、Python がバージョン 3.0 以前に使っていた C 形式の八進リテラルとの曖昧さを回避するためです。

整数リテラルの例をいくつか示します:

7     2147483647                        0o177    0b100110111
3     79228162514264337593543950336     0o377    0xdeadbeef
      100_000_000_000                   0b_1110_0101

バージョン 3.6 で変更: グループ化を目的としたリテラル中のアンダースコアが許されるようになりました。

2.4.6. 浮動小数点数リテラル

浮動小数点数リテラルは以下の字句定義で記述されます:

floatnumber   ::=  pointfloat | exponentfloat
pointfloat    ::=  [digitpart] fraction | digitpart "."
exponentfloat ::=  (digitpart | pointfloat) exponent
digitpart     ::=  digit (["_"] digit)*
fraction      ::=  "." digitpart
exponent      ::=  ("e" | "E") ["+" | "-"] digitpart

なお、整数部と指数部は常に 10 を基数として解釈されます。例えば、077e010 は正しい表記であり、77e10 と同じ数を表します。浮動小数点数リテラルの取りうる値の範囲は実装に依存します。整数リテラルと同じように、アンダースコアで数字をグループ分けできます。

浮動小数点数リテラルの例をいくつか示します:

3.14    10.    .001    1e100    3.14e-10    0e0    3.14_15_93

バージョン 3.6 で変更: グループ化を目的としたリテラル中のアンダースコアが許されるようになりました。

2.4.7. 虚数 (imaginary) リテラル

虚数リテラルは以下のような字句定義で記述されます:

imagnumber ::=  (floatnumber | digitpart) ("j" | "J")

虚数リテラルは、実数部が 0.0 の複素数を表します。複素数は二つ組の浮動小数点型の数値で表され、それぞれの数値は浮動小数点型と同じ定義域の範囲を持ちます。実数部がゼロでない浮動小数点を生成するには、 (3+4j) のように虚数リテラルに浮動小数点数を加算します。以下に虚数リテラルの例をいくつか示します:

3.14j   10.j    10j     .001j   1e100j   3.14e-10j   3.14_15_93j

2.5. 演算子

以下のトークンは演算子です:

+       -       *       **      /       //      %      @
<<      >>      &       |       ^       ~       :=
<       >       <=      >=      ==      !=

2.6. デリミタ (delimiter)

以下のトークンは文法上のデリミタとして働きます:

(       )       [       ]       {       }
,       :       .       ;       @       =       ->
+=      -=      *=      /=      //=     %=      @=
&=      |=      ^=      >>=     <<=     **=

ピリオドは浮動小数点数や虚数リテラル中にも置けます。ピリオド三つの列はスライス表記における省略符号 (ellipsis) リテラルとして特別な意味を持ちます。リスト後半の累算代入演算子 (augmented assignment operator) は、字句的にはデリミタとして振舞いますが、演算も行います。

以下の印字可能 ASCII 文字は、他のトークンの一部として特殊な意味を持っていたり、字句解析器にとって重要な意味を持っています:

'       "       #       \

以下の印字可能 ASCII 文字は、Python では使われていません。これらの文字が文字列リテラルやコメントの外にある場合、無条件にエラーとなります:

$       ?       `

脚注

[1]

https://www.unicode.org/Public/15.0.0/ucd/NameAliases.txt

3. データモデル

3.1. オブジェクト、値、および型

Python における オブジェクト (object) とは、データを抽象的に表したものです。Python プログラムにおけるデータは全て、オブジェクトまたはオブジェクト間の関係として表されます。(ある意味では、プログラムコードもまたオブジェクトとして表されます。これはフォン・ノイマン: Von Neumann の "プログラム記憶方式コンピュータ: stored program computer" のモデルに適合します。)

Every object has an identity, a type and a value. An object's identity never changes once it has been created; you may think of it as the object's address in memory. The is operator compares the identity of two objects; the id() function returns an integer representing its identity.

CPython 実装の詳細: CPython では、id(x) は x が格納されているメモリ上のアドレスを返します。

オブジェクトの型はオブジェクトがサポートする操作 (例: len() をサポートするか) と、オブジェクトが取りうる値を決定します。 type() 関数はオブジェクトの型 (型自体もオブジェクトです) を返します。同一性と同じく、オブジェクトの型(type) も変更不可能です。 [1]

オブジェクトによっては 値 を変更することが可能です。値を変更できるオブジェクトのことを mutable と呼びます。生成後に値を変更できないオブジェクトのことを immutable と呼びます。(mutable なオブジェクトへの参照を格納している immutableなコンテナオブジェクトの値は、その格納しているオブジェクトの値が変化した時に変化しますが、コンテナがどのオブジェクトを格納しているのかが変化しないのであれば immutable だと考えることができます。したがって、immutable かどうかは値が変更可能かどうかと完全に一致するわけではありません) オブジェクトが mutable かどうかはその型によって決まります。例えば、数値型、文字列型とタプル型のインスタンスは immutable で、dict や list は mutable です。

オブジェクトを明示的に破壊することはできません; しかし、オブジェクトに到達不能 (unreachable) になると、ガベージコレクション (garbage-collection) によって処理されるかもしれません。ガベージコレクションを遅らせたり、全く行わない実装も許されています --- 到達可能なオブジェクトを処理してしまわないかぎり、ガベージコレクションをどう実装するかは実装品質の問題です。

CPython 実装の詳細: 現在の CPython 実装では参照カウント (reference-counting) 方式を使っており、(オプションとして) 循環参照を行っているガベージオブジェクトを遅延検出します。この実装ではほとんどのオブジェクトを到達不能になると同時に処理することができますが、循環参照を含むガベージオブジェクトの収集が確実に行われるよう保証しているわけではありません。循環参照を持つガベージオブジェクト収集の制御については、 gc モジュールを参照してください。 CPython以外の実装は別の方式を使っており、CPythonも将来は別の方式を使うかもしれません。オブジェクトが到達不能になったときに即座に終了処理されることに頼らないでください (ですからファイルは必ず明示的に閉じてください)。

Note that the use of the implementation's tracing or debugging facilities may keep objects alive that would normally be collectable. Also note that catching an exception with a try...except statement may keep objects alive.

Some objects contain references to "external" resources such as open files or windows. It is understood that these resources are freed when the object is garbage-collected, but since garbage collection is not guaranteed to happen, such objects also provide an explicit way to release the external resource, usually a close() method. Programs are strongly recommended to explicitly close such objects. The try...finally statement and the with statement provide convenient ways to do this.

他のオブジェクトに対する参照をもつオブジェクトもあります; これらは コンテナ (container) と呼ばれます。コンテナオブジェクトの例として、タプル、リスト、および辞書が挙げられます。オブジェクトへの参照自体がコンテナの値の一部です。ほとんどの場合、コンテナの値というと、コンテナに入っているオブジェクトの値のことを指し、それらオブジェクトのアイデンティティではありません; しかしながら、コンテナの変更可能性について述べる場合、今まさにコンテナに入っているオブジェクトのアイデンティティのことを指します。したがって、 (タプルのように) 変更不能なオブジェクトが変更可能なオブジェクトへの参照を含む場合、その値が変化するのは変更可能なオブジェクトが変更された時、ということになります。

型はオブジェクトの動作のほとんど全てに影響します。オブジェクトのアイデンティティが重要かどうかでさえ、ある意味では型に左右されます: 変更不能な型では、新たな値を計算するような操作を行うと、実際には同じ型と値を持った既存のオブジェクトへの参照を返すことがありますが、変更可能なオブジェクトではそのような動作は起こりえません。例えば、 a = 1; b = 1 とすると、 a と b は値 1 を持つ同じオブジェクトを参照するときもあるし、そうでないときもあります。これは実装に依存します。しかし、 c = []; d = [] とすると、 c と d はそれぞれ二つの異なった、互いに一意な、新たに作成された空のリストを参照することが保証されています。 (c = d = [] とすると、 c と d の両方に同じオブジェクトを代入します)

3.2. 標準型の階層

以下は Python に組み込まれている型のリストです。(実装によって、C、Java、またはその他の言語で書かれた) 拡張モジュールで、その他の型が定義されていることがあります。新たな型 (有理数や、整数を効率的に記憶する配列、など) の追加は、たいてい標準ライブラリを通して提供されますが、将来のバージョンの Python では、型の階層構造にこのような追加がなされるかもしれません。

以下に説明する型のいくつかには、 '特殊属性 (special attribute)' を列挙した段落があります。これらの属性は実装へのアクセス手段を提供するもので、一般的な用途に利用するためのものではありません。特殊属性の定義は将来変更される可能性があります。

3.2.1. None

この型には単一の値しかありません。この値を持つオブジェクトはただ一つしか存在しません。このオブジェクトは組み込み名 None でアクセスされます。このオブジェクトは、様々な状況で値が存在しないことをしめします。例えば、明示的に値を返さない関数は None を返します。 None の真値 (truth value) は偽 (false) です。

3.2.2. NotImplemented

This type has a single value. There is a single object with this value. This object is accessed through the built-in name NotImplemented. Numeric methods and rich comparison methods should return this value if they do not implement the operation for the operands provided. (The interpreter will then try the reflected operation, or some other fallback, depending on the operator.) It should not be evaluated in a boolean context.

詳細は 算術演算の実装 を参照してください。

バージョン 3.9 で変更: Evaluating NotImplemented in a boolean context is deprecated. While it currently evaluates as true, it will emit a DeprecationWarning. It will raise a TypeError in a future version of Python.

3.2.3. Ellipsis

この型には単一の値しかありません。この値を持つオブジェクトはただ一つしか存在しません。このオブジェクトはリテラル ... またはPythonで決められている名前 Ellipsis でアクセスされます。真理値は真 (true)です。

3.2.4. numbers.Number

数値リテラルによって作成されたり、算術演算や組み込みの算術関数によって返されるオブジェクトです。数値オブジェクトは変更不能です; 一度値が生成されると、二度と変更されることはありません。Python の数値オブジェクトはいうまでもなく数学で言うところの数値と強く関係していますが、コンピュータ内で数値を表現する際に伴う制限を受けています。

__repr__() と __str__() から計算された数値クラスの文字列表現には次のような特性があります:

その文字列は、クラスコンストラクタに渡したときに、元の数値の値を持つオブジェクトを生成する有効な数値リテラルです。

できるなら、10を底として表現されます。

小数点の前にある 1 つのゼロを除いて、上に連なるゼロは表示されません。

小数点の後にある 1 つのゼロを除いて、下に連なるゼロは表示されません。

符号は数値が負数のときのみ表示されます。

Python は整数、浮動小数点数、複素数の間で区別を行っています:

3.2.4.1. numbers.Integral (整数)

整数型は、整数(正の数および負の数)を表す数学的集合内における要素を表現する型です。

注釈

整数表現に関する規則は、負の整数を含むシフト演算やマスク演算において、最も有意義な解釈ができるように意図されています。

整数には 2 種類あります:

整数 (int)

無制限の範囲の数を表現しますが、利用可能な (仮想) メモリサイズの制限のみを受けます。シフト演算やマスク演算のために2進数表現を持つと想定されます。負の数は符号ビットが左に無限に延びているような錯覚を与える 2 の補数表現の変型で表されます。

ブール値 (bool)

真偽値の False と True を表します。False と True を表す 2 つのオブジェクトのみがブール値オブジェクトです。ブール型は整数型の派生型であり、ほとんどの状況でそれぞれ 0 と 1 のように振る舞いますが、例外として文字列に変換されたときはそれぞれ "False" および "True" という文字列が返されます。

3.2.4.2. numbers.Real (float) (実数)

この型は計算機レベルの倍精度浮動小数点数を表現します。表現可能な値の範囲やオーバーフローの扱いは計算機のアーキテクチャ（および、CやJavaによる実装）に従います。Pythonは単精度浮動小数点数をサポートしません。一般的に単精度浮動小数点数を使う理由はプロセッサーとメモリの使用を節約するためと説明されます。しかし、こうした節約はPythonでオブジェクトを扱う際のオーバーヘッドに比べれば微々たるものです。また、2種類の浮動小数点数型を持つことで複雑になる理由はありません。

3.2.4.3. numbers.Complex (complex)

この型は、計算機レベルで倍精度とされている浮動小数点を 2 つ一組にして複素数を表現します。浮動小数点について述べたのと同じ性質が当てはまります。複素数 z の実数部および虚数部は、それぞれ読み出し専用属性 z.real および z.imag で取り出すことができます。

3.2.5. シーケンス型 (sequence)

These represent finite ordered sets indexed by non-negative numbers. The built-in function 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 a[i]. Some sequences, including built-in sequences, interpret negative subscripts by adding the sequence length. For example, a[-2] equals a[n-2], the second to last item of sequence a with length n.

Sequences also support slicing: a[i:j] selects all items with index k such that i <= k < 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.

シーケンスによっては、第三の "ステップ (step)" パラメタを持つ "拡張スライス (extended slice)" もサポートしています: a[i:j:k] は、 x = i + n*k, n >= 0 かつ i <= x < j であるようなインデクス x を持つような a 全ての要素を選択します。

シーケンスは、変更可能なものか、そうでないかで区別されています:

3.2.5.1. 変更不能なシーケンス (immutable sequence)

変更不能なシーケンス型のオブジェクトは、一度生成されるとその値を変更することができません。 (オブジェクトに他のオブジェクトへの参照が入っている場合、参照されているオブジェクトは変更可能なオブジェクトでもよく、その値は変更される可能性があります; しかし、変更不能なオブジェクトが直接参照しているオブジェクトの集合自体は、変更することができません。)

以下の型は変更不能なシーケンス型です:

文字列型 (string)

文字列はUnicodeコードポイントを表現する値の配列です。文字列中のどのコードポイントも U+0000 - U+10FFFF の範囲で表現されることができます。Pythonは char 型を持ちません。代わりに、文字列中のどのコードポイントも長さ ''1'' の文字列オブジェクトとして表現することができます。組み込み関数 ord() は文字列形式を U+0000 - U+10FFFF の範囲の整数に変換します。また、組み込み関数 chr() は 0 - 10FFFF の範囲の整数を対応する長さ 1 の文字列に変換します。str.encode() はテキストエンコーディングを使うことで str を bytes に変換するために使うことができます。また、bytes.decode() によりその逆が実行することができます。

タプル型 (tuple)

タプルの要素は任意の Python オブジェクトです。二つ以上の要素からなるタプルは、個々の要素を表現する式をカンマで区切って構成します。単一の要素からなるタプル (単集合 'singleton') を作るには、要素を表現する式の直後にカンマをつけます (単一の式だけではタプルを形成しません。これは、式をグループ化するのに丸括弧を使えるようにしなければならないからです)。要素の全くない丸括弧の対を作ると空のタプルになります。

bytes

bytes オブジェクトは不変な配列です。要素は 8-bit バイトで、 0 <= x < 256 の範囲の整数で表現されます。 (b'abc' のような) bytes リテラルや組み込みの bytes() コンストラクタを使って bytes オブジェクトを作成できます。また、 bytes オブジェクトは decode() メソッドを通して文字列にデコードできます。

3.2.5.2. 変更可能なシーケンス型 (mutable sequence)

変更可能なシーケンスは、作成した後で変更することができます。変更可能なシーケンスでは、添字表記やスライス表記を使って指定された要素に代入を行うことができ、 del (delete) 文を使って要素を削除することができます。

注釈

The collections and array module provide additional examples of mutable sequence types.

Python に最初から組み込まれている変更可能なシーケンス型は、今のところ二つです:

リスト型 (list)

リストの要素は任意の Python オブジェクトにできます。リストは、角括弧の中にカンマで区切られた式を並べて作ります。 (長さが 0 や 1 のシーケンスを作るために特殊な場合分けは必要ないことに注意してください。)

バイト配列

bytearray オブジェクトは変更可能な配列です。組み込みの bytearray() コンストラクタによって作成されます。変更可能なことを除けば (つまりハッシュ化できない)、 byte array は変更不能な bytes オブジェクトと同じインターフェースと機能を提供します。

3.2.6. 集合型

集合型は、順序のない、ユニークで不変なオブジェクトの有限集合を表現します。そのため、(配列の)添字を使ったインデックスアクセスはできません。ただし、イテレートは可能で、組み込み関数 len() は集合の要素数を返します。集合型の一般的な使い方は、集合に属しているかの高速なテスト、シーケンスからの重複の排除、共通集合・和集合・差・対称差といった数学的な演算の計算です。

集合の要素には、辞書のキーと同じ普遍性に関するルールが適用されます。数値型は通常の数値比較のルールに従うことに注意してください。もし2つの数値の比較結果が同値である(例えば、 1 と 1.0)なら、そのうちの1つのみを集合に含めることができます。

現在、2つの組み込み集合型があります:

集合型

可変な集合型です。組み込みの set() コンストラクタで作成され、後から add() などのいくつかのメソッドで更新できます。

Frozen set 型

不変な集合型です。組み込みの frozenset() コンストラクタによって作成されます。 frozenset は不変で ハッシュ可能 なので、別の集合型の要素になったり、辞書のキーにすることができます。

3.2.7. マッピング型 (mapping)

任意のインデクス集合でインデクス化された、オブジェクトからなる有限の集合を表現します。添字表記 a[k] は、 k でインデクス指定された要素を a から選択します; 選択された要素は式の中で使うことができ、代入や del 文の対象にすることができます。組み込み関数 len() は、マッピング内の要素数を返します。

Python に最初から組み込まれているマッピング型は、今のところ一つだけです:

3.2.7.1. 辞書型 (dictionary)

ほぼ任意の値でインデクスされたオブジェクトからなる有限の集合を表します。キー (key) として使えない値の唯一の型は、リストや辞書、そしてオブジェクトの同一性でなく値で比較されるその他の変更可能な型です。これは、辞書型を効率的に実装する上で、キーのハッシュ値が不変である必要があるためです。数値型をキーに使う場合、キー値は通常の数値比較における規則に従います: 二つの値が等しくなる場合 (例えば 1 と 1.0)、互いに同じ辞書のエントリを表すインデクスとして使うことができます。

辞書は挿入の順序を保持します。つまり、キーは辞書に追加された順番に生成されていきます。既存のキーを置き換えても、キーの順序は変わりません。キーを削除したのちに再挿入すると、元の場所ではなく辞書の最後に追加されます。

辞書は変更可能な型です; 辞書は {...} 表記で生成します (辞書表示 を参照してください)。

拡張モジュール dbm.ndbm 、 dbm.gnu は、 collections モジュールのように、別のマッピング型の例を提供しています。

バージョン 3.7 で変更: Pythonのバージョン3.6では、辞書は挿入順序を保持しませんでした。CPython 3.6では挿入順序は保持されましたが、それは策定された言語の仕様というより、その当時の実装の細部とみなされていました。

3.2.8. 呼び出し可能型 (callable type)

関数呼び出し操作 (呼び出し (call) 参照) を行うことができる型です:

3.2.8.1. ユーザ定義関数 (user-defined function)

ユーザ定義関数オブジェクトは、関数定義を行うことで生成されます (関数定義 参照)。関数は、仮引数 (formal parameter) リストと同じ数の要素が入った引数リストとともに呼び出されます。

3.2.8.1.1. Special read-only attributes

属性

意味

function.__globals__

A reference to the dictionary that holds the function's global variables -- the global namespace of the module in which the function was defined.

function.__closure__

None or a tuple of cells that contain bindings for the function's free variables.

セルオブジェクトは属性 cell_contents を持っています。これはセルの値を設定するのに加えて、セルの値を得るのにも使えます。

3.2.8.1.2. Special writable attributes

Most of these attributes check the type of the assigned value:

属性

意味

function.__doc__

The function's documentation string, or None if unavailable. Not inherited by subclasses.

function.__name__

The function's name. See also: __name__ attributes.

function.__qualname__

The function's qualified name. See also: __qualname__ attributes.

Added in version 3.3.

function.__module__

関数が定義されているモジュールの名前です。モジュール名がない場合は None になります。

function.__defaults__

A tuple containing default parameter values for those parameters that have defaults, or None if no parameters have a default value.

function.__code__

The code object representing the compiled function body.

function.__dict__

The namespace supporting arbitrary function attributes. See also: __dict__ attributes.

function.__annotations__

A dictionary containing annotations of parameters. The keys of the dictionary are the parameter names, and 'return' for the return annotation, if provided. See also: Annotations Best Practices.

function.__kwdefaults__

A dictionary containing defaults for keyword-only parameters.

function.__type_params__

A tuple containing the type parameters of a generic function.

Added in version 3.12.

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 built-in functions may be supported in the future.

Additional information about a function's definition can be retrieved from its code object (accessible via the __code__ attribute).

3.2.8.2. インスタンスメソッド

インスタンスメソッドオブジェクトは、クラス、クラスインスタンスと任意の呼び出し可能オブジェクト (通常はユーザ定義関数) を結びつけます。

Special read-only attributes:

method.__self__

Refers to the class instance object to which the method is bound

method.__func__

Refers to the original function object

method.__doc__

The method's documentation (same as method.__func__.__doc__). A string if the original function had a docstring, else None.

method.__name__

The name of the method (same as method.__func__.__name__)

method.__module__

The name of the module the method was defined in, or None if unavailable.

Methods also support accessing (but not setting) the arbitrary function attributes on the underlying 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 function object or a classmethod object.

When an instance method object is created by retrieving a user-defined function object from a class via one of its instances, its __self__ attribute is the instance, and the method object is said to be bound. The new method's __func__ attribute is the original function object.

When an instance method object is created by retrieving a classmethod object from a class or instance, its __self__ attribute is the class itself, and its __func__ attribute is the function object underlying the class method.

When an instance method object is called, the underlying function (__func__) is called, inserting the class instance (__self__) in front of the argument list. For instance, when C is a class which contains a definition for a function f(), and x is an instance of C, calling x.f(1) is equivalent to calling C.f(x, 1).

When an instance method object is derived from a classmethod object, the "class instance" stored in __self__ will actually be the class itself, so that calling either x.f(1) or C.f(1) is equivalent to calling f(C,1) where f is the underlying function.

Note that the transformation from function object to instance method object happens each time the attribute is retrieved from the instance. In some cases, a fruitful optimization is to assign the attribute to a local variable and call that local variable. Also notice that this transformation only happens for user-defined functions; other callable objects (and all non-callable objects) are retrieved without transformation. It is also 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.

3.2.8.3. ジェネレータ関数 (generator function)

yield 文 (yield 文 の節を参照) を使う関数もしくはメソッドは ジェネレータ関数 と呼ばれます。そのような関数が呼び出されたときは常に、関数の本体を実行するのに使える イテレータ オブジェクトを返します: イテレータの iterator.__next__() メソッドを呼び出すと、 yield 文を使って値が提供されるまで関数を実行します。関数の return 文を実行するか終端に達したときは、 StopIteration 例外が送出され、イテレータが返すべき値の最後まで到達しています。

3.2.8.4. コルーチン関数 (coroutine function)

async def を使用して定義された関数やメソッドを コルーチン関数 (coroutine function) と呼びます。呼び出された時、そのような関数は coroutine オブジェクトを返します。コルーチン関数は async with や async for 文だけでなく await 式を持つことが出来ます。コルーチンオブジェクト を参照してください。

3.2.8.5. 非同期ジェネレータ関数 (asynchronous generator function)

async def を使って定義され、 yield 文を使用している関数やメソッドを asynchronous generator function と呼びます。そのような関数は、呼び出されたとき、非同期イテレータ オブジェクトを返します。このオブジェクトは async for 文で関数の本体を実行するのに使えます。

非同期イテレータの aiterator.__anext__ メソッドを呼び出すと、他の処理が待たされているときに、 yield 式を使い値を提供するところまで処理を進める awaitable を返します。その関数が空の return 文を実行する、もしくは処理の終わりに到達したときは、 StopAsyncIteration 例外が送出され、非同期イテレータは出力すべき値の最後に到達したことになります。

3.2.8.6. 組み込み関数 (built-in function)

A built-in function object is a wrapper around a C function. Examples of built-in functions are len() and math.sin() (math is a standard built-in module). The number and type of the arguments are determined by the C function. Special read-only attributes:

__doc__ is the function's documentation string, or None if unavailable. See function.__doc__.

__name__ is the function's name. See function.__name__.

__self__ is set to None (but see the next item).

__module__ is the name of the module the function was defined in or None if unavailable. See function.__module__.

3.2.8.7. 組み込みメソッド (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 alist.append(), assuming alist is a list object. In this case, the special read-only attribute __self__ is set to the object denoted by alist. (The attribute has the same semantics as it does with other instance methods.)

3.2.8.8. クラス

Classes are callable. These objects normally act as factories for new instances of themselves, but variations are possible for class types that override __new__(). The arguments of the call are passed to __new__() and, in the typical case, to __init__() to initialize the new instance.

3.2.8.9. クラスのインスタンス

任意のクラスのインスタンスは、クラスで __call__() メソッドを定義することで呼び出し可能になります。

3.2.9. モジュール

Modules are a basic organizational unit of Python code, and are created by the import system as invoked either by the import statement, or by calling functions such as importlib.import_module() and built-in __import__(). A module object has a namespace implemented by a dictionary object (this is the dictionary referenced by the __globals__ attribute of functions defined in the module). Attribute references are translated to lookups in this dictionary, e.g., m.x is equivalent to 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).

属性の代入を行うと、モジュールの名前空間辞書の内容を更新します。例えば、 m.x = 1 は m.__dict__["x"] = 1 と同じです。

定義済みの (書き込み可能な) 属性:

__name__

モジュールの名前。

__doc__

モジュールのドキュメントで、文字列か、もし利用できない場合は None です。

__file__

ロードされたモジュールファイルのパス名です。インタプリタに静的にリンクされている C モジュールのような特定の種類のモジュールでは、 __file__ 属性は存在しないかもしれません。共有ライブラリから動的にロードされた拡張モジュールの場合、この属性は 共有ライブラリファイルのパス名になります。

__annotations__

モジュールの本体の実行中に収集した 変数アノテーション を格納する辞書です。 __annotations__ を利用するベストプラクティスについては、 アノテーションのHOWTO を参照してください。

読み出し専用の特殊属性: __dict__ はモジュールの名前空間で、辞書オブジェクトです。

CPython 実装の詳細: CPython がモジュール辞書を削除する方法により、モジュール辞書が生きた参照を持っていたとしてもその辞書はモジュールがスコープから外れた時に削除されます。これを避けるには、辞書をコピーするか、辞書を直接使っている間モジュールを保持してください。

3.2.10. カスタムクラス型

Custom class types are typically created by class definitions (see section クラス定義). A class has a namespace implemented by a dictionary object. Class attribute references are translated to lookups in this dictionary, e.g., C.x is translated to 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 The Python 2.3 Method Resolution Order.

When a class attribute reference (for class C, say) would yield a class method object, it is transformed into an instance method object whose __self__ attribute is C. When it would yield a staticmethod object, it is transformed into the object wrapped by the static method object. See section デスクリプタ (descriptor) の実装 for another way in which attributes retrieved from a class may differ from those actually contained in its __dict__.

クラス属性を代入すると、そのクラスの辞書だけが更新され、基底クラスの辞書は更新しません。

クラスオブジェクトを呼び出す (上記を参照) と、クラスインスタンスを生成します (下記を参照)。

特殊属性:

__name__

クラス名。

__module__

クラスが定義されているモジュールの名前。

__dict__

クラスの名前空間を格納している辞書。

__bases__

ベースクラスリストに現れる順序でベースクラスを格納しているタプル。

__doc__

クラスのドキュメントで、文字列か、もし未定義の場合は None です。

__annotations__

クラスの本体の実行中に収集した 変数アノテーション を格納する辞書です。 __annotations__ を利用するベストプラクティスについては、 アノテーションのHOWTO を参照してください。

__type_params__

A tuple containing the type parameters of a generic class.

3.2.11. クラスインスタンス (class instance)

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 __self__ attribute is the instance. Static method and class method objects are also transformed; see above under "Classes". See section デスクリプタ (descriptor) の実装 for another way in which attributes of a class retrieved via its instances may differ from the objects actually stored in the class's __dict__. If no class attribute is found, and the object's class has a __getattr__() method, that is called to satisfy the lookup.

属性の代入や削除を行うと、インスタンスの辞書を更新しますが、クラスの辞書を更新することはありません。クラスで __setattr__() や __delattr__() メソッドが定義されている場合、直接インスタンスの辞書を更新する代わりにこれらのメソッドが呼び出されます。

クラスインスタンスは、ある特定の名前のメソッドを持っている場合、数値型やシーケンス型、あるいはマップ型のように振舞うことができます。 特殊メソッド名 を参照してください。

特殊属性: __dict__ は属性の辞書です; __class__ はインスタンスのクラスです。

3.2.12. I/O オブジェクト (ファイルオブジェクトの別名)

file object は開かれたファイルを表します。ファイルオブジェクトを作るための様々なショートカットがあります: open() 組み込み関数、 os.popen() 、 os.fdopen() 、ソケットオブジェクトの makefile() メソッド (あるいは拡張モジュールから提供される他の関数やメソッド) 。

オブジェクト sys.stdin 、 sys.stdout および sys.stderr は、インタプリタの標準入力、標準出力、および標準エラー出力ストリームに対応するファイルオブジェクトに初期化されます。これらはすべてテキストモードで開かれ、 io.TextIOBase 抽象クラスによって定義されたインターフェースに従います。

3.2.13. 内部型 (internal type)

インタプリタが内部的に使っているいくつかの型は、ユーザに公開されています。これらの定義は将来のインタプリタのバージョンでは変更される可能性がありますが、ここでは記述の完全性のために触れておきます。

3.2.13.1. コードオブジェクト

コードオブジェクトは バイトコンパイルされた (byte-compiled) 実行可能な Python コード、別名 バイトコード を表現します。コードオブジェクトと関数オブジェクトの違いは、関数オブジェクトが関数のグローバル変数 (関数を定義しているモジュールのグローバル) に対して明示的な参照を持っているのに対し、コードオブジェクトにはコンテキストがないということです; また、関数オブジェクトではデフォルト引数値を記憶できますが、コードオブジェクトではできません (実行時に計算される値を表現するため)。関数オブジェクトと違い、コードオブジェクトは変更不可能で、変更可能なオブジェクトへの参照を (直接、間接に関わらず) 含みません。

3.2.13.1.1. Special read-only attributes

codeobject.co_name

The function name

codeobject.co_qualname

The fully qualified function name

Added in version 3.11.

codeobject.co_argcount

The total number of positional parameters (including positional-only parameters and parameters with default values) that the function has

codeobject.co_posonlyargcount

The number of positional-only parameters (including arguments with default values) that the function has

codeobject.co_kwonlyargcount

The number of keyword-only parameters (including arguments with default values) that the function has

codeobject.co_nlocals

The number of local variables used by the function (including parameters)

codeobject.co_varnames

A tuple containing the names of the local variables in the function (starting with the parameter names)

codeobject.co_cellvars

A tuple containing the names of local variables that are referenced by nested functions inside the function

codeobject.co_freevars

A tuple containing the names of free variables in the function

codeobject.co_code

A string representing the sequence of bytecode instructions in the function

codeobject.co_consts

A tuple containing the literals used by the bytecode in the function

codeobject.co_names

A tuple containing the names used by the bytecode in the function

codeobject.co_filename

The name of the file from which the code was compiled

codeobject.co_firstlineno

The line number of the first line of the function

codeobject.co_lnotab

A string encoding the mapping from 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.14.

codeobject.co_stacksize

The required stack size of the code object

codeobject.co_flags

An integer encoding a number of flags for the interpreter.

The following flag bits are defined for co_flags: bit 0x04 is set if the function uses the *arguments syntax to accept an arbitrary number of positional arguments; bit 0x08 is set if the function uses the **keywords syntax to accept arbitrary keyword arguments; bit 0x20 is set if the function is a generator. See Code Objects Bit Flags for details on the semantics of each flags that might be present.

Future feature declarations (from __future__ import division) also use bits in co_flags to indicate whether a code object was compiled with a particular feature enabled: bit 0x2000 is set if the function was compiled with future division enabled; bits 0x10 and 0x1000 were used in earlier versions of Python.

Other bits in co_flags are reserved for internal use.

If a code object represents a function, the first item in co_consts is the documentation string of the function, or None if undefined.

3.2.13.1.2. Methods on code objects

codeobject.co_positions()

Returns an iterable over the source code positions of each bytecode instruction in the code object.

The iterator returns tuples containing the (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 instruction. 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:

Running the interpreter with -X no_debug_ranges.

Loading a pyc file compiled while using -X no_debug_ranges.

Position tuples corresponding to artificial instructions.

Line and column numbers that can't be represented due to implementation specific limitations.

When this occurs, some or all of the tuple elements can be None.

Added in version 3.11.

注釈

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 -X no_debug_ranges command line flag or the PYTHONNODEBUGRANGES environment variable can be used.

codeobject.co_lines()

Returns an iterator that yields information about successive ranges of bytecodes. Each item yielded is a (start, end, lineno) tuple:

start (an int) represents the offset (inclusive) of the start of the bytecode range

end (an int) represents the offset (exclusive) of the end of the bytecode range

lineno is an int representing the line number of the bytecode range, or None if the bytecodes in the given range have no line number

The items yielded will have the following properties:

The first range yielded will have a start of 0.

The (start, end) ranges will be non-decreasing and consecutive. That is, for any pair of tuples, the start of the second will be equal to the end of the first.

No range will be backwards: end >= start for all triples.

The last tuple yielded will have end equal to the size of the bytecode.

Zero-width ranges, where start == end, are allowed. Zero-width ranges are used for lines that are present in the source code, but have been eliminated by the bytecode compiler.

Added in version 3.10.

参考

PEP 626 [https://peps.python.org/pep-0626/] - Precise line numbers for debugging and other tools.

The PEP that introduced the co_lines() method.

codeobject.replace(**kwargs)

Return a copy of the code object with new values for the specified fields.

Added in version 3.8.

3.2.13.2. フレーム (frame) オブジェクト

Frame objects represent execution frames. They may occur in traceback objects, and are also passed to registered trace functions.

3.2.13.2.1. Special read-only attributes

frame.f_back

Points to the previous stack frame (towards the caller), or None if this is the bottom stack frame

frame.f_code

The code object being executed in this frame. Accessing this attribute raises an auditing event object.__getattr__ with arguments obj and "f_code".

frame.f_locals

The dictionary used by the frame to look up local variables

frame.f_globals

The dictionary used by the frame to look up global variables

frame.f_builtins

The dictionary used by the frame to look up built-in (intrinsic) names

frame.f_lasti

The "precise instruction" of the frame object (this is an index into the bytecode string of the code object)

3.2.13.2.2. Special writable attributes

frame.f_trace

If not 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 f_trace_lines).

frame.f_trace_lines

Set this attribute to False to disable triggering a tracing event for each source line.

frame.f_trace_opcodes

Set this attribute to 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.

frame.f_lineno

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.

3.2.13.2.3. Frame object methods

フレームオブジェクトはメソッドを一つサポートします:

frame.clear()

This method clears all references to local variables held by the frame. Also, if the frame belonged to a generator, the generator is finalized. This helps break reference cycles involving frame objects (for example when catching an exception and storing its traceback for later use).

RuntimeError is raised if the frame is currently executing.

Added in version 3.4.

3.2.13.3. トレースバック (traceback) オブジェクト

Traceback objects represent the stack trace of an exception. A traceback object is implicitly created when an exception occurs, and may also be explicitly created by calling 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 try 文.) It is accessible as the third item of the tuple returned by sys.exc_info(), and as the __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 sys.last_traceback.

For explicitly created tracebacks, it is up to the creator of the traceback to determine how the tb_next attributes should be linked to form a full stack trace.

Special read-only attributes:

traceback.tb_frame

Points to the execution frame of the current level.

Accessing this attribute raises an auditing event object.__getattr__ with arguments obj and "tb_frame".

traceback.tb_lineno

Gives the line number where the exception occurred

traceback.tb_lasti

Indicates the "precise instruction".

The line number and last instruction in the traceback may differ from the line number of its frame object if the exception occurred in a try statement with no matching except clause or with a finally clause.

traceback.tb_next

The special writable attribute tb_next is the next level in the stack trace (towards the frame where the exception occurred), or None if there is no next level.

バージョン 3.7 で変更: This attribute is now writable

3.2.13.4. スライス (slice) オブジェクト

スライスオブジェクトは、 __getitem__() メソッドのためのスライスを表すのに使われます。スライスオブジェクトは組み込みの slice() 関数でも生成されます。

読み出し専用の特殊属性: start は下限です; stop は上限です; step はステップの値です; それぞれ省略された場合は None となっています。これらの属性は任意の型を持てます。

スライスオブジェクトはメソッドを一つサポートします:

slice.indices(self, length)

このメソッドは単一の整数引数 length を取り、スライスオブジェクトが length 要素のシーケンスに適用されたときに表現する、スライスに関する情報を計算します。このメソッドは 3 つの整数からなるタプルを返します; それぞれ start および stop のインデックスと、step すなわちスライスのまたぎ幅です。インデックス値がないか、範囲外の値であれば、通常のスライスと変わらないやりかたで扱われます。

3.2.13.5. 静的メソッド (static method) オブジェクト

静的メソッドは、上で説明したような関数オブジェクトからメソッドオブジェクトへの変換を阻止するための方法を提供します。静的メソッドオブジェクトは他の何らかのオブジェクト、通常はユーザ定義メソッドオブジェクトを包むラッパです。静的メソッドをクラスやクラスインスタンスから取得すると、実際に返されるオブジェクトはラップされたオブジェクトになり、それ以上は変換の対象にはなりません。静的メソッドオブジェクトは通常呼び出し可能なオブジェクトをラップしますが、静的オブジェクト自体は呼び出し可能です。静的オブジェクトは組み込みコンストラクタ staticmethod() で生成されます。

3.2.13.6. クラスメソッドオブジェクト

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 "instance methods". Class method objects are created by the built-in classmethod() constructor.

3.3. 特殊メソッド名

クラスは、特殊な名前のメソッドを定義して、特殊な構文 (算術演算や添え字表記、スライス表記など) による特定の演算を実装できます。これは、Python の演算子オーバロード (operator overloading) へのアプローチです。これにより、クラスは言語の演算子に対する独自の振る舞いを定義できます。例えば、あるクラスが __getitem__() という名前のメソッドを定義しており、 x がこのクラスのインスタンスであるとすると、 x[i] は type(x).__getitem__(x, i) とほぼ等価です。特に注釈のない限り、適切なメソッドが定義されていないとき、このような演算を試みると例外 (たいていは AttributeError か TypeError) が送出されます。

特殊メソッドに None を設定することは、それに対応する演算が利用できないことを意味します。例えば、クラスの __iter__() を None に設定した場合、そのクラスはイテラブルにはならず、そのインスタンスに対し iter() を呼び出すと (__getitem__() に処理が戻されずに) TypeError を送出します。 [2]

組み込み型をエミュレートするクラスを実装するときは、模範とされるオブジェクトにとって意味がある範囲に実装をとどめるのが重要です。例えば、あるシーケンスは個々の要素の取得はきちんと動くかもしれませんが、スライスの展開が意味をなさないかもしれません。 (W3C のドキュメントオブジェクトモデルにある NodeList インターフェースがその一例です。)

3.3.1. 基本的なカスタマイズ

object.__new__(cls[, ...])

クラス cls の新しいインスタンスを作るために呼び出されます。 __new__() は静的メソッドで (このメソッドは特別扱いされているので、明示的に静的メソッドと宣言する必要はありません)、インスタンスを生成するよう要求されているクラスを第一引数にとります。残りの引数はオブジェクトのコンストラクタの式 (クラスの呼び出し文) に渡されます。 __new__() の戻り値は新しいオブジェクトのインスタンス (通常は cls のインスタンス) でなければなりません。

典型的な実装では、クラスの新たなインスタンスを生成するときには super().__new__(cls[, ...]) に適切な引数を指定してスーパクラスの __new__() メソッドを呼び出し、新たに生成されたインスタンスに必要な変更を加えてから返します。

もし __new__() が オブジェクトの作成中に呼び出され、cls のインスタンスを返した場合には、 __init__(self[, ...]) のようにして新しいインスタンスの __init__() が呼び出されます。このとき、 self は新たに生成されたインスタンスで、残りの引数はオブジェクトコンストラクタに渡された引数と同じになります。

__new__() が cls のインスタンスを返さない場合、インスタンスの __init__() メソッドは呼び出されません。

__new__() の主な目的は、変更不能な型 (int, str, tuple など) のサブクラスでインスタンス生成をカスタマイズすることにあります。また、クラス生成をカスタマイズするために、カスタムのメタクラスでよくオーバーライドされます。

object.__init__(self[, ...])

インスタンスが (__new__() によって) 生成された後、それが呼び出し元に返される前に呼び出されます。引数はクラスのコンストラクタ式に渡したものです。基底クラスとその派生クラスがともに __init__() メソッドを持つ場合、派生クラスの __init__() メソッドは基底クラスの __init__() メソッドを明示的に呼び出して、インスタンスの基底クラス部分が適切に初期化されること保証しなければなりません。例えば、 super().__init__([args...]) 。

__new__() と __init__() は連携してオブジェクトを構成する (__new__() が作成し、 __init__() がそれをカスタマイズする) ので、 __init__() から非 None 値を返してはいけません; そうしてしまうと、実行時に TypeError が送出されてしまいます。

object.__del__(self)

インスタンスが破棄されるときに呼び出されます。これはファイナライザや (適切ではありませんが) デストラクタとも呼ばれます。基底クラスが __del__() メソッドを持っている場合は、派生クラスの __del__() メソッドは何であれ、基底クラスの __del__() メソッドを明示的に呼び出して、インスタンスの基底クラス部分をきちんと確実に削除しなければなりません。

__del__() メソッドが破棄しようとしているインスタンスへの新しい参照を作り、破棄を送らせることは (推奨されないものの) 可能です。これはオブジェクトの 復活 と呼ばれます。復活したオブジェクトが再度破棄される直前に __del__() が呼び出されるかどうかは実装依存です; 現在の CPython の実装では最初の一回しか呼び出されません。

インタプリタが終了したときに、残存しているオブジェクトの __del__() メソッドが呼び出される保証はありません。

注釈

del x は直接 x.__del__() を呼び出しません --- 前者は x の参照カウントを 1 つ減らし、後者は x の参照カウントが 0 まで落ちたときのみ呼び出されます。

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

参考

gc モジュールのドキュメント。

警告

メソッド __del__() は不安定な状況で呼び出されるため、実行中に発生した例外は無視され、代わりに sys.stderr に警告が表示されます。特に:

__del__() は、任意のコードが実行されているときに、任意のスレッドから呼び出せます。 __del__() で、ロックを取ったり、ブロックするリソースを呼び出したりする必要がある場合、 __del__() の実行により中断されたコードにより、そのリソースが既に取得されていて、デッドロックが起きるかもしれません。

__del__() は、インタプリタのシャットダウン中に実行できます。従って、(他のモジュールも含めた) アクセスする必要があるグローバル変数はすでに削除されているか、 None に設定されているかもしれません。 Python は、単一のアンダースコアで始まる名前のグローバルオブジェクトは、他のグローバル変数が削除される前にモジュールから削除されることを保証します; そのようなグローバル変数への他からの参照が存在しない場合、__del__() メソッドが呼ばれた時点で、インポートされたモジュールがまだ利用可能であることを保証するのに役立つかもしれません。

object.__repr__(self)

repr() 組み込み関数によって呼び出され、オブジェクトを表す「公式の (official)」文字列を計算します。可能なら、これは (適切な環境が与えられれば) 同じ値のオブジェクトを再生成するのに使える、有効な Python 式のようなものであるべきです。できないなら、 <...some useful description...> 形式の文字列が返されるべきです。戻り値は文字列オブジェクトでなければなりません。クラスが __repr__() を定義していて __str__() は定義していなければ、そのクラスのインスタンスの「非公式の (informal)」文字列表現が要求されたときにも __repr__() が使われます。

この関数はデバッグの際によく用いられるので、たくさんの情報を含み、あいまいでないような表記にすることが重要です。

object.__str__(self)

オブジェクトの「非公式の (informal)」あるいは表示に適した文字列表現を計算するために、 str(object) と組み込み関数 format(), print() によって呼ばれます。戻り値は string オブジェクトでなければなりません。

__str__() が有効な Python 表現を返すことが期待されないという点で、このメソッドは object.__repr__() とは異なります: より便利な、または簡潔な表現を使用することができます。

組み込み型 object によって定義されたデフォルト実装は、 object.__repr__() を呼び出します。

object.__bytes__(self)

bytes によって呼び出され、オブジェクトのバイト文字列表現を計算します。これは bytes オブジェクトを返すべきです。

object.__format__(self, format_spec)

format() 組み込み関数、さらには フォーマット済み文字列リテラル の評価、 str.format() メソッドによって呼び出され、オブジェクトの "フォーマット化された (formatted)" 文字列表現を作ります。 format_spec 引数は、 必要なフォーマット化オプションの記述を含む文字列です。 format_spec 引数の解釈は、 __format__() を実装する型によりますが、 ほとんどのクラスは組み込み型のいずれかにフォーマット化を委譲したり、 同じようなフォーマット化オプション構文を使います。

標準のフォーマット構文の解説は、 書式指定ミニ言語仕様 を参照してください。

戻り値は文字列オブジェクトでなければなりません。

バージョン 3.4 で変更: 空でない文字列が渡された場合 object 自身の __format__ メソッドは TypeError を送出します。

バージョン 3.7 で変更: object.__format__(x, '') は format(str(x), '') ではなく str(x) と等価になりました。

object.__lt__(self, other)

object.__le__(self, other)

object.__eq__(self, other)

object.__ne__(self, other)

object.__gt__(self, other)

object.__ge__(self, other)

これらはいわゆる "拡張比較 (rich comparison)" メソッドです。演算子シンボルとメソッド名の対応は以下の通りです: x<y は x.__lt__(y) を呼び出します; x<=y は x.__le__(y) を呼び出します; x==y は x.__eq__(y) を呼び出します; x!=y は x.__ne__(y) を呼び出します; x>y は x.__gt__(y) を呼び出します; x>=y は x.__ge__(y) を呼び出します。

A rich comparison method may return the singleton NotImplemented if it does not implement the operation for a given pair of arguments. By convention, False and 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 if statement), Python will call bool() on the value to determine if the result is true or false.

By default, object implements __eq__() by using is, returning NotImplemented in the case of a false comparison: True if x is y else NotImplemented. For __ne__(), by default it delegates to __eq__() and inverts the result unless it is NotImplemented. There are no other implied relationships among the comparison operators or default implementations; for example, the truth of (x<y or x==y) does not imply x<=y. To automatically generate ordering operations from a single root operation, see functools.total_ordering().

カスタムの比較演算をサポートしていて、辞書のキーに使うことができる ハッシュ可能 オブジェクトを作るときの重要な注意点について、 __hash__() のドキュメント内に書かれているので参照してください。

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, __lt__() and __gt__() are each other's reflection, __le__() and __ge__() are each other's reflection, and __eq__() and __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 NotImplemented, the == and != operators will fall back to is and is not, respectively.

object.__hash__(self)

組み込みの hash() 関数や、 set, frozenset, dict のようなハッシュを使ったコレクション型の要素に対する操作から呼び出されます。 __hash__() メソッドは整数を返さなければなりません。このメソッドに必要な性質は、比較結果が等しいオブジェクトは同じハッシュ値を持つということです; オブジェクトを比較するときでも利用される要素をタプルに詰めてハッシュ値を計算することで、それぞれの要素のハッシュ値を混合することをおすすめします。

def __hash__(self):
    return hash((self.name, self.nick, self.color))

注釈

hash() はオブジェクト独自の __hash__() メソッドが返す値を Py_ssize_t のサイズに切り詰めます。これは 64-bit でビルドされていると 8 バイトで、 32-bit でビルドされていると 4 バイトです。オブジェクトの __hash__() が異なる bit サイズのビルドでも可搬性が必要である場合は、必ず全てのサポートするビルドの bit 幅をチェックしてください。そうする簡単な方法は python -c "import sys; print(sys.hash_info.width)" を実行することです。

クラスが __eq__() メソッドを定義していないなら、 __hash__() メソッドも定義してはなりません; クラスが __eq__() を定義していても __hash__() を定義していないなら、そのインスタンスはハッシュ可能コレクションの要素として使えません。クラスがミュータブルなオブジェクトを定義しており、 __eq__() メソッドを実装しているなら、 __hash__() を定義してはなりません。これは、ハッシュ可能 コレクションの実装においてキーのハッシュ値がイミュータブルであることが要求されているからです (オブジェクトのハッシュ値が変化すると、誤ったハッシュバケツ: hash bucket に入ってしまいます)。

ユーザー定義クラスはデフォルトで __eq__() と __hash__() メソッドを持っています。 このとき、(同一でない) すべてのオブジェクトは比較して異なり、 x.__hash__() は x == y が x is y と hash(x) == hash(y) の両方を意味するような適切な値を返します。

__eq__() をオーバーライドしていて __hash__() を定義していないクラスでは、 __hash__() は暗黙的に None に設定されます。クラスの __hash__() メソッドが None の場合、そのクラスのインスタンスのハッシュ値を取得しようとすると適切な TypeError が送出され、 isinstance(obj, collections.abc.Hashable) でチェックするとハッシュ不能なものとして正しく認識されます。

__eq__() をオーバーライドしたクラスが親クラスからの __hash__() の 実装を保持したいなら、明示的に __hash__ = <ParentClass>.__hash__ を設定することで、それをインタプリタに伝えなければなりません。

__eq__() をオーバーライドしていないクラスがハッシュサポートを抑制したい場合、クラス定義に __hash__ = None を含めてください。クラス自身で明示的に TypeError を送出する __hash__() を定義すると、 isinstance(obj, collections.abc.Hashable) 呼び出しで誤ってハッシュ可能と識別されるでしょう。

注釈

デフォルトでは、文字列とバイト列の __hash__() 値は予測不可能なランダム値で "ソルト" されます。 ハッシュ値は単独の Python プロセス内では定数であり続けますが、Python を繰り返し起動する毎に、予測できなくなります。

This is intended to provide protection against a denial-of-service caused by carefully chosen inputs that exploit the worst case performance of a dict insertion, O(n²) complexity. See http://ocert.org/advisories/ocert-2011-003.html for details.

ハッシュ値の変更は、集合のイテレーション順序に影響します。Python はこの順序付けを保証していません (そして通常 32-bit と 64-bit の間でも異なります)。

PYTHONHASHSEED も参照してください。

バージョン 3.3 で変更: ハッシュのランダム化がデフォルトで有効になりました。

object.__bool__(self)

Called to implement truth value testing and the built-in operation bool(); should return False or True. When this method is not defined, __len__() is called, if it is defined, and the object is considered true if its result is nonzero. If a class defines neither __len__() nor __bool__(), all its instances are considered true.

3.3.2. 属性値アクセスをカスタマイズする

以下のメソッドを定義して、クラスインスタンスへの属性アクセス ( x.name の使用、 x.name への代入、 x.name の削除) の意味をカスタマイズすることができます。

object.__getattr__(self, name)

デフォルトの属性アクセスが AttributeError で失敗したとき (name がインスタンスの属性または self のクラスツリーの属性でないために __getattribute__() が AttributeError を送出したか、 name プロパティの __get__() が AttributeError を送出したとき) に呼び出されます。このメソッドは (計算された) 属性値を返すか、 AttributeError 例外を送出しなければなりません。

Note that if the attribute is found through the normal mechanism, __getattr__() is not called. (This is an intentional asymmetry between __getattr__() and __setattr__().) This is done both for efficiency reasons and because otherwise __getattr__() would have no way to access other attributes of the instance. Note that at least for instance variables, you can fake total control by not inserting any values in the instance attribute dictionary (but instead inserting them in another object). See the __getattribute__() method below for a way to actually get total control over attribute access.

object.__getattribute__(self, name)

クラスのインスタンスに対する属性アクセスを実装するために、無条件に呼び出されます。クラスが __getattr__() も定義している場合、 __getattr__() は、 __getattribute__() で明示的に呼び出すか、 AttributeError 例外を送出しない限り呼ばれません。このメソッドは (計算された) 属性値を返すか、 AttributeError 例外を送出します。このメソッドが再帰的に際限なく呼び出されてしまうのを防ぐため、実装の際には常に、必要な属性全てへのアクセスで、例えば object.__getattribute__(self, name) のように基底クラスのメソッドを同じ属性名を使って呼び出さなければなりません。

注釈

This method may still be bypassed when looking up special methods as the result of implicit invocation via language syntax or built-in functions. See 特殊メソッド検索.

object.__getattr__ に obj と name を渡して実行すると、 監査イベント を送出します。

object.__setattr__(self, name, value)

属性の代入が試みられた際に呼び出されます。これは通常の代入の過程 (すなわち、インスタンス辞書への値の代入) の代わりに呼び出されます。name は属性名で、value はその属性に代入する値です。

__setattr__() の中でインスタンス属性への代入が必要なら、基底クラスのこれと同じ名前のメソッドを呼び出さなければなりません。例えば、 object.__setattr__(self, name, value) とします。

object.__setattr__ に obj と name と value を渡して実行すると、 監査イベント を送出します。

object.__delattr__(self, name)

__setattr__() に似ていますが、代入ではなく値の削除を行います。このメソッドを実装するのは、オブジェクトにとって del obj.name が意味がある場合だけにしなければなりません。

object.__delattr__ に obj と name を渡して実行すると、 監査イベント を送出します。

object.__dir__(self)

Called when dir() is called on the object. An iterable must be returned. dir() converts the returned iterable to a list and sorts it.

3.3.2.1. モジュールの属性値アクセスをカスタマイズする

特殊な名前の __getattr__ と __dir__ も、モジュール属性へのアクセスをカスタマイズするのに使えます。モジュールレベルの __getattr__ 関数は属性名である 1 引数を受け取り、計算した値を返すか AttributeError を送出します。属性がモジュールオブジェクトから、通常の検索、つまり object.__getattribute__() で見付からなかった場合は、 AttributeError を送出する前に、モジュールの __dict__ から __getattr__ が検索されます。見付かった場合は、その属性名で呼び出され、結果が返されます。

The __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 dir() search on a module.

より細かい粒度でのモジュールの動作 (属性やプロパティの設定など) のカスタマイズのために、モジュールオブジェクトの __class__ 属性に types.ModuleType のサブクラスが設定できます。例えば次のようになります:

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

注釈

モジュールの __getattr__ を定義したり __class__ を設定したりしても、影響があるのは属性アクセスの構文が使われる検索だけです -- モジュールの globals への直接アクセスは (モジュール内のコードからとモジュールの globals のどちらでも) 影響を受けません。

バージョン 3.5 で変更: モジュールの属性 __class__ が書き込み可能になりました。

Added in version 3.7: __getattr__ モジュール属性と __dir__ モジュール属性。

参考

PEP 562 [https://peps.python.org/pep-0562/] - モジュールの __getattr__ と __dir__

モジュールの __getattr__ 関数および __dir__ 関数の説明。

3.3.2.2. デスクリプタ (descriptor) の実装

以下のメソッドは、このメソッドを持つクラス (いわゆる デスクリプタ(descriptor) クラス) のインスタンスが、 オーナー (owner) クラスに存在するときにのみ適用されます (デスクリプタは、オーナーのクラス辞書か、その親のいずれかのクラス辞書になければなりません)。以下の例では、"属性" とは、名前がオーナークラスの __dict__ のプロパティ (porperty) のキーであるような属性を指します。

object.__get__(self, instance, owner=None)

オーナークラス（クラス属性アクセスの場合）や、クラスのインスタンス（インスタンス属性アクセスの場合）の属性取得時に呼び出されます。 instance を通じて属性をアクセスする時に、オプションの owner 引数はオーナークラスです。 owner を通じて属性アクセスするときは None です。

このメソッドは、算出された属性値を返すか、 AttributeError 例外を送出します。

PEP 252 [https://peps.python.org/pep-0252/] は __get__() は1つや2つの引数を持つ呼び出し可能オブジェクトであると定義しています。Pythonの組み込みのデスクリプタはこの仕様をサポートしていますが、サードパーティ製のツールの中には両方の引数を必要とするものもあります。Pythonの __getattribute__() 実装は必要かどうかに関わらず、両方の引数を常に渡します。

object.__set__(self, instance, value)

オーナークラスのインスタンス instance 上の属性を新たな値 value に設定する際に呼び出されます。

__set__() あるいは __delete__() を追加すると、デスクリプタは「データデスクリプタ」に変わります。詳細は デスクリプタの呼び出し を参照してください。

object.__delete__(self, instance)

オーナークラスのインスタンス instance 上の属性を削除する際に呼び出されます。

Instances of descriptors may also have the __objclass__ attribute present:

object.__objclass__

The attribute __objclass__ is interpreted by the 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).

3.3.2.3. デスクリプタの呼び出し

一般にデスクリプタとは、特殊な "束縛に関する動作 (binding behaviour)" をもつオブジェクト属性のことです。デスクリプタは、デスクリプタプロトコル (descriptor protocol) のメソッド: __get__(), __set__(), および __delete__() を使って、属性アクセスをオーバーライドしているものです。これらのメソッドのいずれかがオブジェクトに対して定義されている場合、オブジェクトはデスクリプタであるといいます。

属性アクセスのデフォルトの動作は、オブジェクトの辞書から値を取り出したり、値を設定したり、削除したりするというものです。例えば、 a.x による属性の検索では、まず a.__dict__['x'] 、次に type(a).__dict__['x'] 、そして type(a) の基底クラスでメタクラスでないものに続く、といった具合に連鎖が起こります。

しかし、検索対象の値が、デスクリプタメソッドのいずれかを定義しているオブジェクトであれば、Python はデフォルトの動作をオーバーライドして、代わりにデスクリプタメソッドを呼び出します。先述の連鎖の中のどこでデスクリプタメソッドが呼び出されるかは、どのデスクリプタメソッドが定義されていて、どのように呼び出されたかに依存します。

デスクリプタ呼び出しの基点となるのは、属性名への束縛 (binding) 、すなわち a.x です。引数がどのようにデスクリプタに結合されるかは a に依存します:

直接呼び出し (Direct Call)

最も単純で、かつめったに使われない呼び出し操作は、コード中で直接デスクリプタメソッドの呼び出し: x.__get__(a) を行うというものです。

インスタンス束縛 (Instance Binding)

オブジェクトインスタンスへ束縛すると、a.x は呼び出し type(a).__dict__['x'].__get__(a, type(a)) に変換されます。

クラス束縛 (Class Binding)

クラスへ束縛すると、A.x は呼び出し A.__dict__['x'].__get__(None, A) に変換されます。

super 束縛 (Super Binding)

super(A, a).x のようなドットを使ったルックアップは a.__class__.__mro__ を探索して、 A の前のクラス B をまず探し、 B.__dict__['x'].__get__(a, A) を返します。もしデスクリプタでなければ x を変更せずに返します。

For instance bindings, the precedence of descriptor invocation depends on which descriptor methods are defined. A descriptor can define any combination of __get__(), __set__() and __delete__(). If it does not define __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 __set__() and/or __delete__(), it is a data descriptor; if it defines neither, it is a non-data descriptor. Normally, data descriptors define both __get__() and __set__(), while non-data descriptors have just the __get__() method. Data descriptors with __get__() and __set__() (and/or __delete__()) defined always override a redefinition in an instance dictionary. In contrast, non-data descriptors can be overridden by instances.

(@staticmethod や @classmethod を含む) Python メソッドは、非データデスクリプタとして実装されています。その結果、インスタンスではメソッドを再定義したりオーバーライドできます。このことにより、個々のインスタンスが同じクラスの他のインスタンスと互いに異なる動作を獲得することができます。

property() 関数はデータデスクリプタとして実装されています。従って、インスタンスはあるプロパティの動作をオーバーライドすることができません。

3.3.2.4. __slots__

__slots__ を使うと、(プロパティのように) データメンバを明示的に宣言し、 (明示的に __slots__ で宣言しているか親クラスに存在しているかでない限り) __dict__ や __weakref__ を作成しないようにできます。

__dict__ を使うのに比べて、節約できるメモリ空間はかなり大きいです。属性探索のスピードもかなり向上できます。

object.__slots__

このクラス変数には、インスタンスが用いる変数名を表す、文字列、イテラブル、または文字列のシーケンスを代入できます。__slots__ は、各インスタンスに対して宣言された変数に必要な記憶領域を確保し、__dict__ と __weakref__ が自動的に生成されないようにします。

Notes on using __slots__:

__slots__ を持たないクラスから継承するとき、インスタンスの __dict__ 属性と __weakref__ 属性は常に利用可能です。

__dict__ 変数がない場合、 __slots__ に列挙されていない新たな変数をインスタンスに代入することはできません。列挙されていない変数名を使って代入しようとした場合、 AttributeError が送出されます。新たな変数を動的に代入したいのなら、 __slots__ を宣言する際に '__dict__' を変数名のシーケンスに追加してください。

__slots__ を定義しているクラスの各インスタンスに __weakref__ 変数がない場合、インスタンスに対する弱参照 (weak references) はサポートされません。弱参照のサポートが必要なら、 __slots__ を宣言する際に '__weakref__' を変数名のシーケンスに追加してください。

__slots__ は、クラスのレベルで各変数に対する デスクリプタ を使って実装されます。その結果、 __slots__ に定義されているインスタンス変数のデフォルト値はクラス属性を使って設定できなくなっています; そうしないと、デスクリプタによる代入をクラス属性が上書きしてしまうからです。

__slots__ の宣言の作用は、それが定義されたクラスだけには留まりません。親クラスで宣言された __slots__ は子クラスでも利用可能です。ただし、子クラスは、自身も __slots__ (ここには 追加の スロットの名前のみ含めるべき) を定義しない限り __dict__ や __weakref__ を持ちます。

あるクラスで、基底クラスですでに定義されているスロットを定義した場合、基底クラスのスロットで定義されているインスタンス変数は (デスクリプタを基底クラスから直接取得しない限り) アクセスできなくなります。これにより、プログラムの趣意が不定になってしまいます。将来は、この問題を避けるために何らかのチェックが追加されるかもしれません。

TypeError will be raised if nonempty __slots__ are defined for a class derived from a "variable-length" built-in type such as int, bytes, and tuple.

Any non-string iterable may be assigned to __slots__.

If a 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 inspect.getdoc() and displayed in the output of help().

__class__ への代入は、両方のクラスが同じ __slots__ を持っているときのみ動作します。

複数のスロットを持つ親クラスを使った 多重継承 はできますが、スロットで作成された属性を持つ親クラスは 1 つに限られます (他の基底クラスのスロットは空でなければなりません) - それに違反すると TypeError が送出されます。

もし __slots__ に対して イテレータ を使用すると、イテレータの値ごとに デスクリプタ が作られます。しかし、 __slots__ 属性は空のイテレータとなります。

3.3.3. クラス生成をカスタマイズする

クラスが他のクラスを継承するときに必ず、親クラスの __init_subclass__() が呼び出されます。これを利用すると、サブクラスの挙動を変更するクラスを書くことができます。これは、クラスデコレータととても良く似ていますが、クラスデコレータが、それが適用された特定のクラスにのみに影響するのに対して、 __init_subclass__ は、もっぱら、このメソッドを定義したクラスの将来のサブクラスに適用されます。

classmethod object.__init_subclass__(cls)

このメソッドは、それが定義されたクラスが継承された際に必ず呼び出されます。cls は新しいサブクラスです。もし、このメソッドがインスタンスメソッドとして定義されると、暗黙的にクラスメソッドに変換されます。

Keyword arguments which are given to a new class are passed to the parent class's __init_subclass__. For compatibility with other classes using __init_subclass__, one should take out the needed keyword arguments and pass the others over to the base class, as in:

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

object.__init_subclass__ のデフォルト実装は何も行いませんが、何らかの引数とともに呼び出された場合は、エラーを送出します。

注釈

メタクラスのヒント metaclass は残りの型機構によって消費され、 __init_subclass__ 実装に渡されることはありません。実際のメタクラス (明示的なヒントではなく) は、 type(cls) としてアクセスできます。

Added in version 3.6.

When a class is created, type.__new__() scans the class variables and makes callbacks to those with a __set_name__() hook.

object.__set_name__(self, owner, name)

オーナーとなるクラス owner が作成された時点で自動的に呼び出されます。オブジェクトはそのクラスの name に割り当てられます。

class A:
    x = C()  # Automatically calls: x.__set_name__(A, 'x')

If the class variable is assigned after the class is created, __set_name__() will not be called automatically. If needed, __set_name__() can be called directly:

class A:
   pass

c = C()
A.x = c                  # The hook is not called
c.__set_name__(A, 'x')   # Manually invoke the hook

詳細は クラスオブジェクトの作成 を参照してください。

Added in version 3.6.

3.3.3.1. メタクラス

デフォルトでは、クラスは type() を使って構築されます。 クラス本体は新しい名前空間で実行され、クラス名が type(name, bases, namespace) の結果にローカルに束縛されます。

クラス生成プロセスはカスタマイズできます。そのためにはクラス定義行で metaclass キーワード引数を渡すか、そのような引数を定義行に含む既存のクラスを継承します。次の例で MyClass と MySubclass は両方とも Meta のインスタンスです:

class Meta(type):
    pass

class MyClass(metaclass=Meta):
    pass

class MySubclass(MyClass):
    pass

クラス定義の中で指定された他のキーワード引数は、後述するすべてのメタクラス操作に渡されます。

クラス定義が実行される際に、以下のステップが生じます:

MRO エントリの解決が行われる;

適切なメタクラスが決定される;

クラスの名前空間が準備される;

クラスの本体が実行される;

クラスオブジェクトが作られる。

3.3.3.2. MRO エントリの解決

object.__mro_entries__(self, bases)

If a base that appears in a class definition is not an instance of type, then an __mro_entries__() method is searched on the base. If an __mro_entries__() method is found, the base is substituted with the result of a call to __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.

参考

types.resolve_bases()

Dynamically resolve bases that are not instances of type.

types.get_original_bases()

Retrieve a class's "original bases" prior to modifications by __mro_entries__().

PEP 560 [https://peps.python.org/pep-0560/]

Core support for typing module and generic types.

3.3.3.3. 適切なメタクラスの決定

クラス定義に対して適切なメタクラスは、以下のように決定されます:

基底も明示的なメタクラスも与えられていない場合は、 type() が使われます;

明示的なメタクラスが与えられていて、それが type() のインスタンス ではない 場合、それをメタクラスとして直接使います;

明示的なメタクラスとして type() のインスタンスが与えられたか、基底が定義されていた場合は、最も派生した (継承関係で最も下の) メタクラスが使われます。

最も派生的なメタクラスは、(もしあれば) 明示的に指定されたメタクラスと、指定されたすべてのベースクラスのメタクラスから選ばれます。最も派生的なメタクラスは、これらのメタクラス候補のすべてのサブタイプであるようなものです。メタクラス候補のどれもその基準を満たさなければ、クラス定義は TypeError で失敗します。

3.3.3.4. クラスの名前空間の準備

適切なメタクラスが指定されると、クラスの名前空間が用意されます。もしメタクラスが __prepare__ 属性を持っている場合、 namespace = metaclass.__prepare__(name, bases, **kwds) が呼ばれます。追加のキーワード引数は、もしクラス定義にあれば設定されます。 __prepare__ メソッドは クラスメソッド として実装する必要があります。 __prepare__ が作成して返した名前空間は __new__ に渡されますが、最終的なクラスオブジェクトは新しい dict にコピーして作成されます。

メタクラスに __prepare__ 属性がない場合、クラスの名前空間は空の 順序付きマッピングとして初期化されます。

参考

PEP 3115 [https://peps.python.org/pep-3115/] - Metaclasses in Python 3000

__prepare__ 名前空間フックの導入

3.3.3.5. クラス本体の実行

クラス本体が (大まかには) exec(body, globals(), namespace) として実行されます。通常の呼び出しと exec() の重要な違いは、クラス定義が関数内部で行われる場合、レキシカルスコープによってクラス本体 (任意のメソッドを含む) が現在のスコープと外側のスコープから名前を参照できるという点です。

しかし、クラス定義が関数内部で行われる時でさえ、クラス内部で定義されたメソッドはクラススコープで定義された名前を見ることはできません。クラス変数はインスタンスメソッドかクラスメソッドの最初のパラメータからアクセスするか、次の節で説明する、暗黙的に静的スコープが切られている __class__ 参照からアクセスしなければなりません。

3.3.3.6. クラスオブジェクトの作成

クラス本体の実行によってクラスの名前空間が初期化されたら、metaclass(name, bases, namespace, **kwds) を呼び出すことでクラスオブジェクトが作成されます (ここで渡される追加のキーワードは __prepare__ に渡されるものと同じです)。

このクラスオブジェクトは、 super() の無引数形式によって参照されるものです。 __class__ は、クラス本体中のメソッドが __class__ または super のいずれかを参照している場合に、コンパイラによって作成される暗黙のクロージャー参照です。これは、メソッドに渡された最初の引数に基づいて現在の呼び出しを行うために使用されるクラスまたはインスタンスが識別される一方、 super() の無引数形式がレキシカルスコープに基づいて定義されているクラスを正確に識別することを可能にします。

CPython 実装の詳細: CPython 3.6 以降では、 __class__ セルは、クラス名前空間にある __classcell__ エントリーとしてメタクラスに渡されます。 __class__ セルが存在していた場合は、そのクラスが正しく初期化されるために、 type.__new__ の呼び出しに到達するまで上に伝搬されます。失敗した場合は、Python 3.8 では RuntimeError になります。

デフォルトのメタクラス type や最終的には type.__new__ を呼び出すメタクラスを使っているときは、クラスオブジェクトを作成した後に次のカスタム化の手順が起動されます:

type.__new__ メソッドが __set_name__() が定義されているクラスの名前空間にある全ての属性を収集します;

それらの __set_name__ メソッドが、そのメソッドが定義されているクラス、およびそこに属する属性に割り当てられている名前を引数として呼び出されます;

新しいクラスのメソッド解決順序ですぐ上に位置する親クラスで __init_subclass__() フックが呼び出されます。

クラスオブジェクトが作成された後には、クラス定義に含まれているクラスデコレータ (もしあれば) にクラスオブジェクトが渡され、デコレータが返すオブジェクトがここで定義されたクラスとしてローカルの名前空間に束縛されます。

新しいクラスが type.__new__ で生成されたときは、名前空間引数として与えられたオブジェクトは新しい順序付きのマッピングに複製され、元のオブジェクトは破棄されます。新しく複製したものは読み出し専用のプロキシでラップされ、クラスオブジェクトの __dict__ 属性になります。

参考

PEP 3135 [https://peps.python.org/pep-3135/] - New super

暗黙の __class__ クロージャ参照について記述しています

3.3.3.7. メタクラスの用途

メタクラスは限りない潜在的利用価値を持っています。これまで試されてきたアイデアには、列挙型、ログ記録、インターフェースのチェック、 自動デリゲーション、自動プロパティ生成、プロキシ、フレームワーク、そして自動リソースロック／同期といったものがあります。

3.3.4. インスタンスのカスタマイズとサブクラスチェック

以下のメソッドは組み込み関数 isinstance() と issubclass() のデフォルトの動作を上書きするのに利用します。

特に、 abc.ABCMeta メタクラスは、抽象基底クラス (ABCs) を"仮想基底クラス (virtual base classes)" として、他の ABC を含む、任意のクラスや (組み込み型を含む) 型に追加するために、これらのメソッドを実装しています。

class.__instancecheck__(self, instance)

instance が (直接、または間接的に) class のインスタンスと考えられる場合に true を返します。定義されていれば、 isinstance(instance, class) の実装のために呼び出されます。

class.__subclasscheck__(self, subclass)

subclass が (直接、または間接的に) class のサブクラスと考えられる場合に true を返します。定義されていれば、 issubclass(subclass, class) の実装のために呼び出されます。

なお、これらのメソッドは、クラスの型 (メタクラス) 上で検索されます。実際のクラスにクラスメソッドとして定義することはできません。これは、インスタンスそれ自体がクラスであるこの場合にのみ、インスタンスに呼び出される特殊メソッドの検索と一貫しています。

参考

PEP 3119 [https://peps.python.org/pep-3119/] - 抽象基底クラスの導入

抽象基底クラス (abc モジュールを参照) を言語に追加する文脈においての動機から、 __instancecheck__() と __subclasscheck__() を通して、 isinstance() と issubclass() に独自の動作をさせるための仕様の記述があります。

3.3.5. ジェネリック型をエミュレートする

When using type annotations, it is often useful to parameterize a generic type using Python's square-brackets notation. For example, the annotation list[int] might be used to signify a list in which all the elements are of type int.

参考

PEP 484 [https://peps.python.org/pep-0484/] - 型ヒント

Introducing Python's framework for type annotations

Generic Alias Types

Documentation for objects representing parameterized generic classes

ジェネリクス, user-defined generics and typing.Generic

実行時にパラメータ設定が可能であり、かつ静的な型チェッカーが理解できるジェネリッククラスを実装する方法のドキュメントです。

A class can generally only be parameterized if it defines the special class method __class_getitem__().

classmethod object.__class_getitem__(cls, key)

key にある型引数で特殊化されたジェネリッククラスを表すオブジェクトを返します。

When defined on a class, __class_getitem__() is automatically a class method. As such, there is no need for it to be decorated with @classmethod when it is defined.

3.3.5.1. The purpose of __class_getitem__

The purpose of __class_getitem__() is to allow runtime parameterization of standard-library generic classes in order to more easily apply 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 __class_getitem__(), or inherit from typing.Generic, which has its own implementation of __class_getitem__().

Custom implementations of __class_getitem__() on classes defined outside of the standard library may not be understood by third-party type-checkers such as mypy. Using __class_getitem__() on any class for purposes other than type hinting is discouraged.

3.3.5.2. __class_getitem__ versus __getitem__

Usually, the subscription of an object using square brackets will call the __getitem__() instance method defined on the object's class. However, if the object being subscribed is itself a class, the class method __class_getitem__() may be called instead. __class_getitem__() should return a GenericAlias object if it is properly defined.

Presented with the expression obj[x], the Python interpreter follows something like the following process to decide whether __getitem__() or __class_getitem__() should be called:

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"
        )

In Python, all classes are themselves instances of other classes. The class of a class is known as that class's metaclass, and most classes have the type class as their metaclass. type does not define __getitem__(), meaning that expressions such as list[int], dict[str, float] and tuple[str, bytes] all result in __class_getitem__() being called:

>>> # 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'>

However, if a class has a custom metaclass that defines __getitem__(), subscribing the class may result in different behaviour. An example of this can be found in the enum module:

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

参考

PEP 560 [https://peps.python.org/pep-0560/] - typing モジュールとジェネリック型に対する言語コアによるサポート

Introducing __class_getitem__(), and outlining when a subscription results in __class_getitem__() being called instead of __getitem__()

3.3.6. 呼び出し可能オブジェクトをエミュレートする

object.__call__(self[, args...])

インスタンスが関数として "呼ばれた" 際に呼び出されます。このメソッドが定義されている場合、 x(arg1, arg2, ...) は大まかには type(x).__call__(x, arg1, ...) に変換されます。

3.3.7. コンテナをエミュレートする

The following methods can be defined to implement container objects. Containers usually are sequences (such as lists or tuples) or mappings (like 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 0 <= k < N where N is the length of the sequence, or slice objects, which define a range of items. It is also recommended that mappings provide the methods keys(), values(), items(), get(), clear(), setdefault(), pop(), popitem(), copy(), and update() behaving similar to those for Python's standard dictionary objects. The collections.abc module provides a MutableMapping abstract base class to help create those methods from a base set of __getitem__(), __setitem__(), __delitem__(), and keys(). Mutable sequences should provide methods append(), count(), index(), extend(), insert(), pop(), remove(), reverse() and sort(), like Python standard list objects. Finally, sequence types should implement addition (meaning concatenation) and multiplication (meaning repetition) by defining the methods __add__(), __radd__(), __iadd__(), __mul__(), __rmul__() and __imul__() described below; they should not define other numerical operators. It is recommended that both mappings and sequences implement the __contains__() method to allow efficient use of the in operator; for mappings, 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 __iter__() method to allow efficient iteration through the container; for mappings, __iter__() should iterate through the object's keys; for sequences, it should iterate through the values.

object.__len__(self)

Called to implement the built-in function len(). Should return the length of the object, an integer >= 0. Also, an object that doesn't define a __bool__() method and whose __len__() method returns zero is considered to be false in a Boolean context.

CPython 実装の詳細: In CPython, the length is required to be at most sys.maxsize. If the length is larger than sys.maxsize some features (such as len()) may raise OverflowError. To prevent raising OverflowError by truth value testing, an object must define a __bool__() method.

object.__length_hint__(self)

Called to implement 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 >= 0. The return value may also be NotImplemented, which is treated the same as if the __length_hint__ method didn't exist at all. This method is purely an optimization and is never required for correctness.

Added in version 3.4.

注釈

スライシングは、以下の 3 メソッドによって排他的に行われます。次のような呼び出しは

a[1:2] = b

次のように翻訳され

a[slice(1, 2, None)] = b

以下も同様です。存在しないスライスの要素は None で埋められます。

object.__getitem__(self, key)

Called to implement evaluation of self[key]. For sequence types, the accepted keys should be integers. Optionally, they may support slice objects as well. Negative index support is also optional. If key is of an inappropriate type, TypeError may be raised; if key is a value outside the set of indexes for the sequence (after any special interpretation of negative values), IndexError should be raised. For mapping types, if key is missing (not in the container), KeyError should be raised.

注釈

for ループでは、シーケンスの終端を正しく検出できるようにするために、不正なインデクスに対して IndexError が送出されるものと期待しています。

注釈

When subscripting a class, the special class method __class_getitem__() may be called instead of __getitem__(). See __class_getitem__ versus __getitem__ for more details.

object.__setitem__(self, key, value)

self[key] に対する代入を実装するために呼び出されます。 __getitem__() と同じ注意事項があてはまります。このメソッドを実装できるのは、あるキーに対する値の変更をサポートしているか、新たなキーを追加できるようなマップの場合と、ある要素を置き換えることができるシーケンスの場合だけです。不正な key に対しては、 __getitem__() メソッドと同様の例外の送出を行わなければなりません。

object.__delitem__(self, key)

self[key] の削除を実装するために呼び出されます。 __getitem__() と同じ注意事項があてはまります。このメソッドを実装できるのは、キーの削除をサポートしているマップの場合と、要素を削除できるシーケンスの場合だけです。不正な key に対しては、 __getitem__() メソッドと同様の例外の送出を行わなければなりません。

object.__missing__(self, key)

self[key] の実装において辞書内にキーが存在しなかった場合に、 dict のサブクラスのために dict.__getitem__() によって呼び出されます。

object.__iter__(self)

このメソッドは、コンテナに対して イテレータ が要求された際に呼び出されます。このメソッドは、コンテナ内の全てのオブジェクトに渡って反復処理できるような、新たなイテレータオブジェクトを返さなければなりません。マッピングでは、コンテナ内のキーに渡って反復処理しなければなりません。

object.__reversed__(self)

reversed() 組み込み関数が逆方向イテレーションを実装するために、(存在すれば)呼び出します。コンテナ内の全要素を逆順にイテレートする、新しいイテレータを返すべきです。

__reversed__() メソッドが定義されていない場合、 reversed() 組込み関数は sequence プロトコル (__len__() と __getitem__()) を使った方法にフォールバックします。 sequence プロトコルをサポートしたオブジェクトは、 reversed() よりも効率のいい実装を提供できる場合にのみ __reversed__() を定義するべきです。

帰属テスト演算子 (in および not in) は通常、コンテナの要素に対する反復処理のように実装されます。しかし、コンテナオブジェクトで以下の特殊メソッドを定義して、より効率的な実装を行ったり、オブジェクトがイテラブルでなくてもよいようにできます。

object.__contains__(self, item)

帰属テスト演算を実装するために呼び出されます。 item が self 内に存在する場合には真を、そうでない場合には偽を返さなければなりません。マップオブジェクトの場合、値やキーと値の組ではなく、キーに対する帰属テストを考えなければなりません。

__contains__() を定義しないオブジェクトに対しては、メンバシップテストはまず、 __iter__() を使った反復を試みます、次に古いシーケンス反復プロトコル __getitem__() を使います、 言語レファレンスのこの節 を参照して下さい。

3.3.8. 数値型をエミュレートする

以下のメソッドを定義して、数値型オブジェクトをエミュレートすることができます。特定の種類の数値型ではサポートされていないような演算に対応するメソッド (非整数の数値に対するビット単位演算など) は、未定義のままにしておかなければなりません。

object.__add__(self, other)

object.__sub__(self, other)

object.__mul__(self, other)

object.__matmul__(self, other)

object.__truediv__(self, other)

object.__floordiv__(self, other)

object.__mod__(self, other)

object.__divmod__(self, other)

object.__pow__(self, other[, modulo])

object.__lshift__(self, other)

object.__rshift__(self, other)

object.__and__(self, other)

object.__xor__(self, other)

object.__or__(self, other)

これらのメソッドを呼んで二項算術演算子 (+, -, *, @, /, //, %, divmod(), pow(), **, <<, >>, &, ^, |) を実装します。例えば x が __add__() メソッドのあるクラスのインスタンスである場合、式 x + y を評価すると type(x).__add__(x, y) が呼ばれます。 __divmod__() メソッドは __floordiv__() と __mod__() を使用するのと等価でなければなりません。 __truediv__() と関連してはなりません。組み込みの pow() 関数の三項のものがサポートされていなければならない場合、 __pow__() はオプションの第三引数を受け取るものとして定義されなければなりません。

If one of those methods does not support the operation with the supplied arguments, it should return NotImplemented.

object.__radd__(self, other)

object.__rsub__(self, other)

object.__rmul__(self, other)

object.__rmatmul__(self, other)

object.__rtruediv__(self, other)

object.__rfloordiv__(self, other)

object.__rmod__(self, other)

object.__rdivmod__(self, other)

object.__rpow__(self, other[, modulo])

object.__rlshift__(self, other)

object.__rrshift__(self, other)

object.__rand__(self, other)

object.__rxor__(self, other)

object.__ror__(self, other)

These methods are called to implement the binary arithmetic operations (+, -, *, @, /, //, %, divmod(), pow(), **, <<, >>, &, ^, |) with reflected (swapped) operands. These functions are only called if the left operand does not support the corresponding operation [3] and the operands are of different types. [4] For instance, to evaluate the expression x - y, where y is an instance of a class that has an __rsub__() method, type(y).__rsub__(y, x) is called if type(x).__sub__(x, y) returns NotImplemented.

ただし、三項演算子 pow() が __rpow__() を呼ぶことはないので注意してください (型強制の規則が非常に難解になるからです)。

注釈

右側の被演算子の型が左側の被演算子の型のサブクラスであり、このサブクラスであるメソッドに対する反射メソッドと異なる実装が定義されている場合には、左側の被演算子の非反射メソッドが呼ばれる前に、このメソッドが呼ばれます。この振る舞いにより、サブクラスが親の演算をオーバーライドすることが可能になります。

object.__iadd__(self, other)

object.__isub__(self, other)

object.__imul__(self, other)

object.__imatmul__(self, other)

object.__itruediv__(self, other)

object.__ifloordiv__(self, other)

object.__imod__(self, other)

object.__ipow__(self, other[, modulo])

object.__ilshift__(self, other)

object.__irshift__(self, other)

object.__iand__(self, other)

object.__ixor__(self, other)

object.__ior__(self, other)

These methods are called to implement the augmented arithmetic assignments (+=, -=, *=, @=, /=, //=, %=, **=, <<=, >>=, &=, ^=, |=). 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 NotImplemented, the augmented assignment falls back to the normal methods. For instance, if x is an instance of a class with an __iadd__() method, x += y is equivalent to x = x.__iadd__(y) . If __iadd__() does not exist, or if x.__iadd__(y) returns NotImplemented, x.__add__(y) and y.__radd__(x) are considered, as with the evaluation of x + y. In certain situations, augmented assignment can result in unexpected errors (see なぜ加算はされるのに a_tuple[i] += ['item'] は例外を送出するのですか?), but this behavior is in fact part of the data model.

object.__neg__(self)

object.__pos__(self)

object.__abs__(self)

object.__invert__(self)

呼び出して単項算術演算 (-, +, abs() および ~) を実装します。

object.__complex__(self)

object.__int__(self)

object.__float__(self)

組み込み関数の complex(), int(), float() の実装から呼び出されます。適切な型の値を返さなければなりません。

object.__index__(self)

呼び出して operator.index() を実装します。 Python が数値オブジェクトを整数オブジェクトに損失なく変換する必要がある場合 (たとえばスライシングや、組み込みの bin() 、 hex() 、 oct() 関数) は常に呼び出されます。このメソッドがあるとその数値オブジェクトが整数型であることが示唆されます。整数を返さなければなりません。

もし __int__(), __float__(), __complex__() が定義されていない場合、組み込み関数の int(), float(), complex() は __index__() にフォールバックします。

object.__round__(self[, ndigits])

object.__trunc__(self)

object.__floor__(self)

object.__ceil__(self)

組み込み関数の round() と math モジュール関数の trunc(), floor(), ceil() の実装から呼び出されます。 ndigits が __round__() に渡されない限りは、これらの全てのメソッドは Integral (たいていは int) に切り詰められたオブジェクトの値を返すべきです。

The built-in function int() falls back to __trunc__() if neither __int__() nor __index__() is defined.

バージョン 3.11 で変更: int() の __trunc__() への処理の委譲は非推奨になりました。

3.3.9. with文とコンテキストマネージャ

コンテキストマネージャ(context manager) とは、 with 文の実行時にランタイムコンテキストを定義するオブジェクトです。コンテキストマネージャは、コードブロックを実行するために必要な入り口および出口の処理を扱います。コンテキストマネージャは通常、 with 文（ with 文 の章を参照）により起動されますが、これらのメソッドを直接呼び出すことで起動することもできます。

コンテキストマネージャの代表的な使い方としては、様々なグローバル情報の保存および更新、リソースのロックとアンロック、ファイルのオープンとクローズなどが挙げられます。

コンテキストマネージャについてのさらなる情報については、 コンテキストマネージャ型 を参照してください。

object.__enter__(self)

コンテキストマネージャのの入り口で実行される処理です。 with 文は、文の as 節で規定された値を返すこのメソッドを呼び出します。

object.__exit__(self, exc_type, exc_value, traceback)

コンテキストマネージャの出口で実行される処理です。パラメータは、コンテキストが終了した原因となった例外について説明しています。コンテキストが例外を送出せず終了した場合は、全ての引き数に None が設定されます。

もし、例外が送出され、かつメソッドが例外を抑制したい場合（すなわち、例外が伝播されるのを防ぎたい場合）、このメソッドは True を返す必要があります。そうでなければ、このメソッドの終了後、例外は通常通り伝播することになります。

Note that __exit__() methods should not reraise the passed-in exception; this is the caller's responsibility.

参考

PEP 343 [https://peps.python.org/pep-0343/] - "with" ステートメント

Python の with 文の仕様、背景、および例が記載されています。

3.3.10. クラスパターンマッチの位置引数のカスタマイズ

パターンの中でクラス名を利用する場合、位置引数はデフォルトでは利用できません。 MyClass で特別なサポートがないと、 case MyClass(x, y) は通常無効です。このようなパターンを利用するには、 __match_args__ 属性をクラスに定義する必要があります。

object.__match_args__

このクラス変数には文字列のタプルがアサイン可能です。このクラスがクラスパターンの位置引数の中で利用されると、それぞれの位置引数は対応する __match_args__ の中の値をキーワードとする、キーワード引数に変換されます。この属性がない時は、 () が設定されているのと同義です。

例えば、もし MyClass.__match_args__ に ("left", "center", "right") が定義されていた場合、 case MyClass(x, y) は case MyClass(left=x, center=y) と同義です。パターンの引数の数は、 __match_args__ の要素数と同等かそれ以下でなければならない点に注意してください。もし、多かった場合には、パターンマッチは TypeError を送出します。

Added in version 3.10.

参考

PEP 634 [https://peps.python.org/pep-0634/] - 構造的パターンマッチ

match 文の詳細。

3.3.11. Emulating buffer types

The 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 bytes and 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.

object.__buffer__(self, flags)

Called when a buffer is requested from self (for example, by the 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. inspect.BufferFlags provides a convenient way to interpret the flags. The method must return a memoryview object.

object.__release_buffer__(self, buffer)

Called when a buffer is no longer needed. The buffer argument is a memoryview object that was previously returned by __buffer__(). The method must release any resources associated with the buffer. This method should return None. Buffer objects that do not need to perform any cleanup are not required to implement this method.

Added in version 3.12.

参考

PEP 688 [https://peps.python.org/pep-0688/] - Making the buffer protocol accessible in Python

Introduces the Python __buffer__ and __release_buffer__ methods.

collections.abc.Buffer

ABC for buffer types.

3.3.12. 特殊メソッド検索

カスタムクラスでは、特殊メソッドの暗黙の呼び出しは、オブジェクトのインスタンス辞書ではなく、オブジェクトの型で定義されているときにのみ正しく動作することが保証されます。この動作のため、以下のコードは例外を送出します:

>>> 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()

この動作の背景となる理由は、 __hash__() と __repr__() といった type オブジェクトを含むすべてのオブジェクトで定義されている特殊メソッドにあります。これらのメソッドの暗黙の検索が通常の検索プロセスを使った場合、 type オブジェクト自体に対して実行されたときに失敗してしまいます:

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

クラスの非結合メソッドをこのようにして実行しようとすることは、'metaclass confusion' と呼ばれることもあり、特殊メソッドを検索するときはインスタンスをバイパスすることで回避されます:

>>> type(1).__hash__(1) == hash(1)
True
>>> type(int).__hash__(int) == hash(int)
True

正確性のためにインスタンス属性をスキップするのに加えて、特殊メソッド検索はオブジェクトのメタクラスを含めて、 __getattribute__() メソッドもバイパスします:

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

このように __getattribute__() 機構をバイパスすることで、特殊メソッドの扱いに関するある程度の自由度と引き換えに (特殊メソッドはインタプリタから一貫して実行されるためにクラスオブジェクトに設定 しなければならない)、インタープリタを高速化するための大きな余地が手に入ります。

3.4. コルーチン

3.4.1. 待機可能オブジェクト (Awaitable Object)

awaitable オブジェクトは一般的には __await__() メソッドが実装されています。 async def 関数が返す Coroutineオブジェクト は待機可能です。

注釈

types.coroutine() デコレータでデコレータが付けられたジェネレータから返される generator iterator オブジェクトも待機可能ですが、 __await__() は実装されていません。

object.__await__(self)

iterator を返さなければなりません。このメソッドは awaitable オブジェクトを実装するのに使われるべきです。簡単のために、 asyncio.Future にはこのメソッドが実装され、 await 式と互換性を持つようになっています。

注釈

The language doesn't place any restriction on the type or value of the objects yielded by the iterator returned by __await__, as this is specific to the implementation of the asynchronous execution framework (e.g. asyncio) that will be managing the awaitable object.

Added in version 3.5.

参考

待機可能オブジェクトについてより詳しくは PEP 492 [https://peps.python.org/pep-0492/] を参照してください。

3.4.2. コルーチンオブジェクト

Coroutineオブジェクト は awaitable オブジェクトです。__await__() を呼び出し、その返り値に対し反復処理をすることでコルーチンの実行を制御できます。コルーチンの実行が完了し制御を戻したとき、イテレータは StopIteration を送出し、その例外の value 属性に返り値を持たせます。コルーチンが例外を送出した場合は、イテレータにより伝搬されます。コルーチンから StopIteration 例外を外に送出すべきではありません。

コルーチンには以下に挙げるメソッドもあり、これらはジェネレータのメソッドからの類似です (ジェネレータ-イテレータメソッド を参照してください)。ただし、ジェネレータと違って、コルーチンは反復処理を直接はサポートしていません。

バージョン 3.5.2 で変更: コルーチンで2回以上待機 (await) すると RuntimeError となります。

coroutine.send(value)

Starts or resumes execution of the coroutine. If value is None, this is equivalent to advancing the iterator returned by __await__(). If value is not None, this method delegates to the send() method of the iterator that caused the coroutine to suspend. The result (return value, StopIteration, or other exception) is the same as when iterating over the __await__() return value, described above.

coroutine.throw(value)

coroutine.throw(type[, value[, traceback]])

コルーチンで指定された例外を送出します。このメソッドは、イテレータにコルーチンを一時停止する throw() メソッドがある場合に処理を委任します。そうでない場合には、中断した地点から例外が送出されます。結果 (返り値か StopIteration かその他の例外) は、上で解説したような __await__() の返り値に対して反復処理を行ったときと同じです。例外がコルーチンの中で捕捉されなかった場合、呼び出し元へ伝搬されます。

バージョン 3.12 で変更: The second signature (type[, value[, traceback]]) is deprecated and may be removed in a future version of Python.

coroutine.close()

コルーチンが自分自身の後片付けをし終了します。コルーチンが一時停止している場合は、コルーチンを一時停止させたイテレータに close() メソッドがあれば、まずはそれに処理を委任します。そして一時停止した地点から GeneratorExit が送出され、ただちにコルーチンが自分自身の後片付けを行います。最後に、実行が開始されていなかった場合でも、コルーチンに実行が完了した印を付けます。

コルーチンオブジェクトが破棄されるときには、上記の手順を経て自動的に閉じられます。

3.4.3. 非同期イテレータ (Asynchronous Iterator)

非同期イテレータ の __anext__ メソッドからは非同期のコードが呼べます。

非同期イテレータは async for 文の中で使えます。

object.__aiter__(self)

非同期イテレータ オブジェクトを返さなくてはなりません。

object.__anext__(self)

イテレータの次の値を返す 待機可能オブジェクト を返さなければなりません。反復処理が終了したときには StopAsyncIteration エラーを送出すべきです。

非同期イテラブルオブジェクトの例:

class Reader:
    async def readline(self):
        ...

    def __aiter__(self):
        return self

    async def __anext__(self):
        val = await self.readline()
        if val == b'':
            raise StopAsyncIteration
        return val

Added in version 3.5.

バージョン 3.7 で変更: Python 3.7 より前では、 __aiter__() は 非同期イテレータ になる awaitable を返せました。

Python 3.7 からは、 __aiter__() は非同期イテレータオブジェクトを返さなければなりません。それ以外のものを返すと TypeError になります。

3.4.4. 非同期コンテキストマネージャ (Asynchronous Context Manager)

非同期コンテキストマネージャ は、 __aenter__ メソッドと __aexit__ メソッド内部で実行を一時停止できる コンテキストマネージャ です。

非同期コンテキストマネージャは async with 文の中で使えます。

object.__aenter__(self)

Semantically similar to __enter__(), the only difference being that it must return an awaitable.

object.__aexit__(self, exc_type, exc_value, traceback)

Semantically similar to __exit__(), the only difference being that it must return an awaitable.

非同期コンテキストマネージャクラスの例:

class AsyncContextManager:
    async def __aenter__(self):
        await log('entering context')

    async def __aexit__(self, exc_type, exc, tb):
        await log('exiting context')

Added in version 3.5.

脚注

[1]

特定の条件が満たされた場合、オブジェクトの type を変更することが できます 。これは、正しく扱われなかった場合にとても奇妙な動作を引き起こすので、一般的には良い考えではありません。

[2]

The __hash__(), __iter__(), __reversed__(), and __contains__() methods have special handling for this; others will still raise a TypeError, but may do so by relying on the behavior that None is not callable.

[3]

"Does not support" here means that the class has no such method, or the method returns NotImplemented. Do not set the method to 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.

[4]

同じ型の被演算子については、無反転のメソッド (たとえば __add__()) が失敗した場合、その演算はサポートされていないとみなされます。これは、反射したメソッドが呼び出されない理由です。

4. 実行モデル

4.1. プログラムの構造

Python プログラムはコードブロックから構成されます。ブロック (block) は、一つのまとまりとして実行される Python プログラムテキストの断片です。モジュール、関数本体、そしてクラス定義はブロックであり、対話的に入力された個々のコマンドもブロックです。スクリプトファイル (インタープリタに標準入力として与えられたり、インタープリタにコマンドライン引数として与えられたファイル) もコードブロックです。スクリプトコマンド (インタープリタのコマンドライン上で -c オプションで指定されたコマンド) もコードブロックです。引数 -m を使用して、コマンドラインからトップレベルスクリプト(すなわちモジュール __main__ )として実行されるモジュールもまたコードブロックです。組み込み関数 eval() や exec() に渡された文字列引数もコードブロックです。

コードブロックは、実行フレーム (execution frame) 上で実行されます。実行フレームには、 (デバッグに使われる) 管理情報が収められています。また、現在のコードブロックの実行が完了した際に、どのようにプログラムの実行を継続するかを決定しています。

4.2. 名前づけと束縛 (naming and binding)

4.2.1. 名前の束縛

名前 (name) は、オブジェクトを参照します。名前を導入するには、名前への束縛 (name binding) 操作を行います。

以下の構文が名前を束縛します:

formal parameters to functions,

クラス定義,

関数定義,

代入式,

targets that are identifiers if occurring in an assignment:

for loop header,

after as in a with statement, except clause, except* clause, or in the as-pattern in structural pattern matching,

in a capture pattern in structural pattern matching

import 文.

type statements.

type parameter lists.

The import statement of the form 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.

del 文で指定される対象は、(del の意味付けは、実際は名前の解放 (unbind) ですが) 文の目的上、束縛済みのものとみなされます。

代入文や import 文はいずれも、クラスや関数定義、モジュールレベル (トップレベルのコードブロック) 内で起こります。

ある名前がブロック内で束縛されているなら、 nonlocal や global として宣言されていない限り、それはそのブロックのローカル変数 (local variable) です。ある名前がモジュールレベルで束縛されているなら、その名前はグローバル変数 (global variable) です。 (モジュールコードブロックの変数は、ローカル変数でも、グローバル変数でもあります。) ある変数があるコードブロック内で使われていて、そのブロックで定義はされていないなら、それは自由変数 (free variable) です。

プログラムテキスト中に名前が出現するたびに、その名前が使われている最も内側の関数ブロック中で作成された 束縛 (binding) を使って名前の参照が行われます。

4.2.2. 名前解決

スコープ (scope) は、ブロック内の名前の可視性を決めます。ローカル変数があるブロック内で定義されている場合、変数のスコープはそのブロックを含みます。関数ブロック内で名前の定義を行った場合、その中のブロックが名前に別の束縛を行わない限り、定義ブロック内の全てのブロックを含むようにスコープが拡張されます。

ある名前がコードブロック内で使われると、その名前を最も近傍から囲うようなスコープ (最内スコープ: nearest enclosing scope) を使って束縛の解決を行います。こうしたスコープからなる、あるコードブロック内で参照できるスコープ全ての集合は、ブロックの環境(environment)と呼ばれます。

名前が全く見付からなかったときは、 NameError 例外が送出されます。現在のスコープが関数のもので、名前が使われる場所でローカル変数がまだ値に束縛されていない場合、 UnboundLocalError 例外が送出されます。 UnboundLocalError は NameError の子クラスです。

ある名前がコードブロック内のどこかで束縛操作されていたら、そのブロック内で使われるその名前はすべて、現在のブロックへの参照として扱われます。このため、ある名前がそのブロック内で束縛される前に使われるとエラーにつながります。この規則は敏感です。Python には宣言がなく、コードブロックのどこでも名前束縛操作ができます。あるコードブロックにおけるローカル変数は、ブロックのテキスト全体から名前束縛操作を走査することで決定されます。例は UnboundLocalError についての FAQ 項目 を参照してください。

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

global 文は、同じブロックの束縛操作と同じスコープを持ちます。ある自由変数の最内スコープに global 文がある場合、その自由変数はグローバル変数とみなされます。

The nonlocal statement causes corresponding names to refer to previously bound variables in the nearest enclosing function scope. SyntaxError is raised at compile time if the given name does not exist in any enclosing function scope. Type parameters cannot be rebound with the nonlocal statement.

あるモジュールの名前空間は、そのモジュールが最初に import された時に自動的に作成されます。スクリプトの主モジュール (main module) は常に __main__ と呼ばれます。

Class definition blocks and arguments to exec() and 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 annotation scopes, which have access to their enclosing class scopes. This means that the following will fail:

class A:
    a = 42
    b = list(a + i for i in range(10))

However, the following will succeed:

class A:
    type Alias = Nested
    class Nested: pass

print(A.Alias.__value__)  # <type 'A.Nested'>

4.2.3. Annotation scopes

Type parameter lists and type statements introduce annotation scopes, which behave mostly like function scopes, but with some exceptions discussed below. Annotations currently do not use annotation scopes, but they are expected to use annotation scopes in Python 3.13 when PEP 649 [https://peps.python.org/pep-0649/] is implemented.

Annotation scopes are used in the following contexts:

Type parameter lists for generic type aliases.

Type parameter lists for generic functions. A generic function's annotations are executed within the annotation scope, but its defaults and decorators are not.

Type parameter lists for generic classes. A generic class's base classes and keyword arguments are executed within the annotation scope, but its decorators are not.

The bounds and constraints for type variables (lazily evaluated).

The value of type aliases (lazily evaluated).

Annotation scopes differ from function scopes in the following ways:

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.

Expressions in annotation scopes cannot contain yield, yield from, await, or := expressions. (These expressions are allowed in other scopes contained within the annotation scope.)

Names defined in annotation scopes cannot be rebound with 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.

While annotation scopes have an internal name, that name is not reflected in the __qualname__ of objects defined within the scope. Instead, the __qualname__ of such objects is as if the object were defined in the enclosing scope.

Added in version 3.12: Annotation scopes were introduced in Python 3.12 as part of PEP 695 [https://peps.python.org/pep-0695/].

4.2.4. Lazy evaluation

The values of type aliases created through the type statement are lazily evaluated. The same applies to the bounds and constraints of type variables created through the type parameter syntax. This means that they are not evaluated when the type alias or type variable is created. Instead, they are only evaluated when doing so is necessary to resolve an attribute access.

例:

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

Here the exception is raised only when the __value__ attribute of the type alias or the __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:

from typing import Literal

type SimpleExpr = int | Parenthesized
type Parenthesized = tuple[Literal["("], Expr, Literal[")"]]
type Expr = SimpleExpr | tuple[SimpleExpr, Literal["+", "-"], Expr]

Lazily evaluated values are evaluated in 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.

Added in version 3.12.

4.2.5. 組み込みと制限付きの実行

CPython 実装の詳細: ユーザは __builtins__ に触れるべきではありません; これは厳密に実装の詳細です。組み込みの名前空間の中の値をオーバーライドしたいユーザは、 builtins モジュールを import して、その属性を適切に変更するべきです。

あるコードブロックの実行に関連する組み込み名前空間は、実際にはコードブロックのグローバル名前空間から名前 __builtins__ を検索することで見つかります; __builtins__ は辞書かモジュールでなければなりません (後者の場合はモジュールの辞書が使われます)。デフォルトでは、 __main__ モジュール中においては、 __builtins__ は組み込みモジュール builtins です; それ以外の任意のモジュールにおいては、 __builtins__ は builtins モジュール自身の辞書のエイリアスです。

4.2.6. 動的な機能とのやりとり

自由変数の名前解決はコンパイル時でなく実行時に行われます。つまり、以下のコードは42を出力します:

i = 10
def f():
    print(i)
i = 42
f()

eval() と exec() 関数は、名前の解決に、現在の環境の全てを使えるわけではありません。名前は呼び出し側のローカルやグローバル名前空間で解決できます。自由変数は最内名前空間ではなく、グローバル名前空間から解決されます。 [1] exec() と eval() 関数にはオプションの引数があり、グローバルとローカル名前空間をオーバライドできます。名前空間が一つしか指定されなければ、両方の名前空間として使われます。

4.3. 例外

例外とは、コードブロックの通常の制御フローを中断して、エラーやその他の例外的な状況を処理できるようにするための手段です。例外はエラーが検出された時点で 送出 (raise) されます; 例外は、エラーが発生部の周辺のコードブロックか、エラーが発生したコードブロック直接または間接的に呼び出しているコードブロックで 処理 (handle) することができます。

Python インタプリタは、ランタイムエラー (ゼロ除算など) が検出されると例外を送出します。Python プログラムから、 raise 文を使って明示的に例外を送出することもできます。例外ハンドラ (exception handler) は、 try ... except 文で指定することができます。 try 文の finally 節を使うとクリーンアップコード (cleanup code) を指定できます。このコードは例外は処理しませんが、先行するコードブロックで例外が起きても起きなくても実行されます。

Python は、エラー処理に "プログラムの終了 (termination)" モデルを用いています: 例外ハンドラは、プログラムに何が発生したかを把握することができ、ハンドラの外側のレベルに処理を継続することはできますが、(問題のあったコード部分を最初から実行しなおすのでない限り) エラーの原因を修復したり、実行に失敗した操作をやり直すことはできません。

例外が全く処理されないとき、インタプリタはプログラムの実行を終了させるか、対話メインループに処理を戻します。どちらの場合も、例外が SystemExit でなければ、スタックのトレースバックを出力します。

例外は、クラスインスタンスによって識別されます。 except 節はインスタンスのクラスにもとづいて選択されます: これはインスタンスのクラスか、その 非仮想基底クラス を参照します。このインスタンスはハンドラによって受け取られ、例外条件に関する追加情報を伝えることができます。

注釈

例外のメッセージは、Python API 仕様には含まれていません。メッセージの内容は、ある Python のバージョンと次のバージョンの間で警告なしに変更される可能性があるので、複数バージョンのインタプリタで動作するようなコードは、例外メッセージの内容に依存させるべきではありません。

try 文については、 try 文 節、 raise 文については raise 文 節も参照してください。

脚注

[1]

この制限は、上記の操作によって実行されるコードが、モジュールをコンパイルしたときには利用できないために起こります。

5. インポートシステム

ある 1 つの module にある Python コードから他のモジュールを インポート することで、そこにあるコードへアクセスできるようになります。 import 文はインポート機構を動かす最も一般的な方法ですが、それが唯一の方法ではありません。 importlib.import_module() や組み込みの __import__() といった関数を使っても、インポート機構を動かすことができます。

import 文は 2 つの処理を連続して行っています; ある名前のモジュールを探し、その検索結果をローカルスコープの名前に束縛します。 import 文の検索処理は、適切な引数で __import__() 関数を呼び出すこととして定義されています。 __import__() の戻り値は import 文の名前束縛処理の実行で使われます。名前束縛処理の厳密な詳細は import 文を参照してください。

__import__() を直接呼び出すとモジュールの検索のみが行われ、見つかった場合、モジュールの作成処理が行われます。親パッケージのインポートや (sys.modules を含む) 様々なキャッシュの更新などの副作用は起きるかもしれませんが、 import 文のみが名前束縛処理を行います。

import 文が実行されるときには、標準の組み込み関数 __import__() が呼ばれます。インポートシステムを呼び出すその他の (importlib.import_module() 関数のような) メカニズムは、__import__() の呼び出しをバイパスして独自のインポート・セマンティクスを実装している可能性があります。

モジュールが初めてインポートされるとき、 Python はそのモジュールを検索し、見付かった場合、モジュールオブジェクトを作成し、初期化します [1] 。その名前のモジュールが見付からなかった場合、 ModuleNotFoundError が送出されます。 Python には、インポート機構が実行されたときに名前からモジュールを検索する様々な戦略が実装されています。これらの戦略は、これ以降の節で解説される様々なフックを使って、修正したり拡張したりできます。

バージョン 3.3 で変更: インポートシステムが PEP 302 [https://peps.python.org/pep-0302/] の第 2 フェーズの完全な実装へ更新されました。もはや暗黙的なインポート機構はありません - インポート機構全体は sys.meta_path を通して公開されています。加えて、ネイティブの名前空間パッケージのサポートは実装されています (PEP 420 [https://peps.python.org/pep-0420/] を参照) 。

5.1. importlib

importlib モジュールはインポート機構とやり取りするための便利な API を提供します。例えば importlib.import_module() は、インポート機構を実行するための組み込みの __import__() よりもシンプルで推奨される API を提供します。より詳細なことは importlib ライブラリのドキュメントを参照してください。

5.2. パッケージ

Python にはモジュールオブジェクトの種類は 1 種類しかなく、 Python 、 C 、それ以外のもののどれで実装されているかに関係なく、すべてのモジュールはこの種類になります。モジュールの組織化を助け、名前階層を提供するために、 Python には パッケージ という概念があります。

パッケージはファイルシステムのディレクトリ、モジュールはディレクトリにあるファイルと考えることができますが、パッケージやモジュールはファイルシステムから生まれる必要はないので、この比喩を額面通りに受け取ってはいけません。この文書の目的のために、ディレクトリとファイルという便利な比喩を使うことにします。ファイルシステムのディレクトリのように、パッケージは階層構造を成し、通常のモジュールだけでなく、サブパッケージを含むこともあります。

すべてのパッケージはモジュールですが、すべてのモジュールがパッケージとは限らないことを心に留めておくのが重要です。もしくは他の言い方をすると、パッケージは単なる特別な種類のモジュールであると言えます。特に、__path__ 属性を持つ任意のモジュールはパッケージと見なされます。

すべてのモジュールは名前を持ちます。Python の属性アクセスの文法と同様に、サブパッケージの名前は親パッケージ名とドット記号で区切られます。したがって、email という名前のパッケージや、それが含む email.mime という名前のサブパッケージ、さらにそれに含まれる email.mime.text と言う名前のモジュールを考えることができます。

5.2.1. 通常のパッケージ

Python では、 通常のパッケージ と 名前空間パッケージ の 2 種類のパッケージが定義されています。通常のパッケージは Python 3.2 以前から存在する伝統的なパッケージです。典型的な通常のパッケージは __init__.py ファイルを含むディレクトリとして実装されます。通常のパッケージがインポートされたとき、この __init__.py ファイルが暗黙的に実行され、それで定義しているオブジェクトがパッケージ名前空間にある名前に束縛されます。 __init__.py ファイルは、他のモジュールに書ける Python コードと同じものを含むことができ、モジュールがインポートされたときに Python はモジュールに属性を追加したりします。

例えば、以下のようなファイルシステム配置は、3 つのサブパッケージを持つ最上位の parent パッケージを定義します:

parent/
    __init__.py
    one/
        __init__.py
    two/
        __init__.py
    three/
        __init__.py

parent.one をインポートすると暗黙的に parent/__init__.py と parent/one/__init__.py が実行されます。その後に parent.two もしくは parent.three をインポートすると、それぞれ parent/two/__init__.py や parent/three/__init__.py が実行されます。

5.2.2. 名前空間パッケージ

名前空間パッケージは様々な ポーション を寄せ集めたもので、それぞれのポーションはサブパッケージを親パッケージに提供します。ポーションはファイルシステムの別々の場所にあることもあります。ポーションは、 zip ファイルの中やネットワーク上や、それ以外のインポート時に Python が探すどこかの場所で見つかることもあります。名前空間パッケージはファイルシステム上のオブジェクトに対応することもあるし、そうでないこともあります; それらは実際の実体のない仮想モジュールです。

名前空間パッケージは、 __path__ 属性に普通のリストは使いません。その代わりに独自の iterable 型を使っていて、ポーションの親パッケージのパス (もしくは最上位パッケージのための sys.path) が変わった場合、そのパッケージでの次のインポートの際に、新たに自動でパッケージポーションを検索します。

名前空間パッケージには parent/__init__.py ファイルはありません。それどころか、異なるポーションがそれぞれ提供する複数の parent ディレクトリがインポート検索の際に見つかることもあります。したがって parent/one は物理的に parent/two の隣りにあるとは限りません。その場合、そのパッケージかサブパッケージのうち 1 つがインポートされたとき、Python は最上位の parent パッケージのための名前空間パッケージを作成します。

名前空間パッケージの仕様については PEP 420 [https://peps.python.org/pep-0420/] も参照してください。

5.3. 検索

検索を始めるためには、 Python はインポートされるモジュール (もしくはパッケージですが、ここでの議論の目的においてはささいな違いです) の 完全修飾 名を必要とします。この名前は、 import 文の様々な引数や importlib.import_module() および __import__() 関数のパラメータから得られます。

この名前はインポート検索の様々なフェーズで使われ、これは例えば foo.bar.baz のようなドットで区切られたサブモジュールへのパスだったりします。この場合、 Python は最初に foo を、次に foo.bar 、そして最後に foo.bar.baz をインポートしようとします。中間のいずれかのインポートに失敗した場合は、 ModuleNotFoundError が送出されます。

5.3.1. モジュールキャッシュ

インポート検索で最初に調べる場所は sys.modules です。このマッピングは、中間のパスを含む、これまでにインポートされたすべてのモジュールのキャッシュを提供します。なので foo.bar.baz がインポート済みの場合、 sys.modules は foo 、 foo.bar 、 foo.bar.baz のエントリーを含みます。それぞれのキーはその値として対応するモジュールオブジェクトを持ちます。

インポートではモジュール名は sys.modules から探され、存在した場合は、対応する値がインポートされるべきモジュールであり、この処理は完了します。しかし値が None だった場合、 ModuleNotFoundError が送出されます。モジュール名が見付からなかった場合は、 Python はモジュールの検索を続けます。

sys.modules は書き込み可能です。キーの削除は対応するモジュールを破壊しない (他のモジュールがそのモジュールへの参照を持っている) かもしれませんが、指定されたモジュールのキャッシュされたエントリーを無効にし、それが次にインポートされたとき Python にそのモジュールを改めて検索させることになります。キーを None に対応付けることもできますが、次にそのモジュールがインポートされるときに ModuleNotFoundError となってしまいます。

たとえモジュールオブジェクトへの参照を保持しておいて、 sys.modules にキャッシュされたエントリーを無効にし、その指定したモジュールを再インポートしたとしても、 2 つのモジュールオブジェクトは同じでは ない ことに注意してください。それとは対照的に、 importlib.reload() は 同じ モジュールオブジェクトを再利用し、モジュールのコードを再実行することで単にモジュールの内容を再初期化するだけです。

5.3.2. ファインダーとローダー

sys.modules に指定されたモジュールが見つからなかった場合は、 Python のインポートプロトコルが起動され、モジュールを見つけロードします。このプロトコルは 2 つの概念的なオブジェクト、 ファインダー と ローダー から成ります。ファインダーの仕事は、知っている戦略を使って指定されたモジュールを見つけられるかどうか判断することです。両方のインターフェースを実装しているオブジェクトは インポーター と呼ばれます - インポーターは要求されたモジュールがロードできると分かったとき、自分自身を返します。

Python にはデフォルトのファインダーとインポーターがいくつかあります。 1 つ目のものは組み込みモジュールの見つけ方を知っていて、 2 つ目のものは凍結されたモジュール (訳注: freeze ツールで処理されたモジュールのこと。 プログラミング FAQ の「どうしたら Python スクリプトからスタンドアロンバイナリを作れますか？」の項目を参照) の見つけ方を知っています。 3 つ目のものは インポートパス からモジュールを探します。 インポートパス はファイルシステムのパスや zip ファイルの位置を示すリストです。このリストは、 URL で特定できるもののような、位置を示すことのできる任意のリソースの検索にまで拡張することもできます。

インポート機構は拡張可能なので、モジュール検索の範囲とスコープを拡張するために新しいファインダーを付け加えることができます。

ファインダーは実際にはモジュールをロードしません。指定されたモジュールが見つかった場合、ファインダーは module spec (モジュール仕様)、すなわちモジュールのインポート関連の情報をカプセル化したものを返します。モジュールのロード時にインポート機構はそれを利用します。

次の節では、インポート機構を拡張するための新しいファインダーやローダーの作成と登録を含め、ファインダーとローダーのプロトコルについてより詳しく解説します。

バージョン 3.4 で変更: Python の以前のバージョンでは、ファインダーは直接 ローダー を返していましたが、現在はローダーを 含む モジュール仕様を返します。ローダーはインポート中はまだ使われていますが、責任は減りました。

5.3.3. インポートフック

インポート機構は拡張可能なように設計されています; その主となる仕組みは インポートフック です。インポートフックには 2 種類あります: メタフック と インポートパスフック です。

メタフックはインポート処理の最初、 sys.modules キャッシュの検索以外のインポート処理より前に呼び出されます。これにより、 sys.path の処理や凍結されたモジュールや組み込みのモジュールでさえも、メタフックで上書きすることができます。メタフックは以下で解説するように、 sys.meta_path に新しいファインダーオブジェクトを追加することで登録されます。

インポートパスフックは、 sys.path (もしくは package.__path__) の処理の一部として、対応するパス要素を取り扱うところで呼び出されます。インポートパスフックは以下で解説するように、新しい呼び出し可能オブジェクトを sys.path_hooks に追加することで登録されます。

5.3.4. メタパス

指定されたモジュールが sys.modules に見つからなかったとき、 Python は次にメタパス・ファインダー・オブジェクトが格納されている sys.meta_path を検索します。指定されたモジュールを扱うことができるかどうかを調べるために、各ファインダーに問い合わせを行います。メタパス・ファインダーには、名前とインポートパスと (オプションの) ターゲットモジュールの 3 つの引数を取る find_spec() という名前のメソッドが実装されていなければいけません。メタパス・ファインダーでは、指定されたモジュールを扱えるかどうかを判定するための戦略は任意のものを使って構いません。

meta path finder が指定されたモジュールの扱い方を知っている場合は、ファインダは spec オブジェクトを返します。指定されたモジュールを扱えない場合は None を返します。 sys.meta_path に対する処理が spec を返さずにリストの末尾に到達してしまった場合は、 ModuleNotFoundError を送出します。その他の送出された例外はそのまま呼び出し元に伝播され、インポート処理を異常終了させます。

メタパス・ファインダーの find_spec() メソッドは 2 つまたは 3 つの引数を渡して呼び出します。1 つ目の引数はインポートされるモジュールの完全修飾名で、例えば foo.bar.baz などです。2 つ目の引数はモジュールの検索で使われるパスです。最上位のモジュールでは 2 つ目の引数は None にしますが、サブモジュールやサブパッケージでは 2 つ目の引数は親パッケージの __path__ 属性の値です。適切な __path__ 属性にアクセスできなかった場合は、 ModuleNotFoundError が送出されます。3 つ目の引数は、あとでロードされるターゲットとなる既存のモジュールオブジェクトです。インポートシステムはリロードの間だけターゲットモジュール をセットします。

メタパスは、1 回のインポート要求で複数回走査される可能性があります。例えば、関係するモジュールがどれもまだキャッシュされていないとしたときに foo.bar.baz をインポートすると、最初は各メタパス・ファインダー (mpf) に対して mpf.find_spec("foo", None, None) を呼び出して、最上位のインポート処理を行います。foo がインポートされた後に、mpf.find_spec("foo.bar", foo.__path__, None) を呼び出していく 2 回目のメタパスの走査が行われ、foo.bar がインポートされます。foo.bar のインポートまで行われたら、最後の走査で mpf.find_spec("foo.bar.baz", foo.bar.__path__, None) を呼び出していきます。

あるメタパス・ファインダーは最上位のインポートのみサポートしています。これらのインポーターは、2 つ目の引数に None 以外のものが渡されたとき、常に None を返します。

Python のデフォルトの sys.meta_path は 3 つのパスファインダーを持っています。組み込みモジュールのインポートの方法を知っているもの、凍結されたモジュールのインポートの方法を知っているもの、 インポートパス からのモジュールのインポートの方法を知っているもの (つまり パスベース・ファインダー) があります。

バージョン 3.4 で変更: The find_spec() method of meta path finders replaced find_module(), which is now deprecated. While it will continue to work without change, the import machinery will try it only if the finder does not implement find_spec().

バージョン 3.10 で変更: Use of find_module() by the import system now raises ImportWarning.

バージョン 3.12 で変更: find_module() has been removed. Use find_spec() instead.

5.4. ロード

モジュール仕様が見つかった場合、インポート機構はモジュールをロードする時にそれ (およびそれに含まれるローダー) を使います。これは、インポートのロード部分で起こることの近似です:

module = None
if spec.loader is not None and hasattr(spec.loader, 'create_module'):
    # It is assumed 'exec_module' will also be defined on the loader.
    module = spec.loader.create_module(spec)
if module is None:
    module = ModuleType(spec.name)
# The import-related module attributes get set here:
_init_module_attrs(spec, module)

if spec.loader is None:
    # unsupported
    raise ImportError
if spec.origin is None and spec.submodule_search_locations is not None:
    # namespace package
    sys.modules[spec.name] = module
elif not hasattr(spec.loader, 'exec_module'):
    module = spec.loader.load_module(spec.name)
else:
    sys.modules[spec.name] = module
    try:
        spec.loader.exec_module(module)
    except BaseException:
        try:
            del sys.modules[spec.name]
        except KeyError:
            pass
        raise
return sys.modules[spec.name]

以下の詳細に注意してください:

sys.modules の中に与えられた名前を持つ既存のモジュールオブジェクトがあるなら、 import は既にそれを返しているでしょう。

モジュールは、ローダーがモジュールコードを実行する前に sys.modules に存在しています。 モジュールコードが (直接的または間接的に) 自分自身をインポートする可能性があるので、これは重要です; モジュールを sys.modules に追加することで、最悪のケースでは無限の再帰が、そして最良のケースでは複数回のロードが、前もって防止されます。

ロード処理に失敗した場合、その失敗したモジュールは -- そして、そのモジュールだけが -- sys.modules から取り除かれます。 sys.modules キャッシュに既に含まれていたすべてのモジュールと、副作用としてロードに成功したすべてのモジュールは、常にキャッシュに残されます。これはリロードとは対照的で、リロードの場合は失敗したモジュールも sys.modules に残されます。

後のセクション で要約されるように、モジュールが作られてから実行されるまでの間にインポート機構はインポート関連のモジュール属性を設定します (上記擬似コード例の "_init_module_attrs")。

モジュール実行はモジュールの名前空間が構築されるロードの重要な瞬間です。実行はローダーに完全に委任され、ローダーは何をどのように構築するかを決定することになります。

ロードの間に作成されて exec_module() に渡されたモジュールは、インポートの終わりに返されるものとは異なるかもしれません [2]。

バージョン 3.4 で変更: インポートシステムはローダーの定型的な責任を引き継ぎました。これらは以前は importlib.abc.Loader.load_module() メソッドによって実行されました。

5.4.1. ローダー

モジュールローダーは、ロードの重要な機能であるモジュール実行機能を提供します。インポート機構は、実行しようとするモジュールオブジェクトを単一の引数として importlib.abc.Loader.exec_module() メソッドを呼び出します。 importlib.abc.Loader.exec_module() から返された任意の値は無視されます。

ローダーは以下の仕様を満たしていなければいけません:

モジュールが (組み込みモジュールや動的に読み込まれる拡張モジュールではなくて) Python モジュールだった場合、ローダーはモジュールのグローバル名前空間 (module.__dict__) で、モジュールのコードを実行すべきです。

exec_module() の呼び出し中に ImportError 以外の例外が送出され、伝播されてきたとしても、モジュールをロードできない場合は ImportError を送出すべきです。

多くの場合、ファインダーとローダーは同じオブジェクトで構いません; そのような場合では find_spec() メソッドは単に self (訳注: オブジェクト自身) を返すだけです。

モジュールローダーは、 create_module() メソッドを実装することでロード中にモジュールオブジェクトを作成することを選択できます。このメソッドは、モジュール仕様を引数に取って、ロード中に使う新しいモジュールオブジェクトを返します。 create_module() はモジュールオブジェクトに属性を設定する必要はありません。もしこのメソッドが None を返すなら、インポート機構は新しいモジュールを自身で作成します。

Added in version 3.4: ローダーの create_module() メソッド。

バージョン 3.4 で変更: load_module() メソッドは exec_module() によって置き換えられ、インポート機構がロードのすべての定型的な処理を引き受けました。

既存のローダーとの互換性のため、もしローダーに load_module() メソッドが存在し、かつローダーが exec_module() を実装していなければ、インポート機構はローダーの load_module() メソッドを使います。しかし、 load_module() は deprecated であり、ローダーは代わりに exec_module() を実装すべきです。

load_module() メソッドは、モジュールを実行することに加えて上記で説明されたすべての定型的なロード機能を実施しなければなりません。同じ制約が適用されます。以下は追加の明確化です:

sys.modules に与えられた名前のモジュールが存在している場合、ローダーはその既存のモジュールを使わなければいけません。 (そうしないと importlib.reload() は正しく動かないでしょう。) 指定されたモジュールが sys.modules に存在しない場合、ローダーは新しいモジュールオブジェクトを作成し、 sys.modules に追加しなければいけません。

無限の再帰または複数回のロードを防止するために、ローダーがモジュールコードを実行する前にモジュールは sys.modules に存在しなければなりません (must)。

ロード処理に失敗した場合、ローダーは sys.modules に追加したモジュールを取り除かなければいけませんが、それはロードに失敗したモジュール のみ を、そのモジュールがローダー自身に明示的にロードされた場合に限り、除去しなければなりません。

バージョン 3.5 で変更: exec_module() が定義されていて create_module() が定義されていない場合、 DeprecationWarning が送出されるようになりました。

バージョン 3.6 で変更: exec_module() が定義されていて create_module() が定義されていない場合、 ImportError が送出されるようになりました。

バージョン 3.10 で変更: load_module() を使用すると ImportWarning が発生します。

5.4.2. サブモジュール

サブモジュールをロードするのにどのようなメカニズム (例えば、 importlib API 、 import または import-from ステートメント、またはビルトイン関数の __import__) が使われた場合でも、バインディングはサブモジュールオブジェクトを親モジュールの名前空間に配置します。例えば、もしパッケージ spam がサブモジュール foo を持っていた場合、 spam.foo をインポートした後は spam は値がサブモジュールに束縛された属性 foo を持ちます。以下のディレクトリ構造を持っているとしましょう:

spam/
    __init__.py
    foo.py

そして spam/__init__.py は以下のようになっているとします:

from .foo import Foo

このとき、以下を実行することにより spam モジュールの中に foo と Foo に束縛された名前が置かれます:

>>> import spam
>>> spam.foo
<module 'spam.foo' from '/tmp/imports/spam/foo.py'>
>>> spam.Foo
<class 'spam.foo.Foo'>

Python の慣れ親しんだ名前束縛ルールからするとこれは驚きかもしれませんが、それは実際インポートシステムの基本的な機能です。不変に保たなければならないのは (上記のインポートの後などで) sys.modules['spam'] と sys.modules['spam.foo'] が存在する場合、後者が前者の foo 属性として存在しなければならないということです。

5.4.3. モジュール仕様

インポート機構は、インポートの間 (特にロードの前) に、個々のモジュールについてのさまざまな情報を扱います。情報のほとんどはすべてのモジュールで共通です。モジュール仕様の目的は、このインポート関連の情報をモジュールの単位でカプセル化することです。

インポートの際にモジュール仕様を使うことは、インポートシステムコンポーネント間、例えばモジュール仕様を作成するファインダーとそれを実行するローダーの間で状態を転送することを可能にします。最も重要なのは、それによってインポート機構がロードの定型的な作業を実行できるようになるということです。これに対して、モジュール仕様なしではローダがその責任を担っていました。

モジュール仕様は、モジュールオブジェクトの __spec__ 属性として公開されます。モジュール仕様の内容の詳細については ModuleSpec を参照してください。

Added in version 3.4.

5.4.4. インポート関連のモジュール属性

インポート機構はロードの間、モジュールの仕様に基づいて、ローダーがモジュールが実行する前に以下の属性を書き込みます。

It is strongly recommended that you rely on __spec__ and its attributes instead of any of the other individual attributes listed below.

__name__

__name__ 属性はモジュールの完全修飾名に設定されなければなりません。この名前を利用してインポートシステムでモジュールを一意に識別します。

__loader__

__loader__ 属性はモジュールロード時にインポート機構が使用したローダーオブジェクトに設定されなければなりません。この属性は普通は内省用のものですが、ローダー固有の追加機能のために用いることが出来ます。例えばローダー関連のデータの取得です。

It is strongly recommended that you rely on __spec__ instead of this attribute.

バージョン 3.12 で変更: The value of __loader__ is expected to be the same as __spec__.loader. The use of __loader__ is deprecated and slated for removal in Python 3.14.

__package__

The module's __package__ attribute may be set. Its value must be a string, but it can be the same value as its __name__. When the module is a package, its __package__ value should be set to its __name__. When the module is not a package, __package__ should be set to the empty string for top-level modules, or for submodules, to the parent package's name. See PEP 366 [https://peps.python.org/pep-0366/] for further details.

この属性は PEP 366 [https://peps.python.org/pep-0366/] で定義されているように、メインモジュールからの明示的な相対インポートを計算するために、 __name__ の代わりに使用されます。

It is strongly recommended that you rely on __spec__ instead of this attribute.

バージョン 3.6 で変更: __package__ の値が __spec__.parent と同じ値を持つことを要求されるようになりました。

バージョン 3.10 で変更: ImportWarning is raised if import falls back to __package__ instead of parent.

バージョン 3.12 で変更: Raise DeprecationWarning instead of ImportWarning when falling back to __package__.

__spec__

__spec__ 属性はモジュールロード時に使用されたモジュールスペックに設定されなければなりません。 __spec__ を適切に設定すると インタープリタ起動中に初期化されるモジュール にも同様に適用されます。例外は __main__ で、__spec__ は 場合によっては None に設定されます。

When __spec__.parent is not set, __package__ is used as a fallback.

Added in version 3.4.

バージョン 3.6 で変更: __package__ が定義されていないときに __spec__.parent がフォールバックとして使われるようになりました。

__path__

モジュールが (通常のまたは名前空間) パッケージの場合、モジュールオブジェクトの __path__ 属性が設定される必要があります。値はイテレート可能でなければなりませんが、__path__ に意味がない場合は空でも構いません。__path__ が空でない場合、イテレート時に文字列を生成しなければなりません。__path__ のセマンティクスの詳細は 下記 の通りです。

パッケージでないモジュールは __path__ 属性を持ってはいけません。

__file__

__cached__

__file__ is optional (if set, value must be a string). It 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 import system may opt to leave it unset if it has no semantic meaning (e.g. a module loaded from a database).

もし __file__ を設定するなら、 __cached__ 属性もコードのコンパイルされたバージョンのどれか (例えば、バイトコンパイルされたファイル) へのパスに設定できます。この属性を設定するにあたってファイルが存在する必要はありません; パスは、単にコンパイルされたファイルが存在するかもしれない場所を示しているだけです (PEP 3147 [https://peps.python.org/pep-3147/] を参照)。

__file__ が設定されていないときにも __cached__ は設定できることに注意してください。ただし、そのシナリオはかなり変則的です。究極的には、ローダーとは (__file__ と __cached__ の由来である) ファインダーが提供するモジュール仕様を利用するものです。したがって、もしローダーがキャッシュされたモジュールからロードする一方でファイルからはロードしないなら、その変則的なシナリオは適切でしょう。

It is strongly recommended that you rely on __spec__ instead of __cached__.

5.4.5. module.__path__

定義より、モジュールに __path__ 属性があれば、そのモジュールはパッケージとなります。

パッケージの __path__ 属性は、そのサブパッケージのインポート中に使われます。インポート機構の内部では、それは sys.path とほとんど同じように機能します。つまり、インポート中にモジュールを探す場所のリストを提供します。しかし、一般的に __path__ は sys.path よりも制約が強いです。

__path__ は文字列の iterable でなければいけませんが、空でも構いません。 sys.path と同じ規則がパッケージの __path__ にも適用され、パッケージの __path__ を走査するときに (後で解説する) sys.path_hooks が考慮に入れられます。

パッケージの __init__.py ファイルは、パッケージの __path__ 属性を設定もしくは変更することがあり、これが PEP 420 [https://peps.python.org/pep-0420/] 以前の名前空間パッケージの典型的な実装方法でした。 PEP 420 [https://peps.python.org/pep-0420/] の採択により、もはや名前空間パッケージは、 __path__ を操作するコードだけを含む __init__.py ファイルを提供する必要がなくなりました;インポート機構は、名前空間パッケージに対し自動的に適切な __path__ をセットします。

5.4.6. モジュールの repr

デフォルトでは、すべてのモジュールは利用可能な repr を持っています。ただしこれは、これまでに説明した属性の設定内容に依存しており、モジュール仕様によってモジュールオブジェクトの repr をより明示的に制御することができます。

もしモジュールが仕様 (__spec__) を持っていれば、インポート機構はそこから repr を生成しようとします。もしそれが失敗するか、または仕様が存在しなければ、インポートシステムはモジュールで入手可能なあらゆる情報を使ってデフォルトの repr を構築します。それは module.__name__, module.__file__, module.__loader__ を (足りない情報についてはデフォルト値を使って補いながら) repr への入力として使おうと試みます。

これが使われている正確な規則です:

モジュールが __spec__ 属性を持っていれば、仕様に含まれる情報が repr を生成するために使われます。 "name", "loader", "origin", "has_location" 属性が参照されます。

モジュールに __file__ 属性がある場合は、モジュールの repr の一部として使われます。

モジュールに __file__ はないが __loader__ があり、その値が None ではない場合は、ローダーの repr がモジュールの repr の一部として使われます。

そうでなければ、単にモジュールの __name__ を repr の中で使います。

バージョン 3.12 で変更: Use of 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.

5.4.7. キャッシュされたバイトコードの無効化

Before Python loads cached bytecode from a .pyc file, it checks whether the cache is up-to-date with the source .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 .pyc files: checked and unchecked. For checked hash-based .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 .pyc files, Python simply assumes the cache file is valid if it exists. Hash-based .pyc files validation behavior may be overridden with the --check-hash-based-pycs flag.

バージョン 3.7 で変更: Added hash-based .pyc files. Previously, Python only supported timestamp-based invalidation of bytecode caches.

5.5. パスベース・ファインダー

上で触れた通り、 Python にはいくつかのデフォルトのメタパス・ファインダーが備わっています。そのうちの 1 つは パスベース・ファインダー (PathFinder) と呼ばれ、 パスエントリ のリストである インポートパス を検索します。それぞれのパスエントリは、モジュールを探す場所を指しています。

パスベース・ファインダー自体は何かのインポート方法を知っているわけではありません。その代わりに、個々のパスエントリを走査し、それぞれに特定の種類のパスの扱いを知っているパスエントリ・ファインダーを関連付けます。

デフォルトのパスエントリ・ファインダーは、ファイルシステム上のモジュールを見つけるためのすべてのセマンティクスを実装しています。それは Python ソースコード (.py ファイル) 、Python バイトコード (.pyc ファイル) 、共有ライブラリ (例えば .so ファイル) などの特別なファイルタイプを処理します。標準ライブラリの zipimport モジュールによってサポートされる場合は、デフォルトのパスエントリ・ファインダーは (共有ライブラリ以外の) すべてのファイルタイプの zip ファイルからのロードも扱います。

パスエントリはファイルシステム上の場所に限定される必要はありません。URL やデータベースクエリやその他文字列で指定できる場所を参照することも可能です。

パスベース・ファインダーにはフックやプロトコルを追加することができ、それによって検索可能なパスエントリの種類を拡張し、カスタマイズすることができます。例えば、ネットワーク上の URL をパスエントリとしてサポートしたい場合、 web 上のモジュールを見つけるために HTTP の取り扱い方を実装したフックを書くことができます。この (呼び出し可能オブジェクトである) フックは、下で解説するプロトコルをサポートする パスエントリ・ファインダー を返します。このプロトコルは web からモジュールのローダーを取得するのに使われます。

警告の言葉: この節と前の節の両方で ファインダー という言葉が、 メタパス・ファインダー と パスエントリ・ファインダー という用語で区別されて使われています。これら 2 種類のファインダーは非常に似ており、似たプロトコルをサポートし、インポート処理で同じように機能しますが、微妙に異なっているのを心に留めておくのは重要です。特に、メタパス・ファインダーはインポート処理の開始時、 sys.meta_path の走査が動くときに動作します。

それとは対照的に、パスエントリ・ファインダーはある意味でパスベース・ファインダーの実装詳細であり、実際 sys.meta_path からパスベース・ファインダーが取り除かれた場合、パスエントリ・ファインダーの実装は何も実行されないでしょう。

5.5.1. パスエントリ・ファインダー

パスベース・ファインダー には、文字列 パスエントリ で指定された場所の Python モジュールや Python パッケージを見つけ、ロードする責任があります。ほとんどのパスエントリはファイルシステム上の場所を指定していますが、そこに制限される必要はありません。

メタパス・ファインダーとして、 パスベース・ファインダー には前に解説した find_spec() プロトコルが実装されていますが、これに加えて インポートパス からモジュールを見つけ、ロードする方法をカスタマイズするために使えるフックを提供しています。

パスベース・ファインダー は sys.path 、 sys.path_hooks 、 sys.path_importer_cache という 3 つの変数を使います。さらにパッケージオブジェクトの __path__ 属性も使います。これらによって、インポート処理をカスタマイズする方法が提供されます。

sys.path contains a list of strings providing search locations for modules and packages. It is initialized from the PYTHONPATH environment variable and various other installation- and implementation-specific defaults. Entries in sys.path can name directories on the file system, zip files, and potentially other "locations" (see the site module) that should be searched for modules, such as URLs, or database queries. Only strings should be present on sys.path; all other data types are ignored.

パスベース・ファインダー は メタパス・ファインダー なので、インポート機構は、前で解説したパスベース・ファインダーの find_spec() メソッドを呼び出すことで インポートパス の検索を始めます。 path 引数が find_spec() に渡されたときは、それは走査するパス文字列のリスト - 典型的にはそのパッケージの中でインポートしているパッケージの __path__ 属性になります。 path 引数が None だった場合、それは最上位のインポートであることを示していて、 sys.path が使われます。

The path based finder iterates over every entry in the search path, and for each of these, looks for an appropriate path entry finder (PathEntryFinder) for the path entry. Because this can be an expensive operation (e.g. there may be 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 sys.path_importer_cache (despite the name, this cache actually stores finder objects rather than being limited to importer objects). In this way, the expensive search for a particular path entry location's path entry finder need only be done once. User code is free to remove cache entries from sys.path_importer_cache forcing the path based finder to perform the path entry search again.

path entry がキャッシュの中に無かった場合、 path based finder は sys.path_hooks の中の呼び出し可能オブジェクトを全て辿ります。このリストのそれぞれの path entry フック は、検索する path entry という引数 1 つを渡して呼び出されます。その呼び出し可能オブジェクトは path entry を扱える path entry finder を返すか、 ImportError を送出します。 ImportError は、フックが path entry のための path entry finder を探せないことを報せるために path based finder が使います。この例外は処理されず、 import path を辿っていく処理が続けられます。フックは引数として文字列またはバイト列オブジェクトを期待します; バイト列オブジェクトのエンコーディングはフックに任されていて (例えば、ファイルシステムのエンコーディングの UTF-8 やそれ以外などです) 、フックが引数をデコードできなかった場合は ImportError を送出すべきです。

sys.path_hooks を辿る処理が パスエントリ・ファインダー を何も返さずに終わった場合、パスベース・ファインダーの find_spec() メソッドは、 sys.path_importer_cache に (このパスエントリに対するファインダーが存在しないことを示すために) None を保存し、 メタパス・ファインダー はモジュールが見つからなかったことを伝えるために None を返します。

sys.path_hooks 上の パスエントリフック 呼び出し可能オブジェクトの戻り値のいずれかが パスエントリ・ファインダー であった 場合、後で出てくるモジュール仕様を探すためのプロトコルが使われ、それがモジュールをロードするために使われます。

（空の文字列によって表される）現在のディレクトリは、 sys.path の他のエントリとは多少異なる方法で処理されます。まず、現在のディレクトリが存在しないことが判明した場合、 sys.path_importer_cache には何も追加されません。次に、現在のディレクトリに対する値は個々のモジュールのルックアップで毎回新たに検索されます。 3番目に、 sys.path_importer_cache に使われ、 importlib.machinery.PathFinder.find_spec() が返すパスは、実際のディレクトリであって空の文字列ではありません。

5.5.2. パスエントリ・ファインダー・プロトコル

モジュールと初期化されたパッケージのインポートをサポートするため、および名前空間パッケージのポーションとして提供するために、パスエントリ・ファインダーは find_spec() メソッドを実装しなければいけません。

find_spec() は 2 つの引数を取ります。インポートしようとしているモジュールの完全修飾名と、 (オプションの) 対象モジュールです。 find_spec() はモジュールに対応する完全に初期化 (populated) された仕様を返します。この仕様は (1つの例外を除いて) 常に "loader" セットを持っています。

To indicate to the import machinery that the spec represents a namespace portion, the path entry finder sets submodule_search_locations to a list containing the portion.

バージョン 3.4 で変更: find_spec() replaced find_loader() and find_module(), both of which are now deprecated, but will be used if find_spec() is not defined.

古いパスエントリ・ファインダーの中には、 find_spec() の代わりにこれら 2 つの deperecated なメソッドのうちのいずれかを実装しているものがあるかもしれません。これらのメソッドは後方互換性のためにまだ考慮されています。しかし、パスエントリ・ファインダーに find_spec() が実装されていれば、古いメソッドは無視されます。

find_loader() takes one argument, the fully qualified name of the module being imported. find_loader() returns a 2-tuple where the first item is the loader and the second item is a namespace portion.

他のインポート機構の実装に対する後方互換性のために、多くのパスエントリ・ファインダーは、メタパス・ファインダーがサポートするのと同じ伝統的な find_module() メソッドもサポートしています。しかし、パスエントリ・ファインダーの find_module() メソッドは、決して path 引数では呼び出されません (このメソッドは、パスフックの最初の呼び出しから適切なパス情報を記録する動作が期待されています)。

パスエントリ・ファインダーの find_module() メソッドは deprecated です。なぜなら、その方法ではパスエントリ・ファインダーが名前空間パッケージに対してポーションを提供することができないからです。もし find_loader() と find_module() の両方がパスエントリ・ファインダーに存在したら、インポートシステムは常に find_module() よりも find_loader() を優先して呼び出します。

バージョン 3.10 で変更: Calls to find_module() and find_loader() by the import system will raise ImportWarning.

バージョン 3.12 で変更: find_module() and find_loader() have been removed.

5.6. 標準のインポートシステムを置き換える

インポートシステム全体を置き換えるための最も信頼性のある仕組みは、 sys.meta_path のデフォルトの内容を削除し、全部をカスタムのメタパスフックで置き換えるものです。

もし、 import 文の動作だけを変更し、インポートシステムにアクセスする他の API には影響を与えなくてもよければ、組み込みの __import__() 関数を置き換えるだけで十分です。この手法は、ある 1 つのモジュール内だけで import 文の動作を変更するのにも用いられます。

(標準のインポートシステム全体を停止するのではなく) すでにメタパスにいるフックからあるモジュールのインポートを選択的に防ぐためには、 find_spec() から None を返す代わりに、直接 ModuleNotFoundError を送出するだけで十分です。 None を返すのはメタパスの走査を続けるべきであることを意味しますが、例外を送出するとすぐに走査を打ち切ります。

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

package/
    __init__.py
    subpackage1/
        __init__.py
        moduleX.py
        moduleY.py
    subpackage2/
        __init__.py
        moduleZ.py
    moduleA.py

In either subpackage1/moduleX.py or subpackage1/__init__.py, the following are valid relative imports:

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

Absolute imports may use either the import <> or from <> import <> syntax, but relative imports may only use the second form; the reason for this is that:

import XXX.YYY.ZZZ

should expose XXX.YYY.ZZZ as a usable expression, but .moduleY is not a valid expression.

5.8. __main__ に対する特別な考慮

__main__ モジュールは、 Python のインポートシステムに関連する特別なケースです。 他の場所 で言及されているように、 __main__ モジュールは sys や builtins などと同様にインタプリタースタートアップで直接初期化されます。しかし、前者 2 つのモジュールと違って、 __main__ は厳密にはビルトインのモジュールとしての資格を持っていません。これは、 __main__ が初期化される方法がインタプリタが起動されるときのフラグやその他のオプションに依存するためです。

5.8.1. __main__.__spec__

__main__ がどのように初期化されるかに依存して、 __main__.__spec__ は適切に設定されることもあれば None になることもあります。

Python が -m オプションを付けて実行された場合には、 __spec__ は対応するモジュールまたはパッケージのモジュール仕様に設定されます。また、ディレクトリや zip ファイル、または他の sys.path エントリを実行する処理の一部として __main__ モジュールがロードされる場合にも __spec__ が生成 (populate) されます。

それ以外のケース では、 __main__.__spec__ は None に設定されます。これは、 __main__ を生成 (populate) するために使われたコードがインポート可能なモジュールと直接一致していないためです:

対話プロンプト

-c オプション

stdin から起動された場合

ソースファイルやバイトコードファイルから直接起動された場合

最後のケースでは、たとえ技術的にはファイルがモジュールとして直接インポートできた としても __main__.__spec__ は常に None になることに注意してください。もし __main__ において有効なモジュールメタデータが必要なら -m スイッチを使ってください。

__main__ がインポート可能なモジュールと一致し、 __main__.__spec__ がそれに応じて設定されていたとしても、それでもなお、この 2 つのモジュールは別物とみなされることに注意してください。これは、 if __name__ == "__main__": チェックによって保証されるブロックは、 __main__ 名前空間を生成 (populate) するためにモジュールが使用される時にだけ実行され、通常のインポート時には実行されない、という事実に起因しています。

5.9. 参考資料

Python の初期の頃からすると、インポート機構は目覚ましい発展を遂げました。一部細かいところがドキュメントが書かれたときから変わってはいますが、最初期の パッケージの仕様 [https://www.python.org/doc/essays/packages/] はまだ読むことができます。

オリジナルの sys.meta_path の仕様は PEP 302 [https://peps.python.org/pep-0302/] で、その後継となる拡張が PEP 420 [https://peps.python.org/pep-0420/] です。

PEP 420 [https://peps.python.org/pep-0420/] introduced namespace packages for Python 3.3. PEP 420 [https://peps.python.org/pep-0420/] also introduced the find_loader() protocol as an alternative to find_module().

PEP 366 [https://peps.python.org/pep-0366/] は、メインモジュールでの明示的な相対インポートのために追加した __package__ 属性の解説をしています。

PEP 328 [https://peps.python.org/pep-0328/] は絶対インポート、明示的な相対インポート、および、当初 __name__ で提案し、後に PEP 366 [https://peps.python.org/pep-0366/] が __package__ で定めた仕様を導入しました。

PEP 338 [https://peps.python.org/pep-0338/] はモジュールをスクリプトとして実行するときの仕様を定めています。

PEP 451 [https://peps.python.org/pep-0451/] は、モジュール仕様オブジェクトにおけるモジュール毎のインポート状態のカプセル化を追加しています。また、ローダーの定型的な責任のほとんどをインポート機構に肩代わりさせています。これらの変更により、インポートシステムのいくつかの API が deprecate され、またファインダーとローダーには新しいメソッドが追加されました。

脚注

[1]

types.ModuleType を参照してください。

[2]

importlib の実装は、戻り値を直接使うことは避けています。その代わりに、モジュール名を調べて sys.modules からモジュールオブジェクトを得ます。こうすることの間接的な効果は、インポートされたモジュールが sys.modules にいる自分自身を置き換えることがあるということです。これは実装依存の動作であり、他の Python 実装では保証されていない動作です。

6. 式 (expression)

この章では、Python の式における個々の要素の意味について解説します。

表記法に関する注意: この章と以降の章での拡張BNF (extended BNF) 表記は、字句解析規則ではなく、構文規則を記述するために用いられています。ある構文規則 (のある表現方法) が、以下の形式

name ::=  othername

で記述されていて、この構文特有の意味付け (semantics) が記述されていない場合、 name の形式をとる構文の意味付けは othername の意味付けと同じになります。

6.1. 算術変換 (arithmetic conversion)

以下の算術演算子の記述で、「数値引数は共通の型に変換されます」と書かれているとき、組み込み型に対する演算子の実装は以下の通りに動作します:

片方の引数が複素数型であれば、他方は複素数型に変換されます;

それ以外の場合で、片方の引数が浮動小数点数であれば、他方は浮動小数点型に変換されます;

それ以外場合は、両方の引数は整数でなければならず、変換の必要はありません。

特定の演算子 ('%' 演算子の左引数としての文字列) には、さらに別の規則が適用されます。拡張は、それ自身の型変換のふるまいを定義していなければなりません。

6.2. アトム、原子的要素 (atom)

atom は、式の一番基本的な要素です。もっとも単純な atom は、識別子またはリテラルです。丸括弧、角括弧、または波括弧で囲われた形式 (form) もまた、構文上アトムに分類されます。atom の構文は以下のようになります:

atom      ::=  identifier | literal | enclosure
enclosure ::=  parenth_form | list_display | dict_display | set_display
               | generator_expression | yield_atom

6.2.1. 識別子 (identifier、または名前 (name))

アトムの形になっている識別子 (identifier) は名前 (name) です。字句定義については 識別子 (identifier) およびキーワード (keyword) 節を、名前付けや束縛については 名前づけと束縛 (naming and binding) 節を参照してください。

名前があるオブジェクトに束縛されている場合、名前 atom を評価するとそのオブジェクトになります。名前が束縛されていない場合、 atom を評価しようとすると NameError 例外を送出します。

プライベートな名前のマングリング: クラス定義内に書かれた識別子で、2つ以上のアンダースコアから始まり、末尾が2つ以上のアンダースコアで終わっていないものは、そのクラスの プライベートな名前 とみなされます。プライベートな名前は、コードが生成される前により長い形式に変換されます。この変換によって、クラス名の先頭にアンダースコアがあれば除去し、先頭にアンダースコアを1つ付加し、名前の前に挿入されます。例えば、クラス名 Ham の中の識別子 __spam は、_Ham__spam に変換されます。変換は識別子が使用されている構文のコンテキストからは独立しています。変換された名前が非常に長い (255文字を超える) 場合、実装によっては名前の切り詰めが行われるかもしれません。クラス名がアンダースコアのみから成る場合は変換は行われません。

6.2.2. リテラル

Python では、文字列やバイト列リテラルと、様々な数値リテラルをサポートしています:

literal ::=  stringliteral | bytesliteral
             | integer | floatnumber | imagnumber

リテラルの評価は、与えられた型 (文字列、バイト列、整数、浮動小数点数、複素数) の与えられた値を持つオブジェクトを与えます。浮動小数点や虚数 (複素数) リテラルの場合、値は近似値になる場合があります。詳しくは リテラル を参照してください。

リテラルは全て変更不能なデータ型に対応します。このため、オブジェクトのアイデンティティはオブジェクトの値ほど重要ではありません。同じ値を持つ複数のリテラルを評価した場合、(それらのリテラルがプログラムの同じ場所由来のものであっても、そうでなくても) 同じオブジェクトを指しているか、まったく同じ値を持つ別のオブジェクトになります。

6.2.3. 丸括弧形式 (parenthesized form)

丸括弧形式とは、式リストの一形態で、丸括弧で囲ったものです:

parenth_form ::=  "(" [starred_expression] ")"

丸括弧で囲われた式のリストは、個々の式が表現するものになります: リスト内に少なくとも一つのカンマが入っていた場合、タプルになります; そうでない場合、式のリストを構成している単一の式自体の値になります。

中身が空の丸括弧のペアは、空のタプルオブジェクトを表します。タプルは変更不能なので、リテラルと同じ規則が適用されます (すなわち、空のタプルが二箇所で使われると、それらは同じオブジェクトになることもあるし、ならないこともあります)。

タプルは丸括弧で作成されるのではなく、カンマによって作成されることに注意してください。例外は空のタプルで、この場合には丸括弧が 必要です --- 丸括弧のつかない "何も記述しない式 (nothing)" を使えるようにしてしまうと、文法があいまいなものになってしまい、よくあるタイプミスが検出されなくなってしまいます。

6.2.4. リスト、集合、辞書の表示

リスト、集合、辞書を構築するために、 Python は "表示 (display)" と呼ばれる特別な構文を提供していて、次の二種類ずつがあります:

コンテナの内容を明示的に列挙する

内包表記 (comprehension) と呼ばれる、ループ処理とフィルター処理の組み合わせを用いた計算結果

内包表記の共通の構文要素は次の通りです:

comprehension ::=  assignment_expression comp_for
comp_for      ::=  ["async"] "for" target_list "in" or_test [comp_iter]
comp_iter     ::=  comp_for | comp_if
comp_if       ::=  "if" or_test [comp_iter]

内包表記はまず単一の式、続いて少なくとも 1 個の for 節、さらに続いて 0 個以上の for 節あるいは if 節からなります。この場合、各々の for 節や if 節を、左から右へ深くなっていくネストしたブロックとみなし、ネストの最内のブロックに到達するごとに内包表記の先頭にある式を評価した結果が、最終的にできあがるコンテナの各要素になります。

ただし、最も左にある for 節のイテラブル式を除いて、内包表記は暗黙的にネストされた個別のスコープで実行されます。この仕組みのおかげで、対象のリスト内で代入された名前が外側のスコープに "漏れる" ことはありません。

最も左にある for 節のイテラブル式は、それを直接囲んでいるスコープでそのまま評価され、暗黙的な入れ子のスコープに引数として渡されます。後に続く for 節と、最も左にある for 節のフィルター条件はイテラブル式を直接囲んでいるスコープでは評価できません。というのは、それらは最も左のイテラブルから得られる値に依存しているかもしれないからです。例えば次の通りです: [x*y for x in range(10) for y in range(x, x+10)] 。

内包表記が常に適切な型のコンテナになるのを保証するために、 yield 式や yield from 式は暗黙的な入れ子のスコープでは禁止されています。

Python 3.6 から、 async def 関数では async for 節が asynchronous iterator の反復処理をするのに使われることがありました。 async def 関数に含まれる内包表記が、先頭の式に続く for 節あるいは async for 節で構成されていることや、追加の for 節あるいは async for 節を含んでいること、そのうえ await 式を使っていることがあるかもしれません。内包表記が async for 節あるいは await 式やその他の非同期内包表記を含んでいる場合、それは 非同期内包表記 と呼ばれます。非同期内包表記は、それが現れるコルーチン関数の実行を中断させるかもしれません。 PEP 530 [https://peps.python.org/pep-0530/] も参照してください。

Added in version 3.6: 非同期内包表記が導入されました。

バージョン 3.8 で変更: yield および yield from は暗黙的な入れ子のスコープでは禁止となりました。

バージョン 3.11 で変更: Asynchronous comprehensions are now allowed inside comprehensions in asynchronous functions. Outer comprehensions implicitly become asynchronous.

6.2.5. リスト表示

リスト表示は、角括弧で囲われた式の系列です。系列は空の系列であってもかまいません:

list_display ::=  "[" [starred_list | comprehension] "]"

リスト表示は、新しいリストオブジェクトを与えます。リストの内容は、式のリストまたはリスト内包表記 (list comprehension) で指定されます。カンマで区切られた式のリストが与えられたときは、それらの各要素は左から右へと順に評価され、その順にリスト内に配置されます。内包表記が与えられたときは、内包表記の結果の要素でリストが構成されます。

6.2.6. 集合表示

集合表示は波括弧で表され、キーと値を分けるコロンがないことで辞書表現と区別されます:

set_display ::=  "{" (starred_list | comprehension) "}"

集合表示は、新しいミュータブルな集合オブジェクトを与えます。集合の内容は、式の並びまたは内包表記によって指定されます。カンマ区切りの式のリストが与えられたときは、その要素は左から右へ順に評価され、集合オブジェクトに加えられます。内包表記が与えられたときは、内包表記の結果の要素で集合が構成されます。

空集合は {} で構成できません。このリテラルは空の辞書を構成します。

6.2.7. 辞書表示

A dictionary display is a possibly empty series of dict items (key/value pairs) enclosed in curly braces:

dict_display       ::=  "{" [dict_item_list | dict_comprehension] "}"
dict_item_list     ::=  dict_item ("," dict_item)* [","]
dict_item          ::=  expression ":" expression | "**" or_expr
dict_comprehension ::=  expression ":" expression comp_for

辞書表示は、新たな辞書オブジェクトを表します。

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.

A double asterisk ** denotes dictionary unpacking. Its operand must be a mapping. Each mapping item is added to the new dictionary. Later values replace values already set by earlier dict items and earlier dictionary unpackings.

Added in version 3.5: 辞書表示のアンパックは最初に PEP 448 [https://peps.python.org/pep-0448/] で提案されました。

辞書内包表記は、リストや集合の内包表記とは対照的に、通常の "for" や "if" 節の前に、コロンで分けられた 2 つの式が必要です。内包表記が起動すると、結果のキーと値の要素が、作られた順に新しい辞書に挿入されます。

Restrictions on the types of the key values are listed earlier in section 標準型の階層. (To summarize, the key type should be 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 で変更: Python 3.8 より前のバージョンでは、辞書内包表記において、キーと値の評価順序は明示されていませんでした。CPython では、値がキーより先に評価されていました。バージョン 3.8 からは PEP 572 [https://peps.python.org/pep-0572/] で提案されているように、キーが値より先に評価されます。

6.2.8. ジェネレータ式

ジェネレータ式 (generator expression) とは、丸括弧を使ったコンパクトなジェネレータ表記法です:

generator_expression ::=  "(" expression comp_for ")"

ジェネレータ式は新たなジェネレータオブジェクトを与えます。この構文は内包表記とほぼ同じですが、角括弧や波括弧ではなく、丸括弧で囲まれます。

ジェネレータ式の中で使われている変数は、 (通常のジェネレータと同じように) そのジェネレータオブジェクトに対して __next__() メソッドが呼ばれるときまで評価が遅延されます。ただし、最も左にある for 節のイテラブル式は直ちに評価されます。そのためそこで生じたエラーは、最初の値が得られた時点ではなく、ジェネレータ式が定義された時点で発せられます。後に続く for 節と、最も左にある for 節のフィルター条件はイテラブル式を直接囲んでいるスコープでは評価できません。というのは、それらは最も左のイテラブルから得られる値に依存しているかもしれないからです。例えば次の通りです: (x*y for x in range(10) for y in range(x, x+10)) 。

関数の唯一の引数として渡す場合には、丸括弧を省略できます。詳しくは 呼び出し (call) 節を参照してください。

ジェネレータ式自身の期待される動作を妨げないために、 yield 式や yield from 式は暗黙的に定義されたジェネレータでは禁止されています。

ジェネレータ式が async for 節あるいは await 式を含んでいる場合、それは 非同期ジェネレータ式 と呼ばれます。非同期ジェネレータ式は、非同期イテレータである新しい非同期ジェネレータオブジェクトを返します (非同期イテレータ (Asynchronous Iterator) を参照してください)。

Added in version 3.6: 非同期ジェネレータ式が導入されました。

バージョン 3.7 で変更: Python 3.7 より前では、非同期ジェネレータ式は async def コルーチンでしか使えませんでした。 3.7 からは、任意の関数で非同期ジェネレータ式が使えるようになりました。

バージョン 3.8 で変更: yield および yield from は暗黙的な入れ子のスコープでは禁止となりました。

6.2.9. Yield 式

yield_atom       ::=  "(" yield_expression ")"
yield_from       ::=  "yield" "from" expression
yield_expression ::=  "yield" expression_list | yield_from

yield 式は ジェネレータ 関数や 非同期ジェネレータ 関数を定義するときに使われます。従って、関数定義の本体でのみ使えます。関数の本体で yield 式 を使用するとその関数はジェネレータ関数になり、 async def 関数の本体で使用するとそのコルーチン関数は非同期ジェネレータ関数になります。例えば次のようになります:

def gen():  # defines a generator function
    yield 123

async def agen(): # defines an asynchronous generator function
    yield 123

含まれているスコープの副作用のため、 yield 式は暗黙的に定義されたスコープの一部として内包表記やジェネレータ式を実装するのに使うことは許可されていません。

バージョン 3.8 で変更: yield 式は、暗黙的な入れ子のスコープで内包表記やジェネレータ式を実装するための使用が禁止になりました。

ジェネレータ関数についてはすぐ下で説明されています。非同期ジェネレータ関数は、 非同期ジェネレータ関数 (asynchronous generator function) 節に分けて説明されています。

ジェネレータ関数が呼び出された時、ジェネレータとしてのイテレータを返します。ジェネレータはその後ジェネレータ関数の実行を制御します。ジェネレータのメソッドが呼び出されると実行が開始されます。開始されると、最初の yield 式まで処理して一時停止し、呼び出し元へ expression_list の値を、または expression_list が省略されていれば None を返します。ここで言う一時停止とは、ローカル変数の束縛、命令ポインタや内部の評価スタック、そして例外処理のを含むすべてのローカル状態が保持されることを意味します。再度、ジェネレータのメソッドが呼び出されて実行を再開した時、ジェネレータは yield 式がただの外部呼び出しであったかのように処理を継続します。再開後の yield 式の値は実行を再開するメソッドに依存します。__next__() を使用した場合 (一般に for 文や組み込み関数 next() など) の結果は None となり、send() を使用した場合はそのメソッドに渡された値が結果になります。

これまで説明した内容から、ジェネレータ関数はコルーチンにとてもよく似ています。ジェネレータ関数は何度も生成し、1つ以上のエントリポイントを持ち、その実行は一時停止されます。ジェネレータ関数は yield した後で実行の継続を制御できないことが唯一の違いです。その制御は常にジェネレータの呼び出し元へ移されます。

yield 式は try 構造内で使用できます。ジェネレータの (参照カウントがゼロに達するか、ガベージコレクションによる) 完了前に再開されない場合、ジェネレータ-イテレータの close() メソッドが呼ばれ、finally 節が実行されます。

yield from <expr> を使用した場合、与えられた式はイテラブルでなければなりません。そのイテラブルをイテレートすることで生成された値は現在のジェネレータのメソッドの呼び出し元へ直接渡されます。send() で渡されたあらゆる値と throw() で渡されたあらゆる例外は根底のイテレータに適切なメソッドがあれば渡されます。適切なメソッドがない場合、send() は AttributeError か TypeError を、throw() は渡された例外を即座に送出します。

根底のイテレータの完了時、引き起こされた StopIteration インスタンスの value 属性はその yield 式の値となります。 StopIteration を起こす際に明示的にセットされるか、サブイテレータがジェネレータであれば (サブイテレータからかえる値で) 自動的にセットされるかのどちらかです。

バージョン 3.3 で変更: サブイテレータに制御フローを委譲するために yield from <expr> が追加されました。

yield 式が代入文の単独の右辺式であるとき、括弧は省略できます。

参考

PEP 255 [https://peps.python.org/pep-0255/] - 単純なジェネレータ

Python へのジェネレータと yield 文の導入提案。

PEP 342 [https://peps.python.org/pep-0342/] - 拡張されたジェネレータを用いたコルーチン

シンプルなコルーチンとして利用できるように、ジェネレータの構文と API を拡張する提案。

PEP 380 [https://peps.python.org/pep-0380/] - サブジェネレータへの委譲構文

サブジェネレータの委譲を簡単にするための、 yield_from 構文の導入提案。

PEP 525 [https://peps.python.org/pep-0525/] - 非同期ジェネレータ

コルーチン関数へのジェネレータの実装能力の追加による PEP 492 [https://peps.python.org/pep-0492/] の拡張提案。

6.2.9.1. ジェネレータ-イテレータメソッド

この説ではジェネレータイテレータのメソッドについて説明します。これらはジェネレータ関数の実行制御に使用できます。

以下のジェネレータメソッドの呼び出しは、ジェネレータが既に実行中の場合 ValueError 例外を送出する点に注意してください。

generator.__next__()

ジェネレータ関数の実行を開始するか、最後に yield 式が実行されたところから再開します。ジェネレータ関数が __next__() メソッドによって再開された時、その時点の yield 式の値は常に None と評価されます。その後次の yield 式まで実行し、ジェネレータは一時停止し、expression_list の値を __next__() メソッドの呼び出し元に返します。ジェネレータが次の値を yield せずに終了した場合、StopIteration 例外が送出されます。

このメソッドは通常、例えば for ループや組み込みの next() 関数によって暗黙に呼び出されます。

generator.send(value)

ジェネレータ関数の内部へ値を "送り"、実行を再開します。引数の value はその時点の yield 式の結果になります。 send() メソッドは次にジェネレータが生成した値を返し、ジェネレータが次の値を生成することなく終了すると StopIteration を送出します。 send() が呼び出されてジェネレータが開始するときは、値を受け取る yield 式が存在しないので、 None を引数として呼び出さなければなりません。

generator.throw(value)

generator.throw(type[, value[, traceback]])

ジェネレータが中断した位置で例外を発生させて、そのジェネレータ関数が生成する次の値を返します。ジェネレータが値を生成することなく終了すると StopIteration が発生します。ジェネレータ関数が渡された例外を捕捉しない、もしくは違う例外を発生させるなら、その例外は呼び出し元へ伝搬されます。

In typical use, this is called with a single exception instance similar to the way the 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 __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.

generator.close()

Raises a GeneratorExit at the point where the generator function was paused. If the generator function then exits gracefully, is already closed, or raises GeneratorExit (by not catching the exception), close returns to its caller. If the generator yields a value, a RuntimeError is raised. If the generator raises any other exception, it is propagated to the caller. close() does nothing if the generator has already exited due to an exception or normal exit.

6.2.9.2. 使用例

以下の簡単なサンプルはジェネレータとジェネレータ関数の振る舞いを実際に紹介します:

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

yield from の使用例は、"What's New in Python." の PEP 380: サブジェネレータへの委譲構文 を参照してください。

6.2.9.3. 非同期ジェネレータ関数 (asynchronous generator function)

async def を使用して定義された関数やメソッドに yield 式があると、その関数は 非同期ジェネレータ 関数として定義されます。

非同期ジェネレータ関数が呼び出されると、非同期ジェネレータオブジェクトと呼ばれる非同期イテレータが返されます。そして、そのオブジェクトはジェネレータ関数の実行を制御します。通常、非同期ジェネレータオブジェクトは、コルーチン関数内の async for 文で使われ、これはジェネレータオブジェクトが for 文で使われる様子に類似します。

非同期ジェネレータのメソッドの 1 つを呼び出すと awaitable オブジェクトが返され、このオブジェクトが動く番になったときに実行が開始されます。そのときに実行は最初の yield 式まで進み、そこで再び中断され、 expression_list の値を待機中のコルーチンに返します。ジェネレータと同様に、中断とは、現在のローカル変数束縛、命令ポインタ、内部評価スタック、および例外処理の状態など、すべてのローカルな状態が保たれることを意味します。非同期ジェネレータのメソッドから次のオブジェクトが返されたことで実行が再開されると、関数はあたかも yield 式が単なる外部呼び出しであるかのように処理を進めていきます。再開後の yield 式の値は、実行を再開したメソッドによって異なります。 __anext__() を使った場合は、結果は None になります。そうではなく、 asend() が使用された場合は、結果はそのメソッドに渡された値になります。

If an asynchronous generator happens to exit early by 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 aclose() method to finalize the generator and ultimately detach it from the event loop.

非同期ジェネレータ関数では、 try 構造内の任意の場所で yield 式が使用できます。ただし、非同期ジェネレータが、(参照カウントがゼロに達するか、ガベージコレクションによる) 終了処理より前に再開されない場合、 try 構造内の yield 式は失敗となり、実行待ちだった finally 節が実行されます。このケースでは、非同期ジェネレータが作動しているイベントループやスケジューラの責務は、非同期ジェネレータの aclose() メソッドを呼び出し、残りのコルーチンオブジェクトを実行し、それによって実行待ちだった finally 節が実行できるようにします。

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 aclose() and executes the coroutine. This finalizer may be registered by calling 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 asyncio.Loop.shutdown_asyncgens in Lib/asyncio/base_events.py [https://github.com/python/cpython/tree/3.12/Lib/asyncio/base_events.py].

yield from <expr> 式は、非同期ジェネレータ関数で使われると文法エラーになります。

6.2.9.4. 非同期ジェネレータイテレータメソッド

この小節では、ジェネレータ関数の実行制御に使われる非同期ジェネレータイテレータのメソッドについて説明します。

coroutine agen.__anext__()

Returns an awaitable which when run starts to execute the asynchronous generator or resumes it at the last executed yield expression. When an asynchronous generator function is resumed with an __anext__() method, the current yield expression always evaluates to None in the returned awaitable, which when run will continue to the next yield expression. The value of the expression_list of the yield expression is the value of the StopIteration exception raised by the completing coroutine. If the asynchronous generator exits without yielding another value, the awaitable instead raises a StopAsyncIteration exception, signalling that the asynchronous iteration has completed.

このメソッドは通常、 for ループによって暗黙に呼び出されます。

coroutine agen.asend(value)

Returns an awaitable which when run resumes the execution of the asynchronous generator. As with the 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 asend() method will return the next value yielded by the generator as the value of the raised StopIteration, or raises StopAsyncIteration if the asynchronous generator exits without yielding another value. When asend() is called to start the asynchronous generator, it must be called with None as the argument, because there is no yield expression that could receive the value.

coroutine agen.athrow(value)

coroutine agen.athrow(type[, value[, traceback]])

Returns an awaitable that raises an exception of type 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 StopIteration exception. If the asynchronous generator exits without yielding another value, a 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.

coroutine agen.aclose()

Returns an awaitable that when run will throw a 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 GeneratorExit (by not catching the exception), then the returned awaitable will raise a StopIteration exception. Any further awaitables returned by subsequent calls to the asynchronous generator will raise a StopAsyncIteration exception. If the asynchronous generator yields a value, a 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 aclose() will return an awaitable that does nothing.

6.3. プライマリ

プライマリは、言語において最も結合の強い操作を表します。文法は以下のようになります:

primary ::=  atom | attributeref | subscription | slicing | call

6.3.1. 属性参照

属性参照は、プライマリの後ろにピリオドと名前を連ねたものです:

attributeref ::=  primary "." identifier

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 __getattribute__() method or the __getattr__() method. The __getattribute__() method is called first and either returns a value or raises AttributeError if the attribute is not available.

If an AttributeError is raised and the object has a __getattr__() method, that method is called as a fallback.

6.3.2. 添字表記 (subscription)

The subscription of an instance of a container class will generally select an element from the container. The subscription of a generic class will generally return a GenericAlias object.

subscription ::=  primary "[" expression_list "]"

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 __getitem__() and __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 __class_getitem__ is called instead of __getitem__, see __class_getitem__ versus __getitem__.

If the expression list contains at least one comma, it will evaluate to a tuple containing the items of the expression list. Otherwise, the expression list will evaluate to the value of the list's sole member.

組み込みオブジェクトでは、__getitem__()　によって添字表記をサポートするオブジェクトには 2 種類あります:

マッピング。プライマリが マッピング であれば、式リストの値評価結果はマップ内のいずれかのキー値に相当するオブジェクトにならなければなりません。添字表記は、そのキーに対応するマッピング内の値 (value) を選択します。組み込みのマッピングクラスの例は dict クラスです。

シーケンス。プライマリが シーケンス であれば、式リストの評価結果は int または slice (以下の節で論じます) でなければなりません。組み込みのシーケンスクラスの例には str、list、tuple クラスが含まれます。

The formal syntax makes no special provision for negative indices in sequences. However, built-in sequences all provide a __getitem__() method that interprets negative indices by adding the length of the sequence to the index so that, for example, x[-1] selects the last item of 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 __getitem__() method, subclasses overriding this method will need to explicitly add that support.

文字列 は文字 (character) を要素とする特別な種類のシーケンスです。文字は個別の型ではなく、 1 文字だけからなる文字列です。

6.3.3. スライス表記 (slicing)

スライス表記はシーケンスオブジェクト (文字列、タプルまたはリスト) におけるある範囲の要素を選択します。スライス表記は式として用いたり、代入や del 文の対象として用いたりできます。スライス表記の構文は以下のようになります:

slicing      ::=  primary "[" slice_list "]"
slice_list   ::=  slice_item ("," slice_item)* [","]
slice_item   ::=  expression | proper_slice
proper_slice ::=  [lower_bound] ":" [upper_bound] [ ":" [stride] ]
lower_bound  ::=  expression
upper_bound  ::=  expression
stride       ::=  expression

上記の形式的な構文法にはあいまいなところがあります: 式リストに見えるものは、スライスリストにも見えるため、添字表記はスライス表記としても解釈されうるということです。(スライスリストが適切なスライスを含まない場合)、これ以上の構文の複雑化はせず、スライス表記としての解釈よりも添字表記としての解釈が優先されるように定義することで、あいまいさを取り除いています。

The semantics for a slicing are as follows. The primary is indexed (using the same __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 標準型の階層) whose start, stop and step attributes are the values of the expressions given as lower bound, upper bound and stride, respectively, substituting None for missing expressions.

6.3.4. 呼び出し (call)

呼び出しは、呼び出し可能オブジェクト (例えば function) を arguments の系列とともに呼び出します。系列は空の系列であってもかまいません:

call                 ::=  primary "(" [argument_list [","] | comprehension] ")"
argument_list        ::=  positional_arguments ["," starred_and_keywords]
                            ["," keywords_arguments]
                          | starred_and_keywords ["," keywords_arguments]
                          | keywords_arguments
positional_arguments ::=  positional_item ("," positional_item)*
positional_item      ::=  assignment_expression | "*" expression
starred_and_keywords ::=  ("*" expression | keyword_item)
                          ("," "*" expression | "," keyword_item)*
keywords_arguments   ::=  (keyword_item | "**" expression)
                          ("," keyword_item | "," "**" expression)*
keyword_item         ::=  identifier "=" expression

最後の位置引数やキーワード引数の後にカンマをつけてもかまいません。構文の意味付けに影響を及ぼすことはありません。

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 __call__() method are callable). All argument expressions are evaluated before the call is attempted. Please refer to section 関数定義 for the syntax of formal parameter lists.

キーワード引数が存在する場合、以下のようにして最初に位置引数 (positional argument) に変換されます。まず、値の入っていないスロットが仮引数に対して生成されます。N 個の位置引数がある場合、位置引数は先頭の N スロットに配置されます。次に、各キーワード引数について、識別子を使って対応するスロットを決定します (識別子が最初の仮引数名と同じなら、最初のスロットを使う、といった具合です)。スロットがすでにすべて埋まっていたなら TypeError 例外が送出されます。それ以外の場合、引数をスロットに埋めていきます。 (式が None であっても、その式でスロットを埋めます)。全ての引数が処理されたら、まだ埋められていないスロットをそれぞれに対応する関数定義時のデフォルト値で埋めます。(デフォルト値は、関数が定義されたときに一度だけ計算されます; 従って、リストや辞書のような変更可能なオブジェクトがデフォルト値として使われると、対応するスロットに引数を指定しない限り、このオブジェクトが全ての呼び出しから共有されます; このような状況は通常避けるべきです。) デフォルト値が指定されていない、値の埋められていないスロットが残っている場合 TypeError 例外が送出されます。そうでない場合、値の埋められたスロットからなるリストが呼び出しの引数として使われます。

CPython 実装の詳細: 実装では、名前を持たない位置引数を受け取る組み込み関数を提供されるかもしれません。そういった引数がドキュメント化のために '名付けられて' いたとしても、実際には名付けられていないのでキーワードでは提供されません。 CPython では、C 言語で実装された関数の、名前を持たない位置引数をパースするために PyArg_ParseTuple() を使用します。

仮引数スロットの数よりも多くの位置引数がある場合、構文 *identifier を使って指定された仮引数がないかぎり、 TypeError 例外が送出されます; 仮引数 *identifier がある場合、この仮引数は余分な位置引数が入ったタプル (もしくは、余分な位置引数がない場合には空のタプル) を受け取ります。

キーワード引数のいずれかが仮引数名に対応しない場合、構文 **identifier を使って指定された仮引数がない限り、 TypeError 例外が送出されます; 仮引数 **identifier がある場合、この仮引数は余分なキーワード引数が入った (キーワードをキーとし、引数値をキーに対応する値とした) 辞書を受け取ります。余分なキーワード引数がない場合には、空の (新たな) 辞書を受け取ります。

関数呼び出しに *expression という構文が現れる場合は、 expression の評価結果は イテラブル でなければなりません。そのイテラブルの要素は、追加の位置引数であるかのように扱われます。 f(x1, x2, *y, x3, x4) という呼び出しにおいて、 y の評価結果がシーケンス y1, ..., yM だった場合は、この呼び出しは M+4 個の位置引数 x1, x2, y1, ..., yM, x3, x4 での呼び出しと同じになります。

この結論としては、 *expression 構文がキーワード引数の 後ろ に来ることもありますが、キーワード引数 (と任意の **expression 引数 -- 下を参照) よりも 前 にあるものとして処理されます。従って、このような動作になります:

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

キーワード引数と *expression 構文を同じ呼び出しで一緒に使うことはあまりないので、実際に上記のような混乱が頻繁に生じることはありません。

関数呼び出しで **expression 構文が使われた場合、 expression の評価結果は マッピング でなければなりません。その内容は追加のキーワード引数として扱われます。キーにマッチする引数が (明示的なキーワード引数によって、あるいは他のアンパックの中で) 既に値を与えられていたなら、 TypeError 例外が送出されます。

When **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. "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 ** parameter, if there is one, or if there is not, a TypeError exception is raised.

*identifier や **identifier 構文を使った仮引数は、位置引数スロットやキーワード引数名にすることができません。

バージョン 3.5 で変更: 関数呼び出しは任意の数の * アンパックと ** アンパックを受け取り、位置引数はイテラブルアンパック (*) の後ろに置け、キーワード引数は辞書アンパック (**) の後ろに置けるようになりました。最初に PEP 448 [https://peps.python.org/pep-0448/] で提案されました。

呼び出しを行うと、例外を送出しない限り、常に何らかの値を返します。 None を返す場合もあります。戻り値がどのように算出されるかは、呼び出し可能オブジェクトの形態によって異なります。

各形態では---

ユーザ定義関数:

関数のコードブロックに引数リストが渡され、実行されます。コードブロックは、まず仮引数を実引数に結合 (bind) します; この動作については 関数定義 で記述しています。コードブロックで return 文が実行される際に、関数呼び出しの戻り値 (return value) が決定されます。

組み込み関数またはメソッド:

結果はインタプリタに依存します; 組み込み関数やメソッドの詳細は 組み込み関数 を参照してください。

クラスオブジェクト:

そのクラスの新しいインスタンスが返されます。

クラスインスタンスメソッド:

対応するユーザ定義の関数が呼び出されます。このとき、呼び出し時の引数リストより一つ長い引数リストで呼び出されます: インスタンスが引数リストの先頭に追加されます。

クラスインスタンス:

The class must define a __call__() method; the effect is then the same as if that method was called.

6.4. Await 式

awaitable オブジェクトでの coroutine 実行を一時停止します。 coroutine function 内でのみ使用できます。

await_expr ::=  "await" primary

Added in version 3.5.

6.5. べき乗演算 (power operator)

べき乗演算は、左側にある単項演算子よりも強い結合優先順位となります。一方、右側にある単項演算子よりは弱い結合優先順位になっています。構文は以下のようになります:

power ::=  (await_expr | primary) ["**" u_expr]

従って、べき乗演算子と単項演算子からなる演算列が丸括弧で囲われていない場合、演算子は右から左へと評価されます (この場合は演算子の評価順序を強制しません。つまり -1**2 は -1 になります)。

べき乗演算子の意味は、二つの引数で呼び出される組み込み関数 pow() と同じで、左引数を右引数乗して与えます。数値引数はまず共通の型に変換され、結果はその型です。

整数の被演算子では、第二引数が負でない限り、結果は被演算子と同じ型になります; 第二引数が負の場合、全ての引数は浮動小数点型に変換され、浮動小数点型が返されます。例えば 10**2 は 100 を返しますが、10**-2 は 0.01 を返します。

0.0 を負の数でべき乗すると ZeroDivisionError を送出します。負の数を小数でべき乗した結果は複素数 (complex number) になります。 (以前のバージョンでは ValueError を送出していました)

This operation can be customized using the special __pow__() method.

6.6. 単項算術演算とビット単位演算 (unary arithmetic and bitwise operation)

全ての単項算術演算とビット単位演算は、同じ優先順位を持っています:

u_expr ::=  power | "-" u_expr | "+" u_expr | "~" u_expr

The unary - (minus) operator yields the negation of its numeric argument; the operation can be overridden with the __neg__() special method.

The unary + (plus) operator yields its numeric argument unchanged; the operation can be overridden with the __pos__() special method.

The unary ~ (invert) operator yields the bitwise inversion of its integer argument. The bitwise inversion of x is defined as -(x+1). It only applies to integral numbers or to custom objects that override the __invert__() special method.

上記の三つはいずれも、引数が正しい型でない場合には TypeError 例外が送出されます。

6.7. 二項算術演算 (binary arithmetic operation)

二項算術演算は、慣習的な優先順位を踏襲しています。演算子のいずれかは、特定の非数値型にも適用されるので注意してください。べき乗 (power) 演算子を除き、演算子には二つのレベル、すなわち乗算的 (multiplicatie) 演算子と加算的 (additie) 演算子しかありません:

m_expr ::=  u_expr | m_expr "*" u_expr | m_expr "@" m_expr |
            m_expr "//" u_expr | m_expr "/" u_expr |
            m_expr "%" u_expr
a_expr ::=  m_expr | a_expr "+" m_expr | a_expr "-" m_expr

* (乗算: multiplication) 演算子は、引数同士の積を与えます。引数は、両方とも数値であるか、片方が整数で他方がシーケンスかのどちらかでなければなりません。前者の場合、数値は共通の型に変換された後乗算されます。後者の場合、シーケンスの繰り返し操作が行われます。繰り返し数を負にすると、空のシーケンスを与えます。

This operation can be customized using the special __mul__() and __rmul__() methods.

@ (at) 演算子は行列の乗算に対し使用されます。 Python の組み込み型はこの演算子を実装していません。

Added in version 3.5.

/ (除算: division) および // (切り捨て除算: floor division) は、引数同士の商を与えます。数値引数はまず共通の型に変換されます。整数の除算結果は浮動小数点になりますが、整数の切り捨て除算結果は整数になります; この場合、結果は数学的な除算に 'floor' 関数 を適用したものになります。ゼロによる除算を行うと ZeroDivisionError 例外を送出します。

This operation can be customized using the special __truediv__() and __floordiv__() methods.

% (剰余: modulo) 演算は、第一引数を第二引数で除算したときの剰余になります。数値引数はまず共通の型に変換されます。右引数値がゼロの場合には ZeroDivisionError 例外が送出されます。引数値は浮動小数点でもよく。例えば 3.14%0.7 は 0.34 になります (3.14 は 4*0.7 + 0.34 だからです)。剰余演算子は常に第二引数と同じ符号 (またはゼロ) の結果になります; 剰余演算の結果の絶対値は、常に第二引数の絶対値よりも小さくなります。 [1]

切り捨て除算演算と剰余演算は、恒等式: x == (x//y)*y + (x%y) の関係にあります。切り捨て除算や剰余はまた、組み込み関数 divmod(): divmod(x, y) == (x//y, x%y) とも関係しています。 [2] 。

% 演算子は、数値に対する剰余演算を行うのに加えて、文字列 (string) オブジェクトにオーバーロードされ、旧式の文字列の書式化 (いわゆる補間) を行います。文字列の書式化の構文は Python ライブラリリファレンス printf 形式の文字列書式化 節を参照してください。

The modulo operation can be customized using the special __mod__() method.

切り捨て除算演算子、剰余演算子、および divmod() 関数は、複素数に対しては定義されていません。目的に合うならば、代わりに abs() を使って浮動小数点に変換してください。

+ (加算) 演算は、引数同士の和を与えます。引数は双方とも数値型か、双方とも同じ型のシーケンスでなければなりません。前者の場合、数値は共通の型に変換され、加算されます。後者の場合、シーケンスは結合 (concatenate) されます。

This operation can be customized using the special __add__() and __radd__() methods.

- (減算) 演算は、引数間で減算を行った値を返します。数値引数はまず共通の型に変換されます。

This operation can be customized using the special __sub__() method.

6.8. シフト演算 (shifting operation)

シフト演算は、算術演算よりも低い優先順位を持っています:

shift_expr ::=  a_expr | shift_expr ("<<" | ">>") a_expr

これらは整数を引数にとります。引数は共通の型に変換されます。シフト演算は第一引数を、第二引数で与えられたビット数だけ、左または右にビットシフトします。

This operation can be customized using the special __lshift__() and __rshift__() methods.

n ビットの右シフトは pow(2,n) による除算として定義されます。n ビットの左シフトは pow(2,n) による乗算として定義されます。

6.9. ビット単位演算の二項演算 (binary bitwise operation)

以下の三つのビット単位演算には、それぞれ異なる優先順位レベルがあります:

and_expr ::=  shift_expr | and_expr "&" shift_expr
xor_expr ::=  and_expr | xor_expr "^" and_expr
or_expr  ::=  xor_expr | or_expr "|" xor_expr

The & operator yields the bitwise AND of its arguments, which must be integers or one of them must be a custom object overriding __and__() or __rand__() special methods.

The ^ operator yields the bitwise XOR (exclusive OR) of its arguments, which must be integers or one of them must be a custom object overriding __xor__() or __rxor__() special methods.

The | operator yields the bitwise (inclusive) OR of its arguments, which must be integers or one of them must be a custom object overriding __or__() or __ror__() special methods.

6.10. 比較

C 言語と違って、Python における比較演算子は同じ優先順位をもっており、全ての算術演算子、シフト演算子、ビット単位演算子よりも低くなっています。また a < b < c が数学で伝統的に用いられているのと同じ解釈になる点も C 言語と違います:

comparison    ::=  or_expr (comp_operator or_expr)*
comp_operator ::=  "<" | ">" | "==" | ">=" | "<=" | "!="
                   | "is" ["not"] | ["not"] "in"

Comparisons yield boolean values: True or False. Custom rich comparison methods may return non-boolean values. In this case Python will call bool() on such value in boolean contexts.

比較はいくらでも連鎖することができます。例えば x < y <= z は x < y and y <= z と等価になります。ただしこの場合、前者では y はただ一度だけ評価される点が異なります (どちらの場合でも、 x < y が偽になると z の値はまったく評価されません)。

形式的には、 a, b, c, ..., y, z が式で op1, op2, ..., opN が比較演算子である場合、 a op1 b op2 c ... y opN z は a op1 b and b op2 c and ... y opN z と等価になります。ただし、前者では各式は多くても一度しか評価されません。

a op1 b op2 c と書いた場合、 a から c までの範囲にあるかどうかのテストを指すのではないことに注意してください。例えば x < y > z は (きれいな書き方ではありませんが) 完全に正しい文法です。

6.10.1. 値の比較

演算子 <, >, ==, >=, <=, および != は2つのオブジェクトの値を比較します。オブジェクトが同じ型を持つ必要はりません。

オブジェクト、値、および型 の章では、オブジェクトは (型や id に加えて) 値を持つことを述べています。オブジェクトの値は Python ではやや抽象的な概念です: 例えば、オブジェクトの値にアクセスする正統な方法はありません。また、その全てのデータ属性から構成されるなどの特定の方法で、オブジェクトの値を構築する必要性もありません。比較演算子は、オブジェクトの値とは何かについての特定の概念を実装しています。この比較の実装によって、間接的にオブジェクトの値を定義していると考えることもできます。

Because all types are (direct or indirect) subtypes of object, they inherit the default comparison behavior from object. Types can customize their comparison behavior by implementing rich comparison methods like __lt__(), described in 基本的なカスタマイズ.

等価比較 (== および !=) のデフォルトの振る舞いは、オブジェクトの同一性に基づいています。従って、同一のインスタンスの等価比較の結果は等しいとなり、同一でないインスタンスの等価比較の結果は等しくないとなります。デフォルトの振る舞いをこのようにしたのは、全てのオブジェクトを反射的 (reflexive つまり x is y ならば x == y) なものにしたかったからです。

デフォルトの順序比較 (<, >, <=, >=) は提供されません; 比較しようとすると TypeError が送出されます。この振る舞いをデフォルトの振る舞いにした動機は、等価性と同じような不変性が欠けているからです。

同一でないインスタンスは常に等価でないとする等価比較のデフォルトの振る舞いは、型が必要とするオブジェクトの値や値に基づいた等価性の実用的な定義とは対照的に思えるでしょう。そのような型では比較の振る舞いをカスタマイズする必要が出てきて、実際にたくさんの組み込み型でそれが行われています。

次のリストでは、最重要の組み込み型の比較の振る舞いを解説しています。

いくつかの組み込みの数値型 (数値型 int, float, complex) と標準ライブラリの型 fractions.Fraction および decimal.Decimal は、これらの型の範囲で異なる型とも比較できますが、複素数では順序比較がサポートされていないという制限があります。関わる型の制限の範囲内では、精度のロス無しに数学的に (アルゴリズム的に) 正しい比較が行われます。

非数値である float('NaN') と decimal.Decimal('NaN') は特別です。数と非数値との任意の順序比較は偽です。直観に反する帰結として、非数値は自分自身と等価ではないことになります。例えば x = float('NaN') ならば、 3 < x, x < 3, x == x は全て偽で、x != x は真です。この振る舞いは IEEE 754 に従ったものです。

None and NotImplemented are singletons. PEP 8 [https://peps.python.org/pep-0008/] advises that comparisons for singletons should always be done with is or is not, never the equality operators.

バイナリシーケンス (bytes または bytearray のインスタンス) は、これらの型の範囲で異なる型とも比較できます。比較は要素の数としての値を使った辞書式順序で行われます。

文字列 (str のインスタンス) の比較は、文字の Unicode のコードポイントの数としての値 (組み込み関数 ord() の返り値) を使った辞書式順序で行われます。 [3]

文字列とバイナリシーケンスは直接には比較できません。

シーケンス (tuple, list, or range のインスタンス) の比較は、同じ型どうしでしか行えず、 range は順序比較をサポートしていません。異なる型どうしの等価比較の結果は等価でないとなり、異なる型どうしの順序比較は 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.

組み込みのコレクションどうしの辞書式比較は次のように動作します:

比較の結果が等価となる2つのコレクションは、同じ型、同じ長さ、対応する要素どうしの比較の結果が等価でなければなりません (例えば、 [1,2] == (1,2) は型が同じでないので偽です)。

順序比較をサポートしているコレクションの順序は、最初の等価でない要素の順序と同じになります (例えば、 [1,2,x] <= [1,2,y] は x <= y と同じ値になります)。対応する要素が存在しない場合、短い方のコレクションの方が先の順序となります (例えば、 [1,2] < [1,2,3] は真です)。

マッピング (dict のインスタンス) の比較の結果が等価となるのは、同じ (key, value) を持っているときかつそのときに限ります。キーと値の等価比較では反射性が強制されます。

順序比較 (<, >, <=, >=) は TypeError を送出します。

集合 (set または frozenset のインスタンス) の比較は、これらの型の範囲で異なる型とも行えます。

集合には、部分集合あるいは上位集合かどうかを基準とする順序比較が定義されています。この関係は全順序を定義しません (例えば、 {1,2} と {2,3} という2つの集合は片方がもう一方の部分集合でもなく上位集合でもありません)。従って、集合は全順序性に依存する関数の引数として適切ではありません (例えば、 min(), max(), sorted() は集合のリストを入力として与えると未定義な結果となります)。

集合の比較では、その要素の反射性が強制されます。

他の組み込み型のほとんどは比較メソッドが実装されておらず、デフォルトの比較の振る舞いを継承します。

比較の振る舞いをカスタマイズしたユーザ定義クラスは、可能なら次の一貫性の規則に従う必要があります:

等価比較は反射的でなければなりません。つまり、同一のオブジェクトは等しくなければなりません:

x is y ならば x == y

比較は対称的でなければなりません。つまり、以下の式の結果は同じでなければなりません:

x == y と y == x

x != y と y != x

x < y と y > x

x <= y と y >= x

比較は推移的でなければなりません。以下の (包括的でない) 例がその説明です:

x > y and y > z ならば x > z

x < y and y <= z ならば x < z

比較の逆は真偽値の否定でなければなりません。つまり、以下の式の結果は同じでなければなりません:

x == y と not x != y

x < y と not x >= y (全順序の場合)

x > y と not x <= y (全順序の場合)

最後の2式は全順序コレクションに当てはまります (たとえばシーケンスには当てはまりますが、集合やマッピングには当てはまりません)。 total_ordering() デコレータも参照してください。

hash() の結果は等価性と一貫している必要があります。等価なオブジェクトどうしは同じハッシュ値を持つか、ハッシュ値が計算できないものとされる必要があります。

Python はこの一貫性規則を強制しません。事実、非数値がこの規則に従わない例となります。

6.10.2. 所属検査演算

演算子 in および not in は所属関係を調べます。 x in s の評価は、 x が s の要素であれば True となり、そうでなければ False となります。 x not in s は x in s の否定を返します。すべての組み込みのシーケンス型と集合型に加えて、辞書も in を辞書が与えられたキーを持っているかを調べる演算子としてサポートしています。リスト、タプル、集合、凍結集合、辞書、 collections.deque のようなコンテナ型において、式 x in y は any(x is e or x == e for e in y) と等価です。

文字列やバイト列型については、 x in y は x が y の部分文字列であるとき、かつそのときに限り True になります。これは y.find(x) != -1 と等価です。空文字列は、他の任意の文字列の部分文字列とみなされます。従って "" in "abc" は True を返すことになります。

For user-defined classes which define the __contains__() method, x in y returns True if y.__contains__(x) returns a true value, and False otherwise.

For user-defined classes which do not define __contains__() but do define __iter__(), x in y is True if some value z, for which the expression x is z or x == z is true, is produced while iterating over y. If an exception is raised during the iteration, it is as if in raised that exception.

Lastly, the old-style iteration protocol is tried: if a class defines __getitem__(), x in y is True if and only if there is a non-negative integer index i such that x is y[i] or x == y[i], and no lower integer index raises the IndexError exception. (If any other exception is raised, it is as if in raised that exception).

演算子 not in は in の真理値を反転した値として定義されています。

6.10.3. 同一性の比較

演算子 is および is not は、オブジェクトの同一性に対するテストを行います: x is y は、 x と y が同じオブジェクトを指すとき、かつそのときに限り真になります。オブジェクトの同一性は id() 関数を使って判定されます。 x is not y は is の真値を反転したものになります。 [4]

6.11. ブール演算 (boolean operation)

or_test  ::=  and_test | or_test "or" and_test
and_test ::=  not_test | and_test "and" not_test
not_test ::=  comparison | "not" not_test

In the context of Boolean operations, and also when expressions are used by control flow statements, the following values are interpreted as false: False, 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 __bool__() method.

演算子 not は、引数が偽である場合には True を、それ以外の場合には False になります。

式 x and y は、まず x を評価します; x が偽なら x の値を返します; それ以外の場合には、 y を評価した結果値を返します。

式 x or y は、まず x を評価します; x が真なら x の値を返します; それ以外の場合には、 y を評価した結果値を返します。

なお、 and も or も、返す値を True や False に制限せず、最後に評価した引数を返します。この仕様が便利なときもあります。例えば s が文字列で、空文字列ならデフォルトの値に置き換えたいとき、式 s or 'foo' は望んだ値を与えます。 not は必ず新しい値を作成するので、引数の型に関係なくブール値を返します (例えば、 not 'foo' は '' ではなく False になります)。

6.12. 代入式

assignment_expression ::=  [identifier ":="] expression

An assignment expression (sometimes also called a "named expression" or "walrus") assigns an expression to an identifier, while also returning the value of the expression.

One common use case is when handling matched regular expressions:

if matching := pattern.search(data):
    do_something(matching)

Or, when processing a file stream in chunks:

while chunk := file.read(9000):
    process(chunk)

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 assert, with, and assignment statements. In all other places where they can be used, parentheses are not required, including in if and while statements.

Added in version 3.8: 代入式に関してより詳しくは PEP 572 [https://peps.python.org/pep-0572/] を参照してください。

6.13. 条件式 (Conditional Expressions)

conditional_expression ::=  or_test ["if" or_test "else" expression]
expression             ::=  conditional_expression | lambda_expr

条件式 (しばしば "三項演算子" と呼ばれます) は最も優先度が低いPython の演算です。

x if C else y という式は最初に x ではなく条件 C を評価します。 C が true の場合 x が評価され値が返されます。 それ以外の場合には y が評価され返されます。

条件演算に関してより詳しくは PEP 308 [https://peps.python.org/pep-0308/] を参照してください。

6.14. ラムダ (lambda)

lambda_expr ::=  "lambda" [parameter_list] ":" expression

ラムダ式 (ラムダ形式とも呼ばれます) は無名関数を作成するのに使います。式 lambda parameters: expression は関数オブジェクトになります。この無名オブジェクトは以下に定義されている関数オブジェクト同様に動作します:

def <lambda>(parameters):
    return expression

引数の一覧の構文は 関数定義 を参照してください。ラムダ式で作成された関数は文やアノテーションを含むことができない点に注意してください。

6.15. 式のリスト

expression_list    ::=  expression ("," expression)* [","]
starred_list       ::=  starred_item ("," starred_item)* [","]
starred_expression ::=  expression | (starred_item ",")* [starred_item]
starred_item       ::=  assignment_expression | "*" or_expr

リスト表示や辞書表示の一部になっているものを除き、少なくとも一つのカンマを含む式のリストはタプルになります。タプルの長さは、リストにある式の数に等しくなります。式は左から右へ評価されます。

アスタリスク * は イテラブルのアンパック を意味します。この被演算子は イテラブル でなければなりません。このイテラブルはアンパックされた位置で要素のシーケンスに展開され、新しいタプル、リスト、集合に入れ込まれます。

Added in version 3.5: 式リストでのイテラブルのアンパックは最初に PEP 448 [https://peps.python.org/pep-0448/] で提案されました。

A trailing comma is required only to create a one-item tuple, such as 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: ().)

6.16. 評価順序

Python は、式を左から右へと順に評価します。ただし、代入式を評価するときは、右辺が左辺よりも先に評価されます。

以下に示す実行文の各行での評価順序は、添え字の数字順序と同じになります:

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

6.17. 演算子の優先順位

以下の表は Python における演算子の優先順位を要約したものです。優先順位の最も高い (結合が最も強い) ものから最も低い (結合が最も弱い) ものに並べてあります。同じボックス内の演算子の優先順位は同じです。構文が明示的に示されていないものは二項演算子です。同じボックス内の演算子は、左から右へとグループ化されます (例外として、べき乗および条件式は右から左にグループ化されます)。

比較 節で述べられているように、比較、所属、同一性のテストは全てが同じ優先順位を持っていて、左から右に連鎖するという特徴を持っていることに注意してください。

演算子

説明

(expressions...),

[expressions...], {key: value...}, {expressions...}

結合式または括弧式、リスト表示、辞書表示、集合表示

x[index], x[index:index], x(arguments...), x.attribute

添字指定、スライス操作、呼び出し、属性参照

await x

Await 式

**

べき乗 [5]

+x, -x, ~x

正数、負数、ビット単位 NOT

*, @, /, //, %

乗算、行列乗算、除算、切り捨て除算、剰余 [6]

+, -

加算および減算

<<, >>

シフト演算

&

ビット単位 AND

^

ビット単位 XOR

|

ビット単位 OR

in, not in, is, is not, <, <=, >, >=, !=, ==

所属や同一性のテストを含む比較

not x

ブール演算 NOT

and

ブール演算 AND

or

ブール演算 OR

if -- else

条件式

lambda

ラムダ式

:=

代入式

脚注

[1]

abs(x%y) < abs(y) は数学的には真となりますが、浮動小数点に対する演算の場合には、値丸め (roundoff) のために数値計算的に真にならない場合があります。例えば、Python の浮動小数点型が IEEE754 倍精度数型になっているプラットフォームを仮定すると、 -1e-100 % 1e100 は 1e100 と同じ符号になるはずなのに、計算結果は -1e-100 + 1e100 となります。これは数値計算的には厳密に 1e100 と等価です。関数 math.fmod() は、最初の引数と符号が一致するような値を返すので、上記の場合には -1e-100 を返します。どちらのアプローチが適切かは、アプリケーションに依存します。

[2]

x が y の正確な整数倍に非常に近いと、丸めのために x//y が (x-x%y)//y よりも 1 だけ大きくなる可能性があります。そのような場合、Python は divmod(x,y)[0] * y + x % y が x に非常に近くなるという関係を保つために、後者の値を返します。

[3]

Unicode 標準では、 コードポイント (code point) (例えば、U+0041) と 抽象文字 (abstract character) (例えば、"LATIN CAPITAL LETTER A") を区別します。 Unicode のほとんどの抽象文字は 1 つのコードポイントだけを使って表現されますが、複数のコードポイントの列を使っても表現できる抽象文字もたくさんあります。例えば、抽象文字 "LATIN CAPITAL LETTER C WITH CEDILLA" はコード位置 U+00C7 にある 合成済み文字 (precomposed character) 1 つだけでも表現できますし、コード位置 U+0043 (LATIN CAPITAL LETTER C) にある 基底文字 (base character) の後ろに、コード位置 U+0327 (COMBINING CEDILLA) にある 結合文字 (combining character) が続く列としても表現できます。

文字列の比較操作は Unicode のコードポイントのレベルで行われます。これは人間にとっては直感的ではないかもしれません。例えば、 "\u00C7" == "\u0043\u0327" は、どちらの文字も同じ抽象文字 "LATIN CAPITAL LETTER C WITH CEDILLA" を表現しているにもかかわらず、その結果は False となります。

抽象文字のレベルで (つまり、人間にとって直感的な方法で) 文字列を比較するには unicodedata.normalize() を使ってください。

[4]

自動的なガベージコレクション、フリーリスト、ディスクリプタの動的特性のために、インスタンスメソッドや定数の比較を行うようなときに is 演算子の利用は、一見すると普通ではない振る舞いだと気付くかもしれません。詳細はそれぞれのドキュメントを確認してください。

[5]

べき乗演算子 ** は、右側にある単項算術演算子あるいは単項ビット演算子より弱い結合優先順位となります。つまり 2**-1 は 0.5 になります。

[6]

% 演算子は文字列フォーマットにも使われ、同じ優先順位が当てはまります。

7. 単純文 (simple statement)

単純文とは、単一の論理行内に収められる文です。単一の行内には、複数の単純文をセミコロンで区切って入れることができます。単純文の構文は以下の通りです:

simple_stmt ::=  expression_stmt
                 | assert_stmt
                 | assignment_stmt
                 | augmented_assignment_stmt
                 | annotated_assignment_stmt
                 | pass_stmt
                 | del_stmt
                 | return_stmt
                 | yield_stmt
                 | raise_stmt
                 | break_stmt
                 | continue_stmt
                 | import_stmt
                 | future_stmt
                 | global_stmt
                 | nonlocal_stmt
                 | type_stmt

7.1. 式文 (expression statement)

式文は、(主に対話的な使い方では) 値を計算して出力するために使ったり、(通常は) プロシジャ (procedure: 有意な結果を返さない関数のことです; Python では、プロシジャは値 None を返します) を呼び出すために使います。その他の使い方でも式文を使うことができますし、有用なこともあります。式文の構文は以下の通りです:

expression_stmt ::=  starred_expression

式文は式のリスト (単一の式のこともあります) を値評価します。

対話モードでは、値が None でなければ、値を組み込み関数 repr() で文字列に変換して、その結果の文字列を標準出力に一行使って書き出します。 (None になる式文の値は書き出されないので、プロシジャの呼び出しを行っても出力は得られません。)

7.2. 代入文 (assignment statement)

代入文は、名前を値に (再) 束縛したり、変更可能なオブジェクトの属性や要素を変更したりするために使われます:

assignment_stmt ::=  (target_list "=")+ (starred_expression | yield_expression)
target_list     ::=  target ("," target)* [","]
target          ::=  identifier
                     | "(" [target_list] ")"
                     | "[" [target_list] "]"
                     | attributeref
                     | subscription
                     | slicing
                     | "*" target

(attributeref, subscription, slicing の構文については プライマリ 節を参照してください。)

代入文は式のリスト (これは単一の式でも、カンマで区切られた式リストでもよく、後者はタプルになることを思い出してください) を評価し、得られたそれぞれのオブジェクトをターゲット (target) のリストに対して左から右へと代入してゆきます。

代入はターゲット (リスト) の形式に従って再帰的に行われます。ターゲットが変更可能なオブジェクト (属性参照、添字表記、またはスライス) の一部である場合、この変更可能なオブジェクトは最終的に代入を実行して、その代入が有効な操作であるか判断しなければなりません。代入が不可能な場合には例外を発行することもできます。型ごとにみられる規則や、送出される例外は、そのオブジェクト型定義で与えられています (標準型の階層 節を参照してください).

ターゲットリストは、丸括弧や角括弧で囲まれていてもよく、それに対するオブジェクトの代入は、以下のように再帰的に定義されています。

ターゲットリストのターゲットが1つだけでコンマが続いておらず、任意に丸括弧で囲われている場合、オブジェクトはそのターゲットに代入されます。

その他:

"星付き"のターゲットと呼ばれる、頭にアスタリスクが一つ付いたターゲットがターゲットリストに一つだけ含まれている場合: オブジェクトはイテラブルで、少なくともターゲットリストのターゲットの数よりも一つ少ない要素を持たなければなりません。星付きのターゲットより前のターゲットに、イテラブルの先頭の要素が左から右へ代入されます。星付きのターゲットより後ろのターゲットに、イテラブルの末尾の要素が代入されます。星付きのターゲットに、イテラブルの残った要素のリストが代入されます (リスト空でもかまいません)。

そうでない場合: オブジェクトは、ターゲットリストのターゲットと同じ数の要素を持つイテラブルでなければならず、要素は左から右へ対応するターゲットに代入されます。

単一のターゲットへの単一のオブジェクトの代入は、以下のようにして再帰的に定義されています。

ターゲットが識別子 (名前) の場合:

名前が現在のコードブロック内の global や nonlocal 文に書かれていないければ: 名前は現在のローカル名前空間内のオブジェクトに束縛されます。

そうでなければ: 名前はそれぞれグローバル名前空間内か、 nonlocal で決められた外側の名前空間内のオブジェクトに束縛されます。

名前がすでに束縛済みの場合、再束縛 (rebind) がおこなわれます。再束縛によって、以前その名前に束縛されていたオブジェクトの参照カウント (reference count) がゼロになった場合、オブジェクトは解放 (deallocate) され、デストラクタ (destructor) が (存在すれば) 呼び出されます。

ターゲットが属性参照の場合: 参照されている一次語の式が値評価されます。値は代入可能な属性を伴うオブジェクトでなければなりません; そうでなければ、 TypeError が送出されます。次に、このオブジェクトに対して、被代入オブジェクトを指定した属性に代入してよいか問い合わせます; 代入を実行できない場合、例外 (通常は AttributeError ですが、必然ではありません) を送出します。

注意: オブジェクトがクラスインスタンスで、代入演算子の両辺に属性参照があるとき、右辺式の a.x はインスタンスの属性と (インスタンスの属性が存在しなければ) クラス属性のどちらにもアクセスする可能性があります。左辺のターゲット a.x は常にインスタンスの属性として割り当てられ、必要ならば生成されます。このとおり、現れる二つの a.x は同じ値を参照するとは限りません: 右辺式はクラス属性を参照し、左辺は新しいインスタンス属性を代入のターゲットとして生成するようなとき:

class Cls:
    x = 3             # class variable
inst = Cls()
inst.x = inst.x + 1   # writes inst.x as 4 leaving Cls.x as 3

このことは、 property() で作成されたプロパティのようなデスクリプタ属性に対しては、必ずしもあてはまるとは限りません。

ターゲットが添字表記なら: 参照されている一次語式が評価されます。参照から (リストのような) ミュータブルなシーケンスオブジェクトか、(辞書のような) マッピングオブジェクトが得られなければなりません。次に、添字表記の表す式が評価されます。

一次語が (リストのような) ミュータブルなシーケンスオブジェクトであれば、添字表記は整数を与えなければなりません。整数が負なら、シーケンスの長さが加算されます。整数は最終的に、シーケンスの長さよりも小さな非負の整数でなくてはならず、シーケンスは、そのインデクスに持つ要素に被代入オブジェクトを代入してよいか問い合わせられます。インデクスが範囲外なら、 IndexError が送出されます (添字指定されたシーケンスに代入を行っても、リスト要素の新たな追加はできません)。

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 __setitem__() method is called with appropriate arguments.

ターゲットがスライスなら: 参照されている一次語式が評価されます。一次語式は、(リストのような) ミュータブルなシーケンスオブジェクトを与えなければなりません。被代入オブジェクトは同じ型のシーケンスオブジェクトでなければなりません。次に、スライスの下限と上限を示す式があれば評価されます; デフォルト値はそれぞれ 0 とシーケンスの長さです。上限と下限の評価は整数でなければなりません。いずれかの境界が負数なら、シーケンスの長さが加算されます。最終的に、境界は 0 からシーケンスの長さまでに収まるように刈りこまれます。最後に、スライスを被代入オブジェクトで置き換えてよいかシーケンスオブジェクトに問い合わせます。ターゲットシーケンスで許されている限り、スライスの長さは被代入シーケンスの長さと異なっていてよく、この場合にはターゲットシーケンスの長さが変更されます。

CPython 実装の詳細: 現在の実装では、ターゲットの構文は式の構文と同じであるとみなされており、無効な構文はコード生成フェーズ中に詳細なエラーメッセージを伴って拒否されます。

代入の定義によれば、左辺と右辺のオーバーラップは '同時 (simultaneous)' です (例えば a, b = b, a は二つの変数を入れ替えます) が、代入対象となる変数群 どうし のオーバーラップは左から右へ起こり、混乱の元です。例えば、以下のプログラムは [0, 2] を出力してしまいます:

x = [0, 1]
i = 0
i, x[i] = 1, 2         # i is updated, then x[i] is updated
print(x)

参考

PEP 3132 [https://peps.python.org/pep-3132/] - Extended Iterable Unpacking

*target の指定機能。

7.2.1. 累算代入文 (augmented assignment statement)

累算代入文は、二項演算と代入文を組み合わせて一つの文にしたものです:

augmented_assignment_stmt ::=  augtarget augop (expression_list | yield_expression)
augtarget                 ::=  identifier | attributeref | subscription | slicing
augop                     ::=  "+=" | "-=" | "*=" | "@=" | "/=" | "//=" | "%=" | "**="
                               | ">>=" | "<<=" | "&=" | "^=" | "|="

(最後の3つの構文定義については プライマリ を参照してください。)

累算代入文は、ターゲット (通常の代入文と違って、アンパックは起こりません) と式リストを評価し、それら二つの被演算子間で特定の累算代入型の二項演算を行い、結果をもとのターゲットに代入します。ターゲットは一度しか評価されません。

x += 1 のような累算代入式は、 x = x + 1 のように書き換えてほぼ同様の動作にできますが、厳密に等価にはなりません。累算代入の方では、 x は一度しか評価されません。また、実際の処理として、可能ならば インプレース (in-place) 演算が実行されます。これは、代入時に新たなオブジェクトを生成してターゲットに代入するのではなく、以前のオブジェクトの内容を変更するということです。

通常の代入とは違い、累算代入文は右辺を評価する 前に 左辺を評価します。たとえば、a[i] += f(x) はまず a[i] を調べ、f(x) を評価して加算を行い、最後に結果を a[i] に割り当てます。

累算代入文で行われる代入は、タプルへの代入や、一文中に複数のターゲットが存在する場合を除き、通常の代入と同じように扱われます。同様に、累算代入で行われる二項演算は、場合によって インプレース演算 が行われることを除き、通常の二項演算と同じです。

属性参照のターゲットの場合、 クラス属性とインスタンス属性についての注意 と同様に通常の代入が適用されます。

7.2.2. 注釈付き代入文 (annotated assignment statements)

注釈 代入は、1 つの文の中で変数や属性のアノテーションとオプションの代入文を組み合わせたものです:

annotated_assignment_stmt ::=  augtarget ":" expression
                               ["=" (starred_expression | yield_expression)]

通常の 代入文 (assignment statement) との違いは、代入先が 1 つに限定されることだけです。

代入先として単純名を使うと、クラススコープもしくはモジュールスコープの場合、注釈は評価され、クラスもしくはモジュールの特殊属性 __annotations__ に格納されます。この属性は、変数名 (プライベート変数の場合はマングリングされた名前) から評価後の注釈への対応付けを持つ辞書です。この属性は書き込み可能であり、注釈が静的に存在している場合、クラスもしくはモジュールの本体の実行の先頭で自動的に作成されます。

代入先として式を使うと、クラススコープもしくはモジュールスコープの場合、注釈は評価されますが、格納されません。

関数スコープで名前に注釈が付いていた場合は、その名前はその関数スコープでローカルなものになります。注釈は絶対に評価されず、関数スコープにも格納されません。

If the right hand side is present, an annotated assignment performs the actual assignment before evaluating annotations (where applicable). If the right hand side is not present for an expression target, then the interpreter evaluates the target except for the last __setitem__() or __setattr__() call.

参考

PEP 526 [https://peps.python.org/pep-0526/] - Syntax for Variable Annotations

(クラス変数やインスタンス変数を含んだ) 変数の型注釈を付ける、コメントで表現するのではない文法の追加提案。

PEP 484 [https://peps.python.org/pep-0484/] - Type hints

typing モジュールを追加し、静的解析ツールや IDE で使える型アノテーションの標準的な文法を提供する提案。

バージョン 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.

7.3. assert 文

assert 文は、プログラム内にデバッグ用アサーション (debugging assertion) を仕掛けるための便利な方法です:

assert_stmt ::=  "assert" expression ["," expression]

単純な形式 assert expression は

if __debug__:
    if not expression: raise AssertionError

と等価です。拡張形式 assert expression1, expression2 は、これと等価です

if __debug__:
    if not expression1: raise AssertionError(expression2)

上記の等価関係は、 __debug__ と AssertionError が、同名の組み込み変数を参照しているという前提の上に成り立っています。現在の実装では、組み込み変数 __debug__ は通常の状況では True であり、最適化が要求された場合（コマンドラインオプション -O）は False です。現状のコード生成器は、コンパイル時に最適化が要求されていると assert 文のコードを一切出力しません。実行に失敗した式のソースコードをエラーメッセージ内に入れる必要はありません; コードはスタックトレース内で表示されます。

__debug__ への代入は不正な操作です。組み込み変数の値は、インタプリタが開始するときに決定されます。

7.4. pass 文

pass_stmt ::=  "pass"

pass はヌル操作 (null operation) です --- pass が実行されても、何も起きません。 pass は、構文法的には文が必要だが、コードとしては何も実行したくない場合のプレースホルダとして有用です。例えば:

def f(arg): pass    # a function that does nothing (yet)

class C: pass       # a class with no methods (yet)

7.5. del 文

del_stmt ::=  "del" target_list

オブジェクトの削除 (deletion) は、代入の定義と非常に似た方法で再帰的に定義されています。ここでは完全な詳細は記述せず、いくつかのヒントを述べるにとどめます。

ターゲットリストに対する削除は、各々のターゲットを左から右へと順に再帰的に削除します。

名前の削除は、ローカルまたはグローバル名前空間からその名前の束縛を取り除きます。どちらの名前空間かは、名前が同じコードブロック内の global 文で宣言されているかどうかによります。名前が未束縛 (unbound) なら、 NameError 例外が送出されます。

属性参照、添字表記、およびスライスの削除操作は、対象となる一次語オブジェクトに渡されます; スライスの削除は一般的には適切な型の空のスライスを代入するのと等価です (が、この仕様自体もスライスされるオブジェクトで決定されています)。

バージョン 3.2 で変更: 以前は、ある名前がネストしたブロックの自由変数として表れる場合は、ローカル名前空間からその名前を削除することは不正な処理でした。

7.6. return 文

return_stmt ::=  "return" [expression_list]

return は、関数定義内で構文法的にネストして現れますが、ネストしたクラス定義内には現れません。

式リストがある場合、リストが値評価されます。それ以外の場合は None で置き換えられます。

return を使うと、式リスト (または None) を戻り値として、現在の関数呼び出しから抜け出します。

return によって、 finally 節をともなう try 文の外に処理が引き渡されると、実際に関数から抜ける前に finally 節が実行されます。

ジェネレータ関数では、 return 文はジェネレータの終わりを示し、 StopIteration 例外を送出させます。返された値は (あれば)、 StopIteration を構成する引数に使われ、 StopIteration.value 属性になります。

非同期ジェネレータ関数では、引数無しの return 文は非同期ジェネレータの終わりを示し、 StopAsyncIteration を送出させます。引数ありの return 文は、非同期ジェネレータ関数では文法エラーです。

7.7. yield 文

yield_stmt ::=  yield_expression

yield 文は意味的に yield 式 と同じです。yield 文を用いると yield 式文で必要な括弧を省略することが出来ます。例えば、yield 文

yield <expr>
yield from <expr>

は以下の yield 式文と等価です

(yield <expr>)
(yield from <expr>)

yield 式及び文は generator を定義するときに、その本体内でのみ使うことが出来ます。関数定義内で yield を使用することで、その定義は通常の関数でなくジェネレータ関数になります。

yield の意味の完全な説明は、 Yield 式 節を参照してください。

7.8. raise 文

raise_stmt ::=  "raise" [expression ["from" expression]]

If no expressions are present, 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 RuntimeError exception is raised indicating that this is an error.

そうでなければ、 raise は最初の式を、例外オブジェクトとして評価します。これは、 BaseException のサブクラスまたはインスタンスでなければなりません。クラスなら、例外インスタンスが必要なとき、クラスを無引数でインスタンス化することで得られます。

例外の 型 は例外インスタンスのクラスで、 値 はインスタンスそのものです。

A traceback object is normally created automatically when an exception is raised and attached to it as the __traceback__ attribute. You can create an exception and set your own traceback in one step using the with_traceback() exception method (which returns the same exception instance, with its traceback set to its argument), like so:

raise Exception("foo occurred").with_traceback(tracebackobj)

The 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 __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 __cause__ attribute. If the raised exception is not handled, both exceptions will be printed:

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

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 except or finally clause, or a with statement, is used. The previous exception is then attached as the new exception's __context__ attribute:

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

Exception chaining can be explicitly suppressed by specifying None in the from clause:

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

例外に関する追加情報は 例外 節にあります。また、例外処理に関する情報は try 文 節にあります。

バージョン 3.3 で変更: None が raise X from Y の Y として使えるようになりました。

Added the __suppress_context__ attribute to suppress automatic display of the exception context.

バージョン 3.11 で変更: If the traceback of the active exception is modified in an except clause, a subsequent 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.

7.9. break 文

break_stmt ::=  "break"

break 文は、構文としては for ループや while ループの内側でのみ出現することができますが、ループ内の関数定義やクラス定義の内側には出現できません。

break 文は、文を囲う最も内側のループを終了させ、ループにオプションの else 節がある場合にはそれをスキップします。

for ループを break によって終了すると、ループ制御ターゲットはその時の値を保持します。

break が finally 節を伴う try 文の外側に処理を渡す際には、ループを実際に抜ける前にその finally 節が実行されます。

7.10. continue 文

continue_stmt ::=  "continue"

continue 文は for ループや while ループ内のネストで構文法的にのみ現れますが、ループ内の関数定義やクラス定義の中には現れません。 continue 文は、文を囲う最も内側のループの次の周期に処理を継続します。

continue が finally 句を持った try 文を抜けるとき、その finally 句が次のループサイクルを始める前に実行されます。

7.11. import 文

import_stmt     ::=  "import" module ["as" identifier] ("," module ["as" identifier])*
                     | "from" relative_module "import" identifier ["as" identifier]
                     ("," identifier ["as" identifier])*
                     | "from" relative_module "import" "(" identifier ["as" identifier]
                     ("," identifier ["as" identifier])* [","] ")"
                     | "from" relative_module "import" "*"
module          ::=  (identifier ".")* identifier
relative_module ::=  "."* module | "."+

(from 節が無い) 基本の import 文は 2 つのステップで実行されます:

モジュールを見付け出し、必要であればロードし初期化する

import 文が表れるスコープのローカル名前空間で名前を定義する。

文が (カンマで区切られた) 複数の節を含んでいるときは、ちょうどその節が個別の import 文に分割されたかのように、2つのステップが節ごとに個別に実行されます。

モジュールを見付け、ロードする 1 つ目のステップの詳細については、 インポートシステム の節により詳しく書かれています。そこでは、インポートシステムの動作をカスタマイズするのに使える全てのフックの仕組みだけでなく、様々な種類のインポートできるパッケージとモジュールについても解説されています。このステップが失敗するということは、おそらくモジュールが見付からないか、 あるいは モジュールにあるコードの実行を含め、モジュールの初期化の途中でエラーが起きるかのどちらかが起きていることに注意してください。

要求したモジュールが無事に取得できた場合、次の 3 つのうちの 1 つの方法でローカル名前空間で使えるようになります:

モジュール名の後に as が続いていた場合は、 as の後ろの名前を直接、インポートされたモジュールが束縛します。

他の名前が指定されておらず、インポートされているモジュールが最上位のモジュールだった場合、そのモジュール名がインポートされたモジュールへの参照として、ローカル名前空間で束縛されます

インポートされているモジュールが最上位のモジュール でない 場合、モジュールを含む最上位のパッケージ名が、そのパッケージへの参照として、ローカル名前空間で束縛されます。インポートされたモジュールには、直接ではなく完全修飾名を使ってアクセスしなければなりません

from 形式ではもう少し複雑な手順を踏みます:

from 節で指定されたモジュールを見付け出し、必要であればロードし初期化する;

import 節で指定されたそれぞれの識別子に対し以下の処理を行う:

インポートされたモジュールがその識別子名の属性を持っているかを確認する

その識別子名の属性を持っていなかった場合は、その識別子名でサブモジュールのインポートを試み、インポートされたモジュールにその属性があるか再度確認する

属性が見付からない場合は、 ImportError を送出する。

属性が見付かった場合は、 as 節があるならそこの名前、そうでないなら属性名を使って、その値への参照がローカル名前空間に保存される

例:

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

識別子のリストが星 ('*') に置き換わっている場合は、モジュールで定義されている公開された全ての名前が、 import 文がいるスコープのローカル名前空間に束縛されます。

モジュールで定義される 公開された名前 は、モジュールの名前空間にある __all__ という名前の変数を調べることで決定されます; その変数が定義されている場合は、それはモジュールで定義されたかインポートされた名前からなる、文字列のシーケンスでなければいけません。__all__ で列挙された名前は、全て公開されていると見なされ、存在することが要求されます。__all__ が定義されていない場合、公開された名前とは、モジュールの名前空間で見付かった、アンダースコア文字 ('_') で始まらない全ての名前のことです。__all__ は全ての公開 API を含むべきです。これは API の一部でないもの (そのモジュールでインポートされ使われているライブラリモジュールなど) をうっかり外部に公開してしまわないための仕組みです。

インポートのワイルドカード形式 --- from module import * --- は、モジュールレベルでのみ許されます。クラスや関数定義でこの形式を使おうとすると、 SyntaxError が送出されます。

インポートするモジュールを指定するとき、そのモジュールの絶対名 (absolute name) を指定する必要はありません。モジュールやパッケージが他のパッケージに含まれている場合、共通のトップパッケージからそのパッケージ名を記述することなく相対インポートすることができます。 from の後に指定されるモジュールやパッケージの先頭に複数個のドットを付けることで、正確な名前を指定することなしに現在のパッケージ階層からいくつ上の階層へ行くかを指定することができます。先頭のドットが 1 つの場合、 import をおこなっているモジュールが存在する現在のパッケージを示します。 3 つのドットは 2 つ上のレベルを示します。なので、 pkg パッケージの中のモジュールで from . import mod を実行すると、 pkg.mod をインポートすることになります。 pkg.subpkg1 の中から from ..subpkg2 import mod を実行すると、 pkg.subpkg2.mod をインポートします。相対インポートの仕様は Package Relative Imports の節に含まれています。

どのモジュールがロードされるべきかを動的に決めたいアプリケーションのために、組み込み関数 importlib.import_module() が提供されています。

Raises an auditing event import with arguments module, filename, sys.path, sys.meta_path, sys.path_hooks.

7.11.1. future 文 (future statement)

future 文 は、将来の特定の新たな機能が標準化された Python のリリースで利用可能になるような構文や意味付けを使って、特定のモジュールをコンパイルさせるための、コンパイラに対する指示句 (directive) です。

future 文は互換性のない変更がされた将来の Python のバージョンに容易に移行するためのものです。future 文によって新機能が標準となるリリースの前にそれをモジュール単位で使用することが出来ます。

future_stmt ::=  "from" "__future__" "import" feature ["as" identifier]
                 ("," feature ["as" identifier])*
                 | "from" "__future__" "import" "(" feature ["as" identifier]
                 ("," feature ["as" identifier])* [","] ")"
feature     ::=  identifier

future 文は、モジュールの先頭周辺に書かなければなりません。 future 文の前に書いてよい内容は以下です :

モジュールのドキュメンテーション文字列 ( あれば )

コメント ,

空行 ,

その他の future 文。

future 文を使う必要がある唯一の機能は annotations です (PEP 563 [https://peps.python.org/pep-0563/] を参照してください)。

future 文で有効にできる歴史的な機能は、今でも Python 3 が認識します。そのリストは absolute_import, division, generator_stop, generators, unicode_literals, print_function, nested_scopes, with_statement です。これらは既に全てが有効になっていて、後方互換性のためだけに残されているため、冗長なだけです。

future 文は、コンパイル時に特別なやり方で認識され、扱われます: 言語の中核をなす構文構成 (construct) に対する意味付けが変更されている場合、変更部分はしばしば異なるコードを生成することで実現されています。新たな機能によって、(新たな予約語のような) 互換性のない新たな構文が取り入れられることさえあります。この場合、コンパイラはモジュールを別のやりかたで解析する必要があるかもしれません。こうしたコード生成に関する決定は、実行時まで先延ばしすることはできません。

これまでの全てのリリースにおいて、コンパイラはどの機能が定義済みかを知っており、 future 文に未知の機能が含まれている場合にはコンパイル時エラーを送出します。

future 文の実行時における直接的な意味付けは、 import 文と同じです。標準モジュール __future__ があり、これについては後で述べます。 __future__ は、 future 文が実行される際に通常の方法で import されます。

future 文の実行時における特別な意味付けは、 future 文で有効化される特定の機能によって変わります。

以下の文には、何ら特殊な意味はないので注意してください:

import __future__ [as name]

これは future 文ではありません; この文は通常の import 文であり、その他の特殊な意味付けや構文的な制限はありません。

Code compiled by calls to the built-in functions exec() and compile() that occur in a module 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 compile() --- see the documentation of that function for details.

対話的インタプリタのプロンプトでタイプ入力した future 文は、その後のインタプリタセッション中で有効になります。インタプリタを -i オプションで起動して実行すべきスクリプト名を渡し、スクリプト中に future 文を入れておくと、新たな機能はスクリプトが実行された後に開始する対話セッションで有効になります。

参考

PEP 236 [https://peps.python.org/pep-0236/] - Back to the __future__

__future__ 機構の原案

7.12. global 文

global_stmt ::=  "global" identifier ("," identifier)*

global 文は、現在のコードブロック全体で維持される宣言文です。 global 文は、列挙した識別子をグローバル変数として解釈するよう指定することを意味します。 global を使わずにグローバル変数に代入を行うことは不可能ですが、自由変数を使えばその変数をグローバルであると宣言せずにグローバル変数を参照することができます。

global 文で列挙する名前は、同じコードブロック中で、プログラムテキスト上 global 文より前に使ってはなりません。

global 文で列挙する名前は、仮引数として、または with 文や except 節のターゲットとして定義されたり、for のターゲットリスト、class 定義、関数定義、import 文、変数アノテーションの中で定義されたりしてはなりません。

CPython 実装の詳細: 現在の実装では、これらの制限のうち幾つかについては強制していませんが、プログラムでこの緩和された仕様を乱用すべきではありません。将来の実装では、この制限を強制したり、暗黙のうちにプログラムの意味付けを変更したりする可能性があります。

プログラマのための注意点: global はパーザに対する指示句 (directive) です。この指示句は、 global 文と同時に読み込まれたコードに対してのみ適用されます。特に、組み込みの exec() 関数内に入っている global 文は、関数の呼び出しを 含んでいる コードブロック内に効果を及ぼすことはなく、そのような文字列に含まれているコードは、関数の呼び出しを含むコード内の global 文に影響を受けません。同様のことが、関数 eval() および compile() にも当てはまります。

7.13. nonlocal 文

nonlocal_stmt ::=  "nonlocal" identifier ("," identifier)*

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 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 SyntaxError is raised.

The nonlocal statement applies to the entire scope of a function or class body. A SyntaxError is raised if a variable is used or assigned to prior to its nonlocal declaration in the scope.

参考

PEP 3104 [https://peps.python.org/pep-3104/] - Access to Names in Outer Scopes

nonlocal 文の詳細。

Programmer's note: nonlocal is a directive to the parser and applies only to code parsed along with it. See the note for the global statement.

7.14. The type statement

type_stmt ::=  'type' identifier [type_params] "=" expression

The type statement declares a type alias, which is an instance of typing.TypeAliasType.

For example, the following statement creates a type alias:

type Point = tuple[float, float]

This code is roughly equivalent to:

annotation-def VALUE_OF_Point():
    return tuple[float, float]
Point = typing.TypeAliasType("Point", VALUE_OF_Point())

annotation-def indicates an 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 __value__ attribute (see 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 type parameter list after the name. See Generic type aliases for more.

type is a soft keyword.

Added in version 3.12.

参考

PEP 695 [https://peps.python.org/pep-0695/] - Type Parameter Syntax

Introduced the type statement and syntax for generic classes and functions.

8. 複合文 (compound statement)

複合文には、他の文 (のグループ) が入ります; 複合文は、中に入っている他の文の実行の制御に何らかのやり方で影響を及ぼします。一般的には、複合文は複数行にまたがって書かれますが、全部の文を一行に連ねた単純な書き方もあります。

if 、 while 、および for 文は、伝統的な制御フロー構成を実現します。 try は例外処理および/または一連の文に対するクリーンアップコードを指定します。それに対して、 with 文はコードのかたまりの前後でコードの初期化と終了処理を実行できるようにします。関数とクラス定義もまた、構文的には複合文です。

複合文は、一つ以上の '節 (clause)' からなります。節は、ヘッダと 'スイート (suite)' からなります。一つの複合文を成す各節のヘッダは、全て同じインデントレベルに置かれます。各節のヘッダは一意に識別するキーワードで始まり、コロンで終わります。スイートは、節によって制御される文の集まりです。スイートは、ヘッダがある行のコロンの後にセミコロンで区切って置かれた一つ以上の単純文、または、ヘッダに続く行で一つ多くインデントされた文の集まりです。後者の形式のスイートに限り、さらに複合文をネストできます; 以下の文は、 else 節がどちらの if 節に属するかがはっきりしないなどの理由から不正になります:

if test1: if test2: print(x)

また、このコンテキスト中では、セミコロンによる結合はコロンより強いです。従って、以下の例では、 print() の呼び出しはは全て実行されるか、全く実行されないかのどちらかです:

if x < y < z: print(x); print(y); print(z)

まとめると、以下のようになります:

compound_stmt ::=  if_stmt
                   | while_stmt
                   | for_stmt
                   | try_stmt
                   | with_stmt
                   | match_stmt
                   | funcdef
                   | classdef
                   | async_with_stmt
                   | async_for_stmt
                   | async_funcdef
suite         ::=  stmt_list NEWLINE | NEWLINE INDENT statement+ DEDENT
statement     ::=  stmt_list NEWLINE | compound_stmt
stmt_list     ::=  simple_stmt (";" simple_stmt)* [";"]

なお、文は常に NEWLINE か、その後に DEDENT が続いたもので終了します。また、オプションの継続節は必ず、文を開始できない予約語で始まるので、曖昧さは存在しません。 (Python では、 'ぶら下がり (dangling) else' 問題は、ネストされた if 文をインデントさせることで解決されます)。

以下の節における文法規則の記述方式は、明確さのために、各節を別々の行に書くようにしています。

8.1. if 文

if 文は、条件分岐を実行するために使われます:

if_stmt ::=  "if" assignment_expression ":" suite
             ("elif" assignment_expression ":" suite)*
             ["else" ":" suite]

if 文は、式を一つ一つ評価してゆき、真になるまで続けて、真になった節のスイートだけを選択します (真: true と偽: false の定義については、 ブール演算 (boolean operation) 節を参照してください); 次に、選択したスイートを実行します (そして、 if 文の他の部分は、実行や評価をされません)。全ての式が偽になった場合、 else 節があれば、そのスイートが実行されます。

8.2. while 文

while 文は、式の値が真である間、実行を繰り返すために使われます:

while_stmt ::=  "while" assignment_expression ":" suite
                ["else" ":" suite]

while 文は式を繰り返し真偽評価し、真であれば最初のスイートを実行します。式が偽であれば (最初から偽になっていることもありえます)、 else 節がある場合にはそれを実行し、ループを終了します。

最初のスイート内で break 文が実行されると、 else 節のスイートを実行することなくループを終了します。 continue 文が最初のスイート内で実行されると、スイート内にある残りの文の実行をスキップして、式の真偽評価に戻ります。

8.3. for 文

for 文は、シーケンス (文字列、タプルまたはリスト) や、その他の反復可能なオブジェクト (iterable object) 内の要素に渡って反復処理を行うために使われます:

for_stmt ::=  "for" target_list "in" starred_list ":" suite
              ["else" ":" suite]

starred_list 式は一度だけ評価され、評価結果として イテラブル オブジェクトを返す必要があります。そのイテラブルから イテレータ が作られます。まず、イテレータから生成される最初の要素が、通常の代入式のルールに従って target_list に代入され(代入文 (assignment statement) 節参照)、１つ目のスイート (suite) が実行されます。これが、イテレータから生成される各要素に対して繰り返されます。イテレータのすべての要素が処理されたあと、 else 節がもしあれば実行され、ループ処理が終了します。

最初のスイートの中で break 文が実行されると、 else 節のスイートを実行することなくループを終了します。 continue 文が最初のスイート内で実行されると、スイート内にある残りの文の実行をスキップして、次の要素の処理に移るか、これ以上次の要素が無い場合は else 節の処理に移ります。

for ループはターゲットリスト内の変数への代入を行います。これにより、for ループ内も含めて、それ以前の全ての代入は上書きされます:

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

ループが終了してもターゲットリスト内の名前は削除されませんが、イテラブルが空の場合には、ループでの代入は全く行われません。ヒント: 組み込み型 range() は、 整数の不変算術列を表します。例えば、 range(3) を反復すると0、1そして2の順に結果を返します。

バージョン 3.11 で変更: 式のリストの中でアスタリスク付きの式 (starred elements) を指定できるようになりました。

8.4. try 文

try 文は、ひとまとめの文に対して、例外処理および/またはクリーンアップコードを指定します:

try_stmt  ::=  try1_stmt | try2_stmt | try3_stmt
try1_stmt ::=  "try" ":" suite
               ("except" [expression ["as" identifier]] ":" suite)+
               ["else" ":" suite]
               ["finally" ":" suite]
try2_stmt ::=  "try" ":" suite
               ("except" "*" expression ["as" identifier] ":" suite)+
               ["else" ":" suite]
               ["finally" ":" suite]
try3_stmt ::=  "try" ":" suite
               "finally" ":" suite

例外に関するその他の情報は 例外 節にあります。また、 raise 文の使用による例外の生成に関する情報は、 raise 文 節にあります。

8.4.1. except 節

except 節は一つ以上の例外ハンドラを指定します。 try 節内で例外が起きなければ、どの例外ハンドラも実行されません。 try スイート内で例外が発生すると、例外ハンドラの検索が開始されます。この検索では、except 節を逐次、発生した例外に対応するまで調べます。式を伴わない except 節を使うなら、最後に書かなければならず、これは全ての例外に対応します。式を伴う except 節に対しては、その式が評価され、結果のオブジェクトが例外と "互換である (compatible)" 場合にその節が対応します。ある例外に対してオブジェクトが互換であるのは、そのオブジェクトが例外オブジェクトのクラスかその 非仮想基底クラス の場合、または例外オブジェクトのクラスかその非仮想基底クラスの要素が入ったタプルである場合です。

例外がどの except 節にも合致しなかった場合、現在のコードを囲うさらに外側、そして呼び出しスタックへと検索を続けます。 [1]

except 節のヘッダにある式を値評価するときに例外が発生すると、元々のハンドラ検索はキャンセルされ、新たな例外に対する例外ハンドラの検索を現在の except 節の外側のコードや呼び出しスタックに対して行います (try 文全体が例外を発行したかのように扱われます)。

対応する except 節が見つかると、except 節のスイートが実行されます。その際、 as キーワードが except 節に存在すれば、その後で指定されているターゲットに例外が代入されます。全ての except 節は実行可能なブロックを持っていなければなりません。このブロックの末尾に到達すると、通常は try 文全体の直後から実行を継続します。(このことは、ネストされた二つの例外ハンドラが同じ例外に対して存在し、内側のハンドラ内の try 節で例外が発生した場合、外側のハンドラはその例外を処理しないことを意味します。)

例外が as target を使って代入されたとき、それは except 節の終わりに消去されます。これはちょうど、以下のコード:

except E as N:
    foo

が、以下のコードに翻訳されたかのようなものです:

except E as N:
    try:
        foo
    finally:
        del N

よって、例外を except 節以降で参照できるようにするためには、別の名前に代入されなければなりません。例外が削除されるのは、トレースバックが付与されると、そのスタックフレームと循環参照を形作り、次のガベージ収集までそのフレーム内のすべての局所変数を生存させてしまうからです。

except 節のスイートが実行される前に、例外が sys モジュールに格納されます。 except 節の中では、 sys.exception() を呼び出す事によってこの例外にアクセスすることができます。例外ハンドラを抜けると、 sys モジュールに格納されている例外の値が、一つ前の値に戻ります:

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

8.4.2. except* 節

The except* clause(s) are used for handling ExceptionGroups. The exception type for matching is interpreted as in the case of except, but in the case of exception groups we can have partial matches when the type matches some of the exceptions in the group. This means that multiple except* clauses can execute, each handling part of the exception group. Each clause executes at most once and handles an exception group of all matching exceptions. Each exception in the group is handled by at most one except* clause, the first that matches it.

>>> try:
...     raise ExceptionGroup("eg",
...         [ValueError(1), TypeError(2), OSError(3), OSError(4)])
... except* TypeError as e:
...     print(f'caught {type(e)} with nested {e.exceptions}')
... except* OSError as e:
...     print(f'caught {type(e)} with nested {e.exceptions}')
...
caught <class 'ExceptionGroup'> with nested (TypeError(2),)
caught <class 'ExceptionGroup'> with nested (OSError(3), OSError(4))
  + Exception Group Traceback (most recent call last):
  |   File "<stdin>", line 2, in <module>
  | ExceptionGroup: eg
  +-+---------------- 1 ----------------
    | ValueError: 1
    +------------------------------------

Any remaining exceptions that were not handled by any except* clause are re-raised at the end, along with all exceptions that were raised from within the except* clauses. If this list contains more than one exception to reraise, they are combined into an exception group.

If the raised exception is not an exception group and its type matches one of the except* clauses, it is caught and wrapped by an exception group with an empty message string.

>>> try:
...     raise BlockingIOError
... except* BlockingIOError as e:
...     print(repr(e))
...
ExceptionGroup('', (BlockingIOError()))

An except* clause must have a matching type, and this type cannot be a subclass of BaseExceptionGroup. It is not possible to mix except and except* in the same try. break, continue and return cannot appear in an except* clause.

8.4.3. else 節

オプションの else 節は、コントロールフローが try スイートを抜け、例外が送出されず、 return 文、 continue 文、 break 文のいずれもが実行されなかった場合に実行されます。 else 節で起きた例外は、手前にある except 節では処理されません。

8.4.4. finally 節

finally 節がある場合は、 '後始末' の対処を指定します。まず except 節や else 節を含め、 try 節が実行されます。それらの節の中で例外が起き、その例外が処理されていない場合には、例外は一時的に保存されます。次に finally 節が実行されます。保存された例外があった場合は、 finally 節の末尾で再送出されます。 finally 節で別の例外が送出される場合は、保存されていた例外は新しい例外のコンテキストとして設定されます。 finally 節で return 文、 break 文あるいは continue 文を実行した場合は、保存された例外は破棄されます:

>>> def f():
...     try:
...         1/0
...     finally:
...         return 42
...
>>> f()
42

finally 節を実行している間は、プログラムからは例外情報は利用できません。

try...finally 文の try スイート内で return 、 break 、または continue 文が実行された場合、 finally 節も、この文を '抜け出る途中に' 実行されます。

関数の返り値は最後に実行された return 文によって決まります。 finally 節は必ず実行されるため、finally 節で実行された return 文は常に最後に実行されることになります:

>>> def foo():
...     try:
...         return 'try'
...     finally:
...         return 'finally'
...
>>> foo()
'finally'

バージョン 3.8 で変更: Python3.8 以前では、実装上の問題により finally 節での continue 文は不正でした。

8.5. with 文

with 文は、ブロックの実行を、コンテキストマネージャによって定義されたメソッドでラップするために使われます (with文とコンテキストマネージャ セクションを参照してください)。これにより、よくある try...except...finally 利用パターンをカプセル化して便利に再利用することができます。

with_stmt          ::=  "with" ( "(" with_stmt_contents ","? ")" | with_stmt_contents ) ":" suite
with_stmt_contents ::=  with_item ("," with_item)*
with_item          ::=  expression ["as" target]

一つの "要素" を持つ with 文の実行は以下のように進行します:

コンテキスト式 (with_item で与えられた式) を評価することで、コンテキストマネージャを取得します。

コンテキストマネージャの __enter__() メソッドが、後で使うためにロードされます。

コンテキストマネージャの __exit__() メソッドが、後で使うためにロードされます。

コンテキストマネージャの __enter__() メソッドが呼ばれます。

with 文にターゲットが含まれていたら、それに __enter__() からの戻り値が代入されます。

注釈

with 文は、 __enter__() メソッドがエラーなく終了した場合には __exit__() が常に呼ばれることを保証します。ですので、もしターゲットリストへの代入中にエラーが発生した場合には、これはそのスイートの中で発生したエラーと同じように扱われます。以下のステップ 7 を参照してください。

スイートが実行されます。

コンテキストマネージャの __exit__() メソッドが呼ばれます。スイートが例外によって終了されたのなら、その例外の型、値、トレースバックが __exit__() に引数として渡されます。そうでなければ、 3 つの None 引数が与えられます。

スイートが例外により終了され、 __exit__() メソッドからの戻り値が偽（false）ならば、例外が再送出されます。この戻り値が真（true）ならば例外は抑制され、実行は with 文の次の文から続きます。

もしそのスイートが例外でない何らかの理由で終了した場合、その __exit__() からの戻り値は無視されて、実行は発生した終了の種類に応じた通常の位置から継続します。

以下のコード:

with EXPRESSION as TARGET:
    SUITE

これは次と等価です:

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)

複数の要素があるとき、コンテキストマネージャは複数の with 文がネストされたかのように進行します:

with A() as a, B() as b:
    SUITE

これは次と等価です:

with A() as a:
    with B() as b:
        SUITE

括弧で囲むことにより、複数のコンテキストマネージャを複数行に渡って書くことができます。例:

with (
    A() as a,
    B() as b,
):
    SUITE

バージョン 3.1 で変更: 複数のコンテキスト式をサポートしました。

バージョン 3.10 で変更: 括弧で囲むことで、文を複数行に分割して書けるようになりました。

参考

PEP 343 [https://peps.python.org/pep-0343/] - "with" ステートメント

Python の with 文の仕様、背景、および例が記載されています。

8.6. match 文

Added in version 3.10.

match 文はパターンマッチングを行う目的で使われます。構文:

match_stmt   ::=  'match' subject_expr ":" NEWLINE INDENT case_block+ DEDENT
subject_expr ::=  star_named_expression "," star_named_expressions?
                  | named_expression
case_block   ::=  'case' patterns [guard] ":" block

注釈

このセクションでは、一重引用符で囲まれているものは ソフトキーワード を表します。

パターンマッチングは、パターン (case の後ろ) とマッチング対象の値 (match の後ろ)を入力とします。パターン (サブパターンを含みうる) は、マッチング対象の値に対して、マッチするかどうかの判定が行われます。結果として次のことが起こります:

マッチ成功、もしくはマッチ失敗 (パターン成功・失敗とも呼ばれます)。

マッチした値の名前への束縛。必要な条件は後述します。

match と case キーワードは ソフトキーワード です。

参考

PEP 634 [https://peps.python.org/pep-0634/] -- 構造的パターンマッチ: 仕様

PEP 636 [https://peps.python.org/pep-0636/] -- 構造的パターンマッチ: チュートリアル

8.6.1. 概要

match 文の論理的な動作の流れの概要は次の通りです:

サブジェクト式 subject_expr が評価され、サブジェクト値が得られます。サブジェクト式がコンマを含む場合、 通常のルール に従ってタプルが作成されます。

case_block 内の各パターンに対して、サブジェクト値がマッチするかどうかをチェックします。マッチ成功・失敗の具体的なルールは後述します。マッチングのチェックにより、パターン内の名前の一部あるいはすべてに値が束縛されます。具体的な束縛ルールはパターンの種類によって異なるため、後述します。マッチが成功したパターンの中で束縛された名前は、そのパターンのブロック内だけでなく、 match 文の後でも使用することができます。

注釈

パターンマッチが全体として失敗しても、その中に含まれるサブパターンが成功する可能性があります。失敗したマッチで発生する名前束縛を前提としたコードを書かないように気をつけてください。逆に、マッチが失敗したあとで変数の値が変わっていないというのも前提にしないでください。実際どういう振る舞いになるかは Python の実装依存であり、実装間で異なる可能性があります。色々な実装が最適化を行えるよう、意図的に実装依存としています。

パターンが成功した場合、該当のガードが (もしあれば) 評価されます。この場合、パターン内の名前がすべて束縛されていることが保証されています。

ガードの評価値が真であるか、もしくはガードがなければ、 case_block 内の block が実行されます。

そうでなければ、次の case_block に対して再び上記の処理が実行されます。

これ以上 case block が存在しない場合は、 match 文が終了します。

注釈

基本的に、 match 文のパターンが評価されるという前提でコードを書くべきではありません。インタープリタの実装によっては、結果をキャッシュするなどの最適化を行い、評価をスキップする可能性があります。

簡単な match 文の例:

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

この例では、 if flag がガードです。ガードについては次のセクションを参照してください。

8.6.2. ガード

guard ::=  "if" named_expression

guard (case 一部として現れる) が成功してはじめて、その case ブロックのコードが実行されます。ガードは if の後に式を書く形で表記されます。

guard 付きの case ブロックの処理の流れは次のとおりです:

case ブロックのパターンが成功するかどうかをチェックする。失敗した場合は、 guard は評価されず、次の case ブロックのチェックに進む。

パターンが成功した場合は、 guard の評価が行われます。

guard 条件の評価値が真である場合、該当の case ブロックが選択されます。

guard 条件の評価値が偽の場合、該当の case ブロックは選択されません。

guard の評価中に例外が送出された場合は、その例外がそのまま送出されます。

ガードは式であるため、副作用を起こすことができます。ガードの評価は、最初の case ブロックから順に、パターンが失敗した case ブロックは飛ばしつつ、一つづつ評価されなければいけません (つまり、ガードの評価は書かれている順番で実行される必要があります)。また、case ブロックが選択された時点で、ガードの評価をそれ以上行ってはいけません。

8.6.3. 論駁不可能なケースブロック

論駁不可能なケースブロックとは、何にでもマッチするケースブロックのことです。 match 文の中で、論駁不可能なケースブロックは最大一つまで、かつ最後に位置する必要があります。

ケースブロックが論駁不可能であるためには、ガードがなく、パターンが論駁不可能である必要があります。パターンが論駁不可能であるためには、その文法上の構造のみから、それが常に成功することが証明できる必要があります。論駁不可能なパターンは以下のようなもののみです:

左辺が論駁不可能である AS パターン

含まれるパターンのうち少なくとも一つが論駁不可能である OR パターン

キャプチャパターン

ワイルドカードパターン

括弧で囲われた、論駁不可能なパターン

8.6.4. パターン

注釈

このセクションでは、通常のEBNFを拡張した文法記法を使用します。

SEP.RULE+ という表記は RULE (SEP RULE)* の略です。

!RULE は否定先読みの条件を表します。

patterns のトップレベルの構文は以下の通りです:

patterns       ::=  open_sequence_pattern | pattern
pattern        ::=  as_pattern | or_pattern
closed_pattern ::=  | literal_pattern
                    | capture_pattern
                    | wildcard_pattern
                    | value_pattern
                    | group_pattern
                    | sequence_pattern
                    | mapping_pattern
                    | class_pattern

以下の説明では分かりやすさのため、パターンの振る舞いを簡単に言い表した場合の説明を「簡単に言うと」の後に書いています (そのほとんどは、Raymond Hettinger 氏のドキュメントに影響を受けてのものです)。ただし、これはあくまで理解を助けるためのであり、内部的な実装を必ずしも反映したものでは ありません 。また、使用可能なすべてのパターン構造を網羅しているわけではありません。

8.6.4.1. OR パターン

OR パターンは、縦線 | で区切られた複数のパターンからなります。構文:

or_pattern ::=  "|".closed_pattern+

最後のサブパターン以外、 論駁不可能 であってはいけません。また、曖昧さ回避のため、各サブパターンが束縛する名前の組み合わせは、すべて同じである必要があります。

OR パターンでは、サブジェクト値に対して順に各サブパターンのマッチングが行われます。マッチが成功するとそこで終了し、この OR パターンは成功したとみなされます。一方、どのサブパターンも成功しなければ、この OR パターンは失敗したことになります。

簡単に言うと、 P1 | P2 | ... というパターンは P1 をマッチしようとし、失敗すれば P2 を試します。いずれかのパターンがマッチが成功すれば直ちに成功となり、それ以外の場合は失敗となります。

8.6.4.2. AS パターン

AS パターンはサブジェクト値に対して、 as キーワードの左側にある OR パターンをマッチさせます。構文:

as_pattern ::=  or_pattern "as" capture_pattern

OR パターンが失敗すれば、この AS パターンは失敗となります。成功すれば、サブジェクト値が as キーワードの右側の名前に束縛され、この AS パターンは成功となります。 capture_pattern として _ を指定することはできません。

簡単に言うと、 P as NAME は P をマッチさせ、成功した場合に NAME = <subject> の代入を行います。

8.6.4.3. リテラルパターン

リテラルパターンは、一部を除く Python の リテラル に対応します。構文:

literal_pattern ::=  signed_number
                     | signed_number "+" NUMBER
                     | signed_number "-" NUMBER
                     | strings
                     | "None"
                     | "True"
                     | "False"
                     | signed_number: NUMBER | "-" NUMBER

strings というルールと NUMBER というトークンは Python の文法仕様 で定義されています。クォート３つで囲われた文字列や raw 文字列、 raw バイト列も使用可能です。 f-strings は使用できません。

signed_number '+' NUMBER と signed_number '-' NUMBER という構文は 複素数 を表現するためのものです。そのため、左側には実数、右側には虚数を書く必要があります。例: 3 + 4j 。

簡単に言うと、 LITERAL は <subject> == LITERAL であるときのみ成功するパターンです。シングルトンである None と True 、 False は is 演算子を使って比較されます。

8.6.4.4. キャプチャパターン

キャプチャパターンは、サブジェクト値を名前に束縛します。構文:

capture_pattern ::=  !'_' NAME

アンダースコア一文字の _ はキャプチャパターンではありません (!'_' が表しているのはこの条件です) 。 wildcard_pattern として扱われます。

パターン一つの中で、一つの名前は一度しか束縛することができません。例えば、 case x, x: ... は間違いですが、 case [x] | x: ... は正しいです。

キャプチャパターンは常に成功します。束縛された名前のスコープは、 PEP 572 [https://peps.python.org/pep-0572/] で確立された代入式演算子のスコープルールと同じです。すなわち、当てはまる global 文 か nonlocal 文がない限り、その局所変数のスコープは、該当の match 文を包む最も内側の関数となります。

簡単に言うと、 NAME は常に成功し、 NAME = <subject> の代入が行われます。

8.6.4.5. ワイルドカードパターン

ワイルドカードパターンは常に成功 (何に対してもマッチする) し、名前の束縛はしません。構文:

wildcard_pattern ::=  '_'

_ は、パターンの中で使用された場合は常に ソフトキーワード です。しかし、パターンの中でない場合はソフトキーワードではありません。たとえサブジェクト式や guard 、 case ブロックの中でも、通常の変数となります。

簡単に言うと、 _ は常に成功します。

8.6.4.6. 値パターン

値パターンは Python で名前の付けられた値を表します。構文:

value_pattern ::=  attr
attr          ::=  name_or_attr "." NAME
name_or_attr  ::=  attr | NAME

ドットがついたこの名前は、Python 標準の 名前解決ルール によって解決されます。このパターンは、解決された値がサブジェクト値と等しい (比較演算子 == に基づく) ときに成功となります。

簡単に言うと、 NAME1.NAME2 は <subject> == NAME1.NAME2 であるときのみ成功します。

注釈

一つの match 文で同じ値が複数回出現する場合は、インタープリタが最初に解決された値をキャッシュし、名前解決を何度も行うことなく値を再利用する可能性があります。このキャッシュは、その match 文のその実行一回の間だけで再利用されます。

8.6.4.7. グループパターン

A group pattern allows users to add parentheses around patterns to emphasize the intended grouping. Otherwise, it has no additional syntax. Syntax:

group_pattern ::=  "(" pattern ")"

In simple terms (P) has the same effect as P.

8.6.4.8. シーケンスパターン

A sequence pattern contains several subpatterns to be matched against sequence elements. The syntax is similar to the unpacking of a list or tuple.

sequence_pattern       ::=  "[" [maybe_sequence_pattern] "]"
                            | "(" [open_sequence_pattern] ")"
open_sequence_pattern  ::=  maybe_star_pattern "," [maybe_sequence_pattern]
maybe_sequence_pattern ::=  ",".maybe_star_pattern+ ","?
maybe_star_pattern     ::=  star_pattern | pattern
star_pattern           ::=  "*" (capture_pattern | wildcard_pattern)

There is no difference if parentheses or square brackets are used for sequence patterns (i.e. (...) vs [...] ).

注釈

A single pattern enclosed in parentheses without a trailing comma (e.g. (3 | 4)) is a group pattern. While a single pattern enclosed in square brackets (e.g. [3 | 4]) is still a sequence pattern.

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:

If the subject value is not a sequence [2], the sequence pattern fails.

If the subject value is an instance of str, bytes or bytearray the sequence pattern fails.

The subsequent steps depend on whether the sequence pattern is fixed or variable-length.

If the sequence pattern is fixed-length:

If the length of the subject sequence is not equal to the number of subpatterns, the sequence pattern fails

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.

Otherwise, if the sequence pattern is variable-length:

If the length of the subject sequence is less than the number of non-star subpatterns, the sequence pattern fails.

The leading non-star subpatterns are matched to their corresponding items as for fixed-length sequences.

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.

Remaining non-star subpatterns are matched to their corresponding subject items, as for a fixed-length sequence.

注釈

The length of the subject sequence is obtained via len() (i.e. via the __len__() protocol). This length may be cached by the interpreter in a similar manner as value patterns.

In simple terms [P1, P2, P3, ... , P<N>] matches only if all the following happens:

<subject> がシーケンスかをチェックする

len(subject) == <N>

P1 matches <subject>[0] (note that this match can also bind names)

P2 matches <subject>[1] (note that this match can also bind names)

... and so on for the corresponding pattern/element.

8.6.4.9. マッピングパターン

A mapping pattern contains one or more key-value patterns. The syntax is similar to the construction of a dictionary. Syntax:

mapping_pattern     ::=  "{" [items_pattern] "}"
items_pattern       ::=  ",".key_value_pattern+ ","?
key_value_pattern   ::=  (literal_pattern | value_pattern) ":" pattern
                         | double_star_pattern
double_star_pattern ::=  "**" capture_pattern

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 SyntaxError. Two keys that otherwise have the same value will raise a ValueError at runtime.

The following is the logical flow for matching a mapping pattern against a subject value:

If the subject value is not a mapping [3],the mapping pattern fails.

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.

If duplicate keys are detected in the mapping pattern, the pattern is considered invalid. A SyntaxError is raised for duplicate literal values; or a ValueError for named keys of the same value.

注釈

Key-value pairs are matched using the two-argument form of the mapping subject's get() method. Matched key-value pairs must already be present in the mapping, and not created on-the-fly via __missing__() or __getitem__().

In simple terms {KEY1: P1, KEY2: P2, ... } matches only if all the following happens:

<subject> がマッピングかをチェックする

KEY1 in <subject>

P1 は <subject>[KEY1] にマッチする

... and so on for the corresponding KEY/pattern pair.

8.6.4.10. クラスパターン

A class pattern represents a class and its positional and keyword arguments (if any). Syntax:

class_pattern       ::=  name_or_attr "(" [pattern_arguments ","?] ")"
pattern_arguments   ::=  positional_patterns ["," keyword_patterns]
                         | keyword_patterns
positional_patterns ::=  ",".pattern+
keyword_patterns    ::=  ",".keyword_pattern+
keyword_pattern     ::=  NAME "=" pattern

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:

If name_or_attr is not an instance of the builtin type , raise TypeError.

If the subject value is not an instance of name_or_attr (tested via isinstance()), the class pattern fails.

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.

If this raises an exception other than AttributeError, the exception bubbles up.

If this raises AttributeError, the class pattern has failed.

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.

II. If all keyword patterns succeed, the class pattern succeeds.

If any positional patterns are present, they are converted to keyword patterns using the __match_args__ attribute on the class name_or_attr before matching:

I. The equivalent of getattr(cls, "__match_args__", ()) is called.

If this raises an exception, the exception bubbles up.

If the returned value is not a tuple, the conversion fails and TypeError is raised.

If there are more positional patterns than len(cls.__match_args__), TypeError is raised.

Otherwise, positional pattern i is converted to a keyword pattern using __match_args__[i] as the keyword. __match_args__[i] must be a string; if not TypeError is raised.

If there are duplicate keywords, TypeError is raised.

参考

クラスパターンマッチの位置引数のカスタマイズ

II. Once all positional patterns have been converted to keyword patterns,

the match proceeds as if there were only keyword patterns.

For the following built-in types the handling of positional subpatterns is different:

bool

bytearray

bytes

dict

float

frozenset

int

list

set

str

tuple

These classes accept a single positional argument, and the pattern there is matched against the whole object rather than an attribute. For example int(0|1) matches the value 0, but not the value 0.0.

In simple terms CLS(P1, attr=P2) matches only if the following happens:

isinstance(<subject>, CLS)

convert P1 to a keyword pattern using CLS.__match_args__

For each keyword argument attr=P2:

hasattr(<subject>, "attr")

P2 は <subject>.attr にマッチする

... and so on for the corresponding keyword argument/pattern pair.

参考

PEP 634 [https://peps.python.org/pep-0634/] -- 構造的パターンマッチ: 仕様

PEP 636 [https://peps.python.org/pep-0636/] -- 構造的パターンマッチ: チュートリアル

8.7. 関数定義

関数定義は、ユーザ定義関数オブジェクトを定義します (標準型の階層 節参照):

funcdef                   ::=  [decorators] "def" funcname [type_params] "(" [parameter_list] ")"
                               ["->" expression] ":" suite
decorators                ::=  decorator+
decorator                 ::=  "@" assignment_expression NEWLINE
parameter_list            ::=  defparameter ("," defparameter)* "," "/" ["," [parameter_list_no_posonly]]
                                 | parameter_list_no_posonly
parameter_list_no_posonly ::=  defparameter ("," defparameter)* ["," [parameter_list_starargs]]
                               | parameter_list_starargs
parameter_list_starargs   ::=  "*" [parameter] ("," defparameter)* ["," ["**" parameter [","]]]
                               | "**" parameter [","]
parameter                 ::=  identifier [":" expression]
defparameter              ::=  parameter ["=" expression]
funcname                  ::=  identifier

関数定義は実行可能な文です。関数定義を実行すると、現在のローカルな名前空間内で関数名を関数オブジェクト (関数の実行可能コードをくるむラッパー) に束縛します。この関数オブジェクトには、関数が呼び出された際に使われるグローバルな名前空間として、現在のグローバルな名前空間への参照が入っています。

関数定義は関数本体を実行しません; 関数本体は関数が呼び出された時にのみ実行されます。 [4]

関数定義は一つ以上の デコレータ 式でラップできます。デコレータ式は関数を定義するとき、関数定義の入っているスコープで評価されます。その結果は、関数オブジェクトを唯一の引数にとる呼び出し可能オブジェクトでなければなりません。関数オブジェクトの代わりに、返された値が関数名に束縛されます。複数のデコレータはネストして適用されます。例えば、以下のようなコード:

@f1(arg)
@f2
def func(): pass

は、だいたい次と等価です

def func(): pass
func = f1(arg)(f2(func))

ただし、前者のコードでは元々の関数を func という名前へ一時的に束縛することはない、というところを除きます。

バージョン 3.9 で変更: Functions may be decorated with any valid assignment_expression. Previously, the grammar was much more restrictive; see PEP 614 [https://peps.python.org/pep-0614/] for details.

A list of 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 __type_params__ attribute. See Generic functions for more.

バージョン 3.12 で変更: Type parameter lists are new in Python 3.12.

1 つ以上の 仮引数 が parameter = expression の形を取っているとき、関数は "デフォルト引数値" を持つと言います。デフォルト値を持つ仮引数では、呼び出し時にそれに対応する 実引数 は省略でき、その場合は仮引数のデフォルト値が使われます。ある引数がデフォルト値を持っている場合、それ以降 "*" が出てくるまでの引数は全てデフォルト値を持っていなければなりません -- これは文法定義では表現されていない構文的制限です。

デフォルト引数値は関数定義が実行されるときに左から右へ評価されます。 これは、デフォルト引数の式は関数が定義されるときにただ一度だけ評価され、同じ "計算済みの" 値が呼び出しのたびに使用されることを意味します。この仕様を理解しておくことは特に、デフォルト引数値がリストや辞書のようなミュータブルなオブジェクトであるときに重要です: 関数がこのオブジェクトを変更 (例えばリストに要素を追加) すると、このデフォルト引数値が変更の影響を受けてしまします。一般には、これは意図しない動作です。このような動作を避けるには、デフォルト値として None を使い、この値を関数本体の中で明示的にテストします。例えば以下のようにします:

def whats_on_the_telly(penguin=None):
    if penguin is None:
        penguin = []
    penguin.append("property of the zoo")
    return penguin

関数呼び出しの意味付けに関する詳細は、 呼び出し (call) 節で述べられています。関数呼び出しを行うと、パラメタリストに記述された全てのパラメタに、位置引数、キーワード引数、デフォルト値のいずれかから値が代入されます。 "*identifier" 形式が存在すれば、余ったすべての位置引数を受け取ったタプルに初期化されます。このデフォルト値は空のタプルです。 "**identifier" 形式が存在すれば、余ったすべてのキーワード引数を受け取った順序付きのマッピングオブジェクトに初期化されます。このデフォルト値は同じ型の空のマッピングオブジェクトです。 "*" や "*identifier" の後のパラメタはキーワード専用パラメータで、キーワード引数によってのみ渡されます。 "/" の前のパラメタは位置専用パラメータで、位置引数によってのみ渡されます。

バージョン 3.8 で変更: The / function parameter syntax may be used to indicate positional-only parameters. See PEP 570 [https://peps.python.org/pep-0570/] for details.

引数には、引数名に続けて ": expression" 形式の アノテーション を付けられます。 *identifier や **identifier の形式でも、すべての引数にはアノテーションをつけられます。関数には、引数リストの後に "-> expression" 形式の "return" アノテーションをつけられます。これらのアノテーションは、任意の有効な Python の式が使えます。アノテーションがあっても、関数の意味論は変わりません。アノテーションの値は、関数オブジェクトの __annotations__ 属性の、引数名をキーとする値として得られます。 __future__ の annotations インポートを使った場合は、アノテーションは実行時には文字列として保持され、これにより評価の遅延が可能になっています。そうでない場合は、アノテーションは関数定義が実行されたときに評価されます。このケースでは、アノテーションはソースコードに現れたのとは違う順序で評価されることがあります。

式を即時に使用するために、無名関数 (名前に束縛されていない関数) を作成することもできます。これは ラムダ (lambda) の節で解説されているラムダ式を使います。ラムダ式は簡略化された関数定義の簡略表現に過ぎないことに注意してください; "def" 文で定義された関数もラムダ式で作成された関数のように、引数として渡せたり、他の名前に割り当てることができます。複数の式とアノテーションが実行できるので、 "def" 形式の方がより強力です。

プログラマへのメモ: 関数は第一級オブジェクトです。関数定義内で実行された "def" 文は、返り値や引数として渡せるローカル関数を定義します。ネストした関数内で使われる自由変数は、 def を含んでいる関数のローカル変数にアクセスできます。詳細は 名前づけと束縛 (naming and binding) 節を参照してください。

参考

PEP 3107 [https://peps.python.org/pep-3107/] - Function Annotations

関数アノテーションの元の仕様書。

PEP 484 [https://peps.python.org/pep-0484/] - 型ヒント

アノテーションの標準的な意味付けである型ヒントの定義。

PEP 526 [https://peps.python.org/pep-0526/] - Syntax for Variable Annotations

Ability to type hint variable declarations, including class variables and instance variables.

PEP 563 [https://peps.python.org/pep-0563/] - アノテーションの遅延評価

実行時にアノテーションを貪欲評価するのではなく文字列形式で保持することによる、アノテーションにおける前方参照のサポート

PEP 318 [https://peps.python.org/pep-0318/] - Decorators for Functions and Methods

Function and method decorators were introduced. Class decorators were introduced in PEP 3129 [https://peps.python.org/pep-3129/].

8.8. クラス定義

クラス定義は、クラスオブジェクトを定義します (標準型の階層 節参照):

classdef    ::=  [decorators] "class" classname [type_params] [inheritance] ":" suite
inheritance ::=  "(" [argument_list] ")"
classname   ::=  identifier

クラス定義は実行可能な文です。継承リストは通常、基底クラスリストを与えます (より高度な使い方は、 メタクラス を参照してください)。ですから、リストのそれぞれの要素の評価はサブクラス化しても良いクラスであるべきです。継承リストのないクラスは、デフォルトで、基底クラス object を継承するので:

class Foo:
    pass

は、以下と同等です

class Foo(object):
    pass

次にクラスのスイートが、新たな実行フレーム (名前づけと束縛 (naming and binding) を参照してください) 内で、新たに作られたローカル名前空間と元々のグローバル名前空間を使って実行されます (通常、このスイートには主に関数定義が含まれます)。クラスのスイートが実行し終えると、実行フレームは破棄されますが、ローカルな名前空間は保存されます。[5] 次に、継承リストを基底クラスに、保存されたローカル名前空間を属性値辞書に、それぞれ使ってクラスオブジェクトが生成されます。最後に、もとのローカル名前空間において、クラス名がこのクラスオブジェクトに束縛されます。

クラス本体で属性が定義された順序は新しいクラスの __dict__ に保持されます。この性質が期待できるのは、クラスが作られた直後かつ定義構文を使って定義されたクラスであるときのみです。

クラス作成は、 メタクラス を利用して大幅にカスタマイズできます。

関数をデコレートするのと同じように、クラスもデコレートすることが出来ます、

@f1(arg)
@f2
class Foo: pass

は、だいたい次と等価です

class Foo: pass
Foo = f1(arg)(f2(Foo))

デコレータ式の評価規則は関数デコレータと同じです。結果はクラス名に束縛されます。

バージョン 3.9 で変更: Classes may be decorated with any valid assignment_expression. Previously, the grammar was much more restrictive; see PEP 614 [https://peps.python.org/pep-0614/] for details.

A list of 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 __type_params__ attribute. See Generic classes for more.

バージョン 3.12 で変更: Type parameter lists are new in Python 3.12.

プログラマのための注釈: クラス定義内で定義された変数はクラス属性であり、全てのインスタンス間で共有されます。インスタンス属性は、メソッドの中で self.name = value とすることで設定できます。クラス属性もインスタンス属性も "self.name" 表記でアクセスでき、この表記でアクセスしたとき、インスタンス属性は同名のクラス属性を隠蔽します。クラス属性は、インスタンス属性のデフォルト値として使えますが、そこにミュータブルな値を使うと予期せぬ結果につながります。 記述子 を使うと、詳細な実装が異なるインスタンス変数を作成できます。

参考

PEP 3115 [https://peps.python.org/pep-3115/] - Metaclasses in Python 3000

メタクラスの宣言を現在の文法と、メタクラス付きのクラスがどのように構築されるかの意味論を変更した提案

PEP 3129 [https://peps.python.org/pep-3129/] - クラスデコレータ

クラスデコレータを追加した提案。関数デコレータとメソッドデコレータは PEP 318 [https://peps.python.org/pep-0318/] で導入されました。

8.9. コルーチン

Added in version 3.5.

8.9.1. コルーチン関数定義

async_funcdef ::=  [decorators] "async" "def" funcname "(" [parameter_list] ")"
                   ["->" expression] ":" suite

Python で実行しているコルーチンは多くの時点で一時停止と再開ができます (coroutine を参照)。await 式である async for と async with はコルーチン関数の本体でしか使えません。

Functions defined with async def syntax are always coroutine functions, even if they do not contain await or async keywords.

コルーチン関数の本体の中で yield from 式を使用すると SyntaxError になります。

コルーチン関数の例:

async def func(param1, param2):
    do_stuff()
    await some_coroutine()

バージョン 3.7 で変更: await and async are now keywords; previously they were only treated as such inside the body of a coroutine function.

8.9.2. async for 文

async_for_stmt ::=  "async" for_stmt

asynchronous iterable は、その __anext__ メソッドで非同期なコードを実行可能な、asynchronous iterator を直接返す __aiter__ メソッドを提供しています。

async for 文によって非同期なイテラブルを簡単にイテレーションすることができます。

以下のコード:

async for TARGET in ITER:
    SUITE
else:
    SUITE2

は意味論的に以下と等価です:

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

詳細は __aiter__() や __anext__() を参照してください。

コルーチン関数の本体の外で async for 文を使用すると SyntaxError になります。

8.9.3. async with 文

async_with_stmt ::=  "async" with_stmt

asynchronous context manager は、 enter メソッドと exit メソッド内部で実行を一時停止できる context manager です。

以下のコード:

async with EXPRESSION as TARGET:
    SUITE

これは次と等価です:

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)

詳細は __aenter__() や __aexit__() を参照してください。

コルーチン関数の本体の外で async with 文を使用すると SyntaxError になります。

参考

PEP 492 [https://peps.python.org/pep-0492/] - async 構文および await 構文付きのコルーチン

コルーチンを Python のまともな独り立ちした概念にし、サポートする構文を追加した提案。

8.10. Type parameter lists

Added in version 3.12.

type_params  ::=  "[" type_param ("," type_param)* "]"
type_param   ::=  typevar | typevartuple | paramspec
typevar      ::=  identifier (":" expression)?
typevartuple ::=  "*" identifier
paramspec    ::=  "**" identifier

Functions (including coroutines), classes and type aliases may contain a type parameter list:

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]

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 ([]) 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 def func[T](): pass, the name 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 annotation scope) that wraps the creation of the generic object.

Generic functions, classes, and type aliases have a __type_params__ attribute listing their type parameters.

Type parameters come in three kinds:

typing.TypeVar, introduced by a plain name (e.g., T). Semantically, this represents a single type to a type checker.

typing.TypeVarTuple, introduced by a name prefixed with a single asterisk (e.g., *Ts). Semantically, this stands for a tuple of any number of types.

typing.ParamSpec, introduced by a name prefixed with two asterisks (e.g., **P). Semantically, this stands for the parameters of a callable.

typing.TypeVar declarations can define bounds and constraints with a colon (:) followed by an expression. A single expression after the colon indicates a bound (e.g. T: int). Semantically, this means that the 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. 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 typing.TypeVars 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 __bound__ and __constraints__. To accomplish this, the bounds or constraints are evaluated in a separate annotation scope.

typing.TypeVarTuples and typing.ParamSpecs cannot have bounds or constraints.

The following example indicates the full set of allowed type parameter declarations:

def overly_generic[
   SimpleTypeVar,
   TypeVarWithBound: int,
   TypeVarWithConstraints: (str, bytes),
   *SimpleTypeVarTuple,
   **SimpleParamSpec,
](
   a: SimpleTypeVar,
   b: TypeVarWithBound,
   c: Callable[SimpleParamSpec, TypeVarWithConstraints],
   *d: SimpleTypeVarTuple,
): ...

8.10.1. Generic functions

Generic functions are declared as follows:

def func[T](arg: T): ...

This syntax is equivalent to:

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()

Here annotation-def indicates an 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 typing module, but creates an instance of 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:

@decorator
def func[T: int, *Ts, **P](*args: *Ts, arg: Callable[P, T] = some_default):
    ...

Except for the lazy evaluation of the TypeVar bound, this is equivalent to:

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())

The capitalized names like DEFAULT_OF_arg are not actually bound at runtime.

8.10.2. Generic classes

Generic classes are declared as follows:

class Bag[T]: ...

This syntax is equivalent to:

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()

Here again annotation-def (not a real keyword) indicates an annotation scope, and the name TYPE_PARAMS_OF_Bag is not actually bound at runtime.

Generic classes implicitly inherit from 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:

@decorator
class Bag(Base[T], arg=T): ...

これは次と等価です:

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())

8.10.3. Generic type aliases

The type statement can also be used to create a generic type alias:

type ListOrSet[T] = list[T] | set[T]

Except for the lazy evaluation of the value, this is equivalent to:

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()

Here, annotation-def (not a real keyword) indicates an annotation scope. The capitalized names like TYPE_PARAMS_OF_ListOrSet are not actually bound at runtime.

脚注

[1]

例外は、別の例外を送出するような finally 節が無い場合にのみ呼び出しスタックへ伝わります。新しい例外によって、古い例外は失われます。

[2]

In pattern matching, a sequence is defined as one of the following:

collections.abc.Sequence を継承したクラス。

collections.abc.Sequence として登録されたPythonクラス。

a builtin class that has its (CPython) Py_TPFLAGS_SEQUENCE bit set

a class that inherits from any of the above

The following standard library classes are sequences:

array.array

collections.deque

list

memoryview

range

tuple

注釈

Subject values of type str, bytes, and bytearray do not match sequence patterns.

[3]

In pattern matching, a mapping is defined as one of the following:

a class that inherits from collections.abc.Mapping

a Python class that has been registered as collections.abc.Mapping

a builtin class that has its (CPython) Py_TPFLAGS_MAPPING bit set

a class that inherits from any of the above

The standard library classes dict and types.MappingProxyType are mappings.

[4]

A string literal appearing as the first statement in the function body is transformed into the function's __doc__ attribute and therefore the function's docstring.

[5]

クラスの本体の最初の文として現われる文字列リテラルは、その名前空間の __doc__ 要素となり、そのクラスの ドキュメンテーション文字列 になります。

9. トップレベル要素

Python インタプリタは、標準入力や、プログラムの引数として与えられたスクリプト、対話的にタイプ入力された命令、モジュールのソースファイルなど、様々な入力源から入力を得ることができます。この章では、それぞれの場合に用いられる構文法について説明しています。

9.1. 完全な Python プログラム

言語仕様の中では、その言語を処理するインタプリタがどのように起動されるかまで規定する必要はないのですが、完全な Python プログラムの概念を知っておくと役に立ちます。完全な Python プログラムは、最小限に初期化された環境: 全ての組み込み変数と標準モジュールが利用可能で、かつ sys (様々なシステムサービス)、 builtins (組み込み関数、例外、および None)、 __main__ の 3 つを除く全てのモジュールが初期化されていない状態で動作します。 __main__ は、完全なプログラムを実行する際に、ローカルおよびグローバルな名前空間を提供するために用いられます。

完全な Python プログラムの構文は、下の節で述べるファイル入力のためのものです。

インタプリタは、対話的モード (interactive mode) で起動されることもあります; この場合、インタプリタは完全なプログラムを読んで実行するのではなく、一度に単一の実行文 (複合文のときもあります) を読み込んで実行します。初期状態の環境は、完全なプログラムを実行するときの環境と同じです; 各実行文は、 __main__ の名前空間内で実行されます。

完全なプログラムは3つの形式でインタープリタに渡せます: -c string コマンドラインオプションで、コマンドラインの第 1 引数で渡されるファイル、あるいは標準入力として渡します。ファイルや標準入力が tty デバイスだった場合、インタープリタは対話モードに入ります。それ以外の場合は、ファイルを完全なプログラムとして実行します。

9.2. ファイル入力

非対話的なファイルから読み出された入力は、全て同じ形式:

file_input ::=  (NEWLINE | statement)*

をとります。この構文法は、以下の状況で用いられます:

(ファイルや文字列内の) 完全な Python プログラムを構文解析するとき;

モジュールを構文解析するとき;

exec() で渡された文字列を構文解析するとき;

9.3. 対話的入力

対話モードでの入力は、以下の文法の下に構文解析されます:

interactive_input ::=  [stmt_list] NEWLINE | compound_stmt NEWLINE

対話モードでは、(トップレベルの) 複合文の最後に空白行を入れなくてはならないことに注意してください; これは、複合文の終端をパーザが検出するための手がかりとして必要です。

9.4. 式入力

式入力には eval() が使われます。これは先頭の空白を無視します。 eval() に対する文字列引数は、以下の形式をとらなければなりません:

eval_input ::=  expression_list NEWLINE*

10. 完全な文法仕様

以下に示すのは Python の完全な文法です。CPython のパーサを生成するための文法定義から直接導かれたものです (Grammar/python.gram [https://github.com/python/cpython/tree/3.12/Grammar/python.gram] を参照のこと)。ここに示すのは、コード生成およびエラー処理に関係する部分を省略したバージョンです。

文法の記法は EBNF [https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form] と PEG [https://en.wikipedia.org/wiki/Parsing_expression_grammar] との混合です。特に、& にシンボル、トークンまたは括弧でくくられたグループが続く場合、それは正の先読み (positive lookahead) (すなわち、文法にマッチするためには必要だが、マッチ後に消費されない) です。一方で、! は負の先読み (negative lookahead) (すなわち、マッチ しない ために必要) です。 PEG の順序付き選択 (ordered choice) の区切り文字として (伝統的に使われている / ではなく) | を使用します。文法の記法について、詳しくは PEP 617 [https://peps.python.org/pep-0617/] を見てください。

# PEG grammar for Python

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

# STARTING RULES
# ==============

file: [statements] ENDMARKER
interactive: statement_newline
eval: expressions NEWLINE* ENDMARKER
func_type: '(' [type_expressions] ')' '->' expression NEWLINE* ENDMARKER

# GENERAL STATEMENTS
# ==================

statements: statement+

statement: compound_stmt  | simple_stmts

statement_newline:
    | compound_stmt NEWLINE
    | simple_stmts
    | NEWLINE
    | ENDMARKER

simple_stmts:
    | simple_stmt !';' NEWLINE  # Not needed, there for speedup
    | ';'.simple_stmt+ [';'] NEWLINE

# NOTE: assignment MUST precede expression, else parsing a simple assignment
# will throw a SyntaxError.
simple_stmt:
    | assignment
    | type_alias
    | star_expressions
    | return_stmt
    | import_stmt
    | raise_stmt
    | 'pass'
    | del_stmt
    | yield_stmt
    | assert_stmt
    | 'break'
    | 'continue'
    | global_stmt
    | nonlocal_stmt

compound_stmt:
    | function_def
    | if_stmt
    | class_def
    | with_stmt
    | for_stmt
    | try_stmt
    | while_stmt
    | match_stmt

# SIMPLE STATEMENTS
# =================

# NOTE: annotated_rhs may start with 'yield'; yield_expr must start with 'yield'
assignment:
    | NAME ':' expression ['=' annotated_rhs ]
    | ('(' single_target ')'
         | single_subscript_attribute_target) ':' expression ['=' annotated_rhs ]
    | (star_targets '=' )+ (yield_expr | star_expressions) !'=' [TYPE_COMMENT]
    | single_target augassign ~ (yield_expr | star_expressions)

annotated_rhs: yield_expr | star_expressions

augassign:
    | '+='
    | '-='
    | '*='
    | '@='
    | '/='
    | '%='
    | '&='
    | '|='
    | '^='
    | '<<='
    | '>>='
    | '**='
    | '//='

return_stmt:
    | 'return' [star_expressions]

raise_stmt:
    | 'raise' expression ['from' expression ]
    | 'raise'

global_stmt: 'global' ','.NAME+

nonlocal_stmt: 'nonlocal' ','.NAME+

del_stmt:
    | 'del' del_targets &(';' | NEWLINE)

yield_stmt: yield_expr

assert_stmt: 'assert' expression [',' expression ]

import_stmt:
    | import_name
    | import_from

# Import statements
# -----------------

import_name: 'import' dotted_as_names
# note below: the ('.' | '...') is necessary because '...' is tokenized as ELLIPSIS
import_from:
    | 'from' ('.' | '...')* dotted_name 'import' import_from_targets
    | 'from' ('.' | '...')+ 'import' import_from_targets
import_from_targets:
    | '(' import_from_as_names [','] ')'
    | import_from_as_names !','
    | '*'
import_from_as_names:
    | ','.import_from_as_name+
import_from_as_name:
    | NAME ['as' NAME ]
dotted_as_names:
    | ','.dotted_as_name+
dotted_as_name:
    | dotted_name ['as' NAME ]
dotted_name:
    | dotted_name '.' NAME
    | NAME

# COMPOUND STATEMENTS
# ===================

# Common elements
# ---------------

block:
    | NEWLINE INDENT statements DEDENT
    | simple_stmts

decorators: ('@' named_expression NEWLINE )+

# Class definitions
# -----------------

class_def:
    | decorators class_def_raw
    | class_def_raw

class_def_raw:
    | 'class' NAME [type_params] ['(' [arguments] ')' ] ':' block

# Function definitions
# --------------------

function_def:
    | decorators function_def_raw
    | function_def_raw

function_def_raw:
    | 'def' NAME [type_params] '(' [params] ')' ['->' expression ] ':' [func_type_comment] block
    | ASYNC 'def' NAME [type_params] '(' [params] ')' ['->' expression ] ':' [func_type_comment] block

# Function parameters
# -------------------

params:
    | parameters

parameters:
    | slash_no_default param_no_default* param_with_default* [star_etc]
    | slash_with_default param_with_default* [star_etc]
    | param_no_default+ param_with_default* [star_etc]
    | param_with_default+ [star_etc]
    | star_etc

# Some duplication here because we can't write (',' | &')'),
# which is because we don't support empty alternatives (yet).

slash_no_default:
    | param_no_default+ '/' ','
    | param_no_default+ '/' &')'
slash_with_default:
    | param_no_default* param_with_default+ '/' ','
    | param_no_default* param_with_default+ '/' &')'

star_etc:
    | '*' param_no_default param_maybe_default* [kwds]
    | '*' param_no_default_star_annotation param_maybe_default* [kwds]
    | '*' ',' param_maybe_default+ [kwds]
    | kwds

kwds:
    | '**' param_no_default

# 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:
    | param ',' TYPE_COMMENT?
    | param TYPE_COMMENT? &')'
param_no_default_star_annotation:
    | param_star_annotation ',' TYPE_COMMENT?
    | param_star_annotation TYPE_COMMENT? &')'
param_with_default:
    | param default ',' TYPE_COMMENT?
    | param default TYPE_COMMENT? &')'
param_maybe_default:
    | param default? ',' TYPE_COMMENT?
    | param default? TYPE_COMMENT? &')'
param: NAME annotation?
param_star_annotation: NAME star_annotation
annotation: ':' expression
star_annotation: ':' star_expression
default: '=' expression  | invalid_default

# If statement
# ------------

if_stmt:
    | 'if' named_expression ':' block elif_stmt
    | 'if' named_expression ':' block [else_block]
elif_stmt:
    | 'elif' named_expression ':' block elif_stmt
    | 'elif' named_expression ':' block [else_block]
else_block:
    | 'else' ':' block

# While statement
# ---------------

while_stmt:
    | 'while' named_expression ':' block [else_block]

# For statement
# -------------

for_stmt:
    | 'for' star_targets 'in' ~ star_expressions ':' [TYPE_COMMENT] block [else_block]
    | ASYNC 'for' star_targets 'in' ~ star_expressions ':' [TYPE_COMMENT] block [else_block]

# With statement
# --------------

with_stmt:
    | 'with' '(' ','.with_item+ ','? ')' ':' block
    | 'with' ','.with_item+ ':' [TYPE_COMMENT] block
    | ASYNC 'with' '(' ','.with_item+ ','? ')' ':' block
    | ASYNC 'with' ','.with_item+ ':' [TYPE_COMMENT] block

with_item:
    | expression 'as' star_target &(',' | ')' | ':')
    | expression

# Try statement
# -------------

try_stmt:
    | 'try' ':' block finally_block
    | 'try' ':' block except_block+ [else_block] [finally_block]
    | 'try' ':' block except_star_block+ [else_block] [finally_block]

# Except statement
# ----------------

except_block:
    | 'except' expression ['as' NAME ] ':' block
    | 'except' ':' block
except_star_block:
    | 'except' '*' expression ['as' NAME ] ':' block
finally_block:
    | 'finally' ':' block

# Match statement
# ---------------

match_stmt:
    | "match" subject_expr ':' NEWLINE INDENT case_block+ DEDENT

subject_expr:
    | star_named_expression ',' star_named_expressions?
    | named_expression

case_block:
    | "case" patterns guard? ':' block

guard: 'if' named_expression

patterns:
    | open_sequence_pattern
    | pattern

pattern:
    | as_pattern
    | or_pattern

as_pattern:
    | or_pattern 'as' pattern_capture_target

or_pattern:
    | '|'.closed_pattern+

closed_pattern:
    | 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:
    | signed_number !('+' | '-')
    | complex_number
    | strings
    | 'None'
    | 'True'
    | 'False'

# Literal expressions are used to restrict permitted mapping pattern keys
literal_expr:
    | signed_number !('+' | '-')
    | complex_number
    | strings
    | 'None'
    | 'True'
    | 'False'

complex_number:
    | signed_real_number '+' imaginary_number
    | signed_real_number '-' imaginary_number

signed_number:
    | NUMBER
    | '-' NUMBER

signed_real_number:
    | real_number
    | '-' real_number

real_number:
    | NUMBER

imaginary_number:
    | NUMBER

capture_pattern:
    | pattern_capture_target

pattern_capture_target:
    | !"_" NAME !('.' | '(' | '=')

wildcard_pattern:
    | "_"

value_pattern:
    | attr !('.' | '(' | '=')

attr:
    | name_or_attr '.' NAME

name_or_attr:
    | attr
    | NAME

group_pattern:
    | '(' pattern ')'

sequence_pattern:
    | '[' maybe_sequence_pattern? ']'
    | '(' open_sequence_pattern? ')'

open_sequence_pattern:
    | maybe_star_pattern ',' maybe_sequence_pattern?

maybe_sequence_pattern:
    | ','.maybe_star_pattern+ ','?

maybe_star_pattern:
    | star_pattern
    | pattern

star_pattern:
    | '*' pattern_capture_target
    | '*' wildcard_pattern

mapping_pattern:
    | '{' '}'
    | '{' double_star_pattern ','? '}'
    | '{' items_pattern ',' double_star_pattern ','? '}'
    | '{' items_pattern ','? '}'

items_pattern:
    | ','.key_value_pattern+

key_value_pattern:
    | (literal_expr | attr) ':' pattern

double_star_pattern:
    | '**' pattern_capture_target

class_pattern:
    | name_or_attr '(' ')'
    | name_or_attr '(' positional_patterns ','? ')'
    | name_or_attr '(' keyword_patterns ','? ')'
    | name_or_attr '(' positional_patterns ',' keyword_patterns ','? ')'

positional_patterns:
    | ','.pattern+

keyword_patterns:
    | ','.keyword_pattern+

keyword_pattern:
    | NAME '=' pattern

# Type statement
# ---------------

type_alias:
    | "type" NAME [type_params] '=' expression

# Type parameter declaration
# --------------------------

type_params: '[' type_param_seq  ']'

type_param_seq: ','.type_param+ [',']

type_param:
    | NAME [type_param_bound]
    | '*' NAME
    | '**' NAME

type_param_bound: ':' expression

# EXPRESSIONS
# -----------

expressions:
    | expression (',' expression )+ [',']
    | expression ','
    | expression

expression:
    | disjunction 'if' disjunction 'else' expression
    | disjunction
    | lambdef

yield_expr:
    | 'yield' 'from' expression
    | 'yield' [star_expressions]

star_expressions:
    | star_expression (',' star_expression )+ [',']
    | star_expression ','
    | star_expression

star_expression:
    | '*' bitwise_or
    | expression

star_named_expressions: ','.star_named_expression+ [',']

star_named_expression:
    | '*' bitwise_or
    | named_expression

assignment_expression:
    | NAME ':=' ~ expression

named_expression:
    | assignment_expression
    | expression !':='

disjunction:
    | conjunction ('or' conjunction )+
    | conjunction

conjunction:
    | inversion ('and' inversion )+
    | inversion

inversion:
    | 'not' inversion
    | comparison

# Comparison operators
# --------------------

comparison:
    | bitwise_or compare_op_bitwise_or_pair+
    | bitwise_or

compare_op_bitwise_or_pair:
    | 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: '==' bitwise_or
noteq_bitwise_or:
    | ('!=' ) bitwise_or
lte_bitwise_or: '<=' bitwise_or
lt_bitwise_or: '<' bitwise_or
gte_bitwise_or: '>=' bitwise_or
gt_bitwise_or: '>' bitwise_or
notin_bitwise_or: 'not' 'in' bitwise_or
in_bitwise_or: 'in' bitwise_or
isnot_bitwise_or: 'is' 'not' bitwise_or
is_bitwise_or: 'is' bitwise_or

# Bitwise operators
# -----------------

bitwise_or:
    | bitwise_or '|' bitwise_xor
    | bitwise_xor

bitwise_xor:
    | bitwise_xor '^' bitwise_and
    | bitwise_and

bitwise_and:
    | bitwise_and '&' shift_expr
    | shift_expr

shift_expr:
    | shift_expr '<<' sum
    | shift_expr '>>' sum
    | sum

# Arithmetic operators
# --------------------

sum:
    | sum '+' term
    | sum '-' term
    | term

term:
    | term '*' factor
    | term '/' factor
    | term '//' factor
    | term '%' factor
    | term '@' factor
    | factor

factor:
    | '+' factor
    | '-' factor
    | '~' factor
    | power

power:
    | await_primary '**' factor
    | await_primary

# Primary elements
# ----------------

# Primary elements are things like "obj.something.something", "obj[something]", "obj(something)", "obj" ...

await_primary:
    | AWAIT primary
    | primary

primary:
    | primary '.' NAME
    | primary genexp
    | primary '(' [arguments] ')'
    | primary '[' slices ']'
    | atom

slices:
    | slice !','
    | ','.(slice | starred_expression)+ [',']

slice:
    | [expression] ':' [expression] [':' [expression] ]
    | named_expression

atom:
    | NAME
    | 'True'
    | 'False'
    | 'None'
    | strings
    | NUMBER
    | (tuple | group | genexp)
    | (list | listcomp)
    | (dict | set | dictcomp | setcomp)
    | '...'

group:
    | '(' (yield_expr | named_expression) ')'

# Lambda functions
# ----------------

lambdef:
    | 'lambda' [lambda_params] ':' expression

lambda_params:
    | 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:
    | lambda_slash_no_default lambda_param_no_default* lambda_param_with_default* [lambda_star_etc]
    | lambda_slash_with_default lambda_param_with_default* [lambda_star_etc]
    | lambda_param_no_default+ lambda_param_with_default* [lambda_star_etc]
    | lambda_param_with_default+ [lambda_star_etc]
    | lambda_star_etc

lambda_slash_no_default:
    | lambda_param_no_default+ '/' ','
    | lambda_param_no_default+ '/' &':'

lambda_slash_with_default:
    | lambda_param_no_default* lambda_param_with_default+ '/' ','
    | lambda_param_no_default* lambda_param_with_default+ '/' &':'

lambda_star_etc:
    | '*' lambda_param_no_default lambda_param_maybe_default* [lambda_kwds]
    | '*' ',' lambda_param_maybe_default+ [lambda_kwds]
    | lambda_kwds

lambda_kwds:
    | '**' lambda_param_no_default

lambda_param_no_default:
    | lambda_param ','
    | lambda_param &':'
lambda_param_with_default:
    | lambda_param default ','
    | lambda_param default &':'
lambda_param_maybe_default:
    | lambda_param default? ','
    | lambda_param default? &':'
lambda_param: NAME

# LITERALS
# ========

fstring_middle:
    | fstring_replacement_field
    | FSTRING_MIDDLE
fstring_replacement_field:
    | '{' (yield_expr | star_expressions) '='? [fstring_conversion] [fstring_full_format_spec] '}'
fstring_conversion:
    | "!" NAME
fstring_full_format_spec:
    | ':' fstring_format_spec*
fstring_format_spec:
    | FSTRING_MIDDLE
    | fstring_replacement_field
fstring:
    | FSTRING_START fstring_middle* FSTRING_END

string: STRING
strings: (fstring|string)+

list:
    | '[' [star_named_expressions] ']'

tuple:
    | '(' [star_named_expression ',' [star_named_expressions]  ] ')'

set: '{' star_named_expressions '}'

# Dicts
# -----

dict:
    | '{' [double_starred_kvpairs] '}'

double_starred_kvpairs: ','.double_starred_kvpair+ [',']

double_starred_kvpair:
    | '**' bitwise_or
    | kvpair

kvpair: expression ':' expression

# Comprehensions & Generators
# ---------------------------

for_if_clauses:
    | for_if_clause+

for_if_clause:
    | ASYNC 'for' star_targets 'in' ~ disjunction ('if' disjunction )*
    | 'for' star_targets 'in' ~ disjunction ('if' disjunction )*

listcomp:
    | '[' named_expression for_if_clauses ']'

setcomp:
    | '{' named_expression for_if_clauses '}'

genexp:
    | '(' ( assignment_expression | expression !':=') for_if_clauses ')'

dictcomp:
    | '{' kvpair for_if_clauses '}'

# FUNCTION CALL ARGUMENTS
# =======================

arguments:
    | args [','] &')'

args:
    | ','.(starred_expression | ( assignment_expression | expression !':=') !'=')+ [',' kwargs ]
    | kwargs

kwargs:
    | ','.kwarg_or_starred+ ',' ','.kwarg_or_double_starred+
    | ','.kwarg_or_starred+
    | ','.kwarg_or_double_starred+

starred_expression:
    | '*' expression

kwarg_or_starred:
    | NAME '=' expression
    | starred_expression

kwarg_or_double_starred:
    | NAME '=' expression
    | '**' expression

# ASSIGNMENT TARGETS
# ==================

# Generic targets
# ---------------

# NOTE: star_targets may contain *bitwise_or, targets may not.
star_targets:
    | star_target !','
    | star_target (',' star_target )* [',']

star_targets_list_seq: ','.star_target+ [',']

star_targets_tuple_seq:
    | star_target (',' star_target )+ [',']
    | star_target ','

star_target:
    | '*' (!'*' star_target)
    | target_with_star_atom

target_with_star_atom:
    | t_primary '.' NAME !t_lookahead
    | t_primary '[' slices ']' !t_lookahead
    | star_atom

star_atom:
    | NAME
    | '(' target_with_star_atom ')'
    | '(' [star_targets_tuple_seq] ')'
    | '[' [star_targets_list_seq] ']'

single_target:
    | single_subscript_attribute_target
    | NAME
    | '(' single_target ')'

single_subscript_attribute_target:
    | t_primary '.' NAME !t_lookahead
    | t_primary '[' slices ']' !t_lookahead

t_primary:
    | t_primary '.' NAME &t_lookahead
    | t_primary '[' slices ']' &t_lookahead
    | t_primary genexp &t_lookahead
    | t_primary '(' [arguments] ')' &t_lookahead
    | atom &t_lookahead

t_lookahead: '(' | '[' | '.'

# Targets for del statements
# --------------------------

del_targets: ','.del_target+ [',']

del_target:
    | t_primary '.' NAME !t_lookahead
    | t_primary '[' slices ']' !t_lookahead
    | del_t_atom

del_t_atom:
    | NAME
    | '(' del_target ')'
    | '(' [del_targets] ')'
    | '[' [del_targets] ']'

# TYPING ELEMENTS
# ---------------

# type_expressions allow */** but ignore them
type_expressions:
    | ','.expression+ ',' '*' expression ',' '**' expression
    | ','.expression+ ',' '*' expression
    | ','.expression+ ',' '**' expression
    | '*' expression ',' '**' expression
    | '*' expression
    | '**' expression
    | ','.expression+

func_type_comment:
    | NEWLINE TYPE_COMMENT &(NEWLINE INDENT)   # Must be followed by indented block
    | TYPE_COMMENT

# ========================= END OF THE GRAMMAR ===========================

# ========================= START OF INVALID RULES =======================

Python 標準ライブラリ

Python 言語リファレンス ではプログラミング言語 Python の厳密な構文とセマンティクスについて説明されていますが、このライブラリリファレンスマニュアルでは Python とともに配付されている標準ライブラリについて説明します。また Python 配布物に収められていることの多いオプションのコンポーネントについても説明します。

Python の標準ライブラリはとても拡張性があり、下の長い目次のリストで判るように幅広いものを用意しています。このライブラリには、例えばファイル I/O のように、Python プログラマが直接アクセスできないシステム機能へのアクセス機能を提供する (Cで書かれた) 組み込みモジュールや、日々のプログラミングで生じる多くの問題に標準的な解決策を提供するPython で書かれたモジュールが入っています。これら数多くのモジュールには、プラットフォーム固有の事情をプラットフォーム独立な API へと昇華させることにより、Pythonプログラムに移植性を持たせ、それを高めるという明確な意図があります。

Windows 向けの Python インストーラはたいてい標準ライブラリのすべてを含み、しばしばそれ以外の追加のコンポーネントも含んでいます。Unix 系のオペレーティングシステムの場合は Python は一揃いのパッケージとして提供されるのが普通で、オプションのコンポーネントを手に入れるにはオペレーティングシステムのパッケージツールを使うことになるでしょう。

標準ライブラリに加えて、数10万のコンポーネントが (独立したプログラムやモジュールからパッケージ、アプリケーション開発フレームワークまで) 活動しているコレクションとしてPython Package Index [https://pypi.org] から入手可能です。

はじめに

利用可能性について

組み込み関数

組み込み定数

site モジュールで追加される定数

組み込み型

真理値判定

ブール演算 --- and, or, not

比較

数値型 int, float, complex

ブーリアン型 - bool

イテレータ型

シーケンス型 --- list, tuple, range

テキストシーケンス型 --- str

バイナリシーケンス型 --- bytes, bytearray, memoryview

set（集合）型 --- set, frozenset

マッピング型 --- dict

コンテキストマネージャ型

型アノテーション型 --- ジェネリックエイリアス 、 ユニオン

その他の組み込み型

特殊属性

整数と文字列の変換での長さ制限

組み込み例外

例外コンテキスト

組み込み例外から継承する

基底クラス

具象例外

警告

例外グループ

例外のクラス階層

テキスト処理サービス

string --- Common string operations

re --- Regular expression operations

difflib --- Helpers for computing deltas

textwrap --- Text wrapping and filling

unicodedata --- Unicode Database

stringprep --- Internet String Preparation

readline --- GNU readline interface

rlcompleter --- Completion function for GNU readline

バイナリデータ処理

struct --- Interpret bytes as packed binary data

codecs --- Codec registry and base classes

データ型

datetime --- Basic date and time types

zoneinfo --- IANA time zone support

calendar --- General calendar-related functions

collections --- Container datatypes

collections.abc --- Abstract Base Classes for Containers

heapq --- Heap queue algorithm

bisect --- Array bisection algorithm

array --- Efficient arrays of numeric values

weakref --- 弱参照

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

copy --- Shallow and deep copy operations

pprint --- Data pretty printer

reprlib --- Alternate repr() implementation

enum --- Support for enumerations

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

数値と数学モジュール

numbers --- Numeric abstract base classes

math --- Mathematical functions

cmath --- Mathematical functions for complex numbers

decimal --- Decimal fixed point and floating point arithmetic

fractions --- Rational numbers

random --- Generate pseudo-random numbers

statistics --- Mathematical statistics functions

関数型プログラミング用モジュール

itertools --- Functions creating iterators for efficient looping

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

operator --- Standard operators as functions

ファイルとディレクトリへのアクセス

pathlib --- Object-oriented filesystem paths

os.path --- Common pathname manipulations

fileinput --- Iterate over lines from multiple input streams

stat --- Interpreting stat() results

filecmp --- File and Directory Comparisons

tempfile --- Generate temporary files and directories

glob --- Unix style pathname pattern expansion

fnmatch --- Unix filename pattern matching

linecache --- Random access to text lines

shutil --- High-level file operations

データの永続化

pickle --- Python object serialization

copyreg --- Register pickle support functions

shelve --- Python object persistence

marshal --- Internal Python object serialization

dbm --- Interfaces to Unix "databases"

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

データ圧縮とアーカイブ

zlib --- Compression compatible with gzip

gzip --- Support for gzip files

bz2 --- Support for bzip2 compression

lzma --- Compression using the LZMA algorithm

zipfile --- Work with ZIP archives

tarfile --- Read and write tar archive files

ファイルフォーマット

csv --- CSV File Reading and Writing

configparser --- Configuration file parser

tomllib --- Parse TOML files

netrc --- netrc file processing

plistlib --- Generate and parse Apple .plist files

暗号関連のサービス

hashlib --- Secure hashes and message digests

hmac --- Keyed-Hashing for Message Authentication

secrets --- Generate secure random numbers for managing secrets

汎用オペレーティングシステムサービス

os --- Miscellaneous operating system interfaces

io --- Core tools for working with streams

time --- Time access and conversions

argparse --- Parser for command-line options, arguments and sub-commands

getopt --- C-style parser for command line options

logging --- Logging facility for Python

logging.config --- Logging configuration

logging.handlers --- Logging handlers

getpass --- Portable password input

curses --- Terminal handling for character-cell displays

curses.textpad --- curses プログラムのためのテキスト入力ウィジェット

curses.ascii --- Utilities for ASCII characters

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

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

errno --- Standard errno system symbols

ctypes --- A foreign function library for Python

並行実行

threading --- Thread-based parallelism

multiprocessing --- Process-based parallelism

multiprocessing.shared_memory --- Shared memory for direct access across processes

The concurrent package

concurrent.futures --- Launching parallel tasks

subprocess --- Subprocess management

sched --- Event scheduler

queue --- A synchronized queue class

contextvars --- Context Variables

_thread --- Low-level threading API

ネットワーク通信とプロセス間通信

asyncio --- Asynchronous I/O

socket --- Low-level networking interface

ssl --- TLS/SSL wrapper for socket objects

select --- Waiting for I/O completion

selectors --- High-level I/O multiplexing

signal --- Set handlers for asynchronous events

mmap --- Memory-mapped file support

インターネット上のデータの操作

email --- An email and MIME handling package

json --- JSON encoder and decoder

mailbox --- Manipulate mailboxes in various formats

mimetypes --- Map filenames to MIME types

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

binascii --- Convert between binary and ASCII

quopri --- Encode and decode MIME quoted-printable data

構造化マークアップツール

html --- HyperText Markup Language support

html.parser --- Simple HTML and XHTML parser

html.entities --- Definitions of HTML general entities

XMLを扱うモジュール群

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

xml.dom --- The Document Object Model API

xml.dom.minidom --- Minimal DOM implementation

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

xml.sax --- Support for SAX2 parsers

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

xml.sax.saxutils --- SAX Utilities

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

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

インターネットプロトコルとサポート

webbrowser --- Convenient web-browser controller

wsgiref --- WSGI Utilities and Reference Implementation

urllib --- URL handling modules

urllib.request --- Extensible library for opening URLs

urllib.response --- urllib で使用するレスポンスクラス

urllib.parse --- Parse URLs into components

urllib.error --- Exception classes raised by urllib.request

urllib.robotparser --- Parser for robots.txt

http --- HTTP modules

http.client --- HTTP protocol client

ftplib --- FTP protocol client

poplib --- POP3 protocol client

imaplib --- IMAP4 protocol client

smtplib --- SMTP protocol client

uuid --- UUID objects according to RFC 4122

socketserver --- A framework for network servers

http.server --- HTTP servers

http.cookies --- HTTP state management

http.cookiejar --- Cookie handling for HTTP clients

xmlrpc --- XMLRPC server and client modules

xmlrpc.client --- XML-RPC client access

xmlrpc.server --- Basic XML-RPC servers

ipaddress --- IPv4/IPv6 manipulation library

マルチメディアサービス

wave --- Read and write WAV files

colorsys --- Conversions between color systems

国際化

gettext --- Multilingual internationalization services

locale --- Internationalization services

プログラムのフレームワーク

turtle --- タートルグラフィックス

cmd --- Support for line-oriented command interpreters

shlex --- Simple lexical analysis

Tk を用いたグラフィカルユーザインターフェイス

tkinter --- Python interface to Tcl/Tk

tkinter.colorchooser --- Color choosing dialog

tkinter.font --- Tkinter font wrapper

Tkinter ダイアログ

tkinter.messagebox --- Tkinter message prompts

tkinter.scrolledtext --- Scrolled Text Widget

tkinter.dnd --- Drag and drop support

tkinter.ttk --- Tk themed widgets

tkinter.tix --- Tkの拡張ウィジェット

IDLE

開発ツール

typing --- 型ヒントのサポート

pydoc --- Documentation generator and online help system

Python 開発モード

doctest --- Test interactive Python examples

unittest --- Unit testing framework

unittest.mock --- mock object library

unittest.mock --- getting started

2to3 --- Python 2 から 3 への自動コード変換

test --- Regression tests package for Python

test.support --- テストのためのユーティリティ関数

test.support.socket_helper --- Utilities for socket tests

test.support.script_helper --- Utilities for the Python execution tests

test.support.bytecode_helper --- Support tools for testing correct bytecode generation

test.support.threading_helper --- Utilities for threading tests

test.support.os_helper --- Utilities for os tests

test.support.import_helper --- Utilities for import tests

test.support.warnings_helper --- Utilities for warnings tests

デバッグとプロファイル

Audit events table

bdb --- Debugger framework

faulthandler --- Dump the Python traceback

pdb --- Python デバッガ

Python プロファイラ

timeit --- Measure execution time of small code snippets

trace --- Trace or track Python statement execution

tracemalloc --- Trace memory allocations

ソフトウェア・パッケージと配布

ensurepip --- Bootstrapping the pip installer

venv --- Creation of virtual environments

zipapp --- Manage executable Python zip archives

Python ランタイムサービス

sys --- System-specific parameters and functions

sys.monitoring --- Execution event monitoring

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

builtins --- Built-in objects

__main__ --- Top-level code environment

warnings --- Warning control

dataclasses --- Data Classes

contextlib --- with 文コンテキスト用ユーティリティ

abc --- Abstract Base Classes

atexit --- Exit handlers

traceback --- Print or retrieve a stack traceback

__future__ --- Future statement definitions

gc --- Garbage Collector interface

inspect --- Inspect live objects

site --- Site-specific configuration hook

カスタム Python インタプリタ

code --- Interpreter base classes

codeop --- Compile Python code

モジュールのインポート

zipimport --- Import modules from Zip archives

pkgutil --- Package extension utility

modulefinder --- Find modules used by a script

runpy --- Locating and executing Python modules

importlib --- import の実装

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

importlib.resources.abc -- Abstract base classes for resources

importlib.metadata -- Accessing package metadata

The initialization of the sys.path module search path

Python言語サービス

ast --- Abstract Syntax Trees

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

token --- Constants used with Python parse trees

keyword --- Testing for Python keywords

tokenize --- Tokenizer for Python source

tabnanny --- Detection of ambiguous indentation

pyclbr --- Python module browser support

py_compile --- Compile Python source files

compileall --- Byte-compile Python libraries

dis --- Disassembler for Python bytecode

pickletools --- Tools for pickle developers

MS Windows 固有のサービス

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

winreg --- Windows registry access

winsound --- Sound-playing interface for Windows

Unix 固有のサービス

posix --- The most common POSIX system calls

pwd --- The password database

grp --- The group database

termios --- POSIX style tty control

tty --- Terminal control functions

pty --- Pseudo-terminal utilities

fcntl --- The fcntl and ioctl system calls

resource --- Resource usage information

syslog --- Unix syslog library routines

Modules command-line interface (CLI)

取って代わられたモジュール群

aifc --- AIFFおよびAIFCファイルの読み書き

audioop --- 生の音声データを操作する

cgi --- CGI (ゲートウェイインターフェース規格) のサポート

cgitb --- CGI スクリプトのトレースバック管理機構

chunk --- IFFチャンクデータの読み込み

crypt --- Unix パスワードをチェックするための関数

imghdr --- 画像の形式を決定する

mailcap --- mailcap ファイルの操作

msilib --- Microsoft インストーラーファイルの読み書き

nis --- Sun の NIS (Yellow Pages) へのインターフェース

nntplib --- NNTP プロトコルクライアント

optparse --- Parser for command line options

ossaudiodev --- OSS互換オーディオデバイスへのアクセス

pipes --- シェルパイプラインへのインターフェース

sndhdr --- サウンドファイルの識別

spwd --- シャドウパスワードデータベース

sunau --- Sun AUファイルの読み書き

telnetlib --- Telnet クライアント

uu --- uuencode形式のエンコードとデコード

xdrlib --- XDR データのエンコードおよびデコード

セキュリティで考慮すべき点

はじめに

この "Python ライブラリ" には様々な内容が収録されています。

このライブラリには、数値型やリスト型のような、通常は言語の "核" をなす部分とみなされるデータ型が含まれています。Python 言語のコア部分では、これらの型に対してリテラル表現形式を与え、意味づけ上のいくつかの制約を与えていますが、完全にその意味づけを定義しているわけではありません。(一方で、言語のコア部分では演算子のスペルや優先順位のような構文法的な属性を定義しています。)

このライブラリにはまた、組み込み関数と例外が納められています --- 組み込み関数および例外は、全ての Python で書かれたコード上で、 import 文を使わずに使うことができるオブジェクトです。これらの組み込み要素のうちいくつかは言語のコア部分で定義されていますが、大半は言語コアの意味づけ上不可欠なものではないのでここでしか記述されていません。

とはいえ、このライブラリの大部分に収録されているのはモジュールのコレクションです。このコレクションを細分化する方法はいろいろあります。あるモジュールは C 言語で書かれ、Python インタプリタに組み込まれています; 一方別のモジュールは Python で書かれ、ソースコードの形式で取り込まれます。またあるモジュールは、例えば実行スタックの追跡結果を出力するといった、Python に非常に特化したインターフェースを提供し、一方他のモジュールでは、特定のハードウェアにアクセスするといった、特定のオペレーティングシステムに特化したインターフェースを提供し、さらに別のモジュールでは WWW (ワールドワイドウェブ) のような特定のアプリケーション分野に特化したインターフェースを提供しています。モジュールによっては全てのバージョン、全ての移植版の Python で利用することができたり、背後にあるシステムがサポートしている場合にのみ使えたり、Python をコンパイルしてインストールする際に特定の設定オプションを選んだときにのみ利用できたりします。

このマニュアルは "内部から外部へ" と構成されています。つまり、最初に組み込みの関数を記述し、組み込みのデータ型、例外、そして最後に各モジュールと続きます。モジュールは関係のあるものでグループ化して一つの章にしています。

つまり、このマニュアルを最初から読み始め、読み飽きたところで次の章に進めば、 Python ライブラリで利用できるモジュールやサポートしているアプリケーション領域の概要をそこそこ理解できるということです。もちろん、このマニュアルを小説のように読む必要は ありません --- (マニュアルの先頭部分にある) 目次にざっと目を通したり、 (最後尾にある) 索引でお目当ての関数やモジュール、用語を探すことだってできます。もしランダムな項目について勉強してみたいのなら、ランダムにページを選び (random 参照)、そこから 1, 2 節読むこともできます。このマニュアルの各節をどんな順番で読むかに関わらず、 組み込み関数 の章から始めるとよいでしょう。マニュアルの他の部分は、この節の内容について知っているものとして書かれているからです。

それでは、ショーの始まりです！

利用可能性について

「利用できる環境 : Unix 」の意味はこの関数が Unix システムにあることが多いということです。このことは特定の OS における存在を主張するものではありません。

If not separately noted, all functions that claim "Availability: Unix" are supported on macOS, which builds on a Unix core.

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.

WebAssemblyプラットフォーム

The WebAssembly [https://webassembly.org/] platforms wasm32-emscripten (Emscripten [https://emscripten.org/]) and wasm32-wasi (WASI [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 sleep() block the browser event loop.

The properties and behavior of Python on WebAssembly platforms depend on the Emscripten [https://emscripten.org/]-SDK or WASI [https://wasi.dev/]-SDK version, WASM runtimes (browser, NodeJS, wasmtime [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 [https://pyodide.org/] or PyScript [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 XMLHttpRequest and Fetch APIs.

Process-related APIs are not available or always fail with an error. That includes APIs that spawn new processes (fork(), execve()), wait for processes (waitpid()), send signals (kill()), or otherwise interact with processes. The subprocess is importable but does not work.

The 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 [https://emscripten.org/docs/porting/networking.html] for more information. WASI snapshot preview 1 only permits sockets from an existing file descriptor.

Some functions are stubs that either don't do anything and always return hardcoded values.

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.

組み込み関数

Python インタプリタには数多くの関数と型が組み込まれており、いつでも利用できます。それらをここにアルファベット順に挙げます。

組み込み関数

A

abs()

aiter()

all()

anext()

any()

ascii()

B

bin()

bool()

breakpoint()

bytearray()

bytes()

C

callable()

chr()

classmethod()

compile()

complex()

D

delattr()

dict()

dir()

divmod()

E

enumerate()

eval()

exec()

F

filter()

float()

format()

frozenset()

G

getattr()

globals()

H

hasattr()

hash()

help()

hex()

I

id()

input()

int()

isinstance()

issubclass()

iter()

L

len()

list()

locals()

M

map()

max()

memoryview()

min()

N

next()

O

object()

oct()

open()

ord()

P

pow()

print()

property()

R

range()

repr()

reversed()

round()

S

set()

setattr()

slice()

sorted()

staticmethod()

str()

sum()

super()

T

tuple()

type()

V

vars()

Z

zip()

_

__import__()

abs(x)

数の絶対値を返します。引数は整数、浮動小数点数または __abs__() が実装されたオブジェクトです。引数が複素数なら、その絶対値 (magnitude) が返されます。

aiter(async_iterable)

asynchronous iterable から asynchronous iterator を返します。 x.__aiter__() を呼び出すのと等価です。

なお、 iter() とは異なり、 aiter() は第二引数を持ちません。

Added in version 3.10.

all(iterable)

iterable の全ての要素が真ならば (もしくは iterable が空ならば) True を返します。以下のコードと等価です:

def all(iterable):
    for element in iterable:
        if not element:
            return False
    return True

awaitable anext(async_iterator)

awaitable anext(async_iterator, default)

待ち受け中に、与えられた非同期イテレータ (asynchronous iterator) を返します。イテレータが枯渇した場合、 default が与えられていれば default を返します。

これは組み込みの next() 関数の非同期版であり、同じように動作します。

これは async_iterator の __anext__() メソッドを呼び出し、待ち受け可能オブジェクト (awaitable) を返します。待ち受けることによりイテレータの次の値を返します。 default が与えられた場合、イテレータが枯渇したときにその値が返されます。 default が与えられない場合は StopAsyncIteration が送出されます。

Added in version 3.10.

any(iterable)

iterable のいずれかの要素が真ならば True を返します。iterable が空なら False を返します。以下のコードと等価です:

def any(iterable):
    for element in iterable:
        if element:
            return True
    return False

ascii(object)

repr() と同様、オブジェクトの印字可能な表現を含む文字列を返しますが、repr() によって返された文字列中の非 ASCII 文字は \x 、 \u 、 \U エスケープを使ってエスケープされます。これは Python 2 の repr() によって返されるのと同じ文字列を作ります。

bin(x)

整数を先頭に "0b" が付いた 2 進文字列に変換します。結果は Python の式としても使える形式になります。 x が Python の int オブジェクトでない場合、整数を返す __index__() メソッドが定義されていなければなりません。いくつかの例を示します:

>>> bin(3)
'0b11'
>>> bin(-10)
'-0b1010'

先頭に "0b" が付いて欲しい、もしくは付いて欲しくない場合には、次の方法のどちらでも使えます。

>>> format(14, '#b'), format(14, 'b')
('0b1110', '1110')
>>> f'{14:#b}', f'{14:b}'
('0b1110', '1110')

より詳しいことは format() も参照してください。

class bool(x=False)

真偽値、すなわち True か False のいずれかを返します。 x は標準の 真偽値判定手続き を用いて変換されます。 x が偽かまたは省略された場合、この関数は False を返します。それ以外の場合は True を返します。 bool クラスは int クラスの派生クラスです (数値型 int, float, complex を参照してください)。このクラスからさらに派生することはできません。このクラスのインスタンスは False と True の身です (ブーリアン型 - bool を参照してください)。

バージョン 3.7 で変更: x は位置専用引数になりました。

breakpoint(*args, **kws)

この関数は、呼び出された箇所から処理をデバッガに移行します。より具体的には、この関数は sys.breakpointhook() を args と kws をそのまま渡して呼び出します。デフォルトでは、 sys.breakpointhook() は引数なしで pdb.set_trace() を呼び出すだけです。そのような場合、この関数は pdb を明示的にインポートしたり、デバッガに処理を移行するためのコードを書いたりしなくても済むようにするだけの、ただの便利な関数です。しかし sys.breakpointhook() を別の関数に設定して breakpoint() が自動的に呼び出させるようにすると、自分好みのデバッガに処理を移行させることができます。 sys.breakpointhook() にアクセスできない場合、この関数は RuntimeError を送出します。

デフォルトでは、環境変数 PYTHONBREAKPOINT をセットすることで breakpoint() の動作を変えることができます。使い方の詳細は sys.breakpointhook() を参照してください。

ただし、 sys.breakpointhook() が別の関数で置き換えられている場合、上記の環境変数によって必ずしも動作を変えることができないことに注意してください。

引数 breakpointhook 付きで 監査イベント builtins.breakpoint を送出します。

Added in version 3.7.

class bytearray(source=b'')

class bytearray(source, encoding)

class bytearray(source, encoding, errors)

新しいバイト配列を返します。bytearray クラスは0 <= x < 256の範囲の整数からなる変更可能な配列です。ミュータブルなシーケンス型 に記述されている変更可能な配列に対する普通のメソッドの大半を備えています。また、bytes 型が持つメソッドの大半も備えています（see bytes と bytearray の操作)。

オプションの source 引数は、配列を異なる方法で初期化するのに使われます:

文字列 の場合、 encoding (と、オプションの errors) 引数も与えなければなりません。このとき bytearray() は文字列を str.encode() でバイトに変換して返します。

整数 の場合、配列はそのサイズになり、null バイトで初期化されます。

バッファインターフェース に適合するオブジェクトの場合、そのオブジェクトの読み出し専用バッファがバイト配列の初期化に使われます。

イテラブル の場合、範囲 0 <= x < 256 内の整数のイテラブルでなければならず、それらが配列の初期の内容として使われます。

引数がなければ、長さ 0 の配列が生成されます。

バイナリシーケンス型 --- bytes, bytearray, memoryview と bytearray オブジェクト も参照してください。

class bytes(source=b'')

class bytes(source, encoding)

class bytes(source, encoding, errors)

範囲 0 <= x < 256 の整数のイミュータブルなシーケンスである "bytes" オブジェクトを返します。 bytes は bytearray のイミュータブル版であり、オブジェクトを変化させないメソッドや、インデックス指定、オブジェクトのスライスについてのふるまいは同じです。

従って、コンストラクタ引数は bytearray() のものと同様に解釈されます。

バイト列オブジェクトはリテラルでも生成できます。 文字列およびバイト列リテラル を参照してください。

バイナリシーケンス型 --- bytes, bytearray, memoryview, バイトオブジェクト, bytes と bytearray の操作 も参照してください。

callable(object)

object 引数が呼び出し可能オブジェクトであれば True を、そうでなければ False を返します。この関数が True を返しても、呼び出しは失敗する可能性がありますが、False であれば、 object の呼び出しは決して成功しません。なお、クラスは呼び出し可能 (クラスを呼び出すと新しいインスタンスを返します) です。また、インスタンスはクラスが __call__() メソッドを持つなら呼び出し可能です。

Added in version 3.2: この関数は Python 3.0 で一度取り除かれましたが、Python 3.2 で復活しました。

chr(i)

Unicode コードポイントが整数 i である文字を表す文字列を返します。例えば chr(97) は文字列 'a' を、 chr(8364) は文字列 '€' を返します。 ord() の逆です。

引数の有効な範囲は 0 から 1,114,111 (16 進数で 0x10FFFF) です。 i が範囲外の場合 ValueError が送出されます。

@classmethod

メソッドをクラスメソッドへ変換します。

クラスメソッドは、インスタンスメソッドが暗黙の第一引数としてインスタンスをとるように、第一引数としてクラスをとります。クラスメソッドを宣言するには、以下のイディオムを使います:

class C:
    @classmethod
    def f(cls, arg1, arg2): ...

@classmethod 形式は関数 デコレータ です。詳しくは 関数定義 を参照してください。

クラスメソッドは、(C.f() のように) クラスから呼び出すことも、(C().f() のように) インスタンスから呼び出すこともできます。インスタンスはそのクラスが何であるかを除いて無視されます。クラスメソッドが派生クラスから呼び出される場合は、その派生クラスオブジェクトが暗黙の第一引数として渡されます。

クラスメソッドは C++ や Java の静的メソッドとは異なります。静的メソッドは、この節の staticmethod() を参照してください。クラスメソッドについてより詳しいことは 標準型の階層 を参照してください。

バージョン 3.9 で変更: クラスメソッドは property() など、他の デスクリプタ をラップすることができるようになりました。

バージョン 3.10 で変更: クラスメソッドはメソッド属性 (__module__, __name__, __qualname__, __doc__ や __annotations__) を引き継ぐようになりました。また、新たに __wrapped__ 属性を持つようになりました。

バージョン 3.11 で変更: クラスメソッドは property() など、他の デスクリプタ をラップすることができなくなりました。

compile(source, filename, mode, flags=0, dont_inherit=False, optimize=-1)

source をコードオブジェクト、もしくは、 AST オブジェクトにコンパイルします。 コードオブジェクトは exec() 文で実行したり、 eval() 呼び出しで評価できます。 source は通常の文字列、 バイト列、 AST オブジェクトのいずれでもかまいません。 AST オブジェクトへの、また、 AST オブジェクトからのコンパイルの方法は、 ast モジュールのドキュメントを参照してください。

filename 引数には、コードの読み出し元のファイルを与えなければなりません; ファイルから読み出されるのでなければ、認識可能な値を渡して下さい ('<string>' が一般的に使われます)。

mode 引数は、コンパイルされるコードの種類を指定します; source が一連の文から成るなら 'exec' 、単一の式から成るなら 'eval' 、単一の対話的文の場合 'single' です。(後者の場合、評価が None 以外である式文が印字されます)。

オプション引数 flags と dont_inherit は、どの コンパイラオプション を有効化するか、 将来の機能 のどれを許可するかを制御します。どちらの引数も存在しない (またはどちらもゼロである) 場合は、 compile() の呼び出し元のコードに作用したものと同じフラグでコンパイルされます。 flags 引数が与えられて dont_inherit が与えられない (またはゼロ) の場合、上記に加えて flags 引数で与えられたコンパイラオプションと future 文が使われます。 dont_inherit がゼロでない整数の場合、 flags 引数で指定されたオプションだけが有効です -- 呼び出し元コードに適用されたフラグ (将来の機能とコンパイラオプション) は無視されます。

有効化するコンパイラオプションと future 文はビットフィールドで指定可能で、ビット単位の OR をとることで複数のオプションを一緒に指定することができます。特定の future 機能を指定するために必要なビットフィールドの情報は、 __future__ モジュールにおける _Feature インスタンスの compiler_flag 属性で得ることができます。 コンパイラフラグ の情報は ast モジュールの PyCF_ で始まるフラグで得ることができます。

引数 optimize は、コンパイラの最適化レベルを指定します; デフォルトの値 -1 は、インタプリタの -O オプションで与えられるのと同じ最適化レベルを選びます。明示的なレベルは、 0 (最適化なし、 __debug__ は真)、 1 (assert は取り除かれ、 __debug__ は偽)、 2 (docstring も取り除かれる) です。

この関数は、コンパイルされたソースが不正である場合 SyntaxError を、ソースがヌルバイトを含む場合 ValueError を送出します。

Python コードをパースしてその AST 表現を得たいのであれば、 ast.parse() を参照してください。

引数 source, filename を指定して 監査イベント compile を送出します。

注釈

複数行に渡るコードの文字列を 'single' や 'eval' モードでコンパイルするとき、入力は一つ以上の改行文字で終端されなければなりません。これは、 code モジュールで不完全な文と完全な文を検知しやすくするためです。

警告

AST オブジェクトにコンパイルしているときに、十分に大きい文字列や複雑な文字列によって Python の抽象構文木コンパイラのスタックが深さの限界を越えることで、 Python インタプリタをクラッシュさせられます。

バージョン 3.2 で変更: Windows や Mac の改行も受け付けます。また 'exec' モードでの入力が改行で終わっている必要もありません。optimize 引数が追加されました。

バージョン 3.5 で変更: 以前は source にヌルバイトがあったときに TypeError を送出していました。

Added in version 3.8: ast.PyCF_ALLOW_TOP_LEVEL_AWAIT フラグを渡してトップレベルの await, async for, および async with のサポートを有効化することができるようになりました。

class complex(real=0, imag=0)

class complex(string)

値 real + imag*1j の複素数を返すか、文字列や数を複素数に変換します。第一引数が文字列なら、それが複素数と解釈され、この関数は第二引数無しで呼び出されなければなりません。第二引数は文字列であってはなりません。それぞれの引数は (複素数を含む) 任意の数値型です。 imag が省略された場合、標準の値はゼロで、このコンストラクタは int や float のような数値変換としてはたらきます。両方の引数が省略された場合、 0j を返します。

一般的な Python オブジェクト x に対して、 complex(x) は x.__complex__() に処理を委譲します。 __complex__() が定義されていない場合は __float__() にフォールバックします。 __float__() も定義されていない場合は __index__() にフォールバックします。

注釈

文字列から変換するとき、その文字列は中央の + や - 演算子の周りに空白を含んではなりません。例えば、complex('1+2j') はいいですが、complex('1 + 2j') は ValueError を送出します。

複素数型については 数値型 int, float, complex に説明があります。

バージョン 3.6 で変更: コードリテラル中で桁をグループ化するのにアンダースコアを利用できます。

バージョン 3.8 で変更: __complex__() と __float__() が定義されていない場合、 __index__() へフォールバックします。

delattr(object, name)

setattr() の親戚です。引数はオブジェクトと文字列です。文字列はオブジェクトの属性名のいずれかでなければなりません。対象のオブジェクトが許可する場合に限り、この関数は指定された名前の属性を削除します。たとえば、 delattr(x, 'foobar') は del x.foobar と等価です。 name は Python の識別子である必要はありません (setattr() を参照してください)。

class dict(**kwarg)

class dict(mapping, **kwarg)

class dict(iterable, **kwarg)

新しい辞書を作成します。 dict オブジェクトは辞書クラスです。このクラスに関するドキュメンテーションは dict と マッピング型 --- dict を参照してください。

他のコンテナについては、 ビルトインの list, set, tuple クラスおよび collections モジュールを参照してください。

dir()

dir(object)

引数がない場合、現在のローカルスコープにある名前のリストを返します。引数がある場合、そのオブジェクトの有効な属性のリストを返そうと試みます。

オブジェクトが __dir__() という名のメソッドを持つなら、そのメソッドが呼び出され、属性のリストを返さなければなりません。これにより、カスタムの __getattr__() や __getattribute__() 関数を実装するオブジェクトは、dir() が属性を報告するやり方をカスタマイズできます。

オブジェクトが __dir__() を提供しない場合、その型オブジェクトと、定義されていればオブジェクトの __dict__ 属性から、できるだけ情報を集めようとします。結果のリストは必ずしも完全ではなく、カスタムの __getattr__() を持つ場合は不正確かもしれません。

デフォルトの dir() メカニズムは、完全というより最重要な情報を作成しようとするため、異なる型のオブジェクトでは異なって振る舞います:

オブジェクトがモジュールオブジェクトの場合、リストにはモジュールの属性の名前が含まれます。

オブジェクトが型オブジェクトやクラスオブジェクトの場合、リストにはその属性の名前と、再帰的にたどったその基底クラスの属性が含まれます。

それ以外の場合には、リストにはオブジェクトの属性名、クラス属性名、再帰的にたどった基底クラスの属性名が含まれます。

返されるリストはアルファベット順に並べられています。例えば:

>>> 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']

注釈

dir() は主に対話プロンプトでの使用に便利なように提供されているので、厳密性や一貫性を重視して定義された名前のセットというよりも、むしろ興味を引くような名前のセットを返そうとします。また、この関数の細かい動作はリリース間で変わる可能性があります。例えば、引数がクラスであるとき、メタクラス属性は結果のリストに含まれません。

divmod(a, b)

2つの (複素数でない) 数を引数としてとり、整数の除法を行ったときの商と剰余からなる2つの数のペアを返します。被演算子の型が混ざっている場合、二項算術演算子での規則が適用されます。整数に対する結果は (a // b, a % b) と同じです。浮動小数点数では、結果は (q, a % b) とあらわされます。ただし q は通常 math.floor(a / b) で、それより 1 だけ小さくなることもあります。いずれにせよ q * b + a % b は a に非常に近い値になります。もし a % b がゼロでないときは、その符号は b と同じであり、かつ 0 <= abs(a % b) < abs(b) を満たします。

enumerate(iterable, start=0)

enumerate オブジェクトを返します。 iterable は、シーケンスか iterator か、あるいはイテレーションをサポートするその他のオブジェクトでなければなりません。 enumerate() によって返されたイテレータの __next__() メソッドは、 (デフォルトでは 0 となる start からの) カウントと、 iterable 上のイテレーションによって得られた値を含むタプルを返します。

>>> 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')]

次と等価です:

def enumerate(iterable, start=0):
    n = start
    for elem in iterable:
        yield n, elem
        n += 1

eval(expression, globals=None, locals=None)

パラメータ:

expression (str | code object) -- A Python expression.

globals (dict | None) -- The global namespace (default: None).

locals (mapping | None) -- The local namespace (default: None).

戻り値:

The result of the evaluated expression.

Raises:

Syntax errors are reported as exceptions.

globals と locals の2つの辞書をそれぞれグローバルとローカルの名前空間とし、expression 引数が Python 式 (技術的な言葉では条件のリスト) として評価されます。 globals 辞書が存在し、 __builtins__ をキーとして持たない場合は、そのキーの値として 組み込みモジュール builtins の辞書への参照が、expression が解析される前に挿入されます。これにより、 eval() に渡す前の globals に自身で定義した __builtins__ を定義することで、実行されるコードで利用可能な組み込み関数を制御することができます。 locals 辞書が省略された場合、 globals 辞書がデフォルトとして使われます。どちらの辞書も省略された場合、 eval() が呼び出された環境における globals と locals のもとで式が評価されます。 eval() は、その実行環境において、 ネストされたスコープ (ローカルでないオブジェクト) へのアクセスを持たないことに注意してください。

例:

>>> x = 1
>>> eval('x+1')
2

この関数は (compile() で生成されるような) 任意のコードオブジェクトを実行するのにも利用できます。この場合、文字列の代わりにコードオブジェクトを渡してください。このコードオブジェクトが、引数 mode を 'exec' としてコンパイルされている場合、 eval() の戻り値は None になります。

ヒント: exec() 関数により文の動的な実行がサポートされています。globals() および locals() 関数は、それぞれ現在のグローバルおよびローカルな辞書を返すので、それらを eval() や exec() に渡して使うことができます。

ソースコードとして文字列が与えられた場合、先頭と末尾の空白文字およびタブは取り去られます。

リテラルだけを含む式の文字列を安全に評価できる関数、 ast.literal_eval() も参照してください。

引数 code_object を指定して 監査イベント exec を送出します。

exec(object, globals=None, locals=None, /, *, closure=None)

This function supports dynamic execution of Python code. object must be either a string or a code object. If it is a string, the string is parsed as a suite of Python statements which is then executed (unless a syntax error occurs). [1] If it is a code object, it is simply executed. In all cases, the code that's executed is expected to be valid as file input (see the section ファイル入力 in the Reference Manual). Be aware that the nonlocal, yield, and return statements may not be used outside of function definitions even within the context of code passed to the exec() function. The return value is None.

どの場合でも、オプションの部分が省略されると、コードは現在のスコープ内で実行されます。 globals だけが与えられた場合、その値は辞書でなければならず (かつ辞書のサブクラスであってはならず)、グローバル変数とローカル変数の両方に使われます。 globals と locals の両方が与えられた場合、それぞれグローバル変数とローカル変数に使われます。 locals を指定する場合、その値はマップ型オブジェクトでなければなりません。モジュールレベルでは globals と locals は同じ辞書であることに留意してください。もし exec が globals と locals に異なる2つのオブジェクトを受け取った場合、コードはクラス定義に埋め込まれたかのように実行されます。

globals 辞書がキー __builtins__ に対する値を含まなければ、そのキーに対して、組み込みモジュール builtins の辞書への参照が挿入されます。ですから、実行されるコードを exec() に渡す前に、 globals に自作の __builtins__ 辞書を挿入することで、コードがどの組み込みを利用できるか制御できます。

引数 closure はクロージャ、すなわちセル変数のタプルを指定します。この引数は object が自由変数を含むコードオブジェクトである場合のみ有効です。タプルの長さはコードオブジェクトから参照されている自由変数の数と厳密に一致しなければなりません。

引数 code_object を指定して 監査イベント exec を送出します。

注釈

組み込み関数 globals() および locals() は、それぞれ現在のグローバルおよびローカルの辞書を返すので、それらを exec() の第二、第三引数にそのまま渡して使うと便利なことがあります。

注釈

The default locals act as described for function locals() below: modifications to the default locals dictionary should not be attempted. Pass an explicit locals dictionary if you need to see effects of the code on locals after function exec() returns.

バージョン 3.11 で変更: closure パラメータが追加されました。

filter(function, iterable)

iterable の要素のうち、 function が真であるものからイテレータを構築します。 iterable にはシーケンスか、イテレーションをサポートするコンテナか、イテレータを渡せます。 function が None のときは恒等関数が指定されたものとして扱われ、 iterable のうち偽であるものがすべて取り除かれます。

なお、filter(function, iterable) は、関数が None でなければジェネレータ式 (item for item in iterable if function(item)) と同等で、関数が None なら (item for item in iterable if item) と同等です。

逆の働きをする関数については、 itertools.filterfalse() を参照してください。 iterable の要素のうち、 function が偽であるものを返します。

class float(x=0.0)

数または文字列 x から生成された浮動小数点数を返します。

引数が文字列の場合、10進数でなければなりません。先頭に符号または空白を含んでもかまいません。符号は '+' か '-' のいずれかです。正符号 '+' は生成される値に対して何の効果もありません。引数は NaN (not-a-number) や正または負の無限大をあらわす文字列でもかまいません。より正確にいうと、入力は先頭と末尾の空白文字を除き、以下に示す floatvalue の生成規則に従う必要があります:

sign        ::=  "+" | "-"
infinity    ::=  "Infinity" | "inf"
nan         ::=  "nan"
digit       ::=  <a Unicode decimal digit, i.e. characters in Unicode general category Nd>
digitpart   ::=  digit (["_"] digit)*
number      ::=  [digitpart] "." digitpart | digitpart ["."]
exponent    ::=  ("e" | "E") ["+" | "-"] digitpart
floatnumber ::=  number [exponent]
floatvalue  ::=  [sign] (floatnumber | infinity | nan)

大文字と小文字は重要ではないので、例えば、 "inf", "Inf", "INFINITY", "iNfINity" はすべて正の無限大を表す綴りとして受け入れられます。

一方で、引数が整数または浮動小数点数なら、(Python の浮動小数点数の精度で) 同じ値の浮動小数点数が返されます。引数が Python の浮動小数点数の範囲外なら、 OverflowError が送出されます。

一般の Python オブジェクト x に対して、float(x) は x.__float__() に委譲します。 __float__() が定義されていない場合、__index__() へフォールバックします。

引数が与えられなければ、0.0 が返されます。

例:

>>> float('+1.23')
1.23
>>> float('   -12345\n')
-12345.0
>>> float('1e-003')
0.001
>>> float('+1E6')
1000000.0
>>> float('-Infinity')
-inf

浮動小数点数型については、 数値型 int, float, complex も参照してください。

バージョン 3.6 で変更: コードリテラル中で桁をグループ化するのにアンダースコアを利用できます。

バージョン 3.7 で変更: x は位置専用引数になりました。

バージョン 3.8 で変更: __float__() が定義されていない場合、 __index__() へフォールバックします。

format(value, format_spec='')

value を format_spec で指示された通りに "整形" した文字列表現に変換します。 format_spec の解釈は value 引数の型に依存しますが、ほとんどの組み込み型で使われる標準的な構文が存在します: 書式指定ミニ言語仕様。

デフォルトの format_spec は空の文字列です。それは通常 str(value) の呼び出しと同じ結果になります。

format(value, format_spec) の呼び出しは、 type(value).__format__(value, format_spec) に翻訳され、これは value の __format__() メソッドの検索をするとき、インスタンス辞書を回避します。このメソッドの探索が object に到達しても format_spec が空にならなかったり、 format_spec や返り値が文字列でなかったりした場合、 TypeError が送出されます。

バージョン 3.4 で変更: format_spec が空の文字列でない場合 object().__format__(format_spec) は TypeError を送出します。

class frozenset(iterable=set())

新しい frozenset オブジェクトを返します。オプションで iterable から得られた要素を含みます。 frozenset はビルトインクラスです。このクラスに関するドキュメントは frozenset と set（集合）型 --- set, frozenset を参照してください。

他のコンテナについては、ビルトインクラス set, list, tuple, dict や collections モジュールを見てください。

getattr(object, name)

getattr(object, name, default)

object の指定された属性の値を返します。 name は文字列でなければなりません。与えられた文字列がオブジェクトの属性名のうちいずれかに一致すれば、戻り値はその属性の値になります。たとえば、 getattr(x, 'foobar') は x.foobar と等価です。もし指定された属性が存在しない場合、 default が指定されていればその値が返されます。そうでない場合は AttributeError が送出されます。 name は Python 識別子である必要はありません (setattr() を参照してください)。

注釈

プライベートな名前のマングリング はコンパイル時に行われます。そのため、プライベートな属性 (先頭に2つのアンダースコアを伴う名前を持つ属性) の値を getattr() で取り出すためには、属性名を手動でマングリングする必要があります。

globals()

現在のモジュールの名前空間を実装した辞書を返します。関数内のコードに対しては、関数が定義されるときに辞書が設定され、その関数がどこから呼ばれたかにかかわらず同じ内容になります。

hasattr(object, name)

引数はオブジェクトと文字列です。文字列がオブジェクトの属性名の一つであった場合 True を、そうでない場合 False を返します。 (この関数は、 getattr(object, name) を呼び出して AttributeError を送出するかどうかを見ることで実装されています。)

hash(object)

オブジェクトのハッシュ値を (存在すれば) 返します。ハッシュ値は整数です。これらは辞書を検索する際に辞書のキーを高速に比較するために使われます。等しい値となる数値は等しいハッシュ値を持ちます (1 と 1.0 のように型が異なっていてもです)。

注釈

独自の __hash__() メソッドを実装したオブジェクトを使う場合、hash() が実行するマシンのビット幅に合わせて戻り値を切り捨てることに注意してください。

help()

help(request)

組み込みヘルプシステムを起動します。(この関数は対話的な使用のためのものです。) 引数が与えられていない場合、対話的ヘルプシステムはインタプリタコンソール上で起動します。引数が文字列の場合、文字列はモジュール、関数、クラス、メソッド、キーワード、またはドキュメントの項目名として検索され、ヘルプページがコンソール上に印字されます。引数がその他のオブジェクトの場合、そのオブジェクトに関するヘルプページが生成されます。

help() を呼び出したときに関数の引数リストにスラッシュ (/) が現れた場合は、スラッシュより前の引数が位置専用引数だという意味であることに注意してください。より詳しい情報は、 位置専用引数についての FAQ の項目 を参照してください。

この関数は、 site モジュールから、組み込みの名前空間に移されました。

バージョン 3.4 で変更: pydoc と inspect への変更により、呼び出し可能オブジェクトの報告されたシグニチャがより包括的で一貫性のあるものになりました。

hex(x)

整数を先頭に "0x" が付いた小文字の 16 進文字列に変換します。 x が Python の int オブジェクトでない場合、整数を返す __index__() メソッドが定義されていなければなりません。いくつかの例を示します:

>>> hex(255)
'0xff'
>>> hex(-42)
'-0x2a'

整数を大文字の 16 進文字列や小文字の 16 進文字列、先頭の "0x" 付きや "0x" 無しに変換したい場合は、次に挙げる方法が使えます:

>>> '%#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')

より詳しいことは format() も参照してください。

16を底として16進数文字列を整数に変換するには int() も参照してください。

注釈

浮動小数点数の16進文字列表記を得たい場合には、 float.hex() メソッドを使って下さい。

id(object)

オブジェクトの "識別値" を返します。この値は整数で、このオブジェクトの有効期間中は一意かつ定数であることが保証されています。有効期間が重ならない 2 つのオブジェクトは同じ id() 値を持つかもしれません。

CPython 実装の詳細: これはオブジェクトのメモリアドレスです。

引数 id を指定して 監査イベント builtins.id を送出します。

input()

input(prompt)

引数 prompt が存在すれば、それが末尾の改行を除いて標準出力に書き出されます。次に、この関数は入力から 1 行を読み込み、文字列に変換して (末尾の改行を除いて) 返します。 EOF が読み込まれたとき、 EOFError が送出されます。例:

>>> s = input('--> ')
--> Monty Python's Flying Circus
>>> s
"Monty Python's Flying Circus"

readline モジュールが読み込まれていれば、 input() はそれを使って精緻な行編集やヒストリ機能を提供します。

引数 prompt 付きで 監査イベント builtins.input を送出します。

引数 result 付きで 監査イベント builtins.input/result を送出します。

class int(x=0)

class int(x, base=10)

数値または文字列 x から作成された整数オブジェクトを返します。引数が与えられない場合には 0 を返します。 x に __int__() が定義されている場合は、 int(x) は x.__int__() を返します。 x に __index__() が定義されている場合は、 x.__index__() を返します。 x に __trunc__() が定義されている場合は、 x.__trunc__() を返します。浮動小数点数については、これは 0 に近い側へ切り捨てます。

x が数値でないか、または base が与えられた場合、 x は base を基数とした整数を表現する文字列、 bytes インスタンス、または bytearray インスタンスのいずれかでなければなりません。文字列は先頭に + or - を伴ったり (符号と数値の間に空白文字を入れてはいけません)、数値の先頭に任意の数のゼロを付けたり、前後に空白文字を付けたり、各桁を単一の下線で区切ったりしても有効です。

n-進数の整数文字列は、各桁が0から n-1 の数値で表されます。ユニコードの10進数では、各桁は0から9のいずれかです。また10から35までの値は a から z (または A から Z) で表されます。デフォルトの base は10です。基数に指定可能な値は0および2から36までの整数です。2進数、8進数、16進数の文字列は、整数リテラルと同様に、それぞれ 0b/0B, 0o/0O, または 0x/0X をプレフィックスとして追加することができます。基数を0に指定した場合、文字列は コードにおける整数リテラル と同じように解釈されます。すなわち、プレフィックスによって基数が2, 8, 10, または 16 のどれになるかが決まります。基数を0にした場合先頭にゼロを追加することはできません: すなわち int('010', 0) は基数を0に指定しているため不正ですが、 int('010') や int('010', 8) は有効です。

整数型については、 数値型 int, float, complex も参照してください。

バージョン 3.4 で変更: base が int のインスタンスでなく、base オブジェクトが base.__index__ メソッドを持っている場合、そのメソッドを呼んで底に対する整数を得ることができます。以前のバージョンでは base.__index__ ではなく base.__int__ を使用していました。

バージョン 3.6 で変更: コードリテラル中で桁をグループ化するのにアンダースコアを利用できます。

バージョン 3.7 で変更: x は位置専用引数になりました。

バージョン 3.8 で変更: __int__() が定義されていない場合、 __index__() へフォールバックします。

バージョン 3.11 で変更: __trunc__() への処理の委譲は非推奨になりました。

バージョン 3.11 で変更: int への文字列入力やその文字列表現は、サービス拒否攻撃 (DoS 攻撃) を避けるために制限されることがあります。文字列 x を int に変換したり int を文字列に変換したりする際にその制限を超えた場合、 ValueError が送出されます。詳しくは 整数文字列の変換における長さ制限 を参照してください。

isinstance(object, classinfo)

object 引数が classinfo 引数に指定した型、またはその (直接、間接、または 仮想 の) サブクラスのインスタンスである場合に True を返します。 object が与えられた型のオブジェクトでない場合、この関数は常に False を返します。 classinfo が型オブジェクトのタプル (または再帰的にそのようなタプルを含むタプル) や複数の型の Union 型 である場合、 object がそれらの型のいずれかのインスタンスであれば True を返します。 classinfo が型や型からなるタプルまたは再帰的タプルのいずれでもない場合、 TypeError 例外が送出されます。タプルの中で先行する型に対するチェックが成功した場合、後続の不正な型に対して TypeError が送出されないことがあります。

バージョン 3.10 で変更: classinfo に Union 型 を指定できるようになりました。

issubclass(class, classinfo)

class が classinfo の (直接、間接、または 仮想 の) サブクラスである場合に True を返します。クラスは自身のサブクラスとみなされます。 classinfo はクラスオブジェクトのタプル (または再帰的にそのようなタプルを含むタプル) やクラスオブジェクトの Union 型 でもよく、この場合は class が classinfo のいずれかのクラスのサブクラスであれば True を返します。上記以外の値が指定された場合、 TypeError 例外が送出されます。

バージョン 3.10 で変更: classinfo に Union 型 を指定できるようになりました。

iter(object)

iter(object, sentinel)

iterator オブジェクトを返します。第二引数があるかどうかによって第一引数の解釈は大きく異なります。第二引数がない場合、 object は iterable プロトコル (__iter__() メソッド) をサポートするコレクションオブジェクトか、またはシーケンスプロトコル (0 から始まる整数を引数にとる __getitem__() メソッド) をサポートするオブジェクトでなければなりません。第一引数がどちらのプロトコルもサポートしない場合は TypeError 例外が送出されます。第二引数 sentinel が与えられた場合、 object は呼び出し可能オブジェクトでなければなりません。この場合に生成されるイテレータは __next__() メソッドを呼び出すごとに引数なしで object を呼び出します; 戻り値が sentinel と等しければ、 StopIteration が送出されます。それ以外の場合は戻り値がそのまま返されます。

イテレータ型 も見てください。

2引数形式の iter() の便利な利用方法の1つは、ブロックリーダーの構築です。例えば、バイナリのデータベースファイルから固定幅のブロックをファイルの終端に到達するまで読み出すには次のようにします:

from functools import partial
with open('mydata.db', 'rb') as f:
    for block in iter(partial(f.read, 64), b''):
        process_block(block)

len(s)

オブジェクトの長さ (要素の数) を返します。引数はシーケンス (文字列、バイト列、タプル、リスト、range 等) かコレクション (辞書、集合、凍結集合等) です。

CPython 実装の詳細: len は、例えば range(2 ** 100) のような、 sys.maxsize を超える長さに対して OverflowError を送出します。

class list

class list(iterable)

list は、実際には関数ではなくミュータブルなシーケンス型で、 リスト型 (list) と シーケンス型 --- list, tuple, range にドキュメント化されています。

locals()

Update and return a dictionary representing the current local symbol table. Free variables are returned by locals() when it is called in function blocks, but not in class blocks. Note that at the module level, locals() and globals() are the same dictionary.

注釈

The contents of this dictionary should not be modified; changes may not affect the values of local and free variables used by the interpreter.

map(function, iterable, *iterables)

function を iterable の全ての要素に適用して結果を生成 (yield) するイテレータを返します。追加の iterables 引数が渡された場合、 function は渡されたイテラブルと同じ数の引数を取らなければならず、関数は全てのイテラブルから並行して得られた要素の組に対して適用されます。複数のイテラブルが渡された場合、そのうちで最も短いイテラブルが使い尽くされた段階で止まります。関数の入力が引数タプルとして単一のイテラブルの形で整理されている場合は、 itertools.starmap() を参照してください。

max(iterable, *, key=None)

max(iterable, *, default, key=None)

max(arg1, arg2, *args, key=None)

iterable の中で最大の要素、または2つ以上の引数の中で最大のものを返します。

位置引数が1つだけ与えられた場合、それは空でない iterable でなくてはいけません。その iterable の最大の要素が返されます。2 つ以上のキーワード無しの位置引数が与えられた場合、その位置引数の中で最大のものが返されます。

任意のキーワード専用引数が 2 つあります。 key 引数は引数を 1 つ取る順序関数 (list.sort() のもののように) を指定します。 default 引数は与えられたイテラブルが空の場合に返すオブジェクトを指定します。イテラブルが空で default が与えられていない場合 ValueError が送出されます。

最大の要素が複数あるとき、この関数はそのうち最初に現れたものを返します。これは、sorted(iterable, key=keyfunc, reverse=True)[0] や heapq.nlargest(1, iterable, key=keyfunc) のような、他のソート安定性を維持するツールと両立します。

バージョン 3.4 で変更: キーワード専用引数 default が追加されました。

バージョン 3.8 で変更: key 引数が None であることを許容します。

class memoryview(object)

与えられたオブジェクトから作られた "メモリビュー" オブジェクトを返します。詳しくは メモリビュー を参照してください。

min(iterable, *, key=None)

min(iterable, *, default, key=None)

min(arg1, arg2, *args, key=None)

iterable の中で最小の要素、または2つ以上の引数の中で最小のものを返します。

位置引数が1つだけ与えられた場合、それは空でない iterable でなくてはいけません。その iterable の最小の要素が返されます。2 つ以上のキーワード無しの位置引数が与えられた場合、その位置引数の中で最小のものが返されます。

任意のキーワード専用引数が 2 つあります。 key 引数は引数を 1 つ取る順序関数 (list.sort() のもののように) を指定します。 default 引数は与えられたイテラブルが空の場合に返すオブジェクトを指定します。イテラブルが空で default が与えられていない場合 ValueError が送出されます。

最小の要素が複数あるとき、この関数はそのうち最初に現れたものを返します。これは、sorted(iterable, key=keyfunc)[0] や heapq.nsmallest(1, iterable, key=keyfunc) のような、他のソート安定性を維持するツールと両立します。

バージョン 3.4 で変更: キーワード専用引数 default が追加されました。

バージョン 3.8 で変更: key 引数が None であることを許容します。

next(iterator)

next(iterator, default)

iterator の __next__() メソッドを呼び出すことにより、次の要素を取得します。イテレータが使い尽くされた場合、 default が与えられていればその値が返されます。そうでない場合は StopIteration が送出されます。

class object

何の機能も持たない新しいオブジェクトを返します。 object は全てのクラスの基底クラスです。これは、全ての Python クラスのインスタンスに共通のメソッド群を持ちます。この関数はいかなる引数も受け付けません。

注釈

object は __dict__ を 持たない ので、 object クラスのインスタンスに任意の属性を代入することはできません。

oct(x)

整数を先頭に "0o" が付いた 8 進文字列に変換します。結果は Python の式としても使える形式になります。 x が Python の int オブジェクトでない場合、整数を返す __index__() メソッドが定義されていなければなりません。例えば、次のようになります:

>>> oct(8)
'0o10'
>>> oct(-56)
'-0o70'

整数を接頭辞 "0o" 付きや "0o" 無しの 8 進文字列に変換したい場合は、次に挙げる方法のいずれかを使ってください。

>>> '%#o' % 10, '%o' % 10
('0o12', '12')
>>> format(10, '#o'), format(10, 'o')
('0o12', '12')
>>> f'{10:#o}', f'{10:o}'
('0o12', '12')

より詳しいことは format() も参照してください。

open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)

file を開き、対応する ファイルオブジェクト を返します。ファイルを開くことができなければ、OSError が送出されます。この関数の利用例について、 ファイルを読み書きする を参照してください。

file は path-like object で、開くファイルのパス名 (絶対パスまたは現在の作業ディレクトリからの相対パス) あるいはラップするファイルの整数のファイルデスクリプタを与えます。 (ファイルデスクリプタが与えられた場合、 closefd が False に設定されていないかぎり、この関数が返す I/O オブジェクトがクローズされるときにファイルデスクリプタもクローズされます。)

mode はファイルが開かれる際のモードを指定するオプションの文字列です。デフォルトは 'r' で、読み込み用にテキストモードで開くという意味です。その他によく使われるモードは、書き込み用の 'w' (ファイルが既に存在する場合は上書きします)、排他的な生成をあらわす 'x' 、そして追記用の 'a' (いくつかの Unix システムで、 すべての 書き込みは現在のシーク位置にかかわらずファイルの末尾に追記する、という意味です) です。テキストモードで encoding が指定されない場合に使われるエンコーディングは、プラットフォーム依存です: 現在のロケールエンコーディングを取得するために locale.getencoding() が呼ばれます。 (生のバイトデータを読み書きする際にはバイナリモードを使います。このときは encoding は未指定のままとします。) 指定可能なモードは以下の通りです:

文字

意味

'r'

読み込み用に開く (デフォルト)

'w'

書き込み用に開き、まずファイルを切り詰める

'x'

排他的な生成に開き、ファイルが存在する場合は失敗する

'a'

書き込み用に開き、ファイルが存在する場合には末尾に追記する

'b'

バイナリモード

't'

テキストモード (デフォルト)

'+'

更新用に開く (読み込み・書き込み用)

デフォルトのモードは 'r' (テキストの読み込み用に開く、 'rt' と同義) です。 'w+' と 'w+b' はファイルを開いて上書きします。 'r+' と 'r+b' はファイルを上書きせずに開きます。

概要 で触れられているように、Python はバイナリとテキストの I/O を区別します。(mode 引数に 'b' を含めて) バイナリモードで開かれたファイルは、内容をいかなるデコーディングもせずに bytes オブジェクトとして返します。(デフォルトや、 mode 引数に 't' が含まれたときの) テキストモードでは、ファイルの内容は str として返され、バイト列はまず、プラットフォーム依存のエンコーディングか、encoding が指定された場合は指定されたエンコーディングを使ってデコードされます。

注釈

Python は、下層のオペレーティングシステムがテキストファイルをどう認識するかには依存しません; すべての処理は Python 自身で行われ、よってプラットフォーム非依存です。

buffering はオプションの整数で、バッファリングのポリシーを設定するために使われます。 バッファリングを無効化するためには0を渡してください (バイナリモードでのみ設定可能です)。また行単位でのバッファリングには1を設定してください (テキストモードでの書き込み時のみ有効です)。固定サイズのチャンクバッファに対するサイズをバイト単位で指定したい場合は、1より大きい整数を渡してください。この形式でバッファサイズを指定した場合、バイナリ形式でバッファリングをサポートする I/O (buffered I/O) にはそのまま適用されますが、 TextIOWrapper (すなわち mode='r+' のモードでオープンされたファイル) では別のバッファリングを行うかもしれません。 TextIOWrapper でバッファリングを無効化するには、 io.TextIOWrapper.reconfigure() で write_through フラグを使うことを検討してください。 buffering 引数が与えられなかった場合、デフォルトのバッファリングポリシーは以下のように動作します:

バイナリファイルは固定サイズのチャンクでバッファリングされます。バッファサイズは、下層のデバイスの「ブロックサイズ」を決定するヒューリスティックを用いて選択され、それが不可能な場合は代わりに io.DEFAULT_BUFFER_SIZE が使われます。多くのシステムでは、バッファサイズは通常 4096 か 8192 バイト長です。

「対話的な」テキストファイル (isatty() が True を返すファイル) は行バッファリングを使用します。 その他のテキストファイルは、上で説明したバイナリファイル用の方針を使用します。

encoding はファイルのエンコードやデコードに使われる text encoding の名前です。このオプションはテキストモードでのみ使用してください。デフォルトエンコーディングはプラットフォーム依存 (locale.getencoding() が返すもの) ですが、Pythonでサポートされているエンコーディングはどれでも使えます。詳しくは codecs モジュール内のサポートしているエンコーディングのリストを参照してください。

errors はオプションの文字列で、エンコードやデコードでのエラーをどのように扱うかを指定するものです。バイナリモードでは使用できません。様々な標準のエラーハンドラが使用可能です (エラーハンドラ に列記されています) が、 codecs.register_error() に登録されているエラー処理の名前も使用可能です。標準のエラーハンドラの名前には、以下のようなものがあります:

'strict' はエンコーディングエラーがあると例外 ValueError を発生させます。デフォルト値である None も同じ効果です。

'ignore' はエラーを無視します。エンコーディングエラーを無視することで、データが失われる可能性があることに注意してください。

'replace' は、不正な形式のデータが存在した場所に('?' のような) 置換マーカーを挿入します。

'surrogateescape' は正しくないバイト列をユニコードの下位サロゲート領域のうち U+DC80 から U+DCFF の範囲のコードユニットであらわします。データの書き込み時に surrogateescape エラーハンドラが使われると、これらのサロゲートコードユニットは元と同じバイト列に変換されます。これはエンコーディングが不明なファイルを処理するのに便利です。

'xmlcharrefreplace' はファイルへの書き込み時のみサポートされます。そのエンコーディングでサポートされない文字は、&#nnn; 形式の適切な XML 文字参照で置換されます。

'backslashreplace' は不正なデータを Python のバックスラッシュ付きのエスケープシーケンスで置換します。

'namereplace' (書き込み時のみサポートされています) はサポートされていない文字を \N{...} エスケープシーケンスで置換します。

newline はストリームから受け取った改行文字をどのようにパースするかを決定します。 None, '', '\n', '\r', または '\r\n' のいずれかを指定できます。これは以下のように動作します:

ストリームからの入力の読み込み時、newline が None の場合、ユニバーサル改行モードが有効になります。入力中の行は '\n', '\r', または '\r\n' で終わり、呼び出し元に返される前に '\n' に変換されます。 '' の場合、ユニバーサル改行モードは有効になりますが、行末は変換されずに呼び出し元に返されます。その他の正当な値の場合、入力行は与えられた文字列でのみ終わり、行末は変換されずに呼び出し元に返されます。

ストリームへの出力の書き込み時、newline が None の場合、全ての '\n' 文字はシステムのデフォルトの行セパレータ os.linesep に変換されます。 newline が '' または '\n' の場合は変換されません。newline がその他の正当な値の場合、全ての '\n' 文字は与えられた文字列に変換されます。

closefd が False で、ファイル名ではなくてファイル記述子が与えられた場合、下層のファイル記述子はファイルが閉じられた後も開いたままとなります。ファイル名が与えられた場合、closefd は True (デフォルト値) でなければなりません。そうでない場合エラーが送出されます。

呼び出し可能オブジェクトを opener として与えることで、カスタムのオープナーが使えます。そしてファイルオブジェクトの下層のファイル記述子は、opener を (file, flags) で呼び出して得られます。opener は開いたファイル記述子を返さなければなりません。 (os.open を opener として渡すと、None を渡したのと同様の機能になります)。

新たに作成されたファイルは 継承不可 です。

次の例は os.open() 関数の dir_fd 引数を使い、与えられたディレクトリからの相対パスで指定されたファイルを開きます:

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

open() 関数が返す file object の型はモードに依存します。 open() をファイルをテキストモード ('w', 'r', 'wt', 'rt', など) で開くのに使ったときは io.TextIOBase (特に io.TextIOWrapper) のサブクラスを返します。ファイルをバッファリング付きのバイナリモードで開くのに使ったときは io.BufferedIOBase のサブクラスを返します。実際のクラスは様々です。読み込みバイナリモードでは io.BufferedReader を返します。書き込みバイナリモードや追記バイナリモードでは io.BufferedWriter を返します。読み書きモードでは io.BufferedRandom を返します。バッファリングが無効なときはrawストリーム、すなわち io.RawIOBase のサブクラスである io.FileIO を返します。

fileinput 、(open() が宣言された場所である) io 、 os 、 os.path 、 tempfile 、 shutil などの、ファイル操作モジュールも参照してください。

引数 file, mode, flags を指定して 監査イベント open を送出します。

mode と flags の2つの引数は呼び出し時の値から修正されたり、推量により設定されたりする可能性があります。

バージョン 3.3 で変更:

opener 引数を追加しました。

'x' モードを追加しました。

以前は IOError が送出されました; それは現在 OSError のエイリアスです。

既存のファイルを 排他的生成モード('x')で開いた場合、 FileExistsError を送出するようになりました。

バージョン 3.4 で変更:

ファイルが継承不可になりました。

バージョン 3.5 で変更:

システムコールが中断されシグナルハンドラが例外を送出しなかった場合、この関数は InterruptedError 例外を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 [https://peps.python.org/pep-0475/] を参照してください)。

'namereplace' エラーハンドラが追加されました。

バージョン 3.6 で変更:

os.PathLike を実装したオブジェクトを受け入れるようになりました。

Windowsでは、コンソールバッファのオープンは、io.FileIO ではなく、io.RawIOBase のサブクラスを返すでしょう。

バージョン 3.11 で変更: 'U' モードは削除されました。

ord(c)

1 文字の Unicode 文字を表す文字列に対し、その文字の Unicode コードポイントを表す整数を返します。例えば、 ord('a') は整数 97 を返し、 ord('€') (ユーロ記号) は 8364 を返します。これは chr() の逆です。

pow(base, exp, mod=None)

base の exp 乗を返します; mod があれば、base の exp 乗に対する mod の剰余を返します (pow(base, exp) % mod より効率よく計算されます)。二引数の形式 pow(base, exp) は、冪乗演算子を使った base**exp と等価です。

引数は数値型でなければなりません。型混合の場合、二項算術演算における型強制規則が適用されます。 int オペランドの場合、第2引数が負でない限り、結果は (型強制後の) オペランドと同じ型になります; 第2引数が負の場合、全ての引数は浮動小数点数に変換され、浮動小数点数の結果が返されます。例えば、 pow(10, 2) は 100 を返しますが、 pow(10, -2) は 0.01 を返します。底が int 型または float 型で負の値であり、かつ指数が整数でない場合、複素数の結果が返されます。例えば、 pow(-9, 0.5) は 3j に近い値を返します。

base と exp が int オペランドで mod が存在するとき、 mod もまた整数型でなければならず、かつゼロであってはいけません。 mod が存在して exp が負の整数の場合、 base は mod と互いに素 (最大公約数が1) でなければなりません。この場合、 inv_base を base に対する mod を法とするモジュラ逆数 (base と inv_base の積を mod で割った余りが1になるような数) として、 pow(inv_base, -exp, mod) が返されます。

以下は 97 を法とする 38 のモジュラ逆数の計算例です:

>>> pow(38, -1, mod=97)
23
>>> 23 * 38 % 97 == 1
True

バージョン 3.8 で変更: int オペランドに対して、三引数形式の pow で第二引数に負の値を取ることができるようになりました。これによりモジュラ逆数の計算が可能になります。

バージョン 3.8 で変更: キーワード引数を取ることができるようになりました。以前は位置引数だけがサポートされていました。

print(*objects, sep=' ', end='\n', file=None, flush=False)

objects を sep で区切りながらテキストストリーム file に表示し、最後に end を表示します。sep 、 end 、 file 、 flush を与える場合、キーワード引数として与える必要があります。

キーワードなしの引数はすべて、 str() がするように文字列に変換され、 sep で区切られながらストリームに書き出され、最後に end が続きます。 sep と end の両方とも、文字列でなければなりません。これらを None にすると、デフォルトの値が使われます。 objects が与えられなければ、 print() は end だけを書き出します。

file 引数は、 write(string) メソッドを持つオブジェクトでなければなりません。指定されないか、 None である場合、 sys.stdout が使われます。表示される引数は全てテキスト文字列に変換されますから、 print() はバイナリモードファイルオブジェクトには使用できません。代わりに file.write(...) を使ってください。

出力がバッファ化されるかどうかは通常 file で決まりますが、flush キーワード引数が真ならストリームは強制的にフラッシュされます。

バージョン 3.3 で変更: キーワード引数 flush が追加されました。

class property(fget=None, fset=None, fdel=None, doc=None)

property 属性を返します。

fget は属性値を取得するための関数です。fset は属性値を設定するための関数です。fdel は属性値を削除するための関数です。doc は属性の docstring を作成します。

典型的な使用法は、属性 x の処理の定義です:

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

c が C のインスタンスならば、c.x は getter を呼び出し、c.x = value は setter を、del c.x は deleter を呼び出します。

doc は、与えられれば property 属性のドキュメント文字列になります。与えられなければ、 property は fget のドキュメント文字列 (もしあれば) をコピーします。そのため property() を デコレータ として使えば、読み出し専用 property を作るのは容易です:

class Parrot:
    def __init__(self):
        self._voltage = 100000

    @property
    def voltage(self):
        """Get the current voltage."""
        return self._voltage

@property デコレータは voltage() を同じ名前のまま 読み出し専用属性の "getter" にし、voltage のドキュメント文字列を "Get the current voltage." に設定します。

@getter

@setter

@deleter

property オブジェクトは getter, setter, deleter メソッドを持っています。これらのメソッドをデコレータとして使うと、対応するアクセサ関数がデコレートされた関数に設定された、 property のコピーを作成できます。 これを一番分かりやすく説明する例があります:

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

このコードは最初の例と等価です。追加の関数には、必ず元の property と同じ名前 (この例では x) を与えて下さい。

返される property オブジェクトも、コンストラクタの引数に対応した fget, fset, および fdel 属性を持ちます。

バージョン 3.5 で変更: 属性オブジェクトのドックストリングが書き込み可能になりました。

class range(stop)

class range(start, stop, step=1)

range は、実際には関数ではなくイミュータブルなシーケンス型で、 range と シーケンス型 --- list, tuple, range にドキュメント化されています。

repr(object)

オブジェクトの印字可能な表現を含む文字列を返します。この関数は多くの型について、 eval() に渡されたときと同じ値を持つようなオブジェクトを表す文字列を生成しようとします。そうでない場合は、山括弧に囲まれたオブジェクトの型の名前と追加の情報 (大抵の場合はオブジェクトの名前とアドレスを含みます) を返します。クラスは、 __repr__() メソッドを定義することで、この関数によりそのクラスのインスタンスが返すものを制御することができます。sys.displayhook() にアクセスできない場合、この関数は RuntimeError を送出します。

このクラスは、eval 評価可能な独自の representation を持ちます:

class Person:
   def __init__(self, name, age):
      self.name = name
      self.age = age

   def __repr__(self):
      return f"Person('{self.name}', {self.age})"

reversed(seq)

要素を逆順に取り出すイテレータ (reverse iterator) を返します。 seq は __reversed__() メソッドを持つか、シーケンス型プロトコル ( __len__() メソッド、および、 0 以上の整数を引数とする __getitem__() メソッド) をサポートするオブジェクトでなければなりません。

round(number, ndigits=None)

number を小数点以下 ndigits 桁の精度で丸めた値を返します。ndigits が省略されたり、None だった場合、入力値に最も近い整数を返します。

round() をサポートする組み込み型では、値は 10 のマイナス ndigits 乗の倍数の中で最も近いものに丸められます; 二つの倍数が同じだけ近いなら、偶数を選ぶ方に (そのため、例えば round(0.5) と round(-0.5) は両方とも 0 に、 round(1.5) は 2 に) 丸められます。 ndigits には任意の整数値が有効となります (正の整数、ゼロ、負の整数)。返り値は ndigits が指定されていないか None の場合は整数、そうでなければ返り値は number と同じ型です。

一般的な Python オブジェクト number に対して、round は処理を number.__round__ に移譲します。

注釈

浮動小数点数に対する round() の振る舞いは意外なものかもしれません: 例えば、 round(2.675, 2) は予想通りの 2.68 ではなく 2.67 を与えます。これはバグではありません: これはほとんどの小数が浮動小数点数で正確に表せないことの結果です。詳しくは 浮動小数点演算、その問題と制限 を参照してください。

class set

class set(iterable)

オプションで iterable の要素を持つ、新しい set オブジェクトを返します。 set は組み込みクラスです。このクラスについて詳しい情報は set や set（集合）型 --- set, frozenset を参照してください。

他のコンテナについては collections モジュールや組み込みの frozenset 、 list 、 tuple 、 dict クラスを参照してください。

setattr(object, name, value)

getattr() の相方です。引数はオブジェクト、文字列、それから任意の値です。文字列は既存の属性または新たな属性の名前にできます。この関数は指定したオブジェクトが許せば、値を属性に関連付けます。例えば、 setattr(x, 'foobar', 123) は x.foobar = 123 と等価です。

__getattribute__() のカスタマイズや __slots__ を通じてオブジェクトが強制していない限り、 name は 識別子 (identifier) およびキーワード (keyword) で定義されている Python 識別子である必要はありません。属性名が識別子でない場合、ドットを使った属性へのアクセスはできませんが、 getattr() などを通じてアクセス可能です。

注釈

プライベートな名前のマングリング はコンパイル時に行われます。そのため、プライベートな属性 (先頭に2つのアンダースコアを伴う名前を持つ属性) の値を setattr() でセットするためには、属性名を手動でマングリングする必要があります。

class slice(stop)

class slice(start, stop, step=None)

range(start, stop, step) で指定されたインデックスのセットを表す slice オブジェクトを返します。 引数 start と step のデフォルトは None です。

start

stop

step

スライスオブジェクトには読み出し専用のデータ属性 start stop step があり、これらは単に引数の値（またはそのデフォルト値）を返します。 スライスオブジェクトは特に他の機能を持ちませんが、 NumPy や他のサードパーティパッケージで使われています。

スライスオブジェクトは、拡張インデックス構文が使われた場合にも作られます。 例： a[start:stop:step] や a[start:stop, i] 。 iterator を返す代替バージョンについては itertools.islice() を参照して下さい。

バージョン 3.12 で変更: スライスオブジェクトが hashable (ハッシュ可能) となりました (ただし、属性 start 、 stop 、 step がすべてハッシュ可能である場合に限ります)。

sorted(iterable, /, *, key=None, reverse=False)

iterable の要素を並べ替えた新たなリストを返します。

2 つのオプション引数があり、これらはキーワード引数として指定されなければなりません。

key には 1 引数関数を指定します。これは iterable の各要素から比較キーを展開するのに使われます (例えば、 key=str.lower のように指定します)。デフォルト値は None です (要素を直接比較します)。

reverse は真偽値です。 True がセットされた場合、リストの要素は個々の比較が反転したものとして並び替えられます。

旧式の cmp 関数を key 関数に変換するには functools.cmp_to_key() を使用してください。

組み込みの sorted() 関数は安定なことが保証されています。同等な要素の相対順序を変更しないことが保証されていれば、ソートは安定です。これは複数のパスでソートを行なうのに役立ちます（例えば部署でソートしてから給与の等級でソートする場合）。

ソートアルゴリズムは、要素間の比較に < 演算子だけを使います。したがってソートのためには __lt__() メソッドを定義すれば十分なはずですが、 PEP 8 [https://peps.python.org/pep-0008/] は6つの 比較演算子 を全て実装することを推奨しています。これにより、異なるメソッドを必要とする max() のような他のソートツールを、同じデータに対して適用することによって起こりうるバグを避ける助けになります。6つの比較演算子を全て実装することは、リフレクションによって __gt__() メソッドを呼び出す可能性のある型混合の比較での混乱を避けることにも役立ちます。

ソートの例と簡単なチュートリアルは Sorting Techniques を参照して下さい。

@staticmethod

メソッドを静的メソッドへ変換します。

静的メソッドは暗黙の第一引数を受け取りません。静的メソッドを宣言するには、このイディオムを使ってください:

class C:
    @staticmethod
    def f(arg1, arg2, argN): ...

@staticmethod 形式は関数 デコレータ です。詳しくは 関数定義 を参照してください。

A static method can be called either on the class (such as C.f()) or on an instance (such as C().f()). Moreover, the static method descriptor is also callable, so it can be used in the class definition (such as f()).

Python における静的メソッドは Java や C++ における静的メソッドと類似しています。クラスコンストラクタの代替を生成するのに役立つ変種、 classmethod() も参照してください。

あらゆるデコレータと同じく、 staticmethod は普通の関数のように呼べ、その返り値で処理が行えます。この機能は、クラス本体から関数を参照する必要があり、かつ、インスタンスメソッドに自動変換されるのを避けたいケースで必要になります。そのようなケースでは、このイディオムが使えます:

def regular_function():
    ...

class C:
    method = staticmethod(regular_function)

静的メソッドについて詳しい情報は 標準型の階層 を参照してください。

バージョン 3.10 で変更: 静的メソッドはメソッド属性 (__module__, __name__, __qualname__, __doc__ そして __annotations__) を継承するようになり、また新たに __wrapped__ 属性を持つようになりました。さらに、静的メソッドを通常の関数として呼び出すことができるようになりました。

class str(object='')

class str(object=b'', encoding='utf-8', errors='strict')

object の str 版を返します。詳細は str() を参照してください。

str は組み込みの文字列 クラス です。文字列に関する一般的な情報は、テキストシーケンス型 --- str を参照してください。

sum(iterable, /, start=0)

start と iterable の要素を左から右へ合計し、総和を返します。 iterable の要素は通常は数値で、start の値は文字列であってはなりません。

使う場面によっては、 sum() よりもいい選択肢があります。文字列からなるシーケンスを結合する高速かつ望ましい方法は ''.join(sequence) を呼ぶことです。浮動小数点数値を拡張された精度で加算するには、 math.fsum() を参照してください。一連のイテラブルを連結するには、 itertools.chain() の使用を考えてください。

バージョン 3.8 で変更: start パラメータをキーワード引数として指定することができるようになりました。

バージョン 3.12 で変更: Summation of floats switched to an algorithm that gives higher accuracy on most builds.

class super

class super(type, object_or_type=None)

メソッドの呼び出しを type の親または兄弟クラスに委譲するプロキシオブジェクトを返します。これはクラスの中でオーバーライドされた継承メソッドにアクセスするのに便利です。

object_or_type はメソッドの検索のための method resolution order (メソッド解決順序) を決定します。検索は type 直後のクラスから開始します。

例えば object_or_type の __mro__ 属性が D -> B -> C -> A -> object であり、 type の値が B だとすると、 super() は C -> A -> object の順番でメソッドを検索します。

object_or_type の __mro__ 属性は、 getattr() と super() の 両方で使われる、メソッド解決の探索順序を列記します。 この属性は動的で、継承の階層構造が更新されれば、随時変化します。

第 2 引数が省かれたなら、返されるスーパーオブジェクトは束縛されません。第 2 引数がオブジェクトであれば、 isinstance(obj, type) は真でなければなりません。第 2 引数が型であれば、 issubclass(type2, type) は真でなければなりません (これはクラスメソッドに役に立つでしょう)。

super の典型的な用途は 2 つあります。第一に、単継承のクラス階層構造で super は名前を明示することなく親クラスを参照するのに使え、それゆえコードをメンテナンスしやすくなります。この用途は他のプログラミング言語で見られる super の用途によく似ています。

2つ目の用途は動的な実行環境において協調的 (cooperative) な多重継承をサポートすることです。これは Python に特有の用途で、静的にコンパイルされる言語や、単継承のみをサポートする言語には見られないものです。この機能により、同じ名前のメソッドを実装する複数の基底クラスを使った "ダイヤモンド型* の継承構造を実装することができます。良い設計は、そのような実装において、どのような場合でも同じ呼び出しシグネチャを持つように強制します。 (理由は呼び出しの順序が実行時に決定されること、呼び出し順序はクラス階層構造の変化に順応すること、そして呼び出し順序が実行時まで未知の兄弟クラスが含まれる場合があることです)。

両方の用途において、典型的なスーパークラスの呼び出しは次のようになります:

class C(B):
    def method(self, arg):
        super().method(arg)    # This does the same thing as:
                               # super(C, self).method(arg)

メソッドのルックアップに加えて、 super() は属性のルックアップに対しても同様に動作します。考えうる用途のひとつは親クラスや兄弟クラスの descriptors (デスクリプタ) を呼び出すことです。

なお、super() は super().__getitem__(name) のような明示的なドット表記属性探索の束縛処理の一部として実装されています。これは、 __getattribute__() メソッドを予測可能な順序でクラスを検索するように実装し、協調的な多重継承をサポートすることで実現されています。従って、 super() は文や super()[name] のような演算子を使った暗黙の探索向けには定義されていません。

また、 super() の使用は引数無しの形式を除きメソッド内部に限定されないことにも注目して下さい。2引数の形式は、必要な要素を正確に指定するので、適当な参照を作ることができます。クラス定義中における引数無しの形式は、定義されているクラスを取り出すのに必要な詳細を、通常の方法で現在のインスタンスにアクセスするようにコンパイラが埋めるのではたらきます。

super() を用いて協調的なクラスを設計する方法の実践的な提案は、 guide to using super() [https://rhettinger.wordpress.com/2011/05/26/super-considered-super/] を参照してください。

class tuple

class tuple(iterable)

tuple は、実際は関数ではなくイミュータブルなシーケンス型で、タプル型 (tuple) と シーケンス型 --- list, tuple, range にドキュメント化されています。

class type(object)

class type(name, bases, dict, **kwds)

引数が1つだけの場合、object の型を返します。返り値は型オブジェクトで、一般に object.__class__ によって返されるのと同じオブジェクトです。

オブジェクトの型の判定には、 isinstance() 組み込み関数を使うことが推奨されます。これはサブクラスを考慮するからです。

引数が3つの場合、新しい型オブジェクトを返します。これは本質的には class 文の動的な書式です。 name 文字列はクラス名で、 __name__ 属性になります。 bases 基底クラスのタプルで、 __bases__ 属性になります; 空の場合は全てのクラスの基底クラスである object が追加されます。 dict は、クラス本体の属性とメソッドの定義を含む辞書です; 辞書は __dict__ 属性になる前にコピーされたり、ラップされることがあります。以下の2つの文は同じ type オブジェクトを生成します:

>>> class X:
...     a = 1
...
>>> X = type('X', (), dict(a=1))

型オブジェクト も参照してください。

三引数形式の呼び出しに与えられたキーワード引数は、(metaclass を除く) クラス定義におけるキーワード引数と同様に、適切なメタクラスの機構 (通常は __init_subclass__()) に渡されます。

クラス生成をカスタマイズする も参照してください。

バージョン 3.6 で変更: type.__new__ をオーバーライドしていない type のサブクラスは、オブジェクトの型を得るのに１引数形式を利用することができません。

vars()

vars(object)

モジュール、クラス、インスタンス、あるいはそれ以外の __dict__ 属性を持つオブジェクトの、 __dict__ 属性を返します。

モジュールやインスタンスのようなオブジェクトは、更新可能な __dict__ 属性を持っています。ただし、それ以外のオブジェクトでは __dict__ 属性への書き込みが制限されている場合があります。書き込みに制限がある例としては、辞書を直接更新されることを防ぐために types.MappingProxyType を使っているクラスがあります。

引数がなければ、vars() は locals() のように振る舞います。ただし、辞書 locals への更新は無視されるため、辞書 locals は読み出し時のみ有用であることに注意してください。

指定されたオブジェクトに __dict__ 属性がない場合 (たとえばそのクラスが __slots__ 属性を定義している場合)、 TypeError 例外が送出されます。

zip(*iterables, strict=False)

複数のイテラブルを並行に反復処理し、各イテラブルの要素からなるタプルを生成します。

以下はプログラム例です:

>>> for item in zip([1, 2, 3], ['sugar', 'spice', 'everything nice']):
...     print(item)
...
(1, 'sugar')
(2, 'spice')
(3, 'everything nice')

より正式な定義: zip() は、 i 番目のタプルが 引数に与えた各イテラブルの i 番目の要素を含むような、タプルのイテレータを返します。

zip() に対する別の考え方は、この関数は行を列に、また列を行に変換するということです。これは 行列の転置 [https://en.wikipedia.org/wiki/Transpose] とよく似ています。

zip() は遅延評価です: イテラブルが for ループに渡されたり、 list でラップされたりするなどして反復処理されるまで、要素が実際に処理されることはありません。

ここで考慮すべきことは、 zip() に渡されるイテラブルが異なる長さを持つことがあるという点です; ときには意図的な場合もあり、またときにはイテラブルを準備するコードにおけるバグのこともあるでしょう。 Python はこの問題に対して3つの異なるアプローチを提供します:

デフォルトでは、 zip() は最も短いイテラブルが消費しきった時点で停止します。より繰り返し数の長いイテラブルの残りの要素は無視して、結果を最も短いイテラブルの長さに切り詰めます:

>>> list(zip(range(3), ['fee', 'fi', 'fo', 'fum']))
[(0, 'fee'), (1, 'fi'), (2, 'fo')]

zip() は、しばしば受け取ったイテラブルが全て同じ長さであるという想定の下で使われます。そのような場合、 strict=True オプションの利用が推奨されます。その出力は通常の zip() と同じです:

>>> list(zip(('a', 'b', 'c'), (1, 2, 3), strict=True))
[('a', 1), ('b', 2), ('c', 3)]

しかし、デフォルトの動作と異なり、あるイテラブルが他のイテラブルよりも先に消費しきった場合に ValueError 例外を送出します:

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

strict=True 引数なしの場合、長さの異なるイテラブルを生じる原因となるいかなるバグも、この時点では問題なく処理されます。そして代わりにプログラムの別の場所で、原因を特定しにくいバグとして検出されることになるでしょう。

短いイテラブルを一定の値でパディングして全てのイテラブルが同じ長さになるようにすることもできます。この機能は itertools.zip_longest() で提供されます。

エッジケース: 引数としてイテラブルをひとつだけ渡した場合、 zip() は 1 タプルのイテレータを返します。引数なしの場合は空のイテレータを返します。

ヒントとコツ:

イテラブルの左から右への評価順序は保証されています。そのため zip(*[iter(s)]*n, strict=True) を使ってデータ系列を長さ n のグループにクラスタリングするイディオムが使えます。これは、各出力タプルがイテレータを n 回呼び出した結果となるよう、 同じ イテレータを n 回繰り返します。これは入力を長さ n のチャンクに分割する効果があります。

zip() に続けて * 演算子を使うと、zip したリストを元に戻せます:

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

バージョン 3.10 で変更: strict 引数が追加されました。

__import__(name, globals=None, locals=None, fromlist=(), level=0)

注釈

これは importlib.import_module() とは違い、日常の Python プログラミングでは必要ない高等な関数です。

この関数は import 文により呼び出されます。 (builtins モジュールをインポートして builtins.__import__ に代入することで) この関数を置き換えて import 文のセマンティクスを変更することができますが、同様のことをするのに通常はインポートフック (PEP 302 [https://peps.python.org/pep-0302/] 参照) を利用する方が簡単で、かつデフォルトのインポート実装が使用されていることを仮定するコードとの間で問題が起きないので、このやり方は 強く 推奨されません。 __import__() を直接使用することも推奨されず、 importlib.import_module() の方が好まれます。

この関数は、モジュール name をインポートし、 globals と locals が与えられれば、パッケージのコンテキストで名前をどう解釈するか決定するのに使います。 fromlist は name で与えられるモジュールからインポートされるべきオブジェクトまたはサブモジュールの名前を与ます。標準の実装では locals 引数はまったく使われず、 globals は import 文のパッケージコンテキストを決定するためにのみ使われます。

level は絶対と相対どちらのインポートを使うかを指定します。 0 (デフォルト) は絶対インポートのみ実行します。正の level の値は、 __import__() を呼び出したディレクトリから検索対象となる親ディレクトリの数を示します (詳細は PEP 328 [https://peps.python.org/pep-0328/] を参照してください)。

name 変数が package.module 形式であるとき、通常は、name で指名されたモジュール ではなく、最上位のパッケージ (最初のドットまでの名前) が返されます。しかしながら、空でない fromlist 引数が与えられると、 name で指名されたモジュールが返されます。

例えば、文 import spam は、以下のコードのようなバイトコードに帰結します:

spam = __import__('spam', globals(), locals(), [], 0)

文 import spam.ham は、この呼び出しになります:

spam = __import__('spam.ham', globals(), locals(), [], 0)

ここで __import__() がどのように最上位モジュールを返しているかに注意して下さい。 import 文により名前が束縛されたオブジェクトになっています。

一方で、文 from spam.ham import eggs, sausage as saus は、以下となります

_temp = __import__('spam.ham', globals(), locals(), ['eggs', 'sausage'], 0)
eggs = _temp.eggs
saus = _temp.sausage

ここで、__import__() から spam.ham モジュールが返されます。このオブジェクトから、インポートされる名前が取り出され、それぞれの名前として代入されます。

単純に名前からモジュール (パッケージの範囲内であるかも知れません) をインポートしたいなら、 importlib.import_module() を使ってください。

バージョン 3.3 で変更: 負の level の値はサポートされなくなりました (デフォルト値の 0 に変更されます)。

バージョン 3.9 で変更: コマンドラインオプション -E or -I が指定された場合、環境変数 PYTHONCASEOK は無視されるようになりました。

脚注

[1]

なお、パーサは Unix スタイルの行末の記法しか受け付けません。コードをファイルから読んでいるなら、必ず、改行変換モードで Windows や Mac スタイルの改行を変換してください。

組み込み定数

組み込み名前空間にはいくつかの定数があります。定数の一覧:

False

bool 型の偽値です。False への代入は不正で、SyntaxError を送出します。

True

bool 型の真値です。True への代入は不正で、SyntaxError を送出します。

None

関数にデフォルト引数が渡されなかったときなどに、値の非存在を表すのに頻繁に用いられるオブジェクトです。None への代入は不正で、SyntaxError を送出します。None が NoneType 型の唯一のインスタンスです。

NotImplemented

特殊な二項演算のメソッド (e.g. __eq__(), __lt__(), __add__(), __rsub__(), etc.) が、他の型に対して演算が実装されていないことを示すために返す特殊値です。インプレースの特殊な二項演算のメソッド (e.g. __imul__(), __iand__(), etc.) も同じ理由でこの値を返すことがあります。この処理では真偽値コンテキストでの評価はしてはいけません。NotImplemented が types.NotImplementedType 型の唯一のインスタンスです。

注釈

二項演算の (あるいはインプレースの) メソッドが NotImplemented を返した場合、インタープリタはもう一方の型で定義された対の演算で代用を試みます (あるいは演算によっては他の代替手段も試みます)。試行された演算全てが NotImplemented を返した場合、インタープリタは適切な例外を送出します。 NotImplemented を正しく返さないと、誤解を招きかねないエラーメッセージになったり、 NotImplemented が Python コードに返されるようなことになります。

例として 算術演算の実装 を参照してください。

注釈

NotImplementedError と NotImplemented は、似たような名前と目的を持っていますが、相互に変換できません。 利用する際には、 NotImplementedError を参照してください。

バージョン 3.9 で変更: NotImplemented の評価は非推奨です。現時点で真と評価されていても DeprecationWarning が出ます。この警告は将来のバージョンの Python で TypeError を送出します。

Ellipsis

Ellipsis リテラル "..." と同じです。主に拡張スライス構文やユーザ定義のコンテナデータ型において使われる特殊な値です。Ellipsis が types.EllipsisType 型の唯一のインスタンスです。

__debug__

この定数は、Python が -O オプションを有効にして開始されたのでなければ真です。 assert 文も参照して下さい。

注釈

名前 None 、 False 、 True 、 __debug__ は再代入できない (これらに対する代入は、たとえ属性名としてであっても SyntaxError が送出されます) ので、これらは「真の」定数であると考えられます。

site モジュールで追加される定数

site モジュール (-S コマンドラインオプションが指定されない限り、スタートアップ時に自動的にインポートされます) は組み込み名前空間にいくつかの定数を追加します。それらは対話的インタープリタシェルで有用ですが、プログラム中では使うべきではありません。

quit(code=None)

exit(code=None)

表示されたときに "Use quit() or Ctrl-D (i.e. EOF) to exit" のようなメッセージを表示し、呼び出されたときには指定された終了コードを伴って SystemExit を送出するオブジェクトです。

copyright

credits

表示あるいは呼び出されたときに、それぞれ著作権あるいはクレジットのテキストが表示されるオブジェクトです。

license

表示されたときに "Type license() to see the full license text" というメッセージを表示し、呼び出されたときには完全なライセンスのテキストをページャのような形式で (1画面分づつ) 表示するオブジェクトです。

組み込み型

以下のセクションでは、インタプリタに組み込まれている標準型について記述します。

主要な組み込み型は、数値、シーケンス、マッピング、クラス、インスタンス、および例外です。

コレクションクラスには、ミュータブルなものがあります。コレクションのメンバをインプレースに足し、引き、または並べ替えて、特定の要素を返さないメソッドは、コレクション自身ではなく None を返します。

演算には、複数の型でサポートされているものがあります; 特に、ほぼ全てのオブジェクトは、等価比較でき、真理値を判定でき、 (repr() 関数や、わずかに異なる str() 関数によって) 文字列に変換できます。オブジェクトが print() 関数で印字されるとき、文字列に変換する関数が暗黙に使われます。

真理値判定

どのようなオブジェクトでも真理値として判定でき、 if や while の条件あるいは以下のブール演算の被演算子として使えます。

オブジェクトは、デフォルトでは真と判定されます。ただし、そのクラスが __bool__() メソッドを定義していて False を返す場合、または __len__() メソッドを定義していてゼロを返す場合は偽と判定されます。 [1] 以下は偽と判定される主な組み込みオブジェクトです:

偽であると定義されている定数: None と False

数値型におけるゼロ: 0, 0.0, 0j, Decimal(0), Fraction(0, 1)

空のシーケンスまたはコレクション: '', (), [], {}, set(), range(0)

ブール値の結果を返す演算および組み込み関数は、特に注釈のない限り常に偽値として 0 または False を返し、真値として 1 または True を返します。 (重要な例外: ブール演算 or および and は常に被演算子のうちの一つを返します。)

ブール演算 --- and, or, not

以下にブール演算を、優先順位が低い順に示します:

演算

結果

注釈

x or y

x が真なら x, そうでなければ y

(1)

x and y

x が偽なら x, そうでなければ y

(2)

not x

x が偽なら True, そうでなければ False

(3)

注釈:

この演算子は短絡評価されます。つまり第一引数が偽のときにのみ、第二引数が評価されます。

この演算子は短絡評価されます。つまり第一引数が真のときにのみ、第二引数が評価されます。

not は非ブール演算子よりも優先度が低いので、 not a == b は not (a == b) と解釈され、 a == not b は構文エラーです。

比較

Python には 8 種の比較演算があります。比較演算の優先順位は全て同じです (ブール演算より高い優先順位です)。比較は任意に連鎖できます; 例えば、 x < y <= z は x < y and y <= z とほぼ等価ですが、この y は一度だけしか評価されません (どちらにしても、 x < y が偽となれば z は評価されません)。

以下の表に比較演算をまとめます:

演算

意味

<

より小さい

<=

以下

>

より大きい

>=

以上

==

等しい

!=

等しくない

is

同一のオブジェクトである

is not

同一のオブジェクトでない

異なる数値型の場合を除き、異なる型のオブジェクト同士は等価になることはありません。 == 演算子は常に定義されていますが、いくつかのオブジェクト型 (たとえばクラスオブジェクト) では is と同等になります。 <, <=, > および >= 演算子は、それらの意味が明快である場合に限って定義されます; たとえば、オペランドのいずれかが複素数である場合、これらの演算子は TypeError 例外を送出します。

あるクラスの同一でないインスタンスは、通常等価でないとされますが、そのクラスが __eq__() メソッドを定義している場合は除きます。

クラスのインスタンスは、そのクラスがメソッド __lt__() 、 __le__() 、 __gt__() 、 __ge__() のうち十分なものを定義していない限り、同じクラスの別のインスタンスや他の型のオブジェクトとは順序付けできません (一般に、比較演算子の通常の意味を求めるなら、 __lt__() と __eq__() だけで十分です)。

is および is not 演算子の振る舞いはカスタマイズできません。また、これらはいかなる 2 つのオブジェクトにも適用でき、決して例外を送出しません。

in と not in という構文上で同じ優先度を持つ演算子がさらに 2 つあり、 iterable または __contains__() を実装した型でサポートされています。

数値型 int, float, complex

数値型には 3 種類あります: 整数 、 浮動小数点数 、 複素数 です。さらに、ブール型は整数のサブタイプです。整数には精度の制限がありません。浮動小数点型はたいていは C の double を使って実装されています; あなたのプログラムが動作するマシンでの浮動小数点型の精度と内部表現は、 sys.float_info から利用できます。複素数は実部と虚部を持ち、それぞれ浮動小数点数です。複素数 z から実部および虚部を取り出すには、 z.real および z.imag を使ってください。 (標準ライブラリには、さらに分数のための数値型 fractions.Fraction や、ユーザによる精度の定義が可能な浮動小数点数のための decimal.Decimal があります。)

数値は、数値リテラルによって、あるいは組み込み関数や演算子の戻り値として生成されます。 (十六進、八進、二進数を含む) 修飾のない整数リテラルは、整数を与えます。小数点または指数表記を含む数値リテラルは浮動小数点数を与えます。数値リテラルに 'j' または 'J' をつけると虚数 (実部がゼロの複素数) を与え、それに整数や浮動小数点数を加えて実部と虚部を持つ複素数を得られます。

Python は型混合の算術演算に完全に対応しています: ある二項算術演算子の被演算子の数値型が互いに異なるとき、"より狭い方" の型の被演算子はもう片方の型に合わせて広げられます。ここで整数は浮動小数点数より狭く、浮動小数点数は複素数より狭いです。たくさんの異なる型の数値間での比較は、それらの厳密な数で比較したかのように振る舞います。 [2]

コンストラクタ int() 、 float() 、 complex() で、特定の型の数を生成できます。

全ての (複素数を除く) 組み込み数値型は以下の演算に対応しています (演算の優先順位については、 演算子の優先順位 を参照してください):

演算

結果

注釈

完全なドキュメント

x + y

x と y の和

x - y

x と y の差

x * y

x と y の積

x / y

x と y の商

x // y

x と y の商を切り下げたもの

(1)(2)

x % y

x / y の剰余

(2)

-x

x の符号反転

+x

x そのまま

abs(x)

x の絶対値または大きさ

abs()

int(x)

x の整数への変換

(3)(6)

int()

float(x)

x の浮動小数点数への変換

(4)(6)

float()

complex(re, im)

実部 re, 虚部 im の複素数。 im の既定値はゼロ。

(6)

complex()

c.conjugate()

複素数 c の共役複素数

divmod(x, y)

(x // y, x % y) からなるペア

(2)

divmod()

pow(x, y)

x の y 乗

(5)

pow()

x ** y

x の y 乗

(5)

注釈:

整数の除算とも呼ばれます。 int 型のオペランドに対しては、結果は int 型になります。 float 型のオペランドに対しては、結果は float 型になります。一般に結果の型は必ずしも int 型ではありませんが、結果は常に整数です。結果は常に負の無限大の方向に丸められます: 1//2 は 0 、 (-1)//2 は -1 、 1//(-2) は -1 、そして (-1)//(-2) は 0 です。

複素数型には使えません。適用可能な場合には代わりに abs() で浮動小数点型に変換してください。

float から int への変換は小数点以下を切り捨てます。別の変換方法については関数 math.floor() や math.ceil() を参照してください。

浮動小数点数は、文字列 "nan" と "inf" を、オプションの接頭辞 "+" または "-" と共に、非数 (Not a Number (NaN)) や正、負の無限大として受け付けます。

Python は、プログラム言語一般でそうであるように、 pow(0, 0) および 0 ** 0 を 1 と定義します。

受け付けられる数値リテラルは数字 0 から 9 または等価な Unicode (Nd プロパティを持つコードポイント) を含みます。

Nd プロパティを持つコードポイントの完全なリストは Unicode 標準 [https://unicode.org/Public/UNIDATA/extracted/DerivedNumericType.txt] をご覧ください。

全ての numbers.Real 型 (int 、 float) は以下の演算も含みます:

演算

結果

math.trunc(x)

x を Integral (整数) に切り捨てます

round(x[, n])

x を n 桁に丸めます。丸め方は偶数丸めです。 n が省略されれば 0 がデフォルトとなります。

math.floor(x)

x 以下の最大の Integral (整数) を返します

math.ceil(x)

x 以上の最小の Integral (整数) を返します

その他の数値演算は、 math や cmath モジュールをご覧ください。

整数型におけるビット単位演算

ビット単位演算は整数についてのみ意味を持ちます。ビット単位演算の結果は、あたかも両方の値の先頭を無限個の符号ビットで埋めたものに対して計算したかのような値になります。

二項ビット単位演算の優先順位は全て、数値演算よりも低く、比較よりも高くなっています; 単項演算 ~ の優先順位は他の単項数値演算 (+ および -) と同じです。

以下の表では、ビット単位演算を優先順位が低い順に並べています:

演算

結果

注釈

x | y

x と y のビット単位 論理和

(4)

x ^ y

x と y のビット単位 排他的論理和

(4)

x & y

x と y のビット単位 論理積

(4)

x << n

x の n ビット左シフト

(1)(2)

x >> n

x の n ビット右シフト

(1)(3)

~x

x のビット反転

注釈:

負値のシフト数は不正であり、 ValueError が送出されます。

n ビットの左シフトは、 pow(2, n) による乗算と等価です。

n ビットの右シフトは、 pow(2, n) による切り捨て除算と等価です。

桁の長い方の値に少なくとも 1 つ余計に符号ビットを付け加えた幅 (計算するビット幅は 1 + max(x.bit_length(), y.bit_length()) かそれ以上) でこれらの計算を行えば、無限個の符号ビットがあるかのように計算したのと同じ結果を得るのに十分です。

整数型における追加のメソッド

整数型は numbers.Integral 抽象基底クラス を実装します。さらに、追加のメソッドをいくつか提供します:

int.bit_length()

整数を、符号と先頭の 0 は除いて二進法で表すために必要なビットの数を返します:

>>> n = -37
>>> bin(n)
'-0b100101'
>>> n.bit_length()
6

正確には、 x が非 0 なら、 x.bit_length() は 2**(k-1) <= abs(x) < 2**k を満たす唯一の正の整数 k です。同様に、 abs(x) が十分小さくて対数を適切に丸められるとき、 k = 1 + int(log(abs(x), 2)) です。 x が 0 なら、 x.bit_length() は 0 を返します。

次と等価です:

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

Added in version 3.1.

int.bit_count()

整数の絶対値の二進数表現における 1 の数を返します。これは population count としても知られています。 例:

>>> n = 19
>>> bin(n)
'0b10011'
>>> n.bit_count()
3
>>> (-n).bit_count()
3

次と等価です:

def bit_count(self):
    return bin(self).count("1")

Added in version 3.10.

int.to_bytes(length=1, byteorder='big', *, signed=False)

整数を表すバイト列を返します。

>>> (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'

整数は length バイトで表されます、デフォルト値は 1 です。整数が与えられた数のバイトで表せなければ、 OverflowError が送出されます。

byteorder 引数は、整数を表すのに使われるバイトオーダーを決定します。デフォルト値は "big" です。 byteorder が "big" なら、最上位のバイトがバイト配列の最初に来ます。 byteorder が "little" なら、最上位のバイトがバイト配列の最後に来ます。

signed 引数は、整数を表すのに 2 の補数を使うかどうかを決定します。 signed が False で、負の整数が与えられたなら、 OverflowError が送出されます。 signed のデフォルト値は False です。

上記のデフォルト値は整数を 1 バイトのオブジェクトに適切に変換するのに使うことができます:

>>> (65).to_bytes()
b'A'

ただし、デフォルト引数で 255 より大きな整数を変換しないでください。 そうでなければ:exc:OverflowError 例外を引き起こします。

次と等価です:

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)

Added in version 3.2.

バージョン 3.11 で変更: length と byteorder 引数にデフォルト値を追加しました。

classmethod int.from_bytes(bytes, byteorder='big', *, signed=False)

与えられたバイト列の整数表現を返します。

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

引数 bytes は bytes-like object か、または bytes を生成する iterable でなければなりません。

byteorder 引数は、整数を表すのに使われるバイトオーダーを決定します。デフォルト値は "big" です。 byteorder が "big" なら、最上位のバイトがバイト配列の最初に来ます。 byteorder が "little" なら、最上位のバイトがバイト配列の最後に来ます。ホストシステムにネイティブのバイトオーダーを要求するには、 sys.byteorder をバイトオーダーの値として使ってください。

signed 引数は、整数を表すのに 2 の補数を使うかどうかを決定します。

次と等価です:

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

Added in version 3.2.

バージョン 3.11 で変更: byteorder 引数にデフォルト値を追加しました。

int.as_integer_ratio()

比が元の数と等しくなるような整数のペアを返します。戻り値の分母に相当する数は正の整数です。元の数が整数の場合の比は、常にその整数が分子であり、分母は 1 です。

Added in version 3.8.

int.is_integer()

常に True を返します。 float.is_integer() に対するダックタイピングの互換性のために存在しています。

Added in version 3.12.

浮動小数点数に対する追加のメソッド

浮動小数点数型は、 numbers.Real 抽象基底クラス を実装しています。浮動小数点型はまた、以下の追加のメソッドを持ちます。

float.as_integer_ratio()

比が厳密に元の浮動小数点数であるような一対の整数を返します。比は既約分数として与えられ、分母は正の値です。無限大に対しては OverflowError を、非数 (NaN) に対しては ValueError を送出します。

float.is_integer()

浮動小数点数インスタンスが有限の整数値なら True を、そうでなければ False を返します:

>>> (-2.0).is_integer()
True
>>> (3.2).is_integer()
False

16 進表記の文字列へ、または、 16 進表記からの変換をサポートする二つのメソッドがあります。 Python の浮動小数点数は内部的には2進数で保持されるので、浮動小数点数の 10進数 へまたは 10進数 からの変換には若干の丸め誤差があります。それに対し、16 進表記では、浮動小数点数を正確に表現できます。これはデバッグのときや、数学的な用途 (numerical work) に便利でしょう。

float.hex()

浮動小数点数の 16 進文字列表現を返します。有限の浮動小数点数に対し、この表現は常に 0x で始まり p と指数が続きます。

classmethod float.fromhex(s)

16 進文字列表現 s で表される、浮動小数点数を返すクラスメソッドです。文字列 s は、前や後にホワイトスペースを含んでいても構いません。

float.fromhex() はクラスメソッドですが、 float.hex() はインスタンスメソッドであることに注意して下さい。

16 進文字列表現は以下の書式となります:

[sign] ['0x'] integer ['.' fraction] ['p' exponent]

sign は必須ではなく、 + と - のどちらかです。 integer と fraction は 16 進数の文字列で、 exponent は 10 進数で符号もつけられます。大文字・小文字は区別されず、最低でも 1 つの 16 進数文字を整数部もしくは小数部に含む必要があります。この制限は C99 規格のセクション 6.4.4.2 で規定されていて、 Java 1.5 以降でも使われています。特に、 float.hex() の出力は C や Java コード中で、浮動小数点数の 16 進表記として役に立つでしょう。また、 C の %a 書式や、 Java の Double.toHexString で書きだされた文字列は float.fromhex() で受け付けられます。

なお、指数部は 16 進数ではなく 10 進数で書かれ、係数に掛けられる 2 の累乗を与えます。例えば、16 進文字列 0x3.a7p10 は浮動小数点数 (3 + 10./16 + 7./16**2) * 2.0**10 すなわち 3740.0 を表します:

>>> float.fromhex('0x3.a7p10')
3740.0

逆変換を 3740.0 に適用すると、同じ数を表す異なる 16 進文字列表現を返します:

>>> float.hex(3740.0)
'0x1.d380000000000p+11'

数値型のハッシュ化

数 x と y に対して、型が異なっていたとしても、 x == y であれば必ず hash(x) == hash(y) であることが要請されます (詳細は __hash__() メソッドドキュメントを参照してください)。実装の簡単さと 複数の数値型 (int 、 float 、 decimal.Decimal 、 fractions.Fraction を含みます) 間の効率のため、Python の 数値型に対するハッシュ値はある単一の数学的関数に基づいていて、 その関数はすべての有理数に対し定義されているため、 int と fractions.Fraction のすべてのインスタンスと、 float と decimal.Decimal のすべての有限なインスタンスに 対して適用されます。本質的には、この関数は定数の素数 P に対して P を法とする還元で与えられます。 値 P は、 sys.hash_info の modulus 属性として Python で利用できます。

CPython 実装の詳細: 現在使われている素数は、32 bit C long のマシンでは P = 2**31 - 1 、 64-bit C long のマシンでは P = 2**61 - 1 です。

詳細な規則はこうです:

x = m / n が非負の有理数で、 n が P で割り切れないなら、 invmod(n, P) を n を P で割った剰余の (剰余演算の意味での) 逆数を与えるものとして、 hash(x) を m * invmod(n, P) % P と定義します。

x = m / n が非負の有理数で、 n が P で割り切れる (が m は割り切れない) なら、 n は P で割った余りの逆数を持たず、上の規則は適用できません。この場合、 hash(x) を定数 sys.hash_info.inf と定義します。

x = m / n が負の有理数なら、 hash(x) を -hash(-x) と定義します。その結果のハッシュが -1 なら、 -2 に置き換えます。

特定の値 sys.hash_info.inf 、 -sys.hash_info.inf は、正の無限大、負の無限大のハッシュ値を (それぞれ) 表すのに使われます。

複素 (complex) 数 z に対して、実部と虚部のハッシュ値は、 hash(z.real) + sys.hash_info.imag * hash(z.imag) の 2**sys.hash_info.width を法とする還元を計算することにより組み合わせられ、よってこれは range(-2**(sys.hash_info.width - 1), 2**(sys.hash_info.width - 1)) に収まります。再び、結果が -1 なら、 -2 で置き換えられます。

上述の規則をわかりやすくするため、有理数 float や、 complex のハッシュを計算する組み込みのハッシュと等価な Python コードの例を挙げます:

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

ブーリアン型 - bool

ブーリアン型は真理値を表現します。 bool 型はただ2つの定数インスタンス True と False を持ちます。

組み込み関数 bool() は、もしその値が真理値として解釈可能ならば、任意の値を真偽値に変換します (上記 真理値判定 節を参照してください)。

論理演算には ブーリアン演算子 and, or および not を使ってください。2つの真偽値に対してビット演算子 &, |, ^ を適用した場合は、それぞれ論理演算 "and", "or", "xor" に相当するブール値を返します。しかしながら、論理演算子 and, or および != を使うほうが &, | や ^ を使うよりも好ましいです。

バージョン 3.12 で非推奨: ビット反転演算子 ~ は非推奨であり、 Python 3.14 ではエラーを送出するようになります。

bool は int のサブクラスです (数値型 int, float, complex を参照してください)。多くの数値的なコンテキストにおいて、 False と True はそれぞれ整数 0 と 1 であるかのように振る舞います。しかし、そのような振る舞いを信頼することは推奨されません; int() を使って明示的に整数値に変換してください。

イテレータ型

Python はコンテナでの反復処理の概念をサポートしています。この概念は 2 つの別々のメソッドを使って実装されています; これらのメソッドを使ってユーザ定義のクラスで反復を行えるようにできます。後に詳しく述べるシーケンスは、必ず反復処理メソッドをサポートしています。

コンテナオブジェクトが イテラブル のサポートを提供するためには、一つのメソッドが定義されていなければなりません:

container.__iter__()

iterator オブジェクトを返します。オブジェクトは後述するイテレータプロトコルをサポートする必要があります。もしコンテナが異なる種類の反復処理をサポートするなら、それぞれの反復処理のためのイテレータを要求するメソッドをそれぞれ提供しても構いません 。(複数の形式の反復処理を提供するオブジェクトの例として、幅優先探索と深さ優先探索をサポートする木構造が挙げられます。)このメソッドは Python/C API での Python オブジェクトの型構造体の tp_iter スロットに対応します。

イテレータオブジェクト自体は以下の 2 つのメソッドをサポートする必要があります。これらのメソッドは 2 つ合わせて iterator protocol: (イテレータプロトコル) を成します:

iterator.__iter__()

iterator オブジェクト自体を返します。このメソッドはコンテナとイテレータの両方を for および in 文で使えるようにするために必要です。このメソッドは Python/C API において Python オブジェクトを表す型構造体の tp_iter スロットに対応します。

iterator.__next__()

iterator の次のアイテムを返します。もしそれ以上アイテムが無ければ StopIteration 例外を送出します。 このメソッドは Python/C APIでのPythonオブジェクトの型構造体の tp_iternext スロットに対応します。

Python では、いくつかのイテレータオブジェクトを定義して、一般のシーケンス型、特殊なシーケンス型、辞書型、その他の特殊な形式に渡って反復をサポートしています。特殊型は、イテレータプロトコルの実装以外では重要ではありません。

イテレータの __next__() メソッドが一旦 StopIteration を送出したなら、以降の呼び出しでも例外を送出し続けなければなりません。この特性に従わない実装は壊れているとみなされます。

ジェネレータ型

Python における generator (ジェネレータ) は、イテレータプロトコルを実装する便利な方法を提供します。コンテナオブジェクトの __iter__() メソッドがジェネレータとして実装されていれば、そのメソッドは __iter__() および __next__() メソッドを提供するイテレータオブジェクト (厳密にはジェネレータオブジェクト) を自動的に返します。ジェネレータに関する詳細な情報は、 yield 式のドキュメント にあります。

シーケンス型 --- list, tuple, range

基本的なシーケンス型は 3 つあります: リスト、タプル、range オブジェクトです。バイナリデータ や テキスト文字列 を処理するように仕立てられたシーケンス型は、セクションを割いて解説します。

共通のシーケンス演算

以下の表にある演算は、ほとんどのミュータブル、イミュータブル両方のシーケンスでサポートされています。カスタムのシーケンス型にこれらの演算を完全に実装するのが簡単になるように、 collections.abc.Sequence ABC が提供されています。

以下のテーブルで、シーケンス演算を優先順位が低い順に挙げます。表内で、 s と t は同じ型のシーケンス、 n、 i、 j 、 k は整数、x は s に課された型と値の条件を満たす任意のオブジェクトです。

in および not in 演算の優先順位は比較演算と同じです。+ (結合) および * (繰り返し)の優先順位は対応する数値演算と同じです。 [3]

演算

結果

注釈

x in s

s のある要素が x と等しければ True , そうでなければ False

(1)

x not in s

s のある要素が x と等しければ False, そうでなければ True

(1)

s + t

s と t の結合

(6)(7)

s * n または n * s

s 自身を n 回足すのと同じ

(2)(7)

s[i]

s の 0 から数えて i 番目の要素

(3)

s[i:j]

s の i から j までのスライス

(3)(4)

s[i:j:k]

s の i から j まで、 k 毎のスライス

(3)(5)

len(s)

s の長さ

min(s)

s の最小の要素

max(s)

s の最大の要素

s.index(x[, i[, j]])

s 中で x が最初に出現するインデックス (インデックス i 以降からインデックス j までの範囲)

(8)

s.count(x)

s 中に x が出現する回数

同じ型のシーケンスは比較もサポートしています。特に、タプルとリストは対応する要素を比較することで辞書式順序で比較されます。つまり、等しいとされるためには、すべての要素が等しく、両シーケンスの型も長さも等しくなければなりません。(完全な詳細は言語リファレンスの 比較 を参照してください。)

ミュータブルなシーケンスに対する前方および逆方向イテレータはインデックスを使って要素にアクセスします。インデックスは、仮に参照するシーケンスが変化したとしても前方 (または後方) に進み続けます。イテレータは IndexError または StopIteration に出会った場合 (またはインデックスがゼロより小さくなった場合) にのみ終了します。

注釈:

in および not in 演算は、一般に単純な包含判定にのみ使われますが、(str, bytes, bytearray のような) 特殊なシーケンスでは部分シーケンス判定にも使われます:

>>> "gg" in "eggs"
True

0 未満の値 n は 0 として扱われます (これは s と同じ型の空のシーケンスを表します)。シーケンス s の要素はコピーされないので注意してください; コピーではなく要素に対する参照カウントが増えます。これは Python に慣れていないプログラマをよく悩ませます。例えば以下のコードを考えます:

>>> lists = [[]] * 3
>>> lists
[[], [], []]
>>> lists[0].append(3)
>>> lists
[[3], [3], [3]]

ここで、[[]] が空リストを含む 1 要素のリストなので、[[]] * 3 の 3 要素はこの一つの空リスト (への参照) です。lists のいずれかの要素を変更すると、その一つのリストが変更されます。別々のリストのリストを作るにはこうします:

>>> lists = [[] for i in range(3)]
>>> lists[0].append(3)
>>> lists[1].append(5)
>>> lists[2].append(7)
>>> lists
[[3], [5], [7]]

別の説明が FAQ エントリ 多次元のリストを作るにはどうしますか？ にあります。

i または j が負の数の場合、インデックスはシーケンスの末端からの相対インデックスになります: len(s) + i または len(s) + j が代わりに使われます。ただし -0 はやはり 0 であることに注意してください。

s の i から j へのスライスは i <= k < j となるようなインデックス k を持つ要素からなるシーケンスとして定義されます。 i または j が len(s) よりも大きい場合、 len(s) を使います。 i が省略されるか None だった場合、 0 を使います。 j が省略されるか None だった場合、 len(s) を使います。 i が j 以上の場合、スライスは空のシーケンスになります。

s の「 i から j まででステップが k のスライス」は、インデックス x = i + n*k （ただし n は 0 <= n < (j-i)/k を満たす任意の整数）を持つ要素からなるシーケンスとして定義されます。言い換えるとインデックスは i, i+k, i+2*k, i+3*k と続き、 j に達したところでストップします (ただし j は含みません)。 k が正の数である場合、 i または j が len(s) より大きければ len(s) を代わりに使用します。 k が負の数である場合、 i または j が len(s) - 1 より大きければ len(s) - 1 を代わりに使用します。 i または j を省略または None を指定すると、 "端" (どちらの端かは k の符号に依存) の値を代わりに使用します。なお k はゼロにできないので注意してください。また k に None を指定すると、 1 が指定されたものとして扱われます。

イミュータブルなシーケンスの結合は、常に新しいオブジェクトを返します。これは、結合の繰り返しでシーケンスを構築する実行時間コストがシーケンスの長さの合計の二次式になることを意味します。実行時間コストを線形にするには、代わりに以下のいずれかにしてください:

str オブジェクトを結合するには、リストを構築して最後に str.join() を使うか、 io.StringIO インスタンスに書き込んで完成してから値を取得してください

bytes オブジェクトを結合するなら、同様に bytes.join() や io.BytesIO を使うか、 bytearray オブジェクトでインプレースに結合できます。 bytearray オブジェクトはミュータブルで、効率のいい割り当て超過機構を備えています

tuple オブジェクトを結合するなら、代わりに list を拡張してください

その他の型については、関連するクラスのドキュメントを調べてください

シーケンス型には、 (range のように) 特殊なパターンに従う項目のシーケンスのみをサポートするものがあり、それらはシーケンスの結合や繰り返しをサポートしません。

index は x が s 中に見つからないとき ValueError を送出します。追加の引数 i と j は、すべての実装がサポートしているわけではありません。追加の引数を渡すのは、おおよそ s[i:j].index(x) を使うのと等価ですが、データをコピーしなくて済むし、返されるのはスライスの最初ではなくシーケンスの最初からの相対インデクスです。

イミュータブルなシーケンス型

イミュータブルなシーケンス型が一般に実装している演算のうち、ミュータブルなシーケンス型がサポートしていないのは、組み込みの hash() だけです。

このサポートにより、tuple インスタンスのようなイミュータブルなシーケンスは、 dict のキーとして使え、 set や frozenset インスタンスに保存できます。

ハッシュ不可能な値を含むイミュータブルなシーケンスをハッシュ化しようとすると、 TypeError となります。

ミュータブルなシーケンス型

以下のテーブルにある演算は、ほとんどのミュータブルなシーケンスでサポートされています。カスタムのシーケンス型にこれらの演算を完全に実装するのが簡単になるように、 collections.abc.MutableSequence ABC が提供されています。

このテーブルで、 s はミュータブルなシーケンス型のインスタンス、 t は任意のイテラブルオブジェクト、 x は s に課された型と値の条件を満たす任意のオブジェクト (例えば、 bytearray は値の制限 0 <= x <= 255 に合う整数のみを受け付けます) です。

演算

結果

注釈

s[i] = x

s の要素 i を x と入れ替えます

s[i:j] = t

s の i から j 番目までのスライスをイテラブル t の内容に入れ替えます

del s[i:j]

s[i:j] = [] と同じです

s[i:j:k] = t

s[i:j:k] の要素を t の要素と入れ替えます

(1)

del s[i:j:k]

リストから s[i:j:k] の要素を削除します

s.append(x)

x をシーケンスの最後に加えます (s[len(s):len(s)] = [x] と同じ)

s.clear()

s から全ての要素を取り除きます (del s[:] と同じ)

(5)

s.copy()

s の浅いコピーを作成します (s[:] と同じ)

(5)

s.extend(t) または s += t

s を t の内容で拡張します (ほとんど s[len(s):len(s)] = t と同じ)

s *= n

s をその内容を n 回繰り返したもので更新

(6)

s.insert(i, x)

s の i で与えられたインデックスに x を挿入します。 (s[i:i] = [x] と同じ)

s.pop() または s.pop(i)

s から i 番目の要素を取り出し、また取り除きます

(2)

s.remove(x)

s から s[i] が x が等価となる最初の要素を取り除きます

(3)

s.reverse()

s をインプレースに逆転させます

(4)

注釈:

t は置き換えるスライスと同じ長さでなければいけません。

オプションの引数 i は標準で -1 なので、標準では最後の要素をリストから除去して返します。

remove() は s に x が見つからなければ ValueError を送出します。

reverse() メソッドは、大きなシーケンスを反転するときの容量の節約のため、シーケンスをインプレースに変化させます。副作用としてこの演算が行われることをユーザに気づかせるために、これは反転したシーケンスを返しません。

clear() および copy() は、スライシング操作をサポートしないミュータブルなコンテナ (dict や set など) のインターフェースとの一貫性のために含まれています。 copy() は collections.abc.MutableSequence ABC の一部ではありませんが、ほとんどのミュータブルなシーケンスクラスが提供しています。

Added in version 3.3: clear() および copy() メソッド。

値 n は整数であるか、__index__() を実装したオブジェクトです。 n の値がゼロまたは負数の場合、シーケンスをクリアします。共通のシーケンス演算 で s * n について説明したとおり、シーケンスの要素はコピーされないので注意してください; コピーではなく要素に対する参照カウントが増えます。

リスト型 (list)

リストはミュータブルなシーケンスで、一般的に同種の項目の集まりを格納するために使われます (厳密な類似の度合いはアプリケーションによって異なる場合があります)。

class list([iterable])

リストの構成にはいくつかの方法があります:

角括弧の対を使い、空のリストを表す: []

角括弧を使い、項目をカンマで区切る: [a]、[a, b, c]

リスト内包表記を使う: [x for x in iterable]

型コンストラクタを使う: list() または list(iterable)

コンストラクタは、 iterable の項目と同じ項目で同じ順のリストを構築します。 iterable は、シーケンス、イテレートをサポートするコンテナ、またはイテレータオブジェクトです。 iterable が既にリストなら、 iterable[:] と同様にコピーが作られて返されます。例えば、 list('abc') は ['a', 'b', 'c'] を、 list( (1, 2, 3) ) は [1, 2, 3] を返します。引数が与えられなければ、このコンストラクタは新しい空のリスト [] を作成します。

リストを作る方法は、他にも組み込み関数 sorted() などいろいろあります。

リストは 共通の および ミュータブルの シーケンス演算をすべて実装します。リストは、更に以下のメソッドも提供します:

sort(*, key=None, reverse=False)

このメソッドは、項目間の < 比較のみを用いてリストをインプレースにソートします。例外は抑制されません。比較演算がどこかで失敗したら、ソート演算自体が失敗します (そしてリストは部分的に変更された状態で残されるでしょう)。

sort() は、キーワードでしか渡せない 2 つの引数 (キーワード専用引数) を受け付けます:

key は一引数をとる関数を指定し、リストのそれぞれの要素から比較キーを取り出すのに使います (例えば、 key=str.lower)。それぞれの項目に対応するキーは一度計算され、ソート処理全体に使われます。デフォルトの値 None は、別のキー値を計算せず、リストの値が直接ソートされることを意味します。

2.x 形式の cmp 関数を key 関数に変換するために、functools.cmp_to_key() ユーティリティが利用できます。

reverse は真偽値です。 True がセットされた場合、リストの要素は個々の比較が反転したものとして並び替えられます。

このメソッドは、大きなシーケンスをソートするときの容量の節約のため、シーケンスをインプレースに変化させます。副作用としてこの演算が行われることをユーザに気づかせるために、これはソートしたシーケンスを返しません (新しいリストインスタンスを明示的に要求するには sorted() を使ってください)。

sort() メソッドは安定していることが保証されています。ソートは、等しい要素の相対順序が変更されないことが保証されていれば、安定しています。これは複数パスのソートを行なう (例えば部署でソートして、それから給与の等級でソートする) のに役立ちます。

ソートの例と簡単なチュートリアルは Sorting Techniques を参照して下さい。

CPython 実装の詳細: リストがソートされている間、または変更しようとする試みの影響中、あるいは検査中でさえ、リストは未定義です。Python の C 実装では、それらが続いている間、リストは空として出力され、リストがソート中に変更されていることを検知できたら ValueError を送出します。

タプル型 (tuple)

タプルはイミュータブルなシーケンスで、一般的に異種のデータの集まり (組み込みの enumerate() で作られた 2-タプルなど) を格納するために使われます。タプルはまた、同種のデータのイミュータブルなシーケンスが必要な場合 (set インスタンスや dict インスタンスに保存できるようにするためなど) にも使われます。

class tuple([iterable])

タプルの構成にはいくつかの方法があります:

丸括弧の対を使い、空のタプルを表す: ()

カンマを使い、単要素のタプルを表す: a, または (a,)

項目をカンマで区切る: a, b, c または (a, b, c)

組み込みの tuple() を使う: tuple() または tuple(iterable)

コンストラクタは、 iterable の項目と同じ項目で同じ順のタプルを構築します。 iterable は、シーケンス、イテレートをサポートするコンテナ、またはイテレータオブジェクトです。 iterable が既にタプルなら、そのまま返されます。例えば、 tuple('abc') は ('a', 'b', 'c') を、 tuple( [1, 2, 3] ) は (1, 2, 3) を返します。引数が与えられなければ、このコンストラクタは新しい空のタプル () を作成します。

なお、タプルを作るのはカンマであり、丸括弧ではありません。丸括弧は省略可能ですが、空のタプルの場合や構文上の曖昧さを避けるのに必要な時は例外です。例えば、 f(a, b, c) は三引数の関数呼び出しですが、f((a, b, c)) は 3-タプルを唯一の引数とする関数の呼び出しです。

タプルは 共通の シーケンス演算をすべて実装します。

異種のデータの集まりで、インデックスによってアクセスするよりも名前によってアクセスしたほうが明確になるものには、単純なタプルオブジェクトよりも collections.namedtuple() が向いているかもしれません。

range

range 型は、数のイミュータブルなシーケンスを表し、一般に for ループにおいて特定の回数のループに使われます。

class range(stop)

class range(start, stop[, step])

range コンストラクタの引数は整数 (組み込みの int または __index__() 特殊メソッドを実装するオブジェクト) でなければなりません。step 引数が省略された場合のデフォルト値は 1 です。start 引数が省略された場合のデフォルト値は 0 です。 step が 0 の場合、ValueError が送出されます。

step が正の場合、range r の内容は式 r[i] = start + step*i で決定されます。ここで、 i >= 0 かつ r[i] < stop です。

step が負の場合も、range r の内容は式 r[i] = start + step*i で決定されます。ただし、制約条件は i >= 0 かつ r[i] > stop です。

r[0] が値の制約を満たさない場合、range オブジェクトは空になります。range は負のインデックスをサポートしますが、これらは正のインデックスにより決定されるシーケンスの末尾からのインデックス指定として解釈されます。

range は sys.maxsize より大きい絶対値を含むことができますが、いくつかの機能 (len() など) は OverflowError を送出することがあります。

range の例:

>>> 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))
[]

range は 共通の シーケンス演算を、結合と繰り返し以外すべて実装します (range オブジェクトは厳格なパターンに従うシーケンスのみを表せ、繰り返しと結合はたいていそのパターンを破るという事実によります)。

start

引数 start の値 (この引数が与えられていない場合は 0)

stop

引数 stop の値

step

引数 step の値 (この引数が与えられていない場合は 1)

range 型が通常の list や tuple にまさる点は、range オブジェクトがサイズや表す範囲にかかわらず常に一定の (小さな) 量のメモリを使うことです (start、stop、step の値のみを保存し、後は必要に応じて個々の項目や部分 range を計算するためです)。

range オブジェクトは collections.abc.Sequence ABC を実装し、包含判定、要素インデックス検索、スライシングのような機能を提供し、負のインデックスをサポートします (シーケンス型 --- list, tuple, range を参照):

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

== および != による range オブジェクトの等価性の判定は、これらをシーケンスとして比較します。つまり、二つの range オブジェクトは同じ値のシーケンスを表すなら等しいとみなされます。(なお、二つの等しいとされる range オブジェクトが異なる start, stop および step 属性を持つことがあります。例えば range(0) == range(2, 1, 3) や range(0, 3, 2) == range(0, 4, 2)。)

バージョン 3.2 で変更: シーケンス ABC を実装。スライスと負のインデックスのサポート。int オブジェクトの帰属判定を、すべてのアイテムをイテレートする代わりに、定数時間で行います。

バージョン 3.3 で変更: (オブジェクトの同一性に基づいて比較する代わりに) range オブジェクトをそれらが定義する値のシーケンスに基づいて比較するように '==' と '!=' を定義しました。

属性 start, stop および step が追加。

参考

The linspace recipe [https://code.activestate.com/recipes/579000-equally-spaced-numbers-linspace/] shows how to implement a lazy version of range suitable for floating point applications.

テキストシーケンス型 --- str

Python のテキストデータは str オブジェクト、すなわち 文字列 として扱われます。文字列は Unicode コードポイントのイミュータブルな シーケンス です。文字列リテラルには様々な記述方法があります:

シングルクォート: '"ダブル" クォートを埋め込むことができます'

ダブルクォート: "'シングル' クォートを埋め込むことができます"。

三重引用符: '''三つのシングルクォート''', """三つのダブルクォート"""

三重引用符文字列は、複数行に分けることができます。関連付けられる空白はすべて文字列リテラルに含まれます。

単式の一部であり間に空白のみを含む文字列リテラルは、一つの文字列リテラルに暗黙に変換されます。つまり、("spam " "eggs") == "spam eggs" です。

サポートされている エスケープシーケンス や、ほとんどのエスケープシーケンスの処理を無効化する r ("raw") 接頭辞など、文字列リテラルのさまざまな形式についての詳細は 文字列およびバイト列リテラル を参照してください。

文字列は他のオブジェクトに str コンストラクタを使うことでも生成できます。

"character" 型が特別に用意されているわけではないので、文字列のインデックス指定を行うと長さ 1 の文字列を作成します。つまり、空でない文字列 s に対し、s[0] == s[0:1] です。

ミュータブルな文字列型もありませんが、ミュータブルな断片から効率よく文字列を構成するのに str.join() や io.StringIO が使えます。

バージョン 3.3 で変更: Python 2 シリーズとの後方互換性のため、文字列リテラルの u 接頭辞が改めて許可されました。それは文字列リテラルとしての意味には影響がなく、 r 接頭辞と結合することはできません。

class str(object='')

class str(object=b'', encoding='utf-8', errors='strict')

object の 文字列 版を返します。 object が与えられなかった場合、空文字列が返されます。それ以外の場合 str() の動作は、 encoding や errors が与えられたかどうかによって次のように変わります。

encoding も errors も与えられない場合、 str(object) は "形式ばらず"、 表示用にきれいに整えられた object の文字列表現である type(object).__str__(object) を返します。文字列オブジェクトに対しては、文字列そのものです。 object が __str__() メソッドを持たない場合、 str() は代わりに repr(object) の結果を返します。

encoding か errors の少なくとも一方が与えられた場合、 object は bytes-like object (たとえば bytes や bytearray) でなくてはなりません。object が bytes (もしくは bytearray) オブジェクトである場合は、 str(bytes, encoding, errors) は bytes.decode(encoding, errors) と等価です。そうでない場合は、 bytes.decode() が呼ばれる前に buffer オブジェクトの下層にある bytes オブジェクトが取得されます。 buffer オブジェクトについて詳しい情報は、 バイナリシーケンス型 --- bytes, bytearray, memoryview や バッファプロトコル (buffer Protocol) を参照してください。

encoding 引数や errors 引数無しに bytes オブジェクトを str() に渡すと、略式の文字列表現を返す 1 つ目の場合に該当します。(Python のコマンドラインオプション -b も参照してください) 例えば:

>>> str(b'Zoot!')
"b'Zoot!'"

str クラスとそのメソッドについて詳しくは、 テキストシーケンス型 — str や 文字列メソッド の節を参照してください。フォーマットされた文字列を出力するには、 f-strings と カスタムの文字列書式化 の節を参照してください。加えて、 テキスト処理サービス の節も参照してください。

文字列メソッド

文字列は 共通の シーケンス演算全てに加え、以下に述べるメソッドを実装します。

文字列は、二形式の文字列書式化をサポートします。一方は柔軟さが高くカスタマイズできます (str.format()、 書式指定文字列の文法 、および カスタムの文字列書式化 を参照してください)。他方は C 言語の printf 形式の書式化に基づいてより狭い範囲と型を扱うもので、正しく扱うのは少し難しいですが、扱える場合ではたいていこちらのほうが高速です (printf 形式の文字列書式化)。

標準ライブラリの テキスト処理サービス 節は、その他テキストに関する様々なユーティリティ (re モジュールによる正規表現サポートなど) を提供するいくつかのモジュールをカバーしています。

str.capitalize()

最初の文字を大文字にし、残りを小文字にした文字列のコピーを返します。

バージョン 3.8 で変更: 最初の文字が大文字ではなくタイトルケースに置き換えられるようになりました。つまり二重音字のような文字はすべての文字が大文字にされるのではなく、最初の文字だけ大文字にされるようになります。

str.casefold()

文字列の casefold されたコピーを返します。casefold された文字列は、大文字小文字に関係ないマッチに使えます。

casefold は、小文字化と似ていますが、より積極的です。これは文字列の大文字小文字の区別をすべて取り去ることを意図しているためです。例えば、ドイツ語の小文字 'ß' は "ss" と同じです。これは既に小文字なので、lower() は 'ß' に何もしませんが、casefold() はこれを "ss" に変換します。

The casefolding algorithm is described in section 3.13 'Default Case Folding' of the Unicode Standard [https://www.unicode.org/versions/Unicode15.0.0/ch03.pdf].

Added in version 3.3.

str.center(width[, fillchar])

width の長さをもつ中央寄せされた文字列を返します。パディングには fillchar で指定された値 (デフォルトでは ASCII スペース) が使われます。 width が len(s) 以下なら元の文字列が返されます。

str.count(sub[, start[, end]])

[start, end] の範囲に、部分文字列 sub が重複せず出現する回数を返します。オプション引数 start および end はスライス表記と同じように解釈されます。

sub が空の場合は、文字と文字の間にある空文字列の数、すなわち文字列の長さに1を加えたものを返します。

str.encode(encoding='utf-8', errors='strict')

bytes にエンコードされた文字列を返します。

encoding のデフォルト値は 'utf-8' です; 指定可能な値については 標準エンコーディング を参照してください。

errors はエンコーディングエラーをどのように取り扱うかを制御します。 'strict' (デフォルト) では UnicodeError 例外が送出されます。そのほかに指定可能な値は 'ignore', 'replace', 'xmlcharrefreplace', 'backslashreplace' と、そして codecs.register_error() で登録された名前です。詳しくは エラーハンドラ を参照してください。

パフォーマンス上の理由から、 errors の値の妥当性は、エンコーディングエラーが実際に発生するか、 Python 開発モード が有効になっているか、もしくは デバッグビルド が使われていない限りチェックされません。

バージョン 3.1 で変更: キーワード引数のサポートが追加されました。

バージョン 3.9 で変更: errors 引数の値は Python 開発モード と デバッグモード でチェックされるようになりました。

str.endswith(suffix[, start[, end]])

文字列が指定された suffix で終わるなら True を、そうでなければ False を返します。 suffix は見つけたい複数の接尾語のタプルでも構いません。オプションの start があれば、その位置から判定を始めます。オプションの end があれば、その位置で比較を止めます。

str.expandtabs(tabsize=8)

文字列内の全てのタブ文字が 1 つ以上のスペースで置換された、文字列のコピーを返します。スペースの数は現在の桁 (column) 位置と tabsize に依存します。タブ位置は tabsize 文字毎に存在します (デフォルト値である 8 の場合、タブ位置は 0, 8, 16 などになります)。文字列を展開するため、まず現桁位置がゼロにセットされ、文字列が 1 文字ずつ調べられます。文字がタブ文字 (\t) であれば、現桁位置が次のタブ位置と一致するまで、1 つ以上のスペースが結果の文字列に挿入されます。(タブ文字自体はコピーされません。) 文字が改行文字 (\n もしくは \r) の場合、文字がコピーされ、現桁位置は 0 にリセットされます。その他の文字は変更されずにコピーされ、現桁位置は、その文字の表示のされ方 (訳注: 全角、半角など) に関係なく、1 ずつ増加します。

>>> '01\t012\t0123\t01234'.expandtabs()
'01      012     0123    01234'
>>> '01\t012\t0123\t01234'.expandtabs(4)
'01  012 0123    01234'

str.find(sub[, start[, end]])

文字列のスライス s[start:end] に部分文字列 sub が含まれる場合、その最小のインデックスを返します。オプション引数 start および end はスライス表記と同様に解釈されます。 sub が見つからなかった場合 -1 を返します。

注釈

find() メソッドは、 sub の位置を知りたいときにのみ使うべきです。 sub が部分文字列であるかどうかのみを調べるには、 in 演算子を使ってください:

>>> 'Py' in 'Python'
True

str.format(*args, **kwargs)

文字列の書式化操作を行います。このメソッドを呼び出す文字列は通常の文字、または、 {} で区切られた置換フィールドを含みます。それぞれの置換フィールドは位置引数のインデックスナンバー、または、キーワード引数の名前を含みます。返り値は、それぞれの置換フィールドが対応する引数の文字列値で置換された文字列のコピーです。

>>> "The sum of 1 + 2 is {0}".format(1+2)
'The sum of 1 + 2 is 3'

書式指定のオプションについては、書式指定文字列を規定する 書式指定文字列の文法 を参照してください。

注釈

数値 (int, float, complex, decimal.Decimal とサブクラス) を n の整数表現型 (例: '{:n}'.format(1234)) でフォーマットするとき、LC_CTYPE ロケールと LC_NUMERIC ロケールの一方または両方が 1 バイトより長い非 ASCII 文字であると同時に異なる値である場合、この関数は localeconv() の decimal_point と thousands_sep フィールドを読み取るため一時的に LC_CTYPE ロケールに LC_NUMERIC のロケール値を設定します。この一時的な変更は他のスレッドの動作に影響します。

バージョン 3.7 で変更: 数値を n の整数表現型でフォーマットするとき、この関数は一時的に LC_CTYPE ロケールに LC_NUMERIC のロケール値を設定する場合があります。

str.format_map(mapping)

str.format(**mapping) と似ていますが、 mapping は dict にコピーされず、直接使われます。これは例えば mapping が dict のサブクラスであるときに便利です:

>>> class Default(dict):
...     def __missing__(self, key):
...         return key
...
>>> '{name} was born in {country}'.format_map(Default(name='Guido'))
'Guido was born in country'

Added in version 3.2.

str.index(sub[, start[, end]])

find() と同様ですが、部分文字列が見つからなかったとき ValueError を送出します。

str.isalnum()

文字列中の全ての文字が英数字で、かつ 1 文字以上あるなら True を、そうでなければ False を返します。文字 c は以下のいずれかが True を返せば英数字です: c.isalpha() 、 c.isdecimal() 、 c.isdigit() 、 c.isnumeric() 。

str.isalpha()

Return True if all characters in the string are alphabetic and there is at least one character, 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, Alphabetic, and Ideographic' of the Unicode Standard [https://www.unicode.org/versions/Unicode15.0.0/ch04.pdf].

str.isascii()

文字列が空であるか、文字列の全ての文字が ASCII である場合に True を、それ以外の場合に False を返します。 ASCII 文字のコードポイントは U+0000-U+007F の範囲にあります。

Added in version 3.7.

str.isdecimal()

文字列中の全ての文字が十進数字で、かつ 1 文字以上あるなら True を、そうでなければ False を返します。十進数字とは十進数を書くのに使われる文字のことで、たとえば U+0660 (ARABIC-INDIC DIGIT ZERO) なども含みます。正式には、Unicode の一般カテゴリ "Nd" に含まれる文字を指します。

str.isdigit()

文字列中の全ての文字が数字で、かつ 1 文字以上あるなら True を、そうでなければ False を返します。ここでの数字とは、十進数字に加えて、互換上付き数字のような特殊操作を必要とする数字を含みます。また 10 を基数とした表現ができないカローシュティー数字のような体系の文字も含みます。正式には、数字とは、プロパティ値 Numeric_Type=Digit または Numeric_Type=Decimal を持つ文字です。

str.isidentifier()

文字列が、 識別子 (identifier) およびキーワード (keyword) 節の言語定義における有効な識別子であれば True を返します。

keyword.iskeyword() は、文字列 s が def や class のような予約済みの識別子かどうかを調べるのに使うことができます。

例:

>>> from keyword import iskeyword

>>> 'hello'.isidentifier(), iskeyword('hello')
(True, False)
>>> 'def'.isidentifier(), iskeyword('def')
(True, True)

str.islower()

文字列中の大小文字の区別のある文字 [4] 全てが小文字で、かつ大小文字の区別のある文字が 1 文字以上あるなら True を、そうでなければ False を返します。

str.isnumeric()

文字列中の全ての文字が数を表す文字で、かつ 1 文字以上あるなら True を、そうでなければ False を返します。数を表す文字は、数字と、Unicode の数値プロパティを持つ全ての文字を含みます。たとえば U+2155 (VULGAR FRACTION ONE FIFTH)。正式には、数を表す文字は、プロパティ値 Numeric_Type=Digit、 Numeric_Type=Decimal または Numeric_Type=Numeric を持つものです。

str.isprintable()

文字列中のすべての文字が印字可能であるか、文字列が空であれば True を、そうでなければ False を返します。非印字可能文字は、 Unicode 文字データベースで "Other" または "Separator" と定義されている文字の、印字可能と見なされる ASCII space (0x20) 以外のものです。(なお、この文脈での印字可能文字は、文字列に repr() が呼び出されるときにエスケープすべきでない文字のことです。これは sys.stdout や sys.stderr に書き込まれる文字列の操作とは関係ありません。)

str.isspace()

文字列が空白文字だけからなり、かつ 1 文字以上ある場合には True を返し、そうでない場合は False を返します。

Unicode 文字データベース (unicodedata を参照) で一般カテゴリが Zs ("Seperator, space") であるか、 双方向クラスが　WS、B、 S のいずれかである場合、その文字は 空白文字(whitespace) です。

str.istitle()

文字列がタイトルケース文字列であり、かつ 1 文字以上ある場合、例えば大文字は大小文字の区別のない文字の後にのみ続き、小文字は大小文字の区別のある文字の後ろにのみ続く場合には True を返します。そうでない場合は False を返します。

str.isupper()

文字列中の大小文字の区別のある文字 [4] 全てが大文字で、かつ大小文字の区別のある文字が 1 文字以上あるなら True を、そうでなければ False を返します。

>>> 'BANANA'.isupper()
True
>>> 'banana'.isupper()
False
>>> 'baNana'.isupper()
False
>>> ' '.isupper()
False

str.join(iterable)

iterable 中の文字列を結合した文字列を返します。 iterable に bytes オブジェクトのような非文字列の値が存在するなら、 TypeError が送出されます。要素間のセパレータは、このメソッドを提供する文字列です。

str.ljust(width[, fillchar])

長さ width の左揃えした文字列を返します。パディングは指定された fillchar (デフォルトでは ASCII スペース) を使って行われます。 width が len(s) 以下ならば、元の文字列が返されます。

str.lower()

全ての大小文字の区別のある文字 [4] が小文字に変換された、文字列のコピーを返します。

The lowercasing algorithm used is described in section 3.13 'Default Case Folding' of the Unicode Standard [https://www.unicode.org/versions/Unicode15.0.0/ch03.pdf].

str.lstrip([chars])

文字列の先頭の文字を除去したコピーを返します。引数 chars は除去される文字の集合を指定する文字列です。 chars が省略されるか None の場合、空白文字が除去されます。 chars 文字列は接頭辞ではなく、その値に含まれる文字の組み合わせ全てがはぎ取られます:

>>> '   spacious   '.lstrip()
'spacious   '
>>> 'www.example.com'.lstrip('cmowz.')
'example.com'

文字の集合全てではなく、指定した文字列そのものを接頭辞として削除するメソッドについては、 str.removeprefix() を参照してください。使用例:

>>> 'Arthur: three!'.lstrip('Arthur: ')
'ee!'
>>> 'Arthur: three!'.removeprefix('Arthur: ')
'three!'

static str.maketrans(x[, y[, z]])

この静的メソッドは str.translate() に使える変換テーブルを返します。

引数を 1 つだけ与える場合、それは Unicode 序数 (整数) または文字 (長さ 1 の文字列) を、Unicode 序数、(任意長の) 文字列、または None に対応づける辞書でなければなりません。このとき、文字で指定したキーは序数に変換されます。

引数を 2 つ指定する場合、それらは同じ長さの文字列である必要があり、結果の辞書では、x のそれぞれの文字が y の同じ位置の文字に対応付けられます。第 3 引数を指定する場合、文字列を指定する必要があり、それに含まれる文字が None に対応付けられます。

str.partition(sep)

文字列を sep の最初の出現位置で区切り、 3 要素のタプルを返します。タプルの内容は、区切りの前の部分、区切り文字列そのもの、そして区切りの後ろの部分です。もし区切れなければ、タプルには元の文字列そのものとその後ろに二つの空文字列が入ります。

str.removeprefix(prefix, /)

文字列が prefix で始まる場合、 string[len(prefix):] を返します。それ以外の場合、元の文字列のコピーを返します:

>>> 'TestHook'.removeprefix('Test')
'Hook'
>>> 'BaseTestCase'.removeprefix('Test')
'BaseTestCase'

Added in version 3.9.

str.removesuffix(suffix, /)

文字列が suffix で終わる場合、 string[:-len(suffix)] を返します。それ以外の場合、元の文字列のコピーを返します:

>>> 'MiscTests'.removesuffix('Tests')
'Misc'
>>> 'TmpDirMixin'.removesuffix('Tests')
'TmpDirMixin'

Added in version 3.9.

str.replace(old, new[, count])

Return a copy of the string with all occurrences of substring old replaced by new. If the optional argument count is given, only the first count occurrences are replaced.

str.rfind(sub[, start[, end]])

文字列中の領域 s[start:end] に sub が含まれる場合、その最大のインデックスを返します。オプション引数 start および end はスライス表記と同様に解釈されます。 sub が見つからなかった場合 -1 を返します。

str.rindex(sub[, start[, end]])

rfind() と同様ですが、 sub が見つからなかった場合 ValueError を送出します。

str.rjust(width[, fillchar])

width の長さをもつ右寄せした文字列を返します。パディングには fillchar で指定された文字(デフォルトでは ASCII スペース)が使われます。 width が len(s) 以下の場合、元の文字列が返されます。

str.rpartition(sep)

文字列を sep の最後の出現位置で区切り、 3 要素のタプルを返します。タプルの内容は、区切りの前の部分、区切り文字列そのもの、そして区切りの後ろの部分です。もし区切れなければ、タプルには二つの空文字列とその後ろに元の文字列そのものが入ります。

str.rsplit(sep=None, maxsplit=-1)

sep を区切り文字とした、文字列中の単語のリストを返します。 maxsplit が与えられた場合、文字列の 右端 から最大 maxsplit 回分割を行います。sep が指定されていない、あるいは None のとき、全ての空白文字が区切り文字となります。右から分割していくことを除けば、 rsplit() は後ほど詳しく述べる split() と同様に振る舞います。

str.rstrip([chars])

文字列の末尾部分を除去したコピーを返します。引数 chars は除去される文字集合を指定する文字列です。 chars が省略されるか None の場合、空白文字が除去されます。 chars 文字列は接尾語ではなく、そこに含まれる文字の組み合わせ全てがはぎ取られます:

>>> '   spacious   '.rstrip()
'   spacious'
>>> 'mississippi'.rstrip('ipz')
'mississ'

文字の集合全てではなく、指定した文字列そのものを接尾辞として削除するメソッドについては str.removesuffix() を参照してください。使用例:

>>> 'Monty Python'.rstrip(' Python')
'M'
>>> 'Monty Python'.removesuffix(' Python')
'Monty'

str.split(sep=None, maxsplit=-1)

文字列を sep をデリミタ文字列として区切った単語のリストを返します。maxsplit が与えられていれば、最大で maxsplit 回分割されます (つまり、リストは最大 maxsplit+1 要素になります)。 maxsplit が与えられないか -1 なら、分割の回数に制限はありません (可能なだけ分割されます)。

sep が与えられた場合、連続した区切り文字はまとめられず、空の文字列を区切っていると判断されます(例えば '1,,2'.split(',') は ['1', '', '2'] を返します)。引数 sep は複数の文字にもできます (例えば '1<>2<>3'.split('<>') は ['1', '2', '3'] を返します)。区切り文字を指定して空の文字列を分割すると、 [''] を返します。

例えば:

>>> '1,2,3'.split(',')
['1', '2', '3']
>>> '1,2,3'.split(',', maxsplit=1)
['1', '2,3']
>>> '1,2,,3,'.split(',')
['1', '2', '', '3', '']

sep が指定されていないか None の場合、異なる分割アルゴリズムが適用されます。連続する空白文字はひとつのデリミタとみなされます。また、文字列の先頭や末尾に空白があっても、結果の最初や最後に空文字列は含まれません。よって、空文字列や空白だけの文字列を None デリミタで分割すると [] が返されます。

例えば:

>>> '1 2 3'.split()
['1', '2', '3']
>>> '1 2 3'.split(maxsplit=1)
['1', '2 3']
>>> '   1   2   3   '.split()
['1', '2', '3']

str.splitlines(keepends=False)

文字列を改行部分で分解し、各行からなるリストを返します。 keepends に真が与えらない限り、返されるリストに改行は含まれません。

このメソッドは以下の行境界で分解します。特に、以下の境界は universal newlines のスーパーセットです。

表現

説明

\n

改行

\r

復帰

\r\n

改行 + 復帰

\v or \x0b

垂直タブ

\f or \x0c

改ページ

\x1c

ファイル区切り

\x1d

グループ区切り

\x1e

レコード区切り

\x85

改行 (C1 制御コード)

\u2028

行区切り

\u2029

段落区切り

バージョン 3.2 で変更: \v と \f が行境界のリストに追加されました。

例えば:

>>> 'ab c\n\nde fg\rkl\r\n'.splitlines()
['ab c', '', 'de fg', 'kl']
>>> 'ab c\n\nde fg\rkl\r\n'.splitlines(keepends=True)
['ab c\n', '\n', 'de fg\r', 'kl\r\n']

split() とは違って、デリミタ文字列 sep が与えられたとき、このメソッドは空文字列に空リストを返し、終末の改行は結果に行を追加しません:

>>> "".splitlines()
[]
>>> "One line\n".splitlines()
['One line']

比較のために split('\n') は以下のようになります:

>>> ''.split('\n')
['']
>>> 'Two lines\n'.split('\n')
['Two lines', '']

str.startswith(prefix[, start[, end]])

文字列が指定された prefix で始まるなら True を、そうでなければ False を返します。 prefix は見つけたい複数の接頭語のタプルでも構いません。オプションの start があれば、その位置から判定を始めます。オプションの end があれば、その位置で比較を止めます。

str.strip([chars])

文字列の先頭および末尾部分を除去したコピーを返します。引数 chars は除去される文字集合を指定する文字列です。 chars が省略されるか None の場合、空白文字が除去されます。 chars 文字列は接頭語でも接尾語でもなく、そこに含まれる文字の組み合わせ全てがはぎ取られます:

>>> '   spacious   '.strip()
'spacious'
>>> 'www.example.com'.strip('cmowz.')
'example'

文字列の最も外側の先頭および末尾から、引数 chars 値がはぎ取られます。文字列の先頭から chars の文字集合に含まれない文字に達するまで、文字が削除されます。文字列の末尾に対しても同様の操作が行われます。例えば、次のようになります:

>>> comment_string = '#....... Section 3.2.1 Issue #32 .......'
>>> comment_string.strip('.#! ')
'Section 3.2.1 Issue #32'

str.swapcase()

大文字が小文字に、小文字が大文字に変換された、文字列のコピーを返します。なお、 s.swapcase().swapcase() == s が真であるとは限りません。

str.title()

文字列を、単語ごとに大文字から始まり、残りの文字のうち大小文字の区別があるものは全て小文字にする、タイトルケースにして返します。

例えば:

>>> 'Hello world'.title()
'Hello World'

このアルゴリズムは、連続した文字の集まりという、言語から独立した単純な単語の定義を使います。この定義は多くの状況ではうまく機能しますが、短縮形や所有格のアポストロフィが単語の境界になってしまい、望みの結果を得られない場合があります:

>>> "they're bill's friends from the UK".title()
"They'Re Bill'S Friends From The Uk"

string.capwords() 関数は単語をスペースでのみ分割するため、この問題はありません。

または、正規表現を使うことでアポストロフィに対応できます:

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

str.translate(table)

与えられた変換テーブルに基づいて文字列を構成する各文字をマッピングし、マッピング後の文字列のコピーを返します。変換テーブルは、__getitem__() によるインデックス指定を実装するオブジェクトである必要があります。一般的には、 mapping または sequence です。Unicode 序数 (整数) でインデックス指定する場合、変換テーブルのオブジェクトは次のいずれも行うことができます。Unicode 序数または文字列を返して文字を 1 文字以上の別の文字にマッピングすること、None を返して返り値の文字列から指定した文字を削除すること、例外 LookupError を送出して文字をその文字自身にマッピングすること。

文字から文字への異なる形式のマッピングから変換マップを作成するために、 str.maketrans() が使えます。

文字のマッピングを好みに合わせてより柔軟に変更する方法については、codecs モジュールも参照してください。

str.upper()

全ての大小文字の区別のある文字 [4] が大文字に変換された、文字列のコピーを返します。なお s.upper().isupper() は、 s が大小文字の区別のある文字を含まなかったり、結果の文字の Unicode カテゴリが "Lu" ではなく例えば "Lt" (Letter, titlecase) などであったら、 False になりえます。

The uppercasing algorithm used is described in section 3.13 'Default Case Folding' of the Unicode Standard [https://www.unicode.org/versions/Unicode15.0.0/ch03.pdf].

str.zfill(width)

長さが width になるよう ASCII '0' で左詰めした文字列のコピーを返します。先頭が符号接頭辞 ('+'/'-') だった場合、 '0' は符号の前ではなく 後 に挿入されます。width が len(s) 以下の場合元の文字列を返します。

例えば:

>>> "42".zfill(5)
'00042'
>>> "-42".zfill(5)
'-0042'

printf 形式の文字列書式化

注釈

ここで解説されているフォーマット操作には、(タプルや辞書を正しく表示するのに失敗するなどの) よくある多くの問題を引き起こす、様々な欠陥が出現します。新しい フォーマット済み文字列リテラル や str.format() インターフェースや テンプレート文字列 が、これらの問題を回避する助けになるでしょう。これらの代替手段には、それ自身に、トレードオフや、簡潔さ、柔軟さ、拡張性といった利点があります。

String objects have one unique built-in operation: the % operator (modulo). This is also known as the string formatting or interpolation operator. Given format % values (where format is a string), % conversion specifications in format are replaced with zero or more elements of values. The effect is similar to using the sprintf() in the C language.

format が単一の引数しか要求しない場合、 values はタプルでない単一のオブジェクトでもかまいません。 [5] それ以外の場合、 values はフォーマット文字列中で指定された項目と正確に同じ数の要素からなるタプルか、単一のマップオブジェクトでなければなりません。

一つの変換指定子は 2 またはそれ以上の文字を含み、その構成要素は以下からなりますが、示した順に出現しなければなりません:

指定子の開始を示す文字 '%' 。

マップキー (オプション)。丸括弧で囲った文字列からなります (例えば (somename)) 。

変換フラグ (オプション)。一部の変換型の結果に影響します。

最小のフィールド幅 (オプション)。 '*' (アスタリスク) を指定した場合、実際の文字列幅が values タプルの次の要素から読み出されます。タプルには最小フィールド幅やオプションの精度指定の後に変換したいオブジェクトがくるようにします。

精度 (オプション)。 '.' (ドット) とその後に続く精度で与えられます。 '*' (アスタリスク) を指定した場合、精度の桁数は values タプルの次の要素から読み出されます。タプルには精度指定の後に変換したい値がくるようにします。

精度長変換子 (オプション)。

変換型。

% 演算子の右側の引数が辞書の場合 (またはその他のマップ型の場合), 文字列中のフォーマットには、辞書に挿入されているキーを丸括弧で囲い、文字 '%' の直後にくるようにしたものが含まれていなければ なりません 。マップキーはフォーマット化したい値をマップから選び出します。例えば:

>>> print('%(language)s has %(number)03d quote types.' %
...       {'language': "Python", "number": 2})
Python has 002 quote types.

この場合、 * 指定子をフォーマットに含めてはいけません (* 指定子は順番付けされたパラメタのリストが必要だからです)。

変換フラグ文字を以下に示します:

Flag

意味

'#'

値の変換に (下で定義されている) "別の形式" を使います。

'0'

数値型に対してゼロによるパディングを行います。

'-'

変換された値を左寄せにします ('0' と同時に与えた場合、 '0' を上書きします) 。

' '

(スペース) 符号付きの変換で正の数の場合、前に一つスペースを空けます (そうでない場合は空文字になります) 。

'+'

変換の先頭に符号文字 ('+' または '-') を付けます("スペース" フラグを上書きします) 。

精度長変換子(h, l,または L) を使うことができますが、 Python では必要ないため無視されます。 -- つまり、例えば %ld は %d と等価です。

変換型を以下に示します:

変換

意味

注釈

'd'

符号付き 10 進整数。

'i'

符号付き 10 進整数。

'o'

符号付き 8 進数。

(1)

'u'

旧式の型 -- 'd' と同じです。

(6)

'x'

符号付き 16 進数 (小文字)。

(2)

'X'

符号付き 16 進数 (大文字)。

(2)

'e'

指数表記の浮動小数点数 (小文字)。

(3)

'E'

指数表記の浮動小数点数 (大文字)。

(3)

'f'

10 進浮動小数点数。

(3)

'F'

10 進浮動小数点数。

(3)

'g'

浮動小数点数。指数部が -4 以上または精度以下の場合には小文字指数表記、それ以外の場合には10進表記。

(4)

'G'

浮動小数点数。指数部が -4 以上または精度以下の場合には大文字指数表記、それ以外の場合には10進表記。

(4)

'c'

文字一文字 (整数または一文字からなる文字列を受理します)。

'r'

文字列 (Python オブジェクトを repr() で変換します)。

(5)

's'

文字列 (Python オブジェクトを str() で変換します)。

(5)

'a'

文字列 (Python オブジェクトを ascii() で変換します)。

(5)

'%'

引数を変換せず、返される文字列中では文字 '%' になります。

注釈:

別の形式を指定（訳注: 変換フラグ # を使用）すると 8 進数を表す接頭辞 ('0o') が最初の数字の前に挿入されます。

別の形式を指定（訳注: 変換フラグ # を使用）すると 16 進数を表す接頭辞 '0x' または '0X' (使用するフォーマット文字が 'x' か 'X' に依存します) が最初の数字の前に挿入されます。

この形式にした場合、変換結果には常に小数点が含まれ、それはその後ろに数字が続かない場合にも適用されます。

指定精度は小数点の後の桁数を決定し、そのデフォルトは 6 です。

この形式にした場合、変換結果には常に小数点が含まれ他の形式とは違って末尾の 0 は取り除かれません。

指定精度は小数点の前後の有効桁数を決定し、そのデフォルトは 6 です。

精度が N なら、出力は N 文字に切り詰められます。

PEP 237 [https://peps.python.org/pep-0237/] を参照してください。

Python 文字列には明示的な長さ情報があるので、 %s 変換において '\0' を文字列の末端と仮定したりはしません。

バージョン 3.1 で変更: 絶対値が 1e50 を超える数値の %f 変換が %g 変換に置き換えられなくなりました。

バイナリシーケンス型 --- bytes, bytearray, memoryview

バイナリデータを操作するためのコア組み込み型は bytes および bytearray です。これらは、別のバイナリオブジェクトのメモリにコピーを作成すること無くアクセスするための バッファプロトコル を利用する memoryview でサポートされています。

array モジュールは、32 ビット整数や IEEE754 倍精度浮動小数点値のような基本データ型の、効率的な保存をサポートしています。

バイトオブジェクト

bytes はバイトの不変なシーケンスです。多くのメジャーなプロトコルがASCIIテキストエンコーディングをベースにしているので、 bytes オブジェクトは ASCII 互換のデータに対してのみ動作する幾つかのメソッドを提供していて、文字列オブジェクトと他の多くの点で近いです。

class bytes([source[, encoding[, errors]]])

まず、 bytes リテラルの構文は文字列リテラルとほぼ同じで、 b というプリフィックスを付けます:

シングルクォート: b'still allows embedded "double" quotes'

ダブルクォート: b"still allows embedded 'single' quotes".

3重クォート: b'''3 single quotes''', b"""3 double quotes"""

bytes リテラルでは (ソースコードのエンコーディングに関係なく) ASCII文字のみが許可されています。 127より大きい値を bytes リテラルに記述する場合は適切なエスケープシーケンスを書く必要があります。

文字列リテラルと同じく、 bytes リテラルでも r プリフィックスを用いてエスケープシーケンスの処理を無効にすることができます。 bytes リテラルの様々な形式やサポートされているエスケープシーケンスについては 文字列およびバイト列リテラル を参照してください。

bytesリテラルと repr 出力は ASCII テキストをベースにしたものですが、 bytes オブジェクトは、各値が 0 <= x < 256 の範囲に収まるような整数 (この制限に違反しようとすると ValueError が発生します) の不変なシーケンスとして振る舞います。多くのバイナリフォーマットがASCIIテキストを元にした要素を持っていたり何らかのテキスト操作アルゴリズムによって操作されるものの、任意のバイナリデータが一般にテキストになっているわけではないことを強調するためにこのように設計されました (何も考えずにテキスト操作アルゴリズムをASCII非互換なバイナリデータフォーマットに対して行うとデータを破壊することがあります)。

リテラル以外に、幾つかの方法で bytes オブジェクトを作ることができます:

指定された長さの、0で埋められた bytes オブジェクト: bytes(10)

整数の iterable から: bytes(range(20))

既存のバイナリデータからバッファプロトコルでコピーする: bytes(obj)

bytes ビルトイン関数も参照してください。

16 進数で 2 桁の数は正確に 1 バイトに相当するため、16 進整はバイナリデータを表現する形式として広く使われています。 従って、 bytes 型にはその形式でデータを読み取るための追加のクラスメソッドがあります。

classmethod fromhex(string)

この bytes のクラスメソッドは、与えられた文字列オブジェクトをデコードして bytes オブジェクトを返します。それぞれのバイトを 16 進数 2 桁で表現した文字列を指定しなければなりません。ASCII 空白文字は無視されます。

>>> bytes.fromhex('2Ef0 F1f2  ')
b'.\xf0\xf1\xf2'

バージョン 3.7 で変更: bytes.fromhex() は文字列にある空白だけでなく、 ASCII の空白文字全てをスキップするようになりました。

bytes オブジェクトをその 16 進表記に変換するための、反対向きの変換関数があります。

hex([sep[, bytes_per_sep]])

インスタンス内の 1 バイトにつき 2 つの 16 進数を含む、文字列オブジェクトを返します。

>>> b'\xf0\xf1\xf2'.hex()
'f0f1f2'

16進数文字列を読みやすく表示したい場合、単一文字パラメータ sep を指定してセパレータを出力に含めることができます。デフォルトでは、セパレータはバイトごとに表示が区切られるように追加されます。2つ目のオプションパラメータ bytes_per_sep はセパレータを入れる間隔を制御します。正の整数値はセパレータの位置を右から計算し、負の整数値は左から計算します。

>>> value = b'\xf0\xf1\xf2'
>>> value.hex('-')
'f0-f1-f2'
>>> value.hex('_', 2)
'f0_f1f2'
>>> b'UUDDLRLRAB'.hex(' ', -4)
'55554444 4c524c52 4142'

Added in version 3.5.

バージョン 3.8 で変更: bytes.hex() が、16進数出力の各バイトを分割するセパレータを挿入するためのオプションパラメータ sep と bytes_per_sep をサポートするようになりました。

bytes オブジェクトは (タプルに似た) 整数のシーケンスなので、 bytes オブジェクト b について、 b[0] は整数になり、 b[0:1] は長さ 1 の bytes オブジェクトになります。 (この動作は、文字列に対するインデックス指定もスライスも長さ 1 の文字列を返すのと対照的です。)

bytes オブジェクトの repr 出力はリテラル形式 (b'...') になります。 bytes([46, 46, 46]) などの形式よりも便利な事が多いからです。 bytes オブジェクトはいつでも list(b) で整数のリストに変換できます。

bytearray オブジェクト

bytearray オブジェクトは bytes オブジェクトの可変なバージョンです。

class bytearray([source[, encoding[, errors]]])

bytearray に専用のリテラル構文はないので、コンストラクタを使って作成します:

空のインスタンスを作る: bytearray()

指定された長さの0で埋められたインスタンスを作る: bytearray(10)

整数の iterable から: bytearray(range(20))

既存のバイナリデータからバッファプロトコルを通してコピーする: bytearray(b'Hi!')

bytearray オブジェクトは可変なので、 bytes と bytearray の操作 で解説されている bytes オブジェクトと共通の操作に加えて、 mutable シーケンス操作もサポートしています。

bytearray ビルトイン関数も参照してください。

16 進数で 2 桁の数は正確に 1 バイトに相当するため、16 進整はバイナリデータを表現する形式として広く使われています。 従って、 bytearray 型にはその形式でデータを読み取るための追加のクラスメソッドがあります。

classmethod fromhex(string)

この bytearray のクラスメソッドは、与えられた文字列オブジェクトをデコードして bytearray オブジェクトを返します。それぞれのバイトを 16 進数 2 桁で表現した文字列を指定しなければなりません。ASCII 空白文字は無視されます。

>>> bytearray.fromhex('2Ef0 F1f2  ')
bytearray(b'.\xf0\xf1\xf2')

バージョン 3.7 で変更: bytearray.fromhex() は文字列にある空白だけでなく、 ASCII の空白文字全てをスキップするようになりました。

bytearray オブジェクトをその 16 進表記に変換するための、反対向きの変換関数があります。

hex([sep[, bytes_per_sep]])

インスタンス内の 1 バイトにつき 2 つの 16 進数を含む、文字列オブジェクトを返します。

>>> bytearray(b'\xf0\xf1\xf2').hex()
'f0f1f2'

Added in version 3.5.

バージョン 3.8 で変更: bytes.hex() と同様に、 bytearray.hex() が、16進数出力の各バイトを分割するセパレータを挿入するためのオプションパラメータ sep と bytes_per_sep をサポートするようになりました。

bytearray オブジェクトは整数のシーケンス (リストのようなもの) なので、 bytearray オブジェクト b について、 b[0] は整数になり、 b[0:1] は長さ 1 の bytearray オブジェクトになります。(これは、文字列においてインデックス指定もスライスも長さ 1 の文字列を返すのと対照的です。)

bytearray オブジェクトの表記はバイトのリテラル形式 (bytearray(b'...')) を使用します。これは bytearray([46, 46, 46]) などの形式よりも便利な事が多いためです。 bytearray オブジェクトはいつでも list(b) で整数のリストに変換できます。

bytes と bytearray の操作

bytes と bytearray は両方共 一般のシーケンス操作 をサポートしています。また、両方とも bytes-like object をサポートしている任意のオブジェクトを対象に操作することもできます。この柔軟性により bytes と bytearray を自由に混ぜてもエラーを起こすことなく扱うことができます。ただし、操作の結果のオブジェクトはその操作の順序に依存することになります。

注釈

文字列のメソッドが引数として bytes を受け付けないのと同様、bytes オブジェクトと bytearray オブジェクトのメソッドは引数として文字列を受け付けません。例えば、以下のように書かなければなりません:

a = "abc"
b = a.replace("a", "f")

および:

a = b"abc"
b = a.replace(b"a", b"f")

いくつかの bytes と bytearray の操作は ASCII と互換性のあるバイナリフォーマットが使われていると仮定していますので、フォーマットの不明なバイナリデータに対して使うことは避けるべきです。こうした制約については以下で説明します。

注釈

これらの ASCII ベースの演算を使って ASCII ベースではないバイナリデータを操作すると、データを破壊する恐れがあります。

以下の bytes および bytearray オブジェクトのメソッドは、任意のバイナリデータに対して使用できます。

bytes.count(sub[, start[, end]])

bytearray.count(sub[, start[, end]])

[start, end] の範囲に、部分シーケンス sub が重複せず出現する回数を返します。オプション引数 start および end はスライス表記と同じように解釈されます。

検索対象の部分シーケンスは、任意の bytes-like object または 0 から 255 の範囲の整数にできます。

sub が空の場合は、文字と文字の間にある空のスライスの数、すなわちbytesオブジェクトの長さに1を加えたものを返します。

バージョン 3.3 で変更: 部分シーケンスとして 0 から 255 の範囲の整数も受け取れるようになりました。

bytes.removeprefix(prefix, /)

bytearray.removeprefix(prefix, /)

バリナリーデータが文字列 prefix で始まる場合、 bytes[len(prefix):] を返します。それ以外の場合、元のバイナリーデータのコピーを返します:

>>> b'TestHook'.removeprefix(b'Test')
b'Hook'
>>> b'BaseTestCase'.removeprefix(b'Test')
b'BaseTestCase'

prefix は、任意の bytes-like object にできます。

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

Added in version 3.9.

bytes.removesuffix(suffix, /)

bytearray.removesuffix(suffix, /)

バイナリーデータが文字列 suffix で終わり、 suffix が空でない場合、 bytes[:-len(suffix)] を返します。それ以外の場合、元のバイナリーデータのコピーを返します:

>>> b'MiscTests'.removesuffix(b'Tests')
b'Misc'
>>> b'TmpDirMixin'.removesuffix(b'Tests')
b'TmpDirMixin'

suffix は、任意の bytes-like object にできます。

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

Added in version 3.9.

bytes.decode(encoding='utf-8', errors='strict')

bytearray.decode(encoding='utf-8', errors='strict')

str にデコードされたbytesを返します。

encoding のデフォルト値は 'utf-8' です; 指定可能な値については 標準エンコーディング を参照してください。

errors はデコーディングエラーをどのように取り扱うかを制御します。 'strict' (デフォルト) では UnicodeError 例外が送出されます。そのほかに指定可能な値は 'ignore', 'replace' と、そして codecs.register_error() で登録された名前です。詳しくは エラーハンドラ を参照してください。

パフォーマンス上の理由から、 errors の値の妥当性は、デコーディングエラーが実際に発生するか、 Python 開発モード が有効になっているか、もしくは デバッグビルド が使われていない限りチェックされません。

注釈

引数 encoding を str に渡すと bytes-like object を直接デコードすることができます。つまり、一時的な bytes や bytearray オブジェクトを作成する必要はありません。

バージョン 3.1 で変更: キーワード引数のサポートが追加されました。

バージョン 3.9 で変更: errors 引数の値は Python 開発モード と デバッグモード でチェックされるようになりました。

bytes.endswith(suffix[, start[, end]])

bytearray.endswith(suffix[, start[, end]])

バイナリデータが指定された suffix で終わる場合は True を、そうでなければ False を返します。 suffix は見つけたい複数の接尾語のタプルでも構いません。オプションの start が指定されている場合、その位置から判定を開始します。オプションの end が指定されている場合、その位置で比較を終了します。

検索対象の接尾語 (複数も可) は、任意の bytes-like object にできます。

bytes.find(sub[, start[, end]])

bytearray.find(sub[, start[, end]])

スライス s[start:end] に部分シーケンス sub が含まれる場合、データ中のその sub の最小のインデックスを返します。オプション引数 start および end はスライス表記と同様に解釈されます。 sub が見つからなかった場合、 -1 を返します。

検索対象の部分シーケンスは、任意の bytes-like object または 0 から 255 の範囲の整数にできます。

注釈

find() メソッドは、 sub の位置を知りたいときにのみ使うべきです。 sub が部分文字列 (訳注: おそらく原文の誤り、正しくは部分シーケンス) であるかどうかのみを調べるには、 in 演算子を使ってください:

>>> b'Py' in b'Python'
True

バージョン 3.3 で変更: 部分シーケンスとして 0 から 255 の範囲の整数も受け取れるようになりました。

bytes.index(sub[, start[, end]])

bytearray.index(sub[, start[, end]])

find() と同様ですが、部分シーケンスが見つからなかった場合 ValueError を送出します。

検索対象の部分シーケンスは、任意の bytes-like object または 0 から 255 の範囲の整数にできます。

バージョン 3.3 で変更: 部分シーケンスとして 0 から 255 の範囲の整数も受け取れるようになりました。

bytes.join(iterable)

bytearray.join(iterable)

iterable 中のバイナリデータを結合した bytes または bytearray オブジェクトを返します。 iterable に str オブジェクトなど bytes-like objects ではない値が含まれている場合、 TypeError が送出されます。なお要素間のセパレータは、このメソッドを提供する bytes または bytearray オブジェクトとなります。

static bytes.maketrans(from, to)

static bytearray.maketrans(from, to)

この静的メソッドは、 bytes.translate() に渡すのに適した変換テーブルを返します。このテーブルは、 from 中の各バイトを to の同じ位置にあるバイトにマッピングします。 from と to は両方とも同じ長さの bytes-like objects でなければなりません。

Added in version 3.1.

bytes.partition(sep)

bytearray.partition(sep)

区切り sep が最初に出現する位置でシーケンスを分割し、 3 要素のタプルを返します。タプルの内容は、区切りの前の部分、その区切りオブジェクトまたはその bytearray 型のコピー、そして区切りの後ろの部分です。もし区切りが見つからなければ、タプルには元のシーケンスのコピーと、その後ろに二つの空の bytes または bytearray オブジェクトが入ります。

検索する区切りとしては、任意の bytes-like object を指定できます。

bytes.replace(old, new[, count])

bytearray.replace(old, new[, count])

部分シーケンス old を全て new に置換したシーケンスを返します。オプション引数 count が与えられている場合、先頭から count 個の old だけを置換します。

検索する部分シーケンスおよび置換後の部分シーケンスとしては、任意の bytes-like object を指定できます。

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

bytes.rfind(sub[, start[, end]])

bytearray.rfind(sub[, start[, end]])

シーケンス中の領域 s[start:end] に sub が含まれる場合、その最大のインデックスを返します。オプション引数 start および end はスライス表記と同様に解釈されます。 sub が見つからなかった場合 -1 を返します。

検索対象の部分シーケンスは、任意の bytes-like object または 0 から 255 の範囲の整数にできます。

バージョン 3.3 で変更: 部分シーケンスとして 0 から 255 の範囲の整数も受け取れるようになりました。

bytes.rindex(sub[, start[, end]])

bytearray.rindex(sub[, start[, end]])

rfind() と同様ですが、部分シーケンス sub が見つからなかった場合 ValueError を送出します。

検索対象の部分シーケンスは、任意の bytes-like object または 0 から 255 の範囲の整数にできます。

バージョン 3.3 で変更: 部分シーケンスとして 0 から 255 の範囲の整数も受け取れるようになりました。

bytes.rpartition(sep)

bytearray.rpartition(sep)

区切り sep が最後に出現する位置でシーケンスを分割し、 3 要素のタプルを返します。タプルの内容は、区切りの前の部分、その区切りオブジェクトまたはその bytearray 型のコピー、そして区切りの後ろの部分です。もし区切れなければ、タプルには二つの空の bytes または bytearray オブジェクトと、その後ろに元のシーケンスのコピーが入ります。

検索する区切りとしては、任意の bytes-like object を指定できます。

bytes.startswith(prefix[, start[, end]])

bytearray.startswith(prefix[, start[, end]])

バイナリデータが指定された prefix で始まる場合は True を、そうでなければ False を返します。 prefix は見つけたい複数の接頭語のタプルでも構いません。オプションの start が指定されている場合、その位置から判定を開始します。オプションの end が指定されている場合、その位置で比較を終了します。

検索対象の接頭語 (複数も可) は、任意の bytes-like object にできます。

bytes.translate(table, /, delete=b'')

bytearray.translate(table, /, delete=b'')

オプション引数 delete に現れるすべてのバイトを除去し、残ったバイトを与えられた変換テーブルに従ってマップした、バイト列やバイト配列オブジェクトのコピーを返します。変換テーブルは長さ 256 のバイト列オブジェクトでなければなりません。

変換テーブルの作成に、 bytes.maketrans() メソッドを使うこともできます。

文字を削除するだけの変換には、 table 引数を None に設定してください:

>>> b'read this short text'.translate(None, b'aeiou')
b'rd ths shrt txt'

バージョン 3.6 で変更: delete はキーワード引数として指定可能になりました。

以下の bytes および bytearray オブジェクトのメソッドは、 ASCII と互換性のあるバイナリフォーマットが使われていると仮定していますが、適切な引数を指定すれば任意のバイナリデータに使用できます。なお、このセクションで紹介する bytearray のメソッドはすべてインプレースで動作 せず 、新しいオブジェクトを生成します。

bytes.center(width[, fillbyte])

bytearray.center(width[, fillbyte])

長さ width の中央寄せされたシーケンスのコピーを返します。パディングには fillbyte で指定された値 (デフォルトでは ASCII スペース) が使われます。 bytes オブジェクトの場合、 width が len(s) 以下なら元のシーケンスが返されます。

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

bytes.ljust(width[, fillbyte])

bytearray.ljust(width[, fillbyte])

長さ width の左寄せされたシーケンスのコピーを返します。パディングには fillbyte で指定された値 (デフォルトでは ASCII スペース) が使われます。 bytes オブジェクトの場合、 width が len(s) 以下なら元のシーケンスが返されます。

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

bytes.lstrip([chars])

bytearray.lstrip([chars])

先頭から特定のバイト値を除去したコピーを返します。引数 chars は除去されるバイト値の集合を指定するバイナリシーケンスです － この名前は、このメソッドが通常は ASCII 文字列に対して使われることに由来しています。 chars が省略されるか None の場合、 ASCII の空白文字 (訳注: 空白文字の定義については bytearray.isspace() を参照) が除去されます。なお chars 引数と一致する接頭辞が除去されるのではなく、それに含まれるバイトの組み合わせ全てが除去されます:

>>> b'   spacious   '.lstrip()
b'spacious   '
>>> b'www.example.com'.lstrip(b'cmowz.')
b'example.com'

削除したいバイト値のバイナリシーケンスには、 bytes-like object を指定することができます。バイナリシーケンスで指定した文字の集合全てではなく、指定した文字列そのものを接頭辞として削除するメソッドについては、 removeprefix() を参照してください。使用例:

>>> b'Arthur: three!'.lstrip(b'Arthur: ')
b'ee!'
>>> b'Arthur: three!'.removeprefix(b'Arthur: ')
b'three!'

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

bytes.rjust(width[, fillbyte])

bytearray.rjust(width[, fillbyte])

長さ width の右寄せされたシーケンスのコピーを返します。パディングには fillbyte で指定された値 (デフォルトでは ASCII スペース) が使われます。 bytes オブジェクトの場合、 width が len(s) 以下なら元のシーケンスが返されます。

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

bytes.rsplit(sep=None, maxsplit=-1)

bytearray.rsplit(sep=None, maxsplit=-1)

sep を区切りとして、同じ型の部分シーケンスに分割します。 maxsplit が与えられた場合、シーケンスの 右端 から最大 maxsplit 回だけ分割を行います。 sep が指定されていないか None のとき、 ASCII 空白文字の組み合わせで作られる部分シーケンスすべてが区切りとなります。右から分割していくことを除けば、 rsplit() は後ほど詳しく述べる split() と同様に振る舞います。

bytes.rstrip([chars])

bytearray.rstrip([chars])

末尾から特定のバイト値を除去したコピーを返します。引数 chars は除去されるバイト値の集合を指定するバイナリシーケンスです － この名前は、このメソッドが通常は ASCII 文字列に対して使われることに由来しています。 chars が省略されるか None の場合、 ASCII の空白文字 (訳注: 空白文字の定義については bytearray.isspace() を参照) が除去されます。なお chars 引数と一致する接尾辞が除去されるのではなく、それに含まれるバイトの組み合わせ全てが除去されます:

>>> b'   spacious   '.rstrip()
b'   spacious'
>>> b'mississippi'.rstrip(b'ipz')
b'mississ'

削除したいバイト値のバイナリシーケンスには、 bytes-like object を指定することができます。バイナリシーケンスで指定した文字の集合全てではなく、指定した文字列そのものを接尾辞として削除するメソッドについては、 removesuffix() を参照してください。使用例:

>>> b'Monty Python'.rstrip(b' Python')
b'M'
>>> b'Monty Python'.removesuffix(b' Python')
b'Monty'

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

bytes.split(sep=None, maxsplit=-1)

bytearray.split(sep=None, maxsplit=-1)

sep を区切りとして、同じ型の部分シーケンスに分割します。 maxsplit が与えられ、かつ負の数でない場合、シーケンスの 左端 から最大 maxsplit 回だけ分割を行います (したがって結果のリストの要素数は最大で maxsplit+1 になります)。 maxsplit が指定されていないか -1 のとき、分割の回数に制限はありません (可能なだけ分割されます)。

sep が与えられた場合、連続した区切り用バイト値はまとめられず、空の部分シーケンスを区切っていると判断されます(例えば b'1,,2'.split(b',') は [b'1', b'', b'2'] を返します)。引数 sep は複数バイトのシーケンスにもできます (例えば b'1<>2<>3'.split(b'<>') は [b'1', b'2', b'3'] を返します)。空のシーケンスを分割すると、分割するオブジェクトの型によって [b''] または [bytearray(b'')] が返ります。引数 sep には、あらゆる bytes-like object を指定できます。

例えば:

>>> 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'', b'3', b'']

sep が指定されていないか None の場合、異なる分割アルゴリズムが適用されます。連続する ASCII 空白文字はひとつの区切りとみなされ、またシーケンスの先頭や末尾に空白があっても、結果の最初や最後に空のシーケンスは含まれません。したがって区切りを指定せずに空のシーケンスや ASCII 空白文字だけのシーケンスを分割すると、 [] が返されます。

例えば:

>>> 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']

bytes.strip([chars])

bytearray.strip([chars])

先頭および末尾から特定のバイト値を除去したコピーを返します。引数 chars は除去されるバイト値の集合を指定するバイナリシーケンスです － この名前は、このメソッドが通常は ASCII 文字列に対して使われることに由来しています。 chars が省略されるか None の場合、 ASCII の空白文字 (訳注: 空白文字の定義については bytearray.isspace() を参照) が除去されます。なお chars 引数と一致する接頭辞および接尾辞が除去されるのではなく、それに含まれるバイトの組み合わせ全てが除去されます:

>>> b'   spacious   '.strip()
b'spacious'
>>> b'www.example.com'.strip(b'cmowz.')
b'example'

除去対象のバイト値を含むバイナリシーケンスには、任意の bytes-like object を指定できます。

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

以下の bytes および bytearray オブジェクトのメソッドは、 ASCII と互換性のあるバイナリフォーマットが使われていると仮定しており、任意のバイナリデータに対して使用すべきではありません。なお、このセクションで紹介する bytearray のメソッドはすべてインプレースで動作 せず 、新しいオブジェクトを生成します。

bytes.capitalize()

bytearray.capitalize()

各バイトを ASCII 文字と解釈して、最初のバイトを大文字にし、残りを小文字にしたシーケンスのコピーを返します。 ASCII 文字と解釈できないバイト値は、変更されません。

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

bytes.expandtabs(tabsize=8)

bytearray.expandtabs(tabsize=8)

桁 (column) 位置と指定されたタブ幅 (tab size) に応じて、全ての ASCII タブ文字を 1 つ以上の ASCII スペース文字に置換したシーケンスのコピーを返します。ここで tabsize バイトごとの桁位置をタブ位置とします (デフォルト値である 8 の場合、タブ位置は 0 桁目、 8 桁目、 16 桁目、と続いていきます)。シーケンスを展開するにあたって、まず現桁位置をゼロに設定し、シーケンスを 1 バイトずつ調べていきます。もしバイト値が ASCII タブ文字 (b'\t') であれば、現桁位置が次のタブ位置と一致するまで 1 つ以上の ASCII スペース文字を結果のシーケンスに挿入していきます（ASCII タブ文字自体はコピーしません）。もしバイト値が ASCII 改行文字 (b'\n' もしくは b'\r') であれば、そのままコピーした上で現桁位置を 0 にリセットします。その他のバイト値については変更せずにコピーし、そのバイト値の表示のされ方（訳注: 全角、半角など）に関わらず現桁位置を 1 つ増加させます:

>>> b'01\t012\t0123\t01234'.expandtabs()
b'01      012     0123    01234'
>>> b'01\t012\t0123\t01234'.expandtabs(4)
b'01  012 0123    01234'

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

bytes.isalnum()

bytearray.isalnum()

シーケンスが空でなく、かつ全てのバイト値が ASCII 文字のアルファベットまたは数字である場合は True を、そうでなければ False を返します。ここでの ASCII 文字のアルファベットとはシーケンス b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ' に含まれるバイト値です。 ASCII 文字の数字とは b'0123456789' に含まれるバイト値です。

例えば:

>>> b'ABCabc1'.isalnum()
True
>>> b'ABC abc1'.isalnum()
False

bytes.isalpha()

bytearray.isalpha()

シーケンスが空でなく、かつ全てのバイト値が ASCII 文字のアルファベットである場合は True を、そうでなければ False を返します。ここでの ASCII 文字のアルファベットとはシーケンス b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ' に含まれるバイト値です。

例えば:

>>> b'ABCabc'.isalpha()
True
>>> b'ABCabc1'.isalpha()
False

bytes.isascii()

bytearray.isascii()

シーケンスが空であるか、シーケンスの全てのバイトが ASCII である場合に True を、それ以外の場合に False を返します。 ASCII バイトは 0-0x7F の範囲にあります。

Added in version 3.7.

bytes.isdigit()

bytearray.isdigit()

シーケンスが空でなく、かつ全てのバイト値が ASCII 文字の数字である場合は True を、そうでなければ False を返します。ここでの ASCII 文字の数字とは b'0123456789' に含まれるバイト値です。

例えば:

>>> b'1234'.isdigit()
True
>>> b'1.23'.isdigit()
False

bytes.islower()

bytearray.islower()

シーケンス中に小文字アルファベットの ASCII 文字が一つ以上あり、かつ大文字アルファベットの ASCII 文字が一つも無い場合に True を返します。そうでなければ False を返します。

例えば:

>>> b'hello world'.islower()
True
>>> b'Hello world'.islower()
False

ここでの小文字の ASCII 文字とは b'abcdefghijklmnopqrstuvwxyz' に含まれるバイト値です。また大文字の ASCII 文字とは b'ABCDEFGHIJKLMNOPQRSTUVWXYZ' に含まれるバイト値です。

bytes.isspace()

bytearray.isspace()

シーケンスが空でなく、かつ全てのバイト値が ASCII 空白文字である場合は True を、そうでなければ False を返します。ここでの ASCII 空白文字とはシーケンス b' \t\n\r\x0b\f' に含まれるバイト値です (半角スペース、タブ、ラインフィード、キャリッジリターン、垂直タブ、フォームフィード) 。

bytes.istitle()

bytearray.istitle()

シーケンスが空でなく、かつ ASCII のタイトルケース文字列になっている場合は True を、そうでなければ False を返します。「タイトルケース文字列」の定義については bytes.title() を参照してください。

例えば:

>>> b'Hello World'.istitle()
True
>>> b'Hello world'.istitle()
False

bytes.isupper()

bytearray.isupper()

シーケンス中に大文字アルファベットの ASCII 文字が一つ以上あり、かつ小文字アルファベットの ASCII 文字が一つも無い場合に True を返します。そうでなければ False を返します。

例えば:

>>> b'HELLO WORLD'.isupper()
True
>>> b'Hello world'.isupper()
False

ここでの小文字の ASCII 文字とは b'abcdefghijklmnopqrstuvwxyz' に含まれるバイト値です。また大文字の ASCII 文字とは b'ABCDEFGHIJKLMNOPQRSTUVWXYZ' に含まれるバイト値です。

bytes.lower()

bytearray.lower()

シーケンスに含まれる大文字アルファベットの ASCII 文字を全て小文字アルファベットに変換したシーケンスのコピーを返します。

例えば:

>>> b'Hello World'.lower()
b'hello world'

ここでの小文字の ASCII 文字とは b'abcdefghijklmnopqrstuvwxyz' に含まれるバイト値です。また大文字の ASCII 文字とは b'ABCDEFGHIJKLMNOPQRSTUVWXYZ' に含まれるバイト値です。

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

bytes.splitlines(keepends=False)

bytearray.splitlines(keepends=False)

バイナリシーケンスを ASCII の改行コードで分割し、各行をリストにして返します。このメソッドは universal newlines アプローチで行を分割します。 keepends 引数に真を与えた場合を除き、改行コードは結果のリストに含まれません。

例えば:

>>> b'ab c\n\nde fg\rkl\r\n'.splitlines()
[b'ab c', b'', 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']

split() とは違って、空シーケンスに対して区切り sep を与えて呼び出すと空のリストを返します。またシーケンス末尾に改行コードがある場合、（訳註: その後ろに空行があるとは判断せず）余分な行を生成することはありません:

>>> b"".split(b'\n'), b"Two lines\n".split(b'\n')
([b''], [b'Two lines', b''])
>>> b"".splitlines(), b"One line\n".splitlines()
([], [b'One line'])

bytes.swapcase()

bytearray.swapcase()

シーケンスに含まれる小文字アルファベットの ASCII 文字を全て大文字アルファベットに変換し、さらに大文字アルファベットを同様に小文字アルファベットに変換したシーケンスのコピーを返します。

例えば:

>>> b'Hello World'.swapcase()
b'hELLO wORLD'

ここでの小文字の ASCII 文字とは b'abcdefghijklmnopqrstuvwxyz' に含まれるバイト値です。また大文字の ASCII 文字とは b'ABCDEFGHIJKLMNOPQRSTUVWXYZ' に含まれるバイト値です。

str.swapcase() とは違い、バイナリバージョンのこちらでは bin.swapcase().swapcase() == bin が常に成り立ちます。一般的に Unicode 文字の大文字小文字変換は対称的ではありませんが、 ASCII 文字の場合は対称的です。

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

bytes.title()

bytearray.title()

タイトルケース化したバイナリシーケンスを返します。具体的には、各単語が大文字アルファベットの ASCII 文字で始まり、かつ残りの文字が小文字アルファベットになっているシーケンスが返ります。大文字小文字の区別が無いバイト値については変更されずそのままになります。

例えば:

>>> b'Hello world'.title()
b'Hello World'

ここでの小文字の ASCII 文字とは b'abcdefghijklmnopqrstuvwxyz' に含まれるバイト値です。また大文字の ASCII 文字とは b'ABCDEFGHIJKLMNOPQRSTUVWXYZ' に含まれるバイト値です。その他のバイト値については、大文字小文字の区別はありません。

このアルゴリズムは、連続した文字の集まりという、言語から独立した単純な単語の定義を使います。この定義は多くの状況ではうまく機能しますが、短縮形や所有格のアポストロフィが単語の境界になってしまい、望みの結果を得られない場合があります:

>>> b"they're bill's friends from the UK".title()
b"They'Re Bill'S Friends From The Uk"

正規表現を使うことでアポストロフィに対応できます:

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

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

bytes.upper()

bytearray.upper()

シーケンスに含まれる小文字アルファベットの ASCII 文字を全て大文字アルファベットに変換したシーケンスのコピーを返します。

例えば:

>>> b'Hello World'.upper()
b'HELLO WORLD'

ここでの小文字の ASCII 文字とは b'abcdefghijklmnopqrstuvwxyz' に含まれるバイト値です。また大文字の ASCII 文字とは b'ABCDEFGHIJKLMNOPQRSTUVWXYZ' に含まれるバイト値です。

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

bytes.zfill(width)

bytearray.zfill(width)

長さが width になるよう ASCII b'0' で左詰めしたシーケンスのコピーを返します。先頭が符号接頭辞 (b'+'/b'-') だった場合、 b'0' は符号の前ではなく 後 に挿入されます。 bytes オブジェクトの場合、 width が len(seq) 以下であれば元のシーケンスが返ります。

例えば:

>>> b"42".zfill(5)
b'00042'
>>> b"-42".zfill(5)
b'-0042'

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

printf 形式での bytes の書式化

注釈

ここで述べる書式化演算には様々な癖があり、よく間違いの元になっています (タプルや辞書を正しく表示できないなど)。もし表示する値がタプルや辞書かもしれない場合、それをタプルに包むようにしてください。

bytes オブジェクト (bytes/bytearray) には固有の操作: % 演算子 (モジュロ) があります。この演算子は bytes の 書式化 または 補間 演算子とも呼ばれます。format % values (format は bytes オブジェクト) とすると、format 中の % 変換指定は values 中のゼロ個またはそれ以上の要素で置換されます。この動作は C 言語における sprintf() に似ています。

format が単一の引数しか要求しない場合、 values はタプルではない単一のオブジェクトで問題ありません。 [5] それ以外の場合、 values は書式シーケンス（訳註: 先の例での format ）中で指定された項目と正確に同じ数の要素を含むタプルか、単一のマッピング型のオブジェクト (たとえば辞書) でなければなりません。

一つの変換指定子は 2 またはそれ以上の文字を含み、その構成要素は以下からなりますが、示した順に出現しなければなりません:

指定子の開始を示す文字 '%' 。

マップキー (オプション)。丸括弧で囲った文字列からなります (例えば (somename)) 。

変換フラグ (オプション)。一部の変換型の結果に影響します。

最小のフィールド幅 (オプション)。 '*' (アスタリスク) を指定した場合、実際の文字列幅が values タプルの次の要素から読み出されます。タプルには最小フィールド幅やオプションの精度指定の後に変換したいオブジェクトがくるようにします。

精度 (オプション)。 '.' (ドット) とその後に続く精度で与えられます。 '*' (アスタリスク) を指定した場合、精度の桁数は values タプルの次の要素から読み出されます。タプルには精度指定の後に変換したい値がくるようにします。

精度長変換子 (オプション)。

変換型。

% 演算子の右側の引数が辞書の場合 (またはその他のマッピング型の場合) 、 bytes オブジェクト中のフォーマットには、辞書のキーを丸括弧で囲って文字 '%' の直後に書いたものが含まれていなければ なりません 。マップキーは書式化したい値をマッピングから選び出します。例えば:

>>> print(b'%(language)s has %(number)03d quote types.' %
...       {b'language': b"Python", b"number": 2})
b'Python has 002 quote types.'

この場合、 * 指定子をフォーマットに含めてはいけません (* 指定子は順番付けされたパラメタのリストが必要だからです)。

変換フラグ文字を以下に示します:

Flag

意味

'#'

値の変換に (下で定義されている) "別の形式" を使います。

'0'

数値型に対してゼロによるパディングを行います。

'-'

変換された値を左寄せにします ('0' と同時に与えた場合、 '0' を上書きします) 。

' '

(スペース) 符号付きの変換で正の数の場合、前に一つスペースを空けます (そうでない場合は空文字になります) 。

'+'

変換の先頭に符号文字 ('+' または '-') を付けます("スペース" フラグを上書きします) 。

精度長変換子(h, l,または L) を使うことができますが、 Python では必要ないため無視されます。 -- つまり、例えば %ld は %d と等価です。

変換型を以下に示します:

変換

意味

注釈

'd'

符号付き 10 進整数。

'i'

符号付き 10 進整数。

'o'

符号付き 8 進数。

(1)

'u'

旧式の型 -- 'd' と同じです。

(8)

'x'

符号付き 16 進数 (小文字)。

(2)

'X'

符号付き 16 進数 (大文字)。

(2)

'e'

指数表記の浮動小数点数 (小文字)。

(3)

'E'

指数表記の浮動小数点数 (大文字)。

(3)

'f'

10 進浮動小数点数。

(3)

'F'

10 進浮動小数点数。

(3)

'g'

浮動小数点数。指数部が -4 以上または精度以下の場合には小文字指数表記、それ以外の場合には10進表記。

(4)

'G'

浮動小数点数。指数部が -4 以上または精度以下の場合には大文字指数表記、それ以外の場合には10進表記。

(4)

'c'

1 バイト (整数または要素 1 つの bytes/bytearray オブジェクトを受理します)

'b'

バイナリシーケンス (buffer protocol をサポートするか、 __bytes__() メソッドがあるオブジェクト)

(5)

's'

's' は 'b' の別名です。Python 2/3 の両方を対象としたコードでのみ使用すべきです。

(6)

'a'

バイナリシーケンス (Python オブジェクトを repr(obj).encode('ascii', 'backslashreplace') で変換します)。

(5)

'r'

'r' は 'a' の別名です。Python 2/3 の両方を対象としたコードでのみ使用すべきです。

(7)

'%'

引数を変換せず、返される文字列中では文字 '%' になります。

注釈:

別の形式を指定（訳注: 変換フラグ # を使用）すると 8 進数を表す接頭辞 ('0o') が最初の数字の前に挿入されます。

別の形式を指定（訳注: 変換フラグ # を使用）すると 16 進数を表す接頭辞 '0x' または '0X' (使用するフォーマット文字が 'x' か 'X' に依存します) が最初の数字の前に挿入されます。

この形式にした場合、変換結果には常に小数点が含まれ、それはその後ろに数字が続かない場合にも適用されます。

指定精度は小数点の後の桁数を決定し、そのデフォルトは 6 です。

この形式にした場合、変換結果には常に小数点が含まれ他の形式とは違って末尾の 0 は取り除かれません。

指定精度は小数点の前後の有効桁数を決定し、そのデフォルトは 6 です。

精度が N なら、出力は N 文字に切り詰められます。

b'%s' は非推奨ですが、3.x 系では削除されません。

b'%r' は非推奨ですが、3.x 系では削除されません。

PEP 237 [https://peps.python.org/pep-0237/] を参照してください。

注釈

bytearray のこのメソッドはインプレースでは動作 しません -- 一切変化が無い場合でも、常に新しいオブジェクトを生成します。

参考

PEP 461 [https://peps.python.org/pep-0461/] - bytes と bytearray への % 書式化の追加

Added in version 3.5.

メモリビュー

memoryview オブジェクトは、Python コードが バッファプロトコル をサポートするオブジェクトの内部データへ、コピーすることなくアクセスすることを可能にします。

class memoryview(object)

object を参照する memoryview を作成します。 object はバッファプロトコルをサポートしていなければなりません。バッファプロトコルをサポートする組み込みオブジェクトには、 bytes 、 bytearray などがあります。

memoryview は元となる object が扱うメモリーの最小単位を 要素 として扱います。多くの単純なオブジェクト、例えば bytes や bytearray では、要素は単バイトになりますが、他の array.array 等の型では、要素はより大きくなりえます。

len(view) はビューの入れ子になったリスト表現である tolist の長さと等しくなります。ビューが view.ndim = 1 を満たす場合はビューの要素数とも等しくなります。

バージョン 3.12 で変更: view.ndim == 0 で len(view) の場合、1の代わりに TypeError を返すようになりました。

itemsize 属性は各要素のバイト数を与えます。

memoryview はスライスおよびインデックス指定で内容を取得できます。一次元のスライスは部分ビューになります:

>>> v = memoryview(b'abcefg')
>>> v[1]
98
>>> v[-1]
103
>>> v[1:4]
<memory at 0x7f3ddc9f4350>
>>> bytes(v[1:4])
b'bce'

もしメモリビューの format が struct モジュールによって定義されているネイティブのフォーマット指定子であれば、整数または整数のタプルでのインデックス指定により適切な型の 要素1つ を得ることができます。一次元のメモリビューでは、整数または整数 1 つのタプルでインデックス指定できます。多次元のメモリビューでは、その次元数を ndim としたとき、ちょうど ndim 個の整数からなるタプルでインデックス指定できます。ゼロ次元のメモリビューでは、空のタプルでインデックス指定できます。

format が単バイト単位ではない例を示します:

>>> import array
>>> a = array.array('l', [-11111111, 22222222, -33333333, 44444444])
>>> m = memoryview(a)
>>> m[0]
-11111111
>>> m[-1]
44444444
>>> m[::2].tolist()
[-11111111, -33333333]

メモリビューの参照しているオブジェクトが書き込み可能であれば、一次元スライスでの代入が可能です。ただしサイズの変更はできません:

>>> 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')

'B', 'b', 'c' いずれかのフォーマットの ハッシュ可能 な (読み出し専用の) 型の1次元メモリビューもまた、ハッシュ可能です。ハッシュは hash(m) == hash(m.tobytes()) として定義されています:

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

バージョン 3.3 で変更: 1 次元のメモリビューがスライス可能になりました。 'B', 'b', 'c' いずれかのフォーマットの 1 次元のメモリビューが ハッシュ可能 になりました。

バージョン 3.4 で変更: memoryview は自動的に collections.abc.Sequence へ登録されるようになりました。

バージョン 3.5 で変更: メモリビューは整数のタプルでインデックス指定できるようになりました。

memoryview にはいくつかのメソッドがあります:

__eq__(exporter)

memoryview と PEP 3118 [https://peps.python.org/pep-3118/] エクスポーターは、 shape が同じで、 struct のフォーマットで解釈したときの値が同じ場合に同値になります。

tolist() がサポートしている struct フォーマットの一部では、 v.tolist() == w.tolist() が成り立つときに v == w になります:

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

どちらかの書式文字列が struct モジュールにサポートされていなければ、 (書式文字列とバッファの内容が同一でも) オブジェクトは常に等しくないものとして比較されます:

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

浮動小数点数の場合と同様 memoryview オブジェクトに対する v is w は v == w を意味しないことに注意してください。

バージョン 3.3 で変更: 以前のバージョンは、要素フォーマットと論理的な配列構造を無視して生のメモリを比較していました。

tobytes(order='C')

バッファ中のデータをバイト文字列として返します。これはメモリビューに対して bytes コンストラクタを呼び出すのと同等です。

>>> m = memoryview(b"abc")
>>> m.tobytes()
b'abc'
>>> bytes(m)
b'abc'

連続でない配列については、結果はすべての要素がバイトに変換されたものを含むフラットなリスト表現に等しくなります。 tobytes() は、 struct モジュール文法にないものを含むすべての書式文字列をサポートします。

Added in version 3.8: order は {'C', 'F', 'A'} のいずれかを取ることができます。 order が 'C' か 'F' の場合、元の配列は C または Fortran のデータ並びにそれぞれ変換されます。連続したデータに対するビューの場合、 'A' は物理メモリ上のデータの正確なコピーを返します。特に、メモリ上における Fortran のデータ並びは保存されます。不連続なデータに対するビューの場合、データはまず C のデータ並びに変換されます。 order=None は order='C' と同じです。

hex([sep[, bytes_per_sep]])

バッファ中の各バイトを 2 つの 16 進数で表した文字列を返します:

>>> m = memoryview(b"abc")
>>> m.hex()
'616263'

Added in version 3.5.

バージョン 3.8 で変更: bytes.hex() と同様に、 memoryview.hex() は、16進数出力のバイト文字列を分割するセパレータを挿入するためのオプションパラメータ sep と bytes_per_sep をサポートするようになりました。

tolist()

バッファ中のデータを要素のリストとして返します。

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

バージョン 3.3 で変更: tolist() が struct モジュール文法に含まれるすべての単一文字の native フォーマットと多次元の表現をサポートするようになりました。

toreadonly()

読み込み専用のメモリビューオブジェクトを返します。元のメモリビューオブジェクトは変更されません。

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

Added in version 3.8.

release()

memoryview オブジェクトによって晒されている、元になるバッファを解放します。多くのオブジェクトはビューに支配されているときに特殊なふるまいをします (例えば、 bytearray は大きさの変更を一時的に禁止します)。ですから、release() を呼び出すことは、これらの制約をできるだけ早く取り除く (そしてぶら下がったリソースをすべて解放する) のに便利です。

このメソッドが呼ばれた後、このビュー上のそれ以上の演算は ValueError を送出します (複数回呼ばれえる release() 自身は除きます):

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

コンテキストマネージャプロトコルは、 with 文を使って同様の効果を得るのに使えます:

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

Added in version 3.2.

cast(format[, shape])

memoryview を新しいフォーマットか shape にキャストします。 shape はデフォルトで [byte_length//new_itemsize] で、 1次元配列になります。戻り値は memoryview ですが、バッファー自体はコピーされません。サポートされている変換は 1次元配列 -> C言語型の連続配列 と C言語型の連続配列 -> 1次元配列 です（参考: contiguous）。

キャスト後のフォーマットは単一要素のネイティブフォーマットに限定され、 struct の文法で指定します。利用可能なフォーマットのひとつはバイトフォーマット ('B', 'b' または 'c') です。キャスト後のバイト長は元の長さと同じでなければなりません。全てのフォーマットのバイト長は、オペレーティングシステムに依存することに注意してください。

1次元 long から 1次元 unsigned byte へのキャスト:

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

1次元 unsigned byte から 1次元 char へのキャスト:

>>> 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')

1次元 byte から 3次元 int へ、そして 1次元 signed char へのキャスト:

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

1次元 unsigned long から 2次元 unsigned long へのキャスト:

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

Added in version 3.3.

バージョン 3.5 で変更: 単バイトのビューへキャストする場合、キャスト元のフォーマットについて制約は無くなりました。

読み出し専用の属性もいくつか使えます:

obj

memoryview が参照しているオブジェクト:

>>> b  = bytearray(b'xyz')
>>> m = memoryview(b)
>>> m.obj is b
True

Added in version 3.3.

nbytes

nbytes == product(shape) * itemsize == len(m.tobytes()). その配列が連続表現において利用するスペースです。これは len(m) と一致するとは限りません:

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

多次元配列:

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

Added in version 3.3.

readonly

メモリが読み出し専用かどうかを示す真偽値です。

format

ビューの中の各要素に対する (struct モジュールスタイルの) フォーマットを含む文字列。 memoryview は、任意のフォーマット文字列を使ってエクスポーターから作成することができます。しかし、いくつかのメソッド(例えば tolist()) はネイティブの単一要素フォーマットに制限されます。

バージョン 3.3 で変更: フォーマット 'B' は struct モジュール構文で扱われるようになりました。これは memoryview(b'abc')[0] == b'abc'[0] == 97 ということを意味します。

itemsize

memoryview の各要素のバイト単位の大きさ:

>>> import array, struct
>>> m = memoryview(array.array('H', [32000, 32001, 32002]))
>>> m.itemsize
2
>>> m[0]
32000
>>> struct.calcsize('H') == m.itemsize
True

ndim

メモリが表す多次元配列が何次元かを示す整数です。

shape

メモリが表している N 次元配列の形状を表す、長さ ndim の整数のタプルです。

バージョン 3.3 で変更: ndim = 0 の場合は None ではなく空のタプルとなるよう変更されました。

strides

配列のそれぞれの次元に対して、それぞれの要素にアクセスするのに必要なバイト数を表す、長さ ndim の整数のタプルです。

バージョン 3.3 で変更: ndim = 0 の場合は None ではなく空のタプルとなるよう変更されました。

suboffsets

PILスタイルの配列の内部で利用している値。この値はただの情報として公開されています。

c_contiguous

メモリーが C 形式の順序で連続しているかどうかを示す真偽値（参考: contiguous ）。

Added in version 3.3.

f_contiguous

メモリーがFortran形式の順序で連続しているかどうかを示す真偽値（参考: contiguous ）。

Added in version 3.3.

contiguous

メモリーが連続しているかどうかを示す真偽値（参考: contiguous ）。

Added in version 3.3.

set（集合）型 --- set, frozenset

set オブジェクトは、固有の hashable オブジェクトの順序なしコレクションです。通常の用途には、帰属テスト、シーケンスからの重複除去、積集合、和集合、差集合、対称差 (排他的論理和) のような数学的演算の計算が含まれます。(他のコンテナについては組み込みの dict, list, tuple クラスや collections モジュールを参照してください。)

集合は、他のコレクションと同様、 x in set, len(set), for x in set をサポートします。コレクションには順序がないので、集合は挿入の順序や要素の位置を記録しません。従って、集合はインデクシング、スライシング、その他のシーケンス的な振舞いをサポートしません。

set および frozenset という、2つの組み込みの集合型があります。 set はミュータブルで、add() や remove() のようなメソッドを使って内容を変更できます。ミュータブルなため、ハッシュ値を持たず、また辞書のキーや他の集合の要素として用いることができません。一方、frozenset 型はイミュータブルで、ハッシュ可能 です。作成後に内容を改変できないため、辞書のキーや他の集合の要素として用いることができます。

空でない set (frozenset ではない) は、set コンストラクタに加え、要素を波括弧中にカンマで区切って列挙することでも生成できます。例: {'jack', 'sjoerd'}。

どちらのクラスのコンストラクタも同様に働きます:

class set([iterable])

class frozenset([iterable])

iterable から要素を取り込んだ、新しい set もしくは frozenset オブジェクトを返します。 集合の要素は ハッシュ可能 なものでなくてはなりません。集合の集合を表現するためには、内側の集合は frozenset オブジェクトでなくてはなりません。iterable が指定されない場合、新しい空の集合が返されます。

集合はいくつかの方法で生成できます:

波括弧内にカンマ区切りで要素を列挙する: {'jack', 'sjoerd'}

集合内包表記を使う: {c for c in 'abracadabra' if c not in 'abc'}

型コンストラクタを使う: set(), set('foobar'), set(['a', 'b', 'foo'])

set および frozenset のインスタンスは以下の操作を提供します:

len(s)

集合 s の要素数 (s の濃度) を返します。

x in s

x が s のメンバーに含まれるか判定します。

x not in s

x が s のメンバーに含まれていないことを判定します。

isdisjoint(other)

集合が other と共通の要素を持たないとき、True を返します。集合はそれらの積集合が空集合となるときのみ、互いに素 (disjoint) となります。

issubset(other)

set <= other

set の全ての要素が other に含まれるか判定します。

set < other

set が other の真部分集合であるかを判定します。つまり、 set <= other and set != other と等価です。

issuperset(other)

set >= other

other の全ての要素が set に含まれるか判定します。

set > other

set が other の真上位集合であるかを判定します。つまり、 set >= other and set != other と等価です。

union(*others)

set | other | ...

set と全ての other の要素からなる新しい集合を返します。

intersection(*others)

set & other & ...

set と全ての other に共通する要素を持つ、新しい集合を返します。

difference(*others)

set - other - ...

set に含まれて、かつ、全ての other に含まれない要素を持つ、新しい集合を返します。

symmetric_difference(other)

set ^ other

set と other のいずれか一方だけに含まれる要素を持つ新しい集合を返します。

copy()

集合の浅いコピーを返します。

なお、演算子でない版の union(), intersection(), difference(), symmetric_difference(), issubset(), issuperset() メソッドは、任意のイテラブルを引数として受け付けます。対して、演算子を使う版では、引数は集合でなくてはなりません。これは、set('abc') & 'cbs' のような誤りがちな構文を予防し、より読みやすい set('abc').intersection('cbs') を支持します。

set と frozenset のどちらも、集合同士の比較をサポートします。二つの集合は、それぞれの集合の要素全てが他方にも含まれている (互いに他方の部分集合である) とき、かつそのときに限り等しいです。一方の集合が他方の集合の真部分集合である (部分集合であるが等しくない) とき、かつそのときに限り一方の集合は他方の集合より小さいです。一方の集合が他方の集合の真上位集合である (上位集合であるが等しくない) とき、かつそのときに限り一方の集合は他方の集合より大きいです。

set のインスタンスは、 frozenset のインスタンスと、要素に基づいて比較されます。例えば、 set('abc') == frozenset('abc') や set('abc') in set([frozenset('abc')]) は True を返します。

部分集合と等価性の比較は全順序付けを行う関数へと一般化することはできません。例えば、互いに素である二つの非空集合は、等しくなく、他方の部分集合でもありませんから、以下の すべて に False を返します: a<b, a==b, そして a>b.

集合は半順序（部分集合関係）しか定義しないので、集合のリストにおける list.sort() メソッドの出力は未定義です。

集合の要素は、辞書のキーのように、 ハッシュ可能 でなければなりません。

set インスタンスと frozenset インスタンスを取り混ぜての二項演算は、第一被演算子の型を返します。例えば: frozenset('ab') | set('bc') は frozenset インスタンスを返します。

以下の表に挙げる演算は set に適用されますが、frozenset のイミュータブルなインスタンスには適用されません:

update(*others)

set |= other | ...

全ての other の要素を追加し、 set を更新します。

intersection_update(*others)

set &= other & ...

元の set と全ての other に共通する要素だけを残して set を更新します。

difference_update(*others)

set -= other | ...

other に含まれる要素を取り除き、 set を更新します。

symmetric_difference_update(other)

set ^= other

どちらかにのみ含まれて、共通には持たない要素のみで set を更新します。

add(elem)

要素 elem を set に追加します。

remove(elem)

要素 elem を set から取り除きます。elem が set に含まれていなければ KeyError を送出します。

discard(elem)

要素 elem が set に含まれていれば、取り除きます。

pop()

s から任意の要素を取り除き、それを返します。集合が空の場合、 KeyError を送出します

clear()

set の全ての要素を取り除きます。

なお、演算子でない版の update(), intersection_update(), difference_update(), および symmetric_difference_update() メソッドは、任意のイテラブルを引数として受け付けます。

__contains__(), remove(), discard() メソッドの引数 elem は集合かもしれないことに注意してください。その集合と等価な frozenset の検索をサポートするために、 elem から一時的な frozenset を作成します。

マッピング型 --- dict

マッピング オブジェクトは、 ハッシュ可能 な値を任意のオブジェクトに対応付けます。マッピングはミュータブルなオブジェクトです。現在、標準のマッピング型は辞書 (dictionary) だけです。 (他のコンテナについては組み込みの list, set, および tuple クラスと、 collections モジュールを参照してください。)

辞書のキーには、*ほぼ*どんな値も使うことができます。キーとして使えないのは、 hashable (ハッシュ可能) でない値、すなわちリストや辞書のようなミュータブルな型 (内包する値ではなくオブジェクト自体が同一であるかによって比較が行われるような型)です。比較した際に等しいとみなされる値 (例えば 1 と 1.0 と True) は、どれを使っても同じエントリーに関連付けられます。

class dict(**kwargs)

class dict(mapping, **kwargs)

class dict(iterable, **kwargs)

オプションの位置引数と空の可能性もあるキーワード引数の集合により初期化された新しい辞書を返します。

辞書はいくつかの方法で生成できます:

波括弧内にカンマ区切りで key: value 対を列挙する: {'jack': 4098, 'sjoerd': 4127} あるいは {4098: 'jack', 4127: 'sjoerd'}

辞書内包表記を使う: {}, {x: x ** 2 for x in range(10)}

型コンストラクタを使う: dict(), dict([('foo', 100), ('bar', 200)]), dict(foo=100, bar=200)

位置引数が何も与えられなかった場合、空の辞書が作成されます。位置引数が与えられ、それがマッピングオブジェクトだった場合、そのマッピングオブジェクトと同じキーと値のペアを持つ辞書が作成されます。それ以外の場合、位置引数は iterable オブジェクトでなければなりません。iterable のそれぞれの要素自身は、ちょうど 2 個のオブジェクトを持つイテラブルでなければなりません。それぞれの要素の最初のオブジェクトは新しい辞書のキーになり、2 番目のオブジェクトはそれに対応する値になります。同一のキーが 2 回以上現れた場合は、そのキーの最後の値が新しい辞書での対応する値になります。

キーワード引数が与えられた場合、キーワード引数とその値が位置引数から作られた辞書に追加されます。既に存在しているキーが追加された場合、キーワード引数の値は位置引数の値を置き換えます。

例を出すと、次の例は全て {"one": 1, "two": 2, "three": 3} に等しい辞書を返します:

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

最初の例のようにキーワード引数を与える方法では、キーは有効な Python の識別子でなければなりません。それ以外の方法では、辞書のキーとして有効などんなキーでも使えます。

以下は辞書型がサポートする操作です (それゆえ、カスタムのマップ型もこれらの操作をサポートするべきです):

list(d)

辞書 d で使われている全てのキーのリストを返します。

len(d)

辞書 d の項目数を返します。

d[key]

d のキー key の項目を返します。マップに key が存在しなければ、 KeyError を送出します。

辞書のサブクラスが __missing__() メソッドを定義していて、 key が存在しない場合、 d[key] 演算はこのメソッドをキー key を引数として呼び出します。 d[key] 演算は、 __missing__(key) の呼び出しによって返された値をそのまま返すか、送出されたものをそのまま送出します。他の演算やメソッドは __missing__() を呼び出しません。 __missing__() が定義されていない場合、 KeyError が送出されます。 __missing__() はメソッドでなければならず、インスタンス変数であってはなりません:

>>> class Counter(dict):
...     def __missing__(self, key):
...         return 0
...
>>> c = Counter()
>>> c['red']
0
>>> c['red'] += 1
>>> c['red']
1

ここでお見せした例は collections.Counter 実装の一部です。これとは違った __missing__ が collections.defaultdict で使われています。

d[key] = value

d[key] に value を設定します。

del d[key]

d から d[key] を削除します。マップに key が存在しなければ、 KeyError を送出します。

key in d

d がキー key を持っていれば True を、そうでなければ、 False を返します。

key not in d

not key in d と等価です。

iter(d)

辞書のキーに渡るイテレータを返します。これは iter(d.keys()) へのショートカットです。

clear()

辞書の全ての項目を消去します。

copy()

辞書の浅いコピーを返します。

classmethod fromkeys(iterable[, value])

iterable からキーを取り、値を value に設定した、新しい辞書を作成します。

fromkeys() は新しい辞書を返すクラスメソッドです。 value はデフォルトで None となります。作られる辞書内のすべての値が同一のインスタンスを指すことになるため、value にミュータブルなオブジェクト (例えば空のリスト) を指定しても通常意味はありません。別々の値を指すようにしたい場合は、代わりに 辞書内包表記 を使用してください。

get(key[, default])

key が辞書にあれば key に対する値を、そうでなければ default を返します。 default が与えられなかった場合、デフォルトでは None となります。そのため、このメソッドは KeyError を送出することはありません。

items()

辞書の項目 ((key, value) 対) の新しいビューを返します。ビューオブジェクトのドキュメント を参照してください。

keys()

辞書のキーの新しいビューを返します。ビューオブジェクトのドキュメント を参照してください。

pop(key[, default])

key が辞書に存在すればその値を辞書から消去して返し、そうでなければ default を返します。 default が与えられず、かつ key が辞書に存在しなければ KeyError を送出します。

popitem()

任意の (key, value) 対を辞書から消去して返します。対は LIFO の順序で返却されます。

集合のアルゴリズムで使われるのと同じように、 popitem() は辞書に繰り返し適用して消去するのに便利です。辞書が空であれば、 popitem() の呼び出しは KeyError を送出します。

バージョン 3.7 で変更: LIFO 順序が保証されるようになりました。以前のバージョンでは、 popitem() は任意の key/value 対を返していました。

reversed(d)

辞書のキーに渡る逆イテレータを返します。これは reversed(d.keys()) へのショートカットです。

Added in version 3.8.

setdefault(key[, default])

もし、 key が辞書に存在すれば、その値を返します。そうでなければ、値を default として key を挿入し、 default を返します。 default のデフォルトは None です。

update([other])

辞書の内容を other のキーと値で更新します。既存のキーは上書きされます。返り値は None です。

update() は、他の辞書オブジェクトでもキー/値の対のイテラブル (タプル、もしくは、長さが2のイテラブル) でも、どちらでも受け付けます。キーワード引数が指定されれば、そのキー/値の対で辞書を更新します: d.update(red=1, blue=2)。

values()

辞書の値の新しいビューを返します。ビューオブジェクトのドキュメント を参照してください。

dict.values() で得られた２つのビューの等しさを比較すると、必ず False が返ります。 dict.values() どうしを比較したときも同様です:

>>> d = {'a': 1}
>>> d.values() == d.values()
False

d | other

d と other のキーと値を統合した新しい辞書を作成します。 d と other のキーに重複がある場合は、 other の方の値が優先されます。

Added in version 3.9.

d |= other

辞書 d のキーと値を other で更新します。 other は マッピング か、またはキーと値のペアの イテラブル です。 d と other のキーに重複がある場合は、 other の方の値が優先されます。

Added in version 3.9.

複数の辞書は、(順序に関係なく) 同じ (key, value) の対を持つ場合に、そしてその場合にのみ等しくなります。順序比較 ('<', '<=', '>=', '>') は TypeError を送出します。

辞書は挿入順序を保存するようになりました。キーの更新は順序には影響が無いことに注意してください。いったん削除されてから再度追加されたキーは末尾に挿入されます。:

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

バージョン 3.7 で変更: 辞書の順序が挿入順序であることが保証されるようになりました。この振る舞いは CPython 3.6 の実装詳細でした。

辞書と辞書のビューは reversed() で順序を逆にすることができます:

>>> 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)]

バージョン 3.8 で変更: 辞書がリバース可能になりました。

参考

dict の読み出し専用ビューを作るために types.MappingProxyType を使うことができます。

辞書ビューオブジェクト

dict.keys(), dict.values(), dict.items() によって返されるオブジェクトは、 ビューオブジェクト です。これらは、辞書の項目の動的なビューを提供し、辞書が変更された時、ビューはその変更を反映します。

辞書ビューは、イテレートすることで対応するデータを yield できます。また、帰属判定をサポートします:

len(dictview)

辞書の項目数を返します。

iter(dictview)

辞書のキー、値、または ((key, value) のタプルとして表される) 項目に渡るイテレータを返します。

キーと値は挿入順序で反復されます。これにより、 (value, key) の対の列を pairs = zip(d.values(), d.keys()) のように zip() で作成できます。同じリストを作成する他の方法は、 pairs = [(v, k) for (k, v) in d.items()] です。

辞書の項目の追加や削除中にビューをイテレートすると、 RuntimeError を送出したり、すべての項目に渡ってイテレートできなかったりします。

バージョン 3.7 で変更: 辞書の順序が挿入順序であると保証されるようになりました。

x in dictview

x が元の辞書のキー、値、または項目 (項目の場合、 x は (key, value) タプルです) にあるとき True を返します。

reversed(dictview)

辞書のキーもしくは値、項目の順序を逆にしたイテレーターを返します。戻り値のビューは、挿入された順とは逆の順でイテレートします。

バージョン 3.8 で変更: 辞書のビューがリバース可能になりました。

dictview.mapping

ビューの参照先の辞書をラップする types.MappingProxyType オブジェクト を返します。

Added in version 3.10.

キーのビューは要素に重複がなくハッシュ可能 (hashable) であるため、集合の特性を持ちます。項目のビューも、 キーと値の対に重複がなく、かつキーがハッシュ可能であるため、集合的な演算を持っています。もし項目の全ての値がハッシュ可能ならば、項目のビューは集合と相互に演算することが可能です。 (値のビューは一般に要素に重複があるため、集合の特性を持つとはみなされません。) 集合の特性を持つビューに対しては、 collections.abc.Set 抽象基底クラスで定義された全ての演算が利用可能です (たとえば ==, < や ^ など)。 集合演算に対しては、集合はオペランドとして集合しか取ることができないのに対して、これら集合の特性を持つビューはオペランドとして任意のイテラブルを取ることができます。

辞書ビューの使用法の例:

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

コンテキストマネージャ型

Python の with 文は、コンテキストマネージャによって定義される実行時コンテキストの概念をサポートします。これは、文の本体が実行される前に進入し文の終わりで脱出する実行時コンテキストを、ユーザ定義クラスが定義できるようにする一対のメソッドで実装されます:

contextmanager.__enter__()

実行時コンテキストに入り、このオブジェクトまたは他の実行時コンテキストに関連したオブジェクトを返します。このメソッドが返す値はこのコンテキストマネージャを使う with 文の as 節の識別子に束縛されます。

自分自身を返すコンテキストマネージャの例として ファイルオブジェクト があります。ファイルオブジェクトは __enter__() から自分自身を返し、 open() が with 文のコンテキスト式として使われるようにします。

関連オブジェクトを返すコンテキストマネージャの例としては decimal.localcontext() が返すものがあります。このマネージャはアクティブな10進数コンテキストをオリジナルのコンテキストのコピーにセットしてそのコピーを返します。こうすることで, with 文の本体の内部で、with 文の外側のコードに影響を与えずに、 10進数コンテキストを変更できます。

contextmanager.__exit__(exc_type, exc_val, exc_tb)

実行時コンテキストから抜け、(発生していた場合) 例外を抑制するかどうかを示すブール値フラグを返します。 with 文の本体の実行中に例外が発生した場合、引数にはその例外の型と値とトレースバック情報を渡します。そうでない場合、引数は全て None となります。

このメソッドから真値が返されると with 文は例外の発生を抑え、 with 文の直後の文に実行を続けます。そうでなければ、このメソッドの実行を終えると例外の伝播が続きます。このメソッドの実行中に起きた例外は with 文の本体の実行中に起こった例外を置き換えてしまいます。

渡された例外を明示的に再送出すべきではありません。その代わりに、このメソッドが偽の値を返すことでメソッドの正常終了と送出された例外を抑制しないことを伝えるべきです。このようにすればコンテキストマネージャは __exit__() メソッド自体が失敗したのかどうかを簡単に見分けることができます。

Python は、易しいスレッド同期、ファイルなどのオブジェクトの即時クローズ、アクティブな小数算術コンテキストの単純な操作をサポートするために、いくつかのコンテキストマネージャを用意しています。各型はコンテキスト管理プロトコルを実装しているという以上の特別の取り扱いを受けるわけではありません。例については contextlib モジュールを参照してください。

Python の ジェネレータ と contextlib.contextmanager デコレータ はこのプロトコルの簡便な実装方法を提供します。ジェネレータ関数を contextlib.contextmanager デコレータでデコレートすると、デコレートされないジェネレータ関数が作成するイテレータの代わりに、必要な __enter__() および __exit__() メソッドを実装したコンテキストマネージャを返すようになります。

これらのメソッドのために Python/C API の中の Python オブジェクトの型構造体に特別なスロットが作られたわけではないことに注意してください。これらのメソッドを定義したい拡張型はこれらを通常の Python からアクセスできるメソッドとして提供しなければなりません。実行時コンテキストを準備するオーバーヘッドに比べたら、一回のクラス辞書の探索のオーバーヘッドは無視できます。

型アノテーション型 --- ジェネリックエイリアス 、 ユニオン

型アノテーション の中心となる組み込みの型は ジェネリックエイリアス と ユニオン です。

ジェネリックエイリアス型

GenericAlias オブジェクトは一般的に、クラスに 添字表記 をすることで作られます。 list や dict のような コンテナ系のクラス に対して使われることがほとんどです。例えば、 list[int] は list クラスに int という引数を与えた添字表記をすることで作られる GenericAlias オブジェクトです。 GenericAlias オブジェクトは主に 型アノテーション の用途で使われます。

注釈

一般に、クラスへの添字表記は、そのクラスが特殊メソッド __class_getitem__() を実装しているときに限り可能です。

GenericAlias オブジェクトは パラメータ付きジェネリック型 を実装したジェネリック型 (generic type) の代用として振る舞います。

コンテナクラスに対してクラスの 添字表記 に与えられた単一または複数の引数は、そのオブジェクトが包含する要素の型をあらわします。たとえば set[bytes] という表記は、全ての要素が bytes であるような set をあらわす型アノテーションとして使うことができます。

__class_getitem__() メソッドを定義しているけれどもコンテナでないクラスに対しては、クラスの添字表記に与えられた単一または複数の引数は、しばしばオブジェクトに定義された単一または複数のメソッドの戻り値の型をあらわします。たとえば、 正規表現操作 は str と bytes の両方のデータ型に対して使うことができます:

x = re.search('foo', 'foo') とした場合、 x は re.Match オブジェクトとなり、 x.group(0) と x[0] の戻り値はどちらも str となります。このようなオブジェクトは、 GenericAlias を使った型アノテーション re.Match[str] で表現することができます。

y = re.search(b'bar', b'bar') (ここで b は bytes 型をあらわします) とした場合、y もまた re.Match のインスタンスとなりますが、 y.group(0) と y[0] の戻り値はどちらも bytes 型になります。型アノテーションでは、このような re.Match オブジェクトは re.Match[bytes] と表現することになるでしょう。

GenericAlias オブジェクトは types.GenericAlias クラスのインスタンスです。このクラスは直接 GenericAlias オブジェクトを生成するのに使うこともできます。

T[X, Y, ...]

型 "X", "Y", またはさらに多くの引数でパラメータ化される型 T を表現する GenericAlias を生成します。引数の数は T の使われ方によって決まります。たとえば、 float 型の要素を含む list を引数にとる関数の型アノテーションは次のようになります:

def average(values: list[float]) -> float:
    return sum(values) / len(values)

もうひとつの例として mapping オブジェクトの場合を示します。ここではキーと値の2つの型をパラメータとするジェネリック型である dict を使っています。この例では、関数はキーが str 型、値が int 型であるような dict を引数にとります:

def send_post_request(url: str, body: dict[str, int]) -> None:
    ...

組み込み関数 isinstance() と issubclass() は第二引数として GenericAlias 型を指定することはできません:

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

Python 実行時には 型アノテーション は強制されません。この性質はジェネリック型とその型パラメータにもおよびます。 GenericAlias からコンテナオブジェクトを生成した場合、コンテナ内の要素は型のチェックを受けません。たとえば、以下のコードは推奨されませんが、エラーになることなく実行できます:

>>> t = list[str]
>>> t([1, 2, 3])
[1, 2, 3]

しかも、パラメータ付きジェネリック型は、オブジェクト生成時にパラメータの型情報を削除します:

>>> t = list[str]
>>> type(t)
<class 'types.GenericAlias'>

>>> l = t()
>>> type(l)
<class 'list'>

repr() や str() のジェネリック型に対する呼び出しは、パラメータ型を表示します:

>>> repr(list[int])
'list[int]'

>>> str(list[int])
'list[int]'

ジェネリックコンテナ型の __getitem__() メソッドは、 dict[str][str] のようなミスを許さないように、例外を送出します:

>>> dict[str][str]
Traceback (most recent call last):
  ...
TypeError: dict[str] is not a generic class

一方で、同様の式は 型変数 が使われた場合は有効です。添字の数は``GenericAlias`` オブジェクトの __args__ 属性における型変数の数と同じでなければなりません:

>>> from typing import TypeVar
>>> Y = TypeVar('Y')
>>> dict[str, Y][int]
dict[str, int]

標準ジェネリッククラス

以下の標準ライブラリクラスは、パラメータ付きジェネリック型をサポートします。このリストは完全に網羅されていない可能性があります。

tuple

list

dict

set

frozenset

type

collections.deque

collections.defaultdict

collections.OrderedDict

collections.Counter

collections.ChainMap

’’collections.abc.Awaitable

collections.abc.Coroutine

collections.abc.AsyncIterable

collections.abc.AsyncIterator

collections.abc.AsyncGenerator

collections.abc.Iterable

collections.abc.Iterator

collections.abc.Generator

collections.abc.Reversible

collections.abc.Container

collections.abc.Collection

collections.abc.Callable

collections.abc.Set

collections.abc.MutableSet

collections.abc.Mapping

collections.abc.MutableMapping

collections.abc.Sequence

collections.abc.MutableSequence

collections.abc.ByteString

collections.abc.MappingView

collections.abc.KeysView

collections.abc.ItemsView

collections.abc.ValuesView

contextlib.AbstractContextManager

contextlib.AbstractAsyncContextManager

dataclasses.Field

functools.cached_property

functools.partialmethod

os.PathLike

queue.LifoQueue

queue.Queue

queue.PriorityQueue

queue.SimpleQueue

re.Pattern

re.Match

shelve.BsdDbShelf

shelve.DbfilenameShelf

shelve.Shelf

types.MappingProxyType

weakref.WeakKeyDictionary

weakref.WeakMethod

weakref.WeakSet

weakref.WeakValueDictionary

GenericAlias オブジェクトの特別な属性

全てのパラメータ付きジェネリック型は、下記に示す読み出し専用の属性を実装しています。

genericalias.__origin__

この属性は、対応するパラメータ付きでないジェネリッククラスを指します:

>>> list[int].__origin__
<class 'list'>

genericalias.__args__

この属性は、ジェネリッククラスの元の __class_getitem__() に渡された tuple です (長さが1の場合もあります):

>>> dict[str, list[int]].__args__
(<class 'str'>, list[int])

genericalias.__parameters__

この属性は、 __args__ にある固有の型変数のタプルで、必要に応じて遅延計算されます (空の可能性もあります):

>>> from typing import TypeVar

>>> T = TypeVar('T')
>>> list[T].__parameters__
(~T,)

注釈

typing.ParamSpec パラメータを含む GenericAlias オブジェクトは、代入後に正しい __parameters__ を持たない可能性があります。これは typing.ParamSpec が主に静的な型チェックを目的としているためです。

genericalias.__unpacked__

これは、型エイリアスが * 演算子を使って取り出された場合に真となる真偽値です (TypeVarTuple を参照してください)。

Added in version 3.11.

参考

PEP 484 [https://peps.python.org/pep-0484/] - 型ヒント

型アノテーションのための Python のフレームワークへの導入です。

PEP 585 [https://peps.python.org/pep-0585/] - 標準コレクション型の型ヒントにおける総称型 (generics) の使用

特殊なクラスメソッド __class_getitem__() を実装している場合に、標準ライブラリのクラスに対してネイティブにパラメータ表記を可能にする機能への導入です。

ジェネリクス, ユーザー定義のジェネリック型, および typing.Generic

実行時にパラメータ設定が可能であり、かつ静的な型チェッカーが理解できるジェネリッククラスを実装する方法のドキュメントです。

Added in version 3.9.

Union 型

Unionオブジェクトは、複数の type objects を | (bit演算のor)演算した値を保持します。この型は主に type annotations に使用します。Union型の式は typing.Union と比べて型ヒントの構文がわかりやすくなります。

X | Y | ...

X と Y などの型を保持するUnionオブジェクトを定義すします。X | Y はXとYのいずれかを意味します。これは typing.Union[X, Y] と等価です。たとえば、以下の関数は引数として int 型または float 型を想定しています。:

def square(number: int | float) -> int | float:
    return number ** 2

注釈

The | operand cannot be used at runtime to define unions where one or more members is a forward reference. For example, int | "Foo", where "Foo" is a reference to a class not yet defined, will fail at runtime. For unions which include forward references, present the whole expression as a string, e.g. "int | Foo".

union_object == other

Unionオブジェクトは他のUnionオブジェクトとの等価性をテストできます。以下は詳細です:

ユニオン型のユニオン型は平滑化されます:

(int | str) | float == int | str | float

余分な型は削除されます:

int | str | int == int | str

ユニオン型を比較すると順序は無視されます:

int | str == str | int

typing.Union と互換性があります:

int | str == typing.Union[int, str]

Optional型は None とのUnion型で記述できます:

str | None == typing.Optional[str]

isinstance(obj, union_object)

issubclass(obj, union_object)

isinstance() と issubclass() の呼び出しはどちらもUnionオブジェクトをサポートしています。

>>> isinstance("", int | str)
True

しかし、Unionオブジェクトの中の parameterized generics はチェックできません:

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

The user-exposed type for the union object can be accessed from types.UnionType and used for isinstance() checks. An object cannot be instantiated from the type:

>>> import types
>>> isinstance(int | str, types.UnionType)
True
>>> types.UnionType()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: cannot create 'types.UnionType' instances

注釈

X | Y 構文をサポートするために、型オブジェクトに:meth:!__or__ メソッドが追加されました。メタクラスで:meth:!__or__ を実装するとUnionをオーバーライドする場合があります:

>>> class M(type):
...     def __or__(self, other):
...         return "Hello"
...
>>> class C(metaclass=M):
...     pass
...
>>> C | int
'Hello'
>>> int | C
int | C

参考

PEP 604 [https://peps.python.org/pep-0604/] -- X | Y 構文とUnion型を提案しているPEP

Added in version 3.10.

その他の組み込み型

インタプリタは、その他いくつかの種類のオブジェクトをサポートしています。これらのほとんどは 1 つまたは 2 つの演算だけをサポートしています。

モジュール

モジュールに対する唯一の特殊な演算は属性アクセス: m.name です。ここで m はモジュールで、 name は m のシンボルテーブル上に定義された名前にアクセスします。モジュール属性に代入することもできます。 (なお、import 文は、厳密にいえば、モジュールオブジェクトに対する演算ではありません; import foo は foo と名づけられたモジュールオブジェクトの存在を必要とはせず、foo と名づけられたモジュールの (外部の) 定義 を必要とします。)

全てのモジュールにある特殊属性が __dict__ です。これはモジュールのシンボルテーブルを含む辞書です。この辞書を書き換えると実際にモジュールのシンボルテーブルを変更することができますが、__dict__ 属性を直接代入することはできません (m.__dict__['a'] = 1 と書いて m.a を 1 に定義することはできますが、m.__dict__ = {} と書くことはできません)。 __dict__ を直接書き換えることは推奨されません。

インタプリタ内に組み込まれたモジュールは、 <module 'sys' (built-in)> のように書かれます。ファイルから読み出された場合、 <module 'os' from '/usr/local/lib/pythonX.Y/os.pyc'> と書かれます。

クラスおよびクラスインスタンス

これらについては オブジェクト、値、および型 および クラス定義 を参照してください。

関数

関数オブジェクトは関数定義によって生成されます。関数オブジェクトに対する唯一の操作は、それを呼び出すことです: func(argument-list) 。

関数オブジェクトには実際には二種類あります: 組み込み関数とユーザ定義関数です。どちらも同じ操作 (関数の呼び出し) をサポートしますが、実装は異なるので、オブジェクトの型も異なります。

詳細は、 関数定義 を参照してください。

メソッド

メソッドは属性表記を使って呼び出される関数です。メソッドには二種類あります: (リストの append() のような) built-in methods と、class instance method です。組み込みメソッドは、それをサポートする型と一緒に記述されています。

インスタンスを通してメソッド (クラスの名前空間内で定義された関数) にアクセスすると、特殊なオブジェクトが得られます。それは束縛メソッド (bound method) オブジェクトで、インスタンスメソッド (instance method) とも呼ばれます。呼び出された時、引数リストに self 引数が追加されます。束縛メソッドには 2 つの特殊読み出し専用属性があります。 m.__self__ はそのメソッドが操作するオブジェクトで、m.__func__ はそのメソッドを実装している関数です。 m(arg-1, arg-2, ..., arg-n) の呼び出しは、 m.__func__(m.__self__, arg-1, arg-2, ..., arg-n) の呼び出しと完全に等価です。

function objects と同様に、メソッドオブジェクトは任意の属性の取得をサポートしています。しかし、メソッド属性は実際には下層の関数オブジェクト (method.__func__) に記憶されているので、バインドされるメソッドにメソッド属性を設定することは許されていません。メソッドに属性を設定しようとすると AttributeError が送出されます。メソッドの属性を設定するためには、次のようにその下層の関数オブジェクトに明示的に設定する必要があります:

>>> class C:
...     def method(self):
...         pass
...
>>> c = C()
>>> c.method.whoami = 'my name is method'  # can't set on the method
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: 'method' object has no attribute 'whoami'
>>> c.method.__func__.whoami = 'my name is method'
>>> c.method.whoami
'my name is method'

詳細は インスタンスメソッド を参照してください。

コードオブジェクト

コードオブジェクトは、関数本体のような "擬似コンパイルされた" Python の実行可能コードを表すために実装系によって使われます。コードオブジェクトはグローバルな実行環境への参照を持たない点で関数オブジェクトとは異なります。コードオブジェクトは組み込み関数 compile() によって返され、また関数オブジェクトの __code__ 属性として取り出せます。 code モジュールも参照してください。

__code__ へのアクセスは object.__getattr__ に obj と "__code__" を渡して行いますが、 監査イベント を送出します。

コードオブジェクトは、組み込み関数 exec() や eval() に (ソース文字列の代わりに) 渡すことで、実行や評価できます。

詳細は、 標準型の階層 を参照してください。

型オブジェクト

型オブジェクトは様々なオブジェクト型を表します。オブジェクトの型は組み込み関数 type() でアクセスされます。型オブジェクトには特有の操作はありません。標準モジュール types には全ての組み込み型名が定義されています。

型はこのように書き表されます: <class 'int'> 。

ヌルオブジェクト

このオブジェクトは明示的に値を返さない関数によって返されます。このオブジェクトには特有の操作はありません。ヌルオブジェクトは一つだけで、 None (組み込み名) と名づけられています。 type(None)() は同じシングルトンを作成します。

None と書き表されます。

Ellipsis オブジェクト

このオブジェクトは一般にスライシングによって使われます (スライス表記 (slicing) を参照してください)。特殊な演算は何もサポートしていません。Ellipsis オブジェクトは一つだけで、その名前は Ellipsis (組み込み名) です。type(Ellipsis)() は単一の Ellipsis を作成します。

Ellipsis または ... と書き表されます。

NotImplemented オブジェクト

このオブジェクトは、対応していない型に対して比較演算や二項演算が求められたとき、それらの演算から返されます。詳細は 比較 を参照してください。 NotImplemented オブジェクトは一つだけです。 type(NotImplemented)() はこの単一のインスタンスを作成します。

NotImplemented と書き表されます。

内部オブジェクト

この情報は 標準型の階層 を参照してください。stack frame objects、traceback objects、スライスオブジェクトについて記述されています。

特殊属性

実装は、いくつかのオブジェクト型に対して、適切な場合には特殊な読み出し専用の属性を追加します。そのうちいくつかは dir() 組込み関数で報告されません。

object.__dict__

オブジェクトの (書き込み可能な) 属性を保存するために使われる辞書またはその他のマッピングオブジェクトです。

instance.__class__

クラスインスタンスが属しているクラスです。

class.__bases__

クラスオブジェクトの基底クラスのタプルです。

definition.__name__

クラス、関数、メソッド、デスクリプタ、ジェネレータインスタンスの名前です。

definition.__qualname__

クラス、関数、メソッド、デスクリプタ、ジェネレータインスタンスの 修飾名 です。

Added in version 3.3.

definition.__type_params__

The type parameters of generic classes, functions, and type aliases.

Added in version 3.12.

class.__mro__

この属性はメソッドの解決時に基底クラスを探索するときに考慮されるクラスのタプルです。

class.mro()

このメソッドは、メタクラスによって、そのインスタンスのメソッド解決の順序をカスタマイズするために、上書きされるかも知れません。このメソッドはクラスのインスタンス化時に呼ばれ、その結果は __mro__ に格納されます。

class.__subclasses__()

それぞれのクラスは、それ自身の直接のサブクラスへの弱参照を保持します。このメソッドはそれらの参照のうち、生存しているもののリストを返します。リストは定義順です。例:

>>> int.__subclasses__()
[<class 'bool'>, <enum 'IntEnum'>, <flag 'IntFlag'>, <class 're._constants._NamedIntConstant'>]

整数と文字列の変換での長さ制限

CPythonはDoS(サービス妨害攻撃)を軽減するために int と str の間の変換に全体的な制限を設けました。この制限は10進数や2のべき乗以外の基数に のみ 適用されます。16進数、8進数と2進数は制限がありません。上限値は設定できます。

The 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 int('1' * 500_000) can take over a second on a fast CPU.

Limiting conversion size offers a practical way to avoid CVE-2020-10735 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=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.

演算の結果が制限を超えると、ValueError が送出されます:

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

デフォルトの上限値は4,300桁で、sys.int_info.default_max_str_digits で定義されています。設定可能な最小の上限値は 640 桁で、 sys.int_info.str_digits_check_threshold で定義されています。

確認:

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

Added in version 3.11.

影響のあるAPI

制限は int と str または bytes の間での変換で時間がかかる可能性があると適用されます:

int(string) でデフォルトの基数10。

int(string, base) で2のべき乗以外のすべての基数。

str(integer)

repr(integer)

他の10進数での文字列変換。たとえば f"{integer}"、"{}".format(integer) や b"%d" % integer。

制限は、線形アルゴリズムの関数では適用されません。

int(string, base) で基数が2、4、8、16または32。

int.from_bytes() と int.to_bytes() 。

hex(), oct(), bin().

書式指定ミニ言語仕様 での16進数、8進数、2進数での表現。

str から float。

str から decimal.Decimal。

上限値を設定する

Pythonを起動する前に環境変数またはインタープリタのコマンドラインのフラグで上限値を設定できます。

PYTHONINTMAXSTRDIGITS、たとえば PYTHONINTMAXSTRDIGITS=640 python3 は上限値を640に設定し、PYTHONINTMAXSTRDIGITS=0 python3 は制限を無効化します。

-X int_max_str_digits、たとえば python3 -X int_max_str_digits=640

sys.flags.int_max_str_digits contains the value of PYTHONINTMAXSTRDIGITS or -X int_max_str_digits. If both the env var and the -X option are set, the -X option takes precedence. A value of -1 indicates that both were unset, thus a value of sys.int_info.default_max_str_digits was used during initialization.

コードでは、以下の sys APIを使用して現在の上限値を調べ、新しい値を設定できます。

sys.get_int_max_str_digits() と sys.set_int_max_str_digits() はインタープリタ全体での上限値を取得、設定できます。サブインタープリタはそれぞれの上限値を持ちます。

デフォルト値と最小値に関する情報は sys.int_info で参照できます:

sys.int_info.default_max_str_digits はコンパイル時のデフォルト上限値です。

sys.int_info.str_digits_check_threshold is the lowest accepted value for the limit (other than 0 which disables it).

Added in version 3.11.

注意

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 .pyc does not already exist for the code. A workaround for source that contains such large constants is to convert them to 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 .py sources to .pyc files.

Recommended configuration

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

以下はプログラム例です:

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

If you need to disable it entirely, set it to 0.

脚注

[1]

これらの特殊なメソッドのさらなる情報については、 Python リファレンスマニュアル (基本的なカスタマイズ) を参照してください。

[2]

この結果として、リスト [1, 2] は [1.0, 2.0] と等しいと見なされます。タプルの場合も同様です。

[3]

パーザが演算対象の型を識別できるようにするために、このような優先順位でなければならないのです。

[4] (1,2,3,4)

大小文字の区別のある文字とは、一般カテゴリプロパティが "Lu" (Letter, uppercase (大文字))、 "Ll" (Letter, lowercase (小文字))、 "Lt" (Letter、titlecase (先頭が大文字)) のいずれかであるものです。

[5] (1,2)

従って、一個のタプルだけをフォーマット出力したい場合には出力したいタプルを唯一の要素とする単一のタプルを values に与えなくてはなりません。

組み込み例外

Python において、すべての例外は BaseException から派生したクラスのインスタンスでなければなりません。特定のクラスを言及する except 節を伴う try 文において、その節はそのクラスから派生した例外クラスも処理しますが、そのクラスの派生 元 の例外クラスは処理しません。サブクラス化の関係にない 2 つの例外クラスは、それらが同じ名前だった場合でも等しくなりえません。

この章で挙げる組み込み例外は、インタプリタや組み込み関数によって生成されます。特に注記しないかぎり、これらはエラーの詳しい原因を示す "関連値 (associated value)" を持ちます。この値は、複数の情報 (エラーコードや、そのコードを説明する文字列など) の文字列かタプルです。関連値は通常、例外クラスのコンストラクタに引数として渡されます。

ユーザによるコードも組み込み例外を送出できます。これを使って、例外ハンドラをテストしたり、インタプリタが同じ例外を送出する状況と "ちょうど同じような" エラー条件であることを報告したりできます。しかし、ユーザのコードが適切でないエラーを送出するのを妨げる方法はないので注意してください。

組み込み例外クラスは新たな例外を定義するためにサブクラス化することができます。新しい例外は、Exception クラスかそのサブクラスの一つから派生することをお勧めします。 BaseException からは派生しないで下さい。例外を定義する上での詳しい情報は、 Python チュートリアルの ユーザー定義例外 の項目にあります。

例外コンテキスト

例外オブジェクトの3つの属性は、例外が送出された常用に関する情報を提供します:

BaseException.__context__

BaseException.__cause__

BaseException.__suppress_context__

When raising a new exception while another exception is already being handled, the new exception's __context__ attribute is automatically set to the handled exception. An exception may be handled when an except or finally clause, or a with statement, is used.

This implicit exception context can be supplemented with an explicit cause by using from with raise:

raise new_exc from original_exc

from に続く式は例外か None でなくてはなりません。式は送出される例外の __cause__ として設定されます。 __cause__ を設定することは、 __suppress_context__ 属性を暗黙的に True に設定することにもなるので、 raise new_exc from None を使うことで効率的に古い例外を新しいもので置き換えて表示する (例えば、 KeyError を AttributeError に置き換え)、古い例外はデバッグ時の調査で使えるよう __context__ に残すことができます。

デフォルトの traceback 表示コードは、例外自体の traceback に加え、これらの連鎖された例外を表示します。__cause__ で明示的に連鎖させた例外は、存在するならば常に表示されます。__context__ で暗黙に連鎖させた例外は、__cause__ が None かつ __suppress_context__ が false の場合にのみ表示されます。

いずれにせよ、連鎖された例外に続いて、その例外自体は常に表示されます。そのため、traceback の最終行には、常に送出された最後の例外が表示されます。

組み込み例外から継承する

User code can create subclasses that inherit from an exception type. It's recommended to only subclass one exception type at a time to avoid any possible conflicts between how the bases handle the args attribute, as well as due to possible memory layout incompatibilities.

CPython 実装の詳細: Most built-in exceptions are implemented in C for efficiency, see: Objects/exceptions.c [https://github.com/python/cpython/tree/3.12/Objects/exceptions.c]. Some have custom memory layouts which makes it impossible to create a subclass that inherits from multiple exception types. The memory layout of a type is an implementation detail and might change between Python versions, leading to new conflicts in the future. Therefore, it's recommended to avoid subclassing multiple exception types altogether.

基底クラス

以下の例外は、主に他の例外の基底クラスとして使われます。

exception BaseException

全ての組み込み例外の基底クラスです。ユーザ定義の例外に直接継承されることは意図されていません (継承には Exception を使ってください)。このクラスのインスタンスに str() が呼ばれた場合、インスタンスへの引数の表現か、引数が無い場合には空文字列が返されます。

args

例外コンストラクタに与えられた引数のタプルです。組み込み例外は普通、エラーメッセージを与える一つの文字列だけを引数として呼ばれますが、中には (OSError など) いくつかの引数を必要とし、このタプルの要素に特別な意味を込めるものもあります。

with_traceback(tb)

This method sets tb as the new traceback for the exception and returns the exception object. It was more commonly used before the exception chaining features of PEP 3134 [https://peps.python.org/pep-3134/] became available. The following example shows how we can convert an instance of SomeException into an instance of OtherException while preserving the traceback. Once raised, the current frame is pushed onto the traceback of the OtherException, as would have happened to the traceback of the original SomeException had we allowed it to propagate to the caller.

try:
    ...
except SomeException:
    tb = sys.exception().__traceback__
    raise OtherException(...).with_traceback(tb)

__traceback__

A writable field that holds the traceback object associated with this exception. See also: raise 文.

add_note(note)

例外のノートとして文字列 note を追加します。ノートは標準のトレースバックで例外文字列の後に表示されます。note が文字列以外の場合 TypeError が送出されます。

Added in version 3.11.

__notes__

add_note() で追加された例外のノートのリスト。この属性は add_note() を呼び出すと生成されます。

Added in version 3.11.

exception Exception

システム終了以外の全ての組み込み例外はこのクラスから派生しています。全てのユーザ定義例外もこのクラスから派生させるべきです。

exception ArithmeticError

算術上の様々なエラーに対して送出される組み込み例外 OverflowError, ZeroDivisionError, FloatingPointError の基底クラスです。

exception BufferError

バッファ に関連する操作が行えなかったときに送出されます。

exception LookupError

マッピングまたはシーケンスで使われたキーやインデクスが無効な場合に送出される例外 IndexError および KeyError の基底クラスです。 codecs.lookup() によって直接送出されることもあります。

具象例外

以下の例外は、通常送出される例外です。

exception AssertionError

assert 文が失敗した場合に送出されます。

exception AttributeError

属性参照 (属性参照 を参照) や代入が失敗した場合に送出されます (オブジェクトが属性の参照や属性の代入をまったくサポートしていない場合には TypeError が送出されます)。

コンストラクタのキーワード専用引数を使って name および obj 属性を設定できます。設定された場合、アクセスが試みられた属性の名前と、その属性にアクセスしたオブジェクトを、それぞれ表します。

バージョン 3.10 で変更: name および obj 属性が追加されました。

exception EOFError

input() が何もデータを読まずに end-of-file (EOF) に達した場合に送出されます。(注意: io.IOBase.read() と io.IOBase.readline() メソッドは、EOF に達すると空文字列を返します。)

exception FloatingPointError

現在は使われていません。

exception GeneratorExit

ジェネレータ や コルーチン が閉じられたときに送出されます。 generator.close() と coroutine.close() を参照してください。この例外は厳密に言えばエラーではないので、 Exception ではなく BaseException を直接継承しています。

exception ImportError

import 文でモジュールをロードしようとして問題が発生すると送出されます。 from ... import の中の"from list" (訳注：... の部分)の名前が見つからないときにも送出されます。

オブションのキーワード専用引数 name と path は、対応する属性に設定されます:

name

インポートを試みたモジュールの名前。

path

例外を引き起こしたファイルのパス。

バージョン 3.3 で変更: name および path 属性が追加されました。

exception ModuleNotFoundError

ImportError のサブクラスで、import 文でモジュールが見つからない場合に送出されます。また、 sys.modules に None が含まれる場合にも送出されます。

Added in version 3.6.

exception IndexError

シーケンスの添字が範囲外の場合に送出されます。 (スライスのインデクスはシーケンスの範囲に収まるように暗黙のうちに調整されます; インデクスが整数でない場合、 TypeError が送出されます。)

exception KeyError

マッピング (辞書) のキーが、既存のキーの集合内に見つからなかった場合に送出されます。

exception KeyboardInterrupt

ユーザが割り込みキー (通常は Control-C または Delete) を押した場合に送出されます。実行中、割り込みは定期的に監視されます。Exception を捕捉するコードに誤って捕捉されてインタプリタの終了が阻害されないように、この例外は BaseException を継承しています。

注釈

Catching a KeyboardInterrupt requires special consideration. Because it can be raised at unpredictable points, it may, in some circumstances, leave the running program in an inconsistent state. It is generally best to allow KeyboardInterrupt to end the program as quickly as possible or avoid raising it entirely. (See Note on Signal Handlers and Exceptions.)

exception MemoryError

ある操作中にメモリが不足したが、その状況は (オブジェクトをいくつか消去することで) まだ復旧可能かもしれない場合に送出されます。この例外の関連値は、メモリ不足になった (内部) 操作の種類を示す文字列です。下層のメモリ管理アーキテクチャ (C の malloc() 関数) のために、インタプリタが現状から完璧に復旧できるとはかぎらないので注意してください。それでも、プログラムの暴走が原因の場合に備えて実行スタックのトレースバックを出力できるように、例外が送出されます。

exception NameError

ローカルまたはグローバルの名前が見つからなかった場合に送出されます。これは非修飾の (訳注: spam.egg ではなく単に egg のような) 名前のみに適用されます。関連値は見つからなかった名前を含むエラーメッセージです。

コンストラクタのキーワード専用引数を使って name 属性を設定できます。設定された場合、アクセスが試みられた変数の名前を表します。

バージョン 3.10 で変更: name 属性が追加されました。

exception NotImplementedError

この例外は RuntimeError から派生しています。ユーザ定義の基底クラスにおいて、抽象メソッドが派生クラスでオーバライドされることを要求する場合にこの例外を送出しなくてはなりません。またはクラスは実装中であり本来の実装を追加する必要があることを示します。

注釈

演算子やメソッドがサポートされていないことを示す目的でこの例外を使用するべきではありません。そのようなケースではオペレータやメソッドを未定義のままとするか、サブクラスの場合は None を設定してください。

注釈

NotImplementedError と NotImplemented は、似たような名前と目的を持っていますが、相互に変換できません。 利用する際には、NotImplemented を参照してください。

exception OSError([arg])

exception OSError(errno, strerror[, filename[, winerror[, filename2]]])

この例外はシステム関数がシステム関連のエラーを返した場合に送出されます。例えば "file not found" や "disk full" のような I/O の失敗が発生したときです (引数の型が不正な場合や、他の偶発的なエラーは除きます)。

コンストラクタの2番目の形式は下記の対応する属性を設定します。指定されなかった場合属性はデフォルトで None です。後方互換性のために、引数が3つ渡された場合、args 属性は最初の2つの要素のみからなるタプルを持ちます。

コンストラクタは実際には、 OS exceptions で述べられている OSError のサブクラスを返すことがよくあります。特定のサブクラスは最終的な errno 値によります。この挙動は OSError を直接またはエイリアスで構築し、サブクラス化時に継承されなかった場合にのみ発生します。

errno

C 変数 errno に由来する数値エラーコードです。

winerror

Windows において、ネイティブ Windows エラーコードを与えます。そして errno 属性は POSIX でいうネイティブエラーコードへのおよその翻訳です。

Windows では、winerror コンストラクタ引数が整数の場合 errno 属性は Windows エラーコードから決定され、errno 引数は無視されます。他のプラットフォームでは winerror 引数は無視され、 winerror 属性は存在しません。

strerror

OS が提供するような、対応するエラーメッセージです。 POSIX では perror() で、Windows では FormatMessage() で体裁化されます。

filename

filename2

ファイルシステムパスが1つ関与する例外 (例えば open() や os.unlink()) の場合、filename は関数に渡されたファイル名です。ファイルシステムパスが2つ関与する関数 (例えば os.rename()) の場合、filename2 は関数に渡された2つ目のファイル名です。

バージョン 3.3 で変更: EnvironmentError, IOError, WindowsError, socket.error, select.error, mmap.error が OSError に統合されました。コンストラクタはサブクラスを返すかもしれません。

バージョン 3.4 で変更: filename 属性が filesystem encoding and error handler のエンコーディングでエンコードやデコードされた名前から、関数に渡された元々のファイル名になりました。また、filename2 コンストラクタ引数が追加されました。

exception OverflowError

算術演算の結果が表現できない大きな値になった場合に送出されます。これは整数では起こりません (むしろ MemoryError が送出されることになるでしょう)。しかし、歴史的な理由のため、要求された範囲の外の整数に対して OverflowError が送出されることがあります。C の浮動小数点演算の例外処理は標準化されていないので、ほとんどの浮動小数点演算もチェックされません。

exception RecursionError

この例外は RuntimeError を継承しています。インタープリタが最大再帰深度 (sys.getrecursionlimit() を参照) の超過を検出すると送出されます。

Added in version 3.5: 以前は RuntimeError をそのまま送出していました。

exception ReferenceError

weakref.proxy() によって生成された弱参照 (weak reference) プロキシを使って、ガーベジコレクションによって回収された後の参照対象オブジェクトの属性にアクセスした場合に送出されます。弱参照については weakref モジュールを参照してください。

exception RuntimeError

他のカテゴリに分類できないエラーが検出された場合に送出されます。関連値は、何が問題だったのかをより詳細に示す文字列です。

exception StopIteration

組込み関数 next() と iterator の __next__() メソッドによって、そのイテレータが生成するアイテムがこれ以上ないことを伝えるために送出されます。

value

この例外オブジェクトには一つの属性 value があり、例外を構成する際に引数として与えられ、デフォルトは None です。

generator や coroutine 関数が返るとき、新しい StopIteration インスタンスが送出されます。関数の返り値は例外のコンストラクタの value 引数として使われます。

ジェネレータのコードが直接的あるいは間接的に StopIteration を送出する場合は、 RuntimeError に変換されます (StopIteration は変換後の例外の原因として保持されます)。

バージョン 3.3 で変更: value 属性とジェネレータ関数が値を返すためにそれを使う機能が追加されました。

バージョン 3.5 で変更: from __future__ import generator_stop による RuntimeError への変換が導入されました。 PEP 479 [https://peps.python.org/pep-0479/] を参照してください。

バージョン 3.7 で変更: PEP 479 [https://peps.python.org/pep-0479/] が全てのコードでデフォルトで有効化されました: ジェネレータから送出された StopIteration は RuntimeError に変換されます。

exception StopAsyncIteration

イテレーションを停止するために、 asynchronous iterator オブジェクトの __anext__() メソッドによって返される必要があります。

Added in version 3.5.

exception SyntaxError(message, details)

パーザが構文エラーに遭遇した場合に送出されます。この例外は import 文、組み込み関数 compile()、exec() や eval() 、初期化スクリプトの読み込みや標準入力で (対話的な実行時にも) 起こる可能性があります。

例外インスタンスの str() はエラーメッセージのみを返します。詳細はタプルで、個々の属性としても利用できます。

filename

構文エラーが発生したファイルの名前。

lineno

ファイルのエラーが発生した行番号。1から数えはじめるため、ファイルの最初の行の lineno は1です。

offset

行のエラーが発生した列番号。1から数えはじめるため、行の最初の文字の offset は1です。

text

エラーを含むソースコードのテキスト。

end_lineno

ファイルのエラーが発生した最後の行番号。1から数えはじめるため、ファイルの最初の行の lineno は1です。

end_offset

行のエラーが発生した最後の列番号。1から数えはじめるため、行の最初の文字の offset は1です。

For errors in f-string fields, the message is prefixed by "f-string: " and the offsets are offsets in a text constructed from the replacement expression. For example, compiling f'Bad {a b} field' results in this args attribute: ('f-string: ...', ('', 1, 2, '(a b)n', 1, 5)).

バージョン 3.10 で変更: end_lineno および end_offset 属性が追加されました。

exception IndentationError

正しくないインデントに関する構文エラーの基底クラスです。これは SyntaxError のサブクラスです。

exception TabError

タブとスペースを一貫しない方法でインデントに使っているときに送出されます。これは IndentationError のサブクラスです。

exception SystemError

インタプリタが内部エラーを発見したが、状況は全ての望みを棄てさせるほど深刻ではないと思われる場合に送出されます。関連値は (下位層で) どの動作が失敗したかを示す文字列です。

使用中の Python インタプリタの作者または保守担当者にこのエラーを報告してください。このとき、Python インタプリタのバージョン (sys.version 。Python の対話的セッションを開始した際にも出力されます)、正確なエラーメッセージ (例外の関連値) を忘れずに報告してください。可能な場合にはエラーを引き起こしたプログラムのソースコードも報告してください。

exception SystemExit

この例外は sys.exit() 関数から送出されます。Exception をキャッチするコードに誤ってキャッチされないように、Exception ではなく BaseException を継承しています。これにより例外は上の階層に適切に伝わり、インタープリタを終了させます。この例外が処理されなかった場合はスタックのトレースバックを表示せずに Python インタープリタは終了します。コンストラクタは sys.exit() に渡されるオプション引数と同じものを受け取ります。値が整数の場合、システムの終了ステータス (C 言語の exit() 関数に渡すもの)を指定します。値が None の場合、終了ステータスは 0 です。それ以外の型の場合 (例えば str)、 オブジェクトの値が表示され、終了ステータスは 1 です。

sys.exit() は、クリーンアップのための処理 (try 文の finally 節) が実行されるようにするため、またデバッガが制御不能になるリスクを冒さずにスクリプトを実行できるようにするために例外に変換されます。即座に終了することが真に強く必要であるとき (例えば、os.fork() を呼んだ後の子プロセス内) には os._exit() 関数を使うことができます。

code

コンストラクタに渡された終了ステータス又はエラーメッセージ。(デフォルトは None)

exception TypeError

組み込み演算または関数が適切でない型のオブジェクトに対して適用された際に送出されます。関連値は型の不整合に関して詳細を述べた文字列です。

この例外は、そのオブジェクトで実行しようとした操作がサポートされておらず、その予定もない場合にユーザーコードから送出されるかもしれません。オブジェクトでその操作をサポートするつもりだが、まだ実装を提供していないのであれば、送出する適切な例外は NotImplementedError です。

誤った型の引数が渡された場合は (例えば、int が期待されるのに、list が渡された) TypeError となるべきです。しかし、誤った値(例えば、期待する範囲外の数)が引数として渡された場合は、 ValueError となるべきです。

exception UnboundLocalError

関数やメソッド内のローカルな変数に対して参照を行ったが、その変数には値が代入されていなかった場合に送出されます。 NameError のサブクラスです。

exception UnicodeError

Unicode に関するエンコードまたはデコードのエラーが発生した際に送出されます。 ValueError のサブクラスです。

UnicodeError はエンコードまたはデコードのエラーの説明を属性として持っています。例えば、 err.object[err.start:err.end] は、無効な入力のうちコーデックが処理に失敗した箇所を表します。

encoding

エラーを送出したエンコーディングの名前です。

reason

そのコーデックエラーを説明する文字列です。

object

コーデックがエンコードまたはデコードしようとしたオブジェクトです。

start

object の最初の無効なデータのインデクスです。

end

object の最後の無効なデータの次のインデクスです。

exception UnicodeEncodeError

Unicode 関連のエラーがエンコード中に発生した際に送出されます。 UnicodeError のサブクラスです。

exception UnicodeDecodeError

Unicode 関連のエラーがデコード中に発生した際に送出されます。 UnicodeError のサブクラスです。

exception UnicodeTranslateError

Unicode 関連のエラーが変換中に発生した際に送出されます。 UnicodeError のサブクラスです。

exception ValueError

演算子や関数が、正しい型だが適切でない値を持つ引数を受け取ったときや、 IndexError のようなより詳細な例外では記述できない状況で送出されます。

exception ZeroDivisionError

除算や剰余演算の第二引数が 0 であった場合に送出されます。関連値は文字列で、その演算における被演算子と演算子の型を示します。

以下の例外は、過去のバージョンとの後方互換性のために残されています; Python 3.3 より、これらは OSError のエイリアスです。

exception EnvironmentError

exception IOError

exception WindowsError

Windows でのみ利用できます。

OS 例外

以下の例外は OSError のサブクラスで、システムエラーコードに依存して送出されます。

exception BlockingIOError

ある操作が、ノンブロッキング操作に設定されたオブジェクト (例えばソケット) をブロックしそうになった場合に送出されます。errno EAGAIN, EALREADY, EWOULDBLOCK および EINPROGRESS に対応します。

BlockingIOError は、 OSError の属性に加えて一つの属性を持ちます:

characters_written

ストリームがブロックされるまでに書き込まれた文字数を含む整数です。この属性は io からのバッファ I/O クラスを使っているときに利用できます。

exception ChildProcessError

子プロセスの操作が失敗した場合に送出されます。errno ECHILD に対応します。

exception ConnectionError

コネクション関係の問題の基底クラス。

サブクラスは BrokenPipeError, ConnectionAbortedError, ConnectionRefusedError, ConnectionResetError です。

exception BrokenPipeError

ConnectionError のサブクラスで、もう一方の端が閉じられたパイプに書き込こもうとするか、書き込みのためにシャットダウンされたソケットに書き込こもうとした場合に発生します。 errno EPIPE と ESHUTDOWN に対応します。

exception ConnectionAbortedError

ConnectionError のサブクラスで、接続の試行が通信相手によって中断された場合に発生します。 errno ECONNABORTED に対応します。

exception ConnectionRefusedError

ConnectionError のサブクラスで、接続の試行が通信相手によって拒否された場合に発生します。 errno ECONNREFUSED に対応します。

exception ConnectionResetError

ConnectionError のサブクラスで、接続が通信相手によってリセットされた場合に発生します。 errno ECONNRESET に対応します。

exception FileExistsError

すでに存在するファイルやディレクトリを作成しようとした場合に送出されます。errno EEXIST に対応します。

exception FileNotFoundError

要求されたファイルやディレクトリが存在しない場合に送出されます。errno ENOENT に対応します。

exception InterruptedError

システムコールが入力信号によって中断された場合に送出されます。errno EINTR に対応します。

バージョン 3.5 で変更: シグナルハンドラが例外を送出せず、システムコールが信号で中断された場合 Python は InterruptedError を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 [https://peps.python.org/pep-0475/] を参照してください) 。

exception IsADirectoryError

ディレクトリに (os.remove() などの) ファイル操作が要求された場合に送出されます。errno EISDIR に対応します。

exception NotADirectoryError

ディレクトリへの操作(たとえば os.listdir())をディレクトリ以外に対して要求された場合に送出されます。多くのPOSIXプラットフォームではディレクトリではないファイルをディレクトリとして開いたり移動するときにも発生する場合があります。errno ENOTDIR に対応します。

exception PermissionError

十分なアクセス権、例えばファイルシステム権限のない操作が試みられた場合に送出されます。errno EACCES、EPERM および ENOTCAPABLE に対応します。

バージョン 3.11.1 で変更: WASIの ENOTCAPABLE は PermissionError にマップされました。

exception ProcessLookupError

与えられたプロセスが存在しない場合に送出されます。errno ESRCH に対応します。

exception TimeoutError

システム関数がシステムレベルでタイムアウトした場合に送出されます。errno ETIMEDOUT に対応します。

Added in version 3.3: 上記のすべての OSError サブクラスが追加されました。

参考

PEP 3151 [https://peps.python.org/pep-3151/] - OS および IO 例外階層の手直し

警告

次の例外は警告カテゴリとして使われます。詳細については 警告カテゴリ のドキュメントを参照してください。

exception Warning

警告カテゴリの基底クラスです。

exception UserWarning

ユーザコードによって生成される警告の基底クラスです。

exception DeprecationWarning

他の Python 開発者へ向けて警告を発するときの、廃止予定の機能についての警告の基底クラスです。

Ignored by the default warning filters, except in the __main__ module (PEP 565 [https://peps.python.org/pep-0565/]). Enabling the Python Development Mode shows this warning.

The deprecation policy is described in PEP 387 [https://peps.python.org/pep-0387/].

exception PendingDeprecationWarning

古くなって将来的に廃止される予定だが、今のところは廃止されていない機能についての警告の基底クラスです。

近々起こる可能性のある機能廃止について警告を発することはまれなので、このクラスはめったに使われず、既に決まっている廃止については DeprecationWarning が望ましいです。

デフォルトの警告フィルターで無効化されています。Python Development Mode を有効にするとこの警告が表示されます。

The deprecation policy is described in PEP 387 [https://peps.python.org/pep-0387/].

exception SyntaxWarning

曖昧な構文に対する警告の基底クラスです。

exception RuntimeWarning

あいまいなランタイム挙動に対する警告の基底クラスです。

exception FutureWarning

Python で書かれたアプリケーションのエンドユーザーへ向けて警告を発するときの、廃止予定の機能についての警告の基底クラスです。

exception ImportWarning

モジュールインポートの誤りと思われるものに対する警告の基底クラスです。

デフォルトの警告フィルターで無効化されています。Python Development Mode を有効にするとこの警告が表示されます。

exception UnicodeWarning

Unicode に関連した警告の基底クラスです。

exception EncodingWarning

エンコーディングに関連した警告の基底クラスです。

詳細は Opt-in EncodingWarning を参照してください。

Added in version 3.10.

exception BytesWarning

bytes や bytearray に関連した警告の基底クラスです。

exception ResourceWarning

リソースの使用に関連した警告の基底クラスです。

デフォルトの警告フィルターで無効化されています。Python Development Mode を有効にするとこの警告が表示されます。

Added in version 3.2.

例外グループ

以下は関係がない複数の例外を送出する必要があるときに使用します。例外グループは例外の階層構造の一部のため、他の例外と同様 except で処理できます。また、except* によって判別でき、例外グループに含まれている例外の型に基づいてサブグループにマッチします。

exception ExceptionGroup(msg, excs)

exception BaseExceptionGroup(msg, excs)

この2つの例外型は一連の例外 excs を包含します。msg 引数は文字列の必要があります。2つのクラスの異なる点は、BaseException は BaseExceptionGroup を拡張して任意の例外を含められますが、ExceptionGroup は Exception を拡張して Exception のサブクラスのみを含められます。この設計により except Exception は ExceptionGroup をキャッチしますが、BaseExceptionGroup はキャッチしません。

BaseExceptionGroup のコンストラクターは含まれる例外がすべて Exception の場合は BaseExceptionGroup ではなく ExceptionGroup を返すように自動的に選択されます。一方 ExceptionGroup コンストラクタは、Exception サブクラス以外の例外を含む場合は TypeError を送出します。

message

コンストラクタの msg 引数。この属性は読み込み専用です。

exceptions

コンストラクタに渡された一連の excs に含まれる例外のタプルです。この属性は読み込み専用です。

subgroup(condition)

現在のグループで 条件 にマッチする礼儀のみを含む例外グループを返します。結果が空の場合は None を返します。

The condition can be either a function that accepts an exception and returns true for those that should be in the subgroup, or it can be an exception type or a tuple of exception types, which is used to check for a match using the same check that is used in an except clause.

The nesting structure of the current exception is preserved in the result, as are the values of its message, __traceback__, __cause__, __context__ and __notes__ fields. Empty nested groups are omitted from the result.

The condition is checked for all exceptions in the nested exception group, including the top-level and any nested exception groups. If the condition is true for such an exception group, it is included in the result in full.

split(condition)

subgroup() と似てますが (match, rest) のペアを返します。match は subgroup(condition) で rest は残りのマッチしない部分です。

derive(excs)

同じ message の例外グループを返しますが、excs の例外を含んでいます。

This method is used by subgroup() and split(). A subclass needs to override it in order to make subgroup() and split() return instances of the subclass rather than ExceptionGroup.

subgroup() と split() は __traceback__、__cause__、__context__ と __notes__ フィールドを元の例外グループから derive() が返す例外グループにコピーするため、derive() ではこれらのフィールドを更新する必要がありません。

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

Note that BaseExceptionGroup defines __new__(), so subclasses that need a different constructor signature need to override that rather than __init__(). For example, the following defines an exception group subclass which accepts an exit_code and and constructs the group's message from it.

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)

Like ExceptionGroup, any subclass of BaseExceptionGroup which is also a subclass of Exception can only wrap instances of Exception.

Added in version 3.11.

例外のクラス階層

組み込み例外のクラス階層は以下のとおりです:

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
      │    └── 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

テキスト処理サービス

この章で説明するモジュールは幅広い文字列操作や様々なテキスト処理サービスを提供しています。

codecs モジュールはテキスト処理と高い関連性を持った バイナリデータ処理 のなかで説明されています。加えて Python の組み込み文字列型の テキストシーケンス型 --- str のドキュメントも参照して下さい。

string --- Common string operations

文字列定数

カスタムの文字列書式化

書式指定文字列の文法

書式指定ミニ言語仕様

書式指定例

テンプレート文字列

ヘルパー関数

re --- Regular expression operations

正規表現のシンタックス

モジュールコンテンツ

フラグ

関数

例外

正規表現オブジェクト

マッチオブジェクト

正規表現の例

ペアの確認

scanf() をシミュレートする

search() vs. match()

電話帳を作る

テキストの秘匿

全ての副詞を見つける

全ての副詞とその位置を見つける

Raw 文字列記法

トークナイザを書く

difflib --- Helpers for computing deltas

SequenceMatcherオブジェクト

SequenceMatcher の例

Differ オブジェクト

Differ の例

difflib のコマンドラインインターフェース

ndiff example

textwrap --- Text wrapping and filling

unicodedata --- Unicode Database

stringprep --- Internet String Preparation

readline --- GNU readline interface

初期化ファイル

行バッファ

履歴ファイル

履歴リスト

開始フック

補完

使用例

rlcompleter --- Completion function for GNU readline

string --- Common string operations

ソースコード: Lib/string.py [https://github.com/python/cpython/tree/3.12/Lib/string.py]

参考

テキストシーケンス型 --- str

文字列メソッド

文字列定数

このモジュールで定義されている定数は以下の通りです:

string.ascii_letters

後述の ascii_lowercase と ascii_uppercase を合わせたもの。この値はロケールに依存しません。

string.ascii_lowercase

小文字 'abcdefghijklmnopqrstuvwxyz' 。この値はロケールに依存せず、固定です。

string.ascii_uppercase

大文字 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' 。この値はロケールに依存せず、固定です。

string.digits

文字列 '0123456789' です。

string.hexdigits

文字列 '0123456789abcdefABCDEF' です。

string.octdigits

文字列 '01234567' です。

string.punctuation

C ロケールにおいて、区切り文字 (punctuation characters) として扱われる ASCII 文字の文字列です: !"#$%&'()*+,-./:;<=>?@[\]^_`{|}~.

string.printable

印刷可能な ASCII 文字で構成される文字列です。 digits, ascii_letters, punctuation および whitespace を組み合わせたものです。

string.whitespace

空白 (whitespace) として扱われる ASCII 文字全てを含む文字列です。ほとんどのシステムでは、これはスペース (space)、タブ (tab)、改行 (linefeed)、復帰 (return)、改頁 (formfeed)、垂直タブ (vertical tab) です。

カスタムの文字列書式化

組み込みの文字列 (string) クラスには、 PEP 3101 [https://peps.python.org/pep-3101/] で記述されている format() メソッドによって複雑な変数置換と値のフォーマットを行う機能があります。 string モジュールの Formatter クラスでは、組み込みの format() メソッドと同じ実装を使用して、独自の文字列フォーマットの振る舞いを作成してカスタマイズすることができます。

class string.Formatter

Formatter クラスは、以下のメソッドを持ちます:

format(format_string, /, *args, **kwargs)

主要な API メソッドです。書式文字列と、任意の位置引数およびキーワード引数のセットを取ります。これは、vformat() を呼び出す単なるラッパーです。

バージョン 3.7 で変更: 書式文字列は 位置専用 の引数となりました。

vformat(format_string, args, kwargs)

この関数はフォーマットの実際の仕事をします。この関数は、 *args および **kwargs シンタックスを使用して、辞書を個々の引数として unpack してから再度 pack するのではなく、引数としてあらかじめ用意した辞書を渡したい場合のために、独立した関数として公開されます。 vformat() は、書式文字列を文字データと置換フィールドに分解する仕事をします。それは、以下に記述する様々なメソッドを呼び出します。

さらに、 Formatter ではサブクラスによって置き換えられることを意図した次のようないくつかのメソッドが定義されています。

parse(format_string)

format_stringを探査し、タプル、 (literal_text, field_name, format_spec, conversion) のイテラブルを返します。これは vformat() が文字列を文字としての文字データや置換フィールドに展開するために使用されます。

タプルの値は、概念的に文字としての文字データと、それに続く単一の置換フィールドを表現します。文字としての文字データが無い場合は (ふたつの置換フィールドが連続した場合などに起き得ます) 、 literal_text は長さが 0 の文字列となります。置換フィールドが無い場合は、 field_name, format_spec および conversion が None となります。

get_field(field_name, args, kwargs)

引数として与えた parse() (上記参照) により返される field_name を書式指定対象オブジェクトに変換します。返り値はタプル、 (obj, used_key) です。デフォルトでは PEP 3101 [https://peps.python.org/pep-3101/] に規定される "0[name]" や "label.title" のような形式の文字列を引数としてとります。 args と kwargs は vformat() に渡されます。返り値 used_key は、 get_value() の key 引数と同じ意味を持ちます。

get_value(key, args, kwargs)

与えられたフィールドの値を取り出します。 key 引数は整数でも文字列でも構いません。整数の場合は、位置引数 args のインデックス番号を示します。文字列の場合は、名前付きの引数 kwargs を意味します。

args 引数は、 vformat() への位置引数のリストに設定され、 kwargs 引数は、キーワード引数の辞書に設定されます。

フィールド名が (ピリオドで区切られた) いくつかの要素からなっている場合、最初の要素のみがこれらの関数に渡されます。残りの要素に関しては、通常の属性またはインデックスアクセスと同様に処理されます。

つまり、例えば、フィールドが '0.name' と表現されるとき、 get_value() は、 key 引数が 0 として呼び出されます。属性 name は、組み込みの getattr() 関数が呼び出され、 get_value() が返されたのちに検索されます。

インデックスまたはキーワードが存在しないアイテムを参照した場合、 IndexError または KeyError が送出されます。

check_unused_args(used_args, args, kwargs)

希望に応じて未使用の引数がないか確認する機能を実装します。この関数への引数は、書式指定文字列で実際に参照されるすべての引数のキーの set (位置引数の整数、名前付き引数の文字列) と、vformat に渡される args と kwargs への参照です。使用されない引数の set は、これらのパラメータから計算されます。 check_unused_args() は、確認の結果が偽である場合に例外を送出するものとみなされます。

format_field(value, format_spec)

format_field() は単純に組み込みのグローバル関数 format() を呼び出します。このメソッドは、サブクラスをオーバーライドするために提供されます。

convert_field(value, conversion)

(get_field() が返す) 値を (parse() メソッドが返すタプルの形式で) 与えられた変換タイプとして変換します。デフォルトバージョンは 's' (str), 'r' (repr), 'a' (ascii) 変換タイプを理解します。

書式指定文字列の文法

str.format() メソッドと Formatter クラスは、文字列の書式指定に同じ文法を共有します (ただし、 Formatter サブクラスでは、独自の書式指定文法を定義することが可能です)。この文法は フォーマット済み文字列リテラル の文法と関係してはいますが、少し洗練されておらず、特に任意の式がサポートされていません。

書式指定文字列は波括弧 {} に囲まれた "置換フィールド" を含みます。波括弧に囲まれた部分以外は全て単純な文字として扱われ、変更を加えることなく出力へコピーされます。波括弧を文字として扱う必要がある場合は、二重にすることでエスケープすることができます: {{ および }} 。

置換フィールドの文法は以下です:

replacement_field ::=  "{" [field_name] ["!" conversion] [":" format_spec] "}"
field_name        ::=  arg_name ("." attribute_name | "[" element_index "]")*
arg_name          ::=  [identifier | digit+]
attribute_name    ::=  identifier
element_index     ::=  digit+ | index_string
index_string      ::=  <any source character except "]"> +
conversion        ::=  "r" | "s" | "a"
format_spec       ::=  format-spec:format_spec

もっと簡単にいうと、置換フィールドは field_name で始められます。これによって指定したオブジェクトの値が、置換フィールドの代わりに書式化され出力に挿入されます。field_name の後に、感嘆符 '!' を挟んで conversion フィールドを続けることができます。最後にコロン ':' を挟んで、 format_spec を書くことができます。これは、置換される値の非デフォルトの書式を指定します。

書式指定ミニ言語仕様 節も参照して下さい。

field_name それ自身は、数かキーワードのいずれかである arg_name から始まります。それが数である場合、位置引数を参照します。また、それがキーワードである場合、指定されたキーワード引数を参照します。文字列に対して str.isdecimal() を呼び出した結果が真の場合、 arg_name は数として扱われます。書式文字列中で数の arg_names が順に 0, 1, 2, ... である場合、それらはすべて (いくつかではありません) 省略することができます。そして数 0, 1, 2, ... は、自動的にその順で挿入されます。 arg_name は引用符で区切られていないので、書式文字列内の任意の辞書キー (例えば文字列 '10' や ':-]' など) を指定することはできません。 arg_name の後に任意の数のインデックス式または属性式を続けることができます。 '.name' 形式の式は getattr() を使用して指定された属性を選択します。一方、 '[index]' 形式の式は __getitem__() を使用してインデックス参照を行います。

バージョン 3.1 で変更: str.format() を使い、位置引数指定を省略することができます。 '{} {}'.format(a, b) は '{0} {1}'.format(a, b) と同じになります。

バージョン 3.4 で変更: Formatter を使い、位置引数指定を省略することができます。

簡単な書式指定文字列の例を挙げます:

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

置換 (conversion) フィールドにより書式変換前に型の強制変換が実施されます。通常、値の書式変換は __format__() によって実施されます。しかしながら、場合によっては、文字列として変換することを強制したり、書式指定の定義をオーバーライドしたくなることもあります。 __format__() の呼び出し前に値を文字列に変換すると、通常の書式変換の処理は飛ばされます。

現在 3つの変換フラグがサポートされています: 値に対して str() を呼ぶ '!s' 、 repr() を呼ぶ '!r' 、 ascii() を呼ぶ '!a'。

いくつかの例です:

"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

format_spec フィールドは、フィールド幅、文字揃え、埋め方、精度などの、値を表現する仕様を含みます。それぞれの値の型は、 "formatting mini-language" 、または、 format_spec の実装で定義されます。

ほとんどの組み込み型は、次のセクションに記載された共通の formatting mini-language をサポートします。

format_spec フィールド内には入れ子になった置換フィールドを含めることもできます。入れ子になった置換フィールドにはフィールド名、変換フラグ、書式指定を含めることができますが、さらに入れ子の階層を含めることはできません。 format_spec 中の置換フィールドは format_spec 文字列が解釈される前に置き換えられます。これにより、値の書式を動的に指定することができます。

書式指定例 のいくつかの例も参照して下さい。

書式指定ミニ言語仕様

書式指定 ("Format specifications") は書式指定文字列の個々の値を表現する方法を指定するための、置換フィールドで使用されます (書式指定文字列の文法 および f-strings を参照してください) 。それらは、組み込み関数の format() 関数に直接渡されます。それぞれの書式指定可能な型について、書式指定がどのように解釈されるかが規定されます。

多くの組み込み型は、書式指定に関して以下のオプションを実装します。しかしながら、いくつかの書式指定オプションは数値型でのみサポートされます。

一般的な取り決めとして、空の書式指定は、値に対して str() を呼び出したときと同じ結果を与えます。通常、空でない書式指定はその結果を変更します。

一般的な書式指定子 (standard format specifier) の書式は以下です:

format_spec     ::=  [[fill]align][sign]["z"]["#"]["0"][width][grouping_option]["." precision][type]
fill            ::=  <any character>
align           ::=  "<" | ">" | "=" | "^"
sign            ::=  "+" | "-" | " "
width           ::=  digit+
grouping_option ::=  "_" | ","
precision       ::=  digit+
type            ::=  "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%"

有効な align 値を指定する場合、その前に fill 文字を付けることができます。この文字には任意の文字を指定でき、省略された場合はデフォルトの空白文字となります。 formatted string literal の中や str.format() メソッドを使う場合はリテラルの波括弧 ("{" と "}") を fill 文字として使えないことに注意してください。ただし、波括弧を入れ子になった置換フィールド内に挿入することはできます。この制限は format() 関数には影響しません。

様々な align オプションの意味は以下のとおりです:

オプション

意味

'<'

利用可能なスペースにおいて、左詰めを強制します (ほとんどのオブジェクトにおいてのデフォルト)。

'>'

利用可能なスペースにおいて、右詰めを強制します (いくつかのオブジェクトにおいてのデフォルト)。

'='

符号 (があれば) の後ろを埋めます。 '+000000120' のような形で表示されます。このオプションは数値型に対してのみ有効です。フィールド幅の直前が '0' の時はこれがデフォルトの数値になります。

'^'

利用可能なスペースにおいて、中央寄せを強制します。

最小のフィールド幅が定義されない限り、フィールド幅はデータを表示するために必要な幅と同じになることに注意して下さい。そのため、その場合には、 align オプションは意味を持ちません。

sign オプションは数値型に対してのみ有効であり、以下のうちのひとつとなります:

オプション

意味

'+'

符号の使用を、正数、負数の両方に対して指定します。

'-'

符号の使用を、負数に対してのみ指定します (デフォルトの挙動です)。

空白

空白を正数の前に付け、負号を負数の前に使用することを指定します。

'z' オプションはマイナス0の浮動小数点数をフォーマットの制度で丸めたあとにプラス0に強制的に変換します。このオプションは浮動小数点数型に対してのみ有効です。

バージョン 3.11 で変更: 'z' オプションが追加されました (PEP 682 [https://peps.python.org/pep-0682/] も参照)。

'#' オプションは、変換に「別形式」を使用します。別形式は、異なる型に対して違った風に定義されます。このオプションは、整数、浮動小数点数、複素数でのみ有効です。整数に対して2進法、8進法、または16進法の出力が使用される場合、このオプションは出力される値にそれぞれ '0b', '0o', '0x', '0X' 接頭辞を加えます。浮動小数点数、複素数については、別形式では、小数点文字の後に数字がなくても変換結果には常に小数点文字が含まれます。通常は、数字が続く場合にのみ小数点文字がこれらの変換結果に現われます。さらに、'g' と 'G' の変換については、最後の 0 は結果から取り除かれません。

',' オプションは、千の位のセパレータにカンマを使うことを合図します。ロケール依存のセパレータには、代わりに 'n' の整数表現形式を使ってください。

バージョン 3.1 で変更: ',' オプションが追加されました (PEP 378 [https://peps.python.org/pep-0378/] も参照)。

'_' オプションは、浮動小数点数の表現型と整数の表現型 'd' における千倍ごとの区切り文字にアンダースコアを使うというしるしです。整数の表現型の 'b', 'o', 'x', 'X' では、4桁ごとにアンダースコアが挿入されます。他の表現型でこのオプションを指定するとエラーになります。

バージョン 3.6 で変更: '_' オプションが追加されました (PEP 515 [https://peps.python.org/pep-0515/] も参照)。

width は10進数の整数で、接頭辞、セパレータ、他のフォーマット文字を含んだ最小の合計フィールド幅を定義します。指定されない場合、フィールド幅はその内容により決定されます。

alignment が明示的に与えられない場合、 width フィールドにゼロ ('0') 文字を前置することは、数値型のための符号を意識した 0 パディングを可能にします。これは fill 文字に '0' を指定して、 alignment タイプに '=' を指定したことと等価です。

バージョン 3.10 で変更: Preceding the width field by '0' no longer affects the default alignment for strings.

*precision*は、表現型``'f'または'F'の場合小数点以下、表現型'g'または'G'``の場合は小数点以上と以下が何桁で表示されるべきかを示す10進整数です。文字列の表現型の場合は最大フィールド幅、言い換えるとフィールドの内容から何文字が使用されるかを示します。*precision*は整数の表現型には使用できません。

最後に、type は、データがどのように表現されるかを決定します。

利用可能な文字列の表現型は以下です:

型

意味

's'

文字列。これがデフォルトの値で、多くの場合省略されます。

None

's' と同じです。

利用可能な整数の表現型は以下です:

型

意味

'b'

2進数。出力される数値は2を基数とします。

'c'

文字。数値を対応する Unicode 文字に変換します。

'd'

10進数。出力される数値は10を基数とします。

'o'

8進数。出力される数値は8を基数とします。

'x'

16進数。出力される数値は16を基数とします。 10進で9を超える数字には小文字が使われます。

'X'

16進数。出力される数値は16を基数とします。10進で9を超える数字には大文字が使われます。'#'``が指定された場合、接頭辞'0x'も大文字'0X'``になります

'n'

数値。現在のロケールに従い、区切り文字を挿入することを除けば、 'd' と同じです。

None

'd' と同じです。

これらの表現型に加えて、整数は ('n' と None を除く) 以下の浮動小数点数の表現型で書式指定できます。そうすることで整数は書式変換される前に float() を使って浮動小数点数に変換されます。

利用可能な float と Decimal の表現型は以下です:

型

意味

'e'

Scientific notation. For a given precision p, formats the number in scientific notation with the letter 'e' separating the coefficient from the exponent. The coefficient has one digit before and p digits after the decimal point, for a total of p + 1 significant digits. With no precision given, uses a precision of 6 digits after the decimal point for float, and shows all coefficient digits for Decimal. If no digits follow the decimal point, the decimal point is also removed unless the # option is used.

'E'

指数表記です。大文字の 'E' を使うことを除いては、 'e' と同じです。

'f'

Fixed-point notation. For a given precision p, formats the number as a decimal number with exactly p digits following the decimal point. With no precision given, uses a precision of 6 digits after the decimal point for float, and uses a precision large enough to show all coefficient digits for Decimal. If no digits follow the decimal point, the decimal point is also removed unless the # option is used.

'F'

固定小数点数表記です。nan が NAN に、inf が INF に変換されることを除き 'f' と同じです。

'g'

General format. For a given precision p >= 1, this rounds the number to p significant digits and then formats the result in either fixed-point format or in scientific notation, depending on its magnitude. A precision of 0 is treated as equivalent to a precision of 1.

The precise rules are as follows: suppose that the result formatted with presentation type 'e' and precision p-1 would have exponent exp. Then, if m <= exp < p, where m is -4 for floats and -6 for Decimals, the number is formatted with presentation type 'f' and precision p-1-exp. Otherwise, the number is formatted with presentation type 'e' and precision 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 '#' option is used.

With no precision given, uses a precision of 6 significant digits for float. For Decimal, the coefficient of the result is formed from the coefficient digits of the value; scientific notation is used for values smaller than 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.

正と負の無限大と 0 および NaN は精度に関係なくそれぞれ inf, -inf, 0, -0 および nan となります。

'G'

汎用フォーマットです。数値が大きくなったとき、 'E' に切り替わることを除き、 'g' と同じです。無限大と NaN の表示も大文字になります。

'n'

数値です。現在のロケールに合わせて、数値分割文字が挿入されることを除き、 'g' と同じです。

'%'

パーセンテージです。数値は 100 倍され、固定小数点数フォーマット ('f') でパーセント記号付きで表示されます。

None

For float this is the same as 'g', except that when fixed-point notation is used to format the result, it always includes at least one digit past the decimal point. The precision used is as large as needed to represent the given value faithfully.

For Decimal, this is the same as either 'g' or 'G' depending on the value of context.capitals for the current decimal context.

The overall effect is to match the output of str() as altered by the other format modifiers.

書式指定例

この節では、 str.format() 構文の例を紹介し、さらに従来の %-書式と比較します。

多くの場合、新構文に {} を加え、 % の代わりに : を使うことで、古い %-書式に類似した書式になります。例えば、'%03.2f' は '{:03.2f}' と変換できます。

以下の例で示すように、新構文はさらに新たに様々なオプションもサポートしています。

位置引数を使ったアクセス:

>>> '{0}, {1}, {2}'.format('a', 'b', 'c')
'a, b, c'
>>> '{}, {}, {}'.format('a', 'b', 'c')  # 3.1+ only
'a, b, c'
>>> '{2}, {1}, {0}'.format('a', 'b', 'c')
'c, b, a'
>>> '{2}, {1}, {0}'.format(*'abc')      # unpacking argument sequence
'c, b, a'
>>> '{0}{1}{0}'.format('abra', 'cad')   # arguments' indices can be repeated
'abracadabra'

名前を使ったアクセス:

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

引数の属性へのアクセス:

>>> 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)'

引数の要素へのアクセス:

>>> coord = (3, 5)
>>> 'X: {0[0]};  Y: {0[1]}'.format(coord)
'X: 3;  Y: 5'

%s と %r の置き換え:

>>> "repr() shows quotes: {!r}; str() doesn't: {!s}".format('test1', 'test2')
"repr() shows quotes: 'test1'; str() doesn't: test2"

テキストの幅を指定した整列:

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

%+f と %-f, % f の置換、そして符号の指定:

>>> '{:+f}; {:+f}'.format(3.14, -3.14)  # show it always
'+3.140000; -3.140000'
>>> '{: f}; {: f}'.format(3.14, -3.14)  # show a space for positive numbers
' 3.140000; -3.140000'
>>> '{:-f}; {:-f}'.format(3.14, -3.14)  # show only the minus -- same as '{:f}; {:f}'
'3.140000; -3.140000'

%x と %o の置換、そして値に対する異なる底の変換:

>>> # 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'

千の位のセパレータにカンマを使用する:

>>> '{:,}'.format(1234567890)
'1,234,567,890'

パーセントを表示する:

>>> points = 19
>>> total = 22
>>> 'Correct answers: {:.2%}'.format(points/total)
'Correct answers: 86.36%'

型特有の書式指定を使う:

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

引数をネストする、さらに複雑な例:

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

テンプレート文字列

テンプレート文字列では PEP 292 [https://peps.python.org/pep-0292/] で解説されている単純な文字列置換ができます。テンプレート文字列の主な使い道は国際化 (i18n) です。というのは、その国際化の文脈において、より簡潔な文法と機能を持つテンプレート文字列を使うと、 Python にある他の組み込みの文字列フォーマット機能よりも翻訳がしやすいからです。テンプレート文字列の上に構築された国際化のためのライプラリの例として、 flufl.i18n [https://flufli18n.readthedocs.io/en/latest/] を調べてみてください。

テンプレート文字列は $ に基づいた置換をサポートしていて、次の規則が使われています:

$$ はエスケープ文字です; $ 一つに置換されます。

$identifier は "identifier" のマッピングキーに合致する置換プレースホルダーを指定します。デフォルトでは、 "identifier" は大文字と小文字を区別しない ASCII 英数字 (アンダースコアを含む) からなら文字列に制限されています。文字列はアンダースコアか ASCII 文字から始まるものでなければなりません。$ の後に識別子に使えない文字が出現すると、そこでプレースホルダ名の指定が終わります。

${identifier} は $identifier と同じです。プレースホルダ名の後ろに識別子として使える文字列が続いていて、それをプレースホルダ名の一部として扱いたくない場合、例えば "${noun}ification" のような場合に必要な書き方です。

上記以外の書き方で文字列中に $ を使うと ValueError を送出します。

string モジュールでは、上記のような規則を実装した Template クラスを提供しています。 Template のメソッドを以下に示します:

class string.Template(template)

コンストラクタはテンプレート文字列になる引数を一つだけ取ります。

substitute(mapping={}, /, **kwds)

テンプレート置換を行い、新たな文字列を生成して返します。mapping はテンプレート中のプレースホルダに対応するキーを持つような任意の辞書類似オブジェクトです。辞書を指定する代わりに、キーワード引数も指定でき、その場合にはキーワードをプレースホルダ名に対応させます。mapping と kwds の両方が指定され、内容が重複した場合には、kwds に指定したプレースホルダを優先します。

safe_substitute(mapping={}, /, **kwds)

substitute() と同じですが、プレースホルダに対応するものを mapping や kwds から見つけられなかった場合に、 KeyError 例外を送出する代わりにもとのプレースホルダがそのまま入ります。また、 substitute() とは違い、規則外の書き方で $ を使った場合でも、 ValueError を送出せず単に $ を返します。

その他の例外も発生し得る一方で、このメソッドが「安全 (safe) 」と呼ばれているのは、置換操作は常に、例外を送出する代わりに利用可能な文字列を返そうとするからです。別の見方をすれば、 safe_substitute() は区切り間違いによるぶら下がり (dangling delimiter) や波括弧の非対応、 Python の識別子として無効なプレースホルダ名を含むような不正なテンプレートを何も警告せずに無視するため、安全とはいえないのです。

is_valid()

Returns false if the template has invalid placeholders that will cause substitute() to raise ValueError.

Added in version 3.11.

get_identifiers()

Returns a list of the valid identifiers in the template, in the order they first appear, ignoring any invalid identifiers.

Added in version 3.11.

Template のインスタンスは、次のような public な属性を提供しています:

template

コンストラクタの引数 template に渡されたオブジェクトです。通常、この値を変更すべきではありませんが、読み出し専用アクセスを強制しているわけではありません。

Templateの使い方の例を以下に示します:

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

さらに進んだ使い方: Template のサブクラスを派生して、プレースホルダの書式、区切り文字、テンプレート文字列の解釈に使われている正規表現全体をカスタマイズできます。こうした作業には、以下のクラス属性をオーバライドします:

delimiter -- プレースホルダの開始を示すリテラル文字列です。デフォルトの値は $ です。実装系はこの文字列に対して必要に応じて re.escape() を呼び出すので、正規表現になってしまうような文字列にしては なりません 。さらにクラスを作成した後に delimiter を変更できない (つまり、別の delimiter を設定したいのであれば、サブクラスの名前空間で行わなければならない) ことに注意してください。

idpattern -- This is the regular expression describing the pattern for non-braced placeholders. The default value is the regular expression (?a:[_a-z][_a-z0-9]*). If this is given and braceidpattern is None this pattern will also apply to braced placeholders.

注釈

flags のデフォルトは re.IGNORECASE なので、 [a-z] というパターンはいくつかの非 ASCII 文字に適合できます。そのため、ここではローカルの a フラグを使っています。

バージョン 3.7 で変更: braceidpattern を使用すると、中括弧の内側と外側で使用する別々のパターンを定義できます。

braceidpattern -- This is like idpattern but describes the pattern for braced placeholders. Defaults to None which means to fall back to idpattern (i.e. the same pattern is used both inside and outside braces). If given, this allows you to define different patterns for braced and unbraced placeholders.

Added in version 3.7.

flags -- 代入の認識のために使用される正規表現をコンパイルする際に適用される正規表現フラグ。デフォルト値は re.IGNORECASE です。re.VERBOSE が常にフラグに追加されるということに注意してください。したがって、カスタムな idpattern は verbose 正規表現の規約に従わなければなりません。

Added in version 3.2.

他にも、クラス属性 pattern をオーバライドして、正規表現パターン全体を指定できます。オーバライドを行う場合、 pattern の値は 4 つの名前つきキャプチャグループ (capturing group) を持った正規表現オブジェクトでなければなりません。これらのキャプチャグループは、上で説明した規則と、無効なプレースホルダに対する規則に対応しています:

escaped -- このグループはエスケープシーケンス、すなわちデフォルトパターンにおける $$ に対応します。

named -- このグループは波括弧でくくらないプレースホルダ名に対応します; キャプチャグループに区切り文字を含めてはなりません。

braced -- このグループは波括弧でくくったプレースホルダ名に対応します; キャプチャグループに区切り文字を含めてはなりません。

invalid -- このグループはそのほかの区切り文字のパターン (通常は区切り文字一つ) に対応し、正規表現の末尾に出現しなければなりません。

The methods on this class will raise ValueError if the pattern matches the template without one of these named groups matching.

ヘルパー関数

string.capwords(s, sep=None)

str.split() を使って引数を単語に分割し、 str.capitalize() を使ってそれぞれの単語の先頭の文字を大文字に変換し、 str.join() を使ってつなぎ合わせます。オプションの第2引数 sep が与えられないか None の場合、この置換処理は文字列中の連続する空白文字をスペース一つに置き換え、先頭と末尾の空白を削除します、それ以外の場合には sep は split と join に使われます。

re --- Regular expression operations

ソースコード: Lib/re/ [https://github.com/python/cpython/tree/3.12/Lib/re/]

このモジュールは Perl に見られる正規表現マッチング操作と同様のものを提供します。

パターンおよび検索される文字列には、Unicode 文字列 (str) や 8 ビット文字列 (bytes) を使います。ただし、Unicode 文字列と 8 ビット文字列の混在はできません。つまり、Unicode 文字列にバイト列のパターンでマッチングしたり、その逆はできません。同様に、置換時の置換文字列はパターンおよび検索文字列の両方と同じ型でなくてはなりません。

正規表現では、特殊な形式を表すためや、特殊文字をその特殊な意味を発動させず使うために、バックスラッシュ文字 ('\') を使います。こうしたバックスラッシュの使い方は、 Python の文字列リテラルにおける同じ文字の使い方と衝突します。例えば、リテラルのバックスラッシュにマッチさせるには、パターン文字列として '\\\\' と書かなければなりません。なぜなら、正規表現は \\ でなければならないうえ、それぞれのバックスラッシュは標準の Python 文字列リテラルで \\ と表現せねばならないからです。 Python の文字列リテラルにおいて、バックスラッシュの使用による不正なエスケープ文字がある場合は、SyntaxWarning が発生し、将来的には SyntaxError になることにも注意してください。この動作は、正規表現として有効な文字列に対しても同様です。

これを解決するには、正規表現パターンに Python の raw 文字列記法を使います。 'r' を前置した文字列リテラル内ではバックスラッシュが特別扱いされません。従って "\n" が改行一文字からなる文字列であるのに対して、 r"\n" は '\' と 'n' の二文字からなる文字列です。通常、 Python コード中では、パターンをこの raw 文字列記法を使って表現します。

重要なこととして、大抵の正規表現操作は、モジュールレベルの関数としても、 コンパイル済み正規表現 のメソッドとしても利用できます。関数は正規表現オブジェクトを前もってコンパイルする必要がない近道ですが、微調整のための変数が減ります。

参考

The third-party regex [https://pypi.org/project/regex/] module, which has an API compatible with the standard library re module, but offers additional functionality and a more thorough Unicode support.

正規表現のシンタックス

正規表現 (または RE) は、その表現にマッチ (match) する文字列の集合を指定します。このモジュールの関数を使えば、ある文字列が与えられた正規表現にマッチするか (または、与えられた正規表現がある文字列にマッチするか、と言い換えても同じことになります) を検査できます。

正規表現を連結することで新しい正規表現を作れます。A と B がともに正規表現であれば AB も正規表現です。一般的に、ある文字列 p が A にマッチし、別の文字列 q が B にマッチするなら、文字列 pq は AB にマッチします。ただし、 A または B に優先度の低い演算が含まれる場合や、 A と B との間に境界条件がある場合や、番号付けされたグループ参照をしている場合、を除きます。こうして、ここで述べるような簡単な基本表現から、複雑な表現を容易に構築できます。正規表現に関する理論と実装の詳細については Friedl 本 [Frie09] か、コンパイラの構築に関するテキストを参照してください。

以下で正規表現の形式を簡単に説明します。詳細な情報ややさしい説明は、 正規表現 HOWTO を参照してください。

正規表現には、特殊文字と通常文字の両方を含められます。 'A' 、 'a' 、または '0' のようなほとんどの通常文字は、最も単純な正規表現です。これは単純に、その文字自体にマッチします。通常文字は連結できるので、 last は文字列 'last' にマッチします。 (この節では以降、正規表現は一般にクオートを使わず この特殊スタイルで 表記し、マッチ対象の文字列は、 'シングルクオートで括って' 表記します。)

'|' や '(' といったいくつかの文字は特殊です。特殊文字は通常文字の種別を表したり、周辺の通常文字に対する解釈方法に影響します。

繰り返しの演算子または修飾子 (*、 +、 ?、 {m,n} など) は直接入れ子にはできません。これは、非貪欲な修飾子の接尾辞 ? や他の実装での他の修飾子との曖昧さを回避します。内側で繰り返したものをさらに繰り返すには、丸括弧が使えます。例えば、正規表現 (?:a{6})* は 6 の倍数個の 'a' 文字にマッチします。

特殊文字を以下に示します:

.

(ドット) デフォルトのモードでは改行以外の任意の文字にマッチします。 DOTALL フラグが指定されていれば改行も含む全ての文字にマッチします。

^

(キャレット) 文字列の先頭にマッチし、 MULTILINE モードでは各改行の直後にもマッチします。

$

文字列の末尾、あるいは文字列の末尾の改行の直前にマッチし、 MULTILINE モードでは改行の前にもマッチします。 foo は 'foo' と 'foobar' の両方にマッチしますが、正規表現 foo$ は 'foo' だけにマッチします。興味深いことに、 'foo1\nfoo2\n' を foo.$ で検索した場合、通常は 'foo2' だけにマッチしますが、 MULTILINE モードでは 'foo1' にもマッチします。 $ だけで 'foo\n' を検索した場合、2 つの (空の) マッチを見つけます: 1つは改行の直前で、もう1つは文字列の末尾です。

*

直前の正規表現を 0 回以上、できるだけ多く繰り返したものにマッチさせる結果の正規表現にします。例えば ab* は 'a'、'ab'、または 'a' に任意個数の 'b' を続けたものにマッチします。

+

直前の正規表現を 1 回以上繰り返したものにマッチさせる結果の正規表現にします。例えば ab+ は 'a' に 1 つ以上の 'b' が続いたものにマッチし、単なる 'a' にはマッチしません。

?

直前の正規表現を 0 回か 1 回繰り返したものにマッチさせる結果の正規表現にします。例えば ab? は 'a' あるいは 'ab' にマッチします。

*?, +?, ??

'*' 、 '+' 、および '?' 修飾子は全て 貪欲 (greedy) マッチで、できるだけ多くのテキストにマッチします。この挙動が望ましくない時もあります。例えば正規表現 <.*> が '<a> b <c>' に対してマッチされると、 '<a>' だけでなく文字列全体にマッチしてしまいます。修飾子の後に ? を追加すると、 非貪欲 (non-greedy) あるいは 最小 (minimal) のマッチが行われ、できるだけ 少ない 文字にマッチします。正規表現 <.*?> を使うと '<a>' だけにマッチします。

*+, ++, ?+

Like the '*', '+', and '?' quantifiers, those where '+' 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, a*a will match 'aaaa' because the a* will match all 4 'a's, but, when the final 'a' is encountered, the expression is backtracked so that in the end the a* ends up matching 3 'a's total, and the fourth 'a' is matched by the final 'a'. However, when a*+a is used to match 'aaaa', the a*+ will match all 4 'a', but when the final 'a' fails to find any more characters to match, the expression cannot be backtracked and will thus fail to match. x*+, x++ and x?+ are equivalent to (?>x*), (?>x+) and (?>x?) correspondingly.

Added in version 3.11.

{m}

直前の正規表現をちょうど m 回繰り返したものにマッチさせるよう指定します。それより少ないマッチでは正規表現全体がマッチしません。例えば、 a{6} は 6 個ちょうどの 'a' 文字にマッチしますが、 5 個ではマッチしません。

{m,n}

直前の正規表現を m 回から n 回、できるだけ多く繰り返したものにマッチさせる結果の正規表現にします。例えば、a{3,5} は、3 個から 5 個の 'a' 文字にマッチします。m を省略すると下限は 0 に指定され、n を省略すると上限は無限に指定されます。例として、 a{4,}b は 'aaaab' や、1,000 個の 'a' 文字に 'b' が続いたものにマッチしますが、'aaab' にはマッチしません。コンマは省略できません、省略すると修飾子が上で述べた形式と混同されてしまうからです。

{m,n}?

結果の正規表現は、前にある正規表現を、m 回から n 回まで繰り返したものにマッチし、できるだけ 少なく 繰り返したものにマッチするようにします。これは、前の数量詞の非貪欲版です。例えば、 6 文字文字列 'aaaaaa' では、 a{3,5} は、5 個の 'a' 文字にマッチしますが、 a{3,5}? は 3 個の文字にマッチするだけです。

{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 'aaaaaa', a{3,5}+aa attempt to match 5 'a' characters, then, requiring 2 more 'a's, will need more characters than available and thus fail, while a{3,5}aa will match with a{3,5} capturing 5, then 4 'a's by backtracking and then the final 2 'a's are matched by the final aa in the pattern. x{m,n}+ is equivalent to (?>x{m,n}).

Added in version 3.11.

\

特殊文字をエスケープ ( '*' や '?' などの文字にマッチできるようにする) し、または特殊シーケンスを合図します。特殊シーケンスは後で議論します。

パターンを表現するのに raw 文字列を使っていないのであれば、 Python ももまた、バックスラッシュを文字列リテラルでエスケープシーケンスとして使うことを思い出して下さい。そのエスケープシーケンスを Python のパーザが認識しないなら、そのバックスラッシュとそれに続く文字が結果の文字列に含まれます。しかし、Python が結果のシーケンスを認識するなら、そのバックスラッシュは 2 回繰り返さなければいけません。これは複雑で理解しにくいので、ごく単純な表現以外は、全て raw 文字列を使うことを強く推奨します。

[]

文字の集合を指定するのに使います。集合の中では:

文字を個別に指定できます。 [amk] は 'a' 、 'm' または 'k' にマッチします。

連続した文字の範囲を、 '-' を2 つの文字で挟んで指定できます。例えば、 [a-z] はあらゆる小文字の ASCII 文字にマッチします。[0-5][0-9] は 00 から 59 まで全ての 2 桁の数字にマッチします。[0-9A-Fa-f] は任意の 16 進数字にマッチします。- がエスケープされているか (例: [a\-z])、先頭や末尾の文字にされていると (例: [-a] や [a-])、リテラル '-' にマッチします。

集合の中では、特殊文字はその特殊な意味を失います。例えば [(+*)] はリテラル文字 '(' 、 '+' 、 '*' 、または ')' のどれにでもマッチします。

Character classes such as \w or \S (defined below) are also accepted inside a set, although the characters they match depend on the flags used.

補集合 をとって範囲内にない文字にマッチできます。集合の最初の文字が '^' なら、集合に 含まれない 全ての文字にマッチします。例えば、 [^5] は '5' を除くあらゆる文字にマッチし、 [^^] は '^' を除くあらゆる文字にマッチします。 ^ は集合の最初の文字でなければ特別の意味を持ちません。

集合の中でリテラル ']' にマッチさせるには、その前にバックスラッシュをつけるか、集合の先頭に置きます。例えば、 [()[\]{}] と []()[{}] はどちらも閉じ角括弧、開き角括弧、波括弧、丸括弧にマッチします。

Unicode Technical Standard #18 [https://unicode.org/reports/tr18/] にあるような集合の入れ子や集合操作が将来追加される可能性があります。これは構文を変化させるもので、この変化を容易にするために、さしあたって曖昧な事例には FutureWarning が送出されます。これはリテラル '[' で始まる集合や、リテラル文字の連続 '--' 、 '&&' 、 '~~' および '||' を含む集合を含みます。警告を避けるにはバックスラッシュでエスケープしてください。

バージョン 3.7 で変更: 文字セットが将来意味論的に変化する構造を含むなら FutureWarning が送出されます。

|

A と B を任意の正規表現として、 A|B は A と B のいずれかにマッチする正規表現を作成します。この方法で任意の数の正規表現を '|' で分離できます。これはグループ (下記参照) 中でも使えます。対象文字列を走査するとき、'|' で分離された正規表現は左から右へ順に試されます。一つのパターンが完全にマッチしたとき、そのパターン枝が受理されます。つまり、ひとたび A がマッチしてしまえば、例え B によって全体のマッチが長くなるとしても、 B はもはや走査されません。言いかえると、 '|' 演算子は決して貪欲にはなりません。リテラル '|' にマッチするには、 \| を使うか、 [|] のように文字クラス中に囲みます。

(...)

丸括弧で囲まれた正規表現にマッチするとともに、グループの開始と終了を表します。グループの中身は以下で述べるように、マッチが実行された後で回収したり、その文字列中で以降 \number 特殊シーケンスでマッチしたりできます。リテラル '(' や ')' にマッチするには、\( や \) を使うか、文字クラス中に囲みます: [(]、 [)] 。

(?...)

これは拡張記法です ('(' に続く '?' はそれ以上の意味を持ちません) 。 '?' に続く最初の文字がこの構造の意味と特有の構文を決定します。拡張は一般に新しいグループを作成しません。ただし (?P<name>...) はこの法則の唯一の例外です。現在サポートされている拡張は以下の通りです。

(?aiLmsux)

(One or more letters from the set 'a', 'i', 'L', 'm', 's', 'u', 'x'.) The group matches the empty string; the letters set the corresponding flags for the entire regular expression:

re.A (ASCIIのみにマッチ)

re.I (大文字小文字を無視)

re.L (ロケール依存)

re.M (マルチライン)

re.S (ドットはすべてにマッチ)

re.U (Unicodeマッチ)

re.X (冗長)

(The flags are described in モジュールコンテンツ.) This is useful if you wish to include the flags as part of the regular expression, instead of passing a flag argument to the 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.

(?:...)

普通の丸括弧の、キャプチャしない版です。丸括弧で囲まれた正規表現にマッチしますが、このグループがマッチした部分文字列は、マッチを実行したあとで回収することも、そのパターン中で以降参照することも できません 。

(?aiLmsux-imsx:...)

(Zero or more letters from the set 'a', 'i', 'L', 'm', 's', 'u', 'x', optionally followed by '-' followed by one or more letters from the 'i', 'm', 's', 'x'.) The letters set or remove the corresponding flags for the part of the expression:

re.A (ASCIIのみにマッチ)

re.I (大文字小文字を無視)

re.L (ロケール依存)

re.M (マルチライン)

re.S (ドットはすべてにマッチ)

re.U (Unicodeマッチ)

re.X (冗長)

(The flags are described in モジュールコンテンツ.)

文字 'a' 、 'L' および 'u' は相互に排他であり、組み合わせることも '-' に続けることもできません。その代わり、これらの内一つがインライングループ中に現れると、外側のグループでのマッチングモードを上書きします。 Unicode パターン中では (?a:...) は ASCII 限定マッチングに切り替え、 (?u:...) は Unicode マッチング (デフォルト) に切り替えます。バイト列パターン中では、 (?L:...) はロケール依存マッチングに切り替え、 (?a:...) は ASCII 限定マッチング (デフォルト) に切り替えます。この上書きは狭いインライングループにのみ影響し、元のマッチングモードはグループ外では復元されます。

Added in version 3.6.

バージョン 3.7 で変更: 文字 'a' 、 'L' および 'u' もグループ中で使えます。

(?>...)

Attempts to match ... 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 (?>...) because once exited, the expression, known as an atomic group, has thrown away all stack points within itself. Thus, (?>.*). would never match anything because first the .* would match all characters possible, then, having nothing left to match, the final . would fail to match. Since there are no stack points saved in the Atomic Group, and there is no stack point before it, the entire expression would thus fail to match.

Added in version 3.11.

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

名前付きグループは 3 つのコンテキストで参照できます。パターンが (?P<quote>['\"]).*?(?P=quote) (シングルまたはダブルクオートで囲まれた文字列にマッチ) ならば:

グループ "quote" を参照するコンテキスト

参照する方法

その同じパターン中

(?P=quote) (示したとおり)

\1

マッチオブジェクト m の処理時

m.group('quote')

m.end('quote') (など)

re.sub() の repl 引数へ渡される文字列中

\g<quote>

\g<1>

\1

バージョン 3.12 で変更: In bytes patterns, group name can only contain bytes in the ASCII range (b'\x00'-b'\x7f').

(?P=name)

名前付きグループへの後方参照です。これは name という名前の既出のグループがマッチした文字列にマッチします。

(?#...)

コメントです。括弧の中身は単純に無視されます。

(?=...)

... が次に続くものにマッチすればマッチしますが、文字列をまったく消費しません。これは 先読みアサーション (lookahead assertion) と呼ばれます。例えば、Isaac (?=Asimov) は 'Isaac ' に、その後に 'Asimov' が続く場合にのみ、マッチします。

(?!...)

... が次に続くものにマッチしなければマッチします。これは 否定先読みアサーション (negative lookahead assertion) です。例えば、Isaac (?!Asimov) は 'Isaac ' に、その後に 'Asimov' が続か ない 場合にのみ、マッチします。

(?<=...)

その文字列における現在位置の前に、現在位置で終わる ... とのマッチがあれば、マッチします。これは 後読みアサーション と呼ばれます。(?<=abc)def は、後読みは 3 文字をバックアップし、含まれているパターンがマッチするか検査するので 'abcdef' にマッチを見つけます。含まれるパターンは、固定長の文字列にのみマッチしなければなりません。すなわち、 abc や a|b は許されますが、a* や a{3,4} は許されません。肯定後読みアサーションで始まるパターンは、検索される文字列の先頭とは決してマッチしないことに注意して下さい。match() 関数ではなく search() 関数を使う方が望ましいでしょう:

>>> import re
>>> m = re.search('(?<=abc)def', 'abcdef')
>>> m.group(0)
'def'

この例ではハイフンに続く単語を探します:

>>> m = re.search(r'(?<=-)\w+', 'spam-egg')
>>> m.group(0)
'egg'

バージョン 3.5 で変更: 固定長のグループ参照をサポートするようになりました。

(?<!...)

その文字列における現在位置の前に ... とのマッチがなければ、マッチします。これは 否定後読みアサーション(negative lookbehind assertion) と呼ばれます。肯定後読みアサーションと同様に、含まれるパターンは固定長の文字列にのみマッチしなければなりません。否定後読みアサーションで始まるパターンは検索される文字列の先頭でマッチできます。

(?(id/name)yes-pattern|no-pattern)

与えられた id や name のグループが存在すれば yes-pattern との、存在しなければ no-pattern とのマッチを試みます。no-pattern はオプションであり省略できます。例えば、(<)?(\w+@\w+(?:\.\w+)+)(?(1)>|$) は貧弱な E-mail マッチングパターンで、'<user@host.com>' や 'user@host.com' にはマッチしますが、'<user@host.com' や 'user@host.com>' にはマッチしません。

バージョン 3.12 で変更: Group id can only contain ASCII digits. In bytes patterns, group name can only contain bytes in the ASCII range (b'\x00'-b'\x7f').

特殊シーケンスは '\' と以下のリストの文字から構成されます。通常文字が ASCII 数字でも ASCII 文字でもなければ、結果の正規表現は 2 番目の文字にマッチします。例えば、\$ は文字 '$' にマッチします。

\number

同じ番号のグループの中身にマッチします。グループは 1 から始まる番号をつけられます。例えば、 (.+) \1 は、 'the the' あるいは '55 55' にマッチしますが、 'thethe' にはマッチしません(グループの後のスペースに注意して下さい)。この特殊シーケンスは最初の 99 グループのうちの一つとのマッチにのみ使えます。 number の最初の桁が 0 であるか、 number が 3 桁の 8 進数であれば、それはグループのマッチとしてではなく、 8 進値 number を持つ文字として解釈されます。文字クラスの '[' と ']' の間では全ての数値エスケープが文字として扱われます。

\A

文字列の先頭でのみマッチします。

\b

空文字列にマッチしますが、単語の先頭か末尾でのみです。単語は単語文字の並びとして定義されます。形式的には、 \b は \w と \W 文字 (またはその逆) との、あるいは \w と文字列の先頭・末尾との境界として定義されます。例えば、 r'\bat\b' は 'at' 、 'at.'、 '(at)' や 'as at ay' にはマッチしますが、 'attempt' や 'atlas' にはマッチしません。

The default word characters in Unicode (str) patterns are Unicode alphanumerics and the underscore, but this can be changed by using the ASCII flag. Word boundaries are determined by the current locale if the LOCALE flag is used.

注釈

Inside a character range, \b represents the backspace character, for compatibility with Python's string literals.

\B

空文字列にマッチしますが、それが単語の先頭か末尾 でない ときのみです。つまり r'at\B' は 'athens'、 'atom'、'attorney' にマッチしますが、 'at'、 'at.' や 'at!' にはマッチしません。 \B は \b のちょうど反対で、 Unicode パターンにおける単語文字は Unicode 英数字およびアンダースコアですが、 これは ASCII フラグを使って変更できます。 LOCALE フラグが使われているなら単語の境界は現在のロケールによって決定されます。

\d

Unicode (str) パターンでは:

任意の Unicode 10 進数字 (Unicode 文字カテゴリ [Nd] [https://www.unicode.org/versions/Unicode15.0.0/ch04.pdf#G134153])にマッチします。これは [0-9] とその他多数の数字を含みます。

ASCII フラグを使用すると [0-9] にマッチします。

8 ビット (bytes) パターンでは:

任意のASCII文字の 10 進数字にマッチします。これは [0-9] と等価です。

\D

Matches any character which is not a decimal digit. This is the opposite of \d.

ASCII フラグを使用すると [^0-9] にマッチします。

\s

Unicode (str) パターンでは:

Unicode 空白文字 (これは [ \t\n\r\f\v] その他多くの文字、例えば多くの言語におけるタイポグラフィ規則で定義されたノーブレークスペースなどを含みます) にマッチします。

ASCII フラグを使用すると [ \t\n\r\f\v] にマッチします。

8 ビット (bytes) パターンでは:

ASCII 文字セットで空白文字と見なされる文字にマッチします。これは [ \t\n\r\f\v] と等価です。

\S

Matches any character which is not a whitespace character. This is the opposite of \s.

ASCII フラグを使用すると [^ \t\n\r\f\v] にマッチします。

\w

Unicode (str) パターンでは:

Matches Unicode word characters; this includes all Unicode alphanumeric characters (as defined by str.isalnum()), as well as the underscore (_).

ASCII フラグを使用すると [a-zA-Z0-9_] にマッチします。

8 ビット (bytes) パターンでは:

ASCII 文字セットで英数字と見なされる文字にマッチします。これは [a-zA-Z0-9_] と等価です。LOCALE フラグが使われているなら、現在のロケールで英数字と見なされる文字およびアンダースコアにマッチします。

\W

Matches any character which is not a word character. This is the opposite of \w. By default, matches non-underscore (_) characters for which str.isalnum() returns False.

ASCII フラグを使用すると [^a-zA-Z0-9_] にマッチします。

If the LOCALE flag is used, matches characters which are neither alphanumeric in the current locale nor the underscore.

\Z

文字列の末尾でのみマッチします。

Python 文字列リテラルでサポートされている エスケープシーケンス のほとんども正規表現パーザで受理されます:

\a      \b      \f      \n
\N      \r      \t      \u
\U      \v      \x      \\

(\b は単語の境界を表すのに使われ、文字クラス中でのみ "後退 (backspace)" 文字を意味することに注意してください。)

'\u'、'\U' および '\N' エスケープシーケンスは、Unicode (str)パターン内でのみ認識されます。バイト列ではエラーとなります。ASCII 文字のエスケープで未知のものは将来使うために予約されていて、エラーとして扱われます。

8 進エスケープは限られた形式でのみ含まれます。その最初の桁が 0 であるか、それが 3 桁の 8 進数であるならば、それは 8 進エスケープと見なされます。そうでなければ、それはグループ参照です。文字列リテラルでは、8 進エスケープは常にたかだか 3 桁長です。

バージョン 3.3 で変更: '\u' と '\U' エスケープシーケンスが追加されました。

バージョン 3.6 で変更: '\' と ASCII 文字からなる未知のエスケープはエラーになります。

バージョン 3.8 で変更: '\N{name}' エスケープシーケンスが追加されました。文字列リテラルでは、同名のUnicode 文字に展開されます。('\N{EM DASH}' など)

モジュールコンテンツ

このモジュールはいくつかの関数、定数、例外を定義します。このうちいくつかの関数は、コンパイル済み正規表現がそなえる完全な機能のメソッドを簡易にしたものです。些細なものを除くほとんどのアプリケーションは常にコンパイル済み形式を使います。

フラグ

バージョン 3.6 で変更: フラグ定数は、enum.IntFlag のサブクラスである RegexFlag のインスタンスになりました。

class re.RegexFlag

An enum.IntFlag class containing the regex options listed below.

Added in version 3.11: - added to __all__

re.A

re.ASCII

\w、\W、\b、\B、\d、\D、\s、および \S において、ASCII 文字のみでマッチングを行います。これは Unicode(str) パターンでのみ意味があり、バイト列パターンでは無視されます。

インラインフラグの (?a) に相当します。

注釈

The U flag still exists for backward compatibility, but is redundant in Python 3 since matches are Unicode by default for str patterns, and Unicode matching isn't allowed for bytes patterns. UNICODE and the inline flag (?u) are similarly redundant.

re.DEBUG

コンパイルした表現に関するデバッグ情報を出力します。

対応するインラインフラグはありません。

re.I

re.IGNORECASE

Perform case-insensitive matching; expressions like [A-Z] will also match lowercase letters. Full Unicode matching (such as Ü matching ü) also works unless the ASCII flag is used to disable non-ASCII matches. The current locale does not change the effect of this flag unless the LOCALE flag is also used.

インラインフラグの (?i) に相当します。

Unicode パターン [a-z] または [A-Z] が IGNORECASE フラグとあわせて使われたとき、52 の ASCII 文字に加えて 4 の非 ASCII 文字 'İ' (U+0130, Latin capital letter I with dot above) 、 'ı' (U+0131, Latin small letter dotless i) 、 'ſ' (U+017F, Latin small letter long s) および 'K' (U+212A, Kelvin sign) にマッチすることに注意してください。 ASCII フラグが使われているなら、文字 'a' から 'z' および 'A' から 'Z' にのみマッチします。

re.L

re.LOCALE

Make \w, \W, \b, \B and case-insensitive matching dependent on the current locale. This flag can be used only with bytes patterns.

インラインフラグの (?L) に相当します。

警告

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.

バージョン 3.6 で変更: LOCALE はバイト列パターンにのみ使え、ASCII と互換ではありません。

バージョン 3.7 で変更: LOCALE フラグがあるコンパイル済み正規表現オブジェクトはコンパイル時のロケールに依存しなくなりました。マッチング時のロケールのみがマッチングの結果に影響します。

re.M

re.MULTILINE

指定されると、パターン文字 '^' は、文字列の先頭および各行の先頭(各改行の直後)とマッチします；そしてパターン文字 '$' は文字列の末尾および各行の末尾 (改行の直前) とマッチします。デフォルトでは、 '^' は、文字列の先頭とだけマッチし、 '$' は、文字列の末尾および文字列の末尾の改行の直前(がもしあれば)とマッチします。

インラインフラグの (?m) に相当します。

re.NOFLAG

Indicates no flag being applied, the value is 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:

def myfunc(text, flag=re.NOFLAG):
    return re.match(text, flag)

Added in version 3.11.

re.S

re.DOTALL

特殊文字 '.' を、改行を含む任意の文字と、とにかくマッチさせます；このフラグがなければ、 '.' は、改行 以外の 任意の文字とマッチします。

インラインフラグの (?s) に相当します。

re.U

re.UNICODE

In Python 3, Unicode characters are matched by default for str patterns. This flag is therefore redundant with no effect and is only kept for backward compatibility.

See ASCII to restrict matching to ASCII characters instead.

re.X

re.VERBOSE

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 *?, (?: or (?P<...>. For example, (? : and * ? are not allowed. When a line contains a # that is not in a character class and is not preceded by an unescaped backslash, all characters from the leftmost such # through the end of the line are ignored.

つまり、10 進数字にマッチする下記のふたつの正規表現オブジェクトは、機能的に等価です:

a = re.compile(r"""\d +  # the integral part
                   \.    # the decimal point
                   \d *  # some fractional digits""", re.X)
b = re.compile(r"\d+\.\d*")

インラインフラグの (?x) に相当します。

関数

re.compile(pattern, flags=0)

正規表現パターンを 正規表現オブジェクト にコンパイルし、以下に述べる match() 、 search() その他のメソッドを使ってマッチングに使えるようにします。

The expression's behaviour can be modified by specifying a flags value. Values can be any of the flags variables, combined using bitwise OR (the | operator).

シーケンス

prog = re.compile(pattern)
result = prog.match(string)

は、以下と同等です

result = re.match(pattern, string)

が、 re.compile() を使い、結果の正規表現オブジェクトを保存して再利用するほうが、一つのプログラムでその表現を何回も使うときに効率的です。

注釈

re.compile() やモジュールレベルのマッチング関数に渡された最新のパターンはコンパイル済みのものがキャッシュされるので、一度に正規表現を少ししか使わないプログラムでは正規表現をコンパイルする必要はありません。

re.search(pattern, string, flags=0)

string 全体を走査して、正規表現 pattern がマッチを発生する最初の位置を探して、対応する Match を返します。もし文字列内に、そのパターンとマッチする位置がないならば、 None を返します；これは、文字列内のある点で長さゼロのマッチを探すこととは異なることに注意して下さい。

re.match(pattern, string, flags=0)

もし string の先頭で 0 個以上の文字が正規表現 pattern とマッチすれば、対応する Match を返します。もし文字列がパターンとマッチしなければ、 None を返します；これは長さゼロのマッチとは異なることに注意して下さい。

MULTILINE モードにおいても、re.match() は各行の先頭でマッチするのではなく、文字列の先頭でのみマッチすることに注意してください。

string 中のどこででもマッチさせたいなら、代わりに search() を使ってください (search() vs. match() も参照してください)。

re.fullmatch(pattern, string, flags=0)

string 全体が正規表現 pattern にマッチするなら、対応する Match を返します。文字列がパターンにマッチしないなら None を返します。これは長さ 0 のマッチとは異なることに注意して下さい。

Added in version 3.4.

re.split(pattern, string, maxsplit=0, flags=0)

string を、出現した pattern で分割します。 pattern 中でキャプチャの丸括弧が使われていれば、パターン中の全てのグループのテキストも結果のリストの一部として返されます。maxsplit が 0 でなければ、分割は最大 maxsplit 回起こり、残りの文字列はリストの最終要素として返されます。

>>> re.split(r'\W+', 'Words, words, words.')
['Words', 'words', 'words', '']
>>> re.split(r'(\W+)', 'Words, words, words.')
['Words', ', ', 'words', ', ', 'words', '.', '']
>>> re.split(r'\W+', 'Words, words, words.', 1)
['Words', 'words, words.']
>>> re.split('[a-f]+', '0a3B9', flags=re.IGNORECASE)
['0', '3', '9']

セパレータ中にキャプチャグループがあり、それが文字列の先頭にマッチするなら、結果は空文字列で始まります。同じことが文字列の末尾にも言えます。

>>> re.split(r'(\W+)', '...words, words...')
['', '...', 'words', ', ', 'words', '...', '']

そうして、結果のリストにおいて、セパレータの構成要素は常に同じ相対的インデックスに見つかります。

パターンへの空マッチは、直前の空マッチに隣接していないときのみ文字列を分割します。

>>> re.split(r'\b', 'Words, words, words.')
['', 'Words', ', ', 'words', ', ', 'words', '.']
>>> re.split(r'\W*', '...words...')
['', '', 'w', 'o', 'r', 'd', 's', '', '']
>>> re.split(r'(\W*)', '...words...')
['', '...', '', '', 'w', '', 'o', '', 'r', '', 'd', '', 's', '...', '', '', '']

バージョン 3.1 で変更: オプションの flags 引数が追加されました。

バージョン 3.7 で変更: 空文字列にマッチしうるパターンでの分割をサポートするようになりました。

re.findall(pattern, string, flags=0)

Return all non-overlapping matches of pattern in string, as a list of strings or tuples. The string is scanned left-to-right, and matches are returned in the order found. Empty matches are included in the result.

The result depends on the number of capturing groups in the pattern. If there are no groups, return a list of strings matching the whole pattern. If there is exactly one group, return a list of strings matching that group. If multiple groups are present, return a list of tuples of strings matching the groups. Non-capturing groups do not affect the form of the result.

>>> 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')]

バージョン 3.7 で変更: 空でないマッチが前の空マッチの直後から始められるようになりました。

re.finditer(pattern, string, flags=0)

string 中の正規表現 pattern の重複しないマッチ全てに渡る Match オブジェクトを yield する イテレータ を返します。 string は左から右へ走査され、マッチは見つかった順で返されます。空マッチは結果に含まれます。

バージョン 3.7 で変更: 空でないマッチが前の空マッチの直後から始められるようになりました。

re.sub(pattern, repl, string, count=0, flags=0)

string 中に出現する最も左の重複しない pattern を置換 repl で置換することで得られる文字列を返します。パターンが見つからない場合、 string がそのまま返されます。 repl は文字列または関数です。 repl が文字列の場合は、その中の全てのバックスラッシュエスケープが処理されます。 \n は 1 つの改行文字に変換され、 \r はキャリッジリターンに変換される、などです。 ASCII 文字のエスケープで未知のものは将来使うために予約されていて、エラーとして扱われます。それ以外の \& のような未知のエスケープは残されます。 \6 のような後方参照は、パターンのグループ 6 がマッチした部分文字列で置換されます。例えば:

>>> 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{'

もし repl が関数であれば、重複しない pattern が発生するたびにその関数が呼ばれます。この関数は一つの Match 引数を取り、置換文字列を返します。例えば:

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

パターンは、文字列でも Pattern でも構いません。

オプション引数 count は出現したパターンを置換する最大の回数です。 count は非負整数です。省略されるか 0 なら、出現した全てが置換されます。パターンへの空マッチは前の空マッチに隣接していないときのみ置換されるので、 sub('x*', '-', 'abxd') は '-a-b--d-' を返します。

文字列型 repl 引数では、上で述べた文字エスケープや後方参照に加えて、 \g<name> は (?P<name>...) 構文で定義された name という名前のグループがマッチした部分文字列を使い、 \g<number> は対応するグループ番号を使います。よって \g<2> は \2 と等価ですが、 \g<2>0 のような置換においても曖昧になりません。 \20 は、グループ 20 への参照として解釈され、グループ 2 への参照にリテラル文字 '0' が続いたものとしては解釈されません。後方参照 \g<0> は正規表現とマッチした部分文字列全体で置き換わります。

バージョン 3.1 で変更: オプションの flags 引数が追加されました。

バージョン 3.5 で変更: マッチしなかったグループは空文字列に置き換えられます。

バージョン 3.6 で変更: pattern 中に '\' と ASCII 文字からなる未知のエスケープがあると、エラーになります。

バージョン 3.7 で変更: Unknown escapes in repl consisting of '\' and an ASCII letter now are errors.

バージョン 3.7 で変更: Empty matches for the pattern are replaced when adjacent to a previous non-empty match.

バージョン 3.12 で変更: Group id can only contain ASCII digits. In bytes replacement strings, group name can only contain bytes in the ASCII range (b'\x00'-b'\x7f').

re.subn(pattern, repl, string, count=0, flags=0)

sub() と同じ操作を行いますが、タプル (new_string、 number_of_subs_made) を返します。

バージョン 3.1 で変更: オプションの flags 引数が追加されました。

バージョン 3.5 で変更: マッチしなかったグループは空文字列に置き換えられます。

re.escape(pattern)

pattern 中の特殊文字をエスケープします。これは正規表現メタ文字を含みうる任意のリテラル文字列にマッチしたい時に便利です。

>>> 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))))
/|\-|\+|\*\*|\*

この関数は、バックスラッシュのみをエスケープするべき sub() および subn() における置換文字列に使われてはなりません。例えば:

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

バージョン 3.3 で変更: '_' 文字がエスケープされなくなりました。

バージョン 3.7 で変更: 正規表現で特別な意味を持つ文字だけがエスケープされます。結果として、 '!'、 '"'、 '%'、 "'"、 ','、 '/'、 ':'、 ';'、 '<'、 '='、 '>'、 '@'、 と "`" はもはやエスケープされません。

re.purge()

正規表現キャッシュをクリアします。

例外

exception re.error(msg, pattern=None, pos=None)

Exception raised when a string passed to one of the functions here is not a valid regular expression (for example, it might contain unmatched parentheses) or when some other error occurs during compilation or matching. It is never an error if a string contains no match for a pattern. The error instance has the following additional attributes:

msg

フォーマットされていないエラーメッセージです。

pattern

正規表現のパターンです。

pos

pattern のコンパイルに失敗した場所のインデックスです (None の場合もあります)。

lineno

pos に対応する行です (None の場合もあります)。

colno

pos に対応する列です (None の場合もあります)。

バージョン 3.5 で変更: 追加の属性が追加されました。

正規表現オブジェクト

class re.Pattern

Compiled regular expression object returned by re.compile().

バージョン 3.9 で変更: re.Pattern supports [] to indicate a Unicode (str) or bytes pattern. See ジェネリックエイリアス型.

Pattern.search(string[, pos[, endpos]])

string 全体を走査して、この正規表現がマッチを発生する最初の位置を探して、対応する Match を返します。もし文字列内に、そのパターンとマッチする位置がないならば、 None を返します；これは、文字列内のある点で長さゼロのマッチを探すこととは異なることに注意して下さい。

オプションの第二引数 pos は、文字列のどこから探し始めるかを指定するインデックスで、デフォルトでは 0 です。これは文字列のスライスと完全には同じではありません。パターン文字 '^' は本当の文字列の先頭と改行の直後でマッチしますが、検索を開始するインデックスでマッチするとは限りません。

オプションの引数 endpos は文字列がどこまで検索されるかを制限します。文字列の長さが endpos 文字だったかのようになるので、pos から endpos - 1 の文字に対してだけマッチを探します。endpos が pos よりも小さいと、マッチは見つかりません。そうでなければ、rx をコンパイル済み正規表現オブジェクトとして、rx.search(string, 0, 50) は rx.search(string[:50], 0) と等価です。

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

Pattern.match(string[, pos[, endpos]])

もし string の先頭で 0 個以上の文字がこの正規表現とマッチすれば、対応する Match を返します。もし文字列がパターンとマッチしなければ、 None を返します；これは長さゼロのマッチとは異なることに注意して下さい。

オプションの pos および endpos 引数は search() メソッドのものと同じ意味です。

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

string 中のどこででもマッチさせたいなら、代わりに search() を使ってください (search() vs. match() も参照してください)。

Pattern.fullmatch(string[, pos[, endpos]])

string 全体がこの正規表現にマッチするなら、対応する Match を返します。文字列がパターンにマッチしないなら None を返します。これは長さ 0 のマッチとは異なることに注意して下さい。

オプションの pos および endpos 引数は search() メソッドのものと同じ意味です。

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

Added in version 3.4.

Pattern.split(string, maxsplit=0)

split() 関数にこのコンパイル済みパターンを使うのと同じです。

Pattern.findall(string[, pos[, endpos]])

findall() 関数にこのコンパイル済みパターンを使うのと似ていますが、オプションの pos および endpos 引数で search() のように検索範囲を制限できます。

Pattern.finditer(string[, pos[, endpos]])

finditer() 関数にこのコンパイル済みパターンを使うのと似ていますが、オプションの pos および endpos 引数で search() のように検索範囲を制限できます。

Pattern.sub(repl, string, count=0)

sub() 関数にこのコンパイル済みパターンを使うのと同じです。

Pattern.subn(repl, string, count=0)

subn() 関数にこのコンパイル済みパターンを使うのと同じです。

Pattern.flags

正規表現のマッチングフラグです。これは compile() に与えられたフラグ、パターン中の (?...) インラインフラグ、およびパターンが Unicode 文字列だった時の UNICODE のような暗黙のフラグの組み合わせです。

Pattern.groups

パターン中のキャプチャグループの数です。

Pattern.groupindex

(?P<id>) で定義されたあらゆるシンボリックグループ名をグループ番号へ写像する辞書です。シンボリックグループがパターン中で全く使われていなければ、この辞書は空です。

Pattern.pattern

パターンオブジェクトがコンパイルされた元のパターン文字列です。

バージョン 3.7 で変更: copy.copy() および copy.deepcopy() をサポートするようになりました。コンパイル済み正規表現オブジェクトはアトミックであると見なされます。

マッチオブジェクト

マッチオブジェクトのブール値は常に True です。 match() および search() はマッチがないとき None を返すので、マッチがあるか単純な if 文で判定できます。

match = re.search(pattern, string)
if match:
    process(match)

class re.Match

Match object returned by successful matches and searches.

バージョン 3.9 で変更: re.Match supports [] to indicate a Unicode (str) or bytes match. See ジェネリックエイリアス型.

Match.expand(template)

Return the string obtained by doing backslash substitution on the template string template, as done by the sub() method. Escapes such as \n are converted to the appropriate characters, and numeric backreferences (\1, \2) and named backreferences (\g<1>, \g<name>) are replaced by the contents of the corresponding group. The backreference \g<0> will be replaced by the entire match.

バージョン 3.5 で変更: マッチしなかったグループは空文字列に置き換えられます。

Match.group([group1, ...])

このマッチの 1 つ以上のサブグループを返します。引数が 1 つなら結果は 1 つの文字列です。複数の引数があれば、結果は引数ごとに 1 項目のタプルです。引数がなければ、 group1 はデフォルトで 0 (マッチ全体が返される) です。 groupN 引数が 0 なら、対応する返り値はマッチした文字列全体です。1 以上 99 以下なら、丸括弧による対応するグループにマッチする文字列です。グループ番号が負であるかパターン中で定義されたグループの数より大きければ、 IndexError 例外が送出されます。あるグループがパターンのマッチしなかった部分に含まれているなら、対応する結果は None です。あるグループがパターンの複数回マッチした部分に含まれているなら、最後のマッチが返されます。

>>> 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')

正規表現が (?P<name>...) 構文を使うなら、 groupN 引数はグループ名でグループを識別する文字列でも構いません。文字列引数がパターン中でグループ名として使われていなければ、 IndexError 例外が送出されます。

やや複雑な例:

>>> m = re.match(r"(?P<first_name>\w+) (?P<last_name>\w+)", "Malcolm Reynolds")
>>> m.group('first_name')
'Malcolm'
>>> m.group('last_name')
'Reynolds'

名前付きグループはインデックスでも参照できます:

>>> m.group(1)
'Malcolm'
>>> m.group(2)
'Reynolds'

あるグループが複数回マッチすると、その最後のマッチにのみアクセスできます:

>>> m = re.match(r"(..)+", "a1b2c3")  # Matches 3 times.
>>> m.group(1)                        # Returns only the last match.
'c3'

Match.__getitem__(g)

これは m.group(g) と同等です。これでマッチの個別のグループに簡単にアクセスできます:

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

Named groups are supported as well:

>>> m = re.match(r"(?P<first_name>\w+) (?P<last_name>\w+)", "Isaac Newton")
>>> m['first_name']
'Isaac'
>>> m['last_name']
'Newton'

Added in version 3.6.

Match.groups(default=None)

このマッチの、1 からパターン中のグループ数まで、全てのサブグループを含むタプルを返します。default 引数はマッチに関係しなかったグループに使われます。デフォルトでは None です。

例えば:

>>> m = re.match(r"(\d+)\.(\d+)", "24.1632")
>>> m.groups()
('24', '1632')

少数位およびその後の全てをオプションにすると、全てのグループがマッチに関係するとは限りません。そういったグループは default 引数が与えられない限りデフォルトで None になります。

>>> 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')

Match.groupdict(default=None)

このマッチの、全ての 名前付き サブグループを含む、サブグループ名をキーとする辞書を返します。 default 引数はマッチに関係しなかったグループに使われます。デフォルトは None です。例えば:

>>> m = re.match(r"(?P<first_name>\w+) (?P<last_name>\w+)", "Malcolm Reynolds")
>>> m.groupdict()
{'first_name': 'Malcolm', 'last_name': 'Reynolds'}

Match.start([group])

Match.end([group])

group がマッチした部分文字列の先頭と末尾のインデックスを返します。 group はデフォルトで 0 (マッチした部分文字列全体という意味) です。 group が存在してかつマッチには寄与していなかったなら -1 を返します。マッチオブジェクト m と、マッチに寄与したグループ g に対して、グループ g がマッチした部分文字列 (m.group(g) と等価です) は以下の通りです

m.string[m.start(g):m.end(g)]

group が空文字列にマッチしていたら m.start(group) は m.end(group) と等しくなることに注意して下さい。例えば、 m = re.search('b(c?)', 'cba') とすると、 m.start(0) は 1 で、 m.end(0) は 2 で、 m.start(1) と m.end(1) はともに 2 であり、 m.start(2) は IndexError 例外を発生します。

メールアドレスから remove_this を取り除く例:

>>> email = "tony@tiremove_thisger.net"
>>> m = re.search("remove_this", email)
>>> email[:m.start()] + email[m.end():]
'tony@tiger.net'

Match.span([group])

マッチ m について、2 タプル (m.start(group), m.end(group)) を返します。 group がマッチに寄与していなければ、これは (-1, -1) です。 group はデフォルトで 0 、マッチ全体です。

Match.pos

正規表現オブジェクト の search() や match() に渡された pos の値です。これは正規表現エンジンがマッチを探し始める位置の文字列のインデックスです。

Match.endpos

正規表現オブジェクト の search() や match() に渡された endpos の値です。これは正規表現エンジンがそれ以上は進まない文字列のインデックスです。

Match.lastindex

最後にマッチしたキャプチャグループの整数インデックスです。どのグループも全くマッチしなければ None です。例えば、表現 (a)b 、 ((a)(b)) や ((ab)) が 'ab' に適用されると lastindex == 1 となり、同じ文字列に (a)(b) が適用されると lastindex == 2 となります。

Match.lastgroup

最後にマッチしたキャプチャグループの名前です。そのグループに名前がないか、どのグループも全くマッチしていなければ None です。

Match.re

このマッチインスタンスを生じさせた match() または search() メソッドの属する 正規表現オブジェクト です。

Match.string

match() や search() へ渡された文字列です。

バージョン 3.7 で変更: copy.copy() および copy.deepcopy() をサポートするようになりました。マッチオブジェクトはアトミックであると見なされます。

正規表現の例

ペアの確認

この例では、マッチオブジェクトをより美しく表示するために、この補助関数を使用します:

def displaymatch(match):
    if match is None:
        return None
    return '<Match: %r, groups=%r>' % (match.group(), match.groups())

あなたがポーカープログラムを書いているとします。プレイヤーの手札は 5 文字の文字列によって表され、それぞれの文字が 1 枚のカードを表します。 "a" はエース、 "k" はキング、 "q" はクイーン、 "j" はジャック、 "t" は 10、そして "2" から "9" はその数字のカードを表します。

与えられた文字列が有効な手札であるか見るには、以下のようにできます:

>>> 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=()>"

最後の手札、 "727ak" 、はペア、すなわち同じ値の 2 枚のカードを含みます。正規表現でこれにマッチするには、このように後方参照を使えます:

>>> 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',)>"

ペアになっているのがどのカードか調べるには、このようにマッチオブジェクトの group() メソッドを使えます:

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

scanf() をシミュレートする

Python には現在のところ、 scanf() に相当するものがありません。正規表現は一般的に、 scanf() のフォーマット文字列より強力ですが、冗長でもあります。以下の表に、 scanf() のフォーマットトークンと正規表現のおおよその対応付けを示します。

scanf() トークン

正規表現

%c

.

%5c

.{5}

%d

[-+]?\d+

%e, %E, %f, %g

[-+]?(\d+(\.\d*)?|\.\d+)([eE][-+]?\d+)?

%i

[-+]?(0[xX][\dA-Fa-f]+|0[0-7]*|\d+)

%o

[-+]?[0-7]+

%s

\S+

%u

\d+

%x, %X

[-+]?(0[xX])?[\dA-Fa-f]+

以下のような文字列からファイル名と数を抽出するには

/usr/sbin/sendmail - 0 errors, 4 warnings

以下のように scanf() フォーマットを使えます

%s - %d errors, %d warnings

等価な正規表現はこうです

(\S+) - (\d+) errors, (\d+) warnings

search() vs. match()

Python offers different primitive operations based on regular expressions:

re.match() checks for a match only at the beginning of the string

re.search() checks for a match anywhere in the string (this is what Perl does by default)

re.fullmatch() checks for entire string to be a match

例えば:

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

'^' で始まる正規表現を search() で使って、マッチを文字列の先頭でのみに制限できます:

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

ただし、 MULTILINE モードにおいて match() は文字列の先頭でのみマッチし、 '^' で始まる正規表現で search() を使うと各行の先頭でマッチすることに注意してください。

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

電話帳を作る

split() は渡されたパターンで文字列を分割してリストにします。このメソッドは、テキストデータをデータ構造に変換して、読みやすくしたり、以下の例で実演する電話帳作成のように Python で編集したりしやすくするのに、非常に役に立ちます。

最初に、入力を示します。通常、これはファイルからの入力になるでしょう。ここでは、3重引用符の書式とします。

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

各項目は 1 つ以上の改行で区切られています。まずは文字列を変換して、空行でない各行を項目とするリストにします:

>>> 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']

そして各項目を、ファーストネーム、ラストネーム、電話番号、住所に分割してリストにします。分割パターンである空白文字は住所にも含まれるので、 split() の maxsplit 引数を使います:

>>> [re.split(":? ", entry, 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']]

この :? パターンはラストネームの次のコロンにマッチして、分割結果のリストに出てこないようにします。 maxsplit を 4 にすれば、家屋番号とストリート名を分割できます:

>>> [re.split(":? ", entry, 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']]

テキストの秘匿

sub() は出現する各パターンを文字列で、または関数の返り値で置き換えます。この例ではテキストを「秘匿」する関数と合わせて sub() を使うところを実演します。具体的には、文中の各単語について、最初と最後の文字を除く全ての文字をランダムに並び替えます:

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

全ての副詞を見つける

search() は最初のパターンにのみマッチしますが、 findall() は出現する 全ての パターンにマッチします。例えば、ライターがあるテキストの全ての副詞を見つけたいなら、以下のように findall() を使えます:

>>> text = "He was carefully disguised but captured quickly by police."
>>> re.findall(r"\w+ly\b", text)
['carefully', 'quickly']

全ての副詞とその位置を見つける

パターンの全てのマッチについて、マッチしたテキスト以上の情報が必要なら、文字列ではなく Match を返す finditer() が便利です。先の例に続いて、ライターがあるテキストの全ての副詞 およびその位置 を見つけたいなら、以下のように finditer() を使えます:

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

Raw 文字列記法

Raw 文字列記法 (r"text") で正規表現をまともに保てます。それがなければ、正規表現中のバックスラッシュ ('\') を個々にバックスラッシュを前置してエスケープしなければなりません。例えば、以下の 2 行のコードは機能的に等価です:

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

リテラルのバックスラッシュにマッチさせたいなら、正規表現中ではエスケープする必要があります。Raw 文字列記法では、r"\\" になります。Raw 文字列記法を用いないと、"\\\\" としなくてはならず、以下のコードは機能的に等価です:

>>> re.match(r"\\", r"\\")
<re.Match object; span=(0, 1), match='\\'>
>>> re.match("\\\\", r"\\")
<re.Match object; span=(0, 1), match='\\'>

トークナイザを書く

トークナイザやスキャナ [https://en.wikipedia.org/wiki/Lexical_analysis] は文字列を解析し、文字のグループにカテゴリ分けします。これはコンパイラやインタプリタを書くうえで役立つ第一段階です。

テキストのカテゴリは正規表現で指定されます。この技法では、それらを一つのマスター正規表現に結合し、マッチの連続についてループします:

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 = '''
    IF quantity THEN
        total := total + price * quantity;
        tax := price * 0.05;
    ENDIF;
'''

for token in tokenize(statements):
    print(token)

このトークナイザは以下の出力を作成します:

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)

[Frie09]

Friedl, Jeffrey. Mastering Regular Expressions. 3rd ed., O'Reilly Media, 2009. 当書の第三版ではもはや Python についてまったく取り扱っていませんが、初版では良い正規表現を書くことを綿密に取り扱っていました。

difflib --- Helpers for computing deltas

ソースコード: Lib/difflib.py [https://github.com/python/cpython/tree/3.12/Lib/difflib.py]

このモジュールは、シーケンスを比較するためのクラスや関数を提供しています。例えば、ファイルの差分を計算して、それを HTML や context diff, unified diff などいろいろなフォーマットで出力するために、このモジュールを利用できます。ディレクトリやファイル群を比較するためには、 filecmp モジュールも参照してください。

class difflib.SequenceMatcher

柔軟性のあるクラスで、二つのシーケンスの要素が ハッシュ可能 な型であれば、どの型の要素を含むシーケンスも比較可能です。基本的なアルゴリズムは、1980年代の後半に発表された Ratcliff と Obershelp による"ゲシュタルトパターンマッチング"と大げさに名づけられたアルゴリズム以前から知られている、やや凝ったアルゴリズムです。その考え方は、"junk" 要素を含まない最も長い互いに隣接したマッチ列を探すことです。ここで、 "junk" 要素とは、空行や空白などの、意味を持たない要素のことです。 (junk を処理するのは、Ratcliff と Obershelp のアルゴリズムに追加された拡張です。)この考え方は、マッチ列の左右に隣接するシーケンスの断片に対して再帰的にあてはめられます。この方法では編集を最小にするシーケンスは生まれませんが、人間の目からみて「正しい感じ」にマッチする傾向があります。

実行時間: 基本的な Ratcliff-Obershelp アルゴリズムは、最悪の場合3乗、期待値で2乗となります。 SequenceMatcher オブジェクトでは、最悪のケースで2乗、期待値は比較されるシーケンス中に共通に現れる要素数に非常にややこしく依存しています。最良の場合は線形時間になります。

自動 junk ヒューリスティック: SequenceMatcher は、シーケンスの特定の要素を自動的に junk として扱うヒューリスティックをサポートしています。このヒューリスティックは、各個要素がシーケンス内に何回現れるかを数えます。ある要素の重複数が (最初のものは除いて) 合計でシーケンスの 1% 以上になり、そのシーケンスが 200 要素以上なら、その要素は "popular" であるものとしてマークされ、シーケンスのマッチングの目的からは junk として扱われます。このヒューリスティックは、 SequenceMatcher の作成時に autojunk パラメタを False に設定することで無効化できます。

バージョン 3.2 で変更: Added the autojunk parameter.

class difflib.Differ

テキスト行からなるシーケンスを比較するクラスです。人が読むことのできる差分を作成します。 Differ クラスは SequenceMatcher クラスを利用して、行からなるシーケンスを比較したり、(ほぼ)同一の行内の文字を比較したりします。

Differ クラスによる差分の各行は、2文字のコードで始まります:

コード

意味

'- '

行はシーケンス1にのみ存在する

'+ '

行はシーケンス2にのみ存在する

'  '

行は両方のシーケンスで同一

'? '

行は入力シーケンスのどちらにも存在しない

Lines beginning with '?' 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.

class difflib.HtmlDiff

このクラスは、二つのテキストを左右に並べて比較表示し、行間あるいは行内の変更点を強調表示するような HTML テーブル (またはテーブルの入った完全な HTML ファイル) を生成するために使います。テーブルは完全差分モード、コンテキスト差分モードのいずれでも生成できます。

このクラスのコンストラクタは以下のようになっています:

__init__(tabsize=8, wrapcolumn=None, linejunk=None, charjunk=IS_CHARACTER_JUNK)

HtmlDiff のインスタンスを初期化します。

tabsize はオプションのキーワード引数で、タブストップ幅を指定します。デフォルトは 8 です。

wrapcolumn はオプションのキーワード引数で、テキストを折り返すカラム幅を指定します。デフォルトは None で折り返しを行いません。

linejunk および charjunk はオプションのキーワード引数で、 ndiff() (HtmlDiff はこの関数を使って左右のテキストの差分を HTML で生成します) に渡されます。それぞれの引数のデフォルト値および説明は ndiff() のドキュメントを参照してください。

以下のメソッドが public になっています:

make_file(fromlines, tolines, fromdesc='', todesc='', context=False, numlines=5, *, charset='utf-8')

fromlines と tolines (いずれも文字列のリスト) を比較し、行間または行内の変更点が強調表示された行差分の入った表を持つ完全な HTML ファイルを文字列で返します。

fromdesc および todesc はオプションのキーワード引数で、差分表示テーブルにおけるそれぞれ差分元、差分先ファイルのカラムのヘッダになる文字列を指定します (いずれもデフォルト値は空文字列です)。

context および numlines はともにオプションのキーワード引数です。context を True にするとコンテキスト差分を表示し、デフォルトの False にすると完全なファイル差分を表示します。numlines のデフォルト値は 5 で、context が True の場合、numlines は強調部分の前後にあるコンテキスト行の数を制御します。context が False の場合、numlines は "next" と書かれたハイパーリンクをたどった時に到達する場所が次の変更部分より何行前にあるかを制御します (値をゼロにした場合、"next" ハイパーリンクを辿ると変更部分の強調表示がブラウザの最上部に表示されるようになります)。

注釈

fromdesc と todesc はエスケープされていないHTMLとして解釈されます。信頼できないソースからの入力を受け取る際には適切にエスケープされるべきです。

バージョン 3.5 で変更: charset キーワード専用引数が追加されました。HTML 文書のデフォルトの文字集合が 'ISO-8859-1' から 'utf-8' に変更されました。

make_table(fromlines, tolines, fromdesc='', todesc='', context=False, numlines=5)

fromlines と tolines (いずれも文字列のリスト) を比較し、行間または行内の変更点が強調表示された行差分の入った完全な HTML テーブルを文字列で返します。

このメソッドの引数は、 make_file() メソッドの引数と同じです。

difflib.context_diff(a, b, fromfile='', tofile='', fromfiledate='', tofiledate='', n=3, lineterm='\n')

a と b (文字列のリスト) を比較し、差分 (差分形式の行を生成する ジェネレータ) を、 context diff のフォーマット(以下「コンテキスト形式」)で返します。

コンテキスト形式は、変更があった行に前後数行を加えてある、コンパクトな表現方法です。変更箇所は、変更前/変更後に分けて表します。コンテキスト (変更箇所前後の行) の行数は n で指定し、デフォルト値は 3 です。

デフォルトで、 diff 制御行 (*** や --- を含む行) は改行付きで生成されます。 io.IOBase.readlines() で作られた入力が io.IOBase.writelines() で扱うのに適した diff になるので (なぜなら入力と出力の両方が改行付きのため) 、これは有用です。

行末に改行文字を持たない入力に対しては、出力でも改行文字を付加しないように lineterm 引数に "" を渡してください。

コンテキスト形式は、通常、ヘッダにファイル名と変更時刻を持っています。この情報は、文字列 fromfile, tofile, fromfiledate, tofiledate で指定できます。変更時刻の書式は、通常、ISO 8601 フォーマットで表されます。指定しなかった場合のデフォルト値は、空文字列です。

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

より詳細な例は、 difflib のコマンドラインインターフェース を参照してください。

difflib.get_close_matches(word, possibilities, n=3, cutoff=0.6)

「十分」なマッチの上位のリストを返します。word はマッチさせたいシーケンス (大概は文字列) です。possibilities は word にマッチさせるシーケンスのリスト (大概は文字列のリスト) です。

オプションの引数 n (デフォルトでは 3)はメソッドの返すマッチの最大数です。n は 0 より大きくなければなりません。

オプションの引数 cutoff (デフォルトでは 0.6)は、区間 [0, 1] に入る小数の値です。word との一致率がそれ未満の possibilities の要素は無視されます。

possibilities の要素でマッチした上位(多くても n 個)は、類似度のスコアに応じて(一番似たものを先頭に)ソートされたリストとして返されます。

>>> 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']

difflib.ndiff(a, b, linejunk=None, charjunk=IS_CHARACTER_JUNK)

a と b (文字列のリスト) を比較し、差分 (差分形式の行を生成する ジェネレータ) を、 Differ のスタイルで返します。

オプションのキーワード引数 linejunk と charjunk には、フィルタ関数 (または None) を渡します。

linejunk: 文字列型の引数 1 つを受け取る関数です。文字列が junk の場合は真を、そうでない場合は偽を返します。デフォルトでは None です。モジュールレべルの関数 IS_LINE_JUNK() は、高々 1 つのシャープ記号('#')を除いて可視の文字を含まない行をフィルタリングするものです。しかし、下層にある SequenceMatcher クラスが、どの行が雑音となるほど頻繁に登場するかを動的に分析します。このクラスによる分析は、この関数を使用するよりも通常うまく動作します。

charjunk: 文字 (長さ1の文字列) を受け取る関数です。文字列が junk の場合は真を、そうでない場合は偽を返します。デフォルトでは、モジュールレべルの関数 IS_CHARACTER_JUNK() であり、これは空白文字類 (空白またはタブ、改行文字をこれに含めてはいけません) をフィルタして排除します。

>>> diff = ndiff('one\ntwo\nthree\n'.splitlines(keepends=True),
...              'ore\ntree\nemu\n'.splitlines(keepends=True))
>>> print(''.join(diff), end="")
- one
?  ^
+ ore
?  ^
- two
- three
?  -
+ tree
+ emu

difflib.restore(sequence, which)

差分を生成した元の二つのシーケンスのうち一つを返します。

Differ.compare() または ndiff() によって生成された sequence を与えられると、行頭のプレフィクスを取りのぞいてファイル 1 または 2 (引数 which で指定される) に由来する行を復元します。

例:

>>> 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(''.join(restore(diff, 1)), end="")
one
two
three
>>> print(''.join(restore(diff, 2)), end="")
ore
tree
emu

difflib.unified_diff(a, b, fromfile='', tofile='', fromfiledate='', tofiledate='', n=3, lineterm='\n')

a と b (文字列のリスト) を比較し、差分 (差分形式の行を生成する ジェネレータ) を、 unified diff フォーマット(以下「ユニファイド形式」)で返します。

ユニファイド形式は変更があった行にコンテキストとなる前後数行を加えた、コンパクトな表現方法です。変更箇所は (変更前/変更後を分離したブロックではなく) インラインスタイルで表されます。コンテキストの行数は、n で指定し、デフォルト値は 3 です。

デフォルトで、 diff 制御行 (---, +++, @@ を含む行) は改行付きで生成されます。 io.IOBase.readlines() で作られた入力が io.IOBase.writelines() で扱うのに適した diff になるので (なぜなら入力と出力の両方が改行付きのため) 、これは有用です。

行末に改行文字を持たない入力に対しては、出力でも改行文字を付加しないように lineterm 引数に "" を渡してください。

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.

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

より詳細な例は、 difflib のコマンドラインインターフェース を参照してください。

difflib.diff_bytes(dfunc, a, b, fromfile=b'', tofile=b'', fromfiledate=b'', tofiledate=b'', n=3, lineterm=b'\n')

dfunc を使用して a と b (bytes オブジェクトのリスト) を比較して、差分形式の行 (これも bytes オブジェクトです) を*dfunc* の戻り値の形式で返します。dfunc は、呼び出し可能である必要があります。一般に、これは unified_diff() または context_diff() です。

未知のエンコーディングまたは一貫性のないエンコーディングのデータ同士を比較できます。n 以外のすべての入力は、bytes オブジェクトである必要があります。n 以外のすべての入力を損失なく str に変換して、dfunc(a, b, fromfile, tofile, fromfiledate, tofiledate, n, lineterm) を呼び出すことにより動作します。dfunc の出力は、bytes 型に変換されます。これにより、受け取る差分形式の行のエンコーディングは、a と b の未知または一貫性のないエンコーディングと同一になります。

Added in version 3.5.

difflib.IS_LINE_JUNK(line)

無視できる行のとき True を返します。行 line は空白、または '#' ひとつのときに無視できます。それ以外のときには無視できません。古いバージョンでは ndiff() の引数 linejunk にデフォルトで使用されました。

difflib.IS_CHARACTER_JUNK(ch)

無視できる文字のとき True を返します。文字 ch が空白、またはタブ文字のときには無視できます。それ以外の時には無視できません。 ndiff() の引数 charjunk としてデフォルトで使用されます。

参考

Pattern Matching: The Gestalt Approach [https://www.drdobbs.com/database/pattern-matching-the-gestalt-approach/184407970]

John W. Ratcliff と D. E. Metzener による類似のアルゴリズムに関する議論。Dr. Dobb's Journal [https://www.drdobbs.com/] 1988年7月号掲載。

SequenceMatcherオブジェクト

SequenceMatcher クラスには、以下のようなコンストラクタがあります:

class difflib.SequenceMatcher(isjunk=None, a='', b='', autojunk=True)

オプションの引数 isjunk は、None (デフォルトの値です) にするか、単一の引数をとる関数でなければなりません。後者の場合、関数はシーケンスの要素を受け取り、要素が junk であり、無視すべきである場合に限り真を返すようにしなければなりません。isjunk に None を渡すと、lambda x: False を渡したのと同じになります; すなわち、いかなる要素も無視しなくなります。例えば以下のような引数を渡すと:

lambda x: x in " \t"

空白とタブ文字を無視して文字のシーケンスを比較します。

オプションの引数 a と b は、比較される文字列で、デフォルトでは空の文字列です。両方のシーケンスの要素は、 ハッシュ可能 である必要があります。

オプションの引数 autojunk は、自動 junk ヒューリスティックを無効にするために使えます。

バージョン 3.2 で変更: Added the autojunk parameter.

SequenceMatcher オブジェクトは3つのデータ属性を持っています: bjunk は、 isjunk が True であるような b の要素の集合です; bpopular は、 (無効でなければ) ヒューリスティックによって popular であると考えられる非ジャンク要素の集合です; b2j は、 b の残りの要素をそれらが生じる位置のリストに写像する dict です。この 3 つは set_seqs() または set_seq2() で b がリセットされる場合は常にリセットされます。

Added in version 3.2: bjunk および bpopular 属性。

SequenceMatcher オブジェクトは以下のメソッドを持ちます:

set_seqs(a, b)

比較される2つの文字列を設定します。

SequenceMatcher オブジェクトは、2つ目のシーケンスについての詳細な情報を計算し、キャッシュします。 1つのシーケンスをいくつものシーケンスと比較する場合、まず set_seq2() を使って文字列を設定しておき、別の文字列を1つずつ比較するために、繰り返し set_seq1() を呼び出します。

set_seq1(a)

比較を行う1つ目のシーケンスを設定します。比較される2つ目のシーケンスは変更されません。

set_seq2(b)

比較を行う2つ目のシーケンスを設定します。比較される1つ目のシーケンスは変更されません。

find_longest_match(alo=0, ahi=None, blo=0, bhi=None)

a[alo:ahi] と b[blo:bhi] の中から、最長のマッチ列を探します。

isjunk が省略されたか None の時、 find_longest_match() は a[i:i+k] が b[j:j+k] と等しいような (i, j, k) を返します。その値は alo <= i <= i+k <= ahi かつ blo <= j <= j+k <= bhi となります。 (i', j', k') でも、同じようになります。さらに k >= k', i <= i' が i == i', j <= j' でも同様です。言い換えると、いくつものマッチ列すべてのうち、 a 内で最初に始まるものを返します。そしてその a 内で最初のマッチ列すべてのうち b 内で最初に始まるものを返します。

>>> s = SequenceMatcher(None, " abcd", "abcd abcd")
>>> s.find_longest_match(0, 5, 0, 9)
Match(a=0, b=4, size=5)

引数 isjunk が与えられている場合、上記の通り、はじめに最長のマッチ列を判定します。ブロック内に junk 要素が見当たらないような追加条件の際はこれに該当しません。次にそのマッチ列を、その両側の junk 要素にマッチするよう、できる限り広げていきます。そのため結果となる列は、探している列のたまたま直前にあった同一の junk 以外の junk にはマッチしません。

以下は前と同じサンプルですが、空白を junk とみなしています。これは ' abcd' が2つ目の列の末尾にある ' abcd' にマッチしないようにしています。代わりに 'abcd' にはマッチします。そして 2つ目の文字列中、一番左の 'abcd' にマッチします:

>>> s = SequenceMatcher(lambda x: x==" ", " abcd", "abcd abcd")
>>> s.find_longest_match(0, 5, 0, 9)
Match(a=1, b=0, size=4)

どんな列にもマッチしない時は、(alo, blo, 0) を返します。

このメソッドは named tuple Match(a, b, size) を返します。

バージョン 3.9 で変更: デフォルト引数が追加されました。

get_matching_blocks()

マッチした互いに重複の無いシーケンスを表す、3つ組の値のリストを返します。それぞれの値は (i, j, n) という形式で表され、a[i:i+n] == b[j:j+n] という関係を意味します。3つの値は i と j の間で単調に増加します。

最後の3つ組はダミーで、(len(a), len(b), 0) という値を持ちます。これは n == 0 である唯一のタプルです。もし (i, j, n) と (i', j', n') がリストで並んでいる3つ組で、2つ目が最後の3つ組でなければ、i+n < i' または j+n < j' です。言い換えると並んでいる3つ組は常に隣接していない同じブロックを表しています。

>>> 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)]

get_opcodes()

a を b にするための方法を記述する5つのタプルを返します。それぞれのタプルは (tag, i1, i2, j1, j2) という形式であらわされます。最初のタプルは i1 == j1 == 0 であり、i1 はその前にあるタプルの i2 と同じ値です。同様に j1 は前の j2 と同じ値になります。

tag の値は文字列であり、次のような意味です:

値

意味

'replace'

a[i1:i2] は b[j1:j2] に置き換えられる。

'delete'

a[i1:i2] は削除される。この時、j1 == j2 である。

'insert'

b[j1:j2] が a[i1:i1] に挿入される。この時 i1 == i2 である。

'equal'

a[i1:i2] == b[j1:j2] (サブシーケンスは等しい).

例えば:

>>> 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' --> ''
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]       '' --> 'f'

get_grouped_opcodes(n=3)

最大 n 行までのコンテキストを含むグループを生成するような、 ジェネレータ を返します。

このメソッドは、 get_opcodes() で返されるグループの中から、似たような差異のかたまりに分け、間に挟まっている変更の無い部分を省きます。

グループは get_opcodes() と同じ書式で返されます。

ratio()

[0, 1] の範囲の浮動小数点数で、シーケンスの類似度を測る値を返します。

T が2つのシーケンスの要素数の総計だと仮定し、M をマッチした数とすると、この値は 2.0*M / T であらわされます。もしシーケンスがまったく同じ場合、値は 1.0 となり、まったく異なる場合には 0.0 となります。

このメソッドは get_matching_blocks() または get_opcodes() がまだ呼び出されていない場合には非常にコストが高いです。この場合、上限を素早く計算するために、 quick_ratio() もしくは real_quick_ratio() を最初に試してみる方がいいかもしれません。

注釈

注意: ratio() の呼び出しの結果は引数の順序に依存します。例えば次の通りです:

>>> SequenceMatcher(None, 'tide', 'diet').ratio()
0.25
>>> SequenceMatcher(None, 'diet', 'tide').ratio()
0.5

quick_ratio()

ratio() の上界を、より高速に計算します。

real_quick_ratio()

ratio() の上界を、非常に高速に計算します。

The three methods that return the ratio of matching to total characters can give different results due to differing levels of approximation, although quick_ratio() and real_quick_ratio() are always at least as large as ratio():

>>> s = SequenceMatcher(None, "abcd", "bcde")
>>> s.ratio()
0.75
>>> s.quick_ratio()
0.75
>>> s.real_quick_ratio()
1.0

SequenceMatcher の例

この例は2つの文字列を比較します。空白を "junk" とします:

>>> s = SequenceMatcher(lambda x: x == " ",
...                     "private Thread currentThread;",
...                     "private volatile Thread currentThread;")

ratio() returns a float in [0, 1], measuring the similarity of the sequences. As a rule of thumb, a ratio() value over 0.6 means the sequences are close matches:

>>> print(round(s.ratio(), 3))
0.866

If you're only interested in where the sequences match, get_matching_blocks() is handy:

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

Note that the last tuple returned by get_matching_blocks() is always a dummy, (len(a), len(b), 0), and this is the only case in which the last tuple element (number of elements matched) is 0.

If you want to know how to change the first sequence into the second, use get_opcodes():

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

参考

SequenceMatcher を使った、シンプルで使えるコードを知るには、このモジュールの関数 get_close_matches() を参照してください。

Simple version control recipe [https://code.activestate.com/recipes/576729-simple-version-control/] for a small application built with SequenceMatcher.

Differ オブジェクト

Differ オブジェクトによって生成された差分が 最小 であるなどとは言いません。むしろ、最小の差分はしばしば直観に反しています。その理由は、どこでもできるとなれば一致を見いだしてしまうからで、ときには思いがけなく100ページも離れたマッチになってしまうのです。一致点を互いに隣接したマッチに制限することで、場合によって長めの差分を出力するというコストを掛けることにはなっても、ある種の局所性を保つことができるのです。

Differ は、以下のようなコンストラクタを持ちます:

class difflib.Differ(linejunk=None, charjunk=None)

オプションのキーワードパラメータ linejunk と charjunk は、フィルタ関数を渡します (使わないときは None):

linejunk: ひとつの文字列引数を受け取る関数です。文字列が junk のときに真を返します。デフォルトでは、None であり、どんな行であっても junk とは見なされません。

charjunk: この関数は文字(長さ1の文字列)を引数として受け取り、文字が junk であるときに真を返します。デフォルトは None であり、どんな文字も junk とは見なされません。

これらの junk フィルター関数により、差分を発見するマッチングが高速化し、差分の行や文字が無視されることがなくなります。説明については、 find_longest_match() メソッドの isjunk 引数の説明をご覧ください。

Differ オブジェクトは、以下の1つのメソッドを通して利用されます。（差分を生成します）:

compare(a, b)

文字列からなる2つのシーケンスを比較し、差分（を表す文字列からなるシーケンス）を生成します。

各シーケンスの要素は、改行で終わる独立した単一行からなる文字列でなければなりません。そのようなシーケンスは、ファイル風オブジェクトの readlines() メソッドによって得ることができます。（得られる）差分は改行文字で終了する文字列のシーケンスとして得られ、ファイル風オブジェクトの writelines() メソッドによって出力できる形になっています。

Differ の例

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 readlines() method of file-like objects):

>>> text1 = '''  1. Beautiful is better than ugly.
...   2. Explicit is better than implicit.
...   3. Simple is better than complex.
...   4. Complex is better than complicated.
... '''.splitlines(keepends=True)
>>> len(text1)
4
>>> text1[0][-1]
'\n'
>>> text2 = '''  1. Beautiful is better than ugly.
...   3.   Simple is better than complex.
...   4. Complicated is better than complex.
...   5. Flat is better than nested.
... '''.splitlines(keepends=True)

次に Differ オブジェクトをインスタンス化します:

>>> d = Differ()

注意: Differ オブジェクトをインスタンス化するとき、行 junk と文字 junk をフィルタリングする関数を渡すことができます。詳細は Differ() コンストラクタを参照してください。

最後に、2つを比較します:

>>> result = list(d.compare(text1, text2))

result は文字列のリストなので、pretty-printしてみましょう:

>>> 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']

これは、複数行の文字列として、次のように出力されます:

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

difflib のコマンドラインインターフェース

This example shows how to use difflib to create a diff-like utility.

""" 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()

ndiff example

This example shows how to use difflib.ndiff().

"""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:])

textwrap --- Text wrapping and filling

ソースコード: Lib/textwrap.py [https://github.com/python/cpython/tree/3.12/Lib/textwrap.py]

textwrap モジュールは、実際の処理を行う TextWrapper とともに、いくつかの便利な関数を提供しています。1つか2つの文字列を wrap あるいは fill するだけの場合は便利関数で十分ですが、多くの処理を行う場合は効率のために TextWrapper のインスタンスを使うべきでしょう。

textwrap.wrap(text, width=70, *, initial_indent='', subsequent_indent='', expand_tabs=True, replace_whitespace=True, fix_sentence_endings=False, break_long_words=True, drop_whitespace=True, break_on_hyphens=True, tabsize=8, max_lines=None, placeholder=' [...]')

text (文字列)内の段落を一つだけ折り返しを行います。したがって、すべての行が高々 width 文字の長さになります。最後に改行が付かない出力行のリストを返します。

オプションのキーワード引数は、以下で説明する TextWrapper のインスタンス属性に対応しています。

wrap() の動作についての詳細は TextWrapper.wrap() メソッドを参照してください。

textwrap.fill(text, width=70, *, initial_indent='', subsequent_indent='', expand_tabs=True, replace_whitespace=True, fix_sentence_endings=False, break_long_words=True, drop_whitespace=True, break_on_hyphens=True, tabsize=8, max_lines=None, placeholder=' [...]')

text 内の段落を一つだけ折り返しを行い、折り返しが行われた段落を含む一つの文字列を返します。 fill() はこれの省略表現です

"\n".join(wrap(text, ...))

特に、 fill() は wrap() とまったく同じ名前のキーワード引数を受け取ります。

textwrap.shorten(text, width, *, fix_sentence_endings=False, break_long_words=True, break_on_hyphens=True, placeholder=' [...]')

与えられた text を折りたたみ、切り詰めて、与えられた width に収まるようにします。

最初に、text 内の空白が折りたたまれます (すべての空白を、1 文字の空白文字で置き換えます)。結果が width 内に収まった場合、その結果が返されます。width に収まらない場合、残りの文字数と placeholder との和が width 内に収まるように、末尾から単語が切り捨てられます:

>>> textwrap.shorten("Hello  world!", width=12)
'Hello world!'
>>> textwrap.shorten("Hello  world!", width=11)
'Hello [...]'
>>> textwrap.shorten("Hello world", width=10, placeholder="...")
'Hello...'

オプションのキーワード引数は、以下で説明する TextWrapper インスタンスの属性に対応します。文字列が TextWrapper の fill() 関数に渡される前に、空白が折りたたまれます。そのため、tabsize、expand_tabs、drop_whitespace、replace_whitespace の値を変更しても、意味がありません。

Added in version 3.4.

textwrap.dedent(text)

text の各行に対し、共通して現れる先頭の空白を削除します。

この関数は通常、三重引用符で囲われた文字列をスクリーン/その他の左端にそろえ、なおかつソースコード中ではインデントされた形式を損なわないようにするために使われます。

タブとスペースはともにホワイトスペースとして扱われますが、同じではないことに注意してください: "  hello" という行と "\thello" は、同じ先頭の空白文字をもっていないとみなされます。

空白文字しか含まない行は入力の際に無視され、出力の際に単一の改行文字に正規化されます。

例えば:

def test():
    # end first line with \ to avoid the empty line!
    s = '''\
    hello
      world
    '''
    print(repr(s))          # prints '    hello\n      world\n    '
    print(repr(dedent(s)))  # prints 'hello\n  world\n'

textwrap.indent(text, prefix, predicate=None)

text の中の選択された行の先頭に prefix を追加します。

行の分割は text.splitlines(True) で行います。

デフォルトでは、(改行文字を含む)空白文字だけの行を除いてすべての行に prefix を追加します。

例えば:

>>> s = 'hello\n\n \nworld'
>>> indent(s, '  ')
'  hello\n\n \n  world'

省略可能な predicate 引数を使って、どの行をインデントするかを制御することができます。例えば、空行や空白文字のみの行にも prefix を追加するのは簡単です:

>>> print(indent(s, '+ ', lambda line: True))
+ hello
+
+
+ world

Added in version 3.3.

wrap()、fill()、shorten() は TextWrapper インスタンスを作成し、その一つのメソッドを呼び出すことで機能します。そのインスタンスは再利用されません。したがって、wrap() や fill() を使用して多くのテキスト文字列を処理するアプリケーションについては、独自の TextWrapper オブジェクトを作成する方が効率が良い方法でしょう。

テキストはなるべく空白か、ハイフンを含む語のハイフンの直後で折り返されます。 TextWrapper.break_long_words が偽に設定されていなければ、必要な場合に長い語が分解されます。

class textwrap.TextWrapper(**kwargs)

TextWrapper コンストラクタはたくさんのオプションのキーワード引数を受け取ります。それぞれのキーワード引数は一つのインスタンス属性に対応します。したがって、例えば

wrapper = TextWrapper(initial_indent="* ")

はこれと同じです

wrapper = TextWrapper()
wrapper.initial_indent = "* "

あなたは同じ TextWrapper オブジェクトを何回も再利用できます。また、使用中にインスタンス属性へ代入することでそのオプションのどれでも変更できます。

TextWrapper インスタンス属性(とコンストラクタのキーワード引数)は以下の通りです:

width

(デフォルト: 70) 折り返しが行われる行の最大の長さ。入力行に width より長い単一の語が無い限り、 TextWrapper は width 文字より長い出力行が無いことを保証します。

expand_tabs

(デフォルト: True) もし真ならば、そのときは text 内のすべてのタブ文字は text の expandtabs() メソッドを用いて空白に展開されます。

tabsize

(デフォルト: 8) expand_tabs が真の場合、 text の中のすべてのTAB文字は tabsize と現在のカラムに応じて、ゼロ以上のスペースに展開されます。

Added in version 3.3.

replace_whitespace

(デフォルト: True) 真の場合、 wrap() メソッドはタブの展開の後、 wrap 処理の前に各種空白文字をスペース1文字に置換します。置換される空白文字は: TAB, 改行, 垂直TAB, FF, CR ('\t\n\v\f\r') です。

注釈

expand_tabs が偽で replace_whitespace が真ならば、各タブ文字は1つの空白に置き換えられます。それはタブ展開と同じでは ありません 。

注釈

replace_whitespace が偽の場合、改行が行の途中で現れることで出力がおかしくなることがあります。このため、テキストを(str.splitlines() などを使って)段落ごとに分けて別々に wrap する必要があります。

drop_whitespace

(デフォルト: True) 真の場合、(wrap 処理のあとインデント処理の前に) 各行の最初と最後の空白文字を削除します。ただし、段落の最初の空白については、次の文字が空白文字でない場合は削除されません。削除される空白文字が行全体に及ぶ場合は、行自体を削除します。

initial_indent

(default: '') wrap の出力の最初の行の先頭に付与する文字列。最初の行の長さに加算されます。空文字列の場合インデントされません。

subsequent_indent

(デフォルト: '') 一行目以外の折り返しが行われる出力のすべての行の先頭に付けられる文字列。一行目以外の各行の折り返しまでの長さにカウントされます。

fix_sentence_endings

(デフォルト: False) もし真ならば、 TextWrapper は文の終わりを見つけようとし、確実に文がちょうど二つの空白で常に区切られているようにします。これは一般的に固定スペースフォントのテキストに対して望ましいです。しかし、文の検出アルゴリズムは完全ではありません: 文の終わりには、後ろに空白がある '.', '!' または '?' の中の一つ、ことによると '"' あるいは "'" が付随する小文字があると仮定しています。このアルゴリズムに伴う一つの問題は下記の"Dr."と

[...] Dr. Frankenstein's monster [...]

下記の"Spot."の間の差異を検出できないことです

[...] See Spot. See Spot run [...]

fix_sentence_endings はデフォルトで偽です。

文検出アルゴリズムは"小文字"の定義のために string.lowercase に依存し、同一行の文を区切るためにピリオドの後に二つの空白を使う慣習に依存しているため、英文テキストに限定されたものです。

break_long_words

(デフォルト: True) もし真ならば、そのとき width より長い行が確実にないようにするために、 width より長い語は切られます。偽ならば、長い語は切られないでしょう。そして、 width より長い行があるかもしれません。 (width を超える分を最小にするために、長い語は単独で一行に置かれるでしょう。)

break_on_hyphens

(デフォルト: True) 真の場合、英語で一般的なように、ラップ処理は空白か合成語に含まれるハイフンの直後で行われます。偽の場合、空白だけが改行に適した位置として判断されます。ただし、本当に語の途中で改行が行われないようにするためには、 break_long_words 属性を真に設定する必要があります。過去のバージョンでのデフォルトの振る舞いは、常にハイフンの直後での改行を許していました。

max_lines

(デフォルト None) None 以外の場合、出力は行数 max_lines を超えないようにされ、切り詰める際には出力の最後の行を placeholder に置き換えます。

Added in version 3.4.

placeholder

(デフォルト: ' [...]') 切り詰める場合に出力の最後の行に置く文字列です。

Added in version 3.4.

TextWrapper はモジュールレベルの簡易関数に類似したいくつかの公開メソッドも提供します:

wrap(text)

1段落の文字列 text を、各行が width 文字以下になるように wrap します。 wrap のすべてのオプションは TextWrapper インスタンスの属性から取得します。結果の、行末に改行のない行のリストを返します。出力の内容が空になる場合は、返すリストも空になります。

fill(text)

text 内の段落を一つだけ折り返しを行い、折り返しが行われた段落を含む一つの文字列を返します。

unicodedata --- Unicode Database

This module provides access to the Unicode Character Database (UCD) which defines character properties for all Unicode characters. The data contained in this database is compiled from the UCD version 15.0.0 [https://www.unicode.org/Public/15.0.0/ucd].

このモジュールは、ユニコード標準付録 #44 「 ユニコード文字データベース [https://www.unicode.org/reports/tr44/] 」で定義されているのと同じ名前およびシンボルを使用します。このモジュールは次のような関数を定義します:

unicodedata.lookup(name)

名前に対応する文字を探します。その名前の文字が見つかった場合、その文字が返されます。見つからなかった場合には、 KeyError を発生させます。

バージョン 3.3 で変更: name aliases [1] と named sequences [2] のサポートが追加されました。

unicodedata.name(chr[, default])

文字 chr に付いている名前を、文字列で返します。名前が定義されていない場合には default が返されますが、この引数が与えられていなければ ValueError を発生させます。

unicodedata.decimal(chr[, default])

文字 chr に割り当てられている十進数を、整数で返します。この値が定義されていない場合には default が返されますが、この引数が与えられていなければ ValueError を発生させます。

unicodedata.digit(chr[, default])

文字 chr に割り当てられている数値を、整数で返します。この値が定義されていない場合には default が返されますが、この引数が与えられていなければ ValueError を発生させます。

unicodedata.numeric(chr[, default])

文字 chr に割り当てられている数値を、float で返します。この値が定義されていない場合には default が返されますが、この引数が与えられていなければ ValueError を発生させます。

unicodedata.category(chr)

文字 chr に割り当てられた、汎用カテゴリを返します。

unicodedata.bidirectional(chr)

文字 chr に割り当てられた、双方向クラスを返します。そのような値が定義されていない場合、空の文字列が返されます。

unicodedata.combining(chr)

文字 chr に割り当てられた正規結合クラスを返します。結合クラス定義されていない場合、0 が返されます。

unicodedata.east_asian_width(chr)

ユニコード文字 chr に割り当てられたeast asian widthを文字列で返します。

unicodedata.mirrored(chr)

文字 chr に割り当てられた、鏡像化のプロパティを返します。その文字が双方向テキスト内で鏡像化された文字である場合には 1 を、それ以外の場合には 0 を返します。

unicodedata.decomposition(chr)

文字 chr に割り当てられた、文字分解マッピングを、文字列型で返します。そのようなマッピングが定義されていない場合、空の文字列が返されます。

unicodedata.normalize(form, unistr)

Unicode 文字列 unistr の正規形 form を返します。 form の有効な値は、'NFC'、'NFKC'、'NFD'、'NFKD' です。

Unicode 規格は標準等価性 (canonical equivalence) と互換等価性 (compatibility equivalence) に基づいて、様々な Unicode文字列の正規形を定義します。Unicode では、複数の方法で表現できる文字があります。たとえば、文字 U+00C7 (LATIN CAPITAL LETTER C WITH CEDILLA) は、U+0043 (LATIN CAPITAL LETTER C) U+0327 (COMBINING CEDILLA) というシーケンスとしても表現できます。

各文字には2つの正規形があり、それぞれ正規形 C と正規形 D といいます。正規形 D (NFD) は標準分解 (canonical decomposition) としても知られており、各文字を分解された形に変換します。正規形 C (NFC) は標準分解を適用した後、結合済文字を再構成します。

互換等価性に基づいて、2つの正規形が加えられています。Unicode では、一般に他の文字との統合がサポートされている文字があります。たとえば、U+2160 (ROMAN NUMERAL ONE) は事実上 U+0049 (LATIN CAPITAL LETTER I) と同じものです。しかし、Unicode では、既存の文字集合 (たとえば gb2312) との互換性のために、これがサポートされています。

正規形 KD (NFKD) は、互換分解 (compatibility decomposition) を適用します。すなわち、すべての互換文字を、等価な文字で置換します。正規形 KC (NFKC) は、互換分解を適用してから、標準分解を適用します。

2つのunicode文字列が正規化されていて人間の目に同じに見えても、片方が結合文字を持っていてもう片方が持っていない場合、それらは完全に同じではありません。

unicodedata.is_normalized(form, unistr)

Unicode 文字列 unistr が正規形 form かどうかを返します。 form の有効な値は、'NFC'、'NFKC'、'NFD'、'NFKD' です。

Added in version 3.8.

更に、本モジュールは以下の定数を公開します:

unicodedata.unidata_version

このモジュールで使われている Unicode データベースのバージョン。

unicodedata.ucd_3_2_0

これはモジュール全体と同じメソッドを具えたオブジェクトですが、Unicode データベースバージョン 3.2 を代わりに使っており、この特定のバージョンの Unicode データベースを必要とするアプリケーション(IDNA など)のためものです。

例:

>>> import unicodedata
>>> unicodedata.lookup('LEFT CURLY BRACKET')
'{'
>>> unicodedata.name('/')
'SOLIDUS'
>>> unicodedata.decimal('9')
9
>>> unicodedata.decimal('a')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: not a decimal
>>> unicodedata.category('A')  # 'L'etter, 'u'ppercase
'Lu'
>>> unicodedata.bidirectional('\u0660') # 'A'rabic, 'N'umber
'AN'

脚注

[1]

https://www.unicode.org/Public/15.0.0/ucd/NameAliases.txt

[2]

https://www.unicode.org/Public/15.0.0/ucd/NamedSequences.txt

stringprep --- Internet String Preparation

ソースコード: Lib/stringprep.py [https://github.com/python/cpython/tree/3.12/Lib/stringprep.py]

(ホスト名のような) インターネット上にある存在に識別名をつける際、しばしば識別名間の "等価性" 比較を行う必要があります。厳密には、例えば大小文字の区別をするかしないかいったように、比較をどのように行うかはアプリケーションの領域に依存します。また、例えば "印字可能な" 文字で構成された識別名だけを許可するといったように、可能な識別名を制限することも必要となるかもしれません。

RFC 3454 [https://datatracker.ietf.org/doc/html/rfc3454.html] では、インターネットプロトコル上で Unicode 文字列を "調製 (prepare)" するためのプロシジャを定義しています。文字列は通信路に載せられる前に調製プロシジャで処理され、その結果ある正規化された形式になります。RFC ではあるテーブルの集合を定義しており、それらはプロファイルにまとめられています。各プロファイルでは、どのテーブルを使い、 stringprep プロシジャのどのオプション部分がプロファイルの一部になっているかを定義しています。 stringprep プロファイルの一つの例は nameprep で、国際化されたドメイン名に使われます。

stringprep モジュールは RFC 3454 [https://datatracker.ietf.org/doc/html/rfc3454.html] のテーブルを公開しているに過ぎません。これらのテーブルは辞書やリストとして表現するには大きすぎるので、このモジュールでは Unicode 文字データベースを内部的に利用しています。モジュールソースコード自体は mkstringprep.py ユーティリティを使って生成されました。

その結果、これらのテーブルはデータ構造体ではなく、関数として公開されています。RFC には 2 種類のテーブル: 集合およびマップ、が存在します。集合については、 stringprep は "特性関数 (characteristic function)" 、すなわち引数が集合の一部である場合に True を返す関数を提供します。マッピングについては、マップ関数: キーが与えられると、それに関連付けられた値を返す関数を提供します。以下はこのモジュールで利用可能な全ての関数を列挙したものです。

stringprep.in_table_a1(code)

code がテーブル A.1 (Unicode 3.2 における未割り当てコードポイント: unassigned code point) かどうか判定します。

stringprep.in_table_b1(code)

code がテーブル B.1 (一般には何にも対応付けられていない: commonly mapped to nothing) かどうか判定します。

stringprep.map_table_b2(code)

テーブル B.2 (NFKC で用いられる大小文字の対応付け) に従って、code に対応付けられた値を返します。

stringprep.map_table_b3(code)

テーブル B.3 (正規化を伴わない大小文字の対応付け) に従って、code に対応付けられた値を返します。

stringprep.in_table_c11(code)

code がテーブル C.1.1 (ASCII スペース文字) かどうか判定します。

stringprep.in_table_c12(code)

code がテーブル C.1.2 (非 ASCII スペース文字) かどうか判定します。

stringprep.in_table_c11_c12(code)

code がテーブル C.1 (スペース文字、C.1.1 および C.1.2 の和集合) かどうか判定します。

stringprep.in_table_c21(code)

code がテーブル C.2.1 (ASCII 制御文字) かどうか判定します。

stringprep.in_table_c22(code)

code がテーブル C.2.2 (非 ASCII 制御文字) かどうか判定します。

stringprep.in_table_c21_c22(code)

code がテーブル C.2 (制御文字、C.2.1 および C.2.2 の和集合) かどうか判定します。

stringprep.in_table_c3(code)

code がテーブル C.3 (プライベート利用) かどうか判定します。

stringprep.in_table_c4(code)

code がテーブル C.4 (非文字コードポイント: non-character code points) かどうか判定します。

stringprep.in_table_c5(code)

code がテーブル C.5 (サロゲーションコード) かどうか判定します。

stringprep.in_table_c6(code)

code がテーブル C.6 (平文:plain text として不適切) かどうか判定します。

stringprep.in_table_c7(code)

code がテーブル C.7 (標準表現:canonical representation として不適切) かどうか判定します。

stringprep.in_table_c8(code)

code がテーブル C.8 (表示プロパティの変更または撤廃) かどうか判定します。

stringprep.in_table_c9(code)

code がテーブル C.9 (タグ文字) かどうか判定します。

stringprep.in_table_d1(code)

code がテーブル D.1 (双方向プロパティ "R" または "AL" を持つ文字) かどうか判定します。

stringprep.in_table_d2(code)

code がテーブル D.2 (双方向プロパティ "L" を持つ文字) かどうか判定します。

readline --- GNU readline interface

readline モジュールでは、補完や Python インタプリタからの履歴ファイルの読み書きを容易にするための多くの関数を定義しています。このモジュールは直接、または rlcompleter モジュールを介して使うことができます。 rlcompleter モジュールは対話的プロンプトで Python 識別子の補完をサポートするものです。このモジュールで利用される設定は、インタプリタの対話プロンプトならびに組み込みの input() 関数の両方の挙動に影響します。

readline のキーバインディングは初期化ファイルで設定できます。このファイルは、たいていはホームディレクトリに .inputrc という名前で置いてあります。 GNU Readline マニュアルの Readline Init File [https://tiswww.cwru.edu/php/chet/readline/rluserman.html#Readline-Init-File] を参照して、そのファイルの形式や可能な構成、 Readline ライブラリ全体の機能を知ってください。

注釈

The underlying Readline library API may be implemented by the libedit library instead of GNU readline. On macOS the readline module detects which library is being used at run time.

The configuration file for libedit is different from that of GNU readline. If you programmatically load configuration strings you can check for the text "libedit" in readline.__doc__ to differentiate between GNU readline and libedit.

If you use editline/libedit readline emulation on macOS, the initialization file located in your home directory is named .editrc. For example, the following content in ~/.editrc will turn ON vi keybindings and TAB completion:

python:bind -v
python:bind ^I rl_complete

初期化ファイル

以下の関数は初期化ファイルならびにユーザ設定関連のものです:

readline.parse_and_bind(string)

string 引数で渡された最初の行を実行します。これにより下層のライブラリーの rl_parse_and_bind() が呼ばれます。

readline.read_init_file([filename])

readline 初期化ファイルを実行します。デフォルトのファイル名は最後に使用されたファイル名です。これにより下層のライブラリーの rl_read_init_file() が呼ばれます。

行バッファ

以下の関数は行バッファを操作します:

readline.get_line_buffer()

行バッファ (下層のライブラリーの rl_line_buffer) の現在の内容を返します。

readline.insert_text(string)

テキストをカーサー位置の行バッファに挿入します。これにより下層のライブラリーの rl_insert_text() が呼ばれますが、戻り値は無視されます。

readline.redisplay()

スクリーンの表示を変更して行バッファの現在の内容を反映させます。これにより下層のライブラリーの rl_redisplay() が呼ばれます。

履歴ファイル

以下の関数は履歴ファイルを操作します:

readline.read_history_file([filename])

readline 履歴ファイルを読み込み、履歴リストに追加します。デフォルトのファイル名は ~/.history です。これにより下層のライブラリーの read_history() が呼ばれます。

readline.write_history_file([filename])

履歴リストを readline 履歴ファイルに保存します。既存のファイルは上書きされます。デフォルトのファイル名は ~/.history です。これにより下層のライブラリーの write_history() が呼ばれます。

readline.append_history_file(nelements[, filename])

履歴の最後の nelements 項目をファイルに追加します。デフォルトのファイル名は ~/.history です。ファイルは存在していなくてはなりません。これにより下層のライブラリーの append_history() が呼ばれます。Python がこの機能をサポートするライブラリーのバージョンでコンパイルされたときのみ、この関数は存在します。

Added in version 3.5.

readline.get_history_length()

readline.set_history_length(length)

Set or return the desired number of lines to save in the history file. The write_history_file() function uses this value to truncate the history file, by calling history_truncate_file() in the underlying library. Negative values imply unlimited history file size.

履歴リスト

以下の関数はグローバルな履歴リストを操作します:

readline.clear_history()

現在の履歴をクリアします。これにより下層のライブラリーの clear_history() が呼ばれます。Python がこの機能をサポートするライブラリーのバージョンでコンパイルされたときのみ、この関数は存在します。

readline.get_current_history_length()

履歴に現在ある項目の数を返します。 (get_history_length() は履歴ファイルに書かれる最大行数を返します。)

readline.get_history_item(index)

現在の履歴の index 番目の項目を返します。添字は1から始まります。これにより下層のライブラリーの history_get() が呼ばれます。

readline.remove_history_item(pos)

履歴から指定された位置の項目を削除します。添字は0から始まります。これにより下層のライブラリーの remove_history() が呼ばれます。

readline.replace_history_item(pos, line)

指定された位置の項目を line で置き換えます。添字は0から始まります。これにより下層のライブラリーの replace_history_entry() が呼ばれます。

readline.add_history(line)

最後に入力したかのように、 line を履歴バッファに追加します。これにより下層のライブラリーの add_history() が呼ばれます。

readline.set_auto_history(enabled)

Enable or disable automatic calls to add_history() when reading input via readline. The enabled argument should be a Boolean value that when true, enables auto history, and that when false, disables auto history.

Added in version 3.6.

CPython 実装の詳細: Auto history is enabled by default, and changes to this do not persist across multiple sessions.

開始フック

readline.set_startup_hook([function])

Set or remove the function invoked by the rl_startup_hook callback of the underlying library. If function is specified, it will be used as the new hook function; if omitted or None, any function already installed is removed. The hook is called with no arguments just before readline prints the first prompt.

readline.set_pre_input_hook([function])

Set or remove the function invoked by the 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 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.

補完

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 rlcompleter to complete Python identifiers for the interactive interpreter. If the readline module is to be used with a custom completer, a different set of word delimiters should be set.

readline.set_completer([function])

completer 関数を設定または削除します。function が指定された場合、新たな completer 関数として用いられます; 省略された場合や None の場合、現在インストールされている completer 関数は削除されます。completer 関数は function(text, state) の形式で、関数が文字列でない値を返すまで state を 0, 1, 2, ..., にして呼び出します。この関数は text から始まる補完結果として次に来そうなものを返さなければなりません。

The installed completer function is invoked by the entry_func callback passed to rl_completion_matches() in the underlying library. The text string comes from the first parameter to the rl_attempted_completion_function callback of the underlying library.

readline.get_completer()

completer 関数を取得します。completer 関数が設定されていなければ None を返します。

readline.get_completion_type()

Get the type of completion being attempted. This returns the rl_completion_type variable in the underlying library as an integer.

readline.get_begidx()

readline.get_endidx()

Get the beginning or ending index of the completion scope. These indexes are the start and end arguments passed to the 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.

readline.set_completer_delims(string)

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 rl_completer_word_break_characters variable in the underlying library.

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 None, any completion display function already installed is removed. This sets or clears the rl_completion_display_matches_hook callback in the underlying library. The completion display function is called as function(substitution, [matches], longest_match_length) once each time matches need to be displayed.

使用例

以下の例では、ユーザのホームディレクトリにある履歴ファイル .python_history の読み込みと保存を自動的に行うために、 readline モジュールの履歴の読み書き関数をどのように使うかを示しています。以下のソースコードは通常、対話セッション中はユーザの PYTHONSTARTUP ファイルから自動的に実行されます:

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)

Python が 対話モード で実行される時、このコードは実際には自動的に実行されます ( readline の設定 を参照してください)。

次の例では上記と同じ目的を達成できますが、ここでは新規の履歴のみを追加することで、並行して対話セッションがサポートされます:

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)

次の例では code.InteractiveConsole クラスを拡張し、履歴の保存・復旧をサポートします。

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)

rlcompleter --- Completion function for GNU readline

ソースコード: Lib/rlcompleter.py [https://github.com/python/cpython/tree/3.12/Lib/rlcompleter.py]

The rlcompleter module defines a completion function suitable to be passed to set_completer() in the readline module.

When this module is imported on a Unix platform with the readline module available, an instance of the Completer class is automatically created and its complete() method is set as the readline completer. The method provides completion of valid Python identifiers and keywords.

以下はプログラム例です:

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

The rlcompleter module is designed for use with Python's interactive mode. Unless Python is run with the -S option, the module is automatically imported and configured (see readline の設定).

readline のないプラットフォームでも、このモジュールで定義される Completer クラスは独自の目的に使えます。

class rlcompleter.Completer

Completerオブジェクトは以下のメソッドを持っています:

complete(text, state)

Return the next possible completion for text.

When called by the readline module, this method is called successively with state == 0, 1, 2, ... until the method returns None.

もし text がピリオド('.')を含まない場合、 __main__ 、 builtins で定義されている名前か、キーワード (keyword モジュールで定義されている) から補完されます。

If called for a dotted name, it will try to evaluate anything without obvious side-effects (functions will not be evaluated, but it can generate calls to __getattr__()) up to the last part, and find matches for the rest via the dir() function. Any exception raised during the evaluation of the expression is caught, silenced and None is returned.

バイナリデータ処理

この章で紹介されているモジュールはバイナリデータを扱うための基本的な処理を提供しています。ファイルフォーマットやネットワークプロトコルなど、その他のバイナリデータ処理については、それぞれの節で解説されています。

テキスト処理サービス で紹介する一部のライブラリには、 ASCII 互換のバイナリフォーマットで利用できるもの (例: re) や 、すべてのバイナリデータで利用できるもの (例: difflib) があります。

加えて、 バイナリシーケンス型 --- bytes, bytearray, memoryview に書かれているPythonビルトインデータ型についても参照してください。

struct --- Interpret bytes as packed binary data

関数と例外

書式文字列

バイトオーダ、サイズ、アラインメント

書式指定文字

使用例

Applications

Native Formats

Standard Formats

クラス

codecs --- Codec registry and base classes

Codec 基底クラス

エラーハンドラ

ステートレスなエンコードとデコード

インクリメンタルなエンコードとデコード

IncrementalEncoder オブジェクト

IncrementalDecoder オブジェクト

ストリームのエンコードとデコード

StreamWriter オブジェクト

StreamReader オブジェクト

StreamReaderWriter オブジェクト

StreamRecoder オブジェクト

エンコーディングと Unicode

標準エンコーディング

Python 特有のエンコーディング

テキストエンコーディング

バイナリ変換 (Binary Transforms)

テキスト変換 (Text Transforms)

encodings.idna --- アプリケーションにおける国際化ドメイン名 (IDNA)

encodings.mbcs --- Windows ANSI コードページ

encodings.utf_8_sig --- BOM 印付き UTF-8

struct --- Interpret bytes as packed binary data

ソースコード: Lib/struct.py [https://github.com/python/cpython/tree/3.12/Lib/struct.py]

This module converts between Python values and C structs represented as Python bytes objects. Compact format strings describe the intended conversions to/from Python values. The module's functions and objects can be used for two largely distinct applications, data exchange with external sources (files or network connections), or data transfer between the Python application and the C layer.

注釈

When no prefix character is given, native mode is the default. It packs or unpacks data based on the platform and compiler on which the Python interpreter was built. The result of packing a given C struct includes pad bytes which maintain proper alignment for the C types involved; similarly, alignment is taken into account when unpacking. In contrast, when communicating data between external sources, the programmer is responsible for defining byte ordering and padding between elements. See バイトオーダ、サイズ、アラインメント for details.

いくつかの struct の関数 (および Struct のメソッド) は buffer 引数を取ります。 これは バッファプロトコル (buffer Protocol) を実装していて読み取り可能または読み書き可能なバッファを提供するオブジェクトのことです。この目的のために使われる最も一般的な型は bytes と bytearray ですが、バイトの配列とみなすことができるような他の多くの型がバッファプロトコルを実装しています。そのため、それらは bytes オブジェクトから追加のコピーなしで読み出しや書き込みができます。

関数と例外

このモジュールは以下の例外と関数を定義しています:

exception struct.error

様々な状況で送出される例外です。引数は何が問題なのかを記述する文字列です。

struct.pack(format, v1, v2, ...)

フォーマット文字列 format に従い値 v1, v2, ... をパックして、バイト列オブジェクトを返します。引数は指定したフォーマットが要求する型と正確に一致していなければなりません。

struct.pack_into(format, buffer, offset, v1, v2, ...)

フォーマット文字列 format に従い値 v1, v2, ... をパックしてバイト列にし、書き込み可能な buffer のオフセット offset 位置より書き込みます。オフセットは省略出来ません。

struct.unpack(format, buffer)

(pack(format, ...) でパックされたであろう) バッファ buffer を、書式文字列 format に従ってアンパックします。値が一つしかない場合を含め、結果はタプルで返されます。バッファのバイトサイズは、 calcsize() の返り値である書式文字列が要求するサイズと一致しなければなりません。

struct.unpack_from(format, /, buffer, offset=0)

バッファ buffer を、 offset の位置から書式文字列 format に従ってアンパックします。値が一つしかない場合を含め、結果はタプルで返されます。 offset を始点とするバッファのバイトサイズは、少なくとも calcsize() の返り値である書式文字列が要求するサイズでなければなりません。

struct.iter_unpack(format, buffer)

バッファ buffer を、書式文字列 format に従ってイテレータ形式でアンパックします。この関数が返すイテレータは、すべての内容を読み終わるまでバッファから一定の大きさのチャンクを読み取ります。バッファのバイトサイズは、 calcsize() の返り値である書式文字列が要求するサイズの倍数でなければなりません。

イテレーション毎に書式文字列で指定されたタプルを yield します。

Added in version 3.4.

struct.calcsize(format)

書式文字列 format に従って、構造体 (それと pack(format, ...) によって作成されるバイト列オブジェクト) のサイズを返します。

書式文字列

Format strings describe the data layout when packing and unpacking data. They are built up from format characters, which specify the type of data being packed/unpacked. In addition, special characters control the byte order, size and alignment. Each format string consists of an optional prefix character which describes the overall properties of the data and one or more format characters which describe the actual data values and padding.

バイトオーダ、サイズ、アラインメント

By default, C types are represented in the machine's native format and byte order, and properly aligned by skipping pad bytes if necessary (according to the rules used by the C compiler). This behavior is chosen so that the bytes of a packed struct correspond exactly to the memory layout of the corresponding C struct. Whether to use native byte ordering and padding or standard formats depends on the application.

これに代わって、フォーマット文字列の最初の文字を使って、バイトオーダやサイズ、アラインメントを指定することができます。指定できる文字を以下のテーブルに示します:

文字

バイトオーダ

サイズ

アラインメント

@

native

native

native

=

native

standard

none

<

リトルエンディアン

standard

none

>

ビッグエンディアン

standard

none

!

ネットワーク (= ビッグエンディアン)

standard

none

フォーマット文字列の最初の文字が上のいずれかでない場合、'@' であるとみなされます。

注釈

The number 1023 (0x3ff in hexadecimal) has the following byte representations:

03 ff in big-endian (>)

ff 03 in little-endian (<)

Python の例:

>>> import struct
>>> struct.pack('>h', 1023)
b'\x03\xff'
>>> struct.pack('<h', 1023)
b'\xff\x03'

ネイティブのバイトオーダはビッグエンディアンかリトルエンディアンで、ホストシステムに依存します。例えば、Intel x86、AMD64 (x86-64) および Apple M1 はリトルエンディアンです。IBM z および多くの古いアーキテクチャはビッグエンディアンです。使っているシステムでのエンディアンは sys.byteorder を使って調べて下さい。

ネイティブのサイズおよびアラインメントは C コンパイラの sizeof 式で決定されます。ネイティブのサイズおよびアラインメントはネイティブのバイトオーダと同時に使われます。

標準のサイズはフォーマット文字だけで決まります。 書式指定文字 の表を参照して下さい。

'@' と '=' の違いに注意してください: 両方ともネイティブのバイトオーダですが、後者のバイトサイズとアラインメントは標準のものに合わせてあります。

The form '!' represents the network byte order which is always big-endian as defined in IETF RFC 1700 [https://datatracker.ietf.org/doc/html/rfc1700].

バイトオーダに関して、「(強制的にバイトスワップを行う)ネイティブの逆」を指定する方法はありません。'<' または '>' のうちふさわしい方を選んでください。

注釈:

パディングは構造体のメンバの並びの中にだけ自動で追加されます。最初や最後にパディングが追加されることはありません。

ネイティブでないサイズおよびアラインメントが使われる場合にはパディングは行われません (たとえば '<', '>', '=', '!' を使った場合です)。

特定の型によるアラインメント要求に従うように構造体の末端をそろえるには、繰り返し回数をゼロにした特定の型でフォーマットを終端します。 使用例 を参照して下さい。

書式指定文字

フォーマット文字 (format character) は以下の意味を持っています; C と Python の間の変換では、値は正確に以下に指定された型でなくてはなりません: 「標準のサイズ」列は standard サイズ使用時にパックされた値が何バイトかを示します。つまり、フォーマット文字列が '<', '>', '!', '=' のいずれかで始まっている場合のものです。native サイズ使用時にはパックされた値の大きさはプラットフォーム依存です。

フォーマット

C の型

Python の型

標準のサイズ

注釈

x

パディングバイト

値なし

(7)

c

char

長さ 1 のバイト列

1

b

signed char

整数

1

(1), (2)

B

unsigned char

整数

1

(2)

?

_Bool

真偽値型(bool)

1

(1)

h

short

整数

2

(2)

H

unsigned short

整数

2

(2)

i

int

整数

4

(2)

I

unsigned int

整数

4

(2)

l

long

整数

4

(2)

L

unsigned long

整数

4

(2)

q

long long

整数

8

(2)

Q

unsigned long long

整数

8

(2)

n

ssize_t

整数

(3)

N

size_t

整数

(3)

e

(6)

浮動小数点数

2

(4)

f

float

浮動小数点数

4

(4)

d

double

浮動小数点数

8

(4)

s

char[]

bytes

(9)

p

char[]

bytes

(8)

P

void*

整数

(5)

バージョン 3.3 で変更: 'n' および 'N' フォーマットのサポートが追加されました。

バージョン 3.6 で変更: 'e' フォーマットのサポートが追加されました。

注釈:

'?' 変換コードは C99 で定義された _Bool 型に対応します。その型が利用できない場合は、 char で代用されます。標準モードでは常に1バイトで表現されます。

When attempting to pack a non-integer using any of the integer conversion codes, if the non-integer has a __index__() method then that method is called to convert the argument to an integer before packing.

バージョン 3.2 で変更: Added use of the __index__() method for non-integers.

'n' および 'N' 変換コードは (デフォルトもしくはバイトオーダ文字 '@' 付きで選択される) native サイズ使用時のみ利用できます。standard サイズ使用時には、自身のアプリケーションに適する他の整数フォーマットを使うことができます。

'f' 、 'd' および 'e' 変換コードについて、パックされた表現は IEEE 754 binary32 ('f' の場合) 、 binary64 ('d' の場合) 、またはbinary16('e' の場合) フォーマットが、プラットフォームにおける浮動小数点数のフォーマットに関係なく使われます。

'P' フォーマット文字はネイティブバイトオーダでのみ利用可能です (デフォルトのネットワークバイトオーダに設定するか、'@' バイトオーダ指定文字を指定しなければなりません)。'=' を指定した場合、ホスト計算機のバイトオーダに基づいてリトルエンディアンとビッグエンディアンのどちらを使うかを決めます。struct モジュールはこの設定をネイティブのオーダ設定として解釈しないので、'P' を使うことはできません。

IEEE 754 の binary16 "半精度" 型は、 IEEE 754 standard [https://en.wikipedia.org/wiki/IEEE_754-2008_revision] の2008 年の改訂で導入されました。半精度型は、符号 bit 、5 bit の指数部、 11 bit の精度 (明示的には 10 bit が保存される) を持ち、おおよそ 6.1e-05 から 6.5e+04 までの数を完全な精度で表現できます。この型は C コンパイラでは広くはサポートされていません: たいていのマシンでは、保存するのに unsigned short が使えますが、数学の演算には使えません。詳しいことは Wikipedia の half-precision floating-point format [https://en.wikipedia.org/wiki/Half-precision_floating-point_format] のページを参照してください。

When packing, 'x' inserts one NUL byte.

フォーマット文字 'p' は "Pascal 文字列 (pascal string)" をコードします。Pascal 文字列は count で与えられる 固定長のバイト列 に収められた短い可変長の文字列です。このデータの先頭の 1 バイトには文字列の長さか255 のうち、小さい方の数が収められます。その後に文字列のバイトデータが続きます。 pack() に渡された Pascal 文字列の長さが長すぎた (count-1 よりも長い) 場合、先頭の count-1 バイトが書き込まれます。文字列が count-1 よりも短い場合、指定した count バイトに達するまでの残りの部分はヌルで埋められます。 unpack() では、フォーマット文字 'p' は指定された count バイトだけデータを読み込みますが、返される文字列は決して 255 文字を超えることはないので注意してください。

For the 's' format character, the count is interpreted as the length of the bytes, not a repeat count like for the other format characters; for example, '10s' means a single 10-byte string mapping to or from a single Python byte string, while '10c' means 10 separate one byte character elements (e.g., cccccccccc) mapping to or from ten different Python byte objects. (See 使用例 for a concrete demonstration of the difference.) If a count is not given, it defaults to 1. For packing, the string is truncated or padded with null bytes as appropriate to make it fit. For unpacking, the resulting bytes object always has exactly the specified number of bytes. As a special case, '0s' means a single, empty string (while '0c' means 0 characters).

フォーマット文字の前に整数をつけ、繰り返し回数 (count) を指定することができます。例えば、フォーマット文字列 '4h' は 'hhhh' と全く同じ意味です。

フォーマット文字間の空白文字は無視されます; count とフォーマット文字の間にはスペースを入れてはいけません。

整数フォーマット ('b', 'B', 'h', 'H', 'i', 'I', 'l', 'L', 'q', 'Q') のいずれかを使って値 x をパックするとき x がフォーマットの適切な値の範囲に無い場合、 struct.error が送出されます。

バージョン 3.1 で変更: 以前は、いくつかの整数フォーマットが適切な範囲にない値を覆い隠して、 struct.error の代わりに DeprecationWarning を送出していました。

'?' フォーマット文字では、返り値は True または False です。パックするときには、引数オブジェクトの論理値としての値が使われます。 0 または 1 のネイティブや標準の真偽値表現でパックされ、アンパックされるときはゼロでない値は True になります。

使用例

注釈

Native byte order examples (designated by the '@' format prefix or lack of any prefix character) may not match what the reader's machine produces as that depends on the platform and compiler.

Pack and unpack integers of three different sizes, using big endian ordering:

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

Attempt to pack an integer which is too large for the defined field:

>>> pack(">h", 99999)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
struct.error: 'h' format requires -32768 <= number <= 32767

Demonstrate the difference between 's' and 'c' format characters:

>>> pack("@ccc", b'1', b'2', b'3')
b'123'
>>> pack("@3s", b'123')
b'123'

アンパックした結果のフィールドは、変数に割り当てるか named tuple でラップすることによって名前を付けることができます:

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

The ordering of format characters may have an impact on size in native mode since padding is implicit. In standard mode, the user is responsible for inserting any desired padding. Note in the first pack call below that three NUL bytes were added after the packed '#' to align the following integer on a four-byte boundary. In this example, the output was produced on a little endian machine:

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

The following format 'llh0l' results in two pad bytes being added at the end, assuming the platform's longs are aligned on 4-byte boundaries:

>>> pack('@llh0l', 1, 2, 3)
b'\x00\x00\x00\x01\x00\x00\x00\x02\x00\x03\x00\x00'

参考

array モジュール

一様なデータ型からなるバイナリ記録データのパック。

json モジュール

JSON encoder and decoder.

pickle モジュール

Python object serialization.

Applications

Two main applications for the struct module exist, data interchange between Python and C code within an application or another application compiled using the same compiler (native formats), and data interchange between applications using agreed upon data layout (standard formats). Generally speaking, the format strings constructed for these two domains are distinct.

Native Formats

When constructing format strings which mimic native layouts, the compiler and machine architecture determine byte ordering and padding. In such cases, the @ format character should be used to specify native byte ordering and data sizes. Internal pad bytes are normally inserted automatically. It is possible that a zero-repeat format code will be needed at the end of a format string to round up to the correct byte boundary for proper alignment of consecutive chunks of data.

Consider these two simple examples (on a 64-bit, little-endian machine):

>>> calcsize('@lhl')
24
>>> calcsize('@llh')
18

Data is not padded to an 8-byte boundary at the end of the second format string without the use of extra padding. A zero-repeat format code solves that problem:

>>> calcsize('@llh0l')
24

The 'x' format code can be used to specify the repeat, but for native formats it is better to use a zero-repeat format like '0l'.

By default, native byte ordering and alignment is used, but it is better to be explicit and use the '@' prefix character.

Standard Formats

When exchanging data beyond your process such as networking or storage, be precise. Specify the exact byte order, size, and alignment. Do not assume they match the native order of a particular machine. For example, network byte order is big-endian, while many popular CPUs are little-endian. By defining this explicitly, the user need not care about the specifics of the platform their code is running on. The first character should typically be < or > (or !). Padding is the responsibility of the programmer. The zero-repeat format character won't work. Instead, the user must explicitly add 'x' pad bytes where needed. Revisiting the examples from the previous section, we have:

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

The above results (executed on a 64-bit machine) aren't guaranteed to match when executed on different machines. For example, the examples below were executed on a 32-bit machine:

>>> calcsize('<qqh6x')
24
>>> calcsize('@llh0l')
12
>>> pack('@llh0l', 1, 2, 3) == pack('<qqh6x', 1, 2, 3)
False

クラス

struct モジュールは次の型を定義します:

class struct.Struct(format)

フォーマット文字列 format に従ってバイナリデータを読み書きする、新しい Struct オブジェクトを返します。 Struct オブジェクトを一度作ってからそのメソッドを呼び出すと、フォーマット文字列のコンパイルが一度だけになるので、モジュールレベルの関数を同じフォーマットで呼び出すよりも効率的です。

注釈

The compiled versions of the most recent format strings passed to the module-level functions are cached, so programs that use only a few format strings needn't worry about reusing a single Struct instance.

コンパイルされた Struct オブジェクトは以下のメソッドと属性をサポートします:

pack(v1, v2, ...)

pack() 関数と同じ、コンパイルされたフォーマットを利用するメソッドです。 (len(result) は size と等しいでしょう)

pack_into(buffer, offset, v1, v2, ...)

pack_into() 関数と同じ、コンパイルされたフォーマットを利用するメソッドです。

unpack(buffer)

unpack() 関数と同じ、コンパイルされたフォーマットを利用するメソッドです。 (buffer のバイト数は size と等しくなければなりません)。

unpack_from(buffer, offset=0)

unpack_from() 関数と同じ、コンパイルされたフォーマットを利用するメソッドです。 (offset を始点とする buffer のバイト数は少なくとも size 以上でなければなりません)。

iter_unpack(buffer)

iter_unpack() 関数と同じ、コンパイルされたフォーマットを利用するメソッドです。 (buffer のバイト数は size の倍数でなければなりません)。

Added in version 3.4.

format

この Struct オブジェクトを作成する時に利用されたフォーマット文字列です。

バージョン 3.7 で変更: The format string type is now str instead of bytes.

size

format 属性に対応する構造体の (従って pack() メソッドによって作成されるバイト列オブジェクトの) サイズです。

codecs --- Codec registry and base classes

ソースコード: Lib/codecs.py [https://github.com/python/cpython/tree/3.12/Lib/codecs.py]

このモジュールは、標準的な Python codec (エンコーダとデコーダ) 用の基底クラスを定義し、codec とエラー処理検索プロセスを管理する内部の Python codec レジストリへのアクセスを提供します。多くの codec はテキストをバイトにエンコードする (そしてバイトをテキストにデコードする) テキストエンコーディング ですが、テキストをテキストに、またはバイトをバイトにエンコードする codec も提供されています。カスタムの codec は任意の型間でエンコードとデコードを行えますが、一部のモジュール機能は テキストエンコーディング か bytes へのエンコードのみに制限されています。

このモジュールでは、任意の codec でエンコードやデコードを行うための、以下の関数が定義されています。

codecs.encode(obj, encoding='utf-8', errors='strict')

encoding に記載された codec を使用して obj をエンコードします。

希望のエラー処理スキームを errors に設定することができます。デフォルトのエラーハンドラ (エラー処理関数) は 'strict' です。これはエンコードエラーは ValueError (もしくは UnicodeEncodeError のような、より codec に固有のサブクラス) を送出することを意味します。codec エラー処理についてのより詳しい情報は Codec 基底クラス を参照してください。

codecs.decode(obj, encoding='utf-8', errors='strict')

encoding に記載された codec を使用して obj をデコードします。

希望のエラー処理スキームを errors に設定することができます。デフォルトのエラーハンドラは 'strict' です。これはデコードエラーは ValueError (もしくは UnicodeDecodeError のような、より codec に固有のサブクラス) を送出することを意味します。codec エラー処理についてのより詳しい情報は Codec 基底クラス を参照してください。

各 codec についての詳細も、次のようにして直接調べることができます。

codecs.lookup(encoding)

Python codec レジストリから codec 情報を探し、以下で定義するような CodecInfo オブジェクトを返します。

エンコーディングの検索は、まずレジストリのキャッシュから行います。見つからなければ、登録されている検索関数のリストから探します。 CodecInfo オブジェクトが一つも見つからなければ LookupError を送出します。見つかったら、その CodecInfo オブジェクトはキャッシュに保存され、呼び出し側に返されます。

class codecs.CodecInfo(encode, decode, streamreader=None, streamwriter=None, incrementalencoder=None, incrementaldecoder=None, name=None)

codec レジストリ内を検索する場合の、codec の詳細です。コントラクタ引数は、次の同名の属性に保存されます。

name

エンコーディングの名前です。

encode

decode

ステートレスなエンコーディングとデコーディングの関数です。これらは、Codec インスタンスの encode() メソッドと decode() メソッドと同じインターフェースを持っている必要があります (see Codec のインターフェース を参照)。この関数またはメソッドは、ステートレスモードで動作することが想定されています。

incrementalencoder

incrementaldecoder

インクリメンタル・エンコーダとデコーダのクラスまたはファクトリ関数です。これらは、基底クラスの IncrementalEncoder と IncrementalDecoder が定義するインターフェースをそれぞれ提供する必要があります。インクリメンタルな codec は、ステート (内部状態) を保持することができます。

streamwriter

streamreader

ストリームライターとリーダーのクラスまたはファクトリ関数です。これらは、基底クラスの StreamWriter と StreamReader が定義するインターフェースをそれぞれ提供する必要があります。ストリーム codec は、ステートを保持することができます。

さまざまな codec 構成要素へのアクセスを簡便化するために、このモジュールは以下のような関数を提供しています。これらの関数は、 codec の検索に lookup() を使います:

codecs.getencoder(encoding)

与えられたエンコーディングに対する codec を検索し、エンコーダ関数を返します。

エンコーディングが見つからなければ LookupError を送出します。

codecs.getdecoder(encoding)

与えられたエンコーディングに対する codec を検索し、デコーダ関数を返します。

エンコーディングが見つからなければ LookupError を送出します。

codecs.getincrementalencoder(encoding)

与えられたエンコーディングに対する codec を検索し、インクリメンタル・エンコーダクラスまたはファクトリ関数を返します。

エンコーディングが見つからないか、 codec がインクリメンタル・エンコーダをサポートしなければ LookupError を送出します。

codecs.getincrementaldecoder(encoding)

与えられたエンコーディングに対する codec を検索し、インクリメンタル・デコーダクラスまたはファクトリ関数を返します。

エンコーディングが見つからないか、 codec がインクリメンタル・デコーダをサポートしなければ LookupError を送出します。

codecs.getreader(encoding)

与えられたエンコーディングに対する codec を検索し、StreamReader クラスまたはファクトリ関数を返します。

エンコーディングが見つからなければ LookupError を送出します。

codecs.getwriter(encoding)

与えられたエンコーディングに対する codec を検索し、StreamWriter クラスまたはファクトリ関数を返します。

エンコーディングが見つからなければ LookupError を送出します。

次のように、適切な codec 検索関数を登録することで、カスタムの codecs を利用することができます。

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 CodecInfo object. In case a search function cannot find a given encoding, it should return None.

バージョン 3.9 で変更: Hyphens and spaces are converted to underscore.

codecs.unregister(search_function)

Unregister a codec search function and clear the registry's cache. If the search function is not registered, do nothing.

Added in version 3.10.

エンコードされたテキストファイルを処理する場合、組み込みの open() とそれに関連付けられた io モジュールの使用が推奨されていますが、このモジュールは追加のユーティリティ関数とクラスを提供し、バイナリファイルを処理する場合に幅広い codecs を利用できるようにします。

codecs.open(filename, mode='r', encoding=None, errors='strict', buffering=-1)

エンコードされたファイルを mode を使って開き、透過的なエンコード/デコードを提供する StreamReaderWriter のインスタンスを返します。デフォルトのファイルモードは 'r' 、つまり、読み出しモードでファイルを開きます。

注釈

encoding が None でなければ、下層のエンコードされたファイルは、常にバイナリモードで開きます。読み書き時に、 '\n' の自動変換は行われません。mode 引数は、組み込みの open() 関数が受け入れる任意のバイナリモードにすることができます。'b' が自動的に付加されます。

encoding は、そのファイルに対して使用されるエンコーディングを指定します。バイトにエンコードする、あるいはバイトからデコードするすべてのエンコーディングが許可されます。ファイルメソッドがサポートするデータ型は、使用される codec によって異なります。

エラーハンドリングのために errors を渡すことができます。これはデフォルトでは 'strict' で、エンコード時にエラーがあれば ValueError を送出します。

buffering has the same meaning as for the built-in open() function. It defaults to -1 which means that the default buffer size will be used.

バージョン 3.11 で変更: 'U' モードは削除されました。

codecs.EncodedFile(file, data_encoding, file_encoding=None, errors='strict')

透過的なエンコード変換を行うファイルのラップされたバージョンである、StreamRecoder インスタンスを返します。元のファイルは、ラップされたバージョンが閉じられる時に、閉じられます。

ラップされたファイルに書き込まれたデータは、指定された data_encoding に従ってデコードされ、次に file_encoding を使用して元のファイルにバイトとして書き出されます。元のファイルから読み出されたバイトは、file_encoding に従ってデコードされ、結果は data_encoding を使用してエンコードされます。

file_encoding が与えられなければ、data_encoding がデフォルトになります。

エラーハンドリングのために errors を渡すことができます。これはデフォルトでは 'strict' で、エンコード時にエラーがあれば ValueError を送出します。

codecs.iterencode(iterator, encoding, errors='strict', **kwargs)

インクリメンタル・エンコーダを使って、 iterator から供給される入力を反復的にエンコードします。この関数は generator です。 errors 引数は (他のあらゆるキーワード引数と同様に) インクリメンタル・エンコーダにそのまま引き渡されます。

この関数では、コーデックはエンコードするテキストの str オブジェクトを受け付ける必要があります。従って、 base64_codec のようなバイトからバイトへのエンコーダはサポートしていません。

codecs.iterdecode(iterator, encoding, errors='strict', **kwargs)

インクリメンタル・デコーダを使って、 iterator から供給される入力を反復的にデコードします。この関数は generator です。 errors 引数は (他のあらゆるキーワード引数と同様に) インクリメンタル・デコーダにそのまま引き渡されます。

この関数では、コーデックはエンコードする bytes オブジェクトを受け付ける必要があります。従って、 rot_13 のようなテキストからテキストへのエンコーダが iterencode() で同等に使えるとしても、この関数ではサポートしていません。

このモジュールは以下のような定数も定義しています。プラットフォーム依存なファイルを読み書きするのに役立ちます:

codecs.BOM

codecs.BOM_BE

codecs.BOM_LE

codecs.BOM_UTF8

codecs.BOM_UTF16

codecs.BOM_UTF16_BE

codecs.BOM_UTF16_LE

codecs.BOM_UTF32

codecs.BOM_UTF32_BE

codecs.BOM_UTF32_LE

これらの定数は、いくつかのエンコーディングの Unicode のバイトオーダマーク (BOM) で、様々なバイトシーケンスを定義します。これらは、UTF-16 と UTF-32 のデータストリームで使用するバイトオーダを指定したり、 UTF-8 で Unicode シグネチャとして使われます。 BOM_UTF16 は、プラットフォームのネイティブバイトオーダによって BOM_UTF16_BE または BOM_UTF16_LE です。 BOM は BOM_UTF16 のエイリアスです。同様に、 BOM_LE は BOM_UTF16_LE の、 BOM_BE は BOM_UTF16_BE のエイリアスです。その他の定数は UTF-8 と UTF-32 エンコーディングの BOM を表します。

Codec 基底クラス

codecs モジュールは、 codec オブジェクトを操作するインターフェースを定義する一連の基底クラスを定義します。このモジュールは、カスタムの codec の実装の基礎として使用することもできます。

Python で codec として使えるようにするには、ステートレスエンコーダ、ステートレスデコーダ、ストリームリーダ、ストリームライタの 4 つのインターフェースを定義する必要があります。通常は、ストリームリーダとライタはステートレスエンコーダとデコーダを再利用して、ファイルプロトコルを実装します。codec の作者は、codec がエンコードとデコードのエラーの処理方法も定義する必要があります。

エラーハンドラ

エラー処理の簡便化と標準化のため、コーデックは、errors 文字列引数を指定した場合に別のエラー処理を行うような仕組みを実装してもかまいません:

>>> 'German ß, ♬'.encode(encoding='ascii', errors='backslashreplace')
b'German \\xdf, \\u266c'
>>> 'German ß, ♬'.encode(encoding='ascii', errors='xmlcharrefreplace')
b'German &#223;, &#9836;'

The following error handlers can be used with all Python 標準エンコーディング codecs:

値

意味

'strict'

UnicodeError (または、そのサブクラス) を送出します。これがデフォルトの動作です。 strict_errors() で実装されています。

'ignore'

不正な形式のデータを無視し、何も通知することなく処理を継続します。ignore_errors() で実装されています。

'replace'

Replace with a replacement marker. On encoding, use ? (ASCII character). On decoding, use ? (U+FFFD, the official REPLACEMENT CHARACTER). Implemented in replace_errors().

'backslashreplace'

Replace with backslashed escape sequences. On encoding, use hexadecimal form of Unicode code point with formats \xhh \uxxxx \Uxxxxxxxx. On decoding, use hexadecimal form of byte value with format \xhh. Implemented in backslashreplace_errors().

'surrogateescape'

デコード時には、バイト列を U+DC80 から U+DCFF の範囲の個々のサロゲートコードで置き換えます。データのエンコード時に 'surrogateescape' エラーハンドラが使用されると、このコードは同じバイト列に戻されます。 (詳しくは PEP 383 [https://peps.python.org/pep-0383/] を参照。)

The following error handlers are only applicable to encoding (within text encodings):

値

意味

'xmlcharrefreplace'

Replace with XML/HTML numeric character reference, which is a decimal form of Unicode code point with format &#num;. Implemented in xmlcharrefreplace_errors().

'namereplace'

Replace with \N{...} escape sequences, what appears in the braces is the Name property from Unicode Character Database. Implemented in namereplace_errors().

さらに、次のエラーハンドラは与えられた codec に特有です:

値

Codecs

意味

'surrogatepass'

utf-8, utf-16, utf-32, utf-16-be, utf-16-le, utf-32-be, utf-32-le

Allow encoding and decoding surrogate code point (U+D800 - U+DFFF) as normal code point. Otherwise these codecs treat the presence of surrogate code point in str as an error.

Added in version 3.1: 'surrogateescape' および 'surrogatepass' エラーハンドラ。

バージョン 3.4 で変更: The 'surrogatepass' error handler now works with utf-16* and utf-32* codecs.

Added in version 3.5: 'namereplace' エラーハンドラです。

バージョン 3.5 で変更: The 'backslashreplace' error handler now works with decoding and translating.

次のように、名前付きの新しいエラーハンドラを登録することで、許可される値の集合を拡張することができます。

codecs.register_error(name, error_handler)

エラーハンドラ error_handler を名前 name で登録します。エンコード中およびデコード中にエラーが送出された場合、name が errors 引数として指定されていれば error_handler が呼び出されます。

error_handler はエラーの場所に関する情報の入った UnicodeEncodeError インスタンスとともに呼び出されます。エラー処理関数はこの例外を送出するか、別の例外を送出するか、入力のエンコードできなかった部分の代替文字列とエンコードを再開する場所が入ったタプルを返す必要があります。代替文字列は str または bytes のいずれかにすることができます。代替文字列がバイト列である場合、エンコーダは単に出力バッファにそれをコピーします。代替文字列が文字列である場合、エンコーダは代替文字列をエンコードします。元の入力中の指定位置からエンコードが再開されます。位置を負の値にすると、入力文字列の末端からの相対位置として扱われます。境界の外側にある位置を返した場合には IndexError が送出されます。

デコードと翻訳の動作は似ていますが、エラーハンドラに渡されるのが UnicodeDecodeError か UnicodeTranslateError である点と、エラーハンドラの置換した内容が直接出力されるという点が異なります。

登録済みのエラーハンドラ (標準エラーハンドラを含む) は、次のようにその名前で検索することができます。

codecs.lookup_error(name)

名前 name で登録済みのエラーハンドラを返します。

エラーハンドラが見つからなければ LookupError を送出します。

以下の標準エラーハンドラも、モジュールレベルの関数として利用できます。

codecs.strict_errors(exception)

Implements the 'strict' error handling.

Each encoding or decoding error raises a UnicodeError.

codecs.ignore_errors(exception)

Implements the 'ignore' error handling.

Malformed data is ignored; encoding or decoding is continued without further notice.

codecs.replace_errors(exception)

Implements the 'replace' error handling.

Substitutes ? (ASCII character) for encoding errors or ? (U+FFFD, the official REPLACEMENT CHARACTER) for decoding errors.

codecs.backslashreplace_errors(exception)

Implements the 'backslashreplace' error handling.

Malformed data is replaced by a backslashed escape sequence. On encoding, use the hexadecimal form of Unicode code point with formats \xhh \uxxxx \Uxxxxxxxx. On decoding, use the hexadecimal form of byte value with format \xhh.

バージョン 3.5 で変更: Works with decoding and translating.

codecs.xmlcharrefreplace_errors(exception)

Implements the 'xmlcharrefreplace' error handling (for encoding within 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 &#num; .

codecs.namereplace_errors(exception)

Implements the 'namereplace' error handling (for encoding within text encoding only).

The unencodable character is replaced by a \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 'ß' will be converted to byte sequence \N{LATIN SMALL LETTER SHARP S} .

Added in version 3.5.

ステートレスなエンコードとデコード

基底の Codec クラスは以下のメソッドを定義します。これらのメソッドは、内部状態を持たないエンコーダ／デコーダ関数のインターフェースを定義します:

class codecs.Codec

encode(input, errors='strict')

オブジェクト input エンコードし、(出力オブジェクト, 消費した長さ) のタプルを返します。例えば、 テキストエンコーディング は文字列オブジェクトを特有の文字セット (例えば cp1252 や iso-8859-1) を用いてバイト列オブジェクトに変換します。

errors 引数は適用するエラー処理を定義します。'strict' 処理がデフォルトです。

このメソッドは Codec に内部状態を保存してはなりません。効率よくエンコードするために状態を保持しなければならないような codecs には StreamWriter を使ってください。

エンコーダは長さが 0 の入力を処理できなければなりません。この場合、空のオブジェクトを出力オブジェクトとして返さなければなりません。

decode(input, errors='strict')

オブジェクト input をデコードし、(出力オブジェクト, 消費した長さ) のタプルを返します。例えば、 テキストエンコーディング は、特定の文字集合エンコーディングでエンコードされたバイト列オブジェクトを文字列オブジェクトに変換します。

テキストエンコーディングとバイト列からバイト列への codec では、input は bytes オブジェクト、または読み出し専用のバッファインターフェースを提供するオブジェクトである必要があります。例えば、buffer オブジェクトやメモリマップドファイルでなければなりません。

errors 引数は適用するエラー処理を定義します。'strict' 処理がデフォルトです。

このメソッドは、 Codec インスタンスに内部状態を保存してはなりません。効率よくエンコード／デコードするために状態を保持しなければならないような codecs には StreamReader を使ってください。

デコーダは長さが 0 の入力を処理できなければなりません。この場合、空のオブジェクトを出力オブジェクトとして返さなければなりません。

インクリメンタルなエンコードとデコード

IncrementalEncoder クラスおよび IncrementalDecoder クラスはそれぞれインクリメンタル・エンコードおよびデコードのための基本的なインターフェースを提供します。エンコード／デコードは内部状態を持たないエンコーダ／デコーダを一度呼び出すことで行なわれるのではなく、インクリメンタル・エンコーダ／デコーダの encode()/decode() メソッドを複数回呼び出すことで行なわれます。インクリメンタル・エンコーダ／デコーダはメソッド呼び出しの間エンコード／デコード処理の進行を管理します。

encode()/decode() メソッド呼び出しの出力結果をまとめたものは、入力をひとまとめにして内部状態を持たないエンコーダ／デコーダでエンコード／デコードしたものと同じになります。

IncrementalEncoder オブジェクト

IncrementalEncoder クラスは入力を複数ステップでエンコードするのに使われます。全てのインクリメンタル・エンコーダが Python codec レジストリと互換性を持つために定義すべきメソッドとして、このクラスには以下のメソッドが定義されています。

class codecs.IncrementalEncoder(errors='strict')

IncrementalEncoder インスタンスのコンストラクタ。

全てのインクリメンタル・エンコーダはこのコンストラクタインターフェースを提供しなければなりません。さらにキーワード引数を付け加えるのは構いませんが、Python codec レジストリで利用されるのはここで定義されているものだけです。

IncrementalEncoder は、 errors キーワード引数を提供することで、様々なエラー取扱方法を実装することができます。取り得る値については エラーハンドラ を参照してください。

errors 引数は、同名の属性に代入されます。この属性を変更すると、 IncrementalEncoder オブジェクトが生きている間に、異なるエラー処理方法に切り替えることができるようになります。

encode(object, final=False)

object を(エンコーダの現在の状態を考慮に入れて)エンコードし、得られたエンコードされたオブジェクトを返します。 encode() 呼び出しがこれで最後という時には final は真でなければなりません(デフォルトは偽です)。

reset()

エンコーダを初期状態にリセットします。出力は破棄されます。.encode(object, final=True) を呼び出して、必要に応じて空バイト列またはテキスト文字列を渡すことにより、エンコーダをリセットし、出力を取得します。

getstate()

エンコーダの現在の状態を返します。それは必ず整数でなければなりません。実装は、0 が最も一般的な状態であることを保証すべきです。 (整数より複雑な状態は、状態を marshal/pickle して生じた文字列のバイトを整数にコード化することによって整数に変換することができます。)

setstate(state)

エンコーダの状態を state にセットします。 state は getstate() によって返されたエンコーダ状態でなければなりません。

IncrementalDecoder オブジェクト

IncrementalDecoder クラスは入力を複数ステップでデコードするのに使われます。全てのインクリメンタル・デコーダが Python codec レジストリと互換性を持つために定義すべきメソッドとして、このクラスには以下のメソッドが定義されています。

class codecs.IncrementalDecoder(errors='strict')

IncrementalDecoder インスタンスのコンストラクタ。

全てのインクリメンタル・デコーダはこのコンストラクタインターフェースを提供しなければなりません。さらにキーワード引数を付け加えるのは構いませんが、Python codec レジストリで利用されるのはここで定義されているものだけです。

IncrementalDecoder は、 errors キーワード引数を提供することで、様々なエラー取扱方法を実装することができます。取り得る値については エラーハンドラ を参照してください。

errors 引数は、同名の属性に代入されます。この属性を変更すると、 IncrementalDecoder オブジェクトが生きている間に、異なるエラー処理方法に切り替えることができるようになります。

decode(object, final=False)

object を(デコーダの現在の状態を考慮に入れて)デコードし、得られたデコードされたオブジェクトを返します。 decode() 呼び出しがこれで最後という時には final は真でなければなりません(デフォルトは偽です)。もし final が真ならばデコーダは入力をデコードし切り全てのバッファをフラッシュしなければなりません。そうできない場合(たとえば入力の最後に不完全なバイト列があるから)、デコーダは内部状態を持たない場合と同じようにエラーの取り扱いを開始しなければなりません(例外を送出するかもしれません)。

reset()

デコーダを初期状態にリセットします。

getstate()

デコーダの現在の状態を返します。これは2要素を含むタプルでなければなりません。1番目はまだデコードされていない入力を含むバッファです。2番目は整数で、付加的な状態情報です (実装は 0 が最も一般的な付加的な状態情報であることを保証すべきです)。この付加的な状態情報が 0 である場合、デコーダを入力がバッファされていない状態に戻して、付加的な状態情報を 0 にセットすることが可能でなければなりません。その結果、以前バッファされた入力をデコーダに与えることで、何の出力もせずにデコーダを前の状態に戻します。 (整数より複雑な付加的な状態情報は、情報を marshal/pickle して、結果として生じる文字列のバイト列を整数にエンコードすることで、整数に変換することができます。)

setstate(state)

デコーダの状態を state にセットします。 state は getstate() によって返されたデコーダの状態でなければなりません。

ストリームのエンコードとデコード

The StreamWriter and StreamReader classes provide generic working interfaces which can be used to implement new encoding submodules very easily. See encodings.utf_8 for an example of how this is done.

StreamWriter オブジェクト

StreamWriter クラスは Codec のサブクラスで、以下のメソッドを定義しています。全てのストリームライタは、 Python の codec レジストリとの互換性を保つために、これらのメソッドを定義する必要があります。

class codecs.StreamWriter(stream, errors='strict')

StreamWriter インスタンスのコンストラクタです。

全てのストリームライタはコンストラクタとしてこのインターフェースを提供しなければなりません。キーワード引数を追加しても構いませんが、Python の codec レジストリはここで定義されている引数だけを使います。

stream 引数は、特定の codec に対応して、テキストまたはバイナリデータの書き込みが可能なファイルライクオブジェクトである必要があります。

StreamWriter は、 errors キーワード引数を提供することで、様々なエラー取扱方法を実装することができます。下層のストリーム codec がサポートできる標準エラーハンドラについては エラーハンドラ を参照してください。

errors 引数は、同名の属性に代入されます。この属性を変更すると、 StreamWriter オブジェクトが生きている間に、異なるエラー処理に変更できます。

write(object)

object の内容をエンコードしてストリームに書き出します。

writelines(list)

Writes the concatenated iterable of strings to the stream (possibly by reusing the write() method). Infinite or very large iterables are not supported. The standard bytes-to-bytes codecs do not support this method.

reset()

内部状態保持に使われた codec のバッファをリセットします。

このメソッドが呼び出された場合、出力先データをきれいな状態にし、わざわざストリーム全体を再スキャンして状態を元に戻さなくても新しくデータを追加できるようにしなければなりません。

ここまでで挙げたメソッドの他にも、 StreamWriter では背後にあるストリームの他の全てのメソッドや属性を継承しなければなりません。

StreamReader オブジェクト

StreamReader クラスは Codec のサブクラスで、以下のメソッドを定義しています。全てのストリームリーダは、 Python の codec レジストリとの互換性を保つために、これらのメソッドを定義する必要があります。

class codecs.StreamReader(stream, errors='strict')

StreamReader インスタンスのコンストラクタです。

全てのストリームリーダはコンストラクタとしてこのインターフェースを提供しなければなりません。キーワード引数を追加しても構いませんが、Python の codec レジストリはここで定義されている引数だけを使います。

stream 引数は、特定の codec に対応して、テキストまたはバイナリデータの読み出しが可能なファイルライクオブジェクトである必要があります。

StreamReader は、 errors キーワード引数を提供することで、様々なエラー取扱方法を実装することができます。下層のストリーム codec がサポートできる標準エラーハンドラについては エラーハンドラ を参照してください。

errors 引数は、同名の属性に代入されます。この属性を変更すると、 StreamReader オブジェクトが生きている間に、異なるエラー処理に変更できます。

errors 引数に許される値の集合は register_error() で拡張できます。

read(size=-1, chars=-1, firstline=False)

ストリームからのデータをデコードし、デコード済のオブジェクトを返します。

chars 引数は、いくつのデコードされたコードポイントまたはバイト列を返すかを表します。 read() メソッドは、要求された数以上のデータを返すことはありませんが、データがそれより少ない場合には要求された数未満のデータを返す場合があります。

size 引数は、デコード用に読み込むエンコードされたバイト列またはコードポイントの、およその最大バイト数を表します。デコーダはこの値を適切な値に変更できます。デフォルト値 -1 の場合、可能な限り多くのデータを読み込みます。この引数の目的は、巨大なファイルの一括デコードを防ぐことにあります。

firstline フラグは、1行目さえ返せばその後の行でデコードエラーがあっても無視して十分だ、ということを示します。

このメソッドは貪欲な読み込み戦略を取るべきです。すなわち、エンコーディング定義と size の値が許す範囲で、できるだけ多くのデータを読むべきだということです。たとえば、ストリーム上にエンコーディングの終端や状態の目印があれば、それも読み込みます。

readline(size=None, keepends=True)

入力ストリームから1行読み込み、デコード済みのデータを返します。

size が与えられた場合、ストリームの read() メソッドに size 引数として渡されます。

keepends が偽の場合には行末の改行が削除された行が返ります。

readlines(sizehint=None, keepends=True)

入力ストリームから全ての行を読み込み、行のリストとして返します。

keepends が真なら、改行は、codec の decode() メソッドを使って実装され、リスト要素の中に含まれます。

sizehint が与えられた場合、ストリームの read() メソッドに size 引数として渡されます。

reset()

内部状態保持に使われた codec のバッファをリセットします。

ストリームの読み位置を再設定してはならないので注意してください。このメソッドはデコードの際にエラーから復帰できるようにするためのものです。

ここまでで挙げたメソッドの他にも、 StreamReader では背後にあるストリームの他の全てのメソッドや属性を継承しなければなりません。

StreamReaderWriter オブジェクト

StreamReaderWriter は、読み書き両方に使えるストリームをラップできる便利なクラスです。

lookup() 関数が返すファクトリ関数を使って、インスタンスを生成するという設計です。

class codecs.StreamReaderWriter(stream, Reader, Writer, errors='strict')

StreamReaderWriter インスタンスを生成します。 stream はファイル類似のオブジェクトです。 Reader と Writer は、それぞれ StreamReader と StreamWriter インターフェースを提供するファクトリ関数かファクトリクラスでなければなりません。エラー処理は、ストリームリーダとライタで定義したものと同じように行われます。

StreamReaderWriter インスタンスは、 StreamReader クラスと StreamWriter クラスを合わせたインターフェースを継承します。元になるストリームからは、他のメソッドや属性を継承します。

StreamRecoder オブジェクト

StreamRecoder はデータをあるエンコーディングから別のエンコーディングに変換します。異なるエンコーディング環境を扱うとき、便利な場合があります。

lookup() 関数が返すファクトリ関数を使って、インスタンスを生成するという設計です。

class codecs.StreamRecoder(stream, encode, decode, Reader, Writer, errors='strict')

Creates a StreamRecoder instance which implements a two-way conversion: encode and decode work on the frontend — the data visible to code calling read() and write(), while Reader and Writer work on the backend — the data in stream.

これらのオブジェクトを使って、たとえば、 Latin-1 から UTF-8 への変換、あるいは逆向きの変換を、透過的に行うことができます。

stream 引数はファイルライクオブジェクトでなくてはなりません。

encode 引数と decode 引数は Codec のインターフェースに忠実でなくてはなりません。Reader と Writer は、それぞれ StreamReader と StreamWriter のインターフェースを提供するオブジェクトのファクトリ関数かクラスでなくてはなりません。

エラー処理はストリーム・リーダやライタで定義されている方法と同じように行われます。

StreamRecoder インスタンスは、 StreamReader と StreamWriter クラスを合わせたインターフェースを定義します。また、元のストリームのメソッドと属性も継承します。

エンコーディングと Unicode

文字列は内部的に U+0000--U+10FFFF の範囲のコードポイントのシーケンスとして格納されます (実装に関する詳細については PEP 393 [https://peps.python.org/pep-0393/] を参照してください)。文字列オブジェクトが CPU とメモリの外で使用されるようになると、エンディアンやこれらの配列をバイト列として格納する方法が問題になります。他のコーデックでも同様ですが、文字列オブジェクトをバイト列に変換することは エンコード と呼ばれます。また、バイト列から文字列オブジェクトを再生成することは デコード と呼ばれます。テキストをシリアライズするコーデックには多くの種類があります。それらは、集合的に term:テキストエンコーディング <text encoding> と呼ばれます。

最も単純なテキストエンコーディング ('latin-1' または 'iso-8859-1') では、0--255 の範囲にあるコードポイントを 0x0--0xff のバイトにマップします。つまり、この codec では U+00FF 以上のコードポイントを含む文字列オブジェクトをエンコードすることはできません。このようなエンコード処理をしようとすると、次のように UnicodeEncodeError が送出されます (エラーメッセージの細かところは異なる場合があります。): UnicodeEncodeError: 'latin-1' codec can't encode character '\u1234' in position 3: ordinal not in range(256) 。

他のエンコーディングの一群 (charmap エンコーディングと呼ばれます) があり、 Unicode コードポイントの別の部分集合と、それらから 0x0--0xff のバイトへの対応付けを選択したものです。これがどのように行なわれるかを知るには、単にたとえば encodings/cp1252.py (主に Windows で使われるエンコーディングです) を開いてみてください。 256 文字のひとつの文字列定数があり、どの文字がどのバイト値へ対応付けられるかが示されています。

これらのエンコーディングはすべて、 Unicode に定義された 1114112 のコードポイントのうちの 256 だけをエンコードすることができます。 Unicode のすべてのコードポイントを格納するための単純で直接的な方法は、各コードポイントを連続する4バイトとして格納することです。これには2つの可能性があります: ビッグエンディアンまたはリトルエンディアンの順にバイトを格納することです。これら2つのエンコーディングはそれぞれ UTF-32-BE および UTF-32-LE と呼ばれます。それらのデメリットは、例えばリトルエンディアンのマシン上で UTF-32-BE を使用すると、エンコードでもデコードでも常にバイト順を交換する必要があることです。UTF-32 はこの問題を回避します: バイト順は、常に自然なエンディアンに従います。しかし、これらのバイト順が異なるエンディアン性を持つ CPU によって読まれる場合、結局バイト順を交換しなければなりません。UTF-16 あるいは UTF-32 バイト列のエンディアン性を検出する目的で、いわゆる BOM (「バイト・オーダー・マーク」) があります。これは Unicode 文字 U+FEFF です。この文字はすべての UTF-16 あるいは UTF-32 バイト列の前に置くことができます。この文字のバイトが交換されたバージョン (0xFFFE) は、 Unicode テキストに現われてはならない不正な文字です。したがって、UTF-16 あるいは UTF-32 バイト列中の最初の文字が U+FFFE であるように見える場合、デコードの際にバイトを交換しなければなりません。不運にも文字 U+FEFF は ZERO WIDTH NO-BREAK SPACE として別の目的を持っていました: 幅を持たず、単語を分割することを許容しない文字。それは、例えばリガチャアルゴリズムにヒントを与えるために使用することができます。 Unicode 4.0 で、ZERO WIDTH NO-BREAK SPACE としての U+FEFF の使用は廃止予定になりました (この役割は U+2060 (WORD JOINER) によって引き継がれました)。しかしながら、 Unicode ソフトウェアは、依然として両方の役割の U+FEFF を扱うことができなければなりません: BOM として、エンコードされたバイトのメモリレイアウトを決定する手段であり、一旦バイト列が文字列にデコードされたならば消えます; ZERO WIDTH NO-BREAK SPACE として、他の任意の文字のようにデコードされる通常の文字です。

さらにもう一つ Unicode 文字全てをエンコードできるエンコーディングがあり、UTF-8 と呼ばれています。UTF-8 は8ビットエンコーディングで、したがって UTF-8 にはバイト順の問題はありません。UTF-8 バイト列の各バイトは二つのパートから成ります。二つはマーカ(上位数ビット)とペイロードです。マーカは0ビットから4ビットの 1 の列に 0 のビットが一つ続いたものです。Unicode 文字は次のようにエンコードされます (x はペイロードを表わし、連結されると一つの Unicode 文字を表わします):

範囲

エンコーディング

U-00000000 ... U-0000007F

0xxxxxxx

U-00000080 ... U-000007FF

110xxxxx 10xxxxxx

U-00000800 ... U-0000FFFF

1110xxxx 10xxxxxx 10xxxxxx

U-00010000 ... U-0010FFFF

11110xxx 10xxxxxx 10xxxxxx 10xxxxxx

Unicode 文字の最下位ビットとは最も右にある x のビットです。

UTF-8 は8ビットエンコーディングなので BOM は必要とせず、デコードされた文字列中の U+FEFF は(たとえ最初の文字であったとしても) ZERO WIDTH NO-BREAK SPACE として扱われます。

外部からの情報無しには、文字列のエンコーディングにどのエンコーディングが使われたのか信頼できる形で決定することは不可能です。どの charmap エンコーディングもどんなランダムなバイト列でもデコードできます。しかし UTF-8 ではそれは可能ではありません。任意のバイト列を許さないような構造を持っているからです。UTF-8 エンコーディングであることを検知する信頼性を向上させるために、Microsoft は Notepad プログラム用に UTF-8 の変種 (Python では "utf-8-sig" と呼んでいます) を考案しました。Unicode 文字がファイルに書き込まれる前に UTF-8 でエンコードした BOM (バイト列では 0xef, 0xbb, 0xbf のように見えます) が書き込まれます。このようなバイト値で charmap エンコードされたファイルが始まることはほとんどあり得ない (たとえば iso-8859-1 では

LATIN SMALL LETTER I WITH DIAERESIS

RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK

INVERTED QUESTION MARK

のようになる)ので、utf-8-sig エンコーディングがバイト列から正しく推測される確率を高めます。つまりここでは BOM はバイト列を生成する際のバイト順を決定できるように使われているのではなく、エンコーディングを推測する助けになる印として使われているのです。utf-8-sig codec はエンコーディングの際ファイルに最初の3文字として 0xef, 0xbb, 0xbf を書き込みます。デコーディングの際はファイルの先頭に現れたこれら3バイトはスキップします。UTF-8 では BOM の使用は推奨されておらず、一般的には避けるべきです。

標準エンコーディング

Python には数多くの codec が組み込みで付属します。これらは C 言語の関数、対応付けを行うテーブルの両方で提供されています。以下のテーブルでは codec と、いくつかの良く知られている別名と、エンコーディングが使われる言語を列挙します。別名のリスト、言語のリストともしらみつぶしに網羅されているわけではありません。大文字と小文字、またはアンダースコアの代りにハイフンにしただけの綴りも有効な別名です; そのため、例えば 'utf-8' は 'utf_8' codec の正当な別名です。

CPython 実装の詳細: いくつかの一般的なエンコーディングは、パフォーマンスを改善するために codec の検索機構を回避することがあります。このような最適化の機会を認識するのは、 CPython の限定された (大文字小文字を区別しない) 別名に対してのみです: utf-8, utf8, latin-1, latin1, iso-8859-1, iso8859-1, mbcs (Windows のみ), ascii, us-ascii, utf-16, utf16, utf-32, utf32 およびダッシュの代わりにアンダースコアを用いたもの。これらのエンコーディングの別のつづりを使用すると実行時間の低下を招くかもしれません。

バージョン 3.6 で変更: us-ascii に対して最適化の機会が認識されるようになりました。

多くの文字セットは同じ言語をサポートしています。これらの文字セットは個々の文字 (例えば、EURO SIGN がサポートされているかどうか) や、文字のコード部分への割り付けが異なります。特に欧州言語では、典型的に以下の変種が存在します:

ISO 8859 コードセット

Microsoft Windows コードページで、8859 コード形式から導出されているが、制御文字を追加のグラフィック文字と置き換えたもの

IBM EBCDIC コードページ

ASCII 互換の IBM PC コードページ

Codec

別名

言語

ascii

646, us-ascii

英語

big5

big5-tw, csbig5

繁体字中国語

big5hkscs

big5-hkscs, hkscs

繁体字中国語

cp037

IBM037, IBM039

英語

cp273

273, IBM273, csIBM273

ドイツ語

Added in version 3.4.

cp424

EBCDIC-CP-HE, IBM424

ヘブライ語

cp437

437, IBM437

英語

cp500

EBCDIC-CP-BE, EBCDIC-CP-CH, IBM500

西ヨーロッパ言語

cp720

アラビア語

cp737

ギリシャ語

cp775

IBM775

バルト沿岸国

cp850

850, IBM850

西ヨーロッパ言語

cp852

852, IBM852

中央および東ヨーロッパ

cp855

855, IBM855

ブルガリア、ベラルーシ、マケドニア、ロシア、セルビア

cp856

ヘブライ語

cp857

857, IBM857

トルコ語

cp858

858, IBM858

西ヨーロッパ言語

cp860

860, IBM860

ポルトガル語

cp861

861, CP-IS, IBM861

アイスランド語

cp862

862, IBM862

ヘブライ語

cp863

863, IBM863

カナダ

cp864

IBM864

アラビア語

cp865

865, IBM865

デンマーク、ノルウェー

cp866

866, IBM866

ロシア語

cp869

869, CP-GR, IBM869

ギリシャ語

cp874

タイ語

cp875

ギリシャ語

cp932

932, ms932, mskanji, ms-kanji

日本語

cp949

949, ms949, uhc

韓国語

cp950

950, ms950

繁体字中国語

cp1006

Urdu

cp1026

ibm1026

トルコ語

cp1125

1125, ibm1125, cp866u, ruscii

ウクライナ語

Added in version 3.4.

cp1140

ibm1140

西ヨーロッパ言語

cp1250

windows-1250

中央および東ヨーロッパ

cp1251

windows-1251

ブルガリア、ベラルーシ、マケドニア、ロシア、セルビア

cp1252

windows-1252

西ヨーロッパ言語

cp1253

windows-1253

ギリシャ語

cp1254

windows-1254

トルコ語

cp1255

windows-1255

ヘブライ語

cp1256

windows-1256

アラビア語

cp1257

windows-1257

バルト沿岸国

cp1258

windows-1258

ベトナム

euc_jp

eucjp, ujis, u-jis

日本語

euc_jis_2004

jisx0213, eucjis2004

日本語

euc_jisx0213

eucjisx0213

日本語

euc_kr

euckr, korean, ksc5601, ks_c-5601, ks_c-5601-1987, ksx1001, ks_x-1001

韓国語

gb2312

chinese, csiso58gb231280, euc-cn, euccn, eucgb2312-cn, gb2312-1980, gb2312-80, iso-ir-58

簡体字中国語

gbk

936, cp936, ms936

Unified Chinese

gb18030

gb18030-2000

Unified Chinese

hz

hzgb, hz-gb, hz-gb-2312

簡体字中国語

iso2022_jp

csiso2022jp, iso2022jp, iso-2022-jp

日本語

iso2022_jp_1

iso2022jp-1, iso-2022-jp-1

日本語

iso2022_jp_2

iso2022jp-2, iso-2022-jp-2

日本語, 韓国語, 簡体字中国語, 西欧, ギリシャ語

iso2022_jp_2004

iso2022jp-2004, iso-2022-jp-2004

日本語

iso2022_jp_3

iso2022jp-3, iso-2022-jp-3

日本語

iso2022_jp_ext

iso2022jp-ext, iso-2022-jp-ext

日本語

iso2022_kr

csiso2022kr, iso2022kr, iso-2022-kr

韓国語

latin_1

iso-8859-1, iso8859-1, 8859, cp819, latin, latin1, L1

西ヨーロッパ言語

iso8859_2

iso-8859-2, latin2, L2

中央および東ヨーロッパ

iso8859_3

iso-8859-3, latin3, L3

エスペラント、マルタ

iso8859_4

iso-8859-4, latin4, L4

バルト沿岸国

iso8859_5

iso-8859-5, cyrillic

ブルガリア、ベラルーシ、マケドニア、ロシア、セルビア

iso8859_6

iso-8859-6, arabic

アラビア語

iso8859_7

iso-8859-7, greek, greek8

ギリシャ語

iso8859_8

iso-8859-8, hebrew

ヘブライ語

iso8859_9

iso-8859-9, latin5, L5

トルコ語

iso8859_10

iso-8859-10, latin6, L6

北欧語

iso8859_11

iso-8859-11, thai

タイ語

iso8859_13

iso-8859-13, latin7, L7

バルト沿岸国

iso8859_14

iso-8859-14, latin8, L8

ケルト語

iso8859_15

iso-8859-15, latin9, L9

西ヨーロッパ言語

iso8859_16

iso-8859-16, latin10, L10

南東ヨーロッパ

johab

cp1361, ms1361

韓国語

koi8_r

ロシア語

koi8_t

タジク

Added in version 3.5.

koi8_u

ウクライナ語

kz1048

kz_1048, strk1048_2002, rk1048

カザフ

Added in version 3.5.

mac_cyrillic

maccyrillic

ブルガリア、ベラルーシ、マケドニア、ロシア、セルビア

mac_greek

macgreek

ギリシャ語

mac_iceland

maciceland

アイスランド語

mac_latin2

maclatin2, maccentraleurope, mac_centeuro

中央および東ヨーロッパ

mac_roman

macroman, macintosh

西ヨーロッパ言語

mac_turkish

macturkish

トルコ語

ptcp154

csptcp154, pt154, cp154, cyrillic-asian

カザフ

shift_jis

csshiftjis, shiftjis, sjis, s_jis

日本語

shift_jis_2004

shiftjis2004, sjis_2004, sjis2004

日本語

shift_jisx0213

shiftjisx0213, sjisx0213, s_jisx0213

日本語

utf_32

U32, utf32

全ての言語

utf_32_be

UTF-32BE

全ての言語

utf_32_le

UTF-32LE

全ての言語

utf_16

U16, utf16

全ての言語

utf_16_be

UTF-16BE

全ての言語

utf_16_le

UTF-16LE

全ての言語

utf_7

U7, unicode-1-1-utf-7

全ての言語

utf_8

U8, UTF, utf8, cp65001

全ての言語

utf_8_sig

全ての言語

バージョン 3.4 で変更: utf-16* と utf-32* のエンコーダは、サロゲートコードポイント (U+D800--U+DFFF) がエンコードされることを許可しなくなりました。utf-32* デコーダは、サロゲートコードポイントに対応するバイト列をデコードしなくなりました。

バージョン 3.8 で変更: cp65001 is now an alias to utf_8.

Python 特有のエンコーディング

予め定義された codec のいくつかは Python 特有のものなので、それらの codec 名は Python の外では無意味なものとなります。以下に、想定されている入出力のタイプに基づいて、それらを表にしました（テキストエンコーディングは codec の最も一般的な使用例ですが、その根底にある codec 基盤は、ただのテキストエンコーディングというよりも、任意のデータの変換をサポートしていることに注意してください）。非対称的な codec については、記載された意味がエンコーディングの方向を説明しています。

テキストエンコーディング

次の codec では、 Unicode におけるテキストエンコーディングと同様に、 str から bytes へのエンコードと、 bytes-like object から str へのデコードを提供します。

Codec

別名

意味

idna

RFC 3490 [https://datatracker.ietf.org/doc/html/rfc3490.html] の実装です。 encodings.idna も参照してください。 errors='strict' のみがサポートされています。

mbcs

ansi, dbcs

Windows のみ: 被演算子を ANSI コードページ (CP_ACP) に従ってエンコードします。

oem

Windows のみ: 被演算子を OEM コードページ (CP_OEMCP) に従ってエンコードします。

Added in version 3.6.

palmos

PalmOS 3.5 のエンコーディングです。

punycode

RFC 3492 [https://datatracker.ietf.org/doc/html/rfc3492.html] の実装です。ステートフル codecs は、サポートされません。

raw_unicode_escape

Latin-1 encoding with \uXXXX and \UXXXXXXXX for other code points. Existing backslashes are not escaped in any way. It is used in the Python pickle protocol.

undefined

空文字列を含む全ての変換に対して例外を送出します。エラーハンドラは無視されます。

unicode_escape

ASCII でエンコードされた Python ソースコード内の、Unicode リテラルに適したエンコーディングです。ただし、引用符はエスケープされません。Latin-1 ソースコードからデコードします。実際には、Python のソースコードはデフォルトでは UTF-8 を使用することに注意してください。

バージョン 3.8 で変更: "unicode_internal" codec is removed.

バイナリ変換 (Binary Transforms)

以下の codec は、bytes-like object から bytes マッピングへのバイナリ変換を提供します。bytes.decode() はこの変換をサポートしておらず、 str を出力するだけです。

Codec

別名

意味

エンコーダ / デコーダ

base64_codec [1]

base64, base_64

被演算子をマルチラインの MIME base64 に変換します (結果は常に末尾の '\n' を含みます)。

バージョン 3.4 で変更: 任意の bytes-like object をエンコードとデコード用の入力として受け取ります。

base64.encodebytes() / base64.decodebytes()

bz2_codec

bz2

被演算子をbz2を使って圧縮します。

bz2.compress() / bz2.decompress()

hex_codec

hex

被演算子をバイトあたり 2 桁の 16 進数の表現に変換します。

binascii.b2a_hex() / binascii.a2b_hex()

quopri_codec

quopri, quotedprintable, quoted_printable

被演算子を MIME quoted printable 形式に変換します。

quotetabs=True を指定した quopri.encode() / quopri.decode()

uu_codec

uu

被演算子を uuencode を用いて変換します。

uu.encode() / uu.decode() (Note: uu is deprecated.)

zlib_codec

zip, zlib

被演算子を gzip を用いて圧縮します。

zlib.compress() / zlib.decompress()

[1]

バイト様オブジェクト に加えて、'base64_codec' も str の ASCII のみのインスタンスをデコード用に受け入れるようになりました

Added in version 3.2: バイナリ変換が復活しました。(訳注: 2.x にはあったものが 3.0 で削除されていた。)

バージョン 3.4 で変更: バイナリ変換のエイリアスが復活しました。(訳注: 2.x にはあったエイリアス。3.2 でエイリアスは復活しなかった。)

テキスト変換 (Text Transforms)

以下の codec は、str から str マッピングへのテキスト変換を提供します。str.encode() はこの変換をサポートしておらず、 bytes を出力するだけです。

Codec

別名

意味

rot_13

rot13

被演算子のシーザー暗号 (Caesar-cypher) を返します。

Added in version 3.2: rot_13 テキスト変換が復活しました。(訳注: 2.x にはあったものが 3.0 で削除されていた。)

バージョン 3.4 で変更: rot13 エイリアスが復活しました。(訳注: 2.x にはあったエイリアス。3.2 でエイリアスは復活しなかった。)

encodings.idna --- アプリケーションにおける国際化ドメイン名 (IDNA)

このモジュールでは RFC 3490 [https://datatracker.ietf.org/doc/html/rfc3490.html] (アプリケーションにおける国際化ドメイン名、 IDNA: Internationalized Domain Names in Applications) および RFC 3492 [https://datatracker.ietf.org/doc/html/rfc3492.html] (Nameprep: 国際化ドメイン名 (IDN) のための stringprep プロファイル) を実装しています。このモジュールは punycode エンコーディングおよび stringprep の上に構築されています。

If you need the IDNA 2008 standard from RFC 5891 [https://datatracker.ietf.org/doc/html/rfc5891.html] and RFC 5895 [https://datatracker.ietf.org/doc/html/rfc5895.html], use the third-party idna [https://pypi.org/project/idna/] module.

これらの RFC はともに、非 ASCII 文字の入ったドメイン名をサポートするためのプロトコルを定義しています。 (www.Alliancefrançaise.nu のような) 非 ASCII 文字を含むドメイン名は、 ASCII と互換性のあるエンコーディング (ACE、 www.xn--alliancefranaise-npb.nu のような形式) に変換されます。ドメイン名の ACE 形式は、 DNS クエリ、 HTTP Host フィールドなどといった、プロトコル中で任意の文字を使えないような全ての局面で用いられます。この変換はアプリケーション内で行われます; 可能ならユーザからは不可視となります: アプリケーションは Unicode ドメインラベルをネットワークに載せる際に IDNA に、 ACE ドメインラベルをユーザに提供する前に Unicode に、それぞれ透過的に変換しなければなりません。

Python ではこの変換をいくつかの方法でサポートします: idna codec は Unicode と ACE 間の変換を行い、入力文字列を RFC 3490 の section 3.1 [https://datatracker.ietf.org/doc/html/rfc3490.html#section-3.1] で定義されている区切り文字に基づいてラベルに分解し、各ラベルを要求通りに ACE に変換します。逆に、入力のバイト文字列を . 区切り文字でラベルに分解し、 ACE ラベルを Unicode に変換します。さらに、 socket モジュールは Unicode ホスト名を ACE に透過的に変換するため、アプリケーションはホスト名を socket モジュールに渡す際にホスト名の変換に煩わされることがありません。その上で、ホスト名を関数パラメタとして持つ、 http.client や ftplib のようなモジュールでは Unicode ホスト名を受理します (http.client でもまた、 Host フィールドにある IDNA ホスト名を、フィールド全体を送信する場合に透過的に送信します)。

(逆引きなどによって) ネットワーク越しにホスト名を受信する際、Unicode への自動変換は行われません: こうしたホスト名をユーザに提供したいアプリケーションでは、Unicode にデコードしてやる必要があります。

encodings.idna ではまた、 nameprep 手続きを実装しています。 nameprep はホスト名に対してある正規化を行って、国際化ドメイン名で大小文字を区別しないようにするとともに、類似の文字を一元化します。 nameprep 関数は必要なら直接使うこともできます。

encodings.idna.nameprep(label)

label を nameprep したバージョンを返します。現在の実装ではクエリ文字列を仮定しているので、AllowUnassigned は真です。

encodings.idna.ToASCII(label)

RFC 3490 [https://datatracker.ietf.org/doc/html/rfc3490.html] 仕様に従ってラベルを ASCIIに変換します。 UseSTD3ASCIIRules は偽であると仮定します。

encodings.idna.ToUnicode(label)

RFC 3490 [https://datatracker.ietf.org/doc/html/rfc3490.html] 仕様に従ってラベルを Unicode に変換します。

encodings.mbcs --- Windows ANSI コードページ

This module implements the ANSI codepage (CP_ACP).

利用可能な環境: Windows 。

バージョン 3.2 で変更: 3.2 以前は errors 引数は無視されました; エンコードには常に 'replace' が、デコードには 'ignore' が使われました。

バージョン 3.3 で変更: 任意のエラーハンドラのサポート。

encodings.utf_8_sig --- BOM 印付き UTF-8

このモジュールは UTF-8 codec の変種を実装します。エンコーディング時は、UTF-8 でエンコードしたバイト列の前に UTF-8 でエンコードした BOM を追加します。これは内部状態を持つエンコーダで、この動作は (バイトストリームの最初の書き込み時に) 一度だけ行なわれます。デコーディング時は、データの最初に UTF-8 でエンコードされた BOM があれば、それをスキップします。

データ型

この章で解説されるモジュールは日付や時間、型が固定された配列、ヒープキュー、両端キュー、列挙型のような種々の特殊なデータ型を提供します。

Python にはその他にもいくつかの組み込みデータ型があります。特に、 dict 、 list 、 set 、 frozenset 、そして tuple があります。 str クラスは Unicode データを扱うことができ、 bytes と bytearray クラスはバイナリデータを扱うことができます。

この章では以下のモジュールが記述されています:

datetime --- Basic date and time types

Aware オブジェクトと Naive オブジェクト

定数

利用可能なデータ型

共通の特徴

オブジェクトが Aware なのか Naive なのかの判断

timedelta オブジェクト

使用例: timedelta

date オブジェクト

使用例: date

datetime オブジェクト

使用例: datetime

time オブジェクト

使用例: time

tzinfo オブジェクト

timezone オブジェクト

strftime() と strptime() の振る舞い

strftime() と strptime() の書式コード

技術詳細

zoneinfo --- IANA time zone support

ZoneInfo を使用する

データソース

Configuring the data sources

Compile-time configuration

Environment configuration

Runtime configuration

ZoneInfo クラス

文字列表現

Pickle serialization

関数

Globals

例外と警告

calendar --- General calendar-related functions

コマンドラインからの使用

collections --- Container datatypes

ChainMap オブジェクト

ChainMap の例とレシピ

Counter オブジェクト

deque オブジェクト

deque のレシピ

defaultdict オブジェクト

defaultdict の使用例

namedtuple() 名前付きフィールドを持つタプルのファクトリ関数

OrderedDict オブジェクト

OrderedDict の例とレシピ

UserDict オブジェクト

UserList オブジェクト

UserString オブジェクト

collections.abc --- Abstract Base Classes for Containers

コレクション抽象基底クラス

コレクションの抽象基底クラス -- 詳細な説明

例とレシピ

heapq --- Heap queue algorithm

基本的な例

優先度キュー実装の注釈

理論

bisect --- Array bisection algorithm

パフォーマンスに関するメモ

ソート済みリストの探索

使用例

array --- Efficient arrays of numeric values

weakref --- 弱参照

弱参照オブジェクト

使用例

ファイナライザオブジェクト

Comparing finalizers with __del__() methods

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

動的な型生成

標準的なインタプリタ型

追加のユーティリティクラスと関数

コルーチンユーティリティ関数

copy --- Shallow and deep copy operations

pprint --- Data pretty printer

関数

PrettyPrinter オブジェクト

使用例

reprlib --- Alternate repr() implementation

Reprオブジェクト

Reprオブジェクトをサブクラス化する

enum --- Support for enumerations

モジュールコンテンツ

データ型

__dunder__ 名のサポート

_sunder_ 名のサポート

ユーティリティとデコレータ

注釈

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

例外

datetime --- Basic date and time types

ソースコード: Lib/datetime.py [https://github.com/python/cpython/tree/3.12/Lib/datetime.py]

datetime モジュールは、日付や時刻を操作するためのクラスを提供しています。

日付や時刻に対する算術がサポートされている一方、実装では出力のフォーマットや操作のための効率的な属性の抽出に重点を置いています。

Tip

書式コード に飛ぶ。

参考

calendar モジュール

汎用のカレンダー関連関数。

time モジュール

時刻へのアクセスと変換。

zoneinfo モジュール

IANAタイムゾーンデータベースを表す具体的なタイムゾーン。

dateutil [https://dateutil.readthedocs.io/en/stable/] パッケージ

拡張タイムゾーンと構文解析サポートのあるサードパーティーライブラリ。

Package DateType [https://pypi.org/project/DateType/]

Third-party library that introduces distinct static types to e.g. allow static type checkers to differentiate between naive and aware datetimes.

Aware オブジェクトと Naive オブジェクト

日時のオブジェクトは、それらがタイムゾーンの情報を含んでいるかどうかによって "aware" あるいは "naive" に分類されます。

タイムゾーンや夏時間の情報のような、アルゴリズム的で政治的な適用可能な時間調節に関する知識を持っているため、 aware オブジェクトは他の aware オブジェクトとの相対関係を特定できます。 aware オブジェクトは解釈の余地のない特定の実時刻を表現します。 [1]

naive オブジェクトには他の日付時刻オブジェクトとの相対関係を把握するのに足る情報が含まれません。あるプログラム内の数字がメートルを表わしているのか、マイルなのか、それとも質量なのかがプログラムによって異なるように、naive オブジェクトが協定世界時 (UTC) なのか、現地時間なのか、それとも他のタイムゾーンなのかはそのプログラムに依存します。Naive オブジェクトはいくつかの現実的な側面を無視してしまうというコストを無視すれば、簡単に理解でき、うまく利用することができます。

aware オブジェクトを必要とするアプリケーションのために、 datetime と time オブジェクトは追加のタイムゾーン情報の属性 tzinfo を持ちます。 tzinfo には抽象クラス tzinfo のサブクラスのインスタンスを設定できます。これらの tzinfo オブジェクトは UTC 時間からのオフセットやタイムゾーンの名前、夏時間が実施されるかどうかの情報を保持しています。

ただ一つの具象 tzinfo クラスである timezone クラスが datetime モジュールで提供されています。 timezone クラスは、UTCからのオフセットが固定である単純なタイムゾーン（例えばUTCそれ自体）、および北アメリカにおける東部標準時（EST）／東部夏時間（EDT）のような単純ではないタイムゾーンの両方を表現できます。より深く詳細までタイムゾーンをサポートするかはアプリケーションに依存します。世界中の時刻の調整を決めるルールは合理的というよりかは政治的なもので、頻繁に変わり、UTC を除くと都合のよい基準というものはありません。

定数

datetime モジュールでは以下の定数を公開しています:

datetime.MINYEAR

The smallest year number allowed in a date or datetime object. MINYEAR is 1.

datetime.MAXYEAR

The largest year number allowed in a date or datetime object. MAXYEAR is 9999.

datetime.UTC

UTCタイムゾーンシングルトン datetime.timezone.utc の別名。

Added in version 3.11.

利用可能なデータ型

class datetime.date

理想的な naive な日付で、これまでもこれからも現在のグレゴリオ暦 (Gregorian calender) が有効であることを仮定しています。属性は year, month,および day です。

class datetime.time

理想的な時刻で、特定の日から独立しており、毎日が厳密に 24*60*60 秒であると仮定しています。("うるう秒: leap seconds" の概念はありません。) 属性は hour, minute, second, microsecond, および tzinfo です。

class datetime.datetime

日付と時刻を組み合わせたものです。属性は year, month, day, hour, minute, second, microsecond, および tzinfo です。

class datetime.timedelta

datetime あるいは date クラスの二つのインスタンス間の時間差をマイクロ秒精度で表す経過時間値です。

class datetime.tzinfo

タイムゾーン情報オブジェクトの抽象基底クラスです。 datetime および time クラスで用いられ、カスタマイズ可能な時刻修正の概念 (たとえばタイムゾーンや夏時間の計算) を提供します。

class datetime.timezone

tzinfo 抽象基底クラスを UTC からの固定オフセットとして実装するクラスです。

Added in version 3.2.

これらの型のオブジェクトは変更不可能 (immutable) です。

サブクラスの関係は以下のようになります:

object
    timedelta
    tzinfo
        timezone
    time
    date
        datetime

共通の特徴

date 型、datetime 型、time 型、timezone 型には共通する特徴があります:

これらの型のオブジェクトは変更不可能 (immutable) です。

これらの型のオブジェクトは ハッシュ可能 であり、辞書のキーとして使えることになります。

これらの型のオブジェクトは pickle モジュールを利用して効率的な pickle 化をサポートしています。

オブジェクトが Aware なのか Naive なのかの判断

date 型のオブジェクトは常に naive です。

time 型あるいは datetime 型のオブジェクトは aware か naive のどちらかです。

次の条件を両方とも満たす場合、 datetime オブジェクト d は aware です:

d.tzinfo が None でない

d.tzinfo.utcoffset(d) が None を返さない

どちらかを満たさない場合は、 d は naive です。

次の条件を両方とも満たす場合、 time オブジェクト t は aware です:

t.tzinfo が None でない

t.tzinfo.utcoffset(None) が None を返さない

どちらかを満たさない場合は、 t は naive です。

aware なオブジェクトと naive なオブジェクトの区別は timedelta オブジェクトにはあてはまりません。

timedelta オブジェクト

timedelta オブジェクトは経過時間、すなわち二つの datetime または date のインスタンスの差を表します。

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

days, seconds, microseconds だけが内部的に保持されます。引数は以下のようにして変換されます:

1 ミリ秒は 1000 マイクロ秒に変換されます。

1 分は 60 秒に変換されます。

1 時間は 3600 秒に変換されます。

1 週間は 7 日に変換されます。

さらに、値が一意に表されるように days, seconds, microseconds が以下のように正規化されます

0 <= microseconds < 1000000

0 <= seconds < 3600*24 (一日中の秒数)

-999999999 <= days <= 999999999

次の例は、 days, seconds, microseconds に加えて任意の引数がどう "集約" され、最終的に3つの属性に正規化されるかの説明をしています:

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

引数のいずれかが浮動小数点であり、小数のマイクロ秒が存在する場合、小数のマイクロ秒は全ての引数から一度取り置かれ、それらの和は最近接偶数のマイクロ秒に丸められます。浮動小数点の引数がない場合、値の変換と正規化の過程は厳密な (失われる情報がない) ものとなります。

日の値を正規化した結果、指定された範囲の外側になった場合には、 OverflowError が送出されます。

負の値を正規化すると、最初は混乱するような値になります。例えば:

>>> from datetime import timedelta
>>> d = timedelta(microseconds=-1)
>>> (d.days, d.seconds, d.microseconds)
(-1, 86399, 999999)

以下にクラス属性を示します:

timedelta.min

最小の値を表す timedelta オブジェクトで、 timedelta(-999999999) です。

timedelta.max

最大の値を表す timedelta オブジェクトで、 timedelta(days=999999999, hours=23, minutes=59, seconds=59, microseconds=999999) です。

timedelta.resolution

timedelta オブジェクトが等しくならない最小の時間差で、 timedelta(microseconds=1) です。

Note that, because of normalization, timedelta.max is greater than -timedelta.min. -timedelta.max is not representable as a timedelta object.

インスタンスの属性 (読み出しのみ):

属性

値

days

両端値を含む -999999999 から 999999999 の間

seconds

両端値を含む 0 から 86399 の間

microseconds

両端値を含む 0 から 999999 の間

サポートされている演算を以下に示します:

演算

結果

t1 = t2 + t3

Sum of t2 and t3. Afterwards t1 - t2 == t3 and t1 - t3 == t2 are true. (1)

t1 = t2 - t3

Difference of t2 and t3. Afterwards t1 == t2 - t3 and t2 == t1 + t3 are true. (1)(6)

t1 = t2 * i または t1 = i * t2

Delta multiplied by an integer. Afterwards t1 // i == t2 is true, provided i != 0.

In general, t1  * i == t1 * (i-1) + t1 is true. (1)

t1 = t2 * f または t1 = f * t2

時間差と浮動小数点の積。結果は最近接偶数への丸めを利用して最も近い timedelta.resolution の倍数に丸められます。

f = t2 / t3

Division (3) of overall duration t2 by interval unit t3. Returns a float object.

t1 = t2 / f または t1 = t2 / i

時間差を浮動小数点や整数で除したもの。結果は最近接偶数への丸めを利用して最も近い timedelta.resolution の倍数に丸められます。

t1 = t2 // i または t1 = t2 // t3

floor が計算され、余りは (もしあれば) 捨てられます。後者の場合、整数が返されます。(3)

t1 = t2 % t3

剰余が timedelta オブジェクトとして計算されます。(3)

q, r = divmod(t1, t2)

商と剰余が計算されます: q = t1 // t2 (3) と r = t1 % t2 。q は整数で r は timedelta オブジェクトです。

+t1

同じ値を持つ timedelta オブジェクトを返します。(2)

-t1

Equivalent to timedelta(-t1.days, -t1.seconds*, -t1.microseconds), and to t1 * -1. (1)(4)

abs(t)

Equivalent to +t when t.days >= 0, and to -t when t.days < 0. (2)

str(t)

[D day[s], ][H]H:MM:SS[.UUUUUU] という形式の文字列を返します。t が負の値の場合は D は負の値となります。(5)

repr(t)

timedelta オブジェクトの文字列表現を返します。その文字列は、正規の属性値を持つコンストラクタ呼び出しのコードになっています。

注釈:

この演算は正確ですが、オーバフローするかもしれません。

この演算は正確であり、オーバフローし得ません。

Division by zero raises ZeroDivisionError.

-timedelta.max is not representable as a timedelta object.

timedelta オブジェクトの文字列表現は内部表現に類似した形に正規化されます。そのため負の timedelta は少し変な結果になります。例えば:

>>> timedelta(hours=-5)
datetime.timedelta(days=-1, seconds=68400)
>>> print(_)
-1 day, 19:00:00

t3 が timedelta.max のときを除けば、式 t2 - t3 は常に、式 t2 + (-t3) と同等です。t3 が timedelta.max の場合、前者の式は結果の値が出ますが、後者はオーバーフローを起こします。

上に列挙した操作に加え timedelta オブジェクトは date および datetime オブジェクトとの間で加減算をサポートしています (下を参照してください)。

バージョン 3.2 で変更: timedelta オブジェクトの別の timedelta オブジェクトによる、切り捨て除算と真の除算、および剰余演算と divmod() 関数がサポートされるようになりました。 timedelta オブジェクトと float オブジェクトの真の除算と掛け算がサポートされるようになりました。

timedelta オブジェクトは等価性と順序の比較をサポートします。

ブール演算コンテキストでは、 timedelta オブジェクトは timedelta(0) に等しくない場合かつそのときに限り真となります。

インスタンスメソッド:

timedelta.total_seconds()

この期間に含まれるトータルの秒数を返します。td / timedelta(seconds=1) と等価です。秒以外の期間の単位では、直接に除算する形式 (例えば td / timedelta(microseconds=1)) が使われます。

非常に長い期間 (多くのプラットフォームでは270年以上) については、このメソッドはマイクロ秒の精度を失うことがあることに注意してください。

Added in version 3.2.

使用例: timedelta

正規化の追加の例です:

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

timedelta の計算の例です:

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

date オブジェクト

date オブジェクトは、両方向に無期限に拡張された現在のグレゴリオ暦という理想化された暦の日付 (年月日) を表します。

1 年 1 月 1 日は日番号 1、1 年 1 月 2 日は日番号 2 と呼ばれ、他も同様です。 [2]

class datetime.date(year, month, day)

全ての引数が必須です。引数は整数で、次の範囲に収まっていなければなりません:

MINYEAR <= year <= MAXYEAR

1 <= month <= 12

1 <= day <= 指定された月と年における日数

範囲を超えた引数を与えた場合、 ValueError が送出されます。

他のコンストラクタ、および全てのクラスメソッドを以下に示します:

classmethod date.today()

現在のローカルな日付を返します。

date.fromtimestamp(time.time()) と等価です。

classmethod date.fromtimestamp(timestamp)

time.time() で返されるような POSIX タイムスタンプに対応するローカルな日付を返します。

timestamp がプラットフォームの C 関数 localtime() がサポートする値の範囲から外れていた場合、 OverflowError を送出するかもしれません。また localtime() 呼び出しが失敗した場合には OSError を送出するかもしれません。この範囲は通常は 1970 年から 2038 年までに制限されています。タイムスタンプの表記にうるう秒を含める非 POSIX なシステムでは、うるう秒は fromtimestamp() では無視されます。

バージョン 3.3 で変更: timestamp がプラットフォームの C 関数 localtime() のサポートする値の範囲から外れていた場合、 ValueError ではなく OverflowError を送出するようになりました。 localtime() の呼び出し失敗で ValueError ではなく OSError を送出するようになりました。

classmethod date.fromordinal(ordinal)

先発グレゴリオ暦による序数に対応する日付を返します。 1 年 1 月 1 日が序数 1 となります。

1 <= ordinal <= date.max.toordinal() でない場合、 ValueError が送出されます。任意の日付 d に対し、 date.fromordinal(d.toordinal()) == d となります。

classmethod date.fromisoformat(date_string)

以下の例外を除く、有効な ISO 8601 フォーマットで与えられた date_string に対応する date を返します :

Reduced precision dates are not currently supported (YYYY-MM, YYYY).

Extended date representations are not currently supported (±YYYYYY-MM-DD).

序数の日付は現在サポートされていません(YYYY-OOO)。

例:

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

Added in version 3.7.

バージョン 3.11 で変更: 以前はこのメソッドは YYYY-MM-DD フォーマットのみをサポートしていました。

classmethod date.fromisocalendar(year, week, day)

年月日で指定された ISO 暦の日付に対応する date を返します。この関数は date.isocalendar() 関数の逆関数です。

Added in version 3.8.

以下にクラス属性を示します:

date.min

表現できる最も古い日付で、date(MINYEAR, 1, 1) です。

date.max

表現できる最も新しい日付で、date(MAXYEAR, 12, 31) です。

date.resolution

等しくない日付オブジェクト間の最小の差で、timedelta(days=1) です。

インスタンスの属性 (読み出しのみ):

date.year

両端値を含む MINYEAR から MAXYEAR までの値です。

date.month

両端値を含む 1 から 12 までの値です。

date.day

1 から与えられた月と年における日数までの値です。

サポートされている演算を以下に示します:

演算

結果

date2 = date1 + timedelta

date2 will be timedelta.days days after date1. (1)

date2 = date1 - timedelta

Computes date2 such that date2 + timedelta == date1. (2)

timedelta = date1 - date2

(3)

date1 == date2

date1 != date2

等価性の比較。(4)

date1 < date2

date1 > date2

date1 <= date2

date1 >= date2

順序の比較。(5)

注釈:

date2 は、 timedelta.days > 0 の場合は進む方向に、 timedelta.days < 0 の場合は戻る方向に移動します。演算後は date2 - date1 == timedelta.days が成立します。 timedelta.seconds および timedelta.microseconds は無視されます。 date2.year が MINYEAR になってしまったり、 MAXYEAR より大きくなってしまう場合には OverflowError が送出されます。

timedelta.seconds と timedelta.microseconds は無視されます。

This is exact, and cannot overflow. timedelta.seconds and timedelta.microseconds are 0, and date2 + timedelta == date1 after.

同じ日を表す date オブジェクトは等しいです。

date1 is considered less than date2 when date1 precedes date2 in time. In other words, date1 < date2 if and only if date1.toordinal() < date2.toordinal().

ブール演算コンテキストでは、全ての time オブジェクトは真とみなされます。

インスタンスメソッド:

date.replace(year=self.year, month=self.month, day=self.day)

キーワード引数で指定されたパラメータが置き換えられることを除き、同じ値を持つ date オブジェクトを返します。

以下はプログラム例です:

>>> from datetime import date
>>> d = date(2002, 12, 31)
>>> d.replace(day=26)
datetime.date(2002, 12, 26)

date.timetuple()

time.localtime() が返すような time.struct_time を返します。

時分秒が 0 で、 DST フラグが -1 です。

d.timetuple() は次の式と等価です:

time.struct_time((d.year, d.month, d.day, 0, 0, 0, d.weekday(), yday, -1))

where yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1 is the day number within the current year starting with 1 for January 1st.

date.toordinal()

先発グレゴリオ暦における日付序数を返します。 1 年の 1 月 1 日が序数 1 となります。任意の date オブジェクト d について、 date.fromordinal(d.toordinal()) == d となります。

date.weekday()

月曜日を 0、日曜日を 6 として、曜日を整数で返します。例えば、 date(2002, 12, 4).weekday() == 2 であり、水曜日を示します。 isoweekday() も参照してください。

date.isoweekday()

月曜日を 1,日曜日を 7 として、曜日を整数で返します。例えば、 date(2002, 12, 4).isoweekday() == 3 であり、水曜日を示します。 weekday(), isocalendar() も参照してください。

date.isocalendar()

year、week、weekday の3つで構成された named tuple を返します。

ISO 暦はグレゴリオ暦の変種として広く用いられています。 [3]

ISO 年は完全な週が 52 週または 53 週あり、週は月曜から始まって日曜に終わります。ISO 年でのある年における最初の週は、その年の木曜日を含む最初の (グレゴリオ暦での) 週となります。この週は週番号 1 と呼ばれ、この木曜日での ISO 年はグレゴリオ暦における年と等しくなります。

例えば、2004 年は木曜日から始まるため、ISO 年の最初の週は 2003 年 12 月 29 日、月曜日から始まり、2004 年 1 月 4 日、日曜日に終わります

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

バージョン 3.9 で変更: 結果が タプル から named tuple へ変更されました。

date.isoformat()

日付を ISO 8601 書式の YYYY-MM-DD で表した文字列を返します:

>>> from datetime import date
>>> date(2002, 12, 4).isoformat()
'2002-12-04'

date.__str__()

date オブジェクト d において、str(d) は d.isoformat() と等価です。

date.ctime()

日付を表す文字列を返します:

>>> from datetime import date
>>> date(2002, 12, 4).ctime()
'Wed Dec  4 00:00:00 2002'

d.ctime() は次の式と等価です:

time.ctime(time.mktime(d.timetuple()))

これが等価になるのは、 (time.ctime() に呼び出され、 date.ctime() に呼び出されない) ネイティブの C 関数 ctime() が C 標準に準拠しているプラットフォーム上でです。

date.strftime(format)

明示的な書式文字列で制御された、日付を表現する文字列を返します。時間、分、秒を表す書式コードは値 0 になります。 strftime() と strptime() の振る舞い および date.isoformat() も参照してください。

date.__format__(format)

date.strftime() と等価です。これにより、 フォーマット済み文字列リテラル の中や str.format() を使っているときに date オブジェクトの書式文字列を指定できます。 strftime() と strptime() の振る舞い および date.isoformat() も参照してください。

使用例: date

イベントまでの日数を数える例を示します:

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

さらなる date を使う例:

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

datetime オブジェクト

datetime オブジェクトは date オブジェクトおよび time オブジェクトの全ての情報が入っている単一のオブジェクトです。

date オブジェクトと同様に、 datetime は現在のグレゴリオ暦が両方向に延長されているものと仮定します。また、 time オブジェクトと同様に、 datetime は毎日が厳密に 3600*24 秒であると仮定します。

以下にコンストラクタを示します:

class datetime.datetime(year, month, day, hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)

year, month, day 引数は必須です。 tzinfo は None または tzinfo サブクラスのインスタンスです。残りの引数は次の範囲の整数でなければなりません:

MINYEAR <= year <= MAXYEAR,

1 <= month <= 12,

1 <= day <= 指定された月と年における日数,

0 <= hour < 24,

0 <= minute < 60,

0 <= second < 60,

0 <= microsecond < 1000000,

fold in [0, 1].

範囲を超えた引数を与えた場合、 ValueError が送出されます。

バージョン 3.6 で変更: fold パラメータが追加されました。

他のコンストラクタ、および全てのクラスメソッドを以下に示します:

classmethod datetime.today()

tzinfo を None にして、現在のローカルな日時を返します。

次と等価です:

datetime.fromtimestamp(time.time())

now(), fromtimestamp() も参照してください。

このメソッドの機能は now() と等価ですが、 tz 引数はありません。

classmethod datetime.now(tz=None)

現在のローカルな日時を返します。

オプションの引数 tz が None であるか指定されていない場合、このメソッドは today() と同様ですが、可能ならば time.time() タイムスタンプを通じて得ることができる、より高い精度で時刻を提供します (例えば、プラットフォームが C 関数 gettimeofday() をサポートする場合には可能なことがあります)。

tz が None でない場合、 tz は tzinfo のサブクラスのインスタンスでなければならず、現在の日付および時刻は tz のタイムゾーンに変換されます。

today() および utcnow() よりもこの関数を使う方が好ましいです。

classmethod datetime.utcnow()

tzinfo が None である現在の UTC の日付および時刻を返します。

このメソッドは now() と似ていますが、 naive な datetime オブジェクトとして現在の UTC 日付および時刻を返します。 aware な現在の UTC datetime は datetime.now(timezone.utc) を呼び出すことで取得できます。 now() も参照してください。

警告

naive な datetime オブジェクトは多くの datetime メソッドでローカルな時間として扱われるため、 aware な datetime を使って UTC の時刻を表すのが好ましいです。そのため、 UTC での現在の時刻を表すオブジェクトの作成では datetime.now(timezone.utc) を呼び出す方法が推奨されます。

バージョン 3.12 で非推奨: 代わりに UTC で datetime.now() を使用してください。

classmethod datetime.fromtimestamp(timestamp, tz=None)

time.time() が返すような、 POSIX タイムスタンプに対応するローカルな日付と時刻を返します。オプションの引数 tz が None であるか、指定されていない場合、タイムスタンプはプラットフォームのローカルな日付および時刻に変換され、返される datetime オブジェクトは naive なものになります。

tz が None でない場合、 tz は tzinfo のサブクラスのインスタンスでなければならず、タイムスタンプは tz のタイムゾーンに変換されます。

タイムスタンプがプラットフォームの C 関数 localtime() や gmtime() でサポートされている範囲を超えた場合、 fromtimestamp() は OverflowError を送出することがあります。この範囲はよく 1970 年から 2038 年に制限されています。また localtime() や gmtime() が失敗した際は OSError を送出します。うるう秒がタイムスタンプの概念に含まれている非 POSIX システムでは、 fromtimestamp() はうるう秒を無視します。このため、秒の異なる二つのタイムスタンプが同一の datetime オブジェクトとなることが起こり得ます。 utcfromtimestamp() よりも、このメソッドの方が好ましいです。

バージョン 3.3 で変更: timestamp がプラットフォームの C 関数 localtime() もしくは gmtime() のサポートする値の範囲から外れていた場合、 ValueError ではなく OverflowError を送出するようになりました。 localtime() もしくは gmtime() の呼び出し失敗で ValueError ではなく OSError を送出するようになりました。

バージョン 3.6 で変更: fromtimestamp() は fold を1にしてインスタンスを返します。

classmethod datetime.utcfromtimestamp(timestamp)

POSIX タイムスタンプに対応する、tzinfo が None の UTC での datetime を返します。(返されるオブジェクトは naive です。)

タイムスタンプがプラットフォームにおける C 関数 localtime() でサポートされている範囲を超えている場合には OverflowError を、gmtime() が失敗した場合には OSError を送出します。これはたいてい 1970 年から 2038 年に制限されています。

aware な datetime オブジェクトを得るには fromtimestamp() を呼んでください:

datetime.fromtimestamp(timestamp, timezone.utc)

POSIX 互換プラットフォームでは、これは以下の表現と等価です:

datetime(1970, 1, 1, tzinfo=timezone.utc) + timedelta(seconds=timestamp)

後者を除き、式は常に年の全範囲 (MINYEAR から MAXYEAR を含みます) をサポートします。

警告

naive な datetime オブジェクトは多くの datetime メソッドでローカルな時間として扱われるため、 aware な datetime を使って UTC の時刻を表すのが好ましいです。そのため、 UTC でのある特定のタイムスタンプを表すオブジェクトの作成では datetime.fromtimestamp(timestamp, tz=timezone.utc) を呼び出す方法が推奨されます。

バージョン 3.3 で変更: timestamp がプラットフォームの C 関数 gmtime() のサポートする値の範囲から外れていた場合、 ValueError ではなく OverflowError を送出するようになりました。 gmtime() の呼び出し失敗で ValueError ではなく OSError を送出するようになりました。

バージョン 3.12 で非推奨: 代わりに UTC で datetime.fromtimestamp() を使用してください。

classmethod datetime.fromordinal(ordinal)

1 年 1 月 1 日を序数 1 とする早期グレゴリオ暦序数に対応する datetime オブジェクトを返します。 1 <= ordinal <= datetime.max.toordinal() でなければ ValueError が送出されます。返されるオブジェクトの時間、分、秒、およびマイクロ秒はすべて 0 で、 tzinfo は None となっています。

classmethod datetime.combine(date, time, tzinfo=time.tzinfo)

日付部分と与えられた date オブジェクトとが等しく、時刻部分と与えられた time オブジェクトとが等しい、新しい datetime オブジェクトを返します。 tzinfo 引数が与えられた場合、その値は返り値の tzinfo 属性に設定するのに使われます。そうでない場合、 time 引数の tzinfo 属性が使われます。date 引数に datetime オブジェクトが与えられた場合、その時刻部分と tzinfo 属性は無視されます。

任意の datetime オブジェクト d に対して、d == datetime.combine(d.date(), d.time(), d.tzinfo) となります。

バージョン 3.6 で変更: tzinfo 引数が追加されました。

classmethod datetime.fromisoformat(date_string)

以下の例外を除く、有効な ISO 8601 フォーマットで与えられた date_string に対応する datetime を返します :

小数の秒があるタイムゾーンオフセット。

T セパレーターを他の1文字のユニコードに置き換えたもの。

少数の時と分はサポートされていません。

Reduced precision dates are not currently supported (YYYY-MM, YYYY).

Extended date representations are not currently supported (±YYYYYY-MM-DD).

序数の日付は現在サポートされていません(YYYY-OOO)。

例:

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

Added in version 3.7.

バージョン 3.11 で変更: 以前は、このメソッドは date.isoformat() または datetime.isoformat() から出力されるフォーマットのみをサポートしていました。

classmethod datetime.fromisocalendar(year, week, day)

年月日で指定された ISO 暦の日付に対応する datetime を返します。 datetime の日付でない部分は、標準のデフォルト値で埋められます。この関数は datetime.isocalendar() の逆関数です。

Added in version 3.8.

classmethod datetime.strptime(date_string, format)

date_string に対応した datetime を返します。 format にしたがって構文解析されます。

format がマイクロ秒やタイムゾーン情報を含まない場合は、以下と等価です:

datetime(*(time.strptime(date_string, format)[0:6]))

date_string と format が time.strptime() で構文解析できない場合や、この関数が時刻タプルを返してこない場合には ValueError を送出します。strftime() と strptime() の振る舞い および datetime.fromisoformat() も参照してください。

以下にクラス属性を示します:

datetime.min

表現できる最も古い datetime で、 datetime(MINYEAR, 1, 1, tzinfo=None) です。

datetime.max

表現できる最も新しい datetime で、 datetime(MAXYEAR, 12, 31, 23, 59, 59, 999999, tzinfo=None) です。

datetime.resolution

等しくない datetime オブジェクト間の最小の差で、 timedelta(microseconds=1) です。

インスタンスの属性 (読み出しのみ):

datetime.year

両端値を含む MINYEAR から MAXYEAR までの値です。

datetime.month

両端値を含む 1 から 12 までの値です。

datetime.day

1 から与えられた月と年における日数までの値です。

datetime.hour

in range(24) を満たします。

datetime.minute

in range(60) を満たします。

datetime.second

in range(60) を満たします。

datetime.microsecond

in range(1000000) を満たします。

datetime.tzinfo

datetime コンストラクタに tzinfo 引数として与えられたオブジェクトになり、何も渡されなかった場合には None になります。

datetime.fold

In [0, 1]. Used to disambiguate wall times during a repeated interval. (A repeated interval occurs when clocks are rolled back at the end of daylight saving time or when the UTC offset for the current zone is decreased for political reasons.) The values 0 and 1 represent, respectively, the earlier and later of the two moments with the same wall time representation.

Added in version 3.6.

サポートされている演算を以下に示します:

演算

結果

datetime2 = datetime1 + timedelta

(1)

datetime2 = datetime1 - timedelta

(2)

timedelta = datetime1 - datetime2

(3)

datetime1 == datetime2

datetime1 != datetime2

等価性の比較。(4)

datetime1 < datetime2

datetime1 > datetime2

datetime1 <= datetime2

datetime1 >= datetime2

順序の比較。(5)

datetime2 is a duration of timedelta removed from datetime1, moving forward in time if timedelta.days > 0, or backward if timedelta.days < 0. The result has the same tzinfo attribute as the input datetime, and datetime2 - datetime1 == timedelta after. OverflowError is raised if datetime2.year would be smaller than MINYEAR or larger than MAXYEAR. Note that no time zone adjustments are done even if the input is an aware object.

Computes the datetime2 such that datetime2 + timedelta == datetime1. As for addition, the result has the same tzinfo attribute as the input datetime, and no time zone adjustments are done even if the input is aware.

datetime から datetime の減算は両方の被演算子が naive であるか、両方とも aware である場合にのみ定義されています。片方が aware でもう一方が naive の場合、 TypeError が送出されます。

両方とも naive か、両方とも aware で同じ tzinfo 属性を持つ場合、 tzinfo 属性は無視され、結果は datetime2 + t == datetime1 であるような timedelta オブジェクト t となります。この場合タイムゾーン修正は全く行われません。

両方が aware で異なる tzinfo 属性を持つ場合、 a-b は a および b をまず naive な UTC datetime オブジェクトに変換したかのようにして行います。演算結果は決してオーバフローを起こさないことを除き、 (a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None) - b.utcoffset()) と同じになります。

datetime オブジェクトはタイムゾーンを考慮して同じ日付と時刻を表す場合、等しいです。

Naive and aware datetime objects are never equal. datetime objects are never equal to date objects that are not also datetime instances, even if they represent the same date.

If both comparands are aware, and have the same tzinfo attribute, the tzinfo and fold attributes are ignored and the base datetimes are compared. If both comparands are aware and have different tzinfo attributes, the comparison acts as comparands were first converted to UTC datetimes except that the implementation never overflows. datetime instances in a repeated interval are never equal to datetime instances in other time zone.

タイムゾーンを考慮して、datetime1 が時刻として datetime2 よりも前を表す場合に、datetime1 は datetime2 よりも小さいと見なされます。

Order comparison between naive and aware datetime objects, as well as a datetime object and a date object that is not also a datetime instance, raises TypeError.

If both comparands are aware, and have the same tzinfo attribute, the tzinfo and fold attributes are ignored and the base datetimes are compared. If both comparands are aware and have different tzinfo attributes, the comparison acts as comparands were first converted to UTC datetimes except that the implementation never overflows.

バージョン 3.3 で変更: aware な datetime インスタンスと naive な datetime インスタンスの等価比較では TypeError は送出されません。

インスタンスメソッド:

datetime.date()

同じ年、月、日の date オブジェクトを返します。

datetime.time()

同じhour、minute、second、microsecond 及び foldを持つ time オブジェクトを返します。 tzinfo は None です。 timetz() も参照してください。

バージョン 3.6 で変更: 値 foldは返される time オブジェクトにコピーされます。

datetime.timetz()

同じhour、minute、second、microsecond、fold および tzinfo 属性を持つ time オブジェクトを返します。 time() メソッドも参照してください。

バージョン 3.6 で変更: 値 foldは返される time オブジェクトにコピーされます。

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)

キーワード引数で指定した属性の値を除き、同じ属性をもつ datetime オブジェクトを返します。メンバに対する変換を行わずに aware な datetime オブジェクトから naive な datetime オブジェクトを生成するために、tzinfo=None を指定することもできます。

バージョン 3.6 で変更: fold パラメータが追加されました。

datetime.astimezone(tz=None)

tz を新たに tzinfo 属性 として持つ datetime オブジェクトを返します。日付および時刻データを調整して、返り値が self と同じ UTC 時刻を持ち、 tz におけるローカルな時刻を表すようにします。

もし与えられた場合、 tz は tzinfo のサブクラスのインスタンスでなければならず、 インスタンスの utcoffset() および dst() メソッドは None を返してはなりません。もし self が naive ならば、おそらくシステムのタイムゾーンで時間を表現します。

引数無し (もしくは tz=None の形 ) で呼び出された場合、システムのローカルなタイムゾーンが変更先のタイムゾーンだと仮定されます。変換後の datetime インスタンスの .tzinfo 属性には、 OS から取得したゾーン名とオフセットを持つ timezone インスタンスが設定されます。

self.tzinfo が tz の場合、 self.astimezone(tz) は self に等しくなります。つまり、date および time に対する調整は行われません。そうでない場合、結果はタイムゾーン tz におけるローカル時刻で、 self と同じ UTC 時刻を表すようになります。これは、astz = dt.astimezone(tz) とした後、 astz - astz.utcoffset() は通常 dt - dt.utcoffset() と同じ date および time を持つことを示します。

単にタイムゾーンオブジェクト tz を datetime オブジェクト dt に追加したいだけで、日付や時刻データへの調整を行わないのなら、dt.replace(tzinfo=tz) を使ってください。単に aware な datetime オブジェクト dt からタイムゾーンオブジェクトを除去したいだけで、日付や時刻データの変換を行わないのなら、dt.replace(tzinfo=None) を使ってください。

デフォルトの tzinfo.fromutc() メソッドを tzinfo のサブクラスで上書きして, astimezone() が返す結果に影響を及ぼすことができます。エラーの場合を無視すると、 astimezone() は以下のように動作します:

def astimezone(self, tz):
    if self.tzinfo is tz:
        return self
    # Convert self to UTC, and attach the new time zone object.
    utc = (self - self.utcoffset()).replace(tzinfo=tz)
    # Convert from UTC to tz's local time.
    return tz.fromutc(utc)

バージョン 3.3 で変更: tz が省略可能になりました。

バージョン 3.6 で変更: datetime.datetime.astimezone() メソッドを naive なインスタンスに対して呼び出せるようになりました。これは、システムのローカルな時間を表現していると想定されます。

datetime.utcoffset()

tzinfo が None の場合、 None を返し、そうでない場合には self.tzinfo.utcoffset(self) を返します。後者の式が None あるいは 1 日以下の大きさを持つ timedelta オブジェクトのいずれかを返さない場合には例外を送出します。

バージョン 3.7 で変更: UTC オフセットが分単位でなければならない制限が無くなりました。

datetime.dst()

tzinfo が None の場合 None を返し、そうでない場合には self.tzinfo.dst(self) を返します。後者の式が None もしくは、1 日未満の大きさを持つ timedelta オブジェクトのいずれかを返さない場合には例外を送出します。

バージョン 3.7 で変更: DST オフセットが分単位でなければならない制限が無くなりました。

datetime.tzname()

tzinfo が None の場合 None を返し、そうでない場合には self.tzinfo.tzname(self) を返します。後者の式が None か文字列オブジェクトのいずれかを返さない場合には例外を送出します。

datetime.timetuple()

time.localtime() が返すような time.struct_time を返します。

d.timetuple() は次の式と等価です:

time.struct_time((d.year, d.month, d.day,
                  d.hour, d.minute, d.second,
                  d.weekday(), yday, dst))

where 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 tm_isdst flag of the result is set according to the dst() method: tzinfo is None or dst() returns None, tm_isdst is set to -1; else if dst() returns a non-zero value, tm_isdst is set to 1; else tm_isdst is set to 0.

datetime.utctimetuple()

datetime インスタンス d が naive の場合、このメソッドは d.timetuple() と同じであり、 d.dst() の返す内容にかかわらず tm_isdst が 0 に強制される点だけが異なります。 DST が UTC 時刻に影響を及ぼすことは決してありません。

If d is aware, d is normalized to UTC time, by subtracting d.utcoffset(), and a time.struct_time for the normalized time is returned. tm_isdst is forced to 0. Note that an OverflowError may be raised if d.year was MINYEAR or MAXYEAR and UTC adjustment spills over a year boundary.

警告

naive な datetime オブジェクトは多くの datetime メソッドでローカルな時間として扱われるため、 aware な datetime を使って UTC の時刻を表すのが好ましいです。結果として、 datetime.utctimetuple() は誤解を招きやすい返り値を返すかもしれません。 UTC を表す naive な datetime があった場合、 datetime.timetuple() が使えるところでは datetime.replace(tzinfo=timezone.utc) で aware にします。

datetime.toordinal()

先発グレゴリオ暦における日付序数を返します。self.date().toordinal() と同じです。

datetime.timestamp()

datetime インスタンスに対応する POSIX タイムスタンプを返します。返り値は time.time() で返される値に近い float です。

このメソッドでは naive な datetime インスタンスはローカル時刻とし、プラットフォームの C 関数 mktime() に頼って変換を行います。 datetime は多くのプラットフォームの mktime() より広い範囲の値をサポートしているので、遥か過去の時刻や遥か未来の時刻に対し、このメソッドは OverflowError または OSError を送出するかもしれません。

aware な datetime インスタンスに対しては以下のように返り値が計算されます:

(dt - datetime(1970, 1, 1, tzinfo=timezone.utc)).total_seconds()

Added in version 3.3.

バージョン 3.6 で変更: The timestamp() method uses the fold attribute to disambiguate the times during a repeated interval.

注釈

UTC 時刻を表す naive な datetime インスタンスから直接 POSIX タイムスタンプを取得するメソッドはありません。アプリケーションがその変換を使っており、システムのタイムゾーンが UTC に設定されていなかった場合、 tzinfo=timezone.utc を引数に与えることで POSIX タイムスタンプを取得できます:

timestamp = dt.replace(tzinfo=timezone.utc).timestamp()

もしくは直接タイムスタンプを計算することもできます:

timestamp = (dt - datetime(1970, 1, 1)) / timedelta(seconds=1)

datetime.weekday()

月曜日を 0、日曜日を 6 として、曜日を整数で返します。 self.date().weekday() と同じです。 isoweekday() も参照してください。

datetime.isoweekday()

月曜日を 1、日曜日を 7 として、曜日を整数で返します。 self.date().isoweekday() と等価です。 weekday() 、 isocalendar() も参照してください。

datetime.isocalendar()

year、week、weekday の3つで構成された named tuple を返します。 self.date().isocalendar() と等価です。

datetime.isoformat(sep='T', timespec='auto')

日時を ISO 8601 書式で表した文字列で返します:

microsecond が 0 でない場合は YYYY-MM-DDTHH:MM:SS.ffffff

microsecond が 0 の場合は YYYY-MM-DDTHH:MM:SS

utcoffset() が None を返さない場合は、文字列の後ろに UTC オフセットが追記されます:

microsecond が 0 でない場合は YYYY-MM-DDTHH:MM:SS.ffffff+HH:MM[:SS[.ffffff]]

microsecond が 0 の場合は YYYY-MM-DDTHH:MM:SS+HH:MM[:SS[.ffffff]]

例:

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

オプションの引数 sep (デフォルトでは 'T' です) は 1 文字のセパレータで、結果の文字列の日付と時刻の間に置かれます。例えば:

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

オプション引数 timespec は、含める追加の時間の要素の数を指定します(デフォルトでは 'auto' です)。以下の内一つを指定してください。

'auto': microsecond が0である場合 'seconds' と等しく、そうでない場合は 'microseconds' と等しくなります。

'hours': hour を2桁の HH 書式で含めます。

'minutes': hour および minute を HH:MM の書式で含めます。

'seconds': hour 、 minute 、 second を HH:MM:SS の書式で含めます。

'milliseconds': 全ての時刻を含みますが、小数第二位をミリ秒に切り捨てます。 HH:MM:SS.sss の書式で表現します。

'microseconds': 全ての時刻を HH:MM:SS.mmmmmm の書式で含めます。

注釈

除外された要素は丸め込みではなく、切り捨てされます。

不正な timespec 引数には ValueError があげられます:

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

バージョン 3.6 で変更: timespec パラメータを追加しました.

datetime.__str__()

datetime オブジェクト d において、 str(d) は d.isoformat(' ') と等価です。

datetime.ctime()

日付および時刻を表す文字列を返します:

>>> from datetime import datetime
>>> datetime(2002, 12, 4, 20, 30, 40).ctime()
'Wed Dec  4 20:30:40 2002'

出力文字列は入力が aware であれ naive であれ、タイムゾーン情報を含み ません。

d.ctime() は次の式と等価です:

time.ctime(time.mktime(d.timetuple()))

これが等価になるのは、 (time.ctime() に呼び出され、 datetime.ctime() に呼び出されない) ネイティブの C 関数 ctime() が C 標準に準拠しているプラットフォーム上でです。

datetime.strftime(format)

明示的な書式文字列で制御された、日付および時刻を表現する文字列を返します。strftime() と strptime() の振る舞い および datetime.isoformat() も参照してください。

datetime.__format__(format)

datetime.strftime() と等価です。これにより、 フォーマット済み文字列リテラル の中や str.format() を使っているときに datetime オブジェクトの書式文字列を指定できます。 strftime() と strptime() の振る舞い および datetime.isoformat() も参照してください。

使用例: datetime

datetime オブジェクトを使う例:

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

下にある例では、1945年までは +4 UTC 、それ以降は +4:30 UTC を使用しているアフガニスタンのカブールのタイムゾーン情報を表現する tzinfo のサブクラスを定義しています:

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"

上に出てきた KabulTz の使い方:

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

time オブジェクト

time オブジェクトは (ローカルの) 日中時刻を表現します。この時刻表現は特定の日の影響を受けず、 tzinfo オブジェクトを介した修正の対象となります。

class datetime.time(hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)

全ての引数はオプションです。 tzinfo は None または tzinfo クラスのサブクラスのインスタンスにすることができます。残りの引数は整数で、以下のような範囲に入らなければなりません:

0 <= hour < 24,

0 <= minute < 60,

0 <= second < 60,

0 <= microsecond < 1000000,

fold in [0, 1].

If an argument outside those ranges is given, ValueError is raised. All default to 0 except tzinfo, which defaults to None.

以下にクラス属性を示します:

time.min

表現できる最も古い time で、 time(0, 0, 0, 0) です。

time.max

表現できる最も新しい time で、 time(23, 59, 59, 999999) です。

time.resolution

等しくない time オブジェクト間の最小の差で、 timedelta(microseconds=1) ですが, time オブジェクト間の四則演算はサポートされていないので注意してください。

インスタンスの属性 (読み出しのみ):

time.hour

in range(24) を満たします。

time.minute

in range(60) を満たします。

time.second

in range(60) を満たします。

time.microsecond

in range(1000000) を満たします。

time.tzinfo

time コンストラクタに tzinfo 引数として与えられたオブジェクトになり、何も渡されなかった場合には None になります。

time.fold

In [0, 1]. Used to disambiguate wall times during a repeated interval. (A repeated interval occurs when clocks are rolled back at the end of daylight saving time or when the UTC offset for the current zone is decreased for political reasons.) The values 0 and 1 represent, respectively, the earlier and later of the two moments with the same wall time representation.

Added in version 3.6.

time objects support equality and order comparisons, where a is considered less than b when a precedes b in time.

Naive and aware time objects are never equal. Order comparison between naive and aware time objects raises TypeError.

If both comparands are aware, and have the same tzinfo attribute, the tzinfo and fold attributes are ignored and the base times are compared. If both comparands are aware and have different tzinfo attributes, the comparands are first adjusted by subtracting their UTC offsets (obtained from self.utcoffset()).

バージョン 3.3 で変更: aware な インスタンスと naive な time インスタンスの等価比較では TypeError は送出されません。

ブール値の文脈では、 time オブジェクトは常に真とみなされます。

バージョン 3.5 で変更: Python 3.5 以前は、 time オブジェクトは UTC で深夜を表すときに偽とみなされていました。この挙動は分かりにくく、エラーの元となると考えられ、Python 3.5 で削除されました。全詳細については bpo-13936 [https://bugs.python.org/issue?@action=redirect&bpo=13936] を参照してください。

その他のコンストラクタ:

classmethod time.fromisoformat(time_string)

以下の例外を除く、有効な ISO 8601 フォーマットで与えられた time_string に対応する time を返します :

小数の秒があるタイムゾーンオフセット。

The leading T, normally required in cases where there may be ambiguity between a date and a time, is not required.

Fractional seconds may have any number of digits (anything beyond 6 will be truncated).

少数の時と分はサポートされていません。

例:

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

Added in version 3.7.

バージョン 3.11 で変更: 以前は、このメソっどは time.isoformat() から出力されるフォーマットのみをサポートしていました。

インスタンスメソッド:

time.replace(hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, tzinfo=self.tzinfo, *, fold=0)

キーワード引数で指定したメンバの値を除き、同じ値をもつ time オブジェクトを返します。データに対する変換を行わずに aware な time オブジェクトから naive な time オブジェクトを生成するために、 tzinfo=None を指定することもできます。

バージョン 3.6 で変更: fold パラメータが追加されました。

time.isoformat(timespec='auto')

時刻を ISO 8601 書式で表した次の文字列のうち1つを返します:

microsecond が 0 でない場合は HH:MM:SS.ffffff

microsecond が 0 の場合は HH:MM:SS

utcoffset() が None を返さない場合、 HH:MM:SS.ffffff+HH:MM[:SS[.ffffff]]

microsecond が 0 で utcoffset() が None を返さない場合、 HH:MM:SS+HH:MM[:SS[.ffffff]]

オプション引数 timespec は、含める追加の時間の要素の数を指定します(デフォルトでは 'auto' です)。以下の内一つを指定してください。

'auto': microsecond が0である場合 'seconds' と等しく、そうでない場合は 'microseconds' と等しくなります。

'hours': hour を2桁の HH 書式で含めます。

'minutes': hour および minute を HH:MM の書式で含めます。

'seconds': hour 、 minute 、 second を HH:MM:SS の書式で含めます。

'milliseconds': 全ての時刻を含みますが、小数第二位をミリ秒に切り捨てます。 HH:MM:SS.sss の書式で表現します。

'microseconds': 全ての時刻を HH:MM:SS.mmmmmm の書式で含めます。

注釈

除外された要素は丸め込みではなく、切り捨てされます。

不正な timespec 引数には ValueError があげられます。

以下はプログラム例です:

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

バージョン 3.6 で変更: timespec パラメータを追加しました.

time.__str__()

time オブジェクト t において、str(t) は t.isoformat() と等価です。

time.strftime(format)

明示的な書式文字列で制御された、時刻を表現する文字列を返します。strftime() と strptime() の振る舞い および time.isoformat() も参照してください。

time.__format__(format)

time.strftime() と等価です。これにより、 フォーマット済み文字列リテラル の中や str.format() を使っているときに time オブジェクトの書式文字列を指定できます。 strftime() と strptime() の振る舞い および time.isoformat() も参照してください。

time.utcoffset()

tzinfo が None の場合、 None を返し、そうでない場合には self.tzinfo.utcoffset(None) を返します。後者の式が None あるいは 1 日以下の大きさを持つ timedelta オブジェクトのいずれかを返さない場合には例外を送出します。

バージョン 3.7 で変更: UTC オフセットが分単位でなければならない制限が無くなりました。

time.dst()

tzinfo が None の場合 None を返し、そうでない場合には self.tzinfo.dst(None) を返します。後者の式が None もしくは、1 日未満の大きさを持つ timedelta オブジェクトのいずれかを返さない場合には例外を送出します。

バージョン 3.7 で変更: DST オフセットが分単位でなければならない制限が無くなりました。

time.tzname()

tzinfo が None の場合 None を返し、そうでない場合には self.tzinfo.tzname(None) を返します。後者の式が None か文字列オブジェクトのいずれかを返さない場合には例外を送出します。

使用例: time

time オブジェクトを使う例:

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

tzinfo オブジェクト

class datetime.tzinfo

このクラスは抽象基底クラスで、直接インスタンス化すべきでないことを意味します。 tzinfo のサブクラスを定義し、ある特定のタイムゾーンに関する情報を保持するようにしてください。

tzinfo (の具体的なサブクラス) のインスタンスは datetime および time オブジェクトのコンストラクタに渡すことができます。後者のオブジェクトでは、データ属性をローカル時刻におけるものとして見ており、 tzinfo オブジェクトはローカル時刻の UTC からのオフセット、タイムゾーンの名前、 DST オフセットを、渡された日付および時刻オブジェクトからの相対で示すためのメソッドを提供します。

具象サブクラスを作成し、(少なくとも) 使いたい datetime のメソッドが必要とする tzinfo のメソッドを実装する必要があります。 datetime モジュールは tzinfo のシンプルな具象サブクラス timezone を提供します。これは UTC そのものか北アメリカの EST と EDT のような UTC からの固定されたオフセットを持つタイムゾーンを表せます。

pickle 化についての特殊な要求事項: tzinfo のサブクラスは引数なしで呼び出すことのできる __init__() メソッドを持たなければなりません。そうでなければ、 pickle 化することはできますがおそらく unpickle 化することはできないでしょう。これは技術的な側面からの要求であり、将来緩和されるかもしれません。

tzinfo の具体的なサブクラスでは、以下のメソッドを実装する必要があります。厳密にどのメソッドが必要なのかは、 aware な datetime オブジェクトがこのサブクラスのインスタンスをどのように使うかに依存します。不確かならば、単に全てを実装してください。

tzinfo.utcoffset(dt)

ローカル時間の UTC からのオフセットを、 UTC から東向きを正とした timedelta オブジェクトで返します。ローカル時間が UTC の西側にある場合、この値は負になります。

このメソッドは UTC からのオフセットの 総計 を表しています。例えば、 tzinfo オブジェクトがタイムゾーンと DST 修正の両方を表現する場合、 utcoffset() はそれらの合計を返さなければなりません。 UTC オフセットが未知である場合、 None を返します。そうでない場合には、返される値は -timedelta(hours=24) から timedelta(hours=24) までの timedelta 境界を含まないオブジェクトでなければなりません (オフセットの大きさは 1 日より短くなければなりません)。ほとんどの utcoffset() 実装は、おそらく以下の二つのうちの一つに似たものになるでしょう:

return CONSTANT                 # fixed-offset class
return CONSTANT + self.dst(dt)  # daylight-aware class

utcoffset() が None を返さない場合、 dst() も None を返してはなりません。

utcoffset() のデフォルトの実装は NotImplementedError を送出します。

バージョン 3.7 で変更: UTC オフセットが分単位でなければならない制限が無くなりました。

tzinfo.dst(dt)

夏時間 (DST) 修正を、 class:timedelta オブジェクトで返します。 DST 情報が未知の場合、 None が返されます。

DST が有効でない場合には timedelta(0) を返します。 DST が有効の場合、オフセットは timedelta オブジェクトで返します (詳細は utcoffset() を参照してください)。 DST オフセットが利用可能な場合、この値は utcoffset() が返す UTC からのオフセットには既に加算されているため、 DST を個別に取得する必要がない限り dst() を使って問い合わせる必要はないので注意してください。例えば、 datetime.timetuple() は tzinfo 属性の dst() メソッドを呼んで tm_isdst フラグがセットされているかどうか判断し、 tzinfo.fromutc() は dst() タイムゾーンを移動する際に DST による変更があるかどうかを調べます。

標準および夏時間の両方をモデル化している tzinfo サブクラスのインスタンス tz は以下の式:

tz.utcoffset(dt) - tz.dst(dt)

must return the same result for every datetime dt with dt.tzinfo == tz. For sane 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 datetime.astimezone() relies on this, but cannot detect violations; it's the programmer's responsibility to ensure it. If a tzinfo subclass cannot guarantee this, it may be able to override the default implementation of tzinfo.fromutc() to work correctly with astimezone() regardless.

ほとんどの dst() 実装は、おそらく以下の二つのうちの一つに似たものになるでしょう:

def dst(self, dt):
    # a fixed-offset class:  doesn't account for DST
    return timedelta(0)

もしくは:

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)

デフォルトの dst() 実装は NotImplementedError を送出します。

バージョン 3.7 で変更: DST オフセットが分単位でなければならない制限が無くなりました。

tzinfo.tzname(dt)

Return the time zone name corresponding to the datetime object dt, as a string. Nothing about string names is defined by the datetime module, and there's no requirement that it mean anything in particular. For example, "GMT", "UTC", "-500", "-5:00", "EDT", "US/Eastern", "America/New York" are all valid replies. Return None if a string name isn't known. Note that this is a method rather than a fixed string primarily because some tzinfo subclasses will wish to return different names depending on the specific value of dt passed, especially if the tzinfo class is accounting for daylight time.

デフォルトの tzname() 実装は NotImplementedError を送出します。

以下のメソッドは datetime や time オブジェクトにおいて、同名のメソッドが呼び出された際に応じて呼び出されます。 datetime オブジェクトは自身を引数としてメソッドに渡し、 time オブジェクトは引数として None をメソッドに渡します。従って、 tzinfo のサブクラスにおけるメソッドは引数 dt が None の場合と、 datetime の場合を受理するように用意しなければなりません。

None が渡された場合、最良の応答方法を決めるのはクラス設計者次第です。例えば、このクラスが tzinfo プロトコルと関係をもたないということを表明させたければ、 None が適切です。標準時のオフセットを見つける他の手段がない場合には、標準 UTC オフセットを返すために utcoffset(None) を使うともっと便利かもしれません。

datetime オブジェクトが datetime() メソッドの応答として返された場合、 dt.tzinfo は self と同じオブジェクトになります。ユーザが直接 tzinfo メソッドを呼び出さないかぎり、 tzinfo メソッドは dt.tzinfo と self が同じであることに依存します。その結果 tzinfo メソッドは dt がローカル時間であると解釈するので、他のタイムゾーンでのオブジェクトの振る舞いについて心配する必要がありません。

サブクラスでオーバーライドすると良い、もう 1 つの tzinfo のメソッドがあります:

tzinfo.fromutc(dt)

デフォルトの datetime.astimezone() 実装で呼び出されます。 datetime.astimezone() から呼ばれた場合、 dt.tzinfo は self であり、 dt の日付および時刻データは UTC 時刻を表しているものとして見えます。 fromutc() の目的は、 self のローカル時刻に等しい datetime オブジェクトを返すことにより日付と時刻データメンバを修正することにあります。

ほとんどの tzinfo サブクラスではデフォルトの fromutc() 実装を問題なく継承できます。デフォルトの実装は、固定オフセットのタイムゾーンや、標準時と夏時間の両方について記述しているタイムゾーン、そして DST 移行時刻が年によって異なる場合でさえ、扱えるくらい強力なものです。デフォルトの fromutc() 実装が全ての場合に対して正しく扱うことができないような例は、標準時の (UTCからの) オフセットが引数として渡された特定の日や時刻に依存するもので、これは政治的な理由によって起きることがあります。デフォルトの astimezone() や fromutc() の実装は、結果が標準時オフセットの変化にまたがる何時間かの中にある場合、期待通りの結果を生成しないかもしれません。

エラーの場合のためのコードを除き、デフォルトの fromutc() の実装は以下のように動作します:

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

次の tzinfo_examples.py ファイルには、 tzinfo クラスの例がいくつか載っています:

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")

標準時および夏時間の両方を記述している tzinfo のサブクラスでは、夏時間の移行のときに、回避不能の難解な問題が年に 2 度あるので注意してください。具体的な例として、東部アメリカ時刻 (US Eastern, UTC -0500) を考えます。 EDT は 3 月の第二日曜日の 1:59 (EST) の 1 分後に開始し、11 月の最初の日曜日の (EDTの) 1:59 に終了します:

  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

DSTの開始 ("start" ライン) で、ローカルの実時間は 1:59 から 3:00 に飛びます。この日には、 2:MM という形式の実時間は意味をなさないので、 DST が始まった日に astimezone(Eastern) は hour == 2 となる結果を返すことはありません。例として、 2016 年の春方向の移行では、次のような結果になります:

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

DST が終了 ("end" ライン) で、更なる問題が潜んでいます: ローカルの実時間で、曖昧さ無しに時を綴れない 1 時間が存在します: それは夏時間の最後の 1 時間です。東部では、夏時間が終了する日の UTC での 5:MM 形式の時間がそれです。ローカルの実時間は (夏時間の) 1:59 から (標準時の) 1:00 に再び巻き戻されます。ローカルの時刻における 1:MM は曖昧です。そして astimezone() は 2 つの隣り合う UTC 時間を同じローカルの時間に対応付けて、ローカルの時計の振る舞いを真似ます。東部の例では、 5:MM および 6:MM という形式の UTC 時刻は両方とも東部時刻に変換された際に 1:MM に対応付けられますが、それ以前の時間は fold 属性を 0 にし、以降の時間では 1 にします。例えば、 2016 年での秋方向の移行では、次のような結果になります:

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

fold 属性が異なるだけの datetime インスタンスは比較において等しいとみなされることに注意してください。

壁時間に関する曖昧さは、明示的に fold 属性を検証するか、 timezone が使用されたハイブリッドな tzinfo サブクラスか、そのほかの絶対時間差を示す tzinfo サブクラス(EST (-5 時間の絶対時間差) のみを表すクラスや、 EDT (-4 時間の絶対時間差) のみを表すクラス)を使用すると回避できます。このような曖昧さを許容できないアプリケーションは、このような手法によって回避すべきです。

参考

zoneinfo

datetime モジュールには (UTC からの任意の固定オフセットを扱う) 基本的な timezone クラスと、(UTC タイムゾーンのインスタンスである) timezone.utc 属性があります。

zoneinfo は Python に IANA タイムゾーンデータベース (オルソンデータベースとしても知られています) を導入するもので、これを使うことが推奨されています。

IANA タイムゾーンデータベース [https://www.iana.org/time-zones]

(しばしば tz、tzdata や zoneinfo と呼ばれる) タイムゾーンデータベースはコードとデータを保持しており、それらは地球全体にわたる多くの代表的な場所のローカル時刻の履歴を表しています。政治団体によるタイムゾーンの境界、UTC オフセット、夏時間のルールの変更を反映するため、定期的にデータベースが更新されます。

timezone オブジェクト

timezone クラスは tzinfo のサブクラスで、各インスタンスは UTC からの固定されたオフセットで定義されたタイムゾーンを表しています。

このクラスのオブジェクトは、一年のうち異なる日に異なるオフセットが使われていたり、常用時 (civil time) に歴史的な変化が起きた場所のタイムゾーン情報を表すのには使えないので注意してください。

class datetime.timezone(offset, name=None)

ローカル時刻と UTC の差分を表す timedelta オブジェクトを offset 引数に指定しなくてはいけません。これは -timedelta(hours=24) から timedelta(hours=24) までの両端を含まない範囲に収まっていなくてはなりません。そうでない場合 ValueError が送出されます。

name 引数は必須ではありません。もし指定された場合、その値は datetime.tzname() メソッドの返り値として使われる文字列でなければなりません。

Added in version 3.2.

バージョン 3.7 で変更: UTC オフセットが分単位でなければならない制限が無くなりました。

timezone.utcoffset(dt)

timezone インスタンスが構築されたときに指定された固定値を返します。

dt 引数は無視されます。返り値は、ローカル時刻と UTC の差分に等しい timedelta インスタンスです。

バージョン 3.7 で変更: UTC オフセットが分単位でなければならない制限が無くなりました。

timezone.tzname(dt)

timezone インスタンスが構築されたときに指定された固定値を返します。

name が構築時に与えられなかった場合、 tzname(dt) によって返される name は以下の様に offset の値から生成されます。 offset が timedelta(0) であった場合、 name は "UTC"になります。それ以外の場合、 'UTC±HH:MM' という書式の文字列になり、± は offset を、HH と MM はそれぞれ二桁の offset.hours と offset.minutes を表現します。

バージョン 3.6 で変更: offset=timedelta(0) によって生成される名前はプレーンな 'UTC' であり 'UTC+00:00' ではありません。

timezone.dst(dt)

常に None を返します。

timezone.fromutc(dt)

dt + offset を返します。 dt 引数は tzinfo が self になっている aware な datetime インスタンスでなければなりません。

以下にクラス属性を示します:

timezone.utc

UTC タイムゾーン timezone(timedelta(0)) です。

strftime() と strptime() の振る舞い

date, datetime, time オブジェクトは全て strftime(format) メソッドをサポートし、時刻を表現する文字列を明示的な書式文字列で統制して作成しています。

逆に datetime.strptime() クラスメソッドは日付や時刻に対応する書式文字列から datetime オブジェクトを生成します。

下の表は strftime() と strptime() との高レベルの対比を表しています。

strftime

strptime

使用法

オブジェクトを与えられた書式に従って文字列に変換する

指定された対応する書式で文字列を構文解析して datetime オブジェクトにする

メソッドの種類

インスタンスメソッド

クラスメソッド

メソッドを持つクラス

date; datetime; time

datetime

シグネチャ

strftime(format)

strptime(date_string, format)

strftime() と strptime() の書式コード

These methods accept format codes that can be used to parse and format dates:

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

以下のリストは 1989 C 標準が要求する全ての書式コードで、標準 C 実装があれば全ての環境で動作します。

ディレクティブ

意味

使用例

注釈

%a

ロケールの曜日名を短縮形で表示します。

Sun, Mon, ..., Sat (en_US);

So, Mo, ..., Sa (de_DE)

(1)

%A

ロケールの曜日名を表示します。

Sunday, Monday, ..., Saturday (en_US);

Sonntag, Montag, ..., Samstag (de_DE)

(1)

%w

曜日を10進表記した文字列を表示します。0 が日曜日で、6 が土曜日を表します。

0, 1, ..., 6

%d

0埋めした10進数で表記した月中の日にち。

01, 02, ..., 31

(9)

%b

ロケールの月名を短縮形で表示します。

Jan, Feb, ..., Dec (en_US);

Jan, Feb, ..., Dez (de_DE)

(1)

%B

ロケールの月名を表示します。

January, February, ..., December (en_US);

Januar, Februar, ..., Dezember (de_DE)

(1)

%m

0埋めした10進数で表記した月。

01, 02, ..., 12

(9)

%y

0埋めした10進数で表記した世紀無しの年。

00, 01, ..., 99

(9)

%Y

西暦 ( 4桁) の 10 進表記を表します。

0001, 0002, ..., 2013, 2014, ..., 9998, 9999

(2)

%H

0埋めした10進数で表記した時 (24時間表記)。

00, 01, ..., 23

(9)

%I

0埋めした10進数で表記した時 (12時間表記)。

01, 02, ..., 12

(9)

%p

ロケールの AM もしくは PM と等価な文字列になります。

AM, PM (en_US);

am, pm (de_DE)

(1), (3)

%M

0埋めした10進数で表記した分。

00, 01, ..., 59

(9)

%S

0埋めした10進数で表記した秒。

00, 01, ..., 59

(4), (9)

%f

10進数で表記したマイクロ秒 (6桁に0埋めされます)。

000000, 000001, ..., 999999

(5)

%z

UTCオフセットを ±HHMM[SS[.ffffff]] の形式で表示します (オブジェクトがnaiveであれば空文字列)。

(空文字列), +0000, -0400, +1030, +063415, -030712.345216

(6)

%Z

タイムゾーンの名前を表示します (オブジェクトがnaiveであれば空文字列)。

(空文字列), UTC, GMT

(6)

%j

0埋めした10進数で表記した年中の日にち。

001, 002, ..., 366

(9)

%U

0埋めした10進数で表記した年中の週番号 (週の始まりは日曜日とする)。新年の最初の日曜日に先立つ日は 0週に属するとします。

00, 01, ..., 53

(7), (9)

%W

0埋めした10進数で表記した年中の週番号 (週の始まりは月曜日とする)。新年の最初の月曜日に先立つ日は 0週に属するとします。

00, 01, ..., 53

(7), (9)

%c

ロケールの日時を適切な形式で表します。

Tue Aug 16 21:30:00 1988 (en_US);

Di 16 Aug 21:30:00 1988 (de_DE)

(1)

%x

ロケールの日付を適切な形式で表します。

08/16/88 (None);

08/16/1988 (en_US);

16.08.1988 (de_DE)

(1)

%X

ロケールの時間を適切な形式で表します。

21:30:00 (en_US);

21:30:00 (de_DE)

(1)

%%

文字 '%' を表します。

%

C89規格により要求されない幾つかの追加のコードが便宜上含まれています。これらのパラメータはすべてISO 8601の日付値に対応しています。

ディレクティブ

意味

使用例

注釈

%G

ISO week(%V)の内過半数を含む西暦表記の ISO 8601 year です。

0001, 0002, ..., 2013, 2014, ..., 9998, 9999

(8)

%u

1 を月曜日を表す 10進数表記の ISO 8601 weekday です。

1, 2, ..., 7

%V

週で最初の月曜日を始めとする ISO 8601 week です。Week 01 は 1月4日を含みます。

01, 02, ..., 53

(8), (9)

%:z

UTCオフセットを ±HH:MM[:SS[.ffffff]] の形式で表示します (オブジェクトがnaiveであれば空文字列)。

(空文字列), +00:00, -04:00, +10:30, +06:34:15, -03:07:12.345216

(6)

これらが strftime() メソッドと一緒に使用された場合、すべてのプラットフォームで利用できるわけではありません。 ISO 8601 year 指定子およびISO 8601 week 指定子は、上記のyear および week number 指定子と互換性がありません。不完全またはあいまいなISO 8601 指定子で strptime() を呼び出すと、 ValueError が送出されます。

Python はプラットフォームの C ライブラリの strftime() 関数を呼び出していて、プラットフォームごとにその実装が異なるのはよくあることなので、サポートされる書式コード全体はプラットフォームごとに様々です。手元のプラットフォームでサポートされているフォーマット記号全体を見るには、 strftime(3) [https://manpages.debian.org/strftime(3)] のドキュメントを参照してください。サポートされていないフォーマット指定子の扱いもプラットフォーム間で差異があります。

Added in version 3.6: %G, %u および %V が追加されました。

Added in version 3.12: %:z が追加されました。

技術詳細

大雑把にいうと、 d.strftime(fmt) は time モジュールの time.strftime(fmt, d.timetuple()) のように動作します。ただし全てのオブジェクトが timetuple() メソッドをサポートしているわけではありません。

datetime.strptime() クラスメソッドでは、デフォルト値は 1900-01-01T00:00:00.000 です。書式文字列で指定されなかった部分はデフォルト値から引っ張ってきます。 [4]

datetime.strptime(date_string, format) は次の式と等価です:

datetime(*(time.strptime(date_string, format)[0:6]))

ただし、 datetime.strptime はサポートしているが time.strptime には無い、秒未満の単位やタイムゾーンオフセットの情報が format に 含まれているときは除きます。

For time objects, the format codes for year, month, and day should not be used, as time objects have no such values. If they're used anyway, 1900 is substituted for the year, and 1 for the month and day.

For date objects, the format codes for hours, minutes, seconds, and microseconds should not be used, as date objects have no such values. If they're used anyway, 0 is substituted for them.

同じ理由で、現在のロケールの文字集合で表現できない Unicode コードポイントを含む書式文字列の対処もプラットフォーム依存です。あるプラットフォームではそういったコードポイントはそのまま出力に出される一方、他のプラットフォームでは strftime が UnicodeError を送出したり、その代わりに空文字列を返したりするかもしれません。

注釈:

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.

strptime() メソッドは [1, 9999] の範囲の年数全てを構文解析できますが、 year < 1000 の範囲の年数は 0 埋めされた 4 桁の数字でなければなりません。

バージョン 3.2 で変更: 以前のバージョンでは、 strftime() メソッドは years >= 1900 の範囲の年数しか扱えませんでした。

バージョン 3.3 で変更: バージョン 3.2 では、 strftime() メソッドは years >= 1000 の範囲の年数しか扱えませんでした。

strptime() メソッドと共に使われた場合、 %p 指定子は出力の時間フィールドのみに影響し、 %I 指定子が使われたかのように振る舞います。

time モジュールと違い、 datetime モジュールはうるう秒をサポートしていません。

strptime() メソッドと共に使われた場合、 %f 指定子は 1 桁から 6 桁の数字を受け付け、右側から0埋めされます。 %f は C 標準規格の書式文字セットの拡張です (とは言え、 datetime モジュールのオブジェクトそれぞれに実装されているので、どれででも使えます)。

naive オブジェクトでは、書式コード %z、%:z および %Z は空文字列に置き換えられます。

aware オブジェクトでは次のようになります:

%z

utcoffset() は ±HHMM[SS[.ffffff]] 形式の文字列に変換されます。ここで、 HH は UTC オフセットの時間を表す 2 桁の文字列、 MM は UTC オフセットの分数を表す 2 桁の文字列、 SS は UTC オフセットの秒数を表す 2 桁の文字列、 ffffff は UTC オフセットのマイクロ秒数を表す 6 桁の文字列です。オフセットに秒未満の端数が無いときは ffffff 部分は省略され、オフセットに分未満の端数が無いときは ffffff 部分も SS 部分も省略されます。例えば、 utcoffset() が timedelta(hours=-3, minutes=-30) を返す場合、 %z は文字列 '-0330' に置き換えられます。

バージョン 3.7 で変更: UTC オフセットが分単位でなければならない制限が無くなりました。

バージョン 3.7 で変更: %z 指定子が strptime() メソッドに渡されたときは、時分秒のセパレータとしてコロンが UTC オフセットで使えます。例えば、 '+01:00:00' は 1 時間のオフセットだと構文解析されます。加えて、 'Z' を渡すことは '+00:00' を渡すことと同等です。

%:z

Behaves exactly as %z, but has a colon separator added between hours, minutes and seconds.

%Z

In strftime(), %Z is replaced by an empty string if tzname() returns None; otherwise %Z is replaced by the returned value, which must be a string.

strptime() は %Z に特定の値のみを受け入れます:

使用しているマシンのロケールによる time.tzname の任意の値

ハードコードされた値 UTC または GMT

つまり、日本に住んでいる場合は JST, UTC と GMT が有効な値であり、 EST はおそらく無効な値となります。無効な値の場合は ValueError を送出します。

バージョン 3.2 で変更: %z 指定子が strptime() メソッドに与えられた場合、 aware な datetime オブジェクトが作成されます。返り値の tzinfo は timezone インスタンスになっています。

strptime() メソッドと共に使われた場合、 %U と %W 指定子は、曜日と年(%Y)が指定された場合の計算でのみ使われます。

%U および %W と同様に、 %V は曜日と ISO 年 (%G) が strptime() の書式文字列の中で指定された場合に計算でのみ使われます。 %G と %Y は互いに完全な互換性を持たないことにも注意してください。

strptime() メソッドと共に使われるとき、書式 %d, %m, %H, %I, %M, %S, %j, %U, %W, %V では先行ゼロは任意です。書式 %y では先行ゼロは必須です。

脚注

[1]

もし相対性理論の効果を無視するならば、ですが

[2]

この暦法は、全ての計算における基本カレンダーである、 Dershowitz と Reingold の書籍 Calendrical Calculations における先発グレゴリオ暦 ("proleptic Gregorian") の定義に一致します。先発グレゴリオ暦の序数とその他多くの暦法どうしの変換アルゴリズムについては、この書籍を参照してください。

[3]

優れた説明は R. H. van Gent の guide to the mathematics of the ISO 8601 calendar [https://web.archive.org/web/20220531051136/https://webspace.science.uu.nl/~gent0113/calendar/isocalendar.htm] を参照してください。

[4]

Passing datetime.strptime('Feb 29', '%b %d') will fail since 1900 is not a leap year.

zoneinfo --- IANA time zone support

Added in version 3.9.

ソースコード: Lib/zoneinfo [https://github.com/python/cpython/tree/3.12/Lib/zoneinfo]

The zoneinfo module provides a concrete time zone implementation to support the IANA time zone database as originally specified in PEP 615 [https://peps.python.org/pep-0615/]. By default, zoneinfo uses the system's time zone data if available; if no system time zone data is available, the library will fall back to using the first-party tzdata [https://pypi.org/project/tzdata/] package available on PyPI.

参考

モジュール: datetime

ZoneInfo クラスを使用するように設計されたデータ型 time と datetime を提供します。

Package tzdata [https://pypi.org/project/tzdata/]

CPythonコアデベロッパーによってメンテナンスされているファーストパーティーのパッケージ。タイムゾーンデータを供給し、PyPIで配布されている。

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. See WebAssemblyプラットフォーム for more information.

ZoneInfo を使用する

ZoneInfo は datetime.tzinfo 抽象基底クラスの具体的な実装であり、tzinfo に指定することを想定しています。コンストラクタ、datetime.replace メソッド、datetime.astimezone メソッドのいずれかで指定します。

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

Datetimes constructed in this way are compatible with datetime arithmetic and handle daylight saving time transitions with no further intervention:

>>> dt_add = dt + timedelta(days=1)

>>> print(dt_add)
2020-11-01 12:00:00-08:00

>>> dt_add.tzname()
'PST'

These time zones also support the fold attribute introduced in PEP 495 [https://peps.python.org/pep-0495/]. During offset transitions which induce ambiguous times (such as a daylight saving time to standard time transition), the offset from before the transition is used when fold=0, and the offset after the transition is used when fold=1, for 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

When converting from another time zone, the fold will be set to the correct value:

>>> from datetime import timezone
>>> LOS_ANGELES = ZoneInfo("America/Los_Angeles")
>>> dt_utc = datetime(2020, 11, 1, 8, tzinfo=timezone.utc)

>>> # Before the PDT -> PST transition
>>> print(dt_utc.astimezone(LOS_ANGELES))
2020-11-01 01:00:00-07:00

>>> # After the PDT -> PST transition
>>> print((dt_utc + timedelta(hours=1)).astimezone(LOS_ANGELES))
2020-11-01 01:00:00-08:00

データソース

The zoneinfo module does not directly provide time zone data, and instead pulls time zone information from the system time zone database or the first-party PyPI package tzdata [https://pypi.org/project/tzdata/], if available. Some systems, including notably Windows systems, do not have an IANA database available, and so for projects targeting cross-platform compatibility that require time zone data, it is recommended to declare a dependency on tzdata. If neither system data nor tzdata are available, all calls to ZoneInfo will raise ZoneInfoNotFoundError.

Configuring the data sources

When ZoneInfo(key) is called, the constructor first searches the directories specified in TZPATH for a file matching key, and on failure looks for a match in the tzdata package. This behavior can be configured in three ways:

The default TZPATH when not otherwise specified can be configured at compile time.

TZPATH can be configured using an environment variable.

At runtime, the search path can be manipulated using the reset_tzpath() function.

Compile-time configuration

The default TZPATH includes several common deployment locations for the time zone database (except on Windows, where there are no "well-known" locations for time zone data). On POSIX systems, downstream distributors and those building Python from source who know where their system time zone data is deployed may change the default time zone path by specifying the compile-time option TZPATH (or, more likely, the configure flag --with-tzpath), which should be a string delimited by os.pathsep.

On all platforms, the configured value is available as the TZPATH key in sysconfig.get_config_var().

Environment configuration

When initializing TZPATH (either at import time or whenever reset_tzpath() is called with no arguments), the zoneinfo module will use the environment variable PYTHONTZPATH, if it exists, to set the search path.

PYTHONTZPATH

This is an os.pathsep-separated string containing the time zone search path to use. It must consist of only absolute rather than relative paths. Relative components specified in PYTHONTZPATH will not be used, but otherwise the behavior when a relative path is specified is implementation-defined; CPython will raise InvalidTZPathWarning, but other implementations are free to silently ignore the erroneous component or raise an exception.

To set the system to ignore the system data and use the tzdata package instead, set PYTHONTZPATH="".

Runtime configuration

The TZ search path can also be configured at runtime using the reset_tzpath() function. This is generally not an advisable operation, though it is reasonable to use it in test functions that require the use of a specific time zone path (or require disabling access to the system time zones).

ZoneInfo クラス

class zoneinfo.ZoneInfo(key)

文字列 key でIANAタイムゾーンを指定した、具体的な datetime.tzinfo のサブクラス。Calls to the primary constructor will always return objects that compare identically; put another way, barring cache invalidation via ZoneInfo.clear_cache(), for all values of key, the following assertion will always be true:

a = ZoneInfo(key)
b = ZoneInfo(key)
assert a is b

key must be in the form of a relative, normalized POSIX path, with no up-level references. The constructor will raise ValueError if a non-conforming key is passed.

key に一致するファイルが見つからない場合、コンストラクタは ZoneInfoNotFoundError を送出します。

ZoneInfo クラスには2つの別のコンストラクターがあります:

classmethod ZoneInfo.from_file(fobj, /, key=None)

file-like オブジェクトが返すbytes（バイナリーモードで開いたファイルや io.BytesIO オブジェクト）から ZoneInfo オブジェクトを構築します。一次コンストラクタと異なり、常に新規オブジェクトを構築します。

The key parameter sets the name of the zone for the purposes of __str__() and __repr__().

このコンストラクタで生成したオブジェクトはpickle化できません（pickling を参照）。

classmethod ZoneInfo.no_cache(key)

An alternate constructor that bypasses the constructor's cache. It is identical to the primary constructor, but returns a new object on each call. This is most likely to be useful for testing or demonstration purposes, but it can also be used to create a system with a different cache invalidation strategy.

Objects created via this constructor will also bypass the cache of a deserializing process when unpickled.

注意

Using this constructor may change the semantics of your datetimes in surprising ways, only use it if you know that you need to.

次のクラスメソッドもサポートされています:

classmethod ZoneInfo.clear_cache(*, only_keys=None)

A method for invalidating the cache on the ZoneInfo class. If no arguments are passed, all caches are invalidated and the next call to the primary constructor for each key will return a new instance.

If an iterable of key names is passed to the only_keys parameter, only the specified keys will be removed from the cache. Keys passed to only_keys but not found in the cache are ignored.

警告

Invoking this function may change the semantics of datetimes using ZoneInfo in surprising ways; this modifies module state and thus may have wide-ranging effects. Only use it if you know that you need to.

The class has one attribute:

ZoneInfo.key

This is a read-only attribute that returns the value of key passed to the constructor, which should be a lookup key in the IANA time zone database (e.g. America/New_York, Europe/Paris or Asia/Tokyo).

For zones constructed from file without specifying a key parameter, this will be set to None.

注釈

Although it is a somewhat common practice to expose these to end users, these values are designed to be primary keys for representing the relevant zones and not necessarily user-facing elements. Projects like CLDR (the Unicode Common Locale Data Repository) can be used to get more user-friendly strings from these keys.

文字列表現

The string representation returned when calling str on a ZoneInfo object defaults to using the ZoneInfo.key attribute (see the note on usage in the attribute documentation):

>>> 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]'

For objects constructed from a file without specifying a key parameter, str falls back to calling repr(). ZoneInfo's repr is implementation-defined and not necessarily stable between versions, but it is guaranteed not to be a valid ZoneInfo key.

Pickle serialization

Rather than serializing all transition data, ZoneInfo objects are serialized by key, and ZoneInfo objects constructed from files (even those with a value for key specified) cannot be pickled.

The behavior of a ZoneInfo file depends on how it was constructed:

ZoneInfo(key): When constructed with the primary constructor, a ZoneInfo object is serialized by key, and when deserialized, the deserializing process uses the primary and thus it is expected that these are expected to be the same object as other references to the same time zone. For example, if europe_berlin_pkl is a string containing a pickle constructed from ZoneInfo("Europe/Berlin"), one would expect the following behavior:

>>> a = ZoneInfo("Europe/Berlin")
>>> b = pickle.loads(europe_berlin_pkl)
>>> a is b
True

ZoneInfo.no_cache(key): When constructed from the cache-bypassing constructor, the ZoneInfo object is also serialized by key, but when deserialized, the deserializing process uses the cache bypassing constructor. If europe_berlin_pkl_nc is a string containing a pickle constructed from ZoneInfo.no_cache("Europe/Berlin"), one would expect the following behavior:

>>> a = ZoneInfo("Europe/Berlin")
>>> b = pickle.loads(europe_berlin_pkl_nc)
>>> a is b
False

ZoneInfo.from_file(fobj, /, key=None): When constructed from a file, the ZoneInfo object raises an exception on pickling. If an end user wants to pickle a ZoneInfo constructed from a file, it is recommended that they use a wrapper type or a custom serialization function: either serializing by key or storing the contents of the file object and serializing that.

This method of serialization requires that the time zone data for the required key be available on both the serializing and deserializing side, similar to the way that references to classes and functions are expected to exist in both the serializing and deserializing environments. It also means that no guarantees are made about the consistency of results when unpickling a ZoneInfo pickled in an environment with a different version of the time zone data.

関数

zoneinfo.available_timezones()

Get a set containing all the valid keys for IANA time zones available anywhere on the time zone path. This is recalculated on every call to the function.

This function only includes canonical zone names and does not include "special" zones such as those under the posix/ and right/ directories, or the posixrules zone.

注意

This function may open a large number of files, as the best way to determine if a file on the time zone path is a valid time zone is to read the "magic string" at the beginning.

注釈

These values are not designed to be exposed to end-users; for user facing elements, applications should use something like CLDR (the Unicode Common Locale Data Repository) to get more user-friendly strings. See also the cautionary note on ZoneInfo.key.

zoneinfo.reset_tzpath(to=None)

Sets or resets the time zone search path (TZPATH) for the module. When called with no arguments, TZPATH is set to the default value.

Calling reset_tzpath will not invalidate the ZoneInfo cache, and so calls to the primary ZoneInfo constructor will only use the new TZPATH in the case of a cache miss.

The to parameter must be a sequence of strings or os.PathLike and not a string, all of which must be absolute paths. ValueError will be raised if something other than an absolute path is passed.

Globals

zoneinfo.TZPATH

A read-only sequence representing the time zone search path -- when constructing a ZoneInfo from a key, the key is joined to each entry in the TZPATH, and the first file found is used.

TZPATH may contain only absolute paths, never relative paths, regardless of how it is configured.

The object that zoneinfo.TZPATH points to may change in response to a call to reset_tzpath(), so it is recommended to use zoneinfo.TZPATH rather than importing TZPATH from zoneinfo or assigning a long-lived variable to zoneinfo.TZPATH.

For more information on configuring the time zone search path, see Configuring the data sources.

例外と警告

exception zoneinfo.ZoneInfoNotFoundError

Raised when construction of a ZoneInfo object fails because the specified key could not be found on the system. This is a subclass of KeyError.

exception zoneinfo.InvalidTZPathWarning

Raised when PYTHONTZPATH contains an invalid component that will be filtered out, such as a relative path.

calendar --- General calendar-related functions

ソースコード: Lib/calendar.py [https://github.com/python/cpython/tree/3.12/Lib/calendar.py]

このモジュールは Unix の cal プログラムのようなカレンダー出力を行い、それに加えてカレンダーに関する有益な関数群を提供します。標準ではこれらのカレンダーは（ヨーロッパの慣例に従って）月曜日を週の始まりとし、日曜日を最後の日としています。 setfirstweekday() を用いることで、日曜日(6)や他の曜日を週の始まりに設定することができます。日付を表す引数は整数値で与えます。関連する機能として、 datetime と time モジュールも参照してください。

このモジュールに定義された関数やクラスは理想化されたカレンダー、つまり現在のグレゴリオ暦を過去と未来両方に無限に拡張したものを使っています。これはすべての計算の基礎のカレンダーとなっている、 Dershowitz と Reingold の本 "Calendrical Calculations" 中の "proleptic Gregorian" のカレンダーの定義に合致します。ゼロと負の年は ISO 8601 の基準に定められている通りに扱われます。0 年は 1 BC、-1 年は 2 BC、のように続きます。

class calendar.Calendar(firstweekday=0)

Calendar オブジェクトを作ります。 firstweekday は整数で週の始まりの曜日を指定するものです。MONDAY が 0 (デフォルト)、SUNDAY なら 6 です。

Calendar オブジェクトは整形されるカレンダーのデータを準備するために使えるいくつかのメソッドを提供しています。しかし整形機能そのものは提供していません。それはサブクラスの仕事なのです。

Calendar インスタンスには以下のメソッドがあります:

iterweekdays()

曜日の数字を一週間分生成するイテレータを返します。イテレータから得られる最初の数字は firstweekday が返す数字と同じになります。

itermonthdates(year, month)

year 年 month (1--12) 月に対するイテレータを返します。このイテレータはその月の全ての日、およびその月が始まる前の日とその月が終わった後の日のうち、週の欠けを埋めるために必要な日を (datetime.date オブジェクトとして) 返します。

itermonthdays(year, month)

Return an iterator for the month month in the year year similar to itermonthdates(), but not restricted by the datetime.date range. Days returned will simply be day of the month numbers. For the days outside of the specified month, the day number is 0.

itermonthdays2(year, month)

Return an iterator for the month month in the year year similar to itermonthdates(), but not restricted by the datetime.date range. Days returned will be tuples consisting of a day of the month number and a week day number.

itermonthdays3(year, month)

Return an iterator for the month month in the year year similar to itermonthdates(), but not restricted by the datetime.date range. Days returned will be tuples consisting of a year, a month and a day of the month numbers.

Added in version 3.7.

itermonthdays4(year, month)

Return an iterator for the month month in the year year similar to itermonthdates(), but not restricted by the datetime.date range. Days returned will be tuples consisting of a year, a month, a day of the month, and a day of the week numbers.

Added in version 3.7.

monthdatescalendar(year, month)

year 年 month 月の週のリストを返します。週は全て七つの datetime.date オブジェクトからなるリストです。

monthdays2calendar(year, month)

year 年 month 月の週のリストを返します。週は全て七つの日付の数字と曜日を表す数字のタプルからなるリストです。

monthdayscalendar(year, month)

year 年 month 月の週のリストを返します。週は全て七つの日付の数字からなるリストです。

yeardatescalendar(year, width=3)

指定された年のデータを整形に向く形で返します。返される値は月の並びのリストです。月の並びは最大で width ヶ月(デフォルトは3ヶ月)分です。各月は4ないし6週からなり、各週は1ないし7日からなります。各日は datetime.date オブジェクトです。

yeardays2calendar(year, width=3)

指定された年のデータを整形に向く形で返します (yeardatescalendar() と同様です)。週のリストの中が日付の数字と曜日の数字のタプルになります。月の範囲外の部分の日付はゼロです。

yeardayscalendar(year, width=3)

指定された年のデータを整形に向く形で返します (yeardatescalendar() と同様です)。週のリストの中が日付の数字になります。月の範囲外の日付はゼロです。

class calendar.TextCalendar(firstweekday=0)

このクラスはプレインテキストのカレンダーを生成するのに使えます。

TextCalendar インスタンスには以下のメソッドがあります:

formatmonth(theyear, themonth, w=0, l=0)

ひと月分のカレンダーを複数行の文字列で返します。 w により日の列幅を変えることができ、それらは中央揃えされます。 l により各週の表示される行数を変えることができます。 setfirstweekday() メソッドでセットされた週の最初の曜日に依存します。

prmonth(theyear, themonth, w=0, l=0)

formatmonth() で返されるひと月分のカレンダーを出力します。

formatyear(theyear, w=2, l=1, c=6, m=3)

m 列からなる一年間のカレンダーを複数行の文字列で返します。任意の引数 w, l, c はそれぞれ、日付列の表示幅、各週の行数及び月と月の間のスペースの数を変更するためのものです。 setfirstweekday() メソッドでセットされた週の最初の曜日に依存します。カレンダーを出力できる最初の年はプラットフォームに依存します。

pryear(theyear, w=2, l=1, c=6, m=3)

formatyear() で返される一年間のカレンダーを出力します。

class calendar.HTMLCalendar(firstweekday=0)

このクラスは HTML のカレンダーを生成するのに使えます。

HTMLCalendar インスタンスには以下のメソッドがあります:

formatmonth(theyear, themonth, withyear=True)

ひと月分のカレンダーを HTML のテーブルとして返します。withyear が真であればヘッダには年も含まれます。そうでなければ月の名前だけが使われます。

formatyear(theyear, width=3)

一年分のカレンダーを HTML のテーブルとして返します。width の値 (デフォルトでは 3 です) は何ヶ月分を一行に収めるかを指定します。

formatyearpage(theyear, width=3, css='calendar.css', encoding=None)

一年分のカレンダーを一つの完全な HTML ページとして返します。 width の値(デフォルトでは 3 です) は何ヶ月分を一行に収めるかを指定します。 css は使われるカスケーディングスタイルシートの名前です。スタイルシートを使わないようにするために None を渡すこともできます。 encoding には出力に使うエンコーディングを指定します (デフォルトではシステムデフォルトのエンコーディングです)。

formatmonthname(theyear, themonth, withyear=True)

Return a month name as an HTML table row. If withyear is true the year will be included in the row, otherwise just the month name will be used.

HTMLCalendar has the following attributes you can override to customize the CSS classes used by the calendar:

cssclasses

A list of CSS classes used for each weekday. The default class list is:

cssclasses = ["mon", "tue", "wed", "thu", "fri", "sat", "sun"]

more styles can be added for each day:

cssclasses = ["mon text-bold", "tue", "wed", "thu", "fri", "sat", "sun red"]

Note that the length of this list must be seven items.

cssclass_noday

The CSS class for a weekday occurring in the previous or coming month.

Added in version 3.7.

cssclasses_weekday_head

A list of CSS classes used for weekday names in the header row. The default is the same as cssclasses.

Added in version 3.7.

cssclass_month_head

The month's head CSS class (used by formatmonthname()). The default value is "month".

Added in version 3.7.

cssclass_month

The CSS class for the whole month's table (used by formatmonth()). The default value is "month".

Added in version 3.7.

cssclass_year

The CSS class for the whole year's table of tables (used by formatyear()). The default value is "year".

Added in version 3.7.

cssclass_year_head

The CSS class for the table head for the whole year (used by formatyear()). The default value is "year".

Added in version 3.7.

Note that although the naming for the above described class attributes is singular (e.g. cssclass_month cssclass_noday), one can replace the single CSS class with a space separated list of CSS classes, for example:

"text-bold text-red"

Here is an example how HTMLCalendar can be customized:

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"

class calendar.LocaleTextCalendar(firstweekday=0, locale=None)

This subclass of TextCalendar can be passed a locale name in the constructor and will return month and weekday names in the specified locale.

class calendar.LocaleHTMLCalendar(firstweekday=0, locale=None)

This subclass of HTMLCalendar can be passed a locale name in the constructor and will return month and weekday names in the specified locale.

注釈

The constructor, formatweekday() and formatmonthname() methods of these two classes temporarily change the LC_TIME locale to the given locale. Because the current locale is a process-wide setting, they are not thread-safe.

単純なテキストのカレンダーに関して、このモジュールには以下のような関数が提供されています。

calendar.setfirstweekday(weekday)

週の最初の曜日(0 は月曜日, 6 は日曜日)を設定します。定数 MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY 及び SUNDAY は便宜上提供されています。例えば、日曜日を週の開始日に設定するときは:

import calendar
calendar.setfirstweekday(calendar.SUNDAY)

calendar.firstweekday()

現在設定されている週の最初の曜日を返します。

calendar.isleap(year)

year が閏年なら True を、そうでなければ False を返します。

calendar.leapdays(y1, y2)

範囲(y1 ... y2)指定された期間の閏年の回数を返します。ここで y1 や y2 は年を表します。

この関数は、世紀の境目をまたぐ範囲でも正しく動作します。

calendar.weekday(year, month, day)

year (1970--...), month (1--12), day (1--31) で与えられた日の曜日(0 は月曜日)を返します。

calendar.weekheader(n)

短縮された曜日名を含むヘッダを返します。n は各曜日を何文字で表すかを指定します。

calendar.monthrange(year, month)

year と month で指定された月の一日の曜日と日数を返します。

calendar.monthcalendar(year, month)

月のカレンダーを行列で返します。各行が週を表し、月の範囲外の日は0になります。それぞれの週は setfirstweekday() で設定をしていない限り月曜日から始まります。

calendar.prmonth(theyear, themonth, w=0, l=0)

month() 関数によって返される月のカレンダーを出力します。

calendar.month(theyear, themonth, w=0, l=0)

Returns a month's calendar in a multi-line string using the formatmonth() of the TextCalendar class.

calendar.prcal(year, w=0, l=0, c=6, m=3)

calendar() 関数で返される一年間のカレンダーを出力します。

calendar.calendar(year, w=2, l=1, c=6, m=3)

Returns a 3-column calendar for an entire year as a multi-line string using the formatyear() of the TextCalendar class.

calendar.timegm(tuple)

カレンダーと直接は関係無いが、 time モジュールの gmtime() 関数が返す形式の時刻を表すタプルを引数に取り、1970 を基点とするエポック時刻で POSIX エンコーディングであると仮定して、対応する Unix タイムスタンプの値を返します。実際には、 time.gmtime() と timegm() はお互いの逆関数です。

calendar モジュールの以下のデータ属性を利用することができます:

calendar.day_name

現在のロケールでの曜日を表す配列です。

calendar.day_abbr

現在のロケールでの短縮された曜日を表す配列です。

calendar.MONDAY

calendar.TUESDAY

calendar.WEDNESDAY

calendar.THURSDAY

calendar.FRIDAY

calendar.SATURDAY

calendar.SUNDAY

Aliases for the days of the week, where MONDAY is 0 and SUNDAY is 6.

Added in version 3.12.

class calendar.Day

Enumeration defining days of the week as integer constants. The members of this enumeration are exported to the module scope as MONDAY through SUNDAY.

Added in version 3.12.

calendar.month_name

現在のロケールでの月の名を表す配列です。この配列は通常の約束事に従って、1月を数字の 1 で表しますので、長さが 13 ある代わりに month_name[0] が空文字列になります。

calendar.month_abbr

現在のロケールでの短縮された月の名を表す配列です。この配列は通常の約束事に従って、1月を数字の 1 で表しますので、長さが 13 ある代わりに month_abbr[0] が空文字列になります。

calendar.JANUARY

calendar.FEBRUARY

calendar.MARCH

calendar.APRIL

calendar.MAY

calendar.JUNE

calendar.JULY

calendar.AUGUST

calendar.SEPTEMBER

calendar.OCTOBER

calendar.NOVEMBER

calendar.DECEMBER

Aliases for the months of the year, where JANUARY is 1 and DECEMBER is 12.

Added in version 3.12.

class calendar.Month

Enumeration defining months of the year as integer constants. The members of this enumeration are exported to the module scope as JANUARY through DECEMBER.

Added in version 3.12.

The calendar module defines the following exceptions:

exception calendar.IllegalMonthError(month)

A subclass of ValueError, raised when the given month number is outside of the range 1-12 (inclusive).

month

The invalid month number.

exception calendar.IllegalWeekdayError(weekday)

A subclass of ValueError, raised when the given weekday number is outside of the range 0-6 (inclusive).

weekday

The invalid weekday number.

参考

datetime モジュール

time モジュールと似た機能を持った日付と時間用のオブジェクト指向インターフェース。

time モジュール

時間に関連した低水準の関数群。

コマンドラインからの使用

Added in version 2.5.

The calendar module can be executed as a script from the command line to interactively print a calendar.

python -m calendar [-h] [-L LOCALE] [-e ENCODING] [-t {text,html}]
                   [-w WIDTH] [-l LINES] [-s SPACING] [-m MONTHS] [-c CSS]
                   [year] [month]

For example, to print a calendar for the year 2000:

$ 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

以下のオプションが使用できます:

--help, -h

ヘルプメッセージを表示して終了します。

--locale LOCALE, -L LOCALE

The locale to use for month and weekday names. Defaults to English.

--encoding ENCODING, -e ENCODING

The encoding to use for output. --encoding is required if --locale is set.

--type {text,html}, -t {text,html}

Print the calendar to the terminal as text, or as an HTML document.

year

The year to print the calendar for. Must be a number between 1 and 9999. Defaults to the current year.

month

The month of the specified year to print the calendar for. Must be a number between 1 and 12, and may only be used in text mode. Defaults to printing a calendar for the full year.

Text-mode options:

--width WIDTH, -w WIDTH

The width of the date column in terminal columns. The date is printed centred in the column. Any value lower than 2 is ignored. Defaults to 2.

--lines LINES, -l LINES

The number of lines for each week in terminal rows. The date is printed top-aligned. Any value lower than 1 is ignored. Defaults to 1.

--spacing SPACING, -s SPACING

The space between months in columns. Any value lower than 2 is ignored. Defaults to 6.

--months MONTHS, -m MONTHS

The number of months printed per row. Defaults to 3.

HTML-mode options:

--css CSS, -c CSS

The path of a CSS stylesheet to use for the calendar. This must either be relative to the generated HTML, or an absolute HTTP or file:/// URL.

collections --- Container datatypes

ソースコード: Lib/collections/__init__.py [https://github.com/python/cpython/tree/3.12/Lib/collections/__init__.py]

このモジュールは、汎用の Python 組み込みコンテナ dict, list, set, および tuple に代わる、特殊なコンテナデータ型を実装しています。

namedtuple()

名前付きフィールドを持つタプルのサブクラスを作成するファクトリ関数

deque

両端における append や pop を高速に行えるリスト風のコンテナ

ChainMap

複数のマッピングの一つのビューを作成する辞書風のクラス

Counter

ハッシュ可能 なオブジェクトを数え上げる辞書のサブクラス

OrderedDict

項目が追加された順序を記憶する辞書のサブクラス

defaultdict

ファクトリ関数を呼び出して存在しない値を供給する辞書のサブクラス

UserDict

辞書のサブクラス化を簡単にする辞書オブジェクトのラッパ

UserList

リストのサブクラス化を簡単にするリストオブジェクトのラッパ

UserString

文字列のサブクラス化を簡単にする文字列オブジェクトのラッパ

ChainMap オブジェクト

Added in version 3.3.

ChainMap クラスは、複数のマッピングを素早く連結し、一つの単位として扱うために提供されています。これはたいてい、新しい辞書を作成して update() を繰り返すよりも早いです。

このクラスはネストされたスコープをシミュレートするのに使え、テンプレート化に便利です。

class collections.ChainMap(*maps)

ChainMap は、複数の辞書やその他のマッピングをまとめて、一つの、更新可能なビューを作成します。 maps が指定されないなら、一つの空辞書が与えられますから、新しいチェーンは必ず一つ以上のマッピングをもちます。

根底のマッピングはリストに保存されます。このリストはパブリックで、 maps 属性を使ってアクセスや更新できます。それ以外に状態はありません。

探索は、根底のマッピングをキーが見つかるまで引き続き探します。対して、書き込み、更新、削除は、最初のマッピングのみ操作します。

ChainMap は、根底のマッピングを参照によって組み込みます。ですから、根底のマッピングの一つが更新されると、その変更は ChainMap に反映されます。

通常の辞書のメソッドすべてがサポートされています。さらに、maps 属性、新しいサブコンテキストを作成するメソッド、最初のマッピング以外のすべてにアクセスするためのプロパティがあります:

maps

マッピングのユーザがアップデートできるリストです。このリストは最初に探されるものから最後に探されるものの順に並んでいます。これが唯一のソートされた状態であり、変更してマッピングが探される順番を変更できます。このリストは常に一つ以上のマッピングを含んでいなければなりません。

new_child(m=None, **kwargs)

新しいマッピングに現在のインスタンスが持つ全てのマッピングを追加したものを持つ新しい ChainMap インスタンスを返します。 m が指定された場合、新しいマッピングのリストの先頭部分になります; 指定されない場合は空の辞書が使われます。すなわち d.new_child() は ChainMap({}, *d.maps) と等価になります。キーワード引数が指定された場合、それらによって指定されたマッピングまたは空の辞書が更新されます。このメソッドは、元のマッピングに変更を加えることなく値を更新できるサブコンテキストを生成するのに使われます。

バージョン 3.4 で変更: オプションの m 引数が追加されました。

バージョン 3.10 で変更: キーワード引数のサポートが追加されました。

parents

現在のインスタンスの最初のマッピング以外のすべてのマッピングを含む新しい ChainMap を返すプロパティです。これは最初のマッピングを検索から飛ばすのに便利です。使用例は nonlocal キーワードを ネストされたスコープ に使う例と似ています。この使用例はまた、組み込み super() 関数にも似ています。 d.parents への参照は ChainMap(*d.maps[1:]) と等価です。

ChainMap() の反復順序は、マッピングオブジェクトを末尾から先頭に向かう走査で決まることに注意してください。

>>> baseline = {'music': 'bach', 'art': 'rembrandt'}
>>> adjustments = {'art': 'van gogh', 'opera': 'carmen'}
>>> list(ChainMap(adjustments, baseline))
['music', 'art', 'opera']

これは、末尾のマッピングオブジェクトから始めた一連の dict.update() の呼び出しと同じ順序になります。

>>> combined = baseline.copy()
>>> combined.update(adjustments)
>>> list(combined)
['music', 'art', 'opera']

バージョン 3.9 で変更: PEP 584 [https://peps.python.org/pep-0584/] で規定されている | 演算子と |= 演算子のサポートを追加しました。

参考

Enthought 社の CodeTools パッケージ [https://github.com/enthought/codetools] に含まれる MultiContext クラス [https://github.com/enthought/codetools/blob/4.0.0/codetools/contexts/multi_context.py] は、チェーン内のすべてのマッピングへの書き込みをサポートするオプションを持ちます。

Django のテンプレート用の Context class [https://github.com/django/django/blob/main/django/template/context.py] は、読み出し専用のマッピングのチェーンです。 new_child() メソッドや parents プロパティに似た push や pop の機能もあります。

The Nested Contexts recipe [https://code.activestate.com/recipes/577434-nested-contexts-a-chain-of-mapping-objects/] has options to control whether writes and other mutations apply only to the first mapping or to any mapping in the chain.

非常に単純化した読み出し専用バージョンの Chainmap [https://code.activestate.com/recipes/305268/]。

ChainMap の例とレシピ

この節では、チェーンされたマッピングを扱う様々な手法を示します。

Python の内部探索チェーンをシミュレートする例:

import builtins
pylookup = ChainMap(locals(), globals(), vars(builtins))

ユーザ指定のコマンドライン引数、環境変数、デフォルト値、の順に優先させる例:

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'])

ChainMap を使ってネストされたコンテキストをシミュレートするパターンの例:

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

ChainMap クラスは、探索はチェーン全体に対して行いますが、更新 (書き込みと削除) は最初のマッピングに対してのみ行います。しかし、深い書き込みと削除を望むなら、チェーンの深いところで見つかったキーを更新するサブクラスを簡単に作れます:

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'})

Counter オブジェクト

便利で迅速な検数をサポートするカウンタツールが提供されています。例えば:

>>> # 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)]

class collections.Counter([iterable-or-mapping])

Counter は ハッシュ可能 なオブジェクトをカウントする dict のサブクラスです。これは、要素を辞書のキーとして保存し、そのカウントを辞書の値として保存するコレクションです。カウントは、0 や負のカウントを含む整数値をとれます。 Counter クラスは、他の言語のバッグや多重集合のようなものです。

要素は、 iterable から数え上げられたり、他の mapping (やカウンタ) から初期化されます:

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

カウンタオブジェクトは辞書のインターフェースを持ちますが、存在しない要素に対して KeyError を送出する代わりに 0 を返すという違いがあります:

>>> c = Counter(['eggs', 'ham'])
>>> c['bacon']                              # count of a missing element is zero
0

カウントを 0 に設定しても、要素はカウンタから取り除かれません。完全に取り除くには、 del を使ってください:

>>> c['sausage'] = 0                        # counter entry with a zero count
>>> del c['sausage']                        # del actually removes the entry

Added in version 3.1.

バージョン 3.7 で変更: Counter は dict のサブクラスとして要素の挿入順を維持する機能を継承しました。 Counter オブジェクトに対する数学演算も順序を維持します。結果の順序はまず左の被演算子における要素の出現順に従い、その後右の被演算子において要素が出現する順序になります。

カウンタオブジェクトは全ての辞書で利用できるメソッドに加えて、以下に示す追加のメソッドをサポートしています。

elements()

それぞれの要素を、そのカウント分の回数だけ繰り返すイテレータを返します。要素は挿入した順番で返されます。ある要素のカウントが 1 未満なら、 elements() はそれを無視します。

>>> c = Counter(a=4, b=2, c=0, d=-2)
>>> sorted(c.elements())
['a', 'a', 'a', 'a', 'b', 'b']

most_common([n])

最も多い n 要素を、カウントが多いものから少ないものまで順に並べたリストを返します。 n が省略されるか None であれば、 most_common() はカウンタの すべての 要素を返します。等しいカウントの要素は挿入順に並べられます:

>>> Counter('abracadabra').most_common(3)
[('a', 5), ('b', 2), ('r', 2)]

subtract([iterable-or-mapping])

要素から iterable の要素または mapping の要素が引かれます。 dict.update() に似ていますが、カウントを置き換えるのではなく引きます。入力も出力も、 0 や負になりえます。

>>> 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})

Added in version 3.2.

total()

カウントの合計を計算します。

>>> c = Counter(a=10, b=5, c=0)
>>> c.total()
15

Added in version 3.10.

普通の辞書のメソッドは、以下の 2 つのメソッドがカウンタに対して異なる振る舞いをするのを除き、 Counter オブジェクトにも利用できます。

fromkeys(iterable)

このクラスメソッドは Counter オブジェクトには実装されていません。

update([iterable-or-mapping])

要素が iterable からカウントされるか、別の mapping (やカウンタ) が追加されます。 dict.update() に似ていますが、カウントを置き換えるのではなく追加します。また、 iterable には (key, value) 対のシーケンスではなく、要素のシーケンスが求められます。

カウンタオブジェクトは等価、部分集合、上位集合のための次の拡張比較 (rich comparison) 演算子をサポートします: ==, !=, <, <=, >, >=。これらの比較は、存在しない要素をカウントがゼロであるとみなします。すなわち、 Counter(a=1) == Counter(a=1, b=0) は真を返します。

バージョン 3.10 で変更: 拡張比較 (rich comparison) 演算が追加されました。

バージョン 3.10 で変更: 等価比較において、存在しない要素はカウントがゼロであるとみなされるようになりました。かつては Counter(a=3) と Counter(a=3, b=0) は異なるとみなされていました。

Counter オブジェクトを使ったよくあるパターン:

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()                       # convert to a list of (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

Counter オブジェクトを組み合わせて多重集合 (0より大きいカウントを持つカウンタ) を作るためのいくつかの数学演算が提供されています。加算と減算はそれぞれの要素のカウンタを加算または減算することによりカウンタオブジェクトを組み合わせます。積集合と和集合は、それぞれのカウントの最大値と最小値を返します。等価と包含はそれぞれのカウントを比較します。それぞれの演算は符号付きカウントを持った入力を受け付けますが、カウントが0以下の要素は結果から取り除かれます。

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

単項加算および減算は、空カウンタの加算や空カウンタからの減算へのショートカットです。

>>> c = Counter(a=2, b=-4)
>>> +c
Counter({'a': 2})
>>> -c
Counter({'b': 4})

Added in version 3.3: 単項加算、単項減算、in-place の多重集合操作のサポートが追加されました。

注釈

カウンタはもともと、推移するカウントを正の整数で表すために設計されました。しかし、他の型や負の値を必要とするユースケースを不必要に排除することがないように配慮されています。このようなユースケースの助けになるように、この節で最低限の範囲と型の制限について記述します。

Counter クラス自体は辞書のサブクラスで、キーと値に制限はありません。値はカウントを表す数であることを意図していますが、値フィールドに任意のものを保存 できます 。

most_common() メソッドが要求するのは、値が順序付け可能なことだけです。

c[key] += 1 のようなインプレース演算では、値の型に必要なのは 足し算と引き算ができることだけです。よって分数、浮動小数点数、 小数も使え、負の値がサポートされています。これと同じことが、 負や 0 の値を入力と出力に許す update() と subtract() メソッド にも言えます。

多重集合メソッドは正の値を扱うユースケースに対してのみ設計されています。入力は負や 0 に出来ますが、正の値の出力のみが生成されます。型の制限はありませんが、値の型は足し算、引き算、比較をサポートしている必要があります。

elements() メソッドは整数のカウントを要求します。これは 0 と負のカウントを無視します。

参考

Smalltalk の Bag class [https://www.gnu.org/software/smalltalk/manual-base/html_node/Bag.html] 。

Wikipedia の Multisets [https://en.wikipedia.org/wiki/Multiset] の項目。

C++ multisets [http://www.java2s.com/Tutorial/Cpp/0380__set-multiset/Catalog0380__set-multiset.htm] の例を交えたチュートリアル。

数学的な多重集合の演算とそのユースケースは、 Knuth, Donald. The Art of Computer Programming Volume II, Section 4.6.3, Exercise 19 を参照してください。

与えられた要素の集まりからなる与えられた大きさの相違なる多重集合をすべて数え上げるには、 itertools.combinations_with_replacement() を参照してください:

map(Counter, combinations_with_replacement('ABC', 2)) # --> AA AB AC BB BC CC

deque オブジェクト

class collections.deque([iterable[, maxlen]])

iterable で与えられるデータから、新しい deque オブジェクトを (append() をつかって) 左から右に初期化して返します。 iterable が指定されない場合、新しい deque オブジェクトは空になります。

Deques are a generalization of stacks and queues (the name is pronounced "deck" and is short for "double-ended queue"). Deques support thread-safe, memory efficient appends and pops from either side of the deque with approximately the same O(1) performance in either direction.

Though list objects support similar operations, they are optimized for fast fixed-length operations and incur O(n) memory movement costs for pop(0) and insert(0, v) operations which change both the size and position of the underlying data representation.

maxlen が指定されなかったり None だった場合、 deque は任意のサイズまで大きくなります。そうでない場合、 deque のサイズは指定された最大長に制限されます。長さが制限された deque がいっぱいになると、新しい要素を追加するときに追加した要素数分だけ追加したのと反対側から要素が捨てられます。長さが制限された deque は Unix における tail フィルタと似た機能を提供します。トランザクションの tracking や最近使った要素だけを残したいデータプール (pool of data) などにも便利です。

Deque オブジェクトは以下のようなメソッドをサポートしています:

append(x)

x を deque の右側につけ加えます。

appendleft(x)

x を deque の左側につけ加えます。

clear()

deque からすべての要素を削除し、長さを 0 にします。

copy()

deque の浅いコピーを作成します。

Added in version 3.5.

count(x)

deque の x に等しい要素を数え上げます。

Added in version 3.2.

extend(iterable)

イテラブルな引数 iterable から得られる要素を deque の右側に追加し拡張します。

extendleft(iterable)

イテラブルな引数 iterable から得られる要素を deque の左側に追加し拡張します。注意: 左から追加した結果は、イテラブルな引数の順序とは逆になります。

index(x[, start[, stop]])

deque 内の x の位置を返します (インデックス start からインデックス stop の両端を含む範囲で)。最初のマッチを返すか、見つからない場合には ValueError を発生させます。

Added in version 3.5.

insert(i, x)

x を deque の位置 i に挿入します。

挿入によって、長さに制限のある deque の長さが maxlen を超える場合、IndexError が発生します。

Added in version 3.5.

pop()

deque の右側から要素をひとつ削除し、その要素を返します。要素がひとつも存在しない場合は IndexError を発生させます。

popleft()

deque の左側から要素をひとつ削除し、その要素を返します。要素がひとつも存在しない場合は IndexError を発生させます。

remove(value)

value の最初に現れるものを削除します。要素が見付からないない場合は ValueError を送出します。

reverse()

deque の要素をインプレースに反転し、None を返します。

Added in version 3.2.

rotate(n=1)

deque の要素を全体で n ステップだけ右にローテートします。n が負の値の場合は、左にローテートします。

deque が空でないときは、 deque をひとつ右にローテートすることは d.appendleft(d.pop()) と同じで、 deque をひとつ左にローテートすることは d.append(d.popleft()) と同じです。

deque オブジェクトは読み出し専用属性も 1 つ提供しています:

maxlen

deque の最大長で、制限されていなければ None です。

Added in version 3.1.

In addition to the above, deques support iteration, pickling, len(d), reversed(d), copy.copy(d), copy.deepcopy(d), membership testing with the in operator, and subscript references such as d[0] to access the first element. Indexed access is O(1) at both ends but slows to O(n) in the middle. For fast random access, use lists instead.

バージョン 3.5 から deque は __add__(), __mul__(), __imul__() をサポートしました。

例:

>>> 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'])

deque のレシピ

この節では deque を使った様々なアプローチを紹介します。

長さが制限された deque は Unix における tail フィルタに相当する機能を提供します:

def tail(filename, n=10):
    'Return the last n lines of a file'
    with open(filename) as f:
        return deque(f, n)

deque を使用する別のアプローチは、右に要素を追加し左から要素を取り出すことで最近追加した要素のシーケンスを保持することです:

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

ラウンドロビンスケジューラ [https://en.wikipedia.org/wiki/Round-robin_scheduling] は、入力されたイテレータを deque に格納することで実装できます。値は、位置0にある選択中のイテレータから取り出されます。そのイテレータが値を出し切った場合は、 popleft() で除去できます; そうでない場合は、 rotate() メソッドで末尾に回せます:

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()

rotate() メソッドは、 deque のスライスや削除の機能を提供します。例えば、 純粋な Python 実装の del d[n] は rotate() メソッドを頼りに、pop される要素の位置を割り出します:

def delete_nth(d, n):
    d.rotate(-n)
    d.popleft()
    d.rotate(n)

deque のスライスの実装でも、同様のアプローチを使います。まず対象となる要素を rotate() によって deque の左端まで移動させてから、 popleft() で古い要素を削除します。そして、 extend() で新しい要素を追加したのち、循環を逆にします。このアプローチをやや変えたものとして、Forth スタイルのスタック操作、つまり dup, drop, swap, over, pick, rot, および roll を実装するのも簡単です。

defaultdict オブジェクト

class collections.defaultdict(default_factory=None, /[, ...])

新しい辞書に似たオブジェクトを返します。 defaultdict は組み込みの dict クラスのサブクラスです。これはメソッドをひとつオーバーライドし、書き込み可能なインスタンス変数をひとつ追加しています。それ以外の機能は dict クラスと同じですので、ここでは説明しません。

1つ目の引数は default_factory 属性の初期値です。デフォルトは None です。残りの引数はキーワード引数も含め、 dict のコンストラクタに与えられた場合と同様に扱われます。

defaultdict オブジェクトは標準の dict に加えて、以下のメソッドを実装しています:

__missing__(key)

もし default_factory 属性が None であれば、このメソッドは KeyError 例外を、 key を引数として発生させます。

もし default_factory 属性が None でない場合、このメソッドは引数なしで呼び出され、与えらえた key に対応するデフォルト値を提供します。この値は、辞書内に key に対応して登録され、最後に返されます。

もし default_factory の呼出が例外を発生させた場合には、変更せずそのまま例外を投げます。

This method is called by the __getitem__() method of the dict class when the requested key is not found; whatever it returns or raises is then returned or raised by __getitem__().

Note that __missing__() is not called for any operations besides __getitem__(). This means that get() will, like normal dictionaries, return None as a default rather than using default_factory.

defaultdict オブジェクトは以下のインスタンス変数をサポートしています:

default_factory

この属性は __missing__() メソッドによって使われます。これは存在すればコンストラクタの第1引数によって初期化され、そうでなければ None になります。

バージョン 3.9 で変更: PEP 584 [https://peps.python.org/pep-0584/] で規定されている合成演算子 (|) と更新演算子 (|=)が追加されました。

defaultdict の使用例

list を default_factory とすることで、キー=値ペアのシーケンスをリストの辞書へ簡単にグループ化できます。:

>>> 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])]

それぞれのキーが最初に登場したとき、マッピングにはまだ存在しません。そのためエントリは default_factory 関数が返す空の list を使って自動的に作成されます。 list.append() 操作は新しいリストに紐付けられます。キーが再度出現した場合には、通常の参照動作が行われます(そのキーに対応するリストが返ります)。そして list.append() 操作で別の値をリストに追加します。このテクニックは dict.setdefault() を使った等価なものよりシンプルで速いです:

>>> d = {}
>>> for k, v in s:
...     d.setdefault(k, []).append(v)
...
>>> sorted(d.items())
[('blue', [2, 4]), ('red', [1]), ('yellow', [1, 3])]

default_factory を int にすると、 defaultdict を(他の言語の bag や multisetのように)要素の数え上げに便利に使うことができます:

>>> s = 'mississippi'
>>> d = defaultdict(int)
>>> for k in s:
...     d[k] += 1
...
>>> sorted(d.items())
[('i', 4), ('m', 1), ('p', 2), ('s', 4)]

最初に文字が出現したときは、マッピングが存在しないので default_factory 関数が int() を呼んでデフォルトのカウント0を生成します。インクリメント操作が各文字を数え上げます。

常に0を返す int() は特殊な関数でした。定数を生成するより速くて柔軟な方法は、 0に限らず何でも定数を生成するラムダ関数を使うことです:

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

default_factory を set に設定することで、 defaultdict をセットの辞書を作るために利用することができます:

>>> 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})]

namedtuple() 名前付きフィールドを持つタプルのファクトリ関数

名前付きタプルは、タプルの中のすべての場所に意味を割り当てて、より読みやすく自己解説的なコードを書けるようにします。通常のタプルが利用される場所ならどこでも利用でき、場所に対するインデックスの代わりに名前を使ってフィールドにアクセスできるようになります。

collections.namedtuple(typename, field_names, *, rename=False, defaults=None, module=None)

typename という名前の tuple の新しいサブクラスを返します。新しいサブクラスは、 tuple に似ているけれどもインデックスやイテレータだけでなく属性名によるアクセスもできるオブジェクトを作るのに使います。このサブクラスのインスタンスは、わかりやすい docstring (型名と属性名が入っています) や、 tuple の内容を name=value という形のリストで返す使いやすい __repr__() も持っています。

field_names は ['x', 'y'] のような文字列のシーケンスです。 field_names には、代わりに各属性名を空白文字 (whitespace) および/またはカンマ (,) で区切った文字列を渡すこともできます。例えば、 'x y' や 'x, y' です。

アンダースコア (_) で始まる名前を除いて、 Python の正しい識別子 (identifier) ならなんでも属性名として使うことができます。正しい識別子とはアルファベット(letters), 数字(digits), アンダースコア(_) を含みますが、数字やアンダースコアで始まる名前や、 class, for, return, global, pass, raise などといった keyword は使えません。

rename が真の場合、不適切なフィールド名は自動的に位置を示す名前に置き換えられます。例えば ['abc', 'def', 'ghi', 'abc'] は、予約語の def と、重複しているフィールド名の abc が除去され、['abc', '_1', 'ghi', '_3'] に変換されます。

defaults には None あるいはデフォルト値の iterable が指定できます。デフォルト値を持つフィールドはデフォルト値を持たないフィールドより後ろに来なければならないので、 defaults は最も右にある変数に適用されます。例えば、 field_names が ['x', 'y', 'z'] で defaults が (1, 2) の場合、 x は必須の引数、 y は 1 がデフォルト、 z は 2 がデフォルトとなります。

もし module が指定されていれば、名前付きタプルの __module__ 属性は、指定された値に設定されます

名前付きタプルのインスタンスはインスタンスごとの辞書を持たないので、軽量で、普通のタプル以上のメモリを使用しません。

pickle 化をサポートするには、名前付きタプルのクラス定義は typename と同じ名前の変数に割り当てなければなりません。

バージョン 3.1 で変更: rename のサポートが追加されました。

バージョン 3.6 で変更: verbose と rename 引数が キーワード専用引数 になりました.

バージョン 3.6 で変更: module 引数が追加されました。

バージョン 3.7 で変更: verbose 引数と _source 属性が削除されました。

バージョン 3.7 で変更: defaults 引数と _field_defaults 属性が追加されました。

>>> # 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)

名前付きタプルは csv や sqlite3 モジュールが返すタプルのフィールドに名前を付けるときにとても便利です:

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)

タプルから継承したメソッドに加えて、名前付きタプルは3つの追加メソッドと2つの属性をサポートしています。フィールド名との衝突を避けるために、メソッド名と属性名はアンダースコアで始まります。

classmethod somenamedtuple._make(iterable)

既存の sequence や Iterable から新しいインスタンスを作るクラスメソッド.

>>> t = [11, 22]
>>> Point._make(t)
Point(x=11, y=22)

somenamedtuple._asdict()

フィールド名を対応する値にマッピングする新しい dict を返します:

>>> p = Point(x=11, y=22)
>>> p._asdict()
{'x': 11, 'y': 22}

バージョン 3.1 で変更: 通常の dict の代わりに OrderedDict を返すようになりました。

バージョン 3.8 で変更: collections.OrderedDict ではなく dict を返すようになりました。Python 3.7以降は、通常の辞書で順番が保証されています。 OrderedDict 特有の機能を使いたい場合は、結果を OrderedDict(nt._asdict()) 型にキャストして使用することを推奨します。

somenamedtuple._replace(**kwargs)

指定されたフィールドを新しい値で置き換えた、新しい名前付きタプルを作って返します:

>>> 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())

somenamedtuple._fields

フィールド名をリストにしたタプルです。内省 (introspection) したり、既存の名前付きタプルをもとに新しい名前つきタプルを作成する時に便利です。

>>> p._fields            # view the field names
('x', 'y')

>>> Color = namedtuple('Color', 'red green blue')
>>> Pixel = namedtuple('Pixel', Point._fields + Color._fields)
>>> Pixel(11, 22, 128, 255, 0)
Pixel(x=11, y=22, red=128, green=255, blue=0)

somenamedtuple._field_defaults

フィールド名からデフォルト値への対応を持つ辞書です。

>>> Account = namedtuple('Account', ['type', 'balance'], defaults=[0])
>>> Account._field_defaults
{'balance': 0}
>>> Account('premium')
Account(type='premium', balance=0)

文字列に格納された名前を使って名前つきタプルから値を取得するには getattr() 関数を使います:

>>> getattr(p, 'x')
11

辞書を名前付きタプルに変換するには、 ** 演算子 (double-star-operator, 引数リストのアンパック で説明しています) を使います。:

>>> d = {'x': 11, 'y': 22}
>>> Point(**d)
Point(x=11, y=22)

名前付きタプルは通常の Python クラスなので、継承して機能を追加したり変更するのは容易です。次の例では計算済みフィールドと固定幅の print format を追加しています:

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

このサブクラスは __slots__ に空のタプルをセットしています。これにより、インスタンス辞書の作成を抑制してメモリ使用量を低く保つのに役立ちます。

サブクラス化は新しいフィールドを追加するのには適していません。代わりに、新しい名前付きタプルを _fields 属性を元に作成してください:

>>> Point3D = namedtuple('Point3D', Point._fields + ('z',))

__doc__ フィールドに直接代入することでドックストリングをカスタマイズすることが出来ます:

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

バージョン 3.5 で変更: 属性ドックストリングが書き込み可能になりました。

参考

名前付きタプルに型ヒントを追加する方法については、 typing.NamedTuple を参照してください。 class キーワードを使った洗練された記法も紹介されています:

class Component(NamedTuple):
    part_number: int
    weight: float
    description: Optional[str] = None

タプルではなく、辞書をもとにした変更可能な名前空間を作成するには types.SimpleNamespace() を参照してください。

dataclasses モジュールは、生成される特殊メソッドをユーザー定義クラスに自動的に追加するためのデコレータや関数を提供しています。

OrderedDict オブジェクト

順序付き辞書は普通の辞書のようですが、順序操作に関係する追加の機能があります。組み込みの dict クラスが挿入順序を記憶しておく機能 (この新しい振る舞いは Python 3.7 で保証されるようになりました) を獲得した今となっては、順序付き辞書の重要性は薄れました。

いまだ残っている dict との差分:

通常の dict は対応付けに向いているように設計されました。挿入順序の追跡は二の次です。

OrderedDict は並べ替え操作に向いているように設計されました。空間効率、反復処理の速度、更新操作のパフォーマンスは二の次です。

OrderedDict のアルゴリズムは、頻繁な並べ替え処理を dict よりもうまく扱うことができます。後述のレシピに示されている通り、この性質はさまざまな種類の LRU キャッシュの実装に適しています。

OrderedDict に対する等価演算は突き合わせ順序もチェックします。

組み込みの dict では、順序を考慮した等価演算は p == q and all(k1 == k2 for k1, k2 in zip(p, q)) で実現することができます。

OrderedDict の popitem() メソッドはシグネチャが異なります。どの要素を取り出すかを指定するオプション引数を受け付けます。

組み込みの dict の場合、 OrderedDict の od.popitem(last=True) と同じ機能は、最も右側の (最後の) 要素を取り出すことが保証されている d.popitem() が果たします。

組み込みの dict の場合、 OrderedDict の od.popitem(last=False) は (k := next(iter(d)), d.pop(k)) で実現できます。これにより、該当する要素のうちで最も左側の (先頭の) ものを辞書から削除して返すことができます。

OrderedDict には、 効率的に要素を末尾に置き直す move_to_end() メソッドがあります。

組み込みの dict の場合、キーと値のペアを最も右側 (末尾) に移動する OrderedDict の od.move_to_end(k, last=True) は d[k] = d.pop(k) で実現できます。

組み込みの dict では、キーと値のペアを最も左側 (先頭) に移動する OrderedDict の od.move_to_end(k, last=False) を実現する効率の良い方法はありません。

Python 3.8 以前は、 dict には __reversed__() メソッドが欠けています。

class collections.OrderedDict([items])

辞書の順序を並べ直すためのメソッドを持つ dict のサブクラスのインスタンスを返します。

Added in version 3.1.

popitem(last=True)

順序付き辞書の popitem() メソッドは、(key, value) 対を返して消去します。この対は last が真なら LIFO で、偽なら FIFO で返されます。

move_to_end(key, last=True)

存在する key を順序付き辞書の先頭または末尾に移動します。要素は last が真 (デフォルト) の場合に最も右側すなわち末尾に移動します。また last が偽の場合には先頭に移動します。指定した key が存在しない場合は KeyError を送出します。

>>> d = OrderedDict.fromkeys('abcde')
>>> d.move_to_end('b')
>>> ''.join(d)
'acdeb'
>>> d.move_to_end('b', last=False)
>>> ''.join(d)
'bacde'

Added in version 3.2.

通常のマッピングのメソッドに加え、順序付き辞書は reversed() による逆順の反復もサポートしています。

OrderedDict 間の等価判定は順序が影響し、 list(od1.items())==list(od2.items()) のように実装されます。 OrderedDict オブジェクトと他のマッピング (Mapping) オブジェクトの等価判定は、順序に影響されず、通常の辞書と同様です。これによって、 OrderedDict オブジェクトは通常の辞書が使われるところならどこでも使用できます。

バージョン 3.5 で変更: OrderedDict の項目、キー、値の ビュー が reversed() による逆順の反復をサポートするようになりました。

バージョン 3.6 で変更: PEP 468 [https://peps.python.org/pep-0468/] の受理によって、OrderedDict のコンストラクタと、update() メソッドに渡したキーワード引数の順序は保持されます。

バージョン 3.9 で変更: PEP 584 [https://peps.python.org/pep-0584/] で規定されている合成演算子 (|) と更新演算子 (|=)が追加されました。

OrderedDict の例とレシピ

キーが 最後に 追加されたときの順序を記憶する、順序付き辞書の変種を作るのは簡単です。新しい値が既存の値を上書きする場合、元々の挿入位置が最後尾へ変更されます:

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)

OrderedDict は functools.lru_cache() の変種を実装するのにも役に立ちます:

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(0)
        return result

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(0)
        else:
            self.requests.pop(args, None)
            self.cache[args] = result
            if len(self.cache) > self.maxsize:
                self.cache.popitem(0)
        return result

UserDict オブジェクト

クラス UserDict は、辞書オブジェクトのラッパとしてはたらきます。このクラスの必要性は、 dict から直接的にサブクラス化できる能力に部分的に取って代わられました; しかし、根底の辞書に属性としてアクセスできるので、このクラスを使った方が簡単になることもあります。

class collections.UserDict([initialdata])

辞書をシミュレートするクラスです。インスタンスの内容は通常の辞書に保存され、 UserDict インスタンスの data 属性を通してアクセスできます。 initialdata が与えられれば、 data はその内容で初期化されます。他の目的のために使えるように、 initialdata への参照が保存されないことに注意してください。

マッピングのメソッドと演算をサポートするのに加え、 UserDict インスタンスは以下の属性を提供します:

data

UserDict クラスの内容を保存するために使われる実際の辞書です。

UserList オブジェクト

このクラスはリストオブジェクトのラッパとしてはたらきます。これは独自のリスト風クラスの基底クラスとして便利で、既存のメソッドをオーバーライドしたり新しいメソッドを加えたりできます。こうして、リストに新しい振る舞いを加えられます。

このクラスの必要性は、 list から直接的にサブクラス化できる能力に部分的に取って代わられました; しかし、根底のリストに属性としてアクセスできるので、このクラスを使った方が簡単になることもあります。

class collections.UserList([list])

リストをシミュレートするクラスです。インスタンスの内容は通常のリストに保存され、 UserList インスタンスの data 属性を通してアクセスできます。インスタンスの内容は最初に list のコピーに設定されますが、デフォルトでは空リスト [] です。 list は何らかのイテラブル、例えば通常の Python リストや UserList オブジェクト、です。

ミュータブルシーケンスのメソッドと演算をサポートするのに加え、 UserList インスタンスは以下の属性を提供します:

data

UserList クラスの内容を保存するために使われる実際の list オブジェクトです。

サブクラス化の要件: UserList のサブクラスは引数なしか、あるいは一つの引数のどちらかとともに呼び出せるコンストラクタを提供することが期待されています。新しいシーケンスを返すリスト演算は現在の実装クラスのインスタンスを作成しようとします。そのために、データ元として使われるシーケンスオブジェクトである一つのパラメータとともにコンストラクタを呼び出せると想定しています。

派生クラスがこの要求に従いたくないならば、このクラスがサポートしているすべての特殊メソッドはオーバーライドされる必要があります。その場合に提供される必要のあるメソッドについての情報は、ソースを参考にしてください。

UserString オブジェクト

クラス UserString は、文字列オブジェクトのラッパとしてはたらきます。このクラスの必要性は、 str から直接的にサブクラス化できる能力に部分的に取って代わられました; しかし、根底の文字列に属性としてアクセスできるので、このクラスを使った方が簡単になることもあります。

class collections.UserString(seq)

文字列オブジェクトをシミュレートするクラスです。インスタンスの内容は通常の文字列に保存され、 UserString インスタンスの data 属性を通してアクセスできます。インスタンスの内容には最初に seq のコピーが設定されます。 seq 引数は、組み込みの str() 関数で文字列に変換できる任意のオブジェクトです。

文字列のメソッドと演算をサポートするのに加え、 UserString インスタンスは次の属性を提供します:

data

UserString クラスの内容を保存するために使われる実際の str オブジェクトです。

バージョン 3.5 で変更: 新たなメソッド __getnewargs__, __rmod__, casefold, format_map, isprintable, maketrans。

collections.abc --- Abstract Base Classes for Containers

Added in version 3.3: 以前はこのモジュールは collections モジュールの一部でした。

ソースコード: Lib/_collections_abc.py [https://github.com/python/cpython/tree/3.12/Lib/_collections_abc.py]

This module provides abstract base classes that can be used to test whether a class provides a particular interface; for example, whether it is hashable or whether it is a mapping.

issubclass() や isinstance() を使ったインターフェースに対するテストは、以下の3つのいずれかの方法で動作します。

1） 新しく定義したクラスは抽象基底クラスのいずれかを直接継承することができます。その場合クラスは必要な抽象メソッドを提供しなければなりません。残りのミックスインメソッドは継承により引き継がれますが、必要ならオーバーライドすることができます。その他のメソッドは必要に応じて追加することができます:

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

>>> issubclass(C, Sequence)
True
>>> isinstance(C(), Sequence)
True

2） 既存のクラスや組み込みのクラスを "仮想派生クラス" として ABC に登録することができます。これらのクラスは、全ての抽象メソッドとミックスインメソッドを含む完全な API を定義する必要があります。これにより、そのクラスが完全なインターフェースをサポートしているかどうかを、ユーザーが issubclass() や isinstance() で判断できるようになります。このルールの例外は、残りの API から自動的に推測ができるようなメソッドです:

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

>>> issubclass(D, Sequence)
True
>>> isinstance(D(), Sequence)
True

In this example, class D does not need to define __contains__, __iter__, and __reversed__ because the in-operator, the iteration logic, and the reversed() function automatically fall back to using __getitem__ and __len__.

3） いくつかの単純なインターフェースは、必要なメソッドの存在だけで (それらのメソッドが None に設定されていなければ) 直接認識されます:

class E:
    def __iter__(self): ...
    def __next__(self): ...

>>> issubclass(E, Iterable)
True
>>> isinstance(E(), Iterable)
True

複雑なインターフェースは、単に特定のメソッドが存在すること以上の定義を持つため、3番目のテクニックをサポートしていません。それらのインターフェースはメソッドの意味やメソッド間の関係まで指定するので、特定のメソッド名の存在からだけではインターフェースの推測ができません。たとえば、あるクラスが __getitem__, __len__, および __iter__ を提供するというだけでは、 Sequence と Mapping を区別するには不十分です。

Added in version 3.9: これらの抽象クラスは [] をサポートするようになりました。 ジェネリックエイリアス型 および PEP 585 [https://peps.python.org/pep-0585/] を参照してください。

コレクション抽象基底クラス

collections モジュールは以下の ABC (抽象基底クラス) を提供します:

ABC

継承しているクラス

抽象メソッド

mixin メソッド

Container [1]

__contains__

Hashable [1]

__hash__

Iterable [1] [2]

__iter__

Iterator [1]

Iterable

__next__

__iter__

Reversible [1]

Iterable

__reversed__

Generator [1]

Iterator

send, throw

close, __iter__, __next__

Sized [1]

__len__

Callable [1]

__call__

Collection [1]

Sized, Iterable, Container

__contains__, __iter__, __len__

Sequence

Reversible, Collection

__getitem__, __len__

__contains__, __iter__, __reversed__, index, count

MutableSequence

Sequence

__getitem__, __setitem__, __delitem__, __len__, insert

Inherited Sequence methods and append, clear, reverse, extend, pop, remove, and __iadd__

ByteString

Sequence

__getitem__, __len__

Sequence から継承したメソッド

Set

Collection

__contains__, __iter__, __len__

__le__, __lt__, __eq__, __ne__, __gt__, __ge__, __and__, __or__, __sub__, __xor__, isdisjoint

MutableSet

Set

__contains__, __iter__, __len__, add, discard

Set から継承したメソッドと、 clear, pop, remove, __ior__, __iand__, __ixor__, __isub__

Mapping

Collection

__getitem__, __iter__, __len__

__contains__, keys, items, values, get, __eq__, __ne__

MutableMapping

Mapping

__getitem__, __setitem__, __delitem__, __iter__, __len__

Mapping から継承したメソッドと、 pop, popitem, clear, update, setdefault

MappingView

Sized

__len__

ItemsView

MappingView, Set

__contains__, __iter__

KeysView

MappingView, Set

__contains__, __iter__

ValuesView

MappingView, Collection

__contains__, __iter__

Awaitable [1]

__await__

Coroutine [1]

Awaitable

send, throw

close

AsyncIterable [1]

__aiter__

AsyncIterator [1]

AsyncIterable

__anext__

__aiter__

AsyncGenerator [1]

AsyncIterator

asend, athrow

aclose, __aiter__, __anext__

Buffer [1]

__buffer__

脚注

[1] (1,2,3,4,5,6,7,8,9,10,11,12,13,14,15)

These ABCs override __subclasshook__() to support testing an interface by verifying the required methods are present and have not been set to None. This only works for simple interfaces. More complex interfaces require registration or direct subclassing.

[2]

Checking isinstance(obj, Iterable) detects classes that are registered as Iterable or that have an __iter__() method, but it does not detect classes that iterate with the __getitem__() method. The only reliable way to determine whether an object is iterable is to call iter(obj).

コレクションの抽象基底クラス -- 詳細な説明

class collections.abc.Container

ABC for classes that provide the __contains__() method.

class collections.abc.Hashable

ABC for classes that provide the __hash__() method.

class collections.abc.Sized

ABC for classes that provide the __len__() method.

class collections.abc.Callable

ABC for classes that provide the __call__() method.

class collections.abc.Iterable

ABC for classes that provide the __iter__() method.

Checking isinstance(obj, Iterable) detects classes that are registered as Iterable or that have an __iter__() method, but it does not detect classes that iterate with the __getitem__() method. The only reliable way to determine whether an object is iterable is to call iter(obj).

class collections.abc.Collection

サイズ付きのイテラブルなコンテナクラスの ABC です。

Added in version 3.6.

class collections.abc.Iterator

__iter__() メソッドと __next__() メソッドを提供するクラスの ABC です。 iterator の定義も参照してください。

class collections.abc.Reversible

ABC for iterable classes that also provide the __reversed__() method.

Added in version 3.6.

class collections.abc.Generator

ABC for generator classes that implement the protocol defined in PEP 342 [https://peps.python.org/pep-0342/] that extends iterators with the send(), throw() and close() methods.

Added in version 3.5.

class collections.abc.Sequence

class collections.abc.MutableSequence

class collections.abc.ByteString

読み出し専用の シーケンス およびミュータブルな シーケンス の ABC です。

Implementation note: Some of the mixin methods, such as __iter__(), __reversed__() and index(), make repeated calls to the underlying __getitem__() method. Consequently, if __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.

バージョン 3.5 で変更: index() メソッドは stop と start 引数をサポートしました。

バージョン 3.12 で非推奨、バージョン 3.14 で削除予定: The ByteString ABC has been deprecated. For use in typing, prefer a union, like bytes | bytearray, or collections.abc.Buffer. For use as an ABC, prefer Sequence or collections.abc.Buffer.

class collections.abc.Set

class collections.abc.MutableSet

ABCs for read-only and mutable sets.

class collections.abc.Mapping

class collections.abc.MutableMapping

読み出し専用の マッピング およびミュータブルな マッピング の ABC です。

class collections.abc.MappingView

class collections.abc.ItemsView

class collections.abc.KeysView

class collections.abc.ValuesView

マッピング、要素、キー、値の ビュー の ABC です。

class collections.abc.Awaitable

ABC for awaitable objects, which can be used in await expressions. Custom implementations must provide the __await__() method.

Coroutine ABC の Coroutine オブジェクトとインスタンスは、すべてこの ABC のインスタンスです。

注釈

In CPython, generator-based coroutines (generators decorated with @types.coroutine) are awaitables, even though they do not have an __await__() method. Using isinstance(gencoro, Awaitable) for them will return False. Use inspect.isawaitable() to detect them.

Added in version 3.5.

class collections.abc.Coroutine

ABC for coroutine compatible classes. These implement the following methods, defined in コルーチンオブジェクト: send(), throw(), and close(). Custom implementations must also implement __await__(). All Coroutine instances are also instances of Awaitable.

注釈

In CPython, generator-based coroutines (generators decorated with @types.coroutine) are awaitables, even though they do not have an __await__() method. Using isinstance(gencoro, Coroutine) for them will return False. Use inspect.isawaitable() to detect them.

Added in version 3.5.

class collections.abc.AsyncIterable

ABC for classes that provide an __aiter__ method. See also the definition of asynchronous iterable.

Added in version 3.5.

class collections.abc.AsyncIterator

__aiter__ および __anext__ メソッドを提供するクラスの ABC です。asynchronous iterator の定義も参照してください。

Added in version 3.5.

class collections.abc.AsyncGenerator

ABC for asynchronous generator classes that implement the protocol defined in PEP 525 [https://peps.python.org/pep-0525/] and PEP 492 [https://peps.python.org/pep-0492/].

Added in version 3.6.

class collections.abc.Buffer

ABC for classes that provide the __buffer__() method, implementing the buffer protocol. See PEP 688 [https://peps.python.org/pep-0688/].

Added in version 3.12.

例とレシピ

抽象基底クラスは、クラスやインスタンスが特定の機能を提供しているかどうかを調べることを可能にします。例えば:

size = None
if isinstance(myvar, collections.abc.Sized):
    size = len(myvar)

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 Set API, it is only necessary to supply the three underlying abstract methods: __contains__(), __iter__(), and __len__(). The ABC supplies the remaining methods such as __and__() and isdisjoint():

class ListBasedSet(collections.abc.Set):
    ''' Alternate set implementation favoring space over speed
        and not requiring the set elements to be hashable. '''
    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

Set と MutableSet を mixin 型として利用するときの注意点:

Since some set operations create new sets, the default mixin methods need a way to create new instances from an iterable. The class constructor is assumed to have a signature in the form ClassName(iterable). That assumption is factored-out to an internal classmethod called _from_iterable() which calls cls(iterable) to produce a new set. If the Set mixin is being used in a class with a different constructor signature, you will need to override _from_iterable() with a classmethod or regular method that can construct new instances from an iterable argument.

To override the comparisons (presumably for speed, as the semantics are fixed), redefine __le__() and __ge__(), then the other operations will automatically follow suit.

The Set mixin provides a _hash() method to compute a hash value for the set; however, __hash__() is not defined because not all sets are hashable or immutable. To add set hashability using mixins, inherit from both Set() and Hashable(), then define __hash__ = Set._hash.

参考

MutableSet を使った例として OrderedSet recipe [https://code.activestate.com/recipes/576694/]。

ABCs についての詳細は、 abc モジュールと PEP 3119 [https://peps.python.org/pep-3119/] を参照してください。

heapq --- Heap queue algorithm

ソースコード: Lib/heapq.py [https://github.com/python/cpython/tree/3.12/Lib/heapq.py]

このモジュールではヒープキューアルゴリズムの一実装を提供しています。優先度キューアルゴリズムとしても知られています。

Heaps are binary trees for which every parent node has a value less than or equal to any of its children. We refer to this condition as the heap invariant.

This implementation uses arrays for which heap[k] <= heap[2*k+1] and heap[k] <= heap[2*k+2] for all k, counting elements from zero. For the sake of comparison, non-existing elements are considered to be infinite. The interesting property of a heap is that its smallest element is always the root, heap[0].

以下の API は教科書におけるヒープアルゴリズムとは 2 つの側面で異なっています: (a) ゼロベースのインデクス化を行っています。これにより、ノードに対するインデクスとその子ノードのインデクスの関係がやや明瞭でなくなりますが、Python はゼロベースのインデクス化を使っているのでよりしっくりきます。(b) われわれの pop メソッドは最大の要素ではなく最小の要素 (教科書では "min heap:最小ヒープ" と呼ばれています; 教科書では並べ替えをインプレースで行うのに適した "max heap:最大ヒープ" が一般的です)。

これらの 2 点によって、ユーザに戸惑いを与えることなく、ヒープを通常の Python リストとして見ることができます: heap[0] が最小の要素となり、heap.sort() はヒープ不変式を保ちます!

ヒープを作成するには、 [] に初期化されたリストを使うか、 heapify() を用いて要素の入ったリストを変換します。

次の関数が用意されています:

heapq.heappush(heap, item)

item を heap に push します。ヒープ不変式を保ちます。

heapq.heappop(heap)

pop を行い、 heap から最小の要素を返します。ヒープ不変式は保たれます。ヒープが空の場合、 IndexError が送出されます。pop せずに最小の要素にアクセスするには、 heap[0] を使ってください。

heapq.heappushpop(heap, item)

item を heap に push した後、pop を行って heap から最初の要素を返します。この一続きの動作を heappush() に引き続いて heappop() を別々に呼び出すよりも効率的に実行します。

heapq.heapify(x)

リスト x をインプレース処理し、線形時間でヒープに変換します。

heapq.heapreplace(heap, item)

heap から最小の要素を pop して返し、新たに item を push します。ヒープのサイズは変更されません。ヒープが空の場合、 IndexError が送出されます。

この一息の演算は heappop() に次いで heappush() を送出するよりも効率的で、固定サイズのヒープを用いている場合にはより適しています。 pop/push の組み合わせは必ずヒープから要素を一つ返し、それを item と置き換えます。

返される値は加えられた item よりも大きくなるかもしれません。それを望まないなら、代わりに heappushpop() を使うことを考えてください。この push/pop の組み合わせは二つの値の小さい方を返し、大きい方の値をヒープに残します。

このモジュールではさらに3つのヒープに基く汎用関数を提供します。

heapq.merge(*iterables, key=None, reverse=False)

複数のソートされた入力をマージ(merge)して一つのソートされた出力にします (たとえば、複数のログファイルの時刻の入ったエントリーをマージします)。ソートされた値にわたる iterator を返します。

sorted(itertools.chain(*iterables)) と似ていますが、イテレータを返し、一度にはデータをメモリに読み込まず、それぞれの入力ストリームが予め(最小から最大へ)ソートされていることを仮定します。

2 つのオプション引数があり、これらはキーワード引数として指定されなければなりません。

key は 1 つの引数からなる key function を指定します。この関数は、入力の各要素から比較のキーを取り出すのに使われます。デフォルト値は None です (要素を直接比較します)。

reverse は真偽値です。 True を設定した場合、挿入要素は逆向きに比較されたかのように結合されます。 sorted(itertools.chain(*iterables), reverse=True) でこれに似た挙動を実現するには、全てのイテラブルは降順で並んでいなければなりません。

バージョン 3.5 で変更: オプションの key 引数および reverse 引数を追加.

heapq.nlargest(n, iterable, key=None)

iterable で定義されるデータセットのうち、最大値から降順に n 個の値のリストを返します。(あたえられた場合) key は、引数を一つとる、iterable のそれぞれの要素から比較キーを生成する関数を指定します(例 key=str.lower)。以下のコードと同等です: sorted(iterable, key=key, reverse=True)[:n]

heapq.nsmallest(n, iterable, key=None)

iterable で定義されるデータセットのうち、最小値から昇順に n 個の値のリストを返します。(あたえられた場合) key は、引数を一つとる、iterable のそれぞれの要素から比較キーを生成する関数を指定します(例 key=str.lower)。以下のコードと同等です: sorted(iterable, key=key)[:n]

後ろ二つの関数は n の値が小さな場合に最適な動作をします。大きな値の時には sorted() 関数の方が効率的です。さらに、 n==1 の時には min() および max() 関数の方が効率的です。この関数を繰り返し使うことが必要なら、iterable を実際のヒープに変えることを考えてください。

基本的な例

すべての値をヒープに push してから最小値を 1 つずつ pop することで、ヒープソート [https://ja.wikipedia.org/wiki/%E3%83%92%E3%83%BC%E3%83%97%E3%82%BD%E3%83%BC%E3%83%88] を実装できます:

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

これは sorted(iterable) に似ていますが、 sorted() とは異なり、この実装はステーブルソートではありません。

ヒープの要素はタプルに出来ます。これは、追跡される主レコードとは別に (タスクの優先度のような) 比較値を指定するときに便利です:

>>> 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')

優先度キュー実装の注釈

優先度つきキュー [https://ja.wikipedia.org/wiki/%E5%84%AA%E5%85%88%E5%BA%A6%E3%81%A4%E3%81%8D%E3%82%AD%E3%83%A5%E3%83%BC] は、ヒープの一般的な使い方で、実装にはいくつか困難な点があります:

ソート安定性: 優先度が等しい二つのタスクが、もともと追加された順序で返されるためにはどうしたらいいでしょうか？

(priority, task) ペアに対するタプルの比較は、priority が同じで task がデフォルトの比較順を持たないときに破綻します。

あるタスクの優先度が変化したら、どうやってそれをヒープの新しい位置に移動させるのでしょうか？

未解決のタスクが削除される必要があるとき、どのようにそれをキューから探して削除するのでしょうか？

最初の二つの困難の解決策は、項目を優先度、項目番号、そしてタスクを含む 3 要素のリストとして保存することです。この項目番号は、同じ優先度の二つのタスクが、追加された順序で返されるようにするための同点決勝戦として働きます。そして二つの項目番号が等しくなることはありませんので、タプルの比較が二つのタスクを直接比べようとすることはありえません。

比較できないタスク問題のもう一つの解決法は、タスクアイテムを無視して優先順序フィールドだけで比較するラッパークラスです:

from dataclasses import dataclass, field
from typing import Any

@dataclass(order=True)
class PrioritizedItem:
    priority: int
    item: Any=field(compare=False)

残りの困難は主に、未解決のタスクを探して、その優先度を変更したり、完全に削除することです。タスクを探すことは、キュー内の項目を指し示す辞書によってなされます。

項目を削除したり、優先度を変更することは、ヒープ構造の不変関係を壊すことになるので、もっと難しいです。ですから、可能な解決策は、その項目が無効であるものとしてマークし、必要なら変更された優先度の項目を加えることです:

pq = []                         # list of entries arranged in a heap
entry_finder = {}               # mapping of tasks to entries
REMOVED = '<removed-task>'      # placeholder for a removed task
counter = itertools.count()     # unique sequence count

def add_task(task, priority=0):
    'Add a new task or update the priority of an existing task'
    if task in entry_finder:
        remove_task(task)
    count = next(counter)
    entry = [priority, count, task]
    entry_finder[task] = entry
    heappush(pq, entry)

def remove_task(task):
    'Mark an existing task as REMOVED.  Raise KeyError if not found.'
    entry = entry_finder.pop(task)
    entry[-1] = REMOVED

def pop_task():
    'Remove and return the lowest priority task. Raise KeyError if empty.'
    while pq:
        priority, count, task = heappop(pq)
        if task is not REMOVED:
            del entry_finder[task]
            return task
    raise KeyError('pop from an empty priority queue')

理論

ヒープとは、全ての k について、要素を 0 から数えたときに、a[k] <= a[2*k+1] かつ a[k] <= a[2*k+2] となる配列です。比較のために、存在しない要素を無限大と考えます。ヒープの興味深い属性は a[0] が常に最小の要素になることです。

上記の奇妙な不変式は、勝ち抜き戦判定の際に効率的なメモリ表現を行うためのものです。以下の番号は a[k] ではなく k とします:

                               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

上の木構造では、各セル k は 2*k+1 および 2*k+2 を最大値としています。スポーツに見られるような通常の 2 つ組勝ち抜き戦では、各セルはその下にある二つのセルに対する勝者となっていて、個々のセルの勝者を追跡していくことにより、そのセルに対する全ての相手を見ることができます。しかしながら、このような勝ち抜き戦を使う計算機アプリケーションの多くでは、勝歴を追跡する必要はりません。メモリ効率をより高めるために、勝者が上位に進級した際、下のレベルから持ってきて置き換えることにすると、あるセルとその下位にある二つのセルは異なる三つの要素を含み、かつ上位のセルは二つの下位のセルに対して "勝者と" なります。

If this heap invariant is protected at all time, index 0 is clearly the overall winner. The simplest algorithmic way to remove it and find the "next" winner is to move some loser (let's say cell 30 in the diagram above) into the 0 position, and then percolate this new 0 down the tree, exchanging values, until the invariant is re-established. This is clearly logarithmic on the total number of items in the tree. By iterating over all items, you get an O(n log n) sort.

このソートの良い点は、新たに挿入する要素が、最後に取り出された 0 番目の要素よりも "良い値" でない限り、ソートを行っている最中に新たな要素を効率的に追加できるというところです。この性質は、シミュレーション的な状況で、ツリーで全ての入力イベントを保持し、"勝者" の状況を最小のスケジュール時刻にするような場合に特に便利です。あるイベントが他のイベント群の実行をスケジュールする際、それらは未来にスケジュールされることになるので、それらのイベント群を容易にヒープに積むことができます。すなわち、ヒープはスケジューラを実装する上で良いデータ構造であるといえます (私はこれを MIDI シーケンサで使っています :-)。

これまで、スケジューラを実装するための様々なデータ構造が広範に研究されてきました。ヒープは、十分高速で、速度はおおむね一定であり、最悪の場合でも平均的な速度とさほど変わらないため、良いデータ構造といえます。しかし、最悪の場合にひどい速度になるとしても、全体的にはより効率の高い他のデータ構造表現も存在します。

ヒープはまた、巨大なディスクのソートでも非常に有用です。おそらくご存知のように、巨大なソートを行うと、複数の "ラン (run)" (予めソートされた配列で、そのサイズは通常 CPU メモリの量に関係しています) が生成され、続いて統合処理 (merging) がこれらのランを判定します。この統合処理はしばしば非常に巧妙に組織されています [1]。重要なのは、最初のソートが可能な限り長いランを生成することです。勝ち抜き戦はこれを達成するための良い方法です。もし利用可能な全てのメモリを使って勝ち抜き戦を行い、要素を置換および濾過処理して現在のランに収めれば、ランダムな入力に対してメモリの二倍のサイズのランを生成することになり、大体順序づけがなされている入力に対してはもっと高い効率になります。

さらに、ディスク上の 0 番目の要素を出力して、現在の勝ち抜き戦に (最後に出力した値に "勝って" しまうために) 収められない入力を得たなら、ヒープには収まらないため、ヒープのサイズは減少します。解放されたメモリは二つ目のヒープを段階的に構築するために巧妙に再利用することができ、この二つ目のヒープは最初のヒープが崩壊していくのと同じ速度で成長します。最初のヒープが完全に消滅したら、ヒープを切り替えて新たなランを開始します。なんと巧妙で効率的なのでしょう！

一言で言うと、ヒープは知って得するメモリ構造です。私はいくつかのアプリケーションでヒープを使っていて、'ヒープ' モジュールを常備するのはいい事だと考えています。:-)

脚注

[1]

現在使われているディスクバランス化アルゴリズムは、最近ではもはや巧妙というよりも目障りになっています。これは、ディスクのシーク機能が向上した結果です。巨大な容量を持つテープドライブなど、シーク不能なデバイスでは、事情は全く異なります。テープの 1 つ 1 つの動きが可能な限り効率的に行われるように非常に巧妙な処理を (相当前もって) 確保しなければなりません (統合処理の "進行" に最も多く使用させます)。テープによっては逆方向に読むことさえでき、巻き戻しに時間を取られるのを避けるために使うこともできます。正直、本当に良いテープソートは見ていて素晴らしく驚異的なものです！ソートというのは常に偉大な芸術なのです！:-)

bisect --- Array bisection algorithm

ソースコード: Lib/bisect.py [https://github.com/python/cpython/tree/3.12/Lib/bisect.py]

This module provides support for maintaining a list in sorted order without having to sort the list after each insertion. For long lists of items with expensive comparison operations, this can be an improvement over linear searches or frequent resorting.

The module is called bisect because it uses a basic bisection algorithm to do its work. Unlike other bisection tools that search for a specific value, the functions in this module are designed to locate an insertion point. Accordingly, the functions never call an __eq__() method to determine whether a value has been found. Instead, the functions only call the __lt__() method and will return an insertion point between values in an array.

次の関数が用意されています:

bisect.bisect_left(a, x, lo=0, hi=len(a), *, key=None)

ソートされた順序を保ったまま x を a に挿入できる点を探し当てます。リストの中から検索する部分集合を指定するには、パラメータの lo と hi を使います。デフォルトでは、リスト全体が使われます。x がすでに a に含まれている場合、挿入点は既存のどのエントリーよりも前(左)になります。戻り値は、list.insert() の第一引数として使うのに適しています。a はすでにソートされているものとします。

The returned insertion point ip partitions the array a into two slices such that all(elem < x for elem in a[lo : ip]) is true for the left slice and all(elem >= x for elem in a[ip : hi]) is true for the right slice.

key specifies a key function of one argument that is used to extract a comparison key from each element in the array. To support searching complex records, the key function is not applied to the x value.

If key is None, the elements are compared directly and no key function is called.

バージョン 3.10 で変更: key パラメータが追加されました。

bisect.bisect_right(a, x, lo=0, hi=len(a), *, key=None)

bisect.bisect(a, x, lo=0, hi=len(a), *, key=None)

Similar to bisect_left(), but returns an insertion point which comes after (to the right of) any existing entries of x in a.

The returned insertion point ip partitions the array a into two slices such that all(elem <= x for elem in a[lo : ip]) is true for the left slice and all(elem > x for elem in a[ip : hi]) is true for the right slice.

バージョン 3.10 で変更: key パラメータが追加されました。

bisect.insort_left(a, x, lo=0, hi=len(a), *, key=None)

x を a にソート順で挿入します。

This function first runs bisect_left() to locate an insertion point. Next, it runs the insert() method on a to insert x at the appropriate position to maintain sort order.

To support inserting records in a table, the key function (if any) is applied to x for the search step but not for the insertion step.

Keep in mind that the O(log n) search is dominated by the slow O(n) insertion step.

バージョン 3.10 で変更: key パラメータが追加されました。

bisect.insort_right(a, x, lo=0, hi=len(a), *, key=None)

bisect.insort(a, x, lo=0, hi=len(a), *, key=None)

Similar to insort_left(), but inserting x in a after any existing entries of x.

This function first runs bisect_right() to locate an insertion point. Next, it runs the insert() method on a to insert x at the appropriate position to maintain sort order.

To support inserting records in a table, the key function (if any) is applied to x for the search step but not for the insertion step.

Keep in mind that the O(log n) search is dominated by the slow O(n) insertion step.

バージョン 3.10 で変更: key パラメータが追加されました。

パフォーマンスに関するメモ

When writing time sensitive code using bisect() and insort(), keep these thoughts in mind:

Bisection is effective for searching ranges of values. For locating specific values, dictionaries are more performant.

The insort() functions are O(n) because the logarithmic search step is dominated by the linear time insertion step.

The search functions are stateless and discard key function results after they are used. Consequently, if the search functions are used in a loop, the key function may be called again and again on the same array elements. If the key function isn't fast, consider wrapping it with functools.cache() to avoid duplicate computations. Alternatively, consider searching an array of precomputed keys to locate the insertion point (as shown in the examples section below).

参考

Sorted Collections [https://grantjenks.com/docs/sortedcollections/] is a high performance module that uses bisect to managed sorted collections of data.

bisect を利用して、直接の探索ができ、キー関数をサポートする、完全な機能を持つコレクションクラスを組み立てる SortedCollection recipe [https://code.activestate.com/recipes/577197-sortedcollection/]。キーは、探索中に不必要な呼び出しをさせないために、予め計算しておきます。

ソート済みリストの探索

The above bisect functions are useful for finding insertion points but can be tricky or awkward to use for common searching tasks. The following five functions show how to transform them into the standard lookups for sorted lists:

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

使用例

The bisect() function can be useful for numeric table lookups. This example uses bisect() to look up a letter grade for an exam score (say) based on a set of ordered numeric breakpoints: 90 and up is an 'A', 80 to 89 is a 'B', and so on:

>>> 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']

The bisect() and insort() functions also work with lists of tuples. The key argument can serve to extract the field used for ordering records in a table:

>>> from collections import namedtuple
>>> from operator import attrgetter
>>> from bisect import bisect, insort
>>> from pprint import pprint

>>> Movie = namedtuple('Movie', ('name', 'released', 'director'))

>>> movies = [
...     Movie('Jaws', 1975, 'Spielberg'),
...     Movie('Titanic', 1997, 'Cameron'),
...     Movie('The Birds', 1963, 'Hitchcock'),
...     Movie('Aliens', 1986, 'Cameron')
... ]

>>> # Find the first movie released after 1960
>>> by_year = attrgetter('released')
>>> movies.sort(key=by_year)
>>> movies[bisect(movies, 1960, key=by_year)]
Movie(name='The Birds', released=1963, director='Hitchcock')

>>> # Insert a movie while maintaining sort order
>>> romance = Movie('Love Story', 1970, 'Hiller')
>>> insort(movies, romance, key=by_year)
>>> pprint(movies)
[Movie(name='The Birds', released=1963, director='Hitchcock'),
 Movie(name='Love Story', released=1970, director='Hiller'),
 Movie(name='Jaws', released=1975, director='Spielberg'),
 Movie(name='Aliens', released=1986, director='Cameron'),
 Movie(name='Titanic', released=1997, director='Cameron')]

If the key function is expensive, it is possible to avoid repeated function calls by searching a list of precomputed keys to find the index of a record:

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

array --- Efficient arrays of numeric values

このモジュールでは、基本的な値 (文字、整数、浮動小数点数) のアレイ (array、配列) をコンパクトに表現できるオブジェクト型を定義しています。アレイはシーケンス (sequence) 型であり、中に入れるオブジェクトの型に制限があることを除けば、リストとまったく同じように振る舞います。オブジェクト生成時に一文字の 型コード を用いて型を指定します。次の型コードが定義されています:

型コード

C の型

Python の型

最小サイズ (バイト単位)

注釈

'b'

signed char

int

1

'B'

unsigned char

int

1

'u'

wchar_t

Unicode文字(unicode型)

2

(1)

'h'

signed short

int

2

'H'

unsigned short

int

2

'i'

signed int

int

2

'I'

unsigned int

int

2

'l'

signed long

int

4

'L'

unsigned long

int

4

'q'

signed long long

int

8

'Q'

unsigned long long

int

8

'f'

浮動小数点数

浮動小数点数

4

'd'

double

浮動小数点数

8

注釈:

It can be 16 bits or 32 bits depending on the platform.

バージョン 3.9 で変更: array('u') now uses wchar_t as C type instead of deprecated Py_UNICODE. This change doesn't affect its behavior because Py_UNICODE is alias of wchar_t since Python 3.3.

バージョン 3.3 で非推奨、バージョン 4.0 で削除予定.

値の実際の表現はマシンアーキテクチャ (厳密に言うとCの実装) によって決まります。値の実際のサイズは array.itemsize 属性から得られます。

このモジュールは以下の項目を定義しています:

array.typecodes

すべての利用可能なタイプコードを含む文字列

このモジュールでは次の型を定義しています:

class array.array(typecode[, initializer])

A new array whose items are restricted by typecode, and initialized from the optional initializer value, which must be a bytes or bytearray object, a Unicode string, or iterable over elements of the appropriate type.

If given a bytes or bytearray object, the initializer is passed to the new array's frombytes() method; if given a Unicode string, the initializer is passed to the fromunicode() method; otherwise, the initializer's iterator is passed to the extend() method to add initial items to the array.

アレイオブジェクトでは、インデクス指定、スライス、連結および反復といった、 通常のシーケンスの演算をサポートしています。スライス代入を使うときは、 代入値は同じ型コードのアレイオブジェクトでなければなりません。 それ以外のオブジェクトを指定すると TypeError を送出します。 アレイオブジェクトはバッファインターフェースを実装しており、 bytes-like objects をサポートしている場所ならどこでも利用できます。

引数 typecode, initializer 付きで 監査イベント array.__new__ を送出します。

typecode

アレイを作るときに使う型コード文字です。

itemsize

アレイの要素 1 つの内部表現に使われるバイト長です。

append(x)

値 x の新たな要素をアレイの末尾に追加します。

buffer_info()

アレイの内容を記憶するために使っているバッファの、現在のメモリアドレスと要素数の入ったタプル (address, length) を返します。バイト単位で表したメモリバッファの大きさは array.buffer_info()[1] * array.itemsize で計算できます。例えば ioctl() 操作のような、メモリアドレスを必要とする低レベルな (そして、本質的に危険な) I/Oインターフェースを使って作業する場合に、ときどき便利です。アレイ自体が存在し、長さを変えるような演算を適用しない限り、有効な値を返します。

注釈

C やC++ で書いたコードからアレイオブジェクトを使う場合 (buffer_info() の情報を使う意味のある唯一の方法です) は、アレイオブジェクトでサポートしているバッファインターフェースを使う方がより理にかなっています。このメソッドは後方互換性のために保守されており、新しいコードでの使用は避けるべきです。バッファインターフェースの説明は バッファプロトコル (buffer Protocol) にあります。

byteswap()

アレイのすべての要素に対して「バイトスワップ」 (リトルエンディアンとビッグエンディアンの変換) を行います。このメソッドは大きさが 1、2、4 および 8 バイトの値のみをサポートしています。他の種類の値に使うと RuntimeError を送出します。異なるバイトオーダを使うマシンで書かれたファイルからデータを読み込むときに役に立ちます。

count(x)

シーケンス中の x の出現回数を返します。

extend(iterable)

iterable から要素を取り出し、アレイの末尾に要素を追加します。 iterable が別のアレイ型である場合、二つのアレイは 全く 同じ型コードでなければなりません。それ以外の場合には TypeError を送出します。 iterable がアレイでない場合、アレイに値を追加できるような正しい型の要素からなるイテレーション可能オブジェクトでなければなりません。

frombytes(buffer)

Appends items from the bytes-like object, interpreting its content as an array of machine values (as if it had been read from a file using the fromfile() method).

Added in version 3.2: 明確化のため fromstring() の名前が frombytes() に変更されました。

fromfile(f, n)

ファイルオブジェクト f から (マシンのデータ形式そのままで) n 個の要素を読み出し、アレイの末尾に要素を追加します。 n 個未満の要素しか読めなかった場合は EOFError を送出しますが、それまでに読み出せた値はアレイに追加されます。

fromlist(list)

リストから要素を追加します。型に関するエラーが発生した場合にアレイが変更されないことを除き、 for x in list: a.append(x) と同じです。

fromunicode(s)

Extends this array with data from the given Unicode string. The array must have type code 'u'; otherwise a ValueError is raised. Use array.frombytes(unicodestring.encode(enc)) to append Unicode data to an array of some other type.

index(x[, start[, stop]])

Return the smallest i such that i is the index of the first occurrence of x in the array. The optional arguments start and stop can be specified to search for x within a subsection of the array. Raise ValueError if x is not found.

バージョン 3.10 で変更: Added optional start and stop parameters.

insert(i, x)

アレイ中の位置 i の前に値 x をもつ新しい要素を挿入します。 i の値が負の場合、アレイの末尾からの相対位置として扱います。

pop([i])

アレイからインデクスが i の要素を取り除いて返します。オプションの引数はデフォルトで -1 になっていて、最後の要素を取り除いて返すようになっています。

remove(x)

アレイ中の x のうち、最初に現れたものを取り除きます。

reverse()

アレイの要素の順番を逆にします。

tobytes()

array をマシンの値の array に変換して、 bytes の形で返します (tofile() メソッドを使ってファイルに書かれるバイト列と同じです)。

Added in version 3.2: tostring() is renamed to tobytes() for clarity.

tofile(f)

すべての要素を (マシンの値の形式で) file object f に書き込みます。

tolist()

アレイを同じ要素を持つ普通のリストに変換します。

tounicode()

Convert the array to a Unicode string. The array must have a type 'u'; otherwise a ValueError is raised. Use array.tobytes().decode(enc) to obtain a Unicode string from an array of some other type.

The string representation of array objects has the form array(typecode, initializer). The initializer is omitted if the array is empty, otherwise it is a Unicode string if the typecode is 'u', otherwise it is a list of numbers. The string representation is guaranteed to be able to be converted back to an array with the same type and value using eval(), so long as the array class has been imported using from array import array. Variables inf and nan must also be defined if it contains corresponding floating point values. Examples:

array('l')
array('u', 'hello \u2641')
array('l', [1, 2, 3, 4, 5])
array('d', [1.0, 2.0, 3.14, -inf, nan])

参考

struct モジュール

異なる種類のバイナリデータのパックおよびアンパック。

Module xdrlib

Packing and unpacking of External Data Representation (XDR) data as used in some remote procedure call systems.

NumPy [https://numpy.org/]

The NumPy package defines another array type.

weakref --- 弱参照

ソースコード: Lib/weakref.py [https://github.com/python/cpython/tree/3.12/Lib/weakref.py]

weakref モジュールは、Pythonプログラマがオブジェクトへの弱参照 (weak refarence)を作成できるようにします。

以下では、用語リファレント(referent) は弱参照が参照するオブジェクトを意味します。

オブジェクトへの弱参照があることは、そのオブジェクトを生かしておくのには不十分です。リファレントへの参照が弱参照しか残っていない場合、 garbage collection はリファレントを自由に破棄し、メモリを別のものに再利用することができます。しかし、オブジェクトへの強参照がなくても、オブジェクトが実際に破棄されるまでは、弱参照はオブジェクトを返す場合があります。

弱参照の主な用途は、巨大なオブジェクトを保持するキャッシュやマッピングを実装することです。ここで、キャッシュやマッピングに保持されているからという理由だけで、巨大なオブジェクトが生き続けることは望ましくありません。

例えば、巨大なバイナリ画像のオブジェクトがたくさんあり、それぞれに名前を関連付けたいとします。 Python の辞書型を使って名前を画像に対応付けたり画像を名前に対応付けたりすると、画像オブジェクトは辞書内のキーや値に使われているため存続しつづけることになります。 weakref モジュールが提供している WeakKeyDictionary や WeakValueDictionary クラスはその代用で、対応付けを構築するのに弱参照を使い、キャッシュやマッピングに存在するという理由だけでオブジェクトを存続させないようにします。例えば、もしある画像オブジェクトが WeakValueDictionary の値になっていた場合、最後に残った画像オブジェクトへの参照を弱参照マッピングが保持していれば、ガーベジコレクションはこのオブジェクトを再利用でき、画像オブジェクトに対する弱参照内の対応付けは削除されます。

WeakKeyDictionary と WeakValueDictionary はその実装に弱参照を使用しており、キーや値がガーベジコレクションによって回収されたことを弱参照辞書に通知するコールバック関数を設定しています。 WeakSet は set インターフェースを実装していますが、 WeakKeyDictionary のように要素への弱参照を持ちます。

finalize は、オブジェクトのガベージコレクションの実行時にクリーンアップ関数が呼び出されるように登録する、単純な方法を提供します。これは、未加工の弱参照上にコールバック関数を設定するよりも簡単です。なぜなら、オブジェクトのコレクションが完了するまでファイナライザが生き続けることを、モジュールが自動的に保証するからです。

ほとんどのプログラムでは弱参照コンテナまたは finalize のどれかを使えば必要なものは揃うはずです。通常は直接自前の弱参照を作成する必要はありません。低レベルな機構は、より進んだ使い方をするために weakref モジュールとして公開されています。

全てのオブジェクトが弱参照で参照できるわけではありません。弱参照をサポートするオブジェクトは、クラスインスタンス、(C ではなく) Python で書かれた関数、インスタンスメソッド、set オブジェクト、frozenset オブジェクト、 file オブジェクト 、 generators 型のオブジェクト、socket オブジェクト、array オジェクト、deque オブジェクト、正規表現パターンオブジェクト、code オブジェクトです。

バージョン 3.2 で変更: thread.lock, threading.Lock, code オブジェクトのサポートが追加されました。

list や dict など、いくつかの組み込み型は弱参照を直接サポートしませんが、以下のようにサブクラス化を行えばサポートを追加できます:

class Dict(dict):
    pass

obj = Dict(red=1, green=2, blue=3)   # this object is weak referenceable

CPython 実装の詳細: tuple や int など、他の組み込み型はサブクラス化しても弱参照をサポートしません。

拡張型は、簡単に弱参照をサポートできます。詳細については、 弱参照(Weak Reference)のサポート を参照してください。

When __slots__ are defined for a given type, weak reference support is disabled unless a '__weakref__' string is also present in the sequence of strings in the __slots__ declaration. See __slots__ documentation for details.

class weakref.ref(object[, callback])

object への弱参照を返します。リファレントがまだ生きているならば、元のオブジェクトは参照オブジェクトの呼び出しで取り出せす。リファレントがもはや生きていないならば、参照オブジェクトを呼び出したときに None を返します。 callback に None 以外の値を与えた場合、オブジェクトをまさに後始末処理しようとするときに呼び出します。このとき弱参照オブジェクトは callback の唯一のパラメタとして渡されます。リファレントはもはや利用できません。

同じオブジェクトに対してたくさんの弱参照を作れます。それぞれの弱参照に対して登録されたコールバックは、もっとも新しく登録されたコールバックからもっとも古いものへと呼び出されます。

Exceptions raised by the callback will be noted on the standard error output, but cannot be propagated; they are handled in exactly the same way as exceptions raised from an object's __del__() method.

object が ハッシュ可能 ならば、弱参照はハッシュ可能です。それらは object が削除された後でもそれらのハッシュ値を保持します。 object が削除されてから初めて hash() が呼び出された場合に、その呼び出しは TypeError を発生させます。

弱参照は等価性のテストをサポートしていますが、順序をサポートしていません。参照がまだ生きているならば、 callback に関係なく二つの参照はそれらのリファレントと同じ等価関係を持ちます。リファレントのどちらか一方が削除された場合、参照オブジェクトが同一である場合に限り、その参照は等価です。

これはサブクラス化可能な型というよりファクトリ関数です。

__callback__

この読み出し専用の属性は、現在弱参照に関連付けられているコールバックを返します。コールバックが存在しないか、弱参照のリファレントが生きていない場合、この属性の値は None になります。

バージョン 3.4 で変更: __callback__ 属性が追加されました。

weakref.proxy(object[, callback])

弱参照を使う object へのプロキシを返します。弱参照オブジェクトを明示的な参照外しをしながら利用する代わりに、多くのケースでプロキシを利用することができます。返されるオブジェクトは、 object が呼び出し可能かどうかによって、 ProxyType または CallableProxyType のどちらかの型を持ちます。プロキシオブジェクトはリファレントに関係なく ハッシュ可能 ではありません。これによって、それらの基本的な変更可能という性質による多くの問題を避けています。そして、辞書のキーとしての利用を妨げます。 callback は ref() 関数の同じ名前のパラメータと同じものです。(--- 訳注: リファレントが変更不能型であっても、プロキシはリファレントが消えるという状態の変更があるために、変更可能型です。---)

Accessing an attribute of the proxy object after the referent is garbage collected raises ReferenceError.

バージョン 3.8 で変更: Extended the operator support on proxy objects to include the matrix multiplication operators @ and @=.

weakref.getweakrefcount(object)

object を参照する弱参照とプロキシの数を返します。

weakref.getweakrefs(object)

object を参照するすべての弱参照とプロキシオブジェクトのリストを返します。

class weakref.WeakKeyDictionary([dict])

キーを弱参照するマッピングクラス。キーへの強参照がなくなったときに、辞書のエントリは捨てられます。アプリケーションの他の部分が所有するオブジェクトへ属性を追加することもなく、それらのオブジェクトに追加データを関連づけるために使うことができます。これは属性へのアクセスをオーバーライドするオブジェクトに特に便利です。

Note that when a key with equal value to an existing key (but not equal identity) is inserted into the dictionary, it replaces the value but does not replace the existing key. Due to this, when the reference to the original key is deleted, it also deletes the entry in the dictionary:

>>> 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 = {}

A workaround would be to remove the key prior to reassignment:

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

バージョン 3.9 で変更: PEP 584 [https://peps.python.org/pep-0584/] で規定されている | 演算子と |= 演算子のサポートを追加しました。

WeakKeyDictionary オブジェクトは、追加のメソッドを持ちます。このメソッドは、内部の参照を直接公開します。その参照は、利用される時に生存しているとは限りません。なので、参照を利用する前に、その参照をチェックする必要があります。これにより、必要なくなったキーの参照が残っているために、ガベージコレクタがそのキーを削除できなくなる事態を避ける事ができます。

WeakKeyDictionary.keyrefs()

キーへの弱参照を持つ iterable オブジェクトを返します。

class weakref.WeakValueDictionary([dict])

値を弱参照するマッピングクラス。値への強参照が存在しなくなったときに、辞書のエントリは捨てられます。

バージョン 3.9 で変更: PEP 584 [https://peps.python.org/pep-0584/] で規定されている | 演算子と |= 演算子のサポートを追加しました。

WeakValueDictionary objects have an additional method that has the same issues as the WeakKeyDictionary.keyrefs() method.

WeakValueDictionary.valuerefs()

値への弱参照を持つ iterable オブジェクトを返します。

class weakref.WeakSet([elements])

要素への弱参照を持つ集合型。要素への強参照が無くなったときに、その要素は削除されます。

class weakref.WeakMethod(method[, callback])

拡張された ref のサブクラスで、束縛されたメソッドへの弱参照をシミュレートします (つまり、クラスで定義され、インスタンスにあるメソッド)。束縛されたメソッドは短命なので、標準の弱参照では保持し続けられません。 WeakMethod には、オブジェクトと元々の関数が死ぬまで束縛されたメソッドを再作成する特別なコードがあります:

>>> 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()
>>>

callback is the same as the parameter of the same name to the ref() function.

Added in version 3.4.

class weakref.finalize(obj, func, /, *args, **kwargs)

obj がガベージコレクションで回収されるときに呼び出される、呼び出し可能なファイナライザオブジェクトを返します。通常の弱参照とは異なり、ファイナライザは参照しているオブジェクトが回収されるまで必ず生き残り、そのおかげでライフサイクル管理が大いに簡単になります。

ファイナライザは (直接もしくはガベージコレクションのときに) 呼び出されるまで 生きている と見なされ、呼び出された後には 死んでいます 。生きているファイナライザを呼び出すと、 func(*arg, **kwargs) を評価した結果を返します。一方、死んでいるファイナライザを呼び出すと None を返します。

Exceptions raised by finalizer callbacks during garbage collection will be shown on the standard error output, but cannot be propagated. They are handled in the same way as exceptions raised from an object's __del__() method or a weak reference's callback.

プログラムが終了するとき、生き残ったそれぞれのファイナライザは、自身の atexit 属性が偽に設定されるまで呼び出され続けます。ファイナライザは生成された順序の逆順で呼び出されます。

A finalizer will never invoke its callback during the later part of the interpreter shutdown when module globals are liable to have been replaced by None.

__call__()

If self is alive then mark it as dead and return the result of calling func(*args, **kwargs). If self is dead then return None.

detach()

If self is alive then mark it as dead and return the tuple (obj, func, args, kwargs). If self is dead then return None.

peek()

If self is alive then return the tuple (obj, func, args, kwargs). If self is dead then return None.

alive

ファイナライザが生きている場合には真、そうでない場合には偽のプロパティです。

atexit

A writable boolean property which by default is true. When the program exits, it calls all remaining live finalizers for which atexit is true. They are called in reverse order of creation.

注釈

It is important to ensure that func, args and kwargs do not own any references to obj, either directly or indirectly, since otherwise obj will never be garbage collected. In particular, func should not be a bound method of obj.

Added in version 3.4.

weakref.ReferenceType

弱参照オブジェクトのための型オブジェクト。

weakref.ProxyType

呼び出し可能でないオブジェクトのプロキシのための型オブジェクト。

weakref.CallableProxyType

呼び出し可能なオブジェクトのプロキシのための型オブジェクト。

weakref.ProxyTypes

プロキシのためのすべての型オブジェクトを含むシーケンス。これは両方のプロキシ型の名前付けに依存しないで、オブジェクトがプロキシかどうかのテストをより簡単にできます。

参考

PEP 205 [https://peps.python.org/pep-0205/] - 弱参照

この機能の提案と理論的根拠。初期の実装と他の言語における類似の機能についての情報へのリンクを含んでいます。

弱参照オブジェクト

Weak reference objects have no methods and no attributes besides ref.__callback__. A weak reference object allows the referent to be obtained, if it still exists, by calling it:

>>> import weakref
>>> class Object:
...     pass
...
>>> o = Object()
>>> r = weakref.ref(o)
>>> o2 = r()
>>> o is o2
True

リファレントがもはや存在しないならば、参照オブジェクトの呼び出しは None を返します:

>>> del o, o2
>>> print(r())
None

弱参照オブジェクトがまだ生きているかどうかのテストは、式 ref() is not None を用いて行われます。通常、参照オブジェクトを使う必要があるアプリケーションコードはこのパターンに従います:

# 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()

"生存性(liveness)"のテストを分割すると、スレッド化されたアプリケーションにおいて競合状態を作り出します。 (訳注:if r() is not None: r().do_something() では、2度目のr()がNoneを返す可能性があります) 弱参照が呼び出される前に、他のスレッドは弱参照が無効になる原因となり得ます。上で示したイディオムは、シングルスレッドのアプリケーションと同じくマルチスレッド化されたアプリケーションにおいても安全です。

サブクラス化を行えば、 ref オブジェクトの特殊なバージョンを作成できます。これは WeakValueDictionary の実装で使われており、マップ内の各エントリによるメモリのオーバヘッドを減らしています。こうした実装は、ある参照に追加情報を関連付けたい場合に便利ですし、リファレントを取り出すための呼び出し時に何らかの追加処理を行いたい場合にも使えます。

以下の例では、 ref のサブクラスを使って、あるオブジェクトに追加情報を保存し、リファレントがアクセスされたときにその値に作用をできるようにするための方法を示しています:

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

使用例

この簡単な例では、アプリケーションが以前に参照したオブジェクトを取り出すためにオブジェクトIDを利用する方法を示します。オブジェクトに生きたままであることを強制することなく、オブジェクトの IDを他のデータ構造の中で使うことができ、必要に応じてIDからオブジェクトを取り出せます。

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]

ファイナライザオブジェクト

The main benefit of using finalize is that it makes it simple to register a callback without needing to preserve the returned finalizer object. For instance

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

ファイナライザは直接呼び出すこともできます。ただし、ファイナライザはコールバックを最大でも一度しか呼び出しません。

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

You can unregister a finalizer using its detach() method. This kills the finalizer and returns the arguments passed to the constructor when it was created.

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

Unless you set the atexit attribute to False, a finalizer will be called when the program exits if it is still alive. For instance

>>> obj = Object()
>>> weakref.finalize(obj, print, "obj dead or exiting")
<finalize object at ...; for 'Object' at ...>
>>> exit()
obj dead or exiting

Comparing finalizers with __del__() methods

インスタンスが一時ディレクトリを表す、クラスを作成するとします。そのディレクトリは、次のイベントのいずれかが起きた時に、そのディレクトリの内容とともに削除されるべきです。

オブジェクトのガベージコレクションが行われた場合

the object's remove() method is called, or

プログラムが終了した場合

We might try to implement the class using a __del__() method as follows:

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()

Starting with Python 3.4, __del__() methods no longer prevent reference cycles from being garbage collected, and module globals are no longer forced to None during interpreter shutdown. So this code should work without any issues on CPython.

However, handling of __del__() methods is notoriously implementation specific, since it depends on internal details of the interpreter's garbage collector implementation.

A more robust alternative can be to define a finalizer which only references the specific functions and objects that it needs, rather than having access to the full state of the object:

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

Defined like this, our finalizer only receives a reference to the details it needs to clean up the directory appropriately. If the object never gets garbage collected the finalizer will still be called at exit.

The other advantage of weakref based finalizers is that they can be used to register finalizers for classes where the definition is controlled by a third party, such as running code when a module is unloaded:

import weakref, sys
def unloading_module():
    # implicit reference to the module globals from the function body
weakref.finalize(sys.modules[__name__], unloading_module)

注釈

If you create a finalizer object in a daemonic thread just as the program exits then there is the possibility that the finalizer does not get called at exit. However, in a daemonic thread atexit.register(), try: ... finally: ... and with: ... do not guarantee that cleanup occurs either.

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

ソースコード: Lib/types.py [https://github.com/python/cpython/tree/3.12/Lib/types.py]

このモジュールは新しい型の動的な生成を支援するユーティリティ関数を定義します。

さらに、標準の Python インタプリタによって使用されているものの、 int や str のように組み込みとして公開されていないようないくつかのオブジェクト型の名前を定義しています。

最後に、組み込みになるほど基本的でないような追加の型関連のユーティリティと関数をいくつか提供しています。

動的な型生成

types.new_class(name, bases=(), kwds=None, exec_body=None)

適切なメタクラスを使用して動的にクラスオブジェクトを生成します。

最初の3つの引数はクラス定義ヘッダーを構成する—クラス名、基底クラス (順番に)、キーワード引数 (例えば metaclass)—です。

exec_body 引数は、新規に生成されたクラスの名前空間を構築するために使用されるコールバックです。それは唯一の引数としてクラスの名前空間を受け取り、クラスの内容で名前空間を直接更新します。コールバックが渡されない場合、それは lambda ns: None を渡すことと同じ効果があります。

Added in version 3.3.

types.prepare_class(name, bases=(), kwds=None)

適切なメタクラスを計算してクラスの名前空間を生成します。

引数はクラス定義ヘッダーを構成する要素—クラス名、基底クラス (順番に)、キーワード引数 (例えば metaclass)—です。

返り値は metaclass, namespace, kwds の3要素のタプルです

metaclass は適切なメタクラスです。namespace は用意されたクラスの名前空間です。また kwds は、'metaclass' エントリが削除された、渡された kwds 引数の更新されたコピーです。kwds 引数が渡されなければ、これは空の dict になります。

Added in version 3.3.

バージョン 3.6 で変更: 返されるタプルの namespace 要素のデフォルト値が変更されました。現在では、メタクラスが __prepare__ メソッドを持っていないときは、挿入順序を保存するマッピングが使われます。

参考

メタクラス

これらの関数によってサポートされるクラス生成プロセスの完全な詳細

PEP 3115 [https://peps.python.org/pep-3115/] - Metaclasses in Python 3000

__prepare__ 名前空間フックの導入

types.resolve_bases(bases)

Resolve MRO entries dynamically as specified by PEP 560 [https://peps.python.org/pep-0560/].

This function looks for items in bases that are not instances of type, and returns a tuple where each such object that has an __mro_entries__() method is replaced with an unpacked result of calling this method. If a bases item is an instance of type, or it doesn't have an __mro_entries__() method, then it is included in the return tuple unchanged.

Added in version 3.7.

types.get_original_bases(cls, /)

Return the tuple of objects originally given as the bases of cls before the __mro_entries__() method has been called on any bases (following the mechanisms laid out in PEP 560 [https://peps.python.org/pep-0560/]). This is useful for introspecting Generics.

For classes that have an __orig_bases__ attribute, this function returns the value of cls.__orig_bases__. For classes without the __orig_bases__ attribute, cls.__bases__ is returned.

例:

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,)

Added in version 3.12.

参考

PEP 560 [https://peps.python.org/pep-0560/] - typing モジュールとジェネリック型に対する言語コアによるサポート

標準的なインタプリタ型

このモジュールは、Python インタプリタを実装するために必要な多くの型に対して名前を提供します。それは、listiterator 型のような、単に処理中に付随的に発生するいくつかの型が含まれることを意図的に避けています。

これらの名前は典型的に isinstance() や issubclass() によるチェックに使われます。

これらのタイプのいずれかをインスタンス化する場合、シグネチャは Python のバージョンによって異なる可能性があることに注意してください。

以下の型に対して標準的な名前が定義されています:

types.NoneType

None の型です。

Added in version 3.10.

types.FunctionType

types.LambdaType

ユーザ定義の関数と lambda 式によって生成された関数の型です。

引数 code を指定して 監査イベント function.__new__ を送出します。

この監査イベントは、関数オブジェクトを直接インスタンス化した場合にのみ発生し、通常のコンパイル時には発生しません。

types.GeneratorType

ジェネレータ関数によって生成された ジェネレータ イテレータオブジェクトの型です。

types.CoroutineType

async def 関数に生成される コルーチン オブジェクトです。

Added in version 3.5.

types.AsyncGeneratorType

非同期ジェネレータ関数によって作成された 非同期ジェネレータ イテレータオブジェクトの型です。

Added in version 3.6.

class types.CodeType(**kwargs)

The type of code objects such as returned by compile().

引数 code, filename, name, argcount, posonlyargcount, kwonlyargcount, nlocals, stacksize, flags を指定して 監査イベント 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.

types.CellType

The type for cell objects: such objects are used as containers for a function's free variables.

Added in version 3.8.

types.MethodType

ユーザー定義のクラスのインスタンスのメソッドの型です。

types.BuiltinFunctionType

types.BuiltinMethodType

len() や sys.exit() のような組み込み関数や、組み込み型のメソッドの型です。 (ここでは "組み込み" という単語を "Cで書かれた" という意味で使っています)

types.WrapperDescriptorType

The type of methods of some built-in data types and base classes such as object.__init__() or object.__lt__().

Added in version 3.7.

types.MethodWrapperType

The type of bound methods of some built-in data types and base classes. For example it is the type of object().__str__.

Added in version 3.7.

types.NotImplementedType

NotImplemented の型です。

Added in version 3.10.

types.MethodDescriptorType

The type of methods of some built-in data types such as str.join().

Added in version 3.7.

types.ClassMethodDescriptorType

The type of unbound class methods of some built-in data types such as dict.__dict__['fromkeys'].

Added in version 3.7.

class types.ModuleType(name, doc=None)

module の型です。コンストラクタは生成するモジュールの名前と任意でその docstring を受け取ります。

注釈

インポートによりコントロールされる様々な属性を設定する場合、importlib.util.module_from_spec() を使用して新しいモジュールを作成してください。

__doc__

モジュールの docstring です。デフォルトは None です。

__loader__

モジュールをロードする loader です。デフォルトは None です。

This attribute is to match importlib.machinery.ModuleSpec.loader as stored in the __spec__ object.

注釈

A future version of Python may stop setting this attribute by default. To guard against this potential change, preferably read from the __spec__ attribute instead or use getattr(module, "__loader__", None) if you explicitly need to use this attribute.

バージョン 3.4 で変更: デフォルトが None になりました。以前はオプションでした。

__name__

The name of the module. Expected to match importlib.machinery.ModuleSpec.name.

__package__

モジュールがどの package に属しているかです。モジュールがトップレベルである (すなわち、いかなる特定のパッケージの一部でもない) 場合、この属性は '' に設定されます。そうでない場合、パッケージ名 (モジュールがパッケージ自身なら __name__) に設定されます。デフォルトは None です。

This attribute is to match importlib.machinery.ModuleSpec.parent as stored in the __spec__ object.

注釈

A future version of Python may stop setting this attribute by default. To guard against this potential change, preferably read from the __spec__ attribute instead or use getattr(module, "__package__", None) if you explicitly need to use this attribute.

バージョン 3.4 で変更: デフォルトが None になりました。以前はオプションでした。

__spec__

A record of the module's import-system-related state. Expected to be an instance of importlib.machinery.ModuleSpec.

Added in version 3.4.

types.EllipsisType

Ellipsis の型です。

Added in version 3.10.

class types.GenericAlias(t_origin, t_args)

The type of parameterized generics such as list[int].

t_origin should be a non-parameterized generic class, such as list, tuple or dict. t_args should be a tuple (possibly of length 1) of types which parameterize t_origin:

>>> from types import GenericAlias

>>> list[int] == GenericAlias(list, (int,))
True
>>> dict[str, int] == GenericAlias(dict, (str, int))
True

Added in version 3.9.

バージョン 3.9.2 で変更: This type can now be subclassed.

参考

Generic Alias Types

In-depth documentation on instances of types.GenericAlias

PEP 585 [https://peps.python.org/pep-0585/] - 標準コレクション型の型ヒントにおける総称型 (generics) の使用

Introducing the types.GenericAlias class

class types.UnionType

The type of union type expressions.

Added in version 3.10.

class types.TracebackType(tb_next, tb_frame, tb_lasti, tb_lineno)

sys.exception().__traceback__ に含まれるようなトレースバックオブジェクトの型です。

See the language reference for details of the available attributes and operations, and guidance on creating tracebacks dynamically.

types.FrameType

The type of frame objects such as found in tb.tb_frame if tb is a traceback object.

types.GetSetDescriptorType

The type of objects defined in extension modules with PyGetSetDef, such as FrameType.f_locals or array.array.typecode. This type is used as descriptor for object attributes; it has the same purpose as the property type, but for classes defined in extension modules.

types.MemberDescriptorType

datetime.timedelta.days のような、拡張モジュールにおいて PyMemberDef によって定義されたオブジェクトの型です。この型は、標準の変換関数を利用するような、Cのシンプルなデータメンバで利用されます。 property 型と同じ目的を持った型ですが、こちらは拡張モジュールで定義された型のためのものです。

In addition, when a class is defined with a __slots__ attribute, then for each slot, an instance of MemberDescriptorType will be added as an attribute on the class. This allows the slot to appear in the class's __dict__.

CPython 実装の詳細: Pythonの他の実装では、この型は GetSetDescriptorType と同じかもしれません。

class types.MappingProxyType(mapping)

読み出し専用のマッピングのプロキシです。マッピングのエントリーに関する動的なビューを提供します。つまり、マッピングが変わった場合にビューがこれらの変更を反映するということです。

Added in version 3.3.

バージョン 3.9 で変更: Updated to support the new union (|) operator from PEP 584 [https://peps.python.org/pep-0584/], which simply delegates to the underlying mapping.

key in proxy

元になったマッピングが key というキーを持っている場合 True を返します。そうでなければ False を返します。

proxy[key]

元になったマッピングの key というキーに対応するアイテムを返します。 key が存在しなければ、 KeyError が発生します。

iter(proxy)

元になったマッピングのキーを列挙するイテレータを返します。これは iter(proxy.keys()) のショートカットです。

len(proxy)

元になったマッピングに含まれるアイテムの数を返します。

copy()

元になったマッピングの浅いコピーを返します。

get(key[, default])

key が元になったマッピングに含まれている場合 key に対する値を返し、そうでなければ default を返します。もし default が与えられない場合は、デフォルト値の None になります。そのため、このメソッドが KeyError を発生させることはありません。

items()

元になったマッピングの items ((key, value) ペアの列) に対する新しいビューを返します。

keys()

元になったマッピングの keys に対する新しいビューを返します。

values()

元になったマッピングの values に対する新しいビューを返します。

reversed(proxy)

Return a reverse iterator over the keys of the underlying mapping.

Added in version 3.9.

hash(proxy)

Return a hash of the underlying mapping.

Added in version 3.12.

追加のユーティリティクラスと関数

class types.SimpleNamespace

名前空間への属性アクセスに加えて意味のある repr を提供するための、単純な object サブクラスです。

Unlike object, with SimpleNamespace you can add and remove attributes. If a SimpleNamespace object is initialized with keyword arguments, those are directly added to the underlying namespace.

この型は以下のコードとほぼ等価です:

class SimpleNamespace:
    def __init__(self, /, **kwargs):
        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

SimpleNamespace は class NS: pass を置き換えるものとして有用かもしれません。ですが、構造化されたレコード型に対しては、これよりはむしろ namedtuple() を使用してください。

Added in version 3.3.

バージョン 3.9 で変更: Attribute order in the repr changed from alphabetical to insertion (like dict).

types.DynamicClassAttribute(fget=None, fset=None, fdel=None, doc=None)

クラスの属性アクセスを __getattr__ に振り替えます。

これは記述子で、インスタンス経由のアクセスとクラス経由のアクセスで振る舞いが異なる属性を定義するのに使います。インスタンスアクセスは通常通りですが、クラス経由の属性アクセスはクラスの __getattr__ メソッドに振り替えられます。これは AttributeError の送出により行われます。

これによって、インスタンス上で有効なプロパティを持ち、クラス上で同名の仮想属性を持つことができます (例については enum.Enum を参照してください)。

Added in version 3.4.

コルーチンユーティリティ関数

types.coroutine(gen_func)

この関数は、 generator 関数を、ジェネレータベースのコルーチンを返す coroutine function に変換します。返されるジェネレータベースのコルーチンは依然として generator iterator ですが、同時に coroutine オブジェクトかつ awaitable であるとみなされます。ただし、必ずしも __await__() メソッドを実装する必要はありません。

gen_func はジェネレータ関数で、インプレースに変更されます。

gen_func がジェネレータ関数でない場合、この関数はラップされます。この関数が collections.abc.Generator のインスタンスを返す場合、このインスタンスは awaitable なプロキシオブジェクトにラップされます。それ以外のすべての型のオブジェクトは、そのまま返されます。

Added in version 3.5.

copy --- Shallow and deep copy operations

ソースコード: Lib/copy.py [https://github.com/python/cpython/tree/3.12/Lib/copy.py]

Python において代入文はオブジェクトをコピーしません。代入はターゲットとオブジェクトの間に束縛を作ります。ミュータブルなコレクションまたはミュータブルなアイテムを含むコレクションについては、元のオブジェクトを変更せずにコピーを変更できるように、コピーが必要になることが時々あります。このモジュールは、汎用的な浅い (shallow) コピーと深い (deep) コピーの操作 (以下で説明されます) を提供します。

以下にインターフェースをまとめます:

copy.copy(x)

Return a shallow copy of x.

copy.deepcopy(x[, memo])

Return a deep copy of x.

exception copy.Error

モジュール特有のエラーを送出します。

浅い (shallow) コピーと深い (deep) コピーの違いが関係するのは、複合オブジェクト (リストやクラスインスタンスのような他のオブジェクトを含むオブジェクト) だけです:

浅いコピー (shallow copy) は新たな複合オブジェクトを作成し、その後 (可能な限り) 元のオブジェクト中に見つかったオブジェクトに対する 参照 を挿入します。

深いコピー (deep copy) は新たな複合オブジェクトを作成し、その後元のオブジェクト中に見つかったオブジェクトの コピー を挿入します。

深いコピー操作には、しばしば浅いコピー操作の時には存在しない 2 つの問題がついてまわります:

再帰的なオブジェクト (直接、間接に関わらず、自分自身に対する参照を持つ複合オブジェクト) は再帰ループを引き起こします。

深いコピーは何もかもコピーしてしまうため、例えば複数のコピー間で共有するつもりだったデータも余分にコピーしてしまいます。

deepcopy() 関数では、これらの問題を以下のようにして回避しています:

現時点でのコピー過程ですでにコピーされたオブジェクトの memo 辞書を保持する。

ユーザ定義のクラスでコピー操作やコピーされる内容の集合を上書きできるようにする。

このモジュールでは、モジュール、メソッド、スタックトレース、スタックフレーム、ファイル、ソケット、ウィンドウ、その他これらに類似の型をコピーしません。このモジュールでは元のオブジェクトを変更せずに返すことで関数とクラスを (浅くまたは深く)「コピー」します。これは pickle モジュールでの扱われかたと同じです。

辞書型の浅いコピーは dict.copy() で、リストの浅いコピーはリスト全体を指すスライス (例えば copied_list = original_list[:]) でできます。

クラスは、コピーを制御するために pickle の制御に使用するのと同じインターフェースを使用することができます。これらのメソッドについての情報はモジュール pickle の説明を参照してください。実際、 copy モジュールは、 copyreg モジュールによって登録された pickle 関数を使用します。

In order for a class to define its own copy implementation, it can define special methods __copy__() and __deepcopy__(). The former is called to implement the shallow copy operation; no additional arguments are passed. The latter is called to implement the deep copy operation; it is passed one argument, the memo dictionary. If the __deepcopy__() implementation needs to make a deep copy of a component, it should call the deepcopy() function with the component as first argument and the memo dictionary as second argument. The memo dictionary should be treated as an opaque object.

参考

pickle モジュール

オブジェクト状態の取得と復元をサポートするために使われる特殊メソッドについて議論されています。

pprint --- Data pretty printer

ソースコード: Lib/pprint.py [https://github.com/python/cpython/tree/3.12/Lib/pprint.py]

pprint モジュールを使うと、Pythonの任意のデータ構造をインタープリタへの入力で使われる形式にして "pretty-print" できます。書式化された構造の中にPythonの基本的なタイプではないオブジェクトがあるなら、表示できないかもしれません。表示できないのは、ファイル、ソケット、あるいはクラスのようなオブジェクトや、 その他Pythonのリテラルとして表現できない様々なオブジェクトが含まれていた場合です。

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 で変更: types.SimpleNamespace の pretty-print サポートが追加されました。

バージョン 3.10 で変更: dataclasses.dataclass の pretty-print サポートが追加されました。

関数

pprint.pp(object, *args, sort_dicts=False, **kwargs)

object のフォーマットされた表現の後に改行を入れて表示します。もし sort_dicts が false (デフォルト) ならば、辞書はキーが挿入順に表示され、そうでなければ、辞書のキーがソートされます。 args と kwargs はフォーマットパラメータとして pprint() に渡されます。

>>> 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']

Added in version 3.8.

pprint.pprint(object, stream=None, indent=1, width=80, depth=None, *, compact=False, sort_dicts=True, underscore_numbers=False)

stream 上に object のフォーマットされた表現を出力して、その後に newline を続けます。 stream が None の場合、 sys.stdout が使用されます。これは、対話型インタプリタの中で値を調査するために print() 関数の代わりに使用されることがあります (さらに、スコープ内で使用するために print = pprint.pprint を再代入することができます)。

The configuration parameters stream, indent, width, depth, compact, sort_dicts and underscore_numbers are passed to the PrettyPrinter constructor and their meanings are as described in its documentation below.

Note that sort_dicts is True by default and you might want to use pp() instead where it is False by default.

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 PrettyPrinter constructor as formatting parameters and their meanings are as described in its documentation below.

pprint.isreadable(object)

object を書式化して出力できる("readable") か、あるいは eval() を使って値を再構成できるかを返します。再帰的なオブジェクトに対しては常に False を返します。

>>> pprint.isreadable(stuff)
False

pprint.isrecursive(object)

Determine if object requires a recursive representation. This function is subject to the same limitations as noted in saferepr() below and may raise an RecursionError if it fails to detect a recursive object.

pprint.saferepr(object)

Return a string representation of object, protected against recursion in some common data structures, namely instances of dict, list and tuple or subclasses whose __repr__ has not been overridden. If the representation of object exposes a recursive entry, the recursive reference will be represented as <Recursion on typename with id=number>. The representation is not otherwise formatted.

>>> pprint.saferepr(stuff)
"[<Recursion on list with id=...>, 'spam', 'eggs', 'lumberjack', 'knights', 'ni']"

PrettyPrinter オブジェクト

This module defines one class:

class pprint.PrettyPrinter(indent=1, width=80, depth=None, stream=None, *, compact=False, sort_dicts=True, underscore_numbers=False)

PrettyPrinter のインスタンスを生成します。このコンストラクタにはいくつかのキーワード引数を設定できます。

stream (default sys.stdout) is a file-like object to which the output will be written by calling its write() method. If both stream and sys.stdout are None, then pprint() silently returns.

Other values configure the manner in which nesting of complex data structures is displayed.

indent (default 1) specifies the amount of indentation added for each nesting level.

depth controls 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 .... By default, there is no constraint on the depth of the objects being formatted.

width (default 80) specifies 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.

compact impacts the way that long sequences (lists, tuples, sets, etc) are formatted. If compact is false (the default) then each item of a sequence will be formatted on a separate line. If compact is true, as many items as will fit within the width will be formatted on each output line.

If sort_dicts is true (the default), dictionaries will be formatted with their keys sorted, otherwise they will display in insertion order.

If underscore_numbers is true, integers will be formatted with the _ character for a thousands separator, otherwise underscores are not displayed (the default).

バージョン 3.4 で変更: compact 引数が追加されました。

バージョン 3.8 で変更: sort_dicts 引数が追加されました。

バージョン 3.10 で変更: underscore_numbers 引数が追加されました。

バージョン 3.11 で変更: No longer attempts to write to sys.stdout if it is None.

>>> 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', (...)))))))

PrettyPrinter インスタンスには以下のメソッドがあります:

PrettyPrinter.pformat(object)

object の書式化した表現を返します。これは PrettyPrinter のコンストラクタに渡されたオプションを考慮して書式化されます。

PrettyPrinter.pprint(object)

object の書式化した表現を指定したストリームに出力し、最後に改行します。

以下のメソッドは、対応する同じ名前の関数と同じ機能を持っています。以下のメソッドをインスタンスに対して使うと、新たに PrettyPrinter オブジェクトを作る必要がないのでちょっぴり効果的です。

PrettyPrinter.isreadable(object)

object を書式化して出力できる（"readable"）か、あるいは eval() を使って値を再構成できるかを返します。これは再帰的なオブジェクトに対して False を返すことに注意して下さい。もし PrettyPrinter の depth 引数が設定されていて、オブジェクトのレベルが設定よりも深かったら、 False を返します。

PrettyPrinter.isrecursive(object)

オブジェクトが再帰的な表現かどうかを返します。

このメソッドをフックとして、サブクラスがオブジェクトを文字列に変換する方法を修正するのが可能になっています。デフォルトの実装では、内部で saferepr() を呼び出しています。

PrettyPrinter.format(object, context, maxlevels, level)

次の3つの値を返します。object をフォーマット化して文字列にしたもの、その結果が読み込み可能かどうかを示すフラグ、再帰が含まれているかどうかを示すフラグ。最初の引数は表示するオブジェクトです。 2つめの引数はオブジェクトの id() をキーとして含むディクショナリで、オブジェクトを含んでいる現在の（直接、間接に object のコンテナとして表示に影響を与える）環境です。ディクショナリ context の中でどのオブジェクトが表示されたか表示する必要があるなら、3つめの返り値は True になります。 format() メソッドの再帰呼び出しではこのディクショナリのコンテナに対してさらにエントリを加えます。 3つめの引数 maxlevels で再帰呼び出しのレベルを制限します。制限しない場合、 0 になります。この引数は再帰呼び出しでそのまま渡されます。 4つめの引数 level で現在のレベルを設定します。再帰呼び出しでは、現在の呼び出しより小さい値が渡されます。

使用例

To demonstrate several uses of the pp() function and its parameters, let's fetch information about a project from PyPI [https://pypi.org]:

>>> import json
>>> import pprint
>>> from urllib.request import urlopen
>>> with urlopen('https://pypi.org/pypi/sampleproject/json') as resp:
...     project_info = json.load(resp)['info']

In its basic form, pp() shows the whole object:

>>> 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'}

結果をある深さ depth に制限することができます (より深い内容には省略記号が使用されます):

>>> 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'}

それに加えて、最大の文字幅 width を指示することもできます。長いオブジェクトを分離することができなければ、指定された幅を超過します:

>>> 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'}

reprlib --- Alternate repr() implementation

ソースコード: Lib/reprlib.py [https://github.com/python/cpython/tree/3.12/Lib/reprlib.py]

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

このモジュールはクラスとインスタンス、それに関数を提供します:

class 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)

組み込み関数 repr() に似た関数を実装するために役に立つフォーマット用サービスを提供します。過度に長い表現を作り出さないようにするための大きさの制限をオブジェクト型ごとに設定できます。

The keyword arguments of the constructor can be used as a shortcut to set the attributes of the Repr instance. Which means that the following initialization:

aRepr = reprlib.Repr(maxlevel=3)

は、次のコードと等しいです:

aRepr = reprlib.Repr()
aRepr.maxlevel = 3

See section Repr Objects for more information about Repr attributes.

バージョン 3.12 で変更: Allow attributes to be set via keyword arguments.

reprlib.aRepr

これは下で説明される repr() 関数を提供するために使われる Repr のインスタンスです。このオブジェクトの属性を変更すると、 repr() と Python デバッガが使うサイズ制限に影響します。

reprlib.repr(obj)

これは aRepr の repr() メソッドです。同じ名前の組み込み関数が返す文字列と似ていますが、最大サイズに制限のある文字列を返します。

In addition to size-limiting tools, the module also provides a decorator for detecting recursive calls to __repr__() and substituting a placeholder string instead.

@reprlib.recursive_repr(fillvalue='...')

Decorator for __repr__() methods to detect recursive calls within the same thread. If a recursive call is made, the fillvalue is returned, otherwise, the usual __repr__() call is made. For 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'>

Added in version 3.2.

Reprオブジェクト

Repr インスタンスはオブジェクト型毎に表現する文字列のサイズを制限するために使えるいくつかの属性と、特定のオブジェクト型をフォーマットするメソッドを提供します。

Repr.fillvalue

This string is displayed for recursive references. It defaults to ....

Added in version 3.11.

Repr.maxlevel

再帰的な表現を作る場合の深さ制限。デフォルトは 6 です。

Repr.maxdict

Repr.maxlist

Repr.maxtuple

Repr.maxset

Repr.maxfrozenset

Repr.maxdeque

Repr.maxarray

指定されたオブジェクト型に対するエントリ表現の数についての制限。 maxdict に対するデフォルトは 4 で、 maxarray は 5 、その他に対しては 6 です。

Repr.maxlong

整数の表現のおける文字数の最大値。中央の数字が抜け落ちます。デフォルトは 40 です。

Repr.maxstring

文字列の表現における文字数の制限。文字列の"通常の"表現は文字の「元」として使われることに注意してください。表現にエスケープシーケンスが必要とされる場合、表現が短縮されるときにこれらのエスケープシーケンスの形式は崩れます。デフォルトは 30 です。

Repr.maxother

この制限は Repr オブジェクトに利用できる特定のフォーマットメソッドがないオブジェクト型のサイズをコントロールするために使われます。 maxstring と同じようなやり方で適用されます。デフォルトは 20 です。

Repr.indent

If this attribute is set to None (the default), the output is formatted with no line breaks or indentation, like the standard repr(). For 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']

If indent is set to a string, each recursion level is placed on its own line, indented by that string:

>>> aRepr.indent = '-->'
>>> print(aRepr.repr(example))
[
-->1,
-->'spam',
-->{
-->-->'a': 2,
-->-->'b': 'spam eggs',
-->-->'c': {
-->-->-->3: 4.5,
-->-->-->6: [],
-->-->},
-->},
-->'ham',
]

Setting indent to a positive integer value behaves as if it was set to a string with that number of spaces:

>>> aRepr.indent = 4
>>> print(aRepr.repr(example))
[
    1,
    'spam',
    {
        'a': 2,
        'b': 'spam eggs',
        'c': {
            3: 4.5,
            6: [],
        },
    },
    'ham',
]

Added in version 3.12.

Repr.repr(obj)

このインスタンスで設定されたフォーマットを使う、組み込み repr() と等価なもの。

Repr.repr1(obj, level)

repr() が使う再帰的な実装。 obj の型を使ってどのフォーマットメソッドを呼び出すかを決定し、それに obj と level を渡します。再帰呼び出しにおいて level の値に対して level - 1 を与える再帰的なフォーマットを実行するために、型に固有のメソッドは repr1() を呼び出します。

Repr.repr_TYPE(obj, level)

型名に基づく名前をもつメソッドとして、特定の型に対するフォーマットメソッドは実装されます。メソッド名では、 TYPE は '_'.join(type(obj).__name__.split()) に置き換えられます。これらのメソッドへのディスパッチは repr1() によって処理されます。再帰的に値をフォーマットする必要がある型固有のメソッドは、 self.repr1(subobj, level - 1) を呼び出します。

Reprオブジェクトをサブクラス化する

The use of dynamic dispatching by Repr.repr1() allows subclasses of 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:

import reprlib
import sys

class MyRepr(reprlib.Repr):

    def repr_TextIOWrapper(self, obj, level):
        if obj.name in {'<stdin>', '<stdout>', '<stderr>'}:
            return obj.name
        return repr(obj)

aRepr = MyRepr()
print(aRepr.repr(sys.stdin))         # prints '<stdin>'

<stdin>

enum --- Support for enumerations

Added in version 3.4.

ソースコード: Lib/enum.py [https://github.com/python/cpython/tree/3.12/Lib/enum.py]

Important

このページには、リファレンス情報だけが含まれています。チュートリアルは、以下のページを参照してください

基本チュートリアル

上級チュートリアル

Enum クックブック

列挙型とは:

一意の値に紐付けられたシンボリックな名前の集合です

反復可能であり、定義順にその正規の（エイリアスでない）メンバーを返します

値を渡してメンバーを返すために、 呼び出し 構文を使用します

名前を受け取ってメンバーを返すために、 インデックス 構文を使用します

列挙型は、class 構文を使用するか、関数呼び出し構文を使用して作成されます:

>>> from enum import Enum

>>> # class syntax
>>> class Color(Enum):
...     RED = 1
...     GREEN = 2
...     BLUE = 3

>>> # functional syntax
>>> Color = Enum('Color', ['RED', 'GREEN', 'BLUE'])

Enum の作成に class 文を使用できるものの、Enum は通常の Python クラスではありません。詳細は Enum はどう違うのか? を参照してください。

注釈

用語

クラス Color は 列挙型 (または Enum) です

属性 Color.RED, Color.GREEN などは 列挙型のメンバー (または メンバー) で、機能的には定数です。

列挙型のメンバーは 名前 と 値 を持ちます (Color.RED の名前は RED 、 Color.BLUE の値は 3 など。)

モジュールコンテンツ

EnumType

Enumおよびそのサブクラスのための type です。

Enum

列挙型定数を作成する基底クラスです。

IntEnum

int のサブクラスでもある列挙型定数を作成する基底クラスです。(Notes)

StrEnum

str のサブクラスでもある列挙型定数を作成する基底クラスです。(Notes)

Flag

列挙型定数を作成する基底クラスで、ビット演算を使って組み合わせられ、その結果も IntFlag メンバーになります。

IntFlag

列挙型定数を作成する基底クラスで、ビット演算子を使って組み合わせられ、その結果も IntFlag メンバーになります。 IntFlag は int のサブクラスでもあります。(Notes)

ReprEnum

IntEnum、StrEnum、および IntFlag によって使用され、mix-inされた型の str() を保持します。

EnumCheck

CONTINUOUS、NAMED_FLAGS、UNIQUE の値を持つ列挙型です。 verify() と共に使用して、指定された列挙型がさまざまな制約を満たしていることを確認します。

FlagBoundary

An enumeration with the values STRICT, CONFORM, EJECT, and KEEP which allows for more fine-grained control over how invalid values are dealt with in an enumeration.

auto

インスタンスは列挙型のメンバーに適切な値で置き換えられます。StrEnum ではデフォルトの値がメンバー名を小文字にしたものですが、その他の列挙型のデフォルトは1から連番で増加する値となります。

property()

メンバー名との競合を避けながら Enum メンバーに属性を持たせます。value 属性と name 属性はこの方法で実装されます。

unique()

一つの名前だけがひとつの値に束縛されていることを保証する Enum クラスのデコレーターです。

verify()

Enum class decorator that checks user-selectable constraints on an enumeration.

member()

obj をメンバーにします。デコレータとして使用できます。

nonmember()

obj をメンバーにしません。デコレータとして使用できます。

global_enum()

Modify the str() and repr() of an enum to show its members as belonging to the module instead of its class, and export the enum members to the global namespace.

show_flag_values()

フラグに含まれる、全ての2の累乗の整数のリストを返します。

Added in version 3.6: Flag, IntFlag, auto

Added in version 3.11: StrEnum, EnumCheck, ReprEnum, FlagBoundary, property, member, nonmember, global_enum, show_flag_values

データ型

class enum.EnumType

EnumType は enum 列挙型の メタクラス です。 EnumType のサブクラスを作成することが可能です -- 詳細は EnumTypeのサブクラスを作る を参照してください。

EnumType is responsible for setting the correct __repr__(), __str__(), __format__(), and __reduce__() methods on the final enum, as well as creating the enum members, properly handling duplicates, providing iteration over the enum class, etc.

__call__(cls, value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

このメソッドは2つの異なる方法で呼び出されます。

既存のメンバーを検索する:

cls:

呼び出されるenumクラス。

value:

検索する値。

cls を使って新しい列挙型を作成する（既存の列挙型がメンバーを持たない場合のみ）:

cls:

呼び出されるenumクラス。

value:

新しく作成するEnumの名前。

names:

新しく作成するEnumのメンバーの名前/値のリスト。

module:

新しく作成するEnumの属するモジュール名。

qualname:

The actual location in the module where this Enum can be found.

type:

新しく作成するEnumのmix-in型。

start:

Enumの最初の整数値（auto で使用されます）。

boundary:

bit演算での範囲外の値の扱い方（Flag のみ）。

__contains__(cls, member)

メンバーが cls に属している場合は True を返します:

>>> some_var = Color.RED
>>> some_var in Color
True
>>> Color.RED.value in Color
True

バージョン 3.12 で変更: Python 3.12 以前では、非Enumメンバーの包含判定が行われた場合、TypeError が送出されます。

__dir__(cls)

['__class__', '__doc__', '__members__', '__module__'] と、 cls に属するメンバー名を返します:

>>> dir(Color)
['BLUE', 'GREEN', 'RED', '__class__', '__contains__', '__doc__', '__getitem__', '__init_subclass__', '__iter__', '__len__', '__members__', '__module__', '__name__', '__qualname__']

__getitem__(cls, name)

cls 内の一致するメンバーを返すか、KeyError を送出します:

>>> Color['BLUE']
<Color.BLUE: 3>

__iter__(cls)

Returns each member in cls in definition order:

>>> list(Color)
[<Color.RED: 1>, <Color.GREEN: 2>, <Color.BLUE: 3>]

__len__(cls)

cls 内のメンバーの数を返します。:

>>> len(Color)
3

__members__

Returns a mapping of every enum name to its member, including aliases

__reversed__(cls)

cls 内の各メンバー を定義順の逆順で返します:

>>> list(reversed(Color))
[<Color.BLUE: 3>, <Color.GREEN: 2>, <Color.RED: 1>]

Added in version 3.11: Before 3.11 enum used EnumMeta type, which is kept as an alias.

class enum.Enum

Enum は全ての enum 列挙型の基底クラスです。

name

Enum メンバーを定義するために使用される名前:

>>> Color.BLUE.name
'BLUE'

value

Enum メンバーに与えられた値:

>>> Color.RED.value
1

Value of the member, can be set in __new__().

注釈

列挙型のメンバー値

メンバー値は何であっても構いません: int, str などなど。正確な値が重要でない場合は、 auto インスタンスを使っておくと、適切な値が選ばれます。詳細は auto を参照してください。

While mutable/unhashable values, such as dict, list or a mutable dataclass, can be used, they will have a quadratic performance impact during creation relative to the total number of mutable/unhashable values in the enum.

_name_

Name of the member.

_value_

Value of the member, can be set in __new__().

_order_

No longer used, kept for backward compatibility. (class attribute, removed during class creation).

_ignore_

_ignore_ は列挙の作成中にのみ使用され、作成が完了すると削除されます。

_ignore_ は、メンバーにならず、作成された列挙から削除される名前のリストです。例については、TimePeriod を参照してください。

__dir__(self)

Returns ['__class__', '__doc__', '__module__', 'name', 'value'] and any public methods defined on self.__class__:

>>> 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']

_generate_next_value_(name, start, count, last_values)

name:

定義されているメンバーの名前（例：'RED'）。

start:

Enumの開始値。デフォルトは1です。

count:

定義済みのメンバーの数。現在のメンバーを含めない。

last_values:

定義済みの値のリスト。

auto によって返される次の値を決定するために使用される staticmethod です:

>>> from enum import auto
>>> class PowersOfThree(Enum):
...     @staticmethod
...     def _generate_next_value_(name, start, count, last_values):
...         return 3 ** (count + 1)
...     FIRST = auto()
...     SECOND = auto()
...
>>> PowersOfThree.SECOND.value
9

__init__(self, *args, **kwds)

デフォルトでは何もしません。メンバーに複数の値が指定されている場合、それらの値は __init__ の別々の引数となります。例えば、

>>> from enum import Enum
>>> class Weekday(Enum):
...     MONDAY = 1, 'Mon'

Weekday.__init__() は Weekday.__init__(self, 1, 'Mon') として呼び出されます。

__init_subclass__(cls, **kwds)

サブクラスを更に設定するために使用される classmethod です。デフォルトでは何も行いません。

_missing_(cls, value)

cls で見つからない値を検索するための classmethod です。デフォルトでは何もしませんが、カスタムの検索の振る舞いを実装するためにオーバーライドすることができます:

>>> from enum import StrEnum
>>> class Build(StrEnum):
...     DEBUG = auto()
...     OPTIMIZED = auto()
...     @classmethod
...     def _missing_(cls, value):
...         value = value.lower()
...         for member in cls:
...             if member.value == value:
...                 return member
...         return None
...
>>> Build.DEBUG.value
'debug'
>>> Build('deBUG')
<Build.DEBUG: 'debug'>

__new__(cls, *args, **kwds)

デフォルトでは存在しません。指定された場合、列挙型のクラス定義またはmix-inクラス（例えば int など）のいずれかで、メンバーに代入されたすべての値が渡されます。例:

>>> from enum import Enum
>>> class MyIntEnum(int, Enum):
...     TWENTYSIX = '1a', 16

results in the call int('1a', 16) and a value of 26 for the member.

注釈

When writing a custom __new__, do not use super().__new__ -- call the appropriate __new__ instead.

__repr__(self)

repr() の呼び出しに使用される文字列を返します。デフォルトでは、 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')

__str__(self)

str() の呼び出しに使用される文字列を返します。デフォルトでは、 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')

__format__(self)

format() および f-string の呼び出しに使用される文字列を返します。デフォルトでは、__str__() の戻り値を返しますが、オーバーライドすることもできます。:

>>> 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')

注釈

Enum で auto を使用すると、 1 から始まりインクリメントする整数が値となります。

バージョン 3.12 で変更: データクラスのサポート の追加

class enum.IntEnum

IntEnum is the same as Enum, but its members are also integers and can be used anywhere that an integer can be used. If any integer operation is performed with an IntEnum member, the resulting value loses its enumeration status.

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

注釈

IntEnum で auto を使用すると、 1 から始まりインクリメントする整数が値となります。

バージョン 3.11 で変更: __str__() は、既存の定数を置き換えるユースケースをより良くサポートするために int.__str__() に変更されました。同じ理由で、__format__() は既に int.__format__() に変更されています。

class enum.StrEnum

StrEnum is the same as Enum, but its members are also strings and can be used in most of the same places that a string can be used. The result of any string operation performed on or with a StrEnum member is not part of the enumeration.

注釈

標準ライブラリの中には、 str の代わりに str のサブクラス（つまり、 type(unknown) == str の代わりに isinstance(unknown, str) ）を厳密にチェックする場所があります。そのような場所では、 str(StrEnum.member) を使用する必要があります。

注釈

StrEnum で auto を使用すると、メンバー名を小文字に変換したものが値となります。

注釈

__str__() は 既存の定数の置換 ユースケースをより良くサポートするために str.__str__() となりました。 __format__() も同様に、同じ理由で str.__format__() となりました。

Added in version 3.11.

class enum.Flag

Flag は Enum と同じですが、そのメンバーはビット単位演算子 & (論理積)、 | (論理和)、 ^ (排他的論理和)、 および ~ (反転) をサポートしています。これらの演算の結果は列挙型のメンバーです。

__contains__(self, value)

値を含む場合に True を返します:

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

__iter__(self):

エイリアスでない、全てのメンバーを返します:

>>> list(Color.RED)
[<Color.RED: 1>]
>>> list(purple)
[<Color.RED: 1>, <Color.BLUE: 4>]

Added in version 3.11.

__len__(self):

flag 内のメンバーの数を返します:

>>> len(Color.GREEN)
1
>>> len(white)
3

__bool__(self):

メンバーがflagに含まれている場合は True を返し、それ以外の場合は False を返します:

>>> bool(Color.GREEN)
True
>>> bool(white)
True
>>> black = Color(0)
>>> bool(black)
False

__or__(self, other)

現在のフラグと他のフラグの論理和となるフラグを返します:

>>> Color.RED | Color.GREEN
<Color.RED|GREEN: 3>

__and__(self, other)

現在のフラグと他のフラグの論理積となるフラグを返します:

>>> purple & white
<Color.RED|BLUE: 5>
>>> purple & Color.GREEN
<Color: 0>

__xor__(self, other)

現在のフラグと他のフラグの排他的論理和となるフラグを返します:

>>> purple ^ white
<Color.GREEN: 2>
>>> purple ^ Color.GREEN
<Color.RED|GREEN|BLUE: 7>

__invert__(self):

Returns all the flags in type(self) that are not in self:

>>> ~white
<Color: 0>
>>> ~purple
<Color.GREEN: 2>
>>> ~Color.RED
<Color.GREEN|BLUE: 6>

_numeric_repr_()

Function used to format any remaining unnamed numeric values. Default is the value's repr; common choices are hex() and oct().

注釈

auto と Flag を一緒に使うと、1 から始まる2の累乗の整数になります。

バージョン 3.11 で変更: 値が0のフラグの repr() は変更されました。現在は以下のとおりです:

>>> Color(0)
<Color: 0>

class enum.IntFlag

IntFlag is the same as Flag, but its members are also integers and can be used anywhere that an integer can be used.

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

IntFlag のメンバーと整数の演算が行われた場合、結果は IntFlag ではありません:

>>> Color.RED + 2
3

If a Flag operation is performed with an IntFlag member and:

結果が有効な IntFlag: IntFlag が返されます

the result is not a valid IntFlag: the result depends on the FlagBoundary setting

The repr() of unnamed zero-valued flags has changed. It is now:

>>> Color(0)
<Color: 0>

注釈

auto と IntFlag を一緒に使うと、1 から始まる2の累乗の整数になります。

バージョン 3.11 で変更: __str__() は、既存の定数を置き換えるユースケースをより良くサポートするために int.__str__() に変更されました。同じ理由で、__format__() は既に int.__format__() に変更されています。

IntFlag の反転は、与えられたフラグ以外のすべてのフラグの結合となる正の値を返すようになりました。これは既存の Flag の振る舞いに一致します。

class enum.ReprEnum

ReprEnum uses the repr() of Enum, but the str() of the mixed-in data type:

int.__str__() for IntEnum and IntFlag

str.__str__() for StrEnum

ReprEnum を継承することで、Enum デフォルトの str() を使用する代わりに、mix-inされたデータ型の str() / format() を使用します。

Added in version 3.11.

class enum.EnumCheck

EnumCheck には verify() デコレータやさまざまな制約を保証するために使用されるオプションが含まれています。制約に違反すると ValueError が発生します。

UNIQUE

それぞれの値が1つの名前しか持たないことを確認します:

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

CONTINUOUS

最小値のメンバーと最大値のメンバーの間に欠損値がないことを確認します:

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

NAMED_FLAGS

任意のフラググループ/マスクが、名前付きフラグのみを含むことを確認します -- 値を指定するのではなく、auto() によって生成される場合に便利です:

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

注釈

CONTINUOUSとNAMED_FLAGSは整数値のメンバーとともに動作するように設計されています。

Added in version 3.11.

class enum.FlagBoundary

FlagBoundary controls how out-of-range values are handled in Flag and its subclasses.

STRICT

範囲外の値は ValueError を送出します。これは Flag のデフォルトです:

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

CONFORM

Out-of-range values have invalid values removed, leaving a valid Flag value:

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

EJECT

Out-of-range values lose their Flag membership and revert to int.

>>> from enum import Flag, EJECT, auto
>>> class EjectFlag(Flag, boundary=EJECT):
...     RED = auto()
...     GREEN = auto()
...     BLUE = auto()
...
>>> EjectFlag(2**2 + 2**4)
20

KEEP

Out-of-range values are kept, and the Flag membership is kept. This is the default for IntFlag:

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

Added in version 3.11.

__dunder__ 名のサポート

__members__ は読み込み専用の、 member_name:member を要素とする順序付きマッピングです。これはクラスでのみ利用可能です。

__new__(), if specified, must create and return the enum members; it is also a very good idea to set the member's _value_ appropriately. Once all the members are created it is no longer used.

_sunder_ 名のサポート

_name_ -- name of the member

_value_ -- value of the member; can be set in __new__

_missing_() -- a lookup function used when a value is not found; may be overridden

_ignore_ -- a list of names, either as a list or a str, that will not be transformed into members, and will be removed from the final class

_order_ -- no longer used, kept for backward compatibility (class attribute, removed during class creation)

_generate_next_value_() -- used to get an appropriate value for an enum member; may be overridden

注釈

For standard Enum classes the next value chosen is the last value seen incremented by one.

For Flag classes the next value chosen will be the next highest power-of-two, regardless of the last value seen.

Added in version 3.6: _missing_, _order_, _generate_next_value_

Added in version 3.7: _ignore_

ユーティリティとデコレータ

class enum.auto

auto can be used in place of a value. If used, the Enum machinery will call an Enum's _generate_next_value_() to get an appropriate value. For Enum and IntEnum that appropriate value will be the last value plus one; for Flag and IntFlag it will be the first power-of-two greater than the highest value; for StrEnum it will be the lower-cased version of the member's name. Care must be taken if mixing auto() with manually specified values.

auto インスタンスは、代入のトップレベルでのみ解決されます。

FIRST = auto() は動作します（auto() は 1 に置き換えられます）

SECOND = auto(), -2 は動作します（auto は 2 に置き換えられるため、 SECOND 列挙型のメンバーには 2, -2 が使用されます）

THREE = [auto(), -3] は動作 しません （enumメンバー THREE の作成に <auto instance>, -3 が使用されます）

バージョン 3.11.1 で変更: 以前のバージョンでは、 auto() は、代入行に他のものがあると正しく動作しませんでした。

_generate_next_value_ は、 auto が使用する値をカスタマイズするためにオーバーライドすることができる。

注釈

3.13では、デフォルトの _generate_next_value_ は常に最も高いメンバーの値に1を加えたものを返し、メンバーのいずれかが比較できない型である場合には失敗します。

@enum.property

A decorator similar to the built-in property, but specifically for enumerations. It allows member attributes to have the same names as members themselves.

注釈

the property and the member must be defined in separate classes; for example, the value and name attributes are defined in the Enum class, and Enum subclasses can define members with the names value and name.

Added in version 3.11.

@enum.unique

列挙型専用の class デコレーターです。列挙型の __members__ に別名がないかどうか検索します; 見つかった場合、ValueError が詳細情報とともに送出されます:

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

@enum.verify

列挙型専用の class デコレーターです。対象の列挙型に対してチェックを行う制約の指定には EnumCheck のメンバーが使用されます。

Added in version 3.11.

@enum.member

列挙型で使用するデコレータ: 対象は列挙型のメンバー になります。

Added in version 3.11.

@enum.nonmember

列挙型で使用するデコレータ: 対象は列挙型のメンバー になりません。

Added in version 3.11.

@enum.global_enum

A decorator to change the str() and repr() of an enum to show its members as belonging to the module instead of its class. Should only be used when the enum members are exported to the module global namespace (see re.RegexFlag for an example).

Added in version 3.11.

enum.show_flag_values(value)

フラグの value に含まれる全ての2の累乗の整数のリストを返します。

Added in version 3.11.

注釈

IntEnum 、 StrEnum 、 IntFlag

これらの3つの列挙型は、既存の整数ベースおよび文字列ベースの値の代替として設計されています。そのため、追加の制限があります:

__str__ は、列挙型のメンバーの名前ではなく値を使用します

__format__ は __str__ を使用するため、列挙型のメンバーの名前ではなく値を使用します

もし、そのような制限が必要でない/望まない場合は、int または str タイプを継承して、カスタムの基底クラスを作成することができます:

>>> from enum import Enum
>>> class MyIntEnum(int, Enum):
...     pass

または列挙型の中で適切な str() などを再代入することもできます:

>>> from enum import Enum, IntEnum
>>> class MyIntEnum(IntEnum):
...     __str__ = Enum.__str__

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

ソースコード: Lib/graphlib.py [https://github.com/python/cpython/tree/3.12/Lib/graphlib.py]

class graphlib.TopologicalSorter(graph=None)

ハッシュ可能 な頂点のグラフをトポロジカルソートする機能を提供します。

トポロジカル順序はグラフの頂点の線形順序で、頂点 u から 頂点 v への有向辺 u-> v 全てについて、頂点 u が頂点 v よりも前にくるような順序です。例えば、グラフの頂点が実行するタスクを表し、その辺があるタスクが別のタスクよりも前に実行されなければならないという制約を表す場合、トポロジカル順序は制約を満たすタスクの実行順序のシーケンスになります。トポロジカル順序が得られるのは、グラフが有向閉路を持たない、つまり有向非巡回グラフである場合でかつその時に限ります。

もしオプションの graph 引数が与えられた場合、その値は有向非巡回グラフを表す辞書でなければならず、辞書はそのキーがノードで、その値はキーのノードの先行ノードのイテラブルとなります（言い換えると、辞書の値はそのキーのノードを指す辺を持つノードのイテラブルです） 辺 add() メソッドを使うことで、さらにノードを追加することができます。

一般的に、与えられたグラフのソートの実行に必要なステップは以下のようになります:

TopologicalSorter のインスタンスをオプションの初期グラフで生成します。

さらにノードをグラフに追加します。

prepare() をグラフ上で呼び出します。

is_active() が True の間、 get_ready() によって返されたノード群をイテレートし、それらを処理します。ノードの処理が終わる都度、done() を呼び出します。

すぐにグラフのノードをソートした結果が必要で、並行性が不要な場合、便利なメソッド TopologicalSorter.static_order() を直接呼び出すことができます:

>>> graph = {"D": {"B", "C"}, "C": {"A"}, "B": {"A"}}
>>> ts = TopologicalSorter(graph)
>>> tuple(ts.static_order())
('A', 'C', 'B', 'D')

このクラスは、簡単に準備が整ったノードの並列処理を行えるよう設計されています。例えば:

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)

add(node, *predecessors)

新しいノードとその先行ノードをグラフに追加します。 node と predecessors のすべての要素は ハッシュ可能 でなければなりません。

同じ node 引数で複数回呼び出した場合、依存関係の集合は、それまでに指定した依存関係の和集合になります。

It is possible to add a node with no dependencies (predecessors is not provided) or to provide a dependency twice. If a node that has not been provided before is included among predecessors it will be automatically added to the graph with no predecessors of its own.

prepare() を呼び出した後にこのメソッドを呼び出すと、ValueError を送出します。

prepare()

Mark the graph as finished and check for cycles in the graph. If any cycle is detected, CycleError will be raised, but get_ready() can still be used to obtain as many nodes as possible until cycles block more progress. After a call to this function, the graph cannot be modified, and therefore no more nodes can be added using add().

is_active()

Returns True if more progress can be made and False otherwise. Progress can be made if cycles do not block the resolution and either there are still nodes ready that haven't yet been returned by TopologicalSorter.get_ready() or the number of nodes marked TopologicalSorter.done() is less than the number that have been returned by TopologicalSorter.get_ready().

The __bool__() method of this class defers to this function, so instead of:

if ts.is_active():
    ...

このように簡単に記述できます:

if ts:
    ...

前もって prepare() を呼び出さずにこの関数を呼び出すと ValueError を送出します。

done(*nodes)

Marks a set of nodes returned by TopologicalSorter.get_ready() as processed, unblocking any successor of each node in nodes for being returned in the future by a call to TopologicalSorter.get_ready().

Raises ValueError if any node in nodes has already been marked as processed by a previous call to this method or if a node was not added to the graph by using TopologicalSorter.add(), if called without calling prepare() or if node has not yet been returned by get_ready().

get_ready()

Returns a tuple with all the nodes that are ready. Initially it returns all nodes with no predecessors, and once those are marked as processed by calling TopologicalSorter.done(), further calls will return all new nodes that have all their predecessors already processed. Once no more progress can be made, empty tuples are returned.

前もって prepare() を呼び出さずにこの関数を呼び出すと ValueError を送出します。

static_order()

Returns an iterator object which will iterate over nodes in a topological order. When using this method, prepare() and done() should not be called. This method is equivalent to:

def static_order(self):
    self.prepare()
    while self.is_active():
        node_group = self.get_ready()
        yield from node_group
        self.done(*node_group)

The particular order that is returned may depend on the specific order in which the items were inserted in the graph. For 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]

This is due to the fact that "0" and "2" are in the same level in the graph (they would have been returned in the same call to get_ready()) and the order between them is determined by the order of insertion.

If any cycle is detected, CycleError will be raised.

Added in version 3.9.

例外

graphlib モジュールは以下の例外クラスを定義します:

exception graphlib.CycleError

Subclass of ValueError raised by TopologicalSorter.prepare() if cycles exist in the working graph. If multiple cycles exist, only one undefined choice among them will be reported and included in the exception.

The detected cycle can be accessed via the second element in the args attribute of the exception instance and consists in a list of nodes, such that each node is, in the graph, an immediate predecessor of the next node in the list. In the reported list, the first and the last node will be the same, to make it clear that it is cyclic.

数値と数学モジュール

この章で記述されているモジュールは、数値に関するあるいは数学関係の関数とデータ型を提供します。 numbers モジュールは、数値の型の抽象的な階層を定義します。 math と cmath モジュールは、浮動小数点数と複素数のための様々な数学関数を含んでいます。 decimal モジュールは、任意精度の計算を使用して、10進数の正確な表現をサポートします。

この章では以下のモジュールが記述されています:

numbers --- Numeric abstract base classes

数値塔

型実装者のための注意事項

さらに数のABCを追加する

算術演算の実装

math --- Mathematical functions

数論および数表現の関数

指数関数と対数関数

三角関数

角度変換

双曲線関数

特殊関数

定数

cmath --- Mathematical functions for complex numbers

極座標変換

指数関数と対数関数

三角関数

双曲線関数

類別関数

定数

decimal --- Decimal fixed point and floating point arithmetic

クイックスタートチュートリアル

Decimal オブジェクト

論理引数

Context オブジェクト

定数

丸めモード

シグナル

浮動小数点数に関する注意

精度を上げて丸め誤差を抑制する

特殊値

スレッドを使った処理

レシピ

Decimal FAQ

fractions --- Rational numbers

random --- Generate pseudo-random numbers

保守 (bookkeeping) 関数

バイト列用の関数

整数用の関数

シーケンス用の関数

Discrete distributions

実数分布

他の生成器

再現性について

使用例

レシピ

statistics --- Mathematical statistics functions

平均及び中心位置の測度

分散の測度

2入力間の関係の統計

関数の詳細

例外

NormalDist オブジェクト

例とレシピ

Classic probability problems

Monte Carlo inputs for simulations

Approximating binomial distributions

Naive bayesian classifier

Kernel density estimation

numbers --- Numeric abstract base classes

ソースコード: Lib/numbers.py [https://github.com/python/cpython/tree/3.12/Lib/numbers.py]

The numbers module (PEP 3141 [https://peps.python.org/pep-3141/]) defines a hierarchy of numeric abstract base classes which progressively define more operations. None of the types defined in this module are intended to be instantiated.

class numbers.Number

数の階層の根。引数 x が、種類は何であれ、数であるということだけチェックしたい場合、isinstance(x, Number) が使えます。

数値塔

class numbers.Complex

この型のサブクラスは複素数を表し、組み込みの complex 型を受け付ける演算を含みます。それらは: complex および bool への変換、 real, imag, +, -, *, /, **, abs(), conjugate(), ==, != です。 - と != 以外の全てのものは抽象メソッドや抽象プロパティです。

real

抽象プロパティ。この数の実部を取り出します。

imag

抽象プロパティ。この数の虚部を取り出します。

abstractmethod conjugate()

抽象プロパティ。複素共役を返します。たとえば、(1+3j).conjugate() == (1-3j) です。

class numbers.Real

To Complex, Real adds the operations that work on real numbers.

簡潔に言うとそれらは: float への変換, math.trunc(), round(), math.floor(), math.ceil(), divmod(), //, %, <, <=, > および >= です。

Real はまた complex(), real, imag および conjugate() のデフォルトを提供します。

class numbers.Rational

Real をサブタイプ化し numerator と denominator のプロパティを加えたものです。これは float() のデフォルトも提供します。

The numerator and denominator values should be instances of Integral and should be in lowest terms with denominator positive.

numerator

抽象プロパティ。

denominator

抽象プロパティ。

class numbers.Integral

Rational をサブタイプ化し int への変換が加わります。 float(), numerator, denominator のデフォルトを提供します。法 (訳注: 割る数、除数のこと) を持つ pow() に対する抽象メソッドと、ビット列演算 <<, >>, &, ^, |, ~ を追加します。

型実装者のための注意事項

実装する人は等しい数が等しく扱われるように同じハッシュを与えるように気を付けねばなりません。これは二つの異なった実数の拡張があるような場合にはややこしいことになるかもしれません。たとえば、 fractions.Fraction は hash() を以下のように実装しています:

def __hash__(self):
    if self.denominator == 1:
        # Get integers right.
        return hash(self.numerator)
    # Expensive check, but definitely correct.
    if self == float(self):
        return hash(float(self))
    else:
        # Use tuple's hash to avoid a high collision rate on
        # simple fractions.
        return hash((self.numerator, self.denominator))

さらに数のABCを追加する

数に対する ABC が他にも多く存在しうることは、言うまでもありません。それらの ABC を階層に追加する可能性が閉ざされるとしたら、その階層は貧相な階層でしかありません。たとえば、 MyFoo を Complex と Real の間に付け加えるには、次のようにします:

class MyFoo(Complex): ...
MyFoo.register(Real)

算術演算の実装

We want to implement the arithmetic operations so that mixed-mode operations either call an implementation whose author knew about the types of both arguments, or convert both to the nearest built in type and do the operation there. For subtypes of Integral, this means that __add__() and __radd__() should be defined as:

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

ここには5つの異なる Complex のサブクラス間の混在型の演算があります。上のコードの中で MyIntegral と OtherTypeIKnowAbout に触れない部分を "ボイラープレート" と呼ぶことにしましょう。 a を Complex のサブタイプである A のインスタンス (a : A <: Complex)、同様に b : B <: Complex として、 a + b を考えます:

If A defines an __add__() which accepts b, all is well.

If A falls back to the boilerplate code, and it were to return a value from __add__(), we'd miss the possibility that B defines a more intelligent __radd__(), so the boilerplate should return NotImplemented from __add__(). (Or A may not implement __add__() at all.)

Then B's __radd__() gets a chance. If it accepts a, all is well.

ここでボイラープレートに落ち込むならば、もう他に試すべきメソッドはありませんので、デフォルト実装の出番です。

もし B <: A ならば、Python は A.__add__ の前に B.__radd__ を試します。これで良い理由は、 A についての知識を持って実装しており、 Complex に委ねる前にこれらのインスタンスを扱えるはずだからです。

If A <: Complex and B <: Real without sharing any other knowledge, then the appropriate shared operation is the one involving the built in complex, and both __radd__() s land there, so a+b == b+a.

ほとんどの演算はどのような型についても非常に良く似ていますので、与えられた演算子について順結合(forward)および逆結合(reverse)のメソッドを生成する支援関数を定義することは役に立ちます。たとえば、 fractions.Fraction では次のようなものを利用しています:

def _operator_fallbacks(monomorphic_operator, fallback_operator):
    def forward(a, b):
        if isinstance(b, (int, Fraction)):
            return monomorphic_operator(a, b)
        elif isinstance(b, float):
            return fallback_operator(float(a), b)
        elif isinstance(b, complex):
            return fallback_operator(complex(a), b)
        else:
            return NotImplemented
    forward.__name__ = '__' + fallback_operator.__name__ + '__'
    forward.__doc__ = monomorphic_operator.__doc__

    def reverse(b, a):
        if isinstance(a, Rational):
            # Includes ints.
            return monomorphic_operator(a, b)
        elif isinstance(a, Real):
            return fallback_operator(float(a), float(b))
        elif isinstance(a, Complex):
            return fallback_operator(complex(a), complex(b))
        else:
            return NotImplemented
    reverse.__name__ = '__r' + fallback_operator.__name__ + '__'
    reverse.__doc__ = monomorphic_operator.__doc__

    return forward, reverse

def _add(a, b):
    """a + b"""
    return Fraction(a.numerator * b.denominator +
                    b.numerator * a.denominator,
                    a.denominator * b.denominator)

__add__, __radd__ = _operator_fallbacks(_add, operator.add)

# ...

math --- Mathematical functions

このモジュールは、 C 標準で定義された数学関数へのアクセスを提供します。

これらの関数で複素数を使うことはできません。複素数に対応する必要があるならば、 cmath モジュールにある同じ名前の関数を使ってください。ほとんどのユーザーは複素数を理解するのに必要なだけの数学を勉強したくないので、複素数に対応した関数と対応していない関数の区別がされています。これらの関数では複素数が利用できないため、引数に複素数を渡されると、複素数の結果が返るのではなく例外が発生します。その結果、どういった理由で例外が送出されたかに早い段階で気づく事ができます。

このモジュールでは次の関数を提供しています。明示的な注記のない限り、戻り値は全て浮動小数点数になります。

数論および数表現の関数

math.ceil(x)

x の「天井」 (x 以上の最小の整数) を返します。 x が浮動小数点数でなければ、内部的に x.__ceil__ が実行され、 Integral 値が返されます。

math.comb(n, k)

n 個の中から k 個を重複無く順序をつけずに選ぶ方法の数を返します。

k <= n のとき n! / (k! * (n - k)!) と評価し、k > n のとき 0 と評価します。

これは (1 + x)ⁿ の多項式展開における第 k 項の係数と等しいので、二項係数とも呼ばれます。

いずれかの引数が整数でないなら TypeError を送出します。いずれかの引数が負であれば ValueError を送出します。

Added in version 3.8.

math.copysign(x, y)

x の大きさ (絶対値) で y と同じ符号の浮動小数点数を返します。符号付きのゼロをサポートしているプラットフォームでは、copysign(1.0, -0.0) は -1.0 を返します。

math.fabs(x)

x の絶対値を返します。

math.factorial(n)

n の階乗を整数で返します。n が整数でないか、負の数の場合は、 ValueError を送出します。

バージョン 3.9 で非推奨: Accepting floats with integral values (like 5.0) is deprecated.

math.floor(x)

x の「床」 (x 以下の最大の整数) を返します。 x が浮動小数点数でなければ、内部的に x.__floor__ が実行され、 Integral 値が返されます。

math.fmod(x, y)

プラットフォームの C ライブラリで定義されている fmod(x, y) を返します。 Python の x % y という式は必ずしも同じ結果を返さないということに注意してください。 C 標準の要求では、 fmod(x, y) は厳密に (数学的に、つまり無限の精度で) x - n*y と等価であるよう求めています。n は結果が x と同じ符号と abs(y) より小さい絶対値を持つようなある整数です。Python の x % y は、 y と同じ符号の結果を返し、浮動小数点の引数に対して厳密な解を出せないことがあります。例えば、 fmod(-1e-100, 1e100) は -1e-100 ですが、 Python の -1e-100 % 1e100 は 1e100-1e-100 になり、浮動小数点型で厳密に表現できず、ややこしいことに 1e100 に丸められます。このため、一般には浮動小数点の場合には関数 fmod() 、整数の場合には x % y を使う方がよいでしょう。

math.frexp(x)

x の仮数と指数を (m, e) のペアとして返します。m はfloat型で、e は厳密に x == m * 2**e であるような整数型です。x がゼロの場合は、(0.0, 0) を返し、それ以外の場合は、0.5 <= abs(m) < 1 です。これは浮動小数点型の内部表現を可搬性を保ったまま "分解 (pick apart)" するために使われます。

math.fsum(iterable)

Return an accurate floating point sum of values in the iterable. Avoids loss of precision by tracking multiple intermediate partial sums.

アルゴリズムの正確性は、 IEEE-754 演算の保証と、丸めモードが偶数丸め (half-even) である典型的な場合に依存します。Windows 以外のいくつかのビルドでは、下層の C ライブラリが拡張精度の加算を行い、時々計算途中の和を double 型へ丸めてしまうため、最下位ビットが消失することがあります。

For further discussion and two alternative approaches, see the ASPN cookbook recipes for accurate floating point summation [https://code.activestate.com/recipes/393090-binary-floating-point-summation-accurate-to-full-p/].

math.gcd(*integers)

指定された整数引数の最大公約数を返します。0 でない引数があれば、返される値は全ての引数の約数である最大の正の整数です。全ての引数が 0 なら、返される値は 0 です。引数の無い gcd() は 0 を返します。

Added in version 3.5.

バージョン 3.9 で変更: 任意の数の引数のサポートが追加されました。以前は、二つの引数のみがサポートされていました。

math.isclose(a, b, *, rel_tol=1e-09, abs_tol=0.0)

値 a と b が互いに近い場合 True を、そうでない場合は False を返します。

2値が近いと見なされるかどうかは与えられた絶対または相対許容差により決定されます。

rel_tol は相対許容差、すなわち a と b の絶対値の大きい方に対する a と b の許容される最大の差です。例えば許容差を 5% に設定する場合 rel_tol=0.05 を渡します。デフォルトの許容差は 1e-09 で、2値が9桁同じことを保証します。 rel_tol は0より大きくなければなりません。

abs_tol は最小の絶対許容差です。0に近い値を比較するのに有用です。abs_tol は0以上でなければなりません。

エラーが起こらなければ結果は abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol) です。

IEEE 754 特殊値 NaN、inf、-inf は IEEE の規則に従って処理されます。具体的には、NaN は自身を含めたあらゆる値に近いとは見なされません。 inf と -inf は自身とのみ近いと見なされます。

Added in version 3.5.

参考

PEP 485 [https://peps.python.org/pep-0485/] -- A function for testing approximate equality

math.isfinite(x)

x が無限でも NaN でもない場合に True を返します。それ以外の時には False を返します。 (注意: 0.0 は有限数と扱われます。)

Added in version 3.2.

math.isinf(x)

x が正ないし負の無限数ならば True を返します。それ以外の時には False を返します。

math.isnan(x)

x がNaN (not a number、非数) の時に True を返します。それ以外の場合には False を返します。

math.isqrt(n)

非負整数 n の整数平方根を返します。これは n の正確な平方根の床であり、 a² ≤ n を満たす最大の整数 a と等価です。

少し応用すれば、n ≤ a² を満たす最小の整数 a 、言い換えれば n の正確な平方根の天井を効率的に得られます。正の n に対して、これは a = 1 + isqrt(n - 1) を使って計算できます。

Added in version 3.8.

math.lcm(*integers)

指定された整数引数の最小公倍数を返します。全ての引数が 0 でなければ、返される値は全ての引数の倍数である最小の正の整数です。引数に 0 があれば、返される値は 0 です。引数の無い lcm() は 1 を返します。

Added in version 3.9.

math.ldexp(x, i)

x * (2**i) を返します。これは本質的に frexp() の逆関数です。

math.modf(x)

x の小数部分と整数部分を返します。両方の結果は x の符号を受け継ぎます。整数部はfloat型で返されます。

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.

例:

math.nextafter(x, math.inf) goes up: towards positive infinity.

math.nextafter(x, -math.inf) goes down: towards minus infinity.

math.nextafter(x, 0.0) は 0 に近づきます。

math.nextafter(x, math.copysign(math.inf, x)) は 0 から遠ざかります。

math.ulp() を参照してください。

Added in version 3.9.

バージョン 3.12 で変更: Added the steps argument.

math.perm(n, k=None)

n 個の中から k 個を重複無く順序をつけて選ぶ方法の数を返します。

k <= n のとき n! / (n - k)! と評価し、k > n のとき 0 と評価します。

If k is not specified or is None, then k defaults to n and the function returns n!.

いずれかの引数が整数でないなら TypeError を送出します。いずれかの引数が負であれば ValueError を送出します。

Added in version 3.8.

math.prod(iterable, *, start=1)

入力 iterable の全ての要素の積を計算します。積のデフォルト start 値は 1 です。

イテラブルが空のとき、初期値を返します。この関数は特に数値に使うことを意図されており、非数値を受け付けないことがあります。

Added in version 3.8.

math.remainder(x, y)

IEEE 754 標準方式の x を y で割った剰余を返します。有限な x と有限な y では、分数 x / y の厳密な値に最も近い整数を n として、 x - n*y がこの返り値となります。 x / y が隣り合う 2 つの整数のちょうど真ん中だった場合は、最も近い 偶数 が n として使われます。従って、剰余 r = remainder(x, y) は常に abs(r) <= 0.5 * abs(y) を満たします。

特殊なケースについては IEEE 754 に従います: 任意の有限な x に対する remainder(x, math.inf) 、および任意の非 NaN の x に対する remainder(x, 0) と remainder(math.inf, x) は ValueError を送出します。剰余演算の結果がゼロの場合、そのゼロは x と同じ符号を持ちます。

IEEE 754 の二進浮動小数点数を使用しているプラットフォームでは、この演算の結果は常に厳密に表現可能です。丸め誤差は発生しません。

Added in version 3.7.

math.sumprod(p, q)

Return the sum of products of values from two iterables p and q.

Raises ValueError if the inputs do not have the same length.

およそ次と等価です:

sum(itertools.starmap(operator.mul, zip(p, q, strict=True)))

For float and mixed int/float inputs, the intermediate products and sums are computed with extended precision.

Added in version 3.12.

math.trunc(x)

x の小数部を取り除き、残った整数部を返します。これは 0 に向かって丸められます: trunc() は正の x に対しては floor() に等しく、負の x に対しては ceil() に等しいです。x が浮動小数点数でなければ、内部的に x.__trunc__ が実行され、 Integral 値が返されます。

math.ulp(x)

浮動小数点数 x の最下位ビットの値を返します:

x が NaN (非数) なら、x を返します。

x が負なら、ulp(-x) を返します。

x が正の無限大なら、x を返します。

x が 0 に等しければ、(最小の正の 正規化 浮動小数点数 sys.float_info.min よりも小さい) 最小の正の表現可能な 非正規化 浮動小数点数を返します。

x が表現可能な最大の正の浮動小数点数に等しいなら、x より小さい最初の浮動小数点数が x - ulp(x) であるような、x の最下位ビットの値を返します。

それ以外 (x が正の有限な数) なら、x より大きい最初の浮動小数点数が x + ulp(x) であるような、x の最下位ビットの値を返します。

ULP は "Unit in the Last Place" の略です。

math.nextafter() および sys.float_info.epsilon も参照してください。

Added in version 3.9.

frexp() と modf() は C のものとは異なった呼び出し/返しパターンを持っていることに注意してください。引数を1つだけ受け取り、1組のペアになった値を返すので、2つ目の戻り値を '出力用の引数' 経由で返したりはしません (Python には出力用の引数はありません)。

ceil() 、 floor() 、および modf() 関数については、非常に大きな浮動小数点数が 全て 整数そのものになるということに注意してください。通常、Python の浮動小数点型は 53 ビット以上の精度をもたない (プラットフォームにおける C double 型と同じ) ので、結果的に abs(x) >= 2**52 であるような浮動小数点型 x は小数部分を持たなくなるのです。

指数関数と対数関数

math.cbrt(x)

x の立方根を返します。

Added in version 3.11.

math.exp(x)

e = 2.718281... を自然対数の底として、 e の x 乗を返します。この値は、通常は math.e ** x や pow(math.e, x) よりも精度が高いです。

math.exp2(x)

2 の x 乗を返します。

Added in version 3.11.

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 exp(x) - 1 can result in a significant loss of precision [https://en.wikipedia.org/wiki/Loss_of_significance]; the expm1() function provides a way to compute this quantity to full precision:

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

Added in version 3.2.

math.log(x[, base])

引数が1つの場合、x の (e を底とする)自然対数を返します。

引数が2つの場合、log(x)/log(base) として求められる base を底とした x の対数を返します。

math.log1p(x)

1+x の自然対数(つまり底 e の対数)を返します。結果はゼロに近い x に対して正確になるような方法で計算されます。

math.log2(x)

2を底とする x の対数を返します。この関数は、一般に log(x, 2) よりも正確な値を返します。

Added in version 3.3.

参考

int.bit_length() は、その整数を二進法で表すのに何ビット必要かを返す関数です。符号と先頭のゼロは無視されます。

math.log10(x)

x の10を底とした対数(常用対数)を返します。この関数は通常、log(x, 10) よりも高精度です。

math.pow(x, y)

x の y 乗を返します。例外的な場合については、 IEEE 754 標準に可能な限り従います。特に、 pow(1.0, x) と pow(x, 0.0) は、たとえ x が零や NaN でも、常に 1.0 を返します。もし x と y の両方が有限の値で、 x が負、 y が整数でない場合、 pow(x, y) は未定義で、 ValueError を送出します。

組み込みの ** 演算子と違って、 math.pow() は両方の引数を float 型に変換します。正確な整数の冪乗を計算するには ** もしくは組み込みの pow() 関数を使ってください。

バージョン 3.11 で変更: IEEE 754 との一貫性のため、特殊な例である pow(0.0, -inf) および pow(-0.0, -inf) は ValueError を送出する代わりに inf を返すように変更されました。

math.sqrt(x)

x の平方根を返します。

三角関数

math.acos(x)

x の逆余弦を、ラジアンで返します。結果は 0 と pi の間です。

math.asin(x)

x の逆正弦を、ラジアンで返します。結果は -pi/2 と pi/2 の間です。

math.atan(x)

x の逆正接を、ラジアンで返します。結果は -pi/2 と pi/2 の間です。

math.atan2(y, x)

atan(y / x) を、ラジアンで返します。戻り値は -pi から pi の間になります。この角度は、極座標平面において原点から (x, y) へのベクトルが X 軸の正の方向となす角です。 atan2() のポイントは、両方の入力の符号が既知であるために、位相角の正しい象限を計算できることにあります。例えば、 atan(1) と atan2(1, 1) はいずれも pi/4 ですが、 atan2(-1, -1) は -3*pi/4 になります。

math.cos(x)

x ラジアンの余弦を返します。

math.dist(p, q)

それぞれ座標のシーケンス (またはイテラブル) として与えられる点 p と q の間のユークリッド距離を返します。二点の次元は同じでなければなりません。

およそ次と等価です:

sqrt(sum((px - qx) ** 2.0 for px, qx in zip(p, q)))

Added in version 3.8.

math.hypot(*coordinates)

ユークリッドノルム sqrt(sum(x**2 for x in coordinates)) を返します。これは原点から座標で与えられる点までのベクトルの長さです。

二次元の点 (x, y) では、これは直角三角形の斜辺をピタゴラスの定理 sqrt(x*x + y*y) を用いて計算することと等価です。

バージョン 3.8 で変更: n 次元の点のサポートが追加されました。以前は、二次元の場合しかサポートされていませんでした。

バージョン 3.10 で変更: アルゴリズムの精度を改良し、最大の誤差が 1 ulp (最終桁単位) 未満になりました。より一般的には、結果はほとんどの場合に 1/2 ulp 以内に正しく丸められます。

math.sin(x)

x ラジアンの正弦を返します。

math.tan(x)

x ラジアンの正接を返します。

角度変換

math.degrees(x)

角 x をラジアンから度に変換します。

math.radians(x)

角 x を度からラジアンに変換します。

双曲線関数

Hyperbolic functions [https://en.wikipedia.org/wiki/Hyperbolic_functions] are analogs of trigonometric functions that are based on hyperbolas instead of circles.

math.acosh(x)

x の逆双曲線余弦を返します。

math.asinh(x)

x の逆双曲線正弦を返します。

math.atanh(x)

x の逆双曲線正接を返します。

math.cosh(x)

x の双曲線余弦を返します。

math.sinh(x)

x の双曲線正弦を返します。

math.tanh(x)

x の双曲線正接を返します。

特殊関数

math.erf(x)

x の 誤差関数 [https://ja.wikipedia.org/wiki/%E8%AA%A4%E5%B7%AE%E9%96%A2%E6%95%B0] を返します。

The erf() function can be used to compute traditional statistical functions such as the cumulative standard normal distribution [https://en.wikipedia.org/wiki/Cumulative_distribution_function]:

def phi(x):
    'Cumulative distribution function for the standard normal distribution'
    return (1.0 + erf(x / sqrt(2.0))) / 2.0

Added in version 3.2.

math.erfc(x)

x の相補誤差関数を返します。相補誤差関数 [https://ja.wikipedia.org/wiki/%E8%AA%A4%E5%B7%AE%E9%96%A2%E6%95%B0] は 1.0 - erf(x) と定義されます。この関数は、1からの引き算が 桁落ち [https://ja.wikipedia.org/wiki/%E8%AA%A4%E5%B7%AE#.E6.A1.81.E8.90.BD.E3.81.A1] をするような大きな x に対し使われます。

Added in version 3.2.

math.gamma(x)

x の ガンマ関数 [https://ja.wikipedia.org/wiki/%E3%82%AC%E3%83%B3%E3%83%9E%E9%96%A2%E6%95%B0] を返します。

Added in version 3.2.

math.lgamma(x)

x のガンマ関数の絶対値の自然対数を返します。

Added in version 3.2.

定数

math.pi

利用可能なだけの精度の数学定数 π = 3.141592... (円周率)。

math.e

利用可能なだけの精度の数学定数 e = 2.718281... (自然対数の底)。

math.tau

利用可能なだけの精度の数学定数 τ = 6.283185... です。タウは 2π に等しい円定数で、円周と半径の比です。タウについて学ぶには Vi Hart のビデオ Pi is (still) Wrong [https://www.youtube.com/watch?v=jG7vhMMXagQ] をチェックして、パイを二倍食べて Tau day [https://tauday.com/] を祝い始めましょう！

Added in version 3.6.

math.inf

浮動小数の正の無限大です。(負の無限大には -math.inf を使います。) float('inf') の出力と等価です。

Added in version 3.5.

math.nan

A floating-point "not a number" (NaN) value. Equivalent to the output of float('nan'). Due to the requirements of the IEEE-754 standard [https://en.wikipedia.org/wiki/IEEE_754], math.nan and float('nan') are not considered to equal to any other numeric value, including themselves. To check whether a number is a NaN, use the isnan() function to test for NaNs instead of is or ==. Example:

>>> import math
>>> math.nan == math.nan
False
>>> float('nan') == float('nan')
False
>>> math.isnan(math.nan)
True
>>> math.isnan(float('nan'))
True

Added in version 3.5.

バージョン 3.11 で変更: 常に利用出来るようになりました。

CPython 実装の詳細: math モジュールは、ほとんどが実行プラットフォームにおける C 言語の数学ライブラリ関数に対する薄いラッパでできています。例外時の挙動は、適切である限り C99 標準の Annex F に従います。現在の実装では、sqrt(-1.0) や log(0.0) といった (C99 Annex F で不正な演算やゼロ除算を通知することが推奨されている) 不正な操作に対して ValueError を送出し、(例えば exp(1000.0) のような) 演算結果がオーバーフローする場合には OverflowError を送出します。上記の関数群は、1つ以上の引数が NaN であった場合を除いて NaN を返しません。引数に NaN が与えられた場合は、殆どの関数は NaN を返しますが、 (C99 Annex F に従って) 別の動作をする場合があります。例えば、 pow(float('nan'), 0.0) や hypot(float('nan'), float('inf')) といった場合です。訳注: 例外が発生せずに結果が返ると、計算結果がおかしくなった原因が複素数を渡したためだということに気づくのが遅れる可能性があります。

Python は signaling NaN と quiet NaN を区別せず、signaling NaN に対する挙動は未定義とされていることに注意してください。典型的な挙動は、全ての NaN を quiet NaN として扱うことです。

参考

cmath モジュール

これらの多くの関数の複素数版。

cmath --- Mathematical functions for complex numbers

このモジュールは、複素数を扱う数学関数へのアクセスを提供しています。このモジュール中の関数は整数、浮動小数点数または複素数を引数にとります。また、 __complex__() または __float__() どちらかのメソッドを提供している Python オブジェクトも受け付けます。これらのメソッドはそのオブジェクトを複素数または浮動小数点数に変換するのにそれぞれ使われ、呼び出された関数はそうして変換された結果を利用します。

注釈

For functions involving branch cuts, we have the problem of deciding how to define those functions on the cut itself. Following Kahan's "Branch cuts for complex elementary functions" paper, as well as Annex G of C99 and later C standards, we use the sign of zero to distinguish one side of the branch cut from the other: for a branch cut along (a portion of) the real axis we look at the sign of the imaginary part, while for a branch cut along the imaginary axis we look at the sign of the real part.

For example, the cmath.sqrt() function has a branch cut along the negative real axis. An argument of complex(-2.0, -0.0) is treated as though it lies below the branch cut, and so gives a result on the negative imaginary axis:

>>> cmath.sqrt(complex(-2.0, -0.0))
-1.4142135623730951j

But an argument of complex(-2.0, 0.0) is treated as though it lies above the branch cut:

>>> cmath.sqrt(complex(-2.0, 0.0))
1.4142135623730951j

極座標変換

Python の複素数 z は内部的には 直交座標 もしくは デカルト座標 と呼ばれる座標を使って格納されています。この座標はその複素数の 実部 z.real と 虚部 z.imag で決まります。言い換えると:

z == z.real + z.imag*1j

極座標 は複素数を表現する別の方法です。極座標では、複素数 z は半径 r と位相角 phi で定義されます。半径 r は z から原点までの距離です。位相 phi は x 軸の正の部分から原点と z を結んだ線分までの角度を反時計回りにラジアンで測った値です。

次の関数はネイティブの直交座標を極座標に変換したりその逆を行うのに使えます。

cmath.phase(x)

x の位相 (x の 偏角 とも呼びます) を浮動小数点数で返します。phase(x) は math.atan2(x.imag, x.real) と同等です。返り値は [-π, π] の範囲にあり、この演算の分枝切断は負の実軸に沿って延びています。結果の符号は x.imag がゼロであってさえ x.imag の符号と等しくなります:

>>> phase(complex(-1.0, 0.0))
3.141592653589793
>>> phase(complex(-1.0, -0.0))
-3.141592653589793

注釈

複素数 x のモジュラス (絶対値) は組み込みの abs() 関数で計算できます。この演算を行う cmath モジュールの関数はありません。

cmath.polar(x)

x の極座標表現を返します。x の半径 r と x の位相 phi の組 (r, phi) を返します。polar(x) は (abs(x), phase(x)) に等しいです。

cmath.rect(r, phi)

極座標 r, phi を持つ複素数 x を返します。値は r * (math.cos(phi) + math.sin(phi)*1j) に等しいです。

指数関数と対数関数

cmath.exp(x)

e を自然対数の底として、 e の x 乗を返します。

cmath.log(x[, base])

base を底とする x の対数を返します。もし base が指定されていない場合には、x の自然対数を返します。分枝切断を一つもち、0 から負の実数軸に沿って -∞ へと延びています。

cmath.log10(x)

x の底を 10 とする対数を返します。 log() と同じ分枝切断を持ちます。

cmath.sqrt(x)

x の平方根を返します。 log() と同じ分枝切断を持ちます。

三角関数

cmath.acos(x)

x の逆余弦を返します。この関数には二つの分枝切断 (branch cut) があります: 一つは 1 から右側に実数軸に沿って∞へと延びています。もう一つは -1 から左側に実数軸に沿って -∞へと延びています。

cmath.asin(x)

x の逆正弦を返します。 acos() と同じ分枝切断を持ちます。

cmath.atan(x)

x の逆正接を返します。二つの分枝切断があります: 一つは 1j から虚数軸に沿って ∞j へと延びています。もう一つは -1j から虚数軸に沿って -∞j へと延びています。

cmath.cos(x)

x の余弦を返します。

cmath.sin(x)

x の正弦を返します。

cmath.tan(x)

x の正接を返します。

双曲線関数

cmath.acosh(x)

x の逆双曲線余弦を返します。分枝切断が一つあり、1 の左側に実数軸に沿って -∞へと延びています。

cmath.asinh(x)

x の逆双曲線正弦を返します。二つの分枝切断があります: 一つは 1j から虚数軸に沿って ∞j へと延びています。もう一つは -1j から虚数軸に沿って -∞j へと延びています。

cmath.atanh(x)

x の逆双曲線正接を返します。二つの分枝切断があります: 一つは 1 から実数軸に沿って ∞ へと延びています。もう一つは -1 から実数軸に沿って -∞ へと延びています。

cmath.cosh(x)

x の双曲線余弦を返します。

cmath.sinh(x)

x の双曲線正弦を返します。

cmath.tanh(x)

x の双曲線正接を返します。

類別関数

cmath.isfinite(x)

x の実部、虚部ともに有限であれば True を返し、それ以外の場合 False を返します。

Added in version 3.2.

cmath.isinf(x)

x の実数部または虚数部が正または負の無限大であれば True を、そうでなければ False を返します。

cmath.isnan(x)

x の実部と虚部のどちらかが NaN のとき True を返し、それ以外の場合 False を返します。

cmath.isclose(a, b, *, rel_tol=1e-09, abs_tol=0.0)

値 a と b が互いに近い場合 True を、そうでない場合は False を返します。

2値が近いと見なされるかどうかは与えられた絶対または相対許容差により決定されます。

rel_tol は相対許容差、すなわち a と b の絶対値の大きい方に対する a と b の許容される最大の差です。例えば許容差を 5% に設定する場合 rel_tol=0.05 を渡します。デフォルトの許容差は 1e-09 で、2値が9桁同じことを保証します。 rel_tol は0より大きくなければなりません。

abs_tol は最小の絶対許容差です。0に近い値を比較するのに有用です。abs_tol は0以上でなければなりません。

エラーが起こらなければ結果は abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol) です。

IEEE 754 特殊値 NaN、inf、-inf は IEEE の規則に従って処理されます。具体的には、NaN は自身を含めたあらゆる値に近いとは見なされません。 inf と -inf は自身とのみ近いと見なされます。

Added in version 3.5.

参考

PEP 485 [https://peps.python.org/pep-0485/] -- 近似的に等しいことを調べる関数

定数

cmath.pi

定数 π (円周率)で、浮動小数点数です。

cmath.e

定数 e (自然対数の底)で、浮動小数点数です。

cmath.tau

数学定数 τ で、浮動小数点数です。

Added in version 3.6.

cmath.inf

浮動小数点数の正の無限大です。float('inf') と等価です。

Added in version 3.6.

cmath.infj

実部がゼロ、虚部が正の無限大の複素数です。complex(0.0, float('inf')) と等価です。

Added in version 3.6.

cmath.nan

浮動小数点数の非数 "not a number" (NaN) です。float('nan') と等価です。

Added in version 3.6.

cmath.nanj

実部がゼロ、虚部が NaN の複素数です。complex(0.0, float('nan')) と等価です。

Added in version 3.6.

math と同じような関数が選ばれていますが、全く同じではないので注意してください。機能を二つのモジュールに分けているのは、複素数に興味がなかったり、もしかすると複素数とは何かすら知らないようなユーザがいるからです。そういった人たちはむしろ、 math.sqrt(-1) が複素数を返すよりも例外を送出してほしいと考えます。また、 cmath で定義されている関数は、たとえ結果が実数で表現可能な場合 (虚数部がゼロの複素数) でも、常に複素数を返すので注意してください。

分枝切断 (branch cut) に関する注釈: 分枝切断を持つ曲線上では、与えられた関数は連続ではなくなります。これらは多くの複素関数における必然的な特性です。複素関数を計算する必要がある場合、これらの分枝に関して理解しているものと仮定しています。悟りに至るために何らかの (到底基礎的とはいえない) 複素数に関する書をひもといてください。数値計算を目的とした分枝切断の正しい選択方法についての情報としては、以下がよい参考文献となります:

参考

Kahan, W: Branch cuts for complex elementary functions; or, Much ado about nothings's sign bit. In Iserles, A., and Powell, M. (eds.), The state of the art in numerical analysis. Clarendon Press (1987) pp165--211.

decimal --- Decimal fixed point and floating point arithmetic

ソースコード: Lib/decimal.py [https://github.com/python/cpython/tree/3.12/Lib/decimal.py]

decimal モジュールは正確に丸められた十進浮動小数点算術をサポートします。 decimal には、 float データ型に比べて、以下のような利点があります:

「(Decimal は) 人々を念頭にデザインされた浮動小数点モデルを元にしており、必然的に最も重要な指針があります -- コンピュータは人々が学校で習った算術と同じように動作する算術を提供しなければならない」 -- 十進数演算仕様より。

十進数を正確に表現できます。 1.1 や 2.2 のような数は、二進数の浮動小数点型では正しく表現できません。エンドユーザは普通、 二進数における 1.1 + 2.2 の近似値が 3.3000000000000003 だからといって、そのように表示してほしいとは考えないものです。

値の正確さは算術にも及びます。十進の浮動小数点による計算では、 0.1 + 0.1 + 0.1 - 0.3 は厳密にゼロに等しくなります。 二進浮動小数点では 5.5511151231257827e-017 になってしまいます。ゼロに近い値とはいえ、この誤差は数値間の等価性テストの信頼性を阻害します。また、誤差が蓄積されることもあります。こうした理由から、数値間の等価性を厳しく保たなければならないようなアプリケーションを考えるなら、十進数による数値表現が望ましいということになります。

decimal モジュールでは、有効桁数の表記が取り入れられており、例えば 1.30 + 1.20 は 2.50 になります。すなわち、末尾のゼロは有効数字を示すために残されます。こうした仕様は通貨計算を行うアプリケーションでは慣例です。乗算の場合、「教科書的な」アプローチでは、乗算の被演算子すべての桁数を使います。例えば、 1.3 * 1.2 は 1.56 になり、 1.30 * 1.20 は 1.5600 になります。

ハードウェアによる 2 進浮動小数点表現と違い、decimal モジュールでは計算精度をユーザが変更できます(デフォルトでは 28 桁です)。この桁数はほとんどの問題解決に十分な大きさです:

>>> from decimal import *
>>> getcontext().prec = 6
>>> Decimal(1) / Decimal(7)
Decimal('0.142857')
>>> getcontext().prec = 28
>>> Decimal(1) / Decimal(7)
Decimal('0.1428571428571428571428571429')

二進と十進の浮動小数点は、いずれも広く公開されている標準仕様のもとに実装されています。組み込みの浮動小数点型では、標準仕様で提唱されている機能のほんのささやかな部分を利用できるにすぎませんが、decimal では標準仕様が要求している全ての機能を利用できます。必要に応じて、プログラマは値の丸めやシグナル処理を完全に制御できます。この中には全ての不正確な操作を例外でブロックして正確な算術を遵守させるオプションもあります。

decimal モジュールは「偏見なく、正確な丸めなしの十進算術(固定小数点算術と呼ばれることもある)と丸めありの浮動小数点数算術」(十進数演算仕様より引用)をサポートするようにデザインされました。

このモジュールは、十進数型、算術コンテキスト (context for arithmetic)、そしてシグナル (signal) という三つの概念を中心に設計されています。

十進数型は変更不能です。これは符号、係数部、そして指数を持ちます。有効桁数を残すために、仮数部の末尾にあるゼロは切り詰められません。 decimal では、 Infinity, -Infinity, および NaN といった特殊な値も定義されています。標準仕様では -0 と +0 も区別します。

算術コンテキストとは、精度や値丸めの規則、指数部の制限を決めている環境です。この環境では、演算結果を表すためのフラグや、演算上発生した特定のシグナルを例外として扱うかどうかを決めるトラップイネーブラも定義しています。丸め規則には ROUND_CEILING, ROUND_DOWN, ROUND_FLOOR, ROUND_HALF_DOWN, ROUND_HALF_EVEN, ROUND_HALF_UP, ROUND_UP, および ROUND_05UP があります。

シグナルとは、演算の過程で生じる例外的条件です。個々のシグナルは、アプリケーションそれぞれの要求に従って、無視されたり、単なる情報とみなされたり、例外として扱われたりします。 decimal モジュールには、 Clamped, InvalidOperation, DivisionByZero, Inexact, Rounded, Subnormal, Overflow, Underflow, および FloatOperation といったシグナルがあります。

各シグナルには、フラグとトラップイネーブラがあります。演算上何らかのシグナルに遭遇すると、フラグは 1 にセットされます。このとき、もしトラップイネーブラが 1 にセットされていれば、例外を送出します。フラグの値は膠着型 (sticky) なので、演算によるフラグの変化をモニタしたければ、予めフラグをリセットしておかなければなりません。

参考

IBM による汎用十進演算仕様、The General Decimal Arithmetic Specification [https://speleotrove.com/decimal/decarith.html]。

クイックスタートチュートリアル

普通、 decimal を使うときには、モジュールをインポートし、現在の演算コンテキストを getcontext() で調べ、必要なら、精度、丸め、有効なトラップを設定します:

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

Decimal インスタンスは、整数、文字列、浮動小数点数、またはタプルから構成できます。整数や浮動小数点数からの構成は、整数や浮動小数点数の値を正確に変換します。 Decimal は "非数 (Not a Number)" を表す NaN や正負の Infinity (無限大)、 -0 といった特殊な値も表現できます:

>>> 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')

FloatOperation シグナルがトラップされる場合、コンストラクタや順序比較において誤って decimal と float が混ざると、例外が送出されます:

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

Added in version 3.3.

新たな Decimal の有効桁数は入力の桁数だけで決まります。演算コンテキストにおける精度や値丸めの設定が影響するのは算術演算の間だけです。

>>> 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')

C バージョンの内部制限を超えた場合、decimal の構成は InvalidOperation を送出します:

>>> Decimal("1e9999999999999999999")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
decimal.InvalidOperation: [<class 'decimal.InvalidOperation'>]

バージョン 3.3 で変更.

decimal はほとんどの場面で Python の他の機能とうまくやりとりできます。decimal 浮動小数点の空飛ぶサーカス (flying circus) をお見せしましょう:

>>> 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')

いくつかの数学的関数も Decimal には用意されています:

>>> 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')

quantize() メソッドは位を固定して数値を丸めます。このメソッドは、結果を固定の桁数で丸めることがよくある、金融アプリケーションで便利です:

>>> Decimal('7.325').quantize(Decimal('.01'), rounding=ROUND_DOWN)
Decimal('7.32')
>>> Decimal('7.325').quantize(Decimal('1.'), rounding=ROUND_UP)
Decimal('8')

前述のように、 getcontext() 関数を使うと現在の演算コンテキストにアクセスでき、設定を変更できます。ほとんどのアプリケーションはこのアプローチで十分です。

より高度な作業を行う場合、 Context() コンストラクタを使って別の演算コンテキストを作っておくと便利なことがあります。別の演算コンテキストをアクティブにしたければ、 setcontext() を使います。

decimal モジュールでは、標準仕様に従って、すぐ利用できる二つの標準コンテキスト、 BasicContext および ExtendedContext を提供しています。前者はほとんどのトラップが有効になっており、とりわけデバッグの際に便利です:

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

演算コンテキストには、演算中に遭遇した例外的状況をモニタするためのシグナルフラグがあります。フラグが一度セットされると、明示的にクリアするまで残り続けます。そのため、フラグのモニタを行いたいような演算の前には clear_flags() メソッドでフラグをクリアしておくのがベストです。

>>> 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=[])

flags エントリから、pi の有理数による近似値が丸められた (コンテキスト内で決められた精度を超えた桁数が捨てられた) ことと、計算結果が厳密でない (無視された桁の値に非ゼロのものがあった) ことがわかります。

コンテキストの traps 属性に入っている辞書を使うと、個々のトラップをセットできます:

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

ほとんどのプログラムでは、開始時に一度だけ現在の演算コンテキストを修正します。また、多くのアプリケーションでは、データから Decimal への変換はループ内で一度だけキャストして行います。コンテキストを設定し、 Decimal オブジェクトを生成できたら、ほとんどのプログラムは他の Python 数値型と全く変わらないかのように Decimal を操作できます。

Decimal オブジェクト

class decimal.Decimal(value='0', context=None)

value に基づいて新たな Decimal オブジェクトを構築します。

value は整数、文字列、タプル、 float および他の Decimal オブジェクトにできます。 value を指定しない場合、 Decimal('0') を返します。 value が文字列の場合、先頭と末尾の空白および全てのアンダースコアを取り除いた後には以下の 10進数文字列の文法に従わなければなりません:

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

他の Unicode 数字も上の digit の場所に使うことができます。つまり各書記体系における(アラビア-インド系やデーヴァナーガリーなど)の数字や、全角数字０('\uff10')から９('\uff19')までなどです。

value を tuple にする場合、タプルは三つの要素を持ち、それぞれ符号 (正なら 0 、負なら 1)、仮数部を表す数字の tuple 、そして指数を表す整数でなければなりません。例えば、 Decimal((0, (1, 4, 1, 4), -3)) は Decimal('1.414') を返します。

value を float にする場合、二進浮動小数点数値が損失なく正確に等価な Decimal に変換されます。この変換はしばしば 53 桁以上の精度を要求します。例えば、 Decimal(float('1.1')) は Decimal('1.100000000000000088817841970012523233890533447265625') に変換されます。

context の精度 (precision) は、記憶される桁数には影響しません。桁数は value に指定した桁数だけから決定されます。例えば、演算コンテキストに指定された精度が 3 桁しかなくても、Decimal('3.00000') は 5 つのゼロを全て記憶します。

context 引数の目的は、 value が正しくない形式の文字列であった場合に行う処理を決めることにあります; 演算コンテキストが InvalidOperation をトラップするようになっていれば、例外を送出します。それ以外の場合には、コンストラクタは値が NaN の Decimal を返します。

一度生成すると、 Decimal オブジェクトは変更不能 (immutable) になります。

バージョン 3.2 で変更: コンストラクタに対する引数に float インスタンスも許されるようになりました。

バージョン 3.3 で変更: FloatOperation トラップがセットされていた場合 float 引数は例外を送出します。デフォルトでトラップはオフです。

バージョン 3.6 で変更: コード中の整数リテラルや浮動小数点リテラルと同様に、アンダースコアを用いて桁をグルーピングできます。

十進浮動小数点オブジェクトは、 float や int のような他の組み込み型と多くの点で似ています。通常の数学演算や特殊メソッドを適用できます。また、 Decimal オブジェクトはコピーでき、pickle 化でき、print で出力でき、辞書のキーにでき、集合の要素にでき、比較、保存、他の型 (float や int) への型強制を行えます。

十進オブジェクトの算術演算と整数や浮動小数点数の算術演算には少々違いがあります。十進オブジェクトに対して剰余演算を適用すると、計算結果の符号は除数の符号ではなく 被除数 の符号と一致します:

>>> (-7) % 4
1
>>> Decimal(-7) % Decimal(4)
Decimal('-3')

整数除算演算子 // も同様に、実際の商の切り捨てではなく (0に近付くように丸めた) 整数部分を返します。そのため通常の恒等式 x == (x // y) * y + x % y が維持されます:

>>> -7 // 4
-2
>>> Decimal(-7) // Decimal(4)
Decimal('-1')

演算子 % と演算子 // は (それぞれ) 仕様にあるような 剰余 操作と 整数除算 操作を実装しています。

Decimal オブジェクトは一般に、算術演算で浮動小数点数や fractions.Fraction オブジェクトと組み合わせることができません。例えば、 Decimal に float を足そうとすると、 TypeError が送出されます。ただし、Python の比較演算子を使って Decimal インスタンス x と別の数 y を比較することができます。これにより、異なる型の数間の等価比較の際に、紛らわしい結果を避けます。

バージョン 3.2 で変更: Decimal インスタンスと他の数値型が混在する比較が完全にサポートされるようになりました。

こうした標準的な数値型の特性の他に、十進浮動小数点オブジェクトには様々な特殊メソッドがあります:

adjusted()

仮数の先頭の一桁だけが残るように右側の数字を追い出す桁シフトを行い、その結果の指数部を返します: Decimal('321e+5').adjusted() は 7 を返します。最上桁の小数点からの相対位置を調べる際に使います。

as_integer_ratio()

与えられた Decimal インスタンスを、既約分数で分母が正数の分数として表現した整数のペア (n, d) を返します。

>>> Decimal('-3.14').as_integer_ratio()
(-157, 50)

変換は正確に行われます。無限大に対してはOverflowErrorを、NaNに対してはValueError を送出します。

Added in version 3.6.

as_tuple()

数値を表現するための 名前付きタプル: DecimalTuple(sign, digittuple, exponent) を返します。

canonical()

引数の標準的(canonical)エンコーディングを返します。現在のところ、 Decimal インスタンスのエンコーディングは常に標準的なので、この操作は引数に手を加えずに返します。

compare(other, context=None)

二つの Decimal インスタンスの値を比較します。 compare() は Decimal インスタンスを返し、被演算子のどちらかが NaN ならば結果は NaN です:

a or b is a NaN  ==> Decimal('NaN')
a < b            ==> Decimal('-1')
a == b           ==> Decimal('0')
a > b            ==> Decimal('1')

compare_signal(other, context=None)

この演算は compare() とほとんど同じですが、全ての NaN がシグナルを送るところが異なります。すなわち、どちらの比較対象も発信 (signaling) NaN でないならば無言 (quiet) NaN である比較対象があたかも発信 NaN であるかのように扱われます。

compare_total(other, context=None)

二つの対象を数値によらず抽象表現によって比較します。 compare() に似ていますが、結果は Decimal に全順序を与えます。この順序づけによると、数値的に等しくても異なった表現を持つ二つの Decimal インスタンスの比較は等しくなりません:

>>> Decimal('12.0').compare_total(Decimal('12'))
Decimal('-1')

無言 NaN と発信 NaN もこの全順序に位置付けられます。この関数の結果は、もし比較対象が同じ表現を持つならば Decimal('0') であり、一つめの比較対象が二つめより下位にあれば Decimal('-1')、上位にあれば Decimal('1') です。全順序の詳細については仕様を参照してください。

この演算はコンテキストに影響されず、静かです。すなわち、フラグは変更されず、丸めは行われません。例外として、2番目の比較対象の厳密な変換ができない場合、C バージョンのライブラリでは InvalidOperation 例外を送出するかもしれません。

compare_total_mag(other, context=None)

二つの対象を compare_total() のように数値によらず抽象表現によって比較しますが、両者の符号を無視します。 x.compare_total_mag(y) は x.copy_abs().compare_total(y.copy_abs()) と等価です。

この演算はコンテキストに影響されず、静かです。すなわち、フラグは変更されず、丸めは行われません。例外として、2番目の比較対象の厳密な変換ができない場合、C バージョンのライブラリでは InvalidOperation 例外を送出するかもしれません。

conjugate()

self を返すだけです。このメソッドは十進演算仕様に適合するためだけのものです。

copy_abs()

引数の絶対値を返します。この演算はコンテキストに影響されず、静かです。すなわち、フラグは変更されず、丸めは行われません。

copy_negate()

引数の符号を変えて返します。この演算はコンテキストに影響されず、静かです。すなわち、フラグは変更されず、丸めは行われません。

copy_sign(other, context=None)

最初の演算対象のコピーに二つめと同じ符号を付けて返します。たとえば:

>>> Decimal('2.3').copy_sign(Decimal('-1.5'))
Decimal('-2.3')

この演算はコンテキストに影響されず、静かです。すなわち、フラグは変更されず、丸めは行われません。例外として、2番目の比較対象の厳密な変換ができない場合、C バージョンのライブラリでは InvalidOperation 例外を送出するかもしれません。

exp(context=None)

与えられた数での(自然)指数関数 e**x の値を返します。結果は ROUND_HALF_EVEN 丸めモードで正しく丸められます。

>>> Decimal(1).exp()
Decimal('2.718281828459045235360287471')
>>> Decimal(321).exp()
Decimal('2.561702493119680037517373933E+139')

classmethod from_float(f)

Alternative constructor that only accepts instances of float or int.

なお、Decimal.from_float(0.1) は Decimal('0.1') と同じではありません。0.1 は二進浮動小数点数で正確に表せないので、その値は表現できる最も近い値、0x1.999999999999ap-4 として記憶されます。浮動小数点数での等価な値は 0.1000000000000000055511151231257827021181583404541015625 です。

注釈

Python 3.2 以降では、 Decimal インスタンスは float から直接構成できるようになりました。

>>> 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')

Added in version 3.1.

fma(other, third, context=None)

融合積和(fused multiply-add)です。self*other+third を途中結果の積 self*other で丸めを行わずに計算して返します。

>>> Decimal(2).fma(3, 5)
Decimal('11')

is_canonical()

引数が標準的(canonical)ならば True を返し、そうでなければ False を返します。現在のところ、 Decimal のインスタンスは常に標準的なのでこのメソッドの結果はいつでも True です。

is_finite()

引数が有限の数値ならば True を、無限大か NaN ならば False を返します。

is_infinite()

引数が正または負の無限大ならば True を、そうでなければ False を返します。

is_nan()

引数が (無言か発信かは問わず) NaN であれば True を、そうでなければ False を返します。

is_normal(context=None)

引数が 正規(normal) の有限数値ならば True を返します。引数がゼロ、非正規(subnormal)、無限大または NaN であれば False を返します。

is_qnan()

引数が無言 NaN であれば True を、そうでなければ False を返します。

is_signed()

引数に負の符号がついていれば True を、そうでなければ False を返します。注意すべきはゼロや NaN なども符号を持ち得ることです。

is_snan()

引数が発信 NaN であれば True を、そうでなければ False を返します。

is_subnormal(context=None)

引数が非正規数(subnormal)であれば True を、そうでなければ False を返します。

is_zero()

引数が(正または負の)ゼロであれば True を、そうでなければ False を返します。

ln(context=None)

演算対象の自然対数(底 e の対数)を返します。結果は ROUND_HALF_EVEN 丸めモードで正しく丸められます。

log10(context=None)

演算対象の底 10 の対数を返します。結果は ROUND_HALF_EVEN 丸めモードで正しく丸められます。

logb(context=None)

非零の数値については、 Decimal インスタンスとして調整された指数を返します。演算対象がゼロだった場合、 Decimal('-Infinity') が返され DivisionByZero フラグが送出されます。演算対象が無限大だった場合、 Decimal('Infinity') が返されます。

logical_and(other, context=None)

logical_and() は二つの 論理引数 (論理引数 参照)を取る論理演算です。結果は二つの引数の数字ごとの and です。

logical_invert(context=None)

logical_invert() は論理演算です。結果は引数の数字ごとの反転です。

logical_or(other, context=None)

logical_or() は二つの 論理引数 (論理引数 参照)を取る論理演算です。結果は二つの引数の数字ごとの or です。

logical_xor(other, context=None)

logical_xor() は二つの 論理引数 (論理引数 参照)を取る論理演算です。結果は二つの引数の数字ごとの排他的論理和です。

max(other, context=None)

max(self, other) と同じですが、値を返す前に現在のコンテキストに即した丸め規則を適用します。また、 NaN に対して、(コンテキストの設定と、発信か無言どちらのタイプであるかに応じて) シグナルを発行するか無視します。

max_mag(other, context=None)

max() メソッドに似ていますが、比較は絶対値で行われます。

min(other, context=None)

min(self, other) と同じですが、値を返す前に現在のコンテキストに即した丸め規則を適用します。また、 NaN に対して、(コンテキストの設定と、発信か無言どちらのタイプであるかに応じて) シグナルを発行するか無視します。

min_mag(other, context=None)

min() メソッドに似ていますが、比較は絶対値で行われます。

next_minus(context=None)

与えられたコンテキスト(またはコンテキストが渡されなければ現スレッドのコンテキスト)において表現可能な、操作対象より小さい最大の数を返します。

next_plus(context=None)

与えられたコンテキスト(またはコンテキストが渡されなければ現スレッドのコンテキスト)において表現可能な、操作対象より大きい最小の数を返します。

next_toward(other, context=None)

二つの比較対象が等しくなければ、一つめの対象に最も近く二つめの対象へ近付く方向の数を返します。もし両者が数値的に等しければ、二つめの対象の符号を採った一つめの対象のコピーを返します。

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, Decimal('32.100') and Decimal('0.321000e+2') both normalize to the equivalent value 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 reduce.

number_class(context=None)

操作対象の クラス を表す文字列を返します。返されるのは以下の10種類のいずれかです。

"-Infinity", 負の無限大であることを示します。

"-Normal", 負の通常数であることを示します。

"-Subnormal", 負の非正規数であることを示します。

"-Zero", 負のゼロであることを示します。

"+Zero", 正のゼロであることを示します。

"+Subnormal", 正の非正規数であることを示します。

"+Normal", 正の通常数であることを示します。

"+Infinity", 正の無限大であることを示します。

"NaN", 無言 (quiet) NaN (Not a Number) であることを示します。

"sNaN", 発信(signaling) NaN であることを示します。

quantize(exp, rounding=None, context=None)

二つ目の操作対象と同じ指数を持つように丸めを行った、一つめの操作対象と等しい値を返します。

>>> Decimal('1.41421356').quantize(Decimal('1.000'))
Decimal('1.414')

他の操作と違い、打ち切り(quantize)操作後の係数の長さが精度を越えた場合には、 InvalidOperation がシグナルされます。これによりエラー条件がない限り打ち切られた指数が常に右側の引数と同じになることが保証されます。

同様に、他の操作と違い、quantize は Underflow を、たとえ結果が非正規になったり不正確になったとしても、シグナルしません。

二つ目の演算対象の指数が一つ目のそれよりも大きければ丸めが必要かもしれません。この場合、丸めモードは以下のように決められます。rounding 引数が与えられていればそれが使われます。そうでなければ context 引数で決まります。どちらの引数も渡されなければ現在のスレッドのコンテキストの丸めモードが使われます。

処理結果の指数が Emax よりも大きい場合や Etiny() よりも小さい場合にエラーが返されます。

radix()

Decimal(10) つまり Decimal クラスがその全ての算術を実行する基数を返します。仕様との互換性のために取り入れられています。

remainder_near(other, context=None)

self を other で割った剰余を返します。これは self % other とは違って、剰余の絶対値を小さくするように符号が選ばれます。より詳しく言うと、n を self / other の正確な値に最も近い整数としたときの self - n * other が返り値になります。最も近い整数が2つある場合には偶数のものが選ばれます。

結果が0になる場合の符号は self の符号と同じになります。

>>> Decimal(18).remainder_near(Decimal(10))
Decimal('-2')
>>> Decimal(25).remainder_near(Decimal(10))
Decimal('5')
>>> Decimal(35).remainder_near(Decimal(10))
Decimal('-5')

rotate(other, context=None)

一つ目の演算対象の数字を二つ目で指定された量だけ巡回(rotate)した結果を返します。二つめの演算対象は -precision から precision までの範囲の整数でなければなりません。この二つ目の演算対象の絶対値を何桁ずらすかを決めます。そしてもし正の数ならば巡回の方向は左に、そうでなければ右になります。一つ目の演算対象の仮数部は必要ならば精度いっぱいまでゼロで埋められます。符号と指数は変えられません。

same_quantum(other, context=None)

self と other が同じ指数を持っているか、あるいは双方とも NaN である場合に真を返します。

この演算はコンテキストに影響されず、静かです。すなわち、フラグは変更されず、丸めは行われません。例外として、2番目の比較対象の厳密な変換ができない場合、C バージョンのライブラリでは InvalidOperation 例外を送出するかもしれません。

scaleb(other, context=None)

二つ目の演算対象で調整された指数の一つ目の演算対象を返します。同じことですが、一つめの演算対象を 10**other 倍したものを返します。二つ目の演算対象は整数でなければなりません。

shift(other, context=None)

一つ目の演算対象の数字を二つ目で指定された量だけシフトした結果を返します。二つ目の演算対象は -precision から precision までの範囲の整数でなければなりません。この二つ目の演算対象の絶対値が何桁ずらすかを決めます。そしてもし正の数ならばシフトの方向は左に、そうでなければ右になります。一つ目の演算対象の係数は必要ならば精度いっぱいまでゼロで埋められます。符号と指数は変えられません。

sqrt(context=None)

引数の平方根を最大精度で求めます。

to_eng_string(context=None)

文字列に変換します。指数が必要なら工学表記が使われます。

工学表記法では指数は 3 の倍数になります。これにより、基数の小数部には最大で 3 桁までの数字が残されるとともに、末尾に 1 つまたは 2 つの 0 の付加が必要とされるかもしれません。

たとえば、Decimal('123E+1') は Decimal('1.23E+3') に変換されます。

to_integral(rounding=None, context=None)

to_integral_value() メソッドと同じです。to_integral の名前は古いバージョンとの互換性のために残されています。

to_integral_exact(rounding=None, context=None)

最近傍の整数に値を丸め、丸めが起こった場合には Inexact または Rounded のシグナルを適切に出します。丸めモードは以下のように決められます。 rounding 引数が与えられていればそれが使われます。そうでなければ context 引数で決まります。どちらの引数も渡されなければ現在のスレッドのコンテキストの丸めモードが使われます。

to_integral_value(rounding=None, context=None)

Inexact や Rounded といったシグナルを出さずに最近傍の整数に値を丸めます。 rounding が指定されていれば適用されます; それ以外の場合、値丸めの方法は context の設定か現在のコンテキストの設定になります。

論理引数

logical_and(), logical_invert(), logical_or(), および logical_xor() メソッドはその引数が 論理引数 であると想定しています。 論理引数 とは Decimal インスタンスで指数と符号は共にゼロであり、各桁の数字が 0 か 1 であるものです。

Context オブジェクト

コンテキスト (context) とは、算術演算における環境設定です。コンテキストは計算精度を決定し、値丸めの方法を設定し、シグナルのどれが例外になるかを決め、指数の範囲を制限しています。

多重スレッドで処理を行う場合には各スレッドごとに現在のコンテキストがあり、 getcontext() や setcontext() といった関数でアクセスしたり設定変更できます:

decimal.getcontext()

アクティブなスレッドの現在のコンテキストを返します。

decimal.setcontext(c)

アクティブなスレッドのコンテキストを c に設定します。

with 文と localcontext() 関数を使って実行するコンテキストを一時的に変更することもできます。

decimal.localcontext(ctx=None, **kwargs)

with 文の入口でアクティブなスレッドのコンテキストを ctx のコピーに設定し、with 文を抜ける時に元のコンテキストに復旧する、コンテキストマネージャを返します。コンテキストが指定されなければ、現在のコンテキストのコピーが使われます。kwargs 引数は新しいコンテキストの属性を設定するのに使われます。

たとえば、以下のコードでは精度を42桁に設定し、計算を実行し、そして元のコンテキストに復帰します:

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

Using keyword arguments, the code would be the following:

from decimal import localcontext

with localcontext(prec=42) as ctx:
    s = calculate_something()
s = +s

Raises TypeError if kwargs supplies an attribute that Context doesn't support. Raises either TypeError or ValueError if kwargs supplies an invalid value for an attribute.

バージョン 3.11 で変更: localcontext() now supports setting context attributes through the use of keyword arguments.

新たなコンテキストは、以下で説明する Context コンストラクタを使って生成できます。その他にも、 decimal モジュールでは作成済みのコンテキストを提供しています:

class decimal.BasicContext

汎用十進演算仕様で定義されている標準コンテキストの一つです。精度は 9 桁に設定されています。丸め規則は ROUND_HALF_UP です。すべての演算結果フラグはクリアされています。 Inexact, Rounded, Subnormal を除く全ての演算エラートラップが有効 (例外として扱う) になっています。

多くのトラップが有効になっているので、デバッグの際に便利なコンテキストです。

class decimal.ExtendedContext

汎用十進演算仕様で定義されている標準コンテキストの一つです。精度は 9 桁に設定されています。丸め規則は ROUND_HALF_EVEN です。すべての演算結果フラグはクリアされています。トラップは全て無効(演算中に一切例外を送出しない) になっています。

トラップが無効になっているので、エラーの伴う演算結果を NaN や Infinity にし、例外を送出しないようにしたいアプリケーションに向いたコンテキストです。このコンテキストを使うと、他の場合にはプログラムが停止してしまうような状況があっても実行を完了させられます。

class decimal.DefaultContext

Context コンストラクタが新たなコンテキストを作成するさいに雛形にするコンテキストです。このコンテキストのフィールド (精度の設定など) を変更すると、 Context コンストラクタが生成する新たなコンテキストに影響を及ぼします。

このコンテキストは、主に多重スレッド環境で便利です。スレッドを開始する前に何らかのフィールドを変更しておくと、システム全体のデフォルト設定に効果を及ぼすことができます。スレッドを開始した後にフィールドを変更すると、競合条件を抑制するためにスレッドを同期化しなければならないので、推奨しません。

単一スレッドの環境では、このコンテキストを使わないよう薦めます。下で述べるように明示的にコンテキストを作成してください。

デフォルトの値は、 Context.prec=28, Context.rounding=ROUND_HALF_EVEN で、トラップ Overflow, InvalidOperation, および DivisionByZero が有効になっています。

上に挙げた三つのコンテキストに加え、 Context コンストラクタを使って新たなコンテキストを生成できます。

class decimal.Context(prec=None, rounding=None, Emin=None, Emax=None, capitals=None, clamp=None, flags=None, traps=None)

新たなコンテキストを生成します。あるフィールドが定義されていないか None であれば、 DefaultContext からデフォルト値をコピーします。 flags フィールドが設定されていいか None の場合には、全てのフラグがクリアされます。

prec フィールドは範囲 [1, MAX_PREC] 内の整数で、コンテキストにおける算術演算の計算精度を設定します。

rounding オプションは、節 丸めモード で挙げられる定数の一つです。

traps および flags フィールドには、セットしたいシグナルを列挙します。一般的に、新たなコンテキストを作成するときにはトラップだけを設定し、フラグはクリアしておきます。

Emin および Emax フィールドは、許容する指数の外限を指定する整数です。 Emin は範囲 [MIN_EMIN, 0] 内で、 Emax は範囲 [0, MAX_EMAX] 内でなければなりません。

capitals フィールドは 0 または 1 (デフォルト) にします。 1 に設定すると、指数記号を大文字 E で出力します。それ以外の場合には Decimal('6.02e+23') のように小文字の e を使います。

clamp フィールドは、 0 (デフォルト) または 1 です。 1 に設定されると、このコンテキストにおける Decimal インスタンスの指数 e は厳密に範囲 Emin - prec + 1 <= e <= Emax - prec + 1 に制限されます。 clamp が 0 なら、それより弱い条件が支配します: 調整された Decimal インスタンスの指数は最大で Emax です。 clamp が 1 なら、大きな正規数は、可能なら、指数が減らされ、対応する数の 0 が係数に加えられ、指数の制約に合わせられます; これは数の値を保存しますが、有効な末尾の 0 に関する情報を失います。例えば:

>>> Context(prec=6, Emax=999, clamp=1).create_decimal('1.23e999')
Decimal('1.23000E+999')

clamp の値 1 は、IEEE 754 で規定された固定幅十進交換形式と互換にできます。

Context クラスでは、いくつかの汎用のメソッドの他、現在のコンテキストで算術演算を直接行うためのメソッドを数多く定義しています。加えて、 Decimal の各メソッドについて(adjusted() および as_tuple() メソッドを例外として)対応する Context のメソッドが存在します。たとえば、 Context インスタンス C と Decimal インスタンス x に対して、 C.exp(x) は x.exp(context=C) と等価です。それぞれの Context メソッドは、Decimal インスタンスが受け付けられるところならどこでも、Python の整数 (int のインスタンス) を受け付けます。

clear_flags()

フラグを全て 0 にリセットします。

clear_traps()

トラップを全て 0 にリセットします。

Added in version 3.3.

copy()

コンテキストの複製を返します。

copy_decimal(num)

Decimal インスタンス num のコピーを返します。

create_decimal(num)

self をコンテキストとする新たな Decimal インスタンスを num から生成します。 Decimal コンストラクタと違い、数値を変換する際にコンテキストの精度、値丸め方法、フラグ、トラップを適用します。

定数値はしばしばアプリケーションの要求よりも高い精度を持っているため、このメソッドが役に立ちます。また、値丸めを即座に行うため、例えば以下のように、入力値に値丸めを行わないために合計値にゼロの加算を追加するだけで結果が変わってしまうといった、現在の精度よりも細かい値の影響が紛れ込む問題を防げるという恩恵もあります。以下の例は、丸められていない入力を使うということは和にゼロを加えると結果が変わり得るという見本です:

>>> getcontext().prec = 3
>>> Decimal('3.4445') + Decimal('1.0023')
Decimal('4.45')
>>> Decimal('3.4445') + Decimal(0) + Decimal('1.0023')
Decimal('4.44')

このメソッドは IBM 仕様の to-number 演算を実装したものです。引数が文字列の場合、前や後ろに余計な空白を付けたり、アンダースコアを含めたりすることは許されません。

create_decimal_from_float(f)

浮動小数点数 f から新しい Decimal インスタンスを生成しますが、 self をコンテキストとして丸めます。 Decimal.from_float() クラスメソッドとは違い、変換にコンテキストの精度、丸めメソッド、フラグ、そしてトラップが適用されます。

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

Added in version 3.1.

Etiny()

Emin - prec + 1 に等しい値を返します。演算結果の劣化が起こる桁の最小値です。アンダーフローが起きた場合、指数は Etiny に設定されます。

Etop()

Emax - prec + 1 に等しい値を返します。

Decimal を使った処理を行う場合、通常は Decimal インスタンスを生成して、算術演算を適用するというアプローチをとります。演算はアクティブなスレッドにおける現在のコンテキストの下で行われます。もう一つのアプローチは、コンテキストのメソッドを使った特定のコンテキスト下での計算です。コンテキストのメソッドは Decimal クラスのメソッドに似ているので、ここでは簡単な説明にとどめます。

abs(x)

x の絶対値を返します。

add(x, y)

x と y の和を返します。

canonical(x)

同じ Decimal オブジェクト x を返します。

compare(x, y)

x と y を数値として比較します。

compare_signal(x, y)

二つの演算対象の値を数値として比較します。

compare_total(x, y)

二つの演算対象を抽象的な表現を使って比較します。

compare_total_mag(x, y)

二つの演算対象を抽象的な表現を使い符号を無視して比較します。

copy_abs(x)

x のコピーの符号を 0 にセットして返します。

copy_negate(x)

x のコピーの符号を反転して返します。

copy_sign(x, y)

y から x に符号をコピーします。

divide(x, y)

x を y で除算した値を返します。

divide_int(x, y)

x を y で除算した値を整数に切り捨てて返します。

divmod(x, y)

二つの数値間の除算を行い、結果の整数部を返します。

exp(x)

e ** x を返します。

fma(x, y, z)

x を y 倍したものに z を加えて返します。

is_canonical(x)

x が標準的(canonical)ならば True を返します。そうでなければ False です。

is_finite(x)

x が有限ならば True を返します。そうでなければ False です。

is_infinite(x)

x が無限ならば True を返します。そうでなければ False です。

is_nan(x)

x が qNaN か sNaN であれば True を返します。そうでなければ False です。

is_normal(x)

x が通常の数ならば True を返します。そうでなければ False です。

is_qnan(x)

x が無言 NaN であれば True を返します。そうでなければ False です。

is_signed(x)

x が負の数であれば True を返します。そうでなければ False です。

is_snan(x)

x が発信 NaN であれば True を返します。そうでなければ False です。

is_subnormal(x)

x が非正規数であれば True を返します。そうでなければ False です。

is_zero(x)

x がゼロであれば True を返します。そうでなければ False です。

ln(x)

x の自然対数(底 e の対数)を返します。

log10(x)

x の底 10 の対数を返します。

logb(x)

演算対象の MSD の大きさの指数部を返します。

logical_and(x, y)

それぞれの桁に論理演算 and を当てはめます。

logical_invert(x)

x の全ての桁を反転させます。

logical_or(x, y)

それぞれの桁に論理演算 or を当てはめます。

logical_xor(x, y)

それぞれの桁に論理演算 xor を当てはめます。

max(x, y)

二つの値を数値として比較し、大きいほうを返します。

max_mag(x, y)

値を符号を無視して数値として比較します。

min(x, y)

二つの値を数値として比較し、小さいほうを返します。

min_mag(x, y)

値を符号を無視して数値として比較します。

minus(x)

Python における単項マイナス演算子に対応する演算です。

multiply(x, y)

x と y の積を返します。

next_minus(x)

x より小さい最大の表現可能な数を返します。

next_plus(x)

x より大きい最小の表現可能な数を返します。

next_toward(x, y)

x に y の方向に向かって最も近い数を返します。

normalize(x)

x をもっとも単純な形にします。

number_class(x)

x のクラスを指し示すものを返します。

plus(x)

Python における単項のプラス演算子に対応する演算です。コンテキストにおける精度や値丸めを適用するので、等値 (identity) 演算とは 違います。

power(x, y, modulo=None)

x の y 乗を計算します。modulo が指定されていればモジュロを取ります。

引数が 2 つの場合、 x**y を計算します。x が負の場合、 y は整数でなければなりません。y が整数、結果が有限、結果が 'precision' 桁で正確に表現できる、という条件をすべて満たさない場合、結果は不正確になります。結果はコンテキストの丸めモードを使って丸められます。結果は常に、Python バージョンにおいて正しく丸められます。

Decimal(0) ** Decimal(0) results in InvalidOperation, and if InvalidOperation is not trapped, then results in Decimal('NaN').

バージョン 3.3 で変更: C モジュールは power() を適切に丸められた exp() および ln() 関数によって計算します。結果は well-defined ですが、「ほとんどの場合には適切に丸められる」だけです。

引数が 3 つの場合、 (x**y) % modulo を計算します。この 3 引数の形式の場合、引数には以下の制限が課せられます。

全ての引数は整数

y は非負でなければならない

x と y の少なくともどちらかはゼロでない

modulo は非零で大きくても 'precision' 桁

Context.power(x, y, modulo) で得られる値は (x**y) % modulo を精度無制限で計算して得られるものと同じ値ですが、より効率的に計算されます。結果の指数は x, y, modulo の指数に関係なくゼロです。この計算は常に正確です。

quantize(x, y)

x に値丸めを適用し、指数を y にした値を返します。

radix()

単に 10 を返します。何せ十進ですから :)

remainder(x, y)

整数除算の剰余を返します。

剰余がゼロでない場合、符号は割られる数の符号と同じになります。

remainder_near(x, y)

x - y * n を返します。ここで n は x / y の正確な値に一番近い整数です (この結果が 0 ならばその符号は x の符号と同じです)。

rotate(x, y)

x の y 回巡回したコピーを返します。

same_quantum(x, y)

2つの演算対象が同じ指数を持っている場合に True を返します。

scaleb(x, y)

一つめの演算対象の指数部に二つめの値を加えたものを返します。

shift(x, y)

x を y 回シフトしたコピーを返します。

sqrt(x)

x の平方根を精度いっぱいまで求めます。

subtract(x, y)

x と y の間の差を返します。

to_eng_string(x)

文字列に変換します。指数が必要なら工学表記が使われます。

工学表記法では指数は 3 の倍数になります。これにより、基数の小数部には最大で 3 桁までの数字が残されるとともに、末尾に 1 つまたは 2 つの 0 の付加が必要とされるかもしれません。

to_integral_exact(x)

最近傍の整数に値を丸めます。

to_sci_string(x)

数値を科学表記で文字列に変換します。

定数

この節の定数は C モジュールにのみ意味があります。互換性のために、pure Python 版も含まれます。

32-bit

64-bit

decimal.MAX_PREC

425000000

999999999999999999

decimal.MAX_EMAX

425000000

999999999999999999

decimal.MIN_EMIN

-425000000

-999999999999999999

decimal.MIN_ETINY

-849999999

-1999999999999999997

decimal.HAVE_THREADS

値は True です。現在のPythonは常にスレッドを持っているので、非推奨になりました。

バージョン 3.9 で非推奨.

decimal.HAVE_CONTEXTVAR

The default value is True. If Python is configured using the --without-decimal-contextvar option, the C version uses a thread-local rather than a coroutine-local context and the value is False. This is slightly faster in some nested context scenarios.

Added in version 3.8.3.

丸めモード

decimal.ROUND_CEILING

Infinity 方向に丸めます。

decimal.ROUND_DOWN

ゼロ方向に丸めます。

decimal.ROUND_FLOOR

-Infinity 方向に丸めます。

decimal.ROUND_HALF_DOWN

近い方に、引き分けはゼロ方向に向けて丸めます。

decimal.ROUND_HALF_EVEN

近い方に、引き分けは偶数整数方向に向けて丸めます。

decimal.ROUND_HALF_UP

近い方に、引き分けはゼロから遠い方向に向けて丸めます。

decimal.ROUND_UP

ゼロから遠い方向に丸めます。

decimal.ROUND_05UP

ゼロ方向に丸めた後の最後の桁が 0 または 5 ならばゼロから遠い方向に、そうでなければゼロ方向に丸めます。

シグナル

シグナルは、計算中に生じた様々なエラー条件を表現します。各々のシグナルは一つのコンテキストフラグと一つのトラップイネーブラに対応しています。

コンテキストフラグは、該当するエラー条件に遭遇するたびにセットされます。演算後にフラグを調べれば、演算に関する情報 (例えば計算が厳密だったかどうか) がわかります。フラグを調べたら、次の計算を始める前にフラグを全てクリアするようにしてください。

あるコンテキストのトラップイネーブラがあるシグナルに対してセットされている場合、該当するエラー条件が生じると Python の例外を送出します。例えば、 DivisionByZero が設定されていると、エラー条件が生じた際に DivisionByZero 例外を送出します。

class decimal.Clamped

値の表現上の制限に沿わせるために指数部が変更されたことを通知します。

通常、クランプ (clamp) は、指数部がコンテキストにおける指数桁の制限値 Emin および Emax を越えた場合に発生します。可能な場合には、係数部にゼロを加えた表現に合わせて指数部を減らします。

class decimal.DecimalException

他のシグナルの基底クラスで、 ArithmeticError のサブクラスです。

class decimal.DivisionByZero

有限値をゼロで除算したときのシグナルです。

除算やモジュロ除算、数を負の値で累乗した場合に起きることがあります。このシグナルをトラップしない場合、演算結果は Infinity または -Infinity になり、その符号は演算に使った入力に基づいて決まります。

class decimal.Inexact

値の丸めによって演算結果から厳密さが失われたことを通知します。

このシグナルは値丸め操作中にゼロでない桁を無視した際に生じます。演算結果は値丸め後の値です。シグナルのフラグやトラップは、演算結果の厳密さが失われたことを検出するために使えるだけです。

class decimal.InvalidOperation

無効な演算が実行されたことを通知します。

ユーザが有意な演算結果にならないような操作を要求したことを示します。このシグナルをトラップしない場合、 NaN を返します。このシグナルの発生原因として考えられるのは、以下のような状況です:

Infinity - Infinity
0 * Infinity
Infinity / Infinity
x % 0
Infinity % x
sqrt(-x) and x > 0
0 ** 0
x ** (non-integer)
x ** Infinity

class decimal.Overflow

数値オーバフローを示すシグナルです。

このシグナルは、値丸めを行った後の指数部が Context.Emax より大きいことを示します。シグナルをトラップしない場合、演算結果は値丸めのモードにより、表現可能な最大の数値になるように内側へ引き込んで丸めを行った値か、 Infinity になるように外側に丸めた値のいずれかになります。いずれの場合も、 Inexact および Rounded が同時にシグナルされます。

class decimal.Rounded

情報が全く失われていない場合も含み、値丸めが起きたときのシグナルです。

このシグナルは、値丸めによって桁がなくなると常に発生します。なくなった桁がゼロ (例えば 5.00 を丸めて 5.0 になった場合) であってもです。このシグナルをトラップしなければ、演算結果をそのまま返します。このシグナルは有効桁数の減少を検出する際に使います。

class decimal.Subnormal

値丸めを行う前に指数部が Emin より小さかったことを示すシグナルです。

演算結果が微小である場合 (指数が小さすぎる場合) に発生します。このシグナルをトラップしなければ、演算結果をそのまま返します。

class decimal.Underflow

演算結果が値丸めによってゼロになった場合に生じる数値アンダフローです。

演算結果が微小なため、値丸めによってゼロになった場合に発生します。 Inexact および Subnormal シグナルも同時に発生します。

class decimal.FloatOperation

float と Decimal の混合の厳密なセマンティクスを有効にします。

シグナルがトラップされなかった場合 (デフォルト)、Decimal コンストラクタ、 create_decimal() 、およびすべての比較演算子において float と Decimal の混合が許されます。変換も比較も正確です。コンテキストフラグ内に FloatOperation を設定することで、混合操作は現れるたびに暗黙に記録されます。 from_float() や create_decimal_from_float() による明示的な変換はフラグを設定しません。

そうでなければ (シグナルがトラップされれば)、等価性比較および明示的な変換のみが静かにに行われ、その他の混合演算は FloatOperation を送出します。

これらのシグナルの階層構造をまとめると、以下の表のようになります:

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)

浮動小数点数に関する注意

精度を上げて丸め誤差を抑制する

十進浮動小数点数を使うと、十進数表現による誤差を抑制できます (0.1 を正確に表現できるようになります); しかし、ゼロでない桁が一定の精度を越えている場合には、演算によっては依然として値丸めによる誤差を引き起こします。

値丸めによる誤差の影響は、桁落ちを生じるような、ほとんど相殺される量での加算や減算によって増幅されます。Knuth は、十分でない計算精度の下で値丸めを伴う浮動小数点演算を行った結果、加算の結合則や分配則における恒等性が崩れてしまう例を二つ示しています:

# 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')

decimal モジュールでは、最下桁を失わないように十分に計算精度を広げることで、上で問題にしたような恒等性をとりもどせます:

>>> 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')

特殊値

decimal モジュールの数体系では、 NaN, sNaN, -Infinity Infinity, および二つのゼロ、 +0 と -0 といった特殊な値を提供しています。

無限大 (Infinity) は Decimal('Infinity') で直接構築できます。また、 DivisionByZero をトラップせずにゼロで除算を行った場合にも出てきます。同様に、 Overflow シグナルをトラップしなければ、表現可能な最大の数値の制限を越えた値を丸めたときに出てきます。

無限大には符号があり (アフィン: affine であり)、算術演算に使用でき、非常に巨大で不確定の(indeterminate)値として扱われます。例えば、無限大に何らかの定数を加算すると、演算結果は別の無限大になります。

演算によっては結果が不確定になるものがあり、 NaN を返します。ただし、 InvalidOperation シグナルをトラップするようになっていれば例外を送出します。例えば、 0/0 は NaN を返します。 NaN は「非数値 (not a number)」を表します。このような NaN は暗黙のうちに生成され、一度生成されるとそれを他の計算にも流れてゆき、関係する個々の演算全てが個別の NaN を返すようになります。この挙動は、たまに入力値が欠けるような状況で一連の計算を行う際に便利です --- 特定の計算に対しては無効な結果を示すフラグを立てつつ計算を進められるからです。

一方、 NaN の変種である sNaN は関係する全ての演算で演算後にシグナルを送出します。 sNaN は、無効な演算結果に対して特別な処理を行うために計算を停止する必要がある場合に便利です。

Python の比較演算は NaN が関わってくると少し驚くようなことがあります。等価性のテストの一方の対象が無言または発信 NaN である場合いつでも False を返し(たとえ Decimal('NaN')==Decimal('NaN') でも)、一方で不等価をテストするといつでも True を返します。二つの Decimal を <, <=, > または >= を使って比較する試みは一方が NaN である場合には InvalidOperation シグナルを送出し、このシグナルをトラップしなければ結果は False に終わります。汎用十進演算仕様は直接の比較の振る舞いについて定めていないことに注意しておきましょう。ここでの NaN が関係する比較ルールは IEEE 854 標準から持ってきました (section 5.7 の Table 3 を見て下さい)。厳格に標準遵守を貫くなら、 compare() および compare_signal() メソッドを代わりに使いましょう。

アンダフローの起きた計算は、符号付きのゼロ (signed zero) を返すことがあります。符号は、より高い精度で計算を行った結果の符号と同じになります。符号付きゼロの大きさはやはりゼロなので、正のゼロと負のゼロは等しいとみなされ、符号は単なる参考にすぎません。

二つの符号付きゼロが区別されているのに等価であることに加えて、異なる精度におけるゼロの表現はまちまちなのに、値は等価とみなされるということがあります。これに慣れるには多少時間がかかります。正規化浮動小数点表現に目が慣れてしまうと、以下の計算でゼロに等しい値が返っているとは即座に分かりません:

>>> 1 / Decimal('Infinity')
Decimal('0E-1000026')

スレッドを使った処理

関数 getcontext() は、スレッド毎に別々の Context オブジェクトにアクセスします。別のスレッドコンテキストを持つということは、複数のスレッドが互いに影響を及ぼさずに (getcontext().prec=10 のような) 変更を適用できるということです。

同様に、setcontext() 関数は自動的に引数のコンテキストを現在のスレッドのコンテキストに設定します。

getcontext() を呼び出す前に setcontext() が呼び出されていなければ、現在のスレッドで使うための新たなコンテキストを生成するために getcontext() が自動的に呼び出されます。

新たなコンテキストは、DefaultContext と呼ばれる雛形からコピーされます。アプリケーションを通じて全てのスレッドに同じ値を使うようにデフォルトを設定したければ、DefaultContext オブジェクトを直接変更します。 getcontext() を呼び出すスレッド間で競合条件が生じないようにするため、DefaultContext への変更はいかなるスレッドを開始するよりも 前に 行わなければなりません。以下に例を示します:

# 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()
 . . .

レシピ

Decimal クラスの利用を実演している例をいくつか示します。これらはユーティリティ関数としても利用できます:

def moneyfmt(value, places=2, curr='', sep=',', dp='.',
             pos='', neg='-', trailneg=''):
    """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='', neg='', 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 ''.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

Decimal FAQ

Q. decimal.Decimal('1234.5') などと打ち込むのは煩わしいのですが、対話式インタプリタを使う際にタイプ量を少なくする方法はありませんか?

A. コンストラクタを1文字に縮める人もいるようです:

>>> D = decimal.Decimal
>>> D('1.23') + D('3.45')
Decimal('4.68')

Q. 小数点以下2桁の固定小数点数のアプリケーションの中で、いくつかの入力が余計な桁を保持しているのでこれを丸めなければなりません。その他のものに余計な桁はなくそのまま使えます。どのメソッドを使うのがいいでしょうか?

A. quantize() メソッドで固定した桁に丸められます。 Inexact トラップを設定しておけば、確認にも有用です:

>>> TWOPLACES = Decimal(10) ** -2       # same as Decimal('0.01')

>>> # Round to two places
>>> Decimal('3.214').quantize(TWOPLACES)
Decimal('3.21')

>>> # Validate that a number does not exceed two places
>>> Decimal('3.21').quantize(TWOPLACES, context=Context(traps=[Inexact]))
Decimal('3.21')

>>> Decimal('3.214').quantize(TWOPLACES, context=Context(traps=[Inexact]))
Traceback (most recent call last):
   ...
Inexact: None

Q. 正当な2桁の入力が得られたとして、その正当性をアプリケーション実行中も変わらず保ち続けるにはどうすればいいでしょうか?

A. 加減算あるいは整数との乗算のような演算は自動的に固定小数点を守ります。その他の除算や整数以外の乗算などは小数点以下の桁を変えてしまいますので実行後は quantize() ステップが必要です:

>>> 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')

固定小数点のアプリケーションを開発する際は、 quantize() の段階を扱う関数を定義しておくと便利です:

>>> def mul(x, y, fp=TWOPLACES):
...     return (x * y).quantize(fp)
...
>>> def div(x, y, fp=TWOPLACES):
...     return (x / y).quantize(fp)

>>> mul(a, b)                       # Automatically preserve fixed-point
Decimal('325.62')
>>> div(b, a)
Decimal('0.03')

Q. 一つの値に対して多くの表現方法があります。 200 と 200.000 と 2E2 と .02E+4 は全て同じ値で違った精度の数です。これらをただ一つの正規化された値に変換することはできますか?

A. normalize() メソッドは全ての等しい値をただ一つの表現に直します:

>>> 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')]

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:

>>> 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')

Q. ある種の十進数値はいつも指数表記で表示されます。指数表記以外の表示にする方法はありますか?

A. 値によっては、指数表記だけが有効桁数を表せる表記法なのです。たとえば、 5.0E+3 を 5000 と表してしまうと、値は変わりませんが元々の2桁という有効数字が反映されません。

もしアプリケーションが有効数字の追跡を等閑視するならば、指数部や末尾のゼロを取り除き、有効数字を忘れ、しかし値を変えずにおくことは容易です:

>>> def remove_exponent(d):
...     return d.quantize(Decimal(1)) if d == d.to_integral() else d.normalize()

>>> remove_exponent(Decimal('5E+3'))
Decimal('5000')

Q. 普通の float を Decimal に変換できますか?

A. はい。どんな 2 進浮動小数点数も Decimal として正確に表現できます。ただし、正確な変換は直感的に考えたよりも多い桁になることがあります:

>>> Decimal(math.pi)
Decimal('3.141592653589793115997963468544185161590576171875')

Q. 複雑な計算の中で、精度不足や丸めの異常で間違った結果になっていないことをどうやって保証すれば良いでしょうか。

A. decimal モジュールでは検算は容易です。一番良い方法は、大きめの精度や様々な丸めモードで再計算してみることです。大きく異なった結果が出てきたら、精度不足や丸めの問題や悪条件の入力、または数値計算的に不安定なアルゴリズムを示唆しています。

Q. コンテキストの精度は計算結果には適用されていますが入力には適用されていないようです。様々に異なる精度の入力値を混ぜて計算する時に注意すべきことはありますか?

A. はい。原則として入力値は正確であると見做しておりそれらの値を使った計算も同様です。結果だけが丸められます。入力の強みは "what you type is what you get" (打ち込んだ値が得られる値)という点にあります。入力が丸められないということを忘れていると結果が奇妙に見えるというのは弱点です:

>>> getcontext().prec = 3
>>> Decimal('3.104') + Decimal('2.104')
Decimal('5.21')
>>> Decimal('3.104') + Decimal('0.000') + Decimal('2.104')
Decimal('5.20')

解決策は、精度を増やすか、単項プラス演算子を使って入力の丸めを強制することです:

>>> getcontext().prec = 3
>>> +Decimal('1.23456789')      # unary plus triggers rounding
Decimal('1.23')

もしくは、入力を Context.create_decimal() を使って生成時に丸めてしまうこともできます:

>>> Context(prec=5, rounding=ROUND_DOWN).create_decimal('1.2345678')
Decimal('1.2345')

Q. CPython 実装は大きな数に対しても速いでしょうか?

A. はい。CPython 実装と PyPy3 実装では、 C/CFFI 版の decimal モジュールは、任意精度の正しい丸めを行う 10 進浮動小数点演算のための高速な libmpdec [https://www.bytereef.org/mpdecimal/doc/libmpdec/index.html] ライブラリを統合しています。libmpdec は Karatsuba multiplication [https://en.wikipedia.org/wiki/Karatsuba_algorithm] を中程度のサイズの数に対して使い、 Number Theoretic Transform [https://en.wikipedia.org/wiki/Discrete_Fourier_transform_(general)#Number-theoretic_transform] を非常に大きな数に対して使います。

The context must be adapted for exact arbitrary precision arithmetic. Emin and Emax should always be set to the maximum values, clamp should always be 0 (the default). Setting prec requires some care.

The easiest approach for trying out bignum arithmetic is to use the maximum value for prec as well [2]:

>>> setcontext(Context(prec=MAX_PREC, Emax=MAX_EMAX, Emin=MIN_EMIN))
>>> x = Decimal(2) ** 256
>>> x / 128
Decimal('904625697166532776746648320380374280103671755200316906558262375061821325312')

For inexact results, MAX_PREC is far too large on 64-bit platforms and the available memory will be insufficient:

>>> Decimal(1) / 3
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
MemoryError

On systems with overallocation (e.g. Linux), a more sophisticated approach is to adjust 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:

>>> 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'>]

In general (and especially on systems without overallocation), it is recommended to estimate even tighter bounds and set the Inexact trap if all calculations are expected to be exact.

[1]

Added in version 3.3.

[2]

バージョン 3.9 で変更: This approach now works for all exact results except for non-integer powers.

fractions --- Rational numbers

ソースコード: Lib/fractions.py [https://github.com/python/cpython/tree/3.12/Lib/fractions.py]

fractions モジュールは有理数計算のサポートを提供します。

Fraction インスタンスは一対の整数、他の有理数、または文字列から生成されます。

class fractions.Fraction(numerator=0, denominator=1)

class fractions.Fraction(other_fraction)

class fractions.Fraction(float)

class fractions.Fraction(decimal)

class fractions.Fraction(string)

The first version requires that numerator and denominator are instances of numbers.Rational and returns a new Fraction instance with value numerator/denominator. If denominator is 0, it raises a ZeroDivisionError. The second version requires that other_fraction is an instance of numbers.Rational and returns a Fraction instance with the same value. The next two versions accept either a float or a decimal.Decimal instance, and return a Fraction instance with exactly the same value. Note that due to the usual issues with binary floating-point (see 浮動小数点演算、その問題と制限), the argument to Fraction(1.1) is not exactly equal to 11/10, and so Fraction(1.1) does not return Fraction(11, 10) as one might expect. (But see the documentation for the limit_denominator() method below.) The last version of the constructor expects a string or unicode instance. The usual form for this instance is:

[sign] numerator ['/' denominator]

ここで、オプションの sign は '+' か '-' のどちらかであり、numerator および (存在する場合) denominator は十進数の数字の文字列です (コード中の整数リテラルと同様、アンダースコアを使って桁を区切れます)。さらに、 float コンストラクタで受け付けられる有限の値を表す文字列は、Fraction コンストラクタでも受け付けられます。どちらの形式でも、入力される文字列は前後に空白があって構いません。以下に、いくつかの例を示します:

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

Fraction クラスは抽象基底クラス numbers.Rational を継承し、その全てのメソッドと演算を実装します。 Fraction インスタンスは ハッシュ可能 で、不変 (immutable) であるものとして扱われます。加えて、 Fraction には以下のプロパティとメソッドがあります:

バージョン 3.2 で変更: Fraction のコンストラクタが float および decimal.Decimal インスタンスを受け付けるようになりました。

バージョン 3.9 で変更: 今は math.gcd() 関数が 分子 (numerator) と 分母 (denominator) の約分で使われています。 math.gcd() は常に int 型の値を返します。以前は、GCDの型は分子と分母に依存していました。

バージョン 3.11 で変更: Underscores are now permitted when creating a Fraction instance from a string, following PEP 515 [https://peps.python.org/pep-0515/] rules.

バージョン 3.11 で変更: Fraction implements __int__ now to satisfy typing.SupportsInt instance checks.

バージョン 3.12 で変更: Space is allowed around the slash for string inputs: Fraction('2 / 3').

バージョン 3.12 で変更: Fraction instances now support float-style formatting, with presentation types "e", "E", "f", "F", "g", "G" and "%"".

numerator

有理数を既約分数で表したときの分子。

denominator

有理数を既約分数で表したときの分母。

as_integer_ratio()

Return a tuple of two integers, whose ratio is equal to the original Fraction. The ratio is in lowest terms and has a positive denominator.

Added in version 3.8.

is_integer()

Return True if the Fraction is an integer.

Added in version 3.12.

classmethod from_float(flt)

Alternative constructor which only accepts instances of float or numbers.Integral. Beware that Fraction.from_float(0.3) is not the same value as Fraction(3, 10).

注釈

Python 3.2 以降では、 float から直接 Fraction インスタンスを構築できるようになりました。

classmethod from_decimal(dec)

Alternative constructor which only accepts instances of decimal.Decimal or numbers.Integral.

注釈

Python 3.2 以降では、 decimal.Decimal インスタンスから直接 Fraction インスタンスを構築できるようになりました。

limit_denominator(max_denominator=1000000)

分母が高々 max_denominator である、 self に最も近い Fraction を見付けて返します。このメソッドは与えられた浮動小数点数の有理数近似を見つけるのに役立ちます:

>>> from fractions import Fraction
>>> Fraction('3.1415926535897932').limit_denominator(1000)
Fraction(355, 113)

あるいは float で表された有理数を元に戻すのにも使えます:

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

__floor__()

最大の int <= self を返します。このメソッドは math.floor() 関数からでもアクセスできます:

>>> from math import floor
>>> floor(Fraction(355, 113))
3

__ceil__()

最小の int >= self を返します。このメソッドは math.ceil() 関数からでもアクセスできます。

__round__()

__round__(ndigits)

第一のバージョンは、 self に最も近い int を偶数丸めで返します。第二のバージョンは、このメソッドは self に最も近い Fraction(1, 10**ndigits) の倍数 (論理的に、 ndigits が負なら) を、これも偶数丸めで丸めます。 round() 関数からでもアクセスできます。

__format__(format_spec, /)

Provides support for float-style formatting of Fraction instances via the str.format() method, the format() built-in function, or Formatted string literals. The presentation types "e", "E", "f", "F", "g", "G" and "%" are supported. For these presentation types, formatting for a Fraction object x follows the rules outlined for the float type in the 書式指定ミニ言語仕様 section.

ここに例があります:

>>> from fractions import Fraction
>>> 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'

参考

numbers モジュール

数値の塔を作り上げる抽象基底クラス。

random --- Generate pseudo-random numbers

ソースコード: Lib/random.py [https://github.com/python/cpython/tree/3.12/Lib/random.py]

このモジュールでは様々な分布をもつ擬似乱数生成器を実装しています。

整数用に、ある範囲からの一様な選択があります。シーケンス用には、シーケンスからのランダムな要素の一様な選択、リストのランダムな置換をインプレースに生成する関数、順列を置換せずにランダムサンプリングする関数があります。

実数用としては、一様分布、正規分布 (ガウス分布)、対数正規分布、負の指数分布、ガンマおよびベータ分布を計算する関数があります。角度の分布を生成するにはフォン・ミーゼス分布が利用できます。

ほとんど全てのモジュール関数は、基礎となる関数 random() に依存します。この関数はランダムな浮動小数点数を半開区間 0.0 <= X < 1.0 内に一様に生成します。Python は中心となる乱数生成器としてメルセンヌツイスタを使います。これは 53 ビット精度の浮動小数点を生成し、周期は 2**19937-1 です。本体は C で実装されていて、高速でスレッドセーフです。メルセンヌツイスタは、現存する中で最も広範囲にテストされた乱数生成器のひとつです。しかしながら、メルセンヌツイスタは完全に決定論的であるため、全ての目的に合致しているわけではなく、暗号化の目的には全く向いていません。

このモジュールで提供されている関数は、実際には random.Random クラスの隠蔽されたインスタンスのメソッドに束縛されています。内部状態を共有しない生成器を取得するため、自分で Random のインスタンスを生成することができます。

Class Random can also be subclassed if you want to use a different basic generator of your own devising: see the documentation on that class for more details.

random モジュールは SystemRandom クラスも提供していて、このクラスは OS が提供している乱数発生源を利用して乱数を生成するシステム関数 os.urandom() を使うものです。

警告

このモジュールの擬似乱数生成器をセキュリティ目的に使用してはいけません。セキュリティや暗号学的な用途については secrets モジュールを参照してください。

参考

M. Matsumoto and T. Nishimura, "Mersenne Twister: A 623-dimensionally equidistributed uniform pseudorandom number generator", ACM Transactions on Modeling and Computer Simulation Vol. 8, No. 1, January pp.3--30 1998.

Complementary-Multiply-with-Carry recipe [https://code.activestate.com/recipes/576707-long-period-random-number-generator/] for a compatible alternative random number generator with a long period and comparatively simple update operations.

保守 (bookkeeping) 関数

random.seed(a=None, version=2)

乱数生成器を初期化します。

a が省略されるか None の場合、現在のシステム時刻が使用されます。乱数のソースがオペレーティングシステムによって提供される場合、システム時刻の代わりにそれが使用されます (利用可能性についての詳細は os.urandom() 関数を参照)。

a が int の場合、それが直接使われます。

バージョン2 (デフォルト) では、 str, bytes, bytearray オブジェクトは int に変換され、そのビットがすべて使用されます。

バージョン1 (Python の古いバージョンでの乱数列を再現するために提供される) では、 str と bytes に対して適用されるアルゴリズムは、より狭い範囲のシードを生成します。

バージョン 3.2 で変更: 文字列シードのすべてのビットを使うバージョン2スキームに移行。

バージョン 3.11 で変更: seed は次の型の内のいずれかでなければなりません: None、int、float、str、bytes、bytearray。

random.getstate()

乱数生成器の現在の内部状態を記憶したオブジェクトを返します。このオブジェクトを setstate() に渡して内部状態を復元することができます。

random.setstate(state)

state は予め getstate() を呼び出して得ておかなくてはなりません。 setstate() は getstate() が呼び出された時の乱数生成器の内部状態を復元します。

バイト列用の関数

random.randbytes(n)

n バイトのランダムなバイト列を生成します。

セキュリティトークンを生成する目的で、このメソッドを使用しないでください。代わりに secrets.token_bytes() を使用してください。

Added in version 3.9.

整数用の関数

random.randrange(stop)

random.randrange(start, stop[, step])

range(start, stop, step) の要素からランダムに選ばれた要素を返します。

This is roughly equivalent to choice(range(start, stop, step)) but supports arbitrarily large ranges and is optimized for common cases.

位置引数のパターンは range() 関数の引数と一致します。

Keyword arguments should not be used because they can be interpreted in unexpected ways. For example randrange(start=100) is interpreted as randrange(0, 100, 1).

バージョン 3.2 で変更: 一様に分布した値の生成に関して randrange() がより洗練されました。以前は int(random()*n) のようなやや一様でない分布を生成するスタイルを使用していました。

バージョン 3.12 で変更: 整数以外の型の自動変換はサポートされなくなりました。randrange(10.0) や randrange(Fraction(10, 1)) のような呼び出しは TypeError を送出します。

random.randint(a, b)

a <= N <= b であるようなランダムな整数 N を返します。randrange(a, b+1) のエイリアスです。

random.getrandbits(k)

k 桁の乱数ビットを持つ Python の整数を生成し、返します。このメソッドはメルセンヌツイスタ生成器で提供されており、その他の乱数生成器でもオプションの API として提供されている場合があります。getrandbits() が使用可能な場合、randrange() は任意の範囲の乱数を生成できるようになります。

バージョン 3.9 で変更: k の値として 0 が許されるようになりました。

シーケンス用の関数

random.choice(seq)

空でないシーケンス seq からランダムに要素を返します。 seq が空のときは、 IndexError が送出されます。

random.choices(population, weights=None, *, cum_weights=None, k=1)

population から重複ありで選んだ要素からなる大きさ k のリストを返します。population が空の場合 IndexError を送出します。

weights シーケンスが与えられた場合、相対的な重みに基づいて要素が選ばれます。あるいは、cum_weights シーケンスが与えられた場合、累積的な重み (itertools.accumulate() を用いて計算されるかもしれません) で要素が選ばれます。例えば、相対的な重み [10, 5, 30, 5] は累積的な重み [10, 15, 45, 50] と等価です。内部的には、相対的な重みは要素選択の前に累積的な重みに変換されるため、累積的な重みを渡すと手間を省けます。

weights および cum_weights が与えられなかった場合、要素は同じ確率で選択されます。重みのシーケンスが与えられた場合、その長さは population シーケンスと同じでなければなりません。weights と cum_weights を同時に与えると TypeError が送出されます。

weights や cum_weights には random() が返す float 値と相互に変換できるような、任意の数値型を使用できます (int、float、fraction を含みますが、decimal は除きます)。重みには非負で有限の値を指定することが規定されます。全ての重みが 0 の場合、例外 ValueError が送出されます。

与えられた種に対して、同じ重みを持つ choices() 関数は、一般に choice() を繰り返し呼び出す場合とは異なるシーケンスを生成します。 choices() で使用されるアルゴリズムは、内部の一貫性とスピードのために浮動小数点演算を使用します。 choice() で使われるアルゴリズムは、丸め誤差による小さな偏りを避けるために、デフォルトでは選択を繰り返す整数演算になっています。

Added in version 3.6.

バージョン 3.9 で変更: 全ての重みが 0 の場合、例外 ValueError を送出します。

random.shuffle(x)

シーケンス x をインプレースにシャッフルします。

イミュータブルなシーケンスをシャッフルしてシャッフルされたリストを新たに返すには、代わりに sample(x, k=len(x)) を使用してください。

たとえ len(x) が小さくても、x の並べ替えの総数 (訳注: 要素数の階乗) は大半の乱数生成器の周期よりもすぐに大きくなることに注意してください。つまり、長いシーケンスの大半の並べ替えは決して生成されないだろう、ということです。例えば、長さ 2080 のシーケンスがメルセンヌツイスタ生成器の周期に収まる中で最大のものになります。

バージョン 3.11 で変更: オプション引数 random が削除されました。

random.sample(population, k, *, counts=None)

母集団のシーケンスから選ばれた長さ k の一意な要素からなるリストを返します。値の置換を行わないランダムサンプリングに用いられます。

母集団自体を変更せずに、母集団内の要素を含む新たなリストを返します。返されたリストは選択された順に並んでいるので、このリストの部分スライスもランダムなサンプルになります。これにより、くじの当選者 (サンプル) を1等賞と2等賞（の部分スライス）に分けることも可能です。

母集団の要素は ハッシュ可能 でなくても、ユニークでなくてもかまいません。母集団が繰り返しを含む場合、出現するそれぞれがサンプルに選択されえます。

母集団に重複がある場合はその分だけ1つずつ指定するか、キーワード専用オプション引数 counts で指定することができます。例えば、 sample(['red', 'blue'], counts=[4, 2], k=5) は sample(['red', 'red', 'red', 'red', 'blue', 'blue'], k=5) と等価になります。

ある範囲の整数からサンプルを取る場合、引数に range() オブジェクトを使用してください。大きな母集団の場合、これは特に速く、メモリ効率が良いです: sample(range(10000000), k=60)。

サンプルの大きさが母集団の大きさより大きい場合 ValueError が送出されます。

バージョン 3.9 で変更: counts 引数が追加されました。

バージョン 3.11 で変更: The population must be a sequence. Automatic conversion of sets to lists is no longer supported.

Discrete distributions

The following function generates a discrete distribution.

random.binomialvariate(n=1, p=0.5)

Binomial distribution [https://mathworld.wolfram.com/BinomialDistribution.html]. Return the number of successes for n independent trials with the probability of success in each trial being p:

Mathematically equivalent to:

sum(random() < p for i in range(n))

The number of trials n should be a non-negative integer. The probability of success p should be between 0.0 <= p <= 1.0. The result is an integer in the range 0 <= X <= n.

Added in version 3.12.

実数分布

以下の関数は特定の実数値分布を生成します。関数の引数の名前は、一般的な数学の慣例で使われている分布の公式の対応する変数から取られています; これらの公式のほとんどはどんな統計学のテキストにも載っています。

random.random()

ランダムな浮動小数点数（範囲は 0.0 <= X < 1.0）を返します。

random.uniform(a, b)

a <= b であれば a <= N <= b 、b < a であれば b <= N <= a であるようなランダムな浮動小数点数 N を返します。

The end-point value b may or may not be included in the range depending on floating-point rounding in the expression a + (b-a) * random().

random.triangular(low, high, mode)

low <= N <= high でありこれら境界値の間に指定された最頻値 mode を持つようなランダムな浮動小数点数 N を返します。境界 low と high のデフォルトは 0 と 1 です。最頻値 mode 引数のデフォルトは両境界値の中点になり、対称な分布を与えます。

random.betavariate(alpha, beta)

ベータ分布です。引数の満たすべき条件は alpha > 0 および beta > 0 です。 0 から 1 の範囲の値を返します。

random.expovariate(lambd=1.0)

指数分布です。lambd は平均にしたい値の逆数です。(この引数は "lambda" と呼ぶべきなのですが、Python の予約語なので使えません。) 返す値の範囲は lambd が正なら 0 から正の無限大、lambd が負なら負の無限大から 0 です。

バージョン 3.12 で変更: lambd にデフォルト値を追加しました。

random.gammavariate(alpha, beta)

Gamma distribution. (Not the gamma function!) The shape and scale parameters, alpha and beta, must have positive values. (Calling conventions vary and some sources define 'beta' as the inverse of the scale).

確率分布関数は:

          x ** (alpha - 1) * math.exp(-x / beta)
pdf(x) =  --------------------------------------
            math.gamma(alpha) * beta ** alpha

random.gauss(mu=0.0, sigma=1.0)

正規分布、またはガウス分布と呼ばれます。 mu は平均であり、 sigma は標準偏差です。この関数は後で定義する関数 normalvariate() より少しだけ高速です。

Multithreading note: When two threads call this function simultaneously, it is possible that they will receive the same return value. This can be avoided in three ways. 1) Have each thread use a different instance of the random number generator. 2) Put locks around all calls. 3) Use the slower, but thread-safe normalvariate() function instead.

バージョン 3.11 で変更: mu と sigma にデフォルト値を追加しました。

random.lognormvariate(mu, sigma)

対数正規分布です。この分布を自然対数を用いた分布にした場合、平均 mu で標準偏差 sigma の正規分布になります。 mu は任意の値を取ることができ、sigma はゼロより大きくなければなりません。

random.normalvariate(mu=0.0, sigma=1.0)

正規分布です。 mu は平均で、 sigma は標準偏差です。

バージョン 3.11 で変更: mu と sigma にデフォルト値を追加しました。

random.vonmisesvariate(mu, kappa)

mu は平均の角度で、0 から 2*pi までのラジアンで表されます。 kappa は濃度パラメータで、ゼロ以上でなければなりません。kappa がゼロに等しい場合、この分布は範囲 0 から 2*pi の一様でランダムな角度の分布に退化します。

random.paretovariate(alpha)

パレート分布です。 alpha は形状パラメータです。

random.weibullvariate(alpha, beta)

ワイブル分布です。 alpha は尺度パラメタで、 beta は形状パラメータです。

他の生成器

class random.Random([seed])

random モジュールがデフォルトで使用する疑似乱数生成器を実装したクラスです。

バージョン 3.11 で変更: Formerly the seed could be any hashable object. Now it is limited to: None, int, float, str, bytes, or bytearray.

Subclasses of Random should override the following methods if they wish to make use of a different basic generator:

seed(a=None, version=2)

Override this method in subclasses to customise the seed() behaviour of Random instances.

getstate()

Override this method in subclasses to customise the getstate() behaviour of Random instances.

setstate(state)

Override this method in subclasses to customise the setstate() behaviour of Random instances.

random()

Override this method in subclasses to customise the random() behaviour of Random instances.

Optionally, a custom generator subclass can also supply the following method:

getrandbits(k)

Override this method in subclasses to customise the getrandbits() behaviour of Random instances.

class random.SystemRandom([seed])

オペレーティングシステムの提供する発生源によって乱数を生成する os.urandom() 関数を使うクラスです。すべてのシステムで使えるメソッドではありません。ソフトウェアの状態に依存してはいけませんし、一連の操作は再現不能です。従って、 seed() メソッドは何の影響も及ぼさず、無視されます。 getstate() と setstate() メソッドが呼び出されると、例外 NotImplementedError が送出されます。

再現性について

Sometimes it is useful to be able to reproduce the sequences given by a pseudo-random number generator. By reusing a seed value, the same sequence should be reproducible from run to run as long as multiple threads are not running.

random モジュールのアルゴリズムやシード処理関数のほとんどは、Python バージョン間で変更される対象となりますが、次の二点は変更されないことが保証されています:

新しいシード処理メソッドが追加されたら、後方互換なシード処理器が提供されます。

生成器の random() メソッドは、互換なシード処理器に同じシードが与えられた場合、引き続き同じシーケンスを生成します。

使用例

基礎的な例:

>>> random()                          # Random float:  0.0 <= x < 1.0
0.37444887175646646

>>> uniform(2.5, 10.0)                # Random float:  2.5 <= x <= 10.0
3.1800146073117523

>>> expovariate(1 / 5)                # Interval between arrivals averaging 5 seconds
5.148957571865031

>>> randrange(10)                     # Integer from 0 to 9 inclusive
7

>>> randrange(0, 101, 2)              # Even integer from 0 to 100 inclusive
26

>>> choice(['win', 'lose', 'draw'])   # Single random element from a sequence
'draw'

>>> deck = 'ace two three four'.split()
>>> shuffle(deck)                     # Shuffle a list
>>> deck
['four', 'two', 'ace', 'three']

>>> sample([10, 20, 30, 40, 50], k=4) # Four samples without replacement
[40, 10, 50, 30]

シミュレーション:

>>> # Six roulette wheel spins (weighted sampling with replacement)
>>> choices(['red', 'black', 'green'], [18, 18, 2], k=6)
['red', 'green', 'black', 'black', 'red', 'black']

>>> # Deal 20 cards without replacement from a deck
>>> # of 52 playing cards, and determine the proportion of cards
>>> # with a ten-value:  ten, jack, queen, or king.
>>> deal = sample(['tens', 'low cards'], counts=[16, 36], k=20)
>>> deal.count('tens') / 20
0.15

>>> # Estimate the probability of getting 5 or more heads from 7 spins
>>> # of a biased coin that settles on heads 60% of the time.
>>> sum(binomialvariate(n=7, p=0.6) >= 5 for i in range(10_000)) / 10_000
0.4169

>>> # Probability of the median of 5 samples being in middle two quartiles
>>> def trial():
...     return 2_500 <= sorted(choices(range(10_000), k=5))[2] < 7_500
...
>>> sum(trial() for i in range(10_000)) / 10_000
0.7958

サンプルの平均の信頼区間を推定するのに、重複ありでリサンプリングして `統計的ブートストラップ `_ を行う例:

# 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}')

薬と偽薬の間に観察された効果の違いについて、統計的有意性、すなわち p 値 [https://en.wikipedia.org/wiki/P-value] を決定するために、リサンプリング順列試験 [https://en.wikipedia.org/wiki/Resampling_(statistics)#Permutation_tests] を行う例:

# Example from "Statistics is Easy" by Dennis Shasha and Manda Wilson
from statistics import fmean as mean
from random import shuffle

drug = [54, 73, 53, 70, 73, 68, 52, 65, 65]
placebo = [54, 51, 58, 44, 55, 52, 42, 47, 58, 46]
observed_diff = mean(drug) - mean(placebo)

n = 10_000
count = 0
combined = drug + placebo
for i in range(n):
    shuffle(combined)
    new_diff = mean(combined[:len(drug)]) - mean(combined[len(drug):])
    count += (new_diff >= observed_diff)

print(f'{n} label reshufflings produced only {count} instances with a difference')
print(f'at least as extreme as the observed difference of {observed_diff:.1f}.')
print(f'The one-sided p-value of {count / n:.4f} leads us to reject the null')
print(f'hypothesis that there is no difference between the drug and the placebo.')

マルチサーバーキューにおける到達時間とサービス提供のシミュレーション:

from heapq import heapify, heapreplace
from random import expovariate, gauss
from statistics import mean, quantiles

average_arrival_interval = 5.6
average_service_time = 15.0
stdev_service_time = 3.5
num_servers = 3

waits = []
arrival_time = 0.0
servers = [0.0] * num_servers  # time when each server becomes available
heapify(servers)
for i in range(1_000_000):
    arrival_time += expovariate(1.0 / average_arrival_interval)
    next_server_available = servers[0]
    wait = max(0.0, next_server_available - arrival_time)
    waits.append(wait)
    service_duration = max(0.0, gauss(average_service_time, stdev_service_time))
    service_completed = arrival_time + wait + service_duration
    heapreplace(servers, service_completed)

print(f'Mean wait: {mean(waits):.1f}   Max wait: {max(waits):.1f}')
print('Quartiles:', [round(q, 1) for q in quantiles(waits)])

参考

Statistics for Hackers [https://www.youtube.com/watch?v=Iq9DzN6mvYA] Jake Vanderplas [https://us.pycon.org/2016/speaker/profile/295/] による統計解析のビデオ。シミュレーション、サンプリング、シャッフル、交差検定といった基本的な概念のみを用いています。

Economics Simulation [https://nbviewer.org/url/norvig.com/ipython/Economics.ipynb] a simulation of a marketplace by Peter Norvig [https://norvig.com/bio.html] that shows effective use of many of the tools and distributions provided by this module (gauss, uniform, sample, betavariate, choice, triangular, and randrange).

A Concrete Introduction to Probability (using Python) [https://nbviewer.org/url/norvig.com/ipython/Probability.ipynb] a tutorial by Peter Norvig [https://norvig.com/bio.html] covering the basics of probability theory, how to write simulations, and how to perform data analysis using Python.

レシピ

These recipes show how to efficiently make random selections from the combinatoric iterators in the itertools module:

def random_product(*args, repeat=1):
    "Random selection from itertools.product(*args, **kwds)"
    pools = [tuple(pool) for pool in args] * repeat
    return tuple(map(random.choice, pools))

def random_permutation(iterable, r=None):
    "Random selection from itertools.permutations(iterable, r)"
    pool = tuple(iterable)
    r = len(pool) if r is None else r
    return tuple(random.sample(pool, r))

def random_combination(iterable, r):
    "Random selection from itertools.combinations(iterable, r)"
    pool = tuple(iterable)
    n = len(pool)
    indices = sorted(random.sample(range(n), r))
    return tuple(pool[i] for i in indices)

def random_combination_with_replacement(iterable, r):
    "Choose r elements with replacement.  Order the result to match the iterable."
    # Result will be in set(itertools.combinations_with_replacement(iterable, r)).
    pool = tuple(iterable)
    n = len(pool)
    indices = sorted(random.choices(range(n), k=r))
    return tuple(pool[i] for i in indices)

The default random() returns multiples of 2⁻⁵³ in the range 0.0 ≤ x < 1.0. All such numbers are evenly spaced and are exactly representable as Python floats. However, many other representable floats in that interval are not possible selections. For example, 0.05954861408025609 isn't an integer multiple of 2⁻⁵³.

The following recipe takes a different approach. All floats in the interval are possible selections. The mantissa comes from a uniform distribution of integers in the range 2⁵² ≤ mantissa < 2⁵³. The exponent comes from a geometric distribution where exponents smaller than -53 occur half as often as the next larger exponent.

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)

All real valued distributions in the class will use the new method:

>>> fr = FullRandom()
>>> fr.random()
0.05954861408025609
>>> fr.expovariate(0.25)
8.87925541791544

The recipe is conceptually equivalent to an algorithm that chooses from all the multiples of 2⁻¹⁰⁷⁴ in the range 0.0 ≤ x < 1.0. All such numbers are evenly spaced, but most have to be rounded down to the nearest representable Python float. (The value 2⁻¹⁰⁷⁴ is the smallest positive unnormalized float and is equal to math.ulp(0.0).)

参考

Generating Pseudo-random Floating-Point Values [https://allendowney.com/research/rand/downey07randfloat.pdf] a paper by Allen B. Downey describing ways to generate more fine-grained floats than normally generated by random().

statistics --- Mathematical statistics functions

Added in version 3.4.

ソースコード: Lib/statistics.py [https://github.com/python/cpython/tree/3.12/Lib/statistics.py]

このモジュールは、数値 (Real 型) データを数学的に統計計算するための関数を提供します。

このモジュールは、 NumPy [https://numpy.org], SciPy [https://scipy.org/] のような third-party ライブラリや、Minitab、SAS、Matlab のようなプロ統計家向けのフル装備なプロプライエタリ統計パッケージと競合することを意図していません。グラフ関数電卓のレベルを対象としています。

特に明記しない限り、これらの関数は int, float, Decimal そして Fraction をサポートします。他の型 (算術型及びそれ以外) は現在サポートされていません。型が混ざったコレクションも未定義で実装依存です。入力データが複数の型からなる場合、map() を使用すると正しい結果が得られるでしょう。 例: map(float, input_data)。

あるデータセットでは欠損値を表すために NaN (not a number) を使います。 NaNは通常と異なる比較セマンティクスを持つため、ソートやカウントを行う統計関数では、驚きや未定義の振る舞いを引き起こします。 影響を受ける関数は median(), median_low(), median_high(), median_grouped(), mode(), multimode(), そして quantiles() です。 これらの関数を呼ぶ前に、 NaN 値を取り除く必要があります:

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

平均及び中心位置の測度

これらの関数は母集団または標本の平均値や標準値を計算します。

mean()

データの算術平均 (いわゆる「平均」) 。

fmean()

Fast, floating point arithmetic mean, with optional weighting.

geometric_mean()

データの幾何平均。

harmonic_mean()

データの調和平均。

median()

データのメジアン(中央値)。

median_low()

データの low median。

median_high()

データの high median。

median_grouped()

Median (50th percentile) of grouped data.

mode()

離散/名義尺度データの最頻値 (single mode) 。

multimode()

離散/名義尺度データの最頻値 (list of modes) 。

quantiles()

データの等確率での分割。

分散の測度

これらの関数は母集団または標本が標準値や平均値からどれくらい離れているかについて計算します。

pstdev()

データの母標準偏差。

pvariance()

データの母分散。

stdev()

データの標本標準偏差。

variance()

データの標本標準分散。

2入力間の関係の統計

これらの関数は、2つの入力間の関係について統計量を計算します。

covariance()

2変数の標本共分散。

correlation()

ピアソンとスピアマンの相関係数。

linear_regression()

単回帰の傾きと切片。

関数の詳細

註釈: 関数の引数となるデータをソートしておく必要はありません。例の多くがソートされているのは見やすさのためです。

statistics.mean(data)

シーケンス型またはイテラブルになり得る data の標本算術平均を返します。

算術平均はデータの総和をデータ数で除したものです。単に「平均」と呼ばれることも多いですが、数学における平均の一種に過ぎません。データの中心位置の測度の一つです。

data が空の場合 StatisticsError を送出します。

使用例:

>>> 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')

注釈

mean は 外れ値 [https://ja.wikipedia.org/wiki/外れ値] (outliers [https://en.wikipedia.org/wiki/Outlier]) の影響を強く受け、必ずしもデータ点の典型例とはなりません。効率が悪いものの、より堅牢な、 中心的な傾向 (central tendency [https://en.wikipedia.org/wiki/Central_tendency]) の尺度については、 median() を参照してください。

標本平均は真の母平均の不偏推定量のため、出来る限り多くの標本から平均を求めると、mean(sample) は真の母平均に収束します (訳注: 大数の法則)。data が標本ではなく母集団全体の場合、mean(data) は真の母平均 μ を計算することと等価です。

statistics.fmean(data, weights=None)

data を float に変換し、算術平均を計算します。

This runs faster than the mean() function and it always returns a float. The data may be a sequence or iterable. If the input dataset is empty, raises a StatisticsError.

>>> fmean([3.5, 4.0, 5.25])
4.25

Optional weighting is supported. For example, a professor assigns a grade for a course by weighting quizzes at 20%, homework at 20%, a midterm exam at 30%, and a final exam at 30%:

>>> grades = [85, 92, 83, 91]
>>> weights = [0.20, 0.20, 0.30, 0.30]
>>> fmean(grades, weights)
87.6

If weights is supplied, it must be the same length as the data or a ValueError will be raised.

Added in version 3.8.

バージョン 3.11 で変更: weights のサポートが追加されました。

statistics.geometric_mean(data)

Convert data to floats and compute the geometric mean.

The geometric mean indicates the central tendency or typical value of the data using the product of the values (as opposed to the arithmetic mean which uses their sum).

Raises a StatisticsError if the input dataset is empty, if it contains a zero, or if it contains a negative value. The data may be a sequence or iterable.

No special efforts are made to achieve exact results. (However, this may change in the future.)

>>> round(geometric_mean([54, 24, 36]), 1)
36.0

Added in version 3.8.

statistics.harmonic_mean(data, weights=None)

Return the harmonic mean of data, a sequence or iterable of real-valued numbers. If weights is omitted or None, then equal weighting is assumed.

調和平均（harmonic mean）は、データの逆数の算術平均 mean() の逆数です。例えば、3つの値 a, b, c の調和平均は``3/(1/a + 1/b + 1/c)`` になります。いずれかの値が0の場合、結果は0になります。

調和平均は平均の一種で、データの中心位置の測度です。速度のような比(ratios)や率(rates)を平均するときにしばしば適切です。

Suppose a car travels 10 km at 40 km/hr, then another 10 km at 60 km/hr. What is the average speed?

>>> harmonic_mean([40, 60])
48.0

Suppose a car travels 40 km/hr for 5 km, and when traffic clears, speeds-up to 60 km/hr for the remaining 30 km of the journey. What is the average speed?

>>> harmonic_mean([40, 60], weights=[5, 30])
56.0

StatisticsError is raised if data is empty, any element is less than zero, or if the weighted sum isn't positive.

The current algorithm has an early-out when it encounters a zero in the input. This means that the subsequent inputs are not tested for validity. (This behavior may change in the future.)

Added in version 3.6.

バージョン 3.10 で変更: weights のサポートが追加されました。

statistics.median(data)

一般的な「中央2つの平均をとる」方法を使用して、数値データの中央値（中間値）を返します。もし data が空の場合、例外 StatisticsError が送出されます。data はシーケンス型またはイテラブルにもなれます。

中央値は外れ値の影響を受けにくいため、中心位置のロバストな測度です。データ数が奇数の場合は中央の値を返します:

>>> median([1, 3, 5])
3

データ数が偶数の場合は、中央値は中央に最も近い2値の算術平均で補間されます:

>>> median([1, 3, 5, 7])
4.0

データが離散的で、中央値がデータ点にない値でも構わない場合に適しています。

もしあなたのデータが（注文操作をサポートする）序数で、（追加操作をサポートしない）数値でないならば、代わりに median_low() または median_high() の使用を検討してください。

statistics.median_low(data)

数値データの小さい方の中央値(low median)を返します。もし data が空の場合、StatisticsError が送出されます。data はシーケンス型またはイテラブルにもなれます。

low median は必ずデータに含まれています。データ数が奇数の場合は中央の値を返し、偶数の場合は中央の2値の小さい方を返します。

>>> median_low([1, 3, 5])
3
>>> median_low([1, 3, 5, 7])
3

データが離散的で、中央値が補間値よりもデータ点にある値の方が良い場合に用いてください。

statistics.median_high(data)

データの大きい方の中央値(high median)を返します。もし data が空の場合、StatisticsError が送出されます。 data はシーケンス型やイテラブルにもなれます。

high median は必ずデータに含まれています。データ数が奇数の場合は中央の値を返し、偶数の場合は中央の2値の大きい方を返します。

>>> median_high([1, 3, 5])
3
>>> median_high([1, 3, 5, 7])
5

データが離散的で、中央値が補間値よりもデータ点にある値の方が良い場合に用いてください。

statistics.median_grouped(data, interval=1.0)

Estimates the median for numeric data that has been grouped or binned [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:

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

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 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 median_grouped():

>>> data = list(demographics.elements())
>>> median(data)
35
>>> round(median_grouped(data, interval=10), 1)
37.5

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.

statistics.mode(data)

Return the single most common data point from discrete or nominal data. The mode (when it exists) is the most typical value and serves as a measure of central location.

If there are multiple modes with the same frequency, returns the first one encountered in the data. If the smallest or largest of those is desired instead, use min(multimode(data)) or max(multimode(data)). If the input data is empty, StatisticsError is raised.

mode は離散データであることを想定していて、1つの値を返します。これは学校で教わるような最頻値の標準的な取扱いです:

>>> mode([1, 1, 2, 3, 3, 3, 3, 4])
3

The mode is unique in that it is the only statistic in this package that also applies to nominal (non-numeric) data:

>>> mode(["red", "blue", "blue", "red", "green", "red", "red"])
'red'

バージョン 3.8 で変更: Now handles multimodal datasets by returning the first mode encountered. Formerly, it raised StatisticsError when more than one mode was found.

statistics.multimode(data)

Return a list of the most frequently occurring values in the order they were first encountered in the data. Will return more than one result if there are multiple modes or an empty list if the data is empty:

>>> multimode('aabbbbccddddeeffffgg')
['b', 'd', 'f']
>>> multimode('')
[]

Added in version 3.8.

statistics.pstdev(data, mu=None)

母標準偏差 (母分散の平方根) を返します。引数や詳細は pvariance() を参照してください。

>>> pstdev([1.5, 2.5, 2.5, 2.75, 3.25, 4.75])
0.986893273527251

statistics.pvariance(data, mu=None)

data の母分散を返します。data は実数の空でないシーケンスまたはイテラブルです。分散、すなわち2次の中心化モーメントはデータの散らばり具合の測度です。分散が大きいデータはばらつきが大きく、分散が小さいデータは平均値のまわりに固まっています。

If the optional second argument mu is given, it should be the population mean of the data. It can also be used to compute the second moment around a point that is not the mean. If it is missing or None (the default), the arithmetic mean is automatically calculated.

母集団全体から分散を計算する場合に用いてください。標本から分散を推定する場合は variance() を使いましょう。

data が空の場合 StatisticsError を送出します。

例:

>>> data = [0.0, 0.25, 0.25, 1.25, 1.5, 1.75, 2.75, 3.25]
>>> pvariance(data)
1.25

既にデータの平均値を計算している場合、それを第2引数 mu に渡して再計算を避けることが出来ます:

>>> mu = mean(data)
>>> pvariance(data, mu)
1.25

Decimal と Fraction がサポートされています:

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

注釈

母集団全体で呼んだ場合は母分散 σ² を返します。代わりに標本で呼んだ場合は biased variance s²、すなわち自由度 N の分散を返します。

If you somehow know the true population mean μ, you may use this function to calculate the variance of a sample, giving the known population mean as the second argument. Provided the data points are a random sample of the population, the result will be an unbiased estimate of the population variance.

statistics.stdev(data, xbar=None)

標本標準偏差 (標本分散の平方根) を返します。引数や詳細は variance() を参照してください。

>>> stdev([1.5, 2.5, 2.5, 2.75, 3.25, 4.75])
1.0810874155219827

statistics.variance(data, xbar=None)

data の標本分散を返します。data は少なくとも2つの実数の iterable です。分散、すなわち2次の中心化モーメントはデータの散らばり具合の測度です。分散が大きいデータはばらつきが大きく、分散が小さいデータは平均値のまわりに固まっています。

If the optional second argument xbar is given, it should be the sample mean of data. If it is missing or None (the default), the mean is automatically calculated.

データが母集団の標本であるときに用いてください。母集団全体から分散を計算するには pvariance() を参照してください。

data の値が2より少ない場合 StatisticsError を送出します。

例:

>>> data = [2.75, 1.75, 1.25, 0.25, 0.5, 1.25, 3.5]
>>> variance(data)
1.3720238095238095

If you have already calculated the sample mean of your data, you can pass it as the optional second argument xbar to avoid recalculation:

>>> m = mean(data)
>>> variance(data, m)
1.3720238095238095

この関数は引数として渡した xbar が実際の平均値かどうかチェックしません。任意の値を xbar に渡すと無効な結果やありえない結果が返ることがあります。

Decimal と Fraction がサポートされています:

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

注釈

Bessel 補正済みの標本分散 s²、すなわち自由度 N-1 の分散です。与えられたデータ点が代表的 (たとえば独立で均等に分布) な場合、戻り値は母分散の不偏推定量になります。

何らかの方法で真の母平均 μ を知っている場合、それを pvariance() の引数 mu に渡して標本の分散を計算することが出来ます。

statistics.quantiles(data, *, n=4, method='exclusive')

Divide data into n continuous intervals with equal probability. Returns a list of n - 1 cut points separating the intervals.

Set n to 4 for quartiles (the default). Set n to 10 for deciles. Set n to 100 for percentiles which gives the 99 cuts points that separate data into 100 equal sized groups. Raises StatisticsError if n is not least 1.

The data can be any iterable containing sample data. For meaningful results, the number of data points in data should be larger than n. Raises StatisticsError if there are not at least two data points.

The cut points are linearly interpolated from the two nearest data points. For example, if a cut point falls one-third of the distance between two sample values, 100 and 112, the cut-point will evaluate to 104.

The method for computing quantiles can be varied depending on whether the data includes or excludes the lowest and highest possible values from the population.

The default method is "exclusive" and is used for data sampled from a population that can have more extreme values than found in the samples. The portion of the population falling below the i-th of m sorted data points is computed as i / (m + 1). Given nine sample values, the method sorts them and assigns the following percentiles: 10%, 20%, 30%, 40%, 50%, 60%, 70%, 80%, 90%.

Setting the method to "inclusive" is used for describing population data or for samples that are known to include the most extreme values from the population. The minimum value in data is treated as the 0th percentile and the maximum value is treated as the 100th percentile. The portion of the population falling below the i-th of m sorted data points is computed as (i - 1) / (m - 1). Given 11 sample values, the method sorts them and assigns the following percentiles: 0%, 10%, 20%, 30%, 40%, 50%, 60%, 70%, 80%, 90%, 100%.

# 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]

Added in version 3.8.

statistics.covariance(x, y, /)

Return the sample covariance of two inputs x and y. Covariance is a measure of the joint variability of two inputs.

Both inputs must be of the same length (no less than two), otherwise StatisticsError is raised.

例:

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

Added in version 3.10.

statistics.correlation(x, y, /, *, method='linear')

Return the Pearson's correlation coefficient [https://en.wikipedia.org/wiki/Pearson_correlation_coefficient] for two inputs. Pearson's correlation coefficient r takes values between -1 and +1. It measures the strength and direction of a linear relationship.

If method is "ranked", computes Spearman's rank correlation coefficient [https://en.wikipedia.org/wiki/Spearman%27s_rank_correlation_coefficient] for two inputs. The data is replaced by ranks. Ties are averaged so that equal values receive the same rank. The resulting coefficient measures the strength of a monotonic relationship.

Spearman's correlation coefficient is appropriate for ordinal data or for continuous data that doesn't meet the linear proportion requirement for Pearson's correlation coefficient.

Both inputs must be of the same length (no less than two), and need not to be constant, otherwise StatisticsError is raised.

Example with Kepler's laws of planetary motion [https://en.wikipedia.org/wiki/Kepler's_laws_of_planetary_motion]:

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

Added in version 3.10.

バージョン 3.12 で変更: Added support for Spearman's rank correlation coefficient.

statistics.linear_regression(x, y, /, *, proportional=False)

Return the slope and intercept of simple linear regression [https://en.wikipedia.org/wiki/Simple_linear_regression] parameters estimated using ordinary least squares. Simple linear regression describes the relationship between an independent variable x and a dependent variable y in terms of this linear function:

y = slope * x + intercept + noise

where slope and intercept are the regression parameters that are estimated, and noise represents the variability of the data that was not explained by the linear regression (it is equal to the difference between predicted and actual values of the dependent variable).

Both inputs must be of the same length (no less than two), and the independent variable x cannot be constant; otherwise a StatisticsError is raised.

For example, we can use the release dates of the Monty Python films [https://en.wikipedia.org/wiki/Monty_Python#Films] to predict the cumulative number of Monty Python films that would have been produced by 2019 assuming that they had kept the pace.

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

If proportional is true, the independent variable x and the dependent variable y are assumed to be directly proportional. The data is fit to a line passing through the origin. Since the intercept will always be 0.0, the underlying linear function simplifies to:

y = slope * x + noise

Continuing the example from correlation(), we look to see how well a model based on major planets can predict the orbital distances for dwarf planets:

>>> model = linear_regression(period_squared, dist_cubed, proportional=True)
>>> slope = model.slope

>>> # Dwarf planets:   Pluto,  Eris,    Makemake, Haumea, Ceres
>>> orbital_periods = [90_560, 204_199, 111_845, 103_410, 1_680]  # days
>>> predicted_dist = [math.cbrt(slope * (p * p)) for p in orbital_periods]
>>> list(map(round, predicted_dist))
[5912, 10166, 6806, 6459, 414]

>>> [5_906, 10_152, 6_796, 6_450, 414]  # actual distance in million km
[5906, 10152, 6796, 6450, 414]

Added in version 3.10.

バージョン 3.11 で変更: Added support for proportional.

例外

例外が1つ定義されています:

exception statistics.StatisticsError

統計関係の例外。ValueError の派生クラス。

NormalDist オブジェクト

NormalDist is a tool for creating and manipulating normal distributions of a random variable [http://www.stat.yale.edu/Courses/1997-98/101/ranvar.htm]. It is a class that treats the mean and standard deviation of data measurements as a single entity.

Normal distributions arise from the Central Limit Theorem [https://en.wikipedia.org/wiki/Central_limit_theorem] and have a wide range of applications in statistics.

class statistics.NormalDist(mu=0.0, sigma=1.0)

Returns a new NormalDist object where mu represents the arithmetic mean [https://en.wikipedia.org/wiki/Arithmetic_mean] and sigma represents the standard deviation [https://en.wikipedia.org/wiki/Standard_deviation].

sigma が負の数の場合 StatisticsError を送出します。

mean

A read-only property for the arithmetic mean [https://en.wikipedia.org/wiki/Arithmetic_mean] of a normal distribution.

median

A read-only property for the median [https://en.wikipedia.org/wiki/Median] of a normal distribution.

mode

A read-only property for the mode [https://en.wikipedia.org/wiki/Mode_(statistics)] of a normal distribution.

stdev

A read-only property for the standard deviation [https://en.wikipedia.org/wiki/Standard_deviation] of a normal distribution.

variance

A read-only property for the variance [https://en.wikipedia.org/wiki/Variance] of a normal distribution. Equal to the square of the standard deviation.

classmethod from_samples(data)

Makes a normal distribution instance with mu and sigma parameters estimated from the data using fmean() and stdev().

The data can be any iterable and should consist of values that can be converted to type float. If data does not contain at least two elements, raises StatisticsError because it takes at least one point to estimate a central value and at least two points to estimate dispersion.

samples(n, *, seed=None)

Generates n random samples for a given mean and standard deviation. Returns a list of float values.

If seed is given, creates a new instance of the underlying random number generator. This is useful for creating reproducible results, even in a multi-threading context.

pdf(x)

Using a probability density function (pdf) [https://en.wikipedia.org/wiki/Probability_density_function], compute the relative likelihood that a random variable X will be near the given value x. Mathematically, it is the limit of the ratio P(x <= X < x+dx) / dx as dx approaches zero.

The relative likelihood is computed as the probability of a sample occurring in a narrow range divided by the width of the range (hence the word "density"). Since the likelihood is relative to other points, its value can be greater than 1.0.

cdf(x)

Using a cumulative distribution function (cdf) [https://en.wikipedia.org/wiki/Cumulative_distribution_function], compute the probability that a random variable X will be less than or equal to x. Mathematically, it is written P(X <= x).

inv_cdf(p)

Compute the inverse cumulative distribution function, also known as the quantile function [https://en.wikipedia.org/wiki/Quantile_function] or the percent-point [https://web.archive.org/web/20190203145224/https://www.statisticshowto.datasciencecentral.com/inverse-distribution-function/] function. Mathematically, it is written x : P(X <= x) = p.

Finds the value x of the random variable X such that the probability of the variable being less than or equal to that value equals the given probability p.

overlap(other)

Measures the agreement between two normal probability distributions. Returns a value between 0.0 and 1.0 giving the overlapping area for the two probability density functions [https://www.rasch.org/rmt/rmt101r.htm].

quantiles(n=4)

Divide the normal distribution into n continuous intervals with equal probability. Returns a list of (n - 1) cut points separating the intervals.

Set n to 4 for quartiles (the default). Set n to 10 for deciles. Set n to 100 for percentiles which gives the 99 cuts points that separate the normal distribution into 100 equal sized groups.

zscore(x)

Compute the Standard Score [https://www.statisticshowto.com/probability-and-statistics/z-score/] describing x in terms of the number of standard deviations above or below the mean of the normal distribution: (x - mean) / stdev.

Added in version 3.9.

Instances of NormalDist support addition, subtraction, multiplication and division by a constant. These operations are used for translation and scaling. For example:

>>> temperature_february = NormalDist(5, 2.5)             # Celsius
>>> temperature_february * (9/5) + 32                     # Fahrenheit
NormalDist(mu=41.0, sigma=4.5)

Dividing a constant by an instance of NormalDist is not supported because the result wouldn't be normally distributed.

Since normal distributions arise from additive effects of independent variables, it is possible to add and subtract two independent normally distributed random variables [https://en.wikipedia.org/wiki/Sum_of_normally_distributed_random_variables] represented as instances of NormalDist. For 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

Added in version 3.8.

例とレシピ

Classic probability problems

NormalDist readily solves classic probability problems.

For example, given historical data for SAT exams [https://nces.ed.gov/programs/digest/d17/tables/dt17_226.40.asp] showing that scores are normally distributed with a mean of 1060 and a standard deviation of 195, determine the percentage of students with test scores between 1100 and 1200, after rounding to the nearest whole number:

>>> sat = NormalDist(1060, 195)
>>> fraction = sat.cdf(1200 + 0.5) - sat.cdf(1100 - 0.5)
>>> round(fraction * 100.0, 1)
18.4

Find the quartiles [https://en.wikipedia.org/wiki/Quartile] and deciles [https://en.wikipedia.org/wiki/Decile] for the SAT scores:

>>> list(map(round, sat.quantiles()))
[928, 1060, 1192]
>>> list(map(round, sat.quantiles(n=10)))
[810, 896, 958, 1011, 1060, 1109, 1162, 1224, 1310]

Monte Carlo inputs for simulations

To estimate the distribution for a model that isn't easy to solve analytically, NormalDist can generate input samples for a Monte Carlo simulation [https://en.wikipedia.org/wiki/Monte_Carlo_method]:

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

Approximating binomial distributions

Normal distributions can be used to approximate Binomial distributions [https://mathworld.wolfram.com/BinomialDistribution.html] when the sample size is large and when the probability of a successful trial is near 50%.

For example, an open source conference has 750 attendees and two rooms with a 500 person capacity. There is a talk about Python and another about Ruby. In previous conferences, 65% of the attendees preferred to listen to Python talks. Assuming the population preferences haven't changed, what is the probability that the Python room will stay within its capacity limits?

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

Naive bayesian classifier

Normal distributions commonly arise in machine learning problems.

Wikipedia has a nice example of a Naive Bayesian Classifier [https://en.wikipedia.org/wiki/Naive_Bayes_classifier#Person_classification]. The challenge is to predict a person's gender from measurements of normally distributed features including height, weight, and foot size.

We're given a training dataset with measurements for eight people. The measurements are assumed to be normally distributed, so we summarize the data with NormalDist:

>>> 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])

Next, we encounter a new person whose feature measurements are known but whose gender is unknown:

>>> ht = 6.0        # height
>>> wt = 130        # weight
>>> fs = 8          # foot size

Starting with a 50% prior probability [https://en.wikipedia.org/wiki/Prior_probability] of being male or female, we compute the posterior as the prior times the product of likelihoods for the feature measurements given the gender:

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

The final prediction goes to the largest posterior. This is known as the maximum a posteriori [https://en.wikipedia.org/wiki/Maximum_a_posteriori_estimation] or MAP:

>>> 'male' if posterior_male > posterior_female else 'female'
'female'

Kernel density estimation

It is possible to estimate a continuous probability distribution from a fixed number of discrete samples.

The basic idea is to smooth the data using a kernel function such as a normal distribution, triangular distribution, or uniform distribution [https://en.wikipedia.org/wiki/Kernel_(statistics)#Kernel_functions_in_common_use]. The degree of smoothing is controlled by a scaling parameter, h, which is called the bandwidth.

from random import choice, random

def kde_normal(data, h):
    "Create a continuous probability distribution from discrete samples."

    # Smooth the data with a normal distribution kernel scaled by h.
    K_h = NormalDist(0.0, h)

    def pdf(x):
        'Probability density function.  P(x <= X < x+dx) / dx'
        return sum(K_h.pdf(x - x_i) for x_i in data) / len(data)

    def cdf(x):
        'Cumulative distribution function.  P(X <= x)'
        return sum(K_h.cdf(x - x_i) for x_i in data) / len(data)

    def rand():
        'Random selection from the probability distribution.'
        return choice(data) + K_h.inv_cdf(random())

    return pdf, cdf, rand

Wikipedia has an example [https://en.wikipedia.org/wiki/Kernel_density_estimation#Example] where we can use the kde_normal() recipe to generate and plot a probability density function estimated from a small sample:

>>> sample = [-2.1, -1.3, -0.4, 1.9, 5.1, 6.2]
>>> pdf, cdf, rand = kde_normal(sample, h=1.5)
>>> xarr = [i/100 for i in range(-750, 1100)]
>>> yarr = [pdf(x) for x in xarr]

The points in xarr and yarr can be used to make a PDF plot:

Resample [https://en.wikipedia.org/wiki/Resampling_(statistics)] the data to produce 100 new selections:

>>> new_selections = [rand() for i in range(100)]

Determine the probability of a new selection being below 2.0:

>>> round(cdf(2.0), 4)
0.5794

Add a new sample data point and find the new CDF at 2.0:

>>> sample.append(4.9)
>>> round(cdf(2.0), 4)
0.5005

関数型プログラミング用モジュール

この章では、関数型プログラミングスタイルをサポートする呼び出し可能で汎用な操作を実現する関数やクラスについて説明します。

この章では以下のモジュールが記述されています:

itertools --- Functions creating iterators for efficient looping

Itertool関数

Itertools レシピ

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

partial オブジェクト

operator --- Standard operators as functions

演算子から関数への対応表

インプレース (in-place) 演算子

itertools --- Functions creating iterators for efficient looping

このモジュールは イテレータ を構築する部品を実装しています。プログラム言語 APL, Haskell, SML からアイデアを得ていますが、 Python に適した形に修正されています。

このモジュールは、高速でメモリ効率に優れ、単独でも組合せても使用することのできるツールを標準化したものです。同時に、このツール群は "イテレータの代数" を構成していて、pure Python で簡潔かつ効率的なツールを作れるようにしています。

例えば、SML の作表ツール tabulate(f) は f(0), f(1), ... のシーケンスを作成します。同じことを Python では map() と count() を組合せて map(f, count()) という形で実現できます。

これらのツールと組み込み関数は operator モジュール内の高速な関数とともに使うことで見事に動作します。例えば、乗算演算子を2つのベクトルにわたってマップすることで効率的な内積計算を実現できます: sum(starmap(operator.mul, zip(vec1, vec2, strict=True)))。

無限イテレータ:

イテレータ

引数

結果

使用例

count()

[start[, step]]

start, start+step, start+2*step, ...

count(10) → 10 11 12 13 14 ...

cycle()

p

p0, p1, ... plast, p0, p1, ...

cycle('ABCD') → A B C D A B C D ...

repeat()

elem [,n]

elem, elem, elem, ... 無限もしくは n 回

repeat(10, 3) → 10 10 10

一番短い入力シーケンスで止まるイテレータ:

イテレータ

引数

結果

使用例

accumulate()

p [,func]

p0, p0+p1, p0+p1+p2, ...

accumulate([1,2,3,4,5]) → 1 3 6 10 15

batched()

p, n

(p0, p1, ..., p_n-1), ...

batched('ABCDEFG', n=3) → ABC DEF G

chain()

p, q, ...

p0, p1, ... plast, q0, q1, ...

chain('ABC', 'DEF') → A B C D E F

chain.from_iterable()

iterable

p0, p1, ... plast, q0, q1, ...

chain.from_iterable(['ABC', 'DEF']) → A B C D E F

compress()

data, selectors

(d[0] if s[0]), (d[1] if s[1]), ...

compress('ABCDEF', [1,0,1,0,1,1]) → A C E F

dropwhile()

predicate, seq

seq[n], seq[n+1], starting when predicate fails

dropwhile(lambda x: x<5, [1,4,6,4,1]) → 6 4 1

filterfalse()

predicate, seq

elements of seq where predicate(elem) fails

filterfalse(lambda x: x%2, range(10)) → 0 2 4 6 8

groupby()

iterable[, key]

key(v) の値でグループ化したサブイテレータ

islice()

seq, [start,] stop [, step]

seq[start:stop:step]

islice('ABCDEFG', 2, None) → C D E F G

pairwise()

iterable

(p[0], p[1]), (p[1], p[2])

pairwise('ABCDEFG') → AB BC CD DE EF FG

starmap()

func, seq

func(*seq[0]), func(*seq[1]), ...

starmap(pow, [(2,5), (3,2), (10,3)]) → 32 9 1000

takewhile()

predicate, seq

seq[0], seq[1], until predicate fails

takewhile(lambda x: x<5, [1,4,6,4,1]) → 1 4

tee()

it, n

it1, it2 , ... itn 一つのイテレータを n 個に分ける

zip_longest()

p, q, ...

(p[0], q[0]), (p[1], q[1]), ...

zip_longest('ABCD', 'xy', fillvalue='-') → Ax By C- D-

組合せイテレータ:

イテレータ

引数

結果

product()

p, q, ... [repeat=1]

デカルト積、ネストしたforループと等価

permutations()

p[, r]

長さrのタプル列、重複なしのあらゆる並び

combinations()

p, r

長さrのタプル列、ソートされた順で重複なし

combinations_with_replacement()

p, r

長さrのタプル列、ソートされた順で重複あり

使用例

結果

product('ABCD', repeat=2)

AA AB AC AD BA BB BC BD CA CB CC CD DA DB DC DD

permutations('ABCD', 2)

AB AC AD BA BC BD CA CB CD DA DB DC

combinations('ABCD', 2)

AB AC AD BC BD CD

combinations_with_replacement('ABCD', 2)

AA AB AC AD BB BC BD CC CD DD

Itertool関数

以下の関数は全て、イテレータを作成して返します。無限長のストリームのイテレータを返す関数もあり、この場合にはストリームを中断するような関数かループ処理から使用しなければなりません。

itertools.accumulate(iterable[, func, *, initial=None])

累計や加算ではない (func オプション引数で指定される) 2変数関数による累積結果を返すイテレータを作成します。

func が与えられた場合、2つの引数を取る関数でなければなりません。入力 iterable の要素は、 func が引数として取れる型を持ちます。 (例えば、デフォルトの演算の加算では、要素は Decimal や Fraction を含む、加算ができる型を持ちます。)

通常、出力される要素数は入力 iterable の要素数と一致します。ただし、キーワード引数 initial が指定されていれば、 iterable の要素は最初に initial 値を持つため、出力は入力されたイテラブルよりも要素を1つ多く持ちます。

およそ次と等価です:

def accumulate(iterable, func=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 = func(total, element)
        yield total

There are a number of uses for the func argument. It can be set to min() for a running minimum, max() for a running maximum, or operator.mul() for a running product. Amortization tables can be built by accumulating interest and applying payments:

>>> data = [3, 4, 6, 2, 1, 9, 0, 7, 5, 8]
>>> list(accumulate(data, operator.mul))     # running product
[3, 12, 72, 144, 144, 1296, 0, 0, 0, 0]
>>> list(accumulate(data, max))              # running maximum
[3, 4, 6, 6, 6, 9, 9, 9, 9, 9]

# Amortize a 5% loan of 1000 with 10 annual payments of 90
>>> account_update = lambda bal, pmt: round(bal * 1.05) + pmt
>>> list(accumulate(repeat(-90, 10), account_update, initial=1_000))
[1000, 960, 918, 874, 828, 779, 728, 674, 618, 559, 497]

最終的な累積値だけを返す類似の関数については functools.reduce() を見てください。

Added in version 3.2.

バージョン 3.3 で変更: オプションの func 引数が追加されました。

バージョン 3.8 で変更: オプションの initial パラメータが追加されました。

itertools.batched(iterable, n)

iterable から得られるデータを n 個ごとに一つのタプルにまとめます。一番最後のバッチは n 個より少なくなる可能性があります。

入力の iterable から要素を一つづつ取り出し、サイズが n になるまでタプルに溜め込みます。入力の iterable は遅延評価され、次のタプルを作るのに必要なだけ要素が取り出されます。タプルは、個数が n に到達するか、入力の iterable が尽きるとすぐに出力されます:

>>> flattened_data = ['roses', 'red', 'violets', 'blue', 'sugar', 'sweet']
>>> unflattened = list(batched(flattened_data, 2))
>>> unflattened
[('roses', 'red'), ('violets', 'blue'), ('sugar', 'sweet')]

>>> for batch in batched('ABCDEFG', 3):
...     print(batch)
...
('A', 'B', 'C')
('D', 'E', 'F')
('G',)

およそ次と等価です:

def batched(iterable, n):
    # batched('ABCDEFG', 3) → ABC DEF G
    if n < 1:
        raise ValueError('n must be at least one')
    it = iter(iterable)
    while batch := tuple(islice(it, n)):
        yield batch

Added in version 3.12.

itertools.chain(*iterables)

先頭の iterable の全要素を返し、次に2番目の iterable の全要素を返し、と全 iterable の要素を返すイテレータを作成します。連続したシーケンスを一つのシーケンスとして扱う場合に使用します。およそ次と等価です:

def chain(*iterables):
    # chain('ABC', 'DEF') → A B C D E F
    for iterable in iterables:
        yield from iterable

classmethod chain.from_iterable(iterable)

chain() のためのもう一つのコンストラクタです。遅延評価される iterable 引数一つから連鎖した入力を受け取ります。この関数は、以下のコードとほぼ等価です:

def from_iterable(iterables):
    # chain.from_iterable(['ABC', 'DEF']) → A B C D E F
    for iterable in iterables:
        yield from iterable

itertools.combinations(iterable, r)

入力 iterable の要素からなる長さ r の部分列を返します。

組合せ(combination)は入力 iterable に応じた辞書式順序で出力されます。したがって、入力 iterable がソートされていれば、出力されるタプルもソートされた順番で生成されます。

各要素は場所に基づいて一意に取り扱われ、値にはよりません。入力された要素がバラバラなら各組合せの中に重複した値は現れません。

およそ次と等価です:

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)

combinations() のコードは permutations() のシーケンスから (入力プールでの位置に応じた順序で) 要素がソートされていないものをフィルターしたようにも表現できます:

def combinations(iterable, r):
    pool = tuple(iterable)
    n = len(pool)
    for indices in permutations(range(n), r):
        if sorted(indices) == list(indices):
            yield tuple(pool[i] for i in indices)

返される要素の数は、0 <= r <= n の場合は、n! / r! / (n-r)! で、r > n の場合は 0 です。

itertools.combinations_with_replacement(iterable, r)

入力 iterable から、それぞれの要素が複数回現れることを許して、長さ r の要素の部分列を返します。

組合せ(combination)は入力 iterable に応じた辞書式順序で出力されます。したがって、入力 iterable がソートされていれば、出力されるタプルもソートされた順番で生成されます。

要素は、値ではなく位置に基づいて一意に扱われます。ですから、入力の要素が一意であれば、生成された組合せも一意になります。

およそ次と等価です:

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)

combinations_with_replacement() のコードは、 product() の部分列から、要素が (入力プールの位置に従って) ソートされた順になっていない項目をフィルタリングしたものとしても表せます:

def combinations_with_replacement(iterable, r):
    pool = tuple(iterable)
    n = len(pool)
    for indices in product(range(n), repeat=r):
        if sorted(indices) == list(indices):
            yield tuple(pool[i] for i in indices)

返される要素の数は、n > 0 のとき (n+r-1)! / r! / (n-1)! です。

Added in version 3.1.

itertools.compress(data, selectors)

data の要素から selectors の対応する要素が True と評価されるものだけをフィルタしたイテレータを作ります。data と selectors のいずれかが尽きたときに止まります。およそ次と等価です:

def compress(data, selectors):
    # compress('ABCDEF', [1,0,1,0,1,1]) → A C E F
    return (d for d, s in zip(data, selectors) if s)

Added in version 3.1.

itertools.count(start=0, step=1)

数 start で始まる等間隔の値を返すイテレータを作成します。map() に渡して連続したデータを生成するのによく使われます。 また、 zip() に連続した番号を追加するのにも使われます。 およそ次と等価です:

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

浮動小数点数でカウントするときは (start + step * i for i in count()) のように掛け算を使ったコードに置き換えたほうが正確にできることがあります。

バージョン 3.1 で変更: step 引数が追加され、非整数の引数が許されるようになりました。

itertools.cycle(iterable)

iterable から要素を取得し、そのコピーを保存するイテレータを作成します。iterable の全要素を返すと、セーブされたコピーから要素を返します。これを無限に繰り返します。およそ次と等価です:

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

cycle() は大きなメモリ領域を使用します。使用するメモリ量は iterable の大きさに依存します。

itertools.dropwhile(predicate, iterable)

predicate (述語) が真である間は要素を飛ばし、その後は全ての要素を返すイテレータを作成します。このイテレータは、predicate が最初に偽になるまで 全く 要素を返さないため、要素を返し始めるまでに長い時間がかかる場合があります。およそ次と等価です:

def dropwhile(predicate, iterable):
    # dropwhile(lambda x: x<5, [1,4,6,4,1]) → 6 4 1
    iterable = iter(iterable)
    for x in iterable:
        if not predicate(x):
            yield x
            break
    for x in iterable:
        yield x

itertools.filterfalse(predicate, iterable)

iterable から predicate が偽となる要素だけを返すイテレータを作成します。predicate が None の場合、偽の要素だけを返します。およそ次と等価です:

def filterfalse(predicate, iterable):
    # filterfalse(lambda x: x%2, range(10)) → 0 2 4 6 8
    if predicate is None:
        predicate = bool
    for x in iterable:
        if not predicate(x):
            yield x

itertools.groupby(iterable, key=None)

同じキーをもつような要素からなる iterable 中のグループに対して、キーとグループを返すようなイテレータを作成します。key は各要素に対するキー値を計算する関数です。キーを指定しない場合や None にした場合、key 関数のデフォルトは恒等関数になり要素をそのまま返します。通常、iterable は同じキー関数でソート済みである必要があります。

groupby() の操作は Unix の uniq フィルターと似ています。 key 関数の値が変わるたびに休止または新しいグループを生成します (このために通常同じ key 関数でソートしておく必要があるのです)。この動作は SQL の入力順に関係なく共通の要素を集約する GROUP BY とは違います。

返されるグループはそれ自体がイテレータで、 groupby() と iterable を共有しています。もととなる iterable を共有しているため、 groupby() オブジェクトの要素取り出しを先に進めると、それ以前の要素であるグループは見えなくなってしまいます。従って、データが後で必要な場合にはリストの形で保存しておく必要があります:

groups = []
uniquekeys = []
data = sorted(data, key=keyfunc)
for k, g in groupby(data, keyfunc):
    groups.append(list(g))      # Store group iterator as a list
    uniquekeys.append(k)

groupby() はおよそ次と等価です:

class groupby:
    # [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

    def __init__(self, iterable, key=None):
        if key is None:
            key = lambda x: x
        self.keyfunc = key
        self.it = iter(iterable)
        self.tgtkey = self.currkey = self.currvalue = object()

    def __iter__(self):
        return self

    def __next__(self):
        self.id = object()
        while self.currkey == self.tgtkey:
            self.currvalue = next(self.it)    # Exit on StopIteration
            self.currkey = self.keyfunc(self.currvalue)
        self.tgtkey = self.currkey
        return (self.currkey, self._grouper(self.tgtkey, self.id))

    def _grouper(self, tgtkey, id):
        while self.id is id and self.currkey == tgtkey:
            yield self.currvalue
            try:
                self.currvalue = next(self.it)
            except StopIteration:
                return
            self.currkey = self.keyfunc(self.currvalue)

itertools.islice(iterable, stop)

itertools.islice(iterable, start, stop[, step])

Make an iterator that returns selected elements from the iterable. If start is non-zero, then elements from the iterable are skipped until start is reached. Afterward, elements are returned consecutively unless step is set higher than one which results in items being skipped. If stop is None, then iteration continues until the iterator is exhausted, if at all; otherwise, it stops at the specified position.

start が None の場合、イテレーションは0から始まります。step が None の場合、ステップはデフォルトの1になります。

Unlike regular slicing, islice() does not support negative values for start, stop, or step. Can be used to extract related fields from data where the internal structure has been flattened (for example, a multi-line report may list a name field on every third line).

およそ次と等価です:

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(stop, start))
    next_i = start
    for i, element in zip(indices, iterable):
        if i == next_i:
            yield element
            next_i += step

itertools.pairwise(iterable)

Return successive overlapping pairs taken from the input iterable.

The number of 2-tuples in the output iterator will be one fewer than the number of inputs. It will be empty if the input iterable has fewer than two values.

およそ次と等価です:

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

Added in version 3.10.

itertools.permutations(iterable, r=None)

iterable の要素からなる長さ r の順列 (permutation) を連続的に返します。

r が指定されない場合や None の場合、r はデフォルトで iterable の長さとなり、可能な最長の順列の全てが生成されます。

順列(permutation)は入力 iterable に応じた辞書式順序で出力されます。したがって、入力 iterable がソートされていれば、出力されるタプルもソートされた順番で生成されます。

Elements are treated as unique based on their position, not on their value. So if the input elements are unique, there will be no repeated values within a permutation.

およそ次と等価です:

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

permutations() のコードは product() の列から重複 (それらは入力プールの同じ位置から取られたものです) を除くようフィルタしたものとしても表現できます:

def permutations(iterable, r=None):
    pool = tuple(iterable)
    n = len(pool)
    r = n if r is None else r
    for indices in product(range(n), repeat=r):
        if len(set(indices)) == r:
            yield tuple(pool[i] for i in indices)

返される要素の数は、0 <= r <= n の場合 n! / (n-r)! で、r > n の場合は 0 です。

itertools.product(*iterables, repeat=1)

入力イテラブルのデカルト積です。

ジェネレータ式の入れ子になった for ループとおよそ等価です。たとえば product(A, B) は ((x,y) for x in A for y in B) と同じものを返します。

入れ子ループは走行距離計と同じように右端の要素がイテレーションごとに更新されていきます。このパターンは辞書式順序を作り出し、入力のイテレート可能オブジェクトたちがソートされていれば、直積タプルもソートされた順に出てきます。

イテラブル自身との直積を計算するためには、オプションの repeat キーワード引数に繰り返し回数を指定します。たとえば product(A, repeat=4) は product(A, A, A, A) と同じ意味です。

この関数は以下のコードとおよそ等価ですが、実際の実装ではメモリ中に中間結果を作りません:

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

product() は動作する前に、入力のイテラブルを完全に読み取り、直積を生成するためにメモリ内に値を蓄えます。したがって、入力が有限の場合に限り有用です。

itertools.repeat(object[, times])

Make an iterator that returns object over and over again. Runs indefinitely unless the times argument is specified.

およそ次と等価です:

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

repeat は map や zip に定数のストリームを与えるためによく利用されます:

>>> list(map(pow, range(10), repeat(2)))
[0, 1, 4, 9, 16, 25, 36, 49, 64, 81]

itertools.starmap(function, iterable)

Make an iterator that computes the function using arguments obtained from the iterable. Used instead of map() when argument parameters are already grouped in tuples from a single iterable (when the data has been "pre-zipped").

The difference between map() and starmap() parallels the distinction between function(a,b) and function(*c). Roughly equivalent to:

def starmap(function, iterable):
    # starmap(pow, [(2,5), (3,2), (10,3)]) → 32 9 1000
    for args in iterable:
        yield function(*args)

itertools.takewhile(predicate, iterable)

predicate が真である限り iterable から要素を返すイテレータを作成します。およそ次と等価です:

def takewhile(predicate, iterable):
    # takewhile(lambda x: x<5, [1,4,6,4,1]) → 1 4
    for x in iterable:
        if predicate(x):
            yield x
        else:
            break

Note, the element that first fails the predicate condition is consumed from the input iterator and there is no way to access it. This could be an issue if an application wants to further consume the input iterator after takewhile has been run to exhaustion. To work around this problem, consider using more-iterools before_and_after() [https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.before_and_after] instead.

itertools.tee(iterable, n=2)

一つの iterable から n 個の独立したイテレータを返します。

およそ次と等価です:

def tee(iterable, n=2):
    iterator = iter(iterable)
    shared_link = [None, None]
    return tuple(_tee(iterator, shared_link) for _ in range(n))

def _tee(iterator, link):
    try:
        while True:
            if link[1] is None:
                link[0] = next(iterator)
                link[1] = [None, None]
            value, link = link
            yield value
    except StopIteration:
        return

一度 tee() が生成されたら、もとの iterable を他で使ってはいけません。さもなければ、 tee() オブジェクトの知らない間に iterable が先の要素に進んでしまうことになります。

tee iterators are not threadsafe. A RuntimeError may be raised when simultaneously using iterators returned by the same tee() call, even if the original iterable is threadsafe.

tee() はかなり大きなメモリ領域を使用するかもしれません (使用するメモリ量はiterableの大きさに依存します)。一般には、一つのイテレータが他のイテレータよりも先にほとんどまたは全ての要素を消費するような場合には、 tee() よりも list() を使った方が高速です。

itertools.zip_longest(*iterables, fillvalue=None)

各 iterable の要素をまとめるイテレータを作成します。iterable の長さが違う場合、足りない値は fillvalue で埋められます。最も長い itarable が尽きるまでイテレーションします。およそ次と等価です:

def zip_longest(*iterables, fillvalue=None):
    # zip_longest('ABCD', 'xy', fillvalue='-') → Ax By C- D-
    iterators = [iter(it) for it in 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)

iterables の1つが無限になりうる場合 zip_longest() は呼び出し回数を制限するような何かでラップしなければいけません(例えば islice() or takewhile())。 fillvalue は指定しない場合のデフォルトは None です。

Itertools レシピ

この節では、既存の itertools を素材としてツールセットを拡張するためのレシピを示します。

The primary purpose of the itertools recipes is educational. The recipes show various ways of thinking about individual tools — for example, that chain.from_iterable is related to the concept of flattening. The recipes also give ideas about ways that the tools can be combined — for example, how starmap() and repeat() can work together. The recipes also show patterns for using itertools with the operator and collections modules as well as with the built-in itertools such as map(), filter(), reversed(), and enumerate().

A secondary purpose of the recipes is to serve as an incubator. The accumulate(), compress(), and pairwise() itertools started out as recipes. Currently, the sliding_window(), iter_index(), and sieve() recipes are being tested to see whether they prove their worth.

Substantially all of these recipes and many, many others can be installed from the more-itertools [https://pypi.org/project/more-itertools/] project found on the Python Package Index:

python -m pip install more-itertools

Many of the recipes offer the same high performance as the underlying toolset. Superior memory performance is kept by processing elements one at a time rather than bringing the whole iterable into memory all at once. Code volume is kept small by linking the tools together in a functional style [https://www.cs.kent.ac.uk/people/staff/dat/miranda/whyfp90.pdf]. High speed is retained by preferring "vectorized" building blocks over the use of for-loops and generators which incur interpreter overhead.

import collections
import contextlib
import functools
import math
import operator
import random

def take(n, iterable):
    "Return first n items of the iterable as a list."
    return list(islice(iterable, n))

def prepend(value, iterable):
    "Prepend a single value in front of an iterable."
    # prepend(1, [2, 3, 4]) → 1 2 3 4
    return chain([value], iterable)

def tabulate(function, start=0):
    "Return function(0), function(1), ..."
    return map(function, count(start))

def repeatfunc(func, times=None, *args):
    "Repeat calls to func with specified arguments."
    if times is None:
        return starmap(func, repeat(args))
    return starmap(func, repeat(args, times))

def flatten(list_of_lists):
    "Flatten one level of nesting."
    return chain.from_iterable(list_of_lists)

def ncycles(iterable, n):
    "Returns the sequence elements n times."
    return chain.from_iterable(repeat(tuple(iterable), n))

def tail(n, iterable):
    "Return an iterator over the last n items."
    # tail(3, 'ABCDEFG') → E F G
    return iter(collections.deque(iterable, maxlen=n))

def consume(iterator, n=None):
    "Advance the iterator n-steps ahead. If n is None, consume entirely."
    # Use functions that consume iterators at C speed.
    if n is None:
        collections.deque(iterator, maxlen=0)
    else:
        next(islice(iterator, n, n), None)

def nth(iterable, n, default=None):
    "Returns the nth item or a default value."
    return next(islice(iterable, n, None), default)

def quantify(iterable, predicate=bool):
    "Given a predicate that returns True or False, count the True results."
    return sum(map(predicate, iterable))

def first_true(iterable, default=False, predicate=None):
    "Returns the first true value or the *default* if there is no true value."
    # first_true([a,b,c], x) → a or b or c or x
    # first_true([a,b], x, f) → a if f(a) else b if f(b) else x
    return next(filter(predicate, iterable), default)

def all_equal(iterable, key=None):
    "Returns True if all the elements are equal to each other."
    # all_equal('4٤௪౪໔', key=int) → True
    return len(take(2, groupby(iterable, key))) <= 1

def unique_justseen(iterable, key=None):
    "List unique elements, preserving order. Remember only the element just seen."
    # unique_justseen('AAAABBBCCDAABBB') → A B C D A B
    # unique_justseen('ABBcCAD', str.casefold) → A B c A D
    if key is None:
        return map(operator.itemgetter(0), groupby(iterable))
    return map(next, map(operator.itemgetter(1), groupby(iterable, key)))

def unique_everseen(iterable, key=None):
    "List unique elements, preserving order. Remember all elements ever seen."
    # unique_everseen('AAAABBBCCDAABBB') → A B C D
    # unique_everseen('ABBcCAD', str.casefold) → A B c D
    seen = set()
    if key is None:
        for element in filterfalse(seen.__contains__, iterable):
            seen.add(element)
            yield element
    else:
        for element in iterable:
            k = key(element)
            if k not in seen:
                seen.add(k)
                yield element

def sliding_window(iterable, n):
    "Collect data into overlapping fixed-length chunks or blocks."
    # sliding_window('ABCDEFG', 4) → ABCD BCDE CDEF DEFG
    iterator = iter(iterable)
    window = collections.deque(islice(iterator, n - 1), maxlen=n)
    for x in iterator:
        window.append(x)
        yield tuple(window)

def grouper(iterable, n, *, incomplete='fill', fillvalue=None):
    "Collect data into non-overlapping fixed-length chunks or blocks."
    # grouper('ABCDEFG', 3, fillvalue='x') → ABC DEF Gxx
    # grouper('ABCDEFG', 3, incomplete='strict') → ABC DEF ValueError
    # grouper('ABCDEFG', 3, incomplete='ignore') → ABC DEF
    iterators = [iter(iterable)] * n
    match incomplete:
        case 'fill':
            return zip_longest(*iterators, fillvalue=fillvalue)
        case 'strict':
            return zip(*iterators, strict=True)
        case 'ignore':
            return zip(*iterators)
        case _:
            raise ValueError('Expected fill, strict, or ignore')

def roundrobin(*iterables):
    "Visit input iterables in a cycle until each is exhausted."
    # roundrobin('ABC', 'D', 'EF') → A D E B F C
    # Algorithm credited to George Sakkis
    iterators = map(iter, iterables)
    for num_active in range(len(iterables), 0, -1):
        iterators = cycle(islice(iterators, num_active))
        yield from map(next, iterators)

def partition(predicate, iterable):
    """Partition entries into false entries and true entries.

    If *predicate* is slow, consider wrapping it with functools.lru_cache().
    """
    # partition(is_odd, range(10)) → 0 2 4 6 8   and  1 3 5 7 9
    t1, t2 = tee(iterable)
    return filterfalse(predicate, t1), filter(predicate, t2)

def subslices(seq):
    "Return all contiguous non-empty subslices of a sequence."
    # subslices('ABCD') → A AB ABC ABCD B BC BCD C CD D
    slices = starmap(slice, combinations(range(len(seq) + 1), 2))
    return map(operator.getitem, repeat(seq), slices)

def iter_index(iterable, value, start=0, stop=None):
    "Return indices where a value occurs in a sequence or iterable."
    # iter_index('AABCADEAF', 'A') → 0 1 4 7
    seq_index = getattr(iterable, 'index', None)
    if seq_index is None:
        iterator = islice(iterable, start, stop)
        for i, element in enumerate(iterator, start):
            if element is value or element == value:
                yield i
    else:
        stop = len(iterable) if stop is None else stop
        i = start
        with contextlib.suppress(ValueError):
            while True:
                yield (i := seq_index(value, i, stop))
                i += 1

def iter_except(func, exception, first=None):
    "Convert a call-until-exception interface to an iterator interface."
    # iter_except(d.popitem, KeyError) → non-blocking dictionary iterator
    with contextlib.suppress(exception):
        if first is not None:
            yield first()
        while True:
            yield func()

The following recipes have a more mathematical flavor:

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):
    "Add up the squares of the input values."
    # sum_of_squares([10, 20, 30]) → 1400
    return math.sumprod(*tee(iterable))

def reshape(matrix, cols):
    "Reshape a 2-D matrix to have a given number of columns."
    # reshape([(0, 1), (2, 3), (4, 5)], 3) →  (0, 1, 2), (3, 4, 5)
    return batched(chain.from_iterable(matrix), cols)

def transpose(matrix):
    "Swap the rows and columns of a 2-D matrix."
    # transpose([(1, 2, 3), (11, 22, 33)]) → (1, 11) (2, 22) (3, 33)
    return zip(*matrix, strict=True)

def matmul(m1, m2):
    "Multiply two matrices."
    # matmul([(7, 5), (3, 5)], [(2, 5), (7, 9)]) → (49, 80), (41, 60)
    n = len(m2[0])
    return batched(starmap(math.sumprod, product(m1, transpose(m2))), n)

def convolve(signal, kernel):
    """Discrete linear convolution of two iterables.
    Equivalent to polynomial multiplication.

    Convolutions are mathematically commutative; however, the inputs are
    evaluated differently.  The signal is consumed lazily and can be
    infinite. The kernel is fully consumed before the calculations begin.

    Article:  https://betterexplained.com/articles/intuitive-convolution/
    Video:    https://www.youtube.com/watch?v=KuXjwB4LzSA
    """
    # convolve([1, -1, -20], [1, -3]) → 1 -4 -17 60
    # convolve(data, [0.25, 0.25, 0.25, 0.25]) → Moving average (blur)
    # convolve(data, [1/2, 0, -1/2]) → 1st derivative estimate
    # convolve(data, [1, -2, 1]) → 2nd derivative estimate
    kernel = tuple(kernel)[::-1]
    n = len(kernel)
    padded_signal = chain(repeat(0, n-1), signal, repeat(0, n-1))
    windowed_signal = sliding_window(padded_signal, n)
    return map(math.sumprod, repeat(kernel), windowed_signal)

def polynomial_from_roots(roots):
    """Compute a polynomial's coefficients from its roots.

       (x - 5) (x + 4) (x - 3)  expands to:   x³ -4x² -17x + 60
    """
    # polynomial_from_roots([5, -4, 3]) → [1, -4, -17, 60]
    factors = zip(repeat(1), map(operator.neg, roots))
    return list(functools.reduce(convolve, factors, [1]))

def polynomial_eval(coefficients, x):
    """Evaluate a polynomial at a specific value.

    Computes with better numeric stability than Horner's method.
    """
    # Evaluate x³ -4x² -17x + 60 at x = 5
    # polynomial_eval([1, -4, -17, 60], x=5) → 0
    n = len(coefficients)
    if not n:
        return type(x)(0)
    powers = map(pow, repeat(x), reversed(range(n)))
    return math.sumprod(coefficients, powers)

def polynomial_derivative(coefficients):
    """Compute the first derivative of a polynomial.

       f(x)  =  x³ -4x² -17x + 60
       f'(x) = 3x² -8x  -17
    """
    # polynomial_derivative([1, -4, -17, 60]) → [3, -8, -17]
    n = len(coefficients)
    powers = reversed(range(1, n))
    return list(map(operator.mul, coefficients, powers))

def sieve(n):
    "Primes less than n."
    # sieve(30) → 2 3 5 7 11 13 17 19 23 29
    if n > 2:
        yield 2
    data = bytearray((0, 1)) * (n // 2)
    for p in iter_index(data, 1, start=3, stop=math.isqrt(n) + 1):
        data[p*p : n : p+p] = bytes(len(range(p*p, n, p+p)))
    yield from iter_index(data, 1, start=3)

def factor(n):
    "Prime factors of n."
    # factor(99) → 3 3 11
    # factor(1_000_000_000_000_007) → 47 59 360620266859
    # factor(1_000_000_000_000_403) → 1000000000000403
    for prime in sieve(math.isqrt(n) + 1):
        while not n % prime:
            yield prime
            n //= prime
            if n == 1:
                return
    if n > 1:
        yield n

def totient(n):
    "Count of natural numbers up to n that are coprime to n."
    # https://mathworld.wolfram.com/TotientFunction.html
    # totient(12) → 4 because len([1, 5, 7, 11]) == 4
    for prime in set(factor(n)):
        n -= n // prime
    return n

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

ソースコード: Lib/functools.py [https://github.com/python/cpython/tree/3.12/Lib/functools.py]

functools モジュールは高階関数、つまり関数に影響を及ぼしたり他の関数を返したりする関数のためのものです。一般に、どんな呼び出し可能オブジェクトでもこのモジュールの目的には関数として扱えます。

モジュール functools は以下の関数を定義します:

@functools.cache(user_function)

簡単で軽量な無制限の関数キャッシュです。 "メモ化 (memoize)" [https://en.wikipedia.org/wiki/Memoization] とも呼ばれることがあります。

lru_cache(maxsize=None) と同じ関数を返し、関数の引数に対するルックアップ辞書を含む薄いラッパーを生成します。キャッシュ上の古い値を追い出す必要がないため、キャッシュサイズに制限のある lru_cache() よりも軽量で高速です。

例えば:

@cache
def factorial(n):
    return n * factorial(n-1) if n else 1

>>> factorial(10)      # no previously cached result, makes 11 recursive calls
3628800
>>> factorial(5)       # just looks up cached value result
120
>>> factorial(12)      # makes two new recursive calls, the other 10 are cached
479001600

The cache is threadsafe so that the wrapped function can be used in multiple threads. This means that the underlying data structure will remain coherent during concurrent updates.

It is possible for the wrapped function to be called more than once if another thread makes an additional call before the initial call has been completed and cached.

Added in version 3.9.

@functools.cached_property(func)

クラスのメソッドを、値を一度だけ計算して通常の属性としてキャッシュするプロパティに変換します。キャッシュはインスタンスの生存期間にわたって有効です。property() に似ていて、さらにキャッシュを行います。計算コストが高く、一度計算すればその後は不変であるようなインスタンスのプロパティに対して有用です。

以下はプログラム例です:

class DataSet:

    def __init__(self, sequence_of_numbers):
        self._data = tuple(sequence_of_numbers)

    @cached_property
    def stdev(self):
        return statistics.stdev(self._data)

cached_property() のしくみは property() とやや異なります。通常のプロパティは、セッター (setter) が定義されない限り書き込みを禁止します。対照的に、 cached_property は書き込みを許します。

cached_property デコレータはルックアップテーブルで、同名の属性が存在しない場合のみ動作します。動作した場合、 cached_property は同名の属性に書き込みを行います。その後の属性の読み込みと書き込みは cached_property メソッドより優先され、通常の属性のように働きます。

キャッシュされた値は属性を削除することで取り除くことができます。これにより cached_property メソッドを再度実行することが可能になります。

The cached_property does not prevent a possible race condition in multi-threaded usage. The getter function could run more than once on the same instance, with the latest run setting the cached value. If the cached property is idempotent or otherwise not harmful to run more than once on an instance, this is fine. If synchronization is needed, implement the necessary locking inside the decorated getter function or around the cached property access.

このデコレータは PEP 412 [https://peps.python.org/pep-0412/] のキー共有辞書のインターフェースを持ちます。これは、インスタンス辞書がより多くのスペースを使う可能性があることを意味します。

また、このデコレータは各インスタンスの __dict__ 属性が可変のマッピングであることを要求します。すなわち、このデコレータはいくつかの型、たとえばメタクラス (型インスタンスの __dict__ 属性はクラスの名前空間に対する読み込み専用のプロキシであるため) や、 __slots__ を指定していてその中に __dict__ を含まない型 (それ自体が __dict__ 属性を提供しないため) に対しては動作しないことを意味します。

If a mutable mapping is not available or if space-efficient key sharing is desired, an effect similar to cached_property() can also be achieved by stacking property() on top of lru_cache(). See メソッド呼び出しをキャッシュするには どうしたらいいですか？ for more details on how this differs from cached_property().

Added in version 3.8.

バージョン 3.12 で変更: Prior to Python 3.12, cached_property included an undocumented lock to ensure that in multi-threaded usage the getter function was guaranteed to run only once per instance. However, the lock was per-property, not per-instance, which could result in unacceptably high lock contention. In Python 3.12+ this locking is removed.

functools.cmp_to_key(func)

古いスタイルの比較関数を key function に変換します。key 関数を受け取るツール (sorted(), min(), max(), heapq.nlargest(), heapq.nsmallest(), itertools.groupby() など) と共に使用します。この関数は、主に比較関数を使っていた Python 2 からプログラムの移行のための変換ツールとして使われます。

比較関数は2つの引数を受け取り、それらを比較し、 "より小さい" 場合は負の数を、同値の場合には 0 を、 "より大きい" 場合には正の数を返す、あらゆる呼び出し可能オブジェクトです。key 関数は呼び出し可能オブジェクトで、1つの引数を受け取り、ソートキーとして使われる値を返します。

以下はプログラム例です:

sorted(iterable, key=cmp_to_key(locale.strcoll))  # locale-aware sort order

ソートの例と簡単なチュートリアルは Sorting Techniques を参照して下さい。

Added in version 3.2.

@functools.lru_cache(user_function)

@functools.lru_cache(maxsize=128, typed=False)

関数をメモ化用の呼び出し可能オブジェクトでラップし、最近の呼び出し最大 maxsize 回まで保存するするデコレータです。高価な関数や I/O に束縛されている関数を定期的に同じ引数で呼び出すときに、時間を節約できます。

The cache is threadsafe so that the wrapped function can be used in multiple threads. This means that the underlying data structure will remain coherent during concurrent updates.

It is possible for the wrapped function to be called more than once if another thread makes an additional call before the initial call has been completed and cached.

結果のキャッシュには辞書が使われるので、関数の位置引数およびキーワード引数は ハッシュ可能 でなくてはなりません。

引数のパターンが異なる場合は、異なる呼び出しと見なされ別々のキャッシュエントリーとなります。例えば、 f(a=1, b=2) と f(b=2, a=1) はキーワード引数の順序が異なっているので、2つの別個のキャッシュエントリーになります。

user_function が指定された場合、それは呼び出し可能でなければなりません。これにより lru_cache デコレータがユーザー関数に直接適用できるようになります。このとき maxsize の値はデフォルトの 128 となります:

@lru_cache
def count_vowels(sentence):
    return sum(sentence.count(vowel) for vowel in 'AEIOUaeiou')

maxsize が None に設定された場合は、LRU 機能は無効化され、キャッシュは際限無く大きくなります。

If typed is set to true, function arguments of different types will be cached separately. If typed is false, the implementation will usually regard them as equivalent calls and only cache a single result. (Some types such as str and int may be cached separately even when typed is false.)

Note, type specificity applies only to the function's immediate arguments rather than their contents. The scalar arguments, Decimal(42) and Fraction(42) are be treated as distinct calls with distinct results. In contrast, the tuple arguments ('answer', Decimal(42)) and ('answer', Fraction(42)) are treated as equivalent.

The wrapped function is instrumented with a cache_parameters() function that returns a new dict showing the values for maxsize and typed. This is for information purposes only. Mutating the values has no effect.

キャッシュ効率の測定や maxsize パラメータの調整をしやすくするため、ラップされた関数には cache_info() 関数が追加されます。この関数は hits, misses, maxsize, currsize を示す named tuple を返します。

このデコレータは、キャッシュの削除と無効化のための cache_clear() 関数も提供します。

元々の基底の関数には、 __wrapped__ 属性を通してアクセスできます。これはキャッシュを回避して、または関数を別のキャッシュでラップして、内観するのに便利です。

The cache keeps references to the arguments and return values until they age out of the cache or until the cache is cleared.

If a method is cached, the self instance argument is included in the cache. See メソッド呼び出しをキャッシュするには どうしたらいいですか？

LRU (least recently used) キャッシュ [https://en.wikipedia.org/wiki/Cache_replacement_policies#Least_recently_used_(LRU)] は、最も新しい呼び出しが次の呼び出しで最も現れやすいとき (例えば、最もニュースサーバの人気の記事が日ごとに変わる傾向にある場合) に最も最も効率よくはたらきます。キャッシュのサイズ制限は、キャッシュがウェブサーバの長期間に渡るプロセスにおける限界を超えては大きくならないことを保証します。

In general, the LRU cache should only be used when you want to reuse previously computed values. Accordingly, it doesn't make sense to cache functions with side-effects, functions that need to create distinct mutable objects on each call (such as generators and async functions), or impure functions such as time() or random().

静的 web コンテンツ の LRU キャッシュの例:

@lru_cache(maxsize=32)
def get_pep(num):
    'Retrieve text of a Python Enhancement Proposal'
    resource = f'https://peps.python.org/pep-{num:04d}'
    try:
        with urllib.request.urlopen(resource) as s:
            return s.read()
    except urllib.error.HTTPError:
        return 'Not Found'

>>> for n in 8, 290, 308, 320, 8, 218, 320, 279, 289, 320, 9991:
...     pep = get_pep(n)
...     print(n, len(pep))

>>> get_pep.cache_info()
CacheInfo(hits=3, misses=8, maxsize=32, currsize=8)

キャッシュを使って 動的計画法 [https://ja.wikipedia.org/wiki/動的計画法] の技法を実装し、フィボナッチ数 [https://ja.wikipedia.org/wiki/フィボナッチ数] を効率よく計算する例:

@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)

Added in version 3.2.

バージョン 3.3 で変更: typed オプションが追加されました。

バージョン 3.8 で変更: user_function オプションが追加されました。

バージョン 3.9 で変更: Added the function cache_parameters()

@functools.total_ordering

ひとつ以上の拡張順序比較メソッド (rich comparison ordering methods) を定義したクラスを受け取り、残りを実装するクラスデコレータです。このデコレータは全ての拡張順序比較演算をサポートするための労力を軽減します:

引数のクラスは、 __lt__(), __le__(), __gt__(), __ge__() の中からどれか1つと、 __eq__() メソッドを定義する必要があります。

例えば:

@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()))

注釈

このデコレータにより、完全に順序の付いた振る舞いの良い型を簡単に作ることができますが、実行速度は遅くなり、派生した比較メソッドのスタックトレースは複雑になります。性能ベンチマークにより、これがアプリケーションのボトルネックになっていることがわかった場合は、代わりに 6 つの拡張比較メソッドをすべて実装すれば、簡単にスピードアップを図れるでしょう。

注釈

This decorator makes no attempt to override methods that have been declared in the class or its superclasses. Meaning that if a superclass defines a comparison operator, total_ordering will not implement it again, even if the original method is abstract.

Added in version 3.2.

バージョン 3.4 で変更: Returning NotImplemented from the underlying comparison function for unrecognised types is now supported.

functools.partial(func, /, *args, **keywords)

新しい partial オブジェクト を返します。このオブジェクトは呼び出されると位置引数 args とキーワード引数 keywords 付きで呼び出された func のように振る舞います。呼び出しに際してさらなる引数が渡された場合、それらは args に付け加えられます。追加のキーワード引数が渡された場合には、それらで keywords を拡張または上書きします。おおよそ次のコードと等価です:

def partial(func, /, *args, **keywords):
    def newfunc(*fargs, **fkeywords):
        newkeywords = {**keywords, **fkeywords}
        return func(*args, *fargs, **newkeywords)
    newfunc.func = func
    newfunc.args = args
    newfunc.keywords = keywords
    return newfunc

関数 partial() は、関数の位置引数・キーワード引数の一部を「凍結」した部分適用として使われ、簡素化された引数形式をもった新たなオブジェクトを作り出します。例えば、 partial() を使って base 引数のデフォルトが 2 である int() 関数のように振る舞う呼び出し可能オブジェクトを作ることができます:

>>> from functools import partial
>>> basetwo = partial(int, base=2)
>>> basetwo.__doc__ = 'Convert base 2 string to an int.'
>>> basetwo('10010')
18

class functools.partialmethod(func, /, *args, **keywords)

partial と似た動作をする新しい partialmethod 記述子 (デスクリプタ) を返します。直接呼び出しではなく、メソッド定義としての使用が目的であることのみが、partial とは異なります。

func は、descriptor または呼び出し可能オブジェクトである必要があります (通常の関数など、両方の性質を持つオブジェクトは記述子として扱われます。)

func が記述子 (Python の通常の関数、 classmethod()、staticmethod()、abstractmethod() または別の partialmethod のインスタンスなど) の場合、 __get__ への呼び出しは下層の記述子に委譲され、返り値として適切な partial オブジェクト が返されます。

func が記述子以外の呼び出し可能オブジェクトである場合、適切な束縛メソッドが動的に作成されます。この func は、メソッドとして使用された場合、Python の通常の関数と同様に動作します。 partialmethod コンストラクタに args と keywords が渡されるよりも前に、 self 引数が最初の位置引数として挿入されます。

以下はプログラム例です:

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

Added in version 3.4.

functools.reduce(function, iterable[, initializer])

Apply function of two arguments cumulatively to the items of iterable, from left to right, so as to reduce the iterable to a single value. For example, reduce(lambda x, y: x+y, [1, 2, 3, 4, 5]) calculates ((((1+2)+3)+4)+5). The left argument, x, is the accumulated value and the right argument, y, is the update value from the iterable. If the optional initializer is present, it is placed before the items of the iterable in the calculation, and serves as a default when the iterable is empty. If initializer is not given and iterable contains only one item, the first item is returned.

およそ次と等価です:

def reduce(function, iterable, initializer=None):
    it = iter(iterable)
    if initializer is None:
        value = next(it)
    else:
        value = initializer
    for element in it:
        value = function(value, element)
    return value

全ての中間値を返すイテレータについては itertools.accumulate() を参照してください。

@functools.singledispatch

関数を シングルディスパッチ ジェネリック関数 に変換します。

To define a generic function, decorate it with the @singledispatch decorator. When defining a function using @singledispatch, note that the dispatch happens on the type of the first argument:

>>> from functools import singledispatch
>>> @singledispatch
... def fun(arg, verbose=False):
...     if verbose:
...         print("Let me just say,", end=" ")
...     print(arg)

関数にオーバーロード実装を追加するには、デコレータとして使用できる、ジェネリック関数の register() 属性を使用します。型アノテーションが付いている関数については、このデコレータは1つ目の引数の型を自動的に推測します。

>>> @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)

types.UnionType and typing.Union can also be used:

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

型アノテーションを使っていないコードについては、デコレータに適切な型引数を明示的に渡せます:

>>> @fun.register(complex)
... def _(arg, verbose=False):
...     if verbose:
...         print("Better than complicated.", end=" ")
...     print(arg.real, arg.imag)
...

register() 属性を関数形式で使用すると、lambda 関数と既存の関数の登録を有効にできます:

>>> def nothing(arg, verbose=False):
...     print("Nothing.")
...
>>> fun.register(type(None), nothing)

The register() attribute returns the undecorated function. This enables decorator stacking, pickling, and the creation of unit tests for each variant independently:

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

汎用関数は、呼び出されると 1 つ目の引数の型でディスパッチします:

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

特定の型について登録された実装が存在しない場合、その型のメソッド解決順序が、汎用の実装をさらに検索するために使用されます。@singledispatch でデコレートされた元の関数は基底の object 型に登録されます。これは、他によりよい実装が見つからないことを意味します。

抽象基底クラス (abstract base class) に対して実装が登録されると、基底クラスの仮想サブクラスに対してもその実装がディスパッチされます:

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

指定された型に対して、汎用関数がどの実装を選択するかを確認するには、dispatch() 属性を使用します:

>>> fun.dispatch(float)
<function fun_num at 0x1035a2840>
>>> fun.dispatch(dict)    # note: default implementation
<function fun at 0x103fe0000>

登録されたすべての実装にアクセスするには、読み出し専用の registry 属性を使用します:

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

Added in version 3.4.

バージョン 3.7 で変更: register() 属性が型アノテーションの使用をサポートするようになりました。

バージョン 3.11 で変更: The register() attribute now supports types.UnionType and typing.Union as type annotations.

class functools.singledispatchmethod(func)

メソッドを シングルディスパッチ ジェネリック関数 に変換します。

To define a generic method, decorate it with the @singledispatchmethod decorator. When defining a function using @singledispatchmethod, note that the dispatch happens on the type of the first non-self or non-cls argument:

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

@singledispatchmethod は @classmethod など他のデコレータとの入れ子構造をサポートします。 dispatcher.register を可能にするためには、 singledispatchmethod は入れ子構造の中で 最も外側 のデコレータでなければなりません。この Negator クラスの例では、クラスのインスタンスにではなく、クラスに neg メソッドが紐付きます:

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

同様のパターンが他の似たようなデコレータに対しても適用できます: @staticmethod, @abstractmethod など。

Added in version 3.8.

functools.update_wrapper(wrapper, wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)

Update a wrapper function to look like the wrapped function. The optional arguments are tuples to specify which attributes of the original function are assigned directly to the matching attributes on the wrapper function and which attributes of the wrapper function are updated with the corresponding attributes from the original function. The default values for these arguments are the module level constants WRAPPER_ASSIGNMENTS (which assigns to the wrapper function's __module__, __name__, __qualname__, __annotations__, __type_params__, and __doc__, the documentation string) and WRAPPER_UPDATES (which updates the wrapper function's __dict__, i.e. the instance dictionary).

内観や別の目的 (例えば、 lru_cache() のようなキャッシュするデコレータの回避) のために元の関数にアクセスできるように、この関数はラップされている関数を参照するラッパーに自動的に __wrapped__ 属性を追加します。

この関数は主に関数を包んでラッパーを返す デコレータ 関数の中で使われるよう意図されています。もしラッパー関数がアップデートされないとすると、返される関数のメタデータは元の関数の定義ではなくラッパー関数の定義を反映してしまい、これは通常あまり有益ではありません。

update_wrapper() は、関数以外の呼び出し可能オブジェクトにも使えます。 assigned または updated で指名され、ラップされるオブジェクトに存在しない属性は、すべて無視されます (すなわち、ラッパー関数にそれらの属性を設定しようとは試みられません)。しかし、 updated で指名された属性がラッパー関数自身に存在しないなら AttributeError が送出されます。

バージョン 3.2 で変更: The __wrapped__ attribute is now automatically added. The __annotations__ attribute is now copied by default. Missing attributes no longer trigger an AttributeError.

バージョン 3.4 で変更: ラップされた関数が __wrapped__ を定義していない場合でも、 __wrapped__ が常にラップされた関数を参照するようになりました。(bpo-17482 [https://bugs.python.org/issue?@action=redirect&bpo=17482] を参照)

バージョン 3.12 で変更: The __type_params__ attribute is now copied by default.

@functools.wraps(wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)

これはラッパー関数を定義するときに update_wrapper() を関数デコレータとして呼び出す便宜関数です。これは partial(update_wrapper, wrapped=wrapped, assigned=assigned, updated=updated) と等価です。例えば:

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

このデコレータ・ファクトリを使用しないと、上の例中の関数の名前は 'wrapper' となり、元の example() のドキュメンテーション文字列は失われてしまいます。

partial オブジェクト

partial オブジェクトは、 partial() 関数によって作られる呼び出し可能オブジェクトです。オブジェクトには読み出し専用の属性が三つあります:

partial.func

呼び出し可能オブジェクトまたは関数です。 partial オブジェクトの呼び出しは新しい引数とキーワードと共に func に転送されます。

partial.args

最左の位置引数で、 partial オブジェクトの呼び出し時にその呼び出しの際の位置引数の前に追加されます。

partial.keywords

partial オブジェクトの呼び出し時に渡されるキーワード引数です。

partial objects are like function objects in that they are callable, weak referenceable, and can have attributes. There are some important differences. For instance, the __name__ and __doc__ attributes are not created automatically. Also, partial objects defined in classes behave like static methods and do not transform into bound methods during instance attribute look-up.

operator --- Standard operators as functions

ソースコード: Lib/operator.py [https://github.com/python/cpython/tree/3.12/Lib/operator.py]

operator モジュールは、Python の組み込み演算子に対応する効率的な関数群を提供します。例えば、 operator.add(x, y) は式 x+y と等価です。多くの関数名は、特殊メソッドに使われている名前から前後の二重アンダースコアを除いたものと同じです。後方互換性のため、ほとんどの関数に二重アンダースコアを付けたままのバージョンがあります。簡潔さのために、二重アンダースコアが無いバージョンの方が好まれます。

これらの関数は、オブジェクト比較、論理演算、数学演算、シーケンス演算をするものに分類されます。

オブジェクト比較関数は全てのオブジェクトで有効で、関数の名前はサポートする拡張比較演算子からとられています:

operator.lt(a, b)

operator.le(a, b)

operator.eq(a, b)

operator.ne(a, b)

operator.ge(a, b)

operator.gt(a, b)

operator.__lt__(a, b)

operator.__le__(a, b)

operator.__eq__(a, b)

operator.__ne__(a, b)

operator.__ge__(a, b)

operator.__gt__(a, b)

a と b の "拡張比較 (rich comparisons)" を行います。具体的には、 lt(a, b) は a < b 、 le(a, b) は a <= b 、 eq(a, b) は a == b 、 ne(a, b) は a != b 、 gt(a, b) は a > b 、そして ge(a, b) は a >= b と等価です。これらの関数はどのような値を返してもよく、ブール値として解釈できてもできなくてもかまいません。拡張比較の詳細については 比較 を参照してください。

論理演算もまた全てのオブジェクトに対して適用でき、真理値判定、同一性判定およびブール演算をサポートします:

operator.not_(obj)

operator.__not__(obj)

Return the outcome of not obj. (Note that there is no __not__() method for object instances; only the interpreter core defines this operation. The result is affected by the __bool__() and __len__() methods.)

operator.truth(obj)

obj が真の場合 True を返し、そうでない場合 False を返します。この関数は bool のコンストラクタ呼び出しと同等です。

operator.is_(a, b)

a is b を返します。オブジェクトの同一性を判定します。

operator.is_not(a, b)

a is not b を返します。オブジェクトの同一性を判定します。

演算子で最も多いのは数学演算およびビット単位の演算です:

operator.abs(obj)

operator.__abs__(obj)

obj の絶対値を返します。

operator.add(a, b)

operator.__add__(a, b)

数値 a および b について a + b を返します。

operator.and_(a, b)

operator.__and__(a, b)

a と b のビット単位論理積を返します。

operator.floordiv(a, b)

operator.__floordiv__(a, b)

a // b を返します。

operator.index(a)

operator.__index__(a)

整数に変換された a を返します。a.__index__() と同等です。

バージョン 3.10 で変更: 結果は常に厳密な int 型です。以前は、結果は int のサブクラスのインスタンスのこともありました。

operator.inv(obj)

operator.invert(obj)

operator.__inv__(obj)

operator.__invert__(obj)

obj のビット単位反転を返します。~obj と同じです。

operator.lshift(a, b)

operator.__lshift__(a, b)

a の b ビット左シフトを返します。

operator.mod(a, b)

operator.__mod__(a, b)

a % b を返します。

operator.mul(a, b)

operator.__mul__(a, b)

数値 a および b について a * b を返します。

operator.matmul(a, b)

operator.__matmul__(a, b)

a @ b を返します。

Added in version 3.5.

operator.neg(obj)

operator.__neg__(obj)

負の obj (-obj) を返します。

operator.or_(a, b)

operator.__or__(a, b)

a と b のビット単位論理和を返します。

operator.pos(obj)

operator.__pos__(obj)

正の obj (+obj) を返します。

operator.pow(a, b)

operator.__pow__(a, b)

数値 a および b について a ** b を返します。

operator.rshift(a, b)

operator.__rshift__(a, b)

a の b ビット右シフトを返します。

operator.sub(a, b)

operator.__sub__(a, b)

a - b を返します。

operator.truediv(a, b)

operator.__truediv__(a, b)

2/3 が 0 ではなく 0.66 となるような a / b を返します。 "真の" 除算としても知られています。

operator.xor(a, b)

operator.__xor__(a, b)

a および b のビット単位排他的論理和を返します。

シーケンスを扱う演算子（いくつかの演算子はマッピングも扱います）には以下のようなものがあります:

operator.concat(a, b)

operator.__concat__(a, b)

シーケンス a および b について a + b を返します。

operator.contains(a, b)

operator.__contains__(a, b)

b in a の判定結果を返します。被演算子が左右反転しているので注意してください。

operator.countOf(a, b)

a の中に b が出現する回数を返します。

operator.delitem(a, b)

operator.__delitem__(a, b)

a でインデクスが b の値を削除します。

operator.getitem(a, b)

operator.__getitem__(a, b)

a でインデクスが b の値を返します。

operator.indexOf(a, b)

a で最初に b が出現する場所のインデクスを返します。

operator.setitem(a, b, c)

operator.__setitem__(a, b, c)

a でインデクスが b の値を c に設定します。

operator.length_hint(obj, default=0)

Return an estimated length for the object obj. First try to return its actual length, then an estimate using object.__length_hint__(), and finally return the default value.

Added in version 3.4.

The following operation works with callables:

operator.call(obj, /, *args, **kwargs)

operator.__call__(obj, /, *args, **kwargs)

Return obj(*args, **kwargs).

Added in version 3.11.

operator モジュールは属性とアイテムの汎用的な検索のための道具も定義しています。 map(), sorted(), itertools.groupby(), や関数を引数に取るその他の関数に対して高速にフィールドを抽出する際に引数として使うと便利です。

operator.attrgetter(attr)

operator.attrgetter(*attrs)

演算対象から attr を取得する呼び出し可能なオブジェクトを返します。二つ以上の属性を要求された場合には、属性のタプルを返します。属性名はドットを含むこともできます。例えば:

f = attrgetter('name') とした後で、f(b) を呼び出すと b.name を返します。

f = attrgetter('name', 'date') とした後で、f(b) を呼び出すと (b.name, b.date) を返します。

f = attrgetter('name.first', 'name.last') とした後で、f(b) を呼び出すと (b.name.first, b.name.last) を返します。

次と等価です:

def attrgetter(*items):
    if any(not isinstance(item, str) for item in items):
        raise TypeError('attribute name must be a string')
    if len(items) == 1:
        attr = items[0]
        def g(obj):
            return resolve_attr(obj, attr)
    else:
        def g(obj):
            return tuple(resolve_attr(obj, attr) for attr in items)
    return g

def resolve_attr(obj, attr):
    for name in attr.split("."):
        obj = getattr(obj, name)
    return obj

operator.itemgetter(item)

operator.itemgetter(*items)

Return a callable object that fetches item from its operand using the operand's __getitem__() method. If multiple items are specified, returns a tuple of lookup values. For example:

f = itemgetter(2) とした後で、f(r) を呼び出すと r[2] を返します。

g = itemgetter(2, 5, 3) とした後で、g(r) を呼び出すと (r[2], r[5], r[3]) を返します。

次と等価です:

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

The items can be any type accepted by the operand's __getitem__() method. Dictionaries accept any hashable value. Lists, tuples, and strings accept an index or a slice:

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

itemgetter() を使って特定のフィールドをタプルレコードから取り出す例:

>>> 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)]

operator.methodcaller(name, /, *args, **kwargs)

引数の name メソッドを呼び出す呼び出し可能オブジェクトを返します。追加の引数および/またはキーワード引数が与えられると、これらもそのメソッドに引き渡されます。例えば:

f = methodcaller('name') とした後で、f(b) を呼び出すと b.name() を返します。

f = methodcaller('name', 'foo', bar=1) とした後で、f(b) を呼び出すと b.name('foo', bar=1) を返します。

次と等価です:

def methodcaller(name, /, *args, **kwargs):
    def caller(obj):
        return getattr(obj, name)(*args, **kwargs)
    return caller

演算子から関数への対応表

下のテーブルでは、個々の抽象的な操作が、どのように Python 構文上の各演算子や operator モジュールの関数に対応しているかを示しています。

演算

操作

関数

加算

a + b

add(a, b)

結合

seq1 + seq2

concat(seq1, seq2)

包含判定

obj in seq

contains(seq, obj)

除算

a / b

truediv(a, b)

除算

a // b

floordiv(a, b)

ビット単位論理積

a & b

and_(a, b)

ビット単位排他的論理和

a ^ b

xor(a, b)

ビット単位反転

~ a

invert(a)

ビット単位論理和

a | b

or_(a, b)

冪乗

a ** b

pow(a, b)

同一性

a is b

is_(a, b)

同一性

a is not b

is_not(a, b)

インデクス指定の代入

obj[k] = v

setitem(obj, k, v)

インデクス指定の削除

del obj[k]

delitem(obj, k)

インデクス指定

obj[k]

getitem(obj, k)

左シフト

a << b

lshift(a, b)

剰余

a % b

mod(a, b)

乗算

a * b

mul(a, b)

行列の乗算

a @ b

matmul(a, b)

(算術) 負

- a

neg(a)

(論理) 否

not a

not_(a)

正

+ a

pos(a)

右シフト

a >> b

rshift(a, b)

スライス指定の代入

seq[i:j] = values

setitem(seq, slice(i, j), values)

スライス指定の削除

del seq[i:j]

delitem(seq, slice(i, j))

スライス指定

seq[i:j]

getitem(seq, slice(i, j))

文字列書式化

s % obj

mod(s, obj)

減算

a - b

sub(a, b)

真理値判定

obj

truth(obj)

順序付け

a < b

lt(a, b)

順序付け

a <= b

le(a, b)

等価性

a == b

eq(a, b)

不等性

a != b

ne(a, b)

順序付け

a >= b

ge(a, b)

順序付け

a > b

gt(a, b)

インプレース (in-place) 演算子

多くの演算に「インプレース」版があります。 以下の関数はそうした演算子の通常の文法に比べてより素朴な呼び出し方を提供します。たとえば、 文 x += y は x = operator.iadd(x, y) と等価です。別の言い方をすると、 z = operator.iadd(x, y) は複合文 z = x; z += y と等価です。

なお、これらの例では、インプレースメソッドが呼び出されたとき、計算と代入は二段階に分けて行われます。以下に挙げるインプレース関数は、インプレースメソッドを呼び出してその第一段階だけを行います。第二段階の代入は扱われません。

文字列、数、タプルのようなイミュータブルなターゲットでは、更新された値が計算されますが、入力変数に代入し返されはしません。

>>> a = 'hello'
>>> iadd(a, ' world')
'hello world'
>>> a
'hello'

リストや辞書のようなミュータブルなターゲットでは、インプレースメソッドは更新を行うので、その後に代入をする必要はありません。

>>> 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']

operator.iadd(a, b)

operator.__iadd__(a, b)

a = iadd(a, b) は a += b と等価です。

operator.iand(a, b)

operator.__iand__(a, b)

a = iand(a, b) は a &= b と等価です。

operator.iconcat(a, b)

operator.__iconcat__(a, b)

a = iconcat(a, b) は二つのシーケンス a と b に対し a += b と等価です。

operator.ifloordiv(a, b)

operator.__ifloordiv__(a, b)

a = ifloordiv(a, b) は a //= b と等価です。

operator.ilshift(a, b)

operator.__ilshift__(a, b)

a = ilshift(a, b) は a <<= b と等価です。

operator.imod(a, b)

operator.__imod__(a, b)

a = imod(a, b) は a %= b と等価です。

operator.imul(a, b)

operator.__imul__(a, b)

a = imul(a, b) は a *= b と等価です。

operator.imatmul(a, b)

operator.__imatmul__(a, b)

a = imatmul(a, b) は a @= b と等価です。

Added in version 3.5.

operator.ior(a, b)

operator.__ior__(a, b)

a = ior(a, b) は a |= b と等価です。

operator.ipow(a, b)

operator.__ipow__(a, b)

a = ipow(a, b) は a **= b と等価です。

operator.irshift(a, b)

operator.__irshift__(a, b)

a = irshift(a, b) は a >>= b と等価です。

operator.isub(a, b)

operator.__isub__(a, b)

a = isub(a, b) は a -= b と等価です。

operator.itruediv(a, b)

operator.__itruediv__(a, b)

a = itruediv(a, b) は a /= b と等価です。

operator.ixor(a, b)

operator.__ixor__(a, b)

a = ixor(a, b) は a ^= b と等価です。

ファイルとディレクトリへのアクセス

この章で説明されるモジュールはディスクのファイルやディレクトリを扱います。たとえば、ファイルの属性を読むためのモジュール、ファイルパスを移植可能な方式で操作する、テンポラリファイルを作成するためのモジュールです。この章の完全な一覧は:

pathlib --- Object-oriented filesystem paths

基本的な使い方

純粋パス

全般的な性質

演算子

個別の構成要素へのアクセス

メソッドとプロパティ

具象パス

メソッド

Correspondence to tools in the os module

os.path --- Common pathname manipulations

fileinput --- Iterate over lines from multiple input streams

stat --- Interpreting stat() results

filecmp --- File and Directory Comparisons

dircmp クラス

tempfile --- Generate temporary files and directories

使用例

非推奨の関数と変数

glob --- Unix style pathname pattern expansion

fnmatch --- Unix filename pattern matching

linecache --- Random access to text lines

shutil --- High-level file operations

ディレクトリとファイルの操作

プラットフォーム依存の効率的なコピー操作

copytree の例

rmtree の例

アーカイブ化操作

アーカイブ化の例

base_dir を使ったアーカイブ化の例

出力ターミナルのサイズの取得

参考

os モジュール

オペレーティングシステムのインターフェース、Python の ファイルオブジェクト より低レベルでのファイル操作を含みます。

io モジュール

Python 組み込みの I/O ライブラリで、抽象クラスとファイル I/O のようないくつかの具象クラスを含みます。

open() 組込み関数

Python で読み書きのためにファイルを開く標準的な方法です。

pathlib --- Object-oriented filesystem paths

Added in version 3.4.

Source code: Lib/pathlib.py [https://github.com/python/cpython/tree/3.12/Lib/pathlib.py]

このモジュールはファイルシステムのパスを表すクラスを提供していて、様々なオペレーティングシステムについての適切な意味論をそれらのクラスに持たせています。 Path クラスは 純粋パス と 具象パス からなります。純粋パスは I/O を伴わない純粋な計算操作を提供します。具象パスは純粋パスを継承していますが、 I/O 操作も提供しています。

あなたが今までこのモジュールを使用したことがない場合や、タスクに適しているのがどのクラスかわからない場合は、 Path はきっとあなたに必要なものでしょう。 Path はコードが実行されているプラットフォーム用の 具象パス のインスタンスを作成します。

純粋パスは、以下のようないくつかの特殊なケースで有用です:

Unix マシン上で Windows のパスを扱いたいとき (またはその逆)。Unix 上で実行しているときに WindowsPath のインスタンスを作成することはできませんが、PureWindowsPath なら可能になります。

実際に OS にアクセスすることなしにパスを操作するだけのコードを確認したいとき。この場合、純粋クラスのインスタンスを一つ作成すれば、それが OS にアクセスすることはないので便利です。

参考

PEP 428 [https://peps.python.org/pep-0428/]: The pathlib module -- オブジェクト指向のファイルシステムパス。

参考

文字列による低水準のパス操作の場合は os.path も使用できます。

基本的な使い方

メインクラスをインポートします:

>>> from pathlib import Path

サブディレクトリの一覧を取得します:

>>> p = Path('.')
>>> [x for x in p.iterdir() if x.is_dir()]
[PosixPath('.hg'), PosixPath('docs'), PosixPath('dist'),
 PosixPath('__pycache__'), PosixPath('build')]

このディレクトリツリー内の Python ソースファイルの一覧を取得します:

>>> list(p.glob('**/*.py'))
[PosixPath('test_pathlib.py'), PosixPath('setup.py'),
 PosixPath('pathlib.py'), PosixPath('docs/conf.py'),
 PosixPath('build/lib/pathlib.py')]

ディレクトリツリー内を移動します:

>>> p = Path('/etc')
>>> q = p / 'init.d' / 'reboot'
>>> q
PosixPath('/etc/init.d/reboot')
>>> q.resolve()
PosixPath('/etc/rc.d/init.d/halt')

パスのプロパティを問い合わせます:

>>> q.exists()
True
>>> q.is_dir()
False

ファイルを開きます:

>>> with q.open() as f: f.readline()
...
'#!/bin/bash\n'

純粋パス

純粋パスオブジェクトは実際にファイルシステムにアクセスしないパス操作処理を提供します。これらのクラスにアクセスするには 3 つの方法があり、それらを フレーバー と呼んでいます:

class pathlib.PurePath(*pathsegments)

システムのパスのフレーバーを表すジェネリッククラスです (インスタンスを作成することで PurePosixPath または PureWindowsPath のどちらかが作成されます):

>>> PurePath('setup.py')      # Running on a Unix machine
PurePosixPath('setup.py')

pathsegments の各要素は、パスの構成要素を表す文字列か、パスオブジェクトなどの、 os.PathLike インターフェースを実装するオブジェクトである必要があります。 os.PathLike インターフェースでは、 __fspath__() メソッドが文字列を返します:

>>> PurePath('foo', 'some/path', 'bar')
PurePosixPath('foo/some/path/bar')
>>> PurePath(Path('foo'), Path('bar'))
PurePosixPath('foo/bar')

pathsegments が空のとき、現在のディレクトリとみなされます:

>>> PurePath()
PurePosixPath('.')

あるパス構成要素が絶対パスである場合、それより前の要素はすべて無視されます (os.path.join() と同様):

>>> PurePath('/etc', '/usr', 'lib64')
PurePosixPath('/usr/lib64')
>>> PureWindowsPath('c:/Windows', 'd:bar')
PureWindowsPath('d:bar')

Windowsの場合、ルート相対パス (例えば r'\foo') があってもドライブ名はそのまま変わりません:

>>> PureWindowsPath('c:/Windows', '/Program Files')
PureWindowsPath('c:/Program Files')

単一スラッシュと等価な複数スラッシュやシングルドットは簡略化されますが、ダブルドット ('..') や先頭に位置するダブルスラッシュ ('//') は簡略化されません。これは、様々な理由でパスの意味が簡略化した場合と異なってしまうからです (例: シンボリックリンク、UNCパス):

>>> PurePath('foo//bar')
PurePosixPath('foo/bar')
>>> PurePath('//foo/bar')
PurePosixPath('//foo/bar')
>>> PurePath('foo/./bar')
PurePosixPath('foo/bar')
>>> PurePath('foo/../bar')
PurePosixPath('foo/../bar')

(通常 PurePosixPath('foo/../bar') は PurePosixPath('bar') と等価になりますが、foo が他のディレクトリへのシンボリックリンクの場合は等価になりません)

純粋パスオブジェクトは os.PathLike インターフェースを実装しており、そのインターフェースを受理する箇所ならどこでも使用することができます。

バージョン 3.6 で変更: os.PathLike インターフェースがサポートされました。

class pathlib.PurePosixPath(*pathsegments)

PurePath のサブクラスです。このパスフレーバーは非 Windows パスを表します:

>>> PurePosixPath('/etc')
PurePosixPath('/etc')

pathsegments の指定は PurePath と同じです。

class pathlib.PureWindowsPath(*pathsegments)

PurePath のサブクラスです。このパスフレーバー UNC paths [https://en.wikipedia.org/wiki/Path_(computing)#UNC] を含む Windows ファイルシステムパスを表します:

>>> PureWindowsPath('c:/Program Files/')
PureWindowsPath('c:/Program Files')
>>> PureWindowsPath('//server/share/file')
PureWindowsPath('//server/share/file')

pathsegments の指定は PurePath と同じです。

これらクラスはあらゆるシステムコールを行わないため、起動しているシステムにかかわらずインスタンスを作成できます。

全般的な性質

パスオブジェクトはイミュータブルで :term:`ハッシュ可能 <hashable>`です。同じフレーバーのパスオブジェクトは比較ならびに順序付け可能です。これらのプロパティは、フレーバーのケースフォールディング (訳注: 比較のために正規化すること、例えば全て大文字にする) のセマンティクスに従います。

>>> PurePosixPath('foo') == PurePosixPath('FOO')
False
>>> PureWindowsPath('foo') == PureWindowsPath('FOO')
True
>>> PureWindowsPath('FOO') in { PureWindowsPath('foo') }
True
>>> PureWindowsPath('C:') < PureWindowsPath('d:')
True

異なるフレーバーのパスオブジェクト同士の比較は等価になることはなく、順序付けもできません:

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

演算子

スラッシュ演算子を使って、 os.path.join() のように子パスを作成することができます。スラッシュの右側が絶対パスである場合、左側のパスは無視されます。 Windows環境で、右側のパスがルート相対パス (例: r'\foo') である場合、ドライブ名はリセットされません:

>>> 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')

os.PathLike を実装したオブジェクトが受理できる箇所ならどこでも、パスオブジェクトが使用できます:

>>> import os
>>> p = PurePath('/etc')
>>> os.fspath(p)
'/etc'

パスオブジェクトの文字列表現はそのシステム自身の Raw ファイルシステムパス (ネイティブの形式、例えば Windows では区切り文字がバックスラッシュ) になり、文字列としてファイルパスを取るあらゆる関数に渡すことができます:

>>> p = PurePath('/etc')
>>> str(p)
'/etc'
>>> p = PureWindowsPath('c:/Program Files')
>>> str(p)
'c:\\Program Files'

同様に、パスオブジェクトを bytes で呼び出すと、Raw ファイルシステムパスを os.fsencode() でエンコードされたバイト列オブジェクトで返します:

>>> bytes(p)
b'/etc'

注釈

bytes での呼び出しは Unix 上での使用のみ推奨します。Windows では Unicode 形式が標準的なファイルシステムパス表現になります。

個別の構成要素へのアクセス

パスの個別の "構成要素" へアクセスするには、以下のプロパティを使用します:

PurePath.parts

パスのさまざまな構成要素へのアクセス手段を提供するタプルになります:

>>> p = PurePath('/usr/bin/python3')
>>> p.parts
('/', 'usr', 'bin', 'python3')

>>> p = PureWindowsPath('c:/Program Files/PSF')
>>> p.parts
('c:\\', 'Program Files', 'PSF')

(ドライブ名とローカルルートは単一要素にまとめられます)

メソッドとプロパティ

純粋パスは以下のメソッドとプロパティを提供します:

PurePath.drive

ドライブ文字または名前を表す文字列があればそれになります:

>>> PureWindowsPath('c:/Program Files/').drive
'c:'
>>> PureWindowsPath('/Program Files/').drive
''
>>> PurePosixPath('/etc').drive
''

UNC 共有名もドライブとみなされます:

>>> PureWindowsPath('//host/share/foo.txt').drive
'\\\\host\\share'

PurePath.root

ローカルまたはグローバルルートを表す文字列があればそれになります:

>>> PureWindowsPath('c:/Program Files/').root
'\\'
>>> PureWindowsPath('c:Program Files/').root
''
>>> PurePosixPath('/etc').root
'/'

UNC 共有名は常にルートを持ちます:

>>> PureWindowsPath('//host/share').root
'\\'

PurePosixPath でパスの先頭が３つ以上の連続したスラッシュである場合、 余分なスラッシュは除去されます:

>>> PurePosixPath('//etc').root
'//'
>>> PurePosixPath('///etc').root
'/'
>>> PurePosixPath('////etc').root
'/'

注釈

この挙動は、以下に示す、 The Open Group Base Specifications Issue 6 の 4.11 Pathname Resolution [https://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap04.html#tag_04_11] に沿ったものです:

"A pathname that begins with two successive slashes may be interpreted in an implementation-defined manner, although more than two leading slashes shall be treated as a single slash."

PurePath.anchor

ドライブとルートを結合した文字列になります:

>>> PureWindowsPath('c:/Program Files/').anchor
'c:\\'
>>> PureWindowsPath('c:Program Files/').anchor
'c:'
>>> PurePosixPath('/etc').anchor
'/'
>>> PureWindowsPath('//host/share').anchor
'\\\\host\\share\\'

PurePath.parents

パスの論理的な上位パスにアクセスできるイミュータブルなシーケンスになります:

>>> 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:/')

バージョン 3.10 で変更: parents シーケンスが、スライス と負のインデックスをサポートするようになりました。

PurePath.parent

パスの論理的な上位パスになります:

>>> p = PurePosixPath('/a/b/c/d')
>>> p.parent
PurePosixPath('/a/b/c')

アンカーの位置を超えることや空のパスになる位置には対応していません:

>>> p = PurePosixPath('/')
>>> p.parent
PurePosixPath('/')
>>> p = PurePosixPath('.')
>>> p.parent
PurePosixPath('.')

注釈

これは純粋な字句操作であるため、以下のような挙動になります:

>>> p = PurePosixPath('foo/..')
>>> p.parent
PurePosixPath('foo')

任意のファイルシステムパスを上位方向に移動したい場合、シンボリックリンクの解決や ".." 要素の除去のため、最初に Path.resolve() を呼ぶことを推奨します。

PurePath.name

パス要素の末尾を表す文字列があればそれになります。ドライブやルートは含まれません:

>>> PurePosixPath('my/library/setup.py').name
'setup.py'

UNC ドライブ名は考慮されません:

>>> PureWindowsPath('//some/share/setup.py').name
'setup.py'
>>> PureWindowsPath('//some/share').name
''

PurePath.suffix

The file extension of the final component, if any:

>>> PurePosixPath('my/library/setup.py').suffix
'.py'
>>> PurePosixPath('my/library.tar.gz').suffix
'.gz'
>>> PurePosixPath('my/library').suffix
''

PurePath.suffixes

A list of the path's file extensions:

>>> PurePosixPath('my/library.tar.gar').suffixes
['.tar', '.gar']
>>> PurePosixPath('my/library.tar.gz').suffixes
['.tar', '.gz']
>>> PurePosixPath('my/library').suffixes
[]

PurePath.stem

パス要素の末尾から拡張子を除いたものになります:

>>> PurePosixPath('my/library.tar.gz').stem
'library.tar'
>>> PurePosixPath('my/library.tar').stem
'library'
>>> PurePosixPath('my/library').stem
'library'

PurePath.as_posix()

フォワードスラッシュ (/) を使用したパスを表す文字列を返します:

>>> p = PureWindowsPath('c:\\windows')
>>> str(p)
'c:\\windows'
>>> p.as_posix()
'c:/windows'

PurePath.as_uri()

Represent the path as a file URI. ValueError is raised if the path isn't absolute.

>>> p = PurePosixPath('/etc/passwd')
>>> p.as_uri()
'file:///etc/passwd'
>>> p = PureWindowsPath('c:/Windows')
>>> p.as_uri()
'file:///c:/Windows'

PurePath.is_absolute()

パスが絶対パスかどうかを返します。パスが絶対パスとみなされるのは、ルートと (フレーバーが許す場合) ドライブとの両方が含まれる場合です:

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

PurePath.is_relative_to(other)

このパスが other パスに対して相対なのかそうでないのかの結果を返します。

>>> p = PurePath('/etc/passwd')
>>> p.is_relative_to('/etc')
True
>>> p.is_relative_to('/usr')
False

This method is string-based; it neither accesses the filesystem nor treats ".." segments specially. The following code is equivalent:

>>> u = PurePath('/usr')
>>> u == p or u in p.parents
False

Added in version 3.9.

バージョン 3.12 で非推奨、バージョン 3.14 で削除予定: 追加の引数指定は非推奨となりました。指定された場合は other と連結されます。

PurePath.is_reserved()

PureWindowsPath の場合はパスが Windows 上で予約されていれば True を返し、そうでなければ False を返します。PurePosixPath の場合は常に False を返します。

>>> PureWindowsPath('nul').is_reserved()
True
>>> PurePosixPath('nul').is_reserved()
False

File system calls on reserved paths can fail mysteriously or have unintended effects.

PurePath.joinpath(*pathsegments)

このメソッドの呼び出しは、与えられた pathsegments のパスを順番に結合することと等価です。

>>> 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')

PurePath.match(pattern, *, case_sensitive=None)

Match this path against the provided glob-style pattern. Return True if matching is successful, False otherwise.

If pattern is relative, the path can be either relative or absolute, and matching is done from the right:

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

If pattern is absolute, the path must be absolute, and the whole path must match:

>>> PurePath('/a.py').match('/*.py')
True
>>> PurePath('a/b.py').match('/*.py')
False

The pattern may be another path object; this speeds up matching the same pattern against multiple files:

>>> pattern = PurePath('*.py')
>>> PurePath('a/b.py').match(pattern)
True

注釈

The recursive wildcard "**" isn't supported by this method (it acts like non-recursive "*".)

バージョン 3.12 で変更: Accepts an object implementing the os.PathLike interface.

他のメソッドと同様に、大文字小文字の区別はプラットフォームの設定に従います:

>>> PurePosixPath('b.py').match('*.PY')
False
>>> PureWindowsPath('b.py').match('*.PY')
True

Set case_sensitive to True or False to override this behaviour.

バージョン 3.12 で変更: case_sensitive 引数が追加されました。

PurePath.relative_to(other, walk_up=False)

other で表されたパスから現在のパスへの相対パスを返します。それが不可能だった場合は ValueError が送出されます:

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

When walk_up is false (the default), the path must start with other. When the argument is true, .. entries may be added to form the relative path. In all other cases, such as the paths referencing different drives, ValueError is raised.:

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

警告

This function is part of PurePath and works with strings. It does not check or access the underlying file structure. This can impact the walk_up option as it assumes that no symlinks are present in the path; call resolve() first if necessary to resolve symlinks.

バージョン 3.12 で変更: walk_up 引数が追加されました（walk_up=False を指定すると以前の動作と同じになります）。

バージョン 3.12 で非推奨、バージョン 3.14 で削除予定: 追加の位置引数の指定は非推奨となりました。指定された場合は other と連結されます。

PurePath.with_name(name)

現在のパスの name 部分を変更したパスを返します。オリジナルパスに name 部分がない場合は ValueError が送出されます:

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

PurePath.with_stem(stem)

現在のパスの stem 部分を変更したパスを返します。オリジナルパスに stem 部分がない場合は ValueError が送出されます:

>>> 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('')
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

Added in version 3.9.

PurePath.with_suffix(suffix)

suffix を変更した新しいパスを返します。元のパスに suffix が無かった場合、代わりに新しい suffix が追加されます。 suffix が空文字列だった場合、元の suffix は除去されます:

>>> 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('')
PureWindowsPath('README')

PurePath.with_segments(*pathsegments)

Create a new path object of the same type by combining the given pathsegments. This method is called whenever a derivative path is created, such as from parent and relative_to(). Subclasses may override this method to pass information to derivative paths, for 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

Added in version 3.12.

具象パス

具象パスは純粋パスクラスのサブクラスです。純粋パスが提供する操作に加え、パスオブジェクト上でシステムコールを呼ぶメソッドも提供しています。具象パスのインスタンスを作成するには 3 つの方法があります:

class pathlib.Path(*pathsegments)

PurePath のサブクラスであり、システムのパスフレーバーの具象パスを表します (このインスタンスの作成で PosixPath か WindowsPath のどちらかが作成されます):

>>> Path('setup.py')
PosixPath('setup.py')

pathsegments の指定は PurePath と同じです。

class pathlib.PosixPath(*pathsegments)

Path および PurePosixPath のサブクラスで、非 Windows ファイルシステムの具象パスを表します:

>>> PosixPath('/etc')
PosixPath('/etc')

pathsegments の指定は PurePath と同じです。

class pathlib.WindowsPath(*pathsegments)

Path および PureWindowsPath のサブクラスで、Windows ファイルシステムの具象パスを表します:

>>> WindowsPath('c:/Program Files/')
WindowsPath('c:/Program Files')

pathsegments の指定は PurePath と同じです。

インスタンスを作成できるのはシステムと一致するフレーバーのみです (互換性のないパスフレーバーでのシステムコールの許可はバグやアプリケーションの異常終了の原因になります):

>>> 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__,))
NotImplementedError: cannot instantiate 'WindowsPath' on your system

メソッド

具象パスは純粋パスに加え、以下のメソッドを提供します。これらメソッドの多くはシステムコールが失敗すると OSError を送出します。(例えばパスが存在しない場合)

バージョン 3.8 で変更: exists(), is_dir(), is_file(), is_mount(), is_symlink(), is_block_device(), is_char_device(), is_fifo(), is_socket() は、OSレベルで表現不能な文字を含むパスに対して、例外を送出する代わりに False を返すようになりました。

classmethod Path.cwd()

(os.getcwd() が返す) 現在のディレクトリを表す新しいパスオブジェクトを返します:

>>> Path.cwd()
PosixPath('/home/antoine/pathlib')

classmethod Path.home()

ユーザーのホームディレクトリ (os.path.expanduser() での ~ の返り値) を表す新しいパスオブジェクトを返します。ホームディレクトリが解決できない場合は、 RuntimeError を送出します。

>>> Path.home()
PosixPath('/home/antoine')

Added in version 3.5.

Path.stat(*, follow_symlinks=True)

(os.stat() と同様の) 現在のパスについて os.stat_result オブジェクトが含む情報を返します。値はそれぞれのメソッドを呼び出した時点のものになります。

このメソッドは通常はシンボリックリンクをたどります。シンボリックリンクに対して stat したい場合は follow_symlinks=False とするか、 lstat() を利用してください。

>>> p = Path('setup.py')
>>> p.stat().st_size
956
>>> p.stat().st_mtime
1327883547.852554

バージョン 3.10 で変更: follow_symlinks パラメータが追加されました。

Path.chmod(mode, *, follow_symlinks=True)

os.chmod() のようにファイルのモードとアクセス権限を変更します。

このメソッドは通常シンボリックリンクをたどります。一部のUnixではシンボリックリンク自体のパーミッション変更をサポートしています。そのようなプラットフォームでは引数に``follow_symlinks=False`` を追加するか、lchmod() を使用してください。

>>> p = Path('setup.py')
>>> p.stat().st_mode
33277
>>> p.chmod(0o444)
>>> p.stat().st_mode
33060

バージョン 3.10 で変更: follow_symlinks パラメータが追加されました。

Path.exists(*, follow_symlinks=True)

パスが存在するファイルかディレクトリを指している場合は True を返します。

このメソッドは通常はシンボリックリンクをたどります。シンボリックリンクが存在するかを確認したい場合は follow_symlinks=False 引数を追加してください。

>>> Path('.').exists()
True
>>> Path('setup.py').exists()
True
>>> Path('/etc').exists()
True
>>> Path('nonexistentfile').exists()
False

バージョン 3.12 で変更: follow_symlinks パラメータが追加されました。

Path.expanduser()

パス要素 ~ および ~user を os.path.expanduser() が返すように展開した新しいパスオブジェクトを返します。ホームディレクトリが解決できない場合は、 RuntimeError を送出します。

>>> p = PosixPath('~/films/Monty Python')
>>> p.expanduser()
PosixPath('/home/eric/films/Monty Python')

Added in version 3.5.

Path.glob(pattern, *, case_sensitive=None)

現在のパスが表すディレクトリ内で相対 pattern に一致する (あらゆる種類の) すべてのファイルを yield します:

>>> sorted(Path('.').glob('*.py'))
[PosixPath('pathlib.py'), PosixPath('setup.py'), PosixPath('test_pathlib.py')]
>>> sorted(Path('.').glob('*/*.py'))
[PosixPath('docs/conf.py')]

Patterns are the same as for fnmatch, with the addition of "**" which means "this directory and all subdirectories, recursively". In other words, it enables recursive globbing:

>>> sorted(Path('.').glob('**/*.py'))
[PosixPath('build/lib/pathlib.py'),
 PosixPath('docs/conf.py'),
 PosixPath('pathlib.py'),
 PosixPath('setup.py'),
 PosixPath('test_pathlib.py')]

This method calls Path.is_dir() on the top-level directory and propagates any OSError exception that is raised. Subsequent OSError exceptions from scanning directories are suppressed.

デフォルトまたは case_sensitive キーワード専用引数に None を指定した場合、このメソッドはパスの一致判定にプラットフォームに依存した大文字小文字のルールを使用します。一般的にPOSIXは大文字と小文字を区別し、Windowsは区別しません。case_sensitive を True または False に設定するとこの動作を上書きします。

注釈

Using the "**" pattern in large directory trees may consume an inordinate amount of time.

引数 self, pattern を指定して 監査イベント pathlib.Path.glob を送出します。

バージョン 3.11 で変更: Return only directories if pattern ends with a pathname components separator (sep or altsep).

バージョン 3.12 で変更: case_sensitive 引数が追加されました。

Path.group()

Return the name of the group owning the file. KeyError is raised if the file's gid isn't found in the system database.

Path.is_dir()

Return True if the path points to a directory (or a symbolic link pointing to a directory), False if it points to another kind of file.

パスが存在しないか壊れたシンボリックリンクだった場合にも False が返されます; (パーミッションエラーのような) その他のエラーは伝搬されます。

Path.is_file()

Return True if the path points to a regular file (or a symbolic link pointing to a regular file), False if it points to another kind of file.

パスが存在しないか壊れたシンボリックリンクだった場合にも False が返されます; (パーミッションエラーのような) その他のエラーは伝搬されます。

Path.is_junction()

パスがジャンクションを指している場合は True を返し、それ以外の場合は False を返します。現在はWindowsのみジャンクションをサポートしています。

Added in version 3.12.

Path.is_mount()

パスがマウントポイント mount point (ファイルシステムの中で異なるファイルシステムがマウントされているところ) なら、 True を返します。POSIX では、この関数は path の親ディレクトリである path/.. が path と異なるデバイス上にあるか、あるいは path/.. と path が同じデバイス上の同じ i-node を指しているかをチェックします --- これによって全ての Unix 系システムと POSIX 標準でマウントポイントが検出できます。Windowsでは、マウントポイントはドライブレターを持つルート(e.g. c:\)、共有 UNC(e.g. \\server\share)またはマウントされたファイルシステムのディレクトリです。

Added in version 3.7.

バージョン 3.12 で変更: Windows のサポートが追加されました。

Path.is_symlink()

パスがシンボリックリンクを指していた場合 True を返し、その他の場合は False を返します。

パスが存在しない場合も False を返します; (パーミッションエラーのような) その他のエラーは伝搬されます。

Path.is_socket()

パスが Unix ソケット (または Unix ソケットへのシンボリックリンク) を指していた場合 True を返します。その他の種類のファイルの場合 False を返します。

パスが存在しないか壊れたシンボリックリンクだった場合にも False が返されます; (パーミッションエラーのような) その他のエラーは伝搬されます。

Path.is_fifo()

パスが FIFO (または FIFO へのシンボリックリンク) を指していた場合 True を返します。その他の種類のファイルの場合は False を返します。

パスが存在しないか壊れたシンボリックリンクだった場合にも False が返されます; (パーミッションエラーのような) その他のエラーは伝搬されます。

Path.is_block_device()

パスがブロックデバイス (またはブロックデバイスへのシンボリックリンク) を指していた場合 True を返します。その他の種類のファイルの場合は False を返します。

パスが存在しないか壊れたシンボリックリンクだった場合にも False が返されます; (パーミッションエラーのような) その他のエラーは伝搬されます。

Path.is_char_device()

パスがキャラクターデバイス (またはキャラクターデバイスへのシンボリックリンク) を指していた場合、True を返します。その他の種類のファイルの場合 False を返します。

パスが存在しないか壊れたシンボリックリンクだった場合にも False が返されます; (パーミッションエラーのような) その他のエラーは伝搬されます。

Path.iterdir()

パスがディレクトリを指していた場合、ディレクトリの内容のパスオブジェクトを yield します:

>>> 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')

子の要素は任意の順番で yield されます。特殊なパスの '.' と '..' は含まれません。イテレーターを生成したあとにディレクトリにファイルを削除または追加した場合に、そのファイルのパスオブジェクトが含まれるかは定義されていません。

Path.walk(top_down=True, on_error=None, follow_symlinks=False)

Generate the file names in a directory tree by walking the tree either top-down or bottom-up.

For each directory in the directory tree rooted at self (including self but excluding '.' and '..'), the method yields a 3-tuple of (dirpath, dirnames, filenames).

dirpath is a Path to the directory currently being walked, dirnames is a list of strings for the names of subdirectories in dirpath (excluding '.' and '..'), and filenames is a list of strings for the names of the non-directory files in dirpath. To get a full path (which begins with self) to a file or directory in dirpath, do dirpath / name. Whether or not the lists are sorted is file system-dependent.

If the optional argument top_down is true (which is the default), the triple for a directory is generated before the triples for any of its subdirectories (directories are walked top-down). If top_down is false, the triple for a directory is generated after the triples for all of its subdirectories (directories are walked bottom-up). No matter the value of top_down, the list of subdirectories is retrieved before the triples for the directory and its subdirectories are walked.

When top_down is true, the caller can modify the dirnames list in-place (for example, using del or slice assignment), and Path.walk() will only recurse into the subdirectories whose names remain in dirnames. This can be used to prune the search, or to impose a specific order of visiting, or even to inform Path.walk() about directories the caller creates or renames before it resumes Path.walk() again. Modifying dirnames when top_down is false has no effect on the behavior of Path.walk() since the directories in dirnames have already been generated by the time dirnames is yielded to the caller.

By default, errors from os.scandir() are ignored. If the optional argument on_error is specified, it should be a callable; it will be called with one argument, an OSError instance. The callable can handle the error to continue the walk or re-raise it to stop the walk. Note that the filename is available as the filename attribute of the exception object.

By default, Path.walk() does not follow symbolic links, and instead adds them to the filenames list. Set follow_symlinks to true to resolve symlinks and place them in dirnames and filenames as appropriate for their targets, and consequently visit directories pointed to by symlinks (where supported).

注釈

follow_symlinks に True を指定すると、シンボリックリンクが親ディレクトリを指していた場合に、無限ループになることに注意してください。 Path.walk() はすでにたどったディレクトリを管理したりはしません。

注釈

Path.walk() assumes the directories it walks are not modified during execution. For example, if a directory from dirnames has been replaced with a symlink and follow_symlinks is false, Path.walk() will still try to descend into it. To prevent such behavior, remove directories from dirnames as appropriate.

注釈

Unlike os.walk(), Path.walk() lists symlinks to directories in filenames if follow_symlinks is false.

This example displays the number of bytes used by all files in each directory, while ignoring __pycache__ directories:

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__')

This next example is a simple implementation of shutil.rmtree(). Walking the tree bottom-up is essential as rmdir() doesn't allow deleting a directory before it is empty:

# Delete everything reachable from the directory "top".
# CAUTION:  This is dangerous! For example, if top == Path('/'),
# it could delete all of your files.
for root, dirs, files in top.walk(top_down=False):
    for name in files:
        (root / name).unlink()
    for name in dirs:
        (root / name).rmdir()

Added in version 3.12.

Path.lchmod(mode)

Path.chmod() のように振る舞いますが、パスがシンボリックリンクを指していた場合、リンク先ではなくシンボリックリンク自身のモードが変更されます。

Path.lstat()

Path.stat() のように振る舞いますが、パスがシンボリックリンクを指していた場合、リンク先ではなくシンボリックリンク自身の情報を返します。

Path.mkdir(mode=0o777, parents=False, exist_ok=False)

与えられたパスに新しくディレクトリを作成します。mode が与えられていた場合、プロセスの umask 値と組み合わせてファイルのモードとアクセスフラグを決定します。パスがすでに存在していた場合 FileExistsError が送出されます。

parents の値が真の場合、このパスの親ディレクトリを必要に応じて作成します; それらのアクセス制限はデフォルト値が取られ、mode は使用されません (POSIX の mkdir -p コマンドを真似ています)。

parents の値が偽の場合 (デフォルト)、親ディレクトリがないと FileNotFoundError を送出します。

exist_ok の値が (デフォルトの) 偽の場合、対象のディレクトリがすでに存在すると FileExistsError を送出します。

If exist_ok is true, FileExistsError will not be raised unless the given path already exists in the file system and is not a directory (same behavior as the POSIX mkdir -p command).

バージョン 3.5 で変更: exist_ok 引数が追加されました。

Path.open(mode='r', buffering=-1, encoding=None, errors=None, newline=None)

組み込み関数 open() のようにパスが指しているファイルを開きます:

>>> p = Path('setup.py')
>>> with p.open() as f:
...     f.readline()
...
'#!/usr/bin/env python3\n'

Path.owner()

Return the name of the user owning the file. KeyError is raised if the file's uid isn't found in the system database.

Path.read_bytes()

指定されたファイルの内容をバイナリオブジェクトで返します:

>>> p = Path('my_binary_file')
>>> p.write_bytes(b'Binary file contents')
20
>>> p.read_bytes()
b'Binary file contents'

Added in version 3.5.

Path.read_text(encoding=None, errors=None)

指定されたファイルの内容を文字列としてデコードして返します:

>>> p = Path('my_text_file')
>>> p.write_text('Text file contents')
18
>>> p.read_text()
'Text file contents'

ファイルを開いた後に閉じます。オプションのパラメーターの意味は open() と同じです。

Added in version 3.5.

Path.readlink()

( os.readlink() が返す) シンボリックリンクが指すパスを返します:

>>> p = Path('mylink')
>>> p.symlink_to('setup.py')
>>> p.readlink()
PosixPath('setup.py')

Added in version 3.9.

Path.rename(target)

このファイルかディレクトリを与えられた target にリネームし、 target を指すパスのインスタンスを返します。 Unix では target が存在するファイルの場合、ユーザにパーミッションがあれば静かに置換されます。 Windows では target が存在する場合、FileExistsError が送出されます。 target は文字列か別のパスオブジェクトです:

>>> p = Path('foo')
>>> p.open('w').write('some text')
9
>>> target = Path('bar')
>>> p.rename(target)
PosixPath('bar')
>>> target.open().read()
'some text'

targetパスは絶対または相対で指定できます。相対パスは現在の作業ディレクトリからの相対パスとして解釈し、Pathオブジェクトのディレクトリ ではありません。

It is implemented in terms of os.rename() and gives the same guarantees.

バージョン 3.8 で変更: 戻り値を追加し、新しい Path インスタンスを返します。

Path.replace(target)

現在のファイルまたはディレクトリの名前を target に変更し、 target を指すパスのインスタンスを返します。target が既存のファイルか空のディレクトリを指していた場合、無条件に置き換えられます。

targetパスは絶対または相対で指定できます。相対パスは現在の作業ディレクトリからの相対パスとして解釈し、Pathオブジェクトのディレクトリ ではありません。

バージョン 3.8 で変更: 戻り値を追加し、新しい Path インスタンスを返します。

Path.absolute()

正規化やシンボリックリンクの解決をせずに、パスを絶対パスにします。新しいパスオブジェクトを返します:

>>> p = Path('tests')
>>> p
PosixPath('tests')
>>> p.absolute()
PosixPath('/home/antoine/pathlib/tests')

Path.resolve(strict=False)

パスを絶対パスにし、あらゆるシンボリックリンクを解決します。新しいパスオブジェクトが返されます:

>>> p = Path()
>>> p
PosixPath('.')
>>> p.resolve()
PosixPath('/home/antoine/pathlib')

".." 要素は除去されます (このような挙動を示すのはこのメソッドだけです):

>>> p = Path('docs/../setup.py')
>>> p.resolve()
PosixPath('/home/antoine/pathlib/setup.py')

If the path doesn't exist and strict is True, FileNotFoundError is raised. If strict is False, the path is resolved as far as possible and any remainder is appended without checking whether it exists. If an infinite loop is encountered along the resolution path, RuntimeError is raised.

バージョン 3.6 で変更: strict 引数を追加しました(3.6以前の挙動は strict です)。

Path.rglob(pattern, *, case_sensitive=None)

Glob the given relative pattern recursively. This is like calling Path.glob() with "**/" added in front of the pattern, where patterns are the same as for fnmatch:

>>> sorted(Path().rglob("*.py"))
[PosixPath('build/lib/pathlib.py'),
 PosixPath('docs/conf.py'),
 PosixPath('pathlib.py'),
 PosixPath('setup.py'),
 PosixPath('test_pathlib.py')]

デフォルトまたは case_sensitive キーワード専用引数に None を指定した場合、このメソッドはパスの一致判定にプラットフォームに依存した大文字小文字のルールを使用します。一般的にPOSIXは大文字と小文字を区別し、Windowsは区別しません。case_sensitive を True または False に設定するとこの動作を上書きします。

引数 self, pattern を指定して 監査イベント pathlib.Path.rglob を送出します。

バージョン 3.11 で変更: Return only directories if pattern ends with a pathname components separator (sep or altsep).

バージョン 3.12 で変更: case_sensitive 引数が追加されました。

Path.rmdir()

現在のディレクトリを削除します。ディレクトリは空でなければなりません。

Path.samefile(other_path)

このパスが参照するファイルが other_path (Path オブジェクトか文字列) と同じであれば True を、異なるファイルであれば False を返します。意味的には os.path.samefile() および os.path.samestat() と同じです。

なんらかの理由でどちらかのファイルにアクセスできない場合は OSError が送出されます。

>>> p = Path('spam')
>>> q = Path('eggs')
>>> p.samefile(q)
False
>>> p.samefile('spam')
True

Added in version 3.5.

Path.symlink_to(target, target_is_directory=False)

Make this path a symbolic link pointing to target.

Windows では、シンボリックリンクはファイルかディレクトリのどちらかを表しますが、ターゲットに合わせて動的に変化することはありません。ターゲットが存在する場合、シンボリックリンクの種類は対象に合わせて作成されます。ターゲットが存在せず target_is_directory に True が設定された場合、シンボリックリンクはディレクトリのリンクとして作成され、False に設定された場合 (デフォルト) はファイルのリンクになります。Windows 以外のプラットフォームでは target_is_directory は無視されます。

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

注釈

引数の並び (link, target) は os.symlink() とは逆です。

Path.hardlink_to(target)

このパスを target と同じファイルへのハードリンクにします。

注釈

引数の並び (link, target) は os.link() とは逆です。

Added in version 3.10.

Path.touch(mode=0o666, exist_ok=True)

与えられたパスにファイルを作成します。mode が与えられた場合、プロセスの umask 値と組み合わせてファイルのモードとアクセスフラグが決定されます。ファイルがすでに存在した場合、exist_ok が真ならばこの関数は正常に終了します (そしてファイルの更新日付が現在の日時に変更されます)。その他の場合は FileExistsError が送出されます。

Path.unlink(missing_ok=False)

このファイルまたはシンボリックリンクを削除します。パスがディレクトリを指している場合は Path.rmdir() を使用してください。

missing_ok の値が (デフォルトの) 偽の場合、対象のファイルが存在しないと FileNotFoundError を送出します。

missing_ok の値が真の場合、 FileExistsError 例外を送出しません (POSIX の rm -f コマンドの挙動と同じ)。

バージョン 3.8 で変更: missing_ok 引数が追加されました。

Path.write_bytes(data)

指定されたファイルをバイトモードで開き、data を書き込み、ファイルを閉じます:

>>> p = Path('my_binary_file')
>>> p.write_bytes(b'Binary file contents')
20
>>> p.read_bytes()
b'Binary file contents'

同じ名前のファイルがすでにあれば上書きされます。

Added in version 3.5.

Path.write_text(data, encoding=None, errors=None, newline=None)

指定されたファイルをテキストモードで開き、data を書き込み、ファイルを閉じます:

>>> p = Path('my_text_file')
>>> p.write_text('Text file contents')
18
>>> p.read_text()
'Text file contents'

同じ名前のファイルが存在する場合は上書きされます。オプションのパラメーターの意味は open() と同じです。

Added in version 3.5.

バージョン 3.10 で変更: newline パラメータが追加されました。

Correspondence to tools in the os module

下にあるのは、様々な os 関数とそれに相当する PurePath あるいは Path の同等のものとの対応表です。

注釈

Not all pairs of functions/methods below are equivalent. Some of them, despite having some overlapping use-cases, have different semantics. They include os.path.abspath() and Path.absolute(), os.path.relpath() and PurePath.relative_to().

os と os.path

pathlib

os.path.abspath()

Path.absolute() [1]

os.path.realpath()

Path.resolve()

os.chmod()

Path.chmod()

os.mkdir()

Path.mkdir()

os.makedirs()

Path.mkdir()

os.rename()

Path.rename()

os.replace()

Path.replace()

os.rmdir()

Path.rmdir()

os.remove(), os.unlink()

Path.unlink()

os.getcwd()

Path.cwd()

os.path.exists()

Path.exists()

os.path.expanduser()

Path.expanduser() および Path.home()

os.listdir()

Path.iterdir()

os.walk()

Path.walk()

os.path.isdir()

Path.is_dir()

os.path.isfile()

Path.is_file()

os.path.islink()

Path.is_symlink()

os.link()

Path.hardlink_to()

os.symlink()

Path.symlink_to()

os.readlink()

Path.readlink()

os.path.relpath()

PurePath.relative_to() [2]

os.stat()

Path.stat(), Path.owner(), Path.group()

os.path.isabs()

PurePath.is_absolute()

os.path.join()

PurePath.joinpath()

os.path.basename()

PurePath.name

os.path.dirname()

PurePath.parent

os.path.samefile()

Path.samefile()

os.path.splitext()

PurePath.stem および PurePath.suffix

Footnotes

[1]

os.path.abspath() normalizes the resulting path, which may change its meaning in the presence of symlinks, while Path.absolute() does not.

[2]

PurePath.relative_to() requires self to be the subpath of the argument, but os.path.relpath() does not.

os.path --- Common pathname manipulations

Source code: Lib/genericpath.py [https://github.com/python/cpython/tree/3.12/Lib/genericpath.py], Lib/posixpath.py [https://github.com/python/cpython/tree/3.12/Lib/posixpath.py] (for POSIX) and Lib/ntpath.py [https://github.com/python/cpython/tree/3.12/Lib/ntpath.py] (for Windows).

This module implements some useful functions on pathnames. To read or write files see open(), and for accessing the filesystem see the os module. The path parameters can be passed as strings, or bytes, or any object implementing the os.PathLike protocol.

Unix シェルとは異なり、Python はあらゆるパス展開を 自動的には 行いません。アプリケーションがシェルのようなパス展開を必要とした場合は、 expanduser() や expandvars() といった関数を明示的に呼び出すことで行えます。(glob モジュールも参照してください)

参考

pathlib モジュールは高水準のパスオブジェクトを提供します。

注釈

以下のすべての関数は、そのパラメータにバイト列のみ、あるいは文字列のみ受け付けます。パスまたはファイル名を返す場合、返り値は同じ型のオブジェクトになります。

注釈

OS によって異なるパス名の決まりがあるため、標準ライブラリにはこのモジュールのいくつかのバージョンが含まれています。 os.path モジュールは常に現在 Python が動作している OS に適したパスモジュールであるため、ローカルのパスを扱うのに適しています。各々のモジュールをインポートして 常に 一つのフォーマットを利用することも可能です。これらはすべて同じインターフェースを持っています:

posixpath UNIX スタイルのパス用

ntpath Windows パス用

バージョン 3.8 で変更: exists()、 lexists()、 isdir()、 isfile()、 islink()、および ismount() は、OS レベルで表現できない文字列を含む可能性がある例外を送出する代わりに False を返すようになりました。

os.path.abspath(path)

パス名 path の正規化された絶対パスを返します。ほとんどのプラットフォームでは、これは関数 normpath() を次のように呼び出した時と等価です: normpath(join(os.getcwd(), path))。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.basename(path)

パス名 path の末尾のファイル名部分を返します。これは関数 split() に path を渡した時に返されるペアの 2 番めの要素です。この関数が返すのは Unix の basename とは異なります; Unix の basename は '/foo/bar/' に対して 'bar' を返しますが、関数 basename() は空文字列 ('') を返します。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.commonpath(paths)

Return the longest common sub-path of each pathname in the sequence paths. Raise ValueError if paths contain both absolute and relative pathnames, the paths are on the different drives or if paths is empty. Unlike commonprefix(), this returns a valid path.

Added in version 3.5.

バージョン 3.6 で変更: path-like objects のシーケンスを受け入れるようになりました。

os.path.commonprefix(list)

list 内のすべてのパスに共通する接頭辞のうち、最も長いものを (パス名の 1 文字 1 文字を判断して) 返します。list が空の場合、空文字列 ('') を返します。

注釈

この関数は一度に 1 文字ずつ処理するため、不正なパスを返す場合があります。有効なパスを取得するためには、commonpath() を参照してください。

>>> os.path.commonprefix(['/usr/lib', '/usr/local/lib'])
'/usr/l'

>>> os.path.commonpath(['/usr/lib', '/usr/local/lib'])
'/usr'

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.dirname(path)

パス名 path のディレクトリ名を返します。これは関数 split() に path を渡した時に返されるペアの 1 番めの要素です。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.exists(path)

path が実在するパスかオープンしているファイル記述子を参照している場合 True を返します。壊れたシンボリックリンクについては False を返します。一部のプラットフォームでは、たとえ path が物理的に存在していたとしても、要求されたファイルに対する os.stat() の実行権がなければこの関数が False を返すことがあります。

バージョン 3.3 で変更: path は整数でも可能になりました: それがオープンしているファイル記述子なら True が返り、それ以外なら False が返ります。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.lexists(path)

Return True if path refers to an existing path, including broken symbolic links. Equivalent to exists() on platforms lacking os.lstat().

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.expanduser(path)

Unix および Windows では、与えられた引数の先頭のパス要素 ~ 、または ~user を、 user のホームディレクトリのパスに置き換えて返します。

Unix では、先頭の ~ は、環境変数 HOME が設定されているならその値に置き換えられます。設定されていない場合は、現在のユーザのホームディレクトリをビルトインモジュール pwd を使ってパスワードディレクトリから探して置き換えます。先頭の ~user については、直接パスワードディレクトリから探します。

On Windows, USERPROFILE will be used if set, otherwise a combination of HOMEPATH and HOMEDRIVE will be used. An initial ~user is handled by checking that the last directory component of the current user's home directory matches USERNAME, and replacing it if so.

置き換えに失敗したり、引数のパスがチルダで始まっていなかった場合は、パスをそのまま返します。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

バージョン 3.8 で変更: Windowsで HOME は参照しなくなりました。

os.path.expandvars(path)

引数のパスの環境変数を展開して返します。引数の中の $name または ${name} のような形式の文字列は環境変数、 name の値に置き換えられます。不正な変数名や存在しない変数名の場合には変換されず、そのまま返します。

Windows では、 $name や ${name} の形式に加えて、 %name% の形式もサポートされています。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.getatime(path)

path に最後にアクセスした時刻を返します。返り値は、エポック (time モジュールを参照) からの経過秒数を与える浮動小数点数です。ファイルが存在しない、あるいはアクセスできなかった場合は OSError を送出します。

os.path.getmtime(path)

path に最後に更新した時刻を返します。返り値は、エポック (time モジュールを参照) からの経過秒数を与える浮動小数点数です。ファイルが存在しない、あるいはアクセスできなかった場合は OSError を送出します。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.getctime(path)

システムの ctime、Unix系など一部のシステムでは最後にメタデータが変更された時刻、Windows などその他のシステムでは path の作成時刻を返します。返り値はエポック (time モジュールを参照) からの経過時間を示す秒数になります。ファイルが存在しない、あるいはアクセスできなかった場合は OSError を送出します。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.getsize(path)

path のサイズをバイト数で返します。ファイルが存在しない、あるいはアクセスできなかった場合は OSError を送出します。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.isabs(path)

Return True if path is an absolute pathname. On Unix, that means it begins with a slash, on Windows that it begins with a (back)slash after chopping off a potential drive letter.

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.isfile(path)

path が 存在する 一般ファイルなら True を返します。この関数はシンボリックリンクの先を辿るので、同じパスに対して islink() と isfile() の両方が真を返すことがあります。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.isdir(path)

path が 存在する ディレクトリなら True を返します。この関数はシンボリックリンクの先を辿るので、同じパスに対して islink() と isdir() の両方が真を返すことがあります。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.isjunction(path)

Return True if path refers to an existing directory entry that is a junction. Always return False if junctions are not supported on the current platform.

Added in version 3.12.

os.path.islink(path)

path が 存在する ディレクトリを指すシンボリックリンクなら True を返します。 Python ランタイムがシンボリックリンクをサポートしていないプラットフォームでは、常に False を返します。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.ismount(path)

パス名 path がマウントポイント mount point (ファイルシステムの中で異なるファイルシステムがマウントされているところ) なら、 True を返します。 POSIX では、この関数は path の親ディレクトリである path/.. が path と異なるデバイス上にあるか、あるいは path/.. と path が同じデバイス上の同じ i-node を指しているかをチェックします --- これによって全ての Unix 系システムと POSIX 標準でマウントポイントが検出できます。だたし、同じファイルシステムの bind mount の信頼できる検出はできません。 Windows では、ドライブレターを持つルートと共有 UNC は常にマウントポイントであり、また他のパスでは、入力のパスが異なるデバイスからのものか見るために GetVolumePathName が呼び出されます。

バージョン 3.4 で変更: Added support for detecting non-root mount points on Windows.

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.isdevdrive(path)

Return True if pathname path is located on a Windows Dev Drive. A Dev Drive is optimized for developer scenarios, and offers faster performance for reading and writing files. It is recommended for use for source code, temporary build directories, package caches, and other IO-intensive operations.

May raise an error for an invalid path, for example, one without a recognizable drive, but returns False on platforms that do not support Dev Drives. See the Windows documentation [https://learn.microsoft.com/windows/dev-drive/] for information on enabling and creating Dev Drives.

利用可能な環境: Windows 。

Added in version 3.12.

os.path.join(path, *paths)

Join one or more path segments intelligently. The return value is the concatenation of path and all members of *paths, with exactly one directory separator following each non-empty part, except the last. That is, the result will only end in a separator if the last part is either empty or ends in a separator. If a segment is an absolute path (which on Windows requires both a drive and a root), then all previous segments are ignored and joining continues from the absolute path segment.

On Windows, the drive is not reset when a rooted path segment (e.g., r'\foo') is encountered. If a segment is on a different drive or is an absolute path, all previous segments are ignored and the drive is reset. Note that since there is a current directory for each drive, os.path.join("c:", "foo") represents a path relative to the current directory on drive C: (c:foo), not c:\foo.

バージョン 3.6 で変更: path と paths が path-like object を受け付けるようになりました。

os.path.normcase(path)

パス名の大文字・小文字を正規化します。 Windowsでは、パス名にある文字を全て小文字に、スラッシュをバックスラッシュに変換します。他のオペレーティングシステムでは、パスを変更せずに返します。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.normpath(path)

パスを正規化します。余分な区切り文字や上位レベル参照を除去し、A//B、A/B/、A/./B や A/foo/../B などはすべて A/B になります。この文字列操作は、シンボリックリンクを含むパスの意味を変えてしまう場合があります。Windows では、スラッシュをバックスラッシュに変換します。大文字小文字の正規化には normcase() を使用してください。

注釈

On POSIX systems, in accordance with IEEE Std 1003.1 2013 Edition; 4.13 Pathname Resolution [https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_13], if a pathname begins with exactly two slashes, the first component following the leading characters may be interpreted in an implementation-defined manner, although more than two leading characters shall be treated as a single character.

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.realpath(path, *, strict=False)

Return the canonical path of the specified filename, eliminating any symbolic links encountered in the path (if they are supported by the operating system).

If a path doesn't exist or a symlink loop is encountered, and strict is True, OSError is raised. If strict is False, the path is resolved as far as possible and any remainder is appended without checking whether it exists.

注釈

This function emulates the operating system's procedure for making a path canonical, which differs slightly between Windows and UNIX with respect to how links and subsequent path components interact.

Operating system APIs make paths canonical as needed, so it's not normally necessary to call this function.

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

バージョン 3.8 で変更: Windows においてシンボリックリンクとジャンクションが解決されるようになりました。

バージョン 3.10 で変更: strict 引数が追加されました。

os.path.relpath(path, start=os.curdir)

カレントディレクトリあるいはオプションの start ディレクトリからの path への相対パスを返します。これはパス計算で行っており、ファイルシステムにアクセスして path や start の存在や性質を確認することはありません。Windowsでは、 path と start が異なるドライブの場合、 ValueError を送出します。

start defaults to os.curdir.

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.samefile(path1, path2)

引数の両パス名が同じファイルまたはディレクトリを参照している場合、 True を返します。これは、デバイス番号と i-node 番号で決定されます。どちらかのパス名への os.stat() 呼び出しが失敗した場合、例外が送出されます。

バージョン 3.2 で変更: Windows サポートを追加しました。

バージョン 3.4 で変更: Windows が他のプラットフォームと同じ実装を使用するようになりました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.sameopenfile(fp1, fp2)

ファイル記述子 fp1 と fp2 が同じファイルを参照していたら True を返します。

バージョン 3.2 で変更: Windows サポートを追加しました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.samestat(stat1, stat2)

stat タプル stat1 と stat2 が同じファイルを参照していれば True を返します。これらのタプルは os.fstat() 、 os.lstat() あるいは os.stat() の返り値で構いません。この関数は samefile() と sameopenfile() を使用した比較に基いて実装しています。

バージョン 3.4 で変更: Windows サポートを追加しました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.split(path)

パス名 path を (head, tail) のペアに分割します。 tail はパス名の構成要素の末尾で、 head はそれより前の部分です。 tail はスラッシュを含みません; もし path がスラッシュで終わっていれば tail は空文字列になります。もし path にスラッシュがなければ、 head は空文字になります。 path が空文字なら、 head と tail の両方が空文字になります。 head の末尾のスラッシュは head がルートディレクトリ (または 1 個以上のスラッシュだけ) でない限り取り除かれます。 join(head, tail) は常に path と同じ場所を返しますが、文字列としては異なるかもしれません。関数 dirname(), basename() も参照してください。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.splitdrive(path)

パス名 path を (drive, tail) のペアに分割します。drive はマウントポイントか空文字列になります。ドライブ指定をサポートしていないシステムでは、drive は常に空文字になります。どの場合でも、drive + tail は path と等しくなります。

Windows では、パス名はドライブ名/UNC 共有ポイントと相対パスに分割されます。

パスがドライブレターを含む場合、ドライブレターにはコロンまでが含まれます:

>>> splitdrive("c:/dir")
("c:", "/dir")

If the path contains a UNC path, drive will contain the host name and share:

>>> splitdrive("//host/computer/dir")
("//host/computer", "/dir")

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.splitroot(path)

Split the pathname path into a 3-item tuple (drive, root, tail) where drive is a device name or mount point, root is a string of separators after the drive, and tail is everything after the root. Any of these items may be the empty string. In all cases, drive + root + tail will be the same as path.

On POSIX systems, drive is always empty. The root may be empty (if path is relative), a single forward slash (if path is absolute), or two forward slashes (implementation-defined per IEEE Std 1003.1-2017; 4.13 Pathname Resolution [https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_13].) For example:

>>> splitroot('/home/sam')
('', '/', 'home/sam')
>>> splitroot('//home/sam')
('', '//', 'home/sam')
>>> splitroot('///home/sam')
('', '/', '//home/sam')

On Windows, drive may be empty, a drive-letter name, a UNC share, or a device name. The root may be empty, a forward slash, or a backward slash. For example:

>>> splitroot('C:/Users/Sam')
('C:', '/', 'Users/Sam')
>>> splitroot('//Server/Share/Users/Sam')
('//Server/Share', '/', 'Users/Sam')

Added in version 3.12.

os.path.splitext(path)

Split the pathname path into a pair (root, ext) such that root + ext == path, and the extension, ext, is empty or begins with a period and contains at most one period.

If the path contains no extension, ext will be '':

>>> splitext('bar')
('bar', '')

If the path contains an extension, then ext will be set to this extension, including the leading period. Note that previous periods will be ignored:

>>> splitext('foo.bar.exe')
('foo.bar', '.exe')
>>> splitext('/foo/bar.exe')
('/foo/bar', '.exe')

Leading periods of the last component of the path are considered to be part of the root:

>>> splitext('.cshrc')
('.cshrc', '')
>>> splitext('/foo/....jpg')
('/foo/....jpg', '')

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.supports_unicode_filenames

ファイル名に任意の Unicode 文字列を (システムの制限内で) 使用できる場合は True になります。

fileinput --- Iterate over lines from multiple input streams

ソースコード: Lib/fileinput.py [https://github.com/python/cpython/tree/3.12/Lib/fileinput.py]

このモジュールは標準入力やファイルの並びにまたがるループを素早く書くためのヘルパークラスと関数を提供しています。単一のファイルを読み書きしたいだけなら、 open() を参照してください。

典型的な使い方は以下の通りです:

import fileinput
for line in fileinput.input(encoding="utf-8"):
    process(line)

このスクリプトは sys.argv[1:] に列挙されている全てのファイルの行に渡って反復処理を行います。もし列挙されているものがなければ、 sys.stdin がデフォルトとして扱われます。ファイル名として '-' が与えられた場合も、 sys.stdin に置き換えられ、 mode と openhook は無視されます。別のファイル名リストを使いたい時には、そのリストを input() の最初の引数に与えます。ファイル名が 1 つでも受け付けます。

全てのファイルはデフォルトでテキストモードでオープンされます。しかし、 input() や FileInput をコールする際に mode パラメータを指定すれば、これをオーバーライドすることができます。オープン中あるいは読み込み中にI/Oエラーが発生した場合には、 OSError が発生します。

バージョン 3.3 で変更: 以前は IOError が送出されました; それは現在 OSError のエイリアスです。

sys.stdin が2回以上使われた場合は、2回目以降は行を返しません。ただしインタラクティブに利用している時や明示的にリセット (sys.stdin.seek(0) を使う) を行った場合はその限りではありません。

空のファイルは開いた後すぐ閉じられます。空のファイルはファイル名リストの最後にある場合にしか外部に影響を与えません。

ファイルの各行は、各種改行文字まで含めて返されます。ファイルの最後が改行文字で終っていない場合には、改行文字で終わらない行が返されます。

You can control how files are opened by providing an opening hook via the openhook parameter to fileinput.input() or 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 hook_compressed() to support compressed files.

以下の関数がこのモジュールの基本的なインターフェースです:

fileinput.input(files=None, inplace=False, backup='', *, mode='r', openhook=None, encoding=None, errors=None)

FileInput クラスのインスタンスを作ります。生成されたインスタンスは、このモジュールの関数群が利用するグローバルな状態として利用されます。この関数への引数は FileInput クラスのコンストラクタへ渡されます。

FileInput のインスタンスは with 文の中でコンテキストマネージャーとして使用できます。次の例では、仮に例外が生じたとしても with 文から抜けた後で input は閉じられます:

with fileinput.input(files=('spam.txt', 'eggs.txt'), encoding="utf-8") as f:
    for line in f:
        process(line)

バージョン 3.2 で変更: コンテキストマネージャとして使うことができるようになりました。

バージョン 3.8 で変更: キーワード引数 mode と openhook は、キーワード専用引数になりました。

バージョン 3.10 で変更: The keyword-only parameter encoding and errors are added.

以下の関数は fileinput.input() 関数によって作られたグローバルな状態を利用します。アクティブな状態が無い場合には、 RuntimeError が発生します。

fileinput.filename()

現在読み込み中のファイル名を返します。一行目が読み込まれる前は None を返します。

fileinput.fileno()

現在のファイルの "ファイル記述子" を整数値で返します。ファイルがオープンされていない場合 (最初の行の前、ファイルとファイルの間) は -1 を返します。

fileinput.lineno()

最後に読み込まれた行の、累積した行番号を返します。1行目が読み込まれる前は 0 を返します。最後のファイルの最終行が読み込まれた後には、その行の行番号を返します。

fileinput.filelineno()

現在のファイル中での行番号を返します。1行目が読み込まれる前は 0 を返します。最後のファイルの最終行が読み込まれた後には、その行のファイル中での行番号を返します。

fileinput.isfirstline()

最後に読み込まれた行がファイルの1行目なら True 、そうでなければ False を返します。

fileinput.isstdin()

最後に読み込まれた行が sys.stdin から読み込まれていれば True 、そうでなければ False を返します。

fileinput.nextfile()

現在のファイルを閉じます。次の繰り返しでは(存在すれば)次のファイルの最初の行が読み込まれます。閉じたファイルの読み込まれなかった行は、累積の行数にカウントされません。ファイル名は次のファイルの最初の行が読み込まれるまで変更されません。最初の行の読み込みが行われるまでは、この関数は呼び出されても何もしませんので、最初のファイルをスキップするために利用することはできません。最後のファイルの最終行が読み込まれた後にも、この関数は呼び出されても何もしません。

fileinput.close()

シーケンスを閉じます。

このモジュールのシーケンスの振舞いを実装しているクラスのサブクラスを作ることもできます:

class fileinput.FileInput(files=None, inplace=False, backup='', *, mode='r', openhook=None, encoding=None, errors=None)

FileInput クラスはモジュールの関数に対応するメソッド filename() 、 fileno() 、 lineno() 、 filelineno() 、 isfirstline() 、 isstdin() 、 nextfile() および close() を実装しています。イテラブル であることに加えて、次の入力行を返す readline() メソッドがあります。シーケンスはシーケンシャルに読み込むことしかできません。つまりランダムアクセスと readline() を混在させることはできません。

mode を使用すると、 open() に渡すファイルモードを指定することができます。これは 'r' および 'rb' のうちのいずれかとなります。

openhook を指定する場合は、ふたつの引数 filename と mode をとる関数でなければなりません。この関数の返り値は、オープンしたファイルオブジェクトとなります。inplace と openhook を同時に使うことはできません。

You can specify encoding and errors that is passed to open() or openhook.

FileInput のインスタンスは with 文の中でコンテキストマネージャーとして使用できます。次の例では、仮に例外が生じたとしても with 文から抜けた後で input は閉じられます:

with FileInput(files=('spam.txt', 'eggs.txt')) as input:
    process(input)

バージョン 3.2 で変更: コンテキストマネージャとして使うことができるようになりました。

バージョン 3.8 で変更: キーワード引数 mode と openhook は、キーワード専用引数になりました。

バージョン 3.10 で変更: The keyword-only parameter encoding and errors are added.

バージョン 3.11 で変更: The 'rU' and 'U' modes and the __getitem__() method have been removed.

インプレース(in-place)フィルタオプション: キーワード引数 inplace=True が fileinput.input() か FileInput クラスのコンストラクタに渡された場合には、入力ファイルはバックアップファイルに移動され、標準出力が入力ファイルに設定されます(バックアップファイルと同じ名前のファイルが既に存在していた場合には、警告無しに置き替えられます)。これによって入力ファイルをその場で書き替えるフィルタを書くことができます。キーワード引数 backup (通常は backup='.<拡張子>' という形で利用します)が与えられていた場合、バックアップファイルの拡張子として利用され、バックアップファイルは削除されずに残ります。デフォルトでは、拡張子は '.bak' になっていて、出力先のファイルが閉じられればバックアップファイルも消されます。インプレースフィルタ機能は、標準入力を読み込んでいる間は無効にされます。

このモジュールには、次のふたつのオープン時フックが用意されています:

fileinput.hook_compressed(filename, mode, *, encoding=None, errors=None)

gzip や bzip2 で圧縮された (拡張子が '.gz' や '.bz2' の) ファイルを、 gzip モジュールや bz2 モジュールを使って透過的にオープンします。ファイルの拡張子が '.gz' や '.bz2' でない場合は、通常通りファイルをオープンします (つまり、 open() をコールする際に伸長を行いません)。

The encoding and errors values are passed to io.TextIOWrapper for compressed files and open for normal files.

使用例: fi = fileinput.FileInput(openhook=fileinput.hook_compressed, encoding="utf-8")

バージョン 3.10 で変更: The keyword-only parameter encoding and errors are added.

fileinput.hook_encoded(encoding, errors=None)

各ファイルを open() でオープンするフックを返します。指定した encoding および errors でファイルを読み込みます。

使用例: fi = fileinput.FileInput(openhook=fileinput.hook_encoded("utf-8", "surrogateescape"))

バージョン 3.6 で変更: オプションの errors 引数が追加されました。

バージョン 3.10 で非推奨: This function is deprecated since fileinput.input() and FileInput now have encoding and errors parameters.

stat --- Interpreting stat() results

ソースコード: Lib/stat.py [https://github.com/python/cpython/tree/3.12/Lib/stat.py]

The stat module defines constants and functions for interpreting the results of os.stat(), os.fstat() and os.lstat() (if they exist). For complete details about the stat(), fstat() and lstat() calls, consult the documentation for your system.

バージョン 3.4 で変更: stat モジュールは、C 実装に裏付けされるようになりました。

stat モジュールでは、特殊なファイル型を判別するための以下の関数を定義しています:

stat.S_ISDIR(mode)

ファイルのモードがディレクトリの場合にゼロでない値を返します。

stat.S_ISCHR(mode)

ファイルのモードがキャラクタ型の特殊デバイスファイルの場合にゼロでない値を返します。

stat.S_ISBLK(mode)

ファイルのモードがブロック型の特殊デバイスファイルの場合にゼロでない値を返します。

stat.S_ISREG(mode)

ファイルのモードが通常ファイルの場合にゼロでない値を返します。

stat.S_ISFIFO(mode)

ファイルのモードが FIFO (名前つきパイプ) の場合にゼロでない値を返します。

stat.S_ISLNK(mode)

ファイルのモードがシンボリックリンクの場合にゼロでない値を返します。

stat.S_ISSOCK(mode)

ファイルのモードがソケットの場合にゼロでない値を返します。

stat.S_ISDOOR(mode)

ファイルのモードがドアの場合にゼロでない値を返します。

Added in version 3.4.

stat.S_ISPORT(mode)

ファイルのモードがイベントポートの場合にゼロでない値を返します。

Added in version 3.4.

stat.S_ISWHT(mode)

ファイルのモードがホワイトアウトの場合にゼロでない値を返します。

Added in version 3.4.

より一般的なファイルのモードを操作するための二つの関数が定義されています:

stat.S_IMODE(mode)

os.chmod() で設定することのできる一部のファイルモード --- すなわち、ファイルの許可ビット (permission bits) に加え、 (サポートされているシステムでは) スティッキービット (sticky bit)、実行グループ ID 設定 (set-group-id) および実行ユーザ ID 設定 (set-user-id) ビット --- を返します。

stat.S_IFMT(mode)

Return the portion of the file's mode that describes the file type (used by the S_IS*() functions above).

Normally, you would use the 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 stat() system call for each test. These are also useful when checking for information about a file that isn't handled by os.path, like the tests for block and character devices.

以下はプログラム例です:

import os, sys
from stat import *

def walktree(top, callback):
    '''recursively descend the directory tree rooted at top,
       calling the callback function for each regular file'''

    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)

ファイルのモードを人間が可読な文字列に変換するために、追加のユーティリティ関数が提供されています。

stat.filemode(mode)

ファイルのモードを '-rwxrwxrwx' 形式の文字列に変換します。

Added in version 3.3.

バージョン 3.4 で変更: この関数は、S_IFDOOR 、 S_IFPORT 、 S_IFWHT をサポートしています。

以下の全ての変数は、 os.stat() 、 os.fstat() 、または os.lstat() が返す 10 要素のタプルにおけるインデクスを単にシンボル定数化したものです。

stat.ST_MODE

Iノードの保護モード。

stat.ST_INO

Iノード番号。

stat.ST_DEV

Iノードが存在するデバイス。

stat.ST_NLINK

該当する Iノードへのリンク数。

stat.ST_UID

ファイルの所持者のユーザ ID。

stat.ST_GID

ファイルの所持者のグループ ID。

stat.ST_SIZE

通常ファイルではバイトサイズ; いくつかの特殊ファイルでは処理待ちのデータ量。

stat.ST_ATIME

最後にアクセスした時刻。

stat.ST_MTIME

最後に変更された時刻。

stat.ST_CTIME

オペレーティングシステムから返される"ctime"。あるOS(Unixなど)では最後にメタデータが更新された時間となり、別のOS(Windowsなど)では作成時間となります(詳細については各プラットフォームのドキュメントを参照してください)。

"ファイルサイズ" の解釈はファイルの型によって異なります。通常のファイルの場合、サイズはファイルの大きさをバイトで表したものです。ほとんどの Unix 系 (特に Linux) における FIFO やソケットの場合、"サイズ" は os.stat() 、 os.fstat() 、あるいは os.lstat() を呼び出した時点で読み出し待ちであったデータのバイト数になります; この値は時に有用で、特に上記の特殊なファイルを非ブロックモードで開いた後にポーリングを行いたいといった場合に便利です。他のキャラクタ型およびブロック型デバイスにおけるサイズフィールドの意味はさらに異なっていて、背後のシステムコールの実装によります。

以下の変数は、 ST_MODE フィールドで使用されるフラグを定義しています。

最初に挙げる、以下のフラグを使うよりは、上記の関数を使うほうがポータブルです:

stat.S_IFSOCK

ソケット。

stat.S_IFLNK

シンボリックリンク。

stat.S_IFREG

通常のファイル。

stat.S_IFBLK

ブロックデバイス。

stat.S_IFDIR

ディレクトリ。

stat.S_IFCHR

キャラクターデバイス。

stat.S_IFIFO

FIFO。

stat.S_IFDOOR

ドア。

Added in version 3.4.

stat.S_IFPORT

イベントポート。

Added in version 3.4.

stat.S_IFWHT

ホワイトアウト。

Added in version 3.4.

注釈

S_IFDOOR 、 S_IFPORT 、または S_IFWHT は、プラットフォームがこれらのファイルタイプをサポートしていない場合、0 として定義されます。

以下のフラグは、 os.chmod() の mode 引数に使うこともできます:

stat.S_ISUID

UID ビットを設定する。

stat.S_ISGID

グループIDビットを設定する。このビットには幾つかの特殊ケースがあります。ディレクトリに対して設定されていた場合、 BSD のセマンティクスが利用される事を示しています。すなわち、そこに作成されるファイルは、作成したプロセスの有効グループID (effective group ID) ではなくそのディレクトリのグループIDを継承し、そこに作成されるディレクトリにも S_ISGID ビットが設定されます。グループ実行ビット (S_IXGRP) が設定されていないファイルに対してこのビットが設定されていた場合、強制ファイル/レコードロックを意味します (S_ENFMT も参照してください)。

stat.S_ISVTX

スティッキービット。このビットがディレクトリに対して設定されているとき、そのディレクトリ内のファイルは、そのファイルのオーナー、あるいはそのディレクトリのオーナーか特権プロセスのみが、リネームや削除をすることが出来ることを意味しています。

stat.S_IRWXU

ファイルオーナーの権限に対するマスク。

stat.S_IRUSR

オーナーがリード権限を持っている。

stat.S_IWUSR

オーナーがライト権限を持っている。

stat.S_IXUSR

オーナーが実行権限を持っている。

stat.S_IRWXG

グループの権限に対するマスク。

stat.S_IRGRP

グループがリード権限を持っている。

stat.S_IWGRP

グループがライト権限を持っている。

stat.S_IXGRP

グループが実行権限を持っている。

stat.S_IRWXO

その他 (グループ外) の権限に対するマスク。

stat.S_IROTH

その他はリード権限を持っている。

stat.S_IWOTH

その他はライト権限を持っている。

stat.S_IXOTH

その他は実行権限を持っている。

stat.S_ENFMT

System V ファイルロック強制。このフラグは S_ISGID と共有されています。グループ実行ビット (S_IXGRP) が設定されていないファイルでは、ファイル/レコードのロックが強制されます。

stat.S_IREAD

S_IRUSR の、 Unix V7 のシノニム。

stat.S_IWRITE

S_IWUSR の、 Unix V7 のシノニム。

stat.S_IEXEC

S_IXUSR の、 Unix V7 のシノニム。

以下のフラグを os.chflags() の flags 引数として利用できます:

stat.UF_NODUMP

ファイルをダンプしない。

stat.UF_IMMUTABLE

ファイルは変更されない。

stat.UF_APPEND

ファイルは追記しかされない。

stat.UF_OPAQUE

ユニオンファイルシステムのスタックを通したとき、このディレクトリは不透明です。

stat.UF_NOUNLINK

ファイルはリネームや削除されない。

stat.UF_COMPRESSED

ファイルは圧縮して保存される (macOS 10.6+)。

stat.UF_HIDDEN

ファイルは GUI で表示されるべきでない (macOS 10.5+)。

stat.SF_ARCHIVED

ファイルはアーカイブされているかもしれません。

stat.SF_IMMUTABLE

ファイルは変更されない。

stat.SF_APPEND

ファイルは追記しかされない。

stat.SF_NOUNLINK

ファイルはリネームや削除されない。

stat.SF_SNAPSHOT

このファイルはスナップショットファイルです。

詳しい情報は *BSD か macOS システムの man page chflags(2) [https://manpages.debian.org/chflags(2)] を参照してください。

Windows では、os.stat() が返す st_file_attributes メンバー内のビットを検証する際に、以下のファイル属性定数を使用できます。これらの定数の意味について詳しくは、Windows API documentation [https://msdn.microsoft.com/en-us/library/windows/desktop/gg258117.aspx] を参照してください。

stat.FILE_ATTRIBUTE_ARCHIVE

stat.FILE_ATTRIBUTE_COMPRESSED

stat.FILE_ATTRIBUTE_DEVICE

stat.FILE_ATTRIBUTE_DIRECTORY

stat.FILE_ATTRIBUTE_ENCRYPTED

stat.FILE_ATTRIBUTE_HIDDEN

stat.FILE_ATTRIBUTE_INTEGRITY_STREAM

stat.FILE_ATTRIBUTE_NORMAL

stat.FILE_ATTRIBUTE_NOT_CONTENT_INDEXED

stat.FILE_ATTRIBUTE_NO_SCRUB_DATA

stat.FILE_ATTRIBUTE_OFFLINE

stat.FILE_ATTRIBUTE_READONLY

stat.FILE_ATTRIBUTE_REPARSE_POINT

stat.FILE_ATTRIBUTE_SPARSE_FILE

stat.FILE_ATTRIBUTE_SYSTEM

stat.FILE_ATTRIBUTE_TEMPORARY

stat.FILE_ATTRIBUTE_VIRTUAL

Added in version 3.5.

Windows では、os.lstat() が返す st_reparse_tag メンバーとの比較に次の定数が 使えます。これらはよく知られている定数ですが、全てを網羅したリストではありません。

stat.IO_REPARSE_TAG_SYMLINK

stat.IO_REPARSE_TAG_MOUNT_POINT

stat.IO_REPARSE_TAG_APPEXECLINK

Added in version 3.8.

filecmp --- File and Directory Comparisons

ソースコード: Lib/filecmp.py [https://github.com/python/cpython/tree/3.12/Lib/filecmp.py]

filecmp モジュールでは、ファイルおよびディレクトリを比較するため、様々な時間／正確性のトレードオフに関するオプションを備えた関数を定義しています。ファイルの比較については、 difflib モジュールも参照してください。

filecmp モジュールでは以下の関数を定義しています:

filecmp.cmp(f1, f2, shallow=True)

名前が f1 および f2 のファイルを比較し、二つのファイルが同じらしければ True を返し、そうでなければ False を返します。

If shallow is true and the 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.

可搬性と効率のために、この関数は外部プログラムを一切呼び出さないので注意してください。

この関数は過去の比較と結果のキャッシュを使用します。ファイルの os.stat() 情報が変更された場合、キャッシュの項目は無効化されます。clear_cache() を使用して全キャッシュを削除することが出来ます。

filecmp.cmpfiles(dir1, dir2, common, shallow=True)

dir1 と dir2 ディレクトリの中の、common で指定されたファイルを比較します。

ファイル名からなる3つのリスト: match, mismatch, errors を返します。match には双方のディレクトリで一致したファイルのリストが含まれ、mismatch にはそうでないファイル名のリストが入ります。そして errors は比較されなかったファイルが列挙されます。errors になるのは、片方あるいは両方のディレクトリに存在しなかった、ユーザーにそのファイルを読む権限がなかった、その他何らかの理由で比較を完了することができなかった場合です。

引数 shallow はその意味も標準の設定も filecmp.cmp() と同じです。

例えば、cmpfiles('a', 'b', ['c', 'd/e']) は a/c を b/c と、a/d/e を b/d/e と、それぞれ比較します。'c' と 'd/e' はそれぞれ、返される3つのリストのいずれかに登録されます。

filecmp.clear_cache()

filecmp のキャッシュをクリアします。背後のファイルシステムの mtime 分解能未満でのファイル変更後にすぐに比較するような場合に有用です。

Added in version 3.4.

dircmp クラス

class filecmp.dircmp(a, b, ignore=None, hide=None)

Construct a new directory comparison object, to compare the directories a and b. ignore is a list of names to ignore, and defaults to filecmp.DEFAULT_IGNORES. hide is a list of names to hide, and defaults to [os.curdir, os.pardir].

The dircmp class compares files by doing shallow comparisons as described for filecmp.cmp().

dircmp クラスは以下のメソッドを提供しています:

report()

a と b の比較を (sys.stdout に) 表示します。

report_partial_closure()

a および b およびそれらの直下にある共通のサブディレクトリ間での比較結果を出力します。

report_full_closure()

a および b およびそれらの共通のサブディレクトリ間での比較結果を (再帰的に比較して) 出力します。

dircmp クラスは、比較されているディレクトリ階層に関する様々な情報のビットを得るために使用することのできる、興味深い属性を数多く提供しています。

Note that via __getattr__() hooks, all attributes are computed lazily, so there is no speed penalty if only those attributes which are lightweight to compute are used.

left

ディレクトリ a です。

right

ディレクトリ b です。

left_list

a にあるファイルおよびサブディレクトリです。hide および ignore でフィルタされています。

right_list

b にあるファイルおよびサブディレクトリです。hide および ignore でフィルタされています。

common

a および b の両方にあるファイルおよびサブディレクトリです。

left_only

a だけにあるファイルおよびサブディレクトリです。

right_only

b だけにあるファイルおよびサブディレクトリです。

common_dirs

a および b の両方にあるサブディレクトリです。

common_files

a および b の両方にあるファイルです。

common_funny

a および b の両方にあり、ディレクトリ間でタイプが異なるか、 os.stat() がエラーを報告するような名前です。

same_files

クラスのファイル比較オペレータを用いて a と b の両方において同一のファイルです。

diff_files

a と b の両方に存在し、クラスのファイル比較オペレータに基づいて内容が異なるファイルです。

funny_files

a および b 両方にあるが、比較されなかったファイルです。

subdirs

A dictionary mapping names in common_dirs to dircmp instances (or MyDirCmp instances if this instance is of type MyDirCmp, a subclass of dircmp).

バージョン 3.10 で変更: Previously entries were always dircmp instances. Now entries are the same type as self, if self is a subclass of dircmp.

filecmp.DEFAULT_IGNORES

Added in version 3.4.

デフォルトで dircmp に無視されるディレクトリのリストです。

これは subdirs 属性を使用して 2 つのディレクトリを再帰的に探索して、共通の異なるファイルを示すための単純化された例です:

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

tempfile --- Generate temporary files and directories

ソースコード: Lib/tempfile.py [https://github.com/python/cpython/tree/3.12/Lib/tempfile.py]

This module creates temporary files and directories. It works on all supported platforms. TemporaryFile, NamedTemporaryFile, TemporaryDirectory, and SpooledTemporaryFile are high-level interfaces which provide automatic cleanup and can be used as context managers. mkstemp() and mkdtemp() are lower-level functions which require manual cleanup.

ユーザが呼び出し可能な全ての関数とコンストラクタは追加の引数を受け取ります。その引数によって一時ファイルやディレクトリの場所と名前を直接操作することが出来ます。このモジュールに使用されるファイル名はランダムな文字を含みます。そのためファイルは共有された一時ディレクトリに安全に作成されます。後方互換性を保つために引数の順序は若干奇妙です。分かりやすさのためにキーワード引数を使用してください。

このモジュールではユーザが呼び出し可能な以下の項目を定義しています:

tempfile.TemporaryFile(mode='w+b', buffering=-1, encoding=None, newline=None, suffix=None, prefix=None, dir=None, *, errors=None)

一時的な記憶領域として使うことの出来る file-like object を返します。ファイルは mkstemp() と同じルールにより安全に作成されます。オブジェクトは閉じられる (オブジェクトのガベージコレクションによる暗黙的なものも含みます) とすぐに破壊されます。 Unix では、そのファイルのディレクトリエントリは全く作成されないか、ファイル作成後すぐに削除されます。これは他のプラットフォームではサポートされません。よって、この関数で作成された一時ファイルがファイルシステムで可視な名前を持つかどうかをコードで当てにすべきではありません。

The resulting object can be used as a context manager (see 使用例). On completion of the context or destruction of the file object the temporary file will be removed from the filesystem.

作成されたファイルを閉じることなく読み書きできるように、 mode 引数のデフォルトは 'w+b' です。保存されるデータに関わらず全てのプラットフォーム上で一貫して動作するようにバイナリモードが使用されます。 buffering、encoding、errors、newline は、 open() に対する引数として解釈されます。

dir、prefix、suffix 引数の意味とデフォルトは mkstemp() のものと同じです。

返されたオブジェクトは、POSIXプラットフォームでは本物のファイルオブジェクトです。それ以外のプラットフォームでは、file 属性が下層の本物のファイルであるファイル様オブジェクトです。

The os.O_TMPFILE flag is used if it is available and works (Linux-specific, requires Linux kernel 3.11 or later).

On platforms that are neither Posix nor Cygwin, TemporaryFile is an alias for NamedTemporaryFile.

引数 fullpath を指定して 監査イベント tempfile.mkstemp を送出します。

バージョン 3.5 で変更: The os.O_TMPFILE flag is now used if available.

バージョン 3.8 で変更: errors 引数が追加されました。

tempfile.NamedTemporaryFile(mode='w+b', buffering=-1, encoding=None, newline=None, suffix=None, prefix=None, dir=None, delete=True, *, errors=None, delete_on_close=True)

This function operates exactly as TemporaryFile() does, except the following differences:

This function returns a file that is guaranteed to have a visible name in the file system.

To manage the named file, it extends the parameters of TemporaryFile() with delete and delete_on_close parameters that determine whether and how the named file should be automatically deleted.

The returned object is always a file-like object whose file attribute is the underlying true file object. This file-like object can be used in a with statement, just like a normal file. The name of the temporary file can be retrieved from the name attribute of the returned file-like object. On Unix, unlike with the TemporaryFile(), the directory entry does not get unlinked immediately after the file creation.

If delete is true (the default) and delete_on_close is true (the default), the file is deleted as soon as it is closed. If delete is true and delete_on_close is false, the file is deleted on context manager exit only, or else when the file-like object is finalized. Deletion is not always guaranteed in this case (see object.__del__()). If delete is false, the value of delete_on_close is ignored.

Therefore to use the name of the temporary file to reopen the file after closing it, either make sure not to delete the file upon closure (set the delete parameter to be false) or, in case the temporary file is created in a with statement, set the delete_on_close parameter to be false. The latter approach is recommended as it provides assistance in automatic cleaning of the temporary file upon the context manager exit.

Opening the temporary file again by its name while it is still open works as follows:

On POSIX the file can always be opened again.

On Windows, make sure that at least one of the following conditions are fulfilled:

delete is false

additional open shares delete access (e.g. by calling os.open() with the flag O_TEMPORARY)

delete is true but delete_on_close is false. Note, that in this case the additional opens that do not share delete access (e.g. created via builtin open()) must be closed before exiting the context manager, else the os.unlink() call on context manager exit will fail with a PermissionError.

On Windows, if delete_on_close is false, and the file is created in a directory for which the user lacks delete access, then the os.unlink() call on exit of the context manager will fail with a PermissionError. This cannot happen when delete_on_close is true because delete access is requested by the open, which fails immediately if the requested access is not granted.

On POSIX (only), a process that is terminated abruptly with SIGKILL cannot automatically delete any NamedTemporaryFiles it created.

引数 fullpath を指定して 監査イベント tempfile.mkstemp を送出します。

バージョン 3.8 で変更: errors 引数が追加されました。

バージョン 3.12 で変更: Added delete_on_close parameter.

class tempfile.SpooledTemporaryFile(max_size=0, mode='w+b', buffering=-1, encoding=None, newline=None, suffix=None, prefix=None, dir=None, *, errors=None)

This class operates exactly as TemporaryFile() does, except that data is spooled in memory until the file size exceeds max_size, or until the file's fileno() method is called, at which point the contents are written to disk and operation proceeds as with TemporaryFile().

rollover()

The resulting file has one additional method, rollover(), which causes the file to roll over to an on-disk file regardless of its size.

The returned object is a file-like object whose _file attribute is either an io.BytesIO or io.TextIOWrapper object (depending on whether binary or text mode was specified) or a true file object, depending on whether rollover() has been called. This file-like object can be used in a with statement, just like a normal file.

バージョン 3.3 で変更: the truncate method now accepts a size argument.

バージョン 3.8 で変更: errors 引数が追加されました。

バージョン 3.11 で変更: Fully implements the io.BufferedIOBase and io.TextIOBase abstract base classes (depending on whether binary or text mode was specified).

class tempfile.TemporaryDirectory(suffix=None, prefix=None, dir=None, ignore_cleanup_errors=False, *, delete=True)

This class securely creates a temporary directory using the same rules as mkdtemp(). The resulting object can be used as a context manager (see 使用例). On completion of the context or destruction of the temporary directory object, the newly created temporary directory and all its contents are removed from the filesystem.

name

The directory name can be retrieved from the name attribute of the returned object. When the returned object is used as a context manager, the name will be assigned to the target of the as clause in the with statement, if there is one.

cleanup()

The directory can be explicitly cleaned up by calling the cleanup() method. If ignore_cleanup_errors is true, any unhandled exceptions during explicit or implicit cleanup (such as a PermissionError removing open files on Windows) will be ignored, and the remaining removable items deleted on a "best-effort" basis. Otherwise, errors will be raised in whatever context cleanup occurs (the cleanup() call, exiting the context manager, when the object is garbage-collected or during interpreter shutdown).

The delete parameter can be used to disable cleanup of the directory tree upon exiting the context. While it may seem unusual for a context manager to disable the action taken when exiting the context, it can be useful during debugging or when you need your cleanup behavior to be conditional based on other logic.

引数 fullpath を指定して 監査イベント tempfile.mkdtemp を送出します。

Added in version 3.2.

バージョン 3.10 で変更: ignore_cleanup_errors 引数が追加されました。

バージョン 3.12 で変更: Added the delete parameter.

tempfile.mkstemp(suffix=None, prefix=None, dir=None, text=False)

可能な限り最も安全な手段で一時ファイルを生成します。プラットフォームが os.open() の os.O_EXCL フラグを正しく実装している限り、ファイルの作成で競合が起こることはありません。作成したユーザのユーザ ID からのみファイルを読み書き出来ます。プラットフォームがファイルが実行可能かどうかを示す許可ビットを使用している場合、ファイルは誰からも実行不可です。このファイルのファイル記述子は子プロセスに継承されません。

TemporaryFile() と違って、 mkstemp() のユーザは用済みになった時に一時ファイルを削除しなければなりません。

suffix が None でない場合、ファイル名はその接尾辞で終わります。そうでない場合、接尾辞はありません。 mkstemp() はファイル名と接尾辞の間にドットを追加しません。必要であれば suffix の先頭につけてください。

prefix が None でない場合、ファイル名はその接頭辞で始まります。そうでない場合、デフォルトの接頭辞が使われます。必要に応じ、デフォルトは gettempprefix() または gettempprefixb() の返り値です。

dir が None でない場合、ファイルはそのディレクトリ下に作成されます。 None の場合、デフォルトのディレクトリが使われます。デフォルトのディレクトリはプラットフォームに依存するリストから選ばれますが、アプリケーションのユーザは TMPDIR、TEMP、または TMP 環境変数を設定することでディレクトリの場所を管理することができます。そのため、生成されるファイル名が、os.popen() で外部コマンドにクォーティング無しで渡すことができるなどといった、扱いやすい性質を持つ保証はありません。

suffix、prefix、dir のいずれかが None でない場合、それらは同じ型でなければなりません。 bytes の場合、返された名前は str でなはく bytes です。他の挙動はデフォルトで返り値を bytes に強制的にしたい場合は suffix=b'' を渡してください。

text に真を指定した場合は、ファイルはテキストモードで開かれます。そうでない場合(デフォルト)は、ファイルはバイナリモードで開かれます。

mkstemp() は開かれたファイルを扱うための OS レベルのハンドル (os.open() が返すものと同じ) とファイルの絶対パス名が順番に並んだタプルを返します。

引数 fullpath を指定して 監査イベント tempfile.mkstemp を送出します。

バージョン 3.5 で変更: suffix、prefix、dir は bytes の返り値を得るために bytes で渡すことが出来ます。それ以前は str のみ許されていました。適切なデフォルト値を使用するよう、suffix と prefix は None を受け入れ、デフォルトにするようになりました。

バージョン 3.6 で変更: dir パラメタが path-like object を受け付けるようになりました。

tempfile.mkdtemp(suffix=None, prefix=None, dir=None)

可能な限り安全な方法で一時ディレクトリを作成します。ディレクトリの生成で競合は発生しません。ディレクトリを作成したユーザ ID だけが、このディレクトリに対して内容を読み出したり、書き込んだり、検索したりすることができます。

mkdtemp() のユーザは用済みになった時に一時ディレクトリとその中身を削除しなければなりません。

prefix, suffix, dir 引数は mkstemp() 関数のものと同じです。

mkdtemp() は新たに生成されたディレクトリの絶対パス名を返します。

引数 fullpath を指定して 監査イベント tempfile.mkdtemp を送出します。

バージョン 3.5 で変更: suffix、prefix、dir は bytes の返り値を得るために bytes で渡すことが出来ます。それ以前は str のみ許されていました。適切なデフォルト値を使用するよう、suffix と prefix は None を受け入れ、デフォルトにするようになりました。

バージョン 3.6 で変更: dir パラメタが path-like object を受け付けるようになりました。

バージョン 3.12 で変更: mkdtemp() now always returns an absolute path, even if dir is relative.

tempfile.gettempdir()

一時ファイルに用いられるディレクトリの名前を返します。これはモジュール内の全ての関数の dir 引数のデフォルト値を定義します。

Python は呼び出したユーザがファイルを作ることの出来るディレクトリを検索するのに標準的なリストを使用します。そのリストは:

環境変数 TMPDIR で与えられているディレクトリ名。

環境変数 TEMP で与えられているディレクトリ名。

環境変数 TMP で与えられているディレクトリ名。

プラットフォーム依存の場所:

Windows ではディレクトリ C:\TEMP 、 C:\TMP 、 \TEMP 、および \TMP の順。

その他の全てのプラットフォームでは、 /tmp 、 /var/tmp 、および /usr/tmp の順。

最後の手段として、現在の作業ディレクトリ。

この検索の結果はキャッシュされます。以下の tempdir の記述を参照してください。

バージョン 3.10 で変更: Always returns a str. Previously it would return any tempdir value regardless of type so long as it was not None.

tempfile.gettempdirb()

gettempdir() と同じですが返り値は bytesです。

Added in version 3.5.

tempfile.gettempprefix()

一時ファイルを生成する際に使われるファイル名の接頭辞を返します。これにはディレクトリ部は含まれません。

tempfile.gettempprefixb()

gettempprefix() と同じですが返り値は bytes です。

Added in version 3.5.

The module uses a global variable to store the name of the directory used for temporary files returned by gettempdir(). It can be set directly to override the selection process, but this is discouraged. All functions in this module take a dir argument which can be used to specify the directory. This is the recommended approach that does not surprise other unsuspecting code by changing global API behavior.

tempfile.tempdir

When set to a value other than None, this variable defines the default value for the dir argument to the functions defined in this module, including its type, bytes or str. It cannot be a path-like object.

tempdir が (デフォルトの) None の場合、 gettempprefix() を除く上記のいずれかの関数を呼び出す際は常に gettempdir() で述べられているアルゴリズムによって初期化されます。

注釈

Beware that if you set tempdir to a bytes value, there is a nasty side effect: The global default return type of mkstemp() and mkdtemp() changes to bytes when no explicit prefix, suffix, or dir arguments of type str are supplied. Please do not write code expecting or depending on this. This awkward behavior is maintained for compatibility with the historical implementation.

使用例

tempfile モジュールの典型的な使用法のいくつかの例を挙げます:

>>> import tempfile

# create a temporary file and write some data to it
>>> fp = tempfile.TemporaryFile()
>>> fp.write(b'Hello world!')
# read data from file
>>> fp.seek(0)
>>> fp.read()
b'Hello world!'
# close the file, it will be removed
>>> fp.close()

# create a temporary file using a context manager
>>> with tempfile.TemporaryFile() as fp:
...     fp.write(b'Hello world!')
...     fp.seek(0)
...     fp.read()
b'Hello world!'
>>>
# file is now closed and removed

# create a temporary file using a context manager
# close the file, use the name to open the file again
>>> with tempfile.NamedTemporaryFile(delete_on_close=False) as fp:
...     fp.write(b'Hello world!')
...     fp.close()
... # the file is closed, but not removed
... # open the file again by using its name
...     with open(fp.name, mode='rb') as f:
...         f.read()
b'Hello world!'
>>>
# file is now removed

# create a temporary directory using the context manager
>>> with tempfile.TemporaryDirectory() as tmpdirname:
...     print('created temporary directory', tmpdirname)
>>>
# directory and contents have been removed

非推奨の関数と変数

一時ファイルを作成する歴史的な手法は、まず mktemp() 関数でファイル名を作り、その名前を使ってファイルを作成するというものでした。残念ながらこの方法は安全ではありません。なぜなら、mktemp() の呼び出しと最初のプロセスが続いてファイル作成を試みる間に、異なるプロセスがその名前でファイルを同時に作成するかもしれないからです。解決策は二つのステップを同時に行い、ファイルをすぐに作成するというものです。この方法は mkstemp() や上述している他の関数で使用されています。

tempfile.mktemp(suffix='', prefix='tmp', dir=None)

バージョン 2.3 で非推奨: 代わりに mkstemp() を使って下さい。

呼び出し時には存在しなかった、ファイルの絶対パス名を返します。 prefix、suffix、dir 引数は mkstemp() のものと似ていますが、bytes のファイル名、suffix=None、そして prefix=None がサポートされていない点で異なります。

警告

この関数を使うとプログラムのセキュリティホールになる可能性があります。この関数がファイル名を返した後、あなたがそのファイル名を使って次に何かをしようとする段階に至る前に、誰か他の人間があなたを出し抜くことができてしまいます。 mktemp() の利用は、 NamedTemporaryFile() に delete=False 引数を渡すことで、簡単に置き換えることができます:

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

glob --- Unix style pathname pattern expansion

ソースコード: Lib/glob.py [https://github.com/python/cpython/tree/3.12/Lib/glob.py]

glob モジュールは Unix シェルで使われているルールに従い指定されたパターンに一致するすべてのパス名を見つけ出します。返される結果の順序は不定です。チルダ展開は行われませんが、*, ?, および [] で表現される文字範囲については正しくマッチされます。これは、関数 os.scandir() および fnmatch.fnmatch() を使用して行われており、実際にサブシェルを呼び出しているわけではありません。

ドット (.) で始まるファイルは、同じくドットで始まるパターンにのみマッチします。この動作は fnmatch.fnmatch() や pathlib.Path.glob() とは異なります。 (チルダやシェル変数の展開には、 os.path.expanduser() と os.path.expandvars() を使ってください。)

リテラルにマッチさせるには、メタ文字を括弧に入れてください。例えば、'[?]' は文字 '?' にマッチします。

参考

pathlib モジュールは高水準のパスオブジェクトを提供します。

glob.glob(pathname, *, root_dir=None, dir_fd=None, recursive=False, include_hidden=False)

パスの仕様を含む文字列 pathname にマッチするパス名のリストを返します。戻り値のリストは空になる可能性があります。 pathname は (/usr/src/Python-1.5/Makefile のような) 絶対パスも、 (../../Tools/*/*.gif のような) 相対パスもどちらも指定可能で、シェル形式のワイルドカードを含めることもできます。参照先が存在しない、壊れたシンボリックリンクも (シェルの場合と同様に) 結果に含まれます。結果がソートされているかどうかはファイルシステムによります。条件を満たすファイルがこの関数の呼び出し中に追加または削除された場合、それらのファイルに対するパス名が結果に含まれるかどうかはの動作は不定です。

root_dir が None でない場合、その値は検索のルートディレクトリを指定する path-like オブジェクト でなければなりません。これは glob() を呼び出す前にカレントディレクトリを変更したのと同じ効果を持ちます。 pathname が相対パスの場合、戻り値のリストは root_dir からの相対パスを含むことになります。

この関数は dir_fd パラメタで ディレクトリ記述子への相対パス をサポートしています。

recursive が真の場合、パターン "**" はあらゆるファイルや0個以上のディレクトリ、サブディレクトリおよびディレクトリへのシンボリックリンクにマッチします。パターンの末尾が os.sep または os.altsep の場合、ファイルは一致しません。

include_hidden が真の場合、パターン "**" は隠しディレクトリにマッチします。

引数 pathname, recursive を指定して 監査イベント glob.glob を送出します。

引数 pathname, recursive, root_dir, dir_fd を指定して 監査イベント glob.glob/2 を送出します。

注釈

パターン "**" を大きなディレクトリツリーで使用するととてつもなく時間がかかるかもしれません。

注釈

This function may return duplicate path names if pathname contains multiple "**" patterns and recursive is true.

バージョン 3.5 で変更: "**" を使った再帰的な glob がサポートされました。

バージョン 3.10 で変更: root_dir と dir_fd 引数が追加されました。

バージョン 3.11 で変更: include_hidden パラメータが追加されました。

glob.iglob(pathname, *, root_dir=None, dir_fd=None, recursive=False, include_hidden=False)

実際には一度にすべてを格納せずに、glob() と同じ値を順に生成する イテレーター を返します。

引数 pathname, recursive を指定して 監査イベント glob.glob を送出します。

引数 pathname, recursive, root_dir, dir_fd を指定して 監査イベント glob.glob/2 を送出します。

注釈

This function may return duplicate path names if pathname contains multiple "**" patterns and recursive is true.

バージョン 3.5 で変更: "**" を使った再帰的な glob がサポートされました。

バージョン 3.10 で変更: root_dir と dir_fd 引数が追加されました。

バージョン 3.11 で変更: include_hidden パラメータが追加されました。

glob.escape(pathname)

すべての特殊文字 ('?' 、 '*' 、 '[') をエスケープします。特殊文字を含んでいる可能性のある任意のリテラル文字列をマッチさせたいときに便利です。drive/UNC sharepoints の特殊文字はエスケープされません。たとえば Windows では escape('//?/c:/Quo vadis?.txt') は '//?/c:/Quo vadis[?].txt' を返します。

Added in version 3.4.

For example, consider a directory containing the following files: 1.gif, 2.txt, card.gif and a subdirectory sub which contains only the file 3.txt. glob() will produce the following results. Notice how any leading components of the path are preserved.

>>> 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/']

ディレクトリが . で始まるファイルを含んでいる場合、デフォルトでそれらはマッチしません。例えば、 card.gif と .card.gif を含むディレクトリを考えてください:

>>> import glob
>>> glob.glob('*.gif')
['card.gif']
>>> glob.glob('.c*')
['.card.gif']

参考

Module fnmatch

Shell-style filename (not path) expansion

fnmatch --- Unix filename pattern matching

ソースコード: Lib/fnmatch.py [https://github.com/python/cpython/tree/3.12/Lib/fnmatch.py]

このモジュールは Unix のシェル形式のワイルドカードに対応しています。これらは、 (re モジュールでドキュメント化されている) 正規表現とは 異なります 。シェル形式のワイルドカードで使われる特殊文字は、次のとおりです。

Pattern

意味

*

すべてにマッチします

?

任意の一文字にマッチします

[seq]

seq にある任意の文字にマッチします

[!seq]

seq にない任意の文字にマッチします

リテラルにマッチさせるには、メタ文字を括弧に入れてください。例えば、'[?]' は文字 '?' にマッチします。

ファイル名の区切り文字 (Unixでは '/') はこのモジュールに固有なものでは ない ことに注意してください。パス名展開については、 glob モジュールを参照してください (glob はパス名の部分にマッチさせるのに filter() を使っています)。同様に、ピリオドで始まるファイル名はこのモジュールに固有ではなくて、 * と ? のパターンでマッチします。

Also note that functools.lru_cache() with the maxsize of 32768 is used to cache the compiled regex patterns in the following functions: fnmatch(), fnmatchcase(), filter().

fnmatch.fnmatch(name, pat)

Test whether the filename string name matches the pattern string pat, returning True or False. Both parameters are case-normalized using os.path.normcase(). fnmatchcase() can be used to perform a case-sensitive comparison, regardless of whether that's standard for the operating system.

次の例では、カレントディレクトリにある、拡張子が .txt である全てのファイルを表示しています:

import fnmatch
import os

for file in os.listdir('.'):
    if fnmatch.fnmatch(file, '*.txt'):
        print(file)

fnmatch.fnmatchcase(name, pat)

Test whether the filename string name matches the pattern string pat, returning True or False; the comparison is case-sensitive and does not apply os.path.normcase().

fnmatch.filter(names, pat)

Construct a list from those elements of the iterable names that match pattern pat. It is the same as [n for n in names if fnmatch(n, pat)], but implemented more efficiently.

fnmatch.translate(pat)

Return the shell-style pattern pat converted to a regular expression for using with re.match().

例:

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

参考

glob モジュール

Unix シェル形式のパス展開。

linecache --- Random access to text lines

ソースコード: Lib/linecache.py [https://github.com/python/cpython/tree/3.12/Lib/linecache.py]

linecache モジュールは、キャッシュ (一つのファイルから何行も読んでおくのが一般的です) を使って、内部で最適化を図りつつ、Python ソースファイルの任意の行を取得するのを可能にします。 traceback モジュールは、整形されたトレースバックにソースコードを含めるためにこのモジュールを利用しています。

tokenize.open() 関数は、ファイルを開くために使用されます。この関数は、 tokenize.detect_encoding() を使用してファイルのエンコーディングを取得します。エンコーディングトークンが存在しない場合、デフォルトの UTF-8 になります。

linecache モジュールでは次の関数が定義されています:

linecache.getline(filename, lineno, module_globals=None)

filename という名前のファイルから lineno 行目を取得します。この関数は決して例外を発生させません --- エラーの際には '' を返します (行末の改行文字は、見つかった行に含まれます)。

filename という名前のファイルが見付からなかった場合、この関数は最初に module_globals にある PEP 302 [https://peps.python.org/pep-0302/] __loader__ を確認します。ローダーが存在していて、 get_source メソッドが実装されていた場合、ソースコードの行を決定します (get_source() が None を返した場合は、 '' が返ります)。最後に、 filename が相対ファイル名だった場合、モジュール検索パス sys.path のエントリからの相対パスを探します。

linecache.clearcache()

キャッシュをクリアします。それまでに getline() を使って読み込んだファイルの行が必要でなくなったら、この関数を使ってください。

linecache.checkcache(filename=None)

キャッシュが有効かどうかを確認します。キャッシュしたファイルがディスク上で変更された可能性があり、更新後のバージョンが必要な場合にこの関数を使用します。 filename が与えられない場合、全てのキャッシュエントリを確認します。

linecache.lazycache(filename, module_globals)

後々の呼び出しで module_globals が None となっていても、ファイルの形式でないモジュールの行を後から getline() で取得するのに十分な詳細を把握しておきます。この関数により、モジュールの globals を無限に持ち運ぶ必要無しに、実際に必要な行まで

Added in version 3.5.

以下はプログラム例です:

>>> import linecache
>>> linecache.getline(linecache.__file__, 8)
'import sys\n'

shutil --- High-level file operations

ソースコード: Lib/shutil.py [https://github.com/python/cpython/tree/3.12/Lib/shutil.py]

shutil モジュールはファイルやファイルの集まりに対する高水準の操作方法を多数提供します。特にファイルのコピーや削除のための関数が用意されています。個別のファイルに対する操作については、 os モジュールも参照してください。

警告

高水準のファイルコピー関数 (shutil.copy(), shutil.copy2()) でも、ファイルのメタデータの全てをコピーすることはできません。

POSIXプラットフォームでは、これはACLやファイルのオーナー、グループが失われることを意味しています。 Mac OSでは、リソースフォーク(resource fork)やその他のメタデータが利用されません。これは、リソースが失われ、ファイルタイプや生成者コード(creator code)が正しくなくなることを意味しています。 Windowsでは、ファイルオーナー、ACL、代替データストリームがコピーされません。

ディレクトリとファイルの操作

shutil.copyfileobj(fsrc, fdst[, length])

Copy the contents of the 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.

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 path-like objects or path names given as strings.

dst は完全な対象ファイル名でなければなりません。対象としてディレクトリ名を指定したい場合は copy() を参照してください。 src と dst が同じファイルだった場合、 SameFileError を送出します。

dst は書き込み可能でなければなりません。そうでない場合、 OSError 例外を送出します。 dst がすでに存在する場合、そのファイルは置き換えられます。キャラクタデバイスやブロックデバイスなどの特殊なファイルとパイプをこの関数でコピーすることはできません。

follow_symlinks が偽で src がシンボリックリンクの場合、 src のリンク先をコピーする代わりに新しいシンボリックリンクを作成します。

引数 src, dst` を指定して :ref:`監査イベント <auditing>` ``shutil.copyfile を送出します。

バージョン 3.3 で変更: 以前は OSError の代わりに IOError が送出されていました。 follow_symlinks 引数が追加されました。 dst を返すようになりました。

バージョン 3.4 で変更: Error の代わりに SameFileError を送出します。後者は前者のサブクラスなのでこの変更は後方互換です。

バージョン 3.8 で変更: ファイルのコピーをより効率的に行うため、プラットフォーム特有の高速なコピーを行うシステムコールが利用されることがあります。 プラットフォーム依存の効率的なコピー操作 を参照してください。

exception shutil.SameFileError

copyfile() のコピー元と先が同じファイルの場合送出されます。

Added in version 3.4.

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 path-like objects or path names given as strings. If follow_symlinks is false, and both src and dst are symbolic links, 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 copystat() for more information. If copymode() cannot modify symbolic links on the local platform, and it is asked to do so, it will do nothing and return.

引数 src, dst` を指定して :ref:`監査イベント <auditing>` ``shutil.copymode を送出します。

バージョン 3.3 で変更: follow_symlinks 引数が追加されました。

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, copystat() also copies the "extended attributes" where possible. The file contents, owner, and group are unaffected. src and dst are path-like objects or path names given as strings.

follow_symlinks が偽の場合、 src と dst の両方がシンボリックリンクであれば、 copystat() はリンク先ではなくてシンボリックリンク自体を操作します。 src からシンボリックリンクの情報を読み込み、 dst のシンボリックリンクにその情報を書き込みます。

注釈

すべてのプラットフォームでシンボリックリンクの検査と変更ができるわけではありません。 Python はその機能が利用かどうかを調べる方法を用意しています。

os.chmod in os.supports_follow_symlinks が True の場合 copystat() はシンボリックリンクのパーミッションを変更できます。

os.utime in os.supports_follow_symlinks が True の場合 copystat() はシンボリックリンクの最終アクセス時間と最終変更時間を変更できます。

os.chflags in os.supports_follow_symlinks が True の場合 copystat() はシンボリックリンクのフラグを変更できます。 (os.chflags がないプラットフォームもあります。)

機能の幾つか、もしくは全てが利用できないプラットフォームでシンボリックリンクを変更しようとした場合、 copystat() は可能な限り全てをコピーします。copystat() が失敗を返すことはありません。

より詳しい情報は os.supports_follow_symlinks を参照して下さい。

引数 src, dst` を指定して :ref:`監査イベント <auditing>` ``shutil.copystat を送出します。

バージョン 3.3 で変更: follow_symlinks 引数と Linux の拡張属性がサポートされました。

shutil.copy(src, dst, *, follow_symlinks=True)

ファイル src をファイルまたはディレクトリ dst にコピーします。 src と dst は両方共 term:path-like object または文字列でなければなりません。 dst がディレクトリを指定している場合、ファイルは dst の中に、 src のベースファイル名を使ってコピーされます。dst が既に存在するファイルを指定している場合、それは置き換えられます。新しく作成したファイルのパスを返します。

follow_symlinks が偽で、 src がシンボリックリンクの場合、 dst はシンボリックリンクとして作成されます。 follow_symlinks が真で src がシンボリックリンクの場合、 dst には src のリンク先のファイルがコピーされます。

copy() はファイルのデータとパーミッションをコピーします。 (os.chmod() を参照) その他の、ファイルの作成時間や変更時間などのメタデータはコピーしません。コピー元のファイルのメタデータを保存したい場合は、 copy2() を利用してください。

引数 src, dst` を指定して :ref:`監査イベント <auditing>` ``shutil.copyfile を送出します。

引数 src, dst` を指定して :ref:`監査イベント <auditing>` ``shutil.copymode を送出します。

バージョン 3.3 で変更: follow_symlinks 引数が追加されました。新しく作成されたファイルのパスを返すようになりました。

バージョン 3.8 で変更: ファイルのコピーをより効率的に行うため、プラットフォーム特有の高速なコピーを行うシステムコールが利用されることがあります。 プラットフォーム依存の効率的なコピー操作 を参照してください。

shutil.copy2(src, dst, *, follow_symlinks=True)

copy2() はファイルのメタデータを保持しようとすることを除けば copy() と等価です。

When follow_symlinks is false, and src is a symbolic link, 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, copy2() will preserve all the metadata it can; copy2() never raises an exception because it cannot preserve file metadata.

copy2() はファイルのメタデータをコピーするために copystat() を利用します。シンボリックリンクのメタデータを変更するためのプラットフォームサポートについては copystat() を参照して下さい。

引数 src, dst` を指定して :ref:`監査イベント <auditing>` ``shutil.copyfile を送出します。

引数 src, dst` を指定して :ref:`監査イベント <auditing>` ``shutil.copystat を送出します。

バージョン 3.3 で変更: follow_symlinks 引数が追加されました。 拡張ファイルシステム属性もコピーしようと試みます (現在は Linux のみ)。新しく作成されたファイルへのパスを返すようになりました。

バージョン 3.8 で変更: ファイルのコピーをより効率的に行うため、プラットフォーム特有の高速なコピーを行うシステムコールが利用されることがあります。 プラットフォーム依存の効率的なコピー操作 を参照してください。

shutil.ignore_patterns(*patterns)

このファクトリ関数は、 copytree() 関数の ignore 引数に渡すための呼び出し可能オブジェクトを作成します。 glob形式の patterns にマッチするファイルやディレクトリが無視されます。下の例を参照してください。

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.

各ディレクトリのパーミッション、最終アクセス時間、最終変更時間は copystat() でコピーされます。それぞれのファイルは copy2() でコピーされます。

symlinks が真の場合、ソースツリー内のシンボリックリンクは新しいツリーでもシンボリックになり、元のシンボリックリンクのメタデータはプラットフォームが許す限りコピーされます。偽の場合や省略された場合、リンク先のファイルの内容とメタデータが新しいツリーにコピーされます。

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 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 os.symlink().

ignore は copytree() が走査しているディレクトリと os.listdir() が返すその内容のリストを引数として受け取ることのできる呼び出し可能オブジェクトでなければなりません。 copytree() は再帰的に呼び出されるので、 ignore はコピーされる各ディレクトリ毎に呼び出されます。 ignore の戻り値はカレントディレクトリに相対的なディレクトリ名およびファイル名のシーケンス（すなわち第二引数の項目のサブセット）でなければなりません。それらの名前はコピー中に無視されます。 ignore_patterns() を用いて glob 形式のパターンによって無視する呼び出し可能オブジェクトを作成することが出来ます。

例外が発生した場合、理由のリストとともに Error を送出します。

copy_function は各ファイルをコピーするために利用される呼び出し可能オブジェクトでなければなりません。copy_function はコピー元のパスとコピー先のパスを引数に呼び出されます。デフォルトでは copy2() が利用されますが、同じ特徴を持つ関数 (shutil.copy() など) ならどれでも利用可能です。

If dirs_exist_ok is false (the default) and dst already exists, a 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.

引数 src, dst` を指定して :ref:`監査イベント <auditing>` ``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 で変更: symlinks が偽の場合メタデータをコピーします。 dst を返すようになりました。

バージョン 3.8 で変更: ファイルのコピーをより効率的に行うため、プラットフォーム特有の高速なコピーを行うシステムコールが利用されることがあります。 プラットフォーム依存の効率的なコピー操作 を参照してください。

バージョン 3.8 で変更: Added the dirs_exist_ok parameter.

shutil.rmtree(path, ignore_errors=False, onerror=None, *, onexc=None, dir_fd=None)

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.

この関数は ディレクトリ記述子への相対パス をサポートしています。

注釈

必要な fd ベースの関数をサポートしているプラットフォームでは、 シンボリックリンク攻撃に耐性のあるバージョンの rmtree() がデフォルトで利用されます。それ以外のプラットフォームでは、 rmtree() の実装はシンボリックリンク攻撃の影響を受けます。適当なタイミングと環境で攻撃者はファイルシステム上のシンボリックリンクを操作して、それ以外の方法ではアクセス不可能なファイルを削除することが出来ます。アプリケーションは、どちらのバージョンの rmtree() が利用されているかを知るために関数のデータ属性 rmtree.avoids_symlink_attacks を利用することができます。

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 sys.exc_info().

引数 path, dir_fd を指定して 監査イベント shutil.rmtree を送出します。

バージョン 3.3 で変更: プラットフォームが fd ベースの関数をサポートする場合に自動的に使用されるシンボリックリンク攻撃に耐性のあるバージョンが追加されました。

バージョン 3.8 で変更: Windows では、ディレクトリへのジャンクションを削除する際にリンク先ディレクトリにあるファイルを削除しなくなりました。

バージョン 3.11 で変更: 引数 dir_fd を追加しました。

バージョン 3.12 で変更: Added the onexc parameter, deprecated onerror.

rmtree.avoids_symlink_attacks

プラットフォームと実装がシンボリックリンク攻撃に耐性のあるバージョンの rmtree() を提供しているかどうかを示します。現在のところ、この属性は fd ベースのディレクトリアクセス関数をサポートしているプラットフォームでのみ真になります。

Added in version 3.3.

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 os.rename() semantics.

If the destination is on the current filesystem, then 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 os.rename() cannot be used. If the source is a directory, copytree() is called, passing it the copy_function. The default copy_function is copy2(). Using 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.

引数 src, dst` を指定して :ref:`監査イベント <auditing>` ``shutil.move を送出します。

バージョン 3.3 で変更: 異なるファイルシステムに対する明示的なシンボリックリンク処理が追加されました。これにより GNU mv の振る舞いに適応するようになります。 dst を返すようになりました。

バージョン 3.5 で変更: キーワード引数 copy_function が追加されました。

バージョン 3.8 で変更: ファイルのコピーをより効率的に行うため、プラットフォーム特有の高速なコピーを行うシステムコールが利用されることがあります。 プラットフォーム依存の効率的なコピー操作 を参照してください。

バージョン 3.9 で変更: src と dst が両方とも path-like object を受け付けるようになりました。

shutil.disk_usage(path)

指定されたパスについて、ディスクの利用状況を、名前付きタプル (named tuple) で返します。このタプルには total, used, free という属性があり、それぞれトータル、使用中、空きの容量をバイト単位で示します。 path はファイルまたはディレクトリです。

注釈

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.

Added in version 3.3.

バージョン 3.8 で変更: Windowsにおいても path にディレクトリだけでなくファイルを指定できるようになりました。

Availability: Unix, Windows。

shutil.chown(path, user=None, group=None)

指定された path のオーナー user と/または group を変更します。

user はシステムのユーザー名か uid です。 group も同じです。少なくともどちらかの引数を指定する必要があります。

内部で利用している os.chown() も参照してください。

引数 path, user, group を指定して 監査イベント shutil.chown を送出します。

利用可能な環境: Unix。

Added in version 3.3.

shutil.which(cmd, mode=os.F_OK | os.X_OK, path=None)

cmd を実行しようとした時に実行される実行ファイルのパスを返します。 cmd を呼び出せない場合は None を返します。

mode is a permission mask passed to os.access(), by default determining if the file exists and is executable.

When no path is specified, the results of os.environ() are used, returning either the "PATH" value or a fallback of os.defpath.

On Windows, the current directory is prepended to the path if mode does not include os.X_OK. When the mode does include os.X_OK, the Windows API 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 NoDefaultCurrentDirectoryInExePath.

Also on Windows, the PATHEXT variable is used to resolve commands that may not already include an extension. For example, if you call shutil.which("python"), which() will search PATHEXT to know that it should look for python.exe within the path directories. For example, on Windows:

>>> shutil.which("python")
'C:\\Python33\\python.EXE'

This is also applied when cmd is a path that contains a directory component:

>> shutil.which("C:\\Python33\\python")
'C:\\Python33\\python.EXE'

Added in version 3.3.

バージョン 3.8 で変更: bytes 型も使用できるようになりました。 cmd が bytes 型の場合、戻り値も bytes 型です。

バージョン 3.12 で変更: On Windows, the current directory is no longer prepended to the search path if mode includes os.X_OK and WinAPI NeedCurrentDirectoryForExePathW(cmd) is false, else the current directory is prepended even if it is already in the search path; PATHEXT is used now even when cmd includes a directory component or ends with an extension that is in PATHEXT; and filenames that have no extension can now be found.

バージョン 3.12.1 で変更: On Windows, if mode includes os.X_OK, executables with an extension in PATHEXT will be preferred over executables without a matching extension. This brings behavior closer to that of Python 3.11.

exception shutil.Error

この例外は複数ファイルの操作を行っているときに生じる例外をまとめたものです。 copytree() に対しては例外の引数は3つのタプル(srcname, dstname, exception)からなるリストです。

プラットフォーム依存の効率的なコピー操作

Python 3.8 から、ファイルのコピーを伴う全ての関数 (copyfile(), copy(), copy2(), copytree(), および move()) はより効率的なファイルのコピーのためにプラットフォーム特有の "高速なコピー" を行うことがあります (bpo-33671 [https://bugs.python.org/issue?@action=redirect&bpo=33671] を参照してください). ここで "高速なコピー" とは、 "outfd.write(infd.read())" のようにPython が管理するユーザー空間のバッファを利用することを避け、コピー操作がカーネル空間内で行われることを意味します。

macOS では fcopyfile [http://www.manpagez.com/man/3/copyfile/] がファイルの内容（メタデータを除く）をコピーするために利用されます。

Linux では os.sendfile() が利用されます。

Windows では shutil.copyfile() はより大きなバッファサイズをデフォルトとして使います (6 KiB の代わりに 1 MiB が使われます)。また、 memoryview() ベースの変形である shutil.copyfileobj() が使われます。

高速なコピー操作が失敗して出力ファイルにデータが書き込まれなかった場合、shutil はユーザーへの通知なしでより効率の低い copyfileobj() 関数にフォールバックします。

バージョン 3.8 で変更.

copytree の例

ignore_patterns() ヘルパ関数を利用する例です:

from shutil import copytree, ignore_patterns

copytree(source, destination, ignore=ignore_patterns('*.pyc', 'tmp*'))

この例では、 .pyc ファイルと、 tmp で始まる全てのファイルやディレクトリを除いて、全てをコピーします。

ignore 引数にロギングさせる別の例です。

from shutil import copytree
import logging

def _logpath(path, names):
    logging.info('Working in %s', path)
    return []   # nothing will be ignored

copytree(source, destination, ignore=_logpath)

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.

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)

アーカイブ化操作

Added in version 3.2.

バージョン 3.5 で変更: xztar 形式のサポートが追加されました。

圧縮とアーカイブ化されているファイルの読み書きの高水準なユーティリティも提供されています。これらは zipfile 、 tarfile モジュールに依拠しています。

shutil.make_archive(base_name, format[, root_dir[, base_dir[, verbose[, dry_run[, owner[, group[, logger]]]]]]])

アーカイブファイル (zip や tar) を作成してその名前を返します。

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 zlib module is available), "tar", "gztar" (if the zlib module is available), "bztar" (if the bz2 module is available), or "xztar" (if the lzma module is available).

root_dir はアーカイブファイルのルートとなるディレクトリです。アーカイブに含まれる全てのパスは root_dir からの相対パスになります。これは、アーカイブファイルを生成する前に root_dir へ移動することに相当します。

base_dir はアーカイブを開始するディレクトリです。すなわち、 base_dir アーカイブに含まれるファイルとディレクトリに対する共通のプレフィックスになります。 base_dir は root_dir からの相対パスでなければなりません。 base_dir と root_dir を組み合わせて使う方法については base_dir を使ったアーカイブ化の例 を参照してください。

root_dir と base_dir のどちらも、デフォルトはカレントディレクトリです。

dry_run が真の場合、アーカイブは作成されませんが実行される操作は logger に記録されます。

owner と group は、tar アーカイブを作成するときに使われます。デフォルトでは、カレントのオーナーとグループを使います。

logger は PEP 282 [https://peps.python.org/pep-0282/] に互換なオブジェクトでなければなりません。これは普通は logging.Logger のインスタンスです。

verbose 引数は使用されず、非推奨です。

引数 base_name`, format, root_dir, base_dir``を指定して :ref:`監査イベント <auditing>` ``shutil.make_archive を送出します。

注釈

This function is not thread-safe when custom archivers registered with 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.

バージョン 3.8 で変更: format="tar" で作成されたアーカイブでは、レガシーなGNU形式に代わってモダンな pax (POSIX.1-2001) 形式が使われます。

バージョン 3.10.6 で変更: This function is now made thread-safe during creation of standard .zip and tar archives.

shutil.get_archive_formats()

アーカイブ化をサポートしているフォーマットのリストを返します。返されるシーケンスのそれぞれの要素は、タプル (name, description) です。

デフォルトでは、 shutil は次のフォーマットを提供しています。

zip: ZIP ファイル (zlib モジュールが利用可能な場合)。

tar: 非圧縮の tar ファイル。 POSIX.1-2001 pax 形式が使われます。

gztar: gzip で圧縮された tar ファイル (zlib モジュールが利用可能な場合)。

bztar: bzip2 で圧縮された tar ファイル (bz2 モジュールが利用可能な場合)。

xztar: xz で圧縮された tar ファイル (lzma モジュールが利用可能な場合)。

register_archive_format() を使って、新しいフォーマットを登録したり、既存のフォーマットに独自のアーカイバを提供したりできます。

shutil.register_archive_format(name, function[, extra_args[, description]])

アーカイバをフォーマット name に登録します。

function はアーカイブのアンパックに使用される呼び出し可能オブジェクトです。funciton は作成するファイルの base_name、続いてアーカイブを開始する元の base_dir (デフォルトは os.curdir) を受け取ります。さらなる引数は、次のキーワード引数として渡されます: owner, group, dry_run ならびに logger (make_archive() に渡されます)。

If function has the custom attribute function.supports_root_dir set to 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 make_archive() is not thread-safe.

extra_args は、与えられた場合、 (name, value) の対のシーケンスで、アーカイバ呼び出し可能オブジェクトが使われるときに追加のキーワード引数として使われます。

description は、アーカイバのリストを返す get_archive_formats() で使われます。デフォルトでは空の文字列です。

バージョン 3.12 で変更: Added support for functions supporting the root_dir argument.

shutil.unregister_archive_format(name)

アーカイブフォーマット name を、サポートされているフォーマットのリストから取り除きます。

shutil.unpack_archive(filename[, extract_dir[, format[, filter]]])

アーカイブをアンパックします。 filename はアーカイブのフルパスです。

extract_dir はアーカイブをアンパックする先のディレクトリ名です。指定されなかった場合は現在の作業ディレクトリを利用します。

format はアーカイブフォーマットで、 "zip", "tar", "gztar", "bztar", "xztar" あるいは register_unpack_format() で登録したその他のフォーマットのどれかです。指定されなかった場合、 unpack_archive() はアーカイブファイル名の拡張子に対して登録されたアンパッカーを利用します。アンパッカーが見つからなかった場合、 ValueError を発生させます。

The keyword-only filter argument is passed to the underlying unpacking function. For zip files, filter is not accepted. For tar files, it is recommended to set it to 'data', unless using features specific to tar and UNIX-like filesystems. (See Extraction filters for details.) The 'data' filter will become the default for tar files in Python 3.14.

引数 filename, extract_dir, format を指定して 監査イベント shutil.unpack_archive を送出します。

警告

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

バージョン 3.7 で変更: filename と extract_dir が path-like object を受け付けるようになりました。

バージョン 3.12 で変更: Added the filter argument.

shutil.register_unpack_format(name, extensions, function[, extra_args[, description]])

アンパック用のフォーマットを登録します。 name はフォーマット名で、 extensions はそのフォーマットに対応する拡張子 (例えば Zip ファイルに対して .zip) のリストです。

function is the callable that will be used to unpack archives. The callable will receive:

the path of the archive, as a positional argument;

the directory the archive must be extracted to, as a positional argument;

possibly a filter keyword argument, if it was given to unpack_archive();

additional keyword arguments, specified by extra_args as a sequence of (name, value) tuples.

フォーマットの説明として description を指定することができます。これは get_unpack_formats() 関数によって返されます。

shutil.unregister_unpack_format(name)

アンパックフォーマットを登録解除します。 name はフォーマットの名前です。

shutil.get_unpack_formats()

登録されているすべてのアンパックフォーマットをリストで返します。戻り値のリストの各要素は (name, extensions, description) の形のタプルです。

デフォルトでは、 shutil は次のフォーマットを提供しています。

zip: ZIP ファイル (対応するモジュールが利用可能な場合にのみ圧縮ファイルはアンパックされます)。

tar: 圧縮されていない tar ファイル。

gztar: gzip で圧縮された tar ファイル (zlib モジュールが利用可能な場合)。

bztar: bzip2 で圧縮された tar ファイル (bz2 モジュールが利用可能な場合)。

xztar: xz で圧縮された tar ファイル (lzma モジュールが利用可能な場合)。

register_unpack_format() を使って新しいフォーマットや既存のフォーマットに対する別のアンパッカーを登録することができます。

アーカイブ化の例

この例では、ユーザの .ssh ディレクトリにあるすべてのファイルを含む、 gzip された tar ファイルアーカイブを作成します:

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

結果のアーカイブは、以下のものを含みます:

$ 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

base_dir を使ったアーカイブ化の例

この例では、 上記の例 と同じく make_archive() の使い方を示しますが、ここでは特に base_dir の使い方を説明します。以下のようなディレクトリ構造があるとします。

$ tree tmp
tmp
└── root
    └── structure
        ├── content
            └── please_add.txt
        └── do_not_add.txt

作成するアーカイブには please_add.txt が含まれますが、いっぽう do_not_add.txt は含まないようにします。この場合以下のようにします。

>>> from shutil import make_archive
>>> import os
>>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive'))
>>> make_archive(
...     archive_name,
...     'tar',
...     root_dir='tmp/root',
...     base_dir='structure/content',
... )
'/Users/tarek/my_archive.tar'

アーカイブに含まれるファイルをリストすると、以下のようになります。

$ python -m tarfile -l /Users/tarek/myarchive.tar
structure/content/
structure/content/please_add.txt

出力ターミナルのサイズの取得

shutil.get_terminal_size(fallback=(columns, lines))

ターミナルウィンドウのサイズを取得します。

幅と高さについて、それぞれ COLUMNS と LINES という環境変数をチェックします。その変数が定義されていて値が正の整数であればそれを利用します。

典型的な COLUMNS や LINES が定義されていない場合には、 sys.__stdout__ に接続されているターミナルに os.get_terminal_size() を呼び出して問い合わせます。

システムが対応していない場合やターミナルに接続していないなどの理由でターミナルサイズの問い合わせに失敗した場合、 fallback 引数に与えられた値を利用します。 fallback のデフォルト値は (80, 24) で、これは多くのターミナルエミュレーターが利用しているデフォルトサイズです。

戻り値は os.terminal_size 型の名前付きタプルです。

参考: The Single UNIX Specification, Version 2, Other Environment Variables [https://pubs.opengroup.org/onlinepubs/7908799/xbd/envvar.html#tag_002_003].

Added in version 3.3.

バージョン 3.11 で変更: The fallback values are also used if os.get_terminal_size() returns zeroes.

データの永続化

この章で解説されるモジュール群は Python データをディスクに永続的な形式で保存します。モジュール pickle とモジュール marshal は多くの Python データ型をバイト列に変換し、バイト列から再生成します。様々な DBM 関連モジュールはハッシュを基にした、文字列から他の文字列へのマップを保存するファイルフォーマット群をサポートします。

この章で解説されるモジュールのリスト:

pickle --- Python object serialization

他の Python モジュールとの関係

marshal との比較

json との比較

データストリームの形式

モジュールインターフェース

pickle 化、非 pickle 化できるもの

クラスインスタンスの pickle 化

外部オブジェクトの永続化

ディスパッチテーブル

状態を持つオブジェクトの扱い

型、関数、その他のオブジェクトに対するリダクションのカスタマイズ

アウトオブバウンドバッファ

生産者 API

消費者 API

使用例

グローバル変数を制限する

性能

使用例

copyreg --- Register pickle support functions

使用例

shelve --- Python object persistence

制限事項

使用例

marshal --- Internal Python object serialization

dbm --- Interfaces to Unix "databases"

dbm.gnu --- GNU database manager

dbm.ndbm --- New Database Manager

dbm.dumb --- 可搬性のある DBM 実装

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

チュートリアル

リファレンス

モジュール関数

モジュール定数

Connection オブジェクト

Cursor オブジェクト

Row オブジェクト

Blob オブジェクト

PrepareProtocol オブジェクト

例外

SQLite と Python の型

デフォルトの適合関数(adapters)とデフォルトの変換関数(converters)(非推奨)

コマンドライン・インターフェース

ハウツー・ガイド

プレースホルダを使用して SQL クエリに値を結び付ける方法

カスタム Python 型を SQLite 値に適合させる方法

適合可能オブジェクトの書き方

適合用呼び出し可能オブジェクト(adapter callables)の登録方法

SQLite 値をカスタム Python 型に変換する方法

適合関数と変換関数のレシピ集

接続(connection)ショートカット・メソッドの使い方

接続(connection)コンテキストマネージャの使い方

SQLite URI の操作方法

行工場(row factories)の作成方法と使用方法

How to handle non-UTF-8 text encodings

説明

トランザクション制御

autocommit 属性に依るトランザクション制御

isolation_level 属性に依るトランザクション制御

pickle --- Python object serialization

ソースコード: Lib/pickle.py [https://github.com/python/cpython/tree/3.12/Lib/pickle.py]

pickle モジュールは Python オブジェクトの直列化および直列化されたオブジェクトの復元のためのバイナリプロトコルを実装しています。"Pickle 化" は Python オブジェクト階層をバイトストリームに変換する処理、"非 pickle 化" は (バイナリファイル または バイトライクオブジェクト から) バイトストリームをオブジェクト階層に復元する処理を意味します。pickle 化 (および非 pickle 化) は "直列化 (serialization)"、"整列化 (marshalling)"、あるいは [1] "平坦化 (flattening)" とも呼ばれますが、混乱を避けるため、ここでは "Pickle 化"、"非 pickle 化" で統一します。

警告

pickle モジュールは 安全ではありません 。信頼できるデータのみを非 pickle 化してください。

非 pickle 化の過程で任意のコードを実行する ような、悪意ある pickle オブジェクトを生成することが可能です。信頼できない提供元からのデータや、改竄された可能性のあるデータの非 pickle 化は絶対に行わないでください。

データが改竄されていないことを保証したい場合は、 hmac による鍵付きハッシュ化を検討してください。

信頼できないデータを処理する場合 json のようなより安全な直列化形式の方が適切でしょう。 json との比較 を参照してください。

他の Python モジュールとの関係

marshal との比較

Python には marshal と呼ばれるより原始的な直列化モジュールがありますが、一般的に Python オブジェクトを直列化する方法としては pickle を選ぶべきです。 marshal は基本的に .pyc ファイルをサポートするために存在しています。

pickle モジュールはいくつかの点で marshal と明確に異なります:

pickle モジュールでは、同じオブジェクトが再度直列化されることのないよう、すでに直列化されたオブジェクトについて追跡情報を保持します。 marshal はこれを行いません。

この機能は再帰的オブジェクトと共有オブジェクトの両方に重要な関わりをもっています。再帰的オブジェクトとは自分自身に対する参照を持っているオブジェクトです。再帰的オブジェクトは marshal で扱うことができず、実際、再帰的オブジェクトを marshal 化しようとすると Python インタプリタをクラッシュさせてしまいます。共有オブジェクトは、直列化しようとするオブジェクト階層の異なる複数の場所で同じオブジェクトに対する参照が存在する場合に生じます。pickle はそのようなオブジェクトを一度だけ保存し、その他全ての参照がそのマスターコピーを指し示すことを保証します。共有オブジェクトを共有のままにしておくことは、変更可能なオブジェクトの場合には非常に重要です。

marshal はユーザ定義クラスやそのインスタンスを直列化するために使うことができません。 pickle はクラスインスタンスを透過的に保存したり復元したりすることができますが、クラス定義をインポートすることが可能で、かつオブジェクトが保存された際と同じモジュールで定義されていなければなりません。

marshal の直列化形式は Python のバージョン間での移植性を保証していません。 .pyc ファイルをサポートすることが主な役割であるため、 Python 開発者は必要があれば直列化形式に非互換な変更を加える権利を有しています。 いっぽう pickle の直列化形式は、互換性のあるプロトコルを選ぶという条件のもとで Python リリース間の後方互換性が保証されます。また処理すべきデータが Python 2 と Python 3 の間で非互換な型を含む場合も、 pickle 化および非 pickle 化のコードはそのような互換性を破る言語の境界を適切に取り扱います。

json との比較

pickle プロトコルと JSON (JavaScript Object Notation) [https://json.org] との基本的な違いは以下のとおりです:

JSON はテキストの直列化フォーマット (大抵の場合 utf-8 にエンコードされますが、その出力は Unicode 文字列です) で、pickle はバイナリの直列化フォーマットです;

JSON は人間が読める形式ですが、pickle はそうではありません;

JSON は相互運用可能で Python 以外でも広く使用されていますが、pickle は Python 固有です;

JSON は、デフォルトでは Python の組み込み型の一部しか表現することができず、カスタムクラスに対しても行えません; pickle は極めて多くの Python 組み込み型を表現できます (その多くは賢い Python 内省機構によって自動的に行われます; 複雑なケースでは 固有のオブジェクト API によって対応できます)。

pickleとは異なり、信頼できないJSONを復元するだけでは、任意のコードを実行できる脆弱性は発生しません。

参考

json モジュール: JSON への直列化および復元を行うための標準ライブラリモジュール。

データストリームの形式

The data format used by pickle is Python-specific. This has the advantage that there are no restrictions imposed by external standards such as JSON or XDR (which can't represent pointer sharing); however it means that non-Python programs may not be able to reconstruct pickled Python objects.

デフォルトでは、pickle データフォーマットは比較的コンパクトなバイナリ表現を使用します。サイズの抑制目的の最適化が必要なら、pickle されたデータを効率的に 圧縮する ことができます。

pickletools モジュールには pickle によって生成されたデータストリームを解析するためのツールが含まれます。pickletools のソースコードには、pickle プロトコルで使用される命令コードに関する詳細なコメントがあります。

現在 pickle 化には 6 種類のプロトコルを使用できます。より高いプロトコルを使用するほど、作成された pickle を読み込むためにより高い Python のバージョンが必要になります。

プロトコルバージョン 0 はオリジナルの「人間に判読可能な」プロトコルで、Python の初期のバージョンとの後方互換性を持ちます。

プロトコルバージョン 1 は旧形式のバイナリフォーマットで、これも Python の初期バージョンと互換性があります。

プロトコルバージョン 2 は Python 2.3 で導入されました。このバージョンでは 新方式のクラス のより効率的な pickle 化を提供しました。プロトコル 2 による改良に関する情報は PEP 307 [https://peps.python.org/pep-0307/] を参照してください。

プロトコルバージョン 3 は Python 3 で追加されました。 bytes オブジェクトを明示的にサポートしており、 Python 2.x で unpickle することはできません。これは Python 3.0から3.7のデフォルトプロトコルでした。

プロトコルバージョン 4 は Python 3.4 で追加されました。このバージョンでは巨大なオブジェクトのサポート、より多くの種類のオブジェクトの pickle 化、および一部のデータ形式の最適化が行われました。これはPython 3.8からのデフォルトプロトコルです。プロトコル 4 による改良に関する情報は PEP 3154 [https://peps.python.org/pep-3154/] を参照してください。

プロトコルバージョン 5 は Python 3.8 で追加されました。このバージョンでは帯域外データのサポートが追加され、また帯域内データに対するパフォーマンスが向上します。プロトコルバージョン 5 によってもたらされる改善についての情報は PEP 574 [https://peps.python.org/pep-0574/] を参照してください。

注釈

直列化は永続性より原始的な概念です。 pickle はファイルオブジェクトの読み書きを行いますが、永続オブジェクトの命名に関する問題にも、(さらに困難な) 永続オブジェクトへの並列アクセスに関する問題にも対応しません。pickle モジュールは複雑なオブジェクトをバイトストリームに変換し、バイトストリームから同じ内部構造のオブジェクトに復元することができます。これらのバイトストリームはファイルに出力されることが多いでしょうが、ネットワークを介して送信したり、データベースに格納することもありえます。shelve モジュールは、オブジェクトを DBM 方式のデータベースファイル上で pickle 化および非 pickle 化するシンプルなインターフェースを提供します。

モジュールインターフェース

オブジェクト階層を直列化するには、dumps() 関数を呼ぶだけです。同様に、データストリームを復元するには、loads() 関数を呼びます。しかし、直列化および復元に対してより多くのコントロールを行いたい場合、それぞれ Pickler または Unpickler オブジェクトを作成することができます。

pickle モジュールは以下の定数を提供しています:

pickle.HIGHEST_PROTOCOL

利用可能なうち最も高い プロトコルバージョン (整数)。この値は protocol 値として関数 dump() および dumps() と、Pickler コンストラクターに渡すことができます。

pickle.DEFAULT_PROTOCOL

pickle化に使われるデフォルトの プロトコルバージョン (整数)。HIGHEST_PROTOCOL よりも小さい場合があります。現在のデフォルトプロトコルは4です。このプロトコルはPython3.4で初めて導入され、その前のバージョンとは互換性がありません。

バージョン 3.0 で変更: デフォルトプロトコルは 3 です。

バージョン 3.8 で変更: デフォルトプロトコルは 4 です。

この pickle 化の手続きを便利にするために、 pickle モジュールでは以下の関数を提供しています:

pickle.dump(obj, file, protocol=None, *, fix_imports=True, buffer_callback=None)

オブジェクト obj を pickle 化し、すでにオープンしている ファイルオブジェクト file に書き込みます。Pickler(file, protocol).dump(obj) と等価です。

引数 file, protocol, fix_imports および buffer_callback は Pickler のコンストラクタと同じ意味になります。

バージョン 3.8 で変更: buffer_callback 引数が追加されました。

pickle.dumps(obj, protocol=None, *, fix_imports=True, buffer_callback=None)

ファイルに書く代わりに、bytes オブジェクトとしてオブジェクト obj の pickle 表現を返します。

引数 protocol, fix_imports および buffer_callback は Pickler のコンストラクタと同じ意味になります。

バージョン 3.8 で変更: buffer_callback 引数が追加されました。

pickle.load(file, *, fix_imports=True, encoding='ASCII', errors='strict', buffers=None)

あるオブジェクトの pickle 化表現を、オープンしている ファイルオブジェクト file から読み込み、その中で指定されているオブジェクト階層に再構成して返します。これは Unpickler(file).load() と等価です。

pickle のプロトコルバージョンは自動的に検出されます。したがって protocol 引数は必要ありません。pickle 化オブジェクト表現より後のバイト列は無視されます。

引数 file, fix_imports, encoding, errors, strict および buffers は Unpickler のコンストラクタと同じ意味になります。

バージョン 3.8 で変更: buffers 引数が追加されました。

pickle.loads(data, /, *, fix_imports=True, encoding='ASCII', errors='strict', buffers=None)

オブジェクトのピックル化表現 data から再構成されたオブジェクト階層を返します。 data は バイトライクオブジェクト (bytes-like object) でなければなりません。

pickle のプロトコルバージョンは自動的に検出されます。したがって protocol 引数は必要ありません。pickle 化オブジェクト表現より後のバイト列は無視されます。

引数 fix_imports, encoding, errors, strict および buffers は Unpickler のコンストラクタと同じ意味になります。

バージョン 3.8 で変更: buffers 引数が追加されました。

pickle モジュールでは 3 つの例外を定義しています:

exception pickle.PickleError

他の pickle 化例外の共通基底クラス。Exception を継承しています。

exception pickle.PicklingError

Pickler が pickle 化不可能なオブジェクトに遭遇したときに送出されるエラー。PickleError を継承しています。

どんな種類のオブジェクトが pickle 化できるのか確認するには pickle 化、非 pickle 化できるもの を参照してください。

exception pickle.UnpicklingError

データ破損やセキュリティ違反のような、オブジェクトを非 pickle 化するのに問題がある場合に送出されるエラー。PickleError を継承します。

非 picke 化の最中に他の例外が送出されることもあるので注意してください。これには AttributeError, EOFError, ImportError, IndexError が含まれます (ただし必ずしもこれらに限定されません)。

pickle モジュールでは、3 つのクラス Pickler, Unpickler および PickleBuffer を提供しています:

class pickle.Pickler(file, protocol=None, *, fix_imports=True, buffer_callback=None)

pickle 化されたオブジェクトのデータストリームを書き込むためのバイナリファイルを引数にとります。

任意の引数 protocol は、整数で、pickle 化で使用するプロトコルを指定します; サポートされているプロトコルは 0 から HIGHEST_PROTOCOL までになります。指定されない場合、DEFAULT_PROTOCOL が使用されます。負数が与えられた場合、HIGHEST_PROTOCOL が使用されます。

引数 file は、1 バイトの引数一つを受け付ける write() メソッドを持たなければなりません。すなわち、file には、バイナリの書き込み用にオープンされたファイルオブジェクト、io.BytesIO オブジェクト、このインターフェースに適合するその他のカスタムオブジェクトをとることができます。

fix_imports が真であり、かつ、protocol が 3 未満の場合、pickle は新しい Python 3 の名前と Python 2 で使用されていた古いモジュール名との対応付けを試みるので、pickle データストリームは Python 2 でも読み込み可能です。

If buffer_callback is None (the default), buffer views are serialized into file as part of the pickle stream.

If buffer_callback is not None, then it can be called any number of times with a buffer view. If the callback returns a false value (such as None), the given buffer is out-of-band; otherwise the buffer is serialized in-band, i.e. inside the pickle stream.

It is an error if buffer_callback is not None and protocol is None or smaller than 5.

バージョン 3.8 で変更: buffer_callback 引数が追加されました。

dump(obj)

obj の pickle 化表現を、コンストラクターで与えられた、すでにオープンしているファイルオブジェクトに書き込みます。

persistent_id(obj)

デフォルトでは何もしません。このメソッドはサブクラスがオーバーライドできるように存在します。

persistent_id() が None を返す場合、通常通り obj が pickle 化されます。それ以外の値を返した場合、Pickler がその値を obj のために永続的な ID として出力するようになります。この永続的な ID の意味は Unpickler.persistent_load() によって定義されています。persistent_id() によって返された値自身は永続的な ID を持つことができないことに注意してください。

詳細および使用例については 外部オブジェクトの永続化 を参照してください。

dispatch_table

pickler オブジェクトのディスパッチテーブルは copyreg.pickle() を使用して宣言できる種類の reduction functions のレジストリです。これはキーがクラスでその値が減少関数のマッピング型オブジェクトです。減少関数は関連するクラスの引数を 1 個とり、__reduce__() メソッドと同じインターフェースでなければなりません。

デフォルトでは、pickler オブジェクトは dispatch_table 属性を持たず、代わりに copyreg モジュールによって管理されるグローバルなディスパッチテーブルを使用します。しかし、特定の pickler オブジェクトによる pickle 化をカスタマイズするために dispatch_table 属性に dict-like オブジェクトを設定することができます。あるいは、Pickler のサブクラスが dispatch_table 属性を持てば、そのクラスのインスタンスに対するデフォルトのディスパッチテーブルとして使用されます。

使用例については ディスパッチテーブル を参照してください。

Added in version 3.3.

reducer_override(obj)

Pickler のサブクラスで定義可能な特殊なリデューサ (reducer) です。このメソッドは dispatch_table 内のいかなるリデューサよりも優先されます。このメソッドは __reduce__() メソッドのインターフェースと適合していなければなりません。また、メソッドが NotImplemented を返すことにより、 dispatch_table に登録されたリデューサにフォールバックして obj を直列化することもできます。

詳細な例については、 型、関数、その他のオブジェクトに対するリダクションのカスタマイズ を参照してください。

Added in version 3.8.

fast

廃止予定です。真値が設定されれば高速モードを有効にします。高速モードは、メモの使用を無効にします。それにより余分な PUT 命令コードを生成しなくなるので pickle 化処理が高速化します。自己参照オブジェクトに対しては使用すべきではありません。さもなければ Pickler に無限再帰を起こさせるでしょう。

よりコンパクトな pickle 化を必要とする場合は、pickletools.optimize() を使用してください。

class pickle.Unpickler(file, *, fix_imports=True, encoding='ASCII', errors='strict', buffers=None)

これは pickle データストリームの読み込みのためにバイナリファイルをとります。

pickle のプロトコルバージョンは自動的に検出されます。したがって protocol 引数は必要ありません。

引数 file は io.BufferedIOBase のインターフェースと同様に、整数を引数にとる read() 、バッファを引数にとる readinto() 、引数を取らない readline() の3つのメソッドを持たなければなりません。したがって、 file はバイナリ読み込みモードでオープンされたディスク上のファイル、 io.BytesIO オブジェクト、または上記インターフェース要件を満たす任意のカスタムオブジェクトのいずれかです。

オプション引数 fix_imports, encoding および errors はPython 2で生成された pickle ストリームに対する互換性サポートを制御するために使われます。 fix_imports が真の場合、 pickle は古い Python 2 の名前を Python 3 の新しい名前に対応づけようとします。 encoding と errors は pickle に Python 2 で pickle 化された 8 ビット文字列をデコードする方法を指定します; これらの引数のデフォルト値はそれぞれ 'ASCII' と 'strict' です。 encoding は 8 ビット文字列インスタンスをバイトオブジェクトとして読み込む場合は 'bytes' を指定します。 Python 2 で pickle 化された NumPy 配列および datetime, date, time の各インスタンスを非 pickle 化するためには encoding='latin1' を使う必要があります。

If buffers is None (the default), then all data necessary for deserialization must be contained in the pickle stream. This means that the buffer_callback argument was None when a Pickler was instantiated (or when dump() or dumps() was called).

If buffers is not None, it should be an iterable of buffer-enabled objects that is consumed each time the pickle stream references an out-of-band buffer view. Such buffers have been given in order to the buffer_callback of a Pickler object.

バージョン 3.8 で変更: buffers 引数が追加されました。

load()

コンストラクターで与えられたオープンしたファイルオブジェクトからオブジェクトの pickle 化表現を読み込み、その中で指定されたオブジェクト階層に再構成して返します。オブジェクトの pickle 化表現より後のバイト列は無視されます。

persistent_load(pid)

デフォルトで UnpicklingError を送出します。

もし定義されていれば、persistent_load() は永続的な ID pid によって指定されたオブジェクトを返す必要があります。永続的な ID が無効な場合、UnpicklingError を送出しなければなりません。

詳細および使用例については 外部オブジェクトの永続化 を参照してください。

find_class(module, name)

必要なら module をインポートして、そこから name という名前のオブジェクトを返します。ここで module および name 引数は str オブジェクトです。その名前が示唆することに反して find_class() は関数を探すためにも使われることに注意してください。

サブクラスは、どんな型のオブジェクトを、どのようにロードするか (潜在的にはセキュリティリスクの減少) に関する制御を得るためにこれをオーバーライドすることができます。詳細に関しては グローバル変数を制限する を参照してください。

引数 modulet, name を指定して 監査イベント pickle.find_class を送出します。

class pickle.PickleBuffer(buffer)

pickle 可能なデータをあらわすバッファのラッパーです。 buffer はバッファライクなオブジェクト (bytes-like object) や N 次元配列のような バッファ機能を提供する オブジェクトでなければなりません。

PickleBuffer はそれ自身バッファ機能を提供します。したがってこのクラスのインスタンスを、バッファ機能を提供するオブジェクトを期待する memoryview など他の API に渡すことが可能です。

PickleBuffer オブジェクトはプロトコル 5 以上でのみ直列化可能で、 アウトオブバウンド (out-of-band) の直列化 に対応しています。

Added in version 3.8.

raw()

このバッファの背後にあるメモリ領域への memoryview を返します。戻り値のオブジェクトはフォーマット B (符号なしバイト) の C-連続な1次元のメモリビューです。バッファが C-連続でも Fortran-連続でもない場合 BufferError 例外が送出されます。

release()

PickleBuffer オブジェクトを通じてアクセスされる背後のバッファを解放します。

pickle 化、非 pickle 化できるもの

以下の型は pickle 化できます:

組み込み定数(None, True, False, Ellipsis, と NotImplemented)

整数、浮動小数点数、複素数

文字列、バイト列、バイト配列

pickle 化可能なオブジェクトからなるタプル、リスト、集合および辞書

モジュールのトップレベルで定義された関数 (def で定義されたもののみで lambda で定義されたものは含まない)

モジュールのトップレベルで定義されているクラス

__getstate__() メソッドを呼び出した結果が pickle 化可能であるようなクラスのインスタンス (詳細は クラスインスタンスの pickle 化 を参照)。

pickle 化できないオブジェクトを pickle 化しようとすると、PicklingError 例外が送出されます。この例外が起きたとき、すでに元のファイルには未知の長さのバイト列が書き込まれている場合があります。極端に再帰的なデータ構造を pickle 化しようとした場合には再帰の深さ制限を越えてしまうかもしれず、この場合には RecursionError が送出されます。この制限は、sys.setrecursionlimit() で慎重に上げていくことは可能です。

関数 (組込みおよびユーザー定義) は、値ではなく、完全 修飾名 で pickle 化されます。[2] これは、関数名のみがそれを含んでいるモジュールおよびクラスの名前をともなって pickle 化されることを意味します。関数のコードやその属性は pickle 化されません。すなわち、非 pickle 化する環境で定義したモジュールがインポート可能な状態になっており、そのモジュール内に関数名のオブジェクトが含まれていなければなりません。この条件を満たさなかった場合は例外が送出されます。[3]

クラスも同様に完全修飾名で pickle 化されるので、unpickle 化環境には同じ制限が課せられます。クラス中のコードやデータは何も pickle 化されないので、以下の例ではクラス属性 attr が unpickle 化環境で復元されないことに注意してください:

class Foo:
    attr = 'A class attribute'

picklestring = pickle.dumps(Foo)

pickle 化可能な関数やクラスがモジュールのトップレベルで定義されていなければならないのはこれらの制限のためです。

同様に、クラスのインスタンスが pickle 化された際、そのクラスのコードおよびデータはオブジェクトと一緒に pickle 化されることはありません。インスタンスのデータのみが pickle 化されます。この仕様は、クラス内のバグを修正したりメソッドを追加した後でも、そのクラスの以前のバージョンで作られたオブジェクトを読み出せるように意図的に行われています。あるクラスの多くのバージョンで使われるような長命なオブジェクトを作ろうと計画しているなら、そのクラスの __setstate__() メソッドによって適切な変換が行われるようにオブジェクトのバージョン番号を入れておくとよいかもしれません。

クラスインスタンスの pickle 化

この節では、クラスインスタンスがどのように pickle 化または非 pickle 化されるのかを定義したり、カスタマイズしたり、コントロールしたりするのに利用可能な一般的機構について説明します。

ほとんどの場合、インスタンスを pickle 化できるようにするために追加のコードは必要ありません。デフォルトで、pickle はインスタンスのクラスと属性を内省によって検索します。クラスインスタンスが非 pickle 化される場合、通常その __init__() メソッドは実行 されません 。デフォルトの振る舞いは、最初に初期化されていないインスタンスを作成して、次に保存された属性を復元します。次のコードはこの振る舞いの実装を示しています:

def save(obj):
    return (obj.__class__, obj.__dict__)

def restore(cls, attributes):
    obj = cls.__new__(cls)
    obj.__dict__.update(attributes)
    return obj

クラスは、いくつかの特殊メソッドを提供することによって、デフォルトの振る舞いを変更することができます:

object.__getnewargs_ex__()

プロトコル 2 以上の場合、 __getnewargs_ex__() メソッドを実装したクラスは __new__() メソッドに渡された値の非 pickle 化の方法を指示することができます。このメソッドは、オブジェクトの生成に必要な位置引数のタプル args と名前付き引数の辞書 kwargs のペア (args, kwargs) を返さなければなりません。これらは非 pickle 化に際して __new__() メソッドに渡されます。

クラスの __new__() メソッドがキーワード専用引数を求める場合はこのメソッドを実装すべきです。そうしない場合、互換性のため __getnewargs__() メソッドの実装を推奨します。

バージョン 3.6 で変更: __getnewargs_ex__() がプロトコル 2 と 3 でも使われるようになりました。

object.__getnewargs__()

このメソッドは __getnewargs_ex__() と同じような機能を提供しますが、位置引数のみをサポートします。このメソッドは引数のタプル args を返さなければならず、戻り値は非 pickle 化に際して __new__() メソッドに渡されます。

__getnewargs_ex__() が定義されていると __getnewargs__() は呼び出しません。

バージョン 3.6 で変更: Python 3.6以前のプロトコル 2 と 3 では、__getnewargs_ex__() の代わりに __getnewargs__() が呼び出されていました。

object.__getstate__()

Classes can further influence how their instances are pickled by overriding the method __getstate__(). It is called and the returned object is pickled as the contents for the instance, instead of a default state. There are several cases:

For a class that has no instance __dict__ and no __slots__, the default state is None.

For a class that has an instance __dict__ and no __slots__, the default state is self.__dict__.

For a class that has an instance __dict__ and __slots__, the default state is a tuple consisting of two dictionaries: self.__dict__, and a dictionary mapping slot names to slot values. Only slots that have a value are included in the latter.

For a class that has __slots__ and no instance __dict__, the default state is a tuple whose first item is None and whose second item is a dictionary mapping slot names to slot values described in the previous bullet.

バージョン 3.11 で変更: Added the default implementation of the __getstate__() method in the object class.

object.__setstate__(state)

非 pickle 化に際して、クラスが __setstate__() を定義している場合、それは非 pickle 化された状態とともに呼び出されます。その場合、状態オブジェクトが辞書でなければならないという要求はありません。そうでなければ、 pickle された状態は辞書で、その要素は新しいインスタンスの辞書に割り当てられます。

注釈

If __reduce__() returns a state with value None at pickling, the __setstate__() method will not be called upon unpickling.

__getstate__() および __setstate__() メソッドの使い方に関する詳細な情報については 状態を持つオブジェクトの扱い 節を参照してください。

注釈

非 pickle 化に際しては、 __getattr__(), __getattribute__(), または __setattr__() といったメソッドがインスタンスに対して呼ばれることがあります。これらのメソッドが何らかの内部の不変な条件が真であることを必要とする場合、その型は __new__() メソッドを実装してそのような不変な条件を構築すべきです。なぜならばインスタンスの非 pickle 化においては __init__() メソッドは呼ばれないからです。

これらから見るように、pickle は上記のメソッドを直接使用しません。実際には、これらのメソッドは __reduce__() 特殊メソッドを実装するコピープロトコルの一部です。コピープロトコルは、pickle 化とオブジェクトのコピーに必要な、データを取得するための統一されたインターフェースを提供します。 [4]

強力ですが、クラスに __reduce__() メソッドを直接実装することはエラーを起こしやすくなります。この理由のため、クラスの設計者は可能なかぎり高レベルインターフェース (__getnewargs_ex__()、__getstate__() および __setstate__()) を使用するべきです。公開はしているものの、__reduce__() の使用は、あくまでオプションとして、より効果的な pickle 化につながる場合、あるいはその両方の場合のみにしてください。

object.__reduce__()

このインターフェースは現在、以下のように定義されています。 __reduce__() メソッドは引数を取らず、文字列あるいは (こちらの方が好まれますが) タプルのいずれかを返すべきです (返されたオブジェクトは、しばしば "reduce value" と呼ばれます)。

文字列が返された場合、その文字列はグローバル変数の名前として解釈されます。それはオブジェクトのモジュールから見たローカル名であるべきです; pickle モジュールは、オブジェクトのモジュールを決定するためにモジュールの名前空間を検索します。この振る舞いは、典型的にシングルトンで便利です。

タプルが返された場合、それは 2〜6 要素長でなければなりません。オプションのアイテムは省略することができます。あるいはそれらの値として None を渡すことができます。各要素の意味は順に:

オブジェクトの初期バージョンを作成するために呼ばれる呼び出し可能オブジェクト。

呼出し可能オブジェクトに対する引数のタプル。呼出し可能オブジェクトが引数を受け取らない場合、空のタプルが与えられなければなりません。

任意で、前述のオブジェクトの __setstate__() メソッドに渡されるオブジェクトの状態。オブジェクトがそのようなメソッドを持たない場合、値は辞書でなければならず、それはオブジェクトの __dict__ 属性に追加されます。

任意で、連続した要素を yield する (シーケンスではなく) イテレーター。これらの要素は obj.append(item) を使用して、あるいはバッチでは obj.extend(list_of_items) を使用して、オブジェクトに追加されます。これは主としてリストのサブクラスに対して使用されますが、適切なシグネチャを持つ append と extend メソッド があるかぎり、他のクラスで使用することもできます。 (append() または extend() のどちらが使用されるかは、どの pickle プロトコルバージョンが使われるかに加えて追加されるアイテムの数にも依存します。したがって、両方をサポートする必要があります)

任意で、連続する key-value ペアを yield する (シーケンスでなく) イテレーター。これらの要素は obj[key] = value を使用して、オブジェクトに格納されます。これは主として辞書のサブクラスに対して使用されますが、__setitem__() を実装しているかぎり他のクラスで使用することもできます。

任意で、シグネチャが (obj, state) である呼び出し可能オブジェクト。このオブジェクトは、 obj のスタティックな __setstate__() メソッドの代わりに、ユーザーがオブジェクトの状態を更新する方法をプログラム的に制御することを許します。 None 以外の場合、この呼び出し可能オブジェクトは obj の __setstate__() メソッドに優先します。

Added in version 3.8: 任意の6番目のタプル要素 (obj, state) が追加されました。

object.__reduce_ex__(protocol)

別の方法として、__reduce_ex__() メソッドを定義することもできます。唯一の違いは、このメソッドは単一の整数引数、プロトコルバージョンを取る必要があるということです。もし定義された場合、pickle は __reduce__() メソッドよりもこのメソッドを優先します。さらに、__reduce__() は自動的に拡張版の同義語になります。このメソッドの主な用途は、古い Python リリースに対して後方互換性のある reduce value を提供することです。

外部オブジェクトの永続化

オブジェクトの永続化のために、pickle モジュールは、pickle データストリーム外のオブジェクトに対する参照の概念をサポートしています。そのようなオブジェクトは永続的 ID によって参照されます。それは、英数文字の文字列 (プロトコル 0 に対して) [5] あるいは単に任意のオブジェクト (より新しい任意のプロトコルに対して) のいずれかです。

そのような永続的 ID の分解能は pickle モジュールでは定義されていません; これはこの分解能を pickler および unpickler のそれぞれ persistent_id() および persistent_load() 上でのユーザー定義メソッドに移譲します。

外部の永続的 ID を持つ pickle オブジェクトの pickler は、引数にオブジェクトを取り、None かオブジェクトの永続的 ID を返すカスタム persistent_id() メソッドを持たなくてはなりません。None を返す場合、pickler は通常通りマーカーとともにオブジェクトを pickle 化するため、unpickler はそれを永続的 ID として認識します。

外部オブジェクトを非 pickle 化するには、unpickler は永続的 ID オブジェクトを取り被参照オブジェクトを返すカスタム persistent_load() メソッドを持たなくてはなりません。

これは、外部のオブジェクトを参照によって pickle 化するために永続的 ID をどのように使用するかを示す包括的な例です。

# Simple example presenting how persistent ID can be used to pickle
# external objects by reference.

import pickle
import sqlite3
from collections import namedtuple

# Simple class representing a record in our database.
MemoRecord = namedtuple("MemoRecord", "key, task")

class DBPickler(pickle.Pickler):

    def persistent_id(self, obj):
        # Instead of pickling MemoRecord as a regular class instance, we emit a
        # persistent ID.
        if isinstance(obj, MemoRecord):
            # Here, our persistent ID is simply a tuple, containing a tag and a
            # key, which refers to a specific record in the database.
            return ("MemoRecord", obj.key)
        else:
            # If obj does not have a persistent ID, return None. This means obj
            # needs to be pickled as usual.
            return None

class DBUnpickler(pickle.Unpickler):

    def __init__(self, file, connection):
        super().__init__(file)
        self.connection = connection

    def persistent_load(self, pid):
        # This method is invoked whenever a persistent ID is encountered.
        # Here, pid is the tuple returned by DBPickler.
        cursor = self.connection.cursor()
        type_tag, key_id = pid
        if type_tag == "MemoRecord":
            # Fetch the referenced record from the database and return it.
            cursor.execute("SELECT * FROM memos WHERE key=?", (str(key_id),))
            key, task = cursor.fetchone()
            return MemoRecord(key, task)
        else:
            # Always raises an error if you cannot return the correct object.
            # Otherwise, the unpickler will think None is the object referenced
            # by the persistent ID.
            raise pickle.UnpicklingError("unsupported persistent object")

def main():
    import io
    import pprint

    # Initialize and populate our database.
    conn = sqlite3.connect(":memory:")
    cursor = conn.cursor()
    cursor.execute("CREATE TABLE memos(key INTEGER PRIMARY KEY, task TEXT)")
    tasks = (
        'give food to fish',
        'prepare group meeting',
        'fight with a zebra',
        )
    for task in tasks:
        cursor.execute("INSERT INTO memos VALUES(NULL, ?)", (task,))

    # Fetch the records to be pickled.
    cursor.execute("SELECT * FROM memos")
    memos = [MemoRecord(key, task) for key, task in cursor]
    # Save the records using our custom DBPickler.
    file = io.BytesIO()
    DBPickler(file).dump(memos)

    print("Pickled records:")
    pprint.pprint(memos)

    # Update a record, just for good measure.
    cursor.execute("UPDATE memos SET task='learn italian' WHERE key=1")

    # Load the records from the pickle data stream.
    file.seek(0)
    memos = DBUnpickler(file, conn).load()

    print("Unpickled records:")
    pprint.pprint(memos)

if __name__ == '__main__':
    main()

ディスパッチテーブル

pickle 化に依存する他のコードの邪魔をせずに、一部のクラスの pickle 化だけをカスタマイズしたい場合、プライベートのディスパッチテーブルを持つ pickler を作成することができます。

copyreg モジュールによって管理されるグローバルなディスパッチテーブルは copyreg.dispatch_table として利用可能です。したがって、copyreg.dispatch_table の修正済のコピーをプライベートのディスパッチテーブルとして使用することを選択できます。

例えば

f = io.BytesIO()
p = pickle.Pickler(f)
p.dispatch_table = copyreg.dispatch_table.copy()
p.dispatch_table[SomeClass] = reduce_SomeClass

これは SomeClass クラスを特別に扱うプライベートのディスパッチテーブルを持つ pickle.Pickler のインスタンスを作成します。あるいは、次のコード

class MyPickler(pickle.Pickler):
    dispatch_table = copyreg.dispatch_table.copy()
    dispatch_table[SomeClass] = reduce_SomeClass
f = io.BytesIO()
p = MyPickler(f)

does the same but all instances of MyPickler will by default share the private dispatch table. On the other hand, the code

copyreg.pickle(SomeClass, reduce_SomeClass)
f = io.BytesIO()
p = pickle.Pickler(f)

modifies the global dispatch table shared by all users of the copyreg module.

状態を持つオブジェクトの扱い

Here's an example that shows how to modify pickling behavior for a class. The TextReader class below opens a text file, and returns the line number and line contents each time its readline() method is called. If a TextReader instance is pickled, all attributes except the file object member are saved. When the instance is unpickled, the file is reopened, and reading resumes from the last location. The __setstate__() and __getstate__() methods are used to implement this behavior.

class TextReader:
    """Print and number lines in a text file."""

    def __init__(self, filename):
        self.filename = filename
        self.file = open(filename)
        self.lineno = 0

    def readline(self):
        self.lineno += 1
        line = self.file.readline()
        if not line:
            return None
        if line.endswith('\n'):
            line = line[:-1]
        return "%i: %s" % (self.lineno, line)

    def __getstate__(self):
        # Copy the object's state from self.__dict__ which contains
        # all our instance attributes. Always use the dict.copy()
        # method to avoid modifying the original state.
        state = self.__dict__.copy()
        # Remove the unpicklable entries.
        del state['file']
        return state

    def __setstate__(self, state):
        # Restore instance attributes (i.e., filename and lineno).
        self.__dict__.update(state)
        # Restore the previously opened file's state. To do so, we need to
        # reopen it and read from it until the line count is restored.
        file = open(self.filename)
        for _ in range(self.lineno):
            file.readline()
        # Finally, save the file.
        self.file = file

使用例は以下のようになるでしょう:

>>> 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!'

型、関数、その他のオブジェクトに対するリダクションのカスタマイズ

Added in version 3.8.

dispatch_table は、ときにその柔軟性が十分でないがことあります。特に、オブジェクトの型以外の別の条件で pickle 化をカスタマイズしたい場合や、関数やクラスを使って pickle 化をカスタマイズしたい場合などです。

そのような場合、 Pickler クラスから派生したサブクラスで reducer_override() メソッドを実装することができます。このメソッドは任意のリダクション用タプルを返すことができます (__reduce__() を参照してください)。もしくは、従来の振る舞いにフォールバックするために NotImplemented を返すこともできます。

dispatch_table と reducer_override() の両方が定義されている場合、 reducer_override() メソッドが優先されます。

注釈

パフォーマンス上の理由により、次に挙げるオブジェクトに対しては reducer_override() が呼ばれないことがあります: None, True, False, および int, float, bytes, str, dict, set, frozenset, list, tuple の厳密なインスタンス。

以下は特定のクラスを pickle 化して再構成する単純な例です:

import io
import pickle

class MyClass:
    my_attribute = 1

class MyPickler(pickle.Pickler):
    def reducer_override(self, obj):
        """Custom reducer for MyClass."""
        if getattr(obj, "__name__", None) == "MyClass":
            return type, (obj.__name__, obj.__bases__,
                          {'my_attribute': obj.my_attribute})
        else:
            # For any other object, fallback to usual reduction
            return NotImplemented

f = io.BytesIO()
p = MyPickler(f)
p.dump(MyClass)

del MyClass

unpickled_class = pickle.loads(f.getvalue())

assert isinstance(unpickled_class, type)
assert unpickled_class.__name__ == "MyClass"
assert unpickled_class.my_attribute == 1

アウトオブバウンドバッファ

Added in version 3.8.

ある状況では、 pickle モジュールは大量のデータを転送するために使われます。 そのため、メモリのコピーを最小限に抑えてパフォーマンスとリソースの消費を良好な状態に保つことが重要になることがあります。 しかし、オブジェクトのグラフ的構造をシーケンシャルなバイトストリームに変換する pickle モジュールの通常の処理は、本質的に pickle ストリームへの、または pickle ストリームからのデータのコピーを伴います。

この制約は、生産者 provider (変換されるオブジェクトの型の実装) と消費者 consumer (通信システムの実装) が pickle プロトコル5以上で提供されるアウトオブバウンドのデータ転送機能をサポートしていれば回避できます。

生産者 API

pickle 化される大きなサイズのデータオブジェクトは、プロトコル5以上でサポートされた __reduce_ex__() メソッドを実装しなければなりません。このメソッドは大きなデータに対して (bytes オブジェクトなどの代わりに) PickleBuffer インスタンスを返します。

PickleBuffer オブジェクトは背後にあるバッファがアウトオブバウンドのデータ転送に適合していることを 知らせます 。これらのオブジェクトは pickle モジュールの通常の使い方との互換性を保っています。しかし、消費者側で pickle モジュールに対してそれらのバッファを自身で処理することを事前に知らせることもできます。

消費者 API

通信システムは、オブジェクトグラフを直列化するときに生成された PickleBuffer オブジェクトのカスタマイズされた処理を有効化することができます。

送信側は buffer_callback 引数を Pickler (または dump() や dumps() 関数) に渡す必要があります。この関数はオブジェクトグラフを pickle 化するときに生成されるそれぞれの PickleBuffer を引数として呼ばれます。 buffer_callback によって蓄積されたバッファは、それが保持するデータのコピーを pickle ストリームに送らず、軽量なマーカーが挿入されるだけです。

受信側は buffers 引数を Unpickler (または load() や loads() 関数) に渡す必要があります。これは buffer_callback に渡されたバッファのイテラブルです。このイテラブルは buffer_callback に渡されたのと同じ順番でバッファを返さなければなりません。これらのバッファは、pickle 化処理によって PickleBuffer オブジェクトを生成したオブジェクトの再構築処理で期待されるデータを提供します。

送信側と受信側の間で、通信システムはアウトオブバウンドバッファの独自の転送メカニズムを自由に実装することができます。見込みのある最適化としては、共有メモリの利用や、データタイプ依存のデータ圧縮などが考えられます。

使用例

以下は、アウトオブバウンドのバッファを使った pickle 処理に関与することができるサブクラス bytearray を実装したささいな例です:

class ZeroCopyByteArray(bytearray):

    def __reduce_ex__(self, protocol):
        if protocol >= 5:
            return type(self)._reconstruct, (PickleBuffer(self),), None
        else:
            # PickleBuffer is forbidden with pickle protocols <= 4.
            return type(self)._reconstruct, (bytearray(self),)

    @classmethod
    def _reconstruct(cls, obj):
        with memoryview(obj) as m:
            # Get a handle over the original buffer object
            obj = m.obj
            if type(obj) is cls:
                # Original buffer object is a ZeroCopyByteArray, return it
                # as-is.
                return obj
            else:
                return cls(obj)

再構成関数 (_reconstruct クラスメソッド) は、受け取ったバッファが持っているオブジェクトを、それが正しい型であれば、そのまま返します。これは、このおもちゃのような例において、ゼロコピーの挙動を模擬的に行う簡単な方法です。

消費者側では、これらのオブジェクトを通常の方法で pickle 化することができます。この場合非直列化処理は元のオブジェクトのコピーを返します:

b = ZeroCopyByteArray(b"abc")
data = pickle.dumps(b, protocol=5)
new_b = pickle.loads(data)
print(b == new_b)  # True
print(b is new_b)  # False: a copy was made

いっぽう直列化において buffer_callback を設定し、非直列化において蓄積されたバッファを渡した場合、コピーではなく元のオブジェクトを得ることができます:

b = ZeroCopyByteArray(b"abc")
buffers = []
data = pickle.dumps(b, protocol=5, buffer_callback=buffers.append)
new_b = pickle.loads(data, buffers=buffers)
print(b == new_b)  # True
print(b is new_b)  # True: no copy was made

この例では bytearray がそれ自身メモリを割り当てるという性質による制限があります: すなわち、他のオブジェクトのメモリを参照する bytearray を生成することはできません。しかし、 NumPy 配列のようなサードパーティのデータ型ではそのような制限はなく、異なるプロセス間または異なるシステム間で、ゼロコピー (または最小限のコピー) でのpickle 処理の利用が可能です。

参考

PEP 574 [https://peps.python.org/pep-0574/] -- Pickle プロトコルバージョン 5 による帯域外データ

グローバル変数を制限する

デフォルトで、非 pickle 化は pickle データ内で見つけたあらゆるクラスや関数をインポートします。多くのアプリケーションでは、この振る舞いは受け入れられません。なぜなら、それによって unpickler が任意のコードをインポートして実行することが可能になるからです。この手の巧妙に作られた pickle データストリームがロードされたときに何を行うかをちょっと考えてみてください:

>>> import pickle
>>> pickle.loads(b"cos\nsystem\n(S'echo hello world'\ntR.")
hello world
0

この例において、unpickler は os.system() 関数をインポートして、次に文字列の引数 "echo hello world" を適用しています。この例は無害ですが、システムを破壊する例を想像するのは難しくありません。

この理由のため、Unpickler.find_class() をカスタマイズすることで非 pickle 化で何を得るかを制御したくなるかもしれません。その名前が示唆するのと異なり、Unpickler.find_class() はグローバル (クラスや関数) が必要とした時にはいつでも呼びだされます。したがって、グローバルを完全に禁止することも安全なサブセットに制限することも可能です。

これは、一部の安全なクラスについてのみ builtins モジュールからロードすることを許可する unpickler の例です:

import builtins
import io
import pickle

safe_builtins = {
    'range',
    'complex',
    'set',
    'frozenset',
    'slice',
}

class RestrictedUnpickler(pickle.Unpickler):

    def find_class(self, module, name):
        # Only allow safe classes from builtins.
        if module == "builtins" and name in safe_builtins:
            return getattr(builtins, name)
        # Forbid everything else.
        raise pickle.UnpicklingError("global '%s.%s' is forbidden" %
                                     (module, name))

def restricted_loads(s):
    """Helper function analogous to pickle.loads()."""
    return RestrictedUnpickler(io.BytesIO(s)).load()

この unpickler が働く使用例は次のように意図されます:

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

この例が示すように、非 pickle 化を認めるものに注意しなければなりません。したがって、セキュリティが重要な場合は xmlrpc.client の marshal API や、サードパーティのソリューションのような別の選択肢を考慮した方がよいでしょう。

性能

pickle プロトコルの最近のバージョン (プロトコル 2 以降) は一部の一般的な機能と組み込みデータ型を効率的にバイナリにエンコードするよう考慮されています。また、pickle モジュールは C 言語で書かれた透過的オプティマイザーを持っています。

使用例

最も単純なコードでは、dump() および load() 関数を使用してください。

import pickle

# An arbitrary collection of objects supported by pickle.
data = {
    'a': [1, 2.0, 3+4j],
    'b': ("character string", b"byte string"),
    'c': {None, True, False}
}

with open('data.pickle', 'wb') as f:
    # Pickle the 'data' dictionary using the highest protocol available.
    pickle.dump(data, f, pickle.HIGHEST_PROTOCOL)

次の例は、pickle 化されたデータを読み込みます。

import pickle

with open('data.pickle', 'rb') as f:
    # The protocol version used is detected automatically, so we do not
    # have to specify it.
    data = pickle.load(f)

参考

copyreg モジュール

拡張型を登録するための Pickle インターフェース構成機構。

pickletools モジュール

pickle データの処理や分析を行うためのツール。

shelve モジュール

オブジェクトのインデクス付きデータベース; pickle を使います。

copy モジュール

オブジェクトの浅いコピーおよび深いコピー。

marshal モジュール

組み込み型の高性能な直列化。

脚注

[1]

marshal モジュールと間違えないように注意してください。

[2]

なぜ lambda 関数を pickle 化できないかというと、すべての lambda 関数は同じ名前: <lambda> を共有しているからです。

[3]

送出される例外は ImportError や AttributeError になるはずですが、他の例外も起こりえます。

[4]

copy モジュールは、浅いコピーと深いコピーの操作にこのプロトコルを使用します。

[5]

英数文字に関する制限は、プロトコル 0 では永続的な ID が改行文字によって区切られるという事実によります。そのため、永続的な ID に何らかの改行文字が含まれると、結果として生じる pickle 化されたデータは判読不能になります。

copyreg --- Register pickle support functions

ソースコード: Lib/copyreg.py [https://github.com/python/cpython/tree/3.12/Lib/copyreg.py]

copyreg モジュールは、特定のオブジェクトを pickle する際に使われる関数を定義する手段を提供します。 pickle モジュールと copy モジュールは、オブジェクトを pickle/コピーする場合にそれらの関数を使用します。このモジュールは、クラスでないオブジェクトコンストラクタに関する設定情報を提供します。そのようなコンストラクタは、ファクトリ関数か、クラスインスタンスかもしれません。

copyreg.constructor(object)

object を有効なコンストラクタであると宣言します。 object が呼び出し可能でなければ(したがってコンストラクタとして有効でなければ)、 TypeError を発生します。

copyreg.pickle(type, function, constructor_ob=None)

Declares that function should be used as a "reduction" function for objects of type type. function must return either a string or a tuple containing between two and six elements. See the dispatch_table for more details on the interface of function.

The constructor_ob parameter is a legacy feature and is now ignored, but if passed it must be a callable.

pickler オブジェクトまたは pickle.Pickler のサブクラスの dispatch_table 属性を、リダクション関数の宣言のために使うこともできるということは覚えておいてください。

使用例

下記の例は、pickle 関数を登録する方法と、それがどのように使用されるかを示そうとしています:

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

shelve --- Python object persistence

ソースコード: Lib/shelve.py [https://github.com/python/cpython/tree/3.12/Lib/shelve.py]

"シェルフ (shelf, 棚)" は辞書に似た永続性を持つオブジェクトです。 "dbm" データベースとの違いは、シェルフの値 (キーではありません！) は実質上どんな Python オブジェクトにも --- pickle モジュールが扱えるなら何でも --- できるということです。これにはほとんどのクラスインスタンス、再帰的なデータ型、沢山の共有されたサブオブジェクトを含むオブジェクトが含まれます。キーは通常の文字列です。

shelve.open(filename, flag='c', protocol=None, writeback=False)

永続的な辞書を開きます。指定された filename は、根底にあるデータベースの基本ファイル名となります。副作用として、 filename には拡張子がつけられる場合があり、ひとつ以上のファイルが生成される可能性もあります。デフォルトでは、根底にあるデータベースファイルは読み書き可能なように開かれます。オプションの flag パラメータは dbm.open() における flag パラメータと同様に解釈されます。

By default, pickles created with pickle.DEFAULT_PROTOCOL are used to serialize values. The version of the pickle protocol can be specified with the protocol parameter.

Python の意味論により、シェルフには永続的な辞書の可変エントリがいつ変更されたかを知る術がありません。デフォルトでは、変更されたオブジェクトはシェルフに代入されたとき だけ 書き込まれます (使用例 参照)。オプションの writeback パラメータが True に設定されている場合は、アクセスされたすべてのエントリはメモリ上にキャッシュされ、 sync() および close() を呼び出した際に書き戻されます; この機能は永続的な辞書上の可変の要素に対する変更を容易にしますが、多数のエントリがアクセスされた場合、膨大な量のメモリがキャッシュのために消費され、アクセスされた全てのエントリを書き戻す (アクセスされたエントリが可変であるか、あるいは実際に変更されたかを決定する方法は存在しないのです) ために、ファイルを閉じる操作が非常に低速になります。

バージョン 3.10 で変更: pickle.DEFAULT_PROTOCOL is now used as the default pickle protocol.

バージョン 3.11 で変更: Accepts path-like object for filename.

注釈

シェルフが自動的に閉じることに依存しないでください; それがもう必要ない場合は常に close() を明示的に呼ぶか、 shelve.open() をコンテキストマネージャとして使用してください:

with shelve.open('spam') as db:
    db['eggs'] = 'eggs'

警告

shelve モジュールは裏で pickle を使っているので、信頼できないソースからシェルフを読み込むのは危険です。 pickle と同じく、 shelf の読み込みでも任意のコードを実行できるからです。

Shelf objects support most of methods and operations supported by dictionaries (except copying, constructors and operators | and |=). This eases the transition from dictionary based scripts to those requiring persistent storage.

追加でサポートされるメソッドが二つあります:

Shelf.sync()

シェルフが writeback を True にセットして開かれている場合に、キャッシュ中の全てのエントリを書き戻します。また可能な場合は、キャッシュを空にしてディスク上の永続的な辞書を同期します。このメソッドはシェルフを close() によって閉じるとき自動的に呼び出されます。

Shelf.close()

永続的な 辞書 オブジェクトを同期して閉じます。既に閉じられているシェルフに対して呼び出すと ValueError を出し失敗します。

参考

Persistent dictionary recipe [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.

制限事項

どのデータベースパッケージが使われるか (例えば dbm.ndbm 、 dbm.gnu) は、どのインターフェースが利用可能かに依存します。従って、データベースを dbm を使って直接開く方法は安全ではありません。データベースはまた、 dbm が使われた場合 (不幸なことに) その制約に縛られます --- これはデータベースに記録されたオブジェクト (の pickle 化された表現) はかなり小さくなければならず、キー衝突が生じた場合に、稀にデータベースを更新することができなくなることを意味します。

shelve モジュールは、シェルフに置かれたオブジェクトの 並列した 読み出し/書き込みアクセスをサポートしません (複数の同時読み出しアクセスは安全です)。あるプログラムが書き込みのために開かれたシェルフを持っているとき、他のプログラムはそのシェルフを読み書きのために開いてはいけません。この問題を解決するために Unix のファイルロック機構を使うことができますが、この機構は Unix のバージョン間で異なり、使われているデータベースの実装について知識が必要となります。

On macOS dbm.ndbm can silently corrupt the database file on updates, which can cause hard crashes when trying to read from the database.

class shelve.Shelf(dict, protocol=None, writeback=False, keyencoding='utf-8')

collections.abc.MutableMapping のサブクラスで、 dict オブジェクト内にpickle化された値を保持します。

By default, pickles created with pickle.DEFAULT_PROTOCOL are used to serialize values. The version of the pickle protocol can be specified with the protocol parameter. See the pickle documentation for a discussion of the pickle protocols.

writeback パラメータが True に設定されていれば、アクセスされたすべてのエントリはメモリ上にキャッシュされ、ファイルを閉じる際に dict に書き戻されます; この機能により、可変のエントリに対して自然な操作が可能になりますが、さらに多くのメモリを消費し、辞書をファイルと同期して閉じる際に長い時間がかかるようになります。

keyencoding パラメータは、shelf の背後にある dict に対して使われる前にキーをエンコードするのに使用されるエンコーディングです。

Shelf オブジェクトは、コンテキストマネージャとしても使用できます。この場合、 with ブロックが終了する際に、自動的に閉じられます。

バージョン 3.2 で変更: keyencoding パラメータを追加; 以前はキーは常に UTF-8 でエンコードされていました。

バージョン 3.4 で変更: コンテキストマネージャーサポートが追加されました。

バージョン 3.10 で変更: pickle.DEFAULT_PROTOCOL is now used as the default pickle protocol.

class shelve.BsdDbShelf(dict, protocol=None, writeback=False, keyencoding='utf-8')

A subclass of Shelf which exposes first(), next(), previous(), last() and set_location() methods. These are available in the third-party bsddb module from pybsddb [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 bsddb.hashopen(), bsddb.btopen() or bsddb.rnopen(). The optional protocol, writeback, and keyencoding parameters have the same interpretation as for the Shelf class.

class shelve.DbfilenameShelf(filename, flag='c', protocol=None, writeback=False)

Shelf のサブクラスで、辞書に似たオブジェクトの代わりに filename を受理します。根底にあるファイルは dbm.open() を使って開かれます。デフォルトでは、ファイルは読み書き可能な状態で開かれます。オプションの flag パラメータは open() 関数におけるパラメータと同様に解釈されます。オプションの protocol および writeback パラメータは Shelf クラスにおけるパラメータと同様に解釈されます。

使用例

インターフェースは以下のコードに集約されています (key は文字列で、data は任意のオブジェクトです):

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

参考

dbm モジュール

dbm スタイルのデータベースに対する共通インターフェース。

pickle モジュール

shelve によって使われるオブジェクト整列化機構。

marshal --- Internal Python object serialization

このモジュールには Python 値をバイナリ形式で読み書きできるような関数が含まれています。このバイナリ形式は Python 特有のものですが、マシンアーキテクチャ非依存のものです (つまり、Python の値を PC 上でファイルに書き込み、Sun に転送し、そこで読み戻すことができます)。バイナリ形式の詳細は意図的にドキュメント化されていません; この形式は (稀にしかないことですが) Python のバージョン間で変更される可能性があるからです。[1]

This is not a general "persistence" module. For general persistence and transfer of Python objects through RPC calls, see the modules pickle and shelve. The marshal module exists mainly to support reading and writing the "pseudo-compiled" code for Python modules of .pyc files. Therefore, the Python maintainers reserve the right to modify the marshal format in backward incompatible ways should the need arise. If you're serializing and de-serializing Python objects, use the pickle module instead -- the performance is comparable, version independence is guaranteed, and pickle supports a substantially wider range of objects than marshal.

警告

marshal モジュールは、誤ったデータや悪意を持って作成されたデータに対する安全性を考慮していません。信頼できない、もしくは認証されていない出所からのデータを非整列化してはなりません。

Not all Python object types are supported; in general, only objects whose value is independent from a particular invocation of Python can be written and read by this module. The following types are supported: booleans, integers, floating point numbers, complex numbers, strings, bytes, bytearrays, tuples, lists, sets, frozensets, dictionaries, and code objects, where it should be understood that tuples, lists, sets, frozensets and dictionaries are only supported as long as the values contained therein are themselves supported. The singletons None, Ellipsis and StopIteration can also be marshalled and unmarshalled. For format version lower than 3, recursive lists, sets and dictionaries cannot be written (see below).

bytes-like オブジェクトを操作する関数と同様に、ファイルの読み書きを行う関数が提供されています。

このモジュールでは、以下の関数が定義されています。

marshal.dump(value, file[, version])

開かれたファイルに値を書き込みます。値はサポートされている型でなくてはなりません。file は書き込み可能な バイナリファイル である必要があります。

If the value has (or contains an object that has) an unsupported type, a ValueError exception is raised --- but garbage data will also be written to the file. The object will not be properly read back by load().

version 引数は dump が使用するデータフォーマットを指定します (下記を参照してください)。

引数 value, version を指定して 監査イベント marshal.dumps を送出します。

marshal.load(file)

Read one value from the open file and return it. If no valid value is read (e.g. because the data has a different Python version's incompatible marshal format), raise EOFError, ValueError or TypeError. The file must be a readable binary file.

引数無しで 監査イベント marshal.load を送出します。

注釈

サポートされていない型を含むオブジェクトが dump() で整列化されている場合、 load() は整列化不能な値を None で置き換えます。

バージョン 3.10 で変更: This call used to raise a code.__new__ audit event for each code object. Now it raises a single marshal.load event for the entire load operation.

marshal.dumps(value[, version])

Return the bytes object that would be written to a file by dump(value, file). The value must be a supported type. Raise a ValueError exception if value has (or contains an object that has) an unsupported type.

version 引数は dumps が使用するデータフォーマットを指定します (下記を参照してください)。

引数 value, version を指定して 監査イベント marshal.dumps を送出します。

marshal.loads(bytes)

Convert the bytes-like object to a value. If no valid value is found, raise EOFError, ValueError or TypeError. Extra bytes in the input are ignored.

引数 bytes を指定して 監査イベント marshal.loads を送出します。

バージョン 3.10 で変更: This call used to raise a code.__new__ audit event for each code object. Now it raises a single marshal.loads event for the entire load operation.

これに加えて、以下の定数が定義されています:

marshal.version

このモジュールが利用するバージョンを表します。バージョン0 は歴史的なフォーマットです。バージョン1 は文字列の再利用をします。バージョン2 は浮動小数点数にバイナリフォーマットを使用します。バージョン3 はオブジェクトのインスタンス化と再帰をサポートします。現在のバージョンは4です。

脚注

[1]

このモジュールの名前は (特に) Modula-3 の設計者の間で使われていた用語の一つに由来しています。彼らはデータを自己充足的な形式で輸送する操作に "整列化 (marshalling)" という用語を使いました。厳密に言えば、"整列させる (to marshal)" とは、あるデータを (例えば RPC バッファのように) 内部表現形式から外部表現形式に変換することを意味し、"非整列化 (unmarshalling)" とはその逆を意味します。

dbm --- Interfaces to Unix "databases"

ソースコード: Lib/dbm/__init__.py [https://github.com/python/cpython/tree/3.12/Lib/dbm/__init__.py]

dbm is a generic interface to variants of the DBM database --- dbm.gnu or dbm.ndbm. If none of these modules is installed, the slow-but-simple implementation in module dbm.dumb will be used. There is a third party interface [https://www.jcea.es/programacion/pybsddb.htm] to the Oracle Berkeley DB.

exception dbm.error

サポートされているモジュールそれぞれによって送出される可能性のある例外を含むタプル。これにはユニークな例外があり、最初の要素として同じく dbm.error という名前の例外が含まれます --- dbm.error が送出される場合、後者(訳注:タプルの dbm.error ではなく例外 dbm.error)が使用されます。

dbm.whichdb(filename)

This function attempts to guess which of the several simple database modules available --- dbm.gnu, dbm.ndbm or dbm.dumb --- should be used to open a given file.

Return one of the following values:

None if the file can't be opened because it's unreadable or doesn't exist

the empty string ('') if the file's format can't be guessed

a string containing the required module name, such as 'dbm.ndbm' or 'dbm.gnu'

バージョン 3.11 で変更: filename accepts a path-like object.

dbm.open(file, flag='r', mode=0o666)

Open a database and return the corresponding database object.

パラメータ:

file (path-like object) --

The database file to open.

If the database file already exists, the 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.

flag (str) --

'r' (default): Open existing database for reading only.

'w': Open existing database for reading and writing.

'c': Open database for reading and writing, creating it if it doesn't exist.

'n': Always create a new, empty database, open for reading and writing.

mode (int) -- The Unix file access mode of the file (default: octal 0o666), used only when the database has to be created.

バージョン 3.11 で変更: file accepts a path-like object.

The object returned by open() supports the same basic functionality as a dict; keys and their corresponding values can be stored, retrieved, and deleted, and the in operator and the keys() method are available, as well as get() and setdefault() methods.

Key and values are always stored as bytes. This means that when strings are used they are implicitly converted to the default encoding before being stored.

これらのオブジェクトは、 with 文での使用にも対応しています。with 文を使用した場合、終了時に自動的に閉じられます。

バージョン 3.2 で変更: get() and setdefault() methods are now available for all dbm backends.

バージョン 3.4 で変更: Added native support for the context management protocol to the objects returned by open().

バージョン 3.8 で変更: Deleting a key from a read-only database raises a database module specific exception instead of KeyError.

以下の例ではホスト名と対応するタイトルをいくつか記録し、データベースの内容を出力します:

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.

参考

shelve モジュール

非文字列データを記録する永続化モジュール。

個々のサブモジュールは以降の節で説明されます。

dbm.gnu --- GNU database manager

ソースコード: Lib/dbm/gnu.py [https://github.com/python/cpython/tree/3.12/Lib/dbm/gnu.py]

The dbm.gnu module provides an interface to the GDBM library, similar to the dbm.ndbm module, but with additional functionality like crash tolerance.

注釈

The file formats created by dbm.gnu and dbm.ndbm are incompatible and can not be used interchangeably.

exception dbm.gnu.error

I/O エラーのような dbm.gnu 特有のエラーで送出されます。誤ったキーの指定のように、一般的なマップ型のエラーに対しては KeyError が送出されます。

dbm.gnu.open(filename, flag='r', mode=0o666, /)

Open a GDBM database and return a gdbm object.

パラメータ:

filename (path-like object) -- The database file to open.

flag (str) --

'r' (default): Open existing database for reading only.

'w': Open existing database for reading and writing.

'c': Open database for reading and writing, creating it if it doesn't exist.

'n': Always create a new, empty database, open for reading and writing.

The following additional characters may be appended to control how the database is opened:

'f': Open the database in fast mode. Writes to the database will not be synchronized.

's': Synchronized mode. Changes to the database will be written immediately to the file.

'u': Do not lock database.

Not all flags are valid for all versions of GDBM. See the open_flags member for a list of supported flag characters.

mode (int) -- The Unix file access mode of the file (default: octal 0o666), used only when the database has to be created.

例外:

error -- If an invalid flag argument is passed.

バージョン 3.11 で変更: filename accepts a path-like object.

dbm.gnu.open_flags

A string of characters the flag parameter of open() supports.

gdbm objects behave similar to mappings, but items() and values() methods are not supported. The following methods are also provided:

gdbm.firstkey()

It's possible to loop over every key in the database using this method and the 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.

gdbm.nextkey(key)

データベースの順方向探索において、key よりも後に来るキーを返します。以下のコードはデータベース db について、キー全てを含むリストをメモリ上に生成することなく全てのキーを出力します:

k = db.firstkey()
while k is not None:
    print(k)
    k = db.nextkey(k)

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

gdbm.sync()

データベースが高速モードで開かれていた場合、このメソッドはディスクにまだ書き込まれていないデータを全て書き込ませます。

gdbm.close()

Close the GDBM database.

dbm.ndbm --- New Database Manager

ソースコード: Lib/dbm/ndbm.py [https://github.com/python/cpython/tree/3.12/Lib/dbm/ndbm.py]

The dbm.ndbm module provides an interface to the NDBM library. This module can be used with the "classic" NDBM interface or the GDBM compatibility interface.

注釈

The file formats created by dbm.gnu and dbm.ndbm are incompatible and can not be used interchangeably.

警告

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

exception dbm.ndbm.error

I/O エラーのような dbm.ndbm 特有のエラーで送出されます。誤ったキーの指定のように、一般的なマップ型のエラーに対しては KeyError が送出されます。

dbm.ndbm.library

Name of the NDBM implementation library used.

dbm.ndbm.open(filename, flag='r', mode=0o666, /)

Open an NDBM database and return an ndbm object.

パラメータ:

filename (path-like object) -- The basename of the database file (without the .dir or .pag extensions).

flag (str) --

'r' (default): Open existing database for reading only.

'w': Open existing database for reading and writing.

'c': Open database for reading and writing, creating it if it doesn't exist.

'n': Always create a new, empty database, open for reading and writing.

mode (int) -- The Unix file access mode of the file (default: octal 0o666), used only when the database has to be created.

ndbm objects behave similar to mappings, but items() and values() methods are not supported. The following methods are also provided:

バージョン 3.11 で変更: Accepts path-like object for filename.

ndbm.close()

Close the NDBM database.

dbm.dumb --- 可搬性のある DBM 実装

ソースコード: Lib/dbm/dumb.py [https://github.com/python/cpython/tree/3.12/Lib/dbm/dumb.py]

注釈

dbm.dumb モジュールは、 dbm が頑健なモジュールを他に見つけることができなかった際の最後の手段とされています。 dbm.dumb モジュールは速度を重視して書かれているわけではなく、他のデータベースモジュールのように重い使い方をするためのものではありません。

The dbm.dumb module provides a persistent dict-like interface which is written entirely in Python. Unlike other dbm backends, such as dbm.gnu, no external library is required.

The dbm.dumb module defines the following:

exception dbm.dumb.error

I/O エラーのような dbm.dumb 特有のエラーの際に送出されます。不正なキーを指定したときのような、一般的な対応付けエラーの際には KeyError が送出されます。

dbm.dumb.open(filename, flag='c', mode=0o666)

Open a dbm.dumb database. The returned database object behaves similar to a mapping, in addition to providing sync() and close() methods.

パラメータ:

filename --

The basename of the database file (without extensions). A new database creates the following files:

filename.dat

filename.dir

flag (str) --

'r': Open existing database for reading only.

'w': Open existing database for reading and writing.

'c' (default): Open database for reading and writing, creating it if it doesn't exist.

'n': Always create a new, empty database, open for reading and writing.

mode (int) -- The Unix file access mode of the file (default: octal 0o666), used only when the database has to be created.

警告

十分に大きかったり複雑だったりするエントリーのあるデータベースを読み込んでいるときに、 Python の抽象構文木コンパイラのスタックの深さの限界を越えるせいで、 Python インタプリタをクラッシュさせることができます。

バージョン 3.5 で変更: open() always creates a new database when flag is 'n'.

バージョン 3.8 で変更: A database opened read-only if flag is 'r'. A database is not created if it does not exist if flag is 'r' or 'w'.

バージョン 3.11 で変更: filename accepts a path-like object.

In addition to the methods provided by the collections.abc.MutableMapping class, the following methods are provided:

dumbdbm.sync()

ディスク上の辞書とデータファイルを同期します。このメソッドは Shelve.sync() メソッドから呼び出されます。

dumbdbm.close()

Close the database.

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

ソースコード: Lib/sqlite3/ [https://github.com/python/cpython/tree/3.12/Lib/sqlite3/]

SQLite は、軽量なディスク上のデータベースを提供する C ライブラリです。別のサーバプロセスを用意する必要なく、 SQL クエリー言語の非標準的な一種を使用してデータベースにアクセスできます。一部のアプリケーションは内部データ保存に SQLite を使えます。また、SQLite を使ってアプリケーションのプロトタイプを作り、その後そのコードを PostgreSQL や Oracle のような大規模データベースに移植するということも可能です。

The sqlite3 module was written by Gerhard Häring. It provides an SQL interface compliant with the DB-API 2.0 specification described by PEP 249 [https://peps.python.org/pep-0249/], and requires SQLite 3.7.15 or newer.

この文書には大きく分けて 4 つの節があります:

チュートリアル sqlite3 モジュールの使い方を学びます。

リファレンス このモジュールが定義するクラスと関数について説明します。

ハウツー・ガイド 特定のタスクの処理方法について詳しく説明します。

説明 トランザクション制御の背景をより深く掘り下げて説明します。

参考

https://www.sqlite.org

SQLite のウェブページ。ここの文書ではサポートされる SQL 方言の文法と使えるデータ型を説明しています。

https://www.w3schools.com/sql/

SQL 学習に効くチュートリアル、リファレンス、実例集。

PEP 249 [https://peps.python.org/pep-0249/] - Database API Specification 2.0

Marc-Andre Lemburg により書かれた PEP。

チュートリアル

このチュートリアルでは、あなたは基本的な sqlite3 機能を使用して、 例としてモンティ・パイソンの映画のデータベースを作成します。 あなたがカーソル(cursors [https://en.wikipedia.org/wiki/Cursor_(databases)])やトランザクション(transactions [https://en.wikipedia.org/wiki/Database_transaction])を含むデータベースの基本概念を理解していることを前提としています。

最初に、新しいデータベースを作成し、データベース接続(connection)を開いて sqlite3 が動作できるようにする必要があります。 sqlite3.connect() を呼び出して、データベース tutorial.db への接続を現在の作業ディレクトリに作成します。存在しない場合は暗黙的に作成します。

import sqlite3
con = sqlite3.connect("tutorial.db")

返された Connection オブジェクト con は、ディスク上のデータベースへの接続を表します。

SQL 文を実行し、SQL クエリから結果を取得するには、データベース・カーソルを使用する必要があります。 con.cursor() を呼び出して Cursor を作成してください:

cur = con.cursor()

さて、今やデータベース接続とカーソルを取得したので、タイトル(title)とリリース年(year)と、レビュー・スコア(score)の列(columns)を持つデータベース・テーブル movie を作成できます。 簡単にするために、テーブル宣言では列名だけを使用できます。SQLite の 柔軟な型付け(flexible typing [https://www.sqlite.org/flextypegood.html])機能のおかげで、データ型の指定はオプションになっています。 cur.execute(...) を呼び出して CREATE TABLE 文を実行してください:

cur.execute("CREATE TABLE movie(title, year, score)")

SQLite に組み込みの sqlite_master テーブルに対してクエリを実行することで、新しいテーブルが作成されたことを確認できます。このテーブルには、 movie テーブル定義のエントリが含まれているはずです(詳細は The Schema Table [https://www.sqlite.org/schematab.html] 参照)。 cur.execute(...) を呼び出してクエリを実行して、その結果を res に代入し、結果の行(row)を取得するために res.fetchone() を呼び出します:

>>> res = cur.execute("SELECT name FROM sqlite_master")
>>> res.fetchone()
('movie',)

クエリがテーブルの名前を含む タプル を返すので、テーブルが作成されたことがわかります。 存在しないテーブル spam に対して sqlite_master をクエリすると、 res.fetchone() は None を返します:

>>> res = cur.execute("SELECT name FROM sqlite_master WHERE name='spam'")
>>> res.fetchone() is None
True

ここで、 INSERT 文を実行して SQL のリテラルとして提供された 2 行のデータを追加し、 再度 cur.execute(...) を呼び出して追加します:

cur.execute("""
    INSERT INTO movie VALUES
        ('Monty Python and the Holy Grail', 1975, 8.2),
        ('And Now for Something Completely Different', 1971, 7.5)
""")

INSERT 文は、変更がデータベースに保存される前にコミットする必要がある、トランザクションを暗黙的に開きます(詳細は、 トランザクション制御 参照)。 トランザクションをコミットするために接続オブジェクト(connection object)の con.commit() を呼び出して下さい:

con.commit()

SELECT クエリを実行することで、データが正しく挿入されたことを確認できます。 結果のすべての行を返すには、おなじみの cur.execute(...) を使用して結果を res に代入し、 res.fetchall() を呼び出して下さい:

>>> res = cur.execute("SELECT score FROM movie")
>>> res.fetchall()
[(8.2,), (7.5,)]

結果は、2 つの タプル の リスト で、 それぞれのタプルにその行の score 値が含まれています。

ここで、 cur.executemany(...) を呼び出して、さらに 3 行挿入します:

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.

data をクエリに結び付け(bind)するために ? プレースホルダが使用されていることに注意してください。 SQL インジェクション攻撃(SQL injection attacks [https://en.wikipedia.org/wiki/SQL_injection])を避けるために、Python の値を SQL 文に結び付けするには、常に 文字列フォーマット の代わりにプレースホルダを使用してください(詳細は プレースホルダを使用して SQL クエリに値を結び付ける方法 参照)。

SELECT クエリを実行することで、新しい行が挿入されたことを確認できます。今回は、クエリの結果を反復処理します:

>>> 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")

各行(row)は タプル の (year, title) の 2 つの項目であり、クエリで選択された列(columns)にマッチします。

最後に、 con.close() を呼び出して既存の接続(connection)を閉じ、新しい接続を開き、新しいカーソルを作成してから、データベースに対してクエリを実行して、データベースがディスクに書き込まれたことを確認します:

>>> 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()

これで、あなたは、 sqlite3 モジュールを使用して SQLite データベースを作成し、複数の方法でデータを挿入し、そこから値を取得することができるようになりました。

参考

ハウツー・ガイド も参考にしてください:

プレースホルダを使用して SQL クエリに値を結び付ける方法

カスタム Python 型を SQLite 値に適合させる方法

SQLite 値をカスタム Python 型に変換する方法

接続(connection)コンテキストマネージャの使い方

行工場(row factories)の作成方法と使用方法

トランザクション制御 トランザクション制御の背景についてより深く掘り下げた説明。

リファレンス

モジュール関数

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)

SQLite データベースとの接続(connection)を開きます。

パラメータ:

database (path-like object) -- The path to the database file to be opened. You can pass ":memory:" to create an SQLite database existing only in memory [https://sqlite.org/inmemorydb.html], and open a connection to it.

timeout (float) -- テーブルがロックされている場合、 OperationalError を送出する前に接続を待機する秒数。 別の接続がテーブルを変更するためにトランザクションを開くと、そのテーブルはトランザクションがコミットされるまでロックされます。 デフォルトは 5 秒です。

detect_types (int) -- register_converter() で登録された変換関数を使用して、 SQLite でネイティブにサポートされている型 以外のデータ型を検出して、 Python 型に変換するかどうか、そして、その変換方法を制御します。 これは、 PARSE_DECLTYPES と PARSE_COLNAMES を(ビット論理和 | を使用して)任意の組み合わせで設定することで有効になります。 両方のフラグが設定されている場合、宣言された型よりも列名が優先されます。 detect_types パラメータが設定されている場合でも、 生成されたフィールド(たとえば max(data))の型は検出できず、代わりに str が返されます。デフォルト (0) では、データ型検出は無効になっています。

isolation_level (str | None) -- Control legacy transaction handling behaviour. See Connection.isolation_level and isolation_level 属性に依るトランザクション制御 for more information. Can be "DEFERRED" (default), "EXCLUSIVE" or "IMMEDIATE"; or None to disable opening transactions implicitly. Has no effect unless Connection.autocommit is set to LEGACY_TRANSACTION_CONTROL (the default).

check_same_thread (bool) -- True (これがデフォルトです)なら、データベース接続を作成したスレッド以外のスレッドがデータベース接続を使用すると、 ProgrammingError が送出されます。 False なら、接続は複数のスレッドからアクセスできます。ただし、データの破損を避けるために、ユーザーによる書き込み操作の直列化が必要になることがあります。詳細は threadsafety を参照してください。

factory (Connection) -- デフォルトの Connection クラスでない場合に接続(connection)を作成する Connection のカスタム・サブクラスです。

cached_statements (int) -- sqlite3 がこの接続(connection)のために内部的にキャッシュするSQL文(statements)の数で、 パース時のオーバーヘッドを回避します。 デフォルトでは、128 文(statements)です。

uri (bool) -- True に設定すると、 database は、ファイル・パス(path)とオプションのクエリ文字列を含む URI として解釈されます。 スキームの部分は "file:" でなければならず、パス(path)は相対パスまたは絶対パスにすることができます。 クエリ文字列により、 パラメーターを SQLite に渡すことができ、さまざまな SQLite URI の操作方法 が有効になります。

autocommit (bool) -- Control PEP 249 [https://peps.python.org/pep-0249/] transaction handling behaviour. See Connection.autocommit and autocommit 属性に依るトランザクション制御 for more information. autocommit currently defaults to LEGACY_TRANSACTION_CONTROL. The default will change to False in a future Python release.

戻り値の型:

Connection

引数 database を指定して 監査イベント sqlite3.connect を送出します。

引数 connection_handle を指定して 監査イベント sqlite3.connect/handle を送出します。

バージョン 3.4 で変更: uri パラメータが追加されました。

バージョン 3.7 で変更: database は、文字列だけでなく、 path-like object にすることもできるようになりました。

バージョン 3.10 で変更: Added the sqlite3.connect/handle auditing event.

バージョン 3.12 で変更: Added the autocommit parameter.

sqlite3.complete_statement(statement)

文字列 statement が 1 つ以上の完全な SQL 文を含んでいるように見える場合、 True を返します。 閉じられていない文字列リテラルがないことと、文がセミコロンで終了していることを確認する以外の、構文の検証やパースは行われません。

例えば:

>>> sqlite3.complete_statement("SELECT foo FROM bar;")
True
>>> sqlite3.complete_statement("SELECT foo")
False

この関数は、コマンドライン入力時に便利で、入力されたテキストが完全な SQL 文を形成しているように見えるかどうか、または execute() を呼び出す前に追加の入力が必要かどうかを判断するのに使えます。

実際の使用例については、 Lib/sqlite3/__main__.py [https://github.com/python/cpython/tree/3.12/Lib/sqlite3/__main__.py] の runsource() を参照してください。

sqlite3.enable_callback_tracebacks(flag, /)

コールバックのトレースバックを有効または無効にします。 デフォルトでは、ユーザー定義関数や集計関数や変換関数や authorizer コールバックなどではトレースバックを取得しません。それらをデバッグしたい場合は、 flag を True に設定してこの関数を呼び出し。その後、 sys.stderr のコールバックからトレースバックを取得します。 機能を再び無効にするには False を使用します。

注釈

Errors in user-defined function callbacks are logged as unraisable exceptions. Use an unraisable hook handler for introspection of the failed callback.

sqlite3.register_adapter(type, adapter, /)

adapter 呼び出し可能オブジェクト を登録して、 Python 型の type を SQLite の型に適合させます。適合関数(adapter)アダプターは、 Python 型 type の Python オブジェクトを唯一の引数として使用して呼び出され、 SQLite がネイティブに理解する型 の値を返す必要があります。

sqlite3.register_converter(typename, converter, /)

converter 呼び出し可能オブジェクト を登録して、 typename 型の SQLite オブジェクトを指定の型の Python オブジェクトに変換します。変換関数(converter)、 typename 型のすべての SQLite 値に対して呼び出されます。 変換関数には bytes オブジェクトが渡され、目的の Python 型のオブジェクトを返す必要があります。型検出の仕組みについては、 connect() のパラメーター detect_types を参照してください。

注釈: typename とクエリ内の型の名前は、大文字小文字を区別せずにマッチングされます。

モジュール定数

sqlite3.LEGACY_TRANSACTION_CONTROL

古いスタイル (Python 3.12 より前) のトランザクション制御の振る舞いを選択するには、 autocommit に、この定数を設定します。詳細については isolation_level 属性に依るトランザクション制御 を参照してください。

sqlite3.PARSE_COLNAMES

このフラグ値を connect() の detect_types パラメーターに渡し、クエリの列(column)名からパースされた型名を変換関数辞書(converter dictionary)のキーとして使用して変換関数を探します。型名は角括弧([])で囲む必要があります。

SELECT p as "p [point]" FROM test;  ! will look up converter "point"

このフラグは | (ビット論理和)演算子を使用して PARSE_DECLTYPES と組み合わせることができます。

sqlite3.PARSE_DECLTYPES

このフラグ値を connect() の detect_types パラメーターに渡して、各列(column)で宣言した型を使用して変換関数を探します。型は、データベース・テーブルの作成時に宣言します。 sqlite3 は、宣言された型の、最初の単語を、変換関数辞書(converter dictionary)のキーとして使用して、変換関数を探します。例えば:

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"
 )

このフラグは | (ビット論理和)演算子を使用して PARSE_COLNAMES と組み合わせることができます。

sqlite3.SQLITE_OK

sqlite3.SQLITE_DENY

sqlite3.SQLITE_IGNORE

Connection.set_authorizer() に渡す 呼び出し可能オブジェクト が返す必要のあるフラグ。これらは以下の意味です:

アクセスは許可されました(SQLITE_OK)

当該SQL文全体の実行をエラーで中止(abort)する必要があります(SQLITE_DENY)

列(column)は NULL 値として扱う必要がありますが、当該SQL文の実行は続行する必要があります(SQLITE_IGNORE)

sqlite3.apilevel

サポートされている DB-API レベルを示す文字列定数。 DB-API で必要です。 "2.0" とハードコーディングされています。

sqlite3.paramstyle

sqlite3 モジュールが期待するパラメータ・マーカーのフォーマットの種類をあらわす文字列定数です。 DB-API で必要です。 "qmark" とハードコーディングされています。

注釈

named DB-API パラメータ・スタイルもサポートされています。

sqlite3.sqlite_version

文字列 としての、ランタイム SQLite ライブラリのバージョン番号。

sqlite3.sqlite_version_info

整数 の タプル としての、ランタイム SQLite ライブラリのバージョン番号。

sqlite3.threadsafety

sqlite3 モジュールがサポートするスレッドセーフのレベルを示す、DB-API 2.0 で必要な整数定数。 この属性は、背後の SQLite ライブラリのコンパイル時のデフォルトの SQLite スレッド・モード (threading mode [https://sqlite.org/threadsafe.html])に基づいて設定されます。 SQLite のスレッド・モードは以下のとおりです:

シングル・スレッド: このモードでは、すべてのミューテックスが無効になり、一度に複数のスレッドで SQLite を使用するのは安全ではありません。

マルチ・スレッド: このモードでは、 1 つのデータベース接続が 2 つ以上のスレッドで同時に使用されない限り、複数のスレッドで SQLite を安全に使用できます。

直列化: 直列化(serialized)モードでは、 SQLite を複数のスレッドで制限なく安全に使用できます。

SQLite スレッド・モードと、 DB-API 2.0 のスレッドセーフ・レベルとの対応は以下のとおりです:

SQLite スレッド・モード

スレッドセーフ・レベル(threadsafety [https://peps.python.org/pep-0249/#threadsafety])

SQLITE_THREADSAFE [https://sqlite.org/compile.html#threadsafe]

DB-API 2.0 での意味

シングル・スレッド

0

0

スレッドはモジュールを共有できません

マルチ・スレッド

1

2

スレッドはモジュールを共有できますが、接続は共有できません

直列化

3

1

スレッドは、モジュールや接続やカーソルを共有できます

バージョン 3.11 で変更: 1 とハード・コーディングする代わりに threadsafety を動的に設定します。

sqlite3.version

文字列 としての、このモジュールのバージョン番号。これは SQLite ライブラリのバージョン番号ではありません。

バージョン 3.12 で非推奨、バージョン 3.14 で削除予定: この定数は、 sqlite3 へのアップストリーム変更に使用されていたサードパーティ・ライブラリである、 pysqlite パッケージのバージョン番号を反映していました。今やこれには何の意味も無いし実用的な価値もありません。

sqlite3.version_info

整数 の タプル としての、このモジュールのバージョン番号。これは SQLite ライブラリのバージョン番号ではありません。

バージョン 3.12 で非推奨、バージョン 3.14 で削除予定: この定数は、 sqlite3 へのアップストリーム変更に使用されていたサードパーティ・ライブラリである、 pysqlite パッケージのバージョン番号を反映していました。今やこれには何の意味も無いし実用的な価値もありません。

sqlite3.SQLITE_DBCONFIG_DEFENSIVE

sqlite3.SQLITE_DBCONFIG_DQS_DDL

sqlite3.SQLITE_DBCONFIG_DQS_DML

sqlite3.SQLITE_DBCONFIG_ENABLE_FKEY

sqlite3.SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER

sqlite3.SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION

sqlite3.SQLITE_DBCONFIG_ENABLE_QPSG

sqlite3.SQLITE_DBCONFIG_ENABLE_TRIGGER

sqlite3.SQLITE_DBCONFIG_ENABLE_VIEW

sqlite3.SQLITE_DBCONFIG_LEGACY_ALTER_TABLE

sqlite3.SQLITE_DBCONFIG_LEGACY_FILE_FORMAT

sqlite3.SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE

sqlite3.SQLITE_DBCONFIG_RESET_DATABASE

sqlite3.SQLITE_DBCONFIG_TRIGGER_EQP

sqlite3.SQLITE_DBCONFIG_TRUSTED_SCHEMA

sqlite3.SQLITE_DBCONFIG_WRITABLE_SCHEMA

これらの定数は、 Connection.setconfig() メソッド や getconfig() メソッドで使用されます。

これらの定数が利用できるかどうかは、 Python にコンパイルされた SQLite のバージョンによって異なります。

Added in version 3.12.

参考

https://www.sqlite.org/c3ref/c_dbconfig_defensive.html

SQLite docs: Database Connection Configuration Options

Connection オブジェクト

class sqlite3.Connection

開いた SQLite データベースの各々は、 sqlite3.connect() を使用して作成される Connection オブジェクトによって表されます。Connection オブジェクトの主な目的は Cursor オブジェクトの作成と トランザクション制御 です。

参考

接続(connection)ショートカット・メソッドの使い方

接続(connection)コンテキストマネージャの使い方

SQLite データベース接続(connection)には、以下の属性とメソッドがあります:

cursor(factory=Cursor)

Cursor オブジェクトを作成して返します。 cursor メソッドは、単一のオプション・パラメーター factory を受け入れます。 factory を指定する場合、これは Cursor またはそのサブクラスのインスタンスを返す 呼び出し可能オブジェクト である必要があります。

blobopen(table, column, row, /, *, readonly=False, name='main')

既存の BLOB への Blob ハンドルを開きます。

パラメータ:

table (str) -- 当該 BLOB が配置されているテーブルの名前。

column (str) -- 当該 BLOB が配置されている列(column)の名前。

row (str) -- 当該 BLOB が配置されている行(row)の名前。

readonly (bool) -- 書き込み権限なしで BLOB を開く必要がある場合は、 True に設定します。 デフォルトは False です。

name (str) -- 当該 BLOB が配置されているデータベース名。 デフォルトは "main" です。

例外:

OperationalError -- WITHOUT ROWID テーブルで BLOB を開こうとしたとき。

戻り値の型:

Blob

注釈

Blob クラスを使用して BLOB のサイズを変更することはできません。 SQL 関数 zeroblob を使用すると、固定サイズのブロブを作成します。

Added in version 3.11.

commit()

保留中のトランザクションをデータベースにコミットします。 autocommit が True または開いているトランザクションがない場合、このメソッドは何も行いません。 autocommit が False の場合に保留中のトランザクションがこのメソッドによってコミットされた場合、新しいトランザクションが暗黙に開かれます。

rollback()

保留中のトランザクションの先頭にロールバックします。 autocommit が True または開いているトランザクションがない場合、このメソッドは何も行いません。 autocommit が False の場合に保留中のトランザクションがこのメソッドによってロールバックされた場合、新しいトランザクションが暗黙に開かれます。

close()

データベース接続を閉じます。 autocommit が False の場合、保留中のトランザクションは暗黙にロールバックされます。 autocommit が True または LEGACY_TRANSACTION_CONTROL の場合、暗黙のトランザクション制御は実行されませんので、保留中の変更が失われないように、データベース接続を閉じる前に必ず commit() を行ってください。

execute(sql, parameters=(), /)

新しい Cursor オブジェクトを作成し、指定の sql と parameters で execute() を呼び出します。新しいカーソル・オブジェクトを返します。

executemany(sql, parameters, /)

新しい Cursor オブジェクトを作成し、与えられた sql と parameters で executemany() を呼び出します。新しいカーソル・オブジェクトを返します。

executescript(sql_script, /)

新しい Cursor オブジェクトを作成し、指定された sql_script で executescript() を呼び出します。新しいカーソル・オブジェクトを返します。

create_function(name, narg, func, *, deterministic=False)

ユーザ定義 SQL 関数を作成または削除します。

パラメータ:

name (str) -- SQL 関数の名前。

narg (int) -- SQL 関数が受け入れることができる引数の数。 -1 を指定すると、任意の数の引数を取ることができます。

func (callback | None) -- この SQL 関数が呼び出されたときに起動される 呼び出し可能オブジェクト 。 この呼び出し可能オブジェクトは、 SQLite によってネイティブにサポートされる型 を返すす必要があります。 既存の SQL 関数を削除するには、 None に設定します。

deterministic (bool) -- True の場合、作成された SQL 関数は決定論的(deterministic [https://sqlite.org/deterministic.html] : 入力が同一なら常に同一の答えを返す)としてマークされ、SQLite が追加の最適化を実行できるようになります。

例外:

NotSupportedError -- If deterministic is used with SQLite versions older than 3.8.3.

バージョン 3.8 で変更: Added the deterministic parameter.

例:

>>> 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()

create_aggregate(name, n_arg, aggregate_class)

ユーザ定義集計関数を作成または削除します。

パラメータ:

name (str) -- SQL 集計関数の名前。

n_arg (int) -- SQL 集計関数が受け入れることができる引数の数。 -1 を指定すると、任意の数の引数を取ることができます。

aggregate_class (class | None) --

クラスは以下のメソッドを実装する必要があります:

step(): 集計に行(row)を足し込みます。

finalize(): 集計の最終結果を SQLite でネイティブにサポートされている型 として返します。

step() メソッドが受け入れなければならない引数の数は n_arg によって制御されます。

既存の SQL 集計関数を削除するには、 None に設定します。

例:

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()

create_window_function(name, num_params, aggregate_class, /)

ユーザー定義の集計ウインドウ関数を作成または削除します。

パラメータ:

name (str) -- 作成または削除する SQL 集計ウインドウ関数の名前。

num_params (int) -- SQL 集計ウィンドウ関数が受け入れることができる引数の数。 -1 を指定した場合、任意の数の引数を取ることができます。

aggregate_class (class | None) --

クラスは以下のメソッドを実装する必要があります:

step(): 現在のウィンドウに行を足し込みます。

value(): 集計の現在の値を返します。

inverse(): 現在のウインドウから指定の行(row)の分を削除します。

finalize(): 集計の最終結果を SQLite でネイティブにサポートされている型 として返します。

step() メソッドと value() メソッドが受け入れなければならない引数の数は num_params によって制御されます。

None に設定すると、既存の SQL 集計ウィンドウ関数が削除されます。

例外:

NotSupportedError -- 集計ウィンドウ関数をサポートしていない 3.25.0 より古いバージョンの SQLite で使用した場合に送出されます。

Added in version 3.11.

例:

# 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()

create_collation(name, callable, /)

照合関数(collating function) callable を使用して name という名前の照合(collation)を作成します。 callable には 2 つの 文字列 引数が渡され、整数 を返す必要があります:

1 番目の文字列が 2 番目の文字列よりも高い順位ならば 1 を返す

1 番目の文字列が 2 番目の文字列よりも低い順位ならば -1 を返す

1 番目の文字列と 2 番目の文字列が同じ順位ならば 0 を返す

以下は逆順での照合例です:

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()

照合関数を削除するには callable を None に設定します。

バージョン 3.11 で変更: 照合の名前には任意のユニコード文字を含めることができます。 以前は ASCII 文字のみが許可されていました。

interrupt()

このメソッドを別のスレッドから呼び出して、この接続(connection)で、実行中のすべてのクエリを中止(abort)させます。 中止(abort)させられたクエリは OperationalError を送出します。

set_authorizer(authorizer_callback)

データベース内のテーブルの列(column)にアクセスしようとするたびに起動される 呼び出し可能オブジェクト authorizer_callback を登録します。 このコールバックは背後の SQLite ライブラリによって列(column)へのアクセスがどのように処理されるかを通知するために、 SQLITE_OK または SQLITE_DENY または SQLITE_IGNORE のいずれかを返さなければなりません。

コールバックの最初の引数は、承認(authorize)される操作の種類を示します。 2 番目と 3 番目の引数は、最初の引数に応じて、引数または None になります。 4 番目の引数は、該当する場合、データベースの名前("main" や "temp" 等)です。 5 番目の引数は、 アクセス試行を担当する最も内側のトリガーまたはビューの名前です。このアクセス試行が入力 SQL コードから直接行われた場合は None です。

最初の引数に指定可能な値と、 最初の引数に応じた 2 番目と 3 番目の引数の意味については、 SQLite のドキュメントを参照してください。 必要なすべての定数は sqlite3 モジュールで利用できます。

authorizer_callback として None を渡すと、承認機構(authorizer)が無効になります。

バージョン 3.11 で変更: None を使用して承認機構(authorizer)を無効にするサポートが追加されました。

set_progress_handler(progress_handler, n)

SQLite 仮想マシンの命令を n 個実行するごとに呼び出されるように、 呼び出し可能オブジェクト progress_handler を登録します。これは、 GUI の更新など、長時間実行される操作中に SQLite から呼び出されるようにしたい場合に便利です。

以前にインストールした progress ハンドラーをクリアしたい場合は、 progress_handler に None を指定してメソッドを呼び出します。

ハンドラー関数からゼロ以外の値を返すと、現在実行中のクエリを終了(terminate)し、 DatabaseError 例外を送出します。

set_trace_callback(trace_callback)

SQLite バックエンドによって実際に実行される SQL 文ごとに起動される 呼び出し可能オブジェクト trace_callback を登録します。

コールバックに渡される唯一の引数は、(str として渡される)実行中のSQL文です。 コールバックの戻り値は無視されます。 バックエンドは、 Cursor.execute() メソッドに渡されたSQL文を実行するだけではないことに注意してください。 sqlite3 モジュールの トランザクション管理 や、現在のデータベース内で定義されたトリガーの実行その他も行います。

trace_callback として None を渡すと、トレース・コールバックが無効になります。

注釈

トレース・コールバックで送出した例外は伝播されません。 開発およびデバッグの補助として、 enable_callback_tracebacks() を使用して、トレース・コールバックで送出した例外からのトレースバックの出力を有効にします。

Added in version 3.3.

enable_load_extension(enabled, /)

enabled が True の場合、 SQLite エンジンが共有ライブラリから SQLite 拡張機能をロードできるようにします。 True 以外の場合は、 SQLite 拡張機能の読み込みを許可しません。 SQLite 拡張機能では、新しい関数の定義、または集計の定義、またはまったく新しい仮想テーブルの実装を定義できます。 よく知られている拡張機能の 1 つは、SQLite と共に配布される全文検索拡張機能です。

注釈

sqlite3 モジュールは、デフォルトではロード可能な拡張機能をサポートするようにビルドされていません。一部のプラットフォーム(特に macOS)には、この機能なしでコンパイルされた SQLite ライブラリがあるためです。 ロード可能な拡張機能のサポートを得るには、 configure に --enable-loadable-sqlite-extensions オプションを渡す必要があります。

引数 connection, enabled を指定して 監査イベント sqlite3.enable_load_extension を送出します。

Added in version 3.2.

バージョン 3.10 で変更: sqlite3.enable_load_extension 監査イベントを追加しました。

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)

load_extension(path, /, *, entrypoint=None)

共有ライブラリから SQLite 拡張機能(extension)をロードします。このメソッドを呼び出す前に enable_load_extension() で拡張機能の読み込みを有効にしてください。

パラメータ:

path (str) -- SQLite 拡張機能(extension)へのパス(path)。

entrypoint (str | None) -- エントリ・ポイント名。 None (デフォルト) の場合、 SQLite は自分自身でエントリ・ポイント名を推測します。 詳細については、SQLite ドキュメント Loading an Extension [https://www.sqlite.org/loadext.html#loading_an_extension] を参照してください。

引数 connection, path を指定して 監査イベント sqlite3.load_extension を送出します。

Added in version 3.2.

バージョン 3.10 で変更: sqlite3.load_extension 監査イベントを追加しました。

バージョン 3.12 で変更: Added the entrypoint parameter.

iterdump()

データベースを SQL ソース・コードとしてダンプする iterator を返します。 後で復元するためにメモリ内データベースを保存する場合に便利です。 sqlite3 シェルの .dump コマンドに似ています。

例:

# 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()

参考

How to handle non-UTF-8 text encodings

backup(target, *, pages=-1, progress=None, name='main', sleep=0.250)

SQLite データベースのバックアップを作成します。

データベースが他のクライアントによってアクセスされている場合、または同一の接続によって並行にアクセスされている場合でも機能します。

パラメータ:

target (Connection) -- バックアップ先のデータベース接続(connection)。

pages (int) -- 一度にコピーするページ数。 0 以下の場合、データベース全体がワンステップでコピーされます。 デフォルトは -1 です。

progress (callback | None) -- 呼び出し可能オブジェクト <callable>`を設定すると、バックアップの指定ページ数単位の反復ごとに 3 つの整数引数で呼び出されます。 *status* は、最後の反復時のステータスで、 *remaining* はまだコピーされていない残りのページ数で、 *total* はコピーされるページの合計です。 デフォルトは ``None` です。

name (str) -- バックアップするデータベース名。 "main" (メイン・データベース。これがデフォルトです)、または "temp" (一時データベース)、 または ATTACH DATABASE SQL文を使用して取り付けられたカスタム・データベース名の、いずれかです。

sleep (float) -- バックアップの指定ページ数単位の反復ごとにスリープする秒数。

例 1. 既存のデータベースを別のデータベースにコピーします:

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()

例 2. 既存のデータベースを臨時コピー(transient copy)にコピーします。

src = sqlite3.connect('example.db')
dst = sqlite3.connect(':memory:')
src.backup(dst)
dst.close()
src.close()

Added in version 3.7.

参考

How to handle non-UTF-8 text encodings

getlimit(category, /)

接続(connection)の実行時制限を取得します。

パラメータ:

category (int) -- 問い合わせを行う実行時制限カテゴリー(SQLite limit category [https://www.sqlite.org/c3ref/c_limit_attached.html])。

戻り値の型:

int

例外:

ProgrammingError -- category に、 背後の SQLite ライブラリが認識できないカテゴリーを指定した場合に送出されます。

例: Connection の con の SQL 文の最大長を照会します (デフォルトは 1000000000 です):

>>> con.getlimit(sqlite3.SQLITE_LIMIT_SQL_LENGTH)
1000000000

Added in version 3.11.

setlimit(category, limit, /)

接続の実行時制限を設定します。 コンパイル時上限を超えて制限を増やそうとすると、 暗黙のうちにコンパイル時上限に切り捨てられます。 制限が変更されたかどうかに関係なく、 制限の以前の値が返されます。

パラメータ:

category (int) -- SQLite limit category [https://www.sqlite.org/c3ref/c_limit_attached.html] を設定する。

limit (int) -- 新しい制限の値。 負数の場合、 現在の制限は変更されません。

戻り値の型:

int

例外:

ProgrammingError -- category に、 背後の SQLite ライブラリが認識できないカテゴリーを指定した場合に送出されます。

class:Connection の con に対して、取り付けられるデータベース(attached databases)の数を 1 に制限します (デフォルトの制限は 10 です):

>>> con.setlimit(sqlite3.SQLITE_LIMIT_ATTACHED, 1)
10
>>> con.getlimit(sqlite3.SQLITE_LIMIT_ATTACHED)
1

Added in version 3.11.

getconfig(op, /)

ブール値の接続構成オプションを問い合わせます。

パラメータ:

op (int) -- SQLITE_DBCONFIG code を指定します。

戻り値の型:

bool

Added in version 3.12.

setconfig(op, enable=True, /)

ブール値の接続構成オプションを設定します。

パラメータ:

op (int) -- SQLITE_DBCONFIG code を指定します。

enable (bool) -- 設定オプションを有効にする必要がある場合は True (デフォルト)。 無効にする場合は False を指定します。

Added in version 3.12.

serialize(*, name='main')

データベースを bytes オブジェクトに直列化(serialize)します。 通常のディスク上のデータベース・ファイルの場合、 直列化はディスク・ファイルの単なるコピーです。 インメモリ・データベースまたは "temp" データベースの場合、 直列化は、 そのデータベースがディスクにバックアップされた場合にディスクに書き込まれるバイト・シーケンスと同じです。

パラメータ:

name (str) -- 直列化するデータベース名。 デフォルトは "main" です。

戻り値の型:

bytes

注釈

このメソッドは、 背後の SQLite ライブラリに直列化 API がある場合にのみ使用できます。

Added in version 3.11.

deserialize(data, /, *, name='main')

直列化 されたデータベースを Connection に、 脱直列化(deserialize)します。 このメソッドにより、 データベース接続はデータベース name から切断され、そして、 data に含まれる直列化データに基づいて、 データベース name がインメモリ・データベースとして再度開かれます。

パラメータ:

data (bytes) -- 直列化されたデータベース。

name (str) -- 脱直列化(deserialize)したデータを入れるデータベース名。 デフォルトは "main" です。

例外:

OperationalError -- データベース接続が読み取りトランザクションやバックアップ操作中の場合。

DatabaseError -- data に有効な SQLite データベースが含まれていない場合。

OverflowError -- len(data) が 2**63 - 1 より大きい場合。

注釈

このメソッドは、 背後の SQLite ライブラリに脱直列化 API がある場合にのみ使用できます。

Added in version 3.11.

autocommit

この属性は、 PEP 249 [https://peps.python.org/pep-0249/] 対応のトランザクションの振る舞いを制御します。 auto​​commit には以下の 3 つの値が指定できます:

False: PEP 249 [https://peps.python.org/pep-0249/] 対応のトランザクションの振る舞いを選びます。 これは、 sqlite3 が、 トランザクションが常に開いていることを保証することを意味します。トランザクションを閉じるには、 commit() や rollback() を使用します。

これが auto​​commit の推奨値です。

True: SQLite の autocommit mode [https://www.sqlite.org/lang_transaction.html#implicit_versus_explicit_transactions] を使用します。このモードでは commit() や rollback() は効果がありません。

LEGACY_TRANSACTION_CONTROL: Python 3.12 より前(PEP 249 [https://peps.python.org/pep-0249/] 非対応)のトランザクション制御。 詳細については isolation_level を参照してください。

これが、今のところは、 auto​​commit のデフォルト値です。

auto​​commit を False に変更すると新しいトランザクションが開き、 True に変更すると保留中のトランザクションがコミットされます。

詳細は autocommit 属性に依るトランザクション制御 を参照してください。

注釈

isolation_level 属性は、 autocommit の値が LEGACY_TRANSACTION_CONTROL でない限り、効果がありません。

Added in version 3.12.

in_transaction

この読み取り専用属性は、低レベルの SQLite autocommit mode [https://www.sqlite.org/lang_transaction.html#implicit_versus_explicit_transactions] に対応します。

トランザクションがアクティブな場合 (コミットされていない変更がある場合) は True 、それ以外の場合は False です。

Added in version 3.2.

isolation_level

sqlite3 の 旧来のトランザクション処理モード を制御します。 None に設定すると、トランザクションは暗黙に開かれることはありません。背後の SQLite の SQLite transaction behaviour [https://www.sqlite.org/lang_transaction.html#deferred_immediate_and_exclusive_transactions] に対応する "DEFERRED" または "IMMEDIATE" または "EXCLUSIVE" のいずれかに設定すると、 暗黙のトランザクション管理 が実行されます。

connect() の isolation_level パラメーターでオーバーライドされない場合、 デフォルトは "" で、 これは "DEFERRED" の別名です。

注釈

トランザクション処理を制御するには、 isolation_level を使用するよりも autocommit を使用することをお勧めします。 autocommit が LEGACY_TRANSACTION_CONTROL (これがデフォルトです)に設定されていない限り、 isolation_level は効果がありません。

row_factory

この接続から作成された Cursor オブジェクトの初期 row_factory 。この属性に割り当てを行っても、 この接続に属する、すでに存在するカーソルの row_factory には影響せず、 この属性に割り当てを行った後に作成する新しいカーソルのみに影響します。 デフォルトでは None です。つまり、各行は タプル として返されます。

詳細は 行工場(row factories)の作成方法と使用方法 をご覧下さい。

text_factory

A callable that accepts a bytes parameter and returns a text representation of it. The callable is invoked for SQLite values with the TEXT data type. By default, this attribute is set to str.

See How to handle non-UTF-8 text encodings for more details.

total_changes

データベース接続が開かれてから、変更または挿入または削除されたデータベース行の総数を返します。

Cursor オブジェクト

Cursor オブジェクトは、 SQL 文を実行し、 取得操作(fetch operation)のコンテキストを管理するために使用されるデータベース・カーソル(database cursor [https://en.wikipedia.org/wiki/Cursor_(databases)])を表します。カーソルは、 Connection.cursor() または 接続(connection)ショートカット・メソッド の、いずれかを使用して作成されます。

カーソル・オブジェクトは イテレータ です。つまり、 SELECT クエリに対して execute() した場合、結果の行(rows)を取得するためには、カーソルを単純に反復(iterate)できます:

for row in cur.execute("SELECT t FROM data"):
    print(row)

class sqlite3.Cursor

Cursor インスタンスは以下の属性やメソッドを持ちます。

execute(sql, parameters=(), /)

Execute a single SQL statement, optionally binding Python values using placeholders.

パラメータ:

sql (str) -- 単一の SQL 文。

parameters (dict | sequence) -- sql のプレースホルダに結び付け(bind)する Python 値。 名前付きプレースホルダが使用されている場合は dict です。 名前のないプレースホルダが使用されている場合は sequence です。 プレースホルダを使用して SQL クエリに値を結び付ける方法 を参照してください。

例外:

ProgrammingError -- sql に複数の SQL 文が含まれている場合。

autocommit が LEGACY_TRANSACTION_CONTROL で、かつ、 isolation_level が None で無く、 かつ、 sql が INSERT または UPDATE または DELETE または REPLACE 文で、かつ、開いているトランザクションがない場合、 sql を実行する前にトランザクションが暗黙に開かれます。

バージョン 3.12 で非推奨、バージョン 3.14 で削除予定: 名前付きプレースホルダー が使用され、かつ、パラメーターが dict ではなくシーケンスである場合、 DeprecationWarning を送出します。 Python 3.14 以降では、代わりに ProgrammingError を送出します。

複数の SQL 文を実行するには executescript() を使用します。

executemany(sql, parameters, /)

parameters のすべての item に対して、 パラメーター化 された DML SQL 文である sql を繰り返し実行します。

execute() と同一の暗黙のトランザクション処理を使用します。

パラメータ:

sql (str) -- 単一の DML 文。

parameters (iterable) -- sql のプレースホルダに結び付け(bind)するためのパラメータの iterable 。 プレースホルダを使用して SQL クエリに値を結び付ける方法 参照。

例外:

ProgrammingError -- If sql contains more than one SQL statement, or is not a DML statement.

例:

rows = [
    ("row1",),
    ("row2",),
]
# cur is an sqlite3.Cursor object
cur.executemany("INSERT INTO data VALUES(?)", rows)

注釈

RETURNING 句(RETURNING clauses [https://www.sqlite.org/lang_returning.html])を含むDML文を含め、結果の行はすべて破棄されます。

バージョン 3.12 で非推奨、バージョン 3.14 で削除予定: 名前付きプレースホルダー が使用され、かつ、パラメーターが dict ではなくシーケンスである場合、 DeprecationWarning を送出します。 Python 3.14 以降では、代わりに ProgrammingError を送出します。

executescript(sql_script, /)

sql_script 内の複数のSQL文を実行します。 autocommit が LEGACY_TRANSACTION_CONTROL で、かつ、保留中のトランザクションがある場合、暗黙の COMMIT 文が最初に実行されます。その他の暗黙のトランザクション制御は実行されませんので、トランザクション制御を sql_script に追加しなければなりません。

sql_script は 文字列 でなければなりません。

例:

# cur is an sqlite3.Cursor object
cur.executescript("""
    BEGIN;
    CREATE TABLE person(firstname, lastname, age);
    CREATE TABLE book(title, author, published);
    CREATE TABLE publisher(name, address);
    COMMIT;
""")

fetchone()

row_factory が None の場合、 次の行のクエリ結果セットを タプル として返します。それ以外の場合は、 それを行工場(row factory)に渡し、 その結果を返します。 これ以上データが無い場合は None を返します。

fetchmany(size=cursor.arraysize)

クエリ結果の次の行セットを list として返します。行がそれ以上ない場合は、空のリストを返します。

呼び出しごとに取得する行数は、size パラメーターで指定されます。 size が指定されていない場合、 arraysize が取得する行数を決定します。有効な行の数が size 未満の場合は、有効な数の行が返されます。

size 引数とパフォーマンスの関係についての注意です。パフォーマンスを最適化するためには、大抵、 arraysize 属性を利用するのがベストです。 size 引数を利用したのであれば、次回の fetchmany() の呼び出しでも size 引数に同一の値を指定するのがのがベストです。

fetchall()

クエリ結果の(残りの)すべての行を list として返します。 有効な行がない場合は、空のリストを返します。 arraysize 属性は、この操作のパフォーマンスに影響を与える可能性があることに注意してください。

close()

(__del__ が呼び出される時ではなく、) 今すぐカーソルを閉じます。

この時点から、このカーソルは使用できなくなります。今後、このカーソルで何らかの操作を試みると、 ProgrammingError 例外が送出されます。

setinputsizes(sizes, /)

DB-API で必要です。 sqlite3 では何もしません。

setoutputsize(size, column=None, /)

DB-API で必要です。 sqlite3 では何もしません。

arraysize

fetchmany によって返される行(row)数を制御する、読み取りと書き込みが可能な属性。 デフォルト値は 1 で、これは呼び出しごとに 1 行が取得されることを意味します。

connection

カーソルが属する SQLite データベース Connection を提供する読み取り専用属性。 con.cursor() と呼び出して作成した Cursor オブジェクトには、con を参照する connection 属性があります:

>>> con = sqlite3.connect(":memory:")
>>> cur = con.cursor()
>>> cur.connection == con
True
>>> con.close()

description

最後のクエリの列(column)名を提供する読み取り専用属性。 Python DB API との互換性を維持するために、各列ごとに 7 項目のタプルで、先頭の項目が列名、残りの6項目が None です。

この属性は SELECT 文にマッチする行(row)が1つもなかった場合でもセットされます。

lastrowid

最後に挿入された行の行 ID (row id) を提供する読み取り専用属性。 execute() で INSERT または REPLACE 文が成功した後にのみ更新されます。他のSQL文や、 executemany() の後や、 executescript() の後や、 挿入が失敗した場合、 lastrowid の値は変更されません。lastrowid の初期値は None です。

注釈

WITHOUT ROWID テーブルへの挿入(insert)は記録されません。

バージョン 3.6 で変更: REPLACE 文のサポートが追加されました。

rowcount

INSERT や UPDATE や DELETE や REPLACE 文で変更された行数を提供する読み取り専用属性。 CTE クエリを含む他のSQL文は -1 です。 execute() と executemany() メソッドのみにおいて、 SQL文(statement)実行の完了後に更新されます。 なぜなら rowcount を更新するためには、結果の行を取得(fetch)しなければならないからです。

row_factory

この カーソル から取得された行の表現方法を制御します。 None の場合、行は タプル として表されます。 sqlite3.Row に設定することもできます。 そしてまた、 Cursor オブジェクトと、 行の値の タプル の、 2 つの引数を受け取り、 SQLite の行(row)を表すカスタム・オブジェクトを返す、 呼び出し可能オブジェクト に設定することもできます。

カーソル・オブジェクト の作成時に Connection.row_factory の値をこの属性のデフォルト値として設定します。この属性に割り当てても、親接続(parent connection)の Connection.row_factory には影響しません。

詳細は 行工場(row factories)の作成方法と使用方法 をご覧下さい。

Row オブジェクト

class sqlite3.Row

Row インスタンスは、 Connection オブジェクトの、高度に最適化された row_factory の役割をします。 反復(iteration)や、等しいかどうかのテスト(equality testing)や、 len() 関数や 、 列名(column name)とインデックスによる マッピング のアクセスを、サポートします。

列名(column names)と値(values)が全く同一である 2 つの Row オブジェクトを比較すると、等しいと見なされます。

詳細は 行工場(row factories)の作成方法と使用方法 をご覧下さい。

keys()

列名(column names)の リスト を 文字列 として返します。 クエリの直後であれば、それは Cursor.description の各タプルの最初のメンバーです。

バージョン 3.5 で変更: スライスがサポートされました。

Blob オブジェクト

class sqlite3.Blob

Added in version 3.11.

Blob インスタンスは、 SQLite の BLOB とデータを読み書きできる file-like object です。 len(blob) を呼び出して、 Blob のサイズ (バイト数) を取得します。 Blob データに直接アクセスするには、インデックスと スライス を使用します。

Blob を コンテキストマネージャ として使用して、 使用後に Blob ハンドルが確実に閉じられるようにします。

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()

close()

Blob を閉じます。

この時点から、 BLOB は使用できなくなります。 BLOB に対してさらに操作を試みると、 Error (またはそのサブクラスの) 例外を送出します。

read(length=-1, /)

BLOB の現在のオフセット位置から length バイトのデータを読み取り返ます。 BLOB の現在のオフセット位置から末尾までの残りが length バイトよりも少ない場合、末尾までのデータを読み取ります。 length が指定されていない場合、 または負数の場合、 read() は BLOB の現在のオフセット位置から末尾までのデータを読み取ります。

write(data, /)

BLOB の現在のオフセット位置から data を書き込みます。 この関数では BLOB の長さを変更できません。 BLOB の末尾を超えて書き込もうとすると ValueError を送出します。

tell()

BLOBの現在のオフセット位置(current access position)を返します。

seek(offset, origin=os.SEEK_SET, /)

Set the current access position of the blob to offset. The origin argument defaults to os.SEEK_SET (absolute blob positioning). Other values for origin are os.SEEK_CUR (seek relative to the current position) and os.SEEK_END (seek relative to the blob’s end).

PrepareProtocol オブジェクト

class sqlite3.PrepareProtocol

PrepareProtocol 型の唯一の目的は、 SQLite でネイティブにサポートされている型 に オブジェクト自身で適合(adapt) できるオブジェクトの PEP 246 [https://peps.python.org/pep-0246/] スタイルの適合プロトコルとして機能することです。

例外

例外の階層は DB-API 2.0 (PEP 249 [https://peps.python.org/pep-0249/]) で定義されています。

exception sqlite3.Warning

この例外は、現在 sqlite3 モジュールでは送出しませんが、ユーザー定義関数が挿入処理中にデータを切り捨てる場合など、sqlite3 を使用するアプリケーションによって送出されるる可能性があります。 Warning は Exception のサブクラスです。

exception sqlite3.Error

このモジュールの他の例外の基底となるクラス。 これを使用すると、1 つの except 文ですべてのエラーをキャッチできます。 Error は Exception のサブクラスです。

例外が SQLite ライブラリ内で発生した場合、 以下の 2 つの属性が例外に追加されます:

sqlite_errorcode

SQLite API [https://sqlite.org/rescode.html] からの数値エラー・コード

Added in version 3.11.

sqlite_errorname

SQLite API [https://sqlite.org/rescode.html] からの数値エラー・コードの記号名

Added in version 3.11.

exception sqlite3.InterfaceError

低レベルの SQLite C API の誤用により送出される例外。 つまり、この例外が送出された場合、おそらく sqlite3 モジュールのバグを示しています。 InterfaceError は Error のサブクラスです。

exception sqlite3.DatabaseError

データベースに関連するエラーに対して送出される例外。 これは、いくつかの種類のデータベース・エラーの基底の例外として機能します。 これを特殊化(specialise)したサブクラスを介して暗黙的にのみ送出されます。 DatabaseError は Error のサブクラスです。

exception sqlite3.DataError

範囲外の数値や長すぎる文字列など、処理されたデータの問題によって発生したエラーに対して送出される例外。 DataError は DatabaseError のサブクラスです。

exception sqlite3.OperationalError

データベースの操作に関連し、必ずしもプログラマの制御下にないエラーに対して発生する例外。 たとえば、データベース・パスが見つからないとか、トランザクションを処理できませんでした等。 OperationalError は DatabaseError のサブクラスです。

exception sqlite3.IntegrityError

データベースの参照整合性が影響を受ける場合に発生する例外。 たとえば外部キーのチェック(foreign key check)が失敗したとき。 DatabaseError のサブクラスです。

exception sqlite3.InternalError

SQLite が内部エラーに遭遇したときに発生する例外。 これが送出された場合、ランタイム SQLite ライブラリに問題があることを示している可能性があります。 InternalError は DatabaseError のサブクラスです。

exception sqlite3.ProgrammingError

sqlite3 API プログラミング・エラーに対して送出される例外。たとえば、クエリに間違った数のバインディング(結び付け)を指定したり、閉じた後の Connection を操作しようとしたりしたとき。 ProgrammingError は DatabaseError のサブクラスです。

exception sqlite3.NotSupportedError

メソッドまたはデータベース API が 背後の SQLite ライブラリでサポートしていない場合に送出される例外。たとえば、背後の SQLite ライブラリが決定論的関数(deterministic functions)をサポートしていない場合に、create_function() で deterministic を True に設定したとき。 NotSupportedError は DatabaseError のサブクラスです。

SQLite と Python の型

SQLite は以下の型をネイティブにサポートします: NULL, INTEGER, REAL, TEXT, BLOB。

したがって、次の Python の型は問題なく SQLite に送り込めます:

Python の型

SQLite の型

None

NULL

int

INTEGER

float

REAL

str

TEXT

bytes

BLOB

SQLite の型から Python の型へのデフォルトでの変換は以下の通りです:

SQLite の型

Python の型

NULL

None

INTEGER

int

REAL

float

TEXT

text_factory に依存する。デフォルトでは str 。

BLOB

bytes

sqlite3 モジュールの型システムは 2 つの方法で拡張可能です。 オブジェクト適合関数(adapter) を介して SQLite データベースに追加の Python 型を格納できます。 または、 変換関数(converter) を介して sqlite3 モジュールが SQLite 型を Python 型に変換できます。

デフォルトの適合関数(adapters)とデフォルトの変換関数(converters)(非推奨)

注釈

デフォルトの適合関数(adapters)とデフォルトの変換関数(converters)は、 Python 3.12 以降非推奨になりました。代わりに、 適合関数と変換関数のレシピ集 を利用して、あなたのニーズに合わせて仕立てて下さい。

非推奨の、デフォルトの適合関数(adapters)とデフォルトの変換関数(converters)は以下のもので構成されています:

datetime.date オブジェクトを ISO 8601 [https://en.wikipedia.org/wiki/ISO_8601] 形式の 文字列 にする適合関数(adapter)。

datetime.datetime オブジェクトを ISO 8601 形式の文字列にする適合関数(adapter)。

"date" と 宣言された 型を datetime.date オブジェクトにする変換関数(converter)。

"timestamp" と宣言された型を datetime.datetime オブジェクトにする変換関数(converter)。小数部分は 6 桁 (マイクロ秒の精度) に切り捨てられます。

注釈

デフォルトの "timestamp" 変換関数は、データベース内の UTC オフセットを無視し、常に素朴(naive)な datetime.datetime オブジェクトを返します。 timestamp で UTC オフセットを保持するには、変換関数を無効のままにするか、あるいは、オフセット対応の変換関数を register_converter() に登録します。

バージョン 3.12 で非推奨.

コマンドライン・インターフェース

sqlite3 モジュールは、単純な SQLite シェルを提供するために、インタプリタで -m スイッチを使用してスクリプトとして呼び出すことができます。引数は以下のとおりです:

python -m sqlite3 [-h] [-v] [filename] [sql]

.quit または CTRL-D を入力するとシェルを終了(exit)します。

-h, --help

CLI ヘルプを表示。

-v, --version

背後の SQLite ライブラリのバージョンを出力します。

Added in version 3.12.

ハウツー・ガイド

プレースホルダを使用して SQL クエリに値を結び付ける方法

たいてい、SQL 操作は Python 変数の値を使う必要があります。しかし、 Python の文字列操作を使用してクエリを組み立てるのはSQLインジェクション攻撃(SQL injection attacks [https://en.wikipedia.org/wiki/SQL_injection])に対して脆弱なので注意が必要です。たとえば、攻撃者は以下のように単純にシングルクォートを閉じて OR TRUE を挿入してすべての行を選択できます:

>>> # Never do this -- insecure!
>>> symbol = input()
' OR TRUE; --
>>> sql = "SELECT * FROM stocks WHERE symbol = '%s'" % symbol
>>> print(sql)
SELECT * FROM stocks WHERE symbol = '' OR TRUE; --'
>>> cur.execute(sql)

代わりに、DB-API のパラメータ割り当てを使います。クエリ文字列にPythonの変数を挿入するには、クエリ文字列中でプレースホルダを使用し、 かつ、 カーソルの execute() メソッドの 2 番目の引数にPythonの変数を値の タプル として指定することにより、 実際の値をクエリに割り当てます。

SQL 文では、疑問符 (qmark スタイル) または名前付きプレースホルダー (名前付きスタイル) の 2 種類のプレースホルダーのいずれかを使用できます。 qmark スタイルの場合、parameters は、 シーケンス でなければならず、シーケンスの長さがプレースホルダーの数と一致する必要があります。そうでなければ、 ProgrammingError を送出します。名前付きスタイルの場合、 parameters は dict (またはそのサブクラス) のインスタンスである必要があり、すべての名前付きパラメーターのキーが含まれている必要があります。余分な項目は無視されます。両方のスタイルの例を以下に示します。

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()

注釈

PEP 249 [https://peps.python.org/pep-0249/] numeric プレースホルダは サポートされていません 。 使用すると、名前付きプレースホルダとして解釈されます。

カスタム Python 型を SQLite 値に適合させる方法

SQLite は、 限られたデータ型のみをネイティブにサポートします。 カスタム Python 型を SQLite データベースに保存するには、 SQLite がネイティブに理解できる Python 型 のいずれかに 適合 (adapt)させます。

Python オブジェクトを SQLite の型に適合させる方法は 2 つあります。それは、オブジェクト自体を適合させる方法と、 adapter callable を使用する方法です。 後者は前者よりも優先されます。 カスタム型をエクスポートするライブラリの場合、 その型がそれ自体を適合させる事ができるようにすることが理にかなっている場合があります。 アプリケーション開発者としては、カスタム適合関数を登録して直接制御する方が理にかなっている場合もあります。

適合可能オブジェクトの書き方

直交座標系(Cartesian coordinate system)で x と y のペアで座標を表す、 Point クラスがあるとします。 この x と y のペアはセミコロンで区切られたテキスト文字列としてデータベースに保存されます。 これは、適合した値を返す __conform__(self, protocol) メソッドを追加することで実装できます。 protocol に渡されるオブジェクトは、 PrepareProtocol 型になります。

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()

適合用呼び出し可能オブジェクト(adapter callables)の登録方法

別の策としては、Python オブジェクトを SQLite 互換の型に変換する関数を作成することが挙げられます。 この関数は、 register_adapter() を使用して登録できます。

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()

SQLite 値をカスタム Python 型に変換する方法

適合関数(adapter)を使用すると、カスタム Python 型から SQLite 値に変換できます。SQLite 値 から カスタム Python 型に変換できるようにするためには、 変換関数 (converters)を使用します。

それでは Point クラスの話に戻るとしましょう。 先程は x 座標と y 座標をセミコロンで区切られた文字列として SQLite に格納しました。

まず、 文字列をパラメーターとして受け取り、そこから Point オブジェクトを構築する変換関数を定義します。

注釈

変換関数には、基になる SQLite データ型に関係なく、 常に bytes オブジェクトで渡されます。

def convert_point(s):
    x, y = map(float, s.split(b";"))
    return Point(x, y)

与えられた SQLite 値をどの時点で変換すべきかを sqlite3 に伝える必要があります。これは、 connect() の detect_types パラメータを使用して、データベースに接続する際に行います。 以下の 3 つの選択肢があります:

暗黙的: detect_types に PARSE_DECLTYPES と設定。

明示的: detect_types に PARSE_COLNAMES と設定。

両方: detect_types に sqlite3.PARSE_DECLTYPES | sqlite3.PARSE_COLNAMES を設定。列名での指定は、宣言時の型よりも優先されます。

以下の例では、暗黙的なアプローチと明示的なアプローチについて表しています:

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()

適合関数と変換関数のレシピ集

この節では一般的な適合関数と変換関数のレシピを紹介します。

import datetime
import sqlite3

def adapt_date_iso(val):
    """Adapt datetime.date to ISO 8601 date."""
    return val.isoformat()

def adapt_datetime_iso(val):
    """Adapt datetime.datetime to timezone-naive ISO 8601 date."""
    return val.isoformat()

def adapt_datetime_epoch(val):
    """Adapt datetime.datetime to Unix timestamp."""
    return int(val.timestamp())

sqlite3.register_adapter(datetime.date, adapt_date_iso)
sqlite3.register_adapter(datetime.datetime, adapt_datetime_iso)
sqlite3.register_adapter(datetime.datetime, adapt_datetime_epoch)

def convert_date(val):
    """Convert ISO 8601 date to datetime.date object."""
    return datetime.date.fromisoformat(val.decode())

def convert_datetime(val):
    """Convert ISO 8601 datetime to datetime.datetime object."""
    return datetime.datetime.fromisoformat(val.decode())

def convert_timestamp(val):
    """Convert Unix epoch timestamp to datetime.datetime object."""
    return datetime.datetime.fromtimestamp(int(val))

sqlite3.register_converter("date", convert_date)
sqlite3.register_converter("datetime", convert_datetime)
sqlite3.register_converter("timestamp", convert_timestamp)

接続(connection)ショートカット・メソッドの使い方

Connection クラスのメソッド execute() と executemany() と executescript() を使うことで、 (しばしば余計な) Cursor オブジェクトをわざわざ作り出さずに済むので、コードをより簡潔に書くことができます。 Cursor オブジェクトは暗黙裡に生成され、ショートカット・メソッドの戻り値として受け取ることができます。この方法を使えば、 SELECT 文を実行してその結果について反復することが、 Connection オブジェクトに対する呼び出し一つで行なえます。

# 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()

接続(connection)コンテキストマネージャの使い方

Connection オブジェクトは、コンテキスト・マネージャーとして使用でき、コンテキスト・マネージャーとして使用すると、 with ブロックを離れるときに、開いているトランザクションを自動的にコミットまたはロールバックします。 with 文のブロックが例外なく終了すると、トランザクションはコミットされます。このコミットが失敗した、または、 with 文のブロックでキャッチされなかった例外が発生した場合、トランザクションはロールバックされます。 autocommit が False の場合、コミット後またはロールバック後に新しいトランザクションが暗黙に開かれます。

with 文のブロックを離れるときに開いているトランザクションがない、または、 autocommit が True の場合、コンテキスト・マネージャは何も行いません。

注釈

The context manager neither implicitly opens a new transaction nor closes the connection. If you need a closing context manager, consider using contextlib.closing().

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()

SQLite URI の操作方法

URI の小技をいくつか紹介します:

データベースを読み取り専用で開きます:

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

まだ存在しない場合、新しいデータベース・ファイルを暗黙に作成しません。なお、新しいファイルが作成できない場合には OperationalError が送出されます:

>>> con = sqlite3.connect("file:nosuchdb.db?mode=rw", uri=True)
Traceback (most recent call last):
OperationalError: unable to open database file

共有の名前付きインメモリ・データベースを作成します:

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()

パラメータのリストを含む、この機能の詳細については、 SQLite URI documentation [https://www.sqlite.org/uri.html] を参照してください。

行工場(row factories)の作成方法と使用方法

デフォルトでは、 sqlite3 は各行(row)を タプル として表します。 タプル があなたのニーズと合わない場合は、 sqlite3.Row クラスまたはカスタム row_factory を使用できます。

row_factory は Cursor と Connection の両方に属性として存在しますが、 その接続(connection)から作成されたすべてのカーソルが同一の行工場(row factory)を使用するようにするために、 Connection.row_factory を設定することをお勧めします。

Row は、 タプル に対してメモリ・オーバーヘッドとパフォーマンスへの影響を最小限に抑えながら、列(row)へのインデックスによるアクセスと、列への(大文字と小文字を区別しない)名前によるアクセスを提供します。 Row を行工場(row factory)として使用するには、 row_factory 属性に割り当てます:

>>> con = sqlite3.connect(":memory:")
>>> con.row_factory = sqlite3.Row

このように設定すると、クエリは :class:`!Row`オブジェクトを返すようになります:

>>> 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()

注釈

The FROM clause can be omitted in the 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 expr AS alias.

各列名が各値にマップされた dict として行を返す、カスタム row_factory を作成することもできます:

def dict_factory(cursor, row):
    fields = [column[0] for column in cursor.description]
    return {key: value for key, value in zip(fields, row)}

これを使うと、クエリは タプル の代わりに dict を返すようになります:

>>> 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()

以下の行工場(row factory)は 名前付きタプル を返します:

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)

namedtuple_factory() は以下のようにして使う事ができます:

>>> 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()

上記レシピをチューニングすれば、 namedtuple の代わりに dataclass または、その他のカスタム・クラスを使用するように適合(adapt)させることができます。

How to handle non-UTF-8 text encodings

By default, sqlite3 uses str to adapt SQLite values with the 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 text_factory to handle such cases.

Because of SQLite's flexible typing [https://www.sqlite.org/flextypegood.html], it is not uncommon to encounter table columns with the 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 Connection instance con connected to this database, we can decode the Latin-2 encoded text using this text_factory:

con.text_factory = lambda data: str(data, encoding="latin2")

For invalid UTF-8 or arbitrary data in stored in TEXT table columns, you can use the following technique, borrowed from the Unicode HOWTO:

con.text_factory = lambda data: str(data, errors="surrogateescape")

注釈

The sqlite3 module API does not support strings containing surrogates.

参考

Unicode HOWTO

説明

トランザクション制御

sqlite3 は、データベース・トランザクションを開くかどうか、いつ、どのように開くかを制御する複数の方法を提供します。 autocommit 属性に依るトランザクション制御 が推奨されますが、isolation_level 属性に依るトランザクション制御 は Python 3.12 より前の動作を保持します。

autocommit 属性に依るトランザクション制御

トランザクションの動作を制御する推奨方法は、 Connection.autocommit 属性を使用することです。 この属性は connect() の autocommit パラメータを使用して設定して頂けるとありがたいです。

autocommit を False に設定することをお勧めします。そうすると PEP 249 [https://peps.python.org/pep-0249/] 対応のトランザクション制御を行います。これは以下のことを意味します:

sqlite3 はトランザクションが常に開いていることを保証します。そのため、 connect() や Connection.commit() や Connection.rollback() は暗黙に新しいトランザクションを開きます(1つ目については保留中のトランザクションを閉じた直後で、後の2つについてはその直後に、です)。 sqlite3 はトランザクションを開くときに BEGIN DEFERRED 文を使用します。

トランザクションは、 commit() を使用して明示的にコミットする必要があります。

トランザクションは、 rollback() を使用して明示的にロールバックする必要があります。

データベースの保留中に行った変更は close() された場合、暗黙のロールバックが実行されます。

autocommit を True に設定して、SQLite の autocommit mode [https://www.sqlite.org/lang_transaction.html#implicit_versus_explicit_transactions] を有効にします。このモードでは、 Connection.commit() と Connection.rollback() は効果がありません。 SQLite の自動コミット・モード(autocommit mode)は、 PEP 249 [https://peps.python.org/pep-0249/] 対応の Connection.autocommit 属性とは異なることに注意してください。 Connection.in_transaction を使用して、低レベル SQLite 自動コミット・モードを問い合わせします。

autocommit を LEGACY_TRANSACTION_CONTROL に設定して、トランザクション制御の振る舞いを Connection.isolation_level 属性に任せます。詳細については isolation_level 属性に依るトランザクション制御 を参照してください。

isolation_level 属性に依るトランザクション制御

注釈

推奨のトランザクション制御方法は、 autocommit 属性を使用することです。 autocommit 属性に依るトランザクション制御 を参照してください。

Connection.autocommit が LEGACY_TRANSACTION_CONTROL (これがデフォルトです)に設定されている場合、トランザクションの振る舞いは Connection.isolation_level 属性を使用して制御されます。 LEGACY_TRANSACTION_CONTROL 以外の場合、 isolation_level は効果がありません。

接続属性 isolation_level が None で無いのなら、 execute() や executemany() が INSERT または UPDATE または DELETE または REPLACE 文を実行する前に新しいトランザクションが暗黙に開かれます。それ以外のSQL文では暗黙のトランザクション処理は行われません。 commit() メソッドや rollback() メソッドを使用して、 保留中のトランザクションをそれぞれコミットおよびロールバックします。あなたは、背後にある SQLite ライブラリのトランザクションの振る舞い(SQLite transaction behaviour [https://www.sqlite.org/lang_transaction.html#deferred_immediate_and_exclusive_transactions]) — つまり、 sqlite3 が暗黙に実行する BEGIN 文の有無とその種類 – を、 isolation_level 属性を介して選択できます。

isolation_level が None に設定されていると、トランザクションは暗黙に開かれません。これにより、背後にある SQLite ライブラリを自動コミット・モード(autocommit mode [https://www.sqlite.org/lang_transaction.html#implicit_versus_explicit_transactions])にしたまま、 明示的な SQL 文を使用して、 ユーザが独自のトランザクション処理を行えるようにします。背後にある SQLite ライブラリの自動コミット・モードは、 in_transaction 属性を使用して問い合わせできます。

executescript() メソッドは、 isolation_level の値に関係なく、与えられた SQL スクリプトの実行前に、保留中のトランザクションを暗黙にコミットします。

バージョン 3.6 で変更: sqlite3 は、 DDL文の前に、開いているトランザクションを暗黙にコミットしていました。これはもはや当てはまりません。

バージョン 3.12 で変更: 推奨のトランザクションを制御方法は、 autocommit 属性を使用することです。

データ圧縮とアーカイブ

この章で説明されるモジュールは zlib, gzip, bzip2, lzma アルゴリズムによるデータの圧縮と、 ZIP, tar フォーマットのアーカイブ作成をサポートします。 shutil モジュールで提供される アーカイブ化操作 も参照してください。

zlib --- Compression compatible with gzip

gzip --- Support for gzip files

使い方の例

コマンドラインインターフェイス

コマンドラインオプション

bz2 --- Support for bzip2 compression

ファイルの圧縮/解凍

逐次圧縮および展開

一括圧縮/解凍

使い方の例

lzma --- Compression using the LZMA algorithm

圧縮ファイルへの読み書き

メモリ上での圧縮と展開

その他

カスタムフィルタチェインの指定

使用例

zipfile --- Work with ZIP archives

ZipFile オブジェクト

Path オブジェクト

PyZipFile オブジェクト

ZipInfo オブジェクト

コマンドラインインターフェイス

コマンドラインオプション

Decompression pitfalls

From file itself

File System limitations

Resources limitations

Interruption

Default behaviors of extraction

tarfile --- Read and write tar archive files

TarFile オブジェクト

TarInfo オブジェクト

Extraction filters

Default named filters

Filter errors

Hints for further verification

Supporting older Python versions

Stateful extraction filter example

コマンドラインインターフェイス

コマンドラインオプション

使用例

サポートしている tar フォーマット

Unicode に関する問題

zlib --- Compression compatible with gzip

このモジュールは、データ圧縮を必要とするアプリケーションが zlib ライブラリを使って圧縮および展開を行えるようにします。zlib ライブラリ自身の Webページは https://www.zlib.net です。Python モジュールと zlib ライブラリの 1.1.3 より前のバージョンには互換性のない部分があることが知られています。1.1.3 には セキュリティホール [https://zlib.net/zlib_faq.html#faq33] が存在するため、1.1.4 以降のバージョンを利用することを推奨します。

zlib の関数にはたくさんのオプションがあり、場合によっては特定の順番で使わなければなりません。このドキュメントではそれら順番についてすべてを説明しようとはしていません。詳細は公式サイト http://www.zlib.net/manual.html にある zlib のマニュアルを参照してください。

.gz ファイルの読み書きのためには、 gzip モジュールを参照してください。

このモジュールで利用可能な例外と関数を以下に示します:

exception zlib.error

圧縮および展開時のエラーによって送出される例外です。

zlib.adler32(data[, value])

data の Adler-32 チェックサムを計算します (Adler-32 チェックサムは、おおむね CRC32 と同等の信頼性を持ちながら、はるかに高速に計算できます)。結果は、符号のない 32 ビットの整数です。 value が与えられている場合、チェックサム計算の初期値として使われます。与えられていない場合、デフォルト値の 1 が使われます。 value を与えることで、複数の入力を結合したデータ全体にわたり、通しのチェックサムを計算できます。このアルゴリズムは暗号論的には強力ではなく、認証やデジタル署名などに用いるべきではありません。また、チェックサムアルゴリズムとして設計されているため、汎用のハッシュアルゴリズムには向きません。

バージョン 3.0 で変更: The result is always unsigned.

zlib.compress(data, /, level=-1, wbits=MAX_WBITS)

Compresses the bytes in data, returning a bytes object containing compressed data. level is an integer from 0 to 9 or -1 controlling the level of compression; 1 (Z_BEST_SPEED) is fastest and produces the least compression, 9 (Z_BEST_COMPRESSION) is slowest and produces the most. 0 (Z_NO_COMPRESSION) is no compression. The default value is -1 (Z_DEFAULT_COMPRESSION). Z_DEFAULT_COMPRESSION represents a default compromise between speed and compression (currently equivalent to level 6).

The wbits argument controls the size of the history buffer (or the "window size") used when compressing data, and whether a header and trailer is included in the output. It can take several ranges of values, defaulting to 15 (MAX_WBITS):

+9 to +15: The base-two logarithm of the window size, which therefore ranges between 512 and 32768. Larger values produce better compression at the expense of greater memory usage. The resulting output will include a zlib-specific header and trailer.

−9 to −15: Uses the absolute value of wbits as the window size logarithm, while producing a raw output stream with no header or trailing checksum.

+25 to +31 = 16 + (9 to 15): Uses the low 4 bits of the value as the window size logarithm, while including a basic gzip header and trailing checksum in the output.

Raises the error exception if any error occurs.

バージョン 3.6 で変更: level can now be used as a keyword parameter.

バージョン 3.11 で変更: The wbits parameter is now available to set window bits and compression type.

zlib.compressobj(level=-1, method=DEFLATED, wbits=MAX_WBITS, memLevel=DEF_MEM_LEVEL, strategy=Z_DEFAULT_STRATEGY[, zdict])

一度にメモリ上に置くことができないようなデータストリームを圧縮するための圧縮オブジェクトを返します。

level は圧縮レベルです。0 から 9 、または -1 の整数を取り、1 (Z_BEST_SPEED) は最も高速で最小限の圧縮を行い、9 (Z_BEST_COMPRESSION) は最も低速で最大限の圧縮を行います。0 (Z_NO_COMPRESSION) は圧縮しません。デフォルトは -1 です (Z_DEFAULT_COMPRESSION)。Z_DEFAULT_COMPRESSION は、速度と圧縮の間のデフォルトの妥協点 (現在、レベル 6 に対応します) を表します。

method は圧縮アルゴリズムです。現在、 DEFLATED のみサポートされています。

The wbits parameter controls the size of the history buffer (or the "window size"), and what header and trailer format will be used. It has the same meaning as described for compress().

memLevel 引数は内部圧縮状態用に使用されるメモリ量を制御します。有効な値は 1 から 9 です。大きい値ほど多くのメモリを消費しますが、より速く、より小さな出力を作成します。

strategy は圧縮アルゴリズムの調整に使用されます。指定可能な値は、 Z_DEFAULT_STRATEGY, Z_FILTERED, Z_HUFFMAN_ONLY, Z_RLE (zlib 1.2.0.1) および Z_FIXED (zlib 1.2.2.2) です。

zdict は定義済み圧縮辞書です。これは圧縮されるデータ内で繰り返し現れると予想されるサブシーケンスを含む (bytes オブジェクトのような) バイト列のシーケンスです。最も一般的と思われるサブシーケンスは辞書の末尾に来なければなりません。

バージョン 3.3 で変更: zdict パラメータとキーワード引数のサポートが追加されました。

zlib.crc32(data[, value])

data の CRC (Cyclic Redundancy Check, 巡回冗長検査) チェックサムを計算します。結果は、符号のない 32 ビットの整数です。 value が与えられている場合、チェックサム計算の初期値として使われます。与えられていない場合、デフォルト値の 0 が使われます。 value を与えることで、複数の入力を結合したデータ全体にわたり、通しのチェックサムを計算できます。このアルゴリズムは暗号論的には強力ではなく、認証やデジタル署名などに用いるべきではありません。また、チェックサムアルゴリズムとして設計されているため、汎用のハッシュアルゴリズムには向きません。

バージョン 3.0 で変更: The result is always unsigned.

zlib.decompress(data, /, wbits=MAX_WBITS, bufsize=DEF_BUF_SIZE)

Decompresses the bytes in data, returning a bytes object containing the uncompressed data. The wbits parameter depends on the format of data, and is discussed further below. If bufsize is given, it is used as the initial size of the output buffer. Raises the error exception if any error occurs.

The wbits parameter controls the size of the history buffer (or "window size"), and what header and trailer format is expected. It is similar to the parameter for compressobj(), but accepts more ranges of values:

+8 to +15: The base-two logarithm of the window size. The input must include a zlib header and trailer.

0: Automatically determine the window size from the zlib header. Only supported since zlib 1.2.3.5.

−8 to −15: Uses the absolute value of wbits as the window size logarithm. The input must be a raw stream with no header or trailer.

+24 to +31 = 16 + (8 to 15): Uses the low 4 bits of the value as the window size logarithm. The input must include a gzip header and trailer.

+40 to +47 = 32 + (8 to 15): Uses the low 4 bits of the value as the window size logarithm, and automatically accepts either the zlib or gzip format.

When decompressing a stream, the window size must not be smaller than the size originally used to compress the stream; using a too-small value may result in an error exception. The default wbits value corresponds to the largest window size and requires a zlib header and trailer to be included.

bufsize は展開されたデータを保持するためのバッファサイズの初期値です。バッファの空きは必要に応じて必要なだけ増加するので、必ずしも正確な値を指定する必要はありません。この値のチューニングでできることは、malloc() が呼ばれる回数を数回減らすことぐらいです。

バージョン 3.6 で変更: wbits and bufsize can be used as keyword arguments.

zlib.decompressobj(wbits=MAX_WBITS[, zdict])

一度にメモリ上に置くことができないようなデータストリームを展開するための展開オブジェクトを返します。

The wbits parameter controls the size of the history buffer (or the "window size"), and what header and trailer format is expected. It has the same meaning as described for decompress().

zdict パラメータには定義済み圧縮辞書を指定します。このパラメータを指定する場合、展開するデータを圧縮した際に使用した辞書と同じものでなければなりません。

注釈

zdict が (bytearray のような) 変更可能オブジェクトの場合、decompressobj() の呼び出しとデコンプレッサの decompress() メソッドの最初の呼び出しの間に辞書の内容を変更してはいけません。

バージョン 3.3 で変更: パラメータに zdict を追加しました。

圧縮オブジェクトは以下のメソッドをサポートしています:

Compress.compress(data)

data を圧縮し、圧縮されたデータを含むバイト列オブジェクトを返します。この文字列は少なくとも data の一部分のデータに対する圧縮データを含みます。このデータは以前に呼んだ compress() が返した出力と結合することができます。入力の一部は以後の処理のために内部バッファに保存されることもあります。

Compress.flush([mode])

未処理の全入力データが処理され、この未処理部分を圧縮したデータを含むバイト列オブジェクトが返されます。mode は定数 Z_NO_FLUSH、Z_PARTIAL_FLUSH、Z_SYNC_FLUSH、Z_FULL_FLUSH、Z_BLOCK (zlib 1.2.3.4)、または Z_FINISH のいずれかをとり、デフォルト値は Z_FINISH です。Z_FINISH を除く全ての定数はこれ以後にもデータバイト文字列を圧縮できるモードです。一方、Z_FINISH は圧縮ストリームを閉じ、これ以後のデータの圧縮を停止します。mode に Z_FINISH を指定して flush() メソッドを呼び出した後は、compress() メソッドを再び呼ぶべきではありません。唯一の現実的な操作はこのオブジェクトを削除することだけです。

Compress.copy()

圧縮オブジェクトのコピーを返します。これを使うと先頭部分が共通している複数のデータを効率的に圧縮することができます。

バージョン 3.8 で変更: Added copy.copy() and copy.deepcopy() support to compression objects.

展開オブジェクトは以下のメソッドと属性をサポートしています:

Decompress.unused_data

圧縮データの末尾より後のバイト列が入ったバイト列オブジェクトです。すなわち、この値は圧縮データの入っているバイト列の最後の文字が利用可能になるまでは b"" のままとなります。入力バイト文字列すべてが圧縮データを含んでいた場合、この属性は b"" 、すなわち空バイト列になります。

Decompress.unconsumed_tail

展開されたデータを収めるバッファの長さ制限を超えたために、直近の decompress() 呼び出しで処理しきれなかったデータを含むバイト列オブジェクトです。このデータはまだ zlib 側からは見えていないので、正しい展開出力を得るには以降の decompress() メソッド呼び出しに (場合によっては後続のデータが追加された) データを差し戻さなければなりません。

Decompress.eof

圧縮データストリームの終了に達したかどうかを示すブール値です。

これは、正常な形式の圧縮ストリームと、不完全あるいは切り詰められたストリームとを区別することを可能にします。

Added in version 3.3.

Decompress.decompress(data, max_length=0)

data を展開し、少なくとも string の一部分に対応する展開されたデータを含むバイト列オブジェクトを返します。このデータは以前に decompress() メソッドを呼んだ時に返された出力と結合することができます。入力データの一部分が以後の処理のために内部バッファに保存されることもあります。

オプションパラメータ max_length が非ゼロの場合、返される展開データの長さが max_length 以下に制限されます。このことは入力した圧縮データの全てが処理されるとは限らないことを意味し、処理されなかったデータは unconsumed_tail 属性に保存されます。展開処理を継続する場合、この保存されたバイト文字列を以降の decompress() 呼び出しに渡さなくてはなりません。 max_length が 0 の場合、全ての入力が展開され、 unconsumed_tail 属性は空になります。

バージョン 3.6 で変更: max_length can be used as a keyword argument.

Decompress.flush([length])

未処理の入力データをすべて処理し、最終的に圧縮されなかった残りの出力バイト列オブジェクトを返します。flush() を呼んだ後、decompress() を再度呼ぶべきではありません。このときできる唯一の現実的な操作はオブジェクトの削除だけです。

オプション引数 length には出力バッファの初期サイズを指定します。

Decompress.copy()

展開オブジェクトのコピーを返します。これを使うとデータストリームの途中にある展開オブジェクトの状態を保存でき、未来のある時点で行なわれるストリームのランダムなシークをスピードアップするのに利用できます。

バージョン 3.8 で変更: Added copy.copy() and copy.deepcopy() support to decompression objects.

使用している zlib ライブラリのバージョン情報を以下の定数で確認できます:

zlib.ZLIB_VERSION

モジュールのビルド時に使用された zlib ライブラリのバージョン文字列です。これは ZLIB_RUNTIME_VERSION で確認できる、実行時に使用している実際の zlib ライブラリのバージョンとは異なる場合があります。

zlib.ZLIB_RUNTIME_VERSION

インタプリタが読み込んだ実際の zlib ライブラリのバージョン文字列です。

Added in version 3.3.

参考

gzip モジュール

gzip 形式ファイルへの読み書きを行うモジュール。

http://www.zlib.net

zlib ライブラリホームページ。

http://www.zlib.net/manual.html

zlib ライブラリの多くの関数の意味と使い方を解説したマニュアル。

gzip --- Support for gzip files

ソースコード: Lib/gzip.py [https://github.com/python/cpython/tree/3.12/Lib/gzip.py]

このモジュールは、GNU の gzip や gunzip のようにファイルを圧縮、展開するシンプルなインターフェイスを提供しています。

データ圧縮は zlib モジュールで提供されています。

gzip は GzipFile クラスと、簡易関数 open()、compress()、および decompress() を提供しています。GzipFile クラスは通常の ファイルオブジェクト と同様に gzip 形式のファイルを読み書きし、データを自動的に圧縮または展開します。

compress や pack 等によって作成され、gzip や gunzip が展開できる他のファイル形式についてはこのモジュールは対応していないので注意してください。

このモジュールは以下の項目を定義しています:

gzip.open(filename, mode='rb', compresslevel=9, encoding=None, errors=None, newline=None)

gzip 圧縮ファイルをバイナリまたはテキストモードで開き、ファイルオブジェクト を返します。

引数 filename には実際のファイル名 (str または bytes オブジェクト) か、既存のファイルオブジェクトを指定します。

引数 mode には、バイナリモード用に 'r'、'rb'、'a'、'ab'、'w'、'wb'、'x'、または 'xb'、テキストモード用に 'rt'、'at'、'wt'、または 'xt' を指定できます。デフォルトは 'rb' です。

引数 compresslevel は GzipFile コンストラクタと同様に 0 から 9 の整数を取ります。

バイナリモードでは、この関数は GzipFile コンストラクタ GzipFile(filename, mode, compresslevel) と等価です。この時、引数 encoding、errors、および newline を指定してはいけません。

テキストモードでは、GzipFile オブジェクトが作成され、指定されたエンコーディング、エラーハンドラの挙動、および改行文字で io.TextIOWrapper インスタンスにラップされます。

バージョン 3.3 で変更: filename にファイルオブジェクト指定のサポート、テキストモードのサポート、および引数に encoding、errors、および newline を追加しました。

バージョン 3.4 で変更: Added support for the 'x', 'xb' and 'xt' modes.

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

exception gzip.BadGzipFile

An exception raised for invalid gzip files. It inherits from OSError. EOFError and zlib.error can also be raised for invalid gzip files.

Added in version 3.8.

class gzip.GzipFile(filename=None, mode=None, compresslevel=9, fileobj=None, mtime=None)

Constructor for the GzipFile class, which simulates most of the methods of a file object, with the exception of the truncate() method. At least one of fileobj and filename must be given a non-trivial value.

クラスの新しいインスタンスは、 fileobj に基づいて作成されます。 fileobj は通常のファイル、 io.BytesIO オブジェクト、 そしてその他ファイルをシミュレートできるオブジェクトでかまいません。 値はデフォルトでは None で、その場合ファイルオブジェクトを生成するために filename を開きます。

fileobj が None でない場合、filename 引数は gzip ファイルヘッダにインクルードされることのみに使用されます。gzip ファイルヘッダは圧縮されていないファイルの元の名前をインクルードするかもしれません。認識可能な場合、規定値は fileobj のファイル名です。そうでない場合、規定値は空の文字列で、元のファイル名はヘッダにはインクルードされません。

The mode argument can be any of 'r', 'rb', 'a', 'ab', 'w', 'wb', 'x', or 'xb', depending on whether the file will be read or written. The default is the mode of fileobj if discernible; otherwise, the default is 'rb'. In future Python releases the mode of fileobj will not be used. It is better to always specify mode for writing.

ファイルは常にバイナリモードで開かれることに注意してください。圧縮ファイルをテキストモードで開く場合、open() (または GzipFile を io.TextIOWrapper でラップしたオブジェクト) を使ってください。

引数 compresslevel は 0 から 9 の整数を取り、圧縮レベルを制御します; 1 は最も高速で最小限の圧縮を行い、9 は最も低速ですが最大限の圧縮を行います。0 は圧縮しません。デフォルトは 9 です。

The mtime argument is an optional numeric timestamp to be written to the last modification time field in the stream when compressing. It should only be provided in compression mode. If omitted or None, the current time is used. See the mtime attribute for more details.

Calling a GzipFile object's 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 io.BytesIO object opened for writing as fileobj, and retrieve the resulting memory buffer using the io.BytesIO object's getvalue() method.

GzipFile supports the io.BufferedIOBase interface, including iteration and the with statement. Only the truncate() method isn't implemented.

GzipFile は以下のメソッドと属性も提供しています:

peek(n)

ファイル内の位置を移動せずに展開した n バイトを読み込みます。呼び出し要求を満たすために、圧縮ストリームに対して最大 1 回の単一読み込みが行われます。返されるバイト数はほぼ要求した値になります。

注釈

peek() の呼び出しでは GzipFile のファイル位置は変わりませんが、下層のファイルオブジェクトの位置が変わる惧れがあります。(e.g. GzipFile が fileobj 引数で作成された場合)

Added in version 3.2.

mtime

When decompressing, the value of the last modification time field in the most recently read header may be read from this attribute, as an integer. The initial value before reading any headers is None.

All gzip compressed streams are required to contain this timestamp field. Some programs, such as gunzip, make use of the timestamp. The format is the same as the return value of time.time() and the st_mtime attribute of the object returned by os.stat().

name

The path to the gzip file on disk, as a str or bytes. Equivalent to the output of os.fspath() on the original input path, with no other normalization, resolution or expansion.

バージョン 3.1 で変更: with 文がサポートされました。mtime コンストラクタ引数と mtime 属性が追加されました。

バージョン 3.2 で変更: ゼロパディングされたファイルやシーク出来ないファイルがサポートされました。

バージョン 3.3 で変更: io.BufferedIOBase.read1() メソッドを実装しました。

バージョン 3.4 で変更: 'x' ならびに 'xb' モードがサポートされました。

バージョン 3.5 で変更: 任意の バイトライクオブジェクト の書き込みがサポートされました。 read() メソッドが None を引数として受け取るようになりました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

バージョン 3.12 で変更: Remove the filename attribute, use the name attribute instead.

バージョン 3.9 で非推奨: Opening GzipFile for writing without specifying the mode argument is deprecated.

gzip.compress(data, compresslevel=9, *, mtime=None)

Compress the data, returning a bytes object containing the compressed data. compresslevel and mtime have the same meaning as in the GzipFile constructor above. When mtime is set to 0, this function is equivalent to zlib.compress() with wbits set to 31. The zlib function is faster.

Added in version 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 0 are delegated to zlib.compress() for better speed.

gzip.decompress(data)

Decompress the data, returning a 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 zlib.decompress() function with wbits set to 31 is faster.

Added in version 3.2.

バージョン 3.11 で変更: Speed is improved by decompressing members at once in memory instead of in a streamed fashion.

使い方の例

圧縮されたファイルを読み込む例:

import gzip
with gzip.open('/home/joe/file.txt.gz', 'rb') as f:
    file_content = f.read()

GZIP 圧縮されたファイルを作成する例:

import gzip
content = b"Lots of content here"
with gzip.open('/home/joe/file.txt.gz', 'wb') as f:
    f.write(content)

既存のファイルを GZIP 圧縮する例:

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)

バイナリ文字列を GZIP 圧縮する例:

import gzip
s_in = b"Lots of content here"
s_out = gzip.compress(s_in)

参考

zlib モジュール

gzip ファイル形式のサポートを行うために必要な基本ライブラリモジュール。

コマンドラインインターフェイス

gzip モジュールは、 ファイルを圧縮、展開するための簡単なコマンドラインインターフェースを提供しています。

Once executed the 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.

コマンドラインオプション

file

If file is not specified, read from sys.stdin.

--fast

Indicates the fastest compression method (less compression).

--best

Indicates the slowest compression method (best compression).

-d, --decompress

Decompress the given file.

-h, --help

ヘルプメッセージを出力します

bz2 --- Support for bzip2 compression

ソースコード: Lib/bz2.py [https://github.com/python/cpython/tree/3.12/Lib/bz2.py]

このモジュールは、bzip2 アルゴリズムを用いて圧縮・展開を行う包括的なインターフェイスを提供します。

bz2 モジュールには以下のクラスや関数があります:

圧縮ファイルを読み書きするための open() 関数と BZ2File クラス。

インクリメンタルにデータを圧縮・展開するための BZ2Compressor および BZ2Decompressor クラス。

一度に圧縮・展開を行う compress() および decompress() 関数。

ファイルの圧縮/解凍

bz2.open(filename, mode='rb', compresslevel=9, encoding=None, errors=None, newline=None)

bzip2 圧縮されたファイルを、バイナリモードかテキストモードでオープンし、ファイルオブジェクト を返します。

BZ2File のコンストラクタと同様に、引数 filename には実際のファイル名 (str または bytes オブジェクト) か、読み書きする既存のファイルオブジェクトを指定します。

引数 mode には、バイナリモード用に 'r'、'rb'、'w'、'wb'、'x'、'xb'、'a'、あるいは 'ab'、テキストモード用に 'rt'、'wt'、'xt'、あるいは 'at' を指定できます。デフォルトは 'rb' です。

引数 compresslevel には BZ2File コンストラクタと同様に 1 から 9 の整数を指定します。

バイナリモードでは、この関数は BZ2File コンストラクタ BZ2File(filename, mode, compresslevel=compresslevel) と等価です。この時、引数 encoding、errors、および newline を指定してはいけません。

テキストモードでは、BZ2File オブジェクトが作成され、指定されたエンコーディング、エラーハンドラの挙動、および改行文字で io.TextIOWrapper にラップされます。

Added in version 3.3.

バージョン 3.4 で変更: 'x' (排他的作成) モードが追加されました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

class bz2.BZ2File(filename, mode='r', *, compresslevel=9)

bzip2 圧縮ファイルをバイナリモードでオープンします。

filename が str あるいは bytes オブジェクトの場合、それを名前とするファイルを直接開きます。そうでない場合、filename は圧縮データを読み書きする ファイルオブジェクト でなくてはなりません。

引数 mode は読み込みモードの 'r' (デフォルト)、上書きモードの 'w'、排他的作成モードの 'x'、あるいは追記モードの 'a' のいずれかを指定できます。これらはそれぞれ 'rb'、'wb'、'xb' および 'ab' と等価です。

filename が (実際のファイル名でなく) ファイルオブジェクトの場合、'w' はファイルを上書きせず、'a' と等価になります。

mode が 'w' あるいは 'a' の場合、compresslevel に圧縮レベルを 1 から 9 の整数で指定できます。圧縮率は 1 が最低で、9 (デフォルト値) が最高です。

mode の値が 'r' の場合、入力ファイルは複数の圧縮ストリームでも構いません。

BZ2File には、 io.BufferedIOBase で規定されているメソッドや属性のうち、 detach() と truncate() を除くすべてが備わっています。イテレーションと with 文をサポートしています。

BZ2File also provides the following methods:

peek([n])

ファイル上の現在位置を変更せずにバッファのデータを返します。このメソッドは少なくとも 1 バイトのデータを返します (EOF の場合を除く)。返される正確なバイト数は規定されていません。

注釈

peek() の呼び出しでは BZ2File のファイル位置は変わりませんが、下層のファイルオブジェクトの位置が変わる惧れがあります(e.g. BZ2File を filename にファイルオブジェクトを渡して作成した場合)。

Added in version 3.3.

fileno()

Return the file descriptor for the underlying file.

Added in version 3.3.

readable()

Return whether the file was opened for reading.

Added in version 3.3.

seekable()

Return whether the file supports seeking.

Added in version 3.3.

writable()

Return whether the file was opened for writing.

Added in version 3.3.

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 b'' if the file is at EOF.

Added in version 3.3.

readinto(b)

Read bytes into b.

Returns the number of bytes read (0 for EOF).

Added in version 3.3.

バージョン 3.1 で変更: with 構文のサポートが追加されました。

バージョン 3.3 で変更: filename が実際のファイル名でなく ファイルオブジェクト だった場合のサポートが追加されました。

'a' (追記) モードが追加され、複数のストリームの読み込みがサポートされました。

バージョン 3.4 で変更: 'x' (排他的作成) モードが追加されました。

バージョン 3.5 で変更: read() メソッドが None を引数として受け取るようになりました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

バージョン 3.9 で変更: buffering パラメータは削除されました。 Python 3.0 からは無視され非推奨となっています。開かれたファイルオブジェクトを渡し、ファイルの開きかたを制御します。

compresslevel パラメータはキーワード専用になりました。

バージョン 3.10 で変更: このクラスは、複数の同時読み出しや書き込みにおいては、既存の gzip や lzma などの同等のクラスのように、スレッド安全ではありません。

逐次圧縮および展開

class bz2.BZ2Compressor(compresslevel=9)

新しくコンプレッサオブジェクトを作成します。このオブジェクトはデータの逐次的な圧縮に使用できます。一度に圧縮したい場合は、compress() 関数を使ってください。

引数 compresslevel を指定する場合は、1 から 9 までの整数を与えてください。デフォルト値は 9 です。

compress(data)

データをコンプレッサオブジェクトに渡します。戻り値は圧縮されたデータですが、圧縮データを返すことができない場合は空のバイト文字列を返します。

コンプレッサオブジェクトにデータをすべて渡し終えたら、flush() メソッドを呼び出し、圧縮プロセスを完了させてください。

flush()

圧縮プロセスを完了させ、内部バッファに残っている圧縮済みデータを返します。

このメソッドを呼び出すと、それ以後コンプレッサオブジェクトは使用できなくなります。

class bz2.BZ2Decompressor

新しくデコンプレッサオブジェクトを作成します。このオブジェクトは逐次的なデータ展開に使用できます。一度に展開したい場合は、decompress() 関数を使ってください。

注釈

このクラスは、decompress() や BZ2File とは異なり、複数の圧縮レベルが混在しているデータを透過的に扱うことができません。 BZ2Decompressor クラスを用いて、複数のストリームからなるデータを展開する場合は、それぞれのストリームについてデコンプレッサオブジェクトを用意してください。

decompress(data, max_length=-1)

data (bytes-like object) を展開し、未圧縮のデータを bytes で返します。 data の一部は、後で decompress() の呼び出しに使用するため内部でバッファされている場合があります。返されたデータは、以前の decompress() の呼び出しの出力に連結する必要があります。

max_length が非負の場合、最大 max_length バイトの展開データを返します。この制限に達して、出力がさらに生成できる場合、 needs_input が False に設定されます。この場合、 decompress() を次に呼び出すと、data を b'' として提供し、出力をさらに取得することができます。

入力データの全てが圧縮され返された (max_length バイトより少ないためか max_length が負のため) 場合、 needs_input 属性は True になります。

ストリームの終端に到達した後にデータを展開しようとすると EOFError が送出されます。ストリームの終端の後ろの全てのデータは無視され、その部分は unused_data 属性に保存されます。

バージョン 3.5 で変更: max_length パラメータが追加されました。

eof

ストリーム終端記号に到達した場合 True を返します。

Added in version 3.3.

unused_data

圧縮ストリームの末尾以降に存在したデータを表します。

ストリームの末尾に達する前には、この属性には b'' という値が収められています。

needs_input

decompress() メソッドが、新しい非圧縮入力を必要とせずにさらに展開データを提供できる場合、 False です。

Added in version 3.5.

一括圧縮/解凍

bz2.compress(data, compresslevel=9)

バイト類オブジェクト の data を圧縮します。

引数 compresslevel を指定する場合は、1 から 9 までの整数を与えてください。デフォルト値は 9 です。

逐次的にデータを圧縮したい場合は、BZ2Compressor を使ってください。

bz2.decompress(data)

バイト類オブジェクト の data を展開します。

data が複数の圧縮ストリームから成る場合、そのすべてを展開します。

逐次的に展開を行う場合は、BZ2Decompressor を使ってください。

バージョン 3.3 で変更: 複数ストリームの入力をサポートしました。

使い方の例

以下は、典型的な bz2 モジュールの利用方法です。

compress() と decompress() を使い、圧縮して展開する実演をしています:

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

BZ2Compressor を使い、逐次圧縮をしています:

>>> 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()

上の例は、非常に "ランダムでない" データストリーム (チャンク b"z" のストリーム) です。ランダムなデータは圧縮率が低い傾向にある一方、揃っていて、繰り返しのあるデータは通常は高い圧縮率を叩き出します。

bzip2 圧縮されたファイルをバイナリモードで読み書きしています:

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

lzma --- Compression using the LZMA algorithm

Added in version 3.3.

ソースコード: Lib/lzma.py [https://github.com/python/cpython/tree/3.12/Lib/lzma.py]

このモジュールは LZMA 圧縮アルゴリズムを使用したデータ圧縮および展開のためのクラスや便利な関数を提供しています。また、xz ユーティリティを使用した .xz およびレガシーな .lzma ファイル形式へのファイルインターフェイスの他、RAW 圧縮ストリームもサポートしています。

このモジュールが提供するインターフェイスは bz2 モジュールと非常によく似ています。 LZMAFile と bz2.BZ2File はスレッドセーフでは ない 点に注意してください。そのため、単一の LZMAFile インスタンスを複数スレッドから使用する場合は、ロックで保護する必要があります。

exception lzma.LZMAError

この例外は圧縮あるいは展開中にエラーが発生した場合、または圧縮/展開状態の初期化中に送出されます。

圧縮ファイルへの読み書き

lzma.open(filename, mode='rb', *, format=None, check=-1, preset=None, filters=None, encoding=None, errors=None, newline=None)

LZMA 圧縮ファイルをバイナリまたはテキストモードでオープンし、ファイルオブジェクト を返します。

filename 引数には、ファイルをオープンする際には実際のファイル名 (str、 bytes、または path-like オブジェクトとして指定します)か、読み込みまたは書き込むためであれば、すでに存在するファイルオブジェクトを指定できます。

引数 mode は、バイナリモードでは "r"、"rb"、"w"、"wb"、"x"、"xb"、"a"、あるいは "ab" の、テキストモードでは "rt"、"wt"、"xt"、あるいは "at" のいずれかになります。デフォルトは "rb" です。

読み込み用にファイルをオープンした場合、引数 format および filters は LZMADecompressor と同じ意味になります。この時、引数 check および preset は使用しないでください。

書き出し用にオープンした場合、引数 format、check、preset、および filters は LZMACompressor と同じ意味になります。

バイナリモードでは、この関数は LZMAFile コンストラクタと等価になります (LZMAFile(filename, mode, ...))。この場合、引数 encoding、errors、および newline を指定しなければなりません。

テキストモードでは、LZMAFile オブジェクトが生成され、指定したエンコーディング、エラーハンドラの挙動、および改行コードで io.TextIOWrapper にラップされます。

バージョン 3.4 で変更: "x", "xb", "xt" モードのサポートが追加されました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

class lzma.LZMAFile(filename=None, mode='r', *, format=None, check=-1, preset=None, filters=None)

LZMA 圧縮ファイルをバイナリモードで開きます。

LZMAFile はすでにオープンしている file object をラップ、または名前付きファイルを直接操作できます。引数 filename にはラップするファイルオブジェクトかオープンするファイル名 (str オブジェクトま、bytes オブジェクト、または path-like オブジェクト) を指定します。既存のファイルオブジェクトをラップした場合、LZMAFile をクローズしてもラップしたファイルはクローズされません。

引数 mode は読み込みモードの "r" (デフォルト)、上書きモードの "w"、排他的生成モードの "x"、あるいは追記モードの "a" のいずれかを指定できます。これらはそれぞれ "rb"、"wb"、"xb"、および "ab" と等価です。

filename が (実際のファイル名でなく) ファイルオブジェクトの場合、"w" モードはファイルを上書きせず、"a" と等価になります。

読み込みモードでファイルをオープンした時、入力ファイルは複数に分割された圧縮ストリームを連結したものでもかまいません。これらは透過的に単一論理ストリームとしてデコードされます。

読み込み用にファイルをオープンした場合、引数 format および filters は LZMADecompressor と同じ意味になります。この時、引数 check および preset は使用しないでください。

書き出し用にオープンした場合、引数 format、check、preset、および filters は LZMACompressor と同じ意味になります。

LZMAFile supports all the members specified by io.BufferedIOBase, except for detach() and truncate(). Iteration and the with statement are supported.

The following method is also provided:

peek(size=-1)

ファイル上の現在位置を変更せずにバッファのデータを返します。EOF に達しない限り、少なくとも 1 バイトが返されます。返される正確なバイト数は規定されていません (引数 size は無視されます)。

注釈

peek() の呼び出しでは LZMAFile のファイル位置は変わりませんが、下層のファイルオブジェクトの位置が変わる惧れがあります。(e.g. LZMAFile を filename にファイルオブジェクトを渡して作成した場合)

バージョン 3.4 で変更: 'x', 'xb' モードがサポートが追加されました。

バージョン 3.5 で変更: read() メソッドが None を引数として受け取るようになりました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

メモリ上での圧縮と展開

class lzma.LZMACompressor(format=FORMAT_XZ, check=-1, preset=None, filters=None)

データをインクリメンタルに圧縮する圧縮オブジェクトを作成します。

大量の単一データを圧縮する、より便利な方法については compress() を参照してください。

引数 format には使用するコンテナフォーマットを指定します。以下の値が指定できます:

FORMAT_XZ: The .xz コンテナフォーマット。

デフォルトのフォーマットです。

FORMAT_ALONE: レガシーな .lzma コンテナフォーマット。

このフォーマットは .xz より制限があります -- インテグリティチェックや複数フィルタをサポートしていません。

FORMAT_RAW: 特定のコンテナフォーマットを使わない、生のデータストリーム。

このフォーマット指定子はインテグリティチェックをサポートしておらず、(圧縮および展開双方のために) 常にカスタムフィルタチェインを指定する必要があります。さらに、この方法で圧縮されたデータは FORMAT_AUTO を使っても展開できません (LZMADecompressor を参照)。

引数 check には圧縮データに組み込むインテグリティチェックのタイプを指定します。このチェックは展開時に使用され、データが破損していないことを保証します。以下の値が指定できます:

CHECK_NONE: インテグリティチェックなし。FORMAT_ALONE および FORMAT_RAW のデフォルト (かつ唯一指定可能な値) です。

CHECK_CRC32: 32-bit 巡回冗長検査。

CHECK_CRC64: 64-bit 巡回冗長検査。FORMAT_XZ のデフォルトです。

CHECK_SHA256: 256-bit セキュアハッシュアルゴリズム (SHA)。

指定したチェック方法がサポートされていない場合、LZMAError が送出されます。

圧縮設定はプリセット圧縮レベル (引数 preset で指定) またはカスタムフィルタチェイン (引数 filters で指定) のどちらかを指定します。

引数 preset を指定する場合、0 から 9 までの整数値でなければならず、オプションで定数 PRESET_EXTREME を論理和指定できます。preset も filters も指定されなかった場合、デフォルトの挙動として PRESET_DEFAULT (プリセットレベル 6) が使用されます。高いプリセット値を指定すると圧縮率が上がりますが、圧縮にかかる時間が長くなります。

注釈

CPU の使用量が多いのに加えて、高いプリセットで圧縮を行うには、メモリをずっと多く必要とします (さらに、生成される出力も展開により多くのメモリを必要とします)。例えば、プリセットが 9 の場合、LZMACompressor オブジェクトのオーバーヘッドは 800 MiB にまで高くなる場合があります。このため、通常はデフォルトのプリセットを使用するのがよいでしょう。

引数 filters を指定する場合、フィルタチェイン指定子でなければなりません。詳しくは カスタムフィルタチェインの指定 を参照してください。

compress(data)

data (bytes オブジェクト) を圧縮し、少なくともその一部が圧縮されたデータを格納する bytes オブジェクトを返します。data の一部は、後で compress() および flush() の呼び出しに使用するため内部でバッファされている場合があります。返すデータは以前の compress() 呼び出しの出力を連結したものです。

flush()

圧縮処理を終了し、コンプレッサの内部バッファにあるあらゆるデータを格納する bytes オブジェクトを返します。

コンプレッサはこのメソッドが呼び出された後は使用できません。

class lzma.LZMADecompressor(format=FORMAT_AUTO, memlimit=None, filters=None)

データをインクリメンタルに展開するために使用できる展開オブジェクトを作成します。

圧縮されたストリーム全体を一度に展開にする、より便利な方法については、decompress() を参照してください。

引数 format には使用するコンテナフォーマットを指定します。デフォルトは FORMAT_AUTO で、.xz および .lzma ファイルを展開できます。その他に指定できる値は、FORMAT_XZ、FORMAT_ALONE、および FORMAT_RAW です。

引数 memlimit にはデコンプレッサが使用できるメモリ量をバイトで指定します。この引数を指定した場合、そのメモリ量で展開ができないと LZMAError を送出します。

引数 filters には展開されるストリームの作成に使用するフィルタチェインを指定します。この引数を使用する際は、引数 format に FORMAT_RAW を指定しなければなりません。フィルタチェインについての詳細は カスタムフィルタチェインの指定 を参照してください。

注釈

このクラスは decompress() および LZMAFile と異なり、複数の圧縮ストリームを含む入力を透過的に扱いません。 LZMADecompressor で複数ストリーム入力を展開するには、各ストリームごとに新しいデコンプレッサを作成しなければなりません。

decompress(data, max_length=-1)

data (bytes-like object) を展開し、未圧縮のデータを bytes で返します。 data の一部は、後で decompress() の呼び出しに使用するため内部でバッファされている場合があります。返されたデータは、以前の decompress() の呼び出しの出力に連結する必要があります。

max_length が非負の場合、最大 max_length バイトの展開データを返します。この制限に達して、出力がさらに生成できる場合、 needs_input が False に設定されます。この場合、 decompress() を次に呼び出すと、data を b'' として提供し、出力をさらに取得することができます。

入力データの全てが圧縮され返された (max_length バイトより少ないためか max_length が負のため) 場合、 needs_input 属性は True になります。

ストリームの終端に到達した後にデータを展開しようとすると EOFError が送出されます。ストリームの終端の後ろの全てのデータは無視され、その部分は unused_data 属性に保存されます。

バージョン 3.5 で変更: max_length パラメータが追加されました。

check

入力ストリームに使用されるインテグリティチェックの ID です。これは何のインテグリティチェックが使用されているか決定するために十分な入力がデコードされるまでは CHECK_UNKNOWN になることがあります。

eof

ストリーム終端記号に到達した場合 True を返します。

unused_data

圧縮ストリームの末尾以降に存在したデータを表します。

ストリームの末尾に達する前は、これは b"" になります。

needs_input

decompress() メソッドが、新しい非圧縮入力を必要とせずにさらに展開データを提供できる場合、 False です。

Added in version 3.5.

lzma.compress(data, format=FORMAT_XZ, check=-1, preset=None, filters=None)

data (bytes オブジェクト) を圧縮し、圧縮データを bytes オブジェクトとして返します。

引数 format、check、preset、および filters についての説明は上記の LZMACompressor を参照してください。

lzma.decompress(data, format=FORMAT_AUTO, memlimit=None, filters=None)

data (bytes オブジェクト) を展開し、展開データを bytes オブジェクトとして返します。

data が複数の明確な圧縮ストリームの連結だった場合、すべてのストリームを展開し、結果の連結を返します。

引数 format、memlimit、および filters の説明は、上記 LZMADecompressor を参照してください。

その他

lzma.is_check_supported(check)

指定したインテグリティチェックがシステムでサポートされていれば True を返します。

CHECK_NONE および CHECK_CRC32 は常にサポートされています。CHECK_CRC64 および CHECK_SHA256 は liblzma が機能制限セットでコンパイルされている場合利用できないことがあります。

カスタムフィルタチェインの指定

フィルタチェイン指定子は、辞書のシーケンスで、各辞書は ID と単一フィルタのオプションからなります。各辞書はキー "id" を持たなければならず、フィルタ依存のオプションを指定する追加キーを持つ場合もあります。有効なフィルタ ID は以下のとおりです:

圧縮フィルタ:

FILTER_LZMA1 (FORMAT_ALONE と共に使用)

FILTER_LZMA2 (FORMAT_XZ および FORMAT_RAW と共に使用)

デルタフィルター:

FILTER_DELTA

ブランチコールジャンプ (BCJ) フィルター:

FILTER_X86

FILTER_IA64

FILTER_ARM

FILTER_ARMTHUMB

FILTER_POWERPC

FILTER_SPARC

一つのフィルタチェインは 4 個までのフィルタを定義することができ、空にはできません。チェインの最後は圧縮フィルタでなくてはならず、その他のフィルタはデルタまたは BCJ フィルタでなければなりません。

圧縮フィルタは以下のオプション (追加エントリとしてフィルタを表す辞書に指定) をサポートしています:

preset: 明示されていないオプションのデフォルト値のソースとして使用する圧縮プリセット。

dict_size: 辞書のサイズのバイト数。これは、 4 KiB から 1.5 GiB の間にしてください (両端を含みます)。

lc: リテラルコンテキストビットの数。

lp: リテラル位置ビットの数。lc + lp で最大 4 までです。

pb: 位置ビットの数。最大で 4 までです。

mode: MODE_FAST または MODE_NORMAL。

nice_len: マッチに "良い" とみなす長さ。273 以下でなければなりません。

mf: 使用するマッチファインダ -- MF_HC3、MF_HC4、MF_BT2、MF_BT3、または MF_BT4。

depth: マッチファインダが使用する検索の最大深度。0 (デフォルト) では他のフィルタオプションをベースに自動選択します。

デルタフィルターは、バイト間の差異を保存し、特定の状況で、コンプレッサーに対してさらに反復的な入力を生成します。デルタフィルターは、1 つのオプション dist のみをサポートします。これは差し引くバイトどうしの距離を示します。デフォルトは 1 で、隣接するバイトの差異を扱います。

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, start_offset. This specifies the address that should be mapped to the beginning of the input data. The default is 0.

使用例

圧縮ファイルからの読み込み:

import lzma
with lzma.open("file.xz") as f:
    file_content = f.read()

圧縮ファイルの作成:

import lzma
data = b"Insert Data Here"
with lzma.open("file.xz", "w") as f:
    f.write(data)

メモリ上でデータを圧縮:

import lzma
data_in = b"Insert Data Here"
data_out = lzma.compress(data_in)

逐次圧縮:

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])

すでにオープンしているファイルへの圧縮データの書き出し:

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")

カスタムフィルタチェインを使った圧縮ファイルの作成:

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")

zipfile --- Work with ZIP archives

Source code: Lib/zipfile/ [https://github.com/python/cpython/tree/3.12/Lib/zipfile/]

ZIP は一般によく知られているアーカイブ (書庫化) および圧縮の標準ファイルフォーマットです。このモジュールでは ZIP 形式のファイルの作成、読み書き、追記、書庫内のファイル一覧の作成を行うためのツールを提供します。より高度な使い方でこのモジュールを利用したいのであれば、 PKZIP Application Note [https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT] に定義されている ZIP ファイルフォーマットの理解が必要になるでしょう。

このモジュールは現在マルチディスク ZIP ファイルを扱うことはできません。ZIP64 拡張を利用する ZIP ファイル (サイズが 4 GiB を超えるような ZIP ファイル) は扱えます。このモジュールは暗号化されたアーカイブの復号をサポートしますが、現在暗号化ファイルを作成することはできません。C 言語ではなく、Python で実装されているため、復号は非常に遅くなっています。

このモジュールは以下の項目を定義しています:

exception zipfile.BadZipFile

正常ではない ZIP ファイルに対して送出されるエラーです。

Added in version 3.2.

exception zipfile.BadZipfile

BadZipFile の別名です。過去のバージョンの Python との互換性のために用意されています。

バージョン 3.2 で非推奨.

exception zipfile.LargeZipFile

ZIP ファイルが ZIP64 の機能を必要としているが、その機能が有効化されていない場合に送出されるエラーです。

class zipfile.ZipFile

ZIP ファイルの読み書きのためのクラスです。コンストラクタの詳細については、ZipFile オブジェクト 節を参照してください。

class zipfile.Path

pathlib.Path インターフェースの一部を実装したクラスです。 importlib.resources.abc.Traversable インターフェースは完全に実装しています。

Added in version 3.8.

class zipfile.PyZipFile

Python ライブラリを含む、ZIP アーカイブを作成するためのクラスです。

class zipfile.ZipInfo(filename='NoName', date_time=(1980, 1, 1, 0, 0, 0))

アーカイブ内の 1 個のメンバの情報を取得するために使うクラスです。このクラスのインスタンスは ZipFile オブジェクトの getinfo() および infolist() メソッドによって返されます。ほとんどの zipfile モジュールの利用者はこのクラスのインスタンスを作成する必要はなく、このモジュールによって作成されたものを使用できます。filename はアーカイブメンバのフルネームでなければならず、date_time はファイルが最後に変更された日時を表す 6 個のフィールドのタプルでなければなりません; フィールドは ZipInfo オブジェクト 節で説明されています。

zipfile.is_zipfile(filename)

filename が正しいマジックナンバをもつ ZIP ファイルの時に True を返し、そうでない場合 False を返します。filename にはファイルやファイルライクオブジェクトを渡すこともできます。

バージョン 3.1 で変更: ファイルおよびファイルライクオブジェクトをサポートしました。

zipfile.ZIP_STORED

アーカイブメンバを圧縮しない (複数ファイルを一つにまとめるだけ) ことを表す数値定数です。

zipfile.ZIP_DEFLATED

通常の ZIP 圧縮方法を表す数値定数です。これには zlib モジュールが必要です。

zipfile.ZIP_BZIP2

BZIP2 圧縮方法を表す数値定数です。これには bz2 モジュールが必要です。

Added in version 3.3.

zipfile.ZIP_LZMA

LZMA 圧縮方法を表す数値定数です。これには lzma モジュールが必要です。

Added in version 3.3.

注釈

ZIP ファイルフォーマット仕様は 2001 年より bzip2 圧縮を、2006 年より LZMA 圧縮をサポートしていますが、(過去の Python リリースを含む) 一部のツールはこれら圧縮方式をサポートしていないため、ZIP ファイルの処理を全く受け付けないか、あるいは個々のファイルの抽出に失敗する場合があります。

参考

PKZIP Application Note [https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT]

ZIP ファイルフォーマットおよびアルゴリズムを作成した Phil Katz によるドキュメント。

Info-ZIP Home Page [https://infozip.sourceforge.net/]

Info-ZIP プロジェクトによる ZIP アーカイブプログラムおよびプログラム開発ライブラリに関する情報。

ZipFile オブジェクト

class zipfile.ZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, compresslevel=None, *, strict_timestamps=True, metadata_encoding=None)

ZIP ファイルを開きます。 file はファイルのパス (文字列) か、ファイルライクオブジェクト、 path-like object のいずれかです。

mode パラメータには、既存のファイルを読み込む場合は 'r' 、内容を消去して新しいファイルに書き込む場合は 'w' 、既存のファイルの末尾に追加する場合は 'a' 、ファイルが存在しない場合にのみファイルを作成して書き込む場合は 'x' を指定します。 mode が 'x' で file が既存のファイルを指している場合、 FileExistsError が発生します。 mode が 'a' で file が既存の ZIP ファイルを指している場合、新しい ZIP アーカイブがそのファイルに追加されます。 file が ZIP ファイルでない場合は、ファイルの末尾にあたらしい ZIP アーカイブが追加されます。これは、既存のファイル (例えば python.exe) に ZIP アーカイブを付け加える用途を想定したものです。 mode が 'a' で file が存在しない場合は、ファイルが作成されます。 mode が 'r' か 'a' の場合、ファイルはシーク可能である必要があります。

compression is the ZIP compression method to use when writing the archive, and should be ZIP_STORED, ZIP_DEFLATED, ZIP_BZIP2 or ZIP_LZMA; unrecognized values will cause NotImplementedError to be raised. If ZIP_DEFLATED, ZIP_BZIP2 or ZIP_LZMA is specified but the corresponding module (zlib, bz2 or lzma) is not available, RuntimeError is raised. The default is ZIP_STORED.

If allowZip64 is True (the default) zipfile will create ZIP files that use the ZIP64 extensions when the zipfile is larger than 4 GiB. If it is false zipfile will raise an exception when the ZIP file would require ZIP64 extensions.

The compresslevel parameter controls the compression level to use when writing files to the archive. When using ZIP_STORED or ZIP_LZMA it has no effect. When using ZIP_DEFLATED integers 0 through 9 are accepted (see zlib for more information). When using ZIP_BZIP2 integers 1 through 9 are accepted (see bz2 for more information).

The strict_timestamps argument, when set to False, allows to zip files older than 1980-01-01 at the cost of setting the timestamp to 1980-01-01. Similar behavior occurs with files newer than 2107-12-31, the timestamp is also set to the limit.

When mode is 'r', metadata_encoding may be set to the name of a codec, which will be used to decode metadata such as the names of members and ZIP comments.

ファイルがモード 'w'、 'x' または 'a' で作成され、その後そのアーカイブにファイルを追加することなく クローズ された場合、空のアーカイブのための適切な ZIP 構造がファイルに書き込まれます。

ZipFile はコンテキストマネージャにもなっているので、with 文をサポートしています。次の例では、myzip は with 文のブロックが終了したときに、(たとえ例外が発生したとしても) クローズされます:

with ZipFile('spam.zip', 'w') as myzip:
    myzip.write('eggs.txt')

注釈

metadata_encoding is an instance-wide setting for the ZipFile. It is not currently possible to set this on a per-member basis.

This attribute is a workaround for legacy implementations which produce archives with names in the current locale encoding or code page (mostly on Windows). According to the .ZIP standard, the encoding of metadata may be specified to be either IBM code page (default) or UTF-8 by a flag in the archive header. That flag takes precedence over metadata_encoding, which is a Python-specific extension.

バージョン 3.2 で変更: ZipFile をコンテキストマネージャとして使用できるようになりました。

バージョン 3.3 で変更: bzip2 および lzma 圧縮をサポートしました。

バージョン 3.4 で変更: ZIP64 拡張がデフォルトで有効になりました。

バージョン 3.5 で変更: seek 出来ないストリームのサポートが追加されました。'x' モードのサポートが追加されました。

バージョン 3.6 で変更: Previously, a plain RuntimeError was raised for unrecognized compression values.

バージョン 3.6.2 で変更: file 引数が path-like object を受け入れるようになりました。

バージョン 3.7 で変更: compresslevel パラメータが追加されました。

バージョン 3.8 で変更: The strict_timestamps keyword-only parameter.

バージョン 3.11 で変更: Added support for specifying member name encoding for reading metadata in the zipfile's directory and file headers.

ZipFile.close()

アーカイブファイルをクローズします。close() はプログラムを終了する前に必ず呼び出さなければなりません。さもないとアーカイブ上の重要なレコードが書き込まれません。

ZipFile.getinfo(name)

アーカイブメンバ name に関する情報を持つ ZipInfo オブジェクトを返します。アーカイブに含まれないファイル名に対して getinfo() を呼び出すと、KeyError が送出されます。

ZipFile.infolist()

アーカイブに含まれる各メンバの ZipInfo オブジェクトからなるリストを返します。既存のアーカイブファイルを開いている場合、リストの順番は実際の ZIP ファイル中のメンバの順番と同じになります。

ZipFile.namelist()

アーカイブメンバの名前のリストを返します。

ZipFile.open(name, mode='r', pwd=None, *, force_zip64=False)

Access a member of the archive as a binary file-like object. name can be either the name of a file within the archive or a ZipInfo object. The mode parameter, if included, must be 'r' (the default) or 'w'. pwd is the password used to decrypt encrypted ZIP files as a bytes object.

open() はコンテキストマネージャでもあるので with 文をサポートしています:

with ZipFile('spam.zip') as myzip:
    with myzip.open('eggs.txt') as myfile:
        print(myfile.read())

With mode 'r' the file-like object (ZipExtFile) is read-only and provides the following methods: read(), readline(), readlines(), seek(), tell(), __iter__(), __next__(). These objects can operate independently of the ZipFile.

With mode='w', a writable file handle is returned, which supports the write() method. While a writable file handle is open, attempting to read or write other files in the ZIP file will raise a ValueError.

When writing a file, if the file size is not known in advance but may exceed 2 GiB, pass force_zip64=True to ensure that the header format is capable of supporting large files. If the file size is known in advance, construct a ZipInfo object with file_size set, and use that as the name parameter.

注釈

open()、read()、および extract() メソッドには、ファイル名または ZipInfo オブジェクトを指定できます。これは重複する名前のメンバを含む ZIP ファイルを読み込むときにそのメリットを享受できるでしょう。

バージョン 3.6 で変更: Removed support of mode='U'. Use io.TextIOWrapper for reading compressed text files in universal newlines mode.

バージョン 3.6 で変更: ZipFile.open() can now be used to write files into the archive with the mode='w' option.

バージョン 3.6 で変更: Calling open() on a closed ZipFile will raise a ValueError. Previously, a RuntimeError was raised.

ZipFile.extract(member, path=None, pwd=None)

Extract a member from the archive to the current working directory; member must be its full name or a ZipInfo object. Its file information is extracted as accurately as possible. path specifies a different directory to extract to. member can be a filename or a ZipInfo object. pwd is the password used for encrypted files as a bytes object.

作成された (ディレクトリか新ファイルの) 正規化されたパスを返します。

注釈

メンバのファイル名が絶対パスなら、ドライブ/UNC sharepoint および先頭の (バック) スラッシュは取り除かれます。例えば、Unix で ///foo/bar は foo/bar となり、Window で C:\foo\bar は foo\bar となります。また、メンバのファイル名に含まれる全ての ".." は取り除かれます。例えば、../../foo../../ba..r は foo../ba..r となります。Windows では、不正な文字 (:, <, >, |, ", ?, および *) はアンダースコア (_) で置き換えられます。

バージョン 3.6 で変更: Calling extract() on a closed ZipFile will raise a ValueError. Previously, a RuntimeError was raised.

バージョン 3.6.2 で変更: path パラメタが path-like object を受け付けるようになりました。

ZipFile.extractall(path=None, members=None, pwd=None)

Extract all members from the archive to the current working directory. path specifies a different directory to extract to. members is optional and must be a subset of the list returned by namelist(). pwd is the password used for encrypted files as a bytes object.

警告

信頼できないソースからきた Zip ファイルを、事前に中身をチェックせずに展開してはいけません。ファイルを path の外側に作成することができるからです。例えば、 "/" で始まる絶対パスを持ったメンバーや、 2 つのドット ".." を持つファイル名などの場合です。このモジュールはそれを避けようとします。 extract() の注釈を参照してください。

バージョン 3.6 で変更: Calling extractall() on a closed ZipFile will raise a ValueError. Previously, a RuntimeError was raised.

バージョン 3.6.2 で変更: path パラメタが path-like object を受け付けるようになりました。

ZipFile.printdir()

アーカイブの内容の一覧を sys.stdout に出力します。

ZipFile.setpassword(pwd)

Set pwd (a bytes object) as default password to extract encrypted files.

ZipFile.read(name, pwd=None)

Return the bytes of the file name in the archive. name is the name of the file in the archive, or a ZipInfo object. The archive must be open for read or append. pwd is the password used for encrypted files as a bytes object and, if specified, overrides the default password set with setpassword(). Calling read() on a ZipFile that uses a compression method other than ZIP_STORED, ZIP_DEFLATED, ZIP_BZIP2 or ZIP_LZMA will raise a NotImplementedError. An error will also be raised if the corresponding compression module is not available.

バージョン 3.6 で変更: Calling read() on a closed ZipFile will raise a ValueError. Previously, a RuntimeError was raised.

ZipFile.testzip()

Read all the files in the archive and check their CRC's and file headers. Return the name of the first bad file, or else return None.

バージョン 3.6 で変更: Calling testzip() on a closed ZipFile will raise a ValueError. Previously, a RuntimeError was raised.

ZipFile.write(filename, arcname=None, compress_type=None, compresslevel=None)

Write the file named filename to the archive, giving it the archive name arcname (by default, this will be the same as filename, but without a drive letter and with leading path separators removed). If given, compress_type overrides the value given for the compression parameter to the constructor for the new entry. Similarly, compresslevel will override the constructor if given. The archive must be open with mode 'w', 'x' or 'a'.

注釈

The ZIP file standard historically did not specify a metadata encoding, but strongly recommended CP437 (the original IBM PC encoding) for interoperability. Recent versions allow use of UTF-8 (only). In this module, UTF-8 will automatically be used to write the member names if they contain any non-ASCII characters. It is not possible to write member names in any encoding other than ASCII or UTF-8.

注釈

アーカイブ名はアーカイブルートに対する相対パスでなければなりません。言い換えると、アーカイブ名はパスセパレータで始まってはいけません。

注釈

もし、arcname (arcname が与えられない場合は、filename) が null byte を含むなら、アーカイブ中のファイルのファイル名は、null byte までで切り詰められます。

注釈

A leading slash in the filename may lead to the archive being impossible to open in some zip programs on Windows systems.

バージョン 3.6 で変更: Calling write() on a ZipFile created with mode 'r' or a closed ZipFile will raise a ValueError. Previously, a RuntimeError was raised.

ZipFile.writestr(zinfo_or_arcname, data, compress_type=None, compresslevel=None)

Write a file into the archive. The contents is data, which may be either a str or a bytes instance; if it is a str, it is encoded as UTF-8 first. zinfo_or_arcname is either the file name it will be given in the archive, or a ZipInfo instance. If it's an instance, at least the filename, date, and time must be given. If it's a name, the date and time is set to the current date and time. The archive must be opened with mode 'w', 'x' or 'a'.

If given, compress_type overrides the value given for the compression parameter to the constructor for the new entry, or in the zinfo_or_arcname (if that is a ZipInfo instance). Similarly, compresslevel will override the constructor if given.

注釈

ZipInfo インスタンスを引数 zinfo_or_arcname として与えた場合、与えられた ZipInfo インスタンスのメンバーである compress_type で指定された圧縮方法が使われます。デフォルトでは、ZipInfo コンストラクターが、このメンバーを ZIP_STORED に設定します。

バージョン 3.2 で変更: 引数 compress_type を追加しました。

バージョン 3.6 で変更: Calling writestr() on a ZipFile created with mode 'r' or a closed ZipFile will raise a ValueError. Previously, a RuntimeError was raised.

ZipFile.mkdir(zinfo_or_directory, mode=511)

Create a directory inside the archive. If zinfo_or_directory is a string, a directory is created inside the archive with the mode that is specified in the mode argument. If, however, zinfo_or_directory is a ZipInfo instance then the mode argument is ignored.

The archive must be opened with mode 'w', 'x' or 'a'.

Added in version 3.11.

以下のデータ属性も利用することができます:

ZipFile.filename

ZIP ファイルの名前です。

ZipFile.debug

使用するデバッグ出力レベルです。この属性は 0 (デフォルト、何も出力しない) から 3 (最も多く出力する) までの値に設定することができます。デバッグ情報は sys.stdout に出力されます。

ZipFile.comment

ZIP ファイルに bytes オブジェクトとして関連付けられたコメントです。モード 'w' 、 'x' または 'a' で作成された ZipFile インスタンスへコメントを割り当てる場合、文字列長は 65535 バイトまでにしてください。その長さを超えたコメントは切り捨てられます。

Path オブジェクト

class zipfile.Path(root, at='')

Construct a Path object from a root zipfile (which may be a ZipFile instance or file suitable for passing to the ZipFile constructor).

at specifies the location of this Path within the zipfile, e.g. 'dir/file.txt', 'dir/', or ''. Defaults to the empty string, indicating the root.

Path objects expose the following features of pathlib.Path objects:

Path objects are traversable using the / operator or joinpath.

Path.name

The final path component.

Path.open(mode='r', *, pwd, **)

Invoke ZipFile.open() on the current path. Allows opening for read or write, text or binary through supported modes: 'r', 'w', 'rb', 'wb'. Positional and keyword arguments are passed through to io.TextIOWrapper when opened as text and ignored otherwise. pwd is the pwd parameter to ZipFile.open().

バージョン 3.9 で変更: Added support for text and binary modes for open. Default mode is now text.

バージョン 3.11.2 で変更: The encoding parameter can be supplied as a positional argument without causing a TypeError. As it could in 3.9. Code needing to be compatible with unpatched 3.10 and 3.11 versions must pass all io.TextIOWrapper arguments, encoding included, as keywords.

Path.iterdir()

Enumerate the children of the current directory.

Path.is_dir()

Return True if the current context references a directory.

Path.is_file()

Return True if the current context references a file.

Path.exists()

Return True if the current context references a file or directory in the zip file.

Path.suffix

The file extension of the final component.

Added in version 3.11: Added Path.suffix property.

Path.stem

The final path component, without its suffix.

Added in version 3.11: Added Path.stem property.

Path.suffixes

A list of the path’s file extensions.

Added in version 3.11: Added Path.suffixes property.

Path.read_text(*, **)

Read the current file as unicode text. Positional and keyword arguments are passed through to io.TextIOWrapper (except buffer, which is implied by the context).

バージョン 3.11.2 で変更: The encoding parameter can be supplied as a positional argument without causing a TypeError. As it could in 3.9. Code needing to be compatible with unpatched 3.10 and 3.11 versions must pass all io.TextIOWrapper arguments, encoding included, as keywords.

Path.read_bytes()

Read the current file as bytes.

Path.joinpath(*other)

Return a new Path object with each of the other arguments joined. The following are equivalent:

>>> Path(...).joinpath('child').joinpath('grandchild')
>>> Path(...).joinpath('child', 'grandchild')
>>> Path(...) / 'child' / 'grandchild'

バージョン 3.10 で変更: Prior to 3.10, joinpath was undocumented and accepted exactly one parameter.

The zipp [https://pypi.org/project/zipp/] project provides backports of the latest path object functionality to older Pythons. Use zipp.Path in place of zipfile.Path for early access to changes.

PyZipFile オブジェクト

PyZipFile コンストラクタは ZipFile コンストラクタと同じパラメータに加え、optimize パラメータをとります。

class zipfile.PyZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, optimize=-1)

バージョン 3.2 で変更: Added the optimize parameter.

バージョン 3.4 で変更: ZIP64 拡張がデフォルトで有効になりました。

インスタンスは ZipFile オブジェクトのメソッドの他に、追加のメソッドを 1 個持ちます:

writepy(pathname, basename='', filterfunc=None)

*.py ファイルを探し、一致するファイルをアーカイブに追加します。

PyZipFile に optimize 引数が与えられない場合、あるいは -1 が指定された場合、対応するファイルは *.pyc ファイルで、必要に応じてコンパイルします。

PyZipFile の optimize パラメータが 0、1、あるいは 2 の場合、それを最適化レベル (compile() 参照) とするファイルのみが、必要に応じてコンパイルされアーカイブに追加されます。

If pathname is a file, the filename must end with .py, and just the (corresponding *.pyc) file is added at the top level (no path information). If pathname is a file that does not end with .py, a RuntimeError will be raised. If it is a directory, and the directory is not a package directory, then all the files *.pyc are added at the top level. If the directory is a package directory, then all *.pyc are added under the package name as a file path, and if any subdirectories are package directories, all of these are added recursively in sorted order.

basename は内部が使用するためだけのものです。

filterfunc を与える場合、単一の文字列引数を取る関数を渡してください。これには(個々のフルパスを含む)それぞれのパスがアーカイブに加えられる前に渡されます。 filterfunc が偽を返せば、そのパスはアーカイブに追加されず、ディレクトリだった場合はその中身が無視されます。例として、私たちのテストファイルが全て test ディレクトリの中にあるか、 test 文字列で始まるとしましょう。 filterfunc を使ってそれらを除外出来ます:

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

writepy() メソッドは以下のようなファイル名でアーカイブを作成します:

string.pyc                   # Top level name
test/__init__.pyc            # Package directory
test/testall.pyc             # Module test.testall
test/bogus/__init__.pyc      # Subpackage directory
test/bogus/myfile.pyc        # Submodule test.bogus.myfile

バージョン 3.4 で変更: Added the filterfunc parameter.

バージョン 3.6.2 で変更: pathname 引数が path-like object を受け付けるようになりました。

バージョン 3.7 で変更: Recursion sorts directory entries.

ZipInfo オブジェクト

ZipInfo クラスのインスタンスは、ZipFile オブジェクトの getinfo() および infolist() メソッドによって返されます。各オブジェクトは ZIP アーカイブ内の 1 個のメンバに関する情報を格納します。

There is one classmethod to make a ZipInfo instance for a filesystem file:

classmethod ZipInfo.from_file(filename, arcname=None, *, strict_timestamps=True)

Construct a ZipInfo instance for a file on the filesystem, in preparation for adding it to a zip file.

filename should be the path to a file or directory on the filesystem.

If arcname is specified, it is used as the name within the archive. If arcname is not specified, the name will be the same as filename, but with any drive letter and leading path separators removed.

The strict_timestamps argument, when set to False, allows to zip files older than 1980-01-01 at the cost of setting the timestamp to 1980-01-01. Similar behavior occurs with files newer than 2107-12-31, the timestamp is also set to the limit.

Added in version 3.6.

バージョン 3.6.2 で変更: filename 引数が path-like object を受け入れるようになりました。

バージョン 3.8 で変更: Added the strict_timestamps keyword-only parameter.

インスタンスは以下のメソッドと属性を持ちます:

ZipInfo.is_dir()

アーカイブのメンバーがディレクトリの場合に True を返します。

This uses the entry's name: directories should always end with /.

Added in version 3.6.

ZipInfo.filename

アーカイブ中のファイル名。

ZipInfo.date_time

アーカイブメンバの最終更新日時。6 つの値からなるタプルになります:

インデックス

値

0

西暦年 (>= 1980)

1

月 (1 から始まる)

2

日 (1 から始まる)

3

時 (0 から始まる)

4

分 (0 から始まる)

5

秒 (0 から始まる)

注釈

ZIP ファイルフォーマットは 1980 年より前のタイムスタンプをサポートしていません。

ZipInfo.compress_type

アーカイブメンバの圧縮形式。

ZipInfo.comment

Comment for the individual archive member as a bytes object.

ZipInfo.extra

拡張フィールドデータ。この bytes オブジェクトに含まれているデータの内部構成については、PKZIP Application Note [https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT] でコメントされています。

ZipInfo.create_system

ZIP アーカイブを作成したシステムを記述する文字列。

ZipInfo.create_version

このアーカイブを作成した PKZIP のバージョン。

ZipInfo.extract_version

このアーカイブを展開する際に必要な PKZIP のバージョン。

ZipInfo.reserved

予約領域。ゼロでなくてはなりません。

ZipInfo.flag_bits

ZIP フラグビット列。

ZipInfo.volume

ファイルヘッダのボリューム番号。

ZipInfo.internal_attr

内部属性。

ZipInfo.external_attr

外部ファイル属性。

ZipInfo.header_offset

ファイルヘッダへのバイトオフセット。

ZipInfo.CRC

圧縮前のファイルの CRC-32 チェックサム。

ZipInfo.compress_size

圧縮後のデータのサイズ。

ZipInfo.file_size

圧縮前のファイルのサイズ。

コマンドラインインターフェイス

zipfile モジュールは、 ZIP アーカイブを操作するための簡単なコマンドラインインターフェースを提供しています。

ZIP アーカイブを新規に作成したい場合、-c オプションの後にまとめたいファイルを列挙してください:

$ python -m zipfile -c monty.zip spam.txt eggs.txt

ディレクトリを渡すこともできます:

$ python -m zipfile -c monty.zip life-of-brian_1979/

ZIP アーカイブを特定のディレクトリに展開したい場合、-e オプションを使用してください:

$ python -m zipfile -e monty.zip target-dir/

ZIP アーカイブ内のファイル一覧を表示するには -l を使用してください:

$ python -m zipfile -l monty.zip

コマンドラインオプション

-l <zipfile>

--list <zipfile>

zipfile 内のファイル一覧を表示します。

-c <zipfile> <source1> ... <sourceN>

--create <zipfile> <source1> ... <sourceN>

ソースファイルから zipfile を作成します。

-e <zipfile> <output_dir>

--extract <zipfile> <output_dir>

zipfile を対象となるディレクトリに展開します。

-t <zipfile>

--test <zipfile>

zipfile が有効かどうか調べます。

--metadata-encoding <encoding>

Specify encoding of member names for -l, -e and -t.

Added in version 3.11.

Decompression pitfalls

The extraction in zipfile module might fail due to some pitfalls listed below.

From file itself

Decompression may fail due to incorrect password / CRC checksum / ZIP format or unsupported compression method / decryption.

File System limitations

Exceeding limitations on different file systems can cause decompression failed. Such as allowable characters in the directory entries, length of the file name, length of the pathname, size of a single file, and number of files, etc.

Resources limitations

The lack of memory or disk volume would lead to decompression failed. For example, decompression bombs (aka ZIP bomb [https://en.wikipedia.org/wiki/Zip_bomb]) apply to zipfile library that can cause disk volume exhaustion.

Interruption

Interruption during the decompression, such as pressing control-C or killing the decompression process may result in incomplete decompression of the archive.

Default behaviors of extraction

Not knowing the default extraction behaviors can cause unexpected decompression results. For example, when extracting the same archive twice, it overwrites files without asking.

tarfile --- Read and write tar archive files

ソースコード: Lib/tarfile.py [https://github.com/python/cpython/tree/3.12/Lib/tarfile.py]

tarfile モジュールは、gzip、bz2、および lzma 圧縮されたものを含む、tar アーカイブを読み書きできます。.zip ファイルの読み書きには zipfile モジュールか、あるいは shutil の高水準関数を使用してください。

いくつかの事実と形態:

モジュールが利用可能な場合、gzip、bz2 ならびに lzma で圧縮されたアーカイブを読み書きします。

POSIX.1-1988 (ustar) フォーマットの読み書きをサポートしています。

longname および longlink 拡張を含む GNU tar フォーマットの読み書きをサポートしています。スパースファイルの復元を含む sparse 拡張は読み込みのみサポートしています。

POSIX.1-2001 (pax) フォーマットの読み書きをサポートしています。

ディレクトリ、一般ファイル、ハードリンク、シンボリックリンク、fifo、キャラクターデバイスおよびブロックデバイスを処理します。また、タイムスタンプ、アクセス許可や所有者のようなファイル情報の取得および保存が可能です。

バージョン 3.3 で変更: lzma 圧縮をサポートしました。

バージョン 3.12 で変更: Archives are extracted using a filter, which makes it possible to either limit surprising/dangerous features, or to acknowledge that they are expected and the archive is fully trusted. By default, archives are fully trusted, but this default is deprecated and slated to change in Python 3.14.

tarfile.open(name=None, mode='r', fileobj=None, bufsize=10240, **kwargs)

パス名 name の TarFile オブジェクトを返します。TarFile オブジェクトと、利用できるキーワード引数に関する詳細な情報については、TarFile オブジェクト 節を参照してください。

mode は 'filemode[:compression]' の形式をとる文字列でなければなりません。デフォルトの値は 'r' です。以下に mode のとりうる組み合わせすべてを示します:

mode

action

'r' または 'r:*'

圧縮方法に関して透過的に、読み込み用にオープンします (推奨)。

'r:'

非圧縮で読み込み用に排他的にオープンします。

'r:gz'

gzip 圧縮で読み込み用にオープンします。

'r:bz2'

bzip2 圧縮で読み込み用にオープンします。

'r:xz'

lzma 圧縮で読み込み用にオープンします。

'x' or 'x:'

圧縮せずに tarfile を排他的に作成します。tarfile が既存の場合 FileExistsError 例外を送出します。

'x:gz'

gzip 圧縮で tarfile を作成します。tarfile が既存の場合 FileExistsError 例外を送出します。

'x:bz2'

bzip2 圧縮で tarfile を作成します。tarfile が既存の場合 FileExistsError 例外を送出します。

'x:xz'

lzma 圧縮で tarfile を作成します。tarfile が既存の場合 FileExistsError 例外を送出します。

'a' または 'a:'

非圧縮で追記用にオープンします。ファイルが存在しない場合は新たに作成されます。

'w' または 'w:'

非圧縮で書き込み用にオープンします。

'w:gz'

gzip 圧縮で書き込み用にオープンします。

'w:bz2'

bzip2 圧縮で書き込み用にオープンします。

'w:xz'

lzma 圧縮で書き込み用にオープンします。

'a:gz'、'a:bz2'、'a:xz' は利用できないことに注意して下さい。もし mode が、ある (圧縮した) ファイルを読み込み用にオープンするのに適していないなら、ReadError が送出されます。これを防ぐには mode 'r' を使って下さい。もし圧縮方式がサポートされていなければ、CompressionError が送出されます。

もし fileobj が指定されていれば、それは name でバイナリモードでオープンされた ファイルオブジェクト の代替として使うことができます。そのファイルオブジェクトの位置が 0 であることを前提に動作します。

For modes 'w:gz', 'x:gz', 'w|gz', 'w:bz2', 'x:bz2', 'w|bz2', tarfile.open() accepts the keyword argument compresslevel (default 9) to specify the compression level of the file.

'w:xz' および 'x:xz' モードの場合、tarfile.open() はファイルの圧縮レベルを指定するキーワード引数 preset を受け付けます。

For special purposes, there is a second format for mode: 'filemode|[compression]'. tarfile.open() will return a 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 read() or write() method (depending on the mode) that works with bytes. bufsize specifies the blocksize and defaults to 20 * 512 bytes. Use this variant in combination with e.g. sys.stdin.buffer, a socket file object or a tape device. However, such a TarFile object is limited in that it does not allow random access, see 使用例. The currently possible modes:

モード

動作

'r|*'

tar ブロックの stream を圧縮方法に関して透過的に読み込み用にオープンします。

'r|'

非圧縮 tar ブロックの stream を読み込み用にオープンします。

'r|gz'

gzip 圧縮の stream を読み込み用にオープンします。

'r|bz2'

bzip2 圧縮の stream を読み込み用にオープンします。

'r|xz'

lzma 圧縮の stream を読み込み用にオープンします。

'w|'

非圧縮の stream を書き込み用にオープンします。

'w|gz'

gzip 圧縮の stream を書き込み用にオープンします。

'w|bz2'

bzip2 圧縮の stream を書き込み用にオープンします。

'w|xz'

lzma 圧縮の stream を書き込み用にオープンします。

バージョン 3.5 で変更: 'x' (排他的作成) モードが追加されました。

バージョン 3.6 で変更: name パラメタが path-like object を受け付けるようになりました。

バージョン 3.12 で変更: The compresslevel keyword argument also works for streams.

class tarfile.TarFile

tar アーカイブを読み書きするためのクラスです。このクラスを直接使わないこと: 代わりに tarfile.open() を使ってください。TarFile オブジェクト を参照してください。

tarfile.is_tarfile(name)

もし name が tar アーカイブファイルであり、tarfile モジュールで読み込める場合に True を返します。 name は str、ファイルまたは file-like オブジェクトです。

バージョン 3.9 で変更: ファイルおよびファイルライクオブジェクトをサポートしました。

tarfile モジュールは以下の例外を定義しています:

exception tarfile.TarError

すべての tarfile 例外のための基本クラスです。

exception tarfile.ReadError

tar アーカイブがオープンされた時、tarfile モジュールで操作できないか、あるいは何か無効であるとき送出されます。

exception tarfile.CompressionError

圧縮方法がサポートされていないか、あるいはデータを正しくデコードできない時に送出されます。

exception tarfile.StreamError

ストリームのような TarFile オブジェクトで典型的な制限のために送出されます。

exception tarfile.ExtractError

TarFile.extract() を使った時に 致命的でない エラーに対して送出されます。ただし TarFile.errorlevel== 2 の場合に限ります。

exception tarfile.HeaderError

TarInfo.frombuf() メソッドが取得したバッファーが不正だったときに送出されます。

exception tarfile.FilterError

Base class for members refused by filters.

tarinfo

Information about the member that the filter refused to extract, as TarInfo.

exception tarfile.AbsolutePathError

Raised to refuse extracting a member with an absolute path.

exception tarfile.OutsideDestinationError

Raised to refuse extracting a member outside the destination directory.

exception tarfile.SpecialFileError

Raised to refuse extracting a special file (e.g. a device or pipe).

exception tarfile.AbsoluteLinkError

Raised to refuse extracting a symbolic link with an absolute path.

exception tarfile.LinkOutsideDestinationError

Raised to refuse extracting a symbolic link pointing outside the destination directory.

モジュールレベルで以下の定数が利用できます。

tarfile.ENCODING

既定の文字エンコーディング。Windows では 'utf-8' 、それ以外では sys.getfilesystemencoding() の返り値です。

tarfile.REGTYPE

tarfile.AREGTYPE

A regular file type.

tarfile.LNKTYPE

A link (inside tarfile) type.

tarfile.SYMTYPE

A symbolic link type.

tarfile.CHRTYPE

A character special device type.

tarfile.BLKTYPE

A block special device type.

tarfile.DIRTYPE

A directory type.

tarfile.FIFOTYPE

A FIFO special device type.

tarfile.CONTTYPE

A contiguous file type.

tarfile.GNUTYPE_LONGNAME

A GNU tar longname type.

tarfile.GNUTYPE_LONGLINK

A GNU tar longlink type.

tarfile.GNUTYPE_SPARSE

A GNU tar sparse file type.

以下の各定数は、tarfile モジュールが作成できる tar アーカイブフォーマットを定義しています。詳細は、サポートしている tar フォーマット を参照してください。

tarfile.USTAR_FORMAT

POSIX.1-1988 (ustar) フォーマット。

tarfile.GNU_FORMAT

GNU tar フォーマット。

tarfile.PAX_FORMAT

POSIX.1-2001 (pax) フォーマット。

tarfile.DEFAULT_FORMAT

アーカイブを作成する際のデフォルトのフォーマット。現在は PAX_FORMAT です。

バージョン 3.8 で変更: 新しいアーカイブのデフォルトフォーマットが GNU_FORMAT から PAX_FORMAT に変更されました。

参考

zipfile モジュール

zipfile 標準モジュールのドキュメント。

アーカイブ化操作

shutil が提供するより高水準のアーカイブ機能についてのドキュメント。

GNU tar manual, Basic Tar Format [https://www.gnu.org/software/tar/manual/html_node/Standard.html]

GNU tar 拡張機能を含む、tar アーカイブファイルのためのドキュメント。

TarFile オブジェクト

TarFile オブジェクトは、tar アーカイブへのインターフェースを提供します。tar アーカイブは一連のブロックです。アーカイブメンバー (保存されたファイル) は、ヘッダーブロックとそれに続くデータブロックで構成されています。一つの tar アーカイブにファイルを何回も保存することができます。各アーカイブメンバーは、TarInfo オブジェクトで確認できます。詳細については TarInfo オブジェクト を参照してください。

TarFile オブジェクトは with 文のコンテキストマネージャーとして利用できます。with ブロックが終了したときにオブジェクトはクローズされます。例外が発生した時、内部で利用されているファイルオブジェクトのみがクローズされ、書き込み用にオープンされたアーカイブのファイナライズは行われないことに注意してください。使用例 節のユースケースを参照してください。

Added in version 3.2: コンテキスト管理のプロトコルがサポートされました。

class 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)

以下のすべての引数はオプションで、インスタンス属性としてもアクセスできます。

name is the pathname of the archive. name may be a path-like object. It can be omitted if fileobj is given. In this case, the file object's name attribute is used if it exists.

mode は、既存のアーカイブから読み込むための 'r'、既存のアーカイブに追記するための 'a'、既存のファイルがあれば上書きして新しいファイルを作成する 'w' 、あるいは存在しない場合にのみ新しいファイルを作成する 'x' のいずれかです。

fileobj が与えられていれば、それを使ってデータを読み書きします。もしそれが決定できれば、mode は fileobj のモードで上書きされます。fileobj は位置 0 から利用されます。

注釈

TarFile をクローズした時、fileobj はクローズされません。

format はアーカイブの書き込みフォーマットを制御します。モジュールレベルで定義されている、USTAR_FORMAT、GNU_FORMAT、あるいは PAX_FORMAT のいずれかである必要があります。読み出しのときは、1 つのアーカイブに異なるフォーマットが混在していたとしても、フォーマットは自動的に検知されます。

tarinfo 引数を利用して、デフォルトの TarInfo クラスを別のクラスで置き換えることができます。

dereference が False だった場合、シンボリックリンクやハードリンクがアーカイブに追加されます。True だった場合、リンクのターゲットとなるファイルの内容がアーカイブに追加されます。シンボリックリンクをサポートしていないシステムでは効果がありません。

ignore_zeros が False だった場合、空ブロックをアーカイブの終端として扱います。True だった場合、空の (無効な) ブロックをスキップして、可能な限り多くのメンバーを取得しようとします。このオプションは、連結されたり、壊れたアーカイブファイルを扱うときにのみ、意味があります。

debug は 0 (デバッグメッセージ無し) から 3 (全デバッグメッセージ) まで設定できます。このメッセージは sys.stderr に書き込まれます。

errorlevel controls how extraction errors are handled, see the corresponding attribute.

引数 encoding および errors にはアーカイブの読み書きやエラー文字列の変換に使用する文字エンコーディングを指定します。ほとんどのユーザーはデフォルト設定のままで動作します。詳細に関しては Unicode に関する問題 節を参照してください。

引数 pax_headers は、オプションの文字列辞書で、format が PAX_FORMAT だった場合に pax グローバルヘッダーに追加されます。

バージョン 3.2 で変更: 引数 errors のデフォルトが 'surrogateescape' になりました。

バージョン 3.5 で変更: 'x' (排他的作成) モードが追加されました。

バージョン 3.6 で変更: name パラメタが path-like object を受け付けるようになりました。

classmethod TarFile.open(...)

代替コンストラクターです。モジュールレベルでの tarfile.open() 関数は、実際はこのクラスメソッドへのショートカットです。

TarFile.getmember(name)

メンバー name に対する TarInfo オブジェクトを返します。name がアーカイブに見つからなければ、KeyError が送出されます。

注釈

アーカイブ内にメンバーが複数ある場合は、最後に出現するものが最新のバージョンとみなされます。

TarFile.getmembers()

TarInfo アーカイブのメンバーをオブジェクトのリストとして返します。このリストはアーカイブ内のメンバーと同じ順番です。

TarFile.getnames()

メンバーをその名前のリストを返します。これは getmembers() で返されるリストと同じ順番です。

TarFile.list(verbose=True, *, members=None)

内容の一覧を sys.stdout に出力します。verbose が False の場合、メンバー名のみ表示します。True の場合、 ls -l に似た出力を生成します。オプションの members を与える場合、 getmembers() が返すリストのサブセットである必要があります。

バージョン 3.5 で変更: members 引数が追加されました。.

TarFile.next()

TarFile が読み込み用にオープンされている時、アーカイブの次のメンバーを TarInfo オブジェクトとして返します。もしそれ以上利用可能なものがなければ、None を返します。

TarFile.extractall(path='.', members=None, *, numeric_owner=False, filter=None)

すべてのメンバーをアーカイブから現在の作業ディレクトリまたは path に抽出します。オプションの members が与えられるときには、getmembers() で返されるリストの一部でなければなりません。所有者、変更時刻、アクセス権限のようなディレクトリ情報はすべてのメンバーが抽出された後にセットされます。これは二つの問題を回避するためです。一つはディレクトリの変更時刻はその中にファイルが作成されるたびにリセットされるということ、もう一つはディレクトリに書き込み許可がなければその中のファイル抽出は失敗してしまうということです。

numeric_owner が True の場合、tarfile の uid と gid 数値が抽出されたファイルのオーナー/グループを設定するために使用されます。False の場合、tarfile の名前付きの値が使用されます。

The filter argument specifies how members are modified or rejected before extraction. See Extraction filters for details. It is recommended to set this explicitly depending on which tar features you need to support.

警告

内容を信頼できない tar アーカイブを、事前の内部チェック前に展開してはいけません。ファイルが path の外側に作られる可能性があります。例えば、"/" で始まる絶対パスのファイル名や、2 重ドット ".." で始まるパスのファイル名です。

Set filter='data' to prevent the most dangerous security issues, and read the Extraction filters section for details.

バージョン 3.5 で変更: numeric_owner 引数が追加されました。

バージョン 3.6 で変更: path パラメタが path-like object を受け付けるようになりました。

バージョン 3.12 で変更: filter パラメータが追加されました。

TarFile.extract(member, path='', set_attrs=True, *, numeric_owner=False, filter=None)

アーカイブからメンバーの完全な名前を使って、現在のディレクトリに展開します。ファイル情報はできる限り正確に展開されます。 member はファイル名もしくは TarInfo オブジェクトです。 path を使って別のディレクトリを指定することもできます。 path は　path-like object でも構いません。set_attrs が false でない限り、ファイルの属性 (所有者、最終更新時刻、モード) は設定されます。

The numeric_owner and filter arguments are the same as for extractall().

注釈

extract() メソッドはいくつかの展開に関する問題を扱いません。ほとんどの場合、extractall() メソッドの利用を考慮するべきです。

警告

extractall() の警告を参してください。

Set filter='data' to prevent the most dangerous security issues, and read the Extraction filters section for details.

バージョン 3.2 で変更: パラメーターに set_attrs を追加しました。

バージョン 3.5 で変更: numeric_owner 引数が追加されました。

バージョン 3.6 で変更: path パラメタが path-like object を受け付けるようになりました。

バージョン 3.12 で変更: filter パラメータが追加されました。

TarFile.extractfile(member)

アーカイブからメンバーをファイルオブジェクトとして抽出します。 member はファイル名でも TarInfo オブジェクトでも構いません。member が一般ファイルまたはリンクの場合、io.BufferedReader オブジェクトが返されます。存在するそれ以外のメンバーでは、 None が返されます。それ以外の場合、None が返されます。アーカイブに member が存在しない場合は KeyError が送出されます。

バージョン 3.3 で変更: 戻り値が io.BufferedReader オブジェクトになりました。

TarFile.errorlevel: int

If errorlevel is 0, errors are ignored when using TarFile.extract() and TarFile.extractall(). Nevertheless, they appear as error messages in the debug output when debug is greater than 0. If 1 (the default), all fatal errors are raised as OSError or FilterError exceptions. If 2, all non-fatal errors are raised as TarError exceptions as well.

Some exceptions, e.g. ones caused by wrong argument types or data corruption, are always raised.

Custom extraction filters should raise FilterError for fatal errors and 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.

TarFile.extraction_filter

Added in version 3.12.

The extraction filter used as a default for the filter argument of extract() and extractall().

The attribute may be None or a callable. String names are not allowed for this attribute, unlike the filter argument to extract().

If extraction_filter is None (the default), calling an extraction method without a filter argument will raise a DeprecationWarning, and fall back to the fully_trusted filter, whose dangerous behavior matches previous versions of Python.

In Python 3.14+, leaving extraction_filter=None will cause extraction methods to use the data filter by default.

The attribute may be set on instances or overridden in subclasses. It also is possible to set it on the 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 site configuration. To set a global default this way, a filter function needs to be wrapped in staticmethod() to prevent injection of a self argument.

TarFile.add(name, arcname=None, recursive=True, *, filter=None)

ファイル name をアーカイブに追加します。 name は、任意のファイルタイプ (ディレクトリ、fifo、シンボリックリンク等)です。 arcname が与えられている場合は、それはアーカイブ内のファイルの代替名を指定します。デフォルトではディレクトリは再帰的に追加されます。これは、 recursive を False に設定すると避けられます。再帰処理はソートされた順序でエントリーを追加します。 filter が与えられた場合、それは TarInfo オブジェクトを引数として受け取り、操作した TarInfo オブジェクトを返す関数でなければなりません。代わりに None を返した場合、 TarInfo オブジェクトはアーカイブから除外されます。使用例 にある例を参照してください。

バージョン 3.2 で変更: filter パラメータが追加されました。

バージョン 3.7 で変更: 再帰処理はソートされた順序でエントリーを追加するようになりました。

TarFile.addfile(tarinfo, fileobj=None)

Add the TarInfo object tarinfo to the archive. If fileobj is given, it should be a binary file, and tarinfo.size bytes are read from it and added to the archive. You can create TarInfo objects directly, or by using gettarinfo().

TarFile.gettarinfo(name=None, arcname=None, fileobj=None)

os.stat() の結果か、既存のファイルに相当するものから、TarInfo オブジェクトを作成します。このファイルは、name で名付けられるか、ファイル記述子を持つ file object fileobj として指定されます。name は path-like object でも構いません。 arcname が与えられた場合、アーカイブ内のファイルに対して代替名を指定します。与えられない場合、名前は fileobj の name 属性 name 属性から取られます。名前はテキスト文字列にしてください。

TarInfo の属性の一部は、addfile() を使用して追加する前に修正できます。ファイルオブジェクトが、ファイルの先頭にある通常のファイルオブジェクトでない場合、 size などの属性は修正が必要かもしれません。これは、 GzipFile などの属性に当てはまります。name も修正できるかもしれず、この場合、arcname はダミーの文字列にすることができます。

バージョン 3.6 で変更: name パラメタが path-like object を受け付けるようになりました。

TarFile.close()

TarFile をクローズします。書き込みモードでは、完了ゼロブロックが 2 個アーカイブに追加されます。

TarFile.pax_headers: dict

pax グローバルヘッダーに含まれる key-value ペアの辞書です。

TarInfo オブジェクト

TarInfo オブジェクトは TarFile の一つのメンバーを表します。ファイルに必要なすべての属性 (ファイルタイプ、ファイルサイズ、時刻、アクセス権限、所有者等のような) を保存する他に、そのタイプを決定するのに役に立ついくつかのメソッドを提供します。これにはファイルのデータそのものは 含まれません 。

TarInfo objects are returned by TarFile's methods getmember(), getmembers() and gettarinfo().

Modifying the objects returned by getmember() or getmembers() will affect all subsequent operations on the archive. For cases where this is unwanted, you can use copy.copy() or call the replace() method to create a modified copy in one step.

Several attributes can be set to None to indicate that a piece of metadata is unused or unknown. Different TarInfo methods handle None differently:

The extract() or extractall() methods will ignore the corresponding metadata, leaving it set to a default.

addfile() will fail.

list() will print a placeholder string.

class tarfile.TarInfo(name='')

TarInfo オブジェクトを作成します。

classmethod TarInfo.frombuf(buf, encoding, errors)

TarInfo オブジェクトを文字列バッファー buf から作成して返します。

バッファーが不正な場合 HeaderError を送出します。

classmethod TarInfo.fromtarfile(tarfile)

TarFile オブジェクトの tarfile から、次のメンバーを読み込んで、それを TarInfo オブジェクトとして返します。

TarInfo.tobuf(format=DEFAULT_FORMAT, encoding=ENCODING, errors='surrogateescape')

TarInfo オブジェクトから文字列バッファーを作成します。引数についての情報は、TarFile クラスのコンストラクターを参照してください。

バージョン 3.2 で変更: 引数 errors のデフォルトが 'surrogateescape' になりました。

TarInfo オブジェクトには以下のデータ属性があります:

TarInfo.name: str

アーカイブメンバーの名前。

TarInfo.size: int

バイト単位でのサイズ。

TarInfo.mtime: int | float

Time of last modification in seconds since the epoch, as in os.stat_result.st_mtime.

バージョン 3.12 で変更: Can be set to None for extract() and extractall(), causing extraction to skip applying this attribute.

TarInfo.mode: int

Permission bits, as for os.chmod().

バージョン 3.12 で変更: Can be set to None for extract() and extractall(), causing extraction to skip applying this attribute.

TarInfo.type

ファイルタイプ。type は通常、定数 REGTYPE、AREGTYPE、LNKTYPE、SYMTYPE、DIRTYPE、FIFOTYPE、CONTTYPE、CHRTYPE、BLKTYPE、あるいは GNUTYPE_SPARSE のいずれかです。TarInfo オブジェクトのタイプをもっと簡単に解決するには、下記の is*() メソッドを使って下さい。

TarInfo.linkname: str

リンク先ファイルの名前。これはタイプ LNKTYPE と SYMTYPE の TarInfo オブジェクトにだけ存在します。

For symbolic links (SYMTYPE), the linkname is relative to the directory that contains the link. For hard links (LNKTYPE), the linkname is relative to the root of the archive.

TarInfo.uid: int

ファイルメンバーを保存した元のユーザーのユーザー ID。

バージョン 3.12 で変更: Can be set to None for extract() and extractall(), causing extraction to skip applying this attribute.

TarInfo.gid: int

ファイルメンバーを保存した元のユーザーのグループ ID。

バージョン 3.12 で変更: Can be set to None for extract() and extractall(), causing extraction to skip applying this attribute.

TarInfo.uname: str

ファイルメンバーを保存した元のユーザーのユーザー名。

バージョン 3.12 で変更: Can be set to None for extract() and extractall(), causing extraction to skip applying this attribute.

TarInfo.gname: str

ファイルメンバーを保存した元のユーザーのグループ名。

バージョン 3.12 で変更: Can be set to None for extract() and extractall(), causing extraction to skip applying this attribute.

TarInfo.chksum: int

Header checksum.

TarInfo.devmajor: int

Device major number.

TarInfo.devminor: int

Device minor number.

TarInfo.offset: int

The tar header starts here.

TarInfo.offset_data: int

The file's data starts here.

TarInfo.sparse

Sparse member information.

TarInfo.pax_headers: dict

pax 拡張ヘッダーに関連付けられた、key-value ペアの辞書。

TarInfo.replace(name=..., mtime=..., mode=..., linkname=..., uid=..., gid=..., uname=..., gname=..., deep=True)

Added in version 3.12.

Return a new copy of the TarInfo object with the given attributes changed. For example, to return a TarInfo with the group name set to 'staff', use:

new_tarinfo = old_tarinfo.replace(gname='staff')

By default, a deep copy is made. If deep is false, the copy is shallow, i.e. pax_headers and any custom attributes are shared with the original TarInfo object.

TarInfo オブジェクトは便利な照会用のメソッドもいくつか提供しています:

TarInfo.isfile()

Return True if the TarInfo object is a regular file.

TarInfo.isreg()

isfile() と同じです。

TarInfo.isdir()

ディレクトリの場合に True を返します。

TarInfo.issym()

シンボリックリンクの場合に True を返します。

TarInfo.islnk()

ハードリンクの場合に True を返します。

TarInfo.ischr()

キャラクターデバイスの場合に True を返します。

TarInfo.isblk()

ブロックデバイスの場合に True を返します。

TarInfo.isfifo()

FIFO の場合に True を返します。

TarInfo.isdev()

キャラクターデバイス、ブロックデバイスあるいは FIFO のいずれかの場合に True を返します。

Extraction filters

Added in version 3.12.

The tar format is designed to capture all details of a UNIX-like filesystem, which makes it very powerful. Unfortunately, the features make it easy to create tar files that have unintended -- and possibly malicious -- effects when extracted. For example, extracting a tar file can overwrite arbitrary files in various ways (e.g. by using absolute paths, .. 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.

参考

PEP 706 [https://peps.python.org/pep-0706/]

Contains further motivation and rationale behind the design.

The filter argument to TarFile.extract() or extractall() can be:

the string '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.

the string '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 tar_filter() for details.

the string 'data': Ignore or block most features specific to UNIX-like filesystems. Intended for extracting cross-platform data archives. See data_filter() for details.

None (default): Use TarFile.extraction_filter.

If that is also None (the default), raise a DeprecationWarning, and fall back to the 'fully_trusted' filter, whose dangerous behavior matches previous versions of Python.

In Python 3.14, the 'data' filter will become the default instead. It's possible to switch earlier; see TarFile.extraction_filter.

A callable which will be called for each extracted member with a TarInfo describing the member and the destination path to where the archive is extracted (i.e. the same path is used for all members):

filter(member: TarInfo, path: str, /) -> TarInfo | None

The callable is called just before each member is extracted, so it can take the current state of the disk into account. It can:

return a TarInfo object which will be used instead of the metadata in the archive, or

return None, in which case the member will be skipped, or

raise an exception to abort the operation or skip the member, depending on errorlevel. Note that when extraction is aborted, extractall() may leave the archive partially extracted. It does not attempt to clean up.

Default named filters

The pre-defined, named filters are available as functions, so they can be reused in custom filters:

tarfile.fully_trusted_filter(member, path)

Return member unchanged.

This implements the 'fully_trusted' filter.

tarfile.tar_filter(member, path)

Implements the 'tar' filter.

Strip leading slashes (/ and os.sep) from filenames.

Refuse to extract files with absolute paths (in case the name is absolute even after stripping slashes, e.g. C:/foo on Windows). This raises AbsolutePathError.

Refuse to extract files whose absolute path (after following symlinks) would end up outside the destination. This raises OutsideDestinationError.

Clear high mode bits (setuid, setgid, sticky) and group/other write bits (S_IWGRP | S_IWOTH).

Return the modified TarInfo member.

tarfile.data_filter(member, path)

Implements the 'data' filter. In addition to what tar_filter does:

Refuse to extract links (hard or soft) that link to absolute paths, or ones that link outside the destination.

This raises AbsoluteLinkError or LinkOutsideDestinationError.

Note that such files are refused even on platforms that do not support symbolic links.

Refuse to extract device files (including pipes). This raises SpecialFileError.

For regular files, including hard links:

Set the owner read and write permissions (S_IRUSR | S_IWUSR).

Remove the group & other executable permission (S_IXGRP | S_IXOTH) if the owner doesn’t have it (S_IXUSR).

For other files (directories), set mode to None, so that extraction methods skip applying permission bits.

Set user and group info (uid, gid, uname, gname) to None, so that extraction methods skip setting it.

Return the modified TarInfo member.

Filter errors

When a filter refuses to extract a file, it will raise an appropriate exception, a subclass of FilterError. This will abort the extraction if TarFile.errorlevel is 1 or more. With errorlevel=0 the error will be logged and the member will be skipped, but extraction will continue.

Hints for further verification

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

Extract to a new temporary directory to prevent e.g. exploiting pre-existing links, and to make it easier to clean up after a failed extraction.

When working with untrusted data, use external (e.g. OS-level) limits on disk, memory and CPU usage.

Check filenames against an allow-list of characters (to filter out control characters, confusables, foreign path separators, etc.).

Check that filenames have expected extensions (discouraging files that execute when you “click on them”, or extension-less files like Windows special device names).

Limit the number of extracted files, total size of extracted data, filename length (including symlink length), and size of individual files.

Check for files that would be shadowed on case-insensitive filesystems.

Also note that:

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.

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.

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. 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 extraction_filter will affect any subsequent operations.

Fully trusted archive:

my_tarfile.extraction_filter = (lambda member, path: member)
my_tarfile.extractall()

Use the 'data' filter if available, but revert to Python 3.11 behavior ('fully_trusted') if this feature is not available:

my_tarfile.extraction_filter = getattr(tarfile, 'data_filter',
                                       (lambda member, path: member))
my_tarfile.extractall()

Use the 'data' filter; fail if it is not available:

my_tarfile.extractall(filter=tarfile.data_filter)

もしくは:

my_tarfile.extraction_filter = tarfile.data_filter
my_tarfile.extractall()

Use the 'data' filter; warn if it is not available:

if hasattr(tarfile, 'data_filter'):
    my_tarfile.extractall(filter='data')
else:
    # remove this when no longer needed
    warn_the_user('Extracting may be unsafe; consider updating Python')
    my_tarfile.extractall()

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:

with StatefulFilter() as filter_func:
    tar.extractall(path, filter=filter_func)

Such a filter can be written as, for 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')

コマンドラインインターフェイス

Added in version 3.4.

tarfile モジュールは、 tar アーカイブを操作するための簡単なコマンドラインインターフェースを提供しています。

tar アーカイブを新規に作成したい場合、-c オプションの後にまとめたいファイル名のリストを指定してください:

$ python -m tarfile -c monty.tar  spam.txt eggs.txt

ディレクトリを渡すこともできます:

$ python -m tarfile -c monty.tar life-of-brian_1979/

tar アーカイブをカレントディレクトリに展開したい場合、-e オプションを使用してください:

$ python -m tarfile -e monty.tar

ディレクトリ名を渡すことで tar アーカイブを別のディレクトリに取り出すこともできます:

$ python -m tarfile -e monty.tar  other-dir/

tar アーカイブ内のファイル一覧を表示するには -l を使用してください:

$ python -m tarfile -l monty.tar

コマンドラインオプション

-l <tarfile>

--list <tarfile>

tarfile 内のファイル一覧を表示します。

-c <tarfile> <source1> ... <sourceN>

--create <tarfile> <source1> ... <sourceN>

ソースファイルから tarfile を作成します。

-e <tarfile> [<output_dir>]

--extract <tarfile> [<output_dir>]

output_dir が指定されていない場合、カレントディレクトリに tarfile を展開します。

-t <tarfile>

--test <tarfile>

tarfile が有効かどうか調べます。

-v, --verbose

詳細も出力します。

--filter <filtername>

Specifies the filter for --extract. See Extraction filters for details. Only string names are accepted (that is, fully_trusted, tar, and data).

使用例

tar アーカイブから現在のディレクトリにすべて抽出する方法:

import tarfile
tar = tarfile.open("sample.tar.gz")
tar.extractall(filter='data')
tar.close()

tar アーカイブの一部を、リストの代わりにジェネレーター関数を利用して TarFile.extractall() で展開する方法:

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()

非圧縮 tar アーカイブをファイル名のリストから作成する方法:

import tarfile
tar = tarfile.open("sample.tar", "w")
for name in ["foo", "bar", "quux"]:
    tar.add(name)
tar.close()

with 文を利用した同じ例:

import tarfile
with tarfile.open("sample.tar", "w") as tar:
    for name in ["foo", "bar", "quux"]:
        tar.add(name)

gzip 圧縮 tar アーカイブを作成してメンバー情報のいくつかを表示する方法:

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()

TarFile.add() 関数の filter 引数を利用してユーザー情報をリセットしながらアーカイブを作成する方法:

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()

サポートしている tar フォーマット

tarfile モジュールは 3 種類の tar フォーマットを作成することができます:

POSIX.1-1988 ustar format (USTAR_FORMAT). ファイル名の長さは256文字までで、リンク名の長さは100文字までです。最大のファイルサイズは8GiBです。このフォーマットは古くて制限が多いですが、広くサポートされています。

GNU tar format (GNU_FORMAT). 長いファイル名とリンク名、8GiBを超えるファイルやスパース(sparse)ファイルをサポートしています。これは GNU/Linux システムにおいてデファクト・スタンダードになっています。 tarfile モジュールは長いファイル名を完全にサポートしています。 スパースファイルは読み込みのみサポートしています。

The POSIX.1-2001 pax format (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.

他にも、読み込みのみサポートしている tar フォーマットがいくつかあります:

ancient V7 フォーマット。これは Unix 7th Edition から存在する、最初の tar フォーマットです。通常のファイルとディレクトリのみ保存します。名前は 100 文字を超えてはならず、ユーザー/グループ名に関する情報は保存されません。いくつかのアーカイブは、フィールドが ASCII でない文字を含む場合に、ヘッダーのチェックサムの計算を誤ります。

SunOS tar 拡張フォーマット。POSIX.1-2001 pax フォーマットの亜流ですが、互換性がありません。

Unicode に関する問題

tar フォーマットは、もともとテープドライブにファイルシステムのバックアップをとる目的で設計されました。現在、tarアーカイブはファイルを配布する際に一般的に用いられ、ネットワーク上で交換されています。オリジナルフォーマットが抱える一つの問題は (他の多くのフォーマットでも同じですが)、様々な文字エンコーディングのサポートについて考慮していないことです。例えば、UTF-8 システム上で作成された通常の tar アーカイブは、非 ASCII 文字を含んでいた場合、Latin-1 システムでは正しく読み取ることができません。テキストのメタデータ (ファイル名、リンク名、ユーザー/グループ名など) は破壊されます。残念なことに、アーカイブのエンコーディングを自動検出する方法はありません。pax フォーマットはこの問題を解決するために設計されました。これは非 ASCII メタデータをユニバーサル文字エンコーディング UTF-8 を使用して格納します。

tarfile における文字変換処理の詳細は TarFile クラスのキーワード引数 encoding および errors によって制御されます。

encoding はアーカイブのメタデータに使用する文字エンコーディングを指定します。デフォルト値は sys.getfilesystemencoding() で、フォールバックとして 'ascii' が使用されます。アーカイブの読み書き時に、メタデータはそれぞれデコードまたはエンコードしなければなりません。encoding に適切な値が設定されていない場合、その変換は失敗することがあります。

引数 errors は文字を変換できない時の扱いを指定します。指定できる値は エラーハンドラ 節を参照してください。デフォルトのスキームは 'surrogateescape' で、Python はそのファイルシステムの呼び出しも使用します。ファイル名、コマンドライン引数、および環境変数 を参照してください。

デフォルトの PAX_FORMAT アーカイブでは、メタデータはすべて UTF-8 で格納されるため、encoding は通常指定する必要はありません。encoding は、まれにある、バイナリの pax ヘッダーがデコードされた場合、あるいはサロゲート文字を含む文字列が格納されていた場合に使用されます。

ファイルフォーマット

この章で説明されるモジュールはマークアップやEメールでない様々なファイルフォーマットを構文解析します。

csv --- CSV File Reading and Writing

モジュールコンテンツ

Dialect クラスと書式化パラメータ

reader オブジェクト

writer オブジェクト

使用例

configparser --- Configuration file parser

クイックスタート

サポートされるデータ型

代替値

サポートするINI ファイルの構造

値の補間

マップ型プロトコルアクセス

パーサーの振る舞いをカスタマイズする

レガシーな API の例

ConfigParser オブジェクト

RawConfigParser オブジェクト

例外

tomllib --- Parse TOML files

使用例

変換表

netrc --- netrc file processing

netrc オブジェクト

plistlib --- Generate and parse Apple .plist files

使用例

csv --- CSV File Reading and Writing

ソースコード: Lib/csv.py [https://github.com/python/cpython/tree/3.12/Lib/csv.py]

CSV (Comma Separated Values、カンマ区切り値列) と呼ばれる形式は、 スプレッドシートやデータベース間でのデータのインポートやエクスポートにおける最も一般的な形式です。 CSVフォーマットは、 RFC 4180 [https://datatracker.ietf.org/doc/html/rfc4180.html] によって標準的な方法でフォーマットを記述する試みが行われる以前から長年使用されました。明確に定義された標準がないということは、異なるアプリケーション によって生成されたり取り込まれたりするデータ間では、しばしば微妙な違いが発生するということを意味します。こうした違いのために、複数のデータ源から得られた CSV ファイルを処理する作業が鬱陶しいものになることがあります。とはいえ、デリミタ (delimiter) やクオート文字の 相違はあっても、全体的な形式は十分似通っているため、こうしたデータを効率的に操作し、データの読み書きにおける細々としたことをプログラマ から隠蔽するような単一のモジュールを書くことは可能です。

csv モジュールでは、CSV 形式で書かれたテーブル状のデータを読み書きするためのクラスを実装しています。このモジュールを使うことで、プログラマは Excel で使われている CSV 形式に関して詳しい知識をもっていなくても、 "このデータを Excel で推奨されている形式で書いてください" とか、 "データを Excel で作成されたこのファイルから読み出してください" と言うことができます。プログラマはまた、他のアプリケーションが解釈できる CSV 形式を記述したり、独自の特殊な目的をもった CSV 形式を定義することができます。

csv モジュールの reader および writer オブジェクトはシーケンス型を読み書きします。プログラマは DictReader や DictWriter クラスを使うことで、データを辞書形式で読み書きすることもできます。

参考

PEP 305 [https://peps.python.org/pep-0305/] - CSV File API

Python へのこのモジュールの追加を提案している Python 改良案 (PEP: Python Enhancement Proposal)。

モジュールコンテンツ

csv モジュールでは以下の関数を定義しています:

csv.reader(csvfile, dialect='excel', **fmtparams)

Return a reader object that will process lines from the given csvfile. A csvfile must be an iterable of strings, each in the reader's defined csv format. A csvfile is most commonly a file-like object or list. If csvfile is a file object, it should be opened with newline=''. [1] An optional dialect parameter can be given which is used to define a set of parameters specific to a particular CSV dialect. It may be an instance of a subclass of the Dialect class or one of the strings returned by the list_dialects() function. The other optional fmtparams keyword arguments can be given to override individual formatting parameters in the current dialect. For full details about the dialect and formatting parameters, see section Dialect クラスと書式化パラメータ.

csv ファイルから読み込まれた各行は、文字列のリストとして返されます。QUOTE_NONNUMERIC フォーマットオプションが指定された場合を除き、データ型の変換が自動的に行われることはありません (このオプションが指定された場合、クォートされていないフィールドは浮動小数点数に変換されます)。

短い利用例:

>>> import csv
>>> with open('eggs.csv', newline='') 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

csv.writer(csvfile, dialect='excel', **fmtparams)

ユーザが与えたデータをデリミタで区切られた文字列に変換し、与えられたファイルオブジェクトに書き込むための writer オブジェクトを返します。 csvfile は write() メソッドを持つ任意のオブジェクトです。 csvfile がファイルオブジェクトの場合、 newline='' として開くべきです [1] 。オプションとして dialect 引数を与えることができ、利用するCSV表現形式(dialect)を指定することができます。 dialect パラメータは Dialect クラスのサブクラスのインスタンスか、 list_dialects() 関数が返す文字列の1つにすることができます。別のオプション引数である fmtparams キーワード引数は、現在の表現形式における個々の書式パラメータを上書きするために与えることができます。dialect と書式パラメータについての詳細は、 Dialect クラスと書式化パラメータ 節を参照してください。 DB API を実装するモジュールとのインターフェースを可能な限り容易にするために、 None は空文字列として書き込まれます。この処理は可逆な変換ではありませんが、SQL で NULL データ値を CSV にダンプする処理を、 cursor.fetch* 呼び出しによって返されたデータを前処理することなく簡単に行うことができます。他の非文字列データは、書き出される前に str() を使って文字列に変換されます。

短い利用例:

import csv
with open('eggs.csv', 'w', newline='') 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'])

csv.register_dialect(name[, dialect[, **fmtparams]])

dialect を name と関連付けます。 name は文字列でなければなりません。表現形式(dialect)は Dialect のサブクラスを渡すか、またはキーワード引数 fmtparams 、もしくは両方で指定できますが、キーワード引数の方が優先されます。表現形式と書式化パラメータについての詳細は、 Dialect クラスと書式化パラメータ 節を参照してください。

csv.unregister_dialect(name)

name に関連づけられた表現形式を表現形式レジストリから削除します。 name が表現形式名でない場合には Error を送出します。

csv.get_dialect(name)

name に関連づけられた表現形式を返します。 name が表現形式名でない場合には Error を送出します。この関数は不変の Dialect を返します。

csv.list_dialects()

登録されている全ての表現形式を返します。

csv.field_size_limit([new_limit])

パーサが許容する現在の最大フィールドサイズを返します。 new_limit が渡されたときは、その値が新しい上限になります。

csv モジュールでは以下のクラスを定義しています:

class csv.DictReader(f, fieldnames=None, restkey=None, restval=None, dialect='excel', *args, **kwds)

通常の reader のように動作しますが、個々の行の情報を dict にマップするオブジェクトを生成します。マップのキーは省略可能な fieldnames パラメータで与えられます。

The fieldnames parameter is a sequence. If fieldnames is omitted, the values in the first row of file f will be used as the fieldnames and will be omitted from the results. If fieldnames is provided, they will be used and the first row will be included in the results. Regardless of how the fieldnames are determined, the dictionary preserves their original ordering.

行がフィールド名より多くのフィールドを持っていた場合、残りのデータはリストに入れられて、 restkey により指定されたフィールド名 (デフォルトでは None) で保存されます。空白でない行がフィールド名よりも少ないフィールドしか持たない場合、足りない値は restval の値 (デフォルトは None ) によって埋められます。

その他の省略可能またはキーワード形式のパラメータは、ベースになっている reader インスタンスに渡されます。

fieldnames に渡された引数がイテレータの場合、 list に変換されます。

バージョン 3.6 で変更: 返される行の型は OrderedDict になりました。

バージョン 3.8 で変更: 返される行の型は dict になりました。

短い利用例:

>>> import csv
>>> with open('names.csv', newline='') 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'}

class csv.DictWriter(f, fieldnames, restval='', extrasaction='raise', dialect='excel', *args, **kwds)

通常の writer のように動作しますが、辞書を出力行にマップするオブジェクトを生成します。 fieldnames パラメータは、writerow() メソッドに渡された辞書の値がどのような順番でファイル f に書かれるかを指定するキーの sequence です。 writerow() メソッドに渡された辞書に fieldnames には存在しないキーが含まれている場合、オプションの extrasaction パラメータによってどんな動作を行うかが指定されます。この値がデフォルト値である 'raise' に設定されている場合、 ValueError が送出されます。 'ignore' に設定されている場合、辞書の余分な値は無視されます。その他のパラメータはベースになっている writer インスタンスに渡されます。

DictReader クラスとは異なり、 DictWriter の fieldnames パラメータは省略可能ではありません。

fieldnames に渡された引数がイテレータの場合、 list に変換されます。

短い利用例:

import csv

with open('names.csv', 'w', newline='') 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'})

class csv.Dialect

Dialect クラスはコンテナクラスです。その属性に、ダブルクォート、空白文字、デリミタなどの扱い方に関する情報を含みます。CSV には厳密な規格がないため、アプリケーションによって生成される CSV データはそれぞれ僅かに異なります。 Dialect クラスのインスタンスは reader と writer のインスタンスの挙動を定義します。

All available Dialect names are returned by list_dialects(), and they can be registered with specific reader and writer classes through their initializer (__init__) functions like this:

import csv

with open('students.csv', 'w', newline='') as csvfile:
    writer = csv.writer(csvfile, dialect='unix')

class csv.excel

excel クラスは Excel で生成される CSV ファイルの通常のプロパティを定義します。これは 'excel' という名前の dialect として登録されています。

class csv.excel_tab

excel_tab クラスは Excel で生成されるタブ分割ファイルの通常のプロパティを定義します。これは 'excel-tab' という名前の dialect として登録されています。

class csv.unix_dialect

unix_dialect クラスは UNIX システムで生成される CSV ファイルの通常のプロパティ (行終端記号として '\n' を用い全てのフィールドをクォートするもの) を定義します。これは 'unix' という名前の dialect として登録されています。

Added in version 3.2.

class csv.Sniffer

Sniffer クラスは CSV ファイルの書式を推理するために用いられるクラスです。

Sniffer クラスではメソッドを二つ提供しています:

sniff(sample, delimiters=None)

与えられた sample を解析し、発見されたパラメータを反映した Dialect サブクラスを返します。オプションの delimiters パラメータを与えた場合、有効なデリミタ文字を含んでいるはずの文字列として解釈されます。

has_header(sample)

Analyze the sample text (presumed to be in CSV format) and return True if the first row appears to be a series of column headers. Inspecting each column, one of two key criteria will be considered to estimate if the sample contains a header:

2番目からn番目の行は数値を含みます。

the second through n-th rows contain strings where at least one value's length differs from that of the putative header of that column.

1 行目の後の 20 行がサンプリングされます。半分以上の行 + 列が条件を満たす場合、 True が返されます。

注釈

このメソッドは大雑把なヒューリスティックであり、結果が偽陽性や偽陰性である可能性があります。

Sniffer の利用例:

with open('example.csv', newline='') as csvfile:
    dialect = csv.Sniffer().sniff(csvfile.read(1024))
    csvfile.seek(0)
    reader = csv.reader(csvfile, dialect)
    # ... process CSV file contents here ...

csv モジュールでは以下の定数を定義しています:

csv.QUOTE_ALL

writer オブジェクトに対し、全てのフィールドをクオートするように指示します。

csv.QUOTE_MINIMAL

writer オブジェクトに対し、 delimiter 、 quotechar または lineterminator に含まれる任意の文字のような特別な文字を含むフィールドだけをクオートするように指示します。

csv.QUOTE_NONNUMERIC

writer オブジェクトに対し、全ての非数値フィールドをクオートするように指示します。

reader オブジェクトに、クォーテーションで囲まれていないすべてのフィールドを float 型に変換するよう指示します。

csv.QUOTE_NONE

writer オブジェクトに対し、フィールドを決してクオートしないように指示します。現在の delimiter が出力データ中に現れた場合、現在設定されている escapechar 文字が前に付けられます。 escapechar がセットされていない場合、エスケープが必要な文字に遭遇した writer は Error を送出します。

reader オブジェクトに、クオート文字に対する特殊処理を行わないよう指示します。

csv.QUOTE_NOTNULL

Instructs writer objects to quote all fields which are not None. This is similar to QUOTE_ALL, except that if a field value is None an empty (unquoted) string is written.

Instructs reader objects to interpret an empty (unquoted) field as None and to otherwise behave as QUOTE_ALL.

Added in version 3.12.

csv.QUOTE_STRINGS

Instructs writer objects to always place quotes around fields which are strings. This is similar to QUOTE_NONNUMERIC, except that if a field value is None an empty (unquoted) string is written.

Instructs reader objects to interpret an empty (unquoted) string as None and to otherwise behave as QUOTE_NONNUMERIC.

Added in version 3.12.

csv モジュールでは以下の例外を定義しています:

exception csv.Error

全ての関数において、エラーが検出された際に送出される例外です。

Dialect クラスと書式化パラメータ

To make it easier to specify the format of input and output records, specific formatting parameters are grouped together into dialects. A dialect is a subclass of the Dialect class containing various attributes describing the format of the CSV file. When creating reader or writer objects, the programmer can specify a string or a subclass of the Dialect class as the dialect parameter. In addition to, or instead of, the dialect parameter, the programmer can also specify individual formatting parameters, which have the same names as the attributes defined below for the Dialect class.

Dialect は以下の属性をサポートしています:

Dialect.delimiter

フィールド間を分割するのに用いられる 1 文字からなる文字列です。デフォルトでは ',' です。

Dialect.doublequote

フィールド内に現れた quotechar のインスタンスで、クオートではないその文字自身でなければならない文字をどのようにクオートするかを制御します。 True の場合、この文字は二重化されます。 False の場合、 escapechar は quotechar の前に置かれます。デフォルトでは True です。

出力においては、 doublequote が False で escapechar がセットされていない場合、フィールド内に quotechar が現れると Error が送出されます。

Dialect.escapechar

writer が、 quoting が QUOTE_NONE に設定されている場合に delimiter をエスケープするため、および、 doublequote が False の場合に quotechar をエスケープするために用いられる、 1 文字からなる文字列です。読み込み時には escapechar はそれに引き続く文字の特別な意味を取り除きます。デフォルトでは None で、エスケープを行ないません。

バージョン 3.11 で変更: 空の escapechar は許可されていません。

Dialect.lineterminator

writer が作り出す各行を終端する際に用いられる文字列です。デフォルトでは '\r\n' です。

注釈

reader は '\r' または '\n' のどちらかを行末と認識するようにハードコードされており、 lineterminator を無視します。この振る舞いは将来変更されるかもしれません。

Dialect.quotechar

delimiter や quotechar といった特殊文字を含むか、改行文字を含むフィールドをクオートする際に用いられる 1 文字からなる文字列です。デフォルトでは '"' です。

バージョン 3.11 で変更: 空の quotechar は許可されていません。

Dialect.quoting

クオートがいつ writer によって生成されるか、また reader によって認識されるかを制御します。QUOTE_* constants のいずれかをとることができ、デフォルトでは QUOTE_MINIMAL です。

Dialect.skipinitialspace

True の場合、 delimiter の直後に続く空白は無視されます。デフォルトでは False です。

Dialect.strict

True の場合、 不正な CSV 入力に対して Error を送出します。デフォルトでは False です。

reader オブジェクト

reader オブジェクト(DictReader インスタンス、および reader() 関数によって返されたオブジェクト) は、以下の public なメソッドを持っています:

csvreader.__next__()

reader の反復可能なオブジェクトから、現在の表現形式 (Dialect) に基づいて次の行を解析してリスト（オブジェクトが reader() から返された場合）または辞書 （ DictReader のインスタンスの場合）として返します。通常は next(reader) のようにして呼び出すことになります。

reader オブジェクトには以下の公開属性があります:

csvreader.dialect

パーサで使われる表現形式の読み出し専用の記述です。

csvreader.line_num

ソースイテレータから読んだ行数です。この数は返されるレコードの数とは、レコードが複数行に亘ることがあるので、一致しません。

DictReader オブジェクトは、以下の public な属性を持っています:

DictReader.fieldnames

オブジェクトを生成するときに渡されなかった場合、この属性は最初のアクセス時か、ファイルから最初のレコードを読み出したときに初期化されます。

writer オブジェクト

writer オブジェクト(DictWriter インスタンス、および writer() 関数によって返されたオブジェクト) は、以下の public なメソッドを持っています: row には、 writer オブジェクトの場合には文字列か数値のイテラブルを指定し、 DictWriter オブジェクトの場合はフィールド名をキーとして対応する文字列か数値を格納した辞書オブジェクトを指定します(数値は str() で変換されます)。複素数を出力する場合、値をかっこで囲んで出力します。このため、CSV ファイルを読み込むアプリケーションで（そのアプリケーションが複素数をサポートしていたとしても）問題が発生する場合があります。

csvwriter.writerow(row)

現在の表現形式 (Dialect.)に沿ってフォーマットされた row パラメータを writer のファイルオブジェクトに書き込みます。ファイルオブジェクトの write メソッドを呼び出した際の戻り値を返します。

バージョン 3.5 で変更: 任意のイテラブルのサポートの追加。

csvwriter.writerows(rows)

rows 引数 (上で解説した row オブジェクトのイテラブル) の全ての要素を現在の表現形式に基づいて書式化し、writer のファイルオブジェクトに書き込みます。

writer オブジェクトには以下の公開属性があります:

csvwriter.dialect

writer で使われる表現形式の読み出し専用の記述です。

DictWriter のオブジェクトは以下の public メソッドを持っています:

DictWriter.writeheader()

Write a row with the field names (as specified in the constructor) to the writer's file object, formatted according to the current dialect. Return the return value of the csvwriter.writerow() call used internally.

Added in version 3.2.

バージョン 3.8 で変更: writeheader() は内部的に利用している csvwriter.writerow() メソッドの返り値を返すようになりました。

使用例

最も簡単な CSV ファイル読み込みの例です:

import csv
with open('some.csv', newline='') as f:
    reader = csv.reader(f)
    for row in reader:
        print(row)

別の書式での読み込み:

import csv
with open('passwd', newline='') as f:
    reader = csv.reader(f, delimiter=':', quoting=csv.QUOTE_NONE)
    for row in reader:
        print(row)

上に対して、単純な書き込みのプログラム例は以下のようになります。

import csv
with open('some.csv', 'w', newline='') as f:
    writer = csv.writer(f)
    writer.writerows(someiterable)

open() が CSV ファイルの読み込みに使われるため、ファイルはデフォルトではシステムのデフォルトエンコーディングでユニコード文字列にデコードされます (locale.getencoding() を参照)。他のエンコーディングを用いてデコードするには、open の引数 encoding を設定して、以下のようにします:

import csv
with open('some.csv', newline='', encoding='utf-8') as f:
    reader = csv.reader(f)
    for row in reader:
        print(row)

システムのデフォルトエンコーディング以外で書き込む場合も同様です。出力ファイルを開く際に引数 encoding を明示してください。

新しい表現形式の登録:

import csv
csv.register_dialect('unixpwd', delimiter=':', quoting=csv.QUOTE_NONE)
with open('passwd', newline='') as f:
    reader = csv.reader(f, 'unixpwd')

もう少し手の込んだ reader の使い方 --- エラーを捉えてレポートします。

import csv, sys
filename = 'some.csv'
with open(filename, newline='') as f:
    reader = csv.reader(f)
    try:
        for row in reader:
            print(row)
    except csv.Error as e:
        sys.exit('file {}, line {}: {}'.format(filename, reader.line_num, e))

このモジュールは文字列の解析は直接サポートしませんが、簡単にできます。

import csv
for row in csv.reader(['one,two,three']):
    print(row)

脚注

[1] (1,2)

newline='' が指定されない場合、クォートされたフィールド内の改行は適切に解釈されず、書き込み時に \r\n を行末に用いる処理系では余分な \r が追加されてしまいます。csv モジュールは独自 (universal) の改行処理を行うため、newline='' を指定することは常に安全です。

configparser --- Configuration file parser

ソースコード: Lib/configparser.py [https://github.com/python/cpython/tree/3.12/Lib/configparser.py]

このモジュールは、 Microsoft Windows の INI ファイルに似た構造を持ったベーシックな設定用言語を実装した ConfigParser クラスを提供します。このクラスを使ってユーザーが簡単にカスタマイズできる Python プログラムを作ることができます。

注釈

このライブラリでは、Windowsのレジストリ用に拡張された INI 文法はサポート していません 。

参考

モジュール tomllib

TOML is a well-specified format for application configuration files. It is specifically designed to be an improved version of INI.

shlex モジュール

アプリケーション設定ファイルにも使える、Unix シェルに似たミニ言語の作成を支援します。

json モジュール

The json module implements a subset of JavaScript syntax which is sometimes used for configuration, but does not support comments.

クイックスタート

次のような、非常に簡単な設定ファイルを例に考えましょう:

[DEFAULT]
ServerAliveInterval = 45
Compression = yes
CompressionLevel = 9
ForwardX11 = yes

[forge.example]
User = hg

[topsecret.server.example]
Port = 50022
ForwardX11 = no

INI ファイルの構造は 下のセクション で解説します。基本的に、ファイルは複数のセクションからなり、各セクションは複数のキーと値を持ちます。 configparser のクラス群はそれらのファイルを読み書きできます。まずは上のような設定ファイルをプログラムから作成してみましょう。

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

この例でわかるように、config parser は辞書のように扱うことができます。辞書との違いは 後に 説明しますが、このインターフェイスは辞書に対して期待するのととても近い動作をします。

これで設定ファイルを作成して保存できました。次はこれを読み込み直して、中のデータを取り出してみましょう。

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

上の例からわかるように、API はとても直感的です。唯一の魔術は、DEFAULT セクションが他の全てのセクションのためのデフォルト値を提供していることです [1]。 また、セクション内の各キーは大文字小文字を区別せず、全て小文字で保存されていることにも注意してください [1]。

It is possible to read several configurations into a single 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.

>>> another_config = configparser.ConfigParser()
>>> another_config.read('example.ini')
['example.ini']
>>> another_config['topsecret.server.example']['Port']
'50022'
>>> another_config.read_string("[topsecret.server.example]\nPort=48484")
>>> another_config['topsecret.server.example']['Port']
'48484'
>>> another_config.read_dict({"topsecret.server.example": {"Port": 21212}})
>>> another_config['topsecret.server.example']['Port']
'21212'
>>> another_config['topsecret.server.example']['ForwardX11']
'no'

This behaviour is equivalent to a ConfigParser.read() call with several files passed to the filenames parameter.

サポートされるデータ型

Config parser は値のデータ型について何も推論せず、常に文字列のまま内部に保存します。他のデータ型が必要な場合は自分で変換する必要があります:

>>> int(topsecret['Port'])
50022
>>> float(topsecret['CompressionLevel'])
9.0

このタスクはとても一般的なため、設定パーサーでは整数、浮動小数点数、真偽値を扱うための手頃なゲッターメソッドが提供されています。真偽値の扱いは一筋縄ではいきません。文字列を bool() に渡しても、 bool('False') が True になってしまいます。そこで config parser は getboolean() を提供しています。このメソッドは大文字小文字を区別せず、 'yes'/'no'、'on'/'off'、'true'/'false'、'1'/'0' を真偽値として認識します [1]。例えば:

>>> topsecret.getboolean('ForwardX11')
False
>>> config['forge.example'].getboolean('ForwardX11')
True
>>> config.getboolean('forge.example', 'Compression')
True

config parser では、 getboolean() 以外に getint() と getfloat() メソッドも提供されています。独自のコンバーターの登録、提供されたメソッドのカスタマイズもできます。 [1]

代替値

As with a dictionary, you can use a section's get() method to provide fallback values:

>>> topsecret.get('Port')
'50022'
>>> topsecret.get('CompressionLevel')
'9'
>>> topsecret.get('Cipher')
>>> topsecret.get('Cipher', '3des-cbc')
'3des-cbc'

デフォルト値は代替値よりも優先されることに注意してください。例えば上の例では、'CompressionLevel' キーは 'DEFAULT' セクションにしか存在しません。その値を 'topsecret.server.example' から取得しようとした場合、代替値を指定しても常にデフォルト値を返します:

>>> topsecret.get('CompressionLevel', '3')
'9'

One more thing to be aware of is that the parser-level get() method provides a custom, more complex interface, maintained for backwards compatibility. When using this method, a fallback value can be provided via the fallback keyword-only argument:

>>> config.get('forge.example', 'monster',
...            fallback='No such things as monsters')
'No such things as monsters'

同様の fallback 引数を、getint() 、 getfloat() と getboolean() メソッドでも使えます。例えば:

>>> 'BatchMode' in topsecret
False
>>> topsecret.getboolean('BatchMode', fallback=True)
True
>>> config['DEFAULT']['BatchMode'] = 'no'
>>> topsecret.getboolean('BatchMode', fallback=True)
False

サポートするINI ファイルの構造

A configuration file consists of sections, each led by a [section] header, followed by key/value entries separated by a specific string (= or : by default [1]). By default, section names are case sensitive but keys are not [1]. Leading and trailing whitespace is removed from keys and values. Values can be omitted if the parser is configured to allow it [1], 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 ConfigParser.SECTCRE.

設定ファイルには先頭に特定の文字 (デフォルトでは # および ; [1]) をつけてコメントをつけることができます。コメントは、他の内容がない行に置くことができ、インデントされていても構いません。[1]

例えば:

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

値の補間

コア機能に加えて、 ConfigParser は補間(interpolation, 内挿とも)をサポートします。これは get() コールが値を返す前に、その値に対して前処理を行えることを意味します。

class configparser.BasicInterpolation

ConfigParser が使用するデフォルト実装です。値に、同じセクションか特別なデフォルトセクション中 [1] の他の値を参照するフォーマット文字列を含めることができます。追加のデフォルト値を初期化時に提供できます。

例えば:

[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%%

上の例では、 interpolation に BasicInterpolation() を設定した ConfigParser が %(home_dir)s を home_dir の値(このケースでは /Users )として解決しています、その結果 %(my_dir)s は /Users/lumberjack になります。全ての補間は必要に応じて実行されるため、設定ファイル中で参照の連鎖をもつキーを特定の順序で記述する必要はありません。

interpolation に None を設定すれば、パーサーは単に my_pictures の値として %(my_dir)s/Pictures を返し、my_dir の値として %(home_dir)s/lumberjack を返します。

class configparser.ExtendedInterpolation

zc.buildout で使用されるような、より高度な文法を実装した補間ハンドラの別の選択肢です。拡張された補間は、他のセクション中の値を示すのに ${section:option} と書けます。補間は複数のレベルに及べます、利便性のために、もし section: の部分が省略されると、現在のセクションがデフォルト値となります(スペシャルセクション中のデフォルト値を使用することもできます)。

たとえば、上記の basic interpolation で指定した設定は、extended interpolation を使うと下記のようになります:

[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

他のセクションから値を持ってくることもできます:

[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}

マップ型プロトコルアクセス

Added in version 3.2.

マップ型プロトコルアクセスは、カスタムオブジェクトを辞書であるかのように使うための機能の総称です。 configparser の場合、マップ型インターフェースの実装は parser['section']['option'] 表記を使います。

とくに、parser['section'] はパーサー内のそのセクションのデータへのプロキシを返します。つまり、値はコピーされるのではなく必要に応じてオリジナルのパーサーから取られます。さらに重要なことに、セクションのプロキシの値が変更されると、オリジナルのパーサー中の値が実際に変更されます。

configparser は可能な限り実際の辞書と近い振る舞いをします。マップ型インターフェースは MutableMapping を矛盾なく完成します。しかし、考慮するべき違いがいくつかあります:

デフォルトでは、セクション内の全てのキーは大文字小文字の区別なくアクセスできます [1]。例えば、for option in parser["section"] は optionxform されたオプションキー名のみを yield します。つまり小文字のキーがデフォルトです。同時に、キー 'a' を含むセクションにおいて、どちらの式も True を返します:

"a" in parser["section"]
"A" in parser["section"]

全てのセクションは DEFAULTSECT 値を持ち、すなわちセクションで .clear() してもセクションは見た目上空になりません。これは、デフォルト値は (技術的にはそこにないので) セクションから削除できないためです。デフォルト値が上書きされた場合、それが削除されるとデフォルト値が再び見えるようになります。デフォルト値を削除しようとすると KeyError が発生します。

DEFAULTSECT はパーサーから取り除けません:

削除しようとすると ValueError が発生します。

parser.clear() はこれをそのまま残し、

parser.popitem() がこれを返すことはありません。

parser.get(section, option, **kwargs) - 第二引数は代替値では ありません。ただし、セクションごとの get() メソッドはマップ型プロトコルと旧式の configparser API の両方に互換です。

parser.items() はマップ型プロトコルと互換です (DEFAULTSECT を含む section_name, section_proxy 対のリストを返します)。ただし、このメソッドは parser.items(section, raw, vars) のようにして引数を与えることでも呼び出せます。後者の呼び出しは指定された section の option, value 対のリストを、(raw=True が与えられない限り) 全ての補間を展開して返します。

マップ型プロトコルは、既存のレガシーな API の上に実装されているので、オリジナルのインターフェースを上書きする派生クラスもまたは期待どおりにはたらきます。

パーサーの振る舞いをカスタマイズする

INI フォーマットの変種は、それを使うアプリケーションの数と同じくらい多く存在します。 configparser は、可能な限り広い範囲の INI スタイルを集めた集合をサポートするために、非常に役立ちます。デフォルトの機能は主に歴史的背景によって決められたので、機能によってはカスタマイズしてお使いください。

The most common way to change the way a specific config parser works is to use the __init__() options:

defaults, デフォルト値: None

このオプションは最初に DEFAULT セクションに加えられるキー-値の対の辞書を受け付けます。

Hint: if you want to specify default values for a specific section, use read_dict() before you read the actual file.

dict_type, デフォルト値: dict

このオプションはマップ型プロトコルの振る舞い方や書き込まれる設定ファイルの見た目に大きく影響します。標準の辞書では、全てのセクションはパーサーに加えられた順に並びます。同じことがセクション内のオプションにも言えます。

セクションとオプションをライトバック時にソートするためなどに、別の辞書型も使えます。

注意: 一度の操作でキー-値の対を複数追加する方法もあります。そのような操作に普通の辞書を使うと、キーの並びは挿入順になります。例えば:

>>> 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']

allow_no_value, デフォルト値: False

一部の設定ファイルには値のない設定項目がありますが、それ以外は ConfigParser がサポートする文法に従います。コンストラクタの allow_no_value 引数で、そのような値を許可することができます。

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

delimiters, デフォルト値: ('=', ':')

デリミタはセクション内でキーを値から区切る部分文字列です。行中で最初に現れた区切り部分文字列がデリミタと見なされます。つまり値にはデリミタを含めることができます (キーには含めることができません)。

ConfigParser.write() の space_around_delimiters 引数も参照してください。

comment_prefixes, デフォルト値: ('#', ';')

inline_comment_prefixes, デフォルト値: None

コメント接頭辞は設定ファイル中で有効なコメントの開始を示す文字列です。comment_prefixes は他の内容がない行 (インデントは自由) にのみ使用でき、inline_comment_prefixes は任意の有効な値 (例えば、セクション名、オプション、空行も可能) の後に使えます。デフォルトではインラインコメントは無効化されていて、'#' と ';' を行全体のコメントに使用します。

バージョン 3.2 で変更: 以前のバージョンの configparser の振る舞いは comment_prefixes=('#',';') および inline_comment_prefixes=(';',) に該当します。

設定パーサーはコメント接頭辞のエスケープをサポートしないので、inline_comment_prefixes はユーザーがコメント接頭辞として使われる文字を含むオプション値を指定するのを妨げる可能性があります。疑わしい場合には、inline_comment_prefixes を設定しないようにしてください。どのような状況でも、複数行にわたる値で、行の先頭にコメント接頭辞文字を保存する唯一の方法は、次の例のように接頭辞を補間することです:

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

strict, デフォルト値: True

When set to True, the parser will not allow for any section or option duplicates while reading from a single source (using read_file(), read_string() or read_dict()). It is recommended to use strict parsers in new applications.

バージョン 3.2 で変更: 以前のバージョンの configparser の振る舞いは strict=False に該当します。

empty_lines_in_values, デフォルト値: True

設定パーサーでは、キーよりもその値を深くインデントするかぎり、複数行にまたがる値を使えます。デフォルトのパーサーはさらにその値の間に空行を置けます。同時に、キーは読みやすくするため任意にインデントできます。結果として、設定ファイルが大きく複雑になったとき、ユーザーがファイル構造を見失いやすいです。この例をご覧ください:

[Section]
key = multiline
  value with a gotcha

 this = is still a part of the multiline value of 'key'

これは特にプロポーショナルフォントを使ってファイルを編集しているユーザーにとって問題になることがあります。だから、アプリケーションの値に空行が必要ないなら、空行を認めないべきです。これによって空行で必ずキーが分かれます。上の例では、2 つのキー、key および this が作られます。

default_section, デフォルト値: configparser.DEFAULTSECT (すなわち: "DEFAULT")

他のセクションのデフォルト値や補間目的での特別なセクションを認める慣行はこのライブラリの明確なコンセプトの一つで、ユーザーは複雑で宣言的な設定を作成できます。このセクションは通常 "DEFAULT" と呼ばれますが、任意の有効なセクション名を指すようにカスタマイズできます。典型的な値には "general" や "common" があります。与えられた名前はソースを読み込む際にデフォルトセクションを認識するのに使われ、設定をファイルに書き戻すときにも使われます。現在の値は parser_instance.default_section 属性から取り出すことができ、実行時 (すなわちファイルを別のフォーマットに変換するとき) に変更することもできます。

interpolation, デフォルト値: configparser.BasicInterpolation

補間の振る舞いは、 interpolation 引数を通してカスタムハンドラを与えることでカスタマイズできます。 None 引数を使うと補間を完全に無効にできます。 ExtendedInterpolation() は、 zc.buildout に影響を受けたより高度な補間を提供します。この話題に 特化したドキュメントのセクション をご覧ください。 RawConfigParser のデフォルト値は None です。

converters, デフォルト値: 未設定

Config parsers provide option value getters that perform type conversion. By default getint(), getfloat(), and 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 {'decimal': decimal.Decimal} would add getdecimal() on both the parser object and all section proxies. In other words, it will be possible to write both parser_instance.getdecimal('section', 'key', fallback=0) and parser_instance['section'].getdecimal('key', 0).

コンバーターがパーサーの状態にアクセスする必要がある場合、設定パーサーサブクラスでメソッドとして実装することができます。このメソッドの名前が get から始まる場合、すべてのセクションプロキシで、辞書と互換性のある形式で利用できます (上記の getdecimal() の例を参照)。

これらのパーサー引数のデフォルト値を上書きすれば、さらに進んだカスタマイズができます。デフォルトはクラスで定義されているので、派生クラスや属性の代入で上書きできます。

ConfigParser.BOOLEAN_STATES

デフォルトでは、 getboolean() を使うことで、設定パーサーは以下の値を True と見なします: '1', 'yes', 'true', 'on' 。以下の値を False と見なします: '0', 'no', 'false', 'off' 。文字列と対応するブール値のカスタム辞書を指定することでこれを上書きできます。たとえば:

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

ほかの典型的なブール値ペアには accept/reject や enabled/disabled などがあります。

ConfigParser.optionxform(option)

このメソッドは読み込み、取得、設定操作のたびにオプション名を変換します。デフォルトでは名前を小文字に変換します。従って設定ファイルが書き込まれるとき、すべてのキーは小文字になります。それがふさわしくなければ、このメソッドを上書きしてください。例えば:

>>> 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']

注釈

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.

ConfigParser.SECTCRE

セクションヘッダを解析するのに使われる、コンパイルされた正規表現です。デフォルトでは [section] が "section" という名前にマッチします。空白はセクション名の一部と見なされるので、[  larch  ] は "  larch  " という名のセクションとして読み込まれます。これがふさわしくない場合、このメソッドを上書きしてください。例えば:

>>> 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']

注釈

ConfigParser オブジェクトはオプション行の認識に OPTCRE 属性も使いますが、これを上書きすることは推奨されません。上書きするとコンストラクタオプション allow_no_value および delimiters に干渉します。

レガシーな API の例

主に後方互換性問題の理由から、 configparser は get/set メソッドを明示するレガシーな API も提供します。メソッドを以下に示すように使うこともできますが、新しいプロジェクトではマップ型プロトコルでアクセスするのが望ましいです。レガシーな API は時折高度で、低レベルで、まったく直感的ではありません。

設定ファイルを書き出す例:

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)

設定ファイルを読み込む例:

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'))

補間するには、 ConfigParser を使ってください:

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

どちらの型の ConfigParsers でもデフォルト値が利用できます。使われているオプションがどこにも定義されていなければ、そのデフォルト値が補間に使われます。

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!"

ConfigParser オブジェクト

class 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={})

主要な設定パーサーです。defaults が与えられれば、その辞書の持つ初期値で初期化されます。dict_type が与えられれば、それがセクションの一覧、セクション中のオプション、およびデフォルト値の辞書オブジェクトを作成するのに使われます。

delimiters が与えられた場合、キーと値を分割する部分文字列の組み合わせとして使われます。comment_prefixes が与えられた場合、他の内容がない行のコメントに接頭する部分文字列の組み合わせとして使われます。コメントはインデントできます。inline_comment_prefixes が与えられた場合、非空行のコメントに接頭する部分文字列としての組み合わせとして使われます。

strict が True (デフォルト) であれば、パーサーは単一のソース (ファイル、文字列、辞書) 中にセクションやオプションの重複を認めず、 DuplicateSectionError や DuplicateOptionError を送出します。 empty_lines_in_values が False (デフォルト: True) なら、空行はそれぞれオプションの終わりを示します。 allow_no_value が True (デフォルト: False) なら、値のないオプションが受け付けられます。そのオプションの値は None となり、後端のデリミタを除いてシリアル化されます。

When default_section is given, it specifies the name for the special section holding default values for other sections and interpolation purposes (normally named "DEFAULT"). This value can be retrieved and changed at runtime using the 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 引数を通してカスタムハンドラを与えることでカスタマイズできます。 None 引数を使うと補間を完全に無効にできます。 ExtendedInterpolation() は、 zc.buildout に影響を受けたより高度な補間を提供します。この件に 特化したドキュメントのセクション を参照してください。

補間に使われるすべてのオプション名は、他のオプション名参照と同様に、 optionxform() メソッドを通して渡されます。例えば、 optionxform() のデフォルトの実装を使うと、値 foo %(bar)s と foo %(BAR)s は等しくなります。

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 get*() method on the parser object and section proxies.

バージョン 3.1 で変更: デフォルトの dict_type は collections.OrderedDict です。

バージョン 3.2 で変更: allow_no_value, delimiters, comment_prefixes, strict, empty_lines_in_values, default_section および interpolation が追加されました。

バージョン 3.5 で変更: converters 引数が追加されました。

バージョン 3.7 で変更: The defaults argument is read with 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 dict, since it now preserves insertion order.

defaults()

インスタンス全体で使われるデフォルト値の辞書を返します。

sections()

利用できるセクションのリストを返します。default section はリストに含まれません。

add_section(section)

section という名のセクションをインスタンスに追加します。与えられた名前のセクション名がすでに存在したら、 DuplicateSectionError が送出されます。 default section 名が渡されたら、 ValueError が送出されます。セクションの名前は文字列でなければなりません。そうでなければ、 TypeError が送出されます。

バージョン 3.2 で変更: 文字列でないセクション名は TypeError を送出します。

has_section(section)

指名された section が設定中に存在するかを示します。default section は認識されません。

options(section)

指定された section 中で利用できるオプションのリストを返します。

has_option(section, option)

与えられた section が存在し、与えられた option を含む場合、 True を返します。それ以外の場合には、 False を返します。指定された section が None または空文字列の場合、 DEFAULT が仮定されます。

read(filenames, encoding=None)

ファイル名の iterable を読み込んでパースしようと試みます。正常にパースできたファイル名のリストを返します。

もし filenames が文字列か bytes オブジェクトか path-like object なら、この引数は1つのファイル名として扱われます。 filenames 中に開けないファイルがある場合、そのファイルは無視されます。この挙動は、設定ファイルが置かれる可能性のある場所(例えば、 カレントディレクトリ、ホームディレクトリ、システム全体の設定を行うディレクトリ)のイテラブルを指定して、イテラブルの中で存在する全ての設定ファイルを読むことを想定して設計されています。

どの設定ファイルも存在しなかった場合、 ConfigParser のインスタンスは 空のデータセットを持ちます。初期値の設定ファイルを先に読み込んでおく必要があるアプリケーションでは、 オプションのファイルを読み込むために read() を呼ぶ前に 、まず read_file() を用いて必要なファイルを読み込んでください:

import configparser, os

config = configparser.ConfigParser()
config.read_file(open('defaults.cfg'))
config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')],
            encoding='cp1250')

バージョン 3.2 で変更: Added the encoding parameter. Previously, all files were read using the default encoding for open().

バージョン 3.6.1 で変更: filenames 引数が path-like object を受け入れるようになりました。

バージョン 3.7 で変更: filenames 引数が bytes オブジェクトを受け入れるようになりました。

read_file(f, source=None)

設定データを f から読み込んで解析します。f は Unicode 文字列を yield するイテラブル (例えばテキストモードで開かれたファイル) です。

Optional argument source specifies the name of the file being read. If not given and f has a name attribute, that is used for source; the default is '<???>'.

Added in version 3.2: readfp() を置き換えます。

read_string(string, source='<string>')

設定データを文字列から解析します。

オプションの引数 source はコンテキストにおける渡された文字列の名前を指定します。与えられなければ、'<string>' が使われます。これは一般にファイルシステムパスや URL にします。

Added in version 3.2.

read_dict(dictionary, source='<dict>')

辞書的な items() メソッドを提供する任意のオブジェクトから設定を読み込みます。キーはセクション名で、値はそのセクションに現れるキーと値をもつ辞書です。使われた辞書型が順序を保存するなら、セクションおよびそのキーは順に加えられます。値は自動で文字列に変換されます。

オプションの引数 source はコンテキストにおける渡された辞書の名前を指定します。与えられなければ、<dict> が使われます。

このメソッドを使ってパーサー間で状態をコピーできます。

Added in version 3.2.

get(section, option, *, raw=False, vars=None[, fallback])

指名された section の option の値を取得します。vars が提供されるなら、それは辞書でなければならず、(与えられたなら) vars, section, DEFAULTSECT 内からこの順で option が探索されます。fallback の値として None を与えられます。

raw が真でない時には、全ての '%' 置換は展開されてから返されます。置換後の値はオプションと同じ順序で探されます。

バージョン 3.2 で変更: 引数 raw, vars および fallback は、(特にマッピングプロトコルを使用するときに) ユーザーが第 3 引数を fallback フォールバックとして使おうとしないように、キーワード専用となりました。

getint(section, option, *, raw=False, vars=None[, fallback])

指定された section 中の option を整数に型強制する補助メソッドです。 raw, vars および fallback の説明は get() を参照してください。

getfloat(section, option, *, raw=False, vars=None[, fallback])

指定された section 中の option を浮動小数点数に型強制する補助メソッドです。 raw, vars および fallback の説明は get() を参照してください。

getboolean(section, option, *, raw=False, vars=None[, fallback])

指定された section 中の option をブール値に型強制する補助メソッドです。なお、このオプションで受け付けられる値はこのメソッドが True を返す '1', 'yes', 'true', および 'on',と、このメソッドが False を返す '0', 'no', 'false', and 'off' です。その他のいかなる値も ValueError を送出します。 raw, vars および fallback の説明は get() を参照してください。

items(raw=False, vars=None)

items(section, raw=False, vars=None)

section が与えられなければ、DEFAULTSECT を含めた section_name, section_proxy の対のリストを返します。

与えられれば、与えられた section 中のオプションの name, value の対のリストを返します。オプションの引数は get() メソッドに与えるものと同じ意味を持ちます。

バージョン 3.8 で変更: vars に現れる項目は結果に表れなくなりました。以前の挙動は、実際のパーサーオプションを補間のために与えられた変数と混合していました。

set(section, option, value)

与えられたセクションが存在すれば、与えられたオプションを指定された値に設定します。そうでなければ NoSectionError を送出します。 option および value は文字列でなければなりません。そうでなければ TypeError が送出されます。

write(fileobject, space_around_delimiters=True)

設定の表現を指定された file object に書き込みます。 fileobject は (文字列を受け付ける) テキストモードで開かれていなければなりません。この表現は後で read() を呼び出すことでパースできます。 space_around_delimiters が真なら、キーと値の間のデリミタはスペースで囲まれます。

注釈

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.

remove_option(section, option)

指定された option を指定された section から削除します。セクションが存在しなければ、 NoSectionError を送出します。オプションが存在して削除されれば、 True を返します。そうでなければ False を返します。

remove_section(section)

指定された section を設定から削除します。セクションが実際に存在すれば、True を返します。そうでなければ False を返します。

optionxform(option)

入力ファイルに現れた、またはクライアントコードで渡されたオプション名 option を内部構造で実際に使われる形式に変換します。デフォルトの実装では option の小文字版を返します。派生クラスでこれを上書きするか、クライアントコードでインスタンス上のこの名前の属性を設定して、この動作に影響を与えることができます。

このメソッドを使うためにパーサーを派生クラス化させる必要はなく、インスタンス上で、これを文字列引数をとって文字列を返す関数に設定できます。例えば、これを str に設定すると、オプション名に大文字小文字の区別をつけられます:

cfgparser = ConfigParser()
cfgparser.optionxform = str

なお、設定ファイルを読み込むとき、オプション名の周りの空白は optionxform() が呼び出される前に取り除かれます。

configparser.MAX_INTERPOLATION_DEPTH

The maximum depth for recursive interpolation for get() when the raw parameter is false. This is relevant only when the default interpolation is used.

RawConfigParser オブジェクト

class 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])

Legacy variant of the ConfigParser. It has interpolation disabled by default and allows for non-string section names, option names, and values via its unsafe add_section and set methods, as well as the legacy defaults= keyword argument handling.

バージョン 3.8 で変更: The default dict_type is dict, since it now preserves insertion order.

注釈

代わりに内部に保存する値の型を検査する ConfigParser を使うことを検討してください。補間を望まない場合、 ConfigParser(interpolation=None) を使用できます。

add_section(section)

インスタンスに section という名のセクションを追加します。与えられた名前のセクションがすでに存在すれば、 DuplicateSectionError が送出されます。 default section 名が渡されると、 ValueError が送出されます。

section の型は検査されないため、ユーザーは非文字列の名前付きセクションを作ることができます。この振る舞いはサポートされておらず、内部エラーを起こす可能性があります。

set(section, option, value)

与えられたセクションが存在していれば、オプションを指定された値に設定します。セクションが存在しなければ NoSectionError を発生させます。 RawConfigParser (あるいは raw パラメータをセットした ConfigParser) を文字列型でない値の 内部的な 格納場所として使うことは可能ですが、すべての機能 (置換やファイルへの出力を含む) がサポートされるのは文字列を値として使った場合だけです。

ユーザーは、このメソッドを使って非文字列の値をキーに代入できます。この振る舞いはサポートされておらず、非rawモードでの値の取得や、ファイルへの書き出しを試みた際にエラーの原因となりえます。このような代入を許さない マッピングプロトコルAPIを使用してください。

例外

exception configparser.Error

他の全ての configparser 例外の基底クラスです。

exception configparser.NoSectionError

指定したセクションが見つからなかった時に起きる例外です。

exception configparser.DuplicateSectionError

Exception raised if 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 __init__().

exception configparser.DuplicateOptionError

strict なパーサーで、単一の入力ファイル、文字列、辞書中に同じオプションが複数回現れたときに送出される例外です。これはミススペルや大文字小文字の区別に関係するエラー、例えば辞書の二つのキーが同じ大文字小文字の区別のない設定キーを表すこと、を捕捉します。

exception configparser.NoOptionError

指定されたオプションが指定されたセクションに見つからないときに送出される例外です。

exception configparser.InterpolationError

文字列の補間中に問題が起きた時に発生する例外の基底クラスです。

exception configparser.InterpolationDepthError

繰り返しの回数が MAX_INTERPOLATION_DEPTH を超えたために文字列補間が完了しなかったときに送出される例外です。 InterpolationError の派生クラスです。

exception configparser.InterpolationMissingOptionError

InterpolationError の派生クラスで、値が参照しているオプションが見つからない場合に発生する例外です。

exception configparser.InterpolationSyntaxError

置換がなされるソーステキストが要求された文法を満たさないときに送出される例外です。 InterpolationError の派生クラスです。

exception configparser.MissingSectionHeaderError

セクションヘッダを持たないファイルを構文解析しようとした時に起きる例外です。

exception configparser.ParsingError

ファイルの構文解析中にエラーが起きた場合に発生する例外です。

バージョン 3.12 で変更: The filename attribute and __init__() constructor argument were removed. They have been available using the name source since 3.2.

脚注

[1] (1,2,3,4,5,6,7,8,9,10,11)

設定パーサーは大々的にカスタマイズできます。脚注の参照で概説された挙動の変更に関心がある場合、Customizing Parser Behaviour セクションを参照してください。

tomllib --- Parse TOML files

Added in version 3.11.

ソースコード: Lib/tomllib [https://github.com/python/cpython/tree/3.12/Lib/tomllib]

このモジュールはTOML（Tom's Obvious Minimal Language, https://toml.io [https://toml.io/en/]）を解析するインターフェースを提供します。このモジュールはTOMLの書き出しはサポートしません。

参考

The Tomli-W package [https://pypi.org/project/tomli-w/] is a TOML writer that can be used in conjunction with this module, providing a write API familiar to users of the standard library marshal and pickle modules.

参考

The TOML Kit package [https://pypi.org/project/tomlkit/] is a style-preserving TOML library with both read and write capability. It is a recommended replacement for this module for editing already existing TOML files.

このモジュールは以下の関数を定義しています:

tomllib.load(fp, /, *, parse_float=float)

TOMLファイルを読み込みます。第1引数には読み込み可能なバイナリのファイルオブジェクトを指定します。戻り値は dict です。TOMLの型は conversion table を使用してPythonのデータ型に変換されます。

parse_float は、全てのデコードされる TOML の浮動小数点数文字列に対して呼ばれます。デフォルトでは、 float(num_str) と等価です。これは TOML 浮動小数点数に対して他のデータ型やパーサ (たとえば decimal.Decimal) を使うのに使えます。呼び出し可能オブジェクトは dict や list 以外を返す必要があり、そうでない場合は ValueError が送出されます。

無効なTOMLドキュメントの場合は TOMLDecodeError が送出されます。

tomllib.loads(s, /, *, parse_float=float)

str からTOMLを読み込みます。戻り値は dict です。TOMLの型は conversion table を使用してPythonのデータ型に変換されます。parse_float  引数は load() と同じ意味を持ちます。

無効なTOMLドキュメントの場合は TOMLDecodeError が送出されます。

次の例外がサポートされています:

exception tomllib.TOMLDecodeError

ValueError のサブクラスです。

使用例

TOMLファイルを解析します:

import tomllib

with open("pyproject.toml", "rb") as f:
    data = tomllib.load(f)

TOMLの文字列を解析します:

import tomllib

toml_str = """
python-version = "3.11.0"
python-implementation = "CPython"
"""

data = tomllib.loads(toml_str)

変換表

TOML

Python

TOMLドキュメント

辞書

string

str

整数

int

浮動小数点数

float （parse_float で設定可能）

boolean

真偽値型(bool)

オフセット付きの日時に日地

datetime.datetime（tzinfo 属性は datetime.timezone のインスタンスが設定される）

ローカルの日時

datetime.datetime（tzinfo 属性は None に設定される）

ローカルの日付

datetime.date

ローカルの時刻

datetime.time

配列

リスト

テーブル

辞書

インラインテーブル

辞書

テーブルの配列

辞書のリスト

netrc --- netrc file processing

ソースコード: Lib/netrc.py [https://github.com/python/cpython/tree/3.12/Lib/netrc.py]

netrc クラスは、Unix ftp プログラムや他の FTP クライアントで用いられる netrc ファイル形式を解析し、カプセル化 (encapsulate) します。

class netrc.netrc([file])

netrc のインスタンスやサブクラスのインスタンスは netrc ファイルのデータをカプセル化します。初期化の際の引数が存在する場合、解析対象となるファイルの指定になります。引数がない場合、 (os.path.expanduser() で特定される) ユーザのホームディレクトリ下にある .netrc が読み出されます。ファイルが見付からなかった場合は FileNotFoundError 例外が送出されます。解析エラーが発生した場合、ファイル名、行番号、解析を中断したトークンに関する情報の入った NetrcParseError を送出します。 POSIX システムにおいて引数を指定しない場合、ファイルのオーナシップやパーミッションが安全でない (プロセスを実行しているユーザ以外が所有者であるか、誰にでも読み書き出来てしまう) のに .netrc ファイル内にパスワードが含まれていると、 NetrcParseError を送出します。このセキュリティ的な振る舞いは、 ftp などの .netrc を使うプログラムと同じものです。

バージョン 3.4 で変更: POSIX パーミッションのチェックが追加されました。

バージョン 3.7 で変更: 引数で file が渡されなかったときは、 .netrc ファイルの場所を探すのに os.path.expanduser() が使われるようになりました。

バージョン 3.10 で変更: netrc try UTF-8 encoding before using locale specific encoding. The entry in the netrc file no longer needs to contain all tokens. The missing tokens' value default to an empty string. All the tokens and their values now can contain arbitrary characters, like whitespace and non-ASCII characters. If the login name is anonymous, it won't trigger the security check.

exception netrc.NetrcParseError

Exception raised by the netrc class when syntactical errors are encountered in source text. Instances of this exception provide three interesting attributes:

msg

Textual explanation of the error.

filename

The name of the source file.

lineno

The line number on which the error was found.

netrc オブジェクト

netrc インスタンスは以下のメソッドを持っています:

netrc.authenticators(host)

host の認証情報として、三要素のタプル (login, account, password) を返します。与えられた host に対するエントリが netrc ファイルにない場合、'default' エントリに関連付けられたタプルが返されます。host に対応するエントリがなく、default エントリもない場合、None を返します。

netrc.__repr__()

クラスの持っているデータを netrc ファイルの書式に従った文字列で出力します。(コメントは無視され、エントリが並べ替えられる可能性があります。)

netrc のインスタンスは以下の public なインスタンス変数を持っています:

netrc.hosts

ホスト名を (login, account, password) からなるタプルに対応づけている辞書です。'default' エントリがある場合、その名前の擬似ホスト名として表現されます。

netrc.macros

マクロ名を文字列のリストに対応付けている辞書です。

plistlib --- Generate and parse Apple .plist files

ソースコード: Lib/plistlib.py [https://github.com/python/cpython/tree/3.12/Lib/plistlib.py]

このモジュールは Apple (主に macOS と iOS) で使われる「プロパティーリスト」ファイルを読み書きするインターフェイスを提供します。このモジュールはバイナリと XML の plist ファイルの両方をサポートします。

プロパティーリスト (.plist) ファイル形式は基本的型のオブジェクト、たとえば辞書やリスト、数、文字列など、に対する単純な直列化です。たいてい、トップレベルのオブジェクトは辞書です。

plist ファイルを書き出したり解析したりするには dump() や load() 関数を利用します。

To work with plist data in bytes objects, use dumps() and loads().

値は文字列、整数、浮動小数点数、ブール型、タプル、リスト、辞書 (ただし文字列だけがキーになれます)、 bytes、bytearray または datetime.datetime のオブジェクトです。

バージョン 3.4 で変更: 新しい API。古い API は撤廃されました。バイナリ形式の plist がサポートされました。

バージョン 3.8 で変更: Support added for reading and writing UID tokens in binary plists as used by NSKeyedArchiver and NSKeyedUnarchiver.

バージョン 3.9 で変更: Old API removed.

参考

PList manual page [https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/PropertyLists/]

このファイル形式の Apple の文書。

このモジュールは以下の関数を定義しています:

plistlib.load(fp, *, fmt=None, dict_type=dict)

plist ファイルを読み込みます。fp は読み込み可能かつバイナリのファイルオブジェクトです。展開されたルートオブジェクト (通常は辞書です) を返します。

fmt はファイルの形式で、次の値が有効です。

None: ファイル形式を自動検出します

FMT_XML: XML ファイル形式です

FMT_BINARY: バイナリの plist 形式です

dict_type は、 plist ファイルから読み出された辞書に使われる型です。

FMT_XML 形式の XML データは xml.parsers.expat にある Expat パーサーを使って解析されます。不正な形式の XML に対して送出される可能性のある例外については、そちらの文書を参照してください。plist 解析器では、未知の要素は単純に無視されます。

バイナリ形式のパーサーは、ファイルを解析できない場合に InvalidFileException を送出します。

Added in version 3.4.

plistlib.loads(data, *, fmt=None, dict_type=dict)

Load a plist from a bytes object. See load() for an explanation of the keyword arguments.

Added in version 3.4.

plistlib.dump(value, fp, *, fmt=FMT_XML, sort_keys=True, skipkeys=False)

plist ファイルに value を書き込みます。Fp は、書き込み可能なバイナリファイルオブジェクトにしてください。

fmt 引数は plist ファイルの形式を指定し、次のいずれかの値をとることができます。

FMT_XML: XML 形式の plist ファイルです

FMT_BINARY: バイナリ形式の plist ファイルです

sort_keys が真 (デフォルト) の場合、辞書内のキーは、plist にソートされた順序で書き込まれます。偽の場合、ディクショナリのイテレートの順序で書き込まれます。

skipkeys が偽 (デフォルト) の場合、この関数は辞書のキーが文字列でない場合に TypeError を送出します。真の場合、そのようなキーは読み飛ばされます。

TypeError が、オブジェクトがサポート外の型のものであったりサポート外の型のオブジェクトを含むコンテナだった場合に、送出されます。

(バイナリの) plist ファイル内で表現できない整数値に対しては、 OverflowError が送出されます。

Added in version 3.4.

plistlib.dumps(value, *, fmt=FMT_XML, sort_keys=True, skipkeys=False)

value を plist 形式のバイトオブジェクトとして返します。この関数のキーワード引数の説明については、 dump() を参照してください。

Added in version 3.4.

以下のクラスが使用可能です:

class plistlib.UID(data)

Wraps an int. This is used when reading or writing NSKeyedArchiver encoded data, which contains UID (see PList manual).

It has one attribute, data, which can be used to retrieve the int value of the UID. data must be in the range 0 <= data < 2**64.

Added in version 3.8.

以下の定数が利用可能です:

plistlib.FMT_XML

plist ファイルの XML 形式です

Added in version 3.4.

plistlib.FMT_BINARY

plist ファイルのバイナリ形式です

Added in version 3.4.

使用例

plist を作ります:

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())

plist を解析します:

import plistlib

plist = b"""<plist version="1.0">
<dict>
    <key>foo</key>
    <string>bar</string>
</dict>
</plist>"""
pl = plistlib.loads(plist)
print(pl["foo"])

暗号関連のサービス

The modules described in this chapter implement various algorithms of a cryptographic nature. They are available at the discretion of the installation. On Unix systems, the crypt module may also be available. Here's an overview:

hashlib --- Secure hashes and message digests

ハッシュアルゴリズム

使用法

Constructors

属性

Hash Objects

SHAKE 可変長ダイジェスト

File hashing

鍵導出

BLAKE2

ハッシュオブジェクトの作成

定数

使用例

簡単なハッシュ化

Using different digest sizes

Keyed hashing

Randomized hashing

Personalization

ツリーモード

クレジット:

hmac --- Keyed-Hashing for Message Authentication

secrets --- Generate secure random numbers for managing secrets

乱数

トークンの生成

トークンは何バイト使うべきか？

その他の関数

レシピとベストプラクティス

hashlib --- Secure hashes and message digests

ソースコード: Lib/hashlib.py [https://github.com/python/cpython/tree/3.12/Lib/hashlib.py]

This module implements a common interface to many different secure hash and message digest algorithms. Included are the FIPS secure hash algorithms SHA1, SHA224, SHA256, SHA384, SHA512, (defined in the FIPS 180-4 standard [https://csrc.nist.gov/publications/detail/fips/180/4/final]), the SHA-3 series (defined in the FIPS 202 standard [https://csrc.nist.gov/publications/detail/fips/202/final]) as well as RSA's MD5 algorithm (defined in internet RFC 1321 [https://datatracker.ietf.org/doc/html/rfc1321.html]). The terms "secure hash" and "message digest" are interchangeable. Older algorithms were called message digests. The modern term is secure hash.

注釈

adler32 や crc32 ハッシュ関数は zlib モジュールで提供されています。

ハッシュアルゴリズム

There is one constructor method named for each type of hash. All return a hash object with the same simple interface. For example: use sha256() to create a SHA-256 hash object. You can now feed this object with bytes-like objects (normally bytes) using the update method. At any point you can ask it for the digest of the concatenation of the data fed to it so far using the digest() or hexdigest() methods.

To allow multithreading, the Python GIL is released while computing a hash supplied more than 2047 bytes of data at once in its constructor or .update method.

Constructors for hash algorithms that are always present in this module are sha1(), sha224(), sha256(), sha384(), sha512(), sha3_224(), sha3_256(), sha3_384(), sha3_512(), shake_128(), shake_256(), blake2b(), and blake2s(). md5() is normally available as well, though it may be missing or blocked if you are using a rare "FIPS compliant" build of Python. These correspond to algorithms_guaranteed.

Additional algorithms may also be available if your Python distribution's hashlib was linked against a build of OpenSSL that provides others. Others are not guaranteed available on all installations and will only be accessible by name via new(). See algorithms_available.

警告

Some algorithms have known hash collision weaknesses (including MD5 and SHA1). Refer to Attacks on cryptographic hash algorithms [https://en.wikipedia.org/wiki/Cryptographic_hash_function#Attacks_on_cryptographic_hash_algorithms] and the hashlib-seealso section at the end of this document.

Added in version 3.6: SHA3 (Keccak) and SHAKE constructors sha3_224(), sha3_256(), sha3_384(), sha3_512(), shake_128(), shake_256() were added. blake2b() and blake2s() were added.

バージョン 3.9 で変更: All hashlib constructors take a keyword-only argument usedforsecurity with default value True. A false value allows the use of insecure and blocked hashing algorithms in restricted environments. False indicates that the hashing algorithm is not used in a security context, e.g. as a non-cryptographic one-way compression function.

バージョン 3.9 で変更: Hashlib now uses SHA3 and SHAKE from OpenSSL if it provides it.

バージョン 3.12 で変更: For any of the MD5, SHA1, SHA2, or SHA3 algorithms that the linked OpenSSL does not provide we fall back to a verified implementation from the HACL* project [https://github.com/hacl-star/hacl-star].

使用法

To obtain the digest of the byte string b"Nobody inspects the spammish repetition":

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

もっと簡潔に書くと、このようになります:

>>> hashlib.sha256(b"Nobody inspects the spammish repetition").hexdigest()
'031edd7d41651593c5fe5c006fa5752b37fddff7bc4e843aa6af0c950f4b9406'

Constructors

hashlib.new(name, [data, ]*, usedforsecurity=True)

Is a generic constructor that takes the string name of the desired algorithm as its first parameter. It also exists to allow access to the above listed hashes as well as any other algorithms that your OpenSSL library may offer.

Using new() with an algorithm name:

>>> h = hashlib.new('sha256')
>>> h.update(b"Nobody inspects the spammish repetition")
>>> h.hexdigest()
'031edd7d41651593c5fe5c006fa5752b37fddff7bc4e843aa6af0c950f4b9406'

hashlib.md5([data, ]*, usedforsecurity=True)

hashlib.sha1([data, ]*, usedforsecurity=True)

hashlib.sha224([data, ]*, usedforsecurity=True)

hashlib.sha256([data, ]*, usedforsecurity=True)

hashlib.sha384([data, ]*, usedforsecurity=True)

hashlib.sha512([data, ]*, usedforsecurity=True)

hashlib.sha3_224([data, ]*, usedforsecurity=True)

hashlib.sha3_256([data, ]*, usedforsecurity=True)

hashlib.sha3_384([data, ]*, usedforsecurity=True)

hashlib.sha3_512([data, ]*, usedforsecurity=True)

Named constructors such as these are faster than passing an algorithm name to new().

属性

Hashlib provides the following constant module attributes:

hashlib.algorithms_guaranteed

このモジュールによってすべてのプラットフォームでサポートされていることが保証されるハッシュアルゴリズムの名前を含む集合です。一部のアップストリームのベンダーが提供する奇妙な "FIPS準拠の" Pythonビルドではmd5のサポートを除外していますが、その場合であっても 'md5' がリストに含まれることに注意してください。

Added in version 3.2.

hashlib.algorithms_available

実行中の Python インタープリタで利用可能なハッシュアルゴリズム名の set です。これらの名前は new() に渡すことができます。algorithms_guaranteed は常にサブセットです。この set の中に同じアルゴリズムが違う名前で複数回現れることがあります (OpenSSL 由来)。

Added in version 3.2.

Hash Objects

コンストラクタが返すハッシュオブジェクトには、次のような定数属性が用意されています:

hash.digest_size

生成されたハッシュのバイト数。

hash.block_size

内部で使われるハッシュアルゴリズムのブロックのバイト数。

ハッシュオブジェクトには次のような属性があります:

hash.name

このハッシュの正規名です。常に小文字で、new() の引数として渡してこのタイプの別のハッシュを生成することができます。

バージョン 3.4 で変更: name 属性は CPython には最初からありましたが、Python 3.4 までは正式に明記されていませんでした。そのため、プラットフォームによっては存在しないかもしれません。

ハッシュオブジェクトには次のようなメソッドがあります:

hash.update(data)

hash オブジェクトを bytes-like object で更新します。このメソッドの呼出しの繰り返しは、それらの引数を全て結合した引数で単一の呼び出しをした際と同じになります。すなわち m.update(a); m.update(b) は m.update(a + b) と等価です。

hash.digest()

これまで update() メソッドに渡されたデータのダイジェスト値を返します。これは digest_size と同じ長さの、0 から 255 の範囲全てを含み得るバイトの列です。

hash.hexdigest()

digest() と似ていますが、倍の長さの、16進形式文字列を返します。これは、電子メールなどの非バイナリ環境で値を交換する場合に便利です。

hash.copy()

ハッシュオブジェクトのコピー ("クローン") を返します。これは、最初の部分文字列が共通なデータのダイジェストを効率的に計算するために使用します。

SHAKE 可変長ダイジェスト

hashlib.shake_128([data, ]*, usedforsecurity=True)

hashlib.shake_256([data, ]*, usedforsecurity=True)

The shake_128() and shake_256() algorithms provide variable length digests with length_in_bits//2 up to 128 or 256 bits of security. As such, their digest methods require a length. Maximum length is not limited by the SHAKE algorithm.

shake.digest(length)

Return the digest of the data passed to the update() method so far. This is a bytes object of size length which may contain bytes in the whole range from 0 to 255.

shake.hexdigest(length)

Like digest() except the digest is returned as a string object of double length, containing only hexadecimal digits. This may be used to exchange the value in email or other non-binary environments.

Example use:

>>> h = hashlib.shake_256(b'Nobody inspects the spammish repetition')
>>> h.hexdigest(20)
'44709d6fcb83d92a76dcb0b668c98e1b1d3dafe7'

File hashing

The hashlib module provides a helper function for efficient hashing of a file or file-like object.

hashlib.file_digest(fileobj, digest, /)

Return a digest object that has been updated with contents of file object.

fileobj must be a file-like object opened for reading in binary mode. It accepts file objects from builtin open(), BytesIO instances, SocketIO objects from socket.socket.makefile(), and similar. The function may bypass Python's I/O and use the file descriptor from fileno() directly. fileobj must be assumed to be in an unknown state after this function returns or raises. It is up to the caller to close fileobj.

digest must either be a hash algorithm name as a str, a hash constructor, or a callable that returns a hash object.

例:

>>> import io, hashlib, hmac
>>> with open(hashlib.__file__, "rb") as f:
...     digest = hashlib.file_digest(f, "sha256")
...
>>> digest.hexdigest()
'...'

>>> buf = io.BytesIO(b"somedata")
>>> mac1 = hmac.HMAC(b"key", digestmod=hashlib.sha512)
>>> digest = hashlib.file_digest(buf, lambda: mac1)

>>> digest is mac1
True
>>> mac2 = hmac.HMAC(b"key", b"somedata", digestmod=hashlib.sha512)
>>> mac1.digest() == mac2.digest()
True

Added in version 3.11.

鍵導出

鍵の導出 (derivation) と引き伸ばし (stretching) のアルゴリズムはセキュアなパスワードのハッシュ化のために設計されました。 sha1(password) のような甘いアルゴリズムは、ブルートフォース攻撃に抵抗できません。良いパスワードハッシュ化は調節可能で、遅くて、 salt [https://en.wikipedia.org/wiki/Salt_%28cryptography%29] を含まなければなりません。

hashlib.pbkdf2_hmac(hash_name, password, salt, iterations, dklen=None)

この関数は PKCS#5 のパスワードに基づいた鍵導出関数 2 を提供しています。疑似乱数関数として HMAC を使用しています。

文字列 hash_name は、HMAC のハッシュダイジェストアルゴリズムの望ましい名前で、例えば 'sha1' や 'sha256' です。 password と salt はバイト列のバッファとして解釈されます。アプリケーションとライブラリは、 password を適切な長さ (例えば 1024) に制限すべきです。 salt は os.urandom() のような適切なソースからの、およそ 16 バイトかそれ以上のバイト列にするべきです。

The number of iterations should be chosen based on the hash algorithm and computing power. As of 2022, hundreds of thousands of iterations of SHA-256 are suggested. For rationale as to why and how to choose what is best for your application, read Appendix A.2.2 of NIST-SP-800-132 [https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf]. The answers on the stackexchange pbkdf2 iterations question [https://security.stackexchange.com/questions/3959/recommended-of-iterations-when-using-pbkdf2-sha256/] explain in detail.

dklen は、導出された鍵の長さです。 dklen が None の場合、ハッシュアルゴリズム hash_name のダイジェストサイズが使われます。例えば SHA-512 では 64 です。

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

Function only available when Python is compiled with OpenSSL.

Added in version 3.4.

バージョン 3.12 で変更: Function now only available when Python is built with OpenSSL. The slow pure Python implementation has been removed.

hashlib.scrypt(password, *, salt, n, r, p, maxmem=0, dklen=64)

この関数は、 RFC 7914 [https://datatracker.ietf.org/doc/html/rfc7914.html] で定義されるscrypt のパスワードに基づいた鍵導出関数を提供します。

password と salt は bytes-like object でなければなりません。アプリケーションとライブラリは、 password を適切な長さ (例えば 1024) に制限すべきです。 salt は os.urandom() のような適切なソースからの、およそ 16 バイトかそれ以上のバイト列にするべきです。

n is the CPU/Memory cost factor, r the block size, p parallelization factor and maxmem limits memory (OpenSSL 1.1.0 defaults to 32 MiB). dklen is the length of the derived key.

Added in version 3.6.

BLAKE2

BLAKE2 [https://www.blake2.net] is a cryptographic hash function defined in RFC 7693 [https://datatracker.ietf.org/doc/html/rfc7693.html] that comes in two flavors:

BLAKE2b, optimized for 64-bit platforms and produces digests of any size between 1 and 64 bytes,

BLAKE2s, optimized for 8- to 32-bit platforms and produces digests of any size between 1 and 32 bytes.

BLAKE2 supports keyed mode (a faster and simpler replacement for HMAC [https://en.wikipedia.org/wiki/Hash-based_message_authentication_code]), salted hashing, personalization, and tree hashing.

このモジュールのハッシュオブジェクトは標準ライブラリーの hashlib オブジェクトの API に従います。

ハッシュオブジェクトの作成

新しいハッシュオブジェクトは、コンストラクタ関数を呼び出すことで生成されます:

hashlib.blake2b(data=b'', *, digest_size=64, key=b'', salt=b'', person=b'', fanout=1, depth=1, leaf_size=0, node_offset=0, node_depth=0, inner_size=0, last_node=False, usedforsecurity=True)

hashlib.blake2s(data=b'', *, digest_size=32, key=b'', salt=b'', person=b'', fanout=1, depth=1, leaf_size=0, node_offset=0, node_depth=0, inner_size=0, last_node=False, usedforsecurity=True)

These functions return the corresponding hash objects for calculating BLAKE2b or BLAKE2s. They optionally take these general parameters:

data: initial chunk of data to hash, which must be bytes-like object. It can be passed only as positional argument.

digest_size: 出力するダイジェストのバイト数。

key: key for keyed hashing (up to 64 bytes for BLAKE2b, up to 32 bytes for BLAKE2s).

salt: salt for randomized hashing (up to 16 bytes for BLAKE2b, up to 8 bytes for BLAKE2s).

person: personalization string (up to 16 bytes for BLAKE2b, up to 8 bytes for BLAKE2s).

下の表は一般的なパラメータの上限 (バイト単位) です:

Hash

digest_size

len(key)

len(salt)

len(person)

BLAKE2b

64

64

16

16

BLAKE2s

32

32

8

8

注釈

BLAKE2 specification defines constant lengths for salt and personalization parameters, however, for convenience, this implementation accepts byte strings of any size up to the specified length. If the length of the parameter is less than specified, it is padded with zeros, thus, for example, b'salt' and b'salt\x00' is the same value. (This is not the case for key.)

これらのサイズは以下に述べるモジュール constants で利用できます。

コンストラクタ関数は以下のツリーハッシングパラメタを受け付けます:

fanout: fanout (0 to 255, 0 if unlimited, 1 in sequential mode).

depth: ツリーの深さの最大値（1から255までの値で、無制限であれば255、シーケンスモードでは1）。

leaf_size: maximal byte length of leaf (0 to 2**32-1, 0 if unlimited or in sequential mode).

node_offset: node offset (0 to 2**64-1 for BLAKE2b, 0 to 2**48-1 for BLAKE2s, 0 for the first, leftmost, leaf, or in sequential mode).

node_depth: node depth (0 to 255, 0 for leaves, or in sequential mode).

inner_size: inner digest size (0 to 64 for BLAKE2b, 0 to 32 for BLAKE2s, 0 in sequential mode).

last_node: boolean indicating whether the processed node is the last one (False for sequential mode).

See section 2.10 in BLAKE2 specification [https://www.blake2.net/blake2_20130129.pdf] for comprehensive review of tree hashing.

定数

blake2b.SALT_SIZE

blake2s.SALT_SIZE

ソルト長（コンストラクタが受け付けれる最大長）

blake2b.PERSON_SIZE

blake2s.PERSON_SIZE

Personalization string length (maximum length accepted by constructors).

blake2b.MAX_KEY_SIZE

blake2s.MAX_KEY_SIZE

最大キー長

blake2b.MAX_DIGEST_SIZE

blake2s.MAX_DIGEST_SIZE

ハッシュ関数が出力しうるダイジェストの最大長

使用例

簡単なハッシュ化

To calculate hash of some data, you should first construct a hash object by calling the appropriate constructor function (blake2b() or blake2s()), then update it with the data by calling update() on the object, and, finally, get the digest out of the object by calling digest() (or hexdigest() for hex-encoded string).

>>> from hashlib import blake2b
>>> h = blake2b()
>>> h.update(b'Hello world')
>>> h.hexdigest()
'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'

As a shortcut, you can pass the first chunk of data to update directly to the constructor as the positional argument:

>>> from hashlib import blake2b
>>> blake2b(b'Hello world').hexdigest()
'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'

You can call hash.update() as many times as you need to iteratively update the hash:

>>> from hashlib import blake2b
>>> items = [b'Hello', b' ', b'world']
>>> h = blake2b()
>>> for item in items:
...     h.update(item)
...
>>> h.hexdigest()
'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'

Using different digest sizes

BLAKE2 はダイジェストの長さを、BLAKE2bでは64バイトまで、BLAKE2sでは32バイトまでのダイジェスト長を指定できます。例えばSHA-1を、出力を同じ長さのままでBLAKE2bで置き換えるには、BLAKE2bに20バイトのダイジェストを生成するように指示できます:

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

Hash objects with different digest sizes have completely different outputs (shorter hashes are not prefixes of longer hashes); BLAKE2b and BLAKE2s produce different outputs even if the output length is the same:

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

Keyed hashing

Keyed hashing can be used for authentication as a faster and simpler replacement for Hash-based message authentication code [https://en.wikipedia.org/wiki/HMAC] (HMAC). BLAKE2 can be securely used in prefix-MAC mode thanks to the indifferentiability property inherited from BLAKE.

This example shows how to get a (hex-encoded) 128-bit authentication code for message b'message data' with key b'pseudorandom key':

>>> from hashlib import blake2b
>>> h = blake2b(key=b'pseudorandom key', digest_size=16)
>>> h.update(b'message data')
>>> h.hexdigest()
'3d363ff7401e02026f4a4687d4863ced'

As a practical example, a web application can symmetrically sign cookies sent to users and later verify them to make sure they weren't tampered with:

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

Even though there's a native keyed hashing mode, BLAKE2 can, of course, be used in HMAC construction with hmac module:

>>> import hmac, hashlib
>>> m = hmac.new(b'secret key', digestmod=hashlib.blake2s)
>>> m.update(b'message')
>>> m.hexdigest()
'e3c8102868d28b5ff85fc35dda07329970d1a01e273c37481326fe0c861c8142'

Randomized hashing

By setting salt parameter users can introduce randomization to the hash function. Randomized hashing is useful for protecting against collision attacks on the hash function used in digital signatures.

Randomized hashing is designed for situations where one party, the message preparer, generates all or part of a message to be signed by a second party, the message signer. If the message preparer is able to find cryptographic hash function collisions (i.e., two messages producing the same hash value), then they might prepare meaningful versions of the message that would produce the same hash value and digital signature, but with different results (e.g., transferring $1,000,000 to an account, rather than $10). Cryptographic hash functions have been designed with collision resistance as a major goal, but the current concentration on attacking cryptographic hash functions may result in a given cryptographic hash function providing less collision resistance than expected. Randomized hashing offers the signer additional protection by reducing the likelihood that a preparer can generate two or more messages that ultimately yield the same hash value during the digital signature generation process --- even if it is practical to find collisions for the hash function. However, the use of randomized hashing may reduce the amount of security provided by a digital signature when all portions of the message are prepared by the signer.

(NIST SP-800-106 "Randomized Hashing for Digital Signatures" [https://csrc.nist.gov/publications/detail/sp/800-106/archive/2009-02-25])

In BLAKE2 the salt is processed as a one-time input to the hash function during initialization, rather than as an input to each compression function.

警告

Salted hashing (or just hashing) with BLAKE2 or any other general-purpose cryptographic hash function, such as SHA-256, is not suitable for hashing passwords. See BLAKE2 FAQ [https://www.blake2.net/#qa] for more information.

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

Personalization

Sometimes it is useful to force hash function to produce different digests for the same input for different purposes. Quoting the authors of the Skein hash function:

We recommend that all application designers seriously consider doing this; we have seen many protocols where a hash that is computed in one part of the protocol can be used in an entirely different part because two hash computations were done on similar or related data, and the attacker can force the application to make the hash inputs the same. Personalizing each hash function used in the protocol summarily stops this type of attack.

(The Skein Hash Function Family [https://www.schneier.com/wp-content/uploads/2016/02/skein.pdf], p. 21)

BLAKE2は person 引数にバイト列を渡すことでパーソナライズできます:

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

Personalization together with the keyed mode can also be used to derive different keys from a single one.

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

ツリーモード

これが二つの葉ノードからなる最小の木をハッシュする例です:

  10
 /  \
00  01

次の例では、64バイトの内部桁が使われ、32バイトの最終的なダイジェストを返しています:

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

クレジット:

BLAKE2 [https://www.blake2.net] は*Jean-Philippe Aumasson*、 Luca Henzen、 Willi Meier そして Raphael C.-W. Phan によって作成された SHA-3 [https://en.wikipedia.org/wiki/Secure_Hash_Algorithms] の最終候補である BLAKE [https://web.archive.org/web/20200918190133/https://131002.net/blake/] を元に、Jean-Philippe Aumasson、 Samuel Neves、 Zooko Wilcox-O'Hearn, そして Christian Winnerlein によって設計されました。

それは、 Daniel J. Bernstein によって設計されたChaCha [https://cr.yp.to/chacha.html] 暗号由来のアルゴリズムを用いています。

標準ライブラリは pyblake2 [https://pythonhosted.org/pyblake2/] モジュールを基礎として実装されています。このモジュールは Dmitry Chestnykh によって、Samuel Neves が作成した C実装を元に書かれました。このドキュメントは、pyblake2 [https://pythonhosted.org/pyblake2/] からコピーされ、Dmitry Chestnykh によって書かれました。

Christian Heimes によって、一部のCコードがPython向けに書き直されました。

以下の public domain dedicationが、Cのハッシュ関数実装と、拡張コードと、このドキュメントに適用されます:

To the extent possible under law, the author(s) have dedicated all copyright and related and neighboring rights to this software to the public domain worldwide. This software is distributed without any warranty.

You should have received a copy of the CC0 Public Domain Dedication along with this software. If not, see https://creativecommons.org/publicdomain/zero/1.0/.

The following people have helped with development or contributed their changes to the project and the public domain according to the Creative Commons Public Domain Dedication 1.0 Universal:

Alexandr Sokolovskiy

参考

hmac モジュール

ハッシュを用いてメッセージ認証コードを生成するモジュールです。

base64 モジュール

バイナリハッシュを非バイナリ環境用にエンコードするもうひとつの方法です。

https://nvlpubs.nist.gov/nistpubs/fips/nist.fips.180-4.pdf

The FIPS 180-4 publication on Secure Hash Algorithms.

https://csrc.nist.gov/publications/detail/fips/202/final

The FIPS 202 publication on the SHA-3 Standard.

https://www.blake2.net/

BLAKE2 の公式ウェブサイト

https://en.wikipedia.org/wiki/Cryptographic_hash_function

どのアルゴリズムにどんな既知の問題があって、それが実際に利用する際にどう影響するかについての Wikipedia の記事。

https://www.ietf.org/rfc/rfc8018.txt

PKCS #5: Password-Based Cryptography Specification Version 2.1

https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf

NIST Recommendation for Password-Based Key Derivation.

hmac --- Keyed-Hashing for Message Authentication

ソースコード: Lib/hmac.py [https://github.com/python/cpython/tree/3.12/Lib/hmac.py]

このモジュールでは RFC 2104 [https://datatracker.ietf.org/doc/html/rfc2104.html] で記述されている HMAC アルゴリズムを実装しています。

hmac.new(key, msg=None, digestmod)

Return a new hmac object. key is a bytes or bytearray object giving the secret key. If msg is present, the method call update(msg) is made. digestmod is the digest name, digest constructor or module for the HMAC object to use. It may be any name suitable to hashlib.new(). Despite its argument position, it is required.

バージョン 3.4 で変更: 引数 key に bytes または bytearray オブジェクトを渡せるようになりました。引数 msg に hashlib がサポートする全てのタイプを渡せるようになりました。引数 digestmod にハッシュアルゴリズム名を渡せるようになりました。

バージョン 3.8 で変更: The digestmod argument is now required. Pass it as a keyword argument to avoid awkwardness when you do not have an initial msg.

hmac.digest(key, msg, digest)

与えられたsecret key と digest の msg のダイジェストを返します。この関数は HMAC(key, msg, digest).digest() に似ていますが、最適化されたCやインラインの実装を使用しており、メモリに収まるメッセージに対しては高速です。パラメータ key 、 msg 、および digest は、 new() と同じ意味を持ちます。

CPython実装の詳細、最適化されたC実装は、OpenSSLがサポートするダイジェストアルゴリズムの文字列と名前が digest の場合にのみ使用されます。

Added in version 3.7.

HMAC オブジェクトは以下のメソッドを持っています:

HMAC.update(msg)

hmac オブジェクトを msg で更新します。このメソッドの呼出の繰り返しは、それらの引数を全て結合した引数で単一の呼び出しをした際と同じになります。すなわち m.update(a); m.update(b) は m.update(a + b) と等価です。

バージョン 3.4 で変更: 引数 msg は hashlib がサポートしているあらゆる型のいずれかです。

HMAC.digest()

これまで update() メソッドに渡されたバイト列のダイジェスト値を返します。これはコンストラクタに与えられた digest_size と同じ長さのバイト列で、 NUL バイトを含む非 ASCII 文字が含まれることがあります。

警告

When comparing the output of digest() to an externally supplied digest during a verification routine, it is recommended to use the compare_digest() function instead of the == operator to reduce the vulnerability to timing attacks.

HMAC.hexdigest()

digest() と似ていますが、返される文字列は倍の長さとなり、16進形式となります。これは、電子メールなどの非バイナリ環境で値を交換する場合に便利です。

警告

When comparing the output of hexdigest() to an externally supplied digest during a verification routine, it is recommended to use the compare_digest() function instead of the == operator to reduce the vulnerability to timing attacks.

HMAC.copy()

hmac オブジェクトのコピー ("クローン") を返します。このコピーは最初の部分文字列が共通になっている文字列のダイジェスト値を効率よく計算するために使うことができます。

ハッシュオブジェクトには次のような属性があります:

HMAC.digest_size

生成された HMAC ダイジェストのバイト数。

HMAC.block_size

内部で使われるハッシュアルゴリズムのブロックのバイト数。

Added in version 3.4.

HMAC.name

このHMAC の正規名で、例えば hmac-md5 のように常に小文字です。

Added in version 3.4.

バージョン 3.10 で変更: Removed the undocumented attributes HMAC.digest_cons, HMAC.inner, and HMAC.outer.

このモジュールは以下のヘルパ関数も提供しています:

hmac.compare_digest(a, b)

a == b を返します。この関数は、内容ベースの短絡的な振る舞いを避けることによってタイミング分析を防ぐよう設計されたアプローチを用い、暗号化に用いるのに相応しいものとしています。 a と b は両方が同じ型でなければなりません: (例えば HMAC.hexdigest() が返したような ASCII のみの) str または bytes-like object のどちらか一方。

注釈

a と b が異なる長さであったりエラーが発生した場合には、タイミング攻撃で理論上 a と b の型と長さについての情報が暴露されますが、その値は明らかになりません。

Added in version 3.3.

バージョン 3.10 で変更: The function uses OpenSSL's CRYPTO_memcmp() internally when available.

参考

hashlib モジュール

セキュアハッシュ関数を提供する Python モジュールです。

secrets --- Generate secure random numbers for managing secrets

Added in version 3.6.

ソースコード: Lib/secrets.py [https://github.com/python/cpython/tree/3.12/Lib/secrets.py]

secrets モジュールを使って、パスワードやアカウント認証、セキュリティトークンなどの機密を扱うのに適した、暗号学的に強い乱数を生成することができます。

特に、 random モジュールのデフォルトの擬似乱数ジェネレータよりも secrets を使用するべきです。 random モジュールはモデル化やシミュレーション向けで、セキュリティや暗号学的に設計されてはいません。

参考

PEP 506 [https://peps.python.org/pep-0506/]

乱数

secrets モジュールは OS が提供する最も安全な乱雑性のソースへのアクセスを提供します。

class secrets.SystemRandom

OS が提供する最も高品質なソースを用いて乱数を生成するためのクラスです。更に詳しいことについては random.SystemRandom を参照してください。

secrets.choice(seq)

Return a randomly chosen element from a non-empty sequence.

secrets.randbelow(exclusive_upper_bound)

Return a random int in the range [0, exclusive_upper_bound).

secrets.randbits(k)

ランダムな k ビットの整数を返します。

トークンの生成

secrets モジュールはパスワードのリセットや想像しにくい URL などの用途に適した、安全なトークンを生成するための関数を提供します。

secrets.token_bytes([nbytes=None])

nbytes バイトを含むバイト文字列を返します。nbytes が None の場合や与えられなかった場合は妥当なデフォルト値が使われます。

>>> token_bytes(16)
b'\xebr\x17D*t\xae\xd4\xe3S\xb6\xe2\xebP1\x8b'

secrets.token_hex([nbytes=None])

十六進数のランダムなテキスト文字列を返します。文字列は nbytes のランダムなバイトを持ち、各バイトは二つの十六進数に変換されます。nbytes が None の場合や与えられなかった場合は妥当なデフォルト値が使われます。

>>> token_hex(16)
'f9bf78b9a18ce6d46a0cd2b0b86df9da'

secrets.token_urlsafe([nbytes=None])

nbytes のランダムなバイトを持つ URL 安全なテキスト文字列を返します。テキストは Base64 でエンコードされていて、平均的に各バイトは約 1.3 文字になります。 nbytes が None の場合や与えられなかった場合は妥当なデフォルト値が使われます。

>>> token_urlsafe(16)
'Drmhze6EPcv0fN_81Bj-nA'

トークンは何バイト使うべきか？

総当たり攻撃 [https://ja.wikipedia.org/wiki/総当たり攻撃] に耐えるには、トークンは十分にランダムでなければなりません。残念なことに、コンピュータの性能が向上し、より短時間により多くの推測ができるようになるにつれ、十分とされるランダムさというのは必然的に増えます。2015 年の時点で、secrets モジュールに想定される通常の用途では、32 バイト (256 ビット) のランダムさは十分と考えられています。

独自の長さのトークンを扱いたい場合、様々な token_* 関数に int 引数で渡すことで、トークンに使用するランダムさを明示的に指定することができます。引数はランダムさのバイト数として使用されます。

それ以外の場合、すなわち引数がない場合や None の場合、token_* 関数は妥当なデフォルト値を代わりに使います。

注釈

デフォルトはメンテナンスリリースの間を含め、いつでも変更される可能性があります。

その他の関数

secrets.compare_digest(a, b)

Return True if strings or bytes-like objects a and b are equal, otherwise False, using a "constant-time compare" to reduce the risk of timing attacks [https://codahale.com/a-lesson-in-timing-attacks/]. See hmac.compare_digest() for additional details.

レシピとベストプラクティス

この節では secrets を使用してセキュリティの基礎的なレベルを扱う際のレシピとベストプラクティスを説明します。

8文字のアルファベットと数字を含むパスワードを生成するには:

import string
import secrets
alphabet = string.ascii_letters + string.digits
password = ''.join(secrets.choice(alphabet) for i in range(8))

注釈

Applications should not store passwords in a recoverable format [https://cwe.mitre.org/data/definitions/257.html], whether plain text or encrypted. They should be salted and hashed using a cryptographically strong one-way (irreversible) hash function.

アルファべットと数字からなり、小文字を少なくとも1つと数字を少なくとも3つ含む、10文字のパスワードを生成するには:

import string
import secrets
alphabet = string.ascii_letters + string.digits
while True:
    password = ''.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

XKCD スタイルのパスフレーズ [https://xkcd.com/936/] を生成するには:

import secrets
# On standard Linux systems, use a convenient dictionary file.
# Other platforms may need to provide their own word-list.
with open('/usr/share/dict/words') as f:
    words = [word.strip() for word in f]
    password = ' '.join(secrets.choice(words) for i in range(4))

パスワードの復元用途に適したセキュリティトークンを含む、推測しにくい一時 URL を生成するには:

import secrets
url = 'https://example.com/reset=' + secrets.token_urlsafe()

汎用オペレーティングシステムサービス

本章に記述されたモジュールは、ファイルの取り扱いや時間計測のような (ほぼ)すべてのオペレーティングシステムで利用可能な機能にインターフェースを提供します。これらのインターフェースは、Unix もしくは C のインターフェースを基に作られますが、ほとんどの他のシステムで同様に利用可能です。概要を以下に記述します:

os --- Miscellaneous operating system interfaces

ファイル名、コマンドライン引数、および環境変数

Python UTF-8 Mode

プロセスのパラメーター

ファイルオブジェクトの生成

ファイル記述子の操作

ターミナルのサイズの問い合わせ

ファイル記述子の継承

ファイルとディレクトリ

Linux 拡張属性

プロセス管理

スケジューラーへのインターフェイス

雑多なシステム情報

乱数

io --- Core tools for working with streams

概要

テキスト I/O

バイナリ I/O

Raw I/O

Text Encoding

Opt-in EncodingWarning

高水準のモジュールインターフェイス

クラス階層

I/O 基底クラス

生ファイルI/O

バッファ付きストリーム

テキスト I/O

性能

バイナリ I/O

テキスト I/O

マルチスレッディング

リエントラント性

time --- Time access and conversions

関数

Clock ID Constants

Timezone Constants

argparse --- Parser for command-line options, arguments and sub-commands

中核的な機能

add_argument() のためのクイックリンク

使用例

パーサーを作る

引数を追加する

引数を解析する

ArgumentParser オブジェクト

prog

usage

description

epilog

parents

formatter_class

prefix_chars

fromfile_prefix_chars

argument_default

allow_abbrev

conflict_handler

add_help

exit_on_error

add_argument() メソッド

name または flags

action

nargs

const

default

type

choices

required

help

metavar

dest

Action クラス

parse_args() メソッド

オプション値の文法

不正な引数

- を含む引数

引数の短縮形 (先頭文字でのマッチング)

sys.argv 以外

Namespace オブジェクト

その他のユーティリティ

サブコマンド

FileType オブジェクト

引数グループ

相互排他

パーサーのデフォルト値

ヘルプの表示

部分解析

ファイル解析のカスタマイズ

終了メソッド

混在した引数の解析

optparse からのアップグレード

例外

getopt --- C-style parser for command line options

logging --- Logging facility for Python

ロガーオブジェクト

ロギングレベル

ハンドラオブジェクト

フォーマッタオブジェクト

フィルタオブジェクト

LogRecord オブジェクト

LogRecord 属性

LoggerAdapter オブジェクト

スレッドセーフ性

モジュールレベルの関数

モジュールレベル属性

warnings モジュールとの統合

logging.config --- Logging configuration

環境設定のための関数

セキュリティで考慮すべき点

環境設定辞書スキーマ

辞書スキーマの詳細

増分設定

オブジェクトの接続

ユーザ定義オブジェクト

ハンドラの設定順序

外部オブジェクトへのアクセス

内部オブジェクトへのアクセス

インポート解決とカスタムインポーター

Configuring QueueHandler and QueueListener

環境設定ファイルの書式

logging.handlers --- Logging handlers

StreamHandler

FileHandler

NullHandler

WatchedFileHandler

BaseRotatingHandler

RotatingFileHandler

TimedRotatingFileHandler

SocketHandler

DatagramHandler

SysLogHandler

NTEventLogHandler

SMTPHandler

MemoryHandler

HTTPHandler

QueueHandler

QueueListener

getpass --- Portable password input

curses --- Terminal handling for character-cell displays

関数

Window オブジェクト

定数

curses.textpad --- curses プログラムのためのテキスト入力ウィジェット

Textbox オブジェクト

curses.ascii --- Utilities for ASCII characters

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

関数

Panel オブジェクト

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

クロスプラットフォーム

Java プラットフォーム

Windows プラットフォーム

macOS プラットフォーム

Unix プラットフォーム

Linux プラットフォーム

errno --- Standard errno system symbols

ctypes --- A foreign function library for Python

ctypesチュートリアル

動的リンクライブラリをロードする

ロードしたdllから関数にアクセスする

関数を呼び出す

基本データ型

続・関数を呼び出す

Calling variadic functions

自作のデータ型とともに関数を呼び出す

要求される引数の型を指定する (関数プロトタイプ)

戻り値の型

ポインタを渡す(または、パラメータの参照渡し)

構造体と共用体

構造体/共用体アライメントとバイトオーダー

構造体と共用体におけるビットフィールド

配列

ポインタ

型変換

不完全型

コールバック関数

dllからエクスポートされた値へアクセスする

びっくり仰天

可変サイズのデータ型

ctypesリファレンス

共有ライブラリを見つける

共有ライブラリをロードする

外部関数

関数プロトタイプ

ユーティリティー関数

データ型

基本データ型

構造化データ型

配列とポインタ

os --- Miscellaneous operating system interfaces

ソースコード: Lib/os.py [https://github.com/python/cpython/tree/3.12/Lib/os.py]

このモジュールは、 OS 依存の機能を利用するポータブルな方法を提供します。単純なファイルの読み書きについては、 open() を参照してください。パス操作については、 os.path モジュールを参照してください。コマンドラインに与えられたすべてのファイルから行を読み込んでいくには、 fileinput モジュールを参照してください。一時ファイルや一時ディレクトリの作成については、 tempfile モジュールを参照してください。高水準のファイルとディレクトリの操作については、 shutil モジュールを参照してください。

利用可能性に関する注意 :

Python の、すべての OS 依存モジュールの設計方針は、可能な限り同一のインターフェースで同一の機能を利用できるようにする、というものです。例えば、 os.stat(path) は path に関する stat 情報を、 (POSIX を元にした ) 同じフォーマットで返します。

特定のオペレーティングシステム固有の拡張も os を介して利用することができますが、これらの利用はもちろん、可搬性を脅かします。

パスやファイル名を受け付けるすべての関数は、バイト列型および文字列型両方のオブジェクトを受け付け、パスやファイル名を返す時は、同じ型のオブジェクトを返します。

VxWorks では、os.popen, os.fork, os.execv および os.spawn*p* はサポートされていません。

On WebAssembly platforms wasm32-emscripten and wasm32-wasi, large parts of the os module are not available or behave differently. API related to processes (e.g. fork(), execve()), signals (e.g. kill(), wait()), and resources (e.g. nice()) are not available. Others like getuid() and getpid() are emulated or stubs.

注釈

このモジュール内のすべての関数は、間違った、あるいはアクセス出来ないファイル名やファイルパス、その他型が合っていても OS が受理しない引数に対して、 OSError (またはそのサブクラス)を送出します。

exception os.error

組み込みの OSError 例外に対するエイリアスです。

os.name

import されているオペレーティングシステムに依存するモジュールの名前です。現在次の名前が登録されています: 'posix', 'nt', 'java'。

参考

sys.platform has a finer granularity. os.uname() gives system-dependent version information.

platform モジュールはシステムの詳細な識別情報をチェックする機能を提供しています。

ファイル名、コマンドライン引数、および環境変数

Python では、ファイル名、コマンドライン引数、および環境変数を表すのに文字列型を使用します。一部のシステムでは、これらをオペレーティングシステムに渡す前に、文字列からバイト列へ、またはその逆のデコードが必要です。Python はこの変換を行うために filesystem encoding and error handler を使用します (sys.getfilesystemencoding() 参照)。

The filesystem encoding and error handler are configured at Python startup by the PyConfig_Read() function: see filesystem_encoding and filesystem_errors members of PyConfig.

バージョン 3.1 で変更: On some systems, conversion using the file system encoding may fail. In this case, Python uses the surrogateescape encoding error handler, which means that undecodable bytes are replaced by a Unicode character U+DCxx on decoding, and these are again translated to the original byte on encoding.

file system encoding では、すべてが 128 バイト以下に正常にデコードされることが保証されなくてはなりません。ファイルシステムのエンコーディングでこれが保証されなかった場合は、API 関数が UnicodeError を送出します。

See also the locale encoding.

Python UTF-8 Mode

Added in version 3.7: より詳しくは PEP 540 [https://peps.python.org/pep-0540/] を参照してください。

The Python UTF-8 Mode ignores the locale encoding and forces the usage of the UTF-8 encoding:

Use UTF-8 as the filesystem encoding.

sys.getfilesystemencoding() returns 'utf-8'.

locale.getpreferredencoding() returns 'utf-8' (the do_setlocale argument has no effect).

sys.stdin, sys.stdout, and sys.stderr all use UTF-8 as their text encoding, with the surrogateescape error handler being enabled for sys.stdin and sys.stdout (sys.stderr continues to use backslashreplace as it does in the default locale-aware mode)

On Unix, os.device_encoding() returns 'utf-8' rather than the device encoding.

Note that the standard stream settings in UTF-8 mode can be overridden by PYTHONIOENCODING (just as they can be in the default locale-aware mode).

As a consequence of the changes in those lower level APIs, other higher level APIs also exhibit different default behaviours:

Command line arguments, environment variables and filenames are decoded to text using the UTF-8 encoding.

os.fsdecode() and os.fsencode() use the UTF-8 encoding.

open(), io.open(), and 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.

The Python UTF-8 Mode is enabled if the LC_CTYPE locale is C or POSIX at Python startup (see the PyConfig_Read() function).

It can be enabled or disabled using the -X utf8 command line option and the PYTHONUTF8 environment variable.

If the 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 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 sys.flags.utf8_mode.

See also the UTF-8 mode on Windows and the filesystem encoding and error handler.

参考

PEP 686 [https://peps.python.org/pep-0686/]

Python 3.15 will make Python UTF-8 Mode default.

プロセスのパラメーター

これらの関数とデータアイテムは、現在のプロセスおよびユーザーに対する情報提供および操作のための機能を提供しています。

os.ctermid()

プロセスの制御端末に対応するファイル名を返します。

Availability: Unix, not Emscripten, not WASI.

os.environ

A mapping object where keys and values are strings that represent the process environment. For example, environ['HOME'] is the pathname of your home directory (on some platforms), and is equivalent to getenv("HOME") in C.

このマップ型の内容は、 os モジュールの最初の import の時点、通常は Python の起動時に site.py が処理される中で取り込まれます。それ以後に変更された環境変数は os.environ を直接変更しない限り os.environ には反映されません。

このマップ型オブジェクトは環境変数に対する変更に使うこともできます。 putenv() はマップ型オブジェクトが修正される時に、自動的に呼ばれることになります。

Unix では、キーと値に sys.getfilesystemencoding()、エラーハンドラーに 'surrogateescape' を使用します。異なるエンコーディングを使用したい場合は environb を使用します。

On Windows, the keys are converted to uppercase. This also applies when getting, setting, or deleting an item. For example, environ['monty'] = 'python' maps the key 'MONTY' to the value 'python'.

注釈

putenv() を直接呼び出しても os.environ の内容は変わらないので、 os.environ を直接変更する方が良いです。

注釈

On some platforms, including FreeBSD and macOS, setting environ may cause memory leaks. Refer to the system documentation for putenv().

このマップ型オブジェクトからアイテムを削除することで環境変数を消すことができます。 unsetenv() は os.environ からアイテムが取り除かれた時に自動的に呼ばれます。 pop() または clear() が呼ばれた時も同様です。

バージョン 3.9 で変更: 更新され PEP 584 [https://peps.python.org/pep-0584/] の合成演算子 (|) と更新演算子 (|=) がサポートされました。

os.environb

Bytes version of environ: a mapping object where both keys and values are bytes objects representing the process environment. environ and environb are synchronized (modifying environb updates environ, and vice versa).

environb is only available if supports_bytes_environ is True.

Added in version 3.2.

バージョン 3.9 で変更: 更新され PEP 584 [https://peps.python.org/pep-0584/] の合成演算子 (|) と更新演算子 (|=) がサポートされました。

os.chdir(path)

os.fchdir(fd)

os.getcwd()

これらの関数は、 ファイルとディレクトリ 節で説明されています。

os.fsencode(filename)

path-like な filename を ファイルシステムのエンコーディングとエラーハンドラ にエンコードします。未変更の bytes オブジェクトを返します。

fsdecode() はこの逆変換を行う関数です。

Added in version 3.2.

バージョン 3.6 で変更: os.PathLike インターフェースを実装したオブジェクトを受け入れるようになりました。

os.fsdecode(filename)

path-like な filename を ファイルシステムのエンコーディングとエラーハンドラ からデコードします。未変更の str オブジェクトを返します。

fsencode() はこの逆変換を行う関数です。

Added in version 3.2.

バージョン 3.6 で変更: os.PathLike インターフェースを実装したオブジェクトを受け入れるようになりました。

os.fspath(path)

path のファイルシステム表現を返します。

もし str か bytes: のオブジェクトが渡された場合は、変更せずにそのまま返します。さもなければ、 __fspath__() が呼び出され、その戻り値が str か bytes のオブジェクトであれば、その値を返します。他のすべてのケースでは TypeError が送出されます。

Added in version 3.6.

class os.PathLike

ファイルシステムパスを表すオブジェクト(例: pathlib.PurePath) 向けの abstract base class です。

Added in version 3.6.

abstractmethod __fspath__()

このオブジェクトが表現するファイルシステムパスを返します。

このメソッドは str か bytes のオブジェクトのみを返す必要があります(str が好まれます)。

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 getenv() uses os.environ, the mapping of getenv() is similarly also captured on import, and the function may not reflect future environment changes.

Unix では、キーと値は sys.getfilesystemencoding()、エラーハンドラー 'surrogateescape' でデコードされます。異なるエンコーディングを使用したい場合は os.getenvb() を使用します。

Availability: Unix, Windows。

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 getenvb() uses os.environb, the mapping of getenvb() is similarly also captured on import, and the function may not reflect future environment changes.

getenvb() is only available if supports_bytes_environ is True.

利用可能な環境: Unix。

Added in version 3.2.

os.get_exec_path(env=None)

プロセスを起動する時に名前付き実行ファイルを検索するディレクトリのリストを返します。 env が指定されると、それを環境変数の辞書とみなし、その辞書からキー PATH の値を探します。デフォルトでは env は None であり、environ が使用されます。

Added in version 3.2.

os.getegid()

現在のプロセスの実効グループ id を返します。この id は現在のプロセスで実行されているファイルの "set id" ビットに対応します。

Availability: Unix, not Emscripten, not WASI.

os.geteuid()

現在のプロセスの実効ユーザー id を返します。

Availability: Unix, not Emscripten, not WASI.

os.getgid()

現在のプロセスの実グループ id を返します。

利用可能な環境: Unix。

The function is a stub on Emscripten and WASI, see WebAssemblyプラットフォーム for more information.

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.

Availability: Unix, not Emscripten, not WASI.

Added in version 3.3.

os.getgroups()

現在のプロセスに関連付けられた従属グループ id のリストを返します。

Availability: Unix, not Emscripten, not WASI.

注釈

On macOS, getgroups() behavior differs somewhat from other Unix platforms. If the Python interpreter was built with a deployment target of 10.5 or earlier, 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 setgroups() if suitably privileged. If built with a deployment target greater than 10.5, 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 setgroups(), and its length is not limited to 16. The deployment target value, MACOSX_DEPLOYMENT_TARGET, can be obtained with sysconfig.get_config_var().

os.getlogin()

プロセスの制御端末にログインしているユーザー名を返します。ほとんどの場合、getpass.getuser() を使う方が便利です。なぜなら、getpass.getuser() は、ユーザーを見つけるために、環境変数 LOGNAME や USERNAME を調べ、さらには pwd.getpwuid(os.getuid())[0] まで調べに行くからです。

Availability: Unix, Windows, not Emscripten, not WASI.

os.getpgid(pid)

プロセス id pid のプロセスのプロセスグループ id を返します。 pid が 0 の場合、現在のプロセスのプロセスグループ id を返します。

Availability: Unix, not Emscripten, not WASI.

os.getpgrp()

現在のプロセスグループの id を返します。

Availability: Unix, not Emscripten, not WASI.

os.getpid()

現在のプロセス id を返します。

The function is a stub on Emscripten and WASI, see WebAssemblyプラットフォーム for more information.

os.getppid()

親プロセスのプロセス id を返します。親プロセスが終了していた場合、Unix では init プロセスの id (1) が返され、Windows では親のプロセス id だったもの (別のプロセスで再利用されているかもしれない) がそのまま返されます。

Availability: Unix, Windows, not Emscripten, not WASI.

バージョン 3.2 で変更: Windows サポートが追加されました。

os.getpriority(which, who)

プログラムのスケジューリング優先度を取得します。which の値は PRIO_PROCESS、PRIO_PGRP、あるいは PRIO_USER のいずれか一つで、who の値は which に応じて解釈されます (PRIO_PROCESS であればプロセス識別子、PRIO_PGRP であればプロセスグループ識別子、そして PRIO_USER であればユーザー ID)。who の値がゼロの場合、呼び出したプロセス、呼び出したプロセスのプロセスグループ、および呼び出したプロセスの実ユーザー id を (それぞれ) 意味します。

Availability: Unix, not Emscripten, not WASI.

Added in version 3.3.

os.PRIO_PROCESS

os.PRIO_PGRP

os.PRIO_USER

getpriority() と setpriority() 用のパラメータです。

Availability: Unix, not Emscripten, not WASI.

Added in version 3.3.

os.PRIO_DARWIN_THREAD

os.PRIO_DARWIN_PROCESS

os.PRIO_DARWIN_BG

os.PRIO_DARWIN_NONUI

getpriority() と setpriority() 用のパラメータです。

Availability: macOS

Added in version 3.12.

os.getresuid()

現在のプロセスの実ユーザー id 、実効ユーザー id 、および保存ユーザー id を示す、 (ruid, euid, suid) のタプルを返します。

Availability: Unix, not Emscripten, not WASI.

Added in version 3.2.

os.getresgid()

現在のプロセスの実グループ id 、実効グループ id 、および保存グループ id を示す、 (rgid, egid, sgid) のタプルを返します。

Availability: Unix, not Emscripten, not WASI.

Added in version 3.2.

os.getuid()

現在のプロセスの実ユーザー id を返します。

利用可能な環境: Unix。

The function is a stub on Emscripten and WASI, see WebAssemblyプラットフォーム for more information.

os.initgroups(username, gid, /)

システムの initgroups() を呼び出し、指定された username がメンバーである全グループと gid で指定されたグループでグループアクセスリストを初期化します。

Availability: Unix, not Emscripten, not WASI.

Added in version 3.2.

os.putenv(key, value, /)

key という名前の環境変数に文字列 value を設定します。このような環境変数の変更は、os.system()、popen()、または fork() と execv() で起動されたサブプロセスに影響を与えます。

Assignments to items in os.environ are automatically translated into corresponding calls to putenv(); however, calls to putenv() don't update os.environ, so it is actually preferable to assign to items of os.environ. This also applies to getenv() and getenvb(), which respectively use os.environ and os.environb in their implementations.

注釈

On some platforms, including FreeBSD and macOS, setting environ may cause memory leaks. Refer to the system documentation for putenv().

引数 key, value を指定して 監査イベント os.putenv を送出します。

バージョン 3.9 で変更: 常に利用出来るようになりました。

os.setegid(egid, /)

現在のプロセスに実効グループ id をセットします。

Availability: Unix, not Emscripten, not WASI.

os.seteuid(euid, /)

現在のプロセスに実効ユーザー id をセットします。

Availability: Unix, not Emscripten, not WASI.

os.setgid(gid, /)

現在のプロセスにグループ id をセットします。

Availability: Unix, not Emscripten, not WASI.

os.setgroups(groups, /)

現在のグループに関連付けられた従属グループ id のリストを groups に設定します。 groups はシーケンス型でなくてはならず、各要素はグループを特定する整数でなくてはなりません。通常、この操作はスーパユーザーしか利用できません。

Availability: Unix, not Emscripten, not WASI.

注釈

macOS では、 groups の長さはシステムで定義された実効グループ id の最大数 ( 通常は 16) を超えない場合があります。 setgroups() 呼び出しで設定されたものと同じグループリストが返されないケースについては、 getgroups() のドキュメントを参照してください。

os.setns(fd, nstype=0)

Reassociate the current thread with a Linux namespace. See the setns(2) [https://manpages.debian.org/setns(2)] and namespaces(7) [https://manpages.debian.org/namespaces(7)] man pages for more details.

If fd refers to a /proc/pid/ns/ link, setns() reassociates the calling thread with the namespace associated with that link, and nstype may be set to one of the CLONE_NEW* constants to impose constraints on the operation (0 means no constraints).

Since Linux 5.8, fd may refer to a PID file descriptor obtained from pidfd_open(). In this case, 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 CLONE_NEW* constants, e.g. 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 fileno() method, or a raw file descriptor.

This example reassociates the thread with the init process's network namespace:

fd = os.open("/proc/1/ns/net", os.O_RDONLY)
os.setns(fd, os.CLONE_NEWNET)
os.close(fd)

Availability: Linux >= 3.0 with glibc >= 2.14.

Added in version 3.12.

参考

The unshare() function.

os.setpgrp()

Call the system call setpgrp() or setpgrp(0, 0) depending on which version is implemented (if any). See the Unix manual for the semantics.

Availability: Unix, not Emscripten, not WASI.

os.setpgid(pid, pgrp, /)

Call the system call 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.

Availability: Unix, not Emscripten, not WASI.

os.setpriority(which, who, priority)

プログラムのスケジューリング優先度を設定します。which は PRIO_PROCESS、PRIO_PGRP、あるいは PRIO_USER のいずれか一つで、who の値は which に応じて解釈されます (PRIO_PROCESS であればプロセス識別子、PRIO_PGRP であればプロセスグループ識別子、そして PRIO_USER であればユーザー ID)。who の値がゼロの場合、呼び出したプロセス、呼び出したプロセスのプロセスグループ、および呼び出したプロセスの実ユーザー id を (それぞれ) 意味します。priority は -20 から 19 の整数値で、デフォルトの優先度は 0 です。小さい数値ほど優先されるスケジューリングとなります。

Availability: Unix, not Emscripten, not WASI.

Added in version 3.3.

os.setregid(rgid, egid, /)

現在のプロセスの実グループ id および実効グループ id を設定します。

Availability: Unix, not Emscripten, not WASI.

os.setresgid(rgid, egid, sgid, /)

現在のプロセスの、実グループ id 、実効グループ id 、および保存グループ id を設定します。

Availability: Unix, not Emscripten, not WASI.

Added in version 3.2.

os.setresuid(ruid, euid, suid, /)

現在のプロセスの実ユーザー id 、実効ユーザー id 、および保存ユーザー id を設定します。

Availability: Unix, not Emscripten, not WASI.

Added in version 3.2.

os.setreuid(ruid, euid, /)

現在のプロセスの実ユーザー id および実効ユーザー id を設定します。

Availability: Unix, not Emscripten, not WASI.

os.getsid(pid, /)

Call the system call getsid(). See the Unix manual for the semantics.

Availability: Unix, not Emscripten, not WASI.

os.setsid()

Call the system call setsid(). See the Unix manual for the semantics.

Availability: Unix, not Emscripten, not WASI.

os.setuid(uid, /)

現在のプロセスのユーザー id を設定します。

Availability: Unix, not Emscripten, not WASI.

os.strerror(code, /)

Return the error message corresponding to the error code in code. On platforms where strerror() returns NULL when given an unknown error number, ValueError is raised.

os.supports_bytes_environ

環境のネイティブ OS タイプがバイト型の場合、 True です (例: Windows では、 False です)。

Added in version 3.2.

os.umask(mask, /)

現在の数値 umask を設定し、以前の umask 値を返します。

The function is a stub on Emscripten and WASI, see WebAssemblyプラットフォーム for more information.

os.uname()

現在のオペレーティングシステムを識別する情報を返します。返り値は 5 個の属性を持つオブジェクトです:

sysname - OS の名前

nodename - (実装時に定義された) ネットワーク上でのマシン名

release - OS のリリース

version - OS のバージョン

machine - ハードウェア識別子

後方互換性のため、このオブジェクトはイテラブルでもあり、sysname、nodename、release、version、および machine の 5 個の要素をこの順序で持つタプルのように振る舞います。

一部のシステムでは、nodename はコンポーネントを読み込むために 8 文字または先頭の要素だけに切り詰められます; ホスト名を取得する方法としては、socket.gethostname() を使う方がよいでしょう。あるいは socket.gethostbyaddr(socket.gethostname()) でもかまいません。

利用可能な環境: Unix。

バージョン 3.3 で変更: 返り値の型が、タプルから属性名のついたタプルライクオブジェクトに変更されました。

os.unsetenv(key, /)

key という名前の環境変数を unset (削除) します。このような環境変数の変更は、os.system()、popen()、または fork() と execv() で起動されたサブプロセスに影響を与えます。

os.environ のアイテムの削除を行うと、自動的に unsetenv() の対応する呼び出しに変換されます。直接 unsetenv() を呼び出した場合 os.environ は更新されないため、実際には os.environ のアイテムを削除する方が望ましい操作です。

引数 key を指定して 監査イベント os.unsetenv を送出します。

バージョン 3.9 で変更: 常に関数は利用出来るようになりました。

os.unshare(flags)

Disassociate parts of the process execution context, and move them into a newly created namespace. See the unshare(2) [https://manpages.debian.org/unshare(2)] man page for more details. The flags argument is a bit mask, combining zero or more of the 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 0, no changes are made to the calling process's execution context.

Availability: Linux >= 2.6.16.

Added in version 3.12.

参考

The setns() function.

Flags to the unshare() function, if the implementation supports them. See unshare(2) [https://manpages.debian.org/unshare(2)] in the Linux manual for their exact effect and availability.

os.CLONE_FILES

os.CLONE_FS

os.CLONE_NEWCGROUP

os.CLONE_NEWIPC

os.CLONE_NEWNET

os.CLONE_NEWNS

os.CLONE_NEWPID

os.CLONE_NEWTIME

os.CLONE_NEWUSER

os.CLONE_NEWUTS

os.CLONE_SIGHAND

os.CLONE_SYSVSEM

os.CLONE_THREAD

os.CLONE_VM

ファイルオブジェクトの生成

以下の関数は新しい ファイルオブジェクト を作成します。(ファイル記述子のオープンについては open() も参照してください)

os.fdopen(fd, *args, **kwargs)

ファイル記述子 fd に接続し、オープンしたファイルオブジェクトを返します。これは組み込み関数 open() の別名であり、同じ引数を受け取ります。唯一の違いは fdopen() の第一引数が常に整数でなければならないことです。

ファイル記述子の操作

これらの関数は、ファイル記述子を使って参照されている I/O ストリームを操作します。

ファイル記述子とは現在のプロセスで開かれたファイルに対応する小さな整数です。例えば、標準入力のファイル記述子は通常 0 で、標準出力は 1 、標準エラーは 2 です。プロセスから開かれたその他のファイルには 3 、 4 、 5 と割り振られていきます。「ファイル記述子」という名称は少し誤解を与えるものかもしれません。Unix プラットフォームでは、ソケットやパイプもファイル記述子によって参照されます。

fileno() メソッドを使用して、必要な場合に file object に関連付けられているファイル記述子を取得することができます。ファイル記述子を直接使用すると、ファイルオブジェクトのメソッドが使用されないため、データの内部バッファなどの性質は無視されることに注意してください。

os.close(fd)

ファイル記述子 fd をクローズします。

注釈

この関数は低水準の I/O 向けのもので、 os.open() や pipe() が返すファイル記述子に対して使用しなければなりません。組み込み関数 open() や popen() 、 fdopen() が返す "ファイルオブジェクト" を閉じるには、オブジェクトの close() メソッドを使用してください。

os.closerange(fd_low, fd_high, /)

fd_low 以上 fd_high 未満のすべてのファイル記述子をエラーを無視してクローズします。以下のコードと等価です:

for fd in range(fd_low, fd_high):
    try:
        os.close(fd)
    except OSError:
        pass

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 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 OSError is raised with errno set to 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.

返り値はコピーされたバイトの量です。この値は、要求した量より少なくなることもあります。

注釈

On Linux, 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.

Availability: Linux >= 4.5 with glibc >= 2.27.

Added in version 3.8.

os.device_encoding(fd)

fd に関連付けられたデバイスが端末 (ターミナル) に接続されている場合に、そのデバイスのエンコーディングを表す文字列を返します。端末に接続されていない場合、 None を返します。

On Unix, if the Python UTF-8 Mode is enabled, return 'UTF-8' rather than the device encoding.

バージョン 3.10 で変更: On Unix, the function now implements the Python UTF-8 Mode.

os.dup(fd, /)

ファイル記述子 fd の複製を返します。新しいファイル記述子は 継承不可 です。

Windows では、標準ストリーム (0: 標準入力、1: 標準出力、2: 標準エラー出力) を複製する場合、新しいファイル記述子は 継承可能 です。

Availability: not WASI.

バージョン 3.4 で変更: 新しいファイル記述子が継承不可になりました。

os.dup2(fd, fd2, inheritable=True)

ファイル記述子 fd を fd2 に複製し、必要な場合には後者を先に閉じます。 fd2 が返ります。新しいファイル記述子はデフォルトでは 継承可能 で、inheritable が False の場合は継承不可です。

Availability: not WASI.

バージョン 3.4 で変更: オプションの inheritable 引数が追加されました。

バージョン 3.7 で変更: 成功したときは fd2 が返ります。以前は常に None が返っていました。

os.fchmod(fd, mode)

fd で指定されたファイルのモードを mode に変更します。mode に指定できる値については、chmod() のドキュメントを参照してください。Python 3.3 以降では os.chmod(fd, mode) と等価です。

引数 path, mode, dir_fd を指定して 監査イベント os.chmod を送出します。

利用可能な環境: Unix。

The function is limited on Emscripten and WASI, see WebAssemblyプラットフォーム for more information.

os.fchown(fd, uid, gid)

fd で指定されたファイルの所有者 id およびグループ id を数値 uid および gid に変更します。いずれかの id を変更せずにおくにはその値として -1 を指定します。chown() を参照してください。Python 3.3 以降では os.chown(fd, uid, gid) と等価です。

引数 path, uid, gid, dir_fd を指定して 監査イベント os.chown を送出します。

利用可能な環境: Unix。

The function is limited on Emscripten and WASI, see WebAssemblyプラットフォーム for more information.

os.fdatasync(fd)

ファイル記述子 fd を持つファイルのディスクへの書き込みを強制します。メタデータの更新は強制しません。

利用可能な環境: Unix。

注釈

この関数は MacOS では利用できません。

os.fpathconf(fd, name, /)

開いているファイルに関連するシステム設定情報を返します。 name は取得する設定名を指定します。これは、いくつかの標準 (POSIX.1 、 Unix 95 、 Unix 98 その他 ) で定義された定義済みのシステム値名の文字列である場合があります。プラットフォームによっては別の名前も定義されています。ホストオペレーティングシステムの関知する名前は pathconf_names 辞書で与えられています。このマップ型オブジェクトに含まれていない構成変数については、 name に整数を渡してもかまいません。

name が不明の文字列である場合、 ValueError を送出します。 name の特定の値がホストシステムでサポートされていない場合、 pathconf_names に含まれていたとしても、 errno.EINVAL をエラー番号として OSError を送出します。

Python 3.3 以降では os.pathconf(fd, name) と等価です。

利用可能な環境: Unix。

os.fstat(fd)

ファイル記述子 fd の状態を取得します。stat_result オブジェクトを返します。

Python 3.3 以降では os.stat(fd) と等価です。

参考

stat() 関数。

os.fstatvfs(fd, /)

statvfs() と同様に、ファイル記述子 fd に関連付けられたファイルが格納されているファイルシステムに関する情報を返します。Python 3.3 以降では os.statvfs(fd) と等価です。

利用可能な環境: Unix。

os.fsync(fd)

Force write of file with filedescriptor fd to disk. On Unix, this calls the native fsync() function; on Windows, the MS _commit() function.

Python の ファイルオブジェクト f を使う場合、f の内部バッファを確実にディスクに書き込むために、まず f.flush() を、その後 os.fsync(f.fileno()) を実行してください。

Availability: Unix, Windows。

os.ftruncate(fd, length, /)

ファイル記述子 fd に対応するファイルを、サイズが最長で length バイトになるように切り詰めます。Python 3.3 以降では os.truncate(fd, length) と等価です。

引数 fd, length を指定して 監査イベント os.truncate を送出します。

Availability: Unix, Windows。

バージョン 3.5 で変更: Windows サポートを追加しました。

os.get_blocking(fd, /)

記述子のブロッキングモードを取得します。 O_NONBLOCK フラグが設定されている場合は False で、フラグがクリアされている場合は True です。

set_blocking() および socket.socket.setblocking() も参照してください。

Availability: Unix, Windows。

The function is limited on Emscripten and WASI, see WebAssemblyプラットフォーム for more information.

On Windows, this function is limited to pipes.

Added in version 3.5.

バージョン 3.12 で変更: Added support for pipes on Windows.

os.isatty(fd, /)

ファイル記述子 fd がオープンされていて、 tty (のような) デバイスに接続されている場合、 True を返します。そうでない場合は False を返します。

os.lockf(fd, cmd, len, /)

オープンされたファイル記述子に対して、POSIX ロックの適用、テスト、解除を行います。fd はオープンされたファイル記述子です。cmd には使用するコマンド (F_LOCK、F_TLOCK、F_ULOCK、あるいは F_TEST のいずれか一つ) を指定します。len にはロックするファイルのセクションを指定します。

引数 fd, cmd, len を指定して 監査イベント os.lockf を送出します。

利用可能な環境: Unix。

Added in version 3.3.

os.F_LOCK

os.F_TLOCK

os.F_ULOCK

os.F_TEST

lockf() がとる動作を指定するフラグです。

利用可能な環境: Unix。

Added in version 3.3.

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.

Availability: Unix, not Emscripten, not WASI.

Added in version 3.11.

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:

SEEK_SET or 0 -- set pos relative to the beginning of the file

SEEK_CUR or 1 -- set pos relative to the current file position

SEEK_END or 2 -- set pos relative to the end of the file

SEEK_HOLE -- set pos to the next data location, relative to pos

SEEK_DATA -- set pos to the next data hole, relative to pos

バージョン 3.3 で変更: Add support for SEEK_HOLE and SEEK_DATA.

os.SEEK_SET

os.SEEK_CUR

os.SEEK_END

Parameters to the lseek() function and the seek() method on file-like objects, for whence to adjust the file position indicator.

SEEK_SET

Adjust the file position relative to the beginning of the file.

SEEK_CUR

Adjust the file position relative to the current file position.

SEEK_END

Adjust the file position relative to the end of the file.

Their values are 0, 1, and 2, respectively.

os.SEEK_HOLE

os.SEEK_DATA

Parameters to the lseek() function and the seek() method on file-like objects, for seeking file data and holes on sparsely allocated files.

SEEK_DATA

Adjust the file offset to the next location containing data, relative to the seek position.

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.

注釈

These operations only make sense for filesystems that support them.

Availability: Linux >= 3.1, macOS, Unix

Added in version 3.3.

os.open(path, flags, mode=0o777, *, dir_fd=None)

ファイル path を開き、flag に従って様々なフラグを設定し、可能なら mode に従ってファイルモードを設定します。mode を計算する際、まず現在の umask 値でマスクされます。新たに開いたファイルのファイル記述子を返します。新しいファイル記述子は 継承不可 です。

フラグとファイルモードの値についての詳細は C ランタイムのドキュメントを参照してください; (O_RDONLY や O_WRONLY のような) フラグ定数は os モジュールでも定義されています。特に、Windows ではバイナリモードでファイルを開く時に O_BINARY を加える必要があります。

この関数は dir_fd パラメタで ディレクトリ記述子への相対パス をサポートしています。

引数 path, mode, flags を指定して 監査イベント open を送出します。

バージョン 3.4 で変更: 新しいファイル記述子が継承不可になりました。

注釈

この関数は低水準の I/O 向けのものです。通常の利用では、組み込み関数 open() を使用してください。 open() は read() や write() (そしてさらに多くの) メソッドを持つ ファイルオブジェクト を返します。ファイル記述子をファイルオブジェクトでラップするには fdopen() を使用してください。

バージョン 3.3 で変更: 引数 dir_fd を追加しました。

バージョン 3.5 で変更: システムコールが中断されシグナルハンドラが例外を送出しなかった場合、この関数は InterruptedError 例外を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 [https://peps.python.org/pep-0475/] を参照してください)。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

以下の定数は open() 関数の flags 引数に利用します。これらの定数は、ビット単位に OR 演算子 | で組み合わせることができます。一部、すべてのプラットフォームでは使用できない定数があります。利用可能かどうかや使い方については、Unix では open(2) [https://manpages.debian.org/open(2)]、Windows では MSDN [https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx] を参照してください。

os.O_RDONLY

os.O_WRONLY

os.O_RDWR

os.O_APPEND

os.O_CREAT

os.O_EXCL

os.O_TRUNC

上記の定数は Unix および Windows で利用可能です。

os.O_DSYNC

os.O_RSYNC

os.O_SYNC

os.O_NDELAY

os.O_NONBLOCK

os.O_NOCTTY

os.O_CLOEXEC

上記の定数は Unix でのみ利用可能です。

バージョン 3.3 で変更: 定数 O_CLOEXEC が追加されました。

os.O_BINARY

os.O_NOINHERIT

os.O_SHORT_LIVED

os.O_TEMPORARY

os.O_RANDOM

os.O_SEQUENTIAL

os.O_TEXT

上記の定数は Windows でのみ利用可能です。

os.O_EVTONLY

os.O_FSYNC

os.O_SYMLINK

os.O_NOFOLLOW_ANY

上記の定数は macOS でのみ利用可能です。

バージョン 3.10 で変更: Add O_EVTONLY, O_FSYNC, O_SYMLINK and O_NOFOLLOW_ANY constants.

os.O_ASYNC

os.O_DIRECT

os.O_DIRECTORY

os.O_NOFOLLOW

os.O_NOATIME

os.O_PATH

os.O_TMPFILE

os.O_SHLOCK

os.O_EXLOCK

上記の定数は拡張仕様であり、Cライブラリで定義されていない場合は利用できません。

バージョン 3.4 で変更: O_PATH を、それをサポートするシステムで追加しました。また、 O_TMPFILE を追加しました (Linux Kernel 3.11 以降でのみ利用可能です)。

os.openpty()

新しい擬似端末のペアを開きます。pty および tty を表すファイル記述子のペア (master, slave) を返します。新しいファイル記述子は 継承不可 です。(若干) 可搬性の高いアプローチには pty を使用してください。

Availability: Unix, not Emscripten, not WASI.

バージョン 3.4 で変更: 新しいファイル記述子が継承不可になりました。

os.pipe()

パイプを作成します。読み込み、書き込みに使うことの出来るファイル記述子のペア (r, w) を返します。新しいファイル記述子は 継承不可 です。

Availability: Unix, Windows。

バージョン 3.4 で変更: 新しいファイル記述子が継承不可になりました。

os.pipe2(flags, /)

flags を設定したパイプをアトミックに作成します。flags には値 O_NONBLOCK と O_CLOEXEC を一つ以上論理和指定できます。読み込み、書き込みに使うことの出来るファイル記述子のペア (r, w) を返します。

Availability: Unix, not Emscripten, not WASI.

Added in version 3.3.

os.posix_fallocate(fd, offset, len, /)

fd で指定されたファイルに対し、開始位置 offset から len バイト分割り当てるに十分なディスクスペースを確保します。

Availability: Unix, not Emscripten.

Added in version 3.3.

os.posix_fadvise(fd, offset, len, advice, /)

データへアクセスする意思を、パターンを指定して宣言します。これによりカーネルが最適化を行えるようになります。advice は fd で指定されたファイルに対し、開始位置 offset から len バイト分の領域に適用されます。advice には POSIX_FADV_NORMAL、POSIX_FADV_SEQUENTIAL、POSIX_FADV_RANDOM、POSIX_FADV_NOREUSE、POSIX_FADV_WILLNEED、または POSIX_FADV_DONTNEED のいずれか一つを指定します。

利用可能な環境: Unix。

Added in version 3.3.

os.POSIX_FADV_NORMAL

os.POSIX_FADV_SEQUENTIAL

os.POSIX_FADV_RANDOM

os.POSIX_FADV_NOREUSE

os.POSIX_FADV_WILLNEED

os.POSIX_FADV_DONTNEED

posix_fadvise() において、使われるであろうアクセスパターンを指定する advice に使用できるフラグです。

利用可能な環境: Unix。

Added in version 3.3.

os.pread(fd, n, offset, /)

ファイル記述子の位置 offset から最大で n バイトを読み出します。ファイルオフセットは変化しません。

読み込んだバイト分のバイト列を返します。 fd が参照しているファイルの終端に達した場合、空のバイト列が返されます。

利用可能な環境: Unix。

Added in version 3.3.

os.preadv(fd, buffers, offset, flags=0, /)

ファイル記述子 fd の offset の位置から、可変な bytes-like オブジェクト buffers にオフセットを変更せずに読み込みます。データをそれぞれのバッファがいっぱいになるまで移し、いっぱいになったらシーケンスの次のバッファに処理を移し、残りのデータを読み込ませます。

flags 引数にはゼロあるいは次のフラグのバイトごとの OR を取った結果が保持されています。

RWF_HIPRI

RWF_NOWAIT

実際に読み込んだ合計バイト数を返します。この値は、すべてのオブジェクトの容量の総量よりも小さくなることがあります。

オペレーティングシステムは、使用可能なバッファの個数に基づいて上限 (sysconf() の 'SC_IOV_MAX' の値) を設定することがあります。

os.readv() と os.pread() の機能を統合します。

Availability: Linux >= 2.6.30, FreeBSD >= 6.0, OpenBSD >= 2.7, AIX >= 7.1.

Using flags requires Linux >= 4.6.

Added in version 3.7.

os.RWF_NOWAIT

即座に利用できないデータを待ちません。このフラグを指定すると、バックエンドのストレージからデータを読む必要があるか、ロックを待機する場合、システムコールは即座にリターンします。

If some data was successfully read, it will return the number of bytes read. If no bytes were read, it will return -1 and set errno to errno.EAGAIN.

利用可能な環境: Linux 4.14以上。

Added in version 3.7.

os.RWF_HIPRI

優先度の高い読み込み・書き込み (read/write) フラグです。ブロックストレージに対して、追加のリソースを必要とする一方で低レイテンシなデバイスのポーリングを使うことを許可します。

現状、Linuxでは、ファイル記述子を O_DIRECT フラグを指定したオープンした場合でのみ、この機能を利用できます。

利用可能な環境: Linux 4.6以上。

Added in version 3.7.

os.pwrite(fd, str, offset, /)

str 中のバイト文字列をファイル記述子 fd の offset の位置に書き込みます。ファイルオフセットを変化しません。

実際に書き込まれたバイト数を返します。

利用可能な環境: Unix。

Added in version 3.3.

os.pwritev(fd, buffers, offset, flags=0, /)

buffers の内容をファイル記述子 fd のオフセット位置 offset に書き込みます。ファイルのオフセット位置は変更しません。 buffers は bytes-like オブジェクト のシーケンスでなければなりません。バッファは配列の順番で処理されます。すなわち、最初のバッファの内容は、次のバッファの処理に移る前に全て書き込まれ、以降も同様に処理されます。

flags 引数にはゼロあるいは次のフラグのバイトごとの OR を取った結果が保持されています。

RWF_DSYNC

RWF_SYNC

RWF_APPEND

実際に書き込まれた合計バイト数を返します。

オペレーティングシステムは、使用可能なバッファの個数に基づいて上限 (sysconf() の 'SC_IOV_MAX' の値) を設定することがあります。

os.writev() と os.pwrite() の機能を統合します。

Availability: Linux >= 2.6.30, FreeBSD >= 6.0, OpenBSD >= 2.7, AIX >= 7.1.

Using flags requires Linux >= 4.6.

Added in version 3.7.

os.RWF_DSYNC

書き込みごとに os.open() の O_DSYNC と同等の効果を提供するフラグです。このフラグはシステムコールによって書き込まれたデータ範囲に対してのみ適用されます。

利用可能な環境: Linux 4.7以上。

Added in version 3.7.

os.RWF_SYNC

書き込みごとに os.open() の O_SYNC と同等の効果を提供するフラグです。このフラグはシステムコールによって書き込まれたデータ範囲に対してのみ適用されます。

利用可能な環境: Linux 4.7以上。

Added in version 3.7.

os.RWF_APPEND

Provide a per-write equivalent of the O_APPEND os.open() flag. This flag is meaningful only for 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 -1, the current file offset is updated.

利用可能な環境: Linux 4.16以上。

Added in version 3.10.

os.read(fd, n, /)

ファイル記述子 fd から 最大 n バイトを読み込みます。

読み込んだバイト分のバイト列を返します。 fd が参照しているファイルの終端に達した場合、空のバイト列が返されます。

注釈

この関数は低水準の I/O 向けのもので、 os.open() や pipe() が返すファイル記述子に対して使用されなければなりません。組み込み関数 open() や popen() 、 fdopen() 、あるいは sys.stdin が返す "ファイルオブジェクト" を読み込むには、オブジェクトの read() か readline() メソッドを使用してください。

バージョン 3.5 で変更: システムコールが中断されシグナルハンドラが例外を送出しなかった場合、この関数は InterruptedError 例外を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 [https://peps.python.org/pep-0475/] を参照してください)。

os.sendfile(out_fd, in_fd, offset, count)

os.sendfile(out_fd, in_fd, offset, count, headers=(), trailers=(), flags=0)

ファイル記述子 in_fd からファイル記述子 out_fd への開始位置 offset へ count バイトコピーします。送信バイト数を返します。 EOF に達した場合は 0 を返します。

前者の関数表記は sendfile() が定義されているすべてのプラットフォームでサポートされています。

Linux では、offset に None が与えられると、バイト列は in_fd の現在の位置から読み込まれ、in_fd の位置は更新されます。

後者は macOS および FreeBSD で使用される場合があります。headers および trailers は任意のバッファのシーケンス型オブジェクトで、in_fd からのデータが書き出される前と後に書き出されます。返り値は前者と同じです。

macOS と FreeBSD では、count の値に 0 を指定すると、 in_fd の末尾に達するまで送信します。

全てのプラットフォームはソケットをファイル記述子 out_fd としてサポートし、あるプラットフォームは他の種類 (例えば、通常のファイル、パイプ) も同様にサポートします。

クロスプラットフォームのアプリケーションは headers、trailers ならびに flags 引数を使用するべきではありません。

Availability: Unix, not Emscripten, not WASI.

注釈

sendfile() のより高水準のラッパについては socket.socket.sendfile() を参照してください。

Added in version 3.3.

バージョン 3.9 で変更: 引数 out と in は out_fd と in_fd に名前が変更されました。

os.SF_NODISKIO

os.SF_MNOWAIT

os.SF_SYNC

実装がサポートしている場合 sendfile() 関数に渡すパラメーターです。

Availability: Unix, not Emscripten, not WASI.

Added in version 3.3.

os.SF_NOCACHE

Parameter to the sendfile() function, if the implementation supports it. The data won't be cached in the virtual memory and will be freed afterwards.

Availability: Unix, not Emscripten, not WASI.

Added in version 3.11.

os.set_blocking(fd, blocking, /)

指定されたファイル記述子のブロッキングモードを設定します。ブロッキングが False の場合 O_NONBLOCK フラグを設定し、そうでない場合はクリアします。

get_blocking() および socket.socket.setblocking() も参照してください。

Availability: Unix, Windows。

The function is limited on Emscripten and WASI, see WebAssemblyプラットフォーム for more information.

On Windows, this function is limited to pipes.

Added in version 3.5.

バージョン 3.12 で変更: Added support for pipes on Windows.

os.splice(src, dst, count, offset_src=None, offset_dst=None)

Transfer count bytes from file descriptor src, starting from offset offset_src, to file descriptor dst, starting from offset offset_dst. At least one of the file descriptors must refer to a pipe. If offset_src is 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 None. The files pointed to by src and dst must reside in the same filesystem, otherwise an OSError is raised with errno set to errno.EXDEV.

このコピーは、カーネルからユーザースペースにデータを転送した後カーネルに戻すという追加のコスト無しに完了します。加えて、追加の最適化ができるファイルシステムもあります。このコピーはファイルが両方ともバイナリファイルとして開かれたかのように行われます。

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.

Availability: Linux >= 2.6.17 with glibc >= 2.5

Added in version 3.10.

os.SPLICE_F_MOVE

os.SPLICE_F_NONBLOCK

os.SPLICE_F_MORE

Added in version 3.10.

os.readv(fd, buffers, /)

Read from a file descriptor fd into a number of mutable 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.

実際に読み込んだ合計バイト数を返します。この値は、すべてのオブジェクトの容量の総量よりも小さくなることがあります。

オペレーティングシステムは、使用可能なバッファの個数に基づいて上限 (sysconf() の 'SC_IOV_MAX' の値) を設定することがあります。

利用可能な環境: Unix。

Added in version 3.3.

os.tcgetpgrp(fd, /)

fd (os.open() が返すオープンしたファイル記述子 ) で与えられる端末に関連付けられたプロセスグループを返します。

Availability: Unix, not WASI.

os.tcsetpgrp(fd, pg, /)

fd (os.open() が返すオープンしたファイル記述子 ) で与えられる端末に関連付けられたプロセスグループを pg に設定します。

Availability: Unix, not WASI.

os.ttyname(fd, /)

ファイル記述子 fd に関連付けられている端末デバイスを特定する文字列を返します。 fd が端末に関連付けられていない場合、例外が送出されます。

利用可能な環境: Unix。

os.write(fd, str, /)

str のバイト列をファイル記述子 fd に書き出します。

実際に書き込まれたバイト数を返します。

注釈

この関数は低水準の I/O 向けのもので、 os.open() や pipe() が返すファイル記述子に対して使用しなければなりません。組み込み関数 open() や popen() 、 fdopen() 、あるいは sys.stdout や sys.stderr が返す "ファイルオブジェクト" に書き込むには、オブジェクトの write() メソッドを使用してください。

バージョン 3.5 で変更: システムコールが中断されシグナルハンドラが例外を送出しなかった場合、この関数は InterruptedError 例外を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 [https://peps.python.org/pep-0475/] を参照してください)。

os.writev(fd, buffers, /)

buffers の内容をファイル記述子 fd へ書き出します。 buffers は bytes-like オブジェクト のシーケンスでなければなりません。バッファは配列の順番で処理されます。最初のバッファの内容全体は 2 番目のバッファに進む前に書き込まれ、その次も同様です。

実際に書き込まれた合計バイト数を返します。

オペレーティングシステムは、使用可能なバッファの個数に基づいて上限 (sysconf() の 'SC_IOV_MAX' の値) を設定することがあります。

利用可能な環境: Unix。

Added in version 3.3.

ターミナルのサイズの問い合わせ

Added in version 3.3.

os.get_terminal_size(fd=STDOUT_FILENO, /)

ターミナル (端末) のサイズ (columns, lines) を、terminal_size 型のタプルで返します。

オプションの引数 fd には問い合わせるファイル記述子を指定します (デフォルトは STDOUT_FILENO、または標準出力)。

ファイル記述子が接続されていなかった場合、 OSError が送出されます。

通常は高水準関数である shutil.get_terminal_size() を使用してください。os.get_terminal_size は低水準の実装です。

Availability: Unix, Windows。

class os.terminal_size

ターミナルウィンドウのサイズ (columns, lines) を保持するタプルのサブクラスです。

columns

ターミナルウィンドウの横幅 (文字数) です。

lines

ターミナルウィンドウの高さ (文字数) です。

ファイル記述子の継承

Added in version 3.4.

ファイル記述子には「継承可能 (inheritable)」フラグというものがあって、これにより子プロセスにファイル記述子が引き継がれるかどうかが決定されます。Python 3.4 より、 Python によって作成されるファイル記述子はデフォルトで継承不可 (non-inheritable) となりました。

UNIX の場合、継承不可のファイル記述子は新規プロセス実行時にクローズされ、そうでないファイル記述子は引き継がれます。

Windows の場合は、標準ストリームを除き、継承不可のハンドルと継承不可のファイル記述子は子プロセスでクローズされます。標準ストリーム (ファイル記述子の 0, 1, 2: 標準入力, 標準出力, 標準エラー出力) は常に引き継がれます。 spawn* 関数を使う場合、全ての継承可能なハンドルと全ての継承可能なファイル記述子は引き継がれます。 subprocess モジュールを使う場合、標準ストリームを除く全てのファイル記述子はクローズされ、継承可能なハンドルは close_fds 引数が False の場合にのみ引き継がれます。

On WebAssembly platforms wasm32-emscripten and wasm32-wasi, the file descriptor cannot be modified.

os.get_inheritable(fd, /)

指定したファイル記述子の「継承可能 (inheritable)」フラグを取得します (boolean)。

os.set_inheritable(fd, inheritable, /)

指定したファイル記述子の「継承可能 (inheritable)」フラグをセットします。

os.get_handle_inheritable(handle, /)

指定したハンドルの「継承可能 (inheritable)」フラグを取得します (boolean)。

利用可能な環境: Windows 。

os.set_handle_inheritable(handle, inheritable, /)

指定したハンドルの「継承可能 (inheritable)」フラグをセットします。

利用可能な環境: Windows 。

ファイルとディレクトリ

一部の Unix プラットフォームでは、このセクションの関数の多くが以下の機能を一つ以上サポートしています。

ファイル記述子の指定: os モジュールの関数で path 引数に渡される値はファイルパスでなければなりません。しかしながら、いくつかの関数では path 引数にファイルパスではなく、そのファイルをオープンしたファイル記述子を指定できるようになりました。この場合それらの関数はファイル記述子が参照するファイルに対して操作を行います。 (POSIX システムの場合、 Python はプレフィックス f の付いた関数の亜種 (たとえば chdir``の代わりに ``fchdir) を呼び出します。)

os.supports_fd を使うことで、そのプラットフォーム上で path にファイル記述子を指定できるかどうかを確認することができます。この機能が利用可能でない場合、 os.supports_fd の利用は NotImplementedError 例外を送出します。

その関数が引数に dir_fd または follow_symlinks もサポートしている場合、path にファイル記述子を指定した時にそれらのいずれかを指定するとエラーになります。

ディレクトリ記述子からの相対パス: dir_fd が None でない場合、その値はディレクトリを参照するファイル記述子である必要があり、また操作対象のファイルパスは相対パスである必要があります; このときパスはファイル記述子が指すディレクトリからの相対パスと解釈されます。パスが絶対パスの場合、 dir_fd は無視されます。 (POSIX システムでは、 Python はサフィックス at が付いた関数の亜種、もしくはさらにプレフィックス f が付いたもの (たとえば access の代わりに faccessat) を呼び出します。

そのプラットフォーム上で特別な関数に dir_fd がサポートされているかどうかは、os.supports_dir_fd で確認できます。利用できない場合 NotImplementedError が送出されます。

シンボリックリンクをたどらない: follow_symlinks が False で、かつパスの末尾の要素がシンボリックリンクの場合、関数はシンボリックリンクが指すファイルではなくシンボリックリンク自身を操作対象とします。 (POSIX システムの場合、 Python はプレフィックス l... 付きの関数の亜種を呼び出します。)

そのプラットフォーム上で特別な関数に follow_symlinks がサポートされているかどうかは、os.supports_follow_symlinks で確認できます。利用できない場合 NotImplementedError が送出されます。

os.access(path, mode, *, dir_fd=None, effective_ids=False, follow_symlinks=True)

実 uid/gid を使って path に対するアクセスが可能か調べます。ほとんどのオペレーティングシステムは実効 uid/gid を使うため、このルーチンは suid/sgid 環境において、プログラムを起動したユーザーが path に対するアクセス権をもっているかを調べるために使われます。 path が存在するかどうかを調べるには mode を F_OK にします。ファイルアクセス権限 ( パーミッション ) を調べるには、 R_OK, W_OK, X_OK から一つまたはそれ以上のフラグを論理和指定でとることもできます。アクセスが許可されている場合 True を、そうでない場合 False を返します。詳細は access(2) [https://manpages.debian.org/access(2)] の Unix マニュアルページを参照してください。

この関数は ディレクトリ記述子への相対パス および シンボリックリンクをたどらない をサポートしています。

effective_ids が True の場合、access() は実 uid/gid ではなく実効 uid/gid を使用してアクセス権を調べます。プラットフォームによっては effective_ids がサポートされていない場合があります; サポートされているかどうかは os.supports_effective_ids で確認できます。利用できない場合 NotImplementedError が送出されます。

注釈

ユーザーが、例えばファイルを開く権限を持っているかどうかを調べるために実際に open() を行う前に access() を使用することはセキュリティホールの原因になります。なぜなら、調べた時点とオープンした時点との時間差を利用してそのユーザーがファイルを不当に操作してしまうかもしれないからです。その場合は EAFP テクニックを利用するのが望ましいやり方です。例えば

if os.access("myfile", os.R_OK):
    with open("myfile") as fp:
        return fp.read()
return "some default data"

このコードは次のように書いたほうが良いです

try:
    fp = open("myfile")
except PermissionError:
    return "some default data"
else:
    with fp:
        return fp.read()

注釈

I/O 操作は access() が成功を示した時でも失敗することがあります。特にネットワークファイルシステムが通常の POSIX のパーミッションビットモデルをはみ出すアクセス権限操作を備える場合にはそのようなことが起こりえます。

バージョン 3.3 で変更: 引数 dir_fd、effective_ids、および follow_symlinks が追加されました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.F_OK

os.R_OK

os.W_OK

os.X_OK

access() で path をテストする時に mode 引数に渡す値です。上からそれぞれ、ファイルの存在、読み込み許可、書き込み許可、および実行許可になります。

os.chdir(path)

現在の作業ディレクトリを path に設定します。

この関数は ファイル記述子の指定 をサポートしています。記述子は、オープンしているファイルではなく、オープンしているディレクトリを参照していなければなりません。

この関数は OSError やそのサブクラスである FileNotFoundError, PermissionError, NotADirectoryError などの例外を送出することがあります。

引数 path を指定して 監査イベント os.chdir を送出します。

バージョン 3.3 で変更: 一部のプラットフォームで、path にファイル記述子の指定をサポートしました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.chflags(path, flags, *, follow_symlinks=True)

path のフラグを flags に変更します。 flags は、以下の値 (stat モジュールで定義されているもの ) をビット単位の論理和で組み合わせることができます :

stat.UF_NODUMP

stat.UF_IMMUTABLE

stat.UF_APPEND

stat.UF_OPAQUE

stat.UF_NOUNLINK

stat.UF_COMPRESSED

stat.UF_HIDDEN

stat.SF_ARCHIVED

stat.SF_IMMUTABLE

stat.SF_APPEND

stat.SF_NOUNLINK

stat.SF_SNAPSHOT

この関数は シンボリックリンクをたどらない をサポートしています。

引数 path, flags を指定して 監査イベント os.chflags を送出します。

Availability: Unix, not Emscripten, not WASI.

バージョン 3.3 で変更: Added the follow_symlinks parameter.

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.chmod(path, mode, *, dir_fd=None, follow_symlinks=True)

path のモードを数値 mode に変更します。 mode は、 (stat モジュールで定義されている ) 以下の値のいずれかまたはビット単位の論理和で組み合わせた値を取り得ます :

stat.S_ISUID

stat.S_ISGID

stat.S_ENFMT

stat.S_ISVTX

stat.S_IREAD

stat.S_IWRITE

stat.S_IEXEC

stat.S_IRWXU

stat.S_IRUSR

stat.S_IWUSR

stat.S_IXUSR

stat.S_IRWXG

stat.S_IRGRP

stat.S_IWGRP

stat.S_IXGRP

stat.S_IRWXO

stat.S_IROTH

stat.S_IWOTH

stat.S_IXOTH

この関数は ファイル記述子の指定 、 ディレクトリ記述子への相対パス 、および シンボリックリンクをたどらない をサポートしています。

注釈

Although Windows supports chmod(), you can only set the file's read-only flag with it (via the stat.S_IWRITE and stat.S_IREAD constants or a corresponding integer value). All other bits are ignored.

The function is limited on Emscripten and WASI, see WebAssemblyプラットフォーム for more information.

引数 path, mode, dir_fd を指定して 監査イベント os.chmod を送出します。

バージョン 3.3 で変更: path にオープンしているファイル記述子の指定のサポート、および引数 dir_fd と follow_symlinks を追加しました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.chown(path, uid, gid, *, dir_fd=None, follow_symlinks=True)

path の所有者 id およびグループ id を、数値 uid および gid に変更します。いずれかの id を変更せずにおくには、その値として -1 を指定します。

この関数は ファイル記述子の指定 、 ディレクトリ記述子への相対パス 、および シンボリックリンクをたどらない をサポートしています。

数値 id の他に名前でも受け取る高水準関数の shutil.chown() を参照してください。

引数 path, uid, gid, dir_fd を指定して 監査イベント os.chown を送出します。

利用可能な環境: Unix。

The function is limited on Emscripten and WASI, see WebAssemblyプラットフォーム for more information.

バージョン 3.3 で変更: path にオープンしているファイル記述子の指定のサポート、および引数 dir_fd と follow_symlinks を追加しました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.chroot(path)

現在のプロセスのルートディレクトリを path に変更します。

Availability: Unix, not Emscripten, not WASI.

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.fchdir(fd)

現在の作業ディレクトリをファイル記述子 fd が表すディレクトリに変更します。記述子はオープンしているファイルではなく、オープンしたディレクトリを参照していなければなりません。Python 3.3 以降では os.chdir(fd) と等価です。

引数 path を指定して 監査イベント os.chdir を送出します。

利用可能な環境: Unix。

os.getcwd()

現在の作業ディレクトリを表す文字列を返します。

os.getcwdb()

現在の作業ディレクトリを表すバイト列を返します。

バージョン 3.8 で変更: この関数は Windows において ANSI コードページ ではなく UTF-8 エンコーディングを使うようになりました: 変更の背景については PEP 529 [https://peps.python.org/pep-0529/] をご覧ください。この関数は Windows において非推奨になりません。

os.lchflags(path, flags)

path のフラグを数値 flags に設定します。chflags() に似ていますが、シンボリックリンクをたどりません。Python 3.3 以降では os.chflags(path, flags, follow_symlinks=False) と等価です。

引数 path, flags を指定して 監査イベント os.chflags を送出します。

Availability: Unix, not Emscripten, not WASI.

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.lchmod(path, mode)

path のモードを数値 mode に変更します。パスがシンボリックリンクの場合はそのリンク先ではなくシンボリックリンクそのものに対して作用します。mode に指定できる値については chmod() のドキュメントを参照してください。Python 3.3 以降では os.chmod(path, mode, follow_symlinks=False) と等価です。

lchmod() is not part of POSIX, but Unix implementations may have it if changing the mode of symbolic links is supported.

引数 path, mode, dir_fd を指定して 監査イベント os.chmod を送出します。

Availability: Unix, not Linux, FreeBSD >= 1.3, NetBSD >= 1.3, not OpenBSD

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.lchown(path, uid, gid)

path の所有者 id およびグループ id を、数値 uid および gid に変更します。この関数はシンボリックリンクをたどりません。Python 3.3 以降では os.chown(path, uid, gid, follow_symlinks=False) と等価です。

引数 path, uid, gid, dir_fd を指定して 監査イベント os.chown を送出します。

利用可能な環境: Unix。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.link(src, dst, *, src_dir_fd=None, dst_dir_fd=None, follow_symlinks=True)

src を指し示すハードリンク dst を作成します。

この関数は src_dir_fd と dst_dir_fd の両方またはどちらかに対し ディレクトリ記述子への相対パス および シンボリックリンクをたどらない をサポートしています。

引数 src, dst, src_dir_fd, dst_dir_fd を指定して 監査イベント os.link を送出します。

Availability: Unix, Windows, not Emscripten.

バージョン 3.2 で変更: Windows サポートを追加しました。

バージョン 3.3 で変更: Added the src_dir_fd, dst_dir_fd, and follow_symlinks parameters.

バージョン 3.6 で変更: src と dst が path-like object を受け付けるようになりました。

os.listdir(path='.')

path に指定したディレクトリに含まれるエントリ名のリストを返します。リストの順番は不定です。特別なエントリ '.' と '..' はリストに含まれません。この関数の呼び出し中にディレクトリからファイルが削除されたり、ディレクトリにファイルが追加されたりした場合、それらのファイルがリストに含まれるかどうかは不定です。

path に path-like オブジェクト を指定することもできます。 path が (直接的または間接的に PathLike インターフェースを介した) bytes 型の場合、戻り値のファイル名も bytes 型になります; それ以外の場合、ファイル名は str 型です。

この関数は ファイル記述子の指定 もサポートしています; ファイル記述子はディレクトリを参照していなくてはなりません。

引数 path を指定して 監査イベント os.listdir を送出します。

注釈

文字列型 のファイル名を バイト列型 にエンコードするには、fsencode() を使用します。

参考

ディレクトリエントリに加えてファイル属性情報も返す scandir() 関数の方が、多くの一般的な用途では使い勝手が良くなります。

バージョン 3.2 で変更: 引数 path は任意になりました。

バージョン 3.3 で変更: path へのオープン・ファイル記述子の指定をサポートしました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.listdrives()

Return a list containing the names of drives on a Windows system.

A drive name typically looks like '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 OSError if an error occurs collecting the drive names.

Raises an auditing event os.listdrives with no arguments.

Availability: Windows

Added in version 3.12.

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 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 OSError if the volume is not recognized or if an error occurs collecting the paths.

Raises an auditing event os.listmounts with argument volume.

Availability: Windows

Added in version 3.12.

os.listvolumes()

Return a list containing the volumes in the system.

Volumes are typically represented as a GUID path that looks like \\?\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 os.listmounts().

May raise OSError if an error occurs collecting the volumes.

Raises an auditing event os.listvolumes with no arguments.

Availability: Windows

Added in version 3.12.

os.lstat(path, *, dir_fd=None)

Perform the equivalent of an lstat() system call on the given path. Similar to stat(), but does not follow symbolic links. Return a stat_result object.

シンボリックリンクをサポートしていないプラットフォームでは stat() の別名です。

Python 3.3 以降では os.stat(path, dir_fd=dir_fd, follow_symlinks=False) と等価です。

この関数は ディレクトリ記述子への相対パス もサポートすることができます。

参考

stat() 関数。

バージョン 3.2 で変更: Windows 6.0 (Vista) のシンボリックリンクをサポートしました。

バージョン 3.3 で変更: 引数 dir_fd を追加しました。

バージョン 3.6 で変更: 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 stat().

os.mkdir(path, mode=0o777, *, dir_fd=None)

ディレクトリ path を数値モード mode で作成します。

If the directory already exists, FileExistsError is raised. If a parent directory in the path does not exist, FileNotFoundError is raised.

いくつかのシステムにおいては mode は無視されます。それが使われる時には、最初に現在の umask 値でマスクされます。もし最後の 9 ビット (つまり mode の8進法表記の最後の3桁) を除いたビットが設定されていたら、それらの意味はプラットフォームに依存します。いくつかのプラットフォームではそれらは無視され、それらを設定するためには明示的に chmod() を呼ぶ必要があるでしょう。

On Windows, a mode of 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.

この関数は ディレクトリ記述子への相対パス もサポートすることができます。

一時ディレクトリを作成することもできます : tempfile モジュールの tempfile.mkdtemp() 関数を参照してください。

引数 path, mode, dir_fd を指定して 監査イベント os.mkdir を送出します。

バージョン 3.3 で変更: 引数 dir_fd を追加しました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

バージョン 3.12.4 で変更: Windows now handles a mode of 0o700.

os.makedirs(name, mode=0o777, exist_ok=False)

再帰的にディレクトリを作成する関数です。mkdir() と似ていますが、末端ディレクトリを作成するために必要なすべての中間ディレクトリも作成します。

The mode parameter is passed to mkdir() for creating the leaf directory; see 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 makedirs(). The file permission bits of existing parent directories are not changed.

exist_ok の値が False の場合 (デフォルト)、対象のディレクトリがすでに存在すると FileExistsError を送出します。

注釈

作成するパス要素に pardir (UNIX では "..") が含まれる場合、makedirs() は混乱します。

この関数は UNC パスを正しく扱えるようになりました。

引数 path, mode, dir_fd を指定して 監査イベント os.mkdir を送出します。

バージョン 3.2 で変更: Added the exist_ok parameter.

バージョン 3.4.1 で変更: Python 3.4.1 より前、 exist_ok が True でそのディレクトリが既存の場合でも、 makedirs() は mode が既存ディレクトリのモードと合わない場合にはエラーにしようとしていました。このモードチェックの振る舞いを安全に実装することが出来なかったため、 Python 3.4.1 でこのチェックは削除されました。 bpo-21082 [https://bugs.python.org/issue?@action=redirect&bpo=21082] を参照してください。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

バージョン 3.7 で変更: The mode argument no longer affects the file permission bits of newly created intermediate-level directories.

os.mkfifo(path, mode=0o666, *, dir_fd=None)

FIFO (名前付きパイプ) path を数値モード mode で作成します。先に現在の umask 値でマスクされます。

この関数は ディレクトリ記述子への相対パス もサポートすることができます。

FIFO は通常のファイルのようにアクセスできるパイプです。 FIFO は ( 例えば os.unlink() を使って ) 削除されるまで存在しつづけます。一般的に、 FIFO は " クライアント " と " サーバー " 形式のプロセス間でランデブーを行うために使われます : この時、サーバーは FIFO を読み込み用に、クライアントは書き出し用にオープンします。 mkfifo() は FIFO をオープンしない --- 単にランデブーポイントを作成するだけ --- なので注意してください。

Availability: Unix, not Emscripten, not WASI.

バージョン 3.3 で変更: 引数 dir_fd を追加しました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.mknod(path, mode=0o600, device=0, *, dir_fd=None)

path という名前で、ファイルシステムノード (ファイル、デバイス特殊ファイル、または名前つきパイプ) を作成します。mode は、作成するノードのアクセス権限とタイプの両方を stat.S_IFREG、stat.S_IFCHR、stat.S_IFBLK、および stat.S_IFIFO の組み合わせ (ビット単位の論理和) で指定します (これらの定数は stat で利用可能です)。stat.S_IFCHR と stat.S_IFBLK を指定した場合、devide は新しく作成されたデバイス特殊ファイルを (おそらく os.makedev() を使って) 定義し、それ以外の定数を指定した場合は無視されます。

この関数は ディレクトリ記述子への相対パス もサポートすることができます。

Availability: Unix, not Emscripten, not WASI.

バージョン 3.3 で変更: 引数 dir_fd を追加しました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.major(device, /)

Extract the device major number from a raw device number (usually the st_dev or st_rdev field from stat).

os.minor(device, /)

Extract the device minor number from a raw device number (usually the st_dev or st_rdev field from stat).

os.makedev(major, minor, /)

メジャーおよびマイナーデバイス番号から、新しく RAW デバイス番号を作成します。

os.pathconf(path, name)

名前付きファイルに関連するシステム設定情報を返します。 name には取得したい設定名を指定します ; これは定義済みのシステム値名の文字列で、多くの標準 (POSIX.1 、 Unix 95 、 Unix 98 その他 ) で定義されています。プラットフォームによっては別の名前も定義しています。ホストオペレーティングシステムの関知する名前は pathconf_names 辞書で与えられています。このマップ型オブジェクトに入っていない設定変数については、 name に整数を渡してもかまいません。

name が不明の文字列である場合、 ValueError を送出します。 name の特定の値がホストシステムでサポートされていない場合、 pathconf_names に含まれていたとしても、 errno.EINVAL をエラー番号として OSError を送出します。

この関数は ファイル記述子の指定 をサポートしています。

利用可能な環境: Unix。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.pathconf_names

pathconf() および fpathconf() が受理するシステム設定名を、ホストオペレーティングシステムで定義されている整数値に対応付けている辞書です。この辞書はシステムでどの設定名が定義されているかを知るために利用できます。

利用可能な環境: Unix。

os.readlink(path, *, dir_fd=None)

シンボリックリンクが指しているパスを表す文字列を返します。返される値は絶対パスにも、相対パスにもなり得ます ; 相対パスの場合、 os.path.join(os.path.dirname(path), result) を使って絶対パスに変換することができます。

If the path is a string object (directly or indirectly through a 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.

この関数は ディレクトリ記述子への相対パス もサポートすることができます。

When trying to resolve a path that may contain links, use realpath() to properly handle recursion and platform differences.

Availability: Unix, Windows。

バージョン 3.2 で変更: Windows 6.0 (Vista) のシンボリックリンクをサポートしました。

バージョン 3.3 で変更: 引数 dir_fd を追加しました。

バージョン 3.6 で変更: Unixで、 path-like object を受け入れるようになりました。

バージョン 3.8 で変更: Windowsで、 path-like object と bytes オブジェクトを受け入れるようになりました。

Added support for directory junctions, and changed to return the substitution path (which typically includes \\?\ prefix) rather than the optional "print name" field that was previously returned.

os.remove(path, *, dir_fd=None)

Remove (delete) the file path. If path is a directory, an OSError is raised. Use rmdir() to remove directories. If the file does not exist, a FileNotFoundError is raised.

この関数は ディレクトリ記述子への相対パス をサポートしています。

Windows では、使用中のファイルを削除しようとすると例外を送出します; Unixでは、ディレクトリエントリは削除されますが、記憶装置上に割り当てられたファイル領域は元のファイルが使われなくなるまで残されます。

この関数は意味論的に unlink() と同一です。

引数 path, dir_fd を指定して 監査イベント os.remove を送出します。

バージョン 3.3 で変更: 引数 dir_fd を追加しました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.removedirs(name)

再帰的なディレクトリ削除関数です。 rmdir() と同じように動作しますが、末端ディレクトリがうまく削除できるかぎり、 removedirs() は path に現れる親ディレクトリをエラーが送出されるまで ( このエラーは通常、指定したディレクトリの親ディレクトリが空でないことを意味するだけなので無視されます ) 順に削除することを試みます。例えば、 os.removedirs('foo/bar/baz') では最初にディレクトリ 'foo/bar/baz' を削除し、次に 'foo/bar' さらに 'foo' をそれらが空ならば削除します。末端のディレクトリが削除できなかった場合には OSError が送出されます。

引数 path, dir_fd を指定して 監査イベント os.remove を送出します。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

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 OSError subclass in a number of cases:

On Windows, if dst exists a FileExistsError is always raised. The operation may fail if src and dst are on different filesystems. Use 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 IsADirectoryError or a 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 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).

この関数は src_dir_fd と dst_dir_fd のどちらかまたは両方の指定に ディレクトリ記述子への相対パス をサポートしています。

対象の上書きがクロスプラットフォームになる場合は replace() を使用してください。

引数 src, dst, src_dir_fd, dst_dir_fd を指定して 監査イベント os.rename を送出します。

バージョン 3.3 で変更: Added the src_dir_fd and dst_dir_fd parameters.

バージョン 3.6 で変更: src と dst が path-like object を受け付けるようになりました。

os.renames(old, new)

再帰的にディレクトリやファイル名を変更する関数です。 rename() のように動作しますが、新たなパス名を持つファイルを配置するために必要な途中のディレクトリ構造をまず作成しようと試みます。名前変更の後、元のファイル名のパス要素は removedirs() を使って右側から順に削除されます。

注釈

この関数はコピー元の末端のディレクトリまたはファイルを削除する権限がない場合には失敗します。

引数 src, dst, src_dir_fd, dst_dir_fd を指定して 監査イベント os.rename を送出します。

バージョン 3.6 で変更: old と new が path-like object を受け付けるようになりました。

os.replace(src, dst, *, src_dir_fd=None, dst_dir_fd=None)

ファイルまたはディレクトリ src の名前を dst へ変更します。dst が空でないディレクトリの場合 OSError が送出されます。dst が存在し、かつファイルの場合、ユーザーの権限がある限り暗黙のうちに置き換えられます。src と dst が異なるファイルシステム上にあると失敗することがあります。ファイル名の変更が成功する場合はアトミック操作となります (これは POSIX 要求仕様です)。

この関数は src_dir_fd と dst_dir_fd のどちらかまたは両方の指定に ディレクトリ記述子への相対パス をサポートしています。

引数 src, dst, src_dir_fd, dst_dir_fd を指定して 監査イベント os.rename を送出します。

Added in version 3.3.

バージョン 3.6 で変更: src と dst が path-like object を受け付けるようになりました。

os.rmdir(path, *, dir_fd=None)

Remove (delete) the directory path. If the directory does not exist or is not empty, a FileNotFoundError or an OSError is raised respectively. In order to remove whole directory trees, shutil.rmtree() can be used.

この関数は ディレクトリ記述子への相対パス をサポートしています。

引数 path, dir_fd を指定して 監査イベント os.rmdir を送出します。

バージョン 3.3 で変更: 引数 dir_fd を追加しました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.scandir(path='.')

Return an iterator of os.DirEntry objects corresponding to the entries in the directory given by path. The entries are yielded in arbitrary order, and the special entries '.' and '..' 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.

listdir() の代わりに scandir() を使用すると、ファイルタイプや属性情報も必要とするコードのパフォーマンスが大幅に向上します。これは、オペレーティングシステムがディレクトリのスキャン中にこの情報を提供した場合、os.DirEntry オブジェクトがその情報を公開するからです。すべての os.DirEntry メソッドはシステムコールを実行する場合がありますが、is_dir() と is_file() は、通常はシンボリックリンクにしかシステムコールを必要としません。os.DirEntry.stat() は、Unix 上では常にシステムコールを必要としますが、Windows ではシンボリックリンク用にシステムコールを一つ必要とするだけです。

path may be a path-like object. If path is of type bytes (directly or indirectly through the PathLike interface), the type of the name and path attributes of each os.DirEntry will be bytes; in all other circumstances, they will be of type str.

この関数は ファイル記述子の指定 もサポートしています; ファイル記述子はディレクトリを参照していなくてはなりません。

引数 path を指定して 監査イベント os.scandir を送出します。

scandir() イテレータは、 コンテキストマネージャ プロトコルをサポートし、次のメソッドを持ちます。

scandir.close()

イテレータを閉じ、獲得した資源を開放します。

この関数は、イテレータがすべて消費されるか、ガーベージコレクトされた、もしくはイテレート中にエラーが発生した際に自動的に呼び出されます。しかし、 with 文を用いるか、明示的に呼び出すことを推奨します。

Added in version 3.6.

次の単純な例では、scandir() を使用して、指定した path 内の先頭が '.' でないすべてのファイル (ディレクトリを除く) をすべて表示します。entry.is_file() を呼び出しても、通常は追加のシステムコールは行われません:

with os.scandir(path) as it:
    for entry in it:
        if not entry.name.startswith('.') and entry.is_file():
            print(entry.name)

注釈

On Unix-based systems, scandir() uses the system's opendir() [https://pubs.opengroup.org/onlinepubs/009695399/functions/opendir.html] and readdir() [https://pubs.opengroup.org/onlinepubs/009695399/functions/readdir_r.html] functions. On Windows, it uses the Win32 FindFirstFileW [https://msdn.microsoft.com/en-us/library/windows/desktop/aa364418(v=vs.85).aspx] and FindNextFileW [https://msdn.microsoft.com/en-us/library/windows/desktop/aa364428(v=vs.85).aspx] functions.

Added in version 3.5.

バージョン 3.6 で変更: Added support for the context manager protocol and the close() method. If a scandir() iterator is neither exhausted nor explicitly closed a ResourceWarning will be emitted in its destructor.

関数が path-like object を受け入れるようになりました。

バージョン 3.7 で変更: Unix で ファイル記述子の指定 のサポートが追加されました。

class os.DirEntry

ディレクトリエントリのファイルパスとその他のファイル属性を公開するために、scandir() が yield するオブジェクトです。

scandir() は、追加のシステムコールを実行することなく、この情報をできるだけ多く提供します。stat() または lstat() システムコールが実行された場合、os.DirEntry オブジェクトは結果をキャッシュします。

os.DirEntry インスタンスは、寿命の長いデータ構造に保存されることは想定されていません。ファイルメタデータが変更された場合や、 scandir() が呼び出されてから長時間が経過した場合は、 os.stat(entry.path) を呼び出して最新の情報を取得してください。

os.DirEntry のメソッドはオペレーティングシステムコールを実行する場合があるため、それらは OSError も送出する場合があります。エラーを細かく制御する必要がある場合、 os.DirEntry のメソッドの一つの呼び出し時に OSError を捕捉して、適切な処理を行うことができます。

To be directly usable as a path-like object, os.DirEntry implements the PathLike interface.

os.DirEntry インスタンスの属性とメソッドは以下の通りです:

name

scandir() の path 引数に対して相対的な、エントリのベースファイル名です。

The name attribute will be bytes if the scandir() path argument is of type bytes and str otherwise. Use fsdecode() to decode byte filenames.

path

The entry's full path name: equivalent to os.path.join(scandir_path, entry.name) where scandir_path is the scandir() path argument. The path is only absolute if the scandir() path argument was absolute. If the scandir() path argument was a file descriptor, the path attribute is the same as the name attribute.

The path attribute will be bytes if the scandir() path argument is of type bytes and str otherwise. Use fsdecode() to decode byte filenames.

inode()

項目の inode 番号を返します。

結果は os.DirEntry オブジェクトにキャッシュされます。最新の情報を取得するには os.stat(entry.path, follow_symlinks=False).st_ino を使用してください。

Windows 上では、最初のキャッシュされていない呼び出しでシステムコールが必要ですが、 Unix 上では必要ありません。

is_dir(*, follow_symlinks=True)

この項目がディレクトリまたはディレクトリへのシンボリックリンクである場合、 True を返します。項目がそれ以外のファイルやそれ以外のファイルへのシンボリックリンクである場合や、もはや存在しない場合は False を返します。

follow_symlinks が False の場合、項目がディレクトリ (シンボリックリンクはたどりません) の場合にのみ True を返します。項目がディレクトリ以外のファイルである場合や、項目がもはや存在しない場合は False を返します。

結果は os.DirEntry オブジェクトにキャッシュされます。follow_symlinks が True の場合と False の場合とでは、別のオブジェクトにキャッシュされます。最新の情報を取得するには stat.S_ISDIR() と共に os.stat() を呼び出してください。

多くの場合、最初のキャッシュされない呼び出しでは、システムコールは必要とされません。具体的には、シンボリックリンク以外では、Windows も Unix もシステムコールを必要としません。ただし、dirent.d_type == DT_UNKNOWN を返す、ネットワークファイルシステムなどの特定の Unix ファイルシステムは例外です。項目がシンボリックリンクの場合、follow_symlinks が False の場合を除き、シンボリックリンクをたどるためにシステムコールが必要となります。

このメソッドは PermissionError のような OSError を送出することがありますが、 FileNotFoundError は捕捉され送出されません。

is_file(*, follow_symlinks=True)

この項目がファイルまたはファイルへのシンボリックリンクである場合、 True を返します。項目がディレクトリやファイル以外の項目へのシンボリックリンクである場合や、もはや存在しない場合は False を返します。

follow_symlinks が False の場合、項目がファイル (シンボリックリンクはたどりません) の場合にのみ True を返します。項目がディレクトリやその他のファイル以外の項目である場合や、項目がもはや存在しない場合は False を返します。

結果は os.DirEntry オブジェクトにキャッシュされます。キャッシュ、システムコール、例外は、is_dir() と同様に行われます。

is_symlink()

この項目がシンボリックリンクの場合 (たとえ破損していても)、True を返します。項目がディレクトリやあらゆる種類のファイルの場合、またはもはや存在しない場合は False を返します。

結果は os.DirEntry オブジェクトにキャッシュされます。最新の情報をフェッチするには os.path.islink() を呼び出してください。

多くの場合、最初のキャッシュされない呼び出しでは、システムコールは必要とされません。具体的には、Windows も Unix もシステムコールを必要としません。ただし、dirent.d_type == DT_UNKNOWN を返す、ネットワークファイルシステムなどの特定の Unix ファイルシステムは例外です。

このメソッドは PermissionError のような OSError を送出することがありますが、 FileNotFoundError は捕捉され送出されません。

is_junction()

Return True if this entry is a junction (even if broken); return 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 os.DirEntry object. Call os.path.isjunction() to fetch up-to-date information.

Added in version 3.12.

stat(*, follow_symlinks=True)

この項目の stat_result オブジェクトを返します。このメソッドは、デフォルトでシンボリックリンクをたどります。シンボリックリンクを開始するには、 follow_symlinks=False 引数を追加します。

On Unix, this method always requires a system call. On Windows, it only requires a system call if follow_symlinks is True and the entry is a reparse point (for example, a symbolic link or directory junction).

Windows では、stat_result の st_ino 、 st_dev 、 st_nlink 属性は常にゼロに設定されます。これらの属性を取得するには、 os.stat() を呼び出します。

結果は os.DirEntry オブジェクトにキャッシュされます。follow_symlinks が True の場合と False の場合とでは、別のオブジェクトにキャッシュされます。最新の情報を取得するには、 os.stat() を呼び出してください。

Note that there is a nice correspondence between several attributes and methods of os.DirEntry and of pathlib.Path. In particular, the name attribute has the same meaning, as do the is_dir(), is_file(), is_symlink(), is_junction(), and stat() methods.

Added in version 3.5.

バージョン 3.6 で変更: PathLike インターフェースをサポートしました。Windowsで:class:bytes パスをサポートしました。

バージョン 3.12 で変更: The st_ctime attribute of a stat result is deprecated on Windows. The file creation time is properly available as st_birthtime, and in the future st_ctime may be changed to return zero or the metadata change time, if available.

os.stat(path, *, dir_fd=None, follow_symlinks=True)

Get the status of a file or a file descriptor. Perform the equivalent of a stat() system call on the given path. path may be specified as either a string or bytes -- directly or indirectly through the PathLike interface -- or as an open file descriptor. Return a stat_result object.

この関数は通常はシンボリックリンクをたどります。シンボリックリンクに対して stat したい場合は follow_symlinks=False とするか、 lstat() を利用してください。

この関数は ファイル記述子の指定 および シンボリックリンクをたどらない をサポートしています。

On Windows, passing 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 os.path.realpath() function to resolve the path name as far as possible and call lstat() on the result. This does not apply to dangling symlinks or junction points, which will raise the usual exceptions.

以下はプログラム例です:

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

参考

fstat() と lstat()。

バージョン 3.3 で変更: Added the dir_fd and follow_symlinks parameters, specifying a file descriptor instead of a path.

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

バージョン 3.8 で変更: On Windows, all reparse points that can be resolved by the operating system are now followed, and passing 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 follow_symlinks=False had been specified instead of raising an error.

class os.stat_result

Object whose attributes correspond roughly to the members of the stat structure. It is used for the result of os.stat(), os.fstat() and os.lstat().

属性:

st_mode

ファイルモード。ファイルタイプとファイルモードのビット （権限）。

st_ino

Platform dependent, but if non-zero, uniquely identifies the file for a given value of st_dev. Typically:

the inode number on Unix,

the file index [https://msdn.microsoft.com/en-us/library/aa363788] on Windows

st_dev

このファイルが存在するデバイスの識別子。

st_nlink

ハードリンクの数。

st_uid

ファイル所有者のユーザ識別子。

st_gid

ファイル所有者のグループ識別子。

st_size

ファイルが通常のファイルまたはシンボリックリンクの場合、そのファイルのバイト単位でのサイズです。シンボリックリンクのサイズは、含まれるパス名の長さで、null バイトで終わることはありません。

タイムスタンプ:

st_atime

秒で表した最終アクセス時刻。

st_mtime

秒で表した最終内容更新時刻。

st_ctime

Time of most recent metadata change expressed in seconds.

バージョン 3.12 で変更: st_ctime is deprecated on Windows. Use st_birthtime for the file creation time. In the future, st_ctime will contain the time of the most recent metadata change, as for other platforms.

st_atime_ns

ナノ秒 (整数) で表した最終アクセス時刻。

Added in version 3.3.

st_mtime_ns

ナノ秒 (整数) で表した最終内容更新時刻。

Added in version 3.3.

st_ctime_ns

Time of most recent metadata change expressed in nanoseconds as an integer.

Added in version 3.3.

バージョン 3.12 で変更: st_ctime_ns is deprecated on Windows. Use st_birthtime_ns for the file creation time. In the future, st_ctime will contain the time of the most recent metadata change, as for other platforms.

st_birthtime

Time of file creation expressed in seconds. This attribute is not always available, and may raise AttributeError.

バージョン 3.12 で変更: st_birthtime is now available on Windows.

st_birthtime_ns

Time of file creation expressed in nanoseconds as an integer. This attribute is not always available, and may raise AttributeError.

Added in version 3.12.

注釈

The exact meaning and resolution of the st_atime, st_mtime, st_ctime and st_birthtime attributes depend on the operating system and the file system. For example, on Windows systems using the FAT32 file systems, st_mtime has 2-second resolution, and st_atime has only 1-day resolution. See your operating system documentation for details.

Similarly, although st_atime_ns, st_mtime_ns, st_ctime_ns and 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 st_atime, st_mtime, st_ctime and st_birthtime cannot preserve all of it, and as such will be slightly inexact. If you need the exact timestamps you should always use st_atime_ns, st_mtime_ns, st_ctime_ns and st_birthtime_ns.

(Linux のような ) 一部の Unix システムでは、以下の属性が利用できる場合があります :

st_blocks

ファイルに対して割り当てられている 512 バイトのブロックの数です。ファイルにホール (hole) が含まれている場合、st_size/512 より小さくなる場合があります。

st_blksize

効率的なファイルシステム I/O のための「推奨される」ブロックサイズです。ファイルに、これより小さいチャンクで書き込むと、非効率的な読み込み、編集、再書き込みが起こる場合があります。

st_rdev

inode デバイスの場合デバイスタイプ

st_flags

ファイルのユーザ定義フラグ

他の (FreeBSD のような ) Unix システムでは、以下の属性が利用できる場合があります ( ただし root ユーザ以外が使うと値が入っていない場合があります ):

st_gen

ファイル生成番号

On Solaris and derivatives, the following attributes may also be available:

st_fstype

String that uniquely identifies the type of the filesystem that contains the file.

On macOS systems, the following attributes may also be available:

st_rsize

ファイルの実際のサイズ

st_creator

ファイルの作成者

st_type

ファイルタイプ

On Windows systems, the following attributes are also available:

st_file_attributes

Windows file attributes: dwFileAttributes member of the BY_HANDLE_FILE_INFORMATION structure returned by GetFileInformationByHandle(). See the FILE_ATTRIBUTE_* <stat.FILE_ATTRIBUTE_ARCHIVE> constants in the stat module.

Added in version 3.5.

st_reparse_tag

When st_file_attributes has the FILE_ATTRIBUTE_REPARSE_POINT set, this field contains the tag identifying the type of reparse point. See the IO_REPARSE_TAG_* constants in the stat module.

The standard module stat defines functions and constants that are useful for extracting information from a stat structure. (On Windows, some items are filled with dummy values.)

For backward compatibility, a stat_result instance is also accessible as a tuple of at least 10 integers giving the most important (and portable) members of the stat structure, in the order st_mode, st_ino, st_dev, st_nlink, st_uid, st_gid, st_size, st_atime, st_mtime, st_ctime. More items may be added at the end by some implementations. For compatibility with older Python versions, accessing stat_result as a tuple always returns integers.

バージョン 3.5 で変更: Windows now returns the file index as st_ino when available.

バージョン 3.7 で変更: Added the st_fstype member to Solaris/derivatives.

バージョン 3.8 で変更: Added the st_reparse_tag member on Windows.

バージョン 3.8 で変更: On Windows, the st_mode member now identifies special files as S_IFCHR, S_IFIFO or S_IFBLK as appropriate.

バージョン 3.12 で変更: On Windows, 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 st_birthtime for the creation time.

On Windows, 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, st_rdev no longer returns a value. Previously it would contain the same as st_dev, which was incorrect.

Added the st_birthtime member on Windows.

os.statvfs(path)

Perform a 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 statvfs structure, namely: f_bsize, f_frsize, f_blocks, f_bfree, f_bavail, f_files, f_ffree, f_favail, f_flag, f_namemax, f_fsid.

f_flag 属性のビットフラグ用に 2 つのモジュールレベル定数が定義されています: ST_RDONLY が設定されるとファイルシステムは読み出し専用でマウントされ、ST_NOSUID が設定されると setuid/setgid ビットの動作は無効になるか、サポートされません。

GNU/glibc ベースのシステム用に、追加のモジュールレベルの定数が次のように定義されています。 ST_NODEV (デバイス特殊ファイルへのアクセスを許可しない) 、 ST_NOEXEC (プログラムの実行を許可しない) 、 ST_SYNCHRONOUS (書き込みが一度に同期される) 、ST_MANDLOCK (ファイルシステムで強制的なロックを許可する) 、 ST_WRITE (ファイル/ディレクトリ/シンボリックリンクに書き込む) 、 ST_APPEND (追記のみのファイル) 、ST_IMMUTABLE (変更不能なファイル) 、 ST_NOATIME (アクセス時刻を更新しない) 、ST_NODIRATIME (ディレクトリアクセス時刻を更新しない) 、ST_RELATIME (mtime/ctimeに対して相対的に atime を更新する)。

この関数は ファイル記述子の指定 をサポートしています。

利用可能な環境: Unix。

バージョン 3.2 で変更: 定数 ST_RDONLY および ST_NOSUID が追加されました。

バージョン 3.3 で変更: path へのオープン・ファイル記述子の指定をサポートしました。

バージョン 3.4 で変更: ST_NODEV, ST_NOEXEC, ST_SYNCHRONOUS, ST_MANDLOCK, ST_WRITE, ST_APPEND, ST_IMMUTABLE, ST_NOATIME, ST_NODIRATIME, ST_RELATIME 定数が追加されました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

バージョン 3.7 で変更: Added the f_fsid attribute.

os.supports_dir_fd

A set object indicating which functions in the 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 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 in operator on supports_dir_fd. As an example, this expression evaluates to True if os.stat() accepts open file descriptors for dir_fd on the local platform:

os.stat in os.supports_dir_fd

現在 dir_fd 引数は Unix プラットフォームでのみ動作します。Windows で動作する関数はありません。

Added in version 3.3.

os.supports_effective_ids

A set object indicating whether os.access() permits specifying True for its effective_ids parameter on the local platform. (Specifying False for effective_ids is always supported on all platforms.) If the local platform supports it, the collection will contain os.access(); otherwise it will be empty.

This expression evaluates to True if os.access() supports effective_ids=True on the local platform:

os.access in os.supports_effective_ids

現在 effective_ids は Unix プラットフォームでのみサポートされています。Windows では動作しません。

Added in version 3.3.

os.supports_fd

A set object indicating which functions in the 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 in operator on supports_fd. As an example, this expression evaluates to True if os.chdir() accepts open file descriptors for path on your local platform:

os.chdir in os.supports_fd

Added in version 3.3.

os.supports_follow_symlinks

A set object indicating which functions in the os module accept 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 True for follow_symlinks is always supported on all platforms.)

To check whether a particular function accepts False for its follow_symlinks parameter, use the in operator on supports_follow_symlinks. As an example, this expression evaluates to True if you may specify follow_symlinks=False when calling os.stat() on the local platform:

os.stat in os.supports_follow_symlinks

Added in version 3.3.

os.symlink(src, dst, target_is_directory=False, *, dir_fd=None)

src を指し示すシンボリックリンク dst を作成します。

Windows では、シンボリックリンクはファイルかディレクトリのどちらかを表しますが、ターゲットに合わせて動的に変化することはありません。ターゲットが存在する場合、シンボリックリンクの種類は対象に合わせて作成されます。ターゲットが存在せず target_is_directory に True が設定された場合、シンボリックリンクはディレクトリのリンクとして作成され、False に設定された場合 (デフォルト) はファイルのリンクになります。Windows 以外のプラットフォームでは target_is_directory は無視されます。

この関数は ディレクトリ記述子への相対パス をサポートしています。

注釈

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.

この関数が特権を持たないユーザーに呼び出されると、OSError が送出されます。

引数 src, dst, dir_fd を指定して 監査イベント os.symlink を送出します。

Availability: Unix, Windows。

The function is limited on Emscripten and WASI, see WebAssemblyプラットフォーム for more information.

バージョン 3.2 で変更: Windows 6.0 (Vista) のシンボリックリンクをサポートしました。

バージョン 3.3 で変更: Added the dir_fd parameter, and now allow target_is_directory on non-Windows platforms.

バージョン 3.6 で変更: src と dst が path-like object を受け付けるようになりました。

バージョン 3.8 で変更: Added support for unelevated symlinks on Windows with Developer Mode.

os.sync()

ディスクキャッシュのディスクへの書き出しを強制します。

利用可能な環境: Unix。

Added in version 3.3.

os.truncate(path, length)

path に対応するファイルを、サイズが最大で length バイトになるよう切り詰めます。

この関数は ファイル記述子の指定 をサポートしています。

引数 path, length を指定して 監査イベント os.truncate を送出します。

Availability: Unix, Windows。

Added in version 3.3.

バージョン 3.5 で変更: Windows サポートを追加しました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.unlink(path, *, dir_fd=None)

ファイル path を削除します。意味上は remove() と等価です。 unlink の名前は伝統的な Unix の関数名です。詳細は remove() のドキュメントを参照してください。

引数 path, dir_fd を指定して 監査イベント os.remove を送出します。

バージョン 3.3 で変更: 引数 dir_fd を追加しました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.utime(path, times=None, *, [ns, ]dir_fd=None, follow_symlinks=True)

path で指定されたファイルに最終アクセス時刻および最終修正時刻を設定します。

utime() は 2 つの任意引数 times と ns をとります。これらは path に設定する時刻を指定し、以下のように使用されます:

ns を指定する場合、ナノ秒を表す整数値をメンバーとして使用して、 (atime_ns, mtime_ns) の形式の 2 要素タプルを指定する必要があります。

times が None ではない場合、(atime, mtime) の形式で各メンバーは単位を秒で表す整数か浮動小数点値のタプルを指定しなければなりません。

times が None で、 ns が指定されていない場合、これは両方の時間を現在時刻として ns=(atime_ns, mtime_ns) を指定することと等価です。

times と ns の両方にタプルが指定されるとエラーになります。

ここで設定した時刻が、後に stat() の呼び出し時正確に返されない場合があります。これはオペレーティングシステムが記録するアクセスおよび修正時刻の精度に依存しています; stat() を参照してください。正確な時刻を保持する最善の方法は、utime() で ns 引数を指定し、os.stat() の返り値オブジェクトから st_atime_ns および st_mtime_ns フィールドを使用することです。

この関数は ファイル記述子の指定 、 ディレクトリ記述子への相対パス 、および シンボリックリンクをたどらない をサポートしています。

引数 path, times, ns, dir_fd を指定して 監査イベント os.utime を送出します。

バージョン 3.3 で変更: path にオープンしているファイル記述子の指定のサポート、および引数 dir_fd, follow_symlinks, ns を追加しました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.walk(top, topdown=True, onerror=None, followlinks=False)

ディレクトリツリー以下のファイル名を、ツリーをトップダウンもしくはボトムアップに走査することで作成します。ディレクトリ top を根に持つディレクトリツリーに含まれる、各ディレクトリ (top 自身を含む ) ごとに、タプル (dirpath, dirnames, filenames) を yield します。

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 '.' and '..'). 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 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.

オプション引数 topdown が True であるか、指定されなかった場合、各ディレクトリからタプルを生成した後で、サブディレクトリからタプルを生成します。 ( ディレクトリはトップダウンで生成 ) 。 topdown が False の場合、ディレクトリに対応するタプルは、そのディレクトリ以下の全てのサブディレクトリに対応するタプルの後で ( ボトムアップで ) 生成されます。 topdown の値によらず、サブディレクトリのリストは、ディレクトリとそのサブディレクトリのタプルを生成する前に取り出されます。

topdown が True のとき、呼び出し側は dirnames リストを、インプレースで ( たとえば、 del やスライスを使った代入で ) 変更でき、 walk() は dirnames に残っているサブディレクトリ内のみを再帰します。これにより、検索を省略したり、特定の訪問順序を強制したり、呼び出し側が walk() を再開する前に、呼び出し側が作った、または名前を変更したディレクトリを、 walk() に知らせたりすることができます。 topdown が False のときに dirnames を変更しても効果はありません。ボトムアップモードでは dirpath 自身が生成される前に dirnames 内のディレクトリの情報が生成されるからです。

デフォルトでは、 scandir() 呼び出しからのエラーは無視されます。オプション引数の onerror を指定する場合は関数でなければなりません ; この関数は単一の引数として OSError インスタンスを伴って呼び出されます。この関数でエラーを報告して走査を継続したり、例外を送出して走査を中止したりできます。ファイル名は例外オブジェクトの filename 属性として利用できます。

デフォルトでは、 walk() はディレクトリへのシンボリックリンクをたどりません。 followlinks に True を指定すると、ディレクトリへのシンボリックリンクをサポートしているシステムでは、シンボリックリンクの指しているディレクトリを走査します。

注釈

followlinks に True を指定すると、シンボリックリンクが親ディレクトリを指していた場合に、無限ループになることに注意してください。 walk() はすでにたどったディレクトリを管理したりはしません。

注釈

相対パスを渡した場合、 walk() が再開されるまでの間に現在の作業ディレクトリを変更しないでください。 walk() はカレントディレクトリを変更しませんし、呼び出し側もカレントディレクトリを変更しないと仮定しています。

以下の例では、最初のディレクトリ以下にある各ディレクトリに含まれる、非ディレクトリファイルのバイト数を表示します。ただし、 CVS サブディレクトリ以下は見に行きません

import os
from os.path import join, getsize
for root, dirs, files in os.walk('python/Lib/email'):
    print(root, "consumes", end=" ")
    print(sum(getsize(join(root, name)) for name in files), end=" ")
    print("bytes in", len(files), "non-directory files")
    if 'CVS' in dirs:
        dirs.remove('CVS')  # don't visit CVS directories

次の例 (shutil.rmtree() の単純な実装) では、ツリーをボトムアップで走査することが不可欠になります; rmdir() はディレクトリが空になるまで削除を許さないからです:

# 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))

引数 top, topdown, onerror, followlinks を指定して 監査イベント os.walk を送出します。

バージョン 3.5 で変更: この関数は、今では os.listdir() ではなく os.scandir() を呼び出します。これにより、 os.stat() の呼び出し回数を削減でき、動作が高速化します。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.fwalk(top='.', topdown=True, onerror=None, *, follow_symlinks=False, dir_fd=None)

挙動は walk() と同じですが、dir_fd をサポートし、タプル (dirpath, dirnames, filenames, dirfd) を yield します。

dirpath、dirnames、および filenames は walk() の出力と同じで、dirfd は dirpath を参照するファイル記述子です。

この関数は常に ディレクトリ記述子への相対パス および シンボリックリンクをたどらない をサポートしています。ただし、他の関数と異なり、fwalk() での follow_symlinks のデフォルト値は False になることに注意してください。

注釈

fwalk() はファイル記述子を yield するため、それらが有効なのは次のイテレートステップまでです。それ以後も保持したい場合は dup() などを使って複製して使用してください。

以下の例では、最初のディレクトリ以下にある各ディレクトリに含まれる、非ディレクトリファイルのバイト数を表示します。ただし、 CVS サブディレクトリ以下は見に行きません

import os
for root, dirs, files, rootfd in os.fwalk('python/Lib/email'):
    print(root, "consumes", end="")
    print(sum([os.stat(name, dir_fd=rootfd).st_size for name in files]),
          end="")
    print("bytes in", len(files), "non-directory files")
    if 'CVS' in dirs:
        dirs.remove('CVS')  # don't visit CVS directories

次の例では、ツリーをボトムアップで走査することが不可欠になります ; rmdir() はディレクトリが空になるまで削除を許さないからです

# 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)

引数 top, topdown, onerror, follow_symlinks を指定して 監査イベント os.fwalk を送出します。

利用可能な環境: Unix。

Added in version 3.3.

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

バージョン 3.7 で変更: Added support for bytes paths.

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 os.MFD_* constants available on the system (or a bitwise ORed combination of them). By default, the new file descriptor is 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 /proc/self/fd/. The displayed name is always prefixed with 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.

Availability: Linux >= 3.17 with glibc >= 2.27.

Added in version 3.8.

os.MFD_CLOEXEC

os.MFD_ALLOW_SEALING

os.MFD_HUGETLB

os.MFD_HUGE_SHIFT

os.MFD_HUGE_MASK

os.MFD_HUGE_64KB

os.MFD_HUGE_512KB

os.MFD_HUGE_1MB

os.MFD_HUGE_2MB

os.MFD_HUGE_8MB

os.MFD_HUGE_16MB

os.MFD_HUGE_32MB

os.MFD_HUGE_256MB

os.MFD_HUGE_512MB

os.MFD_HUGE_1GB

os.MFD_HUGE_2GB

os.MFD_HUGE_16GB

These flags can be passed to memfd_create().

Availability: Linux >= 3.17 with glibc >= 2.27

The MFD_HUGE* flags are only available since Linux 4.14.

Added in version 3.8.

os.eventfd(initval[, flags=os.EFD_CLOEXEC])

Create and return an event file descriptor. The file descriptors supports raw read() and write() with a buffer size of 8, select(), poll() and similar. See man page eventfd(2) [https://manpages.debian.org/eventfd(2)] for more information. By default, the new file descriptor is non-inheritable.

initval is the initial value of the event counter. The initial value must be an 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⁶⁴-2.

flags can be constructed from EFD_CLOEXEC, EFD_NONBLOCK, and EFD_SEMAPHORE.

If EFD_SEMAPHORE is specified and the event counter is non-zero, eventfd_read() returns 1 and decrements the counter by one.

If EFD_SEMAPHORE is not specified and the event counter is non-zero, eventfd_read() returns the current event counter value and resets the counter to zero.

If the event counter is zero and EFD_NONBLOCK is not specified, eventfd_read() blocks.

eventfd_write() increments the event counter. Write blocks if the write operation would increment the counter to a value larger than 2⁶⁴-2.

以下はプログラム例です:

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)

Availability: Linux >= 2.6.27 with glibc >= 2.8

Added in version 3.10.

os.eventfd_read(fd)

Read value from an eventfd() file descriptor and return a 64 bit unsigned int. The function does not verify that fd is an eventfd().

Availability: Linux >= 2.6.27

Added in version 3.10.

os.eventfd_write(fd, value)

Add value to an eventfd() file descriptor. value must be a 64 bit unsigned int. The function does not verify that fd is an eventfd().

Availability: Linux >= 2.6.27

Added in version 3.10.

os.EFD_CLOEXEC

Set close-on-exec flag for new eventfd() file descriptor.

Availability: Linux >= 2.6.27

Added in version 3.10.

os.EFD_NONBLOCK

Set O_NONBLOCK status flag for new eventfd() file descriptor.

Availability: Linux >= 2.6.27

Added in version 3.10.

os.EFD_SEMAPHORE

Provide semaphore-like semantics for reads from a eventfd() file descriptor. On read the internal counter is decremented by one.

Availability: Linux >= 2.6.30

Added in version 3.10.

Linux 拡張属性

Added in version 3.3.

以下の関数はすべて Linux でのみ使用可能です。

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 PathLike interface). If it is str, it is encoded with the filesystem encoding.

この関数は ファイル記述子の指定 および シンボリックリンクをたどらない をサポートしています。

引数 path, attribute を指定して 監査イベント os.getxattr を送出します。

バージョン 3.6 で変更: path と attribute が path-like object を受け付けるようになりました。

os.listxattr(path=None, *, follow_symlinks=True)

path の拡張ファイルシステム属性のリストを返します。リスト内の属性はファイルシステムのエンコーディングでデコードされた文字列で表されます。path が None の場合、listxattr() はカレントディレクトリを調べます。

この関数は ファイル記述子の指定 および シンボリックリンクをたどらない をサポートしています。

引数 path を指定して 監査イベント os.listxattr を送出します。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

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 PathLike interface). If it is a string, it is encoded with the filesystem encoding and error handler.

この関数は ファイル記述子の指定 および シンボリックリンクをたどらない をサポートしています。

引数 path, attribute を指定して 監査イベント os.removexattr を送出します。

バージョン 3.6 で変更: path と attribute が path-like object を受け付けるようになりました。

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 PathLike interface). If it is a str, it is encoded with the filesystem encoding and error handler. flags may be XATTR_REPLACE or XATTR_CREATE. If XATTR_REPLACE is given and the attribute does not exist, ENODATA will be raised. If XATTR_CREATE is given and the attribute already exists, the attribute will not be created and EEXISTS will be raised.

この関数は ファイル記述子の指定 および シンボリックリンクをたどらない をサポートしています。

注釈

Linux カーネル 2.6.39 以前では、バグのため一部のファイルシステムで引数 flags が無視されます。

引数 path, attribute, value, flags を指定して 監査イベント os.setxattr を送出します。

バージョン 3.6 で変更: path と attribute が path-like object を受け付けるようになりました。

os.XATTR_SIZE_MAX

拡張属性の値にできる最大サイズです。現在、Linux では 64 キロバイトです。

os.XATTR_CREATE

setxattr() の引数 flags に指定できる値です。その操作で属性を作成しなければならないことを意味します。

os.XATTR_REPLACE

setxattr() の引数 flags に指定できる値です。その操作で既存の属性を置き換えなければならないことを意味します。

プロセス管理

以下の関数はプロセスの生成や管理に利用できます。

さまざまな exec* 関数は、プロセス内にロードされる新しいプログラムに与えるための、引数のリストを取ります。どの関数の場合でも、新しいプログラムに渡されるリストの最初の引数は、ユーザがコマンドラインで入力する引数ではなく、そのプログラム自体の名前です。 C プログラマならば、プログラムの main() に渡される argv[0] だと考えれば良いでしょう。たとえば、 os.execv('/bin/echo', ['foo', 'bar']) が標準出力に出力するのは bar だけで、 foo は無視されたかのように見えることになります。

os.abort()

SIGABRT シグナルを現在のプロセスに対して生成します。 Unix では、デフォルトの動作はコアダンプの生成です ; Windows では、プロセスは即座に終了コード 3 を返します。この関数の呼び出しは signal.signal() を使って SIGABRT に対し登録された Python シグナルハンドラーを呼び出さないことに注意してください。

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 sys.path), and also by ctypes.

Remove the directory by calling close() on the returned object or using it in a with statement.

See the Microsoft documentation [https://msdn.microsoft.com/44228cf2-6306-466c-8f16-f513cd3ba8b5] for more information about how DLLs are loaded.

引数 path を指定して 監査イベント os.add_dll_directory を送出します。

利用可能な環境: Windows 。

Added in version 3.8: Previous versions of CPython would resolve DLLs using the default behavior for the current process. This led to inconsistencies, such as only sometimes searching PATH or the current working directory, and OS functions such as 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 porting notes for information on updating libraries.

os.execl(path, arg0, arg1, ...)

os.execle(path, arg0, arg1, ..., env)

os.execlp(file, arg0, arg1, ...)

os.execlpe(file, arg0, arg1, ..., env)

os.execv(path, args)

os.execve(path, args, env)

os.execvp(file, args)

os.execvpe(file, args, env)

これらの関数はすべて、現在のプロセスを置き換える形で新たなプログラムを実行します ; 現在のプロセスは返り値を返しません。 Unix では、新たに実行される実行コードは現在のプロセス内に読み込まれ、呼び出し側と同じプロセス ID を持つことになります。エラーは OSError 例外として報告されます。

現在のプロセスは瞬時に置き換えられます。開かれているファイルオブジェクトやファイル記述子はフラッシュされません。そのため、バッファ内にデータが残っているかもしれない場合、 exec* 関数を実行する前に sys.stdout.flush() か os.fsync() を利用してバッファをフラッシュしておく必要があります。

The "l" and "v" variants of the 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 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 (execlp(), execlpe(), execvp(), and execvpe()) will use the PATH environment variable to locate the program file. When the environment is being replaced (using one of the exec*e variants, discussed in the next paragraph), the new environment is used as the source of the PATH variable. The other variants, execl(), execle(), execv(), and execve(), will not use the 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.

execle() 、 execlpe() 、 execve() 、および execvpe() (すべて末尾に "e" がついています) では、 env 引数は新たなプロセスで利用される環境変数を定義するためのマップ型でなくてはなりません ( 現在のプロセスの環境変数の代わりに利用されます ); execl() 、 execlp() 、 execv() 、および execvp() では、すべて新たなプロセスは現在のプロセスの環境を引き継ぎます。

一部のプラットフォームの execve() では、path はオープンしているファイル記述子で指定することもできます。この機能をサポートしていないプラットフォームもあります; os.supports_fd を使うことで利用可能かどうか調べることができます。利用できない場合、NotImplementedError が送出されます。

引数 path, args, env を指定して 監査イベント os.exec を送出します。

Availability: Unix, Windows, not Emscripten, not WASI.

バージョン 3.3 で変更: Added support for specifying path as an open file descriptor for execve().

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os._exit(n)

終了ステータス n でプロセスを終了します。この時クリーンアップハンドラーの呼び出しや、標準入出力バッファのフラッシュなどは行いません。

注釈

The standard way to exit is sys.exit(n). _exit() should normally only be used in the child process after a fork().

以下の終了コードは必須ではありませんが _exit() で使うことができます。一般に、メールサーバーの外部コマンド配送プログラムのような、 Python で書かれたシステムプログラムに使います。

注釈

いくつかのバリエーションがあって、これらのすべてがすべての Unix プラットフォームで使えるわけではありません。以下の定数は下層のプラットフォームで定義されていれば定義されます。

os.EX_OK

Exit code that means no error occurred. May be taken from the defined value of EXIT_SUCCESS on some platforms. Generally has a value of zero.

Availability: Unix, Windows。

os.EX_USAGE

誤った個数の引数が渡された時など、コマンドが間違って使われたことを表す終了コード。

Availability: Unix, not Emscripten, not WASI.

os.EX_DATAERR

入力データが誤っていたことを表す終了コード。

Availability: Unix, not Emscripten, not WASI.

os.EX_NOINPUT

入力ファイルが存在しなかった、または、読み込み不可だったことを表す終了コード。

Availability: Unix, not Emscripten, not WASI.

os.EX_NOUSER

指定されたユーザーが存在しなかったことを表す終了コード。

Availability: Unix, not Emscripten, not WASI.

os.EX_NOHOST

指定されたホストが存在しなかったことを表す終了コード。

Availability: Unix, not Emscripten, not WASI.

os.EX_UNAVAILABLE

要求されたサービスが利用できないことを表す終了コード。

Availability: Unix, not Emscripten, not WASI.

os.EX_SOFTWARE

内部ソフトウェアエラーが検出されたことを表す終了コード。

Availability: Unix, not Emscripten, not WASI.

os.EX_OSERR

fork できない、 pipe の作成ができないなど、オペレーティングシステムのエラーが検出されたことを表す終了コード。

Availability: Unix, not Emscripten, not WASI.

os.EX_OSFILE

システムファイルが存在しなかった、開けなかった、あるいはその他のエラーが起きたことを表す終了コード。

Availability: Unix, not Emscripten, not WASI.

os.EX_CANTCREAT

ユーザーには作成できない出力ファイルを指定したことを表す終了コード。

Availability: Unix, not Emscripten, not WASI.

os.EX_IOERR

ファイルの I/O を行っている途中にエラーが発生した時の終了コード。

Availability: Unix, not Emscripten, not WASI.

os.EX_TEMPFAIL

一時的な失敗が発生したことを表す終了コード。これは、再試行可能な操作の途中に、ネットワークに接続できないというような、実際にはエラーではないかも知れないことを意味します。

Availability: Unix, not Emscripten, not WASI.

os.EX_PROTOCOL

プロトコル交換が不正、不適切、または理解不能なことを表す終了コード。

Availability: Unix, not Emscripten, not WASI.

os.EX_NOPERM

操作を行うために十分な許可がなかった（ファイルシステムの問題を除く）ことを表す終了コード。

Availability: Unix, not Emscripten, not WASI.

os.EX_CONFIG

設定エラーが起こったことを表す終了コード。

Availability: Unix, not Emscripten, not WASI.

os.EX_NOTFOUND

"an entry was not found" のようなことを表す終了コード。

Availability: Unix, not Emscripten, not WASI.

os.fork()

子プロセスを fork します。子プロセスでは 0 が返り、親プロセスでは子プロセスの id が返ります。エラーが発生した場合は、 OSError を送出します。

FreeBSD 6.3 以下、Cygwinを含む一部のプラットフォームにおいて、 fork() をスレッド内から利用した場合に既知の問題があることに注意してください。

引数無しで 監査イベント os.fork を送出します。

警告

If you use TLS sockets in an application calling fork(), see the warning in the ssl documentation.

警告

On macOS the use of this function is unsafe when mixed with using higher-level system APIs, and that includes using urllib.request.

バージョン 3.8 で変更: Calling fork() in a subinterpreter is no longer supported (RuntimeError is raised).

バージョン 3.12 で変更: If Python is able to detect that your process has multiple threads, os.fork() now raises a 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 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 malloc and 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 [https://discuss.python.org/t/33555] for technical details of why we're surfacing this longstanding platform compatibility problem to developers.

Availability: POSIX, not Emscripten, not WASI.

os.forkpty()

子プロセスを fork します。この時新しい擬似端末を子プロセスの制御端末として使います。親プロセスでは (pid, fd) からなるペアが返り、 fd は擬似端末のマスター側のファイル記述子となります。可搬性のあるアプローチを取るには、 pty モジュールを利用してください。エラーが発生した場合は、 OSError を送出します。

引数無しで 監査イベント os.forkpty を送出します。

警告

On macOS the use of this function is unsafe when mixed with using higher-level system APIs, and that includes using urllib.request.

バージョン 3.8 で変更: Calling forkpty() in a subinterpreter is no longer supported (RuntimeError is raised).

バージョン 3.12 で変更: If Python is able to detect that your process has multiple threads, this now raises a DeprecationWarning. See the longer explanation on os.fork().

Availability: Unix, not Emscripten, not WASI.

os.kill(pid, sig, /)

プロセス pid にシグナル sig を送ります。ホストプラットフォームで利用可能なシグナルを特定する定数は signal モジュールで定義されています。

Windows: The signal.CTRL_C_EVENT and 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. The Windows version of kill() additionally takes process handles to be killed.

signal.pthread_kill() も参照してください。

引数 pid, sig を指定して 監査イベント os.kill を送出します。

Availability: Unix, Windows, not Emscripten, not WASI.

バージョン 3.2 で変更: Windows サポートを追加しました。

os.killpg(pgid, sig, /)

プロセスグループ pgid にシグナル sig を送ります。

引数 pgid, sig を指定して 監査イベント os.killpg を送出します。

Availability: Unix, not Emscripten, not WASI.

os.nice(increment, /)

プロセスの "nice 値 " に increment を加えます。新たな nice 値を返します。

Availability: Unix, not Emscripten, not WASI.

os.pidfd_open(pid, flags=0)

Return a file descriptor referring to the process pid with flags set. This descriptor can be used to perform process management without races and signals.

See the pidfd_open(2) [https://manpages.debian.org/pidfd_open(2)] man page for more details.

Availability: Linux >= 5.3

Added in version 3.9.

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 waitid(2) [https://manpages.debian.org/waitid(2)] will immediately return the error EAGAIN rather than blocking.

Availability: Linux >= 5.10

Added in version 3.12.

os.plock(op, /)

プログラムのセグメントをメモリ内にロックします。 op (<sys/lock.h> で定義されています ) にはどのセグメントをロックするかを指定します。

Availability: Unix, not Emscripten, not WASI.

os.popen(cmd, mode='r', buffering=-1)

コマンド cmd への、または cmd からのパイプ入出力を開きます。戻り値はパイプに接続されている開かれたファイルオブジェクトで、 mode が 'r' (デフォルト) または 'w' かによって読み出しまたは書き込みを行うことができます。引数 bufsize は、組み込み関数 open() における対応する引数と同じ意味を持ちます。 返されるファイルオブジェクトは、バイトではなくテキスト文字列を読み書きします。

close メソッドは、サブプロセスが正常に終了した場合は None を返し、エラーが発生した場合にはサブプロセスの返りコードを返します。POSIX システムでは、返りコードが正の場合、そのコードは1バイト左にシフトしてプロセスが終了したことを示します。返りコードが負の場合、プロセスは返りコードの符号を変えた信号により終了します 。 (例えば、サブプロセスが kill された場合、返り値は - signal.SIGKILL となる場合があります。) Windows システムでは、返り値には子プロセスからの符号のついた整数の返りコードを含まれます。

On Unix, waitstatus_to_exitcode() can be used to convert the close method result (exit status) into an exit code if it is not None. On Windows, the close method result is directly the exit code (or None).

これは、subprocess.Popen を使用して実装されています。サブプロセスを管理し、サブプロセスと通信を行うためのより強力な方法については、クラスのドキュメンテーションを参照してください。

Availability: not Emscripten, not WASI.

注釈

The Python UTF-8 Mode affects encodings used for cmd and pipe contents.

popen() is a simple wrapper around subprocess.Popen. Use subprocess.Popen or subprocess.run() to control options like encodings.

os.posix_spawn(path, argv, env, *, file_actions=None, setpgroup=None, resetids=False, setsid=False, setsigmask=(), setsigdef=(), scheduler=None)

Wraps the posix_spawn() C library API for use from Python.

大部分のユーザーは posix_spawn() ではなく、 func:subprocess.run を使うべきです。

The positional-only arguments path, args, and env are similar to execve().

path には実行ファイルへのパスを指定します。 path はディレクトリを含む形（実行ファイルへの絶対パスまたは相対パス）で指定する必要があります。実行ファイル名のみを指定したい場合は posix_spawnp() を使ってください。

file_actions 引数はCライブラリ実装の fork() と exec() の間で子プロセスが持つファイルデスクリプタに対して行うアクションを記述するタプルのシーケンスです。各タプルの最初の要素は、残りのタプル要素の解釈方法を指定する以下の3つの型指定子のうちのひとつでなければなりません。

os.POSIX_SPAWN_OPEN

(os.POSIX_SPAWN_OPEN, fd, path, flags, mode)

os.dup2(os.open(path, flags, mode), fd) を実行します。

os.POSIX_SPAWN_CLOSE

(os.POSIX_SPAWN_CLOSE, fd)

os.close(fd) を実行します。

os.POSIX_SPAWN_DUP2

(os.POSIX_SPAWN_DUP2, fd, new_fd)

os.dup2(fd, new_fd) を実行します。

These tuples correspond to the C library posix_spawn_file_actions_addopen(), posix_spawn_file_actions_addclose(), and posix_spawn_file_actions_adddup2() API calls used to prepare for the 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 POSIX_SPAWN_SETPGROUP flag.

If the resetids argument is 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 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 POSIX_SPAWN_RESETIDS flag.

If the setsid argument is True, it will create a new session ID for posix_spawn. setsid requires POSIX_SPAWN_SETSID or POSIX_SPAWN_SETSID_NP flag. Otherwise, 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 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 POSIX_SPAWN_SETSIGDEF flag.

The scheduler argument must be a tuple containing the (optional) scheduler policy and an instance of sched_param with the scheduler parameters. A value of None in the place of the scheduler policy indicates that is not being provided. This argument is a combination of the C library POSIX_SPAWN_SETSCHEDPARAM and POSIX_SPAWN_SETSCHEDULER flags.

引数 path, argv, env を指定して 監査イベント os.posix_spawn を送出します。

Added in version 3.8.

Availability: Unix, not Emscripten, not WASI.

os.posix_spawnp(path, argv, env, *, file_actions=None, setpgroup=None, resetids=False, setsid=False, setsigmask=(), setsigdef=(), scheduler=None)

Wraps the posix_spawnp() C library API for use from Python.

Similar to posix_spawn() except that the system searches for the executable file in the list of directories specified by the PATH environment variable (in the same way as for execvp(3)).

引数 path, argv, env を指定して 監査イベント os.posix_spawn を送出します。

Added in version 3.8.

Availability: POSIX, not Emscripten, not WASI.

See posix_spawn() documentation.

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 os.fork() or similar process cloning APIs. The parameters are optional and keyword-only. Each specifies a different call point.

before is a function called before forking a child process.

after_in_parent is a function called from the parent process after forking a child process.

after_in_child is a function called from the child process.

These calls are only made if control is expected to return to the Python interpreter. A typical 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 fork() calls made by third-party C code may not call those functions, unless it explicitly calls PyOS_BeforeFork(), PyOS_AfterFork_Parent() and PyOS_AfterFork_Child().

There is no way to unregister a function.

Availability: Unix, not Emscripten, not WASI.

Added in version 3.7.

os.spawnl(mode, path, ...)

os.spawnle(mode, path, ..., env)

os.spawnlp(mode, file, ...)

os.spawnlpe(mode, file, ..., env)

os.spawnv(mode, path, args)

os.spawnve(mode, path, args, env)

os.spawnvp(mode, file, args)

os.spawnvpe(mode, file, args, env)

新たなプロセス内でプログラム path を実行します。

(subprocess モジュールが、新しいプロセスを実行して結果を取得するための、より強力な機能を提供しています。この関数の代わりに subprocess モジュールを利用することが推奨されています。 subprocess モジュールのドキュメントの、 古い関数を subprocess モジュールで置き換える セクションを参照してください )

mode が P_NOWAIT の場合、この関数は新たなプロセスのプロセス ID を返します ; mode が P_WAIT の場合、子プロセスが正常に終了するとその終了コードが返ります。そうでない場合にはプロセスを kill したシグナル signal に対して -signal が返ります。 Windows では、プロセス ID は実際にはプロセスハンドル値になるので、 waitpid() 関数で使えます。

Note on VxWorks, this function doesn't return -signal when the new process is killed. Instead it raises OSError exception.

The "l" and "v" variants of the 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 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.

末尾近くに "p" をもつ型 (spawnlp(), spawnlpe(), spawnvp(), spawnvpe()) は、プログラム file を探すために環境変数 PATH を利用します。環境変数が ( 次の段で述べる spawn*e 型関数で ) 置き換えられる場合、環境変数は PATH を決定する上の情報源として使われます。その他の型、 spawnl(), spawnle(), spawnv(), および spawnve() では、実行コードを探すために PATH を使いません。 path には適切に設定された絶対パスまたは相対パスが入っていなくてはなりません。

spawnle(), spawnlpe(), spawnve(), および spawnvpe() (すべて末尾に "e" がついています) では、 env 引数は新たなプロセスで利用される環境変数を定義するためのマップ型でなくてはなりません ; spawnl() 、 spawnlp() 、 spawnv() 、および spawnvp() では、すべて新たなプロセスは現在のプロセスの環境を引き継ぎます。 env 辞書のキーと値はすべて文字列である必要があります。不正なキーや値を与えると関数が失敗し、 127 を返します。

例えば、以下の spawnlp() および spawnvpe() 呼び出しは等価です

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)

引数 mode, path, args, env を指定して 監査イベント os.spawn を送出します。

Availability: Unix, Windows, not Emscripten, not WASI.

spawnlp() 、 spawnlpe() 、 spawnvp() 、および spawnvpe() は Windows では利用できません。 spawnle() および spawnve() は Windows においてスレッドセーフではありません ; 代わりに subprocess モジュールの利用を推奨します。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.P_NOWAIT

os.P_NOWAITO

Possible values for the mode parameter to the spawn* family of functions. If either of these values is given, the spawn* functions will return as soon as the new process has been created, with the process id as the return value.

Availability: Unix, Windows。

os.P_WAIT

Possible value for the mode parameter to the spawn* family of functions. If this is given as mode, the 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 -signal if a signal kills the process.

Availability: Unix, Windows。

os.P_DETACH

os.P_OVERLAY

spawn* 関数ファミリに対する mode パラメタとして取れる値です。これらの値は上の値よりもやや可搬性において劣っています。 P_DETACH は P_NOWAIT に似ていますが、新たなプロセスは呼び出しプロセスのコンソールから切り離され (detach) ます。 P_OVERLAY が使われた場合、現在のプロセスは置き換えられます。したがって spawn* は返りません。

利用可能な環境: Windows 。

os.startfile(path[, operation][, arguments][, cwd][, show_cmd])

ファイルを関連付けられたアプリケーションを使ってスタートします。

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 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 'open', 'print' and 'edit' (to be used on files) as well as 'explore' and '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 ShellExecute() function.

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 ('/') Use pathlib or the os.path.normpath() function to ensure that paths are properly encoded for Win32.

To reduce interpreter startup overhead, the Win32 ShellExecute() function is not resolved until this function is first called. If the function cannot be resolved, NotImplementedError will be raised.

引数 path, operation を指定して 監査イベント os.startfile を送出します。

Raises an auditing event os.startfile/2 with arguments path, operation, arguments, cwd, show_cmd.

利用可能な環境: Windows 。

バージョン 3.10 で変更: Added the arguments, cwd and show_cmd arguments, and the os.startfile/2 audit event.

os.system(command)

Execute the command (a string) in a subshell. This is implemented by calling the Standard C function system(), and has the same limitations. Changes to 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 wait().

Windows では、返り値は command を実行した後にシステムシェルから返される値です。シェルは通常 cmd.exe であり、返す値は実行したコマンドの終了ステータスになります。シェルの種類は Windows の環境変数 COMSPEC: に指定されています。ネイティブでないシェルを使用している場合は、そのドキュメントを参照してください。

subprocess モジュールは、新しいプロセスを実行して結果を取得するためのより強力な機能を提供しています。この関数の代わりに subprocess モジュールを利用することが推奨されています。 subprocess モジュールのドキュメントの 古い関数を subprocess モジュールで置き換える 節のレシピを参考にして下さい。

On Unix, 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.

引数 command を指定して 監査イベント os.system を送出します。

Availability: Unix, Windows, not Emscripten, not WASI.

os.times()

現在の全体的なプロセス時間を返します。返り値は 5 個の属性を持つオブジェクトになります:

user - user time

system - system time

children_user - user time of all child processes

children_system - system time of all child processes

elapsed - elapsed real time since a fixed point in the past

後方互換性のため、このオブジェクトは 5 個のアイテム user 、 system 、 children_user 、 children_system 、および elapsed を持つタプルのようにも振る舞います。

See the Unix manual page times(2) [https://manpages.debian.org/times(2)] and times(3) [https://man.freebsd.org/cgi/man.cgi?time(3)] manual page on Unix or the GetProcessTimes MSDN [https://docs.microsoft.com/windows/win32/api/processthreadsapi/nf-processthreadsapi-getprocesstimes] on Windows. On Windows, only user and system are known; the other attributes are zero.

Availability: Unix, Windows。

バージョン 3.3 で変更: 返り値の型が、タプルから属性名のついたタプルライクオブジェクトに変更されました。

os.wait()

子プロセスの実行完了を待機し、子プロセスの pid と終了コードインジケーター --- 16 ビットの数値で、下位バイトがプロセスを kill したシグナル番号、上位バイトが終了ステータス ( シグナル番号がゼロの場合 ) --- の入ったタプルを返します ; コアダンプファイルが生成された場合、下位バイトの最上桁ビットが立てられます。

If there are no children that could be waited for, ChildProcessError is raised.

戻り値の終了ステータスを終了コードに変換するために waitstatus_to_exitcode() を使うことができます。

Availability: Unix, not Emscripten, not WASI.

参考

The other wait*() functions documented below can be used to wait for the completion of a specific child process and have more options. waitpid() is the only one also available on Windows.

os.waitid(idtype, id, options, /)

Wait for the completion of a child process.

idtype can be P_PID, P_PGID, P_ALL, or (on Linux) P_PIDFD. The interpretation of id depends on it; see their individual descriptions.

options is an OR combination of flags. At least one of WEXITED, WSTOPPED or WCONTINUED is required; WNOHANG and WNOWAIT are additional optional flags.

The return value is an object representing the data contained in the siginfo_t structure with the following attributes:

si_pid (process ID)

si_uid (real user ID of the child)

si_signo (always SIGCHLD)

si_status (the exit status or signal number, depending on si_code)

si_code (see CLD_EXITED for possible values)

If WNOHANG is specified and there are no matching children in the requested state, None is returned. Otherwise, if there are no matching children that could be waited for, ChildProcessError is raised.

Availability: Unix, not Emscripten, not WASI.

注釈

This function is not available on macOS.

Added in version 3.3.

os.waitpid(pid, options, /)

この関数の詳細は Unix と Windows で異なります。

Unix の場合 : プロセス id pid で与えられた子プロセスの完了を待機し、子プロセスのプロセス id と (wait() と同様にコード化された ) 終了ステータスインジケーターからなるタプルを返します。この関数の動作は options によって変わります。通常の操作では 0 にします。

pid が 0 よりも大きい場合、 waitpid() は特定のプロセスのステータス情報を要求します。 pid が 0 の場合、現在のプロセスグループ内の任意の子プロセスの状態に対する要求です。 pid が -1 の場合、現在のプロセスの任意の子プロセスに対する要求です。 pid が -1 よりも小さい場合、プロセスグループ -pid ( すなわち pid の絶対値 ) 内の任意のプロセスに対する要求です。

options is an OR combination of flags. If it contains WNOHANG and there are no matching children in the requested state, (0, 0) is returned. Otherwise, if there are no matching children that could be waited for, ChildProcessError is raised. Other options that can be used are WUNTRACED and WCONTINUED.

Windows では、プロセスハンドル pid を指定してプロセスの終了を待って、 pid と、終了ステータスを 8bit 左シフトした値のタプルを返します。 ( シフトは、この関数をクロスプラットフォームで利用しやすくするために行われます ) 0 以下の pid は Windows では特別な意味を持っておらず、例外を発生させます。 options の値は効果がありません。 pid は、子プロセスで無くても、プロセス ID を知っているどんなプロセスでも参照することが可能です。 spawn* 関数を P_NOWAIT と共に呼び出した場合、適切なプロセスハンドルが返されます。

戻り値の終了ステータスを終了コードに変換するために waitstatus_to_exitcode() を使うことができます。

Availability: Unix, Windows, not Emscripten, not WASI.

バージョン 3.5 で変更: システムコールが中断されシグナルハンドラが例外を送出しなかった場合、この関数は InterruptedError 例外を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 [https://peps.python.org/pep-0475/] を参照してください)。

os.wait3(options)

waitpid() に似ていますが、プロセス id を引数に取らず、子プロセス id 、終了ステータスインジケータ、リソース使用情報の 3 要素からなるタプルを返します。リソース使用情報の詳しい情報は resource.getrusage() を参照してください。options 引数は waitpid() および wait4() に渡されるものと同じです。

戻り値の終了ステータスを終了コードに変換するために waitstatus_to_exitcode() を使うことができます。

Availability: Unix, not Emscripten, not WASI.

os.wait4(pid, options)

waitpid() に似ていますが、子プロセス id 、終了ステータスインジケータ、リソース使用情報の 3 要素からなるタプルを返します。リソース使用情報の詳しい情報は resource.getrusage() を参照してください。 wait4() の引数は waitpid() に与えられるものと同じです。

戻り値の終了ステータスを終了コードに変換するために waitstatus_to_exitcode() を使うことができます。

Availability: Unix, not Emscripten, not WASI.

os.P_PID

os.P_PGID

os.P_ALL

os.P_PIDFD

waitid() の idtype に指定できる値です。これらは id がどう解釈されるかに影響します:

P_PID - wait for the child whose PID is id.

P_PGID - wait for any child whose progress group ID is id.

P_ALL - wait for any child; id is ignored.

P_PIDFD - wait for the child identified by the file descriptor id (a process file descriptor created with pidfd_open()).

Availability: Unix, not Emscripten, not WASI.

注釈

P_PIDFD is only available on Linux >= 5.4.

Added in version 3.3.

Added in version 3.9: The P_PIDFD constant.

os.WCONTINUED

This options flag for waitpid(), wait3(), wait4(), and waitid() causes child processes to be reported if they have been continued from a job control stop since they were last reported.

Availability: Unix, not Emscripten, not WASI.

os.WEXITED

This options flag for waitid() causes child processes that have terminated to be reported.

The other wait* functions always report children that have terminated, so this option is not available for them.

Availability: Unix, not Emscripten, not WASI.

Added in version 3.3.

os.WSTOPPED

This options flag for 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 wait* functions.

Availability: Unix, not Emscripten, not WASI.

Added in version 3.3.

os.WUNTRACED

This options flag for waitpid(), wait3(), and 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 waitid().

Availability: Unix, not Emscripten, not WASI.

os.WNOHANG

This options flag causes waitpid(), wait3(), wait4(), and waitid() to return right away if no child process status is available immediately.

Availability: Unix, not Emscripten, not WASI.

os.WNOWAIT

This options flag causes waitid() to leave the child in a waitable state, so that a later wait*() call can be used to retrieve the child status information again.

This option is not available for the other wait* functions.

Availability: Unix, not Emscripten, not WASI.

os.CLD_EXITED

os.CLD_KILLED

os.CLD_DUMPED

os.CLD_TRAPPED

os.CLD_STOPPED

os.CLD_CONTINUED

waitid() の返り値の si_code に設定され得る値です。

Availability: Unix, not Emscripten, not WASI.

Added in version 3.3.

バージョン 3.9 で変更: CLD_KILLED と CLD_STOPPED が追加されました。

os.waitstatus_to_exitcode(status)

待機ステータスを終了コードに変換します。

Unix の場合:

子プロセスが正常終了した場合 (WIFEXITED(status)``が真の場合)、子プロセスの終了ステータス (``WEXITSTATUS(status)) を返します: 戻り値は0または正の整数です。

子プロセスがシグナルによって終了した場合 (WIFSIGNALED(status)``が真の場合)、子プロセスを終了したシグナルの番号に負符号をつけた ``-signum (-WTERMSIG(status)) を返します: 戻り値は負の整数です。

それ以外の場合、 ValueError 例外を送出します。

Windows の場合、 status を8ビット右にシフトした値を返します。

Unix の場合、プロセスがトレースされているか waitpid() が WUNTRACED オプションをつけて実行されている場合、呼び出しもとは最初に WIFSTOPPED(status) が真であるかを確認しなければなりません。この関数は WIFSTOPPED(status) が真の場合呼び出してはいけません。

参考

WIFEXITED(), WEXITSTATUS(), WIFSIGNALED(), WTERMSIG(), WIFSTOPPED(), WSTOPSIG() 関数。

Availability: Unix, Windows, not Emscripten, not WASI.

Added in version 3.9.

以下の関数は system() 、 wait() 、あるいは waitpid() が返すプロセス状態コードを引数にとります。これらの関数はプロセスの配置を決めるために利用できます。

os.WCOREDUMP(status, /)

プロセスに対してコアダンプが生成されていた場合には True を、それ以外の場合は False を返します。

この関数は WIFSIGNALED() が真である場合のみ使用されるべきです。

Availability: Unix, not Emscripten, not WASI.

os.WIFCONTINUED(status)

Return True if a stopped child has been resumed by delivery of SIGCONT (if the process has been continued from a job control stop), otherwise return False.

WCONTINUED オプションを参照してください。

Availability: Unix, not Emscripten, not WASI.

os.WIFSTOPPED(status)

プロセスがシグナルの送信によって中断させられた場合に True を返します。それ以外の場合は False を返します。

WIFSTOPPED() は waitpid() が WUNTRACED オプションを使って実行されたか、もしくはプロセスがトレースされている場合 (ptrace(2) [https://manpages.debian.org/ptrace(2)] を参照してください) にのみ True を返します。

Availability: Unix, not Emscripten, not WASI.

os.WIFSIGNALED(status)

プロセスがシグナルによって終了させられた場合に True を返します。そうでない場合は False を返します。

Availability: Unix, not Emscripten, not WASI.

os.WIFEXITED(status)

プロセスが正常終了した場合、すなわち exit() や _exit() を呼び出したか、もしくは main() から戻ることにより終了した場合に True を返します。それ以外は False を返します。

Availability: Unix, not Emscripten, not WASI.

os.WEXITSTATUS(status)

プロセスの終了ステータスを返します。

この関数は WIFEXITED() が真である場合のみ使用されるべきです。

Availability: Unix, not Emscripten, not WASI.

os.WSTOPSIG(status)

プロセスを停止させたシグナル番号を返します。

この関数は WIFSTOPPED() が真である場合のみ使用されるべきです。

Availability: Unix, not Emscripten, not WASI.

os.WTERMSIG(status)

プロセスを終了させたシグナルの番号を返します。

この関数は WIFSIGNALED() が真である場合のみ使用されるべきです。

Availability: Unix, not Emscripten, not WASI.

スケジューラーへのインターフェイス

以下の関数は、オペレーティングシステムがプロセスに CPU 時間を割り当てる方法を制御します。これらは一部の Unix プラットフォームでのみ利用可能です。詳しくは Unix マニュアルページを参照してください。

Added in version 3.3.

次のスケジューリングポリシーは、オペレーティングシステムでサポートされていれば公開されます。

os.SCHED_OTHER

デフォルトのスケジューリングポリシーです。

os.SCHED_BATCH

常にCPUに負荷のかかる (CPU-intensive) プロセス用のポリシーです。他の対話式プロセスなどの応答性を維持するよう試みます。

os.SCHED_IDLE

非常に優先度の低いバックグラウンドタスク用のスケジューリングポリシーです。

os.SCHED_SPORADIC

散発的なサーバープログラム用のスケジューリングポリシーです。

os.SCHED_FIFO

FIFO (First In, First Out) 型のスケジューリングポリシーです。

os.SCHED_RR

ラウンドロビン型のスケジューリングポリシーです。

os.SCHED_RESET_ON_FORK

このフラグは他のスケジューリングポリシーとともに論理和指定できます。このフラグが与えられたプロセスが fork されると、その子プロセスのスケジューリングポリシーおよび優先度はデフォルトにリセットされます。

class os.sched_param(sched_priority)

このクラスは、sched_setparam()、sched_setscheduler()、および sched_getparam() で使用される、調節可能なスケジューリングパラメーターを表します。これはイミュータブルです。

現在、一つの引数のみ指定できます:

sched_priority

スケジューリングポリシーのスケジューリング優先度です。

os.sched_get_priority_min(policy)

policy の最小優先度値を取得します。policy には上記のスケジューリングポリシー定数の一つを指定します。

os.sched_get_priority_max(policy)

policy の最大優先度値を取得します。policy には上記のスケジューリングポリシー定数の一つを指定します。

os.sched_setscheduler(pid, policy, param, /)

PID pid のプロセスのスケジューリングポリシーを設定します。pid が 0 の場合、呼び出しプロセスを意味します。policy には上記のスケジューリングポリシー定数の一つを指定します。param は sched_param のインスタンスです。

os.sched_getscheduler(pid, /)

PID pid のプロセスのスケジューリングポリシーを返します。pid が 0 の場合、呼び出しプロセスを意味します。返り値は上記のスケジューリングポリシー定数の一つになります。

os.sched_setparam(pid, param, /)

PID pid を持つプロセスのスケジューリングパラメータを設定します。 pid を 0 とした場合呼び出しプロセスを意味します。 param は sched_param インスタンスです。

os.sched_getparam(pid, /)

PID pid のプロセスのスケジューリングパラメーターを sched_param のインスタンスとして返します。pid が 0 の場合、呼び出しプロセスを意味します。

os.sched_rr_get_interval(pid, /)

PID pid のプロセスのラウンドロビンクォンタム (秒) を返します。pid が 0 の場合、呼び出しプロセスを意味します。

os.sched_yield()

自発的に CPU を解放します。

os.sched_setaffinity(pid, mask, /)

PID pid のプロセス (0 であれば現在のプロセス) を CPU の集合に制限します。mask はプロセスを制限する CPU の集合を表す整数のイテラブルなオブジェクトです。

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.

雑多なシステム情報

os.confstr(name, /)

システム設定値を文字列で返します。 name には取得したい設定名を指定します ; この値は定義済みのシステム値名を表す文字列にすることができます ; 名前は多くの標準 (POSIX.1 、 Unix 95 、 Unix 98 その他 ) で定義されています。ホストオペレーティングシステムの関知する名前は confstr_names 辞書のキーとして与えられています。このマップ型オブジェクトに入っていない設定変数については、 name に整数を渡してもかまいません。

name に指定された設定値が定義されていない場合、 None を返します。

name が文字列で、かつ不明の場合、 ValueError を送出します。 name の指定値がホストシステムでサポートされておらず、 confstr_names にも入っていない場合、 errno.EINVAL をエラー番号として OSError を送出します。

利用可能な環境: Unix。

os.confstr_names

confstr() が受理する名前を、ホストオペレーティングシステムで定義されている整数値に対応付けている辞書です。この辞書はシステムでどの設定名が定義されているかを決定するために利用できます。

利用可能な環境: Unix。

os.cpu_count()

Return the number of logical CPUs in the system. Returns None if undetermined.

This number is not equivalent to the number of logical CPUs the current process can use. len(os.sched_getaffinity(0)) gets the number of logical CPUs the calling thread of the current process is restricted to

Added in version 3.4.

os.getloadavg()

過去 1 分、 5 分、および 15 分間の、システムの実行キューの平均プロセス数を返します。平均負荷が得られない場合には OSError を送出します。

利用可能な環境: Unix。

os.sysconf(name, /)

整数値のシステム設定値を返します。 name で指定された設定値が定義されていない場合、 -1 が返されます。 name に関するコメントとしては、 confstr() で述べた内容が同様に当てはまります ; 既知の設定名についての情報を与える辞書は sysconf_names で与えられています。

利用可能な環境: Unix。

os.sysconf_names

sysconf() が受理する名前を、ホストオペレーティングシステムで定義されている整数値に対応付けている辞書です。この辞書はシステムでどの設定名が定義されているかを決定するために利用できます。

利用可能な環境: Unix。

バージョン 3.11 で変更: Add 'SC_MINSIGSTKSZ' name.

以下のデータ値はパス名編集操作をサポートするために利用されます。これらの値はすべてのプラットフォームで定義されています。

パス名に対する高水準の操作は os.path モジュールで定義されています。

os.curdir

現在のディレクトリ参照するためにオペレーティングシステムで使われる文字列定数です。 POSIX と Windows では '.' になります。 os.path からも利用できます。

os.pardir

親ディレクトリを参照するためにオペレーティングシステムで使われる文字列定数です。 POSIX と Windows では '..' になります。 os.path からも利用できます。

os.sep

パス名を要素に分割するためにオペレーティングシステムで利用されている文字です。例えば POSIX では '/' で、 Windows では '\\' です。しかし、このことを知っているだけではパス名を解析したり、パス名同士を結合したりするには不十分です --- こうした操作には os.path.split() や os.path.join() を使用してください --- が、たまに便利なこともあります。 os.path からも利用できます。

os.altsep

文字パス名を要素に分割する際にオペレーティングシステムで利用されるもう一つの文字で、分割文字が一つしかない場合には None になります。この値は sep がバックスラッシュとなっている DOS や Windows システムでは '/' に設定されています。 os.path からも利用できます。

os.extsep

ベースのファイル名と拡張子を分ける文字です。例えば、 os.py であれば '.' です。 os.path からも利用できます。

os.pathsep

(PATH のような ) サーチパス内の要素を分割するためにオペレーティングシステムが慣習的に用いる文字で、 POSIX における ':' や DOS および Windows における ';' に相当します。 os.path からも利用できます。

os.defpath

exec*p* や spawn*p* において、環境変数辞書内に 'PATH' キーがない場合に使われる標準設定のサーチパスです。 os.path からも利用できます。

os.linesep

現在のプラットフォーム上で行を分割 ( あるいは終端 ) するために用いられている文字列です。この値は例えば POSIX での '\n' や Mac OS での '\r' のように、単一の文字にもなりますし、例えば Windows での '\r\n' のように複数の文字列にもなります。テキストモードで開いたファイルに書き込む時には、 os.linesep を利用しないでください。すべてのプラットフォームで、単一の '\n' を使用してください。

os.devnull

ヌルデバイスのファイルパスです。例えば POSIX では '/dev/null' で、 Windows では 'nul' です。この値は os.path からも利用できます。

os.RTLD_LAZY

os.RTLD_NOW

os.RTLD_GLOBAL

os.RTLD_LOCAL

os.RTLD_NODELETE

os.RTLD_NOLOAD

os.RTLD_DEEPBIND

setdlopenflags() 関数と getdlopenflags() 関数と一緒に使用するフラグ。それぞれのフラグの意味については、Unix マニュアルの dlopen(3) [https://manpages.debian.org/dlopen(3)] ページを参照してください。

Added in version 3.3.

乱数

os.getrandom(size, flags=0)

最大で size バイトからなるランダムなバイト列を返します。この関数は要求されたバイト数よりも少ないバイト数を返すことがあります。

バイト列は、ユーザー空間の乱数生成器や暗号目的ののシードとして利用できます。

getrandom() はデバイスドライバや他の環境ノイズ源から収集されたエントロピーに頼っています。不必要な大量のデータの読出しは、/dev/random と /dev/urandom デバイスの他のユーザーに負の影響を与えるでしょう。

The flags argument is a bit mask that can contain zero or more of the following values ORed together: os.GRND_RANDOM and GRND_NONBLOCK.

Linux getrandom() manual page [https://man7.org/linux/man-pages/man2/getrandom.2.html] も参照してください。

利用可能な環境: Linux 3.17以上。

Added in version 3.6.

os.urandom(size, /)

暗号に関する用途に適した size バイトからなるランダムなバイト文字列を返します。

この関数は OS 固有の乱数発生源からランダムなバイト列を生成して返します。この関数の返すデータは暗号を用いたアプリケーションで十分利用できる程度に予測不能ですが、実際のクオリティは OS の実装によって異なります。

Linux では、 getrandom() システムコールが利用可能ならブロッキングモードで呼び出されます: すなわちシステムの urandom エントロピープールが初期化されるまで (128 ビットのエントロピーがカーネルにより収集されるまで) 処理がブロックされます。論拠については PEP 524 [https://peps.python.org/pep-0524/] を参照してください。 Linux では、 (GRND_NONBLOCK フラグを使って) 非ブロッキングモードでランダムなバイトを取得したり、システムの urandom エントロピープールが初期化されるまでポーリングするために getrandom() 関数を利用することができます。

Unix ライクなシステムでは、ランダムなバイトは /dev/urandom デバイスから読み込みます。 /dev/urandom デバイスが利用できないか、もしくは読み取り不可のときは、 NotImplementedError 例外が送出されます。

Windowsで、 BCryptGenRandom() を使用します。

参考

secrets モジュールは高レベルの乱数生成機能を提供します。プラットフォームが提供する乱数生成器に対する簡便なインターフェースについては、 random.SystemRandom を参照してください。

バージョン 3.5 で変更: Linux 3.17 以降では、使用可能な場合に getrandom() システムコールが使用されるようになりました。OpenBSD 5.6 以降では、C getentropy() 関数が使用されるようになりました。これらの関数は、内部ファイル記述子を使用しません。

バージョン 3.5.2 で変更: Linux において、 getrandom() システムコールがブロックするなら (urandom エントロピープールが初期化されていなければ) 、 /dev/urandom を読む方法にフォールバックします。

バージョン 3.6 で変更: Linuxで、 セキュリティを高めるために、getrandom() をブロッキングモードで使用するようになりました。

バージョン 3.11 で変更: On Windows, BCryptGenRandom() is used instead of CryptGenRandom() which is deprecated.

os.GRND_NONBLOCK

デフォルトでは、getrandom() は /dev/random から読み込んだときにランダムなバイトが存在しない場合や、 /dev/urandom から読み込んだときにエントロピープールが初期化されていない場合に処理をブロックします。

GRND_NONBLOCK フラグがセットされると、 getrandom() はこれらの場合に処理をブロックせず、ただちに BlockingIOError 例外を送出します。

Added in version 3.6.

os.GRND_RANDOM

このビットがセットされた場合、 ランダムバイトは /dev/urandom プールの代わりに /dev/random プールから取り出されます。

Added in version 3.6.

io --- Core tools for working with streams

ソースコード: Lib/io.py [https://github.com/python/cpython/tree/3.12/Lib/io.py]

概要

io モジュールは様々な種類の I/O を扱う Python の主要な機能を提供しています。 I/O には主に3つの種類があります; テキスト I/O, バイナリ I/O, raw I/O です。これらは汎用的なカテゴリで、各カテゴリには様々なストレージが利用されます。これらのいずれかのカテゴリに属する具象オブジェクトは全て file object と呼ばれます。他によく使われる用語として ストリーム と file-like オブジェクト があります。

それぞれの具象ストリームオブジェクトは、カテゴリに応じた機能を持ちます。ストリームは読み込み専用、書き込み専用、読み書き可能のいずかになります。任意のランダムアクセス（前方、後方の任意の場所にシークする）が可能かもしれませんし、シーケンシャルアクセスしかできないかもしれません（例えばソケットやパイプなど）。

All streams are careful about the type of data you give to them. For example giving a str object to the write() method of a binary stream will raise a TypeError. So will giving a bytes object to the write() method of a text stream.

バージョン 3.3 で変更: 以前 IOError を送出していた操作が OSError を送出するようになりました。 IOError は今は OSError の別名です。

テキスト I/O

テキスト I/O は、 str オブジェクトを受け取り、生成します。すなわち、背後にあるストレージがバイト列 (例えばファイルなど) を格納するときは常に、透過的にデータのエンコード・デコードを行ない、オプションでプラットフォーム依存の改行文字変換を行います。

テキストストリームを作る一番簡単な方法は、オプションでエンコーディングを指定して、 open() を利用することです:

f = open("myfile.txt", "r", encoding="utf-8")

StringIO オブジェクトはインメモリーのテキストストリームです:

f = io.StringIO("some initial text data")

テキストストリームの API は TextIOBase のドキュメントで詳しく解説します。

バイナリ I/O

バイナリー I/O (buffered I/O とも呼ばれます) は bytes-like オブジェクト を受け取り bytes オブジェクトを生成します。エンコード、デコード、改行文字変換は一切行いません。このカテゴリのストリームは全ての非テキストデータや、テキストデータの扱いを手動で管理したい場合に利用することができます。

バイナリーストリームを生成する一番簡単な方法は、 open() の mode 文字列に 'b' を指定することです:

f = open("myfile.jpg", "rb")

BytesIO はインメモリーのバイナリストリームです:

f = io.BytesIO(b"some initial binary data: \x00\x01")

バイナリーストリーム API は BufferedIOBase のドキュメントで詳しく解説します。

他のライブラリモジュールが、別のテキスト・バイナリーストリームを生成する方法を提供しています。例えば socket.socket.makefile() などです。

Raw I/O

Raw I/O (unbuffered I/O とも呼ばれます) は、バイナリーストリームやテキストストリームの低水準の部品としてよく利用されます。ユーザーコードで直接 raw ストリームを扱うべき場面は滅多にありません。とはいえ、バッファリングを無効にしてファイルをバイナリーモードで開くことで raw ストリームを作ることができます:

f = open("myfile.jpg", "rb", buffering=0)

raw ストリーム API は RawIOBase のドキュメントで詳しく解説します。

Text Encoding

The default encoding of TextIOWrapper and open() is locale-specific (locale.getencoding()).

However, many developers forget to specify the encoding when opening text files encoded in UTF-8 (e.g. JSON, TOML, Markdown, etc...) since most Unix platforms use UTF-8 locale by default. This causes bugs because the locale encoding is not UTF-8 for most Windows users. For example:

# May not work on Windows when non-ASCII characters in the file.
with open("README.md") as f:
    long_description = f.read()

Accordingly, it is highly recommended that you specify the encoding explicitly when opening text files. If you want to use UTF-8, pass encoding="utf-8". To use the current locale encoding, encoding="locale" is supported since Python 3.10.

参考

Python UTF-8 Mode

Python UTF-8 Mode can be used to change the default encoding to UTF-8 from locale-specific encoding.

PEP 686 [https://peps.python.org/pep-0686/]

Python 3.15 will make Python UTF-8 Mode default.

Opt-in EncodingWarning

Added in version 3.10: See PEP 597 [https://peps.python.org/pep-0597/] for more details.

To find where the default locale encoding is used, you can enable the -X warn_default_encoding command line option or set the PYTHONWARNDEFAULTENCODING environment variable, which will emit an EncodingWarning when the default encoding is used.

If you are providing an API that uses open() or TextIOWrapper and passes encoding=None as a parameter, you can use text_encoding() so that callers of the API will emit an EncodingWarning if they don't pass an encoding. However, please consider using UTF-8 by default (i.e. encoding="utf-8") for new APIs.

高水準のモジュールインターフェイス

io.DEFAULT_BUFFER_SIZE

このモジュールの buffered I/O クラスで利用されるデフォルトのバッファーサイズを表す整数です。可能であれば、open() は file の blksize (os.stat() で取得される) を利用します。

io.open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)

組み込みの open() 関数のエイリアスです。

引数 path, mode, flags を指定して 監査イベント open を送出します。

io.open_code(path)

'rb' モードでファイルを開きます。この関数はファイルの中身を実行可能なコードとして扱いたい場合にのみ使用します。

path should be a str and an absolute path.

The behavior of this function may be overridden by an earlier call to the PyFile_SetOpenCodeHook(). However, assuming that path is a str and an absolute path, open_code(path) should always behave the same as open(path, 'rb'). Overriding the behavior is intended for additional validation or preprocessing of the file.

Added in version 3.8.

io.text_encoding(encoding, stacklevel=2, /)

This is a helper function for callables that use open() or TextIOWrapper and have an encoding=None parameter.

This function returns encoding if it is not None. Otherwise, it returns "locale" or "utf-8" depending on UTF-8 Mode.

This function emits an EncodingWarning if sys.flags.warn_default_encoding is true and encoding is None. stacklevel specifies where the warning is emitted. For example:

def read_text(path, encoding=None):
    encoding = io.text_encoding(encoding)  # stacklevel=2
    with open(path, encoding) as f:
        return f.read()

In this example, an EncodingWarning is emitted for the caller of read_text().

See Text Encoding for more information.

Added in version 3.10.

バージョン 3.11 で変更: text_encoding() returns "utf-8" when UTF-8 mode is enabled and encoding is None.

exception io.BlockingIOError

互換性のための、組み込みの BlockingIOError 例外のエイリアスです。

exception io.UnsupportedOperation

OSError と ValueError を継承した例外です。ストリームがサポートしていない操作を行おうとした時に送出されます。

参考

sys

標準 IO ストリームを持っています: sys.stdin, sys.stdout, sys.stderr。

クラス階層

I/O ストリームの実装はクラス階層に分けて整理されています。まずストリームのカテゴリを分類するための 抽象基底クラス (ABC) があり、続いて標準のストリーム実装を行う具象クラス群があります。

注釈

The abstract base classes also provide default implementations of some methods in order to help implementation of concrete stream classes. For example, BufferedIOBase provides unoptimized implementations of readinto() and readline().

I/O 階層の最上位には抽象基底クラスの IOBase があります。 IOBase ではストリームに対して基本的なインターフェースを定義しています。 しかしながら、ストリームに対する読み込みと書き込みが分離されていないことに注意してください。 実装においては与えられた操作をサポートしない場合は UnsupportedOperation を送出することが許されています。

RawIOBase ABC は IOBase を拡張します。このクラスはストリームからの bytes の読み書きを扱います。 FileIO は、 RawIOBase を継承してマシンのファイルシステム中のファイルへのインターフェースを提供します。

The BufferedIOBase ABC extends IOBase. It deals with buffering on a raw binary stream (RawIOBase). Its subclasses, BufferedWriter, BufferedReader, and BufferedRWPair buffer raw binary streams that are writable, readable, and both readable and writable, respectively. BufferedRandom provides a buffered interface to seekable streams. Another BufferedIOBase subclass, BytesIO, is a stream of in-memory bytes.

TextIOBase ABC は IOBase を拡張します。このクラスはテキストをあらわすバイトストリームを対象とし、バイトデータと文字列の間のエンコーディングやデコーディングを適切に行います。 TextIOWrapper は TextIOBase を拡張し、バッファリングされた生のストリーム (BufferedIOBase) に対するバッファリングされたテキストのインターフェースです。最後に、 StringIO はメモリ上のテキストデータに対するストリームです。

引数名は規約に含まれていません。 そして open() の引数だけがキーワード引数として用いられることが意図されています。

次のテーブルは io モジュールが提供する ABC の概要です:

ABC

継承元

スタブメソッド

Mixin するメソッドとプロパティ

IOBase

fileno, seek, truncate

close, closed, __enter__, __exit__, flush, isatty, __iter__, __next__, readable, readline, readlines, seekable, tell, writable, writelines

RawIOBase

IOBase

readinto, write

IOBase から継承したメソッド、 read, readall

BufferedIOBase

IOBase

detach, read, read1, write

IOBase から継承したメソッド、 readinto, readinto1

TextIOBase

IOBase

detach, read, readline, write

IOBase から継承したメソッド、 encoding, errors, newlines

I/O 基底クラス

class io.IOBase

The abstract base class for all I/O classes.

継承先のクラスが選択的にオーバライドできるように、このクラスは多くのメソッドに空の抽象実装をしています。デフォルトの実装では、読み込み、書き込み、シークができないファイルを表現します。

Even though IOBase does not declare read() or write() because their signatures will vary, implementations and clients should consider those methods part of the interface. Also, implementations may raise a ValueError (or UnsupportedOperation) when operations they do not support are called.

ファイルへのバイナリデータの読み書きに用いられる基本型は bytes です。他の bytes-like オブジェクト もメソッドの引数として受け付けられます。テキスト I/O クラスは str データを扱います。

閉じられたストリームに対するメソッド呼び出しは (問い合わせであっても) 未定義です。この場合、実装は ValueError を送出することがあります。

IOBase (とそのサブクラス) はイテレータプロトコルをサポートします。 IOBase オブジェクトをイテレートすると、ストリーム内の行が yield されます。ストリーム内の行の定義は、そのストリームが (バイト列を yield する) バイナリストリームか (文字列を yield する) テキストストリームかによって、 少し異なります。下の readline() を参照してください。

IOBase はコンテキストマネージャでもあります。そのため with 構文をサポートします。 次の例では、 with 構文が終わった後で---たとえ例外が発生した場合でも、 file は閉じられます。

with open('spam.txt', 'w') as file:
    file.write('Spam and eggs!')

IOBase は以下のデータ属性とメソッドを提供します:

close()

このストリームをフラッシュして閉じます。このメソッドはファイルが既に閉じられていた場合は特に何の効果もありません。いったんファイルが閉じられると、すべてのファイルに対する操作 (例えば読み込みや書き込み) で ValueError が発生します。

利便性のためにこのメソッドを複数回呼ぶことは許されています。しかし、効果があるのは最初の1回だけです。

closed

ストリームが閉じられていた場合 True になります。

fileno()

ストリームが保持しているファイル記述子 (整数値) が存在する場合はそれを返します。もし IO オブジェクトがファイル記述子を使っていない場合は OSError が発生します。

flush()

適用可能であればストリームの書き込みバッファをフラッシュします。読み出し専用や非ブロッキングストリームでは何もしません。

isatty()

ストリームが対話的であれば (つまりターミナルや tty デバイスにつながっている場合) True を返します。

readable()

Return True if the stream can be read from. If False, read() will raise OSError.

readline(size=-1, /)

ストリームから 1 行読み込んで返します。もし size が指定された場合、最大で size バイトが読み込まれます。

バイナリファイルでは行末文字は常に b'\n' となります。テキストファイルでは、認識される行末文字を選択するために open() に対する newline 引数が使われます。

readlines(hint=-1, /)

ストリームから行のリストを読み込んで返します。 hint を指定することで、読み込む行数を制御できます。もし読み込んだすべての行のサイズ (バイト数、もしくは文字数) が hint の値を超えた場合、それ以上の行は読み込まれません。

引数 hint の値が 0 以下、および None の場合は、ヒントがないものとして取り扱われます。

Note that it's already possible to iterate on file objects using for line in file: ... without calling file.readlines().

seek(offset, whence=os.SEEK_SET, /)

Change the stream position to the given byte offset, interpreted relative to the position indicated by whence, and return the new absolute position. Values for whence are:

os.SEEK_SET or 0 -- start of the stream (the default); offset should be zero or positive

os.SEEK_CUR or 1 -- current stream position; offset may be negative

os.SEEK_END or 2 -- end of the stream; offset is usually negative

Added in version 3.1: The SEEK_* constants.

Added in version 3.3: Some operating systems could support additional values, like os.SEEK_HOLE or os.SEEK_DATA. The valid values for a file could depend on it being open in text or binary mode.

seekable()

ストリームがランダムアクセスをサポートしている場合、 True を返します。 False の場合、 seek()、 tell()、 truncate() を使用すると OSError を発生させます。

tell()

現在のストリーム位置を返します。

truncate(size=None, /)

ストリームのサイズを、指定された size バイト (または size が指定されていない場合、現在位置) に変更します。現在のストリーム位置は変更されません。このサイズ変更により、現在のファイルサイズを拡大または縮小させることができます。拡大の場合には、新しいファイル領域の内容はプラットホームによって異なります (ほとんどのシステムでは、追加のバイトが 0 で埋められます)。新しいファイルサイズが返されます。

バージョン 3.5 で変更: Windows で、拡大時に追加領域を 0 で埋めるようになりました。

writable()

Return True if the stream supports writing. If False, write() and truncate() will raise OSError.

writelines(lines, /)

ストリームに行のリストを書き込みます。行区切り文字は追加されないので、書き込む各行の行末に行区切り文字を含ませるのが一般的です。

__del__()

オブジェクトの破壊の用意をします。このメソッドはインスタンスの close() メソッドを呼びます。 IOBase はこのメソッドのデフォルトの実装を提供します

class io.RawIOBase

Base class for raw binary streams. It inherits from IOBase.

生のバイナリストリームは典型的に、背後にある OS デバイスや API への低水準なアクセスを提供し、それらを高水準の基本要素へカプセル化しようとはしません (そのような機能は後述するバッファされたバイナリストリームやテキストストリームのような高水準のクラスで行われます)。

RawIOBase は IOBase が提供するメソッドに加えて、以下のメソッドを提供します:

read(size=-1, /)

オブジェクトを size バイトまで読み込み、それを返します。簡単のため、 size が指定されていないか -1 の場合は、 EOF までの全てのバイトを返します。そうでない場合は、システムコール呼び出しが一度だけ行われます。オペレーティングシステムコールから返ってきたものが size バイトより少なければ、 size バイトより少ない返り値になることがあります。

size が 0 でないのに 0 バイトが返った場合、それはファイルの終端を表します。オブジェクトがノンブロッキングモードで、1 バイトも読み込めなければ、None が返されます。

デフォルトの実装は readall() と readinto() に従います。

readall()

EOF までストリームからすべてのバイトを読み込みます。必要な場合はストリームに対して複数の呼び出しをします。

readinto(b, /)

あらかじめ確保された書き込み可能な bytes 類オブジェクト b にバイト列を読み込み、読み込んだバイト数を返します。例えば、 b は bytearray です。オブジェクトがノンブロッキングモードで、 1 バイトも読み込めなければ、 None が返されます。

write(b, /)

与えられた bytes-like オブジェクト b を生ストリームに書き込み、書き込んだバイト数を返します。これは、根底の生ストリームの性質や、特にノンブロッキングである場合に、 b のバイト数より小さくなることがあります。生ストリームがブロックされないように設定されていて、かつ1バイトも即座に書き込むことができなければ、 None が返されます。このメソッドから返った後で呼び出し元は b を解放したり変更したりするかもしれないので、実装はメソッド呼び出しの間だけ b にアクセスすべきです。

class io.BufferedIOBase

Base class for binary streams that support some kind of buffering. It inherits from IOBase.

RawIOBase との主な違いは、メソッド read()、 readinto() および write() は 、ことによると複数回のシステムコールを行って、(それぞれ) 要求されただけの入力を読み込もうとしたり与えられた出力の全てを消費しようとしたりする点です。

加えて、元になる生ストリームが非ブロッキングモードでかつ準備ができていない場合に、これらのメソッドは、 BlockingIOError を送出するかもしれません。対応する RawIOBase バージョンと違って、 None を返すことはありません。

さらに、 read() メソッドは、 readinto() に従うデフォルト実装を持ちません。

通常の BufferedIOBase 実装は RawIOBase 実装を継承せずに、 BufferedWriter と BufferedReader がするようにこれをラップすべきです。

BufferedIOBase は IOBase から継承した属性とメソッドに加えて、以下のデータ属性とメソッドを提供またはオーバーライドします:

raw

BufferedIOBase が扱う根底の生ストリーム (RawIOBase インスタンス) を返します。これは BufferedIOBase API には含まれず、よって実装に含まれないことがあります。

detach()

根底の生ストリームをバッファから分離して返します。

生ストリームが取り外された後、バッファは使用不能状態になります。

バッファには、 BytesIO など、このメソッドで返される単体のストリームという概念を持たないものがあります。これらは UnsupportedOperation を送出します。

Added in version 3.1.

read(size=-1, /)

最大で size バイト読み込んで返します。 引数が省略されるか、 None か、または負の値であった場合、 データは EOF に到達するまで読み込まれます。 ストリームが既に EOF に到達していた場合は空の bytes オブジェクトが返されます。

引数が正で、元になる生ストリームが対話的でなければ、必要なバイト数を満たすように複数回の生 read が発行されるかもしれません (先に EOF に到達しない限りは)。対話的な場合は、最大で一回の raw read しか発行されず、短い結果でも EOF に達したことを意味しません。

元になる生ストリームがノンブロッキングモードで、呼び出された時点でデータを持っていなければ、 BlockingIOError が送出されます。

read1(size=-1, /)

根底の raw ストリームの read() (または readinto() ) メソッドを高々 1 回呼び出し、最大で size バイト読み込み、返します。これは、 BufferedIOBase オブジェクトの上に独自のバッファリングを実装するときに便利です。

size に -1 （デフォルト値)を指定すると任意バイト長を返します（EOFに到達していなければ返されるバイト数は 0 より大きくなります）

readinto(b, /)

あらかじめ確保された書き込み可能な bytes 類オブジェクト b にバイト列を読み込み、読み込んだバイト数を返します。例えば、 b は bytearray です。

read() と同様に、下層の raw ストリームが対話的でない限り、複数の読み込みは下層の raw ストリームに与えられるかもしれません。

元になる生ストリームがノンブロッキングモードで、呼び出された時点でデータを持っていなければ、 BlockingIOError が送出されます。

readinto1(b, /)

根底の raw ストリームの read() (または readinto()) メソッドを高々 1 回呼び出し、あらかじめ確保された書き込み可能な bytes-like オブジェクト b にバイト列を読み込みます。読み込んだバイト数を返します。

元になる生ストリームがノンブロッキングモードで、呼び出された時点でデータを持っていなければ、 BlockingIOError が送出されます。

Added in version 3.5.

write(b, /)

与えられた bytes-like オブジェクト b を書き込み、書き込んだバイト数を返します (これは常に b のバイト数と等しくなります。なぜなら、もし書き込みに失敗した場合は OSError が発生するからです)。実際の実装に依存して、これらのバイト列は根底のストリームに即座に書き込まれることもあれば、パフォーマンスやレイテンシの関係でバッファに保持されることもあります。

ノンブロッキングモードであるとき、バッファが満杯で根底の生ストリームが書き込み時点でさらなるデータを受け付けられない場合 BlockingIOError が送出されます。

このメソッドが戻った後で、呼び出し元は b を解放、または変更するかもしれないので、実装はメソッド呼び出しの間だけ b にアクセスすべきです。

生ファイルI/O

class io.FileIO(name, mode='r', closefd=True, opener=None)

A raw binary stream representing an OS-level file containing bytes data. It inherits from RawIOBase.

name は、次の 2 つのいずれかです。

開くファイルへのパスを表す文字列または bytes オブジェクト。この場合、closefd は True (デフォルト) でなければなりません。 True でない場合、エラーが送出されます。

結果の FileIO オブジェクトがアクセスを与える、既存の OS レベルファイル記述子の数を表す整数。FileIO オブジェクトが閉じられると、closefd が False に設定されていない場合、この fd も閉じられます。

mode は 読み込み（デフォルト）、書き込み、排他的作成、追記に対し 'r' 、 'w' 、 'x' 、 'a' です。ファイルは書き込みや追記で開かれたときに存在しない場合作成されます。書き込みのときにファイルの内容は破棄されます。作成時に既に存在する場合は FileExistsError が送出されます。作成のためにファイルを開くのは暗黙的に書き込みなので、このモードは 'w' と同じように振る舞います。読み込みと書き込みを同時に許可するにはモードに '+' を加えてください。

The read() (when called with a positive argument), readinto() and write() methods on this class will only make one system call.

呼び出し可能オブジェクトを opener として与えることで、カスタムのオープナーが使えます。そしてファイルオブジェクトの基底のファイルディスクリプタは、opener を (name, flags) で呼び出して得られます。opener は開いたファイルディスクリプタを返さなければなりません。 (os.open を opener として渡すと、None を渡したのと同様の機能になります。)

新たに作成されたファイルは 継承不可 です。

opener 引数を使う例については open() 組み込み関数を参照してください。

バージョン 3.3 で変更: opener 引数が追加されました。'x' モードが追加されました。

バージョン 3.4 で変更: ファイルが継承不可になりました。

FileIO は RawIOBase と IOBase から継承したデータ属性に加えて以下のデータ属性を提供します:

mode

コンストラクタに渡されたモードです。

name

ファイル名。コンストラクタに名前が渡されなかったときはファイル記述子になります。

バッファ付きストリーム

バッファ付き I/O ストリームは、I/O デバイスに生 I/O より高レベルなインターフェースを提供します。

class io.BytesIO(initial_bytes=b'')

A binary stream using an in-memory bytes buffer. It inherits from BufferedIOBase. The buffer is discarded when the close() method is called.

省略可能な引数 initial_bytes は、初期データを含んだ bytes-like オブジェクト です。

BytesIO は BufferedIOBase または IOBase からのメソッドに加えて、以下のメソッドを提供もしくはオーバーライドします:

getbuffer()

バッファの内容をコピーすることなく、その内容の上に、読み込み及び書き込みが可能なビューを返します。また、このビューを変更すると、バッファの内容は透過的に更新されます:

>>> b = io.BytesIO(b"abcdef")
>>> view = b.getbuffer()
>>> view[2:4] = b"56"
>>> b.getvalue()
b'ab56ef'

注釈

ビューが存在する限り、BytesIO オブジェクトはリサイズやクローズされません。

Added in version 3.2.

getvalue()

バッファの全内容を含む bytes を返します。

read1(size=-1, /)

BytesIO においては、このメソッドは read() と同じです。

バージョン 3.7 で変更: size 引数が任意になりました。

readinto1(b, /)

BytesIO においては、このメソッドは readinto() と同じです。

Added in version 3.5.

class io.BufferedReader(raw, buffer_size=DEFAULT_BUFFER_SIZE)

A buffered binary stream providing higher-level access to a readable, non seekable RawIOBase raw binary stream. It inherits from BufferedIOBase.

このオブジェクトからデータを読み出した時、背後にある生のストリームからはより大きな量のデータの読み出しがリクエストされ、内部バッファに読み出したデータが保持されることがあります。バッファされたデータはその後の読み出し処理で直接返すことができます。

このコンストラクタは与えられた raw ストリームと buffer_size に対し BufferedReader を生成します。 buffer_size が省略された場合、代わりに DEFAULT_BUFFER_SIZE が使われます。

BufferedReader は BufferedIOBase または IOBase からのメソッドに加えて、以下のメソッドを提供もしくはオーバーライドします:

peek(size=0, /)

位置を進めずにストリームからバイト列を返します。これを果たすために生ストリームに対して行われる read は高々一度だけです。返されるバイト数は、要求より少ないかもしれませんし、多いかもしれません。

read(size=-1, /)

size バイトを読み込んで返します。size が与えられないか負の値ならば、EOF まで、または非ブロッキングモード中で read 呼び出しがブロックされるまでを返します。

read1(size=-1, /)

raw ストリームに対しただ一度の呼び出しで最大 size バイトを読み込んで返します。少なくとも 1 バイトがバッファされていれば、バッファされているバイト列だけが返されます。それ以外の場合は raw ストリームの読み込みが一回呼び出されます。

バージョン 3.7 で変更: size 引数が任意になりました。

class io.BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE)

A buffered binary stream providing higher-level access to a writeable, non seekable RawIOBase raw binary stream. It inherits from BufferedIOBase.

このオブジェクトに対して書き込みを行なったとき、データは通常内部バッファに配置されます。バッファは以下に示すさまざまな条件で背後にある RawIOBase オブジェクトに書き込まれます:

保留中の全データに対してバッファが足りなくなったとき;

when flush() is called;

when a seek() is requested (for BufferedRandom objects);

BufferedWriter オブジェクトが閉じられたり破棄されたりしたとき。

このコンストラクタは与えられた書き込み可能な raw ストリームに対し BufferedWriter を生成します。 buffer_size が省略された場合、 DEFAULT_BUFFER_SIZE がデフォルトになります。

BufferedWriter は BufferedIOBase または IOBase からのメソッドに加えて、以下のメソッドを提供もしくはオーバーライドします:

flush()

バッファに保持されたバイト列を生ストリームに強制的に流し込みます。生ストリームがブロックした場合 BlockingIOError が送出されます。

write(b, /)

bytes-like オブジェクト b を書き込み、書き込んだバイト数を返します。ノンブロッキング時、バッファが書き込まれるべきなのに生ストリームがブロックした場合 BlockingIOError が送出されます。

class io.BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)

A buffered binary stream providing higher-level access to a seekable RawIOBase raw binary stream. It inherits from BufferedReader and BufferedWriter.

このコンストラクタは第一引数として与えられるシーク可能な生ストリームに対し、リーダーおよびライターを作成します。 buffer_size が省略された場合、 DEFAULT_BUFFER_SIZE がデフォルトになります。

BufferedRandom is capable of anything BufferedReader or BufferedWriter can do. In addition, seek() and tell() are guaranteed to be implemented.

class io.BufferedRWPair(reader, writer, buffer_size=DEFAULT_BUFFER_SIZE, /)

A buffered binary stream providing higher-level access to two non seekable RawIOBase raw binary streams---one readable, the other writeable. It inherits from BufferedIOBase.

reader と writer はそれぞれ読み込み可能、書き込み可能な RawIOBase オブジェクトです。 buffer_size が省略された場合 DEFAULT_BUFFER_SIZE がデフォルトになります。

BufferedRWPair は、 UnsupportedOperation を送出する detach() を除く、 BufferedIOBase の全てのメソッドを実装します。

警告

BufferedRWPair は下層の生ストリームのアクセスを同期しようとはしません。同じオブジェクトをリーダとライタとして渡してはいけません。その場合は代わりに BufferedRandom を使用してください。

テキスト I/O

class io.TextIOBase

Base class for text streams. This class provides a character and line based interface to stream I/O. It inherits from IOBase.

IOBase から継承した属性とメソッドに加えて、 TextIOBase は以下のデータ属性とメソッドを提供しています:

encoding

エンコーディング名で、ストリームのバイト列を文字列にデコードするとき、また文字列をバイト列にエンコードするときに使われます。

errors

このエンコーダやデコーダのエラー設定です。

newlines

文字列、文字列のタプル、または None で、改行がどのように読み換えられるかを指定します。実装や内部コンストラクタのフラグに依って、これは利用できないことがあります。

buffer

TextIOBase が扱う根底のバイナリバッファ (BufferedIOBase インスタンス) です。これは TextIOBase API には含まれず、よって実装に含まれない場合があります。

detach()

根底のバイナリバッファを TextIOBase から分離して返します。

根底のバッファが取り外された後、 TextIOBase は使用不能状態になります。

TextIOBase 実装には、 StringIO など、根底のバッファという概念を持たないものがあります。これらを呼び出すと UnsupportedOperation を送出します。

Added in version 3.1.

read(size=-1, /)

最大 size 文字をストリームから読み込み、一つの str にして返します。 size が負の値または None ならば、 EOF まで読みます。

readline(size=-1, /)

Read until newline or EOF and return a single str. If the stream is already at EOF, an empty string is returned.

size が指定された場合、最大 size 文字が読み込まれます。

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

SEEK_SET or 0: seek from the start of the stream (the default); offset must either be a number returned by TextIOBase.tell(), or zero. Any other offset value produces undefined behaviour.

SEEK_CUR or 1: "seek" to the current position; offset must be zero, which is a no-operation (all other values are unsupported).

SEEK_END or 2: seek to the end of the stream; offset must be zero (all other values are unsupported).

新しい絶対位置を、不透明な数値で返します。

Added in version 3.1: The SEEK_* constants.

tell()

ストリームの現在位置を不透明な数値で返します。この値は根底のバイナリストレージ内でのバイト数を表すとは限りません。

write(s, /)

文字列 s をストリームに書き出し、書き出された文字数を返します。

class 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 BufferedIOBase buffered binary stream. It inherits from TextIOBase.

encoding gives the name of the encoding that the stream will be decoded or encoded with. It defaults to locale.getencoding(). encoding="locale" can be used to specify the current locale's encoding explicitly. See Text Encoding for more information.

errors はオプションの文字列で、エンコードやデコードの際のエラーをどのように扱うかを指定します。エンコードエラーがあったときに ValueError 例外を送出させるには 'strict' を渡します (デフォルトの None でも同じです)。エラーを無視させるには 'ignore' を渡します。 (エンコーディングエラーを無視するとデータを喪失する可能性があることに注意してください。) 'replace' は不正な形式の文字の代わりにマーカ (たとえば '?') を挿入させます。'backslashreplace' を指定すると、不正な形式のデータをバックスラッシュ付きのエスケープシーケンスに置換します。書き込み時には 'xmlcharrefreplace' (適切な XML 文字参照に置換) や 'namereplace' (\N{...} エスケープシーケンスに置換) も使えます。他にも codecs.register_error() で登録されたエラー処理名が有効です。

newline は行末をどのように処理するかを制御します 。None, '', '\n', '\r', '\r\n' のいずれかです。これは以下のように動作します:

ストリームからの入力を読み込んでいるとき、もし newline が None ならば universal newlines モードが有効になります。入力中の行は '\n', '\r', または '\r\n' のいずれで終わってもよく、それらは呼び出し元に返される前に``'n'`` に変換されます。 newline が '' の場合、 universal newlines モードは有効になりますが、行末のコードは変換されずに呼び出し元に返されます。 newline がその他の有効な値の場合は、入力行は与えられた文字列のみで終端され、行末は変換されずに呼び出し元に返されます。

ストリームへの出力の書き込み時、newline が None の場合、全ての '\n' 文字はシステムのデフォルトの行セパレータ os.linesep に変換されます。 newline が '' または '\n' の場合は変換されません。newline がその他の正当な値の場合、全ての '\n' 文字は与えられた文字列に変換されます。

If line_buffering is True, flush() is implied when a call to write contains a newline character or a carriage return.

If write_through is True, calls to write() are guaranteed not to be buffered: any data written on the TextIOWrapper object is immediately handled to its underlying binary buffer.

バージョン 3.3 で変更: write_through 引数が追加されました。

バージョン 3.3 で変更: encoding の規定値が locale.getpreferredencoding() から locale.getpreferredencoding(False) になりました。 locale.setlocale() を用いてロケールのエンコーディングを一時的に変更してはいけません。ユーザが望むエンコーディングではなく現在のロケールのエンコーディングを使用してください。

バージョン 3.10 で変更: The encoding argument now supports the "locale" dummy encoding name.

TextIOWrapper は TextIOBase と IOBase から継承したものに加えて以下のデータ属性をメソッドを提供します:

line_buffering

行バッファリングが有効かどうか。

write_through

書き込みが、根柢のバイナリバッファに即座に渡されるかどうか。

Added in version 3.7.

reconfigure(*, encoding=None, errors=None, newline=None, line_buffering=None, write_through=None)

このテキストストリームを encoding, errors, newline, line_buffering と write_through を新しい設定として再設定します。

encoding が指定されており、errors が指定されていないときに、 errors='strict' が使われている場合を除き、指定されなかったパラメータは現在の設定が保持されます。

ストリームからすでにデータが読み出されていた場合、encodingとnewlineは変更できません。一方で、書き込み後にencodingを変更することはできます。

このメソッドは、新しい設定を適用するまえにストリームをフラッシュします。

Added in version 3.7.

バージョン 3.11 で変更: The method supports encoding="locale" option.

seek(cookie, whence=os.SEEK_SET, /)

Set the stream position. Return the new stream position as an int.

Four operations are supported, given by the following argument combinations:

seek(0, SEEK_SET): Rewind to the start of the stream.

seek(cookie, SEEK_SET): Restore a previous position; cookie must be a number returned by tell().

seek(0, SEEK_END): Fast-forward to the end of the stream.

seek(0, SEEK_CUR): Leave the current stream position unchanged.

Any other argument combinations are invalid, and may raise exceptions.

参考

os.SEEK_SET, os.SEEK_CUR, and os.SEEK_END.

tell()

Return the stream position as an opaque number. The return value of tell() can be given as input to seek(), to restore a previous stream position.

class io.StringIO(initial_value='', newline='\n')

A text stream using an in-memory text buffer. It inherits from TextIOBase.

テキストバッファは close() メソッドが呼び出されたときに破棄されます。

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 write(). The stream is positioned at the start of the buffer which emulates opening an existing file in a 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 a+ mode ready for appending, use f.seek(0, io.SEEK_END) to reposition the stream at the end of the buffer.

newline 引数は TextIOWrapper の同名の引数と同じように働きます。ただし、出力をストリームに書き込む時に newline が None の場合には、改行は全てのプラットフォームで \n になります。

TextIOBase と IOBase から継承したメソッドに加えて StringIO は以下のメソッドを提供しています:

getvalue()

Return a str containing the entire contents of the buffer. Newlines are decoded as if by read(), although the stream position is not changed.

使用例:

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()

class io.IncrementalNewlineDecoder

A helper codec that decodes newlines for universal newlines mode. It inherits from codecs.IncrementalDecoder.

性能

このセクションでは与えられた具体的な I/O 実装の性能について議論します。

バイナリ I/O

バッファ付き I/O は、ユーザが 1 バイトだけ要求した場合でさえ、データを大きな塊でのみ読み書きします。これにより、オペレーティングシステムのバッファ無し I/O ルーチンを呼び出して実行する非効率性はすべて隠されます。その成果は、OS と、実行される I/O の種類によって異なります。例えば、Linux のような現行の OS では、バッファ無しディスク I/O がバッファ付き I/O と同じくらい早いことがあります。しかし、どのプラットフォームとデバイスにおいても、バッファ付き I/O は最低でも予測可能なパフォーマンスを提供します。ですから、バイナリデータに対しては、バッファ無し I/O を使用するより、バッファ付きの I/O を使用するほうが望ましい場合がほとんどです。

テキスト 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, tell() and seek() are both quite slow due to the reconstruction algorithm used.

しかし StringIO は、ネイティブなインメモリ Unicode コンテナで、 BytesIO と同程度の速度を示します。

マルチスレッディング

FileIO objects are thread-safe to the extent that the operating system calls (such as read(2) [https://manpages.debian.org/read(2)] under Unix) they wrap are thread-safe too.

バイナリバッファ付きオブジェクト (BufferedReader, BufferedWriter, BufferedRandom および BufferedRWPair のインスタンス) は、その内部構造をロックを使って保護します。このため、これらを複数のスレッドから同時に呼び出しても安全です。

TextIOWrapper オブジェクトはスレッドセーフではありません。

リエントラント性

バイナリバッファ付きオブジェクト (BufferedReader, BufferedWriter, BufferedRandom および BufferedRWPair のインスタンス) は、リエントラント (再入可能) ではありません。リエントラントな呼び出しは普通の状況では起こりませんが、 I/O を signal ハンドラで行なっているときに起こりえます。スレッドが、すでにアクセスしているバッファ付きオブジェクトに再び入ろうとすると RuntimeError が送出されます。これは、バッファ付きオブジェクトに複数のスレッドから入ることを禁止するわけではありません。

open() 関数は TextIOWrapper 内部のバッファ付きオブジェクトをラップするため、テキストファイルにも暗黙に拡張されます。これは、標準ストリームを含むので、組み込みの print() 関数にも同様に影響します。

time --- Time access and conversions

このモジュールでは、時刻に関するさまざまな関数を提供します。関連した機能について、datetime, calendar モジュールも参照してください。

このモジュールは常に利用可能ですが、すべての関数がすべてのプラットフォームで利用可能なわけではありません。このモジュールで定義されているほとんどの関数は、プラットフォーム上の同名の C ライブラリ関数を呼び出します。これらの関数に対する意味付けはプラットフォーム間で異なるため、プラットフォーム提供のドキュメントを読んでおくと便利でしょう。

まずいくつかの用語の説明と慣習について整理します。

The epoch is the point where the time starts, the return value of time.gmtime(0). It is January 1, 1970, 00:00:00 (UTC) on all platforms.

エポック秒 (seconds since the epoch) は、エポックからの総経過秒数を示していますが、たいていはうるう秒 (leap seconds [https://en.wikipedia.org/wiki/Leap_second]) は含まれていません。全ての POSIX 互換のプラットフォームで、うるう秒はこの総秒数には含まれません。

このモジュールの中の関数は、エポック (epoch) 以前あるいは遠い未来の日付や時刻を扱うことができません。将来カットオフ（関数が正しく日付や時刻を扱えなくなる）が起きる時点は、C ライブラリによって決まります。32-bit システムではカットオフは通常 2038 年です。

関数 strptime() は %y 書式コードが与えられた時に 2 桁の年表記を解析できます。2 桁の年を解析する場合、それらは POSIX および ISO C 標準に従って変換されます: 69-99 の西暦年は 1969-1999 となり、0–68 の西暦年は 2000–2068 になります。

UTC は協定世界時 (Coordinated Universal Time) のことです (以前はグリニッジ標準時または GMT として知られていました)。UTC の頭文字の並びは誤りではなく、英仏の妥協によるものです。

DST は夏時間 (Daylight Saving Time) のことで、一年のうちの一定期間に 1 時間タイムゾーンを修正することです。DST のルールは不可思議で (地域ごとに法律で定められています)、年ごとに変わることもあります。C ライブラリはローカルルールを記したテーブルを持っており (柔軟に対応するため、たいていはシステムファイルから読み込まれます)、この点に関しては唯一の真実の知識の源です。

多くの現時刻を返す関数 (real-time functions) の精度は、値や引数を表現するために使う単位から想像されるよりも低いかも知れません。例えば、ほとんどの Unix システムにおいて、クロックの 1 ティックの精度は 50 から 100 分の 1 秒に過ぎません。

On the other hand, the precision of time() and sleep() is better than their Unix equivalents: times are expressed as floating point numbers, time() returns the most accurate time available (using Unix gettimeofday() where available), and sleep() will accept a time with a nonzero fraction (Unix select() is used to implement this, where available).

gmtime(), localtime(), strptime() が返す時刻値、および asctime(), mktime(), strftime() がとる時刻値は 9 個の整数からなるシーケンスです。gmtime(), localtime(), strptime() の戻り値は個々の値を属性名で取得することもできます。

これらのオブジェクトについての解説は struct_time を参照してください。

バージョン 3.3 で変更: The struct_time type was extended to provide the tm_gmtoff and tm_zone attributes when platform supports corresponding struct tm members.

バージョン 3.6 で変更: The struct_time attributes tm_gmtoff and tm_zone are now available on all platforms.

時間の表現を変換するには、以下の関数を利用してください:

対象

変換先

関数

エポックからの秒数

UTC の struct_time

gmtime()

エポックからの秒数

ローカル時間の struct_time

localtime()

UTC の struct_time

エポックからの秒数

calendar.timegm()

ローカル時間の struct_time

エポックからの秒数

mktime()

関数

time.asctime([t])

Convert a tuple or struct_time representing a time as returned by gmtime() or localtime() to a string of the following form: 'Sun Jun 20 23:21:05 1993'. The day field is two characters long and is space padded if the day is a single digit, e.g.: 'Wed Jun  9 04:26:40 1993'.

If t is not provided, the current time as returned by localtime() is used. Locale information is not used by asctime().

注釈

同名の C の関数と違って、asctime() は末尾に改行文字を加えません。

time.pthread_getcpuclockid(thread_id)

Return the clk_id of the thread-specific CPU-time clock for the specified thread_id.

Use threading.get_ident() or the ident attribute of threading.Thread objects to get a suitable value for thread_id.

警告

Passing an invalid or expired thread_id may result in undefined behavior, such as segmentation fault.

利用可能な環境: Unix

更なる情報については pthread_getcpuclockid(3) [https://manpages.debian.org/pthread_getcpuclockid(3)] の man を参照してください。

Added in version 3.7.

time.clock_getres(clk_id)

指定された clk_id クロックの分解能(精度)を返します。 clk_id として受け付けられる値の一覧は Clock ID Constants を参照してください。

利用可能な環境: Unix。

Added in version 3.3.

time.clock_gettime(clk_id) → float

指定された clk_id クロックの時刻を返します。 clk_id として受け付けられる値の一覧は Clock ID Constants を参照してください。

Use clock_gettime_ns() to avoid the precision loss caused by the float type.

利用可能な環境: Unix。

Added in version 3.3.

time.clock_gettime_ns(clk_id) → int

clock_gettime() に似ていますが、ナノ秒単位の時刻を返します。

利用可能な環境: Unix。

Added in version 3.7.

time.clock_settime(clk_id, time: float)

指定された clk_id クロックの時刻を設定します。現在、 CLOCK_REALTIME は clk_id が受け付ける唯一の値です。

Use clock_settime_ns() to avoid the precision loss caused by the float type.

利用可能な環境: Unix。

Added in version 3.3.

time.clock_settime_ns(clk_id, time: int)

clock_settime() に似ていますが、ナノ秒単位の時刻を設定します。

利用可能な環境: Unix。

Added in version 3.7.

time.ctime([secs])

Convert a time expressed in seconds since the epoch to a string of a form: 'Sun Jun 20 23:21:05 1993' representing local time. The day field is two characters long and is space padded if the day is a single digit, e.g.: 'Wed Jun  9 04:26:40 1993'.

secs を指定しないか None を指定した場合、time() が返す値を現在の時刻として使用します。ctime(secs) は asctime(localtime(secs)) と等価です。ローカル情報は ctime() には使用されません。

time.get_clock_info(name)

指定されたクロックの情報を名前空間オブジェクトとして取得します。サポートされているクロック名およびそれらの値を取得する関数は以下の通りです:

'monotonic': time.monotonic()

'perf_counter': time.perf_counter()

'process_time': time.process_time()

'thread_time': time.thread_time()

'time': time.time()

結果は以下の属性をもちます:

adjustable: 自動 (NTP デーモンによるなど) またはシステム管理者による手動で変更できる場合は True、それ以外の場合は False になります。

implementation: クロック値を取得するために内部で使用している C 関数の名前です。使える値については Clock ID Constants を参照してください。

monotonic: クロック値が後戻りすることがない場合 True が、そうでない場合は False になります。

resolution: クロックの分解能を秒 (float) で表します。

Added in version 3.3.

time.gmtime([secs])

エポック (epoch) からの経過時間で表現された時刻を、UTC で struct_time に変換します。このとき dst フラグは常にゼロとして扱われます。secs を指定しないか None を指定した場合、time() が返す値を現在の時刻として使用します。秒の端数は無視されます。struct_time オブジェクトについては前述の説明を参照してください。calendar.timegm() はこの関数と逆の変換を行います。

time.localtime([secs])

gmtime() に似ていますが、ローカル時間に変換します。secs を指定しないか None を指定した場合、time() が返す値を現在の時刻として使用します。DST が適用されている場合は dst フラグには 1 が設定されます。

localtime() may raise OverflowError, if the timestamp is outside the range of values supported by the platform C localtime() or gmtime() functions, and OSError on localtime() or gmtime() failure. It's common for this to be restricted to years between 1970 and 2038.

time.mktime(t)

localtime() の逆を行う関数です。引数は struct_time か 9 個の要素すべての値を持つ完全なタプル (dst フラグも必要です; 時刻に DST が適用されるか不明の場合は -1 を使用してください) で、UTC ではなく ローカル 時間を指定します。戻り値は time() との互換性のために浮動小数点数になります。入力した値を正しい時刻として表現できない場合、例外 OverflowError または ValueError が送出されます (どちらが送出されるかは、無効な値を受け取ったのが Python と下層の C ライブラリのどちらなのかによって決まります)。この関数で時刻を生成できる最も古い日付はプラットフォームに依存します。

time.monotonic() → float

モノトニッククロック、すなわち後戻りしないクロックの値を (小数秒で) 返します。このクロックはシステムクロックの更新の影響を受けません。戻り値の基準点は定義されていないので、二回の呼び出しの結果の差だけが有効です。

Use monotonic_ns() to avoid the precision loss caused by the float type.

Added in version 3.3.

バージョン 3.5 で変更: この関数は、常に利用でき、常にシステム全域で使えるようになりました。

バージョン 3.10 で変更: On macOS, the function is now system-wide.

time.monotonic_ns() → int

monotonic() に似ていますが、ナノ秒単位の時刻を返します。

Added in version 3.7.

time.perf_counter() → float

パフォーマンスカウンター、すなわち短い時間を計測するための可能な限り高い分解能を持つクロックの値を (小数秒で) 返します。これはスリープ中の経過時間を含み、システムワイドです。戻り値の基準点は定義されていないので、二回の呼び出しの結果の差だけが有効です。

Use perf_counter_ns() to avoid the precision loss caused by the float type.

Added in version 3.3.

バージョン 3.10 で変更: On Windows, the function is now system-wide.

time.perf_counter_ns() → int

perf_counter() に似ていますが、ナノ秒単位の時刻を返します。

Added in version 3.7.

time.process_time() → float

現在のプロセスのシステムおよびユーザー CPU 時間の値を (小数秒で) 返します。これはスリープ中の経過時間を含みません。これは定義上プロセスワイドです。戻り値の基準点は定義されていないので、二回の呼び出しの結果の差だけが有効です。

Use process_time_ns() to avoid the precision loss caused by the float type.

Added in version 3.3.

time.process_time_ns() → int

process_time() に似ていますが、ナノ秒単位の時刻を返します。

Added in version 3.7.

time.sleep(secs)

Suspend execution of the calling thread for the given number of seconds. The argument may be a floating point number to indicate a more precise sleep time.

If the sleep is interrupted by a signal and no exception is raised by the signal handler, the sleep is restarted with a recomputed timeout.

The suspension time may be longer than requested by an arbitrary amount, because of the scheduling of other activity in the system.

On Windows, if secs is zero, the thread relinquishes the remainder of its time slice to any other thread that is ready to run. If there are no other threads ready to run, the function returns immediately, and the thread continues execution. On Windows 8.1 and newer the implementation uses a high-resolution timer [https://docs.microsoft.com/en-us/windows-hardware/drivers/kernel/high-resolution-timers] which provides resolution of 100 nanoseconds. If secs is zero, Sleep(0) is used.

Unix implementation:

Use clock_nanosleep() if available (resolution: 1 nanosecond);

Or use nanosleep() if available (resolution: 1 nanosecond);

Or use select() (resolution: 1 microsecond).

バージョン 3.5 で変更: スリープがシグナルに中断されてもシグナルハンドラが例外を送出しない限り、少なくとも secs だけスリープするようになりました (論拠については PEP 475 [https://peps.python.org/pep-0475/] を参照してください)。

バージョン 3.11 で変更: On Unix, the clock_nanosleep() and nanosleep() functions are now used if available. On Windows, a waitable timer is now used.

time.strftime(format[, t])

gmtime() や localtime() が返す時刻値タプルまたは struct_time を、format で指定した文字列形式に変換します。t が与えられていない場合、localtime() が返す値を現在の時刻として使用します。format は文字列でなくてはなりません。t のいずれかのフィールドが許容範囲外の数値であった場合、ValueError を送出します。

0 は時刻タプル内のいずれの位置の引数にも使用できます; それが一般に不正な値であれば、正しい値に強制的に置き換えられます。

format 文字列には以下のディレクティブ (指示語) を埋め込むことができます。これらはフィールド長や精度のオプションを付けずに表され、strftime() の結果の対応する文字列に置き換えられます:

ディレクティブ

意味

注釈

%a

ロケールの短縮された曜日名になります。

%A

ロケールの曜日名になります。

%b

ロケールの短縮された月名になります。

%B

ロケールの月名になります。

%c

ロケールの日時を適切な形式で表します。

%d

月中の日にちの 10 進表記になります [01,31]。

%f

Microseconds as a decimal number

[000000,999999].

(1)

%H

時 (24 時間表記) の 10 進表記になります [00,23]。

%I

時 (12 時間表記) の 10 進表記になります [01,12]。

%j

年中の日にちの 10 進表記になります [001,366]。

%m

月の 10 進表記になります [01,12]。

%M

分の 10 進表記になります [00,59]。

%p

ロケールの AM もしくは PM と等価な文字列になります。

(2)

%S

秒の 10 進表記になります [00,61]。

(3)

%U

年の初めから何週目か (日曜を週の始まりとします) を表す 10 進数になります [00,53]。年が明けてから最初の日曜日までのすべての曜日は 0 週目に属すると見なされます。

(4)

%w

曜日の 10 進表記になります [0 (日曜日),6]。

%W

年の初めから何週目か (月曜を週の始まりとします) を表す 10 進数になります [00,53]。年が明けてから最初の月曜日までの全ての曜日は 0 週目に属すると見なされます。

(4)

%x

ロケールの日付を適切な形式で表します。

%X

ロケールの時間を適切な形式で表します。

%y

西暦の下 2 桁の 10 進表記になります [00,99]。

%Y

西暦 ( 4桁) の 10 進表記を表します。

%z

タイムゾーンと UTC/GMT との時差を表す正または負の時間を +HHMM、-HHMM で表します。H は時間の、M は分の 10 進表記になります [-23:59, +23:59]。 [1]

%Z

タイムゾーンの名前を表します (タイムゾーンがない場合には空文字列)。非推奨です。 [1]

%%

文字 '%' を表します。

注釈:

The %f format directive only applies to strptime(), not to strftime(). However, see also datetime.datetime.strptime() and datetime.datetime.strftime() where the %f format directive applies to microseconds.

strptime() 関数で使う場合、%p ディレクティブが出力結果の時刻フィールドに影響を及ぼすのは、時刻を解釈するために %I を使ったときのみです。

値の幅は実際に 0 から 61 です; 60 は うるう秒<leap seconds> [https://en.wikipedia.org/wiki/Leap_second] を表し、 61 は歴史的理由によりサポートされています。

strptime() 関数で使う場合、%U および %W を計算に使うのは曜日と年を指定したときだけです。

以下に RFC 2822 [https://datatracker.ietf.org/doc/html/rfc2822.html] インターネット電子メール標準で定義されている日付表現と互換の書式の例を示します。 [1]

>>> from time import gmtime, strftime
>>> strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime())
'Thu, 28 Jun 2001 14:17:15 +0000'

一部のプラットフォームではさらにいくつかのディレクティブがサポートされていますが、標準 ANSI C で意味のある値はここで列挙したものだけです。あなたのプラットフォームでサポートされている書式コードの全一覧については、strftime(3) [https://manpages.debian.org/strftime(3)] のドキュメントを参照してください。

一部のプラットフォームでは、フィールドの幅や精度を指定するオプションがディレクティブの先頭の文字 '%' の直後に付けられるようになっていました; この機能も移植性はありません。フィールドの幅は通常 2 ですが、%j は例外で 3 です。

time.strptime(string[, format])

時刻を表現する文字列を書式に従って解釈します。返される値は gmtime() や localtime() が返すような struct_time です。

format パラメーターは strftime() で使うものと同じディレクティブを使います; このパラメーターの値はデフォルトでは "%a %b %d %H:%M:%S %Y" で、ctime() が返すフォーマットに一致します。string が format に従って解釈できなかった場合、例外 ValueError が送出されます。解析しようとする string が解析後に余分なデータを持っていた場合、ValueError が送出されます。欠落したデータについて、適切な値を推測できない場合はデフォルトの値で埋められ、その値は (1900, 1, 1, 0, 0, 0, 0, 1, -1) です。string も format も文字列でなければなりません。

例えば:

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

%Z ディレクティブへのサポートは tzname に収められている値と daylight が真かどうかで決められます。このため、常に既知の (かつ夏時間でないと考えられている) UTC や GMT を認識する時以外はプラットフォーム固有の動作になります。

ドキュメント内で説明されているディレクティブだけがサポートされています。strftime() はプラットフォームごとに実装されているので、説明されていないディレクティブも利用できるかもしれません。しかし、strptime() はプラットフォーム非依存なので、ドキュメント内でサポートされているとされているディレクティブ以外は利用できません。

class time.struct_time

gmtime(), localtime() および strptime() が返す時刻値シーケンスの型です。これは 名前付きタプル のインターフェースをもったオブジェクトです。値はインデックスでも属性名でもアクセス可能です。以下の値があります:

インデックス

属性

値

0

tm_year

(例えば 1993)

1

tm_mon

[1,12] の間の数

2

tm_day

[1,31] の間の数

3

tm_hour

[0,23] の間の数

4

tm_min

[0,59] の間の数

5

tm_sec

range [0, 61]; see Note (2) in strftime()

6

tm_wday

range [0, 6]; Monday is 0

7

tm_yday

[1,366] の間の数

8

tm_isdst

0, 1 または -1; 以下を参照してください

N/A

tm_zone

タイムゾーンの短縮名

N/A

tm_gmtoff

UTC から東方向へのオフセット (秒)

C の構造体とは異なり、月の値は [0, 11] ではなく [1, 12] であることに注意してください。

mktime() の呼び出し時に、tm_isdst は夏時間が有効な場合は 1、そうでない場合は 0 に設定されることがあります。値が -1 の場合は夏時間について不明なことを表していて、普通 tm_isdst は正しい状態に設定されます。

struct_time を引数とする関数に正しくない長さの struct_time や要素の型が正しくない struct_time を与えた場合には、 TypeError が送出されます。

time.time() → float

エポック (epoch) からの秒数を浮動小数点数で返します。うるう秒 (leap seconds [https://en.wikipedia.org/wiki/Leap_second]) の扱いはプラットフォーム依存です。 Windows とほとんどの Unix システムでは、うるう秒はエポック (epoch) 秒の時間の勘定には入りません。これは一般に Unix 時間 [https://en.wikipedia.org/wiki/Unix_time] と呼ばれています。

時刻は常に浮動小数点数で返されますが、すべてのシステムが 1 秒より高い精度で時刻を提供するとは限らないので注意してください。この関数が返す値は通常減少していくことはありませんが、この関数を 2 回呼び出し、その呼び出しの間にシステムクロックの時刻を巻き戻して設定した場合には、以前の呼び出しよりも低い値が返ることがあります。

time() が返す数値は、 gmtime() 関数に渡されて UTC の、あるいは localtime() 関数に渡されて現地時間の、より一般的な時間のフォーマット (つまり、年、月、日、時間など) に変換されているかもしれません。どちらの場合でも struct_time オブジェクトが返され、このオブジェクトの属性としてカレンダー日付の構成要素へアクセスできます。

Use time_ns() to avoid the precision loss caused by the float type.

time.time_ns() → int

time() に似ていますが、時刻を epoch を基点としたナノ秒単位の整数で返します。

Added in version 3.7.

time.thread_time() → float

現在のスレッドのシステムおよびユーザー CPU 時間の値を (小数秒で) 返します。これはスリープ中の経過時間を含みません。これは定義上スレッド固有です。戻り値の基準点は定義されていないので、同一スレッドにおける二回の呼び出しの結果の差だけが有効です。

Use thread_time_ns() to avoid the precision loss caused by the float type.

Availability: Linux, Unix, Windows.

Unix systems supporting CLOCK_THREAD_CPUTIME_ID.

Added in version 3.7.

time.thread_time_ns() → int

thread_time() に似ていますが、ナノ秒単位の時刻を返します。

Added in version 3.7.

time.tzset()

Reset the time conversion rules used by the library routines. The environment variable TZ specifies how this is done. It will also set the variables tzname (from the TZ environment variable), timezone (non-DST seconds West of UTC), altzone (DST seconds west of UTC) and daylight (to 0 if this timezone does not have any daylight saving time rules, or to nonzero if there is a time, past, present or future when daylight saving time applies).

利用可能な環境: Unix。

注釈

多くの場合、環境変数 TZ を変更すると、 tzset() を呼ばない限り localtime() のような関数の出力に影響を及ぼすため、値が信頼できなくなってしまいます。

TZ 環境変数には空白文字を含めてはなりません。

環境変数 TZ の標準的な書式は以下の通りです (分かりやすいように空白を入れています):

std offset [dst [offset [,start[/time], end[/time]]]]

各値は以下のようになっています:

std と dst

三文字またはそれ以上の英数字で、タイムゾーンの略称を与えます。この値は time.tzname になります。

offset

オフセットは形式: ± hh[:mm[:ss]] をとります。この表現は、UTC 時刻にするためにローカルな時間に加算する必要のある時間値を示します。'-' が先頭につく場合、そのタイムゾーンは本初子午線 (Prime Meridian) より東側にあります。それ以外の場合は本初子午線の西側です。オフセットが dst の後ろに続かない場合、夏時間は標準時より一時間先行しているものと仮定します。

start[/time], end[/time]

いつ DST に移動し、DST から戻ってくるかを示します。開始および終了日時の形式は以下のいずれかです:

Jn

ユリウス日 (Julian day) n (1 <= n <= 365) を表します。うるう日は計算に含められないため、2 月 28 日は常に 59 で、3 月 1 日は 60 になります。

n

ゼロから始まるユリウス日 (0 <= n <= 365) です。うるう日は計算に含められるため、2 月 29 日を参照することができます。

Mm.n.d

m 月の週 n における d 番目の日 (0 <= d <= 6, 1 <= n <= 5, 1 <= m <= 12) を表します。週 5 は月 m における最終週の d 番目の日を表し、第 4 週か第 5 週のどちらかになります。週 1 は日 d が最初に現れる日を指します。日 0 は日曜日です。

time は offset とほぼ同じで、先頭に符号 ('-' や '+') を付けてはいけないところだけが違います。時刻が指定されていなければ、デフォルトの値 02:00:00 になります。

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

多くの Unix システム (*BSD, Linux, Solaris, および Darwin を含む) では、システムの zoneinfo (tzfile(5) [https://manpages.debian.org/tzfile(5)]) データベースを使ったほうが、タイムゾーンごとの規則を指定する上で便利です。これを行うには、必要なタイムゾーンデータファイルへのパスをシステムの 'zoneinfo' タイムゾーンデータベースからの相対で表した値を環境変数 TZ に設定します。システムの 'zoneinfo' は通常 /usr/share/zoneinfo にあります。例えば、 'US/Eastern' 、 'Australia/Melbourne' 、 'Egypt' ないし 'Europe/Amsterdam' と指定します。

>>> os.environ['TZ'] = 'US/Eastern'
>>> time.tzset()
>>> time.tzname
('EST', 'EDT')
>>> os.environ['TZ'] = 'Egypt'
>>> time.tzset()
>>> time.tzname
('EET', 'EEST')

Clock ID Constants

These constants are used as parameters for clock_getres() and clock_gettime().

time.CLOCK_BOOTTIME

Identical to CLOCK_MONOTONIC, except it also includes any time that the system is suspended.

This allows applications to get a suspend-aware monotonic clock without having to deal with the complications of CLOCK_REALTIME, which may have discontinuities if the time is changed using settimeofday() or similar.

利用可能な環境: Linux 2.6.39以上。

Added in version 3.7.

time.CLOCK_HIGHRES

Solaris OS は任意のハードウェアソースの使用を試み、ナノ秒レベルの分解能を提供する CLOCK_HIGHRES タイマーを具備しています。CLOCK_HIGHRES は変更不可で、高分解能のクロックです。

利用可能な環境: Solaris。

Added in version 3.3.

time.CLOCK_MONOTONIC

設定不可で、モノトニック時刻 (不特定のエポックからの単調増加な時刻) を表します。

利用可能な環境: Unix。

Added in version 3.3.

time.CLOCK_MONOTONIC_RAW

CLOCK_MONOTONIC と似ていますが、NTP の影響を受けていない、ハードウェアベースの時刻へのアクセスを提供します。

Availability: Linux >= 2.6.28, macOS >= 10.12.

Added in version 3.3.

time.CLOCK_PROCESS_CPUTIME_ID

CPU による高分解能のプロセスごとのタイマーです。

利用可能な環境: Unix。

Added in version 3.3.

time.CLOCK_PROF

CPU による高分解能のプロセスごとのタイマーです。

Availability: FreeBSD, NetBSD >= 7, OpenBSD.

Added in version 3.7.

time.CLOCK_TAI

International Atomic Time [https://www.nist.gov/pml/time-and-frequency-division/nist-time-frequently-asked-questions-faq#tai]

The system must have a current leap second table in order for this to give the correct answer. PTP or NTP software can maintain a leap second table.

利用可能な環境: Linux。

Added in version 3.9.

time.CLOCK_THREAD_CPUTIME_ID

スレッド固有の CPU タイムクロックです。

利用可能な環境: Unix。

Added in version 3.3.

time.CLOCK_UPTIME

Time whose absolute value is the time the system has been running and not suspended, providing accurate uptime measurement, both absolute and interval.

Availability: FreeBSD, OpenBSD >= 5.5.

Added in version 3.7.

time.CLOCK_UPTIME_RAW

Clock that increments monotonically, tracking the time since an arbitrary point, unaffected by frequency or time adjustments and not incremented while the system is asleep.

Availability: macOS >= 10.12.

Added in version 3.8.

The following constant is the only parameter that can be sent to clock_settime().

time.CLOCK_REALTIME

システム全体のリアルタイムクロックです。このクロックを設定するには適切な権限が必要です。

利用可能な環境: Unix。

Added in version 3.3.

Timezone Constants

time.altzone

ローカルの夏時間タイムゾーンにおける UTC からの時刻オフセットで、西に行くほど増加する、秒で表した値です (ほとんどの西ヨーロッパでは負になり、アメリカでは正、イギリスではゼロになります)。daylight がゼロでないときのみ使用してください。以下の注釈を参照してください。

time.daylight

DST タイムゾーンが定義されている場合ゼロでない値になります。以下の注釈を参照してください。

time.timezone

(DST でない) ローカルタイムゾーンの UTC からの時刻オフセットで、西に行くほど増加する秒で表した値です (ほとんどの西ヨーロッパでは負になり、アメリカでは正、イギリスではゼロになります)。以下の注釈を参照してください。

time.tzname

二つの文字列からなるタプルです。最初の要素は DST でないローカルのタイムゾーン名です。ふたつめの要素は DST のタイムゾーンです。DST のタイムゾーンが定義されていない場合。二つ目の文字列を使うべきではありません。以下の注釈を参照してください。

注釈

For the above Timezone constants (altzone, daylight, timezone, and tzname), the value is determined by the timezone rules in effect at module load time or the last time tzset() is called and may be incorrect for times in the past. It is recommended to use the tm_gmtoff and tm_zone results from localtime() to obtain timezone information.

参考

datetime モジュール

日付と時刻に対する、よりオブジェクト指向のインターフェースです。

locale モジュール

国際化サービスです。ロケールの設定は strftime() および strptime() の多くの書式指定子の解釈に影響を及ぼします。

calendar モジュール

一般的なカレンダーに関する関数群です。timegm() はこのモジュールの gmtime() の逆を行う関数です。

脚注

[1] (1,2,3)

%Z の使用は現在非推奨です。ただし、ここで実現したい時間および分オフセットへの展開を行ってくれる %z エスケープはすべての ANSI C ライブラリでサポートされているわけではありません。また、1982 年に提出されたオリジナルの RFC 822 [https://datatracker.ietf.org/doc/html/rfc822.html] 標準では西暦の表現を 2 桁とするよう要求している (%Y でなく %y) ものの、実際には 2000 年になるだいぶ以前から 4 桁の西暦表現に移行しています。その後 RFC 822 [https://datatracker.ietf.org/doc/html/rfc822.html] は撤廃され、4 桁の西暦表現は RFC 1123 [https://datatracker.ietf.org/doc/html/rfc1123.html] で初めて勧告され、RFC 2822 [https://datatracker.ietf.org/doc/html/rfc2822.html] において義務付けられました。

argparse --- Parser for command-line options, arguments and sub-commands

Added in version 3.2.

ソースコード: Lib/argparse.py [https://github.com/python/cpython/tree/3.12/Lib/argparse.py]

チュートリアル

このページは API のリファレンス情報が記載しています。argparse チュートリアル では、コマンドラインの解析についてより優しく説明しています。

argparse モジュールは、ユーザーフレンドリーなコマンドラインインターフェースの作成を簡単にします。プログラムは必要とする引数が何かを定義し、 argparse は sys.argv からそれらの引数を解析する方法を見つけ出します。また、 argparse モジュールはヘルプや使用方法のメッセージを自動的に生成します。さらに、このモジュールはユーザーが不正な引数をプログラムに与えた場合にエラーを発生させます。

中核的な機能

argparse モジュールのコマンドラインインターフェースのサポートは、 argparse.ArgumentParser のインスタンスを中心として構築されています。これは引数の仕様に対するコンテナであり、引数解析器（パーサー）全体に適用されるオプションを持っています:

parser = argparse.ArgumentParser(
                    prog='ProgramName',
                    description='What the program does',
                    epilog='Text at the bottom of help')

ArgumentParser.add_argument() メソッドは各引数の仕様をパーサーに付属させます。このメソッドは位置引数、値を受け取るオプション、機能のオン／オフを切り替えるフラグをサポートします:

parser.add_argument('filename')           # positional argument
parser.add_argument('-c', '--count')      # option that takes a value
parser.add_argument('-v', '--verbose',
                    action='store_true')  # on/off flag

ArgumentParser.parse_args() メソッドはパーサーを実行し、抽出したデータを argparse.Namespace オブジェクト内に配置します:

args = parser.parse_args()
print(args.filename, args.count, args.verbose)

add_argument() のためのクイックリンク

名前

説明

値

action

引数をどのように処理するかを指定します

'store', 'store_const', 'store_true', 'append', 'append_const', 'count', 'help', 'version'

choices

特定の選択肢に値を制限します

['foo', 'bar'], range(1, 10), または Container インスタンス

const

定数値を保存します

default

引数が指定されなかったときに使われるデフォルト値です

特に指定がない場合は None となります

dest

引数解析結果の名前空間で使われる属性名を指定します

help

引数のためのヘルプメッセージです

metavar

ヘルプで表示される、引数の代わりの名前です

nargs

引数として受け取ることのできる数です

int, '?', '*', または '+'

required

その引数が必須か、オプションかを指定します

True または False

type

引数を与えられた型に自動的に変換します

int, float, argparse.FileType('w'), または呼び出し可能な関数

使用例

次のコードは、整数のリストを受け取って合計か最大値を返す Python プログラムです:

import argparse

parser = argparse.ArgumentParser(description='Process some integers.')
parser.add_argument('integers', metavar='N', type=int, nargs='+',
                    help='an integer for the accumulator')
parser.add_argument('--sum', dest='accumulate', action='store_const',
                    const=sum, default=max,
                    help='sum the integers (default: find the max)')

args = parser.parse_args()
print(args.accumulate(args.integers))

上記の Python コードを prog.py という名前のファイルに保存したとすると、このファイルはコマンドラインから実行可能で、次のような有用なヘルプメッセージを提供します:

$ python prog.py -h
usage: prog.py [-h] [--sum] N [N ...]

Process some integers.

positional arguments:
 N           an integer for the accumulator

options:
 -h, --help  show this help message and exit
 --sum       sum the integers (default: find the max)

適切な引数を与えて実行した場合、このプログラムはコマンドライン引数の整数列の合計か最大値を表示します:

$ python prog.py 1 2 3 4
4

$ python prog.py 1 2 3 4 --sum
10

不正な引数が渡されると、エラーが表示されます:

$ python prog.py a b c
usage: prog.py [-h] [--sum] N [N ...]
prog.py: error: argument N: invalid int value: 'a'

以降の節では、この例をひと通り説明して行きます。

パーサーを作る

argparse を使うときの最初のステップは、ArgumentParser オブジェクトを生成することです:

>>> parser = argparse.ArgumentParser(description='Process some integers.')

ArgumentParser オブジェクトはコマンドラインを解析して Python データ型にするために必要なすべての情報を保持します。

引数を追加する

ArgumentParser にプログラム引数の情報を与えるために、add_argument() メソッドを呼び出します。一般的に、このメソッドの呼び出しは ArgumentParser に、コマンドラインの文字列を受け取ってそれをオブジェクトにする方法を教えます。この情報は保存され、parse_args() が呼び出されたときに利用されます。例えば:

>>> parser.add_argument('integers', metavar='N', type=int, nargs='+',
...                     help='an integer for the accumulator')
>>> parser.add_argument('--sum', dest='accumulate', action='store_const',
...                     const=sum, default=max,
...                     help='sum the integers (default: find the max)')

あとで parse_args() を呼び出すと、integers と accumulate という2つの属性を持ったオブジェクトを返します。integers 属性は1つ以上の整数のリストで、accumulate 属性はコマンドラインから --sum が指定された場合は sum() 関数に、それ以外の場合は max() 関数になります。

引数を解析する

ArgumentParser は引数を parse_args() メソッドで解析します。このメソッドはコマンドラインを調べ、各引数を正しい型に変換して、適切なアクションを実行します。ほとんどの場合、これはコマンドラインの解析結果から、シンプルな Namespace オブジェクトを構築することを意味します:

>>> parser.parse_args(['--sum', '7', '-1', '42'])
Namespace(accumulate=<built-in function sum>, integers=[7, -1, 42])

スクリプト内では、parse_args() は通常引数なしで呼び出され、ArgumentParser は自動的に sys.argv からコマンドライン引数を取得します。

ArgumentParser オブジェクト

class 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)

新しい ArgumentParser オブジェクトを生成します。すべての引数はキーワード引数として渡すべきです。各引数についてはあとで詳しく説明しますが、簡単に言うと:

prog - プログラム名(デフォルト: os.path.basename(sys.argv[0]))

usage - プログラムの利用方法を記述する文字列 (デフォルト: パーサーに追加された引数から生成されます)

description - 引数のヘルプの前に表示されるテキスト (デフォルトはテキストなしです)

epilog - 引数のヘルプの後に表示されるテキスト (デフォルトはテキストなしです)

parents - ArgumentParser オブジェクトのリストで、このオブジェクトの引数が追加されます

formatter_class - ヘルプ出力をカスタマイズするためのクラス

prefix_chars - オプションの引数の prefix になる文字集合 (デフォルト: '-')

fromfile_prefix_chars - 追加の引数を読み込むファイルの prefix になる文字集合 (デフォルト: None)

argument_default - 引数のグローバルなデフォルト値 (デフォルト: None)

conflict_handler - 衝突するオプションを解決する方法 (通常は不要)

add_help - -h/--help オプションをパーサーに追加する (デフォルト: True)

allow_abbrev - 長いオプションが先頭文字列に短縮可能 (先頭の文字が一意) である場合に短縮指定を許可する。(デフォルト: True)

exit_on_error - エラーが起きたときに、ArgumentParser がエラー情報を出力して (訳注: プログラムが) 終了する。 (デフォルト: True)

バージョン 3.5 で変更: allow_abbrev 引数が追加されました。

バージョン 3.8 で変更: 以前のバージョンでは、 allow_abbrev は、-vv が -v -v と等価になるような、短いフラグのグループ化を無効にしていました。

バージョン 3.9 で変更: exit_on_error 引数が追加されました。

以下の節では各オプションの利用方法を説明します。

prog

デフォルトでは、ArgumentParser オブジェクトはヘルプメッセージ中に表示するプログラム名を sys.argv[0] から取得します。このデフォルトの動作は、プログラムがコマンドライン上の起動方法に合わせてヘルプメッセージを作成するため、ほとんどの場合望ましい挙動になります。例えば、myprogram.py という名前のファイルに次のコードがあるとします:

import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--foo', help='foo help')
args = parser.parse_args()

このプログラムのヘルプは、プログラム名として (プログラムがどこから起動されたのかに関わらず) myprogram.py を表示します:

$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]

options:
 -h, --help  show this help message and exit
 --foo FOO   foo help
$ cd ..
$ python subdir/myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]

options:
 -h, --help  show this help message and exit
 --foo FOO   foo help

このデフォルトの動作を変更するには、ArgumentParser の prog= 引数に他の値を指定します:

>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.print_help()
usage: myprogram [-h]

options:
 -h, --help  show this help message and exit

プログラム名は、sys.argv[0] から取られた場合でも prog= 引数で与えられた場合でも、ヘルプメッセージ中では %(prog)s フォーマット指定子で利用できます。

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

usage

デフォルトでは、 ArgumentParser は使用法メッセージを、保持している引数から生成します:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', nargs='?', help='foo help')
>>> parser.add_argument('bar', nargs='+', help='bar help')
>>> parser.print_help()
usage: PROG [-h] [--foo [FOO]] bar [bar ...]

positional arguments:
 bar          bar help

options:
 -h, --help   show this help message and exit
 --foo [FOO]  foo help

デフォルトのメッセージは usage= キーワード引数で変更できます:

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

%(prog)s フォーマット指定子を、使用法メッセージ内でプログラム名として利用できます。

description

多くの場合、ArgumentParser のコンストラクターを呼び出すときに description= キーワード引数が使用されます。この引数はプログラムが何をしてどう動くのかについての短い説明になります。ヘルプメッセージで、この説明がコマンドラインの利用法と引数のヘルプメッセージの間に表示されます:

>>> parser = argparse.ArgumentParser(description='A foo that bars')
>>> parser.print_help()
usage: argparse.py [-h]

A foo that bars

options:
 -h, --help  show this help message and exit

デフォルトでは、説明は与えられたスペースに合わせて折り返されます。この挙動を変更するには、formatter_class 引数を参照してください。

epilog

いくつかのプログラムは、プログラムについての追加の説明を引数の説明の後に表示します。このテキストは ArgumentParser の epilog= 引数に指定できます:

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

description 引数と同じく、epilog= テキストもデフォルトで折り返され、ArgumentParser の formatter_class 引数で動作を調整できます。

parents

ときどき、いくつかのパーサーが共通の引数セットを共有することがあります。それらの引数を繰り返し定義する代わりに、すべての共通引数を持ったパーサーを ArgumentParser の parents= 引数に渡すことができます。 parents= 引数は ArgumentParser オブジェクトのリストを受け取り、すべての位置アクションとオプションのアクションをそれらから集め、そのアクションを構築中の ArgumentParser オブジェクトに追加します:

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

一番親になるパーサーに add_help=False を指定していることに注目してください。こうしないと、ArgumentParser は2つの -h/--help オプションを与えられる (1つは親から、もうひとつは子から) ことになり、エラーを発生します。

注釈

parents= に渡す前にパーサーを完全に初期化する必要があります。子パーサーを作成してから親パーサーを変更した場合、その変更は子パーサーに反映されません。

formatter_class

ArgumentParser オブジェクトは代わりのフォーマットクラスを指定することでヘルプのフォーマットをカスタマイズできます。現在、4つのフォーマットクラスがあります:

class argparse.RawDescriptionHelpFormatter

class argparse.RawTextHelpFormatter

class argparse.ArgumentDefaultsHelpFormatter

class argparse.MetavarTypeHelpFormatter

RawDescriptionHelpFormatter と RawTextHelpFormatter はどのようにテキストの説明を表示するかを指定できます。デフォルトでは ArgumentParser オブジェクトはコマンドラインヘルプの中の description と epilog を折り返して表示します:

>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     description='''this description
...         was indented weird
...             but that is okay''',
...     epilog='''
...             likewise for this epilog whose whitespace will
...         be cleaned up and whose words will be wrapped
...         across a couple lines''')
>>> 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

formatter_class= に RawDescriptionHelpFormatter を渡した場合、 description と epilog は整形済みとされ改行されません:

>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     formatter_class=argparse.RawDescriptionHelpFormatter,
...     description=textwrap.dedent('''\
...         Please do not mess up this text!
...         --------------------------------
...             I have indented it
...             exactly the way
...             I want it
...         '''))
>>> 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

RawTextHelpFormatter は引数の説明を含めてすべての種類のヘルプテキストで空白を維持します。例外として、複数の空行はひとつにまとめられます。複数の空白行を保ちたい場合には、行に空白を含めるようにして下さい。

ArgumentDefaultsHelpFormatter は各引数のデフォルト値を自動的にヘルプに追加します:

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

MetavarTypeHelpFormatter は、各引数の値の表示名に type 引数の値を使用します (通常は dest の値が使用されます):

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

prefix_chars

ほとんどのコマンドラインオプションは、-f/--foo のように接頭辞に - を使います。+f や /foo のような、他の、あるいは追加の接頭辞文字をサポートしなければならない場合、ArgumentParser のコンストラクターに prefix_chars= 引数を使って指定します:

>>> 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')

prefix_chars= 引数のデフォルトは '-' です。- を含まない文字セットを指定すると、-f/--foo オプションが使用できなくなります。

fromfile_prefix_chars

ときどき、非常に長い引数リストを扱う場合に、その引数リストを毎回コマンドラインにタイプする代わりにファイルに置いておきたい場合があります。ArgumentParser のコンストラクターに fromfile_prefix_chars= 引数が渡された場合、指定された文字のいずれかで始まる引数はファイルとして扱われ、そのファイルに含まれる引数リストに置換されます。例えば:

>>> 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')

ファイルから読み込まれる引数は、デフォルトでは1行に1つ (ただし、convert_arg_line_to_args() も参照してください) で、コマンドライン上でファイルを参照する引数があった場所にその引数があったものとして扱われます。このため、上の例では、['-f', 'foo', '@args.txt'] は ['-f', 'foo', '-f', 'bar'] と等価になります。

ArgumentParser uses filesystem encoding and error handler to read the file containing arguments.

fromfile_prefix_chars= 引数のデフォルト値は None で、引数がファイル参照として扱われることがないことを意味しています。

バージョン 3.12 で変更: ArgumentParser changed encoding and errors to read arguments files from default (e.g. locale.getpreferredencoding(False) and "strict") to filesystem encoding and error handler. Arguments file should be encoded in UTF-8 instead of ANSI Codepage on Windows.

argument_default

一般的には、引数のデフォルト値は add_argument() メソッドにデフォルト値を渡すか、set_defaults() メソッドに名前と値のペアを渡すことで指定します。しかしまれに、1つのパーサー全体に適用されるデフォルト引数が便利なことがあります。これを行うには、 ArgumentParser に argument_default= キーワード引数を渡します。例えば、全体で parse_args() メソッド呼び出しの属性の生成を抑制するには、argument_default=SUPPRESS を指定します:

>>> 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()

allow_abbrev

通常、ArgumentParser の parse_args() に引数のリストを渡すとき、長いオプションは 短縮しても認識されます。

この機能は、allow_abbrev に False を指定することで無効にできます:

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

Added in version 3.5.

conflict_handler

ArgumentParser オブジェクトは同じオプション文字列に対して複数のアクションを許可していません。デフォルトでは、ArgumentParser オブジェクトは、すでに利用されているオプション文字列を使って新しい引数をつくろうとしたときに例外を送出します:

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

ときどき (例えば parents を利用する場合など)、古い引数を同じオプション文字列で上書きするほうが便利な場合があります。この動作をするには、ArgumentParser の conflict_handler= 引数に 'resolve' を渡します:

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

ArgumentParser オブジェクトは、すべてのオプション文字列が上書きされた場合にだけアクションを削除することに注目してください。上の例では、 --foo オプション文字列だけが上書きされているので、古い -f/--foo アクションは -f アクションとして残っています。

add_help

デフォルトでは、ArgumentParser オブジェクトはシンプルにパーサーのヘルプメッセージを表示するオプションを自動的に追加します。例えば、以下のコードを含む myprogram.py ファイルについて考えてください:

import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--foo', help='foo help')
args = parser.parse_args()

コマンドラインに -h か --help が指定された場合、ArgumentParser の help が表示されます:

$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]

options:
 -h, --help  show this help message and exit
 --foo FOO   foo help

必要に応じて、この help オプションを無効にする場合があります。これは ArgumentParser の add_help= 引数に False を渡すことで可能です:

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

ヘルプオプションは通常 -h/--help です。例外は prefix_chars= が指定されてその中に - が無かった場合で、その場合は -h と --help は有効なオプションではありません。この場合、prefix_chars の最初の文字がヘルプオプションの接頭辞として利用されます:

>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')
>>> parser.print_help()
usage: PROG [+h]

options:
  +h, ++help  show this help message and exit

exit_on_error

通常、不正な引数リストが ArgumentParser の parse_args() メソッドに渡された場合、プログラムはエラー情報を出力して終了します。

もしエラーを例外としてプログラム内でキャッチしたい場合は、exit_on_error を False に設定してください:

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

Added in version 3.9.

add_argument() メソッド

ArgumentParser.add_argument(name or flags...[, action][, nargs][, const][, default][, type][, choices][, required][, help][, metavar][, dest])

1つのコマンドライン引数がどう解析されるかを定義します。各引数についての詳細は後述しますが、簡単に言うと:

name または flags - 名前か、あるいはオプション文字列のリスト (例: foo や -f, --foo)。

action - コマンドラインにこの引数があったときのアクション。

nargs - 受け取るべきコマンドライン引数の数。

const - 一部の action と nargs の組み合わせで利用される定数。

default - コマンドラインに対応する引数が存在せず、さらに namespace オブジェクトにも存在しない場合に利用される値。

type - コマンドライン引数が変換されるべき型。

choices - 引数として許される値のシーケンス。

required - コマンドラインオプションが省略可能かどうか (オプション引数のみ)。

help - 引数が何なのかを示す簡潔な説明。

metavar - 使用法メッセージの中で使われる引数の名前。

dest - parse_args() が返すオブジェクトに追加される属性名。

以下の節では各オプションの利用方法を説明します。

name または flags

add_argument() メソッドは、指定されている引数が -f や --foo のようなオプション引数なのか、ファイル名リストなどの位置引数なのかを知る必要があります。そのため、 add_argument() に初めに渡される引数は、一連のフラグか、単一の引数名のどちらかになります。

たとえば、オプション引数は次のように作成します:

>>> parser.add_argument('-f', '--foo')

一方、位置引数は次のように作成します:

>>> parser.add_argument('bar')

parse_args() が呼ばれたとき、オプション引数は接頭辞 - により識別され、それ以外の引数は位置引数として扱われます:

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

action

ArgumentParser オブジェクトはコマンドライン引数にアクションを割り当てます。このアクションは、割り当てられたコマンドライン引数に関してどんな処理でもできますが、ほとんどのアクションは単に parse_args() が返すオブジェクトに属性を追加するだけです。action キーワード引数は、コマンドライン引数がどう処理されるかを指定します。提供されているアクションは:

'store' - これは単に引数の値を格納します。これはデフォルトのアクションです。例えば:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.parse_args('--foo 1'.split())
Namespace(foo='1')

'store_const' - このアクションは const キーワード引数で指定された値を格納します。const キーワード引数のデフォルト値は None であることに注意してください。'store_const' アクションは、何かの種類のフラグを指定するオプション引数によく使われます。例えば:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_const', const=42)
>>> parser.parse_args(['--foo'])
Namespace(foo=42)

'store_true', 'store_false' - これらは 'store_const' の、それぞれ True と False を格納する特別版になります。加えて、これらはそれぞれデフォルト値を順に False と True にします。例えば:

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

'append' - このアクションはリストを格納し、それぞれの引数として与えられた値をリストに追加します。これは複数回指定可能なオプション引数に対して有用です。デフォルト値が空でない場合、デフォルト値は常にパースされたリストに含まれ、コマンドラインで指定した値はデフォルト値の後に追加されます。使用例:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='append')
>>> parser.parse_args('--foo 1 --foo 2'.split())
Namespace(foo=['1', '2'])

'append_const' - このアクションはリストを格納して、const キーワード引数に与えられた値をそのリストに追加します。const キーワード引数のデフォルト値は None であることに注意してください。'append_const' アクションは、定数を同じリストに複数回格納する場合に便利です。例えば:

>>> 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'>])

'count' - このアクションはキーワード引数の数を数えます。例えば、verboseレベルを上げるのに役立ちます:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--verbose', '-v', action='count', default=0)
>>> parser.parse_args(['-vvv'])
Namespace(verbose=3)

default は明示的に 0 と指定されない場合は None であることに注意してください。

'help' - このアクションは現在のパーサー中のすべてのオプションのヘルプメッセージを表示し、終了します。出力の生成方法の詳細については ArgumentParser を参照してください。

'version' - このアクションは add_argument() の呼び出しに version= キーワード引数を期待します。指定されたときはバージョン情報を表示して終了します:

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

'extend' - このアクションはリストを格納して、各引数の値でそのリストを拡張します。利用例:

>>> 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'])

Added in version 3.8.

また、Action のサブクラス、またはそれと同じインターフェースを実装するオブジェクトを渡すことにより、任意のアクションを指定することができます。例えば argparse モジュールには BooleanOptionalAction があり、--foo や --no-foo のようなオプションに対して真偽値を設定するアクションをサポートしています:

>>> import argparse
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action=argparse.BooleanOptionalAction)
>>> parser.parse_args(['--no-foo'])
Namespace(foo=False)

Added in version 3.9.

カスタムアクションを作成する推奨の方法は、Action クラスを継承し、__call__ メソッド (および、任意で __init__ および format_usage メソッド) をオーバーライドすることです。

カスタムアクションの例です:

>>> 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')

詳細は Action を参照してください。

nargs

ArgumentParser オブジェクトは通常1つのコマンドライン引数を1つのアクションに渡します。nargs キーワード引数は1つのアクションにそれ以外の数のコマンドライン引数を割り当てます。多義性のある引数の指定 を参照してください。指定できる値は:

N (整数) -- N 個の引数がコマンドラインから集められ、リストに格納されます。例えば:

>>> 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'])

nargs=1 は1要素のリストを作ることに注意してください。これはデフォルトの、要素がそのまま属性になる動作とは異なります。

'?' -- 可能なら1つの引数がコマンドラインから取られ、1つのアイテムを作ります。コマンドライン引数が存在しない場合、default の値が生成されます。オプション引数の場合、さらにオプション引数が指定され、その後にコマンドライン引数がないというケースもありえます。この場合は const の値が生成されます。この動作の例です:

>>> 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')

nargs='?' のよくある利用例の1つは、入出力ファイルの指定オプションです:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('infile', nargs='?', type=argparse.FileType('r'),
...                     default=sys.stdin)
>>> parser.add_argument('outfile', nargs='?', type=argparse.FileType('w'),
...                     default=sys.stdout)
>>> parser.parse_args(['input.txt', 'output.txt'])
Namespace(infile=<_io.TextIOWrapper name='input.txt' encoding='UTF-8'>,
          outfile=<_io.TextIOWrapper name='output.txt' encoding='UTF-8'>)
>>> parser.parse_args([])
Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>,
          outfile=<_io.TextIOWrapper name='<stdout>' encoding='UTF-8'>)

'*' -- すべてのコマンドライン引数がリストに集められます。複数の位置引数が nargs='*' を持つことにあまり意味はありませんが、複数のオプション引数が nargs='*' を持つことはありえます。例えば:

>>> 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'])

'+' -- '*' と同じように、すべてのコマンドライン引数をリストに集めます。加えて、最低でも1つのコマンドライン引数が存在しない場合にエラーメッセージを生成します。例えば:

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

nargs キーワード引数が指定されない場合、受け取る引数の数は action によって決定されます。通常これは、1つのコマンドライン引数は1つのアイテムになる (リストにはならない) ことを意味します。

const

add_argument() の const 引数は、コマンドライン引数から読み込まれないけれども ArgumentParser のいくつかのアクションで必要とされる値のために使われます。この引数のよくある2つの使用法は:

add_argument() が action='store_const' か action='append_const' で呼び出されたとき、これらのアクションは const の値を parse_args() が返すオブジェクトの属性に追加します。サンプルは action の説明を参照してください。const が add_argument() に与えられなければ、None のデフォルト値を受け取ります。

add_argument() がオプション文字列 (-f や --foo) と nargs='?' で呼び出された場合。この場合0個か1つのコマンドライン引数を取るオプション引数が作られます。オプション引数にコマンドライン引数が続かなかった場合、代わりに const の値が None であると見なされます。サンプルは nargs の説明を参照してください。

バージョン 3.11 で変更: action='append_const' や action='store_const' の場合も含め、デフォルトでは const=None です。

default

すべてのオプション引数といくつかの位置引数はコマンドライン上で省略されることがあります。 add_argument() の default キーワード引数 (デフォルト: None) は、コマンドライン引数が存在しなかった場合に利用する値を指定します。オプション引数では、オプション文字列がコマンドライン上に存在しなかったときに default の値が利用されます:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=42)
>>> parser.parse_args(['--foo', '2'])
Namespace(foo='2')
>>> parser.parse_args([])
Namespace(foo=42)

対象となる namespace がすでにその属性を持っている場合、それは default の値では上書きされません:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=42)
>>> parser.parse_args([], namespace=argparse.Namespace(foo=101))
Namespace(foo=101)

default の値が文字列の場合、パーサーは値をコマンドライン引数のように解析します。具体的には、パーサーは返り値 Namespace の属性を設定する前に、type 変換引数が与えられていればそれらを適用します。そうでない場合、パーサーは値をそのまま使用します:

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

nargs が ? か * である位置引数では、コマンドライン引数が指定されなかった場合 default の値が使われます。例えば:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', nargs='?', default=42)
>>> parser.parse_args(['a'])
Namespace(foo='a')
>>> parser.parse_args([])
Namespace(foo=42)

default=argparse.SUPPRESS を渡すと、コマンドライン引数が存在しないときに属性の追加をしなくなります:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=argparse.SUPPRESS)
>>> parser.parse_args([])
Namespace()
>>> parser.parse_args(['--foo', '1'])
Namespace(foo='1')

type

デフォルトでは、パーサーはコマンドライン引数を単なる文字列として読み込みます。しかし、それらの文字列を float, int など別の型として扱うべき事がよくあります。add_argument() の type キーワード引数に指定する type converter により、必要な型チェックと型変換を行うことができます。

もし type キーワードが default キーワードとともに使用された場合、default の値が文字列のときのみ、type converter による変換などが行われます。

type キーワードの引数として、単一の文字列を受け取るような任意の呼び出しオブジェクト (callable) が使用できます。もし呼び出しが ArgumentTypeError, TypeError, または ValueError 型の例外を送出した場合は、parser がそれをキャッチして適切なエラーメッセージが表示されます。それ以外の型の例外は処理されません。

一般的なビルトインデータ型や関数を type 引数の値として直接指定できます:

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('source_file', type=open)
parser.add_argument('dest_file', type=argparse.FileType('w', encoding='latin-1'))
parser.add_argument('datapath', type=pathlib.Path)

ユーザが定義した関数も使用できます:

>>> 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')

Type converter として bool() 関数を使用することは推奨されません。なぜなら、これは空文字列を False に、それ以外の全てを True に変換しますが、これはおそらく望まれる動作ではないからです (訳注: 文字列 'false' を False に変換してくれたりはしません)。

一般論として、type キーワードに指定するものは、せいぜい上記の3種類の例外を発生するくらいの、お手軽な変換に限るべきです。より複雑な (interesting) エラー処理、またはリソース管理を伴うものは、引数を解析したあとに別個の処理として行うべきです。

たとえば、JSON または YAML からの変換は複雑なエラーケースを持つので、type がサポートする以上のエラー表示を必要とするでしょう。(JSON デコーダが発生しうる) JSONDecodeError は適切に整形されて表示されません。また、FileNotFoundError が発生しても parser は何も処理しません。

また、type キーワードに FileType を指定した場合には制限があります。ある引数に FileType を指定してファイルが開かれ、その後ろのどこかの引数で処理が失敗した場合、エラーが表示されますが、開かれたファイルは自動では close されません。これを好まない場合は、parser による引数の処理が終わるまで待ち、その後に with 文などでファイルを開くのがよいでしょう。

なお、引数が、あらかじめ決められた値の候補のいずれかに一致するかをチェックしたいだけの場合には、代わりに choices キーワードの使用を検討してください。

choices

コマンドライン引数をいくつかの選択肢の中から選ばせたい場合があります。 これは add_argument() に シーケンスオブジェクトを choices キーワード引数として渡すことで可能です。コマンドラインを解析するとき、引数の値がチェックされ、その値が選択肢の中に含まれていない場合はエラーメッセージを表示します:

>>> 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')

choices シーケンスに含まれているかどうかのチェックは、type による型変換が実行された後であることに注意してください。このため、choices シーケンス中のオブジェクトの型は指定された type にマッチしている必要があります:

>>> parser = argparse.ArgumentParser(prog='doors.py')
>>> parser.add_argument('door', type=int, choices=range(1, 4))
>>> print(parser.parse_args(['3']))
Namespace(door=3)
>>> parser.parse_args(['4'])
usage: doors.py [-h] {1,2,3}
doors.py: error: argument door: invalid choice: 4 (choose from 1, 2, 3)

任意のシーケンスを choices に渡すことができます。すなわち、list オブジェクト、 class:tuple オブジェクト、カスタムシーケンスはすべてサポートされています。

ただし、enum.Enum を渡すことは推奨されません。使用方法、ヘルプ、エラーメッセージなどでどのように表示されるかを制御することが難いからです。

ヘルプテキストにおいて整形された choices の値は、通常 dest から生成されるデフォルトの metavar に優先します。ユーザーは dest パラメータを目にすることがないため、この振る舞いは基本的には望ましいものです。もしこの表示方法が望ましくない場合 (おそらく多くの選択肢がある場合など) は、 metavar を明示的に指定してください。

required

通常 argparse モジュールは、-f や --bar といったフラグは 任意 の引数 (オプション引数) だと仮定し、コマンドライン上になくても良いものとして扱います。フラグの指定を 必須 にするには、add_argument() の required= キーワード引数に True を指定します:

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

上の例のように、引数が required と指定されると、parse_args() はそのフラグがコマンドラインに存在しないときにエラーを表示します。

注釈

ユーザーは、通常 フラグ の指定は 任意 であると認識しているため、必須にするのは一般的には悪いやり方で、できる限り避けるべきです。

help

help の値はその引数の簡潔な説明を含む文字列です。ユーザーが (コマンドライン上で -h か --help を指定するなどして) ヘルプを要求したとき、この help の説明が各引数に表示されます:

>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('--foo', action='store_true',
...                     help='foo the bars before frobbling')
>>> parser.add_argument('bar', nargs='+',
...                     help='one of the bars to be frobbled')
>>> parser.parse_args(['-h'])
usage: frobble [-h] [--foo] bar [bar ...]

positional arguments:
 bar     one of the bars to be frobbled

options:
 -h, --help  show this help message and exit
 --foo   foo the bars before frobbling

help 文字列には、プログラム名や引数の default などを繰り返し記述するのを避けるためのフォーマット指定子を含めることができます。利用できる指定子には、プログラム名 %(prog)s と、 %(default)s や %(type)s など add_argument() のキーワード引数の多くが含まれます:

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

ヘルプ文字列は %-フォーマットをサポートしているので、ヘルプ文字列内にリテラル % を表示したい場合は %% のようにエスケープしなければなりません。

argparse は help に argparse.SUPPRESS を設定することで、特定のオプションをヘルプに表示させないことができます:

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

metavar

ArgumentParser がヘルプメッセージを出力するとき、各引数に対してなんらかの参照方法が必要です。デフォルトでは、 ArgumentParser オブジェクトは各オブジェクトの "名前" として dest を利用します。デフォルトでは、位置引数には dest の値をそのまま 利用し、オプション引数については dest の値を大文字に変換して利用します。このため、1つの dest='bar' である位置引数は bar として参照されます。 1つのオプション引数 --foo が1つのコマンドライン引数を要求するときは、その引数は FOO として参照されます。以下に例を示します:

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

代わりの名前を、metavar として指定できます:

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

metavar は 表示される 名前だけを変更することに注意してください。parse_args() の返すオブジェクトの属性名は dest の値のままです。

nargs を指定した場合、metavar が複数回利用されるかもしれません。metavar にタプルを渡すと、各引数に対して異なる名前を指定できます:

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

dest

ほとんどの ArgumentParser のアクションは parse_args() が返すオブジェクトに対する属性として値を追加します。この属性の名前は add_argument() の dest キーワード引数によって決定されます。位置引数のアクションについては、 dest は通常 add_argument() の第一引数として渡します:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('bar')
>>> parser.parse_args(['XXX'])
Namespace(bar='XXX')

オプション引数のアクションについては、 dest の値は通常オプション文字列から生成されます。 ArgumentParser は最初の長いオプション文字列を選択し、先頭の -- を除去することで dest の値を生成します。長いオプション文字列が指定されていない場合、最初の短いオプション文字列から先頭の - 文字を除去することで dest を生成します。先頭以外のすべての - 文字は、妥当な属性名になるように _ 文字へ変換されます。次の例はこの動作を示しています:

>>> 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')

dest にカスタムの属性名を与えることも可能です:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', dest='bar')
>>> parser.parse_args('--foo XXX'.split())
Namespace(bar='XXX')

Action クラス

Acrtion クラスは Action API、すなわちコマンドラインからの引数を処理する呼び出し可能オブジェクトを返す呼び出し可能オブジェクトを実装します。この API に従うあらゆるオブジェクトは action 引数として add_argument() に渡すことができます。

class argparse.Action(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

Action オブジェクトは、コマンドラインからの一つ以上の文字列から単一の引数を解析するのに必要とされる情報を表現するために ArgumentParser によって使われます。Action クラス 2 つの位置引数と、action それ自身を除く ArgumentParser.add_argument() に渡されるすべてのキーワード引数を受け付けなければなりません。

Action のインスタンス (あるいは action 引数に渡す任意の呼び出し可能オブジェクトの返り値) は、属性 "dest", "option_strings", "default", "type", "required", "help", などを定義しなければなりません。これらの属性を定義するのを確実にするためにもっとも簡単な方法は、Action.__init__ を呼び出すことです。

Action インスタンスは呼び出し可能でなければならず、したがって、サブクラスは 4 つの引数を受け取る __call__ メソッドをオーバライドしなければなりません:

parser - このアクションを持っている ArgumentParser オブジェクト。

namespace - parse_args() が返す Namespace オブジェクト。ほとんどのアクションはこのオブジェクトに属性を setattr() を使って追加します。

values - 型変換が適用された後の、関連付けられたコマンドライン引数。型変換は add_argument() メソッドの type キーワード引数で指定されます。

option_string - このアクションを実行したオプション文字列。option_string 引数はオプションで、アクションが位置引数に関連付けられた場合は渡されません。

__call__ メソッドでは任意のアクションを行えます。典型的には dest および values に基いて namespace に属性をセットします。

Action のサブクラスを定義する際に format_usage メソッドを実装することができます。このメソッドは引数を受け取らず、プログラムの使用方法 (usage) を表示する際に使われる文字列を返すようにします。このメソッドが実装されていない場合は、sensible default (訳注: システムにより上手く設定されたデフォルト値) が使われます。

parse_args() メソッド

ArgumentParser.parse_args(args=None, namespace=None)

引数の文字列をオブジェクトに変換し、namespace オブジェクトの属性に代入します。結果の namespace オブジェクトを返します。

事前の add_argument() メソッドの呼び出しにより、どのオブジェクトが生成されてどう代入されるかが決定されます。詳細は add_argument() のドキュメントを参照してください。

args - 解析する文字列のリスト。デフォルトでは sys.argv から取得されます。

namespace - 属性を代入するオブジェクト。デフォルトでは、新しい空の Namespace オブジェクトです。

オプション値の文法

parse_args() メソッドは、オプションの値がある場合、そのオプションの値の指定に複数の方法をサポートしています。もっとも単純な場合には、オプションとその値は次のように2つの別々の引数として渡されます:

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

長いオプション (1文字よりも長い名前を持ったオプション) では、オプションとその値は次のように = で区切られた1つのコマンドライン引数として渡すこともできます:

>>> parser.parse_args(['--foo=FOO'])
Namespace(foo='FOO', x=None)

短いオプション (1文字のオプション) では、オプションとその値は次のように連結して渡すことができます:

>>> parser.parse_args(['-xX'])
Namespace(foo=None, x='X')

最後の1つのオプションだけが値を要求する場合、または値を要求するオプションがない場合、複数の短いオプションは次のように1つの接頭辞 - だけで連結できます:

>>> 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')

不正な引数

parse_args() は、コマンドラインの解析中に、曖昧なオプション、不正な型、不正なオプション、位置引数の数の不一致などのエラーを検証します。それらのエラーが発生した場合、エラーメッセージと使用法メッセージを表示して終了します:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', type=int)
>>> parser.add_argument('bar', nargs='?')

>>> # invalid type
>>> parser.parse_args(['--foo', 'spam'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: argument --foo: invalid int value: 'spam'

>>> # invalid option
>>> parser.parse_args(['--bar'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: no such option: --bar

>>> # wrong number of arguments
>>> parser.parse_args(['spam', 'badger'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: extra arguments found: badger

- を含む引数

parse_args() メソッドは、ユーザーが明らかなミスをした場合はエラーを表示しますが、いくつか本質的に曖昧な場面があります。例えば、コマンドライン引数 -1 は、オプションの指定かもしれませんし位置引数かもしれません。parse_args() メソッドはこれを次のように扱います: 負の数として解釈でき、パーサーに負の数のように解釈できるオプションが存在しない場合にのみ、- で始まる位置引数になりえます:

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

- で始まる位置引数があって、それが負の数として解釈できない場合、ダミーの引数 '--' を挿入して、parse_args() にそれ以降のすべてが位置引数だと教えることができます:

>>> parser.parse_args(['--', '-f'])
Namespace(foo='-f', one=None)

See also the argparse howto on ambiguous arguments for more details.

引数の短縮形 (先頭文字でのマッチング)

parse_args() メソッドは、デフォルトで、長いオプションに曖昧さがない (先頭文字列が一意である) かぎり、先頭文字列に短縮して指定できます:

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

先頭の文字が同じ引数が複数ある場合に短縮指定を行うとエラーを発生させます。この機能は allow_abbrev に False を指定することで無効にできます。

sys.argv 以外

ArgumentParser が sys.argv 以外の引数を解析できると役に立つ場合があります。その場合は文字列のリストを parse_args() に渡します。これはインタラクティブプロンプトからテストするときに便利です:

>>> 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])

Namespace オブジェクト

class argparse.Namespace

parse_args() が属性を格納して返すためのオブジェクトにデフォルトで使用されるシンプルなクラスです。

このクラスはシンプルに設計されており、単に読みやすい文字列表現を持った object のサブクラスです。もし属性を辞書のように扱える方が良ければ、標準的な Python のイディオム vars() を利用できます:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> args = parser.parse_args(['--foo', 'BAR'])
>>> vars(args)
{'foo': 'BAR'}

ArgumentParser が、新しい Namespace オブジェクトではなく、既存のオブジェクトに属性を設定する方が良い場合があります。これは namespace= キーワード引数を指定することで可能です:

>>> class C:
...     pass
...
>>> c = C()
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.parse_args(args=['--foo', 'BAR'], namespace=c)
>>> c.foo
'BAR'

その他のユーティリティ

サブコマンド

ArgumentParser.add_subparsers([title][, description][, prog][, parser_class][, action][, option_strings][, dest][, required][, help][, metavar])

多くのプログラムは、その機能をサブコマンドへと分割します。 例えば svn プログラムは svn checkout, svn update, svn commit などのサブコマンドを利用できます。 機能をサブコマンドに分割するのは、プログラムがいくつかの異なった機能を持っていて、 それぞれが異なるコマンドライン引数を必要とする場合には良いアイデアです。 ArgumentParser は add_subparsers() メソッドによりサブコマンドを サポートしています。 add_subparsers() メソッドは通常引数なしに呼び出され、 特殊なアクションオブジェクトを返します。このオブジェクトには1つのメソッド add_parser() があり、コマンド名と ArgumentParser コンストラクターの任意の引数を受け取り、通常の方法で操作できる ArgumentParser オブジェクトを返します。

引数の説明:

title - ヘルプ出力でのサブパーサーグループのタイトルです。デフォルトは、description が指定されている場合は "subcommands" に、指定されていない場合は位置引数のタイトルになります

description - ヘルプ出力に表示されるサブパーサーグループの説明です。デフォルトは None になります

prog - サブコマンドのヘルプに表示される使用方法の説明です。デフォルトではプログラム名と位置引数の後ろに、サブパーサーの引数が続きます

parser_class - サブパーサーのインスタンスを作成するときに使用されるクラスです。デフォルトでは現在のパーサーのクラス (例: ArgumentParser) になります

action - コマンドラインにこの引数があったときの基本のアクション。

dest - サブコマンド名を格納する属性の名前です。デフォルトは None で値は格納されません

required - サブコマンドが必須であるかどうかを指定し、デフォルトは False です。(3.7 より追加)

help - ヘルプ出力に表示されるサブパーサーグループのヘルプです。デフォルトは None です

metavar - 利用可能なサブコマンドをヘルプ内で表示するための文字列です。デフォルトは None で、サブコマンドを {cmd1, cmd2, ..} のような形式で表します

いくつかの使用例:

>>> # 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='sub-command 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='XYZ', 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)

parse_args() が返すオブジェクトにはメインパーサーとコマンドラインで選択されたサブパーサーによる属性だけが設定されており、選択されなかったサブコマンドのパーサーの属性が設定されていないことに注意してください。このため、上の例では、a コマンドが指定されたときは foo, bar 属性だけが存在し、b コマンドが指定されたときは foo, baz 属性だけが存在しています。

同じように、サブパーサーにヘルプメッセージが要求された場合は、そのパーサーに対するヘルプだけが表示されます。ヘルプメッセージには親パーサーや兄弟パーサーのヘルプメッセージを表示しません。 (ただし、各サブパーサーコマンドのヘルプメッセージは、上の例にもあるように add_parser() の help= 引数によって指定できます)

>>> parser.parse_args(['--help'])
usage: PROG [-h] [--foo] {a,b} ...

positional arguments:
  {a,b}   sub-command 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

add_subparsers() メソッドは title と description キーワード引数もサポートしています。どちらかが存在する場合、サブパーサーのコマンドはヘルプ出力でそれぞれのグループの中に表示されます。例えば:

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

Furthermore, add_parser supports an additional aliases argument, which allows multiple strings to refer to the same subparser. This example, like svn, aliases co as a shorthand for checkout:

>>> 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')

サブコマンドを扱う1つの便利な方法は add_subparsers() メソッドと set_defaults() を組み合わせて、各サブパーサーにどの Python 関数を実行するかを教えることです。例えば:

>>> # sub-command 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))

こうすると、parse_args() が引数の解析が終わってから適切な関数を呼び出すようになります。このように関数をアクションに関連付けるのは一般的にサブパーサーごとに異なるアクションを扱うもっとも簡単な方法です。ただし、実行されたサブパーサーの名前を確認する必要がある場合は、add_subparsers() を呼び出すときに dest キーワードを指定できます:

>>> 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')

バージョン 3.7 で変更: 新しい required キーワード引数。

FileType オブジェクト

class argparse.FileType(mode='r', bufsize=-1, encoding=None, errors=None)

FileType ファクトリは ArgumentParser.add_argument() の type 引数に渡すことができるオブジェクトを生成します。 type が FileType オブジェクトである引数はコマンドライン引数を、指定されたモード、バッファーサイズ、エンコーディング、エラー処理でファイルとして開きます (詳細は open() 関数を参照してください。):

>>> 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'>)

FileType オブジェクトは擬似引数 '-' を識別し、読み込み用の FileType であれば sys.stdin を、書き込み用の FileType であれば sys.stdout に変換します:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('infile', type=argparse.FileType('r'))
>>> parser.parse_args(['-'])
Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>)

バージョン 3.4 で変更: encodings と errors がパラメータに追加されました。

引数グループ

ArgumentParser.add_argument_group(title=None, description=None)

デフォルトでは、 ArgumentParser はヘルプメッセージを表示するときに、コマンドライン引数を "位置引数" と "オプション" にグループ化します。このデフォルトの動作よりも良い引数のグループ化方法がある場合、 add_argument_group() メソッドで適切なグループを作成できます:

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

add_argument_group() メソッドは、通常の ArgumentParser と同じような add_argument() メソッドを持つ引数グループオブジェクトを返します。引数がグループに追加された時、パーサーはその引数を通常の引数のように扱いますが、ヘルプメッセージではその引数を分離されたグループの中に表示します。 add_argument_group() メソッドには、この表示をカスタマイズするための title と description 引数があります:

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

ユーザー定義グループにないすべての引数は通常の "位置引数" と "オプション引数" セクションに表示されます。

バージョン 3.11 で変更: 引数グループについて add_argument_group() を呼び出すことは非推奨です。この機能はこれまでサポートされたことはなく、常に正しく動作するとは限りません。この関数は継承を通じて思いがけず API に存在することになったもので、将来削除される予定です。

相互排他

ArgumentParser.add_mutually_exclusive_group(required=False)

相互排他グループを作ります。argparse は相互排他グループの中でただ1つの引数のみが存在することを確認します:

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

add_mutually_exclusive_group() メソッドの引数 required に True 値を指定すると、その相互排他引数のどれか1つを選ぶことが要求されます:

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

Note that currently mutually exclusive argument groups do not support the title and description arguments of add_argument_group(). However, a mutually exclusive group can be added to an argument group that has a title and description. For 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

バージョン 3.11 で変更: 相互排他グループについて add_argument_group() や add_mutually_exclusive_group() を呼び出すことは非推奨です。これらの機能はこれまで一度もサポートされたことがなく、常に正しく動作するとは限りません。これらの関数は継承により偶然 API に存在することになったもので、将来削除される予定です。

パーサーのデフォルト値

ArgumentParser.set_defaults(**kwargs)

ほとんどの場合、 parse_args() が返すオブジェクトの属性はコマンドライン引数の内容と引数のアクションによってのみ決定されます。 set_defaults() を使うと与えられたコマンドライン引数の内容によらず追加の属性を決定することが可能です:

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

パーサーレベルのデフォルト値は常に引数レベルのデフォルト値を上書きします:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default='bar')
>>> parser.set_defaults(foo='spam')
>>> parser.parse_args([])
Namespace(foo='spam')

パーサーレベルの default は、複数のパーサーを扱うときに特に便利です。このタイプの例については add_subparsers() メソッドを参照してください。

ArgumentParser.get_default(dest)

add_argument() か set_defaults() によって指定された、 namespace の属性のデフォルト値を取得します:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default='badger')
>>> parser.get_default('foo')
'badger'

ヘルプの表示

ほとんどの典型的なアプリケーションでは、parse_args() が使用法やエラーメッセージのフォーマットと表示について面倒を見ます。しかし、いくつかのフォーマットメソッドが利用できます:

ArgumentParser.print_usage(file=None)

ArgumentParser がコマンドラインからどう実行されるべきかの短い説明を表示します。 file が None の時は、 sys.stdout に出力されます。

ArgumentParser.print_help(file=None)

プログラムの使用法と ArgumentParser に登録された引数についての情報を含むヘルプメッセージを表示します。 file が None の時は、 sys.stdout に出力されます。

これらのメソッドの、表示する代わりにシンプルに文字列を返すバージョンもあります:

ArgumentParser.format_usage()

ArgumentParser がコマンドラインからどう実行されるべきかの短い説明を格納した文字列を返します。

ArgumentParser.format_help()

プログラムの使用法と ArgumentParser に登録された引数についての情報を含むヘルプメッセージを格納した文字列を返します。

部分解析

ArgumentParser.parse_known_args(args=None, namespace=None)

ときどき、スクリプトがコマンドライン引数のいくつかだけを解析し、残りの引数は別のスクリプトやプログラムに渡すことがあります。こういった場合、 parse_known_args() メソッドが便利です。これは parse_args() と同じように動作しますが、余分な引数が存在してもエラーを生成しません。代わりに、評価された namespace オブジェクトと、残りの引数文字列のリストからなる2要素タプルを返します。

>>> 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'])

警告

先頭文字でのマッチング ルールは parse_known_args() にも適用されます。たとえ既知のオプションの先頭文字に過ぎない場合でも、パーサは引数リストに残さずに、オプションを受け取る場合があります。

ファイル解析のカスタマイズ

ArgumentParser.convert_arg_line_to_args(arg_line)

ファイルから引数を読み込む場合 (ArgumentParser コンストラクターの fromfile_prefix_chars キーワード引数を参照)、1行につき1つの引数を読み込みます。 convert_arg_line_to_args() を変更することでこの動作をカスタマイズできます。

このメソッドは、引数ファイルから読まれた文字列である1つの引数 arg_line を受け取ります。そしてその文字列を解析した結果の引数のリストを返します。このメソッドはファイルから1行読みこむごとに、順番に呼ばれます。

このメソッドをオーバーライドすると便利なこととして、スペースで区切られた行の単語1つ1つを別々の引数として扱えます。次の例でその方法を示します:

class MyArgumentParser(argparse.ArgumentParser):
    def convert_arg_line_to_args(self, arg_line):
        return arg_line.split()

終了メソッド

ArgumentParser.exit(status=0, message=None)

このメソッドはプログラムを、status のステータスで終了させ、指定された場合は message を終了前に表示します。ユーザは、この振る舞いを違うものにするために、メソッドをオーバーライドすることができます。

class ErrorCatchingArgumentParser(argparse.ArgumentParser):
    def exit(self, status=0, message=None):
        if status:
            raise Exception(f'Exiting because of an error: {message}')
        exit(status)

ArgumentParser.error(message)

このメソッドは message を含む使用法メッセージを標準エラーに表示して、終了ステータス 2 でプログラムを終了します。

混在した引数の解析

ArgumentParser.parse_intermixed_args(args=None, namespace=None)

ArgumentParser.parse_known_intermixed_args(args=None, namespace=None)

多くの Unix コマンドは、オプション引数と位置引数を混在させることを許しています。 parse_intermixed_args() と parse_known_intermixed_args() メソッドは、このような方法での解析をサポートしています。

このパーサーは、argparse のすべての機能をサポートしておらず、対応しない機能が使われた場合、例外を送出します。特に、サブパーサーや、位置引数とオプション引数を両方含むような相互排他的なグループは、サポートされていません。

この例は、parse_known_args() と parse_intermixed_args() の違いを表しています: 前者は ['2', '3'] を、解析されない引数として返し、後者は全ての位置引数を rest に入れて返しています:

>>> 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])

parse_known_intermixed_args() は、解析した内容を含む名前空間と、残りの引数を含んだリストの、2つの要素を持つタプルを返します。 parse_intermixed_args() は、解析されない引数が残された場合にはエラーを送出します。

Added in version 3.7.

optparse からのアップグレード

もともと、argparse モジュールは optparse モジュールとの互換性を保って開発しようと試みられました。しかし、特に新しい nargs= 指定子とより良い使用法メッセージのために必要な変更のために、optparse を透過的に拡張することは難しかったのです。optparse のほとんどすべてがコピーアンドペーストされたりモンキーパッチを当てられたりしたとき、もはや後方互換性を保とうとすることは現実的ではありませんでした。

argparse モジュールは標準ライブラリ optparse モジュールを、以下を含むたくさんの方法で改善しています:

位置引数を扱う

サブコマンドのサポート

+, / のような代替オプションプレフィクスを許容する

zero-or-more スタイル、one-or-more スタイルの引数を扱う

より有益な使用方法メッセージの生成

カスタム type, カスタム action のために遥かに簡単なインターフェイスを提供する

optparse から argparse への現実的なアップグレードパス:

すべての optparse.OptionParser.add_option() の呼び出しを、ArgumentParser.add_argument() の呼び出しに置き換える。

(options, args) = parser.parse_args() を args = parser.parse_args() に置き換え、位置引数のために必要に応じて ArgumentParser.add_argument() の呼び出しを追加する。これまで options と呼ばれていたものが、argparse では args と呼ばれていることに留意してください。

optparse.OptionParser.disable_interspersed_args() を、parse_args() ではなく parse_intermixed_args() で置き換える。

コールバック・アクションと callback_* キーワード引数を type や action 引数に置き換える。

type キーワード引数に渡していた文字列の名前を、それに応じたオブジェクト (例: int, float, complex, ...) に置き換える。

optparse.Values を Namespace に置き換え、optparse.OptionError と optparse.OptionValueError を ArgumentError に置き換える。

%default や %prog などの暗黙の引数を含む文字列を、%(default)s や %(prog)s などの、通常の Python で辞書を使う場合のフォーマット文字列に置き換える。

OptionParser のコンストラクターの version 引数を、parser.add_argument('--version', action='version', version='<the version>') に置き換える

例外

exception argparse.ArgumentError

引数 (オプション引数または位置引数) の生成時または利用時のエラーです。

この例外の文字列表現は、エラーの原因となった引数についての情報を補足するメッセージです。

exception argparse.ArgumentTypeError

コマンドラインの文字列を、指定された型に変換するのに失敗した時に送出されます。

getopt --- C-style parser for command line options

ソースコード: Lib/getopt.py [https://github.com/python/cpython/tree/3.12/Lib/getopt.py]

注釈

The getopt module is a parser for command line options whose API is designed to be familiar to users of the C getopt() function. Users who are unfamiliar with the C getopt() function or who would like to write less code and get better help and error messages should consider using the argparse module instead.

This module helps scripts to parse the command line arguments in sys.argv. It supports the same conventions as the Unix getopt() function (including the special meanings of arguments of the form '-' and '--'). Long options similar to those supported by GNU software may be used as well via an optional third argument.

このモジュールは2つの関数と1つの例外を提供しています:

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 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 (':'; i.e., the same format that Unix getopt() uses).

注釈

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

longopts は長形式のオプションの名前を示す文字列のリストです。名前には、先頭の '--' は含めません。引数が必要な場合には名前の最後に等号 ('=') を入れます。オプション引数はサポートしていません。長形式のオプションだけを受けつけるためには、shortopts は空文字列である必要があります。長形式のオプションは、該当するオプションを一意に決定できる長さまで入力されていれば認識されます。たとえば、longopts が ['foo', 'frob'] の場合、--fo は --foo にマッチしますが、--f では一意に決定できないので、GetoptError が送出されます。

返り値は2つの要素から成っています: 最初は (option, value) のタプルのリスト、2つ目はオプションリストを取り除いたあとに残ったプログラムの引数リストです (args の末尾部分のスライスになります)。それぞれの引数と値のタプルの最初の要素は、短形式の時はハイフン 1つで始まる文字列 (例: '-x')、長形式の時はハイフン2つで始まる文字列 (例: '--long-option') となり、引数が2番目の要素になります。引数をとらない場合には空文字列が入ります。オプションは見つかった順に並んでいて、複数回同じオプションを指定できます。長形式と短形式のオプションは混在できます。

getopt.gnu_getopt(args, shortopts, longopts=[])

この関数はデフォルトで GNU スタイルのスキャンモードを使う以外は getopt() と同じように動作します。つまり、オプションとオプションでない引数とを混在させることができます。getopt() 関数はオプションでない引数を見つけると解析を停止します。

If the first character of the option string is '+', or if the environment variable POSIXLY_CORRECT is set, then option processing stops as soon as a non-option argument is encountered.

exception getopt.GetoptError

This is raised when an unrecognized option is found in the argument list or when an option requiring an argument is given none. The argument to the exception is a string indicating the cause of the error. For long options, an argument given to an option which does not require one will also cause this exception to be raised. The attributes msg and opt give the error message and related option; if there is no specific option to which the exception relates, opt is an empty string.

exception getopt.error

GetoptError へのエイリアスです。後方互換性のために残されています。

Unix スタイルのオプションを使った例です:

>>> 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', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')]
>>> args
['a1', 'a2']

長形式のオプションを使っても同様です:

>>> 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', ''), ('--output-file', 'abc.def'), ('-x', '')]
>>> args
['a1', 'a2']

スクリプト中での典型的な使い方は以下のようになります:

import getopt, sys

def main():
    try:
        opts, args = getopt.getopt(sys.argv[1:], "ho:v", ["help", "output="])
    except getopt.GetoptError as err:
        # print help information and exit:
        print(err)  # will print something like "option -a not recognized"
        usage()
        sys.exit(2)
    output = None
    verbose = False
    for o, a in opts:
        if o == "-v":
            verbose = True
        elif o in ("-h", "--help"):
            usage()
            sys.exit()
        elif o in ("-o", "--output"):
            output = a
        else:
            assert False, "unhandled option"
    # ...

if __name__ == "__main__":
    main()

argparse モジュールを使えば、より良いヘルプメッセージとエラーメッセージを持った同じコマンドラインインターフェースをより少ないコードで実現できます:

import argparse

if __name__ == '__main__':
    parser = argparse.ArgumentParser()
    parser.add_argument('-o', '--output')
    parser.add_argument('-v', dest='verbose', action='store_true')
    args = parser.parse_args()
    # ... do something with args.output ...
    # ... do something with args.verbose ..

参考

argparse モジュール

別のコマンドラインオプションと引数の解析ライブラリ。

logging --- Logging facility for Python

ソースコード: Lib/logging/__init__.py [https://github.com/python/cpython/tree/3.12/Lib/logging/__init__.py]

Important

このページには、リファレンス情報だけが含まれています。チュートリアルは、以下のページを参照してください

基本チュートリアル

上級チュートリアル

ロギングクックブック

このモジュールは、アプリケーションやライブラリのための柔軟なエラーログ記録 (logging) システムを実装するための関数やクラスを定義しています。

標準ライブラリモジュールとしてログ記録 API が提供される利点は、すべての Python モジュールがログ記録に参加できることであり、これによってあなたが書くアプリケーションのログにサードパーティーのモジュールが出力するメッセージを含ませることができます。

Here's a simple example of idiomatic usage:

# 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()

# mylib.py
import logging
logger = logging.getLogger(__name__)

def do_something():
    logger.info('Doing something')

myapp.py を実行すれば、myapp.log でログが確認できます:

INFO:__main__:Started
INFO:mylib:Doing something
INFO:__main__:Finished

The key feature of this idiomatic usage is that the majority of code is simply creating a module level logger with 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. basicConfig() provides a quick way to configure the root logger that handles many use cases.

このモジュールは、多くの機能性と柔軟性を提供します。ロギングに慣れていないなら、使い方を理解する最良の方法はチュートリアルを読むことです (右上のリンクを参照してください)。

The basic classes defined by the module, together with their attributes and methods, are listed in the sections below.

ロガーは、アプリケーションコードが直接使うインターフェースを公開します。

ハンドラは、(ロガーによって生成された) ログ記録を適切な送信先に送ります。

フィルタは、どのログ記録を出力するかを決定する、きめ細かい機能を提供します。

フォーマッタは、ログ記録が最終的に出力されるレイアウトを指定します。

ロガーオブジェクト

ロガーには以下のような属性とメソッドがあります。ロガーを直接インスタンス化することは 絶対に してはならず、常にモジュール関数 logging.getLogger(name) を介してインスタンス化することに注意してください。同じ name で getLogger() を複数回呼び出すと、常に同じロガー・オブジェクトへの参照が返されます。

name は foo.bar.baz のようにピリオドで分割された (ただし単なるプレーンな foo もありえます) 潜在的に階層的な値です。階層リスト中でより下位のロガーは、上位のロガーの子です。例えば、foo という名前を持つロガーがあるとき、foo.bar, foo.bar.baz, foo.bam という名前を持つロガーはすべて foo の子孫です。ロガー名の階層は Python パッケージ階層と類似していて、推奨される構築方法 logging.getLogger(__name__) を使用してロガーをモジュール単位で構成すれば、Python パッケージ階層と同一になります。これは、モジュールの中では __name__ が Python パッケージ名前空間におけるモジュール名だからです。

class logging.Logger

name

This is the logger's name, and is the value that was passed to getLogger() to obtain the logger.

注釈

This attribute should be treated as read-only.

level

The threshold of this logger, as set by the setLevel() method.

注釈

Do not set this attribute directly - always use setLevel(), which has checks for the level passed to it.

parent

The parent logger of this logger. It may change based on later instantiation of loggers which are higher up in the namespace hierarchy.

注釈

This value should be treated as read-only.

propagate

この属性が真と評価された場合、このロガーに記録されたイベントは、このロガーに取り付けられた全てのハンドラに加え、上位 (祖先) ロガーのハンドラにも渡されます。メッセージは、祖先ロガーのハンドラに直接渡されます - 今問題にしている祖先ロガーのレベルもフィルタも、どちらも考慮されません。

この値の評価結果が偽になる場合、ロギングメッセージは祖先ロガーのハンドラに渡されません。

具体的な例で説明します: A.B.C という名前のロガーの propagate 属性が真と評価された場合、 logging.getLogger('A.B.C').error(...) のようなメソッドの呼び出しを通じて A.B.C に記録された全てのイベントは、 [ログレベルとフィルタの設定を満たした場合に限り] 最初に A.B.C に接続されたハンドラに渡され、その後 A.B, A という名前のロガー、そしてルートロガーという順番で各ロガーに接続されたハンドラに渡されます。この連鎖構造において A.B.C, A.B, A のいずれかの propagate 属性が偽に設定された場合、そのロガーがイベントを処理する最後のロガーとなり、その時点でイベントの伝播は止まります。

コンストラクタはこの属性を True に設定します。

注釈

ハンドラを、あるロガー と その祖先のロガーに接続した場合、同一レコードが複数回発行される場合があります。一般的に、ハンドラを複数のロガーに接続する必要はありません。propagate 設定が True のままになっていれば、ロガーの階層において最上位にある適切なロガーにハンドラを接続するだけで、そのハンドラは全ての子孫ロガーが記録する全てのイベントを確認することができます。一般的なシナリオでは、ハンドラをルートロガーに対してのみ接続し、残りは propagate にすべて委ねます。

handlers

The list of handlers directly attached to this logger instance.

注釈

This attribute should be treated as read-only; it is normally changed via the addHandler() and removeHandler() methods, which use locks to ensure thread-safe operation.

disabled

This attribute disables handling of any events. It is set to False in the initializer, and only changed by logging configuration code.

注釈

This attribute should be treated as read-only.

setLevel(level)

このロガーの閾値を level に設定します。 level よりも深刻でないログメッセージは無視されます; 深刻さが level 以上のログメッセージは、ハンドラのレベルが level より上に設定されていない限り、このロガーに取り付けられているハンドラによって投げられます。

ロガーが生成された際、レベルは NOTSET (これによりすべてのメッセージについて、ロガーがルートロガーであれば処理される、そうでなくてロガーが非ルートロガーの場合には親ロガーに委譲させる) に設定されます。ルートロガーは WARNING レベルで生成されることに注意してください。

「親ロガーに委譲」という用語の意味は、もしロガーのレベルが NOTSET ならば、祖先ロガーの系列の中を NOTSET 以外のレベルの祖先を見つけるかルートに到達するまで辿っていく、ということです。

もし NOTSET 以外のレベルの祖先が見つかったなら、その祖先のレベルが探索を開始したロガーの実効レベルとして扱われ、ログイベントがどのように処理されるかを決めるのに使われます。

ルートに到達した場合、ルートのレベルが NOTSET ならばすべてのメッセージは処理されます。そうでなければルートのレベルが実効レベルとして使われます。

レベルの一覧については ロギングレベル を参照してください。

バージョン 3.2 で変更: level パラメータは、 INFO のような整数定数の代わりに 'INFO' のようなレベルの文字列表現も受け付けるようになりました。ただし、レベルは内部で整数として保存されますし、 getEffectiveLevel() や isEnabledFor() といったメソッドは、整数を返し、また渡されるものと期待します。

isEnabledFor(level)

深刻度が lvl のメッセージが、このロガーで処理されることになっているかどうかを示します。このメソッドはまず、 logging.disable(level) で設定されるモジュールレベルの深刻度レベルを調べ、次にロガーの実効レベルを getEffectiveLevel() で調べます。

getEffectiveLevel()

このロガーの実効レベルを示します。 NOTSET 以外の値が setLevel() で設定されていた場合、その値が返されます。そうでない場合、 NOTSET 以外の値が見つかるまでロガーの階層をルートロガーの方向に追跡します。見つかった場合、その値が返されます。返される値は整数で、典型的には logging.DEBUG, logging.INFO 等のうち一つです。

getChild(suffix)

このロガーの子であるロガーを、接頭辞によって決定し、返します。従って、logging.getLogger('abc').getChild('def.ghi') は、logging.getLogger('abc.def.ghi') によって返されるのと同じロガーを返すことになります。これは簡便なメソッドで、親ロガーがリテラルでなく __name__ などを使って名付けられているときに便利です。

Added in version 3.2.

getChildren()

Returns a set of loggers which are immediate children of this logger. So for example logging.getLogger().getChildren() might return a set containing loggers named foo and bar, but a logger named foo.bar wouldn't be included in the set. Likewise, logging.getLogger('foo').getChildren() might return a set including a logger named foo.bar, but it wouldn't include one named foo.bar.baz.

Added in version 3.12.

debug(msg, *args, **kwargs)

レベル DEBUG のメッセージをこのロガーで記録します。 msg はメッセージの書式文字列で、 args は msg に文字列書式化演算子を使って取り込むための引数です。 (これは、書式化文字列の中でキーワードを使い、引数として単一の辞書を渡すことができる、ということを意味します。) args が提供されない場合は msg の%フォーマットは実行されません。

kwargs のうち、 exc_info, stack_info, stacklevel, extra という4つのキーワード引数の中身を調べます。

exc_info は、この値の評価値が false でない場合、例外情報がロギングメッセージに追加されます。もし例外情報をあらわすタプル(sys.exc_info() 関数によって戻されるフォーマットにおいて)、または、例外情報をあらわすインスタンスが与えられていれば、それが使用されることになります。それ以外の場合には、 sys.exc_info() を呼び出して例外情報を取得します。

2つ目の省略可能なキーワード引数は stack_info で、デフォルトは False です。真の場合、実際のロギング呼び出しを含むスタック情報がロギングメッセージに追加されます。これは exc_info 指定によって表示されるスタック情報と同じものではないことに注意してください: 前者はカレントスレッド内での、一番下からロギング呼び出しまでのスタックフレームですが、後者は例外に呼応して、例外ハンドラが見つかるところまで巻き戻されたスタックフレームの情報です。

exc_info とは独立に stack_info を指定することもできます (例えば、例外が上げられなかった場合でも、コード中のある地点にどのように到着したかを単に示すために)。スタックフレームは、次のようなヘッダー行に続いて表示されます:

Stack (most recent call last):

これは、例外フレームを表示する場合に使用される Traceback (most recent call last): を模倣します。

3番目のオプションキーワード引数は stacklevel で、デフォルトは 1 です。もしこれが1よりも大きい場合は、 LogRecord 内で行番号と関数名を算出する時に、指定されたスタックフレームの数をスキップします。これはログヘルパー内部で使われる場合、関数名、ファイル名、行番号はそのヘルパーの情報ではなく、そのヘルパーを呼び出した呼び出し元のものになります。このパラメータの名前は warnings モジュールと同じものになります。

4番目のキーワード引数は extra で、当該ログイベント用に作られる LogRecord の __dict__ にユーザー定義属性を加えるのに使われる辞書を渡すために用いられます。これらの属性は好きなように使えます。たとえば、ログメッセージの一部にすることもできます。以下の例を見てください:

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)

これは以下のような出力を行います

2006-02-08 22:20:02,165 192.168.0.1 fbloggs  Protocol problem: connection reset

extra に渡される辞書のキーはロギングシステムで使われているものと衝突してはいけません。 (ロギングシステムが使うキーの詳細については LogRecord 属性 の節を参照してください。)

これらの属性をログメッセージに使うことにしたなら、少し注意が必要です。上の例では、 'clientip' と 'user' が LogRecord の属性辞書に含まれていることを期待した書式文字列で Formatter がセットアップされています。もしこれらが欠けていると、書式化例外が発生してしまうためメッセージはログに残りません。したがってこの場合、常にこれらのキーを含む extra 辞書を渡す必要があります。

このようなことは煩わしいかもしれませんが、この機能は限定された場面で使われるように意図しているものなのです。たとえば同じコードがいくつものコンテキストで実行されるマルチスレッドのサーバで、興味のある条件が現れるのがそのコンテキストに依存している (上の例で言えば、リモートのクライアント IP アドレスや認証されたユーザ名など)、というような場合です。そういった場面では、それ用の Formatter が特定の Handler と共に使われるというのはよくあることです。

このロガー (および Logger.propagate 属性を考慮した上で実効的にイベントが伝播する祖先のロガー) にハンドラが接続されていない場合、メッセージは lastResort に設定されたハンドラーに送られます。

バージョン 3.2 で変更: stack_info パラメータが追加されました。

バージョン 3.5 で変更: exc_info パラメータは例外インスタンスを受け入れることが可能です。

バージョン 3.8 で変更: stacklevel 引数が追加されました。

info(msg, *args, **kwargs)

レベル INFO のメッセージをこのロガーで記録します。引数は debug() と同じように解釈されます。

warning(msg, *args, **kwargs)

レベル WARNING のメッセージをこのロガーで記録します。引数は debug() と同じように解釈されます。

注釈

There is an obsolete method warn which is functionally identical to warning. As warn is deprecated, please do not use it - use warning instead.

error(msg, *args, **kwargs)

レベル ERROR のメッセージをこのロガーで記録します。引数は debug() と同じように解釈されます。

critical(msg, *args, **kwargs)

レベル CRITICAL のメッセージをこのロガーで記録します。引数は debug() と同じように解釈されます。

log(level, msg, *args, **kwargs)

整数で表したレベル level のメッセージをこのロガーで記録します。その他の引数は debug() と同じように解釈されます。

exception(msg, *args, **kwargs)

レベル ERROR のメッセージをこのロガーで記録します。引数は debug() と同じように解釈されます。例外情報がログメッセージに追加されます。このメソッドは例外ハンドラからのみ呼び出されるべきです。

addFilter(filter)

指定されたフィルタ filter をこのロガーに追加します。

removeFilter(filter)

指定されたフィルタ filter をこのロガーから取り除きます。

filter(record)

レコードに対してこのロガーのフィルタを適用し、レコードが処理されるべき場合に True を返します。フィルタのいずれかの値が偽を返すまで、それらは順番に試されていきます。いずれも偽を返さなければ、レコードは処理される(ハンドラに渡される)ことになります。ひとつでも偽を返せば、発生したレコードはもはや処理されることはありません。

addHandler(hdlr)

指定されたハンドラ hdlr をこのロガーに追加します。

removeHandler(hdlr)

指定されたハンドラ hdlr をこのロガーから取り除きます。

findCaller(stack_info=False, stacklevel=1)

呼び出し元のソースファイル名と行番号を調べます。ファイル名と行番号、関数名、スタック情報を 4 要素のタプルで返します。stack_info が True でなければ、スタック情報は None が返されます。

stacklevel パラメータは debug() や他のAPIを呼び出すコードから渡されます。もしこれが1よりも大きい場合は、その超過分は返す値を決定する前にスタックフレームをスキップする数として利用されます。これは通常、ログAPIをヘルパーやラッパー経由で呼び出す場合に便利です。こうすることで、イベントログに記録される情報はヘルパーやラッパーのコードではなく、それらを呼び出しているコードのものとなります。

handle(record)

レコードを、このロガーおよびその上位ロガー (ただし propagate の値が false になったところまで) に関連付けられているすべてのハンドラに渡して処理します。このメソッドは、ローカルで生成されたレコードだけでなく、ソケットから受信した unpickle されたレコードに対しても同様に用いられます。 filter() によって、ロガーレベルでのフィルタが適用されます。

makeRecord(name, level, fn, lno, msg, args, exc_info, func=None, extra=None, sinfo=None)

このメソッドは、特殊な LogRecord インスタンスを生成するためにサブクラスでオーバライドできるファクトリメソッドです。

hasHandlers()

このロガーにハンドラが設定されているかどうかを調べます。そのために、このロガーとロガー階層におけるその祖先についてハンドラ探していきます。ハンドラが見つかれば True 、そうでなければ False を返します。このメソッドは、'propagate' 属性が偽に設定されたロガーを見つけると、さらに上位の探索をやめます - そのロガーが、ハンドラが存在するかどうかチェックされる最後のロガー、という意味です。

Added in version 3.2.

バージョン 3.7 で変更: ロガーの pickle 化と unpickle 化ができるようになりました。

ロギングレベル

ログレベルの数値は以下の表のように与えられています。これらは基本的に自分でレベルを定義したい人のためのもので、定義するレベルを既存のレベルの間に位置づけるためには具体的な値が必要になります。もし数値が他のレベルと同じだったら、既存の値は上書きされその名前は失われます。

レベル

数値

What it means / When to use it

logging.NOTSET

0

When set on a logger, indicates that ancestor loggers are to be consulted to determine the effective level. If that still resolves to NOTSET, then all events are logged. When set on a handler, all events are handled.

logging.DEBUG

10

Detailed information, typically only of interest to a developer trying to diagnose a problem.

logging.INFO

20

想定された通りのことが起こったことの確認。

logging.WARNING

30

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.

logging.ERROR

40

より重大な問題により、ソフトウェアがある機能を実行できないこと。

logging.CRITICAL

50

プログラム自体が実行を続けられないことを表す、重大なエラー。

ハンドラオブジェクト

ハンドラ (Handler) は以下の属性とメソッドを持ちます。 Handler は直接インスタンス化されることはありません; このクラスはより便利なサブクラスの基底クラスとして働きます。しかしながら、サブクラスにおける __init__() メソッドでは、 Handler.__init__() を呼び出す必要があります。

class logging.Handler

__init__(level=NOTSET)

レベルを設定して、 Handler インスタンスを初期化します。空のリストを使ってフィルタを設定し、 I/O 機構へのアクセスを直列化するために (createLock() を使って) ロックを生成します。

createLock()

スレッドセーフでない背後の I/O 機能に対するアクセスを直列化するために用いられるスレッドロック (thread lock) を初期化します。

acquire()

createLock() で生成されたスレッドロックを獲得します。

release()

acquire() で獲得したスレッドロックを解放します。

setLevel(level)

このハンドラに対する閾値を level に設定します。 level よりも深刻でないログメッセージは無視されます。ハンドラが生成された際、レベルは NOTSET (すべてのメッセージが処理される) に設定されます。

レベルの一覧については ロギングレベル を参照してください。

バージョン 3.2 で変更: level パラメータは、 INFO のような整数定数の代わりに 'INFO' のようなレベルの文字列表現も受け付けるようになりました。

setFormatter(fmt)

このハンドラのフォーマッタを fmt に設定します。

addFilter(filter)

指定されたフィルタ filter をこのハンドラに追加します。

removeFilter(filter)

指定されたフィルタ filter をこのハンドラから除去します。

filter(record)

レコードに対してこのハンドラのフィルタを適用し、レコードが処理されるべき場合に True を返します。フィルタのいずれかの値が偽を返すまで、それらは順番に試されていきます。いずれも偽を返さなければ、レコードは発行されることになります。ひとつでも偽を返せば、ハンドラはレコードを発行しません。

flush()

すべてのログ出力がフラッシュされるようにします。このクラスのバージョンではなにも行わず、サブクラスで実装するためのものです。

close()

ハンドラで使われているすべてのリソースの後始末を行います。このバージョンでは何も出力せず、 shutdown() が呼ばれたときに閉じられたハンドラを内部リストから削除します。サブクラスではオーバライドされた close() メソッドからこのメソッドが必ず呼ばれるようにしてください。

handle(record)

ハンドラに追加されたフィルタの条件に応じて、指定されたログレコードを出力します。このメソッドは I/O スレッドロックの獲得/解放を伴う実際のログ出力をラップします。

handleError(record)

This method should be called from handlers when an exception is encountered during an emit() call. If the module-level attribute raiseExceptions is 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 raiseExceptions is True, as that is more useful during development).

format(record)

レコードに対する書式化を行います - フォーマッタが設定されていれば、それを使います。そうでない場合、モジュールにデフォルト指定されたフォーマッタを使います。

emit(record)

指定されたログ記録レコードを実際にログ記録する際のすべての処理を行います。このメソッドはサブクラスで実装されることを意図しており、そのためこのクラスのバージョンは NotImplementedError を送出します。

警告

このメソッドはハンドラレベルのロックを取得した後で呼び出されます。また、ロックはこのメソッドがリターンした後で解放されます。このメソッドをオーバーライドする場合、ロックを取得する可能性のある logging API の他の関数やメソッドの呼び出しに注意してください。そのような実装はデッドロックを引き起こす可能性があります。特に以下の点に注意してください:

ロギングを構成するための API はモジュールレベルのロックを取得し、その後ハンドラを構成する際に個々のハンドラに対してハンドラレベルのロックを取得します。

多くのロギング API はモジュールレベルのロックを取得します。そのような API がこのメソッドから呼ばれた場合、他のスレッドからロギングを構成するための API 呼び出しが行われたときにデッドロックに陥る可能性があります。これは他のスレッドがハンドラレベルのロックを取得する 前に モジュールレベルのロックを取得しようとする一方で、 (このメソッドはハンドラレベルのロックが既に取得された状態で呼び出されているため) このメソッドを呼び出したスレッドはハンドラレベルのロックを取得した 後で モジュールレベルのロックを取得しようとするためです。

標準として含まれているハンドラについては、 logging.handlers を参照してください。

フォーマッタオブジェクト

class logging.Formatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)

Responsible for converting a LogRecord to an output string to be interpreted by a human or external system.

パラメータ:

fmt (str) -- A format string in the given style for the logged output as a whole. The possible mapping keys are drawn from the LogRecord object's LogRecord 属性. If not specified, '%(message)s' is used, which is just the logged message.

datefmt (str) -- A format string in the given style for the date/time portion of the logged output. If not specified, the default described in formatTime() is used.

style (str) -- Can be one of '%', '{' or '$' and determines how the format string will be merged with its data: using one of printf 形式の文字列書式化 (%), str.format() ({) or string.Template ($). This only applies to fmt and datefmt (e.g. '%(message)s' versus '{message}'), not to the actual log messages passed to the logging methods. However, there are other ways to use {- and $-formatting for log messages.

validate (bool) -- If True (the default), incorrect or mismatched fmt and style will raise a ValueError; for example, logging.Formatter('%(asctime)s - %(message)s', style='{').

defaults (dict[str, Any]) -- A dictionary with default values to use in custom fields. For example, logging.Formatter('%(ip)s %(message)s', defaults={"ip": None})

バージョン 3.2 で変更: Added the style parameter.

バージョン 3.8 で変更: Added the validate parameter.

バージョン 3.10 で変更: Added the defaults parameter.

format(record)

レコードの属性辞書が、文字列を書式化する演算で被演算子として使われます。書式化された結果の文字列を返します。辞書を書式化する前に、二つの準備段階を経ます。レコードの message 属性が msg % args を使って処理されます。書式化された文字列が '(asctime)' を含むなら、 formatTime() が呼び出され、イベントの発生時刻を書式化します。例外情報が存在する場合、 formatException() を使って書式化され、メッセージに追加されます。ここで注意していただきたいのは、書式化された例外情報は exc_text にキャッシュされるという点です。これが有用なのは例外情報がピックル化されて回線上を送ることができるからですが、しかし二つ以上の Formatter サブクラスで例外情報の書式化をカスタマイズしている場合には注意が必要になります。この場合、フォーマッタが書式化を終えるごとにキャッシュをクリアして（ ext_text 属性に None を設定して）、次のフォーマッタがキャッシュされた値を使わずに新鮮な状態で再計算するようにしなければならないことになります。

スタック情報が利用可能な場合、(必要ならば formatStack() を使って整形した上で) スタック情報が例外情報の後に追加されます。

formatTime(record, datefmt=None)

このメソッドは、フォーマッタが書式化された時間を利用したい際に、 format() から呼び出されます。このメソッドは特定の要求を提供するためにフォーマッタで上書きすることができますが、基本的な振る舞いは以下のようになります: datefmt (文字列) が指定された場合、レコードが生成された時刻を書式化するために time.strftime() で使われます。そうでない場合、 '%Y-%m-%d %H:%M:%S,uuu' というフォーマットが使われます。 uuu 部分はミリ秒値で、それ以外の文字は time.strftime() ドキュメントに従います。このフォーマットの時刻の例は 2003-01-23 00:29:50,411 です。結果の文字列が返されます。

この関数は、ユーザが設定できる関数を使って、生成時刻をタプルに変換します。デフォルトでは、 time.localtime() が使われます。特定のフォーマッタインスタンスに対してこれを変更するには、 converter 属性を time.localtime() や time.gmtime() と同じ署名をもつ関数に設定してください。すべてのフォーマッタインスタンスに対してこれを変更するには、例えば全てのロギング時刻を GMT で表示するには、 Formatter クラスの converter 属性を設定してください。

バージョン 3.3 で変更: 以前は、デフォルトのフォーマットがこの例のようにハードコーディングされていました: 2010-09-06 22:38:15,292 ここで、コンマの前の部分は strptime フォーマット文字列 ('%Y-%m-%d %H:%M:%S') によって扱われる部分で、コンマの後の部分はミリ秒値です。strptime にミリ秒のフォーマットプレースホルダーがないので、ミリ秒値は別のフォーマット文字列 '%s,%03d' を使用して追加されます。そして、これらのフォーマット文字列は両方ともこのメソッドでハードコーディングされていました。変更後は、これらの文字列はクラスレベル属性として定義され、必要ならインスタンスレベルでオーバーライドすることができます。属性の名前は default_time_format (strptime 書式文字列用) と default_msec_format (ミリ秒値の追加用) です。

バージョン 3.9 で変更: default_msec_format 引数が None であることを許容します。

formatException(exc_info)

指定された例外情報 (sys.exc_info() が返すような標準例外のタプル) を文字列として書式化します。デフォルトの実装は単に traceback.print_exception() を使います。結果の文字列が返されます。

formatStack(stack_info)

指定されたスタック情報を文字列としてフォーマットします (traceback.print_stack() によって返される文字列ですが、最後の改行が取り除かれています)。このデフォルト実装は、単に入力値をそのまま返します。

class logging.BufferingFormatter(linefmt=None)

複数のレコードをまとめてフォーマットしたい場合のクラス定義に適した基底クラスです。各行 (単一のレコードに相当します) をフォーマットするために使う Formatter インスタンスを渡すことができます。特に指定がない場合はデフォルトのフォーマッタ (イベントのメッセージだけを出力するフォーマッタ) が使われます。

formatHeader(records)

複数のレコード のリストに対するヘッダを返します。基底クラスの実装は単に空の文字列を返すだけです。レコード数やタイトルを表示したり、あるいはセパレータ行したいなど、ヘッダに対して特別な振る舞いが必要な場合はこのメソッドをオーバーライドする必要があります。

formatFooter(records)

複数のレコード のリストに対するフッタを返します。基底クラスの実装は単に空の文字列を返すだけです。レコード数やセパレータ行の表示など、フッタに対して特別な振る舞いが必要な場合はこのメソッドをオーバーライドする必要があります。

format(records)

複数のレコード のリストに対するフォーマット済みテキストを返します。基底クラスの実装は、レコードがなければ空の文字列を返し、レコードがある場合はヘッダ、単一のレコードをフォーマットするためのラインフォーマッタで各レコードをフォーマットした文字列、そしてフッタを全て連結したものを返します。

フィルタオブジェクト

フィルタ (Filter) は、ハンドラ や ロガー によって使われ、レベルによって提供されるのよりも洗練されたフィルタリングを実現します。基底のフィルタクラスは、ロガー階層構造内の特定地点の配下にあるイベントだけを許可します。例えば、'A.B' で初期化されたフィルタは、ロガー 'A.B', 'A.B.C', 'A.B.C.D', 'A.B.D' 等によって記録されたイベントは許可しますが、'A.BB', 'B.A.B' などは許可しません。空の文字列で初期化された場合、すべてのイベントを通過させます。

class logging.Filter(name='')

Filter クラスのインスタンスを返します。 name が指定されていれば、 name はロガーの名前を表します。指定されたロガーとその子ロガーのイベントがフィルタを通過できるようになります。 name が指定されなければ、すべてのイベントを通過させます。

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.

ハンドラに対するフィルタはハンドラがイベントを発行する前に試され、一方ではロガーに対するフィルタは、イベントが(debug(), info() などによって)ロギングされる際には、ハンドラにイベントが送信される前にはいつでも試されることに注意してください。そのフィルタがそれら子孫ロガーにも適用されていない限り、子孫ロガーによって生成されたイベントはロガーのフィルタ設定によってフィルタされることはありません。

実際には、Filter をサブクラス化する必要はありません。同じ意味の filter メソッドを持つ、すべてのインスタンスを通せます。

バージョン 3.2 で変更: 特殊な Filter クラスを作ったり、 filter メソッドを持つ他のクラスを使う必要はありません: 関数 (あるいは他の callable) をフィルタとして使用することができます。フィルタロジックは、フィルタオブジェクトが filter 属性を持っているかどうかチェックします: もし filter 属性を持っていたら、それは Filter であると仮定され、その filter() メソッドが呼び出されます。そうでなければ、それは callable であると仮定され、レコードを単一のパラメータとして呼び出されます。返される値は filter() によって返されるものと一致すべきです。

バージョン 3.12 で変更: You can now return a LogRecord instance from filters to replace the log record rather than modifying it in place. This allows filters attached to a Handler to modify the log record before it is emitted, without having side effects on other handlers.

フィルタは本来、レコードをレベルよりも洗練された基準に基づいてフィルタするために使われますが、それが取り付けられたハンドラやロガーによって処理されるレコードをすべて監視します。これは、特定のロガーやハンドラに処理されたレコードの数を数えたり、処理されている LogRecord の属性を追加、変更、削除したりするときに便利です。もちろん、LogRecord を変更するには注意が必要ですが、これにより、ログにコンテキスト情報を注入できます (Filter を使ったコンテキスト情報の伝達 を参照してください)。

LogRecord オブジェクト

LogRecord インスタンスは、何かをログ記録するたびに Logger によって生成されます。また、 makeLogRecord() を通して (例えば、ワイヤを通して受け取られた pickle 化されたイベントから) 手動で生成することも出来ます。

class logging.LogRecord(name, level, pathname, lineno, msg, args, exc_info, func=None, sinfo=None)

ロギングされているイベントに適切なすべての情報を含みます。

もっとも重要な情報は msg と args に渡され、 msg % args で結合されてレコードの message 属性を生成します。

パラメータ:

name (str) -- この LogRecord であらわされるイベントを記録したロガーの名前です。 LogRecord が持つロガーの名前は、たとえ異なる (祖先の) ロガーに接続されたハンドラから出力されたとしても、常に同じ値を持つことに注意してください。

level (int) -- 記録されたイベントの 数値であらわしたロギングレベル (10 が DEBUG, 20 が INFO など) です。このパラメータは LogRecord の 2つの 属性に変換されることに注意してください: 数値は levelno に、また対応するログレベルの名前は levelname に保持されます。

pathname (str) -- ロギングの呼び出しが行われたソースファイルへの完全なパス名をあらわす文字列です。

lineno (int) -- ロギングの呼び出しが発せられたソース行番号。

msg (Any) -- イベントの説明メッセージ。様々なデータのプレースホルダを含んだ %フォーマット文字列か、任意のオブジェクト (任意のオブジェクトをメッセージに使用する を参照)。

args (tuple | dict[str, Any]) -- msg 引数と組み合わせてイベント記述を得るための変数データです。

exc_info (tuple[type[BaseException], BaseException, types.TracebackType] | None) -- sys.exc_info() によって返される現在の例外情報を含む例外タプルです。例外情報がない場合は None です。

func (str | None) -- ロギングの呼び出しを行った関数またはメソッドの名前です。

sinfo (str | None) -- 現在のスレッドのスタックベースからログ呼び出しまでの間のスタック情報を表わすテキスト文字列。

getMessage()

ユーザが提供した引数をメッセージに交ぜた後、この LogRecord インスタンスへのメッセージを返します。ユーザがロギングの呼び出しに与えた引数が文字列でなければ、その引数に str() が呼ばれ、文字列に変換されます。これにより、 __str__ メソッドが実際のフォーマット文字列を返せるようなユーザ定義のクラスをメッセージとして使えます。

バージョン 3.2 で変更: LogRecord の生成は、レコードを生成するために使用されるファクトリを提供することにより、さらに設定可能になりました。ファクトリは getLogRecordFactory() と setLogRecordFactory() を使用して設定することができます (ファクトリのシグネチャに関しては setLogRecordFactory() を参照)。

この機能を使うと LogRecord の生成時に独自の値を注入することができます。次のパターンが使えます:

old_factory = logging.getLogRecordFactory()

def record_factory(*args, **kwargs):
    record = old_factory(*args, **kwargs)
    record.custom_attribute = 0xdecafbad
    return record

logging.setLogRecordFactory(record_factory)

このパターンでは複数のファクトリをつなぐこともできます。それらが互いの属性を上書きしたりせず、また上にリストされた標準属性を意図せず上書きしたりしない限り、驚くようなことは何も起こりません (there should be no surprises)。

LogRecord 属性

LogRecord には幾つかの属性があり、そのほとんどはコンストラクタの引数から得られます。(なお、LogRecord コンストラクタの引数と LogRecord 属性が常に厳密に対応するわけではありません。) これらの属性は、レコードからのデータをフォーマット文字列に統合するのに使えます。以下のテーブルに、属性名、意味、そして % 形式フォーマット文字列における対応するプレースホルダを (アルファベット順に) 列挙します。

{}-フォーマット (str.format()) を使用していれば、書式文字列の中でプレースホールダーとして {attrname} を使うことができます。 $-フォーマット (string.Template) を使用している場合は、 ${attrname} 形式にしてください。もちろん、両方の場合で attrname は使用したい実際の属性名に置き換えてください。

{}-フォーマットの場合には、属性名の後にフォーマットフラグを指定することができます。属性名とフォーマットフラグの間はコロンで分割します。例: プレースホールダー {msecs:03.0f} は、ミリセカンド値 4 を 004 としてフォーマットします。利用可能なオプション上の全詳細に関しては str.format() ドキュメンテーションを参照してください。

属性名

フォーマット

説明

args

このフォーマットを自分で使う必要はないでしょう。

msg に組み合わせて message を生成するための引数のタプル、または、マージに用いられる辞書(引数が一つしかなく、かつそれが辞書の場合)。

asctime

%(asctime)s

LogRecord が生成された時刻を人間が読める書式で表したもの。デフォルトでは "2003-07-08 16:49:45,896" 形式 (コンマ以降の数字は時刻のミリ秒部分) です。

created

%(created)f

Time when the LogRecord was created (as returned by time.time()).

exc_info

このフォーマットを自分で使う必要はないでしょう。

(sys.exc_info 風の) 例外タプルか、例外が起こっていない場合は None。

ファイル名

%(filename)s

pathname のファイル名部分。

funcName

%(funcName)s

ロギングの呼び出しを含む関数の名前。

levelname

%(levelname)s

メッセージのための文字のロギングレベル ('DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL')。

levelno

%(levelno)s

メッセージのための数値のロギングレベル (DEBUG, INFO, WARNING, ERROR, CRITICAL)。

lineno

%(lineno)d

ロギングの呼び出しが発せられたソース行番号 (利用できる場合のみ)。

message

%(message)s

msg % args として求められた、ログメッセージ。 Formatter.format() が呼び出されたときに設定されます。

module

%(module)s

モジュール (filename の名前部分)。

msecs

%(msecs)d

LogRecord が生成された時刻のミリ秒部分。

msg

このフォーマットを自分で使う必要はないでしょう。

元のロギングの呼び出しで渡されたフォーマット文字列。 args と合わせて、 message 、または任意のオブジェクトを生成します (任意のオブジェクトをメッセージに使用する 参照)。

name

%(name)s

ロギングに使われたロガーの名前。

pathname

%(pathname)s

ロギングの呼び出しが発せられたファイルの完全なパス名 (利用できる場合のみ)。

process

%(process)d

プロセス ID (利用可能な場合のみ)。

processName

%(processName)s

プロセス名 (利用可能な場合のみ)。

relativeCreated

%(relativeCreated)d

logging モジュールが読み込まれた時刻に対する、LogRecord が生成された時刻を、ミリ秒で表したもの。

stack_info

このフォーマットを自分で使う必要はないでしょう。

現在のスレッドでのスタックの底からこのレコードの生成に帰着したログ呼び出しまでのスタックフレーム情報 (利用可能な場合)。

thread

%(thread)d

スレッド ID (利用可能な場合のみ)。

threadName

%(threadName)s

スレッド名 (利用可能な場合のみ)。

taskName

%(taskName)s

asyncio.Task 名 (利用可能な場合のみ)。

バージョン 3.1 で変更: processName が追加されました。

バージョン 3.12 で変更: taskName が追加されました。

LoggerAdapter オブジェクト

LoggerAdapter インスタンスは文脈情報をログ記録呼び出しに渡すのを簡単にするために使われます。使い方の例は コンテキスト情報をログ記録出力に付加する を参照してください。

class logging.LoggerAdapter(logger, extra)

Returns an instance of LoggerAdapter initialized with an underlying Logger instance and a dict-like object.

process(msg, kwargs)

文脈情報を挿入するために、ログ記録呼び出しに渡されたメッセージおよび/またはキーワード引数に変更を加えます。ここでの実装は extra としてコンストラクタに渡されたオブジェクトを取り、'extra' キーを使って kwargs に加えます。返り値は (msg, kwargs) というタプルで、(変更されているはずの) 渡された引数を含みます。

manager

Delegates to the underlying manager` on logger.

_log

Delegates to the underlying _log`() method on logger.

LoggerAdapter は上記に加え Logger のメソッド debug(), info(), warning(), error(), exception(), critical(), log(), isEnabledFor(), getEffectiveLevel(), setLevel(), hasHandlers() をサポートします。これらは Logger の対応するメソッドと同じシグニチャを持つため、2つのインスタンスは区別せずに利用出来ます。

バージョン 3.2 で変更: isEnabledFor(), getEffectiveLevel(), setLevel(), hasHandlers() が LoggerAdapter に追加されました。これらメソッドは元のロガーに処理を委譲します。

バージョン 3.6 で変更: 基底のロガーに移譲し、アダプターをネストできるようにするために manager 属性と _log() メソッドが追加されました。

スレッドセーフ性

logging モジュールは、クライアントで特殊な作業を必要としない限りスレッドセーフになっています。このスレッドセーフ性はスレッドロックによって達成されています; モジュールの共有データへのアクセスを直列化するためのロックが一つ存在し、各ハンドラでも背後にある I/O へのアクセスを直列化するためにロックを生成します。

signal モジュールを使用して非同期シグナルハンドラを実装している場合、そのようなハンドラからはログ記録を使用できないかもしれません。これは、 threading モジュールにおけるロック実装が常にリエントラントではなく、そのようなシグナルハンドラから呼び出すことができないからです。

モジュールレベルの関数

上で述べたクラスに加えて、いくつかのモジュールレベルの関数が存在します。

logging.getLogger(name=None)

指定された名前のロガーを返します。名前が None であれば、ロガー階層のルート (root) にあるロガーを返します。name を指定する場合には、通常は 'a', 'a.b', 'a.b.c.d' といったドット区切りの階層的な名前にします。名前の付け方はログ機能を使う開発者次第です。

与えられた名前に対して、この関数はどの呼び出しでも同じロガーインスタンスを返します。したがって、ロガーインスタンスをアプリケーションの各部でやりとりする必要はありません。

logging.getLoggerClass()

標準の Logger クラスか、最後に setLoggerClass() に渡したクラスを返します。この関数は、新たなクラス定義の中で呼び出して、カスタマイズした Logger クラスのインストールが既に他のコードで適用したカスタマイズを取り消さないことを保証するために使われることがあります。例えば以下のようにします:

class MyLogger(logging.getLoggerClass()):
    # ... override behaviour here

logging.getLogRecordFactory()

LogRecord を生成するのに使われる callable を返します。

Added in version 3.2: この関数は、ログイベントを表現する LogRecord の構築方法に関して開発者により多くのコントロールを与えるため、 setLogRecordFactory() とともに提供されました。

このファクトリがどのように呼ばれるかに関する詳細は setLogRecordFactory() を参照してください。

logging.debug(msg, *args, **kwargs)

This is a convenience function that calls 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 basicConfig() is called, prior to calling debug on the root logger.

For very short scripts or quick demonstrations of logging facilities, 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 Logger.debug() (or other level-specific methods) on it, as described at the beginnning of this documentation.

logging.info(msg, *args, **kwargs)

Logs a message with level INFO on the root logger. The arguments and behavior are otherwise the same as for debug().

logging.warning(msg, *args, **kwargs)

Logs a message with level WARNING on the root logger. The arguments and behavior are otherwise the same as for debug().

注釈

warning と機能的に等価な古い関数 warn があります。warn は廃止予定なので使わないでください - 代わりに warning を使ってください。

logging.error(msg, *args, **kwargs)

Logs a message with level ERROR on the root logger. The arguments and behavior are otherwise the same as for debug().

logging.critical(msg, *args, **kwargs)

Logs a message with level CRITICAL on the root logger. The arguments and behavior are otherwise the same as for debug().

logging.exception(msg, *args, **kwargs)

Logs a message with level ERROR on the root logger. The arguments and behavior are otherwise the same as for debug(). Exception info is added to the logging message. This function should only be called from an exception handler.

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 debug().

logging.disable(level=CRITICAL)

全てのロガーのレベル level を上書きし、これはロガー自身の出力レベルよりも優先されます。アプリケーション全体を横断するログ出力を一時的に調整する必要が生じたら、この関数は便利でしょう。これの効果は重大度 level 以下の全てのロギング呼び出しを無効にすることですので、INFO で呼び出しをすれば、INFO と DEBUG イベントが捨てられる一方で、重大度 WARNING 以上のものは、ロガーの有効レベルに基いて処理されます。 logging.disable(logging.NOTSET) が呼び出されると、この上書きレベルは削除され、ログ出力は再び個々のロガーの有効レベルに依存するようになります。

CRITICAL より高い独自のログレベル (これは推奨されません) を定義した場合は、 level 引数のデフォルト値を当てにできなくなり、適切な値を明示的に与える必要があります。

バージョン 3.7 で変更: level 引数のデフォルトが CRITICAL レベルになりました。この変更についてのより詳しいことは bpo-28524 [https://bugs.python.org/issue?@action=redirect&bpo=28524] を参照してください。

logging.addLevelName(level, levelName)

内部的な辞書の中でレベル level をテキスト levelName に関連付けます。これは例えば Formatter でメッセージを書式化する際のように、数字のレベルをテキスト表現に対応付ける際に用いられます。この関数は自作のレベルを定義するために使うこともできます。使われるレベルに対する唯一の制限は、レベルは正の整数でなくてはならず、メッセージの深刻度が上がるに従ってレベルの数も上がらなくてはならないということです。

注釈

独自のレベルを定義したい場合、 カスタムレベル のセクションを参照してください。

logging.getLevelNamesMapping()

ログレベルの名前と対応するログレベルのマッピングを返します。例えば、文字列 "CRITICAL" は CRITICAL にマップされます。この関数が返すマッピングオブジェクトは、関数呼び出しのたびに内部のマッピングをコピーしたものです。

Added in version 3.11.

logging.getLevelName(level)

テキストまたは数値表現でログレベル level を返してください。

level が定義済みのレベル CRITICAL, ERROR, WARNING, INFO, DEBUG のいずれかである場合、対応する文字列が返されます。 addLevelName() を使ってレベルに名前を関連付けていた場合、 level に関連付けられた名前が返されます。定義済みのレベルに対応する数値を指定した場合、レベルに対応した文字列表現を返します。

level パラメータは、 INFO のような整数定数の代わりに 'INFO' のようなレベルの文字列表現も受け付けます。この場合、この関数は関連するレベルの数値表現を返します。

もし渡された数値や文字列がマッチしなければ、 'Level %s' % level が返されます。

注釈

レベルは内部的には整数です(これはロギングのロジックが大小比較をする必要があるからです)。この関数は、数値のレベルを、書式記述子 %(levelname)s (LogRecord 属性 参照)によって書式化されるログ出力の表示用レベル名に変換するなどの用途に使用されます。

バージョン 3.4 で変更: Python 3.4以前のバージョンでは、この関数にはテキストのレベルも渡すことが出来、これは対応する数字レベルに読み替えられていました。このドキュメントされていなかった振る舞いは誤りであると判断され、Python 3.4 で一度削除されました。ただし後方互換性のために、これは 3.4.2 で元に戻されました。

logging.getHandlerByName(name)

Returns a handler with the specified name, or None if there is no handler with that name.

Added in version 3.12.

logging.getHandlerNames()

Returns an immutable set of all known handler names.

Added in version 3.12.

logging.makeLogRecord(attrdict)

属性が attrdict で定義された、新しい LogRecord インスタンスを生成して返します。この関数は、 pickle された LogRecord 属性の辞書をソケットを介して送信し、受信端で LogRecord インスタンスとして再構成する場合に便利です。

logging.basicConfig(**kwargs)

デフォルトの Formatter を持つ StreamHandler を生成してルートロガーに追加し、ロギングシステムの基本的な環境設定を行います。関数 debug(), info(), warning(), error(), critical() は、ルートロガーにハンドラが定義されていない場合に自動的に basicConfig() を呼び出します。

この関数は force キーワード引数に True が設定されない限り、ルートロガーに設定されたハンドラがあれば何もしません。

注釈

この関数は、他のスレッドが開始される前にメインスレッドから呼び出されるべきです。Python の 2.7.1 や 3.2 以前のバージョンでは、この関数が複数のスレッドから呼ばれると(珍しい状況下とはいえ)ハンドラがルートロガーに複数回加えられることがあり、ログ内のメッセージが重複するという予期しない結果をもたらすことがあります。

以下のキーワード引数がサポートされます。

フォーマット

説明

filename

StreamHandler ではなく指定された名前で FileHandler が作られます。

filemode

filename が指定された場合、この モード でファイルが開かれます。デフォルトは 'a' です。

format

ハンドラーで指定されたフォーマット文字列を使います。デフォルトは levelname, name, message 属性をコロン区切りにしたものです。

datefmt

指定された日時の書式で time.strftime() が受け付けるものを使います。

style

format が指定された場合、書式文字列にこのスタイルを仕様します。 '%', '{', '$' のうち1つで、それぞれ printf-style, str.format(), string.Template に対応します。デフォルトは '%' です。

level

ルートロガーのレベルを指定された レベル に設定します。

stream

指定されたストリームを StreamHandler の初期化に使います。この引数は filename と同時には使えないことに注意してください。両方が指定されたときには ValueError が送出されます。

handlers

もし指定されれば、 これは root ロガーに追加される既に作られたハンドラのイテラブルになります。まだフォーマッタがセットされていないすべてのハンドラは、この関数で作られたデフォルトフォーマッタが割り当てられることになります。この引数は filename や stream と互換性がないことに注意してください。両方が存在する場合 ValueError が上げられます。

force

このキーワード引数が真に設定されている場合、ルートのロガーに取り付けられたハンドラは全て取り除かれ、他の引数によって指定された設定が有効になる前に閉じられます。

encoding

もしこのキーワード引数が filename とともに指定された場合、 FileHandler が作成されるときにこの値が利用され、出力ファイルを開く時に使用されます。

errors

もしこのキーワード引数が filename とともに指定された場合、 FileHandler が作成されるときのこの値が使用され、出力ファイルを開く時に使われます。もし指定されなかった場合、 'backslashreplace' が使用されます。もし None が指定されると open() のように渡され、'errors' を渡したのと同じように扱われます。

バージョン 3.2 で変更: style 引数が追加されました。

バージョン 3.3 で変更: 互換性のない引数が指定された状況 (例えば handlers が stream や filename と一緒に指定されたり、stream が filename と一緒に指定された場合) を捕捉するために、追加のチェックが加えられました。

バージョン 3.8 で変更: force 引数が追加されました。

バージョン 3.9 で変更: encoding と errors 引数が追加されました。

logging.shutdown()

ロギングシステムに対して、バッファのフラッシュを行い、すべてのハンドラを閉じることで順次シャットダウンを行うように告知します。この関数はアプリケーションの終了時に呼ばれるべきであり、また呼び出し以降はそれ以上ロギングシステムを使ってはなりません。

loggingモジュールがインポートされると、この関数が終了ハンドラーとして登録されます（ atexit 参照）。そのため、通常はこれを手動で行う必要はありません。

logging.setLoggerClass(klass)

ロギングシステムに対して、ロガーをインスタンス化する際にクラス klass を使うように指示します。指定するクラスは引数として名前だけをとるようなメソッド __init__() を定義していなければならず、 __init__() では Logger.__init__() を呼び出さなければなりません。この関数が呼び出されるのはたいてい、独自の振る舞いをするロガーを使う必要のあるアプリケーションでロガーがインスタンス化される前です。呼び出された後は、いつでもそのサブクラスを使ってロガーのインスタンス化をしてはいけません: 引き続き logging.getLogger() API を使用してロガーを取得してください。

logging.setLogRecordFactory(factory)

LogRecord を生成するのに使われる callable をセットします。

パラメータ:

factory -- ログレコードを生成するファクトリとして振舞う callable。

Added in version 3.2: この関数は、ログイベントを表現する LogRecord の構築方法に関して開発者により多くのコントロールを与えるため、 getLogRecordFactory() とともに提供されました。

ファクトリは以下のようなシグネチャを持っています:

factory(name, level, fn, lno, msg, args, exc_info, func=None, sinfo=None, **kwargs)

name:

ロガーの名前。

level:

ログレベル (数値)。

fn:

ログ呼び出しが行われたファイルのフルパス名。

lno:

ログ呼び出しが行われたファイルの行数。

msg:

ログメッセージ。

args:

ログメッセージに対する引数。

exc_info:

例外タプルまたは None。

func:

ログ呼び出しを起動した関数またはメソッドの名前。

sinfo:

traceback.print_stack() で提供されるような、呼び出し階層を示すスタックトレースバック。

kwargs:

追加のキーワード引数。

モジュールレベル属性

logging.lastResort

「最後の手段のハンドラ」が、この属性で利用可能です。これは StreamHandler が sys.stderr に WARNING レベルで書き出しているのがそうですし、ロギングの設定がなにか不在のロギングイベントを扱う場合に使われます。最終的な結果は、メッセージを単に sys.stderr に出力することです。これはかつて「logger XYZ についてのハンドラが見つかりません」と言っていたエラーメッセージを置き換えています。もしも何らかの理由でその昔の振る舞いが必要な場合は、 lastResort に None をセットすれば良いです。

Added in version 3.2.

logging.raiseExceptions

Used to see if exceptions during handling should be propagated.

Default: True.

If raiseExceptions is 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.

warnings モジュールとの統合

captureWarnings() 関数を使って、 logging を warnings モジュールと統合できます。

logging.captureWarnings(capture)

この関数は、logging による警告の補足を、有効にまたは無効にします。

capture が True なら、 warnings モジュールに発せられた警告は、ロギングシステムにリダイレクトされるようになります。具体的には、警告が warnings.formatwarning() でフォーマット化され、結果の文字列が 'py.warnings' という名のロガーに、 WARNING の重大度でロギングされるようになります。

capture が False なら、警告のロギングシステムに対するリダイレクトは止められ、警告は元の (すなわち、captureWarnings(True) が呼び出される前に有効だった) 送信先にリダイレクトされるようになります。

参考

logging.config モジュール

logging モジュールの環境設定 API です。

logging.handlers モジュール

logging モジュールに含まれる、便利なハンドラです。

PEP 282 [https://peps.python.org/pep-0282/] - ログシステム

この機能を Python 標準ライブラリに含めることを述べた提案です。

Python の最初のロギングパッケージ [https://old.red-dove.com/python_logging.html]

これは、 logging パッケージのオリジナルのソースです。このサイトから利用できるバージョンのパッケージは、 logging パッケージを標準ライブラリに含まない、 Python 1.5.2, 2.1.x および 2.2.x で使うのに適しています。

logging.config --- Logging configuration

ソースコード: Lib/logging/config.py [https://github.com/python/cpython/tree/3.12/Lib/logging/config.py]

Important

このページには、リファレンス情報だけが含まれています。チュートリアルは、以下のページを参照してください

基本チュートリアル

上級チュートリアル

ロギングクックブック

この節は、logging モジュールを設定するための API を解説します。

環境設定のための関数

以下の関数は logging モジュールの環境設定をします。これらの関数は、 logging.config にあります。これらの関数の使用はオプションです --- logging モジュールはこれらの関数を使うか、 (logging 自体で定義されている) 主要な API を呼び出し、 logging か logging.handlers で宣言されているハンドラを定義することで設定できます。

logging.config.dictConfig(config)

辞書からロギング環境設定を取得します。この辞書の内容は、以下の 環境設定辞書スキーマ で記述されています。

環境設定中にエラーに遭遇すると、この関数は適宜メッセージを記述しつつ ValueError, TypeError, AttributeError または ImportError を送出します。例外を送出する条件を (不完全かもしれませんが) 以下に列挙します:

文字列でなかったり、実際のロギングレベルと関係ない文字列であったりする level。

ブール値でない propagate の値。

対応する行き先を持たない id。

インクリメンタルな呼び出しの中で見つかった存在しないハンドラ id。

無効なロガー名。

内部や外部のオブジェクトに関わる不可能性。

解析は DictConfigurator クラスによって行われます。このクラスのコンストラクタは環境設定に使われる辞書に渡され、このクラスは configure() メソッドを持ちます。 logging.config モジュールは、呼び出し可能属性 dictConfigClass を持ち、これはまず DictConfigurator に設定されます。 dictConfigClass の値は適切な独自の実装で置き換えられます。

dictConfig() は dictConfigClass を、指定された辞書を渡して呼び出し、それから返されたオブジェクトの configure() メソッドを呼び出して、環境設定を作用させます:

def dictConfig(config):
    dictConfigClass(config).configure()

例えば、 DictConfigurator のサブクラスは、自身の __init__() で DictConfigurator.__init__() を呼び出し、それから続く configure() の呼び出しに使えるカスタムの接頭辞を設定できます。 dictConfigClass は、この新しいサブクラスに束縛され、そして dictConfig() はちょうどデフォルトの、カスタマイズされていない状態のように呼び出せます。

Added in version 3.2.

logging.config.fileConfig(fname, defaults=None, disable_existing_loggers=True, encoding=None)

ログ記録の環境設定を configparser 形式ファイルから読み出します。そのファイルの形式は 環境設定ファイルの書式 で記述されているとおりにしなければなりません。この関数はアプリケーションから何度も呼び出すことができ、これによって、 (設定を選択し、選択された設定を読み出す機構をデベロッパが提供していれば) 複数の準備済みの設定からエンドユーザが選択するようにできます。

It will raise FileNotFoundError if the file doesn't exist and RuntimeError if the file is invalid or empty.

パラメータ:

fname -- A filename, or a file-like object, or an instance derived from RawConfigParser. If a RawConfigParser-derived instance is passed, it is used as is. Otherwise, a ConfigParser is instantiated, and the configuration read by it from the object passed in fname. If that has a readline() method, it is assumed to be a file-like object and read using read_file(); otherwise, it is assumed to be a filename and passed to read().

defaults -- Defaults to be passed to the ConfigParser can be specified in this argument.

disable_existing_loggers -- False が指定された場合は、この呼び出しが行われたときに存在するロガーは有効のまま残されます。後方互換性のあるやり方で古い振る舞いを保つので、デフォルト値は True になっています。そのような振る舞いでは、既存の非ルートロガーまたはそれらのロガーの先祖がロギング設定の中で明示的に名付けられていない限り、既存のロガーを無効にします。

encoding -- fname がファイル名の場合に、ファイルをオープンする時のエンコーディングです。

バージョン 3.4 で変更: fname として RawConfigParser のサブクラスのインスタンスが渡せ得るようになっています。これによってこのようなことが容易になります:

ロギングの設定が、アプリケーション全体の設定における単なる一部であるような設定ファイルの使用。

ファイルから設定を読み込み、 fileConfig に通す前に(例えばコマンドラインパラメータやランタイム環境の他のなにかで)アプリケーションによって修正するようなこと。

バージョン 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.

logging.config.listen(port=DEFAULT_LOGGING_CONFIG_PORT, verify=None)

指定されたポートでソケットサーバを起動し、新しい設定を待ち受けます。ポートが指定されなかった場合は、モジュールのデフォルトの DEFAULT_LOGGING_CONFIG_PORT が使用されます。ロギング設定は dictConfig() あるいは fileConfig() で処理できるファイルとして送信されます。 Thread インスタンスを返し、このインスタンスの start() を呼び出してサーバを起動し、適切なところで join() を呼び出すことができます。サーバを停止するには、 stopListening() を呼び出します。

verify 引数を指定する場合は、これはソケットを通して受け取ったバイト文字列が妥当であるか、処理すべきであるかどうかを検査する callable である必要があります。ソケットを通じて、暗号化または署名あるいはその両方を受け取ることがあります。そのような場合に、 verify callable が署名の正当性検査または暗号化の復号あるいはその両方を実施することが出来ます。 verify callable は単一引数で呼び出されます - ソケットを通じて受け取ったバイト文字列です - そして処理すべきバイト文字列、または捨て去られるべきであることを示すための None を返す必要があります。返却されるバイト文字列は(たとえば正当性検査だけが行われて)渡されたものと同じかもしれませんし、あるいは(おそらく暗号化の復号が行われて)まったく異なるものかもしれません。

ソケットに設定を送るには、まず設定ファイルを読み、それを struct.pack('>L', n) を使って長さ 4 バイトのバイナリにパックしたものを前に付けたバイト列としてソケットに送ります。

注釈

設定の一部は eval() を通じて渡されるため、この関数を利用することはユーザーをセキュリティ上のリスクにさらす可能性があります。この関数は localhost のソケットだけにバインドされており、リモートマシンからの接続を受け付けませんが、それでも listen() を呼び出したプロセスのアカウントのもとで信頼できないコードが実行されうるシナリオが存在します。特に、 listen() を呼び出したプロセスが複数のユーザーが利用するマシン上で実行されており、ユーザー同士が互いに信頼できない場合、悪意あるユーザーが被害者ユーザーのプロセス上で本質的に任意のコードを実行するように計画する可能性があります。攻撃は、単に被害者ユーザーの listen() ソケットに接続して、被害者ユーザーのプロセス上で攻撃者が実行したいコードが実行されるような設定を送り込むだけです。この攻撃はデフォルトのポートが使われている場合きわめて容易であり、異なるポートが使われている場合でもそれほど難しくはありません。このような事象が発生するリスクを回避するためには、 listen() の verify 引数を使って不正な設定が適用されるのを防ぐようにしてください。

バージョン 3.4 で変更: verify 引数が追加されました。

注釈

既存のロガーを無効にしない構成をリスナーに送信する場合は、設定にはJSONフォーマットを使用する必要があります。これは、設定に dictConfig() を使用します。 このメソッドを使用すると、 disable_existing_loggers に False を指定した設定を送信できます。

logging.config.stopListening()

listen() を呼び出して作成された、待ち受け中のサーバを停止します。通常 listen() の戻り値に対して join() が呼ばれる前に呼び出します。

セキュリティで考慮すべき点

logging の設定機能は便利さを提供します。その便利さの一部は設定ファイル内のテキストを logging の設定に使われる Python オブジェクトに変換する機能を提供することによって実現されています - たとえば、 ユーザ定義オブジェクト で説明されているような機能です。しかし、まさにこのメカニズム (実行可能オブジェクトをユーザー定義モジュールからインポートし、設定ファイルから読み込んだパラメータを使ってそれらを呼び出すこと) が任意のコードを呼び出すことに利用できる可能性があります。そして、この理由により、信頼できない情報源から取得した設定ファイルは 細心の注意 を払って取り扱わなければなりません。そのようなファイルをロードする場合、そのファイルがいかなる問題も起こさないと確認した上で実際にファイルをロードしてください。

環境設定辞書スキーマ

ロギング設定を記述するには、生成するさまざまなオブジェクトと、それらのつながりを列挙しなければなりません。例えば、 'console' という名前のハンドラを生成し、'startup' という名前のロガーがメッセージを 'console' ハンドラに送るというようなことを記述します。これらのオブジェクトは、 logging モジュールによって提供されるものに限らず、独自のフォーマッタやハンドラクラスを書くことも出来ます。このクラスへのパラメータは、 sys.stderr のような外部オブジェクトを必要とすることもあります。これらのオブジェクトとつながりを記述する構文は、以下の オブジェクトの接続 で定義されています。

辞書スキーマの詳細

dictConfig() に渡される辞書は、以下のキーを含んでいなければなりません:

version - スキーマのバージョンを表す整数値に設定されます。現在有効な値は 1 だけですが、このキーがあることで、このスキーマは後方互換性を保ちながら発展できます。

その他すべてのキーは省略可能ですが、与えられたなら以下に記述するように解釈されます。以下のすべての場合において、 '環境設定辞書' と記載されている所では、その辞書に特殊な '()' キーがあるかを調べることで、カスタムのインスタント化が必要であるか判断されます。その場合は、以下の ユーザ定義オブジェクト で記述されている機構がインスタンス生成に使われます。そうでなければ、インスタンス化するべきものを決定するのにコンテキストが使われます。

formatters - 対応する値は辞書で、そのそれぞれのキーがフォーマッタ id になり、それぞれの値が対応する Formatter インスタンスをどのように環境設定するかを記述する辞書になります。

設定辞書は Formatter オブジェクトを作成するときの引数に対応する、次のようなオプションキーがないか探索されます。

format

datefmt

style

validate (バージョン3.8以降)

defaults (since version >=3.12)

オプションの class キーはフォーマッタークラスの名前を表します（モジュールとクラス名をドットで繋げる）。インスタンス化時の引数は Formatter と同じであるため、このキーは Formatter をカスタマイズしたサブクラスのインスタンス化に使うのがもっとも便利です。例えばトレースバックにさらに情報を付加したり、情報を要約代替クラスを実装するといったことが想定されます。もし、自作のフォーマッターが異なる引数や追加の設定引数を持つ場合は、 ユーザ定義オブジェクト を使うべきです。

filters - 対応する値は辞書で、そのそれぞれのキーがフィルタ id になり、それぞれの値が対応する Filter インスタンスをどのように環境設定するかを記述する辞書になります。

環境設定辞書は、(デフォルトが空文字列の) キー name を検索され、それらが logging.Filter インスタンスを構成するのに使われます。

handlers - 対応する値は辞書で、そのそれぞれのキーがハンドラ id になり、それぞれの値が対応する Handler インスタンスをどのように環境設定するかを記述する辞書になります。

環境設定辞書は、以下のキーを検索されます:

class (必須)。これはハンドラクラスの完全に修飾された名前です。

level (任意)。ハンドラのレベルです。

formatter (任意)。このハンドラへのフォーマッタの id です。

filters (任意)。このハンドラへのフィルタの id のリストです。

バージョン 3.11 で変更: filters は id に加えてフィルタのインスタンスを受け取ることができるようになりました。

その他の すべての キーは、ハンドラのコンストラクタにキーワード引数として渡されます。例えば、以下のコード片が与えられたとすると:

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

id が console であるハンドラが、 sys.stdout を根底のストリームにして、 logging.StreamHandler としてインスタンス化されます。id が file であるハンドラが、 filename='logconfig.log', maxBytes=1024, backupCount=3 をキーワード引数にして、 logging.handlers.RotatingFileHandler としてインスタンス化されます。

loggers - 対応する値は辞書で、そのそれぞれのキーがロガー名になり、それぞれの値が対応する Logger インスタンスをどのように環境設定するかを記述する辞書になります。

環境設定辞書は、以下のキーを検索されます:

level (任意)。ロガーのレベルです。

propagate (任意)。ロガーの伝播の設定です。

filters (任意)。このロガーへのフィルタの id のリストです。

バージョン 3.11 で変更: filters は id に加えてフィルタのインスタンスを受け取ることができるようになりました。

handlers (任意)。このロガーへのハンドラの id のリストです。

指定されたロガーは、指定されたレベル、伝播、ハンドラに従って環境設定されます。

root - これは、ルートロガーへの設定になります。この環境設定の進行は、propagate 設定が適用されないことを除き、他のロガーと同じです。

incremental - この環境設定が既存の環境設定に対する増分として解釈されるかどうかです。この値のデフォルトは False で、指定された環境設定は、既存の fileConfig() API によって使われているのと同じ意味上で、既存の環境設定を置き換えます。

指定された値が True なら、環境設定は 増分設定 の節で記述されているように進行します。

disable_existing_loggers - 既存の非ルートロガーをすべて無効にするべきかどうかです。この設定は、 fileConfig() における同じ名前のパラメータと同じです。設定されていなければ、このパラメータのデフォルトは True です。この値は、 incremental が True なら無視されます。

増分設定

増分設定に完全な柔軟性を提供するのは難しいです。例えば、フィルタやフォーマッタのようなオブジェクトは匿名なので、一旦環境設定がなされると、設定を拡張するときにそのような匿名オブジェクトを参照することができません。

さらに、一旦環境設定がなされた後、実行時にロガー、ハンドラ、フィルタ、フォーマッタのオブジェクトグラフを任意に変えなければならない例もありません。ロガーとハンドラの冗長性は、レベル (または、ロガーの場合には、伝播フラグ) を設定することによってのみ制御できます。安全な方法でオブジェクトグラフを任意に変えることは、マルチスレッド環境で問題となります。不可能ではないですが、その効用は実装に加えられる複雑さに見合いません。

従って、環境設定辞書の incremental キーが与えられ、これが True であるとき、システムは formatters と filters の項目を完全に無視し、handlers の項目の level 設定と、loggers と root の項目の level と propagate 設定のみを処理します。

環境設定辞書の値を使うことで、設定は pickle 化された辞書としてネットワークを通してソケットリスナに送ることができます。これにより、長時間起動するアプリケーションのロギングの冗長性を、アプリケーションを止めて再起動する必要なしに、いつでも変更することができます。

オブジェクトの接続

このスキーマは、ロギングオブジェクトの一揃い - ロガー、ハンドラ、フォーマッタ、フィルタ - について記述します。これらは、オブジェクトグラフ上でお互い接続されます。従って、このスキーマは、オブジェクト間の接続を表現しなければなりません。例えば、環境設定で、特定のロガーが特定のハンドラに取り付けられたとします。この議論では、ロガーとハンドラが、これら 2 つの接続のそれぞれ送信元と送信先であるといえます。もちろん、この設定オブジェクト中では、これはハンドラへの参照を保持しているロガーで表されます。設定辞書中で、これは次のようになされます。まず、送信先オブジェクトを曖昧さなく指定する id を与えます。そして、その id を送信元オブジェクトの環境設定で使い、送信元とその id をもつ送信先が接続されていることを示します。

ですから、例えば、以下の YAML のコード片を例にとると:

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]

(注釈: YAML がここで使われているのは、辞書の等価な Python 形式よりもこちらのほうが少し読みやすいからです。)

ロガーの id は、プログラム上でロガーへの参照を得るために使われるロガー名で、たとえば foo.bar.baz です。フォーマッタとフィルタの id は、(上の brief, precise のような) 任意の文字列値にできます。これらは一時的なもので、環境設定辞書の処理にのみ意味があり、オブジェクト間の接続を決定するのに使われます。また、これらは設定の呼び出しが完了したとき、どこにも残りません。

上記のコード片は、foo.bar.baz というの名ロガーに、ハンドラ id h1 と h2 で表される 2 つのハンドラを接続することを示します。h1 のフォーマッタは id brief で記述されるもので、h2 のフォーマッタは id precise で記述されるものです。

ユーザ定義オブジェクト

このスキーマは、ハンドラ、フィルタ、フォーマッタのための、ユーザ定義オブジェクトをサポートします。(ロガーは、異なるインスタンスに対して異なる型を持つ必要はないので、この環境設定スキーマは、ユーザ定義ロガークラスをサポートしていません。)

設定されるオブジェクトは、それらの設定を詳述する辞書によって記述されます。場所によっては、あるオブジェクトがどのようにインスタンス化されるかというコンテキストを、ロギングシステムが推測できます。しかし、ユーザ定義オブジェクトがインスタンス化されるとき、システムはどのようにこれを行うかを知りません。ユーザ定義オブジェクトのインスタンス化を完全に柔軟なものにするため、ユーザは 'ファクトリ' - 設定辞書を引数として呼ばれ、インスタンス化されたオブジェクトを返す呼び出し可能オブジェクト - を提供する必要があります。これは特殊キー '()' で利用できる、ファクトリへの絶対インポートパスによって合図されます。ここに具体的な例を挙げます:

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

上記の YAML コード片は 3 つのフォーマッタを定義します。 1 つ目は、id が brief で、指定されたフォーマット文字列をもつ、標準 logging.Formatter インスタンスです。 2 つ目は、id が default で、長いフォーマットを持ち、時間フォーマットも定義していて、結果はその 2 つのフォーマット文字列で初期化された logging.Formatter になります。Python ソース形式で見ると、 brief と default フォーマッタは、それぞれ設定の部分辞書:

{
  'format' : '%(message)s'
}

および:

{
  'format' : '%(asctime)s %(levelname)-8s %(name)-15s %(message)s',
  'datefmt' : '%Y-%m-%d %H:%M:%S'
}

を持ち、これらの辞書が特殊キー '()' を持たないので、インスタンス化はコンテキストから推測され、結果として標準の logging.Formatter インスタンスが生成されます。id が custom である、3 つ目のフォーマッタの設定をする部分辞書は:

{
  '()' : 'my.package.customFormatterFactory',
  'bar' : 'baz',
  'spam' : 99.9,
  'answer' : 42
}

で、ユーザ定義のインスタンス化が望まれることを示す特殊キー '()' を含みます。この場合、指定された呼び出し可能ファクトリオブジェクトが使われます。これが実際の呼び出し可能オブジェクトであれば、それが直接使われます - そうではなく、(この例でのように) 文字列を指定したなら、実際の呼び出し可能オブジェクトは、通常のインポート機構を使って検索されます。その呼び出し可能オブジェクトは、環境設定の部分辞書の、残りの 要素をキーワード引数として呼ばれます。上記の例では、id が custom のフォーマッタは、以下の呼び出しによって返されるものとみなされます:

my.package.customFormatterFactory(bar='baz', spam=99.9, answer=42)

警告

上記の例で bar, spam または answer のようなキーワード引数に指定する値は、設定作業の途中で処理されることなくそのまま呼び出し可能オブジェクトに渡されるため、 cfg://foo や ext://bar のような設定用の辞書や参照であってはいけません。

キー '()' が特殊キーとして使われるのは、キーワードパラメータ名として不正で、呼び出しに使われるキーワード引数と衝突し得ないからです。'()' はまた、対応する値が呼び出し可能オブジェクトであると覚えやすくします。

バージョン 3.11 で変更: handlers と loggers の filters メンバーは id に加えてフィルタのインスタンスを受け取ることができるようになりました。

特殊なキーワード '.' を指定することもできます。この場合その値には属性名とその値のマッピングをあらわす辞書を指定します。指定された属性は、もしそれが見つかった場合、戻り値のユーザー定義オブジェクトに設定されます。したがって、以下のように設定すると:

{
  '()' : 'my.package.customFormatterFactory',
  'bar' : 'baz',
  'spam' : 99.9,
  'answer' : 42,
  '.' {
    'foo': 'bar',
    'baz': 'bozz'
  }
}

戻り値のフォーマッタは属性 foo と``baz`` をもち、それぞれの値は 'bar' と 'bozz' に設定されます。

警告

上記の例で foo や baz のような属性に設定する値は、フォーマッタの設定作業の途中で処理されることなくそのまま属性値として設定されるため、 cfg://foo や ext://bar のような設定用の辞書や参照であってはいけません。

ハンドラの設定順序

ハンドラは対応するキーのアルファベット順に設定され、設定されたハンドラはスキーマ中の環境設定辞書における handlers 辞書 (の作業コピー) を差し替えます。たとえば cfg://handlers.foo という設定において、最初に handlers['foo']``が ``foo という名前のハンドラに対する環境設定辞書を指しているとき、以後 (いったんハンドラが設定されると) 設定されたハンドラのインスタンスを指すようになります。その結果、 cfg://handlers.foo は辞書かハンドラのインスタンスのいずれかに解決される可能性があります。一般に、ハンドラは、依存するハンドラが全て設定された _あとに_ それらに依存するハンドラが設定されるように名前をつける方が賢明です; これにより、 foo という名前のハンドラに依存するハンドラを設定する際に cfg://handlers.foo で依存するハンドラを参照できるようになります。もし依存するハンドラの名前が bar であった場合、アルファベット順の規則から bar の設定が foo の設定よりも先に試みられることにより foo がまだ設定されていないかもしれないことから、問題が起こる可能性があります。一方、依存するハンドラの名前が foobar であった場合は、その設定は foo の後に行われることとなり、 cfg://handlers.foo は環境設定辞書ではなく設定済みのハンドラ foo のインスタンスに解決されます。

外部オブジェクトへのアクセス

環境設定が、例えば sys.stderr のような、設定の外部のオブジェクトへの参照を必要とすることがあります。設定辞書が Python コードで構成されていれば話は簡単ですが、これがテキストファイル (JSON, YAML 等) を通して提供されていると問題となります。テキストファイルでは、sys.stderr をリテラル文字列 'sys.stderr' と区別する標準の方法がありません。この区別を容易にするため、環境設定システムは、文字列中の特定の特殊接頭辞を見つけ、それらを特殊に扱います。例えば、リテラル文字列 'ext://sys.stderr' が設定中の値として与えられたら、この ext:// は剥ぎ取られ、この値の残りが普通のインポート機構で処理されます。

このような接頭辞の処理は、プロトコルの処理と同じようになされます。どちらの機構も、正規表現 ^(?P<prefix>[a-z]+)://(?P<suffix>.*)$ にマッチする接頭辞を検索し、それによって prefix が認識されたなら、接頭辞に応じたやり方で suffix が処理され、その処理の結果によって文字列値が置き換えられます。接頭辞が認識されなければ、その文字列値はそのまま残されます。

内部オブジェクトへのアクセス

外部オブジェクトと同様、環境設定内部のオブジェクトへのアクセスを必要とすることもあります。これは、その各オブジェクトを司る環境設定システムによって暗黙に行われます。例えば、ロガーやハンドラの level に対する文字列値 'DEBUG' は、自動的に値 logging.DEBUG に変換されますし、handlers, filters および formatter の項目は、オブジェクト id を取って、適切な送信先オブジェクトを決定します。

しかし、ユーザ定義モジュールには、 logging モジュールには分からないような、より一般的な機構が必要です。例えば、 logging.handlers.MemoryHandler があって、委譲する先の別のハンドラである target 引数を取るとします。システムはこのクラスをすでに知っていますから、設定中で、与えられた target は関連するターゲットハンドラのオブジェクト id でさえあればよく、システムはその id からハンドラを決定します。しかし、ユーザが my.package.MyHandler を定義して、それが alternate ハンドラを持つなら、設定システムは alternate がハンドラを参照していることを知りません。これを知らせるのに、一般的な解析システムで、ユーザはこのように指定できます:

handlers:
  file:
    # configuration of file handler goes here

  custom:
    (): my.package.MyHandler
    alternate: cfg://handlers.file

リテラル文字列 'cfg://handlers.file' は、ext:// 接頭辞が付いた文字列と同じように分析されますが、インポート名前空間ではなく、環境設定自体が検索されます。この機構は str.format でできるのと同じようにドットやインデックスのアクセスができます。従って、環境設定において以下のコード片が与えられれば:

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.

in the configuration, the string 'cfg://handlers' would resolve to the dict with key handlers, the string 'cfg://handlers.email would resolve to the dict with key email in the handlers dict, and so on. The string 'cfg://handlers.email.toaddrs[1] would resolve to 'dev_team@domain.tld' and the string 'cfg://handlers.email.toaddrs[0]' would resolve to the value 'support_team@domain.tld'. The subject value could be accessed using either 'cfg://handlers.email.subject' or, equivalently, 'cfg://handlers.email[subject]'. The latter form only needs to be used if the key contains spaces or non-alphanumeric characters. 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.

文字列 cfg://handlers.myhandler.mykey.123 が与えられると、これは config_dict['handlers']['myhandler']['mykey']['123'] と分析されます。文字列が cfg://handlers.myhandler.mykey[123] と指定されたら、システムは config_dict['handlers']['myhandler']['mykey'][123] から値を引き出そうとし、失敗したら config_dict['handlers']['myhandler']['mykey']['123'] で代替します。

インポート解決とカスタムインポーター

インポート解決は、デフォルトではインポートを行うために __import__() 組み込み関数を使用します。これを独自のインポートメカニズムに置き換えたいと思うかもしれません: もしそうなら、 DictConfigurator あるいはその上位クラスである BaseConfigurator クラスの importer 属性を置換することができます。ただし、この関数はクラスからディスクリプタ経由でアクセスされる点に注意する必要があります。インポートを行うために Python callable を使用していて、それをインスタンスレベルではなくクラスレベルで定義したければ、 staticmethod() でそれをラップする必要があります。例えば:

from importlib import import_module
from logging.config import BaseConfigurator

BaseConfigurator.importer = staticmethod(import_module)

configurator インスタンス に対してインポート callable をセットする場合は、 staticmethod() でラップする必要はありません。

Configuring QueueHandler and QueueListener

If you want to configure a QueueHandler, noting that this is normally used in conjunction with a QueueListener, you can configure both together. After the configuration, the QueueListener instance will be available as the listener attribute of the created handler, and that in turn will be available to you using getHandlerByName() and passing the name you have used for the QueueHandler in your configuration. The dictionary schema for configuring the pair is shown in the example YAML snippet below.

handlers:
  qhand:
    class: logging.handlers.QueueHandler
    queue: my.module.queue_factory
    listener: my.package.CustomListener
    handlers:
      - hand_name_1
      - hand_name_2
      ...

The queue and listener keys are optional.

If the queue key is present, the corresponding value can be one of the following:

An actual instance of queue.Queue or a subclass thereof. This is of course only possible if you are constructing or modifying the configuration dictionary in code.

A string that resolves to a callable which, when called with no arguments, returns the queue.Queue instance to use. That callable could be a queue.Queue subclass or a function which returns a suitable queue instance, such as my.module.queue_factory().

A dict with a '()' key which is constructed in the usual way as discussed in ユーザ定義オブジェクト. The result of this construction should be a queue.Queue instance.

If the queue key is absent, a standard unbounded queue.Queue instance is created and used.

If the listener key is present, the corresponding value can be one of the following:

A subclass of logging.handlers.QueueListener. This is of course only possible if you are constructing or modifying the configuration dictionary in code.

A string which resolves to a class which is a subclass of QueueListener, such as 'my.package.CustomListener'.

A dict with a '()' key which is constructed in the usual way as discussed in ユーザ定義オブジェクト. The result of this construction should be a callable with the same signature as the QueueListener initializer.

If the listener key is absent, logging.handlers.QueueListener is used.

The values under the 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 QueueHandler and QueueListener.

Added in version 3.12.

環境設定ファイルの書式

fileConfig() が解釈できる環境設定ファイルの形式は、 configparser の機能に基づいています。ファイルには、 [loggers], [handlers], [formatters] といったセクションが入っていなければならず、各セクションではファイル中で定義されている各タイプのエンティティを名前で指定しています。こうしたエンティティの各々について、そのエンティティをどう設定するかを示した個別のセクションがあります。すなわち、 log01 という名前の [loggers] セクションにあるロガーに対しては、対応する詳細設定がセクション [logger_log01] に収められています。同様に、 hand01 という名前の [handlers] セクションにあるハンドラは [handler_hand01] と呼ばれるセクションに設定をもつことになり、 [formatters] セクションにある form01 は [formatter_form01] というセクションで設定が指定されています。ルートロガーの設定は [logger_root] と呼ばれるセクションで指定されていなければなりません。

注釈

fileConfig() API は dictConfig() API よりも古く、ロギングのある種の側面についてカバーする機能に欠けています。たとえば fileConfig() では数値レベルを超えたメッセージを単に拾うフィルタリングを行う Filter オブジェクトを構成出来ません。 Filter のインスタンスをロギングの設定において持つ必要があるならば、 dictConfig() を使う必要があるでしょう。設定の機能における将来の拡張は dictConfig() に対して行われることに注意してください。ですから、そうするのが便利であるときに新しい API に乗り換えるのは良い考えです。

ファイルにおけるこれらのセクションの例を以下に示します。

[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

ルートロガーでは、レベルとハンドラのリストを指定しなければなりません。ルートロガーのセクションの例を以下に示します。

[logger_root]
level=NOTSET
handlers=hand01

level エントリは DEBUG, INFO, WARNING, ERROR, CRITICAL または NOTSET のいずれかの値を取ることができます。ルートロガーでのみ、 NOTSET は全てのメッセージがログとして記録されることを意味します。レベルの値は logging パッケージの名前空間のコンテキストで 評価 されます。

handlers エントリはコンマで区切られたハンドラ名からなるリストで、[handlers] セクションになくてはなりません。また、これらの各ハンドラの名前に対応するセクションが設定ファイルに存在しなければなりません。

ルートロガー以外のロガーでは、いくつか追加の情報が必要になります。これは以下の例のように表されます。

[logger_parser]
level=DEBUG
handlers=hand01
propagate=1
qualname=compiler.parser

level および handlers エントリはルートロガーのエントリと同様に解釈されますが、非ルートロガーのレベルが NOTSET に指定された場合、ロギングシステムはロガー階層のより上位のロガーにロガーの実効レベルを問い合わせるところが違います。propagate エントリは、メッセージをロガー階層におけるこのロガーの上位のハンドラに伝播させることを示す 1 に設定されるか、メッセージを階層の上位に伝播 しない ことを示す 0 に設定されます。qualname エントリはロガーのチャネル名を階層的に表したもの、すなわちアプリケーションがこのロガーを取得する際に使う名前になります。

ハンドラの環境設定を指定しているセクションは以下の例のようになります。

[handler_hand01]
class=StreamHandler
level=NOTSET
formatter=form01
args=(sys.stdout,)

class エントリはハンドラのクラス (logging パッケージの名前空間において eval() で決定されます) を示します。 level はロガーの場合と同じように解釈され、 NOTSET は "すべてを記録する (log everything)" と解釈されます。

formatter エントリはこのハンドラのフォーマッタに対するキー名を表します。空文字列の場合、デフォルトのフォーマッタ (logging._defaultFormatter) が使われます。名前が指定されている場合、その名前は [formatters] セクションになくてはならず、対応するセクションが設定ファイル中になければなりません。

args は、 logging パッケージの名前空間のコンテキストで 評価 される時点では、ハンドラークラスのコンストラクタのための引数のリストです。典型的なコンストラクタの引数が生成される方法については、各ハンドラのコンストラクタまたは下記の例を参照してください。指定されなければデフォルトは () になります。

オプションの kwargs は、 logging パッケージの名前空間のコンテキストで 評価 される時点では、ハンドラークラスのコンストラクタのためのキーワード引数の辞書です。指定されなければデフォルトは {} になります。

[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', '', '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}

フォーマッタの環境設定を指定しているセクションは以下のような形式です。

[formatter_form01]
format=F1 %(asctime)s %(levelname)s %(message)s %(customfield)s
datefmt=
style=%
validate=True
defaults={'customfield': 'defaultvalue'}
class=logging.Formatter

フォーマッターのセクション の辞書スキーマと同じキーを持つ、フォーマッター設定の引数です。

The defaults entry, when evaluated in the context of the logging package's namespace, is a dictionary of default values for custom formatting fields. If not provided, it defaults to None.

注釈

eval() を使用していることで、上述のようにソケット経由で設定を送受信するために listen() を使用していることに起因する潜在的なセキュリティリスクがあります。そのリスクは、相互に信頼できない多数のユーザが同じマシン上でコードを実行する場合に制限されています; 詳細は listen() ドキュメンテーションを参照してください。

参考

logging モジュール

logging モジュールの API リファレンス。

logging.handlers モジュール

logging モジュールに含まれる、便利なハンドラです。

logging.handlers --- Logging handlers

ソースコード: Lib/logging/handlers.py [https://github.com/python/cpython/tree/3.12/Lib/logging/handlers.py]

Important

このページには、リファレンス情報だけが含まれています。チュートリアルは、以下のページを参照してください

基本チュートリアル

上級チュートリアル

ロギングクックブック

このパッケージでは、以下の便利なハンドラが提供されています。なお、これらのハンドラのうち、3 つ (StreamHandler, FileHandler および NullHandler) は、実際には logging モジュール自身で定義されていますが、他のハンドラと一緒にここでドキュメント化します。

StreamHandler

logging コアパッケージに含まれる StreamHandler クラスは、ログ出力を sys.stdout, sys.stderr あるいは何らかのファイル風 (file-like) オブジェクト (あるいは、より正確に言えば write() および flush() メソッドをサポートする何らかのオブジェクト) といったストリームに送信します。

class logging.StreamHandler(stream=None)

StreamHandler クラスの新たなインスタンスを返します。 stream が指定された場合、インスタンスはログ出力先として指定されたストリームを使います; そうでない場合、 sys.stderr が使われます。

emit(record)

フォーマッタが指定されていれば、フォーマッタを使ってレコードを書式化します。 次に、レコードが terminator とともにストリームに書き込まれます。 例外情報が存在する場合、 traceback.print_exception() を使って書式化され、 ストリームの末尾につけられます。

flush()

ストリームの flush() メソッドを呼び出してバッファをフラッシュします。 close() メソッドは Handler から継承しているため何も出力を行わないので、 flush() 呼び出しを明示的に行う必要があるかもしれません。

setStream(stream)

このインスタンスの stream と指定された値が異なる場合、指定された値に設定します。新しい stream を設定する前に、古い stream はフラッシュされます。

パラメータ:

stream -- ハンドラがこれから使う stream 。

戻り値:

the old stream, if the stream was changed, or None if it wasn't.

Added in version 3.7.

terminator

フォーマット済みのレコードをストリームに出力するときの終端として使われる文字列です。デフォルト値は '\n' です。

もし改行区切りにしたくない場合はハンドラーインスタンスの terminator 属性に空文字列を設定してください。

以前のバージョンでは、区切り文字は '\n' にハードコードされていました。

Added in version 3.2.

FileHandler

logging コアパッケージに含まれる FileHandler クラスは、ログ出力をディスク上のファイルに送信します。このクラスは出力機能を StreamHandler から継承しています。

class logging.FileHandler(filename, mode='a', encoding=None, delay=False, errors=None)

Returns a new instance of the FileHandler class. The specified file is opened and used as the stream for logging. If mode is not specified, 'a' is used. If encoding is not 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 emit(). By default, the file grows indefinitely. If errors is specified, it's used to determine how encoding errors are handled.

バージョン 3.6 で変更: 文字列値に加え、 Path オブジェクトも filename 引数が受け取るようになりました。

バージョン 3.9 で変更: errors 引数が追加されました。

close()

ファイルを閉じます。

emit(record)

record をファイルに出力します。

終了時、ロギングがシャットダウンされたためにファイルがクローズされており、ファイルのモードが 'w' である場合、 record は出力されません (bpo-42378 [https://bugs.python.org/issue?@action=redirect&bpo=42378] を参照してください)。

NullHandler

Added in version 3.1.

logging コアパッケージに含まれる NullHandler クラスは、いかなる書式化も出力も行いません。これは本質的には、ライブラリ開発者に使われる 'no-op' ハンドラです。

class logging.NullHandler

NullHandler クラスの新しいインスタンスを返します。

emit(record)

このメソッドは何もしません。

handle(record)

このメソッドは何もしません。

createLock()

アクセスが特殊化される必要がある I/O が下にないので、このメソッドはロックに対して None を返します。

NullHandler の使い方の詳しい情報は、 ライブラリのためのロギングの設定 を参照してください。

WatchedFileHandler

logging.handlers モジュールに含まれる WatchedFileHandler クラスは、ログ記録先のファイルを監視する FileHandler の一種です。ファイルが変更された場合、ファイルを閉じてからファイル名を使って開き直します。

ファイルはログファイルをローテーションさせる newsyslog や logrotate のようなプログラムを使うことで変更されることがあります。このハンドラは、 Unix/Linux で使われることを意図していますが、ファイルが最後にログを出力してから変わったかどうかを監視します。 (ファイルはデバイスや inode が変わることで変わったと判断します。) ファイルが変わったら古いファイルのストリームは閉じて、現在のファイルを新しいストリームを取得するために開きます。

このハンドラを Windows で使うことは適切ではありません。というのも Windows では開いているログファイルを移動したり削除したりできないからです - logging はファイルを排他的ロックを掛けて開きます - そのためこうしたハンドラは必要ないのです。さらに、 Windows では ST_INO がサポートされていません; stat() はこの値として常に 0 を返します。

class logging.handlers.WatchedFileHandler(filename, mode='a', encoding=None, delay=False, errors=None)

Returns a new instance of the WatchedFileHandler class. The specified file is opened and used as the stream for logging. If mode is not specified, 'a' is used. If encoding is not 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 emit(). By default, the file grows indefinitely. If errors is provided, it determines how encoding errors are handled.

バージョン 3.6 で変更: 文字列値に加え、 Path オブジェクトも filename 引数が受け取るようになりました。

バージョン 3.9 で変更: errors 引数が追加されました。

reopenIfNeeded()

ファイルが変更されていないかチェックします。もし変更されていれば、手始めにレコードをファイルに出力し、既存のストリームはフラッシュして閉じられ、ファイルが再度開かれます。

Added in version 3.6.

emit(record)

レコードをファイルに出力しますが、最初に reopenIfNeeded() を呼び出して、変更があった場合はファイルを再度開きます。

BaseRotatingHandler

logging.handlers モジュールに存在する BaseRotatingHandler クラスは、ローテートを行うファイルハンドラ RotatingFileHandler と TimedRotatingFileHandler のベースクラスです。このクラスをインスタンス化する必要はありませんが、オーバーライドすることになるかもしれない属性とメソッドを持っています。

class logging.handlers.BaseRotatingHandler(filename, mode, encoding=None, delay=False, errors=None)

パラメータは FileHandler と同じです。属性は次の通りです:

namer

この属性に callable がセットされた場合、 rotation_filename() メソッドはこの callable に委譲されます。 callable に渡されるパラメータは rotation_filename() に渡されたものです。

注釈

namer 関数はロールオーバー中にかなりの回数呼ばれます。そのため、できるだけ単純で、速くあるべきです。さらに、それは与えられた入力に対しては常に同じ出力を返すべきです。そうでなければ、ロールオーバーの振る舞いは期待通りに動かないかもしれません。

namer 属性にローテーションの際に使われるファイル名に埋め込むための特定の属性を保持しようとする場合に注意が必要なことは、注意喚起しておくべきでしょう。たとえば RotatingFileHandler は、ローテーションが期待通りに動作するために、名前に連続した番号を含むようなファイル名のリストを持つことを期待します。また TimedRotatingFileHandler は (ハンドラの初期化時に渡された backupCount にもとづいて) 削除すべき古いファイルを決定しながら、古いログファイルを削除します。この仕組みが動作するためには、ファイル名は名前に含まれる日付や時刻でソート可能である必要があり、 namer はそれを尊重しなければなりません (namer がこの規則を尊重したくない場合、そのような namer は getFilesToDelete() メソッドが特定の命名規則に適合するようにオーバーライドされた TimedRotatingFileHandler の派生クラス内で使う必要があるでしょう)。

Added in version 3.3.

rotator

この属性に callable がセットされた場合、 rotate() メソッドはこの callable に委譲されます。 callable に渡されるパラメータは rotate() に渡されたものです。

Added in version 3.3.

rotation_filename(default_name)

ローテートを行う際にログファイルのファイル名を変更します。

このメソッドは、ファイル名をカスタマイズするために提供されます。

デフォルト実装は、ハンドラの 'namer' 属性が callable だった場合、その callable を呼んでデフォルト名を渡します。属性が callable でない場合 (デフォルトは None です)、名前は変更せずに返されます。

パラメータ:

default_name -- ログファイルのデフォルトのファイル名。

Added in version 3.3.

rotate(source, dest)

ローテートが行われる時、現在のログをローテートします。

デフォルト実装は、 ハンドラの 'rotator' 属性が callable だった場合、その callable を呼んで source と dest 引数を渡します。属性が callable でない場合 (デフォルトは None です)、単に source が destination に改名されます。

パラメータ:

source -- ソースファイル名。これは通常ベースファイル名 、例えば 'test.log' となります。

dest -- 変更先ファイル名。これは通常ソースファイルをローテートしたもの (例えば 'test.log.1') です。

Added in version 3.3.

これらの属性が存在する理由は、サブクラス化を省略できるようにするためです。 RotatingFileHandler と TimedRotatingFileHandler のインスタンスに対して同じ callable が使えます。もし namer や rotator callable が例外を上げれば、 emit() 呼び出しで発生した他の例外と同じ方法で、つまりハンドラの handleError() メソッドによって扱われます。

ローテート処理に大幅な変更を加える必要があれば、メソッドをオーバーライドすることができます。

例えば、 rotator と namer を使ってログローテートをカスタマイズする を参照してください。

RotatingFileHandler

logging.handlers モジュールに含まれる RotatingFileHandler クラスは、ディスク上のログファイルに対するローテーション処理をサポートします。

class logging.handlers.RotatingFileHandler(filename, mode='a', maxBytes=0, backupCount=0, encoding=None, delay=False, errors=None)

RotatingFileHandler クラスの新たなインスタンスを返します。指定されたファイルが開かれ、ログ記録のためのストリームとして使われます。 mode が指定されなかった場合、 'a' が使われます。 encoding が None でない場合、その値はファイルを開くときのエンコーディングとして使われます。 delay が真ならば、ファイルを開くのは最初の emit() 呼び出しまで遅らせられます。デフォルトでは、ファイルは無制限に大きくなりつづけます。 errors が提供されると、エンコーディングエラーの処理方法を決定します。

maxBytes および backupCount 値を指定することで、あらかじめ決められたサイズでファイルをロールオーバ (rollover) させることができます。指定サイズを超えそうになると、ファイルは閉じられ、暗黙のうちに新たなファイルが開かれます。ロールオーバは現在のログファイルの長さが maxBytes に近くなると常に起きますが、 maxBytes または backupCount がゼロならロールオーバは起きなくなってしまうので、一般的には backupCount を少なくとも 1 に設定し maxBytes を非ゼロにするのが良いでしょう。 backupCount が非ゼロのとき、システムは古いログファイルをファイル名に ".1", ".2" といった拡張子を追加して保存します。例えば、 backupCount が 5 で、基本のファイル名が app.log なら、 app.log, app.log.1, app.log.2 ... と続き、 app.log.5 までを得ることになります。ログの書き込み対象になるファイルは常に app.log です。このファイルが満杯になると、ファイルは閉じられ、 app.log.1 に名前が変更されます。 app.log.1, app.log.2 などが存在する場合、それらのファイルはそれぞれ app.log.2, app.log.3 といった具合に名前が変更されます。

バージョン 3.6 で変更: 文字列値に加え、 Path オブジェクトも filename 引数が受け取るようになりました。

バージョン 3.9 で変更: errors 引数が追加されました。

doRollover()

上述のような方法でロールオーバを行います。

emit(record)

上述のようなロールオーバを行いながら、レコードをファイルに出力します。

TimedRotatingFileHandler

logging.handlers モジュールに含まれる TimedRotatingFileHandler クラスは、特定の時間間隔でのログローテーションをサポートしています。

class logging.handlers.TimedRotatingFileHandler(filename, when='h', interval=1, backupCount=0, encoding=None, delay=False, utc=False, atTime=None, errors=None)

TimedRotatingFileHandler クラスの新たなインスタンスを返します。 filename に指定したファイルを開き、ログ出力先のストリームとして使います。ログファイルのローテーション時には、ファイル名に拡張子 (suffix) をつけます。ログファイルのローテーションは when および interval の積に基づいて行います。

when は interval の単位を指定するために使います。使える値は下表の通りです。大小文字の区別は行いません。

値

interval の単位

atTime の使用有無/使用方法

'S'

秒

無視

'M'

分

無視

'H'

時間

無視

'D'

日

無視

'W0'-'W6'

曜日 (0=月曜)

初期のロールオーバー時刻の算出に使用

'midnight'

atTime が指定されなかった場合は深夜に、そうでない場合は atTime の時刻にロールオーバーされます

初期のロールオーバー時刻の算出に使用

曜日ベースのローテーションを使う場合は、月曜として 'W0' を、火曜として 'W1' を、…、日曜として 'W6' を指定します。このケースの場合は、 interval は使われません。

古いログファイルの保存時、ロギングシステムによりファイル名に拡張子が付けられます。 ロールオーバ間隔によって、strftime の %Y-%m-%d_%H-%M-%S 形式またはその前方の一部を使って、日付と時間に基づいた拡張子が付けられます。

最初に次のロールオーバー時間を計算するとき (ハンドラが生成されるとき)、次のローテーションがいつ起こるかを計算するために、既存のログファイルの最終変更時刻または現在の時間が使用されます。

utc 引数が true の場合時刻は UTC になり、それ以外では現地時間が使われます。

backupCount がゼロでない場合、保存されるファイル数は高々 backupCount 個で、それ以上のファイルがロールオーバされる時に作られるならば、一番古いものが削除されます。削除のロジックは interval で決まるファイルを削除するので、 interval を変えると古いファイルが残ったままになることもあります。

delay が true なら、ファイルを開くのは emit() の最初の呼び出しまで延期されます。

atTime が None でない場合、それは datetime.time インスタンスでなければなりません。ロールオーバーが「夜中」「特定の曜日」に設定されていて、ロールが発生する時刻を指定します。 atTime の値は 初期 のロールオーバーの計算に使われますが、後続のロールオーバーは通常の間隔の計算で算出されます。

errors が指定されると、エンコーディングエラーの取り扱い方法を決定します。

注釈

最初のロールオーバーの計算はハンドラーが初期化されたときに行われます。後続のロールオーバーは、ロールオーバーが発生し、ロールオーバーが出力した時にのみ行われます。これを念頭に置いておかないと混乱する可能性があります。例えば、インターバルが 毎分 に設定されていて、1分ごとにログファイルが常に生成されるとは限りません。アプリケーションが実行されている間、1分に1回以上のログ出力されて いるとすると 毎分、分割されたログファイルが出力されますが、そうでなく、5分ごとに出力される場合は、出力されずにロールオーバーが実行されなかった時間分のギャップが生じます。

バージョン 3.4 で変更: atTime パラメータが追加されました。

バージョン 3.6 で変更: 文字列値に加え、 Path オブジェクトも filename 引数が受け取るようになりました。

バージョン 3.9 で変更: errors 引数が追加されました。

doRollover()

上述のような方法でロールオーバを行います。

emit(record)

上で説明した方法でロールオーバを行いながら、レコードをファイルに出力します。

getFilesToDelete()

ロールオーバーの一環として削除されるファイル名のリストを返します。それらのファイルは、ハンドラによって書き込まれた最も古いバックアップログファイルの絶対パスです。

SocketHandler

logging.handlers モジュールに含まれる SocketHandler クラスは、ログ出力をネットワークソケットに送信します。基底クラスでは TCP ソケットを用います。

class logging.handlers.SocketHandler(host, port)

アドレスが host および port で与えられた遠隔のマシンと通信するようにした SocketHandler クラスのインスタンスを生成して返します。

バージョン 3.4 で変更: port に None を指定すると、Unix ドメインソケットが host 値を用いて作られます - そうでない場合は TCP ソケットが作られます。

close()

ソケットを閉じます。

emit()

レコードの属性辞書を pickle して、バイナリ形式でソケットに書き込みます。ソケット操作でエラーが生じた場合、暗黙のうちにパケットは捨てられます。事前に接続が失われていた場合、接続を再度確立します。受信端でレコードを unpickle して LogRecord にするには、 makeLogRecord() 関数を使ってください。

handleError()

emit() の処理中に発生したエラーを処理します。よくある原因は接続の消失です。次のイベント発生時に再試行できるようにソケットを閉じます。

makeSocket()

サブクラスで必要なソケット形式を詳細に定義できるようにするためのファクトリメソッドです。デフォルトの実装では、 TCP ソケット (socket.SOCK_STREAM) を生成します。

makePickle(record)

レコードの属性辞書をバイナリ形式に pickle したものの先頭に長さ情報を付け、ソケットを介して送信できるようにして返します。この操作の詳細は次のコードと同等です:

data = pickle.dumps(record_attr_dict, 1)
datalen = struct.pack('>L', len(data))
return datalen + data

pickle が完全に安全というわけではないことに注意してください。セキュリティに関して心配なら、より安全なメカニズムを実装するためにこのメソッドをオーバーライドすると良いでしょう。例えば、 HMAC を使って pickle に署名して、受け取る側ではそれを検証することができます。あるいはまた、受け取る側でグローバルなオブジェクトの unpickle を無効にすることができます。

send(packet)

pickle したバイト文字列 packet をソケットに送信します。送信するバイト文字列のフォーマットは、 makePickle() のドキュメントで解説されています。

この関数はネットワークがビジーの時に発生する部分的送信に対応しています。

createSocket()

ソケットの生成を試みます。失敗時には、指数的な減速アルゴリズムを使います。最初の失敗時には、ハンドラは送ろうとしていたメッセージを落とします。続くメッセージが同じインスタンスで扱われたとき、幾らかの時間が経過するまで接続を試みません。デフォルトのパラメタは、最初の遅延時間が 1 秒で、その遅延時間の後でそれでも接続が確保できないなら、遅延時間は 2 倍づつになり、最大で 30 秒になります。

この働きは、以下のハンドラ属性で制御されます:

retryStart (最初の遅延時間、デフォルトは 1.0 秒)。

retryFactor (乗数、デフォルトは 2.0)。

retryMax (最大遅延時間、デフォルトは 30.0 秒)。

つまり、ハンドラが使われた 後に リモートリスナが起動した場合、メッセージが失われてしまうことがあります (ハンドラは、遅延時間が経過するまで接続を試みようとさえせず、その遅延時間中に通知なくメッセージを捨てるので)。

DatagramHandler

logging.handlers モジュールに含まれる DatagramHandler クラスは、 SocketHandler を継承しており、 UDP ソケットを介したログ記録メッセージの送信をサポートしています。

class logging.handlers.DatagramHandler(host, port)

アドレスが host および port で与えられた遠隔のマシンと通信するようにした DatagramHandler クラスのインスタンスを生成して返します。

注釈

UDP はストリーミングプロトコルではないため、このハンドラのインスタンスと host に指定したホストとの間に持続的なコネクションはありません。この理由から、ネットワークソケットを使う場合、イベントがログされるごとに DNS のルックアップを行わなければならないかもしれず、それによりシステムにある程度の待ち時間をもたらす可能性があります。この待ち時間が問題になる場合、自身でルックアップを行い、ホスト名の代わりにルックアップの結果得られた IP アドレスを使ってハンドラを初期化することができます。

バージョン 3.4 で変更: port に None を指定すると、Unix ドメインソケットが host 値を用いて作られます - そうでない場合は UDP ソケットが作られます。

emit()

レコードの属性辞書を pickle して、バイナリ形式でソケットに書き込みます。ソケット操作でエラーが生じた場合、暗黙のうちにパケットは捨てられます。事前に接続が失われていた場合、接続を再度確立します。受信端でレコードを unpickle して LogRecord にするには、 makeLogRecord() 関数を使ってください。

makeSocket()

ここで SocketHandler のファクトリメソッドをオーバライドして、 UDP ソケット (socket.SOCK_DGRAM) を生成しています。

send(s)

pickle したバイト文字列をソケットに送信します。送信するバイト文字列のフォーマットは、 SocketHandler.makePickle() のドキュメントで解説されています。

SysLogHandler

logging.handlers モジュールに含まれる SysLogHandler クラスは、ログ記録メッセージを遠隔またはローカルの Unix syslog に送信する機能をサポートしています。

class logging.handlers.SysLogHandler(address=('localhost', SYSLOG_UDP_PORT), facility=LOG_USER, socktype=socket.SOCK_DGRAM)

遠隔の Unix マシンと通信するための、 SysLogHandler クラスの新たなインスタンスを返します。マシンのアドレスは (host, port) のタプル形式をとる address で与えられます。 address が指定されない場合、 ('localhost', 514) が使われます。アドレスは UDP ソケットを使って開かれます。 (host, port) のタプル形式の代わりに文字列で "/dev/log" のように与えることもできます。この場合、 Unix ドメインソケットが syslog にメッセージを送るのに使われます。 facility が指定されない場合、 LOG_USER が使われます。開かれるソケットの型は、 socktype 引数に依り、デフォルトは socket.SOCK_DGRAM で、UDP ソケットを開きます。 (rsyslog のような新しい syslog デーモンと使うために) TCP ソケットを開くには、 socket.SOCK_STREAM の値を指定してください。

使用中のサーバが UDP ポート 514 を待機していない場合、 SysLogHandler が正常に動作していないように見える場合があります。その場合、ドメインソケットに使うべきアドレスを調べてください。そのアドレスはシステムによって異なります。例えば、Linux システムでは通常 '/dev/log' ですが、 OS X では '/var/run/syslog' です。プラットフォームを確認し、適切なアドレスを使う必要があります (アプリケーションを複数のプラットフォーム上で動作させる必要がある場合、実行時に確認する必要があるかもしれません)。Windows では、多くの場合、UDP オプションを使用する必要があります。

注釈

macOS 12.x (Monterey) において、 Apple 社は syslog デーモンの振る舞いを変更しました - デーモンはドメインソケットをの待ち受けを行いません。したがって、このシステム上では SysLogHandler が動作することは期待できません。

より詳細な情報は gh-91070 [https://github.com/python/cpython/issues/91070] を参照して下さい。

バージョン 3.2 で変更: socktype が追加されました。

close()

遠隔ホストへのソケットを閉じます。

createSocket()

Tries to create a socket and, if it's not a datagram socket, connect it to the other end. This method is called during handler initialization, but it's not regarded as an error if the other end isn't listening at this point - the method will be called again when emitting an event, if there is no socket at that point.

Added in version 3.11.

emit(record)

レコードは書式化された後、 syslog サーバに送信されます。例外情報が存在しても、サーバには 送信されません 。

バージョン 3.2.1 で変更: (参照: bpo-12168 [https://bugs.python.org/issue?@action=redirect&bpo=12168]) 初期のバージョンでは、 syslog デーモンに送られるメッセージは常に NUL バイトで終端していました。初期のバージョンの syslog デーモンが NUL 終端されたメッセージを期待していたからです - たとえ、それが適切な仕様 (RFC 5424 [https://datatracker.ietf.org/doc/html/rfc5424.html]) にはなかったとしても。 syslog デーモンの新しいバージョンは NUL バイトを期待せず、代わりにもしそれがある場合は削除します。さらに、より最近のデーモン (RFC 5424 により忠実なバージョン) は、メッセージの一部として NUL バイトを通します。

このような異なるデーモンの振る舞いすべてに対して syslog メッセージの取り扱いをより容易にするため、 NUL バイトの追加はクラスレベル属性 append_nul を使用して設定できるようになりました。これはデフォルトで True (既存の振る舞いを保持) ですが、 SysLogHandler インスタンスが NUL 終端文字を追加 しない ように False にセットすることができます。

バージョン 3.3 で変更: (参照: bpo-12419 [https://bugs.python.org/issue?@action=redirect&bpo=12419]) 以前のバージョンでは、メッセージソースを識別するための "ident" あるいは "tag" プリフィックス機能はありませんでした。これは、今ではクラスレベル属性を使用して指定することができるようになりました。デフォルトでは既存の振る舞いを保持するために "" ですが、特定の SysLogHandler インスタンスが扱うすべてのメッセージに識別子を前置するようにそれをオーバーライドすることができます。識別子はバイトではなくテキストでなければならず、正確にそのままメッセージに前置されることに注意してください。

encodePriority(facility, priority)

ファシリティおよび優先度を整数に符号化します。値は文字列でも整数でも渡すことができます。文字列が渡された場合、内部の対応付け辞書が使われ、整数に変換されます。

シンボリックな LOG_ 値は SysLogHandler で定義されています。これは sys/syslog.h ヘッダーファイルで定義された値を反映しています。

優先度

名前 (文字列)

シンボル値

alert

LOG_ALERT

crit or critical

LOG_CRIT

debug

LOG_DEBUG

emerg or panic

LOG_EMERG

err or error

LOG_ERR

info

LOG_INFO

notice

LOG_NOTICE

warn or warning

LOG_WARNING

ファシリティ

名前 (文字列)

シンボル値

auth

LOG_AUTH

authpriv

LOG_AUTHPRIV

cron

LOG_CRON

daemon

LOG_DAEMON

ftp

LOG_FTP

kern

LOG_KERN

lpr

LOG_LPR

mail

LOG_MAIL

news

LOG_NEWS

syslog

LOG_SYSLOG

user

LOG_USER

uucp

LOG_UUCP

local0

LOG_LOCAL0

local1

LOG_LOCAL1

local2

LOG_LOCAL2

local3

LOG_LOCAL3

local4

LOG_LOCAL4

local5

LOG_LOCAL5

local6

LOG_LOCAL6

local7

LOG_LOCAL7

mapPriority(levelname)

ログレベル名を syslog 優先度名に対応付けます。カスタムレベルを使用している場合や、デフォルトアルゴリズムがニーズに適していない場合には、このメソッドをオーバーライドする必要があるかもしれません。デフォルトアルゴリズムは、 DEBUG, INFO, WARNING, ERROR, CRITICAL を等価な syslog 名に、他のすべてのレベル名を "warning" に対応付けます。

NTEventLogHandler

logging.handlers モジュールに含まれる NTEventLogHandler クラスは、ログ記録メッセージをローカルな Windows NT, Windows 2000, または Windows XP のイベントログに送信する機能をサポートします。この機能を使えるようにするには、 Mark Hammond による Python 用 Win32 拡張パッケージをインストールする必要があります。

class logging.handlers.NTEventLogHandler(appname, dllname=None, logtype='Application')

NTEventLogHandler クラスの新たなインスタンスを返します。 appname はイベントログに表示する際のアプリケーション名を定義するために使われます。この名前を使って適切なレジストリエントリが生成されます。 dllname はログに保存するメッセージ定義の入った .dll または .exe ファイルへの完全修飾パス名を与えなければなりません (指定されない場合、 'win32service.pyd' が使われます - このライブラリは Win32 拡張とともにインストールされ、いくつかのプレースホルダとなるメッセージ定義を含んでいます)。これらのプレースホルダを利用すると、メッセージの発信源全体がログに記録されるため、イベントログは巨大になるので注意してください。 logtype は 'Application', 'System', 'Security' のいずれかで、デフォルトは 'Application' です。

close()

現時点では、イベントログエントリの発信源としてのアプリケーション名をレジストリから除去することはできます。しかしこれを行うと、イベントログビューアで意図した通りにログが見えなくなるでしょう - これはイベントログが .dll 名を取得するためにレジストリにアクセスできなければならないからです。現在のバージョンではこの操作を行いません。

emit(record)

メッセージ ID、イベントカテゴリ、イベント型を決定し、メッセージを NT イベントログに記録します。

getEventCategory(record)

レコードに対するイベントカテゴリを返します。自作のカテゴリを指定したい場合、このメソッドをオーバライドしてください。このクラスのバージョンのメソッドは 0 を返します。

getEventType(record)

レコードのイベント型を返します。自作の型を指定したい場合、このメソッドをオーバライドしてください。このクラスのバージョンのメソッドは、ハンドラの typemap 属性を使って対応付けを行います。この属性は __init__() で初期化され、 DEBUG, INFO, WARNING, ERROR, CRITICAL が入っています。自作のレベルを使っているのなら、このメソッドをオーバライドするか、ハンドラの typemap 属性に適切な辞書を配置する必要があるでしょう。

getMessageID(record)

レコードのメッセージ ID を返します。自作のメッセージを使っているのなら、ロガーに渡される msg を書式化文字列ではなく ID にします。その上で、辞書参照を行ってメッセージ ID を得ます。このクラスのバージョンでは 1 を返します。この値は win32service.pyd における基本メッセージ ID です。

SMTPHandler

logging.handlers モジュールに含まれる SMTPHandler クラスは、 SMTP を介したログ記録メッセージの送信機能をサポートします。

class logging.handlers.SMTPHandler(mailhost, fromaddr, toaddrs, subject, credentials=None, secure=None, timeout=1.0)

新たな SMTPHandler クラスのインスタンスを返します。インスタンスは email の from および to アドレス行、および subject 行とともに初期化されます。 toaddrs は文字列からなるリストでなければなりません。非標準の SMTP ポートを指定するには、 mailhost 引数に (host, port) のタプル形式を指定します。文字列を使った場合、標準の SMTP ポートが使われます。もし SMTP サーバが認証を必要とするならば、 (username, password) のタプル形式を credentials 引数に指定することができます。

セキュアプロトコル (TLS) の使用を指定するには secure 引数にタプルを渡してください。これは認証情報が渡された場合のみ使用されます。タプルは、空のタプルか、キーファイルの名前を持つ1要素のタプルか、またはキーファイルと証明書ファイルの名前を持つ2要素のタプルのいずれかでなければなりません。 (このタプルは smtplib.SMTP.starttls() メソッドに渡されます。)

SMTP サーバとのコミュニケーションのために、 timeout 引数を使用してタイムアウトを指定することができます。

バージョン 3.3 で変更: Added the timeout parameter.

emit(record)

レコードを書式化し、指定されたアドレスに送信します。

getSubject(record)

レコードに応じたサブジェクト行を指定したいなら、このメソッドをオーバライドしてください。

MemoryHandler

logging.handlers モジュールに含まれる MemoryHandler は、ログ記録するレコードをメモリ上にバッファリングし、定期的にその内容をターゲット (target) となるハンドラにフラッシュする機能をサポートしています。フラッシュ処理はバッファが一杯になるか、ある深刻度かそれ以上のレベルを持つイベントが観測された際に行われます。

MemoryHandler はより一般的な抽象クラス、 BufferingHandler のサブクラスです。この抽象クラスでは、ログ記録するレコードをメモリ上にバッファリングします。各レコードがバッファに追加される毎に、 shouldFlush() を呼び出してバッファをフラッシュすべきかどうか調べます。フラッシュする必要がある場合、 flush() がフラッシュ処理を行うものと想定されます。

class logging.handlers.BufferingHandler(capacity)

容量つきのバッファーを設定してハンドラーが初期化されます。 capacity はバッファ可能なログレコード数を意味します。

emit(record)

レコードをバッファに追加します。 shouldFlush() が true を返す場合、バッファを処理するために flush() を呼び出します。

flush()

For a BufferingHandler instance, flushing means that it sets the buffer to an empty list. This method can be overwritten to implement more useful flushing behavior.

shouldFlush(record)

バッファが許容量に達している場合に True を返します。このメソッドは自作のフラッシュ処理方針を実装するためにオーバライドすることができます。

class logging.handlers.MemoryHandler(capacity, flushLevel=ERROR, target=None, flushOnClose=True)

MemoryHandler クラスの新たなインスタンスを返します。インスタンスはサイズ capacity （バッファされるレコード数）のバッファとともに初期化されます。 flushLevel が指定されていない場合、 ERROR が使われます。 target が指定されていない場合、ハンドラが何らかの意味のある処理を行う前に setTarget() でターゲットを指定する必要があります。 flushOnClose が False に指定されていた場合、ハンドラが閉じられるときにバッファはフラッシュ されません 。 flushOnClose が指定されていないか True に指定されていた場合、ハンドラが閉じられるときのバッファのフラッシュは以前の挙動になります。

バージョン 3.6 で変更: flushOnClose パラメータが追加されました。

close()

flush() を呼び出し、ターゲットを None に設定してバッファを消去します。

flush()

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

setTarget(target)

ターゲットハンドラをこのハンドラに設定します。

shouldFlush(record)

バッファが一杯になっているか、 flushLevel またはそれ以上のレコードでないかを調べます。

HTTPHandler

logging.handlers モジュールに含まれる HTTPHandler クラスは、ログ記録メッセージを GET または POST セマンティクスを使って Web サーバに送信する機能をサポートしています。

class logging.handlers.HTTPHandler(host, url, method='GET', secure=False, credentials=None, context=None)

HTTPHandler クラスの新たなインスタンスを返します。特別なポートを使う必要がある場合、host は host:port の形式で使うことができます。 method が指定されない場合、 GET が使われます。 secure が真の場合、HTTPS 接続が使われます。 HTTPS 接続で使用する SSL 設定のために context 引数を ssl.SSLContext のインスタンスに設定することができます。 credentials を指定する場合、BASIC 認証の際の HTTP 'Authorization' ヘッダに使われるユーザIDとパスワードからなる 2要素タプルを渡してください。 credentials を指定する場合、ユーザIDとパスワードが通信中に平文として剥き出しにならないよう、secure=True も指定すべきです。

バージョン 3.5 で変更: context パラメータが追加されました。

mapLogRecord(record)

URL エンコードされて Web サーバに送信することになる、 record に基づく辞書を供給します。デフォルトの実装では単に record.__dict__ を返します。例えば LogRecord のサブセットのみを Web サーバに送信する場合や、 サーバーに送信する内容を特別にカスタマイズする必要がある場合には、このメソッドをオーバライドできます。

emit(record)

レコードを URL エンコードされた辞書形式で Web サーバに送信します。レコードを送信のために辞書に変換するために mapLogRecord() が呼び出されます。

注釈

Web server に送信するためのレコードを準備することは一般的な書式化操作とは同じではありませんので、 setFormatter() を使って Formatter を指定することは、 HTTPHandler には効果はありません。 format() を呼び出す代わりに、このハンドラは mapLogRecord() を呼び出し、その後その返却辞書を Web server に送信するのに適した様式にエンコードするために urllib.parse.urlencode() を呼び出します。

QueueHandler

Added in version 3.2.

logging.handlers モジュールに含まれる QueueHandler クラスは、 queue モジュールや multiprocessing のモジュールで実装されるようなキューにログメッセージを送信する機能をサポートしています。

QueueListener クラスとともに QueueHandler を使うと、ロギングを行うスレッドから分離されたスレッド上でハンドラを動かすことができます。これは、クライアントに対してサービスするスレッドができるだけ速く応答する必要がある一方、別のスレッド上で (SMTPHandler によって電子メールを送信するような) 潜在的に遅い操作が行われるような、ウェブアプリケーションおよびその他のサービスアプリケーションにおいて重要です。

class logging.handlers.QueueHandler(queue)

QueueHandler クラスの新しいインスタンスを返します。インスタンスは、キューにメッセージを送るように初期化されます。キューは任意のキューのようなオブジェクトが可能です; それはそのまま enqueue() メソッドによって使用されます。そのメソッドはメッセージを送る方法を知っている必要があります。もしタスクのトラッキングAPIにキューが必要でない場合はキューとして SimpleQueue のインスタンスが使用できます。

注釈

multiprocessing を使っている場合、 SimpleQueue を使うことは避けてください。代わりに multiprocessing.Queue を使ってください。

emit(record)

Enqueues the result of preparing the LogRecord. Should an exception occur (e.g. because a bounded queue has filled up), the handleError() method is called to handle the error. This can result in the record silently being dropped (if logging.raiseExceptions is False) or a message printed to sys.stderr (if logging.raiseExceptions is True).

prepare(record)

キューに追加するためレコードを準備します。このメソッドが返したオブジェクトがキューに追加されます。

基底の実装はレコードがメッセージや引数と、またもし存在すれば、発生した例外およびスタック情報と統合されるようにフォーマットします。またこの実装では非 pickle 化不可能な要素をレコードから削除します。特に、この実装はレコードの msg と message 属性を (ハンドラの format() メソッドを呼び出すことによって得られる) 統合されたメッセージで上書きし、同時に args, exc_info, exc_text の3つの属性値をすべて None に設定します。

レコードを dict や JSON 文字列に変換したい場合や、オリジナルのレコードを変更せずに修正済のコピーを送りたい場合は、このメソッドをオーバーライドすると良いでしょう。

注釈

基底の実装は、レコードを pickle 化可能にしつつ、さらなるフォーマット処理を防ぐために、メッセージを引数でフォーマットしてフォーマットされたメッセージを message と msg 属性に設定し、同時に args と exc_text 属性を None に設定します。このことは、 QueueListener 側のハンドラが必要なフォーマット処理を行う、たとえば例外のフォーマット処理を行う、ための必要な情報が得られないかもしれないことを意味します。そのため、 QueueHandler の派生クラスにおいてこのメソッドを、たとえば exc_text 属性が None に設定されないように、オーバーライドしたいと考えるかもしれません。この場合、 message / msg / args といった属性の変更はレコードが pickle 化可能であることを保証することと関係しており、元の args の値が pickle 化可能かどうかによって、これらの属性の変更が避けられないかもしれないということに注意してください (この点については、自分のコードだけでなく依存するライブラリのコードも考慮しなければならないことにも注意してください)

enqueue(record)

キューにレコードを put_nowait() を使ってエンキューします; ブロッキングやタイムアウト、あるいはなにか特別なキューの実装を使いたければ、これをオーバライドしてみてください。

listener

When created via configuration using dictConfig(), this attribute will contain a QueueListener instance for use with this handler. Otherwise, it will be None.

Added in version 3.12.

QueueListener

Added in version 3.2.

logging.handlers モジュールに含まれる QueueListener クラスは、 queue モジュールや multiprocessing のモジュールで実装されるようなキューからログメッセージを受信する機能をサポートしています。メッセージは内部スレッドのキューから受信され、同じスレッド上の複数のハンドラに渡されて処理されます。 QueueListener それ自体はハンドラではありませんが、 QueueHandler と連携して動作するのでここで文書化されています。

QueueHandler クラスとともに QueueListener を使うと、ロギングを行うスレッドから分離されたスレッド上でハンドラを動かすことができます。これは、クライアントに対してサービスするスレッドができるだけ速く応答する必要がある一方、別のスレッド上で (SMTPHandler によって電子メールを送信するような) 潜在的に遅い操作が行われるような、ウェブアプリケーションおよびその他のサービスアプリケーションにおいて重要です。

class logging.handlers.QueueListener(queue, *handlers, respect_handler_level=False)

QueueListener クラスの新しいインスタンスを返します。インスタンスは、メッセージを送るためのキューと、キューに格納されたエントリーを処理するハンドラーのリストが設定されて初期化されます。キューは任意のキューのようなオブジェクトが可能です; それはそのまま dequeue() メソッドによって使用されます。そのメソッドはメッセージを送る方法を知っている必要があります。もしタスクのトラッキングAPIにキューが必要でない場合はキューとして SimpleQueue のインスタンスが使用できます（トラッキングAPIが使用可能な場合は使用されます）。

注釈

multiprocessing を使っている場合、 SimpleQueue を使うことは避けてください。代わりに multiprocessing.Queue を使ってください。

もし respect_handler_level が True なら、メッセージをハンドラーに渡すか決める時に（メッセージのレベルに比べて）ハンドラーのレベルが尊重されます。そうでない場合は依然のPythonバージョンと同様にすべてのメッセージは常にハンドラーに渡されます。

バージョン 3.5 で変更: The respect_handler_level argument was added.

dequeue(block)

キューからレコードを取り除き、それを返します。ブロッキングすることがあります。

ベース実装は get() を使用します。タイムアウトを有効にしたい場合や、カスタムのキュー実装を使いたい場合は、このメソッドをオーバーライドすると良いでしょう。

prepare(record)

レコードを扱うための準備をします。

この実装は渡されたレコードをそのまま返します。その値をハンドラに渡す前に何らかのカスタムな整列化 (marshalling) あるいはレコードに対する操作を行う必要があれば、このメソッドをオーバーライドすると良いでしょう。

handle(record)

レコードを処理します。

これは、ハンドラをループしてそれらに処理すべきレコードを渡します。ハンドラに渡される実際のオブジェクトは、 prepare() から返されたものです。

start()

リスナーを開始します。

これは、 LogRecord を処理するキューを監視するために、バックグラウンドスレッドを開始します。

stop()

リスナーを停止します。

スレッドに終了するように依頼し、終了するまで待ちます。アプリケーションの終了前にこのメソッドを呼ばないと、いくつかのレコードがキューに残り、処理されなくなるかもしれないことに注意してください。

enqueue_sentinel()

リスナーに停止するように指示するためキューに番兵を書き込みます。この実装は put_nowait() を使用します。タイムアウトを有効にしたい場合や、カスタムのキュー実装を使いたい場合は、このメソッドをオーバーライドすると良いでしょう。

Added in version 3.3.

参考

logging モジュール

logging モジュールの API リファレンス。

logging.config モジュール

logging モジュールの環境設定 API です。

getpass --- Portable password input

ソースコード: Lib/getpass.py [https://github.com/python/cpython/tree/3.12/Lib/getpass.py]

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. See WebAssemblyプラットフォーム for more information.

getpass モジュールは二つの関数を提供します:

getpass.getpass(prompt='Password: ', stream=None)

エコーなしでユーザーにパスワードを入力させるプロンプト。ユーザーは prompt の文字列をプロンプトに使え、デフォルトは 'Password: ' です。 Unixではプロンプトはファイルに似たオブジェクト stream へ、必要なら置き換えられたエラーハンドラを使って出力されます。 stream のデフォルトは、制御端末(/dev/tty)か、それが利用できない場合は sys.stderr です (この引数は Windowsでは無視されます)。

もしエコーなしで入力が利用できない場合は、 getpass() は stream に警告メッセージを出力し、 sys.stdin から読み込み、 GetPassWarning 警告を発生させます。

注釈

IDLE から getpass を呼び出した場合、入力はIDLEのウィンドウではなく、IDLE を起動したターミナルから行われます。

exception getpass.GetPassWarning

UserWarning のサブクラスで、入力がエコーされてしまった場合に発生します。

getpass.getuser()

ユーザーの "ログイン名"を返します。

This function checks the environment variables LOGNAME, USER, LNAME and USERNAME, in order, and returns the value of the first one which is set to a non-empty string. If none are set, the login name from the password database is returned on systems which support the pwd module, otherwise, an exception is raised.

一般的に、この関数は os.getlogin() よりも優先されるべきです。

curses --- Terminal handling for character-cell displays

Source code: Lib/curses [https://github.com/python/cpython/tree/3.12/Lib/curses]

curses モジュールは、可搬性のある高度な端末操作のデファクトスタンダードである、curses ライブラリへのインターフェースを提供します。

curses が最も広く用いられているのは Unix 環境ですが、Windows、DOS で利用できるバージョンもあり、おそらく他のシステムで利用できるバージョンもあります。この拡張モジュールは Linux および BSD 系の Unixで動作するオープンソースの curses ライブラリである ncurses の API に合致するように設計されています。

注釈

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.

参考

curses.ascii モジュール

ロケール設定に関わらず ASCII 文字を扱うためのユーティリティ。

curses.panel モジュール

curses ウィンドウにデプス機能を追加するパネルスタック拡張。

curses.textpad モジュール

Emacs ライクなキーバインディングをサポートする編集可能な curses 用テキストウィジェット。

Python で Curses プログラミング

Andrew Kuchling および Eric Raymond によって書かれた、curses を Python で使うためのチュートリアルです。

関数

curses モジュールでは以下の例外を定義しています:

exception curses.error

curses ライブラリ関数がエラーを返した際に送出される例外です。

注釈

関数やメソッドにおけるオプションの引数 x および y がある場合、デフォルト値は常に現在のカーソルになります。オプションの attr がある場合、デフォルト値は A_NORMAL です。

curses では以下の関数を定義しています:

curses.baudrate()

端末の出力速度をビット/秒で返します。ソフトウェア端末エミュレータの場合、これは固定の高い値を持つことになります。この関数は歴史的な理由で入れられています; かつては、この関数は時間遅延を生成するための出力ループを書くために用いられたり、行速度に応じてインターフェースを切り替えたりするために用いられたりしていました。

curses.beep()

注意を促す短い音を鳴らします。

curses.can_change_color()

端末に表示される色をプログラマが変更できるか否かによって、True または False を返します。

curses.cbreak()

cbreak モードに入ります。cbreak モード ("rare" モードと呼ばれることもあります) では、通常の tty 行バッファリングはオフにされ、文字を一文字一文字読むことができます。ただし、raw モードとは異なり、特殊文字 (割り込み:interrupt、終了:quit、一時停止:suspend、およびフロー制御) については、tty ドライバおよび呼び出し側のプログラムに対する通常の効果をもっています。まず raw() を呼び出し、次いで cbreak() を呼び出すと、端末を cbreak モードにします。

curses.color_content(color_number)

色 color_number の赤、緑、および青 (RGB) 要素の強度を返します。color_number は 0 から COLORS - 1 の間でなければなりません。与えられた色の R、G、B、の値からなる三要素のタプルが返されます。この値は 0 (その成分はない) から 1000 (その成分の最大強度) の範囲をとります。

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 A_STANDOUT, A_REVERSE, and the other A_* attributes. pair_number() is the counterpart to this function.

curses.curs_set(visibility)

カーソルの状態を設定します。visibility は 0 、 1``または ``2 に設定され、それぞれ不可視、通常、または非常に可視、を意味します。要求された可視属性を端末がサポートしている場合、以前のカーソル状態が返されます; そうでなければ例外が送出されます。多くの端末では、"可視 (通常)" モードは下線カーソルで、"非常に可視" モードはブロックカーソルです。

curses.def_prog_mode()

現在の端末属性を、稼動中のプログラムが curses を使う際のモードである "プログラム" モードとして保存します。(このモードの反対は、プログラムが curses を使わない "シェル" モードです。) その後 reset_prog_mode() を呼ぶとこのモードを復旧します。

curses.def_shell_mode()

現在の端末属性を、稼動中のプログラムが curses を使っていないときのモードである "シェル" モードとして保存します。(このモードの反対は、プログラムが curses 機能を利用している "プログラム" モードです。) その後 reset_shell_mode() を呼ぶとこのモードを復旧します。

curses.delay_output(ms)

出力に ms ミリ秒の一時停止を入れます。

curses.doupdate()

物理スクリーンを更新します。curses ライブラリは、現在の物理スクリーンの内容と、次の状態として要求されている仮想スクリーンをそれぞれ表す、2 つのデータ構造を保持しています。doupdate() は更新を適用し、物理スクリーンを仮想スクリーンに一致させます。

仮想スクリーンは addstr() のような書き込み操作をウィンドウに行った後に noutrefresh() を呼び出して更新することができます。通常の:meth:~window.refresh 呼び出しは、単に noutrefresh() を呼んだ後に doupdate`を呼ぶだけです; 複数のウィンドウを更新しなければならない場合、すべてのウィンドウに対して :meth:()!noutrefresh` を呼び出した後、一度だけ doupdate() を呼ぶことで、パフォーマンスを向上させることができ、おそらくスクリーンのちらつきも押さえることができます。

curses.echo()

echo モードに入ります。echo モードでは、各文字入力はスクリーン上に入力された通りにエコーバックされます。

curses.endwin()

ライブラリの非初期化を行い、端末を通常の状態に戻します。

curses.erasechar()

ユーザの現在の消去文字 (erase character) を1バイトの bytes オブジェクトで返します。Unix オペレーティングシステムでは、この値は curses プログラムが制御している端末の属性であり、curses ライブラリ自体では設定されません。

curses.filter()

filter() ルーチンを使う場合、initscr() を呼ぶ前に呼び出さなくてはなりません。この手順のもたらす効果は以下の通りです: まず二つの関数の呼び出しの間は、LINES は 1 に設定されます; clear, cup, cud, cud1, cuu1, cuu, vpa は無効化されます; home 文字列は cr の値に設定されます。これにより、カーソルは現在の行に制限されるので、スクリーンの更新も同様に制限されます。この関数は、スクリーンの他の部分に影響を及ぼさずに文字単位の行編集を行う場合に利用できます。

curses.flash()

スクリーンを点滅します。すなわち、画面を色反転して、短時間でもとにもどします。人によっては、beep() で生成される注意音よりも、このような "目に見えるベル" を好みます。

curses.flushinp()

すべての入力バッファをフラッシュします。この関数は、ユーザによってすでに入力されているが、まだプログラムによって処理されていないすべての先行入力文字を破棄します。

curses.getmouse()

getch() が KEY_MOUSE を返してマウスイベントを通知した後、この関数を呼んで待ち行列上に置かれているマウスイベントを取得しなければなりません。イベントは (id, x, y, z, bstate) の 5 要素のタプルで表現されています。id は複数のデバイスを区別するための ID 値で、x, y, z はイベントの座標値です。(現在 z は使われていません) bstate は整数値で、その各ビットはイベントのタイプを示す値に設定されています。この値は以下に示す定数のうち一つまたはそれ以上のビット単位 OR になっています。以下の定数の n は 1 から 5 のボタン番号を示します: BUTTONn_PRESSED, BUTTONn_RELEASED, BUTTONn_CLICKED, BUTTONn_DOUBLE_CLICKED, BUTTONn_TRIPLE_CLICKED, BUTTON_SHIFT, BUTTON_CTRL, BUTTON_ALT。

バージョン 3.10 で変更: The BUTTON5_* constants are now exposed if they are provided by the underlying curses library.

curses.getsyx()

仮想スクリーンにおける現在のカーソル位置をタプル (y, x) で返します。 leaveok() が True に設定されていれば、 (-1, -1) が返されます。

curses.getwin(file)

Read window related data stored in the file by an earlier window.putwin() call. The routine then creates and initializes a new window using that data, returning the new window object.

curses.has_colors()

端末が色表示を行える場合には True を返します。そうでない場合には False を返します。

curses.has_extended_color_support()

Return True if the module supports extended colors; otherwise, return False. Extended color support allows more than 256 color pairs for terminals that support more than 16 colors (e.g. xterm-256color).

Extended color support requires ncurses version 6.1 or later.

Added in version 3.10.

curses.has_ic()

端末が文字の挿入/削除機能を持つ場合に True を返します。最近の端末エミュレータはどれもこの機能を持っており、この関数は歴史的な理由のためだけに存在しています。

curses.has_il()

端末が行の挿入/削除機能を持つ場合に True を返します。最近の端末エミュレータはどれもこの機能を持っていて、この関数は歴史的な理由のためだけに存在しています。

curses.has_key(ch)

キー値 ch をとり、現在の端末タイプがその値のキーを認識できる場合に True を返します。

curses.halfdelay(tenths)

半遅延モード、すなわち cbreak モードに似た、ユーザが打鍵した文字がすぐにプログラムで利用できるようになるモードで使われます。しかしながら、何も入力されなかった場合、十分の tenths 秒後に例外が送出されます。tenths の値は 1 から 255 の間でなければなりません。半遅延モードから抜けるには nocbreak() を使います。

curses.init_color(color_number, r, g, b)

色の定義を変更します。変更したい色番号と、その後に 3 つ組みの RGB 値 (赤、緑、青の成分の大きさ) をとります。color_number の値は 0 から COLORS - 1 の間でなければなりません。r, g, b の値は 0 から 1000 の間でなければなりません。init_color() を使うと、スクリーン上でカラーが使用されている部分はすべて新しい設定に即時変更されます。この関数はほとんどの端末で何も行いません; can_change_color() が True を返す場合にのみ動作します。

curses.init_pair(pair_number, fg, bg)

色ペアの定義を変更します。3 つの引数: 変更したい色ペア、前景色の色番号、背景色の色番号、をとります。pair_number は 1 から COLOR_PAIRS - 1 の間でなければなりません (0 色ペアは黒色背景に白色前景となるように設定されており、変更することができません)。fg および bg 引数は 0 と COLORS - 1 の間、または、use_default_colors() を呼び出した後では -1 でなければなりません。色ペアが以前に初期化されていれば、スクリーンを更新して、指定された色ペアの部分を新たな設定に変更します。

curses.initscr()

ライブラリを初期化します。スクリーン全体をあらわす ウィンドウ オブジェクトを返します。

注釈

端末のオープン時にエラーが発生した場合、curses ライブラリによってインタープリタが終了される場合があります。

curses.is_term_resized(nlines, ncols)

resize_term() によってウィンドウ構造が変更されている場合に True を、そうでない場合は False を返します。

curses.isendwin()

endwin() がすでに呼び出されている (すなわち、curses ライブラリが非初期化されてしまっている) 場合に True を返します。

curses.keyname(k)

bytes オブジェクト k に番号付けされているキーの名前を返します。印字可能な ASCII 文字を生成するキーの名前はそのキーの文字自体になります。コントロールキーと組み合わせたキーの名前は、キャレット(b'^')の後に対応する ASCII 文字が続く 2 バイトの bytes オブジェクトになります。 Alt キーと組み合わせたキー (128--255) の名前は、先頭に b'M-' が付き、その後に対応する ASCII 文字が続く bytes オブジェクトになります。

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.

curses.longname()

現在の端末について記述している terminfo の長形式 name フィールドが入った bytes オブジェクトを返します。verbose 形式記述の最大長は 128 文字です。この値は initscr() 呼び出しの後でのみ定義されています。

curses.meta(flag)

flag が True の場合、8 ビット文字の入力を許可します。flag が False の場合、7 ビット文字だけを許可します。

curses.mouseinterval(interval)

ボタンが押されてから離されるまでの時間をマウスクリック一回として認識する最大の時間間隔をミリ秒で設定します。返り値は以前の内部設定値になります。デフォルトは 200 ミリ秒 (5 分の 1 秒) です。

curses.mousemask(mousemask)

報告すべきマウスイベントを設定し、(availmask, oldmask) の組からなるタプルを返します。availmask はどの指定されたマウスイベントのどれが報告されるかを示します; どのイベント指定も完全に失敗した場合には 0 が返ります。oldmask は与えられたウィンドウの以前のマウスイベントマスクです。この関数が呼ばれない限り、マウスイベントは何も報告されません。

curses.napms(ms)

ms ミリ秒間スリープします。

curses.newpad(nlines, ncols)

与えられた行とカラム数を持つパッド (pad) データ構造を生成し、そのポインタを返します。パッドはウィンドウオブジェクトとして返されます。

パッドはウィンドウと同じようなものですが、スクリーンのサイズによる制限をうけず、スクリーンの特定の部分に関連付けられていなくてもかまいません。大きなウィンドウが必要であり、スクリーンにはそのウィンドウの一部しか一度に表示しない場合に使えます。(スクロールや入力エコーなどによる) パッドに対する再描画は起こりません。パッドに対する refresh() および noutrefresh() メソッドは、パッド中の表示する部分と表示するために利用するスクリーン上の位置を指定する 6 つの引数が必要です。これらの引数は pminrow、pmincol、sminrow、smincol、smaxrow、smaxcol です; p で始まる引数はパッド中の表示領域の左上位置で、s で始まる引数はパッド領域を表示するスクリーン上のクリップ矩形を指定します。

curses.newwin(nlines, ncols)

curses.newwin(nlines, ncols, begin_y, begin_x)

左上の角が (begin_y, begin_x) で、高さ/幅が nlines / ncols の新規 ウィンドウ を返します。

デフォルトでは、ウィンドウは指定された位置からスクリーンの右下まで広がります。

curses.nl()

newlime モードに入ります。このモードはリターンキーを入力中の改行として変換し、出力時に改行文字を復帰 (return) と改行 (line-feed) に変換します。newline モードは初期化時にはオンになっています。

curses.nocbreak()

cbreak モードを終了します。行バッファリングを行う通常の "cooked" モードに戻ります。

curses.noecho()

echo モードを終了します。入力のエコーバックはオフにされます。

curses.nonl()

newline モードを終了します。入力時のリターンキーから改行への変換、および出力時の改行から復帰/改行への低レベル変換を無効化します (ただし、addch('\n') の振る舞いは変更せず、仮想スクリーン上では常に復帰と改行に等しくなります)。変換をオフにすることで、curses は水平方向の動きを少しだけ高速化できることがあります; また、入力中のリターンキーの検出ができるようになります。

curses.noqiflush()

noqiflush() ルーチンを使うと、通常行われている INTR 、 QUIT および SUSP 文字による入力および出力キューのフラッシュが行われなくなります。シグナルハンドラが終了した際、割り込みが発生しなかったかのように出力を続たい場合、ハンドラ中で noqiflush() を呼び出すことができます。

curses.noraw()

raw モードから離れます。行バッファリングを行う通常の "cooked" モードに戻ります。

curses.pair_content(pair_number)

要求された色ペアの色を含むタプル (fg, bg) を返します。pair_number は 0 から COLOR_PAIRS - 1 の間でなければなりません。

curses.pair_number(attr)

attr に対する色ペアセットの番号を返します。color_pair() はこの関数の逆に相当します。

curses.putp(str)

tputs(str, 1, putchar) と等価です; 現在の端末における、指定された terminfo 機能の値を出力します。putp() の出力は常に標準出力に送られるので注意して下さい。

curses.qiflush([flag])

flag が False なら、noqiflush() を呼ぶのとと同じ効果です。flag が True か、引数が与えられていない場合、制御文字が読み出された最にキューはフラッシュされます。

curses.raw()

raw モードに入ります。raw モードでは、通常の行バッファリングと割り込み (interrupt)、終了 (quit)、一時停止 (suspend)、およびフロー制御キーはオフになります; 文字は curses 入力関数に一文字づつ渡されます。

curses.reset_prog_mode()

端末を "program" モードに復旧し、あらかじめ def_prog_mode() で保存した内容に戻します。

curses.reset_shell_mode()

端末を "shell" モードに復旧し、あらかじめ def_shell_mode() で保存した内容に戻します。

curses.resetty()

端末モードの状態を最後に savetty() を呼び出した時の状態に戻します。

curses.resize_term(nlines, ncols)

resizeterm() で使用されるバックエンド関数で、ウィンドウサイズを変更する時、resize_term() は拡張された領域を埋めます。呼び出したアプリケーションはそれらの領域を適切なデータで埋めなくてはなりません。resize_term() 関数はすべてのウィンドウのサイズ変更を試みます。ただし、パッド呼び出しの慣例により、アプリケーションとの追加のやり取りを行わないサイズ変更は行えません。

curses.resizeterm(nlines, ncols)

現在の標準ウィンドウのサイズを指定された寸法に変更し、curses ライブラリが使用する、その他のウィンドウサイズを記憶しているデータ (特に SIGWINCH ハンドラ) を調整します。

curses.savetty()

resetty() で使用される、バッファ内の端末モードの現在の状態を保存します。

curses.get_escdelay()

Retrieves the value set by set_escdelay().

Added in version 3.9.

curses.set_escdelay(ms)

Sets the number of milliseconds to wait after reading an escape character, to distinguish between an individual escape character entered on the keyboard from escape sequences sent by cursor and function keys.

Added in version 3.9.

curses.get_tabsize()

Retrieves the value set by set_tabsize().

Added in version 3.9.

curses.set_tabsize(size)

Sets the number of columns used by the curses library when converting a tab character to spaces as it adds the tab to a window.

Added in version 3.9.

curses.setsyx(y, x)

仮想スクリーンのカーソルを y, x に設定します。y および x がどちらも -1 の場合、 leaveok() が に``True``に設定されます。

curses.setupterm(term=None, fd=-1)

端末を初期化します。term は端末名となる文字列または None です。省略または None の場合、環境変数 TERM の値が使用されます。fd は送信される初期化シーケンスへのファイル記述子です。指定されないまたは -1 の場合、sys.stdout のファイル記述子が使用されます。

curses.start_color()

プログラマがカラーを利用したい場合で、かつ他の何らかのカラー操作ルーチンを呼び出す前に呼び出さなくてはなりません。この関数は initscr() を呼んだ直後に呼ぶようにしておくとよいでしょう。

start_color() は 8 つの基本色 (黒、赤、緑、黄、青、マゼンタ、シアン、および白) と、色数の最大値と端末がサポートする色ペアの最大数が入っている、curses モジュールにおける二つのグローバル変数、COLORS および COLOR_PAIRS を初期化します。この関数はまた、色設定を端末のスイッチが入れられたときの状態に戻します。

curses.termattrs()

端末がサポートするすべてのビデオ属性を論理和した値を返します。この情報は、curses プログラムがスクリーンの見え方を完全に制御する必要がある場合に便利です。

curses.termname()

14 文字以下になるように切り詰められた環境変数 TERM の値を bytes オブジェクトで返します。

curses.tigetflag(capname)

terminfo 機能名 capname に対応する真偽値の機能値を整数で返します。capname が真偽値で表せる機能値でない場合 -1 を返し、機能がキャンセルされているか、端末記述上に見つからない場合 0 を返します。

curses.tigetnum(capname)

terminfo 機能名 capname に対応する数値の機能値を整数で返します。capname が数値で表せる機能値でない場合 -2 を返し、機能がキャンセルされているか、端末記述上に見つからない場合 -1 を返します。

curses.tigetstr(capname)

Return the value of the string capability corresponding to the terminfo capability name capname as a bytes object. Return None if capname is not a terminfo "string capability", or is canceled or absent from the terminal description.

curses.tparm(str[, ...])

str を与えられたパラメタを使って bytes オブジェクトにインスタンス化します。str は terminfo データベースから得られたパラメタを持つ文字列でなければなりません。例えば、tparm(tigetstr("cup"), 5, 3) は b'\033[6;4H' のようになります。厳密には端末の形式によって異なる結果となります。

curses.typeahead(fd)

先読みチェックに使うためのファイル記述子 fd を指定します。fd が -1 の場合、先読みチェックは行われません。

curses ライブラリはスクリーンを更新する間、先読み文字列を定期的に検索することで "行はみ出し最適化 (line-breakout optimization)" を行います。入力が得られ、かつ入力は端末からのものである場合、現在行おうとしている更新は refresh や doupdate を再度呼び出すまで先送りにします。この関数は異なるファイル記述子で先読みチェックを行うように指定することができます。

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 b'^C'. Printing characters are left as they are.

curses.ungetch(ch)

ch をプッシュし、次に getch() を呼び出した時にその値が返るようにします。

注釈

getch() を呼び出すまでは ch は一つしかプッシュできません。

curses.update_lines_cols()

Update the LINES and COLS module variables. Useful for detecting manual screen resize.

Added in version 3.5.

curses.unget_wch(ch)

ch をプッシュし、次に get_wch() を呼び出した時にその値が返るようにします。

注釈

get_wch() を呼び出すまでは ch は一つしかプッシュできません。

Added in version 3.3.

curses.ungetmouse(id, x, y, z, bstate)

与えられた状態データが関連付けられた KEY_MOUSE イベントを入力キューにプッシュします。

curses.use_env(flag)

この関数を使う場合、initscr() または newterm を呼ぶ前に呼び出さなくてはなりません。flag が False の場合、環境変数 LINES および COLUMNS の値 (デフォルトで使用されます) の値が設定されていたり、curses がウィンドウ内で動作して (この場合 LINES や COLUMNS が設定されていないとウィンドウのサイズを使います) いても、terminfo データベースに指定された lines および columns の値を使います。

curses.use_default_colors()

この機能をサポートしている端末上で、色の値としてデフォルト値を使う設定をします。あなたのアプリケーションで透過性とサポートするためにこの関数を使ってください。デフォルトの色は色番号 -1 に割り当てられます。この関数を呼んだ後、たとえば init_pair(x, curses.COLOR_RED, -1) は色ペア x を赤い前景色とデフォルトの背景色に初期化します。

curses.wrapper(func, /, *args, **kwargs)

curses を初期化し、呼び出し可能なオブジェクト func (その他の curses を使用するアプリケーション) を呼び出します。アプリケーションが例外を送出した場合、この関数は端末を例外を再送出する前に正常な状態に戻し、トレースバックを作成します。その後、呼び出し可能オブジェクト func には、第一引数としてメインウィンドウ 'stdscr' が、続いて wrapper() に渡されたその他の引数が渡されます。func を呼び出す前、wrapper() は cbreak モードをオンに、エコーをオフに、端末キーパッドを有効にし、端末が色表示をサポートしている場合は色を初期化します。終了時 (通常終了、例外による終了のどちらでも)、cooked モードに戻し、エコーをオンにし、端末キーパッドを無効にします。

Window オブジェクト

上記の initscr() や newwin() が返すウィンドウは、以下のメソッドと属性を持ちます:

window.addch(ch[, attr])

window.addch(y, x, ch[, attr])

(y, x) にある文字 ch を属性 attr で描画します。このときその場所に以前描画された文字は上書きされます。デフォルトでは、文字の位置および属性はウィンドウオブジェクトにおける現在の設定になります。

注釈

Writing outside the window, subwindow, or pad raises a 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.

window.addnstr(str, n[, attr])

window.addnstr(y, x, str, n[, attr])

文字列 str から最大で n 文字を (y, x) に属性 attr で描画します。以前ディスプレイにあった内容はすべて上書きされます。

window.addstr(str[, attr])

window.addstr(y, x, str[, attr])

(y, x) に文字列 str を属性 attr で描画します。以前ディスプレイにあった内容はすべて上書きされます。

注釈

Writing outside the window, subwindow, or pad raises 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.

A bug in ncurses [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 addstr() with a str that has embedded newlines. Instead, call addstr() separately for each line.

window.attroff(attr)

現在のウィンドウに書き込まれたすべての内容に対し "バックグラウンド" に設定された属性 attr を除去します。

window.attron(attr)

現在のウィンドウに書き込まれたすべての内容に対し "バックグラウンド" に属性 attr を追加します。

window.attrset(attr)

"バックグラウンド" の属性セットを attr に設定します。初期値は 0 (属性なし) です。

window.bkgd(ch[, attr])

ウィンドウ上の背景プロパティを、attr を属性とする文字 ch に設定します。変更はそのウィンドウ中のすべての文字に以下のようにして適用されます:

ウィンドウ中のすべての文字の属性が新たな背景属性に変更されます。

以前の背景文字が出現すると、常に新たな背景文字に変更されます。

window.bkgdset(ch[, attr])

ウィンドウの背景を設定します。ウィンドウの背景は、文字と何らかの属性の組み合わせから成り立ちます。背景情報の属性の部分は、ウィンドウ上に描画されている空白でないすべての文字と組み合わされ (OR され) ます。空白文字には文字部分と属性部分の両方が組み合わされます。背景は文字のプロパティとなり、スクロールや行/文字の挿入/削除操作の際には文字と一緒に移動します。

window.border([ls[, rs[, ts[, bs[, tl[, tr[, bl[, br]]]]]]]])

ウィンドウの縁に境界線を描画します。各引数には境界の特定部分を表現するために使われる文字を指定します; 詳細は以下のテーブルを参照してください。

注釈

どの引数も、0 を指定した場合デフォルトの文字が使われるようになります。キーワード引数は使うことが できません。デフォルトはテーブル内で示しています:

引数

説明

デフォルト値

ls

左側

ACS_VLINE

rs

右側

ACS_VLINE

ts

上側

ACS_HLINE

bs

下側

ACS_HLINE

tl

左上の角

ACS_ULCORNER

tr

右上の角

ACS_URCORNER

bl

左下の角

ACS_LLCORNER

br

右下の角

ACS_LRCORNER

window.box([vertch, horch])

border() と同様ですが、ls および rs は共に vertch で、ts および bs は共に horch です。この関数では、角に使われるデフォルト文字が常に使用されます。

window.chgat(attr)

window.chgat(num, attr)

window.chgat(y, x, attr)

window.chgat(y, x, num, attr)

Set the attributes of num characters at the current cursor position, or at position (y, x) if supplied. If num is not given or is -1, the attribute will be set on all the characters to the end of the line. This function moves cursor to position (y, x) if supplied. The changed line will be touched using the touchline() method so that the contents will be redisplayed by the next window refresh.

window.clear()

erase() に似ていますが、次に refresh() が呼び出された際にすべてのウィンドウを再描画するようにします。

window.clearok(flag)

flag が True ならば、次の refresh() はウィンドウを完全に消去します。

window.clrtobot()

カーソルの位置からウィンドウの端までを消去します: カーソル以降のすべての行が削除されるため、clrtoeol() と等価です。

window.clrtoeol()

カーソル位置から行末までを消去します。

window.cursyncup()

ウィンドウのすべての親ウィンドウについて、現在のカーソル位置を反映するよう更新します。

window.delch([y, x])

(y, x) にある文字を削除します。

window.deleteln()

カーソルの下にある行を削除します。後続の行はすべて 1 行上に移動します。

window.derwin(begin_y, begin_x)

window.derwin(nlines, ncols, begin_y, begin_x)

"derive window (ウィンドウを派生する)" の短縮形です。derwin() は subwin() と同じですが、begin_y および begin_x はスクリーン全体の原点ではなく、ウィンドウの原点からの相対位置です。派生したウィンドウオブジェクトが返されます。

window.echochar(ch[, attr])

文字 ch に属性 attr を付与し、即座に refresh() をウィンドウに対して呼び出します。

window.enclose(y, x)

与えられた文字セル座標をスクリーン原点から相対的なものとし、ウィンドウの中に含まれるかを調べて、True または False を返します。スクリーン上のウィンドウの一部がマウスイベントの発生場所を含むかどうかを調べる上で便利です。

バージョン 3.10 で変更: Previously it returned 1 or 0 instead of True or False.

window.encoding

encode メソッドの引数 (Unicode 文字列および文字) で使用されるエンコーディングです。例えば window.subwin() などでサブウィンドウを生成した時、エンコーディング属性は親ウィンドウから継承します。デフォルトでは、現在のロケールのエンコーディングが使用されます (locale.getencoding() 参照)。

Added in version 3.3.

window.erase()

ウィンドウをクリアします。

window.getbegyx()

左上の角の座標をあらわすタプル (y, x) を返します。

window.getbkgd()

与えられたウィンドウの現在の背景文字と属性のペアを返します。

window.getch([y, x])

文字を 1 個取得します。返される整数は ASCII の範囲の値となる とは限らない ので注意してください。ファンクションキー、キーパッドのキー等は 256 よりも大きな数字で表されます。無遅延 (no-delay) モードでは、入力がない場合 -1 を返し、そうでなければキーが押されるまで待ちます。

window.get_wch([y, x])

ワイド文字を 1 個取得します。ほとんどのキー、ファンクションキーの数値、キーパッドのキー、およびその他の特殊キーの文字を返します。無遅延モードでは、入力がない場合例外を送出します。

Added in version 3.3.

window.getkey([y, x])

文字を 1 個取得し、 getch() が返すような整数ではなく文字列を返します。ファンクションキー、キーパッドのキー、およびその他特殊キーはキー名を含む複数文字を返します。無遅延モードでは、入力がない場合例外を送出します。

window.getmaxyx()

ウィンドウの高さおよび幅を表すタプル (y, x) を返します。

window.getparyx()

親ウィンドウ中におけるウィンドウの開始位置をタプル (y, x) で返します。ウィンドウに親ウィンドウがない場合 (-1, -1) を返します。

window.getstr()

window.getstr(n)

window.getstr(y, x)

window.getstr(y, x, n)

原始的な文字編集機能つきで、ユーザの入力した byte オブヘクトを読み取ります。

window.getyx()

ウィンドウの左上角からの相対で表した現在のカーソル位置をタプル (y, x) で返します。

window.hline(ch, n)

window.hline(y, x, ch, n)

(y, x) から始まり、n の長さを持つ、文字 ch で作られる水平線を表示します。

window.idcok(flag)

flag が False の場合、curses は端末のハードウェアによる文字挿入/削除機能を使おうとしなくなります; flag が True ならば、文字挿入/削除は有効にされます。curses が最初に初期化された際には文字挿入/削除はデフォルトで有効になっています。

window.idlok(flag)

flag が True であれば、curses はハードウェアの行編集機能の利用を試みます。行挿入/削除は無効化されます。

window.immedok(flag)

flag が True ならば、ウィンドウイメージ内における何らかの変更があるとウィンドウを更新するようになります; すなわち、refresh() を自分で呼ばなくても良くなります。とはいえ、wrefresh を繰り返し呼び出すことになるため、この操作はかなりパフォーマンスを低下させます。デフォルトでは無効になっています。

window.inch([y, x])

ウィンドウの指定の位置の文字を返します。下位 8 ビットが本来の文字で、それより上のビットは属性です。

window.insch(ch[, attr])

window.insch(y, x, ch[, attr])

(y, x) に文字 ch を属性 attr で描画し、行の x からの内容を 1 文字分右にずらします。

window.insdelln(nlines)

nlines 行を指定されたウィンドウの現在の行の上に挿入します。その下にある nlines 行は失われます。負の nlines を指定すると、カーソルのある行以降の nlines を削除し、削除された行の後ろに続く内容が上に来ます。その下にある nlines は消去されます。現在のカーソル位置はそのままです。

window.insertln()

カーソルの下に空行を 1 行入れます。それ以降の行は 1 行づつ下に移動します。

window.insnstr(str, n[, attr])

window.insnstr(y, x, str, n[, attr])

文字列をカーソルの下にある文字の前に (一行に収まるだけ) 最大 n 文字挿入します。n がゼロまたは負の値の場合、文字列全体が挿入されます。カーソルの右にあるすべての文字は右に移動し、行の左端にある文字は失われます。カーソル位置は (y, x が指定されていた場合はそこに移動しますが、その後は) 変化しません。

window.insstr(str[, attr])

window.insstr(y, x, str[, attr])

キャラクタ文字列を (行に収まるだけ) カーソルより前に挿入します。カーソルの右側にある文字はすべて右にシフトし、行の右端の文字は失われます。カーソル位置は (y, x が指定されていた場合はそこに移動しますが、その後は) 変化しません。

window.instr([n])

window.instr(y, x[, n])

現在のカーソル位置、または y, x が指定されている場合にはその場所から始まるキャラクタの bytes オブジェクトをウィンドウから抽出して返します。属性は文字から剥ぎ取られます。n が指定された場合、instr() は (末尾の NUL 文字を除いて) 最大で n 文字までの長さからなる文字列を返します。

window.is_linetouched(line)

指定した行が、最後に refresh() を呼んだ時から変更されている場合に True を返します; そうでない場合には False を返します。line が現在のウィンドウ上の有効な行でない場合、curses.error 例外を送出します。

window.is_wintouched()

指定したウィンドウが、最後に refresh() を呼んだ時から変更されている場合に True を返します; そうでない場合には False を返します。

window.keypad(flag)

flag が True の場合、ある種のキー (キーパッドやファンクションキー) によって生成されたエスケープシーケンスは curses で解釈されます。flag が False の場合、エスケープシーケンスは入力ストリームにそのままの状態で残されます。

window.leaveok(flag)

flag が True の場合、カーソルは "カーソル位置" に移動せず現在の場所にとどめます。これにより、カーソルの移動を減らせる可能性があります。この場合、カーソルは不可視にされます。

flag が False の場合、カーソルは更新の際に常に "カーソル位置" に移動します。

window.move(new_y, new_x)

カーソルを (new_y, new_x) に移動します。

window.mvderwin(y, x)

ウィンドウを親ウィンドウの中で移動します。ウィンドウのスクリーン相対となるパラメタ群は変化しません。このルーチンは親ウィンドウの一部をスクリーン上の同じ物理位置に表示する際に用いられます。

window.mvwin(new_y, new_x)

ウィンドウの左上角が (new_y, new_x) になるように移動します。

window.nodelay(flag)

flag が True の場合、getch() は非ブロックで動作します。

window.notimeout(flag)

flag が True の場合、エスケープシーケンスはタイムアウトしなくなります。

flag が False の場合、数ミリ秒間の間エスケープシーケンスは解釈されず、入力ストリーム中にそのままの状態で残されます。

window.noutrefresh()

更新をマークはしますが待機します。この関数はウィンドウのデータ構造を表現したい内容を反映するように更新しますが、物理スクリーン上に反映させるための強制更新を行いません。更新を行うためには doupdate() を呼び出します。

window.overlay(destwin[, sminrow, smincol, dminrow, dmincol, dmaxrow, dmaxcol])

ウィンドウを destwin の上に重ね書き (overlay) します。ウィンドウは同じサイズである必要はなく、重なっている領域だけが複写されます。この複写は非破壊的です。これは現在の背景文字が destwin の内容を上書きしないことを意味します。

複写領域をきめ細かく制御するために、overlay() の第二形式を使うことができます。sminrow および smincol は元のウィンドウの左上の座標で、他の変数は destwin 内の矩形を表します。

window.overwrite(destwin[, sminrow, smincol, dminrow, dmincol, dmaxrow, dmaxcol])

destwin の上にウィンドウの内容を上書き (overwrite) します。ウィンドウは同じサイズである必要はなく、重なっている領域だけが複写されます。この複写は破壊的です。これは現在の背景文字が destwin の内容を上書きすることを意味します。

複写領域をきめ細かく制御するために、overwrite() の第二形式を使うことができます。sminrow および smincol は元のウィンドウの左上の座標で、他の変数は destwin 内の矩形を表します。

window.putwin(file)

ウィンドウに関連付けられているすべてのデータを与えられたファイルオブジェクトに書き込みます。この情報は後に getwin() 関数を使って取得することができます。

window.redrawln(beg, num)

beg 行から始まる num スクリーン行の表示内容が壊れており、次の refresh() 呼び出しで完全に再描画されなければならないことを通知します。

window.redrawwin()

ウィンドウ全体を更新 (touch) し、次の refresh() 呼び出しで完全に再描画されるようにします。

window.refresh([pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol])

ディスプレイを即時更新し (実際のウィンドウとこれまでの描画/削除メソッドの内容とを同期し) ます。

6 つのオプション引数はウィンドウが newpad() で生成された場合にのみ指定することができます。追加の引数はパッドやスクリーンのどの部分が含まれるのかを示すために必要です。pminrow および pmincol にはパッドが表示されている矩形の左上角を指定します。sminrow, smincol, smaxrow, および smaxcol には、スクリーン上に表示される矩形の縁を指定します。パッド内に表示される矩形の右下角はスクリーン座標から計算されるので、矩形は同じサイズでなければなりません。矩形は両方とも、それぞれのウィンドウ構造内に完全に含まれていなければなりません。pminrow, pmincol, sminrow, または smincol に負の値を指定すると、ゼロを指定したものとして扱われます。

window.resize(nlines, ncols)

curses ウィンドウの記憶域を、指定値のサイズに調整するため再割当てします。サイズが現在の値より大きい場合、ウィンドウのデータは現在の背景設定 (bkgdset() で設定) で埋められマージされます。

window.scroll([lines=1])

スクリーンまたはスクロール領域を上に lines 行スクロールします。

window.scrollok(flag)

ウィンドウのカーソルが、最下行で改行を行ったり最後の文字を入力したりした結果、ウィンドウやスクロール領域の縁からはみ出して移動した際の動作を制御します。flag が False の場合、カーソルは最下行にそのままにしておかれます。flag が True の場合、ウィンドウは 1 行上にスクロールします。端末の物理スクロール効果を得るためには idlok() も呼び出す必要があるので注意してください。

window.setscrreg(top, bottom)

スクロール領域を top から bottom に設定します。スクロール動作はすべてこの領域で行われます。

window.standend()

A_STANDOUT 属性をオフにします。端末によっては、この操作ですべての属性をオフにする副作用が発生します。

window.standout()

A_STANDOUT 属性をオンにします。

window.subpad(begin_y, begin_x)

window.subpad(nlines, ncols, begin_y, begin_x)

左上の角が (begin_y, begin_x) にあり、幅/高さがそれぞれ ncols / nlines であるようなサブウィンドウを返します。

window.subwin(begin_y, begin_x)

window.subwin(nlines, ncols, begin_y, begin_x)

左上の角が (begin_y, begin_x) にあり、幅/高さがそれぞれ ncols / nlines であるようなサブウィンドウを返します。

デフォルトでは、サブウィンドウは指定された場所からウィンドウの右下角まで広がります。

window.syncdown()

このウィンドウの上位のウィンドウのいずれかで更新(touch)された各場所をこのウィンドウ内でも更新します。このルーチンは refresh() から呼び出されるので、手動で呼び出す必要はほとんどないはずです。

window.syncok(flag)

flag が True の場合、ウィンドウが変更された際は常に syncup() を自動的に呼ぶようになります。

window.syncup()

ウィンドウ内で更新 (touch) した場所を、上位のすべてのウィンドウ内でも更新します。

window.timeout(delay)

ウィンドウのブロックまたは非ブロック読み込み動作を設定します。delay が負の場合、ブロック読み出しが使われ、入力を無期限で待ち受けます。delay がゼロの場合、非ブロック読み出しが使われ、入力待ちの文字がない場合 getch() は -1 を返します。delay が正の値であれば、getch() は delay ミリ秒間ブロックし、ブロック後の時点で入力がない場合には -1 を返します。

window.touchline(start, count[, changed])

start から始まる count 行が変更されたかのように振舞わせます。もし changed が与えられた場合、その引数は指定された行が変更された(changed=True)か、変更されていないか(changed)を指定します。

window.touchwin()

描画を最適化するために、すべてのウィンドウが変更されたかのように振舞わせます。

window.untouchwin()

ウィンドウ内のすべての行を、最後に refresh() を呼んだ際から変更されていないものとしてマークします。

window.vline(ch, n[, attr])

window.vline(y, x, ch, n[, attr])

Display a vertical line starting at (y, x) with length n consisting of the character ch with attributes attr.

定数

curses モジュールでは以下のデータメンバを定義しています:

curses.ERR

getch() のような整数を返す curses ルーチンのいくつかは、失敗した際に ERR を返します。

curses.OK

napms() のような整数を返す curses ルーチンのいくつかは、成功した際に OK を返します。

curses.version

curses.__version__

A bytes object representing the current version of the module.

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 curses.ncurses_version[0] is equivalent to curses.ncurses_version.major and so on.

Availability: if the ncurses library is used.

Added in version 3.8.

curses.COLORS

The maximum number of colors the terminal can support. It is defined only after the call to start_color().

curses.COLOR_PAIRS

The maximum number of color pairs the terminal can support. It is defined only after the call to start_color().

curses.COLS

The width of the screen, i.e., the number of columns. It is defined only after the call to initscr(). Updated by update_lines_cols(), resizeterm() and resize_term().

curses.LINES

The height of the screen, i.e., the number of lines. It is defined only after the call to initscr(). Updated by update_lines_cols(), resizeterm() and resize_term().

Some constants are available to specify character cell attributes. The exact constants available are system dependent.

属性

意味

curses.A_ALTCHARSET

代替文字セットモード

curses.A_BLINK

点滅モード

curses.A_BOLD

太字モード

curses.A_DIM

低輝度モード

curses.A_INVIS

Invisible or blank mode

curses.A_ITALIC

イタリックモード

curses.A_NORMAL

通常の属性

curses.A_PROTECT

Protected mode

curses.A_REVERSE

Reverse background and foreground colors

curses.A_STANDOUT

強調モード

curses.A_UNDERLINE

下線モード

curses.A_HORIZONTAL

Horizontal highlight

curses.A_LEFT

Left highlight

curses.A_LOW

Low highlight

curses.A_RIGHT

Right highlight

curses.A_TOP

Top highlight

curses.A_VERTICAL

Vertical highlight

Added in version 3.7: A_ITALIC が追加されました。

Several constants are available to extract corresponding attributes returned by some methods.

Bit-mask

意味

curses.A_ATTRIBUTES

Bit-mask to extract attributes

curses.A_CHARTEXT

Bit-mask to extract a character

curses.A_COLOR

Bit-mask to extract color-pair field information

キーは KEY_ で始まる名前をもつ整数定数です。利用可能なキーキャップはシステムに依存します。

キー定数

キー

curses.KEY_MIN

最小のキー値

curses.KEY_BREAK

ブレークキー (Break, 信頼できません)

curses.KEY_DOWN

下矢印

curses.KEY_UP

上矢印

curses.KEY_LEFT

左矢印

curses.KEY_RIGHT

右矢印

curses.KEY_HOME

ホームキー (Home, または上左矢印)

curses.KEY_BACKSPACE

バックスペース (Backspace, 信頼できません)

curses.KEY_F0

ファンクションキー。64 個までサポートされています。

curses.KEY_Fn

ファンクションキー n の値

curses.KEY_DL

行削除 (Delete line)

curses.KEY_IL

行挿入 (Insert line)

curses.KEY_DC

文字削除 (Delete char)

curses.KEY_IC

文字挿入、または文字挿入モードへ入る

curses.KEY_EIC

文字挿入モードから抜ける

curses.KEY_CLEAR

画面消去

curses.KEY_EOS

画面の末端まで消去

curses.KEY_EOL

行末端まで消去

curses.KEY_SF

前に 1 行スクロール

curses.KEY_SR

後ろ (逆方向) に 1 行スクロール

curses.KEY_NPAGE

次のページ (Page Next)

curses.KEY_PPAGE

前のページ (Page Prev)

curses.KEY_STAB

タブ設定

curses.KEY_CTAB

タブリセット

curses.KEY_CATAB

すべてのタブをリセット

curses.KEY_ENTER

入力または送信 (信頼できません)

curses.KEY_SRESET

ソフトウェア (部分的) リセット (信頼できません)

curses.KEY_RESET

リセットまたはハードリセット (信頼できません)

curses.KEY_PRINT

印刷 (Print)

curses.KEY_LL

下ホーム (Home down) または最下行 (左下)

curses.KEY_A1

キーパッドの左上キー

curses.KEY_A3

キーパッドの右上キー

curses.KEY_B2

キーパッドの中央キー

curses.KEY_C1

キーパッドの左下キー

curses.KEY_C3

キーパッドの右下キー

curses.KEY_BTAB

Back tab

curses.KEY_BEG

開始 (Beg)

curses.KEY_CANCEL

キャンセル (Cancel)

curses.KEY_CLOSE

Close [閉じる]

curses.KEY_COMMAND

コマンド (Cmd)

curses.KEY_COPY

Copy [コピー]

curses.KEY_CREATE

生成 (Create)

curses.KEY_END

終了 (End)

curses.KEY_EXIT

Exit [終了]

curses.KEY_FIND

検索 (Find)

curses.KEY_HELP

ヘルプ (Help)

curses.KEY_MARK

マーク (Mark)

curses.KEY_MESSAGE

メッセージ (Message)

curses.KEY_MOVE

移動 (Move)

curses.KEY_NEXT

次へ (Next)

curses.KEY_OPEN

開く (Open)

curses.KEY_OPTIONS

オプション

curses.KEY_PREVIOUS

前へ (Prev)

curses.KEY_REDO

Redo [やり直し]

curses.KEY_REFERENCE

参照 (Ref)

curses.KEY_REFRESH

更新 (Refresh)

curses.KEY_REPLACE

置換 (Replace)

curses.KEY_RESTART

再起動 (Restart)

curses.KEY_RESUME

再開 (Resume)

curses.KEY_SAVE

Save [保存]

curses.KEY_SBEG

シフト付き Beg

curses.KEY_SCANCEL

シフト付き Cancel

curses.KEY_SCOMMAND

シフト付き Command

curses.KEY_SCOPY

シフト付き Copy

curses.KEY_SCREATE

シフト付き Create

curses.KEY_SDC

シフト付き Delete char

curses.KEY_SDL

シフト付き Delete line

curses.KEY_SELECT

選択 (Select)

curses.KEY_SEND

シフト付き End

curses.KEY_SEOL

シフト付き Clear line

curses.KEY_SEXIT

シフト付き Exit

curses.KEY_SFIND

シフト付き Find

curses.KEY_SHELP

シフト付き Help

curses.KEY_SHOME

シフト付き Home

curses.KEY_SIC

シフト付き Input

curses.KEY_SLEFT

シフト付き Left arrow

curses.KEY_SMESSAGE

シフト付き Message

curses.KEY_SMOVE

シフト付き Move

curses.KEY_SNEXT

シフト付き Next

curses.KEY_SOPTIONS

シフト付き Options

curses.KEY_SPREVIOUS

シフト付き Prev

curses.KEY_SPRINT

シフト付き Print

curses.KEY_SREDO

シフト付き Redo

curses.KEY_SREPLACE

シフト付き Replace

curses.KEY_SRIGHT

シフト付き Right arrow

curses.KEY_SRSUME

シフト付き Resume

curses.KEY_SSAVE

シフト付き Save

curses.KEY_SSUSPEND

シフト付き Suspend

curses.KEY_SUNDO

シフト付き Undo

curses.KEY_SUSPEND

一時停止 (Suspend)

curses.KEY_UNDO

Undo [元に戻す]

curses.KEY_MOUSE

マウスイベント通知

curses.KEY_RESIZE

端末リサイズイベント

curses.KEY_MAX

最大キー値

On VT100s and their software emulations, such as X terminal emulators, there are normally at least four function keys (KEY_F1, KEY_F2, KEY_F3, KEY_F4) available, and the arrow keys mapped to KEY_UP, KEY_DOWN, KEY_LEFT and 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:

キーキャップ

定数

Insert

KEY_IC

Delete

KEY_DC

Home

KEY_HOME

End

KEY_END

Page Up

KEY_PPAGE

Page Down

KEY_NPAGE

代替文字セットを以下の表に列挙します。これらは VT100 端末から継承したものであり、X 端末のようなソフトウェアエミュレーション上で一般に利用可能なものです。グラフィックが利用できない場合、curses は印字可能 ASCII文字による粗雑な近似出力を行います。

注釈

これらは initscr() が呼び出された後でしか利用できません。

ACS コード

意味

curses.ACS_BBSS

右上角の別名

curses.ACS_BLOCK

黒四角ブロック

curses.ACS_BOARD

白四角ブロック

curses.ACS_BSBS

水平線の別名

curses.ACS_BSSB

左上角の別名

curses.ACS_BSSS

上向き T 字罫線の別名

curses.ACS_BTEE

下向き T 字罫線

curses.ACS_BULLET

黒丸(bullet)

curses.ACS_CKBOARD

チェッカーボードパタン (点描)

curses.ACS_DARROW

下向き矢印

curses.ACS_DEGREE

度記号

curses.ACS_DIAMOND

ダイアモンド

curses.ACS_GEQUAL

大なりイコール

curses.ACS_HLINE

水平線

curses.ACS_LANTERN

ランタン(lantern) シンボル

curses.ACS_LARROW

左向き矢印

curses.ACS_LEQUAL

小なりイコール

curses.ACS_LLCORNER

左下角

curses.ACS_LRCORNER

右下角

curses.ACS_LTEE

左向き T 字罫線

curses.ACS_NEQUAL

不等号

curses.ACS_PI

パイ記号

curses.ACS_PLMINUS

プラスマイナス記号

curses.ACS_PLUS

大プラス記号

curses.ACS_RARROW

右向き矢印

curses.ACS_RTEE

右向き T 字罫線

curses.ACS_S1

スキャンライン 1

curses.ACS_S3

スキャンライン 3

curses.ACS_S7

スキャンライン 7

curses.ACS_S9

スキャンライン 9

curses.ACS_SBBS

右下角の別名

curses.ACS_SBSB

垂直線の別名

curses.ACS_SBSS

右向き T 字罫線の別名

curses.ACS_SSBB

左下角の別名

curses.ACS_SSBS

下向き T 字罫線の別名

curses.ACS_SSSB

左向き T 字罫線の別名

curses.ACS_SSSS

交差罫線または大プラス記号の別名

curses.ACS_STERLING

ポンドスターリング記号

curses.ACS_TTEE

上向き T 字罫線

curses.ACS_UARROW

上向き矢印

curses.ACS_ULCORNER

左上角

curses.ACS_URCORNER

右上角

curses.ACS_VLINE

垂直線

The following table lists mouse button constants used by getmouse():

Mouse button constant

意味

curses.BUTTONn_PRESSED

Mouse button n pressed

curses.BUTTONn_RELEASED

Mouse button n released

curses.BUTTONn_CLICKED

Mouse button n clicked

curses.BUTTONn_DOUBLE_CLICKED

Mouse button n double clicked

curses.BUTTONn_TRIPLE_CLICKED

Mouse button n triple clicked

curses.BUTTON_SHIFT

Shift was down during button state change

curses.BUTTON_CTRL

Control was down during button state change

curses.BUTTON_ALT

Control was down during button state change

バージョン 3.10 で変更: The BUTTON5_* constants are now exposed if they are provided by the underlying curses library.

以下のテーブルは定義済みの色を列挙したものです:

定数

色

curses.COLOR_BLACK

黒

curses.COLOR_BLUE

青

curses.COLOR_CYAN

シアン (薄く緑がかった青)

curses.COLOR_GREEN

緑

curses.COLOR_MAGENTA

マゼンタ (紫がかった赤)

curses.COLOR_RED

赤

curses.COLOR_WHITE

白

curses.COLOR_YELLOW

黄色

curses.textpad --- curses プログラムのためのテキスト入力ウィジェット

curses.textpad モジュールでは、curses ウィンドウ内での基本的なテキスト編集を処理し、Emacs に似た (すなわち Netscape Navigator, BBedit 6.x, FrameMaker, その他諸々のプログラムとも似た) キーバインドをサポートしている Textbox クラスを提供します。このモジュールではまた、テキストボックスを枠で囲むなどの目的のために有用な、矩形描画関数を提供しています。

curses.textpad モジュールでは以下の関数を定義しています:

curses.textpad.rectangle(win, uly, ulx, lry, lrx)

矩形を描画します。最初の引数はウィンドウオブジェクトでなければなりません; 残りの引数はそのウィンドウからの相対座標になります。2 番目および 3 番目の引数は描画すべき矩形の左上角の y および x 座標です; 4 番目および 5 番目の引数は右下角の y および x 座標です。矩形は、VT100/IBM PC におけるフォーム文字を利用できる端末 (xterm やその他のほとんどのソフトウェア端末エミュレータを含む) ではそれを使って描画されます。そうでなければ ASCII 文字のダッシュ、垂直バー、およびプラス記号で描画されます。

Textbox オブジェクト

以下のような Textbox オブジェクトをインスタンス生成することができます:

class curses.textpad.Textbox(win)

テキストボックスウィジェットオブジェクトを返します。win 引数は、テキストボックスを入れるための ウィンドウ オブジェクトでなければなりません。テキストボックスの編集カーソルは、最初はテキストボックスが入っているウィンドウの左上角に配置され、その座標は (0, 0) です。インスタンスの stripspaces フラグの初期値はオンに設定されます。

Textbox オブジェクトは以下のメソッドを持ちます:

edit([validator])

普段使うことになるエントリポイントです。終了キーストロークの一つが入力されるまで編集キーストロークを受け付けます。validator を与える場合、関数でなければなりません。validator はキーストロークが入力されるたびにそのキーストロークが引数となって呼び出されます; 返された値に対して、コマンドキーストロークとして解釈が行われます。このメソッドはウィンドウの内容を文字列として返します; ウィンドウ内の空白が含められるかどうかは stripspaces 属性で決められます。

do_command(ch)

単一のコマンドキーストロークを処理します。以下にサポートされている特殊キーストロークを示します:

キーストローク

動作

Control-A

ウィンドウの左端に移動します。

Control-B

カーソルを左へ移動し、必要なら前の行に折り返します。

Control-D

カーソル下の文字を削除します。

Control-E

右端 (stripspaces がオフのとき) または行末 (stripspaces がオンのとき) に移動します。

Control-F

カーソルを右に移動し、必要なら次の行に折り返します。

Control-G

ウィンドウを終了し、その内容を返します。

Control-H

逆方向に文字を削除します。

Control-J

ウィンドウが 1 行であれば終了し、そうでなければ新しい行を挿入します。

Control-K

行が空白行ならその行全体を削除し、そうでなければカーソル以降行末までを消去します。

Control-L

スクリーンを更新します。

Control-N

カーソルを下に移動します; 1 行下に移動します。

Control-O

カーソルの場所に空行を 1 行挿入します。

Control-P

カーソルを上に移動します; 1 行上に移動します。

移動操作は、カーソルがウィンドウの縁にあって移動ができない場合には何も行いません。場合によっては、以下のような同義のキーストロークがサポートされています:

定数

キーストローク

KEY_LEFT

Control-B

KEY_RIGHT

Control-F

KEY_UP

Control-P

KEY_DOWN

Control-N

KEY_BACKSPACE

Control-h

他のキーストロークは、与えられた文字を挿入し、(行折り返し付きで) 右に移動するコマンドとして扱われます。

gather()

ウィンドウの内容を文字列として返します; ウィンドウ内の空白が含められるかどうかは stripspaces メンバ変数で決められます。

stripspaces

この属性はウィンドウ内の空白領域の解釈方法を制御するためのフラグです。フラグがオンに設定されている場合、各行の末端にある空白領域は無視されます; すなわち、末端空白領域にカーソルが入ると、その場所の代わりに行の末尾にカーソルが移動します。また、末端の空白領域はウィンドウの内容を取得する際に剥ぎ取られます。

curses.ascii --- Utilities for ASCII characters

ソースコード: Lib/curses/ascii.py [https://github.com/python/cpython/tree/3.12/Lib/curses/ascii.py]

curses.ascii モジュールでは、 ASCII 文字を指す名前定数と、様々な ASCII 文字区分についてある文字が帰属するかどうかを調べる関数を提供します。このモジュールで提供されている定数は以下の制御文字の名前です:

名前

意味

curses.ascii.NUL

curses.ascii.SOH

ヘディング開始、コンソール割り込み

curses.ascii.STX

テキスト開始

curses.ascii.ETX

テキスト終了

curses.ascii.EOT

テキスト伝送終了

curses.ascii.ENQ

問い合わせ、 ACK フロー制御時に使用

curses.ascii.ACK

肯定応答

curses.ascii.BEL

ベル

curses.ascii.BS

一文字後退

curses.ascii.TAB

タブ

curses.ascii.HT

TAB の別名: "水平タブ"

curses.ascii.LF

改行

curses.ascii.NL

LF の別名: "改行"

curses.ascii.VT

垂直タブ

curses.ascii.FF

改頁

curses.ascii.CR

復帰

curses.ascii.SO

シフトアウト、他の文字セットの開始

curses.ascii.SI

シフトイン、標準の文字セットに復帰

curses.ascii.DLE

データリンクでのエスケープ

curses.ascii.DC1

装置制御 1、フロー制御のための XON

curses.ascii.DC2

装置制御 2、ブロックモードフロー制御

curses.ascii.DC3

装置制御 3、フロー制御のための XOFF

curses.ascii.DC4

装置制御 4

curses.ascii.NAK

否定応答

curses.ascii.SYN

同期信号

curses.ascii.ETB

ブロック転送終了

curses.ascii.CAN

キャンセル (Cancel)

curses.ascii.EM

媒体終端

curses.ascii.SUB

代入文字

curses.ascii.ESC

エスケープ文字

curses.ascii.FS

ファイル区切り文字

curses.ascii.GS

グループ区切り文字

curses.ascii.RS

レコード区切り文字、ブロックモード終了子

curses.ascii.US

単位区切り文字

curses.ascii.SP

空白文字

curses.ascii.DEL

削除

これらの大部分は、最近は実際に定数の意味通りに使われることがほとんどないので注意してください。これらのニーモニック符号はデジタル計算機より前のテレプリンタにおける慣習から付けられたものです。

このモジュールでは、標準 C ライブラリの関数を雛型とする以下の関数をサポートしています:

curses.ascii.isalnum(c)

ASCII 英数文字かどうかを調べます; isalpha(c) or isdigit(c) と等価です。

curses.ascii.isalpha(c)

ASCII アルファベット文字かどうかを調べます; isupper(c) or islower(c) と等価です。

curses.ascii.isascii(c)

文字が 7 ビット ASCII 文字に合致するかどうかを調べます。

curses.ascii.isblank(c)

ASCII 余白文字、すなわち空白または水平タブかどうかを調べます。

curses.ascii.iscntrl(c)

ASCII 制御文字 (0x00 から 0x1f の範囲または 0x7f) かどうかを調べます。

curses.ascii.isdigit(c)

ASCII 10 進数字、すなわち '0' から '9' までの文字かどうかを調べます。c in string.digits と等価です。

curses.ascii.isgraph(c)

空白以外の ASCII 印字可能文字かどうかを調べます。

curses.ascii.islower(c)

ASCII 小文字かどうかを調べます。

curses.ascii.isprint(c)

空白文字を含め、ASCII 印字可能文字かどうかを調べます。

curses.ascii.ispunct(c)

空白または英数字以外の ASCII 印字可能文字かどうかを調べます。

curses.ascii.isspace(c)

ASCII 余白文字、すなわち空白、改行、復帰、改頁、水平タブ、垂直タブかどうかを調べます。

curses.ascii.isupper(c)

ASCII 大文字かどうかを調べます。

curses.ascii.isxdigit(c)

ASCII 16 進数字かどうかを調べます。c in string.hexdigits と等価です。

curses.ascii.isctrl(c)

ASCII 制御文字 (0 から 31 までの値) かどうかを調べます。

curses.ascii.ismeta(c)

非 ASCII 文字 (0x80 またはそれ以上の値) かどうかを調べます。

これらの関数は数字も 1 文字の文字列も使えます; 引数を文字列にした場合、組み込み関数 ord() を使って変換されます。

これらの関数は全て、関数に渡した文字列の文字から得られたビット値を調べるので注意してください; 関数はホスト計算機で使われている文字列エンコーディングについて何ら関知しません。

以下の 2 つの関数は、引数として 1 文字の文字列または整数で表したバイト値のどちらでもとり得ます; これらの関数は引数と同じ型で値を返します。

curses.ascii.ascii(c)

ASCII 値を返します。c の下位 7 ビットに対応します。

curses.ascii.ctrl(c)

与えた文字に対応する制御文字を返します (0x1f とビット単位で論理積を取ります)。

curses.ascii.alt(c)

与えた文字に対応する 8 ビット文字を返します (0x80 とビット単位で論理和を取ります)。

以下の関数は 1 文字からなる文字列値または整数値を引数に取り、文字列を返します。

curses.ascii.unctrl(c)

ASCII 文字 c の文字列表現を返します。もし c が印字可能文字であれば、返される文字列は c そのものになります。もし c が制御文字 (0x00--0x1f) であれば、キャレット ('^') と、その後ろに続く c に対応した大文字からなる文字列になります。 c が ASCII 削除文字 (0x7f) であれば、文字列は '^?' になります。 c のメタビット (0x80) がセットされていれば、メタビットは取り去られ、前述のルールが適用され、'!' が前につけられます。

curses.ascii.controlnames

0 (NUL) から 0x1f (US) までの 32 の ASCII 制御文字と、空白文字 SP のニーモニック符号名からなる 33 要素の文字列によるシーケンスです。

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

パネルは深さ (depth) の機能が追加されたウィンドウです。これにより、ウィンドウをお互いに重ね合わせることができ、各ウィンドウの可視部分だけが表示されます。パネルはスタック中に追加したり、スタック内で上下移動させたり、スタックから除去することができます。

関数

curses.panel では以下の関数を定義しています:

curses.panel.bottom_panel()

パネルスタックの最下層のパネルを返します。

curses.panel.new_panel(win)

与えられたウィンドウ win に関連付けられたパネルオブジェクトを返します。返されたパネルオブジェクトを参照しておく必要があることに注意してください。もし参照しなければ、パネルオブジェクトはガベージコレクションされてパネルスタックから削除されます。

curses.panel.top_panel()

パネルスタックの最上層のパネルを返します。

curses.panel.update_panels()

仮想スクリーンをパネルスタック変更後の状態に更新します。この関数では curses.doupdate() を呼ばないので、ユーザは自分で呼び出す必要があります。

Panel オブジェクト

上記の new_panel() が返す Panel オブジェクトはスタック順の概念を持つウィンドウです。ウィンドウはパネルに関連付けられており、表示する内容を決定している一方、パネルのメソッドはパネルスタック中のウィンドウの深さ管理を担います。

Panel オブジェクトは以下のメソッドを持っています:

Panel.above()

現在のパネルの上にあるパネルを返します。

Panel.below()

現在のパネルの下にあるパネルを返します。

Panel.bottom()

パネルをスタックの最下層にプッシュします。

Panel.hidden()

パネルが隠れている (不可視である) 場合に True を返し、そうでない場合 False を返します。

Panel.hide()

パネルを隠します。この操作ではオブジェクトは消去されず、スクリーン上のウィンドウを不可視にするだけです。

Panel.move(y, x)

パネルをスクリーン座標 (y, x) に移動します。

Panel.replace(win)

パネルに関連付けられたウィンドウを win に変更します。

Panel.set_userptr(obj)

パネルのユーザポインタを obj に設定します。このメソッドは任意のデータをパネルに関連付けるために使われ、任意の Python オブジェクトにすることができます。

Panel.show()

(隠れているはずの) パネルを表示します。

Panel.top()

パネルをスタックの最上層にプッシュします。

Panel.userptr()

パネルのユーザポインタを返します。任意の Python オブジェクトです。

Panel.window()

パネルに関連付けられているウィンドウオブジェクトを返します。

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

ソースコード: Lib/platform.py [https://github.com/python/cpython/tree/3.12/Lib/platform.py]

注釈

プラットフォーム毎にアルファベット順に並べています。Linuxについては Unixセクションを参照してください。

クロスプラットフォーム

platform.architecture(executable=sys.executable, bits='', linkage='')

executable で指定した実行可能ファイル（省略時はPythonインタープリタのバイナリ）の各種アーキテクチャ情報を調べます。

戻り値はタプル (bits, linkage) で、アーキテクチャのビット数と実行可能ファイルのリンク形式を示します。どちらの値も文字列で返ります。

値を決定できない場合はパラメータプリセットから与えられる値を返します。bits に '' を与えた場合、サポートされているポインタサイズを知るために sizeof(pointer) (Python バージョン < 1.5.2 では sizeof(long)) が使用されます。

この関数は、システムの file コマンドを使用します。 file はほとんどのUnixプラットフォームと一部の非Unixプラットフォームで利用可能ですが、 file コマンドが利用できず、かつ executable が Pythonインタープリタでない場合には適切なデフォルト値が返ります。

注釈

macOS (とひょっとすると他のプラットフォーム) では、実行可能ファイルは複数のアーキテクチャを含んだユニバーサル形式かもしれません。

To get at the "64-bitness" of the current interpreter, it is more reliable to query the sys.maxsize attribute:

is_64bits = sys.maxsize > 2**32

platform.machine()

Returns the machine type, e.g. 'AMD64'. An empty string is returned if the value cannot be determined.

platform.node()

コンピュータのネットワーク名を返します。ネットワーク名は完全修飾名とは限りません。不明な場合は空文字列を返します。

platform.platform(aliased=False, terse=False)

実行中プラットフォームを識別する文字列を返します。この文字列には、有益な情報をできるだけ多く付加しています。

戻り値は機械で処理しやすい形式ではなく、人間にとって読みやすい 形式となっています。異なったプラットフォームでは異なった戻り値となるようになっています。

aliased が真なら、システムの名称として一般的な名称ではなく、別名を使用して結果を返します。たとえば、SunOS は Solaris となります。この機能は system_alias() で実装されています。

terse が真なら、プラットフォームを特定するために最低限必要な情報だけを返します。

バージョン 3.8 で変更: macOSでは、 mac_ver() が空でないリリース文字列を返すとき、darwin のバージョンではなく macOS のバージョンを取得するために、この関数は mac_ver() を使うようになりました。

platform.processor()

'amdk6' のような、（現実の）プロセッサ名を返します。

不明な場合は空文字列を返します。NetBSDのようにこの情報を提供しない、または machine() と同じ値しか返さないプラットフォームも多く存在しますので、注意してください。

platform.python_build()

Pythonのビルド番号と日付を、(buildno, builddate) のタプルで返します。

platform.python_compiler()

Pythonをコンパイルする際に使用したコンパイラを示す文字列を返します。

platform.python_branch()

Python実装のバージョン管理システム上のブランチを特定する文字列を返します。

platform.python_implementation()

Python実装を指定する文字列を返します。戻り値は: 'CPython', 'IronPython', 'Jython', 'PyPy' のいずれかです。

platform.python_revision()

Python実装のバージョン管理システム上のリビジョンを特定する文字列を返します。

platform.python_version()

Python のバージョンを、'major.minor.patchlevel' 形式の文字列で返します。

sys.version と異なり、patchlevel（デフォルトでは0)も必ず含まれています。

platform.python_version_tuple()

Pythonのバージョンを、文字列のタプル (major, minor, patchlevel) で返します。

sys.version と異なり、patchlevel（デフォルトでは '0')も必ず含まれています。

platform.release()

'2.2.0' や 'NT' のような、システムのリリース情報を返します。不明な場合は空文字列を返します。

platform.system()

'Linux' 、 'Darwin' 、 'Java' 、 'Windows' のような、システム/OS 名を返します。不明な場合は空文字列を返します。

platform.system_alias(system, release, version)

マーケティング目的で使われる一般的な別名に変換して (system, release, version) を返します。混乱を避けるために、情報を並べなおす場合があります。

platform.version()

'#3 on degas' のような、システムのリリース情報を返します。不明な場合は空文字列を返します。

platform.uname()

極めて可搬性の高い uname インターフェースです。 system, node, release, version, machine, processor の6つの属性を持った namedtuple() を返します。

processor is resolved late, on demand.

Note: the first two attribute names differ from the names presented by os.uname(), where they are named sysname and nodename.

不明な項目は '' となります。

バージョン 3.3 で変更: 結果が タプル から namedtuple() へ変更されました。

バージョン 3.9 で変更: processor is resolved late instead of immediately.

Java プラットフォーム

platform.java_ver(release='', vendor='', vminfo=('', '', ''), osinfo=('', '', ''))

Jython用のバージョンインターフェースです。

タプル (release, vendor, vminfo, osinfo) を返します。vminfo はタプル (vm_name, vm_release, vm_vendor)、osinfo はタプル (os_name, os_version, os_arch) です。不明な項目は引数で指定した値(デフォルトは '') となります。

Windows プラットフォーム

platform.win32_ver(release='', version='', csd='', ptype='')

Get additional version information from the Windows Registry and return a tuple (release, version, csd, ptype) referring to OS release, version number, CSD level (service pack) and OS type (multi/single processor). Values which cannot be determined are set to the defaults given as parameters (which all default to an empty string).

As a hint: ptype is 'Uniprocessor Free' on single processor NT machines and 'Multiprocessor Free' on multi processor machines. The 'Free' refers to the OS version being free of debugging code. It could also state 'Checked' which means the OS version uses debugging code, i.e. code that checks arguments, ranges, etc.

platform.win32_edition()

Returns a string representing the current Windows edition, or None if the value cannot be determined. Possible values include but are not limited to 'Enterprise', 'IoTUAP', 'ServerStandard', and 'nanoserver'.

Added in version 3.8.

platform.win32_is_iot()

win32_edition() によって返された Windows のエディションが IoT エディションの時 True を返します。

Added in version 3.8.

macOS プラットフォーム

platform.mac_ver(release='', versioninfo=('', '', ''), machine='')

macOS のバージョン情報を、タプル (release, versioninfo, machine) で返します。versioninfo は、タプル (version, dev_stage, non_release_version) です。

不明な項目は '' となります。タプルの要素は全て文字列です。

Unix プラットフォーム

platform.libc_ver(executable=sys.executable, lib='', version='', chunksize=16384)

executableで指定したファイル（省略時はPythonインタープリタ）がリンクしているlibcバージョンの取得を試みます。戻り値は文字列のタプル (lib, version) で、不明な項目は引数で指定した値となります。

この関数は、実行形式に追加されるシンボルの細かな違いによって、libcのバージョンを特定します。この違いは gcc でコンパイルされた実行可能ファイルでのみ有効だと思われます。

chunksize にはファイルから情報を取得するために読み込むバイト数を指定します。

Linux プラットフォーム

platform.freedesktop_os_release()

Get operating system identification from os-release file and return it as a dict. The os-release file is a freedesktop.org standard [https://www.freedesktop.org/software/systemd/man/os-release.html] and is available in most Linux distributions. A noticeable exception is Android and Android-based distributions.

Raises OSError or subclass when neither /etc/os-release nor /usr/lib/os-release can be read.

On success, the function returns a dictionary where keys and values are strings. Values have their special characters like " and $ unquoted. The fields NAME, ID, and PRETTY_NAME are always defined according to the standard. All other fields are optional. Vendors may include additional fields.

Note that fields like NAME, VERSION, and VARIANT are strings suitable for presentation to users. Programs should use fields like ID, ID_LIKE, VERSION_ID, or VARIANT_ID to identify Linux distributions.

以下はプログラム例です:

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

Added in version 3.10.

errno --- Standard errno system symbols

このモジュールから標準の errno システムシンボルを取得することができます。個々のシンボルの値は errno に対応する整数値です。これらのシンボルの名前は、 linux/include/errno.h から借用されており、網羅的なはずです。

errno.errorcode

errno 値を背後のシステムにおける文字列表現に対応付ける辞書です。例えば、errno.errorcode[errno.EPERM] は 'EPERM' に対応付けられます。

数値のエラーコードをエラーメッセージに変換するには、 os.strerror() を使ってください。

以下のリストの内、現在のプラットフォームで使われていないシンボルはモジュール上で定義されていません。定義されているシンボルだけを挙げたリストは errno.errorcode.keys() として取得することができます。取得できるシンボルには以下のようなものがあります:

errno.EPERM

Operation not permitted. This error is mapped to the exception PermissionError.

errno.ENOENT

No such file or directory. This error is mapped to the exception FileNotFoundError.

errno.ESRCH

No such process. This error is mapped to the exception ProcessLookupError.

errno.EINTR

Interrupted system call. This error is mapped to the exception InterruptedError.

errno.EIO

I/O エラーです (I/O error)

errno.ENXIO

そのようなデバイスまたはアドレスは存在しません (No such device or address)

errno.E2BIG

引数リストが長すぎます (Arg list too long)

errno.ENOEXEC

実行形式にエラーがあります (Exec format error)

errno.EBADF

ファイル番号が間違っています (Bad file number)

errno.ECHILD

No child processes. This error is mapped to the exception ChildProcessError.

errno.EAGAIN

Try again. This error is mapped to the exception BlockingIOError.

errno.ENOMEM

空きメモリがありません (Out of memory)

errno.EACCES

Permission denied. This error is mapped to the exception PermissionError.

errno.EFAULT

不正なアドレスです (Bad address)

errno.ENOTBLK

ブロックデバイスが必要です (Block device required)

errno.EBUSY

そのデバイスまたはリソースは使用中です (Device or resource busy)

errno.EEXIST

File exists. This error is mapped to the exception FileExistsError.

errno.EXDEV

デバイスをまたいだリンクです (Cross-device link)

errno.ENODEV

そのようなデバイスはありません (No such device)

errno.ENOTDIR

Not a directory. This error is mapped to the exception NotADirectoryError.

errno.EISDIR

Is a directory. This error is mapped to the exception IsADirectoryError.

errno.EINVAL

無効な引数です (Invalid argument)

errno.ENFILE

ファイルテーブルがオーバフローしています (File table overflow)

errno.EMFILE

開かれたファイルが多すぎます (Too many open files)

errno.ENOTTY

タイプライタではありません (Not a typewriter)

errno.ETXTBSY

テキストファイルが使用中です (Text file busy)

errno.EFBIG

ファイルが大きすぎます (File too large)

errno.ENOSPC

デバイス上に空きがありません (No space left on device)

errno.ESPIPE

不正なシークです (Illegal seek)

errno.EROFS

リードオンリーのファイルシステムです (Read-only file system)

errno.EMLINK

リンクが多すぎます (Too many links)

errno.EPIPE

Broken pipe. This error is mapped to the exception BrokenPipeError.

errno.EDOM

数学引数が関数の定義域を越えています (Math argument out of domain of func)

errno.ERANGE

表現できない数学演算結果になりました (Math result not representable)

errno.EDEADLK

リソースのデッドロックが起きます (Resource deadlock would occur)

errno.ENAMETOOLONG

ファイル名が長すぎます (File name too long)

errno.ENOLCK

レコードロッキングが利用できません (No record locks available)

errno.ENOSYS

実装されていない機能です (Function not implemented)

errno.ENOTEMPTY

ディレクトリが空ではありません (Directory not empty)

errno.ELOOP

これ以上シンボリックリンクを追跡できません (Too many symbolic links encountered)

errno.EWOULDBLOCK

Operation would block. This error is mapped to the exception BlockingIOError.

errno.ENOMSG

指定された型のメッセージはありません (No message of desired type)

errno.EIDRM

識別子が除去されました (Identifier removed)

errno.ECHRNG

チャネル番号が範囲を超えました (Channel number out of range)

errno.EL2NSYNC

レベル 2 で同期がとれていません (Level 2 not synchronized)

errno.EL3HLT

レベル 3 で終了しました (Level 3 halted)

errno.EL3RST

レベル 3 でリセットしました (Level 3 reset)

errno.ELNRNG

リンク番号が範囲を超えています (Link number out of range)

errno.EUNATCH

プロトコルドライバが接続されていません (Protocol driver not attached)

errno.ENOCSI

CSI 構造体がありません (No CSI structure available)

errno.EL2HLT

レベル 2 で終了しました (Level 2 halted)

errno.EBADE

無効な変換です (Invalid exchange)

errno.EBADR

無効な要求記述子です (Invalid request descriptor)

errno.EXFULL

変換テーブルが一杯です (Exchange full)

errno.ENOANO

陰極がありません (No anode)

errno.EBADRQC

無効なリクエストコードです (Invalid request code)

errno.EBADSLT

無効なスロットです (Invalid slot)

errno.EDEADLOCK

ファイルロックにおけるデッドロックエラーです (File locking deadlock error)

errno.EBFONT

フォントファイル形式が間違っています (Bad font file format)

errno.ENOSTR

ストリーム型でないデバイスです (Device not a stream)

errno.ENODATA

利用可能なデータがありません (No data available)

errno.ETIME

時間切れです (Timer expired)

errno.ENOSR

ストリームリソースを使い切りました (Out of streams resources)

errno.ENONET

計算機はネットワーク上にありません (Machine is not on the network)

errno.ENOPKG

パッケージがインストールされていません (Package not installed)

errno.EREMOTE

対象物は遠隔にあります (Object is remote)

errno.ENOLINK

リンクが切られました (Link has been severed)

errno.EADV

Advertise エラーです (Advertise error)

errno.ESRMNT

Srmount エラーです (Srmount error)

errno.ECOMM

送信時の通信エラーです (Communication error on send)

errno.EPROTO

プロトコルエラーです (Protocol error)

errno.EMULTIHOP

多重ホップを試みました (Multihop attempted)

errno.EDOTDOT

RFS 特有のエラーです (RFS specific error)

errno.EBADMSG

データメッセージではありません (Not a data message)

errno.EOVERFLOW

定義されたデータ型にとって大きすぎる値です (Value too large for defined data type)

errno.ENOTUNIQ

名前がネットワーク上で一意でありません (Name not unique on network)

errno.EBADFD

ファイル記述子の状態が不正です (File descriptor in bad state)

errno.EREMCHG

遠隔のアドレスが変更されました (Remote address changed)

errno.ELIBACC

必要な共有ライブラリにアクセスできません (Can not access a needed shared library)

errno.ELIBBAD

壊れた共有ライブラリにアクセスしています (Accessing a corrupted shared library)

errno.ELIBSCN

a.out の .lib セクションが壊れています (.lib section in a.out corrupted)

errno.ELIBMAX

リンクを試みる共有ライブラリが多すぎます (Attempting to link in too many shared libraries)

errno.ELIBEXEC

共有ライブラリを直接実行することができません (Cannot exec a shared library directly)

errno.EILSEQ

不正なバイト列です (Illegal byte sequence)

errno.ERESTART

割り込みシステムコールを復帰しなければなりません (Interrupted system call should be restarted)

errno.ESTRPIPE

ストリームパイプのエラーです (Streams pipe error)

errno.EUSERS

ユーザが多すぎます (Too many users)

errno.ENOTSOCK

非ソケットに対するソケット操作です (Socket operation on non-socket)

errno.EDESTADDRREQ

目的アドレスが必要です (Destination address required)

errno.EMSGSIZE

メッセージが長すぎます (Message too long)

errno.EPROTOTYPE

ソケットに対して不正なプロトコル型です (Protocol wrong type for socket)

errno.ENOPROTOOPT

利用できないプロトコルです (Protocol not available)

errno.EPROTONOSUPPORT

サポートされていないプロトコルです (Protocol not supported)

errno.ESOCKTNOSUPPORT

サポートされていないソケット型です (Socket type not supported)

errno.EOPNOTSUPP

通信端点に対してサポートされていない操作です (Operation not supported on transport endpoint)

errno.ENOTSUP

Operation not supported

Added in version 3.2.

errno.EPFNOSUPPORT

サポートされていないプロトコルファミリです (Protocol family not supported)

errno.EAFNOSUPPORT

プロトコルでサポートされていないアドレスファミリです (Address family not supported by protocol)

errno.EADDRINUSE

アドレスは使用中です (Address already in use)

errno.EADDRNOTAVAIL

要求されたアドレスを割り当てできません (Cannot assign requested address)

errno.ENETDOWN

ネットワークがダウンしています (Network is down)

errno.ENETUNREACH

ネットワークに到達できません (Network is unreachable)

errno.ENETRESET

リセットによってネットワーク接続が切られました (Network dropped connection because of reset)

errno.ECONNABORTED

Software caused connection abort. This error is mapped to the exception ConnectionAbortedError.

errno.ECONNRESET

Connection reset by peer. This error is mapped to the exception ConnectionResetError.

errno.ENOBUFS

バッファに空きがありません (No buffer space available)

errno.EISCONN

通信端点がすでに接続されています (Transport endpoint is already connected)

errno.ENOTCONN

通信端点が接続されていません (Transport endpoint is not connected)

errno.ESHUTDOWN

Cannot send after transport endpoint shutdown. This error is mapped to the exception BrokenPipeError.

errno.ETOOMANYREFS

参照が多すぎます: 接続できません (Too many references: cannot splice)

errno.ETIMEDOUT

Connection timed out. This error is mapped to the exception TimeoutError.

errno.ECONNREFUSED

Connection refused. This error is mapped to the exception ConnectionRefusedError.

errno.EHOSTDOWN

ホストはシステムダウンしています (Host is down)

errno.EHOSTUNREACH

ホストへの経路がありません (No route to host)

errno.EALREADY

Operation already in progress. This error is mapped to the exception BlockingIOError.

errno.EINPROGRESS

Operation now in progress. This error is mapped to the exception BlockingIOError.

errno.ESTALE

無効な NFS ファイルハンドルです (Stale NFS file handle)

errno.EUCLEAN

構造のクリーニングが必要です (Structure needs cleaning)

errno.ENOTNAM

XENIX 名前付きファイルではありません (Not a XENIX named type file)

errno.ENAVAIL

XENIX セマフォは利用できません (No XENIX semaphores available)

errno.EISNAM

名前付きファイルです (Is a named type file)

errno.EREMOTEIO

遠隔側の I/O エラーです (Remote I/O error)

errno.EDQUOT

ディスククオータを超えました (Quota exceeded)

errno.EQFULL

Interface output queue is full

Added in version 3.11.

errno.ENOTCAPABLE

Capabilities insufficient. This error is mapped to the exception PermissionError.

利用可能な環境: WASI, FreeBSD

Added in version 3.11.1.

errno.ECANCELED

Operation canceled

Added in version 3.2.

errno.EOWNERDEAD

Owner died

Added in version 3.2.

errno.ENOTRECOVERABLE

State not recoverable

Added in version 3.2.

ctypes --- A foreign function library for Python

ソースコード: Lib/ctypes [https://github.com/python/cpython/tree/3.12/Lib/ctypes]

ctypes は Python のための外部関数ライブラリです。このライブラリは C と互換性のあるデータ型を提供し、動的リンク/共有ライブラリ内の関数呼び出しを可能にします。動的リンク/共有ライブラリを純粋な Python でラップするために使うことができます。

ctypesチュートリアル

注意: このチュートリアルのコードサンプルは動作確認のために doctest を使います。コードサンプルの中には Linux、 Windows、あるいは macOS 上で異なる動作をするものがあるため、サンプルのコメントに doctest 命令を入れてあります。

注意: いくつかのコードサンプルで ctypes の c_int 型を参照しています。 sizeof(long) == sizeof(int) であるようなプラットフォームでは、この型は c_long のエイリアスです。そのため、 c_int 型を想定しているときに c_long が表示されたとしても、混乱しないようにしてください --- 実際には同じ型なのです。

動的リンクライブラリをロードする

動的リンクライブラリをロードするために、 ctypes は cdll をエクスポートします。 Windows では windll と oledll オブジェクトをエクスポートします。

You load libraries by accessing them as attributes of these objects. cdll loads libraries which export functions using the standard cdecl calling convention, while windll libraries call functions using the stdcall calling convention. oledll also uses the stdcall calling convention, and assumes the functions return a Windows HRESULT error code. The error code is used to automatically raise an OSError exception when the function call fails.

バージョン 3.3 で変更: Windows エラーは以前は WindowsError を送出していましたが、これは現在では OSError の別名になっています。

Windows用の例ですが、 msvcrt はほとんどの標準 C 関数が含まれている MS 標準 C ライブラリであり、 cdecl 呼び出し規約を使うことに注意してください:

>>> from ctypes import *
>>> print(windll.kernel32)
<WinDLL 'kernel32', handle ... at ...>
>>> print(cdll.msvcrt)
<CDLL 'msvcrt', handle ... at ...>
>>> libc = cdll.msvcrt
>>>

Windows では通常の .dll ファイル拡張子を自動的に追加します。

注釈

cdll.msvcrt 経由で標準 C ライブラリにアクセスすると、Python が使用しているライブラリとは互換性のない可能性のある、古いバージョンのライブラリが使用されます。可能な場合には、ネイティブ Python の機能を使用するか、msvcrt モジュールをインポートして使用してください。

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

>>> cdll.LoadLibrary("libc.so.6")
<CDLL 'libc.so.6', handle ... at ...>
>>> libc = CDLL("libc.so.6")
>>> libc
<CDLL 'libc.so.6', handle ... at ...>
>>>

ロードしたdllから関数にアクセスする

dll オブジェクトの属性として関数にアクセスします:

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

kernel32 や user32 のような win32 システム dll は、多くの場合関数の UNICODE バージョンに加えて ANSI バージョンもエクスポートすることに注意してください。 UNICODE バージョンは後ろに W が付いた名前でエクスポートされ、 ANSI バージョンは A が付いた名前でエクスポートされます。与えられたモジュールの モジュールハンドル を返す win32 GetModuleHandle 関数は次のような C プロトタイプを持ちます。 UNICODE バージョンが定義されているかどうかにより GetModuleHandle としてどちらか一つを公開するためにマクロが使われます:

/* ANSI version */
HMODULE GetModuleHandleA(LPCSTR lpModuleName);
/* UNICODE version */
HMODULE GetModuleHandleW(LPCWSTR lpModuleName);

windll は魔法を使ってどちらか一つを選ぶようなことはしません。GetModuleHandleA もしくは GetModuleHandleW を明示的に指定して必要とするバージョンにアクセスし、バイト列か文字列を使ってそれぞれ呼び出さなければなりません。

時には、 dll が関数を "??2@YAPAXI@Z" のような Python 識別子として有効でない名前でエクスポートすることがあります。このような場合に関数を取り出すには、 getattr() を使わなければなりません。:

>>> getattr(cdll.msvcrt, "??2@YAPAXI@Z")
<_FuncPtr object at 0x...>
>>>

Windows では、名前ではなく序数によって関数をエクスポートする dll もあります。こうした関数には序数を使って dll オブジェクトにインデックス指定することでアクセスします:

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

関数を呼び出す

You can call these functions like any other Python callable. This example uses the rand() function, which takes no arguments and returns a pseudo-random integer:

>>> print(libc.rand())
1804289383

On Windows, you can call the GetModuleHandleA() function, which returns a win32 module handle (passing None as single argument to call it with a NULL pointer):

>>> print(hex(windll.kernel32.GetModuleHandleA(None)))
0x1d000000
>>>

cdecl 呼び出し規約を使って stdcall 関数を呼び出したときには、 ValueError が送出されます。逆の場合も同様です:

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

正しい呼び出し規約を知るためには、呼び出したい関数についての C ヘッダファイルもしくはドキュメントを見なければなりません。

Windows では、関数が無効な引数とともに呼び出された場合の一般保護例外によるクラッシュを防ぐために、 ctypes は win32 構造化例外処理を使います:

>>> windll.kernel32.GetModuleHandleA(32)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
OSError: exception: access violation reading 0x00000020
>>>

しかしそれでも他に ctypes で Python がクラッシュする状況はあるので、どちらにせよ気を配るべきです。クラッシュのデバッグには、 faulthandler モジュールが役に立つ場合があります (例えば、誤った C ライブラリ呼び出しによって引き起こされたセグメンテーション違反) 。

None, integers, bytes objects and (unicode) strings are the only native Python objects that can directly be used as parameters in these function calls. None is passed as a C 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 platforms default C int type, their value is masked to fit into the C type.

他のパラメータ型をもつ関数呼び出しに移る前に、 ctypes データ型についてさらに学ぶ必要があります。

基本データ型

ctypes ではいくつもの C 互換のプリミティブなデータ型を定義しています:

ctypes の型

C の型

Python の型

c_bool

_Bool

bool (1)

c_char

char

1文字のバイト列オブジェクト

c_wchar

wchar_t

1文字の文字列

c_byte

char

int

c_ubyte

unsigned char

int

c_short

short

int

c_ushort

unsigned short

int

c_int

int

int

c_uint

unsigned int

int

c_long

long

int

c_ulong

unsigned long

int

c_longlong

__int64 または long long

int

c_ulonglong

unsigned __int64 または unsigned long long

int

c_size_t

size_t

int

c_ssize_t

ssize_t or Py_ssize_t

int

c_time_t

time_t

int

c_float

float

浮動小数点数

c_double

double

浮動小数点数

c_longdouble

long double

浮動小数点数

c_char_p

char* (NUL 終端)

バイト列オブジェクトまたは None

c_wchar_p

wchar_t* (NUL 終端)

文字列または None

c_void_p

void*

整数または None

コンストラクタは任意のオブジェクトをその真偽値として受け取ります。

これら全ての型はその型を呼び出すことによって作成でき、オプションとして型と値が合っている初期化子を指定することができます:

>>> c_int()
c_long(0)
>>> c_wchar_p("Hello, World")
c_wchar_p(140018365411392)
>>> c_ushort(-3)
c_ushort(65533)
>>>

これらの型は変更可能であり、値を後で変更することもできます:

>>> i = c_int(42)
>>> print(i)
c_long(42)
>>> print(i.value)
42
>>> i.value = -99
>>> print(i.value)
-99
>>>

新しい値をポインタ型 c_char_p, c_wchar_p および c_void_p のインスタンスへ代入すると、変わるのは指している メモリ位置 であって、メモリブロックの 内容ではありません (これは当然で、なぜなら、 Python バイト列オブジェクトは変更不可能だからです):

>>> s = "Hello, World"
>>> c_s = c_wchar_p(s)
>>> print(c_s)
c_wchar_p(139966785747344)
>>> print(c_s.value)
Hello World
>>> c_s.value = "Hi, there"
>>> print(c_s)              # the memory location has changed
c_wchar_p(139966783348904)
>>> print(c_s.value)
Hi, there
>>> print(s)                # first object is unchanged
Hello, World
>>>

しかし、変更可能なメモリを指すポインタであることを想定している関数へそれらを渡さないように注意すべきです。もし変更可能なメモリブロックが必要なら、 ctypes には create_string_buffer() 関数があり、いろいろな方法で作成することできます。現在のメモリブロックの内容は raw プロパティを使ってアクセス (あるいは変更) することができます。もし現在のメモリブロックに NUL 終端文字列としてアクセスしたいなら、 value プロパティを使ってください:

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

The create_string_buffer() function replaces the old c_buffer() function (which is still available as an alias). To create a mutable memory block containing unicode characters of the C type wchar_t, use the create_unicode_buffer() function.

続・関数を呼び出す

printf は sys.stdout では なく 、本物の標準出力チャンネルへプリントすることに注意してください。したがって、これらの例はコンソールプロンプトでのみ動作し、 IDLE や PythonWin では動作しません。:

>>> 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>
ArgumentError: argument 2: TypeError: Don't know how to convert parameter 2
>>>

前に述べたように、必要な C のデータ型へ変換できるようにするためには、整数、文字列およびバイト列オブジェクトを除くすべての Python 型を対応する ctypes 型でラップしなければなりません:

>>> printf(b"An int %d, a double %f\n", 1234, c_double(3.14))
An int 1234, a double 3.140000
31
>>>

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 argtypes attribute for the regular, non-variadic, function arguments:

libc.printf.argtypes = [ctypes.c_char_p]

Because specifying the attribute does not inhibit portability it is advised to always specify argtypes for all variadic functions.

自作のデータ型とともに関数を呼び出す

You can also customize ctypes argument conversion to allow instances of your own classes be used as function arguments. ctypes looks for an _as_parameter_ attribute and uses this as the function argument. The attribute must be an integer, string, bytes, a ctypes instance, or an object with an _as_parameter_ attribute:

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

If you don't want to store the instance's data in the _as_parameter_ instance variable, you could define a property which makes the attribute available on request.

要求される引数の型を指定する (関数プロトタイプ)

It is possible to specify the required argument types of functions exported from DLLs by setting the argtypes attribute.

argtypes must be a sequence of C data types (the 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):

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

(C の関数のプロトタイプのように) 書式を指定すると互換性のない引数型になるのを防ぎ、引数を有効な型へ変換しようとします。:

>>> printf(b"%d %d %d", 1, 2, 3)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ArgumentError: argument 2: TypeError: wrong type
>>> printf(b"%s %d %f\n", b"X", 2, 3)
X 2 3.000000
13
>>>

If you have defined your own classes which you pass to function calls, you have to implement a from_param() class method for them to be able to use them in the argtypes sequence. The 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 _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 ctypes instance, or an object with an _as_parameter_ attribute.

戻り値の型

By default functions are assumed to return the C int type. Other return types can be specified by setting the restype attribute of the function object.

The C prototype of time() is time_t time(time_t *). Because time_t might be of a different type than the default return type int, you should specify the restype attribute:

>>> libc.time.restype = c_time_t

The argument types can be specified using argtypes:

>>> libc.time.argtypes = (POINTER(c_time_t),)

To call the function with a NULL pointer as first argument, use None:

>>> print(libc.time(None))
1150640792

Here is a more advanced example, it uses the strchr() function, which expects a string pointer and a char, and returns a pointer to a string:

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

If you want to avoid the ord("x") calls above, you can set the argtypes attribute, and the second argument will be converted from a single character Python bytes object into a C char:

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

You can also use a callable Python object (a function or a class for example) as the 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:

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

WinError はエラーコードの文字列表現を得るために Windows の FormatMessage() api を呼び出し、例外を 返す 関数です。 WinError はオプションでエラーコードパラメータを取ります。このパラメータが使われない場合は、エラーコードを取り出すために GetLastError() を呼び出します。

Please note that a much more powerful error checking mechanism is available through the errcheck attribute; see the reference manual for details.

ポインタを渡す(または、パラメータの参照渡し)

時には、 C api 関数がパラメータのデータ型として ポインタ を想定していることがあります。おそらくパラメータと同一の場所に書き込むためか、もしくはそのデータが大きすぎて値渡しできない場合です。これは パラメータの参照渡し としても知られています。

ctypes は byref() 関数をエクスポートしており、パラメータを参照渡しするために使用します。 pointer() 関数を使っても同じ効果が得られます。しかし、 pointer() は本当のポインタオブジェクトを構築するためより多くの処理を行うことから、 Python 側でポインタオブジェクト自体を必要としないならば byref() を使う方がより高速です。:

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

構造体と共用体

Structures and unions must derive from the Structure and Union base classes which are defined in the ctypes module. Each subclass must define a _fields_ attribute. _fields_ must be a list of 2-tuples, containing a field name and a field type.

フィールド型は c_int か他の ctypes 型 (構造体、共用体、配列、ポインタ) から派生した ctypes 型である必要があります。

以下は、 x と y という名前の二つの整数からなる簡単な POINT 構造体の例です。コンストラクタで構造体を初期化する方法も説明しています:

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

しかし、もっと複雑な構造体を構築することもできます。ある構造体は、他の構造体をフィールド型として使うことで、他の構造体を含むことができます。

upperleft と lowerright という名前の二つの POINT を持つ RECT 構造体です。:

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

入れ子になった構造体はいくつかの方法を用いてコンストラクタで初期化することができます。:

>>> r = RECT(POINT(1, 2), POINT(3, 4))
>>> r = RECT((1, 2), (3, 4))

フィールド descriptor (記述子)は クラス から取り出せます。デバッグするときに役に立つ情報を得ることができます:

>>> print(POINT.x)
<Field type=c_long, ofs=0, size=4>
>>> print(POINT.y)
<Field type=c_long, ofs=4, size=4>
>>>

警告

ctypes では、ビットフィールドのある共用体や構造体の関数への値渡しはサポートしていません。これは 32-bit の x86 環境では動くかもしれませんが、このライブラリでは一般の場合に動作することは保証していません。

構造体/共用体アライメントとバイトオーダー

By default, Structure and Union fields are aligned in the same way the C compiler does it. It is possible to override this behavior by specifying a _pack_ class attribute in the subclass definition. This must be set to a positive integer and specifies the maximum alignment for the fields. This is what #pragma pack(n) also does in MSVC.

ctypes は Structure と Union に対してネイティブのバイトオーダーを使います。ネイティブではないバイトオーダーの構造体を作成するには、 BigEndianStructure, LittleEndianStructure, BigEndianUnion および LittleEndianUnion ベースクラスの中の一つを使います。これらのクラスにポインタフィールドを持たせることはできません。

構造体と共用体におけるビットフィールド

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

>>> class Int(Structure):
...     _fields_ = [("first_16", c_int, 16),
...                 ("second_16", c_int, 16)]
...
>>> print(Int.first_16)
<Field type=c_long, ofs=0:0, bits=16>
>>> print(Int.second_16)
<Field type=c_long, ofs=0:16, bits=16>
>>>

配列

配列 (Array) はシーケンスであり、決まった数の同じ型のインスタンスを持ちます。

推奨されている配列の作成方法はデータ型に正の整数を掛けることです。:

TenPointsArrayType = POINT * 10

ややわざとらしいデータ型の例になりますが、他のものに混ざって 4 個の POINT がある構造体です:

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

インスタンスはクラスを呼び出す通常の方法で作成します。:

arr = TenPointsArrayType()
for pt in arr:
    print(pt.x, pt.y)

上記のコードは 0 0 という行が並んだものを表示します。配列の要素がゼロで初期化されているためです。

正しい型の初期化子を指定することもできます。:

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

ポインタ

ポインタのインスタンスは ctypes 型に対して pointer() 関数を呼び出して作成します。:

>>> from ctypes import *
>>> i = c_int(42)
>>> pi = pointer(i)
>>>

次のように、ポインタインスタンスは、ポインタが指すオブジェクト (上の例では i) を返す contents 属性を持ちます:

>>> pi.contents
c_long(42)
>>>

ctypes は OOR (original object return 、元のオブジェクトを返すこと) ではないことに注意してください。属性を取り出す度に、新しい同等のオブジェクトを作成しているのです。:

>>> pi.contents is i
False
>>> pi.contents is pi.contents
False
>>>

別の c_int インスタンスがポインタの contents 属性に代入されると、これが記憶されているメモリ位置を指すポインタに変化します。:

>>> i = c_int(99)
>>> pi.contents = i
>>> pi.contents
c_long(99)
>>>

ポインタインスタンスは整数でインデックス指定することもできます。:

>>> pi[0]
99
>>>

整数インデックスへ代入するとポインタが指す値が変更されます。:

>>> print(i)
c_long(99)
>>> pi[0] = 22
>>> print(i)
c_long(22)
>>>

0 ではないインデックスを使うこともできますが、 C の場合と同じように自分が何をしているかを理解している必要があります。任意のメモリ位置にアクセスもしくは変更できるのです。一般的にこの機能を使うのは、 C 関数からポインタを受け取り、そのポインタが単一の要素ではなく実際に配列を指していると 分かっている 場合だけです。

舞台裏では、 pointer() 関数は単にポインタインスタンスを作成するという以上のことを行っています。はじめにポインタ 型 を作成する必要があります。これは任意の ctypes 型を受け取る POINTER() 関数を使って行われ、新しい型を返します:

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

ポインタ型を引数なしで呼び出すと NULL ポインタを作成します。 NULL ポインタは False ブール値を持っています。:

>>> null_ptr = POINTER(c_int)()
>>> print(bool(null_ptr))
False
>>>

ctypes はポインタの指す値を取り出すときに NULL かどうかを調べます(しかし、 NULL でない不正なポインタの指す値の取り出す行為は Python をクラッシュさせるでしょう)。:

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

型変換

Usually, ctypes does strict type checking. This means, if you have POINTER(c_int) in the 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 POINTER(c_int), ctypes accepts an array of c_int:

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

In addition, if a function argument is explicitly declared to be a pointer type (such as POINTER(c_int)) in argtypes, an object of the pointed type (c_int in this case) can be passed to the function. ctypes will apply the required byref() conversion in this case automatically.

POINTER型フィールドを NULL に設定するために、 None を代入してもかまいません。:

>>> bar.values = None
>>>

時には、非互換な型のインスタンスであることもあります。 C では、ある型を他の型へキャストすることができます。 ctypes は同じやり方で使える cast() 関数を提供しています。上で定義した Bar 構造体は POINTER(c_int) ポインタまたは c_int 配列を values フィールドに対して受け取り、他の型のインスタンスは受け取りません:

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

このような場合には、 cast() 関数が便利です。

cast() 関数は ctypes インスタンスを異なる ctypes データ型を指すポインタへキャストするために使えます。 cast() は二つのパラメータ、ある種のポインタかそのポインタへ変換できる ctypes オブジェクトと、 ctypes ポインタ型を取ります。そして、第二引数のインスタンスを返します。このインスタンスは第一引数と同じメモリブロックを参照しています:

>>> a = (c_byte * 4)()
>>> cast(a, POINTER(c_int))
<ctypes.LP_c_long object at ...>
>>>

したがって、 cast() を Bar 構造体の values フィールドへ代入するために使うことができます:

>>> bar = Bar()
>>> bar.values = cast((c_byte * 4)(), POINTER(c_int))
>>> print(bar.values[0])
0
>>>

不完全型

不完全型 はメンバーがまだ指定されていない構造体、共用体もしくは配列です。 C では、前方宣言により指定され、後で定義されます。:

struct cell; /* forward declaration */

struct cell {
    char *name;
    struct cell *next;
};

ctypes コードへの直接的な変換ではこうなるでしょう。しかし、動作しません:

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

because the new class cell is not available in the class statement itself. In ctypes, we can define the cell class and set the _fields_ attribute later, after the class statement:

>>> from ctypes import *
>>> class cell(Structure):
...     pass
...
>>> cell._fields_ = [("name", c_char_p),
...                  ("next", POINTER(cell))]
>>>

試してみましょう。 cell のインスタンスを二つ作り、互いに参照し合うようにします。最後に、つながったポインタを何度かたどります。:

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

コールバック関数

ctypes は C の呼び出し可能な関数ポインタを Python 呼び出し可能オブジェクトから作成できるようにします。これらは コールバック関数 と呼ばれることがあります。

最初に、コールバック関数のためのクラスを作る必要があります。そのクラスには呼び出し規約、戻り値の型およびこの関数が受け取る引数の数と型についての情報があります。

CFUNCTYPE() ファクトリ関数は通常の cdecl 呼び出し規約を用いてコールバック関数のための型を作成します。 Windows では、 WINFUNCTYPE() ファクトリ関数が stdcall 呼び出し規約を用いてコールバック関数の型を作成します。

これらのファクトリ関数はともに最初の引数に戻り値の型、残りの引数としてコールバック関数が想定する引数の型を渡して呼び出されます。

I will present an example here which uses the standard C library's qsort() function, that is used to sort items with the help of a callback function. qsort() will be used to sort an array of integers:

>>> IntArray5 = c_int * 5
>>> ia = IntArray5(5, 1, 7, 33, 99)
>>> qsort = libc.qsort
>>> qsort.restype = None
>>>

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.

コールバック関数は整数へのポインタを受け取り、整数を返す必要があります。まず、コールバック関数のための type を作成します。:

>>> CMPFUNC = CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int))
>>>

まず初めに、これが受け取った変数を表示するだけのシンプルなコールバックです:

>>> def py_cmp_func(a, b):
...     print("py_cmp_func", a[0], b[0])
...     return 0
...
>>> cmp_func = CMPFUNC(py_cmp_func)
>>>

結果は以下の通りです:

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

ここで 2 つの要素を実際に比較し、役に立つ結果を返します:

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

簡単に確認できるように、配列を次のようにソートしました:

>>> for i in ia: print(i, end=" ")
...
1 5 7 33 99
>>>

関数ファクトリはデコレータファクトリとしても使えるので、次のようにも書けます:

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

注釈

C コードから CFUNCTYPE() オブジェクトが使用される限り、そのオブジェクトへの参照を確実に保持してください。 ctypes は参照を保持しないため、あなたが参照を保持しないと、オブジェクトはガベージコレクションの対象となり、コールバックが行われたときにプログラムをクラッシュさせる場合があります。

同様に、コールバック関数が Python の管理外 (例えば、コールバックを呼び出す外部のコード) で作られたスレッドで呼び出された場合、 ctypes は全ての呼び出しごとに新しいダミーの Python スレッドを作成することに注意してください。 この動作はほとんどの目的に対して正しいものですが、同じ C スレッドからの呼び出しだったとしても、 threading.local で格納された値は異なるコールバックをまたいで生存は しません 。

dllからエクスポートされた値へアクセスする

Some shared libraries not only export functions, they also export variables. An example in the Python library itself is the Py_Version, Python runtime version number encoded in a single constant integer.

ctypes can access values like this with the in_dll() class methods of the type. pythonapi is a predefined symbol giving access to the Python C api:

>>> version = ctypes.c_int.in_dll(ctypes.pythonapi, "Py_Version")
>>> print(hex(version.value))
0x30c00a0

ポインタの使い方を説明する拡張例では、 Python がエクスポートする PyImport_FrozenModules ポインタにアクセスします。

この値のドキュメントから引用すると:

このポインタは _frozen のレコードからなり、終端の要素のメンバが NULL かゼロになっているような配列を指すよう初期化されます。フリーズされたモジュールをインポートするとき、このテーブルを検索します。サードパーティ製のコードからこのポインタに仕掛けを講じて、動的に生成されたフリーズ化モジュールの集合を提供するようにできます。

これで、このポインタを操作することが役に立つことを証明できるでしょう。例の大きさを制限するために、このテーブルを ctypes を使って読む方法だけを示します。:

>>> from ctypes import *
>>>
>>> class struct_frozen(Structure):
...     _fields_ = [("name", c_char_p),
...                 ("code", POINTER(c_ubyte)),
...                 ("size", c_int),
...                 ("get_code", POINTER(c_ubyte)),  # Function pointer
...                ]
...
>>>

私たちは _frozen データ型を定義済みなので、このテーブルを指すポインタを得ることができます。:

>>> FrozenTable = POINTER(struct_frozen)
>>> table = FrozenTable.in_dll(pythonapi, "_PyImport_FrozenBootstrap")
>>>

table が struct_frozen レコードの配列への pointer なので、その配列に対して反復処理を行えます。しかし、ループが確実に終了するようにする必要があります。なぜなら、ポインタに大きさの情報がないからです。遅かれ早かれ、アクセス違反か何かでクラッシュすることになるでしょう。 NULL エントリに達したときはループを抜ける方が良いです:

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

標準 Python はフローズンモジュールとフローズンパッケージ (負の size メンバーで表されています) を持っているという事実はあまり知られておらず、テストにだけ使われています。例えば、 import __hello__ を試してみてください。

びっくり仰天

There are some edges in ctypes where you might expect something other than what actually happens.

次に示す例について考えてみてください。:

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

うーん、最後の文に 3 4 1 2 と表示されることを期待していたはずです。何が起きたのでしょうか? 上の行の rc.a, rc.b = rc.b, rc.a の各段階はこのようになります。:

>>> temp0, temp1 = rc.b, rc.a
>>> rc.a = temp0
>>> rc.b = temp1
>>>

temp0 と temp1 は前記の rc オブジェクトの内部バッファでまだ使われているオブジェクトです。したがって、 rc.a = temp0 を実行すると temp0 のバッファ内容が rc のバッファへコピーされます。さらに、これは temp1 の内容を変更します。そのため、最後の代入 rc.b = temp1 は、期待する結果にはならないのです。

Structure 、 Union および Array のサブオブジェクトを取り出しても、そのサブオブジェクトが コピー されるわけではなく、ルートオブジェクトの内部バッファにアクセスするラッパーオブジェクトを取り出すことを覚えておいてください。

期待とは違う振る舞いをする別の例はこれです:

>>> s = c_char_p()
>>> s.value = b"abc def ghi"
>>> s.value
b'abc def ghi'
>>> s.value is s.value
False
>>>

注釈

c_char_p からインスタンス化されたオブジェクトは、bytes または整数に設定された値しか持てません。

なぜ False と表示されるのでしょうか? ctypes インスタンスはメモリと、メモリの内容にアクセスするいくつかの descriptor (記述子)を含むオブジェクトです。メモリブロックに Python オブジェクトを保存してもオブジェクト自身が保存される訳ではなく、オブジェクトの contents が保存されます。その contents に再アクセスすると新しい Python オブジェクトがその度に作られます。

可変サイズのデータ型

ctypes は可変サイズの配列と構造体をサポートしています。

resize() 関数は既存の ctypes オブジェクトのメモリバッファのサイズを変更したい場合に使えます。この関数は第一引数にオブジェクト、第二引数に要求されたサイズをバイト単位で指定します。メモリブロックはオブジェクト型で指定される通常のメモリブロックより小さくすることはできません。これをやろうとすると、 ValueError が送出されます。:

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

これはこれで上手くいっていますが、この配列の追加した要素へどうやってアクセスするのでしょうか? この型は要素の数が 4 個であるとまだ認識しているので、他の要素にアクセスするとエラーになります。:

>>> short_array[:]
[0, 0, 0, 0]
>>> short_array[7]
Traceback (most recent call last):
    ...
IndexError: invalid index
>>>

ctypes で可変サイズのデータ型を使うもう一つの方法は、必要なサイズが分かった後に Python の動的性質を使って一つ一つデータ型を(再)定義することです。

ctypesリファレンス

共有ライブラリを見つける

コンパイルされる言語でプログラミングしている場合、共有ライブラリはプログラムをコンパイル/リンクしているときと、そのプログラムが動作しているときにアクセスされます。

The purpose of the 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 ctypes.util module provides a function which can help to determine the library to load.

ctypes.util.find_library(name)

ライブラリを見つけてパス名を返そうと試みます。 name は lib のような接頭辞、 .so, .dylib のような接尾辞、あるいは、バージョン番号が何も付いていないライブラリの名前です (これは posix リンカのオプション -l に使われている形式です)。ライブラリが見つからないときは None を返します。

厳密な機能はシステムに依存します。

On Linux, find_library() tries to run external programs (/sbin/ldconfig, gcc, objdump and ld) to find the library file. It returns the filename of the library file.

バージョン 3.6 で変更: Linux では、ライブラリを検索する際に、他の方法でライブラリが見つけられない場合は、 LD_LIBRARY_PATH 環境変数の値が使われます

ここに例があります:

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

On macOS, find_library() tries several predefined naming schemes and paths to locate the library, and returns a full pathname if successful:

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

On Windows, find_library() searches along the system search path, and returns the full pathname, but since there is no predefined naming scheme a call like find_library("c") will fail and return None.

If wrapping a shared library with ctypes, it may be better to determine the shared library name at development time, and hardcode that into the wrapper module instead of using find_library() to locate the library at runtime.

共有ライブラリをロードする

共有ライブラリを Python プロセスへロードする方法はいくつかあります。一つの方法は下記のクラスの一つをインスタンス化することです:

class ctypes.CDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=None)

このクラスのインスタンスはロードされた共有ライブラリをあらわします。これらのライブラリの関数は標準 C 呼び出し規約を使用し、 int を返すと仮定されます。

On Windows creating a CDLL instance may fail even if the DLL name exists. When a dependent DLL of the loaded DLL is not found, a 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 path-like object.

参考

Microsoft DUMPBIN tool [https://docs.microsoft.com/cpp/build/reference/dependents] -- A tool to find DLL dependents.

class ctypes.OleDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=None)

Windows 用: このクラスのインスタンスはロードされた共有ライブラリをあらわします。これらのライブラリの関数は stdcall 呼び出し規約を使用し、 windows 固有の HRESULT コードを返すと仮定されます。 HRESULT 値には関数呼び出しが失敗したのか成功したのかを特定する情報とともに、補足のエラーコードが含まれます。戻り値が失敗を知らせたならば、 OSError が自動的に送出されます。

バージョン 3.3 で変更: WindowsError used to be raised, which is now an alias of OSError.

バージョン 3.12 で変更: The name parameter can now be a path-like object.

class ctypes.WinDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=None)

Windows 用: このクラスのインスタンスはロードされた共有ライブラリをあらわします。これらのライブラリの関数は stdcall 呼び出し規約を使用し、デフォルトでは int を返すと仮定されます。

バージョン 3.12 で変更: The name parameter can now be a path-like object.

これらのライブラリがエクスポートするどの関数でも呼び出す前に Python global interpreter lock は解放され、後でまた獲得されます。

class ctypes.PyDLL(name, mode=DEFAULT_MODE, handle=None)

Python GIL が関数呼び出しの間解放 されず 、関数実行の後に Python エラーフラグがチェックされるということを除けば、このクラスのインスタンスは CDLL インスタンスのように振る舞います。エラーフラグがセットされた場合、 Python 例外が送出されます。

要するに、これは Python C api 関数を直接呼び出すのに便利だというだけです。

バージョン 3.12 で変更: The name parameter can now be a path-like object.

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 handle named parameter, otherwise the underlying platforms dlopen() or LoadLibrary() function is used to load the library into the process, and to get a handle to it.

mode パラメータを使うと、ライブラリがどうやってロードされたかを特定できます。詳細は dlopen(3) [https://manpages.debian.org/dlopen(3)] マニュアルページを参考にしてください。 Windows では mode は無視されます。 POSIX システムでは RTLD_NOW が常に追加され、設定変更はできません。

The use_errno parameter, when set to true, enables a ctypes mechanism that allows accessing the system errno error number in a safe way. ctypes maintains a thread-local copy of the systems errno variable; if you call foreign functions created with use_errno=True then the errno value before the function call is swapped with the ctypes private copy, the same happens immediately after the function call.

ctypes.get_errno() 関数は ctypes のプライベートコピーの値を返します。そして、 ctypes.set_errno() 関数は ctypes のプライベートコピーを置き換え、以前の値を返します。

The use_last_error parameter, when set to true, enables the same mechanism for the Windows error code which is managed by the GetLastError() and SetLastError() Windows API functions; ctypes.get_last_error() and 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 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 引数が追加されました。

ctypes.RTLD_GLOBAL

mode パラメータとして使うフラグ。このフラグが利用できないプラットフォームでは、整数のゼロと定義されています。

ctypes.RTLD_LOCAL

mode パラメータとして使うフラグ。これが利用できないプラットフォームでは、 RTLD_GLOBAL と同様です。

ctypes.DEFAULT_MODE

共有ライブラリをロードするために使われるデフォルトモード。 OSX 10.3 では RTLD_GLOBAL であり、そうでなければ RTLD_LOCAL と同じです。

これらのクラスのインスタンスには公開メソッドはありません。共有ライブラリからエクスポートされた関数は、属性として、もしくは添字でアクセスできます。属性を通した関数へのアクセスは結果がキャッシュされ、従って繰り返しアクセスされると毎回同じオブジェクトを返すことに注意してください。それとは反対に、添字を通したアクセスは毎回新しいオブジェクトを返します:

>>> from ctypes import CDLL
>>> libc = CDLL("libc.so.6")  # On Linux
>>> libc.time == libc.time
True
>>> libc['time'] == libc['time']
False

次に述べる公開属性が利用できます。それらの名前はエクスポートされた関数名に衝突しないように下線で始まります。:

PyDLL._handle

ライブラリへのアクセスに用いられるシステムハンドル。

PyDLL._name

コンストラクタに渡されたライブラリの名前。

Shared libraries can also be loaded by using one of the prefabricated objects, which are instances of the LibraryLoader class, either by calling the LoadLibrary() method, or by retrieving the library as attribute of the loader instance.

class ctypes.LibraryLoader(dlltype)

共有ライブラリをロードするクラス。 dlltype は CDLL 、 PyDLL 、 WinDLL もしくは OleDLL 型の一つであるべきです。

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

LoadLibrary(name)

共有ライブラリをプロセスへロードし、それを返します。このメソッドはライブラリの新しいインスタンスを常に返します。

これらの前もって作られたライブラリローダーを利用することができます。:

ctypes.cdll

CDLL インスタンスを作ります。

ctypes.windll

Windows 用: WinDLL インスタンスを作ります。

ctypes.oledll

Windows 用: OleDLL インスタンスを作ります。

ctypes.pydll

PyDLL インスタンスを作ります。

C Python api に直接アクセスするために、すぐに使用できる Python 共有ライブラリオブジェクトが次のように用意されています。

ctypes.pythonapi

An instance of 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 restype attribute to use these functions.

引数 name を指定して 監査イベント ctypes.dlopen を送出します。

引数 library, name を指定して 監査イベント ctypes.dlsym を送出します。

引数 handle, name を指定して 監査イベント ctypes.dlsym/handle を送出します。

外部関数

前節で説明した通り、外部関数はロードされた共有ライブラリの属性としてアクセスできます。デフォルトではこの方法で作成された関数オブジェクトはどんな数の引数でも受け取り、引数としてどんな ctypes データのインスタンスをも受け取り、そして、ライブラリローダーが指定したデフォルトの結果の値の型を返します。関数オブジェクトはプライベートクラスのインスタンスです。:

class ctypes._FuncPtr

C の呼び出し可能外部関数のためのベースクラス。

外部関数のインスタンスも C 互換データ型です。それらは C の関数ポインタを表しています。

この振る舞いは外部関数オブジェクトの特別な属性に代入することによって、カスタマイズすることができます。

restype

外部関数の結果の型を指定するために ctypes 型を代入する。何も返さない関数を表す void に対しては None を使います。

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 restype and assign a callable to the errcheck attribute.

argtypes

関数が受け取る引数の型を指定するために ctypes 型のタプルを代入します。stdcall 呼び出し規約を使う関数はこのタプルの長さと同じ数の引数で呼び出されます。C 呼び出し規約を使う関数は、追加の不特定の引数も取ります。

When a foreign function is called, each actual argument is passed to the from_param() class method of the items in the argtypes tuple, this method allows adapting the actual argument to an object that the foreign function accepts. For example, a c_char_p item in the 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 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.

errcheck

Python 関数または他の呼び出し可能オブジェクトをこの属性に代入します。呼び出し可能オブジェクトは三つ以上の引数とともに呼び出されます。

callable(result, func, arguments)

result is what the foreign function returns, as specified by the restype attribute.

func は外部関数オブジェクト自身で、これにより複数の関数の処理結果をチェックまたは後処理するために、同じ呼び出し可能オブジェクトを再利用できるようになります。

arguments は関数呼び出しに最初に渡されたパラメータが入ったタプルです。これにより使われた引数に基づいた特別な振る舞いをさせることができるようになります。

この関数が返すオブジェクトは外部関数呼び出しから返された値でしょう。しかし、戻り値をチェックして、外部関数呼び出しが失敗しているなら例外を送出させることもできます。

exception ctypes.ArgumentError

この例外は外部関数呼び出しが渡された引数を変換できなかったときに送出されます。

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 ctypes.set_exception with argument code will be raised, allowing an audit hook to replace the exception with its own.

引数 func_pointer, arguments を指定して 監査イベント ctypes.call_function を送出します。

関数プロトタイプ

外部関数は関数プロトタイプをインスタンス化することによって作成されます。関数プロトタイプは C の関数プロトタイプと似ています。実装は定義せずに、関数 (返り値の型、引数の型、呼び出し規約) を記述します。ファクトリ関数は、その関数に要求される返り値の型と引数の型とともに呼び出されます。そしてこの関数はデコレータファクトリとしても使え、 @wrapper 構文で他の関数に適用できます。例については コールバック関数 を参照してください。

ctypes.CFUNCTYPE(restype, *argtypes, use_errno=False, use_last_error=False)

返された関数プロトタイプは標準 C 呼び出し規約をつかう関数を作成します。関数は呼び出されている間 GIL を解放します。 use_errno が真に設定されれば、呼び出しの前後で System 変数 errno の ctypesプライベートコピーは本当の errno の値と交換されます。 use_last_error も Windows エラーコードに対するのと同様です。

ctypes.WINFUNCTYPE(restype, *argtypes, use_errno=False, use_last_error=False)

Windows のみ: 返された関数プロトタイプは stdcall 呼び出し規約を使う関数を作成します。関数は呼び出されている間 GIL を解放します。 use_errno と use_last_error は前述と同じ意味を持ちます。

ctypes.PYFUNCTYPE(restype, *argtypes)

返された関数プロトタイプは Python 呼び出し規約を使う関数を作成します。関数は呼び出されている間 GIL を解放 しません。

ファクトリ関数によって作られた関数プロトタイプは呼び出しのパラメータの型と数に依存した別の方法でインスタンス化することができます。 :

prototype(address)

指定されたアドレス(整数でなくてはなりません)の外部関数を返します。

prototype(callable)

Python の callable から C の呼び出し可能関数(コールバック関数) を作成します。

prototype(func_spec[, paramflags])

共有ライブラリがエクスポートしている外部関数を返します。 func_spec は 2 要素タプル (name_or_ordinal, library) でなければなりません。第一要素はエクスポートされた関数の名前である文字列、またはエクスポートされた関数の序数である小さい整数です。第二要素は共有ライブラリインスタンスです。

prototype(vtbl_index, name[, paramflags[, iid]])

COM メソッドを呼び出す外部関数を返します。 vtbl_index は仮想関数テーブルのインデックスで、非負の小さい整数です。 name は COM メソッドの名前です。 iid はオプションのインターフェイス識別子へのポインタで、拡張されたエラー情報の提供のために使われます。

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

オプションの paramflags パラメータは上述した機能より多機能な外部関数ラッパーを作成します。

paramflags must be a tuple of the same length as argtypes.

このタプルの個々の要素はパラメータについてのより詳細な情報を持ち、 1 、 2 もしくは 3 要素を含むタプルでなければなりません。

第一要素はパラメータについてのフラグの組み合わせを含んだ整数です。

1

入力パラメータを関数に指定します。

2

出力パラメータ。外部関数が値を書き込みます。

4

デフォルトで整数ゼロになる入力パラメータ。

オプションの第二要素はパラメータ名の文字列です。これが指定された場合は、外部関数を名前付きパラメータで呼び出すことができます。

オプションの第三要素はこのパラメータのデフォルト値です。

The following example demonstrates how to wrap the Windows MessageBoxW function so that it supports default parameters and named arguments. The C declaration from the windows header file is this:

WINUSERAPI int WINAPI
MessageBoxW(
    HWND hWnd,
    LPCWSTR lpText,
    LPCWSTR lpCaption,
    UINT uType);

ctypes を使ってラップします。:

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

これで外部関数の MessageBox を次のような方法で呼び出すことができるようになりました:

>>> MessageBox()
>>> MessageBox(text="Spam, spam, spam")
>>> MessageBox(flags=2, text="foo bar")

二番目の例は出力パラメータについて説明します。 win32 の GetWindowRect 関数は、指定されたウィンドウの大きさを呼び出し側が与える RECT 構造体へコピーすることで取り出します。 C の宣言はこうです。:

WINUSERAPI BOOL WINAPI
GetWindowRect(
     HWND hWnd,
     LPRECT lpRect);

ctypes を使ってラップします。:

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

出力パラメータを持つ関数は、単一のパラメータがある場合にはその出力パラメータ値を、複数のパラメータがある場合には出力パラメータ値が入ったタプルを、それぞれ自動的に返します。そのため、GetWindowRect 関数は呼び出されると RECT インスタンスを返します。

Output parameters can be combined with the errcheck protocol to do further output processing and error checking. The win32 GetWindowRect api function returns a BOOL to signal success or failure, so this function could do the error checking, and raises an exception when the api call failed:

>>> def errcheck(result, func, args):
...     if not result:
...         raise WinError()
...     return args
...
>>> GetWindowRect.errcheck = errcheck
>>>

If the errcheck function returns the argument tuple it receives unchanged, ctypes continues the normal processing it does on the output parameters. If you want to return a tuple of window coordinates instead of a RECT instance, you can retrieve the fields in the function and return them instead, the normal processing will no longer take place:

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

ユーティリティー関数

ctypes.addressof(obj)

メモリバッファのアドレスを示す整数を返します。 obj は ctypes 型のインスタンスでなければなりません。

引数 obj を指定して 監査イベント ctypes.addressof を送出します。

ctypes.alignment(obj_or_type)

ctypes 型のアライメントの必要条件を返します。 obj_or_type は ctypes 型またはインスタンスでなければなりません。

ctypes.byref(obj[, offset])

obj (ctypes 型のインスタンスでなければならない) への軽量ポインタを返します。 offset はデフォルトでは 0 で、内部ポインターへ加算される整数です。

byref(obj, offset) は、 C コードとしては、以下のようにみなされます。:

(((char *)&obj) + offset)

返されるオブジェクトは外部関数呼び出しのパラメータとしてのみ使用できます。pointer(obj) と似たふるまいをしますが、作成が非常に速く行えます。

ctypes.cast(obj, type)

この関数は C のキャスト演算子に似ています。obj と同じメモリブロックを指している type の新しいインスタンスを返します。type はポインタ型でなければならず、obj はポインタとして解釈できるオブジェクトでなければなりません。

ctypes.create_string_buffer(init_or_size, size=None)

この関数は変更可能な文字バッファを作成します。返されるオブジェクトは c_char の ctypes 配列です。

init_or_size は配列のサイズを指定する整数もしくは配列要素を初期化するために使われるバイト列オブジェクトである必要があります。

バイト列オブジェクトが第一引数として指定されていた場合、配列の最後の要素が NUL 終端文字となるように、バイト列オブジェクトの長さより 1 つ長いバッファを作成します。バイト列の長さを使うべきではない場合は、第二引数として整数を渡して、配列の長さを指定することができます。

引数 init, size を指定して 監査イベント ctypes.create_string_buffer を送出します。

ctypes.create_unicode_buffer(init_or_size, size=None)

この関数は変更可能な Unicode 文字バッファを作成します。返されるオブジェクトは c_wchar の ctypes 配列です。

init_or_size は配列のサイズを指定する整数もしくは配列要素を初期化するために使われる文字列である必要があります。

第一引数として文字列が指定された場合は、バッファが文字列の長さより一要素分大きく作られます。配列の最後の要素が NUL 終端文字であるためです。文字列の長さを使うべきでない場合は、配列のサイズを指定するために整数を第二引数として渡すことができます。

引数 init, size を指定して 監査イベント ctypes.create_unicode_buffer を送出します。

ctypes.DllCanUnloadNow()

Windows 用: この関数は ctypes をつかってインプロセス COM サーバーを実装できるようにするためのフックです。_ctypes 拡張 dll がエクスポートしている DllCanUnloadNow 関数から呼び出されます。

ctypes.DllGetClassObject()

Windows 用: この関数は ctypes をつかってインプロセス COM サーバーを実装できるようにするためのフックです。_ctypes 拡張 dll がエクスポートしている DllGetClassObject 関数から呼び出されます。

ctypes.util.find_library(name)

ライブラリを検索し、パス名を返します。 name は lib のような接頭辞、 .so や .dylib のような接尾辞、そして、バージョンナンバーを除くライブラリ名です (これは posix のリンカーオプション -l で使われる書式です) 。もしライブラリが見つからなければ、 None を返します。

厳密な機能はシステムに依存します。

ctypes.util.find_msvcrt()

Windows 用: Python と拡張モジュールで使われる VC ランタイムライブラリのファイル名を返します。もしライブラリ名が同定できなければ、 None を返します。

もし、例えば拡張モジュールにより割り付けられたメモリを free(void *) で解放する必要があるなら、メモリ割り付けを行ったのと同じライブラリの関数を使うことが重要です。

ctypes.FormatError([code])

Windows 用: エラーコード code の説明文を返します。エラーコードが指定されない場合は、 Windows api 関数 GetLastError を呼び出して、もっとも新しいエラーコードが使われます。

ctypes.GetLastError()

Windows 用: 呼び出し側のスレッド内で Windows によって設定された最新のエラーコードを返します。この関数は Windows の GetLastError() 関数を直接実行します。 ctypes のプライベートなエラーコードのコピーを返したりはしません。

ctypes.get_errno()

システムの errno 変数の、スレッドローカルなプライベートコピーを返します。

引数無しで 監査イベント ctypes.get_errno を送出します。

ctypes.get_last_error()

Windows only: returns the current value of the ctypes-private copy of the system LastError variable in the calling thread.

引数無しで 監査イベント ctypes.get_last_error を送出します。

ctypes.memmove(dst, src, count)

標準 C の memmove ライブラリ関数と同じものです。: count バイトを src から dst へコピーします。 dst と src はポインタへ変換可能な整数または ctypes インスタンスでなければなりません。

ctypes.memset(dst, c, count)

標準 C の memset ライブラリ関数と同じものです。: アドレス dst のメモリブロックを値 c を count バイト分書き込みます。 dst はアドレスを指定する整数または ctypes インスタンスである必要があります。

ctypes.POINTER(type, /)

Create and return a new ctypes pointer type. Pointer types are cached and reused internally, so calling this function repeatedly is cheap. type must be a ctypes type.

ctypes.pointer(obj, /)

Create a new pointer instance, pointing to obj. The returned object is of the type POINTER(type(obj)).

注意: 外部関数呼び出しへオブジェクトへのポインタを渡したいだけなら、はるかに高速な byref(obj) を使うべきです。

ctypes.resize(obj, size)

この関数は obj の内部メモリバッファのサイズを変更します。 obj は ctypes 型のインスタンスでなければなりません。バッファを sizeof(type(obj)) で与えられるオブジェクト型の本来のサイズより小さくすることはできませんが、バッファを拡大することはできます。

ctypes.set_errno(value)

システム変数 errno の、呼び出し元スレッドでの ctypes のプライベートコピーの現在値を value に設定し、前の値を返します。

引数 errno を指定して 監査イベント ctypes.set_errno を送出します。

ctypes.set_last_error(value)

Windows only: set the current value of the ctypes-private copy of the system LastError variable in the calling thread to value and return the previous value.

引数 error を指定して 監査イベント ctypes.set_last_error を送出します。

ctypes.sizeof(obj_or_type)

ctypes の型やインスタンスのメモリバッファのサイズをバイト数で返します。C の sizeof 演算子と同様の動きをします。

ctypes.string_at(ptr, size=-1)

Return the byte string at void *ptr. If size is specified, it is used as size, otherwise the string is assumed to be zero-terminated.

Raises an auditing event ctypes.string_at with arguments ptr, size.

ctypes.WinError(code=None, descr=None)

Windows only: this function is probably the worst-named thing in ctypes. It creates an instance of OSError. If code is not specified, GetLastError is called to determine the error code. If descr is not specified, FormatError() is called to get a textual description of the error.

バージョン 3.3 で変更: An instance of WindowsError used to be created, which is now an alias of OSError.

ctypes.wstring_at(ptr, size=-1)

Return the wide-character string at void *ptr. If size is specified, it is used as the number of characters of the string, otherwise the string is assumed to be zero-terminated.

Raises an auditing event ctypes.wstring_at with arguments ptr, size.

データ型

class ctypes._CData

この非公開クラスはすべての ctypes データ型の共通のベースクラスです。他のことはさておき、すべての ctypes 型インスタンスは C 互換データを保持するメモリブロックを内部に持ちます。このメモリブロックのアドレスは addressof() ヘルパー関数が返します。別のインスタンス変数が _objects として公開されます。これはメモリブロックがポインタを含む場合に存続し続ける必要のある他の Python オブジェクトを含んでいます。

ctypes データ型の共通メソッド、すべてのクラスメソッドが存在します (正確には、 メタクラス のメソッドです):

from_buffer(source[, offset])

このメソッドは source オブジェクトのバッファを共有する ctypes のインスタンスを返します。 source オブジェクトは書き込み可能バッファインターフェースをサポートしている必要があります。オプションの offset 引数では source バッファのオフセットをバイト単位で指定します。デフォルトではゼロです。もし source バッファが十分に大きくなければ、 ValueError が送出されます。

引数 pointer, size, offset を指定して 監査イベント ctypes.cdata/buffer を送出します。

from_buffer_copy(source[, offset])

このメソッドは source オブジェクトの読み出し可能バッファをコピーすることで、ctypes のインスタンスを生成します。オプションの offset 引数では source バッファのオフセットをバイト単位で指定します。デフォルトではゼロです。もし source バッファが十分に大きくなければ、 ValueError が送出されます。

引数 pointer, size, offset を指定して 監査イベント ctypes.cdata/buffer を送出します。

from_address(address)

このメソッドは address で指定されたメモリを使って ctypes 型のインスタンスを返します。 address は整数でなければなりません。

引数 address を指定して 監査イベント ctypes.cdata を送出します。

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 argtypes tuple; it must return an object that can be used as a function call parameter.

すべての ctypes のデータ型は、それが型のインスタンスであれば、 obj を返すこのクラスメソッドのデフォルトの実装を持ちます。いくつかの型は、別のオブジェクトも受け付けます。

in_dll(library, name)

このメソッドは、共有ライブラリによってエクスポートされた ctypes 型のインスタンスを返します。 name はエクスポートされたデータの名前で、 library はロードされた共有ライブラリです。

ctypes データ型共通のインスタンス変数:

_b_base_

ctypes 型データのインスタンスは、それ自身のメモリブロックを持たず、基底オブジェクトのメモリブロックの一部を共有することがあります。 _b_base_ 読み出し専用属性は、メモリブロックを保持する ctypes の基底オブジェクトです。

_b_needsfree_

この読み出し専用の変数は、 ctypes データインスタンスが、それ自身に割り当てられたメモリブロックを持つとき true になります。それ以外の場合は false になります。

_objects

このメンバは None 、または、メモリブロックの内容が正しく保つために、生存させておかなくてはならない Python オブジェクトを持つディクショナリです。このオブジェクトはデバッグでのみ使われます。決してディクショナリの内容を変更しないで下さい。

基本データ型

class ctypes._SimpleCData

この非公開クラスは、全ての基本的な ctypes データ型の基底クラスです。これは基本的な ctypes データ型に共通の属性を持っているので、ここで触れておきます。 _SimpleCData は _CData の子クラスなので、そのメソッドと属性を継承しています。ポインタでないかポインタを含まない ctypes データ型は、現在は pickle 化できます。

インスタンスは一つだけ属性を持ちます:

value

この属性は、インスタンスの実際の値を持ちます。整数型とポインタ型に対しては整数型、文字型に対しては一文字のバイト列オブジェクト、文字へのポインタに対しては Python のバイト列オブジェクトもしくは文字列となります。

value 属性が ctypes インスタンスより参照されたとき、大抵の場合はそれぞれに対し新しいオブジェクトを返します。 ctypes はオリジナルのオブジェクトを返す実装にはなって おらず 新しいオブジェクトを構築します。同じことが他の ctypes オブジェクトインスタンスに対しても言えます。

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 restype of c_char_p, you will always receive a Python bytes object, not a c_char_p instance.

Subclasses of fundamental data types do not inherit this behavior. So, if a foreign functions restype is a subclass of 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 value attribute.

これらが基本 ctypes データ型です:

class ctypes.c_byte

C の signed char データ型を表し、小整数として値を解釈します。コンストラクタはオプションの整数初期化子を受け取ります。オーバーフローのチェックは行われません。

class ctypes.c_char

C char データ型を表し、単一の文字として値を解釈します。コンストラクタはオプションの文字列初期化子を受け取り、その文字列の長さちょうど一文字である必要があります。

class ctypes.c_char_p

C char* データ型を表し、ゼロ終端文字列へのポインタでなければなりません。バイナリデータを指す可能性のある一般的なポインタに対しては POINTER(c_char) を使わなければなりません。コンストラクタは整数のアドレスもしくはバイト列オブジェクトを受け取ります。

class ctypes.c_double

C double データ型を表します。コンストラクタはオプションの浮動小数点数初期化子を受け取ります。

class ctypes.c_longdouble

C long double データ型を表します。コンストラクタはオプションで浮動小数点数初期化子を受け取ります。 sizeof(long double) == sizeof(double) であるプラットフォームでは c_double の別名です。

class ctypes.c_float

C float データ型を表します。コンストラクタはオプションの浮動小数点数初期化子を受け取ります。

class ctypes.c_int

C signed int データ型を表します。コンストラクタはオプションの整数初期化子を受け取ります。オーバーフローのチェックは行われません。 sizeof(int) == sizeof(long) であるプラットフォームでは、 c_long の別名です。

class ctypes.c_int8

C 8-bit signed int データ型を表します。たいていは、 c_byte の別名です。

class ctypes.c_int16

C 16-bit signed int データ型を表します。たいていは、 c_short の別名です。

class ctypes.c_int32

C 32-bit signed int データ型を表します。たいていは、 c_int の別名です。

class ctypes.c_int64

C 64-bit signed int データ型を表します。たいていは、 c_longlong の別名です。

class ctypes.c_long

C signed long データ型を表します。コンストラクタはオプションの整数初期化子を受け取ります。オーバーフローのチェックは行われません。

class ctypes.c_longlong

C signed long long データ型を表します。コンストラクタはオプションの整数初期化子を受け取ります。オーバーフローのチェックは行われません。

class ctypes.c_short

C signed short データ型を表します。コンストラクタはオプションの整数初期化子を受け取ります。オーバーフローのチェックは行われません。

class ctypes.c_size_t

C size_t データ型を表します。

class ctypes.c_ssize_t

C ssize_t データ型を表します。

Added in version 3.2.

class ctypes.c_time_t

Represents the C time_t datatype.

Added in version 3.12.

class ctypes.c_ubyte

C の unsigned char データ型を表し、小さな整数として値を解釈します。コンストラクタはオプションの整数初期化子を受け取ります; オーバーフローのチェックは行われません。

class ctypes.c_uint

C の unsigned int データ型を表します。コンストラクタはオプションの整数初期化子を受け取ります; オーバーフローのチェックは行われません。これは、 sizeof(int) == sizeof(long) であるプラットフォームでは c_ulong の別名です。

class ctypes.c_uint8

C 8-bit unsigned int データ型を表します。たいていは、 c_ubyte の別名です。

class ctypes.c_uint16

C 16-bit unsigned int データ型を表します。たいていは、 c_ushort の別名です。

class ctypes.c_uint32

C 32-bit unsigned int データ型を表します。たいていは、 c_uint の別名です。

class ctypes.c_uint64

C 64-bit unsigned int データ型を表します。たいていは、 c_ulonglong の別名です。

class ctypes.c_ulong

C unsigned long データ型を表します。コンストラクタはオプションの整数初期化子を受け取ります。オーバーフローのチェックは行われません。

class ctypes.c_ulonglong

C unsigned long long データ型を表します。コンストラクタはオプションの整数初期化子を受け取ります。オーバーフローのチェックは行われません。

class ctypes.c_ushort

C unsigned short データ型を表します。コンストラクタはオプションの整数初期化子を受け取ります。オーバーフローのチェックは行われません。

class ctypes.c_void_p

C void* データ型を表します。値は整数として表されます。コンストラクタはオプションの整数初期化子を受け取ります。

class ctypes.c_wchar

C wchar_t データ型を表し、値は Unicode 文字列の単一の文字として解釈されます。コンストラクタはオプションの文字列初期化子を受け取り、その文字列の長さはちょうど一文字である必要があります。

class ctypes.c_wchar_p

C wchar_t* データ型を表し、ゼロ終端ワイド文字列へのポインタでなければなりません。コンストラクタは整数のアドレスもしくは文字列を受け取ります。

class ctypes.c_bool

C の bool データ型 (より正確には、 C99 以降の _Bool) を表します。 True または False の値を持ち、コンストラクタは真偽値と解釈できるオブジェクトを受け取ります。

class ctypes.HRESULT

Windows only: Represents a HRESULT value, which contains success or error information for a function or method call.

class ctypes.py_object

C PyObject* データ型を表します。引数なしでこれを呼び出すと NULL PyObject* ポインタを作成します。

The ctypes.wintypes module provides quite some other Windows specific data types, for example HWND, WPARAM, or DWORD. Some useful structures like MSG or RECT are also defined.

構造化データ型

class ctypes.Union(*args, **kw)

ネイティブのバイトオーダーでの共用体のための抽象ベースクラス。

class ctypes.BigEndianUnion(*args, **kw)

ビックエンディアン バイトオーダーでの共用体のための抽象ベースクラス。

Added in version 3.11.

class ctypes.LittleEndianUnion(*args, **kw)

リトルエンディアン バイトオーダーでの共用体のための抽象ベースクラス。

Added in version 3.11.

class ctypes.BigEndianStructure(*args, **kw)

ビックエンディアン バイトオーダーでの構造体のための抽象ベースクラス。

class ctypes.LittleEndianStructure(*args, **kw)

リトルエンディアン バイトオーダーでの構造体のための抽象ベースクラス。

ネイティブではないバイトオーダーを持つ構造体および共用体にポインタ型フィールドあるいはポインタ型フィールドを含む他のどんなデータ型をも入れることはできません。

class ctypes.Structure(*args, **kw)

ネイティブ のバイトオーダーでの構造体のための抽象ベースクラス。

具象構造体型と具象共用体型はこれらの型の一つをサブクラス化することで作らなければなりません。少なくとも、 _fields_ クラス変数を定義する必要があります。 ctypes は、属性に直接アクセスしてフィールドを読み書きできるようにする デスクリプタ を作成するでしょう。これらは、

_fields_

構造体のフィールドを定義するシーケンス。要素は2要素タプルか3要素タプルでなければなりません。第一要素はフィールドの名前です。第二要素はフィールドの型を指定します。それはどんな ctypes データ型でも構いません。

c_int のような整数型のために、オプションの第三要素を与えることができます。フィールドのビット幅を定義する正の小整数である必要があります。

一つの構造体と共用体の中で、フィールド名はただ一つである必要があります。これはチェックされません。名前が繰り返しでてきたときにアクセスできるのは一つのフィールドだけです。

Structure サブクラスを定義するクラス文の 後で 、 _fields_ クラス変数を定義することができます。これにより、次のように自身を直接または間接的に参照するデータ型を作成できるようになります:

class List(Structure):
    pass
List._fields_ = [("pnext", POINTER(List)),
                 ...
                ]

しかし、 _fields_ クラス変数はその型が最初に使われる (インスタンスが作成される、それに対して sizeof() が呼び出されるなど) より前に定義されていなければなりません。その後 _fields_ クラス変数へ代入すると AttributeError が送出されます。

構造体型のサブクラスのサブクラスを定義することもでき、もしあるならサブクラスのサブクラス内で定義された _fields_ に加えて、基底クラスのフィールドも継承します。

_pack_

An optional small integer that allows overriding the alignment of structure fields in the instance. _pack_ must already be defined when _fields_ is assigned, otherwise it will have no effect. Setting this attribute to 0 is the same as not setting it at all.

_anonymous_

無名 (匿名) フィールドの名前が並べあげられたオプションのシーケンス。 _fields_ が代入されたとき、 _anonymous_ がすでに定義されていなければなりません。そうでなければ、何ら影響はありません。

この変数に並べあげられたフィールドは構造体型もしくは共用体型フィールドである必要があります。構造体フィールドまたは共用体フィールドを作る必要なく、入れ子になったフィールドに直接アクセスできるようにするために、 ctypes は構造体型の中に記述子を作成します。

型の例です (Windows):

class _U(Union):
    _fields_ = [("lptdesc", POINTER(TYPEDESC)),
                ("lpadesc", POINTER(ARRAYDESC)),
                ("hreftype", HREFTYPE)]

class TYPEDESC(Structure):
    _anonymous_ = ("u",)
    _fields_ = [("u", _U),
                ("vt", VARTYPE)]

TYPEDESC 構造体はCOMデータ型を表現しており、 vt フィールドは共用体フィールドのどれが有効であるかを指定します。 u フィールドは匿名フィールドとして定義されているため、 TYPEDESC インスタンスから取り除かれてそのメンバーへ直接アクセスできます。 td.lptdesc と td.u.lptdesc は同等ですが、前者がより高速です。なぜなら一時的な共用体インスタンスを作る必要がないためです。:

td = TYPEDESC()
td.vt = VT_PTR
td.lptdesc = POINTER(some_type)
td.u.lptdesc = POINTER(some_type)

構造体のサブクラスのサブクラスを定義することができ、基底クラスのフィールドを継承します。サブクラス定義に別の _fields_ 変数がある場合は、この中で指定されたフィールドは基底クラスのフィールドへ追加されます。

構造体と共用体のコンストラクタは位置引数とキーワード引数の両方を受け取ります。位置引数は _fields_ の中に現れたのと同じ順番でメンバーフィールドを初期化するために使われます。コンストラクタのキーワード引数は属性代入として解釈され、そのため、同じ名前をもつ _fields_ を初期化するか、 _fields_ に存在しない名前に対しては新しい属性を作ります。

配列とポインタ

class ctypes.Array(*args)

配列のための抽象基底クラスです。

具象配列型を作成するための推奨される方法は、任意の ctypes データ型に非負の整数を乗算することです。代わりに、この型のサブクラスを作成し、 _length_ と _type_ のクラス変数を定義することもできます。配列の要素は、標準の添え字とスライスによるアクセスを使用して読み書きを行うことができます。スライスの読み込みでは、結果のオブジェクト自体は Array ではありません。

_length_

配列の要素数を指定する正の整数。範囲外の添え字を指定すると、 IndexError が送出されます。len() がこの整数を返します。

_type_

配列内の各要素の型を指定します。

配列のサブクラスのコンストラクタは、位置引数を受け付けて、配列を順番に初期化するために使用します。

class ctypes._Pointer

ポインタのためのプライベートな抽象基底クラスです。

具象ポインタ型は、ポイント先の型を持つ POINTER() を呼び出すことで、作成できます。これは、 pointer() により自動的に行われます。

ポインタが配列を指す場合、その配列の要素は、標準の添え字とスライスによるアクセスを使用して読み書きが行えます。ポインタオブジェクトには、サイズがないため、 len() 関数は TypeError を送出します。負の添え字は、(C と同様に) ポインタの 前 のメモリから読み込み、範囲外の添え字はおそらく (幸運な場合でも) アクセス違反によりクラッシュを起こします。

_type_

ポイント先の型を指定します。

contents

ポインタが指すオブジェクトを返します。この属性に割り当てると、ポインタが割り当てられたオブジェクトを指すようになります。

並行実行

この章で記述されているモジュールは、コードの並行実行のサポートを提供します。ツールの適切な選択は、実行されるタスク(IO bound vs CPU bound) や推奨される開発スタイル (イベントドリブンな協調的マルチタスク vs プリエンプティブマルチタスク) に依存します。ここに概観を示します:

threading --- Thread-based parallelism

スレッドローカルデータ

Thread オブジェクト

Lock オブジェクト

RLock オブジェクト

Condition オブジェクト

Semaphore オブジェクト

Semaphore の例

Event オブジェクト

Timer オブジェクト

バリアオブジェクト

with 文でのロック・条件変数・セマフォの使い方

multiprocessing --- Process-based parallelism

はじめに

Process クラス

コンテキストと開始方式

プロセス間でのオブジェクト交換

プロセス間の同期

プロセス間での状態の共有

ワーカープロセスのプールを使用

リファレンス

Process クラスと例外

パイプ (Pipe) とキュー (Queue)

その他

Connection オブジェクト

同期プリミティブ

共有 ctypes オブジェクト

multiprocessing.sharedctypes モジュール

マネージャー

カスタマイズされたマネージャー

リモートマネージャーを使用する

Proxy オブジェクト

クリーンアップ

プロセスプール

リスナーとクライアント

アドレスフォーマット

認証キー

ログ記録

multiprocessing.dummy モジュール

プログラミングガイドライン

すべての開始方式について

開始方式が spawn および forkserver の場合

使用例

multiprocessing.shared_memory --- Shared memory for direct access across processes

The concurrent package

concurrent.futures --- Launching parallel tasks

Executor オブジェクト

ThreadPoolExecutor

ThreadPoolExecutor の例

ProcessPoolExecutor

ProcessPoolExecutor の例

Future オブジェクト

モジュール関数

例外クラス

subprocess --- Subprocess management

subprocess モジュールを使う

よく使われる引数

Popen コンストラクター

例外

セキュリティで考慮すべき点

Popen オブジェクト

Windows Popen ヘルパー

Windows Constants

古い高水準 API

古い関数を subprocess モジュールで置き換える

Replacing /bin/sh shell command substitution

シェルのパイプラインを置き換える

os.system() を置き換える

os.spawn 関数群を置き換える

os.popen(), os.popen2(), os.popen3() を置き換える

Replacing functions from the popen2 module

レガシーなシェル呼び出し関数

注釈

Windows における引数シーケンスから文字列への変換

Disabling use of vfork() or posix_spawn()

sched --- Event scheduler

スケジューラオブジェクト

queue --- A synchronized queue class

キューオブジェクト

SimpleQueue オブジェクト

contextvars --- Context Variables

コンテキスト変数

マニュアルでのコンテキスト管理

asyncio サポート

以下のモジュールは上記のサービスの一部で使われるサポートモジュールです:

_thread --- Low-level threading API

threading --- Thread-based parallelism

ソースコード: Lib/threading.py [https://github.com/python/cpython/tree/3.12/Lib/threading.py]

このモジュールでは、高水準のスレッドインターフェースをより低水準 な _thread モジュールの上に構築しています。

バージョン 3.7 で変更: このモジュールは以前はオプションでしたが、常に利用可能なモジュールとなりました。

参考

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.

queue provides a thread-safe interface for exchanging data between running threads.

asyncio offers an alternative approach to achieving task level concurrency without requiring the use of multiple operating system threads.

注釈

In the Python 2.x series, this module contained 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.

CPython 実装の詳細: CPython は Global Interpreter Lock のため、ある時点で Python コードを実行できるスレッドは1つに限られます (ただし、いくつかのパフォーマンスが強く求められるライブラリはこの制限を克服しています)。アプリケーションにマルチコアマシンの計算能力をより良く利用させたい場合は、 multiprocessing モジュールや concurrent.futures.ProcessPoolExecutor の利用をお勧めします。 ただし、I/Oバウンドなタスクを並行して複数走らせたい場合においては、 マルチスレッドは正しい選択肢です。

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. See WebAssemblyプラットフォーム for more information.

このモジュールは以下の関数を定義しています:

threading.active_count()

生存中の Thread オブジェクトの数を返します。この数は enumerate() の返すリストの長さと同じです。

関数``activeCount``はこの関数の非推奨エイリアスです。

threading.current_thread()

関数を呼び出している処理のスレッドに対応する Thread オブジェクトを返します。関数を呼び出している処理のスレッドが threading モジュールで生成したものでない場合、限定的な機能しかもたないダミースレッドオブジェクトを返します。

関数``currentThread``はこの関数の非推奨エイリアスです。

threading.excepthook(args, /)

Thread.run() で発生したキャッチされない例外を処理する。

(実) 引数*args*は以下の属性をもちます:

exc_type: 例外の型

exc_value: 例外の値、None の可能性がある。

exc_traceback: Exception traceback, can be None.

thread: Thread which raised the exception, can be None.

If exc_type is SystemExit, the exception is silently ignored. Otherwise, the exception is printed out on sys.stderr.

If this function raises an exception, sys.excepthook() is called to handle it.

threading.excepthook() can be overridden to control how uncaught exceptions raised by 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.

参考

sys.excepthook() handles uncaught exceptions.

Added in version 3.8.

threading.__excepthook__

Holds the original value of threading.excepthook(). It is saved so that the original value can be restored in case they happen to get replaced with broken or alternative objects.

Added in version 3.10.

threading.get_ident()

現在のスレッドの 'スレッドID' を返します。非ゼロの整数です。この値は直接の意味を持っていません; 例えばスレッド特有のデータの辞書に索引をつけるためのような、マジッククッキーとして意図されています。スレッドが終了し、他のスレッドが作られたとき、スレッド ID は再利用されるかもしれません。

Added in version 3.3.

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

利用可能な環境: Windows, FreeBSD, Linux, macOS, OpenBSD, NetBSD, AIX, DragonFlyBSD。

Added in version 3.8.

threading.enumerate()

現在、アクティブな Thread オブジェクト全てのリストを返します。リストには、デーモンスレッド (daemonic thread)、 current_thread() の生成するダミースレッドオブジェクトが入ります。終了したスレッドとまだ開始していないスレッドは入りません。しかし、主スレッドは、たとえ終了しても、常に結果に含まれます。

threading.main_thread()

main Thread オブジェクトを返します。通常の条件では、メインスレッドはPythonインタプリタが起動したスレッドを指します。

Added in version 3.4.

threading.settrace(func)

threading モジュールを使って開始した全てのスレッドにトレース関数を設定します。 func は各スレッドの run() を呼び出す前にスレッドの sys.settrace() に渡されます。

threading.settrace_all_threads(func)

Set a trace function for all threads started from the threading module and all Python threads that are currently executing.

The func will be passed to sys.settrace() for each thread, before its run() method is called.

Added in version 3.12.

threading.gettrace()

settrace() 関数で設定したトレース関数を取得します。

Added in version 3.10.

threading.setprofile(func)

threading モジュールを使って開始した全てのスレッドにプロファイル関数を設定します。 func は各スレッドの run() を呼び出す前にスレッドの sys.setprofile() に渡されます。

threading.setprofile_all_threads(func)

Set a profile function for all threads started from the threading module and all Python threads that are currently executing.

The func will be passed to sys.setprofile() for each thread, before its run() method is called.

Added in version 3.12.

threading.getprofile()

setprofile() 関数で設定したプロファイラ関数を取得します。

Added in version 3.10.

threading.stack_size([size])

新しいスレッドを作るときのスレッドスタックサイズを返します。オプションの size 引数にはこれ以降に作成するスレッドのスタックサイズを指定し、0 (プラットフォームのデフォルト値または設定されたデフォルト値) か、 32,768 (32 KiB) 以上の正の整数でなければなりません。size が指定されない場合 0 が使われます。スレッドのスタックサイズの変更がサポートされていない場合、 RuntimeError を送出します。不正なスタックサイズが指定された場合、 ValueError を送出して、スタックサイズは変更されません。32 KiB は現在のインタープリタ自身のために十分であると保証された最小のスタックサイズです。いくつかのプラットフォームではスタックサイズに対して制限があることに注意してください。例えば最小のスタックサイズが 32 KiB より大きかったり、システムのメモリページサイズ の整数倍の必要があるなどです。この制限についてはプラットフォームのドキュメントを参照してください (一般的なページサイズは 4 KiB なので、プラットフォームに関する情報がない場合は 4096 の整数倍のスタックサイズを選ぶといいかもしれません)。

利用可能な環境: Windows, pthreads。

Unix platforms with POSIX threads support.

このモジュールでは以下の定数も定義しています:

threading.TIMEOUT_MAX

ブロックする関数 (Lock.acquire(), RLock.acquire(), Condition.wait() など) の timeout 引数に許される最大値。これ以上の値を timeout に指定すると OverflowError が発生します。

Added in version 3.2.

このモジュールは多くのクラスを定義しています。それらは下記のセクションで詳しく説明されます。

このモジュールのおおまかな設計は Java のスレッドモデルに基づいています。とはいえ、 Java がロックと条件変数を全てのオブジェクトの基本的な挙動にしているのに対し、 Python ではこれらを別個のオブジェクトに分けています。 Python の Thread クラスがサポートしているのは Java の Thread クラスの挙動のサブセットにすぎません; 現状では、優先度 (priority)やスレッドグループがなく、スレッドの破壊 (destroy)、中断 (stop)、一時停止 (suspend)、復帰 (resume)、割り込み (interrupt) は行えません。 Java の Thread クラスにおける静的メソッドに対応する機能が実装されている場合にはモジュールレベルの関数になっています。

以下に説明するメソッドは全て原子的 (atomic) に実行されます。

スレッドローカルデータ

スレッドローカルデータは、その値がスレッド固有のデータです。スレッドローカルデータを管理するには、単に local (あるいはそのサブクラス) のインスタンスを作成して、その属性に値を設定してください:

mydata = threading.local()
mydata.x = 1

インスタンスの値はスレッドごとに違った値になります。

class threading.local

スレッドローカルデータを表現するクラス。

For more details and extensive examples, see the documentation string of the _threading_local module: Lib/_threading_local.py [https://github.com/python/cpython/tree/3.12/Lib/_threading_local.py].

Thread オブジェクト

The 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 run() method in a subclass. No other methods (except for the constructor) should be overridden in a subclass. In other words, only override the __init__() and run() methods of this class.

ひとたびスレッドオブジェクトを生成すると、スレッドの start() メソッドを呼び出して活動を開始しなければなりません。 start() メソッド はそれぞれのスレッドの run() メソッドを起動します。

スレッドの活動が始まると、スレッドは '生存中 (alive)' とみなされます。 スレッドは、通常 run() メソッドが終了するまで、もしくは捕捉されない例外が送出されるまで生存中となります。 is_alive() メソッドは、スレッドが生存中であるかどうか調べます。

スレッドは他のスレッドの join() メソッドを呼び出すことができます。このメソッドは、 join() メソッドを呼ばれたスレッドが終了するまでメソッドの呼び出し元のスレッドをブロックします。

スレッドは名前を持っています。名前はコンストラクタに渡すことができ、 name 属性を通して読み出したり変更したりできます。

run() メソッドが例外を発生させた場合、threading.excepthook() が呼び出され、例外を処理します。デフォルトでは、threading.excepthook() は SystemExit を黙殺します。

スレッドには "デーモンスレッド (daemon thread)" であるというフラグを立てられます。 このフラグには、残っているスレッドがデーモンスレッドだけになった時に Python プログラム全体を終了させるという意味があります。フラグの初期値はスレッドを生成したスレッドから継承します。フラグの値は daemon プロパティまたは daemon コンストラクタ引数を通して設定できます。

注釈

デーモンスレッドは終了時にいきなり停止されます。デーモンスレッドで使われたリソース (開いているファイル、データベースのトランザクションなど) は適切に解放されないかもしれません。きちんと (gracefully) スレッドを停止したい場合は、スレッドを非デーモンスレッドにして、Event のような適切なシグナル送信機構を使用してください。

スレッドには "主スレッド (main thread)" オブジェクトがあります。主スレッドは Python プログラムを最初に制御していたスレッドです。主スレッドはデーモンスレッドではありません。

"ダミースレッドオブジェクト (dummy thread objects)" が作成される場合があります。ダミースレッドは、 "外来スレッド (alien thread)" に相当するスレッドオブジェクトです。ダミースレッドは、C コードから直接生成されたスレッドのような、 threading モジュールの外で開始された処理スレッドです。ダミースレッドオブジェクトには限られた機能しかなく、常に生存中、かつデーモンスレッドであるとみなされ、 join できません。また、外来スレッドの終了を検出するのは不可能なので、ダミースレッドは削除できません。

class threading.Thread(group=None, target=None, name=None, args=(), kwargs={}, *, daemon=None)

コンストラクタは常にキーワード引数を使って呼び出さなければなりません。各引数は以下の通りです:

group should be None; reserved for future extension when a ThreadGroup class is implemented.

target は run() メソッドによって起動される呼び出し可能オブジェクトです。デフォルトでは何も呼び出さないことを示す None になっています。

name*はスレッド名です。デフォルトでは、"Thread-*N"(N*は小さな10進数)、または*target*引数が指定された場合"Thread-*N (target)"("target"は``target.__name__``)という形式でユニークな名前が構成される。

args は target を呼び出すときの引数のリストかタプルです。デフォルトは () です。

kwargs は target を呼び出すときのキーワード引数の辞書です。デフォルトは {} です。

None でない場合、daemon はスレッドがデーモンかどうかを明示的に設定します。None の場合 (デフォルト)、デーモン属性は現在のスレッドから継承されます。

サブクラスでコンストラクタをオーバライドした場合、必ずスレッドが何かを始める前に基底クラスのコンストラクタ (Thread.__init__()) を呼び出しておかなくてはなりません。

バージョン 3.3 で変更: Added the daemon parameter.

バージョン 3.10 で変更: name 引数が省略された場合、target 名を使用します。

start()

スレッドの活動を開始します。

このメソッドは、スレッドオブジェクトあたり一度しか呼び出してはなりません。 start() は、オブジェクトの run() メソッドが個別の処理スレッド中で呼び出されるように調整します。

同じスレッドオブジェクトに対し、このメソッドを2回以上呼び出した場合、 RuntimeError を送出します。

run()

スレッドの活動をもたらすメソッドです。

このメソッドはサブクラスでオーバライドできます。標準の run() メソッドでは、オブジェクトのコンストラクタの target 引数に呼び出し可能オブジェクトを指定した場合、 args および kwargs の位置引数およびキーワード引数とともに呼び出します。

Thread に渡される args の引数にリストやタプルを使っても、同じ効果が得られます。

以下はプログラム例です:

>>> from threading import Thread
>>> t = Thread(target=print, args=[1])
>>> t.run()
1
>>> t = Thread(target=print, args=(1,))
>>> t.run()
1

join(timeout=None)

スレッドが終了するまで待機します。このメソッドは、 join() を呼ばれたスレッドが正常終了あるいは処理されない例外によって終了するか、オプションのタイムアウトが発生するまで、メソッドの呼び出し元のスレッドをブロックします。

timeout 引数が存在して None 以外の場合、それは操作に対するタイムアウト秒 (あるいは秒未満の端数) を表す浮動小数点数でなければなりません。 join() は常に None を返すので、 join() の後に is_alive() を呼び出してタイムアウトしたかどうかを確認しなければなりません。もしスレッドがまだ生存中であれば、 join() はタイムアウトしています。

timeout が指定されないかまたは None であるときは、この操作はスレッドが終了するまでブロックします。

1つのスレッドは何回も join されることができます。

現在のスレッドに対して join() を呼び出そうとすると、デッドロックを引き起こすため RuntimeError が送出されます。 スレッドが開始される前に join() を呼び出すことも同様のエラーのため、同じ例外が送出されます。

name

識別のためにのみ用いられる文字列です。名前には機能上の意味づけ (semantics) はありません。複数のスレッドに同じ名前をつけてもかまいません。名前の初期値はコンストラクタで設定されます。

getName()

setName()

name に対する非推奨 getter/setter API; 代わりにプロパティを直接使用してください。

バージョン 3.10 で非推奨.

ident

'スレッド識別子' 、または、スレッドが開始されていなければ None です。非ゼロの整数です。 get_ident() 関数を参照下さい。スレッド識別子は、スレッドが終了した後、新たなスレッドが生成された場合、再利用され得ます。スレッド識別子は、スレッドが終了した後でも利用できます。

native_id

The Thread ID (TID) of this thread, as assigned by the OS (kernel). This is a non-negative integer, or None if the thread has not been started. See the 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).

注釈

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.

利用可能な環境: Windows, FreeBSD, Linux, macOS, OpenBSD, NetBSD, AIX, DragonFlyBSD。

Added in version 3.8.

is_alive()

スレッドが生存中かどうかを返します。

このメソッドは、 run() メソッドが起動する直前から run() メソッドが終了する直後までの間 True を返します。モジュール関数 enumerate() は、全ての生存中のスレッドのリストを返します。

daemon

このスレッドがデーモンスレッドか (True) か否か (False) を示すブール値。この値は start() の呼び出し前に設定されなければなりません。さもなければ RuntimeError が送出されます。初期値は生成側のスレッドから継承されます; メインスレッドはデーモンスレッドではないので、メインスレッドで作成されたすべてのスレッドは、デフォルトで daemon = False になります。

デーモンでない生存中のスレッドが全てなくなると、 Python プログラム全体が終了します。

isDaemon()

setDaemon()

daemon に対する非推奨 getter/setter API; 代わりにプロパティを直接使用してください。

バージョン 3.10 で非推奨.

Lock オブジェクト

プリミティブロックとは、ロックが生じた際に特定のスレッドによって所有されない同期プリミティブです。 Python では現在のところ拡張モジュール _thread で直接実装されている最も低水準の同期プリミティブを使えます。

プリミティブロックは2つの状態、 "ロック" または "アンロック" があります。ロックはアンロック状態で作成されます。ロックには基本となる二つのメソッド、 acquire() と release() があります。ロックの状態がアンロックである場合、 acquire() は状態をロックに変更して即座に処理を戻します。 状態がロックの場合、 acquire() は他のスレッドが release() を呼び出してロックの状態をアンロックに変更するまでブロックします。その後、 acquire() 呼び出しは状態を再度ロックに設定してから処理を戻します。 release() メソッドを呼び出すのはロック状態のときでなければなりません; このメソッドはロックの状態をアンロックに変更して、即座に処理を戻します。 アンロックの状態のロックを解放しようとすると RuntimeError が送出されます。

ロックは コンテキストマネージメントプロトコル もサポートします。

複数のスレッドにおいて acquire() がアンロック状態への遷移を待っているためにブロックが起きている時に release() を呼び出してロックの状態をアンロックにすると、一つのスレッドだけが処理を進行できます。 どのスレッドが処理を進行できるのかは定義されておらず、実装によって異なるかもしれません。

全てのメソッドはアトミックに実行されます。

class threading.Lock

プリミティブロック (primitive lock) オブジェクトを実装しているクラスです。スレッドが一度ロックを獲得すると、それ以後のロック獲得の試みはロックが解放されるまでブロックします。どのスレッドでもロックを解放できます。

Note that Lock is actually a factory function which returns an instance of the most efficient version of the concrete Lock class that is supported by the platform.

acquire(blocking=True, timeout=-1)

ブロックあり、またはブロックなしでロックを獲得します。

引数 blocking を True (デフォルト) に設定して呼び出した場合、ロックがアンロック状態になるまでブロックします。そしてそれをロック状態にしてから True を返します。

引数 blocking の値を False にして呼び出すとブロックしません。blocking を True にして呼び出した場合にブロックするような状況では、直ちに False を返します。それ以外の場合には、ロックをロック状態にして True を返します。

正の値に設定された浮動小数点の timeout 引数とともに起動された場合、ロックを得られなければ最大で timeout によって指定された秒数だけブロックします。timeout 引数の -1 は無制限の待機を指定します。blocking が False の場合に timeout を指定することは禁止されています。

ロックを獲得すると True を、ロックを獲得できなかったとき (例えば timeout が過ぎた場合) には False を返します。

バージョン 3.2 で変更: 新しい timeout 引数。

バージョン 3.2 で変更: Lock acquisition can now be interrupted by signals on POSIX if the underlying threading implementation supports it.

release()

ロックを解放します。これはロックを獲得したスレッドだけでなく、任意のスレッドから呼ぶことができます。

ロックの状態がロックのとき、状態をアンロックにリセットして処理を戻します。他のスレッドがロックがアンロック状態になるのを待ってブロックしている場合、ただ一つのスレッドだけが処理を継続できるようにします。

アンロック状態のロックに対して呼び出された場合、RuntimeError が送出されます。

戻り値はありません。

locked()

ロック状態のとき True を返します。

RLock オブジェクト

再入可能ロック (reentrant lock) とは、同じスレッドが複数回獲得できるような同期プリミティブです。再入可能ロックの内部では、プリミティブロックの使うロック／アンロック状態に加え、 "所有スレッド (owning thread)" と "再帰レベル (recursion level)" という概念を用いています。ロック状態では何らかのスレッドがロックを所有しており、アンロック状態ではいかなるスレッドもロックを所有していません。

このロックの状態をロックにするには、スレッドがロックの acquire() メソッドを呼び出します。このメソッドはスレッドがロックを所有すると処理を戻します。ロックの状態をアンロックにするには release() メソッドを呼び出します。 acquire() / release() からなるペアの呼び出しはネストできます; 最後に呼び出した release() (最も外側の呼び出しペアの release()) だけがロックの状態をアンロックにリセットして、 acquire() でブロック中の別のスレッドの処理を進行させることができます。

再入可能ロックは コンテキストマネージメントプロトコル もサポートします。

class threading.RLock

このクラスは再入可能ロックオブジェクトを実装します。再入可能ロックはそれを獲得したスレッドによって解放されなければなりません。いったんスレッドが再入可能ロックを獲得すると、同じスレッドはブロックされずにもう一度それを獲得できます ; そのスレッドは獲得した回数だけ解放しなければいけません。

RLock は実際にはファクトリ関数で、プラットフォームでサポートされる最も効率的なバージョンの具体的な RLock クラスのインスタンスを返すことに注意してください。

acquire(blocking=True, timeout=-1)

ブロックあり、またはブロックなしでロックを獲得します。

引数なしで呼び出した場合: スレッドが既にロックを所有している場合、再帰レベルをインクリメントして即座に処理を戻します。それ以外の場合、他のスレッドがロックを所有していれば、そのロックの状態がアンロックになるまでブロックします。その後、ロックの状態がアンロックになる (いかなるスレッドもロックを所有しない状態になる) と、ロックの所有権を獲得し、再帰レベルを 1 にセットして処理を戻します。ロックの状態がアンロックになるのを待っているスレッドが複数ある場合、その中の一つだけがロックの所有権を獲得できます。この場合、戻り値はありません。

引数 blocking の値を True にして呼び出した場合、引数なしで呼び出したときと同じことを行ない、 True を返します。

引数 blocking の値を False にして呼び出すとブロックしません。引数なしで呼び出した場合にブロックするような状況であった場合には直ちに False を返します。それ以外の場合には、引数なしで呼び出したときと同じ処理を行い True を返します。

正の値に設定された浮動小数点の timeout 引数とともに起動された場合、ロックを得られなければ最大で timeout によって指定された秒数だけブロックします。ロックを獲得した場合 True を返し、タイムアウトが過ぎた場合は False を返します。

バージョン 3.2 で変更: 新しい timeout 引数。

release()

再帰レベルをデクリメントしてロックを解放します。デクリメント後に再帰レベルがゼロになった場合、ロックの状態をアンロック (いかなるスレッドにも所有されていない状態) にリセットし、ロックの状態がアンロックになるのを待ってブロックしているスレッドがある場合にはその中のただ一つだけが処理を進行できるようにします。デクリメント後も再帰レベルがゼロでない場合、ロックの状態はロックのままで、呼び出し側のスレッドに所有されたままになります。

呼び出し側のスレッドがロックを所有しているときにのみこのメソッドを呼び出してください。ロックの状態がアンロックの時にこのメソッドを呼び出すと、 RuntimeError が送出されます。

戻り値はありません。

Condition オブジェクト

条件変数 (condition variable) は、常にある種のロックに関連付けられています; このロックは明示的に渡すことも、デフォルトで生成させることもできます。複数の条件変数で同じロックを共有しなければならない場合には、引渡しによる関連付けが便利です。ロックは条件オブジェクトの一部です: それを別々に扱う必要はありません。

条件変数は コンテキスト管理プロトコル に従います: with 文を使って囲まれたブロックの間だけ関連付けられたロックを獲得することができます。 acquire() メソッドと release() メソッドは、さらに関連付けられたロックの対応するメソッドを呼び出します。

他のメソッドは、関連付けられたロックを保持した状態で呼び出さなければなりません。 wait() メソッドはロックを解放します。そして別のスレッドが notify() または notify_all() を呼ぶことによってスレッドを起こすまでブロックします。一旦起こされたなら、 wait() は再びロックを得て戻ります。タイムアウトを指定することも可能です。

notify() メソッドは条件変数待ちのスレッドを1つ起こします。 notify_all() メソッドは条件変数待ちの全てのスレッドを起こします。

注意: notify() と notify_all() はロックを解放しません; 従って、スレッドが起こされたとき、 wait() の呼び出しは即座に処理を戻すわけではなく、 notify() または notify_all() を呼び出したスレッドが最終的にロックの所有権を放棄したときに初めて処理を返すのです。

条件変数を使う典型的なプログラミングスタイルでは、何らかの共有された状態変数へのアクセスを同期させるためにロックを使います; 状態変数が特定の状態に変化したことを知りたいスレッドは、自分の望む状態になるまで繰り返し wait() を呼び出します。その一方で、状態変更を行うスレッドは、前者のスレッドが待ち望んでいる状態であるかもしれないような状態へ変更を行ったときに notify() や notify_all() を呼び出します。例えば、以下のコードは無制限のバッファ容量のときの一般的な生産者-消費者問題です:

# 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()

アプリケーションの条件をチェックする while ループは必須です。なぜなら、 wait() が任意の長時間の後で返り、 notify() 呼び出しを促した条件がもはや真でないことがありえるからです。これはマルチスレッドプログラミングに固有です。条件チェックを自動化するために wait_for() メソッドを使うことができ、それはタイムアウトの計算を簡略化します:

# Consume an item
with cv:
    cv.wait_for(an_item_is_available)
    get_an_available_item()

notify() と notify_all() のどちらを使うかは、その状態の変化に興味を持っている待ちスレッドが一つだけなのか、あるいは複数なのかで考えます。例えば、典型的な生産者-消費者問題では、バッファに1つの要素を加えた場合には消費者スレッドを 1 つしか起こさなくてかまいません。

class threading.Condition(lock=None)

このクラスは条件変数 (condition variable) オブジェクトを実装します。条件変数を使うと、1つ以上のスレッドを別のスレッドの通知があるまで待機させておけます。

lock に None でない値を指定した場合、その値は Lock または RLock オブジェクトでなければなりません。この場合、 lock は根底にあるロックオブジェクトとして使われます。それ以外の場合には、 RLock オブジェクトを新しく作成して使います。

バージョン 3.3 で変更: ファクトリ関数からクラスに変更されました。

acquire(*args)

根底にあるロックを獲得します。このメソッドは根底にあるロックの対応するメソッドを呼び出します。そのメソッドの戻り値を返します。

release()

根底にあるロックを解放します。このメソッドは根底にあるロックの対応するメソッドを呼び出します。戻り値はありません。

wait(timeout=None)

通知 (notify) を受けるか、タイムアウトするまで待機します。呼び出し側のスレッドがロックを獲得していないときにこのメソッドを呼び出すと RuntimeError が送出されます。

このメソッドは根底にあるロックを解放し、他のスレッドが同じ条件変数に対して notify() または notify_all() を呼び出して現在のスレッドを起こすか、オプションのタイムアウトが発生するまでブロックします。一度スレッドが起こされると、再度ロックを獲得して処理を戻します。

timeout 引数を指定して、 None 以外の値にする場合、タイムアウトを秒 (または端数秒) を表す浮動小数点数でなければなりません。

根底にあるロックが RLock である場合、 release() メソッドではロックは解放されません。というのも、ロックが再帰的に複数回獲得されている場合には、 release() によって実際にアンロックが行われないかもしれないからです。その代わり、ロックが再帰的に複数回獲得されていても確実にアンロックを行える RLock クラスの内部インターフェースを使います。その後ロックを再獲得する時に、もう一つの内部インターフェースを使ってロックの再帰レベルを復帰します。

与えられた timeout が過ぎていなければ返り値は True です。タイムアウトした場合には False が返ります。

バージョン 3.2 で変更: 以前は、このメソッドは常に None を返していました。

wait_for(predicate, timeout=None)

条件が真と判定されるまで待ちます。 predicate は呼び出し可能オブジェクトでなければならず、その結果はブール値として解釈されます。最大の待ち時間を指定する timeout を与えることができます。

このユーティリティメソッドは、述語が満たされるかタイムアウトが発生するまで wait() を繰り返し呼び出す場合があります。戻り値は述語の最後の戻り値で、もしメソッドがタイムアウトすれば、 False と評価されます。

タイムアウト機能を無視すれば、このメソッドの呼び出しは以下のように書くのとほぼ等価です:

while not predicate():
    cv.wait()

したがって、 wait() と同じルールが適用されます: 呼び出された時にロックを保持していなければならず、戻るときにロックが再度獲得されます。述語はロックを保持した状態で評価されます。

Added in version 3.2.

notify(n=1)

デフォルトで、この条件変数を待っている1つのスレッドを起こします。 呼び出し側のスレッドがロックを獲得していないときにこのメソッドを呼び出すと RuntimeError が送出されます。

何らかの待機中スレッドがある場合、そのうち n スレッドを起こします。待機中のスレッドがなければ何もしません。

現在の実装では、少なくとも n スレッドが待機中であれば、ちょうど n スレッドを起こします。とはいえ、この挙動に依存するのは安全ではありません。将来、実装の最適化によって、複数のスレッドを起こすようになるかもしれないからです。

注意: 起こされたスレッドは実際にロックを再獲得できるまで wait() 呼び出しから戻りません。 notify() はロックを解放しないので、 notify() 呼び出し側は明示的にロックを解放しなければなりません。

notify_all()

この条件を待っているすべてのスレッドを起こします。このメソッドは notify() のように動作しますが、 1 つではなくすべての待ちスレッドを起こします。呼び出し側のスレッドがロックを獲得していない場合、 RuntimeError が送出されます。

関数``notifyAll``はこの関数の非推奨エイリアスです。

Semaphore オブジェクト

セマフォ (semaphore) は、計算機科学史上最も古い同期プリミティブの一つ で、草創期のオランダ計算機科学者 Edsger W. Dijkstra によって発明されました (彼は acquire() と release() の代わりに P() と V() を使いました)。

セマフォは acquire() でデクリメントされ release() でインクリメントされるような内部カウンタを管理します。 カウンタは決してゼロより小さくはなりません; acquire() は、カウンタがゼロになっている場合、他のスレッドが release() を呼び出すまでブロックします。

セマフォは コンテキストマネージメントプロトコル もサポートします。

class threading.Semaphore(value=1)

このクラスはセマフォ (semaphore) オブジェクトを実装します。セマフォは、 release() を呼び出した数から acquire() を呼び出した数を引き、初期値を足した値を表す極小のカウンタを管理します。 acquire() メソッドは、カウンタの値を負にせずに処理を戻せるまで必要ならば処理をブロックします。 value を指定しない場合、デフォルトの値は 1 になります。

オプションの引数には、内部カウンタの初期値を指定します。デフォルトは 1 です。与えられた value が 0 より小さい場合、 ValueError が送出されます。

バージョン 3.3 で変更: ファクトリ関数からクラスに変更されました。

acquire(blocking=True, timeout=None)

セマフォを獲得します。

When invoked without arguments:

If the internal counter is larger than zero on entry, decrement it by one and return True immediately.

If the internal counter is zero on entry, block until awoken by a call to release(). Once awoken (and the counter is greater than 0), decrement the counter by 1 and return True. Exactly one thread will be awoken by each call to release(). The order in which threads are awoken should not be relied on.

blocking を False にして呼び出すとブロックしません。引数なしで呼び出した場合にブロックするような状況であった場合には直ちに False を返します。それ以外の場合には、引数なしで呼び出したときと同じ処理を行い True を返します。

None 以外の timeout で起動された場合、最大で timeout 秒ブロックします。 acquire が その間隔の間で完了しなかった場合は False が返ります。そうでなければ True が返ります。

バージョン 3.2 で変更: 新しい timeout 引数。

release(n=1)

内部カウンタを n インクリメントして、セマフォを解放します。 release() 処理に入ったときにカウンタがゼロであり、カウンタの値がゼロより大きくなるのを待っている別のスレッドがあった場合、それらのスレッドから n 個を起こします。

バージョン 3.9 で変更: 複数の待機中のスレッドを一度に解放する n パラメータを追加しました。

class threading.BoundedSemaphore(value=1)

有限セマフォ (bounded semaphore) オブジェクトを実装しているクラスです。有限セマフォは、現在の値が初期値を超過しないようチェックを行います。超過を起こした場合、 ValueError を送出します。たいていの場合、セマフォは限られた容量のリソースを保護するために使われるものです。従って、あまりにも頻繁なセマフォの解放はバグが生じているしるしです。 value を指定しない場合、デフォルトの値は 1 になります。

バージョン 3.3 で変更: ファクトリ関数からクラスに変更されました。

Semaphore の例

セマフォはしばしば、容量に限りのある資源、例えばデータベースサーバなどを保護するために使われます。リソースが固定の状況では、常に有限セマフォを使わなければなりません。主スレッドは、作業スレッドを立ち上げる前にセマフォを初期化します:

maxconnections = 5
# ...
pool_sema = BoundedSemaphore(value=maxconnections)

作業スレッドは、ひとたび立ち上がると、サーバへ接続する必要が生じたときにセマフォの acquire() および release() メソッドを呼び出します:

with pool_sema:
    conn = connectdb()
    try:
        # ... use connection ...
    finally:
        conn.close()

有限セマフォを使うと、セマフォを獲得回数以上に解放してしまうというプログラム上の間違いを見逃しにくくします。

Event オブジェクト

イベントは、あるスレッドがイベントを発信し、他のスレッドはそれを待つという、スレッド間で通信を行うための最も単純なメカニズムの一つです。

イベントオブジェクトは内部フラグを管理します。このフラグは set() メソッドで値を true に、 clear() メソッドで値を false にリセットします。 wait() メソッドはフラグが true になるまでブロックします。

class threading.Event

イベントオブジェクトを実装しているクラスです。イベントは set() メソッドを使うと True に、 clear() メソッドを使うと False にセットされるようなフラグを管理します。 wait() メソッドは、全てのフラグが true になるまでブロックするようになっています。フラグの初期値は false です。

バージョン 3.3 で変更: ファクトリ関数からクラスに変更されました。

is_set()

内部フラグが真のとき True を返します。

メソッド isSet はこのメソッドの非推奨エイリアスです。

set()

内部フラグの値を true にセットします。フラグの値が true になるのを待っている全てのスレッドを起こします。一旦フラグが true になると、スレッドが wait() を呼び出しても全くブロックしなくなります。

clear()

内部フラグの値を false にリセットします。以降は、 set() を呼び出して再び内部フラグの値を true にセットするまで、 wait() を呼び出したスレッドはブロックするようになります。

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; True if returning because the internal flag is set to true, or False if a timeout is given and the the internal flag did not become true within the given wait time.

When the timeout argument is present and not None, it should be a floating point number specifying a timeout for the operation in seconds, or fractions thereof.

バージョン 3.1 で変更: 以前は、このメソッドは常に None を返していました。

Timer オブジェクト

このクラスは、一定時間経過後に実行される活動、すなわちタイマ活動を表現します。 Timer は Thread のサブクラスであり、自作のスレッドを構築した一例でもあります。

Timers are started, as with threads, by calling their Timer.start method. The timer can be stopped (before its action has begun) by calling the 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.

例えば:

def hello():
    print("hello, world")

t = Timer(30.0, hello)
t.start()  # after 30 seconds, "hello, world" will be printed

class threading.Timer(interval, function, args=None, kwargs=None)

interval 秒後に引数 args キーワード引数 kwargs で function を実行するようなタイマを生成します。args*が ``None`` (デフォルト) なら空のリストが使用されます。*kwargs が None (デフォルト) なら空の辞書が使用されます。

バージョン 3.3 で変更: ファクトリ関数からクラスに変更されました。

cancel()

タイマをストップして、その動作の実行をキャンセルします。このメソッドはタイマがまだ活動待ち状態にある場合にのみ動作します。

バリアオブジェクト

Added in version 3.2.

このクラスは、互いを待つ必要のある固定の数のスレッドで使用するための単純な同期プリミティブを提供します。それぞれのスレッドは wait() メソッドを呼ぶことによりバリアを通ろうとしてブロックします。すべてのスレッドがそれぞれの wait() メソッドを呼び出した時点で、すべてのスレッドが同時に解放されます。

バリアは同じ数のスレッドに対して何度でも再利用することができます。

例として、クライアントとサーバの間でスレッドを同期させる単純な方法を紹介します:

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)

class threading.Barrier(parties, action=None, timeout=None)

parties 個のスレッドのためのバリアオブジェクトを作成します。 action は、もし提供されるなら呼び出し可能オブジェクトで、スレッドが解放される時にそのうちの1つによって呼ばれます。 timeout は、 wait() メソッドに対して none が指定された場合のデフォルトのタイムアウト値です。

wait(timeout=None)

バリアを通ります。バリアに対するすべてのスレッドがこの関数を呼んだ時に、それらは同時にすべて解放されます。timeout が提供される場合、それはクラスコンストラクタに渡された値に優先して使用されます。

返り値は 0 から parties -- 1 の範囲の整数で、それぞれのスレッドに対して異なります。これは、特別な後始末 (housekeeping) を行うスレッドを選択するために使用することができます。例えば:

i = barrier.wait()
if i == 0:
    # Only one thread needs to print this
    print("passed the barrier")

action がコンストラクタに渡されていれば、スレッドのうちの1つが解放される前にそれを呼び出します。万一この呼び出しでエラーが発生した場合、バリアは broken な状態に陥ります。

この呼び出しがタイムアウトする場合、バリアは broken な状態に陥ります。

スレッドが待っている間にバリアが broken になるかリセットされた場合、このメソッドは BrokenBarrierError 例外を送出するかもしれません。

reset()

バリアをデフォルトの空の状態に戻します。そのバリアの上で待っているすべてのスレッドは BrokenBarrierError 例外を受け取ります。

状態が未知の他のスレッドがある場合、この関数を使用するのに何らかの外部同期を必要とするかもしれないことに注意してください。バリアが broken な場合、単にそれをそのままにして新しいものを作成する方がよいでしょう。

abort()

バリアを broken な状態にします。これによって、現在または将来の wait() 呼び出しが BrokenBarrierError とともに失敗するようになります。これを使うと、例えばスレッドが異常終了する必要がある場合にアプリケーションがデッドロックするのを避けることができます。

スレッドのうちの1つが返ってこないことに対して自動的に保護するように、単純に常識的な timeout 値でバリアを作成することは望ましいかもしれません。

parties

バリアを通るために要求されるスレッドの数。

n_waiting

現在バリアの中で待っているスレッドの数。

broken

バリアが broken な状態である場合に True となるブール値。

exception threading.BrokenBarrierError

Barrier オブジェクトがリセットされるか broken な場合に、この例外 (RuntimeError のサブクラス) が送出されます。

with 文でのロック・条件変数・セマフォの使い方

All of the objects provided by this module that have acquire and release methods can be used as context managers for a with statement. The acquire method will be called when the block is entered, and release will be called when the block is exited. Hence, the following snippet:

with some_lock:
    # do something...

は、以下と同じです

some_lock.acquire()
try:
    # do something...
finally:
    some_lock.release()

現在のところ、 Lock 、 RLock 、 Condition 、 Semaphore 、 BoundedSemaphore を with 文のコンテキストマネージャとして使うことができます。

multiprocessing --- Process-based parallelism

ソースコード: Lib/multiprocessing/ [https://github.com/python/cpython/tree/3.12/Lib/multiprocessing/]

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. See WebAssemblyプラットフォーム for more information.

はじめに

multiprocessing is a package that supports spawning processes using an API similar to the threading module. The multiprocessing package offers both local and remote concurrency, effectively side-stepping the Global Interpreter Lock by using subprocesses instead of threads. Due to this, the multiprocessing module allows the programmer to fully leverage multiple processors on a given machine. It runs on both POSIX and Windows.

multiprocessing モジュールでは、threading モジュールには似たものが存在しない API も導入されています。その最たるものが Pool オブジェクトです。これは複数の入力データに対して、サブプロセス群に入力データを分配 (データ並列) して関数を並列実行するのに便利な手段を提供します。以下の例では、モジュール内で関数を定義して、子プロセスがそのモジュールを正常にインポートできるようにする一般的な方法を示します。 Pool を用いたデータ並列の基礎的な例は次の通りです:

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]))

標準出力に以下が出力されます:

[1, 4, 9]

参考

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 Pool interface directly, the concurrent.futures API more readily allows the submission of work to the underlying process pool to be separated from waiting for the results.

Process クラス

multiprocessing モジュールでは、プロセスは以下の手順によって生成されます。はじめに Process のオブジェクトを作成し、続いて start() メソッドを呼び出します。この Process クラスは threading.Thread クラスと同様の API を持っています。まずは、簡単な例をもとにマルチプロセスを使用したプログラムについてみていきましょう

from multiprocessing import Process

def f(name):
    print('hello', name)

if __name__ == '__main__':
    p = Process(target=f, args=('bob',))
    p.start()
    p.join()

実行された個々のプロセス ID を表示するために拡張したサンプルコードを以下に示します:

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()

なぜ if __name__ == '__main__' という記述が必要かは プログラミングガイドライン を参照してください。

コンテキストと開始方式

プラットフォームにもよりますが、multiprocessing はプロセスを開始するために 3 つの方法をサポートしています。それら 開始方式 は以下のとおりです

spawn

親プロセスは新たに Python インタープリタープロセスを開始します。子プロセスはプロセスオブジェクトの run() メソッドの実行に必要なリソースのみ継承します。特に、親プロセスからの不要なファイル記述子とハンドルは継承されません。この方式を使用したプロセスの開始は fork や forkserver に比べ遅くなります。

Available on POSIX and Windows platforms. The default on Windows and macOS.

fork

親プロセスは os.fork() を使用して Python インタープリターをフォークします。子プロセスはそれが開始されるとき、事実上親プロセスと同一になります。親プロセスのリソースはすべて子プロセスに継承されます。マルチスレッドプロセスのフォークは安全性に問題があることに注意してください。

Available on POSIX systems. Currently the default on POSIX except macOS.

注釈

The default start method will change away from fork in Python 3.14. Code that requires fork should explicitly specify that via get_context() or set_start_method().

バージョン 3.12 で変更: If Python is able to detect that your process has multiple threads, the os.fork() function that this start method calls internally will raise a DeprecationWarning. Use a different start method. See the os.fork() documentation for further explanation.

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 os.fork(). No unnecessary resources are inherited.

Available on POSIX platforms which support passing file descriptors over Unix pipes such as Linux.

バージョン 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 [https://bugs.python.org/issue?@action=redirect&bpo=33725].

On POSIX using the spawn or forkserver start methods will also start a resource tracker process which tracks the unlinked named system resources (such as named semaphores or 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.)

開始方式はメインモジュールの if __name__ == '__main__' 節内で、関数 set_start_method() によって指定します。以下に例を示します:

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()

関数 set_start_method() はプログラム内で複数回使用してはいけません。

もうひとつの方法として、get_context() を使用してコンテキストオブジェクトを取得することができます。コンテキストオブジェクトは multiprocessing モジュールと同じ API を持ち、同じプログラム内で複数の開始方式を使用できます。

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()

あるコンテキストに関連したオブジェクトは、異なるコンテキストのプロセスとは互換性がない場合があることに注意してください。特に、fork コンテキストを使用して作成されたロックは、spawn あるいは forkserver を使用して開始されたプロセスに渡すことはできません。

特定の開始方式の使用を要求するライブラリは get_context() を使用してライブラリ利用者の選択を阻害しないようにするべきです。

警告

The 'spawn' and '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 'fork' start method may work if code does not use threads.

プロセス間でのオブジェクト交換

multiprocessing モジュールでは、プロセス間通信の手段が2つ用意されています。それぞれ以下に詳細を示します:

キュー (Queue)

Queue クラスは queue.Queue クラスとほとんど同じように使うことができます。以下に例を示します:

from multiprocessing import Process, Queue

def f(q):
    q.put([42, None, 'hello'])

if __name__ == '__main__':
    q = Queue()
    p = Process(target=f, args=(q,))
    p.start()
    print(q.get())    # prints "[42, None, 'hello']"
    p.join()

キューはスレッドセーフであり、プロセスセーフです。

パイプ (Pipe)

Pipe() 関数はパイプで繋がれたコネクションオブジェクトのペアを返します。デフォルトでは双方向性パイプを返します。以下に例を示します:

from multiprocessing import Process, Pipe

def f(conn):
    conn.send([42, None, 'hello'])
    conn.close()

if __name__ == '__main__':
    parent_conn, child_conn = Pipe()
    p = Process(target=f, args=(child_conn,))
    p.start()
    print(parent_conn.recv())   # prints "[42, None, 'hello']"
    p.join()

パイプのそれぞれの端を表す2つのコネクションオブジェクトが Pipe() 関数から返されます。各コネクションオブジェクトには、 send()、 recv()、その他のメソッドがあります。2つのプロセス (またはスレッド) がパイプの 同じ 端で同時に読み込みや書き込みを行うと、パイプ内のデータが破損してしまうかもしれないことに注意してください。もちろん、各プロセスがパイプの別々の端を同時に使用するならば、データが破壊される危険性はありません。

プロセス間の同期

multiprocessing は threading モジュールと等価な同期プリミティブを備えています。以下の例では、ロックを使用して、一度に1つのプロセスしか標準出力に書き込まないようにしています:

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()

ロックを使用しないで標準出力に書き込んだ場合は、各プロセスからの出力がごちゃまぜになってしまいます。

プロセス間での状態の共有

これまでの話の流れで触れたとおり、並行プログラミングを行うときには、できるかぎり状態を共有しないのが定石です。複数のプロセスを使用するときは特にそうでしょう。

しかし、どうしてもプロセス間のデータ共有が必要な場合のために multiprocessing モジュールには2つの方法が用意されています。

共有メモリ (Shared memory)

データを共有メモリ上に保持するために Value クラス、もしくは Array クラスを使用することができます。以下のサンプルコードを使って、この機能についてみていきましょう

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[:])

このサンプルコードを実行すると以下のように表示されます

3.1415927
[0, -1, -2, -3, -4, -5, -6, -7, -8, -9]

num と arr を生成するときに使用されている、引数 'd' と 'i' は array モジュールにより使用される種別の型コードです。ここで使用されている 'd' は倍精度浮動小数、 'i' は符号付整数を表します。これらの共有オブジェクトは、プロセスセーフでありスレッドセーフです。

共有メモリを使用して、さらに柔軟なプログラミングを行うには multiprocessing.sharedctypes モジュールを使用します。このモジュールは共有メモリから割り当てられた任意の ctypes オブジェクトの生成をサポートします。

サーバープロセス (Server process)

Manager() 関数により生成されたマネージャーオブジェクトはサーバープロセスを管理します。マネージャーオブジェクトは Python のオブジェクトを保持して、他のプロセスがプロキシ経由でその Python オブジェクトを操作することができます。

Manager() 関数が返すマネージャは list, dict, Namespace, Lock, RLock, Semaphore, BoundedSemaphore, Condition, Event, Barrier, Queue, Value, Array をサポートします。 以下にサンプルコードを示します。

from multiprocessing import Process, Manager

def f(d, l):
    d[1] = '1'
    d['2'] = 2
    d[0.25] = None
    l.reverse()

if __name__ == '__main__':
    with Manager() as manager:
        d = manager.dict()
        l = manager.list(range(10))

        p = Process(target=f, args=(d, l))
        p.start()
        p.join()

        print(d)
        print(l)

このサンプルコードを実行すると以下のように表示されます

{0.25: None, 1: '1', '2': 2}
[9, 8, 7, 6, 5, 4, 3, 2, 1, 0]

サーバープロセスのマネージャーオブジェクトは共有メモリのオブジェクトよりも柔軟であるといえます。それは、どのような型のオブジェクトでも使えるからです。また、1つのマネージャーオブジェクトはネットワーク経由で他のコンピューター上のプロセスによって共有することもできます。しかし、共有メモリより動作が遅いという欠点があります。

ワーカープロセスのプールを使用

Pool クラスは、ワーカープロセスをプールする機能を備えています。このクラスには、異なる方法でワーカープロセスへタスクを割り当てるいくつかのメソッドがあります。

例えば:

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")

プールオブジェクトのメソッドは、そのプールを作成したプロセスのみが呼び出すべきです。

注釈

このパッケージに含まれる機能を使用するためには、子プロセスから __main__ モジュールをインポートできる必要があります。このことについては プログラミングガイドライン で触れていますが、ここであらためて強調しておきます。なぜかというと、いくつかのサンプルコード、例えば multiprocessing.pool.Pool のサンプルはインタラクティブシェル上では動作しないからです。以下に例を示します:

>>> 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'>)>

(もしこのコードを試すなら、実際には3つの完全なトレースバックがばらばらの順番で出力されますし、親プロセスを何らかの方法で止める必要があります。)

リファレンス

multiprocessing パッケージは threading モジュールの API とほとんど同じです。

Process クラスと例外

class multiprocessing.Process(group=None, target=None, name=None, args=(), kwargs={}, *, daemon=None)

Process オブジェクトは各プロセスの処理を表します。 Process クラスは threading.Thread クラスのすべてのメソッドと同じインターフェースを提供します。

コンストラクターは必ずキーワード引数で呼び出すべきです。引数 group には必ず None を渡してください。 この引数は threading.Thread クラスとの互換性のためだけに残されています。引数 target には、 run() メソッドから呼び出される callable オブジェクトを渡します。この引数はデフォルトで None となっており、何も呼び出されません。引数 name にはプロセス名を渡します (詳細は name を見てください)。 args は対象の呼び出しに対する引数のタプルを渡します。 kwargs は対象の呼び出しに対するキーワード引数の辞書を渡します。もし提供されれば、キーワード専用の daemon 引数はプロセスの daemon フラグを True または False にセットします。 None の場合 (デフォルト)、このフラグは作成するプロセスから継承されます。

デフォルトでは、target に何の引数も与えられません。(実) 引数 args (デフォルトは``()``)は、target に渡す引数のリストまたはタプルを指定するために使用されます。

サブクラスがコンストラクターをオーバーライドする場合は、そのプロセスに対する処理を行う前に基底クラスのコンストラクター (Process.__init__()) を実行しなければなりません。

バージョン 3.3 で変更: Added the daemon parameter.

run()

プロセスが実行する処理を表すメソッドです。

このメソッドはサブクラスでオーバーライドすることができます。標準の run() メソッドは、コンストラクターの target 引数として渡された呼び出し可能オブジェクトを呼び出します。もしコンストラクターに args もしくは kwargs 引数が渡されていれば、呼び出すオブジェクトにこれらの引数を渡します。

Process に渡される args の引数にリストやタプルを使っても、同じ効果が得られます。

以下はプログラム例です:

>>> from multiprocessing import Process
>>> p = Process(target=print, args=[1])
>>> p.run()
1
>>> p = Process(target=print, args=(1,))
>>> p.run()
1

start()

プロセスの処理を開始するためのメソッドです。

各 Process オブジェクトに対し、このメソッドが2回以上呼び出されてはいけません。各プロセスでオブジェクトの run() メソッドを呼び出す準備を行います。

join([timeout])

オプションの引数 timeout が None (デフォルト) の場合、 join() メソッドが呼ばれたプロセスは処理が終了するまでブロックします。 timeout が正の数である場合、最大 timeout 秒ブロックします。プロセスが終了あるいはタイムアウトした場合、メソッドは None を返すことに注意してください。プロセスの exitcode を確認し終了したかどうかを判断してください。

1つのプロセスは何回も join されることができます。

プロセスは自分自身を join することはできません。それはデッドロックを引き起こすことがあるからです。プロセスが start される前に join しようとするとエラーが発生します。

name

プロセスの名前。名前は識別のためだけに使用される文字列です。それ自体には特別な意味はありません。複数のプロセスに同じ名前が与えられても構いません。

最初の名前はコンストラクターによってセットされます。コンストラクターに明示的な名前が渡されない場合、 'Process-N₁:N₂:...:Nk' 形式の名前が構築されます。ここでそれぞれの Nk はその親のN番目の子供です。

is_alive()

プロセスが実行中かを判別します。

おおまかに言って、プロセスオブジェクトは start() メソッドを呼び出してから子プロセス終了までの期間が実行中となります。

daemon

デーモンプロセスであるかのフラグであり、ブール値です。この属性は start() が呼び出される前に設定されている必要があります。

初期値は作成するプロセスから継承します。

あるプロセスが終了するとき、そのプロセスはその子プロセスであるデーモンプロセスすべてを終了させようとします。

デーモンプロセスは子プロセスを作成できないことに注意してください。もし作成できてしまうと、そのデーモンプロセスの親プロセスが終了したときにデーモンプロセスの子プロセスが孤児になってしまう場合があるからです。さらに言えば、デーモンプロセスはUnix デーモンやサービスでは なく 通常のプロセスであり、非デーモンプロセスが終了すると終了されます (そして join されません)。

threading.Thread クラスの API に加えて Process クラスのオブジェクトには以下の属性およびメソッドがあります:

pid

プロセスIDを返します。プロセスの生成前は None が設定されています。

exitcode

The child's exit code. This will be None if the process has not yet terminated.

If the child's run() method returned normally, the exit code will be 0. If it terminated via sys.exit() with an integer argument N, the exit code will be N.

If the child terminated due to an exception not caught within run(), the exit code will be 1. If it was terminated by signal N, the exit code will be the negative value -N.

authkey

プロセスの認証キーです (バイト文字列です)。

multiprocessing モジュールがメインプロセスにより初期化される場合には、 os.urandom() 関数を使用してランダムな値が設定されます。

Process クラスのオブジェクトの作成時にその親プロセスから認証キーを継承します。もしくは authkey に別のバイト文字列を設定することもできます。

詳細は 認証キー を参照してください。

sentinel

プロセスが終了するときに "ready" となるシステムオブジェクトの数値ハンドル。

multiprocessing.connection.wait() を使用していくつかのイベントを同時に wait したい場合はこの値を使うことができます。それ以外の場合は join() を呼ぶ方がより単純です。

On Windows, this is an OS handle usable with the WaitForSingleObject and WaitForMultipleObjects family of API calls. On POSIX, this is a file descriptor usable with primitives from the select module.

Added in version 3.3.

terminate()

Terminate the process. On POSIX this is done using the SIGTERM signal; on Windows TerminateProcess() is used. Note that exit handlers and finally clauses, etc., will not be executed.

このメソッドにより終了するプロセスの子孫プロセスは、終了 しません 。そういった子孫プロセスは単純に孤児になります。

警告

このメソッドの使用時に、関連付けられたプロセスがパイプやキューを使用している場合には、使用中のパイプやキューが破損して他のプロセスから使用できなくなる可能性があります。同様に、プロセスがロックやセマフォなどを取得している場合には、このプロセスが終了してしまうと他のプロセスのデッドロックの原因になるでしょう。

kill()

Same as terminate() but using the SIGKILL signal on POSIX.

Added in version 3.7.

close()

Process オブジェクトを閉じ、関連付けられていたすべてのリソースを開放します。中のプロセスが実行中であった場合、ValueError を送出します。close() が成功した場合、Process オブジェクトの他のメソッドや属性は、ほとんどが ValueError を送出します。

Added in version 3.7.

プロセスオブジェクトが作成したプロセスのみが start(), join(), is_alive(), terminate() と exitcode のメソッドを呼び出すべきです。

以下の例では Process のメソッドの使い方を示しています:

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

exception multiprocessing.ProcessError

すべての multiprocessing 例外の基底クラスです。

exception multiprocessing.BufferTooShort

この例外は Connection.recv_bytes_into() によって発生し、バッファーオブジェクトが小さすぎてメッセージが読み込めないことを示します。

e が BufferTooShort のインスタンスであるとすると、 e.args[0] はそのメッセージをバイト文字列で与えるものです。

exception multiprocessing.AuthenticationError

認証エラーがあった場合に送出されます。

exception multiprocessing.TimeoutError

タイムアウトをサポートするメソッドでタイムアウトが過ぎたときに送出されます。

パイプ (Pipe) とキュー (Queue)

複数のプロセスを使う場合、一般的にはメッセージパッシングをプロセス間通信に使用し、ロックのような同期プリミティブを使用しないようにします。

メッセージのやりとりのために Pipe() (2つのプロセス間の通信用)、もしくはキュー (複数のメッセージ生成プロセス (producer)、消費プロセス (consumer) の実現用) を使うことができます。

Queue, SimpleQueue と JoinableQueue 型は複数プロセスから生成/消費を行う FIFO キューです。これらのキューは標準ライブラリの queue.Queue を模倣しています。 Queue には Python 2.5 の queue.Queue クラスで導入された task_done() と join() メソッドがないことが違う点です。

もし JoinableQueue を使用するなら、キューから削除される各タスクのために JoinableQueue.task_done() を呼び出さなければ なりません 。さもないと、いつか完了していないタスクを数えるためのセマフォがオーバーフローし、例外を発生させるでしょう。

管理オブジェクトを使用することで共有キューを作成できることも覚えておいてください。詳細は マネージャー を参照してください。

注釈

multiprocessing は、タイムアウトを伝えるために、通常の queue.Empty と queue.Full 例外を使用します。それらは multiprocessing の名前空間では利用できないため、queue からインポートする必要があります。

注釈

オブジェクトがキューに追加される際、そのオブジェクトは pickle 化されています。そのため、バックグラウンドのスレッドが後になって下位層のパイプに pickle 化されたデータをフラッシュすることがあります。これにより、少し驚くような結果になりますが、実際に問題になることはないはずです。これが問題になるような状況では、かわりに manager を使ってキューを作成することができるからです。

空のキューの中にオブジェクトを追加した後、キューの empty() メソッドが False を返すまでの間にごくわずかな遅延が起きることがあり、get_nowait() が queue.Empty を発生させることなく制御が呼び出し元に返ってしまうことがあります。

複数のプロセスがオブジェクトをキューに詰めている場合、キューの反対側ではオブジェクトが詰められたのとは違う順序で取得される可能性があります。ただし、同一のプロセスから詰め込まれたオブジェクトは、それらのオブジェクト間では、必ず期待どおりの順序になります。

警告

Queue を利用しようとしている最中にプロセスを Process.terminate() や os.kill() で終了させる場合、キューにあるデータは破損し易くなります。終了した後で他のプロセスがキューを利用しようとすると、例外を発生させる可能性があります。

警告

上述したように、もし子プロセスがキューへ要素を追加するなら (かつ JoinableQueue.cancel_join_thread を使用しないなら) そのプロセスはバッファーされたすべての要素がパイプへフラッシュされるまで終了しません。

これは、そのプロセスを join しようとする場合、キューに追加されたすべての要素が消費されたことが確実でないかぎり、デッドロックを発生させる可能性があることを意味します。似たような現象で、子プロセスが非デーモンプロセスの場合、親プロセスは終了時に非デーモンのすべての子プロセスを join しようとしてハングアップする可能性があります。

マネージャーを使用して作成されたキューではこの問題はありません。詳細は プログラミングガイドライン を参照してください。

プロセス間通信におけるキューの使用例を知りたいなら 使用例 を参照してください。

multiprocessing.Pipe([duplex])

パイプの両端を表す Connection オブジェクトのペア (conn1, conn2) を返します。

duplex が True (デフォルト) ならパイプは双方向性です。duplex が False ならパイプは一方向性で、conn1 はメッセージの受信専用、conn2 はメッセージの送信専用になります。

class multiprocessing.Queue([maxsize])

パイプや2～3個のロック/セマフォを使用して実装されたプロセス共有キューを返します。あるプロセスが最初に要素をキューへ追加するとき、バッファーからパイプの中へオブジェクトを転送する供給スレッドが開始されます。

標準ライブラリの queue モジュールの通常の queue.Empty や queue.Full 例外がタイムアウトを伝えるために送出されます。

Queue は task_done() や join() を除く queue.Queue のすべてのメソッドを実装します。

qsize()

おおよそのキューのサイズを返します。マルチスレッディング/マルチプロセスの特性上、この数値は信用できません。

Note that this may raise NotImplementedError on platforms like macOS where sem_getvalue() is not implemented.

empty()

キューが空っぽなら True を、そうでなければ False を返します。マルチスレッディング/マルチプロセシングの特性上、これは信用できません。

full()

キューがいっぱいなら True を、そうでなければ False を返します。マルチスレッディング/マルチプロセシングの特性上、これは信用できません。

put(obj[, block[, timeout]])

キューの中へ obj を追加します。オプションの引数 block が True (デフォルト) 且つ timeout が None (デフォルト) なら、空きスロットが利用可能になるまで必要であればブロックします。 timeout が正の数なら、最大 timeout 秒ブロックして、その時間内に空きスロットが利用できなかったら queue.Full 例外を発生させます。それ以外 (block が False) で、空きスロットがすぐに利用可能な場合はキューに要素を追加します。そうでなければ queue.Full 例外が発生します(その場合 timeout は無視されます)。

バージョン 3.8 で変更: If the queue is closed, ValueError is raised instead of AssertionError.

put_nowait(obj)

put(obj, False) と等価です。

get([block[, timeout]])

キューから要素を取り出して削除します。オプションの引数 block が True (デフォルト) 且つ timeout が None (デフォルト) なら、要素が取り出せるまで必要であればブロックします。 timeout が正の数なら、最大 timeout 秒ブロックして、その時間内に要素が取り出せなかったら queue.Empty 例外を発生させます。それ以外 (block が False) で、要素がすぐに取り出せる場合は要素を返します。そうでなければ queue.Empty 例外が発生します(その場合 timeout は無視されます)。

バージョン 3.8 で変更: If the queue is closed, ValueError is raised instead of OSError.

get_nowait()

get(False) と等価です。

multiprocessing.Queue は queue.Queue にはない追加メソッドがあります。 これらのメソッドは通常、ほとんどのコードに必要ありません:

close()

カレントプロセスからこのキューへそれ以上データが追加されないことを表します。バックグラウンドスレッドはパイプへバッファーされたすべてのデータをフラッシュするとすぐに終了します。これはキューがガベージコレクトされるときに自動的に呼び出されます。

join_thread()

バックグラウンドスレッドを join します。このメソッドは close() が呼び出された後でのみ使用されます。バッファーされたすべてのデータがパイプへフラッシュされるのを保証するため、バックグラウンドスレッドが終了するまでブロックします。

デフォルトでは、あるプロセスがキューを作成していない場合、終了時にキューのバックグラウンドスレッドを join しようとします。そのプロセスは join_thread() が何もしないように cancel_join_thread() を呼び出すことができます。

cancel_join_thread()

join_thread() がブロッキングするのを防ぎます。特にこれはバックグラウンドスレッドがそのプロセスの終了時に自動的に join されるのを防ぎます。詳細は join_thread() を参照してください。

このメソッドは allow_exit_without_flush() という名前のほうがよかったかもしれません。キューに追加されたデータが失われてしまいがちなため、このメソッドを使う必要はほぼ確実にないでしょう。本当にこれが必要になるのは、キューに追加されたデータを下位層のパイプにフラッシュすることなくカレントプロセスを直ちに終了する必要があり、かつ失われるデータに関心がない場合です。

注釈

このクラスに含まれる機能には、ホストとなるオペレーティングシステム上で動作している共有セマフォ (shared semaphore) を使用しているものがあります。これが使用できない場合には、このクラスが無効になり、 Queue をインスタンス化する時に ImportError が発生します。詳細は bpo-3770 [https://bugs.python.org/issue?@action=redirect&bpo=3770] を参照してください。同様のことが、以下に列挙されている特殊なキューでも成り立ちます。

class multiprocessing.SimpleQueue

単純化された Queue 型です。ロックされた Pipe と非常に似ています。

close()

Close the queue: release internal resources.

A queue must not be used anymore after it is closed. For example, get(), put() and empty() methods must no longer be called.

Added in version 3.9.

empty()

キューが空ならば True を、そうでなければ False を返します。

get()

キューから要素を削除して返します。

put(item)

item をキューに追加します。

class multiprocessing.JoinableQueue([maxsize])

JoinableQueue は Queue のサブクラスであり、 task_done() や join() メソッドが追加されているキューです。

task_done()

以前にキューへ追加されたタスクが完了したことを表します。キューのコンシューマによって使用されます。 タスクをフェッチするために使用されるそれぞれの get() に対して、 後続の task_done() 呼び出しはタスクの処理が完了したことをキューへ伝えます。

もし join() がブロッキング状態なら、 すべての要素が処理されたときに復帰します( task_done() 呼び出しが すべての要素からキュー内へ put() されたと受け取ったことを意味します)。

キューにある要素より多く呼び出された場合 ValueError が発生します。

join()

キューにあるすべてのアイテムが取り出されて処理されるまでブロックします。

キューに要素が追加されると未完了タスク数が増えます。コンシューマがキューの要素が取り出されてすべての処理が完了したことを表す task_done() を呼び出すと数が減ります。 未完了タスク数がゼロになると join() はブロッキングを解除します。

その他

multiprocessing.active_children()

カレントプロセスのすべてのアクティブな子プロセスのリストを返します。

これを呼び出すと "join" してすでに終了しているプロセスには副作用があります。

multiprocessing.cpu_count()

システムの CPU 数を返します。

This number is not equivalent to the number of CPUs the current process can use. The number of usable CPUs can be obtained with len(os.sched_getaffinity(0))

When the number of CPUs cannot be determined a NotImplementedError is raised.

参考

os.cpu_count()

multiprocessing.current_process()

カレントプロセスに対応する Process オブジェクトを返します。

threading.current_thread() とよく似た関数です。

multiprocessing.parent_process()

Return the Process object corresponding to the parent process of the current_process(). For the main process, parent_process will be None.

Added in version 3.8.

multiprocessing.freeze_support()

multiprocessing を使用しているプログラムをフリーズして Windows の実行可能形式を生成するためのサポートを追加します。(py2exe , PyInstaller や cx_Freeze でテストされています。)

メインモジュールの if __name__ == '__main__' の直後にこの関数を呼び出す必要があります。以下に例を示します:

from multiprocessing import Process, freeze_support

def f():
    print('hello world!')

if __name__ == '__main__':
    freeze_support()
    Process(target=f).start()

もし freeze_support() の行がない場合、フリーズされた実行可能形式を実行しようとすると RuntimeError を発生させます。

freeze_support() の呼び出しは Windows 以外の OS では効果がありません。さらに、もしモジュールが Windows の通常の Python インタプリタによって実行されているならば（プログラムがフリーズされていなければ） freeze_support() は効果がありません。

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 'fork', 'spawn' and 'forkserver'. Not all platforms support all methods. See コンテキストと開始方式.

Added in version 3.4.

multiprocessing.get_context(method=None)

multiprocessing モジュールと同じ属性を持つコンテキストオブジェクトを返します。

If method is None then the default context is returned. Otherwise method should be 'fork', 'spawn', 'forkserver'. ValueError is raised if the specified start method is not available. See コンテキストと開始方式.

Added in version 3.4.

multiprocessing.get_start_method(allow_none=False)

開始するプロセスで使用する開始方式名を返します。

開始方式がまだ確定しておらず、allow_none の値が偽の場合、開始方式はデフォルトに確定され、その名前が返されます。開始方式が確定しておらず、allow_none の値が真の場合、 None が返されます。

The return value can be 'fork', 'spawn', 'forkserver' or None. See コンテキストと開始方式.

Added in version 3.4.

バージョン 3.8 で変更: macOS では、 spawn 開始方式がデフォルトになりました。 fork 開始方法は、サブプロセスのクラッシュを引き起こす可能性があるため、安全ではありません。 bpo-33725 [https://bugs.python.org/issue?@action=redirect&bpo=33725] を参照。

multiprocessing.set_executable(executable)

子プロセスを開始するときに、使用する Python インタープリターのパスを設定します。(デフォルトでは sys.executable が使用されます)。コードに組み込むときは、おそらく次のようにする必要があります

set_executable(os.path.join(sys.exec_prefix, 'pythonw.exe'))

子プロセスを作成する前に行ってください。

バージョン 3.4 で変更: Now supported on POSIX when the 'spawn' start method is used.

バージョン 3.11 で変更: path-like object を受け入れるようになりました。

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 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 Pool or starting a Process).

Only meaningful when using the 'forkserver' start method. See コンテキストと開始方式.

Added in version 3.4.

multiprocessing.set_start_method(method, force=False)

Set the method which should be used to start child processes. The method argument can be 'fork', 'spawn' or 'forkserver'. Raises RuntimeError if the start method has already been set and force is not True. If method is None and force is True then the start method is set to None. If method is None and force is False then the context is set to the default context.

これは一度しか呼び出すことができず、その場所もメインモジュールの if __name__ == '__main__' 節内で保護された状態でなければなりません。

See コンテキストと開始方式.

Added in version 3.4.

注釈

multiprocessing には threading.active_count(), threading.enumerate(), threading.settrace(), threading.setprofile(), threading.Timer や threading.local のような関数はありません。

Connection オブジェクト

Connection オブジェクトは pickle でシリアライズ可能なオブジェクトか文字列を送ったり、受け取ったりします。そういったオブジェクトはメッセージ指向の接続ソケットと考えられます。

Connection オブジェクトは通常は Pipe を使用して作成されます。 詳細は リスナーとクライアント も参照してください。

class multiprocessing.connection.Connection

send(obj)

コネクションの相手側へ recv() を使用して読み込むオブジェクトを送ります。

オブジェクトは pickle でシリアライズ可能でなければなりません。 pickle が極端に大きすぎる (OS にも依りますが、およそ 32 MiB+) と、 ValueError 例外が送出されることがあります。

recv()

コネクションの相手側から send() を使用して送られたオブジェクトを返します。 何か受け取るまでブロックします。何も受け取らずにコネクションの相手側でクローズされた場合 EOFError が発生します。

fileno()

コネクションが使用するハンドラーか、ファイル記述子を返します。

close()

コネクションをクローズします。

コネクションがガベージコレクトされるときに自動的に呼び出されます。

poll([timeout])

読み込み可能なデータがあるかどうかを返します。

timeout が指定されていなければすぐに返します。 timeout に数値を指定すると、最大指定した秒数をブロッキングします。 timeout に None を指定するとタイムアウトせずにずっとブロッキングします。

multiprocessing.connection.wait() を使って複数のコネクションオブジェクトを同時にポーリングできることに注意してください。

send_bytes(buffer[, offset[, size]])

bytes-like object から完全なメッセージとしてバイトデータを送ります。

offset が指定されると buffer のその位置からデータが読み込まれます。 size が指定されるとバッファーからその量のデータが読み込まれます。非常に大きなバッファー (OS に依存しますが、およそ 32MiB+) を指定すると、 ValueError 例外が発生するかもしれません。

recv_bytes([maxlength])

コネクションの相手側から送られたバイトデータの完全なメッセージを文字列として返します。何か受け取るまでブロックします。受け取るデータが何も残っておらず、相手側がコネクションを閉じていた場合、 EOFError が送出されます。

maxlength を指定していて、かつメッセージが maxlength より長い場合、 OSError が発生してコネクションからそれ以上読めなくなります。

バージョン 3.3 で変更: この関数は以前は IOError を送出していました。今では OSError の別名です。

recv_bytes_into(buffer[, offset])

コネクションの相手側から送られたバイトデータを buffer に読み込み、メッセージのバイト数を返します。 何か受け取るまでブロックします。何も受け取らずにコネクションの相手側でクローズされた場合 EOFError が発生します。

buffer は書き込み可能な bytes-like object でなければなりません。 offset が与えられたら、その位置からバッファーへメッセージが書き込まれます。 オフセットは buffer バイトよりも小さい正の数でなければなりません。

バッファーがあまりに小さいと BufferTooShort 例外が発生します。 e が例外インスタンスとすると完全なメッセージは e.args[0] で確認できます。

バージョン 3.3 で変更: Connection.send() と Connection.recv() を使用して Connection オブジェクト自体をプロセス間で転送できるようになりました。

Connection objects also now support the context management protocol -- see コンテキストマネージャ型. __enter__() returns the connection object, and __exit__() calls close().

例えば:

>>> 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])

警告

Connection.recv() メソッドは受信したデータを自動的に unpickle 化します。それはメッセージを送ったプロセスが信頼できる場合を除いてセキュリティリスクになります。

そのため Pipe() を使用してコネクションオブジェクトを生成する場合を除いて、何らかの認証処理を実行した後で recv() や send() メソッドのみを使用すべきです。詳細は 認証キー を参照してください。

警告

もしプロセスがパイプの読み込みまたは書き込み中に kill されると、メッセージの境界がどこなのか分からなくなってしまうので、そのパイプ内のデータは破損してしまいがちです。

同期プリミティブ

一般的にマルチプロセスプログラムは、マルチスレッドプログラムほどは同期プリミティブを必要としません。詳細は threading モジュールのドキュメントを参照してください。

マネージャーオブジェクトを使用して同期プリミティブを作成できることも覚えておいてください。詳細は マネージャー を参照してください。

class multiprocessing.Barrier(parties[, action[, timeout]])

バリアーオブジェクト: threading.Barrier のクローンです。

Added in version 3.3.

class multiprocessing.BoundedSemaphore([value])

有限セマフォオブジェクト: threading.BoundedSemaphore の類似物です。

よく似た threading.BoundedSemaphore とは、次の一点だけ異なります。 acquire メソッドの第一引数名は block で、Lock.acquire() と一致しています。

注釈

macOS では sem_getvalue() が実装されていないので Semaphore と区別がつきません。

class multiprocessing.Condition([lock])

状態変数: threading.Condition の別名です。

lock を指定するなら multiprocessing の Lock か RLock オブジェクトにすべきです。

バージョン 3.3 で変更: wait_for() メソッドが追加されました。

class multiprocessing.Event

threading.Event のクローンです。

class multiprocessing.Lock

再帰しないロックオブジェクトで、 threading.Lock 相当のものです。プロセスやスレッドがロックをいったん獲得 (acquire) すると、それに続くほかのプロセスやスレッドが獲得しようとする際、それが解放 (release) されるまではブロックされます。解放はどのプロセス、スレッドからも行えます。スレッドに対して適用される threading.Lock のコンセプトと振る舞いは、特筆すべきものがない限り、プロセスとスレッドに適用される multiprocessing.Lock に引き継がれています。

Lock は実際にはファクトリ関数で、デフォルトコンテキストで初期化された multiprocessing.synchronize.Lock のインスタンスを返すことに注意してください。

Lock は context manager プロトコルをサポートしています。つまり with 文で使うことができます。

acquire(block=True, timeout=None)

ブロックあり、またはブロックなしでロックを獲得します。

引数 block を True (デフォルト) に設定して呼び出した場合、ロックがアンロック状態になるまでブロックします。ブロックから抜けるとそれをロック状態にしてから True を返します。 threading.Lock.acquire() の最初の引数とは名前が違っているので注意してください。

引数 block の値を False にして呼び出すとブロックしません。 現在ロック状態であれば、直ちに False を返します。それ以外の場合には、ロックをロック状態にして True を返します。

timeout として正の浮動小数点数を与えて呼び出すと、ロックが獲得できない限り、指定された秒数だけブロックします。 timeout 値に負数を与えると、ゼロを与えた場合と同じになります。 timeout 値の None (デフォルト) を与えると、無限にブロックします。 timeout 引数の負数と None の扱いは、 threading.Lock.acquire() に実装された動作と異なるので注意してください。 block が False の場合、 timeout は実際的な意味を持たなくなるので無視されます。ロックを獲得した場合は True 、タイムアウトした場合は False で戻ります。

release()

ロックを解放します。これはロックを獲得したプロセスやスレッドだけでなく、任意のプロセスやスレッドから呼ぶことができます。

threading.Lock.release() と同じように振舞いますが、ロックされていない場合に呼び出すと ValueError となる点だけが違います。

class multiprocessing.RLock

再帰ロックオブジェクトで、 threading.RLock 相当のものです。再帰ロックオブジェクトはそれを獲得 (acquire) したプロセスやスレッドが解放 (release) しなければなりません。プロセスやスレッドがロックをいったん獲得すると、同じプロセスやスレッドはブロックされずに再度獲得出来ます。そのプロセスやスレッドは獲得した回数ぶん解放しなければなりません。

RLock は実際にはファクトリ関数で、デフォルトコンテキストで初期化された multiprocessing.synchronize.Lock のインスタンスを返すことに注意してください。

RLock は context manager プロトコルをサポートしています。つまり with 文で使うことができます。

acquire(block=True, timeout=None)

ブロックあり、またはブロックなしでロックを獲得します。

block 引数を True にして呼び出した場合、ロックが既にカレントプロセスもしくはカレントスレッドが既に所有していない限りは、アンロック状態 (どのプロセス、スレッドも所有していない状態) になるまでブロックします。ブロックから抜けるとカレントプロセスもしくはカレントスレッドが (既に持っていなければ) 所有権を得て、再帰レベルをインクリメントし、 True で戻ります。 threading.RLock.acquire() の実装とはこの最初の引数の振る舞いが、その名前自身を始めとしていくつか違うので注意してください。

block 引数を False にして呼び出した場合、ブロックしません。ロックが他のプロセスもしくはスレッドにより獲得済み (つまり所有されている) であれば、カレントプロセスまたはカレントスレッドは所有権を得ず、再帰レベルも変更せずに、 False で戻ります。ロックがアンロック状態の場合、カレントプロセスもしくはカレントスレッドは所有権を得て再帰レベルがインクリメントされ、 True で戻ります。(---訳注: block の True/False 関係なくここでの説明では「所有権を持っている場合の2度目以降の aquire」の説明が欠けています。2度目以降の acquire では再帰レベルがインクリメントされて即座に返ります。全体読めばわかるとは思いますが一応。---)

timeout 引数の使い方と振る舞いは Lock.acquire() と同じです。 timeout 引数の振る舞いがいくつかの点で threading.RLock.acquire() と異なるので注意してください。

release()

再帰レベルをデクリメントしてロックを解放します。デクリメント後に再帰レベルがゼロになった場合、ロックの状態をアンロック (いかなるプロセス、いかなるスレッドにも所有されていない状態) にリセットし、ロックの状態がアンロックになるのを待ってブロックしているプロセスもしくはスレッドがある場合にはその中のただ一つだけが処理を進行できるようにします。デクリメント後も再帰レベルがゼロでない場合、ロックの状態はロックのままで、呼び出し側のプロセスもしくはスレッドに所有されたままになります。

このメソッドは呼び出しプロセスあるいはスレッドがロックを所有している場合に限り呼び出してください。所有者でないプロセスもしくはスレッドによって呼ばれるか、あるいはアンロック (未所有) 状態で呼ばれた場合、 AssertionError が送出されます。同じ状況での threading.RLock.release() 実装とは例外の型が異なるので注意してください。

class multiprocessing.Semaphore([value])

セマフォオブジェクト: threading.Semaphore のクローンです。

よく似た threading.BoundedSemaphore とは、次の一点だけ異なります。 acquire メソッドの第一引数名は block で、Lock.acquire() と一致しています。

注釈

macOS では sem_timedwait がサポートされていないので、acquire() にタイムアウトを与えて呼ぶと、ループ内でスリープすることでこの関数がエミュレートされます。

注釈

メインスレッドが BoundedSemaphore.acquire(), Lock.acquire(), RLock.acquire(), Semaphore.acquire(), Condition.acquire() 又は Condition.wait() を呼び出してブロッキング状態のときに Ctrl-C で生成される SIGINT シグナルを受け取ると、その呼び出しはすぐに中断されて KeyboardInterrupt が発生します。

これは同等のブロッキング呼び出しが実行中のときに SIGINT が無視される threading の振る舞いとは違っています。

注釈

このパッケージに含まれる機能には、ホストとなるオペレーティングシステム上で動作している共有セマフォを使用しているものがあります。これが使用できない場合には、multiprocessing.synchronize モジュールが無効になり、このモジュールのインポート時に ImportError が発生します。詳細は bpo-3770 [https://bugs.python.org/issue?@action=redirect&bpo=3770] を参照してください。

共有 ctypes オブジェクト

子プロセスにより継承される共有メモリを使用する共有オブジェクトを作成することができます。

multiprocessing.Value(typecode_or_type, *args, lock=True)

共有メモリから割り当てられた ctypes オブジェクトを返します。 デフォルトでは、返り値は実際のオブジェクトの同期ラッパーです。オブジェクトそれ自身は、 Value の value 属性によってアクセスできます。

typecode_or_type は返されるオブジェクトの型を決めます。それは ctypes の型か array モジュールで使用されるような1文字の型コードかのどちらか一方です。 *args は型のコンストラクターへ渡されます。

lock が True (デフォルト) なら、値へ同期アクセスするために新たに再帰的なロックオブジェクトが作成されます。 lock が Lock か RLock なら値への同期アクセスに使用されます。 lock が False なら、返されたオブジェクトへのアクセスはロックにより自動的に保護されません。そのため、必ずしも "プロセスセーフ" ではありません。

+= のような演算は、読み込みと書き込みを含むためアトミックでありません。このため、たとえば自動的に共有の値を増加させたい場合、以下のようにするのでは不十分です

counter.value += 1

関連するロックが再帰的 (それがデフォルトです) なら、かわりに次のようにします

with counter.get_lock():
    counter.value += 1

lock はキーワード専用引数であることに注意してください。

multiprocessing.Array(typecode_or_type, size_or_initializer, *, lock=True)

共有メモリから割り当てられた ctypes 配列を返します。デフォルトでは、返り値は実際の配列の同期ラッパーです。

typecode_or_type は返される配列の要素の型を決めます。それは ctypes の型か array モジュールで使用されるような1文字の型コードかのどちらか一方です。 size_or_initializer が整数なら、配列の長さを決定し、その配列はゼロで初期化されます。別の使用方法として size_or_initializer は配列の初期化に使用されるシーケンスになり、そのシーケンス長が配列の長さを決定します。

lock が True (デフォルト) なら、値へ同期アクセスするために新たなロックオブジェクトが作成されます。 lock が Lock か RLock なら値への同期アクセスに使用されます。 lock が False なら、返されたオブジェクトへのアクセスはロックにより自動的に保護されません。そのため、必ずしも "プロセスセーフ" ではありません。

lock はキーワード引数としてのみ利用可能なことに注意してください。

ctypes.c_char の配列は文字列を格納して取り出せる value と raw 属性を持っていることを覚えておいてください。

multiprocessing.sharedctypes モジュール

multiprocessing.sharedctypes モジュールは子プロセスに継承される共有メモリの ctypes オブジェクトを割り当てる関数を提供します。

注釈

共有メモリのポインターを格納することは可能ではありますが、特定プロセスのアドレス空間の位置を参照するということを覚えておいてください。しかし、そのポインターは別のプロセスのコンテキストにおいて無効になる確率が高いです。そして、別のプロセスからそのポインターを逆参照しようとするとクラッシュを引き起こす可能性があります。

multiprocessing.sharedctypes.RawArray(typecode_or_type, size_or_initializer)

共有メモリから割り当てられた ctypes 配列を返します。

typecode_or_type は返される配列の要素の型を決めます。それは ctypes の型か array モジュールで使用されるような1文字の型コードのどちらか一方です。 size_or_initializer が整数なら、それが配列の長さになり、その配列はゼロで初期化されます。別の使用方法として size_or_initializer には配列の初期化に使用されるシーケンスを設定することもでき、その場合はシーケンスの長さが配列の長さになります。

要素を取得したり設定したりすることは潜在的に非アトミックであることに注意してください。ロックを使用して自動的に同期化されたアクセスを保証するには Array() を使用してください。

multiprocessing.sharedctypes.RawValue(typecode_or_type, *args)

共有メモリから割り当てられた ctypes オブジェクトを返します。

typecode_or_type は返されるオブジェクトの型を決めます。それは ctypes の型か array モジュールで使用されるような1文字の型コードかのどちらか一方です。 *args は型のコンストラクターへ渡されます。

値を取得したり設定したりすることは潜在的に非アトミックであることに注意してください。ロックを使用して自動的に同期化されたアクセスを保証するには Value() を使用してください。

ctypes.c_char の配列は文字列を格納して取り出せる value と raw 属性を持っていることを覚えておいてください。詳細は ctypes を参照してください。

multiprocessing.sharedctypes.Array(typecode_or_type, size_or_initializer, *, lock=True)

RawArray() と同様ですが、 lock の値によっては ctypes 配列をそのまま返す代わりに、プロセスセーフな同期ラッパーが返されます。

lock が True (デフォルト) なら、値へ同期アクセスするために新たな ロックオブジェクトが作成されます。 lock が Lock か RLock なら値への同期アクセスに使用されます。 lock が False なら、返された オブジェクトへのアクセスはロックにより自動的に保護されません。 そのため、必ずしも "プロセスセーフ" ではありません。

lock はキーワード専用引数であることに注意してください。

multiprocessing.sharedctypes.Value(typecode_or_type, *args, lock=True)

RawValue() と同様ですが、 lock の値によっては ctypes オブジェクトをそのまま返す代わりに、プロセスセーフな同期ラッパーが返されます。

lock が True (デフォルト) なら、値へ同期アクセスするために新たな ロックオブジェクトが作成されます。 lock が Lock か RLock なら値への同期アクセスに使用されます。 lock が False なら、返された オブジェクトへのアクセスはロックにより自動的に保護されません。 そのため、必ずしも "プロセスセーフ" ではありません。

lock はキーワード専用引数であることに注意してください。

multiprocessing.sharedctypes.copy(obj)

共有メモリから割り当てられた ctypes オブジェクト obj をコピーしたオブジェクトを返します。

multiprocessing.sharedctypes.synchronized(obj[, lock])

同期アクセスに lock を使用する ctypes オブジェクトのためにプロセスセーフなラッパーオブジェクトを返します。 lock が None (デフォルト) なら、 multiprocessing.RLock オブジェクトが自動的に作成されます。

同期ラッパーがラップするオブジェクトに加えて2つのメソッドがあります。 get_obj() はラップされたオブジェクトを返します。 get_lock() は同期のために使用されるロックオブジェクトを返します。

ラッパー経由で ctypes オブジェクトにアクセスすることは raw ctypes オブジェクトへアクセスするよりずっと遅くなることに注意してください。

バージョン 3.5 で変更: synchronized オブジェクトは コンテキストマネージャ プロトコルをサポートしています。

次の表は通常の ctypes 構文で共有メモリから共有 ctypes オブジェクトを作成するための構文を比較します。 (MyStruct テーブル内には ctypes.Structure のサブクラスがあります。)

ctypes

type を使用する sharedctypes

typecode を使用する sharedctypes

c_double(2.4)

RawValue(c_double, 2.4)

RawValue('d', 2.4)

MyStruct(4, 6)

RawValue(MyStruct, 4, 6)

(c_short * 7)()

RawArray(c_short, 7)

RawArray('h', 7)

(c_int * 3)(9, 2, 8)

RawArray(c_int, (9, 2, 8))

RawArray('i', (9, 2, 8))

以下に子プロセスが多くの ctypes オブジェクトを変更する例を紹介します:

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])

結果は以下のように表示されます

49
0.1111111111111111
HELLO WORLD
[(3.515625, 39.0625), (33.0625, 4.0), (5.640625, 90.25)]

マネージャー

マネージャーは異なるプロセス間で共有されるデータの作成方法を提供します。これには別のマシン上で走るプロセス間のネットワーク越しの共有も含まれます。マネージャーオブジェクトは 共有オブジェクト を管理するサーバープロセスを制御します。他のプロセスはプロキシ経由で共有オブジェクトへアクセスすることができます。

multiprocessing.Manager()

プロセス間でオブジェクトを共有するために使用される SyncManager オブジェクトを返します。返されたマネージャーオブジェクトは生成される子プロセスに対応付けられ、共有オブジェクトを作成するメソッドや、共有オブジェクトに対応するプロキシを返すメソッドを持ちます。

マネージャープロセスは親プロセスが終了するか、ガベージコレクトされると停止します。マネージャークラスは multiprocessing.managers モジュールで定義されています:

class multiprocessing.managers.BaseManager(address=None, authkey=None, serializer='pickle', ctx=None, *, shutdown_timeout=1.0)

BaseManager オブジェクトを作成します。

作成後、start() または get_server().serve_forever() を呼び出して、マネージャーオブジェクトが、開始されたマネージャープロセスを確実に参照するようにしてください。

address はマネージャープロセスが新たなコネクションを待ち受けるアドレスです。address が None の場合、任意のアドレスが設定されます。

authkey はサーバープロセスへ接続しようとするコネクションの正当性を検証するために 使用される認証キーです。authkey が None の場合 current_process().authkey が使用されます。authkey を使用する場合はバイト文字列でなければなりません。

serializer must be 'pickle' (use pickle serialization) or 'xmlrpclib' (use xmlrpc.client serialization).

ctx is a context object, or None (use the current context). See the get_context() function.

shutdown_timeout is a timeout in seconds used to wait until the process used by the manager completes in the 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 パラメータを追加しました。

start([initializer[, initargs]])

マネージャーを開始するためにサブプロセスを開始します。initializer が None でなければ、サブプロセスは開始時に initializer(*initargs) を呼び出します。

get_server()

マネージャーの制御下にある実際のサーバーを表す Server オブジェクトを返します。 Server オブジェクトは serve_forever() メソッドをサポートします:

>>> from multiprocessing.managers import BaseManager
>>> manager = BaseManager(address=('', 50000), authkey=b'abc')
>>> server = manager.get_server()
>>> server.serve_forever()

Server はさらに address 属性も持っています。

connect()

ローカルからリモートのマネージャーオブジェクトへ接続します:

>>> from multiprocessing.managers import BaseManager
>>> m = BaseManager(address=('127.0.0.1', 50000), authkey=b'abc')
>>> m.connect()

shutdown()

マネージャーが使用するプロセスを停止します。これはサーバープロセスを開始するために start() が使用された場合のみ有効です。

これは複数回呼び出すことができます。

register(typeid[, callable[, proxytype[, exposed[, method_to_typeid[, create_method]]]]])

マネージャークラスで呼び出し可能オブジェクト(callable)や型を登録するために使用されるクラスメソッドです。

typeid は特に共有オブジェクトの型を識別するために使用される "型識別子" です。これは文字列でなければなりません。

callable はこの型識別子のオブジェクトを作成するために使用される呼び出し可能オブジェクトです。マネージャーインスタンスが connect() メソッドを使ってサーバーに接続されているか、 create_method 引数が False の場合は、 None でも構いません。

proxytype はこの typeid で共有オブジェクトのプロキシを作成するために使用される BaseProxy のサブクラスです。 None の場合、プロキシクラスは自動的に作成されます。

exposed は BaseProxy._callmethod() を使用したアクセスが許されるべき typeid をプロキシするメソッド名のシーケンスを指定するために使用されます (exposed が None の場合 proxytype._exposed_ が存在すればそれが代わりに使用されます)。exposed リストが指定されない場合、共有オブジェクトのすべての "パブリックメソッド" がアクセス可能になります。 (ここでいう "パブリックメソッド" とは __call__() メソッドを持つものと名前が '_' で始まらないあらゆる属性を意味します。)

method_to_typeid はプロキシが返す exposed メソッドの返り値の型を指定するために使用されるマッピングで、メソッド名を typeid 文字列にマップします。 (method_to_typeid が None の場合 proxytype._method_to_typeid_ が存在すれば、それが代わりに使用されます。) メソッド名がこのマッピングのキーではないか、マッピングが None の場合、そのメソッドによって返されるオブジェクトが値として (by value) コピーされます。

create_method は、共有オブジェクトを作成し、それに対するプロキシを返すようサーバープロセスに伝える、名前 typeid のメソッドを作成するかを決定します。デフォルトでは True です。

BaseManager インスタンスも読み出し専用属性を1つ持っています:

address

マネージャーが使用するアドレスです。

バージョン 3.3 で変更: マネージャーオブジェクトはコンテキストマネージメント・プロトコルをサポートします -- コンテキストマネージャ型 を参照してください。 __enter__() は (まだ開始していない場合) サーバープロセスを開始してから、マネージャーオブジェクトを返します。 __exit__() は shutdown() を呼び出します。

旧バージョンでは、 __enter__() はマネージャーのサーバープロセスがまだ開始していなかった場合でもプロセスを開始しませんでした。

class multiprocessing.managers.SyncManager

プロセス間の同期のために使用される BaseManager のサブクラスです。 multiprocessing.Manager() はこの型のオブジェクトを返します。

Its methods create and return Proxy オブジェクト for a number of commonly used data types to be synchronized across processes. This notably includes shared lists and dictionaries.

Barrier(parties[, action[, timeout]])

共有 threading.Barrier オブジェクトを作成して、そのプロキシを返します。

Added in version 3.3.

BoundedSemaphore([value])

共有 threading.BoundedSemaphore オブジェクトを作成して、そのプロキシを返します。

Condition([lock])

共有 threading.Condition オブジェクトを作成して、そのプロキシを返します。

lock が提供される場合 threading.Lock か threading.RLock オブジェクトのためのプロキシになります。

バージョン 3.3 で変更: wait_for() メソッドが追加されました。

Event()

共有 threading.Event オブジェクトを作成して、そのプロキシを返します。

Lock()

共有 threading.Lock オブジェクトを作成して、そのプロキシを返します。

Namespace()

共有 Namespace オブジェクトを作成して、そのプロキシを返します。

Queue([maxsize])

共有 queue.Queue オブジェクトを作成して、そのプロキシを返します。

RLock()

共有 threading.RLock オブジェクトを作成して、そのプロキシを返します。

Semaphore([value])

共有 threading.Semaphore オブジェクトを作成して、そのプロキシを返します。

Array(typecode, sequence)

配列を作成して、そのプロキシを返します。

Value(typecode, value)

書き込み可能な value 属性を作成して、そのプロキシを返します。

dict()

dict(mapping)

dict(sequence)

共有 dict オブジェクトを作成して、そのプロキシを返します。

list()

list(sequence)

共有 list オブジェクトを作成して、そのプロキシを返します。

バージョン 3.6 で変更: 共有オブジェクトは入れ子もできます。例えば、共有リストのような共有コンテナオブジェクトは、 SyncManager がまとめて管理し同期を取っている他の共有オブジェクトを保持できます。

class multiprocessing.managers.Namespace

SyncManager に登録することのできる型です。

Namespace オブジェクトにはパブリックなメソッドはありませんが、書き込み可能な属性を持ちます。そのオブジェクト表現はその属性の値を表示します。

しかし、Namespace オブジェクトのためにプロキシを使用するとき '_' が先頭に付く属性はプロキシの属性になり、参照対象の属性にはなりません:

>>> 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')

カスタマイズされたマネージャー

独自のマネージャーを作成するには、BaseManager のサブクラスを作成して、 マネージャークラスで呼び出し可能なオブジェクトか新たな型を登録するために register() クラスメソッドを使用します。例えば:

from multiprocessing.managers import BaseManager

class MathsClass:
    def add(self, x, y):
        return x + y
    def mul(self, x, y):
        return x * y

class MyManager(BaseManager):
    pass

MyManager.register('Maths', MathsClass)

if __name__ == '__main__':
    with MyManager() as manager:
        maths = manager.Maths()
        print(maths.add(4, 3))         # prints 7
        print(maths.mul(7, 8))         # prints 56

リモートマネージャーを使用する

あるマシン上でマネージャーサーバーを実行して、他のマシンからそのサーバーを使用するクライアントを持つことができます(ファイアウォールを通過できることが前提)。

次のコマンドを実行することでリモートクライアントからアクセスを受け付ける1つの共有キューのためにサーバーを作成します:

>>> 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=('', 50000), authkey=b'abracadabra')
>>> s = m.get_server()
>>> s.serve_forever()

あるクライアントからサーバーへのアクセスは次のようになります:

>>> 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')

別のクライアントもそれを使用することができます:

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

ローカルプロセスもそのキューへアクセスすることができます。クライアント上で上述のコードを使用してアクセスします:

>>> 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=('', 50000), authkey=b'abracadabra')
>>> s = m.get_server()
>>> s.serve_forever()

Proxy オブジェクト

プロキシは別のプロセスで(おそらく)有効な共有オブジェクトを 参照する オブジェクトです。共有オブジェクトはプロキシの 参照対象 になるということができます。複数のプロキシオブジェクトが同じ参照対象を持つ可能性もあります。

プロキシオブジェクトはその参照対象の対応するメソッドを呼び出すメソッドを持ちます (そうは言っても、参照対象のすべてのメソッドが必ずしもプロキシ経由で利用可能なわけではありません)。この方法で、プロキシオブジェクトはまるでその参照先と同じように使えます:

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

プロキシに str() を適用すると参照対象のオブジェクト表現を返すのに対して、 repr() を適用するとプロキシのオブジェクト表現を返すことに注意してください。

プロキシオブジェクトの重要な機能は pickle 化ができることで、これによりプロセス間での受け渡しができます。そのため、参照対象が Proxy オブジェクト を持てます。これによって管理されたリスト、辞書、その他 Proxy オブジェクト をネストできます:

>>> 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']

同様に、辞書とリストのプロキシも他のプロキシの内部に入れてネストできます:

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

(プロキシでない) 標準の list オブジェクトや dict オブジェクトが参照対象に含まれていた場合、それらの可変な値の変更はマネージャーからは伝搬されません。というのも、プロキシには参照対象の中に含まれる値がいつ変更されたかを知る術が無いのです。しかし、コンテナプロキシに値を保存する (これはプロキシオブジェクトの __setitem__ を起動します) 場合はマネージャーを通して変更が伝搬され、その要素を実際に変更するために、コンテナプロキシに変更後の値が再代入されます:

# 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

This approach is perhaps less convenient than employing nested Proxy オブジェクト for most use cases but also demonstrates a level of control over the synchronization.

注釈

multiprocessing のプロキシ型は値による比較に対して何もサポートしません。そのため、例えば以下のようになります:

>>> manager.list([1,2,3]) == [1,2,3]
False

比較を行いたいときは参照対象のコピーを使用してください。

class multiprocessing.managers.BaseProxy

プロキシオブジェクトは BaseProxy のサブクラスのインスタンスです。

_callmethod(methodname[, args[, kwds]])

プロキシの参照対象のメソッドの実行結果を返します。

proxy がプロキシで、プロキシ内の参照対象が obj ならこの式

proxy._callmethod(methodname, args, kwds)

はこの式を評価します

getattr(obj, methodname)(*args, **kwds)

(マネージャープロセス内の)。

返される値はその呼び出し結果のコピーか、新たな共有オブジェクトに対するプロキシになります。詳細は BaseManager.register() の method_to_typeid 引数のドキュメントを参照してください。

その呼び出しによって例外が発生した場合、_callmethod() によってその例外は再送出されます。他の例外がマネージャープロセスで発生したなら、RemoteError 例外に変換されたものが _callmethod() によって送出されます。

特に methodname が 公開 されていない場合は例外が発生することに注意してください。

_callmethod() の使用例になります:

>>> l = manager.list(range(10))
>>> l._callmethod('__len__')
10
>>> l._callmethod('__getitem__', (slice(2, 7),)) # equivalent to l[2:7]
[2, 3, 4, 5, 6]
>>> l._callmethod('__getitem__', (20,))          # equivalent to l[20]
Traceback (most recent call last):
...
IndexError: list index out of range

_getvalue()

参照対象のコピーを返します。

参照対象が unpickle 化できるなら例外を発生します。

__repr__()

プロキシオブジェクトのオブジェクト表現を返します。

__str__()

参照対象のオブジェクト表現を返します。

クリーンアップ

プロキシオブジェクトは弱参照(weakref)コールバックを使用します。プロキシオブジェクトがガベージコレクトされるときにその参照対象が所有するマネージャーからその登録を取り消せるようにするためです。

共有オブジェクトはプロキシが参照しなくなったときにマネージャープロセスから削除されます。

プロセスプール

Pool クラスでタスクを実行するプロセスのプールを作成することができます。

class multiprocessing.pool.Pool([processes[, initializer[, initargs[, maxtasksperchild[, context]]]]])

プロセスプールオブジェクトは、ジョブを送り込めるワーカープロセスのプールを制御します。タイムアウトやコールバックのある非同期の実行をサポートし、並列 map 実装を持ちます。

processes is the number of worker processes to use. If processes is None then the number returned by os.cpu_count() is used.

initializer が None ではない場合、各ワーカープロセスは開始時に initializer(*initargs) を呼び出します。

maxtasksperchild は、ワーカープロセスが exit して新たなワーカープロセスと置き替えられるまでの間に、ワーカープロセスが完了することのできるタスクの数です。この設定により未利用のリソースが解放されるようなります。デフォルトの maxtasksperchild は None で、これはワーカープロセスがプールと同じ期間だけ生き続けるということを意味します。

context はワーカープロセスを開始するために使用されるコンテキストの指定に使用できます。通常プールは関数 multiprocessing.Pool() かコンテキストオブジェクトの Pool() メソッドを使用して作成されます。どちらの場合でも context は適切に設定されます。

プールオブジェクトのメソッドは、そのプールを作成したプロセスのみが呼び出すべきです。

警告

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 close() and 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 object.__del__() for more information).

バージョン 3.2 で変更: Added the maxtasksperchild parameter.

バージョン 3.4 で変更: context パラメータを追加しました。

注釈

Pool 中のワーカープロセスは、典型的にはプールのワークキューの存続期間とちょうど同じだけ生き続けます。ワーカーに確保されたリソースを解放するために (Apache, mod_wsgi, などのような) 他のシステムによく見られるパターンは、プール内のワーカーが設定された量だけの仕事を完了したら exit とクリーンアップを行い、古いプロセスを置き換えるために新しいプロセスを生成するというものです。 Pool の maxtasksperchild 引数は、この能力をエンドユーザーに提供します。

apply(func[, args[, kwds]])

引数 args とキーワード引数 kwds を伴って func を呼びます。結果が準備できるまでブロックします。このブロックがあるため、 apply_async() の方が並行作業により適しています。加えて、 func は、プール内の1つのワーカーだけで実行されます。

apply_async(func[, args[, kwds[, callback[, error_callback]]]])

apply() メソッドの派生版で AsyncResult オブジェクトを返します。

callback が指定された場合、それは単一の引数を受け取る呼び出し可能オブジェクトでなければなりません。結果を返せるようになったときに callback が結果オブジェクトに対して適用されます。ただし呼び出しが失敗した場合は、代わりに error_callback が適用されます。

error_callback が指定された場合、それは単一の引数を受け取る呼び出し可能オブジェクトでなければなりません。対象の関数が失敗した場合、例外インスタンスを伴って error_callback が呼ばれます。

コールバックは直ちに完了すべきです。なぜなら、そうしなければ、結果を扱うスレッドがブロックするからです。

map(func, iterable[, chunksize])

map() 組み込み関数の並列版です (iterable な引数を1つだけサポートするという違いはあります。もしも複数のイテラブルを使いたいのならば starmap() を参照)。結果が出るまでブロックします。

このメソッドはイテラブルをいくつものチャンクに分割し、プロセスプールにそれぞれ独立したタスクとして送ります。(概算の) チャンクサイズは chunksize を正の整数に設定することで指定できます。

Note that it may cause high memory usage for very long iterables. Consider using imap() or imap_unordered() with explicit chunksize option for better efficiency.

map_async(func, iterable[, chunksize[, callback[, error_callback]]])

map() メソッドの派生版で AsyncResult オブジェクトを返します。

callback が指定された場合、それは単一の引数を受け取る呼び出し可能オブジェクトでなければなりません。結果を返せるようになったときに callback が結果オブジェクトに対して適用されます。ただし呼び出しが失敗した場合は、代わりに error_callback が適用されます。

error_callback が指定された場合、それは単一の引数を受け取る呼び出し可能オブジェクトでなければなりません。対象の関数が失敗した場合、例外インスタンスを伴って error_callback が呼ばれます。

コールバックは直ちに完了すべきです。なぜなら、そうしなければ、結果を扱うスレッドがブロックするからです。

imap(func, iterable[, chunksize])

map() の遅延評価版です。

chunksize 引数は map() メソッドで使用されるものと同じです。 引数 iterable がとても長いなら chunksize に大きな値を指定して使用する方がデフォルト値の 1 を使用するよりもジョブの完了が かなり 速くなります。

また chunksize が 1 の場合 imap() メソッドが返すイテレーターの next() メソッドはオプションで timeout パラメーターを持ちます。 next(timeout) は、その結果が timeout 秒以内に返されないときに multiprocessing.TimeoutError を発生させます。

imap_unordered(func, iterable[, chunksize])

イテレーターが返す結果の順番が任意の順番で良いと見なされることを除けば imap() と同じです。 (ワーカープロセスが1つしかない場合のみ "正しい" 順番になることが保証されます。)

starmap(func, iterable[, chunksize])

iterable の要素が、引数として unpack されるイテレート可能オブジェクトであると期待される以外は、 map() と似ています。

そのため、iterable が [(1,2), (3, 4)] なら、結果は [func(1,2), func(3,4)] になります。

Added in version 3.3.

starmap_async(func, iterable[, chunksize[, callback[, error_callback]]])

starmap() と map_async() の組み合わせです。 イテレート可能オブジェクトの iterable をイテレートして、 unpack したイテレート可能オブジェクトを伴って func を呼び出します。結果オブジェクトを返します。

Added in version 3.3.

close()

これ以上プールでタスクが実行されないようにします。すべてのタスクが完了した後でワーカープロセスが終了します。

terminate()

実行中の処理を完了させずにワーカープロセスをすぐに停止します。プールオブジェクトがガベージコレクトされるときに terminate() が呼び出されます。

join()

ワーカープロセスが終了するのを待ちます。 join() を使用する前に close() か terminate() を呼び出さなければなりません。

バージョン 3.3 で変更: Pool オブジェクトがコンテキストマネージメント・プロトコルをサポートするようになりました。 -- コンテキストマネージャ型 を参照してください。 __enter__() は Pool オブジェクトを返します。また __exit__() は terminate() を呼び出します。

class multiprocessing.pool.AsyncResult

Pool.apply_async() や Pool.map_async() で返される結果のクラスです。

get([timeout])

結果を受け取ったときに返します。 timeout が None ではなくて、その結果が timeout 秒以内に受け取れない場合 multiprocessing.TimeoutError が発生します。リモートの呼び出しが例外を発生させる場合、その例外は get() が再発生させます。

wait([timeout])

その結果が有効になるか timeout 秒経つまで待ちます。

ready()

その呼び出しが完了しているかどうかを返します。

successful()

その呼び出しが例外を発生させることなく完了したかどうかを返します。その結果が返せる状態でない場合 ValueError が発生します。

バージョン 3.7 で変更: If the result is not ready, ValueError is raised instead of AssertionError.

次の例はプールの使用例を紹介します:

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

リスナーとクライアント

通常、プロセス間でメッセージを渡すにはキューを使用するか Pipe() が返す Connection オブジェクトを使用します。

しかし multiprocessing.connection モジュールにはさらに柔軟な仕組みがあります。 このモジュールは、基本的にはソケットもしくは Windows の名前付きパイプを扱う高レベルのメッセージ指向 API を提供します。また、 hmac モジュールを使用した ダイジェスト認証 や同時の複数接続のポーリングもサポートします。

multiprocessing.connection.deliver_challenge(connection, authkey)

ランダム生成したメッセージをコネクションの相手側へ送信して応答を待ちます。

その応答がキーとして authkey を使用するメッセージのダイジェストと一致する場合、 コネクションの相手側へ歓迎メッセージを送信します。 そうでなければ AuthenticationError を発生させます。

multiprocessing.connection.answer_challenge(connection, authkey)

メッセージを受信して、そのキーとして authkey を使用するメッセージのダイジェストを計算し、ダイジェストを送り返します。

歓迎メッセージを受け取れない場合 AuthenticationError が発生します。

multiprocessing.connection.Client(address[, family[, authkey]])

address で渡したアドレスを使用するリスナーに対してコネクションを確立しようとして Connection を返します。

コネクション種別は family 引数で決定しますが、一般的には address のフォーマットから推測できるので、これは指定されません。 (アドレスフォーマット を参照してください)

If authkey is given and not 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 None. AuthenticationError is raised if authentication fails. See 認証キー.

class multiprocessing.connection.Listener([address[, family[, backlog[, authkey]]]])

コネクションを '待ち受ける' 束縛されたソケットか Windows の名前付きパイプのラッパーです。

address はリスナーオブジェクトの束縛されたソケットか名前付きパイプが使用するアドレスです。

注釈

'0.0.0.0' のアドレスを使用する場合、Windows 上の終点へ接続することができません。終点へ接続したい場合は '127.0.0.1' を使用すべきです。

family は使用するソケット(名前付きパイプ)の種別です。これは 'AF_INET' (TCP ソケット), 'AF_UNIX' (Unix ドメインソケット) または 'AF_PIPE' (Windows 名前付きパイプ) という文字列のどれか1つになります。これらのうち 'AF_INET' のみが利用可能であることが保証されています。 family が None の場合 address のフォーマットから推測されたものが使用されます。 address も None の場合はデフォルトが選択されます。詳細は アドレスフォーマット を参照してください。 family が 'AF_UNIX' で address が None の場合 tempfile.mkstemp() を使用して作成されたプライベートな一時ディレクトリにソケットが作成されます。

リスナーオブジェクトがソケットを使用する場合、ソケットに束縛されるときに backlog (デフォルトでは1つ) がソケットの listen() メソッドに対して渡されます。

If authkey is given and not 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 None. AuthenticationError is raised if authentication fails. See 認証キー.

accept()

リスナーオブジェクトの名前付きパイプか束縛されたソケット上でコネクションを 受け付けて Connection オブジェクトを返します。 認証が失敗した場合 AuthenticationError が発生します。

close()

リスナーオブジェクトの名前付きパイプか束縛されたソケットをクローズします。これはリスナーがガベージコレクトされるときに自動的に呼ばれます。そうは言っても、明示的に close() を呼び出す方が望ましいです。

リスナーオブジェクトは次の読み出し専用属性を持っています:

address

リスナーオブジェクトが使用中のアドレスです。

last_accepted

最後にコネクションを受け付けたアドレスです。有効なアドレスがない場合は None になります。

バージョン 3.3 で変更: Listener オブジェクトがコンテキストマネージメント・プロトコルをサポートするようになりました。 -- コンテキストマネージャ型 を参照してください。 __enter__() はリスナーオブジェクトを返します。また __exit__() は close() を呼び出します。

multiprocessing.connection.wait(object_list, timeout=None)

object_list 中のオブジェクトが準備ができるまで待機します。準備ができた object_list 中のオブジェクトのリストを返します。timeout が浮動小数点なら、最大でその秒数だけ呼び出しがブロックします。timeout が None の場合、無制限の期間ブロックします。負のタイムアウトは0と等価です。

For both POSIX and Windows, an object can appear in object_list if it is

読み取り可能な Connection オブジェクト;

接続された読み取り可能な socket.socket オブジェクト; または

Process オブジェクトの sentinel 属性。

読み取ることのできるデータがある場合、あるいは相手側の端が閉じられている場合、コネクションまたはソケットオブジェクトは準備ができています。

POSIX: wait(object_list, timeout) almost equivalent select.select(object_list, [], [], timeout). The difference is that, if select.select() is interrupted by a signal, it can raise OSError with an error number of EINTR, whereas 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 WaitForMultipleObjects()) or it can be an object with a fileno() method which returns a socket handle or pipe handle. (Note that pipe handles and socket handles are not waitable handles.)

Added in version 3.3.

例

次のサーバーコードは認証キーとして 'secret password' を使用するリスナーを作成します。このサーバーはコネクションを待ってクライアントへデータを送信します:

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]))

次のコードはサーバーへ接続して、サーバーからデータを受信します:

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])

次のコードは wait() を使って複数のプロセスからのメッセージを同時に待ちます:

import time, random
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)

アドレスフォーマット

'AF_INET' アドレスは (hostname, port) のタプルになります。 hostname は文字列で port は整数です。

'AF_UNIX' アドレスはファイルシステム上のファイル名の文字列です。

'AF_PIPE' アドレスは r'\\.\pipe\PipeName' という形式の文字列です。 ServerName という名前のリモートコンピューター上の名前付きパイプに接続するために Client() を使用するには、代わりに r'\\ServerName\pipe\PipeName' 形式のアドレスを使用する必要があります。

デフォルトでは、2つのバックスラッシュで始まる文字列は 'AF_UNIX' よりも 'AF_PIPE' として推測されることに注意してください。

認証キー

Connection.recv を使用するとき、データは自動的に unpickle されて受信します。 信頼できない接続元からのデータを unpickle することはセキュリティリスクがあります。 そのため Listener や Client() はダイジェスト認証を提供するために hmac モジュールを使用します。

認証キーはパスワードとして見なされるバイト文字列です。コネクションが確立すると、双方の終点で正しい接続先であることを証明するために 知っているお互いの認証キーを要求します。(双方の終点が同じキーを使用して通信しようとしても、コネクション上でそのキーを送信することは できません。)

認証が要求されているにもかかわらず認証キーが指定されていない場合 current_process().authkey の返す値が使用されます。 (詳細は Process を参照してください。) この値はカレントプロセスを作成する Process オブジェクトによって自動的に継承されます。 これは(デフォルトでは)複数プロセスのプログラムの全プロセスが相互にコネクションを 確立するときに使用される1つの認証キーを共有することを意味します。

適当な認証キーを os.urandom() を使用して生成することもできます。

ログ記録

ロギングのためにいくつかの機能が利用可能です。しかし logging パッケージは、 (ハンドラー種別に依存して)違うプロセスからのメッセージがごちゃ混ぜになるので、プロセスの共有ロックを使用しないことに注意してください。

multiprocessing.get_logger()

multiprocessing が使用するロガーを返します。必要に応じて新たなロガーを作成します。

When first created the logger has level logging.NOTSET and no default handler. Messages sent to this logger will not by default propagate to the root logger.

Windows 上では子プロセスが親プロセスのロガーレベルを継承しないことに注意してください。さらにその他のロガーのカスタマイズ内容もすべて継承されません。

multiprocessing.log_to_stderr(level=None)

この関数は get_logger() に対する呼び出しを実行しますが、 get_logger によって作成されるロガーを返すことに加えて、 '[%(levelname)s/%(processName)s] %(message)s' のフォーマットを使用して sys.stderr へ出力を送るハンドラーを追加します。level 引数を渡すことによってロガーの levelname を変更できます。

以下にロギングを有効にした例を紹介します:

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

完全なロギングレベルの表については logging モジュールを参照してください。

multiprocessing.dummy モジュール

multiprocessing.dummy は multiprocessing の API を複製しますが threading モジュールのラッパーでしかありません。

In particular, the Pool function provided by multiprocessing.dummy returns an instance of ThreadPool, which is a subclass of Pool that supports all the same method calls but uses a pool of worker threads rather than worker processes.

class multiprocessing.pool.ThreadPool([processes[, initializer[, initargs]]])

A thread pool object which controls a pool of worker threads to which jobs can be submitted. ThreadPool instances are fully interface compatible with Pool instances, and their resources must also be properly managed, either by using the pool as a context manager or by calling close() and terminate() manually.

processes is the number of worker threads to use. If processes is None then the number returned by os.cpu_count() is used.

initializer が None ではない場合、各ワーカープロセスは開始時に initializer(*initargs) を呼び出します。

Unlike Pool, maxtasksperchild and context cannot be provided.

注釈

A ThreadPool shares the same interface as Pool, which is designed around a pool of processes and predates the introduction of the 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, AsyncResult, that is not understood by any other libraries.

Users should generally prefer to use concurrent.futures.ThreadPoolExecutor, which has a simpler interface that was designed around threads from the start, and which returns concurrent.futures.Future instances that are compatible with many other libraries, including asyncio.

プログラミングガイドライン

multiprocessing を使用するときに守るべき一定のガイドラインとイディオムを挙げます。

すべての開始方式について

以下はすべての開始方式に当てはまります。

共有状態を避ける

できるだけプロセス間で巨大なデータを移動することは避けるようにすべきです。

プロセス間の通信には、threading モジュールの低レベルな同期プリミティブを使うのではなく、キューやパイプを使うのが良いでしょう。

pickle 化の可能性

プロキシのメソッドへの引数は、 pickle 化できるものにしてください。

プロキシのスレッドセーフ性

1 つのプロキシオブジェクトは、ロックで保護しないかぎり、2 つ以上のスレッドから使用してはいけません。

(異なるプロセスで 同じ プロキシを使用することは問題ではありません。)

ゾンビプロセスを join する

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 active_children() is called) all completed processes which have not yet been joined will be joined. Also calling a finished process's Process.is_alive will join the process. Even so it is probably good practice to explicitly join all the processes that you start.

pickle/unpickle より継承する方が良い

開始方式に spawn あるいは forkserver を使用している場合、multiprocessing から多くの型を pickle 化する必要があるため子プロセスはそれらを使うことができます。しかし、一般にパイプやキューを使用して共有オブジェクトを他のプロセスに送信することは避けるべきです。代わりに、共有リソースにアクセスする必要のあるプロセスは上位プロセスからそれらを継承するようにすべきです。

プロセスの強制終了を避ける

あるプロセスを停止するために Process.terminate メソッドを使用すると、そのプロセスが現在使用されている (ロック、セマフォ、パイプやキューのような) 共有リソースを破壊したり他のプロセスから利用できない状態を引き起こし易いです。

そのため、共有リソースを使用しないプロセスでのみ Process.terminate を使用することを考慮することがおそらく最善の方法です。

キューを使用するプロセスを join する

キューに要素を追加するプロセスは、すべてのバッファーされた要素が "feeder" スレッドによって下位層のパイプに対してフィードされるまで終了を待つということを覚えておいてください。 (子プロセスはこの動作を避けるためにキューの Queue.cancel_join_thread メソッドを呼ぶことができます。)

これはキューを使用するときに、キューに追加されたすべての要素が最終的にそのプロセスが join される前に削除されていることを確認する必要があることを意味します。そうしないと、そのキューに要素が追加したプロセスの終了を保証できません。デーモンではないプロセスは自動的に join されることも覚えておいてください。

次の例はデッドロックを引き起こします:

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()

修正するには最後の2行を入れ替えます(または単純に p.join() の行を削除します)。

明示的に子プロセスへリソースを渡す

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.

Windows や他の開始方式と (将来的にでも) 互換性のあるコードを書く場合は別として、これは子プロセスが実行中である限りは親プロセス内でオブジェクトがガベージコレクトされないことも保証します。これは親プロセス内でオブジェクトがガベージコレクトされたときに一部のリソースが開放されてしまう場合に重要かもしれません。

そのため、例えば

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()

は、次のように書き直すべきです

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()

sys.stdin を file-like オブジェクトに置き換えることに注意する

multiprocessing は元々無条件に:

os.close(sys.stdin.fileno())

を multiprocessing.Process._bootstrap() メソッドの中で呼び出していました --- これはプロセス内プロセス (processes-in-processes) で問題が起こしてしまいます。そこで、これは以下のように変更されました:

sys.stdin.close()
sys.stdin = open(os.open(os.devnull, os.O_RDONLY), closefd=False)

これによってプロセス同士が衝突して bad file descripter エラーを起こすという根本的な問題は解決しましたが、アプリケーションの出力バッファーを sys.stdin() から "file-like オブジェクト" に置き換えるという潜在的危険を持ち込んでしまいました。危険というのは、複数のプロセスが file-like オブジェクトの close() を呼び出すと、オブジェクトに同じデータが何度もフラッシュされ、破損してしまう可能性がある、というものです。

もし file-like オブジェクトを書いて独自のキャッシュを実装するなら、キャッシュするときに常に pid を記録しておき、pid が変わったらキュッシュを捨てることで、フォークセーフにできます。例:

@property
def cache(self):
    pid = os.getpid()
    if pid != self._pid:
        self._pid = pid
        self._cache = []
    return self._cache

より詳しい情報は bpo-5155 [https://bugs.python.org/issue?@action=redirect&bpo=5155] 、 bpo-5313 [https://bugs.python.org/issue?@action=redirect&bpo=5313] 、 bpo-5331 [https://bugs.python.org/issue?@action=redirect&bpo=5331] を見てください

開始方式が spawn および forkserver の場合

There are a few extra restrictions which don't apply to the fork start method.

さらなる pickle 化の可能性

Process.__init__() へのすべての引数は pickle 化できることを確認してください。また Process をサブクラス化する場合、そのインスタンスが Process.start メソッドが呼ばれたときに pickle 化できるようにしてください。

グローバル変数

子プロセスで実行されるコードがグローバル変数にアクセスしようとする場合、子プロセスが見るその値は Process.start が呼ばれたときの親プロセスの値と同じではない可能性があります。

しかし、単にモジュールレベルの定数であるグローバル変数なら問題にはなりません。

メインモジュールの安全なインポート

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

例えば、開始方式に spawn あるいは forkserver を使用した場合に以下のモジュールを実行すると RuntimeError で失敗します:

from multiprocessing import Process

def foo():
    print('hello')

p = Process(target=foo)
p.start()

代わりに、次のように if __name__ == '__main__': を使用してプログラムの "エントリポイント" を保護すべきです:

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()

(プログラムをフリーズせずに通常通り実行するなら freeze_support() 行は取り除けます。)

これは新たに生成された Python インタープリターがそのモジュールを安全にインポートして、モジュールの foo() 関数を実行します。

プールまたはマネージャーがメインモジュールで作成される場合に似たような制限が適用されます。

使用例

カスタマイズされたマネージャーやプロキシの作成方法と使用方法を紹介します:

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()

Pool を使用する例です:

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()

ワーカープロセスのコレクションに対してタスクをフィードしてその結果をまとめるキューの使い方の例を紹介します:

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()

multiprocessing.shared_memory --- Shared memory for direct access across processes

ソースコード Lib/multiprocessing/shared_memory.py [https://github.com/python/cpython/tree/3.12/Lib/multiprocessing/shared_memory.py]

Added in version 3.8.

This module provides a class, SharedMemory, for the allocation and management of shared memory to be accessed by one or more processes on a multicore or symmetric multiprocessor (SMP) machine. To assist with the life-cycle management of shared memory especially across distinct processes, a BaseManager subclass, SharedMemoryManager, is also provided in the multiprocessing.managers module.

In this module, shared memory refers to "POSIX style" shared memory blocks (though is not necessarily implemented explicitly as such) and does not refer to "distributed shared memory". This style of shared memory permits distinct processes to potentially read and write to a common (or shared) region of volatile memory. Processes are conventionally limited to only have access to their own process memory space but shared memory permits the sharing of data between processes, avoiding the need to instead send messages between processes containing that data. Sharing data directly via memory can provide significant performance benefits compared to sharing data via disk or socket or other communications requiring the serialization/deserialization and copying of data.

class multiprocessing.shared_memory.SharedMemory(name=None, create=False, size=0)

Create an instance of the SharedMemory class for either creating a new shared memory block or attaching to an existing shared memory block. Each shared memory block is assigned a unique name. In this way, one process can create a shared memory block with a particular name and a different process can attach to that same shared memory block using that same name.

As a resource for sharing data across processes, shared memory blocks may outlive the original process that created them. When one process no longer needs access to a shared memory block that might still be needed by other processes, the close() method should be called. When a shared memory block is no longer needed by any process, the unlink() method should be called to ensure proper cleanup.

パラメータ:

name (str | None) -- The unique name for the requested shared memory, specified as a string. When creating a new shared memory block, if None (the default) is supplied for the name, a novel name will be generated.

create (bool) -- Control whether a new shared memory block is created (True) or an existing shared memory block is attached (False).

size (int) -- The requested number of bytes when creating a new shared memory block. Because some platforms choose to allocate chunks of memory based upon that platform's memory page size, the exact size of the shared memory block may be larger or equal to the size requested. When attaching to an existing shared memory block, the size parameter is ignored.

close()

Close access to the shared memory from this instance. In order to ensure proper cleanup of resources, all instances should call close() once the instance is no longer needed. Note that calling close() does not cause the shared memory block itself to be destroyed.

unlink()

Request that the underlying shared memory block be destroyed. In order to ensure proper cleanup of resources, unlink() should be called once (and only once) across all processes which have need for the shared memory block. After requesting its destruction, a shared memory block may or may not be immediately destroyed and this behavior may differ across platforms. Attempts to access data inside the shared memory block after unlink() has been called may result in memory access errors. Note: the last process relinquishing its hold on a shared memory block may call unlink() and close() in either order.

buf

A memoryview of contents of the shared memory block.

name

Read-only access to the unique name of the shared memory block.

size

Read-only access to size in bytes of the shared memory block.

The following example demonstrates low-level use of SharedMemory instances:

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

The following example demonstrates a practical use of the SharedMemory class with NumPy arrays [https://numpy.org/], accessing the same numpy.ndarray from two distinct Python shells:

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

class multiprocessing.managers.SharedMemoryManager([address[, authkey]])

A subclass of multiprocessing.managers.BaseManager which can be used for the management of shared memory blocks across processes.

A call to start() on a SharedMemoryManager instance causes a new process to be started. This new process's sole purpose is to manage the life cycle of all shared memory blocks created through it. To trigger the release of all shared memory blocks managed by that process, call shutdown() on the instance. This triggers a unlink() call on all of the SharedMemory objects managed by that process and then stops the process itself. By creating SharedMemory instances through a SharedMemoryManager, we avoid the need to manually track and trigger the freeing of shared memory resources.

This class provides methods for creating and returning SharedMemory instances and for creating a list-like object (ShareableList) backed by shared memory.

Refer to BaseManager for a description of the inherited address and authkey optional input arguments and how they may be used to connect to an existing SharedMemoryManager service from other processes.

SharedMemory(size)

Create and return a new SharedMemory object with the specified size in bytes.

ShareableList(sequence)

Create and return a new ShareableList object, initialized by the values from the input sequence.

The following example demonstrates the basic mechanisms of a SharedMemoryManager:

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

The following example depicts a potentially more convenient pattern for using SharedMemoryManager objects via the with statement to ensure that all shared memory blocks are released after they are no longer needed:

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

When using a SharedMemoryManager in a with statement, the shared memory blocks created using that manager are all released when the with statement's code block finishes execution.

class multiprocessing.shared_memory.ShareableList(sequence=None, *, name=None)

Provide a mutable list-like object where all values stored within are stored in a shared memory block. This constrains storable values to the following built-in data types:

int (signed 64-bit)

float

bool

str (less than 10M bytes each when encoded as UTF-8)

bytes (less than 10M bytes each)

None

It also notably differs from the built-in list type in that these lists can not change their overall length (i.e. no append(), insert(), etc.) and do not support the dynamic creation of new ShareableList instances via slicing.

sequence is used in populating a new ShareableList full of values. Set to None to instead attach to an already existing ShareableList by its unique shared memory name.

name is the unique name for the requested shared memory, as described in the definition for SharedMemory. When attaching to an existing ShareableList, specify its shared memory block's unique name while leaving sequence set to None.

注釈

A known issue exists for bytes and str values. If they end with \x00 nul bytes or characters, those may be silently stripped when fetching them by index from the ShareableList. This .rstrip(b'\x00') behavior is considered a bug and may go away in the future. See gh-106939 [https://github.com/python/cpython/issues/106939].

For applications where rstripping of trailing nulls is a problem, work around it by always unconditionally appending an extra non-0 byte to the end of such values when storing and unconditionally removing it when fetching:

>>> 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()

count(value)

Return the number of occurrences of value.

index(value)

Return first index position of value. Raise ValueError if value is not present.

format

Read-only attribute containing the struct packing format used by all currently stored values.

shm

The SharedMemory instance where the values are stored.

以下に ShareableList インスタンスの利用例を示します。

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

The following example depicts how one, two, or many processes may access the same ShareableList by supplying the name of the shared memory block behind it:

>>> 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()

The following examples demonstrates that ShareableList (and underlying SharedMemory) objects can be pickled and unpickled if needed. Note, that it will still be the same shared object. This happens, because the deserialized object has the same unique name and is just attached to an existing object with the same name (if the object is still alive):

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

>>> deserialized_sl = pickle.loads(pickle.dumps(sl))
>>> list(deserialized_sl)
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

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

>>> sl.shm.close()
>>> sl.shm.unlink()

The concurrent package

現在のところ、このパッケージにはモジュールが1つだけあります:

concurrent.futures -- 並列タスク実行

concurrent.futures --- Launching parallel tasks

Added in version 3.2.

ソースコード: Lib/concurrent/futures/thread.py [https://github.com/python/cpython/tree/3.12/Lib/concurrent/futures/thread.py] および Lib/concurrent/futures/process.py [https://github.com/python/cpython/tree/3.12/Lib/concurrent/futures/process.py]

concurrent.futures モジュールは、非同期に実行できる呼び出し可能オブジェクトの高水準のインターフェースを提供します。

非同期実行は ThreadPoolExecutor を用いてスレッドで実行することも、 ProcessPoolExecutor を用いて別々のプロセスで実行することもできます. どちらも Executor 抽象クラスで定義された同じインターフェースを実装します。

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. See WebAssemblyプラットフォーム for more information.

Executor オブジェクト

class concurrent.futures.Executor

非同期呼び出しを実行するためのメソッドを提供する抽象クラスです。このクラスを直接使ってはならず、具象サブクラスを介して使います。

submit(fn, /, *args, **kwargs)

呼び出し可能オブジェクト fn を、 fn(*args, **kwargs) として実行するようにスケジュールし、呼び出し可能オブジェクトの実行を表現する Future オブジェクトを返します。

with ThreadPoolExecutor(max_workers=1) as executor:
    future = executor.submit(pow, 323, 1235)
    print(future.result())

map(fn, *iterables, timeout=None, chunksize=1)

Similar to map(fn, *iterables) except:

the iterables are collected immediately rather than lazily;

fn is executed asynchronously and several calls to fn may be made concurrently.

もし __next__() が呼ばれその結果が元々の Executor.map() の呼び出しから timeout 秒経った後も利用できない場合、返されるイテレータは TimeoutError を送出します。timeout は整数または浮動小数点数です。もし timeout が指定されないか の場合、待ち時間に制限はありません。

If a fn call raises an exception, then that exception will be raised when its value is retrieved from the iterator.

When using ProcessPoolExecutor, this method chops iterables into a number of chunks which it submits to the pool as separate tasks. The (approximate) size of these chunks can be specified by setting chunksize to a positive integer. For very long iterables, using a large value for chunksize can significantly improve performance compared to the default size of 1. With ThreadPoolExecutor, chunksize has no effect.

バージョン 3.5 で変更: chunksize 引数が追加されました。

shutdown(wait=True, *, cancel_futures=False)

executor に対して、現在保留中のフューチャーが実行された後で、使用中のすべての資源を解放するように伝えます。シャットダウンにより後に Executor.submit() と Executor.map() を呼び出すと RuntimeError が送出されます。

wait が True の場合、すべての未完了のフューチャの実行が完了して Executor に関連付けられたリソースが解放されるまで、このメソッドは返りません。 wait が False の場合、このメソッドはすぐに返り、すべての未完了のフューチャの実行が完了したときに、 Executor に関連付けられたリソースが解放されます。 wait の値に関係なく、すべての未完了のフューチャの実行が完了するまで Python プログラム全体は終了しません。

If cancel_futures is True, this method will cancel all pending futures that the executor has not started running. Any futures that are completed or running won't be cancelled, regardless of the value of cancel_futures.

If both cancel_futures and wait are True, all futures that the executor has started running will be completed prior to this method returning. The remaining futures are cancelled.

with 文を使用することで、このメソッドを明示的に呼ばないようにできます。 with 文は Executor をシャットダウンします (wait を True にセットして Executor.shutdown() が呼ばれたかのように待ちます)。

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')

バージョン 3.9 で変更: cancel_futures が追加されました。

ThreadPoolExecutor

ThreadPoolExecutor はスレッドのプールを使用して非同期に呼び出しを行う、 Executor のサブクラスです。

Future に関連づけられた呼び出し可能オブジェクトが、別の Future の結果を待つ時にデッドロックすることがあります。例:

import time
def wait_on_b():
    time.sleep(5)
    print(b.result())  # b will never complete because it is waiting on a.
    return 5

def wait_on_a():
    time.sleep(5)
    print(a.result())  # a will never complete because it is waiting on b.
    return 6

executor = ThreadPoolExecutor(max_workers=2)
a = executor.submit(wait_on_b)
b = executor.submit(wait_on_a)

以下でも同様です:

def wait_on_future():
    f = executor.submit(pow, 5, 2)
    # This will never complete because there is only one worker thread and
    # it is executing this function.
    print(f.result())

executor = ThreadPoolExecutor(max_workers=1)
executor.submit(wait_on_future)

class concurrent.futures.ThreadPoolExecutor(max_workers=None, thread_name_prefix='', initializer=None, initargs=())

最大で max_workers 個のスレッドを非同期実行に使う Executor のサブクラスです。

All threads enqueued to ThreadPoolExecutor will be joined before the interpreter can exit. Note that the exit handler which does this is executed before any exit handlers added using atexit. This means exceptions in the main thread must be caught and handled in order to signal threads to exit gracefully. For this reason, it is recommended that ThreadPoolExecutor not be used for long-running tasks.

initializer is an optional callable that is called at the start of each worker thread; initargs is a tuple of arguments passed to the initializer. Should initializer raise an exception, all currently pending jobs will raise a BrokenThreadPool, as well as any attempt to submit more jobs to the pool.

バージョン 3.5 で変更: max_workers が None か指定されない場合のデフォルト値はマシンのプロセッサの数に 5 を掛けたものになります。これは、 ThreadPoolExecutor は CPU の処理ではなく I/O をオーバーラップするのによく使用されるため、 ProcessPoolExecutor のワーカーの数よりもこのワーカーの数を増やすべきであるという想定に基づいています。

バージョン 3.6 で変更: Added the thread_name_prefix parameter to allow users to control the threading.Thread names for worker threads created by the pool for easier debugging.

バージョン 3.7 で変更: initializer と initargs 引数が追加されました。

バージョン 3.8 で変更: Default value of max_workers is changed to min(32, os.cpu_count() + 4). This default value preserves at least 5 workers for I/O bound tasks. It utilizes at most 32 CPU cores for CPU bound tasks which release the GIL. And it avoids using very large resources implicitly on many-core machines.

ThreadPoolExecutor now reuses idle worker threads before starting max_workers worker threads too.

ThreadPoolExecutor の例

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://nonexistant-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)))

ProcessPoolExecutor

ProcessPoolExecutor はプロセスプールを使って非同期呼び出しを実施する Executor のサブクラスです。ProcessPoolExecutor は multiprocessing モジュールを利用します。このため Global Interpreter Lock を回避することができますが、pickle 化できるオブジェクトしか実行したり返したりすることができません。

__main__ モジュールはワーカサブプロセスでインポート可能でなければなりません。すなわち、 ProcessPoolExecutor は対話的インタープリタでは動きません。

ProcessPoolExecutor に渡された呼び出し可能オブジェクトから Executor や Future メソッドを呼ぶとデッドロックに陥ります。

class concurrent.futures.ProcessPoolExecutor(max_workers=None, mp_context=None, initializer=None, initargs=(), max_tasks_per_child=None)

An Executor subclass that executes calls asynchronously using a pool of at most max_workers processes. If max_workers is None or not given, it will default to the number of processors on the machine. If max_workers is less than or equal to 0, then a ValueError will be raised. On Windows, max_workers must be less than or equal to 61. If it is not then ValueError will be raised. If max_workers is None, then the default chosen will be at most 61, even if more processors are available. mp_context can be a multiprocessing context or None. It will be used to launch the workers. If mp_context is None or not given, the default multiprocessing context is used. See コンテキストと開始方式.

initializer is an optional callable that is called at the start of each worker process; initargs is a tuple of arguments passed to the initializer. Should initializer raise an exception, all currently pending jobs will raise a BrokenProcessPool, as well as any attempt to submit more jobs to the pool.

max_tasks_per_child is an optional argument that specifies the maximum number of tasks a single process can execute before it will exit and be replaced with a fresh worker process. By default max_tasks_per_child is None which means worker processes will live as long as the pool. When a max is specified, the "spawn" multiprocessing start method will be used by default in absence of a mp_context parameter. This feature is incompatible with the "fork" start method.

バージョン 3.3 で変更: When one of the worker processes terminates abruptly, a BrokenProcessPool error is now raised. Previously, behaviour was undefined but operations on the executor or its futures would often freeze or deadlock.

バージョン 3.7 で変更: The mp_context argument was added to allow users to control the start_method for worker processes created by the pool.

initializer と initargs 引数が追加されました。

注釈

The default multiprocessing start method (see コンテキストと開始方式) will change away from fork in Python 3.14. Code that requires fork be used for their ProcessPoolExecutor should explicitly specify that by passing a mp_context=multiprocessing.get_context("fork") parameter.

バージョン 3.11 で変更: The max_tasks_per_child argument was added to allow users to control the lifetime of workers in the pool.

バージョン 3.12 で変更: On POSIX systems, if your application has multiple threads and the multiprocessing context uses the "fork" start method: The os.fork() function called internally to spawn workers may raise a DeprecationWarning. Pass a mp_context configured to use a different start method. See the os.fork() documentation for further explanation.

ProcessPoolExecutor の例

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()

Future オブジェクト

Future クラスは呼び出し可能オブジェクトの非同期実行をカプセル化します。 Future のインスタンスは Executor.submit() によって生成されます。

class concurrent.futures.Future

呼び出し可能オブジェクトの非同期実行をカプセル化します。 Future インスタンスは Executor.submit() で生成され、テストを除いて直接生成すべきではありません。

cancel()

Attempt to cancel the call. If the call is currently being executed or finished running and cannot be cancelled then the method will return False, otherwise the call will be cancelled and the method will return True.

cancelled()

呼び出しが正常にキャンセルされた場合 True を返します。

running()

現在呼び出しが実行中でキャンセルできない場合 True を返します。

done()

呼び出しが正常にキャンセルされたか終了した場合 True を返します。

result(timeout=None)

呼び出しによって返された値を返します。もし呼び出しがまだ完了していなければ、このメソッドは timeout 秒の間、待機します。もし呼び出しが timeout 秒間の間に完了しなければ、 TimeoutError が送出されます。 timeout はintかfloatを指定できます。もし timeout が指定されていないか、 None であれば、待機時間に制限はありません。

future が完了する前にキャンセルされた場合 CancelledError が送出されます。

If the call raised an exception, this method will raise the same exception.

exception(timeout=None)

呼び出しによって送出された例外を返します。もし呼び出しがまだ完了されていなければ、このメソッドは timeout 秒だけ待機します。もし呼び出しが timeout 秒の間に完了しなければ、 TimeoutError が送出されます。 timeout にはintかfloatを指定できます。 timeout が指定されていないか、 None であれば、待機時間に制限はありません。

future が完了する前にキャンセルされた場合 CancelledError が送出されます。

呼び出しが例外を送出することなく完了した場合、None を返します。

add_done_callback(fn)

呼び出し可能な fn オブジェクトを future にアタッチします。futureがキャンセルされたか、実行を終了した際に、future をそのただ一つの引数として fn が呼び出されます。

追加された呼び出し可能オブジェクトは、追加された順番で呼びだされ、追加を行ったプロセスに属するスレッド中で呼び出されます。もし呼び出し可能オブジェクトが Exception のサブクラスを送出した場合、それはログに記録され無視されます。呼び出し可能オブジェクトが BaseException のサブクラスを送出した場合の動作は未定義です。

もしfutureがすでに完了しているか、キャンセル済みであれば、fn は即座に実行されます。

以下の Future メソッドは、ユニットテストでの使用と Executor を実装することを意図しています。

set_running_or_notify_cancel()

このメソッドは、Future に関連付けられたワークやユニットテストによるワークの実行前に、 Executor の実装によってのみ呼び出してください。

このメソッドが False を返す場合、 Future はキャンセルされています。つまり、 Future.cancel() が呼び出されて True が返っています。Future の完了を (as_completed() または wait() により) 待機するすべてのスレッドが起動します。

このメソッドが True を返す場合、 Future はキャンセルされて、実行状態に移行されています。つまり、 Future.running() を呼び出すと True が返ります。

このメソッドは、一度だけ呼び出すことができ、Future.set_result() または Future.set_exception() がキャンセルされた後には呼び出すことができません。

set_result(result)

Future に関連付けられたワークの結果を result に設定します。

このメソッドは、 Executor の実装またはユニットテストによってのみ使用してください。

バージョン 3.8 で変更: This method raises concurrent.futures.InvalidStateError if the Future is already done.

set_exception(exception)

Future に関連付けられたワークの結果を Exception exception に設定します。

このメソッドは、 Executor の実装またはユニットテストによってのみ使用してください。

バージョン 3.8 で変更: This method raises concurrent.futures.InvalidStateError if the Future is already done.

モジュール関数

concurrent.futures.wait(fs, timeout=None, return_when=ALL_COMPLETED)

Wait for the Future instances (possibly created by different Executor instances) given by fs to complete. Duplicate futures given to fs are removed and will be returned only once. Returns a named 2-tuple of sets. The first set, named done, contains the futures that completed (finished or cancelled futures) before the wait completed. The second set, named not_done, contains the futures that did not complete (pending or running futures).

timeout で結果を返すまで待機する最大秒数を指定できます。timeout は整数か浮動小数点数をとります。timeout が指定されないか None の場合、無期限に待機します。

return_when でこの関数がいつ結果を返すか指定します。指定できる値は以下の 定数のどれか一つです:

定数

説明

concurrent.futures.FIRST_COMPLETED

いずれかのフューチャが終了したかキャンセルされたときに返します。

concurrent.futures.FIRST_EXCEPTION

The function will return when any future finishes by raising an exception. If no future raises an exception then it is equivalent to ALL_COMPLETED.

concurrent.futures.ALL_COMPLETED

すべてのフューチャが終了したかキャンセルされたときに返します。

concurrent.futures.as_completed(fs, timeout=None)

Returns an iterator over the Future instances (possibly created by different Executor instances) given by fs that yields futures as they complete (finished or cancelled futures). Any futures given by fs that are duplicated will be returned once. Any futures that completed before as_completed() is called will be yielded first. The returned iterator raises a TimeoutError if __next__() is called and the result isn't available after timeout seconds from the original call to as_completed(). timeout can be an int or float. If timeout is not specified or None, there is no limit to the wait time.

参考

PEP 3148 [https://peps.python.org/pep-3148/] -- futures - execute computations asynchronously

この機能を Python 標準ライブラリに含めることを述べた提案です。

例外クラス

exception concurrent.futures.CancelledError

future がキャンセルされたときに送出されます。

exception concurrent.futures.TimeoutError

A deprecated alias of TimeoutError, raised when a future operation exceeds the given timeout.

バージョン 3.11 で変更: This class was made an alias of TimeoutError.

exception concurrent.futures.BrokenExecutor

Derived from RuntimeError, this exception class is raised when an executor is broken for some reason, and cannot be used to submit or execute new tasks.

Added in version 3.7.

exception concurrent.futures.InvalidStateError

Raised when an operation is performed on a future that is not allowed in the current state.

Added in version 3.8.

exception concurrent.futures.thread.BrokenThreadPool

Derived from BrokenExecutor, this exception class is raised when one of the workers of a ThreadPoolExecutor has failed initializing.

Added in version 3.7.

exception concurrent.futures.process.BrokenProcessPool

Derived from BrokenExecutor (formerly RuntimeError), this exception class is raised when one of the workers of a ProcessPoolExecutor has terminated in a non-clean fashion (for example, if it was killed from the outside).

Added in version 3.3.

subprocess --- Subprocess management

ソースコード: Lib/subprocess.py [https://github.com/python/cpython/tree/3.12/Lib/subprocess.py]

subprocess モジュールは新しいプロセスの開始、入力/出力/エラーパイプの接続、リターンコードの取得を可能とします。このモジュールは以下の古いモジュールや関数を置き換えることを目的としています：

os.system
os.spawn*

これらのモジュールや関数の代わりに、subprocess モジュールをどのように使うかについてを以下の節で説明します。

参考

PEP 324 [https://peps.python.org/pep-0324/] -- subprocess モジュールを提案している PEP

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. See WebAssemblyプラットフォーム for more information.

subprocess モジュールを使う

サブプロセスを起動するために推奨される方法は、すべての用法を扱える run() 関数を使用することです。より高度な用法では下層の Popen インターフェースを直接使用することもできます。

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)

args で指定されたコマンドを実行します。コマンドの完了を待って、CompletedProcess インスタンスを返します。

上記の引数は、もっともよく使われるものだけ示しており、後述の よく使われる引数 で説明されています (そのためここではキーワード専用引数の表記に省略されています)。関数の完全な使用法を説明しても大部分が Popen コンストラクターの内容と同じになります - この関数のほとんどの引数は Popen インターフェイスに渡されます。(timeout、input および check は除く。)

If capture_output is true, stdout and stderr will be captured. When used, the internal Popen object is automatically created with stdout and stdin both set to 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 PIPE and stderr to STDOUT, instead of using capture_output.

A timeout may be specified in seconds, it is internally passed on to Popen.communicate(). If the timeout expires, the child process will be killed and waited for. The 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 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 Popen object is automatically created with stdin set to PIPE, and the stdin argument may not be used as well.

check に真を指定した場合、プロセスが非ゼロの終了コードで終了すると CalledProcessError 例外が送出されます。この例外の属性には、引数、終了コード、標準出力および標準エラー出力が捕捉できた場合に格納されます。

encoding または errors 引数が指定されるか、text 引数が true である場合、stdin, stdout および stderr のためのファイルオブジェクトはテキストモードでオープンされます。 その際には指定された encoding および errors が使われるか、デフォルトの io.TextIOWrapper になります。universal_newlines 引数は text 引数と等価であり、後方互換性のために提供されています。そうでない場合、デフォルトでこれらのファイルオブジェクトはバイナリモードでオープンされます。

env が None 以外の場合、これは新しいプロセスでの環境変数を定義します。デフォルトでは、子プロセスは現在のプロセスの環境変数を引き継ぎます。 Popen に直接渡されます。あらゆるプラットフォームで os.environ のように文字列から文字列へ、またPOSIX プラットフォームにおいては os.environb のようにバイトからバイトへも、定義すること出来ます。

例:

>>> subprocess.run(["ls", "-l"])  # doesn't capture output
CompletedProcess(args=['ls', '-l'], returncode=0)

>>> subprocess.run("exit 1", shell=True, check=True)
Traceback (most recent call last):
  ...
subprocess.CalledProcessError: Command 'exit 1' returned non-zero exit status 1

>>> subprocess.run(["ls", "-l", "/dev/null"], capture_output=True)
CompletedProcess(args=['ls', '-l', '/dev/null'], returncode=0,
stdout=b'crw-rw-rw- 1 root root 1, 3 Jan 23 16:23 /dev/null\n', stderr=b'')

Added in version 3.5.

バージョン 3.6 で変更: encoding と error が引数に追加されました。

バージョン 3.7 で変更: universal_newlines 引数のよりわかりやすい名前として、text 引数が追加されました。capture_output 引数が追加されました。

バージョン 3.12 で変更: shell=True のときのWindowsシェル検索順序を変更しました。カレントディレクトリと %PATH% は、 %COMSPEC% と %SystemRoot%\System32\cmd.exe に置き換えられました。これにより、 cmd.exe という名前の悪意のあるプログラムをカレントディレクトリにドロップしても、動作しなくなりました。

class subprocess.CompletedProcess

run() の戻り値。プロセスが終了したことを表します。

args

プロセスを起動するときに使用された引数。1 個のリストか 1 個の文字列になります。

returncode

子プロセスの終了コード。一般に、終了ステータス 0 はプロセスが正常に終了したことを示します。

負の値 -N は子プロセスがシグナル N により中止させられたことを示します (POSIX のみ)。

stdout

子プロセスから補足された標準出力です。バイト列、もしくは run() でエンコーディングが指定された場合、エラーの場合、text=True が指定された場合は文字列です。標準出力が補足できなかったら None になります。

プロセスが stderr=subprocess.STDOUT で実行された場合、標準出力と標準エラー出力が混合されたものがこの属性に格納され、stderr は None になります。

stderr

子プロセスから補足された標準エラー出力です。バイト列、もしくは run() でエンコーディングが指定された場合、エラーの場合、text=True が指定された場合は文字列です。標準エラー出力が補足できなかったら None になります。

check_returncode()

returncode が非ゼロの場合、CalledProcessError が送出されます。

Added in version 3.5.

subprocess.DEVNULL

Popen の stdin, stdout, stderr 引数に渡して、標準入出力を os.devnull から入出力するように指定するための特殊値です。

Added in version 3.3.

subprocess.PIPE

Popen の stdin, stdout, stderr 引数に渡して、標準ストリームに対するパイプを開くことを指定するための特殊値です。Popen.communicate() に非常に有用です。

subprocess.STDOUT

Popen の stderr 引数に渡して、標準エラー出力が標準出力と同じハンドルに出力されるように指定するための特殊値です。

exception subprocess.SubprocessError

このモジュールの他のすべての例外のための基底クラスです。

Added in version 3.3.

exception subprocess.TimeoutExpired

SubprocessError のサブクラスです。子プロセスの終了を待機している間にタイムアウトが発生した場合に送出されます。

cmd

子プロセスの生成に使用されるコマンド本文。

timeout

タイムアウト秒数。

output

run() にまたは check_output() によって捕捉された場合は、子プロセスの出力となり、それ以外の場合は None となります。text=True の設定に関係なく、出力が捕捉された場合は常に bytes となります。出力がない場合は b'' の代わりに``None`` のままになることがあります。

stdout

output の別名。stderr と対になります。

stderr

run() によって捕捉された場合、子プロセスの標準エラー出力が表示され、それ以外の場合は None となります。text=True の設定に関係なく、標準エラー出力を捕捉した場合は常に bytes となります。標準エラー出力がない場合は、b'' の代わりに None のままになることがあります。

Added in version 3.3.

バージョン 3.5 で変更: 属性 stdout および stderr が追加されました。

exception subprocess.CalledProcessError

SubprocessError のサブクラスです。check_call() または check_output() 、 check=True であるときの run() 、によって実行されたプロセスが非ゼロの終了ステータスを返した場合に送出されます。

returncode

子プロセスの終了ステータスです。もしプロセスがシグナルによって終了したなら、これは負のシグナル番号になります。

cmd

子プロセスの生成に使用されるコマンド本文。

output

run() または check_output() によって捕捉された子プロセスの出力。捕捉されなかったら None になります。

stdout

output の別名。stderr と対になります。

stderr

run() によって捕捉された子プロセスの標準エラー出力。捕捉されなかったら None になります。

バージョン 3.5 で変更: 属性 stdout および stderr が追加されました。

よく使われる引数

幅広い使用例をサポートするために、Popen コンストラクター (とその他の簡易関数) は、多くのオプション引数を受け付けます。一般的な用法については、これらの引数の多くはデフォルト値のままで問題ありません。通常必要とされる引数は以下の通りです:

args はすべての呼び出しに必要で、文字列あるいはプログラム引数のシーケンスでなければなりません。一般に、引数のシーケンスを渡す方が望ましいです。なぜなら、モジュールが必要な引数のエスケープやクオート (例えばファイル名中のスペースを許すこと) の面倒を見ることができるためです。単一の文字列を渡す場合、shell は True でなければなりません (以下を参照)。もしくは、その文字列は引数を指定せずに実行される単なるプログラムの名前でなければなりません。

stdin, stdout and stderr specify the executed program's standard input, standard output and standard error file handles, respectively. Valid values are None, PIPE, DEVNULL, an existing file descriptor (a positive integer), and an existing file object with a valid file descriptor. With the default settings of None, no redirection will occur. PIPE indicates that a new pipe to the child should be created. DEVNULL indicates that the special file os.devnull will be used. Additionally, stderr can be STDOUT, which indicates that the stderr data from the child process should be captured into the same file handle as for stdout.

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

stdin については、入力での行末文字 '\n' はデフォルトの行セパレーター os.linesep に変換されます。stdout と stderr については、出力での行末はすべて '\n' に変換されます。詳細は io.TextIOWrapper クラスのドキュメントでコンストラクターの引数 newline が None である場合を参照してください。

If text mode is not used, stdin, stdout and stderr will be opened as binary streams. No encoding or line ending conversion is performed.

バージョン 3.6 で変更: Added the encoding and errors parameters.

バージョン 3.7 で変更: universal_newlines の別名として、text 引数が追加されました。

注釈

ファイルオブジェクト Popen.stdin、Popen.stdout ならびに Popen.stderr の改行属性は Popen.communicate() メソッドで更新されません。

shell が True なら、指定されたコマンドはシェルによって実行されます。あなたが Python を主として (ほとんどのシステムシェル以上の) 強化された制御フローのために使用していて、さらにシェルパイプ、ファイル名ワイルドカード、環境変数展開、~ のユーザーホームディレクトリへの展開のような他のシェル機能への簡単なアクセスを望むなら、これは有用かもしれません。しかしながら、Python 自身が多くのシェル的な機能の実装を提供していることに注意してください (特に glob, fnmatch, os.walk(), os.path.expandvars(), os.path.expanduser(), shutil)。

バージョン 3.3 で変更: universal_newlines が True の場合、クラスはエンコーディング locale.getpreferredencoding() の代わりに locale.getpreferredencoding(False) を使用します。この変更についての詳細は、 io.TextIOWrapper クラスを参照してください。

注釈

shell=True を使う前に セキュリティで考慮すべき点 を読んでください。

これらのオプションは、他のすべてのオプションとともに Popen コンストラクターのドキュメントの中でより詳細に説明されています。

Popen コンストラクター

このモジュールの中で、根底のプロセス生成と管理は Popen クラスによって扱われます。簡易関数によってカバーされないあまり一般的でないケースを開発者が扱えるように、Popen クラスは多くの柔軟性を提供しています。

class 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)

新しいプロセスで子のプログラムを実行します。POSIX においては、子のプログラムを実行するために、このクラスは os.execvpe() のような挙動を使用します。Windows においては、このクラスは Windows の CreateProcess() 関数を使用します。Popen への引数は以下の通りです。

args はプログラム引数のシーケンスか、単一の文字列または path-like object でなければなりません。デフォルトでは、args がシーケンスの場合に実行されるプログラムは args の最初の要素です。args が文字列の場合、解釈はプラットフォーム依存であり、下記に説明されます。デフォルトの挙動からの追加の違いについては shell および executable 引数を参照してください。特に明記されない限り、args をシーケンスとして渡すことが推奨されます。

警告

For maximum reliability, use a fully qualified path for the executable. To search for an unqualified name on PATH, use shutil.which(). On all platforms, passing sys.executable is the recommended way to launch the current Python interpreter again, and use the -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 os.execvpe(), and note that when resolving or searching for the executable path, cwd overrides the current working directory and env can override the PATH environment variable. For Windows, see the documentation of the lpApplicationName and lpCommandLine parameters of WinAPI CreateProcess, and note that when resolving or searching for the executable path with shell=False, cwd does not override the current working directory and env cannot override the PATH environment variable. Using a full path avoids all of these variations.

An example of passing some arguments to an external program as a sequence is:

Popen(["/usr/bin/git", "commit", "-m", "Fixes a bug."])

POSIX 上では、args が文字列の場合、その文字列は実行すべきプログラムの名前またはパスとして解釈されます。しかし、これはプログラムに引数を渡さない場合にのみ可能です。

注釈

It may not be obvious how to break a shell command into a sequence of arguments, especially in complex cases. shlex.split() can illustrate how to determine the correct tokenization for args:

>>> import shlex, subprocess
>>> command_line = input()
/bin/vikings -input eggs.txt -output "spam spam.txt" -cmd "echo '$MONEY'"
>>> args = shlex.split(command_line)
>>> print(args)
['/bin/vikings', '-input', 'eggs.txt', '-output', 'spam spam.txt', '-cmd', "echo '$MONEY'"]
>>> p = subprocess.Popen(args) # Success!

特に注意すべき点は、シェル内でスペースで区切られたオプション (-input など) と引数 (eggs.txt など) はリストの別々の要素になるのに対し、シェル内で (上記のスペースを含むファイル名や echo コマンドのように) クォーティングやバックスラッシュエスケープが必要なものは単一のリスト要素であることです。

Windows 上では、args がシーケンスなら Windows における引数シーケンスから文字列への変換 に記述された方法で文字列に変換されます。これは根底の CreateProcess() が文字列上で動作するからです。

バージョン 3.6 で変更: args parameter accepts a path-like object if shell is False and a sequence containing path-like objects on POSIX.

バージョン 3.8 で変更: args parameter accepts a path-like object if shell is False and a sequence containing bytes and path-like objects on Windows.

shell 引数 (デフォルトでは False) は、実行するプログラムとしてシェルを使用するかどうかを指定します。 shell が True の場合、 args をシーケンスとしてではなく文字列として渡すことが推奨されます。

POSIX で shell=True の場合、シェルのデフォルトは /bin/sh になります。args が文字列の場合、この文字列はシェルを介して実行されるコマンドを指定します。したがって、文字列は厳密にシェルプロンプトで打つ形式と一致しなければなりません。例えば、文字列の中にスペースを含むファイル名がある場合は、クォーティングやバックスラッシュエスケープが必要です。args がシーケンスの場合には、最初の要素はコマンド名を表わす文字列として、残りの要素は追加の引数としてシェルに渡されます。つまり、以下の Popen と等価ということです:

Popen(['/bin/sh', '-c', args[0], args[1], ...])

Windows で shell=True とすると、COMSPEC 環境変数がデフォルトシェルを指定します。Windows で shell=True を指定する必要があるのは、実行したいコマンドがシェルに組み込みの場合だけです (例えば dir や copy)。バッチファイルやコンソールベースの実行ファイルを実行するために shell=True は必要ありません。

注釈

shell=True を使う前に セキュリティで考慮すべき点 を読んでください。

bufsize は標準入力/標準出力/標準エラー出力パイプファイルオブジェクトを生成するときに open() 関数の対応する引数に渡されます:

0 means unbuffered (read and write are one system call and can return short)

1 means line buffered (only usable if text=True or universal_newlines=True)

それ以外の正の整数はバッファーのおよそのサイズになることを意味します。

負のサイズ (デフォルト) は io.DEFAULT_BUFFER_SIZE のシステムデフォルトが使用されることを意味します。

バージョン 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 0 which was unbuffered and allowed short reads. This was unintentional and did not match the behavior of Python 2 as most code expected.

executable 引数は、実行する置換プログラムを指定します。これが必要になるのは極めて稀です。shell=False のときは、executable は args で指定されている実行プログラムを置換します。しかし、オリジナルの args は依然としてプログラムに渡されます。ほとんどのプログラムは、args で指定されたプログラムをコマンド名として扱います。そして、それは実際に実行されたプログラムとは異なる可能性があります。POSIX において、ps のようなユーティリティの中では、args 名が実行ファイルの表示名になります。shell=True の場合、POSIX において executable 引数はデフォルトの /bin/sh に対する置換シェルを指定します。

バージョン 3.6 で変更: executable 引数が POSIX で path-like object を受け付けるようになりました。

バージョン 3.8 で変更: executable 引数が Windows で path-like object を受け付けるようになりました。

バージョン 3.12 で変更: shell=True のときのWindowsシェル検索順序を変更しました。カレントディレクトリと %PATH% は、 %COMSPEC% と %SystemRoot%\System32\cmd.exe に置き換えられました。これにより、 cmd.exe という名前の悪意のあるプログラムをカレントディレクトリにドロップしても、動作しなくなりました。

stdin, stdout and stderr specify the executed program's standard input, standard output and standard error file handles, respectively. Valid values are None, PIPE, DEVNULL, an existing file descriptor (a positive integer), and an existing file object with a valid file descriptor. With the default settings of None, no redirection will occur. PIPE indicates that a new pipe to the child should be created. DEVNULL indicates that the special file os.devnull will be used. Additionally, stderr can be STDOUT, which indicates that the stderr data from the applications should be captured into the same file handle as for stdout.

preexec_fn に呼び出し可能オブジェクトが指定されている場合、このオブジェクトは子プロセスが実行される直前 (fork されたあと、exec される直前) に子プロセス内で呼ばれます。(POSIXのみ)

警告

アプリケーション中に複数のスレッドが存在する状態で preexec_fn 引数を使用するのは**安全ではありません**。exec が呼ばれる前に子プロセスがデッドロックを起こすことがあります。

注釈

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 os.setsid() or os.setpgid() in the child.

バージョン 3.8 で変更: The preexec_fn parameter is no longer supported in subinterpreters. The use of the parameter in a subinterpreter raises 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 0, 1 and 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 ファイル記述子の継承.

On Windows, if close_fds is true then no handles will be inherited by the child process unless explicitly passed in the handle_list element of STARTUPINFO.lpAttributeList, or by standard handle redirection.

バージョン 3.2 で変更: close_fds のデフォルトは、False から上記のものに変更されました。

バージョン 3.7 で変更: On Windows the default for close_fds was changed from False to True when redirecting the standard handles. It's now possible to set close_fds to True when redirecting the standard handles.

pass_fds はオプションで、親と子の間で開いたままにしておくファイル記述子のシーケンスを指定します。何らかの pass_fds を渡した場合、close_fds は強制的に True になります。(POSIXのみ)

バージョン 3.2 で変更: pass_fds 引数が追加されました。

If cwd is not None, the function changes the working directory to cwd before executing the child. cwd can be a string, bytes or 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 引数が POSIX で path-like object を受け付けるようになりました。

バージョン 3.7 で変更: cwd 引数が Windows で path-like object を受け付けるようになりました。

バージョン 3.8 で変更: cwd 引数が Windows で bytes オブジェクトを受け付けるようになりました。

restore_signals が真の場合 (デフォルト)、Python が SIG_IGN に設定したすべてのシグナルは子プロセスが exec される前に子プロセスの SIG_DFL に格納されます。現在これには SIGPIPE, SIGXFZ および SIGXFSZ シグナルが含まれています。(POSIX のみ)

バージョン 3.2 で変更: restore_signals が追加されました。

If start_new_session is true the setsid() system call will be made in the child process prior to the execution of the subprocess.

利用可能な環境: POSIX

バージョン 3.2 で変更: start_new_session が追加されました。

If process_group is a non-negative integer, the setpgid(0, value) system call will be made in the child process prior to the execution of the subprocess.

利用可能な環境: POSIX

バージョン 3.11 で変更: process_group was added.

If group is not 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 grp.getgrnam() and the value in gr_gid will be used. If the value is an integer, it will be passed verbatim. (POSIX only)

利用可能な環境: POSIX

Added in version 3.9.

If extra_groups is not 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 grp.getgrnam() and the values in gr_gid will be used. Integer values will be passed verbatim. (POSIX only)

利用可能な環境: POSIX

Added in version 3.9.

If user is not 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 pwd.getpwnam() and the value in pw_uid will be used. If the value is an integer, it will be passed verbatim. (POSIX only)

利用可能な環境: POSIX

Added in version 3.9.

If umask is not negative, the umask() system call will be made in the child process prior to the execution of the subprocess.

利用可能な環境: POSIX

Added in version 3.9.

env が None 以外の場合、これは新しいプロセスでの環境変数を定義します。デフォルトでは、子プロセスは現在のプロセスの環境変数を引き継ぎます。あらゆるプラットフォームで os.environ のように文字列から文字列へ、またPOSIX プラットフォームにおいては os.environb のようにバイトからバイトへも、定義すること出来ます。

注釈

env を指定する場合、プログラムを実行するのに必要な変数すべてを与えなければなりません。Windows で Side-by-Side アセンブリ [https://en.wikipedia.org/wiki/Side-by-Side_Assembly] を実行するためには、env は正しい SystemRoot を 含まなければなりません 。

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 よく使われる引数. The universal_newlines argument is equivalent to text and is provided for backwards compatibility. By default, file objects are opened in binary mode.

Added in version 3.6: encoding と errors が追加されました。

Added in version 3.7: text が、universal_newlines のより読みやすい別名として追加されました。

If given, startupinfo will be a STARTUPINFO object, which is passed to the underlying CreateProcess function.

If given, creationflags, can be one or more of the following flags:

CREATE_NEW_CONSOLE

CREATE_NEW_PROCESS_GROUP

ABOVE_NORMAL_PRIORITY_CLASS

BELOW_NORMAL_PRIORITY_CLASS

HIGH_PRIORITY_CLASS

IDLE_PRIORITY_CLASS

NORMAL_PRIORITY_CLASS

REALTIME_PRIORITY_CLASS

CREATE_NO_WINDOW

DETACHED_PROCESS

CREATE_DEFAULT_ERROR_MODE

CREATE_BREAKAWAY_FROM_JOB

pipesize can be used to change the size of the pipe when PIPE is used for stdin, stdout or stderr. The size of the pipe is only changed on platforms that support this (only Linux at this time of writing). Other platforms will ignore this parameter.

バージョン 3.10 で変更: Added the pipesize parameter.

Popen オブジェクトは with 文によってコンテキストマネージャーとしてサポートされます: 終了時には標準ファイル記述子が閉じられ、プロセスを待機します:

with Popen(["ifconfig"], stdout=PIPE) as proc:
    log.write(proc.stdout.read())

引数 executable, args, cwd, env を指定して 監査イベント subprocess.Popen を送出します。

バージョン 3.2 で変更: コンテキストマネージャーサポートが追加されました。

バージョン 3.6 で変更: Popen destructor now emits a ResourceWarning warning if the child process is still running.

バージョン 3.8 で変更: Popen can use os.posix_spawn() in some cases for better performance. On Windows Subsystem for Linux and QEMU User Emulation, Popen constructor using os.posix_spawn() no longer raise an exception on errors like missing program, but the child process fails with a non-zero returncode.

例外

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 OSError. This occurs, for example, when trying to execute a non-existent file. Applications should prepare for OSError exceptions. Note that, when shell=True, 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.

不正な引数で Popen が呼ばれた場合は ValueError が発生します。

呼び出されたプロセスが非ゼロのリターンコードを返した場合 check_call() や check_output() は CalledProcessError を送出します。

All of the functions and methods that accept a timeout parameter, such as run() and Popen.communicate() will raise TimeoutExpired if the timeout expires before the process exits.

このモジュールで定義されたすべての例外は SubprocessError を継承しています。

Added in version 3.3: SubprocessError 基底クラスが追加されました。

セキュリティで考慮すべき点

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 shell=True, it is the application's responsibility to ensure that all whitespace and metacharacters are quoted appropriately to avoid shell injection [https://en.wikipedia.org/wiki/Shell_injection#Shell_injection] vulnerabilities. On some platforms, it is possible to use shlex.quote() for this escaping.

On Windows, batch files (*.bat or *.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 shell=True to allow Python to escape special characters. See gh-114539 [https://github.com/python/cpython/issues/114539] for additional discussion.

Popen オブジェクト

Popen クラスのインスタンスには、以下のようなメソッドがあります:

Popen.poll()

子プロセスが終了しているかどうかを調べます。 returncode 属性を設定して返します。そうでなければ None を返します。

Popen.wait(timeout=None)

子プロセスが終了するまで待ちます。returncode 属性を設定して返します。

プロセスが timeout 秒後に終了してない場合、TimeoutExpired 例外を送出します。この例外を捕捉して wait を再試行するのは安全です。

注釈

stdout=PIPE や stderr=PIPE を使っていて、より多くのデータを受け入れるために OS のパイプバッファーをブロックしているパイプに子プロセスが十分な出力を生成した場合、デッドロックが発生します。これを避けるには Popen.communicate() を使用してください。

注釈

When the timeout parameter is not None, then (on POSIX) the function is implemented using a busy loop (non-blocking call and short sleeps). Use the asyncio module for an asynchronous wait: see asyncio.create_subprocess_exec.

バージョン 3.3 で変更: timeout が追加されました

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 returncode attribute. The optional input argument should be data to be sent to the child process, or 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.

communicate() returns a tuple (stdout_data, stderr_data). The data will be strings if streams were opened in text mode; otherwise, bytes.

子プロセスの標準入力にデータを送りたい場合は、 Popen オブジェクトを stdin=PIPE と指定して作成しなければなりません。同じく、戻り値のタプルから None ではない値を取得するためには、 stdout=PIPE かつ/または stderr=PIPE を指定しなければなりません。

プロセスが timeout 秒後に終了してない場合、TimeoutExpired 例外が送出されます。この例外を捕捉して通信を再試行しても出力データは失われません。

タイムアウトが発生した場合子プロセスは kill されません。したがって、適切にクリーンアップを行うために、正常に動作するアプリケーションは子プロセスを kill して通信を終了すべきです:

proc = subprocess.Popen(...)
try:
    outs, errs = proc.communicate(timeout=15)
except TimeoutExpired:
    proc.kill()
    outs, errs = proc.communicate()

注釈

受信したデータはメモリにバッファーされます。そのため、返されるデータが大きいかあるいは制限がないような場合はこのメソッドを使うべきではありません。

バージョン 3.3 で変更: timeout が追加されました

Popen.send_signal(signal)

signal シグナルを子プロセスに送ります。

Do nothing if the process completed.

注釈

Windows では、SIGTERM は terminate() の別名です。CTRL_C_EVENT と CTRL_BREAK_EVENT を、CREATE_NEW_PROCESS_GROUP を含む creationflags で始まった、プロセスに送れます。

Popen.terminate()

Stop the child. On POSIX OSs the method sends SIGTERM to the child. On Windows the Win32 API function TerminateProcess() is called to stop the child.

Popen.kill()

子プロセスを kill します。POSIX OS では SIGKILL シグナルを子プロセスに送ります。Windows では、kill() は terminate() の別名です。

The following attributes are also set by the class for you to access. Reassigning them to new values is unsupported:

Popen.args

Popen に渡された引数 args です -- プログラム引数のシーケンスまたは 1 個の文字列になります。

Added in version 3.3.

Popen.stdin

If the stdin argument was PIPE, this attribute is a writeable stream object as returned by open(). If the encoding or errors arguments were specified or the text or universal_newlines argument was True, the stream is a text stream, otherwise it is a byte stream. If the stdin argument was not PIPE, this attribute is None.

Popen.stdout

If the stdout argument was PIPE, this attribute is a readable stream object as returned by 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 True, the stream is a text stream, otherwise it is a byte stream. If the stdout argument was not PIPE, this attribute is None.

Popen.stderr

If the stderr argument was PIPE, this attribute is a readable stream object as returned by 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 True, the stream is a text stream, otherwise it is a byte stream. If the stderr argument was not PIPE, this attribute is None.

警告

.stdin.write, .stdout.read, .stderr.read を利用すると、別のパイプの OS パイプバッファーがいっぱいになってデッドロックが発生する恐れがあります。これを避けるためには communicate() を利用してください。

Popen.pid

子プロセスのプロセス ID が入ります。

shell 引数を True に設定した場合は、生成されたシェルのプロセス ID になります。

Popen.returncode

The child return code. Initially None, returncode is set by a call to the poll(), wait(), or communicate() methods if they detect that the process has terminated.

A None value indicates that the process hadn't yet terminated at the time of the last method call.

負の値 -N は子プロセスがシグナル N により中止させられたことを示します (POSIX のみ)。

Windows Popen ヘルパー

STARTUPINFO クラスと以下の定数は、Windows のみで利用できます。

class subprocess.STARTUPINFO(*, dwFlags=0, hStdInput=None, hStdOutput=None, hStdError=None, wShowWindow=0, lpAttributeList=None)

Partial support of the Windows STARTUPINFO [https://msdn.microsoft.com/en-us/library/ms686331(v=vs.85).aspx] structure is used for Popen creation. The following attributes can be set by passing them as keyword-only arguments.

バージョン 3.7 で変更: キーワード専用引数のサポートが追加されました。

dwFlags

特定の STARTUPINFO の属性が、プロセスがウィンドウを生成するときに使われるかを決定するビットフィールドです:

si = subprocess.STARTUPINFO()
si.dwFlags = subprocess.STARTF_USESTDHANDLES | subprocess.STARTF_USESHOWWINDOW

hStdInput

dwFlags が STARTF_USESTDHANDLES を指定すれば、この属性がプロセスの標準入力処理です。STARTF_USESTDHANDLES が指定されなければ、標準入力のデフォルトはキーボードバッファーです。

hStdOutput

dwFlags が STARTF_USESTDHANDLES を指定すれば、この属性がプロセスの標準出力処理です。そうでなければ、この属性は無視され、標準出力のデフォルトはコンソールウィンドウのバッファーです。

hStdError

dwFlags が STARTF_USESTDHANDLES を指定すれば、この属性がプロセスの標準エラー処理です。そうでなければ、この属性は無視され、標準エラー出力のデフォルトはコンソールウィンドウのバッファーです。

wShowWindow

dwFlags が STARTF_USESHOWWINDOW を指定すれば、この属性は ShowWindow [https://msdn.microsoft.com/en-us/library/ms633548(v=vs.85).aspx] 関数の nCmdShow 引数で指定された値なら、 SW_SHOWDEFAULT 以外の任意のものにできます。しかし、この属性は無視されます。

この属性には SW_HIDE が提供されています。これは、Popen が shell=True として呼び出されたときに使われます。

lpAttributeList

A dictionary of additional attributes for process creation as given in STARTUPINFOEX, see UpdateProcThreadAttribute [https://msdn.microsoft.com/en-us/library/windows/desktop/ms686880(v=vs.85).aspx].

Supported attributes:

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 os.set_handle_inheritable() when passed to the Popen constructor, else OSError will be raised with Windows error ERROR_INVALID_PARAMETER (87).

警告

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 os.system(). This also applies to standard handle redirection, which temporarily creates inheritable handles.

Added in version 3.7.

Windows Constants

subprocess モジュールは、以下の定数を公開しています。

subprocess.STD_INPUT_HANDLE

標準入力デバイスです。この初期値は、コンソール入力バッファ、 CONIN$ です。

subprocess.STD_OUTPUT_HANDLE

標準出力デバイスです。この初期値は、アクティブコンソールスクリーン、 CONOUT$ です。

subprocess.STD_ERROR_HANDLE

標準エラーデバイスです。この初期値は、アクティブコンソールスクリーン、 CONOUT$ です。

subprocess.SW_HIDE

ウィンドウを隠します。別のウィンドウがアクティブになります。

subprocess.STARTF_USESTDHANDLES

追加情報を保持する、STARTUPINFO.hStdInput, STARTUPINFO.hStdOutput, および STARTUPINFO.hStdError 属性を指定します。

subprocess.STARTF_USESHOWWINDOW

追加情報を保持する、 STARTUPINFO.wShowWindow 属性を指定します。

subprocess.CREATE_NEW_CONSOLE

新しいプロセスが、親プロセスのコンソールを継承する (デフォルト) のではなく、新しいコンソールを持ちます。

subprocess.CREATE_NEW_PROCESS_GROUP

新しいプロセスグループが生成されることを指定する Popen creationflags パラメーターです。このフラグは、サブプロセスで os.kill() を使うのに必要です。

CREATE_NEW_CONSOLE が指定されていたら、このフラグは無視されます。

subprocess.ABOVE_NORMAL_PRIORITY_CLASS

A Popen creationflags parameter to specify that a new process will have an above average priority.

Added in version 3.7.

subprocess.BELOW_NORMAL_PRIORITY_CLASS

A Popen creationflags parameter to specify that a new process will have a below average priority.

Added in version 3.7.

subprocess.HIGH_PRIORITY_CLASS

A Popen creationflags parameter to specify that a new process will have a high priority.

Added in version 3.7.

subprocess.IDLE_PRIORITY_CLASS

A Popen creationflags parameter to specify that a new process will have an idle (lowest) priority.

Added in version 3.7.

subprocess.NORMAL_PRIORITY_CLASS

A Popen creationflags parameter to specify that a new process will have an normal priority. (default)

Added in version 3.7.

subprocess.REALTIME_PRIORITY_CLASS

A Popen creationflags parameter to specify that a new process will have realtime priority. You should almost never use REALTIME_PRIORITY_CLASS, because this interrupts system threads that manage mouse input, keyboard input, and background disk flushing. This class can be appropriate for applications that "talk" directly to hardware or that perform brief tasks that should have limited interruptions.

Added in version 3.7.

subprocess.CREATE_NO_WINDOW

A Popen creationflags parameter to specify that a new process will not create a window.

Added in version 3.7.

subprocess.DETACHED_PROCESS

A Popen creationflags parameter to specify that a new process will not inherit its parent's console. This value cannot be used with CREATE_NEW_CONSOLE.

Added in version 3.7.

subprocess.CREATE_DEFAULT_ERROR_MODE

A Popen creationflags parameter to specify that a new process does not inherit the error mode of the calling process. Instead, the new process gets the default error mode. This feature is particularly useful for multithreaded shell applications that run with hard errors disabled.

Added in version 3.7.

subprocess.CREATE_BREAKAWAY_FROM_JOB

A Popen creationflags parameter to specify that a new process is not associated with the job.

Added in version 3.7.

古い高水準 API

Python 3.5 より前のバージョンでは、サブプロセスに対して以下の 3 つの関数からなる高水準 API が用意されていました。現在多くの場合 run() の使用で済みますが、既存の多くのコードではこれらの関数が使用されています。

subprocess.call(args, *, stdin=None, stdout=None, stderr=None, shell=False, cwd=None, timeout=None, **other_popen_kwargs)

args で指定されたコマンドを実行します。コマンドの終了を待ち、returncode 属性を返します。

Code needing to capture stdout or stderr should use run() instead:

run(...).returncode

To suppress stdout or stderr, supply a value of DEVNULL.

上記の引数は、よく使われるものだけ示しています。関数の全使用法は Popen コンストラクターの内容と同じになります - この関数は、このインターフェースに直接指定される timeout 以外は与えられた全引数を渡します。

注釈

この関数を使用する際は stdout=PIPE および stderr=PIPE を使用しないでください。子プロセスが OS のパイプバッファーを埋めてしまうほどの出力データを生成した場合、パイプからは読み込まれないので、子プロセスがブロックされることがあります。

バージョン 3.3 で変更: timeout が追加されました

バージョン 3.12 で変更: shell=True のときのWindowsシェル検索順序を変更しました。カレントディレクトリと %PATH% は、 %COMSPEC% と %SystemRoot%\System32\cmd.exe に置き換えられました。これにより、 cmd.exe という名前の悪意のあるプログラムをカレントディレクトリにドロップしても、動作しなくなりました。

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 CalledProcessError. The CalledProcessError object will have the return code in the returncode attribute. If 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 run() instead:

run(..., check=True)

To suppress stdout or stderr, supply a value of DEVNULL.

上記の引数は、よく使われるものだけ示しています。関数の全使用法は Popen コンストラクターの内容と同じになります - この関数は、このインターフェースに直接指定される timeout 以外は与えられた全引数を渡します。

注釈

この関数を使用する際は stdout=PIPE および stderr=PIPE を使用しないでください。子プロセスが OS のパイプバッファーを埋めてしまうほどの出力データを生成した場合、パイプからは読み込まれないので、子プロセスがブロックされることがあります。

バージョン 3.3 で変更: timeout が追加されました

バージョン 3.12 で変更: shell=True のときのWindowsシェル検索順序を変更しました。カレントディレクトリと %PATH% は、 %COMSPEC% と %SystemRoot%\System32\cmd.exe に置き換えられました。これにより、 cmd.exe という名前の悪意のあるプログラムをカレントディレクトリにドロップしても、動作しなくなりました。

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)

引数でコマンドを実行し、その出力を返します。

コマンドのリターンコードが非ゼロならば CalledProcessError 例外が送出されます。CalledProcessError オブジェクトには、リターンコードが returncode 属性に、コマンドからの出力が output 属性に、それぞれ格納されています。

これは次と等価です:

run(..., check=True, stdout=PIPE).stdout

The arguments shown above are merely some common ones. The full function signature is largely the same as that of run() - most arguments are passed directly through to that interface. One API deviation from run() behavior exists: passing input=None will behave the same as input=b'' (or input='', depending on other arguments) rather than using the parent's standard input file handle.

デフォルトで、この関数はデータをエンコードされたバイトとして返します。出力されたデータの実際のエンコードは起動されているコマンドに依存するため、テキストへのデコードは通常アプリケーションレベルで扱う必要があります。

This behaviour may be overridden by setting text, encoding, errors, or universal_newlines to True as described in よく使われる引数 and run().

標準エラー出力も結果に含めるには、stderr=subprocess.STDOUT を使います:

>>> subprocess.check_output(
...     "ls non_existent_file; exit 0",
...     stderr=subprocess.STDOUT,
...     shell=True)
'ls: non_existent_file: No such file or directory\n'

Added in version 3.1.

バージョン 3.3 で変更: timeout が追加されました

バージョン 3.4 で変更: キーワード引数 input が追加されました。

バージョン 3.6 で変更: encoding and errors were added. See run() for details.

Added in version 3.7: text が、universal_newlines のより読みやすい別名として追加されました。

バージョン 3.12 で変更: shell=True のときのWindowsシェル検索順序を変更しました。カレントディレクトリと %PATH% は、 %COMSPEC% と %SystemRoot%\System32\cmd.exe に置き換えられました。これにより、 cmd.exe という名前の悪意のあるプログラムをカレントディレクトリにドロップしても、動作しなくなりました。

古い関数を subprocess モジュールで置き換える

この節では、 "a becomes b" と書かれているものは a の代替として b が使えるということを表します。

注釈

この節で紹介されている "a" 関数は全て、実行するプログラムが見つからないときは (おおむね) 静かに終了します。それに対して "b" 代替手段は OSError 例外を送出します。

また、要求された操作が非ゼロの終了コードを返した場合、check_output() を使用した置き換えは CalledProcessError で失敗します。その出力は、送出された例外の output 属性として利用可能です。

以下の例では、適切な関数が subprocess モジュールからすでにインポートされていることを前提としています。

Replacing /bin/sh shell command substitution

output=$(mycmd myarg)

これは以下のようになります:

output = check_output(["mycmd", "myarg"])

シェルのパイプラインを置き換える

output=$(dmesg | grep hda)

これは以下のようになります:

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]

p2 を開始した後の p1.stdout.close() の呼び出しは、p1 が p2 の前に存在した場合に、p1 が SIGPIPE を受け取るために重要です。

あるいは、信頼された入力に対しては、シェル自身のパイプラインサポートを直接使用することもできます:

output=$(dmesg | grep hda)

これは以下のようになります:

output = check_output("dmesg | grep hda", shell=True)

os.system() を置き換える

sts = os.system("mycmd" + " myarg")
# becomes
retcode = call("mycmd" + " myarg", shell=True)

注釈:

このプログラムは普通シェル経由で呼び出す必要はありません。

The call() return value is encoded differently to that of os.system().

The os.system() function ignores SIGINT and SIGQUIT signals while the command is running, but the caller must do this separately when using the subprocess module.

より現実的な例ではこうなるでしょう:

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)

os.spawn 関数群を置き換える

P_NOWAIT の例:

pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg")
==>
pid = Popen(["/bin/mycmd", "myarg"]).pid

P_WAIT の例:

retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg")
==>
retcode = call(["/bin/mycmd", "myarg"])

シーケンスを使った例:

os.spawnvp(os.P_NOWAIT, path, args)
==>
Popen([path] + args[1:])

環境変数を使った例:

os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env)
==>
Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"})

os.popen(), os.popen2(), os.popen3() を置き換える

(child_stdin, child_stdout) = os.popen2(cmd, mode, bufsize)
==>
p = Popen(cmd, shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, close_fds=True)
(child_stdin, child_stdout) = (p.stdin, p.stdout)

(child_stdin,
 child_stdout,
 child_stderr) = os.popen3(cmd, mode, bufsize)
==>
p = Popen(cmd, shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, stderr=PIPE, close_fds=True)
(child_stdin,
 child_stdout,
 child_stderr) = (p.stdin, p.stdout, p.stderr)

(child_stdin, child_stdout_and_stderr) = os.popen4(cmd, mode, bufsize)
==>
p = Popen(cmd, shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, stderr=STDOUT, close_fds=True)
(child_stdin, child_stdout_and_stderr) = (p.stdin, p.stdout)

終了コードハンドリングは以下のように解釈します:

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")

Replacing functions from the popen2 module

注釈

popen2 関数の cmd 引数が文字列の場合、コマンドは /bin/sh によって実行されます。リストの場合、コマンドは直接実行されます。

(child_stdout, child_stdin) = popen2.popen2("somestring", bufsize, mode)
==>
p = Popen("somestring", shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, close_fds=True)
(child_stdout, child_stdin) = (p.stdout, p.stdin)

(child_stdout, child_stdin) = popen2.popen2(["mycmd", "myarg"], bufsize, mode)
==>
p = Popen(["mycmd", "myarg"], bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, close_fds=True)
(child_stdout, child_stdin) = (p.stdout, p.stdin)

popen2.Popen3 および popen2.Popen4 は以下の点を除けば、基本的に subprocess.Popen と同じです:

Popen は実行が失敗した場合に例外を送出します。

capturestderr 引数は stderr 引数に代わりました。

stdin=PIPE および stdout=PIPE を指定する必要があります。

popen2 はデフォルトですべてのファイル記述子を閉じます。しかし、全てのプラットフォーム上で、あるいは過去の Python バージョンでこの挙動を保証するためには、 Popen に対して close_fds=True を指定しなければなりません。

レガシーなシェル呼び出し関数

このモジュールでは、以下のような 2.x commands モジュールからのレガシー関数も提供しています。これらの操作は、暗黙的にシステムシェルを起動します。また、セキュリティに関して上述した保証や例外処理一貫性は、これらの関数では有効ではありません。

subprocess.getstatusoutput(cmd, *, encoding=None, errors=None)

シェル中の cmd を実行して (exitcode, output) を返します。

Execute the string cmd in a shell with Popen.check_output() and return a 2-tuple (exitcode, output). encoding and errors are used to decode output; see the notes on よく使われる引数 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:

>>> 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, '')

Availability: 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 returncode.

バージョン 3.11 で変更: Added the encoding and errors parameters.

subprocess.getoutput(cmd, *, encoding=None, errors=None)

シェル中の cmd を実行して出力 (stdout と stderr) を返します。

getstatusoutput() に似ていますが、終了コードは無視され、コマンドの出力のみを返します。例えば:

>>> subprocess.getoutput('ls /bin/ls')
'/bin/ls'

Availability: Unix, Windows。

バージョン 3.3.4 で変更: Windowsで利用可能になりました

バージョン 3.11 で変更: Added the encoding and errors parameters.

注釈

Windows における引数シーケンスから文字列への変換

Windows では、 args シーケンスは以下の (MS C ランタイムで使われる規則に対応する) 規則を使って解析できる文字列に変換されます:

引数は、スペースかタブのどちらかの空白で分けられます。

ダブルクオーテーションマークで囲まれた文字列は、空白が含まれていたとしても 1 つの引数として解釈されます。クオートされた文字列は引数に埋め込めます。

バックスラッシュに続くダブルクオーテーションマークは、リテラルのダブルクオーテーションマークと解釈されます。

バックスラッシュは、ダブルクオーテーションが続かない限り、リテラルとして解釈されます。

複数のバックスラッシュにダブルクオーテーションマークが続くなら、バックスラッシュ 2 つで 1 つのバックスラッシュ文字と解釈されます。バックスラッシュの数が奇数なら、最後のバックスラッシュは規則 3 に従って続くダブルクオーテーションマークをエスケープします。

参考

shlex

コマンドラインを解析したりエスケープしたりする関数を提供するモジュール。

Disabling use of vfork() or posix_spawn()

On Linux, subprocess defaults to using the vfork() system call internally when it is safe to do so rather than fork(). This greatly improves performance.

If you ever encounter a presumed highly unusual situation where you need to prevent vfork() from being used by Python, you can set the subprocess._USE_VFORK attribute to a false value.

subprocess._USE_VFORK = False  # See CPython issue gh-NNNNNN.

Setting this has no impact on use of posix_spawn() which could use vfork() internally within its libc implementation. There is a similar subprocess._USE_POSIX_SPAWN attribute if you need to prevent use of that.

subprocess._USE_POSIX_SPAWN = False  # See CPython issue gh-NNNNNN.

It is safe to set these to false on any Python version. They will have no effect on older versions when unsupported. Do not assume the attributes are available to read. Despite their names, a true value does not indicate that the corresponding function will be used, only that it may be.

Please file issues any time you have to use these private knobs with a way to reproduce the issue you were seeing. Link to that issue from a comment in your code.

Added in version 3.8: _USE_POSIX_SPAWN

Added in version 3.11: _USE_VFORK

sched --- Event scheduler

ソースコード: Lib/sched.py [https://github.com/python/cpython/tree/3.12/Lib/sched.py]

sched モジュールは一般的な目的のためのイベントスケジューラを実装するクラスを定義します:

class sched.scheduler(timefunc=time.monotonic, delayfunc=time.sleep)

scheduler クラスはイベントをスケジュールするための一般的なインターフェースを定義します。それは "外の世界" を実際に扱うための2つの関数を必要とします --- timefunc は引数なしで呼ばれて 1 つの数値を返す callable オブジェクトでなければなりません (戻り値は任意の単位で「時間」を表します)。 delayfunc は 1 つの引数を持つ callable オブジェクトでなければならず、その時間だけ遅延する必要があります (引数は timefunc の出力と互換)。 delayfunc は、各々のイベントが実行された後に引数 0 で呼ばれることがあります。これは、マルチスレッドアプリケーションの中で他のスレッドが実行する機会を与えるためです。

バージョン 3.3 で変更: timefunc と delayfunc がオプション引数になりました。

バージョン 3.3 で変更: scheduler クラスをマルチスレッド環境で安全に使用出来るようになりました。

以下はプログラム例です:

>>> import sched, time
>>> s = sched.scheduler(time.time, time.sleep)
>>> def print_time(a='default'):
...     print("From print_time", time.time(), a)
...
>>> def print_some_times():
...     print(time.time())
...     s.enter(10, 1, print_time)
...     s.enter(5, 2, print_time, argument=('positional',))
...     # despite having higher priority, 'keyword' runs after 'positional' as enter() is relative
...     s.enter(5, 1, print_time, kwargs={'a': 'keyword'})
...     s.enterabs(1_650_000_000, 10, print_time, argument=("first enterabs",))
...     s.enterabs(1_650_000_000, 5, print_time, argument=("second enterabs",))
...     s.run()
...     print(time.time())
...
>>> print_some_times()
1652342830.3640375
From print_time 1652342830.3642538 second enterabs
From print_time 1652342830.3643398 first enterabs
From print_time 1652342835.3694863 positional
From print_time 1652342835.3696074 keyword
From print_time 1652342840.369612 default
1652342840.3697174

スケジューラオブジェクト

scheduler インスタンスは以下のメソッドと属性を持っています:

scheduler.enterabs(time, priority, action, argument=(), kwargs={})

新しいイベントをスケジュールします。引数 time は、コンストラクタへ渡された timefunc の戻り値と互換な数値型でなければいけません。同じ time によってスケジュールされたイベントは、それらの priority によって実行されます。数値の小さい方が高い優先度となります。

イベントを実行することは、 action(*argument, **kwargs) を実行することを意味します。 argument は action のための位置引数を保持するシーケンスでなければいけません。 kwargs は action のためのキーワード引数を保持する辞書でなければいけません。

戻り値は、後にイベントをキャンセルする時に使われる可能性のあるイベントです (cancel() を参照)。

バージョン 3.3 で変更: argument 引数が任意になりました。

バージョン 3.3 で変更: kwargs 引数が追加されました。

scheduler.enter(delay, priority, action, argument=(), kwargs={})

時間単位以上の delay でイベントをスケジュールします。相対的時間以外の、引数、効果、戻り値は、 enterabs() に対するものと同じです。

バージョン 3.3 で変更: argument 引数が任意になりました。

バージョン 3.3 で変更: kwargs 引数が追加されました。

scheduler.cancel(event)

キューからイベントを消去します。もし event がキューにある現在のイベントでないならば、このメソッドは ValueError を送出します。

scheduler.empty()

もしイベントキューが空ならば、 True を返します。

scheduler.run(blocking=True)

Run all scheduled events. This method will wait (using the delayfunc function passed to the constructor) for the next event, then execute it and so on until there are no more scheduled events.

blocking が False の場合、最も早く期限が来るスケジュールされたイベントを (存在する場合) 実行し、スケジューラ内で次にスケジュールされた呼び出しの期限を (存在する場合) 返します。

action あるいは delayfunc は例外を投げることができます。いずれの場合も、スケジューラは一貫した状態を維持し、例外を伝播するでしょう。例外が action によって投げられる場合、イベントは run() への呼出しを未来に行なわないでしょう。

イベントのシーケンスが、次イベントの前に、利用可能時間より実行時間が長いと、スケジューラは単に遅れることになるでしょう。イベントが落ちることはありません; 呼出しコードはもはや適切でないキャンセルイベントに対して責任があります。

バージョン 3.3 で変更: blocking 引数が追加されました。

scheduler.queue

読み出し専用の属性で、これから起こるイベントが実行される順序で格納されたリストを返します。各イベントは、次の属性 time, priority, action, argument, kwargs を持った named tuple の形式になります。

queue --- A synchronized queue class

ソースコード: Lib/queue.py [https://github.com/python/cpython/tree/3.12/Lib/queue.py]

queue モジュールは、複数プロデューサ-複数コンシューマ(multi-producer, multi-consumer)キューを実装します。これは、複数のスレッドの間で情報を安全に交換しなければならないときのマルチスレッドプログラミングで特に有益です。このモジュールの Queue クラスは、必要なすべてのロックセマンティクスを実装しています。

このモジュールでは3種類のキューが実装されています。それらはキューから取り出されるエントリの順番だけが違います。 FIFO キューでは、最初に追加されたエントリが最初に取り出されます。 LIFO キューでは、最後に追加されたエントリが最初に取り出されます(スタックのように振る舞います)。 優先順位付きキュー(priority queue)では、エントリは(heapq モジュールを利用して)ソートされ、 最も低い値のエントリが最初に取り出されます。

内部的には、これらの3種類のキューは競争スレッドを一時的にブロックするためにロックを使っています; しかし、スレッド内での再入を扱うようには設計されていません。

In addition, the module implements a "simple" FIFO queue type, SimpleQueue, whose specific implementation provides additional guarantees in exchange for the smaller functionality.

queue モジュールは以下のクラスと例外を定義します:

class queue.Queue(maxsize=0)

FIFO キューのコンストラクタです。 maxsize はキューに入れられる要素数の上限を設定する整数です。いったんこの大きさに達したら、挿入処理はキューの要素が消費されるまでブロックされます。 maxsize が0以下の場合は、キューの大きさは無限です。

class queue.LifoQueue(maxsize=0)

LIFO キューのコンストラクタです。 maxsize はキューに入れられる要素数の上限を設定する整数です。いったんこの大きさに達したら、挿入処理はキューの要素が消費されるまでブロックされます。 maxsize が0以下の場合は、キューの大きさは無限です。

class queue.PriorityQueue(maxsize=0)

優先順位付きキューのコンストラクタです。maxsize はキューに置くことのできる要素数の上限を設定する整数です。いったんこの大きさに達したら、挿入はキューの要素が消費されるまでブロックされます。もし maxsize が0以下であるならば、キューの大きさは無限です。

最小の値を持つ要素が最初に検索されます (最小の値を持つ値は、min(entries) によって返されるものです)。典型的な要素のパターンは、(priority_number, data) 形式のタプルです。

If the data elements are not comparable, the data can be wrapped in a class that ignores the data item and only compares the priority number:

from dataclasses import dataclass, field
from typing import Any

@dataclass(order=True)
class PrioritizedItem:
    priority: int
    item: Any=field(compare=False)

class queue.SimpleQueue

Constructor for an unbounded FIFO queue. Simple queues lack advanced functionality such as task tracking.

Added in version 3.7.

exception queue.Empty

空の Queue オブジェクトで、非ブロックメソッド get() (または get_nowait()) が呼ばれたとき、送出される例外です。

exception queue.Full

満杯の Queue オブジェクトで、非ブロックメソッド put() (または put_nowait()) が呼ばれたとき、送出される例外です。

キューオブジェクト

キューオブジェクト(Queue, LifoQueue, PriorityQueue)は、以下のpublicメソッドを提供しています。

Queue.qsize()

キューの近似サイズを返します。ここで、qsize() > 0 は後続の get() がブロックしないことを保証しないこと、また qsize() < maxsize が put() がブロックしないことを保証しないことに注意してください。

Queue.empty()

キューが空の場合は True を返し、そうでなければ False を返します。empty() が True を返しても、後続の put() の呼び出しがブロックしないことは保証されません。同様に、empty() が False を返しても、後続の get() の呼び出しがブロックしないことは保証されません。

Queue.full()

キューが一杯の場合は True を返し、そうでなければ False を返します。full() が True を返しても、後続の get() の呼び出しがブロックしないことは保証されません。同様に、full() が False を返しても、後続の put() の呼び出しがブロックしないことは保証されません。

Queue.put(item, block=True, timeout=None)

item をキューに入れます。もしオプション引数 block が真で timeout が None (デフォルト) の場合は、必要であればフリースロットが利用可能になるまでブロックします。 timeout が正の数の場合は、最大で timeout 秒間ブロックし、その時間内に空きスロットが利用可能にならなければ、例外 Full を送出します。そうでない場合 (block が偽) は、空きスロットが直ちに利用できるならば、キューにアイテムを置きます。できないならば、例外 Full を送出します (この場合 timeout は無視されます)。

Queue.put_nowait(item)

put(item, block=False) と等価です。

Queue.get(block=True, timeout=None)

キューからアイテムを取り除き、それを返します。オプション引数 block が真で timeout が None (デフォルト) の場合は、必要であればアイテムが取り出せるようになるまでブロックします。もし timeout が正の数の場合は、最大で timeout 秒間ブロックし、その時間内でアイテムが取り出せるようにならなければ、例外 Empty を送出します。そうでない場合 (block が偽) は、直ちにアイテムが取り出せるならば、それを返します。できないならば、例外 Empty を送出します (この場合 timeout は無視されます)。

Prior to 3.0 on POSIX systems, and for all versions on Windows, if block is true and timeout is None, this operation goes into an uninterruptible wait on an underlying lock. This means that no exceptions can occur, and in particular a SIGINT will not trigger a KeyboardInterrupt.

Queue.get_nowait()

get(False) と等価です。

キューに入れられたタスクが全てコンシューマスレッドに処理されたかどうかを追跡するために 2つのメソッドが提供されます。

Queue.task_done()

過去にキューに入れられたタスクが完了した事を示します。キューのコンシューマスレッドに利用されます。タスクの取り出しに使われた各 get() の後に task_done() を呼び出すと、取り出したタスクに対する処理が完了した事をキューに教えます。

join() がブロックされていた場合、全itemが処理された (キューに put() された全てのitemに対して task_done() が呼び出されたことを意味します) 時に復帰します。

キューにある要素より多く呼び出された場合 ValueError が発生します。

Queue.join()

キューにあるすべてのアイテムが取り出されて処理されるまでブロックします。

未完了のタスクのカウント値はキューにアイテムが追加されるときは常に加算され、コンシューマースレッドが task_done() を呼び出してアイテムの回収とその全処理の完了が示されるときは常に減算されます。未完了のタスクのカウント値がゼロになった場合、join() のブロックが解除されます。

キューに入れたタスクが完了するのを待つ例:

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')

SimpleQueue オブジェクト

SimpleQueue オブジェクトは以下のpublicメソッドを提供しています。

SimpleQueue.qsize()

キューの近似サイズを返します。ここで、qsize() > 0 であるからといって、後続の get() の呼び出しがブロックしないことが保証されないことに注意してください。

SimpleQueue.empty()

キューが空の場合は True を返し、そうでなければ False を返します。 empty() が False を返しても、後続の get() の呼び出しがブロックしないことは保証されません。

SimpleQueue.put(item, block=True, timeout=None)

Put item into the queue. The method never blocks and always succeeds (except for potential low-level errors such as failure to allocate memory). The optional args block and timeout are ignored and only provided for compatibility with Queue.put().

CPython 実装の詳細: This method has a C implementation which is reentrant. That is, a put() or get() call can be interrupted by another put() call in the same thread without deadlocking or corrupting internal state inside the queue. This makes it appropriate for use in destructors such as __del__ methods or weakref callbacks.

SimpleQueue.put_nowait(item)

put(item, block=False) と等価です。Queue.put_nowait() との互換性のためのメソッドです。

SimpleQueue.get(block=True, timeout=None)

キューからアイテムを取り除き、それを返します。オプション引数 block が真で timeout が None (デフォルト) の場合は、必要であればアイテムが取り出せるようになるまでブロックします。もし timeout が正の数の場合は、最大で timeout 秒間ブロックし、その時間内でアイテムが取り出せるようにならなければ、例外 Empty を送出します。そうでない場合 (block が偽) は、直ちにアイテムが取り出せるならば、それを返します。できないならば、例外 Empty を送出します (この場合 timeout は無視されます)。

SimpleQueue.get_nowait()

get(False) と等価です。

参考

multiprocessing.Queue クラス

(マルチスレッドではなく) マルチプロセスの文脈で使用されるキュークラス。

collections.deque is an alternative implementation of unbounded queues with fast atomic append() and popleft() operations that do not require locking and also support indexing.

contextvars --- Context Variables

このモジュールは、コンテキストローカルな状態を管理し、保持し、アクセスするための API を提供します。 ContextVar クラスは コンテキスト変数 を宣言し、取り扱うために使われます。非同期フレームワークで現時点のコンテキストを管理するのには、 copy_context() 関数と Context クラスを使うべきです。

状態を持っているコンテキストマネージャは threading.local() ではなくコンテキスト変数を使い、並行処理のコードから状態が意図せず他のコードへ漏れ出すのを避けるべきです。

より詳しくは PEP 567 [https://peps.python.org/pep-0567/] を参照をしてください。

Added in version 3.7.

コンテキスト変数

class contextvars.ContextVar(name[, *, default])

このクラスは新しいコンテキスト変数を宣言するのに使われます。例えば、次の通りです:

var: ContextVar[int] = ContextVar('var', default=42)

必須のパラメータの name は内観やデバッグの目的で使われます。

オプションのキーワード専用引数 default は、現在のコンテキストにその変数の値が見付からなかったときに ContextVar.get() から返されます。

重要: コンテキスト変数は、モジュールのトップレベルで生成する必要があり、クロージャの中で作成すべきではありません。Context オブジェクトはコンテキスト変数への強参照を持っており、コンテキスト変数がガーベジコレクトされるのを防ぎます。

name

変数の名前。読み出し専用のプロパティです。

Added in version 3.7.1.

get([default])

現在のコンテキストのコンテキスト変数の値を返します。

現在のコンテキストのコンテキスト変数に値がなければ、メソッドは:

メソッドの default 引数に値が指定されていればその値を返します。さもなければ

コンテキスト変数が生成された時にデフォルト値が渡されていれば、その値を返します。さもなければ

LookupError を送出します。

set(value)

現在のコンテキストのコンテキスト変数に新しい値を設定する際に呼び出します。

value は必須の引数で、コンテキスト変数の新しい値を指定します。

Token オブジェクトを返します。このオブジェクトを ContextVar.reset() メソッドに渡すことで、以前の値に戻すことができます。

reset(token)

コンテキスト変数の値を、 token を生成した ContextVar.set() が呼び出される前の値にリセットします。

例えば:

var = ContextVar('var')

token = var.set('new value')
# code that uses 'var'; var.get() returns 'new value'.
var.reset(token)

# After the reset call the var has no value again, so
# var.get() would raise a LookupError.

class contextvars.Token

Token オブジェクトは、ContextVar.set() メソッドによって返されるオブジェクトです。このオブジェクトを ContextVar.reset() メソッドに渡すことで、対応する set を呼び出す前のコンテキスト変数の値に戻せます。

var

読み出し専用のプロパティです。トークンを生成した ContextVar オブジェクトを指します。

old_value

読み出し専用のプロパティです。このトークンを作成した ContextVar.set() メソッドの呼び出しの前に持っていた値に設定されています。もし呼び出しの前に値が設定されていなければ Token.MISSING を指します。

MISSING

Token.old_value で利用されるマーカーオブジェクトです。

マニュアルでのコンテキスト管理

contextvars.copy_context()

現在の Context オブジェクトのコピーを返します。

次のスニペットは、現在のコンテキストのコピーを取得し、コンテキストに設定されているすべての変数とその値を表示します:

ctx: Context = copy_context()
print(list(ctx.items()))

The function has an O(1) complexity, i.e. works equally fast for contexts with a few context variables and for contexts that have a lot of them.

class contextvars.Context

ContextVars とその値の対応付け。

Context() は、値を持たない空のコンテキストを生成します。現在のコンテキストのコピーを得るには、copy_context() 関数を利用します。

Every thread will have a different top-level Context object. This means that a ContextVar object behaves in a similar fashion to threading.local() when values are assigned in different threads.

Context は、 collections.abc.Mapping インターフェースを実装します。

run(callable, *args, **kwargs)

callable(*args, **kwargs) を run メソッドが呼ばれたコンテキストオブジェクトの中で実行します。実行した結果を返すか、例外が発生した場合はその例外を伝播します。

callable が行ったコンテキスト変数へのいかなる変更も、コンテキストオブジェクトに格納されます:

var = ContextVar('var')
var.set('spam')

def main():
    # 'var' was set to 'spam' before
    # calling 'copy_context()' and 'ctx.run(main)', so:
    # var.get() == ctx[var] == 'spam'

    var.set('ham')

    # Now, after setting 'var' to 'ham':
    # var.get() == ctx[var] == 'ham'

ctx = copy_context()

# Any changes that the 'main' function makes to 'var'
# will be contained in 'ctx'.
ctx.run(main)

# The 'main()' function was run in the 'ctx' context,
# so changes to 'var' are contained in it:
# ctx[var] == 'ham'

# However, outside of 'ctx', 'var' is still set to 'spam':
# var.get() == 'spam'

2つ以上の OS スレッドから同一のコンテキストオブジェクトを呼び出すか、再帰的に呼び出したとき、メソッドは RuntimeError を送出します。

copy()

コンテキストオブジェクトの浅いコピーを返します。

var in context

context に var の値が設定されていた場合 True を返します; そうでない場合は False を返します。

context[var]

ContextVar var の値を返します。コンテキストオブジェクト内で変数が設定されていない場合は、KeyError を送出します。

get(var[, default])

var がコンテキストオブジェクトの中に値を持てば、その値を返します。さもなければ、default を返します。default を指定していなければ、None を返します。

iter(context)

コンテキストオブジェクトに格納されている変数群のイテレータを返します。

len(proxy)

コンテキストオブジェクトに格納されている変数の数を返します。

keys()

コンテキストオブジェクト中のすべての変数のリストを返します。

values()

コンテキストオブジェクト中のすべての変数の値のリストを返します。

items()

コンテキストオブジェクト中のすべての変数について、変数とその値からなる2要素のタプルのリストを返します。

asyncio サポート

コンテキスト変数は、追加の設定なしに asyncio をサポートします。例えば、次の単純なechoサーバーは、クライアントを扱う Task の中でリモートクライアントのアドレスが利用できるように、コンテキスト変数を利用します:

import asyncio
import contextvars

client_addr_var = contextvars.ContextVar('client_addr')

def render_goodbye():
    # The address of the currently handled client can be accessed
    # without passing it explicitly to this function.

    client_addr = client_addr_var.get()
    return f'Good bye, client @ {client_addr}\n'.encode()

async def handle_request(reader, writer):
    addr = writer.transport.get_extra_info('socket').getpeername()
    client_addr_var.set(addr)

    # In any code that we call is now possible to get
    # client's address by calling 'client_addr_var.get()'.

    while True:
        line = await reader.readline()
        print(line)
        if not line.strip():
            break
        writer.write(line)

    writer.write(render_goodbye())
    writer.close()

async def main():
    srv = await asyncio.start_server(
        handle_request, '127.0.0.1', 8081)

    async with srv:
        await srv.serve_forever()

asyncio.run(main())

# To test it you can use telnet:
#     telnet 127.0.0.1 8081

_thread --- Low-level threading API

このモジュールはマルチスレッド (別名 軽量プロセス (light-weight processes)または タスク (tasks)) に用いられる低水準プリミティブを提供します --- グローバルデータ空間を共有するマルチスレッドを制御します。同期のための単純なロック (別名 mutexes またはバイナリセマフォ (binary semaphores))が提供されています。 threading モジュールは、このモジュール上で、より使い易く高級なスレッディングの API を提供します。

バージョン 3.7 で変更: このモジュールは以前はオプションでしたが、常に利用可能なモジュールとなりました。

このモジュールでは以下の定数および関数を定義しています:

exception _thread.error

スレッド固有の例外です。

バージョン 3.3 で変更: 現在は組み込みの RuntimeError の別名です。

_thread.LockType

これはロックオブジェクトのタイプです。

_thread.start_new_thread(function, args[, kwargs])

新しいスレッドを開始して、そのIDを返します。スレッドは引数リスト args (タプルでなければなりません)の関数 function を実行します。オプション引数 kwargs はキーワード引数の辞書を指定します。

関数が戻るとき、スレッドは静かに終了します。

When the function terminates with an unhandled exception, sys.unraisablehook() is called to handle the exception. The object attribute of the hook argument is function. By default, a stack trace is printed and then the thread exits (but other threads continue to run).

When the function raises a SystemExit exception, it is silently ignored.

Raises an auditing event _thread.start_new_thread with arguments function, args, kwargs.

バージョン 3.8 で変更: sys.unraisablehook() is now used to handle unhandled exceptions.

_thread.interrupt_main(signum=signal.SIGINT, /)

Simulate the effect of a signal arriving in the main thread. A thread can use this function to interrupt the main thread, though there is no guarantee that the interruption will happen immediately.

If given, signum is the number of the signal to simulate. If signum is not given, signal.SIGINT is simulated.

If the given signal isn't handled by Python (it was set to signal.SIG_DFL or signal.SIG_IGN), this function does nothing.

バージョン 3.10 で変更: The signum argument is added to customize the signal number.

注釈

This does not emit the corresponding signal but schedules a call to the associated handler (if it exists). If you want to truly emit the signal, use signal.raise_signal().

_thread.exit()

SystemExit を送出します。それが捕えられないときは、静かにスレッドを終了させます。

_thread.allocate_lock()

新しいロックオブジェクトを返します。ロックのメソッドはこの後に記述されます。ロックは初期状態としてアンロック状態です。

_thread.get_ident()

現在のスレッドの 'スレッドID' を返します。非ゼロの整数です。この値は直接の意味を持っていません; 例えばスレッド特有のデータの辞書に索引をつけるためのような、マジッククッキーとして意図されています。スレッドが終了し、他のスレッドが作られたとき、スレッド ID は再利用されるかもしれません。

_thread.get_native_id()

Return the native integral Thread ID of the current thread assigned by the kernel. This is a non-negative integer. Its value may be used to uniquely identify this particular thread system-wide (until the thread terminates, after which the value may be recycled by the OS).

Availability: Windows, FreeBSD, Linux, macOS, OpenBSD, NetBSD, AIX, DragonFlyBSD.

Added in version 3.8.

_thread.stack_size([size])

新しいスレッドを作るときのスレッドスタックサイズを返します。オプションの size 引数にはこれ以降に作成するスレッドのスタックサイズを指定し、0 (プラットフォームのデフォルト値または設定されたデフォルト値) か、 32,768 (32 KiB) 以上の正の整数でなければなりません。size が指定されない場合 0 が使われます。スレッドのスタックサイズの変更がサポートされていない場合、 RuntimeError を送出します。不正なスタックサイズが指定された場合、 ValueError を送出して、スタックサイズは変更されません。32 KiB は現在のインタープリタ自身のために十分であると保証された最小のスタックサイズです。いくつかのプラットフォームではスタックサイズに対して制限があることに注意してください。例えば最小のスタックサイズが 32 KiB より大きかったり、システムのメモリページサイズ の整数倍の必要があるなどです。この制限についてはプラットフォームのドキュメントを参照してください (一般的なページサイズは 4 KiB なので、プラットフォームに関する情報がない場合は 4096 の整数倍のスタックサイズを選ぶといいかもしれません)。

利用可能な環境: Windows, pthreads。

Unix platforms with POSIX threads support.

_thread.TIMEOUT_MAX

The maximum value allowed for the timeout parameter of Lock.acquire. Specifying a timeout greater than this value will raise an OverflowError.

Added in version 3.2.

ロックオブジェクトは次のようなメソッドを持っています:

lock.acquire(blocking=True, timeout=-1)

オプションの引数なしで使用すると、このメソッドは他のスレッドがロックしているかどうかにかかわらずロックを獲得します。ただし、他のスレッドがすでにロックしている場合には解除されるまで待ってからロックを獲得します (同時にロックを獲得できるスレッドはひとつだけであり、これこそがロックの存在理由です)。

If the blocking argument is present, the action depends on its value: if it is false, the lock is only acquired if it can be acquired immediately without waiting, while if it is true, the lock is acquired unconditionally as above.

If the floating-point timeout argument is present and positive, it specifies the maximum wait time in seconds before returning. A negative timeout argument specifies an unbounded wait. You cannot specify a timeout if blocking is false.

なお、ロックを獲得できた場合は True、できなかった場合は False を返します。

バージョン 3.2 で変更: 新しい timeout 引数。

バージョン 3.2 で変更: POSIX ではロックの取得がシグナルに割り込まれるようになりました。

lock.release()

ロックを解放します。そのロックは既に獲得されたものでなければなりませんが、しかし同じスレッドによって獲得されたものである必要はありません。

lock.locked()

ロックの状態を返します: 同じスレッドによって獲得されたものなら True 、違うのなら False を返します。

これらのメソッドに加えて、ロックオブジェクトは with 文を通じて以下の例のように使うこともできます。

import _thread

a_lock = _thread.allocate_lock()

with a_lock:
    print("a_lock is locked while this executes")

警告:

スレッドは割り込みと奇妙な相互作用をします: KeyboardInterrupt 例外は任意のスレッドによって受け取られます。 (signal モジュールが利用可能なとき、割り込みは常にメインスレッドへ行きます。)

sys.exit() を呼び出す、あるいは SystemExit 例外を送出することは、 _thread.exit() を呼び出すことと同じです。

It is not possible to interrupt the acquire() method on a lock --- the KeyboardInterrupt exception will happen after the lock has been acquired.

メインスレッドが終了したとき、他のスレッドが生き残るかどうかは、システムに依存します。多くのシステムでは、 try ... finally 節や、オブジェクトデストラクタを実行せずに終了されます。

メインスレッドが終了したとき、それの通常のクリーンアップは行なわれず、 (try ... finally 節が尊重されることは除きます)、標準 I/O ファイルはフラッシュされません。

ネットワーク通信とプロセス間通信

この章で解説しているモジュールはネットワーク通信とプロセス間通信の仕組みを提供しています。

例えば signal や mmap のように、同じマシン上の 2 つのプロセスでしか使えないモジュールがあります。その他のモジュールは 2 つ以上のプロセスを使ってマシン間で通信できるネットワークプロトコルをサポートします。

この章で解説されるモジュールのリスト:

asyncio --- Asynchronous I/O

socket --- Low-level networking interface

ssl --- TLS/SSL wrapper for socket objects

select --- Waiting for I/O completion

selectors --- High-level I/O multiplexing

signal --- Set handlers for asynchronous events

mmap --- Memory-mapped file support

asyncio --- Asynchronous I/O

Hello World!

import asyncio

async def main():
    print('Hello ...')
    await asyncio.sleep(1)
    print('... World!')

asyncio.run(main())

asyncio は async/await 構文を使い 並行処理の コードを書くためのライブラリです。

asyncio は、高性能なネットワークとウェブサーバ、データベース接続ライブラリ、分散タスクキューなどの複数の非同期 Python フレームワークの基盤として使われています。

asyncio は多くの場合、 IOバウンドだったり高レベルの 構造化された ネットワークコードに完璧に適しています。

asyncio は次の目的で 高レベル API を提供しています:

並行に Python コルーチンを起動 し、実行全体を管理する

ネットワーク IO と IPC を執り行う

subprocesses を管理する

キュー を使ってタスクを分散する

並列処理のコードを 同期 させる

これに加えて、 ライブラリやフレームワークの開発者 が次のことをするための 低レベル API があります:

create and manage event loops, which provide asynchronous APIs for networking, running subprocesses, handling OS signals, etc;

Transport を使った効率的な protocol を実装します

コールバックを用いたライブラリと async/await 構文を使ったコードの 橋渡し

You can experiment with an asyncio concurrent context in the REPL:

$ 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'

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. See WebAssemblyプラットフォーム for more information.

リファレンス

高レベル API

Runners

コルーチンと Task

ストリーム

同期プリミティブ

サブプロセス

キュー

例外

低レベル API

イベントループ

Future

トランスポートとプロトコル

ポリシー

プラットフォームでのサポート

Extending

ガイドとチュートリアル

高水準の API インデックス

低水準の API インデックス

asyncio での開発

注釈

asyncio のソースコードは Lib/asyncio/ [https://github.com/python/cpython/tree/3.12/Lib/asyncio/] にあります。

Runners

Source code: Lib/asyncio/runners.py [https://github.com/python/cpython/tree/3.12/Lib/asyncio/runners.py]

この節では、asyncio のコードを実行するための高レベルの asyncio のプリミティブの概略を解説します。

これらは イベントループ の上に構築されており、一般的な広く普及しているシナリオでの非同期コードの使用を簡素化することを目的としています。

非同期プログラムの実行

Runner context manager

Handling Keyboard Interruption

非同期プログラムの実行

asyncio.run(coro, *, debug=None, loop_factory=None)

coroutine coro を実行し、結果を返します。

This function runs the passed coroutine, taking care of managing the asyncio event loop, finalizing asynchronous generators, and closing the executor.

この関数は、同じスレッドで他の非同期イベントループが実行中のときは呼び出せません。

debug が True の場合、イベントループはデバッグモードで実行されます。False は明示的にデバッグモードを無効化します。 グローバルな デバッグモード 設定を尊重するために None が使用されます。

If loop_factory is not None, it is used to create a new event loop; otherwise asyncio.new_event_loop() is used. The loop is closed at the end. This function should be used as a main entry point for asyncio programs, and should ideally only be called once. It is recommended to use loop_factory to configure the event loop instead of policies.

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.

以下はプログラム例です:

async def main():
    await asyncio.sleep(1)
    print('hello')

asyncio.run(main())

Added in version 3.7.

バージョン 3.9 で変更: loop.shutdown_default_executor() メソッドを使うように更新されました。

バージョン 3.10 で変更: debug はグローバルなデバッグモード設定を尊重するためにデフォルトで None です。

バージョン 3.12 で変更: Added loop_factory parameter.

Runner context manager

class asyncio.Runner(*, debug=None, loop_factory=None)

同じコンテキスト上での 複数 の非同期関数呼び出しをシンプルにするコンテキストマネージャ。

Sometimes several top-level async functions should be called in the same event loop and contextvars.Context.

debug が True の場合、イベントループはデバッグモードで実行されます。False は明示的にデバッグモードを無効化します。 グローバルな デバッグモード 設定を尊重するために None が使用されます。

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 asyncio.new_event_loop() is used and set as current event loop with asyncio.set_event_loop() if loop_factory is None.

Basically, asyncio.run() example can be rewritten with the runner usage:

async def main():
    await asyncio.sleep(1)
    print('hello')

with asyncio.Runner() as runner:
    runner.run(main())

Added in version 3.11.

run(coro, *, context=None)

Run a coroutine coro in the embedded loop.

Return the coroutine's result or raise its exception.

An optional keyword-only context argument allows specifying a custom contextvars.Context for the coro to run in. The runner's default context is used if None.

この関数は、同じスレッドで他の非同期イベントループが実行中のときは呼び出せません。

close()

Close the runner.

Finalize asynchronous generators, shutdown default executor, close the event loop and release embedded contextvars.Context.

get_loop()

Return the event loop associated with the runner instance.

注釈

Runner uses the lazy initialization strategy, its constructor doesn't initialize underlying low-level structures.

Embedded loop and context are created at the with body entering or the first call of run() or get_loop().

Handling Keyboard Interruption

Added in version 3.11.

When signal.SIGINT is raised by Ctrl-C, KeyboardInterrupt exception is raised in the main thread by default. However this doesn't work with asyncio because it can interrupt asyncio internals and can hang the program from exiting.

To mitigate this issue, asyncio handles signal.SIGINT as follows:

asyncio.Runner.run() installs a custom signal.SIGINT handler before any user code is executed and removes it when exiting from the function.

The Runner creates the main task for the passed coroutine for its execution.

When signal.SIGINT is raised by Ctrl-C, the custom signal handler cancels the main task by calling asyncio.Task.cancel() which raises asyncio.CancelledError inside the main task. This causes the Python stack to unwind, try/except and try/finally blocks can be used for resource cleanup. After the main task is cancelled, asyncio.Runner.run() raises KeyboardInterrupt.

A user could write a tight loop which cannot be interrupted by asyncio.Task.cancel(), in which case the second following Ctrl-C immediately raises the KeyboardInterrupt without cancelling the main task.

コルーチンと Task

この節では、コルーチンと Task を利用する高レベルの asyncio の API の概略を解説します。

コルーチン

Awaitable

Task の作成

タスクのキャンセル

Task Groups

スリープ

並行な Task 実行

Eager Task Factory

キャンセルからの保護

タイムアウト

要素の終了待機

スレッド内での実行

外部スレッドからのスケジュール

イントロスペクション

Task オブジェクト

コルーチン

Source code: Lib/asyncio/coroutines.py [https://github.com/python/cpython/tree/3.12/Lib/asyncio/coroutines.py]

async/await 構文で宣言された コルーチン は、 asyncio を使ったアプリケーションを書くのに推奨される方法です。例えば、次のコードスニペットは "hello" を出力し、そこから 1 秒待って "world" を出力します:

>>> import asyncio

>>> async def main():
...     print('hello')
...     await asyncio.sleep(1)
...     print('world')

>>> asyncio.run(main())
hello
world

単にコルーチンを呼び出しただけでは、コルーチンの実行スケジュールは予約されていないことに注意してください:

>>> main()
<coroutine object main at 0x1053bb7c8>

実際にコルーチンを実行するために、asyncio は以下のメカニズムを提供しています:

最上位のエントリーポイントである "main()" 関数を実行する asyncio.run() 関数 (上の例を参照してください。)

コルーチンを await すること。次のコード片は 1 秒間待機した後に "hello" と出力し、 更に 2 秒間待機してから "world" と出力します:

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())

予想される出力:

started at 17:13:52
hello
world
finished at 17:13:55

asyncio の Tasks としてコルーチンを並行して走らせる asyncio.create_task() 関数。

上のコード例を編集して、ふたつの say_after コルーチンを 並行して 走らせてみましょう:

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')}")

予想される出力が、スニペットの実行が前回よりも 1 秒早いことを示していることに注意してください:

started at 17:14:32
hello
world
finished at 17:14:34

The asyncio.TaskGroup class provides a more modern alternative to create_task(). Using this API, the last example becomes:

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')}")

The timing and output should be the same as for the previous version.

Added in version 3.11: asyncio.TaskGroup.

Awaitable

あるオブジェクトを await 式の中で使うことができる場合、そのオブジェクトを awaitable オブジェクトと言います。多くの asyncio API は awaitable を受け取るように設計されています。

awaitable オブジェクトには主に3つの種類があります: コルーチン, Task, そして Future です

コルーチン

Python のコルーチンは awaitable であり、他のコルーチンから待機されることができます:

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()

    # Let's do it differently now and await it:
    print(await nested())  # will print "42".

asyncio.run(main())

重要

このドキュメントにおいて「コルーチン」という用語は以下2つの密接に関連した概念に対して使用できます:

コルーチン関数: async def 関数;

コルーチンオブジェクト: コルーチン関数 を呼び出すと返ってくるオブジェクト.

Task

Task は、コルーチンを 並行に スケジュールするのに使います。

asyncio.create_task() のような関数で、コルーチンが Task にラップされているとき、自動的にコルーチンは即時実行されるようにスケジュールされます:

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())

Future

Future は、非同期処理の 最終結果 を表現する特別な 低レベルの awaitable オブジェクトです。

Future オブジェクトが 待機 (await) されている とは、Future がどこか他の場所で解決されるまでコルーチンが待機するということです。

asyncioのFutureオブジェクトを使うと、async/awaitとコールバック形式のコードを併用できます。

通常、アプリケーション水準のコードで Future オブジェクトを作る 必要はありません 。

Future オブジェクトはライブラリや asyncio のAPIで外部に提供されることもあり、await （待機）されることができます:

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()
    )

Future オブジェクトを返す低レベル関数の良い例は loop.run_in_executor() です。

Task の作成

ソースコード: Lib/asyncio/tasks.py [https://github.com/python/cpython/tree/3.12/Lib/asyncio/tasks.py]

asyncio.create_task(coro, *, name=None, context=None)

coro coroutine を Task でラップし、その実行をスケジュールします。 Task オブジェクトを返します。

もし name が None でない場合、Task.set_name() を使用し、name がタスクの名前として設定されます。

省略可能なキーワード引数 context によって、coro を実行するためのカスタムの contextvars.Context を指定できます。context が省略された場合、現在のコンテキストのコピーが作成されます。

その Task オブジェクトは get_running_loop() から返されたループの中で実行されます。現在のスレッドに実行中のループが無い場合は、 RuntimeError が送出されます。

注釈

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.

重要

タスクが実行中に消えないように、この関数の結果の参照を保存してください。イベントループは弱い参照のみを保持します。ほかに参照元のないタスクは、完了していなくてもガーベジコレクションされる可能性があります。信頼性のある "fire-and-forget" バックグラウンドタスクが必要な場合、コレクションを使ってください。

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)

Added in version 3.7.

バージョン 3.8 で変更: name パラメータを追加しました。

バージョン 3.11 で変更: context パラメータを追加しました。

タスクのキャンセル

タスクは簡単に、そして安全にキャンセルできます。タスクがキャンセルされた場合、asyncio.CancelledError が次の機会に送出されます。

It is recommended that coroutines use try/finally blocks to robustly perform clean-up logic. In case asyncio.CancelledError is explicitly caught, it should generally be propagated when clean-up is complete. asyncio.CancelledError directly subclasses BaseException so most code will not need to be aware of it.

The asyncio components that enable structured concurrency, like asyncio.TaskGroup and asyncio.timeout(), are implemented using cancellation internally and might misbehave if a coroutine swallows asyncio.CancelledError. Similarly, user code should not generally call uncancel. However, in cases when suppressing asyncio.CancelledError is truly desired, it is necessary to also call uncancel() to completely remove the cancellation state.

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.

class asyncio.TaskGroup

An asynchronous context manager holding a group of tasks. Tasks can be added to the group using create_task(). All tasks are awaited when the context manager exits.

Added in version 3.11.

create_task(coro, *, name=None, context=None)

Create a task in this task group. The signature matches that of asyncio.create_task().

以下はプログラム例です:

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()}")

The 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 tg into one of the coroutines and calling tg.create_task() in that coroutine). Once the last task has finished and the 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 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 async with statement is still active (i.e., __aexit__() hasn't been called yet), the task directly containing the async with statement is also cancelled. The resulting asyncio.CancelledError will interrupt an await, but it will not bubble out of the containing async with statement.

Once all tasks have finished, if any tasks have failed with an exception other than asyncio.CancelledError, those exceptions are combined in an ExceptionGroup or BaseExceptionGroup (as appropriate; see their documentation) which is then raised.

Two base exceptions are treated specially: If any task fails with KeyboardInterrupt or SystemExit, the task group still cancels the remaining tasks and waits for them, but then the initial KeyboardInterrupt or SystemExit is re-raised instead of ExceptionGroup or BaseExceptionGroup.

If the body of the async with statement exits with an exception (so __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 __aexit__(), unless it is asyncio.CancelledError, is also included in the exception group. The same special case is made for KeyboardInterrupt and SystemExit as in the previous paragraph.

スリープ

coroutine asyncio.sleep(delay, result=None)

delay 秒だけ停止します。

result が提供されている場合は、コルーチン完了時にそれが呼び出し元に返されます。

sleep() は常に現在の Task を一時中断し、他の Task が実行されるのを許可します。

delay を 0 に設定することで、他のタスクを実行可能にする最適な方針を提供します。この方法は、実行時間の長い関数が、その実行時間全体にわたってイベントループをブロックしないようにするために利用できます。

現在の時刻を5秒間、毎秒表示するコルーチンの例:

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())

バージョン 3.10 で変更: loop パラメータが削除されました。

並行な Task 実行

awaitable asyncio.gather(*aws, return_exceptions=False)

aws シーケンスにある awaitable オブジェクト を 並行 実行します。

aws にある awaitable がコルーチンである場合、自動的に Task としてスケジュールされます。

全ての awaitable が正常終了した場合、その結果は返り値を集めたリストになります。返り値の順序は、 aws での awaitable の順序に相当します。

return_exceptions が False である場合(デフォルト)、gather() で await しているタスクに対して、最初の例外が直接伝えられます。aws に並んでいる他の awaitable は、キャンセルされずに 引き続いて実行されます。

return_exceptions が True だった場合、例外は成功した結果と同じように取り扱われ、結果リストに集められます。

gather() が キャンセル された場合、起動された全ての (未完了の) awaitable も キャンセル されます。

aws シーケンスにある Task あるいは Future が キャンセル された場合、 CancelledError を送出したかのうように扱われます。つまり、この場合 gather() 呼び出しはキャンセル されません。これは、起動された 1 つの Task あるいは Future のキャンセルが、他の Task あるいは Future のキャンセルを引き起こすのを避けるためです。

注釈

A new alternative to create and run tasks concurrently and wait for their completion is 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).

以下はプログラム例です:

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]

注釈

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 gather.cancel() after catching an exception (raised by one of the awaitables) from gather won't cancel any other awaitables.

バージョン 3.7 で変更: gather 自身がキャンセルされた場合は、 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.

Eager Task Factory

asyncio.eager_task_factory(loop, coro, *, name=None, context=None)

A task factory for eager task execution.

When using this factory (via loop.set_task_factory(asyncio.eager_task_factory)), coroutines begin execution synchronously during 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.

注釈

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.

Added in version 3.12.

asyncio.create_eager_task_factory(custom_task_constructor)

Create an eager task factory, similar to eager_task_factory(), using the provided custom_task_constructor when creating a new task instead of the default Task.

custom_task_constructor must be a callable with the signature matching the signature of Task.__init__. The callable must return a asyncio.Task-compatible object.

This function returns a callable intended to be used as a task factory of an event loop via loop.set_task_factory(factory)).

Added in version 3.12.

キャンセルからの保護

awaitable asyncio.shield(aw)

キャンセル から awaitable オブジェクト を保護します。

aw がコルーチンだった場合、自動的に Task としてスケジュールされます。

文:

task = asyncio.create_task(something())
res = await shield(task)

は、以下と同じです

res = await something()

それを含むコルーチンがキャンセルされた場合を 除き、something() 内で動作している Task はキャンセルされません。 something() 側から見るとキャンセルは発生しません。呼び出し元がキャンセルされた場合でも、 "await" 式は CancelledError を送出します。

注意: something() が他の理由 (例えば、原因が自分自身) でキャンセルされた場合は shield() でも保護できません。

完全にキャンセルを無視したい場合 (推奨はしません) は、 shield() 関数は次のように try/except 節と組み合わせることになるでしょう:

task = asyncio.create_task(something())
try:
    res = await shield(task)
except CancelledError:
    res = None

重要

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.

バージョン 3.10 で変更: loop パラメータが削除されました。

バージョン 3.10 で非推奨: Deprecation warning is emitted if aw is not Future-like object and there is no running event loop.

タイムアウト

asyncio.timeout(delay)

Return an asynchronous context manager that can be used to limit the amount of time spent waiting on something.

delay can either be None, or a float/int number of seconds to wait. If delay is 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 Timeout.reschedule().

以下はプログラム例です:

async def main():
    async with asyncio.timeout(10):
        await long_running_task()

If long_running_task takes more than 10 seconds to complete, the context manager will cancel the current task and handle the resulting asyncio.CancelledError internally, transforming it into a TimeoutError which can be caught and handled.

注釈

The asyncio.timeout() context manager is what transforms the asyncio.CancelledError into a TimeoutError, which means the TimeoutError can only be caught outside of the context manager.

Example of catching TimeoutError:

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

The context manager produced by asyncio.timeout() can be rescheduled to a different deadline and inspected.

class asyncio.Timeout(when)

An asynchronous context manager for cancelling overdue coroutines.

when should be an absolute time at which the context should time out, as measured by the event loop's clock:

If when is None, the timeout will never trigger.

If when < loop.time(), the timeout will trigger on the next iteration of the event loop.

when() → float | None

Return the current deadline, or None if the current deadline is not set.

reschedule(when: float | None)

Reschedule the timeout.

expired() → bool

Return whether the context manager has exceeded its deadline (expired).

以下はプログラム例です:

async def main():
    try:
        # We do not know the timeout when starting, so we pass ``None``.
        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.")

Timeout context managers can be safely nested.

Added in version 3.11.

asyncio.timeout_at(when)

Similar to asyncio.timeout(), except when is the absolute time to stop waiting, or None.

以下はプログラム例です:

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

Added in version 3.11.

coroutine asyncio.wait_for(aw, timeout)

aw awaitable が、完了するかタイムアウトになるのを待ちます。

aw がコルーチンだった場合、自動的に Task としてスケジュールされます。

timeout には None もしくは待つ秒数の浮動小数点数か整数を指定できます。 timeout が None の場合、 Future が完了するまで待ちます。

If a timeout occurs, it cancels the task and raises TimeoutError.

Task の キャンセル を避けるためには、 shield() の中にラップしてください。

この関数は future が実際にキャンセルされるまで待つため、待ち時間の合計は timeout を超えることがあります。キャンセル中に例外が発生した場合は、その例外は伝達されます。

待機が中止された場合 aw も中止されます。

以下はプログラム例です:

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!

バージョン 3.7 で変更: When aw is cancelled due to a timeout, wait_for waits for aw to be cancelled. Previously, it raised TimeoutError immediately.

バージョン 3.10 で変更: loop パラメータが削除されました。

バージョン 3.11 で変更: Raises TimeoutError instead of asyncio.TimeoutError.

要素の終了待機

coroutine asyncio.wait(aws, *, timeout=None, return_when=ALL_COMPLETED)

Run Future and Task instances in the aws iterable concurrently and block until the condition specified by return_when.

イテラブル aws は空であってはなりません。

Task/Future からなる 2 つの集合 (done, pending) を返します。

使い方:

done, pending = await asyncio.wait(aws)

timeout (浮動小数点数または整数) が指定されていたら、処理を返すのを待つ最大秒数を制御するのに使われます。

Note that this function does not raise TimeoutError. Futures or Tasks that aren't done when the timeout occurs are simply returned in the second set.

return_when でこの関数がいつ結果を返すか指定します。指定できる値は以下の 定数のどれか一つです:

定数

説明

asyncio.FIRST_COMPLETED

いずれかのフューチャが終了したかキャンセルされたときに返します。

asyncio.FIRST_EXCEPTION

The function will return when any future finishes by raising an exception. If no future raises an exception then it is equivalent to ALL_COMPLETED.

asyncio.ALL_COMPLETED

すべてのフューチャが終了したかキャンセルされたときに返します。

wait_for() と異なり、 wait() はタイムアウトが起きたときに Future をキャンセルしません。

バージョン 3.10 で変更: loop パラメータが削除されました。

バージョン 3.11 で変更: Passing coroutine objects to wait() directly is forbidden.

バージョン 3.12 で変更: Added support for generators yielding tasks.

asyncio.as_completed(aws, *, timeout=None)

Run awaitable objects in the aws iterable concurrently. Return an iterator of coroutines. Each coroutine returned can be awaited to get the earliest next result from the iterable of the remaining awaitables.

Raises TimeoutError if the timeout occurs before all Futures are done.

以下はプログラム例です:

for coro in as_completed(aws):
    earliest_result = await coro
    # ...

バージョン 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.

スレッド内での実行

coroutine asyncio.to_thread(func, /, *args, **kwargs)

別のスレッドで非同期的に関数 func を実行します。

この関数に渡された *args と **kwargs は関数 func に直接渡されます。また、イベントループスレッドのコンテキスト変数に関数を実行するスレッドからアクセスできるように、現在の contextvars.Context も伝播されます。

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

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

Directly calling 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 asyncio.to_thread(), we can run it in a separate thread without blocking the event loop.

注釈

Due to the GIL, 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, asyncio.to_thread() can also be used for CPU-bound functions.

Added in version 3.9.

外部スレッドからのスケジュール

asyncio.run_coroutine_threadsafe(coro, loop)

与えられたイベントループにコルーチンを送ります。この処理は、スレッドセーフです。

他の OS スレッドから結果を待つための concurrent.futures.Future を返します。

この関数は、イベントループが動作しているスレッドとは異なる OS スレッドから呼び出すためのものです。例えば次のように使います:

# Create a coroutine
coro = asyncio.sleep(1, result=3)

# Submit the coroutine to a given loop
future = asyncio.run_coroutine_threadsafe(coro, loop)

# Wait for the result with an optional timeout argument
assert future.result(timeout) == 3

コルーチンから例外が送出された場合、返された Future に通知されます。これはイベントループの Task をキャンセルするのにも使えます:

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}')

このドキュメントの 並行処理とマルチスレッド処理 節を参照してください。

他の asyncio 関数とは異なり、この関数は明示的に渡される loop 引数を必要とします。

Added in version 3.5.1.

イントロスペクション

asyncio.current_task(loop=None)

現在実行中の Task インスタンスを返します。実行中の Task が無い場合は None を返します。

loop が None の場合、 get_running_loop() が現在のループを取得するのに使われます。

Added in version 3.7.

asyncio.all_tasks(loop=None)

ループで実行された Task オブジェクトでまだ完了していないものの集合を返します。

loop が None の場合、 get_running_loop() は現在のループを取得するのに使われます。

Added in version 3.7.

asyncio.iscoroutine(obj)

Return True if obj is a coroutine object.

Added in version 3.4.

Task オブジェクト

class asyncio.Task(coro, *, loop=None, name=None, context=None, eager_start=False)

Python コルーチン を実行する Future 類 オブジェクトです。スレッドセーフではありません。

Task はイベントループのコルーチンを実行するのに使われます。 Future でコルーチンが待機している場合、 Task は自身のコルーチンの実行を一時停止させ、 Future の完了を待ちます。 Future が 完了 したら、 Task が内包しているコルーチンの実行を再開します。

イベントループは協調スケジューリングを使用します。つまり、イベントループは同時に 1 つの Task のみ実行します。 Task が Future の完了を待っているときは、イベントループは他の Task やコールバックを動作させるか、 IO 処理を実行します。

Task を作成するには高レベルの asyncio.create_task() 関数、あるいは低レベルの loop.create_task() 関数や ensure_future() 関数を使用してください。手作業での Task の実装は推奨されません。

実行中のタスクをキャンセルするためには、cancel() メソッドを使用します。このメソッドを呼ぶと、タスクはそれを内包するコルーチンに対して CancelledError 例外を送出します。キャンセルの際にコルーチンが Future オブジェクトを待っていた場合、その Future オブジェクトはキャンセルされます。

cancelled() は、タスクがキャンセルされたかを調べるのに使用できます。タスクを内包するコルーチンで CancelledError 例外が抑制されておらず、かつタスクが実際にキャンセルされている場合に、このメソッドは True を変えます。

asyncio.Task は、Future.set_result() と Future.set_exception() を除いて、Future の API をすべて継承しています。

An optional keyword-only context argument allows specifying a custom 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 asyncio.Task at task creation time. If set to 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 で変更: 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 で変更: Added the eager_start parameter.

done()

Task が 完了 しているなら True を返します。

Task がラップしているコルーチンが値を返すか、例外を送出するか、または Task がキャンセルされたとき、 Task は 完了 します。

result()

Task の結果を返します。

Task が 完了 している場合、ラップしているコルーチンの結果が返されます (コルーチンが例外を送出された場合、その例外が例外が再送出されます)

Task が キャンセル されている場合、このメソッドは CancelledError 例外を送出します。

Task の結果がまだ未設定の場合、このメソッドは InvalidStateError 例外を送出します。

exception()

Task の例外を返します。

ラップされたコルーチンが例外を送出した場合、その例外が返されます。ラップされたコルーチンが正常終了した場合、このメソッドは None を返します。

Task が キャンセル されている場合、このメソッドは CancelledError 例外を送出します。

Task がまだ 完了 していない場合、このメソッドは InvalidStateError 例外を送出します。

add_done_callback(callback, *, context=None)

Task が 完了 したときに実行されるコールバックを追加します。

このメソッドは低水準のコールバックベースのコードでのみ使うべきです。

詳細については Future.add_done_callback() のドキュメントを参照してください。

remove_done_callback(callback)

コールバックリストから callback を削除します。

このメソッドは低水準のコールバックベースのコードでのみ使うべきです。

詳細については Future.remove_done_callback() のドキュメントを参照してください。

get_stack(*, limit=None)

このタスクのスタックフレームのリストを返します。

コルーチンが完了していない場合、これはサスペンドされた時点でのスタックを返します。コルーチンが正常に処理を完了したか、キャンセルされていた場合は空のリストを返します。コルーチンが例外で終了した場合はトレースバックフレームのリストを返します。

フレームは常に古いものから新しい物へ並んでいます。

サスペンドされているコルーチンの場合スタックフレームが 1 個だけ返されます。

オプション引数 limit は返すフレームの最大数を指定します; デフォルトでは取得可能な全てのフレームを返します。返されるリストの順番は、スタックが返されるか、トレースバックが返されるかによって変わります: スタックでは新しい順に並んだリストが返されますが、トレースバックでは古い順に並んだリストが返されます（これは traceback モジュールの振る舞いと一致します）。

print_stack(*, limit=None, file=None)

このタスクのスタックまたはトレースバックを出力します。

このメソッドは get_stack() によって取得されるフレームに対し、 traceback モジュールと同じような出力を生成します。

引数 limit は get_stack() にそのまま渡されます。

The file argument is an I/O stream to which the output is written; by default output is written to sys.stdout.

get_coro()

Task がラップしているコルーチンオブジェクトを返します。

注釈

This will return None for Tasks which have already completed eagerly. See the Eager Task Factory.

Added in version 3.8.

バージョン 3.12 で変更: Newly added eager task execution means result may be None.

get_context()

Return the contextvars.Context object associated with the task.

Added in version 3.12.

get_name()

Task の名前を返します。

Task に対して明示的に名前が設定されていない場合, デフォルトの asyncio Task 実装はタスクをインスタンス化する際にデフォルトの名前を生成します。

Added in version 3.8.

set_name(value)

Task に名前を設定します。

引数 value は文字列に変換可能なオブジェクトであれば何でもかまいません。

Task のデフォルト実装では、名前はオブジェクトの repr() メソッドの出力で確認できます。

Added in version 3.8.

cancel(msg=None)

このタスクに、自身のキャンセルを要求します。

このメソッドは、イベントループの次のステップにおいて、タスクがラップしているコルーチン内で CancelledError 例外が送出されるように準備します。

The coroutine then has a chance to clean up or even deny the request by suppressing the exception with a try ... ... except CancelledError ... finally block. Therefore, unlike Future.cancel(), 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 Task.uncancel() in addition to catching the exception.

バージョン 3.9 で変更: Added the msg parameter.

バージョン 3.11 で変更: The msg parameter is propagated from cancelled task to its awaiter.

以下の例は、コルーチンがどのようにしてキャンセルのリクエストを阻止するかを示しています:

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

cancelled()

Task が キャンセルされた 場合に True を返します。

cancel() メソッドによりキャンセルがリクエストされ、かつ Task がラップしているコルーチンが内部で送出された CancelledError 例外を伝達したとき、 Task は実際に キャンセル されます。

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 uncancel() are ineffective.

Added in version 3.11.

This method is used by asyncio's internals and isn't expected to be used by end-user code. In particular, if a Task gets successfully uncancelled, this allows for elements of structured concurrency like Task Groups and asyncio.timeout() to continue running, isolating cancellation to the respective structured block. For 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()

While the block with make_request() and make_another_request() might get cancelled due to the timeout, unrelated_code() should continue running even in case of the timeout. This is implemented with uncancel(). TaskGroup context managers use uncancel() in a similar fashion.

If end-user code is, for some reason, suppressing cancellation by catching CancelledError, it needs to call this method to remove the cancellation state.

cancelling()

Return the number of pending cancellation requests to this Task, i.e., the number of calls to cancel() less the number of uncancel() calls.

Note that if this number is greater than zero but the Task is still executing, cancelled() will still return False. This is because this number can be lowered by calling 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 uncancel() for more details.

Added in version 3.11.

ストリーム

ソースコード: Lib/asyncio/streams.py [https://github.com/python/cpython/tree/3.12/Lib/asyncio/streams.py]

ストリームはネットワークコネクションと合わせて動作する高水準の async/await 可能な基本要素です。ストリームはコールバックや低水準のプロトコルやトランスポートを使うことなくデータを送受信することを可能にします。

以下は asyncio ストリームを使って書いた TCP エコークライアントの例です:

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!'))

下記の 使用例 節も参照してください。

ストリーム関数

以下の asyncio のトップレベル関数はストリームの作成や操作を行うことができます:

coroutine asyncio.open_connection(host=None, port=None, *, limit=None, ssl=None, family=0, proto=0, flags=0, sock=None, local_addr=None, server_hostname=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None, happy_eyeballs_delay=None, interleave=None)

ネットワークコネクションを確立し、 (reader, writer) のオブジェクトのペアを返します。

戻り値の reader と writer はそれぞれ StreamReader と StreamWriter クラスのインスタンスです。

limit は戻り値の StreamReader インスタンスが利用するバッファのサイズの上限値を設定します。デフォルトでは limit は 64 KiB に設定されます。

残りの引数は直接 loop.create_connection() に渡されます。

注釈

The sock argument transfers ownership of the socket to the StreamWriter created. To close the socket, call its close() method.

バージョン 3.7 で変更: Added the ssl_handshake_timeout parameter.

バージョン 3.8 で変更: happy_eyeballs_delay と interleave が追加されました。

バージョン 3.10 で変更: loop パラメータが削除されました。

バージョン 3.11 で変更: ssl_shutdown_timeout パラメータが追加されました。

coroutine asyncio.start_server(client_connected_cb, host=None, port=None, *, limit=None, family=socket.AF_UNSPEC, flags=socket.AI_PASSIVE, sock=None, backlog=100, ssl=None, reuse_address=None, reuse_port=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None, start_serving=True)

ソケットサーバーを起動します。

client_connected_cb コールバックは新しいクライアントコネクションが確立されるたびに呼び出されます。このコールバックは StreamReader と StreamWriter クラスのインスタンスのペア (reader, writer) を2つの引数として受け取ります。

client_connected_cb には単純な呼び出し可能オブジェクトか、または コルーチン関数 を指定します; コルーチン関数が指定された場合、コールバックの呼び出しは自動的に Task としてスケジュールされます。

limit は戻り値の StreamReader インスタンスが利用するバッファのサイズの上限値を設定します。デフォルトでは limit は 64 KiB に設定されます。

残りの引数は直接 loop.create_server() に渡されます。

注釈

The sock argument transfers ownership of the socket to the server created. To close the socket, call the server's close() method.

バージョン 3.7 で変更: ssl_handshake_timeout と start_serving パラメータが追加されました。

バージョン 3.10 で変更: loop パラメータが削除されました。

バージョン 3.11 で変更: ssl_shutdown_timeout パラメータが追加されました。

Unix ソケット

coroutine asyncio.open_unix_connection(path=None, *, limit=None, ssl=None, sock=None, server_hostname=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None)

Unix ソケットコネクションを確立し、 (reader, writer) のオブジェクトのペアを返します。

この関数は open_connection() と似ていますが Unix ソケットに対して動作します。

loop.create_unix_connection() のドキュメントも参照してください。

注釈

The sock argument transfers ownership of the socket to the StreamWriter created. To close the socket, call its close() method.

利用可能な環境: Unix。

バージョン 3.7 で変更: Added the ssl_handshake_timeout parameter. The path parameter can now be a path-like object

バージョン 3.10 で変更: loop パラメータが削除されました。

バージョン 3.11 で変更: ssl_shutdown_timeout パラメータが追加されました。

coroutine asyncio.start_unix_server(client_connected_cb, path=None, *, limit=None, sock=None, backlog=100, ssl=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None, start_serving=True)

Unix のソケットサーバーを起動します。

start_server() と似ていますが Unix ソケットに対して動作します。

loop.create_unix_server() のドキュメントも参照してください。

注釈

The sock argument transfers ownership of the socket to the server created. To close the socket, call the server's close() method.

利用可能な環境: Unix。

バージョン 3.7 で変更: Added the ssl_handshake_timeout and start_serving parameters. The path parameter can now be a path-like object.

バージョン 3.10 で変更: loop パラメータが削除されました。

バージョン 3.11 で変更: ssl_shutdown_timeout パラメータが追加されました。

StreamReader

class asyncio.StreamReader

Represents a reader object that provides APIs to read data from the IO stream. As an asynchronous iterable, the object supports the async for statement.

StreamReader オブジェクトを直接インスタンス化することは推奨されません; 代わりに open_connection() や start_server() を使ってください。

feed_eof()

EOF の肯定応答を行います。

coroutine read(n=-1)

ストリームから最大 n バイト読み込みます。

n が指定されないか -1 が指定されていた場合 EOF になるまで読み込み、読み込まれた全ての bytes を返します。EOF を受信し、かつ内部バッファーが空の場合、空の bytes オブジェクトを返します。

n が 0 なら、ただちに空の bytes オブジェクトを返します。

n が正なら、内部バッファで最低でも 1 バイトが利用可能になり次第、利用可能な最大 n bytes を返します。1 バイトも読み込まないうちに EOF を受信したなら、空の bytes オブジェクトを返します。

coroutine readline()

1 行読み込みます。 "行" とは、\n で終了するバイト列のシーケンスです。

EOF を受信し、かつ \n が見つからない場合、このメソッドは部分的に読み込んだデータを返します。

EOF を受信し、かつ内部バッファーが空の場合、空の bytes オブジェクトを返します。

coroutine readexactly(n)

厳密に n バイトのデータを読み出します。

n バイトを読み出す前に EOF に達した場合 IncompleteReadError を送出します。部分的に読み出したデータを取得するには IncompleteReadError.partial 属性を使ってください。

coroutine readuntil(separator=b'\n')

separator が見つかるまでストリームからデータを読み出します。

成功時には、データと区切り文字は内部バッファから削除されます (消費されます)。返されるデータの最後には区切り文字が含まれます。

読み出したデータの量が設定したストリームの上限を超えると LimitOverrunError 例外が送出されます。このときデータは内部バッファーに残され、再度読み出すことができます。

完全な区切り文字が見つかる前に EOF に達すると IncompleteReadError 例外が送出され、内部バッファーがリセットされます。このとき IncompleteReadError.partial 属性は区切り文字の一部を含むかもしれません。

Added in version 3.5.2.

at_eof()

バッファーが空で feed_eof() が呼ばれていた場合 True を返します。

StreamWriter

class asyncio.StreamWriter

IO ストリームにデータを書き込むための API を提供するライターオブジェクトを表します。

StreamWriter オブジェクトを直接インスタンス化することは推奨されません; 代わりに open_connection() や start_server() を使ってください。

write(data)

このメソッドは、背後にあるソケットにデータ data を即座に書き込みます。書き込みに失敗した場合、データは送信可能になるまで内部の書き込みバッファーに格納されて待機します。

このメソッドは drain() メソッドと組み合わせて使うべきです:

stream.write(data)
await stream.drain()

writelines(data)

このメソッドは、背後にあるソケットにバイトデータのリスト (またはイテラブル) を即座に書き込みます。書き込みに失敗した場合、データは送信可能になるまで内部の書き込みバッファーに格納されて待機します。

このメソッドは drain() メソッドと組み合わせて使うべきです:

stream.writelines(lines)
await stream.drain()

close()

このメソッドはストリームと背後にあるソケットをクローズします。

The method should be used, though not mandatory, along with the wait_closed() method:

stream.close()
await stream.wait_closed()

can_write_eof()

背後にあるトランスポートが write_eof() メソッドをサポートしている場合 True を返し、そうでない場合は False を返します。

write_eof()

バッファーされた書き込みデータを全て書き込んでから、ストリームの書き込み側終端をクローズします。

transport

背後にある asyncio トランスポートを返します。

get_extra_info(name, default=None)

オプションのトランスポート情報にアクセスします。詳細は BaseTransport.get_extra_info() を参照してください。

coroutine drain()

ストリームへの書き込み再開に適切な状態になるまで待ちます。使用例:

writer.write(data)
await writer.drain()

このメソッドは背後にある IO 書き込みバッファーとやりとりを行うフロー制御メソッドです。バッファーのサイズが最高水位点に達した場合、drain() はバッファのサイズが最低水位点を下回るまで減量され、書き込み再開可能になるまで書き込みをブロックします。待ち受けの必要がない場合、 drain() は即座にリターンします。

coroutine start_tls(sslcontext, *, server_hostname=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None)

Upgrade an existing stream-based connection to TLS.

引数:

sslcontext: 構成済みの SSLContext インスタンスです。

server_hostname: 対象のサーバーの証明書との照合に使われるホスト名を設定または上書きします。

ssl_handshake_timeout is the time in seconds to wait for the TLS handshake to complete before aborting the connection. 60.0 seconds if None (default).

ssl_shutdown_timeout is the time in seconds to wait for the SSL shutdown to complete before aborting the connection. 30.0 seconds if None (default).

Added in version 3.11.

バージョン 3.12 で変更: ssl_shutdown_timeout パラメータが追加されました。

is_closing()

ストリームがクローズされたか、またはクローズ処理中の場合に True を返します。

Added in version 3.7.

coroutine wait_closed()

ストリームがクローズされるまで待機します。

Should be called after close() to wait until the underlying connection is closed, ensuring that all data has been flushed before e.g. exiting the program.

Added in version 3.7.

使用例

ストリームを使った TCP Echo クライアント

asyncio.open_connection() 関数を使った TCP Echo クライアントです:

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!'))

参考

TCP エコークライアントプロトコル の例は低水準の loop.create_connection() メソッドを使っています。

ストリームを使った TCP Echo サーバー

asyncio.start_server() 関数を使った TCP Echo サーバーです:

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())

参考

TCP エコーサーバープロトコル の例は loop.create_server() メソッドを使っています。

HTTP ヘッダーの取得

コマンドラインから渡された URL の HTTP ヘッダーを問い合わせる簡単な例です:

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

使い方:

python example.py http://example.com/path/page.html

または HTTPS を使用:

python example.py https://example.com/path/page.html

ストリームを使ってデータを待つオープンソケットの登録

open_connection() 関数を使ってソケットがデータを受信するまで待つコルーチンです:

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())

参考

プロトコルを使ってオープンしたソケットをデータ待ち受けのために登録する 例では、低水準のプロトコルと loop.create_connection() メソッドを使っています。

ファイル記述子の読み出しイベントを監視する 例では、低水準の loop.add_reader() メソッドを使ってファイル記述子を監視しています。

同期プリミティブ

ソースコード: Lib/asyncio/locks.py [https://github.com/python/cpython/tree/3.12/Lib/asyncio/locks.py]

asyncio の同期プリミティブは threading モジュールのそれと類似するようにデザインされていますが、2つの重要な注意事項があります:

asyncio の同期プリミティブはスレッドセーフではありません。従って OS スレッドの同期に使うべきではありません (代わりに threading を使ってください);

同期プリミティブのメソッドは timeout 引数を受け付けません; タイムアウトを伴う操作を実行するには asyncio.wait_for() 関数を使ってください。

asyncio モジュールは以下の基本的な同期プリミティブを持っています:

Lock

Event

Condition

Semaphore

BoundedSemaphore

Barrier

Lock

class asyncio.Lock

asyncio タスクのためのミューテックスロックを実装しています。スレッドセーフではありません。

asyncio ロックは、共有リソースに対する排他的なアクセスを保証するために使うことができます。

Lock の望ましい使用方法は、 async with 文と組み合わせて使うことです:

lock = asyncio.Lock()

# ... later
async with lock:
    # access shared state

これは以下のコードと等価です:

lock = asyncio.Lock()

# ... later
await lock.acquire()
try:
    # access shared state
finally:
    lock.release()

バージョン 3.10 で変更: loop パラメータが削除されました。

coroutine acquire()

ロックを獲得します。

このメソッドはロックが 解除される まで待機し、ロックを ロック状態 に変更して True を返します。

複数のコルーチンが acquire() メソッドによりロックの解除を待ち受けている場合、最終的にただひとつのコルーチンが実行されます。

ロックの獲得は 公平 です: すなわちロックを獲得して実行されるコルーチンは、最初にロックの待ち受けを開始したコルーチンです。

release()

ロックを解放します。

ロックが ロック状態 の場合、 ロックを 解除状態 にしてリターンします。

ロックが 解除状態 の場合、 RuntimeError 例外が送出されます。

locked()

ロック状態 の場合に True を返します。

Event

class asyncio.Event

イベントオブジェクトです。スレッドセーフではありません。

asyncio イベントは、複数の asyncio タスクに対して何らかのイベントが発生したことを通知するために使うことができます。

Event オブジェクトは内部フラグを管理します。フラグの値は set() メソッドにより true に、また clear() メソッドにより false に設定することができます。 wait() メソッドはフラグが true になるまで処理をブロックします。フラグの初期値は false です。

バージョン 3.10 で変更: loop パラメータが削除されました。

以下はプログラム例です:

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())

coroutine wait()

イベントがセットされるまで待機します。

イベントがセットされると、即座に True を返します。 そうでなければ、他のタスクが set() メソッドを呼び出すまで処理をブロックします。

set()

イベントをセットします。

イベントがセットされるまで待機している全てのタスクは、即座に通知を受けて実行を再開します。

clear()

イベントをクリア (アンセット) します

wait() メソッドで待ち受けを行うタスクは set() メソッドが再度呼び出されるまで処理をブロックします。

is_set()

イベントがセットされている場合 True を返します。

Condition

class asyncio.Condition(lock=None)

条件変数オブジェクトです。スレッドセーフではありません。

asyncio 条件プリミティブは何らかのイベントが発生するのを待ち受け、そのイベントを契機として共有リソースへの排他的なアクセスを得るために利用することができます。

本質的に、 Condition オブジェクトは Event と a Lock の2つのクラスの機能を組み合わせたものです。複数の Condition オブジェクトが単一の Lock を共有することでができます。これにより、共有リソースのそれぞれの状態に関連する異なるタスクの間で、そのリソースへの排他的アクセスを調整することが可能になります。

オプション引数 lock は Lock または None でなければなりません。後者の場合自動的に新しい Lock オブジェクトが生成されます。

バージョン 3.10 で変更: loop パラメータが削除されました。

Condition の望ましい使用方法は async with 文と組み合わせて使うことです:

cond = asyncio.Condition()

# ... later
async with cond:
    await cond.wait()

これは以下のコードと等価です:

cond = asyncio.Condition()

# ... later
await cond.acquire()
try:
    await cond.wait()
finally:
    cond.release()

coroutine acquire()

下層でのロックを獲得します。

このメソッドは下層のロックが 解除される まで待機し、ロックを ロック状態 に変更して True を返します。

notify(n=1)

Wake up at most n tasks (1 by default) waiting on this condition. The method is no-op if no tasks are waiting.

このメソッドが呼び出される前にロックを獲得しておかなければなりません。また、メソッド呼び出し後速やかにロックを解除しなければなりません。 解除された ロックとと共に呼び出された場合、 RuntimeError 例外が送出されます。

locked()

下層のロックを獲得していれば True を返します。

notify_all()

この条件を待ち受けている全てのタスクを起動します。

このメソッドは notify() と同じように振る舞いますが、待ち受けている全てのタスクを起動します。

このメソッドが呼び出される前にロックを獲得しておかなければなりません。また、メソッド呼び出し後速やかにロックを解除しなければなりません。 解除された ロックとと共に呼び出された場合、 RuntimeError 例外が送出されます。

release()

下層のロックを解除します。

アンロック状態のロックに対して呼び出された場合、RuntimeError が送出されます。

coroutine wait()

通知を受けるまで待機します。

このメソッドが呼び出された時点で呼び出し元のタスクがロックを獲得していない場合、 RuntimeError 例外が送出されます。

このメソッドは下層のロックを解除し、その後 notify() または notify_all() の呼び出しによって起動されるまで処理をブロックします。いったん起動されると、 Condition は再びロックを獲得し、メソッドは True を返します。

coroutine wait_for(predicate)

引数 predicate の条件が 真 になるまで待機します。

The predicate must be a callable which result will be interpreted as a boolean value. The final value is the return value.

Semaphore

class asyncio.Semaphore(value=1)

セマフォオブジェクトです。スレッドセーフではありません。

セマフォは内部のカウンターを管理しています。カウンターは acquire() メソッドの呼び出しによって減算され、 release() メソッドの呼び出しによって加算されます。カウンターがゼロを下回ることはありません。 acquire() メソッドが呼び出された時にカウンターがゼロになっていると、セマフォは処理をブロックし、他のタスクが release() メソッドを呼び出すまで待機します。

オプション引数 value は内部カウンターの初期値を与えます (デフォルトは 1 です)。 指定された値が 0 より小さい場合、 ValueError 例外が送出されます。

バージョン 3.10 で変更: loop パラメータが削除されました。

セマフォの望ましい使用方法は、 async with 文と組み合わせて使うことです:

sem = asyncio.Semaphore(10)

# ... later
async with sem:
    # work with shared resource

これは以下のコードと等価です:

sem = asyncio.Semaphore(10)

# ... later
await sem.acquire()
try:
    # work with shared resource
finally:
    sem.release()

coroutine acquire()

セマフォを獲得します。

内部カウンターがゼロより大きい場合、カウンターを1つ減算して即座に True を返します。内部カウンターがゼロの場合、 release() が呼び出されるまで待機してから True を返します。

locked()

セマフォを直ちに獲得できない場合 True を返します。

release()

セマフォを解放し、内部カウンターを1つ加算します。セマフォ待ちをしているタスクを起動する可能性があります。

BoundedSemaphore と異なり、 Semaphore は release() を acquire() よりも多く呼び出すことを許容します。

BoundedSemaphore

class asyncio.BoundedSemaphore(value=1)

有限セマフォオブジェクトです。スレッドセーフではありません。

有限セマフォは Semaphore の一種で、 release() メソッドの呼び出しにより内部カウンターが 初期値 よりも増加してしまう場合は ValueError 例外を送出します。

バージョン 3.10 で変更: loop パラメータが削除されました。

Barrier

class asyncio.Barrier(parties)

A barrier object. Not thread-safe.

A barrier is a simple synchronization primitive that allows to block until parties number of tasks are waiting on it. Tasks can wait on the wait() method and would be blocked until the specified number of tasks end up waiting on wait(). At that point all of the waiting tasks would unblock simultaneously.

async with can be used as an alternative to awaiting on wait().

The barrier can be reused any number of times.

以下はプログラム例です:

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())

Result of this example is:

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

Added in version 3.11.

coroutine 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 parties-1, different for each task. This can be used to select a task to do some special housekeeping, e.g.:

...
async with barrier as position:
   if position == 0:
      # Only one task prints this
      print('End of *draining phase*')

This method may raise a BrokenBarrierError exception if the barrier is broken or reset while a task is waiting. It could raise a CancelledError if a task is cancelled.

coroutine reset()

Return the barrier to the default, empty state. Any tasks waiting on it will receive the BrokenBarrierError exception.

If a barrier is broken it may be better to just leave it and create a new one.

coroutine abort()

Put the barrier into a broken state. This causes any active or future calls to wait() to fail with the BrokenBarrierError. Use this for example if one of the tasks needs to abort, to avoid infinite waiting tasks.

parties

The number of tasks required to pass the barrier.

n_waiting

The number of tasks currently waiting in the barrier while filling.

broken

バリアが broken な状態である場合に True となるブール値。

exception asyncio.BrokenBarrierError

Barrier オブジェクトがリセットされるか broken な場合に、この例外 (RuntimeError のサブクラス) が送出されます。

バージョン 3.9 で変更: await lock や yield from lock およびそれらと with 文との組み合わせ (すなわち with await lock や with (yield from lock)) によるロックの獲得は削除されました。代わりに async with lock を使ってください。

サブプロセス

ソースコード: Lib/asyncio/subprocess.py [https://github.com/python/cpython/tree/3.12/Lib/asyncio/subprocess.py], Lib/asyncio/base_subprocess.py [https://github.com/python/cpython/tree/3.12/Lib/asyncio/base_subprocess.py]

このセクションはサブプロセスの生成と管理を行う高水準の async/await asyncio API について説明します。

以下は、 asyncio モジュールがどのようにシェルコマンドを実行し、結果を取得できるかを示す例です:

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'))

このサンプルコードは以下を出力します:

['ls /zzz' exited with 1]
[stderr]
ls: /zzz: No such file or directory

全ての asyncio のサブプロセス関数は非同期ですが、 asyncio モジュールはこれらの非同期関数と協調するための多くのツールを提供しているので、複数のサブプロセスを並列に実行して監視することは簡単です。実際、上記のサンプルコードを複数のコマンドを同時に実行するように修正するのはきわめて単純です:

async def main():
    await asyncio.gather(
        run('ls /zzz'),
        run('sleep 1; echo "hello"'))

asyncio.run(main())

使用例 節も参照してください。

サブプロセスの生成

coroutine asyncio.create_subprocess_exec(program, *args, stdin=None, stdout=None, stderr=None, limit=None, **kwds)

サブプロセスを作成します。

The limit argument sets the buffer limit for StreamReader wrappers for Process.stdout and Process.stderr (if subprocess.PIPE is passed to stdout and stderr arguments).

Process のインスタンスを返します。

他のパラメータについては loop.subprocess_exec() を参照してください。

バージョン 3.10 で変更: loop パラメータが削除されました。

coroutine asyncio.create_subprocess_shell(cmd, stdin=None, stdout=None, stderr=None, limit=None, **kwds)

シェルコマンド cmd を実行します。

The limit argument sets the buffer limit for StreamReader wrappers for Process.stdout and Process.stderr (if subprocess.PIPE is passed to stdout and stderr arguments).

Process のインスタンスを返します。

他のパラメータについては loop.subprocess_shell() のドキュメントを参照してください。

重要

シェルインジェクション [https://en.wikipedia.org/wiki/Shell_injection#Shell_injection] の脆弱性を回避するために全ての空白文字および特殊文字を適切にクオートすることは、アプリケーション側の責任で確実に行ってください。シェルコマンドを構成する文字列内の空白文字と特殊文字のエスケープは、 shlex.quote() 関数を使うと適切に行うことができます。

バージョン 3.10 で変更: loop パラメータが削除されました。

注釈

サブプロセスは、 ProactorEventLoop を使えば Windows でも利用可能です。詳しくは Windows におけるサブプロセスのサポート を参照してください。

参考

asyncio は以下に挙げるサブプロセスと協調するための 低水準の API も持っています: loop.subprocess_exec(), loop.subprocess_shell(), loop.connect_read_pipe(), loop.connect_write_pipe() および Subprocess Transports と Subprocess Protocols。

定数

asyncio.subprocess.PIPE

stdin, stdout または stderr に渡すことができます。

PIPE が stdin 引数に渡された場合、 Process.stdin 属性は StreamWriter インスタンスを指します。

PIPE が stdout や stderr 引数に渡された場合、 Process.stdout と Process.stderr 属性は StreamReader インスタンスを指します。

asyncio.subprocess.STDOUT

stderr 引数に対して利用できる特殊な値で、標準エラー出力が標準出力にリダイレクトされることを意味します。

asyncio.subprocess.DEVNULL

プロセスを生成する関数の stdin, stdout または stderr 引数に利用できる特殊な値です。対応するサブプロセスのストリームに特殊なファイル os.devnull が使われることを意味します。

サブプロセスとやりとりする

create_subprocess_exec() と create_subprocess_shell() の2つの関数はどちらも Process クラスのインスタンスを返します。 Process クラスはサブプロセスと通信したり、サブプロセスの完了を監視したりするための高水準のラッパーです。

class asyncio.subprocess.Process

関数 create_subprocess_exec() や create_subprocess_shell() によって生成された OS のプロセスをラップするオブジェクトです。

このクラスは subprocess.Popen クラスと同様の API を持つように設計されていますが、いくつかの注意すべき違いがあります:

Popen と異なり、 Process インスタンスは poll() メソッドに相当するメソッドを持っていません;

the communicate() and wait() methods don't have a timeout parameter: use the wait_for() function;

subprocess.Popen.wait() メソッドが同期処理のビジーループとして実装されているのに対して、 Process.wait() メソッドは非同期処理です;

universal_newlines パラメータはサポートされていません。

このクラスは スレッド安全ではありません。

サブプロセスとスレッド 節も参照してください。

coroutine wait()

子プロセスが終了するのを待ち受けます。

returncode 属性を設定し、その値を返します。

注釈

stdout=PIPE または stderr=PIPE を使っており、OS パイプバッファがさらなるデータを受け付けるようになるまで子プロセスをブロックするほど大量の出力を生成場合、このメソッドはデッドロックする可能性があります。この条件を避けるため、パイプを使用する場合は communicate() メソッドを使ってください。

coroutine communicate(input=None)

プロセスとのやりとりを行います:

stdin にデータを送信します (input が None でない場合);

stdin を閉じます;

EOF に達するまで stdout および stderr からデータを読み出します;

プロセスが終了するまで待ち受けます。

input オプション引数は子プロセスに送信されるデータ (bytes オブジェクト) です。

(stdout_data, stderr_data) のタプルを返します。

input を標準入力 stdin nに書き込んでいる時に BrokenPipeError または ConnectionResetError 例外が送出された場合、例外は無視されます。このような条件は、全てのデータが stdin に書き込まれる前にプロセスが終了した場合に起こります。

子プロセスの標準入力 stdin にデータを送りたい場合、プロセスは stdin=PIPE を設定して生成する必要があります。同様に、 None 以外の何らかのデータを戻り値のタプルで受け取りたい場合、プロセスは stdout=PIPE と stderr=PIPE のいずれかまたは両方を指定して生成しなければなりません。

プロセスから受信したデータはメモリ上にバッファーされることに注意してください。そのため、返されるデータのサイズが大きいかまたは無制限の場合はこのメソッドを使わないようにしてください。

バージョン 3.12 で変更: input=None のときも stdin は閉じられます。

send_signal(signal)

子プロセスにシグナル signal を送信します。

注釈

On Windows, SIGTERM is an alias for terminate(). CTRL_C_EVENT and CTRL_BREAK_EVENT can be sent to processes started with a creationflags parameter which includes CREATE_NEW_PROCESS_GROUP.

terminate()

子プロセスを停止します。

On POSIX systems this method sends SIGTERM to the child process.

On Windows the Win32 API function TerminateProcess() is called to stop the child process.

kill()

子プロセスを強制終了 (kill) します。

POSIX システムの場合、このメソッドは子プロセスに SIGKILL シグナルを送信します。

Windows では、このメソッドは terminate() のエイリアスです。

stdin

標準入力ストリーム (StreamWriter) です。プロセスが stdin=None で生成された場合は None になります。

stdout

標準出力ストリーム (StreamReader) です。プロセスが stdout=None で生成された場合は None になります。

stderr

標準エラー出力ストリーム (StreamReader) です。プロセスが stderr=None で生成された場合は None になります。

警告

Use the communicate() method rather than process.stdin.write(), await process.stdout.read() or await process.stderr.read(). This avoids deadlocks due to streams pausing reading or writing and blocking the child process.

pid

子プロセスのプロセス番号 (PID) です。

create_subprocess_shell() 関数によって生成されたプロセスの場合、この属性は生成されたシェルの PID になることに注意してください。

returncode

プロセスが終了した時の終了ステータスを返します。

この属性が None であることは、プロセスがまだ終了していないことを示しています。

負の値 -N は子プロセスがシグナル N により中止させられたことを示します (POSIX のみ)。

サブプロセスとスレッド

標準的な asyncio のイベントループは、異なるスレッドからサブプロセスを実行するのをデフォルトでサポートしています。

Windows のサブプロセスは ProactorEventLoop (デフォルト) のみ提供され、 SelectorEventLoop はサブプロセスをサポートしていません。

UNIX の child watchers はサブプロセスの終了を待ち受けるために使われます。より詳しい情報については プロセスのウオッチャー を参照してください。

バージョン 3.8 で変更: UNIX では、異なるスレッドから何らの制限なくサブプロセスを生成するために ThreadedChildWatcher を使うようになりました。

現在の子プロセスのウオッチャーが アクティブでない 場合にサブプロセスを生成すると RuntimeError 例外が送出されます。

標準で提供されない別のイベントループ実装の場合、固有の制限がある可能性があります; それぞれの実装のドキュメントを参照してください。

参考

並行処理とマルチスレッド処理

使用例

サブプロセスの制御のために Process クラスを使い、サブプロセスの標準出力を読み出すために StreamReader を使う例です。

サブプロセスは create_subprocess_exec() 関数により生成されます:

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}")

低水準の API を使って書かれた 同様の例 も参照してください。

キュー

ソースコード: Lib/asyncio/queues.py [https://github.com/python/cpython/tree/3.12/Lib/asyncio/queues.py]

asyncio キューは queue モジュールのクラス群と同じ形になるように設計されています。 asyncio キューはスレッドセーフではありませんが、それらは async/await コードから使われるために特別に設計されています。

asyncio キューのメソッドは timeout パラメータを持たないことに注意してください; タイムアウトを伴うキューを使った処理を行うには asyncio.wait_for() 関数を使ってください。

下記の 使用例 節も参照してください。

Queue

class asyncio.Queue(maxsize=0)

先入れ先出し (FIFO) キューです。

maxsize がゼロ以下の場合、キューは無限長になります。 0 より大きい整数の場合、キューが maxsize に達すると await put() は get() によってキューの要素が除去されるまでブロックします。

標準ライブラリにおけるスレッドベースの queue モジュールと異なり、キューのサイズは常に既知であり、 qsize() メソッドを呼び出すことによって取得することができます。

バージョン 3.10 で変更: loop パラメータが削除されました。

このクラスは スレッド安全ではありません。

maxsize

キューに追加できるアイテム数です。

empty()

キューが空ならば True を、そうでなければ False を返します。

full()

キューに要素が maxsize 個あれば True を返します。

キューが maxsize=0 (デフォルト値) で初期化された場合、 full() メソッドが True を返すことはありません。

coroutine get()

キューから要素を削除して返します。キューが空の場合項目が利用可能になるまで待機します。

get_nowait()

直ちに利用できるアイテムがあるときはそれを、そうでなければ QueueEmpty を返します。

coroutine join()

キューにある全ての要素が取得され、処理されるまでブロックします。

未完了のタスクのカウント値は、キューにアイテムが追加されるときは常に加算され、キューの要素を消費するコルーチンが要素を取り出し、処理を完了したことを通知するために task_done() を呼び出すと減算されます。未完了のタスクのカウント値がゼロになると、 join() のブロックは解除されます。

coroutine put(item)

要素をキューに入力します。キューが満杯の場合、要素を追加する前に空きスロットが利用できるようになるまで待機します。

put_nowait(item)

ブロックせずにアイテムをキューに追加します。

直ちに利用できるスロットがない場合、QueueFull を送出します。

qsize()

キュー内の要素数を返します。

task_done()

キューに入っていたタスクが完了したことを示します。

キューコンシューマーによって使用されます。タスクの取得に get() を使用し、その後の task_done() の呼び出しでタスクの処理が完了したことをキューに通知します。

join() が現在ブロック中だった場合、全アイテムが処理されたとき (put() でキューに追加された全アイテムの task_done() の呼び出しを受信したとき) に再開します。

キューに追加されているアイテム数以上の呼び出しが行われたときに ValueError を送出します。

優先度付きのキュー

class asyncio.PriorityQueue

Queue の変種です; 優先順位にしたがって要素を取り出します (最低順位が最初に取り出されます)。

項目は典型的には (priority_number, data) 形式のタプルです。

LIFO キュー

class asyncio.LifoQueue

Queue の変種で、最後に追加された項目を最初に取り出します (後入れ先出し、またはスタック)。

例外

exception asyncio.QueueEmpty

この例外は get_nowait() メソッドが空のキューに対して呼ばれたときに送出されます。

exception asyncio.QueueFull

サイズが maxsize に達したキューに対して put_nowait() メソッドが 呼ばれたときに送出される例外です。

使用例

キューを使って、並行処理を行う複数のタスクにワークロードを分散させることができます:

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())

例外

ソースコード: Lib/asyncio/exceptions.py [https://github.com/python/cpython/tree/3.12/Lib/asyncio/exceptions.py]

exception asyncio.TimeoutError

A deprecated alias of TimeoutError, raised when the operation has exceeded the given deadline.

バージョン 3.11 で変更: This class was made an alias of TimeoutError.

exception asyncio.CancelledError

処理がキャンセルされました。

asyncio タスクがキャンセルされた場合の処理をカスタマイズするために、この例外を一旦キャッチすることができます。 ほとんどの場合、キャッチした例外は再度送出しなければなりません。

バージョン 3.8 で変更: CancelledError is now a subclass of BaseException rather than Exception.

exception asyncio.InvalidStateError

Task または Future の内部状態が不正になりました。

すでに結果の値が設定されている Future オブジェクトに対してさらに結果の値を再び設定しようとする場合などに送出されることがあります。

exception asyncio.SendfileNotAvailableError

与えられたソケットまたはファイルタイプに対して "sendfile" システムコールが利用可能ではありません。

RuntimeError の派生クラスです。

exception asyncio.IncompleteReadError

要求された読み込み処理が完了できませんでした。

asyncio ストリーム API から送出されます。

この例外は EOFError の派生クラスです。

expected

期待される総バイト数 (int) です。

partial

ストリームの終端に達するまでに読み込んだ bytes 文字列です。

exception asyncio.LimitOverrunError

区切り文字を探している間にバッファサイズの上限に到達しました。

asyncio ストリーム API から送出されます。

consumed

未消費のバイトの合計数です。

イベントループ

ソースコード: Lib/asyncio/profile.py [https://github.com/python/cpython/tree/3.12/Lib/asyncio/profile.py] と Lib/asyncio/pstats.py [https://github.com/python/cpython/tree/3.12/Lib/asyncio/pstats.py]

まえがき

イベントループは全ての asyncio アプリケーションの中核をなす存在です。イベントループは非同期タスクやコールバックを実行し、ネットワーク I/O を処理し、サブプロセスを実行します。

アプリケーション開発者は通常 asyncio.run() のような高水準の ayncio 関数だけを利用し、ループオブジェクトを参照したり、ループオブジェクトのメソッドを呼び出したりすることはほとんどありません。この節は、イベントループの振る舞いに対して細かい調整が必要な、低水準のコード、ライブラリ、フレームワークの開発者向けです。

イベントループの取得

以下の低水準関数はイベントループの取得、設定、生成するために使います:

asyncio.get_running_loop()

現在の OS スレッドで実行中のイベントループを取得します。

Raise a RuntimeError if there is no running event loop.

This function can only be called from a coroutine or a callback.

Added in version 3.7.

asyncio.get_event_loop()

現在のイベントループを取得します。

When called from a coroutine or a callback (e.g. scheduled with call_soon or similar API), this function will always return the running event loop.

If there is no running event loop set, the function will return the result of the get_event_loop_policy().get_event_loop() call.

この関数の振る舞いは (特にイベントループポリシーをカスタマイズした場合) 複雑なため、コルーチンやコールバックでは get_event_loop() よりも get_running_loop() を使うほうが好ましいと考えられます。

As noted above, consider using the higher-level asyncio.run() function, instead of using these lower level functions to manually create and close an event loop.

バージョン 3.12 で非推奨: Deprecation warning is emitted if there is no current event loop. In some future Python release this will become an error.

asyncio.set_event_loop(loop)

Set loop as the current event loop for the current OS thread.

asyncio.new_event_loop()

新しいイベントループオブジェクトを生成して返します。

get_event_loop(), set_event_loop(), および new_event_loop() 関数の振る舞いは、 カスタムイベントループポリシーを設定する ことにより変更することができます。

内容

このページは以下の節から構成されます:

イベントループのメソッド 節は、イベントループ API のリファレンスです。

コールバックハンドル 節は loop.call_soon() や loop.call_later() などのスケジューリングメソッドが返す Handle や TimerHandle インスタンスについて解説しています。

サーバーオブジェクト 節は loop.create_server() のようなメソッドが返す型について解説しています。

イベントループの実装 節は SelectorEventLoop と ProactorEventLoop の2つのクラスについて解説しています。

使用例 節ではイベントループ API の具体的な使い方を紹介しています。

イベントループのメソッド

イベントループは以下の 低水準な API を持っています:

ループの開始と停止

コールバックのスケジューリング

遅延コールバックのスケジューリング

フューチャーとタスクの生成

ネットワーク接続の確立

ネットワークサーバの生成

ファイルの転送

TLS へのアップグレード

ファイル記述子の監視

ソケットオブジェクトと直接やりとりする

DNS

パイプとやりとりする

Unix シグナル

スレッドまたはプロセスプールでコードを実行する

エラーハンドリング API

デバッグモードの有効化

サブプロセスの実行

ループの開始と停止

loop.run_until_complete(future)

フューチャー (Future インスタンス) が完了するまで実行します。

引数が コルーチンオブジェクト の場合、暗黙のうちに asyncio.Task として実行されるようにスケジュールされます。

Future の結果を返すか、例外を送出します。

loop.run_forever()

stop() が呼び出されるまでイベントループを実行します。

run_forever() メソッドが呼ばれるより前に stop() メソッドが呼ばれた場合、イベントループはタイムアウトをゼロにして一度だけ I/O セレクタの問い合わせ処理を行い、 I/O イベントに対してスケジュールされた全てのコールバック (および既にスケジュール済みのコールバック) を実行したのち、終了します。

run_forever() メソッドを実行中に stop() メソッドが呼び出された場合、イベントループは現在処理されているすべてのコールバックを実行してから終了します。 この場合、コールバックにより新たにスケジュールされるコールバックは実行されないことに注意してください; これら新たにスケジュールされたコールバックは、次に run_forever() または run_until_complete() が呼び出されたときに実行されます。

loop.stop()

イベントループを停止します。

loop.is_running()

イベントループが現在実行中の場合 True を返します。

loop.is_closed()

イベントループが閉じられていた場合 True を返します。

loop.close()

イベントループをクローズします。

この関数が呼び出される時点で、イベントループが実行中であってはいけません。保留中のコールバックはすべて破棄されます。

このメソッドは全てのキューをクリアし、エグゼキューターが実行完了するのを待たずにシャットダウンします。

このメソッドはべき等 (何回実行しても結果は同じ) であり取り消せません。イベントループがクローズされた後、他のいかなるメソッドも呼び出すべきではありません。

coroutine loop.shutdown_asyncgens()

現在オープンになっているすべての asynchronous generator (非同期ジェネレータ) オブジェクトをスケジュールし、 aclose() メソッドを呼び出すことでそれらをクローズします。 このメソッドの呼び出し後に新しい非同期ジェネレータがイテレートされると、イベントループは警告を発します。このメソッドはスケジュールされたすべての非同期ジェネレータの終了処理を確実に行うために使用すべきです。

asyncio.run() を使った場合はこの関数を呼び出す必要はありません。

以下はプログラム例です:

try:
    loop.run_forever()
finally:
    loop.run_until_complete(loop.shutdown_asyncgens())
    loop.close()

Added in version 3.6.

coroutine loop.shutdown_default_executor(timeout=None)

Schedule the closure of the default executor and wait for it to join all of the threads in the ThreadPoolExecutor. Once this method has been called, using the default executor with loop.run_in_executor() will raise a RuntimeError.

The timeout parameter specifies the amount of time (in float seconds) the executor will be given to finish joining. With the default, None, the executor is allowed an unlimited amount of time.

If the timeout is reached, a RuntimeWarning is emitted and the default executor is terminated without waiting for its threads to finish joining.

注釈

Do not call this method when using asyncio.run(), as the latter handles default executor shutdown automatically.

Added in version 3.9.

バージョン 3.12 で変更: Added the timeout parameter.

コールバックのスケジューリング

loop.call_soon(callback, *args, context=None)

イベントループの次のイテレーションで callback に指定したコールバック (callback) を args 引数で呼び出すようにスケジュールします。

Return an instance of asyncio.Handle, which can be used later to cancel the callback.

コールバックは登録された順に呼び出されます。各コールバックは厳密に1回だけ呼び出されます。

The optional keyword-only context argument specifies a custom contextvars.Context for the callback to run in. Callbacks use the current context when no context is provided.

Unlike call_soon_threadsafe(), this method is not thread-safe.

loop.call_soon_threadsafe(callback, *args, context=None)

A thread-safe variant of call_soon(). When scheduling callbacks from another thread, this function must be used, since call_soon() is not thread-safe.

すでにクローズされたイベントループに対してこのメソッドが呼び出された場合 RuntimeError 例外を送出します。これはメインアプリケーションが終了しているにもかかわらずセカンダリスレッドでメソッドが呼び出されるといった場合に起こりえます。

このドキュメントの 並行処理とマルチスレッド処理 節を参照してください。

バージョン 3.7 で変更: キーワード引数 context が追加されました。詳細は PEP 567 [https://peps.python.org/pep-0567/] を参照してください。

注釈

ほとんどの asyncio モジュールのスケジューリング関数は、キーワード引数をコールバックに渡すことを許していません。キーワード引数を渡すためには functools.partial() を使ってください:

# will schedule "print("Hello", flush=True)"
loop.call_soon(
    functools.partial(print, "Hello", flush=True))

asyncio は partial オブジェクトのデバッグメッセージやエラーメッセージをよりよく可視化することができるため、通常はラムダ式よりも partial オブジェクトを使う方が便利です。

遅延コールバックのスケジューリング

イベントループは、コールバック関数を未来のある時点で呼び出されるようにスケジュールする仕組みを提供します。イベントループは時刻が戻らない単調な時計 (monotonic clock) を使って時刻を追跡します。

loop.call_later(delay, callback, *args, context=None)

delay 秒経過後にコールバック関数 callback を呼び出すようにスケジュールします。 delay には整数または浮動小数点数を指定します。

asyncio.TimerHandle のインスタンスを返します。このインスタンスを使ってスケジュールしたコールバックをキャンセルすることができます。

callback は厳密に一度だけ呼び出されます。2つのコールバックが完全に同じ時間にスケジュールされた場合、呼び出しの順序は未定義です。

オプションの位置引数 args はコールバックが呼び出されるときに位置引数として渡されます。キーワード引数を指定してコールバックを呼び出したい場合は functools.partial() を使用してください。

オプションのキーワード引数 context を使って、コールバック*callback* を実行する際のコンテキスト contextvars.Context を設定することができます。コンテキスト context が指定されない場合は現在のコンテキストが使われます。

バージョン 3.7 で変更: キーワード引数 context が追加されました。詳細は PEP 567 [https://peps.python.org/pep-0567/] を参照してください。

バージョン 3.8 で変更: Python 3.7 またはそれ以前のバージョンでは、デフォルトイベントループの実装を利用した場合に遅延時間 delay が1日を超えることができませんでした。この問題は Python 3.8 で修正されました。

loop.call_at(when, callback, *args, context=None)

絶対値の時刻 when (整数または浮動小数点数) にコールバックを呼び出すようにスケジュールします。 loop.time() と同じ参照時刻を使用します。

このメソッドの振る舞いは call_later() と同じです。

asyncio.TimerHandle のインスタンスを返します。このインスタンスを使ってスケジュールしたコールバックをキャンセルすることができます。

バージョン 3.7 で変更: キーワード引数 context が追加されました。詳細は PEP 567 [https://peps.python.org/pep-0567/] を参照してください。

バージョン 3.8 で変更: Python 3.7 またはそれ以前のバージョンでは、デフォルトイベントループの実装を利用した場合に現在の時刻と when との差が1日を超えることができませんでした。この問題は Python 3.8 で修正されました。

loop.time()

現在の時刻を float 値で返します。時刻はイベントループが内部で参照している時刻が戻らない単調な時計 (monotonic clock) に従います。

注釈

バージョン 3.8 で変更: Python 3.7 またはそれ以前のバージョンでは、タイムアウト (相対値 delay もしくは絶対値 when) は1日を超えることができませんでした。この問題は Python 3.8 で修正されました。

参考

関数 asyncio.sleep()。

フューチャーとタスクの生成

loop.create_future()

イベントループに接続した asyncio.Future オブジェクトを生成します。

asyncio でフューチャーオブジェクトを作成するために推奨される方法です。このメソッドにより、サードパーティ製のイベントループがFutures クラスの(パフォーマンスや計測方法が優れた) 代替実装を提供することを可能にします。

Added in version 3.5.2.

loop.create_task(coro, *, name=None, context=None)

Schedule the execution of coroutine coro. Return a Task object.

サードパーティのイベントループは相互運用のための自身の Task のサブクラスを使用できます。この場合、結果は Task のサブクラスになります。

name 引数が指定され、値が None でない場合、 Task.set_name() メソッドにより name がタスクの名前として設定されます。

省略可能なキーワード引数 context によって、coro を実行するためのカスタムの contextvars.Context を指定できます。context が省略された場合、現在のコンテキストのコピーが作成されます。

バージョン 3.8 で変更: name パラメータを追加しました。

バージョン 3.11 で変更: context パラメータを追加しました。

loop.set_task_factory(factory)

loop.create_task() が使用するタスクファクトリーを設定します。

If factory is None the default task factory will be set. Otherwise, factory must be a callable with the signature matching (loop, coro, context=None), where loop is a reference to the active event loop, and coro is a coroutine object. The callable must return a asyncio.Future-compatible object.

loop.get_task_factory()

タスクファクトリを返します。デフォルトのタスクファクトリを使用中の場合は None を返します。

ネットワーク接続の確立

coroutine loop.create_connection(protocol_factory, host=None, port=None, *, ssl=None, family=0, proto=0, flags=0, sock=None, local_addr=None, server_hostname=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None, happy_eyeballs_delay=None, interleave=None, all_errors=False)

host と port で指定されたアドレスとのストリーミングトランスポート接続をオープンします。

The socket family can be either AF_INET or AF_INET6 depending on host (or the family argument, if provided).

The socket type will be SOCK_STREAM.

protocol_factory は asyncio プロトコル の実装を返す呼び出し可能オブジェクトでなければなりません。

このメソッドはバックグラウンドで接続の確立を試みます。成功した場合、メソッドは (transport, protocol) のペアを返します。

時系列での下層処理の概要は以下のとおりです:

接続を確立し、その接続に対する トランスポート が生成されます。

protocol_factory が引数なしで呼び出され、ファクトリが プロトコル インスタンスを返すよう要求します。

プロトコルインスタンスが connection_made() メソッドを呼び出すことにより、トランスポートと紐付けられます。

成功すると (transport, protocol) タプルが返されます。

作成されたトランスポートは実装依存の双方向ストリームです。

その他の引数:

ssl: 偽値以外が与えられた場合、SSL/TLS トランスポートが作成されます (デフォルトでは暗号化なしの TCP トランスポートが作成されます)。 ssl が ssl.SSLContext オブジェクトの場合、このコンテキストがトランスポートを作成するために使用されます; ssl が True の場合、 ssl.create_default_context() が返すデフォルトのコンテキストが使われます。

参考

SSL/TLS セキュリティについての考察

server_hostname は対象サーバーの証明書との一致を確認するためのホスト名を設定または上書きします。この引数は ssl が None でない場合のみ設定すべきです。デフォルトでは host に指定したサーバー名が使用されます。 host が空の文字列の場合のデフォルト値は設定されていません。その場合、 server_hostname を必ず指定してください。 server_hostname も空の文字列の場合は、ホスト名の一致確認は行われません (これは深刻なセキュリティリスクであり、中間者攻撃を受ける可能性があります)。

family, proto, flags は任意のアドレスファミリであり、host 解決のための getaddrinfo() 経由で渡されるプロトコルおよびフラグになります。このオプションが与えられた場合、これらはすべて socket モジュール定数に従った整数でなければなりません。

happy_eyeballs_delay が設定されると、この接続に対して Happy Eyeballs が有効化されます。設定する値は浮動小数点数であり、次の接続試行を開始する前に、現在の接続試行が完了するのを待つ時間を秒単位で表現します。この値は RFC 8305 [https://datatracker.ietf.org/doc/html/rfc8305.html] で定義されている "接続試行遅延" に相当します。RFC で推奨されている実用的なデフォルト値は 0.25 (250 ミリ秒) です。

interleave はホスト名が複数の IP アドレスに名前解決される場合のアドレスの並べ替えを制御します。 0 または未指定の場合並べ替えは行われず、 getaddrinfo() が返す順番にしたがってアドレスへの接続を試行します。正の整数が指定されると、アドレスはアドレスファミリに応じてインターリーブされます。このとき、与えられた整数は RFC 8305 [https://datatracker.ietf.org/doc/html/rfc8305.html] で定義される "最初のアドレスファミリカウント (First Address Family Count)" として解釈されます。デフォルト値は、 happy_eyeballs_delay が指定されない場合は 0 であり、指定された場合は 1 です。

sock を与える場合、トランスポートに使用される、既存の、かつ接続済の socket.socket オブジェクトを指定します。sock を指定する場合、host、 port、 family、 proto、 flags、 happy_eyeballs_delay、 interleave および local_addr のいずれも指定してはいけません。

注釈

The sock argument transfers ownership of the socket to the transport created. To close the socket, call the transport's close() method.

local_addr を与える場合、ソケットをローカルにバインドするために使用する (local_host, local_port) タプルを指定します。 local_host と local_port は、 host および port と同じく getaddrinfo() を使ってルックアップされます。

ssl_handshake_timeout は TLS ハンドシェイクが完了するまでの (TLS 接続のための) 待ち時間を秒単位で指定します。指定した待ち時間を超えると接続は中断します。 None が与えられた場合はデフォルト値 60.0 が使われます。

ssl_shutdown_timeout is the time in seconds to wait for the SSL shutdown to complete before aborting the connection. 30.0 seconds if None (default).

all_errors determines what exceptions are raised when a connection cannot be created. By default, only a single Exception is raised: the first exception if there is only one or all errors have same message, or a single OSError with the error messages combined. When all_errors is True, an ExceptionGroup will be raised containing all exceptions (even if there is only one).

バージョン 3.5 で変更: ProactorEventLoop において SSL/TLS のサポートが追加されました。

バージョン 3.6 で変更: The socket option socket.TCP_NODELAY is set by default for all TCP connections.

バージョン 3.7 で変更: Added the ssl_handshake_timeout parameter.

バージョン 3.8 で変更: happy_eyeballs_delay と interleave が追加されました。

Happy Eyeballs Algorithm: Success with Dual-Stack Hosts. When a server's IPv4 path and protocol are working, but the server's IPv6 path and protocol are not working, a dual-stack client application experiences significant connection delay compared to an IPv4-only client. This is undesirable because it causes the dual-stack client to have a worse user experience. This document specifies requirements for algorithms that reduce this user-visible delay and provides an algorithm.

For more information: https://datatracker.ietf.org/doc/html/rfc6555

バージョン 3.11 で変更: ssl_shutdown_timeout パラメータが追加されました。

バージョン 3.12 で変更: all_errors が追加されました

参考

open_connection() 関数は高水準の代替 API です。この関数は(StreamReader, StreamWriter) のペアを返し、 async/await コードから直接使うことができます。

coroutine loop.create_datagram_endpoint(protocol_factory, local_addr=None, remote_addr=None, *, family=0, proto=0, flags=0, reuse_port=None, allow_broadcast=None, sock=None)

データグラム接続 (UDP) を生成します。

The socket family can be either AF_INET, AF_INET6, or AF_UNIX, depending on host (or the family argument, if provided).

The socket type will be SOCK_DGRAM.

protocol_factory は asyncio プロトコル の実装を返す呼び出し可能オブジェクトでなければなりません。

成功すると (transport, protocol) タプルが返されます。

その他の引数:

local_addr が指定される場合、ソケットをローカルにバインドするための (local_host, local_port) のタプルを指定します。 local_host と local_port は getaddrinfo() メソッドを使用して検索されます。

remote_addr が指定される場合、(remote_host, remote_por) のタプルで、ソケットをリモートアドレスに束縛するために使用されます。remote_host と remote_port は getaddrinfo() を使用して検索されます。

family, proto, flags は任意のアドレスファミリです。これらのファミリ、プロトコル、フラグは、host 解決のため getaddrinfo() 経由でオプションで渡されます。これらのオプションを指定する場合、すべて socket モジュール定数に従った整数でなければなりません。

reuse_port tells the kernel to allow this endpoint to be bound to the same port as other existing endpoints are bound to, so long as they all set this flag when being created. This option is not supported on Windows and some Unixes. If the socket.SO_REUSEPORT constant is not defined then this capability is unsupported.

allow_broadcast は、カーネルに、このエンドポイントがブロードキャストアドレスにメッセージを送信することを許可するように指示します。

オプションの sock を指定することで、既存の、すでに接続されている socket.socket をトランスポートで使用することができます。このオプションを使用する場合、local_addr と remote_addr は省略してください (None でなければなりません)。

注釈

The sock argument transfers ownership of the socket to the transport created. To close the socket, call the transport's close() method.

UDP echo クライアントプロトコル および UDP echo サーバープロトコル の例を参照してください。

バージョン 3.4.4 で変更: The family, proto, flags, reuse_address, reuse_port, allow_broadcast, and sock parameters were added.

バージョン 3.8 で変更: Windows サポートが追加されました。

バージョン 3.8.1 で変更: The reuse_address parameter is no longer supported, as using socket.SO_REUSEADDR poses a significant security concern for UDP. Explicitly passing reuse_address=True will raise an exception.

SO_REUSEADDR を使って、同一の UDP ソケットアドレスに対して複数のプロセスが異なる UID でソケットを割り当てている場合、受信パケットは複数のソケット間にランダムに分散する可能性があります。

For supported platforms, reuse_port can be used as a replacement for similar functionality. With reuse_port, socket.SO_REUSEPORT is used instead, which specifically prevents processes with differing UIDs from assigning sockets to the same socket address.

バージョン 3.11 で変更: The reuse_address parameter, disabled since Python 3.8.1, 3.7.6 and 3.6.10, has been entirely removed.

coroutine loop.create_unix_connection(protocol_factory, path=None, *, ssl=None, sock=None, server_hostname=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None)

Unix 接続を生成します。

The socket family will be AF_UNIX; socket type will be SOCK_STREAM.

成功すると (transport, protocol) タプルが返されます。

path は Unix ドメインソケット名で、 sock パラメータが指定されない場合は必須です。 抽象 Unix ソケット、 str、 bytes、 and Path 形式でのパスがサポートされています。

このメソッドの引数についての詳細は loop.create_connection() メソッドのドキュメントを参照してください。

利用可能な環境: Unix。

バージョン 3.7 で変更: Added the ssl_handshake_timeout parameter. The path parameter can now be a path-like object.

バージョン 3.11 で変更: ssl_shutdown_timeout パラメータが追加されました。

ネットワークサーバの生成

coroutine loop.create_server(protocol_factory, host=None, port=None, *, family=socket.AF_UNSPEC, flags=socket.AI_PASSIVE, sock=None, backlog=100, ssl=None, reuse_address=None, reuse_port=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None, start_serving=True)

Create a TCP server (socket type SOCK_STREAM) listening on port of the host address.

Server オブジェクトを返します。

引数:

protocol_factory は asyncio プロトコル の実装を返す呼び出し可能オブジェクトでなければなりません。

host パラメータはいくつかの方法で指定することができ、その値によってサーバーがどこをリッスンするかが決まります。

host が文字列の場合、 TCP サーバーは host で指定した単一のネットワークインターフェースに束縛されます。

host が文字列のシーケンスである場合、 TCP サーバーはそのシーケンスで指定された全てのネットワークインターフェースに束縛されます。

host が空の文字列か None の場合、すべてのインターフェースが想定され、複合的なソケットのリスト (通常は一つが IPv4、もう一つが IPv6) が返されます。

The port parameter can be set to specify which port the server should listen on. If 0 or None (the default), a random unused port will be selected (note that if host resolves to multiple network interfaces, a different random port will be selected for each interface).

family can be set to either socket.AF_INET or AF_INET6 to force the socket to use IPv4 or IPv6. If not set, the family will be determined from host name (defaults to AF_UNSPEC).

flags は getaddrinfo() のためのビットマスクになります。

サーバーで既存のソケットオブジェクトを使用するために、オプションの引数 sock にソケットオブジェクトを設定することができます。指定した場合、 host と port を指定してはいけません。

注釈

The sock argument transfers ownership of the socket to the server created. To close the socket, call the server's close() method.

backlog は listen() に渡される、キューに入るコネクションの最大数になります (デフォルトは 100)。

確立した接続の上で TLS を有効化するために、 ssl に SSLContext のインスタンスを指定することができます。

reuse_address は、TIME_WAIT 状態にあるローカルソケットを、その状態が自然にタイムアウトするのを待つことなく再利用するようカーネルに指示します（訳註: ソケットのオプション SO_REUSEADDR を使用します）。指定しない場合、UNIX では自動的に True が設定されます。

reuse_port は、同じポートにバインドされた既存の端点すべてがこのフラグを設定して生成されている場合に限り、この端点を既存の端点と同じポートにバインドすることを許可するよう、カーネルに指示します（訳註: ソケットのオプション SO_REUSEPORT を使用します）。このオプションは、Windows ではサポートされていません。

ssl_handshake_timeout は TLS ハンドシェイクが完了するまでの (TLS サーバーのための) 待ち時間を秒単位で指定します。指定した待ち時間を超えると接続は中断します。 None が与えられた場合はデフォルト値 60.0 が使われます。

ssl_shutdown_timeout is the time in seconds to wait for the SSL shutdown to complete before aborting the connection. 30.0 seconds if None (default).

start_serving が True に設定された場合 (これがデフォルトです)、 生成されたサーバーは即座に接続の受け付けを開始します。 False が指定された場合、ユーザーは接続の受け付けを開始するために Server.start_serving() または Server.serve_forever() を待ち受け (await) る必要があります。

バージョン 3.5 で変更: ProactorEventLoop において SSL/TLS のサポートが追加されました。

バージョン 3.5.1 で変更: host パラメータに文字列のシーケンスを指定できるようになりました。

バージョン 3.6 で変更: Added ssl_handshake_timeout and start_serving parameters. The socket option socket.TCP_NODELAY is set by default for all TCP connections.

バージョン 3.11 で変更: ssl_shutdown_timeout パラメータが追加されました。

参考

start_server() 関数は高水準の代替 API です。この関数は StreamReader と StreamWriter のペアを返し、async/await コードから使うことができます。

coroutine loop.create_unix_server(protocol_factory, path=None, *, sock=None, backlog=100, ssl=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None, start_serving=True)

Similar to loop.create_server() but works with the AF_UNIX socket family.

path は Unix ドメインソケット名で、 sock パラメータが指定されない場合は必須です。 抽象 Unix ソケット、 str、 bytes、 and Path 形式でのパスがサポートされています。

このメソッドの引数についての詳細は loop.create_server() メソッドのドキュメントを参照してください。

利用可能な環境: Unix。

バージョン 3.7 で変更: Added the ssl_handshake_timeout and start_serving parameters. The path parameter can now be a Path object.

バージョン 3.11 で変更: ssl_shutdown_timeout パラメータが追加されました。

coroutine loop.connect_accepted_socket(protocol_factory, sock, *, ssl=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None)

すでに確立した接続を transport と protocol のペアでラップします。

このメソッドは asyncio の範囲外で確立された接続を使うサーバーに対しても使えますが、その場合でも接続は asyncio を使って処理されます。

引数:

protocol_factory は asyncio プロトコル の実装を返す呼び出し可能オブジェクトでなければなりません。

sock は socket.accept メソッドが返す既存のソケットオブジェクトです。

注釈

The sock argument transfers ownership of the socket to the transport created. To close the socket, call the transport's close() method.

ssl には SSLContext を指定できます。指定すると、受け付けたコネクション上での SSL を有効にします。

ssl_handshake_timeout は SSL ハンドシェイクが完了するまでの (SSL 接続のための) 待ち時間を秒単位で指定します。 None が与えられた場合はデフォルト値 60.0 が使われます。

ssl_shutdown_timeout is the time in seconds to wait for the SSL shutdown to complete before aborting the connection. 30.0 seconds if None (default).

(transport, protocol) のペアを返します。

Added in version 3.5.3.

バージョン 3.7 で変更: Added the ssl_handshake_timeout parameter.

バージョン 3.11 で変更: ssl_shutdown_timeout パラメータが追加されました。

ファイルの転送

coroutine loop.sendfile(transport, file, offset=0, count=None, *, fallback=True)

transport を通じて file を送信します。送信したデータの総バイト数を返します。

このメソッドは、もし利用可能であれば高性能な os.sendfile() を利用します。

file はバイナリモードでオープンされた通常のファイルオブジェクトでなければなりません。

offset はファイルの読み込み開始位置を指定します。 count が指定された場合、ファイルの EOF までファイルを送信する代わりに、 count で指定された総バイト数の分だけ送信します。ファイルオブジェクトが指し示す位置は、メソッドがエラーを送出した場合でも更新されます。この場合実際に送信されたバイト数は file.tell() メソッドで取得することができます。

fallback を True に指定することで、 asyncio がプラットフォームが sendfile システムコールをサポートしていない場合 (たとえば Windows や Unix の SSL ソケットなど) に別の方法でファイルの読み込みと送信を行うようにすることができます。

システムが sendfile システムコールをサポートしておらず、かつ fallback が False の場合、 SendfileNotAvailableError 例外を送出します。

Added in version 3.7.

TLS へのアップグレード

coroutine loop.start_tls(transport, protocol, sslcontext, *, server_side=False, server_hostname=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None)

既存のトランスポートベースの接続を TLS にアップグレードします。

Create a TLS coder/decoder instance and insert it between the transport and the protocol. The coder/decoder implements both transport-facing protocol and protocol-facing transport.

Return the created two-interface instance. After await, the protocol must stop using the original transport and communicate with the returned object only because the coder caches protocol-side data and sporadically exchanges extra TLS session packets with transport.

In some situations (e.g. when the passed transport is already closing) this may return None.

引数:

transport と protocol には、 create_server() や create_connection() が返すものと同等のインスタンスを指定します。

sslcontext: 構成済みの SSLContext インスタンスです。

(create_server() で生成されたような) サーバーサイドの接続をアップグレードする場合は server_side に True を渡します。

server_hostname: 対象のサーバーの証明書との照合に使われるホスト名を設定または上書きします。

ssl_handshake_timeout は TLS ハンドシェイクが完了するまでの (TLS 接続のための) 待ち時間を秒単位で指定します。指定した待ち時間を超えると接続は中断します。 None が与えられた場合はデフォルト値 60.0 が使われます。

ssl_shutdown_timeout is the time in seconds to wait for the SSL shutdown to complete before aborting the connection. 30.0 seconds if None (default).

Added in version 3.7.

バージョン 3.11 で変更: ssl_shutdown_timeout パラメータが追加されました。

ファイル記述子の監視

loop.add_reader(fd, callback, *args)

ファイル記述子 fd に対する読み込みが可能かどうかの監視を開始し、 fd が読み込み可能になると、指定した引数でコールバック callback を呼び出します。

loop.remove_reader(fd)

Stop monitoring the fd file descriptor for read availability. Returns True if fd was previously being monitored for reads.

loop.add_writer(fd, callback, *args)

ファイル記述子 fd に対する書き込みが可能かどうかの監視を開始し、 fd が書き込み可能になると、指定した引数でコールバック callback を呼び出します。

コールバック callback に キーワード引数を渡す 場合は functools.partial() を使ってください。

loop.remove_writer(fd)

Stop monitoring the fd file descriptor for write availability. Returns True if fd was previously being monitored for writes.

これらのメソッドに対する制限事項については プラットフォームのサポート状況 節も参照してください。

ソケットオブジェクトと直接やりとりする

一般に、 loop.create_connection() や loop.create_server() のようなトランスポートベースの API を使ったプロトコルの実装はソケットと直接やり取りする実装に比べて高速です。しかしながら、パフォーマンスが重要でなく、直接 socket オブジェクトとやりとりした方が便利なユースケースがいくつかあります。

coroutine loop.sock_recv(sock, nbytes)

nbytes で指定したバイト数までのデータをソケット sock から受信します。 このメソッドは socket.recv() の非同期版です。

受信したデータをバイトオブジェクトとして返します。

sock はノンブロッキングソケットでなければなりません。

バージョン 3.7 で変更: このメソッドは常にコルーチンメソッドとしてドキュメントに記載されてきましたが、 Python 3.7 以前のリリースでは Future オブジェクトを返していました。 Python 3.7 からは async def メソッドになりました。

coroutine loop.sock_recv_into(sock, buf)

ソケット sock からデータを受信してバッファ buf に格納します。ブロッキングコードの socket.recv_into() メソッドをモデルとしています。

バッファに書き込んだデータのバイト数を返します。

sock はノンブロッキングソケットでなければなりません。

Added in version 3.7.

coroutine loop.sock_recvfrom(sock, bufsize)

Receive a datagram of up to bufsize from sock. Asynchronous version of socket.recvfrom().

Return a tuple of (received data, remote address).

sock はノンブロッキングソケットでなければなりません。

Added in version 3.11.

coroutine loop.sock_recvfrom_into(sock, buf, nbytes=0)

Receive a datagram of up to nbytes from sock into buf. Asynchronous version of socket.recvfrom_into().

Return a tuple of (number of bytes received, remote address).

sock はノンブロッキングソケットでなければなりません。

Added in version 3.11.

coroutine loop.sock_sendall(sock, data)

データ data をソケット sock に送信します。 socket.sendall() メソッドの非同期版です。

このメソッドは data をすべて送信し終えるか、またはエラーが起きるまでデータをソケットに送信し続けます。送信に成功した場合 None を返します。エラーの場合は例外が送出されます。エラーとなった場合、接続の受信側で正しく処理されたデータの総量を特定する方法はありません。

sock はノンブロッキングソケットでなければなりません。

バージョン 3.7 で変更: このメソッドは常にコルーチンメソッドとしてドキュメントに記載されてきましたが、 Python 3.7 以前のリリースでは Future オブジェクトを返していました。 Python 3.7 からは async def メソッドになりました。

coroutine loop.sock_sendto(sock, data, address)

Send a datagram from sock to address. Asynchronous version of socket.sendto().

Return the number of bytes sent.

sock はノンブロッキングソケットでなければなりません。

Added in version 3.11.

coroutine loop.sock_connect(sock, address)

ソケット sock をアドレス address のリモートソケットに接続します。

socket.connect() の非同期版です。

sock はノンブロッキングソケットでなければなりません。

バージョン 3.5.2 で変更: address を名前解決する必要はなくなりました。 sock_connect は socket.inet_pton() を呼び出して address が解決済みかどうかを確認します。未解決の場合、 address の名前解決には loop.getaddrinfo() メソッドが使われます。

参考

loop.create_connection() および asyncio.open_connection()。

coroutine loop.sock_accept(sock)

接続を受け付けます。ブロッキングコールの socket.accept() メソッドをモデルとしています。

ソケットはアドレスに束縛済みで、接続を listen 中である必要があります。戻り値は (conn, address) のペアで、conn は接続を通じてデータの送受信を行うための 新しい ソケットオブジェクト、address は接続先の端点でソケットに束縛されているアドレスを示します。

sock はノンブロッキングソケットでなければなりません。

バージョン 3.7 で変更: このメソッドは常にコルーチンメソッドとしてドキュメントに記載されてきましたが、 Python 3.7 以前のリリースでは Future オブジェクトを返していました。 Python 3.7 からは async def メソッドになりました。

参考

loop.create_server() および start_server()。

coroutine loop.sock_sendfile(sock, file, offset=0, count=None, *, fallback=True)

ファイルを送信します。利用可能なら高性能な os.sendfile を使います。送信したデータの総バイト数を返します。

socket.sendfile() メソッドの非同期版です。

sock は socket.SOCK_STREAM タイプのノンブロッキングな socket でなければなりません。

file はバイナリモードでオープンされた通常のファイルオブジェクトでなければなりません。

offset はファイルの読み込み開始位置を指定します。 count が指定された場合、ファイルの EOF までファイルを送信する代わりに、 count で指定された総バイト数の分だけ送信します。ファイルオブジェクトが指し示す位置は、メソッドがエラーを送出した場合でも更新されます。この場合実際に送信されたバイト数は file.tell() メソッドで取得することができます。

fallback が True に設定された場合、 プラットフォームが sendfile システムコールをサポートしていない場合 (たとえば Windows や Unix の SSL ソケットなど) に asyncio が別の方法でファイルの読み込みと送信を行うようにすることができます。

システムが sendfile システムコールをサポートしておらず、かつ fallback が False の場合、 SendfileNotAvailableError 例外を送出します。

sock はノンブロッキングソケットでなければなりません。

Added in version 3.7.

DNS

coroutine loop.getaddrinfo(host, port, *, family=0, type=0, proto=0, flags=0)

socket.getaddrinfo() の非同期版です。

coroutine loop.getnameinfo(sockaddr, flags=0)

socket.getnameinfo() の非同期版です。

バージョン 3.7 で変更: getaddrinfo と getnameinfo の2つのメソッドは、いずれも常にコルーチンメソッドとしてドキュメントに記載されてきましたが、 Python 3.7 以前のリリースでは、実際には asyncio.Future オブジェクトを返していました。 Python 3.7 からはどちらのメソッドもコルーチンになりました。

パイプとやりとりする

coroutine loop.connect_read_pipe(protocol_factory, pipe)

イベントループの読み込み側終端に pipe を登録します。

protocol_factory は asyncio プロトコル の実装を返す呼び出し可能オブジェクトでなければなりません。

pipe には file-like オブジェクト を指定します。

(transport, protocol) のペアを返します。ここで transport は ReadTransport のインターフェースをサポートし、 protocol は protocol_factory ファクトリでインスタンス化されたオブジェクトです。

SelectorEventLoop イベントループの場合、pipe は非ブロックモードに設定されていなければなりません。

coroutine loop.connect_write_pipe(protocol_factory, pipe)

pipe の書き込み側終端をイベントループに登録します。

protocol_factory は asyncio プロトコル の実装を返す呼び出し可能オブジェクトでなければなりません。

pipe は file-like オブジェクト です。

(transport, protocol) のペアを返します。ここで transport は WriteTransport のインスタンスであり、 protocol は protocol_factory ファクトリでインスタンス化されたオブジェクトです。

SelectorEventLoop イベントループの場合、pipe は非ブロックモードに設定されていなければなりません。

注釈

SelectorEventLoop は Windows 上で上記のメソッドをサポートしていません。 Windowsでは代わりに ProactorEventLoop を使ってください。

参考

loop.subprocess_exec() および loop.subprocess_shell() メソッド。

Unix シグナル

loop.add_signal_handler(signum, callback, *args)

コールバック callback をシグナル signum に対するハンドラに設定します。

コールバックは loop、登録された他のコールバック、およびイベントループの実行可能なコルーチンから呼び出されます。 signal.signal() を使って登録されたシグナルハンドラと異なり、この関数で登録されたコールバックはイベントループと相互作用することが可能です。

シグナルナンバーが誤っているか捕捉不可能な場合 ValueError が送出されます。ハンドラーの設定に問題があった場合 RuntimeError が送出されます。

コールバック callback に キーワード引数を渡す 場合は functools.partial() を使ってください。

signal.signal() と同じく、この関数はメインスレッドから呼び出されなければなりません。

loop.remove_signal_handler(sig)

シグナル sig に対するハンドラを削除します。

シグナルハンドラが削除された場合 True を返します。シグナルに対してハンドラが設定されていない場合には False を返します。

利用可能な環境: Unix。

参考

signal モジュール。

スレッドまたはプロセスプールでコードを実行する

awaitable loop.run_in_executor(executor, func, *args)

指定したエグゼキュータで関数 func が実行されるように準備します。

引数 executor は concurrent.futures.Executor のインスタンスでなければなりません。 executor が None の場合はデフォルトのエグゼキュータが使われます。

以下はプログラム例です:

import asyncio
import concurrent.futures

def blocking_io():
    # File operations (such as logging) can block the
    # event loop: run them in a thread pool.
    with open('/dev/urandom', 'rb') as f:
        return f.read(100)

def cpu_bound():
    # CPU-bound operations will block the event loop:
    # in general it is preferable to run them in a
    # process pool.
    return sum(i * i for i in range(10 ** 7))

async def main():
    loop = asyncio.get_running_loop()

    ## Options:

    # 1. Run in the default loop's executor:
    result = await loop.run_in_executor(
        None, blocking_io)
    print('default thread pool', result)

    # 2. Run in a custom thread pool:
    with concurrent.futures.ThreadPoolExecutor() as pool:
        result = await loop.run_in_executor(
            pool, blocking_io)
        print('custom thread pool', result)

    # 3. Run in a custom process pool:
    with concurrent.futures.ProcessPoolExecutor() as pool:
        result = await loop.run_in_executor(
            pool, cpu_bound)
        print('custom process pool', result)

if __name__ == '__main__':
    asyncio.run(main())

Note that the entry point guard (if __name__ == '__main__') is required for option 3 due to the peculiarities of multiprocessing, which is used by ProcessPoolExecutor. See Safe importing of main module.

このメソッドは asyncio.Future オブジェクトを返します。

関数 func に キーワード引数を渡す 場合は functools.partial() を使ってください。

バージョン 3.5.3 で変更: loop.run_in_executor() は内部で生成するスレッドプールエグゼキュータの max_workers を設定せず、代わりにスレッドプールエグゼキュータ (ThreadPoolExecutor) にデフォルト値を設定させるようになりました。

loop.set_default_executor(executor)

Set executor as the default executor used by run_in_executor(). executor must be an instance of ThreadPoolExecutor.

バージョン 3.11 で変更: executor must be an instance of ThreadPoolExecutor.

エラーハンドリング API

イベントループ内での例外の扱い方をカスタマイズできます。

loop.set_exception_handler(handler)

handler を新しいイベントループ例外ハンドラーとして設定します。

handler が None の場合、デフォルトの例外ハンドラが設定されます。そうでなければ、 handler は (loop, context) に一致する関数シグネチャを持った呼び出し可能オブジェクトでなければなりません。ここで loop はアクティブなイベントループへの参照であり、 context は例外の詳細な記述からなる dict オブジェクトです (context についての詳細は call_exception_handler() メソッドのドキュメントを参照してください)。

If the handler is called on behalf of a Task or Handle, it is run in the contextvars.Context of that task or callback handle.

バージョン 3.12 で変更: The handler may be called in the Context of the task or handle where the exception originated.

loop.get_exception_handler()

現在の例外ハンドラを返します。カスタム例外ハンドラが設定されていない場合は None を返します。

Added in version 3.5.2.

loop.default_exception_handler(context)

デフォルトの例外ハンドラーです。

デフォルト例外ハンドラは、例外ハンドラが未設定の場合、例外が発生した時に呼び出されます。デフォルト例外ハンドラの挙動を受け入れるために、カスタム例外ハンドラから呼び出すことも可能です。

引数 context の意味は call_exception_handler() と同じです。

loop.call_exception_handler(context)

現在のイベントループ例外ハンドラーを呼び出します。

context は以下のキーを含む dict オブジェクトです (将来の Python バージョンで新しいキーが追加される可能性があります):

'message': エラーメッセージ;

'exception' (任意): 例外オブジェクト;

'future' (任意): asyncio.Future インスタンス;

'task' (optional): asyncio.Task instance;

'handle' (任意): asyncio.Handle インスタンス;

'protocol' (任意): プロトコル インスタンス;

'transport' (任意): トランスポート インスタンス;

'socket' (optional): socket.socket instance;

'asyncgen' (optional): Asynchronous generator that caused

the exception.

注釈

このメソッドはイベントループの派生クラスでオーバーロードされてはいけません。カスタム例外ハンドラの設定には set_exception_handler() メソッドを使ってください。

デバッグモードの有効化

loop.get_debug()

イベントループのデバッグモード (bool) を取得します。

環境変数 PYTHONASYNCIODEBUG に空でない文字列が設定されている場合のデフォルト値は True、そうでない場合は False になります。

loop.set_debug(enabled: bool)

イベントループのデバッグモードを設定します。

バージョン 3.7 で変更: 新しい Python 開発モード を使ってデバッグモードを有効化することができるようになりました。

loop.slow_callback_duration

This attribute can be used to set the minimum execution duration in seconds that is considered "slow". When debug mode is enabled, "slow" callbacks are logged.

Default value is 100 milliseconds.

参考

asyncio のデバッグモード。

サブプロセスの実行

この節で解説しているのは低水準のメソッドです。通常の async/await コードでは、高水準の関数である asyncio.create_subprocess_shell() や asyncio.create_subprocess_exec() を代わりに使うことを検討してください。

注釈

On Windows, the default event loop ProactorEventLoop supports subprocesses, whereas SelectorEventLoop does not. See Subprocess Support on Windows for details.

coroutine loop.subprocess_exec(protocol_factory, *args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, **kwargs)

args で指定されたひとつの、または複数の文字列引数からサブプロセスを生成します。

args は下記のいずれかに当てはまる文字列のリストでなければなりません:

str;

または ファイルシステムのエンコーディング にエンコードされた bytes

引数の最初の文字列はプログラムの実行ファイルを指定します。それに続く残りの文字列は引数を指定し、そのプログラムに対する argv を構成します。

このメソッドは標準ライブラリの subprocess.Popen クラスを、 shell=False かつ最初の引数に文字列のリストを渡して呼び出した場合に似ています。しかし、 Popen クラスは文字列のリストを引数としてひとつだけ取るのに対して、 subprocess_exec は複数の文字列引数をとることができます。

protocol_factory は asyncio.SubprocessProtocol クラスの派生クラスを返す呼び出し可能オブジェクトでなければなりません。

その他の引数:

stdin は下記のいずれかをとることができます:

a file-like object

an existing file descriptor (a positive integer), for example those created with os.pipe()

デフォルト値は subprocess.PIPE 定数で、この場合新規にパイプを生成して接続します。

None が設定された場合、サブプロセスは元のプロセスのファイルデスクリプタを引き継ぎます。

subprocess.DEVNULL 定数を設定すると、特別なファイル os.devnull を使います。

stdout は下記のいずれかをとることができます:

a file-like object

デフォルト値は subprocess.PIPE 定数で、この場合新規にパイプを生成して接続します。

None が設定された場合、サブプロセスは元のプロセスのファイルデスクリプタを引き継ぎます。

subprocess.DEVNULL 定数を設定すると、特別なファイル os.devnull を使います。

stderr は下記のいずれかをとることができます:

a file-like object

デフォルト値は subprocess.PIPE 定数で、この場合新規にパイプを生成して接続します。

None が設定された場合、サブプロセスは元のプロセスのファイルデスクリプタを引き継ぎます。

subprocess.DEVNULL 定数を設定すると、特別なファイル os.devnull を使います。

subprocess.STDOUT 定数を設定すると、標準エラー出力ストリームをプロセスの標準出力ストリームに接続します。

その他のすべてのキーワード引数は解釈されずにそのまま subprocess.Popen に渡されます。ただし、 bufsize、 universal_newlines、 shell、 text、 encoding および errors は指定してはいけません。

asyncio のサブプロセス API はストリームからテキストへのデコードをサポートしていません。ストリームからテキストに変換するには bytes.decode() 関数を使ってください。

If a file-like object passed as stdin, stdout or stderr represents a pipe, then the other side of this pipe should be registered with connect_write_pipe() or connect_read_pipe() for use with the event loop.

他の引数についての詳細は subprocess.Popen クラスのコンストラクタを参照してください。

(transport, protocol) のペアを返します。ここで transport は asyncio.SubprocessTransport 基底クラスに適合するオブジェクトで、 protocol は protocol_factory によりインスタンス化されたオブジェクトです。

coroutine loop.subprocess_shell(protocol_factory, cmd, *, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, **kwargs)

コマンド cmd からプラットフォームの "シェル" シンタックスを使ってサブプロセスを生成します。 cmd は str 文字列もしくは ファイルシステムのエンコーディング でエンコードされた bytes 文字列です。

これは標準ライブラリの subprocess.Popen クラスを shell=True で呼び出した場合と似ています。

protocol_factory は SubprocessProtocol の派生クラスを返す呼び出し可能オブジェクトでなければなりません。

その他の引数についての詳細は subprocess_exec() メソッドを参照してください。

(transport, protocol) のペアを返します。ここで transport は SubprocessTransport 基底クラスに適合するオブジェクトで、 protocol は protocol_factory によりインスタンス化されたオブジェクトです。

注釈

シェルインジェクション [https://en.wikipedia.org/wiki/Shell_injection#Shell_injection] の脆弱性を回避するために全ての空白文字および特殊文字を適切にクオートすることは、アプリケーション側の責任で確実に行ってください。シェルコマンドを構成する文字列内の空白文字と特殊文字のエスケープは、 shlex.quote() 関数を使うと適切に行うことができます。

コールバックのハンドル

class asyncio.Handle

loop.call_soon() や loop.call_soon_threadsafe() が返すコールバックのラッパーです。

get_context()

Return the contextvars.Context object associated with the handle.

Added in version 3.12.

cancel()

コールバックをキャンセルします。コールバックがキャンセル済みまたは実行済みの場合、このメソッドは何の影響もありません。

cancelled()

コールバックがキャンセルされた場合 True を返します。

Added in version 3.7.

class asyncio.TimerHandle

A callback wrapper object returned by loop.call_later(), and loop.call_at().

このクラスは Handle の派生クラスです。

when()

コールバックのスケジュール時刻を秒単位の float で返します。

戻り値の時刻は絶対値で、 loop.time() と同じ参照時刻を使って定義されています。

Added in version 3.7.

Serverオブジェクト

Server オブジェクトは loop.create_server()、 loop.create_unix_server()、 start_server() および start_unix_server() 関数により生成されます。

Do not instantiate the Server class directly.

class asyncio.Server

Server オブジェクトは非同期のコンテキストマネージャです。 async with 文の中で使われた場合、 async with 文が完了した時に Server オブジェクトがクローズされること、およびそれ以降に接続を受け付けないことが保証されます。

srv = await loop.create_server(...)

async with srv:
    # some code

# At this point, srv is closed and no longer accepts new connections.

バージョン 3.7 で変更: Python 3.7 から、 Server オブジェクトは非同期のコンテキストマネージャになりました。

バージョン 3.11 で変更: This class was exposed publicly as asyncio.Server in Python 3.9.11, 3.10.3 and 3.11.

close()

サーバーを停止します: 待機しているソケットをクローズし sockets 属性に None を設定します。

既存の受信中のクライアントとの接続を表すソケットはオープンのままです。

The server is closed asynchronously; use the wait_closed() coroutine to wait until the server is closed (and no more connections are active).

get_loop()

サーバオブジェクトに付随するイベントループを返します。

Added in version 3.7.

coroutine start_serving()

接続の受け付けを開始します。

This method is idempotent, so it can be called when the server is already serving.

キーワード専用のパラメータ start_serving を loop.create_server() や asyncio.start_server() メソッドに対して使用することにより、初期に接続を受け付けない Server オブジェクトを生成することができます。この場合 Server.start_serving() または Server.serve_forever() メソッドを使ってオブジェクトが接続の受け付けを開始するようにすることができます。

Added in version 3.7.

coroutine serve_forever()

接続の受け入れを開始し、コルーチンがキャンセルされるまで継続します。 serve_forever タスクのキャンセルによりサーバーもクローズされます。

このメソッドはサーバーがすでに接続の受け入れを開始していても呼び出し可能です。ひとつの Server オブジェクトにつき serve_forever タスクはひとつだけ存在できます。

以下はプログラム例です:

async def client_connected(reader, writer):
    # Communicate with the client with
    # reader/writer streams.  For example:
    await reader.readline()

async def main(host, port):
    srv = await asyncio.start_server(
        client_connected, host, port)
    await srv.serve_forever()

asyncio.run(main('127.0.0.1', 0))

Added in version 3.7.

is_serving()

サーバーが新規に接続の受け入れを開始した場合 True を返します。

Added in version 3.7.

coroutine wait_closed()

Wait until the close() method completes and all active connections have finished.

sockets

List of socket-like objects, asyncio.trsock.TransportSocket, which the server is listening on.

バージョン 3.7 で変更: Python 3.7 より前のバージョンでは、 Server.sockets は内部に持っているサーバーソケットのリストを直接返していました。 Python 3.7 ではリストのコピーが返されるようになりました。

イベントループの実装

asyncio は2つの異なるイベントループの実装、 SelectorEventLoop と ProactorEventLoop、 を提供します:

By default asyncio is configured to use SelectorEventLoop on Unix and ProactorEventLoop on Windows.

class asyncio.SelectorEventLoop

An event loop based on the selectors module.

プラットフォーム上で利用可能な最も効率の良い selector を使います。特定のセレクタ実装を使うように手動で構成することも可能です:

import asyncio
import selectors

class MyPolicy(asyncio.DefaultEventLoopPolicy):
   def new_event_loop(self):
      selector = selectors.SelectSelector()
      return asyncio.SelectorEventLoop(selector)

asyncio.set_event_loop_policy(MyPolicy())

Availability: Unix, Windows。

class asyncio.ProactorEventLoop

An event loop for Windows that uses "I/O Completion Ports" (IOCP).

利用可能な環境: Windows 。

参考

I/O 完了ポートに関する MSDN のドキュメント [https://docs.microsoft.com/en-ca/windows/desktop/FileIO/i-o-completion-ports].

class asyncio.AbstractEventLoop

asyncio に適合するイベントループの抽象基底クラスです。

The イベントループのメソッド section lists all methods that an alternative implementation of AbstractEventLoop should have defined.

使用例

この節の全ての使用例は 意図的に loop.run_forever() や loop.call_soon() のような 低水準のイベントループ API の使用法を示しています。一方で現代的な asyncio アプリケーションはここに示すような方法をほとんど必要としません。 asyncio.run() のような高水準の関数の使用を検討してください。

call_soon() を使った Hello World

loop.call_soon() メソッドを使ってコールバックをスケジュールする例です。コールバックは "Hello World" を出力しイベントループを停止します:

import asyncio

def hello_world(loop):
    """A callback to print 'Hello World' and stop the event loop"""
    print('Hello World')
    loop.stop()

loop = asyncio.new_event_loop()

# Schedule a call to hello_world()
loop.call_soon(hello_world, loop)

# Blocking call interrupted by loop.stop()
try:
    loop.run_forever()
finally:
    loop.close()

参考

コルーチンと run() 関数を使用した同じような Hello World の例。

call_later() で現在の日時を表示する

毎秒現在時刻を表示するコールバックの例です。コールバックは loop.call_later() メソッドを使って自身を5秒後に実行するよう再スケジュールし、イベントループを停止します:

import asyncio
import datetime

def display_date(end_time, loop):
    print(datetime.datetime.now())
    if (loop.time() + 1.0) < end_time:
        loop.call_later(1, display_date, end_time, loop)
    else:
        loop.stop()

loop = asyncio.new_event_loop()

# Schedule the first call to display_date()
end_time = loop.time() + 5.0
loop.call_soon(display_date, end_time, loop)

# Blocking call interrupted by loop.stop()
try:
    loop.run_forever()
finally:
    loop.close()

参考

コルーチンと run() 関数を使用した同じような 現在時刻出力 の例。

読み込みイベント用ファイル記述子の監視

ファイル記述子が loop.add_reader() メソッドを使って何らかのデータを受信するまで待機し、その後イベントループをクローズします:

import asyncio
from socket import socketpair

# Create a pair of connected file descriptors
rsock, wsock = socketpair()

loop = asyncio.new_event_loop()

def reader():
    data = rsock.recv(100)
    print("Received:", data.decode())

    # We are done: unregister the file descriptor
    loop.remove_reader(rsock)

    # Stop the event loop
    loop.stop()

# Register the file descriptor for read event
loop.add_reader(rsock, reader)

# Simulate the reception of data from the network
loop.call_soon(wsock.send, 'abc'.encode())

try:
    # Run the event loop
    loop.run_forever()
finally:
    # We are done. Close sockets and the event loop.
    rsock.close()
    wsock.close()
    loop.close()

参考

トランスポート、プロトコル、および loop.create_connection() メソッドを使用した同じような 例。

高水準の asyncio.open_connection() 関数とストリームを使用したもうひとつの 実装例。

SIGINT および SIGTERM 用のシグナルハンドラーの設定

(ここに挙げる signals の例は Unix でのみ動きます。)

Register handlers for signals SIGINT and SIGTERM using the loop.add_signal_handler() method:

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())

Future

ソースコード: Lib/asyncio/futures.py [https://github.com/python/cpython/tree/3.12/Lib/asyncio/futures.py], Lib/asyncio/base_futures.py [https://github.com/python/cpython/tree/3.12/Lib/asyncio/base_futures.py]

Future オブジェクトは 低水準のコールバックベースのコード と高水準の async/await コードとの間を橋渡しします。

Future の関数

asyncio.isfuture(obj)

オブジェクト obj が下記のいずれかであれば True を返します:

asyncio.Future クラスのインスタンス

asyncio.Task クラスのインスタンス

_asyncio_future_blocking 属性を持った Future 的なオブジェクト

Added in version 3.5.

asyncio.ensure_future(obj, *, loop=None)

下記のいずれかを返します:

obj が Future オブジェクト、 Task オブジェクト、または Future 的なオブジェクト (isfuture() 関数を使って検査します) である場合には obj そのもの

引数 obj がコルーチンである (iscoroutine() 関数を使って検査します) 場合には obj をラップした Task オブジェクト; この場合コルーチンは ensure_future() によりスケジュールされます。

引数 obj が awaitable である (inspect.isawaitable() 関数を使って検査します) 場合には obj を await する Task オブジェクト

引数 obj が上記のいずれにもあてはまらない場合は TypeError 例外を送出します。

重要

Task を生成するより好ましい方法である create_task() 関数も参照してください。

Save a reference to the result of this function, to avoid a task disappearing mid-execution.

バージョン 3.5.1 で変更: この関数はどんな awaitable なオブジェクトでも受け入れるようになりました。

バージョン 3.10 で非推奨: Deprecation warning is emitted if obj is not a Future-like object and loop is not specified and there is no running event loop.

asyncio.wrap_future(future, *, loop=None)

concurrent.futures.Future オブジェクトを asyncio.Future オブジェクトでラップします。

バージョン 3.10 で非推奨: Deprecation warning is emitted if future is not a Future-like object and loop is not specified and there is no running event loop.

Future オブジェクト

class asyncio.Future(*, loop=None)

Future は非同期処理の最終結果を表すクラスです。スレッドセーフではありません。

Future is an awaitable object. Coroutines can await on Future objects until they either have a result or an exception set, or until they are cancelled. A Future can be awaited multiple times and the result is same.

典型的には、 Future は低水準のコールバックベースのコード (たとえば asyncio の transports を使って実装されたプロトコル) が高水準の async/await と相互運用することを可能にするために利用されます。

経験則は Future オブジェクトをユーザー向けの API であらわに利用しないことです。推奨される Future オブジェクトの生成方法は loop.create_future() を呼び出すことです。これによりイベントループの代替実装は、自身に最適化された Future オブジェクトの実装を合わせて提供することができます。

バージョン 3.7 で変更: contextvars モジュールのサポートを追加。

バージョン 3.10 で非推奨: Deprecation warning is emitted if loop is not specified and there is no running event loop.

result()

Future の結果を返します。

Future が 完了 していて、 set_result() メソッドにより設定された結果を持っている場合は結果の値を返します。

Future が 完了 していて、 set_exception() メソッドにより設定された例外を持っている場合はその例外を送出します。

Future が キャンセルされた 場合、このメソッドは CancelledError 例外を送出します。

Future の結果が未設定の場合、このメソッドは InvalidStateError 例外を送出します。

set_result(result)

Future を 完了 とマークし、結果を設定します。

Future がすでに 完了 している場合 InvalidStateError 例外を送出します。

set_exception(exception)

Future を 完了 とマークし、例外を設定します。

Future がすでに 完了 している場合 InvalidStateError 例外を送出します。

done()

Future が 完了 しているなら True を返します。

Future は キャンセルされた か、または set_result() メソッドや set_exception() メソッドの呼び出しにより結果や例外が設定された場合に 完了 とみなされます。

cancelled()

Future が キャンセルされた 場合に True を返します。

通常の場合、このメソッドは Future に処理結果や例外を設定する前に Future が キャンセルされていない ことを確認するために使用されます:

if not fut.cancelled():
    fut.set_result(42)

add_done_callback(callback, *, context=None)

Future が 完了 したときに実行されるコールバックを追加します。

callback は Future オブジェクトだけを引数にとって呼び出されます。

このメソッドが呼び出される時点ですでに Future が 完了 している場合、コールバックは loop.call_soon() メソッドによりスケジュールされます。

オプションのキーワード引数 context を使って、コールバック*callback* を実行する際のコンテキスト contextvars.Context を設定することができます。コンテキスト context が指定されない場合は現在のコンテキストが使われます。

コールバックにパラメータを渡すには、次の例のように functools.partial() を使うことができます:

# Call 'print("Future:", fut)' when "fut" is done.
fut.add_done_callback(
    functools.partial(print, "Future:"))

バージョン 3.7 で変更: キーワード引数 context が追加されました。詳細は PEP 567 [https://peps.python.org/pep-0567/] を参照してください。

remove_done_callback(callback)

コールバックリストから callback を削除します。

削除されたコールバックの数を返します。コールバックが複数回追加されていない限り、通常は1が返ります。

cancel(msg=None)

Future をキャンセルし、コールバックをスケジュールします。

Future がすでに 完了 または キャンセル された場合、 False を返します。そうでない場合 Future の状態を キャンセル に変更した上でコールバックをスケジュールし、 True を返します。

バージョン 3.9 で変更: Added the msg parameter.

exception()

この Future オブジェクトに設定された例外を返します。

例外 (または例外が設定されていないときは None) は Future が 完了 している場合のみ返されます。

Future が キャンセルされた 場合、このメソッドは CancelledError 例外を送出します。

Future が 未完了 の場合、このメソッドは InvalidStateError 例外を送出します。

get_loop()

Future オブジェクトが束縛されているイベントループを返します。

Added in version 3.7.

この例は Future オブジェクトを生成し、Future に結果を設定するための非同期タスクを生成してスケジュールし、そして Future に結果が設定されるまで待機します:

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())

重要

Future オブジェクトは concurrent.futures.Future を模倣してデザインされました。両者の重要な違いは以下の通りです:

asyncio の Futures と異なり、 concurrent.futures.Future インスタンスは待ち受けできません。

asyncio.Future.result() と asyncio.Future.exception() は timeout 引数を取りません。

asyncio.Future.result() と asyncio.Future.exception() は Future が 未完了 の場合に InvalidStateError 例外を送出します。

asyncio.Future.add_done_callback() メソッドによって登録されたコールバックは、即座に呼び出されません。代わりにコールバックは loop.call_soon() によりスケジュールされます。

asyncio の Future は concurrent.futures.wait() および concurrent.futures.as_completed() との互換性がありません。

asyncio.Future.cancel() accepts an optional msg argument, but concurrent.futures.Future.cancel() does not.

トランスポートとプロトコル

まえがき

トランスポートとプロトコルは loop.create_connection() のような 低水準の イベントループ API から使われます。これらはコールバックに基づくプログラミングスタイルを使うことでネットワークや IPC プロトコル (HTTP など) の高性能な実装を可能にします。

基本的にトランスポートとプロトコルはライブラリやフレームワークからのみ使われるべきであり、高水準の asyncio アプリケーションから使われるものではありません。

このドキュメントは Transports と Protocols を扱います。

はじめに

最上位の観点からは、トランスポートは どのように バイトデータを送信するかに影響を与え、いっぽうプロトコルは どの バイトデータを送信するかを決定します (また、ある程度は いつ も決定します) 。

同じことを違う言い方で表現します: トランスポートはソケット (または同様の I/O 端点) の抽象化であり、プロトコルはトランスポートから見たときのアプリケーションの抽象化です。

さらにもう一つの見方として、トランスポートとプロトコルの2つのインターフェースは、協調してネットワーク I/O やプロセス間 I/O の抽象インターフェースを定義しています。

トランスポートオブジェクトとプロトコルオブジェクトの間には常に1対1の関係があります: プロトコルはデータを送信するためにトランスポートのメソッドを呼び出し、トランスポートは受信したデータを渡すためにプロトコルのメソッドを呼び出します。

ほとんどの接続に基づくイベントループメソッド (loop.create_connection() など) は通常 protocol_factory 引数を受け取り、 Transport オブジェクトで表現される確立した接続に対する Protocol オブジェクトを生成するために使います。そのようなメソッドは通常 (transport, protocol) タプルを返します。

内容

このページは以下の節から構成されます:

Transports 節は asyncio の BaseTransport, ReadTransport, WriteTransport, Transport, DatagramTransport, および SubprocessTransport クラスについて記述しています。

Protocols 節は asyncio の BaseProtocol, Protocol, BufferedProtocol, DatagramProtocol, および SubprocessProtocol クラスについて記述しています。

Examples 節はトランスポート、プロトコル、および低水準のイベントループ API の利用方法を紹介しています。

トランスポート

ソースコード: Lib/asyncio/transports.py [https://github.com/python/cpython/tree/3.12/Lib/asyncio/transports.py]

トランスポートはさまざまな通信方法を抽象化するために asyncio が提供するクラス群です。

トランスポートオブジェクトは常に asyncio イベントループ によってインスタンス化されます。

asyncio は TCP, UDP, SSL, およびサブプロセスパイプのトランスポートを実装しています。利用可能なトランスポートのメソッドはトランスポートの種類に依存します。

トランスポートクラスは スレッド安全ではありません。

トランスポートのクラス階層構造

class asyncio.BaseTransport

全てのトランスポートの基底クラスです。すべての asyncio トランスポートが共有するメソッドを含んでいます。

class asyncio.WriteTransport(BaseTransport)

書き込み専用の接続に対する基底トランスポートクラスです。

WriteTransport クラスのインスタンスは loop.connect_write_pipe() イベントループメソッドから返され、 loop.subprocess_exec() のようなサブプロセスに関連するメソッドから利用されます。

class asyncio.ReadTransport(BaseTransport)

読み込み専用の接続に対する基底トランスポートクラスです。

Instances of the ReadTransport class are returned from the loop.connect_read_pipe() event loop method and are also used by subprocess-related methods like loop.subprocess_exec().

class asyncio.Transport(WriteTransport, ReadTransport)

TCP 接続のような、読み出しと書き込みの双方向のトランスポートを表現するインターフェースです。

ユーザーはトランスポートを直接インスタンス化することはありません; ユーザーは、ユーティリティ関数にプロトコルファクトリとその他トランスポートとプロトコルを作成するために必要な情報を渡して呼び出します。

Transport クラスのインスタンスは、loop.create_connection(), loop.create_unix_connection(), loop.create_server(), loop.sendfile() などのイベントループメソッドから返されたり、これらのメソッドから利用されたりします。

class asyncio.DatagramTransport(BaseTransport)

データグラム (UDP) 接続のためのトランスポートです。

DatagramTransport クラスのインスタンスは loop.create_datagram_endpoint() イベントループメソッドから返されます。

class asyncio.SubprocessTransport(BaseTransport)

親プロセスとその子プロセスの間の接続を表現する抽象クラスです。

SubprocessTransport クラスのインスタンスは loop.subprocess_shell() と loop.subprocess_exec() の2つのイベントループメソッドから返されます。

基底トランスポート

BaseTransport.close()

トランスポートをクローズします。

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 protocol.connection_lost() method will be called with None as its argument. The transport should not be used once it is closed.

BaseTransport.is_closing()

トランスポートを閉じている最中か閉じていた場合 True を返します。

BaseTransport.get_extra_info(name, default=None)

トランスポートまたはそれが背後で利用しているリソースの情報を返します。

name は取得するトランスポート特有の情報を表す文字列です。

default は、取得したい情報が取得可能でなかったり、サードパーティのイベントループ実装や現在のプラットフォームがその情報の問い合わせをサポートしていない場合に返される値です。

例えば、以下のコードはトランスポート内のソケットオブジェクトを取得しようとします:

sock = transport.get_extra_info('socket')
if sock is not None:
    print(sock.getsockopt(...))

いくつかのトランスポートで問い合わせ可能な情報のカテゴリを示します:

ソケット:

'peername': ソケットが接続されているリモートアドレスで、socket.socket.getpeername() の結果になります (エラーのときは None)

'socket': socket.socket のインスタンスになります

'sockname': ソケット自身のアドレスで、socket.socket.getsockname() の結果になります

SSL ソケット:

'compression': 圧縮アルゴリズムで、ssl.SSLSocket.compression() の結果になります。圧縮されていないときは None になります

'cipher': 3 個の値 (使用されている暗号アルゴリズムの名称、使用が定義されている SSL プロトコルのバージョン、および使用されている秘密鍵のビット数) からなるタプルで、ssl.SSLSocket.cipher() の結果になります

'peercert': ピアの証明書で、ssl.SSLSocket.getpeercert() の結果になります

'sslcontext': ssl.SSLContext のインスタンスになります

'ssl_object': ssl.SSLObject または ssl.SSLSocket インスタンス

パイプ:

'pipe': パイプオブジェクトです

サブプロセス:

'subprocess': subprocess.Popen のインスタンスになります

BaseTransport.set_protocol(protocol)

トランスポートに新しいプロトコルを設定します。

プロトコルの切り替えは、両方のプロトコルのドキュメントで切り替えがサポートされている場合にのみ行うべきです。

BaseTransport.get_protocol()

現在のプロトコルを返します。

読み出し専用のトランスポート

ReadTransport.is_reading()

トランスポートが新しいデータを受信中の場合 True を返します。

Added in version 3.7.

ReadTransport.pause_reading()

トランスポートの受信側を一時停止します。 resume_reading() メソッドが呼び出されるまでプロトコルの protocol.data_received() メソッドにデータは渡されません。

バージョン 3.7 で変更: このメソッドはべき等です。すなわちトランスポートがすでに停止していたりクローズしていても呼び出すことができます。

ReadTransport.resume_reading()

受信を再開します。データが読み込み可能になるとプロトコルの protocol.data_received() メソッドが再び呼び出されるようになります。

バージョン 3.7 で変更: このメソッドはべき等です。すなわちトランスポートがすでにデータを読み込み中であっても呼び出すことができます。

書き込み専用のトランスポート

WriteTransport.abort()

未完了の処理が完了するのを待たず、即座にトランスポートをクローズします。バッファーされているデータは失われます。このメソッドの呼び出し以降データは受信されません。最終的にプロトコルの protocol.connection_lost() メソッドが引数 None で呼び出されます。

WriteTransport.can_write_eof()

トランスポートが write_eof() メソッドをサポートしている場合 True を返し、そうでない場合は False を返します。

WriteTransport.get_write_buffer_size()

トランスポートで使用されている出力バッファーの現在のサイズを返します。

WriteTransport.get_write_buffer_limits()

書き込みフロー制御の 最高 および 最低 水位点を取得します。 (low, high) タプルを返します。ここで low と high はバイト数をあらわす正の整数です。

水位点の設定は set_write_buffer_limits() で行います。

Added in version 3.4.2.

WriteTransport.set_write_buffer_limits(high=None, low=None)

書き込みフロー制御の 最高 および 最低 水位点を設定します。

(バイト数をあらわす) これら2つの値はプロトコルの protocol.pause_writing() と protocol.resume_writing() の2つのメソッドがいつ呼ばれるかを制御します。指定する場合、 low は high と等しいかまたは high より小さくなければなりません。また、 high も low も負の値を指定することはできません。

pause_writing() はバッファーサイズが high の値以上になった場合に呼び出されます。書き込みが一時停止している場合、バッファーサイズが low の値以下になると resume_writing() メソッドが呼び出されます。

デフォルト値は実装固有になります。 high のみ与えられた場合、 low は high 以下の実装固有のデフォルト値になります。 high をゼロに設定すると low も強制的にゼロになり、バッファーが空でなくなるとすぐに pause_writing() メソッドが呼び出されるようになります。 low をゼロに設定すると、バッファーが空にな resume_writing() が呼び出されるようになります。どちらかにゼロを設定することは I/O と計算を並行に実行する機会を減少させるため、一般に最適ではありません。

上限値と下限値を取得するには get_write_buffer_limits() メソッドを使ってください。

WriteTransport.write(data)

トランスポートにバイト列 data を書き込みます。

このメソッドはブロックしません; データをバッファーし、非同期に送信する準備を行います。

WriteTransport.writelines(list_of_data)

バイト列のデータのリスト (またはイテラブル) をトランスポートに書き込みます。この振る舞いはイテラブルを yield して各要素で write() を呼び出すことと等価ですが、より効率的な実装となる場合があります。

WriteTransport.write_eof()

バッファーされた全てのデータをフラッシュした後トランスポートの送信側をクローズします。送信側をクローズした後もデータを受信することは可能です。

このメソッドはトランスポート (例えば SSL) がハーフクローズドな接続をサポートしていない場合 NotImplementedError を送出します。

データグラムトランスポート

DatagramTransport.sendto(data, addr=None)

リモートピア addr (トランスポート依存の対象アドレス) にバイト列 data を送信します。addr が None の場合、データはトランスポートの作成時に指定された送信先に送られます。

このメソッドはブロックしません; データをバッファーし、非同期に送信する準備を行います。

DatagramTransport.abort()

未完了の処理が完了するのを待たず、即座にトランスポートをクローズします。バッファーされているデータは失われます。このメソッドの呼び出し以降データは受信されません。最終的にプロトコルの protocol.connection_lost() メソッドが引数 None で呼び出されます。

サブプロセス化されたトランスポート

SubprocessTransport.get_pid()

サブプロセスのプロセス ID (整数) を返します。

SubprocessTransport.get_pipe_transport(fd)

整数のファイル記述子 fd に該当する通信パイプのトランスポートを返します:

0: 標準入力 (stdin) の読み込み可能ストリーミングトランスポート。サブプロセスが stdin=PIPE で作成されていない場合は None

1: 標準出力 (stdout) の書き込み可能ストリーミングトランスポート。サブプロセスが stdout=PIPE で作成されていない場合は None

2: 標準エラー出力 (stderr) の書き込み可能ストリーミングトランスポート。サブプロセスが stderr=PIPE で作成されていない場合は None

その他の fd: None

SubprocessTransport.get_returncode()

サブプロセスのリターンコードを整数で返します。サブプロセスがリターンしなかった場合は None を返します。 subprocess.Popen.returncode 属性と同じです。

SubprocessTransport.kill()

サブプロセスを強制終了 (kill) します。

POSIX システムでは、この関数はサブプロセスに SIGKILL を送信します。Windows では、このメソッドは terminate() の別名です。

subprocess.Popen.kill() も参照してください。

SubprocessTransport.send_signal(signal)

サブプロセスにシグナル signal を送信します。subprocess.Popen.send_signal() と同じです。

SubprocessTransport.terminate()

サブプロセスを停止します。

On POSIX systems, this method sends SIGTERM to the subprocess. On Windows, the Windows API function TerminateProcess() is called to stop the subprocess.

subprocess.Popen.terminate() も参照してください。

SubprocessTransport.close()

kill() メソッドを呼び出すことでサブプロセスを強制終了します。

サブプロセスがまだリターンしていない場合、 stdin, stdout, および stderr の各パイプのトランスポートをクローズします。

プロトコル

ソースコード: Lib/asyncio/protocols.py [https://github.com/python/cpython/tree/3.12/Lib/asyncio/protocols.py]

asyncio はネットワークプロトコルを実装するために使う抽象基底クラス群を提供します。これらのクラスは トランスポート と組み合わせて使うことが想定されています。

抽象基底プロトコルクラスの派生クラスはメソッドの一部または全てを実装することができます。これらのメソッドは全てコールバックです: それらは、データを受信した、などの決まったイベントに対してトランスポートから呼び出されます。基底プロトコルメソッドは対応するトランスポートから呼び出されるべきです。

基底プロトコル

class asyncio.BaseProtocol

全てのプロトコルクラスが共有する全てのメソッドを持った基底プロトコルクラスです。

class asyncio.Protocol(BaseProtocol)

ストリーミングプロトコル (TCP, Unix ソケットなど) を実装するための基底クラスです。

class asyncio.BufferedProtocol(BaseProtocol)

受信バッファーを手動で制御するストリーミングプロトコルを実装するための基底クラスです。

class asyncio.DatagramProtocol(BaseProtocol)

データグラム (UDP) プロトコルを実装するための基底クラスです。

class asyncio.SubprocessProtocol(BaseProtocol)

子プロセスと (一方向パイプを通じて) 通信するプロトコルを実装するための基底クラスです。

基底プロトコル

全ての asyncio プロトコルは基底プロトコルのコールバックを実装することができます。

通信のコールバック

コネクションコールバックは全てのプロトコルから、成功したコネクションそれぞれにつきただ一度だけ呼び出されます。その他の全てのプロトコルコールバックはこれら2つのメソッドの間に呼び出すことができます。

BaseProtocol.connection_made(transport)

コネクションが作成されたときに呼び出されます。

引数 transport はコネクションをあらわすトランスポートです。プロトコルはトランスポートへの参照を保存する責任を負います。

BaseProtocol.connection_lost(exc)

コネクションが失われた、あるいはクローズされたときに呼び出されます。

引数は例外オブジェクトまたは None になります。None のとき、通常の EOF が受信されたか、あるいはコネクションがこちら側から中止またはクローズされたことを意味します。

フロー制御コールバック

フロー制御コールバックは、プロトコルによって実行される書き込み処理を停止または再開するためにトランスポートから呼び出されます。

詳しくは set_write_buffer_limits() メソッドのドキュメントを参照してください。

BaseProtocol.pause_writing()

トランスポートのバッファーサイズが最高水位点 (high watermark) を超えたときに呼び出されます。

BaseProtocol.resume_writing()

トランスポートのバッファーサイズが最低水位点 (low watermark) に達したきに呼び出されます。

バッファーサイズが最高水位点と等しい場合、 pause_writing() は呼び出されません: バッファーサイズは必ず制限値を超えなければなりません。

それに対して、 resume_writing() はバッファーサイズが最低水位点と等しいかそれよりも小さい場合に呼び出されます。これらの境界条件は、どちらの基準値もゼロである場合の処理が期待通りとなることを保証するために重要です。

ストリーミングプロトコル

loop.create_server(), loop.create_unix_server(), loop.create_connection(), loop.create_unix_connection(), loop.connect_accepted_socket(), loop.connect_read_pipe(), そして loop.connect_write_pipe() などのイベントメソッドはストリーミングプロトコルを返すファクトリを受け付けます。

Protocol.data_received(data)

データを受信したときに呼び出されます。data は受信したデータを含む空ではないバイト列オブジェクトになります。

データがバッファーされるか、チャンキングされるか、または再構築されるかはトランスポートに依存します。一般には、特定のセマンティクスを信頼するべきではなく、代わりにデータのパースを全般的かつ柔軟に行うべきです。ただし、データは常に正しい順序で受信されます。

このメソッドは、コネクションがオープンである間は何度でも呼び出すことができます。

However, protocol.eof_received() is called at most once. Once eof_received() is called, data_received() is not called anymore.

Protocol.eof_received()

コネクションの相手方がこれ以上データを送信しないことを伝えてきたとき (例えば相手方が asyncio を使用しており、 transport.write_eof() を呼び出した場合) に呼び出されます。

このメソッドは (None を含む) 偽値 を返すことがあり、その場合トランスポートは自身をクローズします。一方メソッドが真値を返す場合は、利用しているプロトコルがトランスポートをクローズするかどうかを決めます。デフォルトの実装は None を返すため、コネクションは暗黙のうちにクローズされます。

SSL を含む一部のトランスポートはハーフクローズ接続をサポートしません。そのような場合このメソッドが真値を返すとコネクションはクローズされます。

ステートマシン:

start -> connection_made
    [-> data_received]*
    [-> eof_received]?
-> connection_lost -> end

バッファリングされたストリーミングプロトコル

Added in version 3.7.

バッファー付きプロトコルは ストリーミングプロトコル をサポートするイベントループメソッドで利用することができます。

BufferedProtocol 実装は受信バッファーの手動での明示的な割り当てや制御を可能にします。イベントループはプロトコルにより提供されるバッファを利用することにより不要なデータのコピーを避けることができます。これにより大量のデータを受信するプロトコルにおいて顕著なパフォーマンスの向上をもたらします。精巧なプロトコル実装によりバッファー割り当ての数を劇的に減少させることができます。

以下に示すコールバックは BufferedProtocol インスタンスに対して呼び出されます:

BufferedProtocol.get_buffer(sizehint)

新しい受信バッファを割り当てるために呼び出します。

sizehint は返されるバッファーの推奨される最小サイズです。 sizehint によって推奨された値より小さい、または大きいサイズのバッファーを返すことは容認されています。 -1 がセットされた場合、バッファーサイズは任意となります。サイズがゼロのバッファーを返すとエラーになります。

get_buffer() は バッファープロトコル を実装したオブジェクトを返さなければなりません。

BufferedProtocol.buffer_updated(nbytes)

受信データによりバッファが更新された場合に呼び出されます。

nbytes はバッファに書き込まれた総バイト数です。

BufferedProtocol.eof_received()

protocol.eof_received() メソッドのドキュメントを参照してください。

コネクションの間、 get_buffer() は何度でも呼び出すことができます。しかし protocol.eof_received() が呼び出されるのは最大でも1回で、もし呼び出されると、それ以降 get_buffer() と buffer_updated() が呼び出されることはありません。

ステートマシン:

start -> connection_made
    [-> get_buffer
        [-> buffer_updated]?
    ]*
    [-> eof_received]?
-> connection_lost -> end

データグラムプロトコル

データグラムプロトコルのインスタンスは loop.create_datagram_endpoint() メソッドに渡されたプロトコルファクトリによって生成されるべきです。

DatagramProtocol.datagram_received(data, addr)

データグラムを受信したときに呼び出されます。data は受信データを含むバイトオブジェクトです。addr はデータを送信するピアのアドレスです; 正確な形式はトランスポートに依存します。

DatagramProtocol.error_received(exc)

直前の送信あるいは受信が OSError を送出したときに呼び出されます。exc は OSError のインスタンスになります。

このメソッドが呼ばれるのは、トランスポート (UDP など) がデータグラムを受信側に配信できなかったことが検出されたなどの、まれな場合においてのみです。ほとんどの場合、データグラムが配信できなければそのまま通知されることなく破棄されます。

注釈

BSD システム (macOS, FreeBSD など) ではフロー制御はサポートされていません。これは非常に多くのパケットを書き込もうとしたことによる送信の失敗を検出する信頼できる方法が存在しないためです。

ソケットは常に '準備ができた状態' のように振る舞いますが、超過したパケットは破棄されます。この場合 errno を errno.ENOBUFS に設定した OSError 例外が送出されることがあります。もし例外が送出された場合は DatagramProtocol.error_received() に通知されますが、送出されない場合は単に無視されます。

サブプロセスプロトコル

サブプロセスプロトコルのインスタンスは loop.subprocess_exec() と loop.subprocess_shell() メソッドに渡されたプロトコルファクトリにより生成されるべきです。

SubprocessProtocol.pipe_data_received(fd, data)

子プロセスが標準出力または標準エラー出力のパイプにデータを書き込んだ時に呼び出されます。

fd はパイプのファイル記述子を表す整数です。

data は受信データを含む空でないバイトオブジェクトです。

SubprocessProtocol.pipe_connection_lost(fd, exc)

子プロセスと通信するパイプのいずれかがクローズされたときに呼び出されます。

fd はクローズされたファイル記述子を表す整数です。

SubprocessProtocol.process_exited()

子プロセスが終了したときに呼び出されます。

It can be called before pipe_data_received() and pipe_connection_lost() methods.

使用例

TCP エコーサーバー

loop.create_server() メソッドを使って TCP エコーサーバーを生成し、受信したデータをそのまま送り返して、最後にコネクションをクローズします:

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(
        lambda: EchoServerProtocol(),
        '127.0.0.1', 8888)

    async with server:
        await server.serve_forever()

asyncio.run(main())

参考

ストリームを使った TCP エコーサーバー の例では高水準の asyncio.start_server() 関数を使っています。

TCP エコークライアント

loop.create_connection() メソッドを使った TCP エコークライアントは、データを送信したあとコネクションがクローズされるまで待機します:

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())

参考

ストリームを使った TCP エコークライアント の例では高水準の asyncio.open_connection() 関数を使っています。

UDP エコーサーバー

loop.create_datagram_endpoint() メソッドを使った UDP エコーサーバーは受信したデータをそのまま送り返します:

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(
        lambda: EchoServerProtocol(),
        local_addr=('127.0.0.1', 9999))

    try:
        await asyncio.sleep(3600)  # Serve for 1 hour.
    finally:
        transport.close()

asyncio.run(main())

UDP エコークライアント

loop.create_datagram_endpoint() メソッドを使った UDP エコークライアントはデータを送信し、応答を受信するとトランスポートをクローズします:

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())

既存のソケットへの接続

プロトコルを設定した loop.create_connection() メソッドを使ってソケットがデータを受信するまで待機します:

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())

参考

ファイル記述子の読み込みイベントを監視する 例では低レベルの loop.add_reader() メソッドを使ってファイル記述子 (FD) を登録しています。

ストリームを使ってデータを待ち受けるオープンなソケットを登録する 例ではコルーチン内で open_connection() 関数によって生成されたストリームを使っています。

loop.subprocess_exec() と SubprocessProtocol

サブプロセスからの出力を受け取り、サブプロセスが終了するまで待機するために使われるサブプロセスプロトコルの例です。

サブプロセスは loop.subprocess_exec() メソッドにより生成されます:

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}")

高水準の API を使って書かれた 同様の例 も参照してください。

ポリシー

An event loop policy is a global object used to get and set the current event loop, as well as create new event loops. The default policy can be replaced with built-in alternatives to use different event loop implementations, or substituted by a custom policy that can override these behaviors.

The 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 get_event_loop(), set_event_loop(), and new_event_loop().

ポリシーオブジェクトは AbstractEventLoopPolicy 抽象基底クラスで定義された API を実装しなければなりません。

ポリシーの取得と設定

以下の関数は現在のプロセスに対するポリシーの取得や設定をするために使われます:

asyncio.get_event_loop_policy()

プロセス全体にわたる現在のポリシーを返します。

asyncio.set_event_loop_policy(policy)

プロセス全体にわたる現在のポリシーを policy に設定します。

policy が None の場合、デフォルトポリシーが現在のポリシーに戻されます。

ポリシーオブジェクト

イベントループポリシーの抽象基底クラスは以下のように定義されています:

class asyncio.AbstractEventLoopPolicy

asyncio ポリシーの抽象基底クラスです。

get_event_loop()

現在のコンテキストのイベントループを取得します。

AbstractEventLoop のインターフェースを実装したイベントループオブジェクトを返します。

このメソッドは None を返してはいけません。

バージョン 3.6 で変更.

set_event_loop(loop)

現在のコンテキストにイベントループ loop を設定します。

new_event_loop()

新しいイベントループオブジェクトを生成して返します。

このメソッドは None を返してはいけません。

get_child_watcher()

子プロセスを監視するウオッチャーオブジェクトを返します。

AbstractChildWatcher のインターフェースを実装したウオッチャーオブジェクトを返します。

この関数は Unix 特有です。

バージョン 3.12 で非推奨.

set_child_watcher(watcher)

子プロセスに対する現在のウオッチャーオブジェクトを watcher に設定します。

この関数は Unix 特有です。

バージョン 3.12 で非推奨.

asyncio は以下の組み込みポリシーを提供します:

class asyncio.DefaultEventLoopPolicy

デフォルトの asyncio ポリシーです。Unix では SelectorEventLoop 、Windows では ProactorEventLoop を使います。

デフォルトのポリシーを手動でインストールする必要はありません。 asyncio はデフォルトポリシーを使うように自動的に構成されます。

バージョン 3.8 で変更: Windows では ProactorEventLoop がデフォルトで使われるようになりました。

バージョン 3.12 で非推奨: The get_event_loop() method of the default asyncio policy now emits a DeprecationWarning if there is no current event loop set and it decides to create one. In some future Python release this will become an error.

class asyncio.WindowsSelectorEventLoopPolicy

SelectorEventLoop イベントループ実装を使った別のイベントループポリシーです。

利用可能な環境: Windows 。

class asyncio.WindowsProactorEventLoopPolicy

ProactorEventLoop イベントループ実装を使った別のイベントループポリシーです。

利用可能な環境: Windows 。

プロセスのウオッチャー

プロセスのウオッチャーは Unix 上でイベントループが子プロセスを監視する方法をカスタマイズすることを可能にします。特に、子プロセスがいつ終了したかをイベントループは知る必要があります。

asyncio では、子プロセスは create_subprocess_exec() や loop.subprocess_exec() 関数により生成されます。

asyncio は、子プロセスのウオッチャーが実装すべき AbstractChildWatcher 抽象基底クラスを定義しており、さらに異なる4つの実装クラスを提供しています: ThreadedChildWatcher (デフォルトでこのクラスが使われるように構成されます), MultiLoopChildWatcher, SafeChildWatcher, そして FastChildWatcher です。

サブプロセスとスレッド 節も参照してください。

以下の2つの関数は asyncio のイベントループが使う子プロセスのウオッチャーの実装をカスタマイズするために使うことができます:

asyncio.get_child_watcher()

現在のポリシーにおける子プロセスのウオッチャーを返します。

バージョン 3.12 で非推奨.

asyncio.set_child_watcher(watcher)

現在ポリシーにおける子プロセスのウオッチャーを watcher に設定します。 watcher は AbstractChildWatcher 基底クラスで定義されたメソッドを実装していなければなりません。

バージョン 3.12 で非推奨.

注釈

サードパーティのイベントループ実装は子プロセスのウオッチャーのカスタマイズをサポートしていない可能性があります。そのようなイベントループでは、 set_child_watcher() 関数の利用は禁止されているか、または何の効果もありません。

class asyncio.AbstractChildWatcher

add_child_handler(pid, callback, *args)

新しい子プロセスのハンドラを登録します。

プロセス ID (PID) が pid であるプロセスが終了した時に callback(pid, returncode, *args) コールバック関数が呼び出されるように手配します。同じプロセスに対して別のコールバックを登録した場合、以前登録したハンドラを置き換えます。

callback はスレッドセーフな呼び出し可能オブジェクトでなければなりません。

remove_child_handler(pid)

プロセス ID (PID) が pid であるプロセスに対して登録されたハンドラを削除します。

ハンドラが正しく削除された場合 True を返します。削除するハンドラがない場合は False を返します。

attach_loop(loop)

ウオッチャーをイベントループに接続します。

ウオッチャーがイベントループに接続されている場合、新しいイベントループに接続される前に接続済みのイベントループから切り離されます。

注: 引数は None をとることができます。

is_active()

ウオッチャーが利用可能な状態なら True を返します。

現在の子プロセスのウオッチャーが アクティブでない 場合にサブプロセスを生成すると RuntimeError 例外が送出されます。

Added in version 3.8.

close()

ウオッチャーをクローズします。

このメソッドは、ウオッチャーの背後にあるリソースを確実にクリーンアップするために必ず呼び出さなければなりません。

バージョン 3.12 で非推奨.

class asyncio.ThreadedChildWatcher

この実装は、各サブプロセスの生成時に新しい待ち受けスレッドを開始します。

このクラスは asyncio イベントループがメインでない OS スレッド上で実行されていても期待通りに動きます。

There is no noticeable overhead when handling a big number of children (O(1) each time a child terminates), but starting a thread per process requires extra memory.

このウオッチャーはデフォルトで使われます。

Added in version 3.8.

class asyncio.MultiLoopChildWatcher

この実装はインスタンス化の際に SIGCHLD シグナルハンドラを登録します。これにより、独自の SIGCHLD シグナルハンドラをインストールするようなサードパーティのコードを壊す可能性があります。

このウオッチャーは、各プロセスに明示的に SIGCHLD シグナルをポーリングさせることにより、プロセスを生成する他のコードを中断させないようにします。

いったんウオッチャーがインストールされると、異なるスレッドからのサブプロセスの実行について特に制限はありません。

The solution is safe but it has a significant overhead when handling a big number of processes (O(n) each time a SIGCHLD is received).

Added in version 3.8.

バージョン 3.12 で非推奨.

class asyncio.SafeChildWatcher

この実装はメインスレッドでアクティブなイベントループを使って SIGCHLD シグナルを処理します。メインスレッドでイベントループが実行中でない場合、別のスレッドからサブプロセスを生成することはできません (RuntimeError 例外が送出されます)。

このウオッチャーは、各プロセスに明示的に SIGCHLD シグナルをポーリングさせることにより、プロセスを生成する他のコードを中断させないようにします。

This solution is as safe as MultiLoopChildWatcher and has the same O(n) complexity but requires a running event loop in the main thread to work.

バージョン 3.12 で非推奨.

class asyncio.FastChildWatcher

この実装は終了した子プロセスを得るために直接 os.waitpid(-1) を呼び出します。これにより、プロセスを生成してその終了を待ち受ける別のコードを壊す可能性があります。

There is no noticeable overhead when handling a big number of children (O(1) each time a child terminates).

このソリューションは、 SafeChildWatcher と同様にメインスレッドで実行中のイベントループが必要です。

バージョン 3.12 で非推奨.

class asyncio.PidfdChildWatcher

この実装は子プロセスの終了を待ち受けるためにプロセスのファイル記述子 (pidfds) をポーリングします。いくつかの点で、 PidfdChildWatcher は "Goldilocks" 的な子プロセスのウオッチャー実装です。この実装はシグナルもスレッドも必要とせず、イベントループの外で生成されたいかなるプロセスとも干渉せず、しかもイベントループから生成されたサブプロセスの数に対して線形にスケールします。主な欠点は pidfds が Linux 特有であり、最近のカーネル (5.3+) でしか動かないことです。

Added in version 3.9.

ポリシーのカスタマイズ

新しいイベントループのポリシーを実装するためには、以下に示すように DefaultEventLoopPolicy を継承して振る舞いを変更したいメソッドをオーバーライドすることが推奨されます。:

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())

プラットフォームでのサポート

asyncio モジュールは可搬的であるようにデザインされていますが、いくつかのプラットフォームでは、その根底にあるアーキテクチャや性能による微妙な動作の違いや制限があります。

全てのプラットホーム

loop.add_reader() と loop.add_writer() をファイル I/O を監視するためには使えません。

Windows

ソースコード: Lib/asyncio/proactor_events.py [https://github.com/python/cpython/tree/3.12/Lib/asyncio/proactor_events.py], Lib/asyncio/windows_events.py [https://github.com/python/cpython/tree/3.12/Lib/asyncio/windows_events.py], Lib/asyncio/windows_utils.py [https://github.com/python/cpython/tree/3.12/Lib/asyncio/windows_utils.py]

バージョン 3.8 で変更: Windows では ProactorEventLoop がデフォルトのイベントループになりました。

全ての Windows 上のイベントループは以下のメソッドをサポートしません:

loop.create_unix_connection() and loop.create_unix_server() are not supported. The socket.AF_UNIX socket family is specific to Unix.

loop.add_signal_handler() と loop.remove_signal_handler() はサポートされていません。

SelectorEventLoop は以下の制限があります:

SelectSelector はソケットイベントの待ち受けに使われます: このクラスはソケットをサポートしますが 512 ソケットまでに制限されています。

loop.add_reader() と loop.add_writer() はソケットハンドルのみを受け付けます (たとえばパイプファイル記述子はサポートされていません)。

パイプはサポートされていません。従って loop.connect_read_pipe() と loop.connect_write_pipe() の2つのメソッドは未実装です。

Subprocesses はサポートされていません。すなわち loop.subprocess_exec() と loop.subprocess_shell() の2つのメソッドは未実装です。

ProactorEventLoop は以下の制限があります:

loop.add_reader() と loop.add_writer() はサポートされていません。

The resolution of the monotonic clock on Windows is usually around 15.6 milliseconds. The best resolution is 0.5 milliseconds. The resolution depends on the hardware (availability of HPET [https://en.wikipedia.org/wiki/High_Precision_Event_Timer]) and on the Windows configuration.

Windows におけるサブプロセスのサポート

Windows において、デフォルトのイベントループ ProactorEventLoop はサブプロセスをサポートしますが、 SelectorEventLoop はサポートしません。

policy.set_child_watcher() 関数もサポートされません。 ProactorEventLoop は子プロセスを監視するための異なる仕組みを持っています。

macOS

最近の macOS バージョンは完全にサポートされています。

10.8 以前の macOS

macOS 10.6, 10.7 および 10.8 では、デフォルトイベントループは selectors.KqueueSelector をしていますが、このクラスはこれらの macOS バージョンのキャラクターデバイスをサポートしていません。これらの macOS バージョンでキャラクターデバイスをサポートするためには SelectorEventLoop で SelectSelector または PollSelector を使うように手動で設定します。以下はその例です:

import asyncio
import selectors

selector = selectors.SelectSelector()
loop = asyncio.SelectorEventLoop(selector)
asyncio.set_event_loop(loop)

Extending

The main direction for asyncio extending is writing custom event loop classes. Asyncio has helpers that could be used to simplify this task.

注釈

Third-parties should reuse existing asyncio code with caution, a new Python version is free to break backward compatibility in internal part of API.

Writing a Custom Event Loop

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

In turn, the successor should implement a bunch of private methods declared but not implemented in asyncio.BaseEventLoop.

For example, loop.create_connection() checks arguments, resolves DNS addresses, and calls loop._make_socket_transport() that should be implemented by inherited class. The _make_socket_transport() method is not documented and is considered as an internal API.

Future and Task private constructors

asyncio.Future and asyncio.Task should be never created directly, please use corresponding loop.create_future() and loop.create_task(), or 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:

Future.__init__(*, loop=None)

Create a built-in future instance.

loop is an optional event loop instance.

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 loop.create_task() description.

バージョン 3.11 で変更: context argument is added.

Task lifetime support

A third party task implementation should call the following functions to keep a task visible by asyncio.all_tasks() and asyncio.current_task():

asyncio._register_task(task)

Register a new task as managed by asyncio.

Call the function from a task constructor.

asyncio._unregister_task(task)

Unregister a task from asyncio internal structures.

The function should be called when a task is about to finish.

asyncio._enter_task(loop, task)

Switch the current task to the task argument.

Call the function just before executing a portion of embedded coroutine (coroutine.send() or coroutine.throw()).

asyncio._leave_task(loop, task)

Switch the current task back from task to None.

Call the function just after coroutine.send() or coroutine.throw() execution.

高水準の API インデックス

このページには、すべての高水準の 非同期/待機 可能な asyncio API が一覧になっています。

Task

ユーティリティは asyncio プログラムを実行し、タスクを作成し、タイムアウトのある複数の機能を待っています。

run()

イベントループを作成し、コルーチンを実行し、ループを閉じます。

Runner

複数の非同期関数呼び出しをシンプルにするコンテキストマネージャ。

Task

Task オブジェクト

TaskGroup

タスクのグループを保持するコンテキストマネージャ。グループに属するすべてのタスクが完了するのを待つのに便利で信頼性のある方法を提供します。

create_task()

Start an asyncio Task, then returns it.

current_task()

現在のタスクを返します。

all_tasks()

Return all tasks that are not yet finished for an event loop.

await sleep()

数秒間スリープします。

await gather()

並行してスケジュールして、待ちます。

await wait_for()

タイムアウトで実行します。

await shield()

取り消しから保護します。

await wait()

完了かどうかを監視します。

timeout()

Run with a timeout. Useful in cases when wait_for is not suitable.

to_thread()

Asynchronously run a function in a separate OS thread.

run_coroutine_threadsafe()

別の OS スレッドからコルーチンの実行をスケジュールします。

for in as_completed()

for ループ向けにコルーチンの完了を監視します。

使用例

asyncio.gather() を使って複数の処理を並列に実行する 。

asyncio.wait_for() を使って強制的にタイムアウトする 。

非同期処理をキャンセルする 。

asyncio.sleep() を使う 。

Tasks のドキュメント も参照してください。

キュー

キューは複数の非同期タスクの分散処理、コネクションプールやpub/subパターンの実装に適しています。

Queue

FIFO キューです。

PriorityQueue

優先度付きのキューです。

LifoQueue

LIFO キュー (スタック) です。

使用例

asyncio.Queue を使って複数のタスクを分散処理する.

Queue のドキュメント も参照してください。

サブプロセス

サブプロセスを生成したり、シェルコマンドを実行するためのユーティリティです。

await create_subprocess_exec()

サブプロセスを作成します。

await create_subprocess_shell()

シェルコマンドを実行します。

使用例

シェルコマンドを実行する。

サブプロセス API のドキュメントも参照してください。

ストリーム

ネットワーク IO を利用するための高水準の APIs です。

await open_connection()

TCP コネクションを確立します。

await open_unix_connection()

Unix のソケット接続を確立します。

await start_server()

TCP サーバーを起動します。

await start_unix_server()

Unix のソケットサーバーを起動します。

StreamReader

ネットワークからデータを受信するための高水準の async/await オブジェクトです。

StreamWriter

ネットワークにデータを送信するための高水準の async/await オブジェクトです。

使用例

TCPクライアントの例.

ストリーム API のドキュメントも参照してください。

同期

タスク内で利用できるスレッド並列処理に似た同期プリミティブです。

Lock

ミューテックスロックです。

Event

イベントオブジェクトです。

Condition

条件変数オブジェクトです。

Semaphore

セマフォ (semaphore) です。

BoundedSemaphore

有限セマフォ (bounded semaphore) です。

Barrier

A barrier object.

使用例

asyncio.Event の使用例 。

Using asyncio.Barrier.

asyncio の 同期プリミティブ についてのドキュメントも参照してください。

例外

asyncio.CancelledError

タスクがキャンセルされた場合に送出されます。 Task.cancel() も参照してください。

asyncio.BrokenBarrierError

Raised when a Barrier is broken. See also Barrier.wait().

使用例

CancelledError を処理してキャンセル要求に対応するコードを実行する.

asyncio に特有な例外の完全なリスト も参照してください。

低水準の API インデックス

このページでは低水準の asyncio API を全てリストしています。

イベントループの取得

asyncio.get_running_loop()

実行中のイベントループを取得するために 利用が推奨される 関数です。

asyncio.get_event_loop()

Get an event loop instance (running or current via the current policy).

asyncio.set_event_loop()

ポリシーに基づいて引数のイベントループを "カレント" (current event loop) に設定します。

asyncio.new_event_loop()

新しいイベントループのインスタンスを生成します。

使用例

asyncio.get_running_loop() を使う。

イベントループのメソッド

See also the main documentation section about the イベントループのメソッド.

ライフサイクル

loop.run_until_complete()

Future/Task/awaitable が完了するまで実行します。

loop.run_forever()

イベントループを永久に実行します。

loop.stop()

イベントループを停止します。

loop.close()

イベントループをクローズします。

loop.is_running()

イベントループが実行中の場合 True を返します。

loop.is_closed()

イベントループがクローズされている場合 True を返します。

await loop.shutdown_asyncgens()

非同期ジェネレータをクローズします。

デバッグ

loop.set_debug()

デバッグモードを有効化または無効化します。

loop.get_debug()

現在のデバッグモードを取得します。

コールバックのスケジューリング

loop.call_soon()

コールバックを即座に実行します。

loop.call_soon_threadsafe()

loop.call_soon() のスレッドセーフ版です。

loop.call_later()

与えられた遅延時間の 経過後 にコールバックを実行します。

loop.call_at()

与えられた時刻に コールバックを実行します。

スレッドプール／プロセスプール

await loop.run_in_executor()

CPUバウンドなブロッキング関数、またはその他のブロッキング関数を concurrent.futures 実行オブジェクト (executor) 上で実行します。

loop.set_default_executor()

loop.run_in_executor() のデフォルト実行オブジェクト (executor) を設定します。

タスクとフューチャー

loop.create_future()

Future オブジェクトを生成します。

loop.create_task()

コルーチンを Task としてスケジュールします。

loop.set_task_factory()

loop.create_task() が Tasks を生成する際に使われるファクトリを設定します。

loop.get_task_factory()

loop.create_task() が Tasks を生成するファクトリを取得します。

DNS

await loop.getaddrinfo()

socket.getaddrinfo() の非同期版です。

await loop.getnameinfo()

socket.getnameinfo() の非同期版です。

ネットワークとプロセス間通信 (IPC)

await loop.create_connection()

TCP接続を確立します。

await loop.create_server()

TCPサーバーを起動します。

await loop.create_unix_connection()

Unix のソケット接続を確立します。

await loop.create_unix_server()

Create a Unix socket server.

await loop.connect_accepted_socket()

socket を (transport, protocol) のペアでラップします。

await loop.create_datagram_endpoint()

データグラム (UDP) 接続を確立します。

await loop.sendfile()

確立した接続 (transport) を通じてファイルを送信します。

await loop.start_tls()

既存の接続を TLS にアップグレードします。

await loop.connect_read_pipe()

パイプの読み出し側を (transport, protocol) のペアでラップします。

await loop.connect_write_pipe()

パイプの書き込み側を (transport, protocol) のペアでラップします。

ソケット

await loop.sock_recv()

socket からデータを受信します。

await loop.sock_recv_into()

socket からデータを受信し、バッファに送信します。

await loop.sock_recvfrom()

Receive a datagram from the socket.

await loop.sock_recvfrom_into()

Receive a datagram from the socket into a buffer.

await loop.sock_sendall()

socket にデータを送信します。

await loop.sock_sendto()

Send a datagram via the socket to the given address.

await loop.sock_connect()

socket を接続します。

await loop.sock_accept()

socket の接続を受け入れます。

await loop.sock_sendfile()

Send a file over the socket.

loop.add_reader()

ファイル記述子が読み込み可能かどうかの監視を開始します。

loop.remove_reader()

ファイル記述子が読み込み可能かどうかの監視を停止します。

loop.add_writer()

ファイル記述子が書き込み可能かどうかの監視を開始します。

loop.remove_writer()

ファイル記述子が書き込み可能かどうかの監視を停止します。

Unix シグナル

loop.add_signal_handler()

signal 用のハンドラーを追加します。

loop.remove_signal_handler()

signal 用のハンドラーを削除します。

サブプロセス

loop.subprocess_exec()

サブプロセスを生成します。

loop.subprocess_shell()

シェルコマンドからサブプロセスを生成します。

エラー処理

loop.call_exception_handler()

例外ハンドラを呼び出します。

loop.set_exception_handler()

新しい例外ハンドラーを設定します。

loop.get_exception_handler()

現在の例外ハンドラーを取得します。

loop.default_exception_handler()

デフォルトの例外ハンドラー実装です。

使用例

Using asyncio.new_event_loop() and loop.run_forever().

loop.call_later() を使う。

loop.create_connection() を使って an echo-client を実装する。

loop.create_connection() を使って ソケットに接続する。

add_reader() を使ってファイルデスクリプタの読み込みイベントを監視する。

loop.add_signal_handler() を使う。

loop.subprocess_exec() を使う。

トランスポート

全てのトランスポートは以下のメソッドを実装します:

transport.close()

トランスポートをクローズします。

transport.is_closing()

トランスポートを閉じている最中か閉じていた場合 True を返します。

transport.get_extra_info()

トランスポートについての情報をリクエストします。

transport.set_protocol()

トランスポートに新しいプロトコルを設定します。

transport.get_protocol()

現在のプロトコルを返します。

データを受信できるトランスポート (TCP 接続、 Unix 接続、パイプなど) のメソッドです。該当するトランスポートは loop.create_connection(), loop.create_unix_connection(), loop.connect_read_pipe() などの戻り値です:

読み込みトランスポート

transport.is_reading()

トランスポートがデータを受信中の場合 True を返します。

transport.pause_reading()

データの受信を停止します。

transport.resume_reading()

データの受信を再開します。

データを送信できるトランスポート (TCP 接続、 Unix 接続、パイプなど) のメソッドです。該当するトランスポートは loop.create_connection(), loop.create_unix_connection(), loop.connect_write_pipe() などの戻り値です:

トランスポートにデータを書き込みます。

transport.write()

トランスポートにデータを書き込みます。

transport.writelines()

トランスポートにバッファの内容を書き込みます。

transport.can_write_eof()

トランスポートが 終端 (EOF) の送信をサポートしている場合 True を返します。

transport.write_eof()

バッファに残っているデータをフラッシュしてから終端 (EOF) を送信して、トランスポートをクローズします。

transport.abort()

トランスポートを即座にクローズします。

transport.get_write_buffer_size()

Return the current size of the output buffer.

transport.get_write_buffer_limits()

書き込みフロー制御の高水位点と低水位点を取得します。

transport.set_write_buffer_limits()

書き込みフロー制御の高水位点と低水位点を設定します。

loop.create_datagram_endpoint() が返すトランスポート:

データグラムトランスポート

transport.sendto()

リモートピアにデータを送信します。

transport.abort()

トランスポートを即座にクローズします。

サブプロセスに対するトランスポートの低レベルな抽象化です。 loop.subprocess_exec() や loop.subprocess_shell() の戻り値です:

サブプロセス化されたトランスポート

transport.get_pid()

サブプロセスのプロセス ID を返します。

transport.get_pipe_transport()

リクエストされた通信パイプ (標準入力 stdin, 標準出力 stdout, または標準エラー出力 stderr) のためのトランスポートを返します。

transport.get_returncode()

サブプロセスの終了ステータスを返します。

transport.kill()

サブプロセスを強制終了 (kill) します。

transport.send_signal()

サブプロセスにシグナルを送信します。

transport.terminate()

サブプロセスを停止します。

transport.close()

サブプロセスを強制終了 (kill) し、全てのパイプをクローズします。

プロトコル

プロトコルクラスは以下の コールバックメソッド を実装することができます:

callback connection_made()

コネクションが作成されたときに呼び出されます。

callback connection_lost()

コネクションが失われた、あるいはクローズされたときに呼び出されます。

callback pause_writing()

トランスポートのバッファーサイズが最高水位点 (High-Water Mark) を超えたときに呼び出されます。

callback resume_writing()

トランスポートのバッファーサイズが最低水位点 (Low-Water Mark) に達したきに呼び出されます。

ストリーミングプロトコル (TCP, Unix ソケット, パイプ)

callback data_received()

データを受信したときに呼び出されます。

callback eof_received()

終端 (EOF) を受信したときに呼び出されます。

バッファリングされたストリーミングプロトコル

callback get_buffer()

新しい受信バッファを割り当てるために呼び出します。

callback buffer_updated()

受信データによりバッファが更新された場合に呼び出されます。

callback eof_received()

終端 (EOF) を受信したときに呼び出されます。

データグラムプロトコル

callback datagram_received()

データグラムを受信したときに呼び出されます。

callback error_received()

直前の送信あるいは受信が OSError を送出したときに呼び出されます。

サブプロセスプロトコル

callback pipe_data_received()

子プロセスが標準出力 (stdout) または標準エラー出力 (stderr) のパイプにデータを書き込んだときに呼び出されます。

callback pipe_connection_lost()

子プロセスと通信するパイプのいずれかがクローズされたときに呼び出されます。

callback process_exited()

Called when the child process has exited. It can be called before pipe_data_received() and pipe_connection_lost() methods.

イベントループのポリシー

ポリシーは asyncio.get_event_loop() などの関数の振る舞いを変更する低レベルなメカニズムです。詳細は ポリシーについてのセクション を参照してください。

ポリシーへのアクセス

asyncio.get_event_loop_policy()

プロセス全体にわたる現在のポリシーを返します。

asyncio.set_event_loop_policy()

新たなプロセス全体にわたるポリシーを設定します。

AbstractEventLoopPolicy

ポリシーオブジェクトの基底クラスです。

asyncio での開発

非同期プログラミングは伝統的な "同期的" プログラミングとは異なります。

このページはよくある間違いや落とし穴を列挙し、それらを回避する方法を説明します。

デバッグモード

asyncio はデフォルトで本運用モードで実行されます。いっぽう、開発を容易にするために asyncio は "デバッグモード" を持っています。

asyncio のデバッグモードを有効化する方法はいくつかあります:

PYTHONASYNCIODEBUG 環境変数の値を 1 に設定する。

Python 開発モード を使う。

asyncio.run() 実行時に debug=True を設定する。

loop.set_debug() を呼び出す。

デバッグモードを有効化することに加え、以下も検討してください:

setting the log level of the asyncio logger to logging.DEBUG, for example the following snippet of code can be run at startup of the application:

logging.basicConfig(level=logging.DEBUG)

warnings モジュールが ResourceWarning 警告を表示するように設定します。やり方のひとつは -W default コマンドラインオプションを使うことです。

デバッグモードが有効化されたときの動作:

asyncio は 待ち受け処理 (await) を伴わないコルーチン がないかをチェックし、それらを記録します; これにより "待ち受け忘れ" の落とし穴にはまる可能性を軽減します。

スレッドセーフでない asyncio APIs の多く (loop.call_soon() や loop.call_at() など) は、誤ったスレッドから呼び出されたときに例外を送出します。

I/O セレクタが I/O 処理を実行する時間が長すぎる場合、その実行時間が記録されます。

Callbacks taking longer than 100 milliseconds are logged. The loop.slow_callback_duration attribute can be used to set the minimum execution duration in seconds that is considered "slow".

並行処理とマルチスレッド処理

イベントループはスレッド（典型的にはメインスレッド）内で動作し、すべてのコールバックとタスクをそのスレッド内で実行します。ひとつのタスクがイベントループ内で実行される間、他のタスクを同じスレッド内で実行することはできません。タスクが await 式を実行すると、実行中のタスクはサスペンドされ、イベントループは次のタスクを実行します。

別の OS スレッドからのコールバック (callback) をスケジュールする場合、 loop.call_soon_threadsafe() メソッドを使ってください。例:

loop.call_soon_threadsafe(callback, *args)

ほぼ全ての非同期オブジェクトはスレッドセーフではありませんが、タスクやコールバックの外側で非同期オブジェクトを使うコードが存在しない限り、それが問題にはなることはほとんどありません。もしそのような目的で低レベルの asyncio API を呼び出すようなコードを書く必要がある場合、 loop.call_soon_threadsafe() メソッドを使ってください。例:

loop.call_soon_threadsafe(fut.cancel)

別の OS スレッドからコルーチンオブジェクトをスケジュールする場合は、 run_coroutine_threadsafe() メソッドを使ってください。 run_coroutine_threadsafe() は結果にアクセスするための concurrent.futures.Future オブジェクトを返します:

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()

To handle signals the event loop must be run in the main thread.

The loop.run_in_executor() メソッドを concurrent.futures.ThreadPoolExecutor とともに使用することで、イベントループの OS スレッドをブロックすることなく、別の OS スレッド内でブロッキングコードを実行することができます。

There is currently no way to schedule coroutines or callbacks directly from a different process (such as one started with multiprocessing). The イベントループのメソッド section lists APIs that can read from pipes and watch file descriptors without blocking the event loop. In addition, asyncio's Subprocess APIs provide a way to start a process and communicate with it from the event loop. Lastly, the aforementioned loop.run_in_executor() method can also be used with a concurrent.futures.ProcessPoolExecutor to execute code in a different process.

ブロッキングコードの実行

ブロッキングコード (CPU バウンドなコード) を直接呼び出すべきではありません。たとえば、 CPU 負荷の高い関数を1秒実行したとすると、並行に処理されている全ての非同期タスクと I/O 処理は1秒遅れる可能性があります。

エグゼキューターを使用することにより、イベントループの OS スレッドをブロックすることなく、別のスレッドや別のプロセス上でタスクを実行することができます。詳しくは loop.run_in_executor() メソッドを参照してください。

ログ記録

asyncio は logging モジュールを利用し、 全てのログ記録は "asyncio" ロガーを通じて行われます。

The default log level is logging.INFO, which can be easily adjusted:

logging.getLogger("asyncio").setLevel(logging.WARNING)

Network logging can block the event loop. It is recommended to use a separate thread for handling logs or use non-blocking IO. For example, see ブロックする handler を扱う.

待ち受け処理を伴わないコルーチンの検出

コルーチンが呼び出されただけで、待ち受け処理がない場合 (たとえば await coro() のかわりに coro() と書いてしまった場合) 、またはコルーチンが asyncio.create_task() を使わずにスケジュールされた場合、 asyncio は RuntimeWarning 警告を送出します:

import asyncio

async def test():
    print("never scheduled")

async def main():
    test()

asyncio.run(main())

出力:

test.py:7: RuntimeWarning: coroutine 'test' was never awaited
  test()

デバッグモードの出力:

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()

通常の修正方法はコルーチンを待ち受ける (await) か、 asyncio.create_task() 関数を呼び出すことです:

async def main():
    await test()

回収されない例外の検出

もし Future.set_exception() メソッドが呼び出されても、その Future オブジェクトを待ち受けていなければ、例外は決してユーザーコードまで伝播しません。この場合 asyncio は、 Future オブジェクトがガベージコレクションの対象となったときにログメッセージを送出することがあります。

処理されない例外の例:

import asyncio

async def bug():
    raise Exception("not consumed")

async def main():
    asyncio.create_task(bug())

asyncio.run(main())

出力:

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

タスクが生成された箇所を特定するには、 デバッグモードを有効化して トレースバックを取得してください:

asyncio.run(main(), debug=True)

デバッグモードの出力:

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

socket --- Low-level networking interface

ソースコード: Lib/socket.py [https://github.com/python/cpython/tree/3.12/Lib/socket.py]

このモジュールはBSDの ソケット(socket) インターフェイスへのアクセスを提供します。これは、近代的なUnixシステム、Windows、MacOS、その他多くのプラットフォームで動作します。

注釈

いくつかの挙動はプラットフォームに依存します。オペレーティングシステムのソケットAPIを呼び出しているためです。

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. See WebAssemblyプラットフォーム for more information.

The Python interface is a straightforward transliteration of the Unix system call and library interface for sockets to Python's object-oriented style: the socket() function returns a socket object whose methods implement the various socket system calls. Parameter types are somewhat higher-level than in the C interface: as with read() and write() operations on Python files, buffer allocation on receive operations is automatic, and buffer length is implicit on send operations.

参考

Module socketserver

ネットワークサーバの開発を省力化するためのクラス群。

Module ssl

ソケットオブジェクトに対する TLS/SSL ラッパー.

ソケットファミリー

どのシステムで実行するかとビルドオプションに依存しますが、このモジュールによって多様なソケットファミリーをサポートします。

特定のソケットオブジェクトによって必要とされるアドレスフォーマットは、ソケットオブジェクトが生成されたときに指定されたアドレスファミリーを元に自動的に選択されます。ソケットアドレスは次の通りです。

ファイルシステム上のノードに束縛された AF_UNIX ソケットのアドレスは、ファイルシステムエンコーディングと 'surrogateescape' エラーハンドラ (PEP 383 [https://peps.python.org/pep-0383/] を参照) を使って文字列として表現されます。 Linux の抽象名前空間のアドレスは、先頭が null バイトとなる bytes-like object として返されます。この名前空間のソケットは通常のファイルシステム上のソケットと通信できるので、 Linux 上で動作することを意図したプログラムは両方のアドレスを扱う必要がある可能性があります。文字列と bytes-like オブジェクトはどちらのタイプのアドレスにも引数として渡すことができます。

バージョン 3.3 で変更: これまでは AF_UNIX ソケットパスは UTF-8 エンコーディングを使用するものとされていました。

バージョン 3.5 で変更: 書き込み可能な bytes-like object を使用できるようになりました。

AF_INET アドレスファミリーには、 (host, port) ペアがアドレスとして利用されます。 host はホスト名か 'daring.cwi.nl' のようなインターネットドメインか、 '100.50.200.5' のような IPv4 アドレスで、 port は整数です。

IPv4ではホストアドレスのほかに2つの特別な形式が使用できます。''``はすべてのインターフェイスにバインドされるために使われる:const:`INADDR_ANY`を表し、'<broadcast>'``は:const:`INADDR_BROADCAST`を表します。これらの動作はIPv6と互換性がありません。そのためもしもあなたがPythonプログラムでIPv6をサポートする予定があるのならばこれらを避けたほうが良いでしょう。

AF_INET6 アドレスファミリーでは、 (host, port, flowinfo, scope_id) の4 要素のタプルが利用されます。 flowinfo と scopeid はそれぞれC言語の struct sockaddr_in6 の sin6_flowinfo と sin6_scope_id メンバーを表します。 socket モジュールのメソッドでは、後方互換性のために flowinfo と scope_id の省略を許しています。しかし、 scope_id を省略すると scope された IPv6 アドレスを操作するときに問題が起こる場合があることに注意してください。

バージョン 3.7 で変更: For multicast addresses (with scope_id meaningful) address may not contain %scope_id (or zone id) part. This information is superfluous and may be safely omitted (recommended).

AF_NETLINK ソケットのアドレスは (pid, groups) のペアで表されます。

Linux 限定で、 AF_TIPC アドレスファミリーを用いて TIPC がサポートされます。 TIPC は、クラスタコンピューティング環境のために設計された、IP ベースではないオープンなネットワークプロトコルです。アドレスはタプルで表現され、フィールドはアドレスタイプに依存します。一般的なタプルの形式は (addr_type, v1, v2, v3 [, scope]) で、それぞれは次の通りです:

addr_type は TIPC_ADDR_NAMESEQ, TIPC_ADDR_NAME, TIPC_ADDR_ID の1つ。

scope は TIPC_ZONE_SCOPE, TIPC_CLUSTER_SCOPE, TIPC_NODE_SCOPE の1つ。

addr_type が TIPC_ADDR_NAME の場合、 v1 はサーバータイプ、 v2 はポートID (the port identifier)、そして v3 は 0 であるべきです。

addr_type が TIPC_ADDR_NAMESEQ の場合、 v1 はサーバータイプ、 v2 はポート番号下位(lower port number)、 v3 はポート番号上位(upper port number) です。

addr_type が TIPC_ADDR_ID の場合、 v1 はノード、 v2 は参照、 v3 は0であるべきです。

AF_CAN アドレスファミリーには (interface, ) というタプルを利用します。 interface は 'can0' のようなネットワークインターフェース名を表す文字列です。このファミリーの全てのネットワークインターフェースからパケットを受信するために、ネットワークインターフェース名 '' を利用できます。

CAN_ISOTP protocol require a tuple (interface, rx_addr, tx_addr) where both additional parameters are unsigned long integer that represent a CAN identifier (standard or extended).

CAN_J1939 protocol require a tuple (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.

文字列またはタプル (id, unit) は PF_SYSTEM ファミリーの SYSPROTO_CONTROL プロトコルのために使用されます。この文字列は、動的に割り当てられたIDによるカーネルコントロールの名前です。このタプルは、カーネルコントロールのIDとユニット番号が既知の場合、または登録済みIDが使用中の場合に使用することができます。

Added in version 3.3.

AF_BLUETOOTH は以下のプロトコルとアドレスフォーマットをサポートしています。

BTPROTO_L2CAP は (bdaddr, psm) を受け取ります。 bdaddr は Bluetooth アドレスを表す文字列で、 psm は整数です。

BTPROTO_RFCOMM は (bdaddr, channel) を受け取ります。 bdaddr は Bluetooth アドレスを表す文字列で、 channel は整数です。

BTPROTO_HCI は (device_id,) を受け取ります。 device_id は、数値またはインターフェイスの Bluetooth アドレスを表す文字列です。(OS に依存します。NetBSD と DragonFlyBSD は Bluetooth アドレスを期待しますが、その他すべての OS は、数値を期待します。)

バージョン 3.2 で変更: NetBSD と DragonFlyBSD のサポートが追加されました。

BTPROTO_SCO は bdaddr を受け取ります。ここで、 bdaddr は Bluetooth アドレスを文字列形式で持つ bytes オブジェクトです (例: b'12:23:34:45:56:67')。このプロトコルは、 FreeBSD ではサポートされていません。

AF_ALG はカーネル暗号へのソケットベースのインターフェイスで、Linux でのみ使用できます。アルゴリズムソケットは、2 つから 4 つの要素を持つタプル (type, name [, feat [, mask]]) で構成されます。各要素の意味は、以下の通りです。

type はアルゴリズムタイプを示す文字列です。例: aead, hash, skcipher または rng。

name はアルゴリズム名及び操作モードを示す文字列です。例: sha256, hmac(sha256), cbc(aes) または drbg_nopr_ctr_aes256。

feat と mask は、符号を持たない 32 ビットの整数です。

利用可能な環境: Linux 2.6.38以上。

一部のアルゴリズムタイプでは、さらに新しいカーネルが必要です。

Added in version 3.6.

AF_VSOCK allows communication between virtual machines and their hosts. The sockets are represented as a (CID, port) tuple where the context ID or CID and port are integers.

利用可能な環境: Linux 3.9以上。

See vsock(7) [https://manpages.debian.org/vsock(7)]

Added in version 3.7.

AF_PACKET is a low-level interface directly to network devices. The addresses are represented by the tuple (ifname, proto[, pkttype[, hatype[, addr]]]) where:

ifname - デバイス名を指定する文字列。

proto - The Ethernet protocol number. May be ETH_P_ALL to capture all protocols, one of the ETHERTYPE_* constants or any other Ethernet protocol number.

pkttype - パケットタイプを指定するオプションの整数:

PACKET_HOST (the default) - Packet addressed to the local host.

PACKET_BROADCAST - Physical-layer broadcast packet.

PACKET_MULTICAST - Packet sent to a physical-layer multicast address.

PACKET_OTHERHOST - Packet to some other host that has been caught by a device driver in promiscuous mode.

PACKET_OUTGOING - Packet originating from the local host that is looped back to a packet socket.

hatype - Optional integer specifying the ARP hardware address type.

addr - Optional bytes-like object specifying the hardware physical address, whose interpretation depends on the device.

利用可能な環境: Linux 2.2以上。

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 (node, port) tuple where the node and port are non-negative integers.

利用可能な環境: Linux 4.7以上。

Added in version 3.8.

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. self.setsockopt(IPPROTO_UDPLITE, UDPLITE_SEND_CSCOV, length) will change what portion of outgoing packets are covered by the checksum and self.setsockopt(IPPROTO_UDPLITE, UDPLITE_RECV_CSCOV, length) will filter out packets which cover too little of their data. In both cases length should be in range(8, 2**16, 8).

Such a socket should be constructed with socket(AF_INET, SOCK_DGRAM, IPPROTO_UDPLITE) for IPv4 or socket(AF_INET6, SOCK_DGRAM, IPPROTO_UDPLITE) for IPv6.

Availability: Linux >= 2.6.20, FreeBSD >= 10.1

Added in version 3.9.

AF_HYPERV is a Windows-only socket based interface for communicating with Hyper-V hosts and guests. The address family is represented as a (vm_id, service_id) tuple where the vm_id and service_id are UUID strings.

The 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 socket are:

HV_GUID_ZERO

HV_GUID_BROADCAST

HV_GUID_WILDCARD - Used to bind on itself and accept connections from all partitions.

HV_GUID_CHILDREN - Used to bind on itself and accept connection from child partitions.

HV_GUID_LOOPBACK - Used as a target to itself.

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.

The service_id is the service identifier of the registered service.

Added in version 3.12.

IPv4/v6ソケットの host 部にホスト名を指定すると、処理結果が一定ではない場合があります。これはPythonはDNSから取得したアドレスのうち最初のアドレスを使用するので、 DNSの処理やホストの設定によって異なるIPv4/6アドレスを取得する場合があるためです。常に同じ結果が必要であれば、 host に数値のアドレスを指定してください。

エラー時には例外が発生します。引数型のエラーやメモリ不足の場合には通常の例外が発生し、ソケットやアドレス関連のエラーの場合は OSError またはそのサブクラスが発生します。

setblocking() メソッドで、非ブロッキングモードを使用することができます。また、より汎用的に settimeout() メソッドでタイムアウトを指定する事ができます。

モジュールの内容

socket モジュールは以下の要素を公開しています。

例外

exception socket.error

OSError の非推奨のエイリアスです。

バージョン 3.3 で変更: PEP 3151 [https://peps.python.org/pep-3151/] に基づき、このクラスは OSError のエイリアスになりました。

exception socket.herror

OSError のサブクラス。この例外はアドレス関連のエラー、つまり gethostbyname_ex() と gethostbyaddr() などの、 POSIX C API の h_errno を利用する関数のために利用されます。例外に付随する (h_errno, string) ペアはライブラリの呼び出しによって返されたエラーを表します。 h_errno は数値で、 string は、 hstrerror() C関数によって返される h_errno を説明する文字列です。

バージョン 3.3 で変更: このクラスは OSError のサブクラスになりました。

exception socket.gaierror

A subclass of OSError, this exception is raised for address-related errors by getaddrinfo() and getnameinfo(). The accompanying value is a pair (error, string) representing an error returned by a library call. string represents the description of error, as returned by the gai_strerror() C function. The numeric error value will match one of the EAI_* constants defined in this module.

バージョン 3.3 で変更: このクラスは OSError のサブクラスになりました。

exception socket.timeout

TimeoutError の非推奨のエイリアスです。

OSError のサブクラスです。この例外は、あらかじめ settimeout() を呼び出して (あるいは setdefaulttimeout() を利用して暗黙に) タイムアウトを有効にしてあるソケットでタイムアウトが生じた際に送出されます。 例外に付属する値は文字列で、その内容は現状では常に "timed out" となります。

バージョン 3.3 で変更: このクラスは OSError のサブクラスになりました。

バージョン 3.10 で変更: This class was made an alias of TimeoutError.

定数

AF_* 定数と SOCK_* 定数は、 AddressFamily と SocketKind IntEnum collection になりました。

Added in version 3.4.

socket.AF_UNIX

socket.AF_INET

socket.AF_INET6

These constants represent the address (and protocol) families, used for the first argument to socket(). If the AF_UNIX constant is not defined then this protocol is unsupported. More constants may be available depending on the system.

socket.AF_UNSPEC

AF_UNSPEC means that getaddrinfo() should return socket addresses for any address family (either IPv4, IPv6, or any other) that can be used.

socket.SOCK_STREAM

socket.SOCK_DGRAM

socket.SOCK_RAW

socket.SOCK_RDM

socket.SOCK_SEQPACKET

These constants represent the socket types, used for the second argument to socket(). More constants may be available depending on the system. (Only SOCK_STREAM and SOCK_DGRAM appear to be generally useful.)

socket.SOCK_CLOEXEC

socket.SOCK_NONBLOCK

この2つの定数が定義されていた場合、ソケットタイプと組み合わせていくつかの flags をアトミックに設定することができます (別の呼び出しを不要にして競合状態を避ける事ができます)。

参考

より完全な説明は Secure File Descriptor Handling [https://udrepper.livejournal.com/20407.html] を参照してください。

利用可能な環境: Linux 2.6.27以上。

Added in version 3.2.

SO_*

socket.SOMAXCONN

MSG_*

SOL_*

SCM_*

IPPROTO_*

IPPORT_*

INADDR_*

IP_*

IPV6_*

EAI_*

AI_*

NI_*

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 setsockopt() and 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 で変更: SO_DOMAIN, SO_PROTOCOL, SO_PEERSEC, SO_PASSSEC, TCP_USER_TIMEOUT, TCP_CONGESTION が追加されました。

バージョン 3.6.5 で変更: Windowsでは、実行時のWindowsがサポートしているならば TCP_FASTOPEN、 TCP_KEEPCNT が表示されます。

バージョン 3.7 で変更: TCP_NOTSENT_LOWAT が追加されました。

Windowsでは、実行時のWindowsがサポートしているならば TCP_KEEPIDLE, TCP_KEEPINTVL が表示されます。

バージョン 3.10 で変更: IP_RECVTOS was added. Added TCP_KEEPALIVE. On MacOS this constant can be used in the same way that TCP_KEEPIDLE is used on Linux.

バージョン 3.11 で変更: Added TCP_CONNECTION_INFO. On MacOS this constant can be used in the same way that TCP_INFO is used on Linux and BSD.

バージョン 3.12 で変更: Added SO_RTABLE and SO_USER_COOKIE. On OpenBSD and FreeBSD respectively those constants can be used in the same way that SO_MARK is used on Linux. Also added missing TCP socket options from Linux: TCP_MD5SIG, TCP_THIN_LINEAR_TIMEOUTS, TCP_THIN_DUPACK, TCP_REPAIR, TCP_REPAIR_QUEUE, TCP_QUEUE_SEQ, TCP_REPAIR_OPTIONS, TCP_TIMESTAMP, TCP_CC_INFO, TCP_SAVE_SYN, TCP_SAVED_SYN, TCP_REPAIR_WINDOW, TCP_FASTOPEN_CONNECT, TCP_ULP, TCP_MD5SIG_EXT, TCP_FASTOPEN_KEY, TCP_FASTOPEN_NO_COOKIE, TCP_ZEROCOPY_RECEIVE, TCP_INQ, TCP_TX_DELAY. Added IP_PKTINFO, IP_UNBLOCK_SOURCE, IP_BLOCK_SOURCE, IP_ADD_SOURCE_MEMBERSHIP, IP_DROP_SOURCE_MEMBERSHIP.

socket.AF_CAN

socket.PF_CAN

SOL_CAN_*

CAN_*

Linux ドキュメントにあるこの形式の定数は socket モジュールでも定義されています。

Availability: Linux >= 2.6.25, NetBSD >= 8.

Added in version 3.3.

バージョン 3.11 で変更: NetBSD サポートが追加されました。

socket.CAN_BCM

CAN_BCM_*

CANプロトコルファミリーのCAN_BCMは、ブロードキャストマネージャー(BCM)プロトコルです。Linuxドキュメントにあるこの形式の定数は、socketモジュールでも定義されています。

利用可能な環境: Linux 2.6.25以上。

注釈

The CAN_BCM_CAN_FD_FRAME flag is only available on Linux >= 4.8.

Added in version 3.4.

socket.CAN_RAW_FD_FRAMES

CAN_RAW ソケットで CAN FD をサポートします。これはデフォルトで無効になっています。これにより、アプリケーションが CAN フレームと CAN FD フレームを送信できるようになります。ただし、ソケットからの読み出し時に、CAN と CAN FD の両方のフレームを受け入れなければなりません。

この定数は、 Linux のドキュメンテーションで説明されています。

利用可能な環境: Linux 3.6以上。

Added in version 3.5.

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.

この定数は、 Linux のドキュメンテーションで説明されています。

利用可能な環境: Linux 4.1以上。

Added in version 3.9.

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.

利用可能な環境: Linux 2.6.25以上。

Added in version 3.7.

socket.CAN_J1939

CAN_J1939, in the CAN protocol family, is the SAE J1939 protocol. J1939 constants, documented in the Linux documentation.

利用可能な環境: Linux 5.4以上。

Added in version 3.9.

socket.AF_DIVERT

socket.PF_DIVERT

These two constants, documented in the FreeBSD divert(4) manual page, are also defined in the socket module.

Availability: FreeBSD >= 14.0.

Added in version 3.12.

socket.AF_PACKET

socket.PF_PACKET

PACKET_*

Linux ドキュメントにあるこの形式の定数は socket モジュールでも定義されています。

利用可能な環境: Linux 2.2以上。

socket.ETH_P_ALL

ETH_P_ALL can be used in the socket constructor as proto for the AF_PACKET family in order to capture every packet, regardless of protocol.

For more information, see the packet(7) [https://manpages.debian.org/packet(7)] manpage.

利用可能な環境: Linux。

Added in version 3.12.

socket.AF_RDS

socket.PF_RDS

socket.SOL_RDS

RDS_*

Linux ドキュメントにあるこの形式の定数は socket モジュールでも定義されています。

利用可能な環境: Linux 2.6.30以上。

Added in version 3.3.

socket.SIO_RCVALL

socket.SIO_KEEPALIVE_VALS

socket.SIO_LOOPBACK_FAST_PATH

RCVALL_*

Windows の WSAIoctl() のための定数です。この定数はソケットオブジェクトの ioctl() メソッドに引数として渡されます。

バージョン 3.6 で変更: SIO_LOOPBACK_FAST_PATH が追加されました。

TIPC_*

TIPC 関連の定数で、C のソケットAPIが公開しているものにマッチします。詳しい情報は TIPC のドキュメントを参照してください。

socket.AF_ALG

socket.SOL_ALG

ALG_*

Linux カーネル暗号用の定数です。

利用可能な環境: Linux 2.6.38以上。

Added in version 3.6.

socket.AF_VSOCK

socket.IOCTL_VM_SOCKETS_GET_LOCAL_CID

VMADDR*

SO_VM*

Constants for Linux host/guest communication.

利用可能な環境: Linux 4.8以上。

Added in version 3.7.

socket.AF_LINK

利用可能な環境: BSD, macOS。

Added in version 3.4.

socket.has_ipv6

現在のプラットフォームでIPv6がサポートされているか否かを示す真偽値。

socket.BDADDR_ANY

socket.BDADDR_LOCAL

これらは、特別な意味を持つ Bluetooth アドレスを含む文字列定数です。例えば、BDADDR_ANY を使用すると、 BTPROTO_RFCOMM で束縛ソケットを指定する際に、任意のアドレスを指し示すことができます。

socket.HCI_FILTER

socket.HCI_TIME_STAMP

socket.HCI_DATA_DIR

BTPROTO_HCI で使用します。 HCI_FILTER は NetBSD または DragonFlyBSD では使用できません。 HCI_TIME_STAMP と HCI_DATA_DIR は FreeBSD, NetBSD, DragonFlyBSD では使用できません。

socket.AF_QIPCRTR

Constant for Qualcomm's IPC router protocol, used to communicate with service providing remote processors.

利用可能な環境: Linux 4.7以上。

socket.SCM_CREDS2

socket.LOCAL_CREDS

socket.LOCAL_CREDS_PERSISTENT

LOCAL_CREDS and LOCAL_CREDS_PERSISTENT can be used with SOCK_DGRAM, SOCK_STREAM sockets, equivalent to Linux/DragonFlyBSD SO_PASSCRED, while LOCAL_CREDS sends the credentials at first read, LOCAL_CREDS_PERSISTENT sends for each read, SCM_CREDS2 must be then used for the latter for the message type.

Added in version 3.11.

利用可能な環境: FreeBSD。

socket.SO_INCOMING_CPU

Constant to optimize CPU locality, to be used in conjunction with SO_REUSEPORT.

Added in version 3.11.

利用可能な環境: Linux 3.9以上。

socket.AF_HYPERV

socket.HV_PROTOCOL_RAW

socket.HVSOCKET_CONNECT_TIMEOUT

socket.HVSOCKET_CONNECT_TIMEOUT_MAX

socket.HVSOCKET_CONNECTED_SUSPEND

socket.HVSOCKET_ADDRESS_FLAG_PASSTHRU

socket.HV_GUID_ZERO

socket.HV_GUID_WILDCARD

socket.HV_GUID_BROADCAST

socket.HV_GUID_CHILDREN

socket.HV_GUID_LOOPBACK

socket.HV_GUID_PARENT

Constants for Windows Hyper-V sockets for host/guest communications.

利用可能な環境: Windows 。

Added in version 3.12.

socket.ETHERTYPE_ARP

socket.ETHERTYPE_IP

socket.ETHERTYPE_IPV6

socket.ETHERTYPE_VLAN

IEEE 802.3 protocol number [https://www.iana.org/assignments/ieee-802-numbers/ieee-802-numbers.txt]. constants.

Availability: Linux, FreeBSD, macOS.

Added in version 3.12.

関数

ソケットの作成

以下の関数は全て socket object を生成します。

class socket.socket(family=AF_INET, type=SOCK_STREAM, proto=0, fileno=None)

アドレスファミリー、ソケットタイプ、プロトコル番号を指定してソケットを作成します。アドレスファミリーには AF_INET (デフォルト値), AF_INET6, AF_UNIX, AF_CAN, AF_PACKET, AF_RDS を指定することができます。ソケットタイプには SOCK_STREAM (デフォルト値), SOCK_DGRAM, SOCK_RAW または他の SOCK_ 定数の何れかを指定します。プロトコル番号は通常省略するか、または0を指定しますが、アドレスファミリーに AF_CAN を指定した場合は、プロトコル番号には const:CAN_RAW, CAN_BCM, CAN_ISOTP, 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 socket.getpeername() but not the actual OS resource. Unlike socket.fromfd(), fileno will return the same socket and not a duplicate. This may help close a detached socket using socket.close().

新たに作成されたソケットは 継承不可 です。

引数 self, family, type, protocol 付きで 監査イベント socket.__new__ を送出します。

バージョン 3.3 で変更: AF_CAN, AF_RDS ファミリーが追加されました。

バージョン 3.4 で変更: CAN_BCMプロトコルが追加されました。

バージョン 3.4 で変更: 返されるソケットは継承不可になりました。

バージョン 3.7 で変更: CAN_ISOTP プロトコルが追加されました。

バージョン 3.7 で変更: When SOCK_NONBLOCK or SOCK_CLOEXEC bit flags are applied to type they are cleared, and socket.type will not reflect them. They are still passed to the underlying system socket() call. Therefore,

sock = socket.socket(
    socket.AF_INET,
    socket.SOCK_STREAM | socket.SOCK_NONBLOCK)

will still create a non-blocking socket on OSes that support SOCK_NONBLOCK, but sock.type will be set to socket.SOCK_STREAM.

バージョン 3.9 で変更: CAN_J1939 プロトコルが追加されました。

バージョン 3.10 で変更: IPPROTO_MPTCP プロトコルが追加されました。

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 socket() function above. The default family is AF_UNIX if defined on the platform; otherwise, the default is AF_INET.

新たに作成されたソケットは 継承不可 です。

バージョン 3.2 で変更: 返されるソケットオブジェクトが、サブセットではなく完全なソケットAPIを提供するようになりました。

バージョン 3.4 で変更: 返されるソケットの組は、どちらも継承不可になりました。

バージョン 3.5 で変更: Windows のサポートが追加されました。

socket.create_connection(address, timeout=GLOBAL_DEFAULT, source_address=None, *, all_errors=False)

インターネット address ((host, port) ペア) で listen しているTCPサービスに接続し、ソケットオブジェクトを返します。これは socket.connect() を高級にした関数です。 host が数値でないホスト名の場合、 AF_INET と AF_INET6 の両方で名前解決を試み、得られた全てのアドレスに対して成功するまで接続を試みます。この関数を使って IPv4 と IPv6 に両対応したクライアントを簡単に書くことができます。

オプションの timeout 引数を指定すると、接続を試みる前にソケットオブジェクトのタイムアウトを設定します。 timeout が指定されない場合、 getdefaulttimeout() が返すデフォルトのタイムアウト設定値を利用します。

source_address は接続する前にバインドするソースアドレスを指定するオプション引数で、指定する場合は (host, port) の2要素タプルでなければなりません。 host や port が '' か 0 だった場合は、OSのデフォルトの動作になります。

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 True, it is an ExceptionGroup containing the errors of all attempts.

バージョン 3.2 で変更: source_address が追加されました。

バージョン 3.11 で変更: all_errors が追加されました

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 (host, port)) and returns the socket object.

family should be either AF_INET or AF_INET6. backlog is the queue size passed to socket.listen(); if not specified , a default reasonable value is chosen. reuse_port dictates whether to set the SO_REUSEPORT socket option.

If dualstack_ipv6 is true and the platform supports it the socket will be able to accept both IPv4 and IPv6 connections, else it will raise ValueError. Most POSIX platforms and Windows are supposed to support this functionality. When this functionality is enabled the address returned by 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 has_dualstack_ipv6():

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)

注釈

On POSIX platforms the 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.

Added in version 3.8.

socket.has_dualstack_ipv6()

Return True if the platform supports creating a TCP socket which can handle both IPv4 and IPv6 connections.

Added in version 3.8.

socket.fromfd(fd, family, type, proto=0)

Duplicate the file descriptor fd (an integer as returned by a file object's fileno() method) and build a socket object from the result. Address family, socket type and protocol number are as for the 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.

新たに作成されたソケットは 継承不可 です。

バージョン 3.4 で変更: 返されるソケットは継承不可になりました。

socket.fromshare(data)

socket.share() メソッドから取得した data からソケットオブジェクトを生成します。ソケットはブロッキングモードだと仮定されます。

利用可能な環境: Windows 。

Added in version 3.3.

socket.SocketType

ソケットオブジェクトの型を示す型オブジェクト。 type(socket(...)) と同じです。

その他の関数

socket モジュールはネットワーク関連のサービスを提供しています:

socket.close(fd)

Close a socket file descriptor. This is like os.close(), but for sockets. On some platforms (most noticeable Windows) os.close() does not work for socket file descriptors.

Added in version 3.7.

socket.getaddrinfo(host, port, family=0, type=0, proto=0, flags=0)

host / port 引数の指すアドレス情報を、そのサービスに接続されたソケットを作成するために必要な全ての引数が入った 5 要素のタプルに変換します。 host はドメイン名、IPv4/v6アドレスの文字列、または None です。 port は 'http' のようなサービス名文字列、ポート番号を表す数値、または None です。 host と port に None を指定すると C APIに NULL を渡せます。

オプションの family, type, proto 引数を指定すると、返されるアドレスのリストを絞り込むことができます。これらの引数の値として 0 を渡すと絞り込まない結果を返します。 flags 引数には AI_* 定数のうち 1 つ以上が指定でき、結果の取り方を変えることができます。例えば、 AI_NUMERICHOST を指定するとドメイン名解決を行わないようにし、 host がドメイン名だった場合には例外を送出します。

この関数は以下の構造をとる 5 要素のタプルのリストを返します:

(family, type, proto, canonname, sockaddr)

In these tuples, family, type, proto are all integers and are meant to be passed to the socket() function. canonname will be a string representing the canonical name of the host if 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 (address, port) 2-tuple for AF_INET, a (address, port, flowinfo, scope_id) 4-tuple for AF_INET6), and is meant to be passed to the socket.connect() method.

引数 host, port, family, type, protocol 付きで 監査イベント socket.getaddrinfo を送出します。

次の例では example.org の 80 番ポートポートへの TCP 接続を得るためのアドレス情報を取得しようとしています。 (結果は IPv6 をサポートしているかどうかで変わります):

>>> socket.getaddrinfo("example.org", 80, proto=socket.IPPROTO_TCP)
[(socket.AF_INET6, socket.SOCK_STREAM,
 6, '', ('2606:2800:220:1:248:1893:25c8:1946', 80, 0, 0)),
 (socket.AF_INET, socket.SOCK_STREAM,
 6, '', ('93.184.216.34', 80))]

バージョン 3.2 で変更: パラメータをキーワード引数で渡すことができるようになりました。

バージョン 3.7 で変更: for IPv6 multicast addresses, string representing an address will not contain %scope_id part.

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 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 '0.0.0.0', the hostname from gethostname() is returned.

socket.gethostbyname(hostname)

ホスト名を '100.50.200.5' のようなIPv4形式のアドレスに変換します。ホスト名としてIPv4アドレスを指定した場合、その値は変換せずにそのまま返ります。 gethostbyname() APIへのより完全なインターフェイスが必要であれば、 gethostbyname_ex() を参照してください。 gethostbyname() は、IPv6名前解決をサポートしていません。IPv4/ v6のデュアルスタックをサポートする場合は getaddrinfo() を使用します。

引数 hostname を指定して 監査イベント socket.gethostbyname を送出します。

Availability: not WASI.

socket.gethostbyname_ex(hostname)

Translate a host name to IPv4 address format, extended interface. Return a 3-tuple (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). gethostbyname_ex() does not support IPv6 name resolution, and getaddrinfo() should be used instead for IPv4/v6 dual stack support.

引数 hostname を指定して 監査イベント socket.gethostbyname を送出します。

Availability: not WASI.

socket.gethostname()

Pythonインタープリタを現在実行しているマシンのホスト名を含む文字列を返します。

引数無しで 監査イベント socket.gethostname を送出します。

注意: gethostname() は完全修飾ドメイン名を返すとは限りません。完全修飾ドメイン名が必要であれば、getfqdn() を使用してください。

Availability: not WASI.

socket.gethostbyaddr(ip_address)

Return a 3-tuple (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 getfqdn(). gethostbyaddr() supports both IPv4 and IPv6.

引数 ip_address を指定して 監査イベント socket.gethostbyaddr を送出します。

Availability: not WASI.

socket.getnameinfo(sockaddr, flags)

Translate a socket address sockaddr into a 2-tuple (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, %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 getnameinfo(3) [https://manpages.debian.org/getnameinfo(3)].

引数 sockaddr を指定して 監査イベント socket.getnameinfo を送出します。

Availability: not WASI.

socket.getprotobyname(protocolname)

Translate an internet protocol name (for example, 'icmp') to a constant suitable for passing as the (optional) third argument to the socket() function. This is usually only needed for sockets opened in "raw" mode (SOCK_RAW); for the normal socket modes, the correct protocol is chosen automatically if the protocol is omitted or zero.

Availability: not WASI.

socket.getservbyname(servicename[, protocolname])

インターネットサービス名とプロトコルから、そのサービスのポート番号を取得します。省略可能なプロトコル名として、 'tcp' か 'udp' のどちらかを指定することができます。指定がなければどちらのプロトコルにもマッチします。

引数 servicename, protocolname を指定して 監査イベント socket.getservbyname を送出します。

Availability: not WASI.

socket.getservbyport(port[, protocolname])

インターネットポート番号とプロトコル名から、サービス名を取得します。省略可能なプロトコル名として、 'tcp' か 'udp' のどちらかを指定することができます。指定がなければどちらのプロトコルにもマッチします。

引数 port, protocolname を指定して 監査イベント socket.getservbyport を送出します。

Availability: not WASI.

socket.ntohl(x)

32ビットの正の整数のバイトオーダを、ネットワークバイトオーダからホストバイトオーダに変換します。ホストバイトオーダとネットワークバイトオーダが一致するマシンでは、この関数は何もしません。それ以外の場合は4バイトのスワップを行います。

socket.ntohs(x)

16ビットの正の整数のバイトオーダを、ネットワークバイトオーダからホストバイトオーダに変換します。ホストバイトオーダとネットワークバイトオーダが一致するマシンでは、この関数は何もしません。それ以外の場合は2バイトのスワップを行います。

バージョン 3.10 で変更: Raises OverflowError if x does not fit in a 16-bit unsigned integer.

socket.htonl(x)

32ビットの正の整数のバイトオーダを、ホストバイトオーダからネットワークバイトオーダに変換します。ホストバイトオーダとネットワークバイトオーダが一致するマシンでは、この関数は何もしません。それ以外の場合は4バイトのスワップを行います。

socket.htons(x)

16ビットの正の整数のバイトオーダを、ホストバイトオーダからネットワークバイトオーダに変換します。ホストバイトオーダとネットワークバイトオーダが一致するマシンでは、この関数は何もしません。それ以外の場合は2バイトのスワップを行います。

バージョン 3.10 で変更: Raises OverflowError if x does not fit in a 16-bit unsigned integer.

socket.inet_aton(ip_string)

ドット記法によるIPv4アドレス('123.45.67.89' など)を32ビットにパックしたバイナリ形式に変換し、長さ4のバイト列オブジェクトとして返します。この関数が返す値は、標準Cライブラリの in_addr 型を使用する関数に渡す事ができます。

inet_aton() はドットが 3 個以下の文字列も受け取ります; 詳細については Unix のマニュアル inet(3) [https://manpages.debian.org/inet(3)] を参照してください。

IPv4アドレス文字列が不正であれば、 OSError が発生します。このチェックは、この関数で使用しているCの実装 inet_aton() で行われます。

inet_aton() は、IPv6をサポートしません。IPv4/v6のデュアルスタックをサポートする場合は inet_pton() を使用します。

socket.inet_ntoa(packed_ip)

32 ビットにパックされた IPv4 アドレス (長さ 4 バイトの bytes-like object) を、標準的なドット記法による 4 桁の文字列 ('123.45.67.89' など) に変換します。この関数は、struct in_addr 型を使用する標準 C ライブラリのプログラムとやりとりする場合に便利です。in_addr 型は、この関数が引数として受け取る 32 ビットにパックされたバイナリデータに対する C の型です。

この関数に渡すバイトシーケンスの長さが4バイト以外であれば、 OSError が発生します。 inet_ntoa() は、IPv6をサポートしません。IPv4/v6のデュアルスタックをサポートする場合は inet_ntop() を使用します。

バージョン 3.5 で変更: 書き込み可能な bytes-like object を使用できるようになりました。

socket.inet_pton(address_family, ip_string)

IPアドレスを、アドレスファミリ固有の文字列からパックしたバイナリ形式に変換します。 inet_pton() は、 in_addr 型 (inet_aton() と同様)や in6_addr を使用するライブラリやネットワークプロトコルを呼び出す際に使用することができます。

現在サポートされている address_family は、 AF_INET と AF_INET6 です。 ip_string に不正なIPアドレス文字列を指定すると、 OSError が発生します。有効な ip_string は、 address_family と inet_pton() の実装によって異なります。

Availability: Unix, Windows。

バージョン 3.4 で変更: Windowsで利用可能になりました

socket.inet_ntop(address_family, packed_ip)

パックしたIPアドレス (数バイトからなる bytes-like オブジェクト ) を、 '7.10.0.5' や '5aef:2b::8' などの標準的な、アドレスファミリ固有の文字列形式に変換します。 inet_ntop() は (inet_ntoa() と同様に)、 in_addr 型や in6_addr 型のオブジェクトを返すライブラリやネットワークプロトコル等で使用することができます。

現在サポートされている address_family の値は、 AF_INET と AF_INET6 です。バイトオブジェクトの packed_ip の長さが、指定したアドレスファミリで適切な長さでない場合、 ValueError が発生します。 inet_ntop() の呼び出しでエラーが起こると、 OSError が発生します。

Availability: Unix, Windows。

バージョン 3.4 で変更: Windowsで利用可能になりました

バージョン 3.5 で変更: 書き込み可能な bytes-like object を使用できるようになりました。

socket.CMSG_LEN(length)

指定された length にある制御メッセージ（CMSG）から、末尾のパディングを除いた全体の長さを返します。この値は多くの場合、 recvmsg() が制御メッセージの一連の要素を受信するためのバッファサイズとして使用できますが、バッファの末尾が要素である場合であってもパディングは含まれるので、バッファサイズを取得するには RFC 3542 [https://datatracker.ietf.org/doc/html/rfc3542.html] で求められているように、 CMSG_SPACE() を使用した移植可能なアプリケーションが必要です。通常 length は定数であり、許容範囲外の値が指定された場合は OverflowError 例外が送出されます。

Availability: Unix, not Emscripten, not WASI.

Unix プラットフォーム。

Added in version 3.3.

socket.CMSG_SPACE(length)

指定された length の制御メッセージ（CMSG）の要素を recvmsg() が受信するために必要な、パディングを含めたバッファサイズを返します。複数の項目を受信するために必要なバッファスペースは、 CMSG_SPACE() が返すそれぞれの要素の長さの合計です。通常 length は定数であり、許容範囲外の値が指定された場合は OverflowError 例外が送出されます。

一部のシステムではこの関数を提供せずに制御メッセージをサポートする可能性があることに注意してください。また、この関数の返り値を使用して設定するバッファサイズは、受信する制御メッセージの量を正確に規定しないことがあり、その後に受信するデータがパディング領域に合う場合があることに注意してください。

Availability: Unix, not Emscripten, not WASI.

most Unix platforms.

Added in version 3.3.

socket.getdefaulttimeout()

新規に生成されたソケットオブジェクトの、デフォルトのタイムアウト値を浮動小数点形式の秒数で返します。タイムアウトを使用しない場合には None を返します。最初に socket モジュールがインポートされた時の初期値は None です。

socket.setdefaulttimeout(timeout)

新規に生成されるソケットオブジェクトの、デフォルトのタイムアウト値を秒数 (float 型) で設定します。最初に socket モジュールがインポートされた時の初期値は None です。指定可能な値とその意味については settimeout() メソッドを参照してください。

socket.sethostname(name)

マシンのホスト名を name に設定します。必要な権限がない場合は OSError を送出します。

引数 name を指定して 監査イベント socket.sethostname を送出します。

利用可能な環境: Unix。

Added in version 3.3.

socket.if_nameindex()

ネットワークインターフェース情報 (index int, name string)のタプルを返します。システムコールが失敗した場合、 OSError 例外を送出します。

Availability: Unix, Windows, not Emscripten, not WASI.

Added in version 3.3.

バージョン 3.8 で変更: Windows のサポートが追加されました。

注釈

On Windows network interfaces have different names in different contexts (all names are examples):

UUID: {FB605B73-AAC2-49A6-9A2F-25416AEA0573}

name: ethernet_32770

friendly name: vEthernet (nat)

description: Hyper-V Virtual Ethernet Adapter

This function returns names of the second form from the list, ethernet_32770 in this example case.

socket.if_nametoindex(if_name)

インターフェース名 if_name に対応するネットワークインターフェースのインデックス番号を返します。対応するインターフェースが存在しない場合は OSError 例外を送出します。

Availability: Unix, Windows, not Emscripten, not WASI.

Added in version 3.3.

バージョン 3.8 で変更: Windows のサポートが追加されました。

参考

"Interface name" is a name as documented in if_nameindex().

socket.if_indextoname(if_index)

インターフェースインデックス番号 if_index に対応するネットワークインターフェース名を返します。対応するインターフェースが存在しない場合は OSError 例外を送出します。

Availability: Unix, Windows, not Emscripten, not WASI.

Added in version 3.3.

バージョン 3.8 で変更: Windows のサポートが追加されました。

参考

"Interface name" is a name as documented in if_nameindex().

socket.send_fds(sock, buffers, fds[, flags[, address]])

Send the list of file descriptors fds over an AF_UNIX socket sock. The fds parameter is a sequence of file descriptors. Consult sendmsg() for the documentation of these parameters.

Availability: Unix, Windows, not Emscripten, not WASI.

Unix platforms supporting sendmsg() and SCM_RIGHTS mechanism.

Added in version 3.9.

socket.recv_fds(sock, bufsize, maxfds[, flags])

Receive up to maxfds file descriptors from an AF_UNIX socket sock. Return (msg, list(fds), flags, addr). Consult recvmsg() for the documentation of these parameters.

Availability: Unix, Windows, not Emscripten, not WASI.

Unix platforms supporting sendmsg() and SCM_RIGHTS mechanism.

Added in version 3.9.

注釈

Any truncated integers at the end of the list of file descriptors.

socket オブジェクト

ソケットオブジェクトは以下のメソッドを持ちます。 makefile() 以外のメソッドは、Unixのソケット用システムコールに対応しています。

バージョン 3.2 で変更: context manager プロトコルのサポートが追加されました。コンテキストマネージャを終了することは、 close() を呼ぶことと同一です。

socket.accept()

接続を受け付けます。ソケットはアドレスにbind済みで、listen中である必要があります。戻り値は (conn, address) のペアで、 conn は接続を通じてデータの送受信を行うための 新しい ソケットオブジェクト、 address は接続先でソケットにbindしているアドレスを示します。

新たに作成されたソケットは 継承不可 です。

バージョン 3.4 で変更: ソケットが 継承不可 になりました。

バージョン 3.5 で変更: システムコールが中断されシグナルハンドラが例外を送出しなかった場合、このメソッドは InterruptedError 例外を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 [https://peps.python.org/pep-0475/] を参照してください)。

socket.bind(address)

ソケットを address にbindします。bind済みのソケットを再バインドする事はできません。(address のフォーマットはアドレスファミリによって異なります -- 前述。)

引数 self, address を指定して 監査イベント socket.bind を送出します。

Availability: not WASI.

socket.close()

ソケットを閉じられたものとしてマークします。 makefile() が返したファイルオブジェクトを閉じる時、対応する下層のシステムリソース（例：ファイル記述子）もすべて閉じます。一度この操作をすると、その後、このソケットオブジェクトに対するすべての操作が失敗します。キューに溜まったデータがフラッシュされた後は、リモート側の端点ではそれ以上のデータを受信しません。

ソケットはガベージコレクション時に自動的にクローズされます。しかし、明示的に close() するか、 with 文の中でソケットを使うことを推奨します。

バージョン 3.6 で変更: 下層の close() が呼び出される時、OSError が送出されるようになりました。

注釈

close() は接続に関連付けられたリソースを解放しますが、接続をすぐに切断するとは限りません。接続を即座に切断したい場合は、 close() の前に shutdown() を呼び出してください。

socket.connect(address)

address で示されるリモートソケットに接続します。(address のフォーマットはアドレスファミリによって異なります --- 前述。)

接続が信号によって中断された場合、このメソッドは接続が完了するまで待機するか、タイムアウト時に TimeoutError を送出します。タイムアウトは、信号ハンドラが例外を送出せず、ソケットがブロックするかタイムアウトが設定されている場合に起こります。非ブロックソケットでは、接続が信号によって中断された場合 (あるいは信号ハンドラにより例外が送出された場合)、このメソッドは InterruptedError 例外を送出します。

引数 self, address を指定して 監査イベント socket.connect を送出します。

バージョン 3.5 で変更: このメソッドは、接続が信号によって中断され、信号ハンドラが例外を送出せず、ソケットがブロックであるかタイムアウトが設定されている場合、InterruptedError 例外を送出する代わりに、接続を完了するまで待機するようになりました (論拠については PEP 475 [https://peps.python.org/pep-0475/] を参照してください)。

Availability: not WASI.

socket.connect_ex(address)

connect(address) と同様ですが、C言語の connect() 関数の呼び出しでエラーが発生した場合には例外を送出せずにエラーを戻り値として返します。(これ以外の、"host not found,"等のエラーの場合には例外が発生します。)処理が正常に終了した場合には 0 を返し、エラー時には errno の値を返します。この関数は、非同期接続をサポートする場合などに使用することができます。

引数 self, address を指定して 監査イベント socket.connect を送出します。

Availability: not WASI.

socket.detach()

実際にファイル記述子を閉じることなく、ソケットオブジェクトを閉じた状態にします。ファイル記述子は返却され、他の目的に再利用することができます。

Added in version 3.2.

socket.dup()

ソケットを複製します。

新たに作成されたソケットは 継承不可 です。

バージョン 3.4 で変更: ソケットが 継承不可 になりました。

Availability: not WASI.

socket.fileno()

ソケットのファイル記述子を短い整数型で返します。失敗時には、-1 を返します。ファイル記述子は、 select.select() などで使用します。

Windowsではこのメソッドで返された小整数をファイル記述子を扱う箇所 (os.fdopen() など) で利用できません。 Unix にはこの制限はありません。

socket.get_inheritable()

ソケットのファイル記述子またはソケットのハンドルの 継承可能フラグ を取得します。ソケットが子プロセスへ継承可能なら True 、継承不可なら False を返します。

Added in version 3.4.

socket.getpeername()

ソケットが接続しているリモートアドレスを返します。この関数は、リモート IPv4/v6ソケットのポート番号を調べる場合などに使用します。 address のフォーマットはアドレスファミリによって異なります(前述)。この関数をサポートしていないシステムも存在します。

socket.getsockname()

ソケット自身のアドレスを返します。この関数は、IPv4/v6ソケットのポート番号を調べる場合などに使用します。(address のフォーマットはアドレスファミリによって異なります --- 前述。)

socket.getsockopt(level, optname[, buflen])

Return the value of the given socket option (see the Unix man page getsockopt(2) [https://manpages.debian.org/getsockopt(2)]). The needed symbolic constants (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 struct for a way to decode C structures encoded as byte strings).

Availability: not WASI.

socket.getblocking()

Return True if socket is in blocking mode, False if in non-blocking.

This is equivalent to checking socket.gettimeout() != 0.

Added in version 3.7.

socket.gettimeout()

ソケットに指定されたタイムアウト値を取得します。タイムアウト値が設定されている場合には浮動小数点型で秒数が、設定されていなければ None が返ります。この値は、最後に呼び出された setblocking() または settimeout() によって設定されます。

socket.ioctl(control, option)

プラットフォーム:

Windows

ioctl() メソッドは WSAIoctl システムインターフェースへの制限されたインターフェースです。詳しい情報については、 Win32 documentation [https://msdn.microsoft.com/en-us/library/ms741621%28VS.85%29.aspx] を参照してください。

他のプラットフォームでは一般的な fcntl.fcntl() と fcntl.ioctl() が使われるでしょう; これらの関数は第 1 引数としてソケットオブジェクトを取ります。

現在、以下のコントロールコードのみがサポートされています。 SIO_RCVALL, SIO_KEEPALIVE_VALS, SIO_LOOPBACK_FAST_PATH。

バージョン 3.6 で変更: SIO_LOOPBACK_FAST_PATH が追加されました。

socket.listen([backlog])

サーバーを有効にして、接続を受け付けるようにします。backlog が指定されている場合、少なくとも 0 以上でなければなりません (それより低い場合、0 に設定されます)。システムが新しい接続を拒否するまでに許可する未受付の接続の数を指定します。指定しない場合、デフォルトの妥当な値が選択されます。

Availability: not WASI.

バージョン 3.5 で変更: backlog 引数が任意になりました。

socket.makefile(mode='r', buffering=None, *, encoding=None, errors=None, newline=None)

ソケットに関連付けられた ファイルオブジェクト を返します。戻り値の正確な型は、 makefile() に指定した引数によります。これらの引数は、組み込み関数 open() の引数と同様に解釈されます。ただし、mode の値は 'r' (デフォルト), 'w', 'b' のみがサポートされています。

ソケットはブロッキングモードでなければなりません。タイムアウトを設定することはできますが、タイムアウトが発生すると、ファイルオブジェクトの内部バッファが矛盾した状態になることがあります。

makefile() でファイルオブジェクトにソケットを関連づけた場合、ソケットを閉じるには、関連づけられたすべてのファイルオブジェクトを閉じたあとで、元のソケットの socket.close() を呼び出さなければなりません。

注釈

Windows では subprocess.Popen() の stream 引数などファイルディスクリプタつき file オブジェクトが期待されている場所では、 makefile() によって作成される file-like オブジェクトは使用できません。

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 recv(2) [https://manpages.debian.org/recv(2)] for the meaning of the optional argument flags; it defaults to zero.

注釈

ハードウェアおよびネットワークの現実に最大限マッチするように、 bufsize の値は比較的小さい2の累乗、たとえば 4096、にすべきです。

バージョン 3.5 で変更: システムコールが中断されシグナルハンドラが例外を送出しなかった場合、このメソッドは InterruptedError 例外を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 [https://peps.python.org/pep-0475/] を参照してください)。

socket.recvfrom(bufsize[, flags])

ソケットからデータを受信し、結果をタプル (bytes, address) として返します。 bytes は受信データの bytes オブジェクトで、 address は送信元のアドレスを示します。オプション引数 flags については、 Unix のマニュアルページ recv(2) [https://manpages.debian.org/recv(2)] を参照してください。デフォルトは0です。 (address のフォーマットはアドレスファミリによって異なります(前述))

バージョン 3.5 で変更: システムコールが中断されシグナルハンドラが例外を送出しなかった場合、このメソッドは InterruptedError 例外を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 [https://peps.python.org/pep-0475/] を参照してください)。

バージョン 3.7 で変更: For multicast IPv6 address, first item of address does not contain %scope_id part anymore. In order to get full IPv6 address use getnameinfo().

socket.recvmsg(bufsize[, ancbufsize[, flags]])

ソケットから通常のデータ (最大 bufsize バイト) と補助的なデータを受信します。ancbufsize 引数により、補助的なデータの受信に使用される内部バッファのバイト数として、サイズが設定されます。このデフォルトは 0 で、補助的なデータを受信しないことを意味します。CMSG_SPACE() または CMSG_LEN() を使用して、補助的なデータの適切なサイズを計算することができ、バッファ内に収まらないアイテムは、短縮されるか破棄されます。flags 引数はデフォルトでは 0 で、recv() での意味と同じ意味を持ちます。

戻り値は 4 要素のタプル (data, ancdata, msg_flags, address) です。data アイテムは、受信した非付属的データを保持する bytes オブジェクトです。ancdata アイテムは、ゼロ以上のタプル (cmsg_level, cmsg_type, cmsg_data) からなるリストで、受信する付属的なデータ (制御メッセージ) を表します。cmsg_level と cmsg_type はそれぞれ、プロトコルレベルとプロトコル固有のタイプを指定する整数で、cmsg_data は関連するデータを保持する bytes オブジェクトです。msg_flags アイテムは、受信したメッセージの条件を示す様々なフラグのビット OR です。詳細は、システムのドキュメントを参照してください。受信ソケットが接続されていない場合、address は、送信ソケットが利用できる場合にはそのアドレスで、利用できない場合、その値は未指定になります。

一部のシステムでは、sendmsg() と recvmsg() を使用して、プロセス間で AF_UNIX ソケットを経由してファイル記述子を渡すことができます。この機能を使用する場合 (しばしば SOCK_STREAM ソケットに限定されます)、recvmsg() は、付属的なデータ中に、(socket.SOL_SOCKET, socket.SCM_RIGHTS, fds) という形式のアイテムを返します。ここで、fds は、新しいファイル記述子をネイティブ C の int 型のバイナリ配列として表す bytes オブジェクトです。システムコールが返った後 recvmsg() が例外を送出する場合、まずこのメカニズムを経由して受信したファイル記述子を全て閉じようと試みます。

一部のシステムでは、部分的に受信した付属的なデータアイテムの短縮された長さが示されません。アイテムがバッファの末尾を超えているようである場合、recvmsg() は RuntimeWarning を送出し、関連するデータの開始位置より前で途切れていない場合、バッファ内の付属的なデータの一部を返します。

SCM_RIGHTS メカニズムをサポートするシステム上では、次の関数が最大 maxfds のファイル記述子を受信し、メッセージデータと記述子を含むリストを返しま(無関係な制御メッセージを受信した場合など、予期しない条件は無視します)。 sendmsg() も参照してください。

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)

利用可能な環境: Unix。

Unix プラットフォーム。

Added in version 3.3.

バージョン 3.5 で変更: システムコールが中断されシグナルハンドラが例外を送出しなかった場合、このメソッドは InterruptedError 例外を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 [https://peps.python.org/pep-0475/] を参照してください)。

socket.recvmsg_into(buffers[, ancbufsize[, flags]])

recvmsg() と同様に動作してソケットから通常のデータと付属的なデータを受信しますが、非付属的データは新しいバイトオブジェクトとして返すのではなく、一連のバッファとして返します。buffers 引数は書き込み可能なバッファをエクスポートするオブジェクトのイテラブルでなければなりません (例: bytearray オブジェクト)。これらは、全てに書き込まれるか、残りバッファがなくなるまで、非付属的データの連続チャンクで埋められます。オペレーティングシステムによって、使用できるバッファの数が制限 (sysconf() 値 SC_IOV_MAX) されている場合があります。ancbufsize 引数と flags 引数は、recvmsg() での意味と同じ意味を持ちます。

戻り値は 4 要素のタプル (nbytes, ancdata, msg_flags, address) です。ここで、nbytes はバッファに書き込まれた非付属的データの総数で、ancdata、msg_flags、address は recvmsg() と同様です。

以下はプログラム例です:

>>> 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---')]

利用可能な環境: Unix。

Unix プラットフォーム。

Added in version 3.3.

socket.recvfrom_into(buffer[, nbytes[, flags]])

ソケットからデータを受信し、そのデータを新しいバイト文字列として返す代わりに buffer に書きます。戻り値は (nbytes, address) のペアで、 nbytes は受信したデータのバイト数を、 address はデータを送信したソケットのアドレスです。オプション引数 flags (デフォルト:0) の意味については、 Unix マニュアルページ recv(2) [https://manpages.debian.org/recv(2)] を参照してください。(address のフォーマットは前述のとおりアドレスファミリーに依存します。)

socket.recv_into(buffer[, nbytes[, flags]])

nbytes バイトまでのデータをソケットから受信して、そのデータを新しいバイト文字列にするのではなく buffer に保存します。 nbytes が指定されない(あるいは0が指定された)場合、 buffer の利用可能なサイズまで受信します。受信したバイト数を返り値として返します。オプション引数 flags (デフォルト:0) の意味については、 Unix マニュアルページ recv(2) [https://manpages.debian.org/recv(2)] を参照してください。

socket.send(bytes[, flags])

ソケットにデータを送信します。ソケットはリモートソケットに接続済みでなければなりません。オプション引数 flags の意味は、上記 recv() と同じです。戻り値として、送信したバイト数を返します。アプリケーションでは、必ず戻り値をチェックし、全てのデータが送られた事を確認する必要があります。データの一部だけが送信された場合、アプリケーションで残りのデータを再送信してください。 ソケットプログラミングHOWTO に、さらに詳しい情報があります。

バージョン 3.5 で変更: システムコールが中断されシグナルハンドラが例外を送出しなかった場合、このメソッドは InterruptedError 例外を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 [https://peps.python.org/pep-0475/] を参照してください)。

socket.sendall(bytes[, flags])

ソケットにデータを送信します。ソケットはリモートソケットに接続済みでなければなりません。オプション引数 flags の意味は、上記 recv() と同じです。 send() と異なり、このメソッドは bytes の全データを送信するか、エラーが発生するまで処理を継続します。正常終了の場合は None を返し、エラー発生時には例外が発生します。エラー発生時、送信されたバイト数を調べる事はできません。

バージョン 3.5 で変更: ソケットのタイムアウトは、データが正常に送信される度にリセットされなくなりました。ソケットのタイムアウトは、すべてのデータを送る最大の合計時間となります。

バージョン 3.5 で変更: システムコールが中断されシグナルハンドラが例外を送出しなかった場合、このメソッドは InterruptedError 例外を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 [https://peps.python.org/pep-0475/] を参照してください)。

socket.sendto(bytes, address)

socket.sendto(bytes, flags, address)

ソケットにデータを送信します。このメソッドでは接続先を address で指定するので、接続済みではいけません。オプション引数 flags の意味は、上記 recv() と同じです。戻り値として、送信したバイト数を返します。(address のフォーマットはアドレスファミリによって異なります --- 前述。)

引数 self, address を指定して 監査イベント socket.sendto を送出します。

バージョン 3.5 で変更: システムコールが中断されシグナルハンドラが例外を送出しなかった場合、このメソッドは InterruptedError 例外を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 [https://peps.python.org/pep-0475/] を参照してください)。

socket.sendmsg(buffers[, ancdata[, flags[, address]]])

非付属的なデータを一連のバッファから集め、単一のメッセージにまとめることで、通常のデータと付属的なデータをソケットに送信します。buffers 引数は、非付属的なデータを bytes-like objects (例: bytes オブジェクト) のイテラブルとして指定します。オペレーティングシステムによって、使用できるバッファの数が制限 (sysconf() 値 SC_IOV_MAX) されている場合があります。ancdata 引数は付属的なデータ (制御メッセージ) をゼロ以上のタプル (cmsg_level, cmsg_type, cmsg_data) のイテラブルとして指定します。ここで、cmsg_level と cmsg_type はそれぞれプロトコルレベルとプロトコル固有のタイプを指定する整数で、cmsg_data は関連データを保持するバイトライクオブジェクトです。一部のシステム (特に CMSG_SPACE() を持たないシステム) では、一度の呼び出しで一つの制御メッセージの送信しかサポートされていない場合があります。flags 引数のデフォルトは 0 であり、send() での意味と同じ意味を持ちます。None 以外の address が渡された場合、メッセージの目的地のアドレスを設定します。戻り値は、送信された非付属的データのバイト数です。

以下の関数は、SCM_RIGHTS メカニズムをサポートするシステムで、ファイル記述子 fds を AF_UNIX ソケット経由で送信します。recvmsg() も参照してください。

import socket, array

def send_fds(sock, msg, fds):
    return sock.sendmsg([msg], [(socket.SOL_SOCKET, socket.SCM_RIGHTS, array.array("i", fds))])

Availability: Unix, not WASI.

Unix プラットフォーム。

引数 self, address を指定して 監査イベント socket.sendmsg を送出します。

Added in version 3.3.

バージョン 3.5 で変更: システムコールが中断されシグナルハンドラが例外を送出しなかった場合、このメソッドは InterruptedError 例外を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 [https://peps.python.org/pep-0475/] を参照してください)。

socket.sendmsg_afalg([msg, ]*, op[, iv[, assoclen[, flags]]])

sendmsg() の AF_ALG ソケット用に特化したバージョンです。AF_ALG ソケットの、モード、IV、AEAD に関連づけられたデータ長、フラグを設定します。

利用可能な環境: Linux 2.6.38以上。

Added in version 3.6.

socket.sendfile(file, offset=0, count=None)

高性能の os.sendfile を使用して、ファイルを EOF まで送信し、送信されたバイトの総数を返します。file は、バイナリモードで開かれた標準的なファイルオブジェクトです。os.sendfile が使用できない場合 (例: Windows)、または file が標準的なファイルでない場合、代わりに send() が使用されます。offset は、ファイルの読み出し開始位置を指定します。count が指定されている場合、ファイルを EOF まで送信するのではなく、転送するバイトの総数を指定します。ファイルの位置は、返る時に更新されます。あるいは、エラー時には file.tell()  を使用して送信されたバイトの数を確認することができます。ソケットは SOCK_STREAM タイプでなければなりません。非ブロックソケットはサポートされていません。

Added in version 3.5.

socket.set_inheritable(inheritable)

ソケットのファイル記述子、またはソケットのハンドルの、 継承可能フラグ を立てます。

Added in version 3.4.

socket.setblocking(flag)

ソケットをブロッキングモード、または非ブロッキングモードに設定します。flag が False の場合にはソケットは非ブロッキングモードになり、True の場合にはブロッキングモードになります。

このメソッドは、次の settimeout() 呼び出しの省略表記です:

sock.setblocking(True) は sock.settimeout(None) と等価です

sock.setblocking(False) は sock.settimeout(0.0) と等価です

バージョン 3.7 で変更: The method no longer applies SOCK_NONBLOCK flag on socket.type.

socket.settimeout(value)

ブロッキングソケットの処理のタイムアウト値を指定します。 value には float 型で非負の秒数を指定するか、 None を指定します。ゼロ以外の値を指定した場合、ソケットの処理が完了する前に value で指定した秒数が経過すれば timeout 例外を送出します。ゼロを指定した場合、ソケットは非ブロッキングモード状態に置かれます。 None を指定した場合、ソケットのタイムアウトを無効にします。

詳しくは ソケットタイムアウトの注意事項 を参照してください。

バージョン 3.7 で変更: The method no longer toggles SOCK_NONBLOCK flag on socket.type.

socket.setsockopt(level, optname, value: int)

socket.setsockopt(level, optname, value: buffer)

socket.setsockopt(level, optname, None, optlen: int)

Set the value of the given socket option (see the Unix manual page setsockopt(2) [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, None or a 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 struct for a way to encode C structures as bytestrings). When value is set to None, optlen argument is required. It's equivalent to call setsockopt() C function with optval=NULL and optlen=optlen.

バージョン 3.5 で変更: 書き込み可能な bytes-like object を使用できるようになりました。

バージョン 3.6 で変更: setsockopt(level, optname, None, optlen: int) の形式が追加されました。

Availability: not WASI.

socket.shutdown(how)

接続の片方向、または両方向を切断します。 how が SHUT_RD の場合、以降は受信を行えません。 how が SHUT_WR の場合、以降は送信を行えません。 how が SHUT_RDWR の場合、以降は送受信を行えません。

Availability: not WASI.

socket.share(process_id)

ソケットを複製し、対象のプロセスと共有するための bytes オブジェクトを返します。対象のプロセスを process_id で指定しなければなりません。戻り値の bytes オブジェクトは、何らかのプロセス間通信を使って対象のプロセスに伝えます。対象のプロセス側では、 fromshare() を使って複製されたソケットをとらえます。オペレーティング・システムは対象のプロセスに対してソケットを複製するため、このメソッドを呼び出した後であれば、元のソケットをクローズしても、対象のプロセスに渡ったソケットには影響がありません。

利用可能な環境: Windows 。

Added in version 3.3.

read() メソッドと write() メソッドは存在しませんので注意してください。代わりに flags を省略した recv() と send() を使うことができます。

ソケットオブジェクトには以下の socket コンストラクタに渡された値に対応した (読み出し専用) 属性があります。

socket.family

ソケットファミリー。

socket.type

ソケットタイプ。

socket.proto

ソケットプロトコル。

ソケットタイムアウトの注意事項

ソケットオブジェクトは、ブロッキングモード、非ブロッキングモード、タイムアウトモードのうち、いずれか1つのモードをとります。デフォルトでは、ソケットは常にブロッキングモードで作成されますが、 setdefaulttimeout() で標準のモードを変更することができます。

ブロッキングモード での操作は、完了するか、または（接続がタイムアウトするなどして）システムがエラーを返すまで、ブロックされます。

非ブロッキングモード での操作は、ただちに完了できない場合、例外を送出して失敗します。この場合の例外の種類は、システムに依存するため、ここに記すことができません。 select モジュールの関数を使って、ソケットの読み書きが利用可能かどうか、可能な場合はいつ利用できるかを調べることができます。

タイムアウトモード での操作は、指定されたタイムアウトの時間内に完了しなければ、 timeout 例外を送出します。タイムアウトの時間内にシステムがエラーを返した場合は、そのエラーを返します。

注釈

オペレーティング・システムのレベルでは、 タイムアウトモード のソケットには、内部的に非ブロッキングモードが設定されています。またブロッキングモードとタイムアウトモードの指定は、ファイル記述子と、「そのファイル記述子と同じネットワーク端点を参照するソケットオブジェクト」との間で共有されます。このことは、例えばソケットの fileno() を使うことにした場合に、明らかな影響を与えます。

タイムアウトと connect メソッド

connect() もタイムアウト設定に従います。一般的に、 settimeout() を connect() の前に呼ぶか、 create_connection() にタイムアウト引数を渡すことが推奨されます。ただし、システムのネットワークスタックが Python のソケットタイムアウトの設定を無視して、自身の接続タイムアウトエラーを返すこともあります。

タイムアウトと accept メソッド

getdefaulttimeout() が None でない場合、 accept() メソッドが返すソケットでは、そのタイムアウトが継承されます。 None である場合、待機中のソケットの設定によって動作は異なります。

待機中のソケットが ブロッキングモード または タイムアウトモード である場合、accept() が返すソケットは、ブロッキングモード になります。

待機中のソケットが 非ブロッキングモード である場合、accept() が返すソケットは、オペレーティングシステムによってブロッキングモードまたは非ブロッキングモードになります。クロスプラットフォームの動作を確保したい場合、この設定を手動でオーバーライドすることをお勧めします。

使用例

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 socket(), bind(), listen(), accept() (possibly repeating the accept() to service more than one client), while a client only needs the sequence socket(), connect(). Also note that the server does not sendall()/recv() on the socket it is listening on but on the new socket returned by accept().

次のクライアントとサーバは、IPv4 のみをサポートしています。

# Echo server program
import socket

HOST = ''                 # 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)

# 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))

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.

# 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)

# 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))

次の例は、Windowsで raw socket を利用して非常にシンプルなネットワークスニファーを書きます。このサンプルを実行するには、インターフェースを操作するための管理者権限が必要です:

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)

次の例では、ソケットインターフェースを使用してローソケットプロトコルを使用する CAN ネットワークと通信する方法を説明します。ブロードキャストマネージャプロトコロルで CAN を使用するには、以下でソケットを開きます。

socket.socket(socket.AF_CAN, socket.SOCK_DGRAM, socket.CAN_BCM)

ソケットの束縛 (CAN_RAW) または (CAN_BCM) 接続を行ったあと、ソケットオブジェクトで socket.send() と socket.recv() 操作 (とそのカウンターパート) を通常通りに使用することができます。

最後の例では、特権が必要になるかもしれません:

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')

この例を、ほとんど間を空けずに複数回実行すると、以下のエラーが発生する場合があります:

OSError: [Errno 98] Address already in use

これは以前の実行がソケットを TIME_WAIT 状態のままにし、すぐには再利用できないことで起こります。

There is a socket flag to set, in order to prevent this, socket.SO_REUSEADDR:

s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
s.bind((HOST, PORT))

SO_REUSEADDR フラグは、 TIME_WAIT 状態にあるローカルソケットをそのタイムアウト期限が自然に切れるのを待つことなく再利用することをカーネルに伝えます。

参考

C 言語によるソケットプログラミングの基礎については、以下の資料を参照してください。

An Introductory 4.3BSD Interprocess Communication Tutorial, by Stuart Sechrest

An Advanced 4.3BSD Interprocess Communication Tutorial, by Samuel J. Leffler et al,

両書とも UNIX Programmer's Manual, Supplementary Documents 1 (PS1:7章 PS1:8章)。ソケットの詳細については、各プラットフォームのソケット関連システムコールに関するドキュメントも参照してください。Unix ではマニュアルページ、WindowsではWinSock (または WinSock2) 仕様書をご覧ください。IPv6 対応の API については、 RFC 3493 [https://datatracker.ietf.org/doc/html/rfc3493.html] "Basic Socket Interface Extensions for IPv6" を参照してください。

ssl --- TLS/SSL wrapper for socket objects

Source code: Lib/ssl.py [https://github.com/python/cpython/tree/3.12/Lib/ssl.py]

このモジュールは Transport Layer Security ( "Secure Sockets Layer" という名前でよく知られています) 暗号化と、クライアントサイド、サーバサイド両方のネットワークソケットのためのピア認証の仕組みを提供しています。このモジュールは OpenSSL ライブラリを利用しています。 OpenSSL は、すべてのモダンな Unix システム、 Windows 、 macOS 、その他幾つかの OpenSSL がインストールされているプラットフォームで利用できます。

注釈

Some behavior may be platform dependent, since calls are made to the operating system socket APIs. The installed version of OpenSSL may also cause variations in behavior. For example, TLSv1.3 comes with OpenSSL version 1.1.1.

警告

セキュリティで考慮すべき点 を読まずにこのモジュールを使用しないでください。SSL のデフォルト設定はアプリケーションに十分ではないので、読まない場合はセキュリティに誤った意識を持ってしまうかもしれません。

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. See WebAssemblyプラットフォーム for more information.

このセクションでは、 ssl モジュールのオブジェクトと関数を解説します。 TLS, SSL, 証明書に関するより一般的な情報は、末尾にある "See Also" のセクションを参照してください。

This module provides a class, ssl.SSLSocket, which is derived from the socket.socket type, and provides a socket-like wrapper that also encrypts and decrypts the data going over the socket with SSL. It supports additional methods such as getpeercert(), which retrieves the certificate of the other side of the connection, and cipher(), which retrieves the cipher being used for the secure connection.

より洗練されたアプリケーションのために、 ssl.SSLContext クラスが設定と証明書の管理の助けとなるでしょう。それは SSLContext.wrap_socket() メソッドを通して SSL ソケットを作成することで引き継がれます。

バージョン 3.5.3 で変更: Updated to support linking with 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 で変更: PEP 644 [https://peps.python.org/pep-0644/] has been implemented. The ssl module requires OpenSSL 1.1.1 or newer.

Use of deprecated constants and functions result in deprecation warnings.

関数、定数、例外

ソケットの作成

Instances of SSLSocket must be created using the SSLContext.wrap_socket() method. The helper function create_default_context() returns a new context with secure default settings.

Client socket example with default context and IPv4/IPv6 dual stack:

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())

Client socket example with custom context and IPv4:

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())

Server socket example listening on localhost IPv4:

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

コンテキストの作成

コンビニエンス関数が、共通の目的で使用される SSLContext オブジェクトを作成するのに役立ちます。

ssl.create_default_context(purpose=Purpose.SERVER_AUTH, cafile=None, capath=None, cadata=None)

新規の SSLContext オブジェクトを、与えられた purpose のデフォルト設定で返します。設定は ssl モジュールで選択され、通常は SSLContext のコンストラクタを直接呼び出すよりも高いセキュリティレベルを表現します。

cafile, capath, cadata は証明書の検証で信用するオプションの CA 証明書で、 SSLContext.load_verify_locations() のものと同じです。これら 3 つすべてが None であれば、この関数は代わりにシステムのデフォルトの CA 証明書を信用して選択することができます。

The settings are: PROTOCOL_TLS_CLIENT or PROTOCOL_TLS_SERVER, OP_NO_SSLv2, and OP_NO_SSLv3 with high encryption cipher suites without RC4 and without unauthenticated cipher suites. Passing SERVER_AUTH as purpose sets verify_mode to CERT_REQUIRED and either loads CA certificates (when at least one of cafile, capath or cadata is given) or uses SSLContext.load_default_certs() to load default CA certificates.

When keylog_filename is supported and the environment variable SSLKEYLOGFILE is set, create_default_context() enables key logging.

注釈

プロトコル、オプション、暗号方式その他の設定は、事前に非推奨の状態にすることなく、もっと制限の強い値に変更される場合があります。これらの値は、互換性と安全性との妥当なバランスをとって決められます。

もしもあなたのアプリケーションが特定の設定を必要とする場合、 SSLContext を作って自分自身で設定を適用すべきです。

注釈

ある種の古いクライアントやサーバが接続しようと試みてきた場合に、この関数で作られた SSLContext が "Protocol or cipher suite mismatch" で始まるエラーを起こすのを目撃したらそれは、この関数が OP_NO_SSLv3 を使って除外している SSL 3.0 しかサポートしていないのでしょう。SSL 3.0 は 完璧にぶっ壊れている [https://en.wikipedia.org/wiki/POODLE] ことが広く知られています。それでもまだこの関数を使って、ただし SSL 3.0 接続を許可したいと望むならば、これをこのように再有効化できます:

ctx = ssl.create_default_context(Purpose.CLIENT_AUTH)
ctx.options &= ~ssl.OP_NO_SSLv3

Added in version 3.4.

バージョン 3.4.4 で変更: デフォルトの暗号設定から RC4 が除かれました。

バージョン 3.6 で変更: デフォルトの暗号化文字列に ChaCha20/Poly1305 が追加されました。

デフォルトの暗号化文字列から 3DES が除かれました。

バージョン 3.8 で変更: Support for key logging to SSLKEYLOGFILE was added.

バージョン 3.10 で変更: The context now uses PROTOCOL_TLS_CLIENT or PROTOCOL_TLS_SERVER protocol instead of generic PROTOCOL_TLS.

例外

exception ssl.SSLError

(現在のところ OpenSSL ライブラリによって提供されている)下層の SSL 実装からのエラーを伝えるための例外です。このエラーは、低レベルなネットワークの上に載っている、高レベルな暗号化と認証レイヤーでの問題を通知します。このエラーは OSError のサブタイプです。 SSLError インスタンスのエラーコードとメッセージは OpenSSL ライブラリによるものです。

バージョン 3.3 で変更: SSLError は以前は socket.error のサブタイプでした。

library

エラーが起こった OpenSSL サブモジュールを示すニーモニック文字列で、 SSL, PEM, X509 などです。取り得る値は OpenSSL のバージョンに依存します。

Added in version 3.3.

reason

エラーが起こった原因を示すニーモニック文字列で、 CERTIFICATE_VERIFY_FAILED などです。取り得る値は OpenSSL のバージョンに依存します。

Added in version 3.3.

exception ssl.SSLZeroReturnError

読み出しあるいは書き込みを試みようとした際に SSL コネクションが行儀よく閉じられてしまった場合に送出される SSLError サブクラス例外です。これは下層の転送(read TCP)が閉じたことは意味しないことに注意してください。

Added in version 3.3.

exception ssl.SSLWantReadError

読み出しあるいは書き込みを試みようとした際に、リクエストが遂行される前に下層の TCP 転送で受け取る必要があるデータが不足した場合に non-blocking SSL socket によって送出される SSLError サブクラス例外です。

Added in version 3.3.

exception ssl.SSLWantWriteError

読み出しあるいは書き込みを試みようとした際に、リクエストが遂行される前に下層の TCP 転送が送信する必要があるデータが不足した場合に non-blocking SSL socket によって送出される SSLError サブクラス例外です。

Added in version 3.3.

exception ssl.SSLSyscallError

SSL ソケット上で操作を遂行しようとしていてシステムエラーが起こった場合に送出される SSLError サブクラス例外です。残念ながら元となった errno 番号を調べる簡単な方法はありません。

Added in version 3.3.

exception ssl.SSLEOFError

SSL コネクションが唐突に打ち切られた際に送出される SSLError サブクラス例外です。一般的に、このエラーが起こったら下層の転送を再利用しようと試みるべきではありません。

Added in version 3.3.

exception ssl.SSLCertVerificationError

A subclass of SSLError raised when certificate validation has failed.

Added in version 3.7.

verify_code

A numeric error number that denotes the verification error.

verify_message

A human readable string of the verification error.

exception ssl.CertificateError

SSLCertVerificationError の別名です。

バージョン 3.7 で変更: 例外は SSLCertVerificationError の別名になりました。

乱数生成

ssl.RAND_bytes(num)

暗号学的に強固な擬似乱数の num バイトを返します。擬似乱数生成器に十分なデータでシードが与えられていない場合や、現在の RANDOM メソッドに操作がサポートされていない場合は SSLError を送出します。 RAND_status() を使って擬似乱数生成器の状態をチェックできます。 RAND_add() を使って擬似乱数生成器にシードを与えることができます。

ほとんどすべてのアプリケーションでは os.urandom() が望ましいです。

暗号論的に強い擬似乱数生成器に要求されることについては Wikipedia の記事 Cryptographically secure pseudorandom number generator (CSPRNG) [https://en.wikipedia.org/wiki/Cryptographically_secure_pseudorandom_number_generator] (日本語版: 暗号論的擬似乱数生成器 [http://ja.wikipedia.org/wiki/%E6%9A%97%E5%8F%B7%E8%AB%96%E7%9A%84%E6%93%AC%E4%BC%BC%E4%B9%B1%E6%95%B0%E7%94%9F%E6%88%90%E5%99%A8]) を参照してください。

Added in version 3.3.

ssl.RAND_status()

SSL 擬似乱数生成器が十分なランダム性(randomness)を受け取っている時に True を、それ以外の場合は False を返します。 ssl.RAND_egd() と ssl.RAND_add() を使って擬似乱数生成機にランダム性を加えることができます。

ssl.RAND_add(bytes, entropy)

Mix the given bytes into the SSL pseudo-random number generator. The parameter entropy (a float) is a lower bound on the entropy contained in string (so you can always use 0.0). See RFC 1750 [https://datatracker.ietf.org/doc/html/rfc1750.html] for more information on sources of entropy.

バージョン 3.5 で変更: 書き込み可能な bytes-like object を使用できるようになりました。

証明書の取り扱い

ssl.cert_time_to_seconds(cert_time)

cert_time として証明書内の "notBefore" や "notAfter" の "%b %d %H:%M:%S %Y %Z" strptime フォーマット (C locale) 日付を渡すと、エポックからの積算秒を返します。

例です。 :

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

"notBefore" や "notAfter" の日付には GMT を使わなければなりません(RFC 5280 [https://datatracker.ietf.org/doc/html/rfc5280.html])。

バージョン 3.5 で変更: 入力文字列に指定された 'GMT' タイムゾーンを UTC として解釈するようになりました。以前はローカルタイムで解釈していました。また、整数を返すようになりました(入力に含まれる秒の端数を含まない)。

ssl.get_server_certificate(addr, ssl_version=PROTOCOL_TLS_CLIENT, ca_certs=None[, timeout])

Given the address addr of an SSL-protected server, as a (hostname, port-number) pair, fetches the server's certificate, and returns it as a PEM-encoded string. If ssl_version is specified, uses that version of the SSL protocol to attempt to connect to the server. If ca_certs is specified, it should be a file containing a list of root certificates, the same format as used for the cafile parameter in SSLContext.load_verify_locations(). The call will attempt to validate the server certificate against that set of root certificates, and will fail if the validation attempt fails. A timeout can be specified with the timeout parameter.

バージョン 3.3 で変更: この関数はIPv6互換になりました。

バージョン 3.5 で変更: ssl_version のデフォルトが、最近のサーバへの最大限の互換性のために PROTOCOL_SSLv3 から PROTOCOL_TLS に変更されました。

バージョン 3.10 で変更: timeout 引数が追加されました。

ssl.DER_cert_to_PEM_cert(DER_cert_bytes)

DERエンコードされたバイト列として与えられた証明書から、 PEMエンコードされたバージョンの同じ証明書を返します。

ssl.PEM_cert_to_DER_cert(PEM_cert_string)

PEM 形式のASCII文字列として与えられた証明書から、同じ証明書をDERエンコードしたバイト列を返します。

ssl.get_default_verify_paths()

OpenSSL デフォルトの cafile, capath を指すパスを名前付きタプルで返します。パスは SSLContext.set_default_verify_paths() で使われるものと同じです。戻り値は named tuple DefaultVerifyPaths です:

cafile - cafile の解決済みパス、またはファイルが存在しない場合は None

capath - capath の解決済みパス、またはディレクトリが存在しない場合は None

openssl_cafile_env - cafile を指す OpenSSL の環境変数

openssl_cafile - OpenSSL にハードコードされた cafile のパス

openssl_capath_env - capath を指す OpenSSL の環境変数

openssl_capath - OpenSSL にハードコードされた capath のパス

Added in version 3.4.

ssl.enum_certificates(store_name)

Windows のシステム証明書ストアより証明書を抽出します。 store_name は CA, ROOT, MY のうちどれか一つでしょう。Windows は追加の証明書ストアを提供しているかもしれません。

この関数はタプル (cert_bytes, encoding_type, trust) のリストで返します。encoding_type は cert_bytes のエンコーディングを表します。X.509 ASN.1 に対する x509_asn か PKCS#7 ASN.1 データに対する pkcs_7_asn のいずれかです。trust は、証明書の目的を、OIDS を内容に持つ set として表すか、または証明書がすべての目的で信頼できるならば True です。

以下はプログラム例です:

>>> 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)]

利用可能な環境: Windows 。

Added in version 3.4.

ssl.enum_crls(store_name)

Windows のシステム証明書ストアより CRLs を抽出します。 store_name は CA, ROOT, MY のうちどれか一つでしょう。Windows は追加の証明書ストアを提供しているかもしれません。

この関数はタプル (cert_bytes, encoding_type, trust) のリストで返します。encoding_type は cert_bytes のエンコーディングを表します。X.509 ASN.1 に対する x509_asn か PKCS#7 ASN.1 データに対する pkcs_7_asn のいずれかです。

利用可能な環境: Windows 。

Added in version 3.4.

定数

すべての定数が enum.IntEnum コレクションまたは enum.IntFlag コレクションになりました。

Added in version 3.6.

ssl.CERT_NONE

Possible value for SSLContext.verify_mode. Except for PROTOCOL_TLS_CLIENT, it is the default mode. With client-side sockets, just about any cert is accepted. Validation errors, such as untrusted or expired cert, are ignored and do not abort the TLS/SSL handshake.

In server mode, no certificate is requested from the client, so the client does not send any for client cert authentication.

このドキュメントの下の方の、 セキュリティで考慮すべき点 に関する議論を参照してください。

ssl.CERT_OPTIONAL

Possible value for SSLContext.verify_mode. In client mode, CERT_OPTIONAL has the same meaning as CERT_REQUIRED. It is recommended to use CERT_REQUIRED for client-side sockets instead.

In server mode, a client certificate request is sent to the client. The client may either ignore the request or send a certificate in order perform TLS client cert authentication. If the client chooses to send a certificate, it is verified. Any verification error immediately aborts the TLS handshake.

Use of this setting requires a valid set of CA certificates to be passed to SSLContext.load_verify_locations().

ssl.CERT_REQUIRED

Possible value for SSLContext.verify_mode. In this mode, certificates are required from the other side of the socket connection; an SSLError will be raised if no certificate is provided, or if its validation fails. This mode is not sufficient to verify a certificate in client mode as it does not match hostnames. check_hostname must be enabled as well to verify the authenticity of a cert. PROTOCOL_TLS_CLIENT uses CERT_REQUIRED and enables check_hostname by default.

With server socket, this mode provides mandatory TLS client cert authentication. A client certificate request is sent to the client and the client must provide a valid and trusted certificate.

Use of this setting requires a valid set of CA certificates to be passed to SSLContext.load_verify_locations().

class ssl.VerifyMode

CERT_* 定数の enum.IntEnum コレクションです。

Added in version 3.6.

ssl.VERIFY_DEFAULT

SSLContext.verify_flags に渡せる値です。このモードでは、証明書失効リスト(CRLs)はチェックされません。デフォルトでは OpenSSL は CRLs を必要ともしませんし検証にも使いません。

Added in version 3.4.

ssl.VERIFY_CRL_CHECK_LEAF

SSLContext.verify_flags に渡せる値です。このモードでは、接続先の証明書のみがチェックされ、仲介の CA 証明書はチェックされません。接続先証明書の発行者(その CA の直接の祖先)によって署名された妥当な CRL が必要です。 SSLContext.load_verify_locations で相応しい CRL をロードしていなければ、検証は失敗します。

Added in version 3.4.

ssl.VERIFY_CRL_CHECK_CHAIN

SSLContext.verify_flags に渡せる値です。このモードでは、接続先の証明書チェイン内のすべての証明書についての CRLs がチェックされます。

Added in version 3.4.

ssl.VERIFY_X509_STRICT

SSLContext.verify_flags に渡せる値で、壊れた X.509 証明書に対するワークアラウンドを無効にします。

Added in version 3.4.

ssl.VERIFY_ALLOW_PROXY_CERTS

Possible value for SSLContext.verify_flags to enables proxy certificate verification.

Added in version 3.10.

ssl.VERIFY_X509_TRUSTED_FIRST

SSLContext.verify_flags に渡せる値です。OpenSSL に対し、証明書検証のために信頼チェインを構築する際、信頼できる証明書を選ぶように指示します。これはデフォルトで有効にされています。

Added in version 3.4.4.

ssl.VERIFY_X509_PARTIAL_CHAIN

Possible value for SSLContext.verify_flags. It instructs OpenSSL to accept intermediate CAs in the trust store to be treated as trust-anchors, in the same way as the self-signed root CA certificates. This makes it possible to trust certificates issued by an intermediate CA without having to trust its ancestor root CA.

Added in version 3.10.

class ssl.VerifyFlags

VERIFY_* 定数の enum.IntFlag コレクションです。

Added in version 3.6.

ssl.PROTOCOL_TLS

クライアントとサーバの両方がサポートするプロトコルバージョンのうち、最も大きなものを選択します。名前に反して、このオプションは "SSL" と "TLS" プロトコルのいずれも選択できます。

Added in version 3.6.

バージョン 3.10 で非推奨: TLS clients and servers require different default settings for secure communication. The generic TLS protocol constant is deprecated in favor of PROTOCOL_TLS_CLIENT and PROTOCOL_TLS_SERVER.

ssl.PROTOCOL_TLS_CLIENT

Auto-negotiate the highest protocol version that both the client and server support, and configure the context client-side connections. The protocol enables CERT_REQUIRED and check_hostname by default.

Added in version 3.6.

ssl.PROTOCOL_TLS_SERVER

Auto-negotiate the highest protocol version that both the client and server support, and configure the context server-side connections.

Added in version 3.6.

ssl.PROTOCOL_SSLv23

PROTOCOL_TLS のエイリアスです。

バージョン 3.6 で非推奨: 代わりに PROTOCOL_TLS を使用してください。

ssl.PROTOCOL_SSLv3

チャンネル暗号化プロトコルとしてSSLバージョン3を選択します。

このプロトコルは、 OpenSSL が no-ssl3 オプションをつけてコンパイルされている場合には利用できません。

警告

SSL version 3 は非セキュアです。このプロトコルは強く非推奨です。

バージョン 3.6 で非推奨: OpenSSL has deprecated all version specific protocols. Use the default protocol PROTOCOL_TLS_SERVER or PROTOCOL_TLS_CLIENT with SSLContext.minimum_version and SSLContext.maximum_version instead.

ssl.PROTOCOL_TLSv1

チャンネル暗号化プロトコルとしてTLSバージョン1.0を選択します。

バージョン 3.6 で非推奨: OpenSSL has deprecated all version specific protocols.

ssl.PROTOCOL_TLSv1_1

チャンネル暗号化プロトコルとしてTLSバージョン1.1を選択します。 openssl version 1.0.1+ のみで利用可能です。

Added in version 3.4.

バージョン 3.6 で非推奨: OpenSSL has deprecated all version specific protocols.

ssl.PROTOCOL_TLSv1_2

チャンネル暗号化プロトコルとしてTLSバージョン 1.2 を選択します。 openssl version 1.0.1+ のみで利用可能です。

Added in version 3.4.

バージョン 3.6 で非推奨: OpenSSL has deprecated all version specific protocols.

ssl.OP_ALL

相手にする SSL 実装のさまざまなバグを回避するためのワークアラウンドを有効にします。このオプションはデフォルトで有効です。これを有効にする場合 OpenSSL 用の同じ意味のフラグ SSL_OP_ALL をセットする必要はありません。

Added in version 3.2.

ssl.OP_NO_SSLv2

SSLv2 接続が行われないようにします。このオプションは PROTOCOL_TLS と組み合わされている場合にのみ適用されます。ピアがプロトコルバージョンとして SSLv2 を選択しないようにします。

Added in version 3.2.

バージョン 3.6 で非推奨: SSLv2 は非推奨です

ssl.OP_NO_SSLv3

SSLv3 接続が行われないようにします。このオプションは PROTOCOL_TLS と組み合わされている場合にのみ適用されます。ピアがプロトコルバージョンとして SSLv3 を選択しないようにします。

Added in version 3.2.

バージョン 3.6 で非推奨: SSLv3 は非推奨です

ssl.OP_NO_TLSv1

TLSv1 接続が行われないようにします。このオプションは PROTOCOL_TLS と組み合わされている場合にのみ適用されます。ピアがプロトコルバージョンとして TLSv1 を選択しないようにします。

Added in version 3.2.

バージョン 3.7 で非推奨: The option is deprecated since OpenSSL 1.1.0, use the new SSLContext.minimum_version and SSLContext.maximum_version instead.

ssl.OP_NO_TLSv1_1

TLSv1.1 接続が行われないようにします。このオプションは PROTOCOL_TLS と組み合わされている場合にのみ適用されます。ピアがプロトコルバージョンとして TLSv1.1 を選択しないようにします。openssl バージョン 1.0.1 以降でのみ利用できます。

Added in version 3.4.

バージョン 3.7 で非推奨: The option is deprecated since OpenSSL 1.1.0.

ssl.OP_NO_TLSv1_2

TLSv1.2 接続が行われないようにします。このオプションは PROTOCOL_TLS と組み合わされている場合にのみ適用されます。ピアがプロトコルバージョンとして TLSv1.2 を選択しないようにします。openssl バージョン 1.0.1 以降でのみ利用できます。

Added in version 3.4.

バージョン 3.7 で非推奨: The option is deprecated since OpenSSL 1.1.0.

ssl.OP_NO_TLSv1_3

Prevents a TLSv1.3 connection. This option is only applicable in conjunction with PROTOCOL_TLS. It prevents the peers from choosing TLSv1.3 as the protocol version. TLS 1.3 is available with OpenSSL 1.1.1 or later. When Python has been compiled against an older version of OpenSSL, the flag defaults to 0.

Added in version 3.6.3.

バージョン 3.7 で非推奨: The option is deprecated since OpenSSL 1.1.0. It was added to 2.7.15 and 3.6.3 for backwards compatibility with OpenSSL 1.0.2.

ssl.OP_NO_RENEGOTIATION

Disable all renegotiation in TLSv1.2 and earlier. Do not send HelloRequest messages, and ignore renegotiation requests via ClientHello.

このオプションは OpenSSL 1.1.0h 以降のみで使用できます。

Added in version 3.7.

ssl.OP_CIPHER_SERVER_PREFERENCE

暗号の優先順位として、クライアントのものではなくサーバのものを使います。このオプションはクライアントソケットと SSLv2 のサーバソケットでは効果はありません。

Added in version 3.3.

ssl.OP_SINGLE_DH_USE

SSL セッションを区別するのに同じ DH 鍵を再利用しないようにします。これはセキュリティを向上させますが、より多くの計算機リソースを必要とします。このオプションはサーバソケットに適用されます。

Added in version 3.3.

ssl.OP_SINGLE_ECDH_USE

SSL セッションを区別するのに同じ ECDH 鍵を再利用しないようにします。これはセキュリティを向上させますが、より多くの計算機リソースを必要とします。このオプションはサーバソケットに適用されます。

Added in version 3.3.

ssl.OP_ENABLE_MIDDLEBOX_COMPAT

Send dummy Change Cipher Spec (CCS) messages in TLS 1.3 handshake to make a TLS 1.3 connection look more like a TLS 1.2 connection.

このオプションは OpenSSL 1.1.1 以降のみで使用できます。

Added in version 3.8.

ssl.OP_NO_COMPRESSION

SSL チャネルでの圧縮を無効にします。これはアプリケーションのプロトコルが自身の圧縮方法をサポートする場合に有用です。

Added in version 3.3.

class ssl.Options

OP_* 定数の enum.IntFlag コレクションです。

ssl.OP_NO_TICKET

クライアントサイドがセッションチケットをリクエストしないようにします。

Added in version 3.6.

ssl.OP_IGNORE_UNEXPECTED_EOF

Ignore unexpected shutdown of TLS connections.

このオプションは OpenSSL 3.0.0以降のみで使用できます。

Added in version 3.10.

ssl.OP_ENABLE_KTLS

Enable the use of the kernel TLS. To benefit from the feature, OpenSSL must have been compiled with support for it, and the negotiated cipher suites and extensions must be supported by it (a list of supported ones may vary by platform and kernel version).

Note that with enabled kernel TLS some cryptographic operations are performed by the kernel directly and not via any available OpenSSL Providers. This might be undesirable if, for example, the application requires all cryptographic operations to be performed by the FIPS provider.

このオプションは OpenSSL 3.0.0以降のみで使用できます。

Added in version 3.12.

ssl.OP_LEGACY_SERVER_CONNECT

Allow legacy insecure renegotiation between OpenSSL and unpatched servers only.

Added in version 3.12.

ssl.HAS_ALPN

OpenSSL ライブラリが、組み込みで RFC 7301 [https://datatracker.ietf.org/doc/html/rfc7301.html] で記述されている Application-Layer Protocol Negotiation TLS 拡張をサポートしているかどうか。

Added in version 3.5.

ssl.HAS_NEVER_CHECK_COMMON_NAME

Whether the OpenSSL library has built-in support not checking subject common name and SSLContext.hostname_checks_common_name is writeable.

Added in version 3.7.

ssl.HAS_ECDH

OpenSSL ライブラリが、組み込みの楕円曲線ディフィー・ヘルマン鍵共有をサポートしているかどうか。これは、ディストリビュータが明示的に無効にしていない限りは、真であるはずです。

Added in version 3.3.

ssl.HAS_SNI

OpenSSL ライブラリが、組み込みで (RFC 6066 [https://datatracker.ietf.org/doc/html/rfc6066.html] で記述されている) Server Name Indication 拡張をサポートしているかどうか。

Added in version 3.2.

ssl.HAS_NPN

OpenSSL ライブラリが、組み込みで、Application Layer Protocol Negotiation [https://en.wikipedia.org/wiki/Application-Layer_Protocol_Negotiation] で記述されている Next Protocol Negotiation をサポートしているかどうか。 true であれば、サポートしたいプロトコルを SSLContext.set_npn_protocols() メソッドで提示することができます。

Added in version 3.3.

ssl.HAS_SSLv2

OpenSSL ライブラリが、組み込みで SSL 2.0 プロトコルをサポートしているかどうか。

Added in version 3.7.

ssl.HAS_SSLv3

OpenSSL ライブラリが、組み込みで SSL 3.0 プロトコルをサポートしているかどうか。

Added in version 3.7.

ssl.HAS_TLSv1

OpenSSL ライブラリが、組み込みで TLS 1.0 プロトコルをサポートしているかどうか。

Added in version 3.7.

ssl.HAS_TLSv1_1

OpenSSL ライブラリが、組み込みで TLS 1.1 プロトコルをサポートしているかどうか。

Added in version 3.7.

ssl.HAS_TLSv1_2

OpenSSL ライブラリが、組み込みで TLS 1.2 プロトコルをサポートしているかどうか。

Added in version 3.7.

ssl.HAS_TLSv1_3

OpenSSL ライブラリが、組み込みで TLS 1.3 プロトコルをサポートしているかどうか。

Added in version 3.7.

ssl.CHANNEL_BINDING_TYPES

サポートされている TLS のチャネルバインディングのタイプのリスト。リスト内の文字列は SSLSocket.get_channel_binding() の引数に渡せます。

Added in version 3.3.

ssl.OPENSSL_VERSION

インタプリタによってロードされた OpenSSL ライブラリのバージョン文字列:

>>> ssl.OPENSSL_VERSION
'OpenSSL 1.0.2k  26 Jan 2017'

Added in version 3.2.

ssl.OPENSSL_VERSION_INFO

OpenSSL ライブラリのバージョン情報を表す5つの整数のタプル:

>>> ssl.OPENSSL_VERSION_INFO
(1, 0, 2, 11, 15)

Added in version 3.2.

ssl.OPENSSL_VERSION_NUMBER

1つの整数の形式の、 OpenSSL ライブラリの生のバージョン番号:

>>> ssl.OPENSSL_VERSION_NUMBER
268443839
>>> hex(ssl.OPENSSL_VERSION_NUMBER)
'0x100020bf'

Added in version 3.2.

ssl.ALERT_DESCRIPTION_HANDSHAKE_FAILURE

ssl.ALERT_DESCRIPTION_INTERNAL_ERROR

ALERT_DESCRIPTION_*

RFC 5246 [https://datatracker.ietf.org/doc/html/rfc5246.html] その他からのアラートの種類です。 IANA TLS Alert Registry [https://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-6] にはこのリストとその意味が定義された RFC へのリファレンスが含まれています。

SSLContext.set_servername_callback() でのコールバック関数の戻り値として使われます。

Added in version 3.4.

class ssl.AlertDescription

ALERT_DESCRIPTION_* 定数の enum.IntEnum コレクションです。

Added in version 3.6.

Purpose.SERVER_AUTH

create_default_context() と SSLContext.load_default_certs() に渡すオプションです。この値はコンテキストが web サーバの認証に使われることを示します (ですので、クライアントサイドのソケットを作るのに使うことになるでしょう)。

Added in version 3.4.

Purpose.CLIENT_AUTH

create_default_context() と SSLContext.load_default_certs() に渡すオプションです。この値はコンテキストが web クライアントの認証に使われることを示します (ですので、サーバサイドのソケットを作るのに使うことになるでしょう)。

Added in version 3.4.

class ssl.SSLErrorNumber

SSL_ERROR_* 定数の enum.IntEnum コレクションです。

Added in version 3.6.

class ssl.TLSVersion

enum.IntEnum collection of SSL and TLS versions for SSLContext.maximum_version and SSLContext.minimum_version.

Added in version 3.7.

TLSVersion.MINIMUM_SUPPORTED

TLSVersion.MAXIMUM_SUPPORTED

The minimum or maximum supported SSL or TLS version. These are magic constants. Their values don't reflect the lowest and highest available TLS/SSL versions.

TLSVersion.SSLv3

TLSVersion.TLSv1

TLSVersion.TLSv1_1

TLSVersion.TLSv1_2

TLSVersion.TLSv1_3

SSL 3.0 to TLS 1.3.

バージョン 3.10 で非推奨: All TLSVersion members except TLSVersion.TLSv1_2 and TLSVersion.TLSv1_3 are deprecated.

SSL ソケット

class ssl.SSLSocket(socket.socket)

SSL ソケットは socket オブジェクト の以下のメソッドを提供します:

accept()

bind()

close()

connect()

detach()

fileno()

getpeername(), getsockname()

getsockopt(), setsockopt()

gettimeout(), settimeout(), setblocking()

listen()

makefile()

recv(), recv_into() (非ゼロの flags は渡せません)

send(), sendall() (非ゼロの flags は渡せません)

sendfile() (ただし、 os.sendfile は平文ソケットにのみ使用されます。それ以外の場合には、 send() が使用されます。)

shutdown()

SSL(およびTLS)プロトコルは TCP の上に独自の枠組みを持っているので、SSLソケットの抽象化は、いくつかの点で通常の OSレベルのソケットの仕様から逸脱することがあります。特に ノンブロッキングソケットについての注釈 を参照してください。

SSLSocket のインスタンスは SSLContext.wrap_socket() メソッドを使用して作成されなければなりません。

バージョン 3.5 で変更: sendfile() メソッドが追加されました。

バージョン 3.5 で変更: shutdown() は、バイトが送受信されるたびにソケットのタイムアウトをリセットしません。ソケットのタイムアウトは、シャットダウンの最大合計時間になりました。

バージョン 3.6 で非推奨: SSLSocket インスタンスを直接作成することは非推奨です。ソケットをラップするために SSLContext.wrap_socket() を使用してください。

バージョン 3.7 で変更: SSLSocket instances must to created with wrap_socket(). In earlier versions, it was possible to create instances directly. This was never documented or officially supported.

バージョン 3.10 で変更: Python now uses SSL_read_ex and 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.

SSL ソケットには、以下に示す追加のメソッドと属性もあります:

SSLSocket.read(len=1024, buffer=None)

SSL ソケットからデータの len バイトまでを読み出し、読み出した結果を bytes インスタンスで返します。 buffer を指定すると、結果は代わりに buffer に読み込まれ、読み込んだバイト数を返します。

ソケットが non-blocking で読み出しがブロックすると、 SSLWantReadError もしくは SSLWantWriteError が送出されます。

再ネゴシエーションがいつでも可能なので、 read() の呼び出しは書き込み操作も引き起こしえます。

バージョン 3.5 で変更: ソケットのタイムアウトは、バイトが送受信されるたびにリセットされなくなりました。ソケットのタイムアウトは、最大 len バイトを読むのにかかる最大合計時間になりました。

バージョン 3.6 で非推奨: read() の代わりに recv() を使用してください。

SSLSocket.write(buf)

buf を SSL ソケットに書き込み、書き込んだバイト数を返します。 buf 引数はバッファインターフェイスをサポートするオブジェクトでなければなりません。

ソケットが non-blocking で書き込みがブロックすると、 SSLWantReadError もしくは SSLWantWriteError が送出されます。

再ネゴシエーションがいつでも可能なので、 write() の呼び出しは読み出し操作も引き起こしえます。

バージョン 3.5 で変更: ソケットのタイムアウトは、バイトが送受信されるたびにリセットされなくなりました。ソケットのタイムアウトは、buf を書き込むのにかかる最大合計時間になりました。

バージョン 3.6 で非推奨: write() の代わりに send() を使用してください。

注釈

read(), write() メソッドは下位レベルのメソッドであり、暗号化されていないアプリケーションレベルのデータを読み書きし、それを復号/暗号化して暗号化された書き込みレベルのデータにします。これらのメソッドはアクティブな SSL 接続つまり、ハンドシェイクが完了していて、 SSLSocket.unwrap() が呼ばれていないことを必要とします。

通常はこれらのメソッドの代わりに recv() や send() のようなソケット API メソッドを使うべきです。

SSLSocket.do_handshake()

SSL セットアップのハンドシェイクを実行します。

バージョン 3.4 で変更: ソケットの context の属性 check_hostname が真の場合に、ハンドシェイクメソッドが match_hostname() を実行するようになりました。

バージョン 3.5 で変更: ソケットのタイムアウトは、バイトが送受信されるたびにリセットされなくなりました。ソケットのタイムアウトは、ハンドシェイクにかかる最大合計時間になりました。

バージョン 3.7 で変更: Hostname or IP address is matched by OpenSSL during handshake. The function match_hostname() is no longer used. In case OpenSSL refuses a hostname or IP address, the handshake is aborted early and a TLS alert message is sent to the peer.

SSLSocket.getpeercert(binary_form=False)

接続先に証明書が無い場合、 None を返します。SSL ハンドシェイクがまだ行われていない場合は、 ValueError が送出されます。

binary_form が False で接続先から証明書を取得した場合、このメソッドは dict のインスタンスを返します。証明書が認証されていない場合、辞書は空です。証明書が認証されていた場合いくつかのキーを持った辞書を返し、 subject (証明書が発行された principal), issuer (証明書を発行した principal) を含みます。証明書が Subject Alternative Name 拡張(RFC 3280 [https://datatracker.ietf.org/doc/html/rfc3280.html] を参照)のインスタンスを格納していた場合、 subjectAltName キーも辞書に含まれます。

subject, issuer フィールドは、証明書のそれぞれのフィールドについてのデータ構造で与えられる RDN (relative distinguishued name) のシーケンスを格納したタプルで、各 RDN は name-value ペアのシーケンスです。現実世界での例をお見せします:

{'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}

binary_form 引数が True だった場合、証明書が渡されていればこのメソッドはDERエンコードされた証明書全体をバイト列として返し、接続先が証明書を提示しなかった場合は None を返します。接続先が証明書を提供するかどうかは SSL ソケットの役割に依存します:

クライアント SSL ソケットでは、認証が要求されているかどうかに関わらず、サーバは常に証明書を提供します。

サーバ SSL ソケットでは、クライアントはサーバによって認証が要求されている場合にのみ証明書を提供します。したがって、 (CERT_OPTIONAL や CERT_REQUIRED ではなく) CERT_NONE を使用した場合 getpeercert() は None を返します。

See also SSLContext.check_hostname.

バージョン 3.2 で変更: 返される辞書に issuer, notBefore のような追加アイテムを含むようになりました。

バージョン 3.4 で変更: ハンドシェイクが済んでいなければ ValueError を投げるようになりました。返される辞書に crlDistributionPoints, caIssuers, OCSP URI のような X509v3 拡張アイテムを含むようになりました。

バージョン 3.9 で変更: IPv6 address strings no longer have a trailing new line.

SSLSocket.cipher()

利用されている暗号の名前、その暗号の利用を定義しているSSLプロトコルのバージョン、利用されている鍵のbit長の3つの値を含むタプルを返します。もし接続が確立されていない場合、 None を返します。

SSLSocket.shared_ciphers()

クライアントとサーバーの両方で利用できる暗号方式のリストを返します。返されるリストの各要素は 3つの値を含むタプルで、その値はそれぞれ、暗号方式の名前、その暗号の利用を定義している SSL プロトコルのバージョン、暗号で使用される秘密鍵のビット長です。接続が確立されていないか、ソケットがクライアントソケットである場合、meth:~SSLSocket.shared_ciphers は None を返します。

Added in version 3.5.

SSLSocket.compression()

使われている圧縮アルゴリズムを文字列で返します。接続が圧縮されていなければ None を返します。

上位レベルのプロトコルが自身で圧縮メカニズムをサポートする場合、SSL レベルでの圧縮を OP_NO_COMPRESSION を使って無効にできます。

Added in version 3.3.

SSLSocket.get_channel_binding(cb_type='tls-unique')

現在の接続におけるチャネルバインディングのデータを取得します。未接続あるいはハンドシェイクが完了していなければ None を返します。

cb_type パラメータにより、望みのチャネルバインディングのタイプを選択できます。チャネルバインディングのタイプの妥当なものは CHANNEL_BINDING_TYPES でリストされています。現在のところは RFC 5929 [https://datatracker.ietf.org/doc/html/rfc5929.html] で定義されている 'tls-unique' のみがサポートされています。未サポートのチャネルバインディングのタイプが要求された場合、 ValueError を送出します。

Added in version 3.3.

SSLSocket.selected_alpn_protocol()

TLS ハンドシェイクで選択されたプロトコルを返します。 SSLContext.set_alpn_protocols() が呼ばれていない場合、相手側が ALPN をサポートしていない場合、クライアントが提案したプロトコルのどれもソケットがサポートしない場合、あるいはハンドシェイクがまだ行われていない場合には、 None が返されます。

Added in version 3.5.

SSLSocket.selected_npn_protocol()

TLS/SSL ハンドシェイクで選択された上位レベルのプロトコルを返します。 SSLContext.set_npn_protocols() が呼ばれていない場合、相手側が NPN をサポートしていない場合、あるいはハンドシェイクがまだ行われていない場合には、 None が返されます。

Added in version 3.3.

バージョン 3.10 で非推奨: NPN has been superseded by ALPN

SSLSocket.unwrap()

SSLシャットダウンハンドシェイクを実行します。これは下位レイヤーのソケットからTLSレイヤーを取り除き、下位レイヤーのソケットオブジェクトを返します。これは暗号化されたオペレーションから暗号化されていない接続に移行するときに利用されます。以降の通信には、オリジナルのソケットではなくこのメソッドが返したソケットのみを利用するべきです。

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 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 SSLError is raised.

注釈

Only available with OpenSSL 1.1.1 and TLS 1.3 enabled. Without TLS 1.3 support, the method raises NotImplementedError.

Added in version 3.8.

SSLSocket.version()

コネクションによって実際にネゴシエイトされた SSL プロトコルバージョンを文字列で、または、セキュアなコネクションが確立していなければ None を返します。これを書いている時点では、 "SSLv2", "SSLv3", "TLSv1", "TLSv1.1", "TLSv1.2" などが返ります。最新の OpenSSL はもっと色々な値を定義しているかもしれません。

Added in version 3.5.

SSLSocket.pending()

接続において既に復号済みで読み出し可能で保留になっているバイト列の数を返します。

SSLSocket.context

The SSLContext object this SSL socket is tied to.

Added in version 3.2.

SSLSocket.server_side

サーバサイドのソケットに対して True 、クライアントサイドのソケットに対して False となる真偽値です。

Added in version 3.2.

SSLSocket.server_hostname

サーバのホスト名: str 型、またはサーバサイドのソケットの場合とコンストラクタで hostname が指定されなかった場合は None

Added in version 3.2.

バージョン 3.7 で変更: The attribute is now always ASCII text. When server_hostname is an internationalized domain name (IDN), this attribute now stores the A-label form ("xn--pythn-mua.org"), rather than the U-label form ("pythön.org").

SSLSocket.session

この SSL 接続に対する SSLSession です。このセッションは、TLS ハンドシェイクの実行後、クライアントサイドとサーバサイドのソケットで使用できます。クライアントソケットでは、このセッションを do_handshake() が呼ばれる前に設定して、セッションを再利用できます。

Added in version 3.6.

SSLSocket.session_reused

Added in version 3.6.

SSL コンテキスト

Added in version 3.2.

SSL コンテキストは、SSL 構成オプション、証明書(群)や秘密鍵(群)などのような、一回の SSL 接続よりも長生きするさまざまなデータを保持します。これはサーバサイドソケットの SSL セッションのキャッシュも管理し、同じクライアントからの繰り返しの接続時の速度向上に一役買います。

class ssl.SSLContext(protocol=None)

Create a new SSL context. You may pass protocol which must be one of the 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 PROTOCOL_TLS; it provides the most compatibility with other versions.

次のテーブルは、どのクライアントのバージョンがどのサーバのバージョンに接続できるかを示しています:

client / server

SSLv2

SSLv3

TLS [3]

TLSv1

TLSv1.1

TLSv1.2

SSLv2

yes

no

no [1]

no

no

no

SSLv3

no

yes

no [2]

no

no

no

TLS (SSLv23) [3]

no [1]

no [2]

yes

yes

yes

yes

TLSv1

no

no

yes

yes

no

no

TLSv1.1

no

no

yes

no

yes

no

TLSv1.2

no

no

yes

no

no

yes

脚注

[1] (1,2)

SSLContext では、デフォルトで OP_NO_SSLv2 によりSSLv2 が無効になっています。

[2] (1,2)

SSLContext では、デフォルトで OP_NO_SSLv3 により SSLv3 が無効になっています。

[3] (1,2)

TLS 1.3 protocol will be available with PROTOCOL_TLS in OpenSSL >= 1.1.1. There is no dedicated PROTOCOL constant for just TLS 1.3.

参考

create_default_context() は ssl モジュールに、目的に合ったセキュリティ設定を選ばせます。

バージョン 3.6 で変更: The context is created with secure default values. The options OP_NO_COMPRESSION, OP_CIPHER_SERVER_PREFERENCE, OP_SINGLE_DH_USE, OP_SINGLE_ECDH_USE, OP_NO_SSLv2, and OP_NO_SSLv3 (except for PROTOCOL_SSLv3) are set by default. The initial cipher suite list contains only HIGH ciphers, no NULL ciphers and no MD5 ciphers.

バージョン 3.10 で非推奨: SSLContext without protocol argument is deprecated. The context class will either require PROTOCOL_TLS_CLIENT or 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. PROTOCOL_TLS, PROTOCOL_TLS_CLIENT, and PROTOCOL_TLS_SERVER use TLS 1.2 as minimum TLS version.

SSLContext オブジェクトは以下のメソッドと属性を持っています:

SSLContext.cert_store_stats()

ロードされた X.509 証明書の数、CA 証明書で活性の X.509 証明書の数、証明書失効リストの数、についての統計情報を辞書として取得します。

一つの CA と他の一つの証明書を持ったコンテキストでの例です:

>>> context.cert_store_stats()
{'crl': 0, 'x509_ca': 1, 'x509': 2}

Added in version 3.4.

SSLContext.load_cert_chain(certfile, keyfile=None, password=None)

秘密鍵と対応する証明書をロードします。 certfile は、証明書と、証明書認証で必要とされる任意の数の CA 証明書を含む、PEM フォーマットの単一ファイルへのパスでなければなりません。 keyfile 文字列を指定する場合、秘密鍵が含まれるファイルを指すものでなければなりません。指定しない場合、秘密鍵も certfile から取得されます。 certfile への証明書の格納についての詳細は、 証明書 の議論を参照してください。

password 引数に、秘密鍵を復号するためのパスワードを返す関数を与えることができます。その関数は秘密鍵が暗号化されていて、なおかつパスワードが必要な場合にのみ呼び出されます。その関数は引数なしで呼び出され、string, bytes, または bytearray を返さなければなりません。戻り値が string の場合は鍵を復号化するのに使う前に UTF-8 でエンコードされます。string の代わりに bytes や bytearray を返した場合は password 引数に直接供給されます。秘密鍵が暗号化されていなかったりパスワードを必要としない場合は、指定は無視されます。

password が与えられず、そしてパスワードが必要な場合には、OpenSSL 組み込みのパスワード問い合わせメカニズムが、ユーザに対話的にパスワードを問い合わせます。

秘密鍵が証明書に合致しなければ、 SSLError が送出されます。

バージョン 3.3 で変更: 新しいオプション引数 password。

SSLContext.load_default_certs(purpose=Purpose.SERVER_AUTH)

デフォルトの場所から "認証局" (CA=certification authority) 証明書ファイル一式をロードします。Windows では、CA 証明書はシステム記憶域の CA と ROOT からロードします。全てのシステムでは、この関数は SSLContext.set_default_verify_paths() を呼び出します。将来的にはこのメソッドは、他の場所からも CA 証明書をロードするかもしれません。

The purpose flag specifies what kind of CA certificates are loaded. The default settings Purpose.SERVER_AUTH loads certificates, that are flagged and trusted for TLS web server authentication (client side sockets). Purpose.CLIENT_AUTH loads CA certificates for client certificate verification on the server side.

Added in version 3.4.

SSLContext.load_verify_locations(cafile=None, capath=None, cadata=None)

verify_mode が CERT_NONE でない場合に接続先の証明書ファイルの正当性検証に使われる "認証局" (CA=certification authority) 証明書ファイル一式をロードします。少なくとも cafile か capath のどちらかは指定しなければなりません。

このメソッドは PEM または DER フォーマットの証明書失効リスト (CRLs=certification revocation lists)もロードできます。CRLs のために使うには、 SSLContext.verify_flags を適切に設定しなければなりません。

cafile を指定する場合は、PEM フォーマットで CA 証明書が結合されたファイルへのパスを指定してください。このファイル内で証明書をどのように編成すれば良いのかについての詳しい情報については、 証明書 の議論を参照してください。

capath を指定する場合は、PEM フォーマットの CA 証明書が含まれる、 OpenSSL specific layout [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_load_verify_locations.html] に従ったディレクトリへのパスを指定してください。

cadata オブジェクトを指定する場合は、PEM エンコードの証明書一つ以上の ASCII 文字列か、DER エンコードの証明書の bytes-like object オブジェクトのどちらかを指定してください。PEM エンコードの証明書の周囲の余分な行は無視されますが、少なくとも一つの証明書が含まれている必要があります。

バージョン 3.4 で変更: 新しいオプション引数 cadata 。

SSLContext.get_ca_certs(binary_form=False)

ロードされた "認証局" (CA=certification authority) 証明書のリストを取得します。 binary_form 引数が False である場合、リストのそれぞれのエントリは SSLSocket.getpeercert() が出力するような辞書になります。True である場合、このメソッドは、DER エンコード形式の証明書のリストを返します。返却されるリストには、 SSL 接続によって証明書がリクエストおよびロードされない限り、 capath からの証明書は含まれません。

注釈

capath ディレクトリ内の証明書は一度でも使われない限りはロードされません。

Added in version 3.4.

SSLContext.get_ciphers()

有効な暗号化のリストを取得します。リストは暗号化優先度順に並びます。SSLContext.set_ciphers() を参照してください。

以下はプログラム例です:

>>> 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'}]

Added in version 3.6.

SSLContext.set_default_verify_paths()

デフォルトの "認証局" (CA=certification authority) 証明書を、OpenSSL ライブラリがビルドされた際に定義されたファイルシステム上のパスからロードします。残念ながらこのメソッドが成功したかどうかを知るための簡単な方法はありません: 証明書が見つからなくてもエラーは返りません。OpenSSL ライブラリがオペレーティングシステムの一部として提供されている際にはどうやら適切に構成できるようですが。

SSLContext.set_ciphers(ciphers)

このコンテキストによって作られるソケットで利用できる暗号を設定します。 OpenSSL cipher list format [https://www.openssl.org/docs/manmaster/man1/ciphers.html] に書かれている形式の文字列でなければなりません。 (OpenSSL のコンパイル時オプションや他の設定がそれらすべての暗号の使用を禁止しているなどの理由で) どの暗号も選べない場合、 SSLError が送出されます。

注釈

接続時に SSL ソケットの SSLSocket.cipher() メソッドが、現在選択されているその暗号を使います。

TLS 1.3 cipher suites cannot be disabled with set_ciphers().

SSLContext.set_alpn_protocols(protocols)

SSL/TLS ハンドシェイク時にソケットが提示すべきプロトコルを指定します。 ['http/1.1', 'spdy/2'] のような推奨順に並べた ASCII 文字列のリストでなければなりません。プロトコルの選択は RFC 7301 [https://datatracker.ietf.org/doc/html/rfc7301.html] に従いハンドシェイク中に行われます。ハンドシェイクが正常に終了した後、 SSLSocket.selected_alpn_protocol() メソッドは合意されたプロトコルを返します。

このメソッドは HAS_ALPN が False の場合 NotImplementedError を送出します。

Added in version 3.5.

SSLContext.set_npn_protocols(protocols)

SSL/TLS ハンドシェイク時にソケットが提示すべきプロトコルを指定します。 ['http/1.1', 'spdy/2'] のような推奨順に並べた文字列のリストでなければなりません。プロトコルの選択は Application Layer Protocol Negotiation [https://en.wikipedia.org/wiki/Application-Layer_Protocol_Negotiation] に従いハンドシェイク中に行われます。ハンドシェイクが正常に終了した後、 SSLSocket.selected_alpn_protocol() メソッドは合意されたプロトコルを返します。

このメソッドは HAS_NPN が False の場合 NotImplementedError を送出します。

Added in version 3.3.

バージョン 3.10 で非推奨: NPN has been superseded by ALPN

SSLContext.sni_callback

TLS クライアントがサーバ名表示を指定した際の、SSL/TLS サーバによって TLS Client Hello ハンドシェイクメッセージが受け取られたあとで呼び出されるコールバック関数を登録します。サーバ名表示メカニズムは RFC 6066 [https://datatracker.ietf.org/doc/html/rfc6066.html] セクション 3 - Server Name Indication で述べられています。

SSLContext ごとに一つだけコールバックをセットできます。 sni_callback を None にすればコールバックは無効になります。この関数を続けて呼ぶと、以前に登録されたコールバックを上書きします。

The callback function will be called with three arguments; the first being the ssl.SSLSocket, the second is a string that represents the server name that the client is intending to communicate (or None if the TLS Client Hello does not contain a server name) and the third argument is the original SSLContext. The server name argument is text. For internationalized domain name, the server name is an IDN A-label ("xn--pythn-mua.org").

このコールバックの典型的な利用方法は、 ssl.SSLSocket の SSLSocket.context 属性を、サーバ名に合致する証明書チェインを持つ新しい SSLContext オブジェクトに変更することです。

Due to the early negotiation phase of the TLS connection, only limited methods and attributes are usable like SSLSocket.selected_alpn_protocol() and SSLSocket.context. The SSLSocket.getpeercert(), SSLSocket.cipher() and 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.

TLS ネゴシエーションを継続させるならば、 sni_callback 関数は None を返さなければなりません。TLS が失敗することを必要とするなら、 constant ALERT_DESCRIPTION_* を返してください。ここにない値を返すと、致命エラー ALERT_DESCRIPTION_INTERNAL_ERROR を引き起こします。

sni_callback 関数が例外を送出した場合、TLS 接続は TLS の致命的アラートメッセージ ALERT_DESCRIPTION_HANDSHAKE_FAILURE とともに終了します。

このメソッドは OpenSSL ライブラリが OPENSSL_NO_TLSEXT を定義してビルドされている場合、 NotImplementedError を送出します。

Added in version 3.7.

SSLContext.set_servername_callback(server_name_callback)

This is a legacy API retained for backwards compatibility. When possible, you should use 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 ("pythön.org").

サーバ名に対するデコードエラーがあれば、TLS 接続はクライアントに対する TLS の致命的アラートメッセージ ALERT_DESCRIPTION_INTERNAL_ERROR とともに終了します。

Added in version 3.4.

SSLContext.load_dh_params(dhfile)

ディフィー・ヘルマン(DH)鍵交換のための鍵生成パラメータをロードします。DH 鍵交換を用いることは、(サーバ、クライアントともに)計算機リソースに高い処理負荷をかけますがセキュリティを向上させます。 dhfile パラメータは PEM フォーマットの DH パラメータを含んだファイルへのパスでなければなりません。

この設定はクライアントソケットには適用されません。さらにセキュリティを改善するのに OP_SINGLE_DH_USE オプションも利用できます。

Added in version 3.3.

SSLContext.set_ecdh_curve(curve_name)

楕円曲線ディフィー・ヘルマン(ECDH)鍵交換の曲線名を指定します。ECDH はもとの DH に較べて、ほぼ間違いなく同程度に安全である一方で、顕著に高速です。 curve_name パラメータは既知の楕円曲線を表す文字列でなければなりません。例えば prime256v1 が広くサポートされている曲線です。

この設定はクライアントソケットには適用されません。さらにセキュリティを改善するのに OP_SINGLE_ECDH_USE オプションも利用できます。

このメソッドは HAS_ECDH が False の場合は利用できません。

Added in version 3.3.

参考

SSL/TLS & Perfect Forward Secrecy [https://vincent.bernat.ch/en/blog/2011-ssl-perfect-forward-secrecy]

Vincent Bernat.

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 SSLContext.sslsocket_class (default SSLSocket). The returned SSL socket is tied to the context, its settings and certificates. sock must be a SOCK_STREAM socket; other socket types are unsupported.

server_side 引数は真偽値で、このソケットがサーバサイドとクライアントサイドのどちらの動作をするのかを指定します。

クライアントサイドソケットにおいて、コンテキストの生成は遅延されます。つまり、低レイヤのソケットがまだ接続されていない場合、コンテキストの生成はそのソケットの connect() メソッドが呼ばれた後に行われます。サーバサイドソケットの場合、そのソケットに接続先が居なければそれは listen 用ソケットだと判断されます。 accept() メソッドで生成されるクライアント接続に対してのサーバサイド SSLラップは自動的に行われます。メソッドは SSLError を送出することがあります。

クライアントからの接続では、 server_hostname で接続先サービスのホスト名を指定できます。これは HTTP バーチャルホストにかなり似て、シングルサーバで複数の SSL ベースのサービスを別々の証明書でホストしているようなサーバに対して使えます。 server_side が True の場合に server_hostname を指定すると ValueError を送出します。

do_handshake_on_connect 引数は、 socket.connect() の後に自動的に SSLハンドシェイクを行うか、それともアプリケーションが明示的に SSLSocket.do_handshake() メソッドを実行するかを指定します。 SSLSocket.do_handshake() を明示的に呼びだすことで、ハンドシェイクによるソケットI/Oのブロッキング動作を制御できます。

suppress_ragged_eofs 引数は、 SSLSocket.recv() メソッドが、接続先から予期しないEOF を受け取った時に通知する方法を指定します。 True (デフォルト) の場合、下位のソケットレイヤーから予期せぬEOFエラーが来た場合、通常のEOF (空のバイト列オブジェクト)を返します。 False の場合、呼び出し元に例外を投げて通知します。

session, session を参照してください。

To wrap an SSLSocket in another SSLSocket, use SSLContext.wrap_bio().

バージョン 3.5 で変更: OpenSSL が SNI をサポートしなくても server_hostname を許容するようになりました。

バージョン 3.6 で変更: session 引数が追加されました。

バージョン 3.7 で変更: The method returns an instance of SSLContext.sslsocket_class instead of hard-coded SSLSocket.

SSLContext.sslsocket_class

The return type of SSLContext.wrap_socket(), defaults to SSLSocket. The attribute can be overridden on instance of class in order to return a custom subclass of SSLSocket.

Added in version 3.7.

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 SSLContext.sslobject_class (default SSLObject). The SSL routines will read input data from the incoming BIO and write data to the outgoing BIO.

server_side、 server_hostname 、 session 引数は、 SSLContext.wrap_socket() での意味と同じ意味を持ちます。

バージョン 3.6 で変更: session 引数が追加されました。

バージョン 3.7 で変更: The method returns an instance of SSLContext.sslobject_class instead of hard-coded SSLObject.

SSLContext.sslobject_class

The return type of SSLContext.wrap_bio(), defaults to SSLObject. The attribute can be overridden on instance of class in order to return a custom subclass of SSLObject.

Added in version 3.7.

SSLContext.session_stats()

このコンテキストによって作られた、または管理されている SSL セッションについての統計情報を取得します。 piece of information [https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_sess_number.html] のそれぞれの名前にそれらが持つ数値をマッピングした辞書を返します。例えば、以下は、コンテキスト作成以降のセッションキャッシュのキャッシュヒットとキャッシュミスの総計です。

>>> stats = context.session_stats()
>>> stats['hits'], stats['misses']
(0, 0)

SSLContext.check_hostname

Whether to match the peer cert's hostname in SSLSocket.do_handshake(). The context's verify_mode must be set to CERT_OPTIONAL or CERT_REQUIRED, and you must pass server_hostname to wrap_socket() in order to match the hostname. Enabling hostname checking automatically sets verify_mode from CERT_NONE to CERT_REQUIRED. It cannot be set back to CERT_NONE as long as hostname checking is enabled. The PROTOCOL_TLS_CLIENT protocol enables hostname checking by default. With other protocols, hostname checking must be enabled explicitly.

以下はプログラム例です:

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

Added in version 3.4.

バージョン 3.7 で変更: verify_mode is now automatically changed to CERT_REQUIRED when hostname checking is enabled and verify_mode is CERT_NONE. Previously the same operation would have failed with a ValueError.

SSLContext.keylog_filename

Write TLS keys to a keylog file, whenever key material is generated or received. The keylog file is designed for debugging purposes only. The file format is specified by NSS and used by many traffic analyzers such as Wireshark. The log file is opened in append-only mode. Writes are synchronized between threads, but not between processes.

Added in version 3.8.

SSLContext.maximum_version

A TLSVersion enum member representing the highest supported TLS version. The value defaults to TLSVersion.MAXIMUM_SUPPORTED. The attribute is read-only for protocols other than PROTOCOL_TLS, PROTOCOL_TLS_CLIENT, and PROTOCOL_TLS_SERVER.

The attributes maximum_version, minimum_version and 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 OP_NO_TLSv1_2 in options and maximum_version set to TLSVersion.TLSv1_2 will not be able to establish a TLS 1.2 connection.

Added in version 3.7.

SSLContext.minimum_version

Like SSLContext.maximum_version except it is the lowest supported version or TLSVersion.MINIMUM_SUPPORTED.

Added in version 3.7.

SSLContext.num_tickets

Control the number of TLS 1.3 session tickets of a PROTOCOL_TLS_SERVER context. The setting has no impact on TLS 1.0 to 1.2 connections.

Added in version 3.8.

SSLContext.options

このコンテキストで有効になっている SSL オプションを表す整数。デフォルトの値は OP_ALL ですが、 OP_NO_SSLv2 のような他の値をビット OR 演算で指定できます。

バージョン 3.6 で変更: SSLContext.options は次のように Options のフラグを返します。

>>> ssl.create_default_context().options
<Options.OP_ALL|OP_NO_SSLv3|OP_NO_SSLv2|OP_NO_COMPRESSION: 2197947391>

バージョン 3.7 で非推奨: All OP_NO_SSL* and OP_NO_TLS* options have been deprecated since Python 3.7. Use SSLContext.minimum_version and SSLContext.maximum_version instead.

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, SSLContext.verify_mode must be set to CERT_OPTIONAL or CERT_REQUIRED, too. The actual client cert exchange is delayed until SSLSocket.verify_client_post_handshake() is called and some I/O is performed.

Added in version 3.8.

SSLContext.protocol

コンテキストの構築時に選択されたプロトコルバージョン。この属性は読み出し専用です。

SSLContext.hostname_checks_common_name

Whether check_hostname falls back to verify the cert's subject common name in the absence of a subject alternative name extension (default: true).

Added in version 3.7.

バージョン 3.10 で変更: The flag had no effect with OpenSSL before version 1.1.1l. Python 3.8.9, 3.9.3, and 3.10 include workarounds for previous versions.

SSLContext.security_level

An integer representing the security level [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_get_security_level.html] for the context. This attribute is read-only.

Added in version 3.10.

SSLContext.verify_flags

証明書の検証操作のためのフラグです。 VERIFY_CRL_CHECK_LEAF などのフラグをビット OR 演算でセットできます。デフォルトでは OpenSSL は証明書失効リスト (CRLs) を必要としませんし検証にも使いません。

Added in version 3.4.

バージョン 3.6 で変更: SSLContext.verify_flags は次のように VerifyFlags のフラグを返します。

>>> ssl.create_default_context().verify_flags
<VerifyFlags.VERIFY_X509_TRUSTED_FIRST: 32768>

SSLContext.verify_mode

接続先の証明書の検証を試みるかどうか、また、検証が失敗した場合にどのように振舞うべきかを制御します。この属性は CERT_NONE, CERT_OPTIONAL, CERT_REQUIRED のうちどれか一つでなければなりません。

バージョン 3.6 で変更: SSLContext.verify_mode は次のように VerifyMode enum (列挙) を返します。

>>> ssl.create_default_context().verify_mode
<VerifyMode.CERT_REQUIRED: 2>

証明書

証明書を大まかに説明すると、公開鍵/秘密鍵システムの一種です。このシステムでは、各 principal (これはマシン、人、組織などです) は、ユニークな2つの暗号鍵を割り当てられます。1つは公開され、 公開鍵(public key) と呼ばれます。もう一方は秘密にされ、 秘密鍵(private key) と呼ばれます。 2つの鍵は関連しており、片方の鍵で暗号化したメッセージは、もう片方の鍵 のみ で復号できます。

証明書は2つの principal の情報を含んでいます。証明書は subject 名とその公開鍵を含んでいます。また、もう一つの principal である 発行者(issuer) からの、 subject が本人であることと、その公開鍵が正しいことの宣言(statement)を含んでいます。発行者からの宣言は、その発行者の秘密鍵で署名されています。発行者の秘密鍵は発行者しか知りませんが、誰もがその発行者の公開鍵を利用して宣言を復号し、証明書内の別の情報と比較することで認証することができます。証明書はまた、その証明書が有効である期限に関する情報も含んでいます。この期限は "notBefore" と "notAfter" と呼ばれる2つのフィールドで表現されています。

Python において証明書を利用する場合、クライアントもサーバーも自分を証明するために証明書を利用することができます。ネットワーク接続の相手側に証明書の提示を要求する事ができ、そのクライアントやサーバーが認証を必要とするならその証明書を認証することができます。認証が失敗した場合、接続は例外を発生させます。認証は下位層のOpenSSLフレームワークが自動的に行います。アプリケーションは認証機構について意識する必要はありません。しかし、アプリケーションは認証プロセスのために幾つかの証明書を提供する必要があるかもしれません。

Python は証明書を格納したファイルを利用します。そのファイルは "PEM" (RFC 1422 [https://datatracker.ietf.org/doc/html/rfc1422.html] 参照) フォーマットという、ヘッダー行とフッター行の間にbase-64エンコードされた形をとっている必要があります。

-----BEGIN CERTIFICATE-----
... (certificate in base64 PEM encoding) ...
-----END CERTIFICATE-----

証明書チェイン

Pythonが利用する証明書を格納したファイルは、ときには 証明書チェイン(certificate chain) と呼ばれる証明書のシーケンスを格納します。このチェインの先頭には、まずクライアントやサーバーである principal の証明書を置き、それ以降には、その証明書の発行者(issuer)の証明書などを続け、最後に証明対象(subject)と発行者が同じ 自己署名(self-signed) 証明書で終わります。この最後の証明書は ルート証明書(root certificate と呼ばれます。これらの証明書チェインは単純に1つの証明書ファイルに結合してください。例えば、3つの証明書からなる証明書チェインがある場合、私たちのサーバーの証明書から、私たちのサーバーに署名した認証局の証明書、そして認証局の証明書を発行した機関のルート証明書と続きます:

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

CA 証明書

もし相手から送られてきた証明書の認証をしたい場合、信頼している各発行者の証明書チェインが入った "CA certs" ファイルを提供する必要があります。繰り返しますが、このファイルは単純に、各チェインを結合しただけのものです。認証のために、Pythonはそのファイルの中の最初にマッチしたチェインを利用します。SSLContext.load_default_certs() を呼び出すことでプラットフォームの証明書ファイルも使われますが、これは create_default_context() によって自動的に行われます。

秘密鍵と証明書の組み合わせ

Often the private key is stored in the same file as the certificate; in this case, only the certfile parameter to 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:

-----BEGIN RSA PRIVATE KEY-----
... (private key in base64 encoding) ...
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
... (certificate in base64 PEM encoding) ...
-----END CERTIFICATE-----

自己署名証明書

SSL暗号化接続サービスを提供するサーバーを建てる場合、適切な証明書を取得するには、認証局から買うなどの幾つかの方法があります。また、自己署名証明書を作るケースもあります。 OpenSSLを使って自己署名証明書を作るには、次のようにします。

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

自己署名証明書の欠点は、それ自身がルート証明書であり、他の人はその証明書を持っていない (そして信頼しない)ことです。

使用例

SSLサポートをテストする

インストールされているPythonがSSLをサポートしているかどうかをテストするために、ユーザーコードは次のイディオムを利用することができます。

try:
    import ssl
except ImportError:
    pass
else:
    ...  # do something that requires SSL support

クライアントサイドの処理

この例では、自動的に証明書の検証を行うことを含む望ましいセキュリティ設定でクライアントソケットの SSL コンテキストを作ります:

>>> context = ssl.create_default_context()

自分自身でセキュリティ設定を調整したい場合、コンテキストを一から作ることはできます (ただし、正しくない設定をしてしまいがちなことに注意してください):

>>> context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
>>> context.load_verify_locations("/etc/ssl/certs/ca-bundle.crt")

(このスニペットはすべての CA 証明書が /etc/ssl/certs/ca-bundle.crt にバンドルされていることを仮定しています; もし違っていればエラーになりますので、適宜修正してください)

The PROTOCOL_TLS_CLIENT protocol configures the context for cert validation and hostname verification. verify_mode is set to CERT_REQUIRED and check_hostname is set to True. All other protocols create SSL contexts with insecure defaults.

When you use the context to connect to a server, CERT_REQUIRED and 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:

>>> conn = context.wrap_socket(socket.socket(socket.AF_INET),
...                            server_hostname="www.python.org")
>>> conn.connect(("www.python.org", 443))

そして証明書を持ってくることができます:

>>> cert = conn.getpeercert()

証明書が、期待しているサービス (つまり、 HTTPS ホスト www.python.org) の身元を特定していることを視覚的に点検してみましょう:

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

SSL チャネルは今や確立されて証明書が検証されているので、サーバとのお喋りを続けることができます:

>>> 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'',
 b'']

このドキュメントの下の方の、 セキュリティで考慮すべき点 に関する議論を参照してください。

サーバサイドの処理

サーバサイドの処理では、通常、サーバー証明書と秘密鍵がそれぞれファイルに格納された形で必要です。最初に秘密鍵と証明書が保持されたコンテキストを作成し、クライアントがあなたの信憑性をチェックできるようにします。そののちにソケットを開き、ポートにバインドし、そのソケットの listen() を呼び、クライアントからの接続を待ちます。

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)

クライアントが接続してきた場合、 accept() を呼んで新しいソケットを作成し、接続のためにサーバサイドの SSL ソケットを、コンテキストの SSLContext.wrap_socket() メソッドで作ります:

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()

そして、 connstream からデータを読み、クライアントと切断する(あるいはクライアントが切断してくる)まで何か処理をします。

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

そして新しいクライアント接続のために listen に戻ります。 (もちろん現実のサーバは、おそらく個々のクライアント接続ごとに別のスレッドで処理するか、ソケットを ノンブロッキングモード にし、イベントループを使うでしょう。)

ノンブロッキングソケットについての注意事項

SSL ソケットはノンブロッキングモードにおいては、普通のソケットとは少し違った振る舞いをします。ですのでノンブロッキングソケットとともに使う場合、いくつか気をつけなければならない事項があります:

ほとんどの SSLSocket のメソッドは I/O 操作がブロックすると BlockingIOError ではなく SSLWantWriteError か SSLWantReadError のどちらかを送出します。 SSLWantReadError は下層のソケットで読み出しが必要な場合に送出され、 SSLWantWriteError は下層のソケットで書き込みが必要な場合に送出されます。SSL ソケットに対して 書き込み を試みると下層のソケットから最初に 読み出す 必要があるかもしれず、SSL ソケットに対して 読み出し を試みると下層のソケットに先に 書き込む 必要があるかもしれないことに注意してください。

バージョン 3.5 で変更: 以前の Python バージョンでは、 SSLSocket.send() メソッドは SSLWantWriteError または SSLWantReadError を送出するのではなく、ゼロを返していました。

select() 呼び出しは OS レベルでのソケットが読み出し可能(または書き込み可能)になったことを教えてくれますが、上位の SSL レイヤーでの十分なデータがあることを意味するわけではありません。例えば、SSL フレームの一部が届いただけかもしれません。ですから、 SSLSocket.recv() と SSLSocket.send() の失敗を処理することに備え、ほかの select() 呼び出し後にリトライしなければなりません。

反対に、SSL レイヤーは独自の枠組みを持っているため、select() が気付かない読み出し可能なデータを SSL ソケットが持っている場合があります。したがって、入手可能な可能性のあるデータをすべて引き出すために最初に SSLSocket.recv() を呼び出し、次にそれでもまだ必要な場合にだけ select() 呼び出しでブロックすべきです。

(当然のことながら、ほかのプリミティブ、例えば poll() や selectors モジュール内のものを使う際にも似た但し書きが付きます)

SSL ハンドシェイクそのものがノンブロッキングになります: SSLSocket.do_handshake() メソッドは成功するまでリトライしなければなりません。 select() を用いてソケットの準備が整うのを待つためには、およそ以下のようにします:

while True:
    try:
        sock.do_handshake()
        break
    except ssl.SSLWantReadError:
        select.select([sock], [], [])
    except ssl.SSLWantWriteError:
        select.select([], [sock], [])

参考

asyncio モジュールは ノンブロッキング SSL ソケット をサポートし、より高いレベルの API を提供しています。 selectors モジュールを使ってイベントを poll し、 SSLWantWriteError, SSLWantReadError, BlockingIOError 例外を処理します。SSL ハンドシェイクも非同期に実行します。

メモリ BIO サポート

Added in version 3.5.

Python 2.6 で SSL モジュールが導入されて以降、SSLSocket クラスは、以下の互いに関連するが別々の機能を提供してきました。

SSL プロトコル処理

ネットワーク IO

ネットワーク IO API は、socket.socket が提供するものと同じです。SSLSocket も、そのクラスから継承しています。これにより、SSL ソケットは標準のソケットをそっくりそのまま置き換えるものとして使用できるため、既存のアプリケーションを SSL に対応させるのが非常に簡単になります。

SSL プロトコルの処理とネットワーク IO を組み合わせた場合、通常は問題なく動作しますが、問題が発生する場合があります。一例を挙げると、非同期 IO フレームワークが別の多重化モデルを使用する場合、これは socket.socket と内部 OpenSSL ソケット IO ルーティンが想定する「ファイル記述子上の select/poll」モデル（準備状態ベース）とは異なります。これは、このモデルが非効率的になる Windows などのプラットフォームに主に該当します。そのため、スコープを限定した SSLSocket の変種、 SSLObject が提供されています。

class ssl.SSLObject

ネットワーク IO メソッドを含まない SSL プロトコルインスタンスを表す、スコープを限定した SSLSocket の変種です。一般的にこ、のクラスを使用するのは、メモリバッファを通じて SSL のための非同期 IO を実装するフレームワーク作成者です。

このクラスは、OpenSSL が実装する低水準 SSL オブジェクトの上にインターフェースを実装します。このオブジェクトは SSL 接続の状態をキャプチャしますが、ネットワーク IO 自体は提供しません。IO は、OpenSSL の IO 抽象レイヤである別の「BIO」オブジェクトを通じて実行する必要があります。

このクラスには公開されたコンストラクタがありません。SSLObject インスタンスは、 wrap_bio() メソッドを使用して作成しなければなりません。このメソッドは、SSLObject インスタンスを作成し、2 つの BIO に束縛します。incoming BIO は、Python から SSL プロトコルインスタンスにデータを渡すために使用され、outgoing BIO は、データを反対向きに渡すために使用されます。

次のメソッドがサポートされています:

context

server_side

server_hostname

session

session_reused

read()

write()

getpeercert()

selected_alpn_protocol()

selected_npn_protocol()

cipher()

shared_ciphers()

compression()

pending()

do_handshake()

verify_client_post_handshake()

unwrap()

get_channel_binding()

version()

SSLSocket と比較すると、このオブジェクトでは以下の機能が不足しています。

Any form of network IO; recv() and send() read and write only to the underlying MemoryBIO buffers.

do_handshake_on_connect 機構はありません。必ず手動で do_handshake() を呼んで、ハンドシェイクを開始する必要があります。

suppress_ragged_eofs は処理されません。プロトコルに違反するファイル末尾状態は、 SSLEOFError 例外を通じて報告されます。

unwrap() メソッドの呼び出しは、下層のソケットを返す SSL ソケットとは異なり、何も返しません。

SSLContext.set_servername_callback() に渡される server_name_callback コールバックは、1 つ目の引数として SSLSocket インスタンスではなく SSLObject インスタンスを受け取ります。

SSLObject の使用に関する注意:

SSLObject 上のすべての IO は non-blocking です。例えば、read() は入力 BIO が持つデータよりも多くのデータを必要とする場合、SSLWantReadError を送出します。

バージョン 3.7 で変更: SSLObject instances must be created with wrap_bio(). In earlier versions, it was possible to create instances directly. This was never documented or officially supported.

SSLObject は、メモリバッファを使用して外界と通信します。MemoryBIO クラスは、以下のように OpenSSL メモリ BIO (Basic IO) オブジェクトをラップし、この目的に使用できるメモリバッファを提供します。

class ssl.MemoryBIO

Python と SSL プロトコルインスタンス間でデータをやり取りするために使用できるメモリバッファ。

pending

現在メモリバッファ中にあるバイト数を返します。

eof

メモリ BIOが現在ファイルの末尾にあるかを表す真偽値です。

read(n=-1)

メモリバッファから最大 n 読み取ります。n が指定されていないか、負値の場合、すべてのバイトが返されます。

write(buf)

buf からメモリ BIO にバイトを書き込みます。buf 引数は、バッファプロトコルをサポートするオブジェクトでなければなりません。

戻り値は、書き込まれるバイト数であり、常に buf の長さと等しくなります。

write_eof()

EOF マーカーをメモリ BIO に書き込みます。このメソッドが呼び出された後に write() を呼ぶことはできません。eof 属性は、バッファ内のすべてのデータが読み出された後に True になります。

SSL セッション

Added in version 3.6.

class ssl.SSLSession

session が使用するセッションオブジェクトです。

id

time

timeout

ticket_lifetime_hint

has_ticket

セキュリティで考慮すべき点

最善のデフォルト値

クライアントでの使用 では、セキュリティポリシーによる特殊な要件がない限りは、 create_default_context() 関数を使用して SSL コンテキストを作成することを強くお勧めします。この関数は、システムの信頼済み CA 証明書をロードし、証明書の検証とホスト名のチェックを有効化し、十分にセキュアなプロトコルと暗号を選択しようとします。

例として、 smtplib.SMTP クラスを使用して SMTP サーバーに対して信頼できるセキュアな接続を行う方法を以下に示します:

>>> 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')

接続にクライアントの証明書が必要な場合、 SSLContext.load_cert_chain() によって追加できます。

対照的に、自分自身で SSLContext クラスのコンストラクタを呼び出すことによって SSL コンテキストを作ると、デフォルトでは証明書検証もホスト名チェックも有効になりません。自分で設定を行う場合は、十分なセキュリティレベルを達成するために、以下のパラグラフをお読みください。

手動での設定

証明書の検証

When calling the SSLContext constructor directly, CERT_NONE is the default. Since it does not authenticate the other peer, it can be insecure, especially in client mode where most of 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 CERT_REQUIRED. However, it is in itself not sufficient; you also have to check that the server certificate, which can be obtained by calling 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 SSLContext.check_hostname is enabled.

バージョン 3.7 で変更: Hostname matchings is now performed by OpenSSL. Python no longer uses match_hostname().

サーバモードにおいて、(より上位のレベルでの認証メカニズムではなく) SSL レイヤーを使ってあなたのクライアントを認証したいならば、 CERT_REQUIRED を指定して同じようにクライアントの証明書を検証すべきでしょう。

プロトコルのバージョン

SSL バージョン 2 と 3 は安全性に欠けると考えられており、使用するのは危険です。クライアントとサーバ間の互換性を最大限に確保したい場合、プロトコルバージョンとして PROTOCOL_TLS_CLIENT または PROTOCOL_TLS_SERVER を使用してください。 SSLv2 と SSLv3 はデフォルトで無効になっています。

>>> client_context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
>>> client_context.minimum_version = ssl.TLSVersion.TLSv1_3
>>> client_context.maximum_version = ssl.TLSVersion.TLSv1_3

The SSL context created above will only allow TLSv1.3 and later (if supported by your system) connections to a server. PROTOCOL_TLS_CLIENT implies certificate validation and hostname checks by default. You have to load certificates into the context.

暗号の選択

高度なセキュリティが要求されている場合、SSL セッションのネゴシエーションで有効になる暗号の微調整が SSLContext.set_ciphers() によって可能です。Python 3.2.3 以降、 ssl モジュールではデフォルトで特定の弱い暗号化が無効になっていますが、暗号方式の選択をさらに厳しく制限したい場合もあるでしょう。OpenSSL ドキュメントの cipher list format [https://www.openssl.org/docs/man1.1.1/man1/ciphers.html#CIPHER-LIST-FORMAT] を注意深く読んでください。与えられた暗号方式リストによって有効になる暗号方式をチェックするには、SSLContext.get_ciphers() メソッドまたは openssl ciphers コマンドをシステム上で実行してください。

マルチプロセス化

If using this module as part of a multi-processed application (using, for example the multiprocessing or 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 os.fork(). Any successful call of RAND_add() or RAND_bytes() is sufficient.

TLS 1.3

Added in version 3.7.

The TLS 1.3 protocol behaves slightly differently than previous version of TLS/SSL. Some new TLS 1.3 features are not yet available.

TLS 1.3 uses a disjunct set of cipher suites. All AES-GCM and ChaCha20 cipher suites are enabled by default. The method SSLContext.set_ciphers() cannot enable or disable any TLS 1.3 ciphers yet, but SSLContext.get_ciphers() returns them.

Session tickets are no longer sent as part of the initial handshake and are handled differently. SSLSocket.session and SSLSession are not compatible with TLS 1.3.

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.

TLS 1.3 features like early data, deferred TLS client cert request, signature algorithm configuration, and rekeying are not supported yet.

参考

socket.socket クラス

下位レイヤーの socket クラスのドキュメント

SSL/TLS Strong Encryption: An Introduction [https://httpd.apache.org/docs/trunk/en/ssl/ssl_intro.html]

Apache HTTPサーバのドキュメンテーションのイントロ

RFC 1422: Privacy Enhancement for Internet Electronic Mail: Part II: Certificate-Based Key Management [https://datatracker.ietf.org/doc/html/rfc1422.html]

Steve Kent

RFC 4086: Randomness Requirements for Security [https://datatracker.ietf.org/doc/html/rfc4086.html]

Donald E., Jeffrey I. Schiller

RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile [https://datatracker.ietf.org/doc/html/rfc5280.html]

D. Cooper

RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2 [https://datatracker.ietf.org/doc/html/rfc5246.html]

T. Dierks et. al.

RFC 6066: Transport Layer Security (TLS) Extensions [https://datatracker.ietf.org/doc/html/rfc6066.html]

D. Eastlake

IANA TLS: Transport Layer Security (TLS) Parameters [https://www.iana.org/assignments/tls-parameters/tls-parameters.xml]

IANA

RFC 7525: Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) [https://datatracker.ietf.org/doc/html/rfc7525.html]

IETF

Mozilla's Server Side TLS recommendations [https://wiki.mozilla.org/Security/Server_Side_TLS]

Mozilla

select --- Waiting for I/O completion

This module provides access to the select() and poll() functions available in most operating systems, devpoll() available on Solaris and derivatives, epoll() available on Linux 2.5+ and 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.

注釈

selectors モジュールにより、select モジュールプリミティブに基づく高水準かつ効率的な I/O の多重化が行うことが出来ます。 OS レベルプリミティブを使用した正確な制御を求めない限り、代わりに selectors を使用することが推奨されます。

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. See WebAssemblyプラットフォーム for more information.

このモジュールは以下を定義します:

exception select.error

OSError の非推奨のエイリアスです。

バージョン 3.3 で変更: PEP 3151 [https://peps.python.org/pep-3151/] に基づき、このクラスは OSError のエイリアスになりました。

select.devpoll()

(Solaris およびその派生でのみサポートされています) /dev/poll ポーリングオブジェクトを返します。ポーリングオブジェクトが提供しているメソッドについては ポーリングオブジェクト 節を参照してください。

devpoll() objects are linked to the number of file descriptors allowed at the time of instantiation. If your program reduces this value, devpoll() will fail. If your program increases this value, devpoll() may return an incomplete list of active file descriptors.

新しいファイル記述子は 継承不可 です。

Added in version 3.3.

バージョン 3.4 で変更: 新しいファイル記述子が継承不可になりました。

select.epoll(sizehint=-1, flags=0)

(Linux 2.5.44 以降でのみサポート) エッジポーリング (edge polling) オブジェクトを返します。このオブジェクトは、 I/O イベントのエッジトリガもしくはレベルトリガインターフェースとして使えます。

sizehint informs epoll about the expected number of events to be registered. It must be positive, or -1 to use the default. It is only used on older systems where 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 0 or select.EPOLL_CLOEXEC, otherwise OSError is raised.

エッジポーリングオブジェクトが提供しているメソッドについては エッジおよびレベルトリガポーリング (epoll) オブジェクト 節を参照してください。

epoll オブジェクトはコンテキストマネジメントプロトコルをサポートしています。 with 文内で使用された場合、新たなファイル記述子はブロックの最後で自動的に閉じられます。

新しいファイル記述子は 継承不可 です。

バージョン 3.3 で変更: flags 引数が追加されました。

バージョン 3.4 で変更: with 文のサポートが追加されました。新しいファイル記述子が継承不可になりました。

バージョン 3.4 で非推奨: flags パラメータ。現在ではデフォルトで select.EPOLL_CLOEXEC が使われます。ファイルディスクリプタを継承可能にするには os.set_inheritable() を使ってください。

select.poll()

(全てのオペレーティングシステムでサポートされているわけではありません) ポーリングオブジェクトを返します。このオブジェクトはファイル記述子を登録したり登録解除したりすることができ、ファイル記述子に対する I/O イベント発生をポーリングすることができます; ポーリングオブジェクトが提供しているメソッドについては ポーリングオブジェクト 節を参照してください。

select.kqueue()

(BSD でのみサポート) カーネルキュー(kernel queue)オブジェクトを返します。カーネルキューオブジェクトが提供しているメソッドについては、 kqueue オブジェクト 節を参照してください。

新しいファイル記述子は 継承不可 です。

バージョン 3.4 で変更: 新しいファイル記述子が継承不可になりました。

select.kevent(ident, filter=KQ_FILTER_READ, flags=KQ_EV_ADD, fflags=0, data=0, udata=0)

(BSD でのみサポート) カーネルイベント(kernel event)オブジェクトを返します。カーネルイベントオブジェクトが提供しているメソッドについては、 kevent オブジェクト 節を参照してください。

select.select(rlist, wlist, xlist[, timeout])

This is a straightforward interface to the Unix select() system call. The first three arguments are iterables of 'waitable objects': either integers representing file descriptors or objects with a parameterless method named fileno() returning such an integer:

rlist: 読み込み可能になるまで待機

wlist: 書き込み可能になるまで待機

xlist: "例外状態 (exceptional condition)" になるまで待機 ("例外状態" については、システムのマニュアルページを参照してください)

引数に空のイテラブルを指定してもかまいませんが、3 つの引数全てを空のイテラブルにしてもよいかどうかはプラットフォームに依存します (Unix では動作し、Windows では動作しないことが知られています)。オプションの timeout 引数にはタイムアウトまでの秒数を浮動小数点数で指定します。timeout 引数が省略された場合、関数は少なくとも一つのファイル記述子が何らかの準備完了状態になるまでブロックします。timeout に 0 を指定した場合は、ポーリングを行いブロックしないことを示します。

戻り値は準備完了状態のオブジェクトからなる 3 つのリストです: したがってこのリストはそれぞれ関数の最初の 3 つの引数のサブセットになります。ファイル記述子のいずれも準備完了にならないままタイムアウトした場合、3 つの空のリストが返されます。

イテラブルの中に含めることのできるオブジェクトは Python ファイルオブジェクト (例えば sys.stdin や、 open() または os.popen() が返すオブジェクト)、 socket.socket() が返すソケットオブジェクトです。 ラッパー <wrapper> クラスを自分で定義することもできます。この場合、適切な (まったくデタラメな数ではなく本物のファイル記述子を返す) fileno() メソッドを持つ必要があります。

注釈

File objects on Windows are not acceptable, but sockets are. On Windows, the underlying select() function is provided by the WinSock library, and does not handle file descriptors that don't originate from WinSock.

バージョン 3.5 で変更: この関数は、シグナルによって中断された時に、 InterruptedError を上げる代わりに再計算されたタイムアウトによってリトライするようになりました。ただし、シグナルハンドラが例外を起こした場合を除きます (この論理的根拠については PEP 475 [https://peps.python.org/pep-0475/] を見てください)。

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 select(), poll() or another interface in this module. This doesn't apply to other kind of file-like objects such as sockets.

この値は POSIX により少なくとも512であることが保証されています。

利用可能な環境: Unix

Added in version 3.2.

/dev/poll ポーリングオブジェクト

Solaris and derivatives have /dev/poll. While select() is O(highest file descriptor) and poll() is O(number of file descriptors), /dev/poll is O(active file descriptors).

/dev/poll behaviour is very close to the standard poll() object.

devpoll.close()

ポーリングオブジェクトのファイル記述子を閉じます。

Added in version 3.4.

devpoll.closed

ポーリングオブジェクトが閉じている場合 True です。

Added in version 3.4.

devpoll.fileno()

ポーリングオブジェクトのファイル記述子番号を返します。

Added in version 3.4.

devpoll.register(fd[, eventmask])

ファイル記述子をポーリングオブジェクトに登録します。これ以降の poll() メソッド呼び出しでは、そのファイル記述子に処理待ち中の I/O イベントがあるかどうかを監視します。 fd は整数か、整数値を返す fileno() メソッドを持つオブジェクトを取ります。ファイルオブジェクトも fileno() を実装しているので、引数として使うことができます。

eventmask is an optional bitmask describing the type of events you want to check for. The constants are the same that with poll() object. The default value is a combination of the constants POLLIN, POLLPRI, and POLLOUT.

警告

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 poll().

devpoll.modify(fd[, eventmask])

このメソッドは unregister() に続いて register() を行います。同じことを明示的に行うよりも (少し) 効率的です。

devpoll.unregister(fd)

ポーリングオブジェクトによって追跡中のファイル記述子を登録解除します。 register() メソッドと同様に、 fd は整数か、整数値を返す fileno() メソッドを持つオブジェクトを取ります。

登録されていないファイル記述子の削除を試みるのは安全に無視されます。

devpoll.poll([timeout])

登録されたファイル記述子に対してポーリングを行い、報告すべき I/O イベントまたはエラーの発生したファイル記述子毎に 2 要素のタプル (fd, event) からなるリストを返します。リストは空になることもあります。 fd はファイル記述子で、 event は該当するファイル記述子について報告されたイベントを表すビットマスクです --- 例えば POLLIN は入力待ちを示し、 POLLOUT はファイル記述子に対する書き込みが可能を示す、などです。空のリストは呼び出しがタイムアウトしたか、報告すべきイベントがどのファイル記述子でも発生しなかったことを示します。 timeout が与えられた場合、処理を戻すまで待機する時間の長さをミリ秒単位で指定します。 timeout が省略されたり、 -1 であったり、あるいは None の場合、そのポーリングオブジェクトが監視している何らかのイベントが発生するまでブロックします。

バージョン 3.5 で変更: この関数は、シグナルによって中断された時に、 InterruptedError を上げる代わりに再計算されたタイムアウトによってリトライするようになりました。ただし、シグナルハンドラが例外を起こした場合を除きます (この論理的根拠については PEP 475 [https://peps.python.org/pep-0475/] を見てください)。

エッジおよびレベルトリガポーリング (epoll) オブジェクト

https://linux.die.net/man/4/epoll

eventmask

定数

意味

EPOLLIN

読み込み可能

EPOLLOUT

書き込み可能

EPOLLPRI

緊急の読み出しデータ

EPOLLERR

設定された fd にエラー状態が発生した

EPOLLHUP

設定された fd がハングアップした

EPOLLET

エッジトリガ動作に設定する。デフォルトではレベルトリガ動作

EPOLLONESHOT

1ショット動作に設定する。1回イベントが取り出されたら、その fd が内部で無効になる

EPOLLEXCLUSIVE

関連づけられた fd にイベントがある場合、1 つの epoll オブジェクトのみを起こします。デフォルトでは (このフラグが設定されていない場合には)、fd に対してポーリングするすべての epoll オブジェクトを起こします。

EPOLLRDHUP

ストリームソケットの他端が接続を切断したか、接続の書き込み側のシャットダウンを行った。

EPOLLRDNORM

EPOLLIN と同じ

EPOLLRDBAND

優先データバンドを読み込める。

EPOLLWRNORM

EPOLLOUT と同じ

EPOLLWRBAND

優先データに書き込みできる。

EPOLLMSG

無視される。

Added in version 3.6: EPOLLEXCLUSIVE was added. It's only supported by Linux Kernel 4.5 or later.

epoll.close()

epoll オブジェクトの制御用ファイル記述子を閉じます。

epoll.closed

epoll オブジェクトが閉じている場合 True です。

epoll.fileno()

制御用ファイル記述子の番号を返します。

epoll.fromfd(fd)

fd から epoll オブジェクトを作成します。

epoll.register(fd[, eventmask])

epoll オブジェクトにファイル記述子 fd を登録します。

epoll.modify(fd, eventmask)

登録されたファイル記述子変更します。

epoll.unregister(fd)

epoll オブジェクトから登録されたファイル記述子 fd を削除します。

バージョン 3.9 で変更: The method no longer ignores the EBADF error.

epoll.poll(timeout=None, maxevents=-1)

イベントを待機します。timeout はタイムアウト時間で、単位は秒 (float型) です。

バージョン 3.5 で変更: この関数は、シグナルによって中断された時に、 InterruptedError を上げる代わりに再計算されたタイムアウトによってリトライするようになりました。ただし、シグナルハンドラが例外を起こした場合を除きます (この論理的根拠については PEP 475 [https://peps.python.org/pep-0475/] を見てください)。

ポーリングオブジェクト

The poll() system call, supported on most Unix systems, provides better scalability for network servers that service many, many clients at the same time. poll() scales better because the system call only requires listing the file descriptors of interest, while select() builds a bitmap, turns on bits for the fds of interest, and then afterward the whole bitmap has to be linearly scanned again. select() is O(highest file descriptor), while poll() is O(number of file descriptors).

poll.register(fd[, eventmask])

ファイル記述子をポーリングオブジェクトに登録します。これ以降の poll() メソッド呼び出しでは、そのファイル記述子に処理待ち中の I/O イベントがあるかどうかを監視します。 fd は整数か、整数値を返す fileno() メソッドを持つオブジェクトを取ります。ファイルオブジェクトも fileno() を実装しているので、引数として使うことができます。

eventmask はオプションのビットマスクで、どの種類の I/O イベントを監視したいかを記述します。この値は以下の表で述べる定数 POLLIN 、 POLLPRI 、および POLLOUT の組み合わせにすることができます。ビットマスクを指定しない場合、標準の値が使われ、 3 種類のイベント全てに対して監視が行われます。

定数

意味

POLLIN

読み出し可能なデータが存在する

POLLPRI

緊急の読み出し可能なデータが存在する

POLLOUT

書き出しの準備ができている: 書き出し処理がブロックしない

POLLERR

何らかのエラー状態

POLLHUP

ハングアップ

POLLRDHUP

ストリームソケットの他端が接続を切断したか、接続の書き込み側のシャットダウンを行った。

POLLNVAL

無効な要求: 記述子が開かれていない

登録済みのファイル記述子を登録してもエラーにはならず、一度だけ登録した場合と同じ効果になります。

poll.modify(fd, eventmask)

登録されているファイル記述子 fd を変更する。これは、 register(fd, eventmask) と同じ効果を持ちます。登録されていないファイル記述子に対してこのメソッドを呼び出すと、 errno ENOENT で OSError 例外が発生します。

poll.unregister(fd)

ポーリングオブジェクトによって追跡中のファイル記述子を登録解除します。 register() メソッドと同様に、 fd は整数か、整数値を返す fileno() メソッドを持つオブジェクトを取ります。

登録されていないファイル記述子を登録解除しようとすると KeyError 例外が送出されます。

poll.poll([timeout])

登録されたファイル記述子に対してポーリングを行い、報告すべき I/O イベントまたはエラーの発生したファイル記述子毎に 2 要素のタプル (fd, event) からなるリストを返します。リストは空になることもあります。 fd はファイル記述子で、 event は該当するファイル記述子について報告されたイベントを表すビットマスクです --- 例えば POLLIN は入力待ちを示し、 POLLOUT はファイル記述子に対する書き込みが可能を示す、などです。空のリストは呼び出しがタイムアウトしたか、報告すべきイベントがどのファイル記述子でも発生しなかったことを示します。 timeout が与えられた場合、処理を戻すまで待機する時間の長さをミリ秒単位で指定します。 timeout が省略されたり、負の値であったり、あるいは None の場合、そのポーリングオブジェクトが監視している何らかのイベントが発生するまでブロックします。

バージョン 3.5 で変更: この関数は、シグナルによって中断された時に、 InterruptedError を上げる代わりに再計算されたタイムアウトによってリトライするようになりました。ただし、シグナルハンドラが例外を起こした場合を除きます (この論理的根拠については PEP 475 [https://peps.python.org/pep-0475/] を見てください)。

kqueue オブジェクト

kqueue.close()

kqueue オブジェクトの制御用ファイル記述子を閉じる。

kqueue.closed

kqueue オブジェクトが閉じている場合 True です。

kqueue.fileno()

制御用ファイル記述子の番号を返します。

kqueue.fromfd(fd)

与えられたファイル記述子から、kqueue オブジェクトを作成する。

kqueue.control(changelist, max_events[, timeout]) → eventlist

kevent に対する低水準のインターフェース

changelist は kevent オブジェクトのイテラブルまたは None

max_events は 0 または正の整数

timeout in seconds (floats possible); the default is None, to wait forever

バージョン 3.5 で変更: この関数は、シグナルによって中断された時に、 InterruptedError を上げる代わりに再計算されたタイムアウトによってリトライするようになりました。ただし、シグナルハンドラが例外を起こした場合を除きます (この論理的根拠については PEP 475 [https://peps.python.org/pep-0475/] を見てください)。

kevent オブジェクト

https://man.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2

kevent.ident

イベントを特定するための値。この値は、フィルタにもよりますが、大抵の場合はファイル記述子です。コンストラクタでは、 ident として、整数値か fileno() メソッドを持ったオブジェクトを渡せます。 kevent は内部で整数値を保存します。

kevent.filter

カーネルフィルタの名前。

定数

意味

KQ_FILTER_READ

記述子を受け取り、読み込めるデータが存在する時に戻る

KQ_FILTER_WRITE

記述子を受け取り、書き込み可能な時に戻る

KQ_FILTER_AIO

AIO リクエスト

KQ_FILTER_VNODE

fflag で監視されたイベントが1つ以上発生したときに戻る

KQ_FILTER_PROC

プロセスID上のイベントを監視する

KQ_FILTER_NETDEV

ネットワークデバイス上のイベントを監視する (macOS では利用不可)

KQ_FILTER_SIGNAL

監視しているシグナルがプロセスに届いたときに戻る

KQ_FILTER_TIMER

任意のタイマを設定する

kevent.flags

フィルタアクション。

定数

意味

KQ_EV_ADD

イベントを追加または修正する

KQ_EV_DELETE

キューからイベントを取り除く

KQ_EV_ENABLE

control() がイベントを返すのを許可する

KQ_EV_DISABLE

イベントを無効にする

KQ_EV_ONESHOT

イベントを最初の発生後無効にする

KQ_EV_CLEAR

イベントを受け取った後で状態をリセットする

KQ_EV_SYSFLAGS

内部イベント

KQ_EV_FLAG1

内部イベント

KQ_EV_EOF

フィルタ依存のEOF状態

KQ_EV_ERROR

戻り値を参照

kevent.fflags

フィルタ依存のフラグ。

KQ_FILTER_READ と KQ_FILTER_WRITE フィルタのフラグ:

定数

意味

KQ_NOTE_LOWAT

ソケットバッファの最低基準値

KQ_FILTER_VNODE フィルタのフラグ:

定数

意味

KQ_NOTE_DELETE

unlink() が呼ばれた

KQ_NOTE_WRITE

書き込みが発生した

KQ_NOTE_EXTEND

ファイルのサイズが拡張された

KQ_NOTE_ATTRIB

属性が変更された

KQ_NOTE_LINK

リンクカウントが変更された

KQ_NOTE_RENAME

ファイル名が変更された

KQ_NOTE_REVOKE

ファイルアクセスが破棄された

KQ_FILTER_PROC フィルタフラグ:

定数

意味

KQ_NOTE_EXIT

プロセスが終了した

KQ_NOTE_FORK

プロセスが fork() を呼び出した

KQ_NOTE_EXEC

プロセスが新しいプロセスを実行した

KQ_NOTE_PCTRLMASK

内部フィルタフラグ

KQ_NOTE_PDATAMASK

内部フィルタフラグ

KQ_NOTE_TRACK

fork() の呼び出しを超えてプロセスを監視する

KQ_NOTE_CHILD

NOTE_TRACK に対して子プロセスに渡される

KQ_NOTE_TRACKERR

子プロセスにアタッチできなかった

KQ_FILTER_NETDEV フィルタフラグ (macOS では利用不可):

定数

意味

KQ_NOTE_LINKUP

リンクアップしている

KQ_NOTE_LINKDOWN

リンクダウンしている

KQ_NOTE_LINKINV

リンク状態が不正

kevent.data

フィルタ固有のデータ。

kevent.udata

ユーザー定義値。

selectors --- High-level I/O multiplexing

Added in version 3.4.

ソースコード: Lib/selectors.py [https://github.com/python/cpython/tree/3.12/Lib/selectors.py]

はじめに

このモジュールにより、select モジュールプリミティブに基づく高水準かつ効率的な I/O の多重化が行えます。OS 水準のプリミティブを使用した正確な制御を求めない限り、このモジュールの使用が推奨されます。

It defines a BaseSelector abstract base class, along with several concrete implementations (KqueueSelector, 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 fileno() method, or a raw file descriptor. See file object.

DefaultSelector は、現在のプラットフォームで利用できる、もっとも効率的な実装の別名になります: これはほとんどのユーザーにとってのデフォルトの選択になるはずです。

注釈

プラットフォームごとにサポートされているファイルオブジェクトのタイプは異なります: Windows ではソケットはサポートされますが、パイプはされません。Unix では両方がサポートされます (その他の fifo やスペシャルファイルデバイスなどのタイプもサポートされます)。

参考

select

低水準の I/O 多重化モジュールです。

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. See WebAssemblyプラットフォーム for more information.

クラス

クラス階層:

BaseSelector
+-- SelectSelector
+-- PollSelector
+-- EpollSelector
+-- DevpollSelector
+-- KqueueSelector

以下では、events は与えられたファイルオブジェクトを待機すべき I/O イベントを示すビット単位のマスクになります。これには以下のモジュール定数の組み合わせを設定できます:

定数

意味

selectors.EVENT_READ

読み込み可能

selectors.EVENT_WRITE

書き込み可能

class selectors.SelectorKey

SelectorKey はそれの下層のファイルディスクリプタ、選択したイベントマスク、および付属データへのファイルオブジェクトの関連付けに使用される namedtuple です。いくつかの BaseSelector メソッドを返します。

fileobj

登録されたファイルオブジェクトです。

fd

下層のファイル記述子です。

events

このファイルオブジェクトで待機しなければならないイベントです。

data

このファイルオブジェクトに関連付けられたオプションの不透明型 (Opaque) データです。例えば、これはクライアントごとのセッション ID を格納するために使用できます。

class selectors.BaseSelector

BaseSelector は複数のファイルオブジェクトの I/O イベントの準備状況の待機に使用されます。これはファイルストリームを登録、登録解除、およびこれらのストリームでの I/O イベントを待機 (オプションでタイムアウト) するメソッドをサポートします。これは抽象基底クラスであるため、インスタンスを作成できません。使用する実装を明示的に指定したい、そしてプラットフォームがそれをサポートしている場合は、代わりに DefaultSelector を使用するか、SelectSelector や KqueueSelector などの一つを使用します。BaseSelector とその具象実装は コンテキストマネージャー プロトコルをサポートしています。

abstractmethod register(fileobj, events, data=None)

I/O イベントを監視するファイルオブジェクトをセレクションに登録します。

fileobj は監視するファイルオブジェクトです。これは整数のファイル記述子か、fileno() メソッドを持つオブジェクトのどちらかになります。events は監視するイベントのビット幅マスクになります。data は不透明型 (Opaque) オブジェクトです。

これは新しい SelectorKey インスタンスを返します。不正なイベントマスク化ファイル記述子のときは ValueError が、ファイルオブジェクトがすでに登録済みのときは KeyError が送出されます。

abstractmethod unregister(fileobj)

ファイルオブジェクトのセレクション登録を解除し、監視対象から外します。ファイルオブジェクトの登録解除はそのクローズより前に行われます。

fileobj は登録済みのファイルオブジェクトでなければなりません。

関連付けられた SelectorKey インスタンスを返します。fileobj が登録されていない場合 KeyError を送出します。fileobj が不正な場合 (例えば fileobj に fileno() メソッドが無い場合や fileno() メソッドの戻り値が不正な場合) ValueError を送出します。

modify(fileobj, events, data=None)

登録されたファイルオブジェクトの監視されたイベントや付属データを変更します。

より効率的に実装できる点を除けば、 BaseSelector.unregister(fileobj) に続けて BaseSelector.register(fileobj, events, data) を行うのと等価です。

新たな SelectorKey インスタンスを返します。イベントマスクやファイル記述子が不正な場合は ValueError を、ファイルオブジェクトが登録されていない場合は KeyError を送出します。

abstractmethod select(timeout=None)

登録されたいくつかのファイルオブジェクトが準備できたか、タイムアウトするまで待機します。

timeout > 0 の場合、最大待機時間を秒で指定します。 timeout <= 0 の場合、この関数の呼び出しはブロックせず、 現在準備できているファイルオブジェクトを報告します。 timeout が None の場合、監視しているファイルオブジェクトの一つが準備できるまでブロックします。

この関数は (key, events) タプルのリストを返します。準備できたファイルオブジェクトにつき1タプルです。

key は準備状態のファイルオブジェクトに対応する SelectorKey インスタンスです。 events はそのファイルオブジェクトで準備が完了したイベントのビットマスクです。

注釈

このメソッドは、現在のプロセスで信号を受信した場合、どのファイルオブジェクトも準備完了にならないうちに、またはタイムアウトが経過する前に返ることがあります。その場合、空のリストが返されます。

バージョン 3.5 で変更: このセレクタは、シグナルによって中断された時に、シグナルハンドラが例外を起こさなかった場合、空のイベントリストを返すのではなく、再計算されたタイムアウトによってリトライするようになりました (この論拠については PEP 475 [https://peps.python.org/pep-0475/] を参照してください)。

close()

セレクタを閉じます。

下層のリソースがすべて解放されたことを確かめるために呼ばれなければなりません。一旦閉じられたセレクタは使ってはいけません。

get_key(fileobj)

登録されたファイルオブジェクトに関連付けられたキーを返します。

そのファイルオブジェクトに関連付けられた SelectorKey インスタンスを返します。そのファイルオブジェクトが登録されていない場合 KeyError を送出します。

abstractmethod get_map()

ファイルオブジェクトからセレクタキーへのマッピングを返します。

これは、登録済みのファイルオブジェクトを、それらに関連づけられた SelectorKey インスタンスにマッピングする Mapping のインスタンスを返します。

class selectors.DefaultSelector

デフォルトの selector クラスで、現在のプラットフォームで利用できる最も効率的な実装を使用しています。大半のユーザはこれをデフォルトにすべきです。

class selectors.SelectSelector

select.select() を基底とするセレクタです。

class selectors.PollSelector

select.poll() を基底とするセレクタです。

class selectors.EpollSelector

select.epoll() を基底とするセレクタです。

fileno()

下層の select.epoll() オブジェクトが使用しているファイル記述子を返します。

class selectors.DevpollSelector

select.devpoll() を基底とするセレクタです。

fileno()

下層の select.devpoll() オブジェクトが使用しているファイル記述子を返します。

Added in version 3.5.

class selectors.KqueueSelector

select.kqueue() を基底とするセレクタです。

fileno()

下層の select.kqueue() オブジェクトが使用しているファイル記述子を返します。

使用例

簡単なエコーサーバの実装です:

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)

signal --- Set handlers for asynchronous events

ソースコード: Lib/signal.py [https://github.com/python/cpython/tree/3.12/Lib/signal.py]

このモジュールでは Python でシグナルハンドラを使うための機構を提供します。

一般的なルール

The signal.signal() function allows defining custom handlers to be executed when a signal is received. A small number of default handlers are installed: SIGPIPE is ignored (so write errors on pipes and sockets can be reported as ordinary Python exceptions) and SIGINT is translated into a KeyboardInterrupt exception if the parent process has not changed it.

特定のシグナルに対するハンドラが一度設定されると、明示的にリセットしないかぎり設定されたままになります (Python は背後の実装系に関係なく BSD 形式のインターフェースをエミュレートします)。例外は SIGCHLD のハンドラで、この場合は背後の実装系の仕様に従います。

On WebAssembly platforms wasm32-emscripten and wasm32-wasi, signals are emulated and therefore behave differently. Several functions and signals are not available on these platforms.

Python のシグナルハンドラの実行

Python のシグナルハンドラは、低水準 (C言語) のシグナルハンドラ内で実行されるわけではありません。代わりに、低水準のシグナルハンドラが virtual machine が対応する Python のシグナルハンドラを後から (例えば次の bytecode 命令時に) 実行するようにフラグを立てます:

It makes little sense to catch synchronous errors like SIGFPE or SIGSEGV that are caused by an invalid operation in C code. Python will return from the signal handler to the C code, which is likely to raise the same signal again, causing Python to apparently hang. From Python 3.3 onwards, you can use the faulthandler module to report on synchronous errors.

完全にCで実装された長時間かかる計算 (大きいテキストに対する正規表現のマッチなど) は、どのシグナルを受信しても中断されないまま長時間実行され続ける可能性があります。Python のシグナルハンドラはその計算が終了してから呼び出されます。

If the handler raises an exception, it will be raised "out of thin air" in the main thread. See the note below for a discussion.

シグナルとスレッド

Python のシグナルハンドラは、もしシグナルを受け取ったのが別のスレッドだったとしても、常にメインインタープリターの Python のメインスレッドで実行されます。このためシグナルをスレッド間通信に使うことはできません。代わりに threading モジュールが提供している同期プリミティブを利用できます。

また、メインインタープリターのメインスレッドだけが新しいシグナルハンドラを登録できます。

モジュールの内容

バージョン 3.5 で変更: signal (SIG*), handler (SIG_DFL, SIG_IGN) and sigmask (SIG_BLOCK, SIG_UNBLOCK, SIG_SETMASK) related constants listed below were turned into enums (Signals, Handlers and Sigmasks respectively). getsignal(), pthread_sigmask(), sigpending() and sigwait() functions return human-readable enums as Signals objects.

The signal module defines three enums:

class signal.Signals

enum.IntEnum collection of SIG* constants and the CTRL_* constants.

Added in version 3.5.

class signal.Handlers

enum.IntEnum collection the constants SIG_DFL and SIG_IGN.

Added in version 3.5.

class signal.Sigmasks

enum.IntEnum collection the constants SIG_BLOCK, SIG_UNBLOCK and SIG_SETMASK.

利用可能な環境: Unix。

See the man page sigprocmask(2) [https://manpages.debian.org/sigprocmask(2)] and pthread_sigmask(3) [https://manpages.debian.org/pthread_sigmask(3)] for further information.

Added in version 3.5.

以下に signal モジュールで定義されている変数を示します:

signal.SIG_DFL

二つある標準シグナル処理オプションのうちの一つです; 単純にシグナルに対する標準の関数を実行します。例えば、ほとんどのシステムでは、 SIGQUIT に対する標準の動作はコアダンプと終了で、 SIGCHLD に対する標準の動作は単にシグナルの無視です。

signal.SIG_IGN

もう一つの標準シグナル処理オプションで、受け取ったシグナルを単に無視します。

signal.SIGABRT

Abort signal from abort(3) [https://manpages.debian.org/abort(3)].

signal.SIGALRM

Timer signal from alarm(2) [https://manpages.debian.org/alarm(2)].

利用可能な環境: Unix。

signal.SIGBREAK

Interrupt from keyboard (CTRL + BREAK).

利用可能な環境: Windows 。

signal.SIGBUS

Bus error (bad memory access).

利用可能な環境: Unix。

signal.SIGCHLD

Child process stopped or terminated.

利用可能な環境: Unix。

signal.SIGCLD

SIGCHLD のエイリアスです。

Availability: not macOS.

signal.SIGCONT

Continue the process if it is currently stopped

利用可能な環境: Unix。

signal.SIGFPE

Floating-point exception. For example, division by zero.

参考

ZeroDivisionError is raised when the second argument of a division or modulo operation is zero.

signal.SIGHUP

Hangup detected on controlling terminal or death of controlling process.

利用可能な環境: Unix。

signal.SIGILL

Illegal instruction.

signal.SIGINT

Interrupt from keyboard (CTRL + C).

Default action is to raise KeyboardInterrupt.

signal.SIGKILL

Kill signal.

It cannot be caught, blocked, or ignored.

利用可能な環境: Unix。

signal.SIGPIPE

Broken pipe: write to pipe with no readers.

Default action is to ignore the signal.

利用可能な環境: Unix。

signal.SIGSEGV

Segmentation fault: invalid memory reference.

signal.SIGSTKFLT

Stack fault on coprocessor. The Linux kernel does not raise this signal: it can only be raised in user space.

利用可能な環境: Linux。

On architectures where the signal is available. See the man page signal(7) [https://manpages.debian.org/signal(7)] for further information.

Added in version 3.11.

signal.SIGTERM

Termination signal.

signal.SIGUSR1

User-defined signal 1.

利用可能な環境: Unix。

signal.SIGUSR2

User-defined signal 2.

利用可能な環境: Unix。

signal.SIGWINCH

Window resize signal.

利用可能な環境: Unix。

SIG*

全てのシグナル番号はシンボル定義されています。例えば、ハングアップシグナルは signal.SIGHUP で定義されています; 変数名は C 言語のプログラムで使われているのと同じ名前で、 <signal.h> にあります。 'signal()' に関する Unix マニュアルページでは、システムで定義されているシグナルを列挙しています (あるシステムではリストは signal(2) [https://manpages.debian.org/signal(2)] に、別のシステムでは signal(7) [https://manpages.debian.org/signal(7)] に列挙されています)。全てのシステムで同じシグナル名のセットを定義しているわけではないので注意してください; このモジュールでは、システムで定義されているシグナル名だけを定義しています。

signal.CTRL_C_EVENT

CTRL+C キーストロークに該当するシグナル。このシグナルは os.kill() でだけ利用できます。

利用可能な環境: Windows 。

Added in version 3.2.

signal.CTRL_BREAK_EVENT

CTRL+BREAK キーストロークに該当するシグナル。このシグナルは os.kill() でだけ利用できます。

利用可能な環境: Windows 。

Added in version 3.2.

signal.NSIG

One more than the number of the highest signal number. Use valid_signals() to get valid signal numbers.

signal.ITIMER_REAL

実時間でデクリメントするインターバルタイマーです。タイマーが発火したときに SIGALRM を送ります。

signal.ITIMER_VIRTUAL

プロセスの実行時間だけデクリメントするインターバルタイマーです。タイマーが発火したときに SIGVTALRM を送ります。

signal.ITIMER_PROF

プロセスの実行中と、システムがそのプロセスのために実行している時間だけデクリメントするインターバルタイマーです。ITIMER_VIRTUAL と組み合わせて、このタイマーはよくアプリケーションがユーザー空間とカーネル空間で消費した時間のプロファイリングに利用されます。タイマーが発火したときに SIGPROF を送ります。

signal.SIG_BLOCK

pthread_sigmask() の how 引数に渡せる値で、シグナルがブロックされることを意味します。

Added in version 3.3.

signal.SIG_UNBLOCK

pthread_sigmask() の how 引数に渡せる値で、シグナルがブロック解除されることを意味します。

Added in version 3.3.

signal.SIG_SETMASK

pthread_sigmask() の how 引数に渡せる値で、シグナルが置換されることを意味します。

Added in version 3.3.

signal モジュールは1つの例外を定義しています:

exception signal.ItimerError

背後の setitimer() または getitimer() 実装からエラーを通知するために送出されます。無効なインタバルタイマーや負の時間が setitimer() に渡された場合、このエラーを予期してください。このエラーは OSError を継承しています。

Added in version 3.3: このエラーは以前は IOError のサブタイプでしたが、 OSError のエイリアスになりました。

signal モジュールでは以下の関数を定義しています:

signal.alarm(time)

time がゼロでない値の場合、この関数は time 秒後頃に SIGALRM をプロセスに送るように要求します。それ以前にスケジュールしたアラームはキャンセルされます (常に一つのアラームしかスケジュールできません)。この場合、戻り値は以前に設定されたアラームシグナルが通知されるまであと何秒だったかを示す値です。 time がゼロの場合、アラームは一切スケジュールされず、現在スケジュールされているアラームがキャンセルされます。戻り値がゼロの場合、現在アラームがスケジュールされていないことを示します。

利用可能な環境: Unix。

See the man page alarm(2) [https://manpages.debian.org/alarm(2)] for further information.

signal.getsignal(signalnum)

シグナル signalnum に対する現在のシグナルハンドラを返します。戻り値は呼び出し可能な Python オブジェクトか、 signal.SIG_IGN、 signal.SIG_DFL、および None といった特殊な値のいずれかです。ここで signal.SIG_IGN は以前そのシグナルが無視されていたことを示し、 signal.SIG_DFL は以前そのシグナルの標準の処理方法が使われていたことを示し、 None はシグナルハンドラがまだ Python によってインストールされていないことを示します。

signal.strsignal(signalnum)

Returns the description of signal signalnum, such as "Interrupt" for SIGINT. Returns None if signalnum has no description. Raises ValueError if signalnum is invalid.

Added in version 3.8.

signal.valid_signals()

Return the set of valid signal numbers on this platform. This can be less than range(1, NSIG) if some signals are reserved by the system for internal use.

Added in version 3.8.

signal.pause()

シグナルを受け取るまでプロセスを一時停止します; その後、適切なハンドラが呼び出されます。戻り値はありません。

利用可能な環境: Unix。

See the man page signal(2) [https://manpages.debian.org/signal(2)] for further information.

sigwait(), sigwaitinfo(), sigtimedwait() sigpending() も参照してください。

signal.raise_signal(signum)

Sends a signal to the calling process. Returns nothing.

Added in version 3.8.

signal.pidfd_send_signal(pidfd, sig, siginfo=None, flags=0)

Send signal sig to the process referred to by file descriptor pidfd. Python does not currently support the siginfo parameter; it must be None. The flags argument is provided for future extensions; no flag values are currently defined.

さらに詳しい情報についてはオンラインマニュアルページ pidfd_send_signal(2) [https://manpages.debian.org/pidfd_send_signal(2)] を参照してください。

Availability: Linux >= 5.1

Added in version 3.9.

signal.pthread_kill(thread_id, signalnum)

Send the signal signalnum to the thread thread_id, another thread in the same process as the caller. The target thread can be executing any code (Python or not). However, if the target thread is executing the Python interpreter, the Python signal handlers will be executed by the main thread of the main interpreter. Therefore, the only point of sending a signal to a particular Python thread would be to force a running system call to fail with InterruptedError.

Use threading.get_ident() or the ident attribute of threading.Thread objects to get a suitable value for thread_id.

If signalnum is 0, then no signal is sent, but error checking is still performed; this can be used to check if the target thread is still running.

引数 thread_id, signalnum を指定して 監査イベント signal.pthread_kill を送出します。

利用可能な環境: Unix。

See the man page pthread_kill(3) [https://manpages.debian.org/pthread_kill(3)] for further information.

os.kill() を参照してください。

Added in version 3.3.

signal.pthread_sigmask(how, mask)

これを呼び出すスレッドにセットされているシグナルマスクを取り出したり変更したりします。シグナルマスクは、呼び出し側のために現在どのシグナルの配送がブロックされているかを示す集合 (set) です。呼び出し前のもとのシグナルマスクを集合として返却します。

この関数の振る舞いは how に依存して以下のようになります。

SIG_BLOCK: mask で指定されるシグナルが現時点のシグナルマスクに追加されます。

SIG_UNBLOCK: mask で指定されるシグナルが現時点のシグナルマスクから取り除かれます。もともとブロックされていないシグナルをブロック解除しようとしても問題ありません。

SIG_SETMASK: シグナルマスク全体を mask としてセットします。

mask はシグナル番号の集合です (例えば {signal.SIGINT, signal.SIGTERM})。全てのシグナルを含む全集合として valid_signals() を使うことが出来ます。

呼び出しスレッドにセットされたシグナルマスクを問い合わせるには例えば signal.pthread_sigmask(signal.SIG_BLOCK, []) とします。

SIGKILL and SIGSTOP cannot be blocked.

利用可能な環境: Unix。

See the man page sigprocmask(2) [https://manpages.debian.org/sigprocmask(2)] and pthread_sigmask(3) [https://manpages.debian.org/pthread_sigmask(3)] for further information.

pause(), sigpending(), sigwait() も参照して下さい。

Added in version 3.3.

signal.setitimer(which, seconds, interval=0.0)

which で指定されたタイマー (signal.ITIMER_REAL, signal.ITIMER_VIRTUAL, signal.ITIMER_PROF のどれか) を、 seconds 秒後と (alarm() と異なり、floatを指定できます)、それから (interval が0でなければ) interval 秒間隔で起動するように設定します。 seconds に0を指定すると、which で指定されたタイマーをクリアすることができます。

インターバルタイマーが起動したとき、シグナルがプロセスに送られます。送られるシグナルは利用されたタイマーの種類に依存します。 signal.ITIMER_REAL の場合は SIGALRM が、 signal.ITIMER_VIRTUAL の場合は SIGVTALRM が、 signal.ITIMER_PROF の場合は SIGPROF が送られます。

以前の値が (delay, interval) のタプルとして返されます。

無効なインターバルタイマーを渡すと ItimerError 例外が発生します。

利用可能な環境: Unix。

signal.getitimer(which)

which で指定されたインターバルタイマーの現在の値を返します。

利用可能な環境: Unix。

signal.set_wakeup_fd(fd, *, warn_on_full_buffer=True)

Set the wakeup file descriptor to fd. When a signal is received, the signal number is written as a single byte into the fd. This can be used by a library to wakeup a poll or select call, allowing the signal to be fully processed.

The old wakeup fd is returned (or -1 if file descriptor wakeup was not enabled). If fd is -1, file descriptor wakeup is disabled. If not -1, fd must be non-blocking. It is up to the library to remove any bytes from fd before calling poll or select again.

スレッドが有効な場合、この関数は メインインタープリターのメインスレッド <signals-and-threads> からしか実行できません。それ以外のスレッドからこの関数を実行しようとすると ValueError 例外が発生します。

There are two common ways to use this function. In both approaches, you use the fd to wake up when a signal arrives, but then they differ in how they determine which signal or signals have arrived.

In the first approach, we read the data out of the fd's buffer, and the byte values give you the signal numbers. This is simple, but in rare cases it can run into a problem: generally the fd will have a limited amount of buffer space, and if too many signals arrive too quickly, then the buffer may become full, and some signals may be lost. If you use this approach, then you should set warn_on_full_buffer=True, which will at least cause a warning to be printed to stderr when signals are lost.

In the second approach, we use the wakeup fd only for wakeups, and ignore the actual byte values. In this case, all we care about is whether the fd's buffer is empty or non-empty; a full buffer doesn't indicate a problem at all. If you use this approach, then you should set warn_on_full_buffer=False, so that your users are not confused by spurious warning messages.

バージョン 3.5 で変更: Windowsで、この関数はソケットハンドルをサポートするようになりました。

バージョン 3.7 で変更: warn_on_full_buffer 引数が追加されました。

signal.siginterrupt(signalnum, flag)

システムコールのリスタートの動作を変更します。 flag が False の場合、 signalnum シグナルに中断されたシステムコールは再実行されます。それ以外の場合、システムコールは中断されます。戻り値はありません。

利用可能な環境: Unix。

See the man page siginterrupt(3) [https://manpages.debian.org/siginterrupt(3)] for further information.

Note that installing a signal handler with signal() will reset the restart behaviour to interruptible by implicitly calling siginterrupt() with a true flag value for the given signal.

signal.signal(signalnum, handler)

シグナル signalnum に対するハンドラを関数 handler にします。 handler は二つの引数 (下記参照) を取る呼び出し可能な Python オブジェクトか、 signal.SIG_IGN あるいは signal.SIG_DFL といった特殊な値にすることができます。以前に使われていたシグナルハンドラが返されます (上記の getsignal() の記述を参照してください)。 (さらに詳しい情報については Unix マニュアルページ signal(2) [https://manpages.debian.org/signal(2)] を参照してください。)

スレッドが有効な場合、この関数は メインインタープリターのメインスレッド <signals-and-threads> からしか実行できません。それ以外のスレッドからこの関数を実行しようとすると ValueError 例外が発生します。

handler は二つの引数とともに呼び出されます: シグナル番号、および現在のスタックフレーム (None またはフレームオブジェクト; フレームオブジェクトについての記述は 標準型の階層における説明 か、 inspect モジュールの属性の説明を参照してください)。

On Windows, signal() can only be called with SIGABRT, SIGFPE, SIGILL, SIGINT, SIGSEGV, SIGTERM, or SIGBREAK. A ValueError will be raised in any other case. Note that not all systems define the same set of signal names; an AttributeError will be raised if a signal name is not defined as SIG* module level constant.

signal.sigpending()

呼び出しスレッドで配送が保留されているシグナル (つまり配送がブロックされている間に発生したシグナル) の集合を調べます。保留中のシグナルの集合を返します。

利用可能な環境: Unix。

See the man page sigpending(2) [https://manpages.debian.org/sigpending(2)] for further information.

pause(), pthread_sigmask(), sigwait() も参照して下さい。

Added in version 3.3.

signal.sigwait(sigset)

sigset 集合で指定されたシグナルのうちどれか一つが届くまで呼び出しスレッドを一時停止します。この関数はそのシグナルを受け取ると (それを保留シグナルリストから取り除いて) そのシグナル番号を返します。

利用可能な環境: Unix。

See the man page sigwait(3) [https://manpages.debian.org/sigwait(3)] for further information.

pause(), pthread_sigmask(), sigpending(), sigwaitinfo(), sigtimedwait() も参照して下さい。

Added in version 3.3.

signal.sigwaitinfo(sigset)

Suspend execution of the calling thread until the delivery of one of the signals specified in the signal set sigset. The function accepts the signal and removes it from the pending list of signals. If one of the signals in sigset is already pending for the calling thread, the function will return immediately with information about that signal. The signal handler is not called for the delivered signal. The function raises an InterruptedError if it is interrupted by a signal that is not in sigset.

The return value is an object representing the data contained in the siginfo_t structure, namely: si_signo, si_code, si_errno, si_pid, si_uid, si_status, si_band.

利用可能な環境: Unix。

See the man page sigwaitinfo(2) [https://manpages.debian.org/sigwaitinfo(2)] for further information.

pause(), sigwait(), sigtimedwait() も参照して下さい。

Added in version 3.3.

バージョン 3.5 で変更: The function is now retried if interrupted by a signal not in sigset and the signal handler does not raise an exception (see PEP 475 [https://peps.python.org/pep-0475/] for the rationale).

signal.sigtimedwait(sigset, timeout)

Like sigwaitinfo(), but takes an additional timeout argument specifying a timeout. If timeout is specified as 0, a poll is performed. Returns None if a timeout occurs.

利用可能な環境: Unix。

See the man page sigtimedwait(2) [https://manpages.debian.org/sigtimedwait(2)] for further information.

pause(), sigwait(), sigwaitinfo() も参照して下さい。

Added in version 3.3.

バージョン 3.5 で変更: The function is now retried with the recomputed timeout if interrupted by a signal not in sigset and the signal handler does not raise an exception (see PEP 475 [https://peps.python.org/pep-0475/] for the rationale).

使用例

以下は最小限のプログラム例です。この例では alarm() を使ってファイルを開く処理を待つのに費やす時間を制限します; 例えば、電源の入っていないシリアルデバイスを開こうとすると、通常 os.open() は未定義の期間ハングアップしてしまいますが、この方法はそうした場合に便利です。ここではファイルを開くまで 5 秒間のアラームを設定することで解決しています; ファイルを開く処理が長くかかりすぎると、アラームシグナルが送信され、ハンドラが例外を送出するようになっています。

import signal, os

def handler(signum, frame):
    signame = signal.Signals(signum).name
    print(f'Signal handler called with signal {signame} ({signum})')
    raise OSError("Couldn't open device!")

# Set the signal handler and a 5-second alarm
signal.signal(signal.SIGALRM, handler)
signal.alarm(5)

# This open() may hang indefinitely
fd = os.open('/dev/ttyS0', os.O_RDWR)

signal.alarm(0)          # Disable the alarm

Note on SIGPIPE

Piping output of your program to tools like head(1) [https://manpages.debian.org/head(1)] will cause a SIGPIPE signal to be sent to your process when the receiver of its standard output closes early. This results in an exception like BrokenPipeError: [Errno 32] Broken pipe. To handle this case, wrap your entry point to catch this exception as follows:

import os
import sys

def main():
    try:
        # simulate large output (your code replaces this loop)
        for x in range(10000):
            print("y")
        # flush output here to force SIGPIPE to be triggered
        # while inside this try block.
        sys.stdout.flush()
    except BrokenPipeError:
        # Python flushes standard streams on exit; redirect remaining output
        # to devnull to avoid another BrokenPipeError at shutdown
        devnull = os.open(os.devnull, os.O_WRONLY)
        os.dup2(devnull, sys.stdout.fileno())
        sys.exit(1)  # Python exits with error code 1 on EPIPE

if __name__ == '__main__':
    main()

Do not set SIGPIPE's disposition to SIG_DFL in order to avoid BrokenPipeError. Doing that would cause your program to exit unexpectedly whenever any socket connection is interrupted while your program is still writing to it.

Note on Signal Handlers and Exceptions

If a signal handler raises an exception, the exception will be propagated to the main thread and may be raised after any bytecode instruction. Most notably, a KeyboardInterrupt may appear at any point during execution. Most Python code, including the standard library, cannot be made robust against this, and so a KeyboardInterrupt (or any other exception resulting from a signal handler) may on rare occasions put the program in an unexpected state.

To illustrate this issue, consider the following code:

class SpamContext:
    def __init__(self):
        self.lock = threading.Lock()

    def __enter__(self):
        # If KeyboardInterrupt occurs here, everything is fine
        self.lock.acquire()
        # If KeyboardInterrupt occurs here, __exit__ will not be called
        ...
        # KeyboardInterrupt could occur just before the function returns

    def __exit__(self, exc_type, exc_val, exc_tb):
        ...
        self.lock.release()

For many programs, especially those that merely want to exit on KeyboardInterrupt, this is not a problem, but applications that are complex or require high reliability should avoid raising exceptions from signal handlers. They should also avoid catching KeyboardInterrupt as a means of gracefully shutting down. Instead, they should install their own SIGINT handler. Below is an example of an HTTP server that avoids KeyboardInterrupt:

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(('', 8000), SimpleHTTPRequestHandler)
serve_forever(httpd)
print("Shutdown...")

mmap --- Memory-mapped file support

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. See WebAssemblyプラットフォーム for more information.

メモリにマップされたファイルオブジェクトは、 bytearray と ファイルオブジェクト の両方のように振舞います。しかし通常の文字列オブジェクトとは異なり、これらは可変です。 bytearray が期待されるほとんどの場所で mmap オブジェクトを利用できます。例えば、メモリマップファイルを探索するために re モジュールを使うことができます。それらは可変なので、 obj[index] = 97 のように文字を変換できますし、スライスを使うことで obj[i1:i2] = b'...' のように部分文字列を変換することができます。現在のファイル位置をデータの始めとする読込みや書込み、ファイルの異なる位置へ seek() することもできます。

A memory-mapped file is created by the 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 fileno() method to obtain the correct value for the fileno parameter. Otherwise, you can open the file using the os.open() function, which returns a file descriptor directly (the file still needs to be closed when done).

注釈

書き込み可能でバッファされたファイルへのメモリマップファイルを作りたいのであれば、まず最初にファイルの flush() を呼び出すべきです。これはバッファへのローカルな修正がマッピングで実際に利用可能になることを保障するために必要です。

Unix バージョンと Windows バージョンのどちらのコンストラクタについても、オプションのキーワード・パラメータとして access を指定できます。 access は4つの値の内の1つを受け入れます。 ACCESS_READ は読み出し専用、 ACCESS_WRITE は書き込み可能、 ACCESS_COPY はコピーした上での書き込み、ACCESS_DEFAULT は prot に従います。 access は Unix と Windows の両方で使用することができます。 access が指定されない場合、 Windows の mmap は書き込み可能マップを返します。 3つのアクセス型すべてに対する初期メモリ値は、指定されたファイルから得られます。 ACCESS_READ 型のメモリマップに対して書き込むと TypeError 例外を送出します。 ACCESS_WRITE 型のメモリマップへの書き込みはメモリと元のファイルの両方に影響を与えます。 ACCESS_COPY 型のメモリマップへの書き込みはメモリに影響を与えますが、元のファイルを更新することはありません。

バージョン 3.7 で変更: 定数 ACCESS_DEFAULT が追加されました。

無名メモリ(anonymous memory)にマップするためには fileno として -1 を渡し、length を与えてください。

class mmap.mmap(fileno, length, tagname=None, access=ACCESS_DEFAULT[, offset])

(Windows バージョン) ファイルハンドル fileno によって指定されたファイルから length バイトをマップして、 mmap オブジェクトを生成します。 length が現在のファイルサイズより大きな場合、ファイルサイズは length を含む大きさにまで拡張されます。 length が 0 の場合、マップの最大の長さは現在のファイルサイズになります。ただし、ファイル自体が空のときは Windows が例外を送出します (Windows では空のマップを作成することができません)。

tagname, if specified and not 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 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 は非負整数のオフセットとして指定できます。mmap の参照はファイルの先頭からのオフセットに相対的になります。offset のデフォルトは 0 です。offset は ALLOCATIONGRANULARITY の倍数でなければなりません。

引数 fileno, length, access, offset 付きで 監査イベント mmap.__new__ を送出します。

class mmap.mmap(fileno, length, flags=MAP_SHARED, prot=PROT_WRITE|PROT_READ, access=ACCESS_DEFAULT[, offset])

(Unix バージョン) ファイルディスクリプタ fileno で指定されたファイルから length バイトをマップし、mmap オブジェクトを返します。length が 0 の場合、マップの最大の長さは mmap が呼ばれた時点でのファイルサイズになります。

flags specifies the nature of the mapping. 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 MAP_SHARED creates a mapping that's shared with all other processes mapping the same areas of the file. The default value is MAP_SHARED. Some systems have additional possible flags with the full list specified in MAP_* constants.

prot が指定された場合、希望のメモリ保護を与えます。 2つの最も有用な値は、 PROT_READ と PROT_WRITE です。これは、読込み可能または書込み可能を指定するものです。 prot のデフォルトは PROT_READ | PROT_WRITE です。

access はオプションのキーワード・パラメータとして、 flags と prot の代わりに指定してもかまいません。 flags, prot と access の両方を指定することは間違っています。このパラメータの使用法についての情報は、先に述べた access の記述を参照してください。

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 ALLOCATIONGRANULARITY which is equal to PAGESIZE on Unix systems.

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.

この例は mmap の簡潔な使い方を示すものです:

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()

mmap は with 文の中でコンテキストマネージャとしても使えます:

import mmap

with mmap.mmap(-1, 13) as mm:
    mm.write(b"Hello world!")

Added in version 3.2: コンテキストマネージャのサポート。

次の例では無名マップを作り親プロセスと子プロセスの間でデータのやりとりをしてみせます:

import mmap
import os

mm = mmap.mmap(-1, 13)
mm.write(b"Hello world!")

pid = os.fork()

if pid == 0:  # In a child process
    mm.seek(0)
    print(mm.readline())

    mm.close()

引数 fileno, length, access, offset 付きで 監査イベント mmap.__new__ を送出します。

メモリマップファイルオブジェクトは以下のメソッドをサポートしています:

close()

メモリマップファイルを閉じます。この呼出しの後にオブジェクトの他のメソッドの呼出すことは、 ValueError 例外の送出を引き起こします。このメソッドは開いたファイルのクローズはしません。

closed

ファイルが閉じている場合 True となります。

Added in version 3.2.

find(sub[, start[, end]])

オブジェクト内の [start, end] の範囲に含まれている部分シーケンス sub が見つかった場所の最も小さいインデックスを返します。オプションの引数 start と end はスライスに使われるときのように解釈されます。失敗したときには -1 を返します。

バージョン 3.5 で変更: 書き込み可能な bytes-like object を使用できるようになりました。

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 PAGESIZE or ALLOCATIONGRANULARITY.

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.

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

Availability: Systems with the madvise() system call.

Added in version 3.8.

move(dest, src, count)

オフセット src から始まる count バイトをインデックス dest の位置へコピーします。もし mmap が ACCESS_READ で作成されていた場合、 TypeError 例外を発生させます。

read([n])

現在のファイル位置からの最大 n バイトを含む bytes を返します。引数が省略されるか、 None もしくは負の値が指定された場合、現在のファイル位置からマップ終端までの全てのバイト列を返します。ファイル位置は返されたバイト列の直後を指すように更新されます。

バージョン 3.3 で変更: 引数が省略可能になり、 None も受け付けるようになりました。

read_byte()

現在のファイル位置のバイトを整数値として返し、ファイル位置を 1 進めます。

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.

resize(newsize)

Resizes the map and the underlying file, if any. If the mmap was created with ACCESS_READ or ACCESS_COPY, resizing the map will raise a TypeError exception.

On Windows: Resizing the map will raise an 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

rfind(sub[, start[, end]])

オブジェクト内の [start, end] の範囲に含まれている部分シーケンス sub が見つかった場所の最も大きいインデックスを返します。オプションの引数 start と end はスライスに使われるときのように解釈されます。失敗したときには -1 を返します。

バージョン 3.5 で変更: 書き込み可能な bytes-like object を使用できるようになりました。

seek(pos[, whence])

ファイルの現在位置をセットします。 whence 引数はオプションであり、デフォルトは os.SEEK_SET つまり 0 (絶対位置)です。その他の値として、 os.SEEK_CUR つまり 1 (現在位置からの相対位置)と os.SEEK_END つまり 2 (ファイルの終わりからの相対位置)があります。

size()

ファイルの長さを返します。メモリマップ領域のサイズより大きいかもしれません。

tell()

ファイルポインタの現在位置を返します。

write(bytes)

メモリ内のファイルポイントの現在位置に bytes のバイト列を書き込み、書き込まれたバイト数を返します(もし書き込みが失敗したら ValueError が送出されるため、len(bytes) より少なくなりません)。ファイル位置はバイト列が書き込まれた位置に更新されます。もしmmapが ACCESS_READ とともに作成されていた場合は、書き込みは TypeError 例外を送出するでしょう。

バージョン 3.5 で変更: 書き込み可能な bytes-like object を使用できるようになりました。

バージョン 3.6 で変更: 書きこまれたバイト数を返すようになりました。

write_byte(byte)

メモリ内のファイル・ポインタの現在位置に整数 byte を書き込みます。ファイル位置は 1 だけ進みます。もし mmap が ACCESS_READ で作成されていた場合、書き込み時に TypeError 例外を発生させるでしょう。

MADV_* Constants

mmap.MADV_NORMAL

mmap.MADV_RANDOM

mmap.MADV_SEQUENTIAL

mmap.MADV_WILLNEED

mmap.MADV_DONTNEED

mmap.MADV_REMOVE

mmap.MADV_DONTFORK

mmap.MADV_DOFORK

mmap.MADV_HWPOISON

mmap.MADV_MERGEABLE

mmap.MADV_UNMERGEABLE

mmap.MADV_SOFT_OFFLINE

mmap.MADV_HUGEPAGE

mmap.MADV_NOHUGEPAGE

mmap.MADV_DONTDUMP

mmap.MADV_DODUMP

mmap.MADV_FREE

mmap.MADV_NOSYNC

mmap.MADV_AUTOSYNC

mmap.MADV_NOCORE

mmap.MADV_CORE

mmap.MADV_PROTECT

mmap.MADV_FREE_REUSABLE

mmap.MADV_FREE_REUSE

These options can be passed to mmap.madvise(). Not every option will be present on every system.

Availability: Systems with the madvise() system call.

Added in version 3.8.

MAP_* Constants

mmap.MAP_SHARED

mmap.MAP_PRIVATE

mmap.MAP_DENYWRITE

mmap.MAP_EXECUTABLE

mmap.MAP_ANON

mmap.MAP_ANONYMOUS

mmap.MAP_POPULATE

mmap.MAP_STACK

mmap.MAP_ALIGNED_SUPER

mmap.MAP_CONCEAL

These are the various flags that can be passed to mmap.mmap(). MAP_ALIGNED_SUPER is only available at FreeBSD and MAP_CONCEAL is only available at OpenBSD. Note that some options might not be present on some systems.

バージョン 3.10 で変更: Added MAP_POPULATE constant.

Added in version 3.11: Added MAP_STACK constant.

Added in version 3.12: Added MAP_ALIGNED_SUPER constant. Added MAP_CONCEAL constant.

インターネット上のデータの操作

この章ではインターネット上で一般的に利用されているデータ形式の操作をサポートするモジュール群について記述します。

email --- An email and MIME handling package

email.message: Representing an email message

email.parser: Parsing email messages

FeedParser API

Parser API

追記事項

email.generator: Generating MIME documents

email.policy: Policy Objects

email.errors: Exception and Defect classes

email.headerregistry: Custom Header Objects

email.contentmanager: Managing MIME Content

Content Manager Instances

email: 使用例

email.message.Message: compat32 API を使用した電子メールメッセージの表現

email.mime: Creating email and MIME objects from scratch

email.header: Internationalized headers

email.charset: Representing character sets

email.encoders: Encoders

email.utils: Miscellaneous utilities

email.iterators: Iterators

json --- JSON encoder and decoder

基本的な使い方

エンコーダとデコーダ

例外

標準への準拠と互換性

文字エンコーディング

無限および NaN の数値

オブジェクト中に重複した名前の扱い

トップレベルの非オブジェクト、非配列の値の扱い

実装の制限

コマンドラインインターフェイス

コマンドラインオプション

mailbox --- Manipulate mailboxes in various formats

Mailbox オブジェクト

Maildir オブジェクト

mbox オブジェクト

MH オブジェクト

Babyl オブジェクト

MMDF オブジェクト

Message オブジェクト

MaildirMessage オブジェクト

mboxMessage オブジェクト

MHMessage オブジェクト

BabylMessage オブジェクト

MMDFMessage オブジェクト

例外

使用例

mimetypes --- Map filenames to MIME types

Mime 型オブジェクト

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

セキュリティで考慮すべき点

binascii --- Convert between binary and ASCII

quopri --- Encode and decode MIME quoted-printable data

email --- An email and MIME handling package

ソースコード: Lib/email/__init__.py [https://github.com/python/cpython/tree/3.12/Lib/email/__init__.py]

The email package is a library for managing email messages. It is specifically not designed to do any sending of email messages to SMTP (RFC 2821 [https://datatracker.ietf.org/doc/html/rfc2821.html]), NNTP, or other servers; those are functions of modules such as smtplib and nntplib. The email package attempts to be as RFC-compliant as possible, supporting RFC 5322 [https://datatracker.ietf.org/doc/html/rfc5322.html] and RFC 6532 [https://datatracker.ietf.org/doc/html/rfc6532.html], as well as such MIME-related RFCs as RFC 2045 [https://datatracker.ietf.org/doc/html/rfc2045.html], RFC 2046 [https://datatracker.ietf.org/doc/html/rfc2046.html], RFC 2047 [https://datatracker.ietf.org/doc/html/rfc2047.html], RFC 2183 [https://datatracker.ietf.org/doc/html/rfc2183.html], and RFC 2231 [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 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 EmailMessage API.

The other two major components of the package are the parser and the generator. The parser takes the serialized version of an email message (a stream of bytes) and converts it into a tree of EmailMessage objects. The generator takes an 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 policy module. Every EmailMessage, every generator, and every parser has an associated policy object that controls its behavior. Usually an application only needs to specify the policy when an EmailMessage is created, either by directly instantiating an EmailMessage to create a new email, or by parsing an input stream using a parser. But the policy can be changed when the message is serialized using a 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 email package. We start with the message object model, which is the primary interface an application will use, and follow that with the parser and generator components. Then we cover the 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 parser may detect. Then we cover the headerregistry and the 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 Message class, cover the legacy compat32 API that deals much more directly with the details of how email messages are represented. The 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 compat32 API for backward compatibility reasons.

バージョン 3.6 で変更: Docs reorganized and rewritten to promote the new EmailMessage/EmailPolicy API.

email パッケージ文書の内容

email.message: Representing an email message

email.parser: Parsing email messages

FeedParser API

Parser API

追記事項

email.generator: Generating MIME documents

email.policy: Policy Objects

email.errors: Exception and Defect classes

email.headerregistry: Custom Header Objects

email.contentmanager: Managing MIME Content

Content Manager Instances

email: 使用例

レガシーAPI:

email.message.Message: compat32 API を使用した電子メールメッセージの表現

email.mime: Creating email and MIME objects from scratch

email.header: Internationalized headers

email.charset: Representing character sets

email.encoders: Encoders

email.utils: Miscellaneous utilities

email.iterators: Iterators

参考

smtplib モジュール

SMTP（簡易メール転送プロトコル）クライアント

poplib モジュール

POP (Post Office Protocol) クライアント

モジュール imaplib

IMAP (Internet Message Access Protocol) クライアント

Module nntplib

NNTP (Net News Transport Protocol) client

mailbox モジュール

Tools for creating, reading, and managing collections of messages on disk using a variety standard formats.

email.message: Representing an email message

ソースコード: Lib/email/message.py [https://github.com/python/cpython/tree/3.12/Lib/email/message.py]

Added in version 3.6: [1]

The central class in the email package is the EmailMessage class, imported from the email.message module. It is the base class for the email object model. 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 RFC 5322 [https://datatracker.ietf.org/doc/html/rfc5322.html] or RFC 6532 [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 multipart/* or message/rfc822.

The conceptual model provided by an EmailMessage object is that of an ordered dictionary of headers coupled with a payload that represents the RFC 5322 [https://datatracker.ietf.org/doc/html/rfc5322.html] body of the message, which might be a list of sub-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 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 EmailMessage objects, for MIME container documents such as multipart/* and message/rfc822 message objects.

class 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 default policy, which follows the rules of the email RFCs except for line endings (instead of the RFC mandated \r\n, it uses the Python standard \n line endings). For more information see the policy documentation.

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 False. For backward compatibility with the base Message class maxheaderlen is accepted, but defaults to None, which means that by default the line length is controlled by the 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 Generator.

もし、文字列への変換を完全に行うためにデフォルト値を埋める必要がある場合、メッセージのフラット化は EmailMessage の変更を引き起こす可能性があります (例えば、MIME の境界が生成される、変更される等)。

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

__str__()

Equivalent to as_string(policy=self.policy.clone(utf8=True)). Allows str(msg) to produce a string containing the serialized message in a readable format.

バージョン 3.4 で変更: the method was changed to use utf8=True, thus producing an RFC 6531 [https://datatracker.ietf.org/doc/html/rfc6531.html]-like message representation, instead of being a direct alias for as_string().

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

もし、文字列への変換を完全に行うためにデフォルト値を埋める必要がある場合、メッセージのフラット化は EmailMessage の変更を引き起こす可能性があります (例えば、MIME の境界が生成される、変更される等)。

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 email.generator.BytesGenerator for a more flexible API for serializing messages.

__bytes__()

Equivalent to as_bytes(). Allows bytes(msg) to produce a bytes object containing the serialized message.

is_multipart()

Return True if the message's payload is a list of sub-EmailMessage objects, otherwise return False. When is_multipart() returns False, the payload should be a string object (which might be a CTE encoded binary payload). Note that is_multipart() returning True does not necessarily mean that "msg.get_content_maintype() == 'multipart'" will return the True. For example, is_multipart will return True when the EmailMessage is of type message/rfc822.

set_unixfrom(unixfrom)

Set the message's envelope header to unixfrom, which should be a string. (See mboxMessage for a brief description of this header.)

get_unixfrom()

メッセージのエンベロープヘッダを返します。エンベロープヘッダが設定されていない場合は None が返されます。

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 keys(), but in an 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.

注意: どんな場合も、メッセージ中のエンベロープヘッダはこのマップ形式のインタフェイスには含まれません。

__len__()

複製されたものもふくめてヘッダ数の合計を返します。

__contains__(name)

Return 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 in operator. For example:

if 'message-id' in myMessage:
   print('Message-ID:', myMessage['message-id'])

__getitem__(name)

Return the value of the named header field. name does not include the colon field separator. If the header is missing, None is returned; a 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 get_all() method to get the values of all the extant headers named name.

Using the standard (non-compat32) policies, the returned value is an instance of a subclass of email.headerregistry.BaseHeader.

__setitem__(name, val)

メッセージヘッダに name という名前の val という値をもつフィールドをあらたに追加します。このフィールドは現在メッセージに存在するヘッダーのいちばん後に追加されます。

注意: このメソッドでは、すでに同一の名前で存在するフィールドは上書き されません。もしメッセージが名前 name をもつフィールドをひとつしか持たないようにしたければ、最初にそれを除去してください。たとえば:

del msg['subject']
msg['subject'] = 'Python roolz!'

If the policy defines certain headers to be unique (as the standard policies do), this method may raise a 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.

__delitem__(name)

メッセージのヘッダから、name という名前をもつフィールドをすべて除去します。たとえこの名前をもつヘッダが存在していなくても例外は発生しません。

keys()

メッセージ中にあるすべてのヘッダのフィールド名のリストを返します。

values()

メッセージ中にあるすべてのフィールドの値のリストを返します。

items()

メッセージ中にあるすべてのヘッダのフィールド名とその値を 2-タプルのリストとして返します。

get(name, failobj=None)

Return the value of the named header field. This is identical to __getitem__() except that optional failobj is returned if the named header is missing (failobj defaults to None).

Here are some additional useful header related methods:

get_all(name, failobj=None)

name の名前をもつフィールドのすべての値からなるリストを返します。該当する名前のヘッダがメッセージ中に含まれていない場合は failobj (デフォルトでは None) が返されます。

add_header(_name, _value, **_params)

拡張ヘッダ設定。このメソッドは __setitem__() と似ていますが、追加のヘッダ・パラメータをキーワード引数で指定できるところが違っています。 _name に追加するヘッダフィールドを、 _value にそのヘッダの 最初の 値を渡します。

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 key="value" unless the value is 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 (CHARSET, LANGUAGE, VALUE), where CHARSET is a string naming the charset to be used to encode the value, LANGUAGE can usually be set to None or the empty string (see RFC 2231 [https://datatracker.ietf.org/doc/html/rfc2231.html] for other possibilities), and 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 RFC 2231 [https://datatracker.ietf.org/doc/html/rfc2231.html] format using a CHARSET of utf-8 and a LANGUAGE of None.

以下に例を示します。:

msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')

こうするとヘッダには以下のように追加されます

Content-Disposition: attachment; filename="bud.gif"

An example of the extended interface with non-ASCII characters:

msg.add_header('Content-Disposition', 'attachment',
               filename=('iso-8859-1', '', 'Fußballer.ppt'))

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

get_content_type()

Return the message's content type, coerced to lower case of the form maintype/subtype. If there is no Content-Type header in the message return the value returned by get_default_type(). If the Content-Type header is invalid, return text/plain.

(According to RFC 2045 [https://datatracker.ietf.org/doc/html/rfc2045.html], messages always have a default type, get_content_type() will always return a value. RFC 2045 [https://datatracker.ietf.org/doc/html/rfc2045.html] defines a message's default type to be text/plain unless it appears inside a multipart/digest container, in which case it would be message/rfc822. If the Content-Type header has an invalid type specification, RFC 2045 [https://datatracker.ietf.org/doc/html/rfc2045.html] mandates that the default type be text/plain.)

get_content_maintype()

そのメッセージの主 content-type を返します。これは get_content_type() によって返される文字列の maintype 部分です。

get_content_subtype()

そのメッセージの副 content-type (sub content-type、subtype) を返します。これは get_content_type() によって返される文字列の subtype 部分です。

get_default_type()

デフォルトの content-type を返します。ほどんどのメッセージではデフォルトの content-type は text/plain ですが、メッセージが multipart/digest コンテナに含まれているときだけ例外的に message/rfc822 になります。

set_default_type(ctype)

Set the default content type. ctype should either be text/plain or message/rfc822, although this is not enforced. The default content type is not stored in the Content-Type header, so it only affects the return value of the get_content_type methods when no Content-Type header is present in the message.

set_param(param, value, header='Content-Type', requote=True, charset=None, language='', replace=False)

Set a parameter in the Content-Type header. If the parameter already exists in the header, replace its value with value. When header is Content-Type (the default) and the header does not yet exist in the message, add it, set its value to text/plain, and append the new parameter value. Optional header specifies an alternative header to 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 RFC 2231 [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 utf8 charset and None for the language.

If replace is False (the default) the header is moved to the end of the list of headers. If replace is True, the header will be updated in place.

Use of the requote parameter with EmailMessage objects is deprecated.

Note that existing parameter values of headers may be accessed through the params attribute of the header value (for example, msg['Content-Type'].params['charset']).

バージョン 3.4 で変更: replace キーワードが追加されました。

del_param(param, header='content-type', requote=True)

指定されたパラメータを Content-Type ヘッダ中から完全にとりのぞきます。ヘッダはそのパラメータと値がない状態に書き換えられます。オプション変数 header が与えられた場合、 Content-Type のかわりにそのヘッダが使用されます。

Use of the requote parameter with EmailMessage objects is deprecated.

get_filename(failobj=None)

そのメッセージ中の Content-Disposition ヘッダにある、 filename パラメータの値を返します。目的のヘッダに filename パラメータがない場合には Content-Type ヘッダにある name パラメータを探します。それも無い場合またはヘッダが無い場合には failobj が返されます。返される文字列はつねに email.utils.unquote() によって unquote されます。

get_boundary(failobj=None)

そのメッセージ中の Content-Type ヘッダにある、 boundary パラメータの値を返します。目的のヘッダが欠けていたり、 boundary パラメータがない場合には failobj が返されます。返される文字列はつねに email.utils.unquote() によって unquote されます。

set_boundary(boundary)

メッセージ中の Content-Type ヘッダにある、 boundary パラメータに値を設定します。 set_boundary() は必要に応じて boundary を quote します。そのメッセージが Content-Type ヘッダを含んでいない場合、 HeaderParseError が発生します。

Note that using this method is subtly different from deleting the old Content-Type header and adding a new one with the new boundary via add_header(), because set_boundary() preserves the order of the Content-Type header in the list of headers.

get_content_charset(failobj=None)

そのメッセージ中の Content-Type ヘッダにある、 charset パラメータの値を返します。値はすべて小文字に変換されます。メッセージ中に Content-Type がなかったり、このヘッダ中に charaset パラメータがない場合には failobj が返されます。

get_charsets(failobj=None)

メッセージ中に含まれる文字セットの名前をすべてリストにして返します。そのメッセージが multipart である場合、返されるリストの各要素がそれぞれの subpart のペイロードに対応します。それ以外の場合、これは長さ 1 のリストを返します。

リスト中の各要素は文字列であり、これは対応する subpart 中のそれぞれの Content-Type ヘッダにある charset の値です。その subpart が Content-Type をもってないか、 charset がないか、あるいは MIME maintype が text でないいずれかの場合には、リストの要素として failobj が返されます。

is_attachment()

Content-Disposition ヘッダが存在し、その (大文字小文字を区別しない) 値が attachment の場合、 True を返します。 それ以外の場合は False を返します。

バージョン 3.4.2 で変更: is_multipart() との一貫性のために、is_attachment が属性からメソッドになりました。

get_content_disposition()

Return the lowercased value (without parameters) of the message's Content-Disposition header if it has one, or None. The possible values for this method are inline, attachment or None if the message follows RFC 2183 [https://datatracker.ietf.org/doc/html/rfc2183.html].

Added in version 3.5.

The following methods relate to interrogating and manipulating the content (payload) of the message.

walk()

walk() メソッドは多目的のジェネレータで、これはあるメッセージオブジェクトツリー中のすべての part および subpart をわたり歩くのに使えます。順序は深さ優先です。おそらく典型的な用法は、 walk() を for ループ中でのイテレータとして使うことでしょう。ループを一回まわるごとに、次の subpart が返されるのです。

以下の例は、 multipart メッセージのすべての part において、その MIME タイプを表示していくものです。 :

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

walk iterates over the subparts of any part where is_multipart() returns True, even though msg.get_content_maintype() == 'multipart' may return False. We can see this in our example by making use of the _structure debug helper function:

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

Here the message parts are not multiparts, but they do contain subparts. is_multipart() returns True and walk descends into the subparts.

get_body(preferencelist=('related', 'html', 'plain'))

メッセージの "本体" の最有力候補となる MIME 部を返します。

preferencelist must be a sequence of strings from the set related, html, and 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 get_body method is called.

If 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 multipart/related, check the start parameter and if a part with a matching Content-ID is found, consider only it when looking for candidate matches. Otherwise consider only the first (default root) part of the multipart/related.

If a part has a Content-Disposition header, only consider the part a candidate match if the value of the header is inline.

If none of the candidates matches any of the preferences in preferencelist, return None.

Notes: (1) For most applications the only preferencelist combinations that really make sense are ('plain',), ('html', 'plain'), and the default ('related', 'html', 'plain'). (2) Because matching starts with the object on which get_body is called, calling get_body on a multipart/related will return the object itself unless preferencelist has a non-default value. (3) Messages (or message parts) that do not specify a Content-Type or whose Content-Type header is invalid will be treated as if they are of type text/plain, which may occasionally cause get_body to return unexpected results.

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 text/plain, text/html, multipart/related, or multipart/alternative (unless they are explicitly marked as attachments via Content-Disposition: attachment), and return all remaining parts. When applied directly to a multipart/related, return an iterator over the all the related parts except the root part (ie: the part pointed to by the start parameter, or the first part if there is no start parameter or the start parameter doesn't match the Content-ID of any of the parts). When applied directly to a multipart/alternative or a non-multipart, return an empty iterator.

iter_parts()

Return an iterator over all of the immediate sub-parts of the message, which will be empty for a non-multipart. (See also walk().)

get_content(*args, content_manager=None, **kw)

Call the 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 content_manager specified by the current policy.

set_content(*args, content_manager=None, **kw)

Call the 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 content_manager specified by the current policy.

make_related(boundary=None)

Convert a non-multipart message into a multipart/related message, moving any existing Content- headers and payload into a (new) first part of the 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).

make_alternative(boundary=None)

Convert a non-multipart or a multipart/related into a multipart/alternative, moving any existing Content- headers and payload into a (new) first part of the 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).

make_mixed(boundary=None)

Convert a non-multipart, a multipart/related, or a multipart-alternative into a multipart/mixed, moving any existing Content- headers and payload into a (new) first part of the 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).

add_related(*args, content_manager=None, **kw)

If the message is a multipart/related, create a new message object, pass all of the arguments to its set_content() method, and attach() it to the multipart. If the message is a non-multipart, call make_related() and then proceed as above. If the message is any other type of multipart, raise a TypeError. If content_manager is not specified, use the content_manager specified by the current policy. If the added part has no Content-Disposition header, add one with the value inline.

add_alternative(*args, content_manager=None, **kw)

If the message is a multipart/alternative, create a new message object, pass all of the arguments to its set_content() method, and attach() it to the multipart. If the message is a non-multipart or multipart/related, call make_alternative() and then proceed as above. If the message is any other type of multipart, raise a TypeError. If content_manager is not specified, use the content_manager specified by the current policy.

add_attachment(*args, content_manager=None, **kw)

If the message is a multipart/mixed, create a new message object, pass all of the arguments to its set_content() method, and attach() it to the multipart. If the message is a non-multipart, multipart/related, or multipart/alternative, call make_mixed() and then proceed as above. If content_manager is not specified, use the content_manager specified by the current policy. If the added part has no Content-Disposition header, add one with the value attachment. This method can be used both for explicit attachments (Content-Disposition: attachment) and inline attachments (Content-Disposition: inline), by passing appropriate options to the content_manager.

clear()

ペイロードとヘッダの全てを削除します。

clear_content()

Remove the payload and all of the !Content- headers, leaving all other headers intact and in their original order.

EmailMessage オブジェクトは次のようなインスタンス属性を持ちます:

preamble

MIME ドキュメントの形式では、ヘッダ直後にくる空行と最初の multipart 境界をあらわす文字列のあいだにいくらかのテキスト (訳注: preamble, 序文) を埋めこむことを許しています。このテキストは標準的な MIME の範疇からはみ出しているので、MIME 形式を認識するメールソフトからこれらは通常まったく見えません。しかしメッセージのテキストを生で見る場合、あるいはメッセージを MIME 対応していないメールソフトで見る場合、このテキストは目に見えることになります。

preamble 属性は MIME ドキュメントに加えるこの最初の MIME 範囲外テキストを含んでいます。 Parser があるテキストをヘッダ以降に発見したが、それはまだ最初の MIME 境界文字列が現れる前だった場合、パーザはそのテキストをメッセージの preamble 属性に格納します。 Generator がある MIME メッセージからプレーンテキスト形式を生成するときメッセージが preamble 属性を持つことが発見されれば、これはそのテキストをヘッダと最初の MIME 境界の間に挿入します。詳細は email.parser および email.generator を参照してください。

注意: そのメッセージに preamble がない場合、preamble 属性には None が格納されます。

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 preamble, if there is no epilog text this attribute will be None.

defects

defects 属性はメッセージを解析する途中で検出されたすべての問題点 (defect、障害) のリストを保持しています。解析中に発見されうる障害についてのより詳細な説明は email.errors を参照してください。

class email.message.MIMEPart(policy=default)

This class represents a subpart of a MIME message. It is identical to EmailMessage, except that no MIME-Version headers are added when set_content() is called, since sub-parts do not need their own MIME-Version headers.

脚注

[1]

Originally added in 3.4 as a provisional module. Docs for legacy message class moved to email.message.Message: compat32 API を使用した電子メールメッセージの表現.

email.parser: Parsing email messages

ソースコード: Lib/email/parser.py [https://github.com/python/cpython/tree/3.12/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 EmailMessage object, adding headers using the dictionary interface, and adding payload(s) using set_content() and related methods, or they can be created by parsing a serialized representation of the email message.

The 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 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 True from its is_multipart() method, and the subparts can be accessed via the payload manipulation methods, such as get_body(), iter_parts(), and walk().

There are actually two parser interfaces available for use, the Parser API and the incremental FeedParser API. The 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. 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 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 email package's bundled parser and the EmailMessage class is embodied in the Policy class, so a custom parser can create message object trees any way it finds necessary by implementing custom versions of the appropriate Policy methods.

FeedParser API

The BytesFeedParser, imported from the 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 BytesFeedParser can of course be used to parse an email message fully contained in a bytes-like object, string, or file, but the BytesParser API may be more convenient for such use cases. The semantics and results of the two parser APIs are identical.

BytesFeedParser API は簡単です。まずインスタンスをつくり、それに bytes を (それ以上 bytes が必要なくなるまで) 流しこみます。その後パーザを close すると根っこ (root) のメッセージオブジェクトが返されます。標準に従ったメッセージを解析する場合、 BytesFeedParser は非常に正確であり、標準に従っていないメッセージでもちゃんと動きます。そのさい、これはメッセージがどのように壊れていると認識されたかについての情報を残します。これはメッセージオブジェクトの defects 属性にリストとして現れ、メッセージ中に発見された問題が記録されます。パーザが検出できる障害 (defect) については email.errors モジュールを参照してください。

以下は BytesFeedParser の API です:

class email.parser.BytesFeedParser(_factory=None, *, policy=policy.compat32)

Create a BytesFeedParser instance. Optional _factory is a no-argument callable; if not specified use the 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 compat32 policy, which maintains backward compatibility with the Python 3.2 version of the email package and provides Message as the default factory. All other policies provide EmailMessage as the default _factory. For more information on what else policy controls, see the policy documentation.

Note: The policy keyword should always be specified; The default will change to email.policy.default in a future version of Python.

Added in version 3.2.

バージョン 3.3 で変更: キーワード引数 policy が追加されました。

バージョン 3.6 で変更: _factory defaults to the policy message_factory.

feed(data)

パーサーにデータを供給します。 data は 1行または複数行からなる bytes-like object を渡します。渡される行は完結していなくてもよく、その場合パーサーは部分的な行を適切につなぎ合わせます。各行は3種類の標準的な行末文字 (復帰 CR、改行 LF、または CR+LF) どれかの組み合わせでよく、これらが混在してもかまいません。

close()

Complete the parsing of all previously fed data and return the root message object. It is undefined what happens if feed() is called after this method has been called.

class email.parser.FeedParser(_factory=None, *, policy=policy.compat32)

Works like BytesFeedParser except that the input to the 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 utf8 is True, no binary attachments.

バージョン 3.3 で変更: キーワード引数 policy が追加されました。

Parser API

The BytesParser class, imported from the 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 bytes-like object or file. The email.parser module also provides Parser for parsing strings, and header-only parsers, BytesHeaderParser and HeaderParser, which can be used if you're only interested in the headers of the message. BytesHeaderParser and 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.

class email.parser.BytesParser(_class=None, *, policy=policy.compat32)

Create a BytesParser instance. The _class and policy arguments have the same meaning and semantics as the _factory and policy arguments of BytesFeedParser.

Note: The policy keyword should always be specified; The default will change to email.policy.default in a future version of Python.

バージョン 3.3 で変更: 2.4 で非推奨になった strict 引数の削除。キーワード引数 policy の追加。

バージョン 3.6 で変更: _class defaults to the policy message_factory.

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 readline() and the read() methods.

The bytes contained in fp must be formatted as a block of RFC 5322 [https://datatracker.ietf.org/doc/html/rfc5322.html] (or, if utf8 is True, RFC 6532 [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 Content-Transfer-Encoding of 8bit).

オプション引数 headersonly はヘッダを読み終えた後にパースを止めるかを指定するフラグです。デフォルトは False で、ファイルの内容全体をパースします。

parsebytes(bytes, headersonly=False)

Similar to the parse() method, except it takes a bytes-like object instead of a file-like object. Calling this method on a bytes-like object is equivalent to wrapping bytes in a BytesIO instance first and calling parse().

オプション引数 headersonly は parse() メソッドと同じです。

Added in version 3.2.

class email.parser.BytesHeaderParser(_class=None, *, policy=policy.compat32)

Exactly like BytesParser, except that headersonly defaults to True.

Added in version 3.3.

class email.parser.Parser(_class=None, *, policy=policy.compat32)

This class is parallel to BytesParser, but handles string input.

バージョン 3.3 で変更: strict 引数の削除。キーワード引数 policy の追加。

バージョン 3.6 で変更: _class defaults to the policy message_factory.

parse(fp, headersonly=False)

ファイルなどテキストモードのストリーム形式 (file-like) のオブジェクト fp からすべてのデータを読み込み、得られたテキストを解析して基底 (root) メッセージオブジェクト構造を返します。 fp はストリーム形式のオブジェクトで readline() および read() 両方のメソッドをサポートしている必要があります。

Other than the text mode requirement, this method operates like BytesParser.parse().

parsestr(text, headersonly=False)

parse() メソッドに似ていますが、ファイルなどのストリーム形式のかわりに文字列を引数としてとるところが違います。文字列に対してこのメソッドを呼ぶことは、 text を StringIO インスタンスとして作成して parse() を適用するのと同じです。

オプション引数 headersonly は parse() メソッドと同じです。

class email.parser.HeaderParser(_class=None, *, policy=policy.compat32)

Exactly like Parser, except that headersonly defaults to True.

ファイルや文字列からメッセージオブジェクト構造を作成するのはかなりよくおこなわれる作業なので、便宜上次のような 4つの関数が提供されています。これらは email パッケージのトップレベルの名前空間で使用できます。

email.message_from_bytes(s, _class=None, *, policy=policy.compat32)

bytes-like オブジェクト からメッセージオブジェクト構造を作成して返します。これは BytesParser().parsebytes(s) と同じです。オプション引数 _class および policy は BytesParser クラスのコンストラクタと同様に解釈されます。

Added in version 3.2.

バージョン 3.3 で変更: strict 引数の削除。キーワード引数 policy の追加。

email.message_from_binary_file(fp, _class=None, *, policy=policy.compat32)

オープンされたバイナリ file object からメッセージオブジェクト構造を作成して返します。これは BytesParser().parse(fp) と同じです。 _class および policy は BytesParser クラスのコンストラクタと同様に解釈されます。

Added in version 3.2.

バージョン 3.3 で変更: strict 引数の削除。キーワード引数 policy の追加。

email.message_from_string(s, _class=None, *, policy=policy.compat32)

文字列からメッセージオブジェクト構造を作成して返します。これは Parser().parsestr(s) と同じです。 _class および policy は Parser クラスのコンストラクタと同様に解釈されます。

バージョン 3.3 で変更: strict 引数の削除。キーワード引数 policy の追加。

email.message_from_file(fp, _class=None, *, policy=policy.compat32)

オープンされた file object からメッセージオブジェクト構造を作成して返します。これは Parser().parse(fp) と同じです。 _class および policy は Parser クラスのコンストラクタと同様に解釈されます。

バージョン 3.3 で変更: strict 引数の削除。キーワード引数 policy の追加。

バージョン 3.6 で変更: _class defaults to the policy message_factory.

対話的な Python プロンプトで message_from_bytes() を使用するとすれば、このようになります:

>>> import email
>>> msg = email.message_from_bytes(myBytes)

追記事項

以下はテキスト解析の際に適用されるいくつかの規約です:

Most non-multipart type messages are parsed as a single message object with a string payload. These objects will return False for is_multipart(), and iter_parts() will yield an empty list.

All 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 True for is_multipart(), and iter_parts() will yield a list of subparts.

Most messages with a content type of message/* (such as message/delivery-status and message/rfc822) will also be parsed as container object containing a list payload of length 1. Their is_multipart() method will return True. The single element yielded by iter_parts() will be a sub-message object.

いくつかの標準的でないメッセージは、 multipart の使い方に統一がとれていない場合があります。このようなメッセージは Content-Type ヘッダに multipart を指定しているものの、その is_multipart() メソッドは False を返すことがあります。もしこのようなメッセージが FeedParser によって解析されると、その defects 属性のリスト中には MultipartInvariantViolationDefect クラスのインスタンスが現れます。詳しい情報については email.errors を参照してください。

email.generator: Generating MIME documents

ソースコード: Lib/email/generator.py [https://github.com/python/cpython/tree/3.12/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 smtplib.SMTP.sendmail() or the nntplib module, 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 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 policy is used for both. That is, parsing the serialized byte stream via the BytesParser class and then regenerating the serialized byte stream using BytesGenerator should produce output identical to the input [1]. (On the other hand, using the generator on an EmailMessage constructed by program may result in changes to the EmailMessage object as defaults are filled in.)

The 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 Generator disables header folding for message parts of type multipart/signed and all subparts.

class email.generator.BytesGenerator(outfp, mangle_from_=None, maxheaderlen=None, *, policy=None)

Return a BytesGenerator object that will write any message provided to the flatten() method, or any surrogateescape encoded text provided to the write() method, to the file-like object outfp. outfp must support a write method that accepts binary data.

If optional mangle_from_ is True, put a > character in front of any line in the body that starts with the exact string "From ", that is From followed by a space at the beginning of a line. mangle_from_ defaults to the value of the mangle_from_ setting of the policy (which is True for the compat32 policy and False for all others). mangle_from_ is intended for use when messages are stored in Unix mbox format (see mailbox and WHY THE CONTENT-LENGTH FORMAT IS BAD [https://www.jwz.org/doc/content-length.html]).

If maxheaderlen is not None, refold any header lines that are longer than maxheaderlen, or if 0, do not rewrap any headers. If manheaderlen is 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 None (the default), use the policy associated with the Message or EmailMessage object passed to flatten to control the message generation. See email.policy for details on what policy controls.

Added in version 3.2.

バージョン 3.3 で変更: キーワード引数 policy が追加されました。

バージョン 3.6 で変更: The default behavior of the mangle_from_ and maxheaderlen parameters is to follow the policy.

flatten(msg, unixfrom=False, linesep=None)

msg を基点とするメッセージオブジェクト構造体の文字表現を出力します。出力先のファイルにはこの BytesGenerator インスタンスが作成されたときに指定されたものが使われます。

If the policy option cte_type is 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 Content-Transfer-Encoding of any body parts that have them. If cte_type is 7bit, convert the bytes with the high bit set as needed using an ASCII-compatible Content-Transfer-Encoding. That is, transform parts with non-ASCII Content-Transfer-Encoding (Content-Transfer-Encoding: 8bit) to an ASCII compatible Content-Transfer-Encoding, and encode RFC-invalid non-ASCII bytes in headers using the MIME unknown-8bit character set, thus rendering them RFC-compliant.

If unixfrom is True, print the envelope header delimiter used by the Unix mailbox format (see mailbox) before the first of the RFC 5322 [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 False. Note that for subparts, no envelope header is ever printed.

If linesep is not None, use it as the separator character between all the lines of the flattened message. If linesep is None (the default), use the value specified in the policy.

clone(fp)

Return an independent clone of this BytesGenerator instance with the exact same option settings, and fp as the new outfp.

write(s)

Encode s using the ASCII codec and the surrogateescape error handler, and pass it to the write method of the outfp passed to the BytesGenerator's constructor.

As a convenience, EmailMessage provides the methods as_bytes() and bytes(aMessage) (a.k.a. __bytes__()), which simplify the generation of a serialized binary representation of a message object. For more detail, see email.message.

Because strings cannot represent binary data, the Generator class must convert any binary data in any message it flattens to an ASCII compatible format, by converting them to an ASCII compatible Content-Transfer_Encoding. Using the terminology of the email RFCs, you can think of this as Generator serializing to an I/O stream that is not "8 bit clean". In other words, most applications will want to be using BytesGenerator, and not Generator.

class email.generator.Generator(outfp, mangle_from_=None, maxheaderlen=None, *, policy=None)

Return a Generator object that will write any message provided to the flatten() method, or any text provided to the write() method, to the file-like object outfp. outfp must support a write method that accepts string data.

If optional mangle_from_ is True, put a > character in front of any line in the body that starts with the exact string "From ", that is From followed by a space at the beginning of a line. mangle_from_ defaults to the value of the mangle_from_ setting of the policy (which is True for the compat32 policy and False for all others). mangle_from_ is intended for use when messages are stored in Unix mbox format (see mailbox and WHY THE CONTENT-LENGTH FORMAT IS BAD [https://www.jwz.org/doc/content-length.html]).

If maxheaderlen is not None, refold any header lines that are longer than maxheaderlen, or if 0, do not rewrap any headers. If manheaderlen is 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 None (the default), use the policy associated with the Message or EmailMessage object passed to flatten to control the message generation. See 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.

flatten(msg, unixfrom=False, linesep=None)

msg を基点とするメッセージオブジェクト構造体の文字表現を出力します。出力先のファイルにはこの Generator インスタンスが作成されたときに指定されたものが使われます。

If the policy option cte_type is 8bit, generate the message as if the option were set to 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 Content-Transfer-Encoding. That is, transform parts with non-ASCII Content-Transfer-Encoding (Content-Transfer-Encoding: 8bit) to an ASCII compatible Content-Transfer-Encoding, and encode RFC-invalid non-ASCII bytes in headers using the MIME unknown-8bit character set, thus rendering them RFC-compliant.

If unixfrom is True, print the envelope header delimiter used by the Unix mailbox format (see mailbox) before the first of the RFC 5322 [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 False. Note that for subparts, no envelope header is ever printed.

If linesep is not None, use it as the separator character between all the lines of the flattened message. If linesep is None (the default), use the value specified in the policy.

バージョン 3.2 で変更: 8bit メッセージ本体の再エンコードがサポートされました。linesep 引数が追加されました。

clone(fp)

Return an independent clone of this Generator instance with the exact same options, and fp as the new outfp.

write(s)

Write s to the write method of the outfp passed to the Generator's constructor. This provides just enough file-like API for Generator instances to be used in the print() function.

As a convenience, EmailMessage provides the methods as_string() and str(aMessage) (a.k.a. __str__()), which simplify the generation of a formatted string representation of a message object. For more detail, see email.message.

The email.generator module also provides a derived class, DecodedGenerator, which is like the Generator base class, except that non-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.

class email.generator.DecodedGenerator(outfp, mangle_from_=None, maxheaderlen=None, fmt=None, *, policy=None)

Act like Generator, except that for any subpart of the message passed to Generator.flatten(), if the subpart is of main type text, print the decoded payload of the subpart, and if the main type is not 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 fmt % part_info, where part_info is a dictionary composed of the following keys and values:

type -- 非 text 型 subpart の MIME 形式

maintype -- 非 text 型 subpart の MIME 主形式 (maintype)

subtype -- 非 text 型 subpart の MIME 副形式 (subtype)

filename -- 非 text 型 subpart のファイル名

description -- 非 text 型 subpart につけられた説明文字列

encoding -- 非 text 型 subpart の Content-transfer-encoding

If fmt is None, use the following default fmt:

"[Non-text (%(type)s) part of message omitted, filename %(filename)s]"

Optional _mangle_from_ and maxheaderlen are as with the Generator base class.

脚注

[1]

This statement assumes that you use the appropriate setting for unixfrom, and that there are no email.policy settings calling for automatic adjustments (for example, refold_source must be 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.

email.policy: Policy Objects

Added in version 3.3.

ソースコード: Lib/email/policy.py [https://github.com/python/cpython/tree/3.12/Lib/email/policy.py]

email パッケージの主要な目的は様々なEメールやMIMEのRFCで記述されたEメールメッセージを取り扱うことにあります。しかし、Eメールメッセージの一般的なフォーマット(名前の後にコロンが続き、コロンの後に値が続くという構成の複数のヘッダーフィールドのブロック、空白行、任意の 'body')はEメールの分野外での用途が見いだされたフォーマットです。これらの用途には主となるEメールのRFCに厳密に従っているものもあれば、そうでないものもあります。Eメールを使ったworkingのときでさえも、厳密なRFC準拠にしないのが望ましいことがあります。たとえば、基準に従わないEメールサーバーと相互運用するEメールを作成するときや、基準に違反する方法で使用したい拡張機能を実装するEメールを作成するときです。

これらのばらばらな用途に対応するためPolicyオブジェクトはEメールパッケージに対して柔軟性を提供します。

A Policy object encapsulates a set of attributes and methods that control the behavior of various components of the email package during use. 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 parser classes and the related convenience functions, and for the Message class, this is the Compat32 policy, via its corresponding pre-defined instance 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 EmailMessage is the EmailPolicy policy, via its pre-defined instance default.

When a Message or EmailMessage object is created, it acquires a policy. If the message is created by a 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 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 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 parser module.

The first part of this documentation covers the features of Policy, an abstract base class that defines the features that are common to all policy objects, including 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 EmailPolicy and Compat32, which implement the hooks that provide the standard behavior and the backward compatible behavior and features, respectively.

Policy instances are immutable, but they can be cloned, accepting the same keyword arguments as the class constructor and returning a new 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 sendmail program on a Unix system:

>>> 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()

Here we are telling BytesGenerator to use the RFC correct line separator characters when creating the binary string to feed into sendmail's stdin, where the default policy would use \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 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:

>>> import os
>>> with open('converted.txt', 'wb') as f:
...     f.write(msg.as_bytes(policy=msg.policy.clone(linesep=os.linesep)))
17

Policyオブジェクトは加算オペレータを使用して組み合わせることも可能で、それらのオブジェクトの非デフォルト値を組み合わせた設定を持つPolicyオブジェクトを生成します:

>>> compat_SMTP = policy.compat32.clone(linesep='\r\n')
>>> compat_strict = policy.compat32.clone(raise_on_defect=True)
>>> compat_strict_SMTP = compat_SMTP + compat_strict

この操作には交換法則が成り立ちません。つまり、オブジェクトを加える順番に結果が依存します。次のように説明できます:

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

class email.policy.Policy(**kw)

This is the 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 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:

max_line_length

行の終端文字を数に含まない、シリアライズした出力の任意の行の最大長。デフォルトは RFC 5322 [https://datatracker.ietf.org/doc/html/rfc5322.html] に従い78となっています。値が 0 または None の場合は行の折り返しを全くしないべきであるということを示します。

linesep

The string to be used to terminate lines in serialized output. The default is \n because that's the internal end-of-line discipline used by Python, though \r\n is required by the RFCs.

cte_type

Controls the type of Content Transfer Encodings that may be or are required to be used. The possible values are:

7bit

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.

8bit

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 fold_binary() and utf8 below for exceptions), but body parts may use the 8bit CTE.

A cte_type value of 8bit only works with BytesGenerator, not Generator, because strings cannot contain binary data. If a Generator is operating under a policy that specifies cte_type=8bit, it will act as if cte_type is 7bit.

raise_on_defect

If True, any defects encountered will be raised as errors. If False (the default), defects will be passed to the register_defect() method.

mangle_from_

If True, lines starting with "From " in the body are escaped by putting a > in front of them. This parameter is used when the message is being serialized by a generator. Default: False.

Added in version 3.5.

message_factory

A factory function for constructing a new empty message object. Used by the parser when building messages. Defaults to None, in which case Message is used.

Added in version 3.6.

The following Policy method is intended to be called by code using the email library to create policy instances with custom settings:

clone(**kw)

Return a new Policy instance whose attributes have the same values as the current instance, except where those attributes are given new values by the keyword arguments.

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

handle_defect(obj, defect)

Handle a defect found on obj. When the email package calls this method, defect will always be a subclass of Defect.

The default implementation checks the raise_on_defect flag. If it is True, defect is raised as an exception. If it is False (the default), obj and defect are passed to register_defect().

register_defect(obj, defect)

defect を obj に登録します。email パッケージでは、defect は常に Defect の派生クラスです。

The default implementation calls the append method of the defects attribute of obj. When the email package calls handle_defect, obj will normally have a defects attribute that has an append method. Custom object types used with the email package (for example, custom Message objects) should also provide such an attribute, otherwise defects in parsed messages will raise unexpected errors.

header_max_count(name)

name というヘッダに許される最大の数を返します。

Called when a header is added to an EmailMessage or Message object. If the returned value is not 0 or None, and there are already a number of headers with the name name greater than or equal to the value returned, a ValueError is raised.

Because the default behavior of 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 Message programmatically. (The limit is not observed by the parser, which will faithfully produce as many headers as exist in the message being parsed.)

デフォルトの実装は全てのヘッダ名に None を返します。

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 (name, value) tuple that is to be stored in the 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 ':' separator), while value should be the unfolded value (all line separator characters removed, but whitespace kept intact), stripped of leading whitespace.

sourcelines はサロゲートエスケープされたバイナリーデータを持つことがあります。

デフォルトの実装はありません。

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 Message programmatically (as opposed to a Message created by a parser). The method should return the (name, value) tuple that is to be stored in the 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.

デフォルトの実装はありません。

header_fetch_parse(name, value)

The email package calls this method with the name and value currently stored in the 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 Message; the method is passed the specific name and value of the header destined to be returned to the application.

value はサロゲートエスケープされたバイナリーデータを持つことがあります。このメソッドの返り値にはサロゲートエスケープされたバイナリーデータはありません。

デフォルトの実装はありません。

fold(name, value)

The email package calls this method with the name and value currently stored in the 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 linesep characters at the appropriate places. See RFC 5322 [https://datatracker.ietf.org/doc/html/rfc5322.html] for a discussion of the rules for folding email headers.

value はサロゲートエスケープされたバイナリーデータを持つことがあります。このメソッドが返す文字列にはサロゲートエスケープされたバイナリーデータはありません。

fold_binary(name, value)

返り値が文字列でなく bytes オブジェクトである点を除けば、fold() と同じです。

value はサロゲートエスケープされたバイナリデータを持つことがあります。これらは返されたbytesオブジェクト内でバイナリデータに変換されることがあります。

class email.policy.EmailPolicy(**kw)

This concrete Policy provides behavior that is intended to be fully compliant with the current email RFCs. These include (but are not limited to) RFC 5322 [https://datatracker.ietf.org/doc/html/rfc5322.html], RFC 2047 [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 str subclasses with attributes that depend on the type of the field. The parsing and folding algorithm fully implement RFC 2047 [https://datatracker.ietf.org/doc/html/rfc2047.html] and RFC 5322 [https://datatracker.ietf.org/doc/html/rfc5322.html].

The default value for the message_factory attribute is EmailMessage.

In addition to the settable attributes listed above that apply to all policies, this policy adds the following additional attributes:

Added in version 3.6: [1]

utf8

If False, follow RFC 5322 [https://datatracker.ietf.org/doc/html/rfc5322.html], supporting non-ASCII characters in headers by encoding them as "encoded words". If True, follow RFC 6532 [https://datatracker.ietf.org/doc/html/rfc6532.html] and use utf-8 encoding for headers. Messages formatted in this way may be passed to SMTP servers that support the SMTPUTF8 extension (RFC 6531 [https://datatracker.ietf.org/doc/html/rfc6531.html]).

refold_source

If the value for a header in the Message object originated from a 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:

none

all source values use original folding

long

source values that have any line that is longer than max_line_length will be refolded

all

all values are refolded.

デフォルトは long です。

header_factory

A callable that takes two arguments, name and value, where name is a header field name and value is an unfolded header field value, and returns a string subclass that represents that header. A default header_factory (see headerregistry) is provided that supports custom parsing for the various address and date RFC 5322 [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.

content_manager

An object with at least two methods: get_content and set_content. When the get_content() or set_content() method of an 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 content_manager is set to raw_data_manager.

Added in version 3.4.

このクラスは Policy の抽象メソッドの具象実装を提供します:

header_max_count(name)

Returns the value of the max_count attribute of the specialized class used to represent the header with the given name.

header_source_parse(sourcelines)

The name is parsed as everything up to the ':' 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.

header_store_parse(name, value)

The name is returned unchanged. If the input value has a name attribute and it matches name ignoring case, the value is returned unchanged. Otherwise the name and value are passed to header_factory, and the resulting header object is returned as the value. In this case a ValueError is raised if the input value contains CR or LF characters.

header_fetch_parse(name, value)

If the value has a name attribute, it is returned to unmodified. Otherwise the name, and the value with any CR or LF characters removed, are passed to the header_factory, and the resulting header object is returned. Any surrogateescaped bytes get turned into the unicode unknown-character glyph.

fold(name, value)

Header folding is controlled by the refold_source policy setting. A value is considered to be a 'source value' if and only if it does not have a name attribute (having a 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 header_factory. Folding of a header object is done by calling its fold method with the current policy.

Source values are split into lines using splitlines(). If the value is not to be refolded, the lines are rejoined using the 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 refold_source setting, which causes the binary data to be CTE encoded using the unknown-8bit charset.

fold_binary(name, value)

返り値が bytes である点を除いて、cte_type が 7bit の場合は fold() と同じです。

If cte_type is 8bit, non-ASCII binary data is converted back into bytes. Headers with binary data are not refolded, regardless of the refold_header setting, since there is no way to know whether the binary data consists of single byte characters or multibyte characters.

The following instances of EmailPolicy provide defaults suitable for specific application domains. Note that in the future the behavior of these instances (in particular the HTTP instance) may be adjusted to conform even more closely to the RFCs relevant to their domains.

email.policy.default

デフォルト値を変更していない EmailPolicy のインスタンスです。このポリシーの行末は、 RFC で正しい \r\n ではなく Python の標準の \n です。

email.policy.SMTP

Suitable for serializing messages in conformance with the email RFCs. Like default, but with linesep set to \r\n, which is RFC compliant.

email.policy.SMTPUTF8

The same as SMTP except that utf8 is 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 smtplib.SMTP.send_message() method handles this automatically).

email.policy.HTTP

Suitable for serializing headers with for use in HTTP traffic. Like SMTP except that max_line_length is set to None (unlimited).

email.policy.strict

Convenience instance. The same as default except that raise_on_defect is set to True. This allows any policy to be made strict by writing:

somepolicy + policy.strict

With all of these EmailPolicies, the effective API of the email package is changed from the Python 3.2 API in the following ways:

Setting a header on a Message results in that header being parsed and a header object created.

Fetching a header value from a Message results in that header being parsed and a header object created and returned.

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.

From the application view, this means that any header obtained through the 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.

ヘッダオブジェクトとその属性は headerregistry で述べられています。

class email.policy.Compat32(**kw)

This concrete Policy is the backward compatibility policy. It replicates the behavior of the email package in Python 3.2. The policy module also defines an instance of this class, compat32, that is used as the default policy. Thus the default behavior of the email package is to maintain compatibility with Python 3.2.

以下の属性は Policy デフォルトとは異なる値を持ちます:

mangle_from_

デフォルトは True です。

このクラスは Policy の抽象メソッドの具象実装を提供します:

header_source_parse(sourcelines)

The name is parsed as everything up to the ':' 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.

header_store_parse(name, value)

名前と値は変更されずに返されます。

header_fetch_parse(name, value)

If the value contains binary data, it is converted into a Header object using the unknown-8bit charset. Otherwise it is returned unmodified.

fold(name, value)

Headers are folded using the Header folding algorithm, which preserves existing line breaks in the value, and wraps each resulting line to the max_line_length. Non-ASCII binary data are CTE encoded using the unknown-8bit charset.

fold_binary(name, value)

Headers are folded using the Header folding algorithm, which preserves existing line breaks in the value, and wraps each resulting line to the max_line_length. If cte_type is 7bit, non-ascii binary data is CTE encoded using the unknown-8bit charset. Otherwise the original source header is used, with its existing line breaks and any (RFC invalid) binary data it may contain.

email.policy.compat32

Compat32 のインスタンスで、Python 3.2 の email パッケージの挙動との後方互換性を提供します。

脚注

[1]

Originally added in 3.3 as a provisional feature.

email.errors: Exception and Defect classes

ソースコード: Lib/email/errors.py [https://github.com/python/cpython/tree/3.12/Lib/email/errors.py]

email.errors モジュールでは、以下の例外クラスが定義されています:

exception email.errors.MessageError

これは email パッケージが送出しうるすべての例外の基底クラスです。これは標準の Exception クラスから派生しており、追加のメソッドは定義されていません。

exception email.errors.MessageParseError

This is the base class for exceptions raised by the Parser class. It is derived from MessageError. This class is also used internally by the parser used by headerregistry.

exception email.errors.HeaderParseError

Raised under some error conditions when parsing the RFC 5322 [https://datatracker.ietf.org/doc/html/rfc5322.html] headers of a message, this class is derived from MessageParseError. The set_boundary() method will raise this error if the content type is unknown when the method is called. 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).

exception email.errors.BoundaryError

Deprecated and no longer used.

exception email.errors.MultipartConversionError

この例外は、 Message オブジェクトに add_payload() メソッドでペイロードを追加したが、そのペイロードがすでにスカラー値で、メッセージの Content-Type メインタイプが multipart でないか見付からない場合に送出されます。 MultipartConversionError は MessageError と組み込みの TypeError を多重継承しています。

Message.add_payload() は非推奨なので、実際のところこの例外が送出されることはほとんどありません。しかしながら、 attach() メソッドを MIMENonMultipart から派生したインスタンス (たとえば MIMEImage) に対して呼んだ場合にも送出されることがあります。

exception email.errors.MessageDefect

This is the base class for all defects found when parsing email messages. It is derived from ValueError.

exception email.errors.HeaderDefect

This is the base class for all defects found when parsing email headers. It is derived from MessageDefect.

以下は FeedParser がメッセージの解析中に検出する障害 (defect) の一覧です。これらの障害は、問題が見つかったメッセージに追加されるため、たとえば multipart/alternative 内にあるネストしたメッセージが異常なヘッダをもっていた場合には、そのネストしたメッセージが障害を持っているが、その親メッセージには障害はないとみなされることに注意してください。

すべての障害クラスは email.errors.MessageDefect のサブクラスです。

NoBoundaryInMultipartDefect -- メッセージが multipart だと宣言されているのに、 boundary パラメータがありません。

StartBoundaryNotFoundDefect -- Content-Type ヘッダで宣言された開始境界がありません。

CloseBoundaryNotFoundDefect -- 開始境界はあるが対応する終了境界がありません。

Added in version 3.3.

FirstHeaderLineIsContinuationDefect -- メッセージの最初のヘッダ行が継続行です。

MisplacedEnvelopeHeaderDefect -- ヘッダブロックの途中に "Unix From" ヘッダがあります。

MissingHeaderBodySeparatorDefect - 先頭に空白はないが ':' がないヘッダの解析中に行が見付かりました。その行を本体の最初の行とみなして解析を続けます。

Added in version 3.3.

MalformedHeaderDefect -- ヘッダにコロンがありません、あるいはそれ以外の不正な形式です。

バージョン 3.3 で非推奨: この欠陥が使われていないPythonバージョンがいくつかあります。

MultipartInvariantViolationDefect -- メッセージが multipart だと宣言されているのに、サブパートが存在しません。メッセージがこの欠陥を持つ場合、内容の型が multipart と宣言されていても is_multipart() メソッドは False を返すことがあるので注意してください。

InvalidBase64PaddingDefect -- 一連の base64 でエンコードされた bytes をデコードしているときにパディングが誤っていました。デコードするのに十分なパディングがなされますが、デコードされた bytes は不正かもしれません。

InvalidBase64CharactersDefect -- 一連の base64 でエンコードされた bytes をデコードしているときに base64 アルファベット外の文字がありました。その文字は無視されますが、デコードされた bytes は不正かもしれません。

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.

InvalidDateDefect -- When decoding an invalid or unparsable date field. The original value is kept as-is.

email.headerregistry: Custom Header Objects

ソースコード: Lib/email/headerregistry.py [https://github.com/python/cpython/tree/3.12/Lib/email/headerregistry.py]

Added in version 3.6: [1]

ヘッダーは str のカスタマイズされたサブクラスで表現されます。 与えられたヘッダーを表現するために使用される特定のクラスは、ヘッダーが作成されるときに有効な policy の header_factory で決定されます。 このセクションでは、email ライブラリが RFC 5322 [https://datatracker.ietf.org/doc/html/rfc5322.html] に準拠したメールメッセージを扱うために実装している、特定の header_factory について説明します。このヘッダーは、様々なヘッダータイプに対してカスタマイズされたヘッダーオブジェクトを提供するだけでなく、アプリケーションが独自のカスタムヘッダータイプを追加できるような拡張メカニズムも備えています。

EmailPolicy から派生したポリシーオブジェクトのいずれかを使用する場合、すべてのヘッダーは HeaderRegistry によって生成され、最終的な基底クラスとして BaseHeader を有します。 各ヘッダクラスには、ヘッダの種類によって決まる追加のベースクラスがあります。 例えば、多くのヘッダーは UnstructuredHeader というクラスをもうひとつの基底クラスとして持っています。 ヘッダーに特化した第二のクラスは、ヘッダーの名前によって決定され、 HeaderRegistry に格納されたルックアップテーブルを使用します。 これらすべては、典型的なアプリケーションプログラムに対しては透過的に管理されますが、より複雑なアプリケーションで使用するためにデフォルトの動作を変更するためのインタフェースが提供されています。

以下のセクションでは、まずヘッダーの基本クラスとその属性を説明し、次に HeaderRegistry の動作を変更するための API、そして最後に構造化ヘッダーからパースされたデータを表現するためのサポートクラスについて説明します。

class email.headerregistry.BaseHeader(name, value)

name と value は header_factory 呼び出しから BaseHeader に渡されます。 どのヘッダーオブジェクトの文字列値も、完全にユニコードにデコードされた value です。

基底クラスは以下の読み出し専用属性を定義しています:

name

ヘッダーの名前(フィールドの':'の前の部分)。これは header_factory の name の呼び出しで渡された値と全く同じです; つまり、大文字・小文字が保持されます。

defects

パース中に見つかったRFCのコンプライアンス問題を報告する HeaderDefect インスタンスのタプルです。 email パッケージはコンプライアンスに関する問題を完全に検出するように努めています。 報告されるかもしれない欠陥の種類の議論については、 errors モジュールを参照してください。

max_count

このタイプのヘッダーで、同じ name を持つことができる最大数。 値として None を指定すると、無制限になります。 この属性の BaseHeader の値は None です; 特殊な header クラスでは、必要に応じてこの値をオーバーライドすることが期待されます。

BaseHeader は以下のメソッドも提供します。このメソッドはemail ライブラリのコードから呼び出され、一般にアプリケーションプログラムからは呼び出されません：

fold(*, policy)

ヘッダを policy に従って正しく折りたたむために必要な linesep 文字を含む文字列を返します。 ヘッダには任意のバイナリデータを含めることができないため、 cte_type が 8bit の場合は 7bit と同じように扱われます。 もし utf8 が False であれば、非ASCIIデータは RFC 2047 [https://datatracker.ietf.org/doc/html/rfc2047.html] でエンコードされます。

BaseHeader 自身はヘッダーオブジェクトを生成するために使用することはできません。このクラスは、それぞれの特殊化ヘッダーがヘッダーオブジェクトを生成するために協力するプロトコルを定義しています。 具体的には、 BaseHeader は parse という名前の classmethod() を特殊化されたクラスが提供することを要求しています。このメソッドは以下のように呼び出されます:

parse(string, kwds)

kwds は、初期化されたキー defects を含む辞書です。defects は空のリストです。 解析メソッドは、検出された不具合をこのリストに追加するべきです。 returnの際には、 kwds 辞書に少なくとも decoded と``defects`` のキーを含む必要があります。 decoded はヘッダの文字列値 (つまり、ヘッダを Unicode に完全にデコードした値) でなければなりません。 parseメソッドは、 string がcontent-transfer-encodedな部分を含む可能性があると仮定すべきですが、エンコードされていないヘッダ値をパースできるように、すべての有効なUnicode文字も正しく処理する必要があります。

その後、 BaseHeader の __new__ がヘッダのインスタンスを生成し、 init メソッドを呼び出します。 特殊クラスは、 BaseHeader が提供しない属性を設定したい場合にのみ init メソッドを提供する必要があります。 このような``init`` メソッドは以下のようなものです：

def init(self, /, *args, **kw):
    self._myattr = kw.pop('myattr')
    super().init(*args, **kw)

つまり、特殊クラスが kwds の辞書に追加したものはすべて削除して処理し、 kw``の残りの内容 (と ``args) は``BaseHeader`` の``init`` メソッドに渡す必要があるのです。

class email.headerregistry.UnstructuredHeader

"unstructured" ヘッダは RFC 5322 [https://datatracker.ietf.org/doc/html/rfc5322.html] におけるデフォルトのヘッダのタイプです。指定された構文を持たないすべてのヘッダは、unstructuredとして扱われます。 構造化されていないヘッダの典型的な例は Subject ヘッダです。

RFC 5322 [https://datatracker.ietf.org/doc/html/rfc5322.html] では、非構造化ヘッダは ASCII 文字セットの任意のテキストの集まりです。しかし、 RFC 2047 [https://datatracker.ietf.org/doc/html/rfc2047.html] にはヘッダ値の中で非 ASCII テキストを ASCII 文字としてエンコードするための RFC 5322 [https://datatracker.ietf.org/doc/html/rfc5322.html] と互換性のあるメカニズムが備わっています。 エンコードされた単語を含む value がコンストラクタに渡されると、 UnstructuredHeader パーサは非構造化テキストに対する RFC 2047 [https://datatracker.ietf.org/doc/html/rfc2047.html] 規則に従って、エンコードされた単語を unicode に変換します。 パーサは特定の非適合なエンコードされた単語のデコードを試みるためにヒューリスティックを使用します。 このような場合、欠陥が登録されます。また、エンコードされた単語やエンコードされていないテキスト内の無効な文字などの問題に対しても欠陥が登録されます。

このヘッダ型には追加の属性はありません。

class email.headerregistry.DateHeader

RFC 5322 [https://datatracker.ietf.org/doc/html/rfc5322.html] specifies a very specific format for dates within email headers. The DateHeader parser recognizes that date format, as well as recognizing a number of variant forms that are sometimes found "in the wild".

このヘッダ型は以下の属性も提供しています:

datetime

If the header value can be recognized as a valid date of one form or another, this attribute will contain a datetime instance representing that date. If the timezone of the input date is specified as -0000 (indicating it is in UTC but contains no information about the source timezone), then datetime will be a naive datetime. If a specific timezone offset is found (including +0000), then datetime will contain an aware datetime that uses datetime.timezone to record the timezone offset.

ヘッダーの decoded 値は、 datetime を RFC 5322 [https://datatracker.ietf.org/doc/html/rfc5322.html] のルールに従ってフォーマットすることで決定されます。

email.utils.format_datetime(self.datetime)

DateHeader を作成する際に、 value は datetime インスタンスである可能性があります。 これは、例えば、次のようなコードは有効であり、期待通りの動作をすることを意味します:

msg['Date'] = datetime(2011, 7, 15, 21)

これは単純な datetime であるため、UTC タイムスタンプとして解釈され、結果として -0000 というタイムゾーンを持つ値になります。 もっと便利なのは utils モジュールの localtime() 関数を使用することです:

msg['Date'] = utils.localtime()

この例では、現在のタイムゾーンオフセットを使用して、日付ヘッダーを現在の時刻と日付に設定します。

class email.headerregistry.AddressHeader

アドレスヘッダは最も複雑な構造のヘッダタイプの1つです。 AddressHeader クラスは、あらゆるアドレスヘッダに対する汎用的なインターフェースを提供します。

このヘッダ型は以下の属性も提供しています:

groups

ヘッダー値に含まれるアドレスとグループをエンコードした Group オブジェクトのタプルです。 グループに属さないアドレスは、このリストでは display_name が None であるシングルアドレスの Groups として表現されます。

addresses

ヘッダー値に含まれる全ての個別アドレスをエンコードした Address オブジェクトのタプルです。 ヘッダ値にグループが含まれている場合、そのグループに含まれる個々のアドレスは、ヘッダ値でグループが出現した時点でリストに含まれます (つまり、アドレスのリストは一次元のリストに「フラット化」されます)。

The decoded value of the header will have all encoded words decoded to unicode. idna encoded domain names are also decoded to unicode. The decoded value is set by joining the str value of the elements of the groups attribute with ', '.

A list of Address and Group objects in any combination may be used to set the value of an address header. Group objects whose display_name is 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 groups attribute of the source header.

class email.headerregistry.SingleAddressHeader

追加の属性を 1 つ持つ、AddressHeader の派生クラスです:

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 policy), accessing this attribute will result in a ValueError.

Many of the above classes also have a Unique variant (for example, UniqueUnstructuredHeader). The only difference is that in the Unique variant, max_count is set to 1.

class email.headerregistry.MIMEVersionHeader

There is really only one valid value for the MIME-Version header, and that is 1.0. For future proofing, this header class supports other valid version numbers. If a version number has a valid value per RFC 2045 [https://datatracker.ietf.org/doc/html/rfc2045.html], then the header object will have non-None values for the following attributes:

version

バージョン番号 (文字列)、空白やコメントは除かれます。

major

メジャーバージョン番号 (整数)

minor

マイナーバージョン番号 (整数)

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

params

A dictionary mapping parameter names to parameter values.

class email.headerregistry.ContentTypeHeader

Content-Type ヘッダを扱う ParameterizedMIMEHeader クラスです。

content_type

The content type string, in the form maintype/subtype.

maintype

subtype

class email.headerregistry.ContentDispositionHeader

Content-Disposition ヘッダを扱う ParameterizedMIMEHeader クラスです。

content_disposition

inline and attachment are the only valid values in common use.

class email.headerregistry.ContentTransferEncoding

Content-Transfer-Encoding ヘッダを扱います。

cte

有効な値は 7bit、8bit、base64、quoted-printable です。詳細については RFC 2045 [https://datatracker.ietf.org/doc/html/rfc2045.html] を参照してください。

class email.headerregistry.HeaderRegistry(base_class=BaseHeader, default_class=UnstructuredHeader, use_default_map=True)

This is the factory used by EmailPolicy by default. 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 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 __bases__ list.

デフォルトのマッピング:

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

HeaderRegistry には以下のメソッドがあります:

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.

__getitem__(name)

Construct and return a class to handle creating a name header.

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

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.

class email.headerregistry.Address(display_name='', username='', domain='', addr_spec=None)

このクラスは電子メールのアドレスを表すのに使われます。アドレスの一般的な形式は:

[display_name] <username@domain>

もしくは:

username@domain

where each part must conform to specific syntax rules spelled out in RFC 5322 [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 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.

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.

username

アドレスの username 部分、クォートは取り除かれます。

domain

アドレスの domain 部分。

addr_spec

The username@domain portion of the address, correctly quoted for use as a bare address (the second form shown above). This attribute is not mutable.

__str__()

The str value of the object is the address quoted according to RFC 5322 [https://datatracker.ietf.org/doc/html/rfc5322.html] rules, but with no Content Transfer Encoding of any non-ASCII characters.

To support SMTP (RFC 5321 [https://datatracker.ietf.org/doc/html/rfc5321.html]), Address handles one special case: if username and domain are both the empty string (or None), then the string value of the Address is <>.

class email.headerregistry.Group(display_name=None, addresses=None)

このクラスはアドレスグループを表すのに使われます。アドレスグループの一般的な形式は:

display_name: [address-list];

As a convenience for processing lists of addresses that consist of a mixture of groups and single addresses, a Group may also be used to represent single addresses that are not part of a group by setting display_name to None and providing a list of the single address as addresses.

display_name

The display_name of the group. If it is None and there is exactly one Address in addresses, then the Group represents a single address that is not in a group.

addresses

A possibly empty tuple of Address objects representing the addresses in the group.

__str__()

The str value of a Group is formatted according to RFC 5322 [https://datatracker.ietf.org/doc/html/rfc5322.html], but with no Content Transfer Encoding of any non-ASCII characters. If display_name is none and there is a single Address in the addresses list, the str value will be the same as the str of that single Address.

脚注

[1]

Originally added in 3.3 as a provisional module

email.contentmanager: Managing MIME Content

ソースコード: Lib/email/contentmanager.py [https://github.com/python/cpython/tree/3.12/Lib/email/contentmanager.py]

Added in version 3.6: [1]

class 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 get_content and set_content dispatch methods.

get_content(msg, *args, **kw)

Look up a handler function based on the 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:

完全な MIME 型を表す文字列 (maintype/subtype)

maintype を表す文字列

空の文字列

If none of these keys produce a handler, raise a KeyError for the full MIME type.

set_content(msg, obj, *args, **kw)

If the maintype is multipart, raise a TypeError; otherwise look up a handler function based on the type of obj (see next paragraph), call 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 (typ = type(obj)), and look for the following keys in the registry, stopping with the first one found:

型自身 (typ)

型の完全修飾名 (typ.__module__ + '.' + typ.__qualname__).

型の qualname (typ.__qualname__)

型の name (typ.__name__).

If none of the above match, repeat all of the checks above for each of the types in the MRO (typ.__mro__). Finally, if no other key yields a handler, check for a handler for the key None. If there is no handler for None, raise a KeyError for the fully qualified name of the type.

Also add a MIME-Version header if one is not present (see also MIMEPart).

add_get_handler(key, handler)

Record the function handler as the handler for key. For the possible values of key, see get_content().

add_set_handler(typekey, handler)

Record handler as the function to call when an object of a type matching typekey is passed to set_content(). For the possible values of typekey, see set_content().

Content Manager Instances

Currently the email package provides only one concrete content manager, raw_data_manager, although more may be added in the future. raw_data_manager is the content_manager provided by EmailPolicy and its derivatives.

email.contentmanager.raw_data_manager

This content manager provides only a minimum interface beyond that provided by Message itself: it deals only with text, raw byte strings, and Message objects. Nevertheless, it provides significant advantages compared to the base API: get_content on a text part will return a unicode string without the application needing to manually decode it, 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 add_ methods, thereby simplifying the creation of multipart messages.

email.contentmanager.get_content(msg, errors='replace')

Return the payload of the part as either a string (for text parts), an EmailMessage object (for message/rfc822 parts), or a bytes object (for all other non-multipart types). Raise a KeyError if called on a multipart. If the part is a text part and errors is specified, use it as the error handler when decoding the payload to unicode. The default error handler is replace.

email.contentmanager.set_content(msg, <'str'>, subtype="plain", charset='utf-8', cte=None, disposition=None, filename=None, cid=None, params=None, headers=None)

email.contentmanager.set_content(msg, <'bytes'>, maintype, subtype, cte="base64", disposition=None, filename=None, cid=None, params=None, headers=None)

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 Content-Type header with a maintype/subtype value.

For str, set the MIME maintype to text, and set the subtype to subtype if it is specified, or plain if it is not.

For bytes, use the specified maintype and subtype, or raise a TypeError if they are not specified.

For EmailMessage objects, set the maintype to message, and set the subtype to subtype if it is specified or rfc822 if it is not. If subtype is partial, raise an error (bytes objects must be used to construct message/partial parts).

If charset is provided (which is valid only for str), encode the string to bytes using the specified character set. The default is 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 Content-Transfer-Encoding header to that value. Possible values for cte are quoted-printable, base64, 7bit, 8bit, and binary. If the input cannot be encoded in the specified encoding (for example, specifying a cte of 7bit for an input that contains non-ASCII values), raise a ValueError.

For str objects, if cte is not set use heuristics to determine the most compact encoding.

For EmailMessage, per RFC 2046 [https://datatracker.ietf.org/doc/html/rfc2046.html], raise an error if a cte of quoted-printable or base64 is requested for subtype rfc822, and for any cte other than 7bit for subtype external-body. For message/rfc822, use 8bit if cte is not specified. For all other values of subtype, use 7bit.

注釈

A cte of binary does not actually work correctly yet. The EmailMessage object as modified by set_content is correct, but BytesGenerator does not serialize it correctly.

If disposition is set, use it as the value of the Content-Disposition header. If not specified, and filename is specified, add the header with the value attachment. If disposition is not specified and filename is also not specified, do not add the header. The only valid values for disposition are attachment and inline.

If filename is specified, use it as the value of the filename parameter of the Content-Disposition header.

If cid is specified, add a Content-ID header with cid as its value.

If params is specified, iterate its items method and use the resulting (key, value) pairs to set additional parameters on the Content-Type header.

If headers is specified and is a list of strings of the form headername: headervalue or a list of header objects (distinguished from strings by having a name attribute), add the headers to msg.

脚注

[1]

Originally added in 3.4 as a provisional module

email: 使用例

ここでは email パッケージを使って電子メールメッセージを読む・書く・送信するいくつかの例を紹介します。より複雑な MIME メッセージについても扱います。

First, let's see how to create and send a simple text message (both the text content and the addresses may contain unicode characters):

# 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()

Parsing RFC 822 [https://datatracker.ietf.org/doc/html/rfc822.html] headers can easily be done by the using the classes from the parser module:

# 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))

つぎに、あるディレクトリ内にある何枚かの家族写真をひとつの MIME メッセージに収めて送信する例です:

# 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)

つぎはあるディレクトリに含まれている内容全体をひとつの電子メールメッセージとして送信するやり方です: [1]

#!/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_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()

つぎに、上のような MIME メッセージをどうやって展開してひとつのディレクトリ上の複数ファイルにするかを示します:

#!/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()

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.

#!/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'] = "Ayons asperges pour le déjeuner"
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!

Cela ressemble à un excellent recipie[1] déjeuner.

[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>Cela ressemble à un excellent
        <a href="http://www.yummly.com/recipe/Roasted-Asparagus-Epicurious-203718">
            recipie
        </a> déjeuner.
    </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)

If we were sent the message from the last example, here is one way we could process it:

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

Up to the prompt, the output from the above is:

To: Penelope Pussycat <penelope@example.com>, Fabrette Pussycat <fabrette@example.com>
From: Pepé Le Pew <pepe@example.com>
Subject: Ayons asperges pour le déjeuner

Salut!

Cela ressemble à un excellent recipie[1] déjeuner.

脚注

[1]

最初の思いつきと用例は Matthew Dixon Cowles のおかげです。

email.message.Message: compat32 API を使用した電子メールメッセージの表現

The Message class is very similar to the 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 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 Message) policy Compat32. If you are going to use another policy, you should be using the EmailMessage class instead.

An email message consists of headers and a payload. Headers must be RFC 5322 [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 multipart/* or message/rfc822.

The conceptual model provided by a 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 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 From_ header. The payload is either a string or bytes, in the case of simple message objects, or a list of Message objects, for MIME container documents (e.g. multipart/* and message/rfc822).

Message クラスのメソッドは以下のとおりです:

class email.message.Message(policy=compat32)

If policy is specified (it must be an instance of a policy class) use the rules it specifies to update and serialize the representation of the message. If policy is not set, use the compat32 policy, which maintains backward compatibility with the Python 3.2 version of the email package. For more information see the policy documentation.

バージョン 3.3 で変更: キーワード引数 policy が追加されました。

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 False. For backward compatibility reasons, maxheaderlen defaults to 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 Generator.

もし、文字列への変換を完全に行うためにデフォルト値を埋める必要がある場合、メッセージのフラット化は Message の変更を引き起こす可能性があります (例えば、MIME の境界が生成される、変更される等)。

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 From that is required by the Unix mbox format. For more flexibility, instantiate a Generator instance and use its flatten() method directly. For 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()

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 as_bytes() and BytesGenerator.)

バージョン 3.4 で変更: policy キーワード引数が追加されました。

__str__()

as_string() と等価です。これにより str(msg) は書式化されたメッセージの文字列を作ります。

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

もし、文字列への変換を完全に行うためにデフォルト値を埋める必要がある場合、メッセージのフラット化は Message の変更を引き起こす可能性があります (例えば、MIME の境界が生成される、変更される等)。

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 From that is required by the Unix mbox format. For more flexibility, instantiate a BytesGenerator instance and use its flatten() method directly. For 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()

Added in version 3.4.

__bytes__()

as_bytes() と等価です。これにより bytes(msg) は書式化されたメッセージの bytes オブジェクトを作ります。

Added in version 3.4.

is_multipart()

Return True if the message's payload is a list of sub-Message objects, otherwise return False. When is_multipart() returns False, the payload should be a string object (which might be a CTE encoded binary payload). (Note that is_multipart() returning True does not necessarily mean that "msg.get_content_maintype() == 'multipart'" will return the True. For example, is_multipart will return True when the Message is of type message/rfc822.)

set_unixfrom(unixfrom)

メッセージのエンベロープヘッダを unixfrom に設定します。これは文字列でなければなりません。

get_unixfrom()

メッセージのエンベロープヘッダを返します。エンベロープヘッダが設定されていない場合は None が返されます。

attach(payload)

与えられた payload を現在のペイロードに追加します。この時点でのペイロードは None か、あるいは Message オブジェクトのリストである必要があります。このメソッドの実行後、ペイロードは必ず Message オブジェクトのリストになります。ペイロードにスカラーオブジェクト (文字列など) を格納したい場合は、かわりに set_payload() を使ってください。

This is a legacy method. On the EmailMessage class its functionality is replaced by set_content() and the related make and add methods.

get_payload(i=None, decode=False)

現在のペイロードへの参照を返します。これは is_multipart() が True の場合 Message オブジェクトのリストになり、 is_multipart() が False の場合は文字列になります。ペイロードがリストの場合、リストを変更することはそのメッセージのペイロードを変更することになります。

オプション引数の i がある場合、 is_multipart() が True ならば get_payload() はペイロード中で 0 から数えて i 番目の要素を返します。 i が 0 より小さい場合、あるいはペイロードの個数以上の場合は IndexError が発生します。ペイロードが文字列 (つまり is_multipart() が False) にもかかわらず i が与えられたときは TypeError が発生します。

Optional decode is a flag indicating whether the payload should be decoded or not, according to the Content-Transfer-Encoding header. When True and the message is not a multipart, the payload will be decoded if this header's value is quoted-printable or base64. If some other encoding is used, or 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 True, then 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 (InvalidBase64PaddingDefect or InvalidBase64CharactersDefect, respectively).

When decode is False (the default) the body is returned as a string without decoding the Content-Transfer-Encoding. However, for a Content-Transfer-Encoding of 8bit, an attempt is made to decode the original bytes using the charset specified by the Content-Type header, using the replace error handler. If no charset is specified, or if the 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 EmailMessage class its functionality is replaced by get_content() and iter_parts().

set_payload(payload, charset=None)

メッセージオブジェクト全体のペイロードを payload に設定します。クライアントはペイロードを変更してはいけません。オプションの charset はメッセージのデフォルト文字セットを設定します。詳しくは set_charset() を参照してください。

This is a legacy method. On the EmailMessage class its functionality is replaced by set_content().

set_charset(charset)

ペイロードの文字セットを charset に変更します。これは Charset インスタンス (email.charset 参照)、文字セット名を表す文字列、あるいは None のいずれかです。文字列を指定した場合は Charset インスタンスに変換されます。 charset が None の場合、 charset 引数は Content-Type ヘッダから除去されます (それ以外にメッセージは変更されません)。これら以外のものを文字セットとして指定した場合、 TypeError を送出します。

MIME-Version ヘッダが存在しなければ、追加されます。 Content-Type ヘッダが存在しなければ、 text/plain を値として追加されます。 Content-Type が存在していてもいなくても、 charset パラメタは charset.output_charset に設定されます。 charset.input_charset と charset.output_charset が異なるなら、ペイロードは output_charset に再エンコードされます。 Content-Transfer-Encoding ヘッダが存在しなければ、ペイロードは、必要なら指定された Charset を使って transfer エンコードされ、適切な値のヘッダが追加されます。 Content-Transfer-Encoding ヘッダがすでに存在すれば、ペイロードはすでにその Content-Transfer-Encoding によって正しくエンコードされたものと見なされ、変形されません。

This is a legacy method. On the EmailMessage class its functionality is replaced by the charset parameter of the email.emailmessage.EmailMessage.set_content() method.

get_charset()

そのメッセージ中のペイロードの Charset インスタンスを返します。

This is a legacy method. On the EmailMessage class it always returns None.

以下のメソッドは、メッセージの RFC 2822 [https://datatracker.ietf.org/doc/html/rfc2822.html] ヘッダにアクセスするためのマップ (辞書) 形式のインタフェイスを実装したものです。これらのメソッドと、通常のマップ (辞書) 型はまったく同じ意味をもつわけではないことに注意してください。たとえば辞書型では、同じキーが複数あることは許されていませんが、ここでは同じメッセージヘッダが複数ある場合があります。また、辞書型では keys() で返されるキーの順序は保証されていませんが、 Message オブジェクト内のヘッダはつねに元のメッセージ中に現れた順序、あるいはそのあとに追加された順序で返されます。削除され、その後ふたたび追加されたヘッダはリストの一番最後に現れます。

こういった意味のちがいは意図的なもので、最大の利便性をもつようにつくられています。

注意: どんな場合も、メッセージ中のエンベロープヘッダはこのマップ形式のインタフェイスには含まれません。

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 Header objects with a charset of unknown-8bit.

__len__()

複製されたものもふくめてヘッダ数の合計を返します。

__contains__(name)

メッセージオブジェクトが name という名前のフィールドを持っていれば True を返します。この検査では名前の大文字小文字は区別されません。name は最後にコロンをふくんでいてはいけません。このメソッドは以下のように in 演算子で使われます:

if 'message-id' in myMessage:
   print('Message-ID:', myMessage['message-id'])

__getitem__(name)

指定された名前のヘッダフィールドの値を返します。 name は最後にコロンをふくんでいてはいけません。そのヘッダがない場合は None が返され、 KeyError 例外は発生しません。

注意: 指定された名前のフィールドがメッセージのヘッダに2回以上現れている場合、どちらの値が返されるかは未定義です。ヘッダに存在するフィールドの値をすべて取り出したい場合は get_all() メソッドを使ってください。

__setitem__(name, val)

メッセージヘッダに name という名前の val という値をもつフィールドをあらたに追加します。このフィールドは現在メッセージに存在するフィールドのいちばん後に追加されます。

注意: このメソッドでは、すでに同一の名前で存在するフィールドは上書き されません。もしメッセージが名前 name をもつフィールドをひとつしか持たないようにしたければ、最初にそれを除去してください。たとえば:

del msg['subject']
msg['subject'] = 'Python roolz!'

__delitem__(name)

メッセージのヘッダから、name という名前をもつフィールドをすべて除去します。たとえこの名前をもつヘッダが存在していなくても例外は発生しません。

keys()

メッセージ中にあるすべてのヘッダのフィールド名のリストを返します。

values()

メッセージ中にあるすべてのフィールドの値のリストを返します。

items()

メッセージ中にあるすべてのヘッダのフィールド名とその値を 2-タプルのリストとして返します。

get(name, failobj=None)

Return the value of the named header field. This is identical to __getitem__() except that optional failobj is returned if the named header is missing (defaults to None).

さらに、役に立つメソッドをいくつか紹介します:

get_all(name, failobj=None)

name の名前をもつフィールドのすべての値からなるリストを返します。該当する名前のヘッダがメッセージ中に含まれていない場合は failobj (デフォルトでは None) が返されます。

add_header(_name, _value, **_params)

拡張ヘッダ設定。このメソッドは __setitem__() と似ていますが、追加のヘッダ・パラメータをキーワード引数で指定できるところが違っています。 _name に追加するヘッダフィールドを、 _value にそのヘッダの 最初の 値を渡します。

キーワード引数辞書 _params の各項目ごとに、そのキーがパラメータ名として扱われ、キー名にふくまれるアンダースコアはハイフンに置換されます (アンダースコアは、Python 識別子としてハイフンを使えないための代替です)。ふつう、パラメータの値が None 以外のときは、 key="value" の形で追加されます。パラメータの値が None のときはキーのみが追加されます。値が非 ASCII 文字を含むなら、それは (CHARSET, LANGUAGE, VALUE) の形式の 3 タプルにすることが出来ます。ここで CHARSET はその値をエンコードするのに使われる文字セットを指示する文字列で、 LANGUAGE は通常 None か空文字列にでき (これら以外で指定出来るものについては RFC 2231 [https://datatracker.ietf.org/doc/html/rfc2231.html] を参照してください)、 VALUE は非 ASCII コードポイントを含む文字列値です。この 3 タプルではなく非 ASCII 文字を含む値が渡された場合は、 CHARSET に utf-8 、 LANGUAGE に None を使って RFC 2231 [https://datatracker.ietf.org/doc/html/rfc2231.html] 形式に自動的にエンコードされます。

以下はこの使用例です:

msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')

こうするとヘッダには以下のように追加されます

Content-Disposition: attachment; filename="bud.gif"

非 ASCII 文字を使った例:

msg.add_header('Content-Disposition', 'attachment',
               filename=('iso-8859-1', '', 'Fußballer.ppt'))

は、以下のようになります

Content-Disposition: attachment; filename*="iso-8859-1''Fu%DFballer.ppt"

replace_header(_name, _value)

ヘッダの置換。 _name と一致するヘッダで最初に見つかったものを置き換えます。このときヘッダの順序とフィールド名の大文字小文字は保存されます。一致するヘッダがない場合、 KeyError が発生します。

get_content_type()

そのメッセージの content-type を返します。返された文字列は強制的に小文字で maintype/subtype の形式に変換されます。メッセージ中に Content-Type ヘッダがない場合、デフォルトの content-type は get_default_type() が返す値によって与えられます。 RFC 2045 [https://datatracker.ietf.org/doc/html/rfc2045.html] によればメッセージはつねにデフォルトの content-type をもっているので、 get_content_type() はつねになんらかの値を返すはずです。

RFC 2045 [https://datatracker.ietf.org/doc/html/rfc2045.html] はメッセージのデフォルト content-type を、それが multipart/digest コンテナに現れているとき以外は text/plain に規定しています。あるメッセージが multipart/digest コンテナ中にある場合、その content-type は message/rfc822 になります。もし Content-Type ヘッダが適切でない content-type 書式だった場合、 RFC 2045 [https://datatracker.ietf.org/doc/html/rfc2045.html] はそれのデフォルトを text/plain として扱うよう定めています。

get_content_maintype()

そのメッセージの主 content-type を返します。これは get_content_type() によって返される文字列の maintype 部分です。

get_content_subtype()

そのメッセージの副 content-type (sub content-type、subtype) を返します。これは get_content_type() によって返される文字列の subtype 部分です。

get_default_type()

デフォルトの content-type を返します。ほどんどのメッセージではデフォルトの content-type は text/plain ですが、メッセージが multipart/digest コンテナに含まれているときだけ例外的に message/rfc822 になります。

set_default_type(ctype)

デフォルトの content-type を設定します。 ctype は text/plain あるいは message/rfc822 である必要がありますが、強制ではありません。デフォルトの content-type はヘッダの Content-Type には格納されません。

get_params(failobj=None, header='content-type', unquote=True)

メッセージの Content-Type パラメータをリストとして返します。返されるリストはキー/値の組からなる2要素タプルが連なったものであり、これらは '=' 記号で分離されています。 '=' の左側はキーになり、右側は値になります。パラメータ中に '=' がなかった場合、値の部分は空文字列になり、そうでなければその値は get_param() で説明されている形式になります。また、オプション引数 unquote が True (デフォルト) である場合、この値は unquote されます。

オプション引数 failobj は、 Content-Type ヘッダが存在しなかった場合に返すオブジェクトです。オプション引数 header には Content-Type のかわりに検索すべきヘッダを指定します。

This is a legacy method. On the EmailMessage class its functionality is replaced by the params property of the individual header objects returned by the header access methods.

get_param(param, failobj=None, header='content-type', unquote=True)

メッセージの Content-Type ヘッダ中のパラメータ param を文字列として返します。そのメッセージ中に Content-Type ヘッダが存在しなかった場合、 failobj (デフォルトは None) が返されます。

オプション引数 header が与えられた場合、 Content-Type のかわりにそのヘッダが使用されます。

パラメータのキー比較は常に大文字小文字を区別しません。返り値は文字列か 3 要素のタプルで、タプルになるのはパラメータが RFC 2231 [https://datatracker.ietf.org/doc/html/rfc2231.html] エンコードされている場合です。3 要素タプルの場合、各要素の値は (CHARSET, LANGUAGE, VALUE) の形式になっています。 CHARSET と LAGUAGE は None になることがあり、その場合 VALUE は us-ascii 文字セットでエンコードされているとみなさなければならないので注意してください。普段は LANGUAGE を無視できます。

この関数を使うアプリケーションが、パラメータが RFC 2231 [https://datatracker.ietf.org/doc/html/rfc2231.html] 形式でエンコードされているかどうかを気にしないのであれば、 email.utils.collapse_rfc2231_value() に get_param() の返り値を渡して呼び出すことで、このパラメータをひとつにまとめることができます。この値がタプルならばこの関数は適切にデコードされた Unicode 文字列を返し、そうでない場合は unquote された元の文字列を返します。たとえば:

rawparam = msg.get_param('foo')
param = email.utils.collapse_rfc2231_value(rawparam)

いずれの場合もパラメータの値は (文字列であれ3要素タプルの VALUE 項目であれ) つねに unquote されます。ただし、unquote が False に指定されている場合は unquote されません。

This is a legacy method. On the EmailMessage class its functionality is replaced by the params property of the individual header objects returned by the header access methods.

set_param(param, value, header='Content-Type', requote=True, charset=None, language='', replace=False)

Content-Type ヘッダ中のパラメータを設定します。指定されたパラメータがヘッダ中にすでに存在する場合、その値は value に置き換えられます。 Content-Type ヘッダがまだこのメッセージ中に存在していない場合、 RFC 2045 [https://datatracker.ietf.org/doc/html/rfc2045.html] にしたがいこの値には text/plain が設定され、新しいパラメータ値が末尾に追加されます。

オプション引数 header が与えられた場合、 Content-Type のかわりにそのヘッダが使用されます。オプション引数 requote が False でない限り、この値は quote されます (デフォルトは True)。

オプション引数 charset が与えられると、そのパラメータは RFC 2231 [https://datatracker.ietf.org/doc/html/rfc2231.html] に従ってエンコードされます。オプション引数 language は RFC 2231 の言語を指定しますが、デフォルトではこれは空文字列となります。 charset と language はどちらも文字列である必要があります。

If replace is False (the default) the header is moved to the end of the list of headers. If replace is True, the header will be updated in place.

バージョン 3.4 で変更: replace キーワードが追加されました。

del_param(param, header='content-type', requote=True)

指定されたパラメータを Content-Type ヘッダ中から完全にとりのぞきます。ヘッダはそのパラメータと値がない状態に書き換えられます。 requote が False でない限り (デフォルトでは True です)、すべての値は必要に応じて quote されます。オプション変数 header が与えられた場合、 Content-Type のかわりにそのヘッダが使用されます。

set_type(type, header='Content-Type', requote=True)

Content-Type ヘッダの maintype と subtype を設定します。 type は maintype/subtype という形の文字列でなければなりません。それ以外の場合は ValueError が発生します。

このメソッドは Content-Type ヘッダを置き換えますが、すべてのパラメータはそのままにします。 requote が False の場合、これはすでに存在するヘッダを quote せず放置しますが、そうでない場合は自動的に quote します (デフォルト動作)。

オプション変数 header が与えられた場合、 Content-Type のかわりにそのヘッダが使用されます。 Content-Type ヘッダが設定される場合には、 MIME-Version ヘッダも同時に付加されます。

This is a legacy method. On the EmailMessage class its functionality is replaced by the make_ and add_ methods.

get_filename(failobj=None)

そのメッセージ中の Content-Disposition ヘッダにある、 filename パラメータの値を返します。目的のヘッダに filename パラメータがない場合には Content-Type ヘッダにある name パラメータを探します。それも無い場合またはヘッダが無い場合には failobj が返されます。返される文字列はつねに email.utils.unquote() によって unquote されます。

get_boundary(failobj=None)

そのメッセージ中の Content-Type ヘッダにある、 boundary パラメータの値を返します。目的のヘッダが欠けていたり、 boundary パラメータがない場合には failobj が返されます。返される文字列はつねに email.utils.unquote() によって unquote されます。

set_boundary(boundary)

メッセージ中の Content-Type ヘッダにある、 boundary パラメータに値を設定します。 set_boundary() は必要に応じて boundary を quote します。そのメッセージが Content-Type ヘッダを含んでいない場合、 HeaderParseError が発生します。

注意: このメソッドを使うのは、古い Content-Type ヘッダを削除して新しい boundary をもったヘッダを add_header() で足すのとは少し違います。 set_boundary() は一連のヘッダ中での Content-Type ヘッダの位置を保つからです。しかし、これは元の Content-Type ヘッダ中に存在していた連続する行の順番までは 保ちません 。

get_content_charset(failobj=None)

そのメッセージ中の Content-Type ヘッダにある、 charset パラメータの値を返します。値はすべて小文字に変換されます。メッセージ中に Content-Type がなかったり、このヘッダ中に charaset パラメータがない場合には failobj が返されます。

注意: これは get_charset() メソッドとは異なります。こちらのほうは文字列のかわりに、そのメッセージボディのデフォルトエンコーディングの Charset インスタンスを返します。

get_charsets(failobj=None)

メッセージ中に含まれる文字セットの名前をすべてリストにして返します。そのメッセージが multipart である場合、返されるリストの各要素がそれぞれの subpart のペイロードに対応します。それ以外の場合、これは長さ 1 のリストを返します。

リスト中の各要素は文字列であり、これは対応する subpart 中のそれぞれの Content-Type ヘッダにある charset の値です。しかし、その subpart が Content-Type をもってないか、 charset がないか、あるいは MIME maintype が text でないいずれかの場合には、リストの要素として failobj が返されます。

get_content_disposition()

Return the lowercased value (without parameters) of the message's Content-Disposition header if it has one, or None. The possible values for this method are inline, attachment or None if the message follows RFC 2183 [https://datatracker.ietf.org/doc/html/rfc2183.html].

Added in version 3.5.

walk()

walk() メソッドは多目的のジェネレータで、これはあるメッセージオブジェクトツリー中のすべての part および subpart をわたり歩くのに使えます。順序は深さ優先です。おそらく典型的な用法は、 walk() を for ループ中でのイテレータとして使うことでしょう。ループを一回まわるごとに、次の subpart が返されるのです。

以下の例は、 multipart メッセージのすべての part において、その MIME タイプを表示していくものです。 :

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

walk iterates over the subparts of any part where is_multipart() returns True, even though msg.get_content_maintype() == 'multipart' may return False. We can see this in our example by making use of the _structure debug helper function:

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

Here the message parts are not multiparts, but they do contain subparts. is_multipart() returns True and walk descends into the subparts.

Message オブジェクトはオプションとして 2つのインスタンス属性をとることができます。これはある MIME メッセージからプレーンテキストを生成するのに使うことができます。

preamble

MIME ドキュメントの形式では、ヘッダ直後にくる空行と最初の multipart 境界をあらわす文字列のあいだにいくらかのテキスト (訳注: preamble, 序文) を埋めこむことを許しています。このテキストは標準的な MIME の範疇からはみ出しているので、MIME 形式を認識するメールソフトからこれらは通常まったく見えません。しかしメッセージのテキストを生で見る場合、あるいはメッセージを MIME 対応していないメールソフトで見る場合、このテキストは目に見えることになります。

preamble 属性は MIME ドキュメントに加えるこの最初の MIME 範囲外テキストを含んでいます。 Parser があるテキストをヘッダ以降に発見したが、それはまだ最初の MIME 境界文字列が現れる前だった場合、パーザはそのテキストをメッセージの preamble 属性に格納します。 Generator がある MIME メッセージからプレーンテキスト形式を生成するときメッセージが preamble 属性を持つことが発見されれば、これはそのテキストをヘッダと最初の MIME 境界の間に挿入します。詳細は email.parser および email.generator を参照してください。

注意: そのメッセージに preamble がない場合、preamble 属性には None が格納されます。

epilogue

epilogue 属性はメッセージの最後の MIME 境界文字列からメッセージ末尾までのテキストを含むもので、それ以外は preamble 属性と同じです。

Generator でファイル終端に改行を出力するため、 epilogue に空文字列を設定する必要はなくなりました。

defects

defects 属性はメッセージを解析する途中で検出されたすべての問題点 (defect、障害) のリストを保持しています。解析中に発見されうる障害についてのより詳細な説明は email.errors を参照してください。

email.mime: Creating email and MIME objects from scratch

ソースコード: Lib/email/mime/ [https://github.com/python/cpython/tree/3.12/Lib/email/mime/]

This module is part of the legacy (Compat32) email API. Its functionality is partially replaced by the contentmanager in the new API, but in certain applications these classes may still be useful, even in non-legacy code.

ふつう、メッセージオブジェクト構造はファイルまたは何がしかのテキストをパーザに通すことで得られます。パーザは与えられたテキストを解析し、基底となる root のメッセージオブジェクトを返します。しかし、完全なメッセージオブジェクト構造を何もないところから作成することもまた可能です。個別の Message を手で作成することさえできます。実際には、すでに存在するメッセージオブジェクト構造をとってきて、そこに新たな Message オブジェクトを追加したり、あるものを別のところへ移動させたりできます。これは MIME メッセージを切ったりおろしたりするために非常に便利なインターフェイスを提供します。

新しいメッセージオブジェクト構造は Message インスタンスを作成することにより作れます。ここに添付ファイルやその他適切なものをすべて手で加えてやればよいのです。MIME メッセージの場合、 email パッケージはこれらを簡単におこなえるようにするためにいくつかの便利なサブクラスを提供しています。

以下がそのサブクラスです:

class email.mime.base.MIMEBase(_maintype, _subtype, *, policy=compat32, **_params)

モジュール: email.mime.base

これはすべての Message の MIME 用サブクラスの基底となるクラスです。とくに MIMEBase のインスタンスを直接作成することは (可能ではありますが) ふつうはしないでしょう。 MIMEBase は単により特化された MIME 用サブクラスのための便宜的な基底クラスとして提供されています。

_maintype は Content-Type の主形式 (maintype) であり (text や image など)、 _subtype は Content-Type の副形式 (subtype) です (plain や gif など)。 _params は各パラメータのキーと値を格納した辞書であり、これは直接 Message.add_header に渡されます。

If policy is specified, (defaults to the compat32 policy) it will be passed to Message.

MIMEBase クラスはつねに (_maintype 、 _subtype 、および _params にもとづいた) Content-Type ヘッダと、 MIME-Version ヘッダ (必ず 1.0 に設定される) を追加します。

バージョン 3.6 で変更: キーワード専用引数 policy が追加されました。

class email.mime.nonmultipart.MIMENonMultipart

モジュール: email.mime.nonmultipart

MIMEBase のサブクラスで、これは multipart 形式でない MIME メッセージのための中間的な基底クラスです。このクラスのおもな目的は、通常 multipart 形式のメッセージに対してのみ意味をなす attach() メソッドの使用をふせぐことです。もし attach() メソッドが呼ばれた場合、これは MultipartConversionError 例外を発生します。

class email.mime.multipart.MIMEMultipart(_subtype='mixed', boundary=None, _subparts=None, *, policy=compat32, **_params)

モジュール: email.mime.multipart

MIMEBase のサブクラスで、これは multipart 形式の MIME メッセージのための中間的な基底クラスです。オプション引数 _subtype はデフォルトでは mixed になっていますが、そのメッセージの副形式 (subtype) を指定するのに使うことができます。メッセージオブジェクトには multipart/_subtype という値をもつ Content-Type ヘッダとともに、 MIME-Version ヘッダが追加されるでしょう。

オプション引数 boundary は multipart の境界文字列です。これが None の場合 (デフォルト)、境界は必要に応じて計算されます（例えばメッセージがシリアライズされるときなど）。

_subparts はそのペイロードの subpart の初期値からなるシーケンスです。このシーケンスはリストに変換できるようになっている必要があります。新しい subpart はつねに Message.attach メソッドを使ってそのメッセージに追加できるようになっています。

Optional policy argument defaults to compat32.

Content-Type ヘッダに対する追加のパラメータはキーワード引数 _params を介して取得あるいは設定されます。これはキーワード辞書になっています。

バージョン 3.6 で変更: キーワード専用引数 policy が追加されました。

class email.mime.application.MIMEApplication(_data, _subtype='octet-stream', _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

モジュール: email.mime.application

A subclass of MIMENonMultipart, the MIMEApplication class is used to represent MIME message objects of major type application. _data contains the bytes for the raw application data. Optional _subtype specifies the MIME subtype and defaults to octet-stream.

オプション引数の _encoder は呼び出し可能なオブジェクト (関数など) で、データの転送に使う実際のエンコード処理を行います。この呼び出し可能なオブジェクトは引数を 1 つ取り、それは MIMEApplication のインスタンスです。ペイロードをエンコードされた形式に変更するために get_payload() と set_payload() を使い、必要に応じて Content-Transfer-Encoding やその他のヘッダをメッセージオブジェクトに追加するべきです。デフォルトのエンコードは base64 です。組み込みのエンコーダの一覧は email.encoders モジュールを見てください。

Optional policy argument defaults to compat32.

_params は基底クラスのコンストラクタにそのまま渡されます。

バージョン 3.6 で変更: キーワード専用引数 policy が追加されました。

class email.mime.audio.MIMEAudio(_audiodata, _subtype=None, _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

モジュール: email.mime.audio

A subclass of MIMENonMultipart, the MIMEAudio class is used to create MIME message objects of major type 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 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 TypeError is raised.

オプション引数の _encoder は呼び出し可能なオブジェクト (関数など) で、オーディオデータの転送に使う実際のエンコード処理を行います。この呼び出し可能なオブジェクトは引数を 1 つ取り、それは MIMEAudio のインスタンスです。ペイロードをエンコードされた形式に変更するために get_payload() と set_payload() を使い、必要に応じて Content-Transfer-Encoding やその他のヘッダをメッセージオブジェクトに追加するべきです。デフォルトのエンコードは base64 です。組み込みのエンコーダの一覧は email.encoders モジュールを見てください。

Optional policy argument defaults to compat32.

_params は基底クラスのコンストラクタにそのまま渡されます。

バージョン 3.6 で変更: キーワード専用引数 policy が追加されました。

class email.mime.image.MIMEImage(_imagedata, _subtype=None, _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

モジュール: email.mime.image

A subclass of MIMENonMultipart, the MIMEImage class is used to create MIME message objects of major type 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 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 TypeError is raised.

オプション引数の _encoder は呼び出し可能なオブジェクト (関数など) で、画像データの転送に使う実際のエンコード処理を行います。この呼び出し可能なオブジェクトは引数を 1 つ取り、それは MIMEImage のインスタンスです。ペイロードをエンコードされた形式に変更するために get_payload() と set_payload() を使い、必要に応じて Content-Transfer-Encoding やその他のヘッダをメッセージオブジェクトに追加するべきです。デフォルトのエンコードは base64 です。組み込みのエンコーダの一覧は email.encoders モジュールを見てください。

Optional policy argument defaults to compat32.

_params は MIMEBase コンストラクタに直接渡されます。

バージョン 3.6 で変更: キーワード専用引数 policy が追加されました。

class email.mime.message.MIMEMessage(_msg, _subtype='rfc822', *, policy=compat32)

モジュール: email.mime.message

MIMEMessage クラスは MIMENonMultipart のサブクラスで、主形式 (maintype) が message の MIME オブジェクトを作成するのに使われます。ペイロードとして使われるメッセージは _msg になります。これは Message クラス (あるいはそのサブクラス) のインスタンスでなければいけません。そうでない場合、この関数は TypeError を発生します。

オプション引数 _subtype はそのメッセージの副形式 (subtype) を設定します。デフォルトではこれは rfc822 になっています。

Optional policy argument defaults to compat32.

バージョン 3.6 で変更: キーワード専用引数 policy が追加されました。

class email.mime.text.MIMEText(_text, _subtype='plain', _charset=None, *, policy=compat32)

モジュール: email.mime.text

MIMEText クラスは MIMENonMultipart のサブクラスで、主形式 (maintype) が text の MIME オブジェクトを作成するのに使われます。ペイロードの文字列は _text になります。 _subtype には副形式 (subtype) を指定し、デフォルトは plain です。 _charset はテキストの文字セットで、 MIMENonMultipart コンストラクタに引数として渡されます。この値は、文字列が ascii コードポイントのみを含む場合 us-ascii 、それ以外は utf-8 がデフォルトになっています。 _charset パラメータは、文字列と Charset インスタンスの両方を受け付けます。

_charset 引数に明示的に None をセットしない限りは、作成される MIMEText オブジェクトは charset の付いた Content-Type ヘッダと Content-Transfer-Endcoding ヘッダの両方を持ちます。これは後続の set_payload 呼び出しが、 set_payload コマンドに charset が渡したとしてもエンコードされたペイロードにはならないことを意味します。 Content-Transfer-Encoding ヘッダを削除することでこの振る舞いを「リセット」出来ます。これにより set_payload 呼び出しが新たなペイロードを自動的にエンコード (そして新たな Content-Transfer-Encoding ヘッダを追加) します。

Optional policy argument defaults to compat32.

バージョン 3.5 で変更: _charset は Charset インスタンスも受け取ります。

バージョン 3.6 で変更: キーワード専用引数 policy が追加されました。

email.header: Internationalized headers

ソースコード: Lib/email/header.py [https://github.com/python/cpython/tree/3.12/Lib/email/header.py]

このモジュールはレガシー(Compat32)な電子メールAPIの一部です。現在のAPIではヘッダのエンコードとデコードは EmailMessage クラスの辞書的なAPIによって透過的に処理されます。レガシーコードでの使用に加えて、このモジュールは、ヘッダーをエンコードする際に使用される文字セットを完全に制御する必要があるアプリケーションで役立ちます

この節の以降のテキストはモジュールの元々のドキュメントです。

RFC 2822 [https://datatracker.ietf.org/doc/html/rfc2822.html] は電子メールメッセージの形式を規定する基本規格です。これはほとんどの電子メールが ASCII 文字のみで構成されていたころ普及した RFC 822 [https://datatracker.ietf.org/doc/html/rfc822.html] 標準から発展したものです。 RFC 2822 [https://datatracker.ietf.org/doc/html/rfc2822.html] は電子メールがすべて 7-bit ASCII 文字のみから構成されていると仮定して作られた仕様です。

もちろん、電子メールが世界的に普及するにつれ、この仕様は国際化されてきました。今では電子メールに言語依存の文字集合を使うことができます。基本規格では、まだ電子メールメッセージを 7-bit ASCII 文字のみを使って転送するよう要求していますので、多くの RFC でどうやって非ASCII の電子メールを RFC 2822 [https://datatracker.ietf.org/doc/html/rfc2822.html] 準拠な形式にエンコードするかが記述されています。これらの RFC は以下のものを含みます: RFC 2045 [https://datatracker.ietf.org/doc/html/rfc2045.html] 、 RFC 2046 [https://datatracker.ietf.org/doc/html/rfc2046.html] 、 RFC 2047 [https://datatracker.ietf.org/doc/html/rfc2047.html] 、および RFC 2231 [https://datatracker.ietf.org/doc/html/rfc2231.html] 。 email パッケージは、 email.header および email.charset モジュールでこれらの規格をサポートしています。

ご自分の電子メールヘッダ、たとえば Subject や To などのフィールドに非ASCII文字を入れたい場合、 Header クラスを使う必要があります。 Message オブジェクトの該当フィールドに文字列ではなく、 Header インスタンスを使うのです。 Header クラスは email.header モジュールからインポートしてください。たとえば:

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

Subject フィールドに非ASCII文字を含めていることに注目してください。ここでは、含めたいバイト列がエンコードされている文字集合を指定して Header インスタンスを作成することによって実現しています。のちにこの Message インスタンスからフラットなテキストを生成する際に、この Subject フィールドは RFC 2047 [https://datatracker.ietf.org/doc/html/rfc2047.html] 準拠の適切な形式にエンコードされます。MIME 機能のあるメーラなら、このヘッダに埋めこまれた ISO-8859-1 文字を正しく表示するでしょう。

以下は Header クラスの説明です:

class email.header.Header(s=None, charset=None, maxlinelen=None, header_name=None, continuation_ws=' ', errors='strict')

別の文字集合の文字列を含む MIME 準拠なヘッダを作成します。

オプション引数 s はヘッダの値の初期値です。これが None の場合 (デフォルト)、ヘッダの初期値は設定されません。この値はあとから append() メソッドを呼びだすことによって追加することができます。 s は bytes または str のインスタンスにできます。このセマンティクスについては append() の項を参照してください。

オプション引数 charset には 2 つの目的があります。ひとつは append() メソッドにおける charset 引数と同じものです。もうひとつは、これ以降 charset 引数を省略した append() メソッド呼び出しすべてにおける、デフォルト文字集合を決定するものです。コンストラクタに charset が与えられない場合 (デフォルト)、初期値の s および以後の append() 呼び出しにおける文字集合として us-ascii が使われます。

行の最大長は maxlinelen によって明示的に指定できます。最初の行を (Subject などの s に含まれないフィールドヘッダの責任をとるため) 短く切りとる場合、 header_name にそのフィールド名を指定してください。 maxlinelen のデフォルト値は 76 であり、 header_name のデフォルト値は None です。これはその最初の行を長い、切りとられたヘッダとして扱わないことを意味します。

オプション引数 continuation_ws は RFC 2822 [https://datatracker.ietf.org/doc/html/rfc2822.html] 準拠の折り返し用余白文字で、ふつうこれは空白か、ハードタブ文字 (hard tab) である必要があります。ここで指定された文字は複数にわたる行の行頭に挿入されます。 continuation_ws のデフォルト値は 1 つのスペース文字です。

オプション引数 errors は、 append() メソッドにそのまま渡されます。

append(s, charset=None, errors='strict')

この MIME ヘッダに文字列 s を追加します。

オプション引数 charset がもし与えられた場合、これは Charset インスタンス (email.charset を参照) か、あるいは文字集合の名前でなければなりません。この場合は Charset インスタンスに変換されます。この値が None の場合 (デフォルト)、コンストラクタで与えられた charset が使われます。

s は bytes または str のインスタンスです。 bytes のインスタンスの場合、 charset はその文字列のエンコーディングであり、この文字セットでデコードできないときは UnicodeError が発生します。

s が str のインスタンスの場合、 charset はその文字列の文字セットを決定するためのヒントとして使われます。

いずれの場合でも、 RFC 2822 [https://datatracker.ietf.org/doc/html/rfc2822.html] 準拠のヘッダを RFC 2047 [https://datatracker.ietf.org/doc/html/rfc2047.html] の規則を用いて生成する際、文字列は指定された文字セットの出力コーデックを用いてエンコードされます。出力コーデックを用いて文字列がエンコードできないときは UnicodeError が発生します。

オプションの errors は、 s がバイト文字列だった場合のデコード呼び出しに errors 引数として渡されます。

encode(splitchars=';, \t', maxlinelen=None, linesep='\n')

メッセージヘッダを RFC に沿ったやり方でエンコードします。おそらく長い行は折り返され、非 ASCII 部分は base64 または quoted-printable エンコーディングで包含されるでしょう。

オプション引数 splitchars は、通常のヘッダーの折り返し処理の間に分割アルゴリズムによって特別な重みが与えられるべき文字を含む文字列です。これは、 RFC 2822 [https://datatracker.ietf.org/doc/html/rfc2822.html] の 'higher level syntactic breaks' の非常に荒いサポートです: splitchar の後の分割点は、行分割において優先されます。 分割文字は文字列中での出現順に優先されます。スペースとタブは、分割しようとする行に他の分割文字が出現しない時に、分割点として他の文字と比べてどのような優先順位が与えられるべきかを示すために、文字列に含めることができます。 Splitchars は RFC 2047 [https://datatracker.ietf.org/doc/html/rfc2047.html] エンコードされた行には影響しません。

与えられた場合、maxlinelen はインスタンスの最大行長の値を上書きします。

linesep は、折り返しヘッダの行を区切る文字を指定します。デフォルトではPythonアプリケーションコードに最も有用な値(\n)になりますが、RFC準拠の行区切り文字でヘッダを生成するために``rn``を指定することができます。

バージョン 3.2 で変更: linesep 引数が追加されました。

Header クラスは、標準の演算子や組み込み関数をサポートするためのメソッドもいくつか提供しています。

__str__()

Header の概要を文字列として返します。無制限の行長を使用します。すべての箇所は、指定されたエンコーディングを使用してUnicodeに変換され、適切に結合されます。文字セット 'unknown-8bit' を持つ箇所は、 'replace' エラーハンドラを使ってASCIIとしてデコードされます。

バージョン 3.2 で変更: 'unknown-8bit' 文字集合の処理が追加されました。

__eq__(other)

このメソッドは、ふたつの Header インスタンスどうしが等しいかどうか判定するのに使えます。

__ne__(other)

このメソッドは、ふたつの Header インスタンスどうしが異なっているかどうかを判定するのに使えます。

さらに、 email.header モジュールは以下のような簡易関数も提供しています。

email.header.decode_header(header)

文字集合を変換せずにメッセージのヘッダをデコードします。ヘッダの値は header にあります。

この関数はヘッダのそれぞれのデコードされた部分ごとに、(decoded_string, charset) という形式の 2要素タプルからなるリストを返します。charset はヘッダのエンコードされていない部分に対しては None を、それ以外の場合はエンコードされた文字列が指定している文字集合の名前を小文字からなる文字列で返します。

以下はこの使用例です:

>>> from email.header import decode_header
>>> decode_header('=?iso-8859-1?q?p=F6stal?=')
[(b'p\xf6stal', 'iso-8859-1')]

email.header.make_header(decoded_seq, maxlinelen=None, header_name=None, continuation_ws=' ')

decode_header() によって返される 2要素タプルのリストから Header インスタンスを作成します。

decode_header() はヘッダの値をとってきて、 (decoded_string, charset) という形式の 2要素タプルからなるリストを返します。ここで decoded_string はデコードされた文字列、 charset はその文字集合です。

この関数はこれらのリストの項目から、 Header インスタンスを返します。オプション引数 maxlinelen 、 header_name および continuation_ws は Header コンストラクタに与えるものと同じです。

email.charset: Representing character sets

ソースコード: Lib/email/charset.py [https://github.com/python/cpython/tree/3.12/Lib/email/charset.py]

このモジュールは、レガシーな (Compat32) email API の一部分です。新しい API では別名の表のみ使われています。

この節の以降のテキストはモジュールの元々のドキュメントです。

このモジュールは文字集合の表現および電子メールメッセージの文字集合の変換を行う Charset クラスに加え、文字集合のレジストリとそれを操作する簡易メソッドを提供しています。 Charset インスタンスは email パッケージ中にある他のいくつかのモジュールで使用されます。

このクラスは email.charset モジュールからインポートしてください。

class email.charset.Charset(input_charset=DEFAULT_CHARSET)

文字集合を電子メールのプロパティに写像します。

このクラスは、ある特定の文字集合に対し電子メールに課される条件についての情報を提供します。また、適用可能なコーデックスが利用出来れば、文字集合間の変換を行う簡易ルーチンを提供します。文字集合について、この関数は電子メールメッセージ内での RFC に準拠した文字集合の使い方に関する情報を提供するのに最善を尽くします。

文字集合によっては、電子メールのヘッダや本体で使う場合に quoted-printable や base64 形式でエンコードされなければなりません。また、文字集合によっては完全に変換する必要があり、電子メールの中では使用できません。

以下ではオプション引数 input_charset について説明します。この値は常に小文字に強制的に変換されます。そして文字集合の別名が正規化されたあと、この値は文字集合のレジストリ内を検索し、ヘッダのエンコーディングとメッセージ本体のエンコーディング、および出力時の変換に使われるコーデックを見付けるのに使われます。たとえば input_charset が iso-8859-1 の場合、ヘッダおよびメッセージ本体は quoted-printable でエンコードされ、出力時の変換用コーデックは必要ありません。もし input_charset が euc-jp ならば、ヘッダは base64 でエンコードされ、メッセージ本体はエンコードされませんが、出力されるテキストは euc-jp 文字集合から iso-2022-jp 文字集合に変換されます。

Charset インスタンスは以下のようなデータ属性をもっています:

input_charset

最初に指定される文字集合です。一般的な別名は、正式な 電子メール用の名前に変換されます (たとえば、latin_1 は iso-8859-1 に変換されます)。デフォルトは 7-bit の us-ascii です。

header_encoding

この文字集合が電子メールヘッダに使われる前にエンコードされなければならない場合、この属性は charset.QP (quoted-printable エンコーディング)、charset.BASE64 (base64 エンコーディング)、あるいは最短の QP または BASE64 エンコーディングである charset.SHORTEST に設定されます。そうでない場合、この値は None になります。

body_encoding

header_encoding と同じですが、この値はメッセージ本体のためのエンコーディングを記述します。これはヘッダ用のエンコーディングとは違うかもしれません。body_encoding では、charset.SHORTEST を使うことはできません。

output_charset

文字集合によっては、電子メールのヘッダあるいはメッセージ本体に使う前に変換しなければなりません。もし input_charset がそれらの文字集合のどれかをさしていたら、この output_charset 属性はそれが出力時に変換される文字集合の名前を表しています。それ以外の場合、この値は None になります。

input_codec

input_charset を Unicode に変換するための Python 用コーデック名です。変換用のコーデックが必要ないときは、この値は None になります。

output_codec

Unicode を output_charset に変換するための Python 用コーデック名です。変換用のコーデックが必要ないときは、この値は None になります。この属性は input_codec と同じ値を持つことになるでしょう。

Charset インスタンスは、以下のメソッドも持っています:

get_body_encoding()

メッセージ本体のエンコードに使われる content-transfer-encoding の値を返します。

この値は使用しているエンコーディングの文字列 quoted-printable または base64 か、あるいは関数のいずれかです。後者の場合、これはエンコードされる Message オブジェクトを単一の引数として取るような関数である必要があります。この関数は変換後 Content-Transfer-Encoding ヘッダ自体を、なんであれ適切な値に設定する必要があります。

このメソッドは body_encoding が QP の場合 quoted-printable を返し、body_encoding が BASE64 の場合 base64 を返します。それ以外の場合は文字列 7bit を返します。

get_output_charset()

出力用の文字集合を返します。

これは output_charset 属性が None でなければその値になります。それ以外の場合、この値は input_charset と同じです。

header_encode(string)

文字列 string をヘッダ用にエンコードします。

エンコーディングの形式 (base64 または quoted-printable) は、header_encoding 属性に基づきます。

header_encode_lines(string, maxlengths)

string を最初にバイト列に変換し、ヘッダ用にエンコードします。

これは header_encode() と似ていますが、与えられた引数 maxlengths に従って、行の最大長に合うように文字列が調整されるところが異なります。 maxlengths はイテレータでなければなりません: このイテレータが返す要素は次の行の最大長を表します。

body_encode(string)

文字列 string をメッセージ本体用にエンコードします。

エンコーディングの形式 (base64 または quoted-printable) は、body_encoding 属性に基づきます。

Charset クラスには、標準的な演算と組み込み関数をサポートするいくつかのメソッドがあります。

__str__()

input_charset を小文字に変換された文字列型として返します。 __repr__() は、 __str__() の別名となっています。

__eq__(other)

このメソッドは、2つの Charset インスタンスが同じかどうかをチェックするのに使います。

__ne__(other)

このメソッドは、2つの Charset インスタンスが異なるかどうかをチェックするのに使います。

また、 email.charset モジュールには、グローバルな文字集合、文字集合の別名およびコーデック用のレジストリに新しいエントリを追加する以下の関数も含まれています:

email.charset.add_charset(charset, header_enc=None, body_enc=None, output_charset=None)

文字の属性をグローバルなレジストリに追加します。

charset は入力用の文字集合で、その文字集合の正式名称を指定する必要があります。

オプション引数 header_enc および body_enc は quoted-printable エンコーディングを表す charset.QP か、base64 エンコーディングを表す charset.BASE64、最短の quoted-printable または base64 エンコーディングを表す charset.SHORTEST、あるいはエンコーディングなしの None のいずれかになります。SHORTEST が使えるのは header_enc だけです。デフォルトの値はエンコーディングなしの None になっています。

オプション引数 output_charset には出力用の文字集合が入ります。 Charset.convert() が呼ばれたときの変換はまず入力用の文字集合を Unicode に変換し、それから出力用の文字集合に変換されます。デフォルトでは、出力は入力と同じ文字集合になっています。

input_charset および output_charset はこのモジュール中の文字集合-コーデック対応表にある Unicode コーデックエントリである必要があります。モジュールがまだ対応していないコーデックを追加するには、 add_codec() を使ってください。より詳しい情報については codecs モジュールの文書を参照してください。

グローバルな文字集合用のレジストリは、モジュールのグローバル辞書 CHARSETS 内に保持されています。

email.charset.add_alias(alias, canonical)

文字集合の別名を追加します。alias はその別名で、たとえば latin-1 のように指定します。canonical はその文字集合の正式名称で、たとえば iso-8859-1 のように指定します。

文字集合のグローバルな別名用レジストリは、モジュールのグローバル辞書 ALIASES 内に保持されています。

email.charset.add_codec(charset, codecname)

与えられた文字集合の文字と Unicode との変換を行うコーデックを追加します。

charset は文字集合の正式な名前です。 codecname は、 str の encode() メソッドの第 2 引数で使える Python コーデックの名前です。

email.encoders: Encoders

ソースコード: Lib/email/encoders.py [https://github.com/python/cpython/tree/3.12/Lib/email/encoders.py]

このモジュールは、レガシーな (Compat32) email APIの一部です。新しいAPIでは、この機能は set_content() メソッドの*cte*パラメータによって提供されます。

このモジュールはPython3で非推奨になりました。 MIMEText クラスはクラスのインスタンス化中に渡された _subtype と _charset の値を使ってcontent typeとCTEヘッダを設定するので、ここで提供されている関数は明示的に呼び出すべきではありません。

この節の以降のテキストはモジュールの元々のドキュメントです。

何もないところから Message を作成するときしばしば必要になるのが、ペイロードをメールサーバに通すためにエンコードすることです。これはとくにバイナリデータを含んだ image/* や text/* タイプのメッセージで必要です。

The email package provides some convenient encoders in its encoders module. These encoders are actually used by the MIMEAudio and MIMEImage class constructors to provide default encodings. All encoder functions take exactly one argument, the message object to encode. They usually extract the payload, encode it, and reset the payload to this newly encoded value. They should also set the Content-Transfer-Encoding header as appropriate.

マルチパートメッセージにこれら関数を使うことは全く無意味です。それらは各々のサブパートごとに適用されるべきものです。メッセージがマルチパートのものを渡すと TypeError が発生します。

提供されているエンコーディング関数は以下のとおりです:

email.encoders.encode_quopri(msg)

ペイロードを quoted-printable 形式にエンコードし、 Content-Transfer-Encoding ヘッダを quoted-printable [1] に設定します。これはそのペイロードのほとんどが通常の印刷可能な文字からなっているが、印刷不可能な文字がすこしだけあるときのエンコード方法として適しています。

email.encoders.encode_base64(msg)

ペイロードを base64 形式でエンコードし、 Content-Transfer-Encoding ヘッダを base64 に変更します。これはペイロード中のデータのほとんどが印刷不可能な文字である場合に適しています。 quoted-printable 形式よりも結果としてはコンパクトなサイズになるからです。 base64 形式の欠点は、これが人間にはまったく読めないテキストになってしまうことです。

email.encoders.encode_7or8bit(msg)

これは実際にはペイロードを変更はしませんが、ペイロードの形式に応じて Content-Transfer-Encoding ヘッダを 7bit あるいは 8bit に適した形に設定します。

email.encoders.encode_noop(msg)

これは何もしないエンコーダです。 Content-Transfer-Encoding ヘッダを設定さえしません。

脚注

[1]

注意: encode_quopri() を使ってエンコードすると、データ中のタブ文字や空白文字もエンコードされます。

email.utils: Miscellaneous utilities

ソースコード: Lib/email/utils.py [https://github.com/python/cpython/tree/3.12/Lib/email/utils.py]

email.utils モジュールではいくつかの便利なユーティリティを提供しています:

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 datetime instance, and it is converted to the local time zone according to the system time zone database. If dt is naive (that is, dt.tzinfo is None), it is assumed to be in local time. The isdst parameter is ignored.

Added in version 3.3.

バージョン 3.12 で非推奨、バージョン 3.14 で削除予定: The isdst parameter.

email.utils.make_msgid(idstring=None, domain=None)

Returns a string suitable for an RFC 2822 [https://datatracker.ietf.org/doc/html/rfc2822.html]-compliant 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 キーワードが追加されました。

The remaining functions are part of the legacy (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.

email.utils.quote(str)

文字列 str 内のバックスラッシュをバックスラッシュ2つに置換した新しい文字列を返します。また、ダブルクォートはバックスラッシュ + ダブルクォートに置換されます。

email.utils.unquote(str)

文字列 str の クォートを外した 新しい文字列を返します。str の先頭と末尾がダブルクォートだった場合、それらは取り除かれます。同様に str の先頭と末尾が角ブラケット (<、>) だった場合もそれらは取り除かれます。

email.utils.parseaddr(address)

To や Cc のようなフィールドを持つアドレスをパースして、構成要素の 実名 と 電子メールアドレス を取り出します。 パースに成功した場合、これらの情報持つタプルを返します。失敗した場合は 2 要素のタプル ('', '') を返します。

email.utils.formataddr(pair, charset='utf-8')

parseaddr() の逆で、2 要素のタプル (realname, email_address) を取って To や Cc ヘッダに適した文字列を返します。タプル pair の第1要素が偽である場合、第2要素の値をそのまま返します。

任意の charset は、 realname が非 ASCII 文字を含んでいる場合にその RFC 2047 [https://datatracker.ietf.org/doc/html/rfc2047.html] エンコーディングに使われる文字集合です。str か Charset のインスタンスで、デフォルトは utf-8 です。

バージョン 3.3 で変更: charset オプションが追加されました。

email.utils.getaddresses(fieldvalues)

This method returns a list of 2-tuples of the form returned by parseaddr(). fieldvalues is a sequence of header field values as might be returned by Message.get_all. Here's a simple example that gets all the recipients of a message:

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)

email.utils.parsedate(date)

RFC 2822 [https://datatracker.ietf.org/doc/html/rfc2822.html] の規則に基づいて日付の解析を試みます。しかしながらメイラーによっては指定された形式に従っていないものがあるので、その場合 parsedate() は正しく推測しようとします。 date は "Mon, 20 Nov 1995 19:12:08 -0500" のような RFC 2822 [https://datatracker.ietf.org/doc/html/rfc2822.html] 形式の日付を含む文字列です。日付の解析に成功した場合、 parsedate() は関数 time.mktime() に直接渡せる形式の 9 要素からなるタプルを返します。失敗した場合は None を返します。返されるタプルの 6、7、8番目の添字は使用不可なので注意してください。

email.utils.parsedate_tz(date)

Performs the same function as parsedate(), but returns either None or a 10-tuple; the first 9 elements make up a tuple that can be passed directly to time.mktime(), and the tenth is the offset of the date's timezone from UTC (which is the official term for Greenwich Mean Time) [1]. If the input string has no timezone, the last element of the tuple returned is 0, which represents UTC. Note that indexes 6, 7, and 8 of the result tuple are not usable.

email.utils.parsedate_to_datetime(date)

The inverse of format_datetime(). Performs the same function as parsedate(), but on success returns a datetime; otherwise 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 -0000, the datetime will be a naive 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 datetime will be an aware datetime with the corresponding a timezone tzinfo.

Added in version 3.3.

email.utils.mktime_tz(tuple)

parsedate_tz() が返す 10 要素のタプルを UTC のタイムスタンプ (エポックからの秒数) に変換します。与えられた時間帯が None である場合、時間帯として現地時間 (localtime) が仮定されます。

email.utils.formatdate(timeval=None, localtime=False, usegmt=False)

日付を RFC 2822 [https://datatracker.ietf.org/doc/html/rfc2822.html] 形式の文字列で返します。例:

Fri, 09 Nov 2001 01:08:47 -0000

与えられた場合、オプションの timeval は time.gmtime() や time.localtime() に渡すことの出来る浮動小数の時刻です。それ以外の場合、現在時刻が使われます。

オプション引数 localtime はフラグです。True の場合、この関数は timeval を解析して UTC の代わりに現地のタイムゾーンに対する日付を返します。おそらく夏時間も考慮するでしょう。デフォルトは False で、UTC が使われます。

オプション引数 usegmt はフラグです。True の場合、この関数はタイムゾーンを数値の -0000 ではなく ascii 文字列 GMT として日付を出力します。これはプロトコルによっては (例えば HTTP) 必要です。これは localtime が False のときのみ適用されます。デフォルトは False です。

email.utils.format_datetime(dt, usegmt=False)

Like formatdate, but the input is a datetime instance. If it is a naive datetime, it is assumed to be "UTC with no information about the source timezone", and the conventional -0000 is used for the timezone. If it is an aware datetime, then the numeric timezone offset is used. If it is an aware timezone with offset zero, then usegmt may be set to True, in which case the string GMT is used instead of the numeric timezone offset. This provides a way to generate standards conformant HTTP date headers.

Added in version 3.3.

email.utils.decode_rfc2231(s)

RFC 2231 [https://datatracker.ietf.org/doc/html/rfc2231.html] に従って文字列 s をデコードします。

email.utils.encode_rfc2231(s, charset=None, language=None)

RFC 2231 [https://datatracker.ietf.org/doc/html/rfc2231.html] に従って s をエンコードします。オプション引数 charset および language が与えられた場合、これらは文字セット名と言語名として使われます。もしこれらのどちらも与えられていない場合、 s はそのまま返されます。 charset は与えられているが language が与えられていない場合、文字列 s は language の空文字列を使ってエンコードされます。

email.utils.collapse_rfc2231_value(value, errors='replace', fallback_charset='us-ascii')

ヘッダのパラメータが RFC 2231 [https://datatracker.ietf.org/doc/html/rfc2231.html] 形式でエンコードされている場合、 Message.get_param は 3 要素からなるタプルを返すことがあります。ここには、そのパラメータの文字セット、言語、および値の順に格納されています。 collapse_rfc2231_value() はこのパラメータをひとつの Unicode 文字列にまとめます。オプション引数 errors は str の encode() メソッドの引数 errors に渡されます。このデフォルト値は 'replace' となっています。オプション引数 fallback_charset は、もし RFC 2231 [https://datatracker.ietf.org/doc/html/rfc2231.html] ヘッダの使用している文字セットが Python の知っているものではなかった場合の非常用文字セットとして使われます。デフォルトでは、この値は 'us-ascii' です。

便宜上、 collapse_rfc2231_value() に渡された引数 value がタプルでない場合には、これは文字列でなければなりません。その場合にはクォートを除いた文字列を返します。

email.utils.decode_params(params)

RFC 2231 [https://datatracker.ietf.org/doc/html/rfc2231.html] に従って引数のリストをデコードします。 params は (content-type, string-value) のような形式の 2 要素タプルです。

脚注

[1]

注意: この時間帯のオフセット値は time.timezone の値と符号が逆です。これは time.timezone が POSIX 標準に準拠しているのに対して、こちらは RFC 2822 [https://datatracker.ietf.org/doc/html/rfc2822.html] に準拠しているからです。

email.iterators: Iterators

ソースコード: Lib/email/iterators.py [https://github.com/python/cpython/tree/3.12/Lib/email/iterators.py]

Message.walk メソッドを使うと、簡単にメッセージオブジェクトツリー内を次から次へとたどる (iteration) ことができます。 email.iterators モジュールはこのための高水準イテレータをいくつか提供します。

email.iterators.body_line_iterator(msg, decode=False)

このイテレータは msg 中のすべてのサブパートに含まれるペイロードをすべて順にたどっていき、ペイロード内の文字列を 1 行ずつ返します。サブパートのヘッダはすべて無視され、Python 文字列でないペイロードからなるサブパートも無視されます。これは readline() を使って、ファイルからメッセージを (ヘッダだけとばして) フラットなテキストとして読むのにいくぶん似ているかもしれません。

オプション引数 decode は、 Message.get_payload にそのまま渡されます。

email.iterators.typed_subpart_iterator(msg, maintype='text', subtype=None)

このイテレータは msg 中のすべてのサブパートをたどり、それらの中で指定されたMIME 形式 maintype と subtype をもつようなパートのみを返します。

subtype は省略可能であることに注意してください。これが省略された場合、サブパートの MIME 形式は maintype のみがチェックされます。じつは maintype も省略可能で、その場合にはデフォルトは text です。

つまり、デフォルトでは typed_subpart_iterator() は MIME 形式 text/* をもつサブパートを順に返していくというわけです。

以下の関数は役に立つデバッグ用ツールとして追加されたもので、パッケージとして公式なサポートのあるインターフェイスでは ありません。

email.iterators._structure(msg, fp=None, level=0, include_default=False)

そのメッセージオブジェクト構造の content-type をインデントつきで表示します。例えば:

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

オプション引数 fp は出力を渡すための file-like オブジェクトです。これは Python の print() 関数が対応できるようになっている必要があります。 level は内部的に使用されます。 include_default が真の場合、デフォルトの型も出力します。

json --- JSON encoder and decoder

ソースコード: Lib/json/__init__.py [https://github.com/python/cpython/tree/3.12/Lib/json/__init__.py]

JSON (JavaScript Object Notation) [https://json.org] は、 RFC 7159 [https://datatracker.ietf.org/doc/html/rfc7159.html] (RFC 4627 [https://datatracker.ietf.org/doc/html/rfc4627.html] を obsolete) と ECMA-404 [https://www.ecma-international.org/publications-and-standards/standards/ecma-404/] によって定義された軽量のデータ交換用のフォーマットです。 JavaScript のオブジェクトリテラル記法に由来しています (JavaScript [https://en.wikipedia.org/wiki/JavaScript] の厳密なサブセットではありませんが [1])。

警告

信頼されていないソースからの JSON データをパースするときは十分注意してください。悪意を持った JSON 文字列はデコーダに著しい量の CPU とメモリリソースを消費させる可能性があります。パースするデータ量を制限することを推奨します。

json の API は標準ライブラリの marshal や pickle のユーザに馴染み深いものです。

基本的な Python オブジェクト階層のエンコーディング:

>>> 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"]'

コンパクトなエンコーディング:

>>> import json
>>> json.dumps([1, 2, 3, {'4': 5, '6': 7}], separators=(',', ':'))
'[1,2,3,{"4":5,"6":7}]'

見やすい表示:

>>> import json
>>> print(json.dumps({'4': 5, '6': 7}, sort_keys=True, indent=4))
{
    "4": 5,
    "6": 7
}

JSON のデコーディング:

>>> 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']

JSON オブジェクトのデコーディング方法を誂える:

>>> 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')

JSONEncoder の拡張:

>>> 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', ']']

シェルから json.tool を使って妥当性チェックをして見やすく表示:

$ echo '{"json":"obj"}' | python -m json.tool
{
    "json": "obj"
}
$ echo '{1.2:3.4}' | python -m json.tool
Expecting property name enclosed in double quotes: line 1 column 2 (char 1)

詳細については コマンドラインインターフェイス を参照してください。

注釈

JSON は YAML [https://yaml.org/] 1.2 のサブセットです。このモジュールのデフォルト設定 (特に、デフォルトの セパレータ 値) で生成される JSON は YAML 1.0 および 1.1 のサブセットでもあります。このモジュールは YAML シリアライザとしても使えます。

注釈

このモジュールのエンコーダとデコーダは、デフォルトで入力順と出力順を保つようになっています。根底のコンテナに順序がない場合のみ、順序が失われます。

基本的な使い方

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)

この 変換表 を使って、 obj を JSON 形式の fp (.write() がサポートされている file-like object) へのストリームとして直列化します。

skipkeys が true (デフォルトは False) ならば、基本型 (str, int, float, bool, None) 以外の辞書のキーは TypeError を送出せずに読み飛ばされます。

この json モジュールは常に、 bytes オブジェクトではなく、 str オブジェクトを生成します。従って、 fp.write() は str の入力をサポートしていなければなりません。

ensure_ascii が (デフォルト値の) true の場合、出力では入力された全ての非 ASCII 文字はエスケープされていることが保証されています。ensure_ascii が false の場合、これらの文字はそのまま出力されます。

check_circular が false (デフォルトは True) ならば、コンテナ型の循環参照チェックが省かれ、循環参照があれば RecursionError (またはもっと悪い結果) に終わります。

allow_nan が偽 (デフォルトは True) の場合、許容範囲外の float 値 (nan, inf, -inf) を JSON 仕様を厳格に守って 直列化すると、ValueError になります。 allow_nan が真の場合は、 JavaScript での等価なもの (NaN, Infinity, -Infinity) が使われます。

indent が非負の整数または文字列であれば、JSON の配列要素とオブジェクトメンバはそのインデントレベルで見やすく表示されます。インデントレベルが 0 か負数または "" であれば 改行だけが挿入されます。None (デフォルト) では最もコンパクトな表現が選択されます。正の数のindentはレベル毎に、指定した数のスペースでインデントします。もし indent が文字列 ("\t" のような) であれば、その文字列が個々のレベルのインデントに使用されます。

バージョン 3.2 で変更: 整数に加えて、文字列が indent に使用できるようになりました。

separators はもし指定するなら (item_separator, key_separator) というタプルでなければなりません。デフォルトは indent が None のとき (', ', ': ') で、そうでなければ (',', ': ') です。最もコンパクトな JSON の表現を得たければ空白を削った (',', ':') を指定すればいいでしょう。

バージョン 3.4 で変更: indent が None でなければ (',', ': ') がデフォルトで使われます。

default を指定する場合は関数を指定して、この関数はそれ以外では直列化できないオブジェクトに対して呼び出されます。その関数は、オブジェクトを JSON でエンコードできるバージョンにして返すか、さもなければ TypeError を送出しなければなりません。指定しない場合は、 TypeError が送出されます。

sort_keys が true (デフォルトでは False です)であれば、辞書の出力がキーでソートされます。

カスタマイズされた JSONEncoder のサブクラス (たとえば追加の型を直列化するように default() メソッドをオーバーライドしたもの) を使うには、 cls キーワード引数に指定します; 指定しなければ JSONEncoder が使われます。

バージョン 3.6 で変更: すべてのオプション引数は、 キーワード専用 になりました。

注釈

pickle や marshal とは異なり JSON はフレーム付きのプロトコルではないので、同じ fp に対し繰り返し dump() を呼び、複数のオブジェクトを直列化しようとすると、不正な JSON ファイルが作られてしまいます。

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)

この 変換表 を使って、obj を JSON 形式の str オブジェクトに直列化します。引数は dump() と同じ意味です。

注釈

JSON のキー値ペアのキーは、常に str 型です。辞書が JSON に変換されるとき、辞書の全てのキーは文字列へ強制的に変換が行われます。この結果として、辞書が JSON に変換され、それから辞書に戻された場合、辞書は元のものと同じではありません。つまり文字列ではないキーを持っている場合、 loads(dumps(x)) != x となるということです。

json.load(fp, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)

この 変換表 を使い、 fp (.read() をサポートし JSON ドキュメントを含んでいる text file もしくは binary file) を Python オブジェクトへ脱直列化します。

object_hook はオプションの関数で、任意のオブジェクトリテラルがデコードされた結果 (dict) に対し呼び出されます。 object_hook の返り値は dict の代わりに使われます。この機能は独自のデコーダ (例えば JSON-RPC [https://www.jsonrpc.org] クラスヒンティング) を実装するのに使えます。

object_pairs_hook はオプションで渡す関数で、ペアの順序付きリストのデコード結果に対して呼ばれます。 object_pairs_hook の返り値は dict の代わりに使われます。この機能は独自のデコーダを実装するのに使えます。 object_hook も定義されている場合は、 object_pairs_hook が優先して使用されます。

バージョン 3.1 で変更: object_pairs_hook のサポートが追加されました。

parse_float は、もし指定されれば、全てのデコードされる JSON の浮動小数点数文字列に対して呼ばれます。デフォルトでは、 float(num_str) と等価です。これは JSON 浮動小数点数に対して他のデータ型やパーサ (たとえば decimal.Decimal) を使うのに使えます。

parse_int は、もし指定されれば、全てのデコードされる JSON の整数文字列に対して呼ばれます。デフォルトでは、 int(num_str) と等価です。これは JSON 整数に対して他のデータ型やパーサ (たとえば float) を使うのに使えます。

バージョン 3.11 で変更: デフォルトの parse_int である int() は、インタープリタの integer string conversion length limitation により整数文字列の最大長を制限するようになり、サービスを妨害する攻撃を拒否します。

parse_constant は、もし指定されれば、次の文字列に対して呼ばれます: '-Infinity', 'Infinity', 'NaN', 'null', 'true', 'false'。これは不正な JSON 数値に遭遇したときに例外を送出するのに使えます。

バージョン 3.1 で変更: 'null', 'true', 'false' に対して parse_constant は呼びされません。

カスタマイズされた JSONDecoder のサブクラスを使うには、 cls キーワード引数に指定します; 指定しなかった場合は JSONDecoder が使われます。追加のキーワード引数はこのクラスのコンストラクタに引き渡されます。

脱直列化しようとしているデータが不正な JSON ドキュメントだった場合、 JSONDecodeError が送出されます。

バージョン 3.6 で変更: すべてのオプション引数は、 キーワード専用 になりました。

バージョン 3.6 で変更: fp には binary file 型も使えるようになりました。入力のエンコーディングは UTF-8, UTF-16, UTF-32 のいずれかでなければなりません。

json.loads(s, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)

この 変換表 を使い、 s (JSON ドキュメントを含んでいる str, bytes, bytearray のいずれかのインスタンス) を Python オブジェクトへ脱直列化します。

その他の引数は load() のものと同じ意味です。

脱直列化しようとしているデータが不正な JSON ドキュメントだった場合、 JSONDecodeError が送出されます。

バージョン 3.6 で変更: s には bytes 型と bytearray 型も使えるようになりました。入力エンコーディングは UTF-8, UTF-16, UTF-32 のいずれかでなければなりません。

バージョン 3.9 で変更: キーワード引数 encoding が削除されました。

エンコーダとデコーダ

class json.JSONDecoder(*, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, strict=True, object_pairs_hook=None)

単純な JSON デコーダ。

デフォルトではデコーディングの際、以下の変換を行います:

JSON

Python

object

dict

array

list

string

str

number (int)

int

number (real)

浮動小数点数

true

True

false

False

null

None

また、このデコーダは NaN, Infinity, -Infinity を対応する float の値として、JSON の仕様からは外れますが、理解します。

object_hook は、もし指定されれば、全てのデコードされた JSON オブジェクトに対して呼ばれその返値は与えられた dict の代わりに使われます。この機能は独自の脱直列化 (たとえば JSON-RPC [https://www.jsonrpc.org] クラスヒンティングをサポートするような) を提供するのに使えます。

object_pairs_hook が指定された場合、ペアの順序付きリストのデコード結果に対して毎回呼ばれます。 object_pairs_hook の返り値は dict の代わりに使われます。この機能は独自のデコーダを実装するのに使えます。 object_hook も定義されている場合は、 object_pairs_hook が優先して使用されます。

バージョン 3.1 で変更: object_pairs_hook のサポートが追加されました。

parse_float は、もし指定されれば、全てのデコードされる JSON の浮動小数点数文字列に対して呼ばれます。デフォルトでは、 float(num_str) と等価です。これは JSON 浮動小数点数に対して他のデータ型やパーサ (たとえば decimal.Decimal) を使うのに使えます。

parse_int は、もし指定されれば、全てのデコードされる JSON の整数文字列に対して呼ばれます。デフォルトでは、 int(num_str) と等価です。これは JSON 整数に対して他のデータ型やパーサ (たとえば float) を使うのに使えます。

parse_constant は、もし指定されれば、次の文字列に対して呼ばれます: '-Infinity', 'Infinity', 'NaN', 'null', 'true', 'false'。これは不正な JSON 数値に遭遇したときに例外を送出するのに使えます。

strict が false (デフォルトは True) の場合、制御文字を文字列に含めることができます。ここで言う制御文字とは、'\t' (タブ)、'\n'、'\r'、'\0' を含む 0-31 の範囲のコードを持つ文字のことです。

脱直列化しようとしているデータが不正な JSON ドキュメントだった場合、 JSONDecodeError が送出されます。

バージョン 3.6 で変更: すべての引数は、 キーワード専用 になりました。

decode(s)

s (str インスタンスで JSON 文書を含むもの) の Python 表現を返します。

不正な JSON ドキュメントが与えられた場合、 JSONDecodeError が送出されます。

raw_decode(s)

s (str インスタンスで JSON 文書で始まるもの) から JSON 文書をデコードし、Python 表現と s の文書の終わるところのインデックスからなる 2 要素のタプルを返します。

このメソッドは後ろに余分なデータを従えた文字列から JSON 文書をデコードするのに使えます。

class json.JSONEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Python データ構造に対する拡張可能な JSON エンコーダ。

デフォルトでは以下のオブジェクトと型をサポートします:

Python

JSON

dict

object

list, tuple

array

str

string

int、float と int や float の派生列挙型

number

True

true

False

false

None

null

バージョン 3.4 で変更: int と float の派生列挙型クラスの対応が追加されました。

このクラスを拡張して他のオブジェクトも認識するようにするには、サブクラスを作って default() メソッドを次のように実装します。もう一つ別のメソッドでオブジェクト o に対する直列化可能なオブジェクトを返すものを呼び出すようにします。変換できない時はスーパークラスの実装を (TypeError を送出させるために) 呼ばなければなりません。

skipkeys が false (デフォルト) ならば、str, int, float, None 以外のキーをエンコードしようとすると TypeError を送出します。 skipkeys が true の場合は、それらのアイテムは単に読み飛ばされます。

ensure_ascii が (デフォルト値の) true の場合、出力では入力された全ての非 ASCII 文字はエスケープされていることが保証されています。ensure_ascii が false の場合、これらの文字はそのまま出力されます。

check_circular が true (デフォルト) ならば、リスト、辞書および自作でエンコードしたオブジェクトは循環参照がないかエンコード中にチェックされ、無限再帰 (これは RecursionError を引き起こします) を防止します。 True でない場合は、そういったチェックは施されません。

allow_nan が true (デフォルト) ならば、 NaN, Infinity, -Infinity はそのままエンコードされます。この振る舞いは JSON 仕様に従っていませんが、大半の JavaScript ベースのエンコーダ、デコーダと矛盾しません。 True でない場合は、そのような浮動小数点数をエンコードすると ValueError が送出されます。

sort_keys が true (デフォルトは False) ならば、辞書の出力がキーでソートされます。これは JSON の直列化がいつでも比較できるようになるので回帰試験の際に便利です。

indent が非負の整数または文字列であれば、JSON の配列要素とオブジェクトメンバはそのインデントレベルで見やすく表示されます。インデントレベルが 0 か負数または "" であれば 改行だけが挿入されます。None (デフォルト) では最もコンパクトな表現が選択されます。正の数のindentはレベル毎に、指定した数のスペースでインデントします。もし indent が文字列 ("\t" のような) であれば、その文字列が個々のレベルのインデントに使用されます。

バージョン 3.2 で変更: 整数に加えて、文字列が indent に使用できるようになりました。

separators はもし指定するなら (item_separator, key_separator) というタプルでなければなりません。デフォルトは indent が None のとき (', ', ': ') で、そうでなければ (',', ': ') です。最もコンパクトな JSON の表現を得たければ空白を削った (',', ':') を指定すればいいでしょう。

バージョン 3.4 で変更: indent が None でなければ (',', ': ') がデフォルトで使われます。

default を指定する場合は関数を指定して、この関数はそれ以外では直列化できないオブジェクトに対して呼び出されます。その関数は、オブジェクトを JSON でエンコードできるバージョンにして返すか、さもなければ TypeError を送出しなければなりません。指定しない場合は、 TypeError が送出されます。

バージョン 3.6 で変更: すべての引数は、 キーワード専用 になりました。

default(o)

このメソッドをサブクラスで実装する際には o に対して直列化可能なオブジェクトを返すか、基底クラスの実装を (TypeError を送出するために) 呼び出すかします。

例えば、任意のイテレータをサポートする場合、 default() をこのように実装できます

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)

encode(o)

Python データ構造 o の JSON 文字列表現を返します。たとえば:

>>> json.JSONEncoder().encode({"foo": ["bar", "baz"]})
'{"foo": ["bar", "baz"]}'

iterencode(o)

与えられたオブジェクト o をエンコードし、得られた文字列表現ごとに yield します。たとえば:

for chunk in json.JSONEncoder().iterencode(bigobject):
    mysocket.write(chunk)

例外

exception json.JSONDecodeError(msg, doc, pos)

ValueError のサブクラスで、以下の追加の属性を持ちます:

msg

フォーマットされていないエラーメッセージです。

doc

パース対象 JSON ドキュメントです。

pos

doc の、解析に失敗した開始インデクスです。

lineno

pos に対応する行です。

colno

pos に対応する列です。

Added in version 3.5.

標準への準拠と互換性

JSON 形式の仕様は RFC 7159 [https://datatracker.ietf.org/doc/html/rfc7159.html] と ECMA-404 [https://www.ecma-international.org/publications-and-standards/standards/ecma-404/] で規定されています。 この節では、このモジュールの RFC への準拠水準について詳しく述べます。 簡単のために、 JSONEncoder および JSONDecoder の子クラスと、明示的に触れられていないパラメータについては考慮しないことにします。

このモジュールは、JavaScript では正しいが JSON では不正ないくつかの拡張が実装されているため、厳密な意味では RFC に準拠していません。特に:

無限および NaN の数値を受け付け、また出力します;

あるオブジェクト内での同じ名前の繰り返しを受け付け、最後の名前と値のペアの値のみを使用します。

この RFC は、RFC 準拠のパーサが RFC 準拠でない入力テキストを受け付けることを許容しているので、このモジュールの脱直列化は技術的に言えば、デフォルトの設定では RFC に準拠しています。

文字エンコーディング

RFC は、UTF-8、UTF-16、UTF-32のいずれかでJSONを表現するように要求しており、UTF-8 が最大の互換性を確保するために推奨されるデフォルトです。

RFC で要求ではなく許可されている通り、このモジュールのシリアライザはデフォルトで ensure_ascii=True という設定を用い、従って、結果の文字列が ASCII 文字しか含まないように出力をエスケープします。

ensure_ascii パラメータ以外は、このモジュールは Python オブジェクトと Unicode 文字列 の間の変換において厳密に定義されていて、それ以外のパラメータで文字エンコーディングに直接的に関わるものはありません。

RFC は JSON テキストの最初にバイトオーダマーク(BOM)を追加することを禁止していますので、このモジュールはその出力に BOM を追加しません。RFC は JSON デシリアライザが入力の一番最初の BOM を無視することを、許容はしますが求めてはいません。このモジュールのデシリアライザは一番最初の BOM を見つけると ValueError を送出します。

RFC は JSON 文字列に正当な Unicode 文字に対応付かないバイト列(例えばペアにならない UTF-16 サロゲートのかたわれ)が含まれることを明示的に禁止してはおらず、もちろんこれは相互運用性の問題を引き起こします。デフォルトでは、このモジュールは(オリジナルの str にある場合)そのようなシーケンスのコードポイントを受け取り、出力します。

無限および NaN の数値

RFC は、無限もしくは NaN の数値の表現は許可していません。それにも関わらずデフォルトでは、このモジュールは Infinity、-Infinity、NaN を正しい JSON の数値リテラルの値であるかのように受け付け、出力します:

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

シリアライザでは、この振る舞いを変更するのに allow_nan パラメータが使えます。デシリアライザでは、この振る舞いを変更するのに parse_constant パラメータが使えます。

オブジェクト中に重複した名前の扱い

RFC は JSON オブジェクト中の名前はユニークでなければならないと規定していますが、JSONオブジェクトで名前が繰り返された場合の扱いについて指定していません。デフォルトでは、このモジュールは例外を送出せず、かわりに重複した名前のうち、最後に出現した名前と値のペア以外を無視します。

>>> weird_json = '{"x": 1, "x": 2, "x": 3}'
>>> json.loads(weird_json)
{'x': 3}

object_pairs_hook パラメータでこの動作を変更できます。

トップレベルの非オブジェクト、非配列の値の扱い

廃止された RFC 4627 [https://datatracker.ietf.org/doc/html/rfc4627.html] によって規定された古いバージョンの JSON では、JSON テキストのトップレベルの値は JSON オブジェクトか配列(Python での dict か list)であることを要求していて、JSON の null, boolean, number, string であることは許されていませんでしたが、この制限は RFC 7159 [https://datatracker.ietf.org/doc/html/rfc7159.html] により取り払われました。このモジュールはこの制限を持っていませんし、シリアライザでもデシリアライズでも、一度としてこの制限で実装されたことはありません。

それにも関わらず、相互運用可能性を最大化したいならば、あなた自身の手で自発的にその制約に忠実に従いたいと思うでしょう。

実装の制限

いくつかの JSON デシリアライザの実装は、以下の制限を設定することがあります。

受け入れられる JSON テキストのサイズ

JSON オブジェクトと配列のネストの最大の深さ

JSON 数値の範囲と精度

JSON 文字列の内容と最大の長さ

このモジュールは関連する Python データ型や Python インタプリタ自身の制約の世界を超えたそのような制約を強要はしません。

JSON にシリアライズする際には、あなたの JSON を消費する側のアプリケーションが持つ当該制約に思いを馳せてください。とりわけJSON 数値を IEEE 754 倍精度浮動小数にデシリアライズする際の問題はありがちで、すなわちその有効桁数と精度の制限の影響を受けます。これは、極端に大きな値を持った Python int をシリアライズするとき、あるいは decimal.Decimal のような "風変わりな" 数値型をシリアライズするとき、に特に関係があります。

コマンドラインインターフェイス

ソースコード: Lib/json/tool.py [https://github.com/python/cpython/tree/3.12/Lib/json/tool.py]

json.tool モジュールは JSON オブジェクトの検証と整形出力のための、単純なコマンドラインインターフェイスを提供します。

オプション引数の infile と outfile が指定されない場合、それぞれ sys.stdin と sys.stdout が使用されます。

$ echo '{"json": "obj"}' | python -m json.tool
{
    "json": "obj"
}
$ echo '{1.2:3.4}' | python -m json.tool
Expecting property name enclosed in double quotes: line 1 column 2 (char 1)

バージョン 3.5 で変更: 出力が、入力と同じ順序になりました。辞書をキーでアルファベット順に並べ替えた出力が欲しければ、 --sort-keys オプションを使ってください。

コマンドラインオプション

infile

検証を行う、あるいは整形出力を行う JSON ファイルを指定します:

$ python -m json.tool mp_films.json
[
    {
        "title": "And Now for Something Completely Different",
        "year": 1971
    },
    {
        "title": "Monty Python and the Holy Grail",
        "year": 1975
    }
]

infile が指定されない場合、 sys.stdin から読み込みます。

outfile

infile の出力を outfile に書き込みます。そうでない場合、 sys.stdout に書き込みます。

--sort-keys

辞書の出力を、キーのアルファベット順にソートします。

Added in version 3.5.

--no-ensure-ascii

非 ASCII 文字のエスケープを無効化します。より詳しくは json.dumps() を参照してください。

Added in version 3.9.

--json-lines

すべての入力行を個別のJSON オブジェクトとしてパースします。

Added in version 3.8.

--indent, --tab, --no-indent, --compact

空白文字の制御のための排他的なオプション。

Added in version 3.9.

-h, --help

ヘルプメッセージを出力します

脚注

[1]

RFC 7159 正誤表 [https://www.rfc-editor.org/errata_search.php?rfc=7159] で述べられている通り、JSON は (ECMAScript Edition 5.1 の) JavaScript とは逆に、 U+2028 (LINE SEPARATOR) と U+2029 (PARAGRAPH SEPARATOR) が文字列内に含まれることを許容しています。

mailbox --- Manipulate mailboxes in various formats

ソースコード: Lib/mailbox.py [https://github.com/python/cpython/tree/3.12/Lib/mailbox.py]

This module defines two classes, Mailbox and Message, for accessing and manipulating on-disk mailboxes and the messages they contain. Mailbox offers a dictionary-like mapping from keys to messages. Message extends the email.message module's Message class with format-specific state and behavior. Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF.

参考

email モジュール

メッセージの表現と操作。

Mailbox オブジェクト

class mailbox.Mailbox

メールボックス。内容を確認したり変更したりできます。

The Mailbox class defines an interface and is not intended to be instantiated. Instead, format-specific subclasses should inherit from Mailbox and your code should instantiate a particular subclass.

The Mailbox interface is dictionary-like, with small keys corresponding to messages. Keys are issued by the Mailbox instance with which they will be used and are only meaningful to that 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 Mailbox instance using the set-like method add() and removed using a del statement or the set-like methods remove() and discard().

Mailbox interface semantics differ from dictionary semantics in some noteworthy ways. Each time a message is requested, a new representation (typically a Message instance) is generated based upon the current state of the mailbox. Similarly, when a message is added to a Mailbox instance, the provided message representation's contents are copied. In neither case is a reference to the message representation kept by the Mailbox instance.

The default Mailbox iterator iterates over message representations, not keys as the default 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 KeyError exception if the corresponding message is subsequently removed.

警告

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 Maildir; try to avoid using single-file formats such as mbox for concurrent writing. If you're modifying a mailbox, you must lock it by calling the lock() and 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.

Mailbox instances have the following methods:

add(message)

メールボックスに message を追加し、それに割り当てられたキーを返します。

引数 message は Message インスタンス、 email.message.Message インスタンス、文字列、バイト文字列、ファイル風オブジェクト (バイナリモードで開かれていなければなりません) を使えます。 message が適切な形式に特化した Message サブクラスのインスタンス (例えばメールボックスが mbox インスタンスのときの mboxMessage インスタンス) であれば、形式ごとの情報が利用されます。そうでなければ、形式ごとに必要な情報は適当なデフォルトが使われます。

バージョン 3.2 で変更: バイナリ入力のサポートが追加されました。

remove(key)

__delitem__(key)

discard(key)

メールボックスから key に対応するメッセージを削除します。

対応するメッセージが無い場合、メソッドが remove() または __delitem__() として呼び出されている時は KeyError 例外が送出されます。しかし、 discard() として呼び出されている場合は例外は発生しません。基づいているメールボックス形式が別のプロセスからの平行した変更をサポートしているならば、この discard() の振る舞いの方が好まれるかもしれません。

__setitem__(key, message)

key に対応するメッセージを message で置き換えます。 key に対応しているメッセージが既に無くなっている場合 KeyError 例外が送出されます。

add() と同様に、引数の message には Message インスタンス、 email.message.Message インスタンス、文字列、バイト文字列、ファイル風オブジェクト (バイナリモードで開かれていなければなりません) を使えます。 message が適切な形式に特化した Message サブクラスのインスタンス (例えばメールボックスが mbox インスタンスのときの mboxMessage インスタンス) であれば、形式ごとの情報が利用されます。そうでなければ、現在 key に対応するメッセージの形式ごとの情報が変更されずに残ります。

iterkeys()

Return an iterator over all keys

keys()

The same as iterkeys(), except that a list is returned rather than an iterator

itervalues()

__iter__()

Return an iterator over representations of all messages. The messages are represented as instances of the appropriate format-specific Message subclass unless a custom message factory was specified when the Mailbox instance was initialized.

注釈

__iter__() は辞書のそれのようにキーについてのイテレータではありません。

values()

The same as itervalues(), except that a list is returned rather than an iterator

iteritems()

Return an 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 Message subclass unless a custom message factory was specified when the Mailbox instance was initialized.

items()

The same as iteritems(), except that a list of pairs is returned rather than an iterator of pairs.

get(key, default=None)

__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 get() and a KeyError exception is raised if the method was called as __getitem__(). The message is represented as an instance of the appropriate format-specific Message subclass unless a custom message factory was specified when the Mailbox instance was initialized.

get_message(key)

key に対応するメッセージの表現を形式ごとの Message サブクラスのインスタンスとして返します。もし対応するメッセージが存在しなければ KeyError 例外が送出されます。

get_bytes(key)

key に対応するメッセージのバイト列を返すか、そのようなメッセージが存在しない場合は KeyError 例外を送出します。

Added in version 3.2.

get_string(key)

key に対応するメッセージの文字列表現を返すか、そのようなメッセージが存在しない場合は KeyError 例外を送出します。このメッセージは email.message.Message を通して処理されて7ビットクリーンな表現へ変換されます。

get_file(key)

Return a file-like representation of the message corresponding to key, or raise a 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 binary file; previously it was incorrectly returned in text mode. Also, the file-like object now supports the context manager protocol: you can use a with statement to automatically close it.

注釈

Unlike other representations of messages, file-like representations are not necessarily independent of the Mailbox instance that created them or of the underlying mailbox. More specific documentation is provided by each subclass.

__contains__(key)

key がメッセージに対応していれば True を、そうでなければ False を返します。

__len__()

メールボックス中のメッセージ数を返します。

clear()

メールボックスから全てのメッセージを削除します。

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 Message subclass unless a custom message factory was specified when the Mailbox instance was initialized.

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 KeyError exception. The message is represented as an instance of the appropriate format-specific Message subclass unless a custom message factory was specified when the Mailbox instance was initialized.

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 __setitem__(). As with __setitem__(), each key must already correspond to a message in the mailbox or else a KeyError exception will be raised, so in general it is incorrect for arg to be a Mailbox instance.

注釈

辞書と違い、キーワード引数はサポートされていません。

flush()

Write any pending changes to the filesystem. For some Mailbox subclasses, changes are always written immediately and flush() does nothing, but you should still make a habit of calling this method.

lock()

メールボックスの排他的アドバイザリロックを取得し、他のプロセスが変更しないようにします。ロックが取得できない場合 ExternalClashError が送出されます。ロック機構はメールボックス形式によって変わります。メールボックスの内容に変更を加えるときは いつも ロックを掛けるべきです。

unlock()

メールボックスのロックが存在する場合は解放します。

close()

Flush the mailbox, unlock it if necessary, and close any open files. For some Mailbox subclasses, this method does nothing.

Maildir オブジェクト

class mailbox.Maildir(dirname, factory=None, create=True)

Maildir 形式のメールボックスのための Mailbox のサブクラス。パラメータ factory は呼び出し可能オブジェクトで (バイナリモードで開かれているかのように振る舞う)ファイル風メッセージ表現を受け付けて好みの表現を返すものです。 factory が None ならば、 MaildirMessage がデフォルトのメッセージ表現として使われます。 create が True ならばメールボックスが存在しないときには作成します。

create が True で、パス dirname が存在する場合、ディレクトリレイアウトを検証せずに既存の maildir として扱います。

path ではなく dirname と命名される歴史的な理由のためです。

Maildir はディレクトリ型のメールボックス形式でメール転送エージェント qmail 用に発明され、現在では多くの他のプログラムでもサポートされているものです。Maildir メールボックス中のメッセージは共通のディレクトリ構造の下で個別のファイルに保存されます。このデザインにより、Maildir メールボックスは複数の無関係のプログラムからデータを失うことなくアクセスしたり変更したりできます。そのためロックは不要です。

Maildir メールボックスには三つのサブディレクトリ tmp, new, cur があります。メッセージはまず tmp サブディレクトリに瞬間的に作られた後、 new サブディレクトリに移動されて配送を完了します。メールユーザエージェントが引き続いて cur サブディレクトリにメッセージを移動しメッセージの状態についての情報をファイル名に追加される特別な "info" セクションに保存することができます。

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 '.' is the first character in its name. Folder names are represented by Maildir without the leading '.'. Each folder is itself a Maildir mailbox but should not contain other folders. Instead, a logical nesting is indicated using '.' to delimit levels, e.g., "Archived.2005.07".

colon

本来の Maildir 仕様ではある種のメッセージのファイル名にコロン (':') を使う必要があります。しかしながら、オペレーティングシステムによってはこの文字をファイル名に含めることができないことがあります。そういった環境で Maildir のような形式を使いたい場合、代わりに使われる文字を指定する必要があります。感嘆符 ('!') を使うのが一般的な選択です。以下の例を見てください:

import mailbox
mailbox.Maildir.colon = '!'

The colon attribute may also be set on a per-instance basis.

Maildir instances have all of the methods of Mailbox in addition to the following:

list_folders()

全てのフォルダ名のリストを返します。

get_folder(folder)

Return a Maildir instance representing the folder whose name is folder. A NoSuchMailboxError exception is raised if the folder does not exist.

add_folder(folder)

Create a folder whose name is folder and return a Maildir instance representing it.

remove_folder(folder)

名前が folder であるフォルダを削除します。もしフォルダに一つでもメッセージが含まれていれば NotEmptyError 例外が送出されフォルダは削除されません。

clean()

過去36時間以内にアクセスされなかったメールボックス内の一時ファイルを削除します。Maildir 仕様はメールを読むプログラムはときどきこの作業をすべきだとしています。

Some Mailbox methods implemented by Maildir deserve special remarks:

add(message)

__setitem__(key, message)

update(arg)

警告

これらのメソッドは一意的なファイル名をプロセスIDに基づいて生成します。複数のスレッドを使う場合は、同じメールボックスを同時に操作しないようにスレッド間で調整しておかないと検知されない名前の衝突が起こりメールボックスを壊すかもしれません。

flush()

Maildir メールボックスへの変更は即時に適用されるので、このメソッドは何もしません。

lock()

unlock()

Maildir メールボックスはロックをサポート(または要求)しないので、このメソッドは何もしません。

close()

Maildir instances do not keep any open files and the underlying mailboxes do not support locking, so this method does nothing.

get_file(key)

ホストのプラットフォームによっては、返されたファイルが開いている間、元になったメッセージを変更したり削除したりできない場合があります。

参考

Courier の maildir マニュアルページ [https://www.courier-mta.org/maildir.html]

Maildir 形式の仕様。フォルダをサポートする一般的な拡張について記述されています。

Using maildir format [https://cr.yp.to/proto/maildir.html]

Maildir 形式の発明者による注意書き。更新された名前生成規則と "info" の解釈についても含まれます。

mbox オブジェクト

class mailbox.mbox(path, factory=None, create=True)

mbox 形式のメールボックスのための Mailbox のサブクラス。パラメータ factory は呼び出し可能オブジェクトで (バイナリモードで開かれているかのように振る舞う)ファイル風メッセージ表現を受け付けて好みの表現を返すものです。 factory が None ならば、 mboxMessage がデフォルトのメッセージ表現として使われます。 create が True ならばメールボックスが存在しないときには作成します。

mbox 形式は Unixシステム上でメールを保存する古くからある形式です。mbox メールボックスでは全てのメッセージが一つのファイルに保存されておりそれぞれのメッセージは "From " という5文字で始まる行を先頭に付けられています。

Several variations of the mbox format exist to address perceived shortcomings in the original. In the interest of compatibility, mbox implements the original format, which is sometimes referred to as mboxo. This means that the 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 Mailbox methods implemented by mbox deserve special remarks:

get_file(key)

Using the file after calling flush() or close() on the mbox instance may yield unpredictable results or raise an exception.

lock()

unlock()

Three locking mechanisms are used---dot locking and, if available, the flock() and lockf() system calls.

参考

tin の mbox マニュアルページ [http://www.tin.org/bin/man.cgi?section=5&topic=mbox]

mbox 形式の仕様でロックについての詳細を含む。

Configuring Netscape Mail on Unix: Why The Content-Length Format is Bad [https://www.jwz.org/doc/content-length.html]

バリエーションの一つではなくオリジナルの mbox を使う理由。

"mbox" は相互に互換性を持たないいくつかのメールボックスフォーマットの集まりです [https://www.loc.gov/preservation/digital/formats/fdd/fdd000383.shtml]

mbox バリエーションの歴史。

MH オブジェクト

class mailbox.MH(path, factory=None, create=True)

MH 形式のメールボックスのための Mailbox のサブクラス。パラメータ factory は呼び出し可能オブジェクトで (バイナリモードで開かれているかのように振る舞う)ファイル風メッセージ表現を受け付けて好みの表現を返すものです。 factory が None ならば、 MHMessage がデフォルトのメッセージ表現として使われます。 create が True ならばメールボックスが存在しないときには作成します。

MH はディレクトリに基づいたメールボックス形式で MH Message Handling System というメールユーザエージェントのために発明されました。 MH メールボックス中のそれぞれのメッセージは一つのファイルとして収められています。 MH メールボックスにはメッセージの他に別の MH メールボックス (フォルダ と呼ばれます)を含んでもかまいません。フォルダは無限にネストできます。 MH メールボックスにはもう一つ シーケンス という名前付きのリストでメッセージをサブフォルダに移動することなく論理的に分類するものがサポートされています。シーケンスは各フォルダの .mh_sequences というファイルで定義されます。

The MH class manipulates MH mailboxes, but it does not attempt to emulate all of mh's behaviors. In particular, it does not modify and is not affected by the context or .mh_profile files that are used by mh to store its state and configuration.

MH instances have all of the methods of Mailbox in addition to the following:

list_folders()

全てのフォルダ名のリストを返します。

get_folder(folder)

Return an MH instance representing the folder whose name is folder. A NoSuchMailboxError exception is raised if the folder does not exist.

add_folder(folder)

Create a folder whose name is folder and return an MH instance representing it.

remove_folder(folder)

名前が folder であるフォルダを削除します。もしフォルダに一つでもメッセージが含まれていれば NotEmptyError 例外が送出されフォルダは削除されません。

get_sequences()

folder という名前のフォルダを削除します。フォルダにメッセージが一つでも残っていれば、NotEmptyError 例外が送出されフォルダは削除されません。

set_sequences(sequences)

シーケンス名をキーのリストに対応付ける辞書を返します。シーケンスが一つもなければ空の辞書を返します。

pack()

メールボックス中のシーケンスを get_sequences() で返されるような名前とキーのリストを対応付ける辞書 sequences に基づいて再定義します。

注釈

番号付けの間隔を詰める必要に応じてメールボックス中のメッセージの名前を付け替えます。シーケンスのリストのエントリもそれに応じて更新されます。

Some Mailbox methods implemented by MH deserve special remarks:

remove(key)

__delitem__(key)

discard(key)

これらのメソッドはメッセージを直ちに削除します。名前の前にコンマを付加してメッセージに削除の印を付けるという MH の規約は使いません。

lock()

unlock()

Three locking mechanisms are used---dot locking and, if available, the flock() and lockf() system calls. For MH mailboxes, locking the mailbox means locking the .mh_sequences file and, only for the duration of any operations that affect them, locking individual message files.

get_file(key)

ホストプラットフォームにより、ファイルが開かれたままの場合はメッセージを削除することができない場合があります。

flush()

MH メールボックスへの変更は即時に適用されますのでこのメソッドは何もしません。

close()

MH instances do not keep any open files, so this method is equivalent to unlock().

参考

nmh - Message Handling System [https://www.nongnu.org/nmh/]

mh の改良版である nmh のホームページ。

MH & nmh: Email for Users & Programmers [https://rand-mh.sourceforge.io/book/]

GPLライセンスの mh および nmh の本で、このメールボックス形式についての情報があります。

Babyl オブジェクト

class mailbox.Babyl(path, factory=None, create=True)

Babyl 形式のメールボックスのための Mailbox のサブクラス。パラメータ factory は呼び出し可能オブジェクトで (バイナリモードで開かれているかのように振る舞う)ファイル風メッセージ表現を受け付けて好みの表現を返すものです。 factory が None ならば、 BabylMessage がデフォルトのメッセージ表現として使われます。 create が True ならばメールボックスが存在しないときには作成します。

Babyl は単一ファイルのメールボックス形式で Emacs に付属している Rmail メールユーザエージェントで使われているものです。メッセージの開始は Control-Underscore ('\037') および Control-L ('\014') の二文字を含む行で示されます。メッセージの終了は次のメッセージの開始または最後のメッセージの場合には Control-Underscore を含む行で示されます。

Babyl メールボックス中のメッセージには二つのヘッダのセット、オリジナルヘッダといわゆる可視ヘッダ、があります。可視ヘッダは典型的にはオリジナルヘッダの一部を分り易いように再整形したり短くしたりしたものです。 Babyl メールボックス中のそれぞれのメッセージには ラベル というそのメッセージについての追加情報を記録する短い文字列のリストを伴い、メールボックス中に見出されるユーザが定義した全てのラベルのリストは Babyl オプションセクションに保持されます。

Babyl instances have all of the methods of Mailbox in addition to the following:

get_labels()

メールボックスで使われているユーザが定義した全てのラベルのリストを返します。

注釈

メールボックスにどのようなラベルが存在するかを決めるのに、Babyl オプションセクションのリストを参考にせず、実際のメッセージを捜索しますが、Babyl セクションもメールボックスが変更されたときにはいつでも更新されます。

Some Mailbox methods implemented by Babyl deserve special remarks:

get_file(key)

Babyl メールボックスにおいて、メッセージのヘッダはボディと繋がって格納されていません。ファイル風の表現を生成するために、ヘッダとボディがファイルと同じ API を持つ io.BytesIO インスタンスに一緒にコピーされます。その結果、ファイル風オブジェクトは元にしているメールボックスとは真に独立していますが、文字列表現と比べてメモリーを節約することにはなりません。

lock()

unlock()

Three locking mechanisms are used---dot locking and, if available, the flock() and lockf() system calls.

参考

Format of Version 5 Babyl Files [https://quimby.gnus.org/notes/BABYL]

Babyl 形式の仕様。

Reading Mail with Rmail [https://www.gnu.org/software/emacs/manual/html_node/emacs/Rmail.html]

Rmail のマニュアルで Babyl のセマンティクスについての情報も少しある。

MMDF オブジェクト

class mailbox.MMDF(path, factory=None, create=True)

MMDF 形式のメールボックスのための Mailbox のサブクラス。パラメータ factory は呼び出し可能オブジェクトで (バイナリモードで開かれているかのように振る舞う)ファイル風メッセージ表現を受け付けて好みの表現を返すものです。 factory が None ならば、 MMDFMessage がデフォルトのメッセージ表現として使われます。 create が True ならばメールボックスが存在しないときには作成します。

MMDF は単一ファイルのメールボックス形式で Multichannel Memorandum Distribution Facility というメール転送エージェント用に発明されたものです。各メッセージは mbox と同様の形式で収められますが、前後を4つの Control-A ('\001') を含む行で挟んであります。mbox 形式と同じようにそれぞれのメッセージの開始は "From " の5文字を含む行で示されますが、それ以外の場所での "From " は格納の際 ">From " には変えられません。それは追加されたメッセージ区切りによって新たなメッセージの開始と見間違うことが避けられるからです。

Some Mailbox methods implemented by MMDF deserve special remarks:

get_file(key)

Using the file after calling flush() or close() on the MMDF instance may yield unpredictable results or raise an exception.

lock()

unlock()

Three locking mechanisms are used---dot locking and, if available, the flock() and lockf() system calls.

参考

mmdf man page from tin [http://www.tin.org/bin/man.cgi?section=5&topic=mmdf]

ニュースリーダ tin のドキュメント中の MMDF 形式仕様。

MMDF [https://en.wikipedia.org/wiki/MMDF]

Multichannel Memorandum Distribution Facility についてのウィキペディアの記事。

Message オブジェクト

class mailbox.Message(message=None)

A subclass of the email.message module's Message. Subclasses of 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 email.message.Message instance, its contents are copied; furthermore, any format-specific information is converted insofar as possible if message is a Message instance. If message is a string, a byte string, or a file, it should contain an RFC 2822 [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.

サブクラスにより提供される形式ごとの状態と動作は様々ですが、一般に或るメールボックスに固有のものでないプロパティだけがサポートされます(おそらくプロパティのセットはメールボックス形式ごとに固有でしょうが)。例えば、単一ファイルメールボックス形式におけるファイルオフセットやディレクトリ式メールボックス形式におけるファイル名は保持されません、というのもそれらは元々のメールボックスにしか適用できないからです。しかし、メッセージがユーザに読まれたかどうかあるいは重要だとマークされたかどうかという状態は保持されます、というのはそれらはメッセージ自体に適用されるからです。

There is no requirement that Message instances be used to represent messages retrieved using Mailbox instances. In some situations, the time and memory required to generate Message representations might not be acceptable. For such situations, Mailbox instances also offer string and file-like representations, and a custom message factory may be specified when a Mailbox instance is initialized.

MaildirMessage オブジェクト

class mailbox.MaildirMessage(message=None)

Maildir 固有の動作をするメッセージ。引数 message は Message のコンストラクタと同じ意味を持ちます。

通常、メールユーザエージェントは new サブディレクトリにある全てのメッセージをユーザが最初にメールボックスを開くか閉じるかした後で cur サブディレクトリに移動し、メッセージが実際に読まれたかどうかを記録します。 cur にある各メッセージには状態情報を保存するファイル名に付け加えられた "info" セクションがあります。(メールリーダの中には "info" セクションを new にあるメッセージに付けることもあります。) "info" セクションには二つの形式があります。一つは "2," の後に標準化されたフラグのリストを付けたもの (たとえば "2,FR")、もう一つは "1," の後にいわゆる実験的情報を付け加えるものです。 Maildir の標準的なフラグは以下の通りです:

Flag

意味

説明

D

ドラフト(Draft)

作成中

F

フラグ付き(Flagged)

重要とされたもの

P

通過(Passed)

転送、再送またはバウンス

R

返答済み(Replied)

返答されたもの

S

既読(Seen)

読んだもの

T

ごみ(Trashed)

削除予定とされたもの

MaildirMessage instances offer the following methods:

get_subdir()

"new" (メッセージが new サブディレクトリに保存されるべき場合) または "cur" (メッセージが cur サブディレクトリに保存されるべき場合)のどちらかを返します。

注釈

A message is typically moved from new to cur after its mailbox has been accessed, whether or not the message is has been read. A message msg has been read if "S" in msg.get_flags() is True.

set_subdir(subdir)

メッセージが保存されるべきサブディレクトリをセットします。パラメータ subdir は "new" または "cur" のいずれかでなければなりません。

get_flags()

現在セットされているフラグを特定する文字列を返します。メッセージが標準 Maildir 形式に準拠しているならば、結果はアルファベット順に並べられたゼロまたは1回の 'D'、'F'、'P'、'R'、'S'、'T' をつなげたものです。空文字列が返されるのはフラグが一つもない場合、または "info" が実験的セマンティクスを使っている場合です。

set_flags(flags)

flags で指定されたフラグをセットし、他のフラグは下ろします。

add_flag(flag)

flag で指定されたフラグをセットしますが他のフラグは変えません。一度に二つ以上のフラグをセットすることは、flag に2文字以上の文字列を指定すればできます。現在の "info" はフラグの代わりに実験的情報を使っていても上書きされます。

remove_flag(flag)

flag で指定されたフラグを下ろしますが他のフラグは変えません。一度に二つ以上のフラグを取り除くことは、flag に2文字以上の文字列を指定すればできます。"info" がフラグの代わりに実験的情報を使っている場合は現在の "info" は書き換えられません。

get_date()

メッセージの配送日時をエポックからの秒数を表わす浮動小数点数で返します。

set_date(date)

メッセージの配送日時を date にセットします。date はエポックからの秒数を表わす浮動小数点数です。

get_info()

メッセージの "info" を含む文字列を返します。このメソッドは実験的 (即ちフラグのリストでない) "info" にアクセスし、また変更するのに役立ちます。

set_info(info)

"info" に文字列 info をセットします。

When a MaildirMessage instance is created based upon an mboxMessage or MMDFMessage instance, the Status and X-Status headers are omitted and the following conversions take place:

結果の状態

mboxMessage または MMDFMessage の状態

"cur" サブディレクトリ

O フラグ

F フラグ

F フラグ

R フラグ

A フラグ

S フラグ

R フラグ

T フラグ

D フラグ

When a MaildirMessage instance is created based upon an MHMessage instance, the following conversions take place:

結果の状態

MHMessage の状態

"cur" サブディレクトリ

"unseen" シーケンス

"cur" サブディレクトリおよび S フラグ

"unseen" シーケンス無し

F フラグ

"flagged" シーケンス

R フラグ

"replied" シーケンス

When a MaildirMessage instance is created based upon a BabylMessage instance, the following conversions take place:

結果の状態

BabylMessage の状態

"cur" サブディレクトリ

"unseen" ラベル

"cur" サブディレクトリおよび S フラグ

"unseen" ラベル無し

P フラグ

"forwarded" または "resent" ラベル

R フラグ

"answered" ラベル

T フラグ

"deleted" ラベル

mboxMessage オブジェクト

class mailbox.mboxMessage(message=None)

mbox 固有の動作をするメッセージ。引数 message は Message のコンストラクタと同じ意味を持ちます。

mbox メールボックス中のメッセージは単一ファイルにまとめて格納されています。送り主のエンベロープアドレスおよび配送日時は通常メッセージの開始を示す "From " から始まる行に記録されますが、正確なフォーマットに関しては mbox の実装ごとに大きな違いがあります。メッセージの状態を示すフラグ、たとえば読んだかどうかあるいは重要だとマークを付けられているかどうかといったようなもの、は典型的には Status および X-Status に収められます。

規定されている mbox メッセージのフラグは以下の通りです:

Flag

意味

説明

R

読んだもの

読んだもの

O

古い(Old)

以前に MUA に発見された

D

削除(Deleted)

削除予定とされたもの

F

フラグ付き(Flagged)

重要とされたもの

A

返答済み(Answered)

返答されたもの

"R" および "O" フラグは Status ヘッダに記録され、 "D"、"F"、"A" フラグは X-Status ヘッダに記録されます。フラグとヘッダは通常記述された順番に出現します。

mboxMessage instances offer the following methods:

get_from()

mbox メールボックスのメッセージの開始を示す "From " 行を表わす文字列を返します。先頭の "From " および末尾の改行は含まれません。

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 time.struct_time instance, a tuple suitable for passing to time.strftime(), or True (to use time.gmtime()).

get_flags()

現在セットされているフラグを特定する文字列を返します。メッセージが規定された形式に準拠しているならば、結果は次の順に並べられた 0回か1回の 'R'、'O'、'D'、'F'、'A' です。

set_flags(flags)

flags で指定されたフラグをセットして、他のフラグは下ろします。flags は並べられたゼロまたは1回の 'R'、'O'、'D'、'F'、'A' です。

add_flag(flag)

flag で指定されたフラグをセットしますが他のフラグは変えません。一度に二つ以上のフラグをセットすることは、flag に2文字以上の文字列を指定すればできます。

remove_flag(flag)

flag で指定されたフラグを下ろしますが他のフラグは変えません。一二つ以上のフラグを取り除くことは、flag に2文字以上の文字列を指定すればできます。

When an mboxMessage instance is created based upon a MaildirMessage instance, a "From " line is generated based upon the MaildirMessage instance's delivery date, and the following conversions take place:

結果の状態

MaildirMessage の状態

R フラグ

S フラグ

O フラグ

"cur" サブディレクトリ

D フラグ

T フラグ

F フラグ

F フラグ

A フラグ

R フラグ

When an mboxMessage instance is created based upon an MHMessage instance, the following conversions take place:

結果の状態

MHMessage の状態

R フラグおよび O フラグ

"unseen" シーケンス無し

O フラグ

"unseen" シーケンス

F フラグ

"flagged" シーケンス

A フラグ

"replied" シーケンス

When an mboxMessage instance is created based upon a BabylMessage instance, the following conversions take place:

結果の状態

BabylMessage の状態

R フラグおよび O フラグ

"unseen" ラベル無し

O フラグ

"unseen" ラベル

D フラグ

"deleted" ラベル

A フラグ

"answered" ラベル

When a mboxMessage instance is created based upon an MMDFMessage instance, the "From " line is copied and all flags directly correspond:

結果の状態

MMDFMessage の状態

R フラグ

R フラグ

O フラグ

O フラグ

D フラグ

D フラグ

F フラグ

F フラグ

A フラグ

A フラグ

MHMessage オブジェクト

class mailbox.MHMessage(message=None)

MH 固有の動作をするメッセージ。引数 message は Message のコンストラクタと同じ意味を持ちます。

MH メッセージは伝統的な意味あいにおいてマークやフラグをサポートしません。しかし、MH メッセージにはシーケンスがあり任意のメッセージを論理的にグループ分けできます。いくつかのメールソフト(標準の mh や nmh はそうではありませんが) は他の形式におけるフラグとほぼ同じようにシーケンスを使います:

シーケンス

説明

unseen

読んではいないが既にMUAに見つけられている

replied

返答されたもの

flagged

重要とされたもの

MHMessage instances offer the following methods:

get_sequences()

このメッセージを含むシーケンスの名前のリストを返す。

set_sequences(sequences)

このメッセージを含むシーケンスのリストをセットする。

add_sequence(sequence)

sequence をこのメッセージを含むシーケンスのリストに追加する。

remove_sequence(sequence)

sequence をこのメッセージを含むシーケンスのリストから除く。

When an MHMessage instance is created based upon a MaildirMessage instance, the following conversions take place:

結果の状態

MaildirMessage の状態

"unseen" シーケンス

S フラグ無し

"replied" シーケンス

R フラグ

"flagged" シーケンス

F フラグ

When an MHMessage instance is created based upon an mboxMessage or MMDFMessage instance, the Status and X-Status headers are omitted and the following conversions take place:

結果の状態

mboxMessage または MMDFMessage の状態

"unseen" シーケンス

R フラグ無し

"replied" シーケンス

A フラグ

"flagged" シーケンス

F フラグ

When an MHMessage instance is created based upon a BabylMessage instance, the following conversions take place:

結果の状態

BabylMessage の状態

"unseen" シーケンス

"unseen" ラベル

"replied" シーケンス

"answered" ラベル

BabylMessage オブジェクト

class mailbox.BabylMessage(message=None)

Babyl 固有の動作をするメッセージ。引数 message は Message のコンストラクタと同じ意味を持ちます。

ある種のメッセージラベルは アトリビュート と呼ばれ、規約により特別な意味が与えられています。アトリビュートは以下の通りです:

ラベル

説明

unseen

読んではいないが既にMUAに見つけられている

deleted

削除予定とされたもの

filed

他のファイルまたはメールボックスにコピーされた

answered

返答されたもの

forwarded

転送された

edited

ユーザによって変更された

resent

再送された

By default, Rmail displays only visible headers. The BabylMessage class, though, uses the original headers because they are more complete. Visible headers may be accessed explicitly if desired.

BabylMessage instances offer the following methods:

get_labels()

メッセージに付いているラベルのリストを返します。

set_labels(labels)

メッセージに付いているラベルのリストを labels にセットします。

add_label(label)

メッセージに付いているラベルのリストに label を追加します。

remove_label(label)

メッセージに付いているラベルのリストから label を削除します。

get_visible()

ヘッダがメッセージの可視ヘッダでありボディが空であるような Message インスタンスを返します。

set_visible(visible)

メッセージの可視ヘッダを visible のヘッダと同じにセットします。引数 visible は Message インスタンスまたは email.message.Message インスタンス、文字列、ファイル風オブジェクト(テキストモードで開かれてなければなりません)のいずれかです。

update_visible()

When a 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 Date, From, Reply-To, To, CC, and Subject that are present in the original headers but not the visible headers are added to the visible headers.

When a BabylMessage instance is created based upon a MaildirMessage instance, the following conversions take place:

結果の状態

MaildirMessage の状態

"unseen" ラベル

S フラグ無し

"deleted" ラベル

T フラグ

"answered" ラベル

R フラグ

"forwarded" ラベル

P フラグ

When a BabylMessage instance is created based upon an mboxMessage or MMDFMessage instance, the Status and X-Status headers are omitted and the following conversions take place:

結果の状態

mboxMessage または MMDFMessage の状態

"unseen" ラベル

R フラグ無し

"deleted" ラベル

D フラグ

"answered" ラベル

A フラグ

When a BabylMessage instance is created based upon an MHMessage instance, the following conversions take place:

結果の状態

MHMessage の状態

"unseen" ラベル

"unseen" シーケンス

"answered" ラベル

"replied" シーケンス

MMDFMessage オブジェクト

class mailbox.MMDFMessage(message=None)

MMDF 固有の動作をするメッセージ。引数 message は Message のコンストラクタと同じ意味を持ちます。

mbox メールボックスのメッセージと同様に、MMDF メッセージは送り主のアドレスと配送日時が最初の "From " で始まる行に記録されています。同様に、メッセージの状態を示すフラグは通常 Status および X-Status ヘッダに収められています。

よく使われる MMDF メッセージのフラグは mbox メッセージのものと同一で以下の通りです:

Flag

意味

説明

R

読んだもの

読んだもの

O

古い(Old)

以前に MUA に発見された

D

削除(Deleted)

削除予定とされたもの

F

フラグ付き(Flagged)

重要とされたもの

A

返答済み(Answered)

返答されたもの

"R" および "O" フラグは Status ヘッダに記録され、 "D"、"F"、"A" フラグは X-Status ヘッダに記録されます。フラグとヘッダは通常記述された順番に出現します。

MMDFMessage instances offer the following methods, which are identical to those offered by mboxMessage:

get_from()

mbox メールボックスのメッセージの開始を示す "From " 行を表わす文字列を返します。先頭の "From " および末尾の改行は含まれません。

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 time.struct_time instance, a tuple suitable for passing to time.strftime(), or True (to use time.gmtime()).

get_flags()

現在セットされているフラグを特定する文字列を返します。メッセージが規定された形式に準拠しているならば、結果は次の順に並べられた 0回か1回の 'R'、'O'、'D'、'F'、'A' です。

set_flags(flags)

flags で指定されたフラグをセットして、他のフラグは下ろします。flags は並べられたゼロまたは1回の 'R'、'O'、'D'、'F'、'A' です。

add_flag(flag)

flag で指定されたフラグをセットしますが他のフラグは変えません。一度に二つ以上のフラグをセットすることは、flag に2文字以上の文字列を指定すればできます。

remove_flag(flag)

flag で指定されたフラグを下ろしますが他のフラグは変えません。一二つ以上のフラグを取り除くことは、flag に2文字以上の文字列を指定すればできます。

When an MMDFMessage instance is created based upon a MaildirMessage instance, a "From " line is generated based upon the MaildirMessage instance's delivery date, and the following conversions take place:

結果の状態

MaildirMessage の状態

R フラグ

S フラグ

O フラグ

"cur" サブディレクトリ

D フラグ

T フラグ

F フラグ

F フラグ

A フラグ

R フラグ

When an MMDFMessage instance is created based upon an MHMessage instance, the following conversions take place:

結果の状態

MHMessage の状態

R フラグおよび O フラグ

"unseen" シーケンス無し

O フラグ

"unseen" シーケンス

F フラグ

"flagged" シーケンス

A フラグ

"replied" シーケンス

When an MMDFMessage instance is created based upon a BabylMessage instance, the following conversions take place:

結果の状態

BabylMessage の状態

R フラグおよび O フラグ

"unseen" ラベル無し

O フラグ

"unseen" ラベル

D フラグ

"deleted" ラベル

A フラグ

"answered" ラベル

When an MMDFMessage instance is created based upon an mboxMessage instance, the "From " line is copied and all flags directly correspond:

結果の状態

mboxMessage の状態

R フラグ

R フラグ

O フラグ

O フラグ

D フラグ

D フラグ

F フラグ

F フラグ

A フラグ

A フラグ

例外

The following exception classes are defined in the mailbox module:

exception mailbox.Error

他の全てのモジュール固有の例外の基底クラス。

exception mailbox.NoSuchMailboxError

メールボックスがあると思っていたが見つからなかった場合に送出されます。これはたとえば Mailbox のサブクラスを存在しないパスでインスタンス化しようとしたとき(かつ create パラメータは False であった場合)、あるいは存在しないフォルダを開こうとした時などに発生します。

exception mailbox.NotEmptyError

メールボックスが空であることを期待されているときに空でない場合、たとえばメッセージの残っているフォルダを削除しようとした時などに送出されます。

exception mailbox.ExternalClashError

メールボックスに関係したある条件がプログラムの制御を外れてそれ以上作業を続けられなくなった場合、たとえば他のプログラムが既に保持しているロックを取得しようとして失敗したとき、あるいは一意的に生成されたファイル名が既に存在していた場合などに送出されます。

exception mailbox.FormatError

ファイル中のデータが解析できない場合、たとえば MH インスタンスが壊れた .mh_sequences ファイルを読もうと試みた場合などに送出されます。

使用例

メールボックス中の面白そうなメッセージのサブジェクトを全て印字する簡単な例:

import mailbox
for message in mailbox.mbox('~/mbox'):
    subject = message['subject']       # Could possibly be None.
    if subject and 'python' in subject.lower():
        print(subject)

Babyl メールボックスから MH メールボックスへ全てのメールをコピーし、変換可能な全ての形式固有の情報を変換する:

import mailbox
destination = mailbox.MH('~/Mail')
destination.lock()
for message in mailbox.Babyl('~/RMAIL'):
    destination.add(mailbox.MHMessage(message))
destination.flush()
destination.unlock()

この例は幾つかのメーリングリストのメールをソートするものです。他のプログラムと平行して変更を加えることでメールが破損したり、プログラムを中断することでメールを失ったり、はたまた半端なメッセージがメールボックス中にあることで途中で終了してしまう、といったことを避けるように注意深く扱っています:

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()

mimetypes --- Map filenames to MIME types

ソースコード: Lib/mimetypes.py [https://github.com/python/cpython/tree/3.12/Lib/mimetypes.py]

mimetypes モジュールは、ファイル名あるいは URL と、ファイル名拡張子に関連付けられた MIME 型とを変換します。ファイル名から MIME 型へと、 MIME 型からファイル名拡張子への変換が提供されます; 後者の変換では符号化方式はサポートされていません。

このモジュールは、一つのクラスと多くの便利な関数を提供します。これらの関数がこのモジュールへの標準のインターフェースですが、アプリケーションによっては、そのクラスにも関係するかもしれません。

以下で説明されている関数は、このモジュールへの主要なインターフェースを提供します。たとえモジュールが初期化されていなくても、もしこれらの関数が、 init() がセットアップする情報に依存していれば、これらの関数は、 init() を呼びます。

mimetypes.guess_type(url, strict=True)

url で与えられるファイル名あるいは URL に基づいて、ファイルの型を推定します。URL は文字列または path-like object です。

戻り値は、タプル (type, encoding) です、ここで type は、もし型が(拡張子がないあるいは未定義のため)推定できない場合は、 None を、あるいは、 MIME content-type ヘッダ に利用できる、 'type/subtype' の形の文字列です。

encoding は、符合化方式がない場合は None を、あるいは、符号化に使われるプログラムの名前 (たとえば、 compress あるいは gzip)です。符号化方式は Content-Encoding ヘッダとして使うのに適しており、 Content-Transfer-Encoding ヘッダには適して いません 。マッピングはテーブル駆動です。符号化方式のサフィックスは大/小文字を区別します; データ型サフィックスは、最初大/小文字を区別して試し、それから大/小文字を区別せずに試します。

省略可能な strict 引数は、既知の MIME 型のリストとして認識されるものが、IANAに登録された [https://www.iana.org/assignments/media-types/media-types.xhtml] 正式な型のみに限定されるかどうかを指定するフラグです。strict が True (デフォルト)の時は、IANA 型のみがサポートされます; strict が False のときは、いくつかの追加の、非標準ではあるが、一般的に使用される MIME 型も認識されます。

バージョン 3.8 で変更: Added support for url being a path-like object.

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 ('.'). The extensions are not guaranteed to have been associated with any particular data stream, but would be mapped to the MIME type type by guess_type().

省略可能な strict 引数は guess_type() 関数のものと同じ意味を持ちます。

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 ('.'). The extension is not guaranteed to have been associated with any particular data stream, but would be mapped to the MIME type type by guess_type(). If no extension can be guessed for type, None is returned.

省略可能な strict 引数は guess_type() 関数のものと同じ意味を持ちます。

モジュールの動作を制御するために、いくつかの追加の関数とデータ項目が利用できます。

mimetypes.init(files=None)

内部のデータ構造を初期化します。もし files が与えられていれば、これはデフォルトの type map を増やすために使われる、一連のファイル名でなければなりません。もし省略されていれば、使われるファイル名は knownfiles から取られます。 Windows であれば、現在のレジストリの設定が読み込まれます。 files あるいは knownfiles 内の各ファイル名は、それ以前に現れる名前より優先されます。繰り返し init() を呼び出すことは許されています。

files に空リストを与えることで、システムのデフォルトが適用されるのを避けることが出来ます; 組み込みのリストから well-known な値だけが取り込まれます。

files が None の場合、内部のデータ構造は初期のデフォルト値に完全に再構築されます。これは安定な操作であり、複数回呼び出されたときは同じ結果になります。

バージョン 3.2 で変更: 前のバージョンでは、 Windows のレジストリの設定は無視されていました。

mimetypes.read_mime_types(filename)

ファイル filename で与えられた型のマップが、もしあればロードします。型のマップは、先頭の dot ('.') を含むファイル名拡張子を、'type/subtype' の形の文字列にマッピングする辞書として返されます。もしファイル filename が存在しないか、読み込めなければ、None が返されます。

mimetypes.add_type(type, ext, strict=True)

MIME 型 type からのマッピングを拡張子 ext に追加します。拡張子がすでに既知であれば、新しい型が古いものに置き替わります。その型がすでに既知であれば、その拡張子が、既知の拡張子のリストに追加されます。

strict が True の時(デフォルト)は、そのマッピングは正式な MIME 型に、そうでなければ、非標準の MIME 型に追加されます。

mimetypes.inited

グローバルなデータ構造が初期化されているかどうかを示すフラグ。これは init() により True に設定されます。

mimetypes.knownfiles

共通にインストールされた型マップファイル名のリスト。これらのファイルは、普通 mime.types という名前であり、パッケージごとに異なる場所にインストールされます。

mimetypes.suffix_map

サフィックスをサフィックスにマップする辞書。これは、符号化方式と型が同一拡張子で示される符号化ファイルが認識できるように使用されます。例えば、 .tgz 拡張子は、符号化と型が別個に認識できるように .tar.gz にマップされます。

mimetypes.encodings_map

ファイル名拡張子を符号化方式型にマッピングする辞書。

mimetypes.types_map

ファイル名拡張子を MIME 型にマップする辞書。

mimetypes.common_types

ファイル名拡張子を非標準ではあるが、一般に使われている MIME 型にマップする辞書。

モジュールの使用例:

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

Mime 型オブジェクト

MimeTypes クラスは一つ以上の MIME 型データベースが欲しいアプリケーションにとって有用でしょう。これは mimetypes モジュールのそれと似たインターフェースを提供します。

class mimetypes.MimeTypes(filenames=(), strict=True)

このクラスは、MIME 型データベースを表現します。デフォルトでは、このモジュールの他のものと同じデータベースへのアクセスを提供します。初期データベースは、このモジュールによって提供されるもののコピーで、追加の mime.types 形式のファイルを、 read() あるいは readfp() メソッドを使って、データベースにロードすることで拡張されます。マッピング辞書も、もしデフォルトのデータが望むものでなければ、追加のデータをロードする前にクリアされます。

省略可能な filenames パラメータは、追加のファイルを、デフォルトデータベースの"トップに"ロードさせるのに使うことができます。

suffix_map

サフィックスをサフィックスにマップする辞書。これは、符号化方式と型が同一拡張子で示されるような符号化ファイルが認識できるように使用されます。例えば、 .tgz 拡張子は、符号化方式と型が別個に認識できるように .tar.gz に対応づけられます。これは、最初はモジュールで定義されたグローバルな suffix_map のコピーです。

encodings_map

ファイル名拡張子を符号化型にマッピングする辞書。これは、最初はモジュールで定義されたグローバルな encodings_map のコピーです。

types_map

ファイル名拡張子を MIME 型にマッピングする 2 種類の辞書のタプル; 最初の辞書は非標準型、二つ目は標準型の辞書です。初期状態ではそれぞれ common_types と types_map です。

types_map_inv

MIME 型をファイル名拡張子のリストにマッピングする 2 種類の辞書のタプル; 最初の辞書は非標準型、二つ目は標準型の辞書です。初期状態ではそれぞれ common_types と types_map です。

guess_extension(type, strict=True)

guess_extension() 関数と同様ですが、オブジェクトに保存されたテーブルを使用します。

guess_type(url, strict=True)

guess_type() 関数と同様ですが、オブジェクトに保存されたテーブルを使用します。

guess_all_extensions(type, strict=True)

guess_all_extensions() と同様ですが、オブジェクトに保存されたテーブルを参照します。

read(filename, strict=True)

MIME 情報を、 filename という名のファイルからロードします。これはファイルを解析するのに readfp() を使用します。

strict が True の時 (デフォルト) は、そのマッピングは標準 MIME 型のリストに、そうでなければ、非標準 MIME 型のリストに追加されます。

readfp(fp, strict=True)

MIME 型情報を、オープンしたファイル fp からロードします。ファイルは、標準の mime.types ファイルの形式でなければなりません。

strict が True の時 (デフォルト) は、そのマッピングは標準 MIME 型のリストに、そうでなければ、非標準 MIME 型のリストに追加されます。

read_windows_registry(strict=True)

MIME type 情報を Windows のレジストリから読み込みます。

利用可能な環境: Windows 。

strict が True の時 (デフォルト) は、そのマッピングは標準 MIME 型のリストに、そうでなければ、非標準 MIME 型のリストに追加されます。

Added in version 3.2.

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

ソースコード: Lib/base64.py [https://github.com/python/cpython/tree/3.12/Lib/base64.py]

このモジュールは、バイナリデータを印刷可能なASCII文字列にエンコードして、また逆にデコードするための関数を提供しています。RFC 4648 [https://datatracker.ietf.org/doc/html/rfc4648.html] に定義されている Base16、Base32、 Base64 に加えて事実上の標準となっている Ascii85 と Base 85 をサポートしています。

RFC 4648 [https://datatracker.ietf.org/doc/html/rfc4648.html] エンコーディングは、email で安全に送信したり、 URL の一部として使ったり、あるいは HTTP POST リクエストの一部に含めるために用いるのに適しています。このエンコーディングで使われているアルゴリズムは uuencode プログラムで用いられているものとは同じではありません。

このモジュールは、2つのインターフェースを提供します。このモダンなインターフェースは、bytes-like object を ASCII bytes にエンコードし、bytes-like object か ASCII 文字列を、bytes にデコードすることができます。RFC 4648 [https://datatracker.ietf.org/doc/html/rfc4648.html] に定義されている base-64 アルファベット (一般の、URL あるいはファイルシステムセーフなもの) の両方が使用できます。

従来のインターフェースは文字列からのデコードができませんが、file object との間のエンコードとデコードが可能な関数を提供します。これは標準の base64 アルファベットのみをサポートし、RFC 2045 [https://datatracker.ietf.org/doc/html/rfc2045.html] の規定にあるように、76文字ごとに改行されます。RFC 2045 [https://datatracker.ietf.org/doc/html/rfc2045.html] のサポートのためには、代わりに email パッケージを参照する必要があるかもしれません。

バージョン 3.3 で変更: モダンなインターフェイスのデコード関数が ASCII のみの Unicode 文字列を受け付けるようになりました。

バージョン 3.4 で変更: このモジュールのすべてのエンコード・デコード関数が任意の bytes-like オブジェクト を受け取るようになりました。Ascii85/Base85 のサポートが追加されました。

モダンなインターフェイスは以下のものを提供します:

base64.b64encode(s, altchars=None)

Base64 を使って bytes-like object の s をエンコードし、エンコードされた bytes を返します。

オプション引数 altchars は長さ 2 の bytes-like object で 、+ と / の代わりに使われる代替アルファベットを指定します。これにより、アプリケーションはたとえば URL やファイルシステムの影響を受けない Base64 文字列を生成できます。デフォルトは None で、標準の Base64 アルファベットが使われます。

May assert or raise a ValueError if the length of altchars is not 2. Raises a TypeError if altchars is not a bytes-like object.

base64.b64decode(s, altchars=None, validate=False)

Base64 エンコードされた bytes-like object または ASCII 文字列 s をデコードし、デコードされた bytes を返します。

オプション引数の altchars は長さ 2 の bytes-like object または ASCII 文字列で、+ と / の代わりに使われる代替アルファベットを指定します。

s が正しくパディングされていない場合は binascii.Error 例外を発生させます。

validate が False (デフォルト) の場合、標準の base64 アルファベットでも代替文字でもない文字はパディングチェックの前に無視されます。 validate が True の場合、入力に base64 アルファベット以外の文字があると binascii.Error を発生させます。

For more information about the strict base64 check, see binascii.a2b_base64()

May assert or raise a ValueError if the length of altchars is not 2.

base64.standard_b64encode(s)

標準の base64 アルファベットを使用して bytes-like object の s をエンコードし、エンコードされた bytes を返します。

base64.standard_b64decode(s)

標準の base64 アルファベットを使用した bytes-like object または ASCII 文字列 s をデコードし、デコードされた bytes を返します。

base64.urlsafe_b64encode(s)

bytes-like object s を URLとファイルシステムセーフなアルファベットを利用してエンコードし、エンコードされた bytes を返します。標準 base64 アルファベットに比べて、+ の替わりに - を、/ の替わりに _ を利用します。結果は = を含みます。

base64.urlsafe_b64decode(s)

bytes-like object または ASCII 文字列 s を URLとファイルシステムセーフなアルファベットを利用してデコードし、デコードされた bytes を返します。標準 base64 アルファベットに比べて、+ の替わりに - を、/ の替わりに _ を置換します。

base64.b32encode(s)

Base32 を使って bytes-like object の s をエンコードし、エンコードされた bytes を返します。

base64.b32decode(s, casefold=False, map01=None)

Base32 エンコードされた bytes-like object または ASCII 文字列 s をデコードし、デコードされた bytes を返します。

オプション引数 casefold は小文字のアルファベットを受けつけるかどうかを指定します。セキュリティ上の理由により、デフォルトではこれは False になっています。

RFC 4648 [https://datatracker.ietf.org/doc/html/rfc4648.html] は付加的なマッピングとして、数字の 0 (零) をアルファベットの O (オー) に、数字の 1 (壱) をアルファベットの I (アイ) または L (エル) に対応させることを許しています。オプション引数は map01 は、 None でないときは、数字の 1 をどの文字に対応づけるかを指定します (map01 が None でないとき、数字の 0 はつねにアルファベットの O (オー) に対応づけられます)。セキュリティ上の理由により、これはデフォルトでは None になっているため、 0 および 1 は入力として許可されていません。

s が正しくパディングされていない場合や、入力にアルファベットでない文字が含まれていた場合に、 binascii.Error 例外を発生させます。

base64.b32hexencode(s)

Similar to b32encode() but uses the Extended Hex Alphabet, as defined in RFC 4648 [https://datatracker.ietf.org/doc/html/rfc4648.html].

Added in version 3.10.

base64.b32hexdecode(s, casefold=False)

Similar to b32decode() but uses the Extended Hex Alphabet, as defined in RFC 4648 [https://datatracker.ietf.org/doc/html/rfc4648.html].

This version does not allow the digit 0 (zero) to the letter O (oh) and digit 1 (one) to either the letter I (eye) or letter L (el) mappings, all these characters are included in the Extended Hex Alphabet and are not interchangeable.

Added in version 3.10.

base64.b16encode(s)

Base16 を使って bytes-like object の s をエンコードし、エンコードされた bytes を返します。

base64.b16decode(s, casefold=False)

Base16 エンコードされた bytes-like object または ASCII 文字列 s をデコードし、デコードされた bytes を返します。

オプション引数 casefold は小文字のアルファベットを受けつけるかどうかを指定します。セキュリティ上の理由により、デフォルトではこれは False になっています。

s が正しくパディングされていない場合や、入力にアルファベットでない文字が含まれていた場合に、 binascii.Error 例外を発生させます。

base64.a85encode(b, *, foldspaces=False, wrapcol=0, pad=False, adobe=False)

Ascii85 を使って bytes-like object の b をエンコードし、エンコードされた bytes を返します。

foldspaces を使うと、4 つの連続した空白文字(ASCII 0x20)を 'btoa' によってサポートされている短い特殊文字 'y' に置き換えます。この機能は "標準" Ascii85 ではサポートされていません。

wrapcol は何文字ごとに改行文字 (b'\n') を挿入するかを制御します。ゼロでない場合、出力の各行はこの与えられた文字数を超えません。

pad を指定すると、エンコード前に入力が 4 の倍数になるようにパディングされます。なお、 btoa の実装は常にパディングします。

adobe を指定すると、エンコードしたバイトシーケンスを <~ と ~> で囲みます。これは Adobe の実装で使われています。

Added in version 3.4.

base64.a85decode(b, *, foldspaces=False, adobe=False, ignorechars=b' \t\n\r\x0b')

Ascii85 エンコードされた bytes-like object または ASCII 文字列 b をデコードし、デコードされた bytes を返します。

foldspaces は、短い特殊文字 'y' を受け取って 4 つの連続した空白文字(ASCII 0x20)と解釈するかどうかを制御します。この機能は "標準" Ascii85 ではサポートされていません。

adobe で、入力シーケンスが Adobe Ascii85 (つまり <~ と ~> で囲まれている)かどうかを伝えます。

ignorechars には、入力に含まれていれば無視する文字で構成された bytes-like object または ASCII 文字列を指定してください。これは空白文字だけで構成されているべきです。デフォルトは ASCII における空白文字全てです。

Added in version 3.4.

base64.b85encode(b, pad=False)

base85 (これは例えば git スタイルのバイナリ diff で用いられています) を使って bytes-like object の b をエンコードし、エンコードされた bytes を返します。

pad が真ならば、エンコードに先立って、バイト数が 4 の倍数となるように入力が b'\0' でパディングされます。

Added in version 3.4.

base64.b85decode(b)

base85でエンコードされた bytes-like object または ASCII 文字列の b をデコードし、デコードされた bytes を返します。パディングは、もしあれば、暗黙に削除されます。

Added in version 3.4.

レガシーなインターフェイスは以下のものを提供します:

base64.decode(input, output)

input ファイルの中身をデコードし、結果のバイナリデータを output ファイルに出力します。 input 、 output ともに file objects でなければなりません。 input は input.readline() が空バイト列を返すまで読まれます。

base64.decodebytes(s)

bytes-like object s をデコードし、デコードされた bytes を返します。 s には一行以上の base64 形式でエンコードされたデータが含まれている必要があります。

Added in version 3.1.

base64.encode(input, output)

バイナリの input ファイルの中身を base64 形式でエンコードした結果を output ファイルに出力します。 input 、 output ともに file objects でなければなりません。 input は input.read() が空バイト列を返すまで読まれます。 encode() は76バイトの出力ごとに改行文字(b'\n')を挿入し、RFC 2045 [https://datatracker.ietf.org/doc/html/rfc2045.html] (MIME) の規定にあるように常に出力が新しい行で終わることを保証します。

base64.encodebytes(s)

bytes-like object s (任意のバイナリデータを含むことができます) を、RFC 2045 [https://datatracker.ietf.org/doc/html/rfc2045.html] (MIME) に規定されるように末尾に新しい行のある、76バイトの出力ごとに新しい行 (b'\n') が挿入された、base64 形式でエンコードしたデータを含む bytes を返します。

Added in version 3.1.

モジュールの使用例:

>>> import base64
>>> encoded = base64.b64encode(b'data to be encoded')
>>> encoded
b'ZGF0YSB0byBiZSBlbmNvZGVk'
>>> data = base64.b64decode(encoded)
>>> data
b'data to be encoded'

セキュリティで考慮すべき点

A new security considerations section was added to RFC 4648 [https://datatracker.ietf.org/doc/html/rfc4648.html] (section 12); it's recommended to review the security section for any code deployed to production.

参考

モジュール binascii

ASCII からバイナリへ、バイナリから ASCII への変換をサポートするモジュール。

RFC 1521 [https://datatracker.ietf.org/doc/html/rfc1521.html] - MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies

Section 5.2, "Base64 Content-Transfer-Encoding," provides the definition of the base64 encoding.

binascii --- Convert between binary and ASCII

The 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 uu or base64 instead. The binascii module contains low-level functions written in C for greater speed that are used by the higher-level modules.

注釈

a2b_* 関数は ASCII 文字だけを含むユニコード文字列を受け取ります。他の関数は (bytes や bytearray またはバッファープロトコルをサポートするその他のオブジェクトのような) bytes-like オブジェクト だけを受け取ります。

バージョン 3.3 で変更: a2b_* 関数は ASCII のみのユニコード文字列を受け取るようになりました。

binascii モジュールでは以下の関数を定義します:

binascii.a2b_uu(string)

uuencode された 1 行のデータをバイナリに変換し、変換後のバイナリデータを返します。最後の行を除いて、通常 1 行には (バイナリデータで) 45 バイトが含まれます。入力データの先頭には空白文字が連続していてもかまいません。

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 '`' instead of spaces.

バージョン 3.7 で変更: backtick パラメータを追加しました.

binascii.a2b_base64(string, /, *, strict_mode=False)

base64 でエンコードされたデータのブロックをバイナリに変換し、変換後のバイナリデータを返します。一度に 1 行以上のデータを与えてもかまいません。

If strict_mode is true, only valid base64 data will be converted. Invalid base64 data will raise binascii.Error.

Valid base64:

Conforms to RFC 3548 [https://datatracker.ietf.org/doc/html/rfc3548.html].

Contains only characters from the base64 alphabet.

Contains no excess data after padding (including excess padding, newlines, etc.).

Does not start with a padding.

バージョン 3.11 で変更: Added the strict_mode parameter.

binascii.b2a_base64(data, *, newline=True)

バイナリデータを base64 でエンコードされた 1 行の ASCII 文字列に変換します。戻り値は変換後の 1 行の文字列で、newline が真の場合改行文字を含みます。この関数の出力は RFC 3548 [https://datatracker.ietf.org/doc/html/rfc3548.html] を遵守します。

バージョン 3.6 で変更: パラメータに newline を追加しました。

binascii.a2b_qp(data, header=False)

quoted-printable 形式のデータをバイナリに変換し、バイナリデータを返します。一度に 1 行以上のデータを渡すことができます。オプション引数 header が与えられており、かつその値が真であれば、アンダースコアは空白文字にデコードされます。

binascii.b2a_qp(data, quotetabs=False, istext=True, header=False)

バイナリデータを quoted-printable 形式でエンコードして 1 行から複数行の ASCII 文字列に変換します。変換後の文字列を返します。オプション引数 quptetabs が存在し、かつその値が真であれば、全てのタブおよび空白文字もエンコードされます。オプション引数 istext が存在し、かつその値が真であれば、改行はエンコードされませんが、行末の空白文字はエンコードされます。オプション引数 header が存在し、かつその値が真である場合、空白文字は RFC 1522 [https://datatracker.ietf.org/doc/html/rfc1522.html] にしたがってアンダースコアにエンコードされます。オプション引数 header が存在し、かつその値が偽である場合、改行文字も同様にエンコードされます。そうでない場合、復帰 (linefeed) 文字の変換によってバイナリデータストリームが破損してしまうかもしれません。

binascii.crc_hqx(data, value)

value を CRC の初期値として data の 16 ビット CRC 値を計算し、その結果を返します。この関数は、よく 0x1021 と表現される CRC-CCITT 多項式 x¹⁶ + x¹² + x⁵ + 1 を使います。この CRC は binhex4 形式で使われています。

binascii.crc32(data[, value])

符号無し 32 ビットチェックサムである CRC-32 を data に対して計算します。 crc の初期値は value です。デフォルトの CRC の初期値はゼロです。このアルゴリズムは ZIP ファイルのチェックサムと同じです。このアルゴリズムはチェックサムアルゴリズムとして設計されたもので、一般的なハッシュアルゴリズムには向きません。以下のようにして使います:

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

バージョン 3.0 で変更: The result is always unsigned.

binascii.b2a_hex(data[, sep[, bytes_per_sep=1]])

binascii.hexlify(data[, sep[, bytes_per_sep=1]])

バイナリ data の16進表現を返します。data の各バイトは、対応する2桁の16進表現に変換されます。したがって、返されるバイトオブジェクトは data の2倍の長さになります。

Similar functionality (but returning a text string) is also conveniently accessible using the 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.

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

バージョン 3.8 で変更: 引数 sep と bytes_per_sep が追加されました.

binascii.a2b_hex(hexstr)

binascii.unhexlify(hexstr)

16進数表記の文字列 hexstr の表すバイナリデータを返します。この関数は b2a_hex() の逆です。 hexstr は 16進数字 (大文字でも小文字でも構いません) を偶数個含んでいなければなりません。そうでない場合、例外 Error が送出されます。

Similar functionality (accepting only text string arguments, but more liberal towards whitespace) is also accessible using the bytes.fromhex() class method.

exception binascii.Error

エラーが発生した際に送出される例外です。通常はプログラムのエラーです。

exception binascii.Incomplete

変換するデータが不完全な場合に送出される例外です。通常はプログラムのエラーではなく、多少追加読み込みを行って再度変換を試みることで対処できます。

参考

base64 モジュール

RFC 準拠の base64 形式の、底が 16、32、64、85 のエンコーディング。

Module uu

Support for UU encoding used on Unix.

quopri モジュール

MIME 電子メールメッセージで使われる quoted-printable エンコードのサポート。

quopri --- Encode and decode MIME quoted-printable data

ソースコード: Lib/quopri.py [https://github.com/python/cpython/tree/3.12/Lib/quopri.py]

このモジュールは RFC 1521 [https://datatracker.ietf.org/doc/html/rfc1521.html]: "MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies" で定義されている quoted-printable による伝送のエンコードおよびデコードを行います。 quoted-printable エンコーディングは比較的印字不可能な文字の少ないデータのために設計されています; 画像ファイルを送るときのように印字不可能な文字がたくさんある場合には、 base64 モジュールで利用できる base64 エンコーディングのほうがよりコンパクトになります。

quopri.decode(input, output, header=False)

ファイル input の内容をデコードして、デコードされたバイナリデータをファイル output に書き出します。 input および output は バイナリファイルオブジェクト でなければなりません。オプション引数 header が存在し、かつその値が真である場合、アンダースコアは空白文字にデコードされます。これは RFC 1522 [https://datatracker.ietf.org/doc/html/rfc1522.html]: "MIME (Multipurpose Internet Mail Extensions) Part Two: Message Header Extensions for Non-ASCII Text" で記述されているところの "Q"-エンコードされたヘッダをデコードするのに使われます。

quopri.encode(input, output, quotetabs, header=False)

ファイル input の内容をエンコードして、その結果の quoted-printable データをファイル output に書き出します。 input および output は バイナリファイルオブジェクト でなければなりません。 quotetabs は、内容に含まれている空白とタブ文字をエンコードするかどうかを制御する必須のフラグで、真のときは空白文字をエンコードし、偽のときはエンコードしないままにしておきます。 RFC 1521 [https://datatracker.ietf.org/doc/html/rfc1521.html] に従って、行末にある空白とタブ文字は常にエンコードされることに注意してください。 header は、空白を RFC 1522 [https://datatracker.ietf.org/doc/html/rfc1522.html] に従ってアンダースコアにエンコードするかどうかを制御するフラグです。

quopri.decodestring(s, header=False)

decode() に似ていますが、ソース bytes を受け取り、対応するデコードされた bytes を返します。

quopri.encodestring(s, quotetabs=False, header=False)

encode() に似ていますが、ソース bytes を受け取り、対応するエンコードされた bytes を返します。デフォルトでは、 encode() 関数の quotetabs パラメータに False を渡します。

参考

base64 モジュール

MIME base64 形式データのエンコードおよびデコード

構造化マークアップツール

Python は様々な構造化データマークアップ形式を扱うための、様々なモジュールをサポートしています。これらは標準化一般マークアップ言語 (SGML) およびハイパーテキストマークアップ言語 (HTML)、そして可拡張性マークアップ言語 (XML) を扱うためのいくつかのインターフェースからなります。

html --- HyperText Markup Language support

html.parser --- Simple HTML and XHTML parser

HTML パーサーアプリケーションの例

HTMLParser メソッド

使用例

html.entities --- Definitions of HTML general entities

XMLを扱うモジュール群

XML の脆弱性

The defusedxml Package

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

チュートリアル

XML 木構造と要素

XML の解析

非ブロックパースのためのプル API

関心ある要素の検索

XML ファイルの編集

XML 文書の構築

名前空間のある XML の解析

XPath サポート

使用例

サポートされている XPath 構文

リファレンス

関数

XInclude サポート

使用例

リファレンス

関数

Element オブジェクト

ElementTree オブジェクト

QName オブジェクト

TreeBuilder オブジェクト

XMLParser オブジェクト

XMLPullParser オブジェクト

例外

xml.dom --- The Document Object Model API

モジュールコンテンツ

DOM 内のオブジェクト

DOMImplementation オブジェクト

Node オブジェクト

NodeList オブジェクト

DocumentType オブジェクト

Document オブジェクト

Element オブジェクト

Attr オブジェクト

NamedNodeMap Objects

Comment オブジェクト

Text オブジェクトおよび CDATASection オブジェクト

ProcessingInstruction オブジェクト

例外

適合性

型の対応付け

アクセサメソッド

xml.dom.minidom --- Minimal DOM implementation

DOM オブジェクト

DOM の例

minidom と DOM 標準

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

DOMEventStream オブジェクト

xml.sax --- Support for SAX2 parsers

SAXException オブジェクト

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

ContentHandler オブジェクト

DTDHandler オブジェクト

EntityResolver オブジェクト

ErrorHandler オブジェクト

LexicalHandler Objects

xml.sax.saxutils --- SAX Utilities

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

XMLReader オブジェクト

IncrementalParser オブジェクト

Locator オブジェクト

InputSource オブジェクト

Attributes インターフェース

AttributesNS インターフェース

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

XMLParser オブジェクト

ExpatError 例外

使用例

内容モデルの記述

Expat エラー定数

html --- HyperText Markup Language support

ソースコード: Lib/html/__init__.py [https://github.com/python/cpython/tree/3.12/Lib/html/__init__.py]

このモジュールは HTML を操作するユーティリティを定義しています。

html.escape(s, quote=True)

文字列 s 内の &、<、および > を HTML セーフなシーケンスに変換します。これらの文字を含む HTML を表示する必要がある場合に使用します。オプションフラグ quote が真の場合、文字 (") および (') も変換します。これは例えば <a href="..."> など、引用符で括られている HTML 属性値を包含する時に役立ちます。

Added in version 3.2.

html.unescape(s)

文字列 s 中の名前や数字による参照 (例えば &gt;, &#62;, &#x3e;) を全て対応するユニコード文字に変換します。この関数は、 HTML 5 標準規格で定められた有効な文字参照および無効な文字参照、 list of HTML 5 named character references を対象とします。

Added in version 3.4.

html パッケージのサブモジュールは以下のとおりです:

html.parser -- 許容性のあるモードを持つ HTML/XHTML パーサー

html.entities -- HTML 実体の定義

html.parser --- Simple HTML and XHTML parser

ソースコード: Lib/html/parser.py [https://github.com/python/cpython/tree/3.12/Lib/html/parser.py]

このモジュールでは HTMLParser クラスを定義します。このクラスは HTML (ハイパーテキスト記述言語、HyperText Mark-up Language) および XHTML で書式化されているテキストファイルを解釈するための基礎となります。

class html.parser.HTMLParser(*, convert_charrefs=True)

不正なマークアップをパースできるパーサーインスタンスを作成します。

convert_charrefs が (デフォルトの) True である場合、全ての文字参照 (script/style 要素にあるものは除く) は自動的に対応する Unicode 文字に変換されます。

HTMLParser インスタンスは、HTML データが入力されると、開始タグ、終了タグ、およびその他の要素が見つかる度にハンドラーメソッドを呼び出します。各メソッドの挙動を実装するには HTMLParser サブクラスを使ってそれぞれを上書きして行います。

このパーサーは終了タグが開始タグと一致しているか調べたり、外側のタグ要素が閉じるときに内側で明示的に閉じられていないタグ要素のタグ終了ハンドラーを呼び出したりはしません。

バージョン 3.4 で変更: キーワード引数 convert_charrefs を追加。

バージョン 3.5 で変更: convert_charrefs のデフォルト値は True になりました。

HTML パーサーアプリケーションの例

基礎的な例として、HTMLParser クラスを使い、発見した開始タグ、終了タグ、およびデータを出力する、シンプルな HTML パーサーを以下に示します:

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>')

出力は以下のようになります:

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

HTMLParser メソッド

HTMLParser インスタンスは以下のメソッドを提供します:

HTMLParser.feed(data)

パーサーにテキストを入力します。入力が完全なタグ要素で構成されている場合に限り処理が行われます; 不完全なデータであった場合、新たにデータが入力されるか、close() が呼び出されるまでバッファーされます。 data は str でなければなりません。

HTMLParser.close()

全てのバッファーされているデータについて、その後にファイル終端マークが続いているとみなして強制的に処理を行います。このメソッドは入力データの終端で行う追加処理を定義するために、派生クラスで再定義することができます。しかし、再定義されたバージョンでは、常に HTMLParser 基底クラスのメソッド close() を呼び出さなくてはなりません。

HTMLParser.reset()

インスタンスをリセットします。未処理のデータはすべて失われます。インスタンス化の際に暗黙的に呼び出されます。

HTMLParser.getpos()

現在の行番号およびオフセット値を返します。

HTMLParser.get_starttag_text()

最も最近開かれた開始タグのテキスト部分を返します。このテキストは必ずしも元データを構造化する上で必須ではありませんが、 "広く知られている (as deployed)" HTML を扱ったり、入力を最小限の変更で再生成 (属性間の空白をそのままにする、など) したりする場合に便利なことがあります。

以下のメソッドはデータまたはマークアップ要素が見つかる度に呼び出されます。これらはサブクラスで上書きされることを想定されています。基底クラスの実装は (handle_startendtag() を除き) 何もしません:

HTMLParser.handle_starttag(tag, attrs)

このメソッドは要素の開始タグを扱うために呼び出されます (例: <div id="main">)。

引数 tag はタグの名前で、小文字に変換されます。引数 attrs は (name, value) のペアからなるリストで、タグの <> 括弧内にある属性が収められています。name は小文字に変換され、value 内の引用符は取り除かれ、文字参照と実態参照は置き換えられます。

例えば、タグ <A HREF="https://www.cwi.nl/"> を処理する場合、このメソッドは handle_starttag('a', [('href', 'https://www.cwi.nl/')]) として呼び出されます。

html.entities からのすべての実態参照は、属性値に置き換えられます。

HTMLParser.handle_endtag(tag)

このメソッドは要素の終了タグを扱うために呼び出されます (例: </div>)。

引数 tag はタグの名前で、小文字に変換されます。

HTMLParser.handle_startendtag(tag, attrs)

handle_starttag() と似ていますが、パーサーが XHTML 形式の空タグ (<img ... />) を見つける度に呼び出されます。この特定の字句情報が必要な場合にこのメソッドをサブクラスで上書きすることができます; 既定の実装では、単に handle_starttag() および handle_endtag() を呼び出します。

HTMLParser.handle_data(data)

このメソッドは任意のデータを処理するために呼び出されます (例: テキストノードおよび <script>...</script> aや <style>...</style> の内容)。

HTMLParser.handle_entityref(name)

このメソッドは &name; 形式の名前指定文字参照 (例: &gt;) を処理するために呼び出されます。name は一般実体参照になります (例: 'gt')。このメソッドは convert_charrefs が True なら呼び出されることはありません。

HTMLParser.handle_charref(name)

This method is called to process decimal and hexadecimal numeric character references of the form &#NNN; and &#xNNN;. For example, the decimal equivalent for &gt; is &#62;, whereas the hexadecimal is &#x3E;; in this case the method will receive '62' or 'x3E'. This method is never called if convert_charrefs is True.

HTMLParser.handle_comment(data)

このメソッドはコメントが見つかった場合に呼び出されます (例: <!--comment-->)。

例えば、コメント <!-- comment --> があると。このメソッドを引数 ' comment ' で呼び出されます。

Internet Explorer 独自拡張の条件付きコメント (condcoms) はこのメソッドに送ることができます。<!--[if IE 9]>IE9-specific content<![endif]--> の場合、このメソッドは '[if IE 9]>IE9-specific content<![endif]' を受け取ります。

HTMLParser.handle_decl(decl)

このメソッドは HTML doctype 宣言を扱うために呼び出されます (例: <!DOCTYPE html>)。

引数 decl は <!...> マークアップ内の宣言の内容全体になります (例: 'DOCTYPE html')。

HTMLParser.handle_pi(data)

処理指令が見つかった場合に呼び出されます。data には、処理指令全体が含まれ、例えば <?proc color='red'> という処理指令の場合、handle_pi("proc color='red'") のように呼び出されます。このメソッドは派生クラスで上書きするためのメソッドです; 基底クラスの実装では何も行いません。

注釈

HTMLParser クラスでは、処理指令に SGML の構文を使用します。末尾に '?' がある XHTML の処理指令では、 '?' が data に含まれることになります。

HTMLParser.unknown_decl(data)

このメソッドはパーサーが未知の宣言を読み込んだ時に呼び出されます。

パラメータ data は <![...]> マークアップ内の宣言の内容全体になります。これは派生クラスで上書きする時に役立つことがあります。基底クラスの実装では何もしません。

使用例

以下のクラスは、より多くの例を示すのに用いられるパーサーの実装です:

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()

doctype をパースします:

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

要素のタイトルと一部属性をパースします:

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

それ以上のパースを行わずに、script と style 要素の内容をそのまま返します:

>>> parser.feed('<style type="text/css">#python { color: green }</style>')
Start tag: style
     attr: ('type', 'text/css')
Data     : #python { color: green }
End tag  : style

>>> parser.feed('<script type="text/javascript">'
...             'alert("<strong>hello!</strong>");</script>')
Start tag: script
     attr: ('type', 'text/javascript')
Data     : alert("<strong>hello!</strong>");
End tag  : script

コメントをパースします:

>>> parser.feed('<!-- a comment -->'
...             '<!--[if IE 9]>IE-specific content<![endif]-->')
Comment  :  a comment
Comment  : [if IE 9]>IE-specific content<![endif]

名前指定および数値文字参照をパースし、正しい文字に変換します (注: これら 3 個の参照はすべて '>' と等価です):

>>> parser.feed('&gt;&#62;&#x3E;')
Named ent: >
Num ent  : >
Num ent  : >

不完全なチャンクを feed() に入力しても、(convert_charrefs が True に設定されていない限り) handle_data() は 1 回以上呼び出される場合があります:

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

不正な HTML (例えば属性が引用符で括られていない) のパースも動作します:

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

html.entities --- Definitions of HTML general entities

ソースコード: Lib/html/entities.py [https://github.com/python/cpython/tree/3.12/Lib/html/entities.py]

このモジュールは 4 つの辞書、html5、name2codepoint、codepoint2name、および entitydefs を定義しています。

html.entities.html5

HTML5 名前付き文字参照 [1] と Unicode 文字とを対応付ける辞書です (例: html5['gt;'] == '>')。末尾のセミコロンは名前に含まれますが (例: 'gt;')、一部の名前はセミコロンなしでも標準で受け付けます。この場合、';' ありの名前と ';' なしの名前が両方存在します。 html.unescape() も参照してください。

Added in version 3.3.

html.entities.entitydefs

各 XHTML 1.0 実体定義と ISO Latin-1 における置換テキストとを対応付ける辞書です。

html.entities.name2codepoint

A dictionary that maps HTML4 entity names to the Unicode code points.

html.entities.codepoint2name

A dictionary that maps Unicode code points to HTML4 entity names.

脚注

[1]

See https://html.spec.whatwg.org/multipage/named-characters.html#named-character-references

XMLを扱うモジュール群

ソースコード: Lib/xml/ [https://github.com/python/cpython/tree/3.12/Lib/xml/]

PythonのXMLを扱うインターフェースは xml パッケージにまとめられています。

警告

XML モジュール群は不正なデータや悪意を持って作成されたデータに対して安全ではありません。信頼できないデータをパースする必要がある場合は XML の脆弱性 と The defusedxml Package を参照してください。

注意すべき重要な点として、 xml パッケージのモジュールは SAX に対応した XML パーザが少なくとも一つ利用可能でなければなりません。Expat パーザが Python に取り込まれているので、 xml.parsers.expat モジュールは常に利用できます。

xml.dom および xml.sax パッケージのドキュメントは Python による DOM および SAX インターフェースへのバインディングに関する定義です。

XML に関連するサブモジュール:

xml.etree.ElementTree: ElementTree API、シンプルで軽量な XML プロセッサ

xml.dom: DOM API の定義

xml.dom.minidom: 最小限の DOM の実装

xml.dom.pulldom: 部分的な DOM ツリー構築のサポート

xml.sax: SAX2 基底クラスと便利関数群

xml.parsers.expat: Expat parser バインディング

XML の脆弱性

XML 処理モジュールは悪意を持って生成されたデータに対して安全ではありません。攻撃者は XML の機能を悪用して DoS攻撃、ローカルファイルへのアクセス、他マシンへのネットワーク接続、ファイアーウォールの迂回などを行うことが出来ます。

以下の表は既知の攻撃と各モジュールがそれに対し脆弱かどうかの概要を示しています。

種類

sax

etree

minidom

pulldom

xmlrpc

billion laughs

Vulnerable (1)

Vulnerable (1)

Vulnerable (1)

Vulnerable (1)

Vulnerable (1)

quadratic blowup

Vulnerable (1)

Vulnerable (1)

Vulnerable (1)

Vulnerable (1)

Vulnerable (1)

external entity expansion

Safe (5)

Safe (2)

Safe (3)

Safe (5)

安全 (4)

DTD [https://en.wikipedia.org/wiki/Document_type_definition] retrieval

Safe (5)

安全

安全

Safe (5)

安全

decompression bomb

安全

安全

安全

安全

脆弱

large tokens

Vulnerable (6)

Vulnerable (6)

Vulnerable (6)

Vulnerable (6)

Vulnerable (6)

Expat 2.4.1 and newer is not vulnerable to the "billion laughs" and "quadratic blowup" vulnerabilities. Items still listed as vulnerable due to potential reliance on system-provided libraries. Check pyexpat.EXPAT_VERSION.

xml.etree.ElementTree doesn't expand external entities and raises a ParseError when an entity occurs.

xml.dom.minidom は外部エンティティを展開せず、展開前のエンティティをそのまま返します。

xmlrpc.client doesn't expand external entities and omits them.

Python 3.7.1 からは、一般の外部エンティティはデフォルトで処理されなくなりました。

Expat 2.6.0 and newer is not vulnerable to denial of service through quadratic runtime caused by parsing large tokens. Items still listed as vulnerable due to potential reliance on system-provided libraries. Check pyexpat.EXPAT_VERSION.

billion laughs / exponential entity expansion

Billion Laughs [https://en.wikipedia.org/wiki/Billion_laughs] 攻撃 -- または指数関数的エンティティ展開 (exponential entity expansion) -- は複数階層の入れ子になったエンティティを使用します。各エンティティは別のエンティティを複数回参照し、最終的なエンティティの定義は短い文字列です。指数関数的に展開されることで数 GB のテキストができ、多くのメモリと CPU 時間を消費します。

quadratic blowup entity expansion

二次爆発攻撃 (quadratic blowup attack) はエンティティ展開を悪用する点で Billion Laughs [https://en.wikipedia.org/wiki/Billion_laughs] 攻撃に似ています。入れ子になったエンティティの代わりに、この攻撃は数千字の大きなエンティティを何度も繰り返します。この攻撃は指数関数的なものほど効率的ではありませんが、パーザの深い入れ子になったエンティティを禁止する対抗手段をすり抜けます。

external entity expansion

(外部エンティティ展開) エンティティの定義はただのテキスト置換以上のことが出来ます。外部のリソースやローカルファイルを参照することも出来ます。 XML パーザはリソースにアクセスしてその内容を XML 文書に埋め込みます。

DTD [https://en.wikipedia.org/wiki/Document_type_definition] retrieval

Python の xml.dom.pulldom のような XML ライブラリは DTD をリモートやローカルの場所から読み込みます。この機能には外部エンティティ展開の問題と同じことが予想されます。

decompression bomb

解凍爆弾 (あるいは ZIP 爆弾 [https://ja.wikipedia.org/wiki/%E9%AB%98%E5%9C%A7%E7%B8%AE%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E7%88%86%E5%BC%BE]) は、gzip 圧縮 HTTP ストリームや LZMA 圧縮ファイルなどの圧縮された XML ストリームをパースできる全ての XML ライブラリに対し行われます。攻撃者は送信データ量を1/3以下に減らすことができます。

large tokens

Expat needs to re-parse unfinished tokens; without the protection introduced in Expat 2.6.0, this can lead to quadratic runtime that can be used to cause denial of service in the application parsing XML. The issue is known as CVE-2023-52425 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-52425].

The documentation for defusedxml [https://pypi.org/project/defusedxml/] on PyPI has further information about all known attack vectors with examples and references.

The defusedxml Package

defusedxml [https://pypi.org/project/defusedxml/] is a pure Python package with modified subclasses of all stdlib XML parsers that prevent any potentially malicious operation. Use of this package is recommended for any server code that parses untrusted XML data. The package also ships with example exploits and extended documentation on more XML exploits such as XPath injection.

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

Source code: Lib/xml/etree/ElementTree.py [https://github.com/python/cpython/tree/3.12/Lib/xml/etree/ElementTree.py]

xml.etree.ElementTree モジュールは、XML データを解析および作成するシンプルかつ効率的な API を実装しています。

バージョン 3.3 で変更: このモジュールは利用出来る場合は常に高速な実装を使用します。

バージョン 3.3 で非推奨: The xml.etree.cElementTree module is deprecated.

警告

xml.etree.ElementTree モジュールは悪意を持って作成されたデータに対して安全ではありません。信頼できないデータや認証されていないデータをパースする必要がある場合は XML の脆弱性 を参照してください。

チュートリアル

これは xml.etree.ElementTree (略して ET) を使用するための短いチュートリアルで、ブロックの構築およびモジュールの基本コンセプトを紹介することを目的としています。

XML 木構造と要素

XML は本質的に階層データ形式で、木構造で表すのが最も自然な方法です。ET はこの目的のために 2 つのクラス - XML 文書全体を木で表す ElementTree および木構造内の単一ノードを表す Element - を持っています。文書全体とのやりとり (ファイルの読み書き) は通常 ElementTree レベルで行います。単一 XML 要素およびその子要素とのやりとりは Element レベルで行います。

XML の解析

We'll be using the fictive country_data.xml XML document as the sample data for this section:

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

ファイルを読み込むことでこのデータをインポートすることが出来ます:

import xml.etree.ElementTree as ET
tree = ET.parse('country_data.xml')
root = tree.getroot()

文字列から直接インポートすることも出来ます:

root = ET.fromstring(country_data_as_string)

fromstring() は XML を文字列から Element に直接パースします。Element はパースされた木のルート要素です。他のパース関数は ElementTree を作成するかもしれません。ドキュメントをきちんと確認してください。

Element として、root はタグと属性の辞書を持ちます:

>>> root.tag
'data'
>>> root.attrib
{}

さらにイテレート可能な子ノードも持ちます:

>>> for child in root:
...     print(child.tag, child.attrib)
...
country {'name': 'Liechtenstein'}
country {'name': 'Singapore'}
country {'name': 'Panama'}

子ノードは入れ子になっており、インデックスで子ノードを指定してアクセスできます:

>>> root[0][1].text
'2008'

注釈

XML 入力の全ての要素が、パース後の木に要素として含まれる訳ではありません。現在、このモジュールは入力中のいかなる XML コメント、処理命令、ドキュメントタイプ宣言も読み飛ばします。しかし、XML テキストからのパースではなく、このモジュールの API を使用して構築された木には、コメントや処理命令を含むことができ、それらは XML 出力の生成時に含まれます。ドキュメントタイプ宣言は、 XMLParser コンストラクタにカスタムの TreeBuilder インスタンスを渡すことで、アクセスすることができます。

非ブロックパースのためのプル API

このモジュールが提供するパース関数のほとんどは、結果を返す前に、ドキュメント全体を読む必要があります。 XMLParser を使用して、インクリメンタルにデータを渡すことは可能ではありますが、それはコールバック対象のメソッドを呼ぶプッシュ API であり、多くの場合、低水準すぎて不便です。ユーザーが望むのは、完全に出来上がった Element オブジェクトを便利に使いながら、操作をブロックすることなく XML のパースをインクリメンタルに行えることです。

これを行うための最も強力なツールは、 XMLPullParser です。XML データを取得するためにブロックするような読み込みは必要なく、 XMLPullParser.feed() を呼び出して、インクリメンタルにデータを読みます。パースされた XML 要素を取得するには、XMLPullParser.read_events() を呼び出します。以下に、例を示します。

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

これの分かりやすい用途は、XML データをソケットから受信したり、ストレージデバイスからインクリメンタルに読み出したりするような、非ブロック式に動作するアプリケーションです。このような場合、ブロッキング読み出しは使用できません。

XMLPullParser は柔軟性が非常に高いため、単純に使用したいユーザーにとっては不便かもしれません。アプリケーションにおいて、XML データの読み取り時にブロックすることに支障がないが、インクリメンタルにパースする能力が欲しい場合、iterparse() を参照してください。大きな XML ドキュメントを読んでいて、全てメモリ上にあるという状態にしたくない場合に有用です。

Where immediate feedback through events is wanted, calling method XMLPullParser.flush() can help reduce delay; please make sure to study the related security notes.

関心ある要素の検索

Element は、例えば、Element.iter() などの、配下 (その子ノードや孫ノードなど) の部分木全体を再帰的にイテレートするいくつかの役立つメソッドを持っています:

>>> 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'}

Element.findall() はタグで現在の要素の直接の子要素のみ検索します。 Element.find() は特定のタグで 最初の 子要素を検索し、 Element.text は要素のテキストコンテンツにアクセスします。 Element.get() は要素の属性にアクセスします:

>>> for country in root.findall('country'):
...     rank = country.find('rank').text
...     name = country.get('name')
...     print(name, rank)
...
Liechtenstein 1
Singapore 4
Panama 68

XPath を使用すると、より洗練された方法で、検索したい要素を指定することができます。

XML ファイルの編集

ElementTree は XML 文書を構築してファイルに出力する簡単な方法を提供しています。ElementTree.write() メソッドはこの目的に適います。

Element オブジェクトを作成すると、そのフィールドの直接変更 (Element.text など) や、属性の追加および変更 (Element.set() メソッド)、あるいは新しい子ノードの追加 (例えば Element.append() など) によってそれを操作できます。

例えば各 country の rank に 1 を足して、rank 要素に updated 属性を追加したい場合:

>>> 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')

XML はこのようになります:

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

Element.remove() を使って要素を削除することが出来ます。例えば rank が 50 より大きい全ての country を削除したい場合:

>>> for country in root.findall('country'):
...     # using root.findall() to avoid removal during traversal
...     rank = int(country.find('rank').text)
...     if rank > 50:
...         root.remove(country)
...
>>> tree.write('output.xml')

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 root.findall(), and only then iterates over the list of matches.

XML はこのようになります:

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

XML 文書の構築

SubElement() 関数は、与えられた要素に新しい子要素を作成する便利な手段も提供しています:

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

名前空間のある XML の解析

XML 入力が 名前空間 [https://en.wikipedia.org/wiki/XML_namespace] を持っている場合、 prefix:sometag の形式で修飾されたタグと属性が、その prefix が完全な URI で置換された {uri}sometag の形に展開されます。さらに、 デフォルトの XML 名前空間 [https://www.w3.org/TR/xml-names/#defaulting] があると、修飾されていない全てのタグにその完全 URI が前置されます。

ひとつは接頭辞 "fictional" でもうひとつがデフォルト名前空間で提供された、 2 つの名前空間を組み込んだ XML の例をここにお見せします:

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

この XML の例を、検索し、渡り歩くためのひとつの方法としては、 find() や findall() に渡す xpath で全てのタグや属性に手作業で URI を付けてまわる手があります:

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)

もっと良い方法があります。接頭辞の辞書を作り、これを検索関数で使うことです:

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)

どちらのアプローチでも同じ結果です:

John Cleese
 |--> Lancelot
 |--> Archie Leach
Eric Idle
 |--> Sir Robin
 |--> Gunther
 |--> Commander Clement

XPath サポート

このモジュールは木構造内の要素の位置決めのための XPath 式 [https://www.w3.org/TR/xpath] を限定的にサポートしています。その目指すところは短縮構文のほんの一部だけのサポートであり、XPath エンジンのフルセットは想定していません。

使用例

以下はこのモジュールの XPath 機能の一部を紹介する例です。XML の解析 節から XML 文書 countrydata を使用します:

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]")

For XML with namespaces, use the usual qualified {namespace}tag notation:

# All dublin-core "title" tags in the document
root.findall(".//{http://purl.org/dc/elements/1.1/}title")

サポートされている XPath 構文

操作

意味

tag

Selects all child elements with the given tag. For example, spam selects all child elements named spam, and spam/egg selects all grandchildren named egg in all children named spam. {namespace}* selects all tags in the given namespace, {*}spam selects tags named spam in any (or no) namespace, and {}* only selects tags that are not in a namespace.

バージョン 3.8 で変更: Support for star-wildcards was added.

*

Selects all child elements, including comments and processing instructions. For example, */egg selects all grandchildren named egg.

.

現在のノードを選択します。これはパスの先頭に置くことで相対パスであることを示すのに役立ちます。

//

現在の要素の下にある全てのレベルの全ての子要素を選択します。例えば、.//egg は木全体から egg 要素を選択します。

..

親ノードを選択します。パスが開始要素 (find が呼ばれた要素) の上の要素に進もうとした場合 None を返します。

[@attrib]

与えられた属性を持つ全ての要素を選択します。

[@attrib='value']

与えられた属性が与えられた値を持つ全ての要素を選択します。値に引用符は含められません。

[@attrib!='value']

Selects all elements for which the given attribute does not have the given value. The value cannot contain quotes.

Added in version 3.10.

[tag]

tag という名前の子要素を持つ全ての要素を選択します。直下の子要素のみサポートしています。

[.='text']

子孫のうち、与えられた text とテキスト全体が等しい全ての要素を選択します。

Added in version 3.7.

[.!='text']

Selects all elements whose complete text content, including descendants, does not equal the given text.

Added in version 3.10.

[tag='text']

子孫を含む完全なテキストコンテンツと与えられた text が一致する、 tag と名付けられた子要素を持つすべての要素を選択します。

[tag!='text']

Selects all elements that have a child named tag whose complete text content, including descendants, does not equal the given text.

Added in version 3.10.

[position]

与えられた位置にあるすべての要素を選択します。位置は整数 (先頭は 1)、式 last() (末尾)、あるいは末尾からの相対位置 (例えば last()-1) のいずれかで指定できます。

述語 (角括弧内の式) の前にはタグ名、アスタリスク、あるいはその他の述語がなければなりません。 position 述語の前にはタグ名がなければなりません。

リファレンス

関数

xml.etree.ElementTree.canonicalize(xml_data=None, *, out=None, from_file=None, **options)

C14N 2.0 [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 reduced 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 utf-8 encoding.

Typical uses:

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)

The configuration options are as follows:

with_comments: set to true to include comments (default: false)

strip_text: set to true to strip whitespace before and after text content

(default: false)

rewrite_prefixes: set to true to replace namespace prefixes by "n{number}"

(default: false)

qname_aware_tags: a set of qname aware tag names in which prefixes

should be replaced in text content (default: empty)

qname_aware_attrs: a set of qname aware attribute names in which prefixes

should be replaced in text content (default: empty)

exclude_attrs: a set of attribute names that should not be serialised

exclude_tags: a set of tag names that should not be serialised

In the option list above, "a set" refers to any collection or iterable of strings, no ordering is expected.

Added in version 3.8.

xml.etree.ElementTree.Comment(text=None)

コメント要素のファクトリです。このファクトリ関数は、標準のシリアライザでは XML コメントにシリアライズされる特別な要素を作ります。コメント文字列はバイト文字列でも Unicode 文字列でも構いません。text はそのコメント文字列を含んだ文字列です。コメントを表わす要素のインスタンスを返します。

XMLParser は、入力に含まれるコメントを読み飛ばし、コメントオブジェクトは作成しません。ElementTree は、Element メソッドの 1 つを使用して木内に挿入されたコメントノードのみを含みます。

xml.etree.ElementTree.dump(elem)

要素の木もしくは要素の構造を sys.stdout に出力します。この関数はデバッグ目的のみに使用してください。

出力される形式の正確なところは実装依存です。このバージョンでは、通常の XML ファイルとして出力されます。

elem は要素の木もしくは個別の要素です。

バージョン 3.8 で変更: The dump() function now preserves the attribute order specified by the user.

xml.etree.ElementTree.fromstring(text, parser=None)

文字列定数で与えられた XML 断片を解析します。 XML() と同じです。 text には XML データを含む文字列を指定します。 parser はオプションで、パーザのインスタンスを指定します。指定されなかった場合、標準の XMLParser パーザを使用します。 Element インスタンスを返します。

xml.etree.ElementTree.fromstringlist(sequence, parser=None)

文字列フラグメントのシーケンスから XML ドキュメントを解析します。 sequence は XML データのフラグメントを格納した、リストかその他のシーケンスです。 parser はオプションのパーザインスタンスです。パーザが指定されない場合、標準の XMLParser パーザが使用されます。 Element インスタンスを返します。

Added in version 3.2.

xml.etree.ElementTree.indent(tree, space='  ', level=0)

Appends whitespace to the subtree to indent the tree visually. This can be used to generate pretty-printed XML output. tree can be an Element or ElementTree. space is the whitespace string that will be inserted for each indentation level, two space characters by default. For indenting partial subtrees inside of an already indented tree, pass the initial indentation level as level.

Added in version 3.9.

xml.etree.ElementTree.iselement(element)

オブジェクトが正当な要素オブジェクトであるかをチェックします。 element は要素インスタンスです。引数が要素オブジェクトの場合 True を返します。

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 file object containing XML data. events is a sequence of events to report back. The supported events are the strings "start", "end", "comment", "pi", "start-ns" and "end-ns" (the "ns" events are used to get detailed namespace information). If events is omitted, only "end" events are reported. parser is an optional parser instance. If not given, the standard XMLParser parser is used. parser must be a subclass of XMLParser and can only use the default TreeBuilder as a target. Returns an iterator providing (event, elem) pairs; it has a root attribute that references the root element of the resulting XML tree once source is fully read.

iterparse() は木をインクリメンタルに構築しますが、source (または指定のファイル) でのブロッキング読みを起こします。したがって、ブロッキング読みが許可されないアプリケーションには適しません。完全に非ブロックのパースのためには、XMLPullParser を参照してください。

注釈

iterparse() は "start" イベントを発行した時に開始タグの文字 ">" が現れたことだけを保証します。そのため、属性は定義されますが、その時点ではテキストの内容も tail 属性も定義されていません。同じことは子要素にも言えて、その時点ではあるともないとも言えません。

全部揃った要素が必要ならば、"end" イベントを探してください。

バージョン 3.4 で非推奨: parser 引数。

バージョン 3.8 で変更: イベント comment, pi が追加されました。

xml.etree.ElementTree.parse(source, parser=None)

XML 断片を解析して要素の木にします。 source には XML データを含むファイル名またはファイルオブジェクトを指定します。 parser はオプションでパーザインスタンスを指定します。パーザが指定されない場合、標準の XMLParser パーザが使用されます。 ElementTree インスタンスを返します。

xml.etree.ElementTree.ProcessingInstruction(target, text=None)

PI 要素のファクトリです。このファクトリ関数は XML の処理命令としてシリアライズされた特別な要素を作成します。target は PI ターゲットを含んだ文字列です。text を指定する場合は PI コンテンツを含む文字列にします。PI を表わす要素インスタンスを返します。

Note that XMLParser skips over processing instructions in the input instead of creating PI objects for them. An ElementTree will only contain processing instruction nodes if they have been inserted into to the tree using one of the Element methods.

xml.etree.ElementTree.register_namespace(prefix, uri)

名前空間の接頭辞を登録します。レジストリはグローバルで、与えられた接頭辞か名前空間 URI のどちらかの既存のマッピングはすべて削除されます。prefix には名前空間の接頭辞を指定します。uri には名前空間の URI を指定します。この名前空間のタグや属性は、可能な限り与えられた接頭辞をつけてシリアライズされます。

Added in version 3.2.

xml.etree.ElementTree.SubElement(parent, tag, attrib={}, **extra)

子要素のファクトリです。この関数は要素インスタンスを作成し、それを既存の要素に追加します。

要素名、属性名、および属性値はバイト文字列でも Unicode 文字列でも構いません。 parent には親要素を指定します。 tag には要素名を指定します。attrib はオプションで要素の属性を含む辞書を指定します。 extra は追加の属性で、キーワード引数として与えます。要素インスタンスを返します。

xml.etree.ElementTree.tostring(element, encoding='us-ascii', method='xml', *, xml_declaration=None, default_namespace=None, short_empty_elements=True)

XML 要素を全ての子要素を含めて表現する文字列を生成します。 element は Element のインスタンスです。 encoding [1] は出力エンコーディング(デフォルトは US-ASCII)です。Unicode 文字列を生成するには、encoding="unicode" を使用してください。 method は "xml", "html", "text" のいずれか(デフォルトは "xml") です。 xml_declaration, default_namespace, short_empty_elements は、 ElementTree.write() での意味と同じ意味を持ちます。 XML データを含んだ (オプションで) エンコードされた文字列を返します。

バージョン 3.4 で変更: Added the short_empty_elements parameter.

バージョン 3.8 で変更: Added the xml_declaration and default_namespace parameters.

バージョン 3.8 で変更: The tostring() function now preserves the attribute order specified by the user.

xml.etree.ElementTree.tostringlist(element, encoding='us-ascii', method='xml', *, xml_declaration=None, default_namespace=None, short_empty_elements=True)

XML 要素を全ての子要素を含めて表現する文字列を生成します。 element は Element のインスタンスです。 encoding [1] は出力エンコーディング(デフォルトは US-ASCII)です。Unicode 文字列を生成するには、encoding="unicode" を使用してください。 method は "xml", "html", "text" のいずれか(デフォルトは "xml") です。 xml_declaration*, default_namespace, short_empty_elements は、 ElementTree.write() での意味と同じ意味を持ちます。 XML データを含んだ (オプションで) エンコードされた文字列のリストを返します。b"".join(tostringlist(element)) == tostring(element) となること以外、特定の順序になる保証はありません。

Added in version 3.2.

バージョン 3.4 で変更: Added the short_empty_elements parameter.

バージョン 3.8 で変更: Added the xml_declaration and default_namespace parameters.

バージョン 3.8 で変更: tostringlist() 関数はユーザーが指定した属性の順序を保持するようになりました。

xml.etree.ElementTree.XML(text, parser=None)

文字列定数で与えられた XML 断片を解析します。この関数は Python コードに "XML リテラル" を埋め込むのに使えます。 text には XML データを含む文字列を指定します。 parser はオプションで、パーザのインスタンスを指定します。指定されなかった場合、標準の XMLParser パーザを使用します。 Element インスタンスを返します。

xml.etree.ElementTree.XMLID(text, parser=None)

文字列定数で与えられた XML 断片を解析し、要素 ID と要素を対応付ける辞書を返します。 text には XMLデータを含んだ文字列を指定します。 parser はオプションで、パーザのインスタンスを指定します。指定されなかった場合、標準の XMLParser パーザを使用します。 Element のインスタンスと辞書のタプルを返します。

XInclude サポート

This module provides limited support for XInclude directives [https://www.w3.org/TR/xinclude/], via the 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.

使用例

Here's an example that demonstrates use of the XInclude module. To include an XML document in the current document, use the {http://www.w3.org/2001/XInclude}include element and set the parse attribute to "xml", and use the href attribute to specify the document to include.

<?xml version="1.0"?>
<document xmlns:xi="http://www.w3.org/2001/XInclude">
  <xi:include href="source.xml" parse="xml" />
</document>

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 xml.etree.ElementTree module:

from xml.etree import ElementTree, ElementInclude

tree = ElementTree.parse("document.xml")
root = tree.getroot()

ElementInclude.include(root)

The ElementInclude module replaces the {http://www.w3.org/2001/XInclude}include element with the root element from the source.xml document. The result might look something like this:

<document xmlns:xi="http://www.w3.org/2001/XInclude">
  <para>This is a paragraph.</para>
</document>

If the parse attribute is omitted, it defaults to "xml". The href attribute is required.

To include a text document, use the {http://www.w3.org/2001/XInclude}include element, and set the parse attribute to "text":

<?xml version="1.0"?>
<document xmlns:xi="http://www.w3.org/2001/XInclude">
  Copyright (c) <xi:include href="year.txt" parse="text" />.
</document>

The result might look something like:

<document xmlns:xi="http://www.w3.org/2001/XInclude">
  Copyright (c) 2003.
</document>

リファレンス

関数

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 utf-8. Returns the expanded resource. If the parse mode is "xml", this is an Element instance. If the parse mode is "text", this is a string. If the loader fails, it can return None or raise an exception.

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 Element or an ElementTree instance to find such element. loader is an optional resource loader. If omitted, it defaults to default_loader(). If given, it should be a callable that implements the same interface as 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 None to disable the limitation.

バージョン 3.9 で変更: Added the base_url and max_depth parameters.

Element オブジェクト

class xml.etree.ElementTree.Element(tag, attrib={}, **extra)

要素クラスです。この関数は Element インターフェースを定義すると同時に、そのリファレンス実装を提供します。

要素名、属性名、および属性値はバイト文字列でも Unicode 文字列でも構いません。 tag には要素名を指定します。attrib はオプションで、要素と属性を含む辞書を指定します。extra は追加の属性で、キーワード引数として与えます。要素インスタンスを返します。

tag

この要素が表すデータの種類を示す文字列です (言い替えると、要素の型です)。

text

tail

これらの属性は要素に結びつけられた付加的なデータを保持するのに使われます。これらの属性値はたいてい文字列ですが、アプリケーション固有のオブジェクトであって構いません。要素が XML ファイルから作られる場合、 text 属性は要素の開始タグとその最初の子要素または終了タグまでのテキストか、あるいは None を保持し、 tail 属性は要素の終了タグと次のタグまでのテキストか、あるいは None を保持します。このような XML データ

<a><b>1<c>2<d/>3</c></b>4</a>

の場合、 a 要素は text, tail 属性ともに None, b 要素は text に "1" で tail に "4", c 要素は text に "2" で tail は None, d 要素 は text が None で tail に "3" をそれぞれ保持します。

要素の内側のテキストを収集するためには、itertext() を参照してください。例えば "".join(element.itertext()) のようにします。

アプリケーションはこれらの属性に任意のオブジェクトを格納できます。

attrib

要素の属性を保持する辞書です。 attrib の値は常に書き換え可能な Python 辞書ですが、ElementTree の実装によっては別の内部表現を使用し、要求されたときにだけ辞書を作るようにしているかもしれません。そうした実装の利益を享受するために、可能な限り下記の辞書メソッドを通じて使用してください。

以下の辞書風メソッドが要素の属性に対して動作します。

clear()

要素をリセットします。この関数は全ての子要素を削除し、全属性を消去し、テキストとテール属性を None に設定します。

get(key, default=None)

要素の key という名前の属性を取得します。

属性の値、または属性がない場合は default を返します。

items()

要素の属性を (名前, 値) ペアのシーケンスとして返します。返される属性の順番は決まっていません。

keys()

要素の属性名をリストとして返します。返される名前の順番は決まっていません。

set(key, value)

要素の属性 key に value をセットします。

以下のメソッドは要素の子要素 (副要素) に対して動作します。

append(subelement)

要素 subelement を、要素の子要素の内部リストの末尾に追加します。subelement Element でない場合、TypeError を送出します。

extend(subelements)

0 個以上の要素のシーケンスオブジェクトによって subelements を拡張します。subelements が Element でない場合、TypeError を送出します。

Added in version 3.2.

find(match, namespaces=None)

Finds the first subelement matching match. match may be a tag name or a path. Returns an element instance or None. namespaces is an optional mapping from namespace prefix to full name. Pass '' as prefix to move all unprefixed tag names in the expression into the given namespace.

findall(match, namespaces=None)

Finds all matching subelements, by tag name or path. Returns a list containing all matching elements in document order. namespaces is an optional mapping from namespace prefix to full name. Pass '' as prefix to move all unprefixed tag names in the expression into the given namespace.

findtext(match, default=None, namespaces=None)

Finds text for the first subelement matching match. match may be a tag name or a 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 '' as prefix to move all unprefixed tag names in the expression into the given namespace.

insert(index, subelement)

要素内の指定された位置に subelement を挿入します。subelement が Element でない場合、TypeError を送出します。

iter(tag=None)

現在の要素を根とする木の イテレータ を作成します。イテレータは現在の要素とそれ以下のすべての要素を、文書内での出現順 (深さ優先順) でイテレートします。 tag が None または '*' でない場合、与えられたタグに等しいものについてのみイテレータから返されます。イテレート中に木構造が変更された場合の結果は未定義です。

Added in version 3.2.

iterfind(match, namespaces=None)

タグ名または パス にマッチするすべての子要素を検索します。マッチしたすべての要素を文書内での出現順で yield するイテレータを返します。namespaces はオプションで、名前空間接頭辞と完全名を対応付けるマップオブジェクトを指定します。

Added in version 3.2.

itertext()

テキストのイテレータを作成します。イテレータは、この要素とすべての子要素を文書上の順序で巡回し、すべての内部のテキストを返します。

Added in version 3.2.

makeelement(tag, attrib)

現在の要素と同じ型の新しい要素オブジェクトを作成します。このメソッドは呼び出さずに、 SubElement() ファクトリ関数を使って下さい。

remove(subelement)

要素から subelement を削除します。find* メソッド群と異なり、このメソッドは要素をインスタンスの同一性で比較します。タグや内容では比較しません。

Element オブジェクトは以下のシーケンス型のメソッドを、サブ要素を操作するためにサポートします: __delitem__(), __getitem__(), __setitem__(), __len__().

Caution: Elements with no subelements will test as False. Testing the truth value of an Element is deprecated and will raise an exception in Python 3.14. Use specific len(elem) or elem is None test instead.:

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")

バージョン 3.12 で変更: Testing the truth value of an Element emits 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 [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 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:

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)

ElementTree オブジェクト

class xml.etree.ElementTree.ElementTree(element=None, file=None)

ElementTree ラッパークラスです。このクラスは要素の全階層を表現し、さらに標準 XML との相互変換を追加しています。

element は根要素です。file が指定されている場合、その XML ファイルの内容により木は初期化されます。

_setroot(element)

この木の根要素を置き換えます。従って現在の木の内容は破棄され、与えられた要素が代わりに使われます。注意して使ってください。 element は要素インスタンスです。

find(match, namespaces=None)

Element.find() と同じで、木の根要素を起点とします。

findall(match, namespaces=None)

Element.findall() と同じで、木の根要素を起点とします。

findtext(match, default=None, namespaces=None)

Element.findtext() と同じで、木の根要素を起点とします。

getroot()

この木のルート要素を返します。

iter(tag=None)

根要素に対する、木を巡回するイテレータを返します。イテレータは木のすべての要素に渡ってセクション順にループします。tag は探したいタグです (デフォルトではすべての要素を返します)。

iterfind(match, namespaces=None)

Element.iterfind() と同じで、木の根要素を起点とします。

Added in version 3.2.

parse(source, parser=None)

外部の XML 断片をこの要素木に入れます。source にはファイル名か ファイルオブジェクト を指定します。parser はオプションで、パーザインスタンスを指定します。パーザが指定されない場合、標準の XMLParser パーザが使用されます。断片の根要素を返します。

write(file, encoding='us-ascii', xml_declaration=None, default_namespace=None, method='xml', *, short_empty_elements=True)

要素の木をファイルに XML として書き込みます。 file は、書き込み用に開かれたファイル名または ファイルオブジェクト です。 encoding [1] は出力エンコーディング(デフォルトは US-ASCII)です。 xml_declaration は、 XML 宣言がファイルに書かれるかどうかを制御します。 False の場合は常に書かれず、 True の場合は常に書かれ、 None の場合は US-ASCII 、 UTF-8 、 Unicode 以外の場合に書かれます (デフォルトは None です)。 default_namespace でデフォルトの XML 名前空間 ("xmlns" 用) を指定します。 method は "xml", "html", "text" のいずれかです (デフォルトは "xml" です)。キーワード専用の short_empty_elements 引数は、内容がない属性のフォーマットを制御します。 True (既定) の場合、単一の空要素タグとして書かれ、False の場合、開始タグと終了タグのペアとしてかかれます。

出力は引数 encoding によって、文字列 (str) かバイト列 (bytes) になります。encoding が "unicode" の場合、出力は文字列になり、それ以外ではバイト列になります。file が ファイルオブジェクト の場合、型が衝突する場合があります。文字列をバイト列ファイルへ書き込んだり、その逆を行わないよう注意してください。

バージョン 3.4 で変更: Added the short_empty_elements parameter.

バージョン 3.8 で変更: write() メソッドはユーザーが指定した属性の順序を保持するようになりました。

以下はこれから操作する XML ファイルです:

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

第 1 段落のすべてのリンクの "target" 属性を変更する例:

>>> 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")

QName オブジェクト

class xml.etree.ElementTree.QName(text_or_uri, tag=None)

QName ラッパーです。このクラスは QName 属性値をラップし、出力時に適切な名前空間の扱いを得るために使われます。 text_or_uri は {uri}local という形式の QName 値を含む文字列、または tag 引数が与えられた場合には QName の URI 部分の文字列です。 tag が与えられた場合、一つめの引数は URI と解釈され、この引数はローカル名と解釈されます。 QName インスタンスは不透明です。

TreeBuilder オブジェクト

class xml.etree.ElementTree.TreeBuilder(element_factory=None, *, comment_factory=None, pi_factory=None, insert_comments=False, insert_pis=False)

汎用の要素構造ビルダー。これは start, data, end, comment, pi のメソッド呼び出しの列を整形式の要素構造に変換します。このクラスを使うと、好みの XML 構文解析器、または他の XML に似た形式の構文解析器を使って、要素構造を作り出すことができます。

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 Comment() and 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).

close()

ビルダのバッファをフラッシュし、最上位の文書要素を返します。戻り値は Element インスタンスになります。

data(data)

現在の要素にテキストを追加します。 data は文字列です。バイト文字列もしくは Unicode 文字列でなければなりません。

end(tag)

現在の要素を閉じます。 tag は要素の名前です。閉じられた要素を返します。

start(tag, attrs)

新しい要素を開きます。 tag は要素の名前です。 attrs は要素の属性を保持した辞書です。開かれた要素を返します。

comment(text)

Creates a comment with the given text. If insert_comments is true, this will also add it to the tree.

Added in version 3.8.

pi(target, text)

Creates a process instruction with the given target name and text. If insert_pis is true, this will also add it to the tree.

Added in version 3.8.

加えて、カスタムの TreeBuilder オブジェクトは以下のメソッドを提供できます:

doctype(name, pubid, system)

doctype 宣言を処理します。 name は doctype 名です。 pubid は公式の識別子です。 system はシステム識別子です。このメソッドはデフォルトの TreeBuilder クラスには存在しません。

Added in version 3.2.

start_ns(prefix, uri)

Is called whenever the parser encounters a new namespace declaration, before the start() callback for the opening element that defines it. prefix is '' for the default namespace and the declared namespace prefix name otherwise. uri is the namespace URI.

Added in version 3.8.

end_ns(prefix)

Is called after the end() callback of an element that declared a namespace prefix mapping, with the name of the prefix that went out of scope.

Added in version 3.8.

class 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 [https://www.w3.org/TR/xml-c14n2/] writer. Arguments are the same as for the canonicalize() function. This class does not build a tree but translates the callback events directly into a serialised form using the write function.

Added in version 3.8.

XMLParser オブジェクト

class xml.etree.ElementTree.XMLParser(*, target=None, encoding=None)

このクラスは、このモジュールの構成要素のうち、低水準のものです。効率的でイベントベースのXMLパースのため、xml.parsers.expat を使用します。feed() メソッドで XML データをインクリメンタルに受け取り、target オブジェクトのコールバックを呼び出すことで、パースイベントをプッシュ API に変換します。target が省略された場合、標準の TreeBuilder が使用されます。 encoding [1] が指定された場合、このあたいは XML ファイル内で指定されたエンコーディングを上書きします。

バージョン 3.8 で変更: Parameters are now keyword-only. The html argument no longer supported.

close()

パーザへのデータの提供を完了します。構築中に渡される target の close() メソッドを呼び出す結果を返します。既定では、これがトップレベルのドキュメント要素になります。

feed(data)

パーザへデータを入力します。 data はエンコードされたデータです。

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 flush() temporarily disables reparse deferral with Expat (if currently enabled) and triggers a reparse. Disabling reparse deferral has security consequences; please see xml.parsers.expat.xmlparser.SetReparseDeferralEnabled() for details.

Note that flush() has been backported to some prior releases of CPython as a security fix. Check for availability of flush() using hasattr() if used in code running across a variety of Python versions.

Added in version 3.12.3.

XMLParser.feed() は target の start(tag, attrs_dict) メソッドをそれぞれの開始タグに対して呼び、また end(tag) メソッドを終了タグに対して呼び、そしてデータを data(data) メソッドで処理します。サポートされているその他のコールバックメソッドについては、 TreeBuilder クラスを参照してください。XMLParser.close() は target の close() メソッドを呼びます。 XMLParser は木構造を構築する以外にも使えます。以下の例では、XML ファイルの最高の深さを数えます。

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

XMLPullParser オブジェクト

class xml.etree.ElementTree.XMLPullParser(events=None)

非ブロックアプリケーションに適したプルパーザです。入力側の API は XMLParser のものと似ていますが、コールバックターゲットに呼び出しをプッシュするのではなく、 XMLPullParser はパースイベントの内部リストを収集し、ユーザーがそこから読み出すことができます。events は、呼び出し元に報告するイベントのシーケンスです。サポートされているイベントは、文字列の "start", "end", "comment", "pi", "start-ns", "end-ns" ("ns" イベントは、名前空間の詳細情報の取得に使用) です。events が省略された場合、 "end" イベントのみが報告されます。

feed(data)

指定したバイトデータをパーザに与えます。

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 flush() temporarily disables reparse deferral with Expat (if currently enabled) and triggers a reparse. Disabling reparse deferral has security consequences; please see xml.parsers.expat.xmlparser.SetReparseDeferralEnabled() for details.

Note that flush() has been backported to some prior releases of CPython as a security fix. Check for availability of flush() using hasattr() if used in code running across a variety of Python versions.

Added in version 3.12.3.

close()

パーザに、データストリームが終了したことを伝えます。XMLParser.close() とは異なり、このメソッドは常に None を返します。パーザがクローズした時にまだ帰って来ていないイベントは、まだ read_events() で読むことができます。

read_events()

Return an iterator over the events which have been encountered in the data fed to the parser. The iterator yields (event, elem) pairs, where event is a string representing the type of event (e.g. "end") and elem is the encountered Element object, or other context value as follows.

start, end: the current Element.

comment, pi: the current comment / processing instruction

start-ns: a tuple (prefix, uri) naming the declared namespace mapping.

end-ns: None (this may change in a future version)

read_events() の前の呼び出しで提供されたイベントは、再度 yield されることはありません。イベントは、イテレータから取得された場合にのみ内部キューから消費されるため、read_events() から取得されたイテレータに対して複数の読み出しを並行して反復的に行うと、予期せぬ結果が引き起こされます。

注釈

XMLPullParser は "start" イベントを発行した時に開始タグの文字 ">" が現れたことだけを保証します。そのため、属性は定義されますが、その時点ではテキストの内容も tail 属性も定義されていません。子要素にもそれが存在する、しないにかかわらず同じ物が適用されます。

全部揃った要素が必要ならば、"end" イベントを探してください。

Added in version 3.4.

バージョン 3.8 で変更: イベント comment, pi が追加されました。

例外

class xml.etree.ElementTree.ParseError

解析に失敗した時、このモジュールの様々なメソッドから送出される XML 解析エラーです。この例外のインスタンスが表す文字列は、ユーザフレンドリなメッセージを含んでいます。その他に、以下の属性も利用できます:

code

expat パーザからの数値エラーコードです。エラーコードの一覧とそれらの意味については、xml.parsers.expat のドキュメントを参照してください。

position

エラーが発生した場所を示す line と column 番号のタプルです。

脚注

[1] (1,2,3,4)

XML 出力に含まれるエンコーディング文字列は適切な規格に従っていなければなりません。例えば、"UTF-8" は有効ですが、"UTF8" はそうではありません。https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl と https://www.iana.org/assignments/character-sets/character-sets.xhtml を参照してください。

xml.dom --- The Document Object Model API

ソースコード: Lib/xml/dom/__init__.py [https://github.com/python/cpython/tree/3.12/Lib/xml/dom/__init__.py]

文書オブジェクトモデル (Document Object Model)、すなわち "DOM" は、ワールドワイドウェブコンソーシアム (World Wide Web Consortium, W3C) による、XML ドキュメントにアクセスしたり変更を加えたりするための、プログラミング言語間共通の API です。DOM 実装によって、XML ドキュメントはツリー構造として表現されます。また、クライアントコード側でツリー構造をゼロから構築できるようになります。さらに、前述の構造に対して、よく知られたインターフェースをもつ一連のオブジェクトを通したアクセス手段も提供します。

DOM はランダムアクセスを行うアプリケーションで非常に有用です。SAX では、一度に閲覧することができるのはドキュメントのほんの一部分です。ある SAX 要素に注目している際には、別の要素をアクセスすることはできません。またテキストノードに注目しているときには、その中に入っている要素をアクセスすることができません。SAX によるアプリケーションを書くときには、プログラムがドキュメント内のどこを処理しているのかを追跡するよう、コードのどこかに記述する必要があります。SAX 自体がその作業を行ってくれることはありません。さらに、XML ドキュメントに対する先読み (look ahead) が必要だとすると不運なことになります。

アプリケーションによっては、ツリーにアクセスできなければイベント駆動モデルを実現できません。もちろん、何らかのツリーを SAX イベントに応じて自分で構築することもできるでしょうが、DOM ではそのようなコードを書かなくてもよくなります。DOM は XML データに対する標準的なツリー表現なのです。

文書オブジェクトモデルは、W3C によっていくつかの段階、W3C の用語で言えば "レベル (level)" で定義されています。Python においては、DOM API への対応付けは実質的には DOM レベル 2 勧告に基づいています。

DOM アプリケーションは、普通は XML を DOM に解析するところから始まります。どのようにして解析を行うかについては DOM レベル 1 では全くカバーしておらず、レベル 2 では限定的な改良だけが行われました: レベル 2 では Document を生成するメソッドを提供する DOMImplementation オブジェクトクラスがありますが、実装に依存しない方法で XML リーダ(reader)/パーザ(parser)/文書ビルダ (Document builder) にアクセスする方法はありません。また、既存の Document オブジェクトなしにこれらのメソッドにアクセスするような、よく定義された方法もありません。 Python では、各々の DOM 実装で getDOMImplementation() が定義されているはずです。 DOM レベル 3 ではロード(Load)/ストア(Store) 仕様が追加され、リーダのインターフェースにを定義していますが、Python 標準ライブラリではまだ利用することができません。

DOM 文書オブジェクトを生成したら、そのプロパティとメソッドを使って XML 文書の一部にアクセスできます。これらのプロパティは DOM 仕様で定義されています; 本リファレンスマニュアルでは、Python において DOM 仕様がどのように解釈されているかを記述しています。

W3C から提供されている仕様は、 DOM API を Java、ECMAScript、および OMG IDL で定義しています。ここで定義されている Python での対応づけは、大部分がこの仕様の IDL 版に基づいていますが、厳密な準拠は必要とされていません (実装で IDL の厳密な対応付けをサポートするのは自由ですが)。API への対応付けに関する詳細な議論は 適合性 を参照してください。

参考

Document Object Model (DOM) Level 2 Specification [https://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113/]

Python DOM API が準拠している W3C 勧告。

Document Object Model (DOM) Level 1 Specification [https://www.w3.org/TR/REC-DOM-Level-1/]

xml.dom.minidom でサポートされている W3C の DOM に関する勧告。

Python Language Mapping Specification [https://www.omg.org/spec/PYTH/1.2/PDF]

このドキュメントでは OMG IDL から Python への対応付けを記述しています。

モジュールコンテンツ

xml.dom には以下の関数があります:

xml.dom.registerDOMImplementation(name, factory)

ファクトリ関数 (factory function) factory を名前 name で登録します。ファクトリ関数は DOMImplementation インターフェースを実装するオブジェクトを返さなければなりません。特定の実装 (例えば実装が何らかのカスタマイズをサポートしている場合) に適切となるように、ファクトリ関数は毎回同じオブジェクトを返したり、呼び出しごとに新しいオブジェクトを返したりすることが出来ます。

xml.dom.getDOMImplementation(name=None, features=())

適切な DOM 実装を返します。name は、よく知られた DOM 実装のモジュール名か、 None になります。 None でない場合、対応するモジュールを import して、import が成功した場合 DOMImplementation オブジェクトを返します。 name が与えられておらず、環境変数 PYTHON_DOM が設定されていた場合、 DOM 実装を見つけるのに環境変数が使われます。

name が与えられない場合、利用可能な実装を調べて、指定された機能 (feature) セットを持つものを探します。実装が見つからなければ ImportError を送出します。 features のリストは (feature, version) のペアからなるシーケンスで、利用可能な DOMImplementation オブジェクトの hasFeature() メソッドに渡されます。

いくつかの便利な定数も提供されています:

xml.dom.EMPTY_NAMESPACE

DOM 内のノードに名前空間が何も関連づけられていないことを示すために使われる値です。この値は通常、ノードの namespaceURI の値として見つかったり、名前空間特有のメソッドに対する namespaceURI パラメタとして使われます。

xml.dom.XML_NAMESPACE

Namespaces in XML [https://www.w3.org/TR/REC-xml-names/] (4 節) で定義されている、予約済みプレフィクス (reserved prefix) xml に関連付けられた名前空間 URI です。

xml.dom.XMLNS_NAMESPACE

Document Object Model (DOM) Level 2 Core Specification [https://www.w3.org/TR/DOM-Level-2-Core/core.html] (1.1.8 節) で定義されている、名前空間宣言への名前空間 URI です。

xml.dom.XHTML_NAMESPACE

XHTML 1.0: The Extensible HyperText Markup Language [https://www.w3.org/TR/xhtml1/] (3.1.1 節) で定義されている、XHTML 名前空間 URI です。

加えて、 xml.dom には基底となる Node クラスと DOM 例外クラスが収められています。このモジュールで提供されている Node クラスは DOM 仕様で定義されているメソッドや属性は何ら実装していません; これらは具体的な DOM 実装において提供しなければなりません。このモジュールの一部として提供されている Node クラスでは、具体的な Node オブジェクトの nodeType 属性として使う定数を提供しています; これらの定数は、DOM 仕様に適合するため、クラスではなくモジュールのレベルに配置されています。

DOM 内のオブジェクト

DOM について最も明確に限定しているドキュメントは W3C による DOM 仕様です。

DOM 属性は単純な文字列としてだけではなく、ノードとして操作されるかもしれないので注意してください。とはいえ、そうしなければならない場合はかなり稀なので、今のところ記述されていません。

インターフェース

節

目的

DOMImplementation

DOMImplementation オブジェクト

根底にある実装へのインターフェース。

Node

Node オブジェクト

ドキュメント内の大部分のオブジェクトに対する基底インターフェース。

NodeList

NodeList オブジェクト

ノード列に対するインターフェース。

DocumentType

DocumentType オブジェクト

ドキュメントの処理に必要な宣言についての情報。

Document

Document オブジェクト

ドキュメント全体を表現するオブジェクト。

Element

Element オブジェクト

ドキュメント階層内の要素ノード。

Attr

Attr オブジェクト

要素ノード上の属性値ノード。

Comment

Comment オブジェクト

ソースドキュメント内のコメント表現。

Text

Text オブジェクトおよび CDATASection オブジェクト

ドキュメント内のテキスト記述を含むノード。

ProcessingInstruction

ProcessingInstruction オブジェクト

処理命令 (processing instruction) 表現。

さらに追加の節として、Python で DOM を利用するために定義されている例外について記述しています。

DOMImplementation オブジェクト

DOMImplementation インターフェースは、利用している DOM 実装において特定の機能が利用可能かどうかを決定するための方法をアプリケーションに提供します。DOM レベル 2 では、 DOMImplementation を使って新たな Document オブジェクトや DocumentType オブジェクトを生成する機能も追加しています。

DOMImplementation.hasFeature(feature, version)

機能名 feature とバージョン番号 version で識別される機能（feature）が実装されていれば True を返します。

DOMImplementation.createDocument(namespaceUri, qualifiedName, doctype)

新たな(DOMのスーパークラスである) Document クラスのオブジェクトを返します。このクラスは namespaceUri と qualifiedName が設定された子クラス Element のオブジェクトを所有しています。 doctype は createDocumentType() によって生成された DocumentType クラスのオブジェクト、または None である必要があります。 Python DOM APIでは、子クラスである Element を作成しないことを示すために、はじめの２つの引数を None に設定することができます。

DOMImplementation.createDocumentType(qualifiedName, publicId, systemId)

新たな DocumentType クラスのオブジェクトを返します。このオブジェクトは qualifiedName 、 publicId 、そして systemId 文字列をふくんでおり、XML文書の形式情報を表現しています。

Node オブジェクト

XML 文書の全ての構成要素は Node のサブクラスです。

Node.nodeType

ノード (node) の型を表現する整数値です。型に対応する以下のシンボル定数: ELEMENT_NODE 、 ATTRIBUTE_NODE 、 TEXT_NODE 、 CDATA_SECTION_NODE 、 ENTITY_NODE 、 PROCESSING_INSTRUCTION_NODE 、 COMMENT_NODE 、 DOCUMENT_NODE 、 DOCUMENT_TYPE_NODE 、 NOTATION_NODE 、が Node オブジェクトで定義されています。読み出し専用の属性です。

Node.parentNode

現在のノードの親ノードか、文書ノードの場合には None になります。この値は常に Node オブジェクトか None になります。 Element ノードの場合、この値はルート要素 (root element) の場合を除き親要素 (parent element) となり、ルート要素の場合には Document オブジェクトとなります。 Attr ノードの場合、この値は常に None となります。読み出し専用の属性です。

Node.attributes

属性オブジェクトの NamedNodeMap です。要素だけがこの属性に実際の値を持ちます; その他のオブジェクトでは、この属性を None にします。読み出し専用の属性です。

Node.previousSibling

このノードと同じ親ノードを持ち、直前にくるノードです。例えば、self 要素の開始タグの直前にくる終了タグを持つ要素です。もちろん、XML 文書は要素だけで構成されているだけではないので、直前にくる兄弟関係にある要素 (sibling) はテキストやコメント、その他になる可能性があります。このノードが親ノードにおける先頭の子ノードである場合、属性値は None になります。読み出し専用の属性です。

Node.nextSibling

このノードと同じ親ノードを持ち、直後にくるノードです。例えば、 previousSibling も参照してください。このノードが親ノードにおける末尾の子ノードである場合、属性値は None になります。読み出し専用の属性です。

Node.childNodes

このノード内に収められているノードからなるリストです。読み出し専用の属性です。

Node.firstChild

このノードに子ノードがある場合、その先頭のノードです。そうでない場合 None になります。読み出し専用の属性です。

Node.lastChild

このノードに子ノードがある場合、その末尾のノードです。そうでない場合 None になります。読み出し専用の属性です。

Node.localName

tagName にコロンがあれば、コロン以降の部分に、なければ tagName 全体になります。値は文字列です。

Node.prefix

tagName のコロンがあれば、コロン以前の部分に、なければ空文字列になります。値は文字列か、 None になります。

Node.namespaceURI

要素名に関連付けられた名前空間です。文字列か None になります。読み出し専用の属性です。

Node.nodeName

この属性はノード型ごとに異なる意味を持ちます。その詳細は DOM 仕様を参照してください。この属性で得られることになる情報は、全てのノード型では tagName 、属性では name プロパティといったように、常に他のプロパティで得ることができます。全てのノード型で、この属性の値は文字列か None になります。読み出し専用の属性です。

Node.nodeValue

この属性はノード型ごとに異なる意味を持ちます。その詳細は DOM 仕様を参照してください。その状況は nodeName と似ています。この属性の値は文字列または None になります。

Node.hasAttributes()

ノードが何らかの属性を持っている場合に True を返します。

Node.hasChildNodes()

ノードが何らかの子ノードを持っている場合に True を返します。

Node.isSameNode(other)

other がこのノードと同じノードを参照している場合に True を返します。このメソッドは、何らかのプロキシ (proxy) 機構を利用するような DOM 実装で特に便利です (一つ以上のオブジェクトが同じノードを参照するかもしれないからです)。

注釈

このメソッドは DOM レベル 3 API の提案に基づいたもので、まだ "ワーキングドラフト(working draft)" の段階です。しかし、このインターフェースには異論は出ないと考えられます。W3C による変更があっても、必ずしも Python DOM インターフェースにおけるこのメソッドに影響するとは限りません (ただしこのメソッドに対する何らかの新しい W3C API もサポートされるかもしれません)。

Node.appendChild(newChild)

現在のノードの子ノードリストの末尾に新たな子ノードを追加し、newChild を返します。もしノードが既にツリーにあれば、最初に削除されます。

Node.insertBefore(newChild, refChild)

新たな子ノードを既存の子ノードの前に挿入します。 refChild は現在のノードの子ノードである場合に限られます; そうでない場合、 ValueError が送出されます。 newChild が返されます。もし refChild が None なら、 newChild を子ノードリストの最後に挿入します。

Node.removeChild(oldChild)

子ノードを削除します。 oldChild はこのノードの子ノードでなければなりません。そうでない場合、 ValueError が送出されます。成功した場合 oldChild が返されます。 oldChild をそれ以降使わない場合、 unlink() メソッドを呼び出さなければなりません。

Node.replaceChild(newChild, oldChild)

既存のノードと新たなノードを置き換えます。この操作は oldChild が現在のノードの子ノードである場合に限られます; そうでない場合、 ValueError が送出されます。

Node.normalize()

一続きのテキスト全体を一個の Text インスタンスとして保存するために隣接するテキストノードを結合します。これにより、多くのアプリケーションで DOM ツリーからのテキスト処理が簡単になります。

Node.cloneNode(deep)

このノードを複製 (clone) します。deep を設定すると、子ノードも同様に複製することを意味します。複製されたノードを返します。

NodeList オブジェクト

NodeList はノードのシーケンスを表現します。これらのオブジェクトは DOM コア勧告 (DOM Core recommendation) において、二通りに使われています: Element オブジェクトでは、子ノードのリストを提供するのに NodeList を利用します。また、このインターフェースにおける Node の getElementsByTagName() および getElementsByTagNameNS() メソッドは、クエリに対する結果を表現するのに NodeList を利用します。

DOM レベル 2 勧告では、これらのオブジェクトに対し、以下のようにメソッドを一つ、属性を一つ定義しています。

NodeList.item(i)

存在する場合シークエンスの i 番目の要素を、そうでない場合 None を返します。i は 0 未満やシークエンスの長さ以上であってはなりません。

NodeList.length

シーケンス中のノードの数です。

この他に、Python の DOM インターフェースでは、 NodeList オブジェクトを Python のシーケンスとして使えるようにするサポートが追加されていることが必要です。 NodeList の実装では、全て __len__() と __getitem__() をサポートしなければなりません; このサポートにより、 for 文内で NodeList にわたる繰り返しと、組み込み関数 len() の適切なサポートができるようになります。

DOM 実装が文書の変更をサポートしている場合、 NodeList の実装でも __setitem__() および __delitem__() メソッドをサポートしなければなりません。

DocumentType オブジェクト

文書で宣言されている記法 (notation) やエンティティ (entity) に関する (外部サブセット(external subset) がパーザから利用でき、情報を提供できる場合にはそれも含めた) 情報は、 DocumentType オブジェクトから手に入れることができます。文書の DocumentType は、 Document オブジェクトの doctype 属性で入手することができます; 文書の DOCTYPE 宣言がない場合、文書の doctype 属性は、このインターフェースを持つインスタンスの代わりに None に設定されます。

DocumentType は Node を特殊化したもので、以下の属性を加えています:

DocumentType.publicId

文書型定義 (document type definition) の外部サブセットに対する公開識別子 (public identifier) です。文字列または None になります。

DocumentType.systemId

文書型定義 (document type definition) の外部サブセットに対するシステム識別子 (system identifier) です。文字列の URI または None になります。

DocumentType.internalSubset

ドキュメントの完全な内部サブセットを与える文字列です。サブセットを囲むブラケットは含みません。ドキュメントが内部サブセットを持たない場合、この値は None です。

DocumentType.name

DOCTYPE 宣言でルート要素の名前が与えられている場合、その値になります。

DocumentType.entities

外部エンティティの定義を与える NamedNodeMap です。複数回定義されているエンティティに対しては、最初の定義だけが提供されます (その他は XML 勧告での要求仕様によって無視されます)。パーザによって情報が提供されないか、エンティティが定義されていない場合には、この値は None になることがあります。

DocumentType.notations

記法の定義を与える NamedNodeMap です。複数回定義されている記法名に対しては、最初の定義だけが提供されます (その他は XML 勧告での要求仕様によって無視されます)。パーザによって情報が提供されないか、エンティティが定義されていない場合には、この値は None になることがあります。

Document オブジェクト

Document は XML ドキュメント全体を表現し、その構成要素である要素、属性、処理命令、コメント等を持ちます。 Document は Node からプロパティを継承していることを思い出してください。

Document.documentElement

ドキュメントの唯一無二のルート要素です。

Document.createElement(tagName)

新たな要素ノードを生成して返します。要素は、生成された時点ではドキュメント内に挿入されません。 insertBefore() や appendChild() のような他のメソッドの一つを使って明示的に挿入を行う必要があります。

Document.createElementNS(namespaceURI, tagName)

名前空間を伴う新たな要素ノードを生成して返します。 tagName には接頭辞 (prefix) があってもかまいません。要素は、生成された時点では文書内に挿入されません。 insertBefore() や appendChild() のような他のメソッドの一つを使って明示的に挿入を行う必要があります。

Document.createTextNode(data)

引数として渡されたデータの入ったテキストノードを生成して返します。他の生成 (create) メソッドと同じく、このメソッドは生成されたノードをツリーに挿入しません。

Document.createComment(data)

引数として渡されたデータの入ったコメントノードを生成して返します。他の生成 (create) メソッドと同じく、このメソッドは生成されたノードをツリーに挿入しません。

Document.createProcessingInstruction(target, data)

引数として渡された target および data の入った処理命令ノードを生成して返します。他の生成 (create) メソッドと同じく、このメソッドは生成されたノードをツリーに挿入しません。

Document.createAttribute(name)

属性ノードを生成して返します。このメソッドは属性ノードを特定の要素に関連づけることはしません。新たに生成された属性インスタンスを使うには、適切な Element オブジェクトの setAttributeNode() を使わなければなりません。

Document.createAttributeNS(namespaceURI, qualifiedName)

名前空間を伴う新たな属性ノードを生成して返します。 tagName には接頭辞 (prefix) があってもかまいません。このメソッドは属性ノードを特定の要素に関連づけることはしません。新たに生成された属性インスタンスを使うには、適切な Element オブジェクトの setAttributeNode() を使わなければなりません。

Document.getElementsByTagName(tagName)

全ての下位要素 (直接の子要素、子要素の子要素等) から特定の要素型名を持つものを検索します。

Document.getElementsByTagNameNS(namespaceURI, localName)

全ての下位要素 (直接の子要素、子要素の子要素等) から特定の名前空間 URI とローカル名 (local name) を持つものを検索します。ローカル名は名前空間における接頭辞以降の部分です。

Element オブジェクト

Element は Node のサブクラスです。このため Node クラスの全ての属性を継承します。

Element.tagName

要素型名です。名前空間使用の文書では、要素型名中にコロンがあるかもしれません。値は文字列です。

Element.getElementsByTagName(tagName)

Document クラス内における同名のメソッドと同じです。

Element.getElementsByTagNameNS(namespaceURI, localName)

Document クラス内における同名のメソッドと同じです。

Element.hasAttribute(name)

指定要素に name で渡した名前の属性が存在していれば True を返します。

Element.hasAttributeNS(namespaceURI, localName)

指定要素に namespaceURI と localName で指定した名前の属性が存在していれば True を返します。

Element.getAttribute(name)

name で指定した属性の値を文字列として返します。もし、属性が存在しない、もしくは属性に値が設定されていない場合、空の文字列が返されます。

Element.getAttributeNode(attrname)

attrname で指定された属性の Attr ノードを返します。

Element.getAttributeNS(namespaceURI, localName)

namespaceURI と localName によって指定した属性の値を文字列として返します。もし、属性が存在しない、もしくは属性に値が設定されていない場合、空の文字列が返されます。

Element.getAttributeNodeNS(namespaceURI, localName)

指定した namespaceURI および localName を持つ属性値をノードとして返します。

Element.removeAttribute(name)

名前で指定された属性を削除します。該当する属性がない場合、NotFoundErr が送出されます。

Element.removeAttributeNode(oldAttr)

oldAttr が属性リストにある場合、削除して返します。 oldAttr が存在しない場合、 NotFoundErr が送出されます。

Element.removeAttributeNS(namespaceURI, localName)

名前で指定された属性を削除します。このメソッドは qname ではなく localName を使うので注意してください。該当する属性がなくても例外は送出されません。

Element.setAttribute(name, value)

文字列を使って属性値を設定します。

Element.setAttributeNode(newAttr)

新たな属性ノードを要素に追加します。 name 属性が既存の属性に一致した場合、必要に応じて属性を置換します。置換が行われると古い属性ノードが返されます。 newAttr がすでに使われていれば、 InuseAttributeErr が送出されます。

Element.setAttributeNodeNS(newAttr)

新たな属性ノードを要素に追加します。 namespaceURI および localName 属性が既存の属性に一致した場合、必要に応じて属性を置き換えます。置換が生じると、古い属性ノードが返されます。 newAttr がすでに使われていれば、 InuseAttributeErr が送出されます。

Element.setAttributeNS(namespaceURI, qname, value)

指定された namespaceURI および qname で与えられた属性の値を文字列で設定します。qname は属性の完全な名前であり、この点が上記のメソッドと違うので注意してください。

Attr オブジェクト

Attr は Node を継承しており、全ての属性を継承しています。

Attr.name

要素型名です。名前空間使用の文書では、要素型名中にコロンが含まれるかもしれません。

Attr.localName

名前にコロンがあればコロン以降の部分に、なければ名前全体になります。

Attr.prefix

名前にコロンがあればコロン以前の部分に、なければ空文字列になります。

Attr.value

その要素の text value. これは nodeValue 属性の別名です。

NamedNodeMap Objects

NamedNodeMap は Node を継承して いません 。

NamedNodeMap.length

属性リストの長さです。

NamedNodeMap.item(index)

特定のインデクスを持つ属性を返します。属性の並び方は任意ですが、 DOM 文書が生成されている間は一定になります。各要素は属性ノードです。属性値はノードの value 属性で取得してください。

このクラスをよりマップ型的な動作ができるようにする実験的なメソッドもあります。そうしたメソッドを使うこともできますし、 Element オブジェクトに対して、標準化された getAttribute*() ファミリのメソッドを使うこともできます。

Comment オブジェクト

Comment は XML 文書中のコメントを表現します。 Comment は Node のサブクラスですが、子ノードを持つことはありません。

Comment.data

文字列によるコメントの内容です。この属性には、コメントの先頭にある <!- - と末尾にある - -> 間の全ての文字が入っていますが、<!- - と - -> 自体は含みません。

Text オブジェクトおよび CDATASection オブジェクト

Text インターフェースは XML 文書内のテキストを表現します。パーザおよび DOM 実装が DOM の XML 拡張をサポートしている場合、 CDATA でマークされた区域 (section) に入れられている部分テキストは CDATASection オブジェクトに記憶されます。これら二つのインターフェースは同一のものですが、 nodeType 属性が異なります。

これらのインターフェースは Node インターフェースを拡張したものです。しかし子ノードを持つことはできません。

Text.data

文字列によるテキストノードの内容です。

注釈

CDATASection ノードの利用は、ノードが完全な CDATA マーク区域を表現するという意味ではなく、ノードの内容が CDATA 区域の一部であるということを意味するだけです。単一の CDATA セクションは文書ツリー内で複数のノードとして表現されることがあります。二つの隣接する CDATASection ノードが、異なる CDATA マーク区域かどうかを決定する方法はありません。

ProcessingInstruction オブジェクト

XML 文書内の処理命令を表現します; Node インターフェースを継承していますが、子ノードを持つことはできません。

ProcessingInstruction.target

最初の空白文字までの処理命令の内容です。読み出し専用の属性です。

ProcessingInstruction.data

最初の空白文字以降の処理命令の内容です。

例外

DOM レベル 2 勧告では、単一の例外 DOMException と、どの種のエラーが発生したかをアプリケーションが決定できるようにする多くの定数を定義しています。 DOMException インスタンスは、特定の例外に関する適切な値を提供する code 属性を伴っています。

Python DOM インターフェースでは、上記の定数を提供していますが、同時に一連の例外を拡張して、DOM で定義されている各例外コードに対して特定の例外が存在するようにしています。 DOM の実装では、適切な特定の例外を送出しなければならず、各例外は code 属性に対応する適切な値を伴わなければなりません。

exception xml.dom.DOMException

全ての特定の DOM 例外で使われている基底例外クラスです。この例外クラスを直接インスタンス化することはできません。

exception xml.dom.DomstringSizeErr

指定された範囲のテキストが文字列に収まらない場合に送出されます。この例外は Python の DOM 実装で使われるかどうかは判っていませんが、Python で書かれていない DOM 実装から送出される場合があります。

exception xml.dom.HierarchyRequestErr

挿入できない型のノードを挿入しようと試みたときに送出されます。

exception xml.dom.IndexSizeErr

メソッドに与えたインデクスやサイズパラメタが負の値や許容範囲の値を超えた際に送出されます。

exception xml.dom.InuseAttributeErr

文書中にすでに存在する Attr ノードを挿入しようと試みた際に送出されます。

exception xml.dom.InvalidAccessErr

パラメタまたは操作が根底にあるオブジェクトでサポートされていない場合に送出されます。

exception xml.dom.InvalidCharacterErr

この例外は、文字列パラメタが、現在使われているコンテキストで XML 1.0 勧告によって許可されていない場合に送出されます。例えば、要素型に空白の入った Element ノードを生成しようとすると、このエラーが送出されます。

exception xml.dom.InvalidModificationErr

ノードの型を変更しようと試みた際に送出されます。

exception xml.dom.InvalidStateErr

定義されていないオブジェクトや、もはや利用できなくなったオブジェクトを使おうと試みた際に送出されます。

exception xml.dom.NamespaceErr

Namespaces in XML [https://www.w3.org/TR/REC-xml-names/] に照らして許可されていない方法でオブジェクトを変更しようと試みた場合、この例外が送出されます。

exception xml.dom.NotFoundErr

参照しているコンテキスト中に目的のノードが存在しない場合に送出される例外です。例えば、 NamedNodeMap.removeNamedItem() は渡されたノードがノードマップ中に存在しない場合にこの例外を送出します。

exception xml.dom.NotSupportedErr

要求された方のオブジェクトや操作が実装でサポートされていない場合に送出されます。

exception xml.dom.NoDataAllowedErr

データ属性をサポートしないノードにデータを指定した際に送出されます。

exception xml.dom.NoModificationAllowedErr

オブジェクトに対して (読み出し専用ノードに対する修正のように) 許可されていない修正を行おうと試みた際に送出されます。

exception xml.dom.SyntaxErr

無効または不正な文字列が指定された際に送出されます。

exception xml.dom.WrongDocumentErr

ノードが現在属している文書と異なる文書に挿入され、かつある文書から別の文書へのノードの移行が実装でサポートされていない場合に送出されます。

DOM 勧告で定義されている例外コードは、以下のテーブルに従って上記の例外と対応付けられます:

定数

例外

DOMSTRING_SIZE_ERR

DomstringSizeErr

HIERARCHY_REQUEST_ERR

HierarchyRequestErr

INDEX_SIZE_ERR

IndexSizeErr

INUSE_ATTRIBUTE_ERR

InuseAttributeErr

INVALID_ACCESS_ERR

InvalidAccessErr

INVALID_CHARACTER_ERR

InvalidCharacterErr

INVALID_MODIFICATION_ERR

InvalidModificationErr

INVALID_STATE_ERR

InvalidStateErr

NAMESPACE_ERR

NamespaceErr

NOT_FOUND_ERR

NotFoundErr

NOT_SUPPORTED_ERR

NotSupportedErr

NO_DATA_ALLOWED_ERR

NoDataAllowedErr

NO_MODIFICATION_ALLOWED_ERR

NoModificationAllowedErr

SYNTAX_ERR

SyntaxErr

WRONG_DOCUMENT_ERR

WrongDocumentErr

適合性

この節では適合性に関する要求と、Python DOM API、W3C DOM 勧告、および OMG IDL の Python API への対応付けとの間の関係について述べます。

型の対応付け

DOM 仕様で使われている IDL 型は、以下のテーブルに従って Python の型に対応付けられています。

IDL 型

Python の型

boolean

bool または int

int

int

long int

int

unsigned int

int

DOMString

str または bytes

null

None

アクセサメソッド

OMG IDL から Python への対応付けは、IDL attribute 宣言へのアクセサ関数の定義を、Java による対応付けが行うのとほとんど同じように行います。IDL 宣言の対応付け

readonly attribute string someValue;
         attribute string anotherValue;

は、三つのアクセサ関数: someValue に対する "get" メソッド (_get_someValue())、そして anotherValue に対する "get" および "set" メソッド (_get_anotherValue() および _set_anotherValue()) を生成します。とりわけ、対応付けでは、IDL 属性が通常の Python 属性としてアクセス可能であることは必須ではありません: object.someValue が動作することは必須 ではなく 、 AttributeError を送出してもかまいません。

しかしながら、Python DOM API では、通常の属性アクセスが動作することが必須です。これは、Python IDL コンパイラによって生成された典型的な代用物はまず動作することはなく、DOM オブジェクトが CORBA を介してアクセスされる場合には、クライアント上でラッパーオブジェクトが必要であることを意味します。CORBA DOM クライアントでは他にもいくつか考慮すべきことがある一方で、Python から CORBA を介して DOM を使った経験を持つ実装者はこのことを問題視していません。readonly であると宣言された属性は、全ての DOM 実装で書き込みアクセスを制限しているとは限りません。

Python DOM API では、アクセサ関数は必須ではありません。アクセサ関数が提供された場合、Python IDL 対応付けによって定義された形式をとらなければなりませんが、属性は Python から直接アクセスすることができるので、それらのメソッドは必須ではないと考えられます。readonly であると宣言された属性に対しては、 "set" アクセサを提供してはなりません。

このIDLでの定義はW3C DOM APIの全ての要件を実装しているわけではありません。例えば、一部のオブジェクトの概念や getElementsByTagName() が "live" であることなどです。 Python DOM API はこれらの要件を実装することを強制しません。

xml.dom.minidom --- Minimal DOM implementation

ソースコード: Lib/xml/dom/minidom.py [https://github.com/python/cpython/tree/3.12/Lib/xml/dom/minidom.py]

xml.dom.minidom は、 Document Object Model インターフェースの最小の実装です。他言語の実装と似た API を持ちます。このモジュールは、完全な DOM に比べて単純で、非常に小さくなるように意図されています。 DOM について既に熟知しているユーザを除き、 XML 処理には代わりに xml.etree.ElementTree モジュールを使うことを検討すべきです。

警告

xml.dom.minidom モジュールは悪意を持って作成されたデータに対して安全ではありません。信頼できないデータや認証されていないデータをパースする必要がある場合は XML の脆弱性 を参照してください。

DOM アプリケーションは通常、XML を DOM に解析 (parse) することで開始します。 xml.dom.minidom では、以下のような解析用の関数を介して行います:

from xml.dom.minidom import parse, parseString

dom1 = parse('c:\\temp\\mydata.xml')  # parse an XML file by name

datasource = open('c:\\temp\\mydata.xml')
dom2 = parse(datasource)  # parse an open file

dom3 = parseString('<myxml>Some data<empty/> some more data</myxml>')

parse() 関数はファイル名か、開かれたファイルオブジェクトを引数にとることができます。

xml.dom.minidom.parse(filename_or_file, parser=None, bufsize=None)

与えられた入力から Document を返します。 filename_or_file はファイル名でもファイルオブジェクトでもかまいません。 parser を指定する場合、SAX2 パーザオブジェクトでなければなりません。この関数はパーザの文書ハンドラを変更し、名前空間サポートを有効にします; (エンティティリゾルバ (entity resolver) のような) 他のパーザ設定は前もっておこなわなければなりません。

XML データを文字列で持っている場合、 parseString() を代わりに使うことができます:

xml.dom.minidom.parseString(string, parser=None)

string を表わす Document を返します。このメソッドは、文字列に対する io.StringIO オブジェクトを作成し、それを parse() に渡します。

これらの関数は両方とも、文書の内容を表現する Document オブジェクトを返します。

parse() や parseString() といった関数が行うのは、 XML パーザを、何らかの SAX パーザからくる解析イベント (parse event) を受け取って DOM ツリーに変換できるような "DOM ビルダ (DOM builder)" に結合することです。関数は誤解を招くような名前になっているかもしれませんが、インターフェースについて学んでいるときには理解しやすいでしょう。文書の解析はこれらの関数が戻るより前に完結します; 要するに、これらの関数自体はパーザ実装を提供しないということです。

"DOM 実装" オブジェクトのメソッドを呼び出して Document を生成することもできます。このオブジェクトは、 xml.dom パッケージ、または xml.dom.minidom モジュールの getDOMImplementation() 関数を呼び出して取得できます。 Document を取得したら、DOM を構成するために子ノードを追加していくことができます:

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)

DOM 文書オブジェクトを手にしたら、XML 文書のプロパティやメソッドを使って、文書の一部にアクセスすることができます。これらのプロパティは DOM 仕様で定義されています。文書オブジェクトの主要なプロパティは documentElement プロパティです。このプロパティは XML 文書の主要な要素、つまり他の全ての要素を保持する要素を与えます。以下にプログラム例を示します。

dom3 = parseString("<myxml>Some data</myxml>")
assert dom3.documentElement.tagName == "myxml"

When you are finished with a DOM tree, you may optionally call the unlink() method to encourage early cleanup of the now-unneeded objects. unlink() is an 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.

参考

Document Object Model (DOM) Level 1 Specification [https://www.w3.org/TR/REC-DOM-Level-1/]

xml.dom.minidom でサポートされている W3C の DOM に関する勧告。

DOM オブジェクト

Python の DOM API 定義は xml.dom モジュールドキュメントの一部として与えられています。この節では、 xml.dom の API と xml.dom.minidom との違いについて列挙します。

Node.unlink()

DOM との内部的な参照を破壊して、循環参照ガベージコレクションを持たないバージョンの Python でもガベージコレクションされるようにします。循環参照ガベージコレクションが利用できる場合でも、このメソッドを使えば大量のメモリをすぐに使えるようにできるため、不要になったらすぐに DOM オブジェクトに対してこのメソッドを呼ぶのが良い習慣です。このメソッドは Document オブジェクトに対して呼び出すだけでよいのですが、あるノードの子ノードを破棄するために子ノードに対して呼び出してもかまいません。

with ステートメントを使用することで、このメソッドを明示的に呼ばないようにできます。 with ブロックから出る時に自動的に次のコードが dom を unlink します:

with xml.dom.minidom.parse(datasource) as dom:
    ... # Work with dom.

Node.writexml(writer, indent='', addindent='', newl='', encoding=None, standalone=None)

XML を writer オブジェクトに書き込みます。 writer は入力としてテキストは受け付けますが、バイト列は受け付けません。 writer はファイルオブジェクトインターフェースの write() に該当するメソッドを持たなければなりません。 indent 引数には現在のノードのインデントを指定します。 addindent 引数には現在のノードの下にサブノードを追加する際のインデント増分を指定します。 newl には、改行時に行末を終端する文字列を指定します。

Document ノードでは、追加のキーワード引数 encoding を使って XML ヘッダの encoding フィールドを指定することができます。

同様に、standalone 引数を明示的に指定すると、スタンドアロン文書宣言がXMLのプロローグに追加されます。値が True の場合、standalone="yes" が追加され、それ以外の場合 "no" が設定されます。引数を指定しない場合は文書から宣言が省略されます。

バージョン 3.8 で変更: writexml() メソッドはユーザーが指定した属性の順序を保持するようになりました。

バージョン 3.9 で変更: standalone パラメータが追加されました。

Node.toxml(encoding=None, standalone=None)

DOM ノードによって表わされる XML を含んだ文字列またはバイト文字列を返します。

明示的に encoding [1] 引数を渡すと、結果は指定されたエンコードのバイト文字列になります。encoding 引数なしだと、結果は unicode 文字列です。また、結果として生じる文字列の中の XML 宣言はエンコーディングを指定しません。XML のデフォルトエンコーディングは UTF-8 なので、この文字列を UTF-8 以外でエンコードすることはおそらく正しくありません。

standalone 引数は writexml() と全く同じ動作をします。

バージョン 3.8 で変更: toxml() メソッドはユーザーが指定した属性の順序を保持するようになりました。

バージョン 3.9 で変更: standalone パラメータが追加されました。

Node.toprettyxml(indent='\t', newl='\n', encoding=None, standalone=None)

文書の整形されたバージョンを返します。 indent はインデントを行うための文字で、デフォルトはタブです; newl には行末で出力される文字列を指定し、デフォルトは \n です。

encoding 引数は toxml() の対応する引数と同様に振る舞います。

standalone 引数は writexml() と全く同じ動作をします。

バージョン 3.8 で変更: toprettyxml() メソッドはユーザーが指定した属性の順序を保持するようになりました。

バージョン 3.9 で変更: standalone パラメータが追加されました。

DOM の例

以下のプログラム例は、単純なプログラムのかなり現実的な例です。特にこの例に関しては、DOM の柔軟性をあまり活用してはいません。

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

minidom と DOM 標準

xml.dom.minidom モジュールは、本質的には DOM 1.0 互換の DOM に、いくつかの DOM 2 機能 (主に名前空間機能) を追加したものです。

Python における DOM インターフェースは率直なものです。以下の対応付け規則が適用されます:

インターフェースはインスタンスオブジェクトを介してアクセスされます。アプリケーション自身から、クラスをインスタンス化してはなりません; Document オブジェクト上で利用可能な生成関数 (creator function) を使わなければなりません。派生インターフェースでは基底インターフェースの全ての演算 (および属性) に加え、新たな演算をサポートします。

演算はメソッドとして使われます。DOM では in パラメタのみを使うので、引数は通常の順番 (左から右へ) で渡されます。オプション引数はありません。 void 演算は None を返します。

IDL 属性はインスタンス属性に対応付けられます。OMG IDL 言語における Python への対応付けとの互換性のために、属性 foo はアクセサメソッド _get_foo() および _set_foo() でもアクセスできます。 readonly 属性は変更してはなりません; とはいえ、これは実行時には強制されません。

short int 、 unsigned int 、 unsigned long long 、および boolean 型は、全て Python 整数オブジェクトに対応付けられます。

DOMString 型は Python 文字列型に対応付けられます。 xml.dom.minidom ではバイト列か文字列のどちらかに対応づけられますが、通常文字列を生成します。 DOMString 型の値は、W3C の DOM 仕様で、IDL null 値になってもよいとされている場所では None になることもあります。

const 宣言を行うと、 (xml.dom.minidom.Node.PROCESSING_INSTRUCTION_NODE のように) 対応するスコープ内の変数に対応付けを行います; これらは変更してはなりません。

DOMException は現状では xml.dom.minidom でサポートされていません。その代わり、 xml.dom.minidom は、 TypeError や AttributeError といった標準の Python 例外を使います。

NodeList オブジェクトは Python の組み込みのリスト型を使って実装されています。これらのオブジェクトは DOM 仕様で定義されたインターフェースを提供していますが、以前のバージョンの Python では、公式の API をサポートしていません。しかしながら、これらの API は W3C 勧告で定義されたインターフェースよりも "Python 的な" ものになっています。

以下のインターフェースは xml.dom.minidom では全く実装されていません:

DOMTimeStamp

EntityReference

これらの大部分は、ほとんどの DOM のユーザにとって一般的な用途として有用とはならないような XML 文書内の情報を反映しています。

脚注

[1]

XML 出力に含まれるエンコード名は適切な規格に従っていなければなりません。例えば "UTF-8" は有効ですが、 "UTF8" は XML 文書の宣言では有効ではありません。後者はエンコード名として Python に認められるとしてもです。https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl と https://www.iana.org/assignments/character-sets/character-sets.xhtml を参照してください。

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

Source code: Lib/xml/dom/pulldom.py [https://github.com/python/cpython/tree/3.12/Lib/xml/dom/pulldom.py]

xml.dom.pulldom モジュールは "プルパーザ" を提供します。プルパーザは必要に応じて文書の DOM アクセス可能な断片を生成することができます。基本概念は、入力 XML のストリームから "イベント" を取り出し (pull し) て処理することです。 SAX とは、コールバックつきのイベント駆動処理モデルを採用しているという点で同様ですが、SAX とは対照的に、プルパーザの使用者には処理が完了するかエラー状態が発生するまで、明示的にストリームからイベントを取り出し、イベントに対しループを回す責任があります。

警告

xml.dom.pulldom モジュールは悪意を持って作成されたデータに対して安全ではありません。信頼できないデータや認証されていないデータをパースする必要がある場合は XML の脆弱性 を参照してください。

バージョン 3.7.1 で変更: SAXパーサーは、デフォルトでセキュリティーを向上させるために、一般的な外部エンティティーをデフォルトでは処理しなくなりました。外部エンティティの処理を有効にするには、次の場所にカスタムパーサーインスタンスを渡します:

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)

以下はプログラム例です:

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())

event は定数で以下の内の一つです:

START_ELEMENT

END_ELEMENT

COMMENT

START_DOCUMENT

END_DOCUMENT

CHARACTERS

PROCESSING_INSTRUCTION

IGNORABLE_WHITESPACE

node は型 xml.dom.minidom.Document、 xml.dom.minidom.Element または xml.dom.minidom.Text のオブジェクトです。

文書はイベントの フラットな 流れとして扱われるため、文書の "木" は暗黙のうちに全て読み込まれ、目的の要素は木の中の深さに依らずに見つけられます。つまり、文書ノードの再帰的な検索のような階層的な問題を考える必要はありません。しかしながら要素の前後関係が重要な場合は、前後関係の状態を維持する (すなわち文章中の任意の点の場所を記憶する) か、 DOMEventStream.expandNode() メソッドを使用して DOM 関連の処理に切り替える必要があります。

class xml.dom.pulldom.PullDom(documentFactory=None)

xml.sax.handler.ContentHandler のサブクラスです。

class xml.dom.pulldom.SAX2DOM(documentFactory=None)

xml.sax.handler.ContentHandler のサブクラスです。

xml.dom.pulldom.parse(stream_or_string, parser=None, bufsize=None)

与えられた入力から DOMEventStream を返します。stream_or_string はファイル名かファイル様オブジェクトのいずれかです。parser は、与えれた場合、 XMLReader オブジェクトでなければなりません。この関数はパーザの文書ハンドラを変えて名前空間のサポートを有効にします。パーザの他の設定 (例えばエンティティリゾルバ) は前もってしておかなければなりません。

XML データを文字列で持っている場合、 parseString() を代わりに使うことができます:

xml.dom.pulldom.parseString(string, parser=None)

(ユニコード) string を表す DOMEventStream を返します。

xml.dom.pulldom.default_bufsize

parse() の bufsize パラメタのデフォルト値です。

この変数の値は parse() を呼び出す前に変更することができます。その場合、その新しい値が有効になります。

DOMEventStream オブジェクト

class xml.dom.pulldom.DOMEventStream(stream, parser, bufsize)

バージョン 3.11 で変更: Support for __getitem__() method has been removed.

getEvent()

event が START_DOCUMENT の場合は event と xml.dom.minidom.Document としての現在の node からなるタプルを、 START_ELEMENT か END_ELEMENT の場合は xml.dom.minidom.Element を、 CHARACTERS の場合は xml.dom.minidom.Text を返します。 expandNode() が呼ばれない限り、現在のノードは子ノードの情報を持ちません。

expandNode(node)

node の全子ノードを node に展開します。例:

from xml.dom import pulldom

xml = '<html><title>Foo</title> <p>Some text <div>and more</div></p> </html>'
doc = pulldom.parseString(xml)
for event, node in doc:
    if event == pulldom.START_ELEMENT and node.tagName == 'p':
        # Following statement only prints '<p/>'
        print(node.toxml())
        doc.expandNode(node)
        # Following statement prints node with all its children '<p>Some text <div>and more</div></p>'
        print(node.toxml())

reset()

xml.sax --- Support for SAX2 parsers

ソースコード: Lib/xml/sax/__init__.py [https://github.com/python/cpython/tree/3.12/Lib/xml/sax/__init__.py]

xml.sax パッケージは Python 用の Simple API for XML (SAX) インターフェースを実装した数多くのモジュールを提供しています。またパッケージには SAX 例外と SAX API 利用者が頻繁に利用するであろう有用な関数群も含まれています。

警告

xml.sax モジュールは悪意を持って作成されたデータに対して安全ではありません。信頼できないデータや認証されていないデータをパースする必要がある場合は XML の脆弱性 を参照してください。

バージョン 3.7.1 で変更: SAXパーサーは、セキュリティーを向上させるために、デフォルトで一般的な外部エンティティーを処理しなくなりました。以前は、パーサーは、DTDおよびエンティティ用にファイルシステムからリモートファイルまたはロードされたローカルファイルをフェッチするためのネットワーク接続を作成していました。この機能は parser オブジェクトと(実) 引数 feature_external_ges の setFeature() メソッドで再度有効にすることができます。

その関数群は以下の通りです:

xml.sax.make_parser(parser_list=[])

SAX XMLReader オブジェクトを生成し、返します。最初に見つかったパーサーが使用されます。parser_list を与える場合、それは create_parser() という名前の関数をもつモジュール名のイテラブルでなければなりません。 parser_list に列挙されているモジュールは、パーサーのデフォルトリストにあるモジュールよりも先に使われます。

バージョン 3.8 で変更: parser_list 引数はリストだけでなく、イテラブルでもよくなりました。

xml.sax.parse(filename_or_stream, handler, error_handler=handler.ErrorHandler())

SAX パーサを生成し、そのパーサをドキュメントの解析に使用します。filename_or_stream として与えられるドキュメントは、ファイル名でもファイルオブジェクトでもかまいません。 handler 引数は SAX ContentHandler のインスタントである必要があります。error_handler が与えられる場合は、 SAX ErrorHandler のインスタンスである必要があります。この引数を省略した場合、全ての例外に対して SAXParseException が発生します。 戻り値はありません。すべての操作は渡される handler によって行われなければなりません。

xml.sax.parseString(string, handler, error_handler=handler.ErrorHandler())

parse() と同様ですが、こちらは引数で受け取ったバッファ string をパースします。 string は str インスタンスか bytes-like object でなければなりません。

バージョン 3.5 で変更: str インスタンスがサポートされました。

典型的な SAX アプリケーションでは3種類のオブジェクト(リーダ、ハンドラ、入力元)が用いられます。ここで言うリーダとはパーサを指しています。つまり、入力元からバイト列または文字列を読み込み、一連のイベントを発生させるコード片のことです。発生したイベントはハンドラ・オブジェクトに割り振られます。言い換えると、リーダがハンドラのメソッドを呼び出すわけです。つまり、 SAX アプリケーションは、リーダ・オブジェクトを作成し、入力元のオブジェクトを作成するか開き、ハンドラ・オブジェクトを作成し、これら3つのオブジェクトを連携させる必要があります。準備の最終段階では、リーダが呼び出され、入力をパースします。パース中には、入力データからの構造イベントや構文イベントに基づいて、ハンドラ・オブジェクトのメソッドが呼び出されます。

これらのオブジェクトでは、インターフェースだけが関係します。通常、これらはアプリケーション自体によってはインスタンス化されません。 Python は明示的なインターフェースの概念を持たないので、インターフェースはクラスとして導入されました。しかし、アプリケーションは、提供されたクラスを継承せずに実装してもかまいません。インターフェース InputSource, Locator, Attributes, AttributesNS, XMLReader はモジュール xml.sax.xmlreader で定義されています。ハンドラインターフェースは xml.sax.handler で定義されています。利便性のため、 InputSource (よく直接インスタンス化されるクラス) とハンドラクラスは xml.sax からもアクセスできます。これらのインターフェースについて下記で説明します。

このほかに xml.sax は次の例外クラスも提供しています。

exception xml.sax.SAXException(msg, exception=None)

XML エラーと警告をカプセル化します。このクラスには XML パーサとアプリケーションで発生するエラーおよび警告の基本的な情報を持たせることができます。また機能追加や地域化のためにサブクラス化することも可能です。なお ErrorHandler で定義されているハンドラがこの例外のインスタンスを受け取ることに注意してください。実際に例外を発生させることは必須でなく、情報のコンテナとして利用されることもあるからです。

インスタンスを作成する際 msg はエラー内容を示す可読データにしてください。オプションの exception 引数は None にするか、パース用コードで捕捉されて情報として渡される例外にしてください。

このクラスはSAX 例外の基底クラスになります。

exception xml.sax.SAXParseException(msg, exception, locator)

パースエラー時に発生する SAXException のサブクラスです。パースエラーに関する情報として、このクラスのインスタンスが SAX ErrorHandler インターフェースのメソッドに渡されます。このクラスは SAXException 同様 SAX Locator インターフェースもサポートしています。

exception xml.sax.SAXNotRecognizedException(msg, exception=None)

SAX XMLReader が認識できない機能やプロパティに遭遇したとき発生させる SAXException のサブクラスです。 SAX アプリケーションや拡張モジュールにおいて同様の目的にこのクラスを利用することもできます。

exception xml.sax.SAXNotSupportedException(msg, exception=None)

SAX XMLReader が要求された機能をサポートしていないとき発生させる SAXException のサブクラスです。 SAX アプリケーションや拡張モジュールにおいて同様の目的にこのクラスを利用することもできます。

参考

SAX: The Simple API for XML [http://www.saxproject.org/]

SAX API 定義に関し中心となっているサイトです。Java による実装とオンライン・ドキュメントが提供されています。実装と SAX API の歴史に関する情報のリンクも掲載されています。

xml.sax.handler モジュール

アプリケーションが提供するオブジェクトのインターフェース定義。

xml.sax.saxutils モジュール

SAX アプリケーション向けの有用な関数群。

xml.sax.xmlreader モジュール

パーサが提供するオブジェクトのインターフェース定義。

SAXException オブジェクト

SAXException 例外クラスは以下のメソッドをサポートしています:

SAXException.getMessage()

エラー状態を示す可読メッセージを返します。

SAXException.getException()

カプセル化した例外オブジェクトまたは None を返します。

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

ソースコード: Lib/xml/sax/handler.py [https://github.com/python/cpython/tree/3.12/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 xml.sax.handler, so that all methods get default implementations.

class xml.sax.handler.ContentHandler

アプリケーションにとって最も重要なメインの SAX コールバック・インターフェースです。このインターフェースで発生するイベントの順序はドキュメント内の情報の順序を反映しています。

class xml.sax.handler.DTDHandler

DTD イベントのハンドラです。

パースされていないエンティティや属性など、基本的なパースに必要な DTD イベントの指定だけを行うインターフェースです。

class xml.sax.handler.EntityResolver

エンティティ解決用の基本インターフェースです。このインターフェースを実装したオブジェクトを作成しパーサに登録することで、パーサはすべての外部エンティティを解決するメソッドを呼び出すようになります。

class xml.sax.handler.ErrorHandler

エラーや警告メッセージをアプリケーションに通知するためにパーサが使用するインターフェースです。このオブジェクトのメソッドが、エラーをただちに例外に変換するか、あるいは別の方法で処理するかの制御をしています。

class xml.sax.handler.LexicalHandler

Interface used by the parser to represent low frequency events which may not be of interest to many applications.

これらのクラスに加え、 xml.sax.handler は機能やプロパティ名のシンボル定数を提供しています。

xml.sax.handler.feature_namespaces

値: "http://xml.org/sax/features/namespaces"

真: 名前空間を処理します。

偽: オプションで名前空間を処理しません (暗黙に名前空間接頭辞も無効にします; デフォルト)。

アクセス: (パース時) 読み込み専用; (パース時以外) 読み書き可

xml.sax.handler.feature_namespace_prefixes

値: "http://xml.org/sax/features/namespace-prefixes"

真: 名前空間宣言で用いられている元々の接頭辞付きの名前と属性を報告します。

偽: 名前空間宣言で用いられている属性を報告しません。オプションで元々の接頭辞付きの名前も報告しません (デフォルト)。

アクセス: (パース時) 読み込み専用; (パース時以外) 読み書き可

xml.sax.handler.feature_string_interning

値: "http://xml.org/sax/features/string-interning"

真: 全ての要素名、接頭辞、属性名、名前空間 URI、ローカル名を組込みの intern 関数を使ってシンボルに登録します。

偽: 名前を必ずしもシンボルに登録しませんが、されるかもしれません (デフォルト)。

アクセス: (パース時) 読み込み専用; (パース時以外) 読み書き可

xml.sax.handler.feature_validation

値: "http://xml.org/sax/features/validation"

真: 全ての妥当性検査エラーを報告します (外部一般エンティティと外部変数エンティティが暗示されます)。

偽: 妥当性検査エラーを報告しません。

アクセス: (パース時) 読み込み専用; (パース時以外) 読み書き可

xml.sax.handler.feature_external_ges

値: "http://xml.org/sax/features/external-general-entities"

真: 全ての外部一般 (テキスト) エンティティを取り込みます。

偽: 外部一般エンティティを取り込みません。

アクセス: (パース時) 読み込み専用; (パース時以外) 読み書き可

xml.sax.handler.feature_external_pes

値: "http://xml.org/sax/features/external-parameter-entities"

真: 外部 DTD サブセットを含む全ての外部変数エンティティを取り込みます。

偽: 外部 DTD サブセットであっても外部変数エンティティを取り込みません。

アクセス: (パース時) 読み込み専用; (パース時以外) 読み書き可

xml.sax.handler.all_features

全機能のリスト。

xml.sax.handler.property_lexical_handler

値: "http://xml.org/sax/properties/lexical-handler"

data type: xml.sax.handler.LexicalHandler (not supported in Python 2)

説明: コメントなど字句解析イベント用のオプション拡張ハンドラ。

アクセス: 読み書き可

xml.sax.handler.property_declaration_handler

値: "http://xml.org/sax/properties/declaration-handler"

データ型: xml.sax.sax2lib.DeclHandler (Python 2 では未サポート)

説明: 表記や未解析エンティティをのぞく DTD 関連イベント用のオプション拡張ハンドラ。

アクセス: 読み書き可

xml.sax.handler.property_dom_node

値: "http://xml.org/sax/properties/dom-node"

データ型: org.w3c.dom.Node (Python 2 では未サポート)

説明: パース時は DOM イテレータならば現在の DOM ノードです。非パース時はイテレートのルート DOM ノードです。

アクセス: (パース時) 読み込み専用; (パース時以外) 読み書き可

xml.sax.handler.property_xml_string

値: "http://xml.org/sax/properties/xml-string"

data type: Bytes

説明: 現在のイベントの元になったリテラル文字列。

アクセス: 読み出し専用

xml.sax.handler.all_properties

既知の全プロパティ名のリスト。

ContentHandler オブジェクト

ContentHandler はアプリケーション側でサブクラス化して利用することが前提になっています。パーサは入力ドキュメントのイベントにより、それぞれに対応する以下のメソッドを呼び出します:

ContentHandler.setDocumentLocator(locator)

アプリケーションにドキュメントイベントの発生位置を指すロケータを与えるためにパーサから呼び出されます。

SAX パーサによるロケータの提供は強く推奨されています(必須ではありません)。もし提供する場合は、DocumentHandler インターフェースのどのメソッドよりも先にこのメソッドが呼び出されるようにしなければなりません。

パーサがエラーを報告しない場合でも、ロケータによってアプリケーションは全てのドキュメント関連イベントの終了位置を知ることが出来ます。通常、アプリケーションは自身のエラー (例えば文字コンテンツがアプリケーションの規則に適合しない場合) を報告するためにこれを使用します。ロケータが返す情報は検索エンジンでの利用にはおそらく不充分です。

ロケータが正しい情報を返すのは、このインターフェースからイベントの呼出しが実行されている間だけです。それ以外のときは使用すべきでありません。

ContentHandler.startDocument()

ドキュメントの開始通知を受け取ります。

SAX パーサはこのインターフェースやDTDHandler のどのメソッド (setDocumentLocator() を除く) よりも先にこのメソッドを一度だけ呼び出します。

ContentHandler.endDocument()

ドキュメントの終了通知を受け取ります。

SAX パーサはこのメソッドを一度だけ呼び出します。パース中に呼び出す最後のメソッドです。パーサは (回復不能なエラーで) パース処理を中断するか、あるいは入力の最後に到達するまでこのメソッドを呼び出しません。

ContentHandler.startPrefixMapping(prefix, uri)

接頭辞と URI 名前空間の関連付けのスコープを開始します。

このイベントからの情報は名前空間処理に必須ではありません。SAX XML リーダは feature_namespaces 機能が有効な場合 (デフォルト)、要素と属性名の接頭辞を自動的に置換します。

しかしながら、接頭辞の自動展開を安全に行えないために、アプリケーションが文字データや属性値の中で接頭辞を使わなければならない場合があります。必要ならば startPrefixMapping() や endPrefixMapping() イベントはアプリケーションにコンテキスト自身の中で接頭辞を展開するための情報を提供します。

startPrefixMapping() と endPrefixMapping() イベントは相互に正しい入れ子関係になることが保証されていないので注意が必要です。すべての startPrefixMapping() は対応する startElement() の前に発生し、 endPrefixMapping() イベントは対応する endElement() の後で発生しますが、その順序は保証されていません。

ContentHandler.endPrefixMapping(prefix)

接頭辞と URI の関連付けのスコープを終了します。

詳しくは startPrefixMapping() を参照してください。このイベントは常に対応する endElement() の後で発生しますが、複数の endPrefixMapping() イベントの順序は特に保証されません。

ContentHandler.startElement(name, attrs)

非名前空間モードでの要素の開始を通知します。

name 引数は要素型の生の XML 1.0 名を文字列として持ち、attrs 引数は要素の属性を持つ Attributes インターフェイス (Attributes インターフェース を参照) のオブジェクトを保持します。 attrs ととして渡されたオブジェクトはパーサに再利用されるかもしれません。そのため、それへの参照を確保するのは属性のコピーを保持する確実な方法ではありません。属性のコピーを保持するには attrs 属性の copy() メソッドを使用してください。

ContentHandler.endElement(name)

非名前空間モードでの要素の終了を通知します。

name 引数は startElement() イベントとまったく同じ要素型名を持ちます。

ContentHandler.startElementNS(name, qname, attrs)

名前空間モードでの要素の開始を通知します。

name 引数は要素型の名前を (uri, localname) というタプルとして持ち、qname 引数は元の文書で使われている生の XML 1.0 名を持ち、要素の属性を持つ AttributesNS インターフェイス (AttributesNS インターフェース を参照) のインスタンスを保持します。名前空間が要素に関連付けられていない場合、name の uri 要素は None です。 attrs ととして渡されたオブジェクトはパーサに再利用されるかもしれません。そのため、それへの参照を確保するのは属性のコピーを保持する確実な方法ではありません。属性のコピーを保持するには attrs 属性の copy() メソッドを使用してください。

feature_namespace_prefixes 機能が有効でなければ、パーサで qname を None に設定することも可能です。

ContentHandler.endElementNS(name, qname)

名前空間モードでの要素の終了を通知します。

name 引数は startElementNS() イベントとまったく同じ要素型を持ちます。 qname 引数も同様です。

ContentHandler.characters(content)

文字データの通知を受け取ります。

パーサはこのメソッドを呼び出して文字データの各チャンクを報告します。SAX パーサは一連の文字データを単一のチャンクとして返す場合と複数のチャンクに分けて返す場合がありますが、ロケータの情報が正しく保たれるように、一つのイベントの文字データは常に同じ外部エンティティのものでなければなりません。

content は文字列、バイト列のどちらでもかまいませんが、expat リーダ・モジュールは常に文字列を生成するようになっています。

注釈

Python XML SIG が提供していた初期 SAX 1 では、このメソッドにもっと JAVA 風のインターフェースが用いられています。しかし Python で採用されている大半のパーサでは古いインターフェースを有効に使うことができないため、よりシンプルなものに変更されました。古いコードを新しいインターフェースに変更するには、古い offset と length パラメータでスライスせずに、content を指定するようにしてください。

ContentHandler.ignorableWhitespace(whitespace)

要素内容中の無視できる空白文字の通知を受け取ります。

妥当性検査を行うパーサはこのメソッドを使って、無視できる空白文字 (W3C XML 1.0 勧告の 2.10 節参照) の各チャンクを報告しなければなりません。妥当性検査をしないパーサもコンテンツモデルの利用とパースが可能な場合、このメソッドを利用することが可能です。

SAX パーサは連続する複数の空白文字を単一のチャンクとして返す場合と複数のチャンクに分けて返す場合があります。しかし、ロケータが有用な情報を提供できるように、単一のイベント中のすべての文字は同じ外部エンティティからのものでなければなりません。

ContentHandler.processingInstruction(target, data)

処理命令の通知を受け取ります。

パーサは処理命令が見つかるたびにこのメソッドを呼び出します。処理命令はメインのドキュメント要素の前や後にも発生することがあるので注意してください。

SAX パーサがこのメソッドを使って XML 宣言 (XML 1.0 のセクション 2.8) やテキスト宣言 (XML 1.0 のセクション 4.3.1) の通知をすることはありません。

ContentHandler.skippedEntity(name)

スキップしたエンティティの通知を受け取ります。

パーサはエンティティをスキップするたびにこのメソッドを呼び出します。妥当性検査をしないプロセッサは (外部 DTD サブセットで宣言されているなどの理由で) 宣言が見当たらないエンティティをスキップします。すべてのプロセッサは feature_external_ges および feature_external_pes 属性の値によっては外部エンティティをスキップすることがあります。

DTDHandler オブジェクト

DTDHandler インスタンスは以下のメソッドを提供します:

DTDHandler.notationDecl(name, publicId, systemId)

表記宣言イベントの通知を扱います。

DTDHandler.unparsedEntityDecl(name, publicId, systemId, ndata)

未パースのエンティティ宣言イベントの通知を扱います。

EntityResolver オブジェクト

EntityResolver.resolveEntity(publicId, systemId)

エンティティのシステム識別子を解決し、文字列として読み込んだシステム識別子あるいは InputSource オブジェクトのいずれかを返します。デフォルトの実装では systemId を返します。

ErrorHandler オブジェクト

Objects with this interface are used to receive error and warning information from the XMLReader. If you create an object that implements this interface, then register the object with your 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 SAXParseException as the only parameter. Errors and warnings may be converted to an exception by raising the passed-in exception object.

ErrorHandler.error(exception)

パーサが回復可能なエラーに遭遇すると呼び出されます。このメソッドが例外を送出しない場合パースは継続されますが、アプリケーションは更なるドキュメント情報を期待すべきではありません。パーサの処理を継続を認めることで入力ドキュメント内の他のエラーを見つけることができます。

ErrorHandler.fatalError(exception)

パーサが回復不能なエラーに遭遇すると呼び出されます。このメソッドが return したとき、パースの停止が求められています。

ErrorHandler.warning(exception)

パーサが軽微な警告情報をアプリケーションに通知するときに呼び出されます。このメソッドが return したときはパースの継続が求められ、ドキュメント情報はアプリケーションに送り続けられます。このメソッドでの例外の送出はパースを終了します。

LexicalHandler Objects

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 'http://xml.org/sax/properties/lexical-handler'.

LexicalHandler.comment(content)

Reports a comment anywhere in the document (including the DTD and outside the document element).

LexicalHandler.startDTD(name, public_id, system_id)

Reports the start of the DTD declarations if the document has an associated DTD.

LexicalHandler.endDTD()

Reports the end of DTD declaration.

LexicalHandler.startCDATA()

Reports the start of a CDATA marked section.

The contents of the CDATA marked section will be reported through the characters handler.

LexicalHandler.endCDATA()

Reports the end of a CDATA marked section.

xml.sax.saxutils --- SAX Utilities

ソースコード: Lib/xml/sax/saxutils.py [https://github.com/python/cpython/tree/3.12/Lib/xml/sax/saxutils.py]

モジュール xml.sax.saxutils には SAX アプリケーションの作成に役立つ多くの関数やクラスも含まれており、直接利用したり、基底クラスとして使うことができます。

xml.sax.saxutils.escape(data, entities={})

文字列データ内の '&', '<', '>' をエスケープします。

オプションの entities 引数に辞書を渡すことで、そのほかの文字列データをエスケープすることも可能です。辞書のキーと値はすべて文字列で、キーは対応する値に置換されます。entities が与えられている場合でも、 '&', '<', '>' は常にエスケープされます。

注釈

This function should only be used to escape characters that can't be used directly in XML. Do not use this function as a general string translation function.

xml.sax.saxutils.unescape(data, entities={})

エスケープされた文字列 '&amp;', '&lt;', '&gt;' を元の文字に戻します。

オプションの entities 引数に辞書を渡すことで、そのほかの文字列データをエスケープ解除することも可能です。辞書のキーと値はすべて文字列で、キーは対応する値に置換されます。entities が与えられている場合でも、'&amp', '&lt;', and '&gt;' は常に元の文字に戻されます。

xml.sax.saxutils.quoteattr(data, entities={})

escape() に似ていますが、 data は属性値の作成に使われます。戻り値はクォート済みの data で、置換する文字の追加も可能です。 quoteattr() はクォートすべき文字を data の文脈から判断し、クォートすべき文字を残さないように文字列をエンコードします。 data の中にシングル・クォート、ダブル・クォートがあれば、両方ともエンコードし、全体をダブルクォートで囲みます。戻り値の文字列はそのままで属性値として利用できます:

>>> print("<element attr=%s>" % quoteattr("ab ' cd \" ef"))
<element attr="ab ' cd &quot; ef">

この関数は参照具象構文を使って、 HTML や SGML の属性値を生成するのに便利です。

class xml.sax.saxutils.XMLGenerator(out=None, encoding='iso-8859-1', short_empty_elements=False)

このクラスは SAX イベントを XML 文書に書き戻すことで ContentHandler インターフェースを実装しています。つまり、 XMLGenerator をコンテントハンドラとして用いることで、パースしている元々の文書を複製することが出来ます。 out にはファイル様オブジェクトでなければなりません。デフォルトは sys.stdout です。 encoding は出力ストリームのエンコーディングで、デフォルトは 'iso-8859-1' です。 short_empty_elements は内容を持たない要素のフォーマットを制御します。 False (デフォルト) の場合、開始/終了タグのペアとなり、 True の場合、1つの空タグになります。

バージョン 3.2 で変更: Added the short_empty_elements parameter.

class xml.sax.saxutils.XMLFilterBase(base)

このクラスは XMLReader とクライアント・アプリケーションのイベント・ハンドラとの間に位置するものとして設計されています。デフォルトでは何もせず、ただリクエストをリーダに、イベントをハンドラに、それぞれ加工せず渡すだけです。しかし、サブクラスでメソッドをオーバーライドすると、イベント・ストリームやリクエストを加工してから渡すように変更可能です。

xml.sax.saxutils.prepare_input_source(source, base='')

This function takes an input source and an optional base URL and returns a fully resolved InputSource object ready for reading. The input source can be given as a string, a file-like object, or an InputSource object; parsers will use this function to implement the polymorphic source argument to their parse() method.

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

ソースコード: Lib/xml/sax/xmlreader.py [https://github.com/python/cpython/tree/3.12/Lib/xml/sax/xmlreader.py]

各 SAX パーサは Python モジュールとして XMLReader インターフェースを実装しており、関数 create_parser() を提供しています。この関数は新たなパーサ・オブジェクトを生成する際、 xml.sax.make_parser() から引数なしで呼び出されます。

class xml.sax.xmlreader.XMLReader

SAX パーサが継承可能な基底クラスです。

class xml.sax.xmlreader.IncrementalParser

入力ソースを一度にパースするのではなく、ドキュメントのチャンクが利用可能になるごとに取得したいことがあります。SAX リーダは通常、ファイル全体を一気に読み込まず、チャンク単位で処理するのですが、全体の処理が終わるまで parse() は返りません。そのため、 parse() の排他的挙動を望まないときにこれらのインターフェースを使用してください。

パーサのインスタンスが作成されるとすぐに、feed メソッドを通じてデータを受け入れられるようになります。パースが完了して閉じるための呼び出しが行われた後、パーサがフィードからまたはパースメソッドを使用して新しいデータを受け入れられるように、reset メソッドが呼び出される必要があります。

これらのメソッドをパース処理の途中で呼び出すことはできません。つまり、パースが実行された後で、パーサから return する前に呼び出す必要があるのです。

デフォルトでは、SAX 2.0 ドライバを書く人のために、このクラスは IncrementalParser の feed、close、reset メソッドを使って XMLReader インターフェースの parse メソッドを実装しています。

class xml.sax.xmlreader.Locator

SAX イベントと文書の位置を関連付けるインターフェースです。locator オブジェクトは DocumentHandler メソッドを呼び出している間だけ正しい結果を返し、それ以外とのときは、予測できない結果を返します。情報を利用できない場合、メソッドは None を返すこともあります。

class xml.sax.xmlreader.InputSource(system_id=None)

XMLReader がエンティティを読み込むために必要な情報をカプセル化します。

このクラスには公開識別子、システム識別子、(場合によっては文字エンコーディング情報を含む) バイト・ストリーム、そしてエンティティの文字ストリームなどの情報が含まれます。

アプリケーションは XMLReader.parse() メソッドでの使用や EntityResolver.resolveEntity の戻り値としてこのオブジェトを作成します。

InputSource はアプリケーションに属します。 XMLReader はアプリケーションから渡された InputSource オブジェクトの変更を許可されていませんが、コピーを作ってそれを変更することは可能です。

class xml.sax.xmlreader.AttributesImpl(attrs)

Attributes インターフェース (Attributes インターフェース 参照) の実装です。これは辞書風のオブジェクトで、 startElement() 内で要素の属性を表示します。最も有用な辞書操作に加え、インターフェースに記述されているメソッドを多数サポートしています。このクラスのオブジェクトはリーダによってインスタンス化されなければなりません。attrs は属性名と属性値の対応付けを含む辞書風オブジェクトでなければなりません。

class xml.sax.xmlreader.AttributesNSImpl(attrs, qnames)

AttributesImpl を名前空間認識型に改良したクラスで、 startElementNS() に渡されます。 AttributesImpl の派生クラスですが、 namespaceURI と localname の2要素のタプルを解釈します。さらに、元の文書に出てくる修飾名を返す多くのメソッドを提供します。このクラスは AttributesNS インターフェース (AttributesNS インターフェース 参照) の実装です。

XMLReader オブジェクト

XMLReader は次のメソッドをサポートします:

XMLReader.parse(source)

入力ソースを処理し、SAX イベントを作成します。 source オブジェクトはシステム識別子 (入力ソースを特定する文字列 -- 一般にファイル名や URL)、 pathlib.Path オブジェクトか path-like オブジェクトまたは InputSource オブジェクトです。 parse() が return したとき、入力データの処理は完了し、パーサ・オブジェクトは破棄ないしリセットされます。

バージョン 3.5 で変更: 文字ストリームがサポートされました。

バージョン 3.8 で変更: path-like オブジェクトのサポートが追加されました。

XMLReader.getContentHandler()

現在の ContentHandler を返します。

XMLReader.setContentHandler(handler)

現在の ContentHandler を設定します。 ContentHandler が設定されていない場合、内容イベントは破棄されます。

XMLReader.getDTDHandler()

現在の DTDHandler を返します。

XMLReader.setDTDHandler(handler)

現在の DTDHandler を返します。 DTDHandler が設定されていな場合、DTD イベントは破棄されます。

XMLReader.getEntityResolver()

現在の EntityResolver を返します。

XMLReader.setEntityResolver(handler)

現在の EntityResolver を返します。 EntityResolver が設定されていない場合、外部エンティティの解決を試行することでエンティティのシステム識別子が開かれます。利用できない場合は失敗します。

XMLReader.getErrorHandler()

現在の ErrorHandler を返します。

XMLReader.setErrorHandler(handler)

現在のエラーハンドラを設定します。ErrorHandler が設定されていない場合、エラーが例外として送出され、警告が表示されます。

XMLReader.setLocale(locale)

アプリケーションにエラーや警告のロケール設定を許可します。

SAX パーサにとって、エラーや警告の地域化は必須ではありません。しかし、パーサが要求されたロケールをサポートしていない場合、SAX 例外を送出しなければなりません。アプリケーションはパースの途中でロケールの変更を要求することができます。

XMLReader.getFeature(featurename)

機能 featurename の現在の設定を返します。その機能が認識できないときは、 SAXNotRecognizedException を送出します。有名な機能名はモジュール xml.sax.handler に列挙されています。

XMLReader.setFeature(featurename, value)

機能名 featurename に値 value を設定します。その機能が認識できないときは、 SAXNotRecognizedException を送出します。また、パーサが指定された機能や設定をサポートしていないときは、 SAXNotSupportedException を送出します。

XMLReader.getProperty(propertyname)

属性名 propertyname の現在の値を返します。その属性が認識できないときは、 SAXNotRecognizedException を送出します。有名な属性名はモジュール xml.sax.handler に列挙されています。

XMLReader.setProperty(propertyname, value)

属性名 propertyname に値 value を設定します。その機能が認識できないときは、 SAXNotRecognizedException を送出します。また、パーサが指定された機能や設定をサポートしていないときは、 SAXNotSupportedException を送出します。

IncrementalParser オブジェクト

IncrementalParser のインスタンスは次の追加メソッドを提供します:

IncrementalParser.feed(data)

data のチャンクを処理します。

IncrementalParser.close()

文書の終端を決定します。文書の適格性を調べ (終端でのみ可能)、ハンドラを起動し、パース時に割り当てた資源を解放します。

IncrementalParser.reset()

このメソッドは close が呼び出された後、新しい文書をパースできるように、パーサをリセットするのに呼び出されます。close 後 reset を呼び出さずに parse や feed を呼び出した場合の戻り値は未定義です。

Locator オブジェクト

Locator のインスタンスは次のメソッドを提供します:

Locator.getColumnNumber()

現在のイベントが開始する列番号を返します。

Locator.getLineNumber()

現在のイベントが開始する行番号を返します。

Locator.getPublicId()

現在の文書イベントの公開識別子を返します。

Locator.getSystemId()

現在のイベントのシステム識別子を返します。

InputSource オブジェクト

InputSource.setPublicId(id)

この InputSource の公開識別子を設定します。

InputSource.getPublicId()

この InputSource の公開識別子を返します。

InputSource.setSystemId(id)

この InputSource のシステム識別子を設定します。

InputSource.getSystemId()

この InputSource のシステム識別子を返します。

InputSource.setEncoding(encoding)

この InputSource の文字エンコーディングを設定します。

エンコーディングは XML エンコーディング宣言として受け入れられる文字列でなければなりません (XML 勧告の 4.3.3 節を参照)。

InputSource も文字ストリームを含んでいた場合、InputSource のエンコーディング属性は無視されます。

InputSource.getEncoding()

この InputSource の文字エンコーディングを取得します。

InputSource.setByteStream(bytefile)

この入力ソースのバイトストリーム (binary file) を設定します。

文字ストリームも指定されている場合、SAX パーサはこのバイトストリームを無視しますが、URI 接続自体を開くときには優先してバイトストリームを使います。

アプリケーションがバイトストリームの文字エンコーディングを知っている場合は、setEncoding メソッドで設定する必要があります。

InputSource.getByteStream()

この入力ソースのバイトストリームを取得します。

getEncoding メソッドは、このバイトストリームの文字エンコーディングを返します。不明なときは None を返します。

InputSource.setCharacterStream(charfile)

この入力ソースの文字ストリーム (text file) を設定します。

文字ストリームが指定された場合、SAX パーサは全バイトストリームを無視し、システム識別子への URI 接続の開始を試みません。

InputSource.getCharacterStream()

この入力ソースの文字ストリームを取得します。

Attributes インターフェース

Attributes オブジェクトは copy()、get()、__contains__()、items()、keys()、values() を含む マッピングプロトコル の一部を実装しています。以下のメソッドも提供されています:

Attributes.getLength()

属性の数を返します。

Attributes.getNames()

属性の名前を返します。

Attributes.getType(name)

属性名 name のタイプを返します。通常は 'CDATA' です。

Attributes.getValue(name)

属性 name の値を返します。

AttributesNS インターフェース

このインターフェースは Attributes インターフェース (Attributes インターフェース 参照) のサブタイプです。 Attributes インターフェースがサポートしているすべてのメソッドは AttributesNS オブジェクトでも利用可能です。

次のメソッドもサポートされています:

AttributesNS.getValueByQName(name)

修飾名の値を返します。

AttributesNS.getNameByQName(name)

修飾名 name に対応する (namespace, localname) のペアを返します。

AttributesNS.getQNameByName(name)

(namespace, localname) のペアに対応する修飾名を返します。

AttributesNS.getQNames()

すべての属性の修飾名を返します。

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

警告

pyexpat モジュールは悪意を持って作成されたデータに対して安全ではありません。信頼できないデータや認証されていないデータをパースする必要がある場合は XML の脆弱性 を参照してください。

xml.parsers.expat モジュールは、検証 (validation) を行わない XML パーザ (parser, 解析器)、Expat への Python インターフェースです。モジュールは一つの拡張型 xmlparser を提供します。これは XMLパーザの現在の状況を表します。一旦 xmlparser オブジェクトを生成すると、オブジェクトの様々な属性をハンドラ関数 (handler function) に設定できます。その後、XML 文書をパーザに入力すると、 XML文書の文字列とマークアップに応じてハンドラ関数が呼び出されます。

このモジュールでは、Expatパーザへのアクセスを提供するために pyexpat モジュールを使用します。 pyexpat モジュールの直接使用は撤廃されています。

このモジュールは、例外を一つと型オブジェクトを一つ提供しています:

exception xml.parsers.expat.ExpatError

Expat がエラーを報告したときに例外を送出します。 Expatのエラーを解釈する上での詳細な情報は、 ExpatError 例外 を参照してください。

exception xml.parsers.expat.error

ExpatError の別名です。

xml.parsers.expat.XMLParserType

ParserCreate() 関数から返された戻り値の型を示します。

xml.parsers.expat モジュールには以下の 2 つの関数が収められています:

xml.parsers.expat.ErrorString(errno)

与えられたエラー番号 errno を解説する文字列を返します。

xml.parsers.expat.ParserCreate(encoding=None, namespace_separator=None)

新しい xmlparser オブジェクトを作成し、返します。 encoding が指定されていた場合、XMLデータで使われている文字列のエンコード名でなければなりません。 Expatは、Pythonのように多くのエンコードをサポートしておらず、またエンコーディングのレパートリを拡張することはできません; サポートするエンコードは、UTF-8, UTF-16, ISO-8859-1 (Latin1), ASCII です。 encoding [1] が指定されると、文書に対する明示的、非明示的なエンコード指定を上書き (override) します。

Expat はオプションで XML 名前空間の処理を行うことができます。これは引数 namespace_separator に値を指定することで有効になります。この値は、1文字の文字列でなければなりません; 文字列が誤った長さを持つ場合には ValueError が送出されます (None は値の省略と見なされます)。名前空間の処理が可能なとき、名前空間に属する要素と属性が展開されます。要素のハンドラである StartElementHandler と EndElementHandler に渡された要素名は、名前空間の URI、名前空間の区切り文字、要素名のローカル部を連結したものになります。名前空間の区切り文字が 0 バイト (chr(0)) の場合、名前空間の URI とローカル部は区切り文字なしで連結されます。

たとえば、namespace_separator に空白文字(' ')がセットされ、次のような文書が解析されるとします:

<?xml version="1.0"?>
<root xmlns    = "http://default-namespace.org/"
      xmlns:py = "http://www.python.org/ns/">
  <py:elem1 />
  <elem2 xmlns="" />
</root>

StartElementHandler は各要素ごとに次のような文字列を受け取ります:

http://default-namespace.org/ root
http://www.python.org/ns/ elem1
elem2

pyexpat が使っている Expat ライブラリの制限により、返される xmlparser インスタンスは単独の XML ドキュメントの解析にしか使えません。それぞれのドキュメントごとに別々のパーサのインスタンスを作るために ParserCreate を呼び出してください。

参考

The Expat XML Parser [http://www.libexpat.org/]

Expatプロジェクトのホームページ。

XMLParser オブジェクト

xmlparser オブジェクトは以下のようなメソッドを持ちます:

xmlparser.Parse(data[, isfinal])

文字列 data の内容を解析し、解析されたデータを処理するための適切な関数を呼び出します。このメソッドを最後に呼び出す時は isfinal を真にしなければなりません; 単体ファイルを細切れに渡して解析出来ることを意味しますが、複数ファイルは扱えません。 data にはいつでも空の文字列を渡せます。

xmlparser.ParseFile(file)

file オブジェクトから読み込んだXMLデータを解析します。 file には read(nbytes) メソッドのみが必要です。このメソッドはデータがなくなった場合に空文字列を返さねばなりません。。

xmlparser.SetBase(base)

(XML) 宣言中のシステム識別子中の相対 URI を解決するための、基底 URI を設定します。相対識別子の解決はアプリケーションに任されます: この値は関数 ExternalEntityRefHandler() や NotationDeclHandler(), UnparsedEntityDeclHandler() に引数 base としてそのまま渡されます。

xmlparser.GetBase()

以前の SetBase() によって設定された基底 URI を文字列の形で返します。 SetBase() が呼ばれていないときには None を返します。

xmlparser.GetInputContext()

現在のイベントを発生させた入力データを文字列として返します。データはテキストの入っているエンティティが持っているエンコードになります。イベントハンドラがアクティブでないときに呼ばれると、戻り値は None となります。

xmlparser.ExternalEntityParserCreate(context[, encoding])

親となるパーザで解析された内容が参照している、外部で解析されるエンティティを解析するために使える "子の" パーザを作成します。 context パラメータは、以下に記すように ExternalEntityRefHandler() ハンドラ関数に渡される文字列でなければなりません。子のパーザは ordered_attributes, specified_attributes が現在のパーザの値に設定されて生成されます。

xmlparser.SetParamEntityParsing(flag)

パラメータエンティティ (外部DTDサブセットを含む) の解析を制御します。 flag の有効な値は、 XML_PARAM_ENTITY_PARSING_NEVER, XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE, XML_PARAM_ENTITY_PARSING_ALWAYS です。 flag の設定をしたら true を返します。

xmlparser.UseForeignDTD([flag])

flag の値をデフォルトのtrueにすると、Expatは代わりのDTDをロードするため、すべての引数に None を設定して ExternalEntityRefHandler を呼び出します。XML文書が文書型定義を持っていなければ、 ExternalEntityRefHandler が呼び出しますが、 StartDoctypeDeclHandler と EndDoctypeDeclHandler は呼び出されません。

flag にfalseを与えると、メソッドが前回呼ばれた時のtrueの設定が解除されますが、他には何も起こりません。

このメソッドは Parse() または ParseFile() メソッドが呼び出される前にだけ呼び出されます;これら2つのメソッドのどちらかが呼び出されたあとにメソッドが呼ばれると、 code に定数 errors.codes[errors.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING] が設定されて例外 ExpatError が送出されます。

xmlparser.SetReparseDeferralEnabled(enabled)

警告

Calling SetReparseDeferralEnabled(False) has security implications, as detailed below; please make sure to understand these consequences prior to using the SetReparseDeferralEnabled method.

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 SetReparseDeferralEnabled(False) disables reparse deferral for the current Expat parser instance, temporarily or altogether. Calling SetReparseDeferralEnabled(True) allows re-enabling reparse deferral.

Note that SetReparseDeferralEnabled() has been backported to some prior releases of CPython as a security fix. Check for availability of SetReparseDeferralEnabled() using hasattr() if used in code running across a variety of Python versions.

Added in version 3.12.3.

xmlparser.GetReparseDeferralEnabled()

Returns whether reparse deferral is currently enabled for the given Expat parser instance.

Added in version 3.12.3.

xmlparser オブジェクトは次のような属性を持ちます:

xmlparser.buffer_size

buffer_text が真の時に使われるバッファのサイズです。この属性に新しい整数値を代入することで違うバッファサイズにできます。サイズが変えられるときにバッファはフラッシュされます。

xmlparser.buffer_text

Setting this to true causes the xmlparser object to buffer textual content returned by Expat to avoid multiple calls to the 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.

xmlparser.buffer_used

buffer_text が利用可能なとき、バッファに保持されたバイト数です。これらのバイトはUTF-8でエンコードされたテキストを表します。この属性は buffer_text が偽の時には意味がありません。

xmlparser.ordered_attributes

この属性をゼロ以外の整数にすると、報告される(XMLノードの) 属性を辞書型ではなくリスト型にします。属性は文書のテキスト中の出現順で示されます。それぞれの属性は、2つのリストのエントリ: 属性名とその値、が与えられます。 (このモジュールの古いバージョンでも、同じフォーマットが使われています。) デフォルトでは、この属性はデフォルトでは偽となりますが、いつでも変更可能です。

xmlparser.specified_attributes

ゼロ以外の整数にすると、パーザは文書のインスタンスで特定される属性だけを報告し、属性宣言から導出された属性は報告しないようになります。この属性が指定されたアプリケーションでは、XMLプロセッサの振る舞いに関する標準に従うために必要とされる (文書型) 宣言によって、どのような付加情報が利用できるのかということについて特に注意を払わなければなりません。デフォルトで、この属性は偽となりますが、いつでも変更可能です。

以下の属性には、 xmlparser オブジェクトで最も最近に起きたエラーに関する値が入っており、また Parse() または ParseFile() メソッドが xml.parsers.expat.ExpatError 例外を送出した際にのみ正しい値となります。

xmlparser.ErrorByteIndex

エラーが発生したバイトのインデクスです。

xmlparser.ErrorCode

エラーを特定する数値によるコードです。この値は ErrorString() に渡したり、 errors オブジェクトで定義された内容と比較できます。

xmlparser.ErrorColumnNumber

エラーの発生したカラム番号です。

xmlparser.ErrorLineNumber

エラーの発生した行番号です。

以下の属性は xmlparser オブジェクトがその時パースしている位置に関する値を保持しています。コールバックがパースイベントを報告している間、これらの値はイベントの生成した文字列の先頭の位置を指し示します。コールバックの外から参照された時には、（対応するコールバックであるかにかかわらず）直前のパースイベントの位置を示します。

xmlparser.CurrentByteIndex

パーサへの入力の、現在のバイトインデックス。

xmlparser.CurrentColumnNumber

パーサへの入力の、現在のカラム番号。

xmlparser.CurrentLineNumber

パーサへの入力の、現在の行番号。

以下に指定可能なハンドラのリストを示します。 xmlparser オブジェクト o にハンドラを指定するには、 o.handlername = func を使用します。 handlername は、以下のリストに挙げた値をとらなければならず、また func は正しい数の引数を受理する呼び出し可能なオブジェクトでなければなりません。引数は特に明記しない限り、すべて文字列となります。

xmlparser.XmlDeclHandler(version, encoding, standalone)

XML 宣言が解析された時に呼ばれます。 XML宣言は XML 勧告の適用バージョン、文書テクストのエンコード、ならびに任意の "standalone" 宣言の (任意の) 宣言です。 version と encoding は文字列で、standalone は文書がスタンドアローンと宣言された場合は 1、スタンドアローンでないと宣言された場合は 0、スタンドアローン節がない場合は -1 です。 Expat のバージョン 1.95.0 以降でのみ使用できます。

xmlparser.StartDoctypeDeclHandler(doctypeName, systemId, publicId, has_internal_subset)

Expatが文書型宣言 (<!DOCTYPE ...)を解析し始めたときに呼び出されます。 doctypeName は、与えられた値がそのまま Expat に提供されます。 systemId と publicId パラメタが指定されている場合、それぞれシステムと公開識別子を与えます。省略する時には None にします。文書が内部的な文書宣言のサブセット (internal document declaration subset) を持つか、サブセット自体の場合、 has_internal_subset は true になります。このハンドラには、Expat version 1.2以上が必要です。

xmlparser.EndDoctypeDeclHandler()

Expatが文書型宣言の解析を終えたときに呼び出されます。このハンドラには、Expat version 1.2以上が必要です。

xmlparser.ElementDeclHandler(name, model)

それぞれの要素型宣言ごとに呼び出されます。 name は要素型の名前であり、 model は内容モデル (content model) の表現です。

xmlparser.AttlistDeclHandler(elname, attname, type, default, required)

ひとつの要素型で宣言される属性ごとに呼び出されます。属性リストの宣言が 3つの属性を宣言したとすると、このハンドラは各属性に1度ずつ、 3度呼び出されます。 elname は要素名であり、これに対して宣言が適用され、 attname が宣言された属性名となります。属性型は文字列で、 type として渡されます。取り得る値は、 'CDATA', 'ID', 'IDREF', ... です。 default は、文書のインスタンスによって属性が指定されていないときに使用されるデフォルト値です。デフォルト値(#IMPLIED values)が存在しないときには None を与えます。文書のインスタンス中に属性値を与える必要のあるときには required が true になります。これにはExpat version 1.95.0 以上が必要です。

xmlparser.StartElementHandler(name, attributes)

要素の開始ごとに呼び出されます。 name は要素名を持つ文字列で、 attributes は要素の属性です。 ordered_attributes が真の場合これはリストです (詳細は ordered_attributes を参照してください)。そうでなければ名前を値に対応させる辞書です。

xmlparser.EndElementHandler(name)

要素の終端を処理するごとに呼び出されます。

xmlparser.ProcessingInstructionHandler(target, data)

処理命令を処理するごとに呼び出されます。

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 StartCdataSectionHandler, EndCdataSectionHandler, and 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 CharacterDataHandler(). Set the buffer_text instance attribute to True to avoid that.

xmlparser.UnparsedEntityDeclHandler(entityName, base, systemId, publicId, notationName)

解析されていない (NDATA) エンティティ宣言を処理するために呼び出されます。このハンドラは Expat ライブラリのバージョン1.2のためだけに存在します; より最近のバージョンでは、代わりに EntityDeclHandler を使用してください (根底にある Expat ライブラリ内の関数は、撤廃されたものであると宣言されています)。

xmlparser.EntityDeclHandler(entityName, is_parameter_entity, value, base, systemId, publicId, notationName)

エンティティ宣言ごとに呼び出されます。パラメタと内部エンティティについて、 value はエンティティ宣言の宣言済みの内容を与える文字列となります; 外部エンティティの時には None となります。解析済みエンティティの場合、 notationName パラメタは None となり、解析されていないエンティティの時には記法 (notation) 名となります。 is_parameter_entity は、エンティティがパラメタエンティティの場合真に、一般エンティティ (general entitiy) の場合には偽になります (ほとんどのアプリケーションでは、一般エンティティのことしか気にする必要がありません)。このハンドラは Expat ライブラリのバージョン1.95.0 以降でのみ使用できます。

xmlparser.NotationDeclHandler(notationName, base, systemId, publicId)

記法の宣言 (notation declaration) で呼び出されます。 notationName, base, systemId, および publicId を与える場合、文字列にします。public な識別子が省略された場合、 publicId は None になります。

xmlparser.StartNamespaceDeclHandler(prefix, uri)

要素が名前空間宣言を含んでいる場合に呼び出されます。名前空間宣言は、宣言が配置されている要素に対して StartElementHandler が呼び出される前に処理されます。

xmlparser.EndNamespaceDeclHandler(prefix)

名前空間宣言を含んでいたエレメントの終了タグに到達したときに呼び出されます。このハンドラは、要素に関する名前空間宣言ごとに、 StartNamespaceDeclHandler とは逆の順番で一度だけ呼び出され、各名前空間宣言のスコープが開始されたことを示します。このハンドラは、要素が終了する際、対応する EndElementHandler が呼ばれた後に呼び出されます。

xmlparser.CommentHandler(data)

コメントで呼び出されます。 data はコメントのテキストで、先頭の '<!- -' と末尾の '- ->' を除きます。

xmlparser.StartCdataSectionHandler()

CDATA セクションの開始時に呼び出されます。CDATA セクションの構文的な開始と終了位置を識別できるようにするには、このハンドラと EndCdataSectionHandler が必要です。

xmlparser.EndCdataSectionHandler()

CDATA セクションの終了時に呼び出されます。

xmlparser.DefaultHandler(data)

XML 文書中で、適用可能なハンドラが指定されていない文字すべてに対して呼び出されます。この文字とは、検出されたことが報告されるが、ハンドラは指定されていないようなコンストラクト (construct) の一部である文字を意味します。

xmlparser.DefaultHandlerExpand(data)

DefaultHandler() と同じですが、内部エンティティの展開を禁止しません。エンティティ参照はデフォルトハンドラに渡されません。

xmlparser.NotStandaloneHandler()

XML 文書がスタンドアロンの文書として宣言されていない場合に呼び出されます。外部サブセットやパラメタエンティティへの参照が存在するが、XML 宣言が XML 宣言中で standalone 変数を yes に設定していない場合に起きます。このハンドラが 0 を返すと、パーザは XML_ERROR_NOT_STANDALONE を発生させます。このハンドラが設定されていなければ、パーザは前述の事態で例外を送出しません。

xmlparser.ExternalEntityRefHandler(context, base, systemId, publicId)

外部エンティティの参照時に呼び出されます。 base は現在の基底 (base) で、以前の SetBase() で設定された値になっています。 public、および system の識別子である、 systemId と publicId が指定されている場合、値は文字列です; public 識別子が指定されていない場合、 publicId は None になります。 context の値は不明瞭なものであり、以下に記述するようにしか使ってはなりません。

外部エンティティが解析されるようにするには、このハンドラを実装しなければなりません。このハンドラは、 ExternalEntityParserCreate(context) を使って適切なコールバックを指定し、子パーザを生成して、エンティティを解析する役割を担います。このハンドラは整数を返さなければなりません; 0 を返した場合、パーザは XML_ERROR_EXTERNAL_ENTITY_HANDLING エラーを送出します。そうでない場合、解析を継続します。

このハンドラが与えられておらず、 DefaultHandler コールバックが指定されていれば、外部エンティティは DefaultHandler で報告されます。

ExpatError 例外

ExpatError 例外はいくつかの興味深い属性を備えています:

ExpatError.code

特定のエラーに対する Expat の内部エラー番号です。 errors.messages 辞書はこれらのエラー番号を Expat のエラーメッセージに対応させます。例えば:

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])

errors モジュールはエラーメッセージ定数と、それらのメッセージをエラーコードに対応させる辞書 codes も提供しています。以下を参照してください。

ExpatError.lineno

エラーが検出された場所の行番号です。最初の行の番号は 1 です。

ExpatError.offset

エラーが発生した場所の行内でのオフセットです。最初のカラムの番号は 0 です。

使用例

以下のプログラムでは、与えられた引数を出力するだけの三つのハンドラを定義しています。

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)

このプログラムの出力は以下のようになります:

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

内容モデルの記述

内容モデルは入れ子になったタプルを使って記述されています。各タプルには以下の 4 つの値が収められています: 型、限定詞 (quantifier)、名前、そして子のタプル。子のタプルは単に内容モデルを記述したものです。

最初の二つのフィールドの値は xml.parsers.expat.model モジュールで定義されている定数です。これらの定数は二つのグループ: モデル型 (model type) グループと限定子 (quantifier) グループ、に取りまとめられます。

以下にモデル型グループにおける定数を示します:

xml.parsers.expat.model.XML_CTYPE_ANY

モデル名で指定された要素は ANY の内容モデルを持つと宣言されます。

xml.parsers.expat.model.XML_CTYPE_CHOICE

指定されたエレメントはいくつかのオプションから選択できるようになっています; (A | B | C) のような内容モデルで用いられます。

xml.parsers.expat.model.XML_CTYPE_EMPTY

EMPTY であると宣言されている要素はこのモデル型を持ちます。

xml.parsers.expat.model.XML_CTYPE_MIXED

xml.parsers.expat.model.XML_CTYPE_NAME

xml.parsers.expat.model.XML_CTYPE_SEQ

順々に続くようなモデルの系列を表すモデルがこのモデル型で表されます。 (A, B, C) のようなモデルで用いられます。

限定子グループにおける定数を以下に示します:

xml.parsers.expat.model.XML_CQUANT_NONE

修飾子 (modifier) が指定されていません。従って A のように、厳密に一つだけです。

xml.parsers.expat.model.XML_CQUANT_OPT

このモデルはオプションです: A? のように、一つか全くないかです。

xml.parsers.expat.model.XML_CQUANT_PLUS

このモデルは (A+ のように) 一つかそれ以上あります。

xml.parsers.expat.model.XML_CQUANT_REP

このモデルは A* のようにゼロ回以上あります。

Expat エラー定数

以下の定数は xml.parsers.expat.errors モジュールで提供されています。これらの定数は、エラーが発生した際に送出される ExpatError 例外オブジェクトのいくつかの属性を解釈する上で便利です。後方互換性の理由で、定数値は数字のエラー コード ではなくエラー メッセージ です。属性を解釈するには code 属性と errors.codes[errors.XML_ERROR_CONSTANT_NAME] を比較します。

errors モジュールには以下の属性があります:

xml.parsers.expat.errors.codes

文字列の記述をエラーコードに対応させる辞書です。

Added in version 3.2.

xml.parsers.expat.errors.messages

数値的なエラーコードを文字列の記述に対応させる辞書です。

Added in version 3.2.

xml.parsers.expat.errors.XML_ERROR_ASYNC_ENTITY

xml.parsers.expat.errors.XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF

属性値中のエンティティ参照が、内部エンティティではなく外部エンティティを参照しました。

xml.parsers.expat.errors.XML_ERROR_BAD_CHAR_REF

文字参照が、XML では正しくない (illegal) 文字を参照しました (例えば 0 や '&#0;')。

xml.parsers.expat.errors.XML_ERROR_BINARY_ENTITY_REF

エンティティ参照が、記法 (notation) つきで宣言されているエンティティを参照したため、解析できません。

xml.parsers.expat.errors.XML_ERROR_DUPLICATE_ATTRIBUTE

一つの属性が一つの開始タグ内に一度より多く使われています。

xml.parsers.expat.errors.XML_ERROR_INCORRECT_ENCODING

xml.parsers.expat.errors.XML_ERROR_INVALID_TOKEN

入力されたバイトが文字に適切に関連付けできない際に送出されます; 例えば、UTF-8 入力ストリームにおける NUL バイト (値 0) などです。

xml.parsers.expat.errors.XML_ERROR_JUNK_AFTER_DOC_ELEMENT

空白以外の何かがドキュメント要素の後にあります。

xml.parsers.expat.errors.XML_ERROR_MISPLACED_XML_PI

入力データの先頭以外の場所に XML 定義が見つかりました。

xml.parsers.expat.errors.XML_ERROR_NO_ELEMENTS

この文書には要素がありません (XML では全ての文書は確実に最上位の要素を正確に一つ持たなければなりません)。

xml.parsers.expat.errors.XML_ERROR_NO_MEMORY

Expat が内部メモリを確保できませんでした。

xml.parsers.expat.errors.XML_ERROR_PARAM_ENTITY_REF

パラメータエンティティが許可されていない場所で見つかりました。

xml.parsers.expat.errors.XML_ERROR_PARTIAL_CHAR

入力に不完全な文字が見つかりました。

xml.parsers.expat.errors.XML_ERROR_RECURSIVE_ENTITY_REF

エンティティ参照中に、同じエンティティへの別の参照が入っていました; おそらく違う名前で参照しているか、間接的に参照しています。

xml.parsers.expat.errors.XML_ERROR_SYNTAX

何らかの仕様化されていない構文エラーに遭遇しました。

xml.parsers.expat.errors.XML_ERROR_TAG_MISMATCH

終了タグが最も内側で開かれている開始タグに一致しません。

xml.parsers.expat.errors.XML_ERROR_UNCLOSED_TOKEN

何らかの (開始タグのような) トークンが閉じられないまま、ストリームの終端や次のトークンに遭遇しました。

xml.parsers.expat.errors.XML_ERROR_UNDEFINED_ENTITY

定義されていないエンティティへの参照が行われました。

xml.parsers.expat.errors.XML_ERROR_UNKNOWN_ENCODING

ドキュメントのエンコードが Expat でサポートされていません。

xml.parsers.expat.errors.XML_ERROR_UNCLOSED_CDATA_SECTION

CDATAセクションが閉じられていません。

xml.parsers.expat.errors.XML_ERROR_EXTERNAL_ENTITY_HANDLING

xml.parsers.expat.errors.XML_ERROR_NOT_STANDALONE

XML文書が "standalone" だと宣言されており NotStandaloneHandler が設定され 0 が返されているにもかかわらず、パーサは "standalone" ではないと判別しました。

xml.parsers.expat.errors.XML_ERROR_UNEXPECTED_STATE

xml.parsers.expat.errors.XML_ERROR_ENTITY_DECLARED_IN_PE

xml.parsers.expat.errors.XML_ERROR_FEATURE_REQUIRES_XML_DTD

その操作を完了するにはDTDのサポートが必要ですが、ExpatがDTDのサポートをしない設定になっています。これは xml.parsers.expat モジュールの標準的なビルドでは報告されません。

xml.parsers.expat.errors.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING

パースが始まったあとで動作の変更が要求されました。これはパースが開始される前にのみ変更可能です。（現在のところ） UseForeignDTD() によってのみ送出されます。

xml.parsers.expat.errors.XML_ERROR_UNBOUND_PREFIX

名前空間の処理を有効すると宣言されていないプレフィックスが見つかります。

xml.parsers.expat.errors.XML_ERROR_UNDECLARING_PREFIX

XML文書はプレフィックスに対応した名前空間宣言を削除しようとしました。

xml.parsers.expat.errors.XML_ERROR_INCOMPLETE_PE

パラメータエンティティは不完全なマークアップを含んでいます。

xml.parsers.expat.errors.XML_ERROR_XML_DECL

XML文書中に要素がありません。

xml.parsers.expat.errors.XML_ERROR_TEXT_DECL

外部エンティティ中のテキスト宣言にエラーがあります。

xml.parsers.expat.errors.XML_ERROR_PUBLICID

パブリックID中に許可されていない文字があります。

xml.parsers.expat.errors.XML_ERROR_SUSPENDED

要求された操作は一時停止されたパーサで行われていますが、許可されていない操作です。このエラーは追加の入力を行なおうとしている場合、もしくはパーサが停止しようとしている場合にも送出されます。

xml.parsers.expat.errors.XML_ERROR_NOT_SUSPENDED

パーサを一時停止しようとしましたが、停止されませんでした。

xml.parsers.expat.errors.XML_ERROR_ABORTED

Pythonアプリケーションには通知されません。

xml.parsers.expat.errors.XML_ERROR_FINISHED

要求された操作で、パース対象となる入力が完了したと判断しましたが、入力は受理されませんでした。このエラーは追加の入力を行なおうとしている場合、もしくはパーサが停止しようとしている場合に送出されます。

xml.parsers.expat.errors.XML_ERROR_SUSPEND_PE

xml.parsers.expat.errors.XML_ERROR_RESERVED_PREFIX_XML

An attempt was made to undeclare reserved namespace prefix xml or to bind it to another namespace URI.

xml.parsers.expat.errors.XML_ERROR_RESERVED_PREFIX_XMLNS

An attempt was made to declare or undeclare reserved namespace prefix xmlns.

xml.parsers.expat.errors.XML_ERROR_RESERVED_NAMESPACE_URI

An attempt was made to bind the URI of one the reserved namespace prefixes xml and xmlns to another namespace prefix.

xml.parsers.expat.errors.XML_ERROR_INVALID_ARGUMENT

Pythonアプリケーションには通知されません。

xml.parsers.expat.errors.XML_ERROR_NO_BUFFER

Pythonアプリケーションには通知されません。

xml.parsers.expat.errors.XML_ERROR_AMPLIFICATION_LIMIT_BREACH

The limit on input amplification factor (from DTD and entities) has been breached.

脚注

[1]

XML 出力に含まれるエンコーディング文字列は適切な規格に従っていなければなりません。例えば、 "UTF-8" は有効ですが、 "UTF8" はそうではありません。https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl と https://www.iana.org/assignments/character-sets/character-sets.xhtml を参照してください。

インターネットプロトコルとサポート

この章で記述されるモジュールは、インターネットプロトコルを実装し、関連技術をサポートします。それらは全てPythonで実装されています。これらのモジュールの大部分は、システム依存のモジュール socket が存在することが必要ですが、これは現在ではほとんどの一般的なプラットフォーム上でサポートされています。ここに概観を示します:

webbrowser --- Convenient web-browser controller

ブラウザコントローラーオブジェクト

wsgiref --- WSGI Utilities and Reference Implementation

wsgiref.util -- WSGI 環境のユーティリティ

wsgiref.headers -- WSGI レスポンスヘッダツール群

wsgiref.simple_server -- シンプルな WSGI HTTP サーバ

wsgiref.validate --- WSGI 準拠チェッカー

wsgiref.handlers -- サーバ／ゲートウェイのベースクラス

wsgiref.types -- WSGI types for static type checking

使用例

urllib --- URL handling modules

urllib.request --- Extensible library for opening URLs

Request オブジェクト

OpenerDirector オブジェクト

BaseHandler オブジェクト

HTTPRedirectHandler オブジェクト

HTTPCookieProcessor オブジェクト

ProxyHandler オブジェクト

HTTPPasswordMgr オブジェクト

HTTPPasswordMgrWithPriorAuth オブジェクト

AbstractBasicAuthHandler オブジェクト

HTTPBasicAuthHandler オブジェクト

ProxyBasicAuthHandler オブジェクト

AbstractDigestAuthHandler オブジェクト

HTTPDigestAuthHandler オブジェクト

ProxyDigestAuthHandler オブジェクト

HTTPHandler オブジェクト

HTTPSHandler オブジェクト

FileHandler オブジェクト

DataHandler オブジェクト

FTPHandler オブジェクト

CacheFTPHandler オブジェクト

UnknownHandler オブジェクト

HTTPErrorProcessor オブジェクト

使用例

レガシーインターフェース

urllib.request の制限事項

urllib.response --- urllib で使用するレスポンスクラス

urllib.parse --- Parse URLs into components

URL の解析

URL parsing security

ASCII エンコードバイト列の解析

構造化された解析結果

URL のクオート

urllib.error --- Exception classes raised by urllib.request

urllib.robotparser --- Parser for robots.txt

http --- HTTP modules

HTTP ステータスコード

HTTP status category

HTTP methods

http.client --- HTTP protocol client

HTTPConnection オブジェクト

HTTPResponse オブジェクト

使用例

HTTPMessage オブジェクト

ftplib --- FTP protocol client

リファレンス

FTP オブジェクト

FTP_TLS オブジェクト

モジュール変数

poplib --- POP3 protocol client

POP3 オブジェクト

POP3 の例

imaplib --- IMAP4 protocol client

IMAP4 オブジェクト

IMAP4 の使用例

smtplib --- SMTP protocol client

SMTP オブジェクト

SMTP 使用例

uuid --- UUID objects according to RFC 4122

コマンドラインからの使用

使用例

Command-Line Example

socketserver --- A framework for network servers

サーバ生成に関するノート

Serverオブジェクト

Request Handler Objects

使用例

socketserver.TCPServer の例

socketserver.UDPServer の例

非同期処理の Mix-in

http.server --- HTTP servers

セキュリティで考慮すべき点

http.cookies --- HTTP state management

Cookieオブジェクト

Morselオブジェクト

使用例

http.cookiejar --- Cookie handling for HTTP clients

CookieJar および FileCookieJar オブジェクト

FileCookieJar のサブクラスと web ブラウザとの連携

CookiePolicy オブジェクト

DefaultCookiePolicy オブジェクト

Cookieオブジェクト

使用例

xmlrpc --- XMLRPC server and client modules

xmlrpc.client --- XML-RPC client access

ServerProxy オブジェクト

DateTime オブジェクト

Binary オブジェクト

Fault オブジェクト

ProtocolError オブジェクト

MultiCall オブジェクト

補助関数

クライアントのサンプル

クライアントとサーバーの利用例

xmlrpc.server --- Basic XML-RPC servers

SimpleXMLRPCServer オブジェクト

SimpleXMLRPCServer の例

CGIXMLRPCRequestHandler

XMLRPC サーバの文書化

DocXMLRPCServer オブジェクト

DocCGIXMLRPCRequestHandler

ipaddress --- IPv4/IPv6 manipulation library

便利なファクトリ関数

IP アドレス

Address オブジェクト

文字列と整数への変換

演算子

比較演算子

算術演算

IP ネットワーク定義

プリフィックス, ネットマスク、ホストマスク

Network オブジェクト

演算子

論理演算子

イテレーション

アドレスのコンテナとしてのネットワーク

インターフェイスオブジェクト

演算子

論理演算子

その他のモジュールレベル関数

Custom Exceptions

webbrowser --- Convenient web-browser controller

ソースコード: Lib/webbrowser.py [https://github.com/python/cpython/tree/3.12/Lib/webbrowser.py]

webbrowser モジュールにはウェブベースのドキュメントを表示するための、とてもハイレベルなインターフェースが定義されています。たいていの環境では、このモジュールの open() を呼び出すだけで正しく動作します。

Unixでは、X11上でグラフィカルなブラウザが選択されますが、グラフィカルなブラウザが利用できなかったり、X11が利用できない場合はテキストモードのブラウザが使われます。もしテキストモードのブラウザが使われたら、ユーザがブラウザから抜け出すまでプロセスの呼び出しはブロックされます。

環境変数 BROWSER が存在する場合、これは os.pathsep で区切られたブラウザのリストとして解釈され、プラットフォームのデフォルトのブラウザリストに先立って順に試みられます。リストの中の値に %s が含まれていれば、 %s を URL に置換したコマンドライン文字列と解釈されます；もし %s が含まれなければ、起動するブラウザの名前として単純に解釈されます。 [1]

非UnixプラットフォームあるいはUnix上でリモートブラウザが利用可能な場合、制御プロセスはユーザがブラウザを終了するのを待ちませんが、ディスプレイにブラウザのウィンドウを表示させたままにします。Unix上でリモートブラウザが利用可能でない場合、制御プロセスは新しいブラウザを立ち上げ、待ちます。

The script webbrowser can be used as a command-line interface for the module. It accepts a URL as the argument. It accepts the following optional parameters: -n opens the URL in a new browser window, if possible; -t opens the URL in a new browser page ("tab"). The options are, naturally, mutually exclusive. Usage example:

python -m webbrowser -t "https://www.python.org"

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. See WebAssemblyプラットフォーム for more information.

以下の例外が定義されています:

exception webbrowser.Error

ブラウザのコントロールエラーが起こると発生する例外。

以下の関数が定義されています:

webbrowser.open(url, new=0, autoraise=True)

デフォルトのブラウザで url を表示します。new が 0 なら、url はブラウザの今までと同じウィンドウで開きます。new が 1 なら、可能であればブラウザの新しいウィンドウが開きます。new が 2 なら、可能であればブラウザの新しいタブが開きます。autoraise が True なら、可能であればウィンドウが前面に表示されます（多くのウィンドウマネージャではこの変数の設定に関わらず、前面に表示されます）。

幾つかのプラットフォームにおいて、ファイル名をこの関数で開こうとすると、OSによって関連付けられたプログラムが起動されます。しかし、この動作はポータブルではありませんし、サポートされていません。

引数 url を指定して 監査イベント webbrowser.open を送出します。

webbrowser.open_new(url)

可能であれば、デフォルトブラウザの新しいウィンドウで url を開きますが、そうでない場合はブラウザのただ１つのウィンドウで url を開きます。

webbrowser.open_new_tab(url)

可能であれば、デフォルトブラウザの新しいページ(「タブ」)で url を開きますが、そうでない場合は open_new() と同様に振る舞います。

webbrowser.get(using=None)

ブラウザの種類 using のコントローラーオブジェクトを返します。もし using が None なら、呼び出した環境に適したデフォルトブラウザのコントローラーを返します。

webbrowser.register(name, constructor, instance=None, *, preferred=False)

ブラウザの種類 name を登録します。ブラウザの種類が登録されたら、 get() でそのブラウザのコントローラーを呼び出すことができます。 instance が指定されなかったり、 None なら、インスタンスが必要な時には constructor がパラメータなしに呼び出されて作られます。 instance が指定されたら、 constructor は呼び出されないので、 None でかまいません。

preferred を True に設定すると、 get() の引数無しの呼び出しの結果が優先的にこのブラウザになります。そうでない場合は、この関数は、変数 BROWSER を設定するか、 get() を空文字列ではない、宣言したハンドラの名前と一致する引数とともに呼び出すときにだけ、役に立ちます。

バージョン 3.7 で変更: preferred キーワード専用引数が追加されました。

いくつかの種類のブラウザがあらかじめ定義されています。このモジュールで定義されている、関数 get() に与えるブラウザの名前と、それぞれのコントローラークラスのインスタンスを以下の表に示します。

Type Name

Class Name

注釈

'mozilla'

Mozilla('mozilla')

'firefox'

Mozilla('mozilla')

'epiphany'

Epiphany('epiphany')

'kfmclient'

Konqueror()

(1)

'konqueror'

Konqueror()

(1)

'kfm'

Konqueror()

(1)

'opera'

Opera()

'links'

GenericBrowser('links')

'elinks'

Elinks('elinks')

'lynx'

GenericBrowser('lynx')

'w3m'

GenericBrowser('w3m')

'windows-default'

WindowsDefault

(2)

'macosx'

MacOSXOSAScript('default')

(3)

'safari'

MacOSXOSAScript('safari')

(3)

'google-chrome'

Chrome('google-chrome')

'chrome'

Chrome('chrome')

'chromium'

Chromium('chromium')

'chromium-browser'

Chromium('chromium-browser')

注釈:

"Konqueror" is the file manager for the KDE desktop environment for Unix, and only makes sense to use if KDE is running. Some way of reliably detecting KDE would be nice; the KDEDIR variable is not sufficient. Note also that the name "kfm" is used even when using the konqueror command with KDE 2 --- the implementation selects the best strategy for running Konqueror.

Windowsプラットフォームのみ。

Only on macOS platform.

Added in version 3.3: Chrome/Chromium のサポートが追加されました。

バージョン 3.12 で変更: Support for several obsolete browsers has been removed. Removed browsers include Grail, Mosaic, Netscape, Galeon, Skipstone, Iceape, and Firefox versions 35 and below.

バージョン 3.11 で非推奨、バージョン 3.13 で削除予定: MacOSX is deprecated, use MacOSXOSAScript instead.

簡単な例を示します:

url = 'https://docs.python.org/'

# Open URL in a new tab, if a browser window is already open.
webbrowser.open_new_tab(url)

# Open URL in new window, raising the window if possible.
webbrowser.open_new(url)

ブラウザコントローラーオブジェクト

ブラウザコントローラーには以下のメソッドが定義されていて、モジュールレベルの便利な 3 つの関数に相当します:

webbrowser.name

System-dependent name for the browser.

controller.open(url, new=0, autoraise=True)

このコントローラーでハンドルされたブラウザで url を表示します。new が 1 なら、可能であればブラウザの新しいウィンドウが開きます。new が 2 なら、可能であればブラウザの新しいページ(「タブ」)が開きます。

controller.open_new(url)

可能であれば、このコントローラーでハンドルされたブラウザの新しいウィンドウで url を開きますが、そうでない場合はブラウザのただ１つのウィンドウで url を開きます。 open_new() の別名。

controller.open_new_tab(url)

可能であれば、このコントローラーでハンドルされたブラウザの新しいページ(「タブ」)で url を開きますが、そうでない場合は open_new() と同じです。

脚注

[1]

ここでブラウザの名前が絶対パスで書かれていない場合は PATH 環境変数で与えられたディレクトリから探し出されます。

wsgiref --- WSGI Utilities and Reference Implementation

ソースコード: Lib/wsgiref [https://github.com/python/cpython/tree/3.12/Lib/wsgiref]

Web Server Gateway Interface (WSGI) は、Web サーバソフトウェアと Python で記述された Web アプリケーションとの標準インターフェースです。標準インターフェースを持つことで、WSGI をサポートするアプリケーションを幾つもの異なる Web サーバで使うことが容易になります。

Web サーバとプログラミングフレームワークの作者だけが、WSGI デザインのあらゆる細部や特例などを知る必要があります。WSGI アプリケーションをインストールしたり、既存のフレームワークを使ったアプリケーションを記述するだけの皆さんは、すべてについて理解する必要はありません。

wsgiref は WSGI 仕様のリファレンス実装で、これは Web サーバやフレームワークに WSGI サポートを加えるのに利用できます。これは WSGI 環境変数やレスポンスヘッダを操作するユーティリティ、 WSGI サーバ実装時のベースクラス、WSGI アプリケーションを提供するデモ用 HTTP サーバ、静的型チェック用の型、それと WSGI サーバとアプリケーションの WSGI 仕様 (PEP 3333 [https://peps.python.org/pep-3333/]) 準拠のバリデーションツールを提供します。

wsgi.readthedocs.io [https://wsgi.readthedocs.io/] に、WSGIに関するさらなる情報と、チュートリアルやその他のリソースへのリンクがあります。

wsgiref.util -- WSGI 環境のユーティリティ

このモジュールは WSGI 環境で使う様々なユーティリティ関数を提供します。 WSGI 環境は PEP 3333 [https://peps.python.org/pep-3333/] で記述されているような HTTP リクエスト変数を含む辞書です。environ パラメータを取るすべての関数は WSGI 準拠の辞書を与えられることを期待しています; 細かい仕様については PEP 3333 [https://peps.python.org/pep-3333/] を、型アノテーションに使える型エイリアスについては WSGIEnvironment を参照してください。

wsgiref.util.guess_scheme(environ)

environ 辞書の HTTPS 環境変数を調べることで wsgi.url_scheme が "http" か "https" のどちらであるべきか推測し、その結果を返します。戻り値は文字列です。

この関数は、CGI や FastCGI のような CGI に似たプロトコルをラップするゲートウェイを作成する場合に便利です。典型的には、それらのプロトコルを提供するサーバが SSL 経由でリクエストを受け取った場合には HTTPS 変数に値 "1", "yes" または "on" を持つでしょう。そのため、この関数はそのような値が見つかった場合には "https" を返し、そうでなければ "http" を返します。

wsgiref.util.request_uri(environ, include_query=True)

リクエスト URI 全体 (オプションでクエリ文字列を含む) を、 PEP 3333 [https://peps.python.org/pep-3333/] の "URL 再構築(URL Reconstruction)" にあるアルゴリズムを使って返します。 include_query が false の場合、クエリ文字列は結果となる文字列には含まれません。

wsgiref.util.application_uri(environ)

PATH_INFO と QUERY_STRING 変数が無視されることを除けば request_uri() に似ています。結果はリクエストによって指定されたアプリケーションオブジェクトのベース URI です。

wsgiref.util.shift_path_info(environ)

PATH_INFO から SCRIPT_NAME に一つの名前をシフトしてその名前を返します。environ 辞書は 変更されます 。PATH_INFO や SCRIPT_NAME のオリジナルをそのまま残したい場合にはコピーを使ってください。

PATH_INFO にパスセグメントが何も残っていなければ、None が返されます。

典型的なこのルーチンの使い方はリクエスト URI のそれぞれの要素の処理で、例えばパスを一連の辞書のキーとして取り扱う場合です。このルーチンは、渡された環境を、ターゲット URL で示される別の WSGI アプリケーションの呼び出しに合うように調整します。例えば、 /foo に WSGI アプリケーションがあったとして、そしてリクエスト URL パスが /foo/bar/baz で、 /foo の WSGI アプリケーションが shift_path_info() を呼んだ場合、これは "bar" 文字列を受け取り、 environ は /foo/bar の WSGI アプリケーションへの受け渡しに適するように更新されます。つまり、 SCRIPT_NAME は /foo から /foo/bar に変わって、 PATH_INFO は /bar/baz から /baz に変化するのです。

PATH_INFO が単に "/" の場合、このルーチンは空の文字列を返し、SCRIPT_NAME の末尾にスラッシュを加えます、これはたとえ空のパスセグメントが通常は無視され、そして SCRIPT_NAME は通常スラッシュで終わる事が無かったとしてもです。これは意図的な振る舞いで、このルーチンでオブジェクト巡回(object traversal) をした場合に /x で終わる URI と /x/ で終わるものをアプリケーションが識別できることを保証するためのものです。

wsgiref.util.setup_testing_defaults(environ)

environ をテスト用に自明なデフォルト値で更新します。

このルーチンは WSGI に必要な様々なパラメータを追加します。そのようなパラメータとして HTTP_HOST 、 SERVER_NAME 、 SERVER_PORT 、 REQUEST_METHOD 、 SCRIPT_NAME 、 PATH_INFO 、そして PEP 3333 [https://peps.python.org/pep-3333/] で定義されている wsgi.* 変数群が含まれます。このルーチンはデフォルト値を提供するだけで、これらの変数の既存設定は一切置きかえません。

このルーチンは、ダミー環境をセットアップすることによって WSGI サーバとアプリケーションのユニットテストを容易にすることを意図しています。これは実際の WSGI サーバやアプリケーションで使うべきではありません。なぜならこのデータは偽物なのです！

使用例:

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('', 8000, simple_app) as httpd:
    print("Serving on port 8000...")
    httpd.serve_forever()

上記の環境用関数に加えて、 wsgiref.util モジュールも以下のようなその他のユーティリティを提供します:

wsgiref.util.is_hop_by_hop(header_name)

'header_name' が RFC 2616 [https://datatracker.ietf.org/doc/html/rfc2616.html] で定義されている HTTP/1.1 の "Hop-by-Hop" ヘッダの場合に True を返します。

class wsgiref.util.FileWrapper(filelike, blksize=8192)

A concrete implementation of the wsgiref.types.FileWrapper protocol used to convert a file-like object to an iterator. The resulting objects are iterables. As the object is iterated over, the optional blksize parameter will be repeatedly passed to the filelike object's read() method to obtain bytestrings to yield. When read() returns an empty bytestring, iteration is ended and is not resumable.

filelike に close() メソッドがある場合、返されたオブジェクトも close() メソッドを持ち、これが呼ばれた場合には filelike オブジェクトの close() メソッドを呼び出します。

使用例:

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)

バージョン 3.11 で変更: Support for __getitem__() method has been removed.

wsgiref.headers -- WSGI レスポンスヘッダツール群

このモジュールは単一のクラス、 Headers を提供し、WSGI レスポンスヘッダの操作をマップに似たインターフェースで便利にします。

class wsgiref.headers.Headers([headers])

headers をラップするマップ風オブジェクトを生成します。これは PEP 3333 [https://peps.python.org/pep-3333/] に定義されるようなヘッダの名前／値のタプルのリストです。 headers のデフォルト値は空のリストです。

Headers objects support typical mapping operations including __getitem__(), get(), __setitem__(), setdefault(), __delitem__() and __contains__(). For each of these methods, the key is the header name (treated case-insensitively), and the value is the first value associated with that header name. Setting a header deletes any existing values for that header, then adds a new value at the end of the wrapped header list. Headers' existing order is generally maintained, with new headers added to the end of the wrapped list.

辞書とは違って、 Headers オブジェクトはラップされたヘッダリストに存在しないキーを取得または削除しようとした場合にもエラーを発生しません。単に、存在しないヘッダの取得は None を返し、存在しないヘッダの削除は何もしません。

Headers オブジェクトは keys() 、 values() 、 items() メソッドもサポートします。複数の値を持つヘッダがある場合には、 keys() と items() で返されるリストは同じキーを一つ以上含むことがあります。 Headers オブジェクトの len() は、その items() の長さと同じであり、ラップされたヘッダリストの長さと同じです。実際、 items() メソッドは単にラップされたヘッダリストのコピーを返しているだけです。

Headers オブジェクトに対して bytes() を呼ぶと、HTTP レスポンスヘッダとして送信するのに適した形に整形されたバイト文字列を返します。それぞれのヘッダはコロンとスペースで区切られた値と共に一列に並んでいます。それぞれの行はキャリッジリターンとラインフィードで終了し、バイト文字列は空行で終了しています。

これらのマッピングインターフェースと整形機能に加えて、 Headers オブジェクトは複数の値を持つヘッダの取得と追加、MIME パラメータでヘッダを追加するための以下のようなメソッド群も持っています:

get_all(name)

指定されたヘッダのすべての値のリストを返します。

返されるリストは、元々のヘッダリストに現れる順、またはこのインスタンスに追加された順に並んでいて、重複を含む場合があります。削除されて加えられたフィールドはすべてヘッダリストの末尾に付きます。与えられた name に対するフィールドが何もなければ、空のリストが返ります。

add_header(name, value, **_params)

(複数の値を持つ可能性のある) ヘッダを、キーワード引数を通じて指定するオプションの MIME パラメータと共に追加します。

name は追加するヘッダフィールドです。このヘッダフィールドに MIME パラメータを設定するためにキーワード引数を使うことができます。それぞれのパラメータは文字列か None でなければいけません。パラメータ中のアンダースコアはダッシュ (-) に変換されます。これは、ダッシュが Python の識別子としては不正なのですが、多くの MIME パラメータはダッシュを含むためです。パラメータ値が文字列の場合、これはヘッダ値のパラメータに name="value" の形で追加されます。この値がもし None の場合、パラメータ名だけが追加されます。（これは値なしの MIME パラメータの場合に使われます。）使い方の例は:

h.add_header('content-disposition', 'attachment', filename='bud.gif')

上記はこのようなヘッダを追加します:

Content-Disposition: attachment; filename="bud.gif"

バージョン 3.5 で変更: headers 引数が任意になりました。

wsgiref.simple_server -- シンプルな WSGI HTTP サーバ

このモジュールは WSGI アプリケーションを提供するシンプルな HTTP サーバです (http.server がベースです)。個々のサーバインスタンスは単一の WSGI アプリケーションを、特定のホストとポート上で提供します。もし一つのホストとポート上で複数のアプリケーションを提供したいならば、 PATH_INFO をパースして個々のリクエストでどのアプリケーションを呼び出すか選択するような WSGI アプリケーションを作る必要があります。（例えば、 wsgiref.util から shift_path_info() を利用します。）

wsgiref.simple_server.make_server(host, port, app, server_class=WSGIServer, handler_class=WSGIRequestHandler)

host と port 上で待機し、 app へのコネクションを受け付ける WSGI サーバを作成します。戻り値は与えられた server_class のインスタンスで、指定された handler_class を使ってリクエストを処理します。 app は PEP 3333 [https://peps.python.org/pep-3333/] で定義されるところの WSGI アプリケーションでなければいけません。

使用例:

from wsgiref.simple_server import make_server, demo_app

with make_server('', 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()

wsgiref.simple_server.demo_app(environ, start_response)

この関数は小規模ながら完全な WSGI アプリケーションで、 "Hello world!" メッセージと、 environ パラメータに提供されているキー／値のペアを含むテキストページを返します。これは WSGI サーバ (wsgiref.simple_server のような) がシンプルな WSGI アプリケーションを正しく実行できるかを確かめるのに便利です。

class wsgiref.simple_server.WSGIServer(server_address, RequestHandlerClass)

WSGIServer インスタンスを作成します。 server_address は (host,port) のタプル、そして RequestHandlerClass はリクエストの処理に使われる http.server.BaseHTTPRequestHandler のサブクラスでなければいけません。

make_server() が細かい調整をやってくれるので、通常はこのコンストラクタを呼ぶ必要はありません。

WSGIServer は http.server.HTTPServer のサブクラスなので、そのすべてのメソッド (serve_forever() や handle_request() のような) が利用できます。 WSGIServer も以下のような WSGI 固有メソッドを提供します:

set_app(application)

呼び出し可能 (callable) な application をリクエストを受け取る WSGI アプリケーションとして設定します。

get_app()

Returns the currently set application callable.

しかしながら、通常はこれらの追加されたメソッドを使う必要はありません。 set_app() は普通は make_server() によって呼ばれ、 get_app() は主にリクエストハンドラインスタンスの便宜上存在するからです。

class wsgiref.simple_server.WSGIRequestHandler(request, client_address, server)

与えられた request （すなわちソケット）の HTTP ハンドラ、 client_address ((host,port) のタプル)、 server (WSGIServer インスタンス) の HTTP ハンドラを作成します。

このクラスのインスタンスを直接生成する必要はありません; これらは必要に応じて WSGIServer オブジェクトによって自動的に生成されます。しかしながら、このクラスをサブクラス化し、 make_server() 関数に handler_class として与えることは可能でしょう。サブクラスにおいてオーバーライドする意味のありそうなものは:

get_environ()

リクエストに対する WSGIEnvironment 辞書を返します。デフォルト実装では WSGIServer オブジェクトの base_environ 辞書属性のコンテンツをコピーし、それから HTTP リクエスト由来の様々なヘッダを追加しています。このメソッド呼び出し毎に、 PEP 3333 [https://peps.python.org/pep-3333/] に指定されている関連する CGI 環境変数をすべて含む新規の辞書を返さなければいけません。

get_stderr()

wsgi.errors ストリームとして使われるオブジェクトを返します。デフォルト実装では単に sys.stderr を返します。

handle()

HTTP リクエストを処理します。デフォルト実装では実際の WGI アプリケーションインターフェースを実装するのに wsgiref.handlers クラスを使ってハンドラインスタンスを作成します。

wsgiref.validate --- WSGI 準拠チェッカー

WSGI アプリケーションのオブジェクト、フレームワーク、サーバまたはミドルウェアの作成時には、その新規のコードを wsgiref.validate を使って準拠の検証をすると便利です。このモジュールは WSGI サーバやゲートウェイと WSGI アプリケーションオブジェクト間の通信を検証する WSGI アプリケーションオブジェクトを作成する関数を提供し、双方のプロトコル準拠をチェックします。

このユーティリティは完全な PEP 3333 [https://peps.python.org/pep-3333/] 準拠を保証するものでないことは注意してください; このモジュールでエラーが出ないことは必ずしもエラーが存在しないことを意味しません。しかしこのモジュールがエラーを出したならば、ほぼ確実にサーバかアプリケーションのどちらかが 100% 準拠ではありません。

このモジュールは lan Bicking の "Python Paste" ライブラリの paste.lint モジュールをベースにしています。

wsgiref.validate.validator(application)

application をラップし、新しい WSGI アプリケーションオブジェクトを返します。返されたアプリケーションは全てのリクエストを元々の application に転送し、application とそれを呼び出すサーバの両方が WSGI 仕様と RFC 2616 [https://datatracker.ietf.org/doc/html/rfc2616.html] の両方に準拠しているかをチェックします。

何らかの非準拠が検出されると、 AssertionError 例外が送出されます; しかし、このエラーがどう扱われるかはサーバ依存であることに注意してください。例えば、 wsgiref.simple_server とその他 wsgiref.handlers ベースのサーバ（エラー処理メソッドが他のことをするようにオーバライドしていないもの）は単純にエラーが発生したというメッセージとトレースバックのダンプを sys.stderr やその他のエラーストリームに出力します。

このラッパーは、疑わしいものの実際には PEP 3333 [https://peps.python.org/pep-3333/] で禁止されていないかもしれない挙動を指摘するために warnings モジュールを使って出力を生成します。これらは Python のコマンドラインオプションや warnings API で抑制されなければ、 sys.stderr (wsgi.errors では ありません 。ただし、たまたま同一のオブジェクトだった場合を除く)に書き出されます。

使用例:

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('', 8000, validator_app) as httpd:
    print("Listening on port 8000....")
    httpd.serve_forever()

wsgiref.handlers -- サーバ／ゲートウェイのベースクラス

このモジュールは WSGI サーバとゲートウェイ実装のベースハンドラクラスを提供します。これらのベースクラスは、CGI 風の環境と、それに加えて入力、出力そしてエラーストリームが与えられることで、WSGI アプリケーションとの通信の大部分を処理します。

class wsgiref.handlers.CGIHandler

sys.stdin、sys.stdout、sys.stderr そして os.environ 経由での CGI ベースの呼び出しです。これは、もしあなたが WSGI アプリケーションを持っていて、これを CGI スクリプトとして実行したい場合に有用です。単に CGIHandler().run(app) を起動してください。app はあなたが起動したい WSGI アプリケーションオブジェクトです。

このクラスは BaseCGIHandler のサブクラスで、これは wsgi.run_once を true、 wsgi.multithread を false、そして wsgi.multiprocess を true にセットし、常に sys と os を、必要な CGI ストリームと環境を取得するために使用します。

class wsgiref.handlers.IISCGIHandler

(IIS 7 以降の) 設定オプションの allowPathInfo や (IIS 7 より前の) メタベースの allowPathInfoForScriptMappings を設定せずに Microsoft の IIS Web サーバにデプロイするときに使う、 CGIHandler クラス以外の専用の選択肢です。

By default, IIS gives a PATH_INFO that duplicates the SCRIPT_NAME at the front, causing problems for WSGI applications that wish to implement routing. This handler strips any such duplicated path.

IIS can be configured to pass the correct PATH_INFO, but this causes another bug where PATH_TRANSLATED is wrong. Luckily this variable is rarely used and is not guaranteed by WSGI. On IIS<7, though, the setting can only be made on a vhost level, affecting all other script mappings, many of which break when exposed to the PATH_TRANSLATED bug. For this reason IIS<7 is almost never deployed with the fix (Even IIS7 rarely uses it because there is still no UI for it.).

There is no way for CGI code to tell whether the option was set, so a separate handler class is provided. It is used in the same way as CGIHandler, i.e., by calling IISCGIHandler().run(app), where app is the WSGI application object you wish to invoke.

Added in version 3.2.

class wsgiref.handlers.BaseCGIHandler(stdin, stdout, stderr, environ, multithread=True, multiprocess=False)

CGIHandler に似ていますが、 sys と os モジュールを使う代わりに CGI 環境と I/O ストリームを明示的に指定します。 multithread と multiprocess の値は、ハンドラインスタンスにより実行されるアプリケーションの wsgi.multithread と wsgi.multiprocess フラグの設定に使われます。

このクラスは SimpleHandler のサブクラスで、HTTP の "本サーバ" でないソフトウェアと使うことを意図しています。もしあなたが Status: ヘッダを HTTP ステータスを送信するのに使うようなゲートウェイプロトコルの実装（CGI、FastCGI、SCGIなど）を書いている場合、おそらく SimpleHandler ではなくこのクラスをサブクラス化するとよいでしょう。

class wsgiref.handlers.SimpleHandler(stdin, stdout, stderr, environ, multithread=True, multiprocess=False)

BaseCGIHandler と似ていますが、HTTP の本サーバと使うためにデザインされています。もしあなたが HTTP サーバ実装を書いている場合、おそらく BaseCGIHandler ではなくこのクラスをサブクラス化するとよいでしょう。

This class is a subclass of BaseHandler. It overrides the __init__(), get_stdin(), get_stderr(), add_cgi_vars(), _write(), and _flush() methods to support explicitly setting the environment and streams via the constructor. The supplied environment and streams are stored in the stdin, stdout, stderr, and environ attributes.

The write() method of stdout should write each chunk in full, like io.BufferedIOBase.

class wsgiref.handlers.BaseHandler

これは WSGI アプリケーションを実行するための抽象ベースクラスです。それぞれのインスタンスは一つの HTTP リクエストを処理します。しかし原理上は複数のリクエスト用に再利用可能なサブクラスを作成することができます。

BaseHandler インスタンスは外部から利用されるたった一つのメソッドを持ちます:

run(app)

指定された WSGI アプリケーション、app を実行します。

その他のすべての BaseHandler のメソッドはアプリケーション実行プロセスでこのメソッドから呼ばれます。したがって、それらは主にそのプロセスのカスタマイズのために存在しています。

以下のメソッドはサブクラスでオーバーライドされなければいけません:

_write(data)

バイト列の data をクライアントへの転送用にバッファします。このメソッドが実際にデータを転送しても OK です: 下部システムが実際にそのような区別をしている場合に効率をより良くするために、 BaseHandler は書き出しとフラッシュ操作を分けているからです。

_flush()

バッファされたデータをクライアントに強制的に転送します。このメソッドは何もしなくても OK です（すなわち、 _write() が実際にデータを送る場合）。

get_stdin()

Return an object compatible with InputStream suitable for use as the wsgi.input of the request currently being processed.

get_stderr()

Return an object compatible with ErrorStream suitable for use as the wsgi.errors of the request currently being processed.

add_cgi_vars()

現在のリクエストの CGI 変数を environ 属性に追加します。

オーバーライドされることの多いメソッド及び属性を以下に挙げます。しかし、このリストは単にサマリであり、オーバーライド可能なすべてのメソッドは含んでいません。カスタマイズした BaseHandler サブクラスを作成しようとする前に docstring やソースコードでさらなる情報を調べてください。

WSGI 環境のカスタマイズのための属性とメソッド:

wsgi_multithread

wsgi.multithread 環境変数で使われる値。 BaseHandler ではデフォルトが true ですが、別のサブクラスではデフォルトで（またはコンストラクタによって設定されて）異なる値を持つことがあります。

wsgi_multiprocess

wsgi.multiprocess 環境変数で使われる値。 BaseHandler ではデフォルトが true ですが、別のサブクラスではデフォルトで（またはコンストラクタによって設定されて）異なる値を持つことがあります。

wsgi_run_once

wsgi.run_once 環境変数で使われる値。 BaseHandler ではデフォルトが false ですが、 CGIHandler はデフォルトでこれを true に設定します。

os_environ

すべてのリクエストの WSGI 環境に含まれるデフォルトの環境変数。デフォルトでは wsgiref.handlers がインポートされた時点の os.environ のコピーですが、サブクラスはクラスまたはインスタンスレベルでそれら自身のものを作ることができます。デフォルト値は複数のクラスとインスタンスで共有されるため、この辞書は読み出し専用と考えるべきだという点に注意してください。

server_software

origin_server 属性が設定されている場合、この属性の値がデフォルトの SERVER_SOFTWARE WSGI 環境変数の設定や HTTP レスポンス中のデフォルトの Server: ヘッダの設定に使われます。これは (BaseCGIHandler や CGIHandler のような) HTTP オリジンサーバでないハンドラでは無視されます。

バージョン 3.3 で変更: "Python" という語は "CPython" や "Jython" などのような個別実装の語に置き換えられました。

get_scheme()

現在のリクエストで使われている URL スキームを返します。デフォルト実装は wsgiref.util の guess_scheme() を使い、現在のリクエストの environ 変数に基づいてスキームが"http" か "https" かを推測します。

setup_environ()

environ 属性を、フル実装 (fully populated) の WSGI 環境に設定します。デフォルトの実装は、上記すべてのメソッドと属性、加えて get_stdin() 、 get_stderr() 、 add_cgi_vars() メソッドと wsgi_file_wrapper 属性を利用します。これは、キーが存在せず、 origin_server 属性が true 値で server_software 属性も設定されている場合に SERVER_SOFTWARE を挿入します。

例外処理のカスタマイズのためのメソッドと属性:

log_exception(exc_info)

exc_info タプルをサーバログに記録します。exc_info は (type, value, traceback) のタプルです。デフォルトの実装は単純にトレースバックをリクエストの wsgi.errors ストリームに書き出してフラッシュします。サブクラスはこのメソッドをオーバーライドしてフォーマットを変更したり出力先の変更、トレースバックを管理者にメールしたりその他適切と思われるいかなるアクションも取ることができます。

traceback_limit

デフォルトの log_exception() メソッドで出力されるトレースバック出力に含まれる最大のフレーム数です。 None ならば、すべてのフレームが含まれます。

error_output(environ, start_response)

このメソッドは、ユーザに対してエラーページを出力する WSGI アプリケーションです。これはクライアントにヘッダが送出される前にエラーが発生した場合にのみ呼び出されます。

このメソッドは sys.exception() を使って現在のエラーにアクセスでき、その情報はこれを呼ぶときに start_response に渡すべきです (PEP 3333 [https://peps.python.org/pep-3333/] の "Error Handling" セクションに記述があります)。

デフォルト実装は単に error_status 、 error_headers 、 error_body 属性を出力ページの生成に使います。サブクラスではこれをオーバーライドしてもっと動的なエラー出力をすることができます。

しかし、セキュリティの観点からは診断をあらゆるユーザに吐き出すことは推奨されないことに気をつけてください; 理想的には、診断的な出力を有効にするには何らかの特別なことをする必要があるようにすべきで、これがデフォルト実装では何も含まれていない理由です。

error_status

エラーレスポンスで使われる HTTP ステータスです。これは PEP 3333 [https://peps.python.org/pep-3333/] で定義されているステータス文字列です; デフォルトは 500 コードとメッセージです。

error_headers

エラーレスポンスで使われる HTTP ヘッダです。これは PEP 3333 [https://peps.python.org/pep-3333/] で述べられているような、 WSGI レスポンスヘッダ ((name, value) タプル) のリストであるべきです。デフォルトのリストはコンテントタイプを text/plain にセットしているだけです。

error_body

エラーレスポンスボディ。これは HTTP レスポンスのボディバイト文字列であるべきです。これはデフォルトではプレーンテキストで "A server error occurred. Please contact the administrator." です。

PEP 3333 [https://peps.python.org/pep-3333/] の "オプションのプラットフォーム固有のファイルハンドリング" 機能のためのメソッドと属性:

wsgi_file_wrapper

A wsgi.file_wrapper factory, compatible with wsgiref.types.FileWrapper, or None. The default value of this attribute is the wsgiref.util.FileWrapper class.

sendfile()

オーバーライドしてプラットフォーム固有のファイル転送を実装します。このメソッドはアプリケーションの戻り値が wsgi_file_wrapper 属性で指定されたクラスのインスタンスの場合にのみ呼ばれます。これはファイルの転送が成功できた場合には true を返して、デフォルトの転送コードが実行されないようにするべきです。このデフォルトの実装は単に false 値を返します。

その他のメソッドと属性:

origin_server

この属性はハンドラの _write() と _flush() が、特別に Status: ヘッダに HTTP ステータスを求めるような CGI 風のゲートウェイプロトコル経由でなく、クライアントと直接通信をするような場合には true 値に設定されているべきです。

この属性のデフォルト値は BaseHandler では true ですが、 BaseCGIHandler と CGIHandler では false です。

http_version

origin_server が true の場合、この文字列属性はクライアントへのレスポンスセットの HTTP バージョンの設定に使われます。デフォルトは "1.0" です。

wsgiref.handlers.read_environ()

Transcode CGI variables from os.environ to PEP 3333 [https://peps.python.org/pep-3333/] "bytes in unicode" strings, returning a new dictionary. This function is used by CGIHandler and IISCGIHandler in place of directly using os.environ, which is not necessarily WSGI-compliant on all platforms and web servers using Python 3 -- specifically, ones where the OS's actual environment is Unicode (i.e. Windows), or ones where the environment is bytes, but the system encoding used by Python to decode it is anything other than ISO-8859-1 (e.g. Unix systems using UTF-8).

If you are implementing a CGI-based handler of your own, you probably want to use this routine instead of just copying values out of os.environ directly.

Added in version 3.2.

wsgiref.types -- WSGI types for static type checking

This module provides various types for static type checking as described in PEP 3333 [https://peps.python.org/pep-3333/].

Added in version 3.11.

class wsgiref.types.StartResponse

A typing.Protocol describing start_response() [https://peps.python.org/pep-3333/#the-start-response-callable] callables (PEP 3333 [https://peps.python.org/pep-3333/]).

wsgiref.types.WSGIEnvironment

A type alias describing a WSGI environment dictionary.

wsgiref.types.WSGIApplication

A type alias describing a WSGI application callable.

class wsgiref.types.InputStream

A typing.Protocol describing a WSGI Input Stream [https://peps.python.org/pep-3333/#input-and-error-streams].

class wsgiref.types.ErrorStream

A typing.Protocol describing a WSGI Error Stream [https://peps.python.org/pep-3333/#input-and-error-streams].

class wsgiref.types.FileWrapper

A typing.Protocol describing a file wrapper [https://peps.python.org/pep-3333/#optional-platform-specific-file-handling]. See wsgiref.util.FileWrapper for a concrete implementation of this protocol.

使用例

これは動作する "Hello World" WSGIアプリケーションです:

"""
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()

Example of a WSGI application serving the current directory, accept optional directory and port number (default: 8000) on the command line:

"""
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_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()

urllib --- URL handling modules

ソースコード: Lib/urllib/ [https://github.com/python/cpython/tree/3.12/Lib/urllib/]

urllib は URL を扱う幾つかのモジュールを集めたパッケージです:

urllib.request は URL を開いて読むためのモジュールです

urllib.error は urllib.request が発生させる例外を持っています

urllib.parse は URL をパースするためのモジュールです

urllib.robotparser は robots.txt ファイルをパースするためのモジュールです

urllib.request --- Extensible library for opening URLs

ソースコード: Lib/urllib/request.py [https://github.com/python/cpython/tree/3.12/Lib/urllib/request.py]

urllib.request モジュールは基本的な認証、暗号化認証、リダイレクション、Cookie、その他の介在する複雑なアクセス環境において (大抵は HTTP で) URL を開くための関数とクラスを定義します。

参考

より高水準のHTTPクライアントインターフェースとして Requestsパッケージ [https://requests.readthedocs.io/en/master/] がお奨めです。

警告

On macOS it is unsafe to use this module in programs using os.fork() because the getproxies() implementation for macOS uses a higher-level system API. Set the environment variable no_proxy to * to avoid this problem (e.g. os.environ["no_proxy"] = "*").

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. See WebAssemblyプラットフォーム for more information.

urllib.request モジュールでは以下の関数を定義しています:

urllib.request.urlopen(url, data=None, [timeout, ]*, cafile=None, capath=None, cadefault=False, context=None)

Open url, which can be either a string containing a valid, properly encoded URL, or a Request object.

data はサーバーに送信する追加データを指定するオブジェクトであるか None である必要があります。詳細は Request を確認してください。

urllib.request モジュールは HTTP/1.1 を使用し、その HTTP リクエストに Connection:close ヘッダーを含みます。

任意引数 timeout には接続開始などのブロックする操作におけるタイムアウト時間を秒数で指定します (指定されなかった場合、グローバルのデフォルトタイムアウト時間が利用されます)。この引数は、 HTTP, HTTPS, FTP 接続でのみ有効です。

context を指定する場合は、様々な SSL オプションを記述する ssl.SSLContext インスタンスでなければなりません。詳細は HTTPSConnection を参照してください。

The optional cafile and capath parameters specify a set of trusted CA certificates for HTTPS requests. cafile should point to a single file containing a bundle of CA certificates, whereas capath should point to a directory of hashed certificate files. More information can be found in ssl.SSLContext.load_verify_locations().

The cadefault parameter is ignored.

この関数は常にプロパティ url、 headers、および status を持ち、 コンテキストマネージャ として動作するオブジェクトを返します。これらのプロパティに関する詳細は urllib.response.addinfourl を確認してください。

HTTP および HTTPS URL の場合、この関数は、わずかに修正された http.client.HTTPResponse オブジェクトを返します。上記の3つの新しいメソッドに加えて、 msg 属性が HTTPResponse のドキュメンテーションで指定されているレスポンスヘッダーの代わりに reason 属性 --- サーバーから返された reason フレーズ --- と同じ情報を含んでいます。

FTP 、ファイルおよびデータ URL 、レガシーな URLopener や FancyURLopener によって明示的に扱われるリクエストの場合、この関数は urllib.response.addinfourl オブジェクトを返します。

プロトコルエラー発生時は URLError を送出します。

どのハンドラもリクエストを処理しなかった場合には None を返すことがあるので注意してください (デフォルトでインストールされる グローバルハンドラの OpenerDirector は、 UnknownHandler を使って上記の問題が起きないようにしています)。

In addition, if proxy settings are detected (for example, when a *_proxy environment variable like http_proxy is set), ProxyHandler is default installed and makes sure the requests are handled through the proxy.

Python 2.6 以前のレガシーな urllib.urlopen 関数は廃止されました。urllib.request.urlopen() が過去の urllib2.urlopen に相当します。urllib.urlopen において辞書型オブジェクトで渡していたプロキシの扱いは、ProxyHandler オブジェクトを使用して取得できます。

引数 fullurl, data, headers, method を指定して 監査イベント urllib.Request` を送出します。

バージョン 3.2 で変更: cafile および capath が追加されました。

HTTPS virtual hosts are now supported if possible (that is, if ssl.HAS_SNI is true).

data にイテラブルなオブジェクトを指定できるようになりました。

バージョン 3.3 で変更: cadefault が追加されました。

バージョン 3.4.3 で変更: context が追加されました。

バージョン 3.10 で変更: HTTPS connection now send an ALPN extension with protocol indicator http/1.1 when no context is given. Custom context should set ALPN protocols with set_alpn_protocols().

バージョン 3.6 で非推奨: cafile, capath and cadefault are deprecated in favor of context. Please use ssl.SSLContext.load_cert_chain() instead, or let ssl.create_default_context() select the system's trusted CA certificates for you.

urllib.request.install_opener(opener)

指定された OpenerDirector のインスタンスを、デフォルトで利用されるグローバルの opener としてインストールします。 opener のインストールは、 urlopen にその opener を使って欲しいとき以外必要ありません。普段は単に urlopen() の代わりに OpenerDirector.open() を利用してください。この関数は引数が本当に OpenerDirector のインスタンスであるかどうかはチェックしません。適切なインターフェースを持った任意のクラスを利用することができます。

urllib.request.build_opener([handler, ...])

与えられた順番に URL ハンドラを連鎖させる OpenerDirector のインスタンスを返します。 handler は BaseHandler または BaseHandler のサブクラスのインスタンスのどちらかです (どちらの場合も、コンストラクトは引数無しで呼び出せるようになっていなければなりません) 。クラス ProxyHandler (proxy 設定が検出された場合), UnknownHandler, HTTPHandler, HTTPDefaultErrorHandler, HTTPRedirectHandler, FTPHandler, FileHandler, HTTPErrorProcessor については、そのクラスのインスタンスか、そのサブクラスのインスタンスが handler に含まれていない限り、 handler よりも先に連鎖します。

Python が SSL をサポートするように設定してインストールされている場合 (すなわち、 ssl モジュールを import できる場合) HTTPSHandler も追加されます。

BaseHandler サブクラスでも handler_order メンバー変数を変更して、ハンドラーリスト内での場所を変更できます。

urllib.request.pathname2url(path)

ローカルシステムにおける記法で表されたパス名 path をURL におけるパス部分の形式に変換します。これは完全な URL を生成するわけではありません。戻り値は quote() 関数によってクオートされています。

urllib.request.url2pathname(path)

URL の、パーセントエンコードされたパス部分 path をローカルシステムの記法に変換します。これは完全な URL を受け付けません。path のデコードには unquote() 関数を使用します。

urllib.request.getproxies()

このヘルパー関数はスキーマからプロキシサーバーのURLへのマッピングを行う辞書を返します。この関数はまず、どのOSでも最初に <scheme>_proxy という名前の環境変数を大文字小文字を区別せずにスキャンします。そこで見つからなかった場合、 macOS の場合は macOS システム環境設定を、 Windows の場合はシステムレジストリを参照します。もし小文字と大文字の環境変数が両方存在する (そして値が一致しない) なら、小文字の環境変数が優先されます。

注釈

もし環境変数 REQUEST_METHOD が設定されていたら (これは通常スクリプトが CGI 環境で動いていることを示しています)、環境変数 HTTP_PROXY (大文字の _PROXY) は無視されます。その理由は、クライアントが "Proxy:" HTTP ヘッダーを使ってこの環境変数を注入できるからです。もし CGI 環境で HTTP プロキシを使う必要があれば、 ProxyHandler を明示的に使用するか、環境変数名を小文字にしてください (あるいは、少なくともサフィックスを _proxy にしてください) 。

以下のクラスが提供されています:

class urllib.request.Request(url, data=None, headers={}, origin_req_host=None, unverifiable=False, method=None)

このクラスは URL リクエストを抽象化したものです。

url should be a string containing a valid, properly encoded URL.

data must be an object specifying additional data to send to the server, or None if no such data is needed. Currently HTTP requests are the only ones that use data. The supported object types include bytes, file-like objects, and iterables of bytes-like objects. If no Content-Length nor Transfer-Encoding header field has been provided, HTTPHandler will set these headers according to the type of data. Content-Length will be used to send bytes objects, while Transfer-Encoding: chunked as specified in RFC 7230 [https://datatracker.ietf.org/doc/html/rfc7230.html], Section 3.3.1 will be used to send files and other iterables.

HTTP POST リクエストメソッドでは data は標準の application/x-www-form-urlencoded 形式のバッファーでなければなりません。 urllib.parse.urlencode() 関数は、マップ型あるいは 2 タプルのシーケンスを取り、この形式の ASCII 文字列を返します。これは data パラメーターとして使用される前に bytes 型にエンコードされなければなりません。

headers は辞書でなければなりません。この辞書は add_header() を辞書のキーおよび値を引数として呼び出した時と同じように扱われます。この引数は、多くの場合ブラウザーが何であるかを特定する User-Agent ヘッダーの値を "偽装" するために用いられます。これは一部の HTTP サーバーが、スクリプトからのアクセスを禁止するために一般的なブラウザーの User-Agent ヘッダーしか許可しないためです。例えば、 Mozilla Firefox は User-Agent に "Mozilla/5.0 (X11; U; Linux i686) Gecko/20071127 Firefox/2.0.0.11" のように設定し、 urllib はデフォルトで "Python-urllib/2.6" (Python 2.6の場合) と設定します。headersのすべてのキーはキャメルケースで送信されます。

An appropriate Content-Type header should be included if the data argument is present. If this header has not been provided and data is not None, Content-Type: application/x-www-form-urlencoded will be added as a default.

次の2つの引数は、サードパーティの HTTP クッキーを正しく扱いたい場合にのみ関係してきます:

origin_req_host は、 RFC 2965 [https://datatracker.ietf.org/doc/html/rfc2965.html] で定義されている元のトランザクションにおけるリクエストホスト (request-host of the origin transaction) です。デフォルトの値は http.cookiejar.request_host(self) です。この値は、ユーザーによって開始された元々のリクエストにおけるホスト名や IP アドレスです。例えば、もしリクエストがある HTML ドキュメント内の画像を指していれば、この値は画像を含んでいるページへのリクエストにおけるリクエストホストになるはずです。

unverifiable は、 RFC 2965 [https://datatracker.ietf.org/doc/html/rfc2965.html] の定義において、該当するリクエストが証明不能 (unverifiable) であるかどうかを示します。デフォルトの値は False です。証明不能なリクエストとは、ユーザが受け入れの可否を選択できないような URL を持つリクエストのことです。例えば、リクエストが HTML ドキュメント中の画像であり、ユーザがこの画像を自動的に取得するか どうかを選択できない場合には、証明不能フラグは True になります。

method は使用される HTTP リクエストメソッド (例: 'HEAD') を示す文字列でなければなりません。もし与えられた場合、この値は属性 method に格納され、 get_method() で使用されます。デフォルトは data が None であれば 'GET' で、そうでなければ 'POST' です。サブクラスは method 属性をクラス自身に設定して、異なるデフォルトメソッドを示すことができます。

注釈

The request will not work as expected if the data object is unable to deliver its content more than once (e.g. a file or an iterable that can produce the content only once) and the request is retried for HTTP redirects or authentication. The data is sent to the HTTP server right away after the headers. There is no support for a 100-continue expectation in the library.

バージョン 3.3 で変更: 引数 Request.method が Request クラスに追加されました。

バージョン 3.4 で変更: Request.method のデフォルト値はクラスレベルで指定されることがあります。

バージョン 3.6 で変更: Do not raise an error if the Content-Length has not been provided and data is neither None nor a bytes object. Fall back to use chunked transfer encoding instead.

class urllib.request.OpenerDirector

OpenerDirector クラスは、 BaseHandler の連鎖的に呼び出して URL を開きます。このクラスはハンドラをどのように連鎖させるか、またどのようにエラーをリカバリするかを管理します。

class urllib.request.BaseHandler

このクラスはハンドラ連鎖に登録される全てのハンドラがベースとしているクラスです -- このクラスでは登録のための単純なメカニズムだけを扱います。

class urllib.request.HTTPDefaultErrorHandler

HTTP エラーレスポンスのデフォルトハンドラーを定義するクラスです; すべてのレスポンスは HTTPError 例外に変換されます。

class urllib.request.HTTPRedirectHandler

リダイレクションを扱うクラスです。

class urllib.request.HTTPCookieProcessor(cookiejar=None)

HTTP Cookie を扱うためのクラスです。

class urllib.request.ProxyHandler(proxies=None)

このクラスはプロキシを通過してリクエストを送らせます。引数 proxies を与える場合、プロトコル名からプロキシの URL へ対応付ける辞書でなくてはなりません。標準では、プロキシのリストを環境変数 <protocol>_proxy から読み出します。プロキシ環境変数が設定されていない場合は、 Windows 環境では、 レジストリのインターネット設定セクションからプロキシ設定を手に入れ、 macOS 環境では、 macOS システム設定フレームワーク (System Configuration Framework) からプロキシ情報を取得します。

自動検出されたproxyを無効にするには、空の辞書を渡してください。

no_proxy 環境変数は、proxyを利用せずにアクセスするべきホストを指定するために利用されます。設定する場合は、カンマ区切りの、ホストネーム suffix のリストで、オプションとして :port を付けることができます。例えば、 cern.ch,ncsa.uiuc.edu,some.host:8080.

注釈

変数 REQUEST_METHOD が設定されている場合、 HTTP_PROXY は無視されます; getproxies() のドキュメンテーションを参照してください。

class urllib.request.HTTPPasswordMgr

(realm, uri) -> (user, password) の対応付けデータベースを保持します。

class urllib.request.HTTPPasswordMgrWithDefaultRealm

(realm, uri) -> (user, password) の対応付けデータベースを保持します。レルム None はその他諸々のレルムを表し、他のレルムが該当しない場合に検索されます。

class urllib.request.HTTPPasswordMgrWithPriorAuth

uri -> is_authenticated マッピングのデータベースも持つ HTTPPasswordMgrWithDefaultRealm のバリエーションです。最初に 401 レスポンスを待つのではなく直ちに認証情報を送るときの条件を判断するために、 BasicAuth ハンドラによって使われます。

Added in version 3.5.

class urllib.request.AbstractBasicAuthHandler(password_mgr=None)

これは、リモートホストとプロキシの両方に対して HTTP 認証を行うことを助ける mixin クラスです。 password_mgr は、もし与えられたら HTTPPasswordMgr と互換性のあるオブジェクトでなければなりません; サポートすべきインターフェースに関する情報は HTTPPasswordMgr オブジェクト 節を参照してください。もし passwd_mgr が is_authenticated と update_authenticated メソッドも提供するなら (HTTPPasswordMgrWithPriorAuth オブジェクト を参照)、ハンドラは与えられた URI に対する is_authenticated の結果を用いてリクエストにおいて認証情報を送るかどうかを決定します。もし is_authenticated がその URI に対して True を返すなら、認証情報が送られます。 is_authenticated が False なら認証情報は送られません。そして、もし 401 レスポンスを受け取ったら、認証情報を付けて改めてリクエストが送信されます。もし認証が成功したら、それ以降その URI またはその親 URI に対して行われるリクエストが認証情報を自動的に含むように、 URI に対して is_authenticated を True に設定するために update_authenticated が呼ばれます。

Added in version 3.5: is_authenticated サポートが追加されました。

class urllib.request.HTTPBasicAuthHandler(password_mgr=None)

遠隔ホストとの間での認証を扱います。 password_mgr を与える場合、 HTTPPasswordMgr と互換性がなければなりません; 互換性のためにサポートしなければならないインターフェースについての情報はセクション HTTPPasswordMgr オブジェクト を参照してください。HTTPBasicAuthHandler は、間違った認証スキーマが与えられると ValueError を送出します。

class urllib.request.ProxyBasicAuthHandler(password_mgr=None)

プロキシとの間での認証を扱います。 password_mgr を与える場合、 HTTPPasswordMgr と互換性が なければなりません; 互換性のためにサポートしなければならないインターフェースについての情報はセクション HTTPPasswordMgr オブジェクト を参照してください。

class urllib.request.AbstractDigestAuthHandler(password_mgr=None)

このクラスはHTTP 認証を補助するための混ぜ込みクラス (mixin class) です。遠隔ホストとプロキシの両方に対応しています。 password_mgr を与える場合、 HTTPPasswordMgr と互換性がなければなりません; 互換性のためにサポートしなければならないインターフェースについての情報はセクション HTTPPasswordMgr オブジェクト を参照してください。

class urllib.request.HTTPDigestAuthHandler(password_mgr=None)

リモートホストとの認証を扱います。password_mgr を与える場合、HTTPPasswordMgr と互換性のあるものでなければなりません。サポートしなければならないインターフェースについての情報は HTTPPasswordMgr オブジェクト 節を参照してください。Digest 認証ハンドラーと Basic 認証ハンドラーの両方が追加された場合、常に Digest 認証を先に試みます。Digest 認証が 40x のレスポンスを再び返すと、Basic 認証ハンドラーに送信されます。このハンドラーメソッドは、Digest および Basic 以外の認証スキームが存在する場合は ValueError を送出します。

バージョン 3.3 で変更: 未サポートの認証スキームでは ValueError を送出するようになりました。

class urllib.request.ProxyDigestAuthHandler(password_mgr=None)

プロキシとの間での認証を扱います。 password_mgr を与える場合、 HTTPPasswordMgr と互換性が なければなりません; 互換性のためにサポートしなければならないインターフェースについての情報はセクション HTTPPasswordMgr オブジェクト を参照してください。

class urllib.request.HTTPHandler

HTTP の URL を開きます。

class urllib.request.HTTPSHandler(debuglevel=0, context=None, check_hostname=None)

HTTPS で URL を開きます。context および check_hostname は http.client.HTTPSConnection のものと同じ意味です。

バージョン 3.2 で変更: context および check_hostname が追加されました。

class urllib.request.FileHandler

ローカルファイルを開きます。

class urllib.request.DataHandler

data URL を開きます。

Added in version 3.4.

class urllib.request.FTPHandler

FTP の URL を開きます。

class urllib.request.CacheFTPHandler

FTP の URL を開きます。遅延を最小限にするために、開かれている FTP 接続に対するキャッシュを保持します。

class urllib.request.UnknownHandler

その他諸々のためのクラスで、未知のプロトコルの URL を開きます。

class urllib.request.HTTPErrorProcessor

HTTP エラー応答の処理をします。

Request オブジェクト

以下のメソッドは Request の公開インターフェースについて説明しています。これらはすべてサブクラスでオーバーライドできます。また、解析したリクエストを調査するためにクライアントで使用するいくつかの属性も定義します。

Request.full_url

コンストラクターに渡されたオリジナルの URL です。

バージョン 3.4 で変更.

Request.full_url は、 setter, getter, deleter を持つプロパティです。もし存在すれば、 full_url はオリジナルのリクエスト URL フラグメント付きで返します。

Request.type

URI スキームです。

Request.host

URI オーソリティです。通常はホスト名ですが、コロンで区切られたポート番号が付随することもあります。

Request.origin_req_host

リクエストしたオリジナルのホスト名です。ポート番号はつきません。

Request.selector

URI パスです。Request がプロキシを使用する場合、セレクターはプロキシに渡される完全な URL になります。

Request.data

リクエストのエンティティボディか、指定されない場合は None になります。

バージョン 3.4 で変更: Request.data の値が変更されると、もしそれ以前に "Content-Length" ヘッダーの値が設定または計算されていたらヘッダーが削除されるようになりました。

Request.unverifiable

リクエストが RFC 2965 [https://datatracker.ietf.org/doc/html/rfc2965.html] で定義された証明不能 (unverifiable) であるかどうかを示す論理値です。

Request.method

HTTP リクエストで使うメソッドです。デフォルト値は None で、このときは使うメソッドを get_method() が通常の方法で決定するということになります。この値を設定する (従って get_method() のデフォルトの決定を上書きする) 方法は、 Request サブクラスでのクラスレベルの設定処理でデフォルト値を提供するか、 Request のコンストラクタの method 引数へ値を渡すかです。

Added in version 3.3.

バージョン 3.4 で変更: サブクラスでデフォルト値が設定できるようになりました; 以前はコンストラクタ引数からしか設定できませんでした。

Request.get_method()

HTTP リクエストメソッドを示す文字列を返します。Request.method が None でなければその値を返します。そうでない場合、Request.data が None なら 'GET' を、そうでなければ 'POST' を返します。これは HTTP リクエストに対してのみ意味を持ちます。

バージョン 3.3 で変更: get_method は Request.method の値を参照するようになりました。

Request.add_header(key, val)

リクエストに新たなヘッダーを追加します。ヘッダーは HTTP ハンドラ以外のハンドラでは無視されます。HTTP ハンドラでは、引数はサーバに送信される ヘッダーのリストに追加されます。同じ名前を持つヘッダを 2 つ以上持つことはできず、 key の衝突が生じた場合、後で追加したヘッダーが前に 追加したヘッダーを上書きします。現時点では、この機能は HTTP の機能を損ねることはありません。というのは、複数回呼び出したときに意味を 持つようなヘッダーには、どれもただ一つのヘッダーを使って同じ機能を果たすための (ヘッダー特有の) 方法があるからです。このメソッドを使って追加されたヘッダーはリダイレクトされたリクエストにも追加されることに注意してください。

Request.add_unredirected_header(key, header)

リダイレクトされたリクエストには追加されないヘッダーを追加します。

Request.has_header(header)

インスタンスが名前つきヘッダーであるかどうかを (通常のヘッダーと非リダイレクトヘッダの両方を調べて) 返します。

Request.remove_header(header)

リクエストインスタンス (の通常のヘッダーと非リダイレクトヘッダーの両方) から名前つきヘッダーを削除します。

Added in version 3.4.

Request.get_full_url()

コンストラクタで与えられた URL を返します。

バージョン 3.4 で変更.

Request.full_url を返します。

Request.set_proxy(host, type)

リクエストがプロキシサーバを経由するように準備します。 host および type はインスタンスのもとの設定と置き換えられ ます。インスタンスのセレクタはコンストラクタに与えたもともとの URL になります。

Request.get_header(header_name, default=None)

指定されたヘッダーの値を返します。ヘッダーがない場合は、 default の値を返します。

Request.header_items()

リクエストヘッダーの値を、タプル (header_name, header_value) のリストで返します。

バージョン 3.4 で変更: 3.3 から非推奨だった Request オブジェクトのメソッド add_data, has_data, get_data, get_type, get_host, get_selector, get_origin_req_host, is_unverifiable が削除されました。

OpenerDirector オブジェクト

OpenerDirector インスタンスは以下のメソッドを持っています:

OpenerDirector.add_handler(handler)

handler should be an instance of 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 http_response() would be the HTTP protocol response handler. Also type should be replaced with the actual HTTP code, for example http_error_404() would handle HTTP 404 errors.

<protocol>_open() --- signal that the handler knows how to open protocol URLs.

詳細は、 BaseHandler.<protocol>_open() を参照してください。

http_error_<type>() --- signal that the handler knows how to handle HTTP errors with HTTP error code type.

詳細は、 BaseHandler.http_error_<nnn>() を参照してください。

<protocol>_error() --- signal that the handler knows how to handle errors from (non-http) protocol.

<protocol>_request() --- signal that the handler knows how to pre-process protocol requests.

詳細は、 BaseHandler.<protocol>_request() を参照してください。

<protocol>_response() --- signal that the handler knows how to post-process protocol responses.

詳細は、 BaseHandler.<protocol>_response() を参照してください。

OpenerDirector.open(url, data=None[, timeout])

与えられた url (リクエストオブジェクトでも文字列でもかまいません) を開きます。オプションとして data を与えることができます。 引数、戻り値、および送出される例外は urlopen() と同じです (urlopen() の場合、標準でインストールされている グローバルな OpenerDirector の open() メソッドを呼び出します) 。 オプションの timeout 引数は、接続開始のようなブロックする処理におけるタイムアウト時間を 秒数で指定します。(指定しなかった場合は、グローバルのデフォルト設定が利用されます) タイムアウト機能は、 HTTP, HTTPS, FTP 接続でのみ有効です。

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 http_error_<type>() methods of the handler classes.

戻り値および送出される例外は urlopen() と同じものです。

OpenerDirector オブジェクトは、以下の 3 つのステージに分けて URL を開きます:

各ステージで OpenerDirector オブジェクトのメソッドがどのような順で呼び出されるかは、ハンドラインスタンスの並び方で決まります。

Every handler with a method named like <protocol>_request() has that method called to pre-process the request.

Handlers with a method named like <protocol>_open() are called to handle the request. This stage ends when a handler either returns a non-None value (ie. a response), or raises an exception (usually URLError). Exceptions are allowed to propagate.

In fact, the above algorithm is first tried for methods named default_open(). If all such methods return None, the algorithm is repeated for methods named like <protocol>_open(). If all such methods return None, the algorithm is repeated for methods named unknown_open().

これらのメソッドの実装には、親となる OpenerDirector インスタンスの open() や error() といったメソッド呼び出しが入る場合があるので注意してください。

Every handler with a method named like <protocol>_response() has that method called to post-process the response.

BaseHandler オブジェクト

BaseHandler オブジェクトは直接的に役に立つ 2 つのメソッドと、その他として派生クラスで使われることを想定したメソッドを 提供します。以下は直接的に使うためのメソッドです:

BaseHandler.add_parent(director)

親オブジェクトとして、 director を追加します。

BaseHandler.close()

全ての親オブジェクトを削除します。

以下の属性およびメソッドは BaseHandler から派生したクラスでのみ使われます。

注釈

The convention has been adopted that subclasses defining <protocol>_request() or <protocol>_response() methods are named *Processor; all others are named *Handler.

BaseHandler.parent

有効な OpenerDirector です。この値は違うプロトコルを使って URL を開く場合やエラーを処理する際に使われます。

BaseHandler.default_open(req)

このメソッドは BaseHandler では定義されて いません 。しかし、全ての URL をキャッチさせたいなら、サブクラスで定義する 必要があります。

This method, if implemented, will be called by the parent OpenerDirector. It should return a file-like object as described in the return value of the open() method of OpenerDirector, or None. It should raise URLError, unless a truly exceptional thing happens (for example, MemoryError should not be mapped to URLError).

このメソッドはプロトコル固有のオープンメソッドが呼び出される前に呼び出されます。

BaseHandler.<protocol>_open(req)

このメソッドは BaseHandler では定義されて いません 。しかしプロトコルの URL をキャッチしたいなら、サブクラスで定義する必要があります。

This method, if defined, will be called by the parent OpenerDirector. Return values should be the same as for default_open().

BaseHandler.unknown_open(req)

このメソッドは BaseHandler では定義されて いません 。しかし URL を開くための特定のハンドラが登録されていないような URL をキャッチしたいなら、サブクラスで定義する必要があります。

このメソッドが定義されていた場合、 parent OpenerDirector から呼び出されます。戻り値は default_open() と同じでなければなりません。

BaseHandler.http_error_default(req, fp, code, msg, hdrs)

このメソッドは BaseHandler では定義されて いません 。しかしその他の処理されなかった HTTP エラーを処理する機能をもたせたいなら、サブクラスで定義する必要があります。このメソッドはエラーに遭遇した OpenerDirector から自動的に呼び出されます。その他の状況では普通呼び出すべきではありません。

req は Request オブジェクトで、 fp は HTTP エラー本体を読み出せるようなファイル類似のオブジェクトに なります。 code は 3 桁の 10 進数からなるエラーコードで、 msg ユーザ向けのエラーコード解説です。 hdrs は エラー応答のヘッダーをマップしたオブジェクトです。

返される値および送出される例外は urlopen() と同じものでなければなりません。

BaseHandler.http_error_<nnn>(req, fp, code, msg, hdrs)

nnn は 3 桁の 10 進数からなる HTTP エラーコードでなくてはなりません。このメソッドも BaseHandler では定義されていませんが、サブクラスのインスタンスで定義されていた場合、エラーコード nnn の HTTP エラーが発生した際に呼び出されます。

特定の HTTP エラーに対する処理を行うためには、このメソッドをサブクラスでオーバライドする必要があります。

Arguments, return values and exceptions raised should be the same as for http_error_default().

BaseHandler.<protocol>_request(req)

このメソッドは BaseHandler では 定義されていません が、サブクラスで特定のプロトコルのリクエストのプリプロセスを行いたい場合には定義する必要があります。

このメソッドが定義されていると、親となる OpenerDirector から呼び出されます。その際、 req は Request オブジェクトになります。戻り値は Request オブジェクトでなければなりません。

BaseHandler.<protocol>_response(req, response)

このメソッドは BaseHandler では 定義されていません が、サブクラスで特定のプロトコルのリクエストのポストプロセスを行いたい場合には定義する必要があります。

このメソッドが定義されていると、親となる OpenerDirector から呼び出されます。その際、 req は Request オブジェクトになります。 response は urlopen() の戻り値と同じインターフェースを 実装したオブジェクトになります。戻り値もまた、 urlopen() の戻り値と同じインターフェースを実装したオブジェクトでなければなりません。

HTTPRedirectHandler オブジェクト

注釈

一部の HTTP リクエストはこのモジュールのクライアントモードからの操作を要求します。その場合、HTTPError が送出されます。さまざまなリダイレクションコードの正確な意味についての詳細は RFC 2616 [https://datatracker.ietf.org/doc/html/rfc2616.html] を参照してください。

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

HTTPRedirectHandler.redirect_request(req, fp, code, msg, hdrs, newurl)

Return a Request or None in response to a redirect. This is called by the default implementations of the http_error_30*() methods when a redirection is received from the server. If a redirection should take place, return a new Request to allow http_error_30*() to perform the redirect to newurl. Otherwise, raise HTTPError if no other handler should try to handle this URL, or return None if you can't but another handler might.

注釈

このメソッドのデフォルトの実装は、 RFC 2616 [https://datatracker.ietf.org/doc/html/rfc2616.html] に厳密に従ったものではありません。 RFC 2616 [https://datatracker.ietf.org/doc/html/rfc2616.html] では、 POST リクエストに対する 301 および 302 応答が、ユーザの承認なく自動的にリダイレクトされてはならないと述べています。現実には、ブラウザは POST を GET に変更することで、これらの応答に対して自動的にリダイレクトを行えるようにしています。デフォルトの実装でも、この挙動を再現しています。

HTTPRedirectHandler.http_error_301(req, fp, code, msg, hdrs)

Location: か URI: のURL にリダイレクトします。このメソッドは HTTP における 'moved permanently' レスポンスを取得した際に 親オブジェクトとなる OpenerDirector によって呼び出されます。

HTTPRedirectHandler.http_error_302(req, fp, code, msg, hdrs)

http_error_301() と同じですが、'found' レスポンスに対して呼び出されます。

HTTPRedirectHandler.http_error_303(req, fp, code, msg, hdrs)

http_error_301() と同じですが、'see other' レスポンスに対して呼び出されます。

HTTPRedirectHandler.http_error_307(req, fp, code, msg, hdrs)

The same as http_error_301(), but called for the 'temporary redirect' response. It does not allow changing the request method from POST to GET.

HTTPRedirectHandler.http_error_308(req, fp, code, msg, hdrs)

The same as http_error_301(), but called for the 'permanent redirect' response. It does not allow changing the request method from POST to GET.

Added in version 3.11.

HTTPCookieProcessor オブジェクト

HTTPCookieProcessor インスタンスは属性をひとつだけ持ちます:

HTTPCookieProcessor.cookiejar

Cookie の入っている http.cookiejar.CookieJar オブジェクトです。

ProxyHandler オブジェクト

ProxyHandler.<protocol>_open(request)

The ProxyHandler will have a method <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 request.set_proxy(), and call the next handler in the chain to actually execute the protocol.

HTTPPasswordMgr オブジェクト

以下のメソッドは HTTPPasswordMgr および HTTPPasswordMgrWithDefaultRealm オブジェクトで利用できます。

HTTPPasswordMgr.add_password(realm, uri, user, passwd)

uri は単一の URI でも複数の URI からなるシーケンスでもかまいません。 realm 、 user および passwd は文字列でなくてはなりません。このメソッドによって、 realm と与えられた URI の上位 URI に対して (user, passwd) が認証トークンとして使われるようになります。

HTTPPasswordMgr.find_user_password(realm, authuri)

与えられたレルムおよび URI に対するユーザ名またはパスワードがあればそれを取得します。該当するユーザ名／パスワードが存在しない場合、このメソッドは (None, None) を返します。

HTTPPasswordMgrWithDefaultRealm オブジェクトでは、与えられた realm に対して該当するユーザ名/パスワードが存在しない場合、レルム None が検索されます。

HTTPPasswordMgrWithPriorAuth オブジェクト

このパスワードマネージャは HTTPPasswordMgrWithDefaultRealm を継承して、認証の証明書を常に送らないといけない URI を追跡する機能をサポートしています。

HTTPPasswordMgrWithPriorAuth.add_password(realm, uri, user, passwd, is_authenticated=False)

realm, uri, user, passwd は HTTPPasswordMgr.add_password() のものと同じです。 is_authenticated は、与えられた URI や URI のリストの is_authenticated フラグの初期値に設定されます。 is_authenticated に True を指定した場合は、 realm は無視されます。

HTTPPasswordMgrWithPriorAuth.find_user_password(realm, authuri)

HTTPPasswordMgrWithDefaultRealm オブジェクトに対する同名のメソッドと同じです。

HTTPPasswordMgrWithPriorAuth.update_authenticated(self, uri, is_authenticated=False)

与えられた url や URI のリストの is_authenticated フラグを更新します。

HTTPPasswordMgrWithPriorAuth.is_authenticated(self, authuri)

与えられた URI の is_authenticated フラグの現在の状態を返します。

AbstractBasicAuthHandler オブジェクト

AbstractBasicAuthHandler.http_error_auth_reqed(authreq, host, req, headers)

ユーザ名／パスワードを取得し、再度サーバへのリクエストを試みることで、サーバからの認証リクエストを処理します。 authreq はリクエストにおいて レルムに関する情報が含まれているヘッダーの名前、 host は認証を行う対象の URL とパスを指定します、 req は (失敗した) Request オブジェクト、そして headers はエラーヘッダーでなくてはなりません。

host は、オーソリティ (例 "python.org") か、オーソリティコンポーネントを含む URL (例 "http://python.org") です。どちらの場合も、オーソリティはユーザ情報コンポーネントを含んではいけません (なので、 "python.org" や "python.org:80" は正しく、 "joe:password@python.org" は不正です) 。

HTTPBasicAuthHandler オブジェクト

HTTPBasicAuthHandler.http_error_401(req, fp, code, msg, hdrs)

認証情報がある場合、認証情報付きで再度リクエストを試みます。

ProxyBasicAuthHandler オブジェクト

ProxyBasicAuthHandler.http_error_407(req, fp, code, msg, hdrs)

認証情報がある場合、認証情報付きで再度リクエストを試みます。

AbstractDigestAuthHandler オブジェクト

AbstractDigestAuthHandler.http_error_auth_reqed(authreq, host, req, headers)

authreq はリクエストにおいてレルムに関する情報が含まれているヘッダーの名前、 host は認証を行う対象のホスト名、 req は (失敗した) Request オブジェクト、そして headers はエラーヘッダーでなくてはなりません。

HTTPDigestAuthHandler オブジェクト

HTTPDigestAuthHandler.http_error_401(req, fp, code, msg, hdrs)

認証情報がある場合、認証情報付きで再度リクエストを試みます。

ProxyDigestAuthHandler オブジェクト

ProxyDigestAuthHandler.http_error_407(req, fp, code, msg, hdrs)

認証情報がある場合、認証情報付きで再度リクエストを試みます。

HTTPHandler オブジェクト

HTTPHandler.http_open(req)

HTTP リクエストを送ります。 req.has_data() に応じて、 GET または POST のどちらでも送ることができます。

HTTPSHandler オブジェクト

HTTPSHandler.https_open(req)

HTTPS リクエストを送ります。 req.has_data() に応じて、 GET または POST のどちらでも送ることができます。

FileHandler オブジェクト

FileHandler.file_open(req)

ホスト名がない場合、またはホスト名が 'localhost' の場合にファイルをローカルでオープンします。

バージョン 3.2 で変更: このメソッドはローカルのホスト名に対してのみ適用可能です。リモートホスト名が与えられた場合、URLError が送出されます。

DataHandler オブジェクト

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 RFC 2397 [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 an ValueError in that case.

FTPHandler オブジェクト

FTPHandler.ftp_open(req)

req で表されるファイルを FTP 越しにオープンします。ログインは常に空のユーザネームおよびパスワードで行われます。

CacheFTPHandler オブジェクト

CacheFTPHandler オブジェクトは FTPHandler オブジェクトに以下のメソッドを追加したものです:

CacheFTPHandler.setTimeout(t)

接続のタイムアウトを t 秒に設定します。

CacheFTPHandler.setMaxConns(m)

キャッシュ付き接続の最大接続数を m に設定します。

UnknownHandler オブジェクト

UnknownHandler.unknown_open()

URLError 例外を送出します。

HTTPErrorProcessor オブジェクト

HTTPErrorProcessor.http_response(request, response)

HTTP エラー応答の処理をします。

エラーコード 200 の場合、レスポンスオブジェクトを即座に返します。

For non-200 error codes, this simply passes the job on to the http_error_<type>() handler methods, via OpenerDirector.error(). Eventually, HTTPDefaultErrorHandler will raise an HTTPError if no other handler handles the error.

HTTPErrorProcessor.https_response(request, response)

HTTPS エラー応答の処理をします。

振る舞いは http_response() と同じです。

使用例

以下の例の他に urllib パッケージを使ってインターネット上のリソースを取得するには に多くの例があります。

以下の例では、python.org のメインページを取得して、その最初の 300 バイト分を表示します。

>>> import urllib.request
>>> with urllib.request.urlopen('http://www.python.org/') as f:
...     print(f.read(300))
...
b'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">\n\n\n<html
xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">\n\n<head>\n
<meta http-equiv="content-type" content="text/html; charset=utf-8" />\n
<title>Python Programming '

urlopen は bytes オブジェクトを返すことに注意してください。これは urlopen が、HTTP サーバーから受信したバイトストリームのエンコーディングを自動的に決定できないためです。一般に、返された bytes オブジェクトを文字列にデコードするためのエンコーディングの決定あるいは推測はプログラム側が行います。

以下の W3C ドキュメント https://www.w3.org/International/O-charsetには (X)HTML や XML ドキュメントでそのエンコーディング情報を指定するさまざまな方法の一覧があります。

python.org ウェブサイトでは utf-8 エンコーディングを使用しており、それをその meta タグで指定していますので、bytes オブジェクトのデコードも同様に行います。

>>> with urllib.request.urlopen('http://www.python.org/') as f:
...     print(f.read(100).decode('utf-8'))
...
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtm

コンテキストマネージャー を使用しないアプローチでも同様の結果を得ることができます。

>>> import urllib.request
>>> f = urllib.request.urlopen('http://www.python.org/')
>>> print(f.read(100).decode('utf-8'))
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtm

以下の例では、データストリームを CGI の標準入力へ送信し、返されたデータを読み込みます。この例は Python が SSL をサポートするように設定してインストールされている場合のみ動作します。

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

上の例で使われているサンプルの CGI は以下のようになっています:

#!/usr/bin/env python
import sys
data = sys.stdin.read()
print('Content-type: text/plain\n\nGot Data: "%s"' % data)

これは Request を使った PUT リクエストの例です:

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)

以下はベーシック HTTP 認証の例です:

import urllib.request
# Create an OpenerDirector with support for Basic HTTP Authentication...
auth_handler = urllib.request.HTTPBasicAuthHandler()
auth_handler.add_password(realm='PDQ Application',
                          uri='https://mahler:8092/site-updates.py',
                          user='klem',
                          passwd='kadidd!ehopper')
opener = urllib.request.build_opener(auth_handler)
# ...and install it globally so it can be used with urlopen.
urllib.request.install_opener(opener)
urllib.request.urlopen('http://www.example.com/login.html')

build_opener() provides many handlers by default, including a ProxyHandler. By default, ProxyHandler uses the environment variables named <scheme>_proxy, where <scheme> is the URL scheme involved. For example, the http_proxy environment variable is read to obtain the HTTP proxy's URL.

この例では、デフォルトの ProxyHandler を置き換えてプログラム的に作成したプロキシ URL を使うようにし、 ProxyBasicAuthHandler でプロキシ認証サポートを追加します。

proxy_handler = urllib.request.ProxyHandler({'http': 'http://www.example.com:3128/'})
proxy_auth_handler = urllib.request.ProxyBasicAuthHandler()
proxy_auth_handler.add_password('realm', 'host', 'username', 'password')

opener = urllib.request.build_opener(proxy_handler, proxy_auth_handler)
# This time, rather than install the OpenerDirector, we use it directly:
opener.open('http://www.example.com/login.html')

以下は HTTP ヘッダーを追加する例です:

headers 引数を使って Request コンストラクタを呼び出す方法の他に、以下のようにできます:

import urllib.request
req = urllib.request.Request('http://www.example.com/')
req.add_header('Referer', 'http://www.python.org/')
# Customize the default User-Agent header value:
req.add_header('User-Agent', 'urllib-example/0.1 (Contact: . . .)')
r = urllib.request.urlopen(req)

OpenerDirector は全ての Request に User-Agent ヘッダーを自動的に追加します。これを変更するには以下のようにします:

import urllib.request
opener = urllib.request.build_opener()
opener.addheaders = [('User-agent', 'Mozilla/5.0')]
opener.open('http://www.example.com/')

また、 Request が urlopen() (や OpenerDirector.open())に渡される際には、いくつかの標準ヘッダー (Content-Length, Content-Type および Host) も追加されることを忘れないでください。

以下は GET メソッドを使ってパラメータを含む URL を取得するセッションの例です:

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

以下の例では、POST メソッドを使用しています。urlencode から出力されたパラメーターは urlopen にデータとして渡される前に bytes にエンコードされていることに注意してください:

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

以下の例では、環境変数による設定内容に対して上書きする形で HTTP プロキシを明示的に設定しています:

>>> import urllib.request
>>> proxies = {'http': 'http://proxy.example.com:8080/'}
>>> opener = urllib.request.FancyURLopener(proxies)
>>> with opener.open("http://www.python.org") as f:
...     f.read().decode('utf-8')
...

以下の例では、環境変数による設定内容に対して上書きする形で、まったくプロキシを使わないよう設定しています:

>>> import urllib.request
>>> opener = urllib.request.FancyURLopener({})
>>> with opener.open("http://www.python.org/") as f:
...     f.read().decode('utf-8')
...

レガシーインターフェース

以下の関数およびクラスは、Python 2 のモジュール urllib (urllib2 ではありません) から移植されたものです。これらは将来的に廃止されるかもしれません。

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 (filename, headers) where filename is the local file name under which the object can be found, and headers is whatever the info() method of the object returned by urlopen() returned (for a remote object). Exceptions are the same as for 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 -1 on older FTP servers which do not return a file size in response to a retrieval request.

以下は最も一般的な使用例です:

>>> import urllib.request
>>> local_filename, headers = urllib.request.urlretrieve('http://python.org/')
>>> html = open(local_filename)
>>> html.close()

url が http: スキーム識別子を使用していた場合、任意の引数 data は POST リクエストの指定に使用される場合があります (通常のリクエストタイプは GET です)。引数 data は標準 application/x-www-form-urlencoded 形式のバイトオブジェクトでなければなりません。 urllib.parse.urlencode() 関数を参照してください。

urlretrieve() will raise 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.

Content-Length はデータ量の下限です: 読み込むデータ量がこれを超えている場合 urlretrieve はそれらも読み込みますが、利用できるデータがこれを下回った場合、例外が送出されます。

You can still retrieve the downloaded data in this case, it is stored in the content attribute of the exception instance.

Content-Length ヘッダーが与えられなれけば urlretrieve はダウンロードしたデータのサイズをチェックできません。この場合ダウンロードは正常に完了したとみなすしかありません。

urllib.request.urlcleanup()

以前の urlretrieve() 呼び出し後に残っているかもしれない一時ファイルをクリーンアップします。

class urllib.request.URLopener(proxies=None, **x509)

バージョン 3.3 で非推奨.

URL をオープンし、読み出すためのクラスの基底クラスです。http:, ftp:, file: 以外のスキームを使ったオブジェクトのオープンをサポートしたいのでないかぎり、FancyURLopener を使おうと思うことになるでしょう。

デフォルトでは、 URLopener クラスは User-Agent ヘッダーとして urllib/VVV を送信します。ここで VVV は urllib のバージョン番号です。アプリケーションで独自の User-Agent ヘッダーを送信したい場合は、 URLopener かまたは FancyURLopener のサブクラスを作成し、サブクラス定義においてクラス属性 version を適切な文字列値に設定することで行うことができます。

オプションのパラメーター proxies はスキーム名をプロキシの URL にマップする辞書でなければなりません。空の辞書はプロキシ機能を完全にオフにします。デフォルトの値は None で、この場合、 urlopen() の定義で述べたように、プロキシを設定する環境変数が存在するならそれを使います。

追加のキーワードパラメーターは x509 に集められますが、これは https: スキームを使った際のクライアント認証に使われることがあります。キーワード引数 key_file および cert_file が SSL 鍵と証明書を設定するためにサポートされています; クライアント認証をするには両方が必要です。

URLopener オブジェクトはサーバーがエラーコードを返した場合に OSError 例外を送出します。

open(fullurl, data=None)

適切なプロトコルを使って fullurl を開きます。このメソッドはキャッシュとプロキシ情報を設定し、その後適切な open メソッドを入力引数つきで呼び出します。認識できないスキームが与えられた場合、 open_unknown() が呼び出されます。 data 引数は urlopen() の引数 data と同じ意味を持っています。

This method always quotes fullurl using quote().

open_unknown(fullurl, data=None)

オーバライド可能な、未知のタイプの URL を開くためのインターフェースです。

retrieve(url, filename=None, reporthook=None, data=None)

url の内容を取得し、filename に保存します。戻り値は、ローカルファイル名と、レスポンスヘッダーが含まれる email.message.Message (リモート URL の場合) か None (ローカル URL の場合) からなるタプルになります。呼び出し側は、その後 filename を開いてその内容を読み込まなければなりません。filename が与えられず、URL がローカルファイルを参照している場合、入力ファイル名が返されます。URL がローカルでなく、filename が与えられていない場合、ファイル名は入力 URL のパスの最後の構成要素のサフィックスとマッチするサフィックスを持つ tempfile.mktemp() の出力になります。reporthook が与えられている場合、3 つの数値 (チャンク数、読み込んだチャンクの最大サイズ、および総ダウンロードサイズ --- 不明の場合は -1) の引数を受け取る関数でなければなりません。これは開始時に 1 回と、ネットワークからデータのチャンクを読み込む度に呼び出されます。reporthook はローカル URL に対しては無視されます。

url が http: スキーム識別子を使用していた場合、任意の引数 data は POST リクエストの指定に使用される場合があります (通常のリクエストタイプは GET です)。引数 data は標準 application/x-www-form-urlencoded 形式でなければなりません。urllib.parse.urlencode() 関数を参照してください。

version

URL をオープンするオブジェクトのユーザエージェントを指定する変数です。 urllib を特定のユーザエージェントであるとサーバに通知するには、サブクラスの中でこの値をクラス変数として値を設定するか、コンストラクタの中でベースクラスを呼び出す前に値を設定してください。

class urllib.request.FancyURLopener(...)

バージョン 3.3 で非推奨.

FancyURLopener は URLopener のサブクラスで、以下の HTTP レスポンスコード: 301、302、303、 307、および 401 を取り扱う機能を提供します。レスポンスコード 30x に対しては、 Location ヘッダーを使って実際の URL を取得します。レスポンスコード 401 (認証が要求されていることを示す) に対しては、BASIC認証 (basic HTTP authintication) が行われます。レスポンスコード 30x に対しては、最大で maxtries 属性に指定された数だけ再帰呼び出しを行うようになっています。この値はデフォルトで 10 です。

For all other response codes, the method http_error_default() is called which you can override in subclasses to handle the error appropriately.

注釈

RFC 2616 [https://datatracker.ietf.org/doc/html/rfc2616.html] によると、 POST 要求に対する 301 および 302 応答はユーザの承認無しに自動的にリダイレクトしてはなりません。実際は、これらの応答に対して自動リダイレクトを許すブラウザでは POST を GET に変更しており、 urllib でもこの動作を再現します。

コンストラクタに与えるパラメーターは URLopener と同じです。

注釈

基本的な HTTP 認証を行う際、 FancyURLopener インスタンスは prompt_user_passwd() メソッドを呼び出します。このメソッドはデフォルトでは実行を制御している端末上で認証に必要な情報を要求するように実装されています。必要ならば、このクラスのサブクラスにおいてより適切な動作をサポートするために prompt_user_passwd() メソッドをオーバライドしてもかまいません。

FancyURLopener クラスはオーバライド可能な追加のメソッドを提供しており、適切な振る舞いをさせることができます:

prompt_user_passwd(host, realm)

指定されたセキュリティ領域 (security realm) 下にある与えられたホストにおいて、ユーザー認証に必要な情報を返すための関数です。この関数が返す値は (user, password) からなるタプルでなければなりません。値は Basic 認証で使われます。

このクラスでの実装では、端末に情報を入力するようプロンプトを出します; ローカルの環境において適切な形で対話型モデルを使うには、このメソッドをオーバライドしなければなりません。

urllib.request の制限事項

現在、次のプロトコルのみサポートされています: HTTP (バージョン 0.9 および 1.0)、FTP、ローカルファイル、およびデータ URL

バージョン 3.4 で変更: データ URL サポートが追加されました。

urlretrieve() のキャッシュ機能は、誰かが Expiration time ヘッダーの正しい処理をハックする時間を見つけるまで無効にされています。

ある URL がキャッシュにあるかどうか調べるような関数があればと思っています。

後方互換性のため、 URL がローカルシステム上のファイルを指しているように見えるにも関わらずファイルを開くことができなければ、 URL は FTP プロトコルを使って再解釈されます。この機能は時として混乱を招くエラーメッセージを引き起こします。

関数 urlopen() および urlretrieve() は、ネットワーク接続が確立されるまでの間、一定でない長さの遅延を引き起こすことがあります。このことは、これらの関数を使ってインタラクティブな Web クライアントを構築するのはスレッドなしには難しいことを意味します。

urlopen() あるいは urlretrieve() が返すデータはサーバーから返された生データです。これは (画像のような) バイナリ、プレーンテキスト、あるいは (例えば) HTML などになります。HTTP プロトコルはレスポンスヘッダー内でタイプ情報を提供しており、Content-Type ヘッダーを見ることで調査できます。返されたデータが HTML の場合、モジュール html.parser を使用してこれを解析できます。

FTP プロトコルを扱うコードでは、ファイルとディレクトリを区別できません。このことから、アクセスできないファイルを指している URL からデータを読み出そうとすると、予期しない動作を引き起こす場合があります。 URL が / で終わっていれば、ディレクトリを指しているものとみなして、それに適した処理を行います。しかし、ファイルの読み出し操作が 550 エラー (URL が存在しないか、主にパーミッションの理由でアクセスできない) になった場合、 URL がディレクトリを指していて、末尾の / を忘れたケースを処理するため、パスをディレクトリとして扱います。このために、パーミッションのためにアクセスできないファイルを fetch しようとすると、FTP コードはそのファイルを開こうとして 550 エラーに陥り、次にディレクトリ一覧を表示しようとするため、誤解を生むような結果を引き起こす可能性があるのです。よく調整された制御が必要なら、 ftplib モジュールを使うか、 FancyURLopener をサブクラス化するか、 _urlopener を変更して目的に合わせるよう検討してください。

urllib.response --- urllib で使用するレスポンスクラス

urllib.response モジュールは、read() および readline() を含む 最小限のファイルライクインターフェースを定義する関数およびクラスを定義しています。このモジュールで定義された関数は、urllib.request モジュール内で使用されます。代表的なレスポンスオブジェクトは urllib.response.addinfourl インスタンスです。

class urllib.response.addinfourl

url

取得されたリソースの URL、主にリダイレクトが発生したかどうかを確認するために利用します。

headers

Returns the headers of the response in the form of an EmailMessage instance.

status

Added in version 3.9.

サーバから返される状態コードです。

geturl()

バージョン 3.9 で非推奨: 非推奨となったので url を使用してください。

info()

バージョン 3.9 で非推奨: 非推奨となったので headers を使用してください。

code

バージョン 3.9 で非推奨: 非推奨となったので status を使用してください。

getcode()

バージョン 3.9 で非推奨: 非推奨となったので status を使用してください。

urllib.parse --- Parse URLs into components

ソースコード: Lib/urllib/parse.py [https://github.com/python/cpython/tree/3.12/Lib/urllib/parse.py]

このモジュールでは URL (Uniform Resource Locator) 文字列をその構成要素 (アドレススキーム、ネットワーク上の位置、パスその他) に分解したり、構成要素を URL に組みなおしたり、 "相対 URL (relative URL)" を指定した "基底 URL (base URL)" に基づいて絶対 URL に変換するための標準的なインターフェースを定義しています。

The module has been designed to match the internet RFC on Relative Uniform Resource Locators. It supports the following URL schemes: file, ftp, gopher, hdl, http, https, imap, mailto, mms, news, nntp, prospero, rsync, rtsp, rtsps, rtspu, sftp, shttp, sip, sips, snews, svn, svn+ssh, telnet, wais, ws, wss.

urllib.parse モジュールは、大きく分けると URL の解析を行う関数と URL のクオートを行う関数を定義しています。以下にこれらの詳細を説明します。

This module's functions use the deprecated term netloc (or net_loc), which was introduced in RFC 1808 [https://datatracker.ietf.org/doc/html/rfc1808.html]. However, this term has been obsoleted by RFC 3986 [https://datatracker.ietf.org/doc/html/rfc3986.html], which introduced the term authority as its replacement. The use of netloc is continued for backward compatibility.

URL の解析

URL 解析関数は、URL 文字列を各構成要素に分割するか、あるいは URL の構成要素を組み合わせて URL 文字列を生成します。

urllib.parse.urlparse(urlstring, scheme='', allow_fragments=True)

URL を解析して 6 つの構成要素にし、6 要素の named tuple を返します。このタプルは URL の一般的な構造: scheme://netloc/path;parameters?query#fragment に対応しています。各タプル要素は文字列で、空の場合もあります。構成要素がさらに小さい要素に分解されることはありません (例えばネットワーク上の位置は単一の文字列になります)。また % によるエスケープは展開されません。上で示された区切り文字がタプルの各要素の一部分として含まれることはありませんが、path 要素の先頭のスラッシュがある場合には例外です。たとえば以下のようになります:

>>> from urllib.parse import urlparse
>>> urlparse("scheme://netloc/path;parameters?query#fragment")
ParseResult(scheme='scheme', netloc='netloc', path='/path;parameters', params='',
            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='',
            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'

RFC 1808 [https://datatracker.ietf.org/doc/html/rfc1808.html] にある文法仕様に基づき、urlparse は '//' で始まる場合にのみ netloc を認識します。それ以外の場合は、入力は相対URLであると推定され、path 部分で始まることになります。

>>> from urllib.parse import urlparse
>>> urlparse('//www.cwi.nl:80/%7Eguido/Python.html')
ParseResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            params='', query='', fragment='')
>>> urlparse('www.cwi.nl/%7Eguido/Python.html')
ParseResult(scheme='', netloc='', path='www.cwi.nl/%7Eguido/Python.html',
            params='', query='', fragment='')
>>> urlparse('help/Python.html')
ParseResult(scheme='', netloc='', path='help/Python.html', params='',
            query='', fragment='')

scheme 引数によってデフォルトのアドレススキームを与えると、アドレススキームを指定していない URL のみに使用されます。常に許されるデフォルトの '' (b'' に自動変換出来る)を除き、 urlstring と同じ型(テキストもしくはバイト列)であるべきです。

引数 allow_fragments が false の場合、フラグメント識別子は認識されません。その代わり、それはパス、パラメータ、またはクエリ要素の一部として解析され、戻り値の fragment は空文字に設定されます。

戻り値は 名前付きタプル です。これは、インデックス指定もしくは以下のような名前属性で要素にアクセスできることを意味します:

属性

インデックス

値

指定されなかった場合の値

scheme

0

URL スキーム

scheme パラメータ

netloc

1

ネットワーク上の位置

空文字列

path

2

階層的パス

空文字列

params

3

最後のパス要素に対するパラメータ

空文字列

query

4

クエリ要素

空文字列

fragment

5

フラグメント識別子

空文字列

username

ユーザ名

None

password

パスワード

None

hostname

ホスト名 (小文字)

None

port

ポート番号を表わす整数 (もしあれば)

None

URL中で不正なポートが指定されている場合、 port 属性を読みだすと、ValueError を送出します。結果オブジェクトのより詳しい情報は 構造化された解析結果 節を参照してください。

netloc 属性にマッチしなかった角括弧があると ValueError を送出します。

Characters in the netloc attribute that decompose under NFKC normalization (as used by the IDNA encoding) into any of /, ?, #, @, or : will raise a 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 _replace(). The _replace() method will return a new ParseResult object replacing specified fields with new values.

>>> from urllib.parse import urlparse
>>> u = urlparse('//www.cwi.nl:80/%7Eguido/Python.html')
>>> u
ParseResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            params='', query='', fragment='')
>>> u._replace(scheme='http')
ParseResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            params='', query='', fragment='')

警告

urlparse() does not perform validation. See URL parsing security for details.

バージョン 3.2 で変更: IPv6 URL の解析も行えるようになりました。

バージョン 3.3 で変更: The fragment is now parsed for all URL schemes (unless allow_fragment is false), in accordance with RFC 3986 [https://datatracker.ietf.org/doc/html/rfc3986.html]. Previously, an allowlist of schemes that support fragments existed.

バージョン 3.6 で変更: 範囲外のポート番号を指定すると、 None を返す代わりに、ValueError を送出するようになりました。

バージョン 3.8 で変更: Characters that affect netloc parsing under NFKC normalization will now raise ValueError.

urllib.parse.parse_qs(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None, separator='&')

文字列引数として渡されたクエリ文字列 (application/x-www-form-urlencoded 型のデータ) を解析します。解析されたデータを辞書として返します。辞書のキーは一意なクエリ変数名で、値は各変数名に対する値からなるリストです。

任意の引数 keep_blank_values は、パーセントエンコードされたクエリの中の値が入っていないクエリの値を空白文字列と見なすかどうかを示すフラグです。値が真であれば、値の入っていないフィールドは空文字列のままになります。標準では偽で、値の入っていないフィールドを無視し、そのフィールドはクエリに含まれていないものとして扱います。

任意の引数 strict_parsing はパース時のエラーをどう扱うかを決めるフラグです。値が偽なら (デフォルトの設定です)、エラーは暗黙のうちに無視します。値が真なら ValueError 例外を送出します。

任意のパラメータ encoding および errors はパーセントエンコードされたシーケンスを Unicode 文字にデコードする方法を指定します。これは bytes.decode() メソッドに渡されます。

The optional argument max_num_fields is the maximum number of fields to read. If set, then throws a 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 &.

このような辞書をクエリ文字列に変換するには urllib.parse.urlencode() 関数を (doseq パラメータに True を指定して) 使用します。

バージョン 3.2 で変更: encoding および errors パラメータが追加されました。

バージョン 3.8 で変更: max_num_fields パラメータが追加されました。

バージョン 3.10 で変更: Added separator parameter with the default value of &. Python versions earlier than Python 3.10 allowed using both ; and & as query parameter separator. This has been changed to allow only a single separator key, with & as the default separator.

urllib.parse.parse_qsl(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None, separator='&')

文字列引数として渡されたクエリ文字列 (application/x-www-form-urlencoded 型のデータ) を解析します。解析されたデータは名前と値のペアからなるリストです。

任意の引数 keep_blank_values は、パーセントエンコードされたクエリの中の値が入っていないクエリの値を空白文字列と見なすかどうかを示すフラグです。値が真であれば、値の入っていないフィールドは空文字列のままになります。標準では偽で、値の入っていないフィールドを無視し、そのフィールドはクエリに含まれていないものとして扱います。

任意の引数 strict_parsing はパース時のエラーをどう扱うかを決めるフラグです。値が偽なら (デフォルトの設定です)、エラーは暗黙のうちに無視します。値が真なら ValueError 例外を送出します。

任意のパラメータ encoding および errors はパーセントエンコードされたシーケンスを Unicode 文字にデコードする方法を指定します。これは bytes.decode() メソッドに渡されます。

The optional argument max_num_fields is the maximum number of fields to read. If set, then throws a 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 &.

ペアのリストからクエリ文字列を生成する場合には urllib.parse.urlencode() 関数を使用します。

バージョン 3.2 で変更: encoding および errors パラメータが追加されました。

バージョン 3.8 で変更: max_num_fields パラメータが追加されました。

バージョン 3.10 で変更: Added separator parameter with the default value of &. Python versions earlier than Python 3.10 allowed using both ; and & as query parameter separator. This has been changed to allow only a single separator key, with & as the default separator.

urllib.parse.urlunparse(parts)

urlparse() が返すような形式のタプルから URL を構築します。parts 引数は任意の 6 要素イテラブルです。解析された元の URL が、不要な区切り文字を持っていた場合には、多少違いはあるが等価な URL になるかもしれません (例えばクエリ内容が空の ? のようなもので、RFC はこれらを等価だと述べています)。

urllib.parse.urlsplit(urlstring, scheme='', allow_fragments=True)

urlparse() に似ていますが、URL から params を切り離しません。このメソッドは通常、URL の path 部分において、各セグメントにパラメータ指定をできるようにした最近の URL 構文 (RFC 2396 [https://datatracker.ietf.org/doc/html/rfc2396.html] 参照) が必要な場合に、 urlparse() の代わりに使われます。パスセグメントとパラメータを分割するためには分割用の関数が必要です。この関数は 5 要素の named tuple を返します:

(addressing scheme, network location, path, query, fragment identifier).

戻り値は 名前付きタプル で、インデックスによってもしくは名前属性として要素にアクセスできます:

属性

インデックス

値

指定されなかった場合の値

scheme

0

URL スキーム

scheme パラメータ

netloc

1

ネットワーク上の位置

空文字列

path

2

階層的パス

空文字列

query

3

クエリ要素

空文字列

fragment

4

フラグメント識別子

空文字列

username

ユーザ名

None

password

パスワード

None

hostname

ホスト名 (小文字)

None

port

ポート番号を表わす整数 (もしあれば)

None

URL中で不正なポートが指定されている場合、 port 属性を読みだすと、ValueError を送出します。結果オブジェクトのより詳しい情報は 構造化された解析結果 節を参照してください。

netloc 属性にマッチしなかった角括弧があると ValueError を送出します。

Characters in the netloc attribute that decompose under NFKC normalization (as used by the IDNA encoding) into any of /, ?, #, @, or : will raise a ValueError. If the URL is decomposed before parsing, no error will be raised.

Following some of the WHATWG spec [https://url.spec.whatwg.org/#concept-basic-url-parser] that updates RFC 3986, leading C0 control and space characters are stripped from the URL. \n, \r and tab \t characters are removed from the URL at any position.

警告

urlsplit() does not perform validation. See URL parsing security for details.

バージョン 3.6 で変更: 範囲外のポート番号を指定すると、 None を返す代わりに、ValueError を送出するようになりました。

バージョン 3.8 で変更: Characters that affect netloc parsing under NFKC normalization will now raise 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.

urllib.parse.urlunsplit(parts)

urlsplit() が返すような形式のタプル中のエレメントを組み合わせて、文字列の完全な URL にします。 parts 引数は任意の 5 要素イテラブルです。解析された元の URL が、不要な区切り文字を持っていた場合には、多少違いはあるが等価な URL になるかもしれません (例えばクエリ内容が空の ? のようなもので、RFC はこれらを等価だと述べています)。

urllib.parse.urljoin(base, url, allow_fragments=True)

"基底 URL"(base)と別のURL(url)を組み合わせて、完全な URL ("絶対 URL") を構成します。くだけて言えば、この関数は相対 URL にない要素を提供するために基底 URL の要素、特にアドレススキーム、ネットワーク上の位置、およびパス (の一部) を使います。例えば:

>>> from urllib.parse import urljoin
>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html')
'http://www.cwi.nl/%7Eguido/FAQ.html'

allow_fragments 引数は urlparse() における引数と同じ意味とデフォルトを持ちます。

注釈

url が (// か scheme:// で始まる) 絶対URLであれば、その url のホスト名と / もしくは scheme は結果に反映されます。例えば:

>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html',
...         '//www.python.org/%7Eguido')
'http://www.python.org/%7Eguido'

もしこの動作が望みのものでない場合は、 url を urlsplit() と urlunsplit() で先に処理して、 scheme と netloc を削除してください。

バージョン 3.5 で変更: RFC 3986 [https://datatracker.ietf.org/doc/html/rfc3986.html] で定義された意味論とマッチするように挙動がアップデートされました。

urllib.parse.urldefrag(url)

url がフラグメント識別子を含む場合、フラグメント識別子を持たないバージョンに修正された url と、別の文字列に分割されたフラグメント識別子を返します。url 中にフラグメント識別子がない場合、そのままの url と空文字列を返します。

戻り値は 名前付きタプル で、インデックスによってもしくは名前属性として要素にアクセスできます:

属性

インデックス

値

指定されなかった場合の値

url

0

フラグメントのない URL

空文字列

fragment

1

フラグメント識別子

空文字列

結果オブジェクトのより詳しい情報は 構造化された解析結果 節を参照してください。

バージョン 3.2 で変更: 結果はシンプルな 2 要素のタプルから構造化オブジェクトに変更されました。

urllib.parse.unwrap(url)

Extract the url from a wrapped URL (that is, a string formatted as <URL:scheme://host/path>, <scheme://host/path>, URL:scheme://host/path or scheme://host/path). If url is not a wrapped URL, it is returned without changes.

URL parsing security

The urlsplit() and 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 scheme make sense? Is that a sensible path? Is there anything strange about that 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 [https://url.spec.whatwg.org/#concept-basic-url-parser] describes what user facing web clients such as a web browser require. While RFC 3986 [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.

ASCII エンコードバイト列の解析

URL を解析する関数は元々文字列のみ操作するよう設計されていました。実際のところ、それは URL が正しくクオートされエンコードされた ASCII バイト列を操作できた方が有用でした。結果的にこのモジュールの URL 解析関数はすべて bytes および bytearray オブジェクトに加えて str オブジェクトでも処理するようになりました。

str データが渡された場合、戻り値は str データのみを含んだものになります。bytes あるいは bytearray が渡された場合、戻り値は bytes データのみを含んだものになります。

単一の関数を呼び出す時に bytes または bytearray が混在した str を渡した場合、TypeError が、非 ASCII バイト値が渡された場合 UnicodeDecodeError が送出されます。

str と bytes 間で容易に変換を行えるよう、すべての URL 解析関数は encode() メソッド (結果に str データが含まれる時用) か decode() メソッド (結果に bytes データが含まれる時用) のどちらかを提供しています。これらメソッドの動作は対応する str と bytes メソッドが持つものと同じです (ただしデフォルトのエンコーディングは 'utf-8' ではなく 'ascii' になります)。それぞれは encode() メソッドを持つ bytes データか decode() メソッドを持つ str データのどちらかに対応した型を生成します。

非 ASCII データを含むなど、不適切にクオートされた URL を操作する可能性のあるアプリケーションでは、URL 解析メソッドを呼び出す前に独自にバイト列から文字列にデコードする必要があります。

この項で説明された挙動は URL 解析関数にのみ該当します。URL クオート関数でバイトシーケンスを生成もしくは消化する際には、別にURL クオート関数の項で詳説されている通りのルールに従います。

バージョン 3.2 で変更: URL 解析関数は ASCII エンコードバイトシーケンスも受け付けるようになりました

構造化された解析結果

urlparse()、urlsplit()、および urldefrag() 関数が返すオブジェクトは tuple 型のサブクラスになります。これらサブクラスにはそれぞれの関数で説明されている属性が追加されており、前述のとおりエンコーディングとデコーディングをサポートしています:

urllib.parse.SplitResult.geturl()

オリジナルの URL を再結合した場合は文字列で返されます。これはスキームが小文字に正規化されていたり、空の構成要素が除去されるなど、オリジナルの URL とは異なる場合があります。特に、空のパラメータ、クエリ、およびフラグメント識別子は削除されます。

urldefrag() の戻り値では、空のフラグメント識別子のみ削除されます。urlsplit() および urlparse() の戻り値では、このメソッドが返す URL には説明されているすべての変更が加えられます。

加えた解析関数を逆に行えばこのメソッドの戻り値は元の URL になります:

>>> 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/'

以下のクラスは str オブジェクトを操作した場合、構造化された解析結果の実装を提供します:

class urllib.parse.DefragResult(url, fragment)

urldefrag() の具象クラスの結果には str データが含まれます。encode() メソッドは DefragResultBytes インスタンスを返します。

Added in version 3.2.

class urllib.parse.ParseResult(scheme, netloc, path, params, query, fragment)

urlparse() の具象クラスの結果には str データが含まれます。encode() メソッドは ParseResultBytes インスタンスを返します。

class urllib.parse.SplitResult(scheme, netloc, path, query, fragment)

urlsplit() の具象クラスの結果には str データが含まれます。encode() メソッドは SplitResultBytes インスタンスを返します。

以下のクラスは bytes または bytearray オブジェクトを操作した時に解析結果の実装を提供します:

class urllib.parse.DefragResultBytes(url, fragment)

urldefrag() の具象クラスの結果には bytes データが含まれます。decode() メソッドは DefragResult インスタンスを返します。

Added in version 3.2.

class urllib.parse.ParseResultBytes(scheme, netloc, path, params, query, fragment)

urlparse() の具象クラスの結果には bytes が含まれます。decode() メソッドは ParseResult インスタンスを返します。

Added in version 3.2.

class urllib.parse.SplitResultBytes(scheme, netloc, path, query, fragment)

urlsplit() の具象クラスの結果には bytes データが含まれます。decode() メソッドは SplitResult インスタンスを返します。

Added in version 3.2.

URL のクオート

URL クオート関数は、プログラムデータを取り URL 構成要素として使用できるよう特殊文字をクオートしたり非 ASCII 文字を適切にエンコードすることに焦点を当てています。これらは上述の URL 解析関数でカバーされていない URL 構成要素からオリジナルデータの再作成もサポートしています。

urllib.parse.quote(string, safe='/', encoding=None, errors=None)

Replace special characters in string using the %xx escape. Letters, digits, and the characters '_.-~' 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 '/'.

string に使用できるのは str か bytes オブジェクトです。

バージョン 3.7 で変更: Moved from RFC 2396 [https://datatracker.ietf.org/doc/html/rfc2396.html] to RFC 3986 [https://datatracker.ietf.org/doc/html/rfc3986.html] for quoting URL strings. "~" is now included in the set of unreserved characters.

任意のパラメータ encoding と errors は str.encode() で受け付けられる非 ASCII 文字への対処法を指定します。encoding のデフォルトは 'utf-8'、errors のデフォルトは 'strict' で、非サポート文字があると UnicodeEncodeError を送出します。string が bytes の場合 encoding と errors を指定してはいけません。指定すると TypeError が送出されます。

quote(string, safe, encoding, errors) は quote_from_bytes(string.encode(encoding, errors), safe) と等価であることに留意してください。

例: quote('/El Niño/') は '/El%20Ni%C3%B1o/' を返します。

urllib.parse.quote_plus(string, safe='', encoding=None, errors=None)

Like 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 '/'.

例: quote_plus('/El Niño/') は '%2FEl+Ni%C3%B1o%2F' を返します。

urllib.parse.quote_from_bytes(bytes, safe='/')

quote() と似ていますが、str ではなく bytes オブジェクトを取り、文字列からバイト列へのエンコードを行いません。

例: quote_from_bytes(b'a&\xef') は 'a%26%EF' を返します。

urllib.parse.unquote(string, encoding='utf-8', errors='replace')

Replace %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 bytes.decode() method.

string に使用できるのは str か bytes オブジェクトです。

encoding のデフォルトは 'utf-8'、errors のデフォルトは 'replace' で、不正なシーケンスはプレースホルダー文字に置き換えられます。

例: unquote('/El%20Ni%C3%B1o/') は '/El Niño/' を返します。

バージョン 3.9 で変更: string parameter supports bytes and str objects (previously only str).

urllib.parse.unquote_plus(string, encoding='utf-8', errors='replace')

unquote() と似ていますが、HTML フォームの値のアンクオートのために「+」を空白に置き換えます。

string は str でなければなりません。

例: unquote_plus('/El+Ni%C3%B1o/') は '/El Niño/' を返します。

urllib.parse.unquote_to_bytes(string)

Replace %xx escapes with their single-octet equivalent, and return a bytes object.

string に使用できるのは str か bytes オブジェクトです。

str だった場合、string 内のエスケープされていない非 ASCII 文字は UTF-8 バイト列にエンコードされます。

例: unquote_to_bytes('a%26%EF') は b'a&\xef' を返します。

urllib.parse.urlencode(query, doseq=False, safe='', encoding=None, errors=None, quote_via=quote_plus)

マッピング型オブジェクトまたは 2 個の要素からなるタプルのシーケンス (str か bytes オブジェクトが含まれているかもしれません) を、パーセントエンコードされた ASCII 文字列に変換します。戻り値の文字列が urlopen() 関数での POST 操作の data で使用される場合はバイト列にエンコードしなければなりません。そうでない場合は TypeError が送出されます。

戻り値は '&' 文字で区切られた key=value のペアからなる一組の文字列になります。 key と value は quote_via を使用してクオートされます。デフォルトで、値をクォートするために quote_plus() が使用されます。つまり、スペースは '+' 文字に、 '/' 文字は %2F にクォートされます。これは GET リクエストの標準に準拠します (application/x-www-form-urlencoded)。 quote_via として渡すことができる別の関数は quote() です。それはスペースを %20 にエンコードし、 '/' をエンコードしません。何がクォートされるかを最大限コントロールしたければ、 quote を使って safe に値を指定してください。

引数 query が 2 要素のタプルのシーケンスの場合、各タプルの第一要素はキーに、第二要素は値になります。値となる要素はシーケンスを取ることもでき、この場合、オプションのパラメーター doseq が True と評価されるのであれば、キーに対し値シーケンスの各要素を個別に結び付けた key=value のペアを、 '&' 文字でつないだものを生成します。エンコードされた文字列内のパラメーターの順序はシーケンス内のパラメータータプルの順序と一致します。

safe, encoding, および errors パラメータは quote_via にそのまま渡されます (クエリ要素が str の場合は、 encoding と errors パラメータだけが渡されます)。

このエンコード処理の逆を行うには、このモジュールで提供されている parse_qs() と parse_qsl() を使用して、クエリ文字列を Python データ構造に変換できます。

POST リクエストのデータ、あるいは URL クエリ文字列を生成するために、 urllib.parse.urlencode() メソッドをどのように使えばよいかを見るには、urllib の使用例 を参照してください。

バージョン 3.2 で変更: query はバイト列と文字列オブジェクトをサポートします。

バージョン 3.5 で変更: Added the quote_via parameter.

参考

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

RFC 3986 [https://datatracker.ietf.org/doc/html/rfc3986.html] - Uniform Resource Identifiers

これが現在の標準規格 (STD66) です。urllib.parse モジュールに対するすべての変更はこの規格に準拠していなければなりませんが、若干の逸脱はありえます。これは主には後方互換性のため、また主要なブラウザで一般的に見られる、URL を解析する上でのいくつかの事実上の要件を満たすためです。

RFC 2732 [https://datatracker.ietf.org/doc/html/rfc2732.html] - Format for Literal IPv6 Addresses in URL's.

この規格は IPv6 の URL を解析するときの要求事項を記述しています。

RFC 2396 [https://datatracker.ietf.org/doc/html/rfc2396.html] - Uniform Resource Identifiers (URI): Generic Syntax

この RFC では Uniform Resource Name (URN) と Uniform Resource Locator (URL) の両方に対する一般的な文法的要求事項を記述しています。

RFC 2368 [https://datatracker.ietf.org/doc/html/rfc2368.html] - The mailto URL scheme.

mailto URL スキームに対する文法的要求事項です。

RFC 1808 [https://datatracker.ietf.org/doc/html/rfc1808.html] - Relative Uniform Resource Locators

この RFC には絶対 URL と相対 URL を結合するための規則がボーダケースの取扱い方を決定する "異常な例" つきで収められています。

RFC 1738 [https://datatracker.ietf.org/doc/html/rfc1738.html] - Uniform Resource Locators (URL)

この RFC では絶対 URL の形式的な文法と意味付けを仕様化しています。

urllib.error --- Exception classes raised by urllib.request

ソースコード: Lib/urllib/error.py [https://github.com/python/cpython/tree/3.12/Lib/urllib/error.py]

urllib.error は urllib.request によって投げられる例外を定義しています。基底クラスは URLError です。

urllib.error は必要に応じて以下の例外が送出します:

exception urllib.error.URLError

ハンドラが何らかの問題に遭遇した場合、この例外 (またはこの例外から派生した例外)を送出します。この例外は OSError のサブクラスです。

reason

このエラーの理由。メッセージ文字列あるいは他の例外インスタンスです。

バージョン 3.3 で変更: URLError used to be a subtype of IOError, which is now an alias of OSError.

exception urllib.error.HTTPError(url, code, msg, hdrs, fp)

HTTPError は例外 (URLError のサブクラス) ですが、同時に例外ではない file-like な戻り値を返す関数でもあります (urlopen() の戻り値と同じです)。これは、例えばサーバからの認証リクエストのように、変わった HTTP エラーを処理するのに役立ちます。

url

Contains the request URL. An alias for filename attribute.

code

RFC 2616 [https://datatracker.ietf.org/doc/html/rfc2616.html] に定義されているHTTPステータスコード。この数値型の値は、 http.server.BaseHTTPRequestHandler.responses の辞書に登録されているコードに対応します。

reason

This is usually a string explaining the reason for this error. An alias for msg attribute.

headers

The HTTP response headers for the HTTP request that caused the HTTPError. An alias for hdrs attribute.

Added in version 3.4.

fp

A file-like object where the HTTP error body can be read from.

exception urllib.error.ContentTooShortError(msg, content)

This exception is raised when the urlretrieve() function detects that the amount of the downloaded data is less than the expected amount (given by the Content-Length header).

content

The downloaded (and supposedly truncated) data.

urllib.robotparser --- Parser for robots.txt

ソースコード: Lib/urllib/robotparser.py [https://github.com/python/cpython/tree/3.12/Lib/urllib/robotparser.py]

このモジュールでは単一のクラス、 RobotFileParser を提供します。このクラスは、特定のユーザエージェントが robots.txt ファイルを公開している Web サイトのある URL を取得可能かどうかの質問に答えます。 robots.txt ファイルの構造に関する詳細は http://www.robotstxt.org/orig.html を参照してください。

class urllib.robotparser.RobotFileParser(url='')

url の robots.txt に対し読み込み、パーズ、応答するメソッドを提供します。

set_url(url)

robots.txt ファイルを参照するための URL を設定します。

read()

robots.txt URL を読み出し、パーザに入力します。

parse(lines)

引数 lines の内容を解釈します。

can_fetch(useragent, url)

解釈された robots.txt ファイル中に記載された規則に従ったとき、 useragent が url を取得してもよい場合には True を返します。

mtime()

robots.txt ファイルを最後に取得した時刻を返します。この値は、定期的に新たな robots.txt をチェックする必要がある、長時間動作する Web スパイダープログラムを実装する際に便利です。

modified()

robots.txt ファイルを最後に取得した時刻を現在の時刻に設定します。

crawl_delay(useragent)

Returns the value of the Crawl-delay parameter from robots.txt for the useragent in question. If there is no such parameter or it doesn't apply to the useragent specified or the robots.txt entry for this parameter has invalid syntax, return None.

Added in version 3.6.

request_rate(useragent)

Returns the contents of the Request-rate parameter from robots.txt as a named tuple RequestRate(requests, seconds). If there is no such parameter or it doesn't apply to the useragent specified or the robots.txt entry for this parameter has invalid syntax, return None.

Added in version 3.6.

site_maps()

Returns the contents of the Sitemap parameter from robots.txt in the form of a list(). If there is no such parameter or the robots.txt entry for this parameter has invalid syntax, return None.

Added in version 3.8.

以下に RobotFileParser クラスの利用例を示します。

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

http --- HTTP modules

ソースコード: Lib/http/__init__.py [https://github.com/python/cpython/tree/3.12/Lib/http/__init__.py]

http パッケージはハイパーテキスト転送プロトコルを扱うための幾つかのモジュールを集めたものです:

http.client は低水準のHTTPプロトコルのクライアントです。高水準の URL を開く操作には urllib.request を使ってください

http.server は socketserver をベースにした基礎的な HTTP サーバーを実装しています

http.cookies は cookie の状態管理を実装するためのユーティリティーを提供しています

http.cookiejar は cookie の永続化機能を提供しています

The http module also defines the following enums that help you work with http related code:

class http.HTTPStatus

Added in version 3.5.

一連の HTTP ステータスコード、理由の表現、英語で書かれた長い記述を定義した enum.IntEnum のサブクラスです。

使い方:

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

HTTP ステータスコード

http.HTTPStatus で利用可能な、サポートされている、IANA に登録されたステータスコード <https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml>`_ は:

コード

列挙名

詳細

100

CONTINUE

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.2.1

101

SWITCHING_PROTOCOLS

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.2.2

102

PROCESSING

WebDAV RFC 2518 [https://datatracker.ietf.org/doc/html/rfc2518.html], Section 10.1

103

EARLY_HINTS

An HTTP Status Code for Indicating Hints RFC 8297 [https://datatracker.ietf.org/doc/html/rfc8297.html]

200

OK

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.3.1

201

CREATED

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.3.2

202

ACCEPTED

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.3.3

203

NON_AUTHORITATIVE_INFORMATION

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.3.4

204

NO_CONTENT

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.3.5

205

RESET_CONTENT

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.3.6

206

PARTIAL_CONTENT

HTTP/1.1 RFC 7233 [https://datatracker.ietf.org/doc/html/rfc7233.html], Section 4.1

207

MULTI_STATUS

WebDAV RFC 4918 [https://datatracker.ietf.org/doc/html/rfc4918.html], Section 11.1

208

ALREADY_REPORTED

WebDAV Binding Extensions RFC 5842 [https://datatracker.ietf.org/doc/html/rfc5842.html], Section 7.1 (Experimental)

226

IM_USED

Delta Encoding in HTTP RFC 3229 [https://datatracker.ietf.org/doc/html/rfc3229.html], Section 10.4.1

300

MULTIPLE_CHOICES

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.4.1

301

MOVED_PERMANENTLY

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.4.2

302

FOUND

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.4.3

303

SEE_OTHER

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.4.4

304

NOT_MODIFIED

HTTP/1.1 RFC 7232 [https://datatracker.ietf.org/doc/html/rfc7232.html], Section 4.1

305

USE_PROXY

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.4.5

307

TEMPORARY_REDIRECT

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.4.7

308

PERMANENT_REDIRECT

Permanent Redirect RFC 7238 [https://datatracker.ietf.org/doc/html/rfc7238.html], Section 3 (Experimental)

400

BAD_REQUEST

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.5.1

401

UNAUTHORIZED

HTTP/1.1 Authentication RFC 7235 [https://datatracker.ietf.org/doc/html/rfc7235.html], Section 3.1

402

PAYMENT_REQUIRED

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.5.2

403

FORBIDDEN

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.5.3

404

NOT_FOUND

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.5.4

405

METHOD_NOT_ALLOWED

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.5.5

406

NOT_ACCEPTABLE

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.5.6

407

PROXY_AUTHENTICATION_REQUIRED

HTTP/1.1 Authentication RFC 7235 [https://datatracker.ietf.org/doc/html/rfc7235.html], Section 3.2

408

REQUEST_TIMEOUT

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.5.7

409

CONFLICT

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.5.8

410

GONE

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.5.9

411

LENGTH_REQUIRED

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.5.10

412

PRECONDITION_FAILED

HTTP/1.1 RFC 7232 [https://datatracker.ietf.org/doc/html/rfc7232.html], Section 4.2

413

REQUEST_ENTITY_TOO_LARGE

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.5.11

414

REQUEST_URI_TOO_LONG

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.5.12

415

UNSUPPORTED_MEDIA_TYPE

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.5.13

416

REQUESTED_RANGE_NOT_SATISFIABLE

HTTP/1.1 Range Requests RFC 7233 [https://datatracker.ietf.org/doc/html/rfc7233.html], Section 4.4

417

EXPECTATION_FAILED

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.5.14

418

IM_A_TEAPOT

HTCPCP/1.0 RFC 2324 [https://datatracker.ietf.org/doc/html/rfc2324.html], Section 2.3.2

421

MISDIRECTED_REQUEST

HTTP/2 RFC 7540 [https://datatracker.ietf.org/doc/html/rfc7540.html], Section 9.1.2

422

UNPROCESSABLE_ENTITY

WebDAV RFC 4918 [https://datatracker.ietf.org/doc/html/rfc4918.html], Section 11.2

423

LOCKED

WebDAV RFC 4918 [https://datatracker.ietf.org/doc/html/rfc4918.html], Section 11.3

424

FAILED_DEPENDENCY

WebDAV RFC 4918 [https://datatracker.ietf.org/doc/html/rfc4918.html], Section 11.4

425

TOO_EARLY

Using Early Data in HTTP RFC 8470 [https://datatracker.ietf.org/doc/html/rfc8470.html]

426

UPGRADE_REQUIRED

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.5.15

428

PRECONDITION_REQUIRED

Additional HTTP Status Codes RFC 6585 [https://datatracker.ietf.org/doc/html/rfc6585.html]

429

TOO_MANY_REQUESTS

Additional HTTP Status Codes RFC 6585 [https://datatracker.ietf.org/doc/html/rfc6585.html]

431

REQUEST_HEADER_FIELDS_TOO_LARGE

Additional HTTP Status Codes RFC 6585 [https://datatracker.ietf.org/doc/html/rfc6585.html]

451

UNAVAILABLE_FOR_LEGAL_REASONS

An HTTP Status Code to Report Legal Obstacles RFC 7725 [https://datatracker.ietf.org/doc/html/rfc7725.html]

500

INTERNAL_SERVER_ERROR

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.6.1

501

NOT_IMPLEMENTED

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.6.2

502

BAD_GATEWAY

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.6.3

503

SERVICE_UNAVAILABLE

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.6.4

504

GATEWAY_TIMEOUT

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.6.5

505

HTTP_VERSION_NOT_SUPPORTED

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6.6.6

506

VARIANT_ALSO_NEGOTIATES

Transparent Content Negotiation in HTTP RFC 2295 [https://datatracker.ietf.org/doc/html/rfc2295.html], Section 8.1 (Experimental)

507

INSUFFICIENT_STORAGE

WebDAV RFC 4918 [https://datatracker.ietf.org/doc/html/rfc4918.html], Section 11.5

508

LOOP_DETECTED

WebDAV Binding Extensions RFC 5842 [https://datatracker.ietf.org/doc/html/rfc5842.html], Section 7.2 (Experimental)

510

NOT_EXTENDED

An HTTP Extension Framework RFC 2774 [https://datatracker.ietf.org/doc/html/rfc2774.html], Section 7 (Experimental)

511

NETWORK_AUTHENTICATION_REQUIRED

Additional HTTP Status Codes RFC 6585 [https://datatracker.ietf.org/doc/html/rfc6585.html], Section 6

後方互換性を保つために列挙値は http.client にも定数という形で存在します。列挙名は定数名と同じです (すなわち http.HTTPStatus.OK は http.client.OK としても利用可能です)。

バージョン 3.7 で変更: ステータスコード 421 MISDIRECTED_REQUEST が追加されました。

Added in version 3.8: ステータスコード 451 UNAVAILABLE_FOR_LEGAL_REASONS が追加されました。

Added in version 3.9: ステータスコード 103 EARLY_HINTS, 418 IM_A_TEAPOT, 425 TOO_EARLY が追加されました。

HTTP status category

Added in version 3.12.

The enum values have several properties to indicate the HTTP status category:

Property

Indicates that

詳細

is_informational

100 <= status <= 199

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6

is_success

200 <= status <= 299

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6

is_redirection

300 <= status <= 399

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6

is_client_error

400 <= status <= 499

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6

is_server_error

500 <= status <= 599

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 6

使い方:

>>> from http import HTTPStatus
>>> HTTPStatus.OK.is_success
True
>>> HTTPStatus.OK.is_client_error
False

class http.HTTPMethod

Added in version 3.11.

一連の HTTP メソッド、英語で書かれた記述を定義した enum.StrEnum のサブクラスです。

使い方:

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

HTTP methods

http.HTTPMethod で利用可能な、サポートされている、IANA に登録されたメソッド [https://www.iana.org/assignments/http-methods/http-methods.xhtml] は:

メソッド

列挙名

詳細

GET

GET

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 4.3.1

HEAD

HEAD

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 4.3.2

POST

POST

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 4.3.3

PUT

PUT

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 4.3.4

DELETE

DELETE

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 4.3.5

CONNECT

CONNECT

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 4.3.6

OPTIONS

OPTIONS

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 4.3.7

TRACE

TRACE

HTTP/1.1 RFC 7231 [https://datatracker.ietf.org/doc/html/rfc7231.html], Section 4.3.8

PATCH

PATCH

HTTP/1.1 RFC 5789 [https://datatracker.ietf.org/doc/html/rfc5789.html]

http.client --- HTTP protocol client

ソースコード: Lib/http/client.py [https://github.com/python/cpython/tree/3.12/Lib/http/client.py]

このモジュールでは HTTP および HTTPS プロトコルのクライアントサイドを実装しているクラスを定義しています。通常、このモジュールは直接使いません --- urllib.request モジュールが HTTP や HTTPS を使った URL を扱う上でこのモジュールを使います。

参考

The Requests package [https://requests.readthedocs.io/en/latest/] is recommended for a higher-level HTTP client interface.

注釈

HTTPS のサポートは、Python が SSL サポート付きでコンパイルされている場合にのみ利用できます (ssl モジュールによって)。

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. See WebAssemblyプラットフォーム for more information.

このモジュールでは以下のクラスを提供しています:

class http.client.HTTPConnection(host, port=None, [timeout, ]source_address=None, blocksize=8192)

HTTPConnection インスタンスは、HTTP サーバとの一回のトランザクションを表現します。インスタンスの生成はホスト名とオプションのポート番号を与えることで行います。ポート番号を指定しなかった場合、ホスト名文字列が host:port の形式であれば、ホスト名からポート番号を抽出し、そうでない場合には標準の HTTP ポート番号 (80) を使います。オプションの引数 timeout が渡された場合、ブロックする処理 (コネクション接続など) のタイムアウト時間(秒数)として利用されます (渡されなかった場合は、グローバルのデフォルトタイムアウト設定が利用されます)。オプションの引数 source_address を (host, port) という形式のタプルにすると HTTP 接続の接続元アドレスとして使用します。オプションの blocksize 引数は、送信するファイル類メッセージボディのバッファサイズをバイト単位で設定します。

例えば、以下の呼び出しは全て同じサーバの同じポートに接続するインスタンスを生成します:

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

バージョン 3.2 で変更: source_address が追加されました。

バージョン 3.4 で変更: strict パラメータは廃止されました。HTTP 0.9 の "シンプルなレスポンス" のような形式はもはやサポートされません。

バージョン 3.7 で変更: blocksize 引数が追加されました。

class http.client.HTTPSConnection(host, port=None, *, [timeout, ]source_address=None, context=None, blocksize=8192)

HTTPConnection のサブクラスはセキュア・サーバとやりとりする為の SSL を使う場合に用います。デフォルトのポート番号は 443 です。context が指定されれば、それは様々な SSL オプションを記述する ssl.SSLContext インスタンスでなければなりません。

ベストプラクティスに関するより良い情報が セキュリティで考慮すべき点 にありますのでお読みください。

バージョン 3.2 で変更: source_address、context そして check_hostname が追加されました。

バージョン 3.2 で変更: This class now supports HTTPS virtual hosts if possible (that is, if ssl.HAS_SNI is true).

バージョン 3.4 で変更: strict パラメータは廃止されました。HTTP 0.9 の "シンプルなレスポンス" のような形式はもはやサポートされません。

バージョン 3.4.3 で変更: This class now performs all the necessary certificate and hostname checks by default. To revert to the previous, unverified, behavior ssl._create_unverified_context() can be passed to the context parameter.

バージョン 3.8 で変更: This class now enables TLS 1.3 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 http/1.1 when no context is given. Custom context should set ALPN protocols with set_alpn_protocols().

バージョン 3.12 で変更: The deprecated key_file, cert_file and check_hostname parameters have been removed.

class http.client.HTTPResponse(sock, debuglevel=0, method=None, url=None)

コネクションに成功したときに、このクラスのインスタンスが返されます。ユーザーから直接利用されることはありません。

バージョン 3.4 で変更: strict パラメータは廃止されました。HTTP 0.9 の "シンプルなレスポンス" のような形式はもはやサポートされません。

このモジュールは以下の関数を提供します:

http.client.parse_headers(fp)

Parse the headers from a file pointer fp representing a HTTP request/response. The file has to be a BufferedIOBase reader (i.e. not text) and must provide a valid RFC 2822 [https://datatracker.ietf.org/doc/html/rfc2822.html] style header.

This function returns an instance of http.client.HTTPMessage that holds the header fields, but no payload (the same as HTTPResponse.msg and http.server.BaseHTTPRequestHandler.headers). After returning, the file pointer fp is ready to read the HTTP body.

注釈

parse_headers() does not parse the start-line of a HTTP message; it only parses the 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.

状況に応じて、以下の例外が送出されます:

exception http.client.HTTPException

このモジュールにおける他の例外クラスの基底クラスです。 Exception のサブクラスです。

exception http.client.NotConnected

HTTPException サブクラスです。

exception http.client.InvalidURL

HTTPException のサブクラスです。ポート番号を指定したものの、その値が数字でなかったり空のオブジェクトであった場合に送出されます。

exception http.client.UnknownProtocol

HTTPException サブクラスです。

exception http.client.UnknownTransferEncoding

HTTPException サブクラスです。

exception http.client.UnimplementedFileMode

HTTPException サブクラスです。

exception http.client.IncompleteRead

HTTPException サブクラスです。

exception http.client.ImproperConnectionState

HTTPException サブクラスです。

exception http.client.CannotSendRequest

ImproperConnectionState のサブクラスです。

exception http.client.CannotSendHeader

ImproperConnectionState のサブクラスです。

exception http.client.ResponseNotReady

ImproperConnectionState のサブクラスです。

exception http.client.BadStatusLine

HTTPException のサブクラスです。サーバが理解できない HTTP 状態コードで応答した場合に送出されます。

exception http.client.LineTooLong

A subclass of HTTPException. Raised if an excessively long line is received in the HTTP protocol from the server.

exception http.client.RemoteDisconnected

A subclass of ConnectionResetError and BadStatusLine. Raised by HTTPConnection.getresponse() when the attempt to read the response results in no data read from the connection, indicating that the remote end has closed the connection.

Added in version 3.5: Previously, BadStatusLine('') was raised.

このモジュールで定義されている定数は以下の通りです:

http.client.HTTP_PORT

HTTP プロトコルの標準のポート (通常は 80) です。

http.client.HTTPS_PORT

HTTPS プロトコルの標準のポート (通常は 443) です。

http.client.responses

このディクショナリは、HTTP 1.1ステータスコードをW3Cの名前にマップしたものです。

例: http.client.responses[http.client.NOT_FOUND] は 'Not Found' を示します。

See HTTP ステータスコード for a list of HTTP status codes that are available in this module as constants.

HTTPConnection オブジェクト

HTTPConnection インスタンスには以下のメソッドがあります:

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 RFC 2616 §5.1.2 [https://datatracker.ietf.org/doc/html/rfc2616.html#section-5.1.2] (unless connecting to an HTTP proxy server or using the OPTIONS or CONNECT methods).

If body is specified, the specified data is sent after the headers are finished. It may be a str, a bytes-like object, an open file object, or an iterable of bytes. If body is a string, it is encoded as ISO-8859-1, the default for HTTP. If it is a bytes-like object, the bytes are sent as is. If it is a file object, the contents of the file is sent; this file object should support at least the read() method. If the file object is an instance of io.TextIOBase, the data returned by the read() method will be encoded as ISO-8859-1, otherwise the data returned by 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 Host header [https://datatracker.ietf.org/doc/html/rfc2616.html#section-14.23] must be provided to conform with RFC 2616 §5.1.2 [https://datatracker.ietf.org/doc/html/rfc2616.html#section-5.1.2] (unless connecting to an HTTP proxy server or using the OPTIONS or 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 None, the Content-Length header is set to 0 for methods that expect a body (PUT, POST, and PATCH). If body is a string or a bytes-like object that is not also a 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 False, the HTTPConnection object assumes that all encoding is handled by the calling code. If it is True, the body will be chunk-encoded.

For example, to perform a GET request to https://docs.python.org/3/:

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

注釈

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 str or bytes-like object that is not also a file as the body representation.

バージョン 3.2 で変更: body は 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.

HTTPConnection.getresponse()

サーバに対して HTTP 要求を送り出した後に呼び出されなければりません。要求に対する応答を取得します。 HTTPResponse インスタンスを返します。

注釈

すべての応答を読み込んでからでなければ新しい要求をサーバに送ることはできないことに注意しましょう。

バージョン 3.5 で変更: If a ConnectionError or subclass is raised, the HTTPConnection object will be ready to reconnect when a new request is sent.

HTTPConnection.set_debuglevel(level)

Set the debugging level. The default debug level is 0, meaning no debugging output is printed. Any value greater than 0 will cause all currently defined debug output to be printed to stdout. The debuglevel is passed to any new HTTPResponse objects that are created.

Added in version 3.1.

HTTPConnection.set_tunnel(host, port=None, headers=None)

HTTP トンネリング接続のホスト名とポート番号を設定します。これによりプロキシサーバを通しての接続を実行できます。

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 [https://datatracker.ietf.org/doc/html/rfc7231#section-4.3.6], a HTTP Host: header must be provided, matching the authority-form of the request target provided as the destination for the CONNECT request. If a HTTP 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 HTTPSConnection constructor, and the address of the host that we eventually want to reach to the set_tunnel() method:

>>> import http.client
>>> conn = http.client.HTTPSConnection("localhost", 8080)
>>> conn.set_tunnel("www.python.org")
>>> conn.request("HEAD","/index.html")

Added in version 3.2.

バージョン 3.12 で変更: HTTP CONNECT tunnelling requests use protocol HTTP/1.1, upgraded from protocol HTTP/1.0. Host: HTTP headers are mandatory for HTTP/1.1, so one will be automatically generated and transmitted if not provided in the headers argument.

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

Added in version 3.12.

HTTPConnection.connect()

Connect to the server specified when the object was created. By default, this is called automatically when making a request if the client does not already have a connection.

Raises an auditing event http.client.connect with arguments self, host, port.

HTTPConnection.close()

サーバへの接続を閉じます。

HTTPConnection.blocksize

Buffer size in bytes for sending a file-like message body.

Added in version 3.7.

As an alternative to using the request() method described above, you can also send your request step by step, by using the four functions below.

HTTPConnection.putrequest(method, url, skip_host=False, skip_accept_encoding=False)

サーバへの接続が確立したら、最初にこのメソッドを呼び出さなくてはなりません。このメソッドは method 文字列、url 文字列、そして HTTP バージョン (HTTP/1.1) からなる一行を送信します。Host: や Accept-Encoding: ヘッダの自動送信を無効にしたい場合 (例えば別のコンテンツエンコーディングを受け入れたい場合) には、skip_host や skip_accept_encoding を偽でない値に設定してください。

HTTPConnection.putheader(header, argument[, ...])

RFC 822 [https://datatracker.ietf.org/doc/html/rfc822.html] 形式のヘッダをサーバに送ります。この処理では、 header 、コロンとスペース、そして最初の引数からなる 1 行をサーバに送ります。追加の引数を指定した場合、継続して各行にタブ一つと引数の入った引数行が送信されます。

HTTPConnection.endheaders(message_body=None, *, encode_chunked=False)

サーバに空行を送り、ヘッダ部が終了したことを通知します。オプションの message_body 引数を、リクエストに関連したメッセージボディを渡すのに使うことが出来ます。

If encode_chunked is True, the result of each iteration of message_body will be chunk-encoded as specified in RFC 7230 [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 buffer interface the encoding will result in a single chunk. If message_body is a collections.abc.Iterable, each iteration of message_body will result in a chunk. If message_body is a file object, each call to .read() will result in a chunk. The method automatically signals the end of the chunk-encoded data immediately after message_body.

注釈

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.

バージョン 3.6 で変更: Added chunked encoding support and the encode_chunked parameter.

HTTPConnection.send(data)

サーバにデータを送ります。このメソッドは endheaders() が呼び出された直後で、かつ getresponse() が呼び出される前に使わなければなりません。

Raises an auditing event http.client.send with arguments self, data.

HTTPResponse オブジェクト

HTTPResponse インスタンスはサーバからのHTTPレスポンスをラップします。これを使用してリクエストヘッダとエンティティボディへアクセスすることができます。レスポンスはイテレート可能なオブジェクトであり、また with文と使うことも可能です。

バージョン 3.5 で変更: The io.BufferedIOBase interface is now implemented and all of its reader operations are supported.

HTTPResponse.read([amt])

応答の本体全体か、amt バイトまで読み出して返します。

HTTPResponse.readinto(b)

バッファ b にレスポンスボディの次のデータを最大 len(b) バイト読み込みます。何バイト読んだかを返します。

Added in version 3.3.

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.

HTTPResponse.getheaders()

(header, value) のタプルからなるリストを返します。

HTTPResponse.fileno()

ソケットの fileno を返します。

HTTPResponse.msg

A http.client.HTTPMessage instance containing the response headers. http.client.HTTPMessage is a subclass of email.message.Message.

HTTPResponse.version

サーバが使用した HTTP プロトコルバージョンです。10 は HTTP/1.0 を、11 は HTTP/1.1 を表します。

HTTPResponse.url

取得されたリソースの URL、主にリダイレクトが発生したかどうかを確認するために利用します。

HTTPResponse.headers

Headers of the response in the form of an email.message.EmailMessage instance.

HTTPResponse.status

サーバから返される状態コードです。

HTTPResponse.reason

サーバから返される応答の理由文です。

HTTPResponse.debuglevel

A debugging hook. If debuglevel is greater than zero, messages will be printed to stdout as the response is read and parsed.

HTTPResponse.closed

ストリームが閉じている場合 True となります。

HTTPResponse.geturl()

バージョン 3.9 で非推奨: 非推奨となったので url を使用してください。

HTTPResponse.info()

バージョン 3.9 で非推奨: 非推奨となったので headers を使用してください。

HTTPResponse.getcode()

バージョン 3.9 で非推奨: 非推奨となったので status を使用してください。

使用例

以下は GET リクエストの送信方法を示した例です:

>>> 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()

次の例のセッションでは、HEAD メソッドを利用しています。HEAD メソッドは全くデータを返さないことに注目してください。

>>> 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''
True

Here is an example session that uses the POST method:

>>> 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()

Client side HTTP PUT requests are very similar to POST requests. The difference lies only on the server side where HTTP servers will allow resources to be created via PUT requests. It should be noted that custom HTTP methods are also handled in urllib.request.Request by setting the appropriate method attribute. Here is an example session that uses the PUT method:

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

HTTPMessage オブジェクト

class http.client.HTTPMessage(email.message.Message)

http.client.HTTPMessage のインスタンスは HTTP レスポンスヘッダを格納します。 email.message.Message クラスを利用して実装されています。

ftplib --- FTP protocol client

ソースコード: Lib/ftplib.py [https://github.com/python/cpython/tree/3.12/Lib/ftplib.py]

このモジュールでは FTP クラスと、それに関連するいくつかの項目を定義しています。 FTP クラスは、FTPプロトコルのクライアント側の機能を備えています。このクラスを使うとFTPのいろいろな機能の自動化、例えば他のFTPサーバのミラーリングといったことを実行するPythonプログラムを書くことができます。また、 urllib.request モジュールもFTPを使うURLを操作するのにこのクラスを使っています。 FTP (File Transfer Protocol)についての詳しい情報はinternet RFC 959 [https://datatracker.ietf.org/doc/html/rfc959.html] を参照して下さい。

The default encoding is UTF-8, following RFC 2640 [https://datatracker.ietf.org/doc/html/rfc2640.html].

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. See WebAssemblyプラットフォーム for more information.

ftplib モジュールを使ったサンプルを以下に示します:

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

リファレンス

FTP オブジェクト

class ftplib.FTP(host='', user='', passwd='', acct='', timeout=None, source_address=None, *, encoding='utf-8')

Return a new instance of the FTP class.

パラメータ:

host (str) -- The hostname to connect to. If given, connect(host) is implicitly called by the constructor.

user (str) -- The username to log in with (default: 'anonymous'). If given, login(host, passwd, acct) is implicitly called by the constructor.

passwd (str) -- The password to use when logging in. If not given, and if passwd is the empty string or "-", a password will be automatically generated.

acct (str) -- Account information to be used for the ACCT FTP command. Few systems implement this. See RFC-959 [https://datatracker.ietf.org/doc/html/rfc959.html] for more details.

timeout (float | None) -- A timeout in seconds for blocking operations like connect() (default: the global default timeout setting).

source_address (tuple | None) -- A 2-tuple (host, port) for the socket to bind to as its source address before connecting.

encoding (str) -- The encoding for directories and filenames (default: 'utf-8').

FTP クラスは with 文をサポートしています。例えば:

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

バージョン 3.2 で変更: with 構文のサポートが追加されました。

バージョン 3.3 で変更: source_address 引数が追加されました。

バージョン 3.9 で変更: If the timeout parameter is set to be zero, it will raise a ValueError to prevent the creation of a non-blocking socket. The encoding parameter was added, and the default was changed from Latin-1 to UTF-8 to follow RFC 2640 [https://datatracker.ietf.org/doc/html/rfc2640.html].

Several FTP methods are available in two flavors: one for handling text files and another for binary files. The methods are named for the command which is used followed by lines for the text version or binary for the binary version.

FTP インスタンスには以下のメソッドがあります:

set_debuglevel(level)

Set the instance's debugging level as an int. This controls the amount of debugging output printed. The debug levels are:

0 (default): No debug output.

1: Produce a moderate amount of debug output, generally a single line per request.

2 or higher: Produce the maximum amount of debugging output, logging each line sent and received on the control connection.

connect(host='', port=0, timeout=None, source_address=None)

Connect to the given host and port. This function should be called only once for each instance; it should not be called if a host argument was given when the FTP instance was created. All other FTP methods can only be called after a connection has successfully been made.

パラメータ:

host (str) -- The host to connect to.

port (int) -- The TCP port to connect to (default: 21, as specified by the FTP protocol specification). It is rarely needed to specify a different port number.

timeout (float | None) -- A timeout in seconds for the connection attempt (default: the global default timeout setting).

source_address (tuple | None) -- A 2-tuple (host, port) for the socket to bind to as its source address before connecting.

引数 self, host, port を指定して 監査イベント ftplib.connect を送出します。

バージョン 3.3 で変更: source_address 引数が追加されました。

getwelcome()

サーバに最初に接続した際に送信される応答中のウェルカムメッセージを返します。(このメッセージには時に、ユーザにとって重要な免責事項や ヘルプ情報が入っています。)

login(user='anonymous', passwd='', acct='')

Log on to the connected FTP server. This function should be called only once for each instance, after a connection has been established; it should not be called if the host and user arguments were given when the FTP instance was created. Most FTP commands are only allowed after the client has logged in.

パラメータ:

user (str) -- The username to log in with (default: 'anonymous').

passwd (str) -- The password to use when logging in. If not given, and if passwd is the empty string or "-", a password will be automatically generated.

acct (str) -- Account information to be used for the ACCT FTP command. Few systems implement this. See RFC-959 [https://datatracker.ietf.org/doc/html/rfc959.html] for more details.

abort()

実行中のファイル転送を中止します。これはいつも機能するわけではありませんが、やってみる価値はあります。

sendcmd(cmd)

シンプルなコマンド文字列をサーバに送信して、受信した文字列を返します。

引数 self, cmd を指定して 監査イベント ftplib.sendcmd を送出します。

voidcmd(cmd)

Send a simple command string to the server and handle the response. Return the response string if the response code corresponds to success (codes in the range 200--299). Raise error_reply otherwise.

引数 self, cmd を指定して 監査イベント ftplib.sendcmd を送出します。

retrbinary(cmd, callback, blocksize=8192, rest=None)

Retrieve a file in binary transfer mode.

パラメータ:

cmd (str) -- An appropriate STOR command: "STOR filename".

callback (callable) -- A single parameter callable that is called for each block of data received, with its single argument being the data as bytes.

blocksize (int) -- The maximum chunk size to read on the low-level socket object created to do the actual transfer. This also corresponds to the largest size of data that will be passed to callback. Defaults to 8192.

rest (int) -- A REST command to be sent to the server. See the documentation for the rest parameter of the transfercmd() method.

retrlines(cmd, callback=None)

Retrieve a file or directory listing in the encoding specified by the encoding parameter at initialization. cmd should be an appropriate RETR command (see retrbinary()) or a command such as LIST or NLST (usually just the string 'LIST'). LIST retrieves a list of files and information about those files. NLST retrieves a list of file names. The callback function is called for each line with a string argument containing the line with the trailing CRLF stripped. The default callback prints the line to sys.stdout.

set_pasv(val)

val が真の場合 "パッシブ" モードを有効化し、偽の場合は無効化します。 デフォルトではパッシブモードです。

storbinary(cmd, fp, blocksize=8192, callback=None, rest=None)

Store a file in binary transfer mode.

パラメータ:

cmd (str) -- An appropriate STOR command: "STOR filename".

fp (file object) -- A file object (opened in binary mode) which is read until EOF, using its read() method in blocks of size blocksize to provide the data to be stored.

blocksize (int) -- The read block size. Defaults to 8192.

callback (callable) -- A single parameter callable that is called for each block of data sent, with its single argument being the data as bytes.

rest (int) -- A REST command to be sent to the server. See the documentation for the rest parameter of the transfercmd() method.

バージョン 3.2 で変更: The rest parameter was added.

storlines(cmd, fp, callback=None)

Store a file in line mode. cmd should be an appropriate STOR command (see storbinary()). Lines are read until EOF from the file object fp (opened in binary mode) using its readline() method to provide the data to be stored. callback is an optional single parameter callable that is called on each line after it is sent.

transfercmd(cmd, rest=None)

データ接続中に転送を初期化します。もし転送中なら、EPRT あるいは PORT コマンドと、cmd で指定したコマンドを送信し、接続を続けます。サーバがパッシブなら、EPSV あるいは PASV コマンドを送信して接続し、転送コマンドを開始します。どちらの場合も、接続のためのソケットを返します。

If optional rest is given, a REST command is sent to the server, passing rest as an argument. rest is usually a byte offset into the requested file, telling the server to restart sending the file's bytes at the requested offset, skipping over the initial bytes. Note however that the transfercmd() method converts rest to a string with the encoding parameter specified at initialization, but no check is performed on the string's contents. If the server does not recognize the REST command, an error_reply exception will be raised. If this happens, simply call transfercmd() without a rest argument.

ntransfercmd(cmd, rest=None)

transfercmd() と同様ですが、データと予想されるサイズとのタプルを返します。もしサイズが計算できないなら、サイズの代わりに None が返されます。 cmd と rest は transfercmd() のものと同じです。

mlsd(path='', facts=[])

List a directory in a standardized format by using MLSD command (RFC 3659 [https://datatracker.ietf.org/doc/html/rfc3659.html]). If path is omitted the current directory is assumed. facts is a list of strings representing the type of information desired (e.g. ["type", "size", "perm"]). Return a generator object yielding a tuple of two elements for every file found in path. First element is the file name, the second one is a dictionary containing facts about the file name. Content of this dictionary might be limited by the facts argument but server is not guaranteed to return all requested facts.

Added in version 3.3.

nlst(argument[, ...])

NLST コマンドで返されるファイル名のリストを返します。省略可能な argument は、リストアップするディレクトリです（デフォルトではサーバのカレントディレクトリです）。 NLST コマンドに非標準である複数の引数を渡すことができます。

注釈

If your server supports the command, mlsd() offers a better API.

dir(argument[, ...])

Produce a directory listing as returned by the LIST command, printing it to standard output. The optional argument is a directory to list (default is the current server directory). Multiple arguments can be used to pass non-standard options to the LIST command. If the last argument is a function, it is used as a callback function as for retrlines(); the default prints to sys.stdout. This method returns None.

注釈

If your server supports the command, mlsd() offers a better API.

rename(fromname, toname)

サーバ上のファイルのファイル名 fromname を toname へ変更します。

delete(filename)

サーバからファイル filename を削除します。成功したら応答のテキストを返し、そうでないならパーミッションエラーでは error_perm を、他のエラーでは error_reply を返します。

cwd(pathname)

サーバのカレントディレクトリを設定します。

mkd(pathname)

サーバ上に新たにディレクトリを作ります。

pwd()

サーバ上のカレントディレクトリのパスを返します。

rmd(dirname)

サーバ上のディレクトリ dirname を削除します。

size(filename)

サーバ上のファイル filename のサイズを尋ねます。成功したらファイルサイズが整数で返され、そうでないなら None が返されます。 SIZE コマンドは標準化されていませんが、多くの普通のサーバで実装されていることに注意して下さい。

quit()

サーバに QUIT コマンドを送信し、接続を閉じます。これは接続を閉じるのに"礼儀正しい"方法ですが、 QUIT コマンドに反応してサーバの例外が発生するかもしれません。この例外は、 close() メソッドによって FTP インスタンスに対するその後のコマンド使用が不可になっていることを示しています（下記参照）。

close()

接続を一方的に閉じます。既に閉じた接続に対して実行すべきではありません（例えば quit() を呼び出して成功した後など）。この実行の後、 FTP インスタンスはもう使用すべきではありません（ close() あるいは quit() を呼び出した後で、 login() メソッドをもう一度実行して再び接続を開くことはできません）。

FTP_TLS オブジェクト

class ftplib.FTP_TLS(host='', user='', passwd='', acct='', *, context=None, timeout=None, source_address=None, encoding='utf-8')

An FTP subclass which adds TLS support to FTP as described in RFC 4217 [https://datatracker.ietf.org/doc/html/rfc4217.html]. Connect to port 21 implicitly securing the FTP control connection before authenticating.

注釈

The user must explicitly secure the data connection by calling the prot_p() method.

パラメータ:

host (str) -- The hostname to connect to. If given, connect(host) is implicitly called by the constructor.

user (str) -- The username to log in with (default: 'anonymous'). If given, login(host, passwd, acct) is implicitly called by the constructor.

passwd (str) -- The password to use when logging in. If not given, and if passwd is the empty string or "-", a password will be automatically generated.

acct (str) -- Account information to be used for the ACCT FTP command. Few systems implement this. See RFC-959 [https://datatracker.ietf.org/doc/html/rfc959.html] for more details.

context (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 セキュリティで考慮すべき点 for best practices.

timeout (float | None) -- A timeout in seconds for blocking operations like connect() (default: the global default timeout setting).

source_address (tuple | None) -- A 2-tuple (host, port) for the socket to bind to as its source address before connecting.

encoding (str) -- The encoding for directories and filenames (default: 'utf-8').

Added in version 3.2.

バージョン 3.3 で変更: Added the source_address parameter.

バージョン 3.4 で変更: The class now supports hostname check with ssl.SSLContext.check_hostname and Server Name Indication (see ssl.HAS_SNI).

バージョン 3.9 で変更: If the timeout parameter is set to be zero, it will raise a ValueError to prevent the creation of a non-blocking socket. The encoding parameter was added, and the default was changed from Latin-1 to UTF-8 to follow RFC 2640 [https://datatracker.ietf.org/doc/html/rfc2640.html].

バージョン 3.12 で変更: The deprecated keyfile and certfile parameters have been removed.

FTP_TLS クラスを使ったサンプルセッションはこちらです:

>>> 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']

FTP_TLS class inherits from FTP, defining these additional methods and attributes:

ssl_version

The SSL version to use (defaults to ssl.PROTOCOL_SSLv23).

auth()

ssl_version 属性で指定されたものに従って、 TLS または SSL を使い、セキュアコントロール接続をセットアップします。

バージョン 3.4 で変更: The method now supports hostname check with ssl.SSLContext.check_hostname and Server Name Indication (see ssl.HAS_SNI).

ccc()

Revert control channel back to plaintext. This can be useful to take advantage of firewalls that know how to handle NAT with non-secure FTP without opening fixed ports.

Added in version 3.3.

prot_p()

セキュアデータ接続をセットアップします。

prot_c()

平文データ接続をセットアップします。

モジュール変数

exception ftplib.error_reply

サーバから想定外の応答があったときに送出される例外。

exception ftplib.error_temp

一時的エラーを表すエラーコード(400--499の範囲の応答コード)を受け取った時に発生する例外。

exception ftplib.error_perm

永久エラーを表すエラーコード(500--599の範囲の応答コード)を受け取った時に発生する例外。

exception ftplib.error_proto

File Transfer Protocol の応答仕様に適合しない、すなわち1--5の数字で始まらない応答コードをサーバから受け取った時に発生する例外。

ftplib.all_errors

FTP インスタンスのメソッド実行時、FTP接続で (プログラミングのエラーと考えられるメソッドの実行によって) 発生する全ての例外 (タプル形式)。この例外には以上の４つのエラーはもちろん、 OSError と EOFError も含まれます。

参考

netrc モジュール

.netrc ファイルフォーマットのパーザ。 .netrc ファイルは、 FTPクライアントがユーザにプロンプトを出す前に、ユーザ認証情報をロードするのによく使われます。

poplib --- POP3 protocol client

ソースコード: Lib/poplib.py [https://github.com/python/cpython/tree/3.12/Lib/poplib.py]

このモジュールはクラス POP3 を定義しています。 POP3 はPOP3 サーバへの接続をカプセル化し、RFC 1939 [https://datatracker.ietf.org/doc/html/rfc1939.html] で定義されているプロトコルを実装しています。 POP3 クラスは RFC 1939 [https://datatracker.ietf.org/doc/html/rfc1939.html] の最小限のコマンドセットとオプションのコマンドセットをサポートしています。既に確立されている接続で暗号化された通信を行うために、RFC 2595 [https://datatracker.ietf.org/doc/html/rfc2595.html] で導入された STLS コマンドもサポートされています。

加えて、このモジュールはクラス POP3_SSL を提供しています。 POP3_SSL は SSL を下層のプロトコルレイヤーとして使う POP3 サーバへの接続をサポートしています。

POP3についての注意事項は、それが広くサポートされているにもかかわらず、既に時代遅れだということです。幾つも実装されているPOP3サーバーの品質は、貧弱なものが多数を占めています。もし、お使いのメールサーバーがIMAPをサポートしているなら、 imaplib.IMAP4 クラスが使えます。 IMAPサーバーは、より良く実装されている傾向があります。

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. See WebAssemblyプラットフォーム for more information.

poplib モジュールは二つのクラスを提供します:

class poplib.POP3(host, port=POP3_PORT[, timeout])

このクラスが、実際にPOP3プロトコルを実装します。インスタンスが初期化されるときに、コネクションが作成されます。 port が省略されると、POP3標準のポート(110)が使われます。オプションの timeout 引数は、接続時のタイムアウト時間を秒数で指定します (指定されなかった場合は、グローバルのデフォルトタイムアウト設定が利用されます)。

引数 self, host, port 付きで 監査イベント poplib.connect を送出します。

引数 self, line を指定して 監査イベント poplib.putline を送出します。

バージョン 3.9 で変更: timeout パラメータが0に設定されている場合、非ブロッキングソケットの作成を防ぐために ValueError を送出します。

class poplib.POP3_SSL(host, port=POP3_SSL_PORT, *, timeout=None, context=None)

POP3 クラスのサブクラスで、SSL でカプセル化されたソケットによる POP サーバへの接続を提供します。 port が指定されていない場合、 POP3-over-SSL 標準の 995 番ポートが使われます。timeout については POP3 クラスのコンストラクタの引数と同じです。 context は SSL の設定、証明書、秘密鍵を一つの (POP3_SSL オブジェクトよりも長く存在し続けうる) 構造にまとめた ssl.SSLContext オブジェクトで、省略可能です。ベストプラクティスについては セキュリティで考慮すべき点 を参照してください。

引数 self, host, port 付きで 監査イベント poplib.connect を送出します。

引数 self, line を指定して 監査イベント poplib.putline を送出します。

バージョン 3.2 で変更: context 引数が追加されました。

バージョン 3.4 で変更: The class now supports hostname check with ssl.SSLContext.check_hostname and Server Name Indication (see ssl.HAS_SNI).

バージョン 3.9 で変更: timeout パラメータが0に設定されている場合、非ブロッキングソケットの作成を防ぐために ValueError を送出します。

バージョン 3.12 で変更: The deprecated keyfile and certfile parameters have been removed.

1つの例外が、 poplib モジュールのアトリビュートとして定義されています:

exception poplib.error_proto

このモジュール内で起こったあらゆるエラーで送出される例外です (socket モジュールからのエラーは捕捉されません)。例外の理由は文字列としてコンストラクタに渡されます。

参考

モジュール imaplib

標準 Python IMAP モジュールです。

Frequently Asked Questions About Fetchmail [http://www.catb.org/~esr/fetchmail/fetchmail-FAQ.html]

POP/IMAPクライアント fetchmail のFAQ。POPプロトコルをベースにしたアプリケーションを書くときに有用な、POP3サーバの種類や RFCへの適合度といった情報を収集しています。

POP3 オブジェクト

POP3コマンドはすべて、それと同じ名前のメソッドとして小文字で表現されます。そしてそのほとんどは、サーバからのレスポンスとなるテキストを返します。

POP3 クラスのインスタンスは以下のメソッドを持ちます:

POP3.set_debuglevel(level)

インスタンスのデバッグレベルを設定します。この設定によってデバッグ時に出力される量を調節します。デフォルトは 0 で、何も出力されません。 1 なら、一般的に１つのコマンドあたり１行の適当な量のデバッグ出力を行います。 2 以上なら、コントロール接続で受信した各行を出力して、最大のデバッグ出力をします。

POP3.getwelcome()

POP3サーバーから送られるグリーティングメッセージを返します。

POP3.capa()

RFC 2449 [https://datatracker.ietf.org/doc/html/rfc2449.html] で規定されている機能についてサーバに問い合わせます。{'name': ['param'...]} という形の辞書を返します。

Added in version 3.4.

POP3.user(username)

userコマンドを送出します。応答はパスワード要求を表示します。

POP3.pass_(password)

Send password, response includes message count and mailbox size. Note: the mailbox on the server is locked until quit() is called.

POP3.apop(user, secret)

POP3サーバーにログオンするのに、よりセキュアなAPOP認証を使用します。

POP3.rpop(user)

POP3サーバーにログオンするのに、（UNIXのr-コマンドと同様の）RPOP認証を使用します。

POP3.stat()

メールボックスの状態を得ます。結果は2つのintegerからなるタプルとなります。 (message count, mailbox size).

POP3.list([which])

メッセージのリストを要求します。結果は (response, ['mesg_num octets', ...], octets) という形式で表されます。 which が与えられると、それによりメッセージを指定します。

POP3.retr(which)

which 番のメッセージ全体を取り出し、そのメッセージに既読フラグを立てます。結果は (response, ['line', ...], octets) という形式で表されます。

POP3.dele(which)

which 番のメッセージに削除のためのフラグを立てます。ほとんどのサーバで、QUITコマンドが実行されるまでは実際の削除は行われません（もっとも良く知られた例外は Eudora QPOPで、その配送メカニズムはRFCに違反しており、どんな切断状況でも削除操作を未解決にしています）。

POP3.rset()

メールボックスの削除マークすべてを取り消します。

POP3.noop()

何もしません。接続保持のために使われます。

POP3.quit()

サインオフ: 変更をコミットし、メールボックスをアンロックして、接続を破棄します。

POP3.top(which, howmuch)

メッセージヘッダと howmuch で指定した行数のメッセージを、 which で指定したメッセージ分取り出します。結果は以下のような形式となります。 (response, ['line', ...], octets).

このメソッドはPOP3のTOPコマンドを利用し、RETRコマンドのように、メッセージに既読フラグをセットしません。残念ながら、TOPコマンドはRFCでは貧弱な仕様しか定義されておらず、しばしばノーブランドのサーバーでは（その仕様が）守られていません。このメソッドを信用してしまう前に、実際に使用するPOPサーバーでテストをしてください。

POP3.uidl(which=None)

（ユニークIDによる）メッセージダイジェストのリストを返します。 which が設定されている場合、結果はユニークIDを含みます。それは 'response mesgnum uid という形式のメッセージ、または (response, ['mesgnum uid', ...], octets) という形式のリストとなります。

POP3.utf8()

UTF-8 モードへの切り替えを試行します。成功した場合はサーバの応答を返し、失敗した場合は error_proto を送出します。RFC 6856 [https://datatracker.ietf.org/doc/html/rfc6856.html] で規定されています。

Added in version 3.5.

POP3.stls(context=None)

アクティブな接続にて RFC 2595 [https://datatracker.ietf.org/doc/html/rfc2595.html] で定められた方法で TLS セッションを開始します。TLS セッションはユーザ認証を行う前に開始する必要があります。

context は SSL の設定、証明書、秘密鍵を一つの (POP3 オブジェクトよりも長く存在し続けうる) 構造にまとめた ssl.SSLContext オブジェクトです。ベストプラクティスについては セキュリティで考慮すべき点 を参照してください。

This method supports hostname checking via ssl.SSLContext.check_hostname and Server Name Indication (see ssl.HAS_SNI).

Added in version 3.4.

POP3_SSL クラスのインスタンスは追加のメソッドを持ちません。このサブクラスのインターフェイスは親クラスと同じです。

POP3 の例

以下にメールボックスを開き、全てのメッセージを取得して印刷する最小の (エラーチェックをしない) 使用例を示します:

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)

モジュールの末尾に、より拡張的な使用例が収められたテストセクションがあります。

imaplib --- IMAP4 protocol client

ソースコード: Lib/imaplib.py [https://github.com/python/cpython/tree/3.12/Lib/imaplib.py]

このモジュールでは三つのクラス、 IMAP4, IMAP4_SSL と IMAP4_stream を定義します。これらのクラスは IMAP4 サーバへの接続をカプセル化し、 RFC 2060 [https://datatracker.ietf.org/doc/html/rfc2060.html] に定義されている IMAP4rev1 クライアントプロトコルの大規模なサブセットを実装しています。このクラスは IMAP4 (RFC 1730 [https://datatracker.ietf.org/doc/html/rfc1730.html]) 準拠のサーバと後方互換性がありますが、 STATUS コマンドは IMAP4 ではサポートされていないので注意してください。

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. See WebAssemblyプラットフォーム for more information.

imaplib モジュール内では三つのクラスを提供しており、 IMAP4 は基底クラスとなります:

class imaplib.IMAP4(host='', 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, '' (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 None, the global default socket timeout is used.

The IMAP4 class supports the with statement. When used like this, the IMAP4 LOGOUT command is issued automatically when the with statement exits. E.g.:

>>> from imaplib import IMAP4
>>> with IMAP4("domain.org") as M:
...     M.noop()
...
('OK', [b'Nothing Accomplished. d25if65hy903weo.87'])

バージョン 3.5 で変更: with 構文のサポートが追加されました。

バージョン 3.9 で変更: オプションの timeout 引数が追加されました。

例外は IMAP4 クラスの属性として定義されています:

exception IMAP4.error

何らかのエラー発生の際に送出される例外です。例外の理由は文字列としてコンストラクタに渡されます。

exception IMAP4.abort

IMAP4 サーバのエラーが生じると、この例外が送出されます。この例外は IMAP4.error のサブクラスです。通常、インスタンスを閉じ、新たなインスタンスを再び生成することで、この例外から復旧できます。

exception IMAP4.readonly

この例外は書き込み可能なメールボックスの状態がサーバによって変更された際に送出されます。この例外は IMAP4.error のサブクラスです。他の何らかのクライアントが現在書き込み権限を獲得しており、メールボックスを開きなおして書き込み権限を再獲得する必要があります。

このモジュールではもう一つ、安全 (secure) な接続を使ったサブクラスがあります:

class imaplib.IMAP4_SSL(host='', port=IMAP4_SSL_PORT, *, ssl_context=None, timeout=None)

This is a subclass derived from 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, '' (the local host) is used. If port is omitted, the standard IMAP4-over-SSL port (993) is used. ssl_context is a ssl.SSLContext object which allows bundling SSL configuration options, certificates and private keys into a single (potentially long-lived) structure. Please read セキュリティで考慮すべき点 for best practices.

The optional timeout parameter specifies a timeout in seconds for the connection attempt. If timeout is not given or is None, the global default socket timeout is used.

バージョン 3.3 で変更: ssl_context 引数が追加されました。

バージョン 3.4 で変更: The class now supports hostname check with ssl.SSLContext.check_hostname and Server Name Indication (see ssl.HAS_SNI).

バージョン 3.9 で変更: オプションの timeout 引数が追加されました。

バージョン 3.12 で変更: The deprecated keyfile and certfile parameters have been removed.

さらにもう一つのサブクラスは、子プロセスで確立した接続を使用する場合に使用します:

class imaplib.IMAP4_stream(command)

IMAP4 から派生したサブクラスで、 command を subprocess.Popen() に渡して作成される stdin/stdout ディスクリプタと接続します。

以下のユーティリティ関数が定義されています:

imaplib.Internaldate2tuple(datestr)

IMAP4 の INTERNALDATE 文字列を解析してそれに相当するローカルタイムを返します。戻り値は time.struct_time のタプルか、文字列のフォーマットが不正な場合は None です。

imaplib.Int2AP(num)

整数を [A .. P] からなる文字集合を用いて表現した bytes に変換します。

imaplib.ParseFlags(flagstr)

IMAP4 FLAGS 応答を個々のフラグからなるタプルに変換します。

imaplib.Time2Internaldate(date_time)

Convert date_time to an IMAP4 INTERNALDATE representation. The return value is a string in the form: "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 time.time()), a 9-tuple representing local time an instance of time.struct_time (as returned by time.localtime()), an aware instance of datetime.datetime, or a double-quoted string. In the last case, it is assumed to already be in the correct format.

IMAP4 メッセージ番号は、メールボックスに対する変更が行われた後には変化します; 特に、EXPUNGE 命令はメッセージの削除を行いますが、残ったメッセージには再度番号を振りなおします。従って、メッセージ番号ではなく、UID 命令を使い、その UID を利用するよう強く勧めます。

モジュールの末尾に、より拡張的な使用例が収められたテストセクションがあります。

参考

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) https://github.com/uw-imap/imap (Not Maintained).

IMAP4 オブジェクト

All IMAP4rev1 commands are represented by methods of the same name, either uppercase or lowercase.

命令に対する引数は全て文字列に変換されます。例外は AUTHENTICATE の引数と APPEND の最後の引数で、これは IMAP4 リテラルとして渡されます。必要に応じて (IMAP4 プロトコルが感知対象としている文字が文字列に入っており、かつ丸括弧か二重引用符で囲われていなかった場合) 文字列はクオートされます。しかし、LOGIN 命令の password 引数は常にクオートされます。文字列がクオートされないようにしたい (例えば STORE 命令の flags 引数) 場合、文字列を丸括弧で囲んでください (例: r'(\Deleted)')。

各命令はタプル: (type, [data, ...]) を返し、type は通常 'OK' または 'NO' です。data は命令に対する応答をテキストにしたものか、命令に対する実行結果です。各 data は bytes かタプルとなります。タプルの場合、最初の要素はレスポンスのヘッダで、次の要素にはデータが格納されます (ie: 'literal' value)。

以下のコマンドにおける message_set オプションは、操作の対象となるひとつあるいは複数のメッセージを指す文字列です。単一のメッセージ番号 ('1') かメッセージ番号の範囲 ('2:4')、あるいは連続していないメッセージをカンマでつなげたもの ('1:3,6:9') となります。範囲指定でアスタリスクを使用すると、上限を無限とすることができます ('3:*')。

IMAP4 のインスタンスは以下のメソッドを持っています:

IMAP4.append(mailbox, flags, date_time, message)

指定された名前のメールボックスに message を追加します。

IMAP4.authenticate(mechanism, authobject)

認証命令です --- 応答の処理が必要です。

mechanism は利用する認証メカニズムを与えます。認証メカニズムはインスタンス変数 capabilities の中に AUTH=mechanism という形式で現れる必要があります。

authobject は呼び出し可能なオブジェクトである必要があります:

data = authobject(response)

It will be called to process server continuation responses; the response argument it is passed will be bytes. It should return bytes data that will be base64 encoded and sent to the server. It should return None if the client abort response * should be sent instead.

バージョン 3.5 で変更: string usernames and passwords are now encoded to utf-8 instead of being limited to ASCII.

IMAP4.check()

サーバ上のメールボックスにチェックポイントを設定します。

IMAP4.close()

現在選択されているメールボックスを閉じます。削除されたメッセージは書き込み可能メールボックスから除去されます。LOGOUT 前に実行することを勧めます。

IMAP4.copy(message_set, new_mailbox)

message_set で指定したメッセージ群を new_mailbox の末尾にコピーします。

IMAP4.create(mailbox)

mailbox と名づけられた新たなメールボックスを生成します。

IMAP4.delete(mailbox)

mailbox と名づけられた古いメールボックスを削除します。

IMAP4.deleteacl(mailbox, who)

mailbox における who についてのACLを削除(権限を削除)します。

IMAP4.enable(capability)

Enable capability (see RFC 5161 [https://datatracker.ietf.org/doc/html/rfc5161.html]). Most capabilities do not need to be enabled. Currently only the UTF8=ACCEPT capability is supported (see RFC 6855 [https://datatracker.ietf.org/doc/html/rfc6855.html]).

Added in version 3.5: The enable() method itself, and RFC 6855 [https://datatracker.ietf.org/doc/html/rfc6855.html] support.

IMAP4.expunge()

選択されたメールボックスから削除された要素を永久に除去します。各々の削除されたメッセージに対して、EXPUNGE 応答を生成します。返されるデータには EXPUNGE メッセージ番号を受信した順番に並べたリストが入っています。

IMAP4.fetch(message_set, message_parts)

メッセージ (の一部) を取りよせます。message_parts はメッセージパートの名前を表す文字列を丸括弧で囲ったもので、例えば: "(UID BODY[TEXT])" のようになります。返されるデータはメッセージパートのエンベロープ情報とデータからなるタプルです。

IMAP4.getacl(mailbox)

mailbox に対する ACL を取得します。このメソッドは非標準ですが、Cyrus サーバでサポートされています。

IMAP4.getannotation(mailbox, entry, attribute)

mailbox に対する ANNOTATION を取得します。このメソッドは非標準ですが、Cyrus サーバでサポートされています。

IMAP4.getquota(root)

quota root により、リソース使用状況と制限値を取得します。このメソッドは RFC 2087 [https://datatracker.ietf.org/doc/html/rfc2087.html] で定義されている IMAP4 QUOTA 拡張の一部です。

IMAP4.getquotaroot(mailbox)

mailbox に対して quota root を実行した結果のリストを取得します。このメソッドは RFC 2087 [https://datatracker.ietf.org/doc/html/rfc2087.html] で定義されている IMAP4 QUOTA 拡張の一部です。

IMAP4.list([directory[, pattern]])

pattern にマッチする directory メールボックス名を列挙します。directory の標準の設定値は最上レベルのメールフォルダで、pattern は標準の設定では全てにマッチします。返されるデータには LIST 応答のリストが入っています。

IMAP4.login(user, password)

平文パスワードを使ってクライアントを照合します。password はクオートされます。

IMAP4.login_cram_md5(user, password)

パスワードの保護のため、クライアント認証時に CRAM-MD5 だけを使用します。これは、CAPABILITY レスポンスに AUTH=CRAM-MD5 が含まれる場合のみ有効です。

IMAP4.logout()

サーバへの接続を遮断します。サーバからの BYE 応答を返します。

バージョン 3.8 で変更: The method no longer ignores silently arbitrary exceptions.

IMAP4.lsub(directory='""', pattern='*')

購読しているメールボックス名のうち、ディレクトリ内でパターンにマッチするものを列挙します。directory の標準の設定値は最上レベルのメールフォルダで、pattern は標準の設定では全てにマッチします。返されるデータには返されるデータはメッセージパートエンベロープ情報とデータからなるタプルです。

IMAP4.myrights(mailbox)

mailboxにおける自分のACLを返します (すなわち自分がmailboxで持っている権限を返します)。

IMAP4.namespace()

RFC 2342 [https://datatracker.ietf.org/doc/html/rfc2342.html] で定義されるIMAP名前空間を返します。

IMAP4.noop()

サーバに NOOP を送信します。

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 None, the global default socket timeout is used. Also note that if the timeout parameter is set to be zero, it will raise a ValueError to reject creating a non-blocking socket. This method is implicitly called by the IMAP4 constructor. The connection objects established by this method will be used in the IMAP4.read(), IMAP4.readline(), IMAP4.send(), and IMAP4.shutdown() methods. You may override this method.

引数 self, host, port を指定して 監査イベント imaplib.open を送出します。

バージョン 3.9 で変更: timeout 引数が追加されました。

IMAP4.partial(message_num, message_part, start, length)

メッセージの後略された部分を取り寄せます。返されるデータはメッセージパートエンベロープ情報とデータからなるタプルです。

IMAP4.proxyauth(user)

user として認証されたものとします。認証された管理者がユーザの代理としてメールボックスにアクセスする際に使用します。

IMAP4.read(size)

遠隔のサーバから size バイト読み出します。このメソッドはオーバライドすることができます。

IMAP4.readline()

遠隔のサーバから一行読み出します。このメソッドはオーバライドすることができます。

IMAP4.recent()

サーバに更新を促します。新たなメッセージがない場合応答は None になり、そうでない場合 RECENT 応答の値になります。

IMAP4.rename(oldmailbox, newmailbox)

oldmailbox という名前のメールボックスを newmailbox に名称変更します。

IMAP4.response(code)

応答 code を受信していれば、そのデータを返し、そうでなければ None を返します。通常の形式 (usual type) ではなく指定したコードを返します。

IMAP4.search(charset, criterion[, ...])

Search mailbox for matching messages. charset may be None, in which case no 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 None if the UTF8=ACCEPT capability was enabled using the enable() command.

以下はプログラム例です:

# M is a connected IMAP4 instance...
typ, msgnums = M.search(None, 'FROM', '"LDJ"')

# or:
typ, msgnums = M.search(None, '(FROM "LDJ")')

IMAP4.select(mailbox='INBOX', readonly=False)

メールボックスを選択します。返されるデータは mailbox 内のメッセージ数 (EXISTS 応答) です。標準の設定では mailbox は 'INBOX' です。readonly が設定された場合、メールボックスに対する変更はできません。

IMAP4.send(data)

遠隔のサーバに data を送信します。このメソッドはオーバライドすることができます。

引数 self, data を指定して 監査イベント imaplib.send を送出します。

IMAP4.setacl(mailbox, who, what)

ACL を mailbox に設定します。このメソッドは非標準ですが、Cyrus サーバでサポートされています。

IMAP4.setannotation(mailbox, entry, attribute[, ...])

ANNOTATION を mailbox に設定します。このメソッドは非標準ですが、Cyrus サーバでサポートされています。

IMAP4.setquota(root, limits)

quota root のリソースを limits に設定します。このメソッドは RFC 2087 [https://datatracker.ietf.org/doc/html/rfc2087.html] で定義されている IMAP4 QUOTA 拡張の一部です。

IMAP4.shutdown()

open で確立された接続を閉じます。 IMAP4.logout() は暗黙的にこのメソッドを呼び出します。このメソッドはオーバライドすることができます。

IMAP4.socket()

サーバへの接続に使われているソケットインスタンスを返します。

IMAP4.sort(sort_criteria, charset, search_criterion[, ...])

sort 命令は search に結果の並べ替え (sort) 機能をつけた変種です。返されるデータには、条件に合致するメッセージ番号をスペースで分割したリストが入っています。

sort 命令は search_criterion の前に二つの引数を持ちます; sort_criteria のリストを丸括弧で囲ったものと、検索時の charset です。search と違って、検索時の charset は必須です。uid sort 命令もあり、search に対する uid search と同じように sort 命令に対応します。sort 命令はまず、charset 引数の指定に従って searching criteria の文字列を解釈し、メールボックスから与えられた検索条件に合致するメッセージを探します。次に、合致したメッセージの数を返します。

IMAP4rev1 拡張命令です。

IMAP4.starttls(ssl_context=None)

Send a STARTTLS command. The ssl_context argument is optional and should be a ssl.SSLContext object. This will enable encryption on the IMAP connection. Please read セキュリティで考慮すべき点 for best practices.

Added in version 3.2.

バージョン 3.4 で変更: The method now supports hostname check with ssl.SSLContext.check_hostname and Server Name Indication (see ssl.HAS_SNI).

IMAP4.status(mailbox, names)

mailbox の指定ステータス名の状態情報を要求します。

IMAP4.store(message_set, command, flag_list)

メールボックス内のメッセージ群のフラグ設定を変更します。 command は RFC 2060 [https://datatracker.ietf.org/doc/html/rfc2060.html] のセクション 6.4.6 で指定されているもので、 "FLAGS", "+FLAGS", あるいは "-FLAGS" のいずれかとなります。オプションで末尾に ".SILENT" がつくこともあります。

たとえば、すべてのメッセージに削除フラグを設定するには次のようにします:

typ, data = M.search(None, 'ALL')
for num in data[0].split():
   M.store(num, '+FLAGS', '\\Deleted')
M.expunge()

注釈

Creating flags containing ']' (for example: "[test]") violates RFC 3501 [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 nonetheless 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.

IMAP4.subscribe(mailbox)

新たなメールボックスを購読 (subscribe) します。

IMAP4.thread(threading_algorithm, charset, search_criterion[, ...])

thread コマンドは search にスレッドの概念を加えた変形版です。返されるデータは空白で区切られたスレッドメンバのリストを含んでいます。

各スレッドメンバは0以上のメッセージ番号からなり、空白で区切られており、親子関係を示しています。

Thread has two arguments before the search_criterion argument(s); a threading_algorithm, and the searching charset. Note that unlike search, the searching charset argument is mandatory. There is also a uid thread command which corresponds to thread the way that uid search corresponds to search. The 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.

IMAP4rev1 拡張命令です。

IMAP4.uid(command, arg[, ...])

command args を、メッセージ番号ではなく UID で指定されたメッセージ群に対して実行します。命令内容に応じた応答を返します。少なくとも一つの引数を与えなくてはなりません; 何も与えない場合、サーバはエラーを返し、例外が送出されます。

IMAP4.unsubscribe(mailbox)

古いメールボックスの購読を解除 (unsubscribe) します。

IMAP4.unselect()

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 imaplib.IMAP4.close(), except that no messages are permanently removed from the currently selected mailbox.

Added in version 3.9.

IMAP4.xatom(name[, ...])

サーバから CAPABILITY 応答で通知された単純な拡張命令を許容 (allow) します。

以下の属性が IMAP4 のインスタンス上で定義されています:

IMAP4.PROTOCOL_VERSION

サーバから返された CAPABILITY 応答にある、サポートされている最新のプロトコルです。

IMAP4.debug

デバッグ出力を制御するための整数値です。初期値はモジュール変数 Debug から取られます。3 以上の値にすると各命令をトレースします。

IMAP4.utf8_enabled

Boolean value that is normally False, but is set to True if an enable() command is successfully issued for the UTF8=ACCEPT capability.

Added in version 3.5.

IMAP4 の使用例

以下にメールボックスを開き、全てのメッセージを取得して印刷する最小の (エラーチェックをしない) 使用例を示します:

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()

smtplib --- SMTP protocol client

ソースコード: Lib/smtplib.py [https://github.com/python/cpython/tree/3.12/Lib/smtplib.py]

smtplib モジュールは、SMTPまたはESMTPのリスナーデーモンを備えた任意のインターネット上のホストにメールを送るために使用することができる SMTPクライアント・セッション・オブジェクトを定義します。 SMTPおよびESMTPオペレーションの詳細は、 RFC 821 [https://datatracker.ietf.org/doc/html/rfc821.html] (Simple Mail Transfer Protocol) や RFC 1869 [https://datatracker.ietf.org/doc/html/rfc1869.html] (SMTP Service Extensions)を調べてください。

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. See WebAssemblyプラットフォーム for more information.

class smtplib.SMTP(host='', port=0, local_hostname=None, [timeout, ]source_address=None)

SMTP インスタンスはSMTP接続をカプセル化します。SMTPとESMTP操作の完全なレパートリーをサポートするメソッドがあります。オプションパラメータの host および port が指定されている場合、SMTPの connect() メソッドは初期化中にこれらのパラメータを使って呼び出されます。 local_hostname を指定した場合、それはHELO/EHLOコマンドのローカルホストのFQDNとして使用されます。指定しない場合、ローカルホスト名は socket.getfqdn() を使用して検索されます。 connect() 呼び出しが成功コード以外を返すと、 SMTPConnectError が送出されます。オプションの timeout パラメータは、接続試行のようなブロッキング操作のタイムアウトを秒単位で指定します（指定されていない場合、グローバルなデフォルトのタイムアウト設定が使用されます）。タイムアウトが切れると、 TimeoutError が送出されます。オプションの source_address パラメータを使用すると、複数のネットワークインターフェースを持つマシンの特定の送信元アドレス、かつ（または）特定の送信元TCPポートにバインドできます。接続する前にソケットを送信元アドレスとしてバインドするためにタプル (host, port) が必要です。省略された場合（あるいは、host または port がそれぞれ '' かつ/または 0 の場合）、OSのデフォルト動作が使用されます。

普通に使う場合は、初期化と接続を行ってから、 sendmail() と SMTP.quit() メソッドを呼びます。使用例は先の方で記載しています。

The SMTP class supports the with statement. When used like this, the SMTP QUIT command is issued automatically when the with statement exits. E.g.:

>>> from smtplib import SMTP
>>> with SMTP("domain.org") as smtp:
...     smtp.noop()
...
(250, b'Ok')
>>>

引数 self, data を指定して 監査イベント smtplib.send を送出します。

バージョン 3.3 で変更: with 構文のサポートが追加されました。

バージョン 3.3 で変更: source_address argument was added.

Added in version 3.5: SMTPUTF8 拡張 (RFC 6531 [https://datatracker.ietf.org/doc/html/rfc6531.html]) がサポートされました。

バージョン 3.9 で変更: timeout パラメータが0に設定されている場合、非ブロッキングソケットの作成を防ぐために ValueError を送出します。

class smtplib.SMTP_SSL(host='', port=0, local_hostname=None, *, [timeout, ]context=None, source_address=None)

SMTP_SSL インスタンスは SMTP と全く同じように動作します。SMTP_SSL は、接続の始めからSSLが必要であり、 starttls() が適切でない状況で使用するべきです。 host が指定されていない場合、ローカルホストが使用されます。 port が0の場合、標準のSMTP-over-SSLポート（465）が使用されます。オプション引数 local_hostname, timeout, source_address は SMTP クラスと同じ意味を持ちます。 context オプションは SSLContext を含むことができ、安全な接続のさまざまな側面を設定することができます。ベストプラクティスについては セキュリティで考慮すべき点 を読んでください。

バージョン 3.3 で変更: context が追加されました。

バージョン 3.3 で変更: The source_address argument was added.

バージョン 3.4 で変更: The class now supports hostname check with ssl.SSLContext.check_hostname and Server Name Indication (see ssl.HAS_SNI).

バージョン 3.9 で変更: timeout パラメータが0に設定されている場合、非ブロッキングソケットの作成を防ぐために ValueError を送出します。

バージョン 3.12 で変更: The deprecated keyfile and certfile parameters have been removed.

class smtplib.LMTP(host='', 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 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 SMTP class. To specify a Unix socket, you must use an absolute path for host, starting with a '/'.

認証は、通常のSMTP機構を利用してサポートされています。 Unixソケットを利用する場合、LMTPは通常認証をサポートしたり要求したりはしません。しかし、あなたが必要であれば、利用することができます。

バージョン 3.9 で変更: オプションの timeout 引数が追加されました。

このモジュールの例外には次のものがあります:

exception smtplib.SMTPException

OSError の派生クラスで、このモジュールが提供する他の全ての例外の基底クラスです。

バージョン 3.4 で変更: SMTPException が OSError の派生クラスになりました。

exception smtplib.SMTPServerDisconnected

この例外はサーバが突然接続が切断されるか、SMTP インスタンスを生成する前に接続しようとした場合に送出されます。

exception smtplib.SMTPResponseException

SMTPのエラーコードを含んだ例外のクラスです。これらの例外はSMTPサーバがエラーコードを返すときに生成されます。エラーコードは smtp_code 属性に格納されます。また、 smtp_error 属性にはエラーメッセージが格納されます。

exception smtplib.SMTPSenderRefused

送信者のアドレスが弾かれたときに送出される例外です。全ての SMTPResponseException 例外に、 SMTPサーバが弾いた 'sender' アドレスの文字列がセットされます。

exception smtplib.SMTPRecipientsRefused

全ての受取人アドレスが弾かれたときに送出される例外です。各受取人のエラーは属性 recipients によってアクセス可能で、 SMTP.sendmail() が返す辞書と同じ並びの辞書になっています。

exception smtplib.SMTPDataError

SMTPサーバが、メッセージのデータを受け入れることを拒絶したときに送出される例外です。

exception smtplib.SMTPConnectError

サーバへの接続時にエラーが発生したときに送出される例外です。

exception smtplib.SMTPHeloError

サーバーが HELO メッセージを弾いたときに送出される例外です。

exception smtplib.SMTPNotSupportedError

試行したコマンドやオプションはサーバにサポートされていません。

Added in version 3.5.

exception smtplib.SMTPAuthenticationError

SMTP 認証が失敗しました。最もあり得るのは、サーバーがユーザ名/パスワードのペアを受け付なかった事です。

参考

RFC 821 [https://datatracker.ietf.org/doc/html/rfc821.html] - Simple Mail Transfer Protocol

SMTP のプロトコル定義です。このドキュメントでは SMTP のモデル、操作手順、プロトコルの詳細についてカバーしています。

RFC 1869 [https://datatracker.ietf.org/doc/html/rfc1869.html] - SMTP Service Extensions

SMTP に対する ESMTP 拡張の定義です。このドキュメントでは、新たな命令による SMTP の拡張、サーバによって提供される命令を動的に発見する機能のサポート、およびいくつかの追加命令定義について記述しています。

SMTP オブジェクト

SMTP クラスインスタンスは次のメソッドを提供します:

SMTP.set_debuglevel(level)

デバッグ出力レベルを設定します。level が 1 や True の場合、接続ならびにサーバとの送受信のメッセージがデバッグメッセージとなります。level が 2 の場合、それらのメッセージにタイムスタンプが付きます。

バージョン 3.5 で変更: デバッグレベル2が追加されました。

SMTP.docmd(cmd, args='')

サーバへコマンド cmd を送信します。オプション引数 args はスペース文字でコマンドに連結します。戻り値は、整数値のレスポンスコードと、サーバからの応答の値をタプルで返します (サーバからの応答が数行に渡る場合でも一つの大きな文字列で返します)。

数値応答コードと実際の応答行 (複数の応答は 1 つの長い行に結合されます) からなる 2 値タプルを返します。

通常、このメソッドを明示的に使う必要はありません。他のメソッドを実装するのに使い、自分で拡張したものをテストするのに役立つかもしれません。

応答待ちのときにサーバへの接続が切れると SMTPServerDisconnected が送出されます。

SMTP.connect(host='localhost', port=0)

ホスト名とポート番号をもとに接続します。デフォルトはlocalhostの標準的なSMTPポート(25番)に接続します。もしホスト名の末尾がコロン(':')で、後に番号がついている場合は、「ホスト名:ポート番号」として扱われます。このメソッドはコンストラクタにホスト名及びポート番号が指定されている場合、自動的に呼び出されます。戻り値は、この接続の応答内でサーバによって送信された応答コードとメッセージの2要素タプルです。

引数 self, host, port を指定して 監査イベント smtplib.connect を送出します。

SMTP.helo(name='')

SMTPサーバに HELO コマンドで身元を示します。デフォルトではhostname引数はローカルホストを指します。サーバーが返したメッセージは、オブジェクトの helo_resp 属性に格納されます。

通常は sendmail() が呼びだすため、これを明示的に呼び出す必要はありません。

SMTP.ehlo(name='')

EHLO を利用し、ESMTPサーバに身元を明かします。デフォルトではhostname引数はローカルホストのFQDNです。また、ESMTPオプションのために応答を調べたものは、 has_extn() に備えて保存されます。また、幾つかの情報を属性に保存します: サーバーが返したメッセージは ehlo_resp 属性に、 does_esmtp 属性はサーバーがESMTPをサポートしているかどうかによって True か False に、 esmtp_features 属性は辞書で、サーバーが対応しているSMTP サービス拡張の名前と、もしあればそのパラメータを格納します。

メールを送信する前に has_extn() を使おうとしない限り、このメソッドを明示的に呼ぶ必要はないはずです。必要な場合は sendmail() に暗黙的に呼ばれます。

SMTP.ehlo_or_helo_if_needed()

このメソッドは、現在のセッションでまだ EHLO か HELO コマンドが実行されていない場合、 ehlo() and/or helo() メソッドを呼び出します。このメソッドは先に ESMTP EHLO を試します。

SMTPHeloError

サーバーが HELO に正しく返答しませんでした。

SMTP.has_extn(name)

name が拡張SMTPサービスセットに含まれている場合には True を返し、そうでなければ False を返します。大小文字は区別されません。

SMTP.verify(address)

VRFY を利用してSMTPサーバにアドレスの妥当性をチェックします。妥当である場合はコード250と完全な RFC 822 [https://datatracker.ietf.org/doc/html/rfc822.html] アドレス (人名を含む) のタプルを返します。それ以外の場合は、400以上のエラーコードとエラー文字列を返します。

注釈

ほとんどのサイトはスパマーの裏をかくためにSMTPの VRFY は使用不可になっています。

SMTP.login(user, password, *, initial_response_ok=True)

認証が必要なSMTPサーバにログインします。認証に使用する引数はユーザ名とパスワードです。まだセッションが無い場合は、 EHLO または HELO コマンドでセッションを作ります。ESMTPの場合は EHLO が先に試されます。認証が成功した場合は通常このメソッドは戻りますが、例外が起こった場合は以下の例外が上がります:

SMTPHeloError

サーバーが HELO に正しく返答しませんでした。

SMTPAuthenticationError

サーバがユーザ名/パスワードでの認証に失敗しました。

SMTPNotSupportedError

AUTH コマンドはサーバにサポートされていません。

SMTPException

適当な認証方法が見付かりませんでした。

Each of the authentication methods supported by smtplib are tried in turn if they are advertised as supported by the server. See auth() for a list of supported authentication methods. initial_response_ok is passed through to auth().

オプションのキーワード引数 initial_response_ok は、それをサポートする認証方法に対して、チャレンジ/レスポンスを要求するのではなく、 "AUTH"コマンドとともに RFC 4954 [https://datatracker.ietf.org/doc/html/rfc4954.html] で指定された"初期応答"を送信できるかどうかを指定します。

バージョン 3.5 で変更: SMTPNotSupportedError が送出される場合があります。initial_response_ok 引数が追加されました。

SMTP.auth(mechanism, authobject, *, initial_response_ok=True)

Issue an SMTP 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 AUTH command; the valid values are those listed in the auth element of esmtp_features.

authobject must be a callable object taking an optional single argument:

data = authobject(challenge=None)

If optional keyword argument initial_response_ok is true, authobject() will be called first with no argument. It can return the RFC 4954 [https://datatracker.ietf.org/doc/html/rfc4954.html] "initial response" ASCII str which will be encoded and sent with the AUTH command as below. If the authobject() does not support an initial response (e.g. because it requires a challenge), it should return None when called with challenge=None. If initial_response_ok is false, then authobject() will not be called first with None.

If the initial response check returns None, or if initial_response_ok is false, authobject() will be called to process the server's challenge response; the challenge argument it is passed will be a bytes. It should return ASCII str data that will be base64 encoded and sent to the server.

The SMTP class provides authobjects for the CRAM-MD5, PLAIN, and LOGIN mechanisms; they are named SMTP.auth_cram_md5, SMTP.auth_plain, and SMTP.auth_login respectively. They all require that the user and password properties of the SMTP instance are set to appropriate values.

User code does not normally need to call auth directly, but can instead call the login() method, which will try each of the above mechanisms in turn, in the order listed. auth is exposed to facilitate the implementation of authentication methods not (or not yet) supported directly by smtplib.

Added in version 3.5.

SMTP.starttls(*, context=None)

TLS (Transport Layer Security) モードで SMTP 接続します。続く全てのSMTP コマンドは暗号化されます。その後、もう一度 ehlo() を呼んでください。

If keyfile and certfile are provided, they are used to create an ssl.SSLContext.

Optional context parameter is an ssl.SSLContext object; This is an alternative to using a keyfile and a certfile and if specified both keyfile and certfile should be None.

もしまだ EHLO か HELO コマンドが実行されていない場合、このメソッドは ESMTP EHLO を先に試します。

バージョン 3.12 で変更: The deprecated keyfile and certfile parameters have been removed.

SMTPHeloError

サーバーが HELO に正しく返答しませんでした。

SMTPNotSupportedError

サーバーが STARTTLS 拡張に対応していません。

RuntimeError

実行中の Python インタプリタで、SSL/TLS サポートが利用できません。

バージョン 3.3 で変更: context が追加されました。

バージョン 3.4 で変更: The method now supports hostname check with SSLContext.check_hostname and Server Name Indicator (see HAS_SNI).

バージョン 3.5 で変更: The error raised for lack of STARTTLS support is now the SMTPNotSupportedError subclass instead of the base SMTPException.

SMTP.sendmail(from_addr, to_addrs, msg, mail_options=(), rcpt_options=())

メールを送信します。必要な引数は RFC 822 [https://datatracker.ietf.org/doc/html/rfc822.html] のfromアドレス文字列、 RFC 822 [https://datatracker.ietf.org/doc/html/rfc822.html] のtoアドレス文字列またはアドレス文字列のリスト、メッセージ文字列です。送信側は MAIL FROM コマンドで使用される mail_options の ESMTPオプション(8bitmime のような)のリストを得るかもしれません。全ての RCPT コマンドで使われるべきESMTPオプション (例えば DSN コマンド)は、 rcpt_options を通して利用することができます。(もし送信先別にESMTPオプションを使う必要があれば、メッセージを送るために mail() 、 rcpt() 、 data() といった下位レベルのメソッドを使う必要があります。)

注釈

配送エージェントは from_addr、to_addrs 引数を使い、メッセージのエンベロープを構成します。sendmail はメッセージヘッダを修正しません。

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 \r and \n characters are converted to \r\n characters. A byte string is not modified.

まだセッションが無い場合は、 EHLO または HELO コマンドでセッションを作ります。ESMTPの場合は EHLO が先に試されます。また、サーバがESMTP対応ならば、メッセージサイズとそれぞれ指定されたオプションも渡します。(featureオプションがあればサーバの広告をセットします) EHLO が失敗した場合は、ESMTPオプションの無い HELO が試されます。

このメソッドは最低でも1人の受信者にメールが受け取られたときは正常に戻ります。そうでない場合は例外を投げます。つまり、このメソッドが例外を送出しないときは誰かが送信したメールを受け取ったはずです。また、例外を送出しない場合は拒絶された受信者ごとに項目のある辞書を返します。各項目はサーバーが送ったSMTPエラーコードと付随するエラーメッセージのタプルを持ちます。

mail_options に SMTPUTF8 があり、サーバがサポートしている場合は、from_addr と to_addrs に非 ASCII 文字を含めることが出来ます。

このメソッドは次の例外を送出することがあります:

SMTPRecipientsRefused

全ての受信を拒否され、誰にもメールが届けられませんでした。例外オブジェクトの recipients 属性は、受信拒否についての情報の入った辞書オブジェクトです。 (辞書は少なくとも一つは受信されたときに似ています)。

SMTPHeloError

サーバーが HELO に正しく返答しませんでした。

SMTPSenderRefused

サーバが from_addr を受理しませんでした。

SMTPDataError

サーバが予期しないエラーコードを返しました (受信拒否以外)。

SMTPNotSupportedError

mail_options に SMTPUTF8 が与えられましたが、サーバがサポートしていません。

また、この他の注意として、例外が上がった後もコネクションは開いたままになっています。

バージョン 3.2 で変更: msg はバイト文字列でも構いません。

バージョン 3.5 で変更: SMTPUTF8 のサポートが追加されました。SMTPUTF8 が与えられたが、サーバがサポートしていない場合は SMTPNotSupportedError が送出されます。

SMTP.send_message(msg, from_addr=None, to_addrs=None, mail_options=(), rcpt_options=())

This is a convenience method for calling sendmail() with the message represented by an email.message.Message object. The arguments have the same meaning as for sendmail(), except that msg is a Message object.

If from_addr is None or to_addrs is None, send_message fills those arguments with addresses extracted from the headers of msg as specified in RFC 5322 [https://datatracker.ietf.org/doc/html/rfc5322.html]: from_addr is set to the Sender field if it is present, and otherwise to the From field. to_addrs combines the values (if any) of the To, Cc, and Bcc fields from msg. If exactly one set of Resent-* headers appear in the message, the regular headers are ignored and the Resent-* headers are used instead. If the message contains more than one set of Resent-* headers, a ValueError is raised, since there is no way to unambiguously detect the most recent set of Resent- headers.

send_message serializes msg using BytesGenerator with \r\n as the linesep, and calls sendmail() to transmit the resulting message. Regardless of the values of from_addr and to_addrs, send_message does not transmit any Bcc or 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 SMTPUTF8 support, an SMTPNotSupported error is raised. Otherwise the Message is serialized with a clone of its policy with the utf8 attribute set to True, and SMTPUTF8 and BODY=8BITMIME are added to mail_options.

Added in version 3.2.

Added in version 3.5: 国際化アドレスのサポート (SMTPUTF8)。

SMTP.quit()

SMTPセッションを終了し、接続を閉じます。SMTP QUIT コマンドの結果を返します。

下位レベルのメソッドは標準SMTP/ESMTPコマンド HELP 、 RSET 、 NOOP 、 MAIL 、 RCPT 、 DATA に対応しています。通常これらは直接呼ぶ必要はなく、また、ドキュメントもありません。詳細はモジュールのコードを調べてください。

SMTP 使用例

次の例は最低限必要なメールアドレス('To' と 'From')を含んだメッセージを送信するものです。この例では RFC 822 [https://datatracker.ietf.org/doc/html/rfc822.html] ヘッダの加工もしていません。メッセージに含まれるヘッダは、メッセージに含まれる必要があり、特に、明確な 'To'、と 'From' アドレスはメッセージヘッダに含まれている必要があります。

import smtplib

def prompt(prompt):
    return input(prompt).strip()

fromaddr = prompt("From: ")
toaddrs  = prompt("To: ").split()
print("Enter message, end with ^D (Unix) or ^Z (Windows):")

# Add the From: and To: headers at the start!
msg = ("From: %s\r\nTo: %s\r\n\r\n"
       % (fromaddr, ", ".join(toaddrs)))
while True:
    try:
        line = input()
    except EOFError:
        break
    if not line:
        break
    msg = msg + line

print("Message length is", len(msg))

server = smtplib.SMTP('localhost')
server.set_debuglevel(1)
server.sendmail(fromaddr, toaddrs, msg)
server.quit()

注釈

多くの場合、 email パッケージの機能を使って email メッセージを構築し、それを、 send_message() で送信する、という手順を用います。 email: 使用例 を参照してください。

uuid --- UUID objects according to RFC 4122 [https://datatracker.ietf.org/doc/html/rfc4122.html]

ソースコード: Lib/uuid.py [https://github.com/python/cpython/tree/3.12/Lib/uuid.py]

このモジュールでは immutable (変更不能) な UUID オブジェクト (UUID クラス) と RFC 4122 [https://datatracker.ietf.org/doc/html/rfc4122.html] の定めるバージョン 1、3、4、5 の UUID を生成するための uuid1(), uuid3(), uuid4(), uuid5(), が提供されています。

もしユニークな ID が必要なだけであれば、おそらく uuid1() か uuid4() を呼び出せば良いでしょう。 uuid1() はコンピュータのネットワークアドレスを含む UUID を生成するためにプライバシーを侵害するかもしれない点に注意してください。 uuid4() はランダムな UUID を生成します。

Depending on support from the underlying platform, uuid1() may or may not return a "safe" UUID. A safe UUID is one which is generated using synchronization methods that ensure no two processes can obtain the same UUID. All instances of UUID have an is_safe attribute which relays any information about the UUID's safety, using this enumeration:

class uuid.SafeUUID

Added in version 3.7.

safe

UUID は並列処理に対して安全なプラットフォームで生成された

unsafe

UUID は並列処理に対して安全なプラットフォームで生成されなかった

unknown

プラットフォームは、UUID が安全に生成されたかどうかの情報を提供しなかった

class uuid.UUID(hex=None, bytes=None, bytes_le=None, fields=None, int=None, version=None, *, is_safe=SafeUUID.unknown)

32 桁の 16 進数文字列、bytes に 16 バイトのビッグエンディアンの文字列、bytes_le 引数に 16 バイトのリトルエンディアンの文字列、fields 引数に 6 つの整数のタプル（32ビット time_low, 16 ビット time_mid, 16ビット time_hi_version, 8ビット clock_seq_hi_variant, 8ビット clock_seq_low, 48ビット node ）、または int に一つの 128 ビット整数のいずれかから UUID を生成します。16 進数が与えられた時、波括弧、ハイフン、それと URN 接頭辞は無視されます。例えば、これらの表現は全て同じ UUID を払い出します:

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)

hex, bytes, bytes_le, fields, または int のうち、どれかただ一つだけが与えられなければいけません。version 引数はオプションです; 与えられた場合、結果の UUID は与えられた hex, bytes, bytes_le, fields, または int をオーバーライドして、RFC 4122 [https://datatracker.ietf.org/doc/html/rfc4122.html] に準拠した variant と version ナンバーのセットを持つことになります。bytes_le, fields, or int.

2つのUUIDオブジェクトの比較は、UUID.int 属性の比較によって行われます。UUIDではないオブジェクトとの比較は、 TypeError を送出します。

str(uuid) は 32桁の16進でUUIDを表す``12345678-1234-5678-1234-567812345678`` 形式の文字列を返します。

UUID インスタンスは以下の読み出し専用属性を持ちます:

UUID.bytes

16 バイト文字列（バイトオーダーがビッグエンディアンの 6 つの整数フィールドを持つ）のUUID。

UUID.bytes_le

16 バイト文字列（ time_low, time_mid, time_hi_version をリトルエンディアンで持つ）の UUID。

UUID.fields

UUID の 6 つの整数フィールドを持つタプルで、これは 6 つの個別の属性と 2 つの派生した属性としても取得可能です:

フィールド

意味

UUID.time_low

The first 32 bits of the UUID.

UUID.time_mid

The next 16 bits of the UUID.

UUID.time_hi_version

The next 16 bits of the UUID.

UUID.clock_seq_hi_variant

The next 8 bits of the UUID.

UUID.clock_seq_low

The next 8 bits of the UUID.

UUID.node

The last 48 bits of the UUID.

UUID.time

The 60-bit timestamp.

UUID.clock_seq

The 14-bit sequence number.

UUID.hex

32 文字の小文字 16 進数文字列での UUID。

UUID.int

128 ビット整数での UUID。

UUID.urn

RFC 4122 [https://datatracker.ietf.org/doc/html/rfc4122.html] で規定される URN での UUID。

UUID.variant

UUID の内部レイアウトを決定する UUID の variant。これは定数 RESERVED_NCS, RFC_4122, RESERVED_MICROSOFT, RESERVED_FUTURE のいずれかです。

UUID.version

UUID の version 番号（1 から 5、variant が RFC_4122 である場合だけ意味があります）。

UUID.is_safe

SafeUUID の列挙で、UUID は並列処理に対して安全なプラットフォームで生成されたかを示す。

Added in version 3.7.

The uuid モジュールには以下の関数があります:

uuid.getnode()

48 ビットの正の整数としてハードウェアアドレスを取得します。最初にこれを起動すると、別個のプログラムが立ち上がって非常に遅くなることがあります。もしハードウェアを取得する試みが全て失敗すると、ランダムな 48 ビットを、RFC 4122 [https://datatracker.ietf.org/doc/html/rfc4122.html] で推奨されているように、マルチキャストビット (最初のオクテットの最下位ビット) を 1 に設定して使います。"ハードウェアアドレス" とはネットワークインターフェースの MAC アドレスを指します。複数のネットワークインターフェースを持つマシンの場合、全域管理されたMACアドレス (最初のオクテットの下位より2番目のビットが 設定されていない MACアドレス) が、他の個別管理アドレスよりも優先的に使用されます。この優先順序は保証されません。

バージョン 3.7 で変更: 全域管理されたMACアドレスは、グローバルに固有であると保証されるため、固有である保証のない個別管理アドレスよりも好ましいです。

uuid.uuid1(node=None, clock_seq=None)

UUID をホスト ID、シーケンス番号、現在時刻から生成します。 node が与えられなければ、 getnode() がハードウェアアドレス取得のために使われます。 clock_seq が与えられると、これはシーケンス番号として使われます; さもなくば 14 ビットのランダムなシーケンス番号が選ばれます。

uuid.uuid3(namespace, name)

Generate a UUID based on the MD5 hash of a namespace identifier (which is a UUID) and a name (which is a bytes object or a string that will be encoded using UTF-8).

uuid.uuid4()

ランダムな UUID を生成します。

uuid.uuid5(namespace, name)

Generate a UUID based on the SHA-1 hash of a namespace identifier (which is a UUID) and a name (which is a bytes object or a string that will be encoded using UTF-8).

uuid モジュールは uuid3() または uuid5() で利用するために次の名前空間識別子を定義しています。

uuid.NAMESPACE_DNS

この名前空間が指定された場合、name 文字列は完全修飾ドメイン名です。

uuid.NAMESPACE_URL

この名前空間が指定された場合、name 文字列は URL です。

uuid.NAMESPACE_OID

この名前空間が指定された場合、name 文字列は ISO OID です。

uuid.NAMESPACE_X500

この名前空間が指定された場合、name 文字列は X.500 DN の DER またはテキスト出力形式です。

The uuid module defines the following constants for the possible values of the variant attribute:

uuid.RESERVED_NCS

NCS 互換性のために予約されています。

uuid.RFC_4122

RFC 4122 [https://datatracker.ietf.org/doc/html/rfc4122.html] で与えられた UUID レイアウトを指定します。

uuid.RESERVED_MICROSOFT

Microsoft の互換性のために予約されています。

uuid.RESERVED_FUTURE

将来のために予約されています。

参考

RFC 4122 [https://datatracker.ietf.org/doc/html/rfc4122.html] - Universally Unique IDentifier (UUID) の URN 名前空間

この仕様は UUID のための Uniform Resource Name 名前空間、UUID の内部フォーマットと UUID の生成方法を定義しています。

コマンドラインからの使用

Added in version 3.12.

The uuid module can be executed as a script from the command line.

python -m uuid [-h] [-u {uuid1,uuid3,uuid4,uuid5}] [-n NAMESPACE] [-N NAME]

以下のオプションが使用できます:

-h, --help

ヘルプメッセージを表示して終了します。

-u <uuid>

--uuid <uuid>

Specify the function name to use to generate the uuid. By default uuid4() is used.

-n <namespace>

--namespace <namespace>

The namespace is a UUID, or @ns where ns is a well-known predefined UUID addressed by namespace name. Such as @dns, @url, @oid, and @x500. Only required for uuid3() / uuid5() functions.

-N <name>

--name <name>

The name used as part of generating the uuid. Only required for uuid3() / uuid5() functions.

使用例

典型的な uuid モジュールの利用方法を示します:

>>> 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')

Command-Line Example

Here are some examples of typical usage of the uuid command line interface:

# generate a random uuid - by default uuid4() is used
$ python -m uuid

# generate a uuid using uuid1()
$ python -m uuid -u uuid1

# generate a uuid using uuid5
$ python -m uuid -u uuid5 -n @url -N example.com

socketserver --- A framework for network servers

ソースコード: Lib/socketserver.py [https://github.com/python/cpython/tree/3.12/Lib/socketserver.py]

socketserver モジュールはネットワークサーバを実装するタスクを単純化します。

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. See WebAssemblyプラットフォーム for more information.

基本的な具象サーバクラスが4つあります:

class 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 server_bind() and server_activate(). The other parameters are passed to the BaseServer base class.

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

class socketserver.UnixStreamServer(server_address, RequestHandlerClass, bind_and_activate=True)

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

これらの 4 つのクラスは要求を 同期的に (synchronously) 処理します; 各要求は次の要求を開始する前に完結していなければなりません。同期的な処理は、サーバで大量の計算を必要とする、あるいはクライアントが処理するには時間がかかりすぎるような大量のデータを返す、といった理由によってリクエストに長い時間がかかる状況には向いていません。こうした状況の解決方法は別のプロセスを生成するか、個々の要求を扱うスレッドを生成することです; ForkingMixIn および ThreadingMixIn 配合クラス (mix-in classes) を使えば、非同期的な動作をサポートできます。

サーバの作成にはいくつかのステップが必要です。最初に、 BaseRequestHandler クラスをサブクラス化して要求処理クラス (request hander class) を生成し、その handle() メソッドをオーバーライドしなければなりません; このメソッドは入力される要求を処理します。次に、サーバクラスのうち一つを、サーバのアドレスと要求処理クラスを渡してインスタンス化しなければなりません。サーバを with 文中で使うことが推奨されます。そして、handle_request() または serve_forever() メソッドを呼び出して、一つのまたは多数の要求を処理します。最後に、(with 文を使っていなかったなら) server_close() を呼び出してソケットを閉じます。

ThreadingMixIn から継承してスレッドを利用した接続を行う場合、突発的な通信切断時の処理を明示的に指定する必要があります。 ThreadingMixIn クラスには daemon_threads 属性があり、サーバがスレッドの終了を待ち合わせるかどうかを指定する事ができます。スレッドが独自の処理を行う場合は、このフラグを明示的に指定します。デフォルトは False で、Pythonは ThreadingMixIn クラスが起動した全てのスレッドが終了するまで実行し続けます。

サーバクラス群は使用するネットワークプロトコルに関わらず、同じ外部メソッドおよび属性を持ちます。

サーバ生成に関するノート

継承図にある五つのクラスのうち四つは四種類の同期サーバを表わしています:

+------------+
| BaseServer |
+------------+
      |
      v
+-----------+        +------------------+
| TCPServer |------->| UnixStreamServer |
+-----------+        +------------------+
      |
      v
+-----------+        +--------------------+
| UDPServer |------->| UnixDatagramServer |
+-----------+        +--------------------+

UnixDatagramServer は UDPServer から派生していて、 UnixStreamServer からではないことに注意してください --- IP と Unix サーバの唯一の違いはアドレスファミリーです。

class socketserver.ForkingMixIn

class socketserver.ThreadingMixIn

それぞれのタイプのサーバのフォークしたりスレッド実行したりするバージョンはそれらのミクシン(mix-in)クラスを使って作ることができます。たとえば、ThreadingUDPServer は以下のようにして作られます:

class ThreadingUDPServer(ThreadingMixIn, UDPServer):
    pass

ミクシンクラスは UDPServer で定義されるメソッドをオーバライドするために、最初に来ます。様々な属性を設定することで元になるサーバ機構の振る舞いを変えられます。

ForkingMixIn and the Forking classes mentioned below are only available on POSIX platforms that support fork().

block_on_close

ForkingMixIn.server_close waits until all child processes complete, except if block_on_close attribute is False.

ThreadingMixIn.server_close waits until all non-daemon threads complete, except if block_on_close attribute is False.

daemon_threads

For ThreadingMixIn use daemonic threads by setting ThreadingMixIn.daemon_threads to True to not wait until threads complete.

バージョン 3.7 で変更: ForkingMixIn.server_close and ThreadingMixIn.server_close now waits until all child processes and non-daemonic threads complete. Add a new ForkingMixIn.block_on_close class attribute to opt-in for the pre-3.7 behaviour.

class socketserver.ForkingTCPServer

class socketserver.ForkingUDPServer

class socketserver.ThreadingTCPServer

class socketserver.ThreadingUDPServer

class socketserver.ForkingUnixStreamServer

class socketserver.ForkingUnixDatagramServer

class socketserver.ThreadingUnixStreamServer

class socketserver.ThreadingUnixDatagramServer

These classes are pre-defined using the mix-in classes.

Added in version 3.12: The ForkingUnixStreamServer and ForkingUnixDatagramServer classes were added.

サービスの実装には、 BaseRequestHandler からクラスを派生させてその handle() メソッドを再定義しなければなりません。このようにすれば、サーバクラスと要求処理クラスを結合して様々なバージョンのサービスを実行することができます。要求処理クラスはデータグラムサービスかストリームサービスかで異なることでしょう。この違いは処理サブクラス StreamRequestHandler または DatagramRequestHandler を使うという形で隠蔽できます。

もちろん、まだ頭を使わなければなりません! たとえば、サービスがリクエストによっては書き換えられるようなメモリ上の状態を使うならば、フォークするサーバを使うのは馬鹿げています。というのも子プロセスでの書き換えは親プロセスで保存されている初期状態にも親プロセスから分配される各子プロセスの状態にも届かないからです。この場合、スレッド実行するサーバを使うことはできますが、共有データの一貫性を保つためにロックを使わなければならなくなるでしょう。

一方、全てのデータが外部に(たとえばファイルシステムに)保存される HTTP サーバを作っているのだとすると、同期クラスではどうしても一つの要求が処理されている間サービスが「耳の聞こえない」状態を呈することになります --- この状態はもしクライアントが要求した全てのデータをゆっくり受け取るととても長い時間続きかねません。こういう場合にはサーバをスレッド実行したりフォークすることが適切です。

ある場合には、要求の一部を同期的に処理する一方で、要求データに依って子プロセスをフォークして処理を終了させる、といった方法も適当かもしれません。こうした処理方法は同期サーバを使って要求処理クラスの handle() メソッドの中で自分でフォークするようにして実装することができます。

Another approach to handling multiple simultaneous requests in an environment that supports neither threads nor 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 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).

Serverオブジェクト

class 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 server_address and RequestHandlerClass attributes.

fileno()

サーバが要求待ちを行っているソケットのファイル記述子を整数で返します。この関数は一般的に、同じプロセス中の複数のサーバを監視できるようにするために、 selectors に渡されます。

handle_request()

単一の要求を処理します。この関数は以下のメソッド: get_request() 、 verify_request() 、および process_request() を順番に呼び出します。ハンドラ中でユーザによって提供された handle() が例外を送出した場合、サーバの handle_error() メソッドが呼び出されます。 timeout 秒以内にリクエストが来なかった場合、 handle_timeout() が呼ばれて、 handle_request() が終了します。

serve_forever(poll_interval=0.5)

Handle requests until an explicit shutdown() request. Poll for shutdown every poll_interval seconds. Ignores the timeout attribute. It also calls service_actions(), which may be used by a subclass or mixin to provide actions specific to a given service. For example, the ForkingMixIn class uses service_actions() to clean up zombie child processes.

バージョン 3.3 で変更: Added service_actions call to the serve_forever method.

service_actions()

This is called in the serve_forever() loop. This method can be overridden by subclasses or mixin classes to perform actions specific to a given service, such as cleanup actions.

Added in version 3.3.

shutdown()

Tell the serve_forever() loop to stop and wait until it does. shutdown() must be called while serve_forever() is running in a different thread otherwise it will deadlock.

server_close()

サーバをクリーンアップします。上書き出来ます。

address_family

サーバのソケットが属しているプロトコルファミリです。一般的な値は socket.AF_INET および socket.AF_UNIX です。

RequestHandlerClass

ユーザが提供する要求処理クラスです; 要求ごとにこのクラスのインスタンスが生成されます。

server_address

サーバが要求待ちを行うアドレスです。アドレスの形式はプロトコルファミリによって異なります。詳細は socket モジュールを参照してください。インターネットプロトコルでは、この値は例えば ('127.0.0.1', 80) のようにアドレスを与える文字列と整数のポート番号を含むタプルです。

socket

サーバが入力の要求待ちを行うためのソケットオブジェクトです。

サーバクラスは以下のクラス変数をサポートします:

allow_reuse_address

サーバがアドレスの再使用を許すかどうかを示す値です。この値は標準で False で、サブクラスで再使用ポリシを変更するために設定することができます。

request_queue_size

要求待ち行列 (queue) のサイズです。単一の要求を処理するのに長時間かかる場合には、サーバが処理中に届いた要求は最大 request_queue_size 個まで待ち行列に置かれます。待ち行列が一杯になると、それ以降のクライアントからの要求は "接続拒否 (Connection denied)" エラーになります。標準の値は通常 5 ですが、この値はサブクラスで上書きすることができます。

socket_type

サーバが使うソケットの型です; 一般的な2つの値は、 socket.SOCK_STREAM と socket.SOCK_DGRAM です。

timeout

タイムアウト時間(秒)、もしくは、タイムアウトを望まない場合に None 。 handle_request() がこの時間内にリクエストを受信しない場合、 handle_timeout() メソッドが呼ばれます。

TCPServer のような基底クラスのサブクラスで上書きできるサーバメソッドは多数あります; これらのメソッドはサーバオブジェクトの外部のユーザにとっては役にたたないものです。

finish_request(request, client_address)

RequestHandlerClass をインスタンス化し、 handle() メソッドを呼び出して、実際に要求を処理します。

get_request()

ソケットから要求を受理して、クライアントとの通信に使われる 新しい ソケットオブジェクト、およびクライアントのアドレスからなる、2 要素のタプルを返します。

handle_error(request, client_address)

この関数は RequestHandlerClass インスタンスの handle() メソッドが例外を送出した際に呼び出されます。標準の動作では標準エラー出力へトレースバックを出力し、後続する要求を継続して処理します。

バージョン 3.6 で変更: Now only called for exceptions derived from the Exception class.

handle_timeout()

この関数は timeout 属性が None 以外に設定されて、リクエストがないままタイムアウト秒数が過ぎたときに呼ばれます。 fork型サーバーでのデフォルトの動作は、終了した子プロセスの情報を集めるようになっています。スレッド型サーバーではこのメソッドは何もしません。

process_request(request, client_address)

finish_request() を呼び出して、 RequestHandlerClass のインスタンスを生成します。必要なら、この関数から新たなプロセスかスレッドを生成して要求を処理することができます; その処理は ForkingMixIn または ThreadingMixIn クラスが行います。

server_activate()

Called by the server's constructor to activate the server. The default behavior for a TCP server just invokes listen() on the server's socket. May be overridden.

server_bind()

サーバのコンストラクタによって呼び出され、適切なアドレスにソケットをバインドします。このメソッドは上書きできます。

verify_request(request, client_address)

ブール値を返さなければなりません; 値が True の場合には要求が処理され、 False の場合には要求は拒否されます。サーバへのアクセス制御を実装するためにこの関数を上書きすることができます。標準の実装では常に True を返します。

バージョン 3.6 で変更: context manager プロトコルのサポートが追加されました。コンテキストマネージャを終了することは、 server_close() を呼ぶことと同一です。

Request Handler Objects

class 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 handle() method, and can override any of the other methods. A new instance of the subclass is created for each request.

setup()

handle() メソッドより前に呼び出され、何らかの必要な初期化処理を行います。標準の実装では何も行いません。

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 request; the client address as client_address; and the server instance as server, in case it needs access to per-server information.

The type of request is different for datagram or stream services. For stream services, request is a socket object; for datagram services, request is a pair of string and socket.

finish()

handle() メソッドより後に呼び出され、何らかの必要なクリーンアップ処理を行います。標準の実装では何も行いません。 setup() メソッドが例外を送出した場合、このメソッドは呼び出されません。

request

The new socket.socket object to be used to communicate with the client.

client_address

Client address returned by BaseServer.get_request().

server

BaseServer object used for handling the request.

class socketserver.StreamRequestHandler

class socketserver.DatagramRequestHandler

These BaseRequestHandler subclasses override the setup() and finish() methods, and provide rfile and wfile attributes.

rfile

A file object from which receives the request is read. Support the io.BufferedIOBase readable interface.

wfile

A file object to which the reply is written. Support the io.BufferedIOBase writable interface

バージョン 3.6 で変更: wfile also supports the io.BufferedIOBase writable interface.

使用例

socketserver.TCPServer の例

サーバサイドの例です:

import socketserver

class MyTCPHandler(socketserver.BaseRequestHandler):
    """
    The request handler class for our server.

    It is instantiated once per connection to the server, and must
    override the handle() method to implement communication to the
    client.
    """

    def handle(self):
        # self.request is the TCP socket connected to the client
        self.data = self.request.recv(1024).strip()
        print("Received from {}:".format(self.client_address[0]))
        print(self.data)
        # just send back the same data, but upper-cased
        self.request.sendall(self.data.upper())

if __name__ == "__main__":
    HOST, PORT = "localhost", 9999

    # Create the server, binding to localhost on port 9999
    with socketserver.TCPServer((HOST, PORT), MyTCPHandler) as server:
        # Activate the server; this will keep running until you
        # interrupt the program with Ctrl-C
        server.serve_forever()

別の、ストリーム(標準のファイル型のインターフェースを利用して通信をシンプルにしたファイルライクオブジェクト)を使うリクエストハンドラクラスの例です:

class MyTCPHandler(socketserver.StreamRequestHandler):

    def handle(self):
        # self.rfile is a file-like object created by the handler;
        # we can now use e.g. readline() instead of raw recv() calls
        self.data = self.rfile.readline().strip()
        print("{} wrote:".format(self.client_address[0]))
        print(self.data)
        # Likewise, self.wfile is a file-like object used to write back
        # to the client
        self.wfile.write(self.data.upper())

The difference is that the readline() call in the second handler will call recv() multiple times until it encounters a newline character, while the single recv() call in the first handler will just return what has been received so far from the client's sendall() call (typically all of it, but this is not guaranteed by the TCP protocol).

クライアントサイドの例:

import socket
import sys

HOST, PORT = "localhost", 9999
data = " ".join(sys.argv[1:])

# Create a socket (SOCK_STREAM means a TCP socket)
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
    # Connect to server and send data
    sock.connect((HOST, PORT))
    sock.sendall(bytes(data + "\n", "utf-8"))

    # Receive data from the server and shut down
    received = str(sock.recv(1024), "utf-8")

print("Sent:     {}".format(data))
print("Received: {}".format(received))

この例の出力は次のようになります:

サーバー:

$ python TCPServer.py
127.0.0.1 wrote:
b'hello world with TCP'
127.0.0.1 wrote:
b'python is nice'

クライアント:

$ 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

socketserver.UDPServer の例

サーバサイドの例です:

import socketserver

class MyUDPHandler(socketserver.BaseRequestHandler):
    """
    This class works similar to the TCP handler class, except that
    self.request consists of a pair of data and client socket, and since
    there is no connection the client address must be given explicitly
    when sending data back via sendto().
    """

    def handle(self):
        data = self.request[0].strip()
        socket = self.request[1]
        print("{} wrote:".format(self.client_address[0]))
        print(data)
        socket.sendto(data.upper(), self.client_address)

if __name__ == "__main__":
    HOST, PORT = "localhost", 9999
    with socketserver.UDPServer((HOST, PORT), MyUDPHandler) as server:
        server.serve_forever()

クライアントサイドの例:

import socket
import sys

HOST, PORT = "localhost", 9999
data = " ".join(sys.argv[1:])

# SOCK_DGRAM is the socket type to use for UDP sockets
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)

# As you can see, there is no connect() call; UDP has no connections.
# Instead, data is directly sent to the recipient via sendto().
sock.sendto(bytes(data + "\n", "utf-8"), (HOST, PORT))
received = str(sock.recv(1024), "utf-8")

print("Sent:     {}".format(data))
print("Received: {}".format(received))

この例の出力は、TCPサーバーの例と全く同じようになります。

非同期処理の Mix-in

複数の接続を非同期に処理するハンドラを作るには、 ThreadingMixIn か ForkingMixIn クラスを利用します。

ThreadingMixIn クラスの利用例:

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()

この例の出力は次のようになります:

$ 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

ForkingMixIn クラスは同じように利用することができます。この場合、サーバーはリクエスト毎に新しいプロセスを作成します。fork() をサポートする POSIX プラットフォームでのみ利用可能です。

http.server --- HTTP servers

ソースコード: Lib/http/server.py [https://github.com/python/cpython/tree/3.12/Lib/http/server.py]

このモジュールは HTTP サーバを実装するためのクラスを提供しています。

警告

http.server is not recommended for production. It only implements basic security checks.

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. See WebAssemblyプラットフォーム for more information.

クラス HTTPServer は socketserver.TCPServer のサブクラスです。 HTTPServer は HTTP ソケットを生成してリクエスト待ち (listen) を行い、リクエストをハンドラに渡します。サーバを作成して動作させるためのコードは以下のようになります:

def run(server_class=HTTPServer, handler_class=BaseHTTPRequestHandler):
    server_address = ('', 8000)
    httpd = server_class(server_address, handler_class)
    httpd.serve_forever()

class http.server.HTTPServer(server_address, RequestHandlerClass)

このクラスは TCPServer クラスの上に構築されており、サーバのアドレスをインスタンス変数 server_name および server_port に記憶します。サーバはハンドラからアクセス可能で、通常ハンドラの server インスタンス変数からアクセスします。

class http.server.ThreadingHTTPServer(server_address, RequestHandlerClass)

This class is identical to HTTPServer but uses threads to handle requests by using the ThreadingMixIn. This is useful to handle web browsers pre-opening sockets, on which HTTPServer would wait indefinitely.

Added in version 3.7.

HTTPServer と ThreadingHTTPServer は RequestHandlerClass の初期化のときに与えられなければならず、このモジュールはこのクラスの3つの変種を提供しています:

class http.server.BaseHTTPRequestHandler(request, client_address, server)

このクラスはサーバに到着したリクエストを処理します。このメソッド自体では、実際のリクエストに応答することはできません; (GET や POST のような) 各リクエストメソッドを処理するためにはサブクラス化しなければなりません。 BaseHTTPRequestHandler では、サブクラスで使うためのクラスやインスタンス変数、メソッド群を数多く提供しています。

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 SPAM, the 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 __init__() method.

BaseHTTPRequestHandler は以下のインスタンス変数を持っています:

client_address

HTTP クライアントのアドレスを参照している、(host, port) の形式をとるタプルが入っています。

server

server インスタンスが入っています。

close_connection

handle_one_request() が返る前に設定すべき真偽値で、別のリクエストが期待されているかどうか、もしくはコネクションを切断すべきかどうかを指し示しています。

requestline

HTTP リクエスト行の文字列表現を保持しています。末尾の CRLF は除去されています。この属性は handle_one_request() によって設定されるべきです。妥当なリクエスト行が1行も処理されなかった場合は、空文字列に設定されるべきです。

command

HTTP 命令 (リクエスト形式) が入っています。例えば 'GET' です。

path

Contains the request path. If query component of the URL is present, then path includes the query. Using the terminology of RFC 3986 [https://datatracker.ietf.org/doc/html/rfc3986.html], path here includes hier-part and the query.

request_version

リクエストのバージョン文字列が入っています。例えば 'HTTP/1.0' です。

headers

MessageClass クラス変数で指定されたクラスのインスタンスを保持しています。このインスタンスは HTTP リクエストのヘッダを解釈し、管理しています。 http.client の parse_headers() 関数がヘッダを解釈するために使われ、 HTTP リクエストが妥当な RFC 2822 [https://datatracker.ietf.org/doc/html/rfc2822.html] スタイルのヘッダを提供することを要求します。

rfile

An io.BufferedIOBase input stream, ready to read from the start of the optional input data.

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 io.BufferedIOBase stream.

BaseHTTPRequestHandler は以下の属性を持っています:

server_version

サーバのソフトウェアバージョンを指定します。この値は上書きする必要が生じるかもしれません。書式は複数の文字列を空白で分割したもので、各文字列はソフトウェア名[/バージョン] の形式をとります。例えば、'BaseHTTP/0.2' です。

sys_version

Python 処理系のバージョンが, version_string メソッドや server_version クラス変数で利用可能な形式で入っています。例えば 'Python/1.4' です。

error_message_format

Specifies a format string that should be used by send_error() method for building an error response to the client. The string is filled by default with variables from responses based on the status code that passed to send_error().

error_content_type

エラーレスポンスをクライアントに送信する時に使う Content-Type HTTP ヘッダを指定します。デフォルトでは 'text/html' です。

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 'HTTP/1.1', the server will permit HTTP persistent connections; however, your server must then include an accurate Content-Length header (using send_header()) in all of its responses to clients. For backwards compatibility, the setting defaults to 'HTTP/1.0'.

MessageClass

HTTP ヘッダを解釈するための email.message.Message 類似のクラスを指定します。通常この値が上書きされることはなく、デフォルトの http.client.HTTPMessage になっています。

responses

This attribute contains a mapping of error code integers to two-element tuples containing a short and long message. For example, {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 send_response_only() and send_error() methods.

BaseHTTPRequestHandler インスタンスは以下のメソッドを持っています:

handle()

Calls 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 do_*() methods.

handle_one_request()

This method will parse and dispatch the request to the appropriate do_*() method. You should never need to override it.

handle_expect_100()

HTTP/1.1 準拠のサーバが Expect: 100-continue リクエストヘッダを受け取ったとき、 100 Continue を返し、その後に 200 OK がきます。このメソッドは、サーバがクライアントに継続を要求しない場合、エラーを送出するようにオーバーライドできます。例えば、サーバはレスポンスヘッダとして 417 Expectation Failed を送る選択をし、 return False とできます。

Added in version 3.2.

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 error_message_format attribute and emitted, after a complete set of headers, as the response body. The 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 ???. The body will be empty if the method is HEAD or the response code is one of the following: 1xx, 204 No Content, 205 Reset Content, 304 Not Modified.

バージョン 3.4 で変更: The error response includes a Content-Length header. Added the explain argument.

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 version_string() and date_time_string() methods, respectively. If the server does not intend to send any other headers using the send_header() method, then send_response() should be followed by an end_headers() call.

バージョン 3.3 で変更: Headers are stored to an internal buffer and end_headers() needs to be called explicitly.

send_header(keyword, value)

Adds the HTTP header to an internal buffer which will be written to the output stream when either end_headers() or flush_headers() is invoked. keyword should specify the header keyword, with value specifying its value. Note that, after the send_header calls are done, end_headers() MUST BE called in order to complete the operation.

バージョン 3.2 で変更: ヘッダは内部バッファに保存されます。

send_response_only(code, message=None)

Sends the response header only, used for the purposes when 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.

Added in version 3.2.

end_headers()

Adds a blank line (indicating the end of the HTTP headers in the response) to the headers buffer and calls flush_headers().

バージョン 3.2 で変更: バッファされたヘッダは出力ストリームに書き出されます。

flush_headers()

最終的にヘッダを出力ストリームに送り、内部ヘッダバッファをフラッシュします。

Added in version 3.3.

log_request(code='-', size='-')

受理された (成功した) リクエストをログに記録します。code にはこの応答に関連付けられた HTTP コード番号を指定します。応答メッセージの大きさを知ることができる場合、size パラメタに渡すとよいでしょう。

log_error(...)

リクエストを遂行できなかった際に、エラーをログに記録します。標準では、メッセージを log_message() に渡します。従って同じ引数 (format と追加の値) を取ります。

log_message(format, ...)

任意のメッセージを sys.stderr にログ記録します。このメソッドは通常、カスタムのエラーログ記録機構を作成するために上書きされます。 format 引数は標準の printf 形式の書式文字列で、 log_message() に渡された追加の引数は書式化の入力として適用されます。ログ記録される全てのメッセージには、クライアントの IP アドレスおよび現在の日付、時刻が先頭に付けられます。

version_string()

サーバーのソフトウェアのバージョンを示す文字列を返します。その文字列は、server_version と sys_version の属性が含まれます。

date_time_string(timestamp=None)

メッセージヘッダ向けに書式化された、 timestamp (None または time.time() のフォーマットである必要があります)で与えられた日時を返します。もし timestamp が省略された場合には、現在の日時が使われます。

出力は 'Sun, 06 Nov 1994 08:49:37 GMT' のようになります。

log_date_time_string()

ログ記録向けに書式化された、現在の日付および時刻を返します。

address_string()

クライアントのアドレスを返します。

バージョン 3.3 で変更: Previously, a name lookup was performed. To avoid name resolution delays, it now always returns the IP address.

class 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 で変更: Added the directory parameter.

バージョン 3.9 で変更: The directory parameter accepts a path-like object.

リクエストの解釈のような、多くの作業は基底クラス BaseHTTPRequestHandler で行われます。このクラスは関数 do_GET() および do_HEAD() を実装しています。

SimpleHTTPRequestHandler では以下のメンバ変数を定義しています:

server_version

この値は "SimpleHTTP/" + __version__ になります。__version__ はこのモジュールで定義されている値です。

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.

SimpleHTTPRequestHandler では以下のメソッドを定義しています:

do_HEAD()

このメソッドは 'HEAD' 型のリクエスト処理を実行します: すなわち、 GET リクエストの時に送信されるものと同じヘッダを送信します。送信される可能性のあるヘッダについての完全な説明は do_GET() メソッドを参照してください。

do_GET()

リクエストを現在の作業ディレクトリからの相対的なパスとして解釈することで、リクエストをローカルシステム上のファイルと対応付けます。

リクエストがディレクトリに対応付けられた場合、 index.html または index.htm を (この順序で) チェックします。もしファイルを発見できればその内容を、そうでなければディレクトリ一覧を list_directory() メソッドで生成して、返します。このメソッドは os.listdir() をディレクトリのスキャンに用いており、 listdir() が失敗した場合には 404 応答が返されます。

If the request was mapped to a file, it is opened. Any OSError exception in opening the requested file is mapped to a 404, 'File not found' error. If there was a 'If-Modified-Since' header in the request, and the file was not modified after this time, a 304, 'Not Modified' response is sent. Otherwise, the content type is guessed by calling the guess_type() method, which in turn uses the extensions_map variable, and the file contents are returned.

出力は 'Content-type:' と推測されたコンテントタイプで、その後にファイルサイズを示す 'Content-Length;' ヘッダと、ファイルの更新日時を示す 'Last-Modified:' ヘッダが続きます。

そしてヘッダの終了を示す空白行が続き、さらにその後にファイルの内容が続きます。このファイルはコンテントタイプが text/ で始まっている場合はテキストモードで、そうでなければバイナリモードで開かれます。

For example usage, see the implementation of the test function in Lib/http/server.py [https://github.com/python/cpython/tree/3.12/Lib/http/server.py].

バージョン 3.7 で変更: Support of the 'If-Modified-Since' header.

The SimpleHTTPRequestHandler class can be used in the following manner in order to create a very basic webserver serving files relative to the current directory:

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()

SimpleHTTPRequestHandler can also be subclassed to enhance behavior, such as using different index file names by overriding the class attribute index_pages.

http.server はインタプリタの -m スイッチを使って直接実行することもできます。上の例と同じように、これはカレントディレクトリ以下のファイルへのアクセスを提供します:

python -m http.server

The server listens to port 8000 by default. The default can be overridden by passing the desired port number as an argument:

python -m http.server 9000

By default, the server binds itself to all interfaces. The option -b/--bind specifies a specific address to which it should bind. Both IPv4 and IPv6 addresses are supported. For example, the following command causes the server to bind to localhost only:

python -m http.server --bind 127.0.0.1

バージョン 3.4 で変更: Added the --bind option.

バージョン 3.8 で変更: Support IPv6 in the --bind option.

By default, the server uses the current directory. The option -d/--directory specifies a directory to which it should serve the files. For example, the following command uses a specific directory:

python -m http.server --directory /tmp/

バージョン 3.7 で変更: Added the --directory option.

By default, the server is conformant to HTTP/1.0. The option -p/--protocol specifies the HTTP version to which the server is conformant. For example, the following command runs an HTTP/1.1 conformant server:

python -m http.server --protocol HTTP/1.1

バージョン 3.11 で変更: Added the --protocol option.

class http.server.CGIHTTPRequestHandler(request, client_address, server)

このクラスは、現在のディレクトリかその下のディレクトリにおいて、ファイルか CGI スクリプト出力を提供するために使われます。 HTTP 階層構造からローカルなディレクトリ構造への対応付けは SimpleHTTPRequestHandler と全く同じなので注意してください。

注釈

CGIHTTPRequestHandler クラスで実行される CGI スクリプトは HTTP コード 200 (スクリプトの出力が後に続く) を実行に先立って出力される (これがステータスコードになります) ため、リダイレクト(コード302) を行なうことができません。

このクラスでは、ファイルが CGI スクリプトであると推測された場合、これをファイルとして提供する代わりにスクリプトを実行します。 --- 他の一般的なサーバ設定は特殊な拡張子を使って CGI スクリプトであることを示すのに対し、ディレクトリベースの CGI だけが使われます。

do_GET() および do_HEAD() 関数は、HTTP 要求が cgi_directories パス以下のどこかを指している場合、ファイルを提供するのではなく、CGI スクリプトを実行してその出力を提供するように変更されています。

CGIHTTPRequestHandler では以下のデータメンバを定義しています:

cgi_directories

この値は標準で ['/cgi-bin', '/htbin'] であり、CGI スクリプトを含んでいることを示すディレクトリを記述します。

CGIHTTPRequestHandler は以下のメソッドを定義しています:

do_POST()

このメソッドは、CGI スクリプトでのみ許されている 'POST' 型の HTTP 要求に対するサービスを行います。CGI でない url に対して POST を試みた場合、出力は Error 501, "Can only POST to CGI scripts" になります。

セキュリティ上の理由から、CGI スクリプトはユーザ nobody の UID で動作するので注意してください。 CGI スクリプトが原因で発生した問題は、Error 403 に変換されます。

CGIHTTPRequestHandler can be enabled in the command line by passing the --cgi option:

python -m http.server --cgi

警告

CGIHTTPRequestHandler and the --cgi command line option are not intended for use by untrusted clients and may be vulnerable to exploitation. Always use within a secure environment.

セキュリティで考慮すべき点

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 python -m http.server or the default BaseHTTPRequestHandler .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.

http.cookies --- HTTP state management

ソースコード: Lib/http/cookies.py [https://github.com/python/cpython/tree/3.12/Lib/http/cookies.py]

http.cookies モジュールはHTTPの状態管理機能であるcookieの概念を抽象化、定義しているクラスです。単純な文字列のみで構成されるcookieのほか、シリアル化可能なあらゆるデータ型でクッキーの値を保持するための機能も備えています。

The module formerly strictly applied the parsing rules described in the RFC 2109 [https://datatracker.ietf.org/doc/html/rfc2109.html] and RFC 2068 [https://datatracker.ietf.org/doc/html/rfc2068.html] specifications. It has since been discovered that MSIE 3.0x didn't follow the character rules outlined in those specs; many current-day browsers and servers have also relaxed parsing rules when it comes to cookie handling. As a result, this module now uses parsing rules that are a bit less strict than they once were.

The character set, string.ascii_letters, string.digits and !#$%&'*+-.^_`|~: denote the set of valid characters allowed by this module in a cookie name (as key).

バージョン 3.3 で変更: Allowed ':' as a valid cookie name character.

注釈

不正な cookie に遭遇した場合、 CookieError 例外を送出します。そのため、ブラウザから持ってきた cookie データをパースするときには常に不正なデータに備え CookieError 例外を捕捉してください。

exception http.cookies.CookieError

属性や Set-Cookie ヘッダが正しくないなど、 RFC 2109 [https://datatracker.ietf.org/doc/html/rfc2109.html] に合致していないときに発生する例外です。

class http.cookies.BaseCookie([input])

このクラスはキーが文字列、値が Morsel インスタンスで構成される辞書風オブジェクトです。値に対するキーを設定するときは、値がキーと値を含む Morsel に変換されることに注意してください。

input が与えられたときは、そのまま load() メソッドへ渡されます。

class http.cookies.SimpleCookie([input])

This class derives from BaseCookie and overrides value_decode() and value_encode(). SimpleCookie supports strings as cookie values. When setting the value, SimpleCookie calls the builtin str() to convert the value to a string. Values received from HTTP are kept as strings.

参考

モジュール http.cookiejar

Web クライアント 向けの HTTP クッキー処理です。 http.cookiejar と http.cookies は互いに独立しています。

RFC 2109 [https://datatracker.ietf.org/doc/html/rfc2109.html] - HTTP State Management Mechanism

このモジュールが実装しているHTTPの状態管理に関する規格です。

Cookieオブジェクト

BaseCookie.value_decode(val)

Return a tuple (real_value, coded_value) from a string representation. real_value can be any type. This method does no decoding in BaseCookie --- it exists so it can be overridden.

BaseCookie.value_encode(val)

Return a tuple (real_value, coded_value). val can be any type, but coded_value will always be converted to a string. This method does no encoding in BaseCookie --- it exists so it can be overridden.

通常 value_encode() と value_decode() はともに value_decode の処理内容から逆算した範囲に収まっていなければなりません。

BaseCookie.output(attrs=None, header='Set-Cookie:', sep='\r\n')

HTTPヘッダ形式の文字列表現を返します。 attrs と header はそれぞれ Morsel の output() メソッドに送られます。 sep はヘッダの連結に用いられる文字で、デフォルトは '\r\n' (CRLF)となっています。

BaseCookie.js_output(attrs=None)

ブラウザがJavaScriptをサポートしている場合、HTTPヘッダを送信した場合と同様に動作する埋め込み可能なJavaScript snippetを返します。

attrs の意味は output() と同じです。

BaseCookie.load(rawdata)

rawdata が文字列であれば、 HTTP_COOKIE として処理し、その値を Morsel として追加します。辞書の場合は次と同様の処理をおこないます。

for k, v in rawdata.items():
    cookie[k] = v

Morselオブジェクト

class http.cookies.Morsel

RFC 2109 [https://datatracker.ietf.org/doc/html/rfc2109.html] の属性をキーと値で保持するabstractクラスです。

Morsels are dictionary-like objects, whose set of keys is constant --- the valid RFC 2109 [https://datatracker.ietf.org/doc/html/rfc2109.html] attributes, which are:

expires

path

comment

domain

max-age

secure

version

httponly

samesite

httponly 属性は、 cookie が HTTP リクエストでのみ送信されて、 JavaScript からのはアクセスできない事を示します。これはいくつかのクロスサイトスクリプティングの脅威を和らげることを意図しています。

The attribute samesite specifies that the browser is not allowed to send the cookie along with cross-site requests. This helps to mitigate CSRF attacks. Valid values for this attribute are "Strict" and "Lax".

キーの大小文字は区別されません。そのデフォルト値は '' です。

バージョン 3.5 で変更: __eq__() now takes key and value into account.

バージョン 3.7 で変更: Attributes key, value and coded_value are read-only. Use set() for setting them.

バージョン 3.8 で変更: samesite 属性がサポートされました。

Morsel.value

クッキーの値。

Morsel.coded_value

実際に送信する形式にエンコードされたcookieの値。

Morsel.key

cookieの名前。

Morsel.set(key, value, coded_value)

属性 key 、 value 、 coded_value に値をセットします。

Morsel.isReservedKey(K)

K が Morsel のキーであるかどうかを判定します。

Morsel.output(attrs=None, header='Set-Cookie:')

MoselをHTTPヘッダ形式の文字列表現にして返します。 attrs を指定しない場合、デフォルトですべての属性を含めます。 attrs を指定する場合、属性をリストで渡さなければなりません。 header のデフォルトは "Set-Cookie:" です。

Morsel.js_output(attrs=None)

ブラウザがJavaScriptをサポートしている場合、HTTPヘッダを送信した場合と同様に動作する埋め込み可能なJavaScript snippetを返します。

attrs の意味は output() と同じです。

Morsel.OutputString(attrs=None)

Moselの文字列表現をHTTPやJavaScriptで囲まずに出力します。

attrs の意味は output() と同じです。

Morsel.update(values)

Morsel 辞書の値を辞書 values の値で更新します。values 辞書のキーのいずれかが有効な RFC 2109 [https://datatracker.ietf.org/doc/html/rfc2109.html] 属性でない場合エラーを送出します。

バージョン 3.5 で変更: 不正なキーではエラーが送出されます。

Morsel.copy(value)

Morsel オブジェクトの浅いコピーを返します。

バージョン 3.5 で変更: 辞書ではなく Morsel オブジェクトを返します。

Morsel.setdefault(key, value=None)

キーが有効な RFC 2109 [https://datatracker.ietf.org/doc/html/rfc2109.html] 属性でない場合エラーを送出します。そうでない場合は dict.setdefault() と同じように振る舞います。

使用例

次の例は http.cookies の使い方を示したものです。

>>> from http import cookies
>>> C = cookies.SimpleCookie()
>>> C["fig"] = "newton"
>>> C["sugar"] = "wafer"
>>> print(C) # generate HTTP headers
Set-Cookie: fig=newton
Set-Cookie: sugar=wafer
>>> print(C.output()) # same thing
Set-Cookie: fig=newton
Set-Cookie: sugar=wafer
>>> C = cookies.SimpleCookie()
>>> C["rocky"] = "road"
>>> C["rocky"]["path"] = "/cookie"
>>> print(C.output(header="Cookie:"))
Cookie: rocky=road; Path=/cookie
>>> print(C.output(attrs=[], header="Cookie:"))
Cookie: rocky=road
>>> C = cookies.SimpleCookie()
>>> C.load("chips=ahoy; vienna=finger") # load from a string (HTTP header)
>>> print(C)
Set-Cookie: chips=ahoy
Set-Cookie: vienna=finger
>>> C = cookies.SimpleCookie()
>>> C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=\\012;";')
>>> print(C)
Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=\012;"
>>> C = cookies.SimpleCookie()
>>> C["oreo"] = "doublestuff"
>>> C["oreo"]["path"] = "/"
>>> print(C)
Set-Cookie: oreo=doublestuff; Path=/
>>> C = cookies.SimpleCookie()
>>> C["twix"] = "none for you"
>>> C["twix"].value
'none for you'
>>> C = cookies.SimpleCookie()
>>> C["number"] = 7 # equivalent to C["number"] = str(7)
>>> C["string"] = "seven"
>>> C["number"].value
'7'
>>> C["string"].value
'seven'
>>> print(C)
Set-Cookie: number=7
Set-Cookie: string=seven

http.cookiejar --- Cookie handling for HTTP clients

ソースコード: Lib/http/cookiejar.py [https://github.com/python/cpython/tree/3.12/Lib/http/cookiejar.py]

http.cookiejar モジュールは HTTP クッキーの自動処理をおこなうクラスを定義します。これは小さなデータの断片 -- クッキー -- を要求する web サイトにアクセスする際に有用です。クッキーとは web サーバの HTTP レスポンスによってクライアントのマシンに設定され、のちの HTTP リクエストをおこなうさいにサーバに返されるものです。

標準的な Netscape クッキープロトコルおよび RFC 2965 [https://datatracker.ietf.org/doc/html/rfc2965.html] で定義されているプロトコルの両方を処理できます。RFC 2965 の処理はデフォルトではオフになっています。 RFC 2109 [https://datatracker.ietf.org/doc/html/rfc2109.html] のクッキーは Netscape クッキーとして解析され、のちに有効な 'ポリシー' に従って Netscapeまたは RFC 2965 クッキーとして処理されます。但し、インターネット上の大多数のクッキーは Netscapeクッキーです。 http.cookiejar はデファクトスタンダードの Netscape クッキープロトコル (これは元々 Netscape が策定した仕様とはかなり異なっています) に従うようになっており、RFC 2109 で導入された max-age や port などのクッキー属性にも注意を払います。

注釈

Set-Cookie や Set-Cookie2 ヘッダに現れる多種多様なパラメータの名前 (domain や expires など) は便宜上 属性 と呼ばれますが、ここでは Python の属性と区別するため、かわりに クッキー属性 と呼ぶことにします。

このモジュールは以下の例外を定義しています:

exception http.cookiejar.LoadError

この例外は FileCookieJar インスタンスがファイルからクッキーを読み込むのに失敗した場合に発生します。 LoadError は OSError のサブクラスです。

バージョン 3.3 で変更: LoadError used to be a subtype of IOError, which is now an alias of OSError.

以下のクラスが提供されています:

class http.cookiejar.CookieJar(policy=None)

policy は CookiePolicy インターフェイスを実装するオブジェクトです。

CookieJar クラスには HTTP クッキーを保管します。これは HTTP リクエストに応じてクッキーを取り出し、それを HTTP レスポンスの中で返します。必要に応じて、 CookieJar インスタンスは保管されているクッキーを自動的に破棄します。このサブクラスは、クッキーをファイルやデータベースに格納したり取り出したりする操作をおこなう役割を負っています。

class http.cookiejar.FileCookieJar(filename=None, delayload=None, policy=None)

policy は CookiePolicy インターフェイスを実装するオブジェクトです。これ以外の引数については、該当する属性の説明を参照してください。

FileCookieJar はディスク上のファイルからのクッキーの読み込み、もしくは書き込みをサポートします。実際には、 load() または revert() のどちらかのメソッドが呼ばれるまでクッキーは指定されたファイルからはロード されません 。このクラスのサブクラスは FileCookieJar のサブクラスと web ブラウザとの連携 節で説明します。

This should not be initialized directly – use its subclasses below instead.

バージョン 3.8 で変更: filename 引数が path-like object を受け付けるようになりました。

class http.cookiejar.CookiePolicy

このクラスは、あるクッキーをサーバから受け入れるべきか、そしてサーバに返すべきかを決定する役割を負っています。

class http.cookiejar.DefaultCookiePolicy(blocked_domains=None, allowed_domains=None, netscape=True, rfc2965=False, rfc2109_as_netscape=None, hide_cookie2=False, strict_domain=False, strict_rfc2965_unverifiable=True, strict_ns_unverifiable=False, strict_ns_domain=DefaultCookiePolicy.DomainLiberal, strict_ns_set_initial_dollar=False, strict_ns_set_path=False, secure_protocols=('https', 'wss'))

Constructor arguments should be passed as keyword arguments only. blocked_domains is a sequence of domain names that we never accept cookies from, nor return cookies to. allowed_domains if not None, this is a sequence of the only domains for which we accept and return cookies. secure_protocols is a sequence of protocols for which secure cookies can be added to. By default https and wss (secure websocket) are considered secure protocols. For all other arguments, see the documentation for CookiePolicy and DefaultCookiePolicy objects.

DefaultCookiePolicy は Netscape および RFC 2965 [https://datatracker.ietf.org/doc/html/rfc2965.html] クッキーの標準的な許可 / 拒絶のルールを実装しています。デフォルトでは、 RFC 2109 [https://datatracker.ietf.org/doc/html/rfc2109.html] のクッキー (Set-Cookie の version クッキー属性が 1 で受けとられるもの) は RFC 2965 のルールで扱われます。しかし、RFC 2965 処理が無効に設定されているか rfc2109_as_netscape が True の場合、RFC 2109 クッキーは CookieJar インスタンスによって Cookie のインスタンスの version 属性を 0 に設定する事で Netscapeクッキーに「ダウングレード」されます。また DefaultCookiePolicy にはいくつかの細かいポリシー設定をおこなうパラメータが用意されています。

class http.cookiejar.Cookie

このクラスは Netscape クッキー、 RFC 2109 [https://datatracker.ietf.org/doc/html/rfc2109.html] のクッキー、および RFC 2965 [https://datatracker.ietf.org/doc/html/rfc2965.html] のクッキーを表現します。 http.cookiejar のユーザが自分で Cookie インスタンスを作成することは想定されていません。かわりに、必要に応じて CookieJar インスタンスの make_cookies() を呼ぶことになっています。

参考

urllib.request モジュール

クッキーの自動処理をおこない URL を開くモジュールです。

http.cookies モジュール

HTTP のクッキークラスで、基本的にはサーバサイドのコードで有用です。 http.cookiejar および http.cookies モジュールは互いに依存してはいません。

https://curl.se/rfc/cookie_spec.html

元祖 Netscape のクッキープロトコルの仕様です。今でもこれが主流のプロトコルですが、現在のメジャーなブラウザ (と http.cookiejar) が実装している「Netscape クッキープロトコル」は cookie_spec.html で述べられているものとおおまかにしか似ていません。

RFC 2109 [https://datatracker.ietf.org/doc/html/rfc2109.html] - HTTP State Management Mechanism

RFC 2965 [https://datatracker.ietf.org/doc/html/rfc2965.html] によって過去の遺物になりました。 Set-Cookie の version=1 で使います。

RFC 2965 [https://datatracker.ietf.org/doc/html/rfc2965.html] - HTTP State Management Mechanism

Netscape プロトコルのバグを修正したものです。 Set-Cookie のかわりに Set-Cookie2 を使いますが、普及してはいません。

http://kristol.org/cookie/errata.html

RFC 2965 [https://datatracker.ietf.org/doc/html/rfc2965.html] に対する未完の正誤表です。

RFC 2964 [https://datatracker.ietf.org/doc/html/rfc2964.html] - Use of HTTP State Management

CookieJar および FileCookieJar オブジェクト

CookieJar オブジェクトは保管されている Cookie オブジェクトをひとつずつ取り出すための、 イテレータ プロトコルをサポートしています。

CookieJar は以下のようなメソッドを持っています:

CookieJar.add_cookie_header(request)

request に正しい Cookie ヘッダを追加します。

ポリシーが許すようであれば (CookieJar の CookiePolicy インスタンスにある属性のうち、 rfc2965 および hide_cookie2 がそれぞれ真と偽であるような場合)、必要に応じて Cookie2 ヘッダも追加されます。

request オブジェクト (通常は urllib.request.Request インスタンス) は、 urllib.request のドキュメントに記されているように、メソッド get_full_url(), has_header(), get_header(), header_items(), add_unredirected_header() および属性 host, type, unverifiable, origin_req_host をサポートしている必要があります。

バージョン 3.3 で変更: request object needs origin_req_host attribute. Dependency on a deprecated method get_origin_req_host() has been removed.

CookieJar.extract_cookies(response, request)

HTTP response からクッキーを取り出し、ポリシーによって許可されていればこれを CookieJar 内に保管します。

CookieJar は response 引数の中から許可されている Set-Cookie および Set-Cookie2 ヘッダを探しだし、適切に (CookiePolicy.set_ok() メソッドの承認におうじて) クッキーを保管します。

response オブジェクト (通常は urllib.request.urlopen() あるいはそれに類似する呼び出しによって得られます) は info() メソッドをサポートしている必要があります。これは email.message.Message メソッドのあるオブジェクトを返すものです。

request オブジェクト (通常は urllib.request.Request インスタンス) は urllib.request のドキュメントに記されているように、メソッド get_full_url(), および属性 host, unverifiable, origin_req_host をサポートしている必要があります。この request はそのクッキーの保存が許可されているかを検査するとともに、クッキー属性のデフォルト値を設定するのに使われます。

バージョン 3.3 で変更: request object needs origin_req_host attribute. Dependency on a deprecated method get_origin_req_host() has been removed.

CookieJar.set_policy(policy)

使用する CookiePolicy インスタンスを指定します。

CookieJar.make_cookies(response, request)

response オブジェクトから得られた Cookie オブジェクトからなるシーケンスを返します。

response および request 引数で要求されるインスタンスについては、 extract_cookies() の説明を参照してください。

CookieJar.set_cookie_if_ok(cookie, request)

ポリシーが許すのであれば、与えられた Cookie を設定します。

CookieJar.set_cookie(cookie)

与えられた Cookie を、それが設定されるべきかどうかのポリシーのチェックを行わずに設定します。

CookieJar.clear([domain[, path[, name]]])

いくつかのクッキーを消去します。

引数なしで呼ばれた場合は、すべてのクッキーを消去します。引数がひとつ与えられた場合、その domain に属するクッキーのみを消去します。ふたつの引数が与えられた場合、指定された domain と URL path に属するクッキーのみを消去します。引数が 3つ与えられた場合、domain, path および name で指定されるクッキーが消去されます。

与えられた条件に一致するクッキーがない場合は KeyError を発生させます。

CookieJar.clear_session_cookies()

すべてのセッションクッキーを消去します。

保存されているクッキーのうち、 discard 属性が真になっているものすべてを消去します (通常これは max-age または expires のどちらのクッキー属性もないか、あるいは明示的に discard クッキー属性が指定されているものです)。対話的なブラウザの場合、セッションの終了はふつうブラウザのウィンドウを閉じることに相当します。

注意: ignore_discard 引数に真を指定しないかぎり、 save() メソッドはセッションクッキーは保存しません。

さらに FileCookieJar は以下のようなメソッドを実装しています:

FileCookieJar.save(filename=None, ignore_discard=False, ignore_expires=False)

クッキーをファイルに保存します。

この基底クラスは NotImplementedError を発生させます。サブクラスはこのメソッドを実装しないままにしておいてもかまいません。

filename はクッキーを保存するファイルの名前です。 filename が指定されない場合、 self.filename が使用されます (このデフォルト値は、それが存在する場合は、コンストラクタに渡されています)。 self.filename も None の場合は ValueError が発生します。

ignore_discard : 破棄されるよう指示されていたクッキーでも保存します。ignore_expires : 期限の切れたクッキーでも保存します。

ここで指定されたファイルがもしすでに存在する場合は上書きされるため、以前にあったクッキーはすべて消去されます。保存したクッキーはあとで load() または revert() メソッドを使って復元することができます。

FileCookieJar.load(filename=None, ignore_discard=False, ignore_expires=False)

ファイルからクッキーを読み込みます。

それまでのクッキーは新しいものに上書きされない限り残ります。

ここでの引数の値は save() と同じです。

名前のついたファイルはこのクラスがわかるやり方で指定する必要があります。さもないと LoadError が発生します。さらに、例えばファイルが存在しないような時に OSError が発生する場合があります。

バージョン 3.3 で変更: 以前は IOError が送出されました; それは現在 OSError のエイリアスです。

FileCookieJar.revert(filename=None, ignore_discard=False, ignore_expires=False)

すべてのクッキーを破棄し、保存されているファイルから読み込み直します。

revert() は load() と同じ例外を発生させる事ができます。失敗した場合、オブジェクトの状態は変更されません。

FileCookieJar インスタンスは以下のような公開の属性をもっています:

FileCookieJar.filename

クッキーを保存するデフォルトのファイル名を指定します。この属性には代入することができます。

FileCookieJar.delayload

真であれば、クッキーを読み込むさいにディスクから遅延読み込みします。この属性には代入することができません。この情報は単なるヒントであり、 (ディスク上のクッキーが変わらない限りは) インスタンスのふるまいには影響を与えず、パフォーマンスのみに影響します。 CookieJar オブジェクトはこの値を無視することもあります。標準ライブラリに含まれている FileCookieJar クラスで遅延読み込みをおこなうものはありません。

FileCookieJar のサブクラスと web ブラウザとの連携

クッキーの読み書きのために、以下の CookieJar サブクラスが提供されています。

class http.cookiejar.MozillaCookieJar(filename=None, delayload=None, policy=None)

Mozilla の cookies.txt ファイル形式 (この形式はまた curl や Lynx と Netscape ブラウザによっても使われています) でディスクにクッキーを読み書きするための FileCookieJar です。

注釈

このクラスは RFC 2965 [https://datatracker.ietf.org/doc/html/rfc2965.html] クッキーに関する情報を失います。また、より新しいか、標準でない port などのクッキー属性についての情報も失います。

警告

もしクッキーの損失や欠損が望ましくない場合は、クッキーを保存する前にバックアップを取っておくようにしてください (ファイルへの読み込み / 保存をくり返すと微妙な変化が生じる場合があります)。

また、Mozilla の起動中にクッキーを保存すると、Mozilla によって内容が破壊されてしまうことにも注意してください。

class http.cookiejar.LWPCookieJar(filename=None, delayload=None, policy=None)

libwww-perl のライブラリである Set-Cookie3 ファイル形式でディスクにクッキーを読み書きするための FileCookieJar です。これはクッキーを人間に可読な形式で保存するのに向いています。

バージョン 3.8 で変更: filename 引数が path-like object を受け付けるようになりました。

CookiePolicy オブジェクト

CookiePolicy インターフェイスを実装するオブジェクトは以下のようなメソッドを持っています:

CookiePolicy.set_ok(cookie, request)

クッキーがサーバから受け入れられるべきかどうかを表わす boolean 値を返します。

cookie は Cookie インスタンスです。 request は CookieJar.extract_cookies() の説明で定義されているインターフェイスを実装するオブジェクトです。

CookiePolicy.return_ok(cookie, request)

クッキーがサーバに返されるべきかどうかを表わす boolean 値を返します。

cookie は Cookie インスタンスです。 request は CookieJar.add_cookie_header() の説明で定義されているインターフェイスを実装するオブジェクトです。

CookiePolicy.domain_return_ok(domain, request)

与えられたクッキーのドメインに対して、そこにクッキーを返すべきでない場合には False を返します。

このメソッドは高速化のためのものです。これにより、すべてのクッキーをある特定のドメインに対してチェックする (これには多数のファイル読みこみを伴なう場合があります) 必要がなくなります。 domain_return_ok() および path_return_ok() の両方から true が返された場合、すべての決定は return_ok() に委ねられます。

もし、このクッキードメインに対して domain_return_ok() が true を返すと、つぎにそのクッキーのパス名に対して path_return_ok() が呼ばれます。そうでない場合、そのクッキードメインに対する path_return_ok() および return_ok() は決して呼ばれることはありません。 path_return_ok() が true を返すと、 return_ok() がその Cookie オブジェクト自身の全チェックのために呼ばれます。そうでない場合、そのクッキーパス名に対する return_ok() は決して呼ばれることはありません。

注意: domain_return_ok() は request ドメインだけではなく、すべての cookie ドメインに対して呼ばれます。たとえば request ドメインが "www.example.com" だった場合、この関数は ".example.com" および "www.example.com" の両方に対して呼ばれることがあります。同じことは path_return_ok() にもいえます。

request 引数は return_ok() で説明されているとおりです。

CookiePolicy.path_return_ok(path, request)

与えられたクッキーのパス名に対して、そこにクッキーを返すべきでない場合には False を返します。

domain_return_ok() の説明を参照してください。

上のメソッドの実装にくわえて、 CookiePolicy インターフェイスの実装では以下の属性を設定する必要があります。これはどのプロトコルがどのように使われるべきかを示すもので、これらの属性にはすべて代入することが許されています。

CookiePolicy.netscape

Netscape プロトコルを実装していることを示します。

CookiePolicy.rfc2965

RFC 2965 [https://datatracker.ietf.org/doc/html/rfc2965.html] プロトコルを実装していることを示します。

CookiePolicy.hide_cookie2

Cookie2 ヘッダをリクエストに含めないようにします (このヘッダが存在する場合、私たちは RFC 2965 [https://datatracker.ietf.org/doc/html/rfc2965.html] クッキーを理解するということをサーバに示すことになります)。

もっとも有用な方法は、 DefaultCookiePolicy をサブクラス化した CookiePolicy クラスを定義して、いくつか (あるいはすべて) のメソッドをオーバーライドすることでしょう。 CookiePolicy 自体はどのようなクッキーも受け入れて設定を許可する「ポリシー無し」ポリシーとして使うこともできます (これが役に立つことはあまりありませんが)。

DefaultCookiePolicy オブジェクト

クッキーを受けつけ、またそれを返す際の標準的なルールを実装します。

RFC 2965 [https://datatracker.ietf.org/doc/html/rfc2965.html] クッキーと Netscape クッキーの両方に対応しています。デフォルトでは、RFC 2965 の処理はオフになっています。

自分のポリシーを提供するいちばん簡単な方法は、このクラスを継承して、自分用の追加チェックの前にオーバーライドした元のメソッドを呼び出すことです:

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

CookiePolicy インターフェイスを実装するのに必要な機能に加えて、このクラスではクッキーを受けとったり設定したりするドメインを許可したり拒絶したりできるようになっています。ほかにも、 Netscape プロトコルのかなり緩い規則をややきつくするために、いくつかの厳密性のスイッチがついています (いくつかの良性クッキーをブロックする危険性もありますが)。

ドメインの拒否リストや許可リストも提供されています (デフォルトではどちらもオフです)。拒否リストになく、(許可リストがアクティブなら) 許可リストにあるドメインのみがクッキーを設定したり返したりできます。コンストラクタの引数 blocked_domains 、および blocked_domains() と set_blocked_domains() メソッド ( そして allowed_domains に対応する引数とメソッド) を使ってください。許可リストを設定した場合は、それを None にすることでオフに戻せます。

拒否あるいは許可リスト中にあるドメインのうち、ドット (.) で始まっていないものは、正確にそれと一致するドメインのクッキーにしか適用されません。たとえば拒否リスト中のエントリ "example.com" は、"example.com" にはマッチしますが、"www.example.com" にはマッチしません。一方ドット (.) で始まっているドメインは、より特化されたドメインともマッチします。たとえば、".example.com" は、"www.example.com" と "www.coyote.example.com" の両方にマッチします (が、"example.com" 自身にはマッチしません)。IP アドレスは例外で、つねに正確に一致する必要があります。たとえば、blocked_domains が "192.168.1.2" と ".168.1.2" を含んでいるとすると、192.168.1.2 はブロックされますが、193.168.1.2 はブロックされません。

DefaultCookiePolicy は以下のような追加メソッドを実装しています:

DefaultCookiePolicy.blocked_domains()

ブロックしているドメインのシーケンスを (タプルとして) 返します。

DefaultCookiePolicy.set_blocked_domains(blocked_domains)

ブロックするドメインを設定します。

DefaultCookiePolicy.is_blocked(domain)

domain がクッキーを授受しない拒否リストに載っていれば True を返します。

DefaultCookiePolicy.allowed_domains()

None あるいは明示的に許可されているドメインを (タプルとして) 返します。

DefaultCookiePolicy.set_allowed_domains(allowed_domains)

許可するドメイン、あるいは None を設定します。

DefaultCookiePolicy.is_not_allowed(domain)

domain がクッキーを授受する許可リストに載っていれば True を返します。

DefaultCookiePolicy インスタンスは以下の属性をもっています。これらはすべてコンストラクタから同じ名前の引数をつかって初期化することができ、代入してもかまいません。

DefaultCookiePolicy.rfc2109_as_netscape

真の場合、 CookieJar のインスタンスに RFC 2109 [https://datatracker.ietf.org/doc/html/rfc2109.html] クッキー (即ち Set-Cookie ヘッダのクッキー属性 Version の値が 1 のクッキー) を Netscapeクッキーへ、 Cookie インスタンスの version 属性を 0 に設定する事でダウングレードするように要求します。デフォルトの値は None であり、この場合 RFC 2109 クッキーは RFC 2965 [https://datatracker.ietf.org/doc/html/rfc2965.html] 処理が無効に設定されている場合に限りダウングレードされます。それ故に RFC 2109 クッキーはデフォルトではダウングレードされます。

一般的な厳密性のスイッチ:

DefaultCookiePolicy.strict_domain

サイトに、国別コードとトップレベルドメインだけからなるドメイン名 (.co.uk, .gov.uk, .co.nz など) を設定させないようにします。これは完璧からはほど遠い実装であり、いつもうまくいくとは限りません!

RFC 2965 [https://datatracker.ietf.org/doc/html/rfc2965.html] プロトコルの厳密性に関するスイッチ:

DefaultCookiePolicy.strict_rfc2965_unverifiable

検証不可能なトランザクション (通常これはリダイレクトか、別のサイトがホスティングしているイメージの読み込み要求です) に関する RFC 2965 [https://datatracker.ietf.org/doc/html/rfc2965.html] の規則に従います。この値が偽の場合、検証可能性を基準にしてクッキーがブロックされることは 決して ありません

Netscape プロトコルの厳密性に関するスイッチ:

DefaultCookiePolicy.strict_ns_unverifiable

検証不可能なトランザクションに関する RFC 2965 [https://datatracker.ietf.org/doc/html/rfc2965.html] の規則を Netscape クッキーに対しても適用します。

DefaultCookiePolicy.strict_ns_domain

Netscape クッキーに対するドメインマッチングの規則をどの程度厳しくするかを指示するフラグです。とりうる値については下の説明を見てください。

DefaultCookiePolicy.strict_ns_set_initial_dollar

Set-Cookie: ヘッダで、'$' で始まる名前のクッキーを無視します。

DefaultCookiePolicy.strict_ns_set_path

要求した URI にパスがマッチしないクッキーの設定を禁止します。

strict_ns_domain はいくつかのフラグの集合です。これはいくつかの値を or することで構成します (たとえば DomainStrictNoDots|DomainStrictNonDomain は両方のフラグが設定されていることになります)。

DefaultCookiePolicy.DomainStrictNoDots

クッキーを設定するさい、ホスト名のプレフィクスにドットが含まれるのを禁止します (例: www.foo.bar.com は .bar.com のクッキーを設定することはできません、なぜなら www.foo はドットを含んでいるからです)。

DefaultCookiePolicy.DomainStrictNonDomain

domain クッキー属性を明示的に指定していないクッキーは、そのクッキーを設定したドメインと同一のドメインだけに返されます (例: example.com からのクッキーに domain クッキー属性がない場合、そのクッキーが spam.example.com に返されることはありません)。

DefaultCookiePolicy.DomainRFC2965Match

クッキーを設定するさい、 RFC 2965 [https://datatracker.ietf.org/doc/html/rfc2965.html] の完全ドメインマッチングを要求します。

以下の属性は上記のフラグのうちもっともよく使われる組み合わせで、便宜をはかるために提供されています:

DefaultCookiePolicy.DomainLiberal

0 と同じです (つまり、上述の Netscape のドメイン厳密性フラグがすべてオフにされます)。

DefaultCookiePolicy.DomainStrict

DomainStrictNoDots|DomainStrictNonDomain と同じです。

Cookieオブジェクト

Cookie インスタンスは、さまざまなクッキーの標準で規定されている標準的なクッキー属性とおおまかに対応する Python 属性をもっています。しかしデフォルト値を決める複雑なやり方が存在しており、また max-age および expires クッキー属性は同じ値をもつことになっているので、また RFC 2109 [https://datatracker.ietf.org/doc/html/rfc2109.html] クッキーは http.cookiejar によって version 1 から version 0 (Netscape) クッキーへ 'ダウングレード' される場合があるため、この対応は 1 対 1 ではありません。

CookiePolicy メソッド内でのごくわずかな例外を除けば、これらの属性に代入する必要はないはずです。このクラスは内部の一貫性を保つようにはしていないため、代入するのは自分のやっていることを理解している場合のみにしてください。

Cookie.version

整数または None 。 Netscape クッキーはバージョン 0 であり、 RFC 2965 [https://datatracker.ietf.org/doc/html/rfc2965.html] および RFC 2109 [https://datatracker.ietf.org/doc/html/rfc2109.html] クッキーはバージョン 1 です。しかし、 http.cookiejar は RFC 2109 クッキーを Netscape クッキー (version が 0) に 'ダウングレード' する場合がある事に注意して下さい。

Cookie.name

クッキーの名前 (文字列)。

Cookie.value

クッキーの値 (文字列)、あるいは None 。

Cookie.port

ポートあるいはポートの集合をあらわす文字列 (例: '80' または '80,8080')、あるいは None 。

Cookie.domain

Cookie domain (a string).

Cookie.path

クッキーのパス名 (文字列、例: '/acme/rocket_launchers')。

Cookie.secure

そのクッキーを返せるのがセキュアな接続のみならば True を返します。

Cookie.expires

クッキーの期限が切れる日時をあわらす整数 (エポックから経過した秒数)、あるいは None 。 is_expired() も参照してください。

Cookie.discard

これがセッションクッキーであれば True を返します。

Cookie.comment

このクッキーの働きを説明する、サーバからのコメント文字列、あるいは None 。

Cookie.comment_url

このクッキーの働きを説明する、サーバからのコメントのリンク URL、あるいは None 。

Cookie.rfc2109

RFC 2109 [https://datatracker.ietf.org/doc/html/rfc2109.html] クッキー (即ち Set-Cookie ヘッダにあり、かつクッキー属性 Version の値が 1 のクッキー) の場合、 True を返します。 http.cookiejar が RFC 2109クッキーを Netscape クッキー (version が 0) に 'ダウングレード' する場合があるので、この属性が提供されています。

Cookie.port_specified

サーバがポート、あるいはポートの集合を (Set-Cookie / Set-Cookie2 ヘッダ内で) 明示的に指定していれば True を返します。

Cookie.domain_specified

サーバにより明示的にドメインが指定されていれば True を返します。

Cookie.domain_initial_dot

サーバが明示的に指定したドメインがドット ('.') で始まっていれば True を返します。

クッキーは、オプションとして標準的でないクッキー属性を持つこともできます。これらは以下のメソッドでアクセスできます:

Cookie.has_nonstandard_attr(name)

そのクッキーが指定された名前のクッキー属性をもっている場合には True を返します。

Cookie.get_nonstandard_attr(name, default=None)

クッキーが指定された名前のクッキー属性をもっていれば、その値を返します。そうでない場合は default を返します。

Cookie.set_nonstandard_attr(name, value)

指定された名前のクッキー属性を設定します。

Cookie クラスは以下のメソッドも定義しています:

Cookie.is_expired(now=None)

サーバが要求するクッキーの有効期限を過ぎていれば True を返します。 now が (エポックからの経過秒で) 指定されているときは、特定の時刻で期限切れかどうかを判定します。

使用例

はじめに、もっとも一般的な http.cookiejar の使用例をあげます:

import http.cookiejar, urllib.request
cj = http.cookiejar.CookieJar()
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")

以下の例では、URL を開く際に Netscape や Mozilla または Lynx のクッキーを使う方法を示しています (クッキーファイルの位置は Unix/Netscape の慣例にしたがうものと仮定しています):

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/")

つぎの例は DefaultCookiePolicy の使用例です。 RFC 2965 [https://datatracker.ietf.org/doc/html/rfc2965.html] クッキーをオンにし、Netscape クッキーを設定したり返したりするドメインに対してより厳密な規則を適用します。そしていくつかのドメインからクッキーを設定あるいは返還するのをブロックしています:

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/")

xmlrpc --- XMLRPC server and client modules

XML-RPC は HTTP 経由の XML を使って遠隔手続き呼び出し (Remote Procedure Call) を実現する方法です。XML-RPC を使うと、クライアントはリモートサーバー (サーバーは URI で名前付けられます) 上のメソッドを引数付きで呼び出して、構造化されたデータを受け取る事ができます。

xmlrpc パッケージは XML-RPC のサーバーとクライアントを実装したモジュールを持っています。モジュール一覧:

xmlrpc.client

xmlrpc.server

xmlrpc.client --- XML-RPC client access

ソースコード: Lib/xmlrpc/client.py [https://github.com/python/cpython/tree/3.12/Lib/xmlrpc/client.py]

XML-RPCはXMLを利用した遠隔手続き呼び出し(Remote Procedure Call)の一種で、HTTP(S)をトランスポートとして使用します。XML- RPCでは、クライアントはリモートサーバ(URIで指定されたサーバ)上のメソッドをパラメータを指定して呼び出し、構造化されたデータを取得します。このモジュールは、XML-RPCクライアントの開発をサポートしており、Pythonオブジェクトに適合する転送用XMLの変換の全てを行います。

警告

xmlrpc.client モジュールは悪意を持って構築されたデータに対して安全ではありません。信頼できないデータや認証されていないデータを解析する必要がある場合は、XML の脆弱性 を参照してください。

バージョン 3.5 で変更: HTTPS URI の場合、 xmlrpc.client は必要な証明書検証とホスト名チェックを全てデフォルトで行います。

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. See WebAssemblyプラットフォーム for more information.

class xmlrpc.client.ServerProxy(uri, transport=None, encoding=None, verbose=False, allow_none=False, use_datetime=False, use_builtin_types=False, *, headers=(), context=None)

ServerProxy は、リモートのXML-RPCサーバとの通信を管理するオブジェクトです。最初のパラメータはURI(Uniform Resource Indicator)で、通常はサーバのURLを指定します。2番目のパラメータにはトランスポート・ファクトリを指定する事ができます。トランスポート・ファクトリを省略した場合、URLが https: ならモジュール内部の SafeTransport インスタンスを使用し、それ以外の場合にはモジュール内部の Transport インスタンスを使用します。オプションの 3 番目の引数はエンコード方法で、デフォルトでは UTF-8 です。オプションの 4 番目の引数はデバッグフラグです。

The following parameters govern the use of the returned proxy instance. If allow_none is true, the Python constant None will be translated into XML; the default behaviour is for None to raise a 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 [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 datetime.datetime objects and binary data to be presented as bytes objects; this flag is false by default. datetime.datetime, bytes and 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. [('Header-Name', 'value')]). 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 引数が追加されました。

HTTP及びHTTPS通信の両方で、 http://user:pass@host:port/path のようなHTTP基本認証のための拡張URL構文をサポートしています。 user:pass はbase64でエンコードしてHTTPの'Authorization 'ヘッダとなり、XML-RPCメソッド呼び出し時に接続処理の一部としてリモートサーバに送信されます。リモートサーバが基本認証を要求する場合のみ、この機能を利用する必要があります。HTTPS URL が与えられたなら、 context は ssl.SSLContext にでき、基底のHTTP接続のSSL設定を設定します。

生成されるインスタンスはリモートサーバへのプロクシオブジェクトで、RPC呼び出しを行う為のメソッドを持ちます。リモートサーバがイントロスペクション APIをサポートしている場合は、リモートサーバのサポートするメソッドを検索 (サービス検索)やサーバのメタデータの取得なども行えます。

以下の型をXMLに変換(XMLを通じてマーシャルする)する事ができます (特別な指定がない限り、逆変換でも同じ型として変換されます):

XML-RPC の型

Python の型

boolean

bool

int, i1, i2, i4, i8 または biginteger

int in range from -2147483648 to 2147483647. Values get the <int> tag.

double または float

float. Values get the <double> tag.

string

str

array

適合する要素を持つ list または tuple。array は list として返します。

struct

dict 。キーは文字列のみ。全ての値は変換可能でなくてはならない。ユーザー定義型を渡すこともできます。 __dict__ の属性のみ転送されます。

dateTime.iso8601

DateTime または datetime.datetime。返される型は use_builtin_types および use_datetime の値に依ります。

base64

Binary、 bytes または bytearray。返される型は use_builtin_types フラグの値に依ります。

nil

None 定数。 allow_none が真の場合にのみ渡すことが出来ます。

bigdecimal

decimal.Decimal. Returned type only.

上記のXML-RPCでサポートする全データ型を使用することができます。メソッド呼び出し時、XML- RPCサーバエラーが発生すると Fault インスタンスを送出し、HTTP/HTTPSトランスポート層でエラーが発生した場合には ProtocolError を送出します。 Error をベースとする Fault と ProtocolError の両方が発生します。現在のところxmlrpclibでは組み込み型のサブクラスのインスタンスをマーシャルすることはできません。

文字列を渡す場合、 <, >, & などのXMLで特殊な意味を持つ文字は自動的にエスケープされます。しかし、ASCII値0〜31の制御文字(もちろん、タブ'TAB',改行'LF',リターン'CR'は除く)などのXMLで使用することのできない文字を使用することはできず、使用するとそのXML-RPCリクエストはwell-formedなXMLとはなりません。そのようなバイト列を渡す必要がある場合は、 bytes, bytearray クラスまたは後述の Binary ラッパークラスを使用してください。

Server は、後方互換性の為に ServerProxy の別名として残されています。新しいコードでは ServerProxy を使用してください。

バージョン 3.5 で変更: context 引数が追加されました。

バージョン 3.6 で変更: Added support of type tags with prefixes (e.g. ex:nil). Added support of unmarshalling additional types used by Apache XML-RPC implementation for numerics: i1, i2, i8, biginteger, float and bigdecimal. See https://ws.apache.org/xmlrpc/types.html for a description.

参考

XML-RPC HOWTO [https://tldp.org/HOWTO/XML-RPC-HOWTO/index.html]

数種類のプログラミング言語で記述された XML-RPCの操作とクライアントソフトウェアの素晴らしい説明が掲載されています。 XML- RPCクライアントの開発者が知っておくべきことがほとんど全て記載されています。

XML-RPC Introspection [https://xmlrpc-c.sourceforge.net/introspection.html]

インストロペクションをサポートする、 XML-RPC プロトコルの拡張を解説しています。

XML-RPC Specification [http://xmlrpc.scripting.com/spec.html]

公式の仕様

ServerProxy オブジェクト

ServerProxy インスタンスの各メソッドはそれぞれXML-RPCサーバの遠隔手続き呼び出しに対応しており、メソッドが呼び出されると名前と引数をシグネチャとしてRPCを実行します(同じ名前のメソッドでも、異なる引数シグネチャによってオーバロードされます)。RPC実行後、変換された値を返すか、または Fault オブジェクトもしくは ProtocolError オブジェクトでエラーを通知します。

予約属性 system から、XMLイントロスペクションAPIの一般的なメソッドを利用する事ができます:

ServerProxy.system.listMethods()

XML-RPCサーバがサポートするメソッド名(system以外)を格納する文字列のリストを返します。

ServerProxy.system.methodSignature(name)

XML-RPCサーバで実装されているメソッドの名前を指定し、利用可能なシグネチャの配列を取得します。シグネチャは型のリストで、先頭の型は戻り値の型を示し、以降はパラメータの型を示します。

XML-RPCでは複数のシグネチャ(オーバロード)を使用することができるので、単独のシグネチャではなく、シグネチャのリストを返します。

シグネチャは、メソッドが使用する最上位のパラメータにのみ適用されます。例えばあるメソッドのパラメータが構造体の配列で戻り値が文字列の場合、シグネチャは単に"string, array" となります。パラメータが三つの整数で戻り値が文字列の場合は"string, int, int, int"となります。

メソッドにシグネチャが定義されていない場合、配列以外の値が返ります。 Pythonでは、この値はlist以外の値となります。

ServerProxy.system.methodHelp(name)

XML-RPCサーバで実装されているメソッドの名前を指定し、そのメソッドを解説する文書文字列を取得します。文書文字列を取得できない場合は空文字列を返します。文書文字列にはHTMLマークアップが含まれます。

バージョン 3.5 で変更: Instances of ServerProxy support the context manager protocol for closing the underlying transport.

以下は、動作する例です。サーバ側のコード:

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()

上記のサーバーに対するクライアントコード:

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

DateTime オブジェクト

class xmlrpc.client.DateTime

このクラスは、エポックからの秒数、タプルで表現された時刻、ISO 8601形式の時間/日付文字列、 datetime.datetime, のインスタンスのいずれかで初期化することができます。このクラスには以下のメソッドがあり、主にコードをマーシャル/アンマーシャルするための内部処理を行います:

decode(string)

文字列をインスタンスの新しい時間を示す値として指定します。

encode(out)

出力ストリームオブジェクト out に、XML-RPCエンコーディングの DateTime 値を出力します。

It also supports certain of Python's built-in operators through rich comparison and __repr__() methods.

以下は、動作する例です。サーバ側のコード:

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()

上記のサーバーに対するクライアントコード:

import xmlrpc.client
import datetime

proxy = xmlrpc.client.ServerProxy("http://localhost:8000/")

today = proxy.today()
# convert the ISO8601 string to a datetime object
converted = datetime.datetime.strptime(today.value, "%Y%m%dT%H:%M:%S")
print("Today: %s" % converted.strftime("%d.%m.%Y, %H:%M"))

Binary オブジェクト

class xmlrpc.client.Binary

このクラスは、バイト列データ(NULを含む)で初期化することができます。 Binary の内容は、属性で参照します:

data

Binary インスタンスがカプセル化しているバイナリデータ。このデータは bytes オブジェクトです。

Binary オブジェクトは以下のメソッドを持ち、主に内部的にマーシャル/アンマーシャル時に使用されます:

decode(bytes)

指定されたbase64 bytes オブジェクトをデコードし、インスタンスのデータとします。

encode(out)

バイナリ値をbase64でエンコードし、出力ストリームオブジェクト out に出力します。

エンコードされたデータは、 RFC 2045 section 6.8 [https://datatracker.ietf.org/doc/html/rfc2045.html#section-6.8] にある通り、76文字ごとに改行されます。これは、XMC-RPC仕様が作成された時のデ・ファクト・スタンダードのbase64です。

It also supports certain of Python's built-in operators through __eq__() and __ne__() methods.

バイナリオブジェクトの使用例です。 XML-RPCごしに画像を転送します。

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()

クライアントは画像を取得して、ファイルに保存します。

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)

Fault オブジェクト

class xmlrpc.client.Fault

Fault オブジェクトは、XML-RPCのfaultタグの内容をカプセル化しており、以下の属性を持ちます:

faultCode

失敗のタイプを示す整数。

faultString

失敗の診断メッセージを含む文字列。

以下のサンプルでは、複素数型のオブジェクトを返そうとして、故意に Fault を起こしています。

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()

上記のサーバーに対するクライアントコード:

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)

ProtocolError オブジェクト

class xmlrpc.client.ProtocolError

ProtocolError オブジェクトはトランスポート層で発生したエラー(URI で指定したサーバが見つからなかった場合に発生する404 'not found'など)の内容を示し、以下の属性を持ちます:

url

エラーの原因となったURIまたはURL。

errcode

エラーコード。

errmsg

エラーメッセージまたは診断文字列。

headers

エラーの原因となったHTTP/HTTPSリクエストを含む辞書。

次の例では、不適切な URI を利用して、故意に ProtocolError を発生させています:

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)

MultiCall オブジェクト

MultiCall オブジェクトは遠隔のサーバに対する複数の呼び出しをひとつのリクエストにカプセル化する方法を提供します [1]。

class xmlrpc.client.MultiCall(server)

巨大な (boxcar) メソッド呼び出しに使えるオブジェクトを作成します。 server には最終的に呼び出しを行う対象を指定します。作成した MultiCall オブジェクトを使って呼び出しを行うと、即座に None を返し、呼び出したい手続き名とパラメタを MultiCall オブジェクトに保存するだけに留まります。オブジェクト自体を呼び出すと、それまでに保存しておいたすべての呼び出しを単一の system.multicall リクエストの形で伝送します。呼び出し結果は ジェネレータ になります。このジェネレータにわたってイテレーションを行うと、個々の呼び出し結果を返します。

以下は、このクラスの使用例です。サーバ側のコード:

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()

上記のサーバーに対するクライアントコード:

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

補助関数

xmlrpc.client.dumps(params, methodname=None, methodresponse=None, encoding=None, allow_none=False)

params を XML-RPC リクエストの形式に変換します。 methodresponse が真の場合、XML-RPC レスポンスの形式に変換します。 params に指定できるのは、引数からなるタプルか Fault 例外クラスのインスタンスです。 methodresponse が真の場合、単一の値だけを返します。従って、 params の長さも 1 でなければなりません。 encoding を指定した場合、生成される XML のエンコード方式になります。デフォルトは UTF-8 です。 Python の None は標準の XML-RPC には利用できません。 None を使えるようにするには、 allow_none を真にして、拡張機能つきにしてください。

xmlrpc.client.loads(data, use_datetime=False, use_builtin_types=False)

XML-RPC リクエストまたはレスポンスを (params, methodname) の形式をとる Python オブジェクトにします。 params は引数のタプルです。 methodname は文字列で、パケット中にメソッド名がない場合には None になります。例外条件を示す XML-RPC パケットの場合には、 Fault 例外を送出します。 use_builtin_types フラグは datetime.datetime のオブジェクトとして日付/時刻を、 bytes のオブジェクトとしてバイナリデータを表現する時に使用し、デフォルトでは false に設定されています。

非推奨となった use_datetime フラグは use_builtin_types に似ていますが date/time 値にのみ適用されます。

バージョン 3.3 で変更: use_builtin_types フラグが追加されました。

クライアントのサンプル

# 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)

XML-RPC サーバに HTTP プロキシを経由して接続する場合、カスタムトランスポートを定義する必要があります。以下に例を示します:

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

クライアントとサーバーの利用例

SimpleXMLRPCServer の例 を参照してください。

脚注

[1]

このアプローチは a discussion on xmlrpc.com [https://web.archive.org/web/20060624230303/http://www.xmlrpc.com/discuss/msgReader$1208?mode=topic] にて最初に著されました。

xmlrpc.server --- Basic XML-RPC servers

ソースコード: Lib/xmlrpc/server.py [https://github.com/python/cpython/tree/3.12/Lib/xmlrpc/server.py]

xmlrpc.server モジュールはPythonで記述された基本的なXML-RPC サーバーフレームワークを提供します。サーバーはスタンドアロンであるか、 SimpleXMLRPCServer を使うか、 CGIXMLRPCRequestHandler を使って CGI 環境に組み込まれるかの、いずれかです。

警告

xmlrpc.server モジュールは悪意を持って構築されたデータに対して安全ではありません。信頼できないデータや認証されていないデータを解析する必要がある場合は、 XML の脆弱性 を参照してください。

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. See WebAssemblyプラットフォーム for more information.

class xmlrpc.server.SimpleXMLRPCServer(addr, requestHandler=SimpleXMLRPCRequestHandler, logRequests=True, allow_none=False, encoding=None, bind_and_activate=True, use_builtin_types=False)

サーバーインスタンスを新たに作成します。このクラスは XML-RPC プロトコルで呼ばれる関数の登録のためのメソッドを提供します。引数 requestHandler にはリクエストハンドラーインスタンスのファクトリーを設定します。デフォルトは SimpleXMLRPCRequestHandler です。引数 addr と requestHandler は socketserver.TCPServer のコンストラクターに渡されます。 logRequests が真の場合 (デフォルト)、 リクエストはログに記録されます。この引数を偽にするとはログは記録されません。引数 allow_none と encoding は xmlrpc.client に渡され、サーバーが返す XML-RPC 応答を制御します。 bind_and_activate 引数はコンストラクタが直ちに server_bind() と server_activate() を呼ぶかどうかを制御します。デフォルトでは真です。この引数に False を設定することで、アドレスを束縛する前に allow_reuse_address クラス変数を操作することが出来ます。 use_builtin_types 引数は loads() 関数に渡されます。この引数は日付/時刻の値やバイナリデータを受け取ったときにどの型が処理されるかを制御します。デフォルトでは偽です。

バージョン 3.3 で変更: use_builtin_types フラグが追加されました。

class xmlrpc.server.CGIXMLRPCRequestHandler(allow_none=False, encoding=None, use_builtin_types=False)

CGI 環境における XML-RPC リクエストハンドラーを新たに作成します。引数 allow_none と encoding は xmlrpc.client に渡され、サーバーが返す XML-RPC 応答を制御します。 use_builtin_types 引数は loads() 関数に渡されます。この引数は日付/時刻の値やバイナリデータを受け取ったときにどの型が処理されるかを制御します。デフォルトは偽です。

バージョン 3.3 で変更: use_builtin_types フラグが追加されました。

class xmlrpc.server.SimpleXMLRPCRequestHandler

リクエストハンドラーインスタンスを新たに作成します。このリクエストハンドラーは POST リクエストをサポートし、 SimpleXMLRPCServer コンストラクターの引数 logRequests に従ってログ出力を行います。

SimpleXMLRPCServer オブジェクト

SimpleXMLRPCServer クラスは socketserver.TCPServer のサブクラスで、基本的なスタンドアロンの XML-RPC サーバーを作成する手段を提供します。

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 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, function.__name__ will be used.

バージョン 3.7 で変更: register_function() can be used as a decorator.

SimpleXMLRPCServer.register_instance(instance, allow_dotted_names=False)

オブジェクトを登録します。オブジェクトは register_function() を使用して登録されていないメソッド名を公開するのに使われます。 instance に _dispatch() メソッドがあった場合、リクエストされたメソッド名と引数で _dispatch() を呼び出します。 API は def _dispatch(self, method, params) (params 可変引数リストではないことに注意) です。タスクを実行するのに下層の関数を呼び出す場合、その関数は func(*params) のように引数リストを展開して呼び出されます。 _dispatch() の返り値は結果としてクライアントに返されます。 instance に _dispatch() メソッドがない場合、リクエストされたメソッド名にマッチする属性を検索します。

オプション引数 allow_dotted_names が真でインスタンスに _dispatch() メソッドがない場合、リクエストされたメソッド名がピリオドを含むなら、メソッド名の各要素が個々に検索され、簡単な階層的検索が行われます。その検索で発見された値をリクエストの引数で呼び出し、クライアントに返り値を返します。

警告

allow_dotted_names オプションを有効にすると、侵入者はあなたのモジュールのグローバル変数にアクセスすることができ、あなたのマシンで任意のコードを実行できる可能性があります。このオプションは閉じた安全なネットワークでのみお使い下さい。

SimpleXMLRPCServer.register_introspection_functions()

XML-RPC のイントロスペクション関数、 system.listMethods 、 system.methodHelp 、 system.methodSignature を登録します。

SimpleXMLRPCServer.register_multicall_functions()

XML-RPC における複数の要求を処理する関数 system.multicall を登録します。

SimpleXMLRPCRequestHandler.rpc_paths

この属性値はXML-RPCリクエストを受け付けるURLの有効なパス部分をリストするタプルでなければなりません。これ以外のパスへのリクエストは404「そのようなページはありません」 HTTPエラーになります。このタプルが空の場合は全てのパスが有効であると見なされます。デフォルト値は ('/', '/RPC2') です。

SimpleXMLRPCServer の例

サーバーのコード:

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()

以下のクライアントコードは上のサーバーで使えるようになったメソッドを呼び出します:

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())

register_function() can also be used as a decorator. The previous server example can register functions in a decorator way:

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()

Lib/xmlrpc/server.py モジュール内にある以下の例はドット付名前を許容し複数呼び出し関数を登録するサーバです。

警告

allow_dotted_names オプションを有効にすると、侵入者はあなたのモジュールのグローバル変数にアクセスすることができ、あなたのマシンで任意のコードを実行できる可能性があります。この例は閉じた安全なネットワークでのみお使い下さい。

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)

この ExampleService デモはコマンドラインから起動することができます。

python -m xmlrpc.server

上記のサーバとやりとりするクライアントは Lib/xmlrpc/client.py にあります:

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)

デモ XMLRPC サーバとやりとりするクライアントは以下のように呼び出します:

python -m xmlrpc.client

CGIXMLRPCRequestHandler

CGIXMLRPCRequestHandler クラスは、Python の CGI スクリプトに送られた XML-RPC リクエストを処理するときに使用できます。

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 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, function.__name__ will be used.

バージョン 3.7 で変更: register_function() can be used as a decorator.

CGIXMLRPCRequestHandler.register_instance(instance)

オブジェクトを登録します。オブジェクトは register_function() を使用して登録されていないメソッド名を公開するのに使われます。 instance に _dispatch() メソッドがあった場合、リクエストされたメソッド名と引数で _dispatch() を呼び出します。返り値は結果としてクライアントに返されます。 instance に _dispatch() メソッドがなかった場合、リクエストされたメソッド名にマッチする属性を検索します。リクエストされたメソッド名がピリオドを含む場合、モジュール名の各要素が個々に検索され、簡単な階層的検索が実行されます。その検索で発見された値をリクエストの引数で呼び出し、クライアントに返り値を返します。

CGIXMLRPCRequestHandler.register_introspection_functions()

XML-RPC のイントロスペクション関数、 system.listMethods 、 system.methodHelp 、 system.methodSignature を登録します。

CGIXMLRPCRequestHandler.register_multicall_functions()

XML-RPC マルチコール関数 system.multicall を登録します。

CGIXMLRPCRequestHandler.handle_request(request_text=None)

XML-RPC リクエストを処理します。 与えられた場合、 request_text はHTTP サーバが提供する POST データでなければなりません。そうでない場合、標準入力の内容が使われます。

以下はプログラム例です:

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()

XMLRPC サーバの文書化

これらのクラスは HTTP GET 要求への応答内で HTML 文書となるよう上記クラスを拡張します。サーバは独立していても CGI 環境に埋め込まれていてもかまいません。前者では DocXMLRPCServer を、後者では DocCGIXMLRPCRequestHandler を使用します。

class xmlrpc.server.DocXMLRPCServer(addr, requestHandler=DocXMLRPCRequestHandler, logRequests=True, allow_none=False, encoding=None, bind_and_activate=True, use_builtin_types=True)

サーバ・インスタンスを新たに生成します。全ての引数の意味は SimpleXMLRPCServer のものと同じですが、 requestHandler のデフォルトは DocXMLRPCRequestHandler になっています。

バージョン 3.3 で変更: use_builtin_types フラグが追加されました。

class xmlrpc.server.DocCGIXMLRPCRequestHandler

CGI環境で XMR-RPC リクエストを処理するインスタンスを新たに生成します。

class xmlrpc.server.DocXMLRPCRequestHandler

リクエスト・ハンドラのインスタンスを新たに生成します。このリクエスト・ハンドラは XML-RPC POST 要求とドキュメントの GET 要求をサポートし、 DocXMLRPCServer コンストラクタに与えられた引数 logRequests を優先するためにロギングを変更します。

DocXMLRPCServer オブジェクト

DocXMLRPCServer は SimpleXMLRPCServer の派生クラスで、自己文書化するスタンドアローン XML-RPC サーバの作成手段を提供します。 HTTP POST リクエストは XML-RPC メソッドの呼び出しとして処理されます。 HTTP GET リクエストは pydoc スタイルの HTML 文書の生成に処理されます。これによりサーバは自身の web ベースの文書を提供できます。

DocXMLRPCServer.set_server_title(server_title)

生成する HTML 文書で使用されるタイトルを設定します。このタイトルは HTML の title 要素内で使われます。

DocXMLRPCServer.set_server_name(server_name)

生成する HTML 文書内で使用される名前を設定します。この名前は生成した文書冒頭の h1 要素内で使われます。

DocXMLRPCServer.set_server_documentation(server_documentation)

生成する HTML 文書内で使用される説明を設定します。この説明は文書中のサーバ名の下にパラグラフとして出力されます。

DocCGIXMLRPCRequestHandler

DocCGIXMLRPCRequestHandler は CGIXMLRPCRequestHandler の派生クラスで、自己文書化する XML-RPC CGI スクリプトの作成手段を提供します。 HTTP POST リクエストは XML-RCP メソッドの呼び出しとして処理されます。 HTTP GET リクエストは pydoc スタイルの HTML 文書の生成に処理されます。これによりサーバは自身の web ベースの文書を提供できます。

DocCGIXMLRPCRequestHandler.set_server_title(server_title)

生成する HTML 文書で使用されるタイトルを設定します。このタイトルは HTML の title 要素内で使われます。

DocCGIXMLRPCRequestHandler.set_server_name(server_name)

生成する HTML 文書内で使用される名前を設定します。この名前は生成した文書冒頭の h1 要素内で使われます。

DocCGIXMLRPCRequestHandler.set_server_documentation(server_documentation)

生成する HTML 文書内で使用される説明を設定します。この説明は文書中のサーバ名の下にパラグラフとして出力されます。

ipaddress --- IPv4/IPv6 manipulation library

ソースコード: Lib/ipaddress.py [https://github.com/python/cpython/tree/3.12/Lib/ipaddress.py]

ipaddress は IPv4 と IPv6 アドレスとネットワークの生成・変更・操作を提供しています。

このモジュールの関数やクラスを使うと、IPアドレスに関する様々なタスク、例えば2つのホストが同じサブネットに属しているかどうかをチェックしたり、特定のサブネット内の全てのホストをイテレートしたり、文字列が正しい IP アドレスかネットワークを定義しているかどうかをチェックするなどを簡単に実現することができます。

これはモジュールの完全な API リファレンスです。概要や紹介は ipaddressモジュールの紹介 を参照してください。

Added in version 3.3.

便利なファクトリ関数

ipaddress モジュールは簡単に IP アドレス、ネットワーク、インターフェースを生成するためのファクトリ関数を提供しています:

ipaddress.ip_address(address)

引数に渡された IP address に応じて、 IPv4Address か IPv6Address のオブジェクトを返します。 IPv4 か IPv6 のアドレスを受け取ります; 2**32 より小さい整数はデフォルトでは IPv4 アドレスだと判断されます。 address が正しい IPv4, IPv6 アドレスを表現していない場合は ValueError を発生させます。

>>> ipaddress.ip_address('192.168.0.1')
IPv4Address('192.168.0.1')
>>> ipaddress.ip_address('2001:db8::')
IPv6Address('2001:db8::')

ipaddress.ip_network(address, strict=True)

引数に渡された IP address に応じて、 IPv4Network か IPv6Network のオブジェクトを返します。 address は IP ネットワークを示す文字列あるいは整数です。 IPv4 か IPv6 のネットワークを受け取ります; 2**32 より小さい整数はデフォルトでは IPv4 アドレスだと判断されます。 strict は IPv4Network か IPv6Network のコンストラクタに渡されます。 address が正しい IPv4, IPv6 アドレスを表現していない場合や、ネットワークの host bit がセットされていた場合は ValueError を発生させます。

>>> ipaddress.ip_network('192.168.0.0/28')
IPv4Network('192.168.0.0/28')

ipaddress.ip_interface(address)

引数に渡された IP address に応じて、 IPv4Interface か IPv6Interface のオブジェクトを返します。 address は IP ネットワークを示す文字列あるいは整数です。 IPv4 か IPv6 のネットワークを受け取ります; 2**32 より小さい整数はデフォルトでは IPv4 アドレスだと判断されます。 address が正しい IPv4, IPv6 アドレスを表現していない場合は ValueError を発生させます。

これらの便利関数を利用するデメリットとして、IPv4 と IPv6 両方のフォーマットを扱う必要性があるために、どちらを期待されていたのかを知ることができず、エラーメッセージが最小限の情報しか提供できないことです。利用したいバージョンの特定のコンストラクタを直接呼ぶことで、より詳細なエラーレポートを得ることができます。

IP アドレス

Address オブジェクト

IPv4Address と IPv6Address オブジェクトは多くの共通した属性を持っています。両方の IP バージョンを扱うコードを書きやすくするために、IPv6 アドレスでしか意味が無いいくつかの属性も IPv4Address オブジェクトに実装されています。アドレスオブジェクトは hashable なので、辞書のキーとして利用できます。

class ipaddress.IPv4Address(address)

IPv4 アドレスを構築する。 address が正しい IPv4 アドレスでない場合、 AddressValueError を発生させます。

以下のものが正しい IPv4 アドレスを構築します:

A string in decimal-dot notation, consisting of four decimal integers in the inclusive range 0--255, separated by dots (e.g. 192.168.0.1). Each integer represents an octet (byte) in the address. Leading zeroes are not tolerated to prevent confusion with octal notation.

32bit に収まる整数。

大きさ4の bytes オブジェクトに (最上位オクテットが最初になるように) パックされた整数。

>>> 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')

バージョン 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 inet_pton().

version

適切なバージョン番号: IPv4 なら 4, IPv6 なら 6.

max_prefixlen

このバージョンのアドレスを表現するのに必要なビット数: IPv4 なら 32, IPv6 なら 128.

prefix は、アドレスがネットワークに含まれるかどうかを決定するために比較する、アドレスの先頭ビット数を定義します。

compressed

exploded

ドットと10進数を使った表現の文字列。この表現には先頭の 0 は含まれません。

IPv4 はアドレスの 0 オクテットを省略する記法を定義していないので、IPv4 アドレスにおいてこれらの2つの属性は常に str(addr) と等しくなります。これらの属性を用意することで、IPv4 と IPv6 アドレス両方を扱う、表示用コードが書きやすくなります。

packed

このアドレスのバイナリ表現 - 適切な長さをもった bytes オブジェクト(最上位オクテットが先頭)。 IPv4 では 4 byte で、 IPv6 では 16 byte。

reverse_pointer

The name of the reverse DNS PTR record for the IP address, e.g.:

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

This is the name that could be used for performing a PTR lookup, not the resolved hostname itself.

Added in version 3.5.

is_multicast

アドレスがマルチキャスト用に予約されている場合は True 。 RFC 3171 [https://datatracker.ietf.org/doc/html/rfc3171.html] (IPv4) か RFC 2373 [https://datatracker.ietf.org/doc/html/rfc2373.html] (IPv6) を参照。

is_private

True if the address is defined as not globally reachable by iana-ipv4-special-registry [https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml] (for IPv4) or iana-ipv6-special-registry [https://www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-special-registry.xhtml] (for IPv6) with the following exceptions:

is_private is False for the shared address space (100.64.0.0/10)

For IPv4-mapped IPv6-addresses the is_private value is determined by the semantics of the underlying IPv4 addresses and the following condition holds (see IPv6Address.ipv4_mapped):

address.is_private == address.ipv4_mapped.is_private

is_private has value opposite to is_global, except for the shared address space (100.64.0.0/10 range) where they are both False.

バージョン 3.12.4 で変更: Fixed some false positives and false negatives.

192.0.0.0/24 is considered private with the exception of 192.0.0.9/32 and 192.0.0.10/32 (previously: only the 192.0.0.0/29 sub-range was considered private).

64:ff9b:1::/48 is considered private.

2002::/16 is considered private.

There are exceptions within 2001::/23 (otherwise considered private): 2001:1::1/128, 2001:1::2/128, 2001:3::/32, 2001:4:112::/48, 2001:20::/28, 2001:30::/28. The exceptions are not considered private.

is_global

True if the address is defined as globally reachable by iana-ipv4-special-registry [https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml] (for IPv4) or iana-ipv6-special-registry [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 is_private value is determined by the semantics of the underlying IPv4 addresses and the following condition holds (see IPv6Address.ipv4_mapped):

address.is_global == address.ipv4_mapped.is_global

is_global has value opposite to is_private, except for the shared address space (100.64.0.0/10 range) where they are both False.

Added in version 3.4.

バージョン 3.12.4 で変更: Fixed some false positives and false negatives, see is_private for details.

is_unspecified

アドレスが未定義の時に True. RFC 5735 [https://datatracker.ietf.org/doc/html/rfc5735.html] (IPv4) か RFC 2373 [https://datatracker.ietf.org/doc/html/rfc2373.html] (IPv6) を参照。

is_reserved

IETF で予約されているアドレスの場合に True。

is_loopback

ループバックアドレスである場合に True. RFC 3330 [https://datatracker.ietf.org/doc/html/rfc3330.html] (IPv4) か RFC 2373 [https://datatracker.ietf.org/doc/html/rfc2373.html] (IPv6) を参照。

is_link_local

アドレスがリンクローカル用に予約されいている場合に True. RFC 3927 [https://datatracker.ietf.org/doc/html/rfc3927.html] を参照。

IPv4Address.__format__(fmt)

Returns a string representation of the IP address, controlled by an explicit format string. fmt can be one of the following: 's', the default option, equivalent to str(), 'b' for a zero-padded binary string, 'X' or 'x' for an uppercase or lowercase hexadecimal representation, or 'n', which is equivalent to 'b' for IPv4 addresses and 'x' for IPv6. For binary and hexadecimal representations, the form specifier '#' and the grouping option '_' are available. __format__ is used by format, str.format and f-strings.

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

Added in version 3.9.

class ipaddress.IPv6Address(address)

IPv6 アドレスを構築する。 address が正しい IPv6 アドレスでない場合、 AddressValueError を発生させます。

以下のものが正しい IPv6 アドレスを構築します:

4桁の16進数からなるグループ8個で構成された文字列。各グループは16bitを表現している。グループはコロンで区切られる。これは exploded (長い) 記法を表す。文字列は compressed (省略) 記法でも良い。詳細は RFC 4291 [https://datatracker.ietf.org/doc/html/rfc4291.html] を参照。例えば、 "0000:0000:0000:0000:0000:0abc:0007:0def" は "::abc:7:def" と省略できる。

Optionally, the string may also have a scope zone ID, expressed with a suffix %scope_id. If present, the scope ID must be non-empty, and may not contain %. See RFC 4007 [https://datatracker.ietf.org/doc/html/rfc4007.html] for details. For example, fe80::1234%1 might identify address fe80::1234 on the first link of the node.

128bit に収まる整数。

ビッグエンディアンで 16 バイトの長さの bytes オブジェクトにパックされた整数。

>>> ipaddress.IPv6Address('2001:db8::1000')
IPv6Address('2001:db8::1000')
>>> ipaddress.IPv6Address('ff02::5678%1')
IPv6Address('ff02::5678%1')

compressed

アドレス表現の短い形式で、グループ内の先頭の 0 を省略し、連続する完全に0のグループの一番長いシーケンスを1つの空グループに折りたたんだもの。

これは IPv6 アドレスに対して str(addr) が返す値と同じです。

exploded

アドレス表現の長い形式。全てのグループの先頭の0は省略されず、完全に0のグループも省略されない。

以降の属性とメソッドについては、IPv4Address クラスの対応するドキュメントを参照してください:

packed

reverse_pointer

version

max_prefixlen

is_multicast

is_private

is_global

Added in version 3.4.

is_unspecified

is_reserved

is_loopback

is_link_local

is_site_local

アドレスがサイトローカルな目的のために予約されいている場合に True. サイトローカルアドレスは RFC 3879 [https://datatracker.ietf.org/doc/html/rfc3879.html] によって廃止されている事に注意してください。アドレスが RFC 4193 [https://datatracker.ietf.org/doc/html/rfc4193.html] で定義されているユニークローカルアドレスの範囲に含まれているかどうかをテストするには、 is_private を利用してください。

ipv4_mapped

IPv4 にマップされた(::FFFF/96 で始まる)アドレスの場合、このプロパティは埋め込まれた IPv4 Address を返します。それ以外のアドレスに対しては、このプロパティは None になります。

scope_id

For scoped addresses as defined by RFC 4007 [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 None.

sixtofour

RFC 3056 [https://datatracker.ietf.org/doc/html/rfc3056.html] で定義された 6to4 (2002::/16 で始まる)アドレスの場合、このプロパティは埋め込まれた IPv4 Address を返します。それ以外のアドレスに対しては、このプロパティは None になります。

teredo

RFC 4380 [https://datatracker.ietf.org/doc/html/rfc4380.html] で定義された Teredo (2001::/32 で始まる)アドレスの場合、このプロパティは埋め込まれた (server, client) IP アドレスペアを返します。それ以外のアドレスに対しては、このプロパティは None になります。

IPv6Address.__format__(fmt)

IPv4Address の対応するメソッドのドキュメントを参照してください。

Added in version 3.9.

文字列と整数への変換

socket モジュールなどのネットワークインターフェースを利用するには、アドレスを文字列や整数に変換しなければなりません。これには組み込みの str() と int() 関数を利用します:

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

Note that IPv6 scoped addresses are converted to integers without scope zone ID.

演算子

Address オブジェクトはいくつかの演算子をサポートします。明記されない限り、演算子は互換性のあるオブジェクト間 (つまり IPv4 同士や IPv6 同士) でのみ利用できます。

比較演算子

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:

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

算術演算

アドレスオブジェクトから整数を加減算できます。いくつかの例:

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

IP ネットワーク定義

IPv4Network と IPv6Network オブジェクトは IP ネットワークの定義とインスペクトのための機構を提供します。ネットワーク定義は mask と ネットワークアドレス からなり、 mask でマスク(bitごとの AND) するとネットワークアドレスと同じになる IP アドレスの範囲を定義します。例えば、 255.255.255.0 という mask と 192.168.1.0 というネットワークアドレスからなるネットワーク定義は、 192.168.1.0 から 192.168.1.255 を含む範囲を表します。

プリフィックス, ネットマスク、ホストマスク

IP ネットワークマスクを定義する幾つかの等価な方法があります。プリフィックス /<nbits> は先頭の何bitがネットワークマスクで立っているかを示します。ネットマスク は先頭の幾つかのbitが立っている IP アドレスです。プリフィックス /24 はIPv4 ではネットマスク 255.255.255.0 と、IPv6 では ffff:ff00:: と同じになります。加えて、ネットマスク と論理が逆の ホストマスク があり、ときどき (例えば Cisco のアクセスコントロールリスト) ネットワークマスクを表すために利用されます。/24 と等しい IPv4 のホストマスクは 0.0.0.255 になります。

Network オブジェクト

address オブジェクトで実装されていた属性は全て network オブジェクトにも実装されています。 network はそれに追加で幾つかの属性を実装しています。全ての追加属性は IPv4Network と IPv6Network で共通なので、重複を避けるために IPv4Network にだけドキュメントされています。ネットワークオブジェクトは hashable なので、辞書のキーとして使用できます。

class ipaddress.IPv4Network(address, strict=True)

IPv4 ネットワーク定義を構築します。address は以下の1つです:

IPアドレスと、オプションでスラッシュ (/) で区切られたマスクを持つ文字列。IPアドレスはネットワークアドレスで、マスクは プリフィックス を意味する1つの数値か、 IPv4 アドレスの文字列表現です。マスクがIPv4アドレスのとき、非ゼロのフィールドで始まるときは ネットマスク として、ゼロのフィールドで始まるときは ホストマスク として解釈されます。ただし、すべてのフィールドが0の場合は、ネットマスク として扱われます。マスクが省略された場合、 /32 が指定されたものとします。

例えば、次の address 指定は全て等しくなります: 192.168.1.0/24, 192.168.1.0/255.255.255.0 192.168.1.0/0.0.0.255.

32bit に収まる整数。これは1つのアドレスのネットワークと等しく、ネットワークアドレスが address に、マスクが /32 になります。

4byte の bytes オブジェクトにビッグエンディアンでパックされた整数。これは整数の address と同じように解釈されます。

アドレス記述とネットマスクの2要素のタプル。アドレス記述は、文字列、32ビットの整数、4バイトのパックされた整数、 既存の IPv4Address オブジェクトのいずれかです。ネットマスクは、プレフィックス長を表す整数（例えば `` 24``）またはプレフィックスマスクを表す文字列（例えば `` 255.255.255.0``）です。

address が有効な IPv4 アドレスでない場合に AddressValueError 例外を発生させます。マスクが IPv4 アドレスに対して有効でない場合に NetmaskValueError 例外を発生させます。

strict が True の場合、与えられたアドレスのホストビットが立っていたら ValueError を発生させます。そうでない場合、ホストビットをマスクして正しいネットワークアドレスを計算します。

特に明記されない場合、他の network や address を受け取る network のメソッドは、引数の IP バージョンが self と異なる場合に TypeError を発生させます。

バージョン 3.5 で変更: address コンストラクタ引数に2要素のタプル形式を追加しました

version

max_prefixlen

IPv4Address の対応する属性のドキュメントを参照してください。

is_multicast

is_private

is_unspecified

is_reserved

is_loopback

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.

network_address

この network のネットワークアドレス。ネットワークアドレスとプリフィックス長によってユニークにネットワークが定義されます。

broadcast_address

このネットワークのブロードキャストアドレス。ブロードキャストアドレスに投げられたパケットはそのネットワーク内の全てのホストに受信されます。

hostmask

IPv4Address オブジェクトとして表現された ホストマスク。

netmask

IPv4Address オブジェクトとして表現された ネットマスク。

with_prefixlen

compressed

exploded

A string representation of the network, with the mask in prefix notation.

with_prefixlen and compressed are always the same as str(network). exploded uses the exploded form the network address.

with_netmask

A string representation of the network, with the mask in net mask notation.

with_hostmask

A string representation of the network, with the mask in host mask notation.

num_addresses

ネットワーク内のアドレスの総数

prefixlen

ネットワークプレフィックスのビット長。

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.

>>> 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')]

overlaps(other)

True if this network is partly or wholly contained in other or other is wholly contained in this network.

address_exclude(network)

Computes the network definitions resulting from removing the given network from this one. Returns an iterator of network objects. Raises ValueError if network is not completely contained in this network.

>>> 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')]

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.

>>> 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')]

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.

>>> 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')

subnet_of(other)

このネットワークが other のサブネットの場合に True を返します。

>>> a = ip_network('192.168.1.0/24')
>>> b = ip_network('192.168.1.128/30')
>>> b.subnet_of(a)
True

Added in version 3.7.

supernet_of(other)

このネットワークが other のスーパーネットの場合に True を返します。

>>> a = ip_network('192.168.1.0/24')
>>> b = ip_network('192.168.1.128/30')
>>> a.supernet_of(b)
True

Added in version 3.7.

compare_networks(other)

このネットワークを other と比較します。比較ではネットワークアドレスのみが考慮され、ホストアドレスは考慮されません。-1、0、1 のいずれかを返します。

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

バージョン 3.7 で非推奨: It uses the same ordering and comparison algorithm as "<", "==", and ">"

class ipaddress.IPv6Network(address, strict=True)

IPv6 ネットワーク定義を構築します。address は以下の1つです:

A string consisting of an IP address and an optional prefix length, separated by a slash (/). 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 /128.

Note that currently expanded netmasks are not supported. That means 2001:db00::0/24 is a valid argument while 2001:db00::0/ffff:ff00:: is not.

128bit に収まる整数。これは1つのアドレスのネットワークと等しく、ネットワークアドレスが address に、マスクが /128 になります。

16byte の bytes オブジェクトにビッグエンディアンでパックされた整数。これは整数の address と同じように解釈されます。

アドレス記述とネットマスクの2要素のタプル。アドレス記述は、文字列、128ビットの整数、16バイトのパックされた整数、 既存の IPv6Address オブジェクトのいずれかです。ネットマスクは、プレフィックス長を表す整数です。

address が有効な IPv6 アドレスでない場合に AddressValueError 例外を発生させます。マスクが IPv6 アドレスに対して有効でない場合に NetmaskValueError 例外を発生させます。

strict が True の場合、与えられたアドレスのホストビットが立っていたら ValueError を発生させます。そうでない場合、ホストビットをマスクして正しいネットワークアドレスを計算します。

バージョン 3.5 で変更: address コンストラクタ引数に2要素のタプル形式を追加しました

version

max_prefixlen

is_multicast

is_private

is_unspecified

is_reserved

is_loopback

is_link_local

network_address

broadcast_address

hostmask

netmask

with_prefixlen

compressed

exploded

with_netmask

with_hostmask

num_addresses

prefixlen

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.

overlaps(other)

address_exclude(network)

subnets(prefixlen_diff=1, new_prefix=None)

supernet(prefixlen_diff=1, new_prefix=None)

subnet_of(other)

supernet_of(other)

compare_networks(other)

IPv4Network の対応する属性のドキュメントを参照してください。

is_site_local

These attribute is true for the network as a whole if it is true for both the network address and the broadcast address.

演算子

Network オブジェクトはいくつかの演算子をサポートします。明記されない限り、演算子は互換性のあるオブジェクト間 (つまり IPv4 同士や IPv6 同士) でのみ利用できます。

論理演算子

Network objects can be compared with the usual set of logical operators. Network objects are ordered first by network address, then by net mask.

イテレーション

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 hosts() method). An 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')

アドレスのコンテナとしてのネットワーク

ネットワークオブジェクトは、アドレスのコンテナとして振舞えます。いくつか例をあげます:

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

インターフェイスオブジェクト

インターフェースオブジェクトは hashable なので、辞書のキーとして使用できます。

class ipaddress.IPv4Interface(address)

Construct an IPv4 interface. The meaning of address is as in the constructor of IPv4Network, except that arbitrary host addresses are always accepted.

IPv4Interface is a subclass of IPv4Address, so it inherits all the attributes from that class. In addition, the following attributes are available:

ip

The address (IPv4Address) without network information.

>>> interface = IPv4Interface('192.0.2.5/24')
>>> interface.ip
IPv4Address('192.0.2.5')

network

The network (IPv4Network) this interface belongs to.

>>> interface = IPv4Interface('192.0.2.5/24')
>>> interface.network
IPv4Network('192.0.2.0/24')

with_prefixlen

A string representation of the interface with the mask in prefix notation.

>>> interface = IPv4Interface('192.0.2.5/24')
>>> interface.with_prefixlen
'192.0.2.5/24'

with_netmask

A string representation of the interface with the network as a net mask.

>>> interface = IPv4Interface('192.0.2.5/24')
>>> interface.with_netmask
'192.0.2.5/255.255.255.0'

with_hostmask

A string representation of the interface with the network as a host mask.

>>> interface = IPv4Interface('192.0.2.5/24')
>>> interface.with_hostmask
'192.0.2.5/0.0.0.255'

class ipaddress.IPv6Interface(address)

Construct an IPv6 interface. The meaning of address is as in the constructor of IPv6Network, except that arbitrary host addresses are always accepted.

IPv6Interface is a subclass of IPv6Address, so it inherits all the attributes from that class. In addition, the following attributes are available:

ip

network

with_prefixlen

with_netmask

with_hostmask

IPv4Interface の対応する属性のドキュメントを参照してください。

演算子

Interface オブジェクトはいくつかの演算子をサポートします。明記されない限り、演算子は互換性のあるオブジェクト間 (つまり IPv4 同士や IPv6 同士) でのみ利用できます。

論理演算子

Interface objects can be compared with the usual set of logical operators.

For equality comparison (== and !=), 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 (<, >, 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.

その他のモジュールレベル関数

このモジュールは以下のモジュールレベル関数も提供しています:

ipaddress.v4_int_to_packed(address)

アドレスをネットワークバイトオーダー(ビッグエンディアン)でパックされた4バイトで表現します。 address は IPv4 IPアドレスを整数で表したものです。整数が負だったり IPv4 IPアドレスとして大きすぎる場合は ValueError 例外を発生させます。

>>> ipaddress.ip_address(3221225985)
IPv4Address('192.0.2.1')
>>> ipaddress.v4_int_to_packed(3221225985)
b'\xc0\x00\x02\x01'

ipaddress.v6_int_to_packed(address)

アドレスをネットワークバイトオーダー(ビッグエンディアン)でパックされた16バイトで表現します。 address は IPv6 IPアドレスを整数で表したものです。整数が負だったり IPv6 IPアドレスとして大きすぎる場合は ValueError 例外を発生させます。

ipaddress.summarize_address_range(first, last)

first と last で指定された IPアドレス帯に対するイテレーターを返します。 first はアドレス帯の中の最初の IPv4Address か IPv6Address で、 last はアドレス帯の中の最後の IPv4Address か IPv6Address です。 first か last がIPアドレスでない場合や、2つの型が揃っていない場合に、 TypeError を発生させます。 last が first より大きくない場合や、 first アドレスのバージョンが 4 でも 6 でもない場合は ValueError を発生させます。

>>> [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')]

ipaddress.collapse_addresses(addresses)

Return an iterator of the collapsed IPv4Network or IPv6Network objects. addresses is an iterator of IPv4Network or IPv6Network objects. A TypeError is raised if addresses contains mixed version objects.

>>> [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')]

ipaddress.get_mixed_type_key(obj)

ネットワークとアドレスをソートするための key 関数を返します。アドレスとネットワークは本質的に違うものなので、デフォルトでは比較できません。そのため、次の式は:

IPv4Address('192.0.2.0') <= IPv4Network('192.0.2.0/24')

理にかなっていません。しかし、それでも ipaddress にそれらをソートしてほしい場合があるかもしれません。その場合は、この関数を sorted() の key 引数に使うことができます。

obj はネットワークオブジェクトかアドレスオブジェクトのどちらかです。

Custom Exceptions

クラスのコンストラクタがより具体的なエラー報告をするために、このモジュールでは以下の例外を定義します:

exception ipaddress.AddressValueError(ValueError)

Any value error related to the address.

exception ipaddress.NetmaskValueError(ValueError)

Any value error related to the net mask.

マルチメディアサービス

この章で記述されているモジュールは、主にマルチメディアアプリケーションに役立つさまざまなアルゴリズムまたはインターフェイスを実装しています。これらのモジュールはインストール時の自由裁量に応じて利用できます:

wave --- Read and write WAV files

Wave_read オブジェクト

Wave_write オブジェクト

colorsys --- Conversions between color systems

wave --- Read and write WAV files

ソースコード: Lib/wave.py [https://github.com/python/cpython/tree/3.12/Lib/wave.py]

The wave module provides a convenient interface to the Waveform Audio "WAVE" (or "WAV") file format. Only uncompressed PCM encoded wave files are supported.

バージョン 3.12 で変更: Support for WAVE_FORMAT_EXTENSIBLE headers was added, provided that the extended format is KSDATAFORMAT_SUBTYPE_PCM.

wave モジュールは、以下の関数と例外を定義しています:

wave.open(file, mode=None)

file が文字列ならその名前のファイルを開き、そうでないなら file like オブジェクトとして扱います。 mode は以下のうちのいずれかです:

'rb'

読み出しのみのモード。

'wb'

書き込みのみのモード。

WAVファイルに対して読み込み／書き込み両方のモードで開くことはできないことに注意して下さい。

mode が 'rb' の場合 Wave_read オブジェクトを返し、 'wb' の場合 Wave_write オブジェクトを返します。 mode が省略されていて、 file-like オブジェクトが file として渡されると、 file.mode が mode のデフォルト値として使われます。

If you pass in a file-like object, the wave object will not close it when its close() method is called; it is the caller's responsibility to close the file object.

The open() function may be used in a with statement. When the with block completes, the Wave_read.close() or Wave_write.close() method is called.

バージョン 3.4 で変更: シーク不能なファイルのサポートが追加されました。

exception wave.Error

WAVの仕様を犯したり、実装の欠陥に遭遇して何か実行不可能となった時に発生するエラー。

Wave_read オブジェクト

class wave.Wave_read

Read a WAV file.

open() によって返される Wave_read オブジェクトには、以下のメソッドがあります:

close()

wave によって開かれていた場合はストリームを閉じ、このオブジェクトのインスタンスを使用できなくします。これはオブジェクトのガベージコレクション時に自動的に呼び出されます。

getnchannels()

オーディオチャンネル数（モノラルなら 1 、ステレオなら 2 ）を返します。

getsampwidth()

サンプルサイズをバイト数で返します。

getframerate()

サンプリングレートを返します。

getnframes()

オーディオフレーム数を返します。

getcomptype()

圧縮形式を返します（ 'NONE' だけがサポートされている形式です）。

getcompname()

getcomptype() を人に判読可能な形にしたものです。通常、 'NONE' に対して 'not compressed' が返されます。

getparams()

Returns a namedtuple() (nchannels, sampwidth, framerate, nframes, comptype, compname), equivalent to output of the get*() methods.

readframes(n)

最大 n 個のオーディオフレームを読み込んで、 bytes オブジェクトとして返します。

rewind()

ファイルのポインタをオーディオストリームの先頭に戻します。

The following two methods are defined for compatibility with the aifc module, and don't do anything interesting.

getmarkers()

None を返します。

getmark(id)

エラーを発生します。

以下の2つのメソッドは共通の"位置"を定義しています。"位置"は他の関数とは独立して実装されています。

setpos(pos)

ファイルのポインタを指定した位置に設定します。

tell()

ファイルの現在のポインタ位置を返します。

Wave_write オブジェクト

class wave.Wave_write

Write a WAV file.

Wave_write objects, as returned by open().

For seekable output streams, the wave header will automatically be updated to reflect the number of frames actually written. For unseekable streams, the nframes value must be accurate when the first frame data is written. An accurate nframes value can be achieved either by calling setnframes() or setparams() with the number of frames that will be written before close() is called and then using writeframesraw() to write the frame data, or by calling writeframes() with all of the frame data to be written. In the latter case writeframes() will calculate the number of frames in the data and set nframes accordingly before writing the frame data.

バージョン 3.4 で変更: シーク不能なファイルのサポートが追加されました。

Wave_write objects have the following methods:

close()

nframes が正しいか確認して、ファイルが wave によって開かれていた場合は閉じます。このメソッドはオブジェクトがガベージコレクションされるときに呼び出されます。もし出力ストリームがシーク不能で、 nframes が実際に書き込まれたフレームの数と一致しなければ、例外が起きます。

setnchannels(n)

チャンネル数を設定します。

setsampwidth(n)

サンプルサイズを n バイトに設定します。

setframerate(n)

サンプリングレートを n に設定します。

バージョン 3.2 で変更: 整数ではない値がこのメソッドに入力された場合は、直近の整数に丸められます。

setnframes(n)

フレーム数を n に設定します。もし実際に書き込まれたフレームの数と異なるなら、これは後で変更されます (出力ストリームがシーク不能なら、更新しようとした時にエラーが起きます)。

setcomptype(type, name)

圧縮形式とその記述を設定します。現在のところ、非圧縮を示す圧縮形式 NONE だけがサポートされています。

setparams(tuple)

The tuple should be (nchannels, sampwidth, framerate, nframes, comptype, compname), with values valid for the set*() methods. Sets all parameters.

tell()

ファイルの中の現在位置を返します。 Wave_read.tell() と Wave_read.setpos() メソッドでお断りしたことがこのメソッドにも当てはまります。

writeframesraw(data)

nframes の修正なしにオーディオフレームを書き込みます。

バージョン 3.4 で変更: どのような bytes-like object も使用できるようになりました。

writeframes(data)

出力ストリームが seek 不可能で、 data が書き込まれた後でそれ以前に nframes に設定された値と書き込まれた全フレーム数が一致しなければ、エラーを送出します。

バージョン 3.4 で変更: どのような bytes-like object も使用できるようになりました。

writeframes() や writeframesraw() メソッドを呼び出したあとで、どんなパラメータを設定しようとしても不正となることに注意して下さい。そうすると wave.Error を発生します。

colorsys --- Conversions between color systems

ソースコード: Lib/colorsys.py [https://github.com/python/cpython/tree/3.12/Lib/colorsys.py]

colorsys モジュールは、計算機のディスプレイモニタで使われている RGB (Red Green Blue) 色空間で表された色と、他の 3 種類の色座標系: YIQ, HLS (Hue Lightness Saturation: 色相、彩度、飽和) および HSV (Hue Saturation Value: 色相、彩度、明度) との間の双方向の色値変換を定義します。これらの色空間における色座標系は全て浮動小数点数で表されます。 YIQ 空間では、Y 軸は 0 から 1 ですが、 I および Q 軸は正の値も負の値もとり得ます。他の色空間では、各軸は全て 0 から 1 の値をとります。

参考

色空間に関するより詳細な情報は https://poynton.ca/ColorFAQ.html と https://www.cambridgeincolour.com/tutorials/color-spaces.htm にあります。

colorsys モジュールでは、以下の関数が定義されています:

colorsys.rgb_to_yiq(r, g, b)

RGB から YIQ に変換します。

colorsys.yiq_to_rgb(y, i, q)

YIQ から RGB に変換します。

colorsys.rgb_to_hls(r, g, b)

RGB から HLS に変換します。

colorsys.hls_to_rgb(h, l, s)

HLS から RGB に変換します。

colorsys.rgb_to_hsv(r, g, b)

RGB から HSV に変換します。

colorsys.hsv_to_rgb(h, s, v)

HSV から RGB に変換します。

以下はプログラム例です:

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

国際化

この章で解説されるモジュールは、プログラムのメッセージで使用される言語を選択したり、または出力を地域の習慣に従って変更するメカニズムを提供して、言語やロケールに依存しないソフトの開発を手助けします。

この章で解説されるモジュールのリスト:

gettext --- Multilingual internationalization services

GNU gettext API

クラス形式の API

NullTranslations クラス

GNUTranslations クラス

Solaris メッセージカタログ機構のサポート

Catalog コンストラクタ

プログラムやモジュールを国際化する

モジュールを地域化する

アプリケーションを地域化する

動作中 (on the fly) に言語を切り替える

翻訳処理の遅延解決

謝辞

locale --- Internationalization services

ロケールの背景、詳細、ヒント、助言および補足説明

Python 拡張の作者と、Python を埋め込むようなプログラムに関して

メッセージカタログへのアクセス

gettext --- Multilingual internationalization services

ソースコード: Lib/gettext.py [https://github.com/python/cpython/tree/3.12/Lib/gettext.py]

gettext モジュールは、 Python のモジュールやアプリケーションの国際化 (I18N, I-nternationalizatio-N) および地域化 (L10N, L-ocalizatio-N) サービスを提供します。このモジュールは GNU gettext メッセージカタログの API と、より高水準で Python ファイルに適しているクラス形式の API の両方をサポートしてます。以下で述べるインターフェースを使うことで、モジュールやアプリケーションのメッセージをある自然言語で記述しておき、後から提供する翻訳されたメッセージのカタログによって様々な自然言語環境で実行できます。

ここでは Python のモジュールやアプリケーションを地域化するためのいくつかのヒントも提供しています。

GNU gettext API

gettext モジュールでは、以下の GNU gettext API に非常に良く似た API を提供しています。この API を使う場合、アプリケーション全体の翻訳に影響します。アプリケーションが単一の言語しか扱わず、ユーザのロケールに従って言語が選ばれるのなら、たいていはこの API が求めているものです。 Python モジュールを地域化していたり、アプリケーションの実行中に言語を切り替える必要がある場合は、この API ではなくおそらくクラス形式の API を使いたくなるでしょう。

gettext.bindtextdomain(domain, localedir=None)

domain をロケールディレクトリ localedir に対応付けます。具体的には、 gettext は与えられたドメインに対するバイナリ形式の .mo ファイルを探しに、(Unixでは) localedir/language/LC_MESSAGES/domain.mo というパスを見に行きます。ここで language はそれぞれ環境変数 LANGUAGE 、 LC_ALL 、 LC_MESSAGES 、 LANG の中から検索されます。

localedir が省略されるか None の場合、現在 domain に対応付けられているロケールディレクトリが返されます。 [1]

gettext.textdomain(domain=None)

現在のグローバルドメインを変更したり調べたりします。 domain が None の場合、現在のグローバルドメインが返されます。それ以外の場合には、グローバルドメインに domain を設定し、その設定されたグローバルドメインを返します。

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 _() in the local namespace (see examples below).

gettext.dgettext(domain, message)

gettext() と同様ですが、指定された domain からメッセージを探します。

gettext.ngettext(singular, plural, n)

gettext() と同様ですが、複数形を考慮しています。翻訳が見つかった場合、複数形の選択公式を n に適用し、その結果得られたメッセージを返します (言語によっては二つ以上の複数形があります)。翻訳が見つからなかった場合、 n が 1 なら singular を返します; そうでない場合 plural を返します。

複数形の選択公式はカタログのヘッダから取得されます。選択公式は自由変数 n を持つ C または Python の式です; その式の評価結果はカタログにある複数形のインデックスになります。 .po ファイルで用いられる詳細な文法と、様々な言語における選択公式については GNU gettext ドキュメント [https://www.gnu.org/software/gettext/manual/gettext.html] を参照してください。

gettext.dngettext(domain, singular, plural, n)

ngettext() と同様ですが、指定された domain からメッセージを探します。

gettext.pgettext(context, message)

gettext.dpgettext(domain, context, message)

gettext.npgettext(context, singular, plural, n)

gettext.dnpgettext(domain, context, singular, plural, n)

Similar to the corresponding functions without the p in the prefix (that is, gettext(), dgettext(), ngettext(), dngettext()), but the translation is restricted to the given message context.

Added in version 3.8.

Note that GNU gettext also defines a dcgettext() method, but this was deemed not useful and so it is currently unimplemented.

以下にこの API の典型的な使用法を示します:

import gettext
gettext.bindtextdomain('myapplication', '/path/to/my/language/directory')
gettext.textdomain('myapplication')
_ = gettext.gettext
# ...
print(_('This is a translatable string.'))

クラス形式の API

The class-based API of the gettext module gives you more flexibility and greater convenience than the GNU gettext API. It is the recommended way of localizing your Python applications and modules. gettext defines a GNUTranslations class which implements the parsing of GNU .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 _().

gettext.find(domain, localedir=None, languages=None, all=False)

この関数は標準的な .mo ファイル検索アルゴリズムを実装しています。 textdomain() と同じく、 domain を引数にとります。オプションの localedir は bindtextdomain() と同じです。またオプションの languages は文字列を列挙したリストで、各文字列は言語コードを表します。

localedir が与えられていない場合、標準のシステムロケールディレクトリが使われます。 [2] languages が与えられなかった場合、以下の環境変数: LANGUAGE 、 LC_ALL 、 LC_MESSAGES 、および LANG が検索されます。空でない値を返した最初の候補が languages 変数として使われます。この環境変数は言語名をコロンで分かち書きしたリストを含んでいなければなりません。 find() はこの文字列をコロンで分割し、言語コードの候補リストを生成します。

find() は次に言語コードを展開および正規化し、リストの各要素について、以下のパス構成:

localedir/language/LC_MESSAGES/domain.mo

からなる実在するファイルの探索を反復的に行います。 find() は上記のような実在するファイルで最初に見つかったものを返します。該当するファイルが見つからなかった場合、 None が返されます。 all が与えられていれば、全ファイル名のリストが言語リストまたは環境変数で指定されている順番に並べられたものを返します。

gettext.translation(domain, localedir=None, languages=None, class_=None, fallback=False)

Return a *Translations instance based on the domain, localedir, and languages, which are first passed to find() to get a list of the associated .mo file paths. Instances with identical .mo file names are cached. The actual class instantiated is class_ if provided, otherwise GNUTranslations. The class's constructor must take a single file object argument.

複数の .mo ファイルがあった場合、後ろのファイルは前のファイルのフォールバックとして利用されます。フォールバックの設定のために、 copy.copy() を使いキャッシュから翻訳オブジェクトを複製します; こうすることで、実際のインスタンスデータはキャッシュのものと共有されたままになります。

.mo ファイルが見つからなかった場合、 fallback が偽 (デフォルト値) ならこの関数は OSError を送出し、 fallback が真なら NullTranslations インスタンスが返されます。

バージョン 3.3 で変更: 以前は IOError が送出されました; それは現在 OSError のエイリアスです。

バージョン 3.11 で変更: codeset parameter is removed.

gettext.install(domain, localedir=None, *, names=None)

This installs the function _() in Python's builtins namespace, based on domain and localedir which are passed to the function translation().

names パラメータについては、翻訳オブジェクトの install() メソッドの説明を参照ください。

As seen below, you usually mark the strings in your application that are candidates for translation, by wrapping them in a call to the _() function, like this:

print(_('This string will be translated.'))

For convenience, you want the _() 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.

NullTranslations クラス

翻訳クラスは、元のソースファイル中のメッセージ文字列から翻訳されたメッセージ文字列への変換処理が実際に実装されているクラスです。全ての翻訳クラスで基底クラスとして使われているクラスが NullTranslations です; このクラスは、独自の翻訳クラスを実装するのに使える基本的なインターフェースを提供しています。以下に NullTranslations のメソッドを示します:

class gettext.NullTranslations(fp=None)

オプションの ファイルオブジェクト fp を取ります。この引数は基底クラスでは無視されます。このメソッドは "保護された (protected)" インスタンス変数 _info および _charset を初期化します。これらの変数の値は派生クラスで設定することができます。同様に _fallback も初期化しますが、この値は add_fallback() で設定されます。その後、 fp が None でない場合 self._parse(fp) を呼び出します。

_parse(fp)

基底クラスでは何もしない (no-op) ようになっています。このメソッドの役割はファイルオブジェクト fp を引数に取り、ファイルからデータを読み出し、メッセージカタログを初期化することです。サポートされていないメッセージカタログ形式を使っている場合、その形式を解釈するためにはこのメソッドを上書きしなくてはなりません。

add_fallback(fallback)

fallback を現在の翻訳オブジェクトの代替オブジェクトとして追加します。翻訳オブジェクトが与えられたメッセージに対して翻訳メッセージを提供できない場合、この代替オブジェクトに問い合わせることになります。

gettext(message)

フォールバックが設定されている場合、フォールバックの gettext() に処理を移譲します。そうでない場合、引数として受け取った message を返します。派生クラスで上書きするメソッドです。

ngettext(singular, plural, n)

フォールバックが設定されている場合、フォールバックの ngettext() に処理を移譲します。そうでない場合、 n が 1 なら singular を返します; それ以外なら plural を返します。派生クラスで上書きするメソッドです。

pgettext(context, message)

代替オブジェクトが設定されている場合、 pgettext() を代替オブジェクトに転送します。そうでない場合、翻訳されたメッセージを返します。派生クラスで上書きするメソッドです。

Added in version 3.8.

npgettext(context, singular, plural, n)

代替オブジェクトが設定されている場合、 npgettext() を代替オブジェクトに転送します。そうでない場合、翻訳されたメッセージを返します。派生クラスで上書きするメソッドです。

Added in version 3.8.

info()

Return a dictionary containing the metadata found in the message catalog file.

charset()

メッセージカタログファイルのエンコーディングを返します。

install(names=None)

このメソッドは gettext() を組み込み名前空間にインストールし、変数 _ に束縛します。

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 _(). Supported names are 'gettext', 'ngettext', 'pgettext', and 'npgettext'.

Note that this is only one way, albeit the most convenient way, to make the _() function available to your application. Because it affects the entire application globally, and specifically the built-in namespace, localized modules should never install _(). Instead, they should use this code to make _() available to their module:

import gettext
t = gettext.translation('mymodule', ...)
_ = t.gettext

This puts _() only in the module's global namespace and so only affects calls within this module.

バージョン 3.8 で変更: 'pgettext' と 'npgettext' が追加されました。

GNUTranslations クラス

The gettext module provides one additional class derived from NullTranslations: GNUTranslations. This class overrides _parse() to enable reading GNU gettext format .mo files in both big-endian and little-endian format.

GNUTranslations parses optional metadata out of the translation catalog. It is convention with GNU gettext to include metadata as the translation for the empty string. This metadata is in RFC 822 [https://datatracker.ietf.org/doc/html/rfc822.html]-style key: value pairs, and should contain the Project-Id-Version key. If the key Content-Type is found, then the charset property is used to initialize the "protected" _charset instance variable, defaulting to 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 *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" _info instance variable.

.mo ファイルのマジックナンバーが不正な場合や、メジャーバージョン番号が予期されないものの場合、あるいはその他の問題がファイルの読み出し中に発生した場合、 GNUTranslations クラスのインスタンス化で OSError が送出されることがあります。

class gettext.GNUTranslations

以下のメソッドは基底クラスの実装からオーバライドされています:

gettext(message)

カタログから message id を検索して、対応するメッセージ文字列を Unicode でエンコードして返します。 message id に対応するエントリがカタログに存在せず、フォールバックが設定されている場合、検索処理をフォールバックの gettext() メソッドに移譲します。それ以外の場合は、 message id 自体が返されます。

ngettext(singular, plural, n)

メッセージ id に対する複数形を検索します。カタログに対する検索では singular がメッセージ id として用いられ、 n にはどの複数形を用いるかを指定します。返されるメッセージ文字列は Unicode 文字列です。

メッセージ id がカタログ中に見つからず、フォールバックが指定されている場合は、メッセージ検索要求はフォールバックの ngettext() メソッドに移譲されます。それ以外の場合、 n が 1 ならば singular が返され、それ以外なら plural が返されます。

以下に例を示します。:

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}

pgettext(context, message)

カタログから context と message id を検索して、対応するメッセージ文字列を、 Unicode でエンコードして返します。 message id と context に対するエントリがカタログに存在せず、フォールバックが設定されている場合、フォールバック検索はオブジェクトの pgettext() メソッドに転送されます。そうでない場合、 message id 自体が返されます。

Added in version 3.8.

npgettext(context, singular, plural, n)

メッセージ id に対する複数形を検索します。カタログに対する検索では singular がメッセージ id として用いられ、 n にはどの複数形を用いるかを指定します。

context に対するメッセージ id がカタログ中に見つからず、フォールバックオブジェクトが指定されている場合、メッセージ検索要求はフォールバックオブジェクトの npgettext() メソッドに転送されます。そうでない場合、 n が 1 ならば singular が返され、それ以外に対しては plural が返されます。

Added in version 3.8.

Solaris メッセージカタログ機構のサポート

Solaris オペレーティングシステムでは、独自の .mo バイナリファイル形式を定義していますが、この形式に関するドキュメントが手に入らないため、現時点ではサポートされていません。

Catalog コンストラクタ

GNOME では、James Henstridge によるあるバージョンの gettext モジュールを使っていますが、このバージョンは少し異なった API を持っています。ドキュメントに書かれている利用法は:

import gettext
cat = gettext.Catalog(domain, localedir)
_ = cat.gettext
print(_('hello world'))

For compatibility with this older module, the function Catalog() is an alias for the translation() function described above.

このモジュールと Henstridge のバージョンとの間には一つ相違点があります: 彼のカタログオブジェクトはマップ型の API を介したアクセスがサポートされていましたが、この API は使われていないらしく、現在はサポートされていません。

プログラムやモジュールを国際化する

国際化 (I18N, I-nternationalizatio-N) とは、プログラムを複数の言語に対応させる操作を指します。地域化 (L10N, L-ocalizatio-N) とは、すでに国際化されているプログラムを特定地域の言語や文化的な事情に対応させることを指します。Python プログラムに多言語メッセージ機能を追加するには、以下の手順を踏む必要があります:

プログラムやモジュールで翻訳対象とする文字列に特殊なマークをつけて準備します

マークづけをしたファイルに一連のツールを走らせ、生のメッセージカタログを生成します

特定の言語へのメッセージカタログの翻訳を作成します

メッセージ文字列を適切に変換するために gettext モジュールを使います

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 _('...') --- that is, a call to the function _. For example:

filename = 'mylog.txt'
message = _('writing a log message')
with open(filename, 'w') as fp:
    fp.write(message)

この例では、文字列 'writing a log message' が翻訳対象候補としてマーク付けされており、文字列 'mylog.txt' および 'w' はされていません。

翻訳対象の文字列を抽出するツールもあります。オリジナルの GNU gettext は C と C++ のソースコードしかサポートしませんが、拡張版の xgettext は Python を含めた多くの言語で書かれたコードを読み取り、翻訳できる文字列を発見します。 Babel [https://babel.pocoo.org/] は Python の国際化ライブラリで、翻訳文字列の抽出とメッセージカタログのコンパイルを行う pybabel スクリプトがあります。 François Pinard が開発した xpot と呼ばれるプログラムは同じような処理を行え、彼の po-utils package [https://github.com/pinard/po-utils] の一部として利用可能です。

(Python には pygettext.py および msgfmt.py という名前の pure-Python 版プログラムもあります; これをインストールしてくれる Python ディストリビューションもあります。 pygettext.py は xgettext に似たプログラムですが Python のソースコードしか理解できず、 C や C++ のような他のプログラミング言語を扱えません。 pygettext.py は xgettext と同様のコマンドラインインターフェースをサポートしています; 詳しい使い方については pygettext.py --help と実行してください。 msgfmt.py は GNU msgfmt とバイナリ互換性があります。この2つのプログラムがあれば、 GNU gettext パッケージを使わずに Python アプリケーションを国際化できるでしょう。)

xgettext や pygettext のようなツールは、メッセージカタログである .po ファイルを生成します。このファイルは人間が判読可能な構造をしていて、ソースコード中のマークが着けられた文字列と、その文字列の仮置きの訳文が一緒に書き込まれています。

生成された .po ファイルは翻訳者個々人へ頒布され、サポート対象の各自然言語への訳文が書き込まれます。ある言語への飜訳が完了した <language-name>.po ファイルは翻訳者により返送され、 msgfmt を使い機械が読み込みやすい .mo バイナリカタログファイルへとコンパイルされます。この .mo が gettext モジュールによる実行時の実際の飜訳処理で使われます。

gettext モジュールをソースコード中でどのように使うかは単一のモジュールを国際化するのか、それともアプリケーション全体を国際化するのかによります。次のふたつのセクションで、それぞれについて説明します。

モジュールを地域化する

モジュールを地域化する場合、グローバルな変更、例えば組み込み名前空間への変更を行わないように注意しなければなりません。GNU gettext API ではなく、クラス形式の API を使うべきです。

仮に対象のモジュール名を "spam" とし、モジュールの各言語における翻訳が収められた .mo ファイルが /usr/share/locale に GNU gettext 形式で置かれているとします。この場合、モジュールの最初で以下のようにします:

import gettext
t = gettext.translation('spam', '/usr/share/locale')
_ = t.gettext

アプリケーションを地域化する

If you are localizing your application, you can install the _() 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 _('...') without having to explicitly install it in each file.

単純な場合では、単に以下の短いコードをアプリケーションの主ドライバファイルに追加するだけです:

import gettext
gettext.install('myapplication')

ロケールの辞書を設定する必要がある場合、install() 関数に渡すことが出来ます:

import gettext
gettext.install('myapplication', '/usr/share/locale')

動作中 (on the fly) に言語を切り替える

多くの言語を同時にサポートする必要がある場合、複数の翻訳インスタンスを生成して、例えば以下のコードのように、インスタンスを明示的に切り替えてもかまいません。:

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()

翻訳処理の遅延解決

コードを書く上では、ほとんどの状況で文字列はコードされた場所で翻訳されます。しかし場合によっては、翻訳対象として文字列をマークはするが、その後実際に翻訳が行われるように遅延させる必要が生じます。古典的な例は以下のようなコートです:

animals = ['mollusk',
           'albatross',
           'rat',
           'penguin',
           'python', ]
# ...
for a in animals:
    print(a)

ここで、リスト animals 内の文字列は翻訳対象としてマークはしたいが、文字列が出力されるまで実際に翻訳を行うのは避けたいとします。

こうした状況を処理する一つの方法を以下に示します:

def _(message): return message

animals = [_('mollusk'),
           _('albatross'),
           _('rat'),
           _('penguin'),
           _('python'), ]

del _

# ...
for a in animals:
    print(_(a))

This works because the dummy definition of _() simply returns the string unchanged. And this dummy definition will temporarily override any definition of _() in the built-in namespace (until the del command). Take care, though if you have a previous definition of _() in the local namespace.

Note that the second use of _() will not identify "a" as being translatable to the gettext program, because the parameter is not a string literal.

もう一つの処理法は、以下の例のようなやり方です:

def N_(message): return message

animals = [N_('mollusk'),
           N_('albatross'),
           N_('rat'),
           N_('penguin'),
           N_('python'), ]

# ...
for a in animals:
    print(_(a))

In this case, you are marking translatable strings with the function N_(), which won't conflict with any definition of _(). However, you will need to teach your message extraction program to look for translatable strings marked with N_(). xgettext, pygettext, pybabel extract, and xpot all support this through the use of the -k command-line switch. The choice of N_() here is totally arbitrary; it could have just as easily been MarkThisStringForTranslation().

謝辞

以下の人々が、このモジュールのコード、フィードバック、設計に関する助言、過去の実装、そして有益な経験談による貢献をしてくれました:

Peter Funk

James Henstridge

Juan David Ibáñez Palomar

Marc-André Lemburg

Martin von Löwis

François Pinard

Barry Warsaw

Gustavo Niemeyer

脚注

[1]

The default locale directory is system dependent; for example, on Red Hat Linux it is /usr/share/locale, but on Solaris it is /usr/lib/locale. The gettext module does not try to support these system dependent defaults; instead its default is sys.base_prefix/share/locale (see sys.base_prefix). For this reason, it is always best to call bindtextdomain() with an explicit absolute path at the start of your application.

[2]

上の bindtextdomain() に関する脚注を参照してください。

locale --- Internationalization services

ソースコード: Lib/locale.py [https://github.com/python/cpython/tree/3.12/Lib/locale.py]

locale モジュールは POSIX ロケールデータベースおよびロケール関連機能へのアクセスを提供します。 POSIX ロケール機構を使うことで、プログラマはソフトウェアが実行される各国における詳細を知らなくても、アプリケーション上で特定の地域文化に関係する部分を扱うことができます。

The locale module is implemented on top of the _locale module, which in turn uses an ANSI C locale implementation if available.

locale モジュールでは以下の例外と関数を定義しています:

exception locale.Error

setlocale() に渡されたロケールが認識されない場合例外が送出されます。

locale.setlocale(category, locale=None)

locale が渡され None でない場合、setlocale() は category のロケール設定を変更します。利用可能なカテゴリーは下記の表を参照してください。 locale は文字列か2つの文字列の iterable (言語コードと文字コード) です。iterale の場合 locale aliasing engine を用いてロケール名に変換されます。空の文字列はユーザのデフォルトの設定を指定します。ロケールの変更に失敗した場合 Error が送出されます。成功した場合新しいロケールの設定が返されます。

locale が省略されたり None の場合、category の現在の設定が返されます。

setlocale() はほとんどのシステムでスレッド安全ではありません。アプリケーションを書くとき、大抵は以下のコード

import locale
locale.setlocale(locale.LC_ALL, '')

から書き始めます。これは全てのカテゴリをユーザの環境における標準設定 (大抵は環境変数 LANG で指定されています) に設定します。その後複数スレッドを使ってロケールを変更したりしない限り、問題は起こらないはずです。

locale.localeconv()

地域的な慣行のデータベースを辞書として返します。辞書は以下の文字列をキーとして持っています:

カテゴリ

キー

意味

LC_NUMERIC

'decimal_point'

小数点を表す文字です。

'grouping'

'thousands_sep' が来るかもしれない場所を相対的に表した数からなる配列です。配列が CHAR_MAX で終端されている場合、それ以上の桁では桁数字のグループ化を行いません。配列が 0 で終端されている場合、最後に指定したグループが反復的に使われます。

'thousands_sep'

桁グループ間を区切るために使われる文字です。

LC_MONETARY

'int_curr_symbol'

国際通貨を表現する記号です。

'currency_symbol'

地域的な通貨を表現する記号です。

'p_cs_precedes/n_cs_precedes'

通貨記号が値の前につくかどうかです (それぞれ正の値、負の値を表します)。

'p_sep_by_space/n_sep_by_space'

通貨記号と値との間にスペースを入れるかどうかです (それぞれ正の値、負の値を表します)。

'mon_decimal_point'

金額表示の際に使われる小数点です。

'frac_digits'

金額を地域的な方法で表現する際の小数点以下の桁数です。

'int_frac_digits'

金額を国際的な方法で表現する際の小数点以下の桁数です。

'mon_thousands_sep'

金額表示の際に桁区切り記号です。

'mon_grouping'

'grouping' と同じで、金額表示の際に使われます。

'positive_sign'

正の値の金額表示に使われる記号です。

'negative_sign'

負の値の金額表示に使われる記号です。

'p_sign_posn/n_sign_posn'

符号の位置です (それぞれ正の値と負の値を表します)。以下を参照してください。

数値形式の値に CHAR_MAX を設定すると、そのロケールでは値が指定されていないことを表します。

'p_sign_posn' および 'n_sign_posn' の取り得る値は以下の通りです。

値

説明

0

通貨記号および値は丸括弧で囲われます。

1

符号は値と通貨記号より前に来ます。

2

符号は値と通貨記号の後に続きます。

3

符号は値の直前に来ます。

4

符号は値の直後に来ます。

CHAR_MAX

このロケールでは特に指定しません。

LC_NUMERIC ロケールや LC_MONETARY ロケールが LC_CTYPE ロケールと異なっていて、数値文字列や通貨文字列が非 ASCII 文字列の場合、この関数は一時的に LC_NUMERIC ロケールや LC_MONETARY ロケールに LC_CTYPE ロケールを設定します。この一時的な変更は他のスレッドに影響を及ぼします。

バージョン 3.7 で変更: この関数は、一時的に LC_NUMERIC ロケールに LC_CTYPE ロケールを設定する場合があります。

locale.nl_langinfo(option)

ロケール特有の情報を文字列として返します。この関数は全てのシステムで利用可能なわけではなく、指定できる option もプラットフォーム間で大きく異なります。引数として使えるのは、locale モジュールで利用可能なシンボル定数を表す数字です。

関数 nl_langinfo() は以下のキーのうち一つを受理します。ほとんどの記述は GNU C ライブラリ中の対応する説明から引用されています。

locale.CODESET

選択されたロケールで用いられている文字エンコーディングの名前を文字列で取得します。

locale.D_T_FMT

日付と時刻をロケール特有の方法で表現するために、 time.strftime() の書式文字列として用いることのできる文字列を取得します。

locale.D_FMT

日付をロケール特有の方法で表現するために、 time.strftime() の書式文字列として用いることのできる文字列を取得します。

locale.T_FMT

時刻をロケール特有の方法で表現するために、 time.strftime() の書式文字列として用いることのできる文字列を取得します。

locale.T_FMT_AMPM

時刻を午前／午後の書式で表現するために、 time.strftime() の書式文字列として用いることのできる文字列を取得します。

locale.DAY_1

locale.DAY_2

locale.DAY_3

locale.DAY_4

locale.DAY_5

locale.DAY_6

locale.DAY_7

1 週間中の n 番目の曜日名を取得します。

注釈

ロケール US における、 DAY_1 を日曜日とする慣行に従っています。国際的な (ISO 8601) 月曜日を週の初めとする慣行ではありません。

locale.ABDAY_1

locale.ABDAY_2

locale.ABDAY_3

locale.ABDAY_4

locale.ABDAY_5

locale.ABDAY_6

locale.ABDAY_7

1 週間中の n 番目の曜日名を略式表記で取得します。

locale.MON_1

locale.MON_2

locale.MON_3

locale.MON_4

locale.MON_5

locale.MON_6

locale.MON_7

locale.MON_8

locale.MON_9

locale.MON_10

locale.MON_11

locale.MON_12

n 番目の月の名前を取得します。

locale.ABMON_1

locale.ABMON_2

locale.ABMON_3

locale.ABMON_4

locale.ABMON_5

locale.ABMON_6

locale.ABMON_7

locale.ABMON_8

locale.ABMON_9

locale.ABMON_10

locale.ABMON_11

locale.ABMON_12

n 番目の月の名前を略式表記で取得します。

locale.RADIXCHAR

基数点 (小数点ドット、あるいは小数点コンマ、等) を取得します。

locale.THOUSEP

1000 単位桁区切り (3 桁ごとのグループ化) の区切り文字を取得します。

locale.YESEXPR

肯定／否定で答える質問に対する肯定回答を正規表現関数で認識するために利用できる正規表現を取得します。

locale.NOEXPR

Get a regular expression that can be used with the regex(3) function to recognize a negative response to a yes/no question.

注釈

The regular expressions for YESEXPR and NOEXPR use syntax suitable for the regex function from the C library, which might differ from the syntax used in re.

locale.CRNCYSTR

通貨シンボルを取得します。シンボルを値の前に表示させる場合には "-"、値の後ろに表示させる場合には "+"、シンボルを基数点と置き換える場合には "." を前につけます。

locale.ERA

現在のロケールで使われている年代を表現する値を取得します。

ほとんどのロケールではこの値を定義していません。この値を設定しているロケールの例は Japanese です。日本には日付の伝統的な表示法として、時の天皇に対応する元号名があります。

通常この値を直接指定する必要はありません。 E を書式文字列に指定することで、関数 time.strftime() がこの情報を使うようになります。返される文字列の様式は決められていないので、異なるシステム間で様式に関する同じ知識が使えると期待してはいけません。

locale.ERA_D_T_FMT

日付および時間をロケール固有の年代に基づいた方法で表現するために、 time.strftime() の書式文字列として用いることのできる文字列を取得します。

locale.ERA_D_FMT

日付をロケール固有の年代に基づいた方法で表現するために、 time.strftime() の書式文字列として用いることのできる文字列を取得します。

locale.ERA_T_FMT

時刻をロケール固有の年代に基づいた方法で表現するために、 time.strftime() の書式文字列として用いることのできる文字列を取得します。

locale.ALT_DIGITS

返される値は 0 から 99 までの 100 個の値の表現です。

locale.getdefaultlocale([envvars])

標準のロケール設定を取得しようと試み、結果をタプル (language code, encoding) の形式で返します。

POSIXによると、 setlocale(LC_ALL, '') を呼ばなかったプログラムは、移植可能な 'C' ロケール設定を使います。 setlocale(LC_ALL, '') を呼ぶことで、 LANG 変数で定義された標準のロケール設定を使うようになります。 Python では現在のロケール設定に干渉したくないので、上で述べたような方法でその挙動をエミュレーションしています。

他のプラットフォームとの互換性を維持するために、環境変数 LANG だけでなく、引数 envvars で指定された環境変数のリストも調べられます。最初に見つかった定義が使われます。 envvars は標準では GNU gettext で使われている検索順になります; これは常に変数名 LANG を探します。GNU gettext では 'LC_ALL' 、 'LC_CTYPE' 、 'LANG' 、および 'LANGUAGE' の順に調べられます。

'C' の場合を除き、言語コードは RFC 1766 [https://datatracker.ietf.org/doc/html/rfc1766.html] に対応します。 language code および encoding が決定できなかった場合、 None になるかもしれません。

バージョン 3.11 で非推奨、バージョン 3.15 で削除予定.

locale.getlocale(category=LC_CTYPE)

Returns the current setting for the given locale category as sequence containing language code, encoding. category may be one of the LC_* values except LC_ALL. It defaults to LC_CTYPE.

'C' の場合を除き、言語コードは RFC 1766 [https://datatracker.ietf.org/doc/html/rfc1766.html] に対応します。 language code および encoding が決定できなかった場合、 None になるかもしれません。

locale.getpreferredencoding(do_setlocale=True)

テキストデータに使われる ロケールエンコーディング を、ユーザの設定に基づいて返します。ユーザの設定は異なるシステム間では異なった方法で表現され、システムによってはプログラミング的に得ることができないこともあるので、この関数が返すのはただの推測です。

システムによっては、ユーザの設定を取得するために setlocale() を呼び出す必要があるため、この関数はスレッド安全ではありません。 setlocale() を呼び出す必要がない、または呼び出したくない場合、 do_setlocale を False に設定する必要があります。

On Android or if the Python UTF-8 Mode is enabled, always return 'utf-8', the locale encoding and the do_setlocale argument are ignored.

The Python preinitialization configures the LC_CTYPE locale. See also the filesystem encoding and error handler.

バージョン 3.7 で変更: この関数は、 Android 上あるいは Python UTF-8 モード が有効になっている場合、常に "utf-8" を返すようになりました。

locale.getencoding()

Get the current locale encoding:

On Android and VxWorks, return "utf-8".

On Unix, return the encoding of the current LC_CTYPE locale. Return "utf-8" if nl_langinfo(CODESET) returns an empty string: for example, if the current LC_CTYPE locale is not supported.

On Windows, return the ANSI code page.

The Python preinitialization configures the LC_CTYPE locale. See also the filesystem encoding and error handler.

This function is similar to getpreferredencoding(False) except this function ignores the Python UTF-8 Mode.

Added in version 3.11.

locale.normalize(localename)

与えたロケール名を規格化したロケールコードを返します。返されるロケールコードは setlocale() で使うために書式化されています。規格化が失敗した場合、もとの名前がそのまま返されます。

与えたエンコードがシステムにとって未知の場合、標準の設定では、この関数は setlocale() と同様に、エンコーディングをロケールコードにおける標準のエンコーディングに設定します。

locale.resetlocale(category=LC_ALL)

Sets the locale for category to the default setting.

The default setting is determined by calling getdefaultlocale(). category defaults to LC_ALL.

バージョン 3.11 で非推奨、バージョン 3.13 で削除予定.

locale.strcoll(string1, string2)

現在の LC_COLLATE 設定に従って二つの文字列を比較します。他の比較を行う関数と同じように、 string1 が string2 に対して前に来るか、後に来るか、あるいは二つが等しいかによって、それぞれ負の値、正の値、あるいは 0 を返します。

locale.strxfrm(string)

文字列を、ロケールを考慮した比較に使える形式に変換します。例えば、 strxfrm(s1) < strxfrm(s2) は strcoll(s1, s2) < 0 と等価です。この関数は同じ文字列が何度も比較される場合、例えば文字列からなるシーケンスを順序付けて並べる際に使うことができます。

locale.format_string(format, val, grouping=False, monetary=False)

数値 val を現在の LC_NUMERIC の設定に基づいて書式化します。書式は % 演算子の慣行に従います。浮動小数点数については、必要に応じて浮動小数点が変更されます。 grouping が True なら、ロケールに配慮した桁数の区切りが行われます。

monetary が真なら、桁区切り記号やグループ化文字列を用いて変換を行います。

format % val 形式のフォーマット指定子を、現在のロケール設定を考慮したうえで処理します。

バージョン 3.7 で変更: monetary キーワード引数が追加されました。

locale.currency(val, symbol=True, grouping=False, international=False)

数値 val を、現在の LC_MONETARY の設定にあわせてフォーマットします。

symbol が真の場合は、返される文字列に通貨記号が含まれるようになります。これはデフォルトの設定です。grouping が True の場合(これはデフォルトではありません)は、値をグループ化します。international が True の場合(これはデフォルトではありません)は、国際的な通貨記号を使用します。

注釈

この関数は 'C' ロケールでは動作しないので、まず setlocale() でロケールを設定する必要があります。

locale.str(float)

浮動小数点数を str(float) と同じように書式化しますが、ロケールに配慮した小数点が使われます。

locale.delocalize(string)

文字列を LC_NUMERIC で設定された慣行に従って正規化された数値文字列に変換します。

Added in version 3.5.

locale.localize(string, grouping=False, monetary=False)

Converts a normalized number string into a formatted string following the LC_NUMERIC settings.

Added in version 3.10.

locale.atof(string, func=float)

Converts a string to a number, following the LC_NUMERIC settings, by calling func on the result of calling delocalize() on string.

locale.atoi(string)

文字列を LC_NUMERIC で設定された慣行に従って整数に変換します。

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 PEP 538 [https://peps.python.org/pep-0538/] and PEP 540 [https://peps.python.org/pep-0540/] for how this variable might be automatically coerced to 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 ctype.h. Instead, an internal pyctype.h provides locale-independent equivalents like Py_TOLOWER.

locale.LC_COLLATE

文字列を並べ替えるためのロケールカテゴリです。 locale モジュールの関数 strcoll() および strxfrm() が影響を受けます。

locale.LC_TIME

時刻を書式化するためのロケールカテゴリです。 time.strftime() はこのカテゴリに設定されている慣行に従います。

locale.LC_MONETARY

金額に関係する値を書式化するためのロケールカテゴリです。設定可能なオプションは関数 localeconv() で得ることができます。

locale.LC_MESSAGES

メッセージ表示のためのロケールカテゴリです。現在 Python はアプリケーション毎にロケールに対応したメッセージを出力する機能はサポートしていません。 os.strerror() が返すような、オペレーティングシステムによって表示されるメッセージはこのカテゴリによって影響を受けます。

This value may not be available on operating systems not conforming to the POSIX standard, most notably Windows.

locale.LC_NUMERIC

Locale category for formatting numbers. The functions format_string(), atoi(), atof() and str() of the locale module are affected by that category. All other numeric formatting operations are not affected.

locale.LC_ALL

全てのロケール設定を総合したものです。ロケールを変更する際にこのフラグが使われた場合、そのロケールにおける全てのカテゴリを設定しようと試みます。一つでも失敗したカテゴリがあった場合、全てのカテゴリにおいて設定変更を行いません。このフラグを使ってロケールを取得した場合、全てのカテゴリにおける設定を示す文字列が返されます。この文字列は、後に設定を元に戻すために使うことができます。

locale.CHAR_MAX

localeconv() の返す特別な値のためのシンボル定数です。

以下はプログラム例です:

>>> 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, '')   # use user's preferred locale
>>> locale.setlocale(locale.LC_ALL, 'C')  # use default (C) locale
>>> locale.setlocale(locale.LC_ALL, loc)  # restore saved locale

ロケールの背景、詳細、ヒント、助言および補足説明

C 標準では、ロケールはプログラム全体にわたる特性であり、その変更は高価な処理であるとしています。加えて、頻繁にロケールを変更するようなひどい実装はコアダンプを引き起こすこともあります。このことがロケールを正しく利用する上で苦痛となっています。

最初、プログラムが起動したときには、ユーザの希望するロケールにかかわらずロケールは C です。例外が1つあります: LC_CTYPE カテゴリは、現在のロケールエンコーディングをユーザーの希望するロケールエンコーディングに設定するために、スタートアップで変更されます。他のカテゴリについては、プログラムは setlocale(LC_ALL, '') を呼び出して、明示的にユーザの希望するロケール設定を行わなければなりません。

setlocale() をライブラリルーチン内で呼ぶことは、それがプログラム全体に及ぼす副作用の面から、一般的によくない考えです。ロケールを保存したり復帰したりするのもよくありません: 高価な処理であり、ロケールの設定が復帰する以前に起動してしまった他のスレッドに悪影響を及ぼすからです。

もし、汎用を目的としたモジュールを作っていて、ロケールによって影響をうけるような操作 (例えば time.strftime() の書式の一部) のロケール独立のバージョンが必要ということになれば、標準ライブラリルーチンを使わずに何とかしなければなりません。よりましな方法は、ロケール設定が正しく利用できているか確かめることです。最後の手段は、あなたのモジュールが C ロケール以外の設定には互換性がないとドキュメントに書くことです。

The only way to perform numeric operations according to the locale is to use the special functions defined by this module: atof(), atoi(), format_string(), str().

ロケールに従ってケース変換や文字分類を行う方法はありません。 (ユニコード) テキスト文字列については、これらは文字の値のみによって行われます。その一方、バイト文字列はバイトの ASCII 値に従って変換と分類が行われます。そして、上位ビットが立っているバイト (すなわち、non-ASCII バイト) は、決して変換されず、英字や空白などの文字クラスの一部とみなされることもありません。

Python 拡張の作者と、Python を埋め込むようなプログラムに関して

拡張モジュールは、現在のロケールを調べる以外は、決して setlocale() を呼び出してはなりません。しかし、返される値もロケールの復帰のために使えるだけなので、さほど便利とはいえません (例外はおそらくロケールが C かどうか調べることでしょう)。

When Python code uses the 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 _locale extension module (which does all the work) from the table of built-in modules in the config.c file, and make sure that the _locale module is not accessible as a shared library.

メッセージカタログへのアクセス

locale.gettext(msg)

locale.dgettext(domain, msg)

locale.dcgettext(domain, msg, category)

locale.textdomain(domain)

locale.bindtextdomain(domain, dir)

locale.bind_textdomain_codeset(domain, codeset)

C ライブラリの gettext インタフェースが提供されているシステムでは、 locake モジュールでそのインタフェースを公開しています。このインタフェースは関数 gettext() 、 dgettext() 、 dcgettext() 、 textdomain() 、 bindtextdomain() 、および bind_textdomain_codeset() からなります。これらは gettext モジュールの同名の関数に似ていますが、メッセージカタログとして C ライブラリのバイナリフォーマットを使い、メッセージカタログを探すために C ライブラリのサーチアルゴリズムを使います。

Python applications should normally find no need to invoke these functions, and should use gettext instead. A known exception to this rule are applications that link with additional C libraries which internally invoke C functions gettext or dcgettext. For these applications, it may be necessary to bind the text domain, so that the libraries can properly locate their message catalogs.

プログラムのフレームワーク

この章で解説されるモジュールはあなたのプログラムの大枠を規定するフレームワークです。現状では、ここで解説されるモジュールは全てコマンドラインインターフェースを書くためのものです。

この章で解説されるモジュールの完全な一覧は:

turtle --- タートルグラフィックス

はじめに

チュートリアル

Starting a turtle environment

Basic drawing

Pen の制御

The turtle's position

Making algorithmic patterns

How to...

Get started as quickly as possible

Use the turtle module namespace

Use turtle graphics in a script

Use object-oriented turtle graphics

Turtle graphics reference

Turtle のメソッド

TurtleScreen/Screen のメソッド

RawTurtle/Turtle のメソッドと対応する関数

Turtle の動き

Turtle の状態を知る

設定と計測

Pen の制御

描画状態

色の制御

塗りつぶし

さらなる描画の制御

タートルの状態

可視性

見た目

イベントを利用する

特別な Turtle のメソッド

Compound shapes

TurtleScreen/Screen のメソッドと対応する関数

ウィンドウの制御

アニメーションの制御

スクリーンイベントを利用する

入力メソッド

設定と特殊なメソッド

Screen 独自のメソッド、TurtleScreen から継承したもの以外

Public classes

説明

ヘルプと設定

ヘルプの使い方

ドキュメント文字列の翻訳

Screen および Turtle の設定方法

turtledemo --- デモスクリプト

python 2.6からの変更点

python 3.0からの変更点

cmd --- Support for line-oriented command interpreters

Cmdオブジェクト

Cmd の例

shlex --- Simple lexical analysis

shlex オブジェクト

解析規則

Improved Compatibility with Shells

turtle --- タートルグラフィックス

ソースコード: Lib/turtle.py [https://github.com/python/cpython/tree/3.12/Lib/turtle.py]

はじめに

Turtle graphics is an implementation of the popular geometric drawing tools introduced in Logo [https://en.wikipedia.org/wiki/Turtle_(robot)], developed by Wally Feurzeig, Seymour Papert and Cynthia Solomon in 1967.

Turtle star

Turtle can draw intricate shapes using programs that repeat simple moves.

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.

チュートリアル

New users should start here. In this tutorial we'll explore some of the basics of turtle drawing.

Starting a turtle environment

In a Python shell, import all the objects of the turtle module:

from turtle import *

If you run into a No module named '_tkinter' error, you'll have to install the Tk interface package on your system.

Basic drawing

Send the turtle forward 100 steps:

forward(100)

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

left(120)

Let's continue by drawing a triangle:

forward(100)
left(120)
forward(100)

Notice how the turtle, represented by an arrow, points in different directions as you steer it.

Experiment with those commands, and also with backward() and right().

Pen の制御

Try changing the color - for example, color('blue') - and width of the line - for example, width(3) - and then drawing again.

You can also move the turtle around without drawing, by lifting up the pen: up() before moving. To start drawing again, use down().

The turtle's position

Send your turtle back to its starting-point (useful if it has disappeared off-screen):

home()

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 co-ordinates with:

pos()

Home is at (0, 0).

And after a while, it will probably help to clear the window so we can start anew:

clearscreen()

Making algorithmic patterns

Using loops, it's possible to build up geometric patterns:

for steps in range(100):
    for c in ('blue', 'red', 'green'):
        color(c)
        forward(steps)
        right(30)

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

color('red')
fillcolor('yellow')

Just as up() and down() determine whether lines will be drawn, filling can be turned on and off:

begin_fill()

Next we'll create a loop:

while True:
    forward(200)
    left(170)
    if abs(pos()) < 1:
        break

abs(pos()) < 1 is a good way to know when the turtle is back at its home position.

Finally, complete the filling:

end_fill()

(Note that filling only actually takes place when you give the end_fill() command.)

How to...

This section covers some typical turtle use-cases and approaches.

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 from turtle import *. The turtle graphics tutorial covers this approach.

It's worth noting that many of the turtle commands also have even more terse equivalents, such as fd() for forward(). These are especially useful when working with learners for whom typing is not a skill.

You'll need to have the 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.

Use the turtle module namespace

Using 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 import turtle - fd() becomes turtle.fd(), width() becomes turtle.width() and so on. (If typing "turtle" over and over again becomes tedious, use for example import turtle as t instead.)

Use turtle graphics in a script

It's recommended to use the turtle module namespace as described immediately above, for 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)

Another step is also required though - as soon as the script ends, Python will also close the turtle's window. Add:

t.mainloop()

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.

Use object-oriented turtle graphics

参考

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

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()

Note the last line. t.screen is an instance of the Screen that a Turtle instance exists on; it's created automatically along with the turtle.

The turtle's screen can be customised, for example:

t.screen.title('Object-oriented turtle demo')
t.screen.bgcolor("orange")

Turtle graphics reference

注釈

以下の文書では関数に対する引数リストが与えられています。メソッドでは、勿論、ここでは省略されている self が第一引数になります。

Turtle のメソッド

Turtle の動き

移動および描画

forward() | fd()

backward() | bk() | back()

right() | rt()

left() | lt()

goto() | setpos() | setposition()

teleport()

setx()

sety()

setheading() | seth()

home()

circle()

dot()

stamp()

clearstamp()

clearstamps()

undo()

speed()

Turtle の状態を知る

position() | pos()

towards()

xcor()

ycor()

heading()

distance()

設定と計測

degrees()

radians()

Pen の制御

描画状態

pendown() | pd() | down()

penup() | pu() | up()

pensize() | width()

pen()

isdown()

色の制御

color()

pencolor()

fillcolor()

塗りつぶし

filling()

begin_fill()

end_fill()

さらなる描画の制御

reset()

clear()

write()

タートルの状態

可視性

showturtle() | st()

hideturtle() | ht()

isvisible()

見た目

shape()

resizemode()

shapesize() | turtlesize()

shearfactor()

settiltangle()

tiltangle()

tilt()

shapetransform()

get_shapepoly()

イベントを利用する

onclick()

onrelease()

ondrag()

特別な Turtle のメソッド

begin_poly()

end_poly()

get_poly()

clone()

getturtle() | getpen()

getscreen()

setundobuffer()

undobufferentries()

TurtleScreen/Screen のメソッド

ウィンドウの制御

bgcolor()

bgpic()

clearscreen()

resetscreen()

screensize()

setworldcoordinates()

アニメーションの制御

delay()

tracer()

update()

スクリーンイベントを利用する

listen()

onkey() | onkeyrelease()

onkeypress()

onclick() | onscreenclick()

ontimer()

mainloop() | done()

設定と特殊なメソッド

mode()

colormode()

getcanvas()

getshapes()

register_shape() | addshape()

turtles()

window_height()

window_width()

入力メソッド

textinput()

numinput()

Screen 独自のメソッド

bye()

exitonclick()

setup()

title()

RawTurtle/Turtle のメソッドと対応する関数

この節のほとんどの例では turtle という名前の Turtle インスタンスを使います。

Turtle の動き

turtle.forward(distance)

turtle.fd(distance)

パラメータ:

distance -- 数 (整数または浮動小数点数)

タートルが頭を向けている方へ、タートルを距離 distance だけ前進させます。

>>> turtle.position()
(0.00,0.00)
>>> turtle.forward(25)
>>> turtle.position()
(25.00,0.00)
>>> turtle.forward(-75)
>>> turtle.position()
(-50.00,0.00)

turtle.back(distance)

turtle.bk(distance)

turtle.backward(distance)

パラメータ:

distance -- 数

タートルが頭を向けている方と反対方向へ、タートルを距離 distance だけ後退させます。 タートルの向きは変えません。

>>> turtle.position()
(0.00,0.00)
>>> turtle.backward(30)
>>> turtle.position()
(-30.00,0.00)

turtle.right(angle)

turtle.rt(angle)

パラメータ:

angle -- 数 (整数または浮動小数点数)

タートルを angle 単位だけ右に回します。 (単位のデフォルトは度ですが、 degrees() と radians() 関数を使って設定できます。) 角度の向きはタートルのモードによって意味が変わります。 mode() を参照してください。

>>> turtle.heading()
22.0
>>> turtle.right(45)
>>> turtle.heading()
337.0

turtle.left(angle)

turtle.lt(angle)

パラメータ:

angle -- 数 (整数または浮動小数点数)

タートルを angle 単位だけ左に回します。 (単位のデフォルトは度ですが、 degrees() と radians() 関数を使って設定できます。) 角度の向きはタートルのモードによって意味が変わります。 mode() を参照してください。

>>> turtle.heading()
22.0
>>> turtle.left(45)
>>> turtle.heading()
67.0

turtle.goto(x, y=None)

turtle.setpos(x, y=None)

turtle.setposition(x, y=None)

パラメータ:

x -- 数または数のペア/ベクトル

y -- 数または None

y が None の場合、 x は座標のペアかまたは Vec2D (たとえば pos() で返されます) でなければなりません。

タートルを指定された絶対位置に移動します。ペンが下りていれば線を引きます。タートルの向きは変わりません。

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

turtle.teleport(x, y=None, *, fill_gap=False)

パラメータ:

x -- 数または None

y -- 数または None

fill_gap -- ブール値

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

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

Added in version 3.12.

turtle.setx(x)

パラメータ:

x -- 数 (整数または浮動小数点数)

タートルの第一座標を x にします。第二座標は変わりません。

>>> turtle.position()
(0.00,240.00)
>>> turtle.setx(10)
>>> turtle.position()
(10.00,240.00)

turtle.sety(y)

パラメータ:

y -- 数 (整数または浮動小数点数)

タートルの第二座標を y にします。第一座標は変わりません。

>>> turtle.position()
(0.00,40.00)
>>> turtle.sety(-10)
>>> turtle.position()
(0.00,-10.00)

turtle.setheading(to_angle)

turtle.seth(to_angle)

パラメータ:

to_angle -- 数 (整数または浮動小数点数)

タートルの向きを to_angle に設定します。以下はよく使われる方向を度で表わしたものです:

標準モード

logo モード

0 - 東

0 - 北

90 - 北

90 - 東

180 - 西

180 - 南

270 - 南

270 - 西

>>> turtle.setheading(90)
>>> turtle.heading()
90.0

turtle.home()

タートルを原点 -- 座標 (0, 0) -- に移動し、向きを開始方向に設定します (開始方向はモードに依って違います。 mode() を参照してください)。

>>> turtle.heading()
90.0
>>> turtle.position()
(0.00,-10.00)
>>> turtle.home()
>>> turtle.position()
(0.00,0.00)
>>> turtle.heading()
0.0

turtle.circle(radius, extent=None, steps=None)

パラメータ:

radius -- 数

extent -- 数 (または None)

steps -- 整数 (または None)

半径 radius の円を描きます。中心はタートルの左 radius ユニットの点です。 extent -- 角度です -- は円のどの部分を描くかを決定します。 extent が与えられなければ、デフォルトで完全な円になります。 extent が完全な円でない場合は、弧の一つの端点は、現在のペンの位置です。 radius が正の場合、弧は反時計回りに描かれます。そうでなければ、時計回りです。最後にタートルの向きが extent 分だけ変わります。

円は内接する正多角形で近似されます。 steps でそのために使うステップ数を決定します。この値は与えられなければ自動的に計算されます。また、これを正多角形の描画に利用することもできます。

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

turtle.dot(size=None, *color)

パラメータ:

size -- 1 以上の整数 (与えられる場合には)

color -- 色を表わす文字列またはタプル

直径 size の丸い点を color で指定された色で描きます。 size が与えられなかった場合、pensize+4 と 2*pensize の大きい方が使われます。

>>> turtle.home()
>>> turtle.dot()
>>> turtle.fd(50); turtle.dot(20, "blue"); turtle.fd(50)
>>> turtle.position()
(100.00,-0.00)
>>> turtle.heading()
0.0

turtle.stamp()

キャンバス上の現在タートルがいる位置にタートルの姿のハンコを押します。そのハンコに対して stamp_id が返されますが、これを使うと後で clearstamp(stamp_id) のように呼び出して消すことができます。

>>> turtle.color("blue")
>>> stamp_id = turtle.stamp()
>>> turtle.fd(50)

turtle.clearstamp(stampid)

パラメータ:

stampid -- 整数で、先立つ stamp() 呼出しで返された値でなければなりません

stampid に対応するハンコを消します。

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

turtle.clearstamps(n=None)

パラメータ:

n -- 整数 (または None)

全ての、または最初の/最後の n 個のハンコを消します。 n が None の場合、全てのハンコを消します。 n が正の場合には最初の n 個、 n が負の場合には最後の n 個を消します。

>>> for i in range(8):
...     unused_stamp_id = turtle.stamp()
...     turtle.fd(30)
>>> turtle.clearstamps(2)
>>> turtle.clearstamps(-2)
>>> turtle.clearstamps()

turtle.undo()

最後の(繰り返すことにより複数の)タートルの動きを取り消します。取り消しできる動きの最大数は undobuffer のサイズによって決まります。

>>> for i in range(4):
...     turtle.fd(50); turtle.lt(80)
...
>>> for i in range(8):
...     turtle.undo()

turtle.speed(speed=None)

パラメータ:

speed -- 0 から 10 までの整数またはスピードを表わす文字列(以下の説明を参照)

タートルのスピードを 0 から 10 までの範囲の整数に設定します。引数が与えられない場合は現在のスピードを返します。

与えられた数字が 10 より大きかったり 0.5 より小さかったりした場合は、スピードは 0 になります。スピードを表わす文字列は次のように数字に変換されます:

"fastest": 0

"fast": 10

"normal": 6

"slow": 3

"slowest": 1

1 から 10 までのスピードを上げていくにつれて線を描いたりタートルが回ったりするアニメーションがだんだん速くなります。

注意: speed = 0 はアニメーションを無くします。forward/backward ではタートルがジャンプし、left/right では瞬時に方向を変えます。

>>> turtle.speed()
3
>>> turtle.speed('normal')
>>> turtle.speed()
6
>>> turtle.speed(9)
>>> turtle.speed()
9

Turtle の状態を知る

turtle.position()

turtle.pos()

タートルの現在位置を (Vec2D のベクトルとして) 返します。

>>> turtle.pos()
(440.00,-0.00)

turtle.towards(x, y=None)

パラメータ:

x -- 数または数のペア/ベクトルまたはタートルのインスタンス

y -- x が数ならば数、そうでなければ None

タートルの位置から指定された (x,y) への直線の角度を返します。この値はタートルの開始方向にそして開始方向はモード ("standard"/"world" または "logo") に依存します。

>>> turtle.goto(10, 10)
>>> turtle.towards(0,0)
225.0

turtle.xcor()

タートルの x 座標を返します。

>>> turtle.home()
>>> turtle.left(50)
>>> turtle.forward(100)
>>> turtle.pos()
(64.28,76.60)
>>> print(round(turtle.xcor(), 5))
64.27876

turtle.ycor()

タートルの y 座標を返します。

>>> turtle.home()
>>> turtle.left(60)
>>> turtle.forward(100)
>>> print(turtle.pos())
(50.00,86.60)
>>> print(round(turtle.ycor(), 5))
86.60254

turtle.heading()

タートルの現在の向きを返します (返される値はタートルのモードに依存します。 mode() を参照してください)。

>>> turtle.home()
>>> turtle.left(67)
>>> turtle.heading()
67.0

turtle.distance(x, y=None)

パラメータ:

x -- 数または数のペア/ベクトルまたはタートルのインスタンス

y -- x が数ならば数、そうでなければ None

タートルから与えられた (x,y) あるいはベクトルあるいは渡されたタートルへの距離を、タートルのステップを単位として測った値を返します。

>>> turtle.home()
>>> turtle.distance(30,40)
50.0
>>> turtle.distance((30,40))
50.0
>>> joe = Turtle()
>>> joe.forward(77)
>>> turtle.distance(joe)
77.0

設定と計測

turtle.degrees(fullcircle=360.0)

パラメータ:

fullcircle -- 数

角度を計る単位「度」を、円周を何等分するかという値に指定します。デフォルトは360等分で通常の意味での度です。

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

turtle.radians()

角度を計る単位をラジアンにします。 degrees(2*math.pi) と同じ意味です。

>>> turtle.home()
>>> turtle.left(90)
>>> turtle.heading()
90.0
>>> turtle.radians()
>>> turtle.heading()
1.5707963267948966

Pen の制御

描画状態

turtle.pendown()

turtle.pd()

turtle.down()

ペンを下ろします -- 動くと線が引かれます。

turtle.penup()

turtle.pu()

turtle.up()

ペンを上げます -- 動いても線は引かれません。

turtle.pensize(width=None)

turtle.width(width=None)

パラメータ:

width -- 正の数

線の太さを width にするか、または現在の太さを返します。resizemode が "auto" でタートルの形が多角形の場合、その多角形も同じ太さで描画されます。引数が渡されなければ、現在の pensize が返されます。

>>> turtle.pensize()
1
>>> turtle.pensize(10)   # from here on lines of width 10 are drawn

turtle.pen(pen=None, **pendict)

パラメータ:

pen -- 以下にリストされたキーをもった辞書

pendict -- 以下にリストされたキーをキーワードとするキーワード引数

ペンの属性を "pen-dictionary" に以下のキー/値ペアで設定するかまたは返します:

"shown": True/False

"pendown": True/False

"pencolor": 色文字列または色タプル

"fillcolor": 色文字列または色タプル

"pensize": 正の数

"speed": 0 から 10 までの整数

"resizemode": "auto" または "user" または "noresize"

"stretchfactor": (正の数, 正の数)

"outline": 正の数

"tilt": 数

この辞書を以降の pen() 呼出しに渡して以前のペンの状態に復旧することができます。さらに一つ以上の属性をキーワード引数として渡すこともできます。一つの文で幾つものペンの属性を設定するのに使えます。

>>> 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', ''), ('outline', 1), ('pencolor', 'yellow')]
>>> turtle.pen(penstate, fillcolor="green")
>>> sorted(turtle.pen().items())[:3]
[('fillcolor', 'green'), ('outline', 1), ('pencolor', 'red')]

turtle.isdown()

もしペンが下りていれば True を、上がっていれば False を返します。

>>> turtle.penup()
>>> turtle.isdown()
False
>>> turtle.pendown()
>>> turtle.isdown()
True

色の制御

turtle.pencolor(*args)

ペンの色(pencolor)を設定するかまたは返します。

4種類の入力形式が受け入れ可能です:

pencolor()

現在のペンの色を色指定文字列またはタプルで返します (例を見て下さい)。次の color/pencolor/fillcolor の呼び出しへの入力に使うこともあるでしょう。

pencolor(colorstring)

ペンの色を colorstring に設定します。その値は Tk の色指定文字列で、 "red", "yellow", "#33cc8c" のような文字列です。

pencolor((r, g, b))

ペンの色を r, g, b のタプルで表された RGB の色に設定します。各 r, g, b は 0 から colormode の間の値でなければなりません。ここで colormode は 1.0 か 255 のどちらかです (colormode() を参照)。

pencolor(r, g, b)

ペンの色を r, g, b で表された RGB の色に設定します。各 r, g, b は 0 から colormode の間の値でなければなりません。

タートルの形(turtleshape)が多角形の場合、多角形の外側が新しく設定された色で描かれます。

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

turtle.fillcolor(*args)

塗りつぶしの色(fillcolor)を設定するかまたは返します。

4種類の入力形式が受け入れ可能です:

fillcolor()

現在の塗りつぶしの色を色指定文字列またはタプルで返します (例を見て下さい)。次の color/pencolor/fillcolor の呼び出しへの入力に使うこともあるでしょう。

fillcolor(colorstring)

塗りつぶしの色を colorstring に設定します。その値は Tk の色指定文字列で、 "red", "yellow", "#33cc8c" のような文字列です。

fillcolor((r, g, b))

塗りつぶしの色を r, g, b のタプルで表された RGB の色に設定します。各 r, g, b は 0 から colormode の間の値でなければなりません。ここで colormode は 1.0 か 255 のどちらかです (colormode() を参照)。

fillcolor(r, g, b)

塗りつぶしの色を r, g, b で表された RGB の色に設定します。各 r, g, b は 0 から colormode の間の値でなければなりません。

タートルの形(turtleshape)が多角形の場合、多角形の内側が新しく設定された色で描かれます。

>>> turtle.fillcolor("violet")
>>> turtle.fillcolor()
'violet'
>>> turtle.pencolor()
(50.0, 193.0, 143.0)
>>> turtle.fillcolor((50, 193, 143))  # Integers, not floats
>>> turtle.fillcolor()
(50.0, 193.0, 143.0)
>>> turtle.fillcolor('#ffffff')
>>> turtle.fillcolor()
(255.0, 255.0, 255.0)

turtle.color(*args)

ペンの色(pencolor)と塗りつぶしの色(fillcolor)を設定するかまたは返します。

いくつかの入力形式が受け入れ可能です。形式ごとに 0 から 3 個の引数を以下のように使います:

color()

現在のペンの色と塗りつぶしの色を pencolor() および fillcolor() で返される色指定文字列またはタプルのペアで返します。

color(colorstring), color((r,g,b)), color(r,g,b)

pencolor() の入力と同じですが、塗りつぶしの色とペンの色、両方を与えられた値に設定します。

color(colorstring1, colorstring2), color((r1,g1,b1), (r2,g2,b2))

pencolor(colorstring1) および fillcolor(colorstring2) を呼び出すのと等価です。もう一つの入力形式についても同様です。

タートルの形(turtleshape)が多角形の場合、多角形の内側も外側も新しく設定された色で描かれます。

>>> turtle.color("red", "green")
>>> turtle.color()
('red', 'green')
>>> color("#285078", "#a0c8f0")
>>> color()
((40.0, 80.0, 120.0), (160.0, 200.0, 240.0))

こちらも参照: スクリーンのメソッド colormode() 。

塗りつぶし

turtle.filling()

Return fillstate (True if filling, False else).

>>> turtle.begin_fill()
>>> if turtle.filling():
...    turtle.pensize(5)
... else:
...    turtle.pensize(3)

turtle.begin_fill()

To be called just before drawing a shape to be filled.

turtle.end_fill()

最後に呼び出された 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.

>>> turtle.color("black", "red")
>>> turtle.begin_fill()
>>> turtle.circle(80)
>>> turtle.end_fill()

さらなる描画の制御

turtle.reset()

タートルの描いたものをスクリーンから消し、タートルを中心に戻して、全ての変数をデフォルト値に設定し直します。

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

turtle.clear()

タートルの描いたものをスクリーンから消します。タートルは動かしません。タートルの状態と位置、それに他のタートルたちの描いたものは影響を受けません。

turtle.write(arg, move=False, align='left', font=('Arial', 8, 'normal'))

パラメータ:

arg -- TurtleScreen に書かれるオブジェクト

move -- True/False

align -- 文字列 "left", "center", right" のどれか

font -- 三つ組み (fontname, fontsize, fonttype)

文字を書きます— arg の文字列表現を、現在のタートルの位置に、 align ("left", "center", "right" のどれか) に従って、 与えられたフォントで。 もし move が真ならば、ペンは書いた文の右下隅に移動します。 デフォルトでは、 move は False です。

>>> turtle.write("Home = ", True, align="center")
>>> turtle.write((0,0), True)

タートルの状態

可視性

turtle.hideturtle()

turtle.ht()

タートルを見えなくします。 複雑な図を描いている途中、タートルが見えないようにするのは良い考えです。 というのもタートルを隠すことで描画が目に見えて速くなるからです。

>>> turtle.hideturtle()

turtle.showturtle()

turtle.st()

タートルが見えるようにします。

>>> turtle.showturtle()

turtle.isvisible()

タートルが見えている状態ならば True を、隠されていれば False を返します。

>>> turtle.hideturtle()
>>> turtle.isvisible()
False
>>> turtle.showturtle()
>>> turtle.isvisible()
True

見た目

turtle.shape(name=None)

パラメータ:

name -- 形の名前(shapename)として正しい文字列

タートルの形を与えられた名前(name)の形に設定するか、もしくは名前が与えられなければ現在の形の名前を返します。 name という名前の形は TurtleScreen の形の辞書に載っていなければなりません。最初は次の多角形が載っています: "arrow", "turtle", "circle", "square", "triangle", "classic"。形についての扱いを学ぶには Screen のメソッド register_shape() を参照して下さい。

>>> turtle.shape()
'classic'
>>> turtle.shape("turtle")
>>> turtle.shape()
'turtle'

turtle.resizemode(rmode=None)

パラメータ:

rmode -- 文字列 "auto", "user", "noresize" のどれか

サイズ変更のモード(resizemode)を "auto", "user", "noresize" のどれかに設定します。もし rmode が与えられなければ、現在のサイズ変更モードを返します。それぞれのサイズ変更モードは以下の効果を持ちます:

"auto": ペンのサイズに対応してタートルの見た目を調整します。

"user": 伸長係数(stretchfactor)およびアウトライン幅(outlinewidth)の値に対応してタートルの見た目を調整します。これらの値は shapesize() で設定します。

"noresize": タートルの見た目を調整しません。

resizemode("user") は shapesize() に引数を渡したときに呼び出されます。

>>> turtle.resizemode()
'noresize'
>>> turtle.resizemode("auto")
>>> turtle.resizemode()
'auto'

turtle.shapesize(stretch_wid=None, stretch_len=None, outline=None)

turtle.turtlesize(stretch_wid=None, stretch_len=None, outline=None)

パラメータ:

stretch_wid -- 正の数

stretch_len -- 正の数

outline -- 正の数

ペンの属性 x/y-伸長係数および/またはアウトラインを返すかまたは設定します。サイズ変更のモードは "user" に設定されます。サイズ変更のモードが "user" に設定されたときかつそのときに限り、タートルは伸長係数(stretchfactor)に従って伸長されて表示されます。 stretch_wid は進行方向に直交する向きの伸長係数で、 stretch_len は進行方向に沿ったの伸長係数、 outline は形のアウトラインの幅を決めるものです。

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

turtle.shearfactor(shear=None)

パラメータ:

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.

>>> turtle.shape("circle")
>>> turtle.shapesize(5,2)
>>> turtle.shearfactor(0.5)
>>> turtle.shearfactor()
0.5

turtle.tilt(angle)

パラメータ:

angle -- 数

タートルの形(turtleshape)を現在の傾斜角から角度(angle)だけ回転します。このときタートルの進む方向は 変わりません 。

>>> turtle.reset()
>>> turtle.shape("circle")
>>> turtle.shapesize(5,2)
>>> turtle.tilt(30)
>>> turtle.fd(50)
>>> turtle.tilt(30)
>>> turtle.fd(50)

turtle.settiltangle(angle)

パラメータ:

angle -- 数

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

>>> turtle.reset()
>>> turtle.shape("circle")
>>> turtle.shapesize(5,2)
>>> turtle.settiltangle(45)
>>> turtle.fd(50)
>>> turtle.settiltangle(-45)
>>> turtle.fd(50)

バージョン 3.1 で非推奨.

turtle.tiltangle(angle=None)

パラメータ:

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

>>> turtle.reset()
>>> turtle.shape("circle")
>>> turtle.shapesize(5,2)
>>> turtle.tilt(45)
>>> turtle.tiltangle()
45.0

turtle.shapetransform(t11=None, t12=None, t21=None, t22=None)

パラメータ:

t11 -- a number (optional)

t12 -- a number (optional)

t21 -- a number (optional)

t12 -- a number (optional)

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.

>>> turtle = Turtle()
>>> turtle.shape("square")
>>> turtle.shapesize(4,2)
>>> turtle.shearfactor(-0.5)
>>> turtle.shapetransform()
(4.0, -1.0, -0.0, 2.0)

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.

>>> turtle.shape("square")
>>> turtle.shapetransform(4, -1, 0, 2)
>>> turtle.get_shapepoly()
((50, -20), (30, 20), (-50, 20), (-30, -20))

イベントを利用する

turtle.onclick(fun, btn=1, add=None)

パラメータ:

fun -- 2引数の関数でキャンバスのクリックされた点の座標を引数として呼び出されるものです

btn -- マウスボタンの番号、デフォルトは 1 (左マウスボタン)

add -- True または False -- True ならば、 新しい束縛が追加されますが、そうでなければ、 以前の束縛を置き換えます。

fun をタートルのマウスクリック(mouse-click)イベントに束縛します。 fun が None ならば、既存の束縛が取り除かれます。無名タートル、つまり手続き的なやり方の例です:

>>> def turn(x, y):
...     left(180)
...
>>> onclick(turn)  # Now clicking into the turtle will turn it.
>>> onclick(None)  # event-binding will be removed

turtle.onrelease(fun, btn=1, add=None)

パラメータ:

fun -- 2引数の関数でキャンバスのクリックされた点の座標を引数として呼び出されるものです

btn -- マウスボタンの番号、デフォルトは 1 (左マウスボタン)

add -- True または False -- True ならば、 新しい束縛が追加されますが、そうでなければ、 以前の束縛を置き換えます。

fun をタートルのマウスボタンリリース(mouse-button-release)イベントに束縛します。 fun が None ならば、既存の束縛が取り除かれます。

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

turtle.ondrag(fun, btn=1, add=None)

パラメータ:

fun -- 2引数の関数でキャンバスのクリックされた点の座標を引数として呼び出されるものです

btn -- マウスボタンの番号、デフォルトは 1 (左マウスボタン)

add -- True または False -- True ならば、 新しい束縛が追加されますが、そうでなければ、 以前の束縛を置き換えます。

fun をタートルのマウスムーブ(mouse-move)イベントに束縛します。 fun が None ならば、既存の束縛が取り除かれます。

注意: 全てのマウスムーブイベントのシーケンスに先立ってマウスクリックイベントが起こります。

>>> turtle.ondrag(turtle.goto)

この後、タートルをクリックしてドラッグするとタートルはスクリーン上を動きそれによって(ペンが下りていれば)手書きの線ができあがります。

特別な Turtle のメソッド

turtle.begin_poly()

多角形の頂点の記録を開始します。現在のタートル位置が最初の頂点です。

turtle.end_poly()

多角形の頂点の記録を停止します。現在のタートル位置が最後の頂点です。この頂点が最初の頂点と結ばれます。

turtle.get_poly()

最後に記録された多角形を返します。

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

turtle.clone()

位置、向きその他のプロパティがそっくり同じタートルのクローンを作って返します。

>>> mick = Turtle()
>>> joe = mick.clone()

turtle.getturtle()

turtle.getpen()

Turtle オブジェクトそのものを返します。唯一の意味のある使い方: 無名タートルを返す関数として使う:

>>> pet = getturtle()
>>> pet.fd(50)
>>> pet
<turtle.Turtle object at 0x...>

turtle.getscreen()

タートルが描画中の TurtleScreen オブジェクトを返します。 TurtleScreen のメソッドをそのオブジェクトに対して呼び出すことができます。

>>> ts = turtle.getscreen()
>>> ts
<turtle._Screen object at 0x...>
>>> ts.bgcolor("pink")

turtle.setundobuffer(size)

パラメータ:

size -- 整数または None

アンドゥバッファを設定または無効化します。 size が整数ならばそのサイズの空のアンドゥバッファを用意します。 size の値はタートルのアクションを何度 undo() メソッド/関数で取り消せるかの最大数を与えます。 size が None ならば、アンドゥバッファは無効化されます。

>>> turtle.setundobuffer(42)

turtle.undobufferentries()

アンドゥバッファのエントリー数を返します。

>>> while undobufferentries():
...     undo()

Compound shapes

合成されたタートルの形、つまり幾つかの色の違う多角形から成るような形を使うには、以下のように補助クラス Shape を直接使わなければなりません:

タイプ "compound" の空の Shape オブジェクトを作ります。

addcomponent() メソッドを使って、好きなだけここにコンポーネントを追加します。

例えば:

>>> 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")

こうして作った Shape を Screen の形のリスト(shapelist) に追加して使います:

>>> register_shape("myshape", s)
>>> shape("myshape")

注釈

Shape クラスは register_shape() の内部では違った使われ方をします。アプリケーションを書く人が Shape クラスを扱わなければならないのは、上で示したように合成された形を使うとき だけ です！

TurtleScreen/Screen のメソッドと対応する関数

この節のほとんどの例では screen という名前の TurtleScreen インスタンスを使います。

ウィンドウの制御

turtle.bgcolor(*args)

パラメータ:

args -- 色文字列または 0 から colormode の範囲の数3つ、 またはそれを三つ組みにしたもの

TurtleScreen の背景色を設定するかまたは返します。

>>> screen.bgcolor("orange")
>>> screen.bgcolor()
'orange'
>>> screen.bgcolor("#800080")
>>> screen.bgcolor()
(128.0, 0.0, 128.0)

turtle.bgpic(picname=None)

パラメータ:

picname -- 文字列で gif ファイルの名前 "nopic" 、または None

背景の画像を設定するかまたは現在の背景画像(backgroundimage)の名前を返します。 picname がファイル名ならば、その画像を背景に設定します。 picname が "nopic" ならば、(もしあれば)背景画像を削除します。 picname が None ならば、現在の背景画像のファイル名を返します。

>>> screen.bgpic()
'nopic'
>>> screen.bgpic("landscape.gif")
>>> screen.bgpic()
"landscape.gif"

turtle.clear()

注釈

この TurtleScreen メソッドはグローバル関数としては clearscreen という名前でだけ使えます。グローバル関数 clear は Turtle メソッドの clear から派生した別ものです。

turtle.clearscreen()

全ての図形と全てのタートルを TurtleScreen から削除します。そして空になった TurtleScreen をリセットして初期状態に戻します: 白い背景、背景画像もイベント束縛もなく、トレーシングはオンです。

turtle.reset()

注釈

この TurtleScreen メソッドはグローバル関数としては resetscreen という名前でだけ使えます。グローバル関数 reset は Turtle メソッドの reset から派生した別ものです。

turtle.resetscreen()

スクリーン上の全てのタートルをリセットしその初期状態に戻します。

turtle.screensize(canvwidth=None, canvheight=None, bg=None)

パラメータ:

canvwidth -- 正の整数でピクセル単位の新しいキャンバス幅(canvaswidth)

canvheight -- 正の整数でピクセル単位の新しいキャンバス高さ(canvasheight)

bg -- 色文字列または色タプルで新しい背景色

引数が渡されなければ、現在の (キャンバス幅, キャンバス高さ) を返します。そうでなければタートルが描画するキャンバスのサイズを変更します。描画ウィンドウには影響しません。キャンバスの隠れた部分を見るためにはスクロールバーを使って下さい。このメソッドを使うと、以前はキャンバスの外にあったそうした図形の一部を見えるようにすることができます。

>>> screen.screensize()
(400, 300)
>>> screen.screensize(2000,1500)
>>> screen.screensize()
(2000, 1500)

# 逃げ出してしまったタートルを探すためとかね ;-)

turtle.setworldcoordinates(llx, lly, urx, ury)

パラメータ:

llx -- 数でキャンバスの左下隅の x-座標

lly -- 数でキャンバスの左下隅の y-座標

urx -- 数でキャンバスの右上隅の x-座標

ury -- 数でキャンバスの右上隅の y-座標

ユーザー定義座標系を準備し必要ならばモードを "world" に切り替えます。この動作は screen.reset() を伴います。すでに "world" モードになっていた場合、全ての図形は新しい座標に従って再描画されます。

重要なお知らせ: ユーザー定義座標系では角度が歪むかもしれません。

>>> screen.reset()
>>> screen.setworldcoordinates(-50,-7.5,50,7.5)
>>> for _ in range(72):
...     left(10)
...
>>> for _ in range(8):
...     left(45); fd(2)   # a regular octagon

アニメーションの制御

turtle.delay(delay=None)

パラメータ:

delay -- 正の整数

描画の遅延(delay)をミリ秒単位で設定するかまたはその値を返します。(これは概ね引き続くキャンバス更新の時間間隔です。) 遅延が大きくなると、アニメーションは遅くなります。

オプション引数:

>>> screen.delay()
10
>>> screen.delay(5)
>>> screen.delay()
5

turtle.tracer(n=None, delay=None)

パラメータ:

n -- 非負整数

delay -- 非負整数

タートルのアニメーションをオン・オフし、描画更新の遅延を設定します。 n が与えられた場合、通常のスクリーン更新のうち 1/n しか実際に実行されません。 (複雑なグラフィックスの描画を加速するのに使えます。) 引数なしで呼び出されたなら、現在保存されている n の値を返します。二つ目の引数は遅延の値を設定します(delay() も参照)。

>>> screen.tracer(8, 25)
>>> dist = 2
>>> for i in range(200):
...     fd(dist)
...     rt(90)
...     dist += 2

turtle.update()

TurtleScreen の更新を実行します。トレーサーがオフの時に使われます。

RawTurtle/Turtle のメソッド speed() も参照して下さい。

スクリーンイベントを利用する

turtle.listen(xdummy=None, ydummy=None)

TurtleScreen に(キー・イベントを収集するために)フォーカスします。ダミー引数は listen() を onclick メソッドに渡せるようにするためのものです。

turtle.onkey(fun, key)

turtle.onkeyrelease(fun, key)

パラメータ:

fun -- 引数なしの関数または None

key -- 文字列: キー (例 "a") またはキー・シンボル (例 "space")

fun を指定されたキーのキーリリース(key-release)イベントに束縛します。 fun が None ならばイベント束縛は除かれます。注意: キー・イベントを登録できるようにするためには TurtleScreen はフォーカスを持っていないとなりません(listen() を参照)。

>>> def f():
...     fd(50)
...     lt(60)
...
>>> screen.onkey(f, "Up")
>>> screen.listen()

turtle.onkeypress(fun, key=None)

パラメータ:

fun -- 引数なしの関数または None

key -- 文字列: キー (例 "a") またはキー・シンボル (例 "space")

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 listen().)

>>> def f():
...     fd(50)
...
>>> screen.onkey(f, "Up")
>>> screen.listen()

turtle.onclick(fun, btn=1, add=None)

turtle.onscreenclick(fun, btn=1, add=None)

パラメータ:

fun -- 2引数の関数でキャンバスのクリックされた点の座標を引数として呼び出されるものです

btn -- マウスボタンの番号、デフォルトは 1 (左マウスボタン)

add -- True または False -- True ならば、 新しい束縛が追加されますが、そうでなければ、 以前の束縛を置き換えます。

fun をタートルのマウスクリック(mouse-click)イベントに束縛します。 fun が None ならば、既存の束縛が取り除かれます。

Example for a screen という名の TurtleScreen インスタンスと turtle という名前の Turtle インスタンスの例:

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

注釈

この TurtleScreen メソッドはグローバル関数としては onscreenclick という名前でだけ使えます。グローバル関数 onclick は Turtle メソッドの onclick から派生した別ものです。

turtle.ontimer(fun, t=0)

パラメータ:

fun -- 引数なし関数

t -- 数 >= 0

t ミリ秒後に fun を呼び出すタイマーを仕掛けます。

>>> running = True
>>> def f():
...     if running:
...         fd(50)
...         lt(60)
...         screen.ontimer(f, 250)
>>> f()   ### makes the turtle march around
>>> running = False

turtle.mainloop()

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.

>>> screen.mainloop()

入力メソッド

turtle.textinput(title, prompt)

パラメータ:

title -- string

prompt -- string

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

>>> screen.textinput("NIM", "Name of first player:")

turtle.numinput(title, prompt, default=None, minval=None, maxval=None)

パラメータ:

title -- string

prompt -- string

default -- number (optional)

minval -- number (optional)

maxval -- number (optional)

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

>>> screen.numinput("Poker", "Your stakes:", 1000, minval=10, maxval=10000)

設定と特殊なメソッド

turtle.mode(mode=None)

パラメータ:

mode -- 文字列 "standard", "logo", "world" のいずれか

タートルのモード("standard", "logo", "world" のいずれか)を設定してリセットします。モードが渡されなければ現在のモードが返されます。

モード "standard" は古い turtle 互換です。モード "logo" は Logo タートルグラフィックスとほぼ互換です。モード "world" はユーザーの定義した「世界座標(world coordinates)」を使います。 重要なお知らせ: このモードでは x/y 比が 1 でないと角度が歪むかもしれません。

モード

タートルの向きの初期値

正の角度

"standard"

右 (東) 向き

反時計回り

"logo"

上 (北) 向き

時計回り

>>> mode("logo")   # resets turtle heading to north
>>> mode()
'logo'

turtle.colormode(cmode=None)

パラメータ:

cmode -- 1.0 か 255 のどちらかの値

色モード(colormode)を返すか、または 1.0 か 255 のどちらかの値に設定します。設定した後は、色トリプルの r, g, b 値は 0 から cmode の範囲になければなりません。

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

turtle.getcanvas()

この TurtleScreen の Canvas を返します。Tkinter の Canvas を使って何をするか知っている人には有用です。

>>> cv = screen.getcanvas()
>>> cv
<turtle.ScrolledCanvas object ...>

turtle.getshapes()

現在使うことのできる全てのタートルの形のリストを返します。

>>> screen.getshapes()
['arrow', 'blank', 'circle', ..., 'turtle']

turtle.register_shape(name, shape=None)

turtle.addshape(name, shape=None)

この関数を呼び出す三つの異なる方法があります:

name が gif ファイルの名前で shape が None: 対応する画像の形を取り込みます。

>>> screen.register_shape("turtle.gif")

注釈

画像の形はタートルが向きを変えても 回転しません ので、タートルがどちらを向いているか見ても判りません!

name が任意の文字列で shape が座標ペアのタプル: 対応する多角形を取り込みます。

>>> screen.register_shape("triangle", ((5,-3), (0,5), (-5,-3)))

name が任意の文字列で shape が (合成形の) Shape オブジェクト: 対応する合成形を取り込みます。

タートルの形を TurtleScreen の形リスト(shapelist)に加えます。このように登録された形だけが shape(shapename) コマンドに使えます。

turtle.turtles()

スクリーン上のタートルのリストを返します。

>>> for turtle in screen.turtles():
...     turtle.color("red")

turtle.window_height()

タートルウィンドウの高さを返します。

>>> screen.window_height()
480

turtle.window_width()

タートルウィンドウの幅を返します。

>>> screen.window_width()
640

Screen 独自のメソッド、TurtleScreen から継承したもの以外

turtle.bye()

タートルグラフィックス(turtlegraphics)のウィンドウを閉じます。

turtle.exitonclick()

スクリーン上のマウスクリックに bye() メソッドを束縛します。

設定辞書中の "using_IDLE" の値が False (デフォルトです) の場合、さらにメインループ(mainloop)に入ります。注意: もし IDLE が -n スイッチ(サブプロセスなし)付きで使われているときは、この値は turtle.cfg の中で True とされているべきです。この場合、IDLE のメインループもクライアントスクリプトから見てアクティブです。

turtle.setup(width=_CFG['width'], height=_CFG['height'], startx=_CFG['leftright'], starty=_CFG['topbottom'])

メインウィンドウのサイズとポジションを設定します。引数のデフォルト値は設定辞書に収められており、 turtle.cfg ファイルを通じて変更できます。

パラメータ:

width -- 整数ならばピクセル単位のサイズ、浮動小数点数ならばスクリーンに対する割合 (スクリーンの 50% がデフォルト)

height -- 整数ならばピクセル単位の高さ、浮動小数点数ならばスクリーンに対する割合 (スクリーンの 75% がデフォルト)

startx -- 正の数ならばスクリーンの左端からピクセル単位で測った開始位置、 負の数ならば右端から、None ならば水平方向に真ん中

starty -- 正の数ならばスクリーンの上端からピクセル単位で測った開始位置、 負の数ならば下端から、None ならば垂直方向に真ん中

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

turtle.title(titlestring)

パラメータ:

titlestring -- タートルグラフィックスウィンドウのタイトルバーに表示される文字列

ウインドウのタイトルを titlestring に設定します。

>>> screen.title("Welcome to the turtle zoo!")

Public classes

class turtle.RawTurtle(canvas)

class turtle.RawPen(canvas)

パラメータ:

canvas -- a tkinter.Canvas, a ScrolledCanvas or a TurtleScreen

タートルを作ります。タートルには上の「Turtle/RawTurtle のメソッド」で説明した全てのメソッドがあります。

class turtle.Turtle

RawTurtle のサブクラスで同じインターフェイスを持ちますが、最初に必要になったとき自動的に作られる Screen オブジェクトに描画します。

class turtle.TurtleScreen(cv)

パラメータ:

cv -- a tkinter.Canvas

上で説明した bgcolor() のようなスクリーン向けのメソッドを提供します。

class turtle.Screen

TurtleScreen のサブクラスで 4つのメソッドが加わっています 。

class turtle.ScrolledCanvas(master)

パラメータ:

master -- この ScrolledCanvas すなわちスクロールバーの付いた Tkinter canvas を収める Tkinter ウィジェット

タートルたちが遊び回る場所として自動的に ScrolledCanvas を提供する Screen クラスによって使われます。

class turtle.Shape(type_, data)

パラメータ:

type_ -- 文字列 "polygon", "image", "compound" のいずれか

形をモデル化するデータ構造。ペア (type_, data) は以下の仕様に従わなければなりません:

type_

data

"polygon"

多角形タプル、すなわち座標ペアのタプル

"image"

画像 (この形式は内部的にのみ使用されます!)

"compound"

None (合成形は addcomponent() メソッドを使って作らなければなりません)

addcomponent(poly, fill, outline=None)

パラメータ:

poly -- 多角形、すなわち数のペアのタプル

fill -- poly を塗りつぶす色

outline -- poly のアウトラインの色 (与えられた場合)

例:

>>> 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()

Compound shapes を参照。

class turtle.Vec2D(x, y)

2次元ベクトルのクラスで、タートルグラフィックスを実装するための補助クラス。タートルグラフィックスを使ったプログラムでも有用でしょう。タプルから派生しているので、ベクターはタプルです!

以下の演算が使えます (a, b はベクトル、 k は数):

a + b ベクトル和

a - b ベクトル差

a * b 内積

k * a および a * k スカラー倍

abs(a) a の絶対値

a.rotate(angle) 回転

説明

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 Turtle instance will automatically create a Screen instance if one is not already present.

Turtle is a subclass of 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 tkinter.Canvas, ScrolledCanvas or TurtleScreen.

TurtleScreen is the basic drawing surface for a turtle. Screen is a subclass of TurtleScreen, and includes some additional methods for managing its appearance (including size and title) and behaviour. TurtleScreen's constructor needs a tkinter.Canvas or a ScrolledCanvas as an argument.

The functional interface for turtle graphics uses the various methods of Turtle and TurtleScreen/Screen. Behind the scenes, a screen object is automatically created whenever a function derived from a 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.

ヘルプと設定

ヘルプの使い方

Screen と Turtle クラスのパブリックメソッドはドキュメント文字列で網羅的に文書化されていますので、Python のヘルプ機能を通じてオンラインヘルプとして利用できます:

IDLE を使っているときは、打ち込んだ関数/メソッド呼び出しのシグニチャとドキュメント文字列の一行目がツールチップとして表示されます。

help() をメソッドや関数に対して呼び出すとドキュメント文字列が表示されます:

>>> 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()

メソッドに由来する関数のドキュメント文字列は変更された形をとります:

>>> 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()

これらの変更されたドキュメント文字列はインポート時にメソッドから導出される関数定義と一緒に自動的に作られます。

ドキュメント文字列の翻訳

Screen と Turtle クラスのパブリックメソッドについて、キーがメソッド名で値がドキュメント文字列である辞書を作るユーティリティがあります。

turtle.write_docstringdict(filename='turtle_docstringdict')

パラメータ:

filename -- ファイル名として使われる文字列

ドキュメント文字列辞書(docstring-dictionary)を作って与えられたファイル名の Python スクリプトに書き込みます。この関数はわざわざ呼び出さなければなりません (タートルグラフィックスのクラスから使われることはありません)。ドキュメント文字列辞書は filename.py という Python スクリプトに書き込まれます。ドキュメント文字列の異なった言語への翻訳に対するテンプレートとして使われることを意図したものです。

もしあなたが(またはあなたの生徒さんが) turtle を自国語のオンラインヘルプ付きで使いたいならば、ドキュメント文字列を翻訳してできあがったファイルをたとえば turtle_docstringdict_german.py という名前で保存しなければなりません。

さらに turtle.cfg ファイルで適切な設定をしておけば、このファイルがインポート時に読み込まれて元の英語のドキュメント文字列を置き換えます。

この文書を書いている時点ではドイツ語とイタリア語のドキュメント文字列辞書が存在します。 ( glingl@aon.at にリクエストして下さい。)

Screen および Turtle の設定方法

初期デフォルト設定では古い turtle の見た目と振る舞いを真似るようにして、互換性を最大限に保つようにしています。

このモジュールの特性を反映した、あるいは個々人の必要性 (たとえばクラスルームでの使用)に合致した、異なった設定を使いたい場合、設定ファイル turtle.cfg を用意してインポート時に読み込ませその設定に従わせることができます。

初期設定は以下の turtle.cfg に対応します:

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

いくつかピックアップしたエントリーの短い説明:

最初の4行は Screen.setup メソッドの引数に当たります。

5行目6行目は Screen.screensize メソッドの引数に当たります。

shape は最初から用意されている形ならどれでも使えます(arrow, turtle など)。詳しくは help(shape) をお試し下さい。

塗りつぶしの色(fill color)を使いたくない(つまりタートルを透明にしたい)場合、 fillcolor = "" と書かなければなりません (しかし全ての空でない文字列は cfg ファイル中で引用符を付けてはいけません)。

タートルにその状態を反映させるためには resizemode = auto とします。

たとえば language = italian とするとドキュメント文字列辞書(docstringdict) として turtle_docstringdict_italian.py がインポート時に読み込まれます (もしそれがインポートパス、たとえば turtle と同じディレクトリにあれば)。

exampleturtle および examplescreen はこれらのオブジェクトのドキュメント文字列内での呼び名を決めます。メソッドのドキュメント文字列から関数のドキュメント文字列に変換する際に、これらの名前は取り除かれます。

using_IDLE: IDLE とその -n スイッチ(サブプロセスなし)を常用するならば、この値を True に設定して下さい。これにより exitonclick() がメインループ(mainloop)に入るのを阻止します。

turtle.cfg ファイルは turtle の保存されているディレクトリと現在の作業ディレクトリに追加的に存在し得ます。後者が前者の設定をオーバーライドします。

Lib/turtledemo ディレクトリにも turtle.cfg ファイルがあります。 デモを実際に(できればデモビュワーからでなく)実行してそこに書かれたものとその効果を学びましょう。

turtledemo --- デモスクリプト

turtledemo パッケージには一連のデモスクリプトが含まれています。これらのスクリプトは以下のように、付属のデモビューアを使用して実行および表示できます:

python -m turtledemo

あるいは、個別にデモスクリプトを実行できます。たとえば 、:

python -m turtledemo.bytedesign

turtledemo パッケージのディレクトリには次のものが含まれます:

ソースコードを眺めつつスクリプトを実行できるデモビュワー __main__.py 。

Multiple scripts demonstrating different features of the turtle module. Examples can be accessed via the Examples menu. They can also be run standalone.

設定ファイルの書き方や使い方の例として参考にできる turtle.cfg ファイル。

デモスクリプトは以下の通りです:

名前

説明

フィーチャー

bytedesign

複雑な古典的タートルグラフィックスパターン

tracer(), delay, update()

chaos

verhust 力学系のグラフ化, コンピュータの計算が常識的な予想に反する場合があることを示します。

世界座標系

clock

コンピュータの時間を示すアナログ時計

タートルが時計の針, ontimer

colormixer

r, g, b の実験

ondrag()

forest

3 breadth-first trees

randomization

fractalcurves

Hilbert & Koch 曲線

再帰

lindenmayer

民俗的数学 (インド kolams)

L-システム

minimal_hanoi

ハノイの塔

ハノイ盤として正方形のタートル (shape, shapesize)

nim

play the classical nim game with three heaps of sticks against the computer.

turtles as nimsticks, event driven (mouse, keyboard)

paint

超極小主義的描画プログラム

onclick()

peace

初歩的

turtle: 見た目とアニメーション

penrose

凧と矢による非周期的タイリング

stamp()

planet_and_moon

重力系のシミュレーション

合成形, Vec2D

rosette

タートルグラフィックスについての wikipedia の記事の例

clone(), undo()

round_dance

dancing turtles rotating pairwise in opposite direction

compound shapes, clone shapesize, tilt, get_shapepoly, update

sorting_animate

visual demonstration of different sorting methods

simple alignment, randomization

tree

(図形的) 幅優先木 (ジェネレータを使って)

clone()

two_canvases

simple design

turtles on two canvases

yinyang

もう一つの初歩的な例

circle()

楽しんでね!

python 2.6からの変更点

The methods Turtle.tracer, Turtle.window_width and Turtle.window_height have been eliminated. Methods with these names and functionality are now available only as methods of Screen. The functions derived from these remain available. (In fact already in Python 2.6 these methods were merely duplications of the corresponding TurtleScreen/Screen methods.)

The method Turtle.fill() has been eliminated. The behaviour of begin_fill() and end_fill() have changed slightly: now every filling process must be completed with an end_fill() call.

A method Turtle.filling has been added. It returns a boolean value: True if a filling process is under way, False otherwise. This behaviour corresponds to a fill() call without arguments in Python 2.6.

python 3.0からの変更点

The Turtle methods shearfactor(), shapetransform() and get_shapepoly() have been added. Thus the full range of regular linear transforms is now available for transforming turtle shapes. tiltangle() has been enhanced in functionality: it now can be used to get or set the tilt angle. settiltangle() has been deprecated.

The Screen method onkeypress() has been added as a complement to onkey(). As the latter binds actions to the key release event, an alias: onkeyrelease() was also added for it.

The method Screen.mainloop has been added, so there is no longer a need to use the standalone mainloop() function when working with Screen and Turtle objects.

Two input methods have been added: Screen.textinput and Screen.numinput. These pop up input dialogs and return strings and numbers respectively.

Two example scripts tdemo_nim.py and tdemo_round_dance.py have been added to the Lib/turtledemo directory.

cmd --- Support for line-oriented command interpreters

ソースコード: Lib/cmd.py [https://github.com/python/cpython/tree/3.12/Lib/cmd.py]

Cmd クラスでは、行指向のコマンドインタープリタを書くための簡単なフレームワークを提供します。テストハーネスや管理ツール、そして、後により洗練されたインターフェイスでラップするプロトタイプとして、こうしたインタープリタはよく役に立ちます。

class cmd.Cmd(completekey='tab', stdin=None, stdout=None)

Cmd インスタンス、あるいはサブクラスのインスタンスは、行指向のインタープリタ・フレームワークです。 Cmd 自身をインスタンス化することはありません。むしろ、 Cmd のメソッドを継承したり、アクションメソッドをカプセル化するために、あなたが自分で定義するインタープリタクラスのスーパークラスとしての便利です。

オプション引数 completekey は、補完キーの readline 名です。デフォルトは Tab です。 completekey が None でなく、 readline が利用できるならば、コマンド補完は自動的に行われます。

オプション引数の stdin と stdout には、Cmd またはそのサブクラスのインスタンスが入出力に使用するファイルオブジェクトを指定します。省略時には sys.stdin と sys.stdout が使用されます。

引数に渡した stdin を使いたい場合は、インスタンスの use_rawinput 属性を False にセットしてください。そうしないと stdin は無視されます。

Cmdオブジェクト

Cmd インスタンスは、次のメソッドを持ちます:

Cmd.cmdloop(intro=None)

プロンプトを繰り返し出力し、入力を受け取り、受け取った入力から取り去った先頭の語を解析し、その行の残りを引数としてアクションメソッドへディスパッチします。

オプションの引数は、最初のプロンプトの前に表示されるバナーあるいはイントロ用の文字列です (これはクラス属性 intro をオーバーライドします)。

readline モジュールがロードされているなら、入力は自動的に bash のような履歴リスト編集機能を受け継ぎます(例えば、 Control-P は直前のコマンドへのスクロールバック、 Control-N は次のものへ進む、 Control-F はカーソルを右へ非破壊的に進める、 Control-B はカーソルを非破壊的に左へ移動させる等)。

入力のファイル終端は、文字列 'EOF' として渡されます。

An interpreter instance will recognize a command name foo if and only if it has a method do_foo(). As a special case, a line beginning with the character '?' is dispatched to the method do_help(). As another special case, a line beginning with the character '!' is dispatched to the method do_shell() (if such a method is defined).

This method will return when the postcmd() method returns a true value. The stop argument to postcmd() is the return value from the command's corresponding do_*() method.

If completion is enabled, completing commands will be done automatically, and completing of commands args is done by calling complete_foo() with arguments text, line, begidx, and endidx. text is the string prefix we are attempting to match: all returned matches must begin with it. line is the current input line with leading whitespace removed, begidx and endidx are the beginning and ending indexes of the prefix text, which could be used to provide different completion depending upon which position the argument is in.

Cmd.do_help(arg)

All subclasses of Cmd inherit a predefined do_help(). This method, called with an argument 'bar', invokes the corresponding method help_bar(), and if that is not present, prints the docstring of do_bar(), if available. With no argument, do_help() lists all available help topics (that is, all commands with corresponding help_*() methods or commands that have docstrings), and also lists any undocumented commands.

Cmd.onecmd(str)

Interpret the argument as though it had been typed in response to the prompt. This may be overridden, but should not normally need to be; see the precmd() and postcmd() methods for useful execution hooks. The return value is a flag indicating whether interpretation of commands by the interpreter should stop. If there is a do_*() method for the command str, the return value of that method is returned, otherwise the return value from the default() method is returned.

Cmd.emptyline()

プロンプトに空行が入力されたときに呼び出されるメソッド。このメソッドがオーバーライドされていないなら、最後に入力された空行でないコマンドが繰り返されます。

Cmd.default(line)

コマンドの先頭の語が認識されないときに、入力行に対して呼び出されます。このメソッドがオーバーライドされていないなら、エラーメッセージを表示して戻ります。

Cmd.completedefault(text, line, begidx, endidx)

Method called to complete an input line when no command-specific complete_*() method is available. By default, it returns an empty list.

Cmd.columnize(list, displaywidth=80)

Method called to display a list of strings as a compact set of columns. Each column is only as wide as necessary. Columns are separated by two spaces for readability.

Cmd.precmd(line)

コマンド行 line が解釈実行される直前、しかし入力プロンプトが作られ表示された後に実行されるフックメソッド。このメソッドは Cmd 内のスタブであって、サブクラスでオーバーライドされるために存在します。戻り値は onecmd() メソッドが実行するコマンドとして使われます。 precmd() の実装では、コマンドを書き換えるかもしれないし、あるいは単に変更していない line を返すかもしれません。

Cmd.postcmd(stop, line)

コマンドディスパッチが終わった直後に実行されるフックメソッド。このメソッドは Cmd 内のスタブで、サブクラスでオーバーライドされるために存在します。 line は実行されたコマンド行で、 stop は postcmd() の呼び出しの後に実行を停止するかどうかを示すフラグです。これは onecmd() メソッドの戻り値です。このメソッドの戻り値は、 stop に対応する内部フラグの新しい値として使われます。偽を返すと、実行を続けます。

Cmd.preloop()

cmdloop() が呼び出されたときに一度だけ実行されるフックメソッド。このメソッドは Cmd 内のスタブであって、サブクラスでオーバーライドされるために存在します。

Cmd.postloop()

cmdloop() が戻る直前に一度だけ実行されるフックメソッド。このメソッドは Cmd 内のスタブであって、サブクラスでオーバーライドされるために存在します。

Cmd のサブクラスのインスタンスは、公開されたインスタンス変数をいくつか持っています:

Cmd.prompt

入力を求めるために表示されるプロンプト。

Cmd.identchars

コマンドの先頭の語として受け入れられる文字の文字列。

Cmd.lastcmd

最後の空でないコマンド接頭辞。

Cmd.cmdqueue

キューに入れられた入力行のリスト。cmdqueue リストは新たな入力が必要な際に cmdloop() 内でチェックされます; これが空でない場合、その要素は、あたかもプロンプトから入力されたかのように順に処理されます。

Cmd.intro

イントロあるいはバナーとして表示される文字列。 cmdloop() メソッドに引数を与えるために、オーバーライドされるかもしれません。

Cmd.doc_header

ヘルプ出力に文書化されたコマンドのセクションがある場合に表示するヘッダ。

Cmd.misc_header

The header to issue if the help output has a section for miscellaneous help topics (that is, there are help_*() methods without corresponding do_*() methods).

Cmd.undoc_header

The header to issue if the help output has a section for undocumented commands (that is, there are do_*() methods without corresponding help_*() methods).

Cmd.ruler

ヘルプメッセージのヘッダの下に、区切り行を表示するために使われる文字。空のときは、ルーラ行が表示されません。デフォルトでは、'=' です。

Cmd.use_rawinput

A flag, defaulting to true. If true, cmdloop() uses input() to display a prompt and read the next command; if false, sys.stdout.write() and sys.stdin.readline() are used. (This means that by importing readline, on systems that support it, the interpreter will automatically support Emacs-like line editing and command-history keystrokes.)

Cmd の例

cmd モジュールは、ユーザーがプログラムと対話的に連携できるカスタムシェルを構築するのに主に役立ちます。

この節では、turtle モジュールのいくつかのコマンドを持ったシェルの作成方法の簡単な例を示します。

Basic turtle commands such as forward() are added to a Cmd subclass with method named do_forward(). The argument is converted to a number and dispatched to the turtle module. The docstring is used in the help utility provided by the shell.

The example also includes a basic record and playback facility implemented with the precmd() method which is responsible for converting the input to lowercase and writing the commands to a file. The do_playback() method reads the file and adds the recorded commands to the cmdqueue for immediate playback:

import cmd, sys
from turtle import *

class TurtleShell(cmd.Cmd):
    intro = 'Welcome to the turtle shell.   Type help or ? to list commands.\n'
    prompt = '(turtle) '
    file = None

    # ----- basic turtle commands -----
    def do_forward(self, arg):
        'Move the turtle forward by the specified distance:  FORWARD 10'
        forward(*parse(arg))
    def do_right(self, arg):
        'Turn turtle right by given number of degrees:  RIGHT 20'
        right(*parse(arg))
    def do_left(self, arg):
        'Turn turtle left by given number of degrees:  LEFT 90'
        left(*parse(arg))
    def do_goto(self, arg):
        'Move turtle to an absolute position with changing orientation.  GOTO 100 200'
        goto(*parse(arg))
    def do_home(self, arg):
        'Return turtle to the home position:  HOME'
        home()
    def do_circle(self, arg):
        'Draw circle with given radius an options extent and steps:  CIRCLE 50'
        circle(*parse(arg))
    def do_position(self, arg):
        'Print the current turtle position:  POSITION'
        print('Current position is %d %d\n' % position())
    def do_heading(self, arg):
        'Print the current turtle heading in degrees:  HEADING'
        print('Current heading is %d\n' % (heading(),))
    def do_color(self, arg):
        'Set the color:  COLOR BLUE'
        color(arg.lower())
    def do_undo(self, arg):
        'Undo (repeatedly) the last turtle action(s):  UNDO'
    def do_reset(self, arg):
        'Clear the screen and return turtle to center:  RESET'
        reset()
    def do_bye(self, arg):
        'Stop recording, close the turtle window, and exit:  BYE'
        print('Thank you for using Turtle')
        self.close()
        bye()
        return True

    # ----- record and playback -----
    def do_record(self, arg):
        'Save future commands to filename:  RECORD rose.cmd'
        self.file = open(arg, 'w')
    def do_playback(self, arg):
        'Playback commands from a file:  PLAYBACK rose.cmd'
        self.close()
        with open(arg) as f:
            self.cmdqueue.extend(f.read().splitlines())
    def precmd(self, line):
        line = line.lower()
        if self.file and 'playback' not in line:
            print(line, file=self.file)
        return line
    def close(self):
        if self.file:
            self.file.close()
            self.file = None

def parse(arg):
    'Convert a series of zero or more numbers to an argument tuple'
    return tuple(map(int, arg.split()))

if __name__ == '__main__':
    TurtleShell().cmdloop()

以下は、turtle シェルでの機能のヘルプ表示、空行によるコマンドの繰り返し、単純な記録と再実行のセッション例です:

Welcome to the turtle shell.   Type help or ? to list commands.

(turtle) ?

Documented commands (type help <topic>):
========================================
bye     color    goto     home  playback  record  right
circle  forward  heading  left  position  reset   undo

(turtle) help forward
Move the turtle forward by the specified distance:  FORWARD 10
(turtle) record spiral.cmd
(turtle) position
Current position is 0 0

(turtle) heading
Current heading is 0

(turtle) reset
(turtle) circle 20
(turtle) right 30
(turtle) circle 40
(turtle) right 30
(turtle) circle 60
(turtle) right 30
(turtle) circle 80
(turtle) right 30
(turtle) circle 100
(turtle) right 30
(turtle) circle 120
(turtle) right 30
(turtle) circle 120
(turtle) heading
Current heading is 180

(turtle) forward 100
(turtle)
(turtle) right 90
(turtle) forward 100
(turtle)
(turtle) right 90
(turtle) forward 400
(turtle) right 90
(turtle) forward 500
(turtle) right 90
(turtle) forward 400
(turtle) right 90
(turtle) forward 300
(turtle) playback spiral.cmd
Current position is 0 0

Current heading is 0

Current heading is 180

(turtle) bye
Thank you for using Turtle

shlex --- Simple lexical analysis

ソースコード: Lib/shlex.py [https://github.com/python/cpython/tree/3.12/Lib/shlex.py]

shlex クラスは Unix シェルに似た、単純な構文に対する字句解析器を簡単に書けるようにします。このクラスはしばしば、 Python アプリケーションのための実行制御ファイルのような小規模言語を書く上で便利です。

shlex モジュールは以下の関数を定義しています:

shlex.split(s, comments=False, posix=True)

シェルに似た文法を使って、文字列 s を分割します。 comments が False (デフォルト値) の場合、受理した文字列内のコメントを解析しません (shlex インスタンスの commenters メンバの値を空文字列にします)。この関数はデフォルトでは POSIX モードで動作し、 posix 引数が偽の場合は非 POSIX モードで動作します。

バージョン 3.12 で変更: Passing None for s argument now raises an exception, rather than reading sys.stdin.

shlex.join(split_command)

Concatenate the tokens of the list split_command and return a string. This function is the inverse of split().

>>> from shlex import join
>>> print(join(['echo', '-n', 'Multiple words']))
echo -n 'Multiple words'

The returned value is shell-escaped to protect against injection vulnerabilities (see quote()).

Added in version 3.8.

shlex.quote(s)

文字列 s をシェルエスケープして返します。戻り値は、リストを使えないようなケースで、シェルコマンドライン内で一つのトークンとして安全に利用出来る文字列です。

警告

The shlex module is only designed for Unix shells.

The 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 subprocess.run() with shell=False.

以下のイディオムは安全ではないかもしれません:

>>> filename = 'somefile; rm -rf ~'
>>> command = 'ls -l {}'.format(filename)
>>> print(command)  # executed by a shell: boom!
ls -l somefile; rm -rf ~

quote() がそのセキュリティホールをふさぎます:

>>> 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 ~'"'"''

クォーティングは UNIX シェルならびに split() と互換です:

>>> 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 ~']

Added in version 3.3.

shlex モジュールは以下のクラスを定義します。

class shlex.shlex(instream=None, infile=None, posix=False, punctuation_chars=False)

A 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 read() and readline() methods, or a string. If no argument is given, input will be taken from sys.stdin. The second optional argument is a filename string, which sets the initial value of the infile attribute. If the instream argument is omitted or equal to sys.stdin, this second argument defaults to "stdin". The posix argument defines the operational mode: when posix is not true (default), the shlex instance will operate in compatibility mode. When operating in POSIX mode, 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, False, preserves the behaviour seen under Python 3.5 and earlier. If set to True, then parsing of the characters ();<>|& 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 wordchars attribute that appear in punctuation_chars will be removed from wordchars. See Improved Compatibility with Shells for more information. punctuation_chars can be set only upon shlex instance creation and can't be modified later.

バージョン 3.6 で変更: punctuation_chars 引数が追加されました。

参考

configparser モジュール

Windows .ini ファイルに似た設定ファイルのパーザ。

shlex オブジェクト

shlex インスタンスは以下のメソッドを持っています:

shlex.get_token()

トークンを一つ返します。トークンが push_token() で使ってスタックに積まれていた場合、トークンをスタックからポップします。そうでない場合、トークンを一つ入力ストリームから読み出します。読み出し即時にファイル終了子に遭遇した場合、 eof (非 POSIX モードでは空文字列 ('')、POSIX モードでは None) が返されます。

shlex.push_token(str)

トークンスタックに引数文字列をスタックします。

shlex.read_token()

生 (raw) のトークンを読み出します。プッシュバックスタックを無視し、かつソースリクエストを解釈しません (通常これは便利なエントリポイントではありません。完全性のためにここで記述されています)。

shlex.sourcehook(filename)

shlex がソースリクエスト (下の source を参照してください) を検出した際、このメソッドはその後に続くトークンを引数として渡され、ファイル名と開かれたファイル類似オブジェクトからなるタプルを返すとされています。

通常、このメソッドはまず引数から何らかのクオートを取り除きます。処理後の引数が絶対パス名であった場合か、以前に有効になったソースリクエストが存在しない場合か、以前のソースが (sys.stdin のような) ストリームであった場合、この結果はそのままにされます。そうでない場合で、処理後の引数が相対パス名の場合、ソースインクルードスタックにある直前のファイル名からディレクトリ部分が取り出され、相対パスの前の部分に追加されます (この動作は C 言語プリプロセッサにおける #include "file.h" の扱いと同様です)。

これらの操作の結果はファイル名として扱われ、タプルの最初の要素として返されます。同時にこのファイル名で open() を呼び出した結果が二つ目の要素になります (注意: インスタンス初期化のときとは引数の並びが逆になっています！)

このフックはディレクトリサーチパスや、ファイル拡張子の追加、その他の名前空間に関するハックを実装できるようにするために公開されています。 'close' フックに対応するものはありませんが、shlex インスタンスはソースリクエストされている入力ストリームが EOF を返した時には close() を呼び出します。

ソーススタックをより明示的に操作するには、 push_source() および pop_source() メソッドを使ってください。

shlex.push_source(newstream, newfile=None)

入力ソースストリームを入力スタックにプッシュします。ファイル名引数が指定された場合、以後のエラーメッセージ中で利用することができます。 sourcehook() メソッドが内部で使用しているのと同じメソッドです。

shlex.pop_source()

最後にプッシュされた入力ソースを入力スタックからポップします。字句解析器がスタック上の入力ストリームの EOF に到達した際に利用するメソッドと同じです。

shlex.error_leader(infile=None, lineno=None)

このメソッドはエラーメッセージの論述部分を Unix C コンパイラエラーラベルの形式で生成します; この書式は '"%s", line %d: ' で、 %s は現在のソースファイル名で置き換えられ、 %d は現在の入力行番号で置き換えられます (オプションの引数を使ってこれらを上書きすることもできます)。

このやり方は、 shlex のユーザに対して、Emacs やその他の Unix ツール群が解釈できる一般的な書式でのメッセージを生成することを推奨するために提供されています。

shlex サブクラスのインスタンスは、字句解析を制御したり、デバッグに使えるような public なインスタンス変数を持っています:

shlex.commenters

コメントの開始として認識される文字列です。コメントの開始から行末までのすべてのキャラクタ文字は無視されます。標準では単に '#' が入っています。

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 punctuation_chars is not empty, the characters ~-./*?=, which can appear in filename specifications and command line parameters, will also be included in this attribute, and any characters which appear in punctuation_chars will be removed from wordchars if they are present there. If whitespace_split is set to True, this will have no effect.

shlex.whitespace

空白と見なされ、読み飛ばされる文字群です。空白はトークンの境界を作ります。標準では、スペース、タブ、改行 (linefeed) および復帰 (carriage-return) が入っています。

shlex.escape

エスケープ文字と見なされる文字群です。これは POSIX モードでのみ使われ、デフォルトでは '\' だけが入っています。

shlex.quotes

文字列引用符と見なされる文字群です。トークンを構成する際、同じクオートが再び出現するまで文字をバッファに蓄積します (すなわち、異なるクオート形式はシェル中で互いに保護し合う関係にあります)。標準では、ASCII 単引用符および二重引用符が入っています。

shlex.escapedquotes

quotes のうち、 escape で定義されたエスケープ文字を解釈する文字群です。これは POSIX モードでのみ使われ、デフォルトでは '"' だけが入っています。

shlex.whitespace_split

If True, tokens will only be split in whitespaces. This is useful, for example, for parsing command lines with shlex, getting tokens in a similar way to shell arguments. When used in combination with punctuation_chars, tokens will be split on whitespace in addition to those characters.

バージョン 3.8 で変更: The punctuation_chars attribute was made compatible with the whitespace_split attribute.

shlex.infile

現在の入力ファイル名です。クラスのインスタンス化時に初期設定されるか、その後のソースリクエストでスタックされます。エラーメッセージを構成する際にこの値を調べると便利なことがあります。

shlex.instream

shlex インスタンスが文字を読み出している入力ストリームです。

shlex.source

このメンバ変数は標準で None を取ります。この値に文字列を代入すると、その文字列は多くのシェルにおける source キーワードに似た、字句解析レベルでのインクルード要求として認識されます。すなわち、その直後に現れるトークンをファイル名として新たなストリームを開き、そのストリームを入力として、EOF に到達するまで読み込まれます。新たなストリームの EOF に到達した時点で close() が呼び出され、入力は元の入力ストリームに戻されます。ソースリクエストは任意のレベルの深さまでスタックしてかまいません。

shlex.debug

このメンバ変数が数値で、かつ 1 またはそれ以上の値の場合、 shlex インスタンスは動作に関する冗長な進捗報告を出力します。この出力を使いたいなら、モジュールのソースコードを読めば詳細を学ぶことができます。

shlex.lineno

ソース行番号 (遭遇した改行の数に 1 を加えたもの) です。

shlex.token

トークンバッファです。例外を捕捉した際にこの値を調べると便利なことがあります。

shlex.eof

ファイルの終端を決定するのに使われるトークンです。非 POSIX モードでは空文字列 ('') 、POSIX モードでは None が入ります。

shlex.punctuation_chars

A read-only property. Characters that will be considered punctuation. Runs of punctuation characters will be returned as a single token. However, note that no semantic validity checking will be performed: for example, '>>>' could be returned as a token, even though it may not be recognised as such by shells.

Added in version 3.6.

解析規則

非 POSIX モードで動作中の shlex は以下の規則に従おうとします。

ワード内の引用符を認識しない (Do"Not"Separate は単一ワード Do"Not"Separate として解析されます)

エスケープ文字を認識しない

引用符で囲まれた文字列は、引用符内の全ての文字リテラルを保持する

閉じ引用符でワードを区切る ("Do"Separate は、 "Do" と Separate であると解析されます)

whitespace_split が False の場合、wordchar、 whitespace または quote として宣言されていない全ての文字を、単一の文字トークンとして返す。 True の場合、 shlex は空白文字でのみ単語を区切る。

空文字列 ('') で EOF を送出する

引用符に囲んであっても、空文字列を解析しない

POSIX モードで動作中の shlex は以下の解析規則に従おうとします。

引用符を取り除き、引用符で単語を分解しない ("Do"Not"Separate" は単一ワード DoNotSeparate として解析されます)

引用符で囲まれないエスケープ文字群 ('\' など) は直後に続く文字のリテラル値を保持する

escapedquotes でない引用符文字 ("'" など) で囲まれている全ての文字のリテラル値を保持する

引用符に囲まれた escapedquotes に含まれる文字 ('"' など) は、 escape に含まれる文字を除き、全ての文字のリテラル値を保持する。エスケープ文字群は使用中の引用符、または、そのエスケープ文字自身が直後にある場合のみ、特殊な機能を保持する。他の場合にはエスケープ文字は普通の文字とみなされる。

None で EOF を送出する

引用符に囲まれた空文字列 ('') を許す。

Improved Compatibility with Shells

Added in version 3.6.

The shlex class provides compatibility with the parsing performed by common Unix shells like bash, dash, and sh. To take advantage of this compatibility, specify the punctuation_chars argument in the constructor. This defaults to False, which preserves pre-3.6 behaviour. However, if it is set to True, then parsing of the characters ();<>|& 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:

>>> 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', ')']

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

>>> import shlex
>>> s = shlex.shlex("a && b || c", punctuation_chars="|")
>>> list(s)
['a', '&', '&', 'b', '||', 'c']

注釈

When punctuation_chars is specified, the wordchars attribute is augmented with the characters ~-./*?=. That is because these characters can appear in file names (including wildcards) and command-line arguments (e.g. --color=auto). Hence:

>>> import shlex
>>> s = shlex.shlex('~/a && b-c --color=auto || d *.py?',
...                 punctuation_chars=True)
>>> list(s)
['~/a', '&&', 'b-c', '--color=auto', '||', 'd', '*.py?']

However, to match the shell as closely as possible, it is recommended to always use posix and whitespace_split when using punctuation_chars, which will negate wordchars entirely.

For best effect, punctuation_chars should be set in conjunction with posix=True. (Note that posix=False is the default for shlex.)

Tk を用いたグラフィカルユーザインターフェイス

Tk/Tcl has long been an integral part of Python. It provides a robust and platform independent windowing toolkit, that is available to Python programmers using the tkinter package, and its extension, the tkinter.tix and the tkinter.ttk modules.

tkinter パッケージはオブジェクトの薄い層で作ったTcl/Tkの最上層です。tkinter を使うには、Tcl のコードを書く必要はありませんが、Tk のドキュメント、またはときどき、Tcl のドキュメントを調べる必要が出て来ます。tkinter は Python クラスとして実装した Tk ウィジェットのラッパーの集合です。

tkinter's chief virtues are that it is fast, and that it usually comes bundled with Python. Although its standard documentation is weak, good material is available, which includes: references, tutorials, a book and others. tkinter is also famous for having an outdated look and feel, which has been vastly improved in Tk 8.5. Nevertheless, there are many other GUI libraries that you could be interested in. The Python wiki lists several alternative GUI frameworks and tools [https://wiki.python.org/moin/GuiProgramming].

tkinter --- Python interface to Tcl/Tk

Architecture

Tkinter モジュール

Tkinter お助け手帳

A Hello World Program

Important Tk Concepts

Understanding How Tkinter Wraps Tcl/Tk

How do I...? What option does...?

Navigating the Tcl/Tk Reference Manual

Threading model

簡単なリファレンス

オプションの設定

Packer

Packer のオプション

ウィジェット変数を関連付ける

ウィンドウマネージャ

Tk オプションデータ型

バインドとイベント

index パラメータ

画像

ファイルハンドラ

tkinter.colorchooser --- Color choosing dialog

tkinter.font --- Tkinter font wrapper

Tkinter ダイアログ

tkinter.simpledialog --- 標準 Tkinter 入力ダイアログ

tkinter.filedialog --- ファイル選択ダイアログ

ネイティブの読み込み/保存ダイアログ

tkinter.commondialog --- Dialog window templates

tkinter.messagebox --- Tkinter message prompts

tkinter.scrolledtext --- Scrolled Text Widget

tkinter.dnd --- Drag and drop support

tkinter.ttk --- Tk themed widgets

Ttk を使う

Ttk ウィジェット

ウィジェット

標準オプション

スクロール可能ウィジェットのオプション

ラベルオプション

互換性オプション

ウィジェットの状態

ttk.Widget

コンボボックス

オプション

仮想イベント

ttk.Combobox

Spinbox

オプション

仮想イベント

ttk.Spinbox

ノートブック

オプション

タブオプション

タブ識別子

仮想イベント

ttk.Notebook

プログレスバー

オプション

ttk.Progressbar

セパレータ

オプション

サイズグリップ

プラットフォーム固有のメモ

バグ

ツリービュー

オプション

要素オプション

タグオプション

カラム識別子

仮想イベント

ttk.Treeview

Ttk スタイル

レイアウト

tkinter.tix --- Tkの拡張ウィジェット

Tixを使う

Tixウィジェット

基本ウィジェット

ファイルセレクタ

階層的リストボックス

表的リストボックス

管理ウィジェット

画像タイプ

その他のウィジェット

ジオメトリマネジャを作る

Tixコマンド

IDLE

メニュー

File メニュー (Shell ウィンドウ、Editor ウィンドウ)

Edit メニュー (Shell ウィンドウ、Editor ウィンドウ)

Format メニュー (Shell ウィンドウ、Editor ウィンドウ)

Run メニュー (Editor ウィンドウのみ)

Shell メニュー (Shell ウィンドウのみ)

Debug メニュー (Shell ウィンドウのみ)

Options メニュー (Shell ウィンドウ、Editor ウィンドウ)

Window メニュー (Shell ウィンドウ、Editor ウィンドウ)

Help メニュー (Shell ウィンドウ、Editor ウィンドウ)

Context menus

Editing and Navigation

Editor windows

Key bindings

自動的な字下げ

検索と置換

補完 (Completions)

呼び出しヒント (Calltips)

Code Context

Shell window

テキストの色

Startup and Code Execution

コマンドラインの使い方

Startup failure

Running user code

User output in Shell

Developing tkinter applications

サブプロセスを起こさずに起動する

Help and Preferences

Help sources

Setting preferences [お好み設定]

IDLE on macOS

Extensions [拡張]

idlelib

tkinter --- Python interface to Tcl/Tk

ソースコード: Lib/tkinter/__init__.py [https://github.com/python/cpython/tree/3.12/Lib/tkinter/__init__.py]

tkinter パッケージ ("Tk インターフェース") は、 Tcl/Tk GUI ツールキットに対する標準の Python インターフェースです。 Tk と tkinter は macOS を含むほとんどの Unix プラットフォームの他、 Windows システム上でも利用できます。

コマンドラインから python -m tkinter を実行すると簡素な Tk インターフェースを表示するウィンドウが開き、システムに tkinter が正しくインストールされたことが分かり、さらにインストールされた Tcl/Tk がどのバーションなのかが表示されるので、そのバージョンの Tcl/Tk ドキュメントを選んで読めます。

Tkinter supports a range of Tcl/Tk versions, built either with or without thread support. The official Python binary release bundles Tcl/Tk 8.6 threaded. See the source code for the _tkinter module for more information about supported versions.

Tkinter is not a thin wrapper, but adds a fair amount of its own logic to make the experience more pythonic. This documentation will concentrate on these additions and changes, and refer to the official Tcl/Tk documentation for details that are unchanged.

注釈

Tcl/Tk 8.5 (2007) introduced a modern set of themed user interface components along with a new API to use them. Both old and new APIs are still available. Most documentation you will find online still uses the old API and can be woefully outdated.

参考

TkDocs [https://tkdocs.com/]

Extensive tutorial on creating user interfaces with Tkinter. Explains key concepts, and illustrates recommended approaches using the modern API.

Tkinter 8.5 reference: a GUI for Python [https://www.tkdocs.com/shipman/]

Reference documentation for Tkinter 8.5 detailing available classes, methods, and options.

Tcl/Tk Resources:

Tk commands [https://www.tcl.tk/man/tcl8.6/TkCmd/contents.htm]

Comprehensive reference to each of the underlying Tcl/Tk commands used by Tkinter.

Tcl/Tk ホームページ [https://www.tcl.tk]

Additional documentation, and links to Tcl/Tk core development.

Books:

Modern Tkinter for Busy Python Developers [https://tkdocs.com/book.html]

By Mark Roseman. (ISBN 978-1999149567)

Python GUI programming with Tkinter [https://www.packtpub.com/product/python-gui-programming-with-tkinter/9781788835886]

By Alan D. Moore. (ISBN 978-1788835886)

Programming Python [https://learning-python.com/about-pp4e.html]

By Mark Lutz; has excellent coverage of Tkinter. (ISBN 978-0596158101)

Tcl and the Tk Toolkit (2nd edition) [https://www.amazon.com/exec/obidos/ASIN/032133633X]

By John Ousterhout, inventor of Tcl/Tk, and Ken Jones; does not cover Tkinter. (ISBN 978-0321336330)

Architecture

Tcl/Tk is not a single library but rather consists of a few distinct modules, each with separate functionality and its own official documentation. Python's binary releases also ship an add-on module together with it.

Tcl

Tcl is a dynamic interpreted programming language, just like Python. Though it can be used on its own as a general-purpose programming language, it is most commonly embedded into C applications as a scripting engine or an interface to the Tk toolkit. The Tcl library has a C interface to create and manage one or more instances of a Tcl interpreter, run Tcl commands and scripts in those instances, and add custom commands implemented in either Tcl or C. Each interpreter has an event queue, and there are facilities to send events to it and process them. Unlike Python, Tcl's execution model is designed around cooperative multitasking, and Tkinter bridges this difference (see Threading model for details).

Tk

Tk is a Tcl package [https://wiki.tcl-lang.org/37432] implemented in C that adds custom commands to create and manipulate GUI widgets. Each Tk object embeds its own Tcl interpreter instance with Tk loaded into it. Tk's widgets are very customizable, though at the cost of a dated appearance. Tk uses Tcl's event queue to generate and process GUI events.

Ttk

Themed Tk (Ttk) is a newer family of Tk widgets that provide a much better appearance on different platforms than many of the classic Tk widgets. Ttk is distributed as part of Tk, starting with Tk version 8.5. Python bindings are provided in a separate module, tkinter.ttk.

Internally, Tk and Ttk use facilities of the underlying operating system, i.e., Xlib on Unix/X11, Cocoa on macOS, GDI on Windows.

When your Python application uses a class in Tkinter, e.g., to create a widget, the tkinter module first assembles a Tcl/Tk command string. It passes that Tcl command string to an internal _tkinter binary module, which then calls the Tcl interpreter to evaluate it. The Tcl interpreter will then call into the Tk and/or Ttk packages, which will in turn make calls to Xlib, Cocoa, or GDI.

Tkinter モジュール

Support for Tkinter is spread across several modules. Most applications will need the main tkinter module, as well as the tkinter.ttk module, which provides the modern themed widget set and API:

from tkinter import *
from tkinter import ttk

class tkinter.Tk(screenName=None, baseName=None, className='Tk', useTk=True, sync=False, use=None)

Construct a toplevel Tk widget, which is usually the main window of an application, and initialize a Tcl interpreter for this widget. Each instance has its own associated Tcl interpreter.

The Tk class is typically instantiated using all default values. However, the following keyword arguments are currently recognized:

screenName

When given (as a string), sets the DISPLAY environment variable. (X11 only)

baseName

Name of the profile file. By default, baseName is derived from the program name (sys.argv[0]).

className

Name of the widget class. Used as a profile file and also as the name with which Tcl is invoked (argv0 in interp).

useTk

If True, initialize the Tk subsystem. The tkinter.Tcl() function sets this to False.

sync

If True, execute all X server commands synchronously, so that errors are reported immediately. Can be used for debugging. (X11 only)

use

Specifies the id of the window in which to embed the application, instead of it being created as an independent toplevel window. id must be specified in the same way as the value for the -use option for toplevel widgets (that is, it has a form like that returned by winfo_id()).

Note that on some platforms this will only work correctly if id refers to a Tk frame or toplevel that has its -container option enabled.

Tk reads and interprets profile files, named .className.tcl and .baseName.tcl, into the Tcl interpreter and calls exec() on the contents of .className.py and .baseName.py. The path for the profile files is the HOME environment variable or, if that isn't defined, then os.curdir.

tk

The Tk application object created by instantiating Tk. This provides access to the Tcl interpreter. Each widget that is attached the same instance of Tk has the same value for its tk attribute.

master

The widget object that contains this widget. For Tk, the master is None because it is the main window. The terms master and parent are similar and sometimes used interchangeably as argument names; however, calling winfo_parent() returns a string of the widget name whereas master returns the object. parent/child reflects the tree-like relationship while master/slave reflects the container structure.

children

The immediate descendants of this widget as a dict with the child widget names as the keys and the child instance objects as the values.

tkinter.Tcl(screenName=None, baseName=None, className='Tk', useTk=False)

Tcl() はファクトリ関数で、 Tk クラスで生成するオブジェクトとよく似たオブジェクトを生成します。ただし Tk サブシステムを初期化しません。この関数は、余分なトップレベルウィンドウを作る必要がなかったり、 (X サーバを持たない Unix/Linux システムなどのように) 作成できない環境において Tcl インタプリタを駆動したい場合に便利です。 Tcl() で生成したオブジェクトに対して loadtk() メソッドを呼び出せば、トップレベルウィンドウを作成 (して、Tk サブシステムを初期化) します。

The modules that provide Tk support include:

tkinter

Main Tkinter module.

tkinter.colorchooser

ユーザに色を選択させるためのダイアログです。

tkinter.commondialog

このリストの他のモジュールが定義しているダイアログの基底クラスです。

tkinter.filedialog

ユーザが開きたいファイルや保存したいファイルを指定できるようにする共通のダイアログです。

tkinter.font

フォントの扱いを補助するためのユーティリティです。

tkinter.messagebox

標準的な Tk のダイアログボックスにアクセスします。

tkinter.scrolledtext

垂直スクロールバー付きのテキストウィジェットです。

tkinter.simpledialog

基本的なダイアログと便宜関数 (convenience function) です。

tkinter.ttk

Themed widget set introduced in Tk 8.5, providing modern alternatives for many of the classic widgets in the main tkinter module.

Additional modules:

_tkinter

A binary module that contains the low-level interface to Tcl/Tk. It is automatically imported by the main tkinter module, and should never be used directly by application programmers. It is usually a shared library (or DLL), but might in some cases be statically linked with the Python interpreter.

idlelib

Python's Integrated Development and Learning Environment (IDLE). Based on tkinter.

tkinter.constants

Symbolic constants that can be used in place of strings when passing various parameters to Tkinter calls. Automatically imported by the main tkinter module.

tkinter.dnd

(experimental) Drag-and-drop support for tkinter. This will become deprecated when it is replaced with the Tk DND.

tkinter.tix

(deprecated) An older third-party Tcl/Tk package that adds several new widgets. Better alternatives for most can be found in tkinter.ttk.

turtle

Tk ウィンドウ上でタートルグラフィックスを実現します。

Tkinter お助け手帳

This section is not designed to be an exhaustive tutorial on either Tk or Tkinter. For that, refer to one of the external resources noted earlier. Instead, this section provides a very quick orientation to what a Tkinter application looks like, identifies foundational Tk concepts, and explains how the Tkinter wrapper is structured.

The remainder of this section will help you to identify the classes, methods, and options you'll need in your Tkinter application, and where to find more detailed documentation on them, including in the official Tcl/Tk reference manual.

A Hello World Program

We'll start by walking through a "Hello World" application in Tkinter. This isn't the smallest one we could write, but has enough to illustrate some key concepts you'll need to know.

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()

After the imports, the next line creates an instance of the Tk class, which initializes Tk and creates its associated Tcl interpreter. It also creates a toplevel window, known as the root window, which serves as the main window of the application.

The following line creates a frame widget, which in this case will contain a label and a button we'll create next. The frame is fit inside the root window.

The next line creates a label widget holding a static text string. The grid() method is used to specify the relative layout (position) of the label within its containing frame widget, similar to how tables in HTML work.

A button widget is then created, and placed to the right of the label. When pressed, it will call the destroy() method of the root window.

Finally, the mainloop() method puts everything on the display, and responds to user input until the program terminates.

Important Tk Concepts

Even this simple program illustrates the following key Tk concepts:

widgets

A Tkinter user interface is made up of individual widgets. Each widget is represented as a Python object, instantiated from classes like ttk.Frame, ttk.Label, and ttk.Button.

widget hierarchy

Widgets are arranged in a hierarchy. The label and button were contained within a frame, which in turn was contained within the root window. When creating each child widget, its parent widget is passed as the first argument to the widget constructor.

configuration options

Widgets have configuration options, which modify their appearance and behavior, such as the text to display in a label or button. Different classes of widgets will have different sets of options.

geometry management

Widgets aren't automatically added to the user interface when they are created. A geometry manager like grid controls where in the user interface they are placed.

event loop

Tkinter reacts to user input, changes from your program, and even refreshes the display only when actively running an event loop. If your program isn't running the event loop, your user interface won't update.

Understanding How Tkinter Wraps Tcl/Tk

When your application uses Tkinter's classes and methods, internally Tkinter is assembling strings representing Tcl/Tk commands, and executing those commands in the Tcl interpreter attached to your application's Tk instance.

Whether it's trying to navigate reference documentation, trying to find the right method or option, adapting some existing code, or debugging your Tkinter application, there are times that it will be useful to understand what those underlying Tcl/Tk commands look like.

To illustrate, here is the Tcl/Tk equivalent of the main part of the Tkinter script above.

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

Tcl's syntax is similar to many shell languages, where the first word is the command to be executed, with arguments to that command following it, separated by spaces. Without getting into too many details, notice the following:

The commands used to create widgets (like ttk::frame) correspond to widget classes in Tkinter.

Tcl widget options (like -text) correspond to keyword arguments in Tkinter.

Widgets are referred to by a pathname in Tcl (like .frm.btn), whereas Tkinter doesn't use names but object references.

A widget's place in the widget hierarchy is encoded in its (hierarchical) pathname, which uses a . (dot) as a path separator. The pathname for the root window is just . (dot). In Tkinter, the hierarchy is defined not by pathname but by specifying the parent widget when creating each child widget.

Operations which are implemented as separate commands in Tcl (like grid or destroy) are represented as methods on Tkinter widget objects. As you'll see shortly, at other times Tcl uses what appear to be method calls on widget objects, which more closely mirror what would is used in Tkinter.

How do I...? What option does...?

If you're not sure how to do something in Tkinter, and you can't immediately find it in the tutorial or reference documentation you're using, there are a few strategies that can be helpful.

First, remember that the details of how individual widgets work may vary across different versions of both Tkinter and Tcl/Tk. If you're searching documentation, make sure it corresponds to the Python and Tcl/Tk versions installed on your system.

When searching for how to use an API, it helps to know the exact name of the class, option, or method that you're using. Introspection, either in an interactive Python shell or with print(), can help you identify what you need.

To find out what configuration options are available on any widget, call its configure() method, which returns a dictionary containing a variety of information about each object, including its default and current values. Use keys() to get just the names of each option.

btn = ttk.Button(frm, ...)
print(btn.configure().keys())

As most widgets have many configuration options in common, it can be useful to find out which are specific to a particular widget class. Comparing the list of options to that of a simpler widget, like a frame, is one way to do that.

print(set(btn.configure().keys()) - set(frm.configure().keys()))

Similarly, you can find the available methods for a widget object using the standard dir() function. If you try it, you'll see there are over 200 common widget methods, so again identifying those specific to a widget class is helpful.

print(dir(btn))
print(set(dir(btn)) - set(dir(frm)))

Navigating the Tcl/Tk Reference Manual

As noted, the official Tk commands [https://www.tcl.tk/man/tcl8.6/TkCmd/contents.htm] reference manual (man pages) is often the most accurate description of what specific operations on widgets do. Even when you know the name of the option or method that you need, you may still have a few places to look.

While all operations in Tkinter are implemented as method calls on widget objects, you've seen that many Tcl/Tk operations appear as commands that take a widget pathname as its first parameter, followed by optional parameters, e.g.

destroy .
grid .frm.btn -column 0 -row 0

Others, however, look more like methods called on a widget object (in fact, when you create a widget in Tcl/Tk, it creates a Tcl command with the name of the widget pathname, with the first parameter to that command being the name of a method to call).

.frm.btn invoke
.frm.lbl configure -text "Goodbye"

In the official Tcl/Tk reference documentation, you'll find most operations that look like method calls on the man page for a specific widget (e.g., you'll find the invoke() method on the ttk::button [https://www.tcl.tk/man/tcl8.6/TkCmd/ttk_button.htm] man page), while functions that take a widget as a parameter often have their own man page (e.g., grid [https://www.tcl.tk/man/tcl8.6/TkCmd/grid.htm]).

You'll find many common options and methods in the options [https://www.tcl.tk/man/tcl8.6/TkCmd/options.htm] or ttk::widget [https://www.tcl.tk/man/tcl8.6/TkCmd/ttk_widget.htm] man pages, while others are found in the man page for a specific widget class.

You'll also find that many Tkinter methods have compound names, e.g., winfo_x(), winfo_height(), winfo_viewable(). You'd find documentation for all of these in the winfo [https://www.tcl.tk/man/tcl8.6/TkCmd/winfo.htm] man page.

注釈

Somewhat confusingly, there are also methods on all Tkinter widgets that don't actually operate on the widget, but operate at a global scope, independent of any widget. Examples are methods for accessing the clipboard or the system bell. (They happen to be implemented as methods in the base Widget class that all Tkinter widgets inherit from).

Threading model

Python and Tcl/Tk have very different threading models, which tkinter tries to bridge. If you use threads, you may need to be aware of this.

A Python interpreter may have many threads associated with it. In Tcl, multiple threads can be created, but each thread has a separate Tcl interpreter instance associated with it. Threads can also create more than one interpreter instance, though each interpreter instance can be used only by the one thread that created it.

Each Tk object created by tkinter contains a Tcl interpreter. It also keeps track of which thread created that interpreter. Calls to tkinter can be made from any Python thread. Internally, if a call comes from a thread other than the one that created the Tk object, an event is posted to the interpreter's event queue, and when executed, the result is returned to the calling Python thread.

Tcl/Tk applications are normally event-driven, meaning that after initialization, the interpreter runs an event loop (i.e. Tk.mainloop()) and responds to events. Because it is single-threaded, event handlers must respond quickly, otherwise they will block other events from being processed. To avoid this, any long-running computations should not run in an event handler, but are either broken into smaller pieces using timers, or run in another thread. This is different from many GUI toolkits where the GUI runs in a completely separate thread from all application code including event handlers.

If the Tcl interpreter is not running the event loop and processing events, any tkinter calls made from threads other than the one running the Tcl interpreter will fail.

A number of special cases exist:

Tcl/Tk libraries can be built so they are not thread-aware. In this case, tkinter calls the library from the originating Python thread, even if this is different than the thread that created the Tcl interpreter. A global lock ensures only one call occurs at a time.

While tkinter allows you to create more than one instance of a Tk object (with its own interpreter), all interpreters that are part of the same thread share a common event queue, which gets ugly fast. In practice, don't create more than one instance of Tk at a time. Otherwise, it's best to create them in separate threads and ensure you're running a thread-aware Tcl/Tk build.

Blocking event handlers are not the only way to prevent the Tcl interpreter from reentering the event loop. It is even possible to run multiple nested event loops or abandon the event loop entirely. If you're doing anything tricky when it comes to events or threads, be aware of these possibilities.

There are a few select tkinter functions that presently work only when called from the thread that created the Tcl interpreter.

簡単なリファレンス

オプションの設定

オプションは、色やウィジェットの境界線幅などを制御します。オプションの設定には三通りの方法があります:

オブジェクト生成時、キーワード引数を使用する

fred = Button(self, fg="red", bg="blue")

オブジェクト生成後、オプション名を辞書インデックスのように扱う

fred["fg"] = "red"
fred["bg"] = "blue"

オブジェクト生成後に、config()メソッドを使って複数の属性を更新する

fred.config(fg="red", bg="blue")

オプションとその振る舞いに関する詳細な説明は、該当するウィジェットの Tk の man ページを参照してください。

man ページには、各ウィジェットの "STANDARD OPTIONS (標準オプション)" と "WIDGET SPECIFIC OPTIONS (ウィジェット固有のオプション)" がリストされていることに注意してください。前者は多くのウィジェットに共通のオプションのリストで、後者は特定のウィジェットに特有のオプションです。標準オプションの説明は man ページの options(3) [https://manpages.debian.org/options(3)] にあります。

このドキュメントでは、標準オプションとウィジェット固有のオプションを区別していません。オプションによっては、ある種のウィジェットに適用できません。あるウィジェットがあるオプションに対応しているかどうかは、ウィジェットのクラスによります。例えばボタンには command オプションがありますが、ラベルにはありません。

あるウィジェットがどんなオプションをサポートしているかは、ウィジェットの man ページにリストされています。また、実行時にウィジェットの config() メソッドを引数なしで呼び出したり、 keys() メソッドを呼び出したりして問い合わせることもできます。メソッド呼び出しを行うと辞書型の値を返します。この辞書は、オプションの名前がキー (例えば 'relief') になっていて、値が 5 要素のタプルになっています。

bg のように、いくつかのオプションはより長い名前を持つ共通のオプションに対する同義語になっています (bg は "background" を短縮したものです)。短縮形のオプション名を config() に渡すと、 5 要素ではなく 2 要素のタプルを返します。このタプルには、同義語の名前と「本当の」オプション名が入っています (例えば ('bg', 'background'))。

インデックス

意味

使用例

0

オプション名

'relief'

1

データベース検索用のオプション名

'relief'

2

データベース検索用のオプションクラス

'Relief'

3

デフォルト値

'raised'

4

現在の値

'groove'

以下はプログラム例です:

>>> print(fred.config())
{'relief': ('relief', 'relief', 'Relief', 'raised', 'groove')}

もちろん、実際に出力される辞書には利用可能なオプションが全て表示されます。上の表示例は単なる例にすぎません。

Packer

packer は Tk のジオメトリ管理メカニズムの一つです。ジオメトリマネージャは、複数のウィジェットの位置を、それぞれのウィジェットを含むコンテナ - 共通の マスタ (master) からの相対で指定するために使います。やや扱いにくい placer (あまり使われないのでここでは取り上げません) と違い、packer は定性的な関係を表す指定子 - 上 (above) 、 〜の左 (to the left of) 、 引き延ばし (filling) など - を受け取り、厳密な配置座標の決定を全て行ってくれます。

どんな マスタ ウィジェットでも、大きさは内部の "スレイブ (slave) ウィジェット" の大きさで決まります。 packer は、スレイブウィジェットを pack 先のマスタウィジェット中のどこに配置するかを制御するために使われます。望みのレイアウトを達成するには、ウィジェットをフレームにパックし、そのフレームをまた別のフレームにパックできます。さらに、一度パックを行うと、それ以後の設定変更に合わせて動的に並べ方を調整します。

ジオメトリマネージャがウィジェットのジオメトリを確定するまで、ウィジェットは表示されないので注意してください。初心者のころにはよくジオメトリの確定を忘れてしまい、ウィジェットを生成したのに何も表示されず驚くことになります。ウィジェットは、(例えば packer の pack() メソッドを適用して) ジオメトリを確定した後で初めて表示されます。

pack() メソッドは、キーワード引数つきで呼び出せます。キーワード引数は、ウィジェットをコンテナ内のどこに表示するか、メインのアプリケーションウィンドウをリサイズしたときにウィジェットがどう振舞うかを制御します。以下に例を示します:

fred.pack()                     # defaults to side = "top"
fred.pack(side="left")
fred.pack(expand=1)

Packer のオプション

packer と packer の取りえるオプションについての詳細は、man ページや John Ousterhout の本の183ページを参照してください。

anchor

アンカーの型です。 packer が区画内に各スレイブを配置する位置を示します。

expand

ブール値で、 0 または 1 になります。

fill

指定できる値は 'x' 、 'y' 、 'both' 、 'none' です。

ipadx および ipady

スレイブウィジェットの各側面の内側に行うパディング幅を表す長さを指定します。

padx および pady

スレイブウィジェットの各側面の外側に行うパディング幅を表す長さを指定します。

side

指定できる値は 'left', 'right', 'top', 'bottom' です。

ウィジェット変数を関連付ける

ウィジェットによっては、(テキスト入力ウィジェットのように) 特殊なオプションを使って、現在設定されている値をアプリケーション内の変数に直接関連付けできます。このようなオプションには variable, textvariable, onvalue, offvalue および value があります。この関連付けは双方向に働きます: 変数の値が何らかの理由で変更されると、関連付けされているウィジェットも更新され、新しい値を反映します。

残念ながら、現在の tkinter の実装では、variable や textvariable オプションでは任意の Python の値をウィジェットに渡せません。この関連付け機能がうまく働くのは、tkinter 内で Variable というクラスからサブクラス化されている変数によるオプションだけです。

Variable には、 StringVar, IntVar, DoubleVar, BooleanVar といった便利なサブクラスがすでにすでに数多く定義されています。こうした変数の現在の値を読み出したければ、 get() メソッドを呼び出します。また、値を変更したければ set() メソッドを呼び出します。このプロトコルに従っている限り、それ以上なにも手を加えなくてもウィジェットは常に現在値に追従します。

例えば:

import tkinter as tk

class App(tk.Frame):
    def __init__(self, master):
        super().__init__(master)
        self.pack()

        self.entrythingy = tk.Entry()
        self.entrythingy.pack()

        # Create the application variable.
        self.contents = tk.StringVar()
        # Set it to some value.
        self.contents.set("this is a variable")
        # Tell the entry widget to watch this variable.
        self.entrythingy["textvariable"] = self.contents

        # Define a callback for when the user hits return.
        # It prints the current value of the variable.
        self.entrythingy.bind('<Key-Return>',
                             self.print_contents)

    def print_contents(self, event):
        print("Hi. The current entry content is:",
              self.contents.get())

root = tk.Tk()
myapp = App(root)
myapp.mainloop()

ウィンドウマネージャ

Tk には、ウィンドウマネジャとやり取りするための wm というユーティリティコマンドがあります。wm コマンドにオプションを指定すると、タイトルや配置、アイコンビットマップなどを操作できます。tkinter では、こうしたコマンドは Wm クラスのメソッドとして実装されています。トップレベルウィジェットは Wm クラスからサブクラス化されているので、Wm のメソッドを直接呼び出せます。

あるウィジェットの入っているトップレベルウィンドウを取得したい場合、大抵は単にウィジェットのマスタを参照するだけですみます。とはいえ、ウィジェットがフレーム内にパックされている場合、マスタはトップレベルウィンドウではありません。任意のウィジェットの入っているトップレベルウィンドウを知りたければ _root() メソッドを呼び出してください。このメソッドはアンダースコアがついていますが、これはこの関数が Tkinter の実装の一部であり、Tk の機能に対するインターフェースではないことを示しています。

以下に典型的な使い方の例をいくつか挙げます:

import tkinter as tk

class App(tk.Frame):
    def __init__(self, master=None):
        super().__init__(master)
        self.pack()

# create the application
myapp = App()

#
# here are method calls to the window manager class
#
myapp.master.title("My Do-Nothing Application")
myapp.master.maxsize(1000, 400)

# start the program
myapp.mainloop()

Tk オプションデータ型

anchor

指定できる値はコンパスの方位です: "n" 、 "ne" 、 "e" 、 "se" 、 "s" 、 "sw" 、 "w" 、 "nw" 、および "center" 。

bitmap

八つの組み込み、名前付きビットマップ: 'error' 、 'gray25' 、 'gray50' 、 'hourglass' 、 'info' 、 'questhead' 、 'question' 、 'warning' 。 X ビットマップファイル名を指定するために、 "@/usr/contrib/bitmap/gumby.bit" のような @ を先頭に付けたファイルへの完全なパスを与えてください。

boolean

整数 0 または 1 、あるいは、文字列 "yes" または "no" を渡すことができます。

callback

これは引数を取らない Python 関数ならどれでも構いません。例えば:

def print_it():
    print("hi there")
fred["command"] = print_it

color

Colors can be given as the names of X colors in the rgb.txt file, or as strings representing RGB values in 4 bit: "#RGB", 8 bit: "#RRGGBB", 12 bit: "#RRRGGGBBB", or 16 bit: "#RRRRGGGGBBBB" ranges, where R,G,B here represent any legal hex digit. See page 160 of Ousterhout's book for details.

cursor

cursorfont.h の標準Xカーソル名を、接頭語 XC_ 無しで使うことができます。例えば、handカーソル(XC_hand2)を得るには、文字列 "hand2" を使ってください。あなた自身のビットマップとマスクファイルを指定することもできます。 Ousterhout の本の179ページを参照してください。

distance

スクリーン上の距離をピクセルか絶対距離のどちらかで指定できます。ピクセルは数値として与えられ、絶対距離は文字列として与えられます。絶対距離を表す文字列は、単位を表す終了文字 (センチメートルには c 、インチには i 、ミリメートルには m 、プリンタのポイントには p)を伴います。例えば、3.5インチは "3.5i" と表現します。

font

Tkはフォント名の形式に {courier 10 bold} のようなリストを使います。正の数のフォントサイズはポイント単位で使用され、負の数のサイズはピクセル単位と見なされます。

geometry

これは widthxheight 形式の文字列です。ここでは、ほとんどのウィジェットに対して幅と高さピクセル単位で (テキストを表示するウィジェットに対しては文字単位で)表されます。例えば: fred["geometry"] = "200x100" 。

justify

指定できる値は文字列です: "left" 、 "center" 、 "right" 、そして "fill" 。

region

これは空白で区切られた四つの要素をもつ文字列です。各要素は指定可能な距離です(以下を参照)。例えば: "2 3 4 5" と "3i 2i 4.5i 2i" と "3c 2c 4c 10.43c" は、すべて指定可能な範囲です。

relief

ウィジェットのボーダのスタイルが何かを決めます。指定できる値は: "raised" 、 "sunken" 、 "flat" 、 "groove" 、と "ridge" 。

scrollcommand

これはほとんどの場合スクロールバーウィジェットの set() メソッドですが、1 個の引数を取るあらゆるウィジェットにもなりえます。

wrap

次の中の一つでなければなりません: "none" 、 "char" 、あるいは "word" 。

バインドとイベント

ウィジェットコマンドからの bind メソッドによって、あるイベントを待つことと、そのイベント型が起きたときにコールバック関数を呼び出すことができるようになります。 bind メソッドの形式は:

def bind(self, sequence, func, add=''):

ここでは:

sequence

is a string that denotes the target kind of event. (See the bind(3tk) [https://manpages.debian.org/bind(3tk)] man page, and page 201 of John Ousterhout's book, Tcl and the Tk Toolkit (2nd edition), for details).

func

は一引数を取り、イベントが起きるときに呼び出される Python 関数です。イベント・インスタンスが引数として渡されます。 (このように実施される関数は、一般に callbacks として知られています。)

add

はオプションで、 '' か '+' のどちらかです。空文字列を渡すことは、このイベントが関係する他のどんなバインドをもこのバインドが置き換えることを意味します。 '+' を使う仕方は、この関数がこのイベント型にバインドされる関数のリストに追加されることを意味しています。

例えば:

def turn_red(self, event):
    event.widget["activeforeground"] = "red"

self.button.bind("<Enter>", self.turn_red)

イベントのウィジェットフィールドが turn_red() コールバック内でどのようにアクセスされているかに注目してください。このフィールドは X イベントを捕らえたウィジェットを含んでいます。以下の表はアクセスできる他のイベントフィールドとそれらの Tk での表現方法の一覧です。Tk man ページを参照するときに役に立つでしょう。

Tk

Tkinter イベントフィールド

Tk

Tkinter イベントフィールド

%f

focus

%A

char

%h

高さ

%E

send_event

%k

keycode

%K

keysym

%s

state

%N

keysym_num

%t

time

%T

type

%w

幅

%W

widget

%x

x

%X

x_root

%y

y

%Y

y_root

index パラメータ

多くのウィジェットにはパラメータ "index" を渡す必要があります。これらはテキストウィジェット内の特定の位置や、エントリウィジェット内の特定の文字、あるいはメニューウィジェット内の特定のメニューアイテムを指定するために使用されます。

エントリウィジェットのインデックス(インデックス、ビューインデックスなど)

エントリウィジェットは表示されているテキスト内の文字位置を参照するオプションを持っています。テキストウィジェットにおけるこれらの特別な位置にアクセスするために、次の tkinter 関数を使うことができます:

テキストウィジェットのインデックス

テキストウィジェットに対するインデックス記法はとても機能が豊富で、 Tk manページでよく説明されています。

メニューのインデックス(menu.invoke()、menu.entryconfig()など)

メニューに対するいくつかのオプションとメソッドは特定のメニュー項目を操作します。メニューインデックスはオプションまたはパラメータのために必要とされるときはいつでも、以下のものを渡すことができます:

ウィジェット内の数字の先頭からの位置を指す整数。先頭は 0。

文字列 "active"。現在カーソルがあるメニューの位置を指します。

文字列 "last" 。最後のメニューを指します。

@6 のような @ が前に来る整数。ここでは、整数がメニューの座標系における y ピクセル座標として解釈されます。

文字列 "none"。どんなメニューエントリもまったく指しておらず、ほとんどの場合、すべてのエントリの動作を停止させるために menu.activate() と一緒に使われます。そして、最後に、

メニューの先頭から一番下までスキャンしたときに、メニューエントリのラベルに一致したパターンであるテキスト文字列。このインデックス型は他すべての後に考慮されることに注意してください。その代わりに、それは last 、 active または none とラベル付けされたメニュー項目への一致は上のリテラルとして解釈されることを意味します。

画像

様々な形式の画像を、それに対応する tkinter.Image のサブクラスを使って作成できます:

XBM 形式の画像のための BitmapImage 。

PGM, PPM, GIF, PNG 形式の画像のための PhotoImage 。最後のは Tk 8.6 からサポートされるようになりました。

画像のどちらの型でも file または data オプションを使って作られます (その上、他のオプションも利用できます)。

image オプションがウィジェットにサポートされるところならどこでも、画像オブジェクトを使うことができます (例えば、ラベル、ボタン、メニュー)。これらの場合では、Tk は画像への参照を保持しないでしょう。画像オブジェクトへの最後の Python の参照が削除されたときに、画像データも削除されます。そして、どこで画像が使われていようとも、Tk は空の箱を表示します。

参考

The Pillow [https://python-pillow.org/] package adds support for formats such as BMP, JPEG, TIFF, and WebP, among others.

ファイルハンドラ

Tk を使うとコールバック関数の登録や解除ができ、ファイルディスクリプタに対する入出力が可能なときに、Tk のメインループからその関数が呼ばれます。ファイルディスクリプタ1つにつき、1つだけハンドラは登録されます。コード例です:

import tkinter
widget = tkinter.Tk()
mask = tkinter.READABLE | tkinter.WRITABLE
widget.tk.createfilehandler(file, mask, callback)
...
widget.tk.deletefilehandler(file)

これらの機能は Windows では利用できません。

読み込みに使えるバイト数は分からないので、 BufferedIOBase クラスや TextIOBase クラスの read() メソッドおよび readline() メソッドを使おうとしないでください。これらは読み込みの際に、あらかじめ決められたバイト数を要求するのです。ソケットには、 recv() や recvfrom() メソッドを使うといいです。その他のファイルには、 raw 読み込みか os.read(file.fileno(), maxbytecount) を使ってください。

Widget.tk.createfilehandler(file, mask, func)

ファイルハンドラであるコールバック関数 func を登録します。 file 引数は、 (ファイルやソケットオブジェクトのような) fileno() メソッドを持つオブジェクトか、整数のファイルディスクリプタとなります。 mask 引数は、以下にある3つの定数の組み合わせの OR を取ったものです。コールバックは次のように呼ばれます:

callback(file, mask)

Widget.tk.deletefilehandler(file)

ファイルハンドラの登録を解除します。

_tkinter.READABLE

_tkinter.WRITABLE

_tkinter.EXCEPTION

mask 引数で使う定数です。

tkinter.colorchooser --- Color choosing dialog

ソースコード: Lib/tkinter/colorchooser.py [https://github.com/python/cpython/tree/3.12/Lib/tkinter/colorchooser.py]

Choosertkinter.colorchooser モジュールは Chooser クラスをネイティブカラー選択ダイアログのインターフェースとして提供します。はモーダルなカラー選択ウィンドウを実装しています。 Chooser クラスは Dialog を継承しています。

class tkinter.colorchooser.Chooser(master=None, **options)

tkinter.colorchooser.askcolor(color=None, **options)

カラー選択ダイアログを作成します。このメソッドを呼び出すと、ウィンドウが表示されユーザーが選択するのを待ち、選択された色（もしくは None ）を呼び出し元に返します。

参考

モジュール tkinter.commondialog

Tkinter標準ダイアログモジュール

tkinter.font --- Tkinter font wrapper

ソースコード: Lib/tkinter/font.py [https://github.com/python/cpython/tree/3.12/Lib/tkinter/font.py]

tkinter.font モジュールは名前付きフォントを作成、使用するための Font クラスを提供します。

The different font weights and slants are:

tkinter.font.NORMAL

tkinter.font.BOLD

tkinter.font.ITALIC

tkinter.font.ROMAN

class tkinter.font.Font(root=None, font=None, name=None, exists=False, **options)

The Font class represents a named font. Font instances are given unique names and can be specified by their family, size, and style configuration. Named fonts are Tk's method of creating and identifying fonts as a single object, rather than specifying a font by its attributes with each occurrence.

arguments:

font - font specifier tuple (family, size, options)

name - unique font name

exists - self points to existing named font if true

additional keyword options (ignored if font is specified):

family - font family i.e. Courier, Times

size - font size

If size is positive it is interpreted as size in points.

If size is a negative number its absolute value is treated

as size in pixels.

weight - font emphasis (NORMAL, BOLD)

slant - ROMAN, ITALIC

underline - font underlining (0 - none, 1 - underline)

overstrike - font strikeout (0 - none, 1 - strikeout)

actual(option=None, displayof=None)

Return the attributes of the font.

cget(option)

Retrieve an attribute of the font.

config(**options)

Modify attributes of the font.

copy()

Return new instance of the current font.

measure(text, displayof=None)

Return amount of space the text would occupy on the specified display when formatted in the current font. If no display is specified then the main application window is assumed.

metrics(*options, **kw)

Return font-specific data. Options include:

ascent - distance between baseline and highest point that a

character of the font can occupy

descent - distance between baseline and lowest point that a

character of the font can occupy

linespace - minimum vertical separation necessary between any two

characters of the font that ensures no vertical overlap between lines.

fixed - 1 if font is fixed-width else 0

tkinter.font.families(root=None, displayof=None)

Return the different font families.

tkinter.font.names(root=None)

Return the names of defined fonts.

tkinter.font.nametofont(name, root=None)

Return a Font representation of a tk named font.

バージョン 3.10 で変更: The root parameter was added.

Tkinter ダイアログ

tkinter.simpledialog --- 標準 Tkinter 入力ダイアログ

ソースコード: Lib/tkinter/simpledialog.py [https://github.com/python/cpython/tree/3.12/Lib/tkinter/simpledialog.py]

tkinter.simpledialog モジュールは、ユーザーに値を入力させる単純なモーダルダイアログを作成するための便利なクラスや関数を含んでいます。

tkinter.simpledialog.askfloat(title, prompt, **kw)

tkinter.simpledialog.askinteger(title, prompt, **kw)

tkinter.simpledialog.askstring(title, prompt, **kw)

上の３つの関数は、ユーザーに期待する型の値を入力を促すダイアログを提供します。

class tkinter.simpledialog.Dialog(parent, title=None)

カスタムダイアログ用の基底クラスです。

body(master)

ダイアログインターフェースの構築をオーバーライドし、初期フォーカスを持つべきウィジットを返します。

buttonbox()

デフォルト動作はOKとCancelボタンを追加します。カスタムのボタンレイアウトが必要であればオーバーライドします。

tkinter.filedialog --- ファイル選択ダイアログ

ソースコード: Lib/tkinter/filedialog.py [https://github.com/python/cpython/tree/3.12/Lib/tkinter/filedialog.py]

The tkinter.filedialog module provides classes and factory functions for creating file/directory selection windows.

ネイティブの読み込み/保存ダイアログ

下記のクラスは、振る舞いをカスタマイズできる設定オプション付きの、ネイティブルック＆フィールと統合したファイルダイアログを提供します。以下のキーワード引数は、下記で列挙するクラスや関数に適用できます。

parent - ダイアログをその上に表示するウィンドウ

title - ウィンドウのタイトル

initialdir - 最初に表示するディレクトリ

initialfile - ダイアログを表示した際に選択するファイル

filetypes - (ラベル, パターン) のタプルからなるシーケンスで、'*' ワイルドカードが利用できます

defaultextension - ファイルに追加するデフォルトの拡張子 (保存ダイアログ向け)

multiple - 真の場合、複数要素の選択を許可します

静的なファクトリ関数

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 None to the caller.

tkinter.filedialog.askopenfile(mode='r', **options)

tkinter.filedialog.askopenfiles(mode='r', **options)

The above two functions create an Open dialog and return the opened file object(s) in read-only mode.

tkinter.filedialog.asksaveasfile(mode='w', **options)

Create a SaveAs dialog and return a file object opened in write-only mode.

tkinter.filedialog.askopenfilename(**options)

tkinter.filedialog.askopenfilenames(**options)

The above two functions create an Open dialog and return the selected filename(s) that correspond to existing file(s).

tkinter.filedialog.asksaveasfilename(**options)

Create a SaveAs dialog and return the selected filename.

tkinter.filedialog.askdirectory(**options)

Prompt user to select a directory.

Additional keyword option:

mustexist - determines if selection must be an existing directory.

class tkinter.filedialog.Open(master=None, **options)

class tkinter.filedialog.SaveAs(master=None, **options)

The above two classes provide native dialog windows for saving and loading files.

便利なクラス

The below classes are used for creating file/directory windows from scratch. These do not emulate the native look-and-feel of the platform.

class tkinter.filedialog.Directory(master=None, **options)

Create a dialog prompting the user to select a directory.

注釈

The FileDialog class should be subclassed for custom event handling and behaviour.

class tkinter.filedialog.FileDialog(master, title=None)

Create a basic file selection dialog.

cancel_command(event=None)

Trigger the termination of the dialog window.

dirs_double_event(event)

Event handler for double-click event on directory.

dirs_select_event(event)

Event handler for click event on directory.

files_double_event(event)

Event handler for double-click event on file.

files_select_event(event)

Event handler for single-click event on file.

filter_command(event=None)

Filter the files by directory.

get_filter()

Retrieve the file filter currently in use.

get_selection()

Retrieve the currently selected item.

go(dir_or_file=os.curdir, pattern='*', default='', key=None)

Render dialog and start event loop.

ok_event(event)

Exit dialog returning current selection.

quit(how=None)

Exit dialog returning filename, if any.

set_filter(dir, pat)

Set the file filter.

set_selection(file)

Update the current file selection to file.

class tkinter.filedialog.LoadFileDialog(master, title=None)

A subclass of FileDialog that creates a dialog window for selecting an existing file.

ok_command()

Test that a file is provided and that the selection indicates an already existing file.

class tkinter.filedialog.SaveFileDialog(master, title=None)

A subclass of FileDialog that creates a dialog window for selecting a destination file.

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.

tkinter.commondialog --- Dialog window templates

Source code: Lib/tkinter/commondialog.py [https://github.com/python/cpython/tree/3.12/Lib/tkinter/commondialog.py]

The tkinter.commondialog module provides the Dialog class that is the base class for dialogs defined in other supporting modules.

class tkinter.commondialog.Dialog(master=None, **options)

show(color=None, **options)

Render the Dialog window.

参考

Modules tkinter.messagebox, ファイルを読み書きする

tkinter.messagebox --- Tkinter message prompts

ソースコード: Lib/tkinter/messagebox.py [https://github.com/python/cpython/tree/3.12/Lib/tkinter/messagebox.py]

The tkinter.messagebox module provides a template base class as well as a variety of convenience methods for commonly used configurations. The message boxes are modal and will return a subset of (True, False, None, OK, CANCEL, YES, NO) based on the user's selection. Common message box styles and layouts include but are not limited to:

class tkinter.messagebox.Message(master=None, **options)

Create a message window with an application-specified message, an icon and a set of buttons. Each of the buttons in the message window is identified by a unique symbolic name (see the type options).

The following options are supported:

command

Specifies the function to invoke when the user closes the dialog. The name of the button clicked by the user to close the dialog is passed as argument. This is only available on macOS.

default

Gives the symbolic name of the default button for this message window (OK, CANCEL, and so on). If this option is not specified, the first button in the dialog will be made the default.

detail

Specifies an auxiliary message to the main message given by the message option. The message detail will be presented beneath the main message and, where supported by the OS, in a less emphasized font than the main message.

icon

Specifies an icon to display. If this option is not specified, then the INFO icon will be displayed.

message

Specifies the message to display in this message box. The default value is an empty string.

parent

Makes the specified window the logical parent of the message box. The message box is displayed on top of its parent window.

title

Specifies a string to display as the title of the message box. This option is ignored on macOS, where platform guidelines forbid the use of a title on this kind of dialog.

type

Arranges for a predefined set of buttons to be displayed.

show(**options)

Display a message window and wait for the user to select one of the buttons. Then return the symbolic name of the selected button. Keyword arguments can override options specified in the constructor.

情報メッセージボックス

tkinter.messagebox.showinfo(title=None, message=None, **options)

Creates and displays an information message box with the specified title and message.

警告メッセージボックス

tkinter.messagebox.showwarning(title=None, message=None, **options)

Creates and displays a warning message box with the specified title and message.

tkinter.messagebox.showerror(title=None, message=None, **options)

Creates and displays an error message box with the specified title and message.

質問メッセージボックス

tkinter.messagebox.askquestion(title=None, message=None, *, type=YESNO, **options)

Ask a question. By default shows buttons YES and NO. Returns the symbolic name of the selected button.

tkinter.messagebox.askokcancel(title=None, message=None, **options)

Ask if operation should proceed. Shows buttons OK and CANCEL. Returns True if the answer is ok and False otherwise.

tkinter.messagebox.askretrycancel(title=None, message=None, **options)

Ask if operation should be retried. Shows buttons RETRY and CANCEL. Return True if the answer is yes and False otherwise.

tkinter.messagebox.askyesno(title=None, message=None, **options)

Ask a question. Shows buttons YES and NO. Returns True if the answer is yes and False otherwise.

tkinter.messagebox.askyesnocancel(title=None, message=None, **options)

Ask a question. Shows buttons YES, NO and CANCEL. Return True if the answer is yes, None if cancelled, and False otherwise.

Symbolic names of buttons:

tkinter.messagebox.ABORT = 'abort'

tkinter.messagebox.RETRY = 'retry'

tkinter.messagebox.IGNORE = 'ignore'

tkinter.messagebox.OK = 'ok'

tkinter.messagebox.CANCEL = 'cancel'

tkinter.messagebox.YES = 'yes'

tkinter.messagebox.NO = 'no'

Predefined sets of buttons:

tkinter.messagebox.ABORTRETRYIGNORE = 'abortretryignore'

Displays three buttons whose symbolic names are ABORT, RETRY and IGNORE.

tkinter.messagebox.OK = 'ok'

Displays one button whose symbolic name is OK.

tkinter.messagebox.OKCANCEL = 'okcancel'

Displays two buttons whose symbolic names are OK and CANCEL.

tkinter.messagebox.RETRYCANCEL = 'retrycancel'

Displays two buttons whose symbolic names are RETRY and CANCEL.

tkinter.messagebox.YESNO = 'yesno'

Displays two buttons whose symbolic names are YES and NO.

tkinter.messagebox.YESNOCANCEL = 'yesnocancel'

Displays three buttons whose symbolic names are YES, NO and CANCEL.

Icon images:

tkinter.messagebox.ERROR = 'error'

tkinter.messagebox.INFO = 'info'

tkinter.messagebox.QUESTION = 'question'

tkinter.messagebox.WARNING = 'warning'

tkinter.scrolledtext --- Scrolled Text Widget

ソースコード: Lib/tkinter/scrolledtext.py [https://github.com/python/cpython/tree/3.12/Lib/tkinter/scrolledtext.py]

tkinter.scrolledtext モジュールは"正しい動作"をするように設定された垂直スクロールバーをもつ基本的なテキストウィジェットを実装する同じ名前のクラスを提供します。 ScrolledText クラスを使うことは、テキストウィジェットとスクロールバーを直接設定するより簡単です。

テキストウィジェットとスクロールバーは Frame の中に一緒にpackされ、 Grid と Pack ジオメトリマネジャのメソッドはFrame オブジェクトから得られます。これによって、もっとも標準的なジオメトリマネジャの振る舞いにするために、直接 ScrolledText ウィジェットを使えるようになります。

特定の制御が必要ならば、以下の属性が利用できます:

class tkinter.scrolledtext.ScrolledText(master=None, **kw)

frame

テキストとスクロールバーウィジェットを取り囲むフレーム。

vbar

スクロールバーウィジェット。

tkinter.dnd --- Drag and drop support

ソースコード: Lib/tkinter/dnd.py [https://github.com/python/cpython/tree/3.12/Lib/tkinter/dnd.py]

注釈

This is experimental and due to be deprecated when it is replaced with the Tk DND.

The tkinter.dnd module provides drag-and-drop support for objects within a single application, within the same window or between windows. To enable an object to be dragged, you must create an event binding for it that starts the drag-and-drop process. Typically, you bind a ButtonPress event to a callback function that you write (see バインドとイベント). The function should call dnd_start(), where 'source' is the object to be dragged, and 'event' is the event that invoked the call (the argument to your callback function).

Selection of a target object occurs as follows:

Top-down search of area under mouse for target widget

Target widget should have a callable dnd_accept attribute

If dnd_accept is not present or returns None, search moves to parent widget

If no target widget is found, then the target object is None

Call to <old_target>.dnd_leave(source, event)

Call to <new_target>.dnd_enter(source, event)

Call to <target>.dnd_commit(source, event) to notify of drop

Call to <source>.dnd_end(target, event) to signal end of drag-and-drop

class tkinter.dnd.DndHandler(source, event)

The DndHandler class handles drag-and-drop events tracking Motion and ButtonRelease events on the root of the event widget.

cancel(event=None)

Cancel the drag-and-drop process.

finish(event, commit=0)

Execute end of drag-and-drop functions.

on_motion(event)

Inspect area below mouse for target objects while drag is performed.

on_release(event)

Signal end of drag when the release pattern is triggered.

tkinter.dnd.dnd_start(source, event)

Factory function for drag-and-drop process.

参考

バインドとイベント

tkinter.ttk --- Tk themed widgets

ソースコード: Lib/tkinter/ttk.py [https://github.com/python/cpython/tree/3.12/Lib/tkinter/ttk.py]

tkinter.ttk モジュールは Tk 8.5 で導入された Tk のテーマ付きウィジェットへのアクセスを提供します。これは X11 上のフォントのアンチエイリアスや透過ウィンドウ (X11 ではコンポジションウィンドウマネージャが必要です) を含む、さらなる利点を提供します。

tkinter.ttk の基本的なアイディアは、拡張可能性のためにウィジェットの動作を実装するコードと見た目を記述するコードを分離することです。

参考

Tk Widget Styling Support [https://core.tcl.tk/tips/doc/trunk/tip/48.md]

Tk のテーマサポートを紹介するドキュメント

Ttk を使う

Ttk を使い始めるために、モジュールをインポートします:

from tkinter import ttk

基本的な Tk ウィジェットを上書きするため、次のように Tk のインポートに続けてインポートを行います:

from tkinter import *
from tkinter.ttk import *

このように書くと、いくつかの tkinter.ttk ウィジェット (Button, Checkbutton, Entry, Frame, Label, LabelFrame, Menubutton, PanedWindow, Radiobutton, Scale, Scrollbar) は自動的に Tk ウィジェットを置き換えます。

これにはプラットフォームをまたいでより良い見た目を得られるという、直接的な利益がありますが、ウィジェットは完全な互換性を持っているわけではありません。一番の違いは "fg" や "bg" やその他のスタイルに関係するウィジェットのオプションが Ttk ウィジェットから無くなっていることです。同じ (もしくはより良い) 見た目にするためには ttk.Style を使ってください。

参考

Converting existing applications to use Tile widgets [https://tktable.sourceforge.net/tile/doc/converting.txt]

アプリケーションを移行して新しいウィジェットを使用する際に出くわす典型的な差異について (Tcl の用語を使って) 書かれている研究論文

Ttk ウィジェット

Ttk には 18 のウィジェットがあり、そのうち 12 は Tkinter に既にあるものです: Button, Checkbutton, Entry, Frame, Label, LabelFrame, Menubutton, PanedWindow, Radiobutton, Scale, Scrollbar, Spinbox 。新しい 6 つは次のものです: Combobox, Notebook, Progressbar, Separator, Sizegrip, Treeview 。そして、これらは全て Widget の子クラスです。

Ttk ウィジェットを使用すると、アプリケーションの見た目と使いやすさが向上します。上述の通り、書式をコーディングする方法は異なります。

Tk のコード

l1 = tkinter.Label(text="Test", fg="black", bg="white")
l2 = tkinter.Label(text="Test", fg="black", bg="white")

Ttk のコード:

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")

TtkStyling についての詳細は Style クラスの文書を読んでください。

ウィジェット

ttk.Widget はTk のテーマ付きウィジェットがサポートしている標準のオプションやメソッドを定義するもので、これを直接インスタンス化するものではありません。

標準オプション

All the ttk Widgets accept the following options:

オプション

説明

クラス

ウィンドウクラスを指定します。このクラスはオプションデータベースにウィンドウの他のオプションについて問い合わせを行うときに使われ、これによりウィンドウのデフォルトのバインドタグを決定したり、ウィジェットのデフォルトのレイアウトやスタイルを選択します。このオプションは読み出し専用で、ウィンドウが作成されるときにのみ指定できます。

cursor

このウィジェットで使うマウスカーソルを指定します。空文字列 (デフォルト) が設定されている場合は、カーソルは親ウィジェットのものを引き継ぎます。

takefocus

キーボードによる移動のときにウィンドウがフォーカスを受け入れるかを決定します。0、1、空文字列のいずれかを返します。0 が返されると、キーボードによる移動でそのウィンドウは常にスキップされます。1 なら、そのウィンドウが表示されているときに限り入力フォーカスを受け入れます。そして空文字列は、移動スクリプトによってウィンドウにフォーカスを当てるかどうかが決まることを意味します。

style

独自のウィジェットスタイルを指定するのに使われます。

スクロール可能ウィジェットのオプション

以下のオプションはスクロールバーで操作されるウィジェットが持っているオプションです。

オプション

説明

xscrollcommand

水平方向のスクロールバーとのやり取りに使われます。

ウィジェットのウィンドウが再描画されたとき, ウィジェットは scrollcommand に基いて Tcl コマンドを生成します。

通常このオプションにはあるスクロールバーのメソッド Scrollbar.set() が設定されます。こうすると、ウィンドウの見た目が変わったときにスクロールバーの状態も更新されます。

yscrollcommand

垂直方向のスクロールバーとのやり取りに使われます。詳しくは、上記を参照してください。

ラベルオプション

以下のオプションはラベルやボタンやボタンに類似したウィジェットが持っているオプションです。

オプション

説明

text

ウィジェットに表示される文字列を指定します。

textvariable

text オプションの代わりに使う値の変数名を指定します。

underline

このオプションを設定すると、文字列の中で下線を引く文字のインデックス (0 基点) を指定します。下線が引かれた文字はショートカットとして使われます。

image

表示する画像を指定します。これは 1 つ以上の要素を持つリストです。先頭の要素はデフォルトの画像名です。残りの要素は Style.map() で定義されているような状態名と値のペアの並びで、ウィジェットがある状態、もしくはある状態の組み合わせにいるときに使用する別の画像を指定します。このリストにある全ての画像は同じサイズでなればなりません。

compound

text オプションと image オプションが両方とも指定されていた場合に、テキストに対して画像をどう配置するかを指定します。適当な値は:

text: テキストのみ表示する

image: 画像のみ表示する

top, bottom, left, right: それぞれ画像をテキストの上、下、左、右に配置する。

none: デフォルト。もしあれば画像を表示し、そうでなければテキストを表示する。

幅

0 より大きい場合、テキストラベルを作成するのにどれくらいのスペースを使うかを文字の幅で指定します。0 より小さい場合、最小の幅が指定されます。0 もしくは無指定の場合、テキストラベルに対して自然な幅が使われます。

互換性オプション

オプション

説明

state

"normal" か "disabled" に設定され、 "disabled" 状態のビットをコントロールします。これは書き込み専用のオプションです: これを設定するとウィジェットの状態を変更できますが、 Widget.state() メソッドはこのオプションに影響を及ぼしません。

ウィジェットの状態

ウィジェットの状態は独立した状態フラグのビットマップです。

Flag

説明

active

マウスカーソルがウィジェットの上にあり、マウスのボタンをクリックすることで何らかの動作をさせられます

disabled

プログラムによってウィジェットは無効化されています

focus

ウィジェットにキーボードフォーカスがあります

pressed

ウィジェットは押されています

selected

チェックボタンやラジオボタンのようなウィジェットでの "オン" や "チェック有" や "選択中" に当たります

background

Windows と Mac には "アクティブな" もしくは最前面のウィンドウという概念があります。背面のウィンドウにあるウィジェットには background 状態が設定され、最前面のウィンドウにあるウィジェットでは解除されます

readonly

ウィジェットはユーザからの変更を受け付けません

alternate

ウィジェット特有の切り替え表示になっています

invalid

ウィジェットの値が不正です

状態仕様は状態名の並びになっていて、状態名の先頭にはビットがオフになっていることを示す感嘆符が付くことがあります。

ttk.Widget

以下に書かれているメソッドに加えて、 ttk.Widget は tkinter.Widget.cget() メソッドと tkinter.Widget.configure() メソッドをサポートしています。

class tkinter.ttk.Widget

identify(x, y)

x y の位置にある要素の名前、もしくはその位置に要素が無ければ空文字列を返します。

x と y はウィジェットに対するピクセル単位の座標です。

instate(statespec, callback=None, *args, **kw)

ウィジェットの状態をチェックします。コールバックが指定されていない場合、ウィジェットの状態が statespec に一致していれば True 、そうでなければ False を返します。コールバックが指定されていて、ウィジェットの状態が statespec に一致している場合、引数に args を指定してそのコールバックを呼び出します。

state(statespec=None)

ウィジェットの状態を変更したり、取得したりします。statespec が指定されている場合、それに応じてウィジェットの状態を設定し、どのフラグが変更されたかを示す新しい statespec を返します。statespec が指定されていない場合、現在の状態フラグを返します。

通常 statespec はリストもしくはタプルです。

コンボボックス

ttk.Combobox ウィジェットはテキストフィールドと値のポップダウンリストを結び付けます。このウィジェットは Entry の子クラスです。

Widget から継承したメソッド (Widget.cget(), Widget.configure(), Widget.identify(), Widget.instate(), Widget.state()) と以下の Entry から継承したメソッド (Entry.bbox(), Entry.delete(), Entry.icursor(), Entry.index(), Entry.insert(), Entry.selection(), Entry.xview()) に加え、このクラスには ttk.Combobox で説明するメソッドがあります。

オプション

このウィジェットは以下の固有のオプションを受け付けます:

オプション

説明

exportselection

真偽値を取る。設定されている場合、ウィジェットの選択はウィンドウマネージャの選択とリンクしています (例えば、Misc.selection_get を実行することで得られます)。

justify

ウィジェットの中でテキストをどう配置するかを指定します。 "left", "center", "right" のうちのどれか 1 つです。

高さ

ポップダウンリストの高さを行数で指定します。

postcommand

コンボボックスの値を表示する直前に呼び出される、(Misc.register などで登録した) スクリプトです。どの値を表示するかについても指定できます。

state

"normal", "readonly", "disabled" のどれか 1 つです。"readonly" 状態では、直接入力値を編集することはできず、ユーザはドロップダウンリストから値を 1 つ選ぶことしかできません。"normal" 状態では、テキストフィールドは直接編集できます。"disabled" 状態では、コンボボックスは一切反応しません。

textvariable

コンボボックスの値とリンクさせる変数名を指定します。その変数の値が変更されたとき、ウィジェットの値は更新されます。ウィジェットの値が更新されたときも同様です。 tkinter.StringVar を参照してください。

values

ドロップダウンリストに表示する値のリストを指定します。

幅

入力ウィンドウに必要な幅をウィジェットのフォントの平均的なサイズの文字で測った、文字数を指定します。

仮想イベント

コンボボックスウィジェットは、ユーザが値のリストから1つ選んだときに仮想イベント <<ComboboxSelected>> を生成します。

ttk.Combobox

class tkinter.ttk.Combobox

current(newindex=None)

newindex が指定されている場合、コンボボックスの値がドロップダウンリストの newindex の位置にある値に設定されます。そうでない場合、現在の値のインデックスを、もしくは現在の値がリストに含まれていないなら -1 を返します。

get()

コンボボックスの現在の値を返します。

set(value)

コンボボックスの値を value に設定します。

Spinbox

The ttk.Spinbox widget is a 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 Entry.

Widget から継承したメソッド: Widget.cget(), Widget.configure(), Widget.identify(), Widget.instate(), Widget.state() と、以下の Entry から継承したメソッド: Entry.bbox(), Entry.delete(), Entry.icursor(), Entry.index(), Entry.insert(), Entry.xview() に加え、このクラスには ttk.Spinbox で説明するいくつかのメソッドがあります。

オプション

このウィジェットは以下の固有のオプションを受け付けます:

オプション

説明

from

Float value. If set, this is the minimum value to which the decrement button will decrement. Must be spelled as from_ when used as an argument, since from is a Python keyword.

to

Float value. If set, this is the maximum value to which the increment button will increment.

increment

Float value. Specifies the amount which the increment/decrement buttons change the value. Defaults to 1.0.

values

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.

wrap

Boolean value. If True, increment and decrement buttons will cycle from the to value to the from value or the from value to the to value, respectively.

format

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.

command

Python callable. Will be called with no arguments whenever either of the increment or decrement buttons are pressed.

仮想イベント

The spinbox widget generates an <<Increment>> virtual event when the user presses <Up>, and a <<Decrement>> virtual event when the user presses <Down>.

ttk.Spinbox

class tkinter.ttk.Spinbox

get()

Returns the current value of the spinbox.

set(value)

Sets the value of the spinbox to value.

ノートブック

ノートブックウィジェットは複数のウィンドウを管理し、同時に 1 つのウィンドウを表示します。それぞれの子ウィンドウはタブの関連付けられていて、ユーザはそれを選択して表示されているウィンドウを切り替えます。

オプション

このウィジェットは以下の固有のオプションを受け付けます:

オプション

説明

高さ

0 より大きな値が設定されている場合、 (内部のパディングやタブを含まない) ペイン領域に必要な高さを指定します。設定されていない場合、全てのペインの高さの最大値が使われます。

padding

ノートブックの外周に付け足す追加の領域の量を指定します。パディングは最大 4 個の長さ指定のリストです: 左、上、右、下の順で指定します。4 個より少ない場合、デフォルトで下は上と、右は左と、上は左と同じ値が、それぞれ使われます。

幅

0 より大きな値が指定されている場合、(内部のパディングを含まない) ペイン領域に必要な幅を指定します。設定されていない場合、全てのペインの幅の最大値が使われます。

タブオプション

タブ用のオプションもあります:

オプション

説明

state

"normal", "disabled", "hidden" のうちどれか 1 つです。 "disabled" の場合、タブは選択することができません。 "hidden" の場合、タブは表示されません。

sticky

ペイン領域の中に子ウィンドウがどう置かれるかを指定します。指定する値は "n", "s", "e", "w" からなる 0 文字以上の文字列です。配置マネージャの grid() と同様に、それぞれの文字は子ウィンドウが (北、南、東、西の) どの辺に対して追随するかに対応しています。

padding

ノートブックとこのペインの間に付け足す追加の領域の量を指定します。文法はこのウィジェットの padding オプションと同じです。

text

タブに表示するテキストを指定します。

image

タブに表示する画像を指定します。 Widget のオプション image の説明を参照してください。

compound

text オプションと image オプションが両方指定されているときにテキストに対して画像をどう表示するかを指定します。指定する値については Label Options を参照してください。

underline

テキスト中の下線を引く文字のインデックス (0 基点) を指定します。 Notebook.enable_traversal() が呼ばれていた場合、下線が引かれた文字はショートカットとして使われます。

タブ識別子

ttk.Notebook のいくつかのメソッドにある tab_id は以下の形式を取ります:

0 からタブの数の間の整数

子ウィンドウの名前

タブを指し示す "@x,y" という形式の位置指定

現在選択されているタブを指し示すリテラル文字列 "current"

タブ数を返すリテラル文字列 "end" (Notebook.index() でのみ有効)

仮想イベント

このウィジェットは新しいタブが選択された後に仮想イベント <<NotebookTabChanged>> を生成します。

ttk.Notebook

class tkinter.ttk.Notebook

add(child, **kw)

ノートブックに新しいタブを追加します。

ウィンドウが現在ノートブックによって管理されているが隠れている場合、以前の位置に復元します。

利用可能なオプションのリストについては Tab Options を参照してください。

forget(tab_id)

tab_id で指定されたタブを削除します。関連付けられていたウィンドウは切り離され、管理対象でなくなります。

hide(tab_id)

tab_id で指定されたタブを隠します。

タブは表示されませんが、関連付いているウィンドウはノートブックによって保持されていて、その設定も記憶されています。隠れたタブは add() コマンドで復元できます。

identify(x, y)

x y の位置にあるタブの名前を、そこにタブが無ければ空文字列を返します。

index(tab_id)

tab_id で指定されたタブのインデックスを、 tab_id が文字列の "end" だった場合はタブの総数を返します。

insert(pos, child, **kw)

指定された位置にペインを挿入します。

pos は文字列の "end" か整数のインデックスか管理されている子ウィンドウの名前です。 child が既にノートブックの管理対象だった場合、指定された場所に移動させます。

利用可能なオプションのリストについては Tab Options を参照してください。

select(tab_id=None)

指定された tab_id を選択します。

関連付いている子ウィンドウは表示され、直前に選択されていたウィンドウは (もし異なれば) 表示されなくなります。 tab_id が指定されていない場合は、現在選択されているペインのウィジェット名を返します。

tab(tab_id, option=None, **kw)

指定された tab_id のオプションを問い合わせたり、変更したりします。

kw が与えられなかった場合、タブのオプション値の辞書を返します。 option が指定されていた場合、その option の値を返します。それ以外の場合は、オプションに対応する値が設定されます。

tabs()

ノートブックに管理されているウィンドウのリストを返します。

enable_traversal()

このノートブックを含む最上位にあるウィンドウでのキーボード移動を可能にします。

これによりノートブックを含んだ最上位にあるウィンドウに対し、以下のキーバインディングが追加されます:

Control-Tab: 現在選択されているタブの 1 つ次のタブを選択します。

Shift-Control-Tab: 現在選択されているタブの 1 つ前のタブを選択します。

Alt-K: K があるタブの (下線が引かれた) ショートカットキーだとして、そのタブを選択します。

ネストしたノートブックも含め、1 つのウィンドウの最上位にある複数のノートブックのキーボード移動が可能になることもあります。しかしノートブック上の移動は、全てのペインが同じノートブックを親としているときのみ正しく動作します。

プログレスバー

ttk.Progressbar ウィジェットは長く走る処理の状態を表示します。このウィジェットは 2 つのモードで動作します: 1) 決定的モードでは、全ての処理の総量のうち完了した量を表示します。 2) 非決定的モードでは、今作業が進んでいることをユーザに示します。

オプション

このウィジェットは以下の固有のオプションを受け付けます:

オプション

説明

orient

"horizontal" もしくは "vertical" のいずれかです。プログレスバーの方向を指定します。

length

プログレスバーの長さを指定します。 (水平方向の場合は幅、垂直方向の場合は高さです)

mode

"determinate" か "indeterminate" のいずれかです。

maximum

最大値を数値で指定します。デフォルトは 100 です。

value

プログレスバーの現在値です。決定的 ("determinate") モードでは、完了した処理の量を表します。非決定的 ("indeterminate") モードでは、 maximum を法として解釈され、値が maximum に達したときにプログレスバーは 1 "サイクル" を完了したことになります。

variable

value オプションとリンクさせる変数名です。指定されている場合、変数の値が変更されるとプログレスバーの値は自動的にその値に設定されます。

phase

読み出し専用のオプションです。このウィジェットの値が 0 より大きく、かつ決定的モードでは最大値より小さいときに、ウィジェットが定期的にこのオプションの値を増加させます。このオプションは現在の画面テーマが追加のアニメーション効果を出すのに使います。

ttk.Progressbar

class tkinter.ttk.Progressbar

start(interval=None)

自動増加モードを開始します: interval ミリ秒ごとに Progressbar.step() を繰り返し呼び出すタイマーイベントを設定します。引数で指定しない場合は、 interval はデフォルトで 50 ミリ秒になります。

step(amount=None)

プログレスバーの値を amount だけ増加させます。

引数で指定しない場合は、 amount はデフォルトで 1.0 になります。

stop()

自動増加モードを停止します: このプログレスバーの Progressbar.start() で開始された繰り返しのタイマーイベントを全てキャンセルします。

セパレータ

ttk.Separator ウィジェットは水平もしくは垂直のセパレータを表示します。

ttk.Widget から継承したメソッド以外にメソッドを持ちません。

オプション

このウィジェットは次の特定のオプションを受け付けます。

オプション

説明

orient

"horizontal" か "vertical" のいずれかです。セパレータの方向を指定します。

サイズグリップ

(グローボックスとしても知られる) ttk.Sizegrip ウィジェットを使用すると、つまみ部分を押してドラッグすることで、このウィジェットを含む最上位のウィンドウのサイズを変更できます。

このウィジェットは ttk.Widget から継承したもの以外のオプションとメソッドを持ちません。

プラットフォーム固有のメモ

macOS では、最上位のウィンドウにはデフォルトで組み込みのサイズグリップが含まれています。組み込みのグリップが Sizegrip を隠してしまうので、 Sizegrip を追加しても問題ありません。

バグ

このウィジェットを含む最上位のウィンドウの位置がスクリーンの右端や下端に対して相対的に指定されている場合 (例: ....) 、 Sizegrip ウィジェットはウィンドウのサイズ変更をしません。

このウィジェットは "南東" 方向のサイズ変更しかサポートしていません。

ツリービュー

ttk.Treeview ウィジェットは階層のある要素 (アイテム) の集まりを表示します。それぞれの要素はテキストラベル、オプションの画像、オプションのデータのリストを持っています。データはラベルの後に続くカラムに表示されます。

データが表示される順序はウィジェットの displaycolumns オプションで制御されます。ツリーウィジェットはカラムヘッダを表示することもできます。カラムには数字もしくはウィジェットの columns オプションにある名前でアクセスできます。 Column Identifiers を参照してください。

それぞれの要素は一意な名前で識別されます。要素の作成時に識別子が与えられなかった場合、ウィジェットが要素の識別子を生成します。このウィジェットには {} という名前の特別なルート要素があります。ルート要素自身は表示されません; その子要素たちが階層の最上位に現れます。

それぞれの要素はタグのリストも持っていて、イベントバインディングと個別の要素を関連付け、要素の見た目を管理するのに使えます。

ツリービューウィジェットは水平方向と垂直方向のスクロールをサポートしていて、 Scrollable Widget Options に記述してあるオプションと Treeview.xview() メソッドおよび Treeview.yview() メソッドが使えます。

オプション

このウィジェットは以下の固有のオプションを受け付けます:

オプション

説明

columns

カラム数とその名前を指定するカラム識別子のリストです。

displaycolumns

どのデータカラムをどの順序で表示するかを指定する、 (名前もしくは整数のインデックスの) カラム識別子のリストか、文字列 "#all" です。

高さ

表示する行数を指定します。メモ: 表示に必要な幅はカラム幅の合計から決定されます。

padding

ウィジェットの内部のパディングのサイズを指定します。パディングは最大 4 個の長さ指定のリストです。

selectmode

組み込みのクラスバインディングが選択状態をどう管理するかを指定します。設定する値は "extended", "browse", "none" のどれか 1 つです。 "extended" に設定した場合 (デフォルト)、複数の要素が選択できます。 "browse" に設定した場合、同時に 1 つの要素しか選択できません。 "none" に設定した場合、選択を変更することはできません。

このオプションの値によらず、アプリケーションのコードと関連付けられているタグからは好きなように選択状態を設定できます。

show

ツリーのどの要素を表示するかを指定する、以下にある値を 0 個以上含むリストです。

tree: カラム #0 にツリーのラベルを表示します。

headings: ヘッダ行を表示します。

デフォルトは "tree headings" 、つまり全ての要素を表示します。

メモ: show="tree" が指定されていない場合でも、カラム #0 は常にツリーカラムを参照します。

要素オプション

以下の要素オプションは、ウィジェットの insert コマンドと item コマンドで要素に対して指定できます。

オプション

説明

text

アイテムに表示するテキストラベルです。

image

ラベルの左に表示される Tk 画像です。

values

要素に関連付けられている値のリストです。

それぞれの要素はウィジェットの columns オプションと同じ数の値を持たなければいけません。 columns オプションより少ない場合、残りの値は空として扱われます。 columns オプションより多い場合、余計な値は無視されます。

open

要素の子供を表示するか隠すかを指示する True/False 値です。

tags

この要素に関連付いているタグのリストです。

タグオプション

以下のオプションはタグに対して設定できます:

オプション

説明

foreground

テキストの色を指定します。

background

セルや要素の背景色を指定します。

font

テキストを描画するときに使うフォントを指定します。

image

要素の image オプションが空だった場合に使用する画像を指定します。

カラム識別子

カラム識別子は以下のいずれかの形式を取ります:

columns オプションのリストにある名前。

n 番目のデータカラムを指し示す整数 n 。

n を整数として n 番目の表示されているカラムを指し示す #n という形式の文字列。

注釈:

要素のオプション値は実際に格納されている順序とは違った順序で表示されることがあります。

show="tree" が指定されていない場合でも、カラム #0 は常にツリーカラムを指しています。

データカラムを指す数字は、要素の values オプションのリストのインデックスです; 表示カラムを指す数字は、値が表示されているツリーのカラム番号です。ツリーラベルはカラム #0 に表示されます。 displaycolumns オプションが設定されていない場合は、 n 番目のデータカラムはカラム #n+1 に表示されます。再度言っておくと、 カラム #0 は常にツリーカラムを指します 。

仮想イベント

ツリービューは以下の仮想イベントを生成します。

Event

説明

<<TreeviewSelect>>

選択状態が変更されたときに生成されます。

<<TreeviewOpen>>

フォーカスが当たっている要素に open=True が設定される直前に生成されます。

<<TreeviewClose>>

フォーカスが当たっている要素に open=False が設定された直後に生成されます。

Treeview.focus() メソッドと Treeview.selection() メソッドは変更を受けた要素を判別するのに使えます。

ttk.Treeview

class tkinter.ttk.Treeview

bbox(item, column=None)

(ツリービューウィジェットのウィンドウを基準として) 指定された item のバウンディングボックス情報を (x 座標, y 座標, 幅, 高さ) の形式で返します。

column が指定されている場合は、セルのバウンディングボックスを返します。 (例えば、閉じた状態の要素の子供であったり、枠外にスクロールされていて) item が見えなくなっている場合は、空文字列が返されます。

get_children(item=None)

item の子要素のリストを返します。

item が指定されていなかった場合は、ルート要素の子供が返されます。

set_children(item, *newchildren)

item の子要素を newchildren で置き換えます。

item にいる子供のうち newchildren にないものはツリーから切り離されます。 newchildren にあるどの要素も item の祖先であってはいけません。 newchildren を指定しなかった場合は、 item の子要素が全て切り離されることに注意してください。

column(column, option=None, **kw)

指定した column のオプションを問い合わせたり、変更したりします。

kw が与えられなかった場合は、カラムのオプション値の辞書が返されます。 option が指定されていた場合は、その option の値が返されます。それ以外の場合は、オプションに値を設定します。

設定できるオプションとその値は次の通りです:

id

カラム名を返します。これは読み出し専用のオプションです。

anchor: One of the standard Tk anchor values.

このカラムでセルに対してテキストをどう配置するかを指定します。

minwidth: width

カラムの最小幅をピクセル単位で表したものです。ツリービューウィジェットは、ウィジェットのサイズが変更されたりカラムをユーザがドラッグして移動させたりしたときに、このオプションで指定した幅より狭くすることはありません。

stretch: True/False

ウィジェットがサイズ変更されたとき、カラムの幅をそれに合わせるかどうかを指定します。

width: width

カラムの幅をピクセル単位で表したものです。

ツリーカラムの設定を行うには、 column = "#0" を付けてこのメソッドを呼び出してください。

delete(*items)

指定された items とその子孫たち全てを削除します。

ルート要素は削除されません。

detach(*items)

指定された items を全てツリーから切り離します。

その要素と子孫たちは依然として存在していて、ツリーの別の場所に再度挿入することができますが、隠された状態になり表示はされません。

ルート要素は切り離されません。

exists(item)

指定された item がツリーの中にあれば True を返します。

focus(item=None)

item が指定されていた場合は、 item にフォーカスを当てます。そうでない場合は、現在フォーカスが当たっている要素が、どの要素にもフォーカスが当たっていない場合は '' が返されます。

heading(column, option=None, **kw)

指定された column の heading のオプションを問い合わせたり、変更したりします。

kw が与えられなかった場合は、見出しのオプション値の辞書が返されます。 option が指定されている場合は、 option の値が返されます。それ以外の場合は、オプションに値を設定します。

設定できるオプションとその値は次の通りです:

text: text

カラムの見出しに表示するテキスト。

image: imageName

カラムの見出しの右に表示する画像を指定します。

anchor: anchor

見出しのテキストをどう配置するかを指定します。標準の Tk anchor の値です。

command: callback

見出しラベルがクリックされたときに実行されるコールバックです。

ツリーカラムの見出しの設定を行うには、 column = "#0" を付けてこのメソッドを呼び出してください。

identify(component, x, y)

x y で与えられた場所にある指定された component の説明を返します。その場所に指定された component が無い場合は空文字列を返します。 (訳注: component には "region", "item", "column", "row", "element" が指定でき、それぞれ "cell", "heading" などの場所の名前、要素の識別子、 #n という形式のカラム名、その行にある要素の識別子、 "text", "padding" などの画面構成要素の名前を返します。)

identify_row(y)

y 座標が y の位置にある要素の識別子を返します。

identify_column(x)

x 座標が x の位置にあるセルのデータカラムの識別子を返します。

ツリーカラムは #0 という識別子を持ちます。

identify_region(x, y)

以下のうち 1 つを返します:

region

意味

heading

ツリーの見出し領域

separator

2 つのカラム見出しの間のスペース

tree

ツリーの領域

cell

データセル

使用可能バージョン: Tk 8.6

identify_element(x, y)

x y の位置にある画面構成要素の名前を返します。

使用可能バージョン: Tk 8.6

index(item)

親要素の子要素リストの中での item のインデックスを返します。

insert(parent, index, iid=None, **kw)

新しい要素を作り、その要素の識別子を返します。

parent は親となる要素の識別子で、空文字列にすると新しい要素を最上位に作成します。 index は整数もしくは "end" という値で、それによって親要素の子要素リストのどこに新しい要素を挿入するかを指定します。 index が 0 以下だった場合は、新しい要素は先頭に挿入されます; index が現在の子要素の数以上だった場合は末尾に挿入されます。 iid が指定された場合は、要素の識別子として使われます; iid はまだツリーに存在していないものに限ります。それ以外の場合は、一意な識別子が生成されます。

See Item Options for the list of available options.

item(item, option=None, **kw)

指定された item のオプションを問い合わせたり、変更したりします。

オプションが与えられなかった場合は、要素のオプションと値が辞書の形で返されます。 option が指定された場合は、そのオプションの値が返されます。それ以外の場合は、 kw で与えられたようにオプションに値が設定されます。

move(item, parent, index)

item を parent の子要素リストの index の位置に移動します。

要素を自身の子孫の下に移動させるのは許されていません。 index が 0 以下の場合、 item は先頭に移動されます; 子要素の数以上だった場合、末尾に移動されます。 item が切り離された状態の場合は、再度取り付けられます。

next(item)

item の 1 つ下の兄弟の識別子を、 item が親にとって一番下の子供だった場合 '' を返します。

parent(item)

item の親の識別子を、 item が階層の最上位にいた場合 '' を返します。

prev(item)

item の 1 つ上の兄弟の識別子を、 item が親にとって一番上の子供だった場合 '' を返します。

reattach(item, parent, index)

Treeview.move() のエイリアスです。

see(item)

item を見える状態にします。

item の全ての子孫の open オプションを True にし、必要であれば item がツリーの見える範囲に来るようにウィジェットをスクロールさせます。

selection()

Returns a tuple of selected items.

バージョン 3.8 で変更: selection() no longer takes arguments. For changing the selection state use the following selection methods.

selection_set(*items)

新しく選択状態の要素が items になります。

バージョン 3.6 で変更: items は 1 つのタプルとしてだけでなく、別々の引数としても渡せます。

selection_add(*items)

選択状態の要素として items を追加します。

バージョン 3.6 で変更: items は 1 つのタプルとしてだけでなく、別々の引数としても渡せます。

selection_remove(*items)

選択状態の要素から items を取り除きます。

バージョン 3.6 で変更: items は 1 つのタプルとしてだけでなく、別々の引数としても渡せます。

selection_toggle(*items)

items のそれぞれの要素の選択状態を入れ替えます。

バージョン 3.6 で変更: items は 1 つのタプルとしてだけでなく、別々の引数としても渡せます。

set(item, column=None, value=None)

1 引数で呼び出された場合、指定された item のカラムと値のペアからなる辞書を返します。 2 引数で呼び出された場合、指定された column の現在の値を返します。 3 引数で呼び出された場合、与えられた item の column を指定された値 value に設定します。

tag_bind(tagname, sequence=None, callback=None)

与えられたイベント sequence 用のコールバックをタグ tagname にバインドします。イベントが要素に渡ってきたときに、要素の tags オプションのそれぞれのコールバックが呼び出されます。

tag_configure(tagname, option=None, **kw)

指定された tagname のオプションを問い合わせたり、変更したりします。

kw が与えられなかった場合、 tagname のオプション設定を辞書の形で返します。 option が指定された場合、指定された tagname の option の値を返します。それ以外の場合、与えられた tagname のオプションに値を設定します。

tag_has(tagname, item=None)

item が指定されていた場合、指定された item が与えられた tagname を持っているかどうかに従って 1 または 0 が返されます。そうでない場合、指定されたタグを持つ全ての要素のリストを返します。

使用可能バージョン: Tk 8.6

xview(*args)

ツリービューの水平方向の位置を問い合わせたり、変更したりします。

yview(*args)

ツリービューの垂直方向の位置を問い合わせたり、変更したりします。

Ttk スタイル

ttk のそれぞれのウィジェットにはスタイルが関連付けられていて、それと動的もしくはデフォルトで設定される要素のオプションによってウィジェットを構成する要素とその配置を指定します。デフォルトではスタイル名はウィジェットのクラス名と同じですが、ウィジェットの style オプションで上書きすることができます。ウィジェットのクラス名が分からない場合は、 Misc.winfo_class() (somewidget.winfo_class()) メソッドを使ってください。

参考

Tcl'2004 conference のプレゼンテーション [https://tktable.sourceforge.net/tile/tile-tcl2004.pdf]

この文書ではテーマエンジンがどう動くかを説明しています

class tkinter.ttk.Style

このクラスはスタイルデータベースを操作するために使われます。

configure(style, query_opt=None, **kw)

style の指定されたオプションのデフォルト値を問い合わせたり、設定したりします。

kw のそれぞれのキーはオプション名で値はそのオプションの値の文字列です。

例えば、全てのデフォルトのボタンをパディングのある平らな見た目にし、背景の色を変更するには以下のようにします:

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()

map(style, query_opt=None, **kw)

style の指定されたオプションの動的な値を問い合わせたり、設定したりします。

kw のそれぞれのキーはオプション名で、値はタプルやリストや何か他のお好みのものでグループ化された状態仕様 (statespec) を要素とするリストやタプルです。状態仕様は 1 つもしくは複数の状態と値の組み合わせです。

以下のように、例を示す方がわかりやすいでしょう:

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()

あるオプションに対する状態と値の組 (states, value) の並び順はスタイルに影響を与えることに注意してください。例えば、foreground オプションの順序を [('active', 'blue'), ('pressed', 'red')] に変更した場合、ウィジェットがアクティブもしくは押された状態のとき前面が青くなります。

lookup(style, option, state=None, default=None)

style の指定された option の値を返します。

state を指定する場合は、1 つ以上の状態名の並びである必要があります。 default 引数が指定されていた場合は、オプション指定が見付からなかったときに代わりに返される値として使われます。

デフォルトでボタンがどのフォントを使うかを調べるには、以下のように実行します:

from tkinter import ttk

print(ttk.Style().lookup("TButton", "font"))

layout(style, layoutspec=None)

与えられた style でのウィジェットのレイアウトを定義します。 layoutspec が省略されていた場合は、与えられたスタイルのレイアウト仕様を返します。

layoutspec を指定する場合は、リストもしくは (文字列を除いた) 何か他のシーケンス型である必要があります。それぞれの要素はタプルで、レイアウト名を 1 番目の要素とし、2 番目の要素は Layouts で説明されているフォーマットである必要があります。

フォーマットを理解するために以下の例を見てください (何かを使い易くするための例ではありません):

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()

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" or "from".

"image" が使われた場合、 args はデフォルトの画像名の後ろに状態仕様と値のペア (これが画像仕様です) を並べたものである必要があります。 kw には以下のオプションが指定できます:

border=padding

padding は 4 個以下の整数のリストで、それぞれ左、上、右、下の縁の幅を指定します。

height=height

要素の最小の高さを指定します。0 より小さい場合は、画像の高さをデフォルトとして使用します。

padding=padding

要素の内部のパディングを指定します。指定されない場合は、 border の値がデフォルトとして使われます。

sticky=spec

1 つ外側の枠に対し画像をどう配置するかを指定します。 spec は "n", "s", "w", "e" の文字を 0 個以上含みます。

width=width

要素の最小の幅を指定します。0 より小さい場合は、画像の幅をデフォルトとして使用します。

以下はプログラム例です:

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')

etype の値として "from" が使われた場合は、 element_create() が現在の要素を複製します。 args は要素の複製元のテーマの名前と、オプションで複製する要素を含んでいる必要があります。複製元の要素が指定されていなかった場合、空要素が使用され、 kw は破棄されます。

以下はプログラム例です:

style = ttk.Style(root)
style.element_create('plain.background', 'from', 'default')

element_names()

現在のテーマに定義されている要素のリストを返します。

element_options(elementname)

elementname のオプションのリストを返します。

theme_create(themename, parent=None, settings=None)

新しいテーマを作成します。

themename が既に存在していた場合はエラーになります。 parent が指定されていた場合は、新しいテーマは親テーマからスタイルや要素やレイアウトを継承します。 settings が指定された場合は、 theme_settings() で使われるのと同じ形式である必要があります。

theme_settings(themename, settings)

一時的に現在のテーマを themename に設定し、指定された settings を適用した後、元のテーマを復元します。

settings のそれぞれのキーはスタイル名で値はさらに 'configure', 'map', 'layout', 'element create' をキーとして持ち、その値はそれぞれ Style.configure(), Style.map(), Style.layout(), Style.element_create() メソッドで指定するのと同じ形式である必要があります。

例として、コンボボックスの default テーマを少し変更してみましょう

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()

theme_names()

全ての既存のテーマのリストを返します。

theme_use(themename=None)

themename が与えられなかった場合は、現在使用中のテーマ名を返します。そうでない場合は、現在のテーマを themename に設定し、全てのウィジェットを再描画し、 <<ThemeChanged>> イベントを発生させます。

レイアウト

A layout can be just 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.

設定できるオプションとその値は次の通りです:

side: whichside

要素を空間のどちら側に配置するかを指定します; top, right, bottom, left のどれか 1 つです。省略された場合は、要素は空間全体を占めます。

sticky: nswe

配分された空間の内部に要素をどう配置するかを指定します。

unit: 0 or 1

1 に設定されると、 Widget.identify() などには要素とその子で単一の要素として扱われます。これは、グリップのついたスクロールバーサムのようなものに使われます。

children: [sublayout... ]

要素の内部に配置する要素のリストを指定します。リストのそれぞれの要素はタプル (もしくは他のシーケンス型) で、それの 1 番目の要素はレイアウト名でそれ以降は Layout です。

tkinter.tix --- Tkの拡張ウィジェット

ソースコード: Lib/tkinter/tix.py [https://github.com/python/cpython/tree/3.12/Lib/tkinter/tix.py]

バージョン 3.6 で非推奨: この Tk 拡張は保守されておらず、新しいコードでは使うべきではありません。その代わりに tkinter.ttk を使ってください。

tkinter.tix (Tk Interface Extension) モジュールは豊富な追加ウィジェットを提供します。標準 Tk ライブラリには多くの有用なウィジェットがありますが、決して完全ではありません。 tkinter.tix ライブラリは、HList 、 ComboBox 、 Control (別名SpinBox) および各種のスクロール可能なウィジェットなど、標準 Tk にはないが、一般的に必要とされるウィジェットの大部分を提供します。 tkinter.tix には、NoteBook 、 FileEntry 、 PanedWindow など、一般的に幅広い用途に役に立つたくさんのウィジェットも含まれています。それらは40以上あります。

これら多くの新しいウィジェットと使うと、より便利でより直感的なユーザインターフェースを作成し、新しい相互作用テクニックをアプリケーションに導入することができます。アプリケーションとユーザに特有の要求に合うように、最も適切なアプリケーションウィジェットを選んでアプリケーションを設計できます。

参考

Tix Homepage [https://tix.sourceforge.net/]

Tix のホームページ。ここには追加ドキュメントとダウンロードへのリンクがあります。

Tix Man Pages [https://tix.sourceforge.net/dist/current/man/]

manページと参考資料のオンライン版。

Tix Programming Guide [https://tix.sourceforge.net/dist/current/docs/tix-book/tix.book.html]

プログラマ用参考資料のオンライン版。

Tix Development Applications [https://tix.sourceforge.net/Tixapps/src/Tide.html]

Tix と Tkinter プログラムの開発のための Tix アプリケーション。 Tideアプリケーションは Tk または Tkinter に基づいて動作します。また、リモートで Tix/Tk/Tkinter アプリケーションを変更やデバッグするためのインスペクタ TixInspect が含まれます。

Tixを使う

class tkinter.tix.Tk(screenName=None, baseName=None, className='Tix')

主にアプリケーションのメインウィンドウを表すTixのトップレベルウィジェット。Tcl インタープリタが関連付けられます。

tkinter.tix モジュールのクラスは tkinter モジュールのクラスをサブクラス化します。前者は後者をインポートするので、モジュールを一つインポートするだけで tkinter.tix を Tkinter と一緒に使うことができます。一般的に、 tkinter.tix をインポートし、トップレベルでの tkinter.Tk への呼び出しは tix.Tk に置き換えるだけで済みます。次に例を示します:

from tkinter import tix
from tkinter.constants import *
root = tix.Tk()

tkinter.tix を使うためには、通常 Tk ウィジェットのインストールと平行して、Tix ウィジェットをインストールしなければなりません。インストールをテストするために、次のことを試してください:

from tkinter import tix
root = tix.Tk()
root.tk.eval('package require Tix')

Tixウィジェット

Tix [https://tix.sourceforge.net/dist/current/man/html/TixCmd/TixIntro.htm] は40個以上のウィジェットクラスを tkinter のレパートリーに導入します。

基本ウィジェット

class tkinter.tix.Balloon

ヘルプを提示するためにウィジェット上にポップアップする Balloon [https://tix.sourceforge.net/dist/current/man/html/TixCmd/tixBalloon.htm]。ユーザがカーソルをBalloonウィジェットが束縛されているウィジェット内部へ移動させたとき、説明のメッセージが付いた小さなポップアップウィンドウがスクリーン上に表示されます。

class tkinter.tix.ButtonBox

ButtonBox [https://tix.sourceforge.net/dist/current/man/html/TixCmd/tixButtonBox.htm] ウィジェットは、Ok Cancel のためだけに普通は使われるようなボタンボックスを作成します。

class tkinter.tix.ComboBox

ComboBox [https://tix.sourceforge.net/dist/current/man/html/TixCmd/tixComboBox.htm] ウィジェットはMS Windowsのコンボボックスコントロールに似ています。ユーザはエントリ・サブウィジェットでタイプするか、リストボックス・サブウィジェットから選択するかのどちらかで選択肢を選びます。

class tkinter.tix.Control

Control [https://tix.sourceforge.net/dist/current/man/html/TixCmd/tixControl.htm] ウィジェットは SpinBox ウィジェットとしても知られています。ユーザは二つの矢印ボタンを押すか、またはエントリに直接値を入力して値を調整します。新しい値をユーザが定義した上限と下限に対してチェックします。

class tkinter.tix.LabelEntry

LabelEntry [https://tix.sourceforge.net/dist/current/man/html/TixCmd/tixLabelEntry.htm] ウィジェットはエントリウィジェットとラベルを一つのメガウィジェットにまとめたものです。"記入形式"型のインターフェースの作成を簡単に行うために使うことができます。

class tkinter.tix.LabelFrame

LabelFrame [https://tix.sourceforge.net/dist/current/man/html/TixCmd/tixLabelFrame.htm] ウィジェットはフレームウィジェットとラベルを一つのメガウィジェットにまとめたものです。LabelFrameウィジェット内部にウィジェットを作成するためには、 frame サブウィジェットに対して新しいウィジェットを作成し、それらを frame サブウィジェット内部で取り扱います。

class tkinter.tix.Meter

Meter [https://tix.sourceforge.net/dist/current/man/html/TixCmd/tixMeter.htm] ウィジェットは実行に時間のかかるバックグラウンド・ジョブの進み具合を表示するために使用できます。

class tkinter.tix.OptionMenu

OptionMenu [https://tix.sourceforge.net/dist/current/man/html/TixCmd/tixOptionMenu.htm] はオプションのメニューボタンを作成します。

class tkinter.tix.PopupMenu

PopupMenu [https://tix.sourceforge.net/dist/current/man/html/TixCmd/tixPopupMenu.htm] ウィジェットは tk_popup コマンドの代替品として使用できます。 Tix PopupMenu ウィジェットの利点は、操作に必要なアプリケーション・コードが少ないことです。

class tkinter.tix.Select

Select [https://tix.sourceforge.net/dist/current/man/html/TixCmd/tixSelect.htm] ウィジェットはボタン・サブウィジェットのコンテナです。ユーザに対する選択オプションのラジオボックスまたはチェックボックス形式を提供するために利用することができます。

class tkinter.tix.StdButtonBox

StdButtonBox [https://tix.sourceforge.net/dist/current/man/html/TixCmd/tixStdButtonBox.htm] ウィジェットは、Motif に似たダイアログボックスのための標準的なボタンのグループです。

ファイルセレクタ

class tkinter.tix.DirList

DirList [https://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirList.htm] ウィジェットは、ディレクトリのリストビュー (上の階層のディレクトリとサブディレクトリ) を表示します。ユーザはリスト内に表示されたディレクトリの一つを選択したり、他のディレクトリへ変更したりできます。

class tkinter.tix.DirTree

DirTree [https://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirTree.htm] ウィジェットはディレクトリのツリービュー (上の階層のディレクトリとそのサブディレクトリ) を表示します。ユーザはリスト内に表示されたディレクトリの一つを選択したり、他のディレクトリへ変更したりできます。

class tkinter.tix.DirSelectDialog

DirSelectDialog [https://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirSelectDialog.htm] ウィジェットは、ダイアログウィンドウにファイルシステム内のディレクトリを提示します。ユーザはこのダイアログウィンドウを使用して、ファイルシステム内を移動して目的のディレクトリを選択することができます。

class tkinter.tix.DirSelectBox

DirSelectBox は標準 Motif(TM) ディレクトリ選択ボックスに似ています。ユーザがディレクトリを選択するために一般的に使われます。DirSelectBox は主に最近 ComboBox ウィジェットに選択されたディレクトリを保存し、すばやく再選択できるようにします。

class tkinter.tix.ExFileSelectBox

ExFileSelectBox [https://tix.sourceforge.net/dist/current/man/html/TixCmd/tixExFileSelectBox.htm] ウィジェットは、たいてい tixExFileSelectDialog ウィジェット内に組み込まれます。ユーザがファイルを選択するのに便利なメソッドを提供します。 ExFileSelectBox ウィジェットのスタイルは、MS Windows 3.1 の標準ファイルダイアログにとてもよく似ています。

class tkinter.tix.FileSelectBox

FileSelectBox [https://tix.sourceforge.net/dist/current/man/html/TixCmd/tixFileSelectBox.htm] は標準的な Motif(TM) ファイル選択ボックスに似ています。通常、ユーザがファイルを選択するために使われます。FileSelectBox は、直近に ComboBox ウィジェットに選択されたファイルを保存し、素早く再選択できるようにします。

class tkinter.tix.FileEntry

FileEntry [https://tix.sourceforge.net/dist/current/man/html/TixCmd/tixFileEntry.htm] ウィジェットは、ファイル名を入力するために使うことができます。ユーザはファイル名を手入力できます。その代わりに、エントリの横に並んでいるボタンウィジェットを押すと表示されるファイル選択ダイアログを使用することもできます。

階層的リストボックス

class tkinter.tix.HList

HList [https://tix.sourceforge.net/dist/current/man/html/TixCmd/tixHList.htm] ウィジェットは階層構造をもつどんなデータ(例えば、ファイルシステムディレクトリツリー)でも表示するために使用できます。リストエントリは字下げされ、階層のそれぞれの場所に応じて分岐線で接続されます。

class tkinter.tix.CheckList

CheckList [https://tix.sourceforge.net/dist/current/man/html/TixCmd/tixCheckList.htm] ウィジェットは、ユーザが選ぶ項目のリストを表示します。CheckList は Tk のチェックリストやラジオボタンより多くの項目を扱うことができることを除いて、チェックボタンあるいはラジオボタンウィジェットと同じように動作します。

class tkinter.tix.Tree

Tree [https://tix.sourceforge.net/dist/current/man/html/TixCmd/tixTree.htm] ウィジェットは階層的なデータをツリー形式で表示するために使うことができます。ユーザはツリーの一部を開いたり閉じたりすることによって、ツリーの見えを調整できます。

表的リストボックス

class tkinter.tix.TList

TList [https://tix.sourceforge.net/dist/current/man/html/TixCmd/tixTList.htm] ウィジェットは、表形式でデータを表示するために使うことができます。 TList ウィジェットのリスト・エントリは、Tkのリストボックス・ウィジェットのエントリに似ています。主な差は、(1) TList ウィジェットはリスト・エントリを二次元形式で表示でき、(2) リスト・エントリに対して複数の色やフォントだけでなく画像も使うことができるということです。

管理ウィジェット

class tkinter.tix.PanedWindow

PanedWindow [https://tix.sourceforge.net/dist/current/man/html/TixCmd/tixPanedWindow.htm] ウィジェットは、ユーザがいくつかのペインのサイズを対話的に操作できるようにします。ペインは垂直または水平のどちらかに配置されます。ユーザは二つのペインの間でリサイズ・ハンドルをドラッグしてペインの大きさを変更します。

class tkinter.tix.ListNoteBook

ListNoteBook [https://tix.sourceforge.net/dist/current/man/html/TixCmd/tixListNoteBook.htm] ウィジェットは、 TixNoteBook ウィジェットにとてもよく似ています。ノートのメタファを使って限られた空間をに多くのウィンドウを表示するために使われます。ノートはたくさんのページ(ウィンドウ)に分けられています。ある時には、これらのページの一つしか表示できません。ユーザは hlist サブウィジェットの中の望みのページの名前を選択することによって、これらのページを切り替えることができます。

class tkinter.tix.NoteBook

NoteBook [https://tix.sourceforge.net/dist/current/man/html/TixCmd/tixNoteBook.htm] ウィジェットは、ノートのメタファを多くのウィンドウを表示することができます。ノートはたくさんのページに分けられています。ある時には、これらのページの一つしか表示できません。ユーザは NoteBook ウィジェットの一番上にある目に見える"タブ"を選択することで、これらのページを切り替えることができます。

画像タイプ

tkinter.tix モジュールは次のものを追加します:

全ての tkinter.tix と tkinter ウィジェットに対して XPM ファイルからカラー画像を作成する pixmap [https://tix.sourceforge.net/dist/current/man/html/TixCmd/pixmap.htm] 機能。

Compound [https://tix.sourceforge.net/dist/current/man/html/TixCmd/compound.htm] 画像タイプは複数の水平方向の線から構成される画像を作成するために使うことができます。それぞれの線は左から右に並べられた一連のアイテム(テキスト、ビットマップ、画像あるいは空白)から作られます。例えば、Tk のButton ウィジェットの中にビットマップとテキスト文字列を同時に表示するためにcompound画像は使うことができます。

その他のウィジェット

class tkinter.tix.InputOnly

InputOnly [https://tix.sourceforge.net/dist/current/man/html/TixCmd/tixInputOnly.htm] ウィジェットは、ユーザから入力を受け付けます。それは、bind コマンドを使って行われます(Unixのみ)。

ジオメトリマネジャを作る

加えて、 tkinter.tix は次のものを提供することで tkinter を補強します:

class tkinter.tix.Form

すべての Tk ウィジェットに対する接続ルールに基づいた Form [https://tix.sourceforge.net/dist/current/man/html/TixCmd/tixForm.htm] ジオメトリマネジャ。

Tixコマンド

class tkinter.tix.tixCommand

tixコマンド [https://tix.sourceforge.net/dist/current/man/html/TixCmd/tix.htm] は Tix の内部状態と Tix アプリケーション・コンテキストのいろいろな要素へのアクセスを提供します。これらのメソッドによって操作される情報の大部分は、特定のウィンドウというよりむしろアプリケーション全体かスクリーンあるいはディスプレイに関するものです。

現在の設定を見るための一般的な方法は:

from tkinter import tix
root = tix.Tk()
print(root.tix_configure())

tixCommand.tix_configure(cnf=None, **kw)

Tix アプリケーション・コンテキストの設定オプションを問い合わせたり、変更したりします。オプションが指定されなければ、利用可能なオプションすべてのディクショナリを返します。オプションが値なしで指定された場合は、メソッドは指定されたオプションを説明するリストを返します(このリストはオプションが指定されていない場合に返される値に含まれている、指定されたオプションに対応するサブリストと同一です)。一つ以上のオプション-値のペアが指定された場合は、メソッドは与えられたオプションが与えられた値を持つように変更します。この場合は、メソッドは空文字列を返します。オプションは設定オプションのどれでも構いません。

tixCommand.tix_cget(option)

option によって与えられた設定オプションの現在の値を返します。オプションは設定オプションのどれでも構いません。

tixCommand.tix_getbitmap(name)

ビットマップディレクトリの一つの中の name.xpm または name と言う名前のビットマップファイルの場所を見つけ出します (tix_addbitmapdir() メソッドを参照してください)。 tix_getbitmap() を使うことで、アプリケーションにビットマップファイルのパス名をハードコーディングすることを避けることができます。成功すれば、文字 @ を先頭に付けたビットマップファイルの完全なパス名を返します。戻り値をTkとTixウィジェットの bitmap オプションを設定するために使うことができます。

tixCommand.tix_addbitmapdir(directory)

Tix は tix_getimage() と tix_getbitmap() メソッドが画像ファイルを検索する検索先ディレクトリのリストを保持しています。標準ビットマップディレクトリは $TIX_LIBRARY/bitmaps です。 tix_addbitmapdir() メソッドは directory をこのリストに追加します。そのメソッドを使うことによって、tix_getimage() または tix_getbitmap() メソッドを使ってアプリケーションの画像ファイルも見つけることができます。

tixCommand.tix_filedialog([dlgclass])

このアプリケーションからの異なる呼び出しの間で共有される可能性があるファイル選択ダイアログを返します。最初に呼ばれた時に、このメソッドはファイル選択ダイアログ・ウィジェットを作成します。このダイアログはその後のすべての tix_filedialog() への呼び出しで返されます。オプションの dlgclass パラメータは、要求されているファイル選択ダイアログ・ウィジェットの型を指定するために文字列として渡されます。指定可能なオプションは tix 、 FileSelectDialog あるいは tixExFileSelectDialog です。

tixCommand.tix_getimage(self, name)

ビットマップディレクトリの一つの中の name.xpm 、 name.xbm または name.ppm という名前の画像ファイルの場所を見つけ出します(上の tix_addbitmapdir() メソッドを参照してください)。同じ名前(だが異なる拡張子)のファイルが一つ以上ある場合は、画像のタイプがXディスプレイの深さに応じて選択されます。xbm画像はモノクロディスプレイの場合に選択され、カラー画像はカラーディスプレイの場合に選択されます。 tix_getimage() を使うことによって、アプリケーションに画像ファイルのパス名をハードコーディングすることを避けられます。成功すれば、このメソッドは新たに作成した画像の名前を返し、Tk と Tix ウィジェットの image オプションを設定するためにそれを使うことができます。

tixCommand.tix_option_get(name)

Tixのスキーム・メカニズムによって保持されているオプションを得ます。

tixCommand.tix_resetoptions(newScheme, newFontSet[, newScmPrio])

Tix アプリケーションのスキームとフォントセットをそれぞれ newScheme と newFontSet に再設定します。この設定は、この呼び出し後に作成されたウィジェットだけに影響します。そのため、Tix アプリケーションのどのウィジェットを作成する前にも resetoptions メソッドを呼び出すのが良い方法です。

オプション・パラメータ newScmPrio を、Tix スキームによって設定される Tk オプションの優先度レベルを再設定するために与えることができます。

Tk が X オプションデータベースを扱う方法のため、Tix がインポートされ初期化された後に、カラースキームとフォントセットを tix_config() メソッドを使って再設定することはできません。したがって、 tix_resetoptions() メソッドを代わりに使わなければならないのです。

IDLE

ソースコード: Lib/idlelib/ [https://github.com/python/cpython/tree/3.12/Lib/idlelib/]

IDLE は Python の統合開発環境で、学習用環境です。

IDLE は次のような特徴があります:

クロスプラットホーム: Windows, Unix, macOS で動作します

コード入力、出力、エラーメッセージの色付け機能を持った Python shell (対話的インタプリタ) ウィンドウ

多段 Undo、 Python 対応の色づけ、自動的な字下げ、呼び出し情報の表示、自動補完、他たくさんの機能をもつマルチウィンドウ・テキストエディタ

任意のウィンドウ内での検索、エディタウィンドウ内での置換、複数ファイルを跨いだ検索 (grep)

永続的なブレイクポイント、ステップ実行、グローバルとローカル名前空間の視覚化機能を持ったデバッガ

設定、ブラウザ群、ほかダイアログ群

メニュー

IDLE には2種類のメインウィンドウ、Shell ウィンドウと Editor ウィンドウがあります。 Editor ウィンドウは同時に複数開けます。 Windows と Linux では、それぞれ個別のトップメニューがあります。後で解説するそれぞれのメニューは、ウィンドウがどちらのウィンドウタイプなのかを示しています。

ファイル内の編集 (Edit) => 検索 (Find) で使われるような出力ウィンドウ (Output ウィンドウ) は editor ウィンドウのサブタイプで、 Editor ウィンドウと同じトップメニューを持ちますが、デフォルトタイトルとコンテキストメニューが違います。

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.

File メニュー (Shell ウィンドウ、Editor ウィンドウ)

New File [新規ファイル]

新しいファイル編集ウィンドウを作成します。

Open... [開く...]

Open ダイアログを使って既存のファイルをオープンします。

Open Module... [モジュールを開く...]

既存のモジュールをオープンします (sys.path を検索します)。

Recent Files [最近使ったファイル]

最近使ったファイルのリストを開きます。ファイルを一つクリックするとそれを開きます。

Module Browser

現在 Editor が開いているファイル内にあるクラス、関数、メソッドを木構造で可視化します。 Shell からの場合は、先にモジュール選択のダイアログが開きます。

Path Browser [パスブラウザ]

sys.path ディレクトリ、モジュール、クラスおよびメソッドを木構造で可視化します。

Save [保存]

現在のウィンドウを対応するファイルがあればそこに保存します。開いてから、または最後に保存したのちに編集があった場合のウィンドウには、ウィンドウタイトルの前後に * が付けられます。対応するファイルがなければ代わりに Save As が実行されます。

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

Save Copy As... [コピーとして保存...]

Save the current window to different file without changing the associated file. (See Save As note above about filename extensions.)

Print Window [ウィンドウを印刷]

現在のウィンドウをデフォルトプリンタで印刷します。

Close Window

Close the current window (if an unsaved editor, ask to save; if an unsaved Shell, ask to quit execution). Calling exit() or close() in the Shell window also closes Shell. If this is the only window, also exit IDLE.

Exit IDLE

Close all windows and quit IDLE (ask to save unsaved edit windows).

Edit メニュー (Shell ウィンドウ、Editor ウィンドウ)

Undo [元に戻す]

現在のウィンドウに対する最後の変更を Undo (取り消し) します。最大で 1000 個の変更が Undo できます。

Redo [やり直し]

現在のウィンドウに対する最後にundoされた変更をRedo(再スタート)します。

Select All [全て選択]

カレントウィンドウの内容全体を選択します。

Cut [切り取り]

システムのクリップボードへ選択された部分をコピーします。それから選択された部分を削除します。

Copy [コピー]

選択された部分をシステムのクリップボードへコピーします。

Paste [貼り付け]

システムのクリップボードの内容をカレントウィンドウへ挿入します。

クリップボードの機能はコンテキストメニューからも使えます。

Find... [検索...]

たくさんのオプションをもつ検索ダイアログボックスを開きます。

Find Again [再検索]

直前の検索があれば、それを繰り返します。

Find Selection [現在の選択を検索]

現在選択された文字列があれば、それを検索します。

Find in Files... [ファイルから検索...]

ファイル検索ダイアログを開きます。結果を新しい出力ウィンドウに出力します。

Replace... [置換...]

検索と置換ダイアログを開きます。

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.

Show Completions [補完候補の一覧]

既存の名前が選択できるスクロール可能なリストを開きます。下の編集とナビゲーションの節にある 補完 の項を参照してください。

Expand Word [語の展開]

先頭だけタイプしたものを、同一ウィンドウ内の完全な語と合致するものに展開します。異なる展開を得るためには繰り返します。

Show Call Tip

関数の開き括弧の後ろで、関数パラメータについてのヒントを表示する小さなウィンドウを開きます。下の編集とナビゲーションの節にある 呼び出しヒント の項を参照してください。

Show Surrounding Parens

囲んでいる括弧をハイライトします。

Format メニュー (Shell ウィンドウ、Editor ウィンドウ)

Format Paragraph [パラグラフのフォーマット]

コメント内、マルチライン文字列リテラル内、あるいは選択行の現在位置の (空行区切り) パラグラフの再整形。パラグラフ内の全ての行は N カラム (デフォルトは 72) 以内で再整形されます。

Indent Region [領域をインデント]

選択された行を右へインデント幅分シフトします (デフォルトは空白 4 個)。

Dedent Region [領域をインデント解除]

選択された行を左へインデント幅分シフトします (デフォルトは空白 4 個)。

Comment Out Region [領域をコメントアウト]

選択された行の先頭に ## を挿入します。

Uncomment Region [領域のコメントを解除]

選択された行から先頭の # あるいは ## を取り除きます。

Tabify Region [領域のタブ化]

先頭 の一続きの空白をタブに置き換えます (注意: Python コードのインデントには 4 つの空白を使うことをお勧めします)。

Untabify Region [領域の非タブ化]

すべての タブを適切な数の空白に置き換えます。

Toggle Tabs [タブの切り替え]

字下げのために空白を使うかタブを使うかを切り替えるダイアログを開きます。

New Indent Width [新しいインデント幅]

インデント幅を変更するダイアログを開きます。Python コミュニティによって受け容れられているデフォルトは空白 4 個です。

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.

Run メニュー (Editor ウィンドウのみ)

Run Module [モジュールの実行]

Check Module を実行します。エラーがなければ Shell の環境をクリーンにして再スタートした上で、モジュールを実行します。出力は Shell ウィンドウに表示されます。print や write しない限り、この出力はされません。モジュール実行が完了すると Shell はフォーカスされた状態のままで、プロンプトを表示します。これにより対話的に実行結果を調べることができます。この機能は、コマンドラインからファイルを python -i file で実行することに相当します。

Run... Customized

Same as Run Module, but run the module with customized settings. Command Line Arguments extend sys.argv as if passed on a command line. The module can be run in the Shell without restarting.

Check Module [モジュールのチェック]

Editor ウィンドウでいま開いているモジュールを構文チェックします。モジュールが未保存の場合、 Options -> Configure IDLE -> General の "Autosave Preferences" の設定にもとづき、確認を求められるか自動的に保存します。構文エラーが見つかると Editor ウィンドウでそのおよその位置に移動します。

Python Shell [Python シェル]

Python Shell ウィンドウを開くか、起こします。

Shell メニュー (Shell ウィンドウのみ)

View Last Restart [最後のリスタートを表示する]

最後に Shell のリスタートを行った場所まで Shell ウインドウをスクロールします。

Restart Shell [Shell のリスタート]

Restart the shell to clean the environment and reset display and exception handling.

Previous History

Cycle through earlier commands in history which match the current entry.

Next History

Cycle through later commands in history which match the current entry.

Interrupt Execution [実行の中断]

プログラムの実行を停止します。

Debug メニュー (Shell ウィンドウのみ)

Go to File/Line [ファイル/行へ移動]

カーソルのある現在行の上にファイル名と行番号が見つかれば、(開かれていなければ) そのファイルを開いてその行に飛びます。例外のトレースバックが参照しているソース行を見るのにこれを使いましょう。そのようなファイル名・行番号表示をしている行を見つけるのには Find を使えます。この機能は Shell ウィンドウと Output ウィンドウのコンテキストメニューからも使えます。

Debugger [デバッガ] (トグル切り替え)

アクティブにすると、Shell または Editor に入力したコードをデバッガのもとで実行します。Editor ではコンテキストメニューからブレイクポイントをセット出来ます。この機能はまだ不完全で、少々実験的です。

Stack Viewer [スタックビューア]

最後の例外のスタックトレースと locals 辞書、 globals 辞書をツリーウィジットで表示します。

Auto-open Stack Viewer [スタックビューアの自動オープン]

未捕捉の例外時にスタックビューアを自動的に開くかどうかを切り替えます。

Options メニュー (Shell ウィンドウ、Editor ウィンドウ)

Configure IDLE [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 Setting preferences under Help and preferences.

Most configuration options apply to all windows or all future windows. The option items below only apply to the active window.

Show/Hide Code Context (Editor Window only)

Editor ウィンドウの上部にペインが開き、そこにウィンドウの一番上のコードのブロックコンテキスト (訳注: コードが含まれているブロックのインデント構造) が表示されます。下の編集とナビゲーションの節にある コードコンテキスト の項を参照してください。

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 Setting preferences).

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.

Window メニュー (Shell ウィンドウ、Editor ウィンドウ)

Lists the names of all open windows; select one to bring it to the foreground (deiconifying it if necessary).

Help メニュー (Shell ウィンドウ、Editor ウィンドウ)

About IDLE [IDLE について]

バージョン、コピーライト、ライセンス、クレジット、その他を表示します。

IDLE Help [IDLE ヘルプ]

メニューオプション、基本的な編集やナビゲーションその他チップスを詳しく書いた IDLE のドキュメントを表示します。

Python Docs [Python ドキュメント]

Python ドキュメントがローカルにインストールされていればそれを開きます。もしくはウェブブラウザで最新の Python ドキュメント (https://docs.python.org) を開きます。(訳注: いずれも何もしていなければ英語。下記参照。)

Turtle Demo [Turtle デモ]

Python コード例とタートルによる描画を使って turtledemo モジュールを実行します。

General タブの下の方にある Configure IDLE ダイアログで、追加のヘルプソースを Help メニューに加えられます。下の編集とナビゲーションの節にある ヘルプソース の項を参照してください。

Context menus

ウィンドウ内で右クリック (macOS では Control-クリック) でコンテキストメニューが開きます。コンテキストメニューには Edit メニューにもある標準的なクリップボード機能が含まれています。

Cut [切り取り]

システムのクリップボードへ選択された部分をコピーします。それから選択された部分を削除します。

Copy [コピー]

選択された部分をシステムのクリップボードへコピーします。

Paste [貼り付け]

システムのクリップボードの内容をカレントウィンドウへ挿入します。

Editor ウィンドウではさらにブレイクポイント機能が使えます。ブレイクポイントがセットされた行には、特別に印がつきます。ブレイクポイントはデバッガのもとでの実行にだけ影響します。ファイルに付けたブレイクポイントはユーザの .idlerc ディレクトリに保存されます。

Set Breakpoint [ブレークポイントのセット]

現在行にブレークポイントをセットします。

Clear Breakpoint [ブレークポイントのクリア]

その行のブレークポイントをクリアします。

Shell ウィンドウや Output ウィンドウには次のメニューもあります。

Go to file/line [ファイル/行へ移動]

Debug メニューと同じものです。

The Shell window also has an output squeezing facility explained in the Python Shell window subsection below.

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.

Editing and Navigation

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.

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 Control key on Windows and Unix and the Command key on macOS. (And all such discussions assume that the keys have not been re-bound to something else.)

Arrow keys move the cursor one character or line.

C-LeftArrow and C-RightArrow moves left or right one word.

Home and End go to the beginning or end of the line.

Page Up and Page Down go up or down one screen.

C-Home and C-End go to beginning or end of the file.

Backspace and Del (or C-d) delete the previous or next character.

C-Backspace and C-Del delete one word left or right.

C-k deletes ('kills') everything to the right.

標準的なキーバインディング (C-c がコピーで C-v がペースト、など) は機能するかもしれません。キーバインディングは Configure IDLE ダイアログで選択します。

自動的な字下げ

ブロックの始まりの文の後、次の行は 4 つの空白 (Python Shell ウィンドウでは、一つのタブ) で字下げされます。あるキーワード (break、return など) の後では、次の行は字下げが解除 (dedent) されます。先頭の字下げでは、 Backspace は 4 つの空白があれば削除します。 Tab はインデント幅に対応する数の空白 (Python Shell ウィンドウでは一つのタブ) を挿入します。現在、タブは Tcl/Tk の制約のため 4 つの空白に固定されています。

Format メニュー の indent/dedent region コマンドも参照してください。

検索と置換

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 [x] Regular expression is checked, the target is interpreted according to the Python re module.

補完 (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 Up, Down, PageUp, PageDown, Home, and End keys; and by a single click within the box. Close the box with Escape, Enter, and double 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 os.sep or 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 C-space. If one types a prefix for the desired name before opening the box, the first match or near miss is made visible. The result is the same as if one enters a prefix after the box is displayed. Show Completions after a quote completes filenames in the current directory instead of a root directory.

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

呼び出しヒント (Calltips)

A calltip is shown automatically when one types ( 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 ) 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 itertools.count(. A calltip appears because Idle imports itertools into the user process for its own use. (This could change.) Enter turtle.write( and nothing appears. Idle does not itself import turtle. The menu entry and shortcut also do nothing. Enter import turtle. Thereafter, 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.

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 class, def, or 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.

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 Return with the cursor anywhere on the line. If a line is extended with Backslash (\), 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 Return, as specified above. One may edit pasted code first. If one pastes more than one statement into Shell, the result will be a SyntaxError when multiple statements are compiled as if they were one.

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

C-c attempts to interrupt statement execution (but may fail).

C-d closes Shell if typed at a >>> prompt.

Alt-p and Alt-n (C-p and C-n on macOS) retrieve to the current prompt the previous or next previously entered statement that matches anything already typed.

Return while the cursor is on any previous statement appends the latter to anything already typed at the prompt.

テキストの色

IDLE の表示はデフォルトで白背景に黒字ですが、以下のような特別な意味を持ったテキストには色が付きす。Shell では shell 出力、 shell エラー、ユーザエラー。Python コードでは Shell プロンプト内や Editor でのキーワード、組み込みクラスや組み込み関数の名前、 class や def に続く名前、文字列、そしてコメント。どんなテキストウィンドウでも、カーソル (あれば)、検索で合致したテキスト (あれば)、そして選択されているテキストには色が付きます。

IDLE also highlights the soft keywords match, case, and _ in pattern-matching statements. However, this highlighting is not perfect and will be incorrect in some rare cases, including some _-s in case patterns.

このテキストの色付けはバックグラウンドで行われるため、たまに色が付いてない状態が見えてしまいます。カラースキームは、 Configure IDLE [IDLE の設定] ダイアログの Highlighting タブで変更できます。ただし、エディタ内のデバッガブレークポイント行のマーキングと、ポップアップとダイアログないのテキストの色は、ユーザーにより変更することはできません。

Startup and Code Execution

-s オプションとともに起動すると、IDLE は環境変数 IDLESTARTUP か PYTHONSTARTUP で参照されているファイルを実行します。 IDLE はまず IDLESTARTUP をチェックし、あれば参照しているファイルを実行します。 IDLESTARTUP が無ければ、IDLE は PYTHONSTARTUP をチェックします。これらの環境変数で参照されているファイルは、IDLE シェルでよく使う関数を置いたり、一般的なモジュールの import 文を実行するのに便利です。

加えて、Tk もスタートアップファイルがあればそれをロードします。その Tk のファイルは無条件にロードされることに注意してください。このファイルは .Idle.py で、ユーザーのホームディレクトリから探されます。このファイルの中の文は Tk の名前空間で実行されるので、IDLE の Python シェルで使う関数を import するのには便利ではありません。

コマンドラインの使い方

idle.py [-c command] [-d] [-e] [-h] [-i] [-r file] [-s] [-t title] [-] [arg] ...

-c command  run command in the shell window
-d          enable debugger and open shell window
-e          open editor window
-h          print help message with legal combinations and exit
-i          open shell window
-r file     run file in shell window
-s          run $IDLESTARTUP or $PYTHONSTARTUP first, in shell window
-t title    set title of shell window
-           run stdin in shell (- must be last option before args)

引数がある場合 (訳注: 以下の説明、たぶん実情に反してますが一応訳しています):

-, -c, -r のどれかを使う場合、全ての引数は sys.argv[1:...] に入り、 sys.argv[0] には '', '-c', '-r' の、与えたものが入ります。 Options ダイアログでデフォルトだったとしても Editor ウィンドウが開くことはありません。

これ以外の場合は引数は編集対象のファイルとして開かれて、 sys.argv には IDLE そのものに渡された引数が反映されます。

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 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 ** Invalid host:. The valid value is 127.0.0.1 (idlelib.rpc.LOCALHOST). One can diagnose with tcpconnect -irv 127.0.0.1 6543 in one terminal window and 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 ~/.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 (python -m idlelib) and see if this results in an error message.

On Unix-based systems with tcl/tk older than 8.6.11 (see 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.

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, sys.modules starts with more entries, and 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 sys.stdin, sys.stdout, and sys.stderr with objects that get input from and send output to the Shell window. The original values stored in sys.__stdin__, sys.__stdout__, and sys.__stderr__ are not touched, but may be 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 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 input from sys.stdin or print or write to sys.stdout or sys.stderr, IDLE should be started in a command line window. (On Windows, use python or py rather than pythonw or pyw.) The secondary subprocess will then be attached to that window for input and output.

If sys is reset by user code, such as with 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 sys.getrecursionlimit and 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.

User output in Shell

When a program outputs text, the result is determined by the corresponding output device. When IDLE executes user code, sys.stdout and 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.)

>>> 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='')  # Display s as is.
# Result varies by OS and font.  Try it.

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

Developing tkinter applications

IDLE is intentionally different from standard Python in order to facilitate development of tkinter programs. Enter 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 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 b = tk.Button(root, text='button'); b.pack(). Again, nothing visibly changes in standard Python until one enters root.update().

Most tkinter programs run root.mainloop(), which usually does not return until the tk app is destroyed. If the program is run with python -i or from an IDLE editor, a >>> shell prompt does not appear until 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.

サブプロセスを起こさずに起動する

デフォルトでは、IDLE でのユーザコードの実行は、内部的なループバックインターフェイスを使用する、ソケット経由の分離されたサブプロセスで行われます。この接続は外部からは見えませんし、インターネットとのデータの送受信は行われません。ファイアウォールソフトウェアの警告が発生しても、無視して構いません。

ソケット接続の確立を試みて失敗した場合、IDLE によって通知されます。このような失敗は一過性の場合もありますが、永続的に失敗する場合は、ファイアウォールが接続をブロックしているか、特定のシステムの設定が誤っていることが原因かもしれません。問題が解決するまでは、 IDLE をコマンドラインオプション -n で起動することもできます。

IDLE を -n コマンドラインスイッチを使って開始した場合、IDLE は単一のプロセス内で動作し、RPC Python 実行サーバを走らせるサブプロセスを作りません。これは、プラットフォーム上で Python がサブプロセスや RPC ソケットインターフェイスを作れない場合に有用かもしれません。ただし、このモードではユーザコードが IDLE 自身から隔離されませんし、Run/Run Module (F5) 選択時に環境が再起動されてまっさらな状態になることもありません。コードを変更した場合、影響するモジュールを reload() しないといけませんし、変更を反映するには、すべての特定の項目 (from foo import baz など) を再インポートしないといけません。これらの理由から、可能なら常にデフォルトのサブプロセスを起こすモードで IDLE を起動するのが吉です。

バージョン 3.4 で非推奨.

Help and Preferences

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

Setting preferences [お好み設定]

The font preferences, highlighting, keys, and general preferences can be changed via Configure IDLE on the Option menu. Non-default user settings are saved in a .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 .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.

IDLE on macOS

Under System Preferences: Dock, one can set "Prefer tabs when opening documents" to "Always". This setting is not compatible with the tk/tkinter GUI framework used by IDLE, and it breaks a few IDLE features.

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.

idlelib

Source code: Lib/idlelib [https://github.com/python/cpython/tree/3.12/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 PEP 434 [https://peps.python.org/pep-0434/]).

開発ツール

The modules described in this chapter help you write software. For example, the pydoc module takes a module and generates documentation based on the module's contents. The doctest and unittest modules contains frameworks for writing unit tests that automatically exercise code and verify that the expected output is produced. 2to3 can translate Python 2.x source code into valid Python 3.x code.

この章で解説されるモジュールのリスト:

typing --- 型ヒントのサポート

Specification for the Python Type System

型エイリアス

NewType

呼び出し可能オブジェクトのアノテーション

ジェネリクス

タプルのアノテーション

クラスオブジェクトの型

ユーザー定義のジェネリック型

Any 型

名前的部分型 vs 構造的部分型

モジュールの内容

特殊型付けプリミティブ

特殊型

特殊形式

Building generic types and type aliases

Other special directives

プロトコル

ABCs for working with IO

Functions and decorators

Introspection helpers

定数

非推奨のエイリアス

Aliases to built-in types

Aliases to types in collections

Aliases to other concrete types

Aliases to container ABCs in collections.abc

Aliases to asynchronous ABCs in collections.abc

Aliases to other ABCs in collections.abc

Aliases to contextlib ABCs

メジャーな機能の非推奨時系列

pydoc --- Documentation generator and online help system

Python 開発モード

Effects of the Python Development Mode

ResourceWarning Example

Bad file descriptor error example

doctest --- Test interactive Python examples

簡単な利用法: docstring 中の実行例をチェックする

簡単な利用法: テキストファイル中の実行例をチェックする

doctest のからくり

どの docstring が検証されるのか?

docstring 内の実行例をどのように認識するのか?

実行コンテキストとは何か?

例外はどう扱えばよいか?

オプションフラグ

ディレクティブ (Directives)

警告

基本 API

単体テスト API

拡張 API

DocTest オブジェクト

Example オブジェクト

DocTestFinder オブジェクト

DocTestParser オブジェクト

DocTestRunner オブジェクト

OutputChecker オブジェクト

デバッグ

アドバイス

unittest --- Unit testing framework

基本的な例

コマンドラインインターフェイス

コマンドラインオプション

テストディスカバリ

テストコードの構成

既存テストコードの再利用

テストのスキップと予期された失敗

サブテストを利用して繰り返しテストの区別を付ける

クラスと関数

テストクラス

テストのグループ化

テストのロードと起動

load_tests プロトコル

クラスとモジュールのフィクスチャ

setUpClass と tearDownClass

setUpModule と tearDownModule

シグナルハンドリング

unittest.mock --- mock object library

クイックガイド

Mock クラス

呼び出し

属性の削除

Mock の名前と name 属性

属性として設定されるモック

patcher

patch

patch.object

patch.dict

patch.multiple

patch のメソッド: start と stop

ビルトインをパッチする

TEST_PREFIX

patch デコレータをネストする

どこにパッチするか

デスクリプタやプロキシオブジェクトにパッチする

MagicMock と magic method のサポート

Magic Method をモックする

Magic Mock

ヘルパー

sentinel

DEFAULT

call

create_autospec

ANY

FILTER_DIR

mock_open

autospec を使う

Sealing mocks

Order of precedence of side_effect, return_value and wraps

unittest.mock --- getting started

Mock を使う

Mock のパッチ用メソッド

オブジェクトのメソッド呼び出しに対するモック

クラスをモックする

モックに名前をつける

全ての呼び出しのトラッキング

戻り値や属性を設定する

モックから例外を発生させる

side_effect の関数と iterable

非同期イテレータをモックする

非同期コンテキストマネージャをモックする

既存のオブジェクトから Mock を作る

Using side_effect to return per file content

patch デコレータ

さらなる例

chained call をモックする

部分的なモック

ジェネレータメソッドをモックする

同じパッチを全てのメソッドに適用する

Unboundメソッドをモックする

モックで複数回の呼び出しをチェックする

ミュータブルな引数に対処する

patch をネストする

MagicMock で辞書をモックする

Mock のサブクラスと属性

patch.dict で import をモックする

Tracking order of calls and less verbose call assertions

More complex argument matching

2to3 --- Python 2 から 3 への自動コード変換

2to3 の使用

変換プログラム

lib2to3 --- 2to3's library

test --- Regression tests package for Python

test パッケージのためのユニットテストを書く

コマンドラインインターフェースを利用してテストを実行する

test.support --- テストのためのユーティリティ関数

test.support.socket_helper --- Utilities for socket tests

test.support.script_helper --- Utilities for the Python execution tests

test.support.bytecode_helper --- Support tools for testing correct bytecode generation

test.support.threading_helper --- Utilities for threading tests

test.support.os_helper --- Utilities for os tests

test.support.import_helper --- Utilities for import tests

test.support.warnings_helper --- Utilities for warnings tests

typing --- 型ヒントのサポート

Added in version 3.5.

ソースコード: Lib/typing.py [https://github.com/python/cpython/tree/3.12/Lib/typing.py]

注釈

The Python runtime does not enforce function and variable type annotations. They can be used by third party tools such as type checkers, IDEs, linters, etc.

This module provides runtime support for type hints.

Consider the function below:

def moon_weight(earth_weight: float) -> str:
    return f'On the moon, you would weigh {earth_weight * 0.166} kilograms.'

The function moon_weight takes an argument expected to be an instance of float, as indicated by the type hint earth_weight: float. The function is expected to return an instance of str, as indicated by the -> str hint.

While type hints can be simple classes like float or str, they can also be more complex. The typing module provides a vocabulary of more advanced type hints.

New features are frequently added to the typing module. The typing_extensions [https://pypi.org/project/typing_extensions/] package provides backports of these new features to older versions of Python.

参考

"Typing cheat sheet" [https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html]

型ヒントの簡単な概要 (mypy ドキュメンテーション)

mypy ドキュメンテーション [https://mypy.readthedocs.io/en/stable/index.html] の "Type System Reference" セクション

Python の型システムの規格は PEP によって定められているので、このレファレンスはほとんどの Python 型チェッカーに適用できるはずです。(mypy のみに適用される部分もあるかもしれません。)

"Static Typing with Python" [https://typing.readthedocs.io/en/latest/]

コミュニティーによって書かれた、型システムの機能や便利な型関連のツール、型に関するベストプラクティスを詳しく説明している、特定の型チェッカーに依らないドキュメンテーション。

Specification for the Python Type System

The canonical, up-to-date specification of the Python type system can be found at "Specification for the Python type system" [https://typing.readthedocs.io/en/latest/spec/index.html].

型エイリアス

型エイリアスは type 文を用いて定義され、 TypeAliasType インスタンスが生成されます。 この例では、静的型検査器は Vector と list[float] を等しいものとして扱います

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])

型エイリアスは複雑な型シグネチャを単純化するのに有用です。例えば:

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

type 文はPython3.12で新しく導入されました。後方互換性のために、単に代入によって型エイリアスを作成することもできます：

Vector = list[float]

あるいは、 TypeAlias でマークすることで、これが通常の変数代入ではなく、型エイリアスであることを明示できます

from typing import TypeAlias

Vector: TypeAlias = list[float]

NewType

異なる型を作るためには NewType ヘルパークラスを使います:

from typing import NewType

UserId = NewType('UserId', int)
some_id = UserId(524313)

静的型検査器は新しい型を元々の型のサブクラスのように扱います。この振る舞いは論理的な誤りを見つける手助けとして役に立ちます。

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)

UserId 型の変数も int の全ての演算が行えますが、その結果は常に int 型になります。この振る舞いにより、 int が期待されるところに UserId を渡せますが、不正な方法で UserId を作ってしまうことを防ぎます。

# 'output' is of type 'int', not 'UserId'
output = UserId(23413) + UserId(54341)

これらのチェックは静的型検査器のみによって強制されるということに注意してください。実行時に Derived = NewType('Derived', Base) という文は渡された仮引数をただちに返す Derived callable を作ります。つまり Derived(some_value) という式は新しいクラスを作ることはなく、通常の関数呼び出しより多くのオーバーヘッドがないということを意味します。

より正確に言うと、式 some_value is Derived(some_value) は実行時に常に真を返します。

Derived のサブタイプを作成することはできません

from typing import NewType

UserId = NewType('UserId', int)

# Fails at runtime and does not pass type checking
class AdminUserId(UserId): pass

しかし、 'derived' である NewType をもとにした NewType は作ることが出来ます:

from typing import NewType

UserId = NewType('UserId', int)

ProUserId = NewType('ProUserId', UserId)

そして ProUserId に対する型検査は期待通りに動作します。

より詳しくは PEP 484 [https://peps.python.org/pep-0484/] を参照してください。

注釈

型エイリアスの使用は、2つの型が互いに等価であることを宣言することを思い出してください。 type Alias = Original とすると、静的型チェッカーは Alias を Original と"正確に等価な"ものとして扱います。これは、複雑な型シグネチャを単純化したい場合に便利です。

これに対し、 NewType はある型をもう一方の型の サブタイプ として宣言します。 Derived = NewType('Derived', Original) とすると静的型検査器は Derived を Original の サブクラス として扱います。つまり Original 型の値は Derived 型の値が期待される場所で使うことが出来ないということです。これは論理的な誤りを最小の実行時のコストで防ぎたい時に有用です。

Added in version 3.5.2.

バージョン 3.10 で変更: NewType は関数ではなくクラスになりました。その結果、通常の関数よりも NewType を呼び出す際に多少の実行時コストが追加されます。

バージョン 3.11 で変更: NewType 呼び出し時のパフォーマンスが Python 3.9 のレベルに戻りました

呼び出し可能オブジェクトのアノテーション

関数、またはその他の呼び出し可能オブジェクトは、 collections.abc.Callable または typing.Callable を使用してアノテーションすることができます。 Callable[[int], str] は、 int 型のパラメータを1つ受け取り、 str を返す関数を意味します。

例えば:

from collections.abc import Callable, Awaitable

def feeder(get_next_item: Callable[[], str]) -> None:
    ...  # Body

def async_query(on_success: Callable[[int], None],
                on_error: Callable[[int, Exception], None]) -> None:
    ...  # Body

async def on_update(value: str) -> None:
    ...  # Body

callback: Callable[[str], Awaitable[None]] = on_update

添字表記は常に2つの値とともに使われなければなりません。実引数のリストと返り値の型です。実引数のリストは型のリスト、ParamSpec、Concatenate、ellipsis のいずれかでなければなりません。返り値の型は単一の型でなければなりません。

もしellipsisリテラル ... が引数リストとして与えられた場合、それは任意のパラメータリストを持つ呼び出し可能オブジェクトを受け入れることを示します。

def concat(x: str, y: str) -> str:
    return x + y

x: Callable[..., str]
x = str     # OK
x = concat  # Also OK

Callable cannot express complex signatures such as functions that take a variadic number of arguments, overloaded functions, or functions that have keyword-only parameters. However, these signatures can be expressed by defining a Protocol class with a __call__() method:

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

Callables which take other callables as arguments may indicate that their parameter types are dependent on each other using ParamSpec. Additionally, if that callable adds or removes arguments from other callables, the Concatenate operator may be used. They take the form Callable[ParamSpecVariable, ReturnType] and Callable[Concatenate[Arg1Type, Arg2Type, ..., ParamSpecVariable], ReturnType] respectively.

バージョン 3.10 で変更: Callable は ParamSpec と Concatenate をサポートしました。詳細は PEP 612 [https://peps.python.org/pep-0612/] を参照してください。

参考

ParamSpec と Concatenate のドキュメントに、Callable での使用例が記載されています。

ジェネリクス

コンテナに含まれるオブジェクトに関する型情報は、一般的な方法で静的に推論することができないため、標準ライブラリの多くのコンテナクラスは、要素に期待する型を示す添字表記をサポートしています

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

Generic functions and classes can be parameterized by using type parameter syntax:

from collections.abc import Sequence

def first[T](l: Sequence[T]) -> T:  # Function is generic over the TypeVar "T"
    return l[0]

Or by using the TypeVar factory directly:

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]

バージョン 3.12 で変更: Syntactic support for generics is new in Python 3.12.

タプルのアノテーション

For most containers in Python, the typing system assumes that all elements in the container will be of the same type. For example:

from collections.abc import Mapping

# Type checker will infer that all elements in ``x`` are meant to be ints
x: list[int] = []

# Type checker error: ``list`` only accepts a single type argument:
y: list[int, str] = [1, 'foo']

# Type checker will infer that all keys in ``z`` are meant to be strings,
# and that all values in ``z`` are meant to be either strings or ints
z: Mapping[str, str | int] = {}

list は引数に1つの型のみ受け入れるので、型チェッカーは上記の y への代入でエラーを出力します。同様に、Mapping は引数に2つの型のみ受け入れます。1つ目はキーの型を示し、2つ目は値の型を示します。

しかし、他の多くのPythonのコンテナとは異なり、タプルがすべて同じ型ではない要素を持つことは、慣用的なPythonコードでは一般的です。このため、タプルはPythonの型システムの中でも特殊です。tuple は任意の数の引数を受け入れます

# OK: ``x`` is assigned to a tuple of length 1 where the sole element is an int
x: tuple[int] = (5,)

# OK: ``y`` 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 ``z`` has been assigned to a tuple of length 3
z: tuple[int] = (1, 2, 3)

任意の 長さで、全ての要素が同じ型 T であるタプルを示すには tuple[T, ...] を使います。空のタプルを示すには tuple[()] を使います。単に tuple とアノテーションすることは、tuple[Any, ...] と等価です。

x: tuple[int, ...] = (1, 2)
# These reassignments are OK: ``tuple[int, ...]`` indicates x can be of any length
x = (1, 2, 3)
x = ()
# This reassignment is an error: all elements in ``x`` must be ints
x = ("foo", "bar")

# ``y`` can only ever be assigned to an empty tuple
y: tuple[()] = ()

z: tuple = ("foo", "bar")
# These reassignments are OK: plain ``tuple`` is equivalent to ``tuple[Any, ...]``
z = (1, 2, 3)
z = ()

クラスオブジェクトの型

C と注釈が付けられた変数は C 型の値を受理します。一方で Type[C] （または <Type> ）と注釈が付けられた変数は、そのクラス自身を受理します -- 具体的には、それは C の クラスオブジェクト を受理します。例:

a = 3         # Has type ``int``
b = int       # Has type ``type[int]``
c = type(a)   # Also has type ``type[int]``

Note that type[C] is covariant:

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: ``type[ProUser]`` is a subtype of ``type[User]``
make_new_user(TeamUser)  # Still fine
make_new_user(User())    # Error: expected ``type[User]`` but got ``User``
make_new_user(int)       # Error: ``type[int]`` is not a subtype of ``type[User]``

The only legal parameters for type are classes, Any, type variables, and unions of any of these types. For 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: ``type[TeamUser]`` is not a subtype
                              # of ``type[BasicUser | ProUser]``
new_non_team_user(User)       # Also an error

type[Any] is equivalent to type, which is the root of Python's metaclass hierarchy.

ユーザー定義のジェネリック型

ユーザー定義のクラスを、ジェネリッククラスとして定義できます。

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)

This syntax indicates that the class LoggedVar is parameterised around a single type variable T . This also makes T valid as a type within the class body.

Generic classes implicitly inherit from Generic. For compatibility with Python 3.11 and lower, it is also possible to inherit explicitly from Generic to indicate a generic class:

from typing import TypeVar, Generic

T = TypeVar('T')

class LoggedVar(Generic[T]):
    ...

Generic classes have __class_getitem__() methods, meaning they can be parameterised at runtime (e.g. LoggedVar[int] below):

from collections.abc import Iterable

def zero_all_vars(vars: Iterable[LoggedVar[int]]) -> None:
    for var in vars:
        var.set(0)

A generic type can have any number of type variables. All varieties of TypeVar are permissible as parameters for a generic type:

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]):
    ...

Generic の引数のそれぞれの型変数は別のものでなければなりません。このため次のクラス定義は無効です:

from typing import TypeVar, Generic
...

class Pair[M, M]:  # SyntaxError
    ...

T = TypeVar('T')

class Pair(Generic[T, T]):   # INVALID
    ...

Generic classes can also inherit from other classes:

from collections.abc import Sized

class LinkedList[T](Sized):
    ...

When inheriting from generic classes, some type parameters could be fixed:

from collections.abc import Mapping

class MyDict[T](Mapping[str, T]):
    ...

この場合では MyDict は仮引数 T を 1 つとります。

Using a generic class without specifying type parameters assumes Any for each position. In the following example, MyIterable is not generic but implicitly inherits from Iterable[Any]:

from collections.abc import Iterable

class MyIterable(Iterable): # Same as Iterable[Any]
    ...

User-defined generic type aliases are also supported. Examples:

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)

For backward compatibility, generic type aliases can also be created through a simple assignment:

from collections.abc import Iterable
from typing import TypeVar

S = TypeVar("S")
Response = Iterable[S] | int

バージョン 3.7 で変更: Generic にあった独自のメタクラスは無くなりました。

バージョン 3.12 で変更: Syntactic support for generics and type aliases is new in version 3.12. Previously, generic classes had to explicitly inherit from Generic or contain a type variable in one of their bases.

User-defined generics for parameter expressions are also supported via parameter specification variables in the form [**P]. The behavior is consistent with type variables' described above as parameter specification variables are treated by the typing module as a specialized type variable. The one exception to this is that a list of types can be used to substitute a ParamSpec:

>>> class Z[T, **P]: ...  # T is a TypeVar; P is a ParamSpec
...
>>> Z[int, [dict, float]]
__main__.Z[int, [dict, float]]

Classes generic over a ParamSpec can also be created using explicit inheritance from Generic. In this case, ** is not used:

from typing import ParamSpec, Generic

P = ParamSpec('P')

class Z(Generic[P]):
    ...

Another difference between TypeVar and ParamSpec is that a generic with only one parameter specification variable will accept parameter lists in the forms X[[Type1, Type2, ...]] and also X[Type1, Type2, ...] for aesthetic reasons. Internally, the latter is converted to the former, so the following are equivalent:

>>> class X[**P]: ...
...
>>> X[int, str]
__main__.X[[int, str]]
>>> X[[int, str]]
__main__.X[[int, str]]

Note that generics with ParamSpec may not have correct __parameters__ after substitution in some cases because they are intended primarily for static type checking.

バージョン 3.10 で変更: Generic can now be parameterized over parameter expressions. See ParamSpec and PEP 612 [https://peps.python.org/pep-0612/] for more details.

ユーザーが定義したジェネリッククラスはメタクラスの衝突を起こすことなく基底クラスに抽象基底クラスをとれます。ジェネリックメタクラスはサポートされません。パラメータ化を行うジェネリクスの結果はキャッシュされていて、 typing モジュールのほとんどの型は ハッシュ可能 で等価比較できます。

Any 型

Any は特別な種類の型です。静的型検査器はすべての型を Any と互換として扱い、 Any をすべての型と互換として扱います。

これは、 Any 型の値では、任意の演算やメソッドの呼び出しが行えることを意味します:

from typing import Any

a: Any = None
a = []          # OK
a = 2           # OK

s: str = ''
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()
    ...

Any 型の値をより詳細な型に代入する時に型検査が行われないことに注意してください。例えば、静的型検査器は a を s に代入する時、s が str 型として宣言されていて実行時に int の値を受け取るとしても、エラーを報告しません。

さらに、返り値や引数の型のないすべての関数は暗黙的に Any を使用します。

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

この挙動により、動的型付けと静的型付けが混在したコードを書かなければならない時に Any を 非常口 として使用することができます。

Any の挙動と object の挙動を対比しましょう。 Any と同様に、すべての型は object のサブタイプです。しかしながら、 Any と異なり、逆は成り立ちません: object はすべての他の型のサブタイプでは ありません。

これは、ある値の型が object のとき、型検査器はこれについてのほとんどすべての操作を拒否し、これをより特殊化された変数に代入する (または返り値として利用する) ことは型エラーになることを意味します。例えば:

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")

object は、ある値が型安全な方法で任意の型として使えることを示すために使用します。 Any はある値が動的に型付けられることを示すために使用します。

名前的部分型 vs 構造的部分型

初めは PEP 484 [https://peps.python.org/pep-0484/] は Python の静的型システムを 名前的部分型 を使って定義していました。名前的部分型とは、クラス B が期待されているところにクラス A が許容されるのは A が B のサブクラスの場合かつその場合に限る、ということです。

前出の必要条件は、Iterable などの抽象基底クラスにも当て嵌まります。この型付け手法の問題は、この手法をサポートするためにクラスに明確な型付けを行う必要があることで、これは pythonic ではなく、普段行っている 慣用的な Python コードへの動的型付けとは似ていません。例えば、次のコードは PEP 484 [https://peps.python.org/pep-0484/] に従ったものです

from collections.abc import Sized, Iterable, Iterator

class Bucket(Sized, Iterable[int]):
    ...
    def __len__(self) -> int: ...
    def __iter__(self) -> Iterator[int]: ...

PEP 544 [https://peps.python.org/pep-0544/] によって上にあるようなクラス定義で基底クラスを明示しないコードをユーザーが書け、静的型チェッカーで Bucket が Sized と Iterable[int] 両方のサブタイプだと暗黙的に見なせるようになり、この問題が解決しました。これは structural subtyping (構造的部分型) (あるいは、静的ダックタイピング) として知られています:

from collections.abc import Iterator, Iterable

class Bucket:  # Note: no base classes
    ...
    def __len__(self) -> int: ...
    def __iter__(self) -> Iterator[int]: ...

def collect(items: Iterable[int]) -> int: ...
result = collect(Bucket())  # Passes type check

さらに、特別なクラス Protocol のサブクラスを作ることで、新しい独自のプロトコルを作って構造的部分型というものを満喫できます。

モジュールの内容

The typing module defines the following classes, functions and decorators.

特殊型付けプリミティブ

特殊型

These can be used as types in annotations. They do not support subscription using [].

typing.Any

制約のない型であることを示す特別な型です。

任意の型は Any と互換です。

Any は任意の型と互換です。

バージョン 3.11 で変更: Any can now be used as a base class. This can be useful for avoiding type checker errors with classes that can duck type anywhere or are highly dynamic.

typing.AnyStr

A constrained type variable.

Definition:

AnyStr = TypeVar('AnyStr', str, bytes)

AnyStr is meant to be used for functions that may accept str or bytes arguments but cannot allow the two to mix.

例えば:

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

Note that, despite its name, AnyStr has nothing to do with the Any type, nor does it mean "any string". In particular, AnyStr and str | bytes are different from each other and have different use cases:

# 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!"

typing.LiteralString

Special type that includes only literal strings.

Any string literal is compatible with LiteralString, as is another LiteralString. However, an object typed as just str is not. A string created by composing LiteralString-typed objects is also acceptable as a LiteralString.

例:

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}"
    )

LiteralString is useful for sensitive APIs where arbitrary user-generated strings could generate problems. For example, the two cases above that generate type checker errors could be vulnerable to an SQL injection attack.

より詳しくは PEP 675 [https://peps.python.org/pep-0675/] を参照してください。

Added in version 3.11.

typing.Never

typing.NoReturn

Never and NoReturn represent the bottom type [https://en.wikipedia.org/wiki/Bottom_type], a type that has no members.

They can be used to indicate that a function never returns, such as sys.exit():

from typing import Never  # or NoReturn

def stop() -> Never:
    raise RuntimeError('no way')

Or to define a function that should never be called, as there are no valid arguments, such as assert_never():

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)

Never and NoReturn have the same meaning in the type system and static type checkers treat both equivalently.

Added in version 3.6.2: Added NoReturn.

Added in version 3.11: Added Never.

typing.Self

Special type to represent the current enclosed class.

例えば:

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"

This annotation is semantically equivalent to the following, albeit in a more succinct fashion:

from typing import TypeVar

Self = TypeVar("Self", bound="Foo")

class Foo:
    def return_self(self: Self) -> Self:
        ...
        return self

In general, if something returns self, as in the above examples, you should use Self as the return annotation. If Foo.return_self was annotated as returning "Foo", then the type checker would infer the object returned from SubclassOfFoo.return_self as being of type Foo rather than SubclassOfFoo.

Other common use cases include:

classmethods that are used as alternative constructors and return instances of the cls parameter.

Annotating an __enter__() method which returns self.

You should not use Self as the return annotation if the method is not guaranteed to return an instance of a subclass when the class is subclassed:

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()

より詳しくは PEP 673 [https://peps.python.org/pep-0673/] を参照してください。

Added in version 3.11.

typing.TypeAlias

Special annotation for explicitly declaring a type alias.

例えば:

from typing import TypeAlias

Factors: TypeAlias = list[int]

TypeAlias is particularly useful on older Python versions for annotating aliases that make use of forward references, as it can be hard for type checkers to distinguish these from normal variable assignments:

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 ``TypeAlias`` 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: ...

より詳しくは、 PEP 613 [https://peps.python.org/pep-0613/] をご覧ください。

Added in version 3.10.

バージョン 3.12 で非推奨: TypeAlias is deprecated in favor of the type statement, which creates instances of TypeAliasType and which natively supports forward references. Note that while TypeAlias and TypeAliasType serve similar purposes and have similar names, they are distinct and the latter is not the type of the former. Removal of TypeAlias is not currently planned, but users are encouraged to migrate to type statements.

特殊形式

これらはアノテーションの型として使用できます。これらは全て [] を使用した添字表記をサポートしますが、それぞれ固有の構文があります。

typing.Union

ユニオン型; Union[X, Y] は X | Y と等価で X または Y を表します。

To define a union, use e.g. Union[int, str] or the shorthand int | str. Using that shorthand is recommended. Details:

引数は型でなければならず、少なくとも一つ必要です。

ユニオン型のユニオン型は平滑化されます。例えば:

Union[Union[int, str], float] == Union[int, str, float]

引数が一つのユニオン型は消えます。例えば:

Union[int] == int  # The constructor actually returns int

冗長な実引数は飛ばされます。例えば:

Union[int, str, int] == Union[int, str] == int | str

ユニオン型を比較するとき引数の順序は無視されます。例えば:

Union[int, str] == Union[str, int]

Union のサブクラスを作成したり、インスタンスを作成することは出来ません。

Union[X][Y] と書くことは出来ません。

バージョン 3.7 で変更: 明示的に書かれているサブクラスを、実行時に直和型から取り除かなくなりました。

バージョン 3.10 で変更: ユニオン型は X | Y のように書けるようになりました。 union型の表現 を参照ください。

typing.Optional

Optional[X] は X | None (や Union[X, None]) と同等です。

これがデフォルト値を持つオプション引数とは同じ概念ではないということに注意してください。デフォルト値を持つオプション引数はオプション引数であるために、型アノテーションに Optional 修飾子は必要ありません。例えば次のようになります:

def foo(arg: int = 0) -> None:
    ...

それとは逆に、 None という値が許されていることが明示されている場合は、引数がオプションであろうとなかろうと、 Optional を使うのが好ましいです。例えば次のようになります:

def foo(arg: Optional[int] = None) -> None:
    ...

バージョン 3.10 で変更: Optionalは X | None のように書けるようになりました。 ref:union型の表現 <types-union> を参照ください。

typing.Concatenate

Special form for annotating higher-order functions.

Concatenate can be used in conjunction with Callable and ParamSpec to annotate a higher-order callable which adds, removes, or transforms parameters of another callable. Usage is in the form Concatenate[Arg1Type, Arg2Type, ..., ParamSpecVariable]. Concatenate is currently only valid when used as the first argument to a Callable. The last parameter to Concatenate must be a ParamSpec or ellipsis (...).

For example, to annotate a decorator with_lock which provides a threading.Lock to the decorated function, Concatenate can be used to indicate that with_lock expects a callable which takes in a Lock as the first argument, and returns a callable with a different type signature. In this case, the ParamSpec indicates that the returned callable's parameter types are dependent on the parameter types of the callable being passed in:

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]:
    '''A type-safe decorator which provides a lock.'''
    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:
    '''Add a list of numbers together in a thread-safe manner.'''
    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])

Added in version 3.10.

参考

PEP 612 [https://peps.python.org/pep-0612/] -- Parameter Specification Variables (the PEP which introduced ParamSpec and Concatenate)

ParamSpec

呼び出し可能オブジェクトのアノテーション

typing.Literal

Special typing form to define "literal types".

Literal can be used to indicate to type checkers that the annotated object has a value equivalent to one of the provided literals.

例えば:

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

Literal[...] はサブクラスにはできません。実行時に、任意の値が Literal[...] の型引数として使えますが、型チェッカーが制約を課すことがあります。リテラル型についてより詳しいことは PEP 586 [https://peps.python.org/pep-0586/] を参照してください。

Added in version 3.8.

バージョン 3.9.1 で変更: Literal ではパラメータの重複を解消するようになりました。Literal オブジェクトの等値比較は順序に依存しないようになりました。Literal オブジェクトは、等値比較する際に、パラメータのうち 1 つでも hashable でない場合は TypeError を送出するようになりました。

typing.ClassVar

クラス変数であることを示す特別な型構築子です。

PEP 526 [https://peps.python.org/pep-0526/] で導入された通り、 ClassVar でラップされた変数アノテーションによって、ある属性はクラス変数として使うつもりであり、そのクラスのインスタンスから設定すべきではないということを示せます。使い方は次のようになります:

class Starship:
    stats: ClassVar[dict[str, int]] = {} # class variable
    damage: int = 10                     # instance variable

ClassVar は型のみを受け入れ、それ以外は受け付けられません。

ClassVar はクラスそのものではなく、isinstance() や issubclass() で使うべきではありません。 ClassVar は Python の実行時の挙動を変えませんが、サードパーティの型検査器で使えます。例えば、型チェッカーは次のコードをエラーとするかもしれません:

enterprise_d = Starship(3000)
enterprise_d.stats = {} # Error, setting class variable on instance
Starship.stats = {}     # This is OK

Added in version 3.5.3.

typing.Final

Special typing construct to indicate final names to type checkers.

Final names cannot be reassigned in any scope. Final names declared in class scopes cannot be overridden in subclasses.

例えば:

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

この機能は実行時には検査されません。詳細については PEP 591 [https://peps.python.org/pep-0591/] を参照してください。

Added in version 3.8.

typing.Required

Special typing construct to mark a TypedDict key as required.

This is mainly useful for total=False TypedDicts. See TypedDict and PEP 655 [https://peps.python.org/pep-0655/] for more details.

Added in version 3.11.

typing.NotRequired

Special typing construct to mark a TypedDict key as potentially missing.

より詳しくは、 TypedDict と PEP 655 [https://peps.python.org/pep-0655/] を参照してください。

Added in version 3.11.

typing.Annotated

Special typing form to add context-specific metadata to an annotation.

Add metadata x to a given type T by using the annotation Annotated[T, x]. Metadata added using Annotated can be used by static analysis tools or at runtime. At runtime, the metadata is stored in a __metadata__ attribute.

If a library or tool encounters an annotation Annotated[T, x] and has no special logic for the metadata, it should ignore the metadata and simply treat the annotation as T. As such, Annotated can be useful for code that wants to use annotations for purposes outside Python's static typing system.

Using Annotated[T, x] as an annotation still allows for static typechecking of T, as type checkers will simply ignore the metadata x. In this way, Annotated differs from the @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 Annotated annotation. A tool or library encountering an Annotated type can scan through the metadata elements to determine if they are of interest (e.g., using isinstance()).

Annotated[<type>, <metadata>]

Here is an example of how you might use Annotated to add metadata to type annotations if you were doing range analysis:

@dataclass
class ValueRange:
    lo: int
    hi: int

T1 = Annotated[int, ValueRange(-10, 5)]
T2 = Annotated[T1, ValueRange(-20, 3)]

Details of the syntax:

The first argument to Annotated must be a valid type

Multiple metadata elements can be supplied (Annotated supports variadic arguments):

@dataclass
class ctype:
    kind: str

Annotated[int, ValueRange(3, 10), ctype("char")]

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.

Annotated must be subscripted with at least two arguments ( Annotated[int] is not valid)

The order of the metadata elements is preserved and matters for equality checks:

assert Annotated[int, ValueRange(3, 10), ctype("char")] != Annotated[
    int, ctype("char"), ValueRange(3, 10)
]

Nested Annotated types are flattened. The order of the metadata elements starts with the innermost annotation:

assert Annotated[Annotated[int, ValueRange(3, 10)], ctype("char")] == Annotated[
    int, ValueRange(3, 10), ctype("char")
]

Duplicated metadata elements are not removed:

assert Annotated[int, ValueRange(3, 10)] != Annotated[
    int, ValueRange(3, 10), ValueRange(3, 10)
]

Annotated can be used with nested and generic aliases:

@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
# ``Annotated[list[tuple[int, int]], MaxLen(10)]``:
type V = Vec[int]

Annotated cannot be used with an unpacked TypeVarTuple:

type Variadic[*Ts] = Annotated[*Ts, Ann1]  # NOT valid

This would be equivalent to:

Annotated[T1, T2, T3, ..., Ann1]

where T1, T2, etc. are TypeVars. This would be invalid: only one type should be passed to Annotated.

By default, get_type_hints() strips the metadata from annotations. Pass include_extras=True to have the metadata preserved:

>>> 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'>}

At runtime, the metadata associated with an Annotated type can be retrieved via the __metadata__ attribute:

>>> from typing import Annotated
>>> X = Annotated[int, "very", "important", "metadata"]
>>> X
typing.Annotated[int, 'very', 'important', 'metadata']
>>> X.__metadata__
('very', 'important', 'metadata')

参考

PEP 593 [https://peps.python.org/pep-0593/] - Flexible function and variable annotations

The PEP introducing Annotated to the standard library.

Added in version 3.9.

typing.TypeGuard

Special typing construct for marking user-defined type guard functions.

TypeGuard can be used to annotate the return type of a user-defined type guard function. TypeGuard only accepts a single type argument. At runtime, functions marked this way should return a boolean.

TypeGuard 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 guard":

def is_str(val: str | float):
    # "isinstance" type guard
    if isinstance(val, str):
        # Type of ``val`` is narrowed to ``str``
        ...
    else:
        # Else, type of ``val`` is narrowed to ``float``.
        ...

Sometimes it would be convenient to use a user-defined boolean function as a type guard. Such a function should use TypeGuard[...] as its return type to alert static type checkers to this intention.

Using -> TypeGuard tells the static type checker that for a given function:

The return value is a boolean.

If the return value is True, the type of its argument is the type inside TypeGuard.

例えば:

def is_str_list(val: list[object]) -> TypeGuard[list[str]]:
    '''Determines whether all objects in the list are strings'''
    return all(isinstance(x, str) for x in val)

def func1(val: list[object]):
    if is_str_list(val):
        # Type of ``val`` is narrowed to ``list[str]``.
        print(" ".join(val))
    else:
        # Type of ``val`` remains as ``list[object]``.
        print("Not a list of strings!")

If is_str_list is a class or instance method, then the type in TypeGuard maps to the type of the second parameter after cls or self.

In short, the form def foo(arg: TypeA) -> TypeGuard[TypeB]: ..., means that if foo(arg) returns True, then arg narrows from TypeA to TypeB.

注釈

TypeB need not be a narrower form of TypeA -- it can even be a wider form. The main reason is to allow for things like narrowing list[object] to list[str] even though the latter is not a subtype of the former, since list is invariant. The responsibility of writing type-safe type guards is left to the user.

TypeGuard also works with type variables. See PEP 647 [https://peps.python.org/pep-0647/] for more details.

Added in version 3.10.

typing.Unpack

Typing operator to conceptually mark an object as having been unpacked.

For example, using the unpack operator * on a type variable tuple is equivalent to using Unpack to mark the type variable tuple as having been unpacked:

Ts = TypeVarTuple('Ts')
tup: tuple[*Ts]
# Effectively does:
tup: tuple[Unpack[Ts]]

In fact, Unpack can be used interchangeably with * in the context of typing.TypeVarTuple and builtins.tuple types. You might see Unpack being used explicitly in older versions of Python, where * couldn't be used in certain places:

# 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

Unpack can also be used along with typing.TypedDict for typing **kwargs in a function signature:

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]): ...

See PEP 692 [https://peps.python.org/pep-0692/] for more details on using Unpack for **kwargs typing.

Added in version 3.11.

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 (type parameter lists and the type statement). For compatibility with Python 3.11 and earlier, they can also be created without the dedicated syntax, as documented below.

class typing.Generic

ジェネリック型のための抽象基底クラスです。

A generic type is typically declared by adding a list of type parameters after the class name:

class Mapping[KT, VT]:
    def __getitem__(self, key: KT) -> VT:
        ...
        # Etc.

Such a class implicitly inherits from Generic. The runtime semantics of this syntax are discussed in the Language Reference.

このクラスは次のように使用することが出来ます:

def lookup_name[X, Y](mapping: Mapping[X, Y], key: X, default: Y) -> Y:
    try:
        return mapping[key]
    except KeyError:
        return default

Here the brackets after the function name indicate a generic function.

For backwards compatibility, generic classes can also be declared by explicitly inheriting from Generic. In this case, the type parameters must be declared separately:

KT = TypeVar('KT')
VT = TypeVar('VT')

class Mapping(Generic[KT, VT]):
    def __getitem__(self, key: KT) -> VT:
        ...
        # Etc.

class typing.TypeVar(name, *constraints, bound=None, covariant=False, contravariant=False, infer_variance=False)

型変数です。

The preferred way to construct a type variable is via the dedicated syntax for generic functions, generic classes, and generic type aliases:

class Sequence[T]:  # T is a TypeVar
    ...

This syntax can also be used to create bound and constrained type variables:

class StrSequence[S: str]:  # S is a TypeVar bound to str
    ...

class StrOrBytesSequence[A: (str, bytes)]:  # A is a TypeVar constrained to str or bytes
    ...

However, if desired, reusable type variables can also be constructed manually, like so:

T = TypeVar('T')  # Can be anything
S = TypeVar('S', bound=str)  # Can be any subtype of str
A = TypeVar('A', str, bytes)  # Must be exactly str or bytes

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 Generic for more information on generic types. Generic functions work as follows:

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

Note that type variables can be bound, constrained, or neither, but cannot be both bound and constrained.

The variance of type variables is inferred by type checkers when they are created through the type parameter syntax or when infer_variance=True is passed. Manually created type variables may be explicitly marked covariant or contravariant by passing covariant=True or contravariant=True. By default, manually created type variables are invariant. See PEP 484 [https://peps.python.org/pep-0484/] and PEP 695 [https://peps.python.org/pep-0695/] for more details.

Bound type variables and constrained type variables have different semantics in several important ways. Using a bound type variable means that the TypeVar will be solved using the most specific type possible:

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

Type variables can be bound to concrete types, abstract types (ABCs or protocols), and even unions of types:

# 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

Using a constrained type variable, however, means that the TypeVar can only ever be solved as being exactly one of the constraints given:

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

At runtime, isinstance(x, T) will raise TypeError.

__name__

The name of the type variable.

__covariant__

Whether the type var has been explicitly marked as covariant.

__contravariant__

Whether the type var has been explicitly marked as contravariant.

__infer_variance__

Whether the type variable's variance should be inferred by type checkers.

Added in version 3.12.

__bound__

The bound of the type variable, if any.

バージョン 3.12 で変更: For type variables created through type parameter syntax, the bound is evaluated only when the attribute is accessed, not when the type variable is created (see Lazy evaluation).

__constraints__

A tuple containing the constraints of the type variable, if any.

バージョン 3.12 で変更: For type variables created through type parameter syntax, the constraints are evaluated only when the attribute is accessed, not when the type variable is created (see Lazy evaluation).

バージョン 3.12 で変更: Type variables can now be declared using the type parameter syntax introduced by PEP 695 [https://peps.python.org/pep-0695/]. The infer_variance parameter was added.

class typing.TypeVarTuple(name)

Type variable tuple. A specialized form of type variable that enables variadic generics.

Type variable tuples can be declared in type parameter lists using a single asterisk (*) before the name:

def move_first_element_to_last[T, *Ts](tup: tuple[T, *Ts]) -> tuple[*Ts, T]:
    return (*tup[1:], tup[0])

Or by explicitly invoking the TypeVarTuple constructor:

T = TypeVar("T")
Ts = TypeVarTuple("Ts")

def move_first_element_to_last(tup: tuple[T, *Ts]) -> tuple[*Ts, T]:
    return (*tup[1:], tup[0])

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:

# 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=())

Note the use of the unpacking operator * in tuple[T, *Ts]. Conceptually, you can think of Ts as a tuple of type variables (T1, T2, ...). tuple[T, *Ts] would then become tuple[T, *(T1, T2, ...)], which is equivalent to tuple[T, T1, T2, ...]. (Note that in older versions of Python, you might see this written using Unpack instead, as Unpack[Ts].)

Type variable tuples must always be unpacked. This helps distinguish type variable tuples from normal type variables:

x: Ts          # Not valid
x: tuple[Ts]   # Not valid
x: tuple[*Ts]  # The correct way to do it

Type variable tuples can be used in the same contexts as normal type variables. For example, in class definitions, arguments, and return types:

class Array[*Shape]:
    def __getitem__(self, key: tuple[*Shape]) -> float: ...
    def __abs__(self) -> "Array[*Shape]": ...
    def get_shape(self) -> tuple[*Shape]: ...

Type variable tuples can be happily combined with normal type variables:

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

However, note that at most one type variable tuple may appear in a single list of type arguments or type parameters:

x: tuple[*Ts, *Ts]            # Not valid
class Array[*Shape, *Shape]:  # Not valid
    pass

Finally, an unpacked type variable tuple can be used as the type annotation of *args:

def call_soon[*Ts](
         callback: Callable[[*Ts], None],
         *args: *Ts
) -> None:
    ...
    callback(*args)

In contrast to non-unpacked annotations of *args - e.g. *args: int, which would specify that all arguments are int - *args: *Ts enables reference to the types of the individual arguments in *args. Here, this allows us to ensure the types of the *args passed to call_soon match the types of the (positional) arguments of callback.

See PEP 646 [https://peps.python.org/pep-0646/] for more details on type variable tuples.

__name__

The name of the type variable tuple.

Added in version 3.11.

バージョン 3.12 で変更: Type variable tuples can now be declared using the type parameter syntax introduced by PEP 695 [https://peps.python.org/pep-0695/].

class typing.ParamSpec(name, *, bound=None, covariant=False, contravariant=False)

Parameter specification variable. A specialized version of type variables.

In type parameter lists, parameter specifications can be declared with two asterisks (**):

type IntFunc[**P] = Callable[P, int]

For compatibility with Python 3.11 and earlier, ParamSpec objects can also be created as follows:

P = ParamSpec('P')

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 Concatenate, or as the first argument to Callable, or as parameters for user-defined Generics. See Generic for more information on generic types.

For example, to add basic logging to a function, one can create a decorator 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:

from collections.abc import Callable
import logging

def add_logging[T, **P](f: Callable[P, T]) -> Callable[P, T]:
    '''A type-safe decorator to add logging to a function.'''
    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:
    '''Add two numbers together.'''
    return x + y

Without ParamSpec, the simplest way to annotate this previously was to use a TypeVar with bound Callable[..., Any]. However this causes two problems:

The type checker can't type check the inner function because *args and **kwargs have to be typed Any.

cast() may be required in the body of the add_logging decorator when returning the inner function, or the static type checker must be told to ignore the return inner.

args

kwargs

Since ParamSpec captures both positional and keyword parameters, P.args and P.kwargs can be used to split a ParamSpec into its components. P.args represents the tuple of positional parameters in a given call and should only be used to annotate *args. P.kwargs represents the mapping of keyword parameters to their values in a given call, and should be only be used to annotate **kwargs. Both attributes require the annotated parameter to be in scope. At runtime, P.args and P.kwargs are instances respectively of ParamSpecArgs and ParamSpecKwargs.

__name__

The name of the parameter specification.

Parameter specification variables created with covariant=True or contravariant=True can be used to declare covariant or contravariant generic types. The bound argument is also accepted, similar to TypeVar. However the actual semantics of these keywords are yet to be decided.

Added in version 3.10.

バージョン 3.12 で変更: Parameter specifications can now be declared using the type parameter syntax introduced by PEP 695 [https://peps.python.org/pep-0695/].

注釈

Only parameter specification variables defined in global scope can be pickled.

参考

PEP 612 [https://peps.python.org/pep-0612/] -- Parameter Specification Variables (the PEP which introduced ParamSpec and Concatenate)

Concatenate

呼び出し可能オブジェクトのアノテーション

typing.ParamSpecArgs

typing.ParamSpecKwargs

Arguments and keyword arguments attributes of a ParamSpec. The P.args attribute of a ParamSpec is an instance of ParamSpecArgs, and P.kwargs is an instance of ParamSpecKwargs. They are intended for runtime introspection and have no special meaning to static type checkers.

Calling get_origin() on either of these objects will return the original ParamSpec:

>>> from typing import ParamSpec, get_origin
>>> P = ParamSpec("P")
>>> get_origin(P.args) is P
True
>>> get_origin(P.kwargs) is P
True

Added in version 3.10.

class typing.TypeAliasType(name, value, *, type_params=())

The type of type aliases created through the type statement.

例:

>>> type Alias = int
>>> type(Alias)
<class 'typing.TypeAliasType'>

Added in version 3.12.

__name__

The name of the type alias:

>>> type Alias = int
>>> Alias.__name__
'Alias'

__module__

The module in which the type alias was defined:

>>> type Alias = int
>>> Alias.__module__
'__main__'

__type_params__

The type parameters of the type alias, or an empty tuple if the alias is not generic:

>>> type ListOrSet[T] = list[T] | set[T]
>>> ListOrSet.__type_params__
(T,)
>>> type NotGeneric = int
>>> NotGeneric.__type_params__
()

__value__

The type alias's value. This is lazily evaluated, so names used in the definition of the alias are not resolved until the __value__ attribute is accessed:

>>> type Mutually = Recursive
>>> type Recursive = Mutually
>>> Mutually
Mutually
>>> Recursive
Recursive
>>> Mutually.__value__
Recursive
>>> Recursive.__value__
Mutually

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.

class typing.NamedTuple

collections.namedtuple() の型付き版です。

使い方:

class Employee(NamedTuple):
    name: str
    id: int

これは次と等価です:

Employee = collections.namedtuple('Employee', ['name', 'id'])

フィールドにデフォルト値を与えるにはクラス本体で代入してください:

class Employee(NamedTuple):
    name: str
    id: int = 3

employee = Employee('Guido')
assert employee.id == 3

デフォルト値のあるフィールドはデフォルト値のないフィールドの後でなければなりません。

最終的に出来上がるクラスには、フィールド名をフィールド型へ対応付ける辞書を提供する __annotations__ 属性が追加されています。 (フィールド名は _fields 属性に、デフォルト値は _field_defaults 属性に格納されていて、両方とも namedtuple() API の一部分です。)

NamedTuple のサブクラスは docstring やメソッドも持てます:

class Employee(NamedTuple):
    """Represents an employee."""
    name: str
    id: int = 3

    def __repr__(self) -> str:
        return f'<Employee {self.name}, id={self.id}>'

NamedTuple subclasses can be generic:

class Group[T](NamedTuple):
    key: T
    group: list[T]

後方互換な使用法:

# For creating a generic NamedTuple on Python 3.11 or lower
class Group(NamedTuple, Generic[T]):
    key: T
    group: list[T]

# A functional syntax is also supported
Employee = NamedTuple('Employee', [('name', str), ('id', int)])

バージョン 3.6 で変更: PEP 526 [https://peps.python.org/pep-0526/] 変数アノテーションのシンタックスが追加されました。

バージョン 3.6.1 で変更: デフォルト値、メソッド、ドキュメンテーション文字列への対応が追加されました。

バージョン 3.8 で変更: _field_types 属性および __annotations__ 属性は OrderedDict インスタンスではなく普通の辞書になりました。

バージョン 3.9 で変更: _field_types 属性は削除されました。代わりに同じ情報を持つより標準的な __annotations__ 属性を使ってください。

バージョン 3.11 で変更: Added support for generic namedtuples.

class typing.NewType(name, tp)

Helper class to create low-overhead distinct types.

A NewType is considered a distinct type by a typechecker. At runtime, however, calling a NewType returns its argument unchanged.

使い方:

UserId = NewType('UserId', int)  # Declare the NewType "UserId"
first_user = UserId(1)  # "UserId" returns the argument unchanged at runtime

__module__

The module in which the new type is defined.

__name__

The name of the new type.

__supertype__

The type that the new type is based on.

Added in version 3.5.2.

バージョン 3.10 で変更: NewType is now a class rather than a function.

class typing.Protocol(Generic)

Base class for protocol classes.

Protocol classes are defined like this:

class Proto(Protocol):
    def meth(self) -> int:
        ...

このようなクラスは主に構造的部分型 (静的ダックタイピング) を認識する静的型チェッカーが使います。例えば:

class C:
    def meth(self) -> int:
        return 0

def func(x: Proto) -> int:
    return x.meth()

func(C())  # Passes static type check

詳細については PEP 544 [https://peps.python.org/pep-0544/] を参照してください。 runtime_checkable() (後で説明します) でデコレートされたプロトコルクラスは、与えられたメソッドがあることだけを確認し、その型シグネチャは全く見ない安直な動作をする実行時プロトコルとして振る舞います。

プロトコルクラスはジェネリックにもできます。例えば:

class GenProto[T](Protocol):
    def meth(self) -> T:
        ...

In code that needs to be compatible with Python 3.11 or older, generic Protocols can be written as follows:

T = TypeVar("T")

class GenProto(Protocol[T]):
    def meth(self) -> T:
        ...

Added in version 3.8.

@typing.runtime_checkable

Mark a protocol class as a runtime protocol.

Such a protocol can be used with isinstance() and issubclass(). This raises TypeError when applied to a non-protocol class. This allows a simple-minded structural check, very similar to "one trick ponies" in collections.abc such as Iterable. For 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)

注釈

runtime_checkable() will check only the presence of the required methods or attributes, not their type signatures or types. For example, ssl.SSLObject is a class, therefore it passes an issubclass() check against Callable. However, the ssl.SSLObject.__init__ method exists only to raise a TypeError with a more informative message, therefore making it impossible to call (instantiate) ssl.SSLObject.

注釈

An isinstance() check against a runtime-checkable protocol can be surprisingly slow compared to an isinstance() check against a non-protocol class. Consider using alternative idioms such as hasattr() calls for structural checks in performance-sensitive code.

Added in version 3.8.

バージョン 3.12 で変更: The internal implementation of isinstance() checks against runtime-checkable protocols now uses inspect.getattr_static() to look up attributes (previously, 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 isinstance() checks comparing objects to the protocol. See "What's new in Python 3.12" for more details.

class typing.TypedDict(dict)

Special construct to add type hints to a dictionary. At runtime it is a plain dict.

TypedDict は、その全てのインスタンスにおいてキーの集合が固定されていて、各キーに対応する値が全てのインスタンスで同じ型を持つことが期待される辞書型を宣言します。この期待は実行時にはチェックされず、型チェッカーでのみ強制されます。使用方法は次の通りです:

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')

To allow using this feature with older versions of Python that do not support PEP 526 [https://peps.python.org/pep-0526/], TypedDict supports two additional equivalent syntactic forms:

Using a literal dict as the second argument:

Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str})

Using keyword arguments:

Point2D = TypedDict('Point2D', x=int, y=int, label=str)

バージョン 3.11 で非推奨、バージョン 3.13 で削除予定: The keyword-argument syntax is deprecated in 3.11 and will be removed in 3.13. It may also be unsupported by static type checkers.

The functional syntax should also be used when any of the keys are not valid identifiers, for example because they are keywords or contain hyphens. Example:

# raises SyntaxError
class Point2D(TypedDict):
    in: int  # 'in' is a keyword
    x-y: int  # name with hyphens

# OK, functional syntax
Point2D = TypedDict('Point2D', {'in': int, 'x-y': int})

By default, all keys must be present in a TypedDict. It is possible to mark individual keys as non-required using NotRequired:

class Point2D(TypedDict):
    x: int
    y: int
    label: NotRequired[str]

# Alternative syntax
Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': NotRequired[str]})

This means that a Point2D TypedDict can have the label key omitted.

It is also possible to mark all keys as non-required by default by specifying a totality of False:

class Point2D(TypedDict, total=False):
    x: int
    y: int

# Alternative syntax
Point2D = TypedDict('Point2D', {'x': int, 'y': int}, total=False)

This means that a Point2D TypedDict can have any of the keys omitted. A type checker is only expected to support a literal False or True as the value of the total argument. True is the default, and makes all items defined in the class body required.

Individual keys of a total=False TypedDict can be marked as required using Required:

class Point2D(TypedDict, total=False):
    x: Required[int]
    y: Required[int]
    label: str

# Alternative syntax
Point2D = TypedDict('Point2D', {
    'x': Required[int],
    'y': Required[int],
    'label': str
}, total=False)

It is possible for a TypedDict type to inherit from one or more other TypedDict types using the class-based syntax. Usage:

class Point3D(Point2D):
    z: int

Point3D has three items: x, y and z. It is equivalent to this definition:

class Point3D(TypedDict):
    x: int
    y: int
    z: int

A TypedDict cannot inherit from a non-TypedDict class, except for Generic. For example:

class X(TypedDict):
    x: int

class Y(TypedDict):
    y: int

class Z(object): pass  # A non-TypedDict class

class XY(X, Y): pass  # OK

class XZ(X, Z): pass  # raises TypeError

A TypedDict can be generic:

class Group[T](TypedDict):
    key: T
    group: list[T]

To create a generic TypedDict that is compatible with Python 3.11 or lower, inherit from Generic explicitly:

T = TypeVar("T")

class Group(TypedDict, Generic[T]):
    key: T
    group: list[T]

A TypedDict can be introspected via annotations dicts (see Annotations Best Practices for more information on annotations best practices), __total__, __required_keys__, and __optional_keys__.

__total__

Point2D.__total__ gives the value of the total argument. 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

This attribute reflects only the value of the total argument to the current TypedDict class, not whether the class is semantically total. For example, a TypedDict with __total__ set to True may have keys marked with NotRequired, or it may inherit from another TypedDict with total=False. Therefore, it is generally better to use __required_keys__ and __optional_keys__ for introspection.

__required_keys__

Added in version 3.9.

__optional_keys__

Point2D.__required_keys__ and Point2D.__optional_keys__ return frozenset objects containing required and non-required keys, respectively.

Keys marked with Required will always appear in __required_keys__ and keys marked with NotRequired will always appear in __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 TypedDict . This is done by declaring a TypedDict with one value for the total argument and then inheriting from it in another TypedDict with a different value for total:

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

Added in version 3.9.

注釈

If from __future__ import annotations is used or if annotations are given as strings, annotations are not evaluated when the TypedDict is defined. Therefore, the runtime introspection that __required_keys__ and __optional_keys__ rely on may not work properly, and the values of the attributes may be incorrect.

他の例や、 TypedDict を扱う詳細な規則については PEP 589 [https://peps.python.org/pep-0589/] を参照してください。

Added in version 3.8.

バージョン 3.11 で変更: Added support for marking individual keys as Required or NotRequired. See PEP 655 [https://peps.python.org/pep-0655/].

バージョン 3.11 で変更: Added support for generic TypedDicts.

プロトコル

The following protocols are provided by the typing module. All are decorated with @runtime_checkable.

class typing.SupportsAbs

返り値の型と共変な抽象メソッド __abs__ を備えた ABC です。

class typing.SupportsBytes

抽象メソッド __bytes__ を備えた ABC です。

class typing.SupportsComplex

抽象メソッド __complex__ を備えた ABC です。

class typing.SupportsFloat

抽象メソッド __float__ を備えた ABC です。

class typing.SupportsIndex

抽象メソッド __index__ を備えた ABC です。

Added in version 3.8.

class typing.SupportsInt

抽象メソッド __int__ を備えた ABC です。

class typing.SupportsRound

返り値の型と共変な抽象メソッド __round__ を備えた ABC です。

ABCs for working with IO

class typing.IO

class typing.TextIO

class typing.BinaryIO

ジェネリック型 IO[AnyStr] とそのサブクラスの TextIO(IO[str]) および BinaryIO(IO[bytes]) は、 open() 関数が返すような I/O ストリームの型を表します。

Functions and decorators

typing.cast(typ, val)

値をある型にキャストします。

この関数は値を変更せずに返します。型検査器に対して、返り値が指定された型を持っていることを通知しますが、実行時には意図的に何も検査しません。 (その理由は、処理をできる限り速くしたかったためです。)

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 assert_type(), it emits an error if the value is not of the specified type:

def greet(name: str) -> None:
    assert_type(name, str)  # OK, inferred type of `name` is `str`
    assert_type(name, int)  # type checker error

This function is useful for ensuring the type checker's understanding of a script is in line with the developer's intentions:

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)

Added in version 3.11.

typing.assert_never(arg, /)

Ask a static type checker to confirm that a line of code is unreachable.

以下はプログラム例です:

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)

Here, the annotations allow the type checker to infer that the last case can never execute, because arg is either an int or a str, and both options are covered by earlier cases.

If a type checker finds that a call to assert_never() is reachable, it will emit an error. For example, if the type annotation for arg was instead int | str | float, the type checker would emit an error pointing out that unreachable is of type float. For a call to assert_never to pass type checking, the inferred type of the argument passed in must be the bottom type, Never, and nothing else.

At runtime, this throws an exception when called.

参考

Unreachable Code and Exhaustiveness Checking [https://typing.readthedocs.io/en/latest/source/unreachable.html] has more information about exhaustiveness checking with static typing.

Added in version 3.11.

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:

x: int = 1
reveal_type(x)  # Revealed type is "builtins.int"

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 sys.stderr and returns the argument unchanged (allowing the call to be used within an expression):

x = reveal_type(1)  # prints "Runtime type is int"
print(x)  # prints "1"

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 reveal_type() anywhere, even if the name is not imported from typing. Importing the name from typing, however, allows your code to run without runtime errors and communicates intent more clearly.

Added in version 3.11.

@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 dataclass-like behavior.

dataclass_transform may be used to decorate a class, metaclass, or a function that is itself a decorator. The presence of @dataclass_transform() tells a static type checker that the decorated object performs runtime "magic" that transforms a class in a similar way to @dataclasses.dataclass.

Example usage with a decorator function:

@dataclass_transform()
def create_model[T](cls: type[T]) -> type[T]:
    ...
    return cls

@create_model
class CustomerModel:
    id: int
    name: str

On a base class:

@dataclass_transform()
class ModelBase: ...

class CustomerModel(ModelBase):
    id: int
    name: str

On a metaclass:

@dataclass_transform()
class ModelMeta(type): ...

class ModelBase(metaclass=ModelMeta): ...

class CustomerModel(ModelBase):
    id: int
    name: str

The CustomerModel classes defined above will be treated by type checkers similarly to classes created with @dataclasses.dataclass. For example, type checkers will assume these classes have __init__ methods that accept id and 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 @dataclasses.dataclass decorator: init, eq, order, unsafe_hash, frozen, match_args, kw_only, and slots. It must be possible for the value of these arguments (True or False) to be statically evaluated.

The arguments to the dataclass_transform decorator can be used to customize the default behaviors of the decorated class, metaclass, or function:

パラメータ:

eq_default (bool) -- Indicates whether the eq parameter is assumed to be True or False if it is omitted by the caller. Defaults to True.

order_default (bool) -- Indicates whether the order parameter is assumed to be True or False if it is omitted by the caller. Defaults to False.

kw_only_default (bool) -- Indicates whether the kw_only parameter is assumed to be True or False if it is omitted by the caller. Defaults to False.

frozen_default (bool) --

Indicates whether the frozen parameter is assumed to be True or False if it is omitted by the caller. Defaults to False.

Added in version 3.12.

field_specifiers (tuple[Callable[..., Any], ...]) -- Specifies a static list of supported classes or functions that describe fields, similar to dataclasses.field(). Defaults to ().

**kwargs (Any) -- Arbitrary other keyword arguments are accepted in order to allow for possible future extensions.

Type checkers recognize the following optional parameters on field specifiers:

Recognised parameters for field specifiers

Parameter name

説明

init

Indicates whether the field should be included in the synthesized __init__ method. If unspecified, init defaults to True.

default

Provides the default value for the field.

default_factory

Provides a runtime callback that returns the default value for the field. If neither default nor default_factory are specified, the field is assumed to have no default value and must be provided a value when the class is instantiated.

factory

An alias for the default_factory parameter on field specifiers.

kw_only

Indicates whether the field should be marked as keyword-only. If True, the field will be keyword-only. If False, it will not be keyword-only. If unspecified, the value of the kw_only parameter on the object decorated with dataclass_transform will be used, or if that is unspecified, the value of kw_only_default on dataclass_transform will be used.

alias

Provides an alternative name for the field. This alternative name is used in the synthesized __init__ method.

At runtime, this decorator records its arguments in the __dataclass_transform__ attribute on the decorated object. It has no other runtime effect.

より詳しくは PEP 681 [https://peps.python.org/pep-0681/] を参照してください。

Added in version 3.11.

@typing.overload

Decorator for creating overloaded functions and methods.

The @overload decorator allows describing functions and methods that support multiple different combinations of argument types. A series of @overload-decorated definitions must be followed by exactly one non-@overload-decorated definition (for the same function/method).

@overload-decorated definitions are for the benefit of the type checker only, since they will be overwritten by the non-@overload-decorated definition. The non-@overload-decorated definition, meanwhile, will be used at runtime but should be ignored by a type checker. At runtime, calling an @overload-decorated function directly will raise NotImplementedError.

An example of overload that gives a more precise type than can be expressed using a union or a type variable:

@overload
def process(response: None) -> None:
    ...
@overload
def process(response: int) -> tuple[int, str]:
    ...
@overload
def process(response: bytes) -> str:
    ...
def process(response):
    ...  # actual implementation goes here

詳細と他の型付け意味論との比較は PEP 484 [https://peps.python.org/pep-0484/] を参照してください。

バージョン 3.11 で変更: Overloaded functions can now be introspected at runtime using get_overloads().

typing.get_overloads(func)

Return a sequence of @overload-decorated definitions for func.

func is the function object for the implementation of the overloaded function. For example, given the definition of process in the documentation for @overload, get_overloads(process) will return a sequence of three function objects for the three defined overloads. If called on a function with no overloads, get_overloads() returns an empty sequence.

get_overloads() can be used for introspecting an overloaded function at runtime.

Added in version 3.11.

typing.clear_overloads()

Clear all registered overloads in the internal registry.

This can be used to reclaim the memory used by the registry.

Added in version 3.11.

@typing.final

Decorator to indicate final methods and final classes.

Decorating a method with @final indicates to a type checker that the method cannot be overridden in a subclass. Decorating a class with @final indicates that it cannot be subclassed.

例えば:

class Base:
    @final
    def done(self) -> None:
        ...
class Sub(Base):
    def done(self) -> None:  # Error reported by type checker
        ...

@final
class Leaf:
    ...
class Other(Leaf):  # Error reported by type checker
    ...

この機能は実行時には検査されません。詳細については PEP 591 [https://peps.python.org/pep-0591/] を参照してください。

Added in version 3.8.

バージョン 3.11 で変更: The decorator will now attempt to set a __final__ attribute to True on the decorated object. Thus, a check like if getattr(obj, "__final__", False) can be used at runtime to determine whether an object 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.

@typing.no_type_check

アノテーションが型ヒントでないことを示すデコレータです。

This works as a class or function 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.

@no_type_check mutates the decorated object in place.

@typing.no_type_check_decorator

別のデコレータに no_type_check() の効果を与えるデコレータです。

これは何かの関数をラップするデコレータを no_type_check() でラップします。

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

例えば:

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

There is no runtime checking of this property.

The decorator will attempt to set an __override__ attribute to True on the decorated object. Thus, a check like if getattr(obj, "__override__", False) can be used at runtime to determine whether an object obj has been marked as an override. If the decorated object does not support setting attributes, the decorator returns the object unchanged without raising an exception.

See PEP 698 [https://peps.python.org/pep-0698/] for more details.

Added in version 3.12.

@typing.type_check_only

Decorator to mark a class or function as unavailable at runtime.

このデコレータ自身は実行時には使えません。このデコレータは主に、実装がプライベートクラスのインスタンスを返す場合に、型スタブファイルに定義されているクラスに対して印を付けるためのものです:

@type_check_only
class Response:  # private or not available at runtime
    code: int
    def get_header(self, name: str) -> str: ...

def fetch_response() -> Response: ...

プライベートクラスのインスタンスを返すのは推奨されません。そのようなクラスは公開クラスにするのが望ましいです。

Introspection helpers

typing.get_type_hints(obj, globalns=None, localns=None, include_extras=False)

関数、メソッド、モジュールまたはクラスのオブジェクトの型ヒントを含む辞書を返します。

This is often the same as obj.__annotations__. In addition, forward references encoded as string literals are handled by evaluating them in globals, locals and (where applicable) type parameter namespaces. For a class C, return a dictionary constructed by merging all the __annotations__ along C.__mro__ in reverse order.

The function recursively replaces all Annotated[T, ...] with T, unless include_extras is set to True (see Annotated for more information). For example:

class Student(NamedTuple):
    name: Annotated[str, 'some marker']

assert get_type_hints(Student) == {'name': str}
assert get_type_hints(Student, include_extras=False) == {'name': str}
assert get_type_hints(Student, include_extras=True) == {
    'name': Annotated[str, 'some marker']
}

注釈

get_type_hints() does not work with imported type aliases that include forward references. Enabling postponed evaluation of annotations (PEP 563 [https://peps.python.org/pep-0563/]) may remove the need for most forward references.

バージョン 3.9 で変更: Added include_extras parameter as part of PEP 593 [https://peps.python.org/pep-0593/]. See the documentation on Annotated for more information.

バージョン 3.11 で変更: Previously, Optional[t] was added for function and method annotations if a default value equal to None was set. Now the annotation is returned unchanged.

typing.get_origin(tp)

Get the unsubscripted version of a type: for a typing object of the form X[Y, Z, ...] return X.

If X is a typing-module alias for a builtin or collections class, it will be normalized to the original class. If X is an instance of ParamSpecArgs or ParamSpecKwargs, return the underlying ParamSpec. Return None for unsupported objects.

例:

assert get_origin(str) is None
assert get_origin(Dict[str, int]) is dict
assert get_origin(Union[int, str]) is Union
P = ParamSpec('P')
assert get_origin(P.args) is P
assert get_origin(P.kwargs) is P

Added in version 3.8.

typing.get_args(tp)

Get type arguments with all substitutions performed: for a typing object of the form X[Y, Z, ...] return (Y, Z, ...).

If X is a union or Literal contained in another generic type, the order of (Y, Z, ...) may be different from the order of the original arguments [Y, Z, ...] due to type caching. Return () for unsupported objects.

例:

assert get_args(int) == ()
assert get_args(Dict[int, str]) == (int, str)
assert get_args(Union[int, str]) == (int, str)

Added in version 3.8.

typing.is_typeddict(tp)

Check if a type is a TypedDict.

例えば:

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)

Added in version 3.10.

class typing.ForwardRef

Class used for internal typing representation of string forward references.

For example, List["SomeClass"] is implicitly transformed into List[ForwardRef("SomeClass")]. ForwardRef should not be instantiated by a user, but may be used by introspection tools.

注釈

PEP 585 [https://peps.python.org/pep-0585/] generic types such as list["SomeClass"] will not be implicitly transformed into list[ForwardRef("SomeClass")] and thus will not automatically resolve to list[SomeClass].

Added in version 3.7.4.

定数

typing.TYPE_CHECKING

A special constant that is assumed to be True by 3rd party static type checkers. It is False at runtime.

使い方:

if TYPE_CHECKING:
    import expensive_mod

def fun(arg: 'expensive_mod.SomeType') -> None:
    local_var: expensive_mod.AnotherType = other_fun()

The first type annotation must be enclosed in quotes, making it a "forward reference", to hide the expensive_mod reference from the interpreter runtime. Type annotations for local variables are not evaluated, so the second annotation does not need to be enclosed in quotes.

注釈

from __future__ import annotations が使われた場合、アノーテーションは関数定義時に評価されません。代わりにアノーテーションは __annotations__ 属性に文字列として保存されます。これによりアノーテーションをシングルクォートで囲む必要がなくなります (PEP 563 [https://peps.python.org/pep-0563/] を参照してください)。

Added in version 3.5.2.

非推奨のエイリアス

このモジュールは、既存の標準ライブラリ・クラスに対するいくつかの非推奨エイリアスを定義しています。これらは元々、 [] を使ったジェネリッククラスのパラメータ化をサポートするためにtypingモジュールに含まれていました。しかしこのエイリアスは、Python 3.9 で既存の相当するクラスが [] をサポートするように拡張されたため、冗長な書き方になりました( PEP 585 [https://peps.python.org/pep-0585/] を参照)。

The redundant types are deprecated as of Python 3.9. However, while the aliases may be removed at some point, removal of these aliases is not currently planned. As such, no deprecation warnings are currently issued by the interpreter for these aliases.

If at some point it is decided to remove these deprecated aliases, a deprecation warning will be issued by the interpreter for at least two releases prior to removal. The aliases are guaranteed to remain in the typing module without deprecation warnings until at least Python 3.14.

Type checkers are encouraged to flag uses of the deprecated types if the program they are checking targets a minimum Python version of 3.9 or newer.

Aliases to built-in types

class typing.Dict(dict, MutableMapping[KT, VT])

dict の非推奨なエイリアス。

Note that to annotate arguments, it is preferred to use an abstract collection type such as Mapping rather than to use dict or typing.Dict.

この型は次のように使えます:

def count_words(text: str) -> Dict[str, int]:
    ...

バージョン 3.9 で非推奨: builtins.dict は添字表記 ([]) をサポートするようになりました。 PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

class typing.List(list, MutableSequence[T])

list の非推奨なエイリアス。

Note that to annotate arguments, it is preferred to use an abstract collection type such as Sequence or Iterable rather than to use list or typing.List.

この型は次のように使えます:

def vec2[T: (int, float)](x: T, y: T) -> List[T]:
    return [x, y]

def keep_positives[T: (int, float)](vector: Sequence[T]) -> List[T]:
    return [item for item in vector if item > 0]

バージョン 3.9 で非推奨: builtins.list は添字表記 ([]) をサポートするようになりました。PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

class typing.Set(set, MutableSet[T])

Deprecated alias to builtins.set.

Note that to annotate arguments, it is preferred to use an abstract collection type such as AbstractSet rather than to use set or typing.Set.

バージョン 3.9 で非推奨: builtins.set は添字表記 ([]) をサポートするようになりました。 PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

class typing.FrozenSet(frozenset, AbstractSet[T_co])

Deprecated alias to builtins.frozenset.

バージョン 3.9 で非推奨: builtins.frozenset は添字表記 ([]) をサポートするようになりました。 PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

typing.Tuple

tuple の非推奨なエイリアス。

tuple and Tuple are special-cased in the type system; see タプルのアノテーション for more details.

バージョン 3.9 で非推奨: builtins.tuple は添字表記 ([]) をサポートするようになりました。 PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

class typing.Type(Generic[CT_co])

type の非推奨なエイリアス。

See クラスオブジェクトの型 for details on using type or typing.Type in type annotations.

Added in version 3.5.2.

バージョン 3.9 で非推奨: builtins.type は添字表記 ([]) をサポートするようになりました。 PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

Aliases to types in collections

class typing.DefaultDict(collections.defaultdict, MutableMapping[KT, VT])

collections.defaultdict の非推奨なエイリアス。

Added in version 3.5.2.

バージョン 3.9 で非推奨: collections.defaultdict は添字表記 ([]) をサポートするようになりました。 PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

class typing.OrderedDict(collections.OrderedDict, MutableMapping[KT, VT])

collections.OrderedDict の非推奨なエイリアス。

Added in version 3.7.2.

バージョン 3.9 で非推奨: collections.OrderedDict は添字表記 ([]) をサポートするようになりました。 PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

class typing.ChainMap(collections.ChainMap, MutableMapping[KT, VT])

collections.ChainMap の非推奨なエイリアス。

Added in version 3.6.1.

バージョン 3.9 で非推奨: collections.ChainMap は添字表記 ([]) をサポートするようになりました。 PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

class typing.Counter(collections.Counter, Dict[T, int])

collections.Counter の非推奨なエイリアス。

Added in version 3.6.1.

バージョン 3.9 で非推奨: collections.Counter は添字表記 ([]) をサポートするようになりました。 PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

class typing.Deque(deque, MutableSequence[T])

collections.deque の非推奨なエイリアス。

Added in version 3.6.1.

バージョン 3.9 で非推奨: collections.deque は添字表記 ([]) をサポートするようになりました。 PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

Aliases to other concrete types

バージョン 3.8 で非推奨、バージョン 3.13 で削除予定: The typing.io namespace is deprecated and will be removed. These types should be directly imported from typing instead.

class typing.Pattern

class typing.Match

Deprecated aliases corresponding to the return types from re.compile() and re.match().

These types (and the corresponding functions) are generic over AnyStr. Pattern can be specialised as Pattern[str] or Pattern[bytes]; Match can be specialised as Match[str] or Match[bytes].

バージョン 3.8 で非推奨、バージョン 3.13 で削除予定: The typing.re namespace is deprecated and will be removed. These types should be directly imported from typing instead.

バージョン 3.9 で非推奨: Classes Pattern and Match from re now support []. See PEP 585 [https://peps.python.org/pep-0585/] and ジェネリックエイリアス型.

class typing.Text

Deprecated alias for str.

Text is provided to supply a forward compatible path for Python 2 code: in Python 2, Text is an alias for unicode.

Text は Python 2 と Python 3 の両方と互換性のある方法で値が unicode 文字列を含んでいなければならない場合に使用してください。

def add_unicode_checkmark(text: Text) -> Text:
    return text + u' \u2713'

Added in version 3.5.2.

バージョン 3.11 で非推奨: Python 2 is no longer supported, and most type checkers also no longer support type checking Python 2 code. Removal of the alias is not currently planned, but users are encouraged to use str instead of Text.

Aliases to container ABCs in collections.abc

class typing.AbstractSet(Collection[T_co])

collections.abc.Set の非推奨なエイリアス。

バージョン 3.9 で非推奨: collections.abc.Set は添字表記 ([]) をサポートするようになりました。 PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

class typing.ByteString(Sequence[int])

この型は bytes と bytearray 、バイト列の memoryview を表します。

バージョン 3.9 で非推奨、バージョン 3.14 で削除予定: Prefer collections.abc.Buffer, or a union like bytes | bytearray | memoryview.

class typing.Collection(Sized, Iterable[T_co], Container[T_co])

collections.abc.Collection の非推奨なエイリアス。

Added in version 3.6.

バージョン 3.9 で非推奨: collections.abc.Collection は添字表記 ([]) をサポートするようになりました。 PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

class typing.Container(Generic[T_co])

collections.abc.Container の非推奨なエイリアス。

バージョン 3.9 で非推奨: collections.abc.Container は添字表記 ([]) をサポートするようになりました。 PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

class typing.ItemsView(MappingView, AbstractSet[tuple[KT_co, VT_co]])

collections.abc.ItemsView の非推奨なエイリアス。

バージョン 3.9 で非推奨: collections.abc.ItemsView は添字表記 ([]) をサポートするようになりました。 PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

class typing.KeysView(MappingView, AbstractSet[KT_co])

collections.abc.KeysView の非推奨なエイリアス。

バージョン 3.9 で非推奨: collections.abc.KeysView は添字表記 ([]) をサポートするようになりました。 PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

class typing.Mapping(Collection[KT], Generic[KT, VT_co])

collections.abc.Mapping の非推奨なエイリアス。

この型は次のように使えます:

def get_position_in_index(word_list: Mapping[str, int], word: str) -> int:
    return word_list[word]

バージョン 3.9 で非推奨: collections.abc.Mapping は添字表記 ([]) をサポートするようになりました。 PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

class typing.MappingView(Sized)

collections.abc.MappingView の非推奨なエイリアス。

バージョン 3.9 で非推奨: collections.abc.MappingView は添字表記 ([]) をサポートするようになりました。 PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

class typing.MutableMapping(Mapping[KT, VT])

collections.abc.MutableMapping の非推奨なエイリアス。

バージョン 3.9 で非推奨: collections.abc.MutableMapping は添字表記 ([]) をサポートするようになりました。 PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

class typing.MutableSequence(Sequence[T])

collections.abc.MutableSequence の非推奨なエイリアス。

バージョン 3.9 で非推奨: collections.abc.MutableSequence は添字表記 ([]) をサポートするようになりました。 PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

class typing.MutableSet(AbstractSet[T])

collections.abc.MutableSet の非推奨なエイリアス。

バージョン 3.9 で非推奨: collections.abc.MutableSet は添字表記 ([]) をサポートするようになりました。 PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

class typing.Sequence(Reversible[T_co], Collection[T_co])

collections.abc.Sequence の非推奨なエイリアス。

バージョン 3.9 で非推奨: collections.abc.Sequence は添字表記 ([]) をサポートするようになりました。 PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

class typing.ValuesView(MappingView, Collection[_VT_co])

collections.abc.ValuesView の非推奨なエイリアス。

バージョン 3.9 で非推奨: collections.abc.ValuesView は添字表記 ([]) をサポートするようになりました。 PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

Aliases to asynchronous ABCs in collections.abc

class typing.Coroutine(Awaitable[ReturnType], Generic[YieldType, SendType, ReturnType])

collections.abc.Coroutine の非推奨なエイリアス。

The variance and order of type variables correspond to those of Generator, for 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

Added in version 3.5.3.

バージョン 3.9 で非推奨: collections.abc.Coroutine は添字表記 ([]) をサポートするようになりました。 PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

class typing.AsyncGenerator(AsyncIterator[YieldType], Generic[YieldType, SendType])

collections.abc.AsyncGenerator の非推奨なエイリアス。

非同期ジェネレータはジェネリック型 AsyncGenerator[YieldType, SendType] によってアノテーションを付けられます。例えば:

async def echo_round() -> AsyncGenerator[int, float]:
    sent = yield 0
    while sent >= 0.0:
        rounded = await round(sent)
        sent = yield rounded

通常のジェネレータと違って非同期ジェネレータは値を返せないので、ReturnType 型引数はありません。Generator と同様に、SendType は反変的に振る舞います。

If your generator will only yield values, set the SendType to None:

async def infinite_stream(start: int) -> AsyncGenerator[int, None]:
    while True:
        yield start
        start = await increment(start)

あるいは、ジェネレータが AsyncIterable[YieldType] と AsyncIterator[YieldType] のいずれかの戻り値型を持つとアノテートします:

async def infinite_stream(start: int) -> AsyncIterator[int]:
    while True:
        yield start
        start = await increment(start)

Added in version 3.6.1.

バージョン 3.9 で非推奨: collections.abc.AsyncGenerator は添字表記 ([]) をサポートするようになりました。 PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

class typing.AsyncIterable(Generic[T_co])

collections.abc.AsyncIterable の非推奨なエイリアス。

Added in version 3.5.2.

バージョン 3.9 で非推奨: collections.abc.AsyncIterable は添字表記 ([]) をサポートするようになりました。 PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

class typing.AsyncIterator(AsyncIterable[T_co])

collections.abc.AsyncIterator の非推奨なエイリアス。

Added in version 3.5.2.

バージョン 3.9 で非推奨: collections.abc.AsyncIterator は添字表記 ([]) をサポートするようになりました。 PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

class typing.Awaitable(Generic[T_co])

collections.abc.Awaitable の非推奨なエイリアス。

Added in version 3.5.2.

バージョン 3.9 で非推奨: collections.abc.Awaitable は添字表記 ([]) をサポートするようになりました。 PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

Aliases to other ABCs in collections.abc

class typing.Iterable(Generic[T_co])

collections.abc.Iterable の非推奨なエイリアス。

バージョン 3.9 で非推奨: collections.abc.Iterable は添字表記 ([]) をサポートするようになりました。 PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

class typing.Iterator(Iterable[T_co])

collections.abc.Iterator の非推奨なエイリアス。

バージョン 3.9 で非推奨: collections.abc.Iterator は添字表記 ([]) をサポートするようになりました。 PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

typing.Callable

collections.abc.Callable の非推奨なエイリアス。

See 呼び出し可能オブジェクトのアノテーション for details on how to use collections.abc.Callable and typing.Callable in type annotations.

バージョン 3.9 で非推奨: collections.abc.Callable は添字表記 ([]) をサポートするようになりました。 PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

バージョン 3.10 で変更: Callable は ParamSpec と Concatenate をサポートしました。詳細は PEP 612 [https://peps.python.org/pep-0612/] を参照してください。

class typing.Generator(Iterator[YieldType], Generic[YieldType, SendType, ReturnType])

collections.abc.Generator の非推奨なエイリアス。

ジェネレータはジェネリック型 Generator[YieldType, SendType, ReturnType] によってアノテーションを付けられます。例えば:

def echo_round() -> Generator[int, float, str]:
    sent = yield 0
    while sent >= 0:
        sent = yield round(sent)
    return 'Done'

typing モジュールの多くの他のジェネリクスと違い Generator の SendType は共変や不変ではなく、反変として扱われることに注意してください。

If your generator will only yield values, set the SendType and ReturnType to None:

def infinite_stream(start: int) -> Generator[int, None, None]:
    while True:
        yield start
        start += 1

代わりに、ジェネレータを Iterable[YieldType] や Iterator[YieldType] という返り値の型でアノテーションをつけることもできます:

def infinite_stream(start: int) -> Iterator[int]:
    while True:
        yield start
        start += 1

バージョン 3.9 で非推奨: collections.abc.Generator は添字表記 ([]) をサポートするようになりました。 PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

class typing.Hashable

collections.abc.Hashable の非推奨なエイリアス。

バージョン 3.12 で非推奨: 代わりに collections.abc.Hashable を直接使用してください。

class typing.Reversible(Iterable[T_co])

collections.abc.Reversible の非推奨なエイリアス。

バージョン 3.9 で非推奨: collections.abc.Reversible は添字表記 ([]) をサポートするようになりました。 PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

class typing.Sized

collections.abc.Sized の非推奨なエイリアス。

バージョン 3.12 で非推奨: 代わりに collections.abc.Sized を直接使用してください。

Aliases to contextlib ABCs

class typing.ContextManager(Generic[T_co])

contextlib.AbstractContextManager の非推奨なエイリアス。

Added in version 3.5.4.

バージョン 3.9 で非推奨: contextlib.AbstractContextManager は添字表記 ([]) をサポートするようになりました。 PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

class typing.AsyncContextManager(Generic[T_co])

contextlib.AbstractAsyncContextManager の非推奨なエイリアス。

Added in version 3.6.2.

バージョン 3.9 で非推奨: contextlib.AbstractAsyncContextManager は添字表記 ([]) をサポートするようになりました。 PEP 585 [https://peps.python.org/pep-0585/] と ジェネリックエイリアス型 を参照してください。

メジャーな機能の非推奨時系列

typing の機能の中には非推奨のものがあり、Python の将来のバージョンで削除される可能性があります。以下の表は主な非推奨機能をまとめたものです。これは変更される可能性があり、すべての非推奨機能がリストされているわけではありません。

機能

非推奨となるバージョン

削除予定のバージョン

PEP/issue

typing.io and typing.re submodules

3.8

3.13

bpo-38291 [https://bugs.python.org/issue?@action=redirect&bpo=38291]

標準コレクションのエイリアス

3.9

未定（非推奨のエイリアス を参照）

PEP 585 [https://peps.python.org/pep-0585/]

typing.ByteString

3.9

3.14

gh-91896 [https://github.com/python/cpython/issues/91896]

typing.Text

3.11

未定

gh-92332 [https://github.com/python/cpython/issues/92332]

typing.Hashable、typing.Sized

3.12

未定

gh-94309 [https://github.com/python/cpython/issues/94309]

typing.TypeAlias

3.12

未定

PEP 695 [https://peps.python.org/pep-0695/]

pydoc --- Documentation generator and online help system

ソースコード: Lib/pydoc.py [https://github.com/python/cpython/tree/3.12/Lib/pydoc.py]

The pydoc module automatically generates documentation from Python modules. The documentation can be presented as pages of text on the console, served to a web browser, or saved to HTML files.

For modules, classes, functions and methods, the displayed documentation is derived from the docstring (i.e. the __doc__ attribute) of the object, and recursively of its documentable members. If there is no docstring, pydoc tries to obtain a description from the block of comment lines just above the definition of the class, function or method in the source file, or at the top of the module (see inspect.getcomments()).

The built-in function help() invokes the online help system in the interactive interpreter, which uses pydoc to generate its documentation as text on the console. The same text documentation can also be viewed from outside the Python interpreter by running pydoc as a script at the operating system's command prompt. For example, running

python -m pydoc sys

シェルから行うと sys モジュールのドキュメントを、Unix の man コマンドのような形式で表示させることができます。 pydoc の引数として与えることができるのは、関数名・モジュール名・パッケージ名、また、モジュールやパッケージ内のモジュールに含まれるクラス・メソッド・関数へのドット形式での参照です。 pydoc への引数がパスと解釈されるような場合で(オペレーティングシステムのパス区切り記号を含む場合です。例えばUnixならばスラッシュ含む場合になります)、さらに、そのパスがPythonのソースファイルを指しているなら、そのファイルに対するドキュメントが生成されます。

注釈

In order to find objects and their documentation, pydoc imports the module(s) to be documented. Therefore, any code on module level will be executed on that occasion. Use an if __name__ == '__main__': guard to only execute code when a file is invoked as a script and not just imported.

コンソールへの出力時には、 pydoc は読みやすさのために出力をページ化しようと試みます。環境変数 PAGER がセットされていれば pydoc はその値で設定されたページ化プログラムを使います。

引数の前に -w フラグを指定すると、コンソールにテキストを表示させるかわりにカレントディレクトリにHTMLドキュメントを生成します。

引数の前に -k フラグを指定すると、引数をキーワードとして利用可能な全てのモジュールの概要を検索します。検索のやりかたは、Unixの man コマンドと同様です。モジュールの概要というのは、モジュールのドキュメントの一行目のことです。

また、 pydoc を使うことでローカルマシンにウェブブラウザから閲覧可能なドキュメントを提供するHTTPサーバーを起動することもできます。 python -m pydoc -p 1234 とすると、HTTPサーバーをポート1234に起動します。これで、お好きなウェブブラウザを使って http://localhost:1234/ からドキュメントを見ることができます。ポート番号に 0 を指定すると、任意の空きポートが選択されます。

python -m pydoc -n <hostname> は、与えられたホスト名で listen するサーバーを起動します。デフォルトではホスト名は 'localhost' ですが、他のマシンからサーバーへ疎通できるようにしたい場合は、サーバーが応答するホスト名を変更したいと思うでしょう。開発作業中に、コンテナ内で pydoc を走らせたい場合は、これは特に便利です。

python -m pydoc -b では、サーバとして起動するとともにブラウザも起動し、モジュールインデクスページを開きます。提供されるページには、個別のヘルプページに飛ぶための Get ボタン、全モジュールから概要行に基くキーワード検索するための Search ボタン、と、Module index, Topics , Keywords へのそれぞれリンクがついたナビゲーションバーがページの一番上に付きます。

pydoc でドキュメントを生成する場合、その時点での環境とパス情報に基づいてモジュールがどこにあるのか決定されます。そのため、 pydoc spam を実行した場合につくられるドキュメントは、 Pythonインタプリタを起動して import spam と入力したときに読み込まれるモジュールに対するドキュメントになります。

Module docs for core modules are assumed to reside in https://docs.python.org/X.Y/library/ where X and Y are the major and minor version numbers of the Python interpreter. This can be overridden by setting the PYTHONDOCS environment variable to a different URL or to a local directory containing the Library Reference Manual pages.

バージョン 3.2 で変更: -b オプションが追加されました。

バージョン 3.3 で変更: -g コマンドラインオプションが削除されました。

バージョン 3.4 で変更: pydoc now uses inspect.signature() rather than inspect.getfullargspec() to extract signature information from callables.

バージョン 3.7 で変更: -n オプションが追加されました。

Python 開発モード

Added in version 3.7.

The Python Development Mode introduces additional runtime checks that are too expensive to be enabled by default. It should not be more verbose than the default if the code is correct; new warnings are only emitted when an issue is detected.

It can be enabled using the -X dev command line option or by setting the PYTHONDEVMODE environment variable to 1.

See also Python debug build.

Effects of the Python Development Mode

Enabling the Python Development Mode is similar to the following command, but with additional effects described below:

PYTHONMALLOC=debug PYTHONASYNCIODEBUG=1 python -W default -X faulthandler

Effects of the Python Development Mode:

Add default warning filter. The following warnings are shown:

DeprecationWarning

ImportWarning

PendingDeprecationWarning

ResourceWarning

Normally, the above warnings are filtered by the default warning filters.

It behaves as if the -W default command line option is used.

Use the -W error command line option or set the PYTHONWARNINGS environment variable to error to treat warnings as errors.

Install debug hooks on memory allocators to check for:

Buffer underflow

Buffer overflow

Memory allocator API violation

Unsafe usage of the GIL

See the PyMem_SetupDebugHooks() C function.

It behaves as if the PYTHONMALLOC environment variable is set to debug.

To enable the Python Development Mode without installing debug hooks on memory allocators, set the PYTHONMALLOC environment variable to default.

Call faulthandler.enable() at Python startup to install handlers for the SIGSEGV, SIGFPE, SIGABRT, SIGBUS and SIGILL signals to dump the Python traceback on a crash.

It behaves as if the -X faulthandler command line option is used or if the PYTHONFAULTHANDLER environment variable is set to 1.

Enable asyncio debug mode. For example, asyncio checks for coroutines that were not awaited and logs them.

It behaves as if the PYTHONASYNCIODEBUG environment variable is set to 1.

Check the encoding and errors arguments for string encoding and decoding operations. Examples: open(), str.encode() and 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.

The io.IOBase destructor logs close() exceptions.

Set the dev_mode attribute of sys.flags to True.

The Python Development Mode does not enable the tracemalloc module by default, because the overhead cost (to performance and memory) would be too large. Enabling the tracemalloc module provides additional information on the origin of some errors. For example, ResourceWarning logs the traceback where the resource was allocated, and a buffer overflow error logs the traceback where the memory block was allocated.

The Python Development Mode does not prevent the -O command line option from removing assert statements nor from setting __debug__ to False.

The Python Development Mode can only be enabled at the Python startup. Its value can be read from sys.flags.dev_mode.

バージョン 3.8 で変更: The io.IOBase destructor now logs close() exceptions.

バージョン 3.9 で変更: The encoding and errors arguments are now checked for string encoding and decoding operations.

ResourceWarning Example

Example of a script counting the number of lines of the text file specified in the command line:

import sys

def main():
    fp = open(sys.argv[1])
    nlines = len(fp.readlines())
    print(nlines)
    # The file is closed implicitly

if __name__ == "__main__":
    main()

The script does not close the file explicitly. By default, Python does not emit any warning. Example using README.txt, which has 269 lines:

$ python script.py README.txt
269

Enabling the Python Development Mode displays a ResourceWarning warning:

$ 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

In addition, enabling tracemalloc shows the line where the file was opened:

$ 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])

The fix is to close explicitly the file. Example using a context manager:

def main():
    # Close the file explicitly when exiting the with block
    with open(sys.argv[1]) as fp:
        nlines = len(fp.readlines())
    print(nlines)

Not closing a resource explicitly can leave a resource open for way longer than expected; it can cause severe issues upon exiting Python. It is bad in CPython, but it is even worse in PyPy. Closing resources explicitly makes an application more deterministic and more reliable.

Bad file descriptor error example

Script displaying the first line of itself:

import os

def main():
    fp = open(__file__)
    firstline = fp.readline()
    print(firstline.rstrip())
    os.close(fp.fileno())
    # The file is closed implicitly

main()

By default, Python does not emit any warning:

$ python script.py
import os

The Python Development Mode shows a ResourceWarning and logs a "Bad file descriptor" error when finalizing the file object:

$ 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

os.close(fp.fileno()) closes the file descriptor. When the file object finalizer tries to close the file descriptor again, it fails with the Bad file descriptor error. A file descriptor must be closed only once. In the worst case scenario, closing it twice can lead to a crash (see bpo-18748 [https://bugs.python.org/issue?@action=redirect&bpo=18748] for an example).

The fix is to remove the os.close(fp.fileno()) line, or open the file with closefd=False.

doctest --- Test interactive Python examples

ソースコード: Lib/doctest.py [https://github.com/python/cpython/tree/3.12/Lib/doctest.py]

doctest モジュールは、対話的 Python セッションのように見えるテキストを探し出し、セッションの内容を実行して、そこに書かれている通りに振舞うかを調べます。 doctest は以下のような用途によく使われています:

モジュールの docstring (ドキュメンテーション文字列) 中にある対話実行例のすべてが書かれている通りに動作するか検証することで、docstring の内容が最新かどうかチェックする。

テストファイルやテストオブジェクト中の対話実行例が期待通りに動作するかを検証することで、回帰テストを実現します。

入出力例を豊富に使ったパッケージのチュートリアルドキュメントが書けます。入出力例と解説文のどちらに注目するかによって、ドキュメントは「読めるテスト」にも「実行できるドキュメント」にもなります。

以下に完全かつ短い実行例を示します:

"""
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()

example.py をコマンドラインから直接実行すると、 doctest はその魔法を働かせます:

$ python example.py
$

出力は何もありません！しかしこれが正常で、すべての実行例が正しく動作することを意味しています。スクリプトに -v を与えると、 doctest は何を行おうとしているのかを記録した詳細なログを出力し、最後にまとめを出力します:

$ 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

といった具合で、最後には:

Trying:
    factorial(1e100)
Expecting:
    Traceback (most recent call last):
        ...
    OverflowError: n too large
ok
2 items passed all tests:
   1 tests in __main__
   8 tests in __main__.factorial
9 tests in 2 items.
9 passed and 0 failed.
Test passed.
$

That's all you need to know to start making productive use of 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 Lib/test/test_doctest/test_doctest.py.

簡単な利用法: docstring 中の実行例をチェックする

The simplest way to start using doctest (but not necessarily the way you'll continue to do it) is to end each module M with:

if __name__ == "__main__":
    import doctest
    doctest.testmod()

doctest then examines docstrings in module M.

モジュールをスクリプトとして実行すると、docstring 中の実行例が実行され、検証されます:

python M.py

docstring に書かれた実行例の実行が失敗しない限り、何も表示されません。失敗すると、失敗した実行例と、その原因が (場合によっては複数) 標準出力に印字され、最後に ***Test Failed*** N failures. という行を出力します。ここで、N は失敗した実行例の数です。

一方、-v スイッチをつけて走らせると:

python M.py -v

実行を試みたすべての実行例について詳細に報告し、最後に各種まとめを行った内容が標準出力に印字されます。

verbose=True を testmod() に渡せば、詳細報告 (verbose) モードを強制できます。また、 verbose=False にすれば禁止できます。どちらの場合にも、 testmod() は sys.argv 上のスイッチを調べません。(したがって、 -v をつけても効果はありません)。

testmod() を実行するコマンドラインショートカットもあります。 Python インタプリタに doctest モジュールを標準ライブラリから直接実行して、テストするモジュール名をコマンドライン引数に与えます:

python -m doctest -v example.py

こうすると example.py を単体モジュールとしてインポートして、それに対して testmod() を実行します。このファイルがパッケージの一部で他のサブモジュールをそのパッケージからインポートしている場合はうまく動かないことに注意してください。

testmod() の詳しい情報は 基本 API 節を参照してください。

簡単な利用法: テキストファイル中の実行例をチェックする

doctest のもう一つの簡単な用途は、テキストファイル中にある対話実行例に対するテストです。これには testfile() 関数を使います:

import doctest
doctest.testfile("example.txt")

この短いスクリプトは、 example.txt というファイルの中に入っている対話モードの Python 操作例すべてを実行して、その内容を検証します。ファイルの内容は一つの巨大な docstring であるかのように扱われます; ファイルが Python プログラムである必要はありません！例えば、 example.txt には以下のような内容が入っているとします:

The ``example`` module
======================

Using ``factorial``
-------------------

This is an example text file in reStructuredText format.  First import
``factorial`` from the ``example`` module:

    >>> from example import factorial

Now use it:

    >>> factorial(6)
    120

doctest.testfile("example.txt") を実行すると、このドキュメント内のエラーを見つけ出します:

File "./example.txt", line 14, in example.txt
Failed example:
    factorial(6)
Expected:
    120
Got:
    720

testmod() と同じく、 testfile() は実行例が失敗しない限り何も表示しません。実行例が失敗すると、失敗した実行例とその原因が (場合によっては複数) testmod() と同じ書式で標準出力に書き出されます。

デフォルトでは、 testfile() は自分自身を呼び出したモジュールのあるディレクトリを探します。その他の場所にあるファイルを見に行くように testfile() に指示するためのオプション引数についての説明は 基本 API 節を参照してください。

testmod() と同様に testfile() の冗長性 (verbosity) はコマンドラインスイッチ -v またはオプションのキーワード引数 verbose によって指定できます。

testfile() を実行するコマンドラインショートカットもあります。 Python インタプリタに doctest モジュールを標準ライブラリから直接実行して、テストするモジュール名をコマンドライン引数に与えます:

python -m doctest -v example.txt

ファイル名が .py で終っていないので、 doctest は testmod() ではなく testfile() を使って実行するのだと判断します。

testfile() の詳細は 基本 API 節を参照してください。

doctest のからくり

この節では、doctest のからくり: どの docstring を見に行くのか、どのように対話実行例を見つけ出すのか、どんな実行コンテキストを使うのか、例外をどう扱うか、上記の振る舞いを制御するためにどのようなオプションフラグを使うか、について詳しく吟味します。こうした情報は、doctest に対応した実行例を書くために必要な知識です; 書いた実行例に対して実際に doctest を実行する上で必要な情報については後続の節を参照してください。

どの docstring が検証されるのか?

モジュールの docstring と、すべての関数、クラスおよびメソッドの docstring が検索されます。モジュールに import されたオブジェクトは検索されません。

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 __test__ and uses it to locate other tests. If 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 M.__test__ are searched, and strings are treated as if they were docstrings. In output, a key K in M.__test__ appears with name M.__test__.K.

For example, place this block of code at the top of example.py:

__test__ = {
    'numbers': """
>>> factorial(6)
720

>>> [factorial(n) for n in range(6)]
[1, 1, 2, 6, 24, 120]
"""
}

The value of 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, doctest searches them recursively for docstrings, which are then scanned for tests.

検索中に見つかったクラスも同様に再帰的に検索が行われ、クラスに含まれているメソッドおよびネストされたクラスについて docstring のテストが行われます。

docstring 内の実行例をどのように認識するのか?

ほとんどの場合、対話コンソールセッション上でのコピー／ペーストはうまく動作します。とはいえ、doctest は特定の Python シェルの振る舞いを正確にエミュレーションしようとするわけではありません。

>>> # comments are ignored
>>> x = 12
>>> x
12
>>> if x == 13:
...     print("yes")
... else:
...     print("no")
...     print("NO")
...     print("NO!!!")
...
no
NO
NO!!!
>>>

コードを含む最後の '>>> ' または '... ' 行の直下に期待する出力結果が置かれます。(出力結果がもしあれば) それは次の '>>> ' 行か、すべて空白文字の行まで続きます。

詳細事項:

期待する出力結果には、空白だけの行が入っていてはなりません。そのような行は期待する出力結果の終了を表すと見なされるからです。もし期待する出力結果の内容に空白行が入っている場合には、空白行が入るべき場所すべてに <BLANKLINE> を入れてください。

全てのタブ文字は 8 カラムのタブ位置でスペースに展開されます。テスト対象のコードが作成した出力にあるタブは変更されません。出力例にあるどんなタブも展開 される ので、コードの出力がハードタブを含んでいた場合、 doctest が通るには NORMALIZE_WHITESPACE オプションか directive を有効にするしかありません。そうする代わりに、テストが出力を読み取りテストの一部として期待される値と正しく比較するように、テストを書き直すこともできます。このソース中のタブの扱いは試行錯誤の結果であり、タブの扱いの中で最も問題の起きにくいものだということが分かっています。タブの扱いについては、独自の DocTestParser クラスを実装して、別のアルゴリズムを使うこともできます。

標準出力への出力は取り込まれますが、標準エラーは取り込まれません (例外発生時のトレースバックは別の方法で取り込まれます)。

対話セッションにおいて、バックスラッシュを用いて次の行に続ける場合や、その他の理由でバックスラッシュを用いる場合、raw docstring を使ってバックスラッシュを入力どおりに扱わせるようにしなければなりません:

>>> def f(x):
...     r'''Backslashes in a raw docstring: m\n'''
...
>>> print(f.__doc__)
Backslashes in a raw docstring: m\n

そうしない場合は、バックスラッシュは文字列の一部として解釈されます。例えば、上の \n は改行文字として解釈されてしまいます。それ以外の方法では、doctest にあるバックスラッシュを二重にする (そして raw string を使わない) という方法もあります:

>>> def f(x):
...     '''Backslashes in a raw docstring: m\\n'''
...
>>> print(f.__doc__)
Backslashes in a raw docstring: m\n

開始カラムはどこでもかまいません:

>>> assert "Easy!"
      >>> import math
          >>> math.floor(1.9)
          1

期待する出力結果の先頭部にある空白文字列は、実行例の開始部分にあたる '>>> ' 行の先頭にある空白文字列と同じだけ取り除かれます。

実行コンテキストとは何か?

By default, each time doctest finds a docstring to test, it uses a shallow copy of M's globals, so that running tests doesn't change the module's real globals, and so that one test in 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 M, and names defined earlier in the docstring being run. Examples cannot see names defined in other docstrings.

testmod() や testfile() に globs=your_dict を渡し、自前の辞書を実行コンテキストとして使うこともできます。

例外はどう扱えばよいか?

トレースバックが実行例によって生成される唯一の出力なら問題ありません。単にトレースバックを貼り付けてください。[1] トレースバックには、頻繁に変更されがちな情報 (例えばファイルパスや行番号など) が入っているものなので、これは受け入れるテスト結果に柔軟性を持たせようと doctest が苦労している部分の一つです。

簡単な例を示しましょう:

>>> [1, 2, 3].remove(42)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: list.remove(x): x not in list

この doctest は、 ValueError が送出され、その詳細情報が list.remove(x): x not in list である場合に成功します。

例外が発生したときの期待する出力はトレースバックヘッダから始まっていなければなりません。トレースバックの形式は以下の二通りの行のいずれかで、実行例の最初の行と同じインデントでなければりません:

Traceback (most recent call last):
Traceback (innermost last):

トレースバックヘッダの後ろにトレースバックスタックが続いてもかまいませんが、doctest はその内容を無視します。普通はトレースバックスタックを省略するか、対話セッションからそのままコピーしてきます。

トレースバックスタックの後ろにはもっとも有意義な部分、例外の型と詳細情報の入った行があります。これは通常トレースバックの最後の行ですが、例外が複数行の詳細情報を持っている場合、複数の行にわたることもあります:

>>> raise ValueError('multi\n    line\ndetail')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: multi
    line
detail

上の例では、最後の 3 行 (ValueError から始まる行) における例外の型と詳細情報だけが比較され、それ以外の部分は無視されます。

例外を扱うコツは、実行例をドキュメントとして読む上で明らかに価値のある情報でない限り、トレースバックスタックは省略する、ということです。したがって、先ほどの例は以下のように書くべきでしょう:

>>> raise ValueError('multi\n    line\ndetail')
Traceback (most recent call last):
    ...
ValueError: multi
    line
detail

トレースバックの扱いは非常に特殊なので注意してください。特に、上の書き直した実行例では、 ... の扱いは doctest の ELLIPSIS オプションとは独立しています。この例での省略記号は何かの省略を表しているかもしれませんし、コンマや数字が 3 個 (または 300 個) かもしれませんし、 Monty Python のスキットをインデントして書き写したものかもしれません。

以下の詳細はずっと覚えておく必要はないのですが、一度目を通しておいてください:

doctest は期待する出力の出所が print 文なのか例外なのかを推測できません。したがって、例えば期待する出力が ValueError: 42 is prime であるような実行例は、 ValueError が実際に送出された場合と、万が一期待する出力と同じ文字列を print した場合の両方で成功してしまいます。現実的には、通常の出力がトレースバックヘッダから始まることはないので、実際に問題になることはないでしょう。

トレースバックスタック (がある場合) の各行は、実行例の最初の行よりも深くインデントされているか、または 英数文字以外で始まっていなければなりません。トレースバックヘッダ以後に現れる行のうち、インデントが等しく英数文字で始まる最初の行は例外の詳細情報が書かれた行とみなされるからです。もちろん、本物のトレースバックでは正しく動作します。

doctest のオプション IGNORE_EXCEPTION_DETAIL を指定した場合、最も左端のコロン以後の全ての内容と、例外名の中の全てのモジュール情報が無視されます。

対話シェルでは、 SyntaxError の場合にトレースバックヘッダが省略されることがあります。しかし doctest にとっては、例外を例外でないものと区別するためにトレースバックヘッダが必要です。そこで、トレースバックヘッダを省略するような SyntaxError をテストする必要があるというごく稀なケースでは、実行例にトレースバックヘッダを手作業で追加する必要があるでしょう。

For some exceptions, Python displays the position of the error using ^ markers and tildes:

>>> 1 + None
  File "<stdin>", line 1
    1 + None
    ~~^~~~~~
TypeError: unsupported operand type(s) for +: 'int' and 'NoneType'

例外の型と詳細情報の前にエラー位置を示す行がくるため、doctest はこの行を調べません。例えば、以下の例では、間違った場所に ^ マーカを入れても成功してしまいます:

>>> 1 + None
  File "<stdin>", line 1
    1 + None
    ^~~~~~~~
TypeError: unsupported operand type(s) for +: 'int' and 'NoneType'

オプションフラグ

doctest の振る舞いは、数多くのオプションフラグによって様々な側面から制御されています。フラグのシンボル名はモジュールの定数として提供され、 ビット単位論理和 でつないで様々な関数に渡すことができます。シンボル名は doctest directives でも使用でき、doctest コマンドラインインターフェースに -o を通して与えることができます。

Added in version 3.4: -o コマンドラインオプション

最初に説明するオプション群は、テストのセマンティクスを決めます。すなわち、実際にテストを実行したときの出力と実行例中の期待する出力とが一致しているかどうかを doctest がどのように判断するかを制御します:

doctest.DONT_ACCEPT_TRUE_FOR_1

デフォルトでは、期待する出力ブロックに単に 1 だけが入っており、実際の出力ブロックに 1 または True だけが入っていた場合、これらの出力は一致しているとみなされます。 0 と False の場合も同様です。 DONT_ACCEPT_TRUE_FOR_1 を指定すると、こうした値の読み替えを行いません。デフォルトの挙動で読み替えを行うのは、最近の Python で多くの関数の戻り値型が整数型からブール型に変更されたことに対応するためです; 読み替えを行う場合、"通常の整数" の出力を期待する出力とするような doctest も動作します。このオプションはそのうちなくなるでしょうが、ここ数年はそのままでしょう。

doctest.DONT_ACCEPT_BLANKLINE

デフォルトでは、期待する出力ブロックに <BLANKLINE> だけの入った行がある場合、その行は実際の出力における空行に一致するようになります。完全な空行を入れてしまうと期待する出力がそこで終わっているとみなされてしまうため、期待する出力に空行を入れたい場合にはこの方法を使わなければなりません。 DONT_ACCEPT_BLANKLINE を指定すると、 <BLANKLINE> の読み替えを行わなくなります。

doctest.NORMALIZE_WHITESPACE

このフラグを指定すると、連続する空白 (空白と改行文字) は互いに等価であるとみなします。期待する出力における任意の空白列は実際の出力における任意の空白と一致します。デフォルトでは、空白は厳密に一致しなければなりません。 NORMALIZE_WHITESPACE は、期待する出力の内容が非常に長いために、ソースコード中でその内容を複数行に折り返して書きたい場合に特に便利です。

doctest.ELLIPSIS

このフラグを指定すると、期待する出力中の省略記号マーカ (...) が実際の出力中の任意の部分文字列と一致するようになります。部分文字列は行境界にわたるものや空文字列を含みます。したがって、このフラグを使うのは単純な内容を対象にする場合にとどめましょう。複雑な使い方をすると、正規表現に .* を使ったときのように "しまった、マッチしすぎた！ (match too much!)" と驚くことになりかねません。

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 ValueError: 42 will pass if the actual exception raised is ValueError: 3*14, but will fail if, say, a 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:

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

Note that 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 で変更: doctest モジュールの IGNORE_EXCEPTION_DETAIL フラグが、 テストされている例外を含むモジュールの名前を無視するようになりました。

doctest.SKIP

このフラグを指定すると、実行例は一切実行されません。こうした機能は doctest の実行例がドキュメントとテストを兼ねていて、ドキュメントのためには含めておかなければならないけれどチェックされなくても良い、というような文脈で役に立ちます。例えば、実行例の出力がランダムであるとか、テストドライバーには利用できないリソースに依存している場合などです。

SKIP フラグは一時的に実行例を"コメントアウト"するのにも使えます。

doctest.COMPARISON_FLAGS

上記の比較フラグすべての論理和をとったビットマスクです。

二つ目のオプション群は、テストの失敗を報告する方法を制御します:

doctest.REPORT_UDIFF

このオプションを指定すると、期待する出力および実際の出力が複数行になるときにテストの失敗結果を unified diff 形式を使って表示します。

doctest.REPORT_CDIFF

このオプションを指定すると、期待する出力および実際の出力が複数行になるときにテストの失敗結果を context diff 形式を使って表示します。

doctest.REPORT_NDIFF

このオプションを指定すると、期待する出力と実際の出力との間の差分を difflib.Differ を使って算出します。使われているアルゴリズムは有名な ndiff.py ユーティリティと同じです。これは、行単位の差分と同じように行内の差分にマーカをつけられるようにする唯一の手段です。例えば、期待する出力のある行に数字の 1 が入っていて、実際の出力には l が入っている場合、不一致の起きているカラム位置を示すキャレットの入った行が一行挿入されます。

doctest.REPORT_ONLY_FIRST_FAILURE

このオプションを指定すると、各 doctest で最初にエラーの起きた実行例だけを表示し、それ以後の実行例の出力を抑制します。これにより、正しく書かれた実行例が、それ以前の実行例の失敗によっておかしくなってしまった場合に、 doctest がそれを報告しないようになります。とはいえ、最初に失敗を引き起こした実行例とは関係なく誤って書かれた実行例の報告も抑制してしまいます。 REPORT_ONLY_FIRST_FAILURE を指定した場合、実行例がどこかで失敗しても、それ以後の実行例を続けて実行し、失敗したテストの総数を報告します; 出力が抑制されるだけです。

doctest.FAIL_FAST

このオプションを指定すると、最初に実行例が失敗した時点で終了し、残りの実行例を実行しません。つまり、報告される失敗の数はたかだか 1 つになります。最初の失敗より後の例はデバッグ出力を生成しないため、このフラグはデバッグの際に有用でしょう。

doctest コマンドラインは -f を -o FAIL_FAST の短縮形として受け付けます。

Added in version 3.4.

doctest.REPORTING_FLAGS

上記のエラー報告に関するフラグすべての論理和をとったビットマスクです。

サブクラス化で doctest 内部を拡張するつもりがなければ役に立ちませんが、別の新しいオプションフラグ名を登録する方法もあります:

doctest.register_optionflag(name)

名前 name の新たなオプションフラグを作成し、作成されたフラグの整数値を返します。 register_optionflag() は OutputChecker や DocTestRunner をサブクラス化して、その中で新たに作成したオプションをサポートさせる際に使います。 register_optionflag() は以下のような定形文で呼び出さなければなりません:

MY_FLAG = register_optionflag('MY_FLAG')

ディレクティブ (Directives)

doctest ディレクティブは個々の実行例の オプションフラグ を操作するために使われます。 doctest ディレクティブは後のソースコード例にあるような特殊な Python コメントです:

directive             ::=  "#" "doctest:" directive_options
directive_options     ::=  directive_option ("," directive_option)*
directive_option      ::=  on_or_off directive_option_name
on_or_off             ::=  "+" | "-"
directive_option_name ::=  "DONT_ACCEPT_BLANKLINE" | "NORMALIZE_WHITESPACE" | ...

+ や - とディレクティブオプション名の間に空白を入れてはなりません。ディレクティブオプション名は上で説明したオプションフラグ名のいずれかです。

ある実行例の doctest ディレクティブは、その実行例だけの doctest の振る舞いを変えます。ある特定の挙動を有効にしたければ + を、無効にしたければ - を使います。

例えば、以下のテストは成功します:

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

ディレクティブがない場合、実際の出力には一桁の数字の間に二つスペースが入っていないこと、実際の出力は 1 行になることから、テストは成功しないはずです。別のディレクティブを使って、このテストを成功させることもできます:

>>> print(list(range(20)))  # doctest: +ELLIPSIS
[0, 1, ..., 18, 19]

複数のディレクティブは、一つの物理行の中にコンマで区切って指定できます:

>>> print(list(range(20)))  # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
[0,    1, ...,   18,    19]

一つの実行例中で複数のディレクティブコメントを使った場合、それらは組み合わされます:

>>> print(list(range(20)))  # doctest: +ELLIPSIS
...                         # doctest: +NORMALIZE_WHITESPACE
[0,    1, ...,   18,    19]

この実行例で分かるように、実行例にはディレクティブだけを含む ... 行を追加することができます。この書きかたは、実行例が長すぎるためにディレクティブを同じ行に入れると収まりが悪い場合に便利です:

>>> print(list(range(5)) + list(range(10, 20)) + list(range(30, 40)))
... # doctest: +ELLIPSIS
[0, ..., 4, 10, ..., 19, 30, ..., 39]

フォルトではすべてのオプションが無効になっており、ディレクティブは特定の実行例だけに影響を及ぼすので、通常意味があるのは有効にするためのオプション (+ のついたディレクティブ) だけです。とはいえ、doctest を実行する関数はオプションフラグを指定してデフォルトとは異なった挙動を実現できるので、そのような場合には - を使った無効化オプションも意味を持ちます。

警告

doctest では、期待する出力に対する完全一致を厳格に求めます。一致しない文字が一文字でもあると、テストは失敗してしまいます。このため、 Python が出力に関して何を保証していて、何を保証していないかを正確に知っていないと混乱させられることがあるでしょう。例えば、集合を出力する際、 Python は要素がある特定の順番で並ぶよう保証してはいません。したがって、以下のようなテスト

>>> foo()
{"spam", "eggs"}

は失敗するかもしれないのです! 回避するには

>>> foo() == {"spam", "eggs"}
True

とするのが一つのやり方です。別のやり方は

>>> d = sorted(foo())
>>> d
['eggs', 'spam']

他のやり方もありますが、あとは自分で考えてみてください。

以下のように、オブジェクトアドレスを埋め込むような結果を print するのもよくありません :

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

ELLIPSIS ディレクティブを使うと、上のような例をうまく解決できます:

>>> C()  # doctest: +ELLIPSIS
<C object at 0x...>

浮動小数点数もまた、プラットフォーム間での微妙な出力の違いの原因となります。というのも、Python は浮動小数点の書式化をプラットフォームの C ライブラリに委ねており、この点では、C ライブラリはプラットフォーム間で非常に大きく異なっているからです。

>>> 1./7  # risky
0.14285714285714285
>>> print(1./7) # safer
0.142857142857
>>> print(round(1./7, 6)) # much safer
0.142857

I/2.**J の形式になる数値はどのプラットフォームでもうまく動作するので、私はこの形式の数値を生成するように doctest の実行例を工夫しています:

>>> 3./4  # utterly safe
0.75

単純な分数は人間にとっても理解しやすく、良いドキュメントを書くために役に立ちます。

基本 API

数 testmod() と testfile() は、ほとんどの基本的な用途に十分な doctest インターフェースを提供しています。これら二つの関数についてあまり形式的でない入門が読みたければ、 簡単な利用法: docstring 中の実行例をチェックする 節や 簡単な利用法: テキストファイル中の実行例をチェックする 節を参照してください。

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)

filename 以外の引数はすべてオプションで、キーワード引数形式で指定しなければなりません。

filename に指定したファイル内にある実行例をテストします。(failure_count, test_count) を返します。

オプション引数の module_relative は、ファイル名をどのように解釈するかを指定します:

module_relative が True (デフォルト) の場合、filename は OS に依存しないモジュールの相対パスになります。デフォルトでは、このパスは関数 testfile() を呼び出しているモジュールからの相対パスになります; ただし、package 引数を指定した場合には、パッケージからの相対になります。OS への依存性を除くため、filename ではパスを分割する文字に / を使わなければならず、絶対パスにしてはなりません (パス文字列を / で始めてはなりません)。

module_relative が False の場合、filename は OS 依存のパスを示します。パスは絶対パスでも相対パスでもかまいません; 相対パスにした場合、現在の作業ディレクトリを基準に解決します。

オプション引数 name には、テストの名前を指定します; デフォルトの場合や None を指定した場合、os.path.basename(filename) になります。

オプション引数 package には、Python パッケージを指定するか、モジュール相対のファイル名の場合には相対の基準ディレクトリとなる Python パッケージの名前を指定します。パッケージを指定しない場合、関数を呼び出しているモジュールのディレクトリを相対の基準ディレクトリとして使います。module_relative を False に指定している場合、package を指定するとエラーになります。

オプション引数 globs には辞書を指定します。この辞書は、実行例を実行する際のグローバル変数として用いられます。doctest はこの辞書の浅いコピーを生成するので、実行例は白紙の状態からスタートします。デフォルトの場合や None を指定した場合、新たな空の辞書になります。

オプション引数 extraglobs には辞書を指定します。この辞書は、実行例を実行する際にグローバル変数にマージされます。マージは dict.update() のように振舞います: globs と extraglobs との間に同じキー値がある場合、両者を合わせた辞書中には extraglobs の方の値が入ります。デフォルト、または None であるとき、追加のグローバル変数は使われません。この仕様は、パラメータ付きで doctest を実行するという、やや進んだ機能です。例えば、一般的な名前を使って基底クラス向けに doctest を書いておき、その後で辞書で一般的な名前からテストしたいサブクラスへの対応付けを行う辞書を extraglobs に渡して、様々なサブクラスをテストできます。

オプション引数 verbose が真の場合、様々な情報を出力します。偽の場合にはテストの失敗だけを報告します。デフォルトの場合や None を指定した場合、sys.argv に '-v' を指定しない限りこの値は真になりません。

オプション引数 report が真の場合、テストの最後にサマリを出力します。それ以外の場合には何も出力しません。verbose モードの場合、サマリには詳細な情報を出力しますが、そうでない場合にはサマリはとても簡潔になります (実際には、すべてのテストが成功した場合には何も出力しません)。

オプション引数 optionflags (デフォルト値 0) は、各オプションフラグの ビット単位論理和 を取ります。 オプションフラグ 節を参照してください。

オプション引数 raise_on_error の値はデフォルトでは偽です。真にすると、最初のテスト失敗や予期しない例外が起きたときに例外を送出します。このオプションを使うと、失敗の原因を検死デバッグ (post-mortem debug) できます。デフォルトの動作では、実行例の実行を継続します。

オプション引数 parser には、 DocTestParser (またはそのサブクラス) を指定します。このクラスはファイルから実行例を抽出するために使われます。デフォルトでは通常のパーザ (DocTestParser()) です。

オプション引数 encoding にはファイルをユニコードに変換する際に使われるエンコーディングを指定します。

doctest.testmod(m=None, name=None, globs=None, verbose=None, report=True, optionflags=0, extraglobs=None, raise_on_error=False, exclude_empty=False)

引数はすべてオプションで、m 以外の引数はキーワード引数として指定しなければなりません。

モジュール m (m を指定しないか None にした場合には __main__) から到達可能な関数およびクラスの docstring 内にある実行例をテストします。 m.__doc__ 内の実行例からテストを開始します。

Also test examples reachable from dict m.__test__, if it exists. 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.

モジュール m に属するオブジェクトにつけられた docstring のみを検索します。

(failure_count, test_count) を返します。

オプション引数 name には、モジュールの名前を指定します。デフォルトの場合や None を指定した場合には、m.__name__ を使います。

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 doctest.master.summarize in conjunction with testmod() continues to get output for objects with no tests. The exclude_empty argument to the newer DocTestFinder constructor defaults to true.

オプション引数 extraglobs, verbose, report, optionflags, raise_on_error, および globs は上で説明した testfile() の引数と同じです。ただし、 globs のデフォルト値は m.__dict__ になります。

doctest.run_docstring_examples(f, globs, verbose=False, name='NoName', compileflags=None, optionflags=0)

オブジェクト f に関連付けられた実行例をテストします。 f は文字列、モジュール、関数、またはクラスオブジェクトです。

引数 globs に辞書を指定すると、その浅いコピーを実行コンテキストに使います。

オプション引数 name はテスト失敗時のメッセージに使われます。デフォルトの値は 'NoName' です。

オプション引数 verbose の値を真にすると、テストが失敗しなくても出力を生成します。デフォルトでは、実行例のテストに失敗したときのみ出力を生成します。

オプション引数 compileflags には、実行例を実行するときに Python バイトコードコンパイラが使うフラグを指定します。デフォルトの場合や None を指定した場合、フラグは globs 内にある future 機能セットに対応したものになります。

オプション引数 optionflags は、上で述べた testfile() と同様の働きをします。

単体テスト API

As your collection of doctest'ed modules grows, you'll want a way to run all their doctests systematically. doctest provides two functions that can be used to create unittest test suites from modules and text files containing doctests. To integrate with unittest test discovery, include a load_tests function in your test module:

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

doctest の入ったテキストファイルやモジュールから unittest.TestSuite インスタンスを生成するための主な関数は二つあります:

doctest.DocFileSuite(*paths, module_relative=True, package=None, setUp=None, tearDown=None, globs=None, optionflags=0, parser=DocTestParser(), encoding=None)

単一または複数のテキストファイルに入っている doctest 形式のテストを、 unittest.TestSuite インスタンスに変換します。

The returned 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 failureException exception is raised showing the name of the file containing the test and a (sometimes approximate) line number.

関数には、テストを行いたい一つまたは複数のファイルへのパスを (文字列で) 渡します。

DocFileSuite() には、キーワード引数でオプションを指定できます:

オプション引数 module_relative は paths に指定したファイル名をどのように解釈するかを指定します:

module_relative が True (デフォルト) の場合、paths 中のファイル名は OS に依存しないモジュールの相対パスになります。デフォルトでは、このパスは呼び出し元のモジュールのディレクトリからの相対パスになります; ただし、package 引数を指定した場合には、パッケージからの相対になります。OS への依存性を除くため、各ファイル名はパスを分割するのに / 文字を使わなければならず、絶対パスにしてはなりません (パス文字列を / で始めてはなりません)。

module_relative が False の場合、filename は OS 依存のパスを示します。パスは絶対パスでも相対パスでもかまいません; 相対パスにした場合、現在の作業ディレクトリを基準に解決します。

オプション引数 package には、Python パッケージを指定するか、モジュール相対のファイル名の場合には相対の基準ディレクトリとなる Python パッケージの名前を指定します。パッケージを指定しない場合、関数を呼び出しているモジュールのディレクトリを相対の基準ディレクトリとして使います。module_relative を False に指定している場合、package を指定するとエラーになります。

オプション引数 setUp には、テストスイートのセットアップに使う関数を指定します。この関数は、各ファイルのテストを実行する前に呼び出されます。 setUp 関数は DocTest オブジェクトに引き渡されます。 setUp は globs 属性を介してテストのグローバル変数にアクセスできます。

オプション引数 tearDown には、テストを解体 (tear-down) するための関数を指定します。この関数は、各ファイルのテストの実行を終了するたびに呼び出されます。 tearDown 関数は DocTest オブジェクトに引き渡されます。 tearDown は globs 属性を介してテストのグローバル変数にアクセスできます。

オプション引数 globs は辞書で、テストのグローバル変数の初期値が入ります。この辞書は各テストごとに新たにコピーして使われます。デフォルトでは globs は空の新たな辞書です。

オプション引数 optionflags には、テストを実行する際にデフォルトで適用される doctest オプションを OR で結合して指定します。 オプションフラグ 節を参照してください。結果レポートに関するオプションを指定するより適切な方法は下記の set_unittest_reportflags() の説明を参照してください。

オプション引数 parser には、 DocTestParser (またはそのサブクラス) を指定します。このクラスはファイルから実行例を抽出するために使われます。デフォルトでは通常のパーザ (DocTestParser()) です。

オプション引数 encoding にはファイルをユニコードに変換する際に使われるエンコーディングを指定します。

DocFileSuite() を使用してテキストファイルからロードされた doctests に提供される globals に、グローバル変数 __file__ が追加されます。

doctest.DocTestSuite(module=None, globs=None, extraglobs=None, test_finder=None, setUp=None, tearDown=None, optionflags=0, checker=None)

doctest のテストを unittest.TestSuite に変換します。

The returned unittest.TestSuite is to be run by the unittest framework and runs each doctest in the module. If any of the doctests fail, then the synthesized unit test fails, and a failureException exception is raised showing the name of the file containing the test and a (sometimes approximate) line number.

オプション引数 module には、テストしたいモジュールの名前を指定します。module にはモジュールオブジェクトまたは (ドット表記の) モジュール名を指定できます。module を指定しない場合、この関数を呼び出しているモジュールになります。

オプション引数 globs は辞書で、テストのグローバル変数の初期値が入ります。この辞書は各テストごとに新たにコピーして使われます。デフォルトでは globs は空の新たな辞書です。

オプション引数 extraglobs には追加のグローバル変数セットを指定します。この変数セットは globs に統合されます。デフォルトでは、追加のグローバル変数はありません。

オプション引数 test_finder は、モジュールから doctest を抽出するための DocTestFinder オブジェクト (またはその代替となるオブジェクト) です。

オプション引数 setUp 、 tearDown 、および optionflags は上の DocFileSuite() と同じです。

この関数は testmod() と同じ検索方法を使います。

バージョン 3.5 で変更: module がドキュメンテーション文字列を含まない場合には、 DocTestSuite() は ValueError を送出するのではなく空の unittest.TestSuite を返します。

exception doctest.failureException

When doctests which have been converted to unit tests by DocFileSuite() or DocTestSuite() fail, this exception is raised showing the name of the file containing the test and a (sometimes approximate) line number.

Under the covers, DocTestSuite() creates a unittest.TestSuite out of doctest.DocTestCase instances, and DocTestCase is a subclass of unittest.TestCase. DocTestCase isn't documented here (it's an internal detail), but studying its code can answer questions about the exact details of unittest integration.

Similarly, DocFileSuite() creates a unittest.TestSuite out of doctest.DocFileCase instances, and DocFileCase is a subclass of DocTestCase.

So both ways of creating a unittest.TestSuite run instances of DocTestCase. This is important for a subtle reason: when you run doctest functions yourself, you can control the doctest options in use directly, by passing option flags to doctest functions. However, if you're writing a unittest framework, unittest ultimately controls when and how tests get run. The framework author typically wants to control doctest reporting options (perhaps, e.g., specified by command line options), but there's no way to pass options through unittest to doctest test runners.

このため、 doctest では、以下の関数を使って、 unittest サポートに特化したレポートフラグ表記方法もサポートしています:

doctest.set_unittest_reportflags(flags)

doctest のレポートフラグをセットします。

引数 flags はオプションフラグの ビット単位論理和 を取ります。 オプションフラグ 節を参照してください。「レポートフラグ」しか使えません。

This is a module-global setting, and affects all future doctests run by module unittest: the runTest() method of DocTestCase looks at the option flags specified for the test case when the DocTestCase instance was constructed. If no reporting flags were specified (which is the typical and expected case), doctest's unittest reporting flags are bitwise ORed into the option flags, and the option flags so augmented are passed to the DocTestRunner instance created to run the doctest. If any reporting flags were specified when the DocTestCase instance was constructed, doctest's unittest reporting flags are ignored.

この関数は、関数を呼び出す前に有効になっていた unittest レポートフラグの値を返します。

拡張 API

基本 API は、doctest を使いやすくするための簡単なラッパであり、柔軟性があってほとんどのユーザの必要を満たしています; とはいえ、もっとテストをきめ細かに制御したい場合や、doctest の機能を拡張したい場合、拡張 API (advanced API) を使わなければなりません。

拡張 API は、doctest ケースから抽出した対話モードでの実行例を記憶するための二つのコンテナクラスを中心に構成されています:

Example: 1つの Python 文 と、その期待する出力をペアにしたもの。

DocTest: Example の集まり。通常一つの docstring やテキストファイルから抽出されます。

その他に、doctest の実行例を検索、構文解析、実行、チェックするための処理クラスが以下のように定義されています:

DocTestFinder: 与えられたモジュールからすべての docstring を検索し、 DocTestParser を使って対話モードでの実行例が入ったすべての docstring から DocTest を生成します。

DocTestParser: (オブジェクトの docstring 等の) 文字列から DocTest オブジェクトを生成します。

DocTestRunner: DocTest 内の実行例を実行し、 OutputChecker を使って出力を検証します。

OutputChecker: doctest 実行例から実際に出力された結果を期待する出力と比較し、両者が一致するか判別します。

これらの処理クラスの関係を図にまとめると、以下のようになります:

                            list of:
+------+                   +---------+
|module| --DocTestFinder-> | DocTest | --DocTestRunner-> results
+------+    |        ^     +---------+     |       ^    (printed)
            |        |     | Example |     |       |
            v        |     |   ...   |     v       |
           DocTestParser   | Example |   OutputChecker
                           +---------+

DocTest オブジェクト

class doctest.DocTest(examples, globs, name, filename, lineno, docstring)

単一の名前空間内で実行される doctest 実行例の集まりです。コンストラクタの引数は DocTest インスタンス中の同名の属性の初期化に使われます。

DocTest では、以下の属性を定義しています。これらの変数はコンストラクタで初期化されます。直接変更してはなりません。

examples

対話モードにおける実行例それぞれをエンコードしていて、テストで実行される、 Example オブジェクトからなるリストです。

globs

実行例を実行する名前空間 (いわゆるグローバル変数) です。このメンバは、名前から値への対応付けを行っている辞書です。実行例が名前空間に対して (新たな変数を束縛するなど) 何らかの変更を行った場合、 globs への反映はテストの実行後に起こります。

name

DocTest を識別する名前の文字列です。通常、この値はテストを取り出したオブジェクトかファイルの名前になります。

filename

DocTest を取り出したファイルの名前です; ファイル名が未知の場合や DocTest をファイルから取り出したのでない場合には None になります。

lineno

filename 中で DocTest のテスト実行例が始まっている行の行番号で、行番号が利用できなければ None です。行番号は、ファイルの先頭を 0 として数えます。

docstring

テストを取り出した docstring 自体を現す文字列です。docstring 文字列を得られない場合や、文字列からテスト実行例を取り出したのでない場合には None になります。

Example オブジェクト

class doctest.Example(source, want, exc_msg=None, lineno=0, indent=0, options=None)

ひとつの Python 文と、それに対する期待する出力からなる、単一の対話的モードの実行例です。コンストラクタの引数は Example インスタンス中の同名の属性の初期化に使われます。

Example では、以下の属性を定義しています。これらの変数はコンストラクタで初期化されます。直接変更してはなりません。

source

実行例のソースコードが入った文字列です。ソースコードは単一の Python で、末尾は常に改行です。コンストラクタは必要に応じて改行を追加します。

want

実行例のソースコードを実行した際の期待する出力 (標準出力と、例外が生じた場合にはトレースバック) です。 want の末尾は、期待する出力がまったくない場合を除いて常に改行になります。期待する出力がない場合には空文字列になります。コンストラクタは必要に応じて改行を追加します。

exc_msg

実行例が例外を生成すると期待される場合の例外メッセージです。例外を送出しない場合には None です。この例外メッセージは、 traceback.format_exception_only() の戻り値と比較されます。値が None でない限り、 exc_msg は改行で終わっていなければなりません; コンストラクタは必要に応じて改行を追加します。

lineno

この実行例を含む文字列における実行例が始まる行番号です。行番号は文字列の先頭を 0 として数えます。

indent

実行例の入っている文字列のインデント、すなわち実行例の最初のプロンプトより前にある空白文字の数です。

options

A dictionary mapping from option flags to True or 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 DocTestRunner's optionflags). By default, no options are set.

DocTestFinder オブジェクト

class doctest.DocTestFinder(verbose=False, parser=DocTestParser(), recurse=True, exclude_empty=True)

与えられたオブジェクトについて、そのオブジェクト自身の docstring か、そのオブジェクトに含まれるオブジェクトの docstring から DocTest を抽出する処理クラスです。モジュール、クラス、関数、メソッド、静的メソッド、クラスメソッド、プロパティから DocTest を抽出できます。

オプション引数 verbose を使うと、抽出処理の対象となるオブジェクトを表示できます。デフォルトは False (出力を行わない) です。

オプション引数 parser には、 docstring から DocTest を抽出するのに使う DocTestParser オブジェクト (またはその代替となるオブジェクト) を指定します。

オプション引数 recurse が偽の場合、 DocTestFinder.find() は与えられたオブジェクトだけを調べ、そのオブジェクトに含まれる他のオブジェクトを調べません。

オプション引数 exclude_empty が偽の場合、 DocTestFinder.find() は空の docstring を持つオブジェクトもテスト対象に含めます。

DocTestFinder では以下のメソッドを定義しています:

find(obj[, name][, module][, globs][, extraglobs])

obj または obj 内に入っているオブジェクトの docstring 中で定義されている DocTest のリストを返します。

オプション引数 name には、オブジェクトの名前を指定します。この名前は、関数が返す DocTest の名前になります。 name を指定しない場合、 obj.__name__ を使います。

オプションのパラメータ module は、指定したオブジェクトを収めているモジュールを指定します。 module を指定しないか、None を指定した場合には、正しいモジュールを自動的に決定しようと試みます。オブジェクトのモジュールは以下のような役割を果たします:

globs を指定していない場合、オブジェクトのモジュールはデフォルトの名前空間になります。

他のモジュールから import されたオブジェクトに対して DocTestFinder が DocTest を抽出するのを避けるために使います。 (module 由来でないオブジェクトを無視します。)

オブジェクトの入っているファイル名を調べるために使います。

オブジェクトがファイル内の何行目にあるかを調べる手助けにします。

module が False の場合には、モジュールの検索を試みません。これは正確さを欠くような使い方で、通常 doctest 自体のテストにしか使いません。module が False の場合、または module が None で自動的に的確なモジュールを見つけ出せない場合には、すべてのオブジェクトは (non-existent) モジュールに属するとみなされ、そのオブジェクト内のすべてのオブジェクトに対して (再帰的に) doctest の検索を行います。

各 DocTest のグローバル変数は、 globs と extraglobs を合わせたもの (extraglobs 内の束縛が globs 内の束縛を上書きする) になります。各々の DocTest に対して、グローバル変数を表す辞書の新たな浅いコピーを生成します。 globs を指定しない場合に使われるのデフォルト値は、モジュールを指定していればそのモジュールの __dict__ になり、指定していなければ {} になります。 extraglobs を指定しない場合、デフォルトの値は {} になります。

DocTestParser オブジェクト

class doctest.DocTestParser

対話モードの実行例を文字列から抽出し、それを使って DocTest オブジェクトを生成するために使われる処理クラスです。

DocTestParser では以下のメソッドを定義しています:

get_doctest(string, globs, name, filename, lineno)

指定した文字列からすべての doctest 実行例を抽出し、 DocTest オブジェクト内に集めます。

globs, name, filename, および lineno は新たに作成される DocTest オブジェクトの属性になります。詳しくは DocTest のドキュメントを参照してください。

get_examples(string, name='<string>')

指定した文字列からすべての doctest 実行例を抽出し、 Example オブジェクトからなるリストにして返します。各 Example の行番号は 0 から数えます。オプション引数 name はこの文字列につける名前で、エラーメッセージにしか使われません。

parse(string, name='<string>')

指定した文字列を、実行例とその間のテキストに分割し、実行例を Example オブジェクトに変換し、 Example と文字列からなるリストにして返します。各 Example の行番号は 0から数えます。オプション引数 name はこの文字列につける名前で、エラーメッセージにしか使われません。

DocTestRunner オブジェクト

class doctest.DocTestRunner(checker=None, verbose=None, optionflags=0)

DocTest 内の対話モード実行例を実行し、検証する際に用いられる処理クラスです。

期待する出力と実際の出力との比較は OutputChecker で行います。比較は様々なオプションフラグを使ってカスタマイズできます; 詳しくは オプションフラグ を参照してください。オプションフラグでは不十分な場合、コンストラクタに OutputChecker のサブクラスを渡して比較方法をカスタマイズできます。

The test runner's display output can be controlled in two ways. First, an output function can be passed to run(); this function will be called with strings that should be displayed. It defaults to 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 report_start(), report_success(), report_unexpected_exception(), and report_failure().

オプションのキーワード引数 checker には、 OutputChecker オブジェクト (またはその代替となるオブジェクト) を指定します。このオブジェクトは doctest 実行例の期待する出力と実際の出力との比較を行う際に使われます。

オプションのキーワード引数 verbose は、 DocTestRunner の出すメッセージの冗長性を制御します。 verbose が True の場合、各実行例を実行する都度、その実行例についての情報を出力します。 verbose が False の場合、テストの失敗だけを出力します。 verbose を指定しない場合や None を指定した場合、コマンドラインスイッチ -v を使った場合にのみ verbose 出力を適用します。

オプションのキーワード引数 optionflags を使うと、テストランナーが期待される出力と実際の出力を比較する方法や、テストの失敗を表示する方法を制御できます。詳しくは オプションフラグ 節を参照してください。

DocTestRunner defines the following methods:

report_start(out, test, example)

テストランナーが実行例を処理しようとしているときにレポートを出力します。 DocTestRunner の出力をサブクラスでカスタマイズできるようにするためのメソッドです。直接呼び出してはなりません。

example は処理する実行例です。 test は example の入っているテストです。 out は出力用の関数で、 DocTestRunner.run() に渡されます。

report_success(out, test, example, got)

与えられた実行例が正しく動作したことを報告します。このメソッドは DocTestRunner のサブクラスで出力をカスタマイズできるようにするために提供されています; 直接呼び出してはなりません。

example は処理する実行例です。 got は実行例から実際に得られた出力です。 test は example の入っているテストです。 out は出力用の関数で、 DocTestRunner.run() に渡されます。

report_failure(out, test, example, got)

与えられた実行例が正しく動作しなかったことを報告します。このメソッドは DocTestRunner のサブクラスで出力をカスタマイズできるようにするために提供されています; 直接呼び出してはなりません。

example は処理する実行例です。 got は実行例から実際に得られた出力です。 test は example の入っているテストです。 out は出力用の関数で、 DocTestRunner.run() に渡されます。

report_unexpected_exception(out, test, example, exc_info)

与えられた実行例が期待とは違う例外を送出したことを報告します。このメソッドは DocTestRunner のサブクラスで出力をカスタマイズできるようにするために提供されています; 直接呼び出してはなりません。

example は処理する実行例です。 exc_info には予期せず送出された例外の情報を入れたタプル (sys.exc_info() の返す内容) になります。 test は example の入っているテストです。 out は出力用の関数で、 DocTestRunner.run() に渡されます。

run(test, compileflags=None, out=None, clear_globs=True)

Run the examples in test (a DocTest object), and display the results using the writer function out.

実行例は名前空間 test.globs の下で実行されます。clear_globs が真 (デフォルト) の場合、名前空間はテストの実行後に消去され、ガベージコレクションを促します。テストの実行完了後にその内容を調べたければ、clear_globs=False としてください。

compileflags には、実行例を実行する際に Python コンパイラに適用するフラグセットを指定します。compileflags を指定しない場合、デフォルト値は globs で適用されている future-import フラグセットになります。

The output of each example is checked using the DocTestRunner's output checker, and the results are formatted by the DocTestRunner.report_*() methods.

summarize(verbose=None)

Print a summary of all the test cases that have been run by this DocTestRunner, and return a named tuple TestResults(failed, attempted).

オプションの verbose 引数を使うと、どのくらいサマリを詳しくするかを制御できます。冗長度を指定しない場合、 DocTestRunner 自体の冗長度を使います。

OutputChecker オブジェクト

class doctest.OutputChecker

doctest 実行例を実際に実行したときの出力が期待する出力と一致するかどうかをチェックするために使われるクラスです。 OutputChecker では、与えられた二つの出力を比較して、一致する場合には True を返す check_output() と、二つの出力間の違いを説明する文字列を返す output_difference() の、二つのメソッドがあります。

OutputChecker では以下のメソッドを定義しています:

check_output(want, got, optionflags)

実行例から実際に得られた出力 (got) と、期待する出力 (want) が一致する場合にのみ True を返します。二つの文字列がまったく同一の場合には常に一致するとみなしますが、テストランナーの使っているオプションフラグにより、厳密には同じ内容になっていなくても一致するとみなす場合もあります。オプションフラグについての詳しい情報は オプションフラグ 節を参照してください。

output_difference(example, got, optionflags)

与えられた実行例 (example) の期待する出力と、実際に得られた出力 (got) の間の差異を解説している文字列を返します。optionflags は want と got を比較する際に使われるオプションフラグのセットです。

デバッグ

doctest では、doctest 実行例をデバッグするメカニズムをいくつか提供しています:

doctest を実行可能な Python プログラムに変換し、 Python デバッガ pdb で実行できるようにするための関数がいくつかあります。

DocTestRunner のサブクラス DebugRunner クラスがあります。このクラスは、最初に失敗した実行例に対して例外を送出します。例外には実行例に関する情報が入っています。この情報は実行例の検死デバッグに利用できます。

DocTestSuite() の生成する unittest テストケースは、 debug() メソッドをサポートしています。 debug() は unittest.TestCase で定義されています。

pdb.set_trace() を doctest 実行例の中で呼び出しておけば、その行が実行されたときに Python デバッガが組み込まれます。デバッガを組み込んだあとは、変数の現在の値などを調べられます。たとえば、以下のようなモジュールレベルの docstring の入ったファイル a.py があるとします:

"""
>>> def f(x):
...     g(x*2)
>>> def g(x):
...     print(x+3)
...     import pdb; pdb.set_trace()
>>> f(3)
9
"""

対話セッションは以下のようになるでしょう:

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

以下は、doctest を Python コードに変換して、できたコードをデバッガ下で実行できるようにするための関数です:

doctest.script_from_examples(s)

実行例の入ったテキストをスクリプトに変換します。

引数 s は doctest 実行例の入った文字列です。この文字列は Python スクリプトに変換され、その中では s の doctest 実行例が通常のコードに、それ以外は Python のコメント文になります。生成したスクリプトを文字列で返します。例えば、

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
"""))

は:

# Set x and y to 1 and 2.
x, y = 1, 2
#
# Print their sum:
print(x+y)
# Expected:
## 3

この関数は内部的に他の関数から使われていますが (下記参照)、対話セッションを Python スクリプトに変換したいような場合にも便利でしょう。

doctest.testsource(module, name)

あるオブジェクトの doctest をスクリプトに変換します。

Argument module is a module object, or dotted name of a module, containing the object whose doctests are of interest. Argument name is the name (within the module) of the object with the doctests of interest. The result is a string, containing the object's docstring converted to a Python script, as described for script_from_examples() above. For example, if module a.py contains a top-level function f(), then

import a, doctest
print(doctest.testsource(a, "a.f"))

prints a script version of function f()'s docstring, with doctests converted to code, and the rest placed in comments.

doctest.debug(module, name, pm=False)

オブジェクトの持つ doctest をデバッグします。

module および name 引数は上の testsource() と同じです。指定したオブジェクトの docstring から合成された Python スクリプトは一時ファイルに書き出され、その後 Python デバッガ pdb の制御下で実行されます。

ローカルおよびグローバルの実行コンテキストには、module.__dict__ の浅いコピーが使われます。

オプション引数 pm は、検死デバッグを行うかどうかを指定します。 pm が真の場合、スクリプトファイルは直接実行され、スクリプトが送出した例外が処理されないまま終了した場合にのみデバッガが立ち入ります。その場合、 pdb.post_mortem() によって検死デバッグを起動し、処理されなかった例外から得られたトレースバックオブジェクトを渡します。 pm を指定しないか値を偽にした場合、 pdb.run() に適切な exec() 呼び出しを渡して、最初からデバッガの下でスクリプトを実行します。

doctest.debug_src(src, pm=False, globs=None)

文字列中の doctest をデバッグします。

上の debug() に似ていますが、doctest の入った文字列は src 引数で直接指定します。

オプション引数 pm は上の debug() と同じ意味です。

オプション引数 globs には、ローカルおよびグローバルな実行コンテキストの両方に使われる辞書を指定します。globs を指定しない場合や None にした場合、空の辞書を使います。辞書を指定した場合、実際の実行コンテキストには浅いコピーが使われます。

DebugRunner クラス自体や DebugRunner クラスが送出する特殊な例外は、テストフレームワークの作者にとって非常に興味のあるところですが、ここでは概要しか述べられません。詳しくはソースコード、とりわけ DebugRunner の docstring (それ自体 doctest です!) を参照してください:

class doctest.DebugRunner(checker=None, verbose=None, optionflags=0)

テストの失敗に遭遇するとすぐに例外を送出するようになっている DocTestRunner のサブクラスです。予期しない例外が生じると、 UnexpectedException 例外を送出します。この例外には、テスト、実行例、もともと送出された例外が入っています。期待する出力と実際の出力が一致しないために失敗した場合には、 DocTestFailure 例外を送出します。この例外には、テスト、実行例、実際の出力が入っています。

コンストラクタのパラメータやメソッドについては、 拡張 API 節の DocTestRunner のドキュメントを参照してください。

DebugRunner インスタンスの送出する例外には以下の二つがあります:

exception doctest.DocTestFailure(test, example, got)

doctest 実行例の実際の出力が期待する出力と一致しなかったことを示すために DocTestRunner が送出する例外です。コンストラクタの引数は、インスタンスの同名の属性を初期化するために使われます。

DocTestFailure では以下の属性を定義しています:

DocTestFailure.test

実行例が失敗した時に実行されていた DocTest オブジェクトです。

DocTestFailure.example

失敗した Example オブジェクトです。

DocTestFailure.got

実行例の実際の出力です。

exception doctest.UnexpectedException(test, example, exc_info)

doctest 実行例が予期しない例外を送出したことを示すために DocTestRunner が送出する例外です。コンストラクタの引数は、インスタンスの同名の属性を初期化するために使われます。

UnexpectedException では以下の属性を定義しています:

UnexpectedException.test

実行例が失敗した時に実行されていた DocTest オブジェクトです。

UnexpectedException.example

失敗した Example オブジェクトです。

UnexpectedException.exc_info

予期しない例外についての情報の入ったタプルで、 sys.exc_info() が返すのと同じものです。

アドバイス

冒頭でも触れたように、 doctest は、以下の三つの主な用途を持つようになりました:

docstring 内の実行例をチェックする。

回帰テストを行う。

実行可能なドキュメント/読めるテストの実現。

これらの用途にはそれぞれ違った要求があるので、区別して考えるのが重要です。特に、docstring を曖昧なテストケースに埋もれさせてしまうとドキュメントとしては最悪です。

docstring の例は注意深く作成してください。 doctest の作成にはコツがあり、きちんと学ぶ必要があります --- 最初はすんなりできないでしょう。実行例はドキュメントに本物の価値を与えます。良い例は、たくさんの言葉と同じ価値を持つことがしばしばあります。注意深くやれば、例はユーザにとっては非常に有益であり、時を経るにつれて、あるいは状況が変わった際に、何度も修正するのにかかる時間を節約するという形で、きっと見返りを得るでしょう。私は今でも、自分の doctest 実行例が "無害な" 変更を行った際にうまく動作しなくなることに驚いています。

説明テキストの作成をけちらなければ、doctest は回帰テストの優れたツールにもなり得ます。説明文と実行例を交互に記述していけば、実際に何をどうしてテストしているのかもっと簡単に把握できるようになるでしょう。もちろん、コードベースのテストに詳しくコメントを入れるのも手ですが、そんなことをするプログラマはほとんどいません。多くの人々が、doctest のアプローチをとった方がきれいにテストを書けると気づいています。おそらく、これは単にコード中にコメントを書くのが少し面倒だからという理由でしょう。私はもう少し穿った見方もしています。doctest ベースのテストを書くときの自然な態度は、自分のソフトウェアのよい点を説明しようとして、実行例を使って説明しようとするときの態度そのものだからだ、という理由です。それゆえに、テストファイルは自然と単純な機能の解説から始め、論理的により複雑で境界条件的なケースに進むような形になります。結果的に、一見ランダムに見えるような個別の機能をテストしている個別の関数の集まりではなく、首尾一貫した説明ができるようになるのです。doctest によるテストの作成はまったく別の取り組み方であり、テストと説明の区別をなくして、まったく違う結果を生み出すのです。

回帰テストは特定のオブジェクトやファイルにまとめておくのがよいでしょう。回帰テストの組み方にはいくつか選択肢があります:

テストケースを対話モードの実行例にして入れたテキストファイルを書き、 testfile() や DocFileSuite() を使ってそのファイルをテストします。この方法をお勧めします。最初から doctest を使うようにしている新たなプロジェクトでは、この方法が一番簡単です。

_regrtest_topic という名前の関数を定義します。この関数には、あるトピックに対応するテストケースの入った docstring が一つだけ入っています。この関数はモジュールと同じファイルの中にも置けますし、別のテストファイルに分けてもかまいません。

回帰テストのトピックをテストケースの入った docstring に対応付けた辞書 __test__ 辞書を定義します。

テストコードをモジュールに組み込むことで、そのモジュールは、モジュール自身がテストランナーになることができます。テストが失敗した場合には、問題箇所をデバッグする際に、失敗したdoctestだけを再度実行することで、作成したテストランナーを修正することができます。これがこのようなテストランナーの最小例となります。

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("{} failures out of {} tests".format(fail, total))

脚注

[1]

期待する出力結果と例外の両方を含んだ例はサポートされていません。一方の終わりと他方の始まりを見分けようとするのはエラーの元になりがちですし、解りにくいテストになってしまいます。

unittest --- Unit testing framework

ソースコード: Lib/unittest/__init__.py [https://github.com/python/cpython/tree/3.12/Lib/unittest/__init__.py]

(すでにテストの基本概念について詳しいようでしたら、この部分をとばして アサートメソッド一覧 に進むと良いでしょう。)

unittest ユニットテストフレームワークは元々 JUnit に触発されたもので、他の言語の主要なユニットテストフレームワークと同じような感じです。テストの自動化、テスト用のセットアップやシャットダウンのコードの共有、テストのコレクション化、そして報告フレームワークからのテストの独立性をサポートしています。

これを実現するために、 unittest はいくつかの重要な概念をオブジェクト指向の方法でサポートしています:

テストフィクスチャ (test fixture)

テストフィクスチャ (test fixture) とは、テスト実行のために必要な準備や終了処理を指します。例: テスト用データベースの作成・ディレクトリ・サーバプロセスの起動など。

テストケース (test case)

テストケース (test case) はテストの独立した単位で、各入力に対する結果をチェックします。テストケースを作成する場合は、 unittest が提供する TestCase クラスを基底クラスとして利用することができます。

テストスイート (test suite)

テストスイート (test suite) はテストケースとテストスイートの集まりで、同時に実行しなければならないテストをまとめる場合に使用します。

テストランナー (test runner)

テストランナー (test runner) はテストの実行を管理し結果を提供する要素です。ランナーはグラフィカルインターフェースやテキストインターフェースを使用しても構いませんし、テストの実行結果を示す特別な値を返しても構いません。

参考

doctest モジュール

テストをサポートするもうひとつのモジュールで、このモジュールとは趣きがだいぶ異なります。

Simple Smalltalk Testing: With Patterns [https://web.archive.org/web/20150315073817/http://www.xprogramming.com/testfram.htm]

Kent Beck のテスティングフレームワークに関する原論文で、ここに記載されたパターンを unittest が使用しています。

pytest [https://docs.pytest.org/]

サードパーティのユニットテストフレームワークでより軽量な構文でテストを書くことができます。例えば、assert func(10) == 42 のように書きます。

The Python Testing Tools Taxonomy [https://wiki.python.org/moin/PythonTestingToolsTaxonomy]

多くの Python のテストツールが一覧で紹介されています。ファンクショナルテストのフレームワークやモックライブラリも掲載されています。

Testing in Python メーリングリスト [http://lists.idyll.org/listinfo/testing-in-python]

Python でテストやテストツールについての議論に特化したグループです。

Python のソースコード配布物にあるスクリプト Tools/unittestgui/unittestgui.py はテストディスカバリとテスト実行のための GUI ツールです。主な目的は単体テストの初心者が簡単に使えるようにすることです。実際の生産環境では、 Buildbot [https://buildbot.net/], Jenkins [https://www.jenkins.io/] 、 GitHub Actions [https://github.com/features/actions], AppVeyor [https://www.appveyor.com/] のような継続的インテグレーションシステムでテストを実行することを推奨します。

基本的な例

unittest モジュールには、テストの開発や実行の為の優れたツールが用意されており、この節では、その一部を紹介します。ほとんどのユーザとっては、ここで紹介するツールだけで十分でしょう。

以下は、三つの文字列メソッドをテストするスクリプトです:

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()

テストケースは、 unittest.TestCase のサブクラスとして作成します。メソッド名が test で始まる三つのメソッドがテストです。テストランナーはこの命名規約によってテストを行うメソッドを検索します。

これらのテスト内では、予定の結果が得られていることを確かめるために assertEqual() を、条件のチェックに assertTrue() や assertFalse() を、例外が発生する事を確認するために assertRaises() をそれぞれ呼び出しています。 assert 文の代わりにこれらのメソッドを使用すると、テストランナーでテスト結果を集計してレポートを作成する事ができます。

setUp() および tearDown() メソッドによって各テストメソッドの前後に実行する命令を実装することが出来ます。詳細は テストコードの構成 を参照してください。

最後のブロックは簡単なテストの実行方法を示しています。 unittest.main() は、テストスクリプトのコマンドライン用インターフェースを提供します。コマンドラインから起動された場合、上記のスクリプトは以下のような結果を出力します:

...
----------------------------------------------------------------------
Ran 3 tests in 0.000s

OK

-v オプションをテストスクリプトに渡すことで unittest.main() はより冗長になり、以下のような出力をします:

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

上の例が unittest モジュールで最もよく使われる機能で、ほとんどのテストではこれで十分です。以下では全ての機能を一から解説しています。

バージョン 3.11 で変更: テストメソッドが（デフォルトの``None``以外の）戻り値を返す挙動は現在非推奨です。

コマンドラインインターフェイス

ユニットテストモジュールはコマンドラインから使って、モジュール、クラス、あるいは個別のテストメソッドで定義されたテストを実行することが出来ます:

python -m unittest test_module1 test_module2
python -m unittest test_module.TestClass
python -m unittest test_module.TestClass.test_method

モジュール名ならびに完全修飾されたクラス名やメソッド名の任意の組み合わせを一覧で渡すことが出来ます。

テストモジュールはファイルパスで指定することも出来ます:

python -m unittest tests/test_something.py

そのため、テストモジュールを指定するのにシェルのファイル名補完が使えます。指定されたファイルはやはりモジュールとしてインポート可能でなければなりません。パスから '.py' を取り除き、パスセパレータを '.' に置き換えることでモジュール名に変換されます。モジュールとしてインポート可能でないテストファイルを実行したい場合は、代わりにそのファイルを直接実行するのが良いでしょう。

テスト実行時に (より冗長な) 詳細を表示するには -v フラグを渡します:

python -m unittest -v test_module

引数無しで実行すると テストディスカバリ が開始されます:

python -m unittest

コマンドラインプションの一覧を表示するには以下のコマンドを実行します:

python -m unittest -h

バージョン 3.2 で変更: 以前のバージョンでは、個々のテストメソッドしか実行することができず、モジュール単位やクラス単位で実行することは不可能でした。

コマンドラインオプション

unittest には以下のコマンドラインオプションがあります:

-b, --buffer

標準出力と標準エラーのストリームをテストの実行中にバッファします。テストが成功している間は結果の出力は破棄されます。テストの失敗やエラーの場合、出力は通常通り表示され、エラーメッセージに追加されます。

-c, --catch

Control-C を実行中のテストが終了するまで遅延させ、そこまでの結果を出力します。二回目の Control-C は、通常通り KeyboardInterrupt の例外を発生させます。

この機能の仕組みについては、シグナルハンドリング を参照してください。

-f, --failfast

初回のエラーもしくは失敗の時にテストを停止します。

-k

パターンや部分文字列にマッチするテストメソッドとテストクラスのみ実行します。このオプションは複数回使うことができ、その場合はすべてのパターンにマッチするテストケースが実行対象に含まれます。

ワイルドカード(*) を含むパターンは fnmatch.fnmatchcase() を使用してテスト名と照合され、それ以外の場合は単純な大文字と小文字を区別した部分文字列マッチングが使用されます。

パターンは、テストローダがインポートする時の完全修飾されたテストメソッド名と照合されます。

たとえば、 -k foo は foo_tests.SomeTest.test_something, bar_tests.SomeTest.test_foo にマッチし、 bar_tests.FooTest.test_something はマッチしません。

--locals

トレースバック内の局所変数を表示します。

--durations N

Show the N slowest test cases (N=0 for all).

Added in version 3.2: コマンドラインオプションの -b、-c、-f が追加されました。

Added in version 3.5: コマンドラインオプション --locals。

Added in version 3.7: コマンドラインオプション -k。

Added in version 3.12: The command-line option --durations.

コマンドラインによってテストディスカバリ、すなわちプロジェクトの全テストを実行したりサブセットのみを実行したりすることも出来ます。

テストディスカバリ

Added in version 3.2.

unittest はシンプルなテストディスカバリをサポートします。このテストディスカバリに対応するために、テストが定義された全ファイルは modules もしくは packages としてプロジェクトの最上位のディスカバリでインポート可能である必要があります (つまり、これらのファイルは identifiers として有効である必要があるということです)。

テストディスカバリは TestLoader.discover() で実装されていますが、コマンドラインから使う事も出来ます。その基本的な使い方は:

cd project_directory
python -m unittest discover

注釈

python -m unittest は python -m unittest discover と等価なショートカットです。テストディスカバリに引数を渡したい場合は、discover サブコマンドを明示的に使用しなければなりません。

discover サブコマンドには以下のオプションがあります:

-v, --verbose

詳細な出力

-s, --start-directory directory

ディスカバリを開始するディレクトリ (デフォルトは .)

-p, --pattern pattern

テストファイル名を識別するパターン (デフォルトは test*.py)

-t, --top-level-directory directory

プロジェクトの最上位のディスカバリのディレクトリ (デフォルトは開始のディレクトリ)

-s 、 -p 、および -t オプションは、この順番であれば位置引数として渡す事ができます。以下の二つのコマンドは等価です:

python -m unittest discover -s project_directory -p "*_test.py"
python -m unittest discover project_directory "*_test.py"

パスと同様にパッケージ名を、例えば myproject.subpackage.test のように、開始ディレクトリとして渡すことができます。指定したパッケージ名はインポートされ、そのファイルシステム上の場所が開始ディレクトリとして使われます。

注意

テストディスカバリはインポートによりテストを読み込みます。一旦テストディスカバリが指定された開始ディレクトリから全テストファイルを見付けると、パスはインポートするパッケージ名に変換されます。例えば、 foo/bar/baz.py は foo.bar.baz としてインポートされます。

グローバルにインストールされたパッケージがあり、それとは異なるコピーでディスカバリしようとしたとき、誤った場所からインポートが行われる かもしれません。その場合テストディスカバリは警告し、停止します。

ディレクトリのパスではなくパッケージ名を開始ディレクトリに指定した場合、ディスカバリはインポートするいずれの場所も意図した場所とするため、警告を受けないはずです。

テストモジュールとパッケージは、 load_tests プロトコル によってテストのロードとディスカバリをカスタマイズすることができます。

バージョン 3.4 で変更: テストディスカバリは開始ディレクトリとして 名前空間パッケージ をサポートします。トップレベルのディレクトリも指定する必要があることに注意してください(例えば python -m unittest discover -s root/namespace -t root)。

バージョン 3.11 で変更: unittest dropped the namespace packages support in Python 3.11. It has been broken since Python 3.7. Start directory and subdirectories containing tests must be regular package that have __init__.py file.

Directories containing start directory still can be a namespace package. In this case, you need to specify start directory as dotted package name, and target directory explicitly. For example:

# proj/  <-- current directory
#   namespace/
#     mypkg/
#       __init__.py
#       test_mypkg.py

python -m unittest discover -s namespace.mypkg -t .

テストコードの構成

ユニットテストの基本的な構成要素は、 テストケース --- 設定され正しさのためにチェックされるべき単独のシナリオ --- です。 unittest では、テストケースは unittest.TestCase クラスのインスタンスで表現されます。独自のテストケースを作成するには TestCase のサブクラスを記述するか、 FunctionTestCase を使用しなければなりません。

TestCase インスタンスのテストコードは完全に独立していなければなりません。すなわち単独でか、他の様々なテストケースの任意の組み合わせのいずれかで実行可能でなければなりません。

最も単純な TestCase のサブクラスは、特定のテストコードを実行するためのテストメソッド (すなわち名前が test で始まるメソッド) を実装するだけで簡単に書くことができます:

import unittest

class DefaultWidgetSizeTestCase(unittest.TestCase):
    def test_default_widget_size(self):
        widget = Widget('The widget')
        self.assertEqual(widget.size(), (50, 50))

Note that in order to test something, we use one of the assert* methods provided by the TestCase base class. If the test fails, an exception will be raised with an explanatory message, and unittest will identify the test case as a failure. Any other exceptions will be treated as errors.

テストは多くなり、それらの設定は繰り返しになるかもしれません。幸いにも、setUp() メソッドを実装することで設定コードをくくり出すことができます。テストフレームワークは実行するテストごとに自動的に setUp() を呼びます:

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')

注釈

いろいろなテストが実行される順序は、文字列の組み込みの順序でテストメソッド名をソートすることで決まります。

テスト中に setUp() メソッドで例外が発生した場合、フレームワークはそのテストに問題があるとみなし、そのテストメソッドは実行されません。

同様に、テストメソッド実行後に片付けをする tearDown() メソッドを提供出来ます:

import unittest

class WidgetTestCase(unittest.TestCase):
    def setUp(self):
        self.widget = Widget('The widget')

    def tearDown(self):
        self.widget.dispose()

setUp() が成功した場合、テストメソッドが成功したかどうかに関わらず tearDown() が実行されます。

そのようなテストコードのための作業環境は テストフィクスチャ (test fixture) と呼ばれます。新しい TestCase インスタンスはある単一のテストフィクスチャとして作成され、個々のテストメソッドを実行するのに使われます。従って、 setUp(), tearDown(), __init__() は1回のテストにつき1回だけ呼び出されます。

テストケースの実装では、テストする機能に従ってテストをまとめるのをお勧めします。 unittest はこのための機構、unittest の TestSuite クラスで表現される test suite、を提供します。たいていの場合 unittest.main() を呼び出しは正しい処理を行い、モジュールの全テストケースを集めて実行します。

しかし、テストスイートの構築をカスタマイズしたい場合、自分ですることができます:

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())

テストケースやテストコードの定義を (widget.py のような) テスト対象コードと同じモジュールに置くことが出来ますが、テストコードを (test_widget.py のような) 独立したモジュールに置くのには以下のような利点があります:

テストモジュールだけをコマンドラインから独立に実行することができる。

テストコードと出荷するコードをより簡単に分ける事ができる。

余程のことがない限り、テスト対象のコードに合わせてテストコードを変更することになりにくい。

テストコードは、テスト対象コードほど頻繁に変更されない。

テストコードをより簡単にリファクタリングすることができる。

Cで書いたモジュールのテストはどうせ独立したモジュールなのだから、同様にしない理由がない

テストの方策を変更した場合でも、ソースコードを変更する必要がない。

既存テストコードの再利用

既存のテストコードが有るとき、このテストを unittest で実行しようとするために古いテスト関数をいちいち TestCase クラスのサブクラスに変換するのは大変です。

このような場合は、 unittest では TestCase のサブクラスである FunctionTestCase クラスを使い、既存のテスト関数をラップします。初期設定と終了処理も行なえます。

以下のテストコードがあった場合:

def testSomething():
    something = makeSomething()
    assert something.name is not None
    # ...

オプションの set-up と tear-down メソッドを持った同等のテストケースインスタンスは次のように作成します:

testcase = unittest.FunctionTestCase(testSomething,
                                     setUp=makeSomethingDB,
                                     tearDown=deleteSomethingDB)

注釈

FunctionTestCase を使って既存のテストを unittest ベースのテスト体系に変換することができますが、この方法は推奨されません。時間を掛けて TestCase のサブクラスに書き直した方が将来的なテストのリファクタリングが限りなく易しくなります。

既存のテストが doctest を使って書かれている場合もあるでしょう。その場合、 doctest は DocTestSuite クラスを提供します。このクラスは、既存の doctestベースのテストから、自動的に unittest.TestSuite のインスタンスを作成します。

テストのスキップと予期された失敗

Added in version 3.1.

unittest は特定のテストメソッドやテストクラス全体をスキップする仕組みを備えています。さらに、この機能はテスト結果を「予期された失敗 (expected failure)」とすることができ、テストが失敗しても TestResult の失敗数にはカウントされなくなります。

テストをスキップするには、 skip() デコレータ かその条件付きバージョンの一つを使うか、setUp() やテストメソッドの中で TestCase.skipTest() を呼び出すか、あるいは直接 SkipTest を送出するだけです。

基本的なスキップは以下のようになります:

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

このサンプルを冗長モードで実行すると以下のように出力されます:

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)

テストクラスは以下のようにメソッドをスキップすることができます:

@unittest.skip("showing class skipping")
class MySkippedTestCase(unittest.TestCase):
    def test_not_run(self):
        pass

TestCase.setUp() もスキップすることができます。この機能はセットアップの対象のリソースが使用不可能な時に便利です。

予期された失敗の機能を使用するには expectedFailure() デコレータを使います。

class ExpectedFailureTestCase(unittest.TestCase):
    @unittest.expectedFailure
    def test_fail(self):
        self.assertEqual(1, 0, "broken")

独自のスキップ用のデコレータの作成は簡単です。 そのためには、独自のデコレータのスキップしたい時点で skip() を呼び出します。 以下のデコレータはオブジェクトに指定した属性が無い場合にテストをスキップします:

def skipUnlessHasattr(obj, attr):
    if hasattr(obj, attr):
        return lambda func: func
    return unittest.skip("{!r} doesn't have {!r}".format(obj, attr))

以下のデコレータと例外はテストのスキップと予期された失敗を実装しています:

@unittest.skip(reason)

デコレートしたテストを無条件でスキップします。reason にはテストをスキップした理由を記載します。

@unittest.skipIf(condition, reason)

condition が真の場合、デコレートしたテストをスキップします。

@unittest.skipUnless(condition, reason)

condition が偽の場合、デコレートしたテストをスキップします。

@unittest.expectedFailure

失敗またはエラーが予測されるものとしてテストをマークします。テストが失敗するか (test fixture メソッドのいずれかではなく、) テスト関数そのものでエラーとなった場合に成功したとみなされます。テストが成功した場合は失敗とみなされます。

exception unittest.SkipTest(reason)

この例外はテストをスキップするために送出されます。

ふつうはこれを直接送出する代わりに TestCase.skipTest() やスキッピングデコレータの一つを使用出来ます。

スキップしたテストの前後では、 setUp() および tearDown() は実行されません。同様に、スキップしたクラスの前後では、 setUpClass() および tearDownClass() は実行されません。スキップしたモジュールの前後では、 setUpModule() および tearDownModule() は実行されません。

サブテストを利用して繰り返しテストの区別を付ける

Added in version 3.4.

テストの間にとても小さな差異がある場合（例えばいくつかのパラメータなど）、unittestでは subTest() コンテキストマネージャを使用してテストメソッドの内部でそれらを区別することができます。

例えば以下のテストは:

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)

以下の出力をします:

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

サブテスト無しの場合、最初の失敗で実行は停止し、i の値が表示されないためエラーの原因を突き止めるのは困難になります:

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

クラスと関数

この節では、 unittest モジュールのAPIの詳細について説明します。

テストクラス

class unittest.TestCase(methodName='runTest')

TestCase クラスのインスタンスは、 unittest の世界における論理的なテストの単位を示します。このクラスをベースクラスとして使用し、必要なテストを具象サブクラスに実装します。 TestCase クラスでは、テストランナーがテストを実行するため のインターフェースと、各種の失敗をチェックしレポートするためのメソッドを実装しています。

TestCase の各インスタンスは methodName という名前の単一の基底メソッドを実行します。 TestCase を使用する大半の場合 methodName を変更したりデフォルトの runTest() メソッドを再実装することはありません。

バージョン 3.2 で変更: TestCase が methodName を指定しなくてもインスタンス化できるようになりました。これにより対話的インタプリタから TestCase を簡単に試せるようになりました。

TestCase のインスタンスのメソッドは3種類のグループを提供します。 1つ目のグループはテストの実行で使用されます。 2つ目のグループは条件のチェックおよび失敗のレポートを行うテストの実装で使用されます。 3つ目のグループである問い合わせ用のメソッドによってテスト自身の情報が収集されます。

はじめのグループ (テスト実行) に含まれるメソッドは以下の通りです:

setUp()

テストフィクスチャの準備のために呼び出されるメソッドです。テストメソッドの直前に呼び出されます。このメソッドで AssertionError や SkipTest 以外の例外が発生した場合、テストの失敗ではなくエラーとされます。デフォルトの実装では何も行いません。

tearDown()

テストメソッドが実行され、結果が記録された直後に呼び出されるメソッドです。このメソッドはテストメソッドで例外が投げられても呼び出されます。そのため、サブクラスでこのメソッドを実装する場合は、内部状態を確認することが必要になるでしょう。このメソッドで AssertionError や SkipTest 以外の例外が発生した場合、テストの失敗とは別のエラーとみなされます (従って報告されるエラーの総数は増えます)。このメソッドは、テストの結果に関わらず setUp() が成功した場合にのみ呼ばれます。デフォルトの実装では何も行いません。

setUpClass()

個別のクラス内のテストが実行される前に呼び出されるクラスメソッドです。 setUpClass はクラスを唯一の引数として取り、 classmethod() でデコレートされていなければなりません:

@classmethod
def setUpClass(cls):
    ...

詳しくは クラスとモジュールのフィクスチャ を参照してください。

Added in version 3.2.

tearDownClass()

個別のクラス内のテストが実行された後に呼び出されるクラスメソッドです。 tearDownClass はクラスを唯一の引数として取り、 classmethod() でデコレートされていなければなりません:

@classmethod
def tearDownClass(cls):
    ...

詳しくは クラスとモジュールのフィクスチャ を参照してください。

Added in version 3.2.

run(result=None)

テストを実行し、テスト結果を result に指定された TestResult オブジェクトにまとめます。 result が省略されるか None が渡された場合、 (defaultTestResult() メソッドを呼んで) 一時的な結果オブジェクトを生成し、使用します。 結果オブジェクトは run() の呼び出し元に返されます。

このメソッドは、単に TestCase インスタンスを呼び出した場合と同様に振る舞います。

バージョン 3.3 で変更: 以前のバージョンの run は結果オブジェクトを返しませんでした。また TestCase インスタンスを呼び出した場合も同様でした。

skipTest(reason)

テストメソッドや setUp() が現在のテストをスキップする間に呼ばれます。詳細については、 テストのスキップと予期された失敗 を参照してください。

Added in version 3.1.

subTest(msg=None, **params)

このメソッドを囲っているブロックをサブテストとして実行するコンテキストマネージャを返します。 msg と params はサブテストが失敗したときに表示されるオプションの任意の値で、どんな値が使われたかを明確にするものです。

テストケースには subtest 宣言を幾らでも含めることができ、任意にネストすることができます。

詳細は サブテストを利用して繰り返しテストの区別を付ける を参照してください。

Added in version 3.4.

debug()

テスト結果を収集せずにテストを実行します。例外が呼び出し元に通知されます。また、テストをデバッガで実行することができます。

TestCase クラスは失敗の検査と報告を行う多くのメソッドを提供しています。以下の表は最も一般的に使われるメソッドを列挙しています (より多くのアサートメソッドについては表の下を見てください):

メソッド

確認事項

初出

assertEqual(a, b)

a == b

assertNotEqual(a, b)

a != b

assertTrue(x)

bool(x) is True

assertFalse(x)

bool(x) is False

assertIs(a, b)

a is b

3.1

assertIsNot(a, b)

a is not b

3.1

assertIsNone(x)

x is None

3.1

assertIsNotNone(x)

x is not None

3.1

assertIn(a, b)

a in b

3.1

assertNotIn(a, b)

a not in b

3.1

assertIsInstance(a, b)

isinstance(a, b)

3.2

assertNotIsInstance(a, b)

not isinstance(a, b)

3.2

全てのアサートメソッドは msg 引数を受け取り、指定された場合、失敗時のエラーメッセージとして使われます。 (longMessage も参照してください)。 msg キーワード引数は assertRaises() 、 assertRaisesRegex() 、 assertWarns() 、 assertWarnsRegex() には、そのメソッドをコンテキストマネージャとして使った場合にのみ使えます。

assertEqual(first, second, msg=None)

first と second が等しいことをテストします。両者が等しくない場合、テストは失敗です。

さらに、 first と second が厳密に同じ型であり、list、tuple、dict、set、frozenset もしくは str のいずれか、またはサブクラスが addTypeEqualityFunc() に登録されている任意の型の場合、より有用なデフォルトのエラーメッセージを生成するために、その型特有の比較関数が呼ばれます（型固有のメソッドの一覧 も参照してください）。

バージョン 3.1 で変更: 自動で型固有の比較関数が呼ばれるようになりました。

バージョン 3.2 で変更: 文字列比較のデフォルトの比較関数として assertMultiLineEqual() が追加されました。

assertNotEqual(first, second, msg=None)

first と second が等しくないことをテストします。両者が等しい場合、テストは失敗です。

assertTrue(expr, msg=None)

assertFalse(expr, msg=None)

expr が真 (偽) であることをテストします。

このメソッドは、bool(expr) is True と等価であり、expr is True と等価ではないことに注意が必要です (後者のためには、assertIs(expr, True) が用意されています)。また、専用のメソッドが使用できる場合には、そちらを使用してください (例えば assertTrue(a == b) の代わりに assertEqual(a, b) を使用してください)。そうすることにより、テスト失敗時のエラーメッセージを詳細に表示することができます。

assertIs(first, second, msg=None)

assertIsNot(first, second, msg=None)

first と second が同じオブジェクトであること (またはそうでないこと) をテストします。

Added in version 3.1.

assertIsNone(expr, msg=None)

assertIsNotNone(expr, msg=None)

expr が None であること (および、そうでないこと) をテストします。

Added in version 3.1.

assertIn(member, container, msg=None)

assertNotIn(member, container, msg=None)

member が container に含まれること (またはそうでないこと) をテストします。

Added in version 3.1.

assertIsInstance(obj, cls, msg=None)

assertNotIsInstance(obj, cls, msg=None)

obj が cls のインスタンスであること (あるいはそうでないこと) をテストします (この cls は、 isinstance() が扱うことのできる、クラスもしくはクラスのタプルである必要があります)。正確な型をチェックするためには、 assertIs(type(obj), cls) を使用してください。

Added in version 3.2.

以下のメソッドを使用して例外、警告、およびログメッセージの発生を確認することが出来ます:

メソッド

確認事項

初出

assertRaises(exc, fun, *args, **kwds)

fun(*args, **kwds) が exc を送出する

assertRaisesRegex(exc, r, fun, *args, **kwds)

fun(*args, **kwds) が exc を送出してメッセージが正規表現 r とマッチする

3.1

assertWarns(warn, fun, *args, **kwds)

fun(*args, **kwds) が warn を送出する

3.2

assertWarnsRegex(warn, r, fun, *args, **kwds)

fun(*args, **kwds) が warn を送出してメッセージが正規表現 r とマッチする

3.2

assertLogs(logger, level)

with ブロックが 最低 level で logger を使用する

3.4

assertNoLogs(logger, level)

The with block does not log on

logger with minimum level

3.10

assertRaises(exception, callable, *args, **kwds)

assertRaises(exception, *, msg=None)

callable を呼び出した時に例外が発生することをテストします。 assertRaises() で指定した位置パラメータとキーワードパラメータを該当メソッドに渡します。 exception が送出された場合、テストは成功です。また、他の例外が投げられた場合はエラー、例外が送出されなかった場合は失敗になります。複数の例外をキャッチする場合には、例外クラスのタプルを exception に指定してください。

exception 引数のみ（またはそれに加えて msg 引数）が渡された場合には、コンテキストマネージャが返されます。これにより関数名を渡す形式ではなく、インラインでテスト対象のコードを書くことができます:

with self.assertRaises(SomeException):
    do_something()

コンテキストマネージャとして使われたときは、 assertRaises() は加えて msg キーワード引数も受け付けます。

このコンテキストマネージャは exception で指定されたオブジェクトを格納します。これにより、例外発生時の詳細な確認をおこなうことができます:

with self.assertRaises(SomeException) as cm:
    do_something()

the_exception = cm.exception
self.assertEqual(the_exception.error_code, 3)

バージョン 3.1 で変更: assertRaises() がコンテキストマネージャとして使えるようになりました。

バージョン 3.2 で変更: exception 属性が追加されました。

バージョン 3.3 で変更: コンテキストマネージャとして使用したときに msg キーワード引数が追加されました。

assertRaisesRegex(exception, regex, callable, *args, **kwds)

assertRaisesRegex(exception, regex, *, msg=None)

assertRaises() と同等ですが、例外の文字列表現が regex にマッチすることもテストします。 regex は正規表現オブジェクトか、 re.search() が扱える正規表現が書かれた文字列である必要があります。例えば以下のようになります:

self.assertRaisesRegex(ValueError, "invalid literal for.*XYZ'$",
                       int, 'XYZ')

もしくは:

with self.assertRaisesRegex(ValueError, 'literal'):
   int('XYZ')

Added in version 3.1: assertRaisesRegexp という名前で追加されました。

バージョン 3.2 で変更: assertRaisesRegex() にリネームされました。

バージョン 3.3 で変更: コンテキストマネージャとして使用したときに msg キーワード引数が追加されました。

assertWarns(warning, callable, *args, **kwds)

assertWarns(warning, *, msg=None)

callable を呼び出した時に警告が発生することをテストします。 assertWarns() で指定した位置パラメータとキーワードパラメータを該当メソッドに渡します。 warning が発生した場合にテストが成功し、そうでなければ失敗になります。例外が送出された場合はエラーになります。複数の警告を捕捉する場合には、警告クラスのタプルを warnings に指定してください。

warning 引数のみ（またはそれに加えて msg 引数）が渡された場合には、コンテキストマネージャが返されます。これにより関数名を渡す形式ではなく、インラインでテスト対象のコードを書くことができます:

with self.assertWarns(SomeWarning):
    do_something()

コンテキストマネージャとして使われたときは、 assertWarns() は加えて msg キーワード引数も受け付けます。

このコンテキストマネージャは、捕捉した警告オブジェクトを warning 属性に、警告が発生したソース行を filename 属性と lineno 属性に格納します。これは警告発生時に捕捉された警告に対して追加の確認を行いたい場合に便利です:

with self.assertWarns(SomeWarning) as cm:
    do_something()

self.assertIn('myfile.py', cm.filename)
self.assertEqual(320, cm.lineno)

このメソッドは呼び出されたときに警告フィルタを無視して動作します。

Added in version 3.2.

バージョン 3.3 で変更: コンテキストマネージャとして使用したときに msg キーワード引数が追加されました。

assertWarnsRegex(warning, regex, callable, *args, **kwds)

assertWarnsRegex(warning, regex, *, msg=None)

assertWarns() と同等ですが、警告メッセージが regex にマッチすることもテストします。 regex は正規表現オブジェクトか、 re.search() が扱える正規表現が書かれた文字列である必要があります。例えば以下のようになります:

self.assertWarnsRegex(DeprecationWarning,
                      r'legacy_function\(\) is deprecated',
                      legacy_function, 'XYZ')

もしくは:

with self.assertWarnsRegex(RuntimeWarning, 'unsafe frobnicating'):
    frobnicate('/etc/passwd')

Added in version 3.2.

バージョン 3.3 で変更: コンテキストマネージャとして使用したときに msg キーワード引数が追加されました。

assertLogs(logger=None, level=None)

logger かその子ロガーのうちの1つに、少なくとも1つのログメッセージが少なくとも与えられた level で出力されることをテストするコンテキストマネージャです。

If given, logger should be a logging.Logger object or a 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 "ERROR" or logging.ERROR). The default is logging.INFO.

with ブロック内で出たメッセージの少なくとも一つが logger および level 条件に合っている場合、このテストをパスします。それ以外の場合は失敗です。

コンテキストマネージャから返されるオブジェクトは、条件に該当するログメッセージを追跡し続ける記録のためのヘルパーです。このオブジェクトには2つの属性があります:

records

該当するログメッセージを表す logging.LogRecord オブジェクトのリスト。

output

該当するメッセージ出力をフォーマットした str オブジェクトのリスト。

以下はプログラム例です:

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'])

Added in version 3.4.

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.

logger が与えられた場合、 logging.Logger オブジェクトもしくはロガーの名前である str であるべきです。デフォルトはルートロガーで、これは全てのメッセージを掴まえます。

If given, level should be either a numeric logging level or its string equivalent (for example either "ERROR" or logging.ERROR). The default is logging.INFO.

assertLogs() と異なり、このコンテキストマネージャは何も返しません。

Added in version 3.10.

より具体的な確認を行うために以下のメソッドが用意されています:

メソッド

確認事項

初出

assertAlmostEqual(a, b)

round(a-b, 7) == 0

assertNotAlmostEqual(a, b)

round(a-b, 7) != 0

assertGreater(a, b)

a > b

3.1

assertGreaterEqual(a, b)

a >= b

3.1

assertLess(a, b)

a < b

3.1

assertLessEqual(a, b)

a <= b

3.1

assertRegex(s, r)

r.search(s)

3.1

assertNotRegex(s, r)

not r.search(s)

3.2

assertCountEqual(a, b)

a と b に、順番によらず同じ要素が同じ数だけある。

3.2

assertAlmostEqual(first, second, places=7, msg=None, delta=None)

assertNotAlmostEqual(first, second, places=7, msg=None, delta=None)

first と second が近似的に等しい (等しくない) ことをテストします。これは、places (デフォルト7) で指定した小数位で丸めた差分をゼロと比較することで行われます。これらのメソッドは (round() と同様に) 小数位 を指定するのであって、有効桁数 を指定するのではないことに注意してください。

places の代わりに delta が渡された場合には、first と second の差分が delta 以下 (以上) であることをテストします。

delta と places の両方が指定された場合は TypeError が送出されます。

バージョン 3.2 で変更: assertAlmostEqual() は、オブジェクトが等しい場合には自動で近似的に等しいとみなすようになりました。 assertNotAlmostEqual() は、オブジェクトが等しい場合には自動的に失敗するようになりました。 delta 引数が追加されました。

assertGreater(first, second, msg=None)

assertGreaterEqual(first, second, msg=None)

assertLess(first, second, msg=None)

assertLessEqual(first, second, msg=None)

first が second と比べて、メソッド名に対応して >, >=, < もしくは <= であることをテストします。そうでない場合はテストは失敗です:

>>> self.assertGreaterEqual(3, 4)
AssertionError: "3" unexpectedly not greater than or equal to "4"

Added in version 3.1.

assertRegex(text, regex, msg=None)

assertNotRegex(text, regex, msg=None)

regex の検索が text とマッチする (またはマッチしない) ことをテストします。テスト失敗時には、エラーメッセージにパターンと text が表示されます（もしくは、パターンと意図しないかたちでマッチした text の一部が表示されます）。 regex は正規表現オブジェクトか、 re.search() が扱える正規表現が書かれた文字列である必要があります。

Added in version 3.1: assertRegexpMatches という名前で追加されました。

バージョン 3.2 で変更: メソッド assertRegexpMatches() は assertRegex() にリネームされました。

Added in version 3.2: assertNotRegex()。

assertCountEqual(first, second, msg=None)

シーケンス first が second と同じ要素を含んでいることをテストします。要素の順序はテスト結果に影響しません。要素が含まれていない場合には、シーケンスの差分がエラーメッセージとして表示されます。

first と second の比較では、重複した要素は無視 されません。両者に同じ数の要素が含まれていることを検証します。このメソッドは assertEqual(Counter(list(first)), Counter(list(second))) と同等に振る舞うことに加えて、ハッシュ化できないオブジェクトのシーケンスでも動作します。

Added in version 3.2.

assertEqual() メソッドは、同じ型のオブジェクトの等価性確認のために、型ごとに特有のメソッドにディスパッチします。これらのメソッドは、ほとんどの組み込み型用のメソッドは既に実装されています。さらに、 addTypeEqualityFunc() を使う事で新たなメソッドを登録することができます:

addTypeEqualityFunc(typeobj, function)

assertEqual() で呼び出される型特有のメソッドを登録します。登録するメソッドは、比較する2つのオブジェクトの型が厳密に typeobj と同じ (サブクラスでもいけません) の場合に等価性を確認します。 function は assertEqual() と同様に、2つの位置引数と、3番目に msg=None のキーワード引数を取れる必要があります。このメソッドは、始めの2つに指定したパラメータ間の差分を検出した時に self.failureException(msg) の例外を投げる必要があります。この例外を投げる際は、出来る限り、エラーの内容が分かる有用な情報と差分の詳細をエラーメッセージに含めてください。

Added in version 3.1.

assertEqual() が自動的に呼び出す型特有のメソッドの概要を以下の表示に記載しています。これらのメソッドは通常は直接呼び出す必要がないことに注意が必要です。

メソッド

比較の対象

初出

assertMultiLineEqual(a, b)

文字列

3.1

assertSequenceEqual(a, b)

シーケンス

3.1

assertListEqual(a, b)

リスト

3.1

assertTupleEqual(a, b)

タプル

3.1

assertSetEqual(a, b)

set または frozenset

3.1

assertDictEqual(a, b)

辞書

3.1

assertMultiLineEqual(first, second, msg=None)

複数行の文字列 first が文字列 second と等しいことをテストします。等しくない場合には、両者の差分がハイライトされてエラーメッセージに表示されます。このメソッドは、デフォルトで、 assertEqual() が string を比較するときに自動的に使用します。

Added in version 3.1.

assertSequenceEqual(first, second, msg=None, seq_type=None)

2つのシーケンスが等しいことをテストします。seq_type が指定された場合、first と second が seq_type のインスタンスで無い場合にはテストが失敗します。シーケンスどうしが異なる場合には、両者の差分がエラーメッセージに表示されます。

このメソッドは直接 assertEqual() からは呼ばれませんが、 assertListEqual() と assertTupleEqual() の実装で使われています。

Added in version 3.1.

assertListEqual(first, second, msg=None)

assertTupleEqual(first, second, msg=None)

2つのリストまたはタプルが等しいかどうかをテストします。等しくない場合には、両者の差分を表示します。2つのパラメータの型が異なる場合にはテストがエラーになります。このメソッドは、デフォルトで、 assertEqual() が list または tuple を比較するときに自動的に使用します。

Added in version 3.1.

assertSetEqual(first, second, msg=None)

2つのセットが等しいかどうかをテストします。等しくない場合には、両者の差分を表示します。このメソッドは、デフォルトで、 assertEqual() が set もしくは frozenset を比較するときに自動的に使用します。

first or second のいずれかに set.difference() が無い場合にはテストは失敗します。

Added in version 3.1.

assertDictEqual(first, second, msg=None)

2つの辞書が等しいかどうかをテストします。等しくない場合には、両者の差分を表示します。このメソッドは、デフォルトで、 assertEqual() が dict を比較するときに自動的に使用します。

Added in version 3.1.

最後に、 TestCase の残りのメソッドと属性を紹介します:

fail(msg=None)

無条件にテストを失敗させます。エラーメッセージの表示に、msg または None が使われます。

failureException

test() メソッドが送出する例外を指定するクラス属性です。例えばテストフレームワークで追加情報を付した特殊な例外が必要になる場合、この例外のサブクラスとして作成します。この属性の初期値は AssertionError です。

longMessage

このクラス属性は、失敗した assertXYY の呼び出しで独自の失敗時のメッセージが msg 引数として渡されていたときにどうするかを決定します。 True がデフォルト値です。この場合、標準の失敗時のメッセージの後に独自のメッセージが追記されます。 False に設定したときは、標準のメッセージを独自のメッセージで置き換えます。

アサートメソッドを呼び出す前に、個別のテストメソッドの中でインスタンス属性 self.longMessage を True または False に設定して、この設定を上書きできます。

このクラスの設定はそれぞれのテストを呼び出す前にリセットされます。

Added in version 3.1.

maxDiff

この属性は、アサーションメソッドが失敗をレポートする時に表示する差分の長さをコントロールします。デフォルトは 80*8 文字です。この属性が影響するメソッドは、 assertSequenceEqual() (およびこのメソッドに委譲するシーケンス比較メソッド)、 assertDictEqual() と assertMultiLineEqual() です。

maxDiff を None に設定すると差分表示の上限がなくなります。

Added in version 3.2.

テストフレームワークは、テスト情報を収集するために以下のメソッドを使用します:

countTestCases()

テストオブジェクトに含まれるテストの数を返します。 TestCase インスタンスは常に 1 を返します。

defaultTestResult()

このテストケースクラスで使われるテスト結果クラスのインスタンスを (もし run() メソッドに他の結果インスタンスが提供されないならば) 返します。

TestCase インスタンスに対しては、いつも TestResult のインスタンスですので、 TestCase のサブクラスでは必要に応じてこのメソッドをオーバライドしてください。

id()

テストケースを特定する文字列を返します。通常、id はモジュール名・クラス名を含む、テストメソッドのフルネームを指定します。

shortDescription()

テストの説明を一行分、または説明がない場合には None を返します。デフォルトでは、テストメソッドの docstring の先頭の一行、または None を返します。

バージョン 3.1 で変更: 3.1で docstring があったとしても、返される短い説明文字列にテスト名が付けられるようになりました。この変更によって unittest 拡張に互換性の問題が発生し、 Python 3.2 でテスト名が追加される場所は TextTestResult へ移動しました。

addCleanup(function, /, *args, **kwargs)

tearDown() の後に呼び出される関数を追加します。この関数はリソースのクリーンアップのために使用します。追加された関数は、追加された順と逆の順番で呼び出されます（LIFO）。 addCleanup() に渡された引数とキーワード引数が追加された関数にも渡されます。

setUp() が失敗した場合、つまり tearDown() が呼ばれなかった場合でも、追加されたクリーンアップ関数は呼び出されます。

Added in version 3.1.

enterContext(cm)

Enter the supplied context manager. If successful, also add its __exit__() method as a cleanup function by addCleanup() and return the result of the __enter__() method.

Added in version 3.11.

doCleanups()

このメソッドは、 tearDown() の後、もしくは、 setUp() が例外を投げた場合は setUp() の後に、無条件で呼ばれます。

このメソッドは、 addCleanup() で追加された関数を呼び出す責務を担います。もし、クリーンアップ関数を tearDown() より前に呼び出す必要がある場合には、 doCleanups() を明示的に呼び出してください。

doCleanups() は、どこで呼び出されても、クリーンアップ関数をスタックから削除して実行します。

Added in version 3.1.

classmethod addClassCleanup(function, /, *args, **kwargs)

tearDownClass() の後に呼び出される関数を追加します。この関数はリソースのクリーンアップのために使用します。追加された関数は、追加された順と逆の順番で呼び出されます（LIFO）。 addClassCleanup() に渡された引数とキーワード引数が追加された関数にも渡されます。

setUpClass() が失敗した場合、つまり tearDownClass() が呼ばれなかった場合でも、追加されたクリーンアップ関数は呼び出されます。

Added in version 3.8.

classmethod enterClassContext(cm)

Enter the supplied context manager. If successful, also add its __exit__() method as a cleanup function by addClassCleanup() and return the result of the __enter__() method.

Added in version 3.11.

classmethod doClassCleanups()

このメソッドは、 tearDownClass() の後、もしくは、 setUpClass() が例外を投げた場合は setUpClass() の後に、無条件で呼ばれます。

このメソッドは、 addClassCleanup() で追加された関数を呼び出す責務を担います。もし、クリーンアップ関数を tearDownClass() より前に呼び出す必要がある場合には、 doClassCleanups() を明示的に呼び出してください。

doClassCleanups() は、どこで呼び出されても、クリーンアップ関数をスタックから削除して実行します。

Added in version 3.8.

class unittest.IsolatedAsyncioTestCase(methodName='runTest')

このクラスは TestCase と似たAPIを提供し、テスト関数としてコルーチンも許容します。

Added in version 3.8.

coroutine asyncSetUp()

テストフィクスチャを用意するために呼び出されるメソッドです。これは setUp(). の後に呼び出されます。これはテストメソッドを呼び出す直前に呼び出されます。AssertionError と SkipTest を除いて、このメソッドのによって送出されたあらゆる例外はテストの失敗ではなくエラーとみなされます。デフォルトの実装では何もしません。

coroutine asyncTearDown()

テストメソッドが呼び出され、その結果が記録された直後に呼び出されるメソッドです。これは tearDown() の前に呼び出されます。これはテストメソッドが例外を送出した場合でも呼び出されるので、サブクラスの実装では内部状態のチェックに特に気を付ける必要があります。このメソッドで送出された AssertionError と SkipTest 以外の例外は、テストの失敗ではなく追加のエラーとみなされます(そのため、報告されるエラーの総数が増えることになります)。このメソッドはテストメソッドの結果に関係なく、asyncSetUp() が成功した場合にのみ呼び出されます。デフォルトの実装では何もしません。

addAsyncCleanup(function, /, *args, **kwargs)

このメソッドはクリーンアップ関数として使用できるコルーチンを受け入れます。

coroutine enterAsyncContext(cm)

Enter the supplied asynchronous context manager. If successful, also add its __aexit__() method as a cleanup function by addAsyncCleanup() and return the result of the __aenter__() method.

Added in version 3.11.

run(result=None)

テストを実行するための新しいイベントループを作成し、 result*として渡された :class:`TestResult` オブジェクトに結果を収集します。*result が省略された場合や None の場合は、一時的なresultオブジェクトが(defaultTestResult() メソッドの呼び出しによって)作成され、使用されます。このresultオブジェクトは run() の呼び出し元に返されます。テスト終了時には、イベントループ内のすべてのタスクがキャンセルされます。

順番を示す例です:

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()

テスト実行後、events には ["setUp", "asyncSetUp", "test_response", "asyncTearDown", "tearDown", "cleanup"] が含まれます。

class unittest.FunctionTestCase(testFunc, setUp=None, tearDown=None, description=None)

このクラスでは TestCase インターフェースの内、テストランナーがテストを実行するためのインターフェースだけを実装しており、テスト結果のチェックやレポートに関するメソッドは実装していません。既存のテストコードを unittest によるテストフレームワークに組み込むために使用します。

テストのグループ化

class unittest.TestSuite(tests=())

このクラスは、個々のテストケースやテストスイートの集合を表現しています。通常のテストケースと同じようにテストランナーで実行するためのインターフェースを備えています。 TestSuite インスタンスを実行することはスイートをイテレートして得られる個々のテストを実行することと同じです。

引数 tests が指定された場合、それはテストケースに亘る繰り返し可能オブジェクトまたは内部でスイートを組み立てるための他のテストスイートでなければなりません。後からテストケースやスイートをコレクションに付け加えるためのメソッドも提供されています。

TestSuite は TestCase オブジェクトのように振る舞います。違いは、スイートにはテストを実装しない点にあります。代わりに、テストをまとめてグループ化して、同時に実行します。 TestSuite のインスタンスにテスト追加するためのメソッドが用意されています:

addTest(test)

TestCase 又は TestSuite のインスタンスをスイートに追加します。

addTests(tests)

イテラブル tests に含まれる全ての TestCase 又は TestSuite のインスタンスをスイートに追加します。

このメソッドは tests 上のイテレーションをしながらそれぞれの要素に addTest() を呼び出すのと等価です。

TestSuite クラスは TestCase と以下のメソッドを共有します:

run(result)

スイート内のテストを実行し、結果を result で指定した結果オブジェクトに収集します。 TestCase.run() と異なり、 TestSuite.run() では必ず結果オブジェクトを指定する必要があります。

debug()

このスイートに関連づけられたテストを結果を収集せずに実行します。これによりテストで送出された例外は呼び出し元に伝わるようになり、デバッガの下でのテスト実行をサポートできるようになります。

countTestCases()

このテストオブジェクトによって表現されるテストの数を返します。これには個別のテストと下位のスイートも含まれます。

__iter__()

Tests grouped by a TestSuite are always accessed by iteration. Subclasses can lazily provide tests by overriding __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 TestSuite.run() must be the same for each call iteration. After TestSuite.run(), callers should not rely on the tests returned by this method unless the caller uses a subclass that overrides TestSuite._removeTestAtIndex() to preserve test references.

バージョン 3.2 で変更: In earlier versions the TestSuite accessed tests directly rather than through iteration, so overriding __iter__() wasn't sufficient for providing tests.

バージョン 3.4 で変更: 以前のバージョンでは、 TestSuite.run() の実行後は TestSuite が各 TestCase への参照を保持していました。サブクラスで TestSuite._removeTestAtIndex() をオーバーライドすることでこの振る舞いを復元できます。

通常、 TestSuite の run() メソッドは TestRunner が起動するため、ユーザが直接実行する必要はありません。

テストのロードと起動

class unittest.TestLoader

TestLoader クラスはクラスとモジュールからテストスイートを生成します。通常、このクラスのインスタンスを明示的に生成する必要はありません。 unittest モジュールの unittest.defaultTestLoader を共用インスタンスとして使用することができます。 しかし、このクラスのサブクラスやインスタンスで、属性をカスタマイズすることができます。

TestLoader オブジェクトには以下の属性があります:

errors

テストの読み込み中に起きた致命的でないエラーのリストです。どの時点でもローダーからリセットされることはありません。致命的なエラーは適切なメソッドが例外を送出して、呼び出し元に通知します。致命的でないエラーも、実行したときのエラーを総合テストが通知してくれます。

Added in version 3.5.

TestLoader のオブジェクトには以下のメソッドがあります:

loadTestsFromTestCase(testCaseClass)

TestCase の派生クラス testCaseClass に含まれる全テストケースのスイートを返します。

getTestCaseNames() で指定されたメソッドに対し、テストケースインスタンスが作成されます。デフォルトでは test で始まる名前のメソッド群です。 getTestCaseNames() がメソッド名を返さなかったが、 runTest() メソッドが実装されている場合は、そのメソッドに対するテストケースが代わりに作成されます。

loadTestsFromModule(module, *, pattern=None)

指定したモジュールに含まれる全テストケースのスイートを返します。このメソッドは module 内の TestCase 派生クラスを検索し、見つかったクラスのテストメソッドごとにクラスのインスタンスを作成します。

注釈

TestCase クラスを基底クラスとしてクラス階層を構築するとテストフィクスチャや補助的な関数をうまく共用することができますが、基底クラスに直接インスタンス化できないテストメソッドがあると、この loadTestsFromModule() を使うことができません。この場合でも、 fixture が全て別々で定義がサブクラスにある場合は使用することができます。

モジュールが load_tests 関数を用意している場合、この関数がテストの読み込みに使われます。これによりテストの読み込み処理がカスタマイズできます。これが load_tests プロトコル です。 pattern 引数は load_tests に第3引数として渡されます。

バージョン 3.2 で変更: load_tests のサポートが追加されました。

バージョン 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.

loadTestsFromName(name, module=None)

文字列で指定される全テストケースを含むスイートを返します。

name には "ドット修飾名" でモジュールかテストケースクラス、テストケースクラス内のメソッド、 TestSuite インスタンスまたは TestCase か TestSuite のインスタンスを返す呼び出し可能オブジェクトを指定します。このチェックはここで挙げた順番に行なわれます。すなわち、候補テストケースクラス内のメソッドは「呼び出し可能オブジェクト」としてではなく「テストケースクラス内のメソッド」として拾い出されます。

例えば SampleTests モジュールに TestCase から派生した SampleTestCase クラスがあり、 SampleTestCase にはテストメソッド test_one() ・ test_two() ・ test_three() があるとします。この場合、 name に 'SampleTests.SampleTestCase' と指定すると、 SampleTestCase の三つのテストメソッドを実行するテストスイートが作成されます。 'SampleTests.SampleTestCase.test_two' と指定すれば、 test_two() だけを実行するテストスイートが作成されます。インポートされていないモジュールやパッケージ名を含んだ名前を指定した場合は自動的にインポートされます。

また、module を指定した場合、module 内の name を取得します。

バージョン 3.5 で変更: name を巡回している間に ImportError か AttributeError が発生した場合、実行するとその例外を発生させるようなテストを合成して返します。それらのエラーは self.errors に集められます。

loadTestsFromNames(names, module=None)

loadTestsFromName() と同じですが、名前を一つだけ指定するのではなく、複数の名前のシーケンスを指定する事ができます。戻り値は names 中の名前で指定されるテスト全てを含むテストスイートです。

getTestCaseNames(testCaseClass)

testCaseClass 中の全てのメソッド名を含むソート済みシーケンスを返します。 testCaseClass は TestCase のサブクラスでなければなりません。

discover(start_dir, pattern='test*.py', top_level_dir=None)

指定された開始ディレクトリからサブディレクトリに再帰することですべてのテストモジュールを検索し、それらを含む TestSuite オブジェクトを返します。pattern にマッチしたテストファイルだけがロードの対象になります。 (シェルスタイルのパターンマッチングが使われます)。その中で、インポート可能なもジュール (つまり Python の識別子として有効であるということです) がロードされます。

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.

シンタックスエラーなどでモジュールのインポートに失敗した場合、エラーが記録され、ディスカバリ自体は続けられます。 import の失敗が SkipTest 例外が発生したためだった場合は、そのモジュールはエラーではなく skip として記録されます。

パッケージ (__init__.py という名前のファイルがあるディレクトリ) が見付かった場合、そのパッケージに load_tests 関数があるかをチェックします。関数があった場合、次に package.load_tests(loader, tests, pattern) が呼ばれます。テストの検索の実行では、たとえ load_tests 関数自身が loader.discover を呼んだとしても、パッケージのチェックは1回のみとなることが保証されています。

load_tests が存在して、ディスカバリがパッケージ内を再帰的な検索を続けている途中で ない 場合、load_tests はそのパッケージ内の全てのテストをロードする責務を担います。

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 discover(). That is, if a package's load_tests calls loader.discover(), it does not need to pass this argument.

start_dir はドット付のモジュール名でもディレクトリでも構いません。

Added in version 3.2.

バージョン 3.4 で変更: インポート時に SkipTest を送出するモジュールはエラーではなくスキップとして記録されます。

バージョン 3.4 で変更: start_dir に 名前空間パッケージ を指定できます。

バージョン 3.4 で変更: ファイルシステムの順序がファイル名に従わないとしても実行順序が一定になるように、パスはインポートする前にソートされます。

バージョン 3.5 で変更: パッケージ名がデフォルトのパターンに適合するのは不可能なので、パスが pattern に適合するかどうかに関係無く、見付けたパッケージに load_tests があるかをチェックするようになりました。

バージョン 3.11 で変更: start_dir can not be a namespace packages. It has been broken since Python 3.7 and Python 3.11 officially remove it.

バージョン 3.12.4 で変更: top_level_dir is only stored for the duration of discover call.

以下の属性は、サブクラス化またはインスタンスの属性値を変更して TestLoader をカスタマイズする場合に使用します:

testMethodPrefix

テストメソッドの名前と判断されるメソッド名の接頭語を示す文字列。デフォルト値は 'test' です。

This affects getTestCaseNames() and all the loadTestsFrom* methods.

sortTestMethodsUsing

Function to be used to compare method names when sorting them in getTestCaseNames() and all the loadTestsFrom* methods.

suiteClass

テストのリストからテストスイートを構築する呼び出し可能オブジェクト。メソッドを持つ必要はありません。デフォルト値は TestSuite です。

This affects all the loadTestsFrom* methods.

testNamePatterns

テストメソッドがテストスイートに含まれるためにマッチしなければならないUnixシェルスタイルのワイルドカードテスト名パターンのリストです(-k オプションを参照)。

この属性が None (デフォルト)でない場合、テストスイートに含まれるすべてのテストメソッドはこのリストのパターンのいずれかにマッチしていなければなりません。マッチは常に fnmatch.fnmatchcase() を使用して実行されるため、-k オプションに渡されるパターンとは異なり、単純な部分文字列パターンは * ワイルドカードを使用して変換する必要があることに注意してください。

This affects all the loadTestsFrom* methods.

Added in version 3.7.

class unittest.TestResult

このクラスはどのテストが成功しどのテストが失敗したかという情報を収集するのに使います。

TestResult は、複数のテスト結果を記録します。 TestCase クラスと TestSuite クラスのテスト結果を正しく記録しますので、テスト開発者が独自にテスト結果を管理する処理を開発する必要はありません。

unittest を利用したテストフレームワークでは、 TestRunner.run() が返す TestResult インスタンスを参照し、テスト結果をレポートします。

TestResult インスタンスの以下の属性は、テストの実行結果を検査する際に使用することができます:

errors

TestCase と例外のトレースバック情報をフォーマットした文字列の 2 要素タプルからなるリスト。それぞれのタプルは予想外の例外を送出したテストに対応します。

failures

A list containing 2-tuples of TestCase instances and strings holding formatted tracebacks. Each tuple represents a test where a failure was explicitly signalled using the assert* methods.

skipped

TestCase インスタンスとテストをスキップした理由を保持する文字列の2要素タプルからなるリストです。

Added in version 3.1.

expectedFailures

TestCase と例外のトレースバック情報をフォーマット済の文字列の 2 要素タプルからなるリストです。それぞれのタプルは予期された失敗またはエラーに対応します。

unexpectedSuccesses

予期された失敗とされていながら成功してしまった TestCase のインスタンスのリスト。

collectedDurations

A list containing 2-tuples of test case names and floats representing the elapsed time of each test which was run.

Added in version 3.12.

shouldStop

True が設定されると stop() によりテストの実行が停止します。

testsRun

これまでに実行したテストの総数です。

buffer

True が設定されると、 sys.stdout と sys.stderr は、 startTest() から stopTest() が呼ばれるまでの間バッファリングされます。実際に、結果が sys.stdout と sys.stderr に出力されるのは、テストが失敗するかエラーが発生した時になります。表示の際には、全ての失敗 / エラーメッセージが表示されます。

Added in version 3.2.

failfast

真の場合 stop() が始めの失敗もしくはエラーの時に呼び出され、テストの実行が終了します。

Added in version 3.2.

tb_locals

真の場合、局所変数がトレースバックに表示されます。

Added in version 3.5.

wasSuccessful()

これまでに実行したテストが全て成功していれば True を、それ以外なら False を返します。

バージョン 3.4 で変更: expectedFailure() デコレ－タでマークされたテストに unexpectedSuccesses があった場合 False を返します。

stop()

このメソッドを呼び出して TestResult の shouldStop 属性に True をセットすることで、実行中のテストは中断しなければならないというシグナルを送ることができます。 TestRunner オブジェクトはこのフラグを順守してそれ以上のテストを実行することなく復帰しなければなりません。

たとえばこの機能は、ユーザのキーボード割り込みを受け取って TextTestRunner クラスがテストフレームワークを停止させるのに使えます。 TestRunner の実装を提供する対話的なツールでも同じように使用することができます。

TestResult クラスの以下のメソッドは内部データ管理用のメソッドですが、対話的にテスト結果をレポートするテストツールを開発する場合などにはサブクラスで拡張することができます。

startTest(test)

test を実行する直前に呼び出されます。

stopTest(test)

test の実行直後に、テスト結果に関わらず呼び出されます。

startTestRun()

全てのテストが実行される前に一度だけ実行されます。

Added in version 3.1.

stopTestRun()

全てのテストが実行された後に一度だけ実行されます。

Added in version 3.1.

addError(test, err)

テスト test 実行中に、想定外の例外が発生した場合に呼び出されます。 err は sys.exc_info() が返すタプル (type, value, traceback) です。

デフォルトの実装では、タプル、 (test, formatted_err) をインスタンスの errors 属性に追加します。ここで、 formatted_err は、 err から導出される、整形されたトレースバックです。

addFailure(test, err)

テストケース test が失敗した場合に呼び出されます。 err は sys.exc_info() が返すタプル (type, value, traceback) です。

デフォルトの実装では、タプル、 (test, formatted_err) をインスタンスの failures 属性に追加します。ここで、 formatted_err は、 err から導出される、整形されたトレースバックです。

addSuccess(test)

テストケース test が成功した場合に呼び出されます。

デフォルトの実装では何もしません。

addSkip(test, reason)

test がスキップされた時に呼び出されます。reason はスキップの際に渡された理由の文字列です。

デフォルトの実装では、 (test, reason) のタプルをインスタンスの skipped 属性に追加します。

addExpectedFailure(test, err)

expectedFailure() のデコレータでマークされた test が失敗またはエラーの時に呼び出されます。

デフォルトの実装では (test, formatted_err) のタプルをインスタンスの expectedFailures に追加します。ここで formatted_err は err から派生した整形されたトレースバックです。

addUnexpectedSuccess(test)

expectedFailure() のデコレータでマークされた test が成功した時に呼び出されます。

デフォルトの実装ではテストをインスタンスの unexpectedSuccesses 属性に追加します。

addSubTest(test, subtest, outcome)

サブテストが終了すると呼ばれます。 test はテストメソッドに対応するテストケースです。 subtest はサブテストを記述するカスタムの TestCase インスタンスです。

outcome が None の場合サブテストは成功です。それ以外の場合は失敗で、sys.exc_info() が返す形式 (type, value, traceback) の outcome を持つ例外を伴います。

結果が成功の場合デフォルトの実装では何もせず、サブテストの失敗を通常の失敗として報告します。

Added in version 3.4.

addDuration(test, elapsed)

Called when the test case finishes. elapsed is the time represented in seconds, and it includes the execution of cleanup functions.

Added in version 3.12.

class unittest.TextTestResult(stream, descriptions, verbosity, *, durations=None)

A concrete implementation of TestResult used by the TextTestRunner. Subclasses should accept **kwargs to ensure compatibility as the interface changes.

Added in version 3.2.

バージョン 3.12 で変更: Added the durations keyword parameter.

unittest.defaultTestLoader

TestLoader のインスタンスで、共用することが目的です。 TestLoader をカスタマイズする必要がなければ、新しい TestLoader オブジェクトを作らずにこのインスタンスを使用します。

class unittest.TextTestRunner(stream=None, descriptions=True, verbosity=1, failfast=False, buffer=False, resultclass=None, warnings=None, *, tb_locals=False, durations=None)

結果をストリームに出力する、基本的なテストランナーの実装です。 stream が None の場合、デフォルトで sys.stderr が出力ストリームとして使われます。このクラスはいくつかの設定項目があるだけで、基本的に非常に単純です。グラフィカルなテスト実行アプリケーションでは、独自のテストランナーを実装してください。テストランナーの実装は、 unittest に新しい機能が追加されランナーを構築するインターフェースが変更されたときに備えて **kwargs を受け取れるようにするべきです。

By default this runner shows DeprecationWarning, PendingDeprecationWarning, ResourceWarning and ImportWarning even if they are ignored by default. This behavior can be overridden using Python's -Wd or -Wa options (see Warning control) and leaving warnings to None.

バージョン 3.2 で変更: Added the warnings parameter.

バージョン 3.2 で変更: インポート時でなくインスタンス化時にデフォルトのストリームが sys.stderr に設定されます。

バージョン 3.5 で変更: Added the tb_locals parameter.

バージョン 3.12 で変更: Added the durations parameter.

_makeResult()

このメソッドは run() で使われる TestResult のインスタンスを返します。このメソッドは明示的に呼び出す必要はありませんが、サブクラスで TestResult をカスタマイズすることができます。

_makeResult() は、 TextTestRunner のコンストラクタで resultclass 引数として渡されたクラスもしくはコーラブルオブジェクトをインスタンス化します。 resultclass が指定されていない場合には、デフォルトで TextTestResult が使用されます。結果のクラスは以下の引数が渡されインスタンス化されます:

stream, descriptions, verbosity

run(test)

このメソッドは TextTestRunner へのメインの公開インターフェースです。このメソッドは TestSuite インスタンスあるいは TestCase インスタンスを受け取ります。 _makeResult() が呼ばれて TestResult が作成され、テストが実行され、結果が標準出力に表示されます。

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)

module から複数のテストを読み込んで実行するためのコマンドラインプログラム。この関数を使えば、簡単に実行可能なテストモジュールを作成する事ができます。一番簡単なこの関数の使い方は、以下の行をテストスクリプトの最後に置くことです:

if __name__ == '__main__':
    unittest.main()

より詳細な情報は verbosity 引数を指定して実行すると得られます:

if __name__ == '__main__':
    unittest.main(verbosity=2)

defaultTest 引数は、 argv にテスト名が指定されていない場合に実行する、ある1つのテストの名前もしくはテスト名のイテラブルです。この引数を指定しないか None を指定し、かつ argv にテスト名が与えられない場合は、 module にある全てのテストを実行します。

argv 引数には、プログラムに渡されたオプションのリストを、最初の要素がプログラム名のままで渡せます。指定しないか None の場合は sys.argv が使われます。

The testRunner argument can either be a test runner class or an already created instance of it. By default main calls 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.

testLoader 引数は TestLoader インスタンスでなければなりません。デフォルトは defaultTestLoader です。

main は、 exit=False を指定する事で対話的なインタプリタから使用することもできます。この引数を指定すると、 sys.exit() を呼ばずに、結果のみを出力します:

>>> from unittest import main
>>> main(module='test_module', exit=False)

failfast, catchbreak, buffer は、コマンドラインオプション にある同名のオプションと同じ効果のあるパラメータです。

warnings 引数では、テストの実行中に使うべき 警告フィルタ を指定します。この引数が指定されない場合には、 -W オプションが python に渡されていなければ None のまま (警告の制御 を参照してください) で、そうでなければ 'default' が設定されます。

main を呼び出すと、TestProgram のインスタンスが返されます。このインスタンスは、result 属性にテスト結果を保持します。

バージョン 3.1 で変更: exit パラメータが追加されました。

バージョン 3.2 で変更: verbosity、failfast、catchbreak、buffer、warnings 引数が追加されました。

バージョン 3.4 で変更: defaultTest 引数がテスト名のイテラブルも受け取るようになりました。

load_tests プロトコル

Added in version 3.2.

モジュールやパッケージには、load_tests と呼ばれる関数を実装できます。これにより、通常のテスト実行時やテストディスカバリ時のテストのロードされ方をカスタマイズできます。

テストモジュールが load_tests を定義していると、それが TestLoader.loadTestsFromModule() から呼ばれます。引数は以下です:

load_tests(loader, standard_tests, pattern)

pattern は loadTestsFromModule からそのまま渡されます。デフォルトは None です。

これは TestSuite を返すべきです。

loader はローディングを行う TestLoader のインスタンスです。 standard_tests は、そのモジュールからデフォルトでロードされるテストです。これは、テストの標準セットのテストの追加や削除のみを行いたいテストモジュールに一般に使われます。第三引数は、パッケージをテストディスカバリの一部としてロードするときに使われます。

特定の TestCase クラスのセットからテストをロードする典型的な load_tests 関数は、このようになります:

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

コマンドラインからでも TestLoader.discover() の呼び出しでも、パッケージを含むディレクトリで検索を始めた場合、そのパッケージの __init__.py をチェックして load_tests を探します。その関数が存在しない場合、他のディレクトリであるかのようにパッケージの中を再帰的に検索します。その関数が存在した場合、パッケージのテストの検索をそちらに任せ、 load_tests が次の引数で呼び出されます:

load_tests(loader, standard_tests, pattern)

これはパッケージ内のすべてのテストを表す TestSuite を返すべきです。 (standard_tests には、 __init__.py から収集されたテストのみが含まれます。)

パターンは load_tests に渡されるので、パッケージは自由にテストディスカバリを継続 (必要なら変更) できます。テストパッケージに '何もしない' load_tests 関数は次のようになります:

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

バージョン 3.5 で変更: パッケージ名がデフォルトのパターンに適合するのが不可能なため、検索ではパッケージ名が pattern に適合するかのチェックは行われなくなりました。

クラスとモジュールのフィクスチャ

クラスレベルとモジュールレベルのフィクスチャが TestSuite に実装されました。テストスイートが新しいクラスのテストを始める時、以前のクラス (あれば)の tearDownClass() を呼び出し、その後に新しいクラスの setUpClass() を呼び出します。

同様に、今回のテストのモジュールが前回のテストとは異なる場合、以前のモジュールの tearDownModule を実行し、次に新しいモジュールの setUpModule を実行します。

すべてのテストが実行された後、最後の tearDownClass と tearDownModule が実行されます。

なお、共有フィクスチャは、テストの並列化などの [潜在的な] 機能と同時にはうまくいかず、テストの分離を壊すので、気をつけて使うべきです。

unittest テストローダによるテスト作成のデフォルトの順序では、同じモジュールやクラスからのテストはすべて同じグループにまとめられます。これにより、setUpClass / setUpModule (など) は、一つのクラスやモジュールにつき一度だけ呼ばれます。この順序をバラバラにし、異なるモジュールやクラスのテストが並ぶようにすると、共有フィクスチャ関数は、一度のテストで複数回呼ばれるようにもなります。

共有フィクスチャは標準でない順序で実行されることを意図していません。共有フィクスチャをサポートしたくないフレームワークのために、BaseTestSuite がまだ存在しています。

共有フィクスチャ関数のいずれかで例外が発生した場合、そのテストはエラーとして報告されます。そのとき、対応するテストインスタンスが無いので(TestCase と同じインターフェースの) _ErrorHolder オブジェクトが生成され、エラーを表します。標準 unittest テストランナーを使っている場合はこの詳細は問題になりませんが、あなたがフレームワークの作者である場合は注意してください。

setUpClass と tearDownClass

これらはクラスメソッドとして実装されなければなりません:

import unittest

class Test(unittest.TestCase):
    @classmethod
    def setUpClass(cls):
        cls._connection = createExpensiveConnectionObject()

    @classmethod
    def tearDownClass(cls):
        cls._connection.destroy()

基底クラスの setUpClass および tearDownClass を使いたいなら、それらを自分で呼び出さなければなりません。 TestCase の実装は空です。

setUpClass の中で例外が送出されたら、クラス内のテストは実行されず、 tearDownClass も実行されません。スキップされたクラスは setUpClass も tearDownClass も実行されません。例外が SkipTest 例外であれば、そのクラスはエラーではなくスキップされたものとして報告されます。

setUpModule と tearDownModule

これらは関数として実装されなければなりません:

def setUpModule():
    createConnection()

def tearDownModule():
    closeConnection()

setUpModule の中で例外が送出されたら、モジュール内のテストは実行されず、 tearDownModule も実行されません。例外が SkipTest 例外であれば、そのモジュールはエラーではなくスキップされたものとして報告されます。

例外が発生した場合でも実行しなければならないクリーンアップコードを追加するには``addModuleCleanup``を使用します:

unittest.addModuleCleanup(function, /, *args, **kwargs)

tearDownModule() の後に呼び出される関数を追加します。この関数はリソースのクリーンアップのために使用します。追加された関数は、追加された順と逆の順番で呼び出されます（LIFO）。 addModuleCleanup() に渡された引数とキーワード引数が追加された関数にも渡されます。

setUpModule() が失敗した場合、つまり tearDownModule() が呼ばれなかった場合でも、追加されたクリーンアップ関数は呼び出されます。

Added in version 3.8.

classmethod unittest.enterModuleContext(cm)

Enter the supplied context manager. If successful, also add its __exit__() method as a cleanup function by addModuleCleanup() and return the result of the __enter__() method.

Added in version 3.11.

unittest.doModuleCleanups()

この関数は、 tearDownModule() の後、もしくは、 setUpModule() が例外を投げた場合は setUpModule() の後に、無条件で呼ばれます。

このメソッドは、 addModuleCleanup() で追加された関数を呼び出す責務を担います。もし、クリーンアップ関数を tearDownModule() より前に呼び出す必要がある場合には、 doModuleCleanups() を明示的に呼び出してください。

doModuleCleanups() は、どこで呼び出されても、クリーンアップ関数をスタックから削除して実行します。

Added in version 3.8.

シグナルハンドリング

Added in version 3.2.

unittest の -c/--catch コマンドラインオプションや、 unittest.main() の catchbreak パラメタは、テスト実行中の control-C の処理をよりフレンドリーにします。中断捕捉動作を有効である場合、 control-C が押されると、現在実行されているテストまで完了され、そのテストランが終わると今までの結果が報告されます。control-C がもう一度押されると、通常通り KeyboardInterrupt が送出されます。

シグナルハンドラを処理する control-c は、独自の signal.SIGINT ハンドラをインストールするコードやテストの互換性を保とうとします。 unittest ハンドラが呼ばれ、それがインストールされた signal.SIGINT ハンドラで なければ 、すなわちテスト中のシステムに置き換えられて移譲されたなら、それはデフォルトのハンドラを呼び出します。インストールされたハンドラを置き換えて委譲するようなコードは、通常その動作を期待するからです。 unittest の control-c 処理を無効にしたいような個別のテストには、 removeHandler() デコレータが使えます。

フレームワークの作者がテストフレームワーク内で control-c 処理を有効にするための、いくつかのユーティリティ関数があります。

unittest.installHandler()

control-c ハンドラをインストールします。(主にユーザが control-c を押したことにより) signal.SIGINT が受け取られると、登録した結果すべてに stop() が呼び出されます。

unittest.registerResult(result)

control-c 処理のために TestResult を登録します。結果を登録するとそれに対する弱参照が格納されるので、結果がガベージコレクトされるのを妨げません。

control-c 処理が有効でなければ、 TestResult オブジェクトの登録には副作用がありません。ですからテストフレームワークは、処理が有効か無効かにかかわらず、作成する全ての結果を無条件に登録できます。

unittest.removeResult(result)

登録された結果を削除します。一旦結果が削除されると、control-c が押された際にその結果オブジェクトに対して stop() が呼び出されなくなります。

unittest.removeHandler(function=None)

引数なしで呼び出されると、この関数はCtrl+Cのシグナルハンドラを（それがインストールされていた場合）削除します。また、この関数はテストが実行されている間、Ctrl+Cのハンドラを一時的に削除するテストデコレーターとしても使用できます。

@unittest.removeHandler
def test_signal_handling(self):
    ...

unittest.mock --- mock object library

Added in version 3.3.

ソースコード: Lib/unittest/mock.py [https://github.com/python/cpython/tree/3.12/Lib/unittest/mock.py]

unittest.mock はPython におけるソフトウェアテストのためのライブラリです。テスト中のシステムの一部をモックオブジェクトで置き換え、それらがどのように使われるかをアサートすることができます。

unittest.mock はコア Mock クラスを提供しており、それによってテストスイート内でたくさんのスタブを作成しなくてすみます 。アクションの実行後、メソッドや属性の使用や実引数についてアサートできます。また通常の方法で戻り値を明記したり、必要な属性を設定することもできます。

加えて、 mock はテストのスコープ内にあるモジュールやクラスの属性を変更する patch() デコレータを提供します。さらに、ユニークなオブジェクトの作成には sentinel が利用できます。 Mock や MagicMock 、 patch() の利用例は quick guide を参照してください。

Mock は unittest で利用するために設計されており、多くのモックフレームワークで使われる 'record -> replay' パターンの代わりに、 'action -> assertion' パターンに基づいています。

There is a backport of unittest.mock for earlier versions of Python, available as mock [https://pypi.org/project/mock/] on PyPI.

クイックガイド

Mock および MagicMock オブジェクトはアクセスしたすべての属性とメソッドを作成し、どのように使用されたかについての詳細な情報を格納します。戻り値を指定したり利用できる属性を制限するために Mock および MagicMock を設定でき、どのよう使用されたかについてアサートできます:

>>> 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')

side_effect によって、モック呼び出し時の例外発生などの副作用を実行できます:

>>> from unittest.mock import Mock
>>> mock = Mock(side_effect=KeyError('foo'))
>>> mock()
Traceback (most recent call last):
 ...
KeyError: 'foo'

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

モックには多くの設定法や挙動の制御法があります。例えば spec 引数によって別のオブジェクトからの仕様を受け取るよう設定できます。 spec にないモックの属性やメソッドにアクセスを試みた場合、 AttributeError で失敗します。

patch() デコレータ / コンテキストマネージャーによってテスト対象のモジュール内のクラスやオブジェクトを簡単にモックできます。指定したオブジェクトはテスト中はモック (または別のオブジェクト) に置換され、テスト終了時に復元されます:

>>> 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()

注釈

patch デコレータをネストした場合、モックは適用されるときと同じ順番 (デコレータを適用するときの通常の Python の順番) でデコレートされた関数に渡されます。 つまり下から順に適用されるため、上の例では module.ClassName1 のモックが最初に渡されます。

patch() では探索される名前空間内のオブジェクトにパッチをあてることが重要です。通常は単純ですが、クイックガイドには どこにパッチするか を読んでください。

patch() デコレータと同様に with 文でコンテキストマネージャーとして使用できます:

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

また、 patch.dict() を使うと、スコープ内だけで辞書に値を設定し、テスト終了時には元の状態に復元されます:

>>> foo = {'key': 'value'}
>>> original = foo.copy()
>>> with patch.dict(foo, {'newkey': 'newvalue'}, clear=True):
...     assert foo == {'newkey': 'newvalue'}
...
>>> assert foo == original

mock は Python の マジックメソッド のモックをサポートしています。 マジックメソッドのもっとも簡単な利用法は MagicMock クラスと使うことです。以下のように利用します:

>>> mock = MagicMock()
>>> mock.__str__.return_value = 'foobarbaz'
>>> str(mock)
'foobarbaz'
>>> mock.__str__.assert_called_with()

mock によってマジックメソッドに関数 (あるいは他の Mock インスタンス) を割り当てることができ、それらは適切に呼び出されます。 MagicMock クラスは、すべてのマジックメソッドがあらかじめ作成されている点を除けば Mock クラスと一緒です (まあ、とにかく便利ってこと)。

以下は通常の Mock クラスでマジックメソッドを利用する例です:

>>> mock = Mock()
>>> mock.__str__ = Mock(return_value='wheeeeee')
>>> str(mock)
'wheeeeee'

テスト内のモックオブジェクトが置換するオブジェクトと同じ API を持つことを保証するには、 auto-speccing を使うことができます。パッチをあてる autospec 引数、または create_autospec() 関数を通じて auto-speccing は行われます。 auto-speccing は置換するオブジェクトと同じ属性とメソッドを持つモックオブジェクトを作成し、すべての関数および (コンストラクタを含む) メソッドは本物のオブジェクトと同じ呼び出しシグネチャを持ちます。

誤って使用された場合、モックは製品コードと同じように失敗されることが保証されています:

>>> 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: <lambda>() takes exactly 3 arguments (1 given)

create_autospec() はクラスにおいても利用でき、 __init__ メソッドのシグニチャをコピーします。また、呼び出し可能オブジェクトについても __call__ メソッドのシグニチャをコピーします。

Mock クラス

Mock は、コードにおけるスタブの使用やテストダブルを置き換えるための柔軟なモックオブジェクトです。モックは呼び出し可能で、属性にアクセスした場合それを新たなモックとして作成します [1]。同じ属性にアクセスした場合は常に同じモックを返します。モックはどのように使われたかを記録するので、コードがモックに行うことについてアサートできます。

MagicMock は Mock のサブクラスで、すべてのマジックメソッドが事前に作成され、利用できます。また、呼び出し不可能なモックを作成する場合には、呼び出し不能な変種の NonCallableMock や NonCallableMagicMock があります。

patch() デコレータによって特定のモジュール内のクラスを Mock オブジェクトで一時的に置換することが簡単にできます。デフォルトでは patch() は MagicMock を作成します。 patch() に渡す new_callable 引数によって、別の Mock クラスを指定できます。

class unittest.mock.Mock(spec=None, side_effect=None, return_value=DEFAULT, wraps=None, name=None, spec_set=None, unsafe=False, **kwargs)

新しい Mock オブジェクトを作成します。 Mock はモックオブジェクトの挙動を指定するオプション引数をいくつか取ります:

spec: モックオブジェクトの仕様として働く文字列のリストもしくは存在するオブジェクト (クラスもしくはインスタンス) を指定します。オブジェクトを渡した場合には、 dir 関数によって文字列のリストが生成されます (サポートされない特殊属性や特殊メソッドは除く) 。このリストにない属性にアクセスした際には AttributeError が発生します。

spec が (文字列のリストではなく) オブジェクトの場合、 __class__ はスペックオブジェクトのクラスを返します。これによってモックが isinstance() テストに通るようになります。

spec_set: より厳しい spec です。こちらを利用した場合、 spec_set に渡されたオブジェクトに存在しない属性に対し 設定 や取得をしようとした際に AttributeError が発生します。

side_effect: モックが呼び出された際に呼び出される関数を指定します。 side_effect 属性を参考にしてください。例外を発生させたり、動的に戻り値を変更する場合に便利です。関数には、モックと同じ引数が渡され、 DEFAULT を返さない限りはこの関数の戻り値が使われます。

一方で、 side_effect には、例外クラスやインスタンスを指定できます。この場合は、モックが呼び出された際に指定された例外を発生します。

もし、 side_effect にイテレート可能オブジェクトを指定した場合には、モックの呼び出しごとに順に値を返します。

side_effect に None を指定した場合には、設定がクリアされます。

return_value: モックが呼び出された際に返す値です。デフォルトでは (最初にアクセスされた際に生成される) 新しい Mock を返します。 return_value を参照してください。

unsafe: By default, accessing any attribute whose name starts with assert, assret, asert, aseert or assrt will raise an AttributeError. Passing unsafe=True will allow access to these attributes.

Added in version 3.5.

wraps: このモックオブジェクトがラップするものです。 wraps が None でなければ、このモックを呼び出すと、その呼び出しがラップされたオブジェクトに渡され (て実際の結果を返し) ます。モックの属性アクセスは、ラップされたオブジェクトの対応する属性をラップする Mock オブジェクトを返します (なので、存在しない属性にアクセスしようとすると AttributeError を送出します)。

モックが明示的に return_value を設定されていると、呼び出しはラップされたオブジェクトに渡されず、代わりに return_value が返されます。

name: モックに名前があるなら、それがモックの repr として使われます。これはデバッグの際に役立つでしょう。この名前は子のモックにも伝播します。

モックは、任意のキーワード引数を与えることができます。これらはモックの生成後、属性の設定に使われます。詳細は configure_mock() を参照してください。

assert_called()

モックが少なくとも一度は呼び出されたことをアサートします。

>>> mock = Mock()
>>> mock.method()
<Mock name='mock.method()' id='...'>
>>> mock.method.assert_called()

Added in version 3.6.

assert_called_once()

モックが一度だけ呼び出されたことをアサートします。

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

Added in version 3.6.

assert_called_with(*args, **kwargs)

This method is a convenient way of asserting that the last call has been made in a particular way:

>>> mock = Mock()
>>> mock.method(1, 2, 3, test='wow')
<Mock name='mock.method()' id='...'>
>>> mock.method.assert_called_with(1, 2, 3, test='wow')

assert_called_once_with(*args, **kwargs)

モックが一度だけ呼び出され、かつ指定された引数で呼び出されたことをアサートします。

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

assert_any_call(*args, **kwargs)

モックが特定の引数で呼び出されたことがあるのをアサートします。

The assert passes if the mock has ever been called, unlike assert_called_with() and assert_called_once_with() that only pass if the call is the most recent one, and in the case of assert_called_once_with() it must also be the only call.

>>> mock = Mock(return_value=None)
>>> mock(1, 2, arg='thing')
>>> mock('some', 'thing', 'else')
>>> mock.assert_any_call(1, 2, arg='thing')

assert_has_calls(calls, any_order=False)

モックが特定の呼び出しで呼ばれたことをアサートします。呼び出しでは mock_calls のリストがチェックされます。

any_order が false の場合、呼び出しは連続していなければなりません。指定された呼び出しの前、あるいは呼び出しの後に余分な呼び出しがある場合があります。

any_order が true の場合、呼び出しは任意の順番でも構いませんが、それらがすべて mock_calls に現われなければなりません。

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

assert_not_called()

モックが一度も呼ばれなかったことをアサートします。

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

Added in version 3.5.

reset_mock(*, return_value=False, side_effect=False)

モックオブジェクトのすべての呼び出し属性をリセットします:

>>> mock = Mock(return_value=None)
>>> mock('hello')
>>> mock.called
True
>>> mock.reset_mock()
>>> mock.called
False

バージョン 3.6 で変更: 2つのキーワード専用引数が reset_mock 関数に追加されました。

This can be useful where you want to make a series of assertions that reuse the same object. Note that reset_mock() doesn't clear the return value, side_effect or any child attributes you have set using normal assignment by default. In case you want to reset return_value or side_effect, then pass the corresponding parameter as True. Child mocks and the return value mock (if any) are reset as well.

注釈

return_value と side_effect はキーワード専用引数です。

mock_add_spec(spec, spec_set=False)

モックに仕様を追加します。 spec にはオブジェクトもしくは文字列のリストを指定してください。 spec で設定した属性は、モックの属性としてのみアクセスできます。

spec_set が真なら、 spec 以外の属性は設定できません。

attach_mock(mock, attribute)

属性として mock を設定して、その名前と親を入れ替えます。設定されたモックの呼び出しは、 method_calls や mock_calls 属性に記録されます。

configure_mock(**kwargs)

モックの属性をキーワード引数で設定します。

属性に加え、子の戻り値や副作用もドット表記を用いて設定でき、辞書はメソッドの呼び出し時にアンパックされます:

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

コンストラクタの呼び出しでも同様に行うことができます:

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

configure_mock() は、モック生成後のコンフィギュレーションを容易に行うために存在します。

__dir__()

Mock オブジェクトは、有用な結果を得るために dir(some_mock) の結果を制限します。 spec を設定したモックに対しては、許可された属性のみを含みます。

このフィルタが何をしていて、どのように停止させるかは、 FILTER_DIR を参照してください。

_get_child_mock(**kw)

子のモックを作成し、その値を返すようにしてください。デフォルトでは親と同じタイプで作成されます。サブクラスで子モックの作成される方法をカスタマイズしたい場合には、このメソッドをオーバーライドします。

呼び出し不可能なモックに対しては、(カスタムのサブクラスではなく) 呼び出し可能なモックが使われます。

called

このモックが呼び出されたかどうかを表します:

>>> mock = Mock(return_value=None)
>>> mock.called
False
>>> mock()
>>> mock.called
True

call_count

このモックオブジェクトが呼び出された回数を返します:

>>> mock = Mock(return_value=None)
>>> mock.call_count
0
>>> mock()
>>> mock()
>>> mock.call_count
2

return_value

モックが呼び出された際に返す値を設定します:

>>> mock = Mock()
>>> mock.return_value = 'fish'
>>> mock()
'fish'

デフォルトの戻り値はモックオブジェクトです。通常の方法で設定することもできます:

>>> mock = Mock()
>>> mock.return_value.attribute = sentinel.Attribute
>>> mock.return_value()
<Mock name='mock()()' id='...'>
>>> mock.return_value.assert_called_with()

return_value は生成時にも設定可能です:

>>> mock = Mock(return_value=3)
>>> mock.return_value
3
>>> mock()
3

side_effect

このモックが呼ばれた際に呼び出される関数、イテラブル、もしくは発生させる例外 (クラスまたはインスタンス) を設定できます。

関数を渡した場合はモックと同じ引数で呼び出され、 DEFAULT を返さない限りはその関数の戻り値が返されます。関数が DEFAULT を返した場合は ( return_value によって) モックの通常の値を返します。

iterable が渡された場合、その値はイテレータを取り出すために使用されます。イテレータは毎回の呼び出しにおいて値を yield しなければなりません。この値は、送出される例外インスタンスか、呼び出しからモックに返される値のいずれかです (DEFAULT の処理は関数の場合と同一です)。

以下はモックが (API による例外の扱いをテストするために) 例外を発生させる例です:

>>> mock = Mock()
>>> mock.side_effect = Exception('Boom!')
>>> mock()
Traceback (most recent call last):
  ...
Exception: Boom!

side_effect を使用して連続的に値を返します:

>>> mock = Mock()
>>> mock.side_effect = [3, 2, 1]
>>> mock(), mock(), mock()
(3, 2, 1)

呼び出し可能オブジェクトを使います:

>>> mock = Mock(return_value=3)
>>> def side_effect(*args, **kwargs):
...     return DEFAULT
...
>>> mock.side_effect = side_effect
>>> mock()
3

side_effect は生成時にも設定可能です。呼び出し時の値に 1 を加えて返す例を以下に示します:

>>> side_effect = lambda value: value + 1
>>> mock = Mock(side_effect=side_effect)
>>> mock(3)
4
>>> mock(-8)
-7

side_effect に None を設定した場合はクリアされます:

>>> m = Mock(side_effect=KeyError, return_value=3)
>>> m()
Traceback (most recent call last):
 ...
KeyError
>>> m.side_effect = None
>>> m()
3

call_args

This is either None (if the mock hasn't been called), or the arguments that the mock was last called with. This will be in the form of a tuple: the first member, which can also be accessed through the args property, is any ordered arguments the mock was called with (or an empty tuple) and the second member, which can also be accessed through the kwargs property, is any keyword arguments (or an empty dictionary).

>>> 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!'}

call_args は、 call_args_list や method_calls 、 mock_calls と同様、 call オブジェクトです。これらはタプルとしてアンパックすることで個別に取り出すことができます。そして、より複雑なアサーションを行うことができます。 calls as tuples を参照してください。

バージョン 3.8 で変更: args と kwargs 属性が追加されました。

call_args_list

モックの呼び出しを順に記録したリストです (よって、このリストの長さはモックが呼び出された回数と等しくなります)。モックを作成してから一度も呼び出しを行なっていない場合は、空のリストが返されます。 call オブジェクトは、 call_args_list の比較対象となる呼び出しのリストを作成する際に便利です。

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

call_args_list のメンバは call オブジェクトです。タプルとしてアンパックすることで個別に取り出すことができます。 calls as tuples を参照してください。

method_calls

自身の呼び出しと同様に、モックはメソッドや属性、そして それらの メソッドや属性の呼び出しも追跡します:

>>> 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()]

method_calls のメンバは call オブジェクトです。タプルとしてアンパックすることで個別に取り出すことができます。 calls as tuples を参照してください。

mock_calls

mock_calls は、メソッド、特殊メソッド、 そして 戻り値のモックまで、モックオブジェクトに対する すべての 呼び出しを記録します。

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

mock_calls のメンバは call オブジェクトです。タプルとしてアンパックすることで個別に取り出すことができます。 calls as tuples を参照してください。

注釈

The way mock_calls are recorded means that where nested calls are made, the parameters of ancestor calls are not recorded and so will always compare equal:

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

__class__

通常、オブジェクトの __class__ 属性はその型を返します。 spec を設定したオブジェクトの場合、 __class__ は代わりに spec のクラスを返します。これにより、置き換え / 偽装しているオブジェクトに対する isinstance() も通過することができます:

>>> mock = Mock(spec=3)
>>> isinstance(mock, int)
True

__class__ は書き換え可能で、 isinstance() を通るために必ず spec を使う必要はありません:

>>> mock = Mock()
>>> mock.__class__ = dict
>>> isinstance(mock, dict)
True

class unittest.mock.NonCallableMock(spec=None, wraps=None, name=None, spec_set=None, **kwargs)

呼び出しができない Mock です。コンストラクタのパラメータは Mock と同様ですが、 return_value や side_effect は意味を持ちません。

spec か spec_set にクラスかインスタンスを渡した mock は isinstance() テストをパスします:

>>> mock = Mock(spec=SomeClass)
>>> isinstance(mock, SomeClass)
True
>>> mock = Mock(spec_set=SomeClass())
>>> isinstance(mock, SomeClass)
True

Mock クラスは、 特殊メソッドをサポートしています。すべての詳細は magic methods を参照してください。

モッククラスや patch() デコレータは、任意のキーワード引数を設定できます。 patch() デコレータへのキーワード引数は、モックが作られる際のコンストラクタに渡されます。キーワード引数は、モックの属性を設定します:

>>> m = MagicMock(attribute=3, other='fish')
>>> m.attribute
3
>>> m.other
'fish'

子の戻り値や副作用も、ドットで表記することで同様に設定できます。呼び出し時に直接ドットのついた名前を使用できないので、作成した辞書を ** でアンパックする必要があります:

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

spec (または spec_set) によって作成された呼び出し可能なモックは、モックへの呼び出しがマッチしたときに仕様オブジェクトのシグネチャを内省します。したがって、引数を位置引数として渡したか名前で渡したかどうかに関わらず、実際の呼び出しの引数とマッチすることができます:

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

これは assert_called_with(), assert_called_once_with(), assert_has_calls() and assert_any_call() にも適用されます。 autospec を使う と、 モックオブジェクトのメソッド呼び出しにも適用されます。

バージョン 3.4 で変更: spec や autospec を用いて生成されたモックオブジェクトは、シグネチャを考慮するようになりました。

class unittest.mock.PropertyMock(*args, **kwargs)

A mock intended to be used as a property, or other descriptor, on a class. PropertyMock provides __get__() and __set__() methods so you can specify a return value when it is fetched.

オブジェクトから PropertyMock のインスタンスを取得することは、引数を与えないモックの呼び出しに相当します。設定は、 設定する値を伴った呼び出しになります。:

>>> 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)]

PropertyMock を直接モックに取り付ける方法は、モックの属性を保存する方法によりうまく動作しません。代わりに、モック型に取り付けてください:

>>> m = MagicMock()
>>> p = PropertyMock(return_value=3)
>>> type(m).foo = p
>>> m.foo
3
>>> p.assert_called_once_with()

class unittest.mock.AsyncMock(spec=None, side_effect=None, return_value=DEFAULT, wraps=None, name=None, spec_set=None, unsafe=False, **kwargs)

An asynchronous version of MagicMock. The AsyncMock object will behave so the object is recognized as an async function, and the result of a call is an awaitable.

>>> mock = AsyncMock()
>>> asyncio.iscoroutinefunction(mock)
True
>>> inspect.isawaitable(mock())
True

The result of mock() is an async function which will have the outcome of side_effect or return_value after it has been awaited:

if side_effect is a function, the async function will return the result of that function,

if side_effect is an exception, the async function will raise the exception,

if side_effect is an iterable, the async function will return the next value of the iterable, however, if the sequence of result is exhausted, StopAsyncIteration is raised immediately,

if side_effect is not defined, the async function will return the value defined by return_value, hence, by default, the async function returns a new AsyncMock object.

Setting the spec of a Mock or MagicMock to an async function will result in a coroutine object being returned after calling.

>>> async def async_func(): pass
...
>>> mock = MagicMock(async_func)
>>> mock
<MagicMock spec='function' id='...'>
>>> mock()
<coroutine object AsyncMockMixin._mock_call at ...>

Setting the spec of a Mock, MagicMock, or AsyncMock to a class with asynchronous and synchronous functions will automatically detect the synchronous functions and set them as MagicMock (if the parent mock is AsyncMock or MagicMock) or Mock (if the parent mock is Mock). All asynchronous functions will be AsyncMock.

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

Added in version 3.8.

assert_awaited()

Assert that the mock was awaited at least once. Note that this is separate from the object having been called, the await keyword must be used:

>>> 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()

assert_awaited_once()

Assert that the mock was awaited exactly once.

>>> mock = AsyncMock()
>>> async def main():
...     await mock()
...
>>> asyncio.run(main())
>>> mock.assert_awaited_once()
>>> asyncio.run(main())
>>> mock.method.assert_awaited_once()
Traceback (most recent call last):
...
AssertionError: Expected mock to have been awaited once. Awaited 2 times.

assert_awaited_with(*args, **kwargs)

Assert that the last await was with the specified arguments.

>>> 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 call not found.
Expected: mock('other')
Actual: mock('foo', bar='bar')

assert_awaited_once_with(*args, **kwargs)

Assert that the mock was awaited exactly once and with the specified arguments.

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

assert_any_await(*args, **kwargs)

Assert the mock has ever been awaited with the specified arguments.

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

assert_has_awaits(calls, any_order=False)

Assert the mock has been awaited with the specified calls. The await_args_list list is checked for the awaits.

If any_order is false then the awaits must be sequential. There can be extra calls before or after the specified awaits.

If any_order is true then the awaits can be in any order, but they must all appear in await_args_list.

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

assert_not_awaited()

Assert that the mock was never awaited.

>>> mock = AsyncMock()
>>> mock.assert_not_awaited()

reset_mock(*args, **kwargs)

See Mock.reset_mock(). Also sets await_count to 0, await_args to None, and clears the await_args_list.

await_count

An integer keeping track of how many times the mock object has been awaited.

>>> mock = AsyncMock()
>>> async def main():
...     await mock()
...
>>> asyncio.run(main())
>>> mock.await_count
1
>>> asyncio.run(main())
>>> mock.await_count
2

await_args

This is either None (if the mock hasn’t been awaited), or the arguments that the mock was last awaited with. Functions the same as Mock.call_args.

>>> 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')

await_args_list

This is a list of all the awaits made to the mock object in sequence (so the length of the list is the number of times it has been awaited). Before any awaits have been made it is an empty list.

>>> 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')]

呼び出し

モックオブジェクトは呼び出し可能です。呼び出しの戻り値は return_value 属性に設定された値です。デフォルトでは新しいモックオブジェクトを返します。この新しいモックは、属性に最初にアクセスした際に作成されます (明示もしくはモックの呼び出しによって)。 そしてそれは保存され、それ以降は同じものが返されます。

呼び出しはオブジェクトとして call_args や call_args_list に記録されます。

もし side_effect が設定されている場合は、その呼び出しが記録された後に呼び出されます。よって、もし side_effect が例外を発生させても、その呼び出しは記録されます。

呼び出された際に例外を発生させるモックを作成するためには、 side_effect を例外クラスかインスタンスにする方法が最もシンプルです:

>>> 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')]

もし side_effect が関数だった場合には、その関数の戻り値がモックを呼び出した際の戻り値になります。 side_effect 関数には、モックの呼び出し時に与えられた引数と同じ物があたえられます。これにより、入力によって動的に値を返すことができます:

>>> 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)]

もし、モックにデフォルトの戻り値 (新しいモック) や設定した値を返して欲しい場合は、2つの方法があります。 side_effect の内部で mock.return_value を返すか DEFAULT を返します:

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

side_effect を削除し、デフォルトの挙動を行うようにするには、 side_effect に None を設定します:

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

side_effect には、イテレート可能オブジェクトを設定できます。モックが呼び出されるごとに、イテレート可能オブジェクトから戻り値を得ます (イテレート可能オブジェクトが尽きて StopIteration が発生するまで):

>>> m = MagicMock(side_effect=[1, 2, 3])
>>> m()
1
>>> m()
2
>>> m()
3
>>> m()
Traceback (most recent call last):
  ...
StopIteration

もしイテレート可能オブジェクトの要素が例外だった場合には、戻り値として返される代わりに例外が発生します:

>>> iterable = (33, ValueError, 66)
>>> m = MagicMock(side_effect=iterable)
>>> m()
33
>>> m()
Traceback (most recent call last):
 ...
ValueError
>>> m()
66

属性の削除

モックオブジェクトは要求に応じて属性を生成することで，任意のオブジェクトとして振る舞うことができます。

hasattr() の呼び出しの際に False を返したり，属性にアクセスした際に AttributeError を発生させたりしたい場合， spec を用いる方法があります．しかし，この方法は必ずしも便利ではありません．

属性を削除することで， AttributeError を発生させ，アクセスを "妨げる" ようになります．

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

Mock の名前と name 属性

"name" は Mock コンストラクタの引数なので、モックオブジェクトが "name" 属性を持つことを望む場合、単に生成時にそれを渡すことはできません。2つの選択肢があります。1つのオプションは configure_mock() を使用することです:

>>> mock = MagicMock()
>>> mock.configure_mock(name='my_name')
>>> mock.name
'my_name'

より単純なオプションはモックの生成後に単に "name" 属性をセットすることです:

>>> mock = MagicMock()
>>> mock.name = "foo"

属性として設定されるモック

属性 (もしくは戻り値) に他のモックを設定した場合、このモックは "子" になります。この子に対する呼び出しは、親の method_calls や mock_calls に記録されます。これは、子のモックを構成し、親にそのモックを設定する際に有用です。また、親に対して設定したすべての子の呼び出しを記録するため、それらの間の順番を確認する際にも有用です:

>>> 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)]

モックが名前をもつ場合は、例外的に扱われます。何らかの理由で "子守り" が発生してほしくないときに、それを防ぐことができます。

>>> 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
[]

patch() を用いて作成したモックには、自動的に名前が与えられます。名前を持つモックを設定したい場合には、親に対して attach_mock() メソッドを呼び出します:

>>> 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')]

[1]

例外は特殊メソッドと属性だけです (これらは2つのアンダースコアで開始・終了します)。モックはこれらの代わりに AttributeError を発生させます。これは、インタープリタが暗黙的にこれらのメソッドを要求するためであり、特殊メソッドを予測する際に 非常に 混乱してしまいます。もし特殊メソッドのサポートが必要な場合は、 magic methods を参照してください。

patcher

patch デコレータは、その関数のスコープ内でパッチを適用するオブジェクトに対して使用されます。たとえ例外が発生したとしても、パッチは自動的に解除されます。これらすべての機能は文やクラスのデコレータとしても使用できます。

patch

注釈

重要なのは正しい名前空間に対して patch することです。 where to patch セクションを参照してください。

unittest.mock.patch(target, new=DEFAULT, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs)

patch() は関数デコレータ、クラスデコレータ、コンテキストマネージャーとして利用できます。関数や with 文の body では、 target は new オブジェクトにパッチされます。関数/with 文が終了すると、パッチは元に戻されます。

If new is omitted, then the target is replaced with an AsyncMock if the patched object is an async function or a MagicMock otherwise. If patch() is used as a decorator and new is omitted, the created mock is passed in as an extra argument to the decorated function. If patch() is used as a context manager the created mock is returned by the context manager.

target は 'package.module.ClassName' の形式の文字列でなければなりません。 target はインポートされ、指定されたオブジェクトが new オブジェクトに置き換えられます。なので、 target は patch() を呼び出した環境からインポート可能でなければなりません。 target がインポートされるのは、デコレートした時ではなく、デコレートされた関数が呼び出された時です。

patch が MagicMock を生成する場合、 spec と spec_set キーワード引数は MagicMock に渡されます。

加えて、 spec=True もしくは spec_set=True を渡すことで、モック対象のオブジェクトが spec/spec_set に渡されます。

new_callable allows you to specify a different class, or callable object, that will be called to create the new object. By default AsyncMock is used for async functions and MagicMock for the rest.

より強力な spec の形は autospec です。 autospec=True を指定した場合、 mock は置換対象となるオブジェクトから得られる spec で生成されます。 mock のすべての属性もまた置換対象となるオブジェクトの属性に応じた spec を持ちます。 mock されたメソッドや関数は引数をチェックし、間違ったシグネチャで呼び出された場合は TypeError を発生させます。クラスを置き換える mock の場合、その戻り値 (つまりインスタンス) はそのクラスと同じ spec を持ちます。 create_autospec() 関数と autospec を使う を参照してください。

置換対象ではなく任意のオブジェクトを spec として使うために、 autospec=True の代わりに、 autospec=some_object と指定することができます。

By default patch() will fail to replace attributes that don't exist. If you pass in create=True, and the attribute doesn't exist, patch will create the attribute for you when the patched function is called, and delete it again after the patched function has exited. This is useful for writing tests against attributes that your production code creates at runtime. It is off by default because it can be dangerous. With it switched on you can write passing tests against APIs that don't actually exist!

注釈

バージョン 3.5 で変更: モジュールのビルトインにパッチを当てようとしているなら、 create=True を渡す必要はありません。それはデフォルトで追加されます。

patch は TestCase のクラスデコレータとして利用できます。この場合そのクラスの各テストメソッドをデコレートします。これによりテストメソッドが同じ patch を共有している場合に退屈なコードを減らすことができます。 patch() は patch.TEST_PREFIX で始まるメソッド名のメソッドを探します。デフォルトではこれは 'test' で、 unittest がテストを探す方法とマッチしています。 patch.TEST_PREFIX を設定することで異なる prefix を指定することもできます。

patch は with 文を使ってコンテキストマネージャーとして使うこともできます。その場合パッチは with 文のブロック内でのみ適用されます。 "as" を使って、 "as" に続いて指定した変数にパッチされたオブジェクトが代入されます。これは patch() が mock オブジェクトを生成するときに便利です。

patch() takes arbitrary keyword arguments. These will be passed to AsyncMock if the patched object is asynchronous, to MagicMock otherwise or to new_callable if specified.

異なるユースケースのために、 patch.dict(...), patch.multiple(...), patch.object(...) が用意されています。

patch() を関数デコレータとして利用し、 mock を生成してそれをデコレートされた関数に渡します:

>>> @patch('__main__.SomeClass')
... def function(normal_argument, mock_class):
...     print(mock_class is SomeClass)
...
>>> function(None)
True

クラスをパッチするとそのクラスを MagicMock の インスタンス に置き換えます。テスト中のコードからそのクラスがインスタンス化される場合、 mock の return_value が利用されます。

クラスが複数回インスタンス化される場合、 side_effect を利用して毎回新しい mock を返すようにできます。もしくは、 return_value に、何でも好きなものを設定できます。

パッチしたクラスの インスタンス のメソッドの戻り値をカスタマイズしたい場合、 return_value に対して設定しなければなりません。例:

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

spec か spec_set を指定し、 patch() が クラス を置換するとき、生成された mock の戻り値は同じ spec を持ちます。:

>>> Original = Class
>>> patcher = patch('__main__.Class', spec=True)
>>> MockClass = patcher.start()
>>> instance = MockClass()
>>> assert isinstance(instance, Original)
>>> patcher.stop()

new_callable 引数は、デフォルトの MagicMock の代わりに別のクラスをモックとして生成したい場合に便利です。例えば、 NonCallableMock を利用したい場合:

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

別のユースケースとしては、オブジェクトを io.StringIO インスタンスで置き換えることがあります:

>>> 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()

patch() に mock を生成させる場合、たいてい最初に必要なことはその mock をセットアップすることです。幾らかのセットアップは patch の呼び出しから行うことができます。任意のキーワード引数が、生成された mock の属性に設定されます:

>>> patcher = patch('__main__.thing', first='one', second='two')
>>> mock_thing = patcher.start()
>>> mock_thing.first
'one'
>>> mock_thing.second
'two'

生成された mock の属性のさらに属性、 return_value side_effect などもセットアップできます。これらはキーワード引数のシンタックスでは直接指定できませんが、それらをキーとする辞書を ** を使って patch() に渡すことができます:

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

By default, attempting to patch a function in a module (or a method or an attribute in a class) that does not exist will fail with AttributeError:

>>> @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'

but adding create=True in the call to patch() will make the previous example work as expected:

>>> @patch('sys.non_existing_attribute', 42, create=True)
... def test(mock_stdout):
...     assert sys.non_existing_attribute == 42
...
>>> test()

バージョン 3.8 で変更: patch() now returns an AsyncMock if the target is an async function.

patch.object

patch.object(target, attribute, new=DEFAULT, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs)

オブジェクト (target) の指定された名前のメンバー (attribute) を mock オブジェクトでパッチします。

patch.object() はデコレータ、クラスデコレータ、コンテキストマネージャーとして利用できます。引数の new, spec, create, spec_set, autospec, new_callable は patch() と同じ意味を持ちます。 patch() と同じく、 patch.object() も mock を生成するための任意のキーワード引数を受け取ります。

クラスデコレータとして利用する場合、 patch.object() は patch.TEST_PREFIX にしたがってラップするメソッドを選択します。

patch.object() の呼び出しには3引数の形式と2引数の形式があります。 3引数の場合、 patch 対象のオブジェクト、属性名、その属性を置き換えるオブジェクトを取ります。

2引数の形式では、置き換えるオブジェクトを省略し、生成された mock がデコレート対象となる関数に追加の引数として渡されます:

>>> @patch.object(SomeClass, 'class_method')
... def test(mock_method):
...     SomeClass.class_method(3)
...     mock_method.assert_called_with(3)
...
>>> test()

spec, create やその他の patch.object() の引数は patch() の引数と同じ意味を持ちます。

patch.dict

patch.dict(in_dict, values=(), clear=False, **kwargs)

辞書や辞書のようなオブジェクトにパッチし、テスト後に元の状態に戻します。

in_dict は辞書やその他のマップ型のコンテナです。マップ型の場合、最低限 get, set, del 操作とキーに対するイテレートをサポートしている必要があります。

in_dict に辞書を指定する文字列を渡した場合、それをインポートして取得します。

values は対象の辞書にセットする値を含む、辞書か (key, value) ペアの iterable です。

clear が true なら、新しい値が設定される前に辞書がクリアされます。

patch.dict() はまた、任意のキーワード引数を受け取って辞書に設定します。

バージョン 3.8 で変更: patch.dict() now returns the patched dictionary when used as a context manager.

patch.dict() can be used as a context manager, decorator or class decorator:

>>> foo = {}
>>> @patch.dict(foo, {'newkey': 'newvalue'})
... def test():
...     assert foo == {'newkey': 'newvalue'}
...
>>> test()
>>> assert foo == {}

When used as a class decorator patch.dict() honours patch.TEST_PREFIX (default to 'test') for choosing which methods to wrap:

>>> 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')

If you want to use a different prefix for your test, you can inform the patchers of the different prefix by setting patch.TEST_PREFIX. For more details about how to change the value of see TEST_PREFIX.

patch.dict() を使うと、辞書にメンバーを追加するか、または単にテストが辞書を変更して、その後テストが終了した時にその辞書が確実に復元されるようにすることができます。

>>> 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 == {}

>>> import os
>>> with patch.dict('os.environ', {'newkey': 'newvalue'}):
...     print(os.environ['newkey'])
...
newvalue
>>> assert 'newkey' not in os.environ

patch.dict() を呼び出すときにキーワード引数を使って辞書に値をセットすることができます。

>>> mymodule = MagicMock()
>>> mymodule.function.return_value = 'fish'
>>> with patch.dict('sys.modules', mymodule=mymodule):
...     import mymodule
...     mymodule.function('some', 'args')
...
'fish'

patch.dict() can be used with dictionary like objects that aren't actually dictionaries. At the very minimum they must support item getting, setting, deleting and either iteration or membership test. This corresponds to the magic methods __getitem__(), __setitem__(), __delitem__() and either __iter__() or __contains__().

>>> 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']

patch.multiple

patch.multiple(target, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs)

1回の呼び出しで複数のパッチを実行します。パッチ対象のオブジェクト (あるいはそのオブジェクトをインポートするための文字列) と、パッチ用のキーワード引数を取ります:

with patch.multiple(settings, FIRST_PATCH='one', SECOND_PATCH='two'):
    ...

patch.multiple() に mock を生成させたい場合、キーワード引数の値に DEFAULT を指定します。この場合生成されたモックはデコレート対象の関数にキーワード引数として渡され、コンテキストマネージャーとして patch.multiple() が利用された場合は辞書として返します。

patch.multiple() はデコレータ、クラスデコレータ、コンテキストマネージャーとして使えます。引数の spec, spec_set, create, autospec, new_callable は patch() の引数と同じ意味を持ちます。これらの引数は patch.multiple() によって適用される すべての パッチに対して適用されます。

クラスデコレータとして利用する場合、 patch.multiple() は patch.TEST_PREFIX にしたがってラップするメソッドを選択します。

patch.multiple() に mock を生成させたい場合、キーワード引数の値に DEFAULT を指定します。patch.multiple() をデコレータとして使った場合生成されたモックはデコレート対象の関数にキーワード引数として渡されます。:

>>> 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()

patch.multiple() は他の patch デコレータとネストして利用できますが、キーワード引数は patch() によって作られる通常の引数の 後ろ で受け取る必要があります:

>>> @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()

patch.multiple() がコンテキストマネージャーとして利用される場合、コンテキストマネージャーが返す値は、名前がキーで値が生成された mock となる辞書です:

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

patch のメソッド: start と stop

すべての patcher は start() と stop() メソッドを持ちます。これを使うと、 with 文やデコレータをネストさせずに、 setUp メソッドで複数のパッチをシンプルに適用させることができます。

これらのメソッドを使うには、 patch(), patch.object(), patch.dict() を通常の関数のように呼び出して、戻り値の patcher オブジェクトを保持します。その start() メソッドでパッチを適用し、 stop() メソッドで巻き戻すことができます。

patch() に mock を生成させる場合、 patcher.start の呼び出しの戻り値として mock を受け取れます。:

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

この方式の典型的なユースケースは、 TestCase の setUp メソッドで複数のパッチを行うことです:

>>> 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()

注意

この方式を使う場合、必ず stop メソッドを呼び出してパッチが解除する必要があります。 setUp の中で例外が発生した場合 tearDown が呼び出されないので、これは意外に面倒です。 unittest.TestCase.addCleanup() を使うと簡単にできます:

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

この方式を使うと patcher オブジェクトの参照を維持する必要がなくなるという特典も付きます。

patch.stopall() を利用してすべての start されたパッチを stop することもできます。

patch.stopall()

すべての有効なパッチを stop します。 start で開始したパッチしか stop しません。

ビルトインをパッチする

モジュール内の任意のビルトインに対してパッチを当てることができます。以下の例はビルトインの ord() を修正します:

>>> @patch('__main__.ord')
... def test(mock_ord):
...     mock_ord.return_value = 101
...     print(ord('c'))
...
>>> test()
101

TEST_PREFIX

すべての patcher はクラスデコレータとして利用できます。この場合、そのクラスのすべてのテストメソッドをラップします。 patcher は 'test' で始まる名前のメソッドをテストメソッドだと認識します。これはデフォルトで unittest.TestLoader がテストメソッドを見つける方法と同じです。

他の prefix を使う事もできます。その場合、 patcher にその prefix を patch.TEST_PREFIX に設定することで教えることができます:

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

patch デコレータをネストする

複数のパッチを行いたい場合、シンプルにデコレータを重ねることができます。

次のパターンのように patch デコレータを重ねることができます:

>>> @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')

デコレータは下から上へと適用されることに注意してください。これは Python がデコレータを適用する標準的な方法です。テスト関数に渡される生成された mock の順番もこれに一致します。

どこにパッチするか

patch() は (一時的に) ある 名前 が参照しているオブジェクトを別のものに変更することで適用されます。任意のオブジェクトには、それを参照するたくさんの名前が存在しえます。なので、必ずテスト対象のシステムが使っている名前に対して patch しなければなりません。

基本的な原則は、オブジェクトが ルックアップ されるところにパッチすることです。その場所はオブジェクトが定義されたところとは限りません。これを説明するためにいくつかの例を挙げます。

次のような構造を持ったプロジェクトをテストしようとしていると仮定してください:

a.py
    -> Defines SomeClass

b.py
    -> from a import SomeClass
    -> some_function instantiates SomeClass

いま、 some_function をテストしようとしていて、そのために SomeClass を patch() を使って mock しようとしています。モジュール b をインポートした時点で、 b は SomeClass を a からインポートしています。この状態で a.SomeClass を patch() を使って mock out してもテストには影響しません。モジュール b はすでに 本物の SomeClass への参照を持っていて、パッチの影響を受けないからです。

重要なのは、 SomeClass が使われている (もしくはルックアップされている) 場所にパッチすることです。この場合、 some_function はモジュール b の中にインポートされた SomeClass をルックアップしています。なのでパッチは次のようにしなければなりません:

@patch('b.SomeClass')

ですが、別のシナリオとして、module b が from a import SomeClass ではなく import a をしていて、 some_function が a.SomeClass を利用していたとします。どちらのインポートも一般的なものです。この場合、パッチしたいクラスはそのモジュールからルックアップされているので、 a.SomeClass をパッチする必要があります:

@patch('a.SomeClass')

デスクリプタやプロキシオブジェクトにパッチする

patch と patch.object はどちらも デスクリプタ (クラスメソッド、static メソッド、プロパティ) を正しく patch できます。デスクリプタに patch する場合、インスタンスではなく class にパッチする必要があります。これらはまた 幾らかの 属性アクセスをプロキシするオブジェクト、例えば django の setttings オブジェクト [https://web.archive.org/web/20200603181648/http://www.voidspace.org.uk/python/weblog/arch_d7_2010_12_04.shtml#e1198] に対しても機能します。

MagicMock と magic method のサポート

Magic Method をモックする

Mock supports mocking the Python protocol methods, also known as "magic methods". This allows mock objects to replace containers or other objects that implement Python protocols.

magic method は通常のメソッドとはルックアップ方法が異なるので [2], magic method のサポートは特別に実装されています。そのため、サポートされているのは特定の magic method のみです。ほとんど すべてのメソッドをサポートしていますが、足りないものを見つけたら私達に教えてください。

magic method を mock するには、対象の method に対して関数や mock のインスタンスをセットします。もし関数を使う場合、それは第一引数に self を取る 必要があります [3].

>>> def __str__(self):
...     return 'fooble'
...
>>> mock = Mock()
>>> mock.__str__ = __str__
>>> str(mock)
'fooble'

>>> mock = Mock()
>>> mock.__str__ = Mock()
>>> mock.__str__.return_value = 'fooble'
>>> str(mock)
'fooble'

>>> mock = Mock()
>>> mock.__iter__ = Mock(return_value=iter([]))
>>> list(mock)
[]

ユースケースの1つは with 文の中でコンテキストマネージャーとして使われるオブジェクトを mock することです。

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

magic method の呼び出しは method_calls に含まれませんが、 mock_calls には記録されます。

注釈

mock を生成するのに spec キーワード引数を使った場合、 spec に含まれない magic method を設定しようとすると AttributeError が発生します。

サポートしている magic method の完全なリスト:

__hash__, __sizeof__, __repr__, __str__

__dir__, __format__, __subclasses__

__round__, __floor__, __trunc__ と __ceil__

比較: __lt__, __gt__, __le__, __ge__, __eq__, __ne__

コンテナメソッド: __getitem__, __setitem__, __delitem__, __contains__, __len__, __iter__, __reversed__, __missing__

Context manager: __enter__, __exit__, __aenter__ and __aexit__

単項算術メソッド: __neg__, __pos__, __invert__

The numeric methods (including right hand and in-place variants): __add__, __sub__, __mul__, __matmul__, __truediv__, __floordiv__, __mod__, __divmod__, __lshift__, __rshift__, __and__, __xor__, __or__, and __pow__

算術変換メソッド: __complex__, __int__, __float__, __index__

デスクリプタメソッド: __get__, __set__, __delete__

pickle: __reduce__, __reduce_ex__, __getinitargs__, __getnewargs__, __getstate__, __setstate__

File system path representation: __fspath__

Asynchronous iteration methods: __aiter__ and __anext__

バージョン 3.8 で変更: Added support for os.PathLike.__fspath__().

バージョン 3.8 で変更: Added support for __aenter__, __aexit__, __aiter__ and __anext__.

以下のメソッドは存在しますが、mock が利用している、動的に設定不可能、その他の問題が発生する可能性があるなどの理由で サポートされていません:

__getattr__, __setattr__, __init__, __new__

__prepare__, __instancecheck__, __subclasscheck__, __del__

Magic Mock

MagicMock 系のクラスは2種類あります: MagicMock と NonCallableMagicMock です。

class unittest.mock.MagicMock(*args, **kw)

MagicMock is a subclass of Mock with default implementations of most of the magic methods. You can use MagicMock without having to configure the magic methods yourself.

コンストラクタの引数は Mock と同じ意味を持っています。

spec か spec_set 引数を利用した場合、 spec に存在する magic method のみ が生成されます。

class unittest.mock.NonCallableMagicMock(*args, **kw)

callable でないバージョンの MagicMock

コンストラクタの引数は MagicMock と同じ意味を持ちますが、 return_value と side_effect は callable でない mock では意味を持ちません。

MagicMock が magic method をセットアップするので、あとは通常の方法で構成したり利用したりできます:

>>> mock = MagicMock()
>>> mock[3] = 'fish'
>>> mock.__setitem__.assert_called_with(3, 'fish')
>>> mock.__getitem__.return_value = 'result'
>>> mock[2]
'result'

デフォルトでは、多くのプロトコルメソッドは特定の型の戻り値を要求されます。それらのメソッドではその型のデフォルトの戻り値がデフォルトの戻り値として設定されているので、戻り値に興味が有る場合以外は何もしなくても利用可能です。デフォルトの値を変更したい場合は手動で戻り値を設定可能です。

メソッドとそのデフォルト値:

__lt__: NotImplemented

__gt__: NotImplemented

__le__: NotImplemented

__ge__: NotImplemented

__int__: 1

__contains__: False

__len__: 0

__iter__: iter([])

__exit__: False

__aexit__: False

__complex__: 1j

__float__: 1.0

__bool__: True

__index__: 1

__hash__: mock のデフォルトの hash

__str__: mock のデフォルトの str

__sizeof__: mock のデフォルトの sizeof

例えば:

>>> mock = MagicMock()
>>> int(mock)
1
>>> len(mock)
0
>>> list(mock)
[]
>>> object() in mock
False

The two equality methods, __eq__() and __ne__(), are special. They do the default equality comparison on identity, using the side_effect attribute, unless you change their return value to return something else:

>>> MagicMock() == 3
False
>>> MagicMock() != 3
True
>>> mock = MagicMock()
>>> mock.__eq__.return_value = True
>>> mock == 3
True

MagicMock.__iter__() の return_value は任意の iterable で、イテレータである必要はありません:

>>> mock = MagicMock()
>>> mock.__iter__.return_value = ['a', 'b', 'c']
>>> list(mock)
['a', 'b', 'c']
>>> list(mock)
['a', 'b', 'c']

return_value が iterator であった場合、最初のイテレートでその iterator を消費してしまい、2回目以降のイテレートの結果が空になってしまいます:

>>> mock.__iter__.return_value = iter(['a', 'b', 'c'])
>>> list(mock)
['a', 'b', 'c']
>>> list(mock)
[]

MagicMock はいくつかの曖昧であったり時代遅れなものをのぞいて、対応している magic method を事前にセットアップします。自動でセットアップされていないものも必要なら手動でセットアップすることができます。

MagicMock がサポートしているもののデフォルトではセットアップしない magic method:

__subclasses__

__dir__

__format__

__get__, __set__, __delete__

__reversed__, __missing__

__reduce__, __reduce_ex__, __getinitargs__, __getnewargs__, __getstate__, __setstate__

__getformat__

[2]

Magic method はインスタンスではなくクラスからルックアップされるはずです。Python のバージョンによってこのルールが適用されるかどうかに違いがあります。サポートされているプロトコルメソッドは、サポートされているすべての Python のバージョンで動作するはずです。

[3]

関数はクラスまで hook しますが、各 Mock インスタンス間の独立性は保たれます。

ヘルパー

sentinel

unittest.mock.sentinel

sentinel オブジェクトはテストで必要なユニークなオブジェクトを簡単に提供します。

属性はアクセス時にオンデマンドで生成されます。同じ属性に複数回アクセスすると必ず同じオブジェクトが返されます。返されるオブジェクトは、テスト失敗のメッセージがわかりやすくなるように気が利いた repr を持ちます。

バージョン 3.7 で変更: The sentinel attributes now preserve their identity when they are copied or pickled.

特定のオブジェクトが他のメソッドに引数として渡されることをテストしたり、返されることをテストしたい場合があります。このテストのために名前がついた sentinel オブジェクトを作るのが一般的です。 sentinel はこのようなオブジェクトを生成し、同一性をテストするのに便利な方法を提供します。

次の例では、 method が sentinel.some_object を返すようにモンキーパッチしています:

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

DEFAULT

unittest.mock.DEFAULT

DEFAULT オブジェクトは事前に生成された sentinel (実際には sentinel.DEFAULT) オブジェクトです。 side_effect 関数が、通常の戻り値を使うことを示すために使います。

call

unittest.mock.call(*args, **kwargs)

call() は call_args, call_args_list, mock_calls, method_calls と比較してより下端に assert できるようにするためのヘルパーオブジェクトです。 call() は assert_has_calls() と組み合わせて使うこともできます。

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

call.call_list()

複数回の呼び出しを表す call オブジェクトに対して、 call_list() はすべての途中の呼び出しと最終の呼び出しを含むリストを返します。

call_list は特に "chained call" に対して assert するのに便利です。 "chained call" は1行のコードにおける複数の呼び出しです。この結果は mock の mock_calls に複数の call エントリとして格納されます。この call のシーケンスを手動で構築するのは退屈な作業になります。

call_list() は同じ chained call からその call のシーケンスを構築することができます:

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

call オブジェクトは、どう構築されたかによって、 (位置引数、キーワード引数) のタプルか、 (名前、位置引数、キーワード引数) のタプルになります。自分で call オブジェクトを構築するときはこれを意識する必要はありませんが、 Mock.call_args, Mock.call_args_list, Mock.mock_calls 属性の中の call オブジェクトを解析して個々の引数を解析することができます。

Mock.call_args と Mock.call_args_list の中の call オブジェクトは (位置引数, キーワード引数) のタプルで、 Mock.mock_calls の中の call オブジェクトや自分で構築したオブジェクトは (名前, 位置引数, キーワード引数) のタプルになります。

call オブジェクトの "タプル性" を使って、より複雑な内省とアサートを行うために各引数を取り出しすことができます。位置引数はタプル (位置引数が存在しない場合は空のタプル) で、キーワード引数は辞書になります:

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

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

create_autospec

unittest.mock.create_autospec(spec, spec_set=False, instance=False, **kwargs)

他のオブジェクトを spec として利用して mock オブジェクトを作ります。 mock の属性も、 spec オブジェクトの該当する属性を spec として利用します。

mock された関数やメソッドは、正しいシグネチャで呼び出されたことを確認するために引数をチェックします。

spec_set が True のとき、 spec オブジェクトにない属性をセットしようとすると AttributeError を発生させます。

spec にクラスが指定された場合、 mock の戻り値 (そのクラスのインスタンス) は同じ spec を持ちます。 instance=True を指定すると、インスタンスオブジェクトの spec としてクラスを利用できます。返される mock は、モックのインスタンスが callable な場合にだけ callable となります。

create_autospec() は任意のキーワード引数を受け取り、生成する mock のコンストラクタに渡します。

create_autospec() や、 patch() の autospec 引数で autospec を使うサンプルは autospec を使う を参照してください。

バージョン 3.8 で変更: create_autospec() now returns an AsyncMock if the target is an async function.

ANY

unittest.mock.ANY

mock の呼び出しのうち 幾つか の引数に対して assert したいけれども、それ以外の引数は気にしない、あるいは call_args から個別に取り出してより高度な assert を行いたい場合があります。

特定の引数を無視するために、 すべて と等しくなるオブジェクトを使うことができます。そうすると、 assert_called_with() と assert_called_once_with() は、実際の引数が何であったかに関わらず成功します。

>>> mock = Mock(return_value=None)
>>> mock('foo', bar=object())
>>> mock.assert_called_once_with('foo', bar=ANY)

mock_calls などの call list との比較に ANY を使うこともできます:

>>> m = MagicMock(return_value=None)
>>> m(1)
>>> m(1, 2)
>>> m(object())
>>> m.mock_calls == [call(1), call(1, 2), ANY]
True

ANY is not limited to comparisons with call objects and so can also be used in test assertions:

class TestStringMethods(unittest.TestCase):

    def test_split(self):
        s = 'hello world'
        self.assertEqual(s.split(), ['hello', ANY])

FILTER_DIR

unittest.mock.FILTER_DIR

FILTER_DIR は mock オブジェクトが dir() に何を返すかを制御するためのモジュールレベル変数です。デフォルトは True で、以下に示すフィルタリングを行い、有用なメンバーだけを表示します。このフィルタリングが嫌な場合や、何かの診断のためにフィルタリングを切りたい場合は、 mock.FILTER_DIR = False と設定してください。

フィルタリングが有効な場合、 dir(some_mock) は有用な属性だけを表示し、また通常は表示されない動的に生成される属性も表示します。 mock が spec を使って(もちろん autospec でも)生成された場合、元のオブジェクトのすべての属性が、まだアクセスされていなかったとしても、表示されます。

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

多くのあまり有用ではない (mock 対象のものではなく、 Mock 自身のプライベートな) 属性は、アンダースコアと2つのアンダースコアで prefix された属性は Mock に対して dir() した結果からフィルタリングされます。この動作が嫌な場合は、モジュールレベルの FILTER_DIR スイッチを設定することでフィルターを切ることができます。

>>> 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__',
 ...

Alternatively you can just use vars(my_mock) (instance members) and dir(type(my_mock)) (type members) to bypass the filtering irrespective of mock.FILTER_DIR.

mock_open

unittest.mock.mock_open(mock=None, read_data=None)

open() の利用を置き換えるための mock を作るヘルパー関数。 open() を直接呼んだりコンテキストマネージャーとして利用する場合に使うことができます。

mock 引数は構成する mock オブジェクトです。 None (デフォルト) なら、通常のファイルハンドルと同じ属性やメソッドにAPIが制限された MagicMock が生成されます。

read_data は、ファイルハンドルの read(), readline(), そして readlines() のメソッドが返す文字列です。これらのメソッドを呼び出すと、読み出し終わるまで read_data からデータが読み出されます。これらモックのメソッドはとても単純化されています: mock が呼ばれるたびに read_data は先頭に巻き戻されます。テストコードに与えるデータをさらにコントロールするには自分自身でモックをカスタマイズする必要があります。それでも不十分な場合は、 PyPI [https://pypi.org] にあるインメモリファイルシステムパッケージのうちのどれかを使えば、テストのための本物のファイルシステムが得られるでしょう。

バージョン 3.4 で変更: readline() および readlines() のサポートが追加されました。 read() のモックは、個々の呼び出しで read_data を返すのではなく、それを消費するように変わりました。

バージョン 3.5 で変更: read_data は mock を呼び出す度に毎回リセットされるようになりました。

バージョン 3.8 で変更: Added __iter__() to implementation so that iteration (such as in for loops) correctly consumes read_data.

open() をコンテキストマネージャーとして使う方法は、ファイルが必ず適切に閉じられるようにする素晴らしい方法で、今では一般的になっています:

with open('/some/path', 'w') as f:
    f.write('something')

The issue is that even if you mock out the call to open() it is the returned object that is used as a context manager (and has __enter__() and __exit__() called).

コンテキストマネージャーを MagicMock でモックするのは一般的かつ面倒なので、ヘルパー関数を用意しています。:

>>> 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')

ファイルの読み込みをモックする例:

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

autospec を使う

autospec は mock の spec 機能を基盤にしています。 autospec は mock の API を元のオブジェクト (spec) に制限しますが、再帰的に適用される (lazy に実装されている) ので、 mock の属性も spec の属性と同じ API だけを持つようになります。さらに、 mock された関数/メソッドは元と同じシグネチャを持ち、正しくない引数で呼び出されると TypeError を発生させます。

autospec の動作について説明する前に、それが必要となる背景から説明していきます。

Mock は非常に強力で柔軟なオブジェクトですが、テスト対象のシステムをモックアウトするときに2つの欠点があります。 1つ目の欠点は Mock の API に関したもので、もう一つは mock オブジェクトを使う場合のもっと一般的な問題です。

まず Mock 独自の問題から解説します。 Mock は便利な2つのメソッド、 assert_called_with() と assert_called_once_with() を持っています。

>>> mock = Mock(name='Thing', return_value=None)
>>> mock(1, 2, 3)
>>> mock.assert_called_once_with(1, 2, 3)
>>> mock(1, 2, 3)
>>> mock.assert_called_once_with(1, 2, 3)
Traceback (most recent call last):
 ...
AssertionError: Expected 'mock' to be called once. Called 2 times.

mock が属性をオンデマンドに自動生成し、それを任意の引数で呼び出せるため、それらの assert メソッドのいずれかをミススペルするとその assert の効果が消えてしまいます:

>>> mock = Mock(name='Thing', return_value=None)
>>> mock(1, 2, 3)
>>> mock.assret_called_once_with(4, 5, 6)  # Intentional typo!

typo のために、テストは不正確に、かつ暗黙に成功してしまいます。

2つ目の問題はもっと一般的なものです。なにかのコードをリファクタし、メンバの名前を変更したとします。古いAPI を利用したコードに対するテストが、mock を利用しているとするとテストは通り続けます。このため、コードが壊れていてもテストがすべて通ってしまう可能性があります。

各ユニットが互いにどのように接続されるかをテストしない場合、依然としてテストで見つけることができるバグの余地が多く残っています。

mock はこの問題に対処するために spec と呼ばれる機能を提供しています。何かクラスかインスタンスを spec として mock に渡すと、実際のクラスに存在する属性にしか、 mock に対してもアクセスできなくなります:

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

spec はその mock 自体にしか適用されません。なので、同じ問題がその mock のすべてのメソッドに対して発生します:

>>> mock.has_data()
<mock.Mock object at 0x...>
>>> mock.has_data.assret_called_with()  # Intentional typo!

autospec はこの問題を解決します。 patch() か patch.object() に autospec=True を渡すか、 create_autospec() 関数を使って spec をもとに mock を作ることができます。 patch() の引数に autospec=True を渡した場合、置換対象のオブジェクトが spec オブジェクトとして利用されます。 spec は遅延処理される (mock の属性にアクセスされた時に spec が生成される) ので、非常に複雑だったり深くネストしたオブジェクト (例えばモジュールをインポートするモジュールをインポートするモジュール) に対しても大きなパフォーマンスの問題なしに autospec を使うことができます。

autospec の利用例:

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

request.Request が spec を持っているのが分かります。 request.Request のコンストラクタは2つの引数を持っています (片方は self です)。コンストラクタを間違って呼び出した時に何が起こるでしょうか:

>>> req = request.Request()
Traceback (most recent call last):
 ...
TypeError: <lambda>() takes at least 2 arguments (1 given)

spec はクラスがインスタンス化されたとき (つまり spec が適用された mock の戻り値) にも適用されます:

>>> req = request.Request('foo')
>>> req
<NonCallableMagicMock name='request.Request()' spec='Request' id='...'>

Request オブジェクトは callable ではないので、 request.Request の mock から返されたインスタンスの mock は callable ではなくなります。 spec があれば、 assert のミススペルは正しいエラーを発生させます:

>>> 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')

多くの場合、単に既存の patch() 呼び出しに autospec=True を加えるだけで、ミススペルやAPI変更に伴うバグから守られます。

patch() を経由する以外にも、 create_autospec() を使って autospec が適用された mock を直接作る方法もあります:

>>> from urllib import request
>>> mock_request = create_autospec(request)
>>> mock_request.Request('foo', 'bar')
<NonCallableMagicMock name='mock.Request()' spec='Request' id='...'>

とはいえ、autospec には注意しなければならない点や制限があり、そのためデフォルトでは無効になっています。spec オブジェクトでどんな属性が使えるかどうかを調べるために、autospec は spec オブジェクトをイントロスペクト (実際に属性にアクセスする) 必要があります。mock の属性を利用するとき、水面下で元のオブジェクトに対しても同じ属性の探索が行われます。spec したオブジェクトのどれかがコードを実行するプロパティやデスクリプタを持っている場合、autospec は正しく動きません。もしくは、イントロスペクションしても安全なようにオブジェクトを設計するのがよいでしょう [4]。

A more serious problem is that it is common for instance attributes to be created in the __init__() method and not to exist on the class at all. autospec can't know about any dynamically created attributes and restricts the api to visible attributes.

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

この問題を解決するためにいくつかの方法があります。一番簡単な、ただし一番面倒でないとは限らない方法は、必要とされる属性を mock が生成された後に設定することです。 autospec は属性を参照することを禁止しますが、設定することは禁止していません:

>>> with patch('__main__.Something', autospec=True):
...   thing = Something()
...   thing.a = 33
...

spec と autospec にはよりアグレッシブなバージョンがあり、存在しない属性への設定も禁止します。これはコードが正しい属性にのみ代入することを保証したいときに便利ですが、もちろん先ほどの方法も制限されてしまいます:

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

Probably the best way of solving the problem is to add class attributes as default values for instance members initialised in __init__(). Note that if you are only setting default attributes in __init__() then providing them via class attributes (shared between instances of course) is faster too. e.g.

class Something:
    a = 33

クラス属性を使ってもまた別の問題があります。メンバーのデフォルト値に None を利用し、後から別の型のオブジェクトを代入するのは比較的よくあるパターンです。 spec として None を使うと すべての 属性やメソッドへのアクセスも許されなくなるので使い物になりません。 None を spec にすることが有用な場面は 決して なく、おそらくそのメンバーは他の何かの型のメンバーになることを示すので、 autospec は None に設定されているメンバーには spec を使いません。その属性は通常の mock (MagicMocks) になります。

>>> class Something:
...     member = None
...
>>> mock = create_autospec(Something)
>>> mock.member.foo.bar.baz()
<MagicMock name='mock.member.foo.bar.baz()' id='...'>

すでに利用されているクラスにデフォルト値属性を追加するのが嫌な場合は、他の選択肢もあります。選択肢の1つは、クラスではなくインスタンスを spec に使うことです。別の選択肢は、実際のクラスのサブクラスを作り、実際に利用されている方に影響を与えずにデフォルト値属性を追加することです。どちらの方法も spec として代替オブジェクトを利用することが必要です。 patch() はこれをサポートしていて、 autospec 引数に代替オブジェクトを渡すことができます:

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

[4]

これはクラスやすでにインスタンス化されたオブジェクトにだけ当てはまります。 mock されたクラスを呼び出して mock インスタンスを作っても、実際のオブジェクトのインスタンスは生成されません。 mock は属性を - dir() を呼び出して - 検索するだけです。

Sealing mocks

unittest.mock.seal(mock)

Seal will disable the automatic creation of mocks when accessing an attribute of the mock being sealed or any of its attributes that are already mocks recursively.

If a mock instance with a name or a spec is assigned to an attribute it won't be considered in the sealing chain. This allows one to prevent seal from fixing part of the mock object.

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

Added in version 3.7.

Order of precedence of side_effect, return_value and wraps

The order of their precedence is:

side_effect

return_value

wraps

If all three are set, mock will return the value from side_effect, ignoring return_value and the wrapped object altogether. If any two are set, the one with the higher precedence will return the value. Regardless of the order of which was set first, the order of precedence remains unchanged.

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

As None is the default value of side_effect, if you reassign its value back to None, the order of precedence will be checked between return_value and the wrapped object, ignoring side_effect.

>>> order_mock.get_value.side_effect = None
>>> order_mock.get_value()
'second'

If the value being returned by side_effect is DEFAULT, it is ignored and the order of precedence moves to the successor to obtain the value to return.

>>> from unittest.mock import DEFAULT
>>> order_mock.get_value.side_effect = [DEFAULT]
>>> order_mock.get_value()
'second'

When Mock wraps an object, the default value of return_value will be DEFAULT.

>>> order_mock = Mock(spec=Order, wraps=Order)
>>> order_mock.return_value
sentinel.DEFAULT
>>> order_mock.get_value.return_value
sentinel.DEFAULT

The order of precedence will ignore this value and it will move to the last successor which is the wrapped object.

As the real call is being made to the wrapped object, creating an instance of this mock will return the real instance of the class. The positional arguments, if any, required by the wrapped object must be passed.

>>> order_mock_instance = order_mock()
>>> isinstance(order_mock_instance, Order)
True
>>> order_mock_instance.get_value()
'third'

>>> order_mock.get_value.return_value = DEFAULT
>>> order_mock.get_value()
'third'

>>> order_mock.get_value.return_value = "second"
>>> order_mock.get_value()
'second'

But if you assign None to it, this will not be ignored as it is an explicit assignment. So, the order of precedence will not move to the wrapped object.

>>> order_mock.get_value.return_value = None
>>> order_mock.get_value() is None
True

Even if you set all three at once when initializing the mock, the order of precedence remains the same:

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

If side_effect is exhausted, the order of precedence will not cause a value to be obtained from the successors. Instead, StopIteration exception is raised.

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

>>> order_mock.get_value()
'first side effect value'
>>> order_mock.get_value()
'another side effect value'

>>> order_mock.get_value()
Traceback (most recent call last):
 ...
StopIteration

unittest.mock --- getting started

Added in version 3.3.

Mock を使う

Mock のパッチ用メソッド

一般的な Mock の使い方の中には次のものがあります:

メソッドにパッチを当てる

オブジェクトに対するメソッド呼び出しを記録する

システムの他の部分からメソッドが正しい引数で呼び出されたかどうかを確認するために、そのオブジェクトのメソッドを置き換えることができます:

>>> real = SomeClass()
>>> real.method = MagicMock(name='method')
>>> real.method(3, 4, 5, key='value')
<MagicMock name='method()' id='...'>

モック(上の例では real.method)が利用された場合、どう使われたかを assert できるようにする属性やメソッドがモックにあります。

注釈

この例のような場合、たいてい Mock と MagicMock は互換です。 MagicMock の方が強力なので、デフォルトではこちらを使うといいでしょう。

モックが呼び出されると、その called 属性が True に設定されます。そして assert_called_with() や assert_called_once_with() メソッドを使ってそのメソッドが正しい引数で呼び出されたかどうかをチェックできます。

次の例では ProductionClass().method が something メソッドを呼び出したことをテストしています:

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

オブジェクトのメソッド呼び出しに対するモック

上の例ではオブジェクトのメソッドに対して直接パッチを当てて、それが正しく呼び出されていたかどうかをテストしていました。もう一つのよくあるユースケースが、モックをメソッド (またはテスト対象のシステムのどこか) に渡して、それが正しく利用されたかどうかをチェックする方法です。

次の例で、ProductionClass は closer メソッドを持っています。このメソッドは渡されたオブジェクトの close メソッドを呼び出します。

>>> class ProductionClass:
...     def closer(self, something):
...         something.close()
...

ですからこれをテストするには、close メソッドを持ったオブジェクトを渡して、それが正しく呼び出されたかどうかをテストしなければなりません。

>>> real = ProductionClass()
>>> mock = Mock()
>>> real.closer(mock)
>>> mock.close.assert_called_with()

モックに close メソッドを持たせるために何か準備する必要はありません。 close メソッドにアクセスすると自動的にそれが作られます。なので、もし close が呼び出されなかったとしてもテスト時に生成されるのですが、 assert_called_with() が failure 例外を発生させます。

クラスをモックする

他のよくあるユースケースが、テスト対象のコードによってインスタンス化されているクラスをモックに置き換えることです。クラスに patch すると、そのクラスがモックに置き換えられます。インスタンスは クラスを呼び出した時に 作られます。なので、モックの戻り値を使うことで、「モックのインスタンス」にアクセスできます。

次の例では、 some_function という関数が Foo をインスタンス化し、その method を呼び出しています。 patch() を呼び出すと Foo クラスをモックに置き換えます。 Foo のインスタンスはモックを呼び出して作られるので、モックの return_value を変更することでカスタマイズできます。:

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

モックに名前をつける

モックに名前をつけると便利なことがあります。その名前はモックを repr したときに表示されるので、モックがテスト失敗のメッセージ内に現れた時に便利です。また、モックの名前はそのモックの属性やメソッドにも伝播します:

>>> mock = MagicMock(name='foo')
>>> mock
<MagicMock name='foo' id='...'>
>>> mock.method
<MagicMock name='foo.method' id='...'>

全ての呼び出しのトラッキング

メソッドの複数回の呼び出しをトラックしたいことがあります。 mock_calls 属性は、そのモックの子属性やさらにその子孫に対する呼び出しすべてを記録しています。

>>> 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)]

mock_calls に対して assert すると、予期していないメソッド呼び出しがあったときにその assert が失敗します。これはあるメソッド呼び出しが期待通りに実行されたかどうかだけでなく、その呼び出し順序や期待した以外の呼び出しが起こらなかったことまでテストできるので便利です:

mock_calls と比較するリストを作るために call オブジェクトを利用できます:

>>> expected = [call.method(), call.attribute.method(10, x=53)]
>>> mock.mock_calls == expected
True

However, parameters to calls that return mocks are not recorded, which means it is not possible to track nested calls where the parameters used to create ancestors are important:

>>> m = Mock()
>>> m.factory(important=True).deliver()
<Mock name='mock.factory().deliver()' id='...'>
>>> m.mock_calls[-1] == call.factory(important=False).deliver()
True

戻り値や属性を設定する

モックオブジェクトに戻り値を設定するのはとっても簡単です:

>>> mock = Mock()
>>> mock.return_value = 3
>>> mock()
3

もちろん同じことがモックのメソッドに対しても行えます:

>>> mock = Mock()
>>> mock.method.return_value = 3
>>> mock.method()
3

コンストラクターで戻り値を設定することもできます:

>>> mock = Mock(return_value=3)
>>> mock()
3

モックに属性を設定したかったら、普通に設定するだけです:

>>> mock = Mock()
>>> mock.x = 3
>>> mock.x
3

mock.connection.cursor().execute("SELECT 1") のような複雑なケースでモックを使いたい場合もあります。この呼出があるリストを返すようにしたい場合、このネストした呼び出しを構成しなければなりません。

call を使って "chained call" 内の呼び出しを構成して、 assert で使うことができます:

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

call object を chained call を表す list にするために .call_list() を使います。

モックから例外を発生させる

side_effect という便利な属性があります。この属性に例外クラスやそのインスタンスを設定すると、モックが呼ばれた時にその例外を発生させます。

>>> mock = Mock(side_effect=Exception('Boom!'))
>>> mock()
Traceback (most recent call last):
  ...
Exception: Boom!

side_effect の関数と iterable

side_effect には関数や iterable を設定することもできます。side_effect に iterable を設定するユースケースは、そのモックが複数回呼び出され、そのたびに違う値を返したい場合です。side_effect に iterable を設定すると、そのモックに対するすべての呼び出しは iterable の次の値を返します:

>>> mock = MagicMock(side_effect=[4, 5, 6])
>>> mock()
4
>>> mock()
5
>>> mock()
6

より高度なユースケースとして、mock が呼び出された時の引数によって戻り値を変化させたい場合は、side_effect に関数を設定することができます。その関数は mock と同じ引数で呼び出されます。その関数の戻り値がそのモック呼び出しの戻り値になります:

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

非同期イテレータをモックする

Python 3.8以降、AsyncMock と MagicMock は __aiter__ を通じて 非同期イテレータ (Asynchronous Iterator) のモックをサポートしています。__aiter__ の return_value 属性はイテレーションに使用される戻り値を設定するために使用できます。

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

非同期コンテキストマネージャをモックする

Python 3.8以降、AsyncMock と MagicMock は __aenter__ と __aexit__ を通じて 非同期コンテキストマネージャ (Asynchronous Context Manager) のモックをサポートしています。デフォルトでは、 __aenter__ と __aexit__ は非同期関数を返す AsyncMock インスタンスです。

>>> 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()

既存のオブジェクトから Mock を作る

mock を使いすぎることの問題の一つは、テストが実際のコードではなく mock の実装をテストするようになってしまうことです。some_method というメソッドを実装したクラスがあるとします。他のクラスをテストするときに、some_method を提供する mock を使います。最初のクラスをリファクタリングして some_method がなくなった時、コードは壊れているのにテストは通る状態になってしまいます

Mock は spec というキーワード引数で mock の定義となるオブジェクトを指定できます。定義オブジェクトに存在しないメソッドや属性にアクセスすると AttributeError を発生させます。定義となるクラスの実装を変更した場合、テストの中でそのクラスをインスタンス化させなくても、テストを失敗させる事ができます。

>>> mock = Mock(spec=SomeClass)
>>> mock.old_method()
Traceback (most recent call last):
   ...
AttributeError: object has no attribute 'old_method'

また、定義を指定することで、パラメータが位置引数と名前付き引数のどちらで渡されたかに関わらず、モックへの呼び出しをよりスマートに照合することができます。

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

このよりスマートなマッチングをモックのメソッド呼び出しにも適用したい場合は、auto-speccing を使用します。

任意の属性の参照だけでなく代入も禁止するより強い定義を利用したい場合は、spec の代わりに spec_set を使います。

Using side_effect to return per file content

mock_open() is used to patch open() method. side_effect can be used to return a new Mock object per call. This can be used to return different contents per file stored in a dictionary:

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"

patch デコレータ

注釈

patch() では探索される名前空間内のオブジェクトにパッチをあてることが重要です。通常は単純ですが、クイックガイドには どこにパッチするか を読んでください。

テストの中でクラス属性やモジュール属性、例えば組み込み関数や、テスト対象モジュールにあるインスタンス化されるクラスに対してパッチしたいことがあります。モジュールやクラスは実際はグローバルなので、パッチするときは必ずテスト後にパッチを解除しないと、そのパッチが永続化されて他のテストに影響を与え、解析しにくい問題になります。

mock はこのために3つの便利なデコレータを提供しています: patch(), patch.object(), patch.dict() です。patch はパッチ対象を指定する package.module.Class.attribute の形式の文字列を引数に取ります。オプションでその属性 (やクラスなど) を置き換えるオブジェクトを渡すことができます。 'patch.object' はオブジェクトとパッチしたい属性名、それにオプションで置き換えるオブジェクトを受け取ります。

patch.object:

>>> 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()

モジュール (builtins を含む) をパッチしようとする場合、 patch.object() の代わりに patch() を使用してください:

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

モジュール名は必要に応じて package.module のようにドットを含むことができます:

>>> @patch('package.module.ClassName.attribute', sentinel.attribute)
... def test():
...     from package.module import ClassName
...     assert ClassName.attribute == sentinel.attribute
...
>>> test()

テストメソッド自体をデコレートするのは良いパターンです:

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

Mock を使ってパッチしたい場合は、 patch() を1引数で (または patch.object() を2引数で) 使うことができます。mock が自動で生成され、テスト関数/メソッドに渡されます:

>>> 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()

次のパターンのように patch デコレータを重ねることができます:

>>> 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()

patch デコレータをネストした際、モックは (デコレータを適用する Python の通常の) 順に適用されます。つまり引数は下から上の順になり、よって上記の例では test_module.ClassName2 が先になります。

また、 patch.dict() を使うと、スコープ内だけで辞書に値を設定し、テスト終了時には元の状態に復元されます:

>>> foo = {'key': 'value'}
>>> original = foo.copy()
>>> with patch.dict(foo, {'newkey': 'newvalue'}, clear=True):
...     assert foo == {'newkey': 'newvalue'}
...
>>> assert foo == original

patch, patch.object, patch.dict は全てコンテキストマネージャーとしても利用できます。

patch() に mock を生成させる場合、その参照を with 文の as を使って受け取れます:

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

他の方法として、patch, patch.object, patch.dict はクラスデコレータとしても利用できます。その場合、"test" で始まる全てのメソッドにデコレータを適用するのと同じになります。

さらなる例

より高度なシナリオを想定した例をあげていきます。

chained call をモックする

chained call を mock するのは、一度 return_value 属性を理解してしまえば簡単です。mock が最初に呼ばれた時や、呼び出される前に return_value を参照した場合、新しい Mock が生成されます。

つまり、戻り値のオブジェクトがどう利用されたかは、return_value mock を調べれば分かります:

>>> mock = Mock()
>>> mock().foo(a=2, b=3)
<Mock name='mock().foo()' id='...'>
>>> mock.return_value.foo.assert_called_with(a=2, b=3)

これをもとに、mock を構成して chained call に対する assert を行うのは簡単です。もちろん、元のコードを最初からもっとテストしやすく書くという選択肢もありますが...

では、例として次のようなコードがあるとします:

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

BackendProvider はすでに十分テストされているとします。method() をどうテストしましょうか？特に、response オブジェクトを使う # more code の部分のコードをテストしたいとします。

この chained call はインスタンス属性を起点にしているので、 Something インスタンスの backend 属性に対してモンキーパッチすることができます。今回の場合だと、最後の start_call の呼び出しが返す値にだけ興味があるので、あまり多くの構成は必要ありません。このメソッドが返すのが 'file-like' オブジェクトだとしましょう。そうすると、 response オブジェクトは組み込みの open() を spec として利用できます。

これをするために、backend のモックとしてモックインスタンスを作成し、それに対するモックの response オブジェクトを作成します。最終的な start_call の返り値として response をセットすると、このようにすることができます:

mock_backend.get_endpoint.return_value.create_call.return_value.start_call.return_value = mock_response

これより少し良いやり方として、返り値を直接セットする configure_mock() メソッドを使用して次のようにすることができます:

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

これらによって「モックの backend」をその場で monkey patch して、実際の呼び出しを行うことができます:

>>> something.backend = mock_backend
>>> something.method()

mock_calls を使用すると、チェーンされた呼び出しを単一のアサーションでチェックすることができます。チェーンされた呼び出しは、1行のコードの中で行われる複数の呼び出しです。したがって、 mock_calls には複数のエントリーがあるでしょう。 call.call_list() を使用することで、この呼び出しのリストを作成することができます:

>>> chained = call.get_endpoint('foobar').create_call('spam', 'eggs').start_call()
>>> call_list = chained.call_list()
>>> assert mock_backend.mock_calls == call_list

部分的なモック

In some tests I wanted to mock out a call to datetime.date.today() to return a known date, but I didn't want to prevent the code under test from creating new date objects. Unfortunately datetime.date is written in C, and so I couldn't just monkey-patch out the static datetime.date.today() method.

私はこれを行う単純な方法を見つけました。それは、date クラスをモックで事実上ラップして、しかしコンストラクタの呼び出しを実際のクラスへと素通りさせる (そして、実際のインスタンスを返す) というものです。

The patch decorator is used here to mock out the date class in the module under test. The side_effect attribute on the mock date class is then set to a lambda function that returns a real date. When the mock date class is called a real date will be constructed and returned by side_effect.

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

グローバルに datetime.date にパッチするのではなく、それを使用するモジュールの中の date にパッチしていることに留意してください。どこにパッチするか を参照してください。

When date.today() is called a known date is returned, but calls to the date(...) constructor still return normal dates. Without this you can find yourself having to calculate an expected result using exactly the same algorithm as the code under test, which is a classic testing anti-pattern.

dateコンストラクタの呼び出しは、mock_date の属性(call_count とその仲間)に記録され、テストに役立つこともあります。

日付や他の組み込みクラスのモックに対処する別の方法は このブログエントリ [https://williambert.online/2011/07/how-to-unit-testing-in-django-with-mocking-and-patching/].で議論されています。

ジェネレータメソッドをモックする

Pythonのジェネレータは、反復処理された時に一連の値を返す yield 文を使用した関数やメソッドです [1]。

ジェネレータメソッド/関数はジェネレータオブジェクトを返すために呼び出されます。そしてこのジェネレータオブジェクトが反復処理されます。イテレーションのためのプロトコルメソッドは __iter__() なので、MagicMock を使ってこれをモックすることができます。

ここでは"iter"メソッドをジェネレータとして実装したクラスの例を紹介します:

>>> class Foo:
...     def iter(self):
...         for i in [1, 2, 3]:
...             yield i
...
>>> foo = Foo()
>>> list(foo.iter())
[1, 2, 3]

このクラス、特に "iter"メソッドをどのようにモックするのでしょうか。

(list の呼び出しの中での暗黙的な)イテレーションから返される値を設定するには、foo.iter() の呼び出しで返されるオブジェクトを設定する必要がある。

>>> mock_foo = MagicMock()
>>> mock_foo.iter.return_value = iter([1, 2, 3])
>>> list(mock_foo.iter())
[1, 2, 3]

[1]

ジェネレータ式やジェネレータのより`高度な使い方 <http://www.dabeaz.com/coroutines/index.html>`_ もありますが、ここではそれらについては触れません。ジェネレータとその強力さについての非常に良い紹介記事があります: Generator Tricks for Systems Programmers [http://www.dabeaz.com/generators/]。

同じパッチを全てのメソッドに適用する

複数のテストメソッドに複数のパッチを適用したい場合、当然のことながらすべてのメソッドにパッチデコレータを適用することになります。これは不要な繰り返しのように感じられます。代わりに、(あらゆる形態の):func:`patch`をクラスデコレータとして使用することができます。これはそのクラスのすべてのテストメソッドにパッチを適用します。テストメソッドは名前が ``test``で始まるメソッドで識別されます。

>>> @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'

パッチを管理する別の方法として、patch のメソッド: start と stop.を使用する方法があります。これらを使うと、パッチを setUp と``tearDown``メソッドに移すことができます。

>>> 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()

この方式を使う場合、必ず stop メソッドを呼び出してパッチが解除する必要があります。setUp の中で例外が発生した場合 tearDown が呼び出されないので、これは意外に面倒です。 unittest.TestCase.addCleanup() を使うと簡単にできます:

>>> 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()

Unboundメソッドをモックする

Whilst writing tests today I needed to patch an unbound method (patching the method on the class rather than on the instance). I needed self to be passed in as the first argument because I want to make asserts about which objects were calling this particular method. The issue is that you can't patch with a mock for this, because if you replace an unbound method with a mock it doesn't become a bound method when fetched from the instance, and so it doesn't get self passed in. The workaround is to patch the unbound method with a real function instead. The patch() decorator makes it so simple to patch out methods with a mock that having to create a real function becomes a nuisance.

If you pass autospec=True to patch then it does the patching with a real function object. This function object has the same signature as the one it is replacing, but delegates to a mock under the hood. You still get your mock auto-created in exactly the same way as before. What it means though, is that if you use it to patch out an unbound method on a class the mocked function will be turned into a bound method if it is fetched from an instance. It will have self passed in as the first argument, which is exactly what I wanted:

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

autospec=True を使用しない場合、束縛されていないメソッドは代わりにMockインスタンスでパッチされ、self で呼び出されることはありません。

モックで複数回の呼び出しをチェックする

モックには、モックオブジェクトがどのように使用されるかをアサートするための素晴らしいAPIがあります。

>>> mock = Mock()
>>> mock.foo_bar.return_value = None
>>> mock.foo_bar('baz', spam='eggs')
>>> mock.foo_bar.assert_called_with('baz', spam='eggs')

If your mock is only being called once you can use the assert_called_once_with() method that also asserts that the call_count is one.

>>> 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 to be called once. Called 2 times.

Both assert_called_with and assert_called_once_with make assertions about the most recent call. If your mock is going to be called several times, and you want to make assertions about all those calls you can use call_args_list:

>>> 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()]

call ヘルパーを使えば、これらの呼び出しについて簡単にアサートすることができます。予想される呼び出しのリストを作成し、それを``call_args_list``と比較することができます。これは``call_args_list``のreprと驚くほど似ています:

>>> expected = [call(1, 2, 3), call(4, 5, 6), call()]
>>> mock.call_args_list == expected
True

ミュータブルな引数に対処する

稀ではありますが、問題となることがあるのはミュータブルな引数でモックが呼び出された場合です。call_args や``call_args_list`` は引数への*参照*を保存します。もしテスト対象のコードによって引数が変更されてしまうと、モックが呼び出された時の値をアサートすることはできなくなります。

この問題を示すサンプルコードを示します。

def frob(val):
    pass

def grob(val):
    "First frob and then clear val"
    frob(val)
    val.clear()

grob が``frob``を正しい引数で呼び出していることをテストしようとすると何が起こるか見てみましょう:

>>> 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(),), {})

一つの選択肢は、あなたが渡す引数をモックがコピーすることです。この方法は、オブジェクトidの同一性に依存したアサーションを行う場合に問題を引き起こす可能性があります。

Here's one solution that uses the side_effect functionality. If you provide a side_effect function for a mock then side_effect will be called with the same args as the mock. This gives us an opportunity to copy the arguments and store them for later assertions. In this example I'm using another mock to store the arguments so that I can use the mock methods for doing the assertion. Again a helper function sets this up for me.

>>> 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})

copy_call_args は、テストで呼び出されるモックとともに呼び出されます。この関数はアサーションで使用するための新しいモックを返します。side_effect 関数は引数のコピーを作成し、そのコピーを使って new_mock を呼び出します。

注釈

もしモックが一度しか使われないのであれば、呼び出された時点で引数をチェックする簡単な方法があります。単純に``side_effect``関数の中でチェックを行えばいいのです。

>>> def side_effect(arg):
...     assert arg == {6}
...
>>> mock = Mock(side_effect=side_effect)
>>> mock({6})
>>> mock(set())
Traceback (most recent call last):
    ...
AssertionError

別の方法としては、（ copy.deepcopy() を使用して）引数をコピーする、 Mock や MagicMock のサブクラスを作成する方法があります。以下に実装例を示します。

>>> 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: mock({1})
Actual call: mock(set())
>>> c.foo
<CopyingMock name='mock.foo' id='...'>

When you subclass Mock or MagicMock all dynamically created attributes, and the return_value will use your subclass automatically. That means all children of a CopyingMock will also have the type CopyingMock.

patch をネストする

Using patch as a context manager is nice, but if you do multiple patches you can end up with nested with statements indenting further and further to the right:

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

With unittest cleanup functions and the patch のメソッド: start と stop we can achieve the same effect without the nested indentation. A simple helper method, create_patch, puts the patch in place and returns the created mock for us:

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

MagicMock で辞書をモックする

You may want to mock a dictionary, or other container object, recording all access to it whilst having it still behave like a dictionary.

We can do this with MagicMock, which will behave like a dictionary, and using side_effect to delegate dictionary access to a real underlying dictionary that is under our control.

When the __getitem__() and __setitem__() methods of our MagicMock are called (normal dictionary access) then side_effect is called with the key (and in the case of __setitem__ the value too). We can also control what is returned.

After the MagicMock has been used we can use attributes like call_args_list to assert about how the dictionary was used:

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

注釈

An alternative to using MagicMock is to use Mock and only provide the magic methods you specifically want:

>>> mock = Mock()
>>> mock.__getitem__ = Mock(side_effect=getitem)
>>> mock.__setitem__ = Mock(side_effect=setitem)

A third option is to use MagicMock but passing in dict as the spec (or spec_set) argument so that the MagicMock created only has dictionary magic methods available:

>>> mock = MagicMock(spec_set=dict)
>>> mock.__getitem__.side_effect = getitem
>>> mock.__setitem__.side_effect = setitem

With these side effect functions in place, the mock will behave like a normal dictionary but recording the access. It even raises a KeyError if you try to access a key that doesn't exist.

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

After it has been used you can make assertions about the access using the normal mock methods and attributes:

>>> 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'}

Mock のサブクラスと属性

There are various reasons why you might want to subclass Mock. One reason might be to add helper methods. Here's a silly 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

The standard behaviour for Mock instances is that attributes and the return value mocks are of the same type as the mock they are accessed on. This ensures that Mock attributes are Mocks and MagicMock attributes are MagicMocks [2]. So if you're subclassing to add helper methods then they'll also be available on the attributes and return value mock of instances of your subclass.

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

Sometimes this is inconvenient. For example, one user [https://code.google.com/archive/p/mock/issues/105] is subclassing mock to created a Twisted adaptor [https://twisted.org/documents/11.0.0/api/twisted.python.components.html]. Having this applied to attributes too actually causes errors.

Mock (in all its flavours) uses a method called _get_child_mock to create these "sub-mocks" for attributes and return values. You can prevent your subclass being used for attributes by overriding this method. The signature is that it takes arbitrary keyword arguments (**kwargs) which are then passed onto the mock constructor:

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

[2]

An exception to this rule are the non-callable mocks. Attributes use the callable variant because otherwise non-callable mocks couldn't have callable methods.

patch.dict で import をモックする

One situation where mocking can be hard is where you have a local import inside a function. These are harder to mock because they aren't using an object from the module namespace that we can patch out.

Generally local imports are to be avoided. They are sometimes done to prevent circular dependencies, for which there is usually a much better way to solve the problem (refactor the code) or to prevent "up front costs" by delaying the import. This can also be solved in better ways than an unconditional local import (store the module as a class or module attribute and only do the import on first use).

That aside there is a way to use mock to affect the results of an import. Importing fetches an object from the sys.modules dictionary. Note that it fetches an object, which need not be a module. Importing a module for the first time results in a module object being put in sys.modules, so usually when you import something you get a module back. This need not be the case however.

This means you can use patch.dict() to temporarily put a mock in place in sys.modules. Any imports whilst this patch is active will fetch the mock. When the patch is complete (the decorated function exits, the with statement body is complete or patcher.stop() is called) then whatever was there previously will be restored safely.

Here's an example that mocks out the 'fooble' module.

>>> 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()

As you can see the import fooble succeeds, but on exit there is no 'fooble' left in sys.modules.

This also works for the from module import name form:

>>> 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()

With slightly more work you can also mock package imports:

>>> 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()

Tracking order of calls and less verbose call assertions

The Mock class allows you to track the order of method calls on your mock objects through the method_calls attribute. This doesn't allow you to track the order of calls between separate mock objects, however we can use mock_calls to achieve the same effect.

Because mocks track calls to child mocks in mock_calls, and accessing an arbitrary attribute of a mock creates a child mock, we can create our separate mocks from a parent one. Calls to those child mock will then all be recorded, in order, in the mock_calls of the parent:

>>> manager = Mock()
>>> mock_foo = manager.foo
>>> mock_bar = manager.bar

>>> mock_foo.something()
<Mock name='mock.foo.something()' id='...'>
>>> mock_bar.other.thing()
<Mock name='mock.bar.other.thing()' id='...'>

>>> manager.mock_calls
[call.foo.something(), call.bar.other.thing()]

We can then assert about the calls, including the order, by comparing with the mock_calls attribute on the manager mock:

>>> expected_calls = [call.foo.something(), call.bar.other.thing()]
>>> manager.mock_calls == expected_calls
True

If patch is creating, and putting in place, your mocks then you can attach them to a manager mock using the attach_mock() method. After attaching calls will be recorded in mock_calls of the manager.

>>> 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()]

If many calls have been made, but you're only interested in a particular sequence of them then an alternative is to use the assert_has_calls() method. This takes a list of calls (constructed with the call object). If that sequence of calls are in mock_calls then the assert succeeds.

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

Even though the chained call m.one().two().three() aren't the only calls that have been made to the mock, the assert still succeeds.

Sometimes a mock may have several calls made to it, and you are only interested in asserting about some of those calls. You may not even care about the order. In this case you can pass any_order=True to assert_has_calls:

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

More complex argument matching

Using the same basic concept as ANY we can implement matchers to do more complex assertions on objects used as arguments to mocks.

Suppose we expect some object to be passed to a mock that by default compares equal based on object identity (which is the Python default for user defined classes). To use assert_called_with() we would need to pass in the exact same object. If we are only interested in some of the attributes of this object then we can create a matcher that will check these attributes for us.

You can see in this example how a 'standard' call to assert_called_with isn't sufficient:

>>> 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(<__main__.Foo object at 0x...>)
Actual call: call(<__main__.Foo object at 0x...>)

A comparison function for our Foo class might look something like this:

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

And a matcher object that can use comparison functions like this for its equality operation would look something like this:

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

全てをつなぎ合わせて:

>>> match_foo = Matcher(compare, Foo(1, 2))
>>> mock.assert_called_with(match_foo)

The Matcher is instantiated with our compare function and the Foo object we want to compare against. In assert_called_with the Matcher equality method will be called, which compares the object the mock was called with against the one we created our matcher with. If they match then assert_called_with passes, and if they don't an AssertionError is raised:

>>> 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...>,), {})

With a bit of tweaking you could have the comparison function raise the AssertionError directly and provide a more useful failure message.

As of version 1.5, the Python testing library PyHamcrest [https://pyhamcrest.readthedocs.io/] provides similar functionality, that may be useful here, in the form of its equality matcher (hamcrest.library.integration.match_equality [https://pyhamcrest.readthedocs.io/en/release-1.8/integration/#module-hamcrest.library.integration.match_equality]).

2to3 --- Python 2 から 3 への自動コード変換

2to3 は、 Python 2.x のソースコードを読み込み、一連の 変換プログラム (fixer) を適用して正しい Python 3.x のコードに変換する Python プログラムです。標準ライブラリはほとんど全てのコードを取り扱うのに十分な fixer を含んでいます。ただし 2to3 を構成している lib2to3 は柔軟かつ一般的なライブラリなので、 2to3 のために独自の fixer を書くこともできます。

バージョン 3.11 で非推奨、バージョン 3.13 で削除予定: The lib2to3 module was marked pending for deprecation in Python 3.9 (raising PendingDeprecationWarning on import) and fully deprecated in Python 3.11 (raising DeprecationWarning). The 2to3 tool is part of that. It will be removed in Python 3.13.

2to3 の使用

2to3 は大抵の場合、 Python インタープリターと共に、スクリプトとしてインストールされます。場所は、 Python のルートディレクトリにある、 Tools/scripts ディレクトリです。

2to3 に与える基本の引数は、変換対象のファイル、もしくは、ディレクトリのリストです。ディレクトリの場合は、 Python ソースコードを再帰的に探索します。

Python 2.x のサンプルコード、 example.py を示します:

def greet(name):
    print "Hello, {0}!".format(name)
print "What's your name?"
name = raw_input()
greet(name)

これは、コマンドラインから 2to3 を呼び出すことで、Python 3.x コードに変換されます:

$ 2to3 example.py

オリジナルのソースファイルに対する差分が表示されます。 2to3 は必要となる変更をソースファイルに書き込むこともできます (-n も与えたのでない限りオリジナルのバックアップも作成されます)。変更の書き戻しは -w フラグによって有効化されます:

$ 2to3 -w example.py

変換後、 example.py は以下のようになります:

def greet(name):
    print("Hello, {0}!".format(name))
print("What's your name?")
name = input()
greet(name)

変換処理を通じて、コメントと、インデントは保存されます。

デフォルトでは、 2to3 は一連の 事前定義された変換プログラム を実行します。 -l フラグは、利用可能な変換プログラムの一覧を表示します。 -f フラグにより、実行する変換プログラムを明示的に与えることもできます。同様に、 -x は変換プログラムを明示的に無効化します。下記の例では、 imports と has_key 変換プログラムだけを実行します:

$ 2to3 -f imports -f has_key example.py

このコマンドは apply 以外のすべての変換プログラムを実行します:

$ 2to3 -x apply example.py

いくつかの変換プログラムは 明示的、つまり、デフォルトでは実行されず、コマンドラインで実行するものとして列記する必要があります。デフォルトの変換プログラムに idioms 変換プログラムを追加して実行するには、下記のようにします:

$ 2to3 -f all -f idioms example.py

ここで、 all を指定することで、全てのデフォルトの変換プログラムを有効化できることに注意して下さい。

2to3 がソースコードに修正すべき点を見つけても、自動的には修正できない場合もあります。この場合、 2to3 はファイルの変更点の下に警告を表示します。 3.x に準拠したコードにするために、あなたはこの警告に対処しなくてはなりません。

2to3 は doctest の修正もできます。このモードを有効化するには -d フラグを指定して下さい。 doctest だけ が修正されることに注意して下さい。これは、モジュールが有効な Python コードであることを要求しないということでもあります。例えば、 reST ドキュメント中の doctest に似たサンプルコードなども、このオプションで修正することができます。

-v は、変換処理のより詳しい情報の出力を有効化します。

いくつかの print 文は関数呼び出しとしても文としても解析できるので、 2to3 は print 関数を含むファイルを常に読めるとは限りません。 2to3 は from __future__ import print_function コンパイラディレクティブが存在することを検出すると、内部の文法を変更して print() を関数として解釈するようになります。 -p フラグによって手動でこの変更を有効化することもできます。 print 文を変換済みのコードに対して変換プログラムを適用するには -p を使用してください。同様に、exec() を関数として解釈させるには -e を使用してください。

-o または --output-dir で処理結果の出力先ディレクトリを変更出来ます。入力ファイルを上書きしないならバックアップは意味をなさないので、オプション -n フラグが要ります。

Added in version 3.2.3: -o オプションが追加されました。

-W または --write-unchanged-files により、たとえファイルに変更が必要なくても常にファイルを出力するように 2to3 に指示することが出来ます。これは、 -o とともに使って、Python ソースツリー全体を変換して別のディレクトリに書き出す際に最も有用です。

Added in version 3.2.3: -W フラグが追加されました。

オプション --add-suffix で、全ての出力ファイル名に与えた文字列を追加します。これを指定するのであれば別名で書き出されるためバックアップは必要ないので、オプション -n フラグが要ります。例えば:

$ 2to3 -n -W --add-suffix=3 example.py

とすれば変換後ファイルは example.py3 として書き出されます。

Added in version 3.2.3: --add-suffix オプションが追加されました。

ひとつのディレクトリツリーからプロジェクト全体を変換したければこのように使います:

$ 2to3 --output-dir=python3-version/mycode -W -n python2-version/mycode

変換プログラム

コード変形の各ステップは変換プログラムに隠蔽されます。 2to3 -l コマンドは変換プログラムのリストを表示します。 上記 の通り、それぞれの変換プログラムを個別に有効化したり無効化したりすることができます。ここではそれらをさらに詳細に説明します。

apply

apply() の使用を削除します。例えば apply(function, *args, **kwargs) は function(*args, **kwargs) に変換されます。

asserts

廃止になった unittest メソッド名を新しい名前に置換します。

対象

変換先

failUnlessEqual(a, b)

assertEqual(a, b)

assertEquals(a, b)

assertEqual(a, b)

failIfEqual(a, b)

assertNotEqual(a, b)

assertNotEquals(a, b)

assertNotEqual(a, b)

failUnless(a)

assertTrue(a)

assert_(a)

assertTrue(a)

failIf(a)

assertFalse(a)

failUnlessRaises(exc, cal)

assertRaises(exc, cal)

failUnlessAlmostEqual(a, b)

assertAlmostEqual(a, b)

assertAlmostEquals(a, b)

assertAlmostEqual(a, b)

failIfAlmostEqual(a, b)

assertNotAlmostEqual(a, b)

assertNotAlmostEquals(a, b)

assertNotAlmostEqual(a, b)

basestring

basestring を str に変換します。

buffer

buffer を memoryview に変換します。 memoryview API は buffer と似ているものの厳密に同じではないので、この変換プログラムはオプションです。

dict

辞書をイテレートするメソッドを修正します。 dict.iteritems() は dict.items() に、 dict.iterkeys() は dict.keys() に、 dict.itervalues() は dict.values() に変換されます。同様に dict.viewitems(), dict.viewkeys() dict.viewvalues() はそれぞれ dict.items(), dict.keys(), dict.values() に変換されます。また、 list の呼び出しの中で dict.items(), dict.keys(), dict.values() を使用している場合はそれをラップします。

except

except X, T を except X as T に変換します。

exec

exec 文を exec() 関数に変換します。

execfile

execfile() の使用を削除します。 execfile() への引数は open(), compile(), exec() の呼び出しでラップされます。

exitfunc

sys.exitfunc への代入を atexit モジュールの使用に変更します。

filter

list 呼び出しの中で filter() を使用している部分をラップします。

funcattrs

名前が変更された関数の属性を修正します。例えば my_function.func_closure は my_function.__closure__ に変換されます。

future

from __future__ import new_feature 文を削除します。

getcwdu

os.getcwdu() を os.getcwd() に置き換えます。

has_key

dict.has_key(key) を key in dict に変更します。

idioms

このオプションの変換プログラムは、 Python コードをより Python らしい書き方にするいくつかの変形を行います。 type(x) is SomeClass や type(x) == SomeClass のような型の比較は isinstance(x, SomeClass) に変換されます。 while 1 は while True になります。また、適切な場所では sorted() が使われるようにします。例えば、このブロックは

L = list(some_iterable)
L.sort()

次のように変更されます

L = sorted(some_iterable)

import

暗黙の相対インポート (sibling imports) を検出して、明示的な相対インポート (relative imports) に変換します。

imports

標準ライブラリ中のモジュール名の変更を扱います。

imports2

標準ライブラリ中の別のモジュール名の変更を扱います。単に技術的な制約のために imports とは別になっています。

input

input(prompt) を eval(input(prompt)) に変換します。

intern

intern() を sys.intern() に変換します。

isinstance

isinstance() の第 2 引数の重複を修正します。例えば isinstance(x, (int, int)) は isinstance(x, int) に isinstance(x, (int, float, int)) は isinstance(x, (int, float)) に変換されます。

itertools_imports

itertools.ifilter(), itertools.izip(), itertools.imap() のインポートを削除します。また itertools.ifilterfalse() のインポートを itertools.filterfalse() に変換します。

itertools

itertools.ifilter(), itertools.izip(), itertools.imap() を使っている箇所を同等の組み込み関数で置き換えます。 itertools.ifilterfalse() は itertools.filterfalse() に変換されます。

long

long を int に変更します。

map

list 呼び出しの中の map() をラップします。また、 map(None, x) を list(x) に変換します。 from future_builtins import map を使うと、この変換プログラムを無効にできます。

metaclass

古いメタクラス構文 (クラス定義中の __metaclass__ = Meta) を、新しい構文 (class X(metaclass=Meta)) に変換します。

methodattrs

古いメソッドの属性名を修正します。例えば meth.im_func は meth.__func__ に変換されます。

ne

古い不等号の構文 <> を != に変換します。

next

イテレータの next() メソッドの使用を next() 関数に変換します。また next() メソッドを __next__() に変更します。

nonzero

__nonzero__() を __bool__() に変更します。

numliterals

8 進数リテラルを新しい構文に変換します。

operator

operator モジュール内のさまざまな関数呼び出しを、他の、しかし機能的には同等の関数呼び出しに変換します。必要に応じて、import collections.abc などの適切な import ステートメントが追加されます。以下のマッピングが行われます。

対象

変換先

operator.isCallable(obj)

callable(obj)

operator.sequenceIncludes(obj)

operator.contains(obj)

operator.isSequenceType(obj)

isinstance(obj, collections.abc.Sequence)

operator.isMappingType(obj)

isinstance(obj, collections.abc.Mapping)

operator.isNumberType(obj)

isinstance(obj, numbers.Number)

operator.repeat(obj, n)

operator.mul(obj, n)

operator.irepeat(obj, n)

operator.imul(obj, n)

paren

リスト内包表記で必要になる括弧を追加します。例えば [x for x in 1, 2] は [x for x in (1, 2)] になります。

print

print 文を print() 関数に変換します。

raise

raise E, V を raise E(V) に、raise E, V, T を raise E(V).with_traceback(T) に変換します。例外の代わりにタプルを使用することは 3.0 で削除されたので、E がタプルならこの変換は不正確になります。

raw_input

raw_input() を input() に変換します。

reduce

reduce() が functools.reduce() に移動されたことを扱います。

reload

reload() を importlib.reload() に変換します。

renames

sys.maxint を sys.maxsize に変更します。

repr

バッククォートを使った repr を repr() 関数に置き換えます。

set_literal

set コンストラクタの使用を set リテラルに置換します。この変換プログラムはオプションです。

standarderror

StandardError を Exception に変更します。

sys_exc

廃止された sys.exc_value, sys.exc_type, sys.exc_traceback の代わりに sys.exc_info() を使うように変更します。

throw

ジェネレータの throw() メソッドの API 変更を修正します。

tuple_params

関数定義における暗黙的なタプルパラメータの展開を取り除きます。この変換プログラムによって一時変数が追加されます。

types

types モジュールのいくつかのメンバオブジェクトが削除されたことによって壊れたコードを修正します。

unicode

unicode を str に変更します。

urllib

urllib と urllib2 が urllib パッケージに変更されたことを扱います。

ws_comma

コンマ区切りの要素から余計な空白を取り除きます。この変換プログラムはオプションです。

xrange

xrange() を range() に変更して、既存の range() 呼び出しを list でラップします。

xreadlines

for x in file.xreadlines() を for x in file に変更します。

zip

list 呼び出しの中で使われている zip() をラップします。これは from future_builtins import zip が見つかった場合は無効にされます。

lib2to3 --- 2to3's library

ソースコード: Lib/lib2to3/ [https://github.com/python/cpython/tree/3.12/Lib/lib2to3/]

バージョン 3.11 で非推奨、バージョン 3.13 で削除予定: Python 3.9 switched to a PEG parser (see PEP 617 [https://peps.python.org/pep-0617/]) while lib2to3 is using a less flexible LL(1) parser. Python 3.10 includes new language syntax that is not parsable by lib2to3's LL(1) parser (see PEP 634 [https://peps.python.org/pep-0634/]). The lib2to3 module was marked pending for deprecation in Python 3.9 (raising PendingDeprecationWarning on import) and fully deprecated in Python 3.11 (raising DeprecationWarning). It will be removed from the standard library in Python 3.13. Consider third-party alternatives such as LibCST [https://libcst.readthedocs.io/] or parso [https://parso.readthedocs.io/].

注釈

lib2to3 API は安定しておらず、将来、劇的に変更されるかも知れないと考えるべきです。

test --- Regression tests package for Python

注釈

test パッケージは Python の内部利用専用です。ドキュメント化されているのは Python のコア開発者のためです。ここで述べられているコードは Python のリリースで予告なく変更されたり、削除される可能性があるため、Python 標準ライブラリー外でこのパッケージを使用することは推奨されません。

test パッケージには、Python 用の全ての回帰テストの他に、 test.support モジュールと test.regrtest モジュールが入っています。 test.support はテストを充実させるために使い、 test.regrtest はテストスイートを実行するのに使います。

test パッケージ内のモジュールのうち、名前が test_ で始まるものは、特定のモジュールや機能に対するテストスイートです。新しいテストはすべて unittest か doctest モジュールを使って書くようにしてください。古いテストのいくつかは、 sys.stdout への出力を比較する「従来の」テスト形式になっていますが、この形式のテストは廃止予定です。

参考

unittest モジュール

PyUnit 回帰テストを書く。

doctest モジュール

ドキュメンテーション文字列に埋め込まれたテスト。

test パッケージのためのユニットテストを書く

unittest モジュールを使ってテストを書く場合、幾つかのガイドラインに従うことが推奨されます。 1つは、テストモジュールの名前を、 test_ で始め、テスト対象となるモジュール名で終えることです。テストモジュール中のテストメソッドは名前を test_ で始めて、そのメソッドが何をテストしているかという説明で終えます。これはテスト実行プログラムが、そのメソッドをテストメソッドとして認識するために必要です。また、テストメソッドにはドキュメンテーション文字列を入れるべきではありません。コメント（例えば # True あるいは False だけを返すテスト関数 ）を使用して、テストメソッドのドキュメントを記述してください。これは、ドキュメンテーション文字列が存在する場合はその内容が出力されてしまうため、どのテストを実行しているのかをいちいち表示したくないからです。

以下のような決まり文句を使います:

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()

このコードのパターンを使うと test.regrtest からテストスイートを実行でき、 unittest のコマンドラインインターフェースをサポートしているスクリプトとして自分自身を起動したり、 python -m unittest というコマンドラインインターフェースを通して起動したりできます。

回帰テストの目的はコードを解き明かすことです。そのためには以下のいくつかのガイドラインに従ってください:

テストスイートから、すべてのクラス、関数および定数を実行するべきです。これには外部に公開される外部APIだけでなく「プライベートな」コードも含みます。

ホワイトボックス・テスト（対象のコードの詳細を元にテストを書くこと）を推奨します。ブラックボックス・テスト（公開されるインターフェース仕様だけをテストすること）は、すべての境界条件を確実にテストするには完全ではありません。

すべての取りうる値を、無効値も含めてテストするようにしてください。そのようなテストを書くことで、全ての有効値が通るだけでなく、不適切な値が正しく処理されることも確認できます。

コード内のできる限り多くのパスを網羅してください。分岐するように入力を調整したテストを書くことで、コードの多くのパスをたどることができます。

テスト対象のコードにバグが発見された場合は、明示的にテスト追加するようにしてください。そのようなテストを追加することで、将来コードを変更した際にエラーが再発することを防止できます。

テストの後始末 (例えば一時ファイルをすべて閉じたり削除したりすること) を必ず行ってください。

テストがオペレーティングシステムの特定の状況に依存する場合、テスト開始時に条件を満たしているかを検証してください。

インポートするモジュールをできるかぎり少なくし、可能な限り早期にインポートを行ってください。そうすることで、テストの外部依存性を最小限にし、モジュールのインポートによる副作用から生じる変則的な動作を最小限にできます。

できる限りテストコードを再利用するようにしましょう。時として、入力の違いだけを記述すれば良くなるくらい、テストコードを小さくすることができます。例えば以下のように、サブクラスで入力を指定することで、コードの重複を最小化することができます:

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)

When using this pattern, remember that all classes that inherit from unittest.TestCase are run as tests. The 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 unittest.TestCase.

参考

Test Driven Development

コードより前にテストを書く方法論に関する Kent Beck の著書。

コマンドラインインターフェースを利用してテストを実行する

test パッケージはスクリプトとして Python の回帰テストスイートを実行できます。 -m オプションを利用して、 python -m test.regrtest として実行します。この仕組みの内部では test.regrtest; を使っています; 古いバージョンの Python で使われている python -m test.regrtest という呼び出しは今でも上手く動きます。スクリプトを実行すると、自動的に test パッケージ内のすべての回帰テストを実行し始めます。パッケージ内の名前が test_ で始まる全モジュールを見つけ、それをインポートし、もしあるなら関数 test_main() を実行し、 test_main が無い場合は unittest.TestLoader.loadTestsFromModule からテストをロードしてテストを実行します。実行するテストの名前もスクリプトに渡される可能性があります。単一の回帰テストを指定 (python -m test test_spam) すると、出力を最小限にし、テストが成功したかあるいは失敗したかだけを出力します。

直接 test を実行すると、テストに利用するリソースを設定できます。これを行うには、 -u コマンドラインオプションを使います。 -u のオプションに all を指定すると、すべてのリソースを有効にします: python -m test -uall 。(よくある場合ですが) 何か一つを除く全てが必要な場合、カンマで区切った不要なリソースのリストを all の後に並べます。コマンド python -m test -uall,-audio,-largefile とすると、 audio と largefile リソースを除く全てのリソースを使って test を実行します。すべてのリソースのリストと追加のコマンドラインオプションを出力するには、 python -m test -h を実行してください。

テストを実行しようとするプラットフォームによっては、回帰テストを実行する別の方法があります。 Unix では、Python をビルドしたトップレベルディレクトリで make test を実行できます。 Windows上では、 PCbuild ディレクトリから rt.bat を実行すると、すべての回帰テストを実行します。

test.support --- テストのためのユーティリティ関数

test.support モジュールでは、 Python の回帰テストに対するサポートを提供しています。

注釈

test.support はパブリックなモジュールではありません。ここでドキュメント化されているのは Python 開発者がテストを書くのを助けるためです。このモジュールの API はリリース間で後方非互換な変更がなされる可能性があります。

このモジュールは次の例外を定義しています:

exception test.support.TestFailed

テストが失敗したとき送出される例外です。これは、 unittest ベースのテストでは廃止予定で、 unittest.TestCase の assertXXX メソッドが推奨されます。

exception test.support.ResourceDenied

unittest.SkipTest のサブクラスです。 (ネットワーク接続のような) リソースが利用できないとき送出されます。 requires() 関数によって送出されます。

test.support モジュールでは、以下の定数を定義しています:

test.support.verbose

冗長な出力が有効な場合は True です。実行中のテストについてのより詳細な情報が欲しいときにチェックします。 verbose は test.regrtest によって設定されます。

test.support.is_jython

実行中のインタプリタが Jython ならば True になります。

test.support.is_android

システムが Android の場合 True になります。

test.support.unix_shell

Windows 以外ではシェルのパスです; そうでない場合は None です。

test.support.LOOPBACK_TIMEOUT

Timeout in seconds for tests using a network server listening on the network local loopback interface like 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 connect(), recv() and send() methods of socket.socket.

デフォルト値は5秒です。

INTERNET_TIMEOUT も参照してください。

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 INTERNET_TIMEOUT should not mark a test as failed, but skip the test instead: see transient_internet().

デフォルト値は1分です。

LOOPBACK_TIMEOUT も参照してください。

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 --timeout command line option.

If a test using SHORT_TIMEOUT starts to fail randomly on slow buildbots, use LONG_TIMEOUT instead.

デフォルト値は30秒です。

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 --timeout command line option.

デフォルト値は5分です。

See also LOOPBACK_TIMEOUT, INTERNET_TIMEOUT and SHORT_TIMEOUT.

test.support.PGO

テストが PGO (Profile Guided Optimization) の役に立たないときにスキップできるなら設定します。

test.support.PIPE_MAX_SIZE

書き込みをブロックするための、基底にある OS のパイプバッファサイズより大きいであろう定数。

test.support.Py_DEBUG

True if Python was built with the Py_DEBUG macro defined, that is, if Python was built in debug mode.

Added in version 3.12.

test.support.SOCK_MAX_SIZE

書き込みをブロックするための、基底にある OS のソケットバッファサイズより大きいであろう定数。

test.support.TEST_SUPPORT_DIR

test.support を含んだトップディレクトリを設定します。

test.support.TEST_HOME_DIR

テストパッケージのトップディレクトリを設定します。

test.support.TEST_DATA_DIR

テストパッケージ内の data ディレクトリを設定します。

test.support.MAX_Py_ssize_t

大量のメモリを使うテストのための sys.maxsize を設定します。

test.support.max_memuse

大量のメモリを使うテストのためのメモリ上限となる set_memlimit() を設定します。 MAX_Py_ssize_t が設定上限です。

test.support.real_max_memuse

大量のメモリを使うテストのためのメモリ上限となる set_memlimit() を設定します。 MAX_Py_ssize_t の設定上限はありません。

test.support.MISSING_C_DOCSTRINGS

Set to True if Python is built without docstrings (the WITH_DOC_STRINGS macro is not defined). See the configure --without-doc-strings option.

See also the HAVE_DOCSTRINGS variable.

test.support.HAVE_DOCSTRINGS

Set to True if function docstrings are available. See the python -OO option, which strips docstrings of functions implemented in Python.

See also the MISSING_C_DOCSTRINGS variable.

test.support.TEST_HTTP_URL

ネットワークテスト専用の HTTP サーバーの URL を定義します。

test.support.ALWAYS_EQ

Object that is equal to anything. Used to test mixed type comparison.

test.support.NEVER_EQ

Object that is not equal to anything (even to ALWAYS_EQ). Used to test mixed type comparison.

test.support.LARGEST

Object that is greater than anything (except itself). Used to test mixed type comparison.

test.support.SMALLEST

Object that is less than anything (except itself). Used to test mixed type comparison.

test.support モジュールでは、以下の関数を定義しています:

test.support.busy_retry(timeout, err_msg=None, /, *, error=True)

Run the loop body until break stops the loop.

After timeout seconds, raise an AssertionError if error is true, or just stop the loop if error is false.

以下はプログラム例です:

for _ in support.busy_retry(support.SHORT_TIMEOUT):
    if check():
        break

Example of error=False usage:

for _ in support.busy_retry(support.SHORT_TIMEOUT, error=False):
    if check():
        break
else:
    raise RuntimeError('my custom error')

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 break stops the loop. Sleep at each loop iteration, but not at the first iteration. The sleep delay is doubled at each iteration (up to max_delay seconds).

See busy_retry() documentation for the parameters usage.

Example raising an exception after SHORT_TIMEOUT seconds:

for _ in support.sleeping_retry(support.SHORT_TIMEOUT):
    if check():
        break

Example of error=False usage:

for _ in support.sleeping_retry(support.SHORT_TIMEOUT, error=False):
    if check():
        break
else:
    raise RuntimeError('my custom error')

test.support.is_resource_enabled(resource)

resource が有効で利用可能ならば True を返します。利用可能なリソースのリストは、 test.regrtest がテストを実行している間のみ設定されます。

test.support.python_is_optimized()

Return True if Python was not built with -O0 or -Og.

test.support.with_pymalloc()

Return _testcapi.WITH_PYMALLOC.

test.support.requires(resource, msg=None)

resource が利用できなければ、 ResourceDenied を送出します。その場合、 msg は ResourceDenied の引数になります。 __name__ が '__main__' である関数にから呼び出された場合には常に True を返します。テストを test.regrtest から実行するときに使われます。

test.support.sortdict(dict)

Return a repr of dict with keys sorted.

test.support.findfile(filename, subdir=None)

filename という名前のファイルへのパスを返します。一致するものが見つからなければ、 filename 自体を返します。 filename 自体もファイルへのパスでありえるので、 filename が返っても失敗ではありません。

subdir を設定することで、パスのディレクトリを直接見に行くのではなく、相対パスを使って見付けにいくように指示できます。

test.support.get_pagesize()

Get size of a page in bytes.

Added in version 3.12.

test.support.setswitchinterval(interval)

Set the sys.setswitchinterval() to the given interval. Defines a minimum interval for Android systems to prevent the system from hanging.

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 True or False depending on the host platform. Example usage:

check_impl_detail()               # Only on CPython (default).
check_impl_detail(jython=True)    # Only on Jython.
check_impl_detail(cpython=False)  # Everywhere except CPython.

test.support.set_memlimit(limit)

Set the values for max_memuse and real_max_memuse for big memory tests.

test.support.record_original_stdout(stdout)

Store the value from stdout. It is meant to hold the stdout at the time the regrtest began.

test.support.get_original_stdout()

Return the original stdout set by record_original_stdout() or sys.stdout if it's not set.

test.support.args_from_interpreter_flags()

Return a list of command line arguments reproducing the current settings in sys.flags and sys.warnoptions.

test.support.optim_args_from_interpreter_flags()

Return a list of command line arguments reproducing the current optimization settings in sys.flags.

test.support.captured_stdin()

test.support.captured_stdout()

test.support.captured_stderr()

名前付きストリ－ムを io.StringIO オブジェクトで一時的に置き換えるコンテキストマネージャです。

出力ストリームの使用例:

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"

入力ストリ－ムの使用例:

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")

test.support.disable_faulthandler()

A context manager that temporary disables faulthandler.

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 __del__ methods may be called later than expected and weakrefs may remain alive for longer than expected.

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.

test.support.swap_attr(obj, attr, new_val)

Context manager to swap out an attribute with a new object.

使い方:

with swap_attr(obj, "attr", 5):
    ...

This will set obj.attr to 5 for the duration of the with block, restoring the old value at the end of the block. If attr doesn't exist on obj, it will be created and then deleted at the end of the block.

The old value (or None if it doesn't exist) will be assigned to the target of the "as" clause, if there is one.

test.support.swap_item(obj, attr, new_val)

Context manager to swap out an item with a new object.

使い方:

with swap_item(obj, "item", 5):
    ...

This will set obj["item"] to 5 for the duration of the with block, restoring the old value at the end of the block. If item doesn't exist on obj, it will be created and then deleted at the end of the block.

The old value (or None if it doesn't exist) will be assigned to the target of the "as" clause, if there is one.

test.support.flush_std_streams()

Call the flush() method on sys.stdout and then on sys.stderr. It can be used to make sure that the logs order is consistent before writing into stderr.

Added in version 3.11.

test.support.print_warning(msg)

Print a warning into sys.__stderr__. Format the message as: f"Warning -- {msg}". If msg is made of multiple lines, add "Warning -- " prefix to each line.

Added in version 3.9.

test.support.wait_process(pid, *, exitcode, timeout=None)

Wait until process pid completes and check that the process exit code is exitcode.

Raise an AssertionError if the process exit code is not equal to exitcode.

If the process runs longer than timeout seconds (SHORT_TIMEOUT by default), kill the process and raise an AssertionError. The timeout feature is not available on Windows.

Added in version 3.9.

test.support.calcobjsize(fmt)

Return the size of the PyObject whose structure members are defined by fmt. The returned value includes the size of the Python object header and alignment.

test.support.calcvobjsize(fmt)

Return the size of the PyVarObject whose structure members are defined by fmt. The returned value includes the size of the Python object header and alignment.

test.support.checksizeof(test, o, size)

For testcase test, assert that the sys.getsizeof for o plus the GC header size equals size.

@test.support.anticipate_failure(condition)

ある条件で unittest.expectedFailure() の印をテストに付けるデコレータ。このデコレータを使うときはいつも、関連する問題を指し示すコメントを付けておくべきです。

test.support.system_must_validate_cert(f)

A decorator that skips the decorated test on TLS certification validation failures.

@test.support.run_with_locale(catstr, *locales)

別のロケールで関数を実行し、完了したら適切に元の状態に戻すためのデコレータ。 catstr は (例えば "LC_ALL" のような) ロケールカテゴリを文字列で表したものです。渡された locales が順々に試され、一番最初に出てきた妥当なロケールが使われます。

@test.support.run_with_tz(tz)

A decorator for running a function in a specific timezone, correctly resetting it after it has finished.

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

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

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

@test.support.requires_IEEE_754

Decorator for skipping tests on non-IEEE 754 platforms.

@test.support.requires_zlib

Decorator for skipping tests if zlib doesn't exist.

@test.support.requires_gzip

Decorator for skipping tests if gzip doesn't exist.

@test.support.requires_bz2

Decorator for skipping tests if bz2 doesn't exist.

@test.support.requires_lzma

Decorator for skipping tests if lzma doesn't exist.

@test.support.requires_resource(resource)

Decorator for skipping tests if resource is not available.

@test.support.requires_docstrings

Decorator for only running the test if HAVE_DOCSTRINGS.

@test.support.requires_limited_api

Decorator for only running the test if Limited C API is available.

@test.support.cpython_only

Decorator for tests only applicable to CPython.

@test.support.impl_detail(msg=None, **guards)

Decorator for invoking check_impl_detail() on guards. If that returns False, then uses msg as the reason for skipping the test.

@test.support.no_tracing

Decorator to temporarily turn off tracing for the duration of the test.

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

@test.support.bigmemtest(size, memuse, dry_run=True)

Decorator for bigmem tests.

size is a requested size for the test (in arbitrary, test-interpreted units.) memuse is the number of bytes per unit for the test, or a good estimate of it. For example, a test that needs two byte buffers, of 4 GiB each, could be decorated with @bigmemtest(size=_4G, memuse=2).

The size argument is normally passed to the decorated test method as an extra argument. If dry_run is True, the value passed to the test method may be less than the requested value. If dry_run is False, it means the test doesn't support dummy runs when -M is not specified.

@test.support.bigaddrspacetest

Decorator for tests that fill the address space.

test.support.check_syntax_error(testcase, statement, errtext='', *, lineno=None, offset=None)

Test for syntax errors in statement by attempting to compile statement. testcase is the unittest instance for the test. errtext is the regular expression which should match the string representation of the raised SyntaxError. If lineno is not None, compares to the line of the exception. If offset is not None, compares to the offset of the exception.

test.support.open_urlresource(url, *args, **kw)

Open url. If open fails, raises TestFailed.

test.support.reap_children()

Use this at the end of 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.

test.support.get_attribute(obj, name)

Get an attribute, raising unittest.SkipTest if AttributeError is raised.

test.support.catch_unraisable_exception()

Context manager catching unraisable exception using sys.unraisablehook().

Storing the exception value (cm.unraisable.exc_value) creates a reference cycle. The reference cycle is broken explicitly when the context manager exits.

Storing the object (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.

使い方:

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)

Added in version 3.8.

test.support.load_package_tests(pkg_dir, loader, standard_tests, pattern)

Generic implementation of the unittest 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 load_tests. In simple cases, the test package's __init__.py can be the following:

import os
from test.support import load_package_tests

def load_tests(*args):
    return load_package_tests(os.path.dirname(__file__), *args)

test.support.detect_api_mismatch(ref_api, other_api, *, ignore=())

Returns the set of attributes, functions or methods of ref_api not found on other_api, except for a defined list of items to be ignored in this check specified in ignore.

By default this skips private attributes beginning with '_' but includes all magic methods, i.e. those starting and ending in '__'.

Added in version 3.5.

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.

test.support.run_in_subinterp(code)

Run code in subinterpreter. Raise unittest.SkipTest if tracemalloc is enabled.

test.support.check_free_after_iterating(test, iter, cls, args=())

Assert instances of cls are deallocated after iterating.

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 None when none is found missing.

test.support.check__all__(test_case, module, name_of_module=None, extra=(), not_exported=())

Assert that the __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 csv and its _csv).

The extra argument can be a set of names that wouldn't otherwise be automatically detected as "public", like objects without a proper __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.

使用例:

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)

Added in version 3.6.

test.support.skip_if_broken_multiprocessing_synchronize()

Skip tests if the multiprocessing.synchronize module is missing, if there is no available semaphore implementation, or if creating a lock raises an OSError.

Added in version 3.10.

test.support.check_disallow_instantiation(test_case, tp, *args, **kwds)

Assert that type tp cannot be instantiated using args and kwds.

Added in version 3.10.

test.support.adjust_int_max_str_digits(max_digits)

This function returns a context manager that will change the global sys.set_int_max_str_digits() setting for the duration of the context to allow execution of test code that needs a different limit on the number of digits when converting between an integer and string.

Added in version 3.11.

test.support モジュールでは、以下のクラスを定義しています:

class 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 [https://msdn.microsoft.com/en-us/library/windows/desktop/ms680621.aspx].

On UNIX, resource.setrlimit() is used to set resource.RLIMIT_CORE's soft limit to 0 to prevent coredump file creation.

On both platforms, the old value is restored by __exit__().

class test.support.SaveSignals

Class to save and restore signal handlers registered by the Python signal handler.

save(self)

Save the signal handlers to a dictionary mapping signal numbers to the current signal handler.

restore(self)

Set the signal numbers from the save() dictionary to the saved handler.

class test.support.Matcher

matches(self, d, **kwargs)

Try to match a single dict with the supplied arguments.

match_value(self, k, dv, v)

Try to match a single stored value (dv) with a supplied value (v).

test.support.socket_helper --- Utilities for socket tests

The test.support.socket_helper module provides support for socket tests.

Added in version 3.9.

test.support.socket_helper.IPV6_ENABLED

Set to True if IPv6 is enabled on this host, False otherwise.

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 sock parameter (default is AF_INET, SOCK_STREAM), and binding it to the specified host address (defaults to 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 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 -accept argument to openssl's s_server mode). Always prefer bind_port() over 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.

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 sock.family is AF_INET and sock.type is SOCK_STREAM, and the socket has SO_REUSEADDR or 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 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.

test.support.socket_helper.bind_unix_socket(sock, addr)

Bind a Unix socket, raising unittest.SkipTest if PermissionError is raised.

@test.support.socket_helper.skip_unless_bind_unix_socket

A decorator for running tests that require a functional bind() for Unix sockets.

test.support.socket_helper.transient_internet(resource_name, *, timeout=30.0, errnos=())

A context manager that raises ResourceDenied when various issues with the internet connection manifest themselves as exceptions.

test.support.script_helper --- Utilities for the Python execution tests

The test.support.script_helper module provides support for Python's script execution tests.

test.support.script_helper.interpreter_requires_environment()

Return True if sys.executable interpreter requires environment variables in order to be able to run at all.

This is designed to be used with @unittest.skipIf() to annotate tests that need to use an assert_python*() function to launch an isolated mode (-I) or no environment mode (-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 PYTHONHOME is one way to get most of the testsuite to run in that situation. PYTHONPATH or PYTHONUSERSITE are other common environment variables that might impact whether or not the interpreter can start.

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 __isolated, __cleanenv, __cwd, and TERM.

バージョン 3.9 で変更: The function no longer strips whitespaces from stderr.

test.support.script_helper.assert_python_ok(*args, **env_vars)

Assert that running the interpreter with args and optional environment variables env_vars succeeds (rc == 0) and return a (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 -I), except if the __isolated keyword-only parameter is set to False.

バージョン 3.9 で変更: The function no longer strips whitespaces from stderr.

test.support.script_helper.assert_python_failure(*args, **env_vars)

Assert that running the interpreter with args and optional environment variables env_vars fails (rc != 0) and return a (return code, stdout, stderr) tuple.

See assert_python_ok() for more options.

バージョン 3.9 で変更: The function no longer strips whitespaces from stderr.

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 subprocess.Popen(). Returns a subprocess.Popen object.

test.support.script_helper.kill_python(p)

Run the given subprocess.Popen process until completion and return stdout.

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 False, append .py to the name. Return the full script path.

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 zip which contains the files in script_name. name_in_zip is the archive name. Return a tuple containing (full path, full path of archive name).

test.support.script_helper.make_pkg(pkg_dir, init_source='')

Create a directory named pkg_dir containing an __init__ file with init_source as its contents.

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 __init__ file and a file script_basename containing the source. If compiled is 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.

test.support.bytecode_helper --- Support tools for testing correct bytecode generation

The test.support.bytecode_helper module provides support for testing and inspecting bytecode generation.

Added in version 3.9.

The module defines the following class:

class test.support.bytecode_helper.BytecodeTestCase(unittest.TestCase)

This class has custom assertion methods for inspecting bytecode.

BytecodeTestCase.get_disassembly_as_string(co)

Return the disassembly of co as string.

BytecodeTestCase.assertInBytecode(x, opname, argval=_UNSPECIFIED)

Return instr if opname is found, otherwise throws AssertionError.

BytecodeTestCase.assertNotInBytecode(x, opname, argval=_UNSPECIFIED)

Throws AssertionError if opname is found.

test.support.threading_helper --- Utilities for threading tests

The test.support.threading_helper module provides support for threading tests.

Added in version 3.10.

test.support.threading_helper.join_thread(thread, timeout=None)

Join a thread within timeout. Raise an AssertionError if thread is still alive after timeout seconds.

@test.support.threading_helper.reap_threads

Decorator to ensure the threads are cleaned up even if the test fails.

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 threading.Event.set(). start_threads will attempt to join the started threads upon exit.

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.

test.support.threading_helper.threading_setup()

Return current thread count and copy of dangling threads.

test.support.threading_helper.wait_threads_exit(timeout=None)

Context manager to wait until all threads created in the with statement exit.

test.support.threading_helper.catch_threading_exception()

Context manager catching threading.Thread exception using threading.excepthook().

Attributes set when an exception is caught:

exc_type

exc_value

exc_traceback

thread

See threading.excepthook() documentation.

These attributes are deleted at the context manager exit.

使い方:

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)

Added in version 3.8.

test.support.os_helper --- Utilities for os tests

The test.support.os_helper module provides support for os tests.

Added in version 3.10.

test.support.os_helper.FS_NONASCII

os.fsencode() でエンコードできる 非 ASCII 文字。

test.support.os_helper.SAVEDCWD

os.getcwd() に設定されます。

test.support.os_helper.TESTFN

テンポラリファイルの名前として安全に利用できる名前に設定されます。作成した一時ファイルは全て閉じ、unlink (削除) しなければなりません。

test.support.os_helper.TESTFN_NONASCII

Set to a filename containing the 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.

test.support.os_helper.TESTFN_UNENCODABLE

strictモードのファイルシステムエンコーディングでエンコードできないファイル名（str型）に設定します。そのようなファイル名を生成できない場合は、 None になる可能性があります。

test.support.os_helper.TESTFN_UNDECODABLE

strictモードのファイルシステムエンコーディングでデコードできないファイル名（bytes型）に設定します。そのようなファイル名を生成できない場合は、 None になる可能性があります。

test.support.os_helper.TESTFN_UNICODE

非 ASCII 名を一時ファイルに設定します。

class test.support.os_helper.EnvironmentVarGuard

一時的に環境変数をセット・アンセットするためのクラスです。このクラスのインスタンスはコンテキストマネージャーとして利用されます。また、 os.environ に対する参照・更新を行う完全な辞書のインターフェースを持ちます。コンテキストマネージャーが終了した時、このインスタンス経由で環境変数へ行った全ての変更はロールバックされます。

バージョン 3.1 で変更: 辞書のインターフェースを追加しました。

class test.support.os_helper.FakePath(path)

Simple path-like object. It implements the __fspath__() method which just returns the path argument. If path is an exception, it will be raised in __fspath__().

EnvironmentVarGuard.set(envvar, value)

一時的に、 envvar を value にセットします。

EnvironmentVarGuard.unset(envvar)

一時的に envvar をアンセットします。

test.support.os_helper.can_symlink()

OS がシンボリックリンクをサポートする場合 True を返し、その他の場合は False を返します。

test.support.os_helper.can_xattr()

Return True if the OS supports xattr, False otherwise.

test.support.os_helper.change_cwd(path, quiet=False)

カレントディレクトリを一時的に path に変更し与えるコンテキストマネージャです。

quiet が False の場合、コンテキストマネージャはエラーが起きると例外を送出します。それ以外の場合には、警告を出すだけでカレントディレクトリは同じままにしておきます。

test.support.os_helper.create_empty_file(filename)

Create an empty file with filename. If it already exists, truncate it.

test.support.os_helper.fd_count()

Count the number of open file descriptors.

test.support.os_helper.fs_is_case_insensitive(directory)

Return True if the file system for directory is case-insensitive.

test.support.os_helper.make_bad_fd()

一時ファイルを開いた後に閉じ、そのファイル記述子を返すことで無効な記述子を作成します。

test.support.os_helper.rmdir(filename)

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

test.support.os_helper.rmtree(path)

Call shutil.rmtree() on path or call os.lstat() and os.rmdir() to remove a path and its contents. As with rmdir(), on Windows platforms this is wrapped with a wait loop that checks for the existence of the files.

@test.support.os_helper.skip_unless_symlink

シンボリックリンクのサポートが必要なテストを実行することを表すデコレータ。

@test.support.os_helper.skip_unless_xattr

A decorator for running tests that require support for xattr.

test.support.os_helper.temp_cwd(name='tempcwd', quiet=False)

一時的に新しいディレクトリを作成し、カレントディレクトリ (current working directory, CWD) を変更するコンテキストマネージャです。

一時的にカレントディレクトリを変更する前に、カレントディレクトリに name という名前のディレクトリを作成します。 name が None の場合は、一時ディレクトリは tempfile.mkdtemp() を使って作成されます。

quiet が False でカレントディレクトリの作成や変更ができない場合、例外を送出します。それ以外の場合には、警告を出すだけで元のカレントディレクトリが使われます。

test.support.os_helper.temp_dir(path=None, quiet=False)

path に一時ディレクトリを作成し与えるコンテキストマネージャです。

If path is None, the temporary directory is created using tempfile.mkdtemp(). If quiet is False, the context manager raises an exception on error. Otherwise, if path is specified and cannot be created, only a warning is issued.

test.support.os_helper.temp_umask(umask)

一時的にプロセスの umask を設定するコンテキストマネージャ。

test.support.os_helper.unlink(filename)

Call os.unlink() on filename. As with rmdir(), on Windows platforms, this is wrapped with a wait loop that checks for the existence of the file.

test.support.import_helper --- Utilities for import tests

The test.support.import_helper module provides support for import tests.

Added in version 3.10.

test.support.import_helper.forget(module_name)

モジュール名 module_name を sys.modules から取り除き、モジュールのバイトコンパイル済みファイルを全て削除します。

test.support.import_helper.import_fresh_module(name, fresh=(), blocked=(), deprecated=False)

この関数は、 name で指定された Python モジュールを、インポート前に sys.modules から削除することで新規にインポートしてそのコピーを返します。 reload() 関数と違い、もとのモジュールはこの操作によって影響をうけません。

fresh は、同じようにインポート前に sys.modules から削除されるモジュール名の iterable です。

blocked もモジュール名のイテラブルで、インポート中にモジュールキャッシュ内でその名前を None に置き換えることで、そのモジュールをインポートしようとすると ImportError を発生させます。

指定されたモジュールと fresh や blocked 引数内のモジュール名はインポート前に保存され、フレッシュなインポートが完了したら sys.modules に戻されます。

deprecated が True の場合、インポート中はモジュールとパッケージの廃止メッセージが抑制されます。

指定したモジュールがインポートできなかった場合に、この関数は ImportError を送出します。

使用例:

# 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'])

Added in version 3.1.

test.support.import_helper.import_module(name, deprecated=False, *, required_on=())

この関数は name で指定されたモジュールをインポートして返します。通常のインポートと異なり、この関数はモジュールをインポートできなかった場合に unittest.SkipTest 例外を発生させます。

Module and package deprecation messages are suppressed during this import if deprecated is 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 sys.platform.

Added in version 3.1.

test.support.import_helper.modules_setup()

Return a copy of sys.modules.

test.support.import_helper.modules_cleanup(oldmodules)

Remove modules except for oldmodules and encodings in order to preserve internal cache.

test.support.import_helper.unload(name)

sys.modules から name を削除します。

test.support.import_helper.make_legacy_pyc(source)

Move a PEP 3147 [https://peps.python.org/pep-3147/]/PEP 488 [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.

class 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 DeprecationWarning on import. Example usage:

with CleanImport('foo'):
    importlib.import_module('foo')  # New reference.

class test.support.import_helper.DirsOnSysPath(*paths)

A context manager to temporarily add directories to sys.path.

This makes a copy of sys.path, appends any directories given as positional arguments, then reverts sys.path to the copied settings when the context ends.

Note that all sys.path modifications in the body of the context manager, including replacement of the object, will be reverted at the end of the block.

test.support.warnings_helper --- Utilities for warnings tests

The test.support.warnings_helper module provides support for warnings tests.

Added in version 3.10.

test.support.warnings_helper.ignore_warnings(*, category)

Suppress warnings that are instances of category, which must be Warning or a subclass. Roughly equivalent to warnings.catch_warnings() with warnings.simplefilter('ignore', category=category). For example:

@warning_helper.ignore_warnings(category=DeprecationWarning)
def test_suppress_warning():
    # do something

Added in version 3.8.

test.support.warnings_helper.check_no_resource_warning(testcase)

Context manager to check that no ResourceWarning was raised. You must remove the object which may emit ResourceWarning before the end of the context manager.

test.support.warnings_helper.check_syntax_warning(testcase, statement, errtext='', *, lineno=1, offset=None)

Test for syntax warning in statement by attempting to compile statement. Test also that the SyntaxWarning is emitted only once, and that it will be converted to a SyntaxError when turned into error. testcase is the unittest instance for the test. errtext is the regular expression which should match the string representation of the emitted SyntaxWarning and raised SyntaxError. If lineno is not None, compares to the line of the warning and exception. If offset is not None, compares to the offset of the exception.

Added in version 3.8.

test.support.warnings_helper.check_warnings(*filters, quiet=True)

warning が正しく発行されているかどうかチェックする、 warnings.catch_warnings() を使いやすくするラッパーです。これは、 warnings.simplefilter() を always に設定して、記録された結果を自動的に検証するオプションと共に warnings.catch_warnings(record=True) を呼ぶのとほぼ同じです。

check_warnings は ("message regexp", WarningCategory) の形をした 2要素タプルを位置引数として受け取ります。1つ以上の filters が与えられた場合や、オプションのキーワード引数 quiet が False の場合、警告が期待通りであるかどうかをチェックします。指定された各 filter は最低でも1回は囲われたコード内で発生した警告とマッチしなければテストが失敗しますし、指定されたどの filter ともマッチしない警告が発生してもテストが失敗します。前者のチェックを無効にするには、quiet を True にします。

引数が1つもない場合、デフォルトでは次のようになります:

check_warnings(("", Warning), quiet=True)

この場合、全ての警告は補足され、エラーは発生しません。

コンテキストマネージャーに入る時、 WarningRecorder インスタンスが返されます。このレコーダーオブジェクトの warnings 属性から、 catch_warnings() から得られる警告のリストを取得することができます。便利さのために、レコーダーオブジェクトから直接、一番最近に発生した警告を表すオブジェクトの属性にアクセスできます(以下にある例を参照してください)。警告が1つも発生しなかった場合、それらの全ての属性は None を返します。

レコーダーオブジェクトの reset() メソッドは警告リストをクリアします。

コンテキストマネージャーは次のようにして使います:

with check_warnings(("assertion is always true", SyntaxWarning),
                    ("", UserWarning)):
    exec('assert(False, "Hey!")')
    warnings.warn(UserWarning("Hide me!"))

この場合、どちらの警告も発生しなかった場合や、それ以外の警告が発生した場合は、 check_warnings() はエラーを発生させます。

警告が発生したかどうかだけでなく、もっと詳しいチェックが必要な場合は、次のようなコードになります:

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

全ての警告をキャプチャし、テストコードがその警告を直接テストします。

バージョン 3.2 で変更: 新しいオプション引数 filters と quiet

class test.support.warnings_helper.WarningsRecorder

ユニットテスト時に warning を記録するためのクラスです。上の、 check_warnings() のドキュメントを参照してください。

デバッグとプロファイル

ここに含まれるライブラリは Python での開発を手助けするものです。デバッガを使うと、コードのステップ実行や、スタックフレームの解析、ブレークポイントの設定などができます。プロファイラはコードを実行して実行時間の詳細を提供し、プログラムのボトルネックを特定できるようにします。

Audit events table

bdb --- Debugger framework

faulthandler --- Dump the Python traceback

tracebackのダンプ

フォールトハンドラの状態

タイムアウト後にtracebackをダンプする

ユーザシグナルに対してtracebackをダンプする

ファイル記述子の問題

使用例

pdb --- Python デバッガ

デバッガコマンド

Python プロファイラ

プロファイラとは

かんたんユーザマニュアル

リファレンスマニュアル -- profile と cProfile

Stats クラス

決定論的プロファイリングとは

制限事項

キャリブレーション (補正)

カスタムな時刻取得用関数を使う

timeit --- Measure execution time of small code snippets

基本的な例

Python インターフェイス

コマンドラインインターフェイス

使用例

trace --- Trace or track Python statement execution

コマンドラインからの使用

主要なオプション

修飾的オプション

フィルターオプション

プログラミングインターフェース

tracemalloc --- Trace memory allocations

使用例

上位10を表示する

差を計算する

メモリブロックのトレースバックを取得する

top を整形化する

Record the current and peak size of all traced memory blocks

API

関数

DomainFilter

Filter

Frame

Snapshot

Statistic

StatisticDiff

Trace

Traceback

Audit events table

This table contains all events raised by sys.audit() or PySys_Audit() calls throughout the CPython runtime and the standard library. These calls were added in 3.8 or later (see PEP 578 [https://peps.python.org/pep-0578/]).

See sys.addaudithook() and PySys_AddAuditHook() for information on handling these events.

CPython 実装の詳細: This table is generated from the CPython documentation, and may not represent events raised by other implementations. See your runtime specific documentation for actual events raised.

Audit event

Arguments

References

_thread.start_new_thread

function, args, kwargs

[1]

array.__new__

typecode, initializer

[1]

builtins.breakpoint

breakpointhook

[1]

builtins.id

id

[1]

builtins.input

prompt

[1]

builtins.input/result

result

[1]

code.__new__

code, filename, name, argcount, posonlyargcount, kwonlyargcount, nlocals, stacksize, flags

[1]

compile

source, filename

[1]

cpython.PyInterpreterState_Clear

[1]

cpython.PyInterpreterState_New

[1]

cpython._PySys_ClearAuditHooks

[1]

cpython.run_command

command

[1]

cpython.run_file

filename

[1]

cpython.run_interactivehook

hook

[1]

cpython.run_module

module-name

[1]

cpython.run_startup

filename

[1]

cpython.run_stdin

[1]

ctypes.addressof

obj

[1]

ctypes.call_function

func_pointer, arguments

[1]

ctypes.cdata

address

[1]

ctypes.cdata/buffer

pointer, size, offset

[1][2]

ctypes.create_string_buffer

init, size

[1]

ctypes.create_unicode_buffer

init, size

[1]

ctypes.dlopen

name

[1]

ctypes.dlsym

library, name

[1]

ctypes.dlsym/handle

handle, name

[1]

ctypes.get_errno

[1]

ctypes.get_last_error

[1]

ctypes.set_errno

errno

[1]

ctypes.set_exception

code

[1]

ctypes.set_last_error

error

[1]

ctypes.string_at

ptr, size

[1]

ctypes.wstring_at

ptr, size

[1]

ensurepip.bootstrap

root

[1]

exec

code_object

[1][2]

fcntl.fcntl

fd, cmd, arg

[1]

fcntl.flock

fd, operation

[1]

fcntl.ioctl

fd, request, arg

[1]

fcntl.lockf

fd, cmd, len, start, whence

[1]

ftplib.connect

self, host, port

[1]

ftplib.sendcmd

self, cmd

[1][2]

function.__new__

code

[1]

gc.get_objects

generation

[1]

gc.get_referents

objs

[1]

gc.get_referrers

objs

[1]

glob.glob

pathname, recursive

[1][2]

glob.glob/2

pathname, recursive, root_dir, dir_fd

[1][2]

http.client.connect

self, host, port

[1]

http.client.send

self, data

[1]

imaplib.open

self, host, port

[1]

imaplib.send

self, data

[1]

import

module, filename, sys.path, sys.meta_path, sys.path_hooks

[1]

marshal.dumps

value, version

[1]

marshal.load

[1]

marshal.loads

bytes

[1]

mmap.__new__

fileno, length, access, offset

[1]

msvcrt.get_osfhandle

fd

[1]

msvcrt.locking

fd, mode, nbytes

[1]

msvcrt.open_osfhandle

handle, flags

[1]

nntplib.connect

self, host, port

[1][2]

nntplib.putline

self, line

[1][2]

object.__delattr__

obj, name

[1]

object.__getattr__

obj, name

[1]

object.__setattr__

obj, name, value

[1]

open

path, mode, flags

[1][2][3]

os.add_dll_directory

path

[1]

os.chdir

path

[1][2]

os.chflags

path, flags

[1][2]

os.chmod

path, mode, dir_fd

[1][2][3]

os.chown

path, uid, gid, dir_fd

[1][2][3]

os.exec

path, args, env

[1]

os.fork

[1]

os.forkpty

[1]

os.fwalk

top, topdown, onerror, follow_symlinks, dir_fd

[1]

os.getxattr

path, attribute

[1]

os.kill

pid, sig

[1]

os.killpg

pgid, sig

[1]

os.link

src, dst, src_dir_fd, dst_dir_fd

[1]

os.listdir

path

[1]

os.listdrives

[1]

os.listmounts

volume

[1]

os.listvolumes

[1]

os.listxattr

path

[1]

os.lockf

fd, cmd, len

[1]

os.mkdir

path, mode, dir_fd

[1][2]

os.posix_spawn

path, argv, env

[1][2]

os.putenv

key, value

[1]

os.remove

path, dir_fd

[1][2][3]

os.removexattr

path, attribute

[1]

os.rename

src, dst, src_dir_fd, dst_dir_fd

[1][2][3]

os.rmdir

path, dir_fd

[1]

os.scandir

path

[1]

os.setxattr

path, attribute, value, flags

[1]

os.spawn

mode, path, args, env

[1]

os.startfile

path, operation

[1]

os.startfile/2

path, operation, arguments, cwd, show_cmd

[1]

os.symlink

src, dst, dir_fd

[1]

os.system

command

[1]

os.truncate

fd, length

[1][2]

os.unsetenv

key

[1]

os.utime

path, times, ns, dir_fd

[1]

os.walk

top, topdown, onerror, followlinks

[1]

pathlib.Path.glob

self, pattern

[1]

pathlib.Path.rglob

self, pattern

[1]

pdb.Pdb

[1]

pickle.find_class

module, name

[1]

poplib.connect

self, host, port

[1][2]

poplib.putline

self, line

[1][2]

pty.spawn

argv

[1]

resource.prlimit

pid, resource, limits

[1]

resource.setrlimit

resource, limits

[1]

setopencodehook

[1]

shutil.chown

path, user, group

[1]

shutil.copyfile

src, dst

[1][2][3]

shutil.copymode

src, dst

[1][2]

shutil.copystat

src, dst

[1][2]

shutil.copytree

src, dst

[1]

shutil.make_archive

base_name, format, root_dir, base_dir

[1]

shutil.move

src, dst

[1]

shutil.rmtree

path, dir_fd

[1]

shutil.unpack_archive

filename, extract_dir, format

[1]

signal.pthread_kill

thread_id, signalnum

[1]

smtplib.connect

self, host, port

[1]

smtplib.send

self, data

[1]

socket.__new__

self, family, type, protocol

[1]

socket.bind

self, address

[1]

socket.connect

self, address

[1][2]

socket.getaddrinfo

host, port, family, type, protocol

[1]

socket.gethostbyaddr

ip_address

[1]

socket.gethostbyname

hostname

[1][2]

socket.gethostname

[1]

socket.getnameinfo

sockaddr

[1]

socket.getservbyname

servicename, protocolname

[1]

socket.getservbyport

port, protocolname

[1]

socket.sendmsg

self, address

[1]

socket.sendto

self, address

[1]

socket.sethostname

name

[1]

sqlite3.connect

database

[1]

sqlite3.connect/handle

connection_handle

[1]

sqlite3.enable_load_extension

connection, enabled

[1]

sqlite3.load_extension

connection, path

[1]

subprocess.Popen

executable, args, cwd, env

[1]

sys._current_exceptions

[1]

sys._current_frames

[1]

sys._getframe

frame

[1]

sys._getframemodulename

depth

[1]

sys.addaudithook

[1][2]

sys.excepthook

hook, type, value, traceback

[1]

sys.set_asyncgen_hooks_finalizer

[1]

sys.set_asyncgen_hooks_firstiter

[1]

sys.setprofile

[1]

sys.settrace

[1]

sys.unraisablehook

hook, unraisable

[1]

syslog.closelog

[1]

syslog.openlog

ident, logoption, facility

[1]

syslog.setlogmask

maskpri

[1]

syslog.syslog

priority, message

[1]

telnetlib.Telnet.open

self, host, port

[1]

telnetlib.Telnet.write

self, buffer

[1]

tempfile.mkdtemp

fullpath

[1][2]

tempfile.mkstemp

fullpath

[1][2][3]

urllib.Request

fullurl, data, headers, method

[1]

webbrowser.open

url

[1]

winreg.ConnectRegistry

computer_name, key

[1]

winreg.CreateKey

key, sub_key, access

[1][2]

winreg.DeleteKey

key, sub_key, access

[1][2]

winreg.DeleteValue

key, value

[1]

winreg.DisableReflectionKey

key

[1]

winreg.EnableReflectionKey

key

[1]

winreg.EnumKey

key, index

[1]

winreg.EnumValue

key, index

[1]

winreg.ExpandEnvironmentStrings

str

[1]

winreg.LoadKey

key, sub_key, file_name

[1]

winreg.OpenKey

key, sub_key, access

[1]

winreg.OpenKey/result

key

[1][2][3]

winreg.PyHKEY.Detach

key

[1]

winreg.QueryInfoKey

key

[1]

winreg.QueryReflectionKey

key

[1]

winreg.QueryValue

key, sub_key, value_name

[1][2]

winreg.SaveKey

key, file_name

[1]

winreg.SetValue

key, sub_key, type, value

[1][2]

The following events are raised internally and do not correspond to any public API of CPython:

Audit event

引数

_winapi.CreateFile

file_name, desired_access, share_mode, creation_disposition, flags_and_attributes

_winapi.CreateJunction

src_path, dst_path

_winapi.CreateNamedPipe

name, open_mode, pipe_mode

_winapi.CreatePipe

_winapi.CreateProcess

application_name, command_line, current_directory

_winapi.OpenProcess

process_id, desired_access

_winapi.TerminateProcess

handle, exit_code

ctypes.PyObj_FromPtr

obj

bdb --- Debugger framework

ソースコード: Lib/bdb.py [https://github.com/python/cpython/tree/3.12/Lib/bdb.py]

bdb モジュールは、ブレークポイントを設定したり、デバッガー経由で実行を管理するような、基本的なデバッガー機能を提供します。

以下の例外が定義されています:

exception bdb.BdbQuit

Bdb クラスが、デバッガーを終了させるために投げる例外。

bdb モジュールは2つのクラスを定義しています:

class bdb.Breakpoint(self, file, line, temporary=False, cond=None, funcname=None)

このクラスはテンポラリブレークポイント、無視するカウント、無効化と再有効化、条件付きブレークポイントを実装しています。

ブレークポイントは bpbynumber という名前のリストで番号によりインデックスされ、 bplist により (file, line) の形でインデックスされます。 bpbynumber は Breakpoint クラスのインスタンスを指しています。一方 bplist は、同じ行に複数のブレークポイントが設定される場合があるので、インスタンスのリストを指しています。

ブレークポイントを作るとき、関連付けられる ファイル名 は正規化されていなければなりません。funcname が定義されると、ブレークポイントの ヒット はその関数の最初の行が実行されたときにカウントされます。条件付き ブレークポイントは毎回 ヒット をカウントします。

Breakpoint インスタンスは以下のメソッドを持ちます:

deleteMe()

このブレークポイントをファイル/行に関連付けられたリストから削除します。このブレークポイントがその行に設定された最後のブレークポイントだった場合、そのファイル/行に対するエントリ自体を削除します。

enable()

このブレークポイントを有効にします。

disable()

このブレークポイントを無効にします。

bpformat()

ブレークポイントに関する情報を持つ文字列をフォーマットして返します:

Breakpoint number.

Temporary status (del or keep).

File/line position.

Break condition.

Number of times to ignore.

Number of times hit.

Added in version 3.2.

bpprint(out=None)

ファイル out に、またはそれが None の場合は標準出力に、 bpformat() の出力を表示する。

Breakpoint インスタンスは以下の属性を持ちます:

file

File name of the Breakpoint.

line

Line number of the Breakpoint within file.

temporary

True if a Breakpoint at (file, line) is temporary.

cond

Condition for evaluating a Breakpoint at (file, line).

funcname

Function name that defines whether a Breakpoint is hit upon entering the function.

enabled

True if Breakpoint is enabled.

bpbynumber

Numeric index for a single instance of a Breakpoint.

bplist

Dictionary of Breakpoint instances indexed by (file, line) tuples.

ignore

Number of times to ignore a Breakpoint.

hits

Count of the number of times a Breakpoint has been hit.

class bdb.Bdb(skip=None)

Bdb クラスは一般的なPythonデバッガーの基本クラスとして振舞います。

このクラスはトレース機能の詳細を扱います。ユーザーとのインタラクションは、派生クラスが実装するべきです。標準ライブラリのデバッガクラス (pdb.Pdb) がその利用例です。

skip 引数は、もし与えられたならグロブ形式のモジュール名パターンの iterable でなければなりません。デバッガはこれらのパターンのどれかにマッチするモジュールで発生したフレームにステップインしなくなります。フレームが特定のモジュールで発生したかどうかは、フレームのグローバル変数の __name__ によって決定されます。

バージョン 3.1 で変更: skip パラメータが追加されました。

以下の Bdb のメソッドは、通常オーバーライドする必要はありません。

canonic(filename)

Return canonical form of filename.

For real file names, the canonical form is an operating-system-dependent, case-normalized absolute path. A filename with angle brackets, such as "<stdin>" generated in interactive mode, is returned unchanged.

reset()

Set the botframe, stopframe, returnframe and quitting attributes with values ready to start debugging.

trace_dispatch(frame, event, arg)

この関数は、デバッグされているフレームのトレース関数としてインストールされます。戻り値は新しいトレース関数(殆どの場合はこの関数自身)です。

デフォルトの実装は、実行しようとしている event (文字列として渡されます) の種類に基づいてフレームのディスパッチ方法を決定します。event は次のうちのどれかです:

"line": 新しい行を実行しようとしています。

"call": 関数が呼び出されているか、別のコードブロックに入ります。

"return": 関数か別のコードブロックからreturnしようとしています。

"exception": 例外が発生しました。

"c_call": C関数を呼び出そうとしています。

"c_return": C関数からreturnしました。

"c_exception": C関数が例外を発生させました。

Pythonのイベントに対しては、以下の専用の関数群が呼ばれます。Cのイベントに対しては何もしません。

arg 引数は以前のイベントに依存します。

トレース関数についてのより詳しい情報は、 sys.settrace() のドキュメントを参照してください。コードとフレームオブジェクトについてのより詳しい情報は、 標準型の階層 を参照してください。

dispatch_line(frame)

If the debugger should stop on the current line, invoke the user_line() method (which should be overridden in subclasses). Raise a BdbQuit exception if the quitting flag is set (which can be set from user_line()). Return a reference to the trace_dispatch() method for further tracing in that scope.

dispatch_call(frame, arg)

If the debugger should stop on this function call, invoke the user_call() method (which should be overridden in subclasses). Raise a BdbQuit exception if the quitting flag is set (which can be set from user_call()). Return a reference to the trace_dispatch() method for further tracing in that scope.

dispatch_return(frame, arg)

If the debugger should stop on this function return, invoke the user_return() method (which should be overridden in subclasses). Raise a BdbQuit exception if the quitting flag is set (which can be set from user_return()). Return a reference to the trace_dispatch() method for further tracing in that scope.

dispatch_exception(frame, arg)

If the debugger should stop at this exception, invokes the user_exception() method (which should be overridden in subclasses). Raise a BdbQuit exception if the quitting flag is set (which can be set from user_exception()). Return a reference to the trace_dispatch() method for further tracing in that scope.

通常、継承クラスは以下のメソッド群をオーバーライドしません。しかし、停止やブレークポイント機能を再定義したい場合には、オーバーライドすることもあります。

is_skipped_line(module_name)

Return True if module_name matches any skip pattern.

stop_here(frame)

Return True if frame is below the starting frame in the stack.

break_here(frame)

Return 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 effective().

break_anywhere(frame)

Return True if any breakpoint exists for frame's filename.

継承クラスはデバッガー操作をするために以下のメソッド群をオーバーライドするべきです。

user_call(frame, argument_list)

Called from dispatch_call() if a break might stop inside the called function.

argument_list is not used anymore and will always be None. The argument is kept for backwards compatibility.

user_line(frame)

stop_here() か break_here() が True を返したときに、 dispatch_line() から呼び出されます。

user_return(frame, return_value)

stop_here() が True を返したときに、 dispatch_return() から呼び出されます。

user_exception(frame, exc_info)

stop_here() が True を返したときに、 dispatch_exception() から呼び出されます。

do_clear(arg)

ブレークポイントがテンポラリブレークポイントだったときに、それをどう削除するかを決定します。

継承クラスはこのメソッドを実装しなければなりません。

継承クラスとクライアントは、ステップ状態に影響を及ぼすために以下のメソッドを呼び出すことができます。

set_step()

コードの次の行でストップします。

set_next(frame)

与えられたフレームかそれより下(のフレーム)にある、次の行でストップします。

set_return(frame)

指定されたフレームから抜けるときにストップします。

set_until(frame, lineno=None)

現在の行番号よりも大きい lineno に到達したとき、あるいは、現在のフレームから戻るときにストップします。

set_trace([frame])

frame からデバッグを開始します。frame が指定されなかった場合、デバッグは呼び出し元のフレームから開始します。

set_continue()

ブレークポイントに到達するか終了したときにストップします。もしブレークポイントが1つも無い場合、システムのトレース関数を None に設定します。

set_quit()

Set the quitting attribute to True. This raises BdbQuit in the next call to one of the dispatch_*() methods.

継承クラスとクライアントは以下のメソッドをブレークポイント操作に利用できます。これらのメソッドは、何か悪いことがあればエラーメッセージを含む文字列を返し、すべてが順調であれば None を返します。

set_break(filename, lineno, temporary=False, cond=None, funcname=None)

新しいブレークポイントを設定します。引数の lineno 行が filename に存在しない場合、エラーメッセージを返します。 filename は、 canonic() メソッドで説明されているような、標準形である必要があります。

clear_break(filename, lineno)

filename の lineno 行にあるブレークポイントを削除します。もしブレークポイントが無かった場合、エラーメッセージを返します。

clear_bpbynumber(arg)

Breakpoint.bpbynumber の中で arg のインデックスを持つブレークポイントを削除します。 arg が数値でないか範囲外の場合、エラーメッセージを返します。

clear_all_file_breaks(filename)

filename にあるすべてのブレークポイントを削除します。もしブレークポイントが無かった場合、エラーメッセージを返します。

clear_all_breaks()

存在するすべてのブレークポイントを削除します。もしブレークポイントが無かった場合、エラーメッセージを返します。

get_bpbynumber(arg)

与えられた数値によって指定されるブレークポイントを返します。 arg が文字列なら数値に変換されます。 arg が非数値の文字列である場合、指定されたブレークポイントが存在しないか削除された場合、 ValueError が上げられます。

Added in version 3.2.

get_break(filename, lineno)

Return True if there is a breakpoint for lineno in filename.

get_breaks(filename, lineno)

filename の lineno にあるすべてのブレークポイントを返します。ブレークポイントが存在しない場合は空のリストを返します。

get_file_breaks(filename)

filename の中のすべてのブレークポイントを返します。ブレークポイントが存在しない場合は空のリストを返します。

get_all_breaks()

セットされているすべてのブレークポイントを返します。

継承クラスとクライアントは以下のメソッドを呼んでスタックトレースを表現するデータ構造を取得することができます。

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.

format_stack_entry(frame_lineno, lprefix=': ')

Return a string with information about a stack entry, which is a (frame, lineno) tuple. The return string contains:

The canonical filename which contains the frame.

関数名もしくは "<lambda>"。

入力された引数。

戻り値。

(あれば)その行のコード。

以下の2つのメソッドは、文字列として渡された 文 をデバッグするもので、クライアントから利用されます。

run(cmd, globals=None, locals=None)

Debug a statement executed via the exec() function. globals defaults to __main__.__dict__, locals defaults to globals.

runeval(expr, globals=None, locals=None)

eval() 関数を利用して式を実行しデバッグします。 globals と locals は run() と同じ意味です。

runctx(cmd, globals, locals)

後方互換性のためのメソッドです。 run() を使ってください。

runcall(func, /, *args, **kwds)

1つの関数呼び出しをデバッグし、その結果を返します。

最後に、このモジュールは以下の関数を提供しています:

bdb.checkfuncname(b, frame)

Return True if we should break here, depending on the way the Breakpoint b was set.

If it was set via line number, it checks if b.line is the same as the one in frame. If the breakpoint was set via function name, we have to check we are in the right frame (the right function) and if we are on its first executable line.

bdb.effective(file, line, frame)

Return (active breakpoint, delete temporary flag) or (None, None) as the breakpoint to act upon.

The active breakpoint is the first entry in bplist for the (file, line) (which must exist) that is enabled, for which checkfuncname() is true, and that has neither a false condition nor positive ignore count. The flag, meaning that a temporary breakpoint should be deleted, is False only when the cond cannot be evaluated (in which case, ignore count is ignored).

If no such entry exists, then (None, None) is returned.

bdb.set_trace()

Bdb クラスのインスタンスを使って、呼び出し元のフレームからデバッグを開始します。

faulthandler --- Dump the Python traceback

Added in version 3.3.

This module contains functions to dump Python tracebacks explicitly, on a fault, after a timeout, or on a user signal. Call faulthandler.enable() to install fault handlers for the SIGSEGV, SIGFPE, SIGABRT, SIGBUS, and SIGILL signals. You can also enable them at startup by setting the PYTHONFAULTHANDLER environment variable or by using the -X 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 sigaltstack() function is available. This allows it to dump the traceback even on a stack overflow.

フォールトハンドラは絶望的なケースで呼び出されます。そのためシグナルセーフな関数しか使うことができません (例: ヒープメモリ上にメモリ確保はできません)。この制限により、tracebackのダンプ機能は通常のPythonのtracebackと比べてごく僅かなものです:

ASCIIのみサポートされます。エンコード時には backslashreplace エラーハンドラを使用します。

すべての文字列は500文字以内に制限されています。

ファイル名、関数名、行数のみ表示します。(ソースコードの表示はありません)

100フレーム、100スレッドに制限されています。

順番は保持されます: 最新の呼び出しが最初に表示されます。

デフォルトでは、Pythonのtracebackは sys.stderr に書き出されます。tracebackを見るには、対象アプリケーションはターミナル上で実行しなければなりません。 faulthandler.enable() に渡す引数によってログファイルを指定することができます。

モジュールはC言語で実装されているので、アプリのクラッシュ時でもPythonがデッドロックした場合でもダンプができます。

The Python Development Mode calls faulthandler.enable() at Python startup.

参考

Module pdb

Interactive source code debugger for Python programs.

traceback モジュール

Standard interface to extract, format and print stack traces of Python programs.

tracebackのダンプ

faulthandler.dump_traceback(file=sys.stderr, all_threads=True)

全スレッドのtracebackを file へダンプします。もし all_threads が False であれば、現在のスレッドのみダンプします。

参考

traceback.print_tb(), which can be used to print a traceback object.

バージョン 3.5 で変更: Added support for passing file descriptor to this function.

フォールトハンドラの状態

faulthandler.enable(file=sys.stderr, all_threads=True)

Enable the fault handler: install handlers for the SIGSEGV, SIGFPE, SIGABRT, SIGBUS and SIGILL signals to dump the Python traceback. If all_threads is 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 issue with file descriptors.

バージョン 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.

faulthandler.disable()

フォールトハンドラを無効にします: enable() によってインストールされたシグナルハンドラをアンインストールします。

faulthandler.is_enabled()

フォールトハンドラが有効かどうかチェックします。

タイムアウト後にtracebackをダンプする

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 True. If exit is True, call _exit() with status=1 after dumping the tracebacks. (Note _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 cancel_dump_traceback_later() is called: see 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.

faulthandler.cancel_dump_traceback_later()

dump_traceback_later() の最新の呼び出しをキャンセルします。

ユーザシグナルに対してtracebackをダンプする

faulthandler.register(signum, file=sys.stderr, all_threads=True, chain=False)

ユーザシグナルを登録します: すべてのスレッドでtracebackをダンプするために signum シグナルをインストールします。ただし all_threads が False であれば現在のスレッドのみ file にダンプします。もし chain が True であれば以前のハンドラも呼び出します。

The file must be kept open until the signal is unregistered by unregister(): see issue with file descriptors.

Windowsでは利用不可です。

バージョン 3.5 で変更: Added support for passing file descriptor to this function.

faulthandler.unregister(signum)

ユーザシグナルを登録解除します: register() でインストールした signum シグナルハンドラをアンインストールします。シグナルが登録された場合は True を返し、そうでなければ False を返します。

Windowsでは利用不可です。

ファイル記述子の問題

enable()、dump_traceback_later() ならびに register() は引数 file に渡されたファイル記述子を保持します。ファイルが閉じられファイル記述子が新しいファイルで再利用された場合や、os.dup2() の使用でファイル記述子が置き換えた場合、 traceback の結果は別のファイルへ書き込まれます。ファイルが置き換えられた場合は、毎回これらの関数を呼び出しなおしてください。

使用例

フォールトハンドラを有効化・無効化したときの Linuxでのセグメンテーションフォールトの例:

$ python -c "import ctypes; ctypes.string_at(0)"
Segmentation fault

$ python -q -X faulthandler
>>> import ctypes
>>> ctypes.string_at(0)
Fatal Python error: Segmentation fault

Current thread 0x00007fb899f39700 (most recent call first):
  File "/home/python/cpython/Lib/ctypes/__init__.py", line 486 in string_at
  File "<stdin>", line 1 in <module>
Segmentation fault

pdb --- Python デバッガ

ソースコード: Lib/pdb.py [https://github.com/python/cpython/tree/3.12/Lib/pdb.py]

モジュール pdb は Python プログラム用の対話型ソースコードデバッガを定義します。 (条件付き)ブレークポイントの設定やソース行レベルでのシングルステップ実行、スタックフレームのインスペクション、ソースコードリスティングおよびあらゆるスタックフレームのコンテキストにおける任意の Python コードの評価をサポートしています。事後解析デバッギングもサポートし、プログラムの制御下で呼び出すことができます。

デバッガーは拡張可能です -- 実際にはクラス Pdb として定義されています。現在これについてのドキュメントはありませんが、ソースを読めば簡単に理解できます。拡張インターフェースはモジュール bdb と cmd を使っています。

参考

faulthandler モジュール

Used to dump Python tracebacks explicitly, on a fault, after a timeout, or on a user signal.

traceback モジュール

Standard interface to extract, format and print stack traces of Python programs.

The typical usage to break into the debugger is to insert:

import pdb; pdb.set_trace()

Or:

breakpoint()

at the location you want to break into the debugger, and then run the program. You can then step through the code following this statement, and continue running without the debugger using the continue command.

バージョン 3.7 で変更: The built-in breakpoint(), when called with defaults, can be used instead of import pdb; pdb.set_trace().

def double(x):
   breakpoint()
   return x * 2
val = 3
print(f"{val} * 2 is {double(val)}")

The debugger's prompt is (Pdb), which is the indicator that you are in debug mode:

> ...(3)double()
-> return x * 2
(Pdb) p x
3
(Pdb) continue
3 * 2 is 6

バージョン 3.3 で変更: readline モジュールによるコマンドおよびコマンド引数のタブ補完が利用できます。たとえば、p コマンドの引数では現在のグローバルおよびローカル名が候補として表示されます。

You can also invoke pdb from the command line to debug other scripts. For example:

python -m pdb myscript.py

モジュールとして pdb を起動すると、デバッグ中のプログラムが異常終了したときに pdb が自動的に事後デバッグモードに入ります。事後デバッグ後 (またはプログラムの正常終了後)、pdb はプログラムを再起動します。自動再起動を行った場合、pdb の状態 (ブレークポイントなど) はそのまま維持されるので、たいていの場合、プログラム終了時にデバッガーも終了させるよりも便利なはずです。

バージョン 3.2 で変更: Added the -c option to execute commands as if given in a .pdbrc file; see デバッガコマンド.

バージョン 3.7 で変更: Added the -m option to execute modules similar to the way python -m does. As with a script, the debugger will pause execution just before the first line of the module.

Typical usage to execute a statement under control of the debugger is:

>>> import pdb
>>> def f(x):
...     print(1 / x)
>>> pdb.run("f(2)")
> <string>(1)<module>()
(Pdb) continue
0.5
>>>

クラッシュしたプログラムを調べるための典型的な使い方は以下のようになります:

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

このモジュールは以下の関数を定義しています。それぞれが少しづつ違った方法でデバッガに入ります:

pdb.run(statement, globals=None, locals=None)

デバッガーに制御された状態で (文字列またはコードオブジェクトとして与えられた) statement を実行します。あらゆるコードが実行される前にデバッガープロンプトが現れます。ブレークポイントを設定し、continue とタイプできます。あるいは、文を step や next を使って一つづつ実行することができます (これらのコマンドはすべて下で説明します)。オプションの globals と locals 引数はコードを実行する環境を指定します。デフォルトでは、モジュール __main__ の辞書が使われます。(組み込み関数 exec() または eval() の説明を参照してください。)

pdb.runeval(expression, globals=None, locals=None)

デバッガーに制御された状態で (文字列またはコードオブジェクトとして与えられる) expression を評価します。runeval() から復帰するとき、式の値を返します。その他の点では、この関数は run() と同様です。

pdb.runcall(function, *args, **kwds)

function (関数またはメソッドオブジェクト、文字列ではありません) を与えられた引数とともに呼び出します。 runcall() から復帰するとき、関数呼び出しが返したものはなんでも返します。関数に入るとすぐにデバッガプロンプトが現れます。

pdb.set_trace(*, header=None)

Enter the debugger at the calling stack frame. This is useful to hard-code a breakpoint at a given point in a program, even if the code is not otherwise being debugged (e.g. when an assertion fails). If given, header is printed to the console just before debugging begins.

バージョン 3.7 で変更: header キーワード専用引数。

pdb.post_mortem(traceback=None)

与えられた traceback オブジェクトの事後解析デバッギングに入ります。もし traceback が与えられなければ、その時点で取り扱っている例外のうちのひとつを使います。 (デフォルト動作をさせるには、例外を取り扱っている最中である必要があります。)

pdb.pm()

Enter post-mortem debugging of the traceback found in sys.last_traceback.

run* 関数と set_trace() は、 Pdb クラスをインスタンス化して同名のメソッドを実行することのエイリアス関数です。それ以上の機能を利用したい場合は、インスタンス化を自分で行わなければなりません:

class pdb.Pdb(completekey='tab', stdin=None, stdout=None, skip=None, nosigint=False, readrc=True)

Pdb はデバッガクラスです。

completekey, stdin, stdout 引数は、基底にある cmd.Cmd クラスに渡されます。そちらの解説を参照してください。

skip 引数が指定された場合、 glob スタイルのモジュール名パターンの iterable (イテレート可能オブジェクト) でなければなりません。デバッガはこのパターンのどれかにマッチするモジュールに属するフレームにはステップインしません。 [1]

デフォルトでは、Pdb は continue コマンドが投入されると、(ユーザーがコンソールから Ctrl-C を押したときに送られる) SIGINT シグナル用ハンドラーを設定します。これにより Ctrl-C を押すことで再度デバッガーを起動することができます。Pdb に SIGINT ハンドラーを変更させたくない場合は nosigint を true に設定してください。

readrc 引数はデフォルトでは真で、 Pdb が .pdbrc ファイルをファイルシステムから読み込むかどうかを制御します。

skip を使ってトレースする呼び出しの例:

import pdb; pdb.Pdb(skip=['django.*']).set_trace()

引数無しで 監査イベント pdb.Pdb を送出します。

バージョン 3.1 で変更: skip パラメータが追加されました。

バージョン 3.2 で変更: Added the nosigint parameter. Previously, a SIGINT handler was never set by Pdb.

バージョン 3.6 で変更: readrc 引数。

run(statement, globals=None, locals=None)

runeval(expression, globals=None, locals=None)

runcall(function, *args, **kwds)

set_trace()

前述のこれら関数のドキュメントを参照してください。

デバッガコマンド

デバッガーに認識されるコマンドは以下に一覧されています。たいていのコマンドは以下のように 1、2 文字に省略できます。例えば h(elp) は h か help がで help コマンドを呼び出すことを意味します (ただし he, hel, H, Help, HELP は使用できません)。コマンドの引数はホワイトスペース (スペースかタブ) で区切ってください。コマンド構文として任意の引数は大括弧 ([]) で括られています (実際に大括弧はタイプしないでください)。いくつかから選択できる引数は縦線 (|) で分割されて記述されています。

空行を入力すると入力された直前のコマンドを繰り返します。例外: 直前のコマンドが list コマンドならば、次の 11 行がリストされます。

デバッガが認識しないコマンドは Python 文とみなして、デバッグしているプログラムのコンテキストおいて実行されます。先頭にに感嘆符 (!) を付けることで Python 文であると明示することもできます。これはデバッグ中のプログラムを調査する強力な方法です。変数を変更したり関数を呼び出したりすることも可能です。このような文で例外が発生した場合には例外名が出力されますが、デバッガの状態は変化しません。

デバッガーは エイリアス をサポートしています。エイリアスはデバッグ中のコンテキストに適用可能な一定レベルのパラメータを保持することができます。

Multiple commands may be entered on a single line, separated by ;;. (A single ; is not used as it is the separator for multiple commands in a line that is passed to the Python parser.) No intelligence is applied to separating the commands; the input is split at the first ;; pair, even if it is in the middle of a quoted string. A workaround for strings with double semicolons is to use implicit string concatenation ';'';' or ";"";".

To set a temporary global variable, use a convenience variable. A convenience variable is a variable whose name starts with $. For example, $foo = 1 sets a global variable $foo which you can use in the debugger session. The convenience variables are cleared when the program resumes execution so it's less likely to interfere with your program compared to using normal variables like foo = 1.

There are three preset convenience variables:

$_frame: the current frame you are debugging

$_retval: the return value if the frame is returning

$_exception: the exception if the frame is raising an exception

Added in version 3.12.

If a file .pdbrc exists in the user's home directory or in the current directory, it is read with 'utf-8' encoding and executed as if it had been typed at the debugger prompt, with the exception that empty lines and lines starting with # are ignored. This is particularly useful for aliases. If both files exist, the one in the home directory is read first and aliases defined there can be overridden by the local file.

バージョン 3.2 で変更: .pdbrc に continue や next のようなデバッグを続行するコマンドが使用できるようになりました。以前はこのようなコマンドは無視されていました。

バージョン 3.11 で変更: .pdbrc is now read with 'utf-8' encoding. Previously, it was read with the system locale encoding.

h(elp) [command]

引数を指定しない場合、利用できるコマンドの一覧が表示されます。引数として command が与えられた場合、そのコマンドのヘルプが表示されます。help pdb で完全なドキュメント (pdb モジュールの doctring) が表示されます。command 引数は識別子でなければならないため、! コマンドのヘルプを表示するには help exec と入力します。

w(here)

スタックの底にある最も新しいフレームと一緒にスタックトレースをプリントします。矢印 (>) はカレントフレームを指し、それがほとんどのコマンドのコンテキストを決定します。

d(own) [count]

スタックフレーム内で現在のフレームを count レベル (デフォルトは 1) 新しいフレーム方向に移動します。

u(p) [count]

スタックフレーム内で現在のフレームを count レベル (デフォルトは 1) 古いフレーム方向に移動します。

b(reak) [([filename:]lineno | function) [, condition]]

With a lineno argument, set a break there in the current file. With a function argument, set a break at the first executable statement within that function. The line number may be prefixed with a filename and a colon, to specify a breakpoint in another file (probably one that hasn't been loaded yet). The file is searched on sys.path. Note that each breakpoint is assigned a number to which all the other breakpoint commands refer.

第二引数を指定する場合、その値は式で、その評価値が真でなければブレークポイントは有効になりません。

引数なしの場合は、それぞれのブレークポイントに対して、そのブレークポイントに行き当たった回数、現在の通過カウント ( ignore count ) と、もしあれば関連条件を含めてすべてのブレークポイントをリストします。

tbreak [([filename:]lineno | function) [, condition]]

一時的なブレークポイントで、最初にそこに達したときに自動的に取り除かれます。引数は break と同じです。

cl(ear) [filename:lineno | bpnumber ...]

filename:lineno 引数を与えると、その行にある全てのブレークポイントを解除します。スペースで区切られたブレークポイントナンバーのリストを与えると、それらのブレークポイントを解除します。引数なしの場合は、すべてのブレークポイントを解除します ( が、はじめに確認します ) 。

disable bpnumber [bpnumber ...]

ブレークポイント番号 bpnumber のブレークポイントを無効にします。ブレークポイントを無効にすると、プログラムの実行を止めることができなくなりますが、ブレークポイントの解除と違いブレークポイントのリストに残っており、(再び) 有効にできます。

enable bpnumber [bpnumber ...]

指定したブレークポイントを有効にします。

ignore bpnumber [count]

与えられたブレークポイントナンバーに通過カウントを設定します。count が省略されると、通過カウントは 0 に設定されます。通過カウントがゼロになったとき、ブレークポイントが機能する状態になります。ゼロでないときは、そのブレークポイントが無効にされず、どんな関連条件も真に評価されていて、ブレークポイントに来るたびに count が減らされます。

condition bpnumber [condition]

ブレークポイントに新しい condition を設定します。condition はブレークポイントを制御する条件式で、この式が真を返す場合のみブレークポイントが有効になります。condition を指定しないと既存の条件が除去されます; ブレークポイントは常に有効になります。

commands [bpnumber]

ブレークポイントナンバー bpnumber にコマンドのリストを指定します。コマンドそのものはその後の行に続けます。end だけからなる行を入力することでコマンド群の終わりを示します。例を挙げます:

(Pdb) commands 1
(com) p some_variable
(com) end
(Pdb)

ブレークポイントからコマンドを取り除くには、 commands のあとに end だけを続けます。つまり、コマンドを一つも指定しないようにします。

bpnumber 引数を指定しない場合、commands は最後にセットしたブレークポイントを参照します。

ブレークポイントコマンドはプログラムを走らせ直すのに使えます。単に continue コマンドや step、その他実行を再開するコマンドを使えば良いのです。

実行を再開するコマンド (現在のところ continue, step, next, return, jump, quit とそれらの省略形) によって、コマンドリストは終了するものと見なされます (コマンドにすぐ end が続いているかのように)。というのも実行を再開すれば (それが単純な next や step であっても) 別のブレークポイントに到達するかもしれないからです。そのブレークポイントにさらにコマンドリストがあれば、どちらのリストを実行すべきか状況が曖昧になります。

コマンドリストの中で silent コマンドを使うと、ブレークポイントで停止したという通常のメッセージはプリントされません。この振る舞いは特定のメッセージを出して実行を続けるようなブレークポイントでは望ましいものでしょう。他のコマンドが何も画面出力をしなければ、そのブレークポイントに到達したというサインを見ないことになります。

s(tep)

現在の行を実行し、最初に実行可能なものがあらわれたときに (呼び出された関数の中か、現在の関数の次の行で) 停止します。

n(ext)

現在の関数の次の行に達するか、あるいは関数が返るまで実行を継続します。 (next と step の差は step が呼び出された関数の内部で停止するのに対し、 next は呼び出された関数を (ほぼ) 全速力で実行し、現在の関数内の次の行で停止するだけです。)

unt(il) [lineno]

引数なしだと、現在の行から 1 行先まで実行します。

lineno を指定すると、番号が lineno 以上である行に到達するまで実行します。どちらにしても現在のフレームが返ってきた時点で停止します。

バージョン 3.2 で変更: 明示的に行数指定ができるようになりました。

r(eturn)

現在の関数が返るまで実行を継続します。

c(ont(inue))

ブレークポイントに出会うまで、実行を継続します。

j(ump) lineno

次に実行する行を指定します。最も底のフレーム中でのみ実行可能です。前に戻って実行したり、不要な部分をスキップして先の処理を実行する場合に使用します。

ジャンプには制限があり、例えば for ループの中には飛び込めませんし、 finally 節の外にも飛ぶ事ができません。

l(ist) [first[, last]]

現在のファイルのソースコードを表示します。引数を指定しないと、現在の行の前後 11 行分を表示するか、直前の表示を続行します。引数に . を指定すると、現在の行の前後 11 行分を表示します。数値を 1 個指定すると、その行番号の前後 11 行分を表示します。数値を 2 個指定すると、開始行と最終行として表示します; 2 個めの引数が 1 個め未満だった場合、1 個目を開始行、2 個めを開始行からの行数とみなします。

現在のフレーム内の現在の行は -> で表示されます。例外をデバッグ中の場合、例外が発生または伝搬した行は、それが現在の行とは異なるとき >> で表示されます。

バージョン 3.2 で変更: >> マーカーが追加されました。

ll | longlist

現在の関数またはフレームの全ソースコードを表示します。注目する行は list と同じようにマーカーがつきます。

Added in version 3.2.

a(rgs)

Print the arguments of the current function and their current values.

p expression

現在のコンテキストにおいて expression を評価し、その値をプリントします。

注釈

print() も使えますが、これはデバッガーコマンドではありません --- これは Python の関数 print() が実行されます。

pp expression

p コマンドに似ていますが、expression の値以外は pprint モジュールを使用して "pretty-print" されます。

whatis expression

expression の型を表示します。

source expression

expression のソースコードの取得を試み、可能であれば表示します。

Added in version 3.2.

display [expression]

expression の値が変更されていれば表示します。毎回実行は現在のフレームで停止します。

expression を指定しない場合、現在のフレームのすべての式を表示します。

注釈

Display evaluates expression and compares to the result of the previous evaluation of expression, so when the result is mutable, display may not be able to pick up the changes.

以下はプログラム例です:

lst = []
breakpoint()
pass
lst.append(1)
print(lst)

Display won't realize lst has been changed because the result of evaluation is modified in place by lst.append(1) before being compared:

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

You can do some tricks with copy mechanism to make it work:

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

Added in version 3.2.

undisplay [expression]

現在のフレーム内で expression をこれ以上表示しないようにします。expression を指定しない場合、現在のフレームで display 指定されている式を全てクリアします。

Added in version 3.2.

interact

Start an interactive interpreter (using the code module) whose global namespace contains all the (global and local) names found in the current scope.

Added in version 3.2.

alias [name [command]]

Create an alias called name that executes command. The command must not be enclosed in quotes. Replaceable parameters can be indicated by %1, %2, and so on, while %* is replaced by all the parameters. If command is omitted, the current alias for name is shown. If no arguments are given, all aliases are listed.

エイリアスは入れ子になってもよく、pdb プロンプトで合法的にタイプできるどんなものでも含めることができます。内部 pdb コマンドをエイリアスによって上書きすることが できます。そのとき、このようなコマンドはエイリアスが取り除かれるまで隠されます。エイリアス化はコマンド行の最初の語へ再帰的に適用されます。行の他のすべての語はそのままです。

例として、二つの便利なエイリアスがあります (特に .pdbrc ファイルに置かれたときに):

# Print instance variables (usage "pi classInst")
alias pi for k in %1.__dict__.keys(): print(f"%1.{k} = {%1.__dict__[k]}")
# Print instance variables in self
alias ps pi self

unalias name

指定したエイリアス name を削除します。

! statement

Execute the (one-line) statement in the context of the current stack frame. The exclamation point can be omitted unless the first word of the statement resembles a debugger command, e.g.:

(Pdb) ! n=42
(Pdb)

To set a global variable, you can prefix the assignment command with a global statement on the same line, e.g.:

(Pdb) global list_options; list_options = ['-l']
(Pdb)

run [args ...]

restart [args ...]

デバッグ中の Python プログラムを再実行します。args が与えられると、 shlex で分割され、結果が新しい sys.argv として使われます。ヒストリー、ブレークポイント、アクション、そして、デバッガーオプションは引き継がれます。 restart は run の別名です。

q(uit)

デバッガーを終了します。実行しているプログラムは中断されます。

debug code

Enter a recursive debugger that steps through code (which is an arbitrary expression or statement to be executed in the current environment).

retval

Print the return value for the last return of the current function.

脚注

[1]

フレームが属するモジュールは、そのフレームのグローバルの __name__ によって決定されます。

Python プロファイラ

ソースコード: Lib/profile.py [https://github.com/python/cpython/tree/3.12/Lib/profile.py] と Lib/pstats.py [https://github.com/python/cpython/tree/3.12/Lib/pstats.py]

プロファイラとは

cProfile と profile は 決定論的プロファイリング (deterministic profiling) を行います。 プロファイル (profile) とは、プログラムの各部分がどれだけ頻繁に呼ばれたか、そして実行にどれだけ時間がかかったかという統計情報です。 pstats モジュールを使ってこの統計情報をフォーマットし表示することができます。

Python 標準ライブラリは同じインターフェイスを提供するプロファイラの実装を2つ提供しています:

cProfile はほとんどのユーザーに推奨されるモジュールです。 C言語で書かれた拡張モジュールで、オーバーヘッドが少ないため長時間実行されるプログラムのプロファイルに適しています。 Brett Rosen と Ted Czotter によって提供された lsprof に基づいています。

profile はピュア Python モジュールで、 cProfile モジュールはこのモジュールのインターフェースを真似ています。対象プログラムに相当のオーバーヘッドが生じます。もしプロファイラに何らかの拡張をしたいのであれば、こちらのモジュールを拡張する方が簡単でしょう。このモジュールはもともと Jim Roskind により設計、実装されました。

注釈

2つのプロファイラモジュールは、与えられたプログラムの実行時プロファイルを取得するために設計されており、ベンチマークのためのものではありません (ベンチマーク用途には timeit のほうが正確な計測結果を求められます)。これは Python コードと C で書かれたコードをベンチマークするときに特に大きく影響します。プロファイラは Python コードに対してオーバーヘッドを発生しますが、C言語レベルの関数に対してはオーバーヘッドを生じません。なのでC言語で書かれたコードが、実際の速度と関係なく、Pythonで書かれたコードより速く見えるでしょう。

かんたんユーザマニュアル

この節は "マニュアルなんか読みたくない人"のために書かれています。ここではきわめて簡単な概要説明とアプリケーションのプロファイリングを手っ取り早く行う方法だけを解説します。

1つの引数を取る関数をプロファイルしたい場合、次のようにできます:

import cProfile
import re
cProfile.run('re.compile("foo|bar")')

(お使いのシステムで cProfile が使えないときは代わりに profile を使って下さい)

上のコードは re.compile() を実行して、プロファイル結果を次のように表示します:

      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)

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: Ordered by: cumulative time indicates the output is sorted by the cumtime values. The column headings include:

ncalls

呼び出し回数

tottime

与えられた関数に消費された合計時間 (sub-function の呼び出しで消費された時間は除外されています)

percall

tottime を ncalls で割った値

cumtime

この関数と全ての subfunction に消費された累積時間 (起動から終了まで)。この数字は再帰関数に ついても 正確です。

percall

cumtime をプリミティブな呼び出し回数で割った値

filename:lineno(function)

その関数のファイル名、行番号、関数名

最初の行に 2 つの数字がある場合 (たとえば 3/1) は、関数が再帰的に呼び出されたということです。2 つ目の数字はプリミティブな呼び出しの回数で、1 つ目の数字は総呼び出し回数です。関数が再帰的に呼び出されなかった場合、それらは同じ値で数字は 1 つしか表示されないことに留意してください。

run() 関数でファイル名を指定することで、プロファイル実行の終了時に出力を表示する代わりに、ファイルに保存することが出来ます。

import cProfile
import re
cProfile.run('re.compile("foo|bar")', 'restats')

pstats.Stats クラスはファイルからプロファイルの結果を読み込んで様々な書式に整えます。

ファイル cProfile と profile は他のスクリプトをプロファイルするためのスクリプトとして起動することも出来ます。例えば:

python -m cProfile [-o output_file] [-s sort_order] (-m module | myscript.py)

-o はプロファイルの結果を標準出力の代わりにファイルに書き出します。

-s は出力を sort_stats() で出力をソートする値を指定します。-o がない場合に有効です。

-m specifies that a module is being profiled instead of a script.

Added in version 3.7: Added the -m option to cProfile.

Added in version 3.8: Added the -m option to profile.

pstats モジュールの Stats クラスにはプロファイル結果のファイルに保存されているデータを処理して出力するための様々なメソッドがあります。

import pstats
from pstats import SortKey
p = pstats.Stats('restats')
p.strip_dirs().sort_stats(-1).print_stats()

strip_dirs() メソッドによって全モジュール名から無関係なパスが取り除かれました。sort_stats() メソッドにより、出力される標準的な モジュール/行/名前 文字列にしたがって全項目がソートされました。print_stats() メソッドによって全統計が出力されました。以下のようなソート呼び出しを試すことができます:

p.sort_stats(SortKey.NAME)
p.print_stats()

最初の行ではリストを関数名でソートしています。2行目で情報を出力しています。さらに次の内容も試してください:

p.sort_stats(SortKey.CUMULATIVE).print_stats(10)

このようにすると、関数が消費した累計時間でソートして、さらにその上位10件だけを表示します。どのアルゴリズムが時間を多く消費しているのか知りたいときは、この方法が役に立つはずです。

ループで多くの時間を消費している関数はどれか調べたいときは、次のようにします:

p.sort_stats(SortKey.TIME).print_stats(10)

上記はそれぞれの関数で消費された時間でソートして、上位10件の関数の情報が表示されます。

次の内容も試してください:

p.sort_stats(SortKey.FILENAME).print_stats('__init__')

このようにするとファイル名でソートされ、そのうちクラスの初期化メソッド (メソッド名 __init__) に関する統計情報だけが表示されます:

p.sort_stats(SortKey.TIME, SortKey.CUMULATIVE).print_stats(.5, 'init')

上記は時間 (time) をプライマリキー、累計時間 (cumulative time) をセカンダリキーにしてソートした後でさらに条件を絞って統計情報を出力します。 .5 は上位 50% だけを選択することを意味し、さらにその中から文字列 init を含むものだけが表示されます。

どの関数がどの関数を呼び出しているのかを知りたければ、次のようにします (p は最後に実行したときの状態でソートされています):

p.print_callers(.5, 'init')

このようにすると、関数ごとの呼び出し側関数の一覧が得られます。

さらに詳しい機能を知りたければマニュアルを読むか、次の関数の実行結果から内容を推察してください:

p.print_callees()
p.add('restats')

スクリプトとして起動した場合、 pstats モジュールはプロファイルのダンプを読み込み、分析するための統計ブラウザとして動きます。シンプルな行指向のインターフェース (cmd を使って実装) とヘルプ機能を備えています。

リファレンスマニュアル -- profile と cProfile

profile および cProfile モジュールは以下の関数を提供します:

profile.run(command, filename=None, sort=-1)

この関数は exec() 関数に渡せる一つの引数と、オプション引数としてファイル名を指定できます。全ての場合でこのルーチンは以下を実行します:

exec(command, __main__.__dict__, __main__.__dict__)

そして実行結果からプロファイル情報を収集します。ファイル名が指定されていない場合は、 Stats のインスタンスが自動的に作られ、簡単なプロファイルレポートが表示されます。 sort が指定されている場合は、 Stats インスタンスに渡され、結果をどのように並び替えるかを制御します。

profile.runctx(command, globals, locals, filename=None, sort=-1)

この関数は run() に似ていますが、 globals、 locals 辞書を command のために与えるための追加引数を取ります。このルーチンは以下を実行します:

exec(command, globals, locals)

そしてプロファイル統計情報を run() 同様に収集します。

class profile.Profile(timer=None, timeunit=0.0, subcalls=True, builtins=True)

このクラスは普通、プロファイリングを cProfile.run() 関数が提供するもの以上に正確に制御したい場合にのみ使われます。

timer 引数に、コードの実行時間を計測するためのカスタムな時刻取得用関数を渡せます。これは現在時刻を表す単一の数値を返す関数でなければなりません。もしこれが整数を返す関数ならば、 timeunit には単位時間当たりの実際の持続時間を指定します。たとえば関数が 1000 分の 1 秒単位で計測した時間を返すとすると、 timeunit は .001 でしょう。

Profile クラスを直接使うと、プロファイルデータをファイルに書き出すことなしに結果をフォーマット出来ます:

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())

The Profile class can also be used as a context manager (supported only in cProfile module. see コンテキストマネージャ型):

import cProfile

with cProfile.Profile() as pr:
    # ... do something ...

    pr.print_stats()

バージョン 3.8 で変更: コンテキストマネージャーサポートが追加されました。

enable()

Start collecting profiling data. Only in cProfile.

disable()

Stop collecting profiling data. Only in cProfile.

create_stats()

プロファイリングデータの収集を停止し、現在のプロファイルとして結果を内部で記録します。

print_stats(sort=-1)

現在のプロファイルに基づいて Stats オブジェクトを作成し、結果を標準出力に出力します。

dump_stats(filename)

現在のプロファイルの結果を filename に書き出します。

run(cmd)

exec() を用いて cmd をプロファイルします。

runctx(cmd, globals, locals)

exec() を用いて指定されたグローバルおよびローカルな環境で cmd をプロファイルします。

runcall(func, /, *args, **kwargs)

func(*args, **kwargs) をプロファイルします。

Note that profiling will only work if the called command/function actually returns. If the interpreter is terminated (e.g. via a sys.exit() call during the called command/function execution) no profiling results will be printed.

Stats クラス

Stats クラスを使用してプロファイラデータを解析します。

class pstats.Stats(*filenames or profile, stream=sys.stdout)

このコンストラクタは filename で指定した (単一または複数の) ファイルもしくは Profile のインスタンスから "統計情報オブジェクト" のインスタンスを生成します。出力は stream で指定したストリームに出力されます。

上記コンストラクタで指定するファイルは、使用する Stats に対応したバージョンの profile または cProfile で作成されたものでなければなりません。将来のバージョンのプロファイラとの互換性は 保証されておらず 、他のプロファイラで生成されたファイルや異なるオペレーティングシステムで実行される同じプロファイルとの互換性もないことに注意してください。複数のファイルを指定した場合、同一の関数の統計情報はすべて合算され、複数のプロセスで構成される全体をひとつのレポートで検証することが可能になります。既存の Stats オブジェクトに別のファイルの情報を追加するときは、 add() メソッドを使用します。

プロファイルデータをファイルから読み込む代わりに、 cProfile.Profile または profile.Profile オブジェクトをプロファイルデータのソースとして使うことができます。

Stats には次のメソッドがあります:

strip_dirs()

Stats クラスのこのメソッドは、ファイル名の前に付いているすべてのパス情報を取り除くためのものです。出力の幅を80文字以内に収めたいときに重宝します。このメソッドはオブジェクトを変更するため、取り除いたパス情報は失われます。パス情報除去の操作後、オブジェクトが保持するデータエントリは、オブジェクトの初期化、ロード直後と同じように "ランダムに" 並んでいます。 strip_dirs() を実行した結果、2つの関数名が区別できない (両者が同じファイルの同じ行番号で同じ関数名となった) 場合、一つのエントリに合算されされます。

add(*filenames)

Stats クラスのこのメソッドは、既存のプロファイリングオブジェクトに情報を追加します。引数は対応するバージョンの profile.run() または cProfile.run() によって生成されたファイルの名前でなくてはなりません。関数の名前が区別できない (ファイル名、行番号、関数名が同じ) 場合、一つの関数の統計情報として合算されます。

dump_stats(filename)

Stats オブジェクトに読み込まれたデータを、ファイル名 filename のファイルに保存します。ファイルが存在しない場合は新たに作成され、すでに存在する場合には上書きされます。このメソッドは profile.Profile クラスおよび cProfile.Profile クラスの同名のメソッドと等価です。

sort_stats(*keys)

This method modifies the 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: 'time', 'name', SortKey.TIME or SortKey.NAME). The SortKey enums argument have advantage over the string argument in that it is more robust and less error prone.

2つ以上のキーが指定された場合、2つ目以降のキーは、それ以前のキーで等価となったデータエントリの再ソートに使われます。たとえば sort_stats(SortKey.NAME, SortKey.FILE) とした場合、まずすべてのエントリが関数名でソートされた後、同じ関数名で複数のエントリがあればファイル名でソートされます。

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:

Valid String Arg

Valid enum Arg

意味

'calls'

SortKey.CALLS

呼び出し数

'cumulative'

SortKey.CUMULATIVE

累積時間

'cumtime'

N/A

累積時間

'file'

N/A

ファイル名

'filename'

SortKey.FILENAME

ファイル名

'module'

N/A

ファイル名

'ncalls'

N/A

呼び出し数

'pcalls'

SortKey.PCALLS

プリミティブな呼び出し回数

'line'

SortKey.LINE

行番号

'name'

SortKey.NAME

関数名

'nfl'

SortKey.NFL

関数名/ファイル名/行番号

'stdname'

SortKey.STDNAME

標準名

'time'

SortKey.TIME

内部時間

'tottime'

N/A

内部時間

すべての統計情報のソート結果は降順 (最も多く時間を消費したものが一番上に来る) となることに注意してください。ただし、関数名、ファイル名、行数に関しては昇順 (アルファベット順) になります。 SortKey.NFL と SortKey.STDNAME には微妙な違いがあります。標準名 (standard name) とは表示された名前によるソートで、埋め込まれた行番号のソート順が特殊です。たとえば、 (ファイル名が同じで) 3、20、40という行番号のエントリがあった場合、20、3、40 の順に表示されます。一方 SortKey.NFL は行番号を数値として比較します。要するに、 sort_stats(SortKey.NFL) は sort_stats(SortKey.NAME, SortKey.FILENAME, SortKey.LINE) と指定した場合と同じになります。

後方互換性のため、数値を引数に使った -1, 0, 1, 2 の形式もサポートしています。それぞれ 'stdname', 'calls', 'time', 'cumulative' として処理されます。引数をこの旧スタイルで指定した場合、最初のキー (数値キー) だけが使われ、複数のキーを指定しても2番目以降は無視されます。

Added in version 3.7: Added the SortKey enum.

reverse_order()

Stats クラスのこのメソッドは、オブジェクト内の情報のリストを逆順にソートします。デフォルトでは選択したキーに応じて昇順、降順が適切に選ばれることに注意してください。

print_stats(*restrictions)

Stats クラスのこのメソッドは、 profile.run() の項で述べたプロファイルのレポートを出力します。

出力するデータの順序はオブジェクトに対し最後に行った sort_stats() による操作に基づきます (add() と strip_dirs() による制限にも支配されます)。

引数は (もし与えられると) リストを重要なエントリのみに制限するために使われます。初期段階でリストはプロファイルした関数の完全な情報を持っています。制限の指定は、 (行数を指定する) 整数、 (行のパーセンテージを指定する) 0.0 から 1.0 までの割合を指定する小数、 (出力する standard name にマッチする) 正規表現として解釈される文字列のいずれかを使って行います。複数の制限が指定された場合、指定の順に適用されます。たとえば次のようになります:

print_stats(.1, 'foo:')

上記の場合まず出力するリストは全体の10%に制限され、さらにファイル名の一部に文字列 .*foo: を持つ関数だけが出力されます:

print_stats('foo:', .1)

こちらの例の場合、リストはまずファイル名に .*foo: を持つ関数だけに制限され、その中の最初の 10% だけが出力されます。

print_callers(*restrictions)

Stats クラスのこのメソッドは、プロファイルのデータベースの中から何らかの関数呼び出しを行った関数をすべて出力します。出力の順序は print_stats() によって与えられるものと同じです。出力を制限する引数も同じです。各呼び出し側関数についてそれぞれ一行ずつ表示されます。フォーマットは統計を作り出したプロファイラごとに微妙に異なります:

profile の場合、呼び出し側関数の後に括弧で囲まれて表示される数値はその呼び出しが何回行われたかを示しています。利便性のため、 2番目の括弧なしで表示される数値によって、関数が消費した累積時間を表しています。

cProfile の場合、各呼び出し側関数の後に3つの数字が付きます。呼び出しが何回行われたかと、この呼び出し側関数からの呼び出しによって現在の関数内で消費された合計時間および累積時間です。

print_callees(*restrictions)

Stats クラスのこのメソッドは、指定した関数から呼び出された関数のリストを出力します。呼び出し側、呼び出される側の方向は逆ですが、引数と出力の順序に関しては print_callers() と同じです。

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

Added in version 3.9: Added the following dataclasses: StatsProfile, FunctionProfile. Added the following function: get_stats_profile.

決定論的プロファイリングとは

決定論的プロファイリング とは、すべての 関数呼び出し, 関数からのリターン, 例外発生 をモニターし、正確なタイミングを記録することで、イベント間の時間、つまりどの時間にユーザコードが実行されているのかを計測するやり方です。もう一方の 統計的プロファイリング (このモジュールでこの方法は採用していません) とは、有効なインストラクションポインタからランダムにサンプリングを行い、プログラムのどこで時間が使われているかを推定する方法です。後者の方法は、オーバヘッドが少ないものの、プログラムのどこで多くの時間が使われているか、その相対的な示唆に留まります。

Python の場合、実行中は必ずインタプリタが動作しているため、決定論的プロファイリングを行うために計測用のコードを追加する必要はありません。 Python は自動的に各イベントに フック (オプションのコールバック) を提供します。加えて Python のインタプリタという性質によって、実行時に大きなオーバーヘッドを伴う傾向がありますが、それに比べると一般的なアプリケーションでは決定論的プロファイリングで追加される処理のオーバーヘッドは少ない傾向にあります。結果的に、決定論的プロファイリングは少ないコストで Python プログラムの実行時間に関する詳細な統計を得られる方法となっているのです。

呼び出し回数はコード中のバグ発見にも使用できます (とんでもない数の呼び出しが行われている部分)。インライン拡張の対象とすべき部分を見つけるためにも使えます (呼び出し頻度の高い部分)。内部時間の統計は、注意深く最適化すべき"ホットループ"の発見にも役立ちます。累積時間の統計は、アルゴリズム選択に関連した高レベルのエラー検知に役立ちます。なお、このプロファイラは再帰的なアルゴリズム実装の累計時間を計ることが可能で、通常のループを使った実装と直接比較することもできるようになっています。

制限事項

一つの制限はタイミング情報の正確さに関するものです。決定論的プロファイラには正確さに関する根本的問題があります。最も明白な制限は、 (一般に) "クロック"は .001 秒の精度しかないということです。これ以上の精度で計測することはできません。仮に充分な精度が得られたとしても、"誤差"が計測の平均値に影響を及ぼすことがあります。この最初の誤差を取り除いたとしても、それがまた別の誤差を引き起こす原因となります。

もう一つの問題として、イベントを検知してからプロファイラがその時刻を実際に 取得 するまでに "いくらかの時間がかかる" ことです。同様に、イベントハンドラが終了する時にも、時刻を取得して (そしてその値を保存して) から、ユーザコードが処理を再開するまでの間に遅延が発生します。結果的に多く呼び出される関数または多数の関数から呼び出される関数の情報にはこの種の誤差が蓄積する傾向にあります。このようにして蓄積される誤差は、典型的にはクロックの精度を下回ります (1クロック以下) が、一方でこの時間が累計して非常に大きな値になることも あり得ます 。

この問題はオーバーヘッドの小さい cProfile よりも profile においてより重要です。そのため、 profile は誤差が確率的に (平均値で) 減少するようにプラットフォームごとに補正する機能を備えています。プロファイラに補正を施すと (最小二乗の意味で) 正確さが増しますが、ときには数値が負の値になってしまうこともあります (呼び出し回数が極めて少なく、確率の神があなたに意地悪をしたとき :-) )。プロファイルの結果に負の値が出力されても 驚かないでください 。これは補正を行った場合にのみ生じることで、補正を行わない場合に比べて計測結果は実際にはより正確になっているはずだからです。

キャリブレーション (補正)

profile のプロファイラは time 関数呼び出しおよびその値を保存するためのオーバーヘッドを補正するために、各イベントの処理時間から定数を引きます。デフォルトでこの定数の値は 0 です。以下の手順で、プラットフォームに合った、より適切な定数が得られます (制限事項 参照)。

import profile
pr = profile.Profile()
for i in range(5):
    print(pr.calibrate(10000))

calibrate メソッドは引数として与えられた数だけ Python の呼び出しを行います。直接呼び出す場合と、プロファイラを使って呼び出す場合の両方が実施され、それぞれの時間が計測されます。その結果、プロファイラのイベントに隠されたオーバーヘッドが計算され、その値は浮動小数として返されます。たとえば、 1.8 GHz の Intel Core i5 で macOS を使用、 Python の time.process_time() をタイマとして使った場合、値はおよそ 4.04e-6 となります。

この手順で使用しているオブジェクトはほぼ一定の結果を返します。 非常に 早いコンピュータを使う場合、もしくはタイマの性能が貧弱な場合は、一定の結果を得るために引数に 100000 や 1000000 といった大きな値を指定する必要があるかもしれません。

一定の結果が得られたら、それを使う方法には3通りあります:

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)

選択肢がある場合は、補正値は小さめに設定した方が良いでしょう。プロファイルの結果に負の値が表われる"頻度が低く"なるはずです。

カスタムな時刻取得用関数を使う

プロファイラが時刻を取得する方法を変更したいなら (たとえば、実測時間やプロセスの経過時間を使いたい場合)、時刻取得用の関数を Profile クラスのコンストラクタに指定することができます:

pr = profile.Profile(your_time_func)

この結果生成されるプロファイラは時刻取得に your_time_func() を呼び出すようになります。 profile.Profile と cProfile.Profile のどちらを使っているかにより、 your_time_func の戻り値は異なって解釈されます:

profile.Profile

your_time_func() は単一の数値、あるいは (os.times() と同じように) その合計が累計時間を示すリストを返すようになっていなければなりません。関数が1つの数値、あるいは長さ2の数値のリストを返すようになっていれば、ディスパッチルーチンには特別な高速化バージョンが使われます。

あなたが選択した時刻取得関数のために、プロファイラのクラスを補正すべきであることを警告しておきます (キャリブレーション (補正) 参照)。ほとんどのマシンでは、プロファイル時のオーバヘッドの小ささという意味においては、時刻取得関数が長整数値を返すのが最も良い結果を生みます。 (os.times() は浮動小数点数のタプルを返すので かなり悪い です。) 綺麗な手段でより良い時刻取得関数に置き換えたいと望むなら、クラスを派生して、ディスパッチメソッドを置き換えてあなたの関数を一番いいように処理するように固定化してしまってください。補正定数の調整もお忘れなく。

cProfile.Profile

your_time_func() は単一の数値を返すようになっていなければなりません。単一の整数を返すのであれば、クラスコンストラクタの第二引数に単位時間当たりの実際の持続時間を渡せます。例えば your_integer_time_func が 1000 分の 1 秒単位で計測した時間を返すとすると、 Profile インスタンスを以下のように構築出来ます:

pr = cProfile.Profile(your_integer_time_func, 0.001)

cProfile.Profile クラスはキャリブレーションができないので、自前のタイマ関数は注意を払って使う必要があり、またそれは可能な限り速くなければなりません。自前のタイマ関数で最高の結果を得るには、 _lsprof 内部モジュールの C ソースファイルにハードコードする必要があるかもしれません。

Python 3.3 で time に、プロセス時間や実時間の精密な計測に使える新しい関数が追加されました。例えば、 time.perf_counter() を参照してください。

timeit --- Measure execution time of small code snippets

ソースコード: Lib/timeit.py [https://github.com/python/cpython/tree/3.12/Lib/timeit.py]

このモジュールは小さい Python コードをの時間を計測するシンプルな手段を提供しています。コマンドラインインターフェイス の他 呼び出しも可能 です。このモジュールは実行時間を計測するときに共通するいくつかの罠を回避します。O'Reilly 出版の Python Cookbook 第2版にある、Tim Peter による "Algorithms" 章も参照してください。

基本的な例

次の例は コマンドラインインターフェイス を使って 3 つの異なる式の時間を測定する方法を示しています。

$ 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

同じ事を Python インターフェイス を使って実現することもできます:

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

呼び出し可能オブジェクトは Python インターフェイス から渡すこともできます:

>>> timeit.timeit(lambda: "-".join(map(str, range(100))), number=10000)
0.19665591977536678

ただし、timeit() はコマンドラインインターフェイスを使った時だけ繰り返し回数を自動で決定する事に注意してください。使用例 節でより高度な例を説明しています。

Python インターフェイス

このモジュールは 3 つの有用な関数と 1 つの公開クラスを持っています:

timeit.timeit(stmt='pass', setup='pass', timer=<default timer>, number=1000000, globals=None)

与えられた文、setup コードおよび timer 関数で Timer インスタンスを作成し、その timeit() メソッドを number 回実行します。任意の globals 引数はコードを実行する名前空間を指定します。

バージョン 3.5 で変更: 任意の globals 引数が追加されました。

timeit.repeat(stmt='pass', setup='pass', timer=<default timer>, repeat=5, number=1000000, globals=None)

与えられた文、setup コードおよび timer 関数で Timer インスタンスを作成し、その repeat() メソッドを repeat 回繰り返すのを number 回実行します。任意の globals 引数はコードを実行する名前空間を指定します。

バージョン 3.5 で変更: 任意の globals 引数が追加されました。

バージョン 3.7 で変更: repeat のデフォルト値が 3 から 5 へ変更されました。

timeit.default_timer()

The default timer, which is always time.perf_counter(), returns float seconds. An alternative, time.perf_counter_ns, returns integer nanoseconds.

バージョン 3.3 で変更: デフォルトのタイマーが time.perf_counter() になりました。

class timeit.Timer(stmt='pass', setup='pass', timer=<timer function>, globals=None)

小さなコード片の実行時間を計測するためのクラスです。

コンストラクターは計測する文、セットアップのための追加の文、ならびにタイマー関数を取ります。両文のデフォルトは 'pass' です。タイマー関数はプラットフォーム依存です (モジュールの doctring を参照)。 stmt および setup には、複数行の文字列リテラルを含まない限り、 ; や改行で区切られた複数の文でも構いません。デフォルトでは文は timeit の名前空間内で実行されます。この挙動は名前空間を globals に渡すことで制御出来ます。

最初の命令文の実行時間を計測するには、timeit() メソッドを使用します。repeat() と autorange() メソッドは timeit() を複数回呼び出したい時に使用します。

setup の実行時間は全実行時間から除外されています。

stmt および setup パラメータは、引数なしの呼び出し可能オブジェクトをとることもできます。呼び出し可能オブジェクトを指定すると、そのオブジェクトの呼び出しがタイマー関数に埋め込まれ、その関数が timeit() メソッドによって実行されます。この場合、関数呼び出しが増えるためにタイミングのオーバーヘッドが少し増える点に注意してください。

バージョン 3.5 で変更: 任意の globals 引数が追加されました。

timeit(number=1000000)

Time number executions of the main statement. This executes the setup statement once, and then returns the time it takes to execute the main statement a number of times. The default timer returns seconds as a float. The argument is the number of times through the loop, defaulting to one million. The main statement, the setup statement and the timer function to be used are passed to the constructor.

注釈

デフォルトでは、timeit() は計測中、一時的に ガベージコレクション を停止します。この手法の利点は個々の計測結果がより比較しやすくなることです。欠点は、ガベージコレクションが計測される関数の性能の重要な要素である場合があることです。その場合、setup 文字列の最初の文でガベージコレクションを有効にできます。以下に例を示します:

timeit.Timer('for i in range(10): oct(i)', 'gc.enable()').timeit()

autorange(callback=None)

timeit() を呼び出す回数を自動的に決定します。

This is a convenience function that calls timeit() repeatedly so that the total time >= 0.2 second, returning the eventual (number of loops, time taken for that number of loops). It calls timeit() with increasing numbers from the sequence 1, 2, 5, 10, 20, 50, ... until the time taken is at least 0.2 seconds.

callback が与えられ、Noneでない場合は、 callback(number, time_taken) という2つの引数を指定して試行された後に呼び出されます。

Added in version 3.6.

repeat(repeat=5, number=1000000)

timeit() を複数回繰り返します。

これは timeit() を繰り返し呼び出したい時に有用で、結果をリストにして返します。最初の引数で何回 timeit() を呼ぶか指定します。第 2 引数で timeit() の引数 number を指定します。

注釈

結果のベクトルから平均値や標準偏差を計算して出力させたいと思うかもしれませんが、それはあまり意味がありません。多くの場合、最も低い値がそのマシンが与えられたコード断片を実行する場合の下限値です。結果のうち高めの値は、Python のスピードが一定しないために生じたものではなく、その他の計測精度に影響を及ぼすプロセスによるものです。したがって、結果のうち min() だけが見るべき値となるでしょう。この点を押さえた上で、統計的な分析よりも常識的な判断で結果を見るようにしてください。

バージョン 3.7 で変更: repeat のデフォルト値が 3 から 5 へ変更されました。

print_exc(file=None)

計測対象コードのトレースバックを出力するためのヘルパーです。

利用例:

t = Timer(...)       # outside the try/except
try:
    t.timeit(...)    # or t.repeat(...)
except Exception:
    t.print_exc()

これの標準のトレースバックより優れた点は、コンパイルしたテンプレートのソース行が表示されることです。オプションの引数 file にはトレースバックの出力先を指定します。デフォルトは sys.stderr になります。

コマンドラインインターフェイス

コマンドラインからプログラムとして呼び出す場合は、次の書式を使います:

python -m timeit [-n N] [-r N] [-u U] [-s S] [-p] [-v] [-h] [statement ...]

以下のオプションが使用できます:

-n N, --number=N

'statement' を実行する回数

-r N, --repeat=N

timer を繰り返す回数（デフォルトは5）

-s S, --setup=S

最初に1回だけ実行する文 (デフォルトは pass)

-p, --process

デフォルトの time.perf_counter() の代わり time.process_time() を利用して、実時間ではなくプロセス時間を計測します

Added in version 3.3.

-u, --unit=U

timer 出力の時間の単位を指定します。 nsec、usec、msec、sec を選択できます。

Added in version 3.5.

-v, --verbose

時間計測の結果をそのまま詳細な数値でくり返し表示する

-h, --help

簡単な使い方を表示して終了する

文は複数行指定することもできます。その場合、各行は独立した文として引数に指定されたものとして処理します。クォートと行頭のスペースを使って、インデントした文を使うことも可能です。この複数行のオプションは -s においても同じ形式で指定可能です。

オプション -n でループの回数が指定されていない場合、1, 2, 5, 10, 20, 50, ... という数列で、少なくとも総時間が 0.2 秒になるまで回数を増やしていって、適切なループ回数が計算されます。

default_timer() の測定値は、同じマシン上で実行されている他のプログラムの影響を受ける可能性があるため、正確な時間計測が必要な場合は、計測を数回繰り返し、最適な時間を使用することをおすすめします。 -r オプションはこれに適しています。ほとんどの場合、デフォルトの5回の繰り返しで十分でしょう。 time.process_time() を使用すればCPU時間を測定できます。

注釈

pass 文の実行には基本的なオーバーヘッドが存在します。ここにあるコードはこの事実を隠そうとはしていませんが、注意する必要があります。基本的なオーバーヘッドは引数なしでプログラムを起動することにより計測でき、それは Python のバージョンによって異なるでしょう。

使用例

最初に 1 回だけ実行されるセットアップ文を指定することが可能です:

$ 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

In the output, there are three fields. The loop count, which tells you how many times the statement body was run per timing loop repetition. The repetition count ('best of 5') which tells you how many times the timing loop was repeated, and finally the time the statement body took on average within the best repetition of the timing loop. That is, the time the fastest repetition took divided by the loop count.

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

同じことは Timer クラスとそのメソッドを使用して行うこともできます:

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

以下の例は、複数行を含んだ式を計測する方法を示しています。ここでは、オブジェクトの存在する属性と存在しない属性に対してテストするために hasattr() と try/except を使用した場合のコストを比較しています:

$ 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

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

定義した関数に timeit モジュールがアクセスできるようにするために、 import 文の入った setup パラメータを渡すことができます:

def test():
    """Stupid test function"""
    L = [i for i in range(100)]

if __name__ == '__main__':
    import timeit
    print(timeit.timeit("test()", setup="from __main__ import test"))

他のオプションは globals() を globals 引数に渡すことです。これによりコードはあなたのグローバル名前空間内で実行されます。これはそれぞれでインポートするより 便利です:

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()))

trace --- Trace or track Python statement execution

ソースコード: Lib/trace.py [https://github.com/python/cpython/tree/3.12/Lib/trace.py]

trace モジュールにより、プログラム実行のトレース、 注釈された文のカバレッジの一覧の作成、呼び出し元/呼び出し先の関係の出力、プログラム実行中に実行された関数の表の作成を行うことができます。これは別のプログラム中やコマンドラインから利用することができます。

参考

Coverage.py [https://coverage.readthedocs.io/]

サードパーティの人気なカバレッジツールで、 HTML 出力に加えて分岐カバレッジのような高度な機能も提供しています。

コマンドラインからの使用

trace モジュールはコマンドラインから起動することができます。これは次のように簡単です

python -m trace --count -C . somefile.py ...

これで、 somefile.py の実行中に import された Python モジュールの注釈付きリストがカレントディレクトリに生成されます。

--help

使い方を表示して終了します。

--version

モジュールのバージョンを表示して終了します。

Added in version 3.8: 実行可能なモジュールを走らせられる --module オプションが追加されました。

主要なオプション

trace を実行するときには、以下のオプションの少なくとも 1 つを指定しなければいけません。 --listfuncs オプションは、 --trace オプション、 --count オプションと相互排他的です。 --listfuncs が与えられたとき、 --trace オプション、 --count オプションの両方とも受け付けず、他の場合も同様です。

-c, --count

プログラム完了時に、それぞれの文が何回実行されたかを示す注釈付きリストのファイルを生成します。下記の --coverdir, --file, --no-report も参照してください。

-t, --trace

実行された通りに行を表示します。

-l, --listfuncs

プログラム実行の際に実行された関数を表示します。

-r, --report

--count と --file 引数を使った過去のプログラム実行結果から、注釈付きリストのファイルを生成します。コードを実行するわけではありません。

-T, --trackcalls

プログラム実行によって明らかになった呼び出しの関係を表示します。

修飾的オプション

-f, --file=<file>

複数回にわたるトレース実行についてカウント (count) を累積するファイルに名前をつけます。 --count オプションと一緒に使って下さい。

-C, --coverdir=<dir>

レポートファイルを保存するディレクトリを指定します。 package.module についてのカバレッジレポートは dir/package/module.cover に書き込まれます。

-m, --missing

注釈付きリストの生成時に、実行されなかった行に >>>>>> の印を付けます。

-s, --summary

--count または --report の利用時に、処理されたファイルそれぞれの簡潔な概要を標準出力 (stdout) に書き出します。

-R, --no-report

注釈付きリストを生成しません。これは --count を何度か走らせてから最後に単一の注釈付きリストを生成するような場合に便利です。

-g, --timing

各行の先頭にプログラム開始からの時間を付けます。トレース中にだけ使われます。

フィルターオプション

これらのオプションは複数回指定できます。

--ignore-module=<mod>

指定されたモジュールと（パッケージだった場合は）そのサブモジュールを無視します。引数はカンマ区切りのモジュール名リストです。

--ignore-dir=<dir>

指定されたディレクトリとサブディレクトリ中のモジュールとパッケージを全て無視します。引数は os.pathsep で区切られたディレクトリのリストです。

プログラミングインターフェース

class trace.Trace(count=1, trace=1, countfuncs=0, countcallers=0, ignoremods=(), ignoredirs=(), infile=None, outfile=None, timing=False)

文 (statement) や式 (expression) の実行をトレースするオブジェクトを作成します。引数は全てオプションです。count は行数を数えます。trace は行実行のトレースを行います。countfuncs は実行中に呼ばれた関数を列挙します。countcallers は呼び出しの関係を追跡します。ignoremods は無視するモジュールやパッケージのリストです。ignoredirs は無視するパッケージやモジュールを含むディレクトリのリストです。infile は保存された集計 (count) 情報を読むファイルの名前です。outfile は更新された集計 (count) 情報を書き出すファイルの名前です。timing は、タイムスタンプをトレース開始時点からの相対秒数で表示します。

run(cmd)

コマンドを実行して、現在のトレースパラメータに基づいてその実行から統計情報を集めます。 cmd は、 exec() に渡せるような文字列か code オブジェクトです。

runctx(cmd, globals=None, locals=None)

指定された globals と locals 環境下で、コマンドを実行して、現在のトレースパラメータに基づいてその実行から統計情報を集めます。定義しない場合、globals と locals はデフォルトで空の辞書となります。

runfunc(func, /, *args, **kwds)

与えられた引数の func を、 Trace オブジェクトのコントロール下で現在のトレースパラメタのもとに呼び出します。

results()

与えられた Trace インスタンスの run, runctx, runfunc の以前の呼び出しについて集計した結果を納めた CoverageResults オブジェクトを返します。蓄積されたトレース結果はリセットしません。

class trace.CoverageResults

カバレッジ結果のコンテナで、 Trace.results() で生成されるものです。ユーザーが直接生成するものではありません。

update(other)

別の CoverageResults オブジェクトのデータを統合します。

write_results(show_missing=True, summary=False, coverdir=None)

カバレッジ結果を書き出します。ヒットしなかった行も出力するには show_missing を指定します。モジュールごとの概要を出力に含めるには summary を指定します。coverdir に指定するのは結果ファイルを出力するディレクトリです。None の場合は各ソースファイルごとの結果がそれぞれのディレクトリに置かれます。

簡単な例でプログラミングインターフェースの使い方を見てみましょう:

import sys
import trace

# create a Trace object, telling it what to ignore, and whether to
# do tracing or line-counting or both.
tracer = trace.Trace(
    ignoredirs=[sys.prefix, sys.exec_prefix],
    trace=0,
    count=1)

# run the new command using the given tracer
tracer.run('main()')

# make a report, placing output in the current directory
r = tracer.results()
r.write_results(show_missing=True, coverdir=".")

tracemalloc --- Trace memory allocations

Added in version 3.4.

ソースコード: Lib/tracemalloc.py [https://github.com/python/cpython/tree/3.12/Lib/tracemalloc.py]

tracemallocモジュールは、Python が割り当てたメモリブロックをトレースするためのデバッグツールです。このモジュールは以下の情報を提供します。

オブジェクトが割り当てられた場所のトレースバック

ファイル名ごと、及び行ごとに割り当てられたメモリブロックの以下の統計を取ります：総サイズ、ブロック数、割り当てられたブロックの平均サイズ

メモリリークを検出するために2つのスナップショットの差を計算します。

Python が割り当てたメモリブロックの大半をトレースするには、 PYTHONTRACEMALLOC 環境変数を 1 に設定して可能な限り早くモジュールを開始させるか、-X tracemalloc コマンドラインオプションを使用してください。実行時に tracemalloc.start() を呼んで Python のメモリ割り当てのトレースを開始することが出来ます。

デフォルトでは、割り当てられたメモリブロック1つのトレースは最新1フレームを保存します。開始時に25フレームを保存するには、PYTHONTRACEMALLOC 環境変数を 25 に設定するか、-X tracemalloc=25 コマンドラインオプションを使用してください。

使用例

上位10を表示する

最も多くのメモリを割り当てているファイル10を表示します:

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)

Python テストスイートの出力例です:

[ 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

Python がモジュールから 4855 KiB のデータ (バイトコードで定数) を読み込んでいることと、collections モジュールが namedtuple 型をビルドするのに 244 KiB を割り当てていることが分かります。

オプションの詳細については Snapshot.statistics() を参照してください。

差を計算する

スナップショットを2つ取り、差を表示します:

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)

Python テストスイートのテストを実行する前後の出力例です:

[ 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

Python がモジュールデータ 8173 KiB (バイトコードと定数) を読み込み、前回スナップショットを取ったとき、すなわちテストの前に読み込んだ量より 4428 KiB 多いということが分かります。同様に、 linecache モジュールはトレースバックの書式化に Python ソースコード 940 KiB をキャッシュし、その全ては前回のスナップショットの後に行われたことが分かります。

システムに空きメモリがほとんどない場合、スナップショットをオフラインで解析するための Snapshot.dump() メソッドを使用して、スナップショットをディスクに書き込むことが出来ます。そして Snapshot.load() メソッドを使用してスナップショットを再読み込みします。

メモリブロックのトレースバックを取得する

最大のメモリブロックのトレースバックを表示するコードです:

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)

Python テストスイートの出力例です (トレースバックは 25 フレームに制限されています):

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)

We can see that the most memory was allocated in the importlib module to load data (bytecode and constants) from modules: 870.1 KiB. The traceback is where the importlib loaded data most recently: on the import pdb line of the doctest module. The traceback may change if a new module is loaded.

top を整形化する

<frozen importlib._bootstrap> および <unknown> ファイルを無視して、メモリ割り当て量の上位10を整形化して表示するコードです:

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)

Python テストスイートの出力例です:

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

オプションの詳細については Snapshot.statistics() を参照してください。

Record the current and peak size of all traced memory blocks

The following code computes two sums like 0 + 1 + 2 + ... inefficiently, by creating a list of those numbers. This list consumes a lot of memory temporarily. We can use get_traced_memory() and reset_peak() to observe the small memory usage after the sum is computed as well as the peak memory usage during the computations:

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=}")

出力:

first_size=664, first_peak=3592984
second_size=804, second_peak=29704

Using reset_peak() ensured we could accurately record the peak during the computation of small_sum, even though it is much smaller than the overall peak size of memory blocks since the start() call. Without the call to reset_peak(), second_peak would still be the peak from the computation large_sum (that is, equal to 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 list, and writing sum(range(...))).

API

関数

tracemalloc.clear_traces()

Python が割り当てたメモリブロックのトレースを消去します。

stop() を参照してください。

tracemalloc.get_object_traceback(obj)

Python オブジェクト obj が割り当てられたトレースバックを取得します。Traceback インスタンスか、tracemalloc モジュールがメモリ割り当てをトレースしていない場合かオブジェクトの割り当てをトレースしていない場合は、None を返します。

gc.get_referrers() や sys.getsizeof() 関数も参照してください。

tracemalloc.get_traceback_limit()

トレースのトレースバック内に格納されている最大フレーム数を取得します。

tracemalloc モジュールは上限を取得するためにメモリ割り当てをトレースしていなければなりません。そうでなければ例外が送出されます。

start() 関数で上限を設定します。

tracemalloc.get_traced_memory()

tracemalloc モジュールがトレースするメモリブロックの現在のサイズと最大時のサイズをタプルとして取得します: (current: int, peak: int)。

tracemalloc.reset_peak()

tracemalloc モジュールがトレースするメモリブロックの最大時のサイズを現在のサイズに設定します。

Do nothing if the tracemalloc module is not tracing memory allocations.

This function only modifies the recorded peak size, and does not modify or clear any traces, unlike clear_traces(). Snapshots taken with take_snapshot() before a call to reset_peak() can be meaningfully compared to snapshots taken after the call.

get_traced_memory() も参照してください。

Added in version 3.9.

tracemalloc.get_tracemalloc_memory()

tracemalloc モジュールがメモリブロックのトレースを保存するのに使用しているメモリ使用量をバイト単位で取得します。int を返します。

tracemalloc.is_tracing()

tracemalloc モジュールが Python のメモリ割り当てをトレースしていれば True を、そうでなければ False を返します。

start() ならびに stop() 関数も参照してください。

tracemalloc.start(nframe: int = 1)

Python のメモリ割り当てのトレースを開始します: Python メモリアロケータにフックします。トレースの収集されたトレースバックは nframe フレームに制限されます。デフォルトでは、あるブロックのトレースは最新のフレームのみを保存します、つまり上限は 1 です。 nframe は 1 以上でなければなりません。

You can still read the original number of total frames that composed the traceback by looking at the Traceback.total_nframe attribute.

1 より多くのフレームを保存するのは 'traceback' でグループ化された統計や累積的な統計を計算する場合にのみ有用です。 Snapshot.compare_to() および Snapshot.statistics() メソッドを参照してください。

保存するフレーム数を増やすと tracemalloc モジュールのメモリと CPU のオーバーヘッドは増加します。 tracemalloc モジュールが使用しているメモリ量を調べるには get_tracemalloc_memory() 関数を使用してください。

PYTHONTRACEMALLOC 環境変数 (PYTHONTRACEMALLOC=NFRAME) と -X tracemalloc=NFRAME コマンドラインオプションを使って実行開始時にトレースを始めることが出来ます。

stop()、is_tracing()、get_traceback_limit() 関数を参照してください。

tracemalloc.stop()

Python のメモリ割り当てのトレースを停止します。つまり、Python のメモリ割り当てへのフックをアンインストールします。 Python が割り当てたメモリブロックについてこれまで集めたトレースも全てクリアします。

トレースが全部クリアされる前にスナップショットを取りたい場合は take_snapshot() 関数を呼んでください。

start()、is_tracing()、clear_traces() 関数も参照してください。

tracemalloc.take_snapshot()

Python が割り当てたメモリブロックのトレースのスナップショットを取ります。新しい Snapshot インスタンスを返します。

スナップショットは tracemalloc モジュールがメモリ割り当てのトレースを始める前に割り当てられたメモリブロックを含みません。

トレースのトレースバックは get_traceback_limit() フレームに制限されています。より多くのフレームを保存するには start() 関数の nframe 引数を使用してください。

スナップショットを取るには tracemalloc モジュールはメモリ割り当てをトレースしていなければなりません。 start() 関数を参照してください。

get_object_traceback() 関数を参照してください。

DomainFilter

class tracemalloc.DomainFilter(inclusive: bool, domain: int)

Filter traces of memory blocks by their address space (domain).

Added in version 3.6.

inclusive

If inclusive is True (include), match memory blocks allocated in the address space domain.

If inclusive is False (exclude), match memory blocks not allocated in the address space domain.

domain

Address space of a memory block (int). Read-only property.

Filter

class tracemalloc.Filter(inclusive: bool, filename_pattern: str, lineno: int = None, all_frames: bool = False, domain: int = None)

メモリブロックのトレースをフィルターします。

filename_pattern のシンタックスについては fnmatch.fnmatch() 関数を参照してください。'.pyc' 拡張子は '.py' に置換されます。

例:

Filter(True, subprocess.__file__) は subprocess モジュールのみを含みます

Filter(False, tracemalloc.__file__) は tracemalloc モジュールのトレースを除外します

Filter(False, "<unknown>") は空のトレースバックを除外します

バージョン 3.5 で変更: '.pyo' ファイル拡張子が '.py' に置換されることはもうありません。

バージョン 3.6 で変更: domain 属性が追加されました。

domain

Address space of a memory block (int or None).

tracemalloc uses the domain 0 to trace memory allocations made by Python. C extensions can use other domains to trace other resources.

inclusive

If inclusive is True (include), only match memory blocks allocated in a file with a name matching filename_pattern at line number lineno.

If inclusive is False (exclude), ignore memory blocks allocated in a file with a name matching filename_pattern at line number lineno.

lineno

フィルタの行番号です (int)。lineno が None の場合フィルタはあらゆる行番号にマッチします。

filename_pattern

フィルタのファイル名のパターンです (str)。読み出し専用のプロパティです。

all_frames

all_frames が True の場合トレースバックの全てのフレームをチェックします。all_frames が False の場合最新のフレームをチェックします。

トレースバックの上限が 1 の場合この属性の影響はありません。 get_traceback_limit() 関数と Snapshot.traceback_limit 属性を参照してください。

Frame

class tracemalloc.Frame

トレースバックのフレームです。

Traceback クラスは Frame インスタンスのシークエンスです。

filename

ファイル名 (str)。

lineno

行番号 (int)。

Snapshot

class tracemalloc.Snapshot

Python が割り当てたメモリブロックのトレースのスナップショットです。

take_snapshot() 関数はスナップショットのインスタンスを作ります。

compare_to(old_snapshot: Snapshot, key_type: str, cumulative: bool = False)

古いスナップショットとの差を計算します。 key_type でグループ化された StatisticDiff インスタンスのソート済みリストとして統計を取得します。

key_type および cumulative 引数については Snapshot.statistics() メソッドを参照してください。

結果は降順でソートされます: キーは StatisticDiff.size_diff の絶対値、 StatisticDiff.size、 StatisticDiff.count_diff の絶対置、 Statistic.count、そして StatisticDiff.traceback です。

dump(filename)

スナップショットをファイルに書き込みます。

スナップショットをリロードするには load() を使用します。

filter_traces(filters)

Create a new Snapshot instance with a filtered traces sequence, filters is a list of DomainFilter and Filter instances. If filters is an empty list, return a new 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 で変更: DomainFilter instances are now also accepted in filters.

classmethod load(filename)

スナップショットをファイルからロードします。

dump() を参照してください。

statistics(key_type: str, cumulative: bool = False)

key_type でグループ化された Statistic インスタンスのソート済みリストとして統計を取得します:

key_type

description

'filename'

ファイル名

'lineno'

ファイル名と行番号

'traceback'

traceback

cumulative が True の場合、最新のフレームだけでなく、トレースのトレースバックの全フレームのメモリーブロックについて大きさと数を累積します。累積モードは key_type が 'filename' および 'lineno' と等しい場合にのみ使用することが出来ます。

結果は降順でソートされます: キーは Statistic.size, Statistic.count, Statistic.traceback です。

traceback_limit

traces のトレースバック内に保存されるフレーム数の最大値です。スナップショットが取られたときの get_traceback_limit() の結果です。

traces

Python が割り当てた全メモリブロックのトレースで、 Trace インスタンスのシークェンスです。

シークェンスの順序は未定義です。統計のソート済みリストを取得するには Snapshot.statistics() を使用してください。

Statistic

class tracemalloc.Statistic

メモリ割り当ての統計です。

Snapshot.statistics() は Statistic インスタンスの一覧を返します。

StatisticDiff クラスも参照してください。

count

メモリブロック数 (int)。

size

メモリブロックのバイト単位の総サイズ (int)。

traceback

メモリブロックが割り当てられているトレースバック。Traceback インスタンス。

StatisticDiff

class tracemalloc.StatisticDiff

新旧 Snapshot インスタンスのメモリ割り当ての統計差です。

Snapshot.compare_to() は StatisticDiff インスタンスのリストを返します。 Statistic クラスも参照してください。

count

新しいスナップショット内のメモリブロックの数 (int) です。新しいスナップショット内でメモリブロックが解放された場合は 0 です。

count_diff

新旧スナップショットのメモリブロック数の差 (int) です。メモリブロックが新しいスナップショット内で割り当てられた場合は 0 です。

size

新しいスナップショット内のメモリブロックのバイト単位での総サイズ (int) です。新しいスナップショット内でメモリブロックが解放された場合は 0 です。

size_diff

新旧スナップショットのバイト単位での総サイズの差 (int) です。メモリブロックが新しいスナップショット内で割り当てられた場合は 0 です。

traceback

メモリブロックが割り当てられたトレースバックで、 Traceback のインスタンスです。

Trace

class tracemalloc.Trace

メモリブロックをトレースします。

Snapshot.traces 属性は Trace インスタンスのシークエンスです。

バージョン 3.6 で変更: domain 属性が追加されました。

domain

Address space of a memory block (int). Read-only property.

tracemalloc uses the domain 0 to trace memory allocations made by Python. C extensions can use other domains to trace other resources.

size

メモリブロックのバイト単位のサイズ (int)。

traceback

メモリブロックが割り当てられているトレースバック。Traceback インスタンス。

Traceback

class tracemalloc.Traceback

Sequence of Frame instances sorted from the oldest frame to the most recent frame.

A traceback contains at least 1 frame. If the tracemalloc module failed to get a frame, the filename "<unknown>" at line number 0 is used.

When a snapshot is taken, tracebacks of traces are limited to get_traceback_limit() frames. See the take_snapshot() function. The original number of frames of the traceback is stored in the Traceback.total_nframe attribute. That allows to know if a traceback has been truncated by the traceback limit.

Trace.traceback 属性は Traceback のインスタンスです。

バージョン 3.7 で変更: Frames are now sorted from the oldest to the most recent, instead of most recent to oldest.

total_nframe

Total number of frames that composed the traceback before truncation. This attribute can be set to None if the information is not available.

バージョン 3.9 で変更: Traceback.total_nframe 属性が追加されました。

format(limit=None, most_recent_first=False)

Format the traceback as a list of lines. Use the 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 abs(limit) oldest frames. If most_recent_first is True, the order of the formatted frames is reversed, returning the most recent frame first instead of last.

Similar to the traceback.format_tb() function, except that format() does not include newlines.

以下はプログラム例です:

print("Traceback (most recent call first):")
for line in traceback:
    print(line)

出力:

Traceback (most recent call first):
  File "test.py", line 9
    obj = Object()
  File "test.py", line 12
    tb = tracemalloc.get_object_traceback(f())

ソフトウェア・パッケージと配布

以下のライブラリは Python で書かれたソフトウェアを配布、インストールするためのものです。これらは Python Package Index [https://pypi.org] に対して動作するように設計されていますが、ローカルのインデックスサーバーや、インデックスサーバーなしに使うこともできます。

ensurepip --- Bootstrapping the pip installer

コマンドラインインターフェイス

モジュール API

venv --- Creation of virtual environments

仮想環境の作成

仮想環境のしくみ

API

EnvBuilder を拡張する例

zipapp --- Manage executable Python zip archives

基本的な例

コマンドラインインターフェイス

Python API

使用例

インタープリタの指定

Creating Standalone Applications with zipapp

Caveats

The Python Zip Application Archive Format

ensurepip --- Bootstrapping the pip installer

Added in version 3.4.

Source code: Lib/ensurepip [https://github.com/python/cpython/tree/3.12/Lib/ensurepip]

ensurepip パッケージは pip インストーラを既にインストールされている Python 環境や仮想環境にブートストラップする助けになります。このブートストラップのアプローチは pip が独立したリリースサイクルを持ち、最新の利用可能な安定版が CPython リファレンスインタープリタのメンテナンスリリースや feature リリースにバンドルされていることを反映しています。

ほとんどの場合、Python のエンドユーザーがこのモジュールを直接呼び出す必要はないでしょう(pip はデフォルトでブートストラップされるからです)。しかし、もし Python のインストール時に pip のインストールをスキップしたり、仮想環境を構築したり、明示的に pip をアンインストールした場合、直接呼び出す必要があるかもしれません。

注釈

このモジュールはインターネットに アクセスしません。pip のブートストラップに必要な全てはこのパッケージの一部として含まれています。

参考

Python モジュールのインストール

エンドユーザーが Python パッケージをインストールする際のガイドです。

PEP 453 [https://peps.python.org/pep-0453/]: Python インストールの際の明示的なpipのブートストラッピング

このモジュールのもともとの論拠と仕様。

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. See WebAssemblyプラットフォーム for more information.

コマンドラインインターフェイス

コマンドラインインターフェースを起動するには -m スイッチをつけてインタープリターを使用します。

最も簡単な起動方法は:

python -m ensurepip

この起動方法は pip をインストールします。既にインストールされていた場合は何もしません。インストールされた pip のバージョンを ensurepip で利用できるもののうち、できるだけ新しいものにするためには、--upgrade オプションを追加して:

python -m ensurepip --upgrade

デフォルトでは、pip は現在の仮想環境(もしアクティブなら)か、システムのサイトパッケージ(もしアクティブな仮想環境がなければ)にインストールされます。インストール先は２つの追加コマンドラインオプションで制御できます:

--root dir: Installs pip relative to the given root directory rather than the root of the currently active virtual environment (if any) or the default root for the current Python installation.

--user: は、現在インストールされている Python にグローバルにインストールされる代わりに、ユーザーの site packages ディレクトリに pip をインストールします(このオプションはアクティブな仮想環境のもとでは許可されません)。

デフォルトでは pipX と pipX.Y がインストールされます(X.Yは ensurepip を起動したPythonのバージョン)。インストールされるスクリプトは2つの追加コマンドラインオプションで制御できます:

--altinstall: alternate インストール。X.Y でバージョン付けされたものだけがインストールされます。

--default-pip: "default pip" のインストールが要求されると、通常の二つのスクリプトに加えて pip スクリプトがインストールされます。

2つのスクリプト選択オプションを指定すると例外が発生します。

モジュール API

ensurepip はプログラムから利用出来る 2 つの関数を公開しています:

ensurepip.version()

環境にブートストラップする際にインストールされることになる利用可能な pip のバージョンを示す文字列を返します。

ensurepip.bootstrap(root=None, upgrade=False, user=False, altinstall=False, default_pip=False, verbosity=0)

現在の環境あるいは指示された環境へ pip をブートストラップします。

root で、インストールの root ディレクトリを変更します。 root が None の場合は、インストールは現在の環境でのデフォルトの場所を使います。

upgrade で、 pip の利用可能なバージョンとして、インストール済みの以前のバージョンをアップグレードするかどうかを指定します。

user で、グローバルなインストールではなく user スキームを使うかどうかを指定します。

デフォルトではスクリプト pipX と pipX.Y はインストールされます(X.YはPythonの現在のバージョンです)。

altinstall が設定されていた場合は pipX はインストール されません。

default_pip がセットされていれば、 pip スクリプトが2つの標準スクリプトと共にインストールされます。

altinstall と default_pip の両方を指定すると、 ValueError を起こします。

verbosity でブートストラップ操作からの sys.stdout への出力の冗長レベルをコントロールします。

引数 root 付きで 監査イベント ensurepip.bootstrap を送出します。

注釈

ブートストラップ処理は sys.path, os.environ の両方に対して副作用を持ちます。代わりに、サブプロセスとしてコマンドラインインターフェイスを使うことで、これら副作用を避けることが出来ます。

注釈

ブートストラップ処理は pip によって必要とされるモジュールを追加インストールするかもしれませんが、ほかのソフトウェアはそれら依存物がいつもデフォルトで存在していることを仮定すべきではありません(将来のバージョンの pip ではその依存はなくなるかもしれませんので)。

venv --- Creation of virtual environments

Added in version 3.3.

ソースコード: Lib/venv/ [https://github.com/python/cpython/tree/3.12/Lib/venv/]

venv モジュールは、軽量な仮想環境の作成を行います。それぞれの仮想環境は、site ディレクトリに独立した Python パッケージの集合を持っています。仮想環境は、ベース Python とも呼ばれる、すでにインストールされている Python の上に作成され、明示的にインストールしたパッケージのみが利用可能となるよう、ベース Python から隔離することもできます。

When used from within a virtual environment, common installation tools such as pip [https://pypi.org/project/pip/] will install Python packages into a virtual environment without needing to be told to do so explicitly.

A virtual environment is (amongst other things):

Used to contain a specific Python interpreter and software libraries and binaries which are needed to support a project (library or application). These are by default isolated from software in other virtual environments and Python interpreters and libraries installed in the operating system.

Contained in a directory, conventionally either named venv or .venv in the project directory, or under a container directory for lots of virtual environments, such as ~/.virtualenvs.

Not checked into source control systems such as Git.

Considered as disposable -- it should be simple to delete and recreate it from scratch. You don't place any project code in the environment

Not considered as movable or copyable -- you just recreate the same environment in the target location.

Python仮想環境の背景についてより詳しくは PEP 405 [https://peps.python.org/pep-0405/] を参照してください。

参考

Python Packaging User Guide: Creating and using virtual environments [https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#create-and-use-virtual-environments]

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. See WebAssemblyプラットフォーム for more information.

仮想環境の作成

仮想環境 を作成するには venv コマンドを実行します:

python -m venv /path/to/new/virtual/environment

このコマンドを実行すると、ターゲットディレクトリ (および必要なだけの親ディレクトリ) が作成され、その中に pyvenv.cfg ファイルが置かれます。そのファイルの home キーはこのコマンドを呼び出した Python のインストール場所を指します (よく使われるターゲットディレクトリの名前は .venv です)。このコマンドはまた、 Python バイナリのコピーまたはシンボリックリンク (のプラットフォームあるいは仮想環境作成時に使われた引数に対して適切な方) を含む bin (Windows では Scripts) サブディレクトリを作成します。さらに、 lib/pythonX.Y/site-packages (Windows では Lib\site-packages) サブディレクトリも (最初は空の状態で) 作成します。指定したディレクトリが存在している場合は、それが再利用されます。

バージョン 3.5 で変更: 仮想環境の作成には、 venv の使用が今は推奨されています。

バージョン 3.6 で非推奨: Python 3.3 と 3.4 では仮想環境の作成に pyvenv が推奨されていましたが、Python 3.6 で非推奨になりました。

Windows では、 venv コマンドは次のように実行します:

c:\>Python35\python -m venv c:\path\to\myenv

あるいは、 インストールされている Python のために PATH 変数や PATHEXT 変数が設定してある場合は次のコマンドでも実行できます:

c:\>python -m venv c:\path\to\myenv

このコマンドを -h をつけて実行すると利用できるオプションが表示されます:

usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear]
            [--upgrade] [--without-pip] [--prompt PROMPT] [--upgrade-deps]
            ENV_DIR [ENV_DIR ...]

Creates virtual Python environments in one or more target directories.

positional arguments:
  ENV_DIR               A directory to create the environment in.

optional arguments:
  -h, --help            show this help message and exit
  --system-site-packages
                        Give the virtual environment access to the system
                        site-packages dir.
  --symlinks            Try to use symlinks rather than copies, when symlinks
                        are not the default for the platform.
  --copies              Try to use copies rather than symlinks, even when
                        symlinks are the default for the platform.
  --clear               Delete the contents of the environment directory if it
                        already exists, before environment creation.
  --upgrade             Upgrade the environment directory to use this version
                        of Python, assuming Python has been upgraded in-place.
  --without-pip         Skips installing or upgrading pip in the virtual
                        environment (pip is bootstrapped by default)
  --prompt PROMPT       Provides an alternative prompt prefix for this
                        environment.
  --upgrade-deps        Upgrade core dependencies (pip) to the
                        latest version in PyPI

Once an environment has been created, you may wish to activate it, e.g. by
sourcing an activate script in its bin directory.

バージョン 3.12 で変更: setuptools is no longer a core venv dependency.

バージョン 3.9 で変更: pip と setuptools を PyPI での最新版に更新するには、--upgrade-deps オプションを追加してください。

バージョン 3.4 で変更: デフォルトで pip をインストールします。--without-pip と --copies オプションを追加しました。

バージョン 3.4 で変更: 以前のバージョンでは、対象となるディレクトリが既に存在していた場合は、 --clear オプションや --upgrade オプションを付けない限りはエラーを送出していました。

注釈

Windows でもシンボリックリンクはサポートされていますが、シンボリックリンクを使うのは推奨されません。特に注目すべきなのは、ファイルエクスプローラ上で python.exe をダブルクリックすると、シンボリックリンクを貪欲に解決し仮想環境を無視するということです。

注釈

Microsoft Windows では、ユーザー向けの実行ポリシーを設定して Activate.ps1 スクリプトが使えるようにする必要があるかもしれません。この設定は次の PowerShell コマンドでできます:

PS C:> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

さらに詳しくは About Execution Policies [https://go.microsoft.com/fwlink/?LinkID=135170] を参照してください。

作成された pyvenv.cfg ファイルには、include-system-site-packages キーも含まれます。これは venv が --system-site-packages オプションをつけて実行されたなら true で、そうでなければ false です。

--without-pip オプションが与えられない限り、pip を仮想環境でブートするために ensurepip が呼ばれます。

venv には複数のパスを渡すことができ、その場合はそれぞれのパスに同一の仮想環境が作成されます。

仮想環境のしくみ

Python インタプリタが仮想環境で実行しているとき、sys.prefix と sys.exec_prefix は仮想環境のディレクトリを指し示し、 sys.base_prefix と sys.base_exec_prefix は仮想環境の作成に使われたベース Python のディレクトリを指し示します。sys.prefix != sys.base_prefix を調べれば、現在のインタプリタが仮想環境で実行しているかを判定できます。

A virtual environment may be "activated" using a script in its binary directory (bin on POSIX; Scripts on Windows). This will prepend that directory to your PATH, so that running python will invoke the environment's Python interpreter and you can run installed scripts without having to use their full path. The invocation of the activation script is platform-specific (<venv> must be replaced by the path to the directory containing the virtual environment):

プラットフォーム

シェル

仮想環境を有効化するためのコマンド

POSIX

bash/zsh

$ source <venv>/bin/activate

fish

$ source <venv>/bin/activate.fish

csh/tcsh

$ source <venv>/bin/activate.csh

PowerShell

$ <venv>/bin/Activate.ps1

Windows

cmd.exe

C:\> <venv>\Scripts\activate.bat

PowerShell

PS C:\> <venv>\Scripts\Activate.ps1

Added in version 3.4: fish および csh の有効化スクリプト。

Added in version 3.8: PowerShell Core のサポートのために POSIX 環境にインストールされた、PowerShell 有効化スクリプト。

Python を呼び出すときに仮想環境の Python インタプリタへのフルパスを指定すれば良いだけなので、仮想環境をアクティベートする 必要 はありません。さらに、仮想環境にインストールされたすべてのスクリプトはアクティベートせずとも実行可能なはずです。

In order to achieve this, scripts installed into virtual environments have a "shebang" line which points to the environment's Python interpreter, i.e. #!/<path-to-venv>/bin/python. This means that the script will run with that interpreter regardless of the value of PATH. On Windows, "shebang" line processing is supported if you have the Windows の Python ランチャ installed. Thus, double-clicking an installed script in a Windows Explorer window should run it with the correct interpreter without the environment needing to be activated or on the PATH.

仮想環境がアクティベートされると、VIRTUAL_ENV 環境変数の値が仮想環境へのパスに設定されます。アクティベートしなくても仮想環境を使うことは可能なため、仮想環境が使われているか否かの判断を VIRTUAL_ENV に頼ることはできません。

警告

仮想環境にインストールされたスクリプトは仮想環境がアクティベートされていることを前提とすべきではないため、shebang の行は仮想環境のインタプリタへの絶対パスを含みます。このため、本質的に、仮想環境は一般の場合ポータブルではありません。いつでも仮想環境を再作成できる簡単な方法を持っておくべきです（例えば、requirements.txt という requirements ファイルがあれば、仮想環境の pip を用いて、pip install -r requirements.txt を呼び出すことで、仮想環境が必要とするすべてのパッケージをインストールできます）。何らかの理由で仮想環境を別の場所に移動する必要がある場合は、新しい場所で仮想環境を再作成し、古い場所にある仮想環境を削除してください。仮想環境の親ディレクトリを移動したため仮想環境も移動された場合は、新しい場所で仮想環境を再作成する必要があります。さもなくば、仮想環境にインストールされたソフトウェアが想定通りに動作しない可能性があります。

シェルで deactivate と入力することで仮想環境を無効化できます。厳密な仕組みはプラットフォーム固有であり、内部の実装詳細です (たいていはスクリプトかシェル関数が使われます)。

API

上述の高水準のメソッドは、サードパーティの仮想環境の作成者が環境の作成を必要に応じてカスタマイズするための機構を提供する簡素な API を利用します。それが EnvBuilder クラスです。

class venv.EnvBuilder(system_site_packages=False, clear=False, symlinks=False, upgrade=False, with_pip=False, prompt=None, upgrade_deps=False)

EnvBuilder クラスを実体化するときに、以下のキーワード引数を受け取ります:

system_site_packages -- 真偽値で、システムの Python の site-packages を仮想環境から利用できるかどうかを示します (デフォルト: False)。

clear -- 真偽値で、真の場合環境を作成する前に既存の対象ディレクトリの中身を削除します。

symlinks -- 真偽値で、Python のバイナリをコピーせずにシンボリックの作成を試みるかどうかを示します。

upgrade -- 真偽値で、真の場合実行中の Python で既存の環境をアップグレードします。その Python がインプレースでアップグレードされたときに用います。デフォルトは False です。

with_pip -- 真偽値で、真の場合仮想環境に pip がインストールされていることを保証します。--default-pip オプションで ensurepip を使用します。

prompt -- 仮想環境がアクティベートされたときに使う文字列（デフォルトは None のため、仮想環境のディレクトリ名が使われます）。もし特殊な文字列 "." が渡された場合、カレントディレクトリのベース名がプロンプトとして用いられます。

upgrade_deps -- venv のベースのモジュールを PyPI での最新版にアップデートします。

バージョン 3.4 で変更: with_pip 引数が追加されました。

バージョン 3.6 で変更: prompt 引数が追加されました。

バージョン 3.9 で変更: upgrade_deps 引数が追加されました。

サードパーティーの仮想環境ツールの作成者は、 EnvBuilder を継承して使うことができます。

返される env-builder オブジェクトには create というメソッドがあります:

create(env_dir)

仮想環境を持つことになるターゲットディレクトリ (絶対パスあるいは現在のディレクトリからの相対パス) を指定し、仮想環境を作成します。 create メソッドは、指定されたディレクトリに仮想環境を構築するか、適切な例外を送出します。

EnvBuilder クラスの create メソッドは、サブクラスのカスタマイズに使えるフックを説明します:

def create(self, env_dir):
    """
    Create a virtualized Python environment in a directory.
    env_dir is the target directory to create an environment in.
    """
    env_dir = os.path.abspath(env_dir)
    context = self.ensure_directories(env_dir)
    self.create_configuration(context)
    self.setup_python(context)
    self.setup_scripts(context)
    self.post_setup(context)

メソッド ensure_directories(), create_configuration(), setup_python(), setup_scripts(), post_setup() はそれぞれオーバーライドできます。

ensure_directories(env_dir)

仮想環境のディレクトリとすべての必要なサブディレクトリのうちまだ存在しないものを作成し、コンテキストオブジェクトを返します。このコンテキストオブジェクトは他のメソッドで使うために（パスなどの）属性を保持しているだけです。もし EnvBuilder が clear=True の引数で作成された場合、仮想環境のディレクトリの中身は消去され、すべての必要なサブディレクトリが再作成されます。

返されるコンテキストオブジェクトは以下の属性を持った types.SimpleNamespace です:

env_dir - 仮想環境の場所。アクティベートスクリプトの中の __VENV_DIR__ で使われます（install_scripts() を参照してください）。

env_name - 仮想環境の名前。アクティベートスクリプトの中の __VENV_NAME__ で使われます（install_scripts() を参照してください）。

prompt - アクティベートスクリプトで使われるプロンプト。アクティベートスクリプトの中の __VENV_PROMPT__ で使われます（install_scripts() を参照してください）。

executable - 仮想環境の元になっている Python 実行可能ファイル。これは仮想環境が別の仮想環境から作られた場合も考慮に入れます。

inc_path - 仮想環境の include パス。

lib_path - 仮想環境の purelib パス。

bin_path - 仮想環境のスクリプトのパス。

bin_name - 仮想環境の場所に相対的な、スクリプトのパス。アクティベートスクリプトの中の __VENV_BIN_NAME__ で使われます（install_scripts() を参照してください）。

env_exe - 仮想環境の中の Python インタプリタの名前。アクティベートスクリプトの中の __VENV_PYTHON__ で使われます（install_scripts() を参照してください）。

env_exec_cmd - ファイルシステムのリダイレクトを考慮に入れた、Python インタプリタの名前。これは仮想環境の中で Python を実行するのに使えます。

バージョン 3.11 で変更: venv システム構成インストールスキーム は作成されたディレクトリのパスを構築するために使われます。

バージョン 3.12 で変更: コンテキストに lib_path 属性が追加され、コンテキストオブジェクトがドキュメントに追加されました。

create_configuration(context)

仮想環境に pyvenv.cfg 設定ファイルを作成します。

setup_python(context)

Python 実行ファイルのコピーまたはシンボリックリンクを仮想環境に作成します。 POSIX システムで、特定の python3.x 実行ファイルが使われている場合、同じ名前のファイルが既に存在していない限り、 python および python3 へのシンボリックリンクがその実行ファイルを指すように作成されます。

setup_scripts(context)

プラットフォームに対応した有効化スクリプトを仮想環境にインストールします。

upgrade_dependencies(context)

Upgrades the core venv dependency packages (currently pip) in the environment. This is done by shelling out to the pip executable in the environment.

Added in version 3.9.

バージョン 3.12 で変更: setuptools is no longer a core venv dependency.

post_setup(context)

サードパーティーライブラリがオーバーライドするための空のメソッドです。このメソッドをオーバーライドして、仮想環境構築後にパッケージのプリインストールなどのステップを実装できます。

バージョン 3.7.2 で変更: Windows では、バイナリそのものをコピーするのではなく、python[w].exe にリダイレクトを行うスクリプトを使うようになりました。 3.7.2 でのみ、ソース群でビルドを実行しているのでなければ setup_python() だけは何もしません。

バージョン 3.7.3 で変更: Windows では、 setup_scripts() の代わりに setup_python() の一部としてリダイレクトを行うスクリプトをコピーします。これは 3.7.2 には当てはまりません。シンボリックリンクを使ったときは、オリジナルの実行ファイルをコピーします。

これらに加えて、 EnvBuilder は setup_scripts() やサブクラスの post_setup() が仮想環境にスクリプトをインストールするためのユーティリティーメソッドを提供しています。

install_scripts(context, path)

path は "common", "posix", "nt" ディレクトリを格納したディレクトリへのパスです。各サブディレクトリには仮想環境の bin ディレクトリにインストールするスクリプトを格納します。 "common" の中身と、 os.name に一致するディレクトリの中身を、以下の置換処理を行いながらコピーします:

__VENV_DIR__ は仮想環境ディレクトリの絶対パスに置換されます。

__VENV_NAME__ は仮想環境の名前 (仮想環境ディレクトリのパスの最後の部分) に置換されます。

__VENV_PROMPT__ はプロンプトに置換されます (括弧で囲まれ空白が続く環境名)。

__VENV_BIN_NAME__ は bin ディレクトリ名 (bin か Scripts) に置換されます。

__VENV_PYTHON__ は仮想環境の Python 実行ファイルの絶対パスに置換されます。

(既存環境のアップグレード中は) ディレクトリは存在しても構いません。

モジュールレベルの簡易関数もあります:

venv.create(env_dir, system_site_packages=False, clear=False, symlinks=False, with_pip=False, prompt=None, upgrade_deps=False)

EnvBuilder を指定されたキーワード引数を使って作成し、その create() メソッドに env_dir 引数を渡して実行します。

Added in version 3.3.

バージョン 3.4 で変更: with_pip 引数が追加されました。

バージョン 3.6 で変更: prompt 引数が追加されました。

バージョン 3.9 で変更: upgrade_deps 引数が追加されました。

EnvBuilder を拡張する例

次のスクリプトで、作成された仮想環境に setuptools と pip をインストールするサブクラスを実装して EnvBuilder を拡張する方法を示します:

import os
import os.path
from subprocess import Popen, PIPE
import sys
from threading import Thread
from urllib.parse import urlparse
from urllib.request import urlretrieve
import venv

class ExtendedEnvBuilder(venv.EnvBuilder):
    """
    This builder installs setuptools and pip so that you can pip or
    easy_install other packages into the created virtual environment.

    :param nodist: If true, setuptools and pip are not installed into the
                   created virtual environment.
    :param nopip: If true, pip is not installed into the created
                  virtual environment.
    :param progress: If setuptools or pip are installed, the progress of the
                     installation can be monitored by passing a progress
                     callable. If specified, it is called with two
                     arguments: a string indicating some progress, and a
                     context indicating where the string is coming from.
                     The context argument can have one of three values:
                     'main', indicating that it is called from virtualize()
                     itself, and 'stdout' and 'stderr', which are obtained
                     by reading lines from the output streams of a subprocess
                     which is used to install the app.

                     If a callable is not specified, default progress
                     information is output to sys.stderr.
    """

    def __init__(self, *args, **kwargs):
        self.nodist = kwargs.pop('nodist', False)
        self.nopip = kwargs.pop('nopip', False)
        self.progress = kwargs.pop('progress', None)
        self.verbose = kwargs.pop('verbose', False)
        super().__init__(*args, **kwargs)

    def post_setup(self, context):
        """
        Set up any packages which need to be pre-installed into the
        virtual environment being created.

        :param context: The information for the virtual environment
                        creation request being processed.
        """
        os.environ['VIRTUAL_ENV'] = context.env_dir
        if not self.nodist:
            self.install_setuptools(context)
        # Can't install pip without setuptools
        if not self.nopip and not self.nodist:
            self.install_pip(context)

    def reader(self, stream, context):
        """
        Read lines from a subprocess' output stream and either pass to a progress
        callable (if specified) or write progress information to sys.stderr.
        """
        progress = self.progress
        while True:
            s = stream.readline()
            if not s:
                break
            if progress is not None:
                progress(s, context)
            else:
                if not self.verbose:
                    sys.stderr.write('.')
                else:
                    sys.stderr.write(s.decode('utf-8'))
                sys.stderr.flush()
        stream.close()

    def install_script(self, context, name, url):
        _, _, path, _, _, _ = urlparse(url)
        fn = os.path.split(path)[-1]
        binpath = context.bin_path
        distpath = os.path.join(binpath, fn)
        # Download script into the virtual environment's binaries folder
        urlretrieve(url, distpath)
        progress = self.progress
        if self.verbose:
            term = '\n'
        else:
            term = ''
        if progress is not None:
            progress('Installing %s ...%s' % (name, term), 'main')
        else:
            sys.stderr.write('Installing %s ...%s' % (name, term))
            sys.stderr.flush()
        # Install in the virtual environment
        args = [context.env_exe, fn]
        p = Popen(args, stdout=PIPE, stderr=PIPE, cwd=binpath)
        t1 = Thread(target=self.reader, args=(p.stdout, 'stdout'))
        t1.start()
        t2 = Thread(target=self.reader, args=(p.stderr, 'stderr'))
        t2.start()
        p.wait()
        t1.join()
        t2.join()
        if progress is not None:
            progress('done.', 'main')
        else:
            sys.stderr.write('done.\n')
        # Clean up - no longer needed
        os.unlink(distpath)

    def install_setuptools(self, context):
        """
        Install setuptools in the virtual environment.

        :param context: The information for the virtual environment
                        creation request being processed.
        """
        url = "https://bootstrap.pypa.io/ez_setup.py"
        self.install_script(context, 'setuptools', url)
        # clear up the setuptools archive which gets downloaded
        pred = lambda o: o.startswith('setuptools-') and o.endswith('.tar.gz')
        files = filter(pred, os.listdir(context.bin_path))
        for f in files:
            f = os.path.join(context.bin_path, f)
            os.unlink(f)

    def install_pip(self, context):
        """
        Install pip in the virtual environment.

        :param context: The information for the virtual environment
                        creation request being processed.
        """
        url = 'https://bootstrap.pypa.io/get-pip.py'
        self.install_script(context, 'pip', url)

def main(args=None):
    import argparse

    parser = argparse.ArgumentParser(prog=__name__,
                                     description='Creates virtual Python '
                                                 'environments in one or '
                                                 'more target '
                                                 'directories.')
    parser.add_argument('dirs', metavar='ENV_DIR', nargs='+',
                        help='A directory in which to create the '
                             'virtual environment.')
    parser.add_argument('--no-setuptools', default=False,
                        action='store_true', dest='nodist',
                        help="Don't install setuptools or pip in the "
                             "virtual environment.")
    parser.add_argument('--no-pip', default=False,
                        action='store_true', dest='nopip',
                        help="Don't install pip in the virtual "
                             "environment.")
    parser.add_argument('--system-site-packages', default=False,
                        action='store_true', dest='system_site',
                        help='Give the virtual environment access to the '
                             'system site-packages dir.')
    if os.name == 'nt':
        use_symlinks = False
    else:
        use_symlinks = True
    parser.add_argument('--symlinks', default=use_symlinks,
                        action='store_true', dest='symlinks',
                        help='Try to use symlinks rather than copies, '
                             'when symlinks are not the default for '
                             'the platform.')
    parser.add_argument('--clear', default=False, action='store_true',
                        dest='clear', help='Delete the contents of the '
                                           'virtual environment '
                                           'directory if it already '
                                           'exists, before virtual '
                                           'environment creation.')
    parser.add_argument('--upgrade', default=False, action='store_true',
                        dest='upgrade', help='Upgrade the virtual '
                                             'environment directory to '
                                             'use this version of '
                                             'Python, assuming Python '
                                             'has been upgraded '
                                             'in-place.')
    parser.add_argument('--verbose', default=False, action='store_true',
                        dest='verbose', help='Display the output '
                                             'from the scripts which '
                                             'install setuptools and pip.')
    options = parser.parse_args(args)
    if options.upgrade and options.clear:
        raise ValueError('you cannot supply --upgrade and --clear together.')
    builder = ExtendedEnvBuilder(system_site_packages=options.system_site,
                                   clear=options.clear,
                                   symlinks=options.symlinks,
                                   upgrade=options.upgrade,
                                   nodist=options.nodist,
                                   nopip=options.nopip,
                                   verbose=options.verbose)
    for d in options.dirs:
        builder.create(d)

if __name__ == '__main__':
    rc = 1
    try:
        main()
        rc = 0
    except Exception as e:
        print('Error: %s' % e, file=sys.stderr)
    sys.exit(rc)

このスクリプトは オンライン [https://gist.github.com/vsajip/4673395] よりダウンロードすることも可能です。

zipapp --- Manage executable Python zip archives

Added in version 3.5.

ソースコード: Lib/zipapp.py [https://github.com/python/cpython/tree/3.12/Lib/zipapp.py]

このモジュールは Python コードを含む zip ファイルの作成を行うツールを提供します。 zip ファイルは Python インタープリタで直接実行することが出来ます。このモジュールは コマンドラインインターフェイス と Python API の両方を提供します。

基本的な例

実行可能なアーカイブを Python コードを含むディレクトリから作成する為に コマンドラインインターフェイス をどのように利用することができるかを以下に例示します。アーカイブは実行時にアーカイブ内の myapp モジュールから main 関数を実行します。

$ python -m zipapp myapp -m "myapp:main"
$ python myapp.pyz
<output from myapp>

コマンドラインインターフェイス

コマンドラインからプログラムとして呼び出す場合は、次の形式を使用います:

$ python -m zipapp source [options]

source がディレクトリである場合、 source ディレクトリの内容からアーカイブを作成します。 source がファイルである場合、 source ファイル自身をアーカイブ化し、保存先アーカイブへコピーします。(または --info オプションが指定されている場合はファイルのシェバン行が表示されます。)

以下のオプションが解釈されます:

-o <output>, --output=<output>

出力を output に指定した名前のファイルへ書込みます。このオプションが指定されていない場合、出力先ファイル名は入力元 source と同じになり、 .pyz 拡張子が付与されます。ファイル名が明示的に指定されている場合は、指定されたファイル名を使用します。(必要であれば .pyz 拡張子が含まれます。)

source がアーカイブである場合は、出力先ファイル名を必ず指定しなければなりません。 (source がアーカイブである場合は output を必ず source とは別の名前にしてください。)

-p <interpreter>, --python=<interpreter>

実行コマンドとしての interpreter を指定する #! 行を書庫に追加します。また、POSIX では書庫を実行可能にします。デフォルトでは #! 行を書かず、ファイルを実行可能にはしません。

-m <mainfn>, --main=<mainfn>

mainfn を実行するアーカイブへ __main__.py ファイルを書込んでください。 mainfn 引数は "pkg.mod:fn" の形式で指定します。 "pkg.mod" の場所はアーカイブ内の package/module です。 "fn" は指定した module から呼出すことのできる関数です。 __main__.py ファイルが module から呼出すことのできる関数を実行します。

書庫をコピーする際、 --main を指定することは出来ません。

-c, --compress

Compress files with the deflate method, reducing the size of the output file. By default, files are stored uncompressed in the archive.

書庫をコピーする際、 --compress に効果はありません。

Added in version 3.7.

--info

診断するために書庫に埋め込まれたインタープリタを表示します。この場合、他の全てのオプションは無視され、SOURCE はディレクトリではなく書庫でなければなりません。

-h, --help

簡単な使用法を表示して終了します。

Python API

このモジュールは 2 つの簡便関数を定義しています:

zipapp.create_archive(source, target=None, interpreter=None, main=None, filter=None, compressed=False)

source からアプリケーション書庫を作成します。ソースは以下のいずれかです:

ディレクトリ名、または新しいアプリケーションアーカイブがディレクトリのコンテンツから作成される場合に path-like object オブジェクトが参照するディレクトリ。

既存のアプリケーションアーカイブファイルの名前、または(interpreter 引数に指定した値を反映し、修正する)アーカイブへファイルがコピーされる場合に path-like object オブジェクトが参照するファイル。

バイトモードの読込みで開くファイルオブジェクト。ファイルの内容がアプリケーションアーカイブとなり、ファイルオブジェクトがアーカイブの起点となります。

target 引数は作成される書庫が書き込まれる場所を決めます:

ファイル名、または path-like object オブジェクトを指定した場合、アーカイブは指定したファイルへ書き込まれます。

開いているファイルオブジェクトを指定した場合、アーカイブはそのファイルオブジェクトへ書込みを行ないます。ファイルオブジェクトは必ずバイトモードの書込みで開いてください。

target を指定しないか None を渡した場合、 source は必ずディレクトリでなければならず、target は source のファイル名に .pyz 拡張子を付与したファイル名となります。

interpreter 引数はアーカイブが実行時に使用する Python インタープリタの名前を指定します。インタープリタ名は "シェバン" 行としてアーカイブの起点に書込まれます。 POSIX では OS によってシェバンが解釈され、 Windows では Python ランチャーによって扱われます。シェバン行が書込まれていない場合は interpreter の結果を無視します。 interpreter が指定されており、 target がファイル名である場合、 target ファイルの実行可能ビットが設定されます。

main 引数はアーカイブのメインプログラムとして使用する callable の名前を指定します。 main 引数は source がディレクトリであり、 source が既に __main__.py ファイルを保持していない場合に限り、指定することができます。 main 引数は "pkg.module:callable" の形式を取り、アーカイブは "pkg.module" をインポートして実行され、指定した callable を引数なしで実行します。 source がディレクトリであり、 __main__.py が含まれていない場合、 main は無視すべきエラーとなり、作成されたアーカイブには実行可能ビットが設定されません。

The optional filter argument specifies a callback function that is passed a Path object representing the path to the file being added (relative to the source directory). It should return True if the file is to be added.

The optional compressed argument determines whether files are compressed. If set to True, files in the archive are compressed with the deflate method; otherwise, files are stored uncompressed. This argument has no effect when copying an existing archive.

source または target へファイルオブジェクトを指定した場合、 caller が create_archive の呼出し後にオブジェクトを閉じます。

既存のアーカイブをコピーする際、ファイルオブジェクトは read , readline , write メソッドのみを提供します。アーカイブをディレクトリから作成する際、 target がファイルオブジェクトである場合は、 zipfile.ZipFile クラスへ渡されます。必ずクラスが必要とするメソッドを提供してください。

バージョン 3.7 で変更: Added the filter and compressed parameters.

zipapp.get_interpreter(archive)

アーカイブの最初の行の #! に指定されたインタープリタを返します。 #! が無い場合は None を返します。 archive 引数は、ファイル名またはバイトモードの読込みで開いたファイルに準じるオブジェクトを指定することができ、アーカイブの起点で決定されます。

使用例

ディレクトリを書庫に圧縮し、実行します。

$ python -m zipapp myapp
$ python myapp.pyz
<output from myapp>

同じことを create_archive() 関数を使用して行うことができます:

>>> import zipapp
>>> zipapp.create_archive('myapp', 'myapp.pyz')

POSIX でアプリケーションを直接実行可能にするには使用するインタープリタを指定します。

$ python -m zipapp myapp -p "/usr/bin/env python"
$ ./myapp.pyz
<output from myapp>

シバン行を既存の書庫で置換するには、 create_archive() function: を使用して変更された書庫を作成します:

>>> import zipapp
>>> zipapp.create_archive('old_archive.pyz', 'new_archive.pyz', '/usr/bin/python3')

アーカイブ内のファイルを更新するには BytesIO オブジェクトを使用してメモリーへ格納し、元のファイルを上書きして置換してください。ファイルを上書きする際にエラーが発生し、元のファイルが失われる危険性があることに注意してください。このコードは上記のようなエラーからファイルを保護しませんが、プロダクションコードは保護するべきです。この方法はアーカイブがメモリーに収まる場合にのみ動作します:

>>> 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())

インタープリタの指定

Note that if you specify an interpreter and then distribute your application archive, you need to ensure that the interpreter used is portable. The Python launcher for Windows supports most common forms of POSIX #! line, but there are other issues to consider:

If you use "/usr/bin/env python" (or other forms of the "python" command, such as "/usr/bin/python"), you need to consider that your users may have either Python 2 or Python 3 as their default, and write your code to work under both versions.

If you use an explicit version, for example "/usr/bin/env python3" your application will not work for users who do not have that version. (This may be what you want if you have not made your code Python 2 compatible).

There is no way to say "python X.Y or later", so be careful of using an exact version like "/usr/bin/env python3.4" as you will need to change your shebang line for users of Python 3.5, for example.

Typically, you should use an "/usr/bin/env python2" or "/usr/bin/env python3", depending on whether your code is written for Python 2 or 3.

Creating Standalone Applications with zipapp

Using the zipapp module, it is possible to create self-contained Python programs, which can be distributed to end users who only need to have a suitable version of Python installed on their system. The key to doing this is to bundle all of the application's dependencies into the archive, along with the application code.

The steps to create a standalone archive are as follows:

Create your application in a directory as normal, so you have a myapp directory containing a __main__.py file, and any supporting application code.

Install all of your application's dependencies into the myapp directory, using pip:

$ python -m pip install -r requirements.txt --target myapp

(this assumes you have your project requirements in a requirements.txt file - if not, you can just list the dependencies manually on the pip command line).

Package the application using:

$ python -m zipapp -p "interpreter" myapp

This will produce a standalone executable, which can be run on any machine with the appropriate interpreter available. See インタープリタの指定 for details. It can be shipped to users as a single file.

On Unix, the myapp.pyz file is executable as it stands. You can rename the file to remove the .pyz extension if you prefer a "plain" command name. On Windows, the myapp.pyz[w] file is executable by virtue of the fact that the Python interpreter registers the .pyz and .pyzw file extensions when installed.

Caveats

If your application depends on a package that includes a C extension, that package cannot be run from a zip file (this is an OS limitation, as executable code must be present in the filesystem for the OS loader to load it). In this case, you can exclude that dependency from the zipfile, and either require your users to have it installed, or ship it alongside your zipfile and add code to your __main__.py to include the directory containing the unzipped module in sys.path. In this case, you will need to make sure to ship appropriate binaries for your target architecture(s) (and potentially pick the correct version to add to sys.path at runtime, based on the user's machine).

The Python Zip Application Archive Format

Python has been able to execute zip files which contain a __main__.py file since version 2.6. In order to be executed by Python, an application archive simply has to be a standard zip file containing a __main__.py file which will be run as the entry point for the application. As usual for any Python script, the parent of the script (in this case the zip file) will be placed on sys.path and thus further modules can be imported from the zip file.

The zip file format allows arbitrary data to be prepended to a zip file. The zip application format uses this ability to prepend a standard POSIX "shebang" line to the file (#!/path/to/interpreter).

Formally, the Python zip application format is therefore:

An optional shebang line, containing the characters b'#!' followed by an interpreter name, and then a newline (b'\n') character. The interpreter name can be anything acceptable to the OS "shebang" processing, or the Python launcher on Windows. The interpreter should be encoded in UTF-8 on Windows, and in sys.getfilesystemencoding() on POSIX.

Standard zipfile data, as generated by the zipfile module. The zipfile content must include a file called __main__.py (which must be in the "root" of the zipfile - i.e., it cannot be in a subdirectory). The zipfile data can be compressed or uncompressed.

If an application archive has a shebang line, it may have the executable bit set on POSIX systems, to allow it to be executed directly.

There is no requirement that the tools in this module are used to create application archives - the module is a convenience, but archives in the above format created by any means are acceptable to Python.

Python ランタイムサービス

この章では、Python インタープリタや Python 環境に深く関連する各種の機能を解説します。以下に一覧を示します:

sys --- System-specific parameters and functions

sys.monitoring --- Execution event monitoring

Tool identifiers

Registering and using tools

Events

Local events

Ancillary events

Other events

The STOP_ITERATION event

Turning events on and off

Setting events globally

Per code object events

Disabling events

Registering callback functions

Callback function arguments

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

構成変数

インストールパス

User scheme

posix_user

nt_user

osx_framework_user

Home scheme

posix_home

Prefix scheme

posix_prefix

nt

Installation path functions

その他の関数

sysconfig をスクリプトとして使う

builtins --- Built-in objects

__main__ --- Top-level code environment

__name__ == '__main__'

「トップレベルのスクリプト環境」とは

通常の使われ方

Packaging Considerations

__main__.py in Python Packages

通常の使われ方

import __main__

warnings --- Warning control

警告カテゴリ

警告フィルタ

Describing Warning Filters

デフォルトの警告フィルタ

Overriding the default filter

一時的に警告を抑制する

警告のテスト

Updating Code For New Versions of Dependencies

利用可能な関数

利用可能なコンテキストマネージャー

dataclasses --- Data Classes

モジュールの内容

初期化後の処理

クラス変数

初期化限定変数

凍結されたインスタンス

継承

Re-ordering of keyword-only parameters in __init__()

デフォルトファクトリ関数

可変なデフォルト値

Descriptor-typed fields

contextlib --- with 文コンテキスト用ユーティリティ

ユーティリティ

例とレシピ

可変数個のコンテキストマネージャーをサポートする

__enter__ メソッドからの例外をキャッチする

__enter__ 実装内のクリーンアップ

try-finally + flag 変数パターンを置き換える

コンテキストマネージャーを関数デコレーターとして使う

単回使用、再利用可能、およびリエントラントなコンテキストマネージャ

リエントラントなコンテキストマネージャ

再利用可能なコンテキストマネージャ

abc --- Abstract Base Classes

atexit --- Exit handlers

atexit の例

traceback --- Print or retrieve a stack traceback

TracebackException オブジェクト

StackSummary オブジェクト

FrameSummary オブジェクト

トレースバックの例

__future__ --- Future statement definitions

モジュールコンテンツ

gc --- Garbage Collector interface

inspect --- Inspect live objects

型とメンバー

ソースコードの情報取得

Signature オブジェクトで呼び出し可能オブジェクトを内省する

クラスと関数

インタープリタスタック

属性の静的なフェッチ

Current State of Generators, Coroutines, and Asynchronous Generators

Code Objects Bit Flags

Buffer flags

コマンドラインインターフェイス

site --- Site-specific configuration hook

sitecustomize

usercustomize

readline の設定

モジュールの内容

コマンドラインインターフェイス

sys --- System-specific parameters and functions

このモジュールでは、インタプリタで使用・管理している変数や、インタプリタの動作に深く関連する関数を定義しています。このモジュールは常に利用可能です。

sys.abiflags

Python が標準的な configure でビルトされた POSIX システムにおいて、PEP 3149 [https://peps.python.org/pep-3149/] に記述された ABI フラグを含みます。

Added in version 3.2.

バージョン 3.8 で変更: デフォルトのフラグは空文字列になりました。 (pymalloc のための m フラグが取り除かれました)

利用可能な環境: Unix。

sys.addaudithook(hook)

呼び出し可能な hook を現在の(サブ)インタープリタのアクティブな監査用フックのリストに加えます。

When an auditing event is raised through the 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 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 PySys_AddAuditHook() before initialising the runtime, and any modules allowing arbitrary memory modification (such as ctypes) should be completely removed or closely monitored.

引数無しで 監査イベント sys.addaudithook を送出します。

See the audit events table for all events raised by CPython, and PEP 578 [https://peps.python.org/pep-0578/] for the original design discussion.

Added in version 3.8.

バージョン 3.8.1 で変更: RuntimeError ではない Exception は抑制されなくなりました。

CPython 実装の詳細: When tracing is enabled (see settrace()), Python hooks are only traced if the callable has a __cantrace__ member that is set to a true value. Otherwise, trace functions will skip the hook.

sys.argv

Pythonスクリプトに渡されたコマンドライン引数のリスト。 argv[0] はスクリプトの名前となりますが、フルパス名かどうかは、OSによって異なります。コマンドライン引数に -c を付けて Pythonを起動した場合、 argv[0] は文字列 '-c' となります。スクリプト名なしでPythonを起動した場合、 argv[0] は空文字列になります。

標準入力もしくはコマンドライン引数で指定されたファイルのリストに渡ってループするには、 fileinput モジュールを参照してください。

See also sys.orig_argv.

注釈

Unix では、コマンドライン引数は OS からバイト列で渡されます。 Python はそれをファイルシステムエンコーディングと "surrogateescape" エラーハンドラを使ってデコードします。オリジナルのバイト列が必要なときには、 [os.fsencode(arg) for arg in sys.argv] で取得できます。

sys.audit(event, *args)

Raise an auditing event and trigger any active auditing hooks. event is a string identifying the event, and args may contain optional arguments with more information about the event. The number and types of arguments for a given event are considered a public and stable API and should not be modified between releases.

For example, one auditing event is named os.chdir. This event has one argument called path that will contain the requested new working directory.

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 sys.addaudithook() or PySys_AddAuditHook() functions.

The native equivalent of this function is PySys_Audit(). Using the native function is preferred when possible.

See the audit events table for all events raised by CPython.

Added in version 3.8.

sys.base_exec_prefix

Python の起動中、site.py が実行される前、exec_prefix と同じ値が設定されます。仮想環境 で実行されたのでなければ、この値は変化しません; site.py が仮想環境で使用されていると判断した場合、prefix および exec_prefix は仮想環境を示すよう変更され、base_prefix および base_exec_prefix は引き続き (仮想環境が作成された) ベースの Python インストール先を示します。

Added in version 3.3.

sys.base_prefix

Python の起動中、site.py が実行される前、prefix と同じ値が設定されます。仮想環境 で実行されたのでなければ、この値は変化しません; site.py が仮想環境で使用されていると検出した場合、prefix および exec_prefix は仮想環境を示すよう変更され、base_prefix および base_exec_prefix は引き続き (仮想環境が作成された) ベースの Python インストール先を示します。

Added in version 3.3.

sys.byteorder

プラットフォームのバイト順を示します。ビッグエンディアン (最上位バイトが先頭) のプラットフォームでは 'big', リトルエンディアン (最下位バイトが先頭) では 'little' となります。

sys.builtin_module_names

コンパイル時にPythonインタプリタに組み込まれた、全てのモジュール名を含む文字列のタプル(この情報は、他の手段では取得することができません。 modules.keys() は、インポートされたモジュールのみのリストを返します。)

See also the sys.stdlib_module_names list.

sys.call_tracing(func, args)

Call 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 settrace() or setprofile() to avoid infinite recursion. call_tracing() enables explicit recursion of the tracing function.

sys.copyright

Python インタプリタの著作権を表示する文字列です。

sys._clear_type_cache()

内部の型キャッシュをクリアします。型キャッシュは属性とメソッドの検索を高速化するために利用されます。この関数は、参照リークをデバッグするときに不要な参照を削除するため だけ に利用してください。

この関数は、内部的かつ特殊な目的にのみ利用されるべきです。

sys._current_frames()

各スレッドの識別子を関数が呼ばれた時点のそのスレッドでアクティブになっている一番上のスタックフレームに結びつける辞書を返します。モジュール traceback の関数を使えばそのように与えられたフレームのコールスタックを構築できます。

この関数はデッドロックをデバッグするのに非常に有効です。デッドロック状態のスレッドの協調動作を必要としませんし、そういったスレッドのコールスタックはデッドロックである限りフリーズしたままです。デッドロックにないスレッドのフレームについては、そのフレームを調べるコードを呼んだ時にはそのスレッドの現在の実行状況とは関係ないところを指し示しているかもしれません。

この関数は、内部的かつ特殊な目的にのみ利用されるべきです。

引数無しで 監査イベント sys._current_frames を送出します。

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.

この関数は、内部的かつ特殊な目的にのみ利用されるべきです。

引数無しで 監査イベント sys._current_exceptions を送出します。

バージョン 3.12 で変更: Each value in the dictionary is now a single exception instance, rather than a 3-tuple as returned from sys.exc_info().

sys.breakpointhook()

このフック関数は組み込みの breakpoint() から呼ばれます。デフォルトでは、この関数は pdb デバッガに処理を移行させますが、他の関数を設定することもでき、使用するデバッガを選べます。

この関数のシグネチャは何を呼び出すかに依存します。例えば、(pdb.set_trace() などの) デフォルトの結び付けでは引数は求められませんが、追加の引数 (位置引数およびキーワード引数) を求める関数に結び付けるかもしれません。組み込みの breakpoint() 関数は、自身の *args と **kws をそのまま渡します。 breakpointhooks() の返り値が何であれ、そのまま breakpoint() から返されます。

デフォルトの実装では、最初に環境変数 PYTHONBREAKPOINT を調べます。それが "0" に設定されていた場合は、この関数はすぐに終了します。つまり何もしません。この環境変数が設定されていないか、空文字列に設定されていた場合は、 pdb.set_trace() が呼ばれます。それ以外の場合は、この変数は実行する関数の名前である必要があります。関数名の指定では、例えば package.subpackage.module.function のようなドットでつながれた Python のインポートの命名体系を使ったを使います。この場合では、 package.subpackage.module がインポートされ、そのインポートされたモジュールには function() という呼び出し可能オブジェクトがなくてはなりません。この関数が渡された *args と **kws で実行され、 function() の返り値が何であれ sys.breakpointhook() は組み込みの breakpoint() 関数にその値をそのまま返します。

PYTHONBREAKPOINT で指名された呼び出し可能オブジェクトのインポートで何かしら問題が起きた場合、 RuntimeWarning が報告されブレークポイントは無視されることに注意してください。

また、 sys.breakpointhook() がプログラム上で上書きされていた場合は PYTHONBREAKPOINT は 調べられない ことにも注意してください。

Added in version 3.7.

sys._debugmallocstats()

CPython のメモリアロケータの状態に関する低レベルの情報を標準エラー出力に出力します。

If Python is built in debug mode (configure --with-pydebug option), it also performs some expensive internal consistency checks.

Added in version 3.3.

CPython 実装の詳細: この関数は CPython 固有です。正確な出力形式は定義されていませんし、変更されるかもしれません。

sys.dllhandle

Python DLLのハンドルを示す整数です。

利用可能な環境: Windows 。

sys.displayhook(value)

value が None 以外の時、repr(value) を sys.stdout に出力し、builtins._ に保存します。repr(value) がエラーハンドラを sys.stdout.errors (おそらく 'strict') として sys.stdout.encoding にエンコードできない場合、エラーハンドラを 'backslashreplace' として sys.stdout.encoding にエンコードします。

sys.displayhook は、Pythonの対話セッションで入力された 式 が評価されたときに呼び出されます。対話セッションの出力をカスタマイズする場合、 sys.displayhook に引数の数が一つの関数を指定します。

擬似コード:

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

バージョン 3.2 で変更: UnicodeEncodeError には 'backslashreplace' エラーハンドラを指定してください。

sys.dont_write_bytecode

この値が真の時、Python はソースモジュールをインポートする時に .pyc ファイルを生成しません。この値は -B コマンドラインオプションと PYTHONDONTWRITEBYTECODE 環境変数の値によって、起動時に True か False に設定されますが、実行時にこの変数を変更してバイトコード生成を制御することもできます。

sys._emscripten_info

A named tuple holding information about the environment on the wasm32-emscripten platform. The named tuple is provisional and may change in the future.

_emscripten_info.emscripten_version

Emscripten version as tuple of ints (major, minor, micro), e.g. (3, 1, 8).

_emscripten_info.runtime

Runtime string, e.g. browser user agent, 'Node.js v14.18.2', or 'UNKNOWN'.

_emscripten_info.pthreads

True if Python is compiled with Emscripten pthreads support.

_emscripten_info.shared_memory

True if Python is compiled with shared memory support.

Availability: Emscripten.

Added in version 3.11.

sys.pycache_prefix

If this is set (not None), Python will write bytecode-cache .pyc files to (and read them from) a parallel directory tree rooted at this directory, rather than from __pycache__ directories in the source code tree. Any __pycache__ directories in the source code tree will be ignored and new .pyc files written within the pycache prefix. Thus if you use 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 -X pycache_prefix=PATH command-line option or the PYTHONPYCACHEPREFIX environment variable (command-line takes precedence). If neither are set, it is None.

Added in version 3.8.

sys.excepthook(type, value, traceback)

指定したトレースバックと例外を sys.stderr に出力します。

When an exception other than SystemExit is raised and uncaught, the interpreter calls 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 sys.excepthook.

引数 hook, type, value, traceback を指定して 監査イベント sys.excepthook を送出します。

参考

The sys.unraisablehook() function handles unraisable exceptions and the threading.excepthook() function handles exception raised by threading.Thread.run().

sys.__breakpointhook__

sys.__displayhook__

sys.__excepthook__

sys.__unraisablehook__

これらのオブジェクトはそれぞれ、プログラム起動時の breakpointhook, displayhook, excepthook, unraisablehook の値を保存しています。この値は、 breakpointhook, displayhook, excepthook, unraisablehook に不正なオブジェクトや別のオブジェクトが指定された場合に、元の値に復旧するために使用します。

Added in version 3.7: __breakpointhook__

Added in version 3.8: __unraisablehook__

sys.exception()

This function, when called while an exception handler is executing (such as an except or 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 None.

Added in version 3.11.

sys.exc_info()

This function returns the old-style representation of the handled exception. If an exception e is currently handled (so exception() would return e), exc_info() returns the tuple (type(e), e, e.__traceback__). That is, a tuple containing the type of the exception (a subclass of BaseException), the exception itself, and a traceback object which typically encapsulates the call stack at the point where the exception last occurred.

If no exception is being handled anywhere on the stack, this function return a tuple containing three None values.

バージョン 3.11 で変更: The type and traceback fields are now derived from the 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 exc_info().

sys.exec_prefix

Python のプラットフォーム依存なファイルがインストールされているディレクトリ名を示す文字列です。この値はサイト固有であり、デフォルトは '/usr/local' ですが、ビルド時に configure の --exec-prefix 引数で指定することができます。すべての設定ファイル (pyconfig.h など) は exec_prefix/lib/pythonX.Y/config に、共有ライブラリは exec_prefix/lib/pythonX.Y/lib-dynload にインストールされます (X.Y は 3.2 のような Python のバージョン番号)。

注釈

仮想環境 で起動されている場合、この値は site.py によって仮想環境を示すよう変更されます。実際の Python のインストール先は base_exec_prefix から取得できます。

sys.executable

Python インタプリタの実行ファイルの絶対パスを示す文字列です。このような名前が意味を持つシステムで利用可能です。Python が自身の実行ファイルの実際のパスを取得できない場合、sys.executable は空の文字列または None になります。

sys.exit([arg])

Raise a SystemExit exception, signaling an intention to exit the interpreter.

オプション引数 arg には、終了ステータスとして整数 (デフォルトは0）や他の型のオブジェクトを指定することができます。整数を指定した場合、シェル等は 0 は "正常終了"、0 以外の整数を "異常終了" として扱います。多くのシステムでは、有効な終了ステータスは 0--127 で、これ以外の値を返した場合の動作は未定義です。システムによっては特定の終了コードに個別の意味を持たせている場合がありますが、このような定義は僅かしかありません。Unix プログラムでは構文エラーの場合には 2 を、それ以外のエラーならば 1 を返します。arg に None を指定した場合は、数値の 0 を指定した場合と同じです。それ以外の型のオブジェクトを指定すると、そのオブジェクトが stderr に出力され、終了コードとして 1 を返します。エラー発生時には sys.exit("エラーメッセージ") と書くと、簡単にプログラムを終了することができます。

Since 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 try statements are honored, and it is possible to intercept the exit attempt at an outer level.

バージョン 3.6 で変更: Python インタープリタが (バッファされたデータを標準ストリームに吐き出すときのエラーなどの) SystemExit を捕捉した後の後始末でエラーが起きた場合、終了ステータスは 120 に変更されます。

sys.flags

コマンドラインフラグの状態を表す 名前付きタプル です。各属性は読み出し専用になっています。

flags.debug

-d

flags.inspect

-i

flags.interactive

-i

flags.isolated

-I

flags.optimize

-O または -OO

flags.dont_write_bytecode

-B

flags.no_user_site

-s

flags.no_site

-S

flags.ignore_environment

-E

flags.verbose

-v

flags.bytes_warning

-b

flags.quiet

-q

flags.hash_randomization

-R

flags.dev_mode

-X dev (Python Development Mode)

flags.utf8_mode

-X utf8

flags.safe_path

-P

flags.int_max_str_digits

-X int_max_str_digits (integer string conversion length limitation)

flags.warn_default_encoding

-X warn_default_encoding

バージョン 3.2 で変更: 新しい -q 向けに quiet 属性が追加されました。

Added in version 3.2.3: hash_randomization 属性が追加されました。

バージョン 3.3 で変更: 廃止済みの division_warning 属性を削除しました。

バージョン 3.4 で変更: -I isolated フラグ向けに isolated 属性が追加されました。

バージョン 3.7 で変更: 新しい Python 開発モード 向けに dev_mode 属性が、新しい -X utf8 フラグ向けに utf8_mode 属性が追加されました。

バージョン 3.10 で変更: Added warn_default_encoding attribute for -X warn_default_encoding flag.

バージョン 3.11 で変更: Added the safe_path attribute for -P option.

バージョン 3.11 で変更: Added the int_max_str_digits attribute.

sys.float_info

float 型に関する情報を保持している 名前付きタプル です。精度と内部表現に関する低レベル情報を含んでいます。これらの値は 'C' 言語の標準ヘッダファイル float.h で定義されている様々な浮動小数点定数に対応しています。詳細は 1999 ISO/IEC C standard [C99] の 5.2.4.2.2 節 'Characteristics of floating types' を参照してください。

Attributes of the float_info named tuple

属性

float.h のマクロ

説明

float_info.epsilon

DBL_EPSILON

difference between 1.0 and the least value greater than 1.0 that is representable as a float.

math.ulp() を参照してください。

float_info.dig

DBL_DIG

The maximum number of decimal digits that can be faithfully represented in a float; see below.

float_info.mant_dig

DBL_MANT_DIG

Float precision: the number of base-radix digits in the significand of a float.

float_info.max

DBL_MAX

The maximum representable positive finite float.

float_info.max_exp

DBL_MAX_EXP

The maximum integer e such that radix**(e-1) is a representable finite float.

float_info.max_10_exp

DBL_MAX_10_EXP

The maximum integer e such that 10**e is in the range of representable finite floats.

float_info.min

DBL_MIN

The minimum representable positive normalized float.

Use math.ulp(0.0) to get the smallest positive denormalized representable float.

float_info.min_exp

DBL_MIN_EXP

The minimum integer e such that radix**(e-1) is a normalized float.

float_info.min_10_exp

DBL_MIN_10_EXP

The minimum integer e such that 10**e is a normalized float.

float_info.radix

FLT_RADIX

The radix of exponent representation.

float_info.rounds

FLT_ROUNDS

An integer representing the rounding mode for floating-point arithmetic. This reflects the value of the system FLT_ROUNDS macro at interpreter startup time:

-1: indeterminable

0: toward zero

1: to nearest

2: toward positive infinity

3: toward negative infinity

All other values for FLT_ROUNDS characterize implementation-defined rounding behavior.

The attribute sys.float_info.dig needs further explanation. If s is any string representing a decimal number with at most sys.float_info.dig significant digits, then converting s to a float and back again will recover a string representing the same decimal value:

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

ただし、文字列が有効桁数 sys.float_info.dig より大きい場合には、常に復元されるとは限りません:

>>> s = '9876543211234567'    # 16 significant digits is too many!
>>> format(float(s), '.16g')  # conversion changes value
'9876543211234568'

sys.float_repr_style

repr() 関数が浮動小数点数に対してどう振る舞うかを示す文字列です。この文字列が値 'short' を持てば、有限の浮動小数点数 x に対して、repr(x) は float(repr(x)) == x を満たす短い文字列を返そうとします。これは、Python 3.1 以降での標準の振る舞いです。それ以外の場合、float_repr_style は値 'legacy' を持ち、repr(x) は 3.1 以前のバージョンの Python と同じように振る舞います。

Added in version 3.1.

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 _clear_type_cache() and gc.collect() to get more predictable results.

Python のあるビルドや実装が適切にこの情報を計算できない場合は、その代わりに getallocatedblocks() は 0 を返すことが許されています。

Added in version 3.4.

sys.getunicodeinternedsize()

Return the number of unicode objects that have been interned.

Added in version 3.12.

sys.getandroidapilevel()

Return the build time API version of Android as an integer.

利用可能な環境: Android 。

Added in version 3.7.

sys.getdefaultencoding()

Unicode 実装で使用される現在のデフォルトエンコーディング名を返します。

sys.getdlopenflags()

Return the current value of the flags that are used for dlopen() calls. Symbolic names for the flag values can be found in the os module (RTLD_xxx constants, e.g. os.RTLD_LAZY).

利用可能な環境: Unix。

sys.getfilesystemencoding()

Get the filesystem encoding: the encoding used with the filesystem error handler to convert between Unicode filenames and bytes filenames. The filesystem error handler is returned from getfilesystemencodeerrors().

最良の互換性のために、たとえファイル名の表現に bytes がサポートされていたとしても、全てのケースで str をファイル名に使うべきです。ファイル名を受け取ったり返したりする関数は str と bytes をサポートし、すぐにシステムにとって好ましい表現に変換すべきです。

os.fsencode() や os.fsdecode() を、正しいエンコーディングやエラーモードが使われていることを保証するために使うべきです。

The filesystem encoding and error handler are configured at Python startup by the PyConfig_Read() function: see filesystem_encoding and filesystem_errors members of PyConfig.

バージョン 3.2 で変更: getfilesystemencoding() の結果が None になることはなくなりました。

バージョン 3.6 で変更: Windows はもう 'mbcs' を返す保証は無くなりました。より詳しいことは PEP 529 [https://peps.python.org/pep-0529/] および _enablelegacywindowsfsencoding() を参照してください。

バージョン 3.7 で変更: Python UTF-8 モード が有効なら "utf-8" を返します。

sys.getfilesystemencodeerrors()

Get the filesystem error handler: the error handler used with the filesystem encoding to convert between Unicode filenames and bytes filenames. The filesystem encoding is returned from getfilesystemencoding().

os.fsencode() や os.fsdecode() を、正しいエンコーディングやエラーモードが使われていることを保証するために使うべきです。

The filesystem encoding and error handler are configured at Python startup by the PyConfig_Read() function: see filesystem_encoding and filesystem_errors members of PyConfig.

Added in version 3.6.

sys.get_int_max_str_digits()

Returns the current value for the integer string conversion length limitation. See also set_int_max_str_digits().

Added in version 3.11.

sys.getrefcount(object)

object の参照数を返します。 object は (一時的に) getrefcount() からも参照されるため、参照数は予想される数よりも 1 多くなります。

Note that the returned value may not actually reflect how many references to the object are actually held. For example, some objects are "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.

バージョン 3.12 で変更: Immortal objects have very large refcounts that do not match the actual number of references to the object.

sys.getrecursionlimit()

現在の最大再帰数を返します。最大再帰数は、Python インタプリタスタックの最大の深さです。この制限は Python プログラムが無限に再帰し、C スタックがオーバーフローしてクラッシュすることを防止するために設けられています。この値は setrecursionlimit() で指定することができます。

sys.getsizeof(object[, default])

object のサイズをバイト数で返します。object は任意の型のオブジェクトです。すべての組み込みオブジェクトは正しい値を返します。サードパーティー製の型については実装依存になります。

オブジェクトに直接起因するメモリ消費のみを表し、参照するオブジェクトは含みません。

オブジェクトがサイズを取得する手段を提供していない時は default が返されます。default が指定されていない場合は TypeError が送出されます。

getsizeof() は object の __sizeof__ メソッドを呼び出し、そのオブジェクトがガベージコレクタに管理されていた場合はガベージコレクタのオーバーヘッドを増やします。

See recursive sizeof recipe [https://code.activestate.com/recipes/577504-compute-memory-footprint-of-an-object-and-its-cont/] for an example of using getsizeof() recursively to find the size of containers and all their contents.

sys.getswitchinterval()

インタプリタの "スレッド切り替え間隔" を返します。setswitchinterval() を参照してください。

Added in version 3.2.

sys._getframe([depth])

コールスタックからフレームオブジェクトを返します。オプション引数 depth を指定すると、スタックのトップから depth だけ下のフレームオブジェクトを取得します。 depth がコールスタックよりも深ければ、 ValueError が発生します。 depth のデフォルト値は 0 で、この場合はコールスタックのトップのフレームを返します。

引数 frame で 監査イベント sys._getframe を送出します。

CPython 実装の詳細: この関数は、内部的かつ特殊な目的にのみ利用されるべきです。全ての Python 実装で存在することが保証されているわけではありません。

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, None is returned. The default for depth is zero, returning the module at the top of the call stack.

Raises an auditing event sys._getframemodulename with argument depth.

CPython 実装の詳細: この関数は、内部的かつ特殊な目的にのみ利用されるべきです。全ての Python 実装で存在することが保証されているわけではありません。

sys.getprofile()

setprofile() 関数で設定したプロファイラ関数を取得します。

sys.gettrace()

settrace() 関数で設定したトレース関数を取得します。

CPython 実装の詳細: gettrace() 関数は、デバッガ、プロファイラ、カバレッジツールなどの実装に使うことのみを想定しています。この関数の振る舞いは言語定義ではなく実装プラットフォームの一部です。そのため、他の Python 実装では利用できないかもしれません。

sys.getwindowsversion()

実行中の Windows バージョンを示す、名前付きタプルを返します。名前の付いている要素は、 major, minor, build, platform, service_pack, service_pack_minor, service_pack_major, suite_mask, product_type, platform_version です。 service_pack は文字列を含み、 platform_version は 3-タプル、それ以外は整数です。この構成要素には名前でもアクセスできるので、 sys.getwindowsversion()[0] は sys.getwindowsversion().major と等価です。先行のバージョンとの互換性のため、最初の 5 要素のみが添字の指定で取得できます。

platform will be 2 (VER_PLATFORM_WIN32_NT).

product_type は、以下の値のいずれかになります。:

定数

意味

1 (VER_NT_WORKSTATION)

システムはワークステーションです。

2 (VER_NT_DOMAIN_CONTROLLER)

システムはドメインコントローラです。

3 (VER_NT_SERVER)

システムはサーバですが、ドメインコントローラではありません。

This function wraps the Win32 GetVersionEx() function; see the Microsoft documentation on OSVERSIONINFOEX() for more information about these fields.

platform_version は、プロセスでエミュレートされているバージョンではなく、現在のオペレーティングシステムのメジャーバージョン、マイナーバージョン、ビルドナンバーを返します。この関数は機能の検知ではなくロギングで使うためのものです。

注釈

platform_version derives the version from kernel32.dll which can be of a different version than the OS version. Please use platform module for achieving accurate OS version.

利用可能な環境: Windows 。

バージョン 3.2 で変更: 名前付きタプルに変更され、 service_pack_minor, service_pack_major, suite_mask, および product_type が追加されました。

バージョン 3.6 で変更: platform_version の追加

sys.get_asyncgen_hooks()

asyncgen_hooks オブジェクトを返します。このオブジェクトは (firstiter, finalizer) という形の namedtuple に似た形をしています。 firstiter と finalizer は両方とも None か、 asynchronous generator iterator を引数に取る関数と、イベントループが非同期ジェネレータの終了処理をスケジューリングするのに使う関数であることが求められます。

Added in version 3.6: より詳しくは PEP 525 [https://peps.python.org/pep-0525/] を参照してください。

注釈

This function has been added on a provisional basis (see PEP 411 [https://peps.python.org/pep-0411/] for details.)

sys.get_coroutine_origin_tracking_depth()

Get the current coroutine origin tracking depth, as set by set_coroutine_origin_tracking_depth().

Added in version 3.7.

注釈

This function has been added on a provisional basis (see PEP 411 [https://peps.python.org/pep-0411/] for details.) Use it only for debugging purposes.

sys.hash_info

数値のハッシュ実装のパラメータを与える named tuple です。数値型のハッシュ化についての詳細は 数値型のハッシュ化 を参照してください。

hash_info.width

The width in bits used for hash values

hash_info.modulus

The prime modulus P used for numeric hash scheme

hash_info.inf

The hash value returned for a positive infinity

hash_info.nan

(This attribute is no longer used)

hash_info.imag

The multiplier used for the imaginary part of a complex number

hash_info.algorithm

The name of the algorithm for hashing of str, bytes, and memoryview

hash_info.hash_bits

The internal output size of the hash algorithm

hash_info.seed_bits

The size of the seed key of the hash algorithm

Added in version 3.2.

バージョン 3.4 で変更: algorithm、hash_bits、seed_bits を追加

sys.hexversion

単精度整数にエンコードされたバージョン番号。この値は新バージョン(正規リリース以外であっても)ごとにかならず増加します。例えば、Python 1.5.2 以降でのみ動作するプログラムでは、以下のようなチェックを行います。

if sys.hexversion >= 0x010502F0:
    # use some advanced feature
    ...
else:
    # use an alternative implementation or warn the user
    ...

hexversion は hex() 関数を使って 16 進数に変換しなければ値の意味を持ちません。より読みやすいバージョン番号が必要な場合には named tuple sys.version_info を使用してください。

hexversion のより詳しい情報については API と ABI のバージョニング を参照してください。

sys.implementation

現在起動している Python インタプリタに関する情報が格納されたオブジェクトです。すべての Python 実装において、以下の属性が存在することが要求されています。

name は実装の識別子です (例: 'cpython')。実際の文字列は Python 実装によって定義されますが、小文字であることが保証されています。

version は sys.version_info と同じ形式の、Python 実装 のバージョンを表す名前付きタプルです。これは現在起動しているインタプリタ固有のバージョンを意味します。sys.version_info は Python 言語 のバージョンであり、これはそのバージョンに準拠した 実装 のバージョンです。例えば、PyPy 1.8 の sys.implementation.version は sys.version_info(1, 8, 0, 'final', 0) になるのに対し、 sys.version_info は sys.version_info(2, 7, 2, 'final', 0) になります。CPython は、それがリファレンス実装であるため、両者は同じ値になります。

hexversion は sys.hexversion と同形式の、16 進数での実装のバージョンです。

cache_tag は、キャッシュされたモジュールのファイル名に使用されるタグです。慣例により、これは実装名とバージョンを組み合わせた文字列になります (例: 'cpython-33') が、Python 実装はその他の適切な値を使う場合があります。cache_tag に None が設定された場合、モジュールのキャッシングが無効になっていることを示します。

sys.implementation には Python 実装固有の属性を追加することができます。それら非標準属性の名前はアンダースコアから始めなくてはならず、そしてここでは説明されません。その内容に関係なく、sys.implementation はインタプリタ起動中や実装のバージョン間で変更することはありません (ただし Python 言語のバージョン間についてはその限りではありません)。詳細は PEP 421 [https://peps.python.org/pep-0421/] を参照してください。

Added in version 3.3.

注釈

The addition of new required attributes must go through the normal PEP process. See PEP 421 [https://peps.python.org/pep-0421/] for more information.

sys.int_info

Python における整数の内部表現に関する情報を保持する、named tuple です。この属性は読み出し専用です。

int_info.bits_per_digit

The number of bits held in each digit. Python integers are stored internally in base 2**int_info.bits_per_digit.

int_info.sizeof_digit

The size in bytes of the C type used to represent a digit.

int_info.default_max_str_digits

The default value for sys.get_int_max_str_digits() when it is not otherwise explicitly configured.

int_info.str_digits_check_threshold

The minimum non-zero value for sys.set_int_max_str_digits(), PYTHONINTMAXSTRDIGITS, or -X int_max_str_digits.

Added in version 3.1.

バージョン 3.11 で変更: Added default_max_str_digits and str_digits_check_threshold.

sys.__interactivehook__

この属性が存在する場合、インタープリタが 対話モード で起動したときに値は (引数なしで) 自動的に呼ばれます。これは PYTHONSTARTUP ファイルの読み込み後に行われるため、それにこのフックを設定することが出来ます。site モジュールで 設定します。

引数 hook を指定して 監査イベント cpython.run_interactivehook を送出します。

Added in version 3.4.

sys.intern(string)

string を "隔離" された文字列のテーブルに入力し、隔離された文字列を返します -- この文字列は string 自体かコピーです。隔離された文字列は辞書検索のパフォーマンスを少しだけ向上させるのに有効です -- 辞書中のキーが隔離されており、検索するキーが隔離されている場合、(ハッシュ化後の) キーの比較は文字列の比較ではなくポインタの比較で行うことができるからです。通常、Python プログラム内で利用されている名前は自動的に隔離され、モジュール、クラス、またはインスタンス属性を保持するための辞書は隔離されたキーを持っています。

Interned strings are not immortal; you must keep a reference to the return value of intern() around to benefit from it.

sys.is_finalizing()

Return True if the Python interpreter is shutting down, False otherwise.

Added in version 3.5.

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 import pdb; pdb.pm() to enter the post-mortem debugger; see pdb module for more information.)

Added in version 3.12.

sys.last_type

sys.last_value

sys.last_traceback

These three variables are deprecated; use sys.last_exc instead. They hold the legacy representation of sys.last_exc, as returned from exc_info() above.

sys.maxsize

Py_ssize_t 型の変数が取りうる最大値を示す整数です。通常、32 ビットプラットフォームでは 2**31 - 1、64 ビットプラットフォームでは 2**63 - 1 になります。

sys.maxunicode

Unicode コードポイントの最大値を示す整数、すなわち 1114111 (16 進数で 0x10FFFF) です。

バージョン 3.3 で変更: PEP 393 [https://peps.python.org/pep-0393/] 以前は、オプション設定にUnicode文字の保存形式がUCS-2とUCS-4のどちらを指定したかによって、 sys.maxunicode の値は 0xFFFF が 0x10FFFF になっていました。

sys.meta_path

A list of meta path finder objects that have their 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 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 __path__ attribute is passed in as a second argument. The method returns a module spec, or None if the module cannot be found.

参考

importlib.abc.MetaPathFinder

The abstract base class defining the interface of finder objects on meta_path.

importlib.machinery.ModuleSpec

The concrete class which find_spec() should return instances of.

バージョン 3.4 で変更: Module specs were introduced in Python 3.4, by PEP 451 [https://peps.python.org/pep-0451/].

バージョン 3.12 で変更: Removed the fallback that looked for a find_module() method if a meta_path entry didn't have a find_spec() method.

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 sys.modules.copy() or tuple(sys.modules) to avoid exceptions as its size may change during iteration as a side effect of code or activity in other threads.

sys.orig_argv

The list of the original command line arguments passed to the Python executable.

The elements of sys.orig_argv are the arguments to the Python interpreter, while the elements of sys.argv are the arguments to the user's program. Arguments consumed by the interpreter itself will be present in sys.orig_argv and missing from sys.argv.

Added in version 3.10.

sys.path

モジュールを検索するパスを示す文字列のリスト。 PYTHONPATH 環境変数と、インストール時に指定したデフォルトパスで初期化されます。

By default, as initialized upon program startup, a potentially unsafe path is prepended to sys.path (before the entries inserted as a result of PYTHONPATH):

python -m module command line: prepend the current working directory.

python script.py command line: prepend the script's directory. If it's a symbolic link, resolve symbolic links.

python -c code and python (REPL) command lines: prepend an empty string, which means the current working directory.

To not prepend this potentially unsafe path, use the -P command line option or the PYTHONSAFEPATH environment variable.

プログラムはその目的のために、このリストを自由に修正できます。文字列だけが sys.path に追加でき、 ほかの全てのデータ型はインポート中に無視されます。

参考

site モジュールのドキュメントで、 .pth ファイルを使って sys.path を拡張する方法を解説しています。

sys.path_hooks

path を引数にとって、その path に対する finder の作成を試みる呼び出し可能オブジェクトのリスト。 finder の作成に成功したら、その呼出可能オブジェクトのは finder を返します。失敗した場合は、 ImportError を発生させます。

オリジナルの仕様は PEP 302 [https://peps.python.org/pep-0302/] を参照してください。

sys.path_importer_cache

finder オブジェクトのキャッシュ機能を果たす辞書です。キーは sys.path_hooks に渡されているパスで、値は見つかった finder になります。パスが正常なファイルシステムパスであり、finder が sys.path_hooks 上に見つからない場合は None が格納されます。

オリジナルの仕様は PEP 302 [https://peps.python.org/pep-0302/] を参照してください。

sys.platform

This string contains a platform identifier that can be used to append platform-specific components to sys.path, for instance.

For Unix systems, except on Linux and AIX, this is the lowercased OS name as returned by uname -s with the first part of the version as returned by uname -r appended, e.g. 'sunos5' or 'freebsd8', at the time when Python was built. Unless you want to test for a specific system version, it is therefore recommended to use the following idiom:

if sys.platform.startswith('freebsd'):
    # FreeBSD-specific code here...
elif sys.platform.startswith('linux'):
    # Linux-specific code here...
elif sys.platform.startswith('aix'):
    # AIX-specific code here...

For other systems, the values are:

システム

platform の値

AIX

'aix'

Emscripten

'emscripten'

Linux

'linux'

WASI

'wasi'

Windows

'win32'

Windows/Cygwin

'cygwin'

macOS

'darwin'

バージョン 3.3 で変更: On Linux, sys.platform doesn't contain the major version anymore. It is always 'linux', instead of 'linux2' or 'linux3'. Since older Python versions include the version number, it is recommended to always use the startswith idiom presented above.

バージョン 3.8 で変更: On AIX, sys.platform doesn't contain the major version anymore. It is always 'aix', instead of 'aix5' or 'aix7'. Since older Python versions include the version number, it is recommended to always use the startswith idiom presented above.

参考

os.name has a coarser granularity. os.uname() gives system-dependent version information.

platform モジュールはシステムの詳細な識別情報をチェックする機能を提供しています。

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 "lib" on most platforms. On Fedora and SuSE, it is equal to "lib64" on 64-bit platforms which gives the following sys.path paths (where X.Y is the Python major.minor version):

/usr/lib64/pythonX.Y/: Standard library (like os.py of the os module)

/usr/lib64/pythonX.Y/lib-dynload/: C extension modules of the standard library (like the errno module, the exact filename is platform specific)

/usr/lib/pythonX.Y/site-packages/ (always use lib, not sys.platlibdir): Third-party modules

/usr/lib64/pythonX.Y/site-packages/: C extension modules of third-party packages

Added in version 3.9.

sys.prefix

A string giving the site-specific directory prefix where the platform independent Python files are installed; on Unix, the default is /usr/local. This can be set at build time with the --prefix argument to the configure script. See インストールパス for derived paths.

注釈

仮想環境 で起動されている場合、この値は site.py によって仮想環境を示すよう変更されます。実際の Python のインストール先は base_prefix から取得できます。

sys.ps1

sys.ps2

インタプリタの一次プロンプト、二次プロンプトを指定する文字列。対話モードで実行中のみ定義され、初期値は '>>> ' と '... ' です。文字列以外のオブジェクトを指定した場合、インタプリタが対話コマンドを読み込むごとにオブジェクトの str() を評価します。この機能は、動的に変化するプロンプトを実装する場合に利用します。

sys.setdlopenflags(n)

Set the flags used by the interpreter for 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 sys.setdlopenflags(0). To share symbols across extension modules, call as sys.setdlopenflags(os.RTLD_GLOBAL). Symbolic names for the flag values can be found in the os module (RTLD_xxx constants, e.g. os.RTLD_LAZY).

利用可能な環境: Unix。

sys.set_int_max_str_digits(maxdigits)

Set the integer string conversion length limitation used by this interpreter. See also get_int_max_str_digits().

Added in version 3.11.

sys.setprofile(profilefunc)

Set the system's profile function, which allows you to implement a Python source code profiler in Python. See chapter Python プロファイラ for more information on the Python profiler. The system's profile function is called similarly to the system's trace function (see 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 None. Error in the profile function will cause itself unset.

注釈

The same tracing mechanism is used for setprofile() as settrace(). To trace calls with setprofile() inside a tracing function (e.g. in a debugger breakpoint), see call_tracing().

Profile関数は 3 個の引数、frame、event、および arg を受け取る必要があります。frame は現在のスタックフレームです。event は文字列で、'call', 'return', 'c_call', 'c_return', 'c_exception' のどれかが渡されます。arg はイベントの種類によって異なります。

event には以下の意味があります。

'call'

関数が呼び出された(もしくは、何かのコードブロックに入った)。プロファイル関数が呼ばれる。 arg は None が渡される。

'return'

関数(あるいは別のコードブロック)から戻ろうとしている。プロファイル関数が呼ばれる。 arg は返されようとしている値、または、このイベントが例外が送出されることによって起こったなら None 。

'c_call'

C 関数(拡張関数かビルトイン関数)が呼ばれようとしている。 arg は C 関数オブジェクト。

'c_return'

C 関数から戻った。 arg は C の関数オブジェクト。

'c_exception'

C 関数が例外を発生させた。 arg は C の関数オブジェクト。

引数無しで 監査イベント sys.setprofile を送出します。

sys.setrecursionlimit(limit)

Python インタプリタの、スタックの最大の深さを limit に設定します。この制限は Python プログラムが無限に再帰し、 C スタックがオーバーフローしてクラッシュすることを防止するために設けられています。

limit の最大値はプラットフォームによって異なります。深い再帰処理が必要な場合にはプラットフォームがサポートしている範囲内でより大きな値を指定することができますが、この値が大きすぎればクラッシュするので注意が必要です。

If the new limit is too low at the current recursion depth, a RecursionError exception is raised.

バージョン 3.5.1 で変更: A RecursionError exception is now raised if the new limit is too low at the current recursion depth.

sys.setswitchinterval(interval)

インタプリタのスレッド切り替え間隔を秒で指定します。この浮動小数点値が、並列に動作しているPythonスレッドに割り当てられたタイムスライスの理想的な処理時間です。特に長時間実行される内部関数やメソッドが実行されたとき、実際の値はより高くなることがあります。また、どのスレッドがスレッド切り替え間隔の終わりにスケジュールされる（次に実行される）かはオペレーティングシステムが決定します。インタプリタは自身のスケジューラを持ちません。

Added in version 3.2.

sys.settrace(tracefunc)

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 settrace() for each thread being debugged or use threading.settrace().

Trace関数は 3 個の引数、frame、event、および arg を受け取る必要があります。frame は現在のスタックフレームです。event は文字列で、'call', 'line', 'return', 'exception', 'opcode' のどれかが渡されます。arg はイベントの種類によって異なります。

trace 関数は (event に 'call' を渡された状態で) 新しいローカルスコープに入るたびに呼ばれます。この場合、新しいスコープで利用するローカルの trace 関数への参照か、そのスコープを trace しないのであれば None を返します。

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 settrace(None) is called.

注釈

Tracing is disabled while calling the trace function (e.g. a function set by settrace()). For recursive tracing see call_tracing().

event には以下の意味があります。

'call'

関数が呼び出された(もしくは、何かのコードブロックに入った)。グローバルの trace 関数が呼ばれる。 arg は None が渡される。戻り値はローカルの trace 関数。

'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 None; the return value specifies the new local trace function. See Objects/lnotab_notes.txt for a detailed explanation of how this works. Per-line events may be disabled for a frame by setting f_trace_lines to False on that frame.

'return'

関数(あるいは別のコードブロック)から戻ろうとしている。ローカルの trace 関数が呼ばれる。 arg は返されようとしている値、または、このイベントが例外が送出されることによって起こったなら None 。 trace 関数の戻り値は無視される。

'exception'

例外が発生した。ローカルの trace 関数が呼ばれる。 arg は (exception, value, traceback) のタプル。戻り値は新しいローカルの trace 関数。

'opcode'

The interpreter is about to execute a new opcode (see dis for opcode details). The local trace function is called; arg is 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 f_trace_opcodes to True on the frame.

例外が呼び出しチェインを辿って伝播していくことに注意してください。 'exception' イベントは各レベルで発生します。

For more fine-grained usage, it's possible to set a trace function by assigning 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 settrace() doesn't do. Note that in order for this to work, a global tracing function must have been installed with 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 None to disable itself immediately on each frame).

code と frame オブジェクトについては、 標準型の階層 を参照してください。

引数無しで 監査イベント sys.settrace を送出します。

CPython 実装の詳細: settrace() 関数は、デバッガ、プロファイラ、カバレッジツール等で使うためだけのものです。この関数の挙動は言語定義よりも実装プラットフォームの分野の問題で、全ての Python 実装で利用できるとは限りません。

バージョン 3.7 で変更: 'opcode' event type added; f_trace_lines and f_trace_opcodes attributes added to frames

バージョン 3.12 で変更: 'opcode' event will only be emitted if f_trace_opcodes of at least one frame has been set to True before settrace() is called. This behavior will be changed back in 3.13 to be consistent with previous versions.

sys.set_asyncgen_hooks([firstiter] [, finalizer])

Accepts two optional keyword arguments which are callables that accept an 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.

引数無しで 監査イベント sys.set_asyncgen_hooks_firstiter を送出します。

引数無しで 監査イベント 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.

Added in version 3.6: See PEP 525 [https://peps.python.org/pep-0525/] for more details, and for a reference example of a finalizer method see the implementation of asyncio.Loop.shutdown_asyncgens in Lib/asyncio/base_events.py [https://github.com/python/cpython/tree/3.12/Lib/asyncio/base_events.py]

注釈

This function has been added on a provisional basis (see PEP 411 [https://peps.python.org/pep-0411/] for details.)

sys.set_coroutine_origin_tracking_depth(depth)

Allows enabling or disabling coroutine origin tracking. When enabled, the 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, cr_origin will be None.

To enable, pass a depth value greater than zero; this sets the number of frames whose information will be captured. To disable, pass set depth to zero.

This setting is thread-specific.

Added in version 3.7.

注釈

This function has been added on a provisional basis (see PEP 411 [https://peps.python.org/pep-0411/] for details.) Use it only for debugging purposes.

sys.activate_stack_trampoline(backend, /)

Activate the stack profiler trampoline backend. The only supported backend is "perf".

利用可能な環境: Linux。

Added in version 3.12.

参考

Python support for the Linux perf profiler

https://perf.wiki.kernel.org

sys.deactivate_stack_trampoline()

Deactivate the current stack profiler trampoline backend.

If no stack profiler is activated, this function has no effect.

利用可能な環境: Linux。

Added in version 3.12.

sys.is_stack_trampoline_active()

Return True if a stack profiler trampoline is active.

利用可能な環境: Linux。

Added in version 3.12.

sys._enablelegacywindowsfsencoding()

Changes the 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 PYTHONLEGACYWINDOWSFSENCODING environment variable before launching Python.

See also sys.getfilesystemencoding() and sys.getfilesystemencodeerrors().

利用可能な環境: Windows 。

Added in version 3.6: より詳しくは PEP 529 [https://peps.python.org/pep-0529/] を参照してください。

sys.stdin

sys.stdout

sys.stderr

インタプリタが使用する、それぞれ標準入力、標準出力、および標準エラー出力の ファイルオブジェクト です:

stdin は (input() の呼び出しも含む) すべての対話型入力に使われます。

stdout は print() および expression 文の出力と、input() のプロンプトに使用されます。

インタプリタ自身のプロンプトおよびエラーメッセージは stderr に出力されます。

これらのストリームは open() が返すような通常の テキストファイル です。引数は以下のように選択されます:

The encoding and error handling are is initialized from PyConfig.stdio_encoding and 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 isatty() returns True) use the value of the console input and output codepages at startup, respectively for stdin and stdout/stderr. This defaults to the system 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 PYTHONIOENCODING environment variable before starting Python or by using the new -X utf8 command line option and PYTHONUTF8 environment variable. However, for the Windows console, this only applies when PYTHONLEGACYWINDOWSSTDIO is also set.

When interactive, the stdout stream is line-buffered. Otherwise, it is block-buffered like regular text files. The stderr stream is line-buffered in both cases. You can make both streams unbuffered by passing the -u command-line option or setting the PYTHONUNBUFFERED environment variable.

バージョン 3.9 で変更: Non-interactive stderr is now line-buffered instead of fully buffered.

注釈

標準ストリームにバイナリーデータの読み書きを行うには下位のバイナリー buffer オブジェクトを使用してください。例えば bytes を stdout に書き出す場合は 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 io.StringIO which do not support the buffer attribute.

sys.__stdin__

sys.__stdout__

sys.__stderr__

それぞれ起動時の stdin, stderr, stdout の値を保存しています。終了処理時に利用されます。また、 sys.std* オブジェクトが(訳注:別のファイルライクオブジェクトに)リダイレクトされている場合でも、実際の標準ストリームへの出力に利用できます。

また、標準ストリームが壊れたオブジェクトに置き換えられた場合に、動作する実際のファイルを復元するために利用することもできます。しかし、明示的に置き換え前のストリームを保存しておき、そのオブジェクトを復元する事を推奨します。

注釈

一部の条件下では、stdin, stdout, stderr も、オリジナルの __stdin__, __stdout__, __stderr__ も None になることがあります。これはコンソールに接続しない Windows GUI アプリケーションであり、かつ pythonw で起動された Python アプリケーションが該当します。

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 email package is listed, but the email.mime sub-package and the email.message sub-module are not listed.

See also the sys.builtin_module_names list.

Added in version 3.10.

sys.thread_info

スレッドの実装に関する情報が格納された named tuple です。

thread_info.name

The name of the thread implementation:

"nt": Windows threads

"pthread": POSIX threads

"pthread-stubs": stub POSIX threads (on WebAssembly platforms without threading support)

"solaris": Solaris threads

thread_info.lock

The name of the lock implementation:

"semaphore": a lock uses a semaphore

"mutex+cond": a lock uses a mutex and a condition variable

None この情報が不明の場合

thread_info.version

The name and version of the thread library. It is a string, or None if this information is unknown.

Added in version 3.3.

sys.tracebacklimit

捕捉されない例外が発生した時、出力されるトレースバック情報の最大レベル数を指定する整数値(デフォルト値は 1000)。 0 以下の値が設定された場合、トレースバック情報は出力されず例外型と例外値のみが出力されます。

sys.unraisablehook(unraisable, /)

Handle an unraisable exception.

Called when an exception has occurred but there is no way for Python to handle it. For example, when a destructor raises an exception or during garbage collection (gc.collect()).

The unraisable argument has the following attributes:

exc_type: Exception type.

exc_value: Exception value, can be None.

exc_traceback: Exception traceback, can be None.

err_msg: Error message, can be None.

object: Object causing the exception, can be None.

The default hook formats err_msg and object as: f'{err_msg}: {object!r}'; use "Exception ignored in" error message if err_msg is None.

sys.unraisablehook() can be overridden to control how unraisable exceptions are handled.

参考

excepthook() which handles uncaught exceptions.

警告

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 object using a custom hook can resurrect it if it is set to an object which is being finalized. Avoid storing object after the custom hook completes to avoid resurrecting objects.

引数 hook, unraisable を指定して 監査イベント sys.unraisablehook を送出します。

Added in version 3.8.

sys.version

Python インタプリタのバージョン番号の他、ビルド番号や使用コンパイラなどの情報を示す文字列です。この文字列は Python 対話型インタプリタが起動した時に表示されます。バージョン情報はここから抜き出さずに、 version_info および platform が提供する関数を使って下さい。

sys.api_version

使用中のインタプリタの C API バージョン。 Python と拡張モジュール間の不整合をデバッグする場合などに利用できます。

sys.version_info

バージョン番号を示す 5 要素タプル:major, minor, micro, releaselevel, serial 。 releaselevel 以外は全て整数です。 releaselevel の値は、 'alpha', 'beta', 'candidate', 'final' の何れかです。 Python 2.0 の version_info は、 (2, 0, 0, 'final', 0) となります。構成要素には名前でもアクセスできるので、 sys.version_info[0] は sys.version_info.major と等価、などになります。

バージョン 3.1 で変更: 名前を使った要素アクセスがサポートされました。

sys.warnoptions

この値は、warnings フレームワーク内部のみ使用され、変更することはできません。詳細は warnings を参照してください。

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 sys module for informational purposes; modifying this value has no effect on the registry keys used by Python.

利用可能な環境: Windows 。

sys.monitoring

Namespace containing functions and constants for register callbacks and controlling monitoring events. See sys.monitoring for details.

sys._xoptions

コマンドラインオプション -X で渡された様々な実装固有のフラグの辞書です。オプション名にはその値が明示されていればそれが、それ以外の場合は True がマップされます。例えば:

$ ./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}

CPython 実装の詳細: この -X によって渡されたオプションにアクセスする方法は CPython 固有です。他の実装ではそれらは他の意味でエクスポートされるか、あるいは何もしません。

Added in version 3.2.

出典

[C99]

ISO/IEC 9899:1999. "Programming languages -- C." この標準のパブリックドラフトが参照できます: https://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf。

sys.monitoring --- Execution event monitoring

Added in version 3.12.

注釈

sys.monitoring is a namespace within the sys module, not an independent module, so there is no need to import sys.monitoring, simply import sys and then use sys.monitoring.

This namespace provides access to the functions and constants necessary to activate and control event monitoring.

As programs execute, events occur that might be of interest to tools that monitor execution. The sys.monitoring namespace provides means to receive callbacks when events of interest occur.

The monitoring API consists of three components:

Tool identifiers

Events

Callbacks

Tool identifiers

A tool identifier is an integer and the associated name. Tool identifiers are used to discourage tools from interfering with each other and to allow multiple tools to operate at the same time. Currently tools are completely independent and cannot be used to monitor each other. This restriction may be lifted in the future.

Before registering or activating events, a tool should choose an identifier. Identifiers are integers in the range 0 to 5 inclusive.

Registering and using tools

sys.monitoring.use_tool_id(tool_id: int, name: str, /) → None

Must be called before tool_id can be used. tool_id must be in the range 0 to 5 inclusive. Raises a ValueError if tool_id is in use.

sys.monitoring.free_tool_id(tool_id: int, /) → None

Should be called once a tool no longer requires tool_id.

注釈

free_tool_id() will not disable global or local events associated with tool_id, nor will it unregister any callback functions. This function is only intended to be used to notify the VM that the particular tool_id is no longer in use.

sys.monitoring.get_tool(tool_id: int, /) → str | None

Returns the name of the tool if tool_id is in use, otherwise it returns None. tool_id must be in the range 0 to 5 inclusive.

All IDs are treated the same by the VM with regard to events, but the following IDs are pre-defined to make co-operation of tools easier:

sys.monitoring.DEBUGGER_ID = 0
sys.monitoring.COVERAGE_ID = 1
sys.monitoring.PROFILER_ID = 2
sys.monitoring.OPTIMIZER_ID = 5

There is no obligation to set an ID, nor is there anything preventing a tool from using an ID even it is already in use. However, tools are encouraged to use a unique ID and respect other tools.

Events

The following events are supported:

sys.monitoring.events.BRANCH

A conditional branch is taken (or not).

sys.monitoring.events.CALL

A call in Python code (event occurs before the call).

sys.monitoring.events.C_RAISE

An exception raised from any callable, except for Python functions (event occurs after the exit).

sys.monitoring.events.C_RETURN

Return from any callable, except for Python functions (event occurs after the return).

sys.monitoring.events.EXCEPTION_HANDLED

An exception is handled.

sys.monitoring.events.INSTRUCTION

A VM instruction is about to be executed.

sys.monitoring.events.JUMP

An unconditional jump in the control flow graph is made.

sys.monitoring.events.LINE

An instruction is about to be executed that has a different line number from the preceding instruction.

sys.monitoring.events.PY_RESUME

Resumption of a Python function (for generator and coroutine functions), except for throw() calls.

sys.monitoring.events.PY_RETURN

Return from a Python function (occurs immediately before the return, the callee's frame will be on the stack).

sys.monitoring.events.PY_START

Start of a Python function (occurs immediately after the call, the callee's frame will be on the stack)

sys.monitoring.events.PY_THROW

A Python function is resumed by a throw() call.

sys.monitoring.events.PY_UNWIND

Exit from a Python function during exception unwinding.

sys.monitoring.events.PY_YIELD

Yield from a Python function (occurs immediately before the yield, the callee's frame will be on the stack).

sys.monitoring.events.RAISE

An exception is raised, except those that cause a STOP_ITERATION event.

sys.monitoring.events.RERAISE

An exception is re-raised, for example at the end of a finally block.

sys.monitoring.events.STOP_ITERATION

An artificial StopIteration is raised; see the STOP_ITERATION event.

More events may be added in the future.

These events are attributes of the sys.monitoring.events namespace. Each event is represented as a power-of-2 integer constant. To define a set of events, simply bitwise or the individual events together. For example, to specify both PY_RETURN and PY_START events, use the expression PY_RETURN | PY_START.

sys.monitoring.events.NO_EVENTS

An alias for 0 so users can do explicit comparisons like:

if get_events(DEBUGGER_ID) == NO_EVENTS:
    ...

Events are divided into three groups:

Local events

Local events are associated with normal execution of the program and happen at clearly defined locations. All local events can be disabled. The local events are:

PY_START

PY_RESUME

PY_RETURN

PY_YIELD

CALL

LINE

INSTRUCTION

JUMP

BRANCH

STOP_ITERATION

Ancillary events

Ancillary events can be monitored like other events, but are controlled by another event:

C_RAISE

C_RETURN

The C_RETURN and C_RAISE events are controlled by the CALL event. C_RETURN and C_RAISE events will only be seen if the corresponding CALL event is being monitored.

Other events

Other events are not necessarily tied to a specific location in the program and cannot be individually disabled.

The other events that can be monitored are:

PY_THROW

PY_UNWIND

RAISE

EXCEPTION_HANDLED

The STOP_ITERATION event

PEP 380 [https://peps.python.org/pep-0380/#use-of-stopiteration-to-return-values] specifies that a StopIteration exception is raised when returning a value from a generator or coroutine. However, this is a very inefficient way to return a value, so some Python implementations, notably CPython 3.12+, do not raise an exception unless it would be visible to other code.

To allow tools to monitor for real exceptions without slowing down generators and coroutines, the STOP_ITERATION event is provided. STOP_ITERATION can be locally disabled, unlike RAISE.

Turning events on and off

In order to monitor an event, it must be turned on and a corresponding callback must be registered. Events can be turned on or off by setting the events either globally or for a particular code object.

Setting events globally

Events can be controlled globally by modifying the set of events being monitored.

sys.monitoring.get_events(tool_id: int, /) → int

Returns the int representing all the active events.

sys.monitoring.set_events(tool_id: int, event_set: int, /) → None

Activates all events which are set in event_set. Raises a ValueError if tool_id is not in use.

No events are active by default.

Per code object events

Events can also be controlled on a per code object basis.

sys.monitoring.get_local_events(tool_id: int, code: CodeType, /) → int

Returns all the local events for code

sys.monitoring.set_local_events(tool_id: int, code: CodeType, event_set: int, /) → None

Activates all the local events for code which are set in event_set. Raises a ValueError if tool_id is not in use.

Local events add to global events, but do not mask them. In other words, all global events will trigger for a code object, regardless of the local events.

Disabling events

sys.monitoring.DISABLE

A special value that can be returned from a callback function to disable events for the current code location.

Local events can be disabled for a specific code location by returning sys.monitoring.DISABLE from a callback function. This does not change which events are set, or any other code locations for the same event.

Disabling events for specific locations is very important for high performance monitoring. For example, a program can be run under a debugger with no overhead if the debugger disables all monitoring except for a few breakpoints.

sys.monitoring.restart_events() → None

Enable all the events that were disabled by sys.monitoring.DISABLE for all tools.

Registering callback functions

To register a callable for events call

sys.monitoring.register_callback(tool_id: int, event: int, func: Callable | None, /) → Callable | None

Registers the callable func for the event with the given tool_id

If another callback was registered for the given tool_id and event, it is unregistered and returned. Otherwise register_callback() returns None.

Functions can be unregistered by calling sys.monitoring.register_callback(tool_id, event, None).

Callback functions can be registered and unregistered at any time.

Registering or unregistering a callback function will generate a sys.audit() event.

Callback function arguments

sys.monitoring.MISSING

A special value that is passed to a callback function to indicate that there are no arguments to the call.

When an active event occurs, the registered callback function is called. Different events will provide the callback function with different arguments, as follows:

PY_START and PY_RESUME:

func(code: CodeType, instruction_offset: int) -> DISABLE | Any

PY_RETURN and PY_YIELD:

func(code: CodeType, instruction_offset: int, retval: object) -> DISABLE | Any

CALL, C_RAISE and C_RETURN:

func(code: CodeType, instruction_offset: int, callable: object, arg0: object | MISSING) -> DISABLE | Any

If there are no arguments, arg0 is set to sys.monitoring.MISSING.

RAISE, RERAISE, EXCEPTION_HANDLED, PY_UNWIND, PY_THROW and STOP_ITERATION:

func(code: CodeType, instruction_offset: int, exception: BaseException) -> DISABLE | Any

LINE:

func(code: CodeType, line_number: int) -> DISABLE | Any

BRANCH and JUMP:

func(code: CodeType, instruction_offset: int, destination_offset: int) -> DISABLE | Any

Note that the destination_offset is where the code will next execute. For an untaken branch this will be the offset of the instruction following the branch.

INSTRUCTION:

func(code: CodeType, instruction_offset: int) -> DISABLE | Any

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

Added in version 3.2.

Source code: Lib/sysconfig.py [https://github.com/python/cpython/tree/3.12/Lib/sysconfig.py]

sysconfig モジュールは、インストールパスのリストや、現在のプラットフォームに関連した構成などの、Python の構成情報 (configuration information) へのアクセスを提供します。

構成変数

A Python distribution contains a Makefile and a pyconfig.h header file that are necessary to build both the Python binary itself and third-party C extensions compiled using setuptools.

sysconfig はこれらのファイルに含まれるすべての変数を辞書に格納し、get_config_vars() や get_config_var() でアクセスできるようにします。

Windows では構成変数はだいぶ少なくなります。

sysconfig.get_config_vars(*args)

引数がない場合、現在のプラットフォームに関するすべての構成変数の辞書を返します。

引数がある場合、各引数を構成変数辞書から検索した結果の変数のリストを返します。

各引数において、変数が見つからなかった場合は None が返されます。

sysconfig.get_config_var(name)

1つの変数 name を返します。get_config_vars().get(name) と同じです。

name が見つからない場合、None を返します。

Example of usage:

>>> 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++']

インストールパス

Python uses an installation scheme that differs depending on the platform and on the installation options. These schemes are stored in sysconfig under unique identifiers based on the value returned by os.name. The schemes are used by package installers to determine where to copy files to.

Python は現在9つのスキームをサポートしています:

posix_prefix: Linux や macOS などの POSIX プラットフォーム用のスキームです。これは Python やコンポーネントをインストールするときに使われるデフォルトのスキームです。

posix_home: scheme for POSIX platforms, when the home option is used. This scheme defines paths located under a specific home prefix.

posix_user: scheme for POSIX platforms, when the user option is used. This scheme defines paths located under the user's home directory (site.USER_BASE).

posix_venv: scheme for Python virtual environments on POSIX platforms; by default it is the same as posix_prefix.

nt: scheme for Windows. This is the default scheme used when Python or a component is installed.

nt_user: scheme for Windows, when the user option is used.

nt_venv: scheme for Python virtual environments on Windows; by default it is the same as nt.

venv: a scheme with values from either posix_venv or nt_venv depending on the platform Python runs on.

osx_framework_user オプションが利用された場合の、macOS 用のスキームです。

各スキームは、ユニークな識別子を持ったいくつかのパスの集合から成っています。現在 Python は8つのパスを利用します:

stdlib: プラットフォーム非依存の、標準 Python ライブラリファイルを格納するディレクトリ.

platstdlib: プラットフォーム依存の、標準 Python ライブラリファイルを格納するディレクトリ.

platlib: プラットフォーム依存の、site ごとのファイルを格納するディレクトリ。

purelib: directory for site-specific, non-platform-specific files ('pure' Python).

include: directory for non-platform-specific header files for the Python C-API.

platinclude: directory for platform-specific header files for the Python C-API.

scripts: スクリプトファイルのためのディレクトリ。

data: データファイルのためのディレクトリ。

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 site.USER_BASE (written as userbase hereafter). This scheme installs pure Python modules and extension modules in the same location (also known as site.USER_SITE).

posix_user

Path

インストールディレクトリ

stdlib

userbase/lib/pythonX.Y

platstdlib

userbase/lib/pythonX.Y

platlib

userbase/lib/pythonX.Y/site-packages

purelib

userbase/lib/pythonX.Y/site-packages

include

userbase/include/pythonX.Y

scripts

userbase/bin

data

userbase

nt_user

Path

インストールディレクトリ

stdlib

userbase\PythonXY

platstdlib

userbase\PythonXY

platlib

userbase\PythonXY\site-packages

purelib

userbase\PythonXY\site-packages

include

userbase\PythonXY\Include

scripts

userbase\PythonXY\Scripts

data

userbase

osx_framework_user

Path

インストールディレクトリ

stdlib

userbase/lib/python

platstdlib

userbase/lib/python

platlib

userbase/lib/python/site-packages

purelib

userbase/lib/python/site-packages

include

userbase/include/pythonX.Y

scripts

userbase/bin

data

userbase

Home scheme

"home スキーム" の背後にある考え方は、Python モジュールを個人用のモジュール置き場でビルドし、維持するというものです。このスキームの名前は Unixの「ホーム」ディレクトリの概念からとりました。というのも、 Unixのユーザにとって、自分のホームディレクトリを /usr/ や /usr/local/ のようにレイアウトするのはよくあることだからです。とはいえ、このスキームはどのオペレーティングシステムのユーザでも使えます。

posix_home

Path

インストールディレクトリ

stdlib

home/lib/python

platstdlib

home/lib/python

platlib

home/lib/python

purelib

home/lib/python

include

home/include/python

platinclude

home/include/python

scripts

home/bin

data

home

Prefix scheme

あるインストール済みの Python を使ってモジュールのビルド/インストールを (例えば setup スクリプトを実行して) 行いたいけれども、 別のインストール済みの Python のサードパーティ製モジュール置き場 (あるいは、そう見えるようなディレクトリ構造) に、ビルドされた モジュールをインストールしたい場合には、"prefix スキーム" が便利です。そんな作業はまったくありえそうにない、と思うなら、確かにその通りです --- "home スキーム" を先に説明したのもそのためです。とはいえ、prefix スキームが有用なケースは少なくとも二つあります。

First, consider that many Linux distributions put Python in /usr, rather than the more traditional /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 /usr/local/lib/python2.X rather than /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 /usr/local/bin/python might search for modules in /usr/local/lib/python2.X, but those modules would have to be installed to, say, /mnt/@server/export/lib/python2.X.

posix_prefix

Path

インストールディレクトリ

stdlib

prefix/lib/pythonX.Y

platstdlib

prefix/lib/pythonX.Y

platlib

prefix/lib/pythonX.Y/site-packages

purelib

prefix/lib/pythonX.Y/site-packages

include

prefix/include/pythonX.Y

platinclude

prefix/include/pythonX.Y

scripts

prefix/bin

data

prefix

nt

Path

インストールディレクトリ

stdlib

prefix\Lib

platstdlib

prefix\Lib

platlib

prefix\Lib\site-packages

purelib

prefix\Lib\site-packages

include

prefix\Include

platinclude

prefix\Include

scripts

prefix\Scripts

data

prefix

Installation path functions

sysconfig provides some functions to determine these installation paths.

sysconfig.get_scheme_names()

現在 sysconfig でサポートされているすべてのスキームを格納したタプルを返します。

sysconfig.get_default_scheme()

Return the default scheme name for the current platform.

Added in version 3.10: This function was previously named _get_default_scheme() and considered an implementation detail.

バージョン 3.11 で変更: When Python runs from a virtual environment, the venv scheme is returned.

sysconfig.get_preferred_scheme(key)

Return a preferred scheme name for an installation layout specified by key.

key must be either "prefix", "home", or "user".

The return value is a scheme name listed in get_scheme_names(). It can be passed to sysconfig functions that take a scheme argument, such as get_paths().

Added in version 3.10.

バージョン 3.11 で変更: When Python runs from a virtual environment and key="prefix", the venv scheme is returned.

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 _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 get_default_scheme() and get_preferred_scheme() instead.

Added in version 3.10.

sysconfig.get_path_names()

現在 sysconfig でサポートされているすべてのパス名を格納したタプルを返します。

sysconfig.get_path(name[, scheme[, vars[, expand]]])

scheme で指定されたインストールスキームから、パス name に従ってインストールパスを返します。

name は get_path_names() が返すリストに含まれる値でなければなりません。

sysconfig はインストールパスを、パス名、プラットフォーム、展開される変数に従って格納します。例えば、nt スキームでの stdlib パスは {base}/Lib になります。

get_path() はパスを展開するのに get_config_vars() が返す変数を利用します。すべての変数は各プラットフォームにおいてデフォルト値を持っていて、この関数を呼び出したときにデフォルト値を取得する場合があります。

scheme が指定された場合、get_scheme_names() が返すリストに含まれる値でなければなりません。指定されなかった場合は、現在のプラットフォームでのデフォルトスキームが利用されます。

If vars is provided, it must be a dictionary of variables that will update the dictionary returned by get_config_vars().

expand が False に設定された場合、パスは変数を使って展開されません。

name が見つからない場合、KeyError を送出します。

sysconfig.get_paths([scheme[, vars[, expand]]])

インストールスキームに基づいたすべてのインストールパスを格納した辞書を返します。詳しい情報は get_path() を参照してください。

scheme が指定されない場合、現在のプラットフォームでのデフォルトスキーマが使用されます。

vars を指定する場合、パスを展開するために使用される辞書を更新する値の辞書でなければなりません。

expand に偽を指定すると、パスは展開されません。

scheme が実在するスキームでなかった場合、get_paths() は KeyError を発生させます。

その他の関数

sysconfig.get_python_version()

MAJOR.MINOR の型の Python バージョン番号文字列を返します。'%d.%d' % sys.version_info[:2] に似ています。

sysconfig.get_platform()

現在のプラットフォームを識別するための文字列を返します。

これはプラットフォーム依存のビルドディレクトリやプラットフォーム依存の配布物を区別するために使われます。典型的には、('os.uname()' のように) OSの名前とバージョン、アーキテクチャを含みますが、厳密にはOSに依存します。例えば Linux ではカーネルのバージョンはそれほど重要ではありません。

返される値の例:

linux-i586

linux-alpha (?)

solaris-2.6-sun4u

Windows では以下のどれかを返します:

win-amd64 (64bit Windows on AMD64, 別名 x86_64, Intel64, EM64T)

win32 (その他すべて - 具体的には sys.platform が返す値)

macOS では以下のどれかを返します:

macosx-10.6-ppc

macosx-10.4-ppc64

macosx-10.3-i386

macosx-10.4-fat

その他の非 POSIX プラットフォームでは、現在のところ単に sys.platform を返します。

sysconfig.is_python_build()

実行中の Python インタプリタがソースからビルドされ、かつそのビルドされた場所から実行されている場合に True を返します。 make install を実行した場所からの実行やバイナリインストーラによるインストールではいけません。

sysconfig.parse_config_h(fp[, vars])

config.h スタイルのファイルを解析します。

fp は config.h スタイルのファイルを指すファイルライクオブジェクトです。

name/value ペアを格納した辞書を返します。第二引数にオプションの辞書が渡された場合、新しい辞書ではなくその辞書を利用し、ファイルから読み込んだ値で更新します。

sysconfig.get_config_h_filename()

pyconfig.h のパスを返します。

sysconfig.get_makefile_filename()

Makefile のパスを返します。

sysconfig をスクリプトとして使う

Python の -m オプションを使えば、sysconfig をスクリプトとして使用できます:

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

これは、get_platform()、get_python_version()、get_path() および get_config_vars() が返す情報を標準出力に出力します。

builtins --- Built-in objects

このモジュールは Python の全ての「組み込み」識別子に直接アクセスするためのものです。例えば builtins.open は組み込み関数 open() の完全な名前です。ドキュメントは 組み込み関数 と 組み込み定数 を参照してください。

通常このモジュールはほとんどのアプリケーションで明示的にアクセスされることはありませんが、組み込みの値と同じ名前のオブジェクトを提供するモジュールが同時にその名前の組み込みオブジェクトも必要とするような場合には有用です。たとえば、組み込みの open() をラップした open() という関数を実装したいモジュールがあったとすると、このモジュールは次のように直接的に使われます:

import builtins

def open(path):
    f = builtins.open(path, 'r')
    return UpperCaser(f)

class UpperCaser:
    '''Wrapper around a file that converts output to uppercase.'''

    def __init__(self, f):
        self._f = f

    def read(self, count=-1):
        return self._f.read(count).upper()

    # ...

ほとんどのモジュールではグローバル変数の一部として __builtins__ が利用できるようになっています。 __builtins__ の内容は通常このモジュールそのものか、あるいはこのモジュールの __dict__ 属性です。これは実装の詳細部分なので、異なる Python の実装では __builtins__ は使われていないこともあります。

__main__ --- Top-level code environment

Python では、 __main__ という特別な名前が次の二つの重要な用途で使われます:

プログラムのトップレベル環境の名前。 __name__ == '__main__' という式でチェックすることができる。

Python パッケージにおける __main__.py ファイル。

どちらも Python のモジュールに関わる機能です。１つ目はユーザーがどうモジュールを使うか、２つ目はモジュールとモジュールがどうやりとりするかに関係します。詳細は以下で説明します。 Python モジュールがどういうものかについては、 モジュール を参照してください。

__name__ == '__main__'

Python モジュールやパッケージがインポートされるとき、 __name__ の値はそのモジュールの名前となります。通常、インポートされる Python ファイル自体のファイル名から拡張子``.py`` を除いたものとなります:

>>> import configparser
>>> configparser.__name__
'configparser'

インポートされるファイルがパッケージの一部である場合は、 __name__ にはそのパッケージのパスも含まれます:

>>> from concurrent.futures import process
>>> process.__name__
'concurrent.futures.process'

しかし、モジュールがトップレベルのスクリプト環境で実行される場合は、 __name__ が '__main__' という文字列になります。

「トップレベルのスクリプト環境」とは

__main__ is the name of the environment where top-level code is run. "Top-level code" is the first user-specified Python module that starts running. It's "top-level" because it imports all other modules that the program needs. Sometimes "top-level code" is called an entry point to the application.

以下のものがトップレベルのスクリプト環境となります:

インタラクティブプロンプトのスコープ:

>>> __name__
'__main__'

Python インタープリタにファイル引数として渡される Python モジュール:

$ python helloworld.py
Hello, world!

Python インタープリタにPython -m オプションとして渡される Python モジュールまたはパッケージ:

$ python -m tarfile
usage: tarfile.py [-h] [-v] (...)

標準入力から Python インタープリタが読み込む Python コード:

$ echo "import this" | python
The Zen of Python, by Tim Peters

Beautiful is better than ugly.
Explicit is better than implicit.
...

Python インタープリタに -c オプションで渡される Python コード:

$ python -c "import this"
The Zen of Python, by Tim Peters

Beautiful is better than ugly.
Explicit is better than implicit.
...

上記それぞれの場合で、トップレベルのモジュールの __name__ の値が '__main__' となります。

これにより、 __name__ をチェックすれば各モジュールは自分がトップレベル環境で実行されているかどうかを知ることができます。このことから、モジュールが import 文で初期化された場合以外の場合でのみコードを実行するため、次のコードがしばしば用いられます:

if __name__ == '__main__':
    # Execute when the module is not initialized from an import statement.
    ...

参考

あらゆる場合に __name__ の値がどうセットされるのかについて、詳しくはチュートリアルの モジュール セクションを参照してください。

通常の使われ方

一部のモジュールでは、コマンドライン引数をパースしたり標準入力からデータを取得したなど、スクリプト用途のみのコードが含まれています。このようなモジュールが、例えばユニットテストのため、別のモジュールからインポートされると、そのスクリプト用コードが意図に反して実行されてしまいます。

if __name__ == '__main__' というコードは、このようなときに役立ちます。このブロックの中にあるコードは、当該のモジュールがトップレベル環境で実行されていない限り、実行されません。

if __name__ == '__main__' の下のブロックにあるコードはできるだけ少なくした方が、コードの分かりやすさや正確さにつながります。最もよくあるのが、プログラムの主要な処理を main 関数の中にカプセル化することです:

# 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

注意すべき点として、もし main 関数内のコードをカプセル化せず if __name__ == '__main__' の下に直接書いた場合、 phrase 変数はモジュール全体からグローバルにアクセスできてしまいます。モジュール内の他の関数が意図せずローカル変数ではなくそのグローバル変数を使用してしまう可能性があるため、ミスにつながります。 main 関数を用意することでこの問題は解決できます。

main 関数を使うことのもう一つのメリットとして、 echo 関数が分離し、別の場所からインポートできるようになることです。 echo.py がインポートされるとき、 echo 関数と main 関数が定義されますが、 __name__ != '__main__' であるため、どちらの関数も呼び出されません。

Packaging Considerations

main functions are often used to create command-line tools by specifying them as entry points for console scripts. When this is done, pip [https://pip.pypa.io/] inserts the function call into a template script, where the return value of main is passed into sys.exit(). For example:

sys.exit(main())

Since the call to main is wrapped in sys.exit(), the expectation is that your function will return some value acceptable as an input to sys.exit(); typically, an integer or None (which is implicitly returned if your function does not have a return statement).

By proactively following this convention ourselves, our module will have the same behavior when run directly (i.e. python echo.py) as it will have if we later package it as a console script entry-point in a pip-installable package.

In particular, be careful about returning strings from your main function. sys.exit() will interpret a string argument as a failure message, so your program will have an exit code of 1, indicating failure, and the string will be written to sys.stderr. The echo.py example from earlier exemplifies using the sys.exit(main()) convention.

参考

Python Packaging User Guide [https://packaging.python.org/] contains a collection of tutorials and references on how to distribute and install Python packages with modern tools.

__main__.py in Python Packages

If you are not familiar with Python packages, see section パッケージ of the tutorial. Most commonly, the __main__.py file is used to provide a command-line interface for a package. Consider the following hypothetical package, "bandclass":

bandclass
  ├── __init__.py
  ├── __main__.py
  └── student.py

__main__.py will be executed when the package itself is invoked directly from the command line using the -m flag. For example:

$ python -m bandclass

This command will cause __main__.py to run. How you utilize this mechanism will depend on the nature of the package you are writing, but in this hypothetical case, it might make sense to allow the teacher to search for students:

# bandclass/__main__.py

import sys
from .student import search_students

student_name = sys.argv[1] if len(sys.argv) >= 2 else ''
print(f'Found student: {search_students(student_name)}')

Note that from .student import search_students is an example of a relative import. This import style can be used when referencing modules within a package. For more details, see パッケージ内参照 in the モジュール section of the tutorial.

通常の使われ方

The content of __main__.py typically isn't fenced with an if __name__ == '__main__' block. Instead, those files are kept short and import functions to execute from other modules. Those other modules can then be easily unit-tested and are properly reusable.

If used, an if __name__ == '__main__' block will still work as expected for a __main__.py file within a package, because its __name__ attribute will include the package's path if imported:

>>> import asyncio.__main__
>>> asyncio.__main__.__name__
'asyncio.__main__'

This won't work for __main__.py files in the root directory of a .zip file though. Hence, for consistency, minimal __main__.py like the venv one mentioned below are preferred.

参考

See venv for an example of a package with a minimal __main__.py in the standard library. It doesn't contain a if __name__ == '__main__' block. You can invoke it with python -m venv [directory].

See runpy for more details on the -m flag to the interpreter executable.

See zipapp for how to run applications packaged as .zip files. In this case Python looks for a __main__.py file in the root directory of the archive.

import __main__

Regardless of which module a Python program was started with, other modules running within that same program can import the top-level environment's scope (namespace) by importing the __main__ module. This doesn't import a __main__.py file but rather whichever module that received the special name '__main__'.

Here is an example module that consumes the __main__ namespace:

# namely.py

import __main__

def did_user_define_their_name():
    return 'my_name' in dir(__main__)

def print_user_name():
    if not did_user_define_their_name():
        raise ValueError('Define the variable `my_name`!')

    if '__file__' in dir(__main__):
        print(__main__.my_name, "found in file", __main__.__file__)
    else:
        print(__main__.my_name)

Example usage of this module could be as follows:

# 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())

Now, if we started our program, the result would look like this:

$ python start.py
Define the variable `my_name`!

The exit code of the program would be 1, indicating an error. Uncommenting the line with my_name = "Dinsdale" fixes the program and now it exits with status code 0, indicating success:

$ python start.py
Dinsdale found in file /path/to/start.py

Note that importing __main__ doesn't cause any issues with unintentionally running top-level code meant for script use which is put in the if __name__ == "__main__" block of the start module. Why does this work?

Python inserts an empty __main__ module in sys.modules at interpreter startup, and populates it by running top-level code. In our example this is the start module which runs line by line and imports namely. In turn, namely imports __main__ (which is really start). That's an import cycle! Fortunately, since the partially populated __main__ module is present in sys.modules, Python passes that to namely. See Special considerations for __main__ in the import system's reference for details on how this works.

The Python REPL is another example of a "top-level environment", so anything defined in the REPL becomes part of the __main__ scope:

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

Note that in this case the __main__ scope doesn't contain a __file__ attribute as it's interactive.

The __main__ scope is used in the implementation of pdb and rlcompleter.

warnings --- Warning control

ソースコード: Lib/warnings.py [https://github.com/python/cpython/tree/3.12/Lib/warnings.py]

警告メッセージは一般に、ユーザに警告しておいた方がよいような状況下にプログラムが置かれているが、その状況は (通常は) 例外を送出したりそのプログラムを終了させるほどの正当な理由がないといった状況で発されます。例えば、プログラムが古いモジュールを使っている場合には警告を発したくなるかもしれません。

Python プログラマは、このモジュールの warn() 関数を使って警告を発することができます。(C 言語のプログラマは PyErr_WarnEx() を使います; 詳細は 例外処理 を参照してください)。

警告メッセージは通常 sys.stderr に出力されますが、すべての警告を無視したり、警告を例外にしたりと、その処理を柔軟に変更することができます。 警告の処理は warning category 、警告メッセージのテキスト、警告が発行されたソースの位置に基づいて変化します。 同じソースの位置で特定の警告が繰り返された場合、通常は抑制されます。

警告制御には 2 つの段階 (stage) があります: 第一に、警告が発されるたびに、メッセージを出力すべきかどうかの決定が行われます; 次に、メッセージを出力するなら、メッセージはユーザによって設定が可能なフックを使って書式化され印字されます。

警告メッセージを出力するかどうかの決定は、 警告フィルタ によって制御されます。警告フィルタは一致規則 (matching rule)と動作からなるシーケンスです。 filterwarnings() を呼び出して一致規則をフィルタに追加することができ、 resetwarnings() を呼び出してフィルタを標準設定の状態にリセットすることができます。

警告メッセージの印字は showwarning() を呼び出して行うことができ、この関数は上書きすることができます; この関数の標準の実装では、 formatwarning() を呼び出して警告メッセージを書式化しますが、この関数についても自作の実装を使うことができます。

参考

logging.captureWarnings() を使うことで、標準ロギング基盤ですべての警告を扱うことができます。

警告カテゴリ

警告カテゴリを表現する組み込み例外は数多くあります。このカテゴリ化は警告をグループごとフィルタする上で便利です。

これらは厳密に言えば 組み込み例外 ですが、概念的には警告メカニズムに属しているのでここで記述されています。

標準の警告カテゴリをユーザの作成したコード上でサブクラス化することで、さらに別の警告カテゴリを定義することができます。警告カテゴリは常に Warning クラスのサブクラスでなければなりません。

現在以下の警告カテゴリクラスが定義されています:

Class

説明

Warning

すべての警告カテゴリクラスの基底クラスです。 Exception のサブクラスです。

UserWarning

warn() の標準のカテゴリです。

DeprecationWarning

他の Python 開発者へ向けて警告を発するときの、非推奨の機能についての警告の基底カテゴリです(__main__ によって引き起こされない限り通常は無視されます)。

SyntaxWarning

その文法機能があいまいであることを示す警告カテゴリの基底クラスです。

RuntimeWarning

そのランタイム機能があいまいであることを示す警告カテゴリの基底クラスです。

FutureWarning

Python で書かれたアプリケーションのエンドユーザーへ向けて警告を発するときの、非推奨の機能についての警告の基底カテゴリです。

PendingDeprecationWarning

将来その機能が廃止されることを示す警告カテゴリの基底クラスです(デフォルトでは無視されます)。

ImportWarning

モジュールのインポート処理中に引き起こされる警告カテゴリの基底クラスです(デフォルトでは無視されます)。

UnicodeWarning

Unicode に関係した警告カテゴリの基底クラスです。

BytesWarning

bytes や bytearray に関連した警告カテゴリの基底クラスです。

ResourceWarning

リソースの使用に関連した警告カテゴリの基底クラスです (デフォルトでは無視されます)。

バージョン 3.7 で変更: Previously DeprecationWarning and FutureWarning were distinguished based on whether a feature was being removed entirely or changing its behaviour. They are now distinguished based on their intended audience and the way they're handled by the default warnings filters.

警告フィルタ

警告フィルタは、ある警告を無視すべきか、表示すべきか、あるいは (例外を送出する) エラーにするべきかを制御します。

概念的には、警告フィルタは複数のフィルタ仕様からなる順番リストを維持しています; 何らかの特定の警告が生じると、一致するものが見つかるまでリスト中の各フィルタとの照合が行われます; 一致したフィルタ仕様がその警告の処理方法を決定します。フィルタの各エントリは (action, message, category, module, lineno) からなるタプルです。ここで:

action は以下の文字列のうちの一つです:

値

処理方法

"default"

print the first occurrence of matching warnings for each location (module + line number) where the warning is issued

"error"

一致した警告を例外に変えます

"ignore"

一致した警告を出力しません

"always"

一致した警告を常に出力します

"module"

print the first occurrence of matching warnings for each module where the warning is issued (regardless of line number)

"once"

一致した警告のうち、警告の原因になった場所にかかわらず最初の警告のみ出力します

message is a string containing a regular expression that the start of the warning message must match, case-insensitively. In -W and PYTHONWARNINGS, message is a literal string that the start of the warning message must contain (case-insensitively), ignoring any whitespace at the start or end of message.

category はクラス (Warning のサブクラス) です。警告クラスはこのクラスのサブクラスに一致しなければなりません。

module is a string containing a regular expression that the start of the fully qualified module name must match, case-sensitively. In -W and PYTHONWARNINGS, module is a literal string that the fully qualified module name must be equal to (case-sensitively), ignoring any whitespace at the start or end of module.

lineno は整数で、警告が発生した場所の行番号に一致しなければなりません。0 の場合はすべての行と一致します。

Warning クラスは組み込みの Exception クラスから派生しているので、警告をエラーに変換するには単に category(message) を raise します。

If a warning is reported and doesn't match any registered filter then the "default" action is applied (hence its name).

Describing Warning Filters

The warnings filter is initialized by -W options passed to the Python interpreter command line and the PYTHONWARNINGS environment variable. The interpreter saves the arguments for all supplied entries without interpretation in sys.warnoptions; the warnings module parses these when it is first imported (invalid options are ignored, after printing a message to sys.stderr).

Individual warnings filters are specified as a sequence of fields separated by colons:

action:message:category:module:line

The meaning of each of these fields is as described in 警告フィルタ. When listing multiple filters on a single line (as for PYTHONWARNINGS), the individual filters are separated by commas and the filters listed later take precedence over those listed before them (as they're applied left-to-right, and the most recently applied filters take precedence over earlier ones).

Commonly used warning filters apply to either all warnings, warnings in a particular category, or warnings raised by particular modules or packages. Some examples:

default                      # Show all warnings (even those ignored by default)
ignore                       # Ignore all warnings
error                        # Convert all warnings to errors
error::ResourceWarning       # Treat ResourceWarning messages as errors
default::DeprecationWarning  # Show DeprecationWarning messages
ignore,default:::mymodule    # Only report warnings triggered by "mymodule"
error:::mymodule             # Convert warnings to errors in "mymodule"

デフォルトの警告フィルタ

デフォルトで、 Python はいくつかの警告フィルタをインストールします。これは -W コマンドラインオプション、PYTHONWARNINGS 環境変数または filterwarnings() の呼び出しでオーバーライドできます。

In regular release builds, the default warning filter has the following entries (in order of precedence):

default::DeprecationWarning:__main__
ignore::DeprecationWarning
ignore::PendingDeprecationWarning
ignore::ImportWarning
ignore::ResourceWarning

In a debug build, the list of default warning filters is empty.

バージョン 3.2 で変更: PendingDeprecationWarning に加えて、 DeprecationWarning もデフォルトで無視されるようになりました。

バージョン 3.7 で変更: DeprecationWarning is once again shown by default when triggered directly by code in __main__.

バージョン 3.7 で変更: BytesWarning no longer appears in the default filter list and is instead configured via sys.warnoptions when -b is specified twice.

Overriding the default filter

Developers of applications written in Python may wish to hide all Python level warnings from their users by default, and only display them when running tests or otherwise working on the application. The sys.warnoptions attribute used to pass filter configurations to the interpreter can be used as a marker to indicate whether or not warnings should be disabled:

import sys

if not sys.warnoptions:
    import warnings
    warnings.simplefilter("ignore")

Developers of test runners for Python code are advised to instead ensure that all warnings are displayed by default for the code under test, using code like:

import sys

if not sys.warnoptions:
    import os, warnings
    warnings.simplefilter("default") # Change the filter in this process
    os.environ["PYTHONWARNINGS"] = "default" # Also affect subprocesses

Finally, developers of interactive shells that run user code in a namespace other than __main__ are advised to ensure that DeprecationWarning messages are made visible by default, using code like the following (where user_ns is the module used to execute code entered interactively):

import warnings
warnings.filterwarnings("default", category=DeprecationWarning,
                                   module=user_ns.get("__name__"))

一時的に警告を抑制する

If you are using code that you know will raise a warning, such as a deprecated function, but do not want to see the warning (even when warnings have been explicitly configured via the command line), then it is possible to suppress the warning using the catch_warnings context manager:

import warnings

def fxn():
    warnings.warn("deprecated", DeprecationWarning)

with warnings.catch_warnings():
    warnings.simplefilter("ignore")
    fxn()

このサンプルのコンテキストマネージャーの中では、すべての警告が無視されています。これで、他の廃止予定のコードを含まない(つもりの)部分まで警告を抑止せずに、廃止予定だと分かっているコードだけ警告を表示させないようにすることができます。注意: これが保証できるのはシングルスレッドのアプリケーションだけです。 2つ以上のスレッドが同時に catch_warnings コンテキストマネージャーを使用した場合、動作は未定義です。

警告のテスト

コードが警告を発生させることをテストするには、 catch_warnings コンテキストマネージャーを利用します。このクラスを使うと、一時的に警告フィルタを操作してテストに利用できます。例えば、次のコードでは、発生したすべての警告を取得してチェックしています:

import warnings

def fxn():
    warnings.warn("deprecated", DeprecationWarning)

with warnings.catch_warnings(record=True) as w:
    # Cause all warnings to always be triggered.
    warnings.simplefilter("always")
    # Trigger a warning.
    fxn()
    # Verify some things
    assert len(w) == 1
    assert issubclass(w[-1].category, DeprecationWarning)
    assert "deprecated" in str(w[-1].message)

always の代わりに error を利用することで、すべての警告で例外を発生させることができます。1つ気をつけないといけないのは、一度 once/default ルールによって発生した警告は、フィルタに何をセットしているかにかかわらず、警告レジストリをクリアしない限りは 2度と発生しません。

コンテキストマネージャーが終了したら、警告フィルタはコンテキストマネージャーに入る前のものに戻されます。これは、テスト中に予期しない方法で警告フィルタが変更され、テスト結果が中途半端になる事を予防します。このモジュールの showwarning() 関数も元の値に戻されます。注意: これが保証できるのはシングルスレッドのアプリケーションだけです。 2つ以上のスレッドが同時に catch_warnings コンテキストマネージャを使用した場合、動作は未定義です。

同じ種類の警告を発生させる複数の操作をテストする場合、各操作が新しい警告を発生させている事を確認するのは大切な事です (例えば、警告を例外として発生させて各操作が例外を発生させることを確認したり、警告リストの長さが各操作で増加していることを確認したり、警告リストを各操作の前に毎回クリアする事ができます)。

Updating Code For New Versions of Dependencies

Warning categories that are primarily of interest to Python developers (rather than end users of applications written in Python) are ignored by default.

Notably, this "ignored by default" list includes DeprecationWarning (for every module except __main__), which means developers should make sure to test their code with typically ignored warnings made visible in order to receive timely notifications of future breaking API changes (whether in the standard library or third party packages).

In the ideal case, the code will have a suitable test suite, and the test runner will take care of implicitly enabling all warnings when running tests (the test runner provided by the unittest module does this).

In less ideal cases, applications can be checked for use of deprecated interfaces by passing -Wd to the Python interpreter (this is shorthand for -W default) or setting PYTHONWARNINGS=default in the environment. This enables default handling for all warnings, including those that are ignored by default. To change what action is taken for encountered warnings you can change what argument is passed to -W (e.g. -W error). See the -W flag for more details on what is possible.

利用可能な関数

warnings.warn(message, category=None, stacklevel=1, source=None, *, skip_file_prefixes=None)

警告を発するか、無視するか、あるいは例外を送出します。 category 引数が与えられた場合、 警告カテゴリクラス でなければなりません; 標準の値は UserWarning です。 message を Warning インスタンスで代用することもできますが、この場合 category は無視され、 message.__class__ が使われ、メッセージ文は str(message) になります。発された例外が前述した 警告フィルタ によってエラーに変更された場合、この関数は例外を送出します。引数 stacklevel は Python でラッパー関数を書く際に利用することができます。例えば:

def deprecated_api(message):
    warnings.warn(message, DeprecationWarning, stacklevel=2)

This makes the warning refer to deprecated_api's caller, rather than to the source of deprecated_api itself (since the latter would defeat the purpose of the warning message).

The skip_file_prefixes keyword argument can be used to indicate which stack frames are ignored when counting stack levels. This can be useful when you want the warning to always appear at call sites outside of a package when a constant stacklevel does not fit all call paths or is otherwise challenging to maintain. If supplied, it must be a tuple of strings. When prefixes are supplied, stacklevel is implicitly overridden to be max(2, stacklevel). To cause a warning to be attributed to the caller from outside of the current package you might write:

# 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)

This makes the warning refer to both the example.lower.one_way() and package.higher.another_way() call sites only from calling code living outside of example package.

source 引数が与えられた場合、これは ResourceWarning を発生させた破壊されたオブジェクトです。

バージョン 3.6 で変更: source 引数を追加しました。

バージョン 3.12 で変更: Added skip_file_prefixes.

warnings.warn_explicit(message, category, filename, lineno, module=None, registry=None, module_globals=None, source=None)

warn() の機能に対する低レベルのインターフェースで、メッセージ、警告カテゴリ、ファイル名および行番号、そしてオプションのモジュール名およびレジストリ情報 (モジュールの __warningregistry__ 辞書) を明示的に渡します。モジュール名は標準で .py が取り去られたファイル名になります; レジストリが渡されなかった場合、警告が抑制されることはありません。 message が文字列のとき、 category は Warning のサブクラスでなければなりません。また message は Warning のインスタンスであってもよく、この場合 category は無視されます。

module_globals は、もし与えられるならば、警告が発せられるコードが使っているグローバル名前空間でなければなりません (この引数は zipfile やその他の非ファイルシステムのインポート元の中にあるモジュールのソースを表示することをサポートするためのものです)。

source 引数が与えられた場合、これは ResourceWarning を発生させた破壊されたオブジェクトです。

バージョン 3.6 で変更: source 引数を追加しました。

warnings.showwarning(message, category, filename, lineno, file=None, line=None)

警告をファイルに書き込みます。標準の実装では、 formatwarning(message, category, filename, lineno, line) を呼び出し、返された文字列を file に書き込みます。 file は標準では sys.stderr です。この関数は warnings.showwarning に任意の呼び出し可能オブジェクトを代入して置き換えることができます。 line は警告メッセージに含めるソースコードの1行です。 line が与えられない場合、 showwarning() は filename と lineno から行を取得することを試みます。

warnings.formatwarning(message, category, filename, lineno, line=None)

警告を通常の方法で書式化します。返される文字列内には改行が埋め込まれている可能性があり、かつ文字列は改行で終端されています。 line は警告メッセージに含まれるソースコードの1行です。 line が渡されない場合、 formatwarning() は filename と lineno から行の取得を試みます。

warnings.filterwarnings(action, message='', category=Warning, module='', lineno=0, append=False)

警告フィルタ仕様 のリストにエントリを一つ挿入します。標準ではエントリは先頭に挿入されます; append が真ならば、末尾に挿入されます。この関数は引数の型をチェックし、 message および module の正規表現をコンパイルしてから、これらをタプルにして警告フィルタのリストに挿入します。二つのエントリが特定の警告に合致した場合、リストの先頭に近い方のエントリが後方にあるエントリに優先します。引数が省略されると、標準ではすべてにマッチする値に設定されます。

warnings.simplefilter(action, category=Warning, lineno=0, append=False)

単純なエントリを 警告フィルタ仕様 のリストに挿入します。引数の意味は filterwarnings() と同じですが、この関数により挿入されるフィルタはカテゴリと行番号が一致していればすべてのモジュールのすべてのメッセージに合致しますので、正規表現は必要ありません。

warnings.resetwarnings()

警告フィルタをリセットします。これにより、 -W コマンドラインオプションによるもの simplefilter() 呼び出しによるものを含め、 filterwarnings() の呼び出しによる影響はすべて無効化されます。

利用可能なコンテキストマネージャー

class warnings.catch_warnings(*, record=False, module=None, action=None, category=Warning, lineno=0, append=False)

警告フィルタと showwarning() 関数をコピーし、終了時に復元するコンテキストマネージャーです。 record 引数が False (デフォルト値)だった場合、コンテキスト開始時には None を返します。もし record が True だった場合、リストを返します。このリストにはカスタムの showwarning() 関数(この関数は同時に sys.stdout への出力を抑制します)によってオブジェクトが継続的に追加されます。リストの中の各オブジェクトは、 showwarning() 関数の引数と同じ名前の属性を持っています。

module 引数は、保護したいフィルタを持つモジュールを取ります。 warnings を import して得られるモジュールの代わりに利用されます。この引数は、主に warnings モジュール自体をテストする目的で追加されました。

If the action argument is not None, the remaining arguments are passed to simplefilter() as if it were called immediately on entering the context.

注釈

catch_warnings マネージャーは、モジュールの showwarning() 関数と内部のフィルタ仕様のリストを置き換え、その後復元することによって動作しています。これは、コンテキストマネージャーがグローバルな状態を変更していることを意味していて、したがってスレッドセーフではありません。

バージョン 3.11 で変更: Added the action, category, lineno, and append parameters.

dataclasses --- Data Classes

ソースコード: Lib/dataclasses.py [https://github.com/python/cpython/tree/3.12/Lib/dataclasses.py]

This module provides a decorator and functions for automatically adding generated special methods such as __init__() and __repr__() to user-defined classes. It was originally described in PEP 557 [https://peps.python.org/pep-0557/].

これらの生成されたメソッドで利用されるメンバー変数は PEP 526 [https://peps.python.org/pep-0526/] 型アノテーションを用いて定義されます。例えば、このコードでは:

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

will add, among other things, a __init__() that looks like:

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

Note that this method is automatically added to the class: it is not directly specified in the InventoryItem definition shown above.

Added in version 3.7.

モジュールの内容

@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 decorator that is used to add generated special methods to classes, as described below.

The @dataclass decorator examines the class to find fields. A field is defined as a class variable that has a type annotation. With two exceptions described below, nothing in @dataclass examines the type specified in the variable annotation.

生成されるすべてのメソッドの中でのフィールドの順序は、それらのフィールドがクラス定義に現れた順序です。

The @dataclass decorator will add various "dunder" methods to the class, described below. If any of the added methods already exist in the class, the behavior depends on the parameter, as documented below. The decorator returns the same class that it is called on; no new class is created.

If @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 @dataclass are equivalent:

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

The parameters to @dataclass are:

init: If true (the default), a __init__() method will be generated.

If the class already defines __init__(), this parameter is ignored.

repr: If true (the default), a __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: InventoryItem(name='widget', unit_price=3.0, quantity_on_hand=10).

If the class already defines __repr__(), this parameter is ignored.

eq: If true (the default), an __eq__() method will be generated. This method compares the class as if it were a tuple of its fields, in order. Both instances in the comparison must be of the identical type.

If the class already defines __eq__(), this parameter is ignored.

order: If true (the default is False), __lt__(), __le__(), __gt__(), and __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 ValueError is raised.

If the class already defines any of __lt__(), __le__(), __gt__(), or __ge__(), then TypeError is raised.

unsafe_hash: If False (the default), a __hash__() method is generated according to how eq and frozen are set.

__hash__() is used by built-in hash(), and when objects are added to hashed collections such as dictionaries and sets. Having a __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 __eq__(), and the values of the eq and frozen flags in the @dataclass decorator.

By default, @dataclass will not implicitly add a __hash__() method unless it is safe to do so. Neither will it add or change an existing explicitly defined __hash__() method. Setting the class attribute __hash__ = None has a specific meaning to Python, as described in the __hash__() documentation.

If __hash__() is not explicitly defined, or if it is set to None, then @dataclass may add an implicit __hash__() method. Although not recommended, you can force @dataclass to create a __hash__() method with 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 __hash__() method. Note that you cannot both have an explicit __hash__() method in your dataclass and set unsafe_hash=True; this will result in a TypeError.

If eq and frozen are both true, by default @dataclass will generate a __hash__() method for you. If eq is true and frozen is false, __hash__() will be set to None, marking it unhashable (which it is, since it is mutable). If eq is false, __hash__() will be left untouched meaning the __hash__() method of the superclass will be used (if the superclass is object, this means it will fall back to id-based hashing).

frozen: If true (the default is False), assigning to fields will generate an exception. This emulates read-only frozen instances. If __setattr__() or __delattr__() is defined in the class, then TypeError is raised. See the discussion below.

match_args: If true (the default is True), the __match_args__ tuple will be created from the list of parameters to the generated __init__() method (even if __init__() is not generated, see above). If false, or if __match_args__ is already defined in the class, then __match_args__ will not be generated.

Added in version 3.10.

kw_only: If true (the default value is 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 __init__() parameter generated from a keyword-only field must be specified with a keyword when __init__() is called. There is no effect on any other aspect of dataclasses. See the parameter glossary entry for details. Also see the KW_ONLY section.

Added in version 3.10.

slots: If true (the default is False), __slots__ attribute will be generated and new class will be returned instead of the original one. If __slots__ is already defined in the class, then TypeError is raised.

Added in version 3.10.

バージョン 3.11 で変更: If a field name is already included in the __slots__ of a base class, it will not be included in the generated __slots__ to prevent overriding them. Therefore, do not use __slots__ to retrieve the field names of a dataclass. Use fields() instead. To be able to determine inherited slots, base class __slots__ may be any iterable, but not an iterator.

weakref_slot: If true (the default is False), add a slot named "__weakref__", which is required to make an instance weakref-able. It is an error to specify weakref_slot=True without also specifying slots=True.

Added in version 3.11.

フィールド には、通常の Python の文法でデフォルト値を指定できます。

@dataclass
class C:
    a: int       # 'a' has no default value
    b: int = 0   # assign a default value for 'b'

In this example, both a and b will be included in the added __init__() method, which will be defined as:

def __init__(self, a: int, b: int = 0):

デフォルト値を指定しないフィールドを、デフォルト値を指定したフィールドの後ろに定義すると、 TypeError が送出されます。これは、単一のクラスであっても、クラス継承の結果でも起きえます。

dataclasses.field(*, default=MISSING, default_factory=MISSING, init=True, repr=True, hash=None, compare=True, metadata=None, kw_only=MISSING)

For common and simple use cases, no other functionality is required. There are, however, some dataclass features that require additional per-field information. To satisfy this need for additional information, you can replace the default field value with a call to the provided field() function. For example:

@dataclass
class C:
    mylist: list[int] = field(default_factory=list)

c = C()
c.mylist += [1, 2, 3]

As shown above, the MISSING value is a sentinel object used to detect if some parameters are provided by the user. This sentinel is used because None is a valid value for some parameters with a distinct meaning. No code should directly use the MISSING value.

The parameters to field() are:

default: If provided, this will be the default value for this field. This is needed because the field() call itself replaces the normal position of the default value.

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.

init: If true (the default), this field is included as a parameter to the generated __init__() method.

repr: If true (the default), this field is included in the string returned by the generated __repr__() method.

hash: This can be a bool or None. If true, this field is included in the generated __hash__() method. If None (the default), use the value of compare: this would normally be the expected behavior. A field should be considered in the hash if it's used for comparisons. Setting this value to anything other than None is discouraged.

フィールドのハッシュ値を計算するコストが高い場合に、 hash=False だが compare=True と設定する理由が 1 つあるとすれば、フィールドが等価検査に必要かつ、その型のハッシュ値を計算するのに他のフィールドも使われることです。フィールドがハッシュから除外されていたとしても、比較には使えます。

compare: If true (the default), this field is included in the generated equality and comparison methods (__eq__(), __gt__(), et al.).

metadata: This can be a mapping or None. None is treated as an empty dict. This value is wrapped in MappingProxyType() to make it read-only, and exposed on the 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.

kw_only: If true, this field will be marked as keyword-only. This is used when the generated __init__() method's parameters are computed.

Added in version 3.10.

If the default value of a field is specified by a call to 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 @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:

@dataclass
class C:
    x: int
    y: int = field(repr=False)
    z: int = field(repr=False, default=10)
    t: int = 20

The class attribute C.z will be 10, the class attribute C.t will be 20, and the class attributes C.x and C.y will not be set.

class dataclasses.Field

Field objects describe each defined field. These objects are created internally, and are returned by the fields() module-level method (see below). Users should never instantiate a Field object directly. Its documented attributes are:

name: The name of the field.

type: The type of the field.

default, default_factory, init, repr, hash, compare, metadata, and kw_only have the identical meaning and values as they do in the field() function.

他の属性があることもありますが、それらはプライベートであり、調べたり、依存したりしてはなりません。

dataclasses.fields(class_or_instance)

このデータクラスのフィールドを定義する Field オブジェクトをタプルで返します。データクラスあるいはデータクラスのインスタンスを受け付けます。データクラスやデータクラスのインスタンスが渡されなかった場合は、 TypeError を送出します。 ClassVar や InitVar といった疑似フィールドは返しません。

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 name: value pairs. dataclasses, dicts, lists, and tuples are recursed into. Other objects are copied with copy.deepcopy().

Example of using asdict() on nested dataclasses:

@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}]}

To create a shallow copy, the following workaround may be used:

{field.name: getattr(obj, field.name) for field in fields(obj)}

asdict() raises TypeError if obj is not a dataclass instance.

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 copy.deepcopy().

1つ前の例の続きです:

assert astuple(p) == (10, 20)
assert astuple(c) == ([(0, 0), (10, 4)],)

To create a shallow copy, the following workaround may be used:

tuple(getattr(obj, field.name) for field in dataclasses.fields(obj))

astuple() raises TypeError if obj is not a dataclass instance.

dataclasses.make_dataclass(cls_name, fields, *, bases=(), namespace=None, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False, weakref_slot=False, module=None)

Creates a new dataclass with name cls_name, fields as defined in fields, base classes as given in bases, and initialized with a namespace as given in namespace. fields is an iterable whose elements are each either name, (name, type), or (name, type, Field). If just name is supplied, typing.Any is used for 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 @dataclass.

If module is defined, the __module__ attribute of the dataclass is set to that value. By default, it is set to the module name of the caller.

This function is not strictly required, because any Python mechanism for creating a new class with __annotations__ can then apply the @dataclass function to convert that class to a dataclass. This function is provided as a convenience. For example:

C = make_dataclass('C',
                   [('x', int),
                     'y',
                    ('z', int, field(default=5))],
                   namespace={'add_one': lambda self: self.x + 1})

は、次のコードと等しいです:

@dataclass
class C:
    x: int
    y: 'typing.Any'
    z: int = 5

    def add_one(self):
        return self.x + 1

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 TypeError. If keys in changes are not field names of the given dataclass, raises TypeError.

The newly returned object is created by calling the __init__() method of the dataclass. This ensures that __post_init__(), if present, is also called.

Init-only variables without default values, if any exist, must be specified on the call to replace() so that they can be passed to __init__() and __post_init__().

It is an error for changes to contain any fields that are defined as having init=False. A ValueError will be raised in this case.

Be forewarned about how init=False fields work during a call to replace(). They are not copied from the source object, but rather are initialized in __post_init__(), if they're initialized at all. It is expected that 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 replace() (or similarly named) method which handles instance copying.

dataclasses.is_dataclass(obj)

引数がデータクラスかデータクラスのインスタンスだった場合に True を返します。それ以外の場合は False を返します。

引数がデータクラスのインスタンスである (そして、データクラスそのものではない) かどうかを知る必要がある場合は、 not isinstance(obj, type) で追加のチェックをしてください:

def is_dataclass_instance(obj):
    return is_dataclass(obj) and not isinstance(obj, type)

dataclasses.MISSING

デフォルト値やdefault_factoryが設定されてない場合の番兵の値を設定します。

dataclasses.KW_ONLY

A sentinel value used as a type annotation. Any fields after a pseudo-field with the type of KW_ONLY are marked as keyword-only fields. Note that a pseudo-field of type KW_ONLY is otherwise completely ignored. This includes the name of such a field. By convention, a name of _ is used for a KW_ONLY field. Keyword-only fields signify __init__() parameters that must be specified as keywords when the class is instantiated.

このサンプルでは y と z がキーワード専用フィールドとなります:

@dataclass
class Point:
    x: float
    _: KW_ONLY
    y: float
    z: float

p = Point(0, y=1.5, z=2.0)

In a single dataclass, it is an error to specify more than one field whose type is KW_ONLY.

Added in version 3.10.

exception dataclasses.FrozenInstanceError

frozen=True 付きで定義されたデータクラスで、暗黙的に定義された __setattr__() または __delattr__() が呼び出されたときに送出されます。これは AttributeError のサブクラスです。

初期化後の処理

dataclasses.__post_init__()

When defined on the class, it will be called by the generated __init__(), normally as self.__post_init__(). However, if any InitVar fields are defined, they will also be passed to __post_init__() in the order they were defined in the class. If no __init__() method is generated, then __post_init__() will not automatically be called.

他の機能と組み合わせることで、他の 1 つ以上のフィールドに依存しているフィールドが初期化できます。例えば次のようにできます:

@dataclass
class C:
    a: float
    b: float
    c: float = field(init=False)

    def __post_init__(self):
        self.c = self.a + self.b

The __init__() method generated by @dataclass does not call base class __init__() methods. If the base class has an __init__() method that has to be called, it is common to call this method in a __post_init__() method:

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)

Note, however, that in general the dataclass-generated __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.

下にある初期化限定変数についての節で、 __post_init__() にパラメータを渡す方法を参照してください。 replace() が init=False であるフィールドをどう取り扱うかについての警告も参照してください。

クラス変数

One of the few places where @dataclass actually inspects the type of a field is to determine if a field is a class variable as defined in PEP 526 [https://peps.python.org/pep-0526/]. It does this by checking if the type of the field is typing.ClassVar. If a field is a ClassVar, it is excluded from consideration as a field and is ignored by the dataclass mechanisms. Such ClassVar pseudo-fields are not returned by the module-level fields() function.

初期化限定変数

Another place where @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 dataclasses.InitVar. If a field is an 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 fields() function. Init-only fields are added as parameters to the generated __init__() method, and are passed to the optional __post_init__() method. They are not otherwise used by dataclasses.

例えば、あるフィールドがデータベースから初期化されると仮定して、クラスを作成するときには値が与えられない次の場合を考えます:

@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)

In this case, fields() will return Field objects for i and j, but not for database.

凍結されたインスタンス

It is not possible to create truly immutable Python objects. However, by passing frozen=True to the @dataclass decorator you can emulate immutability. In that case, dataclasses will add __setattr__() and __delattr__() methods to the class. These methods will raise a FrozenInstanceError when invoked.

There is a tiny performance penalty when using frozen=True: __init__() cannot use simple assignment to initialize fields, and must use object.__setattr__(). .. Make sure to not remove "object" from "object.__setattr__" in the above markup

継承

When the dataclass is being created by the @dataclass decorator, it looks through all of the class's base classes in reverse MRO (that is, starting at 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:

@dataclass
class Base:
    x: Any = 15.0
    y: int = 0

@dataclass
class C(Base):
    z: int = 10
    x: int = 15

The final list of fields is, in order, x, y, z. The final type of x is int, as specified in class C.

The generated __init__() method for C will look like:

def __init__(self, x: int = 15, y: int = 0, z: int = 10):

Re-ordering of keyword-only parameters in __init__()

__init__() で必要なパラメータが算出されると、キーワード専用引数は他の一般的な（非キーワード専用）パラメータの後に移動します。これは、すべてのキーワード専用引数は、非キーワード専用パラメータの末尾にこなければならないという、キーワード専用パラメータのPythonの実装の都合で必要なことです。

In this example, Base.y, Base.w, and D.t are keyword-only fields, and Base.x and D.z are regular fields:

@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)

The generated __init__() method for D will look like:

def __init__(self, x: Any = 15.0, z: int = 10, *, y: int = 0, w: int = 1, t: int = 0):

パラメータは、フィールドのリストの表示方法によって並べ替えられます。通常のフィールドから派生したパラメータの後に、キーワードのみのフィールドから派生したパラメータが続きます。

The relative ordering of keyword-only parameters is maintained in the re-ordered __init__() parameter list.

デフォルトファクトリ関数

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

mylist: list = field(default_factory=list)

If a field is excluded from __init__() (using init=False) and the field also specifies default_factory, then the default factory function will always be called from the generated __init__() function. This happens because there is no other way to give the field an initial value.

可変なデフォルト値

Python はメンバ変数のデフォルト値をクラス属性に保持します。データクラスを使っていない、この例を考えてみましょう:

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

Note that the two instances of class C share the same class variable x, as expected.

データクラスを使っているこのコードが もし仮に 有効なものだとしたら:

@dataclass
class D:
    x: list = []      # This code raises ValueError
    def add(self, element):
        self.x.append(element)

データクラスは次のようなコードを生成するでしょう:

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

This has the same issue as the original example using class C. That is, two instances of class D that do not specify a value for x when creating a class instance will share the same copy of 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 @dataclass decorator will raise a 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.

デフォルトファクトリ関数を使うのが、フィールドのデフォルト値として可変な型の新しいインスタンスを作成する手段です:

@dataclass
class D:
    x: list = field(default_factory=list)

assert D().x is not D().x

バージョン 3.11 で変更: Instead of looking for and disallowing objects of type list, dict, or set, unhashable objects are now not allowed as default values. Unhashability is used to approximate mutability.

Descriptor-typed fields

Fields that are assigned descriptor objects as their default value have the following special behaviors:

The value for the field passed to the dataclass's __init__() method is passed to the descriptor's __set__() method rather than overwriting the descriptor object.

Similarly, when getting or setting the field, the descriptor's __get__() or __set__() method is called rather than returning or overwriting the descriptor object.

To determine whether a field contains a default value, @dataclass will call the descriptor's __get__() method using its class access form: 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 AttributeError in this situation, no default value will be provided for the field.

class IntConversionDescriptor:
    def __init__(self, *, default):
        self._default = default

    def __set_name__(self, owner, name):
        self._name = "_" + name

    def __get__(self, obj, type):
        if obj is None:
            return self._default

        return getattr(obj, self._name, self._default)

    def __set__(self, obj, value):
        setattr(obj, self._name, int(value))

@dataclass
class InventoryItem:
    quantity_on_hand: IntConversionDescriptor = IntConversionDescriptor(default=100)

i = InventoryItem()
print(i.quantity_on_hand)   # 100
i.quantity_on_hand = 2.5    # calls __set__ with 2.5
print(i.quantity_on_hand)   # 2

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.

contextlib --- with 文コンテキスト用ユーティリティ

ソースコード: Lib/contextlib.py [https://github.com/python/cpython/tree/3.12/Lib/contextlib.py]

このモジュールは with 文に関わる一般的なタスクのためのユーティリティを提供します。詳しい情報は、 コンテキストマネージャ型 と with文とコンテキストマネージャ を参照してください。

ユーティリティ

以下の関数とクラスを提供しています:

class contextlib.AbstractContextManager

object.__enter__() と object.__exit__() の2つのメソッドを実装した抽象基底クラス (abstract base class) です。 object.__enter__() は self を返すデフォルトの実装が提供されるいっぽう、 object.__exit__() はデフォルトで None を返す抽象メソッドです。 コンテキストマネージャ型 の定義も参照してください。

Added in version 3.6.

class contextlib.AbstractAsyncContextManager

object.__aenter__() と object.__aexit__() の2つのメソッドを実装するクラスのための抽象基底クラス (abstract base class) です。 object.__aenter__() は self を返すデフォルト実装が提供されるいっぽう、 object.__aexit__() はデフォルトで None を返す抽象メソッドです。 非同期コンテキストマネージャ (Asynchronous Context Manager) の定義も参照してください。

Added in version 3.7.

@contextlib.contextmanager

This function is a decorator that can be used to define a factory function for with statement context managers, without needing to create a class or separate __enter__() and __exit__() methods.

多くのオブジェクトが with 文の仕様を固有にサポートしていますが、コンテキストマネージャの権限に属さず、 close() メソッドを実装していないために contextlib.closing の利用もできないリソースを管理する必要があることがあります。

リソースを正しく管理するよう保証する抽象的な例は以下のようなものでしょう:

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)

このとき、関数は次のように使うことができます:

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

デコレート対象の関数は呼び出されたときに ジェネレータ-イテレータを返す必要があります。このイテレータは必ず値を1つ yield しなければなりません。 with 文の as 節が存在するなら、その値は as 節のターゲットへ束縛されることになります。

ジェネレータが yield を実行した箇所で with 文のネストされたブロックが実行されます。ブロックから抜けた後でジェネレータは再開されます。ブロック内で処理されない例外が発生した場合は、ジェネレータ内部の yield を実行した箇所で例外が再送出されます。なので、(もしあれば) エラーを捕捉したり、クリーンアップ処理を確実に実行したりするために、try...except...finally 構文を使用できます。例外を捕捉する目的が、(完全に例外を抑制してしまうのではなく) 単に例外のログをとるため、もしくはあるアクションを実行するためなら、ジェネレータはその例外を再送出しなければなりません。例外を再送出しない場合、ジェネレータのコンテキストマネージャは with 文に対して例外が処理されたことを示し、with 文の直後の文から実行を再開します。

contextmanager() は ContextDecorator を使っているので、 contextmanager() で作ったコンテキストマネージャは with 文だけでなくデコレータとしても利用できます。デコレーターとして利用された場合、新しい generator インスタンスが関数呼び出しのたびに暗黙に生成されます (このことによって、 contextmanager() によって作られたなにがしか「単発」コンテキストマネージャを、コンテキストマネージャがデコレータとして使われるためには多重に呼び出されることをサポートする必要がある、という要件に合致させることが出来ます。)

バージョン 3.2 で変更: ContextDecorator の使用。

@contextlib.asynccontextmanager

contextmanager() と似ていますが、 非同期コンテキストマネージャ (asynchronous context manager) を生成します。

This function is a decorator that can be used to define a factory function for async with statement asynchronous context managers, without needing to create a class or separate __aenter__() and __aexit__() methods. It must be applied to an asynchronous generator function.

簡単な例:

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

Added in version 3.7.

asynccontextmanager() とともに定義されたコンテキストマネージャは、デコレータとして使うことも async with 文と組み合わせて使うこともできます:

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

デコレータとして使われた場合は、各関数呼び出しに対して暗黙のうちに新しいジェネレータインスタンスが生成されます。これにより、 asynccontextmanager() で生成された単回使用のコンテキストマネージャが複数回呼び出し可能となり、コンテキストマネージャをデコレータとして使うことができるための要件を満たすようにすることができます。

バージョン 3.10 で変更: asynccontextmanager() により生成された非同期コンテキストマネージャをデコレータとして使うことができるようになりました。

contextlib.closing(thing)

ブロックの完了時に thing を close するコンテキストマネージャを返します。これは基本的に以下と等価です:

from contextlib import contextmanager

@contextmanager
def closing(thing):
    try:
        yield thing
    finally:
        thing.close()

そして、明示的に page を close する必要なしに、次のように書くことができます:

from contextlib import closing
from urllib.request import urlopen

with closing(urlopen('https://www.python.org')) as page:
    for line in page:
        print(line)

page を明示的に close する必要は無く、エラーが発生した場合でも、 with ブロックを出るときに page.close() が呼ばれます。

注釈

Most types managing resources support the context manager protocol, which closes thing on leaving the with statement. As such, closing() is most useful for third party types that don't support context managers. This example is purely for illustration purposes, as urlopen() would normally be used in a context manager.

contextlib.aclosing(thing)

ブロックの完了時に thing の aclose() メソッドを呼び出すような非同期コンテキストマネージャを返します。これは基本的に以下と等価です:

from contextlib import asynccontextmanager

@asynccontextmanager
async def aclosing(thing):
    try:
        yield thing
    finally:
        await thing.aclose()

重要なことは、たとえば次の例のように break や例外によって早期にブロックが終了した場合に、 aclosing() は非同期ジェネレータの決定論的なクリーンアップをサポートすることです:

from contextlib import aclosing

async with aclosing(my_generator()) as values:
    async for value in values:
        if value == 42:
            break

このパターンは、ジェネレータの非同期な終了のコードがイテレーション処理と同じコンテキストの中で実行されることを保証します (すなわち例外とコンテキスト変数は期待通りに動作し、またジェネレータが依存するタスクの寿命が尽きたあとに終了のコードが実行されることもありません)。

Added in version 3.10.

contextlib.nullcontext(enter_result=None)

enter_result を __enter__ メソッドが返すだけで、その他は何もしないコンテキストマネージャを返します。たとえば以下のように、ある機能を持った別のコンテキストマネージャに対する、選択可能な代役として使われることが意図されています:

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

enter_result を使った例です:

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

非同期コンテキストマネージャ の代役として使うこともできます:

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

Added in version 3.7.

バージョン 3.10 で変更: 非同期コンテキストマネージャ (asynchronous context manager) のサポートが追加されました。

contextlib.suppress(*exceptions)

with 文の内部で指定された例外の発生を抑えるコンテキストマネージャを返します。 with 文の後に続く最初の文から処理が再開されます。

ほかの完全に例外を抑制するメカニズム同様、このコンテキストマネージャは、黙ってプログラム実行を続けることが正しいことであるとわかっている、非常に限定的なエラーをカバーする以上の使い方はしてはいけません。

例えば:

from contextlib import suppress

with suppress(FileNotFoundError):
    os.remove('somefile.tmp')

with suppress(FileNotFoundError):
    os.remove('someotherfile.tmp')

これは以下と等価です:

try:
    os.remove('somefile.tmp')
except FileNotFoundError:
    pass

try:
    os.remove('someotherfile.tmp')
except FileNotFoundError:
    pass

このコンテキストマネージャは 再入可能(リエントラント) です。

If the code within the with block raises a BaseExceptionGroup, suppressed exceptions are removed from the group. If any exceptions in the group are not suppressed, a group containing them is re-raised.

Added in version 3.4.

バージョン 3.12 で変更: suppress now supports suppressing exceptions raised as part of an BaseExceptionGroup.

contextlib.redirect_stdout(new_target)

sys.stdout を一時的に別のファイルまたは file-like オブジェクトにリダイレクトするコンテキストマネージャです。

このツールは、出力先が標準出力 (stdout) に固定されている既存の関数やクラスに出力先の柔軟性を追加します。

たとえば、 help() の出力は通常標準出力 (sys.stdout) に送られます。出力される文字列を io.StringIO オブジェクトにリダイレクトすることによって捕捉することができます。代替の出力ストリームは __enter__ メソッドによって返されるので、 with 文のターゲットとして利用可能です:

with redirect_stdout(io.StringIO()) as f:
    help(pow)
s = f.getvalue()

help() の出力をディスク上のファイルに送るためには、出力を通常のファイルにリダイレクトします:

with open('help.txt', 'w') as f:
    with redirect_stdout(f):
        help(pow)

help() の出力を標準エラー出力 (sys.stderr) に送るには以下のようにします:

with redirect_stdout(sys.stderr):
    help(pow)

sys.stdout のシステム全体にわたる副作用により、このコンテキストマネージャはライブラリコードやマルチスレッドアプリケーションでの使用には適していません。また、サブプロセスの出力に対しても効果がありません。そのような制限はありますが、それでも多くのユーティリティスクリプトに対して有用なアプローチです。

このコンテキストマネージャは 再入可能(リエントラント) です。

Added in version 3.4.

contextlib.redirect_stderr(new_target)

redirect_stdout() と同じですが、標準エラー出力 (sys.stderr) を別のファイルや file-like オブジェクトにリダイレクトします。

このコンテキストマネージャは 再入可能(リエントラント) です。

Added in version 3.5.

contextlib.chdir(path)

現在の作業ディレクトリを変更するパラレル非安全なコンテキストマネージャです。グローバルな状態である作業ディレクトリを変更するため、ほとんどのマルチスレッドまたは非同期のコンテキストに対する利用は適切ではありません。また、プログラムの実行権限を一時的に放棄するジェネレータのような、直線的でないコードを実行する場合も適切ではありません -- 明確に必要でないかぎり、このコンテキストマネージャがアクティブな状態で yield すべきではありません。

これは chdir() の単純なラッパーで、コンテキストに入るときに現在の作業ディレクトリを変更し、終了時に元の作業ディレクトリを復元します。

このコンテキストマネージャは 再入可能(リエントラント) です。

Added in version 3.11.

class contextlib.ContextDecorator

コンテキストマネージャをデコレータとしても使用できるようにする基底クラスです。

ContextDecorator から継承したコンテキストマネージャは、通常のコンテキストマネージャーと同じく __enter__ および __exit__ を実装する必要があります。__exit__ はデコレータとして使用された場合でも例外をオプションの引数として受け取ります。

contextmanager() は ContextDecorator を利用しているので、自動的にデコレーターとしても利用できるようになります。

ContextDecorator の例:

from contextlib import ContextDecorator

class mycontext(ContextDecorator):
    def __enter__(self):
        print('Starting')
        return self

    def __exit__(self, *exc):
        print('Finishing')
        return False

このとき、クラスは次のように使うことができます:

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

これは次のような形のコードに対するシンタックスシュガーになります:

def f():
    with cm():
        # Do stuff

ContextDecorator を使うと代わりに次のように書けます:

@cm()
def f():
    # Do stuff

デコレーターを使うと、cm が関数の一部ではなく全体に適用されていることが明確になります (インデントレベルを1つ節約できるのもメリットです)。

すでに基底クラスを持っているコンテキストマネージャーも、ContextDecorator を mixin クラスとして利用することで拡張できます:

from contextlib import ContextDecorator

class mycontext(ContextBaseClass, ContextDecorator):
    def __enter__(self):
        return self

    def __exit__(self, *exc):
        return False

注釈

デコレートされた関数が複数回呼び出せるように、内部のコンテキストマネージャーは複数の with 文に対応する必要があります。そうでないなら、明示的な with 文を関数内で利用するべきです。

Added in version 3.2.

class contextlib.AsyncContextDecorator

ContextDecorator と同じですが、非同期関数専用のクラスです。

AsyncContextDecorator の使用例:

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

このとき、クラスは次のように使うことができます:

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

Added in version 3.10.

class contextlib.ExitStack

他の、特にオプションであったり入力に依存するようなコンテキストマネージャーやクリーンアップ関数を動的に組み合わせるためのコンテキストマネージャーです。

例えば、複数のファイルを1つの with 文で簡単に扱うことができます:

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

The __enter__() method returns the ExitStack instance, and performs no additional operations.

各インスタンスは登録されたコールバックのスタックを管理し、インスタンスが (明示的に、あるいは with 文の終わりに暗黙的に) close されるときに逆順でそれを呼び出します。コンテキストスタックのインスタンスが暗黙的にガベージコレクトされたときには callback は呼び出され ません 。

このスタックモデルは、(file オブジェクトのように) __init__ メソッドでリソースを確保するコンテキストマネージャーを正しく扱うためのものです。

登録されたコールバックが登録の逆順で実行されるので、複数のネストされた with 文を利用するのと同じ振る舞いをします。これは例外処理にも適用されます。内側のコールバックが例外を抑制したり置き換えたりした場合、外側のコールバックには更新された状態に応じた引数が渡されます。

これは正しく exit callback の stack を巻き戻すための、比較的低レベルな API です。アプリケーション独自のより高レベルなコンテキストマネージャーを作るための基板として使うのに適しています。

Added in version 3.3.

enter_context(cm)

Enters a new context manager and adds its __exit__() method to the callback stack. The return value is the result of the context manager's own __enter__() method.

コンテキストマネージャーは、普段 with 文で利用された時と同じように、例外を抑制することができます。

バージョン 3.11 で変更: cm がコンテキストマネージャでなかった場合、 AttributeError の代わりに TypeError 例外を送出します。

push(exit)

Adds a context manager's __exit__() method to the callback stack.

As __enter__ is not invoked, this method can be used to cover part of an __enter__() implementation with a context manager's own __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 __exit__() method and adds it directly to the callback stack.

By returning true values, these callbacks can suppress exceptions the same way context manager __exit__() methods can.

この関数はデコレータとしても使えるように、受け取ったオブジェクトをそのまま返します。

callback(callback, /, *args, **kwds)

任意の関数と引数を受け取り、コールバックスタックに追加します。

他のメソッドと異なり、このメソッドで追加されたコールバックは例外を抑制しません (例外の詳細も渡されません)。

この関数はデコレータとしても使えるように、受け取った callback をそのまま返します。

pop_all()

コールバックスタックを新しい ExitStack インスタンスに移して、それを返します。このメソッドは callback を実行しません。代わりに、新しい stack が (明示的に、あるいは with 文の終わりに暗黙的に) close されるときに実行されます。

例えば、複数のファイルを "all or nothing" に開く処理を次のように書けます:

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.

close()

すぐにコールバックスタックを巻き戻し、コールバック関数を登録の逆順に呼び出します。登録されたすべてのコンテキストマネージャーと終了 callback に、例外が起こらなかった場合の引数が渡されます。

class contextlib.AsyncExitStack

ExitStack に似た 非同期コンテキストマネージャ です。スタック上で同期と非同期の両方のコンテキストマネージャの組み合わせをサポートします。また、後処理のためのコルーチンも持っています。

The close() method is not implemented; aclose() must be used instead.

coroutine enter_async_context(cm)

Similar to ExitStack.enter_context() but expects an asynchronous context manager.

バージョン 3.11 で変更: cm が非同期コンテキストマネージャでなかった場合、 AttributeError の代わりに TypeError 例外を送出します。

push_async_exit(exit)

Similar to ExitStack.push() but expects either an asynchronous context manager or a coroutine function.

push_async_callback(callback, /, *args, **kwds)

Similar to ExitStack.callback() but expects a coroutine function.

coroutine aclose()

Similar to ExitStack.close() but properly handles awaitables.

asynccontextmanager() の使用例の続きです:

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.

Added in version 3.7.

例とレシピ

このセクションでは、 contextlib が提供するツールの効果的な使い方を示す例とレシピを紹介します。

可変数個のコンテキストマネージャーをサポートする

ExitStack の第一のユースケースは、クラスのドキュメントにかかれている通り、一つの with 文で可変数個のコンテキストマネージャーや他のクリーンアップ関数をサポートすることです。ユーザーの入力 (指定された複数個のファイルを開く場合など) に応じて複数個のコンテキストマネージャーが必要となる場合や、いくつかのコンテキストマネージャーがオプションとなる場合に、可変数個のコンテキストマネージャーが必要になります:

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

上の例にあるように、 ExitStack はコンテキストマネージャープロトコルをサポートしていないリソースの管理を with 文を使って簡単に行えるようにします。

__enter__ メソッドからの例外をキャッチする

稀に、 __enter__ メソッドからの例外を、 with 文の body やコンテキストマネージャーの __exit__ メソッドからの例外は間違えて捕まえないように、 catch したい場合があります。 ExitStack を使って、コンテキストマネージャープロトコル内のステップを分離することができます:

stack = ExitStack()
try:
    x = stack.enter_context(cm)
except Exception:
    # handle __enter__ exception
else:
    with stack:
        # Handle normal case

実際のところ、このようなコードが必要になるのならば、利用している API 側で try/except/finally 文を使った直接的なリソース管理インターフェースを提供するべきです。しかし、すべての API がそのようによく設計されているとは限りません。もしコンテキストマネージャーが提供されている唯一のリソース管理APIであるなら、 ExitStack を使って with 文を使って処理することができない様々なシチュエーションの処理をすることができます。

__enter__ 実装内のクリーンアップ

As noted in the documentation of ExitStack.push(), this method can be useful in cleaning up an already allocated resource if later steps in the __enter__() implementation fail.

次の例では、リソースの確保と開放の関数に加えて、オプションのバリデーション関数を受け取るコンテキストマネージャーで、この方法を使ってコンテキストマネージャープロトコルを提供しています:

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()

try-finally + flag 変数パターンを置き換える

try-finally 文に、finally 句の内容を実行するかどうかを示すフラグ変数を組み合わせたパターンを目にすることがあるかもしれません。一番シンプルな (単に except 句を使うだけでは処理できない) ケースでは次のようなコードになります:

cleanup_needed = True
try:
    result = perform_operation()
    if result:
        cleanup_needed = False
finally:
    if cleanup_needed:
        cleanup_resources()

try 文を使ったコードでは、セットアップとクリーンアップのコードが任意の長さのコードで分離してしまうので、開発者やレビューアにとって問題になりえます。

ExitStack を使えば、代わりに with 文の終わりに実行されるコールバックを登録し、後でそのコールバックをスキップするかどうかを決定できます:

from contextlib import ExitStack

with ExitStack() as stack:
    stack.callback(cleanup_resources)
    result = perform_operation()
    if result:
        stack.pop_all()

これにより、別のフラグ変数を使う代わりに、必要なクリーンアップ処理を手前に明示しておくことができます。

もしあるアプリケーションがこのパターンを多用するのであれば、小さいヘルパークラスを導入してよりシンプルにすることができます:

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()

もしリソースのクリーンアップが単体の関数にまとまってない場合でも、 ExitStack.callback() のデコレーター形式を利用してリソース開放処理を宣言することができます:

from contextlib import ExitStack

with ExitStack() as stack:
    @stack.callback
    def cleanup_resources():
        ...
    result = perform_operation()
    if result:
        stack.pop_all()

デコレータープロトコルの使用上、このように宣言されたコールバック関数は引数を取ることができません。その代わりに、リリースするリソースをクロージャー変数としてアクセスできる必要があります。

コンテキストマネージャーを関数デコレーターとして使う

ContextDecorator はコンテキストマネージャーを通常の with 文に加えて関数デコレーターとしても利用できるようにします。

例えば、関数やまとまった文を、そこに入った時と出た時の時間をトラックするロガーでラップしたい場合があります。そのために関数デコレーターとコンテキストマネージャーを別々に書く代わりに、 ContextDecorator を継承すると1つの定義で両方の機能を提供できます:

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)

このクラスのインスタンスはコンテキストマネージャーとしても利用でき:

with track_entry_and_exit('widget loader'):
    print('Some time consuming activity goes here')
    load_widget()

また関数デコレーターとしても利用できます:

@track_entry_and_exit('widget loader')
def activity():
    print('Some time consuming activity goes here')
    load_widget()

Note that there is one additional limitation when using context managers as function decorators: there's no way to access the return value of __enter__(). If that value is needed, then it is still necessary to use an explicit with statement.

参考

PEP 343 [https://peps.python.org/pep-0343/] - "with" ステートメント

Python の with 文の仕様、背景、および例が記載されています。

単回使用、再利用可能、およびリエントラントなコンテキストマネージャ

ほとんどのコンテキストマネージャは、 with 文の中で一度だけ使われるような場合に効果的になるように書かれています。これら単回使用のコンテキストマネージャは毎回新規に生成されなければなりません - それらを再利用しようとすると、例外を引き起こすか、正しく動作しません。

この共通の制限が意味することは、コンテキストマネージャは (上記すべての使用例に示すとおり) 一般に with 文のヘッダ部分で直接生成することが推奨されるということです。

ファイルオブジェクトは単回使用のコンテキストマネージャ有効に利用した例です。最初の with 文によりファイルがクローズされ、それ以降そのファイルオブジェクトに対するすべての IO 操作を防止します。

contextmanager() により生成されたコンテキストマネージャも単回使用のコンテキスト マネージャです。二回目に使おうとした場合、内部にあるジェネレータが値の生成に失敗したと訴えるでしょう:

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

リエントラントなコンテキストマネージャ

より洗練されたコンテキストマネージャには"リエントラント"なものがあります。そのようなコンテキストマネージャは、複数の with 文で使えるだけでなく、同じコンテキストマネージャをすでに使っている with 文の 内部 でも使うことができます。

threading.RLock はリエントラントなコンテキストマネージャの例であり、また suppress(), redirect_stdout(), そして chdir() もリエントラントです。以下はリエントラントな利用法の非常に単純な例です:

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

リエントラントな性質の実例はお互いを呼び出しあう複数の関数を含んでいる可能性が高く、したがってこの例よりもはるかに複雑です。

リエントラントであることはスレッドセーフであることと同じ ではない ことには注意が必要です。たとえば redirect_stdout() は、 sys.stdout を異なるストリームに束縛することによりシステムの状態に対してグローバルな変更を行うことから、明らかにスレッドセーフではありません。

再利用可能なコンテキストマネージャ

単回使用のコンテキストマネージャとリエントラントなコンテキストマネージャのいずれとも異なるタイプに "再利用可能" なコンテキストマネージャがあります (あるいは、より明確には、"再利用可能だがリエントラントでない" コンテキストマネージャです。リエントラントなコンテキストマネージャもまた再利用可能だからです)。再利用可能なコンテキストマネージャは複数回利用をサポートしますが、同じコンテキストマネージャのインスタンスがすでに with 文で使われている場合には失敗します (もしくは正しく動作しません)。

threading.Lock は再利用可能だがリエントラントでないコンテキストマネージャの例です (リエントラントなロックのためには threading.RLock を代わりに使う必要があります)。

再利用可能だがリエントラントでないコンテキストマネージャのもうひとつの例は ExitStack です。これは現在登録されている 全ての コールバック関数を、どこで登録されたかにかかわらず、呼び出します:

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

例における出力が示すように、ひとつのスタックオブジェクトを複数の with 文で再利用しても正しく動作します。しかし入れ子にして使った場合は、一番内側の with 文を抜ける際にスタックが空になります。これは望ましい動作とは思えません。

ひとつの ExitStack インスタンスを再利用する代わりに複数のインスタンスを使うことにより、この問題は回避することができます:

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

abc --- Abstract Base Classes

ソースコード: Lib/abc.py [https://github.com/python/cpython/tree/3.12/Lib/abc.py]

このモジュールは Python に PEP 3119 [https://peps.python.org/pep-3119/] で概要が示された 抽象基底クラス (ABC) を定義する基盤を提供します。なぜこれが Python に付け加えられたかについてはその PEP を参照してください。 (ABC に基づいた数の型階層を扱った PEP 3141 [https://peps.python.org/pep-3141/] と numbers モジュールも参照してください。)

The collections module has some concrete classes that derive from ABCs; these can, of course, be further derived. In addition, the collections.abc submodule has some ABCs that can be used to test whether a class or instance provides a particular interface, for example, if it is hashable or if it is a mapping.

このモジュールは、 抽象基底クラスを定義するためのメタクラス ABCMeta と、 継承を利用して抽象基底クラスを代替的に定義するヘルパークラス ABC を提供します。

class abc.ABC

A helper class that has ABCMeta as its metaclass. With this class, an abstract base class can be created by simply deriving from ABC avoiding sometimes confusing metaclass usage, for example:

from abc import ABC

class MyABC(ABC):
    pass

Note that the type of ABC is still ABCMeta, therefore inheriting from ABC requires the usual precautions regarding metaclass usage, as multiple inheritance may lead to metaclass conflicts. One may also define an abstract base class by passing the metaclass keyword and using ABCMeta directly, for example:

from abc import ABCMeta

class MyABC(metaclass=ABCMeta):
    pass

Added in version 3.4.

class abc.ABCMeta

抽象基底クラス(ABC)を定義するためのメタクラス。

ABC を作るときにこのメタクラスを使います。ABC は直接的にサブクラス化することができ、ミックスイン(mix-in)クラスのように振る舞います。また、無関係な具象クラス(組み込み型でも構いません)と無関係な ABC を "仮想的サブクラス" として登録できます -- これらとその子孫は組み込み関数 issubclass() によって登録した ABC のサブクラスと判定されますが、登録した ABC は MRO (Method Resolution Order, メソッド解決順)には現れませんし、この ABC のメソッド実装が(super() を通してだけでなく)呼び出し可能になるわけでもありません。 [1]

Classes created with a metaclass of ABCMeta have the following method:

register(subclass)

subclass を "仮想的サブクラス" としてこの ABC に登録します。たとえば:

from abc import ABC

class MyABC(ABC):
    pass

MyABC.register(tuple)

assert issubclass(tuple, MyABC)
assert isinstance((), MyABC)

バージョン 3.3 で変更: クラスデコレータとして使うことができるように、登録されたサブクラスを返します。

バージョン 3.4 で変更: To detect calls to register(), you can use the get_cache_token() function.

また、次のメソッドを抽象基底クラスの中でオーバーライドできます:

__subclasshook__(subclass)

(クラスメソッドとして定義しなければなりません。)

Check whether subclass is considered a subclass of this ABC. This means that you can customize the behavior of issubclass() further without the need to call register() on every class you want to consider a subclass of the ABC. (This class method is called from the __subclasscheck__() method of the ABC.)

This method should return True, False or NotImplemented. If it returns True, the subclass is considered a subclass of this ABC. If it returns False, the subclass is not considered a subclass of this ABC, even if it would normally be one. If it returns NotImplemented, the subclass check is continued with the usual mechanism.

この概念のデモとして、次の ABC 定義の例を見てください:

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)

The ABC MyIterable defines the standard iterable method, __iter__(), as an abstract method. The implementation given here can still be called from subclasses. The get_iterator() method is also part of the MyIterable abstract base class, but it does not have to be overridden in non-abstract derived classes.

ここで定義されるクラスメソッド __subclasshook__() の意味は、 __iter__() メソッドがクラスの(または __mro__ でアクセスされる基底クラスの一つの) __dict__ にある場合にもそのクラスが MyIterable だと見なされるということです。

Finally, the last line makes Foo a virtual subclass of MyIterable, even though it does not define an __iter__() method (it uses the old-style iterable protocol, defined in terms of __len__() and __getitem__()). Note that this will not make get_iterator available as a method of Foo, so it is provided separately.

The abc module also provides the following decorator:

@abc.abstractmethod

抽象メソッドを示すデコレータです。

Using this decorator requires that the class's metaclass is ABCMeta or is derived from it. A class that has a metaclass derived from ABCMeta cannot be instantiated unless all of its abstract methods and properties are overridden. The abstract methods can be called using any of the normal 'super' call mechanisms. abstractmethod() may be used to declare abstract methods for properties and descriptors.

Dynamically adding abstract methods to a class, or attempting to modify the abstraction status of a method or class once it is created, are only supported using the update_abstractmethods() function. The abstractmethod() only affects subclasses derived using regular inheritance; "virtual subclasses" registered with the ABC's register() method are not affected.

When abstractmethod() is applied in combination with other method descriptors, it should be applied as the innermost decorator, as shown in the following usage examples:

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)

In order to correctly interoperate with the abstract base class machinery, the descriptor must identify itself as abstract using __isabstractmethod__. In general, this attribute should be True if any of the methods used to compose the descriptor are abstract. For example, Python's built-in property does the equivalent of:

class Descriptor:
    ...
    @property
    def __isabstractmethod__(self):
        return any(getattr(f, '__isabstractmethod__', False) for
                   f in (self._fget, self._fset, self._fdel))

注釈

Java の抽象メソッドと違い、これらの抽象メソッドは実装を持ち得ます。この実装は super() メカニズムを通してそれをオーバーライドしたクラスから呼び出すことができます。これは協調的多重継承を使ったフレームワークにおいて super 呼び出しの終点として有効です。

The abc module also supports the following legacy decorators:

@abc.abstractclassmethod

Added in version 3.2.

バージョン 3.3 で非推奨: classmethod を abstractmethod() と一緒に使えるようになったため、このデコレータは冗長になりました。

組み込みの classmethod() のサブクラスで、抽象クラスメソッドであることを示します。それ以外は abstractmethod() と同じです。

この特殊ケースは classmethod() デコレータが抽象メソッドに適用された場合に抽象的だと正しく認識されるようになったため撤廃されます:

class C(ABC):
    @classmethod
    @abstractmethod
    def my_abstract_classmethod(cls, arg):
        ...

@abc.abstractstaticmethod

Added in version 3.2.

バージョン 3.3 で非推奨: staticmethod を abstractmethod() と一緒に使えるようになったため、このデコレータは冗長になりました。

組み込みの staticmethod() のサブクラスで、抽象静的メソッドであることを示します。それ以外は abstractmethod() と同じです。

この特殊ケースは staticmethod() デコレータが抽象メソッドに適用された場合に抽象的だと正しく認識されるようになったため撤廃されます:

class C(ABC):
    @staticmethod
    @abstractmethod
    def my_abstract_staticmethod(arg):
        ...

@abc.abstractproperty

バージョン 3.3 で非推奨: property 、 property.getter() 、 property.setter() および property.deleter() を abstractmethod() と一緒に使えるようになったため、このデコレータは冗長になりました。

組み込みの property() のサブクラスで、抽象プロパティであることを示します。

この特殊ケースは property() デコレータが抽象メソッドに適用された場合に抽象的だと正しく認識されるようになったため撤廃されます:

class C(ABC):
    @property
    @abstractmethod
    def my_abstract_property(self):
        ...

この例は読み出し専用のプロパティを定義しています。プロパティを構成するメソッドの1つ以上を abstract にすることで、読み書きできる抽象プロパティを定義することができます:

class C(ABC):
    @property
    def x(self):
        ...

    @x.setter
    @abstractmethod
    def x(self, val):
        ...

構成するメソッド全てが abstract でない場合、abstract と定義されたメソッドのみが、具象サブクラスによってオーバーライドする必要があります:

class D(C):
    @C.x.setter
    def x(self, val):
        ...

The abc module also provides the following functions:

abc.get_cache_token()

現在の抽象基底クラスのキャッシュトークンを返します。

このトークンは、仮想サブクラスのための抽象基底クラスの現在のバージョンを特定する (等価性検査をサポートしている) 不透明なオブジェクトです。任意のABCでの ABCMeta.register() の呼び出しごとに、トークンは変更されます。

Added in version 3.4.

abc.update_abstractmethods(cls)

A function to recalculate an abstract class's abstraction status. This function should be called if a class's abstract methods have been implemented or changed after it was created. Usually, this function should be called from within a class decorator.

Returns cls, to allow usage as a class decorator.

If cls is not an instance of ABCMeta, does nothing.

注釈

This function assumes that cls's superclasses are already updated. It does not update any subclasses.

Added in version 3.10.

脚注

[1]

C++ プログラマは Python の仮想的基底クラスの概念は C++ のものと同じではないということを銘記すべきです。

atexit --- Exit handlers

atexit モジュールは、クリーンアップ関数の登録およびその解除を行う関数を定義します。登録された関数はインタプリタの通常終了時に自動的に実行されます。atexit はそれら関数を登録した順と 逆に 実行します; A、B、C の順に登録した場合、インタプリタ終了時に C、B、A の順に実行されます。

注意: このモジュールを使用して登録された関数は、プログラムが Python が扱わないシグナルによって kill された場合、Python 内部で致命的なエラーが検出された場合、あるいは os._exit() が呼び出された場合は実行されません。

Note: The effect of registering or unregistering functions from within a cleanup function is undefined.

バージョン 3.7 で変更: C-API のサブインタープリタで使われているとき、登録された関数は登録先のインタープリタのローカルな関数になります。

atexit.register(func, *args, **kwargs)

func を終了時に実行する関数として登録します。func に渡す引数は register() の引数として指定しなければなりません。同じ関数を同じ引数で複数回登録できます。

通常のプログラムの終了時、例えば sys.exit() が呼び出されるとき、あるいは、メインモジュールの実行が完了したときに、登録された全ての関数を、最後に登録されたものから順に呼び出します。通常、より低レベルのモジュールはより高レベルのモジュールより前に import されるので、後で後始末が行われるという仮定に基づいています。

終了ハンドラの実行中に例外が発生すると、(SystemExit 以外の場合は)トレースバックを表示して、例外の情報を保存します。全ての終了ハンドラに動作するチャンスを与えた後に、最後に送出された例外を再送出します。

この関数は func を返し、これをデコレータとして利用できます。

警告

Starting new threads or calling os.fork() from a registered function can lead to race condition between the main Python runtime thread freeing thread states while internal threading routines or the new process try to use that state. This can lead to crashes rather than clean shutdown.

バージョン 3.12 で変更: Attempts to start a new thread or os.fork() a new process in a registered function now leads to RuntimeError.

atexit.unregister(func)

関数 func をインタプリタ終了時に実行する関数のリストから削除します。func が登録されていなければ、unregister() は何もしません。func が2回以上登録されている場合は atexit のコールスタックにおける func のすべての出現が削除されます。削除の際の比較には等価比較 (==) が使われます。したがって削除したいものと同一の関数を func に指定する必要はありません。

参考

readline モジュール

readline ヒストリファイルを読み書きするための atexit の有用な例です。

atexit の例

次の簡単な例では、あるモジュールを import した時にカウンタを初期化しておき、プログラムが終了するときにアプリケーションがこのモジュールを明示的に呼び出さなくてもカウンタが更新されるようにする方法を示しています。

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)

register() に指定した位置引数とキーワード引数は登録した関数を呼び出す際に渡されます:

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')

デコレータ として利用する例:

import atexit

@atexit.register
def goodbye():
    print('You are now leaving the Python sector.')

デコレータとして利用できるのは、その関数が引数なしで呼び出された場合に限られます。

traceback --- Print or retrieve a stack traceback

ソースコード: Lib/traceback.py [https://github.com/python/cpython/tree/3.12/Lib/traceback.py]

このモジュールは Python プログラムのスタックトレースを抽出し、書式を整え、表示するための標準インターフェースを提供します。モジュールがスタックトレースを表示するとき、Python インタープリタの動作を正確に模倣します。インタープリタの"ラッパー"の場合のように、プログラムの制御の元でスタックトレースを表示したいと思ったときに役に立ちます。

The module uses traceback objects --- these are objects of type types.TracebackType, which are assigned to the __traceback__ field of BaseException instances.

参考

faulthandler モジュール

Used to dump Python tracebacks explicitly, on a fault, after a timeout, or on a user signal.

Module pdb

Interactive source code debugger for Python programs.

このモジュールには、以下の関数が定義されています:

traceback.print_tb(tb, limit=None, file=None)

Print up to limit stack trace entries from traceback object tb (starting from the caller's frame) if limit is positive. Otherwise, print the last abs(limit) entries. If limit is omitted or None, all entries are printed. If file is omitted or None, the output goes to sys.stderr; otherwise it should be an open file or file-like object to receive the output.

バージョン 3.5 で変更: 負の limit がサポートされました。

traceback.print_exception(exc, /, [value, tb, ]limit=None, file=None, chain=True)

Print exception information and stack trace entries from traceback object tb to file. This differs from print_tb() in the following ways:

tb が None でない場合ヘッダ Traceback (most recent call last): を出力します

it prints the exception type and value after the stack trace

type(value) が SyntaxError であり、 value が適切な形式を持っていれば、そのエラーのおおよその位置を示すマークと共にシンタックスエラーが発生した行が表示されます。

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 print_tb(). If chain is true (the default), then chained exceptions (the __cause__ or __context__ attributes of the exception) will be printed as well, like the interpreter itself does when printing an unhandled exception.

バージョン 3.5 で変更: 引数 etype は無視され、 value の型から推論されます。

バージョン 3.10 で変更: The etype parameter has been renamed to exc and is now positional-only.

traceback.print_exc(limit=None, file=None, chain=True)

print_exception(sys.exception(), limit, file, chain) の省略表現です。

traceback.print_last(limit=None, file=None, chain=True)

This is a shorthand for print_exception(sys.last_exc, limit, file, chain). In general it will work only after an exception has reached an interactive prompt (see sys.last_exc).

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 abs(limit) entries. If limit is omitted or None, all entries are printed. The optional f argument can be used to specify an alternate stack frame to start. The optional file argument has the same meaning as for print_tb().

バージョン 3.5 で変更: 負の limit がサポートされました。

traceback.extract_tb(tb, limit=None)

Return a StackSummary object representing a list of "pre-processed" stack trace entries extracted from the traceback object tb. It is useful for alternate formatting of stack traces. The optional limit argument has the same meaning as for print_tb(). A "pre-processed" stack trace entry is a FrameSummary object containing attributes filename, lineno, name, and line representing the information that is usually printed for a stack trace.

traceback.extract_stack(f=None, limit=None)

Extract the raw traceback from the current stack frame. The return value has the same format as for extract_tb(). The optional f and limit arguments have the same meaning as for print_stack().

traceback.format_list(extracted_list)

extract_tb() または extract_stack() が返すタプルのリストまたは FrameSummary オブジェクトが与えられると、出力の準備を整えた文字列のリストを返します。結果として生じるリストの中の各文字列は、引数リストの中の同じインデックスの要素に対応します。各文字列は末尾に改行が付いています。さらに、ソーステキスト行が None でないそれらの要素に対しては、文字列は内部に改行を含んでいるかもしれません。

traceback.format_exception_only(exc, /[, value])

Format the exception part of a traceback using an exception value such as given by 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 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 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.

バージョン 3.10 で変更: The etype parameter has been renamed to exc and is now positional-only.

バージョン 3.11 で変更: The returned list now includes any notes attached to the exception.

traceback.format_exception(exc, /, [value, tb, ]limit=None, chain=True)

スタックトレースと例外情報を書式化します。引数は print_exception() の対応する引数と同じ意味を持ちます。戻り値は文字列のリストで、それぞれの文字列は改行で終わり、そのいくつかは内部に改行を含みます。これらの行が連結されて出力される場合は、厳密に print_exception() と同じテキストが出力されます。

バージョン 3.5 で変更: 引数 etype は無視され、 value の型から推論されます。

バージョン 3.10 で変更: This function's behavior and signature were modified to match print_exception().

traceback.format_exc(limit=None, chain=True)

これは、print_exc(limit) に似ていますが、ファイルに出力する代わりに文字列を返します。

traceback.format_tb(tb, limit=None)

format_list(extract_tb(tb, limit)) の省略表現です。

traceback.format_stack(f=None, limit=None)

format_list(extract_stack(f, limit)) の省略表現です。

traceback.clear_frames(tb)

Clears the local variables of all the stack frames in a traceback tb by calling the clear() method of each frame object.

Added in version 3.4.

traceback.walk_stack(f)

Walk a stack following f.f_back from the given frame, yielding the frame and line number for each frame. If f is None, the current stack is used. This helper is used with StackSummary.extract().

Added in version 3.5.

traceback.walk_tb(tb)

Walk a traceback following tb_next yielding the frame and line number for each frame. This helper is used with StackSummary.extract().

Added in version 3.5.

このモジュールは以下のクラスも定義しています:

TracebackException オブジェクト

Added in version 3.5.

TracebackException objects are created from actual exceptions to capture data for later printing in a lightweight fashion.

class 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)

後のレンダリングのために例外をキャプチャします。 limit、lookup_lines、capture_locals は StackSummary class のものです。

If compact is true, only data that is required by TracebackException's format() method is saved in the class attributes. In particular, the __context__ field is calculated only if __cause__ is None and __suppress_context__ is false.

局所変数がキャプチャされたとき、それらはトレースバックに表示されることに注意してください。

max_group_width and max_group_depth control the formatting of exception groups (see 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 で変更: Added the max_group_width and max_group_depth parameters.

__cause__

A TracebackException of the original __cause__.

__context__

A TracebackException of the original __context__.

exceptions

If self represents an ExceptionGroup, this field holds a list of TracebackException instances representing the nested exceptions. Otherwise it is None.

Added in version 3.11.

__suppress_context__

The __suppress_context__ value from the original exception.

__notes__

The __notes__ value from the original exception, or None if the exception does not have any notes. If it is not None is it formatted in the traceback after the exception string.

Added in version 3.11.

stack

トレースバックを表す StackSummary。

exc_type

元々のトレースバックのクラス。

filename

構文エラー用 - エラーが発生したファイルの名前。

lineno

構文エラー用 - エラーが発生した行番号。

end_lineno

For syntax errors - the end line number where the error occurred. Can be None if not present.

Added in version 3.10.

text

構文エラー用 - エラーが発生したテクスト。

offset

構文エラー用 - エラーが発生したテクストへのオフセット。

end_offset

For syntax errors - the end offset into the text where the error occurred. Can be None if not present.

Added in version 3.10.

msg

構文エラー用 - コンパイラのエラーメッセージ。

classmethod from_exception(exc, *, limit=None, lookup_lines=True, capture_locals=False)

後のレンダリングのために例外をキャプチャします。 limit、lookup_lines、capture_locals は StackSummary class のものです。

局所変数がキャプチャされたとき、それらはトレースバックに表示されることに注意してください。

print(*, file=None, chain=True)

Print to file (default sys.stderr) the exception information returned by format().

Added in version 3.11.

format(*, chain=True)

例外を書式化します。

If chain is not True, __cause__ and __context__ will not be formatted.

返り値は文字列のジェネレータで、それぞれ改行で終わりますが、内部に改行を持つものもあります。 print_exception() はこのメソッドのラッパで、単にファイルに出力します。

format_exception_only()

トレースバックの例外部を書式化します。

返り値は文字列のジェネレータで、それぞれ改行で終わります。

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 SyntaxError exceptions, it consists of several lines that (when printed) display detailed information about where the syntax error occurred.

バージョン 3.11 で変更: The exception's notes are now included in the output.

StackSummary オブジェクト

Added in version 3.5.

StackSummary objects represent a call stack ready for formatting.

class traceback.StackSummary

classmethod extract(frame_gen, *, limit=None, lookup_lines=True, capture_locals=False)

Construct a StackSummary object from a frame generator (such as is returned by walk_stack() or walk_tb()).

If limit is supplied, only this many frames are taken from frame_gen. If lookup_lines is False, the returned FrameSummary objects will not have read their lines in yet, making the cost of creating the StackSummary cheaper (which may be valuable if it may not actually get formatted). If capture_locals is True the local variables in each FrameSummary are captured as object representations.

バージョン 3.12 で変更: Exceptions raised from repr() on a local variable (when capture_locals is True) are no longer propagated to the caller.

classmethod from_list(a_list)

Construct a StackSummary object from a supplied list of FrameSummary objects or old-style list of tuples. Each tuple should be a 4-tuple with filename, lineno, name, line as the elements.

format()

Returns a list of strings ready for printing. Each string in the resulting list corresponds to a single 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.

format_frame_summary(frame_summary)

Returns a string for printing one of the frames involved in the stack. This method is called for each FrameSummary object to be printed by StackSummary.format(). If it returns None, the frame is omitted from the output.

Added in version 3.11.

FrameSummary オブジェクト

Added in version 3.5.

A FrameSummary object represents a single frame in a traceback.

class traceback.FrameSummary(filename, lineno, name, lookup_line=True, locals=None, line=None)

Represents a single frame in the 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 False, the source code is not looked up until the FrameSummary has the line attribute accessed (which also happens when casting it to a tuple). line may be directly provided, and will prevent line lookups happening at all. locals is an optional local variable dictionary, and if supplied the variable representations are stored in the summary for later display.

FrameSummary instances have the following attributes:

filename

The filename of the source code for this frame. Equivalent to accessing f.f_code.co_filename on a frame object f.

lineno

The line number of the source code for this frame.

name

Equivalent to accessing f.f_code.co_name on a frame object f.

line

A string representing the source code for this frame, with leading and trailing whitespace stripped. If the source is not available, it is None.

トレースバックの例

この簡単な例では基本的な read-eval-print ループを実装しています。標準的な Python の対話インタープリタループに似ていますが、 Python のものより便利ではありません。インタープリタループのより完全な実装については、 code モジュールを参照してください。

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)

次の例は例外とトレースバックの出力並びに形式が異なることを示します:

import sys, traceback

def lumberjack():
    bright_side_of_life()

def bright_side_of_life():
    return tuple()[0]

try:
    lumberjack()
except IndexError:
    exc = sys.exception()
    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)

この例の出力は次のようになります:

*** 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',
 '  File "<doctest default[0]>", line 4, in lumberjack\n    bright_side_of_life()\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',
 '  File "<doctest default[0]>", line 4, in lumberjack\n    bright_side_of_life()\n',
 '  File "<doctest default[0]>", line 7, in bright_side_of_life\n    return tuple()[0]\n           ~~~~~~~^^^\n']
*** tb_lineno: 10

次の例は、スタックの print と format の違いを示しています:

>>> 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']

最後の例は、残りの幾つかの関数のデモをします:

>>> 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(type(an_error), an_error)
['IndexError: tuple index out of range\n']

__future__ --- Future statement definitions

ソースコード: Lib/__future__.py [https://github.com/python/cpython/tree/3.12/Lib/__future__.py]

Imports of the form from __future__ import feature are called future statements. These are special-cased by the Python compiler to allow the use of new Python features in modules containing the future statement before the release in which the feature becomes standard.

While these future statements are given additional special meaning by the Python compiler, they are still executed like any other import statement and the __future__ exists and is handled by the import system the same way any other Python module would be. This design serves three purposes:

import 文を解析する既存のツールを混乱させることを避け、インポートしようとしているモジュールを見つけられるようにするため。

互換性のない変化がいつ言語に導入され、いつ言語の一部になる --- あるいは、なった --- のかを文書化するため。これは実行できる形式で書かれたドキュメントなので、 __future__ をインポートしてその中身を調べることでプログラムから調査することができます。

To ensure that future statements run under releases prior to Python 2.1 at least yield runtime exceptions (the import of __future__ will fail, because there was no module of that name prior to 2.1).

モジュールコンテンツ

機能の記述が __future__ から削除されたことはまだありません。 Python 2.1 で future 文が導入されて以来、この仕組みを使って以下の機能が言語に導入されてきました:

feature

optional in

mandatory in

effect

nested_scopes

2.1.0b1

2.2

PEP 227 [https://peps.python.org/pep-0227/]: Statically Nested Scopes

generators

2.2.0a1

2.3

PEP 255 [https://peps.python.org/pep-0255/]: Simple Generators

division

2.2.0a2

3.0

PEP 238 [https://peps.python.org/pep-0238/]: Changing the Division Operator

absolute_import

2.5.0a1

3.0

PEP 328 [https://peps.python.org/pep-0328/]: Imports: Multi-Line and Absolute/Relative

with_statement

2.5.0a1

2.6

PEP 343 [https://peps.python.org/pep-0343/]: The "with" Statement

print_function

2.6.0a2

3.0

PEP 3105 [https://peps.python.org/pep-3105/]: Make print a function

unicode_literals

2.6.0a2

3.0

PEP 3112 [https://peps.python.org/pep-3112/]: Bytes literals in Python 3000

generator_stop

3.5.0b1

3.7

PEP 479 [https://peps.python.org/pep-0479/]: StopIteration handling inside generators

annotations

3.7.0b1

TBD [1]

PEP 563 [https://peps.python.org/pep-0563/]: Postponed evaluation of annotations

class __future__._Feature

__future__.py のそれぞれの文は次のような形式をしています:

FeatureName = _Feature(OptionalRelease, MandatoryRelease,
                       CompilerFlag)

ここで、普通は、 OptionalRelease は MandatoryRelease より小さく、2つとも sys.version_info と同じフォーマットの5つのタプルからなります:

(PY_MAJOR_VERSION, # the 2 in 2.1.0a3; an int
 PY_MINOR_VERSION, # the 1; an int
 PY_MICRO_VERSION, # the 0; an int
 PY_RELEASE_LEVEL, # "alpha", "beta", "candidate" or "final"; string
 PY_RELEASE_SERIAL # the 3; an int
)

_Feature.getOptionalRelease()

OptionalRelease はその機能が導入された最初のリリースを記録します。

_Feature.getMandatoryRelease()

まだ時期が来ていない MandatoryRelease の場合、MandatoryRelease はその機能が言語の一部となるリリースを記します。

その他の場合、MandatoryRelease はその機能がいつ言語の一部になったのかを記録します。そのリリースから、あるいはそれ以降のリリースでは、この機能を使う際に future 文は必要ではありませんが、future 文を使い続けても構いません。

MandatoryRelease may also be None, meaning that a planned feature got dropped or that it is not yet decided.

_Feature.compiler_flag

CompilerFlag is the (bitfield) flag that should be passed in the fourth argument to the built-in function compile() to enable the feature in dynamically compiled code. This flag is stored in the _Feature.compiler_flag attribute on _Feature instances.

[1]

from __future__ import annotations was previously scheduled to become mandatory in Python 3.10, but the Python Steering Council twice decided to delay the change (announcement for Python 3.10 [https://mail.python.org/archives/list/python-dev@python.org/message/CLVXXPQ2T2LQ5MP2Y53VVQFCXYWQJHKZ/]; announcement for Python 3.11 [https://mail.python.org/archives/list/python-dev@python.org/message/VIZEBX5EYMSYIJNDBF6DMUMZOCWHARSO/]). No final decision has been made yet. See also PEP 563 [https://peps.python.org/pep-0563/] and PEP 649 [https://peps.python.org/pep-0649/].

参考

future 文 (future statement)

コンパイラがどのように future インポートを扱うか。

PEP 236 [https://peps.python.org/pep-0236/] - Back to the __future__

__future__ 機構の原案

gc --- Garbage Collector interface

このモジュールは、循環ガベージコレクタの無効化・検出頻度の調整・デバッグオブションの設定などを行うインターフェースを提供します。また、検出した到達不能オブジェクトのうち、解放する事ができないオブジェクトを参照する事もできます。循環ガベージコレクタはPythonの参照カウントを補うためのものなので、もしプログラム中で循環参照が発生しない事が明らかな場合には検出をする必要はありません。自動検出は、 gc.disable() で停止する事ができます。メモリリークをデバッグするときには、 gc.set_debug(gc.DEBUG_LEAK) とします。これは gc.DEBUG_SAVEALL を含んでいることに注意しましょう。ガベージとして検出されたオブジェクトは、インスペクション用に gc.garbage に保存されます。

gc モジュールは、以下の関数を提供しています:

gc.enable()

自動ガベージコレクションを有効にします。

gc.disable()

自動ガベージコレクションを無効にします。

gc.isenabled()

自動ガベージコレクションが有効なら True を返します。

gc.collect(generation=2)

With no arguments, run a full collection. The optional argument generation may be an integer specifying which generation to collect (from 0 to 2). A ValueError is raised if the generation number is invalid. The number of unreachable objects found is returned.

ビルトイン型が持っている free list は、フルGCか最高世代(2)のGCの時にクリアされます。 float など、実装によって幾つかの free list では全ての要素が解放されるわけではありません。

The effect of calling gc.collect() while the interpreter is already performing a collection is undefined.

gc.set_debug(flags)

ガベージコレクションのデバッグフラグを設定します。デバッグ情報は sys.stderr に出力されます。デバッグフラグは、下の値の組み合わせを指定する事ができます。

gc.get_debug()

現在のデバッグフラグを返します。

gc.get_objects(generation=None)

Returns a list of all objects tracked by the collector, excluding the list returned. If generation is not None, return only the objects tracked by the collector that are in that generation.

バージョン 3.8 で変更: 新しい generation パラメータ。

引数 generation で 監査イベント gc.get_objects を送出します。

gc.get_stats()

インタプリタが開始してからの、世代ごと回収統計を持つ辞書の、3 世代ぶんのリストを返します。キーの数は将来変わるかもしれませんが、現在のところそれぞれの辞書には以下の項目が含まれています:

collections は、この世代が検出を行った回数です;

collected は、この世代内で回収されたオブジェクトの総数です;

uncollectable は、この世代内で回収不能であることがわかった (そしてそれゆえに garbage リストに移動した) オブジェクトの総数です。

Added in version 3.4.

gc.set_threshold(threshold0[, threshold1[, threshold2]])

ガベージコレクションの閾値（検出頻度）を指定します。 threshold0 を 0 にすると、検出は行われません。

The GC classifies objects into three generations depending on how many collection sweeps they have survived. New objects are placed in the youngest generation (generation 0). If an object survives a collection it is moved into the next older generation. Since generation 2 is the oldest generation, objects in that generation remain there after a collection. In order to decide when to run, the collector keeps track of the number object allocations and deallocations since the last collection. When the number of allocations minus the number of deallocations exceeds threshold0, collection starts. Initially only generation 0 is examined. If generation 0 has been examined more than threshold1 times since generation 1 has been examined, then generation 1 is examined as well. With the third generation, things are a bit more complicated, see Collecting the oldest generation [https://devguide.python.org/garbage_collector/#collecting-the-oldest-generation] for more information.

gc.get_count()

現在の検出数を、 (count0, count1, count2) のタプルで返します。

gc.get_threshold()

現在の検出閾値を、 (threshold0, threshold1, threshold2) のタプルで返します。

gc.get_referrers(*objs)

objsで指定したオブジェクトのいずれかを参照しているオブジェクトのリストを返します。この関数では、ガベージコレクションをサポートしているコンテナのみを返します。他のオブジェクトを参照していても、ガベージコレクションをサポートしていない拡張型は含まれません。

尚、戻り値のリストには、すでに参照されなくなっているが、循環参照の一部でまだガベージコレクションで回収されていないオブジェクトも含まれるので注意が必要です。有効なオブジェクトのみを取得する場合、 get_referrers() の前に collect() を呼び出してください。

警告

get_referrers() から返されるオブジェクトは作りかけや利用できない状態である場合があるので、利用する際には注意が必要です。 get_referrers() をデバッグ以外の目的で利用するのは避けてください。

引数 objs を指定して 監査イベント gc.get_referrers を送出します。

gc.get_referents(*objs)

引数で指定したオブジェクトのいずれかから参照されている、全てのオブジェクトのリストを返します。参照先のオブジェクトは、引数で指定したオブジェクトの Cレベルメソッド tp_traverse で取得し、全てのオブジェクトが直接到達可能な全てのオブジェクトを返すわけではありません。 tp_traverse はガベージコレクションをサポートするオブジェクトのみが実装しており、ここで取得できるオブジェクトは循環参照の一部となる可能性のあるオブジェクトのみです。従って、例えば整数オブジェクトが直接到達可能であっても、このオブジェクトは戻り値には含まれません。

引数 objs を指定して 監査イベント gc.get_referents を送出します。

gc.is_tracked(obj)

obj がガベージコレクタに管理されていたら True を返し、それ以外の場合は False を返します。一般的なルールとして、アトミックな (訳注: 他のオブジェクトを参照しないで単一で値を表す型。 int や str など) 型のインスタンスは管理されず、それ以外の型 (コンテナ型、ユーザー定義型など) のインスタンスは管理されます。しかし、いくつかの型では専用の最適化を行い、シンプルなインスタンスの場合に GCのオーバーヘッドを減らしています。 (例: 全ての key と value がアトミック型の値である dict)

>>> gc.is_tracked(0)
False
>>> gc.is_tracked("a")
False
>>> gc.is_tracked([])
True
>>> gc.is_tracked({})
False
>>> gc.is_tracked({"a": 1})
False
>>> gc.is_tracked({"a": []})
True

Added in version 3.1.

gc.is_finalized(obj)

Returns True if the given object has been finalized by the garbage collector, False otherwise.

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

Added in version 3.9.

gc.freeze()

Freeze all the objects tracked by the garbage collector; move them to a permanent generation and ignore them in all the future collections.

If a process will fork() without exec(), avoiding unnecessary copy-on-write in child processes will maximize memory sharing and reduce overall memory usage. This requires both avoiding creation of freed "holes" in memory pages in the parent process and ensuring that GC collections in child processes won't touch the gc_refs counter of long-lived objects originating in the parent process. To accomplish both, call gc.disable() early in the parent process, gc.freeze() right before fork(), and gc.enable() early in child processes.

Added in version 3.7.

gc.unfreeze()

Permanent世代領域にあるオブジェクトを解凍します。つまり、最も古い世代へ戻します。

Added in version 3.7.

gc.get_freeze_count()

Permanent世代領域にあるオブジェクトの数を返します。

Added in version 3.7.

以下の変数は読み出し専用アクセスのために提供されています。(この変数を操作することはできますが、その値は記憶されません):

gc.garbage

到達不能であることが検出されたが、解放する事ができないオブジェクトのリスト（回収不能オブジェクト）。Python 3.4 からは、NULL でない tp_del スロットを持つ C 拡張型のインスタンスを使っている場合を除き、このリストはほとんど常に空であるはずです。

DEBUG_SAVEALL が設定されている場合、全ての到達不能オブジェクトは解放されずにこのリストに格納されます。

バージョン 3.2 で変更: インタプリタシャットダウン 時にこのリストが空でない場合、(デフォルトでは黙りますが) ResourceWarning が発行されます。 DEBUG_UNCOLLECTABLE がセットされていると、加えて回収不能オブジェクトを出力します。

バージョン 3.4 で変更: Following PEP 442 [https://peps.python.org/pep-0442/], objects with a __del__() method don't end up in gc.garbage anymore.

gc.callbacks

ガベージコレクタの起動前と終了後に呼び出されるコールバック関数のリスト。コールバックは phase と info の2つの引数で呼び出されます。

phase は以下 2 つのいずれかです:

"start": ガベージコレクションを始めます。

"stop": ガベージコレクションが終了しました。

info はコールバックに付加情報を提供する辞書です。現在のところ以下のキーが定義されています:

"generation": 回収される最も古い世代。

"collected": phase が "stop" のとき、正常に回収されたオブジェクトの数。

"uncollectable": phase が "stop" のとき、回収出来ずに garbage リストに入れられたオブジェクトの数。

アプリケーションは自身のコールバックをこのリストに追加出来ます。基本的なユースケースは以下のようなものでしょう:

世代が回収される頻度やガベージコレクションにかかった時間の長さといった、ガベージコレクションの統計情報を集めます。

garbage に回収できない独自の型のオブジェクトが現れたとき、アプリケーションがそれらを特定し消去できるようにする。

Added in version 3.3.

以下は set_debug() に指定することのできる定数です:

gc.DEBUG_STATS

検出中に統計情報を出力します。この情報は、検出頻度を最適化する際に有益です。

gc.DEBUG_COLLECTABLE

見つかった回収可能オブジェクトの情報を出力します。

gc.DEBUG_UNCOLLECTABLE

見つかった回収不能オブジェクト（到達不能だが、ガベージコレクションで解放する事ができないオブジェクト）の情報を出力します。回収不能オブジェクトは、 garbage リストに追加されます。

バージョン 3.2 で変更: インタプリタシャットダウン 時に garbage リストが空でない場合に、その中身の出力も行います。

gc.DEBUG_SAVEALL

設定されている場合、全ての到達不能オブジェクトは解放されずに garbage に追加されます。これはプログラムのメモリリークをデバッグするときに便利です。

gc.DEBUG_LEAK

プログラムのメモリリークをデバッグするときに指定します（ DEBUG_COLLECTABLE | DEBUG_UNCOLLECTABLE | DEBUG_SAVEALL と同じ）。

inspect --- Inspect live objects

ソースコード: Lib/inspect.py [https://github.com/python/cpython/tree/3.12/Lib/inspect.py]

inspect は、活動中のオブジェクト (モジュール、クラス、メソッド、関数、トレースバック、フレームオブジェクト、コードオブジェクトなど) から情報を取得する関数を定義しており、クラスの内容を調べたり、メソッドのソースコードを取得したり、関数の引数リストを取り出して整形したり、詳細なトレースバックを表示するのに必要な情報を取得したりするために利用できます。

このモジュールの機能は4種類に分類することができます。型チェック、ソースコードの情報取得、クラスや関数からの情報取得、インタープリタのスタック情報の調査です。

型とメンバー

getmembers() は、クラスやモジュールなどのオブジェクトからメンバーを取得します。名前が "is" で始まる関数は、主に getmembers() の第2引数として利用するために提供されています。以下のような特殊属性を参照できるかどうか調べる時にも使えるでしょう (モジュール属性については インポート関連のモジュール属性 を参照してください):

型

属性

説明

クラス

__doc__

ドキュメント文字列

__name__

クラスの定義名

__qualname__

qualified name

__module__

クラスを定義しているモジュールの名前

__type_params__

A tuple containing the type parameters of a generic class

メソッド

__doc__

ドキュメント文字列

__name__

メソッドの定義名

__qualname__

qualified name

__func__

メソッドを実装している関数オブジェクト

__self__

メソッドに結合しているインスタンス、または None

__module__

name of module in which this method was defined

関数

__doc__

ドキュメント文字列

__name__

関数の定義名

__qualname__

qualified name

__code__

関数をコンパイルした バイトコード を格納するコードオブジェクト

__defaults__

位置またはキーワード引数の全ての既定値のタプル

__kwdefaults__

キーワード専用引数の全ての既定値のマッピング

__globals__

関数が定義されたグローバル名前空間

__builtins__

builtins namespace

__annotations__

仮引数名からアノテーションへのマッピング; "return" キーは return アノテーションに予約されています

__type_params__

A tuple containing the type parameters of a generic function

__module__

name of module in which this function was defined

traceback

tb_frame

このレベルのフレームオブジェクト

tb_lasti

最後に実行しようとしたバイトコード中のインストラクションを示すインデックス

tb_lineno

現在の Python ソースコードの行番号

tb_next

このオブジェクトの内側 (このレベルから呼び出された) のトレースバックオブジェクト

フレーム

f_back

外側 (このフレームを呼び出した) のフレームオブジェクト

f_builtins

このフレームで参照している組み込み名前空間

f_code

このフレームで実行しているコードオブジェクト

f_globals

このフレームで参照しているグローバル名前空間

f_lasti

最後に実行しようとしたバイトコード中のインストラクションを示すインデックス

f_lineno

現在の Python ソースコードの行番号

f_locals

このフレームで参照しているローカル名前空間

f_trace

このフレームのトレース関数、または None

コード

co_argcount

number of arguments (not including keyword only arguments, * or ** args)

co_code

コンパイルされたバイトコードそのままの文字列

co_cellvars

tuple of names of cell variables (referenced by containing scopes)

co_consts

バイトコード中で使用している定数のタプル

co_filename

コードオブジェクトを生成したファイルのファイル名

co_firstlineno

Python ソースコードの先頭行

co_flags

bitmap of CO_* flags, read more here

co_lnotab

行番号からバイトコードインデックスへの変換表を文字列にエンコードしたもの

co_freevars

tuple of names of free variables (referenced via a function's closure)

co_posonlyargcount

number of positional only arguments

co_kwonlyargcount

number of keyword only arguments (not including ** arg)

co_name

コードオブジェクトが定義されたときの名前

co_qualname

fully qualified name with which this code object was defined

co_names

tuple of names other than arguments and function locals

co_nlocals

ローカル変数の数

co_stacksize

必要とされる仮想マシンのスタックスペース

co_varnames

引数名とローカル変数名のタプル

ジェネレータ

__name__

name

__qualname__

qualified name

gi_frame

フレーム

gi_running

ジェネレータが実行中かどうか

gi_code

コード

gi_yieldfrom

yield from でイテレートされているオブジェクト、または None

コルーチン

__name__

name

__qualname__

qualified name

cr_await

待機されているオブジェクト、または None

cr_frame

フレーム

cr_running

コルーチンが実行中かどうか

cr_code

コード

cr_origin

where coroutine was created, or None. See sys.set_coroutine_origin_tracking_depth()

組み込み

__doc__

ドキュメント文字列

__name__

関数、メソッドの元々の名前

__qualname__

qualified name

__self__

メソッドが結合しているインスタンス、または None

バージョン 3.5 で変更: ジェネレータに __qualname__ と gi_yieldfrom 属性が追加されました。

ジェネレータの __name__ 属性がコード名ではなく関数名から設定されるようになり、変更できるようになりました。

バージョン 3.7 で変更: Add cr_origin attribute to coroutines.

バージョン 3.10 で変更: Add __builtins__ attribute to functions.

inspect.getmembers(object[, predicate])

Return all the members of an object in a list of (name, value) pairs sorted by name. If the optional predicate argument—which will be called with the value object of each member—is supplied, only members for which the predicate returns a true value are included.

注釈

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 __dir__().

inspect.getmembers_static(object[, predicate])

Return all the members of an object in a list of (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.

注釈

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.

Added in version 3.11.

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 importlib.machinery.all_suffixes(). If it matches, the final path component is returned with the extension removed. Otherwise, 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 None.

バージョン 3.3 で変更: The function is based directly on importlib.

inspect.ismodule(object)

オブジェクトがモジュールの場合 True を返します。

inspect.isclass(object)

オブジェクトが組み込みか Python が生成したクラスの場合に True を返します。

inspect.ismethod(object)

オブジェクトがメソッドの場合 True を返します。

inspect.isfunction(object)

オブジェクトが、 lambda 式で生成されたものを含む Python 関数の場合に True を返します。

inspect.isgeneratorfunction(object)

オブジェクトが Python のジェネレータ関数の場合 True を返します。

バージョン 3.8 で変更: Functions wrapped in functools.partial() now return True if the wrapped function is a Python generator function.

inspect.isgenerator(object)

オブジェクトがジェネレータの場合 True を返します。

inspect.iscoroutinefunction(object)

Return True if the object is a coroutine function (a function defined with an async def syntax), a functools.partial() wrapping a coroutine function, or a sync function marked with markcoroutinefunction().

Added in version 3.5.

バージョン 3.8 で変更: Functions wrapped in functools.partial() now return True if the wrapped function is a coroutine function.

バージョン 3.12 で変更: Sync functions marked with markcoroutinefunction() now return True.

inspect.markcoroutinefunction(func)

Decorator to mark a callable as a coroutine function if it would not otherwise be detected by iscoroutinefunction().

This may be of use for sync functions that return a coroutine, if the function is passed to an API that requires iscoroutinefunction().

When possible, using an async def function is preferred. Also acceptable is calling the function and testing the return with iscoroutine().

Added in version 3.12.

inspect.iscoroutine(object)

オブジェクトが async def で生成された コルーチン の場合 True を返します。

Added in version 3.5.

inspect.isawaitable(object)

オブジェクトを await 式内で使用できる場合 True を返します。

Can also be used to distinguish generator-based coroutines from regular generators:

import types

def gen():
    yield
@types.coroutine
def gen_coro():
    yield

assert not isawaitable(gen())
assert isawaitable(gen_coro())

Added in version 3.5.

inspect.isasyncgenfunction(object)

Return True if the object is an asynchronous generator function, for example:

>>> async def agen():
...     yield 1
...
>>> inspect.isasyncgenfunction(agen)
True

Added in version 3.6.

バージョン 3.8 で変更: Functions wrapped in functools.partial() now return True if the wrapped function is a asynchronous generator function.

inspect.isasyncgen(object)

オブジェクトが asynchronous generator 関数によって生成された asynchronous generator iterator である場合に True を返します。

Added in version 3.6.

inspect.istraceback(object)

オブジェクトがトレースバックの場合は True を返します。

inspect.isframe(object)

オブジェクトがフレームの場合は True を返します。

inspect.iscode(object)

オブジェクトがコードの場合は True を返します。

inspect.isbuiltin(object)

オブジェクトが組み込み関数か束縛済みの組み込みメソッドの場合に True を返します。

inspect.ismethodwrapper(object)

Return True if the type of object is a MethodWrapperType.

These are instances of MethodWrapperType, such as __str__(), __eq__() and __repr__().

Added in version 3.11.

inspect.isroutine(object)

オブジェクトがユーザ定義か組み込みの関数またはメソッドの場合は True を返します。

inspect.isabstract(object)

オブジェクトが抽象基底クラスであるときに True を返します。

inspect.ismethoddescriptor(object)

オブジェクトがメソッドデスクリプタであり、 ismethod(), isclass(), isfunction(), isbuiltin() でない場合に True を返します。

This, for example, is true of int.__add__. An object passing this test has a __get__() method but not a __set__() method, but beyond that the set of attributes varies. A __name__ attribute is usually sensible, and __doc__ often is.

Methods implemented via descriptors that also pass one of the other tests return False from the ismethoddescriptor() test, simply because the other tests promise more -- you can, e.g., count on having the __func__ attribute (etc) when an object passes ismethod().

inspect.isdatadescriptor(object)

オブジェクトがデータデスクリプタの場合に True を返します。

Data descriptors have a __set__ or a __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 __name__ and __doc__ attributes (properties, getsets, and members have both of these attributes), but this is not guaranteed.

inspect.isgetsetdescriptor(object)

オブジェクトが getset デスクリプタの場合に True を返します。

CPython 実装の詳細: getset とは、拡張モジュールで PyGetSetDef 構造体を用いて定義された属性のことです。そのような型を持たない Python 実装の場合は、このメソッドは常に False を返します。

inspect.ismemberdescriptor(object)

オブジェクトがメンバーデスクリプタの場合に True を返します。

CPython 実装の詳細: メンバーデスクリプタとは、拡張モジュールで PyMemberDef 構造体を用いて定義された属性のことです。そのような型を持たない Python 実装の場合は、このメソッドは常に False を返します。

ソースコードの情報取得

inspect.getdoc(object)

Get the documentation string for an object, cleaned up with 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 None if the documentation string is invalid or missing.

バージョン 3.5 で変更: ドキュメンテーション文字列がオーバーライドされていない場合は継承されるようになりました。

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 None. This could happen if the object has been defined in C or the interactive shell.

inspect.getfile(object)

オブジェクトを定義している (テキストまたはバイナリの) ファイルの名前を返します。オブジェクトが組み込みモジュール、クラス、関数の場合は TypeError 例外が発生します。

inspect.getmodule(object)

Try to guess which module an object was defined in. Return None if the module cannot be determined.

inspect.getsourcefile(object)

Return the name of the Python source file in which an object was defined or None if no way can be identified to get the source. This will fail with a TypeError if the object is a built-in module, class, or function.

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 OSError is raised if the source code cannot be retrieved. A TypeError is raised if the object is a built-in module, class, or function.

バージョン 3.3 で変更: IOError の代わりに OSError を送出します。前者は後者のエイリアスです。

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 OSError is raised if the source code cannot be retrieved. A TypeError is raised if the object is a built-in module, class, or function.

バージョン 3.3 で変更: IOError の代わりに OSError を送出します。前者は後者のエイリアスです。

inspect.cleandoc(doc)

コードブロックと位置を合わせるためのインデントを docstring から削除します。

先頭行の行頭の空白文字は全て削除されます。 2行目以降では全行で同じ数の行頭の空白文字が、削除できるだけ削除されます。その後、先頭と末尾の空白行が削除され、全てのタブが空白に展開されます。

Signature オブジェクトで呼び出し可能オブジェクトを内省する

Added in version 3.3.

The Signature object represents the call signature of a callable object and its return annotation. To retrieve a Signature object, use the signature() function.

inspect.signature(callable, *, follow_wrapped=True, globals=None, locals=None, eval_str=False)

Return a Signature object for the given callable:

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

単純な関数やクラスから、 functools.partial() オブジェクトまで、幅広い Python の呼び出し可能なオブジェクトを受け付けます。

For objects defined in modules using stringized annotations (from __future__ import annotations), signature() will attempt to automatically un-stringize the annotations using get_annotations(). The globals, locals, and eval_str parameters are passed into get_annotations() when resolving the annotations; see the documentation for get_annotations() for instructions on how to use these parameters.

Raises ValueError if no signature can be provided, and TypeError if that type of object is not supported. Also, if the annotations are stringized, and eval_str is not false, the eval() call(s) to un-stringize the annotations in 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 the FAQ entry on positional-only parameters.

バージョン 3.5 で変更: The follow_wrapped parameter was added. Pass False to get a signature of callable specifically (callable.__wrapped__ will not be used to unwrap decorated callables.)

バージョン 3.10 で変更: The globals, locals, and eval_str parameters were added.

注釈

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.

CPython 実装の詳細: If the passed object has a __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.

class inspect.Signature(parameters=None, *, return_annotation=Signature.empty)

A Signature object represents the call signature of a function and its return annotation. For each parameter accepted by the function it stores a Parameter object in its parameters collection.

The optional parameters argument is a sequence of 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.

Signature objects are immutable. Use Signature.replace() to make a modified copy.

バージョン 3.5 で変更: Signature objects are now picklable and hashable.

empty

return アノテーションがないことを指すクラスレベルの特殊マーカです。

parameters

An ordered mapping of parameters' names to the corresponding 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.

return_annotation

呼び出し可能オブジェクトの "return" アノテーションです。呼び出し可能オブジェクトに "return" アノテーションがない場合、この属性は Signature.empty に設定されます。

bind(*args, **kwargs)

Create a mapping from positional and keyword arguments to parameters. Returns BoundArguments if *args and **kwargs match the signature, or raises a TypeError.

bind_partial(*args, **kwargs)

Works the same way as Signature.bind(), but allows the omission of some required arguments (mimics functools.partial() behavior.) Returns BoundArguments, or raises a TypeError if the passed arguments do not match the signature.

replace(*[, parameters][, return_annotation])

Create a new Signature instance based on the instance 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 return_annotation from the copied Signature, pass in Signature.empty.

>>> 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'"

classmethod from_callable(obj, *, follow_wrapped=True, globals=None, locals=None, eval_str=False)

Return a Signature (or its subclass) object for a given callable obj.

This method simplifies subclassing of Signature:

class MySignature(Signature):
    pass
sig = MySignature.from_callable(sum)
assert isinstance(sig, MySignature)

Its behavior is otherwise identical to that of signature().

Added in version 3.5.

バージョン 3.10 で変更: The globals, locals, and eval_str parameters were added.

class inspect.Parameter(name, kind, *, default=Parameter.empty, annotation=Parameter.empty)

Parameter objects are immutable. Instead of modifying a Parameter object, you can use Parameter.replace() to create a modified copy.

バージョン 3.5 で変更: Parameter objects are now picklable and hashable.

empty

デフォルト値とアノテーションがないことを指すクラスレベルの特殊マーカです。

name

仮引数名 (文字列) です。名前は有効な Python 識別子でなければなりません。

CPython 実装の詳細: CPython generates implicit parameter names of the form .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 implicit0.

default

引数のデフォルト値です。引数にデフォルト値がない場合、この属性は Parameter.empty に設定されます。

annotation

引数のアノテーションです。引数にアノテーションがない場合、この属性は Parameter.empty に設定されます。

kind

Describes how argument values are bound to the parameter. The possible values are accessible via Parameter (like Parameter.KEYWORD_ONLY), and support comparison and ordering, in the following order:

名前

意味

POSITIONAL_ONLY

Value must be supplied as a positional argument. Positional only parameters are those which appear before a / entry (if present) in a Python function definition.

POSITIONAL_OR_KEYWORD

値をキーワードまたは位置引数として渡すことができます (これは Python で実装された関数の標準的な束縛動作です)。

VAR_POSITIONAL

その他の仮引数に束縛されていない位置引数のタプルです。Python の関数定義における *args 仮引数に対応します。

KEYWORD_ONLY

値をキーワード引数として渡さなければなりません。キーワード専用引数は Python の関数定義において * や *args の後に現れる引数です。

VAR_KEYWORD

その他の仮引数に束縛されていないキーワード引数の辞書です。Python の関数定義における **kwargs 仮引数に対応します。

Example: print all keyword-only arguments without default values:

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

kind.description

Describes a enum value of Parameter.kind.

Added in version 3.8.

Example: print all descriptions of arguments:

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

replace(*[, name][, kind][, default][, annotation])

Create a new Parameter instance based on the instance replaced was invoked on. To override a Parameter attribute, pass the corresponding argument. To remove a default value or/and an annotation from a Parameter, pass Parameter.empty.

>>> 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'"

バージョン 3.4 で変更: In Python 3.3 Parameter objects were allowed to have name set to None if their kind was set to POSITIONAL_ONLY. This is no longer permitted.

class inspect.BoundArguments

Result of a Signature.bind() or Signature.bind_partial() call. Holds the mapping of arguments to the function's parameters.

arguments

A mutable mapping of parameters' names to arguments' values. Contains only explicitly bound arguments. Changes in arguments will reflect in args and kwargs.

Should be used in conjunction with Signature.parameters for any argument processing purposes.

注釈

Arguments for which Signature.bind() or Signature.bind_partial() relied on a default value are skipped. However, if needed, use BoundArguments.apply_defaults() to add them.

バージョン 3.9 で変更: arguments is now of type dict. Formerly, it was of type collections.OrderedDict.

args

位置引数の値のタプルです。arguments 属性から動的に計算されます。

kwargs

キーワード引数の値の辞書です。arguments 属性から動的に計算されます。

signature

親の Signature オブジェクトへの参照です。

apply_defaults()

存在しない引数のデフォルト値を設定します。

For variable-positional arguments (*args) the default is an empty tuple.

For variable-keyword arguments (**kwargs) the default is an empty dict.

>>> def foo(a, b='ham', *args): pass
>>> ba = inspect.signature(foo).bind('spam')
>>> ba.apply_defaults()
>>> ba.arguments
{'a': 'spam', 'b': 'ham', 'args': ()}

Added in version 3.5.

The args and kwargs properties can be used to invoke functions:

def test(a, *, b):
    ...

sig = signature(test)
ba = sig.bind(10, b=20)
test(*ba.args, **ba.kwargs)

参考

PEP 362 [https://peps.python.org/pep-0362/]: - 関数シグニチャオブジェクト

The detailed specification, implementation details and examples.

クラスと関数

inspect.getclasstree(classes, unique=False)

リストで指定したクラスの継承関係から、ネストしたリストを作成します。ネストしたリストには、直前の要素から派生したクラスが格納されます。各要素は長さ2のタプルで、クラスと基底クラスのタプルを格納しています。unique が真の場合、各クラスは戻り値のリスト内に一つだけしか格納されません。真でなければ、多重継承を利用したクラスとその派生クラスは複数回格納される場合があります。

inspect.getfullargspec(func)

Get the names and default values of a Python function's parameters. A named tuple is returned:

FullArgSpec(args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations)

args is a list of the positional parameter names. varargs is the name of the * parameter or None if arbitrary positional arguments are not accepted. varkw is the name of the ** parameter or 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 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 "return" is used to report the function return value annotation (if any).

Note that signature() and 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 inspect module API.

バージョン 3.4 で変更: This function is now based on signature(), but still ignores __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 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 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.

inspect.getargvalues(frame)

指定したフレームに渡された引数の情報を取得します。戻り値は 名前付きタプル ArgInfo(args, varargs, keywords, locals) です。args は引数名のリストです。 varargs と keywords は * 引数と ** 引数の名前で、引数がなければ None となります。 locals は指定したフレームのローカル変数の辞書です。

注釈

This function was inadvertently marked as deprecated in Python 3.5.

inspect.formatargvalues(args[, varargs, varkw, locals, formatarg, formatvarargs, formatvarkw, formatvalue])

getargvalues() で取得した4つの値を読みやすく整形します。 format* 引数はオプションで、名前と値を文字列に変換する整形関数を指定することができます。

注釈

This function was inadvertently marked as deprecated in Python 3.5.

inspect.getmro(cls)

cls クラスの基底クラス (cls 自身も含む) を、メソッドの優先順位順に並べたタプルを返します。結果のリスト内で各クラスは一度だけ格納されます。メソッドの優先順位はクラスの型によって異なります。非常に特殊なユーザ定義のメタクラスを使用していない限り、cls が戻り値の先頭要素となります。

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 self) to the associated instance. A dict is returned, mapping the argument names (including the names of the * and ** arguments, if any) to their values from args and kwds. In case of invoking func incorrectly, i.e. whenever 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:

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

Added in version 3.2.

バージョン 3.5 で非推奨: Use Signature.bind() and Signature.bind_partial() instead.

inspect.getclosurevars(func)

Get the mapping of external name references in a Python function or method func to their current values. A named tuple 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 の関数やメソッドでない場合 TypeError が送出されます。

Added in version 3.3.

inspect.unwrap(func, *, stop=None)

Get the object wrapped by func. It follows the chain of __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, signature() uses this to stop unwrapping if any object in the chain has a __signature__ attribute defined.

ValueError is raised if a cycle is encountered.

Added in version 3.4.

inspect.get_annotations(obj, *, globals=None, locals=None, eval_str=False)

Compute the annotations dict for an object.

obj may be a callable, class, or module. Passing in an object of any other type raises TypeError.

Returns a dict. 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:

If eval_str is true, values of type str will be un-stringized using eval(). This is intended for use with stringized annotations (from __future__ import annotations).

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

Ignores inherited annotations on classes. If a class doesn't have its own annotations dict, returns an empty dict.

All accesses to object members and dict values are done using getattr() and dict.get() for safety.

Always, always, always returns a freshly created dict.

eval_str controls whether or not values of type str are replaced with the result of calling eval() on those values:

If eval_str is true, eval() is called on values of type str. (Note that get_annotations doesn't catch exceptions; if eval() raises an exception, it will unwind the stack past the get_annotations call.)

If eval_str is false (the default), values of type str are unchanged.

globals and locals are passed in to eval(); see the documentation for eval() for more information. If globals or locals is None, this function may replace that value with a context-specific default, contingent on type(obj):

If obj is a module, globals defaults to obj.__dict__.

If obj is a class, globals defaults to sys.modules[obj.__module__].__dict__ and locals defaults to the obj class namespace.

If obj is a callable, globals defaults to obj.__globals__, although if obj is a wrapped function (using functools.update_wrapper()) it is first unwrapped.

Calling get_annotations is best practice for accessing the annotations dict of any object. See Annotations Best Practices for more information on annotations best practices.

Added in version 3.10.

インタープリタスタック

Some of the following functions return FrameInfo objects. For backwards compatibility these objects allow tuple-like operations on all attributes except positions. This behavior is considered deprecated and may be removed in the future.

class inspect.FrameInfo

frame

The frame object that the record corresponds to.

filename

The file name associated with the code being executed by the frame this record corresponds to.

lineno

The line number of the current line associated with the code being executed by the frame this record corresponds to.

function

The function name that is being executed by the frame this record corresponds to.

code_context

A list of lines of context from the source code that's being executed by the frame this record corresponds to.

index

The index of the current line being executed in the code_context list.

positions

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

バージョン 3.5 で変更: Return a named tuple instead of a tuple.

バージョン 3.11 で変更: FrameInfo is now a class instance (that is backwards compatible with the previous named tuple).

class inspect.Traceback

filename

The file name associated with the code being executed by the frame this traceback corresponds to.

lineno

The line number of the current line associated with the code being executed by the frame this traceback corresponds to.

function

The function name that is being executed by the frame this traceback corresponds to.

code_context

A list of lines of context from the source code that's being executed by the frame this traceback corresponds to.

index

The index of the current line being executed in the code_context list.

positions

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

バージョン 3.11 で変更: Traceback is now a class instance (that is backwards compatible with the previous named tuple).

注釈

フレームレコードの最初の要素などのフレームオブジェクトへの参照を保存すると、循環参照になってしまう場合があります。循環参照ができると、Python の循環参照検出機能を有効にしていたとしても関連するオブジェクトが参照しているすべてのオブジェクトが解放されにくくなり、明示的に参照を削除しないとメモリ消費量が増大する恐れがあります。

参照の削除を Python の循環参照検出機能にまかせることもできますが、 finally 節で循環参照を解除すれば確実にフレーム (とそのローカル変数) は削除されます。また、循環参照検出機能は Python のコンパイルオプションや gc.disable() で無効とされている場合がありますので注意が必要です。例:

def handle_stackframe_without_leak():
    frame = inspect.currentframe()
    try:
        # do something with the frame
    finally:
        del frame

If you want to keep the frame around (for example to print a traceback later), you can also break reference cycles by using the frame.clear() method.

以下の関数でオプション引数 context には、戻り値のソース行リストに何行分のソースを含めるかを指定します。ソース行リストには、実行中の行を中心として指定された行数分のリストを返します。

inspect.getframeinfo(frame, context=1)

Get information about a frame or traceback object. A Traceback object is returned.

バージョン 3.11 で変更: A Traceback object is returned instead of a named tuple.

inspect.getouterframes(frame, context=1)

指定したフレームと、その外側の全フレームの FrameInfo オブジェクトのリストを取得します。外側のフレームとは frame が生成されるまでのすべての関数呼び出しを示します。戻り値のリストの先頭は frame のフレームレコードで、末尾の要素は frame のスタックにある最も外側のフレームのフレームレコードとなります。

バージョン 3.5 で変更: 名前付きタプル FrameInfo(frame, filename, lineno, function, code_context, index) のリストが返されます。

バージョン 3.11 で変更: A list of FrameInfo objects is returned.

inspect.getinnerframes(traceback, context=1)

トレースバックのフレームと、その内側の全フレームの FrameInfo オブジェクトのリストを取得します。内のフレームとは frame から続く一連の関数呼び出しを示します。戻り値のリストの先頭は traceback のフレームレコードで、末尾の要素は例外が発生した位置を示します。

バージョン 3.5 で変更: 名前付きタプル FrameInfo(frame, filename, lineno, function, code_context, index) のリストが返されます。

バージョン 3.11 で変更: A list of FrameInfo objects is returned.

inspect.currentframe()

呼び出し元のフレームオブジェクトを返します。

CPython 実装の詳細: この関数はインタプリタの Python スタックフレームサポートに依存します。これは Python のすべての実装に存在している保証はありません。Python スタックフレームサポートのない環境では、この関数は None を返します。

inspect.stack(context=1)

呼び出し元スタックの FrameInfo オブジェクトのリストを返します。最初の要素は呼び出し元のフレームレコードで、末尾の要素はスタックにある最も外側のフレームのフレームレコードとなります。

バージョン 3.5 で変更: 名前付きタプル FrameInfo(frame, filename, lineno, function, code_context, index) のリストが返されます。

バージョン 3.11 で変更: A list of FrameInfo objects is returned.

inspect.trace(context=1)

実行中のフレームと処理中の例外が発生したフレームの間の FrameInfo オブジェクトのリストを返します。最初の要素は呼び出し元のフレームレコードで、末尾の要素は例外が発生した位置を示します。

バージョン 3.5 で変更: 名前付きタプル FrameInfo(frame, filename, lineno, function, code_context, index) のリストが返されます。

バージョン 3.11 で変更: A list of FrameInfo objects is returned.

属性の静的なフェッチ

Both getattr() and hasattr() can trigger code execution when fetching or checking for the existence of attributes. Descriptors, like properties, will be invoked and __getattr__() and __getattribute__() may be called.

For cases where you want passive introspection, like documentation tools, this can be inconvenient. getattr_static() has the same signature as getattr() but avoids executing code when it fetches attributes.

inspect.getattr_static(obj, attr, default=None)

Retrieve attributes without triggering dynamic lookup via the descriptor protocol, __getattr__() or __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 __dict__ is shadowed by another member (for example a property) then this function will be unable to find instance members.

Added in version 3.2.

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

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. getgeneratorstate() allows the current state of a generator to be determined easily.

inspect.getgeneratorstate(generator)

ジェネレータイテレータの現在の状態を取得します。

取り得る状態は:

GEN_CREATED: 実行開始を待機しています。

GEN_RUNNING: インタープリタによって現在実行されています。

GEN_SUSPENDED: yield 式で現在サスペンドされています。

GEN_CLOSED: 実行が完了しました。

Added in version 3.2.

inspect.getcoroutinestate(coroutine)

Get current state of a coroutine object. The function is intended to be used with coroutine objects created by async def functions, but will accept any coroutine-like object that has cr_running and cr_frame attributes.

取り得る状態は:

CORO_CREATED: 実行開始を待機しています。

CORO_RUNNING: インタープリタにより現在実行中です。

CORO_SUSPENDED: await 式により現在停止中です。

CORO_CLOSED: 実行が完了しました。

Added in version 3.5.

inspect.getasyncgenstate(agen)

Get current state of an asynchronous generator object. The function is intended to be used with asynchronous iterator objects created by async def functions which use the yield statement, but will accept any asynchronous generator-like object that has ag_running and ag_frame attributes.

取り得る状態は:

AGEN_CREATED: Waiting to start execution.

AGEN_RUNNING: Currently being executed by the interpreter.

AGEN_SUSPENDED: Currently suspended at a yield expression.

AGEN_CLOSED: Execution has completed.

Added in version 3.12.

ジェネレータの現在の内部状態を問い合わせることも出来ます。これは主に内部状態が期待通り更新されているかどうかを確認するためのテストの目的に有用です。

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 locals() in the body of the generator, and all the same caveats apply.

If generator is a generator with no currently associated frame, then an empty dictionary is returned. TypeError is raised if generator is not a Python generator object.

CPython 実装の詳細: This function relies on the generator exposing a Python stack frame for introspection, which isn't guaranteed to be the case in all implementations of Python. In such cases, this function will always return an empty dictionary.

Added in version 3.3.

inspect.getcoroutinelocals(coroutine)

This function is analogous to getgeneratorlocals(), but works for coroutine objects created by async def functions.

Added in version 3.5.

inspect.getasyncgenlocals(agen)

This function is analogous to getgeneratorlocals(), but works for asynchronous generator objects created by async def functions which use the yield statement.

Added in version 3.12.

Code Objects Bit Flags

Python code objects have a co_flags attribute, which is a bitmap of the following flags:

inspect.CO_OPTIMIZED

The code object is optimized, using fast locals.

inspect.CO_NEWLOCALS

If set, a new dict will be created for the frame's f_locals when the code object is executed.

inspect.CO_VARARGS

The code object has a variable positional parameter (*args-like).

inspect.CO_VARKEYWORDS

The code object has a variable keyword parameter (**kwargs-like).

inspect.CO_NESTED

The flag is set when the code object is a nested function.

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.

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 PEP 492 [https://peps.python.org/pep-0492/] for more details.

Added in version 3.5.

inspect.CO_ITERABLE_COROUTINE

The flag is used to transform generators into generator-based coroutines. Generator objects with this flag can be used in await expression, and can yield from coroutine objects. See PEP 492 [https://peps.python.org/pep-0492/] for more details.

Added in version 3.5.

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 PEP 525 [https://peps.python.org/pep-0525/] for more details.

Added in version 3.6.

注釈

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 inspect module for any introspection needs.

Buffer flags

class inspect.BufferFlags

This is an enum.IntFlag that represents the flags that can be passed to the __buffer__() method of objects implementing the buffer protocol.

The meaning of the flags is explained at バッファリクエストのタイプ.

SIMPLE

WRITABLE

FORMAT

ND

STRIDES

C_CONTIGUOUS

F_CONTIGUOUS

ANY_CONTIGUOUS

INDIRECT

CONTIG

CONTIG_RO

STRIDED

STRIDED_RO

RECORDS

RECORDS_RO

FULL

FULL_RO

READ

WRITE

Added in version 3.12.

コマンドラインインターフェイス

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

--details

Print information about the specified object rather than the source code

site --- Site-specific configuration hook

ソースコード: Lib/site.py [https://github.com/python/cpython/tree/3.12/Lib/site.py]

このモジュールは初期化中に自動的にインポートされます。 自動インポートはインタプリタの -S オプションで禁止できます。

Importing this module will append site-specific paths to the module search path and add a few builtins, unless -S was used. In that case, 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 main() function.

バージョン 3.3 で変更: 以前は -S を使っているときでも、モジュールをインポートするとパス変更が起動されていました。

site.main() 関数の処理は、前部と後部からなる最大で四つまでのディレクトリを構築するところから始まります。前部では sys.prefix と sys.exec_prefix を使用します; 空の前部は使われません。後部では、1つ目は空文字列を使い、2つ目は lib/site-packages (Windows) または lib/pythonX.Y/site-packages (Unix と macOS) を使います。前部-後部の異なる組み合わせごとに、それが存在しているディレクトリを参照しているかどうかを調べ、存在している場合は sys.path へ追加します。そして、新しく追加されたパスからパス設定ファイルを検索します。

バージョン 3.5 で変更: "site-python" ディレクトリのサポートは削除されました。

"pyvenv.cfg" という名前のファイルが上で挙げたディレクトリの 1 つに存在していた場合、 sys.executable, sys.prefix, sys.exec_prefix にはそのディレクトリが設定され、 site-packages もチェックします (sys.base_prefix と sys.base_exec_prefix は常にインストールされているPythonの "実際の" プレフィックスです)。 (ブートストラップの設定ファイルである) "pyvenv.cfg" で、キー "include-system-site-packages" に "true" (大文字小文字は区別しない) 以外が設定されている場合は、 site-packages を探しにシステムレベルのプレフィックスも見に行きません; そうでない場合は見に行きます。

パス設定ファイルは name.pth という形式の名前をもつファイルで、上の4つのディレクトリのひとつにあります。その内容は sys.path に追加される追加項目(一行に一つ)です。存在しない項目は sys.path へは決して追加されませんが、項目がファイルではなくディレクトリを参照しているかどうかはチェックされません。項目が sys.path へ二回以上追加されることはありません。空行と # で始まる行は読み飛ばされます。 import で始まる(そしてその後ろにスペースかタブが続く)行は実行されます。

注釈

.pth ファイル内の実行可能な行は、特定のモジュールが実際に使用されるかどうかに関係なく、Pythonの起動時に毎回実行されます。したがって、その影響は最小限に抑えられるべきです。実行可能な行の主な目的は、対応するモジュールをインポート可能にすることです(サードパーティ製インポートフックのロード、 PATH の調整など)。その他の初期化は、モジュールが実際にインポートされたときに行われます。コードのチャンクを1行に制限することは、より複雑なものをここに入れないようにするための意図的な手段です。

例えば、 sys.prefix と sys.exec_prefix が /usr/local に設定されていると仮定します。そのときPython X.Y ライブラリは /usr/local/lib/pythonX.Y にインストールされています。ここにはサブディレクトリ /usr/local/lib/pythonX.Y/site-packages があり、その中に三つのサブディレクトリ foo, bar および spam と二つのパス設定ファイル foo.pth と bar.pth をもつと仮定します。 foo.pth には以下のものが記載されていると想定してください:

# foo package configuration

foo
bar
bletch

また、 bar.pth には:

# bar package configuration

bar

が記載されているとします。そのとき、次のバージョンごとのディレクトリが sys.path へこの順番で追加されます:

/usr/local/lib/pythonX.Y/site-packages/bar
/usr/local/lib/pythonX.Y/site-packages/foo

bletch は存在しないため省略されるということに注意してください。 bar ディレクトリは foo ディレクトリの前に来ます。なぜなら、 bar.pth がアルファベット順で foo.pth の前に来るからです。また、 spam はどちらのパス設定ファイルにも記載されていないため、省略されます。

sitecustomize

After these path manipulations, an attempt is made to import a module named 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 ImportError or its subclass exception, and the exception's name attribute equals to 'sitecustomize', it is silently ignored. If Python is started without output streams available, as with pythonw.exe on Windows (which is used by default to start IDLE), attempted output from sitecustomize is ignored. Any other exception causes a silent and perhaps mysterious failure of the process.

usercustomize

After this, an attempt is made to import a module named usercustomize, which can perform arbitrary user-specific customizations, if ENABLE_USER_SITE is true. This file is intended to be created in the user site-packages directory (see below), which is part of sys.path unless disabled by -s. If this import fails with an ImportError or its subclass exception, and the exception's name attribute equals to 'usercustomize', it is silently ignored.

いくつかの非Unixシステムでは、 sys.prefix と sys.exec_prefix は空で、パス操作は省略されます。しかし、 sitecustomize と usercustomize のインポートはそのときでも試みられます。

readline の設定

readline をサポートするシステムではこのモジュールは、Python を 対話モード で -S オプションなしで開始した場合に rlcompleter モジュールをインポートして設定します。デフォルトの振る舞いでは、タブ補完を有効にし、履歴保存ファイルに ~/.python_history を使います。これを無効にするには、あなたの sitecustomize または usercustomize あるいは PYTHONSTARTUP ファイル内で sys.__interactivehook__ 属性を削除 (または上書き) してください。 (---訳注: site モジュールは __interactivehook__ に readline 設定関数を設定後に sitecustomize 等のユーザ設定を実行します。 __interactivehook__ のチェックが行われるのは site モジュール実行の後です。 ---)

バージョン 3.4 で変更: rlcompleter とhistory のアクティベーションが自動で行われるようになりました。

モジュールの内容

site.PREFIXES

siteパッケージディレクトリのprefixのリスト。

site.ENABLE_USER_SITE

ユーザサイトディレクトリのステータスを示すフラグ。 True の場合、ユーザサイトディレクトリが有効で sys.path に追加されていることを意味しています。 False の場合、ユーザによるリクエスト(オプション -s か PYTHONNOUSERSITE)によって、 None の場合セキュリティ上の理由(ユーザまたはグループIDと実効IDの間のミスマッチ)あるいは管理者によって、ユーザサイトディレクトリが無効になっていることを示しています。

site.USER_SITE

Python 実行時のユーザの site-packages へのパスです。 getusersitepackages() がまだ呼び出されていなければ None かもしれません。デフォルト値は UNIX と frameworkなしの macOS ビルドでは ~/.local/lib/pythonX.Y/site-packages 、macOS framework ビルドでは ~/Library/Python/X.Y/lib/python/site-packages、Windows では %APPDATA%\Python\PythonXY\site-packages です。このディレクトリは site ディレクトリなので、 ここにいる .pth ファイルが処理されます。

site.USER_BASE

Path to the base directory for the user site-packages. Can be None if getuserbase() hasn't been called yet. Default value is ~/.local for UNIX and macOS non-framework builds, ~/Library/Python/X.Y for macOS framework builds, and %APPDATA%\Python for Windows. This value is used to compute the installation directories for scripts, data files, Python modules, etc. for the user installation scheme. See also PYTHONUSERBASE.

site.main()

モジュール検索パスに標準のサイト固有ディレクトリを追加します。この関数は、Python インタプリタが -S で開始されていない限り、このモジュールインポート時に自動的に呼び出されます。

バージョン 3.3 で変更: この関数は以前は無条件に呼び出されていました。

site.addsitedir(sitedir, known_paths=None)

sys.path にディレクトリを追加し、その .pth ファイル群を処理します。典型的には sitecustomize か usercustomize 内で使われます(上述)。

site.getsitepackages()

全てのグローバルな site-packages ディレクトリのリストを返します。

Added in version 3.2.

site.getuserbase()

ユーザのベースディレクトリへのパス USER_BASE を返します。未初期化であればこの関数は PYTHONUSERBASE を参考にして、設定もします。

Added in version 3.2.

site.getusersitepackages()

ユーザ固有の site パッケージのディレクトリへのパス USER_SITE を返します。未初期化であればこの関数は USER_BASE を参考にして、設定もします。ユーザ固有の site パッケージが sys.path に追加されたかどうかを確認するには ENABLE_USER_SITE を使ってください。

Added in version 3.2.

コマンドラインインターフェイス

site モジュールはユーザディレクトリをコマンドラインから得る手段も提供しています:

$ python -m site --user-site
/home/user/.local/lib/python3.11/site-packages

引数なしで呼び出された場合、sys.path の中身を表示し、続けて USER_BASE とそのディレクトリが存在するかどうか、 USER_SITE とそのディレクトリが存在するかどうか、最後に ENABLE_USER_SITE の値を、標準出力に出力します。

--user-base

ユーザのベースディレクトリを表示します。

--user-site

ユーザの site-packages ディレクトリを表示します。

両方のオプションが指定された場合、ユーザのベースとユーザの site が(常にこの順序で) os.pathsep 区切りで表示されます。

いずれかのオプションが与えられた場合に、このスクリプトは次のいずれかの終了コードで終了します: ユーザの site-packages が有効ならば 0 、ユーザにより無効にされていれば 1 、セキュリティ的な理由あるいは管理者によって無効にされている場合 2 、そして何かエラーがあった場合は 2 より大きな値。

参考

PEP 370 [https://peps.python.org/pep-0370/] -- ユーザごとの site-packages ディレクトリ

The initialization of the sys.path module search path -- The initialization of sys.path.

カスタム Python インタプリタ

この章で解説されるモジュールで Python の対話インタプリタに似たインターフェースを書くことができます。もし Python そのもの以外に何か特殊な機能をサポートした Python インタプリタを作りたければ、 code モジュールを参照してください。 (codeop モジュールはより低レベルで、不完全(かもしれない) Python コード断片のコンパイルをサポートするために使われます。)

この章で解説されるモジュールの完全な一覧は:

code --- Interpreter base classes

対話的なインタプリタオブジェクト

対話的なコンソールオブジェクト

codeop --- Compile Python code

code --- Interpreter base classes

ソースコード: Lib/code.py [https://github.com/python/cpython/tree/3.12/Lib/code.py]

code モジュールはread-eval-print (読み込み-評価-表示)ループをPythonで実装するための機能を提供します。対話的なインタプリタプロンプトを提供するアプリケーションを作るために使える二つのクラスと便利な関数が含まれています。

class code.InteractiveInterpreter(locals=None)

このクラスは構文解析とインタプリタ状態(ユーザの名前空間)を取り扱います。入力バッファリングやプロンプト出力、または入力ファイル指定を扱いません(ファイル名は常に明示的に渡されます)。オプションの locals 引数はその中でコードが実行される辞書を指定します。その初期値は、キー '__name__' が '__console__' に設定され、キー '__doc__' が None に設定された新しく作られた辞書です。

class code.InteractiveConsole(locals=None, filename='<console>')

Closely emulate the behavior of the interactive Python interpreter. This class builds on InteractiveInterpreter and adds prompting using the familiar sys.ps1 and sys.ps2, and input buffering.

code.interact(banner=None, readfunc=None, local=None, exitmsg=None)

Convenience function to run a read-eval-print loop. This creates a new instance of InteractiveConsole and sets readfunc to be used as the InteractiveConsole.raw_input() method, if provided. If local is provided, it is passed to the InteractiveConsole constructor for use as the default namespace for the interpreter loop. The interact() method of the instance is then run with banner and exitmsg passed as the banner and exit message to use, if provided. The console object is discarded after use.

バージョン 3.6 で変更: exitmsg 引数が追加されました.

code.compile_command(source, filename='<input>', symbol='single')

この関数はPythonのインタプリタメインループ(別名、read-eval-printループ)をエミュレートしようとするプログラムにとって役に立ちます。扱いにくい部分は、ユーザが(完全なコマンドや構文エラーではなく)さらにテキストを入力すれば完全になりうる不完全なコマンドを入力したときを決定することです。この関数は ほとんど の場合に実際のインタプリタメインループと同じ決定を行います。

source はソース文字列です。filename はオプションのソースが読み出されたファイル名で、デフォルトで '<input>' です。symbol はオプションの文法の開始記号で、'single' (デフォルト)または 'eval' か 'exec' にすべきです。

コマンドが完全で有効ならば、コードオブジェクトを返します(compile(source, filename, symbol) と同じ)。コマンドが完全でないならば、 None を返します。コマンドが完全で構文エラーを含む場合は、 SyntaxError を発生させます。または、コマンドが無効なリテラルを含む場合は、 OverflowError もしくは ValueError を発生させます。

対話的なインタプリタオブジェクト

InteractiveInterpreter.runsource(source, filename='<input>', symbol='single')

インタプリタ内のあるソースをコンパイルし実行します。引数は compile_command() のものと同じです。 filename のデフォルトは '<input>' で、 symbol は 'single' です。あるいくつかのことが起きる可能性があります:

入力が不正。 compile_command() が例外(SyntaxError か OverflowError)を起こした場合。 showsyntaxerror() メソッドの呼び出によって、構文トレースバックが表示されるでしょう。 runsource() は False を返します。

入力が完全でなく、さらに入力が必要。 compile_command() が None を返した場合。 runsource() は True を返します。

入力が完全。 compile_command() がコードオブジェクトを返した場合。 (SystemExit を除く実行時例外も処理する) runcode() を呼び出すことによって、コードは実行されます。 runsource() は False を返します。

戻り値は、次の行のプロンプトに sys.ps1 か sys.ps2 のどちらを使うのか判断するために使えます。

InteractiveInterpreter.runcode(code)

コードオブジェクトを実行します。例外が生じたときは、トレースバックを表示するために showtraceback() が呼び出されます。伝搬することが許されている SystemExit を除くすべての例外が捉えられます。

KeyboardInterrupt についての注意。このコードの他の場所でこの例外が生じる可能性がありますし、常に捕らえることができるとは限りません。呼び出し側はそれを処理するために準備しておくべきです。

InteractiveInterpreter.showsyntaxerror(filename=None)

起きたばかりの構文エラーを表示します。複数の構文エラーに対して一つあるのではないため、これはスタックトレースを表示しません。 filename が与えられた場合は、Pythonのパーサが与えるデフォルトのファイル名の代わりに例外の中へ入れられます。なぜなら、文字列から読み込んでいるときはパーサは常に '<string>' を使うからです。出力は write() メソッドによって書き込まれます。

InteractiveInterpreter.showtraceback()

起きたばかりの例外を表示します。スタックの最初の項目を取り除きます。なぜなら、それはインタプリタオブジェクトの実装の内部にあるからです。出力は write() メソッドによって書き込まれます。

バージョン 3.5 で変更: 最初のトレースバックではなく、完全なトレースバックの連鎖が表示されます。

InteractiveInterpreter.write(data)

文字列を標準エラーストリーム(sys.stderr)へ書き込みます。必要に応じて適切な出力処理を提供するために、派生クラスはこれをオーバーライドすべきです。

対話的なコンソールオブジェクト

InteractiveConsole クラスは InteractiveInterpreter のサブクラスです。以下の追加メソッドだけでなく、インタプリタオブジェクトのすべてのメソッドも提供します。

InteractiveConsole.interact(banner=None, exitmsg=None)

対話的な Python コンソールをそっくりにエミュレートします。オプションの banner 引数は最初のやりとりの前に表示するバナーを指定します。デフォルトでは、標準 Python インタプリタが表示するものと同じようなバナーを表示します。それに続けて、実際のインタプリタと混乱しないように (とても似ているから!) 括弧の中にコンソールオブジェクトのクラス名を表示します。

オプション引数の exitmsg は、終了時に出力される終了メッセージを指定します。空文字列を渡すと、出力メッセージを抑止します。もし、 exitmsg が与えられないか、None の場合は、デフォルトのメッセージが出力されます。

バージョン 3.4 で変更: バナーの表示を抑制するには、空の文字列を渡してください。

バージョン 3.6 で変更: 終了時に、終了メッセージを表示します。

InteractiveConsole.push(line)

Push a line of source text to the interpreter. The line should not have a trailing newline; it may have internal newlines. The line is appended to a buffer and the interpreter's runsource() method is called with the concatenated contents of the buffer as source. If this indicates that the command was executed or invalid, the buffer is reset; otherwise, the command is incomplete, and the buffer is left as it was after the line was appended. The return value is True if more input is required, False if the line was dealt with in some way (this is the same as runsource()).

InteractiveConsole.resetbuffer()

入力バッファから処理されていないソーステキストを取り除きます。

InteractiveConsole.raw_input(prompt='')

プロンプトを書き込み、一行を読み込みます。返る行は末尾に改行を含みません。ユーザがEOFキーシーケンスを入力したときは、 EOFError を発生させます。基本実装では、 sys.stdin から読み込みます。サブクラスはこれを異なる実装と置き換えるかもしれません。

codeop --- Compile Python code

ソースコード: Lib/codeop.py [https://github.com/python/cpython/tree/3.12/Lib/codeop.py]

codeop モジュールは、 code モジュールで行われているようなPythonの read-eval-printループをエミュレートするユーティリティを提供します。そのため、このモジュールを直接利用する場面はあまり無いでしょう。プログラムにこのようなループを含めたい場合は、 code モジュールの方が便利です。

この仕事には二つの部分があります:

入力の一行がPythonの文として完全であるかどうかを見分けられること: 簡単に言えば、次が '>>>' か、あるいは '...' かどうかを見分けます。

どのfuture文をユーザが入力したのかを覚えていること。したがって、実質的にそれに続く入力をこれらとともにコンパイルすることができます。

codeop モジュールはこうしたことのそれぞれを行う方法とそれら両方を行う方法を提供します。

前者は実行するには:

codeop.compile_command(source, filename='<input>', symbol='single')

Pythonコードの文字列であるべき source をコンパイルしてみて、source が有効なPythonコードの場合はコードオブジェクトを返します。このような場合、コードオブジェクトのファイル名属性は、デフォルトで '<input>' である filename でしょう。source が有効なPythonコードでは ない が、有効なPythonコードの接頭語である場合には、None を返します。

source に問題がある場合は、例外を発生させます。無効なPython構文がある場合は、 SyntaxError を発生させます。また、無効なリテラルがある場合は、 OverflowError または ValueError を発生させます。

symbol 引数は source が文としてコンパイルされるか('single' 、デフォルト) 、文 のシーケンスとしてか ('exec') 、または 式 としてコンパイルされるかを決定します('eval')。他のどんな値も ValueError を送出させます。

注釈

ソースの終わりに達する前に、成功した結果をもってパーサは構文解析を止めることがあります。このような場合、後ろに続く記号はエラーとならずに無視されます。例えば、バックスラッシュの後ろに改行が2つあって、その後ろにゴミがあるかもしれません。パーサのAPIがより良くなればすぐに、この挙動は修正されるでしょう。

class codeop.Compile

Instances of this class have __call__() methods identical in signature to the built-in function compile(), but with the difference that if the instance compiles program text containing a __future__ statement, the instance 'remembers' and compiles all subsequent program texts with the statement in force.

class codeop.CommandCompiler

Instances of this class have __call__() methods identical in signature to compile_command(); the difference is that if the instance compiles program text containing a __future__ statement, the instance 'remembers' and compiles all subsequent program texts with the statement in force.

モジュールのインポート

この章で解説されるモジュールは他のPythonモジュールをインポートする新しい方法と、インポート処理をカスタマイズするためのフックを提供します。

この章で解説されるモジュールの完全な一覧は:

zipimport --- Import modules from Zip archives

zipimporter オブジェクト

使用例

pkgutil --- Package extension utility

modulefinder --- Find modules used by a script

ModuleFinder の使用例

runpy --- Locating and executing Python modules

importlib --- import の実装

はじめに

関数

importlib.abc -- インポートに関連する抽象基底クラス

importlib.machinery -- インポータおよびパスフック

importlib.util -- インポータのためのユーティリティコード

使用例

プログラムからのインポート

モジュールがインポートできるか確認する

ソースファイルから直接インポートする

Implementing lazy imports

インポーターのセットアップ

Approximating importlib.import_module()

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

Deprecated functions

importlib.resources.abc -- Abstract base classes for resources

importlib.metadata -- Accessing package metadata

概要

機能 API

エントリポイント

配布物メタデータ

配布物バージョン

配布物ファイル

配布物の要件

Mapping import to distribution packages

Distributions

Distribution Discovery

検索アルゴリズムの拡張

The initialization of the sys.path module search path

仮想環境 (Virtual environments)

_pth files

Embedded Python

zipimport --- Import modules from Zip archives

ソースコード: Lib/zipimport.py [https://github.com/python/cpython/tree/3.12/Lib/zipimport.py]

このモジュールは、 Python モジュール (*.py, *.pyc) やパッケージを ZIP 形式のアーカイブから import できるようにします。通常、 zipimport を明示的に使う必要はありません; 組み込みの import は、 sys.path の要素が ZIP アーカイブへのパスを指している場合にこのモジュールを自動的に使います。

普通、 sys.path はディレクトリ名の文字列からなるリストです。このモジュールを使うと、 sys.path の要素に ZIP ファイルアーカイブを示す文字列を使えるようになります。ZIP アーカイブにはサブディレクトリ構造を含めることができ、パッケージの import をサポートさせたり、アーカイブ内のパスを指定してサブディレクトリ下から import を行わせたりできます。例えば、 example.zip/lib/ のように指定すると、アーカイブ中の lib/ サブディレクトリ下だけから import を行います。

ZIP アーカイブ内にはどんなファイルを置いてもかまいませんが、インポートは .py および .pyc ファイルにのみ呼び出されます。動的モジュール (.pyd, .so) の ZIP インポートは行えません。アーカイブ内に .py ファイルしかない場合、 Python は対応する .pyc ファイルを追加してアーカイブを変更しようとはしません。つまり、 ZIP アーカイブ内に .pyc がない場合は、インポートが多少遅くなるかもしれないので注意してください。

バージョン 3.8 で変更: 以前は、アーカイブコメント付きの ZIP アーカイブはサポートされていませんでした。

参考

PKZIP Application Note [https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT]

ZIP ファイルフォーマットおよびアルゴリズムを作成した Phil Katz によるドキュメント。

PEP 273 [https://peps.python.org/pep-0273/] - Zip アーカイブからモジュールをインポートする

このモジュールの実装も行った、James C. Ahlstrom による PEP です。Python 2.3 は PEP 273 [https://peps.python.org/pep-0273/] の仕様に従っていますが、Just van Rossum の書いた import フックによる実装を使っています。インポートフックは PEP 302 [https://peps.python.org/pep-0302/] で解説されています。

importlib - import の実装

Package providing the relevant protocols for all importers to implement.

このモジュールでは例外を一つ定義しています:

exception zipimport.ZipImportError

zipimporter オブジェクトが送出する例外です。 ImportError のサブクラスなので、 ImportError としても捕捉できます。

zipimporter オブジェクト

zipimporter は ZIP ファイルを import するためのクラスです。

class zipimport.zipimporter(archivepath)

新たな zipimporter インスタンスを生成します。 archivepath は ZIP ファイルへのパスまたは ZIP ファイル中の特定のパスへのパスでなければなりません。たとえば、 foo/bar.zip/lib という archivepath の場合、 foo/bar.zip という ZIP ファイルの中の lib ディレクトリにあるモジュールを (存在するものとして) 検索します。

archivepath が有効な ZIP アーカイブを指していない場合、 ZipImportError を送出します。

バージョン 3.12 で変更: Methods find_loader() and find_module(), deprecated in 3.10 are now removed. Use find_spec() instead.

create_module(spec)

Implementation of importlib.abc.Loader.create_module() that returns None to explicitly request the default semantics.

Added in version 3.10.

exec_module(module)

importlib.abc.Loader.exec_module() の実装です。

Added in version 3.10.

find_spec(fullname, target=None)

importlib.abc.PathEntryFinder.find_spec() の実装です。

Added in version 3.10.

get_code(fullname)

fullname に指定したモジュールのコードオブジェクトを返します。モジュールがインポートできなかった場合には ZipImportError を送出します。

get_data(pathname)

pathname に関連付けられたデータを返します。該当するファイルが見つからなかった場合には OSError を送出します。

バージョン 3.3 で変更: 以前は IOError が送出されました; それは現在 OSError のエイリアスです。

get_filename(fullname)

指定されたモジュールが import された場合、そのモジュールに設定した __file__ の値を返します。モジュールがインポートできなかった場合、 ZipImportError を送出します。

Added in version 3.1.

get_source(fullname)

fullname で指定されたモジュールのソースコードを返します。モジュールが見つからない場合、ZipImportError を送出します。アーカイブにはモジュールがあるもののソースコードがない場合、 None を返します。

is_package(fullname)

fullname で指定されたモジュールがパッケージの場合 True を返します。モジュールを見つけられない場合 ZipImportError を送出します。

load_module(fullname)

Load the module specified by fullname. fullname must be the fully qualified (dotted) module name. Returns the imported module on success, raises ZipImportError on failure.

バージョン 3.10 で非推奨: 代わりに exec_module() を使用してください。

invalidate_caches()

Clear out the internal cache of information about files found within the ZIP archive.

Added in version 3.10.

archive

importer に関連付けられた ZIP ファイルのファイル名です。サブパスは含まれません。

prefix

モジュールを検索する ZIP ファイル中のサブパスです。この文字列は ZIP ファイルのルートを指している zipimporter オブジェクトでは空です。

スラッシュでつなげると、archive と prefix 属性は zipimporter コンストラクタに渡された元々の archivepath 引数と等しくなります。

使用例

モジュールを ZIP アーカイブから import する例を以下に示します - zipimport モジュールが明示的に使われていないことに注意してください。

$ unzip -l example.zip
Archive:  example.zip
  Length     Date   Time    Name
 --------    ----   ----    ----
     8467  11-26-02 22:30   jwzthreading.py
 --------                   -------
     8467                   1 file
$ ./python
Python 2.3 (#1, Aug 1 2003, 19:54:32)
>>> import sys
>>> sys.path.insert(0, 'example.zip')  # Add .zip file to front of path
>>> import jwzthreading
>>> jwzthreading.__file__
'example.zip/jwzthreading.py'

pkgutil --- Package extension utility

ソースコード: Lib/pkgutil.py [https://github.com/python/cpython/tree/3.12/Lib/pkgutil.py]

このモジュールはインポートシステムの、特にパッケージサポートに関するユーティリティです。

class pkgutil.ModuleInfo(module_finder, name, ispkg)

モジュールの概要情報を格納する namedtuple

Added in version 3.6.

pkgutil.extend_path(path, name)

パッケージを構成するモジュールの検索パスを拡張します。パッケージの __init__.py で次のように書くことを意図したものです:

from pkgutil import extend_path
__path__ = extend_path(__path__, __name__)

For each directory on sys.path that has a subdirectory that matches the package name, add the subdirectory to the package's __path__. This is useful if one wants to distribute different parts of a single logical package as multiple directories.

同時に *.pkg の * の部分が name 引数に指定された文字列に一致するファイルの検索もおこないます。この機能は import で始まる特別な行がないことを除き *.pth ファイルに似ています (site の項を参照)。 *.pkg は重複のチェックを除き、信頼できるものとして扱われます。 *.pkg ファイルの中に見つかったエントリはファイルシステム上に実在するか否かを問わず、そのまますべてパスに追加されます。(このような仕様です。)

入力パスがリストでない場合(フリーズされたパッケージのとき)は何もせずにリターンします。入力パスが変更されていなければ、アイテムを末尾に追加しただけのコピーを返します。

sys.path はシーケンスであることが前提になっています。 sys.path の要素の内、実在するディレクトリを指す文字列となっていないものは無視されます。ファイル名として使ったときにエラーが発生する sys.path の Unicode要素がある場合、この関数(os.path.isdir() を実行している行) で例外が発生する可能性があります。

pkgutil.find_loader(fullname)

fullname に対するモジュール loader オブジェクトを取得します。

これは後方互換性のために提供している importlib.util.find_spec() へのラッパーで、そこでのほどんどの失敗を ImportError に変換し、完全な importlib.machinery.ModuleSpec を返す代わりにローダのみを返しています。

バージョン 3.3 で変更: パッケージ内部の PEP 302 [https://peps.python.org/pep-0302/] エミュレーションに依存するのではなく直接的に importlib に基くように更新されました。

バージョン 3.4 で変更: PEP 451 [https://peps.python.org/pep-0451/] ベースに更新されました。

バージョン 3.12 で非推奨、バージョン 3.14 で削除予定: 代わりに importlib.util.find_spec() を使用してください。

pkgutil.get_importer(path_item)

指定された path_item に対する finder を取得します。

path hook により新しい finder が作成された場合は、それは sys.path_importer_cache にキャッシュされます。

キャッシュ (やその一部) は、 sys.path_hooks のリスキャンが必要になった場合は手動でクリアすることができます。

バージョン 3.3 で変更: パッケージ内部の PEP 302 [https://peps.python.org/pep-0302/] エミュレーションに依存するのではなく直接的に importlib に基くように更新されました。

pkgutil.get_loader(module_or_name)

module_or_name に対する loader オブジェクトを取得します。

module か package が通常の import 機構によってアクセスできる場合、その機構の該当部分に対するラッパーを返します。モジュールが見つからなかったり import できない場合は None を返します。その名前のモジュールがまだ import されていない場合、そのモジュールを含むパッケージが(あれば)そのパッケージの __path__ を確立するために import されます。

バージョン 3.3 で変更: パッケージ内部の PEP 302 [https://peps.python.org/pep-0302/] エミュレーションに依存するのではなく直接的に importlib に基くように更新されました。

バージョン 3.4 で変更: PEP 451 [https://peps.python.org/pep-0451/] ベースに更新されました。

バージョン 3.12 で非推奨、バージョン 3.14 で削除予定: 代わりに importlib.util.find_spec() を使用してください。

pkgutil.iter_importers(fullname='')

Yield finder objects for the given module name.

If fullname contains a '.', the finders will be for the package containing fullname, otherwise they will be all registered top level finders (i.e. those on both sys.meta_path and sys.path_hooks).

その名前のついたモジュールがパッケージ内に含まれている場合、この関数を実行した副作用としてそのパッケージが import されます。

モジュール名が指定されない場合は全てのトップレベルの finder が生成されます。

バージョン 3.3 で変更: パッケージ内部の PEP 302 [https://peps.python.org/pep-0302/] エミュレーションに依存するのではなく直接的に importlib に基くように更新されました。

pkgutil.iter_modules(path=None, prefix='')

path を指定すればそのすべてのサブモジュールに対して、 path が None なら sys.path のすべてのトップレベルモジュールに対して、ModuleInfo を yield します。

path は None か、モジュールを検索する path のリストのどちらかでなければなりません。

prefix は出力の全てのモジュール名の頭に出力する文字列です。

注釈

これは iter_modules() メソッドを定義している finder に対してのみ動作します。このインターフェイスは非標準なので、モジュールは importlib.machinery.FileFinder と zipimport.zipimporter の実装も提供します。

バージョン 3.3 で変更: パッケージ内部の PEP 302 [https://peps.python.org/pep-0302/] エミュレーションに依存するのではなく直接的に importlib に基くように更新されました。

pkgutil.walk_packages(path=None, prefix='', onerror=None)

path を指定すれば再帰的にその中のモジュールすべてに対して、 path が None ならばアクセスできるすべてのモジュールに対して、ModuleInfo を yield します。

path は None か、モジュールを検索する path のリストのどちらかでなければなりません。

prefix は出力の全てのモジュール名の頭に出力する文字列です。

この関数は与えられた path 上の全ての パッケージ (全てのモジュール ではない) を、サブモジュールを検索するのに必要な __path__ 属性にアクセスするために import します。

onerror は、パッケージを import しようとしたときに何かの例外が発生した場合に、 1つの引数 (import しようとしていたパッケージの名前) で呼び出される関数です。 onerror 関数が提供されない場合、 ImportError は補足され無視されます。それ以外の全ての例外は伝播し、検索を停止させます。

例:

# list all modules python can access
walk_packages()

# list all submodules of ctypes
walk_packages(ctypes.__path__, ctypes.__name__ + '.')

注釈

これは iter_modules() メソッドを定義している finder に対してのみ動作します。このインターフェイスは非標準なので、モジュールは importlib.machinery.FileFinder と zipimport.zipimporter の実装も提供します。

バージョン 3.3 で変更: パッケージ内部の PEP 302 [https://peps.python.org/pep-0302/] エミュレーションに依存するのではなく直接的に importlib に基くように更新されました。

pkgutil.get_data(package, resource)

パッケージからリソースを取得します。

この関数は loader get_data API のラッパーです。 package 引数は標準的なモジュール形式 (foo.bar) のパッケージ名でなければなりません。 resource 引数は / をパス区切りに使った相対ファイル名の形式です。親ディレクトリを .. としたり、ルートからの (/ で始まる) 名前を使うことはできません。

この関数が返すのは指定されたリソースの内容であるバイナリ文字列です。

ファイルシステム中に位置するパッケージで既にインポートされているものに対しては、次と大体同じです:

d = os.path.dirname(sys.modules[package].__file__)
data = open(os.path.join(d, resource), 'rb').read()

If the package cannot be located or loaded, or it uses a loader which does not support get_data, then None is returned. In particular, the loader for namespace packages does not support get_data.

pkgutil.resolve_name(name)

Resolve a name to an object.

This functionality is used in numerous places in the standard library (see bpo-12915 [https://bugs.python.org/issue?@action=redirect&bpo=12915]) - and equivalent functionality is also in widely used third-party packages such as setuptools, Django and Pyramid.

It is expected that name will be a string in one of the following formats, where W is shorthand for a valid Python identifier and dot stands for a literal period in these pseudo-regexes:

W(.W)*

W(.W)*:(W(.W)*)?

The first form is intended for backward compatibility only. It assumes that some part of the dotted name is a package, and the rest is an object somewhere within that package, possibly nested inside other objects. Because the place where the package stops and the object hierarchy starts can't be inferred by inspection, repeated attempts to import must be done with this form.

In the second form, the caller makes the division point clear through the provision of a single colon: the dotted name to the left of the colon is a package to be imported, and the dotted name to the right is the object hierarchy within that package. Only one import is needed in this form. If it ends with the colon, then a module object is returned.

The function will return an object (which might be a module), or raise one of the following exceptions:

ValueError -- if name isn't in a recognised format.

ImportError -- if an import failed when it shouldn't have.

AttributeError -- If a failure occurred when traversing the object hierarchy within the imported package to get to the desired object.

Added in version 3.9.

modulefinder --- Find modules used by a script

ソースコード: Lib/modulefinder.py [https://github.com/python/cpython/tree/3.12/Lib/modulefinder.py]

このモジュールでは、スクリプト中で import されているモジュールセットを調べるために使える ModuleFinder クラスを提供しています。 modulefinder.py はまた、Python スクリプトのファイル名を引数に指定してスクリプトとして実行し、 import されているモジュールのレポートを出力させることもできます。

modulefinder.AddPackagePath(pkg_name, path)

pkg_name という名前のパッケージの在り処が path であることを記録します。

modulefinder.ReplacePackage(oldname, newname)

実際にはパッケージ内で oldname という名前になっているモジュールを newname という名前で指定できるようにします。

class modulefinder.ModuleFinder(path=None, debug=0, excludes=[], replace_paths=[])

このクラスでは run_script() および report() メソッドを提供しています。これらのメソッドは何らかのスクリプト中で import されているモジュールの集合を調べます。 path はモジュールを検索する先のディレクトリ名からなるリストです。 path を指定しない場合、 sys.path を使います。 debug にはデバッグレベルを設定します; 値を大きくすると、実行している内容を表すデバッグメッセージを出力します。 excludes は検索から除外するモジュール名です。 replace_paths には、モジュールパス内で置き換えられるパスをタプル (oldpath, newpath) からなるリストで指定します。

report()

スクリプトで import しているモジュールと、そのパスからなるリストを列挙したレポートを標準出力に出力します。モジュールを見つけられなかったり、モジュールがないように見える場合にも報告します。

run_script(pathname)

pathname に指定したファイルの内容を解析します。ファイルには Python コードが入っていなければなりません。

modules

モジュール名をモジュールに結びつける辞書。 ModuleFinder の使用例 を参照して下さい。

ModuleFinder の使用例

解析対象のスクリプトはこれ (bacon.py) です:

import re, itertools

try:
    import baconhameggs
except ImportError:
    pass

try:
    import guido.python.ham
except ImportError:
    pass

bacon.py のレポートを出力するスクリプトです:

from modulefinder import ModuleFinder

finder = ModuleFinder()
finder.run_script('bacon.py')

print('Loaded modules:')
for name, mod in finder.modules.items():
    print('%s: ' % name, end='')
    print(','.join(list(mod.globalnames.keys())[:3]))

print('-'*50)
print('Modules not imported:')
print('\n'.join(finder.badmodules.keys()))

出力例です (アーキテクチャに依って違ってくるかもしれません):

Loaded modules:
_types:
copyreg:  _inverted_registry,_slotnames,__all__
re._compiler:  isstring,_sre,_optimize_unicode
_sre:
re._constants:  REPEAT_ONE,makedict,AT_END_LINE
sys:
re:  __module__,finditer,_expand
itertools:
__main__:  re,itertools,baconhameggs
re._parser:  _PATTERNENDERS,SRE_FLAG_UNICODE
array:
types:  __module__,IntType,TypeType
---------------------------------------------------
Modules not imported:
guido.python.ham
baconhameggs

runpy --- Locating and executing Python modules

ソースコード: Lib/runpy.py [https://github.com/python/cpython/tree/3.12/Lib/runpy.py]

runpy モジュールは Python のモジュールをインポートせずにその位置を特定したり実行したりするのに使われます。その主な目的はファイルシステムではなく Python のモジュール名前空間を使って位置を特定したスクリプトの実行を可能にする -m コマンドラインスイッチを実装することです。

これはサンドボックスモジュール ではない ことに注意してください。すべてのコードは現在のプロセスで実行され、あらゆる副作用 (たとえば他のモジュールのキャッシュされたインポート等) は関数から戻った後にそのまま残ります。

さらに、 runpy 関数から戻った後で、実行されたコードによって定義された任意の関数およびクラスが正常に動作することは保証されません。この制限が受け入れられないユースケースでは、 importlib がこのモジュールより適切な選択となるでしょう。

runpy モジュールは2つの関数を提供しています:

runpy.run_module(mod_name, init_globals=None, run_name=None, alter_sys=False)

Execute the code of the specified module and return the resulting module globals dictionary. The module's code is first located using the standard import mechanism (refer to PEP 302 [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 __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. The supplied dictionary will not be modified. If any of the special global variables below are defined in the supplied dictionary, those definitions are overridden by run_module().

The special global variables __name__, __spec__, __file__, __cached__, __loader__ and __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).

__name__ は、オプション引数 run_name が None でない場合、指定されたモジュールがパッケージであれば mod_name + '.__main__' に、そうでなければ mod_name 引数の値がセットされます。

__spec__ will be set appropriately for the actually imported module (that is, __spec__.name will always be mod_name or mod_name + '.__main__, never run_name).

__file__, __cached__, __loader__ and __package__ are set as normal based on the module spec.

引数 alter_sys が与えられて True に評価されるならば、 sys.argv[0] は __file__ の値で更新され sys.modules[__name__] は実行されるモジュールの一時的モジュールオブジェクトで更新されます。 sys.argv[0] と sys.modules[__name__] はどちらも関数が処理を戻す前にもとの値に復旧します。

Note that this manipulation of 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 sys module be left alone when invoking this function from threaded code.

参考

コマンドラインから、 -m オプションを与えることで同じ機能を実現出来ます。

バージョン 3.1 で変更: Added ability to execute packages by looking for a __main__ submodule.

バージョン 3.2 で変更: __cached__ グローバル変数が追加されました (PEP 3147 [https://peps.python.org/pep-3147/] を参照)。

バージョン 3.4 で変更: Updated to take advantage of the module spec feature added by PEP 451 [https://peps.python.org/pep-0451/]. This allows __cached__ to be set correctly for modules run this way, as well as ensuring the real module name is always accessible as __spec__.name.

バージョン 3.12 で変更: The setting of __cached__, __loader__, and __package__ are deprecated. See ModuleSpec for alternatives.

runpy.run_path(path_name, init_globals=None, run_name=None)

Execute the code at the named filesystem location and return the resulting module globals dictionary. As with a script name supplied to the CPython command line, the supplied path may refer to a Python source file, a compiled bytecode file or a valid sys.path entry containing a __main__ module (e.g. a zipfile containing a top-level __main__.py file).

For a simple script, the specified code is simply executed in a fresh module namespace. For a valid sys.path entry (typically a zipfile or directory), the entry is first added to the beginning of sys.path. The function then looks for and executes a __main__ module using the updated path. Note that there is no special protection against invoking an existing __main__ entry located elsewhere on 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. The supplied dictionary will not be modified. If any of the special global variables below are defined in the supplied dictionary, those definitions are overridden by run_path().

The special global variables __name__, __spec__, __file__, __cached__, __loader__ and __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).

__name__ は、オプション引数 run_name が None でない場合、 run_name に設定され、それ以外の場合は '<run_path>' に設定されます。

If the supplied path directly references a script file (whether as source or as precompiled byte code), then __file__ will be set to the supplied path, and __spec__, __cached__, __loader__ and __package__ will all be set to None.

If the supplied path is a reference to a valid sys.path entry, then __spec__ will be set appropriately for the imported __main__ module (that is, __spec__.name will always be __main__). __file__, __cached__, __loader__ and __package__ will be set as normal based on the module spec.

A number of alterations are also made to the sys module. Firstly, sys.path may be altered as described above. sys.argv[0] is updated with the value of path_name and sys.modules[__name__] is updated with a temporary module object for the module being executed. All modifications to items in sys are reverted before the function returns.

Note that, unlike run_module(), the alterations made to sys are not optional in this function as these adjustments are essential to allowing the execution of 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.

参考

コマンドラインから インターフェイスオプション で同じ機能を使えます (python path/to/script)。

Added in version 3.2.

バージョン 3.4 で変更: Updated to take advantage of the module spec feature added by PEP 451 [https://peps.python.org/pep-0451/]. This allows __cached__ to be set correctly in the case where __main__ is imported from a valid sys.path entry rather than being executed directly.

バージョン 3.12 で変更: The setting of __cached__, __loader__, and __package__ are deprecated.

参考

PEP 338 [https://peps.python.org/pep-0338/] - モジュールをスクリプトとして実行する

PEP written and implemented by Nick Coghlan.

PEP 366 [https://peps.python.org/pep-0366/] - main モジュールの明示的な相対インポート

PEP written and implemented by Nick Coghlan.

PEP 451 [https://peps.python.org/pep-0451/] -- インポートシステムのための ModuleSpec 型

PEP written and implemented by Eric Snow

コマンドラインと環境 - CPython コマンドライン詳細

importlib.import_module() 関数

importlib --- import の実装

Added in version 3.1.

ソースコード: Lib/importlib/__init__.py [https://github.com/python/cpython/tree/3.12/Lib/importlib/__init__.py]

はじめに

importlib パッケージの目的は3つあります。

1つ目は Python ソースコード中にある import 文の(そして、拡張として、 __import__() 関数の)実装を提供することです。このパッケージは import 文の、どの Python インタープリターでも動作する実装を提供します。また、 Python 以外の言語で実装されたどの実装よりも把握しやすい実装を提供します。

2つ目の目的は、このパッケージが公開している import を実装するための要素を利用して、(インポーター として知られる) インポートプロセスで動作するカスタムのオブジェクトを実装しやすくすることです。

Three, the package contains modules exposing additional functionality for managing aspects of Python packages:

importlib.metadata presents access to metadata from third-party distributions.

importlib.resources provides routines for accessing non-code "resources" from Python packages.

参考

import 文

import 文の言語リファレンス。

Packages specification [https://www.python.org/doc/essays/packages/]

パッケージの元の仕様。幾つかの動作はこの仕様が書かれた頃から変更されています (例: sys.modules で None に基づくリダイレクト)。

__import__() 関数

import 文はこの関数のシンタックスシュガーです。

The initialization of the sys.path module search path

The initialization of sys.path.

PEP 235 [https://peps.python.org/pep-0235/]

大文字小文字を区別しないプラットフォームでのインポート

PEP 263 [https://peps.python.org/pep-0263/]

Python のソースコードのエンコーディング

PEP 302 [https://peps.python.org/pep-0302/]

新しいインポートフック

PEP 328 [https://peps.python.org/pep-0328/]

複数行のインポートと、絶対/相対インポート

PEP 366 [https://peps.python.org/pep-0366/]

main モジュールの明示的な相対インポート

PEP 420 [https://peps.python.org/pep-0420/]

暗黙的な名前空間パッケージ

PEP 451 [https://peps.python.org/pep-0451/]

インポートシステムのための ModuleSpec 型

PEP 488 [https://peps.python.org/pep-0488/]

PYO ファイルの撤廃

PEP 489 [https://peps.python.org/pep-0489/]

複数フェーズでの拡張モジュールの初期化

PEP 552 [https://peps.python.org/pep-0552/]

決定論的 pyc

PEP 3120 [https://peps.python.org/pep-3120/]

デフォルトのソースエンコーディングとして UTF-8 を使用

PEP 3147 [https://peps.python.org/pep-3147/]

PYC リポジトリディレクトリ

関数

importlib.__import__(name, globals=None, locals=None, fromlist=(), level=0)

組み込みの __import__() 関数の実装です。

注釈

プログラムからモジュールをインポートする場合はこの関数の代わりに import_module() を使ってください。

importlib.import_module(name, package=None)

モジュールをインポートします。name 引数は、インポートするモジュールを絶対または相対表現 (例えば pkg.mod または ..mod) で指定します。name が相対表現で与えられたら、package 引数を、パッケージ名を解決するためのアンカーとなるパッケージの名前に設定する必要があります (例えば import_module('..mod', 'pkg.subpkg') は pkg.mod をインポートします)。

import_module() 関数は importlib.__import__() を単純化するラッパーとして働きます。つまり、この関数のすべての意味は importlib.__import__() から受け継いでいます。これらの2つの関数の最も重要な違いは、 import_module() が指定されたパッケージやモジュール (例えば pkg.mod) を返すのに対し、 __import__() はトップレベルのパッケージやモジュール (例えば pkg) を返すことです。

もしモジュールを動的にインポートしていて、インタープリタの実行開始後にモジュールが作成された (例えば、 Python ソースファイルを作成した) 場合、インポートシステムが新しいモジュールを見つけられるように、 invalidate_caches() を呼ぶ必要があるでしょう。

バージョン 3.3 で変更: 親パッケージは自動的にインポートされます。

importlib.invalidate_caches()

sys.meta_path に保存されたファインダーの内部キャッシュを無効にします。ファインダーが invalidate_caches() を実装していれば、無効化を行うためにそれが呼び出されます。すべてのファインダーが新しいモジュールの存在に気づくことを保証しているプログラムの実行中に、モジュールが作成またはインストールされたなら、この関数が呼び出されるべきです。

Added in version 3.3.

バージョン 3.10 で変更: Namespace packages created/installed in a different sys.path location after the same namespace was already imported are noticed.

importlib.reload(module)

以前にインポートされた module をリロードします。引数はモジュールオブジェクトでなければならず、したがってそれ以前に必ずインポートに成功していなければなりません。この関数は、モジュールのソースファイルを外部エディタで編集していて Python インタープリタから離れることなく新しいバージョンを試したい際に便利です。戻り値はモジュールオブジェクトです。 (もし再インポートが異なるオブジェクトを sys.modules に配置したら、元の module とは異なるかもしれません。)

reload() が実行された場合:

Python モジュールのコードは再コンパイルされ、モジュールレベルのコードが再度実行されます。モジュールの辞書中にある何らかの名前に結び付けられたオブジェクトは、そのモジュールを最初にロードしたときの ローダー を再利用して新たに定義されます。拡張モジュールの init 関数が二度呼び出されることはありません。

Python における他のオブジェクトと同様、以前のオブジェクトのメモリ領域は、参照カウントがゼロにならないかぎり再利用されません。

モジュール名前空間内の名前は新しいオブジェクト (または更新されたオブジェクト) を指すよう更新されます。

以前のオブジェクトが (外部の他のモジュールなどからの) 参照を受けている場合、それらを新たなオブジェクトに再束縛し直すことはないので、必要なら自分で名前空間を更新しなければなりません。

いくつか補足説明があります:

モジュールが再ロードされた際、その辞書 (モジュールのグローバル変数を含みます) はそのまま残ります。名前の再定義を行うと、以前の定義を上書きするので、一般的には問題はありません。新たなバージョンのモジュールが古いバージョンで定義された名前を定義していない場合、古い定義がそのまま残ります。辞書がグローバルテーブルやオブジェクトのキャッシュを維持していれば、この機能をモジュールを有効性を引き出すために使うことができます --- つまり、 try 文を使えば、必要に応じてテーブルがあるかどうかをテストし、その初期化を飛ばすことができます:

try:
    cache
except NameError:
    cache = {}

組み込みモジュールや動的にロードされるモジュールを再ロードすることは、一般的にそれほど便利ではありません。 sys, __main__, builtins やその他重要なモジュールの再ロードはお勧め出来ません。多くの場合、拡張モジュールは 1 度以上初期化されるようには設計されておらず、再ロードされた場合には何らかの理由で失敗するかもしれません。

一方のモジュールが from ... import ... を使って、オブジェクトを他方のモジュールからインポートしているなら、他方のモジュールを reload() で呼び出しても、そのモジュールからインポートされたオブジェクトを再定義することはできません --- この問題を回避する一つの方法は、 from 文を再度実行することで、もう一つの方法は from 文の代わりに import と限定的な名前 (module.name) を使うことです。

あるモジュールがクラスのインスタンスを生成している場合、そのクラスを定義しているモジュールの再ロードはそれらインスタンスのメソッド定義に影響しません --- それらは古いクラス定義を使い続けます。これは派生クラスの場合でも同じです。

Added in version 3.4.

バージョン 3.7 で変更: リロードされたモジュールの ModuleSpec が欠けていたときは ModuleNotFoundError が送出されます。

importlib.abc -- インポートに関連する抽象基底クラス

ソースコード: Lib/importlib/abc.py [https://github.com/python/cpython/tree/3.12/Lib/importlib/abc.py]

importlib.abc モジュールは、 import に使われるすべてのコア抽象基底クラス含みます。コア抽象基底クラスの実装を助けるために、コア抽象基底クラスのサブクラスもいくつか提供されています。

抽象基底クラス階層:

object
 +-- MetaPathFinder
 +-- PathEntryFinder
 +-- Loader
      +-- ResourceLoader --------+
      +-- InspectLoader          |
           +-- ExecutionLoader --+
                                 +-- FileLoader
                                 +-- SourceLoader

class importlib.abc.MetaPathFinder

meta path finder を表す抽象基底クラスです。

Added in version 3.3.

バージョン 3.10 で変更: No longer a subclass of Finder.

find_spec(fullname, path, target=None)

指定されたモジュールに対応する スペック を検索する抽象メソッド。もしこれがトップレベルのインポートなら、 path は None です。そうでなければ、これはサブパッケージまたはモジュールのための検索で、 path は親パッケージの __path__ の値です。スペックが見つからなければ None が返されます。 target は、渡されてきたならモジュールオブジェクトです。これはファインダーがどのようなスペックを返せばよいか推測するために使用します。具体的な MetaPathFinders を実装するためには importlib.util.spec_from_loader() が便利かもしれません。

Added in version 3.4.

invalidate_caches()

このファインダーで使われている内部キャッシュがあれば無効にするオプションのメソッドです。 sys.meta_path 上のすべてのファインダーのキャッシュを無効化する際、 importlib.invalidate_caches() によって使われます。

バージョン 3.4 で変更: Returns None when called instead of NotImplemented.

class importlib.abc.PathEntryFinder

path entry finder を表す抽象基底クラスです。 MetaPathFinder と似ているところがありますが、 PathEntryFinder は importlib.machinery.PathFinder が提供するパスに基づく import サブシステムの中でのみ使うことが意図されています。

Added in version 3.3.

バージョン 3.10 で変更: No longer a subclass of Finder.

find_spec(fullname, target=None)

指定されたモジュールに対応する スペック を検索する抽象メソッド。ファインダーは、割り当てられている パス・エントリー 内のモジュールだけを検索します。スペックが見つからなければ None が返されます。 target は、渡されてきたならモジュールオブジェクトです。これはファインダーがどのようなスペックを返せばよいか推測するために使用します。具体的な PathEntryFinders を実装するためには importlib.util.spec_from_loader() が便利かもしれません。

Added in version 3.4.

invalidate_caches()

このファインダーで使われている内部キャッシュがあれば無効にするオプションのメソッドです。キャッシュされたすべてのファインダーの無効化する際、 importlib.machinery.PathFinder.invalidate_caches() によって使われます。

class importlib.abc.Loader

loader の抽象基底クラスです。ローダーの厳密な定義は PEP 302 [https://peps.python.org/pep-0302/] を参照してください。

リソースの読み出しをサポートさせたいローダーには、 importlib.resources.abc.ResourceReader で指定されている get_resource_reader() メソッドを実装してください。

バージョン 3.7 で変更: オプションの get_resource_reader() メソッドが導入されました。

create_module(spec)

モジュールをインポートする際に使用されるモジュールオブジェクトを返すメソッド。このメソッドは None を戻すことができ、その場合はデフォルトのモジュール作成のセマンティクスが適用されることを示します。

Added in version 3.4.

バージョン 3.6 で変更: exec_module() が定義されている場合は、このメソッドはオプションではなくなりました。

exec_module(module)

モジュールがインポートまたはリロードされる際に、そのモジュールをモジュール自身の名前空間の中で実行する抽象的なメソッド。 exec_module() が呼ばれる時点で、モジュールはすでに初期設定されている必要があります。このメソッドが存在するときは、 create_module() の定義が必須です。

Added in version 3.4.

バージョン 3.6 で変更: create_module() の定義が必須となりました。

load_module(fullname)

モジュールをロードするためのレガシーなメソッドです。モジュールがロードできなければ ImportError を送出し、ロードできればロードされたモジュールを返します。

If the requested module already exists in sys.modules, that module should be used and reloaded. Otherwise the loader should create a new module and insert it into 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 sys.modules; modules already in sys.modules before the loader began execution should be left alone.

ローダーはモジュールにいくつかの属性を設定する必要があります。(なお、これらの属性には、モジュールがリロードされた際に変化するものがあります):

__name__

The module's fully qualified name. It is '__main__' for an executed module.

__file__

The location the loader used to load the module. For example, for modules loaded from a .py file this is the filename. It is not set on all modules (e.g. built-in modules).

__cached__

The filename of a compiled version of the module's code. It is not set on all modules (e.g. built-in modules).

__path__

The list of locations where the package's submodules will be found. Most of the time this is a single directory. The import system passes this attribute to __import__() and to finders in the same way as sys.path but just for the package. It is not set on non-package modules so it can be used as an indicator that the module is a package.

__package__

The fully qualified name of the package the module is in (or the empty string for a top-level module). If the module is a package then this is the same as __name__.

__loader__

The loader used to load the module.

exec_module() が利用可能な場合、後方互換な機能が提供されます。

バージョン 3.4 で変更: Raise ImportError when called instead of NotImplementedError. Functionality provided when exec_module() is available.

バージョン 3.4 で非推奨: モジュールをロードするための推奨される API は、 exec_module() (および create_module()) です。ローダーは load_module() の代わりにそれを実装するべきです。 exec_module() が実装されている場合、インポート機構は load_module() の他のすべての責任を肩代わりします。

class importlib.abc.ResourceLoader

loader の抽象基底クラスで、ストレージバックエンドから任意のリソースをロードするオプションの PEP 302 [https://peps.python.org/pep-0302/] プロトコルを実装します。

バージョン 3.7 で非推奨: This ABC is deprecated in favour of supporting resource loading through importlib.resources.abc.ResourceReader.

abstractmethod get_data(path)

path に割り当てられたデータのバイト列を返す抽象メソッドです。任意のデータを保管できるファイル的なストレージバックエンドをもつローダーは、この抽象メソッドを実装して、保管されたデータに直接アクセスさせるようにできます。 path が見つからなければ OSError を送出する必要があります。 path は、モジュールの __file__ 属性を使って、またはパッケージの __path__ の要素を使って、構成されることが期待されます。

バージョン 3.4 で変更: NotImplementedError の代わりに OSError を送出します。

class importlib.abc.InspectLoader

loader の抽象基底クラスで、ローダーがモジュールを検査するためのオプションの PEP 302 [https://peps.python.org/pep-0302/] プロトコルを実装します。

get_code(fullname)

モジュールの code オブジェクトを返すか、 (例えば組み込みモジュールの場合に) モジュールがコードオブジェクトを持たなければ None を返します。要求されたモジュールをローダーが見つけられなかった場合は ImportError を送出します。

注釈

このメソッドにはデフォルト実装がありますが、とはいえパフォーマンスのために、可能ならばオーバライドしたほうが良いです。

バージョン 3.4 で変更: このメソッドはもはや抽象メソッドではなく、具象実装が提供されます。

abstractmethod get_source(fullname)

モジュールのソースを返す抽象メソッドです。これは認識されたすべての行セパレータを '\n' 文字に変換し、 universal newlines を使ったテキスト文字列として返されます。利用できるソースがなければ (例えば組み込みモジュール)、 None を返します。指定されたモジュールが見つからなければ、 ImportError を送出します。

バージョン 3.4 で変更: NotImplementedError の代わりに ImportError を送出します。

is_package(fullname)

モジュールがパッケージであれば True を返し、そうでなければ False を返すオプションのメソッドです。 ローダー がモジュールを見つけられなかったなら ImportError が送出されます。

バージョン 3.4 で変更: NotImplementedError の代わりに ImportError を送出します。

static source_to_code(data, path='<string>')

Python のソースからコードオブジェクトを作ります。

data 引数は compile() 関数がサポートするもの (すなわち文字列かバイト) なら何でも構いません。path 引数はソースコードの元々の場所への "パス" でなければなりませんが、抽象概念 (例えば zip ファイル内の場所) でも構いません。

結果のコードオブジェクトを使って、 exec(code, module.__dict__) を呼ぶことでモジュール内でコードを実行できます。

Added in version 3.4.

バージョン 3.5 で変更: スタティックメソッドになりました。

exec_module(module)

Loader.exec_module() の実装です。

Added in version 3.4.

load_module(fullname)

Loader.load_module() の実装です。

バージョン 3.4 で非推奨: 代わりに exec_module() を使用してください。

class importlib.abc.ExecutionLoader

InspectLoader から継承された抽象基底クラスで、実装されていれば、モジュールをスクリプトとして実行する助けになります。この抽象基底クラスはオプションの PEP 302 [https://peps.python.org/pep-0302/] プロトコルを表します。

abstractmethod get_filename(fullname)

指定されたモジュールの __file__ の値を返す抽象メソッドです。利用できるパスがなければ、 ImportError が送出されます。

ソースコードが利用できるなら、そのモジュールのロードにバイトコードが使われたかにかかわらず、このメソッドはそのソースファイルへのパスを返す必要があります。

バージョン 3.4 で変更: NotImplementedError の代わりに ImportError を送出します。

class importlib.abc.FileLoader(fullname, path)

ResourceLoader と ExecutionLoader から継承された抽象基底クラスで、 ResourceLoader.get_data() および ExecutionLoader.get_filename() の具象実装を提供します。

fullname 引数は、ローダーが解決しようとするモジュールの、完全に解決された名前です。path 引数は、モジュールのファイルへのパスです。

Added in version 3.3.

name

ローダーが扱えるモジュールの名前です。

path

モジュールのファイルへのパスです。

load_module(fullname)

親クラスの load_module() を呼び出します。

バージョン 3.4 で非推奨: 代わりに Loader.exec_module() を使用してください。

abstractmethod get_filename(fullname)

path を返します。

abstractmethod get_data(path)

path をバイナリファイルとして読み込み、そのバイト列を返します。

class importlib.abc.SourceLoader

ソース (オプションでバイトコード) ファイルのロードを実装する抽象基底クラスです。このクラスは、 ResourceLoader と ExecutionLoader の両方を継承し、以下の実装が必要です:

ResourceLoader.get_data()

ExecutionLoader.get_filename()

ソースファイルへのパスのみを返す必要があります。ソースなしのロードはサポートされていません。

このクラスでこれらの抽象メソッドを定義することで、バイトコードファイルを追加でサポートします。これらのメソッドを定義しなければ (またはそのモジュールが NotImplementedError を送出すれば)、このローダーはソースコードに対してのみ働きます。これらのメソッドを実装することで、ローダーはソースとバイトコードファイル の組み合わせ に対して働きます。バイトコードのみを与えた ソースのない ロードは認められません。バイトコードファイルは、 Python コンパイラによる解析の工程をなくして速度を上げる最適化です。ですから、バイトコード特有の API は公開されていません。

path_stats(path)

指定されたパスについてのメタデータを含む dict を返す、オプションの抽象メソッドです。サポートされる辞書のキーは:

'mtime' (必須): ソースコードの更新時刻を表す整数または浮動小数点数です。

'size' (任意): バイト数で表したソースコードのサイズです。

未来の拡張のため、辞書内の他のキーは無視されます。パスが扱えなければ、 OSError が送出されます。

Added in version 3.3.

バージョン 3.4 で変更: NotImplementedError の代わりに OSError を送出します。

path_mtime(path)

指定されたパスの更新時刻を返す、オプションの抽象メソッドです。

バージョン 3.3 で非推奨: このメソッドは廃止され、 path_stats() が推奨されます。このモジュールを実装する必要はありませんが、互換性のため現在も利用できます。パスが扱えなければ、 OSError が送出されます。

バージョン 3.4 で変更: NotImplementedError の代わりに OSError を送出します。

set_data(path, data)

ファイルパスに指定されたバイト列を書き込むオプションの抽象メソッドです。存在しない中間ディレクトリがあれば、自動で作成されます。

When writing to the path fails because the path is read-only (errno.EACCES/PermissionError), do not propagate the exception.

バージョン 3.4 で変更: 呼ばれたときに NotImplementedError を送出することは最早ありません。

get_code(fullname)

InspectLoader.get_code() の具象実装です。

exec_module(module)

Loader.exec_module() の具象実装です。

Added in version 3.4.

load_module(fullname)

Loader.load_module() の具象実装です。

バージョン 3.4 で非推奨: 代わりに exec_module() を使用してください。

get_source(fullname)

InspectLoader.get_source() の具象実装です。

is_package(fullname)

InspectLoader.is_package() の具象実装です。モジュールは、次の 両方 を満たすならパッケージであると決定されます。モジュールの (ExecutionLoader.get_filename() で与えられる) ファイルパスが、ファイル拡張子を除くと __init__ という名のファイルであること。モジュール名自体が __init__ で終わらないこと。

class importlib.abc.ResourceReader

Superseded by TraversableResources

resources の読み出し機能を提供する 抽象基底クラス (abstract base class, ABC) です。

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 __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 in a e.g. zip file versus on the file system.

For any of methods of this class, a resource argument is expected to be a 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 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 None. An object compatible with this ABC should only be returned when the specified module is a package.

Added in version 3.7.

バージョン 3.12 で非推奨、バージョン 3.14 で削除予定: Use importlib.resources.abc.TraversableResources instead.

abstractmethod open_resource(resource)

Returns an opened, file-like object for binary reading of the resource.

リソースが見付からない場合は、 FileNotFoundError が送出されます。

abstractmethod resource_path(resource)

resource へのファイルシステムパスを返します。

リソースの実体がファイルシステムに存在しない場合、 FileNotFoundError が送出されます。

abstractmethod is_resource(name)

name という名前がリソースだと見なせるなら True を返します。 name が存在しない場合は FileNotFoundError が送出されます。

abstractmethod contents()

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

class importlib.abc.Traversable

An object with a subset of pathlib.Path methods suitable for traversing directories and opening files.

For a representation of the object on the file-system, use importlib.resources.as_file().

Added in version 3.9.

バージョン 3.12 で非推奨、バージョン 3.14 で削除予定: Use importlib.resources.abc.Traversable instead.

name

Abstract. The base name of this object without any parent references.

abstractmethod iterdir()

Yield Traversable objects in self.

abstractmethod is_dir()

Return True if self is a directory.

abstractmethod is_file()

Return True if self is a file.

abstractmethod joinpath(child)

Return Traversable child in self.

abstractmethod __truediv__(child)

Return Traversable child in self.

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 pathlib.Path.open).

When opening as text, accepts encoding parameters such as those accepted by io.TextIOWrapper.

read_bytes()

Read contents of self as bytes.

read_text(encoding=None)

Read contents of self as text.

class importlib.abc.TraversableResources

An abstract base class for resource readers capable of serving the importlib.resources.files() interface. Subclasses importlib.resources.abc.ResourceReader and provides concrete implementations of the importlib.resources.abc.ResourceReader's abstract methods. Therefore, any loader supplying importlib.abc.TraversableResources also supplies ResourceReader.

Loaders that wish to support resource reading are expected to implement this interface.

Added in version 3.9.

バージョン 3.12 で非推奨、バージョン 3.14 で削除予定: Use importlib.resources.abc.TraversableResources instead.

abstractmethod files()

Returns a importlib.resources.abc.Traversable object for the loaded package.

importlib.machinery -- インポータおよびパスフック

ソースコード: Lib/importlib/machinery.py [https://github.com/python/cpython/tree/3.12/Lib/importlib/machinery.py]

このモジュールには、 import がモジュールを検索してロードするのに役立つ様々なオブジェクトがあります。

importlib.machinery.SOURCE_SUFFIXES

認識されているソースモジュールのファイル接尾辞を表す文字列のリストです。

Added in version 3.3.

importlib.machinery.DEBUG_BYTECODE_SUFFIXES

最適化されていないバイトコードモジュールのファイル接尾辞を表す文字列のリストです。

Added in version 3.3.

バージョン 3.5 で非推奨: 代わりに BYTECODE_SUFFIXES を使ってください。

importlib.machinery.OPTIMIZED_BYTECODE_SUFFIXES

最適化されたバイトコードモジュールのファイル接尾辞を表す文字列のリストです。

Added in version 3.3.

バージョン 3.5 で非推奨: 代わりに BYTECODE_SUFFIXES を使ってください。

importlib.machinery.BYTECODE_SUFFIXES

認識されているバイトコードモジュールのファイル接尾辞を表す文字列のリストです (先頭のドットを含みます)。

Added in version 3.3.

バージョン 3.5 で変更: この値は __debug__ に依存しなくなりました。

importlib.machinery.EXTENSION_SUFFIXES

認識されている最適化された拡張モジュールのファイル接尾辞を表す文字列のリストです。

Added in version 3.3.

importlib.machinery.all_suffixes()

標準のインポート機構によって認識されているすべてのファイル接尾辞を表す文字列の組み合わせられたリストを返します。これが役立つのは、あるファイルシステムパスがモジュールを参照する可能性があるかだけを知りたくて、そのモジュールの種類を詳しく知る必要はないコード (例えば inspect.getmodulename()) です。

Added in version 3.3.

class importlib.machinery.BuiltinImporter

組み込みモジュールの importer です。すべての既知のモジュールは sys.builtin_module_names に列挙されています。このクラスは importlib.abc.MetaPathFinder および importlib.abc.InspectLoader 抽象基底クラスを実装します。

インスタンス化の必要性を軽減するため、このクラスにはクラスメソッドだけが定義されています。

バージョン 3.5 で変更: PEP 489 [https://peps.python.org/pep-0489/] の一環として、ビルトインインポーターは Loader.create_module() と Loader.exec_module() を実装しています。

class importlib.machinery.FrozenImporter

フリーズされたモジュールの インポーター です。このクラスは importlib.abc.MetaPathFinder および importlib.abc.InspectLoader 抽象基底クラスを実装します。

インスタンス化の必要性を軽減するため、このクラスにはクラスメソッドだけが定義されています。

バージョン 3.4 で変更: Gained create_module() and exec_module() methods.

class importlib.machinery.WindowsRegistryFinder

Windows レジストリで宣言されたモジュールの finder です。このクラスは importlib.abc.MetaPathFinder 抽象基底クラスを実装します。

インスタンス化の必要性を軽減するため、このクラスにはクラスメソッドだけが定義されています。

Added in version 3.3.

バージョン 3.6 で非推奨: 代わりに site の設定を使ってください。 Python の将来のバージョンでは、デフォルトでこのファインダーが使えなくなるかもしれません。

class importlib.machinery.PathFinder

sys.path およびパッケージの __path__ 属性の Finder です。このクラスは importlib.abc.MetaPathFinder 抽象基底クラスを実装します。

インスタンス化の必要性を軽減するため、このクラスにはクラスメソッドだけが定義されています。

classmethod find_spec(fullname, path=None, target=None)

sys.path または定義されていれば path から、 fullname で指定されたモジュールの スペック の検索を試みるクラスメソッドです。検索されるそれぞれのパスエントリに対して sys.path_importer_cache が検査されます。偽でないオブジェクトが見つかれば、それが目的のモジュールを検索するための パスエントリ・ファインダー として使われます。 sys.path_importer_cache に目的のエントリが見つからなければ、パスエントリに対するファインダーが sys.path_hooks から検索され、見つかれば、それが sys.path_importer_cache に保管されるとともに、モジュールについて問い合わせられます。それでもファインダーが見つからなければ None が保管され、また返されます。

Added in version 3.4.

バージョン 3.5 で変更: もしカレントワーキングディレクトリ -- 空の文字列によって表されている -- がすでに有効でなければ、 None が返されますが値は sys.path_importer_cache にキャッシュされません。

classmethod invalidate_caches()

Calls importlib.abc.PathEntryFinder.invalidate_caches() on all finders stored in sys.path_importer_cache that define the method. Otherwise entries in sys.path_importer_cache set to None are deleted.

バージョン 3.7 で変更: Entries of None in sys.path_importer_cache are deleted.

バージョン 3.4 で変更: '' (すなわち空の文字列) に対してはカレントワーキングディレクトリとともに sys.path_hooks のオブジェクトを呼び出します。

class importlib.machinery.FileFinder(path, *loader_details)

ファイルシステムからの結果をキャッシュする importlib.abc.PathEntryFinder の具象実装です。

path 引数は検索を担当するファインダーのディレクトリです。

loader_details 引数は、可変個の 2 要素タプルで、それぞれがローダーとローダーが認識するファイル接尾辞のシーケンスとを含みます。ローダーは、呼び出し可能でモジュール名と見つかったファイルのパスとの 2 引数を受け付けることを期待されます。

ファインダーはモジュール検索のたびに stat を呼び出し、必要に応じてディレクトリの内容をキャッシュすることで、コードキャッシュが古くなっていないことを確かめます。キャッシュの古さはオペレーティングシステムのファイルシステムのステート情報の粒度に依存しますから、モジュールを検索し、新しいファイルを作成し、その後に新しいファイルが表すモジュールを検索する、という競合状態の可能性があります。この操作が stat の呼び出しの粒度に収まるほど速く起こると、モジュールの検索が失敗します。これを防ぐためには、モジュールを動的に作成する際に、必ず importlib.invalidate_caches() を呼び出してください。

Added in version 3.3.

path

ファインダーが検索されるパスです。

find_spec(fullname, target=None)

path 内で fullname を扱うスペックの探索を試みます。

Added in version 3.4.

invalidate_caches()

内部キャッシュを完全に消去します。

classmethod path_hook(*loader_details)

A class method which returns a closure for use on sys.path_hooks. An instance of FileFinder is returned by the closure using the path argument given to the closure directly and loader_details indirectly.

クロージャへの引数が存在するディレクトリでなければ、 ImportError が送出されます。

class importlib.machinery.SourceFileLoader(fullname, path)

importlib.abc.FileLoader を継承し、その他いくつかのメソッドの具象実装を提供する、 importlib.abc.SourceLoader の具象実装です。

Added in version 3.3.

name

このローダーが扱うモジュールの名前です。

path

ソースファイルへのパスです。

is_package(fullname)

path がパッケージを表すとき True を返します。

path_stats(path)

importlib.abc.SourceLoader.path_stats() の具象実装です。

set_data(path, data)

importlib.abc.SourceLoader.set_data() の具象実装です。

load_module(name=None)

ロードするモジュールの名前指定がオプションの、 importlib.abc.Loader.load_module() の具象実装です。

バージョン 3.6 で非推奨: 代わりに importlib.abc.Loader.exec_module() を使用してください。

class importlib.machinery.SourcelessFileLoader(fullname, path)

バイトコードファイル (すなわちソースコードファイルが存在しない) をインポートできる importlib.abc.FileLoader の具象実装です。

注意として、バイトコードを直接使う (つまりソースコードファイルがない) と、そのモジュールはすべての Python 実装では使用できないし、新しいバージョンの Python ではバイトコードフォーマットが変更されていたら使用できません。

Added in version 3.3.

name

ローダーが扱うモジュールの名前です。

path

バイトコードファイルへのパスです。

is_package(fullname)

そのモジュールがパッケージであるかを path に基づいて決定します。

get_code(fullname)

path から作成された name のコードオブジェクトを返します。

get_source(fullname)

このローダーが使われたとき、バイトコードファイルのソースがなければ None を返します。

load_module(name=None)

ロードするモジュールの名前指定がオプションの、 importlib.abc.Loader.load_module() の具象実装です。

バージョン 3.6 で非推奨: 代わりに importlib.abc.Loader.exec_module() を使用してください。

class importlib.machinery.ExtensionFileLoader(fullname, path)

拡張モジュールのための importlib.abc.ExecutionLoader の具象実装です。

fullname 引数はローダーがサポートするモジュールの名前を指定します。path 引数は拡張モジュールのファイルへのパスです。

Note that, by default, importing an extension module will fail in subinterpreters if it doesn't implement multi-phase init (see PEP 489 [https://peps.python.org/pep-0489/]), even if it would otherwise import successfully.

Added in version 3.3.

バージョン 3.12 で変更: Multi-phase init is now required for use in subinterpreters.

name

ローダーがサポートするモジュールの名前です。

path

拡張モジュールへのパスです。

create_module(spec)

与えられたスペックから PEP 489 [https://peps.python.org/pep-0489/] に従ってモジュールオブジェクトを作成します。

Added in version 3.5.

exec_module(module)

与えられたモジュールオブジェクトを PEP 489 [https://peps.python.org/pep-0489/] に従って初期化します。

Added in version 3.5.

is_package(fullname)

EXTENSION_SUFFIXES に基づいて、ファイルパスがパッケージの __init__ モジュールを指していれば True を返します。

get_code(fullname)

拡張モジュールにコードオブジェクトがなければ None を返します。

get_source(fullname)

拡張モジュールにソースコードがなければ None を返します。

get_filename(fullname)

path を返します。

Added in version 3.4.

class importlib.machinery.NamespaceLoader(name, path, path_finder)

A concrete implementation of importlib.abc.InspectLoader for namespace packages. This is an alias for a private class and is only made public for introspecting the __loader__ attribute on namespace packages:

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

Added in version 3.11.

class importlib.machinery.ModuleSpec(name, loader, *, origin=None, loader_state=None, is_package=None)

モジュールのインポートシステムに関する状態の仕様。これは通常はモジュールの __spec__ 属性として公開されています。この後の解説では、モジュールオブジェクトから直接利用できる属性で、それぞれの仕様に対応しているものの名前が括弧書きで書かれています。例えば、 module.__spec__.origin == module.__file__ です。ただし、属性の 値 はたいていは同一ですが、2つのオブジェクトどうしは同期されないため、異なっている可能性があることに注意してください。例えば、モジュールの __file__ を実行時に更新できますが、モジュールの __spec__.origin に自動的には反映されませんし、逆もまた同様です。

Added in version 3.4.

name

(__name__)

The module's fully qualified name. The finder should always set this attribute to a non-empty string.

loader

(__loader__)

The loader used to load the module. The finder should always set this attribute.

origin

(__file__)

The location the loader should use to load the module. For example, for modules loaded from a .py file this is the filename. The finder should always set this attribute to a meaningful value for the loader to use. In the uncommon case that there is not one (like for namespace packages), it should be set to None.

submodule_search_locations

(__path__)

The list of locations where the package's submodules will be found. Most of the time this is a single directory. The finder should set this attribute to a list, even an empty one, to indicate to the import system that the module is a package. It should be set to None for non-package modules. It is set automatically later to a special object for namespace packages.

loader_state

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

cached

(__cached__)

The filename of a compiled version of the module's code. The finder should always set this attribute but it may be None for modules that do not need compiled code stored.

parent

(__package__)

(Read-only) The fully qualified name of the package the module is in (or the empty string for a top-level module). If the module is a package then this is the same as name.

has_location

True if the spec's origin refers to a loadable location,

False otherwise. This value impacts how origin is interpreted and how the module's __file__ is populated.

importlib.util -- インポータのためのユーティリティコード

ソースコード: Lib/importlib/util.py [https://github.com/python/cpython/tree/3.12/Lib/importlib/util.py]

このモジュールには、 インポーター の構築を助ける様々なオブジェクトがあります。

importlib.util.MAGIC_NUMBER

バイトコードバージョン番号を表しているバイト列。バイトコードのロード／書き込みについてヘルプが必要なら importlib.abc.SourceLoader を参照してください。

Added in version 3.4.

importlib.util.cache_from_source(path, debug_override=None, *, optimization=None)

ソース path に関連付けられたバイトコンパイルされたファイルの PEP 3147 [https://peps.python.org/pep-3147/]/PEP 488 [https://peps.python.org/pep-0488/] パスを返します。例えば、 path が /foo/bar/baz.py なら、 Python 3.2 の場合返り値は /foo/bar/__pycache__/baz.cpython-32.pyc になります。 cpython-32 という文字列は、現在のマジックタグから得られます (マジックタグについては get_tag() を参照; sys.implementation.cache_tag が未定義なら NotImplementedError が送出されます。)

optimization パラメータは、バイトコードファイルの最適化レベルを指定するために使われます。空文字列は最適化しないことを表します。したがって、 optimization が '' のとき /foo/bar/baz.py に対して /foo/bar/__pycache__/baz.cpython-32.pyc というバイトコードパスが返ります。 None にするとインタープリタの最適化レベルが使われます。それ以外では値の文字列表現が使われます。したがって、 optimization が 2 のとき /foo/bar/baz.py に対して /foo/bar/__pycache__/baz.cpython-32.opt-2.pyc というバイトコードパスが返ります。 optimization の文字列表現は英数字だけが可能で、そうでなければ ValueError が上げられます。

debug_override パラメータは deprecated で、システムの __debug__ 値をオーバーライドするために使用できます。 True 値は optimization を空文字列に設定するのと等価です。 False 値は optimization を 1 に設定するのと同等です。もし debug_override と optimization のどちらも None 以外であれば TypeError が上げられます。

Added in version 3.4.

バージョン 3.5 で変更: optimization パラメータが追加され、 debug_override パラメータは deprecated になりました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

importlib.util.source_from_cache(path)

PEP 3147 [https://peps.python.org/pep-3147/] ファイル名への path が与えられると、関連するソースコードのファイルパスを返します。例えば、 path が /foo/bar/__pycache__/baz.cpython-32.pyc なら、返されるパスは /foo/bar/baz.py になります。 path は存在する必要はありませんが、 PEP 3147 [https://peps.python.org/pep-3147/] または PEP 488 [https://peps.python.org/pep-0488/] フォーマットに一致しない場合は ValueError が送出されます。 sys.implementation.cache_tag が定義されていない場合、 NotImplementedError が送出されます。

Added in version 3.4.

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

importlib.util.decode_source(source_bytes)

与えられたソースコードを表すバイト列をデコードして、文字列としてそれを一般的な改行形式 (universal newlines) で返します (importlib.abc.InspectLoader.get_source() で要求されるように)。

Added in version 3.4.

importlib.util.resolve_name(name, package)

相対的なモジュール名を解決して絶対的なものにします。

name の先頭にドットがなければ、単に name が返されます。これにより、例えば importlib.util.resolve_name('sys', __spec__.parent) を使うときに package 変数が必要かどうかを確認する必要がなくなります。

name が相対的なモジュール名であるにもかかわらず package が偽値 (例えば None や空文字列) ならば、 ImportError が送出されます。相対的な名前がそれを含むパッケージから抜け出る (例えば spam パッケージ内から ..bacon を要求する) 場合にも ImportError が送出されます。

Added in version 3.3.

バージョン 3.9 で変更: To improve consistency with import statements, raise ImportError instead of ValueError for invalid relative import attempts.

importlib.util.find_spec(name, package=None)

Find the spec for a module, optionally relative to the specified package name. If the module is in sys.modules, then sys.modules[name].__spec__ is returned (unless the spec would be None or is not set, in which case ValueError is raised). Otherwise a search using sys.meta_path is done. None is returned if no spec is found.

name がサブモジュールを示している (ドットを含む) 場合、親モジュールは自動的にインポートされます。

name と package は import_module() に対するものと同じように機能します。

Added in version 3.4.

バージョン 3.7 で変更: Raises ModuleNotFoundError instead of AttributeError if package is in fact not a package (i.e. lacks a __path__ attribute).

importlib.util.module_from_spec(spec)

spec と spec.loader.create_module に基づいて新しいモジュールを作ります。

spec.loader.create_module が None を返さない場合は、既に存在するどの属性もリセットされません。また、 spec にアクセスしたり属性をモジュールに設定したりする際に AttributeError 例外が起きても例外は送出されません。

この関数は、新しいモジュールを作る方法として types.ModuleType よりも推奨されます。なぜなら、できるだけ多くのインポートコントロールされた属性をモジュールに設定するために spec が使用されるからです。

Added in version 3.5.

importlib.util.spec_from_loader(name, loader, *, origin=None, is_package=None)

この関数は、スペックに不足している情報を埋めるために ModuleSpec のような利用可能な loader API を使います。

Added in version 3.4.

importlib.util.spec_from_file_location(name, location, *, loader=None, submodule_search_locations=None)

ファイルへのパスにもとづいて ModuleSpec インスタンスを生成するためのファクトリー関数。不足している情報は、ローダー API を利用してスペックから得られる情報と、モジュールがファイルベースであるという暗黙的な情報によって埋められます。

Added in version 3.4.

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

importlib.util.source_hash(source_bytes)

Return the hash of source_bytes as bytes. A hash-based .pyc file embeds the source_hash() of the corresponding source file's contents in its header.

Added in version 3.7.

importlib.util._incompatible_extension_module_restrictions(*, disable_check)

A context manager that can temporarily skip the compatibility check for extension modules. By default the check is enabled and will fail when a single-phase init module is imported in a subinterpreter. It will also fail for a multi-phase init module that doesn't explicitly support a per-interpreter GIL, when imported in an interpreter with its own GIL.

Note that this function is meant to accommodate an unusual case; one which is likely to eventually go away. There's is a pretty good chance this is not what you were looking for.

You can get the same effect as this function by implementing the basic interface of multi-phase init (PEP 489 [https://peps.python.org/pep-0489/]) and lying about support for multiple interpreters (or per-interpreter GIL).

警告

Using this function to disable the check can lead to unexpected behavior and even crashes. It should only be used during extension module development.

Added in version 3.12.

class importlib.util.LazyLoader(loader)

モジュールが属性アクセスできるようになるまで、モジュールのローダーの実行を遅延するクラス。

This class only works with loaders that define exec_module() as control over what module type is used for the module is required. For those same reasons, the loader's create_module() method must return None or a type for which its __class__ attribute can be mutated along with not using slots. Finally, modules which substitute the object placed into sys.modules will not work as there is no way to properly replace the module references throughout the interpreter safely; ValueError is raised if such a substitution is detected.

注釈

起動時間が重要なプロジェクトでは、もし決して使われないモジュールがあれば、このクラスを使ってモジュールをロードするコストを最小化できるかもしれません。スタートアップ時間が重要でないプロジェクトでは、遅延されたロードの際に発生して文脈の外で起こるエラーメッセージのため、このクラスの使用は 著しく 推奨されません。

Added in version 3.5.

バージョン 3.6 で変更: Began calling create_module(), removing the compatibility warning for importlib.machinery.BuiltinImporter and importlib.machinery.ExtensionFileLoader.

classmethod factory(loader)

遅延ローダを生成する callable を返すクラスメソッド。これは、ローダーをインスタンスとしてではなくクラスとして渡すような状況において使われることを意図しています。

suffixes = importlib.machinery.SOURCE_SUFFIXES
loader = importlib.machinery.SourceFileLoader
lazy_loader = importlib.util.LazyLoader.factory(loader)
finder = importlib.machinery.FileFinder(path, (lazy_loader, suffixes))

使用例

プログラムからのインポート

プログラムからモジュールをインポートするには、 importlib.import_module() を使ってください。

import importlib

itertools = importlib.import_module('itertools')

モジュールがインポートできるか確認する

インポートを実際に行わずに、あるモジュールがインポートできるかを知る必要がある場合は、 importlib.util.find_spec() を使ってください。

Note that if name is a submodule (contains a dot), importlib.util.find_spec() will import the parent module.

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")

ソースファイルから直接インポートする

To import a Python source file directly, use the following recipe:

import importlib.util
import sys

# For illustrative purposes.
import tokenize
file_path = tokenize.__file__
module_name = tokenize.__name__

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)

Implementing lazy imports

The example below shows how to implement lazy imports:

>>> import importlib.util
>>> import sys
>>> def lazy_import(name):
...     spec = importlib.util.find_spec(name)
...     loader = importlib.util.LazyLoader(spec.loader)
...     spec.loader = loader
...     module = importlib.util.module_from_spec(spec)
...     sys.modules[name] = module
...     loader.exec_module(module)
...     return module
...
>>> lazy_typing = lazy_import("typing")
>>> #lazy_typing is a real module object,
>>> #but it is not loaded in memory yet.
>>> lazy_typing.TYPE_CHECKING
False

インポーターのセットアップ

For deep customizations of import, you typically want to implement an importer. This means managing both the finder and loader side of things. For finders there are two flavours to choose from depending on your needs: a meta path finder or a path entry finder. The former is what you would put on sys.meta_path while the latter is what you create using a path entry hook on sys.path_hooks which works with 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):

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

Approximating 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 importlib.import_module():

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

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

ソースコード: Lib/importlib/resources/__init__.py [https://github.com/python/cpython/tree/3.12/Lib/importlib/resources/__init__.py]

Added in version 3.7.

This module leverages Python's import system to provide access to resources within packages.

"Resources" are file-like resources associated with a module or package in Python. The resources may be contained directly in a package, within a subdirectory contained in that package, or adjacent to modules outside a package. Resources may be text or binary. As a result, Python module sources (.py) of a package and compilation artifacts (pycache) are technically de-facto resources of that package. In practice, however, resources are primarily those non-Python artifacts exposed specifically by the package author.

Resources can be opened or read in either binary or text mode.

リソースは大体ディレクトリの中のファイルに似ていますが、これは単なる例え話であることを頭に入れておくことが重要です。例えば、パッケージとそのリソースは zipimport を使って zip ファイルからインポートすることができます。

注釈

このモジュールは、 pkg_resources [https://setuptools.readthedocs.io/en/latest/pkg_resources.html] Basic Resource Access [https://setuptools.readthedocs.io/en/latest/pkg_resources.html#basic-resource-access] に似た機能を、そのパッケージのパフォーマンスのオーバーヘッドを伴わずに提供します。 これにより、パッケージに含まれるリソースの読み込みがより簡単になり、より安定した一貫した意味付けができるようになります。

このモジュールのスタンドアローンバックポートでは、 importlib.resources の使用 [https://importlib-resources.readthedocs.io/en/latest/using.html] と pkg_resources から importlib.resources への移行 [https://importlib-resources.readthedocs.io/en/latest/migration.html] についての詳細情報を提供しています。

Loaders でリソースの読み込みをサポートしたい場合は、 importlib.resources.abc.ResourceReader で指定された get_resource_reader(fullname) メソッドを実装しなければいけません。

class importlib.resources.Anchor

Represents an anchor for resources, either a module object or a module name as a string. Defined as Union[str, ModuleType].

importlib.resources.files(anchor: Anchor | None = None)

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

Added in version 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 DeprecationWarning. Consider passing the anchor positionally or using importlib_resources >= 5.10 for a compatible interface on older Pythons.

importlib.resources.as_file(traversable)

Given a Traversable object representing a file or directory, typically from importlib.resources.files(), return a context manager for use in a with statement. The context manager provides a 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 as_file when the Traversable methods (read_text, etc) are insufficient and an actual file or directory on the file system is required.

Added in version 3.9.

バージョン 3.12 で変更: Added support for traversable representing a directory.

Deprecated functions

An older, deprecated set of functions is still available, but is scheduled for removal in a future version of Python. The main drawback of these functions is that they do not support directories: they assume all resources are located directly within a package.

importlib.resources.Package

Whenever a function accepts a Package argument, you can pass in either a module object or a module name as a string. You can only pass module objects whose __spec__.submodule_search_locations is not None.

The Package type is defined as Union[str, ModuleType].

バージョン 3.12 で非推奨.

importlib.resources.Resource

For resource arguments of the functions below, you can pass in the name of a resource as a string or a path-like object.

The Resource type is defined as Union[str, os.PathLike].

importlib.resources.open_binary(package, resource)

Open for binary reading the resource within package.

package is either a name or a module object which conforms to the Package requirements. resource is the name of the resource to open within package; it may not contain path separators and it may not have sub-resources (i.e. it cannot be a directory). This function returns a typing.BinaryIO instance, a binary I/O stream open for reading.

バージョン 3.11 で非推奨: Calls to this function can be replaced by:

files(package).joinpath(resource).open('rb')

importlib.resources.open_text(package, resource, encoding='utf-8', errors='strict')

Open for text reading the resource within package. By default, the resource is opened for reading as UTF-8.

package is either a name or a module object which conforms to the Package requirements. resource is the name of the resource to open within package; it may not contain path separators and it may not have sub-resources (i.e. it cannot be a directory). encoding and errors have the same meaning as with built-in open().

This function returns a typing.TextIO instance, a text I/O stream open for reading.

バージョン 3.11 で非推奨: Calls to this function can be replaced by:

files(package).joinpath(resource).open('r', encoding=encoding)

importlib.resources.read_binary(package, resource)

Read and return the contents of the resource within package as bytes.

package is either a name or a module object which conforms to the Package requirements. resource is the name of the resource to open within package; it may not contain path separators and it may not have sub-resources (i.e. it cannot be a directory). This function returns the contents of the resource as bytes.

バージョン 3.11 で非推奨: Calls to this function can be replaced by:

files(package).joinpath(resource).read_bytes()

importlib.resources.read_text(package, resource, encoding='utf-8', errors='strict')

Read and return the contents of resource within package as a str. By default, the contents are read as strict UTF-8.

package is either a name or a module object which conforms to the Package requirements. resource is the name of the resource to open within package; it may not contain path separators and it may not have sub-resources (i.e. it cannot be a directory). encoding and errors have the same meaning as with built-in open(). This function returns the contents of the resource as str.

バージョン 3.11 で非推奨: Calls to this function can be replaced by:

files(package).joinpath(resource).read_text(encoding=encoding)

importlib.resources.path(package, resource)

Return the path to the resource as an actual file system path. This function returns a context manager for use in a with statement. The context manager provides a pathlib.Path object.

Exiting the context manager cleans up any temporary file created when the resource needs to be extracted from e.g. a zip file.

package is either a name or a module object which conforms to the Package requirements. resource is the name of the resource to open within package; it may not contain path separators and it may not have sub-resources (i.e. it cannot be a directory).

バージョン 3.11 で非推奨: Calls to this function can be replaced using as_file():

as_file(files(package).joinpath(resource))

importlib.resources.is_resource(package, name)

Return True if there is a resource named name in the package, otherwise False. This function does not consider directories to be resources. package is either a name or a module object which conforms to the Package requirements.

バージョン 3.11 で非推奨: Calls to this function can be replaced by:

files(package).joinpath(resource).is_file()

importlib.resources.contents(package)

Return an iterable over the named items within the package. The iterable returns str resources (e.g. files) and non-resources (e.g. directories). The iterable does not recurse into subdirectories.

package is either a name or a module object which conforms to the Package requirements.

バージョン 3.11 で非推奨: Calls to this function can be replaced by:

(resource.name for resource in files(package).iterdir() if resource.is_file())

importlib.resources.abc -- Abstract base classes for resources

Source code: Lib/importlib/resources/abc.py [https://github.com/python/cpython/tree/3.12/Lib/importlib/resources/abc.py]

Added in version 3.11.

class importlib.resources.abc.ResourceReader

Superseded by TraversableResources

resources の読み出し機能を提供する 抽象基底クラス (abstract base class, ABC) です。

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 __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 in a e.g. zip file versus on the file system.

For any of methods of this class, a resource argument is expected to be a 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 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 None. An object compatible with this ABC should only be returned when the specified module is a package.

バージョン 3.12 で非推奨、バージョン 3.14 で削除予定: Use importlib.resources.abc.TraversableResources instead.

abstractmethod open_resource(resource)

Returns an opened, file-like object for binary reading of the resource.

リソースが見付からない場合は、 FileNotFoundError が送出されます。

abstractmethod resource_path(resource)

resource へのファイルシステムパスを返します。

リソースの実体がファイルシステムに存在しない場合、 FileNotFoundError が送出されます。

abstractmethod is_resource(name)

name という名前がリソースだと見なせるなら True を返します。 name が存在しない場合は FileNotFoundError が送出されます。

abstractmethod contents()

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

class importlib.resources.abc.Traversable

An object with a subset of pathlib.Path methods suitable for traversing directories and opening files.

For a representation of the object on the file-system, use importlib.resources.as_file().

name

Abstract. The base name of this object without any parent references.

abstractmethod iterdir()

Yield Traversable objects in self.

abstractmethod is_dir()

Return True if self is a directory.

abstractmethod is_file()

Return True if self is a file.

abstractmethod joinpath(*pathsegments)

Traverse directories according to pathsegments and return the result as Traversable.

Each pathsegments argument may contain multiple names separated by forward slashes (/, posixpath.sep ). For example, the following are equivalent:

files.joinpath('subdir', 'subsuddir', 'file.txt')
files.joinpath('subdir/subsuddir/file.txt')

Note that some 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 joinpath. For example:

files.joinpath('subdir').joinpath('subsubdir').joinpath('file.txt')

バージョン 3.11 で変更: joinpath accepts multiple pathsegments, and these segments may contain forward slashes as path separators. Previously, only a single child argument was accepted.

abstractmethod __truediv__(child)

Return Traversable child in self. Equivalent to joinpath(child).

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 pathlib.Path.open).

When opening as text, accepts encoding parameters such as those accepted by io.TextIOWrapper.

read_bytes()

Read contents of self as bytes.

read_text(encoding=None)

Read contents of self as text.

class importlib.resources.abc.TraversableResources

An abstract base class for resource readers capable of serving the importlib.resources.files() interface. Subclasses ResourceReader and provides concrete implementations of the ResourceReader's abstract methods. Therefore, any loader supplying TraversableResources also supplies ResourceReader.

Loaders that wish to support resource reading are expected to implement this interface.

abstractmethod files()

Returns a importlib.resources.abc.Traversable object for the loaded package.

importlib.metadata -- Accessing package metadata

Added in version 3.8.

バージョン 3.10 で変更: importlib.metadata は、暫定的なものではなくなりました。

ソースコード: Lib/importlib/metadata/__init__.py [https://github.com/python/cpython/tree/3.12/Lib/importlib/metadata/__init__.py]

importlib.metadata is a library that provides access to the metadata of an installed Distribution Package [https://packaging.python.org/en/latest/glossary/#term-Distribution-Package], such as its entry points or its top-level names (Import Package [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 [https://setuptools.readthedocs.io/en/latest/pkg_resources.html#entry-points] and metadata API [https://setuptools.readthedocs.io/en/latest/pkg_resources.html#metadata-api] of pkg_resources. Along with importlib.resources, this package can eliminate the need to use the older and less efficient pkg_resources package.

importlib.metadata operates on third-party distribution packages installed into Python's site-packages directory via tools such as pip [https://pypi.org/project/pip/]. Specifically, it works with distributions with discoverable dist-info or egg-info directories, and metadata defined by the Core metadata specifications [https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata].

重要

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 package_distributions() to get a mapping between them.

デフォルトでは、配布物のメタデータはファイルシステム上、または sys.path のzipアーカイブに保存されます。拡張機構により、メタデータはほとんどどこにでも置くことができます。

参考

https://importlib-metadata.readthedocs.io/

importlib_metadata のドキュメントは importlib.metadata のバックポートです。これには、このモジュールのクラスと関数の APIリファレンス [https://importlib-metadata.readthedocs.io/en/latest/api.html] と、 pkg_resources の既存のユーザーのための 移行ガイド [https://importlib-metadata.readthedocs.io/en/latest/migration.html] があります。

概要

例えば、pip を使ってインストールした 配布パッケージ [https://packaging.python.org/ja/latest/glossary/#term-Distribution-Package] のバージョン文字列を取得したいとします。 まず、仮想環境を作成し、そこに何かをインストールすることから始めましょう:

$ python -m venv example
$ source example/bin/activate
(example) $ python -m pip install wheel

以下のように実行することで、wheel のバージョン文字列を取得することができます:

(example) $ python
>>> from importlib.metadata import version
>>> version('wheel')
'0.32.3'

また、 console_scripts や distutils.commands などのエントリポイントのプロパティ(通常は 'group' や 'name' )で選択可能なエントリポイントの集合を取得することができます。 各グループは エントリポイント オブジェクトの集合を含んでいます。

ディストリビューションのメタデータ を取得することができます。:

>>> 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']

また、 配布物のバージョン番号 を取得し、 構成ファイル をリストアップし、配布物の 配布物の要件 のリストを取得することができます。

機能 API

本パッケージは、公開APIを通じて以下の機能を提供します。

エントリポイント

entry_points() 関数は、エントリポイントの集合を返します。各 EntryPoint は .name, .group, .value 属性と値を解決する .load() メソッドを持っています。 また、 .value 属性の構成要素を取得するための .module, .attr, .extras 属性が存在します。

すべてのエントリポイントに問い合わせる:

>>> eps = entry_points()

entry_points() 関数は、すべての EntryPoint オブジェクトを集めた EntryPoints オブジェクトを、便宜上 names と groups 属性を付けて返します。

>>> sorted(eps.groups)
['console_scripts', 'distutils.commands', 'distutils.setup_keywords', 'egg_info.writers', 'setuptools.installation']

EntryPoints には、特定のプロパティに一致するエントリポイントを選択するための select メソッドがあります。console_scripts グループ内のエントリポイントを選択する:

>>> scripts = eps.select(group='console_scripts')

Equivalently, since entry_points passes keyword arguments through to select:

>>> scripts = entry_points(group='console_scripts')

"wheel" という名前の特定のスクリプトを選択します。(wheelプロジェクトにあります):

>>> 'wheel' in scripts.names
True
>>> wheel = scripts['wheel']

同様に、選択時にそのエントリポイントを問い合わせます:

>>> (wheel,) = entry_points(group='console_scripts', name='wheel')
>>> (wheel,) = entry_points().select(group='console_scripts', name='wheel')

解決したエントリポイントを検証する:

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

group と name はパッケージの作者によって定義された任意の値で、通常クライアントは特定のグループのエントリポイントを解決したいと思うでしょう。エントリポイント、その他の定義、使用方法についての詳細は setuptoolsのドキュメント [https://setuptools.pypa.io/en/latest/userguide/entry_point.html] を参照してください。

Compatibility Note

The "selectable" entry points were introduced in importlib_metadata 3.6 and Python 3.10. Prior to those changes, entry_points accepted no parameters and always returned a dictionary of entry points, keyed by group. With importlib_metadata 5.0 and Python 3.12, entry_points always returns an EntryPoints object. See backports.entry_points_selectable [https://pypi.org/project/backports.entry_points_selectable/] for compatibility options.

配布物メタデータ

すべての 配布パッケージ [https://packaging.python.org/ja/latest/glossary/#term-Distribution-Package] にはメタデータが含まれており、 metadata() 関数を使って取得することができます:

>>> wheel_metadata = metadata('wheel')

返されたデータ構造である PackageMetadata のキーはメタデータのキーワードを表し、値は配布パッケージのメタデータから解析されずに返されます:

>>> wheel_metadata['Requires-Python']
'>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'

PackageMetadata には json 属性があり、 PEP 566 [https://peps.python.org/pep-0566/] に従ってすべてのメタデータをJSON互換の形式で返します:

>>> wheel_metadata.json['requires_python']
'>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'

注釈

metadata() が返すオブジェクトの実際の型は実装の詳細であり、 PackageMetadataプロトコル [https://importlib-metadata.readthedocs.io/en/latest/api.html#importlib_metadata.PackageMetadata] が示すインターフェースを通じてのみアクセスすることができます。

バージョン 3.10 で変更: ペイロードを通して提示されるとき、 Description がメタデータに含まれるようになりました。行の継続文字は削除されました。

json 属性が追加されました。

配布物バージョン

version() 関数は 配布パッケージ [https://packaging.python.org/ja/latest/glossary/#term-Distribution-Package] のバージョン番号を文字列で取得するもっとも簡単な方法です。:

>>> version('wheel')
'0.32.3'

配布物ファイル

また、配布パッケージに含まれるファイルのフルセットを取得することもできます。files() 関数は 配布パッケージ [https://packaging.python.org/ja/latest/glossary/#term-Distribution-Package] 名を受け取り、この配布パッケージにインストールされているすべてのファイルを返します。返される各ファイルオブジェクトは PackagePath で、 pathlib.PurePath から派生したオブジェクトに、メタデータで示された dist, size, hash プロパティを追加しています。 例えば:

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

ファイルを取得したら、その内容を読むこともできます:

>>> print(util.read_text())
import base64
import sys
...
def as_bytes(s):
    if isinstance(s, text_type):
        return s.encode('utf-8')
    return s

また、 locate メソッドを使用すると、ファイルへの絶対パスを取得することができます:

>>> util.locate()
PosixPath('/home/gustav/example/lib/site-packages/wheel/util.py')

In the case where the metadata file listing files (RECORD or SOURCES.txt) is missing, files() will return None. The caller may wish to wrap calls to files() in always_iterable [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.

配布物の要件

配布パッケージ [https://packaging.python.org/ja/latest/glossary/#term-Distribution-Package] に必要なすべての要件を取得するには、 requires() 関数を使用します:

>>> requires('wheel')
["pytest (>=3.0.0) ; extra == 'test'", "pytest-cov ; extra == 'test'"]

Mapping import to distribution packages

インポート可能なトップレベルのPythonモジュールまたは パッケージ [https://packaging.python.org/ja/latest/glossary/#term-Import-Package] を提供する 配布パッケージ [https://packaging.python.org/en/latest/glossary/#term-Distribution-Package] 名(名前空間パッケージの場合はその名前)を解決する便利なメソッドです:

>>> packages_distributions()
{'importlib_metadata': ['importlib-metadata'], 'yaml': ['PyYAML'], 'jaraco': ['jaraco.classes', 'jaraco.functools'], ...}

Some editable installs, do not supply top-level names [https://github.com/pypa/packaging-problems/issues/609], and thus this function is not reliable with such installs.

Added in version 3.10.

Distributions

上記のAPIは最も一般的で便利な使い方ですが、 Distribution クラスからすべての情報を得ることができます。 Distribution はPython 配布パッケージ [https://packaging.python.org/ja/latest/glossary/#term-Distribution-Package] のメタデータを表す抽象オブジェクトです。 Distribution のインスタンスを取得することができます。

>>> from importlib.metadata import distribution
>>> dist = distribution('wheel')

したがって、バージョン情報を取得する別の方法として、 Distribution インスタンスを使用します:

>>> dist.version
'0.32.3'

Distribution インスタンスには、あらゆる種類の追加メタデータが用意されています:

>>> dist.metadata['Requires-Python']
'>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'
>>> dist.metadata['License']
'MIT'

利用可能なメタデータのフルセットは、ここでは説明しません。詳細は コアとなるメタデータの仕様 [https://packaging.python.org/ja/latest/specifications/core-metadata/#core-metadata] を参照してください。

Distribution Discovery

デフォルトでは、このパッケージは組み込みで、ファイルシステムおよび zip ファイル 配布パッケージ [https://packaging.python.org/ja/latest/glossary/#term-Distribution-Package] のメタデータを発見するためのサポートを提供します。このメタデータ検索のデフォルトは sys.path ですが、その値をどのように解釈するかは、他のインポート機構が行う方法とは若干異なります。具体的には:

importlib.metadata は sys.path の bytes オブジェクトを受け入れません。

importlib.metadata は、インポート時には無視されますが、 sys.path 上の pathlib.Path オブジェクトを優先的に使用します。

検索アルゴリズムの拡張

Because Distribution Package [https://packaging.python.org/en/latest/glossary/#term-Distribution-Package] metadata is not available through sys.path searches, or package loaders directly, the metadata for a distribution is found through import system finders. To find a distribution package's metadata, importlib.metadata queries the list of meta path finders on sys.meta_path.

By default importlib.metadata installs a finder for distribution packages found on the file system. This finder doesn't actually find any distributions, but it can find their metadata.

抽象クラス importlib.abc.MetaPathFinder はPythonの importシステムによってファインダーに期待されるインターフェイスを定義しています。 importlib.metadata はこのプロトコルを拡張し、 sys.meta_path からファインダーにオプションの find_distributions を呼び出すことができるようにし、この拡張インターフェースを DistributionFinder 抽象基底クラスとして提示し、この抽象メソッドを定義しています:

@abc.abstractmethod
def find_distributions(context=DistributionFinder.Context()):
    """Return an iterable of all Distribution instances capable of
    loading the metadata for packages for the indicated ``context``.
    """

DistributionFinder.Context オブジェクトは、検索するパスと一致する名前を示す .path と .name のプロパティを提供し、その他の関連するコンテキストを提供することもできます。

つまり、ファイルシステム以外の場所にある配布パッケージのメタデータを見つけるには、 Distribution をサブクラス化して抽象メソッドを実装します。そして、カスタムファインダーから find_distributions() メソッドで、派生した Distribution のインスタンスを返します。

The initialization of the sys.path module search path

A module search path is initialized when Python starts. This module search path may be accessed at 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 -c command, or -m module.

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

注釈

PYTHONPATH will affect all installed Python versions/environments. Be wary of setting this in your shell profile or global environment variables. The site module offers more nuanced techniques as mentioned below.

The next items added are the directories containing standard Python modules as well as any extension modules that these modules depend on. Extension modules are .pyd files on Windows and .so files on other platforms. The directory with the platform-independent Python modules is called prefix. The directory with the extension modules is called exec_prefix.

The PYTHONHOME environment variable may be used to set the prefix and 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 home.

Once home is determined, the prefix directory is found by first looking for pythonmajorversionminorversion.zip (python311.zip). On Windows the zip archive is searched for in home and on Unix the archive is expected to be in 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 prefix by looking for Lib\os.py. Python on Unix will look for lib/pythonmajorversion.minorversion/os.py (lib/python3.11/os.py). On Windows prefix and exec_prefix are the same, however on other platforms lib/pythonmajorversion.minorversion/lib-dynload (lib/python3.11/lib-dynload) is searched for and used as an anchor for exec_prefix. On some platforms lib may be lib64 or another value, see sys.platlibdir and PYTHONPLATLIBDIR.

Once found, prefix and exec_prefix are available at sys.prefix and sys.exec_prefix respectively.

Finally, the site module is processed and site-packages directories are added to the module search path. A common way to customize the search path is to create sitecustomize or usercustomize modules as described in the site module documentation.

注釈

Certain command line options may further affect path calculations. See -E, -I, -s and -S for further details.

仮想環境 (Virtual environments)

If Python is run in a virtual environment (as described at 仮想環境とパッケージ) then prefix and exec_prefix are specific to the virtual environment.

If a pyvenv.cfg file is found alongside the main executable, or in the directory one level above the executable, the following variations apply:

If home is an absolute path and PYTHONHOME is not set, this path is used instead of the path to the main executable when deducing prefix and exec_prefix.

_pth files

To completely override sys.path create a ._pth file with the same name as the shared library or executable (python._pth or python311._pth). The shared library path is always known on Windows, however it may not be available on other platforms. In the ._pth file specify one line for each path to add to 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.

ファイルが存在したときは、全てのレジストリと環境変数は無視され、隔離モードになり、そのファイルに import site と指定していない限りは site がインポートできなくなります。空行と # で始まる行は無視されます。それぞれのパスはファイルの場所を指す絶対パスあるいは相対パスです。 site 以外のインポート文は許可されておらず、任意のコードも書けません。

import site を指定したときは、(アンダースコアが前に付かない) .pth ファイルは site モジュールにより通常通り処理されることに注意してください。

Embedded Python

If Python is embedded within another application Py_InitializeFromConfig() and the PyConfig structure can be used to initialize Python. The path specific details are described at Python Path Configuration. Alternatively the older Py_SetPath() can be used to bypass the initialization of the module search path.

参考

モジュールの検索 for detailed Windows notes.

Unix プラットフォームで Python を使う for Unix details.

Python言語サービス

PythonにはPython言語を使って作業するときに役に立つモジュールがたくさん提供されています。これらのモジュールはトークンの切り出し、パース、構文解析、バイトコードのディスアセンブリおよびその他のさまざまな機能をサポートしています。

これらのモジュールには、次のものが含まれています:

ast --- Abstract Syntax Trees

抽象文法 (Abstract Grammar)

Node クラス

Root nodes

リテラル

変数

式 (expression)

配列要素の参照 (Subscripting)

内包表記 (Comprehension)

文 (Statements)

インポート

制御フロー

Pattern matching

Type parameters

関数およびクラス定義

async と await

ast ヘルパー

コンパイラフラグ

コマンドラインからの使用

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

記号表の生成

記号表の検査

token --- Constants used with Python parse trees

keyword --- Testing for Python keywords

tokenize --- Tokenizer for Python source

入力のトークナイズ

コマンドラインからの使用

使用例

tabnanny --- Detection of ambiguous indentation

pyclbr --- Python module browser support

Function オブジェクト

クラスオブジェクト

py_compile --- Compile Python source files

コマンドラインインターフェイス

compileall --- Byte-compile Python libraries

コマンドラインでの使用

パブリックな関数

dis --- Disassembler for Python bytecode

コマンドライン・インターフェース

バイトコード解析

解析関数

Python バイトコード命令

命令コードコレクション

pickletools --- Tools for pickle developers

コマンドラインの使い方

コマンドラインオプション

プログラミングインターフェース

ast --- Abstract Syntax Trees

ソースコード: Lib/ast.py [https://github.com/python/cpython/tree/3.12/Lib/ast.py]

ast モジュールは、Python アプリケーションで Python の抽象構文木を処理しやすくするものです。抽象構文そのものは、Python のリリースごとに変化する可能性があります。このモジュールを使用すると、現在の文法をプログラム上で知る助けになるでしょう。

抽象構文木を作成するには、 ast.PyCF_ONLY_AST を組み込み関数 compile() のフラグとして渡すか、あるいはこのモジュールで提供されているヘルパー関数 parse() を使います。その結果は、 ast.AST を継承したクラスのオブジェクトのツリーとなります。抽象構文木は組み込み関数 compile() を使って Python コード・オブジェクトにコンパイルすることができます。

抽象文法 (Abstract Grammar)

抽象文法は、現在次のように定義されています:

-- ASDL's 4 builtin types are:
-- identifier, int, string, constant

module Python
{
    mod = Module(stmt* body, type_ignore* type_ignores)
        | Interactive(stmt* body)
        | Expression(expr body)
        | FunctionType(expr* argtypes, expr returns)

    stmt = FunctionDef(identifier name, arguments args,
                       stmt* body, expr* decorator_list, expr? returns,
                       string? type_comment, type_param* type_params)
          | AsyncFunctionDef(identifier name, arguments args,
                             stmt* body, expr* decorator_list, expr? returns,
                             string? type_comment, type_param* type_params)

          | ClassDef(identifier name,
             expr* bases,
             keyword* keywords,
             stmt* body,
             expr* decorator_list,
             type_param* type_params)
          | Return(expr? value)

          | Delete(expr* targets)
          | Assign(expr* targets, expr value, string? type_comment)
          | TypeAlias(expr name, type_param* type_params, expr value)
          | AugAssign(expr target, operator op, expr value)
          -- 'simple' indicates that we annotate simple name without parens
          | AnnAssign(expr target, expr annotation, expr? value, int simple)

          -- use 'orelse' because else is a keyword in target languages
          | For(expr target, expr iter, stmt* body, stmt* orelse, string? type_comment)
          | AsyncFor(expr target, expr iter, stmt* body, stmt* orelse, string? type_comment)
          | While(expr test, stmt* body, stmt* orelse)
          | If(expr test, stmt* body, stmt* orelse)
          | With(withitem* items, stmt* body, string? type_comment)
          | AsyncWith(withitem* items, stmt* body, string? type_comment)

          | Match(expr subject, match_case* cases)

          | Raise(expr? exc, expr? cause)
          | Try(stmt* body, excepthandler* handlers, stmt* orelse, stmt* finalbody)
          | TryStar(stmt* body, excepthandler* handlers, stmt* orelse, stmt* finalbody)
          | Assert(expr test, expr? msg)

          | Import(alias* names)
          | ImportFrom(identifier? module, alias* names, int? level)

          | Global(identifier* names)
          | Nonlocal(identifier* names)
          | Expr(expr value)
          | Pass | Break | Continue

          -- col_offset is the byte offset in the utf8 string the parser uses
          attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)

          -- BoolOp() can use left & right?
    expr = BoolOp(boolop op, expr* values)
         | NamedExpr(expr target, expr value)
         | BinOp(expr left, operator op, expr right)
         | UnaryOp(unaryop op, expr operand)
         | Lambda(arguments args, expr body)
         | IfExp(expr test, expr body, expr orelse)
         | Dict(expr* keys, expr* values)
         | Set(expr* elts)
         | ListComp(expr elt, comprehension* generators)
         | SetComp(expr elt, comprehension* generators)
         | DictComp(expr key, expr value, comprehension* generators)
         | GeneratorExp(expr elt, comprehension* generators)
         -- the grammar constrains where yield expressions can occur
         | Await(expr value)
         | Yield(expr? value)
         | YieldFrom(expr value)
         -- need sequences for compare to distinguish between
         -- x < 4 < 3 and (x < 4) < 3
         | Compare(expr left, cmpop* ops, expr* comparators)
         | Call(expr func, expr* args, keyword* keywords)
         | FormattedValue(expr value, int conversion, expr? format_spec)
         | JoinedStr(expr* values)
         | Constant(constant value, string? kind)

         -- the following expression can appear in assignment context
         | Attribute(expr value, identifier attr, expr_context ctx)
         | Subscript(expr value, expr slice, expr_context ctx)
         | Starred(expr value, expr_context ctx)
         | Name(identifier id, expr_context ctx)
         | List(expr* elts, expr_context ctx)
         | Tuple(expr* elts, expr_context ctx)

         -- can appear only in Subscript
         | Slice(expr? lower, expr? upper, expr? step)

          -- col_offset is the byte offset in the utf8 string the parser uses
          attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)

    expr_context = Load | Store | Del

    boolop = And | Or

    operator = Add | Sub | Mult | MatMult | Div | Mod | Pow | LShift
                 | RShift | BitOr | BitXor | BitAnd | FloorDiv

    unaryop = Invert | Not | UAdd | USub

    cmpop = Eq | NotEq | Lt | LtE | Gt | GtE | Is | IsNot | In | NotIn

    comprehension = (expr target, expr iter, expr* ifs, int is_async)

    excepthandler = ExceptHandler(expr? type, identifier? name, stmt* body)
                    attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)

    arguments = (arg* posonlyargs, arg* args, arg? vararg, arg* kwonlyargs,
                 expr* kw_defaults, arg? kwarg, expr* defaults)

    arg = (identifier arg, expr? annotation, string? type_comment)
           attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)

    -- keyword arguments supplied to call (NULL identifier for **kwargs)
    keyword = (identifier? arg, expr value)
               attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)

    -- import name with optional 'as' alias.
    alias = (identifier name, identifier? asname)
             attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)

    withitem = (expr context_expr, expr? optional_vars)

    match_case = (pattern pattern, expr? guard, stmt* body)

    pattern = MatchValue(expr value)
            | MatchSingleton(constant value)
            | MatchSequence(pattern* patterns)
            | MatchMapping(expr* keys, pattern* patterns, identifier? rest)
            | MatchClass(expr cls, pattern* patterns, identifier* kwd_attrs, pattern* kwd_patterns)

            | MatchStar(identifier? name)
            -- The optional "rest" MatchMapping parameter handles capturing extra mapping keys

            | MatchAs(pattern? pattern, identifier? name)
            | MatchOr(pattern* patterns)

             attributes (int lineno, int col_offset, int end_lineno, int end_col_offset)

    type_ignore = TypeIgnore(int lineno, string tag)

    type_param = TypeVar(identifier name, expr? bound)
               | ParamSpec(identifier name)
               | TypeVarTuple(identifier name)
               attributes (int lineno, int col_offset, int end_lineno, int end_col_offset)
}

Node クラス

class ast.AST

This is the base of all AST node classes. The actual node classes are derived from the Parser/Python.asdl file, which is reproduced above. They are defined in the _ast C module and re-exported in ast.

抽象文法の左辺のシンボル一つずつにそれぞれ一つのクラスがあります (たとえば ast.stmt や ast.expr)。それに加えて、右辺のコンストラクタ一つずつにそれぞれ一つのクラスがあり、これらのクラスは左辺のツリーのクラスを継承しています。たとえば、 ast.BinOp は ast.expr から継承しています。代替を伴った生成規則 (production rules with alternatives) (別名 "sums") の場合、左辺は抽象クラスとなり、特定のコンストラクタ・ノードのインスタンスのみが作成されます。

_fields

Each concrete class has an attribute _fields which gives the names of all child nodes.

具象クラスのインスタンスは、各子ノードに対してそれぞれひとつの属性を持っています。この属性は、文法で定義された型となります。たとえば ast.BinOp のインスタンスは left という属性を持っており、その型は ast.expr です。

これらの属性が、文法上 (クエスチョンマークを用いて) オプションであるとマークされている場合は、その値が None となることもあります。属性が0個以上の複数の値をとりうる場合 (アスタリスクでマークされている場合) は、値は Python のリストで表されます。全ての属性は AST を compile() でコンパイルする際には存在しなければならず、そして妥当な値でなければなりません。

lineno

col_offset

end_lineno

end_col_offset

ast.expr や ast.stmt のサブクラスのインスタンスは lineno, col_offset, end_lineno, および end_col_offset 属性を持ちます。 lineno と end_lineno はソーステキストの範囲を最初と最後の行番号で表し (1 から数え始めるので、最初の行の行番号は 1 となります)、 col_offset と end_col_offset はノードが生成した最初と最後のトークンの UTF-8 バイトオフセットです。 UTF-8 オフセットはパーサが内部で使用するので記録されます。

コンパイラは終了位置を必要としないことに注意してください。このため終了位置は省略可能です。終了位置を示すオフセットは最後のシンボルの 後の位置 になります。例えば一行で書かれた式のソースコードのセグメントは source_line[node.col_offset : node.end_col_offset] により取得できます。

クラス ast.T のコンストラクタは引数を次のように解析します:

位置引数があるとすれば、 T._fields にあるのと同じだけの個数が無ければなりません。これらの引数はそこにある名前を持った属性として割り当てられます。

キーワード引数があるとすれば、それらはその名前の属性にその値を割り当てられます。

たとえば、 ast.UnaryOp ノードを生成して属性を埋めるには、次のようにすることができます

node = ast.UnaryOp()
node.op = ast.USub()
node.operand = ast.Constant()
node.operand.value = 5
node.operand.lineno = 0
node.operand.col_offset = 0
node.lineno = 0
node.col_offset = 0

or the more compact

node = ast.UnaryOp(ast.USub(), ast.Constant(5, lineno=0, col_offset=0),
                   lineno=0, col_offset=0)

バージョン 3.8 で変更: ast.Constant が全ての定数に使われるようになりました。

バージョン 3.9 で変更: 単純なインデックスはその値で表現され、幅を持つスライスはタプルで表現されます。

バージョン 3.8 で非推奨: Old classes ast.Num, ast.Str, ast.Bytes, ast.NameConstant and ast.Ellipsis are still available, but they will be removed in future Python releases. In the meantime, instantiating them will return an instance of a different class.

バージョン 3.9 で非推奨: Old classes ast.Index and ast.ExtSlice are still available, but they will be removed in future Python releases. In the meantime, instantiating them will return an instance of a different class.

注釈

ここに示されている特定のノードクラスについての記述は、素晴らしい Green Tree Snakes [https://greentreesnakes.readthedocs.io/en/latest/] プロジェクトとそのすべての貢献者の成果物をもとにしています。

Root nodes

class ast.Module(body, type_ignores)

A Python module, as with file input. Node type generated by ast.parse() in the default "exec" mode.

body is a list of the module's 文 (Statements).

type_ignores is a list of the module's type ignore comments; see ast.parse() for more details.

>>> print(ast.dump(ast.parse('x = 1'), indent=4))
Module(
    body=[
        Assign(
            targets=[
                Name(id='x', ctx=Store())],
            value=Constant(value=1))],
    type_ignores=[])

class ast.Expression(body)

A single Python expression input. Node type generated by ast.parse() when mode is "eval".

body is a single node, one of the expression types.

>>> print(ast.dump(ast.parse('123', mode='eval'), indent=4))
Expression(
    body=Constant(value=123))

class ast.Interactive(body)

A single interactive input, like in 対話モード. Node type generated by ast.parse() when mode is "single".

body is a list of statement nodes.

>>> 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))])

class ast.FunctionType(argtypes, returns)

A representation of an old-style type comments for functions, as Python versions prior to 3.5 didn't support PEP 484 [https://peps.python.org/pep-0484/] annotations. Node type generated by ast.parse() when mode is "func_type".

Such type comments would look like this:

def sum_two_number(a, b):
    # type: (int, int) -> int
    return a + b

argtypes is a list of expression nodes.

returns is a single expression node.

>>> 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()))

Added in version 3.8.

リテラル

class ast.Constant(value)

定数です。 Constant リテラルの value 属性は定数値を表す Python オブジェクトを保持します。定数として表現される値は数値、文字列、または None のような単純な型のほかに、全ての要素が定数であるイミュータブルなコンテナ型 (tuples および frozensets) も設定可能です。

>>> print(ast.dump(ast.parse('123', mode='eval'), indent=4))
Expression(
    body=Constant(value=123))

class ast.FormattedValue(value, conversion, format_spec)

このノードは f-string における単一の書式指定置換フィールドを表現します。文字列が単一の置換フィールドしか持たず、他に何も含まない場合は、ノードは単独で存在できます。そうでない場合は JoinedStr の一部としてあらわれます。

value は式ツリーのノードのいずれか (リテラル、変数、関数呼び出しなど) です。

conversion は整数です:

-1: 書式指定なし

115: !s 文字列書式指定

114: !r repr 書式指定

97: !a ascii 書式指定

format_spec は値の書式指定を表現する JoinedStr ノード、もしくは書式指定がない場合は None です。 conversion と format_spec を同時に設定することができます。

class ast.JoinedStr(values)

FormattedValue ノードと Constant ノードの集まりからなる f-string です。

>>> 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())],
                    keywords=[]),
                conversion=-1,
                format_spec=JoinedStr(
                    values=[
                        Constant(value='.3')]))]))

class ast.List(elts, ctx)

class ast.Tuple(elts, ctx)

リストまたはタプルをあらわします。 elts は内包する要素を表現するノードのリストを保持します。 ctx はコンテナが代入のターゲットである場合 (たとえば (x,y)=something のような場合) は Store であり、そうでない場合は Load です。

>>> 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()))

class ast.Set(elts)

集合 (set) をあらわします。 elts は集合の各要素を表現するノードのリストを保持します。

>>> 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)]))

class ast.Dict(keys, values)

辞書をあらわします。 keys と values はそれぞれキーと値のノードのリスト を順序が一致した形で (それぞれ dictionary.keys() と dictionary.values() を呼び出したときに返される順序で) 保持します。

辞書リテラルを使って辞書を展開した場合、展開された式ツリーにおいて辞書は values リストに入り、 keys の対応する位置には None が入ります。

>>> 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())]))

変数

class ast.Name(id, ctx)

変数名をあらわします。 id は変数名を文字列で保持し、 ctx は以下に示す型のいずれかです。

class ast.Load

class ast.Store

class ast.Del

変数の参照は変数の値をロードするか、新しい値を割り当てるか、または値を削除するために使うことができます。変数の参照はこれら3つの場合を区別するためのコンテキストによって与えられます。

>>> print(ast.dump(ast.parse('a'), indent=4))
Module(
    body=[
        Expr(
            value=Name(id='a', ctx=Load()))],
    type_ignores=[])

>>> print(ast.dump(ast.parse('a = 1'), indent=4))
Module(
    body=[
        Assign(
            targets=[
                Name(id='a', ctx=Store())],
            value=Constant(value=1))],
    type_ignores=[])

>>> print(ast.dump(ast.parse('del a'), indent=4))
Module(
    body=[
        Delete(
            targets=[
                Name(id='a', ctx=Del())])],
    type_ignores=[])

class ast.Starred(value, ctx)

*var 形式の変数の参照をあらわします。 value は変数、典型的には Name ノード、を保持します。この型は *args を伴う関数呼び出しノード Call を構築する際に使用します。

>>> 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()))],
    type_ignores=[])

式 (expression)

class ast.Expr(value)

関数呼び出しのような式がそれ自身で文となり、戻り値が使われないかまたは保存されないとき、その式はこのコンテナでラップされます。 value はこの節で説明する他のノード、 Constant ノード、 Name ノード、 Lambda ノード Yield ノードまたは YieldFrom ノードのいずれかを保持します。

>>> print(ast.dump(ast.parse('-a'), indent=4))
Module(
    body=[
        Expr(
            value=UnaryOp(
                op=USub(),
                operand=Name(id='a', ctx=Load())))],
    type_ignores=[])

class ast.UnaryOp(op, operand)

単項演算をあらわします。 op は演算子で、 operand は任意の式ツリーのノードです。

class ast.UAdd

class ast.USub

class ast.Not

class ast.Invert

単項演算の演算子をあらわします。 Not は論理否定キーワード not であり、 Invert はビット反転演算子 ~ です。

>>> print(ast.dump(ast.parse('not x', mode='eval'), indent=4))
Expression(
    body=UnaryOp(
        op=Not(),
        operand=Name(id='x', ctx=Load())))

class ast.BinOp(left, op, right)

(加算や減算のような) 二項演算をあらわします。 op は演算子、 left と right は任意の式ツリーのノードです。

>>> 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())))

class ast.Add

class ast.Sub

class ast.Mult

class ast.Div

class ast.FloorDiv

class ast.Mod

class ast.Pow

class ast.LShift

class ast.RShift

class ast.BitOr

class ast.BitXor

class ast.BitAnd

class ast.MatMult

二項演算の演算子をあらわします。

class ast.BoolOp(op, values)

'or' や 'and' のような論理演算をあらわします。 op は Or または And です。 values は必要な値のリストです。 a or b or c のように同じ演算子を使う連続した演算は、複数の値を持った単一のノードとして表現されます。

not は単項演算 UnaryOp のため、ここには含まれません。

>>> 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())]))

class ast.And

class ast.Or

論理演算の演算子をあらわします。

class ast.Compare(left, ops, comparators)

2つ以上の値の比較をあらわします。 left 比較の中の最初の値、ops は演算子のリスト、 comparators は2つ目以降の値のリストです。

>>> 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)]))

class ast.Eq

class ast.NotEq

class ast.Lt

class ast.LtE

class ast.Gt

class ast.GtE

class ast.Is

class ast.IsNot

class ast.In

class ast.NotIn

比較演算の演算子をあらわします。

class ast.Call(func, args, keywords)

関数呼び出しをあらわします。 func は関数で、多くの場合 Name または Attribute のオブジェクトです。 関数呼び出しの引数:

args は位置引数のリストを保持します。

keywords holds a list of keyword objects representing arguments passed by keyword.

When creating a Call node, args and keywords are required, but they can be empty lists.

>>> 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()))]))

class ast.keyword(arg, value)

関数呼び出しまたはクラス定義のキーワード引数をあらわします。 arg はパラメータ名をあらわす文字列、 value は引数に渡す値をあらわすノードです。

class ast.IfExp(test, body, orelse)

a if b else c のような式をあらわします。各フィールドは単一のノードを保持します。以下の例では、3つの式ノードはすべて Name ノードです。

>>> 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())))

class ast.Attribute(value, attr, ctx)

たとえば d.keys のような属性へのアクセスです。 value はノードで、典型的には Name です。 attr は属性名を与える生の文字列で、 ctx はその属性がどのように振る舞うかに応じて Load、 Store または Del のいずれかです。

>>> print(ast.dump(ast.parse('snake.colour', mode='eval'), indent=4))
Expression(
    body=Attribute(
        value=Name(id='snake', ctx=Load()),
        attr='colour',
        ctx=Load()))

class ast.NamedExpr(target, value)

代入式です。この AST ノードは代入式演算子（ウォルラス演算子、または「セイウチ演算子」としても知られています）によって生成されます。第一引数が複数のノードであってもよい Assign ノードと異なり、このノードの場合は target と value の両方が単一のノードでなければなりません。

>>> print(ast.dump(ast.parse('(x := 4)', mode='eval'), indent=4))
Expression(
    body=NamedExpr(
        target=Name(id='x', ctx=Store()),
        value=Constant(value=4)))

Added in version 3.8.

配列要素の参照 (Subscripting)

class ast.Subscript(value, slice, ctx)

l[1] のような配列要素の参照をあらわします。 value は参照元のオブジェクトです (通常シーケンス型またはマッピング型)。 slice はインデックス、スライス、またはキーです。 Slice を含む Tuple でもかまいません。 ctx は要素の参照により実行されるアクションに応じて Load、 Store または Del のいずれかです。

>>> 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()))

class ast.Slice(lower, upper, step)

基本的なスライス操作 (lower:upper や lower:upper:step の形式) をあらわします。 Subscript の slice フィールドでの直接指定か、または Tuple の要素として指定する場合のみ利用可能です。

>>> 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()))

内包表記 (Comprehension)

class ast.ListComp(elt, generators)

class ast.SetComp(elt, generators)

class ast.GeneratorExp(elt, generators)

class ast.DictComp(key, value, generators)

リストや集合の内包表記、ジェネレータ、および辞書の内包表記です。 elt (または key と value) は各要素として評価される部品をあらわす単一のノードです。

generators は comprehension ノードのリストです。

>>> 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()),
                ifs=[],
                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()),
                ifs=[],
                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()),
                ifs=[],
                is_async=0)]))

class ast.comprehension(target, iter, ifs, is_async)

内包表記におけるひとつの for 節をあらわします。 target は各要素への参照です - 典型的には Name または Tuple ノードです。 iter はイテレートする対象のオブジェクトです。 ifs は条件節のリストです: 各 for 節は複数の ifs を持つことができます。

is_async は内包表記が非同期であることを示します (async for を for の代わりに使います)。値は整数です (0 または 1)。

>>> 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())],
            keywords=[]),
        generators=[
            comprehension(
                target=Name(id='line', ctx=Store()),
                iter=Name(id='file', ctx=Load()),
                ifs=[],
                is_async=0),
            comprehension(
                target=Name(id='c', ctx=Store()),
                iter=Name(id='line', ctx=Load()),
                ifs=[],
                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()),
                ifs=[],
                is_async=1)]))

文 (Statements)

class ast.Assign(targets, value, type_comment)

代入です。 targets はノードのリスト、 value は単一のノードです。

targets の複数のノードは、それぞれに対して同じ値を代入することをあらわします。分割代入は targets 内に Tuple または List を置くことで表現されます。

type_comment

type_comment はコメントとして型アノテーションをあらわすオプション文字列です。

>>> 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))],
    type_ignores=[])

>>> 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()))],
    type_ignores=[])

class ast.AnnAssign(target, annotation, value, simple)

型アノテーションを伴う代入です。 target は単一のノードで、 Name, Attribute または Subscript のいずれかです。 annotation は Constant や Name node のようなアノテーションです。 value はオプションで、代入する値を単一のノードであらわしたものです。 simple 真偽値と解釈される整数で、 target の Name ノードが丸かっこに囲まれておらず、したがって式ではなく純粋な名前である場合に True を設定します。

>>> 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)],
    type_ignores=[])

>>> 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)],
    type_ignores=[])

>>> 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)],
    type_ignores=[])

>>> 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)],
    type_ignores=[])

class ast.AugAssign(target, op, value)

a += 1 のような累積代入をあらわします。下記の例では、 target は (Store コンテキストを伴う) x のための Name ノード、 op は Add 演算子、そして value は定数1をあらわす Constant ノードです。

Assign と異なり、 target 属性は class Tuple や List であってはいけません。

>>> print(ast.dump(ast.parse('x += 2'), indent=4))
Module(
    body=[
        AugAssign(
            target=Name(id='x', ctx=Store()),
            op=Add(),
            value=Constant(value=2))],
    type_ignores=[])

class ast.Raise(exc, cause)

raise 文をあらわします。 exc は送出される例外オブジェクトで、通常は Call または Name、 もしくは単独の raise では None を指定します。 cause はオプションで、 raise x from y の y にあたります。

>>> 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()))],
    type_ignores=[])

class ast.Assert(test, msg)

アサーションです。 test は Compare ノードなどのような条件を保持します。 msg は失敗した時のメッセージを保持します。

>>> 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()))],
    type_ignores=[])

class ast.Delete(targets)

del 文をあらわします。 targets は Name, Attribute, Subscript などのノードのリストです。

>>> 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())])],
    type_ignores=[])

class ast.Pass

pass 文をあらわします。

>>> print(ast.dump(ast.parse('pass'), indent=4))
Module(
    body=[
        Pass()],
    type_ignores=[])

class ast.TypeAlias(name, type_params, value)

A type alias created through the type statement. name is the name of the alias, type_params is a list of type parameters, and value is the value of the type alias.

>>> print(ast.dump(ast.parse('type Alias = int'), indent=4))
Module(
    body=[
        TypeAlias(
            name=Name(id='Alias', ctx=Store()),
            type_params=[],
            value=Name(id='int', ctx=Load()))],
    type_ignores=[])

Added in version 3.12.

関数またはループの内部でのみ適用可能な他の文は、別のセクションで説明します。

インポート

class ast.Import(names)

インポート文です。 names は alias ノードのリストです。

>>> print(ast.dump(ast.parse('import x,y,z'), indent=4))
Module(
    body=[
        Import(
            names=[
                alias(name='x'),
                alias(name='y'),
                alias(name='z')])],
    type_ignores=[])

class ast.ImportFrom(module, names, level)

from x import y をあらわします。 module は 'from' でインポートする先頭がドットでないモジュール名をあらわす文字列か、または from . import foo のような構文の場合は None を指定します。 level は相対インポートのレベルを表す整数を保持します (0 は絶対インポートを意味します)。

>>> 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)],
    type_ignores=[])

class ast.alias(name, asname)

いずれのパラメータも名前をあらわす生の文字列です。 asname は標準の名前を使う場合は None を指定できます。

>>> 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)],
    type_ignores=[])

制御フロー

注釈

else 節のようなオプションの節が存在しない場合は、空のリストとして保存されます。

class ast.If(test, body, orelse)

if 文です。 test は Compare ノードなどの単一のノードを保持します。 body と orelse はそれぞれノードのリストを保持します。

elif 節は AST において固有の表現を持たず、先行する節をあらわすノードの orelse セクションに追加の If ノードとして現れます。

>>> 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))])])],
    type_ignores=[])

class ast.For(target, iter, body, orelse, type_comment)

A for loop. target holds the variable(s) the loop assigns to, as a single Name, Tuple, List, Attribute or Subscript node. iter holds the item to be looped over, again as a single node. body and orelse contain lists of nodes to execute. Those in orelse are executed if the loop finishes normally, rather than via a break statement.

type_comment

type_comment はコメントとして型アノテーションをあらわすオプション文字列です。

>>> 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))])],
    type_ignores=[])

class ast.While(test, body, orelse)

while ループです。 test は Compare のような条件をあらわすノードを保持します。

>> 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))])],
    type_ignores=[])

class ast.Break

class ast.Continue

break 文および continue 文です。

>>> 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()])],
            orelse=[])],
    type_ignores=[])

class ast.Try(body, handlers, orelse, finalbody)

try ブロックです。 ExceptHandler ノードのリストである handlers を除き、全ての属性はそれぞれの節で実行するノードのリストです。

>>> 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))])],
    type_ignores=[])

class ast.TryStar(body, handlers, orelse, finalbody)

try blocks which are followed by except* clauses. The attributes are the same as for Try but the ExceptHandler nodes in handlers are interpreted as except* blocks rather then except.

>>> 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))])],
            orelse=[],
            finalbody=[])],
    type_ignores=[])

Added in version 3.11.

class ast.ExceptHandler(type, name, body)

単一の except 節をあらわします。 type はこの節にマッチする例外のタイプで、典型的には Name ノードです (None を指定すると全ての例外をキャッチする except: 節をあらわします)。 name は例外オブジェクトを保持する変数の名前をあらわす生の文字列で、 as foo を持たない節の場合は None を指定します。 body はノードのリストです。

>>> 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()])],
            orelse=[],
            finalbody=[])],
    type_ignores=[])

class ast.With(items, body, type_comment)

with ブロックです。 items は withitem ノードのリストで、コンテキストマネージャのリストをあらわします。また body はコンテキスト内にインデントされたブロックです。

type_comment

type_comment はコメントとして型アノテーションをあらわすオプション文字列です。

class ast.withitem(context_expr, optional_vars)

with ブロックにおける単一のコンテキストマネージャをあらわします。 context_expr はコンテキストマネージャで、しばしば Call ノードが設定されます。 optional_vars は as foo に相当する Name, Tuple または List のいずれかのノードか、または、この部分が不要な場合は None を設定します。

>>> 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())],
                        keywords=[]))])],
    type_ignores=[])

Pattern matching

class ast.Match(subject, cases)

A match statement. subject holds the subject of the match (the object that is being matched against the cases) and cases contains an iterable of match_case nodes with the different cases.

Added in version 3.10.

class ast.match_case(pattern, guard, body)

A single case pattern in a match statement. pattern contains the match pattern that the subject will be matched against. Note that the AST nodes produced for patterns differ from those produced for expressions, even when they share the same syntax.

The guard attribute contains an expression that will be evaluated if the pattern matches the subject.

body contains a list of nodes to execute if the pattern matches and the result of evaluating the guard expression is true.

>>> 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()),
                        patterns=[],
                        kwd_attrs=[],
                        kwd_patterns=[]),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])],
    type_ignores=[])

Added in version 3.10.

class ast.MatchValue(value)

A match literal or value pattern that compares by equality. value is an expression node. Permitted value nodes are restricted as described in the match statement documentation. This pattern succeeds if the match subject is equal to the evaluated value.

>>> 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))])])],
    type_ignores=[])

Added in version 3.10.

class ast.MatchSingleton(value)

A match literal pattern that compares by identity. value is the singleton to be compared against: None, True, or False. This pattern succeeds if the match subject is the given constant.

>>> 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))])])],
    type_ignores=[])

Added in version 3.10.

class ast.MatchSequence(patterns)

A match sequence pattern. patterns contains the patterns to be matched against the subject elements if the subject is a sequence. Matches a variable length sequence if one of the subpatterns is a MatchStar node, otherwise matches a fixed length sequence.

>>> 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))])])],
    type_ignores=[])

Added in version 3.10.

class ast.MatchStar(name)

Matches the rest of the sequence in a variable length match sequence pattern. If name is not None, a list containing the remaining sequence elements is bound to that name if the overall sequence pattern is successful.

>>> 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))])])],
    type_ignores=[])

Added in version 3.10.

class ast.MatchMapping(keys, patterns, rest)

A match mapping pattern. keys is a sequence of expression nodes. patterns is a corresponding sequence of pattern nodes. rest is an optional name that can be specified to capture the remaining mapping elements. Permitted key expressions are restricted as described in the match statement documentation.

This pattern succeeds if the subject is a mapping, all evaluated key expressions are present in the mapping, and the value corresponding to each key matches the corresponding subpattern. If rest is not None, a dict containing the remaining mapping elements is bound to that name if the overall mapping pattern is successful.

>>> 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(keys=[], patterns=[], rest='rest'),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])],
    type_ignores=[])

Added in version 3.10.

class ast.MatchClass(cls, patterns, kwd_attrs, kwd_patterns)

A match class pattern. cls is an expression giving the nominal class to be matched. patterns is a sequence of pattern nodes to be matched against the class defined sequence of pattern matching attributes. kwd_attrs is a sequence of additional attributes to be matched (specified as keyword arguments in the class pattern), kwd_patterns are the corresponding patterns (specified as keyword values in the class pattern).

This pattern succeeds if the subject is an instance of the nominated class, all positional patterns match the corresponding class-defined attributes, and any specified keyword attributes match their corresponding pattern.

Note: classes may define a property that returns self in order to match a pattern node against the instance being matched. Several builtin types are also matched that way, as described in the match statement documentation.

>>> 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))],
                        kwd_attrs=[],
                        kwd_patterns=[]),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))]),
                match_case(
                    pattern=MatchClass(
                        cls=Name(id='Point3D', ctx=Load()),
                        patterns=[],
                        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))])])],
    type_ignores=[])

Added in version 3.10.

class ast.MatchAs(pattern, name)

A match "as-pattern", capture pattern or wildcard pattern. pattern contains the match pattern that the subject will be matched against. If the pattern is None, the node represents a capture pattern (i.e a bare name) and will always succeed.

The name attribute contains the name that will be bound if the pattern is successful. If name is None, pattern must also be None and the node represents the wildcard pattern.

>>> 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))])])],
    type_ignores=[])

Added in version 3.10.

class ast.MatchOr(patterns)

A match "or-pattern". An or-pattern matches each of its subpatterns in turn to the subject, until one succeeds. The or-pattern is then deemed to succeed. If none of the subpatterns succeed the or-pattern fails. The patterns attribute contains a list of match pattern nodes that will be matched against the subject.

>>> 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))])])],
    type_ignores=[])

Added in version 3.10.

Type parameters

Type parameters can exist on classes, functions, and type aliases.

class ast.TypeVar(name, bound)

A typing.TypeVar. name is the name of the type variable. bound is the bound or constraints, if any. If bound is a Tuple, it represents constraints; otherwise it represents the bound.

>>> print(ast.dump(ast.parse("type Alias[T: int] = list[T]"), indent=4))
Module(
    body=[
        TypeAlias(
            name=Name(id='Alias', ctx=Store()),
            type_params=[
                TypeVar(
                    name='T',
                    bound=Name(id='int', ctx=Load()))],
            value=Subscript(
                value=Name(id='list', ctx=Load()),
                slice=Name(id='T', ctx=Load()),
                ctx=Load()))],
    type_ignores=[])

Added in version 3.12.

class ast.ParamSpec(name)

A typing.ParamSpec. name is the name of the parameter specification.

>>> print(ast.dump(ast.parse("type Alias[**P] = Callable[P, int]"), indent=4))
Module(
    body=[
        TypeAlias(
            name=Name(id='Alias', ctx=Store()),
            type_params=[
                ParamSpec(name='P')],
            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()))],
    type_ignores=[])

Added in version 3.12.

class ast.TypeVarTuple(name)

A typing.TypeVarTuple. name is the name of the type variable tuple.

>>> 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')],
            value=Subscript(
                value=Name(id='tuple', ctx=Load()),
                slice=Tuple(
                    elts=[
                        Starred(
                            value=Name(id='Ts', ctx=Load()),
                            ctx=Load())],
                    ctx=Load()),
                ctx=Load()))],
    type_ignores=[])

Added in version 3.12.

関数およびクラス定義

class ast.FunctionDef(name, args, body, decorator_list, returns, type_comment, type_params)

関数定義です。

name は関数名をあらわす生の文字列です。

args は引数をあらわす arguments ノードです。

body は関数の本体をあらわすノードのリストです。

decorator_list は関数に適用されるデコレータのリストで、外側のデコレータがリストの先頭に保存されます (すなわち、リストの先頭にあるデコレータが最後に適用されます)。

returns は戻り値に対する注釈です。

type_params is a list of type parameters.

type_comment

type_comment はコメントとして型アノテーションをあらわすオプション文字列です。

バージョン 3.12 で変更: Added type_params.

class ast.Lambda(args, body)

lambda は式の中で使うことができる最小限の関数定義です。 FunctionDef ノードと異なり、 body は単一のノードとなります。

>>> print(ast.dump(ast.parse('lambda x,y: ...'), indent=4))
Module(
    body=[
        Expr(
            value=Lambda(
                args=arguments(
                    posonlyargs=[],
                    args=[
                        arg(arg='x'),
                        arg(arg='y')],
                    kwonlyargs=[],
                    kw_defaults=[],
                    defaults=[]),
                body=Constant(value=Ellipsis)))],
    type_ignores=[])

class ast.arguments(posonlyargs, args, vararg, kwonlyargs, kw_defaults, kwarg, defaults)

関数の引数

posonlyargs, args および kwonlyargs はそれぞれ arg ノードのリストです。

vararg と kwarg はそれぞれ単一の arg ノードで、 *args, **kwargs パラメータに相当します。

kw_defaults はキーワード専用引数に対するデフォルト値のリストです。値が None の場合、対応する引数は必須となります。

defaults は位置引数として渡すことのできる引数に対するデフォルト値のリストです。デフォルト値の数nが位置引数の数より少ない場合、それらは最後のn個の引数に割り当てられます。

class ast.arg(arg, annotation, type_comment)

A single argument in a list. arg is a raw string of the argument name; annotation is its annotation, such as a Name node.

type_comment

type_comment はコメントとして型アノテーションをあらわすオプション文字列です。

>>> 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(
                posonlyargs=[],
                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'),
            type_params=[])],
    type_ignores=[])

class ast.Return(value)

return 文です。

>>> print(ast.dump(ast.parse('return 4'), indent=4))
Module(
    body=[
        Return(
            value=Constant(value=4))],
    type_ignores=[])

class ast.Yield(value)

class ast.YieldFrom(value)

yield または yield from 式をあらわします。これらは式なので、送り返される値が使われない場合は Expr ノードでラップされなければなりません。

>>> print(ast.dump(ast.parse('yield x'), indent=4))
Module(
    body=[
        Expr(
            value=Yield(
                value=Name(id='x', ctx=Load())))],
    type_ignores=[])

>>> print(ast.dump(ast.parse('yield from x'), indent=4))
Module(
    body=[
        Expr(
            value=YieldFrom(
                value=Name(id='x', ctx=Load())))],
    type_ignores=[])

class ast.Global(names)

class ast.Nonlocal(names)

global および nonlocal 文です。 names は生の文字列のリストです。

>>> print(ast.dump(ast.parse('global x,y,z'), indent=4))
Module(
    body=[
        Global(
            names=[
                'x',
                'y',
                'z'])],
    type_ignores=[])

>>> print(ast.dump(ast.parse('nonlocal x,y,z'), indent=4))
Module(
    body=[
        Nonlocal(
            names=[
                'x',
                'y',
                'z'])],
    type_ignores=[])

class ast.ClassDef(name, bases, keywords, body, decorator_list, type_params)

クラス定義です。

name はクラス名をあらわす生の文字列です。

bases は明示的に指定された基底クラスをあらわすノードのリストです。

keywords is a list of keyword nodes, principally for 'metaclass'. Other keywords will be passed to the metaclass, as per PEP-3115 [https://peps.python.org/pep-3115/].

body はクラス定義に含まれるコードをあらわすノードのリストです。

decorator_list はノードのリストで、関数定義 FunctionDef の場合と同様に解釈されます。

type_params is a list of type parameters.

>>> 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())],
            type_params=[])],
    type_ignores=[])

バージョン 3.12 で変更: Added type_params.

async と await

class ast.AsyncFunctionDef(name, args, body, decorator_list, returns, type_comment, type_params)

async def 形式の関数定義です。通常の関数定義 FunctionDef と同じフィールドを持ちます。

バージョン 3.12 で変更: Added type_params.

class ast.Await(value)

await 式をあらわします。 value は待ち受ける値です。 AsyncFunctionDef の本体 (body) の中でのみ有効です。

>>> print(ast.dump(ast.parse("""\
... async def f():
...     await other_func()
... """), indent=4))
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=[])

class ast.AsyncFor(target, iter, body, orelse, type_comment)

class ast.AsyncWith(items, body, type_comment)

async for ループと async with コンテキストマネージャです。それぞれ For および With と同じフィールドを持ちます。 AsyncFunctionDef の本体 (body) の中でのみ有効です。

注釈

文字列が ast.parse() によってパースされたとき、戻り値のツリーに含まれる演算子ノード (ast.operator, ast.unaryop, ast.cmpop, ast.boolop および ast.expr_context のサブクラス) はシングルトンです。したがっていずれかの演算子ノードを変更すると、その変更は他の全ての同じ値 (たとえば ast.Add ノードを変更した場合はその他全ての ast.Add ノード) に反映されます。

ast ヘルパー

ノード・クラスの他に、 ast モジュールは以下のような抽象構文木をトラバースするためのユーティリティ関数やクラスも定義しています:

ast.parse(source, filename='<unknown>', mode='exec', *, type_comments=False, feature_version=None)

Parse the source into an AST node. Equivalent to compile(source, filename, mode, ast.PyCF_ONLY_AST).

type_comments=True が与えられると、パーサは PEP 484 [https://peps.python.org/pep-0484/] および PEP 526 [https://peps.python.org/pep-0526/] で規定された型コメントをチェックし、返すように修正されます。これは ast.PyCF_TYPE_COMMENTS を追加したフラグを compile() に渡すことと等価です。パーサは不適切な場所に配置された型コメントに対してシンタックスエラーをレポートします。 このフラグがない場合、型コメントは無視されて AST ノードの type_comment フィールドは常に None になります。さらに、 # type: ignore コメントの位置は Module の type_ignores 属性として返されます (それ以外の場合は常に空のリストになります)。

さらに mode が 'func_type' の場合、入力構文は、たとえば (str, int) -> List[str] のような PEP 484 [https://peps.python.org/pep-0484/] の "シグネチャ型コメント (signature type comments)" に対応するように修正されます。

Setting feature_version to a tuple (major, minor) will result in a "best-effort" attempt to parse using that Python version's grammar. For example, setting feature_version=(3, 9) will attempt to disallow parsing of match statements. Currently major must equal to 3. The lowest supported version is (3, 4) (and this may increase in future Python versions); the highest is sys.version_info[0:2]. "Best-effort" attempt means there is no guarantee that the parse (or success of the parse) is the same as when run on the Python version corresponding to feature_version.

If source contains a null character (\0), ValueError is raised.

警告

Note that successfully parsing source code into an AST object doesn't guarantee that the source code provided is valid Python code that can be executed as the compilation step can raise further SyntaxError exceptions. For instance, the source return 42 generates a valid AST node for a return statement, but it cannot be compiled alone (it needs to be inside a function node).

In particular, ast.parse() won't do any scoping checks, which the compilation step does.

警告

十分に大きい文字列や複雑な文字列によって Python の抽象構文木コンパイラのスタックの深さの限界を越えることで、 Python インタプリタをクラッシュさせることができます。

バージョン 3.8 で変更: type_comments、mode='func_type'、feature_version が追加されました。

ast.unparse(ast_obj)

ast.AST オブジェクトを逆に構文解析して、 ast.parse() が元の ast.AST と等価なオブジェクトを生成できるような文字列を生成します。

警告

生成されたコード文字列は、生成元のコードである ast.AST オブジェクトと必ずしも等価であるとは限りません (定数タプルや frozenset などに対するコンパイラ最適化なしのコードです)。

警告

非常に複雑な式を逆構文解析すると RecursionError となることがあります。

Added in version 3.9.

ast.literal_eval(node_or_string)

Python のリテラルやコンテナ表現のみを含む式ノードまたは文字列を評価します。与えられる文字列またはノードは次の Python リテラル構造のみからなるものに限られます: 文字列、バイト列、数、タプル、リスト、辞書、集合、ブール値、None、Ellipsis。

この関数は Python の式を含んだ文字列を、値自身を解析することなしに評価するのに使えます。この関数は、例えば演算や添え字を含んだ任意の複雑な表現を評価するのには使えません。

This function had been documented as "safe" in the past without defining what that meant. That was misleading. This is specifically designed not to execute Python code, unlike the more general eval(). There is no namespace, no name lookups, or ability to call out. But it is not free from attack: A relatively small input can lead to memory exhaustion or to C stack exhaustion, crashing the process. There is also the possibility for excessive CPU consumption denial of service on some inputs. Calling it on untrusted data is thus not recommended.

警告

Python の抽象構文木コンパイラのスタックの深さの限界を越えることで、 Python インタプリタをクラッシュさせる可能性があります。

It can raise ValueError, TypeError, SyntaxError, MemoryError and RecursionError depending on the malformed input.

バージョン 3.2 で変更: バイト列リテラルと集合リテラルが受け取れるようになりました。

バージョン 3.9 で変更: 'set()' による空の集合の生成をサポートするようになりました。

バージョン 3.10 で変更: For string inputs, leading spaces and tabs are now stripped.

ast.get_docstring(node, clean=True)

与えられた node (これは FunctionDef, AsyncFunctionDef, ClassDef, Module のいずれかのノードでなければなりません) のドキュメント文字列を返します。もしドキュメント文字列が無ければ None を返します。 clean が真ならば、ドキュメント文字列のインデントを inspect.cleandoc() を用いて一掃します。

バージョン 3.5 で変更: AsyncFunctionDef がサポートされました。

ast.get_source_segment(source, node, *, padded=False)

Get source code segment of the source that generated node. If some location information (lineno, end_lineno, col_offset, or end_col_offset) is missing, return None.

padded が True の場合、複数行にわたる文の最初の行が元の位置に一致するように空白文字でパディングされます。

Added in version 3.8.

ast.fix_missing_locations(node)

When you compile a node tree with compile(), the compiler expects lineno and col_offset attributes for every node that supports them. This is rather tedious to fill in for generated nodes, so this helper adds these attributes recursively where not already set, by setting them to the values of the parent node. It works recursively starting at node.

ast.increment_lineno(node, n=1)

node で始まるツリー内の各ノードの行番号と終了行番号を n ずつ増やします。これはファイルの中で別の場所に "コードを移動する" ときに便利です。

ast.copy_location(new_node, old_node)

Copy source location (lineno, col_offset, end_lineno, and end_col_offset) from old_node to new_node if possible, and return new_node.

ast.iter_fields(node)

node にある node._fields のそれぞれのフィールドを (フィールド名, 値) のタプルとして yield します。

ast.iter_child_nodes(node)

node の直接の子ノード全てを yield します。すなわち、yield されるのは、ノードであるような全てのフィールドおよびノードのリストであるようなフィールドの全てのアイテムです。

ast.walk(node)

node の全ての子孫ノード(node 自体を含む)を再帰的に yield します。順番は決められていません。この関数はノードをその場で変更するだけで文脈を気にしないような場合に便利です。

class ast.NodeVisitor

抽象構文木を渡り歩いてビジター関数を見つけたノードごとに呼び出すノード・ビジターの基底クラスです。この関数は visit() メソッドに送られる値を返してもかまいません。

このクラスはビジター・メソッドを付け加えたサブクラスを派生させることを意図しています。

visit(node)

ノードを訪れます。デフォルトの実装では self.visit_classname というメソッド (ここで classname はノードのクラス名です) を呼び出すか、そのメソッドがなければ generic_visit() を呼び出します。

generic_visit(node)

このビジターはノードの全ての子について visit() を呼び出します。

注意して欲しいのは、専用のビジター・メソッドを具えたノードの子ノードは、このビジターが generic_visit() を呼び出すかそれ自身で子ノードを訪れない限り訪れられないということです。

visit_Constant(node)

Handles all constant nodes.

トラバースの途中でノードを変化させたいならば NodeVisitor を使ってはいけません。そうした目的のために変更を許す特別なビジター (NodeTransformer) があります。

バージョン 3.8 で非推奨: Methods visit_Num(), visit_Str(), visit_Bytes(), visit_NameConstant() and visit_Ellipsis() are deprecated now and will not be called in future Python versions. Add the visit_Constant() method to handle all constant nodes.

class ast.NodeTransformer

NodeVisitor のサブクラスで抽象構文木を渡り歩きながらノードを変更することを許すものです。

NodeTransformer は抽象構文木(AST)を渡り歩き、ビジター・メソッドの戻り値を使って古いノードを置き換えたり削除したりします。ビジター・メソッドの戻り値が None ならば、ノードはその場から取り去られ、そうでなければ戻り値で置き換えられます。置き換えない場合は戻り値が元のノードそのものであってもかまいません。

それでは例を示しましょう。Name (たとえば foo) を見つけるたび全て data['foo'] に書き換える変換器 (transformer) です:

class RewriteName(NodeTransformer):

    def visit_Name(self, node):
        return Subscript(
            value=Name(id='data', ctx=Load()),
            slice=Constant(value=node.id),
            ctx=node.ctx
        )

Keep in mind that if the node you're operating on has child nodes you must either transform the child nodes yourself or call the generic_visit() method for the node first.

文のコレクションであるようなノード (全ての文のノードが当てはまります) に対して、このビジターは単独のノードではなくノードのリストを返すかもしれません。

If NodeTransformer introduces new nodes (that weren't part of original tree) without giving them location information (such as lineno), fix_missing_locations() should be called with the new sub-tree to recalculate the location information:

tree = ast.parse('foo', mode='eval')
new_tree = fix_missing_locations(RewriteName().visit(tree))

たいてい、変換器の使い方は次のようになります:

node = YourTransformer().visit(node)

ast.dump(node, annotate_fields=True, include_attributes=False, *, indent=None)

node 内のツリーのフォーマットされたダンプを返します。主な使い道はデバッグです。 annotate_fields が true の場合 (デフォルト)、返される文字列はフィールドの名前と値を示します。 annotate_fields が false の場合、あいまいさのないフィールド名を省略することにより、結果文字列はよりコンパクトになります。行番号や列オフセットのような属性はデフォルトではダンプされません。これが必要であれば、 include_attributes を true にすると表示できます。

indent が非負の整数または文字列の場合、ツリーは指定されたインデントレベルで整形されて出力されます (pretty-printed)。インデントレベルがゼロ、負の数、または "" の場合は改行だけを挿入します。 None (デフォルト値) は単一行での表記になります。正の整数を指定すると各インデントレベルでその数だけの空白でインデントされます。 indent が文字列 ("\t" など) の場合、その文字列が各レベルのインデントに使われます。

バージョン 3.9 で変更: indent オプションを追加しました。

コンパイラフラグ

以下のフラグはプログラムのコンパイルにおける効果を変更するために compile() に渡すことができます:

ast.PyCF_ALLOW_TOP_LEVEL_AWAIT

トップレベルの await, async for, async with および async 内包表記のサポートを有効化します。

Added in version 3.8.

ast.PyCF_ONLY_AST

コンパイルされたコードオブジェクトの代わりに抽象構文木を生成して返します。

ast.PyCF_TYPE_COMMENTS

PEP 484 [https://peps.python.org/pep-0484/] および PEP 526 [https://peps.python.org/pep-0526/] 形式の型コメント (# type: <type>, # type: ignore <stuff>) のサポートを有効化します。

Added in version 3.8.

コマンドラインからの使用

Added in version 3.9.

ast モジュールはコマンドラインからスクリプトとして実行することができます。実行方法は単純です:

python -m ast [-m <mode>] [-a] [infile]

以下のオプションが使用できます:

-h, --help

ヘルプメッセージを表示して終了します。

-m <mode>

--mode <mode>

parse() 関数の mode 引数と同様、コンパイルするコードの種類を指定します。

--no-type-comments

型コメントをパースしません。

-a, --include-attributes

行番号や列オフセットなどの属性を含めます。

-i <indent>

--indent <indent>

AST におけるノードのインデント (空白の数) です。

infile を指定するとその内容が AST にパースされて標準出力に出力されます。そうでない場合は標準入力から入力を読み込みます。

参考

外部ドキュメント Green Tree Snakes [https://greentreesnakes.readthedocs.io/] には Python AST についての詳細が書かれています。

ASTTokens [https://asttokens.readthedocs.io/en/latest/user-guide.html] は Python AST を、生成元のソースコードのトークン位置やテキストで注解します。これはソースコード変換を行うツールで有用です。

leoAst.py [https://leo-editor.github.io/leo-editor/appendices.html#leoast-py] unifies the token-based and parse-tree-based views of python programs by inserting two-way links between tokens and ast nodes.

LibCST [https://libcst.readthedocs.io/] はコードを ast ツリーに似た構文木 (Concrete Syntax Tree) にパースし、かつ全ての書式設定の詳細を保持します。これは自動リファクタリングアプリケーション (codemod) やリンタを作成する際に有用です。

Parso [https://parso.readthedocs.io] is a Python parser that supports error recovery and round-trip parsing for different Python versions (in multiple Python versions). Parso is also able to list multiple syntax errors in your Python file.

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

ソースコード: Lib/symtable.py [https://github.com/python/cpython/tree/3.12/Lib/symtable.py]

記号表(symbol table)は、コンパイラが AST からバイトコードを生成する直前に作られます。記号表はコード中の全ての識別子のスコープの算出に責任を持ちます。 symtable はこうした記号表を調べるインターフェイスを提供します。

記号表の生成

symtable.symtable(code, filename, compile_type)

Python ソース code に対するトップレベルの SymbolTable を返します。 filename はコードを収めてあるファイルの名前です。 compile_type は compile() の mode 引数のようなものです。

記号表の検査

class symtable.SymbolTable

ブロックに対する名前空間の記号表。コンストラクタはパブリックではありません。

get_type()

Return the type of the symbol table. Possible values are 'class', 'module', 'function', 'annotation', 'TypeVar bound', 'type alias', and 'type parameter'. The latter four refer to different flavors of annotation scopes.

バージョン 3.12 で変更: Added 'annotation', 'TypeVar bound', 'type alias', and 'type parameter' as possible return values.

get_id()

記号表の識別子を返します。

get_name()

Return the table's name. This is the name of the class if the table is for a class, the name of the function if the table is for a function, or 'top' if the table is global (get_type() returns 'module'). For type parameter scopes (which are used for generic classes, functions, and type aliases), it is the name of the underlying class, function, or type alias. For type alias scopes, it is the name of the type alias. For TypeVar bound scopes, it is the name of the TypeVar.

get_lineno()

この記号表に対応するブロックの一行目の行番号を返します。

is_optimized()

この記号表に含まれるローカル変数が最適化できるならば True を返します。

is_nested()

ブロックが入れ子のクラスまたは関数のとき True を返します。

has_children()

ブロックが入れ子の名前空間を含んでいるならば True を返します。入れ子の名前空間は get_children() で得られます。

get_identifiers()

Return a view object containing the names of symbols in the table. See the documentation of view objects.

lookup(name)

記号表から名前 name を見つけ出して Symbol インスタンスとして返します。

get_symbols()

記号表中の名前を表す Symbol インスタンスのリストを返します。

get_children()

入れ子になった記号表のリストを返します。

class symtable.Function

A namespace for a function or method. This class inherits from SymbolTable.

get_parameters()

この関数の引数名からなるタプルを返します。

get_locals()

この関数のローカル変数の名前からなるタプルを返します。

get_globals()

この関数のグローバル変数の名前からなるタプルを返します。

get_nonlocals()

この関数の非ローカル変数の名前からなるタプルを返します。

get_frees()

この関数の自由変数の名前からなるタプルを返します。

class symtable.Class

A namespace of a class. This class inherits from SymbolTable.

get_methods()

このクラスで宣言されているメソッド名からなるタプルを返します。

class symtable.Symbol

SymbolTable のエントリーでソースの識別子に対応するものです。コンストラクタはパブリックではありません。

get_name()

記号の名前を返します。

is_referenced()

記号がそのブロックの中で使われていれば True を返します。

is_imported()

記号が import 文で作られたものならば True を返します。

is_parameter()

記号がパラメータならば True を返します。

is_global()

記号がグローバルならば True を返します。

is_nonlocal()

記号が非ローカルならば True を返します。

is_declared_global()

記号が global 文によってグローバルであると宣言されているなら True を返します。

is_local()

記号がそのブロックに対してローカルならば True を返します。

is_annotated()

記号が注釈付きならば True を返します。

Added in version 3.6.

is_free()

記号がそのブロックの中で参照されていて、しかし代入は行われないならば True を返します。

is_assigned()

記号がそのブロックの中で代入されているならば True を返します。

is_namespace()

名前の束縛が新たな名前空間を導入するならば True を返します。

名前が関数または class 文のターゲットとして使われるならば、真です。

例えば:

>>> table = symtable.symtable("def some_func(): pass", "string", "exec")
>>> table.lookup("some_func").is_namespace()
True

一つの名前が複数のオブジェクトに束縛されうることに注意しましょう。結果が True であったとしても、その名前は他のオブジェクトにも束縛されるかもしれず、それがたとえば整数やリストであれば、そこでは新たな名前空間は導入されません。

get_namespaces()

この名前に束縛された名前空間のリストを返します。

get_namespace()

この名前に束縛された名前空間を返します。この名前に束縛された名前空間が複数あるか一つもないなら ValueError が送出されます。

token --- Constants used with Python parse trees

ソースコード: Lib/token.py [https://github.com/python/cpython/tree/3.12/Lib/token.py]

このモジュールは解析木の葉ノード(終端記号)の数値を表す定数を提供します。言語の文法のコンテキストにおける名前の定義については、 Python ディストリビューションのファイル file:Grammar/Tokens を参照してください。名前がマップする特定の数値は Python のバージョン間で変わります。

このモジュールは、数値コードから名前へのマッピングと、いくつかの関数も提供しています。関数は Python の C ヘッダファイルの定義を反映します。

token.tok_name

ディクショナリはこのモジュールで定義されている定数の数値を名前の文字列へマップし、より人が読みやすいように解析木を表現します。

token.ISTERMINAL(x)

終端トークンの値に対して True を返します。

token.ISNONTERMINAL(x)

非終端トークンの値に対して True を返します。

token.ISEOF(x)

x が入力の終わりを示すマーカーならば、 True を返します。

token の定数一覧:

token.ENDMARKER

token.NAME

token.NUMBER

token.STRING

token.NEWLINE

token.INDENT

token.DEDENT

token.LPAR

Token value for "(".

token.RPAR

Token value for ")".

token.LSQB

Token value for "[".

token.RSQB

Token value for "]".

token.COLON

Token value for ":".

token.COMMA

Token value for ",".

token.SEMI

Token value for ";".

token.PLUS

Token value for "+".

token.MINUS

Token value for "-".

token.STAR

Token value for "*".

token.SLASH

Token value for "/".

token.VBAR

Token value for "|".

token.AMPER

Token value for "&".

token.LESS

Token value for "<".

token.GREATER

Token value for ">".

token.EQUAL

Token value for "=".

token.DOT

Token value for ".".

token.PERCENT

Token value for "%".

token.LBRACE

Token value for "{".

token.RBRACE

Token value for "}".

token.EQEQUAL

Token value for "==".

token.NOTEQUAL

Token value for "!=".

token.LESSEQUAL

Token value for "<=".

token.GREATEREQUAL

Token value for ">=".

token.TILDE

Token value for "~".

token.CIRCUMFLEX

Token value for "^".

token.LEFTSHIFT

Token value for "<<".

token.RIGHTSHIFT

Token value for ">>".

token.DOUBLESTAR

Token value for "**".

token.PLUSEQUAL

Token value for "+=".

token.MINEQUAL

Token value for "-=".

token.STAREQUAL

Token value for "*=".

token.SLASHEQUAL

Token value for "/=".

token.PERCENTEQUAL

Token value for "%=".

token.AMPEREQUAL

Token value for "&=".

token.VBAREQUAL

Token value for "|=".

token.CIRCUMFLEXEQUAL

Token value for "^=".

token.LEFTSHIFTEQUAL

Token value for "<<=".

token.RIGHTSHIFTEQUAL

Token value for ">>=".

token.DOUBLESTAREQUAL

Token value for "**=".

token.DOUBLESLASH

Token value for "//".

token.DOUBLESLASHEQUAL

Token value for "//=".

token.AT

Token value for "@".

token.ATEQUAL

Token value for "@=".

token.RARROW

Token value for "->".

token.ELLIPSIS

Token value for "...".

token.COLONEQUAL

Token value for ":=".

token.EXCLAMATION

Token value for "!".

token.OP

token.AWAIT

token.ASYNC

token.TYPE_IGNORE

token.TYPE_COMMENT

token.SOFT_KEYWORD

token.FSTRING_START

token.FSTRING_MIDDLE

token.FSTRING_END

token.COMMENT

token.NL

token.ERRORTOKEN

token.N_TOKENS

token.NT_OFFSET

以下のトークン値は、Cのトークナイザでは利用されませんが、 tokenize モジュールによって利用されます。

token.COMMENT

コメントであることを表すために使われるトークン値です。

token.NL

終わりではない改行を表すために使われるトークン値。 NEWLINE トークンは Pythonコードの論理行の終わりを表します。 NL トークンはコードの論理行が複数の物理行にわたって続いているときに作られます。

token.ENCODING

ソースの bytes をテキストにデコードするために使われるエンコーディングを示すトークン値。tokenize.tokenize() は常に最初に ENCODING トークンを返します。

token.TYPE_COMMENT

Token value indicating that a type comment was recognized. Such tokens are only produced when ast.parse() is invoked with type_comments=True.

バージョン 3.5 で変更: Added AWAIT and ASYNC tokens.

バージョン 3.7 で変更: COMMENT 、NL、ENCODING トークンが追加されました。

バージョン 3.7 で変更: Removed AWAIT and ASYNC tokens. "async" and "await" are now tokenized as NAME tokens.

バージョン 3.8 で変更: Added TYPE_COMMENT, TYPE_IGNORE, COLONEQUAL. Added AWAIT and ASYNC tokens back (they're needed to support parsing older Python versions for ast.parse() with feature_version set to 6 or lower).

keyword --- Testing for Python keywords

ソースコード: Lib/keyword.py [https://github.com/python/cpython/tree/3.12/Lib/keyword.py]

このモジュールでは、Python プログラムで文字列が キーワード や ソフトキーワード か否かをチェックする機能を提供します。

keyword.iskeyword(s)

s が Python の キーワード であれば True を返します。

keyword.kwlist

インタープリタで定義している全ての キーワード のシーケンス。特定の __future__ 宣言がなければ有効ではないキーワードでもこのリストには含まれます。

keyword.issoftkeyword(s)

s が Python の ソフトキーワード であれば True を返します。

Added in version 3.9.

keyword.softkwlist

インタープリタで定義している全ての ソフトキーワード のシーケンス。特定の __future__ 宣言がなければ有効ではないソフトキーワードでもこのリストには含まれます。

Added in version 3.9.

tokenize --- Tokenizer for Python source

ソースコード: Lib/tokenize.py [https://github.com/python/cpython/tree/3.12/Lib/tokenize.py]

tokenize モジュールでは、Python で実装された Python ソースコードの字句解析器を提供します。さらに、このモジュールの字句解析器はコメントもトークンとして返します。このため、このモジュールはスクリーン上で表示する際の色付け機能 (colorizers) を含む "清書出力器 (pretty-printer)" を実装する上で便利です。

トークン・ストリームの扱いをシンプルにするために、全ての operator と delimiter トークンおよび Ellipsis はジェネリックな OP トークンタイプとして返されます。正確な型は tokenize.tokenize() が返す named tuple の exact_type プロパティをチェックすれば解ります。

警告

Note that the functions in this module are only designed to parse syntactically valid Python code (code that does not raise when parsed using ast.parse()). The behavior of the functions in this module is undefined when providing invalid Python code and it can change at any point.

入力のトークナイズ

第一のエントリポイントは ジェネレータ です:

tokenize.tokenize(readline)

tokenize() ジェネレータは一つの引数 readline を必要とします。この引数は呼び出し可能オブジェクトで、ファイルオブジェクトの io.IOBase.readline() メソッドと同じインタフェースを提供している必要があります。この関数は呼び出しのたびに入力の一行を bytes で返さなければなりません。

このジェネレータは次の5要素のタプルを返します; トークンタイプ; トークン文字列; ソース内でそのトークンがどの行、列で開始するかを示す int の (srow, scol) タプル; どの行、列で終了するかを示す int の (erow, ecol) タプル; トークンが見つかった行。 (タプルの最後の要素にある) 行は 物理 行です。この5要素のタプルは named tuple として返され、フィールド名は type string start end line になります。

返される named tuple は追加のプロパティ exact_type を持ちます。このプロパティは OP トークンに対して正確な演算子のタイプを持ちます。それ以外のトークンタイプについては、 exact_type は type フィールドと同じ値を持ちます。

バージョン 3.1 で変更: named tuple のサポートを追加。

バージョン 3.3 で変更: exact_type のサポートを追加。

tokenize() は PEP 263 [https://peps.python.org/pep-0263/] にしたがって、ソースのエンコーディングを UTF-8 BOM か encoding cookie を見つけて決定します。

tokenize.generate_tokens(readline)

Tokenize a source reading unicode strings instead of bytes.

Like tokenize(), the readline argument is a callable returning a single line of input. However, generate_tokens() expects readline to return a str object rather than bytes.

The result is an iterator yielding named tuples, exactly like tokenize(). It does not yield an ENCODING token.

token モジュールの全ての定数は tokenize モジュールからも公開されています。

もう一つの関数がトークン化プロセスを逆転するために提供されています。これは、スクリプトを字句解析し、トークンのストリームに変更を加え、変更されたスクリプトを書き戻すようなツールを作成する際に便利です。

tokenize.untokenize(iterable)

トークンの列を Python ソースコードに変換します。 iterable は少なくとも二つの要素、トークンタイプおよびトークン文字列、からなるシーケンスを返さなければいけません。 その他のシーケンスの要素は無視されます。

再構築されたスクリプトは一つの文字列として返されます。得られる結果はもう一度字句解析すると入力と一致することが保証されるので、変換がロスレスでありラウンドトリップできることは間違いありません。この保証はトークン型およびトークン文字列に対してのものでトークン間のスペース (コラム位置)のようなものは変わることがあり得ます。

It returns bytes, encoded using the ENCODING token, which is the first token sequence output by tokenize(). If there is no encoding token in the input, it returns a str instead.

tokenize() はトークナイズしようとしているソースファイルのエンコーディングを検出する必要があります。これを行うために使っている関数が公開されています:

tokenize.detect_encoding(readline)

detect_encoding() 関数は Python のソースファイルをデコードするのに使うエンコーディングを検出するために使われます。 tokenize() ジェネレータと同じ readline を引数として取ります。

readline を最大2回呼び出し、利用するエンコーディング (文字列として) と、読み込んだ行を (bytes からデコードされないままの状態で) 返します。

UTF-8 BOM か PEP 263 [https://peps.python.org/pep-0263/] で定義されている encoding cookie からエンコーディングを検出します。BOMと cookie の両方が存在し、一致していない場合、SyntaxError が送出されます。 BOM が見つかった場合はエンコーディングとして 'utf-8-sig' が返されます。

エンコーディングが指定されていない場合、デフォルトの 'utf-8' が返されます。

Python のソースファイルを開くには open() を使ってください。これは detect_encoding() を利用してファイルエンコーディングを検出します。

tokenize.open(filename)

detect_encoding() を使って検出したエンコーディングを利用して、ファイルを読み出し専用モードで開きます。

Added in version 3.2.

exception tokenize.TokenError

docstring や複数行にわたることが許される式がファイル内のどこかで終わっていない場合に送出されます。例えば:

"""Beginning of
docstring

もしくは:

[1,
 2,
 3

コマンドラインからの使用

Added in version 3.3.

tokenize モジュールはコマンドラインからスクリプトとして実行することができます。次のようにシンプルに利用できます:

python -m tokenize [-e] [filename.py]

以下のオプションが使用できます:

-h, --help

このヘルプメッセージを出力して終了します

-e, --exact

exact type を使ってトークン名を表示します

filename.py が指定された場合、その内容がトークナイズされ stdout に出力されます。指定されなかった場合は stdin からトークナイズします。

使用例

スクリプト書き換えの例で、浮動小数点数リテラルを Decimal オブジェクトに変換します:

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')

コマンドラインからトークナイズする例。次のスクリプトが:

def say_hello():
    print("Hello, World!")

say_hello()

トークナイズされて次のような出力になります。最初のカラムはトークンが現れた行／カラム、次のカラムはトークンの名前、最後のカラムは (あれば) トークンの値です

$ 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         ''
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      ''

トークンの exact_type 名は -e オプションで表示できます:

$ 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         ''
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      ''

Example of tokenizing a file programmatically, reading unicode strings instead of bytes with generate_tokens():

import tokenize

with tokenize.open('hello.py') as f:
    tokens = tokenize.generate_tokens(f.readline)
    for token in tokens:
        print(token)

Or reading bytes directly with tokenize():

import tokenize

with open('hello.py', 'rb') as f:
    tokens = tokenize.tokenize(f.readline)
    for token in tokens:
        print(token)

tabnanny --- Detection of ambiguous indentation

ソースコード: Lib/tabnanny.py [https://github.com/python/cpython/tree/3.12/Lib/tabnanny.py]

差し当たり、このモジュールはスクリプトとして呼び出すことを意図しています。しかし、IDE 上にインポートして下で説明する関数 check() を使うことができます。

注釈

このモジュールが提供する API を将来のリリースで変更する確率が高いです。このような変更は後方互換性がないかもしれません。

tabnanny.check(file_or_dir)

file_or_dir がディレクトリであってシンボリックリンクでないときに、 file_or_dir という名前のディレクトリツリーを再帰的に下って行き、この通り道に沿ってすべての .py ファイルをチェックします。 file_or_dir が通常の Python ソースファイルの場合には、問題のある空白をチェックします。診断メッセージは print() 関数を使って標準出力に書き込まれます。

tabnanny.verbose

冗長なメッセージをプリントするかどうかを示すフラグ。スクリプトとして呼び出された場合は、-v オプションによって増加します。

tabnanny.filename_only

問題のある空白を含むファイルのファイル名のみをプリントするかどうかを示すフラグ。スクリプトとして呼び出された場合は、-q オプションによって真に設定されます。

exception tabnanny.NannyNag

あいまいなインデントを検出した場合に process_tokens() が送出します。この例外は check() で捕捉され処理されます。

tabnanny.process_tokens(tokens)

この関数は、 tokenize モジュールによって生成されたトークンを check() が処理するために使われます。

参考

tokenize モジュール

Pythonソースコードの字句解析器。

pyclbr --- Python module browser support

ソースコード: Lib/pyclbr.py [https://github.com/python/cpython/tree/3.12/Lib/pyclbr.py]

The pyclbr module provides limited information about the functions, classes, and methods defined in a Python-coded module. The information is sufficient to implement a module browser. The information is extracted from the Python source code rather than by importing the module, so this module is safe to use with untrusted code. This restriction makes it impossible to use this module with modules not implemented in Python, including all standard and optional extension modules.

pyclbr.readmodule(module, path=None)

Return a dictionary mapping module-level class names to class descriptors. If possible, descriptors for imported base classes are included. Parameter module is a string with the name of the module to read; it may be the name of a module within a package. If given, path is a sequence of directory paths prepended to sys.path, which is used to locate the module source code.

This function is the original interface and is only kept for back compatibility. It returns a filtered version of the following.

pyclbr.readmodule_ex(module, path=None)

Return a dictionary-based tree containing a function or class descriptors for each function and class defined in the module with a def or class statement. The returned dictionary maps module-level function and class names to their descriptors. Nested objects are entered into the children dictionary of their parent. As with readmodule, module names the module to be read and path is prepended to sys.path. If the module being read is a package, the returned dictionary has a key '__path__' whose value is a list containing the package search path.

Added in version 3.7: Descriptors for nested definitions. They are accessed through the new children attribute. Each has a new parent attribute.

The descriptors returned by these functions are instances of Function and Class classes. Users are not expected to create instances of these classes.

Function オブジェクト

class pyclbr.Function

Class Function instances describe functions defined by def statements. They have the following attributes:

file

Name of the file in which the function is defined.

module

The name of the module defining the function described.

name

関数の名前です。

lineno

The line number in the file where the definition starts.

parent

For top-level functions, None. For nested functions, the parent.

Added in version 3.7.

children

A dictionary mapping names to descriptors for nested functions and classes.

Added in version 3.7.

is_async

True for functions that are defined with the async prefix, False otherwise.

Added in version 3.10.

クラスオブジェクト

class pyclbr.Class

Class Class instances describe classes defined by class statements. They have the same attributes as Functions and two more.

file

Name of the file in which the class is defined.

module

The name of the module defining the class described.

name

クラスの名前です。

lineno

The line number in the file where the definition starts.

parent

For top-level classes, None. For nested classes, the parent.

Added in version 3.7.

children

A dictionary mapping names to descriptors for nested functions and classes.

Added in version 3.7.

super

A list of Class objects which describe the immediate base classes of the class being described. Classes which are named as superclasses but which are not discoverable by readmodule_ex() are listed as a string with the class name instead of as Class objects.

methods

A dictionary mapping method names to line numbers. This can be derived from the newer children dictionary, but remains for back-compatibility.

py_compile --- Compile Python source files

ソースコード: Lib/py_compile.py [https://github.com/python/cpython/tree/3.12/Lib/py_compile.py]

py_compile モジュールには、ソースファイルからバイトコードファイルを作る関数と、モジュールのソースファイルがスクリプトとして呼び出される時に使用される関数が定義されています。

頻繁に必要となるわけではありませんが、共有ライブラリとしてモジュールをインストールする場合や、特にソースコードのあるディレクトリにバイトコードのキャッシュファイルを書き込む権限がないユーザがいるときには、この関数は役に立ちます。

exception py_compile.PyCompileError

ファイルをコンパイル中にエラーが発生すると送出される例外。

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 PEP 3147 [https://peps.python.org/pep-3147/]/PEP 488 [https://peps.python.org/pep-0488/] path, ending in .pyc. For example, if file is /foo/bar/baz.py cfile will default to /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 PyCompileError is raised when an error is encountered while compiling file. If doraise is false (the default), an error string is written to 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 sys.stderr, and the function returns None instead of a path. If doraise is true, a PyCompileError is raised instead. However if quiet is 2, no message is written, and doraise has no effect.

(明示的に指定されたか計算された結果の) cfile のパスがシンボリックリンクだったり通常のファイルでなかったりした場合は、 FileExistsError が送出されます。この動作は、それらのパスにバイトコンパイルされたファイルを書き込む権限がある場合、インポートのときにそのパスを通常のファイルに変えてしまうことを警告するためのものです。これはリネームを使ってバイトコンパイルされたファイルを配置するインポートで、同時にファイル書き込みをしてしまう問題を避けるための副作用です。

optimize は最適化レベルを制御するもので、組み込みの compile() 関数に渡されます。デフォルトは現在のインタープリタの最適化レベルを選ぶ -1 です。

invalidation_mode should be a member of the PycInvalidationMode enum and controls how the generated bytecode cache is invalidated at runtime. The default is PycInvalidationMode.CHECKED_HASH if the SOURCE_DATE_EPOCH environment variable is set, otherwise the default is PycInvalidationMode.TIMESTAMP.

バージョン 3.2 で変更: PEP 3147 [https://peps.python.org/pep-3147/] に準拠し cfile のデフォルト値を変更しました。以前のデフォルトは file + 'c' (最適化が有効な場合は 'o') でした。同時に optimize パラメータも追加されました。

バージョン 3.4 で変更: バイトコードをキャッシュするファイルへの書き込みに importlib を使うようにコードを変更しました。これにより、例えば権限や write-and-move セマンティクスなどの、ファイルの作成や書き込みの動作が importlib と一致するようになりました。 cfile がシンボリックリンクであるか通常のファイルでない場合、 FileExistsError を送出するという注意書きも追加されました。

バージョン 3.7 で変更: The invalidation_mode parameter was added as specified in PEP 552 [https://peps.python.org/pep-0552/]. If the SOURCE_DATE_EPOCH environment variable is set, invalidation_mode will be forced to PycInvalidationMode.CHECKED_HASH.

バージョン 3.7.2 で変更: The SOURCE_DATE_EPOCH environment variable no longer overrides the value of the invalidation_mode argument, and determines its default value instead.

バージョン 3.8 で変更: quiet パラメータが追加されました。

class 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 .pyc file indicates the desired invalidation mode in its header. See キャッシュされたバイトコードの無効化 for more information on how Python invalidates .pyc files at runtime.

Added in version 3.7.

TIMESTAMP

The .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 .pyc file needs to be regenerated.

CHECKED_HASH

The .pyc file includes a hash of the source file content, which Python will compare against the source at runtime to determine if the .pyc file needs to be regenerated.

UNCHECKED_HASH

Like CHECKED_HASH, the .pyc file includes a hash of the source file content. However, Python will at runtime assume the .pyc file is up to date and not validate the .pyc against the source file at all.

This option is useful when the .pycs are kept up to date by some system external to Python like a build system.

コマンドラインインターフェイス

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.

<file> ... <fileN>

-

Positional arguments are files to compile. If - is the only parameter, the list of files is taken from standard input.

-q, --quiet

Suppress errors output.

バージョン 3.2 で変更: - のサポートが追加されました。

バージョン 3.10 で変更: -q のサポートが追加されました。

参考

compileall モジュール

ディレクトリツリー内の Python ソースファイルを全てコンパイルするライブラリ。

compileall --- Byte-compile Python libraries

ソースコード: Lib/compileall.py [https://github.com/python/cpython/tree/3.12/Lib/compileall.py]

このモジュールは、Python ライブラリのインストールを助けるユーティリティ関数群を提供します。この関数群は、ディレクトリツリー内の Python ソースファイルをコンパイルします。このモジュールを使って、キャッシュされたバイトコードファイルをライブラリのインストール時に生成することで、ライブラリディレクトリに書き込み権限をもたないユーザでも、これらを利用できるようになります。

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. See WebAssemblyプラットフォーム for more information.

コマンドラインでの使用

このモジュールは、 (python -m compileall を使って) Python ソースをコンパイルするスクリプトとして機能します。

directory ...

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 -l <directories from sys.path>.

-l

サブディレクトリを再帰処理せず、指名または暗示されたディレクトリ群に含まれるソースコードファイル群だけをコンパイルします。

-f

タイムスタンプが最新であってもリビルドを強制します。

-q

コンパイルされたファイルのリストを出力しません。一つ渡された場合でもエラーメッセージは出力されます。二つ (-qq) の場合全ての出力は抑制されます。

-d destdir

コンパイルされるそれぞれのファイルへのパスの先頭に、ディレクトリを追加します。これはコンパイル時トレースバックに使われ、バイトコードファイルが実行される時点でソースファイルが存在しない場合に、トレースバックやその他のメッセージに使われるバイトコードファイルにもコンパイルされます。

-s strip_prefix

-p prepend_prefix

Remove (-s) or append (-p) the given prefix of paths recorded in the .pyc files. Cannot be combined with -d.

-x regex

regex を使って、コンパイル候補のそれぞれのファイルのフルパスを検索し、regex がマッチしたファイルを除外します。

-i list

ファイル list を読み込み、そのファイルのそれぞれの行を、コンパイルするファイルとディレクトリのリストに加えます。list が - なら、stdin の行を読み込みます。

-b

バイトコードファイルを、他のバージョンの Python によって生成されたバイトコードファイルを上書きするかもしれない、レガシーな場所に生成します。デフォルトでは PEP 3147 [https://peps.python.org/pep-3147/] で決められた場所と名前を使い、複数のバージョンの Python が共存できるようにします。

-r

サブディレクトリの最大再起深度を制御します。このオプションが与えられた場合、-l オプションは無視されます。 python -m compileall <directory> -r 0 は python -m compileall <directory> -l と等価です。

-j N

Use N workers to compile the files within the given directory. If 0 is used, then the result of os.cpu_count() will be used.

--invalidation-mode [timestamp|checked-hash|unchecked-hash]

生成したバイトコードファイルを実行時に無効化する方法を制御します。timestamp を指定すると、生成した``.pyc`` ファイルにソースファイルのタイムスタンプとサイズを埋め込みます。checked-hash と unchecked-hash を指定すると、ハッシュベースの pycファイルが生成されます。ハッシュベースのpycファイルは、ソースファイルにタイムスタンプではなくハッシュ値を埋め込みます。Python がバイトコードキャッシュファイルを実行時に検証する方法の詳細を知るには、キャッシュされたバイトコードの無効化 を参照してください。デフォルト値は、SOURCE_DATE_EPOCH 環境変数が設定されていなければ timestamp で、SOURCE_DATE_EPOCH 環境変数が設定されていれば、checked-hash になります。

-o level

Compile with the given optimization level. May be used multiple times to compile for multiple levels at a time (for example, compileall -o 1 -o 2).

-e dir

Ignore symlinks pointing outside the given directory.

--hardlink-dupes

If two .pyc files with different optimization level have the same content, use hard links to consolidate duplicate files.

バージョン 3.2 で変更: -i, -b, -h オプションを追加。

バージョン 3.5 で変更: -j, -r, -qq オプションが追加されました。-q オプションが複数のレベルの値に変更されました。-b は常に拡張子 .pyc のバイトエンコーディングファイルを生成し、.pyo を作りません。

バージョン 3.7 で変更: --invalidation-mode オプションが追加されました。

バージョン 3.9 で変更: Added the -s, -p, -e and --hardlink-dupes options. Raised the default recursion limit from 10 to sys.getrecursionlimit(). Added the possibility to specify the -o option multiple times.

compile() 関数で利用される最適化レベルを制御するコマンドラインオプションはありません。 Python インタプリタ自体のオプションを使ってください: python -O -m compileall.

Similarly, the compile() function respects the sys.pycache_prefix setting. The generated bytecode cache will only be useful if compile() is run with the same sys.pycache_prefix (if any) that will be used at runtime.

パブリックな関数

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)

dir という名前のディレクトリーツリーをたどり、途中で見つけた全ての .py をコンパイルします。全ファイルのコンパイルが成功した場合は真を、それ以外の場合は偽を返します。

maxlevels パラメータで最大再帰深度を制限します。デフォルトは sys.getrecursionlimit() です。

ddir が与えられた場合、コンパイルされるそれぞれのファイルへのパスの先頭に、そのディレクトリを追加します。これはコンパイル時トレースバックに使われ、バイトコードファイルが実行される時点でソースファイルが存在しない場合に、トレースバックやその他のメッセージに使われるバイトコードファイルにもコンパイルされます。

force が真の場合、タイムスタンプが最新のであってもモジュールは再コンパイルされます。

If rx is given, its 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 re.Pattern object.

quiet が False か 0 (デフォルト) の場合、ファイル名とその他の情報は標準出力に表示されます。 1 の場合エラーのみが表示されます。 2 の場合出力はすべて抑制されます。

legacy が真の時、バイトコードファイルは古い場所と名前に書かれ、他のバージョンの Python によって作られたバイトコードファイルを上書きする可能性があります。デフォルトは PEP 3147 [https://peps.python.org/pep-3147/] で決められた場所と名前を使い、複数のバージョンの Python のバイトコードファイルが共存できるようにします。

optimize specifies the optimization level for the compiler. It is passed to the built-in compile() function. Accepts also a sequence of optimization levels which lead to multiple compilations of one .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 0, a ValueError will be raised.

invalidation_mode は、py_compile.PycInvalidationMode のメンバーでなければならず、生成されたpycファイルを実行時に無効化する方法を制御します。

The stripdir, prependdir and limit_sl_dest arguments correspond to the -s, -p and -e options described above. They may be specified as str or os.PathLike.

If hardlink_dupes is true and two .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 引数が複数のレベルの値に変更されました。

バージョン 3.5 で変更: optimize の値に関わらず、legacy 引数は .pyc ファイルのみを書き出し、.pyo ファイルを書き出さないようになりました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

バージョン 3.7 で変更: invalidation_mode 引数を追加しました。

バージョン 3.7.2 で変更: The invalidation_mode parameter's default value is updated to 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 10 to sys.getrecursionlimit()

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)

パス fullname のファイルをコンパイルします。コンパイルが成功すれば真を、そうでなければ偽を返します。

ddir が与えられた場合、コンパイルされるファイルのパスの先頭にそのディレクトリを追加します。これはコンパイル時トレースバックに使われ、バイトコードファイルが実行される時点でソースファイルが存在しない場合に、トレースバックやその他のメッセージに使われるバイトコードファイルにもコンパイルされます。

If rx is given, its 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 True is returned. This can be used to exclude files matching a regular expression, given as a re.Pattern object.

quiet が False か 0 (デフォルト) の場合、ファイル名とその他の情報は標準出力に表示されます。 1 の場合エラーのみが表示されます。 2 の場合出力はすべて抑制されます。

legacy が真の時、バイトコードファイルは古い場所と名前に書かれ、他のバージョンの Python によって作られたバイトコードファイルを上書きする可能性があります。デフォルトは PEP 3147 [https://peps.python.org/pep-3147/] で決められた場所と名前を使い、複数のバージョンの Python のバイトコードファイルが共存できるようにします。

optimize specifies the optimization level for the compiler. It is passed to the built-in compile() function. Accepts also a sequence of optimization levels which lead to multiple compilations of one .py file in one call.

invalidation_mode は、py_compile.PycInvalidationMode のメンバーでなければならず、生成されたpycファイルを実行時に無効化する方法を制御します。

The stripdir, prependdir and limit_sl_dest arguments correspond to the -s, -p and -e options described above. They may be specified as str or os.PathLike.

If hardlink_dupes is true and two .pyc files with different optimization level have the same content, use hard links to consolidate duplicate files.

Added in version 3.2.

バージョン 3.5 で変更: quiet 引数が複数のレベルの値に変更されました。

バージョン 3.5 で変更: optimize の値に関わらず、legacy 引数は .pyc ファイルのみを書き出し、.pyo ファイルを書き出さないようになりました。

バージョン 3.7 で変更: invalidation_mode 引数を追加しました。

バージョン 3.7.2 で変更: The invalidation_mode parameter's default value is updated to None.

バージョン 3.9 で変更: 引数 stripdir 、 prependdir 、 limit_sl_dest 、および hardlink_dupes を追加しました。

compileall.compile_path(skip_curdir=True, maxlevels=0, force=False, quiet=0, legacy=False, optimize=-1, invalidation_mode=None)

sys.path からたどって見つけたすべての .py ファイルをバイトコンパイルします。すべてのファイルを問題なくコンパイルできたときに真を、それ以外のときに偽を返します。

skip_curdir が真(デフォルト)のとき、カレントディレクトリは走査から除外されます。それ以外のすべての引数は compile_dir() 関数に渡されます。その他の compile 関数群と異なり、 maxlevels のデフォルトが 0 になっていることに注意してください。

バージョン 3.2 で変更: legacy と optimize 引数が追加されました。

バージョン 3.5 で変更: quiet 引数が複数のレベルの値に変更されました。

バージョン 3.5 で変更: optimize の値に関わらず、legacy 引数は .pyc ファイルのみを書き出し、.pyo ファイルを書き出さないようになりました。

バージョン 3.7 で変更: invalidation_mode 引数を追加しました。

バージョン 3.7.2 で変更: The invalidation_mode parameter's default value is updated to None.

Lib/ ディレクトリ以下にある全ての .py ファイルを強制的に再コンパイルするには、以下のようにします:

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)

参考

Module py_compile

一つのソースファイルをバイトコンパイルします。

dis --- Disassembler for Python bytecode

ソースコード: Lib/dis.py [https://github.com/python/cpython/tree/3.12/Lib/dis.py]

dis モジュールは CPython バイトコード を逆アセンブルすることでバイトコードの解析をサポートします。このモジュールが入力として受け取る CPython バイトコードはファイル Include/opcode.h に定義されており、 コンパイラとインタプリタが使用しています。

CPython 実装の詳細: バイトコードは CPython インタプリタの実装詳細です。Python のバージョン間でバイトコードの追加や、削除、変更がないという保証はありません。このモジュールを使用することによって Python の異なる VM または異なるリリースの間で動作すると考えるべきではありません。

バージョン 3.6 で変更: 従来は使用されるバイト数は命令ごとに異なりましたが、このモジュールでは各々一つの命令につき2バイト使用することとなっています。

バージョン 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 CACHE instructions. These instructions are hidden by default, but can be shown by passing show_caches=True to any dis utility. Furthermore, the interpreter now adapts the bytecode to specialize it for different runtime conditions. The adaptive bytecode can be shown by passing 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 CACHE entries.

As a consequence, the presence of the CACHE instructions is transparent for forward jumps but needs to be taken into account when reasoning about backward jumps.

Example: Given the function myfunc():

def myfunc(alist):
    return len(alist)

the following command can be used to display the disassembly of myfunc():

>>> dis.dis(myfunc)
  2           0 RESUME                   0

  3           2 LOAD_GLOBAL              1 (NULL + len)
             12 LOAD_FAST                0 (alist)
             14 CALL                     1
             22 RETURN_VALUE

("2" は行番号です)。

コマンドライン・インターフェース

The dis module can be invoked as a script from the command line:

python -m dis [-h] [infile]

以下のオプションが使用できます:

-h, --help

使い方を表示して終了します。

If infile is specified, its disassembled code will be written to stdout. Otherwise, disassembly is performed on compiled source code recieved from stdin.

バイトコード解析

Added in version 3.4.

バイトコード解析の API を使うと、 Python のコード片を Bytecode オブジェクトでラップでき、コンパイルされたコードの細かいところに簡単にアクセスできます。

class dis.Bytecode(x, *, first_line=None, current_offset=None, show_caches=False, adaptive=False)

関数、ジェネレータ、非同期ジェネレータ、コルーチン、メソッド、ソースコード文字列、(compile() が返すような) コードオブジェクトに対応するバイトコードを解析します。

これは、下で並べられている関数の多くのものをまとめた便利なラッパーです。とりわけ目立つのは get_instructions() で、 Bytecode インスタンスに対し反復処理をしながら、バイトコード命令を Instruction インスタンスとして返します。

first_line が None でない場合は、それを逆アセンブルしたコードのソースの最初の行に表示する行番号とします。そうでない場合は、ソースの行の情報 (もしあれば) を逆アセンブルされたコードオブジェクトから直接取得します。

current_offset が None でない場合は、逆アセンブルされたコードでのあるインストラクションのオフセット位置を示します。これを設定すると、 dis() の出力において、指定された命令コード (opcode) に "現在の命令 (instruction)" を表す印が表示されます。

If show_caches is True, dis() will display inline cache entries used by the interpreter to specialize the bytecode.

If adaptive is True, dis() will display specialized bytecode that may be different from the original bytecode.

classmethod from_traceback(tb, *, show_caches=False)

与えられたトレースバックから Bytecode インスタンスを構築し、 current_offset がその例外の原因となった命令となるよう設定します。

codeobj

コンパイルされたコードオブジェクト。

first_line

コードオブジェクトのソースの最初の行 (利用可能であれば)

dis()

バイトコード命令の整形された表示を返します (dis.dis() と同じ出力になりますが、複数行文字列として返されます)。

info()

code_info() のようなコードオブジェクトの詳細を含んだ整形された複数行文字列を返します。

バージョン 3.7 で変更: This can now handle coroutine and asynchronous generator objects.

バージョン 3.11 で変更: Added the show_caches and adaptive parameters.

例:

>>> bytecode = dis.Bytecode(myfunc)
>>> for instr in bytecode:
...     print(instr.opname)
...
RESUME
LOAD_GLOBAL
LOAD_FAST
CALL
RETURN_VALUE

解析関数

dis モジュールには、以下に挙げる入力を直接欲しい出力に変換する解析関数も定義してあります。 1つの命令だけが実行されている場合は、解析オブジェクトをいったん作るよりはこちらの方が便利です:

dis.code_info(x)

渡された関数、ジェネレータ、非同期ジェネレータ、コルーチン、メソッド、ソースコード文字列、コードオブジェクトに対する、詳細なコードオブジェクトの情報を、整形された複数行の文字列として返します。

この結果は実装に強く依存しており、Python VM や Python のバージョンによって異なることがあります。

Added in version 3.2.

バージョン 3.7 で変更: This can now handle coroutine and asynchronous generator objects.

dis.show_code(x, *, file=None)

渡された関数、メソッド、ソースコード文字列、コードオブジェクトに対する、詳細なコードオブジェクトの情報を、file (または file が指定されていなければ sys.stdout) に表示します。

これは、インタラクティブシェル上で使うことを想定した、print(code_info(x), file=file) の便利なショートカットです。

Added in version 3.2.

バージョン 3.4 で変更: file 引数が追加されました。

dis.dis(x=None, *, file=None, depth=None, show_caches=False, adaptive=False)

Disassemble the x object. x can denote either a module, a class, a method, a function, a generator, an asynchronous generator, a coroutine, a code object, a string of source code or a byte sequence of raw bytecode. For a module, it disassembles all functions. For a class, it disassembles all methods (including class and static methods). For a code object or sequence of raw bytecode, it prints one line per bytecode instruction. It also recursively disassembles nested code objects. These can include generator expressions, nested functions, the bodies of nested classes, and the code objects used for annotation scopes. Strings are first compiled to code objects with the compile() built-in function before being disassembled. If no object is provided, this function disassembles the last traceback.

file 引数が渡された場合は、アセンブリをそこに書き込みます。そうでない場合は sys.stdout に出力します。

The maximal depth of recursion is limited by depth unless it is None. depth=0 means no recursion.

If show_caches is True, this function will display inline cache entries used by the interpreter to specialize the bytecode.

If adaptive is 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 で変更: Added the show_caches and adaptive parameters.

dis.distb(tb=None, *, file=None, show_caches=False, adaptive=False)

トレースバックのスタックの先頭の関数を逆アセンブルします。Noneが渡された場合は最後のトレースバックを使います。例外を引き起こした命令が表示されます。

file 引数が渡された場合は、アセンブリをそこに書き込みます。そうでない場合は sys.stdout に出力します。

バージョン 3.4 で変更: file 引数が追加されました。

バージョン 3.11 で変更: Added the show_caches and adaptive parameters.

dis.disassemble(code, lasti=-1, *, file=None, show_caches=False, adaptive=False)

dis.disco(code, lasti=-1, *, file=None, show_caches=False, adaptive=False)

コードオブジェクトを逆アセンブルします。lasti が与えられた場合は、最後の命令を示します。出力は次のようなカラムに分割されます:

各行の最初の命令に対する行番号。

現在の命令。 --> として示されます。

ラベル付けされた命令。 >> とともに表示されます。

命令のアドレス。

命令コード名。

命令パラメタ。

パラメタの解釈を括弧で囲んだもの。

パラメタの解釈は、ローカル変数とグローバル変数の名前、定数の値、 分岐先、比較命令を認識します。

file 引数が渡された場合は、アセンブリをそこに書き込みます。そうでない場合は sys.stdout に出力します。

バージョン 3.4 で変更: file 引数が追加されました。

バージョン 3.11 で変更: Added the show_caches and adaptive parameters.

dis.get_instructions(x, *, first_line=None, show_caches=False, adaptive=False)

渡された関数、メソッド、ソースコード文字列、コードオブジェクトにある命令のイテレータを返します。

イテレータは、与えられたコードの各命令の詳細情報を保持する名前付きタプル Instruction からなる列を生成します。

first_line が None でない場合は、それを逆アセンブルしたコードのソースの最初の行に表示する行番号とします。そうでない場合は、ソースの行の情報 (もしあれば) を逆アセンブルされたコードオブジェクトから直接取得します。

The show_caches and adaptive parameters work as they do in dis().

Added in version 3.4.

バージョン 3.11 で変更: Added the show_caches and adaptive parameters.

dis.findlinestarts(code)

This generator function uses the co_lines() method of the code object code to find the offsets which are starts of lines in the source code. They are generated as (offset, lineno) pairs.

バージョン 3.6 で変更: Line numbers can be decreasing. Before, they were always increasing.

バージョン 3.10 で変更: The PEP 626 [https://peps.python.org/pep-0626/] co_lines() method is used instead of the co_firstlineno and co_lnotab attributes of the code object.

dis.findlabels(code)

Detect all offsets in the raw compiled bytecode string code which are jump targets, and return a list of these offsets.

dis.stack_effect(opcode, oparg=None, *, jump=None)

opcode と引数 oparg がスタックに与える影響を計算します。

If the code has a jump target and jump is True, stack_effect() will return the stack effect of jumping. If jump is False, it will return the stack effect of not jumping. And if jump is None (default), it will return the maximal stack effect of both cases.

Added in version 3.4.

バージョン 3.8 で変更: Added jump parameter.

Python バイトコード命令

get_instructions() 関数と Bytecode クラスはバイトコード命令の詳細を Instruction インスタンスの形で提供します:

class dis.Instruction

バイトコード命令の詳細

opcode

以下の命令コードの値と 命令コードコレクション のバイトコードの値に対応する、命令の数値コードです。

opname

人間が読むための命令名

arg

(ある場合は) 命令の数値引数、無ければ None

argval

resolved arg value (if any), otherwise None

argrepr

human readable description of operation argument (if any), otherwise an empty string.

offset

バイトコード列の中での命令の開始位置

starts_line

line started by this opcode (if any), otherwise None

is_jump_target

他のコードからここへジャンプする場合は True 、そうでない場合は False

positions

dis.Positions object holding the start and end locations that are covered by this instruction.

Added in version 3.4.

バージョン 3.11 で変更: Field positions is added.

class dis.Positions

In case the information is not available, some fields might be None.

lineno

end_lineno

col_offset

end_col_offset

Added in version 3.11.

現在 Python コンパイラは次のバイトコード命令を生成します。

一般的な命令

In the following, We will refer to the interpreter stack as STACK and describe operations on it as if it was a Python list. The top of the stack corresponds to STACK[-1] in this language.

NOP

Do nothing code. Used as a placeholder by the bytecode optimizer, and to generate line tracing events.

POP_TOP

Removes the top-of-stack item:

STACK.pop()

END_FOR

Removes the top two values from the stack. Equivalent to POP_TOP; POP_TOP. Used to clean up at the end of loops, hence the name.

Added in version 3.12.

END_SEND

Implements del STACK[-2]. Used to clean up when a generator exits.

Added in version 3.12.

COPY(i)

Push the i-th item to the top of the stack without removing it from its original location:

assert i > 0
STACK.append(STACK[-i])

Added in version 3.11.

SWAP(i)

Swap the top of the stack with the i-th element:

STACK[-i], STACK[-1] = STACK[-1], STACK[-i]

Added in version 3.11.

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 dis utilities, but can be viewed with show_caches=True.

Logically, this space is part of the preceding instruction. Many opcodes expect to be followed by an exact number of caches, and will instruct the interpreter to skip over them at runtime.

Populated caches can look like arbitrary instructions, so great care should be taken when reading or modifying raw, adaptive bytecode containing quickened data.

Added in version 3.11.

1オペランド命令

1オペランド命令はスタックの先頭を取り出して操作を適用し、結果をスタックへプッシュし戻します。

UNARY_NEGATIVE

Implements STACK[-1] = -STACK[-1].

UNARY_NOT

Implements STACK[-1] = not STACK[-1].

UNARY_INVERT

Implements STACK[-1] = ~STACK[-1].

GET_ITER

Implements STACK[-1] = iter(STACK[-1]).

GET_YIELD_FROM_ITER

If STACK[-1] is a generator iterator or coroutine object it is left as is. Otherwise, implements STACK[-1] = iter(STACK[-1]).

Added in version 3.5.

Binary and in-place operations

Binary operations remove the top two items from the stack (STACK[-1] and 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 STACK[-2] supports it, and the resulting STACK[-1] may be (but does not have to be) the original STACK[-2].

BINARY_OP(op)

Implements the binary and in-place operators (depending on the value of op):

rhs = STACK.pop()
lhs = STACK.pop()
STACK.append(lhs op rhs)

Added in version 3.11.

BINARY_SUBSCR

Implements:

key = STACK.pop()
container = STACK.pop()
STACK.append(container[key])

STORE_SUBSCR

Implements:

key = STACK.pop()
container = STACK.pop()
value = STACK.pop()
container[key] = value

DELETE_SUBSCR

Implements:

key = STACK.pop()
container = STACK.pop()
del container[key]

BINARY_SLICE

Implements:

end = STACK.pop()
start = STACK.pop()
container = STACK.pop()
STACK.append(container[start:end])

Added in version 3.12.

STORE_SLICE

Implements:

end = STACK.pop()
start = STACK.pop()
container = STACK.pop()
values = STACK.pop()
container[start:end] = value

Added in version 3.12.

コルーチン命令コード

GET_AWAITABLE(where)

Implements STACK[-1] = get_awaitable(STACK[-1]), where get_awaitable(o) returns o if o is a coroutine object or a generator object with the CO_ITERABLE_COROUTINE flag, or resolves o.__await__.

If the where operand is nonzero, it indicates where the instruction occurs:

1: After a call to __aenter__

2: After a call to __aexit__

Added in version 3.5.

バージョン 3.11 で変更: Previously, this instruction did not have an oparg.

GET_AITER

Implements STACK[-1] = STACK[-1].__aiter__().

Added in version 3.5.

バージョン 3.7 で変更: Returning awaitable objects from __aiter__ is no longer supported.

GET_ANEXT

Implement STACK.append(get_awaitable(STACK[-1].__anext__())) to the stack. See GET_AWAITABLE for details about get_awaitable.

Added in version 3.5.

END_ASYNC_FOR

Terminates an async for loop. Handles an exception raised when awaiting a next item. The stack contains the async iterable in STACK[-2] and the raised exception in STACK[-1]. Both are popped. If the exception is not StopAsyncIteration, it is re-raised.

Added in version 3.8.

バージョン 3.11 で変更: Exception representation on the stack now consist of one, not three, items.

CLEANUP_THROW

Handles an exception raised during a throw() or close() call through the current frame. If STACK[-1] is an instance of StopIteration, pop three values from the stack and push its value member. Otherwise, re-raise STACK[-1].

Added in version 3.12.

BEFORE_ASYNC_WITH

Resolves __aenter__ and __aexit__ from STACK[-1]. Pushes __aexit__ and result of __aenter__() to the stack:

STACK.extend((__aexit__, __aenter__())

Added in version 3.5.

その他の命令コード

SET_ADD(i)

Implements:

item = STACK.pop()
set.add(STACK[-i], item)

Used to implement set comprehensions.

LIST_APPEND(i)

Implements:

item = STACK.pop()
list.append(STACK[-i], item)

Used to implement list comprehensions.

MAP_ADD(i)

Implements:

value = STACK.pop()
key = STACK.pop()
dict.__setitem__(STACK[-i], key, value)

Used to implement dict comprehensions.

Added in version 3.1.

バージョン 3.8 で変更: Map value is STACK[-1] and map key is STACK[-2]. Before, those were reversed.

SET_ADD, LIST_APPEND, MAP_ADD は、追加した値または key/value ペアをスタックから取り除きますが、コンテナオブジェクトはループの次のイテレーションで利用できるようにスタックに残しておきます。

RETURN_VALUE

Returns with STACK[-1] to the caller of the function.

RETURN_CONST(consti)

Returns with co_consts[consti] to the caller of the function.

Added in version 3.12.

YIELD_VALUE

Yields STACK.pop() from a 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.

SETUP_ANNOTATIONS

Checks whether __annotations__ is defined in locals(), if not it is set up to an empty dict. This opcode is only emitted if a class or module body contains variable annotations statically.

Added in version 3.6.

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.

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 f_lasti of the current frame.

Added in version 3.9.

バージョン 3.11 で変更: Exception representation on the stack now consist of one, not three, items.

PUSH_EXC_INFO

Pops a value from the stack. Pushes the current exception to the top of the stack. Pushes the value originally popped back to the stack. Used in exception handlers.

Added in version 3.11.

CHECK_EXC_MATCH

Performs exception matching for except. Tests whether the STACK[-2] is an exception matching STACK[-1]. Pops STACK[-1] and pushes the boolean result of the test.

Added in version 3.11.

CHECK_EG_MATCH

Performs exception matching for except*. Applies split(STACK[-1]) on the exception group representing STACK[-2].

In case of a match, pops two items from the stack and pushes the non-matching subgroup (None in case of full match) followed by the matching subgroup. When there is no match, pops one item (the match type) and pushes None.

Added in version 3.11.

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 context_manager.__exit__(*exc_info()) when an exception has occurred in a with statement.

Added in version 3.9.

バージョン 3.11 で変更: The __exit__ function is in position 4 of the stack rather than 7. Exception representation on the stack now consist of one, not three, items.

LOAD_ASSERTION_ERROR

Pushes AssertionError onto the stack. Used by the assert statement.

Added in version 3.9.

LOAD_BUILD_CLASS

Pushes builtins.__build_class__() onto the stack. It is later called to construct a class.

BEFORE_WITH

This opcode performs several operations before a with block starts. First, it loads __exit__() from the context manager and pushes it onto the stack for later use by WITH_EXCEPT_START. Then, __enter__() is called. Finally, the result of calling the __enter__() method is pushed onto the stack.

Added in version 3.11.

GET_LEN

Perform STACK.append(len(STACK[-1])).

Added in version 3.10.

MATCH_MAPPING

If STACK[-1] is an instance of collections.abc.Mapping (or, more technically: if it has the Py_TPFLAGS_MAPPING flag set in its tp_flags), push True onto the stack. Otherwise, push False.

Added in version 3.10.

MATCH_SEQUENCE

If STACK[-1] is an instance of collections.abc.Sequence and is not an instance of str/bytes/bytearray (or, more technically: if it has the Py_TPFLAGS_SEQUENCE flag set in its tp_flags), push True onto the stack. Otherwise, push False.

Added in version 3.10.

MATCH_KEYS

STACK[-1] is a tuple of mapping keys, and STACK[-2] is the match subject. If STACK[-2] contains all of the keys in STACK[-1], push a tuple containing the corresponding values. Otherwise, push None.

Added in version 3.10.

バージョン 3.11 で変更: Previously, this instruction also pushed a boolean value indicating success (True) or failure (False).

STORE_NAME(namei)

Implements name = STACK.pop(). namei is the index of name in the attribute co_names of the code object. The compiler tries to use STORE_FAST or STORE_GLOBAL if possible.

DELETE_NAME(namei)

Implements del name, where namei is the index into co_names attribute of the code object.

UNPACK_SEQUENCE(count)

Unpacks STACK[-1] into count individual values, which are put onto the stack right-to-left. Require there to be exactly count values.:

assert(len(STACK[-1]) == count)
STACK.extend(STACK.pop()[:-count-1:-1])

UNPACK_EX(counts)

Implements assignment with a starred target: Unpacks an iterable in 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 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. a, *b, c = d will be stored after execution as STACK.extend((a, b, c)).

STORE_ATTR(namei)

Implements:

obj = STACK.pop()
value = STACK.pop()
obj.name = value

where namei is the index of name in co_names of the code object.

DELETE_ATTR(namei)

Implements:

obj = STACK.pop()
del obj.name

where namei is the index of name into co_names of the code object.

STORE_GLOBAL(namei)

STORE_NAME と同じように動作しますが、 name をグローバルとして保存します。

DELETE_GLOBAL(namei)

DELETE_NAME と同じように動作しますが、グローバルの name を削除します。

LOAD_CONST(consti)

co_consts[consti] をスタックにプッシュします。

LOAD_NAME(namei)

Pushes the value associated with co_names[namei] onto the stack. The name is looked up within the locals, then the globals, then the builtins.

LOAD_LOCALS

Pushes a reference to the locals dictionary onto the stack. This is used to prepare namespace dictionaries for LOAD_FROM_DICT_OR_DEREF and LOAD_FROM_DICT_OR_GLOBALS.

Added in version 3.12.

LOAD_FROM_DICT_OR_GLOBALS(i)

Pops a mapping off the stack and looks up the value for co_names[namei]. If the name is not found there, looks it up in the globals and then the builtins, similar to LOAD_GLOBAL. This is used for loading global variables in annotation scopes within class bodies.

Added in version 3.12.

BUILD_TUPLE(count)

Creates a tuple consuming count items from the stack, and pushes the resulting tuple onto the stack.:

assert count > 0
STACK, values = STACK[:-count], STACK[-count:]
STACK.append(tuple(values))

BUILD_LIST(count)

BUILD_TUPLE と同じように動作しますが、この命令はリストを作り出します。

BUILD_SET(count)

BUILD_TUPLE と同じように動作しますが、この命令は set を作り出します。

BUILD_MAP(count)

Pushes a new dictionary object onto the stack. Pops 2 * count items so that the dictionary holds count entries: {..., 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.

BUILD_CONST_KEY_MAP(count)

The version of BUILD_MAP specialized for constant keys. Pops the top element on the stack which contains a tuple of keys, then starting from STACK[-2], pops count values to form values in the built dictionary.

Added in version 3.6.

BUILD_STRING(count)

Concatenates count strings from the stack and pushes the resulting string onto the stack.

Added in version 3.6.

LIST_EXTEND(i)

Implements:

seq = STACK.pop()
list.extend(STACK[-i], seq)

Used to build lists.

Added in version 3.9.

SET_UPDATE(i)

Implements:

seq = STACK.pop()
set.update(STACK[-i], seq)

Used to build sets.

Added in version 3.9.

DICT_UPDATE(i)

Implements:

map = STACK.pop()
dict.update(STACK[-i], map)

Used to build dicts.

Added in version 3.9.

DICT_MERGE(i)

Like DICT_UPDATE but raises an exception for duplicate keys.

Added in version 3.9.

LOAD_ATTR(namei)

If the low bit of namei is not set, this replaces STACK[-1] with getattr(STACK[-1], co_names[namei>>1]).

If the low bit of namei is set, this will attempt to load a method named co_names[namei>>1] from the STACK[-1] object. STACK[-1] is popped. This bytecode distinguishes two cases: if STACK[-1] has a method with the correct name, the bytecode pushes the unbound method and STACK[-1]. STACK[-1] will be used as the first argument (self) by CALL when calling the unbound method. Otherwise, NULL and the object returned by the attribute lookup are pushed.

バージョン 3.12 で変更: If the low bit of namei is set, then a NULL or self is pushed to the stack before the attribute or unbound method respectively.

LOAD_SUPER_ATTR(namei)

This opcode implements super(), both in its zero-argument and two-argument forms (e.g. super().method(), super().attr and super(cls, self).method(), super(cls, self).attr).

It pops three values from the stack (from top of stack down): - self: the first argument to the current method - cls: the class within which the current method was defined - the global super

With respect to its argument, it works similarly to LOAD_ATTR, except that namei is shifted left by 2 bits instead of 1.

The low bit of namei signals to attempt a method load, as with LOAD_ATTR, which results in pushing NULL and the loaded method. When it is unset a single value is pushed to the stack.

The second-low bit of namei, if set, means that this was a two-argument call to super() (unset means zero-argument).

Added in version 3.12.

COMPARE_OP(opname)

Performs a Boolean operation. The operation name can be found in cmp_op[opname].

IS_OP(invert)

Performs is comparison, or is not if invert is 1.

Added in version 3.9.

CONTAINS_OP(invert)

Performs in comparison, or not in if invert is 1.

Added in version 3.9.

IMPORT_NAME(namei)

Imports the module co_names[namei]. STACK[-1] and STACK[-2] are popped and provide the fromlist and level arguments of __import__(). The module object is pushed onto the stack. The current namespace is not affected: for a proper import statement, a subsequent STORE_FAST instruction modifies the namespace.

IMPORT_FROM(namei)

Loads the attribute co_names[namei] from the module found in STACK[-1]. The resulting object is pushed onto the stack, to be subsequently stored by a STORE_FAST instruction.

JUMP_FORWARD(delta)

バイトコードカウンタを delta だけ増加させます。

JUMP_BACKWARD(delta)

Decrements bytecode counter by delta. Checks for interrupts.

Added in version 3.11.

JUMP_BACKWARD_NO_INTERRUPT(delta)

Decrements bytecode counter by delta. Does not check for interrupts.

Added in version 3.11.

POP_JUMP_IF_TRUE(delta)

If STACK[-1] is true, increments the bytecode counter by delta. 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.

POP_JUMP_IF_FALSE(delta)

If STACK[-1] is false, increments the bytecode counter by delta. 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.

POP_JUMP_IF_NOT_NONE(delta)

If STACK[-1] is not None, increments the bytecode counter by delta. STACK[-1] is popped.

This opcode is a pseudo-instruction, replaced in final bytecode by the directed versions (forward/backward).

Added in version 3.11.

バージョン 3.12 で変更: This is no longer a pseudo-instruction.

POP_JUMP_IF_NONE(delta)

If STACK[-1] is None, increments the bytecode counter by delta. STACK[-1] is popped.

This opcode is a pseudo-instruction, replaced in final bytecode by the directed versions (forward/backward).

Added in version 3.11.

バージョン 3.12 で変更: This is no longer a pseudo-instruction.

FOR_ITER(delta)

STACK[-1] is an iterator. Call its __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.

LOAD_GLOBAL(namei)

co_names[namei>>1] という名前のグローバルをスタック上にロードします。

バージョン 3.11 で変更: If the low bit of namei is set, then a NULL is pushed to the stack before the global variable.

LOAD_FAST(var_num)

ローカルな co_varnames[var_num] への参照をスタックにプッシュします。

バージョン 3.12 で変更: This opcode is now only used in situations where the local variable is guaranteed to be initialized. It cannot raise UnboundLocalError.

LOAD_FAST_CHECK(var_num)

Pushes a reference to the local co_varnames[var_num] onto the stack, raising an UnboundLocalError if the local variable has not been initialized.

Added in version 3.12.

LOAD_FAST_AND_CLEAR(var_num)

Pushes a reference to the local co_varnames[var_num] onto the stack (or pushes NULL onto the stack if the local variable has not been initialized) and sets co_varnames[var_num] to NULL.

Added in version 3.12.

STORE_FAST(var_num)

Stores STACK.pop() into the local co_varnames[var_num].

DELETE_FAST(var_num)

ローカルな co_varnames[var_num] を削除します。

MAKE_CELL(i)

Creates a new cell in slot i. If that slot is nonempty then that value is stored into the new cell.

Added in version 3.11.

LOAD_CLOSURE(i)

Pushes a reference to the cell contained in slot i of the "fast locals" storage. The name of the variable is co_fastlocalnames[i].

Note that LOAD_CLOSURE is effectively an alias for LOAD_FAST. It exists to keep bytecode a little more readable.

バージョン 3.11 で変更: i is no longer offset by the length of co_varnames.

LOAD_DEREF(i)

Loads the cell contained in slot i of the "fast locals" storage. Pushes a reference to the object the cell contains on the stack.

バージョン 3.11 で変更: i is no longer offset by the length of co_varnames.

LOAD_FROM_DICT_OR_DEREF(i)

Pops a mapping off the stack and looks up the name associated with slot i of the "fast locals" storage in this mapping. If the name is not found there, loads it from the cell contained in slot i, similar to LOAD_DEREF. This is used for loading free variables in class bodies (which previously used LOAD_CLASSDEREF) and in annotation scopes within class bodies.

Added in version 3.12.

STORE_DEREF(i)

Stores STACK.pop() into the cell contained in slot i of the "fast locals" storage.

バージョン 3.11 で変更: i is no longer offset by the length of co_varnames.

DELETE_DEREF(i)

Empties the cell contained in slot i of the "fast locals" storage. Used by the del statement.

Added in version 3.2.

バージョン 3.11 で変更: i is no longer offset by the length of co_varnames.

COPY_FREE_VARS(n)

Copies the n free variables from the closure into the frame. Removes the need for special code on the caller's side when calling closures.

Added in version 3.11.

RAISE_VARARGS(argc)

Raises an exception using one of the 3 forms of the raise statement, depending on the value of argc:

0: raise (re-raise previous exception)

1: raise STACK[-1] (raise exception instance or type at STACK[-1])

2: raise STACK[-2] from STACK[-1] (raise exception instance or type at STACK[-2] with __cause__ set to STACK[-1])

CALL(argc)

Calls a callable object with the number of arguments specified by argc, including the named arguments specified by the preceding KW_NAMES, if any. On the stack are (in ascending order), either:

NULL

The callable

The positional arguments

The named arguments

or:

The callable

self

The remaining positional arguments

The named arguments

argc is the total of the positional and named arguments, excluding self when a NULL is not present.

CALL pops all arguments and the callable object off the stack, calls the callable object with those arguments, and pushes the return value returned by the callable object.

Added in version 3.11.

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. CALL_FUNCTION_EX pops all arguments and the callable object off the stack, calls the callable object with those arguments, and pushes the return value returned by the callable object.

Added in version 3.6.

PUSH_NULL

Pushes a NULL to the stack. Used in the call sequence to match the NULL pushed by LOAD_METHOD for non-method calls.

Added in version 3.11.

KW_NAMES(consti)

Prefixes CALL. Stores a reference to co_consts[consti] into an internal variable for use by CALL. co_consts[consti] must be a tuple of strings.

Added in version 3.11.

MAKE_FUNCTION(flags)

Pushes a new function object on the stack. From bottom to top, the consumed stack must consist of values if the argument carries a specified flag value

0x01 a tuple of default values for positional-only and positional-or-keyword parameters in positional order

0x02 a dictionary of keyword-only parameters' default values

0x04 a tuple of strings containing parameters' annotations

0x08 a tuple containing cells for free variables, making a closure

the code associated with the function (at STACK[-1])

バージョン 3.10 で変更: Flag value 0x04 is a tuple of strings instead of dictionary

バージョン 3.11 で変更: Qualified name at STACK[-1] was removed.

BUILD_SLICE(argc)

Pushes a slice object on the stack. argc must be 2 or 3. If it is 2, implements:

end = STACK.pop()
start = STACK.pop()
STACK.append(slice(start, stop))

if it is 3, implements:

step = STACK.pop()
end = STACK.pop()
start = STACK.pop()
STACK.append(slice(start, end, step))

See the slice() built-in function for more information.

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 EXTENDED_ARG are allowed, forming an argument from two-byte to four-byte.

FORMAT_VALUE(flags)

Used for implementing formatted literal strings (f-strings). Pops an optional fmt_spec from the stack, then a required value. flags is interpreted as follows:

(flags & 0x03) == 0x00: value is formatted as-is.

(flags & 0x03) == 0x01: call str() on value before formatting it.

(flags & 0x03) == 0x02: call repr() on value before formatting it.

(flags & 0x03) == 0x03: call ascii() on value before formatting it.

(flags & 0x04) == 0x04: pop fmt_spec from the stack and use it, else use an empty fmt_spec.

Formatting is performed using PyObject_Format(). The result is pushed on the stack.

Added in version 3.6.

MATCH_CLASS(count)

STACK[-1] is a tuple of keyword attribute names, STACK[-2] is the class being matched against, and STACK[-3] is the match subject. count is the number of positional sub-patterns.

Pop STACK[-1], STACK[-2], and STACK[-3]. If STACK[-3] is an instance of STACK[-2] and has the positional and keyword attributes required by count and STACK[-1], push a tuple of extracted attributes. Otherwise, push None.

Added in version 3.10.

バージョン 3.11 で変更: Previously, this instruction also pushed a boolean value indicating success (True) or failure (False).

RESUME(where)

A no-op. Performs internal tracing, debugging and optimization checks.

The where operand marks where the RESUME occurs:

0 The start of a function, which is neither a generator, coroutine nor an async generator

1 After a yield expression

2 After a yield from expression

3 After an await expression

Added in version 3.11.

RETURN_GENERATOR

Create a generator, coroutine, or async generator from the current frame. Used as first opcode of in code object for the above mentioned callables. Clear the current frame and return the newly created generator.

Added in version 3.11.

SEND(delta)

Equivalent to STACK[-1] = STACK[-2].send(STACK[-1]). Used in yield from and await statements.

If the call raises StopIteration, pop the top value from the stack, push the exception's value attribute, and increment the bytecode counter by delta.

Added in version 3.11.

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 (< HAVE_ARGUMENT and >= HAVE_ARGUMENT, respectively).

If your application uses pseudo instructions, use the hasarg collection instead.

バージョン 3.6 で変更: Now every instruction has an argument, but opcodes < HAVE_ARGUMENT ignore it. Before, only opcodes >= HAVE_ARGUMENT had an argument.

バージョン 3.12 で変更: Pseudo instructions were added to the dis module, and for them it is not true that comparison with HAVE_ARGUMENT indicates whether they use their arg.

CALL_INTRINSIC_1

Calls an intrinsic function with one argument. Passes STACK[-1] as the argument and sets STACK[-1] to the result. Used to implement functionality that is not performance critical.

The operand determines which intrinsic function is called:

Operand

説明

INTRINSIC_1_INVALID

Not valid

INTRINSIC_PRINT

Prints the argument to standard out. Used in the REPL.

INTRINSIC_IMPORT_STAR

Performs import * for the named module.

INTRINSIC_STOPITERATION_ERROR

Extracts the return value from a StopIteration exception.

INTRINSIC_ASYNC_GEN_WRAP

Wraps an aync generator value

INTRINSIC_UNARY_POSITIVE

Performs the unary + operation

INTRINSIC_LIST_TO_TUPLE

Converts a list to a tuple

INTRINSIC_TYPEVAR

Creates a typing.TypeVar

INTRINSIC_PARAMSPEC

Creates a typing.ParamSpec

INTRINSIC_TYPEVARTUPLE

Creates a typing.TypeVarTuple

INTRINSIC_SUBSCRIPT_GENERIC

Returns typing.Generic subscripted with the argument

INTRINSIC_TYPEALIAS

Creates a typing.TypeAliasType; used in the type statement. The argument is a tuple of the type alias's name, type parameters, and value.

Added in version 3.12.

CALL_INTRINSIC_2

Calls an intrinsic function with two arguments. Used to implement functionality that is not performance critical:

arg2 = STACK.pop()
arg1 = STACK.pop()
result = intrinsic2(arg1, arg2)
STACK.push(result)

The operand determines which intrinsic function is called:

Operand

説明

INTRINSIC_2_INVALID

Not valid

INTRINSIC_PREP_RERAISE_STAR

Calculates the ExceptionGroup to raise from a try-except*.

INTRINSIC_TYPEVAR_WITH_BOUND

Creates a typing.TypeVar with a bound.

INTRINSIC_TYPEVAR_WITH_CONSTRAINTS

Creates a typing.TypeVar with constraints.

INTRINSIC_SET_FUNCTION_TYPE_PARAMS

Sets the __type_params__ attribute of a function.

Added in version 3.12.

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.

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

SETUP_CLEANUP(target)

Like SETUP_FINALLY, but in case of an exception also pushes the last instruction (lasti) to the stack so that 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 target.

SETUP_WITH(target)

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

This variant is used in with and async with constructs, which push the return value of the context manager's __enter__() or __aenter__() to the stack.

POP_BLOCK

Marks the end of the code block associated with the last SETUP_FINALLY, SETUP_CLEANUP or SETUP_WITH.

JUMP

JUMP_NO_INTERRUPT

Undirected relative jump instructions which are replaced by their directed (forward/backward) counterparts by the assembler.

LOAD_METHOD

Optimized unbound method lookup. Emitted as a LOAD_ATTR opcode with a flag set in the arg.

命令コードコレクション

これらのコレクションは、自動でバイトコード命令を解析するために提供されています:

バージョン 3.12 で変更: The collections now contain pseudo instructions and instrumented instructions as well. These are opcodes with values >= MIN_PSEUDO_OPCODE and >= MIN_INSTRUMENTED_OPCODE.

dis.opname

命令コード名のリスト。バイトコードをインデックスに使って参照できます。

dis.opmap

命令コード名をバイトコードに対応づける辞書。

dis.cmp_op

すべての比較命令の名前のリスト。

dis.hasarg

Sequence of bytecodes that use their argument.

Added in version 3.12.

dis.hasconst

定数にアクセスするバイトコードのリスト。

dis.hasfree

Sequence of bytecodes that access a free 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.

dis.hasname

名前によって属性にアクセスするバイトコードのリスト。

dis.hasjrel

相対ジャンプ先を持つバイトコードのリスト。

dis.hasjabs

絶対ジャンプ先を持つバイトコードのリスト。

dis.haslocal

ローカル変数にアクセスするバイトコードのリスト。

dis.hascompare

ブール命令のバイトコードのリスト。

dis.hasexc

Sequence of bytecodes that set an exception handler.

Added in version 3.12.

pickletools --- Tools for pickle developers

ソースコード: Lib/pickletools.py [https://github.com/python/cpython/tree/3.12/Lib/pickletools.py]

このモジュールには、 pickle モジュールの詳細に関わる様々な定数や実装に関する長大なコメント、そして pickle 化されたデータを解析する上で有用な関数をいくつか定義しています。このモジュールの内容は pickle の実装に関わっている Python コア開発者にとって有用なものです; 普通の pickle 利用者にとっては、 pickletools モジュールはおそらく関係ないものでしょう。

コマンドラインの使い方

Added in version 3.2.

コマンドラインから実行するとき、python -m pickletools は 1 つもしくは複数の pickle ファイルの内容を逆アセンブルします。pickle 形式の詳細ではなく pickle に保存された Python オブジェクトを見たい場合は、そのコマンドではなく -m pickle を使いたいと思うかもしれません。しかし、調べたい pickle ファイルが信頼できないソースから来たものであるとき、-m pickletools は pickle のバイトコードを実行しないので、より安全な選択肢です。

例えば、 x.pickle ファイルに pickle 化されているタプル (1, 2) に対して実行すると次のようになります:

$ 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

コマンドラインオプション

-a, --annotate

注釈として短い命令コードの説明を各行に表示します。

-o, --output=<file>

出力結果を書き込むファイル名。

-l, --indentlevel=<num>

新しい MARK レベルのインデントに使われる空白の数。

-m, --memo

複数のオブジェクトが逆アセンブルされたとき、逆アセンブリ間でメモを保持します。

-p, --preamble=<preamble>

複数の pickle ファイルが指定されたとき、各逆アセンブリの前に与えられたプリアンブルを表示します。

プログラミングインターフェース

pickletools.dis(pickle, out=None, memo=None, indentlevel=4, annotate=0)

pickle の抽象的な逆アセンブリを file-like オブジェクト out (デフォルトは sys.stdout) に出力します。pickle は文字列または file-like オブジェクトです。memo は Python の辞書で、pickle のメモとして使われます; これは、pickle 処理を行う 1 つのオブジェクトが、複数の pickle にわたって逆アセンブルを行うために使われます。ストリーム上の MARK 命令コードが示す後続のレベルは、indentlevel 個の空白でインデントされます。annotate に非ゼロの値が与えられた場合、出力される各命令コードは短い命令コードに注釈が付けられます。annotate の値は、注釈の先頭の位置のヒントとして使われます。

バージョン 3.2 で変更: Added the annotate parameter.

pickletools.genops(pickle)

pickle 内の全ての opcode を取り出す イテレータ を返します。このイテレータは (opcode, arg, pos) の三つ組みからなる配列を返します。 opcode は OpcodeInfo クラスのインスタンスのクラスです。 arg は opcode の引数としてデコードされた Python オブジェクトの値です。 pos は opcode の場所を表す値です。 pickle は文字列でもファイル類似オブジェクトでもかまいません。

pickletools.optimize(picklestring)

使われていない PUT 命令コードを除去した上で、その新しい pickle 文字列を返します。最適化された pickle は、長さがより短く、転送時間がより少なく、必要とするストレージ領域がより狭く、unpickle 化がより効率的になります。

MS Windows 固有のサービス

この章では、MS Windows プラットフォーム上でのみ利用可能なモジュール群について記述します。

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

ファイル操作関連

コンソール I/O 関連

その多の関数

winreg --- Windows registry access

関数

定数

HKEY_* 定数

アクセス権限

64-bit 特有のアクセス権

値の型

レジストリハンドルオブジェクト

winsound --- Sound-playing interface for Windows

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

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 getpass module uses this in the implementation of the getpass() function.

ここに挙げた関数の詳細なドキュメントについては、プラットフォーム API ドキュメントで見つけることができます。

このモジュールは、通常版とワイド文字列版の両方のコンソールI/O APIを実装しています。通常版の API は ASCII 文字列のためのもので、国際化アプリケーションでは利用が制限されます。可能な限りワイド文字列版APIを利用するべきです。

バージョン 3.3 で変更: このモジュールの操作で以前は IOError が送出されていたところで OSError が送出されるようになりました。

ファイル操作関連

msvcrt.locking(fd, mode, nbytes)

Lock part of a file based on file descriptor fd from the C runtime. Raises 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 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.

引数 fd, mode, nbytes を指定して 監査イベント msvcrt.locking を送出します。

msvcrt.LK_LOCK

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, OSError is raised.

msvcrt.LK_NBLCK

msvcrt.LK_NBRLCK

指定されたバイト列にロックをかけます。指定領域がロックできなかった場合、 OSError が送出されます。

msvcrt.LK_UNLCK

指定されたバイト列のロックを解除します。指定領域はあらかじめロックされていなければなりません。

msvcrt.setmode(fd, flags)

ファイル記述子 fd に対して、行末文字の変換モードを設定します。テキストモードに設定するには、 flags を os.O_TEXT にします; バイナリモードにするには os.O_BINARY にします。

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 os.O_APPEND, os.O_RDONLY, and os.O_TEXT. The returned file descriptor may be used as a parameter to os.fdopen() to create a file object.

引数 handle, flags を指定して 監査イベント msvcrt.open_osfhandle を送出します。

msvcrt.get_osfhandle(fd)

Return the file handle for the file descriptor fd. Raises OSError if fd is not recognized.

引数 fd を指定して 監査イベント msvcrt.get_osfhandle を送出します。

コンソール I/O 関連

msvcrt.kbhit()

Return True if a keypress is waiting to be read.

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 Enter to be pressed. If the pressed key was a special function key, this will return '\000' or '\xe0'; the next call will return the keycode. The Control-C keypress cannot be read with this function.

msvcrt.getwch()

getch() のワイド文字列版。Unicode の値を返します。

msvcrt.getche()

Similar to getch(), but the keypress will be echoed if it represents a printable character.

msvcrt.getwche()

getche() のワイド文字列版。Unicode の値を返します。

msvcrt.putch(char)

バイト文字列 char をバッファリングを行わないでコンソールに出力します。

msvcrt.putwch(unicode_char)

putch() のワイド文字列版。Unicode の値を引数に取ります。

msvcrt.ungetch(char)

バイト文字列 char をコンソールバッファに "押し戻し (push back)" ます; これにより、押し戻された文字は getch() や getche() で次に読み出される文字になります。

msvcrt.ungetwch(unicode_char)

ungetch() のワイド文字列版。Unicode の値を引数に取ります。

その多の関数

msvcrt.heapmin()

Force the malloc() heap to clean itself up and return unused blocks to the operating system. On failure, this raises OSError.

msvcrt.CRT_ASSEMBLY_VERSION

The CRT Assembly version, from the crtassem.h header file.

msvcrt.VC_ASSEMBLY_PUBLICKEYTOKEN

The VC Assembly public key token, from the crtassem.h header file.

msvcrt.LIBRARIES_ASSEMBLY_NAME_PREFIX

The Libraries Assembly name prefix, from the crtassem.h header file.

winreg --- Windows registry access

これらの関数は Windows レジストリ API を Python から使えるようにします。プログラマがレジストリハンドルを明示的にクローズするのを忘れた場合でも、確実にハンドルがクローズされるようにするために、レジストリハンドルとして整数値ではなく ハンドルオブジェクト が使われます。

バージョン 3.3 で変更: このモジュールのいくつかの関数は以前は WindowsError を送出していました。それは今では OSError の別名です。

関数

このモジュールでは以下の関数を提供します:

winreg.CloseKey(hkey)

以前開かれたレジストリキーを閉じます。hkey 引数は以前開かれたレジストリキーを指定します。

注釈

このメソッドを使って (または hkey.Close() によって) hkey が閉じられなかった場合、Python が hkey オブジェクトを破壊する際に閉じられます。

winreg.ConnectRegistry(computer_name, key)

他のコンピュータ上にある事前に定義されたレジストリハンドルとの接続を確立し、 ハンドルオブジェクト を返します。

computer_name はリモートコンピュータの名前で、r"\\computername" の形式をとります。None の場合、ローカルのコンピュータが使われます。

key は、事前に定義された接続先のハンドルです。

戻り値は開かれたキーのハンドルです。関数が失敗した場合、 OSError 例外が送出されます。

引数 computer_name, key を指定して 監査イベント winreg.ConnectRegistry を送出します。

バージョン 3.3 で変更: 上記 を参照。

winreg.CreateKey(key, sub_key)

指定されたキーを生成するか開き、 ハンドルオブジェクト を返します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

sub_key はこのメソッドが開く、または新規作成するキーの名前です。

key が事前に定義されたキーのうちの一つなら、sub_key は None でかまいません。その場合、この関数に渡されるキーハンドルと同じハンドルが返されます。

キーがすでに存在する場合、この関数はその既存のキーを開きます。

戻り値は開かれたキーのハンドルです。関数が失敗した場合、 OSError 例外が送出されます。

引数 key, sub_key, access を指定して 監査イベント winreg.CreateKey を送出します。

引数 key を指定して 監査イベント winreg.OpenKey/result を送出します。

バージョン 3.3 で変更: 上記 を参照。

winreg.CreateKeyEx(key, sub_key, reserved=0, access=KEY_WRITE)

指定されたキーを生成するか開き、 ハンドルオブジェクト を返します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

sub_key はこのメソッドが開く、または新規作成するキーの名前です。

reserved は予約された整数で、 0 でなくてはなりません。デフォルト値は 0 です。

access は、 key に対して想定されるセキュリティアクセスを示すアクセスマスクを指定する整数です。デフォルトは KEY_WRITE です。その他の利用可能な値については アクセス権 を参照してください。

key が事前に定義されたキーのうちの一つなら、sub_key は None でかまいません。その場合、この関数に渡されるキーハンドルと同じハンドルが返されます。

キーがすでに存在する場合、この関数はその既存のキーを開きます。

戻り値は開かれたキーのハンドルです。関数が失敗した場合、 OSError 例外が送出されます。

引数 key, sub_key, access を指定して 監査イベント winreg.CreateKey を送出します。

引数 key を指定して 監査イベント winreg.OpenKey/result を送出します。

Added in version 3.2.

バージョン 3.3 で変更: 上記 を参照。

winreg.DeleteKey(key, sub_key)

指定されたキーを削除します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

sub_key は文字列で、key 引数によって指定されたキーのサブキーでなければなりません。この値は None であってはならず、キーはサブキーを持っていなくてもかまいません。

このメソッドはサブキーをもつキーを削除することはできません。

このメソッドの実行が成功すると、キー全体が、その値すべてを含めて削除されます。このメソッドが失敗した場合、 OSError 例外が送出されます。

Raises an auditing event winreg.DeleteKey with arguments key, sub_key, access.

バージョン 3.3 で変更: 上記 を参照。

winreg.DeleteKeyEx(key, sub_key, access=KEY_WOW64_64KEY, reserved=0)

指定されたキーを削除します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

sub_key は key 引数によって指定された key の subkey でなければなりません。この値は None であってはなりません。また、key は subkey を持たないかもしれません。

reserved は予約された整数で、 0 でなくてはなりません。デフォルト値は 0 です。

access は、 key に対して想定されるセキュリティアクセスを示すアクセスマスクを指定する整数です。デフォルトは KEY_WOW64_64KEY です。32 bit Windows では、WOW64 定数は無視されます。その他の利用可能な値については アクセス権 を参照してください。

このメソッドはサブキーをもつキーを削除することはできません。

このメソッドの実行が成功すると、キー全体が、その値すべてを含めて削除されます。このメソッドが失敗した場合、 OSError 例外が送出されます。

サポートされていない Windows バージョンでは、 NotImplementedError 例外を発生させます。

Raises an auditing event winreg.DeleteKey with arguments key, sub_key, access.

Added in version 3.2.

バージョン 3.3 で変更: 上記 を参照。

winreg.DeleteValue(key, value)

レジストリキーから指定された名前つきの値を削除します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

value は削除したい値を指定するための文字列です。

引数 key, value を指定して 監査イベント winreg.DeleteValue を送出します。

winreg.EnumKey(key, index)

開かれているレジストリキーのサブキーを列挙し、文字列で返します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

index は整数値で、取得するキーのインデクスを指定します。

この関数は、呼び出されるたびに一つのサブキーの名前を取得します。この関数は通常、これ以上値がないことを示す OSError 例外が送出されるまで繰り返し呼び出されます。

引数 key, index を指定して 監査イベント winreg.EnumKey を送出します。

バージョン 3.3 で変更: 上記 を参照。

winreg.EnumValue(key, index)

開かれているレジストリキーの値を列挙し、タプルで返します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

index は整数値で、取得する値のインデクスを指定します。

この関数は、呼び出されるたびに一つのサブキーの名前を取得します。この関数は通常、これ以上値がないことを示す OSError 例外が送出されるまで繰り返し呼び出されます。

結果は 3 要素のタプルになります:

インデックス

意味

0

値の名前を指定する文字列

1

値のデータを保持するためのオブジェクトで、その型は背後のレジストリ型に依存します

2

値のデータ型を指定する整数です (SetValueEx() のドキュメント内のテーブルを参照してください)

引数 key, index を指定して 監査イベント winreg.EnumValue を送出します。

バージョン 3.3 で変更: 上記 を参照。

winreg.ExpandEnvironmentStrings(str)

REG_EXPAND_SZ のように、環境変数プレースホルダ %NAME% を文字列で展開します:

>>> ExpandEnvironmentStrings('%windir%')
'C:\\Windows'

引数 str を指定して 監査イベント winreg.ExpandEnvironmentStrings を送出します。

winreg.FlushKey(key)

キーのすべての属性をレジストリに書き込みます。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

キーを変更するために FlushKey() を呼ぶ必要はありません。レジストリの変更は怠惰なフラッシュ機構 (lazy flusher) を使ってフラッシュされます。また、システムの遮断時にもディスクにフラッシュされます。 CloseKey() と違って、 FlushKey() メソッドはレジストリに全てのデータを書き終えたときにのみ返ります。アプリケーションは、レジストリへの変更を絶対に確実にディスク上に反映させる必要がある場合にのみ、 FlushKey() を呼ぶべきです。

注釈

FlushKey() を呼び出す必要があるかどうか分からない場合、おそらくその必要はありません。

winreg.LoadKey(key, sub_key, file_name)

指定されたキーの下にサブキーを生成し、サブキーに指定されたファイルのレジストリ情報を記録します。

key は ConnectRegistry() が返したハンドルか、定数 HKEY_USERS と HKEY_LOCAL_MACHINE のどちらかです。

sub_key は記録先のサブキーを指定する文字列です。

file_name はレジストリデータを読み出すためのファイル名です。このファイルは SaveKey() 関数で生成されたファイルでなくてはなりません。ファイル割り当てテーブル (FAT) ファイルシステム下では、ファイル名は拡張子を持っていてはなりません。

A call to LoadKey() fails if the calling process does not have the SE_RESTORE_PRIVILEGE privilege. Note that privileges are different from permissions -- see the RegLoadKey documentation [https://msdn.microsoft.com/en-us/library/ms724889%28v=VS.85%29.aspx] for more details.

key が ConnectRegistry() によって返されたハンドルの場合、 file_name に指定されたパスはリモートコンピュータに対する相対パス名になります。

引数 key, sub_key, file_name を指定して 監査イベント winreg.LoadKey を送出します。

winreg.OpenKey(key, sub_key, reserved=0, access=KEY_READ)

winreg.OpenKeyEx(key, sub_key, reserved=0, access=KEY_READ)

指定されたキーを開き、 ハンドルオブジェクト を返します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

sub_key は開くサブキーを指定する文字列です。

reserved は予約された整数で、 0 でなくてはなりません。デフォルト値は 0 です。

access は、 key に対して想定されるセキュリティアクセスを示すアクセスマスクを指定する整数です。デフォルトは KEY_READ です。その他の利用可能な値については アクセス権 を参照してください。

指定されたキーへの新しいハンドルが返されます。

この関数が失敗すると、 OSError が送出されます。

引数 key, sub_key, access を指定して 監査イベント winreg.OpenKey を送出します。

引数 key を指定して 監査イベント winreg.OpenKey/result を送出します。

バージョン 3.2 で変更: 名前付き引数が使用できるようになりました。

バージョン 3.3 で変更: 上記 を参照。

winreg.QueryInfoKey(key)

キーに関する情報をタプルとして返します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

結果は 3 要素のタプルになります:

インデックス

意味

0

このキーが持つサブキーの数を表す整数。

1

このキーが持つ値の数を表す整数。

2

最後のキーの変更が (あれば) いつだったかを表す整数で、1601 年 1 月 1 日からの 100 ナノ秒単位で数えたもの。

引数 key を指定して 監査イベント winreg.QueryInfoKey を送出します。

winreg.QueryValue(key, sub_key)

キーに対する、名前付けられていない値を文字列で取得します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

sub_key は値が関連付けられているサブキーの名前を保持する文字列です。この引数が None または空文字列の場合、この関数は key で指定されたキーに対して SetValue() メソッドで設定された値を取得します。

レジストリ中の値は名前、型、およびデータから構成されています。このメソッドはあるキーのデータ中で、名前 NULL をもつ最初の値を取得します。しかし背後のAPI 呼び出しは型情報を返しません。なので、可能ならいつでも QueryValueEx() を使うべきです。

引数 key, sub_key, value_name を指定して 監査イベント winreg.QueryValue を送出します。

winreg.QueryValueEx(key, value_name)

開かれたレジストリキーに関連付けられている、指定した名前の値に対して、型およびデータを取得します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

value_name は要求する値を指定する文字列です。

結果は 2 つの要素からなるタプルです:

インデックス

意味

0

レジストリ要素の値。

1

この値のレジストリ型を表す整数。 (SetValueEx() のドキュメント内のテーブルを参照してください。)

引数 key, sub_key, value_name を指定して 監査イベント winreg.QueryValue を送出します。

winreg.SaveKey(key, file_name)

指定されたキーと、そのサブキー全てを指定したファイルに保存します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

file_name はレジストリデータを保存するファイルの名前です、このファイルはすでに存在していてはいけません。このファイル名が拡張子を含んでいる場合、 LoadKey() メソッドは、FAT ファイルシステムを使うことができません。

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 [https://msdn.microsoft.com/en-us/library/ms724878%28v=VS.85%29.aspx] for more details.

この関数は security_attributes を NULL にして API に渡します。

引数 key, file_name を指定して 監査イベント winreg.SaveKey を送出します。

winreg.SetValue(key, sub_key, type, value)

値を指定したキーに関連付けます。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

sub_key は値が関連付けられているサブキーの名前を表す文字列です。

type はデータの型を指定する整数です。現状では、この値は REG_SZ でなければならず、これは文字列だけがサポートされていることを示します。他のデータ型をサポートするには SetValueEx() を使ってください。

value は新たな値を指定する文字列です。

sub_key 引数で指定されたキーが存在しなければ、SetValue 関数で生成されます。

値の長さは利用可能なメモリによって制限されます。(2048 バイト以上の) 長い値はファイルに保存して、そのファイル名を設定レジストリに保存するべきです。そうすればレジストリを効率的に動作させる役に立ちます。

key 引数に指定されたキーは KEY_SET_VALUE アクセスで開かれていなければなりません。

引数 key, sub_key, type, value を指定して 監査イベント winreg.SetValue を送出します。

winreg.SetValueEx(key, value_name, reserved, type, value)

開かれたレジストリキーの値フィールドにデータを記録します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

value_name は値が関連付けられているサブキーの名前を表す文字列です。

reserved は何もしません - API には常にゼロが渡されます。

type はデータの型を指定する整数です。利用できる型については 値の型 を参照してください。

value は新たな値を指定する文字列です。

このメソッドではまた、指定されたキーに対して、さらに別の値や型情報を設定することができます。 key 引数で指定されたキーは KEY_SET_VALUE アクセスで開かれていなければなりません。

キーを開くには、 CreateKey() または OpenKey() メソッドを使ってください。

値の長さは利用可能なメモリによって制限されます。(2048 バイト以上の) 長い値はファイルに保存して、そのファイル名を設定レジストリに保存するべきです。そうすればレジストリを効率的に動作させる役に立ちます。

引数 key, sub_key, type, value を指定して 監査イベント winreg.SetValue を送出します。

winreg.DisableReflectionKey(key)

64ビット OS上で動作している 32bit プロセスに対するレジストリリフレクションを無効にします。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

32bit OS上では一般的に NotImplementedError 例外を発生させます。

key がリフレクションリストに無い場合は、この関数は成功しますが効果はありません。あるキーのリフレクションを無効にしても、そのキーのサブキーのリフレクションには全く影響しません。

引数 key を指定して 監査イベント winreg.DisableReflectionKey を送出します。

winreg.EnableReflectionKey(key)

指定された、リフレクションが無効にされたキーのリフレクションを再び有効にします。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

32bit OS上では一般的に NotImplementedError 例外を発生させます。

あるキーのリフレクションを再開しても、その全てのサブキーには影響しません。

引数 key を指定して 監査イベント winreg.EnableReflectionKey を送出します。

winreg.QueryReflectionKey(key)

指定されたキーのリフレクション状態を確認します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

リフレクションが無効になっている場合、True を返します。

32bit OS上では一般的に NotImplementedError 例外を発生させます。

引数 key を指定して 監査イベント winreg.QueryReflectionKey を送出します。

定数

The following constants are defined for use in many winreg functions.

HKEY_* 定数

winreg.HKEY_CLASSES_ROOT

このキー以下のレジストリエントリは、ドキュメントのタイプ（またはクラス）や、それに関連付けられたプロパティを定義しています。シェルと COM アプリケーションがこの情報を利用します。

winreg.HKEY_CURRENT_USER

このキー以下のレジストリエントリは、現在のユーザーの設定を定義します。この設定には、環境変数、プログラムグループに関するデータ、カラー、プリンター、ネットワーク接続、アプリケーション設定などが含まれます。

winreg.HKEY_LOCAL_MACHINE

このキー以下のレジストリエントリは、コンピュータの物理的な状態を定義します。これには、バスタイプ、システムメモリ、インストールされているソフトウェアやハードウェアが含まれます。

winreg.HKEY_USERS

このキー以下のレジストリエントリは、ローカルコンピュータの新規ユーザーのためのデフォルト設定や、現在のユーザーの設定を定義しています。

winreg.HKEY_PERFORMANCE_DATA

このキー以下のレジストリエントリは、パフォーマンスデータへのアクセスを可能にしています。実際にはデータはレジストリには格納されていません。レジストリ関数がシステムにソースからデータを集めさせます。

winreg.HKEY_CURRENT_CONFIG

ローカルコンピュータシステムの現在のハードウェアプロファイルに関する情報を含みます。

winreg.HKEY_DYN_DATA

このキーは Windows の 98 以降のバージョンでは利用されていません。

アクセス権限

より詳しい情報については、 Registry Key Security and Access [https://msdn.microsoft.com/en-us/library/ms724878%28v=VS.85%29.aspx] を参照してください。

winreg.KEY_ALL_ACCESS

STANDARD_RIGHTS_REQUIRED (KEY_QUERY_VALUE, KEY_SET_VALUE, KEY_CREATE_SUB_KEY, KEY_ENUMERATE_SUB_KEYS, KEY_NOTIFY, KEY_CREATE_LINK) アクセス権限の組み合わせ。

winreg.KEY_WRITE

STANDARD_RIGHTS_WRITE (KEY_SET_VALUE, KEY_CREATE_SUB_KEY) アクセス権限の組み合わせ。

winreg.KEY_READ

STANDARD_RIGHTS_READ (KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, KEY_NOTIFY) アクセス権限の組み合わせ。

winreg.KEY_EXECUTE

KEY_READ と同じ。

winreg.KEY_QUERY_VALUE

レジストリキーの値を問い合わせるのに必要。

winreg.KEY_SET_VALUE

レジストリの値を作成、削除、設定するのに必要。

winreg.KEY_CREATE_SUB_KEY

レジストリキーのサブキーを作るのに必要。

winreg.KEY_ENUMERATE_SUB_KEYS

レジストリキーのサブキーを列挙するのに必要。

winreg.KEY_NOTIFY

レジストリキーやそのサブキーに対する変更通知を要求するのに必要。

winreg.KEY_CREATE_LINK

システムでの利用のために予約されている。

64-bit 特有のアクセス権

より詳しい情報については、 Accessing an Alternate Registry View [https://msdn.microsoft.com/en-us/library/aa384129(v=VS.85).aspx] を参照してください。

winreg.KEY_WOW64_64KEY

64 bit Windows 上のアプリケーションが、64 bit のレジストリビュー上で操作する事を示します。32 bit Windows では、この定数は無視されます。

winreg.KEY_WOW64_32KEY

64 bit Windows 上のアプリケーションが、32 bit のレジストリビュー上で操作する事を示します。32 bit Windows では、この定数は無視されます。

値の型

より詳しい情報については、 Registry Value Types [https://msdn.microsoft.com/en-us/library/ms724884%28v=VS.85%29.aspx] を参照してください。

winreg.REG_BINARY

何らかの形式のバイナリデータ。

winreg.REG_DWORD

32 ビットの数。

winreg.REG_DWORD_LITTLE_ENDIAN

32 ビットのリトルエンディアン形式の数。REG_DWORD と等価。

winreg.REG_DWORD_BIG_ENDIAN

32 ビットのビッグエンディアン形式の数。

winreg.REG_EXPAND_SZ

環境変数を参照している、ヌル文字で終端された文字列。(%PATH%)。

winreg.REG_LINK

Unicode のシンボリックリンク。

winreg.REG_MULTI_SZ

ヌル文字で終端された文字列からなり、二つのヌル文字で終端されている配列。 (Python はこの終端の処理を自動的に行います。)

winreg.REG_NONE

定義されていない値の形式。

winreg.REG_QWORD

64 ビットの数。

Added in version 3.6.

winreg.REG_QWORD_LITTLE_ENDIAN

64 ビットのリトルエンディアン形式の数。REG_QWORD と等価。

Added in version 3.6.

winreg.REG_RESOURCE_LIST

デバイスドライバリソースのリスト。

winreg.REG_FULL_RESOURCE_DESCRIPTOR

ハードウェアセッティング。

winreg.REG_RESOURCE_REQUIREMENTS_LIST

ハードウェアリソースリスト。

winreg.REG_SZ

ヌル文字で終端された文字列。

レジストリハンドルオブジェクト

このオブジェクトは Windows の HKEY オブジェクトをラップし、オブジェクトが破壊されたときに自動的にハンドルを閉じます。オブジェクトの Close() メソッドと CloseKey() 関数のどちらも、後始末がきちんと行われることを保証するために呼び出すことができます。

このモジュールのレジストリ関数は全て、これらのハンドルオブジェクトの一つを返します。

このモジュールのレジストリ関数でハンドルオブジェクトを受理するものは全て整数も受理しますが、ハンドルオブジェクトを利用することを推奨します。

Handle objects provide semantics for __bool__() -- thus

if handle:
    print("Yes")

は、ハンドルが現在有効な (閉じられたり切り離されたりしていない) 場合には Yes となります。

ハンドルオブジェクトは、比較の意味構成もサポートしています。このため、複数のハンドルオブジェクトが参照している下層の Windows ハンドル値が同じ場合、それらのハンドルオブジェクト同士の比較は真になります。

ハンドルオブジェクトは (例えば組み込みの int() 関数を使って) 整数に変換することができます。この場合、背後の Windows ハンドル値が返されます、また、 Detach() メソッドを使って整数のハンドル値を返させると同時に、ハンドルオブジェクトから Windows ハンドルを切り離すこともできます。

PyHKEY.Close()

背後の Windows ハンドルを閉じます。

ハンドルがすでに閉じられていてもエラーは送出されません。

PyHKEY.Detach()

ハンドルオブジェクトから Windows ハンドルを切り離します。

切り離される以前にそのハンドルを保持していた整数オブジェクトが返されます。ハンドルがすでに切り離されていたり閉じられていたりした場合、ゼロが返されます。

この関数を呼び出した後、ハンドルは確実に無効化されますが、閉じられるわけではありません。背後の Win32 ハンドルがハンドルオブジェクトよりも長く維持される必要がある場合にはこの関数を呼び出すとよいでしょう。

Raises an auditing event winreg.PyHKEY.Detach with argument key.

PyHKEY.__enter__()

PyHKEY.__exit__(*exc_info)

HKEY オブジェクトは __enter__(), __exit__() メソッドを実装していて、 with 文のためのコンテキストプロトコルをサポートしています:

with OpenKey(HKEY_LOCAL_MACHINE, "foo") as key:
    ...  # work with key

このコードは、 with ブロックから抜けるときに自動的に key を閉じます。

winsound --- Sound-playing interface for Windows

winsound モジュールは Windows プラットフォーム上で提供されている基本的な音声再生機構へのアクセス手段を提供します。このモジュールではいくつかの関数と定数が定義されています。

winsound.Beep(frequency, duration)

PC のスピーカを鳴らします。引数 frequency は鳴らす音の周波数の指定で、単位は Hz です。値は 37 から 32,767 でなくてはなりません。引数 duration は音を何ミリ秒鳴らすかの指定です。システムがスピーカを鳴らすことができない場合、例外 RuntimeError が送出されます。

winsound.PlaySound(sound, flags)

Call the underlying PlaySound() function from the Platform API. The sound parameter may be a filename, a system sound alias, audio data as a bytes-like object, or None. Its interpretation depends on the value of flags, which can be a bitwise ORed combination of the constants described below. If the sound parameter is None, any currently playing waveform sound is stopped. If the system indicates an error, RuntimeError is raised.

winsound.MessageBeep(type=MB_OK)

Call the underlying MessageBeep() function from the Platform API. This plays a sound as specified in the registry. The type argument specifies which sound to play; possible values are -1, MB_ICONASTERISK, MB_ICONEXCLAMATION, MB_ICONHAND, MB_ICONQUESTION, and MB_OK, all described below. The value -1 produces a "simple beep"; this is the final fallback if a sound cannot be played otherwise. If the system indicates an error, RuntimeError is raised.

winsound.SND_FILENAME

sound パラメタが WAV ファイル名であることを示します。 SND_ALIAS と同時に使ってはいけません。

winsound.SND_ALIAS

引数 sound はレジストリにある音声データに関連付けられた名前であることを示します。指定した名前がレジストリ上にない場合、定数 SND_NODEFAULT が同時に指定されていない限り、システム標準の音声データが再生されます。標準の音声データが登録されていない場合、例外 RuntimeError が送出されます。 SND_FILENAME と同時に使ってはいけません。

全ての Win32 システムは少なくとも以下の名前をサポートします; ほとんどのシステムでは他に多数あります:

PlaySound() name

対応するコントロールパネルでの音声名

'SystemAsterisk'

Asterisk

'SystemExclamation'

Exclamation

'SystemExit'

Exit Windows

'SystemHand'

Critical Stop

'SystemQuestion'

Question

例えば:

import winsound
# Play Windows exit sound.
winsound.PlaySound("SystemExit", winsound.SND_ALIAS)

# Probably play Windows default sound, if any is registered (because
# "*" probably isn't the registered name of any sound).
winsound.PlaySound("*", winsound.SND_ALIAS)

winsound.SND_LOOP

音声データを繰り返し再生します。システムがブロックしないようにするため、 SND_ASYNC フラグを同時に使わなくてはなりません。 SND_MEMORY と同時に使うことはできません。

winsound.SND_MEMORY

PlaySound() の引数 sound が bytes-like オブジェクト の形式をとった WAV ファイルのメモリ上のイメージであることを示します。

注釈

このモジュールはメモリ上のイメージを非同期に再生する機能をサポートしていません。従って、このフラグと SND_ASYNC を組み合わせると例外 RuntimeError が送出されます。

winsound.SND_PURGE

指定した音声の全てのインスタンスについて再生処理を停止します。

注釈

このフラグは現代のWindowsプラットフォームではサポートされていません。

winsound.SND_ASYNC

音声を非同期に再生するようにして、関数呼び出しを即座に返します。

winsound.SND_NODEFAULT

指定した音声が見つからなかった場合にシステム標準の音声を鳴らさないようにします。

winsound.SND_NOSTOP

現在鳴っている音声を中断させないようにします。

winsound.SND_NOWAIT

サウンドドライバがビジー状態にある場合、関数がすぐ返るようにします。

注釈

このフラグは現代のWindowsプラットフォームではサポートされていません。

winsound.MB_ICONASTERISK

音声 SystemDefault を再生します。

winsound.MB_ICONEXCLAMATION

音声 SystemExclamation を再生します。

winsound.MB_ICONHAND

音声 SystemHand を再生します。

winsound.MB_ICONQUESTION

音声 SystemQuestion を再生します。

winsound.MB_OK

音声 SystemDefault を再生します。

Unix 固有のサービス

本章に記述されたモジュールは、Unix オペレーティングシステム、あるいはそれから派生した多くのものに固有の機能のためのインターフェースを提供します。その概要を以下に述べます:

posix --- The most common POSIX system calls

ラージファイルのサポート

注目すべきモジュールの内容

pwd --- The password database

grp --- The group database

termios --- POSIX style tty control

使用例

tty --- Terminal control functions

pty --- Pseudo-terminal utilities

使用例

fcntl --- The fcntl and ioctl system calls

resource --- Resource usage information

リソースの制限

リソースの使用状態

syslog --- Unix syslog library routines

使用例

シンプルな例

posix --- The most common POSIX system calls

このモジュールはオペレーティングシステムの機能のうち、C 言語標準および (Unix インターフェースをほんの少し隠蔽した) POSIX 標準で標準化されている機能に対するアクセス機構を提供します。

利用可能な環境: Unix。

このモジュールを直接インポートしてはいけません。 その代わりに、このインターフェースの ポータブル 版である os モジュールをインポートしてください。 Unix では、os モジュールは posix インターフェースのスーパーセットを提供しています。非 Unix オペレーティングシステムでは、 posix モジュールは利用できませんが、その一部分は os インターフェースを通して常に利用可能です。一度 os をインポートし posix の代わりにそれを使えば、パフォーマンス上の代償は ありません 。加えて os は、 os.environ の要素が変更されたときに putenv() を呼び出すなどの追加の機能も提供します。

エラーは例外として報告されます; よくある例外は型エラーです。一方、システムコールから報告されたエラーは以下に述べるように OSError を送出します。

ラージファイルのサポート

いくつかのオペレーティングシステム (AIX および Solaris が含まれます) は、 int および long を 32 ビット値とする C プログラムモデルで 2GB を超えるサイズのファイルのサポートを提供しています。このサポートは典型的には関連するサイズとオフセットの組合せを 64-bit 値として定義することで実現しています。このようなファイルは時にラージファイル (large files) と呼ばれます。

Python では、 off_t のサイズが long より大きく、かつ long long が少なくとも off_t と同じくらい大きなサイズであるとき、ラージファイルのサポートが有効になります。この場合、ファイルのサイズ、オフセットおよび Python の通常整数型の範囲を超えるような値の表現には Python の長整数型が使われます。このモードを有効にするのに、 configure で Python のコンパイルに特定のコンパイルフラグを必要とするかもしれません。例えば、Solaris 2.6 および 2.7 では、以下のようにする必要があります:

CFLAGS="`getconf LFS_CFLAGS`" OPT="-g -O2 $CFLAGS" \
        ./configure

ラージファイル対応の Linux システムでは、以下のようにすれば良いでしょう:

CFLAGS='-D_LARGEFILE64_SOURCE -D_FILE_OFFSET_BITS=64' OPT="-g -O2 $CFLAGS" \
        ./configure

注目すべきモジュールの内容

os モジュールのドキュメントで説明されている多数の関数に加え、 posix では以下のデータ項目を定義しています:

posix.environ

インタプリタが起動したときの環境を表す文字列辞書です。キーと値は Unix ではバイト列、 Windows では文字列です。例えば、 environ[b'HOME'] (Windows では environ['HOME']) はホームディレクトリのパス名で、 C の getenv("HOME") と同じ値です。

この辞書を編集しても、 execv() 、 popen() 、 system() で渡された環境変数文字列には影響は与えません; 環境変数を変更したい場合は、 environ を execve() に渡すか、変数への代入文と export 文を system() や popen() に渡すコマンド文字列に追加してください。

バージョン 3.2 で変更: Unix ではキーと値はバイト列になりました。

注釈

os モジュールでは、もう一つの os.environ 実装を提供しており、環境変数が変更された場合、その内容を更新するようになっています。 environ を更新した場合、この辞書は古い内容を表していることになってしまうので、このことにも注意してください。 posix モジュール版を直接アクセスするよりも、 os モジュール版を使う方が推奨されています。

pwd --- The password database

このモジュールは Unix のユーザアカウントとパスワードのデータベースへのアクセスを提供します。全ての Unix 系 OS で利用できます。

Availability: Unix, not Emscripten, not WASI.

パスワードデータベースの各エントリはタプルのようなオブジェクトで提供され、それぞれの属性は passwd 構造体のメンバに対応しています(下の属性欄については、<pwd.h> を見てください):

インデックス

属性

意味

0

pw_name

ログイン名

1

pw_passwd

暗号化されたパスワード(optional))

2

pw_uid

ユーザID(UID)

3

pw_gid

グループID(GID)

4

pw_gecos

実名またはコメント

5

pw_dir

ホームディレクトリ

6

pw_shell

シェル

UIDとGIDは整数で、それ以外は全て文字列です。検索したエントリが見つからないと KeyError が発生します。

注釈

In traditional Unix the field pw_passwd usually contains a password encrypted with a DES derived algorithm (see module crypt). However most modern unices use a so-called shadow password system. On those unices the pw_passwd field only contains an asterisk ('*') or the letter 'x' where the encrypted password is stored in a file /etc/shadow which is not world readable. Whether the pw_passwd field contains anything useful is system-dependent. If available, the spwd module should be used where access to the encrypted password is required.

このモジュールでは以下の内容を定義しています:

pwd.getpwuid(uid)

与えられたUIDに対応するパスワードデータベースのエントリを返します。

pwd.getpwnam(name)

与えられたユーザ名に対応するパスワードデータベースのエントリを返します。

pwd.getpwall()

パスワードデータベースの全てのエントリを、任意の順番で並べたリストを返します。

参考

grp モジュール

このモジュールに似た、グループデータベースへのアクセスを提供するモジュール。

Module spwd

An interface to the shadow password database, similar to this.

grp --- The group database

このモジュールでは Unix グループ (group) データベースへのアクセス機構を提供します。全ての Unix バージョンで利用可能です。

Availability: Unix, not Emscripten, not WASI.

このモジュールはグループデータベースのエントリをタプルに似たオブジェクトとして報告されます。このオブジェクトの属性は group 構造体の各メンバ (以下の属性フィールド、<grp.h> を参照) に対応します:

インデックス

属性

意味

0

gr_name

グループ名

1

gr_passwd

(暗号化された) グループパスワード; しばしば空文字列になります

2

gr_gid

数字のグループ ID

3

gr_mem

グループメンバの全てのユーザ名

gid は整数、名前およびパスワードは文字列、そしてメンバリストは文字列からなるリストです。 (ほとんどのユーザは、パスワードデータベースで自分が入れられているグループのメンバとしてグループデータベース内では明示的に列挙されていないので注意してください。完全なメンバ情報を取得するには両方のデータベースを調べてください。また、 + や - で始まる gr_name は YP/NIS 参照である可能性があり、 getgrnam() や getgrgid() でアクセスできないかもしれないことにも注意してください。)

このモジュールでは以下の内容を定義しています:

grp.getgrgid(id)

与えられたグループ ID に対するグループデータベースエントリを返します。要求したエントリが見つからなかった場合、 KeyError が送出されます。

バージョン 3.10 で変更: TypeError is raised for non-integer arguments like floats or strings.

grp.getgrnam(name)

与えられたグループ名に対するグループデータベースエントリを返します。要求したエントリが見つからなかった場合、 KeyError が送出されます。

grp.getgrall()

全ての入手可能なグループエントリを返します。順番は決まっていません。

参考

pwd モジュール

このモジュールと類似の、ユーザデータベースへのインターフェース。

Module spwd

An interface to the shadow password database, similar to this.

termios --- POSIX style tty control

このモジュールでは端末 I/O 制御のための POSIX 準拠の関数呼び出しインターフェースを提供します。これら呼び出しのための完全な記述については、 Unix マニュアルページの termios(3) [https://manpages.debian.org/termios(3)] を参照してください。これは POSIX termios 形式の端末制御をサポートしていてインストール時に有効にした Unix のバージョンでのみ利用可能です。

利用可能な環境: Unix。

このモジュールの関数は全て、ファイル記述子 fd を最初の引数としてとります。この値は、 sys.stdin.fileno() が返すような整数のファイル記述子でも、 sys.stdin 自体のような file object でもかまいません。

このモジュールではまた、モジュールで提供されている関数を使う上で必要となる全ての定数を定義しています; これらの定数は C の対応する関数と同じ名前を持っています。これらの端末制御インターフェースを利用する上でのさらなる情報については、あなたのシステムのドキュメンテーションを参考にしてください。

このモジュールには、以下の関数が定義されています:

termios.tcgetattr(fd)

ファイル記述子 fd の端末属性を含むリストを返します。その形式は: [iflag, oflag, cflag, lflag, ispeed, ospeed, cc] です。 cc は端末特殊文字のリストです (それぞれ長さ 1 の文字列です。ただしインデクス VMIN および VTIME の内容は、それらのフィールドが定義されていた場合整数の値となります)。端末設定フラグおよび端末速度の解釈、および配列 cc のインデクス検索は、 termios で定義されているシンボル定数を使って行わなければなりません。

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 tcgetattr(). The when argument determines when the attributes are changed:

termios.TCSANOW

Change attributes immediately.

termios.TCSADRAIN

Change attributes after transmitting all queued output.

termios.TCSAFLUSH

Change attributes after transmitting all queued output and discarding all queued input.

termios.tcsendbreak(fd, duration)

ファイル記述子 fd にブレークを送信します。duration をゼロにすると、0.25〜0.5 秒間のブレークを送信します; duration の値がゼロでない場合、その意味はシステム依存です。

termios.tcdrain(fd)

ファイル記述子 fd に書き込まれた全ての出力が転送されるまで待ちます。

termios.tcflush(fd, queue)

ファイル記述子 fd にキューされたデータを無視します。どのキューかは queue セレクタで指定します: TCIFLUSH は入力キュー、 TCOFLUSH は出力キュー、 TCIOFLUSH は両方のキューです。

termios.tcflow(fd, action)

ファイル記述子 fd の入力または出力をサスペンドしたりレジュームしたりします。引数 action は出力をサスペンドする TCOOFF 、出力をレジュームする TCOON 、入力をサスペンドする TCIOFF 、入力をレジュームする TCION をとることができます。

termios.tcgetwinsize(fd)

Return a tuple (ws_row, ws_col) containing the tty window size for file descriptor fd. Requires termios.TIOCGWINSZ or termios.TIOCGSIZE.

Added in version 3.11.

termios.tcsetwinsize(fd, winsize)

Set the tty window size for file descriptor fd from winsize, which is a two-item tuple (ws_row, ws_col) like the one returned by tcgetwinsize(). Requires at least one of the pairs (termios.TIOCGWINSZ, termios.TIOCSWINSZ); (termios.TIOCGSIZE, termios.TIOCSSIZE) to be defined.

Added in version 3.11.

参考

tty モジュール

一般的な端末制御操作のための便利な関数。

使用例

以下はエコーバックを切った状態でパスワード入力を促す関数です。ユーザの入力に関わらず以前の端末属性を正確に回復するために、二つの tcgetattr() と try ... finally 文によるテクニックが使われています:

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

tty --- Terminal control functions

ソースコード: Lib/tty.py [https://github.com/python/cpython/tree/3.12/Lib/tty.py]

tty モジュールは端末を cbreak および raw モードにするための関数を定義しています。

利用可能な環境: Unix。

このモジュールは termios モジュールを必要とするため、 Unix でしか動作しません。

tty モジュールでは、以下の関数を定義しています:

tty.cfmakeraw(mode)

Convert the tty attribute list mode, which is a list like the one returned by termios.tcgetattr(), to that of a tty in raw mode.

Added in version 3.12.

tty.cfmakecbreak(mode)

Convert the tty attribute list mode, which is a list like the one returned by termios.tcgetattr(), to that of a tty in cbreak mode.

This clears the ECHO and ICANON local mode flags in mode as well as setting the minimum input to 1 byte with no delay.

Added in version 3.12.

バージョン 3.12.2 で変更: The ICRNL flag is no longer cleared. This matches Linux and macOS stty cbreak behavior and what setcbreak() historically did.

tty.setraw(fd, when=termios.TCSAFLUSH)

Change the mode of the file descriptor fd to raw. If when is omitted, it defaults to termios.TCSAFLUSH, and is passed to termios.tcsetattr(). The return value of termios.tcgetattr() is saved before setting fd to raw mode; this value is returned.

バージョン 3.12 で変更: The return value is now the original tty attributes, instead of None.

tty.setcbreak(fd, when=termios.TCSAFLUSH)

Change the mode of file descriptor fd to cbreak. If when is omitted, it defaults to termios.TCSAFLUSH, and is passed to termios.tcsetattr(). The return value of termios.tcgetattr() is saved before setting fd to cbreak mode; this value is returned.

This clears the ECHO and ICANON local mode flags as well as setting the minimum input to 1 byte with no delay.

バージョン 3.12 で変更: The return value is now the original tty attributes, instead of None.

バージョン 3.12.2 で変更: The ICRNL flag is no longer cleared. This restores the behavior of Python 3.11 and earlier as well as matching what Linux, macOS, & BSDs describe in their stty(1) man pages regarding cbreak mode.

参考

モジュール termios

低水準端末制御インターフェース。

pty --- Pseudo-terminal utilities

ソースコード: Lib/pty.py [https://github.com/python/cpython/tree/3.12/Lib/pty.py]

pty モジュールは擬似端末(他のプロセスを実行してその制御をしている端末をプログラムで読み書きする)を制御する操作を定義しています。

利用可能な環境: 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).

pty モジュールでは以下の関数を定義しています:

pty.fork()

forkします。子プロセスの制御端末を擬似端末に接続します。返り値は (pid, fd) です。子プロセスは pid として0、fd として invalid をそれぞれ受けとります。親プロセスは pid として子プロセスのPID、fd として子プロセスの制御端末 (子プロセスの標準入出力に接続されている)のファイル記述子を受けとります。

警告

On macOS the use of this function is unsafe when mixed with using higher-level system APIs, and that includes using urllib.request.

pty.openpty()

新しい擬似端末のペアを開きます。利用できるなら os.openpty() を使い、利用できなければ一般的なUnixシステム用のエミュレーションコードを使います。マスター、スレーブそれぞれのためのファイル記述子、 (master, slave) のタプルを返します。

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 os.waitpid() on the child process.

os.waitstatus_to_exitcode() can be used to convert the exit status into an exit code.

引数 argv を指定して 監査イベント pty.spawn を送出します。

バージョン 3.4 で変更: spawn() が os.waitpid() が返す子プロセスのステータス値を返すようになりました。

使用例

下記のプログラムは Unix コマンド script(1) [https://manpages.debian.org/script(1)] のように動作します。疑似端末を使用して、端末セッションのすべての入出力を "typescript" に記録します。

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)

fcntl --- The fcntl and ioctl system calls

This module performs file and I/O control on file descriptors. It is an interface to the fcntl() and ioctl() Unix routines. See the fcntl(2) [https://manpages.debian.org/fcntl(2)] and ioctl(2) [https://manpages.debian.org/ioctl(2)] Unix manual pages for full details.

Availability: Unix, not Emscripten, not WASI.

このモジュール内の全ての関数はファイル記述子 fd を最初の引数に取ります。 この値は sys.stdin.fileno() が返すような整数のファイル記述子でも、 sys.stdin 自体のような、純粋にファイル記述子だけを返す fileno() メソッドを提供している io.IOBase オブジェクトでもかまいません。

バージョン 3.3 で変更: 以前は IOError を送出していたこのモジュールの操作が、 OSError を送出するようになりました。

バージョン 3.8 で変更: The fcntl module now contains F_ADD_SEALS, F_GET_SEALS, and F_SEAL_* constants for sealing of os.memfd_create() file descriptors.

バージョン 3.9 で変更: On macOS, the fcntl module exposes the F_GETPATH constant, which obtains the path of a file from a file descriptor. On Linux(>=3.15), the fcntl module exposes the F_OFD_GETLK, F_OFD_SETLK and F_OFD_SETLKW constants, which are used when working with open file description locks.

バージョン 3.10 で変更: On Linux >= 2.6.11, the fcntl module exposes the F_GETPIPE_SZ and F_SETPIPE_SZ constants, which allow to check and modify a pipe's size respectively.

バージョン 3.11 で変更: On FreeBSD, the fcntl module exposes the F_DUP2FD and F_DUP2FD_CLOEXEC constants, which allow to duplicate a file descriptor, the latter setting FD_CLOEXEC flag in addition.

バージョン 3.12 で変更: On Linux >= 4.5, the fcntl module exposes the FICLONE and 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".

このモジュールには、以下の関数が定義されています:

fcntl.fcntl(fd, cmd, arg=0)

操作 cmd をファイル記述子 fd (または fileno() メソッドを提供しているファイルオブジェクト) に対して実行します。 cmd として用いられる値はオペレーティングシステム依存で、 fcntl モジュール内に関連する C ヘッダファイルと同じ名前が使われている定数の形で利用出来ます。引数 arg は整数値か bytes オブジェクトをとります。引数が整数値の場合、この関数の戻り値は C 言語の fcntl() を呼び出した際の整数の戻り値になります。引数が bytes の場合には、 struct.pack() で作られるようなバイナリの構造体を表します。バイナリデータはバッファにコピーされ、そのアドレスが C 言語の fcntl() 呼び出しに渡されます。 呼び出しが成功した後に戻される値はバッファの内容で、 bytes オブジェクトに変換されています。 返されるオブジェクトは arg 引数と同じ長さになります。 この値は 1024 バイトに制限されています。 オペレーティングシステムからバッファに返される情報の長さが 1024 バイトよりも大きい場合、大抵はセグメンテーション違反となるか、より不可思議なデータの破損を引き起こします。

If the fcntl() call fails, an OSError is raised.

引数 fd, cmd, arg を指定して 監査イベント fcntl.fcntl を送出します。

fcntl.ioctl(fd, request, arg=0, mutate_flag=True)

この関数は fcntl() 関数と同じですが、引数の扱いがより複雑であるところが異なります。

パラメータ request は32ビットに収まる値に制限されます。 request 引数として使うのに関係のある追加の定数は termios モジュールにあり、関連する C ヘッダファイルで使われているのと同じ名前が付けられています。

パラメタ arg は、整数、 (bytes のような) 読み出し専用のバッファインターフェースをサポートするオブジェクト、(bytearray のような) 読み書きバッファインターフェースをサポートするオブジェクトのどれかです。

最後の型のオブジェクトを除き、動作は fcntl() 関数と同じです。

可変なバッファが渡された場合、動作は mutate_flag 引数の値で決定されます。

この値が偽の場合、バッファの可変性は無視され、読み出し専用バッファの場合と同じ動作になりますが、上で述べた 1024 バイトの制限は回避されます -- 従って、オペレーティングシステムが希望するバッファ長までであれば正しく動作します。

mutate_flag が真 (デフォルト) の場合、バッファは (実際には) 根底にある ioctl() システムコールに渡され、後者の戻り値が呼び出し側の Python に引き渡され、バッファの新たな内容は ioctl() の動作を反映します。この説明はやや単純化されています。というのは、与えられたバッファが 1024 バイト長よりも短い場合、バッファはまず 1024 バイト長の静的なバッファにコピーされてから ioctl() に渡され、その後引数で与えたバッファに戻しコピーされるからです。

If the ioctl() call fails, an OSError exception is raised.

以下に例を示します:

>>> 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])

引数 fd, request, arg を指定して 監査イベント fcntl.ioctl を送出します。

fcntl.flock(fd, operation)

ファイル記述子 fd (fileno() メソッドを提供しているファイルオブジェクトも含む) に対してロック操作 operation を実行します。 詳細は Unix マニュアルの flock(2) [https://manpages.debian.org/flock(2)] を参照してください (システムによっては、この関数は fcntl() を使ってエミュレーションされています)。

If the flock() call fails, an OSError exception is raised.

引数 fd, operation を指定して 監査イベント fcntl.flock を送出します。

fcntl.lockf(fd, cmd, len=0, start=0, whence=0)

本質的に fcntl() によるロッキングの呼び出しをラップしたものです。 fd はロックまたはアンロックするファイルのファイル記述子 (fileno() メソッドを提供するファイルオブジェクトも受け付けられます) で、 cmd は以下の値のうちいずれかになります:

fcntl.LOCK_UN

Release an existing lock.

fcntl.LOCK_SH

Acquire a shared lock.

fcntl.LOCK_EX

Acquire an exclusive lock.

fcntl.LOCK_NB

Bitwise OR with any of the other three LOCK_* constants to make the request non-blocking.

If LOCK_NB is used and the lock cannot be acquired, an OSError will be raised and the exception will have an errno attribute set to EACCES or EAGAIN (depending on the operating system; for portability, check for both values). On at least some systems, LOCK_EX can only be used if the file descriptor refers to a file opened for writing.

len はロックを行いたいバイト数、 start はロック領域先頭の whence からの相対的なバイトオフセット、 whence は io.IOBase.seek() と同じで、具体的には:

0 -- relative to the start of the file (os.SEEK_SET)

1 -- relative to the current buffer position (os.SEEK_CUR)

2 -- relative to the end of the file (os.SEEK_END)

start の標準の値は 0 で、ファイルの先頭から開始することを意味します。len の標準の値は 0 で、ファイルの終了までロックすることを表します。whence の標準の値も 0 です。

引数 fd, cmd, len, start, whence を指定して 監査イベント fcntl.lockf を送出します。

以下に (全ての SVR4 互換システムでの) 例を示します:

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)

最初の例では、戻り値 rv は整数値を保持しています; 二つ目の例では bytes オブジェクトを保持しています。 lockdata 変数の構造体レイアウトはシステム依存です --- 従って flock() を呼ぶ方が良いでしょう。

参考

os モジュール

If the locking flags O_SHLOCK and O_EXLOCK are present in the os module (on BSD only), the os.open() function provides an alternative to the lockf() and flock() functions.

resource --- Resource usage information

このモジュールでは、プログラムによって使用されているシステムリソースを計測したり制御するための基本的なメカニズムを提供します。

Availability: Unix, not Emscripten, not WASI.

特定のシステムリソースを指定したり、現在のプロセスやその子プロセスのリソース使用情報を要求するためにシンボル定数が使われます。

システムコールが失敗した場合 OSError を送出します。

exception resource.error

OSError の非推奨のエイリアスです。

バージョン 3.3 で変更: PEP 3151 [https://peps.python.org/pep-3151/] に基づき、このクラスは OSError のエイリアスになりました。

リソースの制限

リソースの使用は下に述べる setrlimit() 関数を使って制限することができます。各リソースは二つ組の制限値: ソフトリミット (soft limit) 、およびハードリミット (hard limit) 、で制御されます。ソフトリミットは現在の制限値で、時間とともにプロセスによって下げたり上げたりできます。ソフトリミットはハードリミットを超えることはできません。ハードリミットはソフトリミットよりも高い任意の値まで下げることができますが、上げることはできません。 (スーパユーザの有効な UID を持つプロセスのみがハードリミットを上げることができます。)

制限をかけるべく指定できるリソースはシステムに依存します。指定できるリソースは getrlimit(2) [https://manpages.debian.org/getrlimit(2)] マニュアルページで解説されています。以下に列挙するリソースは背後のオペレーティングシステムがサポートする場合にサポートされています; オペレーティングシステム側で値を調べたり制御したりできないリソースは、そのプラットフォーム向けのこのモジュール内では定義されていません。

resource.RLIM_INFINITY

無制限のリソースの上限を示すための定数です。

resource.getrlimit(resource)

resource の現在のソフトおよびハードリミットを表すタプル (soft, hard) を返します。無効なリソースが指定された場合には ValueError が、背後のシステムコールが予期せず失敗した場合には error が送出されます。

resource.setrlimit(resource, limits)

resource の新たな消費制限を設定します。 limits 引数には、タプル (soft, hard) による二つの整数で、新たな制限を記述しなければなりません。 RLIM_INFINITY を指定することで、無制限を要求することが出来ます。

無効なリソースが指定された場合、ソフトリミットの値がハードリミットの値を超えている場合、プロセスがハードリミットを引き上げようとした場合には ValueError が送出されます。リソースのハードリミットやシステムリミットが無制限でないのに RLIM_INFINITY を指定した場合も、 ValueError になります。スーパーユーザの実効 UID を持ったプロセスは無制限を含めあらゆる妥当な制限値を要求出来ますが、システムが課している制限を超過した要求ではやはり ValueError となります。

setrlimit は背後のシステムコールが予期せず失敗した場合に、 error を送出する場合があります。

VxWorks only supports setting RLIMIT_NOFILE.

引数 src, dst`, ``limits を指定して 監査イベント resource.setrlimit を送出します。

resource.prlimit(pid, resource[, limits])

1つの関数の中で setrlimit() と getrlimit() を組み合わせ、任意のプロセスのリソースの制限値を取得したり設定したりします。 pid が 0 の場合は、現在のプロセスに適用されます。 resource および limits は、 limits がオプションであることを除けば、 setrlimit() と同じ意味です。

limits が与えられないときは、関数はプロセス pid の resource の制限値を返します。 limits が与えられたときは、プロセスの resource の制限値が設定され、設定が変更される前のリソースの制限値が返されます。

pid が見付からないときは ProcessLookupError を、ユーザがプロセスの CAP_SYS_RESOURCE を持ってないときは PermissionError を送出します。

引数 pid, dst`, ``limits を指定して 監査イベント resource.prlimit を送出します。

Availability: Linux >= 2.6.36 with glibc >= 2.13.

Added in version 3.4.

以下のシンボルは、後に述べる関数 setrlimit() および getrlimit() を使って消費量を制御することができるリソースを定義しています。これらのシンボルの値は、C プログラムで使われているシンボルと全く同じです。

getrlimit(2) [https://manpages.debian.org/getrlimit(2)] の Unix マニュアルページには、指定可能なリソースが列挙されています。全てのシステムで同じシンボルが使われているわけではなく、また同じリソースを表すために同じ値が使われているとも限らないので注意してください。このモジュールはプラットフォーム間の相違を隠蔽しようとはしていません --- あるプラットフォームで定義されていないシンボルは、そのプラットフォーム向けの本モジュールでは利用することができません。

resource.RLIMIT_CORE

現在のプロセスが生成できるコアファイルの最大 (バイト) サイズです。プロセスの全体イメージを入れるためにこの値より大きなサイズのコアファイルが要求された結果、部分的なコアファイルが生成される可能性があります。

resource.RLIMIT_CPU

プロセッサが利用することができる最大プロセッサ時間 (秒) です。この制限を超えた場合、 SIGXCPU シグナルがプロセスに送られます。 (どのようにしてシグナルを捕捉したり、例えば開かれているファイルをディスクにフラッシュするといった有用な処理を行うかについての情報は、 signal モジュールのドキュメントを参照してください)

resource.RLIMIT_FSIZE

プロセスが作成するファイルの最大サイズです。

resource.RLIMIT_DATA

プロセスのヒープの最大 (バイト) サイズです。

resource.RLIMIT_STACK

現在のプロセスのコールスタックの最大サイズ (バイト単位) です。これはマルチスレッドプロセスのメインスレッドのスタックのみに影響します。

resource.RLIMIT_RSS

プロセスが取りうる最大 RAM 常駐ページサイズ (resident set size) です。

resource.RLIMIT_NPROC

現在のプロセスが生成できるプロセスの上限です。

resource.RLIMIT_NOFILE

現在のプロセスが開けるファイル記述子の上限です。

resource.RLIMIT_OFILE

RLIMIT_NOFILE の BSD での名称です。

resource.RLIMIT_MEMLOCK

メモリ中でロックできる最大アドレス空間です。

resource.RLIMIT_VMEM

プロセスが占有できるマップメモリの最大領域です。

利用可能な環境: FreeBSD 11 以上。

resource.RLIMIT_AS

アドレス空間でプロセスが占有できる最大領域 (バイト単位) です。

resource.RLIMIT_MSGQUEUE

POSIX メッセージキューに割り当てることの出来るバイト数です。

利用可能な環境: Linux 2.6.8以上。

Added in version 3.4.

resource.RLIMIT_NICE

プロセスの nice の上限です (20 - rlim_cur)。

利用可能な環境: Linux 2.6.12以上。

Added in version 3.4.

resource.RLIMIT_RTPRIO

リアルタイム優先順位の上限です。

利用可能な環境: Linux 2.6.12以上。

Added in version 3.4.

resource.RLIMIT_RTTIME

リアルタイムスケジューリングにおいて、プロセスがブロッキングシステムコールを行わずに使用できるCPU時間の制限値（マイクロ秒単位）。

利用可能な環境: Linux 2.6.25以上。

Added in version 3.4.

resource.RLIMIT_SIGPENDING

プロセスがキュー出来るシグナルの数です。

利用可能な環境: Linux 2.6.8以上。

Added in version 3.4.

resource.RLIMIT_SBSIZE

このユーザが使用するソケットバッファの最大サイズ(バイト単位)。これは、このユーザが常に保持できるネットワークメモリの量、つまり mbuf の量を制限します。

利用可能な環境: FreeBSD。

Added in version 3.4.

resource.RLIMIT_SWAP

このユーザ ID のすべてのプロセスで予約または使用できるスワップスペースの最大サイズ (バイト単位)。この制限は vm.overcommit sysctl のビット 1 が設定されている場合のみ適用されます。この sysctl の完全な説明については tuning(7) [https://man.freebsd.org/cgi/man.cgi?query=tuning&sektion=7] を参照してください。

利用可能な環境: FreeBSD。

Added in version 3.4.

resource.RLIMIT_NPTS

このユーザ ID が作成する擬似端末の数の上限です。

利用可能な環境: FreeBSD。

Added in version 3.4.

resource.RLIMIT_KQUEUES

The maximum number of kqueues this user id is allowed to create.

利用可能な環境: FreeBSD 11 以上。

Added in version 3.10.

リソースの使用状態

以下の関数はリソース使用情報を取得するために使われます:

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 RUSAGE_* constants described below.

簡単な例:

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

返される値の各フィールドはそれぞれ、個々のシステムリソースがどれくらい使用されているか、例えばユーザモードでの実行に費やされた時間やプロセスが主記憶からスワップアウトされた回数、を示しています。幾つかの値、例えばプロセスが使用しているメモリ量は、内部時計の最小単位に依存します。

以前のバージョンとの互換性のため、返される値は 16 要素からなるタプルとしてアクセスすることもできます。

戻り値のフィールド ru_utime および ru_stime は浮動小数点数で、それぞれユーザモードでの実行に費やされた時間、およびシステムモードでの実行に費やされた時間を表します。それ以外の値は整数です。これらの値に関する詳しい情報は getrusage(2) [https://manpages.debian.org/getrusage(2)] を調べてください。以下に簡単な概要を示します:

インデックス

フィールド

リソース

0

ru_utime

time in user mode (float seconds)

1

ru_stime

time in system mode (float seconds)

2

ru_maxrss

最大常駐ページサイズ

3

ru_ixrss

共有メモリサイズ

4

ru_idrss

非共有メモリサイズ

5

ru_isrss

非共有スタックサイズ

6

ru_minflt

I/O を必要としないページフォールト数

7

ru_majflt

I/O を必要とするページフォールト数

8

ru_nswap

スワップアウト回数

9

ru_inblock

ブロック入力操作数

10

ru_oublock

ブロック出力操作数

11

ru_msgsnd

送信メッセージ数

12

ru_msgrcv

受信メッセージ数

13

ru_nsignals

受信シグナル数

14

ru_nvcsw

自発的な実行コンテキスト切り替え数

15

ru_nivcsw

非自発的な実行コンテキスト切り替え数

この関数は無効な who 引数を指定した場合には ValueError を送出します。また、異常が発生した場合には error 例外が送出される可能性があります。

resource.getpagesize()

システムページ内のバイト数を返します。(ハードウェアページサイズと同じとは限りません。)

The following RUSAGE_* symbols are passed to the getrusage() function to specify which processes information should be provided for.

resource.RUSAGE_SELF

getrusage() に渡すと呼び出し中のプロセスが消費しているリソースを要求します。そのプロセスの全スレッドが使用するリソースの合計です。

resource.RUSAGE_CHILDREN

呼び出し元のプロセスの子プロセスが消費するリソースを要求するために、 getrusage() に渡して終了させ、待機させることができます。

resource.RUSAGE_BOTH

getrusage() に渡すと現在のプロセスおよび子プロセスの両方が消費しているリソースを要求します。全てのシステムで利用可能なわけではありません。

resource.RUSAGE_THREAD

getrusage() に渡すと現在のスレッドが消費しているリソースを要求します。全てのシステムで利用可能なわけではありません。

Added in version 3.2.

syslog --- Unix syslog library routines

このモジュールでは Unix syslog ライブラリルーチン群へのインターフェースを提供します。syslog の便宜レベルに関する詳細な記述は Unix マニュアルページを参照してください。

Availability: Unix, not Emscripten, not WASI.

This module wraps the system syslog family of routines. A pure Python library that can speak to a syslog server is available in the logging.handlers module as SysLogHandler.

このモジュールには、以下の関数が定義されています:

syslog.syslog(message)

syslog.syslog(priority, message)

文字列 message をシステムログ機構に送信します。末尾の改行文字は必要に応じて追加されます。各メッセージは facility および level からなる優先度でタグ付けされます。オプションの priority 引数はメッセージの優先度を定義します。標準の値は LOG_INFO です。 priority 中に、便宜レベルが (LOG_INFO | LOG_USER のように) 論理和を使ってコード化されていない場合、 openlog() を呼び出した際の値が使われます。

syslog() が呼び出される前に openlog() が呼び出されなかった場合、 openlog() が引数なしで呼び出されます。

引数 priority, message を指定して 監査イベント syslog.syslog を送出します。

バージョン 3.2 で変更: In previous versions, openlog() would not be called automatically if it wasn't called prior to the call to syslog(), deferring to the syslog implementation to call 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.) openlog() must be called in the main interpreter before syslog() may be used in a subinterpreter. Otherwise it will raise RuntimeError.

syslog.openlog([ident[, logoption[, facility]]])

openlog() 関数を呼び出すことで以降の syslog() の呼び出しに対するログオプションを設定することができます。ログがまだ開かれていない状態で syslog() を呼び出すと openlog() が引数なしで呼び出されます。

オプションの ident キーワード引数は全てのメッセージの先頭に付く文字列で、デフォルトでは sys.argv[0] から前方のパス部分を取り除いたものです。オプションの logoption キーワード引数 (デフォルトは 0) はビットフィールドです。組み合わせられる値については下記を参照してください。オプションの facility キーワード引数 (デフォルトは LOG_USER) は明示的に facility が encode されていないメッセージに設定される facility です。

引数 ident, logoptiona`, facility を指定して 監査イベント 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 RuntimeError if called in a subinterpreter.

syslog.closelog()

syslog モジュールの値をリセットし、システムライブラリの closelog() を呼び出します。

この関数を呼ぶと、モジュールが最初に import されたときと同じようにふるまいます。例えば、(openlog() を呼び出さないで) syslog() を最初に呼び出したときに、 openlog() が呼び出され、 ident やその他の openlog() の引数はデフォルト値にリセットされます。

引数無しで 監査イベント 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 RuntimeError if called in a subinterpreter.

syslog.setlogmask(maskpri)

優先度マスクを maskpri に設定し、以前のマスク値を返します。 maskpri に設定されていない優先度レベルを持った syslog() の呼び出しは無視されます。標準では全ての優先度をログ出力します。関数 LOG_MASK(pri) は個々の優先度 pri に対する優先度マスクを計算します。関数 LOG_UPTO(pri) は優先度 pri までの全ての優先度を含むようなマスクを計算します。

引数 maskpri を指定して 監査イベント socket.setlogmask を送出します。

このモジュールでは以下の定数を定義しています:

Priority levels (high to low):

LOG_EMERG, LOG_ALERT, LOG_CRIT, LOG_ERR, LOG_WARNING, LOG_NOTICE, LOG_INFO, LOG_DEBUG.

Facilities:

LOG_KERN, LOG_USER, LOG_MAIL, LOG_DAEMON, LOG_AUTH, LOG_LPR, LOG_NEWS, LOG_UUCP, LOG_CRON, LOG_SYSLOG, LOG_LOCAL0 to LOG_LOCAL7, and, if defined in <syslog.h>, LOG_AUTHPRIV.

Log options:

LOG_PID, LOG_CONS, LOG_NDELAY, and, if defined in <syslog.h>, LOG_ODELAY, LOG_NOWAIT, and LOG_PERROR.

使用例

シンプルな例

1つ目のシンプルな例:

import syslog

syslog.syslog('Processing started')
if error:
    syslog.syslog(syslog.LOG_ERR, 'Processing started')

いくつかのログオプションを設定する例。ログメッセージにプロセスIDを含み、メッセージをメールのログ用の facility にメッセージを書きます:

syslog.openlog(logoption=syslog.LOG_PID, facility=syslog.LOG_MAIL)
syslog.syslog('E-mail processing initiated...')

Modules command-line interface (CLI)

The following modules have a command-line interface.

ast

asyncio

base64

calendar

code

compileall

cProfile: see profile

difflib

dis

doctest

encodings.rot_13

ensurepip

filecmp

fileinput

ftplib

gzip

http.server

idlelib

inspect

json.tool

mimetypes

pdb

pickle

pickletools

platform

poplib

profile

pstats

py_compile

pyclbr

pydoc

quopri

runpy

site

sqlite3

sysconfig

tabnanny

tarfile

this

timeit

tokenize

trace

turtledemo

unittest

uuid

venv

webbrowser

zipapp

zipfile

See also the Python command-line interface.

取って代わられたモジュール群

The modules described in this chapter are deprecated and only kept for backwards compatibility. They have been superseded by other modules.

aifc --- AIFFおよびAIFCファイルの読み書き

audioop --- 生の音声データを操作する

cgi --- CGI (ゲートウェイインターフェース規格) のサポート

cgitb --- CGI スクリプトのトレースバック管理機構

chunk --- IFFチャンクデータの読み込み

crypt --- Unix パスワードをチェックするための関数

imghdr --- 画像の形式を決定する

mailcap --- mailcap ファイルの操作

msilib --- Microsoft インストーラーファイルの読み書き

nis --- Sun の NIS (Yellow Pages) へのインターフェース

nntplib --- NNTP プロトコルクライアント

optparse --- Parser for command line options

ossaudiodev --- OSS互換オーディオデバイスへのアクセス

pipes --- シェルパイプラインへのインターフェース

sndhdr --- サウンドファイルの識別

spwd --- シャドウパスワードデータベース

sunau --- Sun AUファイルの読み書き

telnetlib --- Telnet クライアント

uu --- uuencode形式のエンコードとデコード

xdrlib --- XDR データのエンコードおよびデコード

aifc --- AIFFおよびAIFCファイルの読み書き

ソースコード: Lib/aifc.py [https://github.com/python/cpython/tree/3.12/Lib/aifc.py]

バージョン 3.11 で非推奨、バージョン 3.13 で削除予定: The aifc module is deprecated (see PEP 594 [https://peps.python.org/pep-0594/#aifc] for details).

このモジュールはAIFFとAIFF-Cファイルの読み書きをサポートします。AIFF（Audio Interchange File Format）はデジタルオーディオサンプルをファイルに保存するためのフォーマットです。AIFF-CはAIFFの新しいバージョンで、オーディオデータの圧縮に対応しています。

オーディオファイルには、オーディオデータについて記述したパラメータがたくさん含まれています。サンプリングレートあるいはフレームレートは、1秒あたりのオーディオサンプル数です。チャンネル数は、モノラル、ステレオ、4チャンネルかどうかを示します。フレームはそれぞれ、チャンネルごとに一つのサンプルからなります。サンプルサイズは、一つのサンプルの大きさをバイト数で示したものです。したがって、一つのフレームは nchannels * samplesize バイト からなり、1秒間では nchannels * samplesize * framerate バイトで構成されます。

例えば、CD品質のオーディオは2バイト（16ビット）のサンプルサイズを持っていて、2チャンネル（ステレオ）であり、44,100フレーム／秒のフレームレートを持っています。そのため、フレームサイズは4バイト（2*2）で、1秒間では2*2*44100バイト（176,400バイト）になります。

aifc モジュールは以下の関数を定義しています:

aifc.open(file, mode=None)

AIFFあるいはAIFF-Cファイルを開き、後述するメソッドを持つインスタンスを返します。引数 file はファイルを示す文字列か、 file object のいずれかです。 mode は、読み込み用に開くときには 'r' か 'rb' のどちらかでなければならず、書き込み用に開くときには 'w' か 'wb' のどちらかでなければなりません。もし省略されたら、 file.mode が存在すればそれが使用され、なければ 'rb' が使われます。書き込み用にこのメソッドを使用するときには、これから全部でどれだけのサンプル数を書き込むのか分からなかったり、 writeframesraw() と setnframes() を使わないなら、ファイルオブジェクトはシーク可能でなければなりません。open() 関数は with 文の中で使われるかもしれません。with ブロックの実行が終了したら、close() メソッドが呼び出されます。

バージョン 3.4 で変更: with 構文のサポートが追加されました。

ファイルが open() によって読み込み用に開かれたときに返されるオブジェクトには、以下のメソッドがあります:

aifc.getnchannels()

オーディオチャンネル数（モノラルなら1、ステレオなら2）を返します。

aifc.getsampwidth()

サンプルサイズをバイト数で返します。

aifc.getframerate()

サンプリングレート（1秒あたりのオーディオフレーム数）を返します。

aifc.getnframes()

ファイルの中のオーディオフレーム数を返します。

aifc.getcomptype()

オーディオファイルで使用されている圧縮形式を示す4バイトの bytes を返します。AIFFファイルでは b'NONE' が返されます。

aifc.getcompname()

オーディオファイルの圧縮形式を人に判読可能な形に変換できる bytes で返します。AIFFファイルでは b'not compressed' が返されます。

aifc.getparams()

get*() メソッドが返すのと同じ (nchannels, sampwidth, framerate, nframes, comptype, compname) の namedtuple() を返します。

aifc.getmarkers()

オーディオファイルのマーカーのリストを返します。一つのマーカーは三つの要素のタプルです。要素の1番目はマークID（整数）、2番目はマーク位置のフレーム数をデータの始めから数えた値（整数）、3番目はマークの名称（文字列）です。

aifc.getmark(id)

与えられた id のマークの要素を getmarkers() で述べたタプルで返します。

aifc.readframes(nframes)

オーディオファイルの次の nframes 個のフレームを読み込んで返します。返されるデータは、全チャンネルの圧縮されていないサンプルをフレームごとに文字列にしたものです。

aifc.rewind()

読み込むポインタをデータの始めに巻き戻します。次に readframes() を使用すると、データの始めから読み込みます。

aifc.setpos(pos)

指定したフレーム数の位置にポインタを設定します。

aifc.tell()

現在のポインタのフレーム位置を返します。

aifc.close()

AIFFファイルを閉じます。このメソッドを呼び出したあとでは、オブジェクトはもう使用できません。

ファイルが open() によって書き込み用に開かれたときに返されるオブジェクトには、 readframes() と setpos() を除く上述の全てのメソッドがあります。さらに以下のメソッドが定義されています。 get*() メソッドは、対応する set*() を呼び出したあとでのみ呼び出し可能です。最初に writeframes() あるいは writeframesraw() を呼び出す前に、フレーム数を除く全てのパラメータが設定されていなければなりません。

aifc.aiff()

AIFFファイルを作ります。デフォルトではAIFF-Cファイルが作られますが、ファイル名が '.aiff' で終わっていればAIFFファイルが作られます。

aifc.aifc()

AIFF-Cファイルを作ります。デフォルトではAIFF-Cファイルが作られますが、ファイル名が '.aiff' で終わっていればAIFFファイルが作られます。

aifc.setnchannels(nchannels)

オーディオファイルのチャンネル数を設定します。

aifc.setsampwidth(width)

オーディオのサンプルサイズをバイト数で設定します。

aifc.setframerate(rate)

サンプリングレートを1秒あたりのフレーム数で設定します。

aifc.setnframes(nframes)

オーディオファイルに書き込まれるフレーム数を設定します。もしこのパラメータが設定されていなかったり正しくなかったら、ファイルはシークに対応していなければなりません。

aifc.setcomptype(type, name)

圧縮形式を設定します。もし設定しなければ、オーディオデータは圧縮されません。AIFFファイルは圧縮できません。name 引数は人間が読める圧縮形式の説明を bytes にしたもので、type 引数は4バイトの bytes でなければなりません。現在のところ、以下の圧縮形式がサポートされています： b'NONE', b'ULAW', b'ALAW', b'G722'。

aifc.setparams(nchannels, sampwidth, framerate, comptype, compname)

上の全パラメータを一度に設定します。引数はそれぞれのパラメータからなるタプルです。つまり、 setparams() の引数として、 getparams() を呼び出した結果を使うことができます。

aifc.setmark(id, pos, name)

指定したID（1以上）、位置、名称でマークを加えます。このメソッドは、 close() の前ならいつでも呼び出すことができます。

aifc.tell()

出力ファイルの現在の書き込み位置を返します。 setmark() との組み合わせで使うと便利です。

aifc.writeframes(data)

出力ファイルにデータを書き込みます。このメソッドは、オーディオファイルのパラメータを設定したあとでのみ呼び出し可能です。

バージョン 3.4 で変更: どのような bytes-like object も使用できるようになりました。

aifc.writeframesraw(data)

オーディオファイルのヘッダ情報が更新されないことを除いて、 writeframes() と同じです。

バージョン 3.4 で変更: どのような bytes-like object も使用できるようになりました。

aifc.close()

AIFFファイルを閉じます。ファイルのヘッダ情報は、オーディオデータの実際のサイズを反映して更新されます。このメソッドを呼び出したあとでは、オブジェクトはもう使用できません。

audioop --- 生の音声データを操作する

バージョン 3.11 で非推奨、バージョン 3.13 で削除予定: audioop モジュールは非推奨です (詳細は PEP 594 [https://peps.python.org/pep-0594/#audioop] 参照)。

audioop モジュールは音声データの便利な操作を含んでいます。このモジュールは、 bytes-like オブジェクト に保存された、符号付き整数の、ビット幅が 8, 16, 24, あるいは 32 ビットの音声データを対象として操作します。特に指定されていない限り、すべての波形データ（スカラー要素）は整数です。

バージョン 3.4 で変更: 24 bit サンプルのサポートが追加されました。すべての関数はどんな bytes-like object でも使用できます。文字列の入力は即座にエラーになります。

このモジュールはa-LAW、u-LAWそしてIntel/DVI ADPCMエンコードをサポートしています。

複雑な操作のうちいくつかはサンプル幅が 16 ビットのデータに対してのみ働きますが、それ以外は常にサンプル幅を操作のパラメタとして (バイト単位で) 渡します。

このモジュールでは以下の変数と関数を定義しています:

exception audioop.error

この例外は、未知のサンプル当たりのバイト数を指定した時など、全般的なエラーに対して送出されます。

audioop.add(fragment1, fragment2, width)

パラメータとして渡された2つのサンプルの和のデータを返します。width はバイト単位のサンプル幅で、1, 2, 3, 4 のいずれかです。両方のデータは同じ長さでなければなりません。オーバーフローした場合は、切り捨てされます。

audioop.adpcm2lin(adpcmfragment, width, state)

Intel/DVI ADPCM 形式のデータをリニア (linear) 形式にデコードします。 ADPCM 符号化方式の詳細については lin2adpcm() の説明を参照して下さい。 (sample, newstate) からなるタプルを返し、サンプルは width に指定した幅になります。

audioop.alaw2lin(fragment, width)

a-LAW形式のデータをリニア (linear) 形式に変換します。a-LAW形式は常に 8 ビットのサンプルを使用するので、ここでは width は単に出力データのサンプル幅となります。

audioop.avg(fragment, width)

データ中の全サンプルの平均値を返します。

audioop.avgpp(fragment, width)

データ中の全サンプルの平均 peak-peak 振幅を返します。フィルタリングを行っていない場合、このルーチンの有用性は疑問です。

audioop.bias(fragment, width, bias)

元の音声データの各サンプルにバイアスを加算した音声データを返します。オーバーフローした場合はラップアラウンドされます。

audioop.byteswap(fragment, width)

fragment のすべてのサンプルを "byteswap" して、修正された fragment を返します。ビッグエンディアンのサンプルをリトルエンディアンに、またはその逆に変換します。

Added in version 3.4.

audioop.cross(fragment, width)

引数に渡したデータ中のゼロ交差回数を返します。

audioop.findfactor(fragment, reference)

rms(add(fragment, mul(reference, -F))) を最小にするような係数 F、すなわち、reference に乗算したときにもっとも fragment に近くなるような値を返します。fragment と reference のサンプル幅はいずれも 2バイトでなければなりません。

このルーチンの実行に要する時間は len(fragment) に比例します。

audioop.findfit(fragment, reference)

reference を可能な限り fragment に一致させようとします (fragment は reference より長くなければなりません)。この処理は (概念的には) fragment からスライスをいくつか取り出し、それぞれについて findfactor() を使って最良な一致を計算し、誤差が最小の結果を選ぶことで実現します。 fragment と reference のサンプル幅は両方とも2バイトでなければなりません。 (offset, factor) からなるタプルを返します。 offset は最適な一致箇所が始まる fragment のオフセット値（整数）で、 factor は findfactor() の返す係数 (浮動小数点数) です。

audioop.findmax(fragment, length)

fragment から、長さが length サンプル (バイトではありません!) で最大のエネルギーを持つスライス、すなわち、rms(fragment[i*2:(i+length)* 2]) を最大にするようなスライスを探し、i を返します。データのはサンプル幅は 2バイトでなければなりません。

このルーチンの実行に要する時間は len(fragment) に比例します。

audioop.getsample(fragment, width, index)

データ中の index サンプル目の値を返します。

audioop.lin2adpcm(fragment, width, state)

データを 4 ビットの Intel/DVI ADPCM 符号化方式に変換します。ADPCM 符号化方式とは適応符号化方式の一つで、あるサンプルと (可変の) ステップだけ離れたその次のサンプルとの差を 4 ビットの整数で表現する方式です。Intel/DVI ADPCMアルゴリズムは IMA (国際MIDI協会) に採用されているので、おそらく標準になるはずです。

state はエンコーダの内部状態が入ったタプルです。エンコーダは (adpcmfrag, newstate) のタプルを返し、次に lin2adpcm() を呼び出す時に newstate を渡さねばなりません。最初に呼び出す時には state に None を渡してもかまいません。 adpcmfrag は ADPCMで符号化されたデータで、バイト当たり 2 つの4ビット値がパックされています。

audioop.lin2alaw(fragment, width)

音声データのサンプルを a-LAW エンコーディングに変換し、バイトオブジェクトとして返します。a-LAW とは 13ビットのダイナミックレンジを 8bit だけで表現できる音声エンコーディングです。Sun の音声ハードウェアなどで使われています。

audioop.lin2lin(fragment, width, newwidth)

サンプル幅を 1、2、3、4 バイト形式の間で変換します。

注釈

.WAV ファイルのような幾つかのオーディオフォーマットでは、16、24 と 32 bit のサンプルは符号付きですが、8 bit のサンプルは符号なしです。そのため、そのようなフォーマットで 8 bit に変換する場合は、変換結果に128を足さなければなりません:

new_frames = audioop.lin2lin(frames, old_width, 1)
new_frames = audioop.bias(new_frames, 1, 128)

逆に、8 bit から 16、24、32 bit に変換する場合も、同じことが言えます。

audioop.lin2ulaw(fragment, width)

音声データのサンプルを u-LAW エンコーディングに変換し、バイトオブジェクトとして返します。u-LAW とは 14ビットのダイナミックレンジを 8bit だけで表現できる音声エンコーディングです。Sun の音声ハードウェアなどで使われています。

audioop.max(fragment, width)

音声データ全サンプルの 絶対値 の最大値を返します。

audioop.maxpp(fragment, width)

音声データの最大 peak-peak 振幅を返します。

audioop.minmax(fragment, width)

音声データ全サンプル中における最小値と最大値からなるタプルを返します。

audioop.mul(fragment, width, factor)

元の音声データの各サンプルに浮動小数点数 factor を乗算した音声データを返します。オーバーフローした場合は切り捨てられます。

audioop.ratecv(fragment, width, nchannels, inrate, outrate, state[, weightA[, weightB]])

入力したデータのフレームレートを変換します。

state は変換ルーチンの内部状態を入れたタプルです。変換ルーチンは (newfragment, newstate) を返し、次に ratecv() を呼び出す時には newstate を渡さなねばなりません。最初の呼び出しでは None を渡します。

引数 weightA と weightB は単純なデジタルフィルタのパラメタで、デフォルト値はそれぞれ 1 と 0 です。

audioop.reverse(fragment, width)

データ内のサンプルの順序を逆転し、変更されたデータを返します。

audioop.rms(fragment, width)

データの自乗平均根(root-mean-square)、すなわち sqrt(sum(S_i^2)/n) を返します。

これはオーディオ信号の強度 (power) を測る一つの目安です。

audioop.tomono(fragment, width, lfactor, rfactor)

ステレオ音声データをモノラル音声データに変換します。左チャネルのデータに lfactor、右チャネルのデータに rfactor を掛けた後、二つのチャネルの値を加算して単一チャネルの信号を生成します。

audioop.tostereo(fragment, width, lfactor, rfactor)

モノラル音声データをステレオ音声データに変換します。ステレオ音声データの各サンプル対は、モノラル音声データの各サンプルをそれぞれ左チャネルは lfactor 倍、右チャネルは rfactor 倍して生成します。

audioop.ulaw2lin(fragment, width)

u-LAW で符号化されている音声データを線形に符号化された音声データに変換します。u-LAW 符号化は常にサンプル当たり 8 ビットを使うため、width は出力音声データのサンプル幅にしか使われません。

mul() や max() といった操作はモノラルとステレオを区別しない、すなわち全てのデータを平等に扱うということに注意してください。この仕様が問題になるようなら、あらかじめステレオ音声データを二つのモノラル音声データに分割しておき、操作後に再度統合してください。そのような例を以下に示します:

def mul_stereo(sample, width, lfactor, rfactor):
    lsample = audioop.tomono(sample, width, 1, 0)
    rsample = audioop.tomono(sample, width, 0, 1)
    lsample = audioop.mul(lsample, width, lfactor)
    rsample = audioop.mul(rsample, width, rfactor)
    lsample = audioop.tostereo(lsample, width, 1, 0)
    rsample = audioop.tostereo(rsample, width, 0, 1)
    return audioop.add(lsample, rsample, width)

もし ADPCM 符号をネットワークパケットの構築に使って独自のプロトコルをステートレスにしたい場合 (つまり、パケットロスを許容したい場合)は、データだけを送信して、ステートを送信すべきではありません。デコーダに従って initial ステート (lin2adpcm() に渡される値) を送るべきで、最終状態 (符号化器が返す値) を送るべきではないことに注意してください。 もし、struct.Struct をバイナリでの状態保存に使いたい場合は、最初の要素 (予測値) を 16bit で符号化し、２番目の要素 (デルタインデックス) を 8bit で符号化できます。

このモジュールの ADPCM 符号のテストは自分自身に対してのみ行っており、他の ADPCM 符号との間では行っていません。作者が仕様を誤解している部分もあるかもしれず、それぞれの標準との間で相互運用できない場合もあり得ます。

find*() ルーチンは一見滑稽に見えるかもしれません。これらの関数の主な目的はエコー除去 (echo cancellation) にあります。エコー除去を十分高速に行うには、出力サンプル中から最も大きなエネルギーを持った部分を取り出し、この部分が入力サンプル中のどこにあるかを調べ、入力サンプルから出力サンプル自体を減算します:

def echocancel(outputdata, inputdata):
    pos = audioop.findmax(outputdata, 800)    # one tenth second
    out_test = outputdata[pos*2:]
    in_test = inputdata[pos*2:]
    ipos, factor = audioop.findfit(in_test, out_test)
    # Optional (for better cancellation):
    # factor = audioop.findfactor(in_test[ipos*2:ipos*2+len(out_test)],
    #              out_test)
    prefill = '\0'*(pos+ipos)*2
    postfill = '\0'*(len(inputdata)-len(prefill)-len(outputdata))
    outputdata = prefill + audioop.mul(outputdata, 2, -factor) + postfill
    return audioop.add(inputdata, outputdata, 2)

cgi --- CGI (ゲートウェイインターフェース規格) のサポート

ソースコード: Lib/cgi.py [https://github.com/python/cpython/tree/3.12/Lib/cgi.py]

バージョン 3.11 で非推奨、バージョン 3.13 で削除予定: The cgi module is deprecated (see PEP 594 [https://peps.python.org/pep-0594/#cgi] for details and alternatives).

The FieldStorage class can typically be replaced with urllib.parse.parse_qsl() for GET and HEAD requests, and the email.message module or multipart [https://pypi.org/project/multipart/] for POST and PUT. Most utility functions have replacements.

ゲートウェイインターフェース規格 (CGI) に準拠したスクリプトをサポートするためのモジュールです。

このモジュールでは、Python で CGI スクリプトを書く際に使える様々なユーティリティを定義しています。

The global variable maxlen can be set to an integer indicating the maximum size of a POST request. POST requests larger than this size will result in a ValueError being raised during parsing. The default value of this variable is 0, meaning the request size is unlimited.

利用可能性: Emscripten でなく、WASI でもないこと。

このモジュールは WebAssembly プラットフォーム wasm32-emscripten と wasm32-wasi では動作しないか、利用不可です。詳しくは、WebAssemblyプラットフォーム を見てください。

はじめに

CGI スクリプトは、HTTP サーバによって起動され、通常は HTML の <FORM> または <ISINDEX> エレメントを通じてユーザが入力した内容を処理します。

ほとんどの場合、CGI スクリプトはサーバ上の特殊なディレクトリ cgi-bin の下に置きます。HTTP サーバは、まずスクリプトを駆動するためのシェルの環境変数に、リクエストの全ての情報 (クライアントのホスト名、リクエストされている URL、クエリ文字列、その他諸々) を設定し、スクリプトを実行した後、スクリプトの出力をクライアントに送信します。

スクリプトの入力端もクライアントに接続されていて、この経路を通じてフォームデータを読み込むこともあります。それ以外の場合には、フォームデータは URL の一部分である「クエリ文字列」を介して渡されます。このモジュールでは、上記のケースの違いに注意しつつ、Python スクリプトに対しては単純なインターフェースを提供しています。このモジュールではまた、スクリプトをデバッグするためのユーティリティも多数提供しています。また、最近はフォームを経由したファイルのアップロードをサポートしています (ブラウザ側がサポートしていればです)。

CGI スクリプトの出力は 2 つのセクションからなり、空行で分割されています。最初のセクションは複数のヘッダからなり、後続するデータがどのようなものかをクライアントに通知します。最小のヘッダセクションを生成するための Python のコードは以下のようなものです:

print("Content-Type: text/html")    # HTML is following
print()                             # blank line, end of headers

二つ目のセクションは通常、ヘッダやインラインイメージ等の付属したテキストをうまくフォーマットして表示できるようにした HTML です。以下に単純な HTML を出力する Python コードを示します:

print("<TITLE>CGI script output</TITLE>")
print("<H1>This is my first CGI script</H1>")
print("Hello, world!")

cgi モジュールを使う

import cgi と記述して開始します。

新たにスクリプトを書く際には、以下の行を付加するかどうか検討してください:

import cgitb
cgitb.enable()

これによって、特別な例外処理が有効にされ、エラーが発生した際に web ブラウザ上に詳細なレポートを出力するようになります。ユーザにスクリプトの内部を見せたくないのなら、以下のようにしてレポートをファイルに保存できます:

import cgitb
cgitb.enable(display=0, logdir="/path/to/logdir")

スクリプトを開発する際には、この機能はとても役に立ちます。 cgitb が生成する報告はバグを追跡するためにかかる時間を大幅に減らせるような情報を提供してくれます。スクリプトをテストし終わり、正確に動作することを確認したら、いつでも cgitb の行を削除できます。

入力されたフォームデータを取得するには、 FieldStorage クラスを使います。フォームが非 ASCII 文字を含んでいる場合は、 encoding キーワードパラメータを使用してドキュメントに対して定義されたエンコーディングの値を設定してください。それは、通常 HTML ドキュメントの HEAD セクション中の META タグ、あるいは Content-Type ヘッダーに含まれています。これは、標準入力または環境変数からフォームの内容を読み出します (どちらから読み出すかは、複数の環境変数の値が CGI 標準に従ってどのように設定されているかで決まります)。インスタンスが標準入力を使うかもしれないので、インスタンス生成を行うのは一度だけにしなければなりません。

FieldStorage のインスタンスは Python の辞書型のように添え字アクセスが可能です。 in を使用することによって要素が含まれているかの判定も出来ますし、標準の辞書メソッド keys() 及び組み込み関数 len() もサポートしています。空の文字列を含むフォーム要素は無視され、辞書には現れません。そのような値を保持するには、FieldStorage のインスタンス作成の際にオプションのキーワードパラメータ keep_blank_values に true を指定してください。

例えば、以下のコード (Content-Type ヘッダと空行はすでに出力された後とします) は name および addr フィールドが両方とも空の文字列に設定されていないか調べます:

form = cgi.FieldStorage()
if "name" not in form or "addr" not in form:
    print("<H1>Error</H1>")
    print("Please fill in the name and addr fields.")
    return
print("<p>name:", form["name"].value)
print("<p>addr:", form["addr"].value)
...further form processing here...

ここで、 form[key] で参照される各フィールドはそれ自体が FieldStorage (または MiniFieldStorage 。フォームのエンコードによって変わります) のインスタンスです。インスタンスの属性 value の内容は対応するフィールドの値で、文字列になります。 getvalue() メソッドはこの文字列値を直接返します。 getvalue() の 2 つめの引数にオプションの値を与えると、リクエストされたキーが存在しない場合に返すデフォルトの値になります。

入力されたフォームデータに同じ名前のフィールドが二つ以上あれば、 form[key] で得られるオブジェクトは FieldStorage や MiniFieldStorage のインスタンスではなく、そうしたインスタンスのリストになります。この場合、 form.getvalue(key) も同様に、文字列からなるリストを返します。もしこうした状況が起きうると思うなら (HTML のフォームに同じ名前をもったフィールドが複数含まれているのなら) 、 getlist() メソッドを使ってください。これは常に値のリストを返します (単一要素のケースを特別扱いする必要はありません)。例えば、以下のコードは任意の数のユーザ名フィールドを結合し、コンマで分割された文字列にします:

value = form.getlist("username")
usernames = ",".join(value)

フィールドがアップロードされたファイルを表している場合、 value 属性や getvalue() メソッドを使ってフィールドの値にアクセスすると、ファイルの内容をすべてメモリ上にバイト列として読み込みます。これは場合によっては望ましい動作ではないかもしれません。アップロードされたファイルがあるかどうかは filename 属性および file 属性のいずれかで調べられます。そして、 FieldStorage インスタンスのガベージコレクションの一部として自動的に閉じられるまでの間に、 file 属性から以下のようにデータを読み込むことができます (read() および readline() メソッドはバイト列を返します):

fileitem = form["userfile"]
if fileitem.file:
    # It's an uploaded file; count lines
    linecount = 0
    while True:
        line = fileitem.file.readline()
        if not line: break
        linecount = linecount + 1

FieldStorage オブジェクトは with 文での使用にも対応しています。 with 文を使用した場合、オブジェクトは終了時に自動的に閉じられます。

アップロードされたファイルの内容を取得している間にエラーが発生した場合 (例えば、ユーザーが戻るボタンやキャンセルボタンで submit を中断した場合)、そのフィールドのオブジェクトの done 属性には -1 が設定されます。

現在ドラフトとなっているファイルアップロードの標準仕様では、一つのフィールドから (再帰的な multipart/* エンコーディングを使って) 複数のファイルがアップロードされる可能性を受け入れています。この場合、アイテムは辞書形式の FieldStorage アイテムとなります。複数ファイルかどうかは type 属性が multipart/form-data (または multipart/* にマッチする他の MIME 型) になっているかどうかを調べれば判別できます。この場合、トップレベルのフォームオブジェクトと同様にして再帰的に個別処理できます。

フォームが「古い」形式で入力された場合 (クエリ文字列または単一の application/x-www-form-urlencoded データで入力された場合)、データ要素の実体は MiniFieldStorage クラスのインスタンスになります。この場合、 list 、 file 、および filename 属性は常に None になります。

フォームがPOSTによって送信され、クエリー文字列も持っていた場合、 FieldStorage と MiniFieldStorage の両方が含まれます。

バージョン 3.4 で変更: file 属性は、それを作成した FieldStorage インスタンスのガベージコレクションによって自動的に閉じられます。

バージョン 3.5 で変更: FieldStorage クラスにコンテキスト管理プロトコルのサポートが追加されました。

高水準インターフェース

前節では CGI フォームデータを FieldStorage クラスを使って読み出す方法について解説しました。この節では、フォームデータを分かりやすく直感的な方法で読み出せるようにするために追加された、より高水準のインターフェースについて記述します。このインターフェースは前節で説明した技術を撤廃するものではありません --- 例えば、前節の技術は依然としてファイルのアップロードを効率的に行う上で便利です。

このインターフェースは 2 つの単純なメソッドからなります。このメソッドを使えば、一般的な方法でフォームデータを処理でき、ある名前のフィールドに入力された値が一つなのかそれ以上なのかを心配する必要がなくなります。

前節では、一つのフィールド名に対して二つ以上の値が入力されるかもしれない場合には、常に以下のようなコードを書くよう学びました:

item = form.getvalue("item")
if isinstance(item, list):
    # The user is requesting more than one item.
else:
    # The user is requesting only one item.

こういった状況は、例えば以下のように、同じ名前を持った複数のチェックボックスからなるグループがフォームに入っているような場合によく起きます:

<input type="checkbox" name="item" value="1" />
<input type="checkbox" name="item" value="2" />

しかしながら、ほとんどの場合、あるフォーム中で特定の名前を持ったコントロールはただ一つしかないので、その名前に関連付けられた値はただ一つしかないはずだと考えるでしょう。そこで、スクリプトには例えば以下のようなコードを書くでしょう:

user = form.getvalue("user").upper()

このコードの問題点は、クライアントがスクリプトにとって常に有効な入力を提供するとは期待できないところにあります。例えば、もし好奇心旺盛なユーザがもう一つの user=foo ペアをクエリ文字列に追加したら、 getvalue("user") メソッドは文字列ではなくリストを返すため、このスクリプトはクラッシュするでしょう。リストに対して upper() メソッドを呼び出すと、引数が有効でない (リスト型はその名前のメソッドを持っていない) ため、例外 AttributeError を送出します。

従って、フォームデータの値を読み出しには、得られた値が単一の値なのか値のリストなのかを常に調べるコードを使うのが適切でした。これでは煩わしく、より読みにくいスクリプトになってしまいます。

ここで述べる高水準のインターフェースで提供している getfirst() や getlist() メソッドを使うと、もっと便利にアプローチできます。

FieldStorage.getfirst(name, default=None)

フォームフィールド name に関連付けられた値をつねに一つだけ返す軽量メソッドです。同じ名前で 1 つ以上の値がポストされている場合、このメソッドは最初の値だけを返します。フォームから値を受信する際の値の並び順はブラウザ間で異なる可能性があり、特定の順番であるとは期待できないので注意してください。[1] 指定したフォームフィールドや値がない場合、このメソッドはオプションの引数 default を返します。このパラメタを指定しない場合、標準の値は None に設定されます。

FieldStorage.getlist(name)

このメソッドはフォームフィールド name に関連付けられた値を常にリストにして返します。name に指定したフォームフィールドや値が存在しない場合、このメソッドは空のリストを返します。値が一つだけ存在する場合、要素を一つだけ含むリストを返します。

これらのメソッドを使うことで、以下のようにナイスでコンパクトにコードを書けます:

import cgi
form = cgi.FieldStorage()
user = form.getfirst("user", "").upper()    # This way it's safe.
for item in form.getlist("item"):
    do_something(item)

関数

より細かく CGI をコントロールしたり、このモジュールで実装されているアルゴリズムを他の状況で利用したい場合には、以下の関数が便利です。

cgi.parse(fp=None, environ=os.environ, keep_blank_values=False, strict_parsing=False, separator='&')

環境変数、またはファイルからからクエリを解釈します (ファイルは標準で sys.stdin になります) keep_blank_values, strict_parsing, separator 引数はそのまま urllib.parse.parse_qs() に渡されます。

バージョン 3.11 で非推奨、バージョン 3.13 で削除予定: This function, like the rest of the cgi module, is deprecated. It can be replaced by calling urllib.parse.parse_qs() directly on the desired query string (except for multipart/form-data input, which can be handled as described for parse_multipart()).

cgi.parse_multipart(fp, pdict, encoding='utf-8', errors='replace', separator='&')

Parse input of type multipart/form-data (for file uploads). Arguments are fp for the input file, pdict for a dictionary containing other parameters in the Content-Type header, and encoding, the request encoding.

Returns a dictionary just like urllib.parse.parse_qs(): keys are the field names, each value is a list of values for that field. For non-file fields, the value is a list of strings.

この関数は簡単に使えますが、数メガバイトのデータがアップロードされると考えられる場合にはあまり適していません --- その場合、より柔軟性のある FieldStorage を代りに使ってください。

バージョン 3.7 で変更: Added the encoding and errors parameters. For non-file fields, the value is now a list of strings, not bytes.

バージョン 3.10 で変更: Added the separator parameter.

バージョン 3.11 で非推奨、バージョン 3.13 で削除予定: This function, like the rest of the cgi module, is deprecated. It can be replaced with the functionality in the email package (e.g. email.message.EmailMessage/email.message.Message) which implements the same MIME RFCs, or with the multipart [https://pypi.org/project/multipart/] PyPI project.

cgi.parse_header(string)

(Content-Type のような) MIME ヘッダを解釈し、ヘッダの主要値と各パラメタからなる辞書にします。

バージョン 3.11 で非推奨、バージョン 3.13 で削除予定: This function, like the rest of the cgi module, is deprecated. It can be replaced with the functionality in the email package, which implements the same MIME RFCs.

For example, with email.message.EmailMessage:

from email.message import EmailMessage
msg = EmailMessage()
msg['content-type'] = 'application/json; charset="utf8"'
main, params = msg.get_content_type(), msg['content-type'].params

cgi.test()

メインプログラムから利用できる堅牢性テストを行う CGI スクリプトです。最小の HTTP ヘッダと、スクリプトで供給された全ての情報をHTML形式で書式化して出力します。

cgi.print_environ()

シェル変数を HTML に書式化して出力します。

cgi.print_form(form)

フォームを HTML に初期化して出力します。

cgi.print_directory()

現在のディレクトリを HTML に書式化して出力します。

cgi.print_environ_usage()

意味のある (CGI の使う) 環境変数を HTML で出力します。

セキュリティへの配慮

重要なルールが一つあります: (os.system(), os.popen() またはその他の同様の機能によって) 外部プログラムを呼び出すなら、クライアントから受信した任意の文字列をシェルに渡していないことをよく確かめてください。これはよく知られているセキュリティホールであり、これによって web のどこかにいる悪賢いハッカーが、だまされやすい CGI スクリプトに任意のシェルコマンドを実行させてしまえます。URL の一部やフィールド名でさえも信用してはいけません。CGI へのリクエストはあなたの作ったフォームから送信されるとは限らないからです！

安全な方法をとるために、フォームから入力された文字をシェルに渡す場合、文字列に入っているのが英数文字、ダッシュ、アンダースコア、およびピリオドだけかどうかを確認してください。

CGI スクリプトを Unix システムにインストールする

あなたの使っている HTTP サーバのドキュメントを読んでください。そしてローカルシステムの管理者と一緒にどのディレクトリに CGI スクリプトをインストールすべきかを調べてください; 通常これはサーバのファイルシステムツリー内の cgi-bin ディレクトリです。

あなたのスクリプトが "others" によって読み取り可能および実行可能であることを確認してください; Unix ファイルモードは 8 進表記で 0o755 です (chmod 0755 filename を使ってください)。スクリプトの最初の行の 1 カラム目が、#! で開始し、その後に Python インタプリタへのパス名が続いていることを確認してください。例えば:

#!/usr/local/bin/python

Python インタプリタが存在し、"others" によって実行可能であることを確かめてください。

あなたのスクリプトが読み書きしなければならないファイルが全て "others" によって読み出しや書き込み可能であることを確かめてください --- 読み出し可能のファイルモードは 0o644 で、書き込み可能のファイルモードは 0o666 になるはずです。これは、セキュリティ上の理由から、 HTTP サーバがあなたのスクリプトを特権を全く持たないユーザ "nobody" の権限で実行するからです。この権限下では、誰でもが読める (書ける、実行できる) ファイルしか読み出し (書き込み、実行) できません。スクリプト実行時のディレクトリや環境変数のセットもあなたがログインしたときの設定と異なります。特に、実行ファイルに対するシェルの検索パス (PATH) や Python のモジュール検索パス (PYTHONPATH)が何らかの値に設定されていると期待してはいけません。

モジュールを Python の標準設定におけるモジュール検索パス上にないディレクトリからロードする必要がある場合、他のモジュールを取り込む前にスクリプト内で検索パスを変更できます。例えば:

import sys
sys.path.insert(0, "/usr/home/joe/lib/python")
sys.path.insert(0, "/usr/local/lib/python")

(この方法では、最後に挿入されたディレクトリが最初に検索されます！)

非 Unix システムにおける説明は変わるでしょう; あなたの使っている HTTP サーバのドキュメントを調べてください (普通は CGI スクリプトに関する節があります)。

CGI スクリプトをテストする

残念ながら、CGI スクリプトは普通、コマンドラインから起動しようとしても動きません。また、コマンドラインから起動した場合には完璧に動作するスクリプトが、不思議なことにサーバからの起動では失敗することがあります。しかし、スクリプトをコマンドラインから実行してみなければならない理由が一つあります: もしスクリプトが文法エラーを含んでいれば、Python インタプリタはそのプログラムを全く実行しないため、HTTP サーバはほとんどの場合クライアントに謎めいたエラーを送信するからです。

スクリプトが構文エラーを含まないのにうまく動作しないなら、次の節に読み進むしかありません。

CGI スクリプトをデバッグする

何よりもまず、些細なインストール関連のエラーでないか確認してください --- 上の CGI スクリプトのインストールに関する節を注意深く読めば時間を大いに節約できます。もしインストールの手続きを正しく理解しているか不安なら、このモジュールのファイル (cgi.py) をコピーして、CGI スクリプトとしてインストールしてみてください。このファイルはスクリプトとして呼び出すと、スクリプトの実行環境とフォームの内容を HTML 形式で出力します。ファイルに正しいモードを設定するなどして、リクエストを送ってみてください。標準的な cgi-bin ディレクトリにインストールされていれば、以下のような URL をブラウザに入力してリクエストを送信できるはずです:

http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home

もしタイプ 404 のエラーになるなら、サーバはスクリプトを発見できないでいます -- おそらくあなたはスクリプトを別のディレクトリに入れる必要があるのでしょう。他のエラーになるなら、先に進む前に解決しなければならないインストール上の問題があります。もし実行環境の情報とフォーム内容 (この例では、各フィールドはフィールド名 "addr" に対して値 "At Home"、およびフィールド名 "name" に対して "Joe Blow") が綺麗にフォーマットされて表示されるなら、 cgi.py スクリプトは正しくインストールされています。同じ操作をあなたの自作スクリプトに対して行えば、スクリプトをデバッグできるようになるはずです。

次のステップでは cgi モジュールの test() 関数を呼び出すことになります: メインプログラムコードを以下の 1 文と置き換えてください

cgi.test()

この操作で cgi.py ファイル自体をインストールした時と同じ結果を出力するはずです。

通常の Python スクリプトが例外を処理しきれずに送出した場合 (様々な理由: モジュール名のタイプミス、ファイルが開けなかった、など)、Python インタプリタはナイスなトレースバックを出力して終了します。Python インタプリタはあなたの CGI スクリプトが例外を送出した場合にも同様に振舞うので、トレースバックは大抵HTTP サーバのいずれかのログファイルに残るかまったく無視されるかです。

幸運なことに、あなたが自作のスクリプトで 何らかの コードを実行できるようになったら、 cgitb モジュールを使って簡単にトレースバックを web ブラウザに送信できます。まだそうでないなら、以下の2行:

import cgitb
cgitb.enable()

をスクリプトの先頭に追加してください。そしてスクリプトを再度走らせます; 問題が発生すれば、クラッシュの原因を見出せるような詳細な報告を読めます。

cgitb モジュールのインポートに問題がありそうだと思うなら、(組み込みモジュールだけを使った) もっと堅牢なアプローチを取れます:

import sys
sys.stderr = sys.stdout
print("Content-Type: text/plain")
print()
...your code here...

このコードは Python インタプリタがトレースバックを出力することに依存しています。出力のコンテント型はプレーンテキストに設定されており、全ての HTML 処理を無効にしています。スクリプトがうまく動作する場合、生の HTML コードがクライアントに表示されます。スクリプトが例外を送出する場合、最初の 2 行が出力された後、トレースバックが表示されます。HTML の解釈は行われないので、トレースバックを読めるはずです。

よくある問題と解決法

ほとんどの HTTP サーバはスクリプトの実行が完了するまで CGI からの出力をバッファします。このことは、スクリプトの実行中にクライアントが進捗状況報告を表示できないことを意味します。

上のインストールに関する説明を調べましょう。

HTTP サーバのログファイルを調べましょう。(別のウィンドウで tail -f logfile を実行すると便利かもしれません！)

常に python script.py などとして、スクリプトが構文エラーでないか調べましょう。

スクリプトに構文エラーがないなら、import cgitb; cgitb.enable() をスクリプトの先頭に追加してみましょう。

外部プログラムを起動するときには、スクリプトがそのプログラムを見つけられるようにしましょう。これは通常、絶対パス名を使うことを意味します --- PATH は普通、あまり CGI スクリプトにとって便利でない値に設定されています。

外部のファイルを読み書きする際には、CGI スクリプトを動作させるときに使われる userid でファイルを読み書きできるようになっているか確認しましょう: userid は通常、Web サーバを動作させている userid か、Web サーバの suexec 機能で明示的に指定している userid になります。

CGI スクリプトを set-uid モードにしてはいけません。これはほとんどのシステムで動作せず、セキュリティ上の信頼性もありません。

脚注

[1]

最近のバージョンの HTML 仕様ではフィールドの値を供給する順番を取り決めてはいますが、ある HTTP リクエストがその取り決めに準拠したブラウザから受信したものかどうか、そもそもブラウザから送信されたものかどうかの判別は退屈で間違いやすいので注意してください。

cgitb --- CGI スクリプトのトレースバック管理機構

ソースコード: Lib/cgitb.py [https://github.com/python/cpython/tree/3.12/Lib/cgitb.py]

バージョン 3.11 で非推奨、バージョン 3.13 で削除予定: The cgitb module is deprecated (see PEP 594 [https://peps.python.org/pep-0594/#cgitb] for details).

cgitb モジュールでは、Python スクリプトのための特殊な例外処理を提供します。(実はこの説明は少し的外れです。このモジュールはもともと徹底的なトレースバック情報を CGI スクリプトで生成した HTML 内に表示するための設計されました。その後この情報を平文テキストでも表示できるように一般化されています。) このモジュールの有効化後に捕捉されない例外が生じた場合、詳細で書式化された報告が Web ブラウザに送信されます。この報告には各レベルにおけるソースコードの抜粋が示されたトレースバックと、現在動作している関数の引数やローカルな変数が収められており、問題のデバッグを助けます。オプションとして、この情報をブラウザに送信する代わりにファイルに保存することもできます。

この機能を有効化するためには、単に自作の CGI スクリプトの最初に以下の2行を追加します:

import cgitb
cgitb.enable()

enable() 関数のオプションは、報告をブラウザに表示するかどうかと、後で解析するためにファイルに報告をログ記録するかどうかを制御します。

cgitb.enable(display=1, logdir=None, context=5, format='html')

この関数は、 sys.excepthook を設定することで、インタプリタの標準の例外処理を cgitb モジュールに肩代わりさせるようにします。

オプションの引数 display は標準で 1 になっており、この値は 0 にしてトレースバックをブラウザに送らないように抑制することもできます。引数 logdir が存在すれば、トレースバックレポートはそのファイルに書き込まれます。logdir の値はログファイルを配置するディレクトリです。オプション引数 context は、トレースバックの中で現在の行の周辺の何行を表示するかです; この値は標準で 5 です。オプション引数 format が "html" の場合、出力は HTML に書式化されます。その他の値を指定すると平文テキストの出力を強制します。デフォルトの値は "html" です。

cgitb.text(info, context=5)

この関数は info (sys.exc_info() の結果を含む 3 タプル) に記述されている例外を取り扱い、 テキストとしてトレースバックをフォーマットし、結果を文字列として返します。オプションの引数 context は、トレースバックにおいてソースコード行の前後のコンテキストを表示する行数です。デフォルトは 5 です。

cgitb.html(info, context=5)

この関数は info (sys.exc_info() の結果を含む 3 タプル) に記述されている例外を取り扱い、 HTML としてトレースバックをフォーマットし、結果を文字列として返します。オプションの引数 context は、トレースバックにおいてソースコード行の前後のコンテキストを表示する行数です。デフォルトは 5 です。

cgitb.handler(info=None)

この関数は標準の設定 (ブラウザに報告を表示しますがファイルにはログを書き込みません) を使って例外を処理します。この関数は、例外を捕捉した際に cgitb を使って報告したい場合に使うことができます。オプションの info 引数は、例外の型、例外の値、トレースバックオブジェクトからなる 3 要素のタプルでなければなりません。これは sys.exc_info() によって返される値と全く同じです。 info 引数が与えられていない場合、現在の例外は sys.exc_info() から取得されます。

chunk --- IFFチャンクデータの読み込み

ソースコード: Lib/chunk.py [https://github.com/python/cpython/tree/3.12/Lib/chunk.py]

バージョン 3.11 で非推奨、バージョン 3.13 で削除予定: The chunk module is deprecated (see PEP 594 [https://peps.python.org/pep-0594/#chunk] for details).

このモジュールはEA IFF 85チャンクを使用しているファイルの読み込みのためのインターフェースを提供します。[1] このフォーマットは少なくとも、Audio Interchange File Format (AIFF/AIFF-C) とReal Media File Format (RMFF)で使われています。WAVEオーディオファイルフォーマットも厳密に対応しているので、このモジュールで読み込みできます。

チャンクは以下の構造を持っています:

Offset値

長さ

内容

0

4

チャンクID

4

4

big- endianで示したチャンクのサイズで、ヘッダは含みません

8

n

バイトデータで、n はこれより先のフィールドのサイズ

8 + n

0 or 1

n が奇数ならチャンクの整頓のために埋められるバイト

IDはチャンクの種類を識別する4バイトの文字列です。

サイズフィールド（big-endianでエンコードされた32ビット値）は、8バイトのヘッダを含まないチャンクデータのサイズを示します。

普通、IFFタイプのファイルは1個かそれ以上のチャンクからなります。このモジュールで定義される Chunk クラスの使い方として提案しているのは、それぞれのチャンクの始めにインスタンスを作り、終わりに達するまでそのインスタンスから読み取り、その後で新しいインスタンスを作るということです。ファイルの終わりで新しいインスタンスを作ろうとすると、 EOFError の例外が発生して失敗します。

class chunk.Chunk(file, align=True, bigendian=True, inclheader=False)

チャンクを表わすクラス。 file 引数はファイル風オブジェクトであると期待されます。このクラスのインスタンスは特別に許可されます。唯一の必要なメソッドは read() です。メソッド seek() および tell() が存在し、例外を上げない場合、それらも使用されます。これらのメソッドが存在し、例外を上げる場合、それらのメソッドはオブジェクトを変更しないことが想定されます。オプションの引数 align が true の場合、チャンクは2バイト境界上で整列されていると仮定されます。 align が false の場合、整列は仮定されません。デフォルト値は true です。オプションの引数 bigendian が false の場合、チャンクサイズはリトルエンディアン順になっていると仮定されます。これは WAVE オーディオファイルに必要とされます。デフォルト値は true です。オプションの引数 inclheader が true の場合、チャンクヘッダ中で与えられたサイズはヘッダのサイズを含んでいます。デフォルト値は false です。

Chunk オブジェクトには以下のメソッドが定義されています:

getname()

チャンクの名前（ID）を返します。これはチャンクの始めの4バイトです。

getsize()

チャンクのサイズを返します。

close()

オブジェクトを閉じて、チャンクの終わりまで飛びます。これは元のファイル自体は閉じません。

close() メソッドが呼ばれた後で他のメソッドを呼ぶと OSError が送出されます。 Python 3.3 以前は IOError (現在は OSError の別名) が送出されていました。

isatty()

False を返します。

seek(pos, whence=0)

チャンクの現在位置を設定します。引数 whence は省略可能で、デフォルト値は 0 （ファイルの絶対位置）です; 他に 1 （現在位置から相対的にシークします）と 2 （ファイルの末尾から相対的にシークします）の値を取ります。何も値は返しません。もし元のファイルがシークに対応していなければ、前方へのシークのみが可能です。

tell()

チャンク内の現在位置を返します。

read(size=-1)

チャンクから最大で size バイト読み込みます ( size バイトを読み込むより前にチャンクの最後に行き着いたら、それより少なくなります) 。もし引数 size が負か省略されたら、チャンクの最後まで全てのデータを読み込みます。チャンクの最後に行き着いたら、空の bytes オブジェクトを返します。

skip()

チャンクの最後まで飛びます。さらにチャンクの read() を呼び出すと、 b'' が返されます。もしチャンクの内容に興味がないなら、このメソッドを呼び出してファイルポインタを次のチャンクの始めに設定します。

脚注

[1]

"EA IFF 85" Standard for Interchange Format Files, Jerry Morrison, Electronic Arts, January 1985.

crypt --- Unix パスワードをチェックするための関数

ソースコード: Lib/crypt.py [https://github.com/python/cpython/tree/3.12/Lib/crypt.py]

バージョン 3.11 で非推奨、バージョン 3.13 で削除予定: The crypt module is deprecated (see PEP 594 [https://peps.python.org/pep-0594/#crypt] for details and alternatives). The hashlib module is a potential replacement for certain use cases. The passlib [https://pypi.org/project/passlib/] package can replace all use cases of this module.

このモジュールは修正 DES アルゴリズムに基づいた一方向ハッシュ関数である crypt(3) [https://manpages.debian.org/crypt(3)] ルーチンを実装しています。詳細については Unix マニュアルページを参照してください。このモジュールは、実際に入力されたパスワードを記録することなくチェック出来るようにするためのハッシュ化パスワードを記録したり、Unix パスワードに (脆弱性検査のための) 辞書攻撃を試みるのに使えます。

このモジュールは実行環境の crypt(3) [https://manpages.debian.org/crypt(3)] の実装に依存しています。そのため、現在の実装で利用可能な拡張を、このモジュールでもそのまま利用できます。

Availability: Unix, not VxWorks.

利用可能性: Emscripten でなく、WASI でもないこと。

このモジュールは WebAssembly プラットフォーム wasm32-emscripten と wasm32-wasi では動作しないか、利用不可です。詳しくは、WebAssemblyプラットフォーム を見てください。

ハッシュ化方式

Added in version 3.3.

crypt モジュールはハッシュ化方式の一覧を定義しています (すべての方式がすべてのプラットフォームで使えるわけではありません):

crypt.METHOD_SHA512

A Modular Crypt Format method with 16 character salt and 86 character hash based on the SHA-512 hash function. This is the strongest method.

crypt.METHOD_SHA256

Another Modular Crypt Format method with 16 character salt and 43 character hash based on the SHA-256 hash function.

crypt.METHOD_BLOWFISH

Another Modular Crypt Format method with 22 character salt and 31 character hash based on the Blowfish cipher.

Added in version 3.7.

crypt.METHOD_MD5

Another Modular Crypt Format method with 8 character salt and 22 character hash based on the MD5 hash function.

crypt.METHOD_CRYPT

2文字のソルトと13文字のハッシュ値を持つモジュラー暗号形式です。これが最も弱い方式です。

モジュール属性

Added in version 3.3.

crypt.methods

利用可能なパスワードのハッシュアルゴリズムのリストを、crypt.METHOD_* オブジェクトとして返します。このリストは最も強いものから弱いものの順で並べられています。

モジュール関数

crypt モジュールは以下の関数を定義しています:

crypt.crypt(word, salt=None)

word will usually be a user's password as typed at a prompt or in a graphical interface. The optional salt is either a string as returned from mksalt(), one of the crypt.METHOD_* values (though not all may be available on all platforms), or a full encrypted password including salt, as returned by this function. If salt is not provided, the strongest method available in methods will be used.

通常は、生の文字列のパスワードを word として渡し、前回の crypt() を呼び出した結果と今回の呼び出しの結果が同じになることで、パスワードの確認を行います。

salt (2文字から16文字のランダムな文字列で、方式を示す $digit$ が先頭に付いているかもしれません) は、暗号化アルゴリズムにぶれを生じさせるために使われます。 salt に含まれる文字は、モジュラー暗号形式の先頭にある $digit$ を除いて、集合 [./a-zA-Z0-9] に含まれていなければいけません。

ハッシュ化されたパスワードを文字列として返します。それは salt と同じアルファベット文字から構成されます。

いくつかの拡張された crypt(3) [https://manpages.debian.org/crypt(3)] は異なる値と salt の長さを許しているので、パスワードをチェックする際には crypt されたパスワード文字列全体を salt として渡すよう勧めます。

バージョン 3.3 で変更: 文字列に加え、 salt が crypt.METHOD_* 値も受け取るようになりました。

crypt.mksalt(method=None, *, rounds=None)

Return a randomly generated salt of the specified method. If no method is given, the strongest method available in methods is used.

The return value is a string suitable for passing as the salt argument to crypt().

rounds specifies the number of rounds for METHOD_SHA256, METHOD_SHA512 and METHOD_BLOWFISH. For METHOD_SHA256 and METHOD_SHA512 it must be an integer between 1000 and 999_999_999, the default is 5000. For METHOD_BLOWFISH it must be a power of two between 16 (2⁴) and 2_147_483_648 (2³¹), the default is 4096 (2¹²).

Added in version 3.3.

バージョン 3.7 で変更: Added the rounds parameter.

使用例

典型的な使い方を簡単な例で示します (タイミング攻撃に晒されないように、一定時間の比較演算子を使う必要があり、 hmac.compare_digest() がこの目的にちょうど良いです):

import pwd
import crypt
import getpass
from hmac import compare_digest as compare_hash

def login():
    username = input('Python login: ')
    cryptedpasswd = pwd.getpwnam(username)[1]
    if cryptedpasswd:
        if cryptedpasswd == 'x' or cryptedpasswd == '*':
            raise ValueError('no support for shadow passwords')
        cleartext = getpass.getpass()
        return compare_hash(crypt.crypt(cleartext, cryptedpasswd), cryptedpasswd)
    else:
        return True

利用可能な方式のうち最も強い方式を使いパスワードのハッシュ値を生成し、元のパスワードと比較してチェックします:

import crypt
from hmac import compare_digest as compare_hash

hashed = crypt.crypt(plaintext)
if not compare_hash(hashed, crypt.crypt(plaintext, hashed)):
    raise ValueError("hashed version doesn't validate against original")

imghdr --- 画像の形式を決定する

ソースコード: Lib/imghdr.py [https://github.com/python/cpython/tree/3.12/Lib/imghdr.py]

バージョン 3.11 で非推奨、バージョン 3.13 で削除予定: The imghdr module is deprecated (see PEP 594 [https://peps.python.org/pep-0594/#imghdr] for details and alternatives).

imghdr モジュールはファイルやバイトストリームに含まれる画像の形式を決定します。

imghdr モジュールは次の関数を定義しています:

imghdr.what(file, h=None)

Test the image data contained in the file named file and return a string describing the image type. If h is provided, the file argument is ignored and h is assumed to contain the byte stream to test.

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

以下に what() からの戻り値とともにリストするように、次の画像形式が認識されます:

値

Image format

'rgb'

SGI ImgLib Files

'gif'

GIF 87a and 89a Files

'pbm'

Portable Bitmap Files

'pgm'

Portable Graymap Files

'ppm'

Portable Pixmap Files

'tiff'

TIFF Files

'rast'

Sun Raster Files

'xbm'

X Bitmap Files

'jpeg'

JPEG data in JFIF or Exif formats

'bmp'

BMP files

'png'

Portable Network Graphics

'webp'

WebP files

'exr'

OpenEXR Files

Added in version 3.5: フォーマット*exr*と*webp*が追加されました.

この変数に追加することで、あなたは imghdr が認識できるファイル形式のリストを拡張できます:

imghdr.tests

個別のテストを行う関数のリスト。それぞれの関数は二つの引数をとります: バイトストリームとオープンされたファイルのようにふるまうオブジェクト。 what() がバイトストリームとともに呼び出されたときは、ファイルのようにふるまうオブジェクトは None でしょう。

テストが成功した場合は、テスト関数は画像形式を表す文字列を返すべきです。あるいは、失敗した場合は None を返すべきです。

以下はプログラム例です:

>>> import imghdr
>>> imghdr.what('bass.gif')
'gif'

mailcap --- mailcap ファイルの操作

ソースコード: Lib/mailcap.py [https://github.com/python/cpython/tree/3.12/Lib/mailcap.py]

バージョン 3.11 で非推奨、バージョン 3.13 で削除予定: The mailcap module is deprecated (see PEP 594 [https://peps.python.org/pep-0594/#mailcap] for details). The mimetypes module provides an alternative.

mailcap ファイルは、メールリーダやウェブブラウザのような MIME 対応のアプリケーションが、異なる MIME タイプのファイルにどのように反応するかを設定するために使われます ("mailcap" の名前は "mail capability" から取られました)。例えば、ある mailcap ファイルに video/mpeg; xmpeg %s のような行が入っていたとします。ユーザが email メッセージやウェブドキュメント上でその MIME タイプ video/mpeg に遭遇すると、 %s はファイル名 (通常テンポラリファイルに属するものになります) に置き換えられ、ファイルを閲覧するためにxmpeg プログラムが自動的に起動されます。

mailcap の形式は RFC 1524 [https://datatracker.ietf.org/doc/html/rfc1524.html], "A User Agent Configuration Mechanism For Multimedia Mail Format Information" で文書化されていますが、この文書はインターネット標準ではありません。しかしながら、 mailcap ファイルはほとんどの Unix システムでサポートされています。

mailcap.findmatch(caps, MIMEtype, key='view', filename='/dev/null', plist=[])

2 要素のタプルを返します; 最初の要素は文字列で、実行すべきコマンド (os.system() に渡されます) が入っています。二つめの要素は与えられた MIME タイプに対する mailcap エントリです。一致する MIME タイプが見つからなかった場合、 (None, None) が返されます。

key は desired フィールドの値で、実行すべき動作のタイプを表現します; ほとんどの場合、単に MIME 形式のデータ本体を見たいと思うので、標準の値は 'view' になっています。与えられた MIME 型をもつ新たなデータ本体を作成した場合や、既存のデータ本体を置き換えたい場合には、'view' の他に 'compose' および 'edit' を取ることもできます。これらフィールドの完全なリストについては RFC 1524 [https://datatracker.ietf.org/doc/html/rfc1524.html] を参照してください。

filename はコマンドライン中で %s に代入されるファイル名です; 標準の値は '/dev/null' で、たいていこの値を使いたいわけではないはずです。従って、ファイル名を指定してこのフィールドを上書きする必要があるでしょう。

plist は名前付けされたパラメタのリストです; 標準の値は単なる空のリストです。リスト中の各エントリはパラメタ名を含む文字列、等号 ('=')、およびパラメタの値でなければなりません。mailcap エントリには %{foo} といったような名前つきのパラメタを含めることができ、'foo' と名づけられたパラメタの値に置き換えられます。例えば、コマンドライン showpartial %{id} %{number} %{total} が mailcap ファイルにあり、plist が ['id=1', 'number=2', 'total=3'] に設定されていれば、コマンドラインは 'showpartial 1 2 3' になります。

mailcap ファイル中では、オプションの "test" フィールドを使って、(計算機アーキテクチャや、利用しているウィンドウシステムといった) 何らかの外部条件をテストするよう指定することができます。 findmatch() はこれらの条件を自動的にチェックし、チェックが失敗したエントリを読み飛ばします。

バージョン 3.11 で変更: To prevent security issues with shell metacharacters (symbols that have special effects in a shell command line), findmatch will refuse to inject ASCII characters other than alphanumerics and @+=:,./-_ into the returned command line.

If a disallowed character appears in filename, findmatch will always return (None, None) as if no entry was found. If such a character appears elsewhere (a value in plist or in MIMEtype), findmatch will ignore all mailcap entries which use that value. A warning will be raised in either case.

mailcap.getcaps()

MIME タイプを mailcap ファイルのエントリに対応付ける辞書を返します。この辞書は findmatch() 関数に渡されるべきものです。エントリは辞書のリストとして記憶されますが、この表現形式の詳細について知っておく必要はないでしょう。

mailcap 情報はシステム上で見つかった全ての mailcap ファイルから導出されます。ユーザ設定の mailcap ファイル $HOME/.mailcap はシステムの mailcap ファイル /etc/mailcap 、 /usr/etc/mailcap 、および /usr/local/etc/mailcap の内容を上書きします。

以下に使用例を示します:

>>> import mailcap
>>> d = mailcap.getcaps()
>>> mailcap.findmatch(d, 'video/mpeg', filename='tmp1223')
('xmpeg tmp1223', {'view': 'xmpeg %s'})

msilib --- Microsoft インストーラーファイルの読み書き

ソースコード: Lib/msilib/__init__.py [https://github.com/python/cpython/tree/3.12/Lib/msilib/__init__.py]

バージョン 3.11 で非推奨、バージョン 3.13 で削除予定: The msilib module is deprecated (see PEP 594 [https://peps.python.org/pep-0594/#msilib] for details).

msilib モジュールは Microsoft インストーラー(.msi)の作成を支援します。このファイルは大抵の場合埋め込まれた「キャビネット」ファイル (.cab) を含むので、CAB ファイル作成用の API も公開されています。.cab ファイルの読み出しは現時点では実装されていませんが、 .msi データベースの読み出しは可能です。

このパッケージの目的は .msi ファイルにある全てのテーブルへの完全なアクセスの提供であり、提供されているものは非常に低レベルな API です。このパッケージの一つの主要な使用目的は Python インストーラーパッケージそれ自体(と言いつつ現在は別バージョンの msilib を使っているのですが)です。

パッケージの内容は大きく四つのパートに分けられます。低レベル CAB ルーチン、低レベル MSI ルーチン、少し高レベルの MSI ルーチン、標準的なテーブル構造、の四つです。

msilib.FCICreate(cabname, files)

新しい CAB ファイルを cabname という名前で作ります。files はタプルのリストで、それぞれのタプルはディスク上のファイル名と CAB ファイルで付けられるファイル名で構成されなければなりません。

ファイルはリストに現れた順番で CAB ファイルに追加されます。全てのファイルは MSZIP 圧縮アルゴリズムを使って一つの CAB ファイルに追加されます。

MSI 作成の様々なステップに対する Python コールバックは現在公開されていません。

msilib.UuidCreate()

新しい一意な識別子の文字列表現を返します。この関数は Windows API の関数 UuidCreate() と UuidToString() をラップしたものです。

msilib.OpenDatabase(path, persist)

MsiOpenDatabase を呼び出して新しいデータベースオブジェクトを返します。path は MSI ファイルのファイル名です。persist は五つの定数 MSIDBOPEN_CREATEDIRECT, MSIDBOPEN_CREATE, MSIDBOPEN_DIRECT, MSIDBOPEN_READONLY, MSIDBOPEN_TRANSACT のどれか一つで、フラグ MSIDBOPEN_PATCHFILE を含めても構いません。これらのフラグの意味は Microsoft のドキュメントを参照してください。フラグに従って、既存のデータベースを開いたり新しいデータベースを作成したりします。

msilib.CreateRecord(count)

MSICreateRecord() を呼び出して新しいレコードオブジェクトを返します。 count はレコードのフィールドの数です。

msilib.init_database(name, schema, ProductName, ProductCode, ProductVersion, Manufacturer)

name という名前の新しいデータベースを作り、schema で初期化し、プロパティ ProductName, ProductCode, ProductVersion, Manufacturer をセットして、返します。

schema は tables と _Validation_records という属性をもったモジュールオブジェクトでなければなりません。大抵の場合、 msilib.schema を使うべきです。

データベースはこの関数から返された時点でスキーマとバリデーションレコードだけが収められています。

msilib.add_data(database, table, records)

全ての records を database の table テーブルに追加します。

table 引数は MSI スキーマで事前に定義されたテーブルでなければなりません。例えば、'Feature', 'File', 'Component', 'Dialog', 'Control', などです。

records はタプルのリストで、それぞれのタプルにはテーブルのスキーマに従ったレコードの全てのフィールドを含んでいるものでなければなりません。オプションのフィールドには None を渡すことができます。

フィールドの値には、整数・文字列・Binary クラスのインスタンスが使えます。

class msilib.Binary(filename)

Binary テーブル中のエントリーを表わします。 add_data() を使ってこのクラスのオブジェクトを挿入するときには filename という名前のファイルをテーブルに読み込みます。

msilib.add_tables(database, module)

module の全てのテーブルの内容を database に追加します。module は tables という内容が追加されるべき全てのテーブルのリストと、テーブルごとに一つある実際の内容を持っている属性とを含んでいなければなりません。

この関数は典型的にシーケンステーブルをインストールするために使われます。

msilib.add_stream(database, name, path)

database の _Stream テーブルに、ファイル path を name というストリーム名で追加します。

msilib.gen_uuid()

新しい UUID を、MSI が通常要求する形式(つまり、中括弧で囲み、16進数は大文字)で返します。

参考

FCICreate [https://msdn.microsoft.com/en-us/library/bb432265.aspx] UuidCreate [https://msdn.microsoft.com/en-us/library/windows/desktop/aa379205.aspx] UuidToString [https://msdn.microsoft.com/en-us/library/windows/desktop/aa379352.aspx]

データベースオブジェクト

Database.OpenView(sql)

MSIDatabaseOpenView() を呼び出して取得したビューオブジェクトを返します。 sql は実行される SQL ステートメントです。

Database.Commit()

MSIDatabaseCommit() を呼び出して現在のトランザクションで保留されている変更をコミットします。

Database.GetSummaryInformation(count)

MsiGetSummaryInformation() を呼び出して新しいサマリー情報オブジェクトを返します。 count は更新された値の最大数です。

Database.Close()

MsiCloseHandle() を通してデータベースオブジェクトを閉じます。

Added in version 3.7.

参考

MSIDatabaseOpenView [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370082.aspx] MSIDatabaseCommit [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370075.aspx] MSIGetSummaryInformation [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370301.aspx] MsiCloseHandle [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370067.aspx]

ビューオブジェクト

View.Execute(params)

MSIViewExecute() を通してビューに対する SQL 問い合わせを実行します。 params が None でない場合、クエリ中のパラメータトークンの実際の値を与えるものです。

View.GetColumnInfo(kind)

MsiViewGetColumnInfo() の呼び出しを通してビューのカラムを説明するレコードを返します。 kind は MSICOLINFO_NAMES または MSICOLINFO_TYPES です。

View.Fetch()

MsiViewFetch() の呼び出しを通してクエリの結果レコードを返します。

View.Modify(kind, data)

MsiViewModify() を呼び出してビューを変更します。 kind は MSIMODIFY_SEEK, MSIMODIFY_REFRESH, MSIMODIFY_INSERT, MSIMODIFY_UPDATE, MSIMODIFY_ASSIGN, MSIMODIFY_REPLACE, MSIMODIFY_MERGE, MSIMODIFY_DELETE, MSIMODIFY_INSERT_TEMPORARY, MSIMODIFY_VALIDATE, MSIMODIFY_VALIDATE_NEW, MSIMODIFY_VALIDATE_FIELD, MSIMODIFY_VALIDATE_DELETE のいずれかです。

data は新しいデータを表わすレコードでなければなりません。

View.Close()

MsiViewClose() を通してビューを閉じます。

参考

MsiViewExecute [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370513.aspx] MSIViewGetColumnInfo [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370516.aspx] MsiViewFetch [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370514.aspx] MsiViewModify [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370519.aspx] MsiViewClose [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370510.aspx]

サマリー情報オブジェクト

SummaryInformation.GetProperty(field)

MsiSummaryInfoGetProperty() を通してサマリーのプロパティを返します。 field はプロパティ名で、定数 PID_CODEPAGE, PID_TITLE, PID_SUBJECT, PID_AUTHOR, PID_KEYWORDS, PID_COMMENTS, PID_TEMPLATE, PID_LASTAUTHOR, PID_REVNUMBER, PID_LASTPRINTED, PID_CREATE_DTM, PID_LASTSAVE_DTM, PID_PAGECOUNT, PID_WORDCOUNT, PID_CHARCOUNT, PID_APPNAME, PID_SECURITY のいずれかです。

SummaryInformation.GetPropertyCount()

MsiSummaryInfoGetPropertyCount() を通してサマリープロパティの個数を返します。

SummaryInformation.SetProperty(field, value)

MsiSummaryInfoSetProperty() を通してプロパティをセットします。 field は GetProperty() におけるものと同じ値をとります。 value はプロパティの新しい値です。許される値の型は整数と文字列です。

SummaryInformation.Persist()

MsiSummaryInfoPersist() を使って変更されたプロパティをサマリー情報ストリームに書き込みます。

参考

MsiSummaryInfoGetProperty [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370409.aspx] MsiSummaryInfoGetPropertyCount [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370488.aspx] MsiSummaryInfoSetProperty [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370491.aspx] MsiSummaryInfoPersist [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370490.aspx]

レコードオブジェクト

Record.GetFieldCount()

MsiRecordGetFieldCount() を通してレコードのフィールド数を返します。

Record.GetInteger(field)

field の値を可能なら整数として返します。field は整数でなければなりません。

Record.GetString(field)

field の値を可能なら文字列として返します。field は整数でなければなりません。

Record.SetString(field, value)

MsiRecordSetString() を通して field を value にセットします。 field は整数、 value は文字列でなければなりません。

Record.SetStream(field, value)

MsiRecordSetStream() を通して field を value という名のファイルの内容にセットします。 field は整数、 value は文字列でなければなりません。

Record.SetInteger(field, value)

MsiRecordSetInteger() を通して field を value にセットします。 field も value も整数でなければなりません。

Record.ClearData()

MsiRecordClearData() を通してレコードの全てのフィールドを 0 にセットします。

参考

MsiRecordGetFieldCount [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370366.aspx] MsiRecordSetString [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370373.aspx] MsiRecordSetStream [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370372.aspx] MsiRecordSetInteger [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370371.aspx] MsiRecordClearData [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370364.aspx]

エラー

全ての MSI 関数のラッパーは MSIError を送出します。例外の内部の文字列がより詳細な情報を含んでいます。

CAB オブジェクト

class msilib.CAB(name)

CAB クラスは CAB ファイルを表わすものです。MSI 構築中、ファイルは Files テーブルと CAB ファイルとに同時に追加されます。そして、全てのファイルを追加し終えたら、CAB ファイルは書き込まれることが可能になり、MSI ファイルに追加されます。

name は MSI ファイル中の CAB ファイルの名前です。

append(full, file, logical)

パス名 full のファイルを CAB ファイルに logical という名で追加します。logical という名が既に存在したならば、新しいファイル名が作られます。

ファイルの CAB ファイル中のインデクスと新しいファイル名を返します。

commit(database)

CAB ファイルを作り、MSI ファイルにストリームとして追加し、Media テーブルに送り込み、作ったファイルはディスクから削除します。

ディレクトリオブジェクト

class msilib.Directory(database, cab, basedir, physical, logical, default[, componentflags])

新しいディレクトリを Directory テーブルに作成します。ディレクトリには各時点で現在のコンポーネントがあります。そのコンポーネントは start_component() を使って明示的に作成されたか、最初にファイルが追加された際に暗黙裡に作成されたものです。ファイルは現在のコンポーネントと cab ファイルの両方に追加されます。ディレクトリを作成するには親ディレクトリオブジェクト(None でも可)、物理的ディレクトリへのパス、論理的ディレクトリ名を指定する必要があります。 default はディレクトリテーブルの DefaultDir スロットを指定します。 componentflags は新しいコンポーネントが得るデフォルトのフラグを指定します。

start_component(component=None, feature=None, flags=None, keyfile=None, uuid=None)

エントリを Component テーブルに追加し、このコンポーネントをこのディレクトリの現在のコンポーネントにします。もしコンポーネント名が与えられなければディレクトリ名が使われます。feature が与えられなければ、ディレクトリのデフォルトフラグが使われます。keyfile が与えられなければ、Component テーブルの KeyPath は null のままになります。

add_file(file, src=None, version=None, language=None)

ファイルをディレクトリの現在のコンポーネントに追加します。現在のコンポーネントが存在しない場合、新しいコンポーネントを開始します。デフォルトではソースとファイルテーブルのファイル名は同じになります。src ファイルが指定された場合、それは現在のディレクトリから相対的に解釈されます。オプションで version と language を File テーブルのエントリ用に指定することができます。

glob(pattern, exclude=None)

現在のコンポーネントに glob パターンで指定されたファイルのリストを追加します。個々のファイルを exclude リストで除外することができます。

remove_pyc()

アンインストールの際に .pyc を削除します。

参考

Directory Table [https://msdn.microsoft.com/en-us/library/windows/desktop/aa368295.aspx] File Table [https://msdn.microsoft.com/en-us/library/windows/desktop/aa368596.aspx] Component Table [https://msdn.microsoft.com/en-us/library/windows/desktop/aa368007.aspx] FeatureComponents Table [https://msdn.microsoft.com/en-us/library/windows/desktop/aa368579.aspx]

フィーチャー

class msilib.Feature(db, id, title, desc, display, level=1, parent=None, directory=None, attributes=0)

id, parent.id, title, desc, display, level, directory, attributes の値を使って、新しいレコードを Feature テーブルに追加します。出来上がったフィーチャーオブジェクトは Directory の start_component() メソッドに渡すことができます。

set_current()

このフィーチャーを msilib の現在のフィーチャーにします。フィーチャーを明示的に指定しない場合、新しいコンポーネントが自動的にデフォルトのフィーチャーに追加されます。

参考

Feature Table [https://msdn.microsoft.com/en-us/library/windows/desktop/aa368585.aspx]

GUI クラス

msilib provides several classes that wrap the GUI tables in an MSI database. However, no standard user interface is provided.

class msilib.Control(dlg, name)

ダイアログコントロールの基底クラス。dlg はコントロールの属するダイアログオブジェクト、name はコントロールの名前です。

event(event, argument, condition=1, ordering=None)

このコントロールの ControlEvent テーブルにエントリを作ります。

mapping(event, attribute)

このコントロールの EventMapping テーブルにエントリを作ります。

condition(action, condition)

このコントロールの ControlCondition テーブルにエントリを作ります。

class msilib.RadioButtonGroup(dlg, name, property)

name という名前のラジオボタンコントロールを作成します。property はラジオボタンが選ばれたときにセットされるインストーラープロパティです。

add(name, x, y, width, height, text, value=None)

グループに name という名前で、座標 x, y に大きさが width, height で text というラベルの付いたラジオボタンを追加します。value が None なら、デフォルトは name になります。

class msilib.Dialog(db, name, x, y, w, h, attr, title, first, default, cancel)

新しい Dialog オブジェクトを返します。 Dialog テーブルを以下の引数に渡された情報を元に作成します: 座標、ダイアログ属性、タイトル、first・default・cancelという三つのコントロールに対する名前。

control(name, type, x, y, width, height, attributes, property, text, control_next, help)

新しい Control オブジェクトを返します。 Control テーブルに指定されたパラメータのエントリが作られます。

これは汎用のメソッドで、特定の型に対しては特化したメソッドが提供されています。

text(name, x, y, width, height, attributes, text)

Text コントロールを追加して返します。

bitmap(name, x, y, width, height, text)

Bitmap コントロールを追加して返します。

line(name, x, y, width, height)

Line コントロールを追加して返します。

pushbutton(name, x, y, width, height, attributes, text, next_control)

PushButton コントロールを追加して返します。

radiogroup(name, x, y, width, height, attributes, property, text, next_control)

RadioButtonGroup コントロールを追加して返します。

checkbox(name, x, y, width, height, attributes, property, text, next_control)

CheckBox コントロールを追加して返します。

参考

Dialog Table [https://msdn.microsoft.com/en-us/library/windows/desktop/aa368286.aspx] Control Table [https://msdn.microsoft.com/en-us/library/windows/desktop/aa368044.aspx] Control Types [https://msdn.microsoft.com/en-us/library/windows/desktop/aa368039.aspx] ControlCondition Table [https://msdn.microsoft.com/en-us/library/windows/desktop/aa368035.aspx] ControlEvent Table [https://msdn.microsoft.com/en-us/library/windows/desktop/aa368037.aspx] EventMapping Table [https://msdn.microsoft.com/en-us/library/windows/desktop/aa368559.aspx] RadioButton Table [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370962.aspx]

事前に計算されたテーブル

msilib はスキーマとテーブル定義だけから成るサブパッケージをいくつか提供しています。現在のところ、これらの定義は MSI バージョン 2.0 に基づいています。

msilib.schema

これは MSI 2.0 用の標準 MSI スキーマで、テーブル定義のリストを提供する tables 変数と、MSI バリデーション用のデータを提供する _Validation_records 変数があります。

msilib.sequence

このモジュールは標準シーケンステーブルのテーブル内容を含んでいます。AdminExecuteSequence, AdminUISequence, AdvtExecuteSequence, InstallExecuteSequence, InstallUISequence が含まれています。

msilib.text

このモジュールは標準的なインストーラーのアクションのための UIText および ActionText テーブルの定義を含んでいます。

nis --- Sun の NIS (Yellow Pages) へのインターフェース

バージョン 3.11 で非推奨、バージョン 3.13 で削除予定: The nis module is deprecated (see PEP 594 [https://peps.python.org/pep-0594/#nis] for details).

nis モジュールは複数のホストを集中管理する上で便利な NIS ライブラリを薄くラップします。

NIS は Unix システム上にしかないので、このモジュールは Unix でしか利用できません。

利用可能性: Emscripten でなく、WASI でもないこと。

このモジュールは WebAssembly プラットフォーム wasm32-emscripten と wasm32-wasi では動作しないか、利用不可です。詳しくは、WebAssemblyプラットフォーム を見てください。

nis モジュールでは以下の関数を定義しています:

nis.match(key, mapname, domain=default_domain)

mapname 中で key に一致するものを返すか、見つからない場合にはエラー (nis.error) を送出します。両方の引数とも文字列で、 key は 8 ビットクリーンです。返される値は (NULL その他を含む可能性のある) 任意のバイト列です。

mapname は他の名前の別名になっていないか最初にチェックされます。

domain 引数は検索に使うNISドメインを上書きできます。指定されなければ、デフォルトNISドメイン内が検索されます。

nis.cat(mapname, domain=default_domain)

match(key, mapname)==value となる key を value に対応付ける辞書を返します。辞書内のキーと値は共に任意のバイト列なので注意してください。

mapname は他の名前の別名になっていないか最初にチェックされます。

domain 引数は検索に使うNISドメインを上書きできます。指定されなければ、デフォルトNISドメイン内が検索されます。

nis.maps(domain=default_domain)

有効なマップのリストを返します。

domain 引数は検索に使うNISドメインを上書きできます。指定されなければ、デフォルトNISドメイン内が検索されます。

nis.get_default_domain()

システムのデフォルトNISドメインを返します。

nis モジュールは以下の例外を定義しています:

exception nis.error

NIS 関数がエラーコードを返した場合に送出されます。

nntplib --- NNTP プロトコルクライアント

ソースコード: Lib/nntplib.py [https://github.com/python/cpython/tree/3.12/Lib/nntplib.py]

バージョン 3.11 で非推奨: The nntplib module is deprecated (see PEP 594 [https://peps.python.org/pep-0594/] for details).

This module defines the class NNTP which implements the client side of the Network News Transfer Protocol. It can be used to implement a news reader or poster, or automated news processors. It is compatible with RFC 3977 [https://datatracker.ietf.org/doc/html/rfc3977.html] as well as the older RFC 977 [https://datatracker.ietf.org/doc/html/rfc977.html] and RFC 2980 [https://datatracker.ietf.org/doc/html/rfc2980.html].

利用可能性: Emscripten でなく、WASI でもないこと。

このモジュールは WebAssembly プラットフォーム wasm32-emscripten と wasm32-wasi では動作しないか、利用不可です。詳しくは、WebAssemblyプラットフォーム を見てください。

以下にこのモジュールの使い方の小さな例を二つ示します。ニュースグループに関する統計情報を列挙し、最新 10 件の記事を出力するには以下のようにします:

>>> s = nntplib.NNTP('news.gmane.io')
>>> resp, count, first, last, name = s.group('gmane.comp.python.committers')
>>> print('Group', name, 'has', count, 'articles, range', first, 'to', last)
Group gmane.comp.python.committers has 1096 articles, range 1 to 1096
>>> resp, overviews = s.over((last - 9, last))
>>> for id, over in overviews:
...     print(id, nntplib.decode_header(over['subject']))
...
1087 Re: Commit privileges for Łukasz Langa
1088 Re: 3.2 alpha 2 freeze
1089 Re: 3.2 alpha 2 freeze
1090 Re: Commit privileges for Łukasz Langa
1091 Re: Commit privileges for Łukasz Langa
1092 Updated ssh key
1093 Re: Updated ssh key
1094 Re: Updated ssh key
1095 Hello fellow committers!
1096 Re: Hello fellow committers!
>>> s.quit()
'205 Bye!'

バイナリファイルから記事を投稿するには、以下のようにします。 (この例では記事番号は有効な番号を指定していて、あなたがそのニュースグループに投稿する 権限を持っていると仮定しています)

>>> s = nntplib.NNTP('news.gmane.io')
>>> f = open('article.txt', 'rb')
>>> s.post(f)
'240 Article posted successfully.'
>>> s.quit()
'205 Bye!'

このモジュール自体では以下のクラスを定義しています:

class nntplib.NNTP(host, port=119, user=None, password=None, readermode=None, usenetrc=False[, timeout])

Return a new NNTP object, representing a connection to the NNTP server running on host host, listening at port port. An optional timeout can be specified for the socket connection. If the optional user and password are provided, or if suitable credentials are present in /.netrc and the optional flag usenetrc is true, the AUTHINFO USER and AUTHINFO PASS commands are used to identify and authenticate the user to the server. If the optional flag readermode is true, then a mode reader command is sent before authentication is performed. Reader mode is sometimes necessary if you are connecting to an NNTP server on the local machine and intend to call reader-specific commands, such as group. If you get unexpected NNTPPermanentErrors, you might need to set readermode. The NNTP class supports the with statement to unconditionally consume OSError exceptions and to close the NNTP connection when done, e.g.:

>>> from nntplib import NNTP
>>> with NNTP('news.gmane.io') as n:
...     n.group('gmane.comp.python.committers')
...
('211 1755 1 1755 gmane.comp.python.committers', 1755, 1, 1755, 'gmane.comp.python.committers')
>>>

引数 self, host, port を指定して 監査イベント nntplib.connect を送出します。

引数 self, line を指定して 監査イベント nntplib.putline を送出します。

バージョン 3.2 で変更: usenetrc がデフォルトで False になりました。

バージョン 3.3 で変更: with 構文のサポートが追加されました。

バージョン 3.9 で変更: timeout パラメータが0に設定されている場合、非ブロッキングソケットの作成を防ぐために ValueError を送出します。

class nntplib.NNTP_SSL(host, port=563, user=None, password=None, ssl_context=None, readermode=None, usenetrc=False[, timeout])

Return a new NNTP_SSL object, representing an encrypted connection to the NNTP server running on host host, listening at port port. NNTP_SSL objects have the same methods as NNTP objects. If port is omitted, port 563 (NNTPS) is used. ssl_context is also optional, and is a SSLContext object. Please read セキュリティで考慮すべき点 for best practices. All other parameters behave the same as for NNTP.

Note that SSL-on-563 is discouraged per RFC 4642 [https://datatracker.ietf.org/doc/html/rfc4642.html], in favor of STARTTLS as described below. However, some servers only support the former.

引数 self, host, port を指定して 監査イベント nntplib.connect を送出します。

引数 self, line を指定して 監査イベント nntplib.putline を送出します。

Added in version 3.2.

バージョン 3.4 で変更: このクラスは ssl.SSLContext.check_hostname と Server Name Indication でホスト名のチェックをサポートしました。(ssl.HAS_SNI を参照してください)。

バージョン 3.9 で変更: timeout パラメータが0に設定されている場合、非ブロッキングソケットの作成を防ぐために ValueError を送出します。

exception nntplib.NNTPError

標準の例外 Exception から派生しており、 nntplib モジュールが送出する全ての例外の基底クラスです。このクラスのインスタンスは以下の属性を持っています:

response

利用可能な場合サーバの応答です。str オブジェクトです。

exception nntplib.NNTPReplyError

サーバから想定外の応答があったときに送出される例外。

exception nntplib.NNTPTemporaryError

400--499の範囲の応答コードを受け取ったときに送出される例外。

exception nntplib.NNTPPermanentError

500--599の範囲の応答コードを受け取ったときに送出される例外。

exception nntplib.NNTPProtocolError

1--5の数字で始まらない応答コードをサーバから受け取ったときに送出される例外。

exception nntplib.NNTPDataError

応答データに何らかのエラーがあったときに送出される例外。

NNTP オブジェクト

接続されたとき NNTP および NNTP_SSL オブジェクトは以下のメソッドと属性をサポートします:

属性

NNTP.nntp_version

サーバがサポートしている NNTP プロトコルのバージョンを表す整数です。実際のところ、この値は RFC 3977 [https://datatracker.ietf.org/doc/html/rfc3977.html] 準拠を通知しているサーバでは 2 で、他の場合は 1 のはずです。

Added in version 3.2.

NNTP.nntp_implementation

NNTP サーバのソフトウェア名とバージョンを記述する文字列です。サーバが通知していない場合は None です。

Added in version 3.2.

メソッド

全てのメソッドにおける戻り値のタプルで最初の要素となる response は、サーバの応答です: この文字列は 3 桁の数字からなるコードで始まります。サーバの応答がエラーを示す場合、上記のいずれかの例外が送出されます。

Many of the following methods take an optional keyword-only argument file. When the file argument is supplied, it must be either a file object opened for binary writing, or the name of an on-disk file to be written to. The method will then write any data returned by the server (except for the response line and the terminating dot) to the file; any list of lines, tuples or objects that the method normally returns will be empty.

バージョン 3.2 で変更: 以下のメソッドの多くは改訂・修正されました。このため、3.1 のものとは互換性がありません。

NNTP.quit()

QUIT 命令を送信し、接続を閉じます。このメソッドを呼び出した後は、NTTP オブジェクトの他のいかなるメソッドも呼び出してはいけません。

NNTP.getwelcome()

サーバに最初に接続した際に送信される応答中のウェルカムメッセージを返します。(このメッセージには時に、ユーザにとって重要な免責事項や ヘルプ情報が入っています。)

NNTP.getcapabilities()

Return the RFC 3977 [https://datatracker.ietf.org/doc/html/rfc3977.html] capabilities advertised by the server, as a dict instance mapping capability names to (possibly empty) lists of values. On legacy servers which don't understand the CAPABILITIES command, an empty dictionary is returned instead.

>>> s = NNTP('news.gmane.io')
>>> 'POST' in s.getcapabilities()
True

Added in version 3.2.

NNTP.login(user=None, password=None, usenetrc=True)

Send AUTHINFO commands with the user name and password. If user and password are None and usenetrc is true, credentials from ~/.netrc will be used if possible.

Unless intentionally delayed, login is normally performed during the NNTP object initialization and separately calling this function is unnecessary. To force authentication to be delayed, you must not set user or password when creating the object, and must set usenetrc to False.

Added in version 3.2.

NNTP.starttls(context=None)

Send a STARTTLS command. This will enable encryption on the NNTP connection. The context argument is optional and should be a ssl.SSLContext object. Please read セキュリティで考慮すべき点 for best practices.

Note that this may not be done after authentication information has been transmitted, and authentication occurs by default if possible during a NNTP object initialization. See NNTP.login() for information on suppressing this behavior.

Added in version 3.2.

バージョン 3.4 で変更: このメソッドは ssl.SSLContext.check_hostname と Server Name Indication でホスト名のチェックをサポートしました。(ssl.HAS_SNI を参照してください)。

NNTP.newgroups(date, *, file=None)

Send a NEWGROUPS command. The date argument should be a datetime.date or datetime.datetime object. Return a pair (response, groups) where groups is a list representing the groups that are new since the given date. If file is supplied, though, then groups will be empty.

>>> from datetime import date, timedelta
>>> resp, groups = s.newgroups(date.today() - timedelta(days=3))
>>> len(groups)
85
>>> groups[0]
GroupInfo(group='gmane.network.tor.devel', last='4', first='1', flag='m')

NNTP.newnews(group, date, *, file=None)

Send a NEWNEWS command. Here, group is a group name or '*', and date has the same meaning as for newgroups(). Return a pair (response, articles) where articles is a list of message ids.

このコマンドは NNTP サーバ管理者に無効にされていることがよくあります。

NNTP.list(group_pattern=None, *, file=None)

Send a LIST or LIST ACTIVE command. Return a pair (response, list) where list is a list of tuples representing all the groups available from this NNTP server, optionally matching the pattern string group_pattern. Each tuple has the form (group, last, first, flag), where group is a group name, last and first are the last and first article numbers, and flag usually takes one of these values:

y: Local postings and articles from peers are allowed.

m: The group is moderated and all postings must be approved.

n: No local postings are allowed, only articles from peers.

j: Articles from peers are filed in the junk group instead.

x: No local postings, and articles from peers are ignored.

=foo.bar: Articles are filed in the foo.bar group instead.

If flag has another value, then the status of the newsgroup should be considered unknown.

This command can return very large results, especially if group_pattern is not specified. It is best to cache the results offline unless you really need to refresh them.

バージョン 3.2 で変更: group_pattern が追加されました。

NNTP.descriptions(grouppattern)

Send a LIST NEWSGROUPS command, where grouppattern is a wildmat string as specified in RFC 3977 [https://datatracker.ietf.org/doc/html/rfc3977.html] (it's essentially the same as DOS or UNIX shell wildcard strings). Return a pair (response, descriptions), where descriptions is a dictionary mapping group names to textual descriptions.

>>> resp, descs = s.descriptions('gmane.comp.python.*')
>>> len(descs)
295
>>> descs.popitem()
('gmane.comp.python.bio.general', 'BioPython discussion list (Moderated)')

NNTP.description(group)

単一のグループ group から説明文字列を取り出します。 ('group' が実際には wildmat 文字列で) 複数のグループがマッチした場合、 最初にマッチしたものを返します。何もマッチしなければ空文字列を返します。

このメソッドはサーバからの応答コードを省略します。応答コードが必要なら、 descriptions() を使ってください。

NNTP.group(name)

Send a GROUP command, where name is the group name. The group is selected as the current group, if it exists. Return a tuple (response, count, first, last, name) where count is the (estimated) number of articles in the group, first is the first article number in the group, last is the last article number in the group, and name is the group name.

NNTP.over(message_spec, *, file=None)

Send an OVER command, or an XOVER command on legacy servers. message_spec can be either a string representing a message id, or a (first, last) tuple of numbers indicating a range of articles in the current group, or a (first, None) tuple indicating a range of articles starting from first to the last article in the current group, or None to select the current article in the current group.

Return a pair (response, overviews). overviews is a list of (article_number, overview) tuples, one for each article selected by message_spec. Each overview is a dictionary with the same number of items, but this number depends on the server. These items are either message headers (the key is then the lower-cased header name) or metadata items (the key is then the metadata name prepended with ":"). The following items are guaranteed to be present by the NNTP specification:

the subject, from, date, message-id and references headers

the :bytes metadata: the number of bytes in the entire raw article (including headers and body)

the :lines metadata: the number of lines in the article body

The value of each item is either a string, or None if not present.

It is advisable to use the decode_header() function on header values when they may contain non-ASCII characters:

>>> _, _, first, last, _ = s.group('gmane.comp.python.devel')
>>> resp, overviews = s.over((last, last))
>>> art_num, over = overviews[0]
>>> art_num
117216
>>> list(over.keys())
['xref', 'from', ':lines', ':bytes', 'references', 'date', 'message-id', 'subject']
>>> over['from']
'=?UTF-8?B?Ik1hcnRpbiB2LiBMw7Z3aXMi?= <martin@v.loewis.de>'
>>> nntplib.decode_header(over['from'])
'"Martin v. Löwis" <martin@v.loewis.de>'

Added in version 3.2.

NNTP.help(*, file=None)

Send a HELP command. Return a pair (response, list) where list is a list of help strings.

NNTP.stat(message_spec=None)

Send a STAT command, where message_spec is either a message id (enclosed in '<' and '>') or an article number in the current group. If message_spec is omitted or None, the current article in the current group is considered. Return a triple (response, number, id) where number is the article number and id is the message id.

>>> _, _, first, last, _ = s.group('gmane.comp.python.devel')
>>> resp, number, message_id = s.stat(first)
>>> number, message_id
(9099, '<20030112190404.GE29873@epoch.metaslash.com>')

NNTP.next()

NEXT 命令を送信します。 stat() のような応答を返します。

NNTP.last()

LAST 命令を送信します。 stat() のような応答を返します。

NNTP.article(message_spec=None, *, file=None)

Send an ARTICLE command, where message_spec has the same meaning as for stat(). Return a tuple (response, info) where info is a namedtuple with three attributes number, message_id and lines (in that order). number is the article number in the group (or 0 if the information is not available), message_id the message id as a string, and lines a list of lines (without terminating newlines) comprising the raw message including headers and body.

>>> resp, info = s.article('<20030112190404.GE29873@epoch.metaslash.com>')
>>> info.number
0
>>> info.message_id
'<20030112190404.GE29873@epoch.metaslash.com>'
>>> len(info.lines)
65
>>> info.lines[0]
b'Path: main.gmane.org!not-for-mail'
>>> info.lines[1]
b'From: Neal Norwitz <neal@metaslash.com>'
>>> info.lines[-3:]
[b'There is a patch for 2.3 as well as 2.2.', b'', b'Neal']

NNTP.head(message_spec=None, *, file=None)

Same as article(), but sends a HEAD command. The lines returned (or written to file) will only contain the message headers, not the body.

NNTP.body(message_spec=None, *, file=None)

Same as article(), but sends a BODY command. The lines returned (or written to file) will only contain the message body, not the headers.

NNTP.post(data)

Post an article using the POST command. The data argument is either a file object opened for binary reading, or any iterable of bytes objects (representing raw lines of the article to be posted). It should represent a well-formed news article, including the required headers. The post() method automatically escapes lines beginning with . and appends the termination line.

If the method succeeds, the server's response is returned. If the server refuses posting, a NNTPReplyError is raised.

NNTP.ihave(message_id, data)

Send an IHAVE command. message_id is the id of the message to send to the server (enclosed in '<' and '>'). The data parameter and the return value are the same as for post().

NNTP.date()

Return a pair (response, date). date is a datetime object containing the current date and time of the server.

NNTP.slave()

SLAVE 命令を送信します。サーバの response を返します。

NNTP.set_debuglevel(level)

インスタンスのデバッグレベルを設定します。このメソッドは印字されるデバッグ出力の量を制御します。標準では 0 に設定されていて、 これはデバッグ出力を全く印字しません。 1 はそこそこの量、一般に NNTP 要求や応答あたり 1 行のデバッグ出力を生成します。値が 2 やそれ以上の場合、(メッセージテキストを含めて) NNTP 接続上で送受信された全ての内容を一行ごとにログ出力する、最大限のデバッグ出力を生成します。

The following are optional NNTP extensions defined in RFC 2980 [https://datatracker.ietf.org/doc/html/rfc2980.html]. Some of them have been superseded by newer commands in RFC 3977 [https://datatracker.ietf.org/doc/html/rfc3977.html].

NNTP.xhdr(hdr, str, *, file=None)

Send an XHDR command. The hdr argument is a header keyword, e.g. 'subject'. The str argument should have the form 'first-last' where first and last are the first and last article numbers to search. Return a pair (response, list), where list is a list of pairs (id, text), where id is an article number (as a string) and text is the text of the requested header for that article. If the file parameter is supplied, then the output of the XHDR command is stored in a file. If file is a string, then the method will open a file with that name, write to it then close it. If file is a file object, then it will start calling write() on it to store the lines of the command output. If file is supplied, then the returned list is an empty list.

NNTP.xover(start, end, *, file=None)

Send an XOVER command. start and end are article numbers delimiting the range of articles to select. The return value is the same of for over(). It is recommended to use over() instead, since it will automatically use the newer OVER command if available.

ユーティリティー関数

このモジュールは以下のユーティリティ関数も定義しています:

nntplib.decode_header(header_str)

Decode a header value, un-escaping any escaped non-ASCII characters. header_str must be a str object. The unescaped value is returned. Using this function is recommended to display some headers in a human readable form:

>>> decode_header("Some subject")
'Some subject'
>>> decode_header("=?ISO-8859-15?Q?D=E9buter_en_Python?=")
'Débuter en Python'
>>> decode_header("Re: =?UTF-8?B?cHJvYmzDqG1lIGRlIG1hdHJpY2U=?=")
'Re: problème de matrice'

optparse --- Parser for command line options

ソースコード: Lib/optparse.py [https://github.com/python/cpython/tree/3.12/Lib/optparse.py]

バージョン 3.2 で非推奨: The optparse module is deprecated and will not be developed further; development will continue with the argparse module.

optparse モジュールは、昔からある getopt よりも簡便で、柔軟性に富み、かつ強力なコマンドライン解析ライブラリです。 optparse では、より宣言的なスタイルのコマンドライン解析手法、すなわち OptionParser のインスタンスを作成してオプションを追加してゆき、そのインスタンスでコマンドラインを解析するという手法をとっています。 optparse を使うと、GNU/POSIX 構文でオプションを指定できるだけでなく、使用法やヘルプメッセージの生成も行えます。

optparse を使った簡単なスクリプトの例を以下に示します:

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()

このようにわずかな行数のコードによって、スクリプトのユーザはコマンドライン上で例えば以下のような「よくある使い方」を実行できるようになります:

<yourscript> --file=outfile -q

As it parses the command line, optparse sets attributes of the options object returned by parse_args() based on user-supplied command-line values. When parse_args() returns from parsing this command line, options.filename will be "outfile" and options.verbose will be False. 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:

<yourscript> -f outfile --quiet
<yourscript> --quiet --file outfile
<yourscript> -q -foutfile
<yourscript> -qfoutfile

さらに、ユーザが以下のいずれかを実行すると

<yourscript> -h
<yourscript> --help

optparse はスクリプトのオプションについて簡単にまとめた内容を出力します:

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

yourscript の中身は実行時に決まります (通常は sys.argv[0] になります)。

背景

optparse は、素直で慣習に則ったコマンドラインインターフェースを備えたプログラムの作成を援助する目的で設計されました。その結果、Unix で慣習的に使われているコマンドラインの構文や機能だけをサポートするに留まっています。こうした慣習に詳しくなければ、よく知っておくためにもこの節を読んでおきましょう。

用語集

引数 (argument)

コマンドラインでユーザが入力するテキストの塊で、シェルが execl や execv に引き渡すものです。Python では、引数は sys.argv[1:] の要素となります。(sys.argv[0] は実行しようとしているプログラムの名前です。引数解析に関しては、この要素はあまり重要ではありません。) Unix シェルでは、「語 (word)」という用語も使います。

場合によっては sys.argv[1:] 以外の引数リストを代入する方が望ましいことがあるので、「引数」は「 sys.argv[1:] または sys.argv[1:] の代替として提供される別のリストの要素」と読むべきでしょう。

オプション (option)

追加的な情報を与えるための引数で、プログラムの実行に対する教示やカスタマイズを行います。オプションには多様な文法が存在します。伝統的な Unix における書法はハイフン ("-") の後ろに一文字が続くもので、例えば -x や -F です。また、伝統的な Unix における書法では、複数のオプションを一つの引数にまとめられます。例えば -x -F は -xF と等価です。 GNU プロジェクトでは -- の後ろにハイフンで区切りの語を指定する方法、例えば --file や --dry-run も提供しています。 optparse は、これら二種類のオプション書法だけをサポートしています。

他に見られる他のオプション書法には以下のようなものがあります:

ハイフンの後ろに数個の文字が続くもので、例えば -pf (このオプションは複数のオプションを一つにまとめたものとは 違います)

ハイフンの後ろに語が続くもので、例えば -file (これは技術的には上の書式と同じですが、通常同じプログラム上で一緒に使うことはありません)

プラス記号の後ろに一文字、数個の文字、または語を続けたもので、例えば +f, +rgb

スラッシュ記号の後ろに一文字、数個の文字、または語を続けたもので、例えば /f, /file

上記のオプション書法は optparse ではサポートしておらず、今後もサポートする予定はありません。これは故意によるものです: 最初の三つはどの環境の標準でもなく、最後の一つは Windows や特定のレガシーなプラットフォーム (VMS や MS-DOS など) を対象にしているときにしか意味をなさないからです。

オプション引数 (option argument)

あるオプションの後ろに続く引数で、そのオプションに密接な関連をもち、オプションと同時に引数リストから取り出されます。 optparse では、オプション引数は以下のように別々の引数にできます:

-f foo
--file foo

また、一つの引数中にも入れられます:

-ffoo
--file=foo

通常、オプションは引数をとることもとらないこともあります。あるオプションは引数をとることがなく、またあるオプションは常に引数をとります。多くの人々が「オプションのオプション引数」機能を欲しています。これは、あるオプションが引数が指定されている場合には引数をとり、そうでない場合には引数をもたないようにするという機能です。この機能は引数解析をあいまいにするため、議論の的となっています: 例えば、もし -a がオプション引数をとり、 -b がまったく別のオプションだとしたら、 -ab をどうやって解析すればいいのでしょうか？こうした曖昧さが存在するため、 optparse は今のところこの機能をサポートしていません。

位置引数 (positional argument)

他のオプションが解析される、すなわち他のオプションとその引数が解析されて引数リストから除去された後に引数リストに置かれているものです。

必須のオプション (required option)

コマンドラインで与えなければならないオプションです; 「必須のオプション (required option)」という語は、英語では矛盾した言葉です。 optparse では必須オプションの実装を妨げてはいませんが、とりたてて実装上役立つこともしていません。

例えば、下記のような架空のコマンドラインを考えてみましょう:

prog -v --report report.txt foo bar

-v と --report はどちらもオプションです。--report オプションが引数をとるとすれば、report.txt はオプションの引数です。foo と bar は位置引数になります。

オプションとは何か

オプションはプログラムの実行を調整したり、カスタマイズしたりするための補助的な情報を与えるために使います。もっとはっきりいうと、オプションはあくまでもオプション (省略可能)であるということです。本来、プログラムはともかくもオプションなしでうまく実行できてしかるべきです。(Unix やGNU ツールセットのプログラムをランダムにピックアップしてみてください。オプションを全く指定しなくてもちゃんと動くでしょう？例外は find, tar, dd くらいです---これらの例外は、オプション文法が標準的でなく、インターフェースが混乱を招くと酷評されてきた変種のはみ出しものなのです)

多くの人が自分のプログラムに「必須のオプション」を持たせたいと考えます。しかしよく考えてください。必須なら、それは オプション(省略可能) ではないのです！ プログラムを正しく動作させるのに絶対的に必要な情報があるとすれば、そこには位置引数を割り当てるべきなのです。

良くできたコマンドライン インターフェース設計として、ファイルのコピーに使われる cp ユーティリティのことを考えてみましょう。ファイルのコピーでは、コピー先を指定せずにファイルをコピーするのは無意味な操作ですし、少なくとも一つのコピー元が必要です。従って、cp は引数無しで実行すると失敗します。とはいえ、cp はオプションを全く必要としない柔軟で便利なコマンドライン文法を備えています:

cp SOURCE DEST
cp SOURCE ... DEST-DIR

まだあります。ほとんどの cp の実装では、ファイルモードや変更時刻を変えずにコピーする、シンボリックリンクの追跡を行わない、すでにあるファイルを上書きする前にユーザに尋ねる、など、ファイルをコピーする方法をいじるための一連のオプションを実装しています。しかし、こうしたオプションは、一つのファイルを別の場所にコピーする、または複数のファイルを別のディレクトリにコピーするという、cp の中心的な処理を乱すことはないのです。

位置引数とは何か

位置引数とは、プログラムを動作させる上で絶対的に必要な情報となる引数です。

よいユーザインターフェースとは、絶対に必要だとされるものが可能な限り少ないものです。プログラムを正しく動作させるために 17 個もの別個の情報が必要だとしたら、その 方法 はさして問題にはなりません ---ユーザはプログラムを正しく動作させられないうちに諦め、立ち去ってしまうからです。ユーザインターフェースがコマンドラインでも、設定ファイルでも、GUI やその他の何であっても同じです: 多くの要求をユーザに押し付ければ、ほとんどのユーザはただ音をあげてしまうだけなのです。

要するに、ユーザが絶対に提供しなければならない情報だけに制限する --- そして可能な限りよく練られたデフォルト設定を使うよう試みてください。もちろん、プログラムには適度な柔軟性を持たせたいとも望むはずですが、それこそがオプションの果たす役割です。繰り返しますが、設定ファイルのエントリであろうが、GUI でできた「環境設定」ダイアログ上のウィジェットであろうが、コマンドラインオプションであろうが関係ありません --- より多くのオプションを実装すればプログラムはより柔軟性を持ちますが、実装はより難解になるのです。高すぎる柔軟性はユーザを閉口させ、コードの維持をより難しくするのです。

チュートリアル

optparse はとても柔軟で強力でありながら、ほとんどの場合には簡単に利用できます。この節では、 optparse ベースのプログラムで広く使われているコードパターンについて述べます。

まず、OptionParser クラスを import しておかなければなりません。次に、プログラムの冒頭で OptionParser インスタンスを生成しておきます:

from optparse import OptionParser
...
parser = OptionParser()

これでオプションを定義できるようになりました。基本的な構文は以下の通りです:

parser.add_option(opt_str, ...,
                  attr=value, ...)

各オプションには、 -f や --file のような一つまたは複数のオプション文字列と、パーザがコマンドライン上のオプションを見つけた際に、何を準備し、何を行うべきかを optparse に教えるためのオプション属性 (option attribute)がいくつか入ります。

通常、各オプションには短いオプション文字列と長いオプション文字列があります。例えば:

parser.add_option("-f", "--file", ...)

オプション文字列は、(ゼロ文字の場合も含め)いくらでも短く、またいくらでも長くできます。ただしオプション文字列は少なくとも一つなければなりません。

OptionParser.add_option() に渡されたオプション文字列は、実際にはこの関数で定義したオプションに対するラベルになります。簡単のため、以後ではコマンドライン上で オプションを見つける という表現をしばしば使いますが、これは実際には optparse がコマンドライン上の オプション文字列 を見つけ、対応づけされているオプションを探し出す、という処理に相当します。

オプションを全て定義したら、 optparse にコマンドラインを解析するように指示します:

(options, args) = parser.parse_args()

(If you like, you can pass a custom argument list to parse_args(), but that's rarely necessary: by default it uses sys.argv[1:].)

parse_args() returns two values:

全てのオプションに対する値の入ったオブジェクト options --- 例えば、--file が単一の文字列引数をとる場合、options.file はユーザが指定したファイル名になります。オプションを指定しなかった場合には None になります

オプションの解析後に残った位置引数からなるリスト args

このチュートリアルの節では、最も重要な四つのオプション属性: action, type, dest (destination), help についてしか触れません。このうち最も重要なのは action です。

オプション・アクションを理解する

アクション(action)は optparse がコマンドライン上にあるオプションを見つけたときに何をすべきかを指示します。 optparse には押し着せのアクションのセットがハードコードされています。新たなアクションの追加は上級者向けの話題であり、 optparse の拡張 で触れます。ほとんどのアクションは、値を何らかの変数に記憶するよう optparse に指示します --- 例えば、文字列をコマンドラインから取り出して、 options の属性の中に入れる、といった具合にです。

オプション・アクションを指定しない場合、 optparse のデフォルトの動作は store になります。

store アクション

もっとも良く使われるアクションは store です。このアクションは次の引数 (あるいは現在の引数の残りの部分) を取り出し、正しい型の値か確かめ、指定した保存先に保存するよう optparse に指示します。

例えば:

parser.add_option("-f", "--file",
                  action="store", type="string", dest="filename")

例えば、以下のように指定しておき、偽のコマンドラインを作成して optparse に解析させてみましょう:

args = ["-f", "foo.txt"]
(options, args) = parser.parse_args(args)

When optparse sees the option string -f, it consumes the next argument, foo.txt, and stores it in options.filename. So, after this call to parse_args(), options.filename is "foo.txt".

オプションの型として、 optparse は他にも int や float をサポートしています:

parser.add_option("-n", type="int", dest="num")

このオプションには長い形式のオプション文字列がないため、設定に問題がないということに注意してください。また、デフォルトのアクションは store なので、ここでは action を明示的に指定していません。

架空のコマンドラインをもう一つ解析してみましょう。今度は、オプション引数をオプションの右側にぴったりくっつけて一緒くたにします: -n42 (一つの引数のみ) は -n 42 (二つの引数からなる) と等価になるので

(options, args) = parser.parse_args(["-n42"])
print(options.num)

は 42 を出力します。

型を指定しない場合、 optparse は引数を string であると仮定します。デフォルトのアクションが store であることも併せて考えると、最初の例はもっと短くなります:

parser.add_option("-f", "--file", dest="filename")

保存先 (destination) を指定しない場合、 optparse はデフォルト値としてオプション文字列から気のきいた名前を設定します: 最初に指定した長い形式のオプション文字列が --foo-bar であれば、デフォルトの保存先は foo_bar になります。長い形式のオプション文字列がなければ、 optparse は最初に指定した短い形式のオプション文字列を探します: 例えば、 -f に対する保存先は f になります。

optparse にはビルトインの complex 型も含まれています。型の追加については optparse の拡張 で触れています。

ブール値 (フラグ) オプションの処理

フラグオプション---特定のオプションに対して真または偽の値の値を設定するオプション--- はよく使われます。 optparse では、二つのアクション、 store_true および store_false をサポートしています。例えば、 verbose というフラグを -v で有効にして、 -q で無効にしたいとします:

parser.add_option("-v", action="store_true", dest="verbose")
parser.add_option("-q", action="store_false", dest="verbose")

ここでは二つのオプションに同じ保存先を指定していますが、全く問題ありません。(下記のように、デフォルト値の設定を少し注意深く行わなければならないだけです。)

-v をコマンドライン上に見つけると、 optparse は options.verbose を True に設定します。 -q を見つければ、 options.verbose は False にセットされます。

その他のアクション

この他にも、 optparse は以下のようなアクションをサポートしています:

"store_const"

store a constant value, pre-set via Option.const

"append"

オプションの引数を指定のリストに追加します

"count"

指定のカウンタを 1 増やします

"callback"

指定の関数を呼び出します

これらのアクションについては、 リファレンスガイド 節および オプション処理コールバック 節で触れます。

デフォルト値

上記の例は全て、何らかのコマンドラインオプションが見つかった時に何らかの変数 (保存先: destination) に値を設定していました。では、該当するオプションが見つからなかった場合には何が起きるのでしょうか？デフォルトは全く与えていないため、これらの値は全て None になります。たいていはこれで十分ですが、もっときちんと制御したい場合もあります。 optparse では各保存先に対してデフォルト値を指定し、コマンドラインの解析前にデフォルト値が設定されるようにできます。

まず、 verbose/quiet の例について考えてみましょう。 optparse に対して、 -q がない限り verbose を True に設定させたいなら、以下のようにします:

parser.add_option("-v", action="store_true", dest="verbose", default=True)
parser.add_option("-q", action="store_false", dest="verbose")

デフォルトの値は特定のオプションではなく 保存先 に対して適用されます。また、これら二つのオプションはたまたま同じ保存先を持っているにすぎないため、上のコードは下のコードと全く等価になります:

parser.add_option("-v", action="store_true", dest="verbose")
parser.add_option("-q", action="store_false", dest="verbose", default=True)

下のような場合を考えてみましょう:

parser.add_option("-v", action="store_true", dest="verbose", default=False)
parser.add_option("-q", action="store_false", dest="verbose", default=True)

やはり verbose のデフォルト値は True になります; 特定の目的変数に対するデフォルト値として有効なのは、最後に指定した値だからです。

A clearer way to specify default values is the set_defaults() method of OptionParser, which you can call at any time before calling parse_args():

parser.set_defaults(verbose=True)
parser.add_option(...)
(options, args) = parser.parse_args()

前の例と同様、あるオプションの値の保存先に対するデフォルトの値は最後に指定した値になります。コードを読みやすくするため、デフォルト値を設定するときには両方のやり方を混ぜるのではなく、片方だけを使うようにしましょう。

ヘルプの生成

optparse にはヘルプと使い方の説明 (usage text) を生成する機能があり、ユーザに優しいコマンドライン インターフェースを作成する上で役立ちます。やらなければならないのは、各オプションに対する help の値と、必要ならプログラム全体の使用法を説明する短いメッセージを与えることだけです。ユーザフレンドリな (ドキュメント付きの) オプションを追加した OptionParser を以下に示します:

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]")

optparse がコマンドライン上で -h や --help を見つけた場合や、 parser.print_help() を呼び出した場合、この OptionParser は以下のようなメッセージを標準出力に出力します:

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]

(help オプションでヘルプを出力した場合、 optparse は出力後にプログラムを終了します。)

optparse ができるだけうまくメッセージを生成するよう手助けするには、他にもまだまだやるべきことがあります:

スクリプト自体の利用法を表すメッセージを定義します:

usage = "usage: %prog [options] arg1 arg2"

optparse は %prog を現在のプログラム名、すなわち os.path.basename(sys.argv[0]) と置き換えます。この文字列は詳細なオプションヘルプの前に展開され出力されます。

usage の文字列を指定しない場合、 optparse は型どおりとはいえ気の利いたデフォルト値、 "Usage: %prog [options]" を使います。位置引数をとらないスクリプトの場合はこれで十分でしょう。

全てのオプションにヘルプ文字列を定義します。行の折り返しは気にしなくてかまいません ---optparse は行の折り返しに気を配り、見栄えのよいヘルプ出力を生成します。

オプションが値をとるということは自動的に生成されるヘルプメッセージの中で分かります。例えば、"mode" option の場合にはこのようになります:

-m MODE, --mode=MODE

ここで "MODE" はメタ変数 (meta-variable) と呼ばれます: メタ変数は、ユーザが -m/--mode に対して指定するはずの引数を表します。デフォルトでは、 optparse は保存先の変数名を大文字だけにしたものをメタ変数に使います。これは時として期待通りの結果になりません --- 例えば、上の例の --filename オプションでは明示的に metavar="FILE" を設定しており、その結果自動生成されたオプション説明テキストは:

-f FILE, --filename=FILE

この機能の重要さは、単に表示スペースを節約するといった理由にとどまりません: 上の例では、手作業で書いたヘルプテキストの中でメタ変数として FILE を使っています。その結果、ユーザに対してやや堅苦しい表現の書法 -f FILE と、より平易に意味付けを説明した "write output to FILE" との間に対応があるというヒントを与えています。これは、エンドユーザにとってより明解で便利なヘルプテキストを作成する単純でありながら効果的な手法なのです。

デフォルト値を持つオプションはヘルプ文字列に %default を含むことができます---optparse はそれをオプションのデフォルト値に str() を適用したもので置き換えます。オプションがデフォルト値を持たない (もしくはデフォルト値が None である) 場合、 %default は none に展開されます。

オプションをグループ化する

たくさんのオプションを扱う場合、オプションをグループ分けするとヘルプ出力が見やすくなります。 OptionParser は、複数のオプションをまとめたオプショングループを複数持つことができます。

オプションのグループは、 OptionGroup を使って作成します:

class optparse.OptionGroup(parser, title, description=None)

ここでは:

parser は、このグループが属する OptionParser のインスタンスです

title はグループのタイトルです

description はオプションで、グループの長い説明です

OptionGroup は (OptionParser のように) OptionContainer を継承していて、オプションをグループに追加するために add_option() メソッドを利用できます。

全てのオプションを定義したら、 OptionParser の add_option_group() メソッドを使ってグループを定義済みのパーサーに追加します。

前のセクションで定義したパーサーに、続けて OptionGroup を追加します:

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)

この結果のヘルプ出力は次のようになります:

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.

さらにサンプルを拡張して、複数のグループを使うようにしてみます:

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)

出力結果は次のようになります:

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

もう1つの、特にオプショングループをプログラムから操作するときに利用できるメソッドがあります:

OptionParser.get_option_group(opt_str)

短いオプション文字列もしくは長いオプション文字列 opt_str (例。 '-o' 、 '--option') が属する OptionGroup を返します。そのような OptionGroup が無い場合は、 None を返します。

バージョン番号の出力

optparse では、使用法メッセージと同様にプログラムのバージョン文字列を出力できます。 OptionParser の version 引数に文字列を渡します:

parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")

%prog は usage と同じような展開を受けます。その他にも version には何でも好きな内容を入れられます。 version を指定した場合、 optparse は自動的に --version オプションをパーザに渡します。コマンドライン中に --version が見つかると、 optparse は version 文字列を展開して (%prog を置き換えて) 標準出力に出力し、プログラムを終了します。

例えば、/usr/bin/foo という名前のスクリプトなら:

$ /usr/bin/foo --version
foo 1.0

以下の2つのメソッドを、version 文字列を表示するために利用できます:

OptionParser.print_version(file=None)

現在のプログラムのバージョン (self.version) を file (デフォルト: stdout) へ表示します。 print_usage() と同じく、 self.version の中の全ての %prog が現在のプログラム名に置き換えられます。 self.version が空文字列だだったり未定義だったときは何もしません。

OptionParser.get_version()

print_version() と同じですが、バージョン文字列を表示する代わりに返します。

optparse のエラー処理法

optparse を使う場合に気を付けなければならないエラーには、大きく分けてプログラマ側のエラーとユーザ側のエラーという二つの種類があります。プログラマ側のエラーの多くは、例えば不正なオプション文字列や定義されていないオプション属性の指定、あるいはオプション属性を指定し忘れるといった、誤った OptionParser.add_option(), 呼び出しによるものです。こうした誤りは通常通りに処理されます。すなわち、例外(optparse.OptionError や TypeError) を送出して、プログラムをクラッシュさせます。

もっと重要なのはユーザ側のエラーの処理です。というのも、ユーザの操作エラーというものはコードの安定性に関係なく起こるからです。 optparse は、誤ったオプション引数の指定 (整数を引数にとるオプション -n に対して -n 4x と指定してしまうなど) や、引数を指定し忘れた場合 (-n が何らかの引数をとるオプションであるのに、 -n が引数の末尾に来ている場合) といった、ユーザによるエラーを自動的に検出します。また、アプリケーション側で定義されたエラー条件が起きた場合、 OptionParser.error() を呼び出してエラーを通知できます:

(options, args) = parser.parse_args()
...
if options.a and options.b:
    parser.error("options -a and -b are mutually exclusive")

いずれの場合にも optparse はエラーを同じやり方で処理します。すなわち、プログラムの使用法メッセージとエラーメッセージを標準エラー出力に出力して、終了ステータス 2 でプログラムを終了させます。

上に挙げた最初の例、すなわち整数を引数にとるオプションにユーザが 4x を指定した場合を考えてみましょう:

$ /usr/bin/foo -n 4x
Usage: foo [options]

foo: error: option -n: invalid integer value: '4x'

値を全く指定しない場合には、以下のようになります:

$ /usr/bin/foo -n
Usage: foo [options]

foo: error: -n option requires an argument

optparse は、常にエラーを引き起こしたオプションについて説明の入ったエラーメッセージを生成するよう気を配ります; 従って、 OptionParser.error() をアプリケーションコードから呼び出す場合にも、同じようなメッセージになるようにしてください。

optparse のデフォルトのエラー処理動作が気に入らないのなら、 OptionParser をサブクラス化して、 exit() かつ/または error() をオーバライドする必要があります。

全てをつなぎ合わせる

optparse を使ったスクリプトは、通常以下のようになります:

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()

リファレンスガイド

parserを作る

optparse を使う最初の一歩は OptionParser インスタンスを作ることです。

class optparse.OptionParser(...)

OptionParser のコンストラクタの引数はどれも必須ではありませんが、いくつものキーワード引数がオプションとして使えます。これらはキーワード引数として渡さなければなりません。すなわち、引数が宣言されている順番に頼ってはいけません。

usage (デフォルト: "%prog [options]")

The usage summary to print when your program is run incorrectly or with a help option. When optparse prints the usage string, it expands %prog to os.path.basename(sys.argv[0]) (or to prog if you passed that keyword argument). To suppress a usage message, pass the special value optparse.SUPPRESS_USAGE.

option_list (デフォルト: [])

パーザに追加する Option オブジェクトのリストです。 option_list の中のオプションは standard_option_list (OptionParser のサブクラスでセットされる可能性のあるクラス属性) の後に追加されますが、バージョンやヘルプのオプションよりは前になります。このオプションの使用は推奨されません。パーザを作成した後で、 add_option() を使って追加してください。

option_class (デフォルト: optparse.Option)

add_option() でパーザにオプションを追加するときに使用されるクラス。

version (デフォルト: None)

ユーザがバージョンオプションを与えたときに表示されるバージョン文字列です。 version に真の値を与えると、 optparse は自動的に単独のオプション文字列 --version とともにバージョンオプションを追加します。部分文字列 %prog は usage と同様に展開されます。

conflict_handler (デフォルト: "error")

オプション文字列が衝突するようなオプションがパーザに追加されたときにどうするかを指定します。 オプション間の衝突 節を参照して下さい。

description (デフォルト: None)

プログラムの概要を表す一段落のテキストです。 optparse はユーザがヘルプを要求したときにこの概要を現在のターミナルの幅に合わせて整形し直して表示します (usage の後、オプションリストの前に表示されます)。

formatter (デフォルト: 新しい IndentedHelpFormatter)

ヘルプテキストを表示する際に使われる optparse.HelpFormatter のインスタンスです。 optparse はこの目的のためにすぐ使えるクラスを二つ提供しています。 IndentedHelpFormatter と TitledHelpFormatter がそれです。

add_help_option (デフォルト: True)

もし真ならば、 optparse はパーザにヘルプオプションを (オプション文字列 -h と --help とともに)追加します。

prog

usage や version の中の %prog を展開するときに os.path.basename(sys.argv[0]) の代わりに使われる文字列です。

epilog (デフォルト: None)

オプションのヘルプの後に表示されるヘルプテキスト.

パーザへのオプション追加

パーザにオプションを加えていくにはいくつか方法があります。推奨するのは チュートリアル 節で示したような OptionParser.add_option() を使う方法です。 add_option() は以下の二つのうちいずれかの方法で呼び出せます:

(make_option() などが返す) Option インスタンスを渡します

make_option() に (すなわち Option のコンストラクタに) 位置引数とキーワード引数の組み合わせを渡して、 Option インスタンスを生成させます

もう一つの方法は、あらかじめ作成しておいた Option インスタンスからなるリストを、以下のようにして OptionParser のコンストラクタに渡すというものです:

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)

(make_option() は Option インスタンスを生成するファクトリ関数です; 現在のところ、この関数は Option のコンストラクタの別名にすぎません。 optparse の将来のバージョンでは、 Option を複数のクラスに分割し、 make_option() は適切なクラスを選んでインスタンスを生成するようになる予定です。従って、 Option を直接インスタンス化しないでください。)

オプションの定義

各々の Option インスタンス、は -f や --file といった同義のコマンドラインオプションからなる集合を表現しています。一つの Option には任意の数のオプションを短い形式でも長い形式でも指定できます。ただし、少なくとも一つは指定しなければなりません。

正しい方法で Option インスタンスを生成するには、 OptionParser の add_option() を使います。

OptionParser.add_option(option)

OptionParser.add_option(*opt_str, attr=value, ...)

短い形式のオプション文字列を一つだけ持つようなオプションを生成するには次のようにします:

parser.add_option("-f", attr=value, ...)

また、長い形式のオプション文字列を一つだけ持つようなオプションの定義は次のようになります:

parser.add_option("--foo", attr=value, ...)

キーワード引数は新しい Option オブジェクトの属性を定義します。オプションの属性のうちでもっとも重要なのは action です。この属性は、他のどの属性と関連があるか、そしてどの属性が必要かに大きく作用します。関係のないオプション属性を指定したり、必要な属性を指定し忘れたりすると、 optparse は誤りを解説した OptionError 例外を送出します。

コマンドライン上にあるオプションが見つかったときの optparse の振舞いを決定しているのは アクション(action) です。 optparse でハードコードされている標準的なアクションには以下のようなものがあります:

"store"

オプションの引数を保存します (デフォルトの動作です)

"store_const"

store a constant value, pre-set via Option.const

"store_true"

store True

"store_false"

store False

"append"

オプションの引数を指定のリストに追加します

"append_const"

append a constant value to a list, pre-set via Option.const

"count"

指定のカウンタを 1 増やします

"callback"

指定の関数を呼び出します

"help"

全てのオプションとそのドキュメントの入った使用法メッセージを出力します

(アクションを指定しない場合、デフォルトは "store" になります。このアクションでは、 type および dest オプション属性を指定できます。 標準的なオプション・アクション を参照してください。)

As you can see, most actions involve storing or updating a value somewhere. optparse always creates a special object for this, conventionally called options, which is an instance of optparse.Values.

class optparse.Values

An object holding parsed argument names and values as attributes. Normally created by calling when calling OptionParser.parse_args(), and can be overridden by a custom subclass passed to the values argument of OptionParser.parse_args() (as described in 引数を解析する).

Option arguments (and various other values) are stored as attributes of this object, according to the dest (destination) option attribute.

例えばこれを呼び出した場合

parser.parse_args()

optparse はまず options オブジェクトを生成します:

options = Values()

パーザ中で以下のようなオプションが定義されていて

parser.add_option("-f", "--file", action="store", type="string", dest="filename")

パーズしたコマンドラインに以下のいずれかが入っていた場合:

-ffoo
-f foo
--file=foo
--file foo

optparse はこのオプションを見つけて、以下と同等の処理を行います

options.filename = "foo"

type および dest オプション属性は action と同じくらい重要ですが、 全ての オプションで意味をなすのは action だけなのです。

オプション属性

class optparse.Option

A single command line argument, with various attributes passed by keyword to the constructor. Normally created with OptionParser.add_option() rather than directly, and can be overridden by a custom class via the option_class argument to OptionParser.

以下のオプション属性は OptionParser.add_option() へのキーワード引数として渡すことができます。特定のオプションに無関係なオプション属性を渡した場合、または必須のオプションを渡しそこなった場合、 optparse は OptionError を送出します。

Option.action

(デフォルト: "store")

このオプションがコマンドラインにあった場合に optparse に何をさせるかを決めます。取りうるオプションについては こちら を参照してください。

Option.type

(デフォルト: "string")

このオプションに与えられる引数の型 (たとえば "string" や "int") です。取りうるオプションについては こちら を参照してください。

Option.dest

(デフォルト: オプション文字列を使う)

このオプションのアクションがある値をどこかに書いたり書き換えたりを意味する場合、これは optparse にその書く場所を教えます。詳しく言えば dest には optparse がコマンドラインを解析しながら組み立てる options オブジェクトの属性の名前を指定します。

Option.default

コマンドラインに指定がなかったときにこのオプションの対象に使われる値です。 OptionParser.set_defaults() も参照してください。

Option.nargs

(デフォルト: 1)

このオプションがあったときに幾つの type 型の引数が消費されるべきかを指定します。 1 より大きい場合、 optparse は dest に値のタプルを格納します。

Option.const

定数を格納する動作のための、その定数です。

Option.choices

"choice" 型オプションに対してユーザが選べる選択肢となる文字列のリストです。

Option.callback

アクションが "callback" であるオプションに対し、このオプションがあったときに呼ばれる呼び出し可能オブジェクトです。呼び出し時に渡される引数の詳細については、 オプション処理コールバック を参照してください。

Option.callback_args

Option.callback_kwargs

callback に渡される標準的な4つのコールバック引数の後ろに追加する、位置引数とキーワード引数。

Option.help

Help text to print for this option when listing all available options after the user supplies a help option (such as --help). If no help text is supplied, the option will be listed without help text. To hide this option, use the special value optparse.SUPPRESS_HELP.

Option.metavar

(デフォルト: オプション文字列を使う)

説明文を表示する際にオプションの引数の身代わりになるものです。例は チュートリアル 節を参照してください。

標準的なオプション・アクション

様々なオプション・アクションにはどれも互いに少しづつ異なった条件と作用があります。ほとんどのアクションに関連するオプション属性がいくつかあり、値を指定して optparse の挙動を操作できます。いくつかのアクションには必須の属性があり、必ず値を指定しなければなりません。

"store" [関連: type, dest, nargs, choices]

オプションの後には必ず引数が続きます。引数は type に従って値に変換されて dest に保存されます。 nargs > 1 の場合、複数の引数をコマンドラインから取り出します。引数は全て type に従って変換され、 dest にタプルとして保存されます。 標準のオプション型 節を参照してください。

choices を(文字列のリストかタプルで) 指定した場合、型のデフォルト値は "choice" になります。

type を指定しない場合、デフォルトの値は "string" です。

dest を指定しない場合、 optparse は保存先を最初の長い形式のオプション文字列から導出します (例えば、 --foo-bar は foo_bar になります)。長い形式のオプション文字列がない場合、 optparse は最初の短い形式のオプションから保存先の変数名を導出します (-f は f になります)。

以下はプログラム例です:

parser.add_option("-f")
parser.add_option("-p", type="float", nargs=3, dest="point")

とすると、以下のようなコマンドライン

-f foo.txt -p 1 -3.5 4 -fbar.txt

を解析した場合、 optparse は以下のように設定を行います

options.f = "foo.txt"
options.point = (1.0, -3.5, 4.0)
options.f = "bar.txt"

"store_const" [関連: const; 関連: dest]

値 const を dest に保存します。

以下はプログラム例です:

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")

とします。 --noisy が見つかると、 optparse は

options.verbose = 2

"store_true" [関連: dest]

A special case of "store_const" that stores True to dest.

"store_false" [関連: dest]

Like "store_true", but stores False.

以下はプログラム例です:

parser.add_option("--clobber", action="store_true", dest="clobber")
parser.add_option("--no-clobber", action="store_false", dest="clobber")

"append" [関連: type, dest, nargs, choices]

このオプションの後ろには必ず引数が続きます。引数は dest のリストに追加されます。 dest のデフォルト値を指定しなかった場合、 optparse がこのオプションを最初にみつけた時点で空のリストを自動的に生成します。 nargs > 1 の場合、複数の引数をコマンドラインから取り出し、長さ nargs のタプルを生成して dest に追加します。

type および dest のデフォルト値は "store" アクションと同じです。

以下はプログラム例です:

parser.add_option("-t", "--tracks", action="append", type="int")

-t3 がコマンドライン上で見つかると、 optparse は:

options.tracks = []
options.tracks.append(int("3"))

その後、--tracks=4 が見つかると以下を実行します:

options.tracks.append(int("4"))

append アクションは、オプションの現在の値の append メソッドを呼び出します。これは、どのデフォルト値も append メソッドを持っていなければならないことを意味します。また、デフォルト値が空でない場合、オプションの解析結果は、そのデフォルトの要素の後ろにコマンドラインからの値が追加されたものになる、ということも意味します:

>>> parser.add_option("--files", action="append", default=['~/.mypkg/defaults'])
>>> opts, args = parser.parse_args(['--files', 'overrides.mypkg'])
>>> opts.files
['~/.mypkg/defaults', 'overrides.mypkg']

"append_const" [関連: const; 関連: dest]

"store_const" と同様ですが、 const の値は dest に追加(append)されます。 "append" の場合と同じように dest のデフォルトは None ですがこのオプションを最初にみつけた時点で空のリストを自動的に生成します。

"count" [関連: dest]

dest に保存されている整数値をインクリメントします。 dest は (デフォルトの値を指定しない限り) 最初にインクリメントを行う前にゼロに設定されます。

以下はプログラム例です:

parser.add_option("-v", action="count", dest="verbosity")

コマンドライン上で最初に -v が見つかると、 optparse は:

options.verbosity = 0
options.verbosity += 1

以後、-v が見つかるたびに

options.verbosity += 1

"callback" [必須: callback; 関連: type, nargs, callback_args, callback_kwargs]

callback に指定された関数を次のように呼び出します

func(option, opt_str, value, parser, *args, **kwargs)

詳細は、 オプション処理コールバック 節を参照してください。

"help"

現在のオプションパーザ内の全てのオプションに対する完全なヘルプメッセージを出力します。ヘルプメッセージは OptionParser のコンストラクタに渡した usage 文字列と、各オプションに渡した help 文字列から生成します。

If no 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 optparse.SUPPRESS_HELP.

optparse は全ての OptionParser に自動的に help オプションを追加するので、通常自分で生成する必要はありません。

以下はプログラム例です:

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)

optparse がコマンドライン上に -h または --help を見つけると、以下のようなヘルプメッセージを標準出力に出力します (sys.argv[0] は "foo.py" だとします):

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

ヘルプメッセージの出力後、 optparse は sys.exit(0) でプロセスを終了します。

"version"

OptionParser に指定されているバージョン番号を標準出力に出力して終了します。バージョン番号は、実際には OptionParser の print_version() メソッドで書式化されてから出力されます。通常、 OptionParser のコンストラクタに version 引数が指定されたときのみ関係のあるアクションです。 help オプションと同様、 optparse はこのオプションを必要に応じて自動的に追加するので、 version オプションを作成することはほとんどないでしょう。

標準のオプション型

optparse には、 "string", "int", "choice", "float", "complex" の 5 種類のビルトインのオプション型があります。 新たなオプションの型を追加したければ、 optparse の拡張 節を参照してください。

文字列オプションの引数はチェックや変換を一切受けません: コマンドライン上のテキストは保存先にそのまま保存されます (またはコールバックに渡されます)。

整数引数 ("int" 型) は次のように解析されます:

数が 0x から始まるならば、16進数として読み取られます

数が 0 から始まるならば、8進数として読み取られます

数が 0b から始まるならば、2進数として読み取られます

それ以外の場合、数は10進数として読み取られます

変換は適切な底 (2, 8, 10, 16 のどれか) とともに int() を呼び出すことで行なわれます。この変換が失敗した場合 optparse の処理も失敗に終わりますが、 より役に立つエラーメッセージを出力します。

"float" および "complex" のオプション引数は直接 float() や complex() で変換されます。エラーは同様の扱いです。

"choice" オプションは "string" オプションのサブタイプです。 choices オプションの属性 (文字列からなるシーケンス) には、利用できるオプション引数のセットを指定します。 optparse.check_choice() はユーザの指定したオプション引数とマスタリストを比較して、無効な文字列が指定された場合には OptionValueError を送出します。

引数を解析する

The whole point of creating and populating an OptionParser is to call its parse_args() method.

OptionParser.parse_args(args=None, values=None)

Parse the command-line options found in args.

The input parameters are

args

処理する引数のリスト (デフォルト: sys.argv[1:])

values

an Values object to store option arguments in (default: a new instance of Values) -- if you give an existing object, the option defaults will not be initialized on it

and the return value is a pair (options, args) where

options

the same object that was passed in as values, or the optparse.Values instance created by optparse

args

全てのオプションの処理が終わった後で残った位置引数

The most common usage is to supply neither keyword argument. If you supply values, it will be modified with repeated setattr() calls (roughly one for every option argument stored to an option destination) and returned by parse_args().

If parse_args() encounters any errors in the argument list, it calls the OptionParser's 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).

オプション解析器への問い合わせと操作

オプションパーザのデフォルトの振る舞いは、ある程度カスタマイズすることができます。また、オプションパーザの中を調べることもできます。OptionParser は幾つかのヘルパーメソッドを提供しています:

OptionParser.disable_interspersed_args()

オプションで無い最初の引数を見つけた時点でパースを止めるように設定します。例えば、 -a と -b が両方とも引数を取らないシンプルなオプションだったとすると、 optparse は通常次の構文を受け付け:

prog -a arg1 -b arg2

それを次と同じように扱います

prog -a -b arg1 arg2

この機能を無効にしたいときは、 disable_interspersed_args() メソッドを呼び出してください。古典的な Unix システムのように、最初のオプションでない引数を見つけたときにオプションの解析を止めるようになります。

別のコマンドを実行するコマンドをプロセッサを作成する際、別のコマンドのオプションと自身のオプションが混ざるのを防ぐために利用することができます。例えば、各コマンドがそれぞれ異なるオプションのセットを持つ場合などに有効です。

OptionParser.enable_interspersed_args()

オプションで無い最初の引数を見つけてもパースを止めないように設定します。オプションとコマンド引数の順序が混ざっても良いようになります。これはデフォルトの動作です。

OptionParser.get_option(opt_str)

オプション文字列 opt_str に対する Option インスタンスを返します。該当するオプションがなければ None を返します。

OptionParser.has_option(opt_str)

OptionParser に(-q や --verbose のような) オプション opt_str がある場合、True を返します。

OptionParser.remove_option(opt_str)

OptionParser に opt_str に対応するオプションがある場合、そのオプションを削除します。該当するオプションに他のオプション文字列が指定されていた場合、それらのオプション文字列は全て無効になります。 opt_str がこの OptionParser オブジェクトのどのオプションにも属さない場合、 ValueError を送出します。

オプション間の衝突

注意が足りないと、衝突するオプションを定義してしまうことがあります:

parser.add_option("-n", "--dry-run", ...)
...
parser.add_option("-n", "--noisy", ...)

(とりわけ、OptionParser から標準的なオプションを備えた自前のサブクラスを定義してしまった場合にはよく起きます。)

ユーザがオプションを追加するたびに、 optparse は既存のオプションとの衝突がないかチェックします。何らかの衝突が見付かると、現在設定されている衝突処理メカニズムを呼び出します。衝突処理メカニズムはコンストラクタ中で呼び出せます:

parser = OptionParser(..., conflict_handler=handler)

個別にも呼び出せます:

parser.set_conflict_handler(handler)

衝突時の処理をおこなうハンドラ(handler)には、以下のものが利用できます:

"error" (デフォルト)

オプション間の衝突をプログラム上のエラーとみなし、 OptionConflictError を送出します

"resolve"

オプション間の衝突をインテリジェントに解決します (下記参照)

一例として、衝突をインテリジェントに解決する OptionParser を定義し、衝突を起こすようなオプションを追加してみましょう:

parser = OptionParser(conflict_handler="resolve")
parser.add_option("-n", "--dry-run", ..., help="do no harm")
parser.add_option("-n", "--noisy", ..., help="be noisy")

この時点で、 optparse はすでに追加済のオプションがオプション文字列 -n を使っていることを検出します。 conflict_handler が "resolve" なので、 optparse は既に追加済のオプションリストの方から -n を除去して問題を解決します。従って、 -n の除去されたオプションは --dry-run だけでしか有効にできなくなります。ユーザがヘルプ文字列を要求した場合、問題解決の結果を反映したメッセージが出力されます:

Options:
  --dry-run     do no harm
  ...
  -n, --noisy   be noisy

これまでに追加したオプション文字列を跡形もなく削り去り、ユーザがそのオプションをコマンドラインから起動する手段をなくせます。この場合、 optparse はオプションを完全に除去してしまうので、こうしたオプションはヘルプテキストやその他のどこにも表示されなくなります。例えば、現在の OptionParser の場合、以下の操作:

parser.add_option("--dry-run", ..., help="new dry-run option")

を行った時点で、最初の -n/--dry-run オプションはもはやアクセスできなくなります。このため、 optparse はオプションを消去してしまい、ヘルプテキストだけが残ります:

Options:
  ...
  -n, --noisy   be noisy
  --dry-run     new dry-run option

クリーンアップ

OptionParser インスタンスはいくつかの循環参照を抱えています。このことは Python のガーベジコレクタにとって問題になるわけではありませんが、使い終わった OptionParser に対して destroy() を呼び出すことでこの循環参照を意図的に断ち切るという方法を選ぶこともできます。この方法は特に長時間実行するアプリケーションで OptionParser から大きなオブジェクトグラフが到達可能になっているような場合に有用です。

その他のメソッド

OptionParser にはその他にも幾つかの公開されたメソッドがあります:

OptionParser.set_usage(usage)

Set the usage string according to the rules described above for the usage constructor keyword argument. Passing None sets the default usage string; use optparse.SUPPRESS_USAGE to suppress a usage message.

OptionParser.print_usage(file=None)

現在のプログラムの使用法メッセージ (self.usage) を file (デフォルト: stdout) に表示します。self.usage 内にある全ての %prog という文字列は現在のプログラム名に置換されます。self.usage が空もしくは未定義の時は何もしません。

OptionParser.get_usage()

print_usage() と同じですが、使用法メッセージを表示する代わりに文字列として返します。

OptionParser.set_defaults(dest=value, ...)

幾つかの保存先に対してデフォルト値をまとめてセットします。 set_defaults() を使うのは複数のオプションにデフォルト値をセットする好ましいやり方です。複数のオプションが同じ保存先を共有することがあり得るからです。たとえば幾つかの "mode" オプションが全て同じ保存先をセットするものだったとすると、どのオプションもデフォルトをセットすることができ、しかし最後に指定したものだけが有効になります:

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

こうした混乱を避けるために set_defaults() を使います:

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")

オプション処理コールバック

optparse の組み込みのアクションや型が望みにかなったものでない場合、二つの選択肢があります: 一つは optparse の拡張、もう一つは callback オプションの定義です。 optparse の拡張は汎用性に富んでいますが、単純なケースに対していささか大げさでもあります。大体は簡単なコールバックで事足りるでしょう。

callback オプションの定義は二つのステップからなります:

"callback" アクションを使ってオプション自体を定義する

コールバックを書く。コールバックは少なくとも後で説明する 4 つの引数をとる関数 (またはメソッド) でなければなりません

callbackオプションの定義

callback オプションを最も簡単に定義するには、 OptionParser.add_option() メソッドを使います。 action の他に指定しなければならない属性は callback すなわちコールバックする関数自体です:

parser.add_option("-c", action="callback", callback=my_callback)

callback は関数 (または呼び出し可能オブジェクト)なので、callback オプションを定義する時にはあらかじめ my_callback() を定義しておかなければなりません。この単純なケースでは、 optparse は -c が何らかの引数をとるかどうか判別できず、通常は -c が引数を伴わないことを意味します --- 知りたいことはただ単に -c がコマンドライン上に現れたどうかだけです。とはいえ、場合によっては、自分のコールバック関数に任意の個数のコマンドライン引数を消費させたいこともあるでしょう。これがコールバック関数をトリッキーなものにしています; これについてはこの節の後の方で説明します。

optparse は常に四つの引数をコールバックに渡し、その他には callback_args および callback_kwargs で指定した追加引数しか渡しません。従って、最小のコールバック関数シグネチャは:

def my_callback(option, opt, value, parser):

コールバックの四つの引数については後で説明します。

callback オプションを定義する場合には、他にもいくつかオプション属性を指定できます:

type

他で使われているのと同じ意味です: "store" や "append" アクションの時と同じく、この属性は optparse に引数を一つ消費して type で指定した型に変換させます。 optparse は変換後の値をどこかに保存する代わりにコールバック関数に渡します。

nargs

これも他で使われているのと同じ意味です: このオプションが指定されていて、かつ nargs > 1 である場合、 optparse は nargs 個の引数を消費します。このとき各引数は type 型に変換できなければなりません。変換後の値はタプルとしてコールバックに渡されます。

callback_args

その他の位置引数からなるタプルで、コールバックに渡されます

callback_kwargs

その他のキーワード引数からなる辞書で、コールバックに渡されます

コールバック関数はどのように呼び出されるか

コールバックは全て以下の形式で呼び出されます:

func(option, opt_str, value, parser, *args, **kwargs)

ここでは:

option

コールバックを呼び出している Option のインスタンスです

opt_str

は、コールバック呼び出しのきっかけとなったコマンドライン上のオプション文字列です。(長い形式のオプションに対する省略形が使われている場合、opt_str は完全な、正式な形のオプション文字列となります --- 例えば、ユーザが --foobar の短縮形として --foo をコマンドラインに入力した時には、opt_str は "--foobar" となります。)

value

オプションの引数で、コマンドライン上に見つかったものです。 optparse は、 type が設定されている場合、単一の引数しかとりません。 value の型はオプションの型として指定された型になります。このオプションに対する type が None である(引数なしの) 場合、 value は None になります。 nargs > 1 であれば、 value は適切な型をもつ値のタプルになります。

parser

現在のオプション解析の全てを駆動している OptionParser インスタンスです。この変数が有用なのは、この値を介してインスタンス属性としていくつかの興味深いデータにアクセスできるからです:

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 parser.largs, e.g. by adding more arguments to it. (This list will become args, the second return value of parse_args().)

parser.rargs

現在残っている引数、すなわち、opt_str および value があれば除き、それ以外の引数が残っているリストです。parser.rargs は自由に変更でき、例えばさらに引数を消費したりできます。

parser.values

オプションの値がデフォルトで保存されるオブジェクト (optparse.OptionValues のインスタンス) です。この値を使うと、コールバック関数がオプションの値を記憶するために、他の optparse と同じ機構を使えるようにするため、グローバル変数や閉包 (closure) を台無しにしないので便利です。コマンドライン上にすでに現れているオプションの値にもアクセスできます。

args

callback_args オプション属性で与えられた任意の位置引数からなるタプルです。

kwargs

callback_kwargs オプション属性で与えられた任意のキーワード引数からなるタプルです。

コールバック中で例外を送出する

オプション自体か、あるいはその引数に問題がある場合、コールバック関数は OptionValueError を送出しなければなりません。 optparse はこの例外をとらえてプログラムを終了させ、ユーザが指定しておいたエラーメッセージを標準エラー出力に出力します。エラーメッセージは明確、簡潔かつ正確で、どのオプションに誤りがあるかを示さなければなりません。さもなければ、ユーザは自分の操作のどこに問題があるかを解決するのに苦労することになります。

コールバックの例 1: ありふれたコールバック

引数をとらず、発見したオプションを単に記録するだけのコールバックオプションの例を以下に示します:

def record_foo_seen(option, opt_str, value, parser):
    parser.values.saw_foo = True

parser.add_option("--foo", action="callback", callback=record_foo_seen)

もちろん、"store_true" アクションを使っても実現できます。

コールバックの例 2: オプションの順番をチェックする

もう少し面白みのある例を示します: この例では、-b を発見して、その後で -a がコマンドライン中に現れた場合にはエラーになります。

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")

コールバックの例 3: オプションの順番をチェックする (汎用的)

このコールバック (フラグを立てるが、-b が既に指定されていればエラーになる) を同様の複数のオプションに対して再利用したければ、もう少し作業する必要があります: エラーメッセージとセットされるフラグを一般化しなければなりません。

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')

コールバックの例 4: 任意の条件をチェックする

もちろん、単に定義済みのオプションの値を調べるだけにとどまらず、コールバックには任意の条件を入れられます。例えば、満月でなければ呼び出してはならないオプションがあるとしましょう。やらなければならないことはこれだけです:

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")

(is_moon_full() の定義は読者への課題としましょう。)

コールバックの例5: 固定引数

決まった数の引数をとるようなコールパックオプションを定義するなら、問題はやや興味深くなってきます。引数をとるようコールバックに指定するのは、 "store" や "append" オプションの定義に似ています。 type を定義していれば、そのオプションは引数を受け取ったときに該当する型に変換できなければなりません。さらに nargs を指定すれば、オプションは nargs 個の引数を受け取ります。

標準の "store" アクションをエミュレートする例を以下に示します:

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")

optparse は 3 個の引数を受け取り、それらを整数に変換するところまで面倒をみてくれます。ユーザは単にそれを保存するだけです。 (他の処理もできます; いうまでもなく、この例にはコールバックは必要ありません)

コールバックの例6: 可変個の引数

あるオプションに可変個の引数を持たせたいと考えているなら、問題はいささか手強くなってきます。この場合、 optparse では該当する組み込みのオプション解析機能を提供していないので、自分でコールバックを書かなければなりません。さらに、 optparse が普段処理している、伝統的な Unix コマンドライン解析における難題を自分で解決しなければなりません。とりわけ、コールバック関数では引数が裸の -- や - の場合における慣習的な処理規則:

either -- or - can be option arguments

裸の -- (何らかのオプションの引数でない場合): コマンドライン処理を停止し、-- を無視します

裸の - (何らかのオプションの引数でない場合): コマンドライン処理を停止しますが、- は残します (parser.largs に追加します)

オプションが可変個の引数をとるようにさせたいなら、いくつかの巧妙で厄介な問題に配慮しなければなりません。どういう実装をとるかは、アプリケーションでどのようなトレードオフを考慮するかによります (このため、 optparse では可変個の引数に関する問題を直接的に取り扱わないのです)。

とはいえ、可変個の引数をもつオプションに対するスタブ (stub、仲介インターフェース) を以下に示しておきます:

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)

optparse の拡張

optparse がコマンドラインオプションをどのように解釈するかを決める二つの重要な要素はそれぞれのオプションのアクションと型なので、拡張の方向は新しいアクションと型を追加することになると思います。

新しい型の追加

新しい型を追加するためには、 optparse の Option クラスのサブクラスを自身で定義する必要があります。このクラスには optparse における型を定義する一対の属性があります。それは TYPES と TYPE_CHECKER です。

Option.TYPES

TYPES は型名のタプルです。新しく作るサブクラスでは、タプル TYPES を単純に標準のものを利用して新しく定義すると良いでしょう。

Option.TYPE_CHECKER

TYPE_CHECKER は辞書で型名を型チェック関数に対応付けるものです。型チェック関数は以下のようなシグネチャを持ちます:

def check_mytype(option, opt, value)

ここで option は Option のインスタンスであり、 opt はオプション文字列(たとえば -f)で、 value は望みの型としてチェックされ変換されるべくコマンドラインで与えられる文字列です。 check_mytype() は想定されている型 mytype のオブジェクトを返さなければなりません。型チェック関数から返される値は OptionParser.parse_args() で返されるOptionValues インスタンスに収められるか、またはコールバックに value パラメータとして渡されます。

型チェック関数は何か問題に遭遇したら OptionValueError を送出しなければなりません。 OptionValueError は文字列一つを引数に取り、それはそのまま OptionParser の error() メソッドに渡され、そこでプログラム名と文字列 "error:" が前置されてプロセスが終了する前に stderr に出力されます。

馬鹿馬鹿しい例ですが、Python スタイルの複素数を解析する "complex" オプション型を作ってみせることにします。(optparse 1.3 が複素数のサポートを組み込んでしまったため以前にも増して馬鹿らしくなりましたが、気にしないでください。)

最初に必要な import 文を書きます:

from copy import copy
from optparse import Option, OptionValueError

まずは型チェック関数を定義しなければなりません。これは後で(これから定義する Option のサブクラスの TYPE_CHECKER クラス属性の中で) 参照されることになります:

def check_complex(option, opt, value):
    try:
        return complex(value)
    except ValueError:
        raise OptionValueError(
            "option %s: invalid complex value: %r" % (opt, value))

最後に Option のサブクラスです:

class MyOption (Option):
    TYPES = Option.TYPES + ("complex",)
    TYPE_CHECKER = copy(Option.TYPE_CHECKER)
    TYPE_CHECKER["complex"] = check_complex

(もしここで Option.TYPE_CHECKER に copy() を適用しなければ、 optparse の Option クラスの TYPE_CHECKER 属性をいじってしまうことになります。 Python の常として、良いマナーと常識以外にそうすることを止めるものはありません。)

これだけです! もう新しいオプション型を使うスクリプトを他の optparse に基づいたスクリプトとまるで同じように書くことができます。ただし、 OptionParser に Option でなく MyOption を使うように指示しなければなければなりません:

parser = OptionParser(option_class=MyOption)
parser.add_option("-c", type="complex")

別のやり方として、オプションリストを構築して OptionParser に渡すという方法もあります。 add_option() を上でやったように使わないならば、OptionParser にどのクラスを使うのか教える必要はありません:

option_list = [MyOption("-c", action="store", type="complex", dest="c")]
parser = OptionParser(option_list=option_list)

新しいアクションの追加

新しいアクションの追加はもう少しトリッキーです。というのも optparse が使っている二つのアクションの分類を理解する必要があるからです:

"store" アクション

optparse が値を現在の OptionValues の属性に格納することになるアクションです。この種類のオプションは Option のコンストラクタに dest 属性を与えることが要求されます。

"typed" アクション

コマンドラインから引数を受け取り、それがある型であることが期待されているアクションです。もう少しはっきり言えば、その型に変換される文字列を受け取るものです。この種類のオプションは Option のコンストラクタに type 属性を与えることが要求されます。

この分類には重複する部分があります。デフォルトの "store" アクションには "store", "store_const", "append", "count" などがありますが、デフォルトの "typed" オプションは "store", "append", "callback" の三つです。

アクションを追加する際に、以下の Option のクラス属性(全て文字列のリストです) の中の少なくとも一つに付け加えることでそのアクションを分類する必要があります:

Option.ACTIONS

全てのアクションは ACTIONS にリストされていなければなりません。

Option.STORE_ACTIONS

"store" アクションはここにもリストされます。

Option.TYPED_ACTIONS

"typed" アクションはここにもリストされます。

Option.ALWAYS_TYPED_ACTIONS

型を取るアクション (つまりそのオプションが値を取る) はここにもリストされます。このことの唯一の効果は optparse が、型の指定が無くアクションが ALWAYS_TYPED_ACTIONS のリストにあるオプションに、デフォルト型 "string" を割り当てるということだけです。

実際に新しいアクションを実装するには、Option の take_action() メソッドをオーバライドしてそのアクションを認識する場合分けを追加しなければなりません。

例えば、"extend" アクションというのを追加してみましょう。このアクションは標準的な "append" アクションと似ていますが、コマンドラインから一つだけ値を読み取って既存のリストに追加するのではなく、複数の値をコンマ区切りの文字列として読み取ってそれらで既存のリストを拡張します。すなわち、もし --names が "string" 型の "extend" オプションだとすると、次のコマンドライン

--names=foo,bar --names blah --names ding,dong

の結果は次のリストになります

["foo", "bar", "blah", "ding", "dong"]

再び Option のサブクラスを定義します:

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)

注意すべきは次のようなところです:

"extend" はコマンドラインの値を予期していると同時にその値をどこかに格納しますので、 STORE_ACTIONS と TYPED_ACTIONS の両方に入ります。

optparse が "extend" アクションに "string" 型を割り当てるように "extend" アクションは ALWAYS_TYPED_ACTIONS にも入れてあります。

MyOption.take_action() にはこの新しいアクション一つの扱いだけを実装してあり、他の標準的な optparse のアクションについては Option.take_action() に制御を戻すようにしてあります。

values は optparse_parser.Values クラスのインスタンスであり、非常に有用な ensure_value() メソッドを提供しています。 ensure_value() は本質的に安全弁付きの getattr() です。次のように呼び出します

values.ensure_value(attr, value)

If the attr attribute of values doesn't exist or is None, then ensure_value() first sets it to value, and then returns value. This is very handy for actions like "extend", "append", and "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 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 None and ensure_value() will take care of getting it right when it's needed.

例外

exception optparse.OptionError

Raised if an Option instance is created with invalid or inconsistent arguments.

exception optparse.OptionConflictError

Raised if conflicting options are added to an OptionParser.

exception optparse.OptionValueError

Raised if an invalid option value is encountered on the command line.

exception optparse.BadOptionError

Raised if an invalid option is passed on the command line.

exception optparse.AmbiguousOptionError

Raised if an ambiguous option is passed on the command line.

ossaudiodev --- OSS互換オーディオデバイスへのアクセス

バージョン 3.11 で非推奨、バージョン 3.13 で削除予定: ossaudiodev モジュールは非推奨です (詳細は PEP 594 [https://peps.python.org/pep-0594/#ossaudiodev] 参照)。

このモジュールを使うとOSS (Open Sound System) オーディオインターフェースにアクセスできます。OSSはオープンソースあるいは商用のUnixで広く利用でき、Linux (カーネル 2.4まで) とFreeBSDで標準のオーディオインターフェースです。

バージョン 3.3 で変更: このモジュールの操作で以前は IOError が送出されていたところで OSError が送出されるようになりました。

参考

Open Sound System Programmer's Guide [http://www.opensound.com/pguide/oss.pdf]

OSS C API の公式ドキュメント

このモジュールでは、OSS デバイスドライバが提供している大量の定数が定義されています; 一覧は Linux や FreeBSD 上の <sys/soundcard.h> を参照してください。

ossaudiodev では以下の変数と関数を定義しています:

exception ossaudiodev.OSSAudioError

何らかのエラーのときに送出される例外です。引数は何が誤っているかを示す文字列です。

(ossaudiodev が open()、 write() 、ioctl() などのシステムコールからエラーを受け取った場合、 OSError を送出します。 ossaudiodev によって直接検知されたエラーでは OSSAudioError になります。)

(以前のバージョンとの互換性のため、この例外クラスは ossaudiodev.error としても利用できます。)

ossaudiodev.open(mode)

ossaudiodev.open(device, mode)

オーディオデバイスを開き、OSSオーディオデバイスオブジェクトを返します。このオブジェクトは read() 、 write() 、 fileno() といったファイル類似オブジェクトのメソッドを数多くサポートしています。 (とはいえ、伝統的な Unix の read/write における意味づけと OSS デバイスの read/write との間には微妙な違いがあります)。また、オーディオ特有の多くのメソッドがあります;メソッドの完全なリストについては下記を参照してください。

device は使用するオーディオデバイスファイルネームです。もしこれが指定されないなら、このモジュールは使うデバイスとして最初に環境変数 AUDIODEV を参照します。見つからなければ /dev/dsp を参照します。

mode は読み出し専用アクセスの場合には 'r'、書き込み専用 (プレイバック) アクセスの場合には 'w'、読み書きアクセスの場合には 'rw' にします。多くのサウンドカードは一つのプロセスが一度にレコーダとプレーヤのどちらかしか開けないようにしているため、必要な操作に応じたデバイスだけを開くようにするのがよいでしょう。また、サウンドカードには半二重 (half- duplex) 方式のものがあります: こうしたカードでは、デバイスを読み出しまたは書き込み用に開くことはできますが、両方同時には開けません。

呼び出しの文法が普通と異なることに注意してください: 最初の 引数は省略可能で、2番目が必須です。これは ossaudiodev にとってかわられた古い linuxaudiodev との互換性のためという歴史的な産物です。

ossaudiodev.openmixer([device])

ミキサデバイスを開き、OSSミキサデバイスオブジェクトを返します。 device は使用するミキサデバイスのファイル名です。 device を指定しない場合、モジュールはまず環境変数 MIXERDEV を参照して使用するデバイスを探します。見つからなければ、 /dev/mixer を参照します。

オーディオデバイスオブジェクト

オーディオデバイスに読み書きできるようになるには、まず 3 つのメソッドを正しい順序で呼び出さねばなりません:

setfmt() で出力形式を設定し

channels() でチャンネル数を設定し

speed() でサンプリングレートを設定します

この代わりに setparameters() メソッドを呼び出せば、三つのオーディオパラメタを一度で設定できます。 setparameters() は便利ですが、多くの状況で柔軟性に欠けるでしょう。

open() の返すオーディオデバイスオブジェクトには以下のメソッドおよび(読み出し専用の)属性があります:

oss_audio_device.close()

オーディオデバイスを明示的に閉じます。オーディオデバイスは、読み出しや書き込みが終了したら必ず閉じねばなりません。閉じたオブジェクトを再度開くことはできません。

oss_audio_device.fileno()

デバイスに関連付けられているファイル記述子を返します。

oss_audio_device.read(size)

オーディオ入力から size バイトを読みだし、 Python 文字列型にして返します。多くの Unix デバイスドライバと違い、ブロックデバイスモード (デフォルト) の OSS オーディオデバイスでは、要求した量のデータ全体を取り込むまで read() がブロックします。

oss_audio_device.write(data)

bytes-like object data の内容をオーディオデバイスに書き込み、書き込まれたバイト数を返します。オーディオデバイスがブロックモード (デフォルト) の場合、常にデータ全体を書き込みます (前述のように、これは通常のUnix デバイスの振舞いとは異なります)。デバイスが非ブロックモードの場合、データの一部が書き込まれないことがあります --- writeall() を参照してください。

バージョン 3.5 で変更: 書き込み可能な bytes-like object を使用できるようになりました。

oss_audio_device.writeall(data)

bytes-like object data をオーディオデバイスに書き込みます。オーディオデバイスがデータを受け取れるようになるまで待機し、書き込めるだけのデータを書き込むという操作を、 data を全て書き込み終わるまで繰り返します。デバイスがブロックモード (デフォルト) の場合には、このメソッドは write() と同じです。 writeall() が有用なのは非ブロックモードだけです。実際に書き込まれたデータの量と渡したデータの量は必ず同じになるので、戻り値はありません。

バージョン 3.5 で変更: 書き込み可能な bytes-like object を使用できるようになりました。

バージョン 3.2 で変更: オーディオデバイスオブジェクトはコンテキストマネージメントプロトコルをサポートしています。つまり with 文で使うことができます。

以下の各メソッドは、厳密に 1 つの ioctl() システムコールに対応しています。対応関係は明らかです: 例えば、 setfmt() は ioctl の SNDCTL_DSP_SETFMT に対応し、 sync() は SNDCTL_DSP_SYNC に対応します (これは OSS のドキュメントを調べるときに便利です) 。中で呼んでいる ioctl() が失敗した場合は、 OSError が送出されます。

oss_audio_device.nonblock()

デバイスを非ブロックモードにします。いったん非ブロックモードにしたら、ブロックモードは戻せません。

oss_audio_device.getfmts()

サウンドカードがサポートしているオーディオ出力形式をビットマスクで返します。以下はOSSでサポートされているフォーマットの一部です:

フォーマット

説明

AFMT_MU_LAW

対数符号化 (Sun の .au 形式や /dev/audio で使われている形式)

AFMT_A_LAW

対数符号化

AFMT_IMA_ADPCM

Interactive Multimedia Association で定義されている 4:1 圧縮形式

AFMT_U8

符号なし 8 ビットオーディオ

AFMT_S16_LE

符号つき 16 ビットオーディオ、リトルエンディアンバイトオーダ (Intelプロセッサで使われている形式)

AFMT_S16_BE

符号つき 16 ビットオーディオ、ビッグエンディアンバイトオーダ (68k、PowerPC、Sparcで使われている形式)

AFMT_S8

符号つき 8 ビットオーディオ

AFMT_U16_LE

符号なし 16 ビットリトルエンディアンオーディオ

AFMT_U16_BE

符号なし 16 ビットビッグエンディアンオーディオ

オーディオ形式の完全なリストは OSS の文書をひもといてください。ただ、ほとんどのシステムは、こうした形式のサブセットしかサポートしていません。古めのデバイスの中には AFMT_U8 だけしかサポートしていないものがあります。現在使われている最も一般的な形式は AFMT_S16_LE です。

oss_audio_device.setfmt(format)

現在のオーディオ形式を format に設定しようと試みます --- format については getfmts() のリストを参照してください。実際にデバイスに設定されたオーディオ形式を返します。要求通りの形式でないこともあります。 AFMT_QUERY を渡すと現在デバイスに設定されているオーディオ形式を返します。

oss_audio_device.channels(nchannels)

出力チャネル数を nchannels に設定します。1 はモノラル、2 はステレオです。いくつかのデバイスでは2つより多いチャンネルを持つものもありますし、ハイエンドなデバイスではモノラルをサポートしないものもあります。デバイスに設定されたチャンネル数を返します。

oss_audio_device.speed(samplerate)

サンプリングレートを1秒あたり samplerate に設定しようと試み、実際に設定されたレートを返します。たいていのサウンドデバイスでは任意のサンプリングレートをサポートしていません。一般的なレートは以下の通りです:

レート

説明

8000

/dev/audio のデフォルト

11025

会話音声の録音に使われるレート

22050

44100

(サンプルあたり 16 ビットで 2 チャネルの場合) CD 品質のオーディオ

96000

(サンプル当たり 24 ビットの場合) DVD 品質のオーディオ

oss_audio_device.sync()

サウンドデバイスがバッファ内の全てのデータを再生し終えるまで待機します。 (デバイスを閉じると暗黙のうちに sync() が起こります) OSS のドキュメント上では、 sync() を使うよりデバイスを一度閉じて開き直すよう勧めています。

oss_audio_device.reset()

再生あるいは録音を即座に中止して、デバイスをコマンドを受け取れる状態に戻します。OSSのドキュメントでは、 reset() を呼び出した後に一度デバイスを閉じ、開き直すよう勧めています。

oss_audio_device.post()

ドライバに出力の一時停止 (pause) が起きそうであることを伝え、ドライバが一時停止をより賢く扱えるようにします。短いサウンドエフェクトを再生した直後やユーザ入力待ちの前、またディスク I/O 前などに使うことになるでしょう。

以下のメソッドは、複数の ioctl() を組み合わせたり、ioctl() と単純な計算を組み合わせたりした便宜用メソッドです。

oss_audio_device.setparameters(format, nchannels, samplerate[, strict=False])

主要なオーディオパラメタ、サンプル形式、チャネル数、サンプルレートを一つのメソッド呼び出しで設定します。 format 、 nchannels および samplerate には、それぞれ setfmt() 、 channels() および speed() と同じやり方で値を設定します。 strict の値が真の場合、 setparameters() は値が実際に要求通りにデバイスに設定されたかどうか調べ、違っていれば OSSAudioError を送出します。実際にデバイスドライバが設定したパラメタ値を表す (format, nchannels, samplerate) からなるタプルを返します (setfmt() 、 channels() および speed() の返す値と同じです)。

例えば、

(fmt, channels, rate) = dsp.setparameters(fmt, channels, rate)

は以下と同等です

fmt = dsp.setfmt(fmt)
channels = dsp.channels(channels)
rate = dsp.rate(rate)

oss_audio_device.bufsize()

ハードウェアのバッファサイズをサンプル数で返します。

oss_audio_device.obufcount()

ハードウェアバッファ上に残っていてまだ再生されていないサンプル数を返します。

oss_audio_device.obuffree()

ブロックを起こさずにハードウェアの再生キューに書き込めるサンプル数を返します。

オーディオデバイスオブジェクトは読み出し専用の属性もサポートしています:

oss_audio_device.closed

デバイスが閉じられたかどうかを示す真偽値です。

oss_audio_device.name

デバイスファイルの名前を含む文字列です。

oss_audio_device.mode

ファイルの I/O モードで、"r", "rw", "w" のどれかです。

ミキサデバイスオブジェクト

ミキサオブジェクトには、2つのファイル類似メソッドがあります:

oss_mixer_device.close()

このメソッドは開いているミキサデバイスオブジェクトを閉じます。このファイルを閉じた後もミキサを使おうとすると、 OSError が送出されます。

oss_mixer_device.fileno()

開かれているミキサデバイスファイルのファイルハンドルナンバを返します。

バージョン 3.2 で変更: ミキサオブジェクトはコンテキストマネージメントプロトコルもサポートします。

以下はオーディオミキシング固有のメソッドです:

oss_mixer_device.controls()

このメソッドは、利用可能なミキサコントロール (SOUND_MIXER_PCM や SOUND_MIXER_SYNTH のように、ミキシングを行えるチャネル) を指定するビットマスクを返します。このビットマスクは利用可能な全てのミキサコントロールのサブセットです --- 定数 SOUND_MIXER_* はモジュールレベルで定義されています。例えば、もし現在のミキサオブジェクトがPCM ミキサをサポートしているか調べるには、以下のPythonコードを実行します:

mixer=ossaudiodev.openmixer()
if mixer.controls() & (1 << ossaudiodev.SOUND_MIXER_PCM):
    # PCM is supported
    ... code ...

ほとんどの用途には、 SOUND_MIXER_VOLUME (マスタボリューム) と SOUND_MIXER_PCM コントロールがあれば十分でしょう --- とはいえ、ミキサを使うコードを書くときには、コントロールを選ぶ時に柔軟性を持たせるべきです。例えば Gravis Ultrasound には SOUND_MIXER_VOLUME がありません。

oss_mixer_device.stereocontrols()

ステレオミキサコントロールを示すビットマスクを返します。ビットが立っているコントロールはステレオであることを示し、立っていないコントロールはモノラルか、ミキサがサポートしていないコントロールである (どちらの理由かは controls() と組み合わせて使うことで判別できます) ことを示します。

ビットマスクから情報を得る例は関数 controls() のコード例を参照してください。

oss_mixer_device.reccontrols()

録音に使用できるミキサコントロールを特定するビットマスクを返します。ビットマスクから情報を得る例は関数 controls() のコード例を参照してください。

oss_mixer_device.get(control)

指定したミキサコントロールのボリュームを返します。2 要素のタプル (left_volume,right_volume) を返します。ボリュームの値は 0 (無音) から100 (最大) で示されます。コントロールがモノラルでも2要素のタプルが返されますが、2つの要素の値は同じになります。

不正なコントロールを指定した場合は OSSAudioError を、サポートされていないコントロールを指定した場合は OSError を送出します。

oss_mixer_device.set(control, (left, right))

指定したミキサコントロールのボリュームを (left,right) に設定します。left と right は整数で、0 (無音) から100 (最大) の間で指定せねばなりません。呼び出しに成功すると新しいボリューム値を 2 要素のタプルで返します。サウンドカードによっては、ミキサの分解能上の制限から、指定したボリュームと厳密に同じにはならない場合があります。

不正なコントロールを指定した場合や、指定したボリューム値が範囲外であった場合、 OSSAudioError を送出します。

oss_mixer_device.get_recsrc()

現在録音のソースに使われているコントロールを示すビットマスクを返します。

oss_mixer_device.set_recsrc(bitmask)

録音のソースを指定するために、この関数を呼び出します。成功した場合は、新しい録音のソース (1 つもしくは複数) を示すビットマスクを返します; 不正なソースを指定した場合は、 OSError を送出します。現在の録音のソースをマイク入力に設定するには以下のように呼び出します:

mixer.setrecsrc (1 << ossaudiodev.SOUND_MIXER_MIC)

pipes --- シェルパイプラインへのインターフェース

ソースコード: Lib/pipes.py [https://github.com/python/cpython/tree/3.12/Lib/pipes.py]

バージョン 3.11 で非推奨、バージョン 3.13 で削除予定: The pipes module is deprecated (see PEP 594 [https://peps.python.org/pep-0594/#pipes] for details). Please use the subprocess module instead.

pipes モジュールでは、 pipeline の概念 --- あるファイルを別のファイルに変換する機構の直列接続 --- を抽象化するためのクラスを定義しています。

このモジュールは /bin/sh コマンドラインを利用するため、 os.system() および os.popen() のための POSIX 準拠のシェル、または互換のシェルが必要です。

Availability: Unix, not VxWorks.

pipes モジュールでは、以下のクラスを定義しています:

class pipes.Template

パイプラインを抽象化したクラス。

以下はプログラム例です:

>>> import pipes
>>> t = pipes.Template()
>>> t.append('tr a-z A-Z', '--')
>>> f = t.open('pipefile', 'w')
>>> f.write('hello world')
>>> f.close()
>>> open('pipefile').read()
'HELLO WORLD'

テンプレートオブジェクト

テンプレートオブジェクトは以下のメソッドを持っています:

Template.reset()

パイプラインテンプレートを初期状態に戻します。

Template.clone()

元のパイプラインテンプレートと等価の新しいオブジェクトを返します。

Template.debug(flag)

flag が真の場合、デバッグをオンにします。そうでない場合、デバッグをオフにします。デバッグがオンの時には、実行されるコマンドが印字され、より多くのメッセージを出力するようにするために、シェルに set -x 命令を与えます。

Template.append(cmd, kind)

新たなアクションをパイプラインの末尾に追加します。cmd 変数は有効な bourne shell 命令でなければなりません。kind 変数は二つの文字からなります。

最初の文字は '-' (コマンドが標準入力からデータを読み出すことを意味します)、'f' (コマンドがコマンドライン上で与えたファイルからデータを読み出すことを意味します)、あるいは '.' (コマンドは入力を読まないことを意味します、従ってパイプラインの先頭になります)、のいずれかになります。

同様に、二つ目の文字は '-' (コマンドが標準出力に結果を書き込むことを意味します)、'f' (コマンドがコマンドライン上で指定したファイルに結果を書き込むことを意味します)、あるいは '.' (コマンドはファイルを書き込まないことを意味し、パイプラインの末尾になります)、のいずれかになります。

Template.prepend(cmd, kind)

パイプラインの先頭に新しいアクションを追加します。引数の説明については append() を参照してください。

Template.open(file, mode)

ファイル類似のオブジェクトを返します。このオブジェクトは file を開いていますが、パイプラインを通して読み書きするようになっています。mode には 'r' または 'w' のいずれか一つしか与えることができないので注意してください。

Template.copy(infile, outfile)

パイプを通して infile を outfile にコピーします。

sndhdr --- サウンドファイルの識別

ソースコード: Lib/sndhdr.py [https://github.com/python/cpython/tree/3.12/Lib/sndhdr.py]

バージョン 3.11 で非推奨、バージョン 3.13 で削除予定: The sndhdr module is deprecated (see PEP 594 [https://peps.python.org/pep-0594/#sndhdr] for details and alternatives).

sndhdr モジュールには、ファイルに保存されたサウンドデータの形式を識別するのに便利な関数が定義されています。どんな形式のサウンドデータがファイルに保存されているのか識別可能な場合、これらの関数は5つの属性、つまり(filetype, framerate, nchannels, nframes, sampwidth)で構成される namedtuple() を返します。 type はデータの形式を示す文字列で、 'aifc', 'aiff', 'au', 'hcom', 'sndr', 'sndt', 'voc', 'wav', '8svx', 'sb', 'ub', 'ul' のうちの一つです。 sampling_rate は実際のサンプリングレート値で、未知の場合や読み取ることが出来なかった場合は 0 です。同様に、 channels はチャンネル数で、識別できない場合や読み取ることが出来なかった場合は 0 です。 frames はフレーム数で、識別できない場合は -1 です。タプルの最後の要素 bits_per_sample はサンプルサイズを示すビット数ですが、A-LAWなら 'A', u-LAWなら 'U' です。

sndhdr.what(filename)

whathdr() を使って、ファイル filename に保存されたサウンドデータの形式を識別します。識別可能なら上記のnamedtupleを返し、識別できない場合は None を返します。

バージョン 3.5 で変更: 結果が tuple から namedtuple に変更されました。

sndhdr.whathdr(filename)

ファイルのヘッダ情報をもとに、保存されたサウンドデータの形式を識別します。ファイル名は filename で渡されます。識別可能なら上記の namedtuple を返し、識別できない場合は None を返します。

バージョン 3.5 で変更: 結果が tuple から namedtuple に変更されました。

The following sound header types are recognized, as listed below with the return value from whathdr(): and what():

値

Sound header format

'aifc'

Compressed Audio Interchange Files

'aiff'

Audio Interchange Files

'au'

Au Files

'hcom'

HCOM Files

'sndt'

Sndtool Sound Files

'voc'

Creative Labs Audio Files

'wav'

Waveform Audio File Format Files

'8svx'

8-Bit Sampled Voice Files

'sb'

Signed Byte Audio Data Files

'ub'

UB Files

'ul'

uLAW Audio Files

sndhdr.tests

個別のテストを行う関数のリスト。それぞれの関数は二つの引数をとります: バイトストリームとオープンされたファイルのようにふるまうオブジェクト。 what() がバイトストリームとともに呼び出されたときは、ファイルのようにふるまうオブジェクトは None でしょう。

テストが成功した場合は、テスト関数は画像形式を表す文字列を返すべきです。あるいは、失敗した場合は None を返すべきです。

例:

>>> import sndhdr
>>> imghdr.what('bass.wav')
'wav'
>>> imghdr.whathdr('bass.wav')
'wav'

spwd --- シャドウパスワードデータベース

バージョン 3.11 で非推奨、バージョン 3.13 で削除予定: The spwd module is deprecated (see PEP 594 [https://peps.python.org/pep-0594/#spwd] for details and alternatives).

このモジュールは Unix のシャドウパスワードデータベースへのアクセスを提供します。様々な Unix 環境で利用できます。

利用可能性: Emscripten でなく、WASI でもないこと。

このモジュールは WebAssembly プラットフォーム wasm32-emscripten と wasm32-wasi では動作しないか、利用不可です。詳しくは、WebAssemblyプラットフォーム を見てください。

シャドウパスワードデータベースへアクセスできる権限が必要(大抵の場合 root である必要があります)です。

シャドウパスワードデータベースのエントリはタプル状のオプジェクトで提供され、その属性は spwd 構造のメンバーに対応しています（以下を参照してください。<shadow.h> を参照):

インデックス

属性

意味

0

sp_namp

ログイン名

1

sp_pwdp

暗号化されたパスワード

2

sp_lstchg

最終更新日

3

sp_min

パスワード変更が出来るようになるまでの最小日数

4

sp_max

パスワードを変更しなくても良い最大日数

5

sp_warn

パスワードが期限切れになる前に、期限切れが近づいている旨の警告をユーザに出しはじめる日数

6

sp_inact

パスワードが期限切れになってからアカウントが無効になるまでの日数

7

sp_expire

アカウントが期限切れになる日の 1970-01-01 からの日数

8

sp_flag

将来のために予約

sp_namp と sp_pwdp は文字列で、他は全て整数です。エントリが見つからなかった時は KeyError が起きます。

以下の関数が定義されています:

spwd.getspnam(name)

与えられたユーザ名に対応するシャドーパスワードデータベースのエントリを返します。

バージョン 3.6 で変更: ユーザが権限を持っていない場合、 KeyError の代わりに PermissionError を送出します。

spwd.getspall()

このモジュールでは以下を定義しています。

参考

grp モジュール

このモジュールに似た、グループデータベースへのアクセスを提供するモジュール。

pwd モジュール

このモジュールに似た通常のパスワードデータベースへのインターフェース。

sunau --- Sun AUファイルの読み書き

ソースコード: Lib/sunau.py [https://github.com/python/cpython/tree/3.12/Lib/sunau.py]

バージョン 3.11 で非推奨、バージョン 3.13 で削除予定: The sunau module is deprecated (see PEP 594 [https://peps.python.org/pep-0594/#sunau] for details).

sunau モジュールは、Sun AUサウンドフォーマットへの便利なインターフェースを提供します。このモジュールは、 aifc モジュールや wave モジュールと互換性のあるインターフェースを備えています。

オーディオファイルはヘッダとそれに続くデータから構成されます。ヘッダのフィールドは以下の通りです:

フィールド

内容

magic word

4バイト文字列 .snd。

header size

infoを含むヘッダのサイズをバイト数で示したもの。

data size

データの物理サイズをバイト数で示したもの。

encoding

オーディオサンプルのエンコード形式。

sample rate

サンプリングレート。

# of channels

サンプルのチャンネル数。

info

オーディオファイルについての説明をASCII文字列で示したもの（null バイトで埋められます）。

infoフィールド以外の全てのヘッダフィールドは4バイトの大きさです。ヘッダフィールドはbig-endianでエンコードされた、計32ビットの符合なし整数です。

sunau モジュールは以下の関数を定義しています:

sunau.open(file, mode)

file が文字列ならその名前のファイルを開き、そうでないならファイルのようにシーク可能なオブジェクトとして扱います。mode は以下のうちのいずれかです

'r'

読み出しのみのモード。

'w'

書き込みのみのモード。

読み込み／書き込み両方のモードで開くことはできないことに注意して下さい。

'r' の mode は AU_read オブジェクトを返し、 'w' と 'wb' の mode は AU_write オブジェクトを返します。

sunau モジュールは以下の例外を定義しています:

exception sunau.Error

Sun AUの仕様や実装に対する不適切な操作により何か実行不可能となった時に発生するエラー。

sunau モジュールは以下のデータアイテムを定義しています:

sunau.AUDIO_FILE_MAGIC

big-endianで保存された正規のSun AUファイルは全てこの整数で始まります。これは文字列 .snd を整数に変換したものです。

sunau.AUDIO_FILE_ENCODING_MULAW_8

sunau.AUDIO_FILE_ENCODING_LINEAR_8

sunau.AUDIO_FILE_ENCODING_LINEAR_16

sunau.AUDIO_FILE_ENCODING_LINEAR_24

sunau.AUDIO_FILE_ENCODING_LINEAR_32

sunau.AUDIO_FILE_ENCODING_ALAW_8

AUヘッダのencodingフィールドの値で、このモジュールでサポートしているものです。

sunau.AUDIO_FILE_ENCODING_FLOAT

sunau.AUDIO_FILE_ENCODING_DOUBLE

sunau.AUDIO_FILE_ENCODING_ADPCM_G721

sunau.AUDIO_FILE_ENCODING_ADPCM_G722

sunau.AUDIO_FILE_ENCODING_ADPCM_G723_3

sunau.AUDIO_FILE_ENCODING_ADPCM_G723_5

AUヘッダのencodingフィールドの値のうち既知のものとして追加されているものですが、このモジュールではサポートされていません。

AU_read オブジェクト

上述の open() によって返されるAU_readオブジェクトには、以下のメソッドがあります:

AU_read.close()

ストリームを閉じ、このオブジェクトのインスタンスを使用できなくします。（これはオブジェクトのガベージコレクション時に自動的に呼び出されます。）

AU_read.getnchannels()

オーディオチャンネル数（モノラルなら1、ステレオなら2）を返します。

AU_read.getsampwidth()

サンプルサイズをバイト数で返します。

AU_read.getframerate()

サンプリングレートを返します。

AU_read.getnframes()

オーディオフレーム数を返します。

AU_read.getcomptype()

圧縮形式を返します。'ULAW', 'ALAW', 'NONE' がサポートされている形式です。

AU_read.getcompname()

getcomptype() を人に判読可能な形にしたものです。上述の形式に対して、それぞれ 'CCITT G.711 u-law', 'CCITT G.711 A-law', 'not compressed' がサポートされています。

AU_read.getparams()

get*() メソッドが返すのと同じ (nchannels, sampwidth, framerate, nframes, comptype, compname) の namedtuple() を返します。

AU_read.readframes(n)

n 個のオーディオフレームの値を読み込んで、 bytes オブジェクトを返します。データはlinear形式で返されます。もし元のデータがu-LAW形式なら、変換されます。

AU_read.rewind()

ファイルのポインタをオーディオストリームの先頭に戻します。

以下の2つのメソッドは共通の"位置"を定義しています。"位置"は他の関数とは独立して実装されています。

AU_read.setpos(pos)

ファイルのポインタを指定した位置に設定します。 tell() で返される値を pos として使用しなければなりません。

AU_read.tell()

ファイルの現在のポインタ位置を返します。返される値はファイルの実際の位置に対して何も操作はしません。

以下の2つのメソッドは aifc モジュールとの互換性のために定義されていますが、何も面白いことはしません。

AU_read.getmarkers()

None を返します。

AU_read.getmark(id)

エラーを発生します。

AU_write オブジェクト

上述の open() によって返されるWave_writeオブジェクトには、以下のメソッドがあります:

AU_write.setnchannels(n)

チャンネル数を設定します。

AU_write.setsampwidth(n)

サンプルサイズを（バイト数で）設定します。

バージョン 3.4 で変更: 24-bit サンプルのサポートが追加されました。

AU_write.setframerate(n)

フレームレートを設定します。

AU_write.setnframes(n)

フレーム数を設定します。あとからフレームが書き込まれるとフレーム数は変更されます。

AU_write.setcomptype(type, name)

圧縮形式とその記述を設定します。'NONE' と 'ULAW' だけが、出力時にサポートされている形式です。

AU_write.setparams(tuple)

tuple は (nchannels, sampwidth, framerate, nframes, comptype, compname) で、それぞれ set*() のメソッドの値にふさわしいものでなければなりません。全ての変数を設定します。

AU_write.tell()

ファイルの中の現在位置を返します。 AU_read.tell() と AU_read.setpos() メソッドでお断りしたことがこのメソッドにも当てはまります。

AU_write.writeframesraw(data)

nframes の修正なしにオーディオフレームを書き込みます。

バージョン 3.4 で変更: どのような bytes-like object も使用できるようになりました。

AU_write.writeframes(data)

オーディオフレームを書き込んで nframes を修正します。

バージョン 3.4 で変更: どのような bytes-like object も使用できるようになりました。

AU_write.close()

nframes が正しいか確認して、ファイルを閉じます。

このメソッドはオブジェクトの削除時に呼び出されます。

writeframes() や writeframesraw() メソッドを呼び出したあとで、どんなパラメータを設定しようとしても不正となることに注意して下さい。

telnetlib --- Telnet クライアント

ソースコード: Lib/telnetlib.py [https://github.com/python/cpython/tree/3.12/Lib/telnetlib.py]

バージョン 3.11 で非推奨、バージョン 3.13 で削除予定: The telnetlib module is deprecated (see PEP 594 [https://peps.python.org/pep-0594/#telnetlib] for details and alternatives).

telnetlib モジュールでは、Telnet プロトコルを実装している Telnet クラスを提供します。Telnet プロトコルについての詳細は RFC 854 [https://datatracker.ietf.org/doc/html/rfc854.html] を参照してください。加えて、このモジュールでは Telnet プロトコルにおける制御文字 (下を参照してください) と、telnet オプションに対するシンボル定数を提供しています。telnet オプションに対するシンボル名は arpa/telnet.h の TELOPT_ がない状態での定義に従います。伝統的に arpa/telnet.h に含められていない telnet オプションのシンボル名については、このモジュールのソースコード自体を参照してください。

telnet コマンドのシンボル定数は、IAC、DONT、DO、WONT、WILL、SE (サブネゴシエーション終了)、NOP (何もしない)、DM (データマーク)、BRK (ブレーク)、IP (プロセス中断)、AO (出力停止)、AYT (応答確認)、EC (文字削除)、EL (行削除)、GA (進め)、SB (サブネゴシエーション開始) です。

利用可能性: Emscripten でなく、WASI でもないこと。

このモジュールは WebAssembly プラットフォーム wasm32-emscripten と wasm32-wasi では動作しないか、利用不可です。詳しくは、WebAssemblyプラットフォーム を見てください。

class telnetlib.Telnet(host=None, port=0[, timeout])

Telnet は Telnet サーバへの接続を表現します。デフォルトでは、 Telnet クラスのインスタンスは最初はサーバに接続していません。接続を確立するには open() を使わなければなりません。別の方法として、コンストラクタにホスト名とオプションのポート番号を渡すこともできます。この場合はコンストラクタの呼び出しが返る以前にサーバへの接続が確立されます。オプション引数の timeout が渡された場合、コネクション接続時のタイムアウト時間を秒数で指定します (指定されなかった場合は、グローバルのデフォルトタイムアウト設定が利用されます)。

すでに接続の開かれているンスタンスを再度開いてはいけません。

このクラスは多くの read_*() メソッドを持っています。これらのメソッドのいくつかは、接続の終端を示す文字を読み込んだ場合に EOFError を送出するので注意してください。例外を送出するのは、これらの関数が終端に到達しなくても空の文字列を返す可能性があるからです。詳しくは下記の個々の説明を参照してください。

Telnet オブジェクトはコンテキストマネージャであり、 with 文で使えます。 with ブロックから抜けるとき、 close() メソッドが呼び出されます:

>>> from telnetlib import Telnet
>>> with Telnet('localhost', 23) as tn:
...     tn.interact()
...

バージョン 3.6 で変更: コンテキストマネージャーサポートが追加されました。

参考

RFC 854 [https://datatracker.ietf.org/doc/html/rfc854.html] - Telnet プロトコル仕様

Telnet プロトコルの定義。

Telnet オブジェクト

Telnet インスタンスは以下のメソッドを持っています:

Telnet.read_until(expected, timeout=None)

expected で指定されたバイト文字列を読み込むか、timeout で指定された秒数が経過するまで読み込みます。

与えられた文字列に一致する部分が見つからなかった場合、読み込むことができたもの全てを返します。これは空のバイト列になる可能性があります。接続が閉じられ、転送処理済みのデータが得られない場合には EOFError が送出されます。

Telnet.read_all()

EOFに到達するまでの全てのデータをバイト列として読み込みます; 接続が閉じられるまでブロックします。

Telnet.read_some()

EOF に到達しない限り、少なくとも 1 バイトの転送処理済みデータを読み込みます。EOF に到達した場合は b'' を返します。すぐに読み出せるデータが存在しない場合にはブロックします。

Telnet.read_very_eager()

I/O によるブロックを起こさずに読み出せる全てのデータを読み込みます (eager モード)。

接続が閉じられており、転送処理済みのデータとして読み出せるものがない場合には EOFError が送出されます。それ以外の場合で、単に読み出せるデータがない場合には b'' を返します。 IAC シーケンス操作中でないかぎりブロックしません。

Telnet.read_eager()

現在すぐに読み出せるデータを読み出します。

接続が閉じられており、転送処理済みのデータとして読み出せるものがない場合には EOFError が送出されます。それ以外の場合で、単に読み出せるデータがない場合には b'' を返します。 IAC シーケンス操作中でないかぎりブロックしません。

Telnet.read_lazy()

すでにキューに入っているデータを処理して返します (lazy モード)。

接続が閉じられており、読み出せるデータがない場合には EOFError を送出します。それ以外の場合で、転送処理済みのデータで読み出せるものがない場合には b'' を返します。 IAC シーケンス操作中でないかぎりブロックしません。

Telnet.read_very_lazy()

すでに処理済みキューに入っているデータを処理して返します (very lazy モード)。

接続が閉じられており、読み出せるデータがない場合には EOFError を送出します。それ以外の場合で、転送処理済みのデータで読み出せるものがない場合には b'' を返します。このメソッドは決してブロックしません。

Telnet.read_sb_data()

SB/SE ペア (サブオプション開始／終了) の間に収集されたデータを返します。 SE コマンドによって起動されたコールバック関数はこれらのデータにアクセスしなければなりません。このメソッドはけっしてブロックしません。

Telnet.open(host, port=0[, timeout])

サーバホストに接続します。第二引数はオプションで、ポート番号を指定します。標準の値は通常の Telnet ポート番号 (23) です。オプション引数の timeout が渡された場合、コネクション接続時などのブロックする操作のタイムアウト時間を秒数で指定します (指定されなかった場合は、グローバルのデフォルトタイムアウト設定が利用されます)。

すでに接続しているインスタンスで再接続を試みてはいけません。

引数 self, host, port 付きで 監査イベント telnetlib.Telnet.open を送出します。

Telnet.msg(msg, *args)

デバッグレベルが > 0 のとき、デバッグ用のメッセージを出力します。追加の引数が存在する場合、標準の文字列書式化演算子 % を使って msg 中の書式指定子に代入されます。

Telnet.set_debuglevel(debuglevel)

デバッグレベルを設定します。 debuglevel が大きくなるほど、 (sys.stdout に) デバッグメッセージがたくさん出力されます。

Telnet.close()

コネクションをクローズします。

Telnet.get_socket()

内部的に使われているソケットオブジェクトです。

Telnet.fileno()

内部的に使われているソケットオブジェクトのファイル記述子です。

Telnet.write(buffer)

ソケットにバイト文字列を書き込みます。このとき IAC 文字については 2 度送信します。接続がブロックした場合、書き込みがブロックする可能性があります。接続が閉じられた場合、 OSError が送出されるかもしれません。

引数 self, buffer 付きで 監査イベント telnetlib.Telnet.write を送出します。

バージョン 3.3 で変更: このメソッドは以前は socket.error を投げていましたが、これは現在では OSError の別名になっています。

Telnet.interact()

非常に低機能の telnet クライアントをエミュレートする対話関数です。

Telnet.mt_interact()

interact() のマルチスレッド版です。

Telnet.expect(list, timeout=None)

正規表現のリストのうちどれか一つにマッチするまでデータを読みます。

第一引数は正規表現のリストです。コンパイルされたもの (regex オブジェクト) でも、コンパイルされていないもの (バイト文字列) でもかまいません。オプションの第二引数はタイムアウトで、単位は秒です。標準の値は無期限に設定されています。

3 つの要素からなるタプル: 最初にマッチした正規表現のインデクス; 返されたマッチオブジェクト; マッチ部分を含む、マッチするまでに読み込まれたバイト列、を返します。

ファイル終了子が見つかり、かつ何もバイト列が読み込まれなかった場合、 EOFError が送出されます。そうでない場合で何もマッチしなかった場合には (-1, None, data) が返されます。ここで data はこれまで受信したバイト列です (タイムアウトが発生した場合には空のバイト列になる場合もあります)。

正規表現の末尾が (.* のような) 貪欲マッチングになっている場合や、入力に対して 1 つ以上の正規表現がマッチする場合には、その結果は決定不能で、I/O のタイミングに依存するでしょう。

Telnet.set_option_negotiation_callback(callback)

telnet オプションが入力フローから読み込まれるたびに、 callback が (設定されていれば) 以下の引数形式: callback(telnet socket, command (DO/DONT/WILL/WONT), option) で呼び出されます。その後 telnet オプションに対しては telnetlib は何も行いません。

Telnet Example

典型的な使用例のサンプルコード:

import getpass
import telnetlib

HOST = "localhost"
user = input("Enter your remote account: ")
password = getpass.getpass()

tn = telnetlib.Telnet(HOST)

tn.read_until(b"login: ")
tn.write(user.encode('ascii') + b"\n")
if password:
    tn.read_until(b"Password: ")
    tn.write(password.encode('ascii') + b"\n")

tn.write(b"ls\n")
tn.write(b"exit\n")

print(tn.read_all().decode('ascii'))

uu --- uuencode形式のエンコードとデコード

ソースコード: Lib/uu.py [https://github.com/python/cpython/tree/3.12/Lib/uu.py]

バージョン 3.11 で非推奨、バージョン 3.13 で削除予定: The uu module is deprecated (see PEP 594 [https://peps.python.org/pep-0594/#uu-and-the-uu-encoding] for details). base64 is a modern alternative.

このモジュールではファイルを uuencode 形式(任意のバイナリデータを ASCII 文字列に変換したもの)にエンコード、デコードする機能を提供します。引数としてファイルが仮定されている所では、ファイルのようなオブジェクトが利用できます。後方互換性のために、パス名を含む文字列も利用できるようにしていて、対応するファイルを開いて読み書きします。しかし、このインターフェースは利用しないでください。呼び出し側でファイルを開いて(Windows では 'rb' か 'wb' のモードで)利用する方法が推奨されます。

このコードは Lance Ellinghouse によって提供され、Jack Jansen によって更新されました。

uu モジュールでは以下の関数を定義しています:

uu.encode(in_file, out_file, name=None, mode=None, *, backtick=False)

in_file を out_file にエンコードします。エンコードされたファイルには、デフォルトでデコード時に利用される name と mode を含んだヘッダがつきます。省略された場合には、in_file から取得された名前か '-' という文字と、0o666 がそれぞれデフォルト値として与えられます。 backtick が真だった場合は、ゼロは空白ではなく '`' で表現されます。

バージョン 3.7 で変更: backtick パラメータを追加しました.

uu.decode(in_file, out_file=None, mode=None, quiet=False)

uuencode 形式でエンコードされた in_file をデコードして varout_file に書き出します。もし out_file がパス名でかつファイルを作る必要があるときには、 mode がパーミッションの設定に使われます。 out_file と mode のデフォルト値は in_file のヘッダから取得されます。しかし、ヘッダで指定されたファイルが既に存在していた場合は、 uu.Error が送出されます。

誤った実装の uuencoder による入力で、エラーから復旧できた場合、 decode() は標準エラー出力に警告を表示するかもしれません。 quiet を真にすることでこの警告を抑制することができます。

exception uu.Error

Exception のサブクラスで、 uu.decode() によって、さまざまな状況で送出される可能性があります。上で紹介された場合以外にも、ヘッダのフォーマットが間違っている場合や、入力ファイルが途中で区切れた場合にも送出されます。

参考

モジュール binascii

ASCII からバイナリへ、バイナリから ASCII への変換をサポートするモジュール。

xdrlib --- XDR データのエンコードおよびデコード

ソースコード: Lib/xdrlib.py [https://github.com/python/cpython/tree/3.12/Lib/xdrlib.py]

バージョン 3.11 で非推奨、バージョン 3.13 で削除予定: The xdrlib module is deprecated (see PEP 594 [https://peps.python.org/pep-0594/#xdrlib] for details).

xdrlib モジュールは外部データ表現標準 (External Data Representation Standard) のサポートを実現します。この標準は 1987 年に Sun Microsystems, Inc. によって書かれ、 RFC 1014 [https://datatracker.ietf.org/doc/html/rfc1014.html] で定義されています。このモジュールでは RFC で記述されているほとんどのデータ型をサポートしています。

xdrlib モジュールでは 2 つのクラスが定義されています。一つは変数を XDR 表現にパックするためのクラスで、もう一方は XDR 表現からアンパックするためのものです。2 つの例外クラスが同様にして定義されています。

class xdrlib.Packer

Packer はデータを XDR 表現にパックするためのクラスです。 Packer クラスのインスタンス生成は引数なしで行われます。

class xdrlib.Unpacker(data)

Unpacker は Packer と対をなしていて、文字列バッファから XDR をアンパックするためのクラスです。入力バッファ data を引数に与えてインスタンスを生成します。

参考

RFC 1014 [https://datatracker.ietf.org/doc/html/rfc1014.html] - XDR: External Data Representation Standard

この RFC が、かつてこのモジュールが最初に書かれた当時に XDR 標準であったデータのエンコード方法を定義していました。現在は RFC 1832 [https://datatracker.ietf.org/doc/html/rfc1832.html] に更新されているようです。

RFC 1832 [https://datatracker.ietf.org/doc/html/rfc1832.html] - XDR: External Data Representation Standard

こちらが新しい方のRFCで、XDR の改訂版が定義されています。

Packer オブジェクト

Packer インスタンスには以下のメソッドがあります:

Packer.get_buffer()

現在のパック処理用バッファを文字列で返します。

Packer.reset()

パック処理用バッファをリセットして、空文字にします。

一般的には、適切な pack_type() メソッドを使えば、一般に用いられているほとんどの XDR データをパックすることができます。各々のメソッドは一つの引数をとり、パックしたい値を与えます。単純なデータ型をパックするメソッドとして、以下のメソッド: pack_uint() 、 pack_int() 、 pack_enum() 、 pack_bool() 、 pack_uhyper() そして pack_hyper() がサポートされています。

Packer.pack_float(value)

単精度 (single-precision) の浮動小数点数 value をパックします。

Packer.pack_double(value)

倍精度 (double-precision) の浮動小数点数 value をパックします。

以下のメソッドは文字列、バイト列、不透明データ (opaque data) のパック処理をサポートします:

Packer.pack_fstring(n, s)

固定長の文字列、s をパックします。n は文字列の長さですが、この値自体はデータバッファにはパック されません。4 バイトのアラインメントを保証するために、文字列は必要に応じて null バイト列でパディングされます。

Packer.pack_fopaque(n, data)

pack_fstring() と同じく、固定長の不透明データストリームをパックします。

Packer.pack_string(s)

可変長の文字列 s をパックします。文字列の長さが最初に符号なし整数でパックされ、続いて pack_fstring() を使って文字列データがパックされます。

Packer.pack_opaque(data)

pack_string() と同じく、可変長の不透明データ文字列をパックします。

Packer.pack_bytes(bytes)

pack_string() と同じく、可変長のバイトストリームをパックします。

以下のメソッドはアレイやリストのパック処理をサポートします:

Packer.pack_list(list, pack_item)

一様な項目からなる list をパックします。このメソッドはサイズ不定、すなわち、全てのリスト内容を網羅するまでサイズが分からないリストに対して有用です。リストのすべての項目に対し、最初に符号無し整数 1 がパックされ、続いてリスト中のデータがパックされます。pack_item は個々の項目をパックするために呼び出される関数です。リストの末端に到達すると、符号無し整数 0 がパックされます。

例えば、整数のリストをパックするには、コードは以下のようになるはずです:

import xdrlib
p = xdrlib.Packer()
p.pack_list([1, 2, 3], p.pack_int)

Packer.pack_farray(n, array, pack_item)

一様な項目からなる固定長のリスト (array) をパックします。 n はリストの長さです。この値はデータバッファにパック されません が、 len(array) が n と等しくない場合、例外 ValueError が送出されます。上と同様に、 pack_item は個々の要素をパック処理するための関数です。

Packer.pack_array(list, pack_item)

一様の項目からなる可変長の list をパックします。まず、リストの長さが符号無し整数でパックされ、つづいて各要素が上の pack_farray() と同じやり方でパックされます。

Unpacker オブジェクト

Unpacker クラスは以下のメソッドを提供します:

Unpacker.reset(data)

文字列バッファを data でリセットします。

Unpacker.get_position()

データバッファ中の現在のアンパック処理位置を返します。

Unpacker.set_position(position)

データバッファ中のアンパック処理位置を position に設定します。 get_position() および set_position() は注意して使わなければなりません。

Unpacker.get_buffer()

現在のアンパック処理用データバッファを文字列で返します。

Unpacker.done()

アンパック処理を終了させます。全てのデータがまだアンパックされていなければ、例外 Error が送出されます。

上のメソッドに加えて、 Packer でパック処理できるデータ型はいずれも Unpacker でアンパック処理できます。アンパック処理メソッドは unpack_type() の形式をとり、引数をとりません。これらのメソッドはアンパックされたデータオブジェクトを返します。

Unpacker.unpack_float()

単精度の浮動小数点数をアンパックします。

Unpacker.unpack_double()

unpack_float() と同様に、倍精度の浮動小数点数をアンパックします。

上のメソッドに加えて、文字列、バイト列、不透明データをアンパックする以下のメソッドが提供されています:

Unpacker.unpack_fstring(n)

固定長の文字列をアンパックして返します。n は予想される文字列の長さです。4 バイトのアラインメントを保証するために null バイトによるパディングが行われているものと仮定して処理を行います。

Unpacker.unpack_fopaque(n)

unpack_fstring() と同様に、固定長の不透明データストリームをアンパックして返します。

Unpacker.unpack_string()

可変長の文字列をアンパックして返します。最初に文字列の長さが符号無し整数としてアンパックされ、次に unpack_fstring() を使って文字列データがアンパックされます。

Unpacker.unpack_opaque()

unpack_string() と同様に、可変長の不透明データ文字列をアンパックして返します。

Unpacker.unpack_bytes()

unpack_string() と同様に、可変長のバイトストリームをアンパックして返します。

以下メソッドはアレイおよびリストのアンパック処理をサポートします:

Unpacker.unpack_list(unpack_item)

一様な項目からなるリストをアンパック処理して返します。リストは、まず符号無し整数によるフラグをアンパックすることで、一度に 1 要素づつアンパック処理されます。フラグが 1 の場合、要素はアンパックされ、返り値のリストに追加されます。フラグが 0 の場合、リストの終端を示します。unpack_item は個々の項目をアンパック処理するために呼び出される関数です。

Unpacker.unpack_farray(n, unpack_item)

一様な項目からなる固定長のアレイをアンパックして（リストとして）返します。n はバッファ内に存在すると期待されるリストの要素数です。上と同様に、unpack_item は各要素をアンパックするために使われる関数です。

Unpacker.unpack_array(unpack_item)

一様な項目からなる可変長の list をアンパックして返します。まず、リストの長さが符号無し整数としてアンパックされ、続いて各要素が上の unpack_farray() のようにしてアンパック処理されます。

例外

このモジュールでの例外はクラスインスタンスとしてコードされています:

exception xdrlib.Error

ベースとなる例外クラスです。 Error public な属性として msg を持ち、エラーの詳細が収められています。

exception xdrlib.ConversionError

Error から派生したクラスです。インスタンス変数は追加されていません。

これらの例外を補足する方法を以下の例に示します:

import xdrlib
p = xdrlib.Packer()
try:
    p.pack_double(8.01)
except xdrlib.ConversionError as instance:
    print('packing the double failed:', instance.msg)

セキュリティで考慮すべき点

The following modules have specific security considerations:

base64: base64 security considerations in RFC 4648 [https://datatracker.ietf.org/doc/html/rfc4648.html]

cgi: CGI security considerations

hashlib: all constructors take a "usedforsecurity" keyword-only argument disabling known insecure and blocked algorithms

http.server is not suitable for production use, only implementing basic security checks. See the security considerations.

logging: Logging configuration uses eval()

multiprocessing: Connection.recv() uses pickle

pickle: Restricting globals in pickle

random shouldn't be used for security purposes, use secrets instead

shelve: shelve is based on pickle and thus unsuitable for dealing with untrusted sources

ssl: SSL/TLS security considerations

subprocess: Subprocess security considerations

tempfile: mktemp is deprecated due to vulnerability to race conditions

xml: XML vulnerabilities

zipfile: maliciously prepared .zip files can cause disk volume exhaustion

The -I command line option can be used to run Python in isolated mode. When it cannot be used, the -P option or the PYTHONSAFEPATH environment variable can be used to not prepend a potentially unsafe path to sys.path such as the current directory, the script's directory or an empty string.

Python インタプリタの拡張と埋め込み

このドキュメントでは、Pythonインタプリンタを拡張する新しいモジュールをで C またはC++ で書く方法を解説しています。このようなモジュールでは新しい関数を定義するだけではなく、新しい型や、そのメソッドを定義することができます。ドキュメントでは他のアプリケーションでPythonを拡張言語として使用するために、Pythonインタプリタをアプリケーションに埋め込む方法についても解説します。最後に、下層のオペレーティングシステムが動的(実行時)ロードをサポートしていれば、拡張モジュールが動的にライブラリにロードされるように、モジュールをコンパイルしリンクする方法について解説します。

このドキュメントでは、読者は Python について基礎的な知識を持ち合わせているものと仮定しています。形式ばらない Python 言語の入門には、 Python チュートリアル を読んでください。 Python 言語リファレンス を読めば、 Python 言語についてより形式的な定義を得られます。また、 Python 標準ライブラリ では、Python に広い適用範囲をもたらしている既存のオブジェクト型、関数、および (組み込み、および Python で書かれたものの両方の) モジュールについて解説しています。

Python/C API 全体の詳しい説明は、別のドキュメントである、 Python/C API リファレンスマニュアル を参照してください。

おすすめのサードパーティツール

このガイドがカバーするのは、このバージョンの CPython の一部として提供されている、拡張を作成するための基本的なツールだけです。 Cython [https://cython.org/], cffi [https://cffi.readthedocs.io], SWIG [https://www.swig.org], Numba [https://numba.pydata.org/] のようなサードパーティのツールは、 Python の C および C++ 拡張を作成するための、より簡潔かつより洗練された手法を提供します。

参考

Python Packaging User Guide: Binary Extensions [https://packaging.python.org/guides/packaging-binary-extensions/]

Python Packaging User Guideはバイナリ拡張の作成が簡単になる便利なツールをカバーしているだけではなく、まず始めになぜ拡張モジュールを作ることが望ましいかの様々な理由について議論しています。

サードパーティツールなしで拡張を作る

ガイドのこの節ではサードパーティツールの補助無しに C および C++ 拡張を作成する方法を説明します。これは自分自身の C 拡張を作成するおすすめの方法というよりも、主にそれらのツールを作成する人向けのものです。

1. C や C++ による Python の拡張

1.1. 簡単な例

1.2. 幕間小話: エラーと例外

1.3. 例に戻る

1.4. モジュールのメソッドテーブルと初期化関数

1.5. コンパイルとリンク

1.6. C から Python 関数を呼び出す

1.7. 拡張モジュール関数でのパラメタ展開

1.8. 拡張モジュール関数のキーワードパラメタ

1.9. 任意の値を構築する

1.10. 参照カウント法

1.11. C++での拡張モジュール作成

1.12. 拡張モジュールに C API を提供する

2. 拡張の型の定義: チュートリアル

2.1. 基本的なこと

2.2. 基本のサンプルにデータとメソッドを追加する

2.3. データ属性をこまかく制御する

2.4. 循環ガベージコレクションをサポートする

2.5. 他の型のサブクラスを作る

3. Defining Extension Types: Assorted Topics

3.1. ファイナライズとメモリ解放

3.2. オブジェクト表現

3.3. 属性を管理する

3.4. オブジェクトの比較

3.5. 抽象的なプロトコルのサポート

3.6. 弱参照(Weak Reference)のサポート

3.7. その他いろいろ

4. C および C++ 拡張のビルド

4.1. Building C and C++ Extensions with setuptools

5. Windows 上での C および C++ 拡張モジュールのビルド

5.1. 型どおりのアプローチ

5.2. Unix と Windows の相違点

5.3. DLL 使用の実際

大規模なアプリケーションへの Python ランタイムの埋め込み

Python インタープリタの中でメインアプリケーションとして実行される拡張を作るのではなく、 CPython をより大きなアプリケーションの中に埋め込む方が望ましいことがあります。この節ではその上手い埋め込みに関わる詳細について説明します。

1. 他のアプリケーションへの Python の埋め込み

1.1. 高水準の埋め込み

1.2. 超高水準の埋め込みから踏み出す: 概要

1.3. 純粋な埋め込み

1.4. 埋め込まれた Python の拡張

1.5. C++による Python の埋め込み

1.6. Unix 系システムにおけるコンパイルとリンク

1. C や C++ による Python の拡張

C プログラムの書き方を知っているなら、Python に新たな組み込みモジュールを追加するのはきわめて簡単です。この新たなモジュール、拡張モジュール (extension module) を使うと、Python が直接行えない二つのこと: 新しい組み込みオブジェクトの実装、そして全ての C ライブラリ関数とシステムコールに対する呼び出し、ができるようになります。

拡張モジュールをサポートするため、Python API (Application Programmer's Interface) では一連の関数、マクロおよび変数を提供していて、Python ランタイムシステムのほとんどの側面へのアクセス手段を提供しています。 Python API は、ヘッダ "Python.h" をインクルードして C ソースに取り込みます。

拡張モジュールのコンパイル方法は、モジュールの用途やシステムの設定方法に依存します。詳細は後の章で説明します。

注釈

C 拡張のインターフェイスは CPython に固有のものであり、これによる拡張モジュールはほかの Python 実装では動作しません。多くの場合、C 拡張を書くことを避けてほかの Python 実装のために移植性を確保することは可能です。たとえば、あなたがしたいことが C ライブラリの関数やシステムコールを呼び出すことである場合、 ctypes あるいは cffi [https://cffi.readthedocs.io/] ライブラリの利用を検討すべきです。これらのモジュールは C コードとインターフェイスし、C 拡張を書いてコンパイルするのに較べて Python 実装間のより高い移植性をもった Python コードを書かせてくれます。

1.1. 簡単な例

spam (Monty Python ファンの好物ですね) という名の拡張モジュールを作成することにして、C ライブラリ関数 system() に対する Python インターフェイスを作成したいとします。 [1] この関数は null で終端されたキャラクタ文字列を引数にとり、整数を返します。この関数を以下のようにして Python から呼び出せるようにしたいとします。

>>> import spam
>>> status = spam.system("ls -l")

まずは spammodule.c を作成するところから始めます。 (伝統として、 spam という名前のモジュールを作成する場合、モジュールの実装が入った C ファイルを spammodule.c と呼ぶことになっています; spammify のように長すぎるモジュール名の場合には、単に spammify.c にもできます。)

このファイルの最初の 2 行は以下のようにします:

#define PY_SSIZE_T_CLEAN
#include <Python.h>

これで、Python API を取り込みます (必要なら、モジュールの用途に関する説明や、著作権表示を追加します)。

注釈

Python は、システムによっては標準ヘッダの定義に影響するようなプリプロセッサ定義を行っているので、 Python.h をいずれの標準ヘッダよりも前にインクルード せねばなりません 。

It is recommended to always define PY_SSIZE_T_CLEAN before including Python.h. See 拡張モジュール関数でのパラメタ展開 for a description of this macro.

Python.h で定義されているユーザから可視のシンボルは、全て接頭辞 Py または PY が付いています。ただし、標準ヘッダファイル内の定義は除きます。簡単のためと、Python 内で広範に使うことになるという理由から、 "Python.h" はいくつかの標準ヘッダファイル: <stdio.h> 、 <string.h> 、 <errno.h> 、および <stdlib.h> をインクルードしています。後者のヘッダファイルがシステム上になければ、 "Python.h" が関数 malloc() 、 free() および realloc() を直接定義します。

次にファイルに追加する内容は、Python 式 spam.system(string) を評価する際に呼び出されることになる C 関数です (この関数を最終的にどのように呼び出すかは、後ですぐわかります):

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);
}

ここでは、Python の引数リスト (例えば、単一の式 "ls -l") から C 関数に渡す引数にそのまま変換しています。 C 関数は常に二つの引数を持ち、便宜的に self および args と呼ばれます。

self 引数には、モジュールレベルの関数であればモジュールが、メソッドにはオブジェクトインスタンスが渡されます。

args 引数は、引数の入った Python タプルオブジェクトへのポインタになります。タプル内の各要素は、呼び出しの際の引数リストにおける各引数に対応します。引数は Python オブジェクトです --- C 関数で引数を使って何かを行うには、オブジェクトから C の値に変換せねばなりません。Python API の関数 PyArg_ParseTuple() は引数の型をチェックし、C の値に変換します。 PyArg_ParseTuple() はテンプレート文字列を使って、引数オブジェクトの型と、変換された値を入れる C 変数の型を判別します。これについては後で詳しく説明します。

PyArg_ParseTuple() は、全ての引数が正しい型を持っていて、アドレス渡しされた各変数に各引数要素を保存したときに真 (非ゼロ) を返します。この関数は不正な引数リストを渡すと偽 (ゼロ) を返します。後者の場合、関数は適切な例外を送出するので、呼び出し側は (例にもあるように) すぐに NULL を返すようにしてください。

1.2. 幕間小話: エラーと例外

An important convention throughout the Python interpreter is the following: when a function fails, it should set an exception condition and return an error value (usually -1 or a NULL pointer). Exception information is stored in three members of the interpreter's thread state. These are NULL if there is no exception. Otherwise they are the C equivalents of the members of the Python tuple returned by sys.exc_info(). These are the exception type, exception instance, and a traceback object. It is important to know about them to understand how errors are passed around.

Python API では、様々な型の例外をセットするための関数をいくつか定義しています。

もっともよく用いられるのは PyErr_SetString() です。引数は例外オブジェクトと C 文字列です。例外オブジェクトは通常、 PyExc_ZeroDivisionError のような定義済みのオブジェクトです。 C 文字列はエラーの原因を示し、Python 文字列オブジェクトに変換されて例外の "付属値" に保存されます。

もう一つ有用な関数として PyErr_SetFromErrno() があります。この関数は引数に例外だけをとり、付属値はグローバル変数 errno から構築します。もっとも汎用的な関数は PyErr_SetObject() で、二つのオブジェクト、例外と付属値を引数にとります。これら関数に渡すオブジェクトには Py_INCREF() を使う必要はありません。

例外がセットされているかどうかは、 PyErr_Occurred() を使って非破壊的に調べられます。この関数は現在の例外オブジェクトを返します。例外が発生していない場合には NULL を返します。通常は、関数の戻り値からエラーが発生したかを判別できるはずなので、 PyErr_Occurred() を呼び出す必要はありません。

関数 g を呼び出す f が、前者の関数の呼び出しに失敗したことを検出すると、 f 自体はエラー値 (大抵は NULL や -1) を返さねばなりません。しかし、 PyErr_* 関数群のいずれかを呼び出す必要は ありません --- なぜなら、 g がすでに呼び出しているからです。次いで f を呼び出したコードもエラーを示す値を 自らを呼び出したコード に返すことになりますが、同様に PyErr_* は 呼び出しません 。以下同様に続きます --- エラーの最も詳しい原因は、最初にエラーを検出した関数がすでに報告しているからです。エラーが Python インタプリタのメインループに到達すると、現在実行中の Python コードは一時停止し、 Python プログラマが指定した例外ハンドラを探し出そうとします。

(モジュールが PyErr_* 関数をもう一度呼び出して、より詳細なエラーメッセージを提供するような状況があります。このような状況ではそうすべきです。とはいえ、一般的な規則としては、この関数を何度も呼び出す必要はなく、ともすればエラーの原因に関する情報を失う結果になりがちです: これにより、ほとんどの操作が様々な理由から失敗するかもしれません)

ある関数呼び出しでの処理の失敗によってセットされた例外を無視するには、 PyErr_Clear() を呼び出して例外状態を明示的に消去しなくてはなりません。エラーをインタプリタには渡したくなく、自前で (何か他の作業を行ったり、何も起こらなかったかのように見せかけるような) エラー処理を完全に行う場合にのみ、 PyErr_Clear() を呼び出すようにすべきです。

malloc() の呼び出し失敗は、常に例外にしなくてはなりません --- malloc() (または realloc()) を直接呼び出しているコードは、 PyErr_NoMemory() を呼び出して、失敗を示す値を返さねばなりません。オブジェクトを生成する全ての関数 (例えば PyLong_FromLong()) は PyErr_NoMemory() の呼び出しを済ませてしまうので、この規則が関係するのは直接 malloc() を呼び出すコードだけです。

また、 PyArg_ParseTuple() という重要な例外を除いて、整数の状態コードを返す関数はたいてい、Unix のシステムコールと同じく、処理が成功した際にはゼロまたは正の値を返し、失敗した場合には -1 を返します。

最後に、エラー標示値を返す際に、(エラーが発生するまでに既に生成してしまったオブジェクトに対して Py_XDECREF() や Py_DECREF() を呼び出して) ごみ処理を注意深く行ってください!

The choice of which exception to raise is entirely yours. There are predeclared C objects corresponding to all built-in Python exceptions, such as PyExc_ZeroDivisionError, which you can use directly. Of course, you should choose exceptions wisely --- don't use PyExc_TypeError to mean that a file couldn't be opened (that should probably be PyExc_OSError). If something's wrong with the argument list, the PyArg_ParseTuple() function usually raises PyExc_TypeError. If you have an argument whose value must be in a particular range or must satisfy other conditions, PyExc_ValueError is appropriate.

モジュール固有の新たな例外も定義できます。定義するには、通常はファイルの先頭部分に静的なオブジェクト変数の宣言を行います:

static PyObject *SpamError;

and initialize it in your module's initialization function (PyInit_spam()) with an exception object:

PyMODINIT_FUNC
PyInit_spam(void)
{
    PyObject *m;

    m = PyModule_Create(&spammodule);
    if (m == NULL)
        return NULL;

    SpamError = PyErr_NewException("spam.error", NULL, NULL);
    Py_XINCREF(SpamError);
    if (PyModule_AddObject(m, "error", SpamError) < 0) {
        Py_XDECREF(SpamError);
        Py_CLEAR(SpamError);
        Py_DECREF(m);
        return NULL;
    }

    return m;
}

Note that the Python name for the exception object is spam.error. The PyErr_NewException() function may create a class with the base class being Exception (unless another class is passed in instead of NULL), described in 組み込み例外.

Note also that the SpamError variable retains a reference to the newly created exception class; this is intentional! Since the exception could be removed from the module by external code, an owned reference to the class is needed to ensure that it will not be discarded, causing SpamError to become a dangling pointer. Should it become a dangling pointer, C code which raises the exception could cause a core dump or other unintended side effects.

We discuss the use of PyMODINIT_FUNC as a function return type later in this sample.

The spam.error exception can be raised in your extension module using a call to PyErr_SetString() as shown below:

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);
}

1.3. 例に戻る

先ほどの関数の例に戻ると、今度は以下の実行文を理解できるはずです:

if (!PyArg_ParseTuple(args, "s", &command))
    return NULL;

It returns NULL (the error indicator for functions returning object pointers) if an error is detected in the argument list, relying on the exception set by PyArg_ParseTuple(). Otherwise the string value of the argument has been copied to the local variable command. This is a pointer assignment and you are not supposed to modify the string to which it points (so in Standard C, the variable command should properly be declared as const char *command).

次の文では、 PyArg_ParseTuple() で得た文字列を渡して Unix 関数 system() を呼び出しています:

sts = system(command);

Our spam.system() function must return the value of sts as a Python object. This is done using the function PyLong_FromLong().

return PyLong_FromLong(sts);

上の場合では、整数オブジェクトを返します。(そう、整数ですら、 Python においてはヒープ上のオブジェクトなのです! )

何ら有用な値を返さない関数 (void を返す関数) に対応する Python の関数は None を返さねばなりません。関数に None を返させるには、以下のような慣用句を使います (この慣用句は Py_RETURN_NONE マクロに実装されています):

Py_INCREF(Py_None);
return Py_None;

Py_None は特殊な Pyhton オブジェクトである None に対応する C での名前です。これまで見てきたようにほとんどのコンテキストで "エラー" を意味する NULL ポインタとは違い、 None は純粋な Python のオブジェクトです。

1.4. モジュールのメソッドテーブルと初期化関数

I promised to show how spam_system() is called from Python programs. First, we need to list its name and address in a "method table":

static PyMethodDef SpamMethods[] = {
    ...
    {"system",  spam_system, METH_VARARGS,
     "Execute a shell command."},
    ...
    {NULL, NULL, 0, NULL}        /* Sentinel */
};

リスト要素の三つ目のエントリ (METH_VARARGS) に注意してください。このエントリは、C 関数が使う呼び出し規約をインタプリタに教えるためのフラグです。通常この値は METH_VARARGS か METH_VARARGS | METH_KEYWORDS のはずです; 0 は旧式の PyArg_ParseTuple() の変化形が使われることを意味します。

METH_VARARGS だけを使う場合、C 関数は、Python レベルでの引数が PyArg_ParseTuple() が受理できるタプルの形式で渡されるものと想定しなければなりません; この関数についての詳細は下で説明します。

The METH_KEYWORDS bit may be set in the third field if keyword arguments should be passed to the function. In this case, the C function should accept a third PyObject * parameter which will be a dictionary of keywords. Use PyArg_ParseTupleAndKeywords() to parse the arguments to such a function.

メソッドテーブルはモジュール定義の構造体から参照されていなければなりません:

static struct PyModuleDef spammodule = {
    PyModuleDef_HEAD_INIT,
    "spam",   /* name of module */
    spam_doc, /* module documentation, may be NULL */
    -1,       /* size of per-interpreter state of the module,
                 or -1 if the module keeps state in global variables. */
    SpamMethods
};

This structure, in turn, must be passed to the interpreter in the module's initialization function. The initialization function must be named PyInit_name(), where name is the name of the module, and should be the only non-static item defined in the module file:

PyMODINIT_FUNC
PyInit_spam(void)
{
    return PyModule_Create(&spammodule);
}

Note that PyMODINIT_FUNC declares the function as PyObject * return type, declares any special linkage declarations required by the platform, and for C++ declares the function as extern "C".

When the Python program imports module spam for the first time, PyInit_spam() is called. (See below for comments about embedding Python.) It calls PyModule_Create(), which returns a module object, and inserts built-in function objects into the newly created module based upon the table (an array of PyMethodDef structures) found in the module definition. PyModule_Create() returns a pointer to the module object that it creates. It may abort with a fatal error for certain errors, or return NULL if the module could not be initialized satisfactorily. The init function must return the module object to its caller, so that it then gets inserted into sys.modules.

When embedding Python, the PyInit_spam() function is not called automatically unless there's an entry in the PyImport_Inittab table. To add the module to the initialization table, use PyImport_AppendInittab(), optionally followed by an import of the module:

int
main(int argc, char *argv[])
{
    wchar_t *program = Py_DecodeLocale(argv[0], NULL);
    if (program == NULL) {
        fprintf(stderr, "Fatal error: cannot decode argv[0]\n");
        exit(1);
    }

    /* Add a built-in module, before Py_Initialize */
    if (PyImport_AppendInittab("spam", PyInit_spam) == -1) {
        fprintf(stderr, "Error: could not extend in-built modules table\n");
        exit(1);
    }

    /* Pass argv[0] to the Python interpreter */
    Py_SetProgramName(program);

    /* Initialize the Python interpreter.  Required.
       If this step fails, it will be a fatal error. */
    Py_Initialize();

    /* Optionally import the module; alternatively,
       import can be deferred until the embedded script
       imports it. */
    PyObject *pmodule = PyImport_ImportModule("spam");
    if (!pmodule) {
        PyErr_Print();
        fprintf(stderr, "Error: could not import module 'spam'\n");
    }

    ...

    PyMem_RawFree(program);
    return 0;
}

注釈

単一のプロセス内 (または fork() 後の exec() が介入していない状態) における複数のインタプリタにおいて、 sys.modules からエントリを除去したり新たなコンパイル済みモジュールを import したりすると、拡張モジュールによっては問題を生じることがあります。拡張モジュールの作者は、内部データ構造を初期化する際にはよくよく用心すべきです。

より実質的なモジュール例は、Python ソース配布物に Modules/xxmodule.c という名前で入っています。このファイルはテンプレートとしても利用できますし、単に例としても読めます。

注釈

xmodule は spam と異なり、 多段階初期化 (multi-phase initialization (Python 3.5 の新機能) を使っています。 PyInit_spam が PyModuleDef を返し、モジュールの生成は後に import 機構が行います。多段階初期化についての詳細は PEP 489 [https://peps.python.org/pep-0489/] を参照してください。

1.5. コンパイルとリンク

新しい拡張モジュールを使えるようになるまで、まだ二つの作業: コンパイルと、Python システムへのリンク、が残っています。動的読み込み (dynamic loading) を使っているのなら、作業の詳細は自分のシステムが使っている動的読み込みの形式によって変わるかもしれません; 詳しくは、拡張モジュールのビルドに関する章 (C および C++ 拡張のビルド 章) や、Windows におけるビルドに関係する追加情報の章 (Windows 上での C および C++ 拡張モジュールのビルド 章) を参照してください。

動的読み込みを使えなかったり、モジュールを常時 Python インタプリタの一部にしておきたい場合には、インタプリタのビルド設定を変更して再ビルドしなければならなくなるでしょう。Unixでは、幸運なことにこの作業はとても単純です: 単に自作のモジュールファイル (例えば spammodule.c) を展開したソース配布物の Modules/ ディレクトリに置き、 Modules/Setup.local に自分のファイルを説明する以下の一行:

spam spammodule.o

を追加して、トップレベルのディレクトリで make を実行して、インタプリタを再ビルドするだけです。 Modules/ サブディレクトリでも make を実行できますが、前もって 'make Makefile' を実行して Makefile を再ビルドしておかなければならりません。(この作業は Setup ファイルを変更するたびに必要です。)

モジュールが別のライブラリとリンクされている必要がある場合、ライブラリも設定ファイルに列挙できます。例えば以下のようにします。

spam spammodule.o -lX11

1.6. C から Python 関数を呼び出す

これまでは、Python からの C 関数の呼び出しに重点を置いて述べてきました。ところでこの逆: C からの Python 関数の呼び出しもまた有用です。とりわけ、いわゆる "コールバック" 関数をサポートするようなライブラリを作成する際にはこの機能が便利です。ある C インターフェースがコールバックを利用している場合、同等の機能を提供する Python コードでは、しばしば Python プログラマにコールバック機構を提供する必要があります; このとき実装では、 C で書かれたコールバック関数から Python で書かれたコールパック関数を呼び出すようにする必要があるでしょう。もちろん、他の用途も考えられます。

幸運なことに、Python インタプリタは簡単に再帰呼び出しでき、 Python 関数を呼び出すための標準インターフェースもあります。 (Python パーザを特定の入力文字を使って呼び出す方法について詳説するつもりはありません --- この方法に興味があるなら、 Python ソースコードの Modules/main.c にある、コマンドラインオプション -c の実装を見てください)

Python 関数の呼び出しは簡単です。まず、C のコードに対してコールバックを登録しようとする Python プログラムは、何らかの方法で Python の関数オブジェクトを渡さねばなりません。このために、コールバック登録関数 (またはその他のインターフェース) を提供せねばなりません。このコールバック登録関数が呼び出された際に、引き渡された Python 関数オブジェクトへのポインタをグローバル変数に --- あるいは、どこか適切な場所に --- 保存します (関数オブジェクトを Py_INCREF() するようよく注意してください!)。例えば、以下のような関数がモジュールの一部になっていることでしょう:

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;
}

This function must be registered with the interpreter using the METH_VARARGS flag; this is described in section モジュールのメソッドテーブルと初期化関数. The PyArg_ParseTuple() function and its arguments are documented in section 拡張モジュール関数でのパラメタ展開.

Py_XINCREF() および Py_XDECREF() は、オブジェクトに対する参照カウントをインクリメント/デクリメントするためのマクロで、 NULL ポインタが渡されても安全に操作できる形式です (とはいえ、上の流れでは temp が NULL になることはありません)。これらのマクロと参照カウントについては、 参照カウント法 で説明しています。

その後、コールバック関数を呼び出す時が来たら、C 関数 PyObject_CallObject() を呼び出します。この関数には二つの引数: Python 関数と Python 関数の引数リストがあり、いずれも任意の Python オブジェクトを表すポインタ型です。引数リストは常にタプルオブジェクトでなければならず、その長さは引数の数になります。Python 関数を引数なしで呼び出すのなら、 NULL か空のタプルを渡します; 単一の引数で関数を呼び出すのなら、単要素 (singleton) のタプルを渡します。 Py_BuildValue() の書式文字列中に、ゼロ個または一個以上の書式化コードが入った丸括弧がある場合、この関数はタプルを返します。以下に例を示します:

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);

PyObject_CallObject() は Python オブジェクトへのポインタを返します: これは Python 関数からの戻り値になります。 PyObject_CallObject() は、引数に対して "参照カウント中立 (reference-count- neutral)" です。上の例ではタプルを生成して引数リストとして提供しており、このタプルは PyObject_CallObject() の呼び出し直後に Py_DECREF() されています。

PyObject_CallObject() は戻り値として "新しい" オブジェクト: 新規に作成されたオブジェクトか、既存のオブジェクトの参照カウントをインクリメントしたものを返します。従って、このオブジェクトをグローバル変数に保存したいのでないかぎり、たとえこの戻り値に興味がなくても (むしろ、そうであればなおさら!) 何がしかの方法で戻り値オブジェクトを Py_DECREF() しなければなりません。

とはいえ、戻り値を Py_DECREF() する前には、値が NULL でないかチェックしておくことが重要です。もし NULL なら、呼び出した Python 関数は例外を送出して終了させられています。 PyObject_CallObject() を呼び出しているコード自体もまた Python から呼び出されているのであれば、今度は C コードが自分を呼び出している Python コードにエラー標示値を返さねばなりません。それにより、インタプリタはスタックトレースを出力したり、例外を処理するための Python コードを呼び出したりできます。例外の送出が不可能だったり、したくないのなら、 PyErr_Clear() を呼んで例外を消去しておかねばなりません。例えば以下のようにします:

if (result == NULL)
    return NULL; /* Pass error back */
...use result...
Py_DECREF(result);

Python コールバック関数をどんなインターフェースにしたいかによっては、引数リストを PyObject_CallObject() に与えなければならない場合もあります。あるケースでは、コールバック関数を指定したのと同じインターフェースを介して、引数リストも渡されているかもしれません。また別のケースでは、新しいタプルを構築して引数リストを渡さねばならないかもしれません。この場合最も簡単なのは Py_BuildValue() を呼ぶやり方です。例えば、整数のイベントコードを渡したければ、以下のようなコードを使うことになるでしょう:

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);

Py_DECREF(arglist) が呼び出しの直後、エラーチェックよりも前に置かれていることに注意してください! また、厳密に言えば、このコードは完全ではありません: Py_BuildValue() はメモリ不足におちいるかもしれず、チェックしておくべきです。

通常の引数とキーワード引数をサポートする PyObject_Call() を使って、キーワード引数を伴う関数呼び出しをすることができます。上の例と同じように、 Py_BuildValue() を作って辞書を作ります。

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);

1.7. 拡張モジュール関数でのパラメタ展開

PyArg_ParseTuple() 関数は以下のように宣言されています:

int PyArg_ParseTuple(PyObject *arg, const char *format, ...);

引数 arg は C 関数から Python に渡される引数リストが入ったタプルオブジェクトでなければなりません。 format 引数は書式文字列で、 Python/C API リファレンスマニュアルの 引数の解釈と値の構築 で解説されている書法に従わねばなりません。残りの引数は、それぞれの変数のアドレスで、書式化文字列から決まる型になっていなければなりません。

PyArg_ParseTuple() は Python 側から与えられた引数が必要な型になっているか調べるのに対し、 PyArg_ParseTuple() は呼び出しの際に渡された C 変数のアドレスが有効な値を持つか調べられないことに注意してください: ここで間違いを犯すと、コードがクラッシュするかもしれませんし、少なくともでたらめなビットをメモリに上書きしてしまいます。慎重に!

呼び出し側に提供されるオブジェクトへの参照はすべて 借用 参照 (borrowed reference) になります; これらのオブジェクトの参照カウントをデクリメントしてはなりません!

以下にいくつかの呼び出し例を示します:

#define PY_SSIZE_T_CLEAN  /* Make "s#" use Py_ssize_t rather than int. */
#include <Python.h>

int ok;
int i, j;
long k, l;
const char *s;
Py_ssize_t size;

ok = PyArg_ParseTuple(args, ""); /* No arguments */
    /* Python call: f() */

ok = PyArg_ParseTuple(args, "s", &s); /* A string */
    /* Possible Python call: f('whoops!') */

ok = PyArg_ParseTuple(args, "lls", &k, &l, &s); /* Two longs and a string */
    /* Possible Python call: f(1, 2, 'three') */

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') */

{
    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) */
}

{
    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)) */
}

{
    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) */
}

1.8. 拡張モジュール関数のキーワードパラメタ

PyArg_ParseTupleAndKeywords() は、以下のように宣言されています:

int PyArg_ParseTupleAndKeywords(PyObject *arg, PyObject *kwdict,
                                const char *format, char *kwlist[], ...);

arg と format パラメタは PyArg_ParseTuple() のものと同じです。 kwdict パラメタはキーワード引数の入った辞書で、 Python ランタイムシステムから第三パラメタとして受け取ります。 kwlist パラメタは各パラメタを識別するための文字列からなる、 NULL 終端されたリストです; 各パラメタ名は format 中の型情報に対して左から右の順に照合されます。成功すると PyArg_ParseTupleAndKeywords() は真を返し、それ以外の場合には適切な例外を送出して偽を返します。

注釈

キーワード引数を使っている場合、タプルは入れ子にして使えません! kwlist 内に存在しないキーワードパラメタが渡された場合、 TypeError の送出を引き起こします。

以下にキーワードを使ったモジュール例を示します。これは Geoff Philbrick (philbrick@hks.com) によるプログラム例をもとにしています:

#define PY_SSIZE_T_CLEAN  /* Make "s#" use Py_ssize_t rather than int. */
#include <Python.h>

static PyObject *
keywdarg_parrot(PyObject *self, PyObject *args, PyObject *keywds)
{
    int voltage;
    const char *state = "a stiff";
    const char *action = "voom";
    const char *type = "Norwegian Blue";

    static char *kwlist[] = {"voltage", "state", "action", "type", NULL};

    if (!PyArg_ParseTupleAndKeywords(args, keywds, "i|sss", kwlist,
                                     &voltage, &state, &action, &type))
        return NULL;

    printf("-- This parrot wouldn't %s if you put %i Volts through it.\n",
           action, voltage);
    printf("-- Lovely plumage, the %s -- It's %s!\n", type, state);

    Py_RETURN_NONE;
}

static PyMethodDef keywdarg_methods[] = {
    /* The cast of the function is necessary since PyCFunction values
     * only take two PyObject* parameters, and keywdarg_parrot() takes
     * three.
     */
    {"parrot", (PyCFunction)(void(*)(void))keywdarg_parrot, METH_VARARGS | METH_KEYWORDS,
     "Print a lovely skit to standard output."},
    {NULL, NULL, 0, NULL}   /* sentinel */
};

static struct PyModuleDef keywdargmodule = {
    PyModuleDef_HEAD_INIT,
    "keywdarg",
    NULL,
    -1,
    keywdarg_methods
};

PyMODINIT_FUNC
PyInit_keywdarg(void)
{
    return PyModule_Create(&keywdargmodule);
}

1.9. 任意の値を構築する

Py_BuildValue() は PyArg_ParseTuple() の対極に位置するものです。この関数は以下のように定義されています:

PyObject *Py_BuildValue(const char *format, ...);

Py_BuildValue() は、 PyArg_ParseTuple() の認識する一連の書式単位に似た書式単位を認識します。ただし (関数への出力ではなく、入力に使われる) 引数はポインタではなく、ただの値でなければなりません。 Python から呼び出された C 関数が返す値として適切な、新たな Python オブジェクトを返します。

PyArg_ParseTuple() とは一つ違う点があります: PyArg_ParseTuple() は第一引数をタプルにする必要があります (Python の引数リストは内部的には常にタプルとして表現されるからです) が、 Py_BuildValue() はタプルを生成するとは限りません。 Py_BuildValue() は書式文字列中に書式単位が二つかそれ以上入っている場合にのみタプルを構築します。書式文字列が空なら、 None を返します。きっかり一つの書式単位なら、その書式単位が記述している何らかのオブジェクトになります。サイズが 0 や 1 のタプル返させたいのなら、書式文字列を丸括弧で囲います。

以下に例を示します (左に呼び出し例を、右に構築される Python 値を示します):

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

1.10. 参照カウント法

C や C++のような言語では、プログラマはヒープ上のメモリを動的に確保したり解放したりする責任があります。こうした作業は C では関数 malloc() や free() で行います。C++では本質的に同じ意味で演算子 new や delete が使われます。そこで、以下の議論は C の場合に限定して行います。

malloc() が確保する全てのメモリブロックは、最終的には free() を厳密に一度だけ呼び出して利用可能メモリのプールに戻さねばなりません。そこで、適切な時に free() を呼び出すことが重要になります。あるメモリブロックに対して、 free() を呼ばなかったにもかかわらずそのアドレスを忘却してしまうと、ブロックが占有しているメモリはプログラムが終了するまで再利用できなくなります。これはメモリリーク(memory leak) と呼ばれています。逆に、プログラムがあるメモリブロックに対して free() を呼んでおきながら、そのブロックを使い続けようとすると、別の malloc() 呼び出しによって行われるブロックの再利用と衝突を起こします。これは解放済みメモリの使用 (using freed memory) と呼ばれます。これは初期化されていないデータに対する参照と同様のよくない結果 --- コアダンプ、誤った参照、不可解なクラッシュ --- を引き起こします。

よくあるメモリリークの原因はコード中の普通でない処理経路です。例えば、ある関数があるメモリブロックを確保し、何らかの計算を行って、再度ブロックを解放するとします。さて、関数の要求仕様を変更して、計算に対するテストを追加すると、エラー条件を検出し、関数の途中で処理を戻すようになるかもしれません。この途中での終了が起きるとき、確保されたメモリブロックは解放し忘れやすいのです。コードが後で追加された場合には特にそうです。このようなメモリリークが一旦紛れ込んでしまうと、長い間検出されないままになることがよくあります: エラーによる関数の終了は、全ての関数呼び出しのに対してほんのわずかな割合しか起きず、その一方でほとんどの近代的な計算機は相当量の仮想記憶を持っているため、メモリリークが明らかになるのは、長い間動作していたプロセスがリークを起こす関数を何度も使った場合に限られるからです。従って、この種のエラーを最小限にとどめるようなコーディング規約や戦略を設けて、不慮のメモリリークを避けることが重要なのです。

Python は malloc() や free() を非常によく利用するため、メモリリークの防止に加え、解放されたメモリの使用を防止する戦略が必要です。このために選ばれたのが参照カウント法 (reference counting) と呼ばれる手法です。参照カウント法の原理は簡単です: 全てのオブジェクトにはカウンタがあり、オブジェクトに対する参照がどこかに保存されたらカウンタをインクリメントし、オブジェクトに対する参照が削除されたらデクリメントします。カウンタがゼロになったら、オブジェクトへの最後の参照が削除されたことになり、オブジェクトは解放されます。

もう一つの戦略は自動ガベージコレクション (automatic garbage collection) と呼ばれています。 (参照カウント法はガベージコレクション戦略の一つとして挙げられることもあるので、二つを区別するために筆者は "自動 (automatic)" を使っています。) 自動ガベージコレクションの大きな利点は、ユーザが free() を明示的によばなくてよいことにあります。 (速度やメモリの有効利用性も利点として主張されています --- が、これは確たる事実ではありません。) C における自動ガベージコレクションの欠点は、真に可搬性のあるガベージコレクタが存在しないということです。それに対し、参照カウント法は可搬性のある実装ができます (malloc() や free() を利用できるのが前提です --- C 標準はこれを保証しています)。いつの日か、十分可搬性のあるガベージコレクタが C で使えるようになるかもしれませんが、それまでは参照カウント法でやっていく以外にはないのです。

Python では、伝統的な参照カウント法の実装を行っている一方で、参照の循環を検出するために働く循環参照検出機構 (cycle detector) も提供しています。循環参照検出機構のおかげで、直接、間接にかかわらず循環参照の生成を気にせずにアプリケーションを構築できます; というのも、参照カウント法だけを使ったガベージコレクション実装にとって循環参照は弱点だからです。循環参照は、(間接参照の場合も含めて) 相互への参照が入ったオブジェクトから形成されるため、循環内のオブジェクトは各々非ゼロの参照カウントを持ちます。典型的な参照カウント法の実装では、たとえ循環参照を形成するオブジェクトに対して他に全く参照がないとしても、循環参照内のどのオブジェクトに属するメモリも再利用できません。

循環参照検出機構はそのようなガベージサイクル (前述したような循環参照オブジェクト) を検出して回収することができます。 gc モジュールそのような検出機構の実行 (collect() 関数) を提供するとともに、設定のためのインタフェースおよび検出機構を実行時に無効にする方法も提供しています。

1.10.1. Python における参照カウント法

Python には、参照カウントのインクリメントやデクリメントを処理する二つのマクロ、 Py_INCREF(x) と Py_DECREF(x) があります。 Py_DECREF() は、参照カウントがゼロに到達した際に、オブジェクトのメモリ解放も行います。柔軟性を持たせるために、 free() を直接呼び出しません --- その代わりにオブジェクトの型オブジェクト (type object) を介します。このために (他の目的もありますが)、全てのオブジェクトには自身の型オブジェクトに対するポインタが入っています。

さて、まだ重大な疑問が残っています: いつ Py_INCREF(x) や Py_DECREF(x) を使えばよいのでしょうか? まず、いくつかの用語説明から始めさせてください。まず、オブジェクトは "占有 (own)" されることはありません; しかし、あるオブジェクトに対する参照の所有 own a reference はできます。オブジェクトの参照カウントは、そのオブジェクトが参照の所有を受けている回数と定義されています。参照の所有者は、参照が必要なくなった際に Py_DECREF() を呼び出す役割を担います。参照の所有権は委譲 (transfer) できます。所有参照 (owned reference) の放棄には、渡す、保存する、 Py_DECREF() を呼び出す、という三つの方法があります。所有参照を処理し忘れると、メモリリークを引き起こします。

オブジェクトに対する参照は、借用 (borrow) も可能です。 [2] 参照の借用者は、 Py_DECREF() を呼んではなりません。借用者は、参照の所有者から借用した期間を超えて参照を保持し続けてはなりません。所有者が参照を放棄した後で借用参照を使うと、解放済みメモリを使用してしまう危険があるので、絶対に避けねばなりません。 [3]

参照の借用が参照の所有よりも優れている点は、コードがとりうるあらゆる処理経路で参照を廃棄しておくよう注意しなくて済むことです --- 別の言い方をすれば、借用参照の場合には、処理の途中で関数を終了してもメモリリークの危険を冒すことがない、ということです。逆に、所有よりも不利な点は、ごくまともに見えるコードが、実際には参照の借用元で放棄されてしまった後にその参照を使うかもしれないような微妙な状況があるということです。

Py_INCREF() を呼び出すと、借用参照を所有参照に変更できます。この操作は参照の借用元の状態には影響しません --- Py_INCREF() は新たな所有参照を生成し、参照の所有者が担うべき全ての責任を課します (つまり、新たな参照の所有者は、以前の所有者と同様、参照の放棄を適切に行わねばなりません)。

1.10.2. 所有権にまつわる規則

オブジェクトへの参照を関数の内外に渡す場合には、オブジェクトの所有権が参照と共に渡されるか否かが常に関数インターフェース仕様の一部となります。

オブジェクトへの参照を返すほとんどの関数は、参照とともに所有権も渡します。特に、 PyLong_FromLong() や Py_BuildValue() のように、新しいオブジェクトを生成する関数は全て所有権を相手に渡します。オブジェクトが実際には新たなオブジェクトでなくても、そのオブジェクトに対する新たな参照の所有権を得ます。例えば、 PyLong_FromLong() はよく使う値をキャッシュしており、キャッシュされた値への参照を返すことがあります。

PyObject_GetAttrString() のように、あるオブジェクトから別のオブジェクトを抽出するような関数もまた、参照とともに所有権を委譲します。こちらの方はやや理解しにくいかもしれません。というのはよく使われるルーチンのいくつかが例外となっているからです: PyTuple_GetItem() 、 PyList_GetItem() 、 PyDict_GetItem() 、および PyDict_GetItemString() は全て、タプル、リスト、または辞書から借用参照を返します。

PyImport_AddModule() は、実際にはオブジェクトを生成して返すことがあるにもかかわらず、借用参照を返します: これが可能なのは、生成されたオブジェクトに対する所有参照は sys.modules に保持されるからです。

オブジェクトへの参照を別の関数に渡す場合、一般的には、関数側は呼び出し手から参照を借用します --- 参照を保存する必要があるなら、関数側は Py_INCREF() を呼び出して独立した所有者になります。とはいえ、この規則には二つの重要な例外: PyTuple_SetItem() と PyList_SetItem() があります。これらの関数は、渡された引数要素に対して所有権を乗っ取り (take over) ます --- たとえ失敗してもです! (PyDict_SetItem() とその仲間は所有権を乗っ取りません --- これらはいわば "普通の" 関数です。)

Python から C 関数が呼び出される際には、C 関数は呼び出し側から引数への参照を借用します。C 関数の呼び出し側はオブジェクトへの参照を所有しているので、借用参照の生存期間が保証されるのは関数が処理を返すまでです。このようにして借用参照を保存したり他に渡したりしたい場合にのみ、 Py_INCREF() を使って所有参照にする必要があります。

Python から呼び出された C 関数が返す参照は所有参照でなければなりません --- 所有権は関数から呼び出し側へと委譲されます。

1.10.3. 薄氷

数少ない状況において、一見無害に見える借用参照の利用が問題をひきおこすことがあります。この問題はすべて、インタプリタが非明示的に呼び出され、インタプリタが参照の所有者に参照を放棄させてしまう状況と関係しています。

知っておくべきケースのうち最初の、そして最も重要なものは、リスト要素に対する参照を借りている際に起きる、関係ないオブジェクトに対する Py_DECREF() の使用です。例えば:

void
bug(PyObject *list)
{
    PyObject *item = PyList_GetItem(list, 0);

    PyList_SetItem(list, 1, PyLong_FromLong(0L));
    PyObject_Print(item, stdout, 0); /* BUG! */
}

上の関数はまず、 list[0] への参照を借用し、次に list[1] を値 0 で置き換え、最後にさきほど借用した参照を出力しています。何も問題ないように見えますね? でもそうではないのです!

Let's follow the control flow into 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 __del__() method. If this class instance has a reference count of 1, disposing of it will call its __del__() method.

Since it is written in Python, the __del__() method can execute arbitrary Python code. Could it perhaps do something to invalidate the reference to item in bug()? You bet! Assuming that the list passed into bug() is accessible to the __del__() method, it could execute a statement to the effect of del list[0], and assuming this was the last reference to that object, it would free the memory associated with it, thereby invalidating item.

問題の原因が分かれば、解決は簡単です。一時的に参照回数を増やせばよいのです。正しく動作するバージョンは以下のようになります:

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);
}

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 __del__() methods would fail...

二つ目は、借用参照がスレッドに関係しているケースです。通常は、 Python インタプリタにおける複数のスレッドは、グローバルインタプリタロックがオブジェクト空間全体を保護しているため、互いに邪魔し合うことはありません。とはいえ、ロックは Py_BEGIN_ALLOW_THREADS マクロで一時的に解除したり、 Py_END_ALLOW_THREADS で再獲得したりできます。これらのマクロはブロックの起こる I/O 呼び出しの周囲によく置かれ、 I/O が完了するまでの間に他のスレッドがプロセッサを利用できるようにします。明らかに、以下の関数は上の例と似た問題をはらんでいます:

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! */
}

1.10.4. NULL ポインタ

一般論として、オブジェクトへの参照を引数にとる関数はユーザが NULL ポインタを渡すとは予想しておらず、渡そうとするとコアダンプになる (か、あとでコアダンプを引き起こす) ことでしょう。一方、オブジェクトへの参照を返すような関数は一般に、例外の発生を示す場合にのみ NULL を返します。引数に対して NULL テストを行わない理由は、関数はしばしば受け取ったオブジェクトを他の関数へと引き渡すからです --- 各々の関数が NULL テストを行えば、冗長なテストが大量に行われ、コードはより低速に動くことになります。

従って、 NULL のテストはオブジェクトの "発生源"、すなわち値が NULL になるかもしれないポインタを受け取ったときだけにしましょう。 malloc() や、例外を送出する可能性のある関数がその例です。

マクロ Py_INCREF() および Py_DECREF() は NULL ポインタのチェックを行いません --- しかし、これらのマクロの変化形である Py_XINCREF() および Py_XDECREF() はチェックを行います。

特定のオブジェクト型について調べるマクロ (Pytype_Check()) は NULL ポインタのチェックを行いません --- 繰り返しますが、様々な異なる型を想定してオブジェクトの型を調べる際には、こうしたマクロを続けて呼び出す必要があるので、個別に NULL ポインタのチェックをすると冗長なテストになってしまうのです。型を調べるマクロには、 NULL チェックを行う変化形はありません。

Python から C 関数を呼び出す機構は、C 関数に渡される引数リスト (例でいうところの args) が決して NULL にならないよう保証しています --- 実際には、常にタプル型になるよう保証しています。[4]

NULL ポインタを Python ユーザレベルに "逃がし" てしまうと、深刻なエラーを引き起こします。

1.11. C++での拡張モジュール作成

C++でも拡張モジュールは作成できます。ただしいくつか制限があります。メインプログラム (Python インタプリタ) は C コンパイラでコンパイルされリンクされているので、グローバル変数や静的オブジェクトをコンストラクタで作成できません。メインプログラムが C++ コンパイラでリンクされているならこれは問題ではありません。 Python インタプリタから呼び出される関数 (特にモジュール初期化関数) は、 extern "C" を使って宣言しなければなりません。また、Python ヘッダファイルを extern "C" {...} に入れる必要はありません--- シンボル __cplusplus (最近の C++ コンパイラは全てこのシンボルを定義しています) が定義されているときに extern "C" {...} が行われるように、ヘッダファイル内にすでに書かれているからです。

1.12. 拡張モジュールに C API を提供する

多くの拡張モジュールは単に Python から使える新たな関数や型を提供するだけですが、時に拡張モジュール内のコードが他の拡張モジュールでも便利なことがあります。例えば、あるモジュールでは順序概念のないリストのように動作する "コレクション (collection)" クラスを実装しているかもしれません。ちょうどリストを生成したり操作したりできる C API を備えた標準の Python リスト型のように、この新たなコレクション型も他の拡張モジュールから直接操作できるようにするには一連の C 関数を持っていなければなりません。

一見するとこれは簡単なこと: 単に関数を (もちろん static などとは宣言せずに) 書いて、適切なヘッダファイルを提供し、C API を書けばよいだけ、に思えます。そして実際のところ、全ての拡張モジュールが Python インタプリタに常に静的にリンクされている場合にはうまく動作します。ところがモジュールが共有ライブラリの場合には、一つのモジュールで定義されているシンボルが他のモジュールから不可視なことがあります。可視性の詳細はオペレーティングシステムによります; あるシステムは Python インタプリタと全ての拡張モジュール用に単一のグローバルな名前空間を用意しています (例えば Windows)。別のシステムはモジュールのリンク時に取り込まれるシンボルを明示的に指定する必要があります (AIX がその一例です)、また別のシステム (ほとんどの Unix) では、違った戦略を選択肢として提供しています。そして、たとえシンボルがグローバル変数として可視であっても、呼び出したい関数の入ったモジュールがまだロードされていないことだってあります!

従って、可搬性の点からシンボルの可視性には何ら仮定をしてはならないことになります。つまり拡張モジュール中の全てのシンボルは static と宣言せねばなりません。例外はモジュールの初期化関数で、これは (モジュールのメソッドテーブルと初期化関数 で述べたように) 他の拡張モジュールとの間で名前が衝突するのを避けるためです。また、他の拡張モジュールからアクセスを 受けるべきではない シンボルは別のやり方で公開せねばなりません。

Python はある拡張モジュールの C レベルの情報 (ポインタ) を別のモジュールに渡すための特殊な機構: Capsule (カプセル)を提供しています。 Capsule はポインタ (void*) を記憶する Python のデータ型です。 Capsule は C API を介してのみ生成したりアクセスしたりできますが、他の Python オブジェクトと同じように受け渡しできます。とりわけ、Capsule は拡張モジュールの名前空間内にある名前に代入できます。他の拡張モジュールはこのモジュールを import でき、次に名前を取得し、最後にCapsule へのポインタを取得します。

拡張モジュールの C API を公開するために、様々な方法で Capsule が使われます。各関数を1つのオブジェクトに入れたり、全ての C API のポインタ配列を Capsule に入れることができます。そして、ポインタに対する保存や取得といった様々な作業は、コードを提供しているモジュールとクライアントモジュールとの間では異なる方法で分散できます。

どの方法を選ぶにしても、 Capsule の name を正しく設定することは重要です。 PyCapsule_New() は name 引数 (const char*) を取ります。 NULL を name に渡すことも許可されていますが、 name を設定することを強く推奨します。正しく名前を付けられた Capsule はある程度の実行時型安全性を持ちます。名前を付けられていない Capsule を他の Capsule と区別する現実的な方法はありません。

特に、 C API を公開するための Capsule には次のルールに従った名前を付けるべきです:

modulename.attributename

PyCapsule_Import() という便利関数は、 Capsule の名前がこのルールに一致しているときにのみ、簡単に Capsule 経由で公開されている C API をロードすることができます。この挙動により、 C API のユーザーが、確実に正しい C API を格納している Capsule をロードできたことを確かめることができます。

以下の例では、名前を公開するモジュールの作者にほとんどの負荷が掛かりますが、よく使われるライブラリを作る際に適切なアプローチを実演します。このアプローチでは、全ての C API ポインタ (例中では一つだけですが!) を、 Capsule の値となる void ポインタの配列に保存します。拡張モジュールに対応するヘッダファイルは、モジュールの import と C API ポインタを取得するよう手配するマクロを提供します; クライアントモジュールは、C API にアクセスする前にこのマクロを呼ぶだけです。

The exporting module is a modification of the spam module from section 簡単な例. The function spam.system() does not call the C library function system() directly, but a function PySpam_System(), which would of course do something more complicated in reality (such as adding "spam" to every command). This function PySpam_System() is also exported to other extension modules.

The function PySpam_System() is a plain C function, declared static like everything else:

static int
PySpam_System(const char *command)
{
    return system(command);
}

The function spam_system() is modified in a trivial way:

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);
}

モジュールの先頭にある以下の行

#include <Python.h>

の直後に、以下の二行を必ず追加してください:

#define SPAM_MODULE
#include "spammodule.h"

#define は、ファイル spammodule.h をインクルードしているのが名前を公開する側のモジュールであって、クライアントモジュールではないことをヘッダファイルに教えるために使われます。最後に、モジュールの初期化関数は C API のポインタ配列を初期化するよう手配しなければなりません:

PyMODINIT_FUNC
PyInit_spam(void)
{
    PyObject *m;
    static void *PySpam_API[PySpam_API_pointers];
    PyObject *c_api_object;

    m = PyModule_Create(&spammodule);
    if (m == NULL)
        return NULL;

    /* Initialize the C API pointer array */
    PySpam_API[PySpam_System_NUM] = (void *)PySpam_System;

    /* Create a Capsule containing the API pointer array's address */
    c_api_object = PyCapsule_New((void *)PySpam_API, "spam._C_API", NULL);

    if (PyModule_AddObject(m, "_C_API", c_api_object) < 0) {
        Py_XDECREF(c_api_object);
        Py_DECREF(m);
        return NULL;
    }

    return m;
}

Note that PySpam_API is declared static; otherwise the pointer array would disappear when PyInit_spam() terminates!

からくりの大部分はヘッダファイル spammodule.h 内にあり、以下のようになっています:

#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) */

All that a client module must do in order to have access to the function PySpam_System() is to call the function (or rather macro) import_spam() in its initialization function:

PyMODINIT_FUNC
PyInit_client(void)
{
    PyObject *m;

    m = PyModule_Create(&clientmodule);
    if (m == NULL)
        return NULL;
    if (import_spam() < 0)
        return NULL;
    /* additional initialization can happen here */
    return m;
}

このアプローチの主要な欠点は、 spammodule.h がやや難解になるということです。とはいえ、各関数の基本的な構成は公開されるものと同じなので、書き方を一度だけ学べばすみます。

最後に、Capsule は、自身に保存されているポインタをメモリ確保したり解放したりする際に特に便利な、もう一つの機能を提供しているということに触れておかねばなりません。詳細は Python/C API リファレンスマニュアルの カプセル, および Capsule の実装部分 (Python ソースコード配布物中のファイル Include/pycapsule.h および Objects/pycapsule.c に述べられています。

脚注

[1]

この関数へのインターフェースはすでに標準モジュール os にあります --- この関数を選んだのは、単純で直接的な例を示したいからです。

[2]

参照を "借用する" というメタファは厳密には正しくありません: なぜなら、参照の所有者は依然として参照のコピーを持っているからです。

[3]

参照カウントが 1 以上かどうか調べる方法は うまくいきません --- 参照カウント自体も解放されたメモリ上にあるため、その領域が他のオブジェクトに使われている可能性があります!

[4]

"旧式の" 呼び出し規約を使っている場合には、この保証は適用されません --- 既存のコードにはいまだに旧式の呼び出し規約が多々あります。

2. 拡張の型の定義: チュートリアル

Python では、組み込みの str 型や list 型のような Python コードから操作できる新しい型を C 拡張モジュールの作者が定義できます。全ての拡張の型のコードはあるパターンに従うのですが、書き始める前に理解しておくべき細かいことがあります。このドキュメントはその話題についてのやさしい入門です。

2.1. 基本的なこと

The CPython runtime sees all Python objects as variables of type PyObject*, which serves as a "base type" for all Python objects. The PyObject structure itself only contains the object's 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".

それなので、新しい拡張の型を定義したいときは、新しい型オブジェクトを作成すればよいわけです。

This sort of thing can only be explained by example, so here's a minimal, but complete, module that defines a new type named Custom inside a C extension module custom:

注釈

ここで紹介している例は、 静的な 拡張の型を定義する伝統的な実装方法です。これはほとんどの場面で十分なものなのです。 C API では、 PyType_FromSpec() 関数を使い、ヒープ上に配置された拡張の型も定義できますが、これについてはこのチュートリアルでは扱いません。

#define PY_SSIZE_T_CLEAN
#include <Python.h>

typedef struct {
    PyObject_HEAD
    /* Type-specific fields go here. */
} CustomObject;

static PyTypeObject CustomType = {
    .ob_base = PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "custom.Custom",
    .tp_doc = PyDoc_STR("Custom objects"),
    .tp_basicsize = sizeof(CustomObject),
    .tp_itemsize = 0,
    .tp_flags = Py_TPFLAGS_DEFAULT,
    .tp_new = PyType_GenericNew,
};

static PyModuleDef custommodule = {
    .m_base = PyModuleDef_HEAD_INIT,
    .m_name = "custom",
    .m_doc = "Example module that creates an extension type.",
    .m_size = -1,
};

PyMODINIT_FUNC
PyInit_custom(void)
{
    PyObject *m;
    if (PyType_Ready(&CustomType) < 0)
        return NULL;

    m = PyModule_Create(&custommodule);
    if (m == NULL)
        return NULL;

    Py_INCREF(&CustomType);
    if (PyModule_AddObject(m, "Custom", (PyObject *) &CustomType) < 0) {
        Py_DECREF(&CustomType);
        Py_DECREF(m);
        return NULL;
    }

    return m;
}

一度に把握するにはちょっと量が多いですが、前の章よりはとっつきやすくなっていることと思います。このファイルでは、3つの要素が定義されています:

What a Custom object contains: this is the CustomObject struct, which is allocated once for each Custom instance.

How the Custom type behaves: this is the CustomType struct, which defines a set of flags and function pointers that the interpreter inspects when specific operations are requested.

How to initialize the custom module: this is the PyInit_custom function and the associated custommodule struct.

まず最初はこれです:

typedef struct {
    PyObject_HEAD
} CustomObject;

This is what a Custom object will contain. PyObject_HEAD is mandatory at the start of each object struct and defines a field called ob_base of type PyObject, containing a pointer to a type object and a reference count (these can be accessed using the macros Py_TYPE and Py_REFCNT respectively). The reason for the macro is to abstract away the layout and to enable additional fields in debug builds.

注釈

上の例では PyObject_HEAD マクロの後にセミコロンはありません。うっかりセミコロンを追加しないように気を付けてください: これを警告するコンパイラもあります。

もちろん、一般的にはオブジェクトは標準的な PyObject_HEAD ボイラープレートの他にもデータを保持しています; 例えば、これは Python 標準の浮動小数点数の定義です:

typedef struct {
    PyObject_HEAD
    double ob_fval;
} PyFloatObject;

2つ目は型オブジェクトの定義です。

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,
};

注釈

上にあるように C99 スタイルの指示付き初期化子を使って、 PyTypeObject の特に関心の無いフィールドまで全て並べたり、フィールドを宣言する順序に気を使ったりせずに済ませるのをお薦めします。

object.h にある実際の PyTypeObject の定義には上の定義にあるよりももっと多くの フィールド があります。ここに出てきていないフィールドは C コンパイラによってゼロで埋められるので、必要でない限り明示的には値の指定をしないのが一般的な作法になっています。

一度に1つずつフィールドを取り上げていきましょう:

.ob_base = PyVarObject_HEAD_INIT(NULL, 0)

この行は、上で触れた ob_base フィールドの初期化に必須のボイラープレートです。

.tp_name = "custom.Custom",

実装している型の名前です。これは、オブジェクトのデフォルトの文字列表現やエラーメッセージに現れます。例えば次の通りです:

>>> "" + custom.Custom()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: can only concatenate str (not "custom.Custom") to str

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 custom and the type is Custom, so we set the type name to custom.Custom. Using the real dotted import path is important to make your type compatible with the pydoc and pickle modules.

.tp_basicsize = sizeof(CustomObject),
.tp_itemsize = 0,

This is so that Python knows how much memory to allocate when creating new Custom instances. tp_itemsize is only used for variable-sized objects and should otherwise be zero.

注釈

If you want your type to be subclassable from Python, and your type has the same 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 __bases__, or else it will not be able to call your type's __new__() method without getting an error. You can avoid this problem by ensuring that your type has a larger value for tp_basicsize than its base type does. Most of the time, this will be true anyway, because either your base type will be object, or else you will be adding data members to your base type, and therefore increasing its size.

We set the class flags to Py_TPFLAGS_DEFAULT.

.tp_flags = Py_TPFLAGS_DEFAULT,

すべての型はフラグにこの定数を含めておく必要があります。これは最低でも Python 3.3 までに定義されているすべてのメンバを許可します。それ以上のメンバが必要なら、対応するフラグの OR をとる必要があります。

この型の docstring は tp_doc に入れます。

.tp_doc = PyDoc_STR("Custom objects"),

To enable object creation, we have to provide a tp_new handler. This is the equivalent of the Python method __new__(), but has to be specified explicitly. In this case, we can just use the default implementation provided by the API function PyType_GenericNew().

.tp_new = PyType_GenericNew,

Everything else in the file should be familiar, except for some code in PyInit_custom():

if (PyType_Ready(&CustomType) < 0)
    return;

This initializes the Custom type, filling in a number of members to the appropriate default values, including ob_type that we initially set to NULL.

Py_INCREF(&CustomType);
if (PyModule_AddObject(m, "Custom", (PyObject *) &CustomType) < 0) {
    Py_DECREF(&CustomType);
    Py_DECREF(m);
    return NULL;
}

This adds the type to the module dictionary. This allows us to create Custom instances by calling the Custom class:

>>> import custom
>>> mycustom = custom.Custom()

That's it! All that remains is to build it; put the above code in a file called custom.c,

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

[project]
name = "custom"
version = "1"

in a file called pyproject.toml, and

from setuptools import Extension, setup
setup(ext_modules=[Extension("custom", ["custom.c"])])

そして、シェルから以下のように入力します

$ python -m pip install .

in a shell should produce a file custom.so in a subdirectory and install it; now fire up Python --- you should be able to import custom and play around with Custom objects.

そんなにむずかしくありません、よね?

もちろん、現在の Custom 型は面白みに欠けています。何もデータを持っていないし、何もできません。継承してサブクラスを作ることさえできないのです。

2.2. 基本のサンプルにデータとメソッドを追加する

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, custom2 that adds these capabilities:

#define PY_SSIZE_T_CLEAN
#include <Python.h>
#include <stddef.h> /* for offsetof() */

typedef struct {
    PyObject_HEAD
    PyObject *first; /* first name */
    PyObject *last;  /* last name */
    int number;
} CustomObject;

static void
Custom_dealloc(CustomObject *self)
{
    Py_XDECREF(self->first);
    Py_XDECREF(self->last);
    Py_TYPE(self)->tp_free((PyObject *) self);
}

static PyObject *
Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
{
    CustomObject *self;
    self = (CustomObject *) type->tp_alloc(type, 0);
    if (self != NULL) {
        self->first = PyUnicode_FromString("");
        if (self->first == NULL) {
            Py_DECREF(self);
            return NULL;
        }
        self->last = PyUnicode_FromString("");
        if (self->last == NULL) {
            Py_DECREF(self);
            return NULL;
        }
        self->number = 0;
    }
    return (PyObject *) self;
}

static int
Custom_init(CustomObject *self, PyObject *args, PyObject *kwds)
{
    static char *kwlist[] = {"first", "last", "number", NULL};
    PyObject *first = NULL, *last = NULL;

    if (!PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist,
                                     &first, &last,
                                     &self->number))
        return -1;

    if (first) {
        Py_XSETREF(self->first, Py_NewRef(first));
    }
    if (last) {
        Py_XSETREF(self->last, Py_NewRef(last));
    }
    return 0;
}

static PyMemberDef Custom_members[] = {
    {"first", Py_T_OBJECT_EX, offsetof(CustomObject, first), 0,
     "first name"},
    {"last", Py_T_OBJECT_EX, offsetof(CustomObject, last), 0,
     "last name"},
    {"number", Py_T_INT, offsetof(CustomObject, number), 0,
     "custom number"},
    {NULL}  /* Sentinel */
};

static PyObject *
Custom_name(CustomObject *self, PyObject *Py_UNUSED(ignored))
{
    if (self->first == NULL) {
        PyErr_SetString(PyExc_AttributeError, "first");
        return NULL;
    }
    if (self->last == NULL) {
        PyErr_SetString(PyExc_AttributeError, "last");
        return NULL;
    }
    return PyUnicode_FromFormat("%S %S", self->first, self->last);
}

static PyMethodDef Custom_methods[] = {
    {"name", (PyCFunction) Custom_name, METH_NOARGS,
     "Return the name, combining the first and last name"
    },
    {NULL}  /* Sentinel */
};

static PyTypeObject CustomType = {
    .ob_base = PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "custom2.Custom",
    .tp_doc = PyDoc_STR("Custom objects"),
    .tp_basicsize = sizeof(CustomObject),
    .tp_itemsize = 0,
    .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,
    .tp_new = Custom_new,
    .tp_init = (initproc) Custom_init,
    .tp_dealloc = (destructor) Custom_dealloc,
    .tp_members = Custom_members,
    .tp_methods = Custom_methods,
};

static PyModuleDef custommodule = {
    .m_base =PyModuleDef_HEAD_INIT,
    .m_name = "custom2",
    .m_doc = "Example module that creates an extension type.",
    .m_size = -1,
};

PyMODINIT_FUNC
PyInit_custom2(void)
{
    PyObject *m;
    if (PyType_Ready(&CustomType) < 0)
        return NULL;

    m = PyModule_Create(&custommodule);
    if (m == NULL)
        return NULL;

    if (PyModule_AddObjectRef(m, "Custom", (PyObject *) &CustomType) < 0) {
        Py_DECREF(m);
        return NULL;
    }

    return m;
}

このバージョンでは、いくつもの変更をおこないます。

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

これにしたがうと、オブジェクトの構造体は次のようになります:

typedef struct {
    PyObject_HEAD
    PyObject *first; /* first name */
    PyObject *last;  /* last name */
    int number;
} CustomObject;

いまや管理すべきデータができたので、オブジェクトの割り当てと解放に際してはより慎重になる必要があります。最低限、オブジェクトの解放メソッドが必要です:

static void
Custom_dealloc(CustomObject *self)
{
    Py_XDECREF(self->first);
    Py_XDECREF(self->last);
    Py_TYPE(self)->tp_free((PyObject *) self);
}

この関数は tp_dealloc メンバに代入されます。

.tp_dealloc = (destructor) Custom_dealloc,

This method first clears the reference counts of the two Python attributes. Py_XDECREF() correctly handles the case where its argument is NULL (which might happen here if tp_new failed midway). It then calls the tp_free member of the object's type (computed by Py_TYPE(self)) to free the object's memory. Note that the object's type might not be CustomType, because the object may be an instance of a subclass.

注釈

上の destructor への明示的な型変換は必要です。なぜなら、 Custom_dealloc が CustomObject * 引数をとると定義しましたが、 tp_dealloc 関数のポインタは PyObject * 引数を受け取ることになっているからです。もし明示的に型変換をしなければ、コンパイラが警告を発するでしょう。これは、Cにおけるオブジェクト指向のポリモーフィズムです！

ファーストネームとラストネームを空文字列に初期化しておきたいので、tp_new の実装を追加することにしましょう:

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;
}

そしてこれを tp_new メンバとしてインストールします:

.tp_new = Custom_new,

The tp_new handler is responsible for creating (as opposed to initializing) objects of the type. It is exposed in Python as the __new__() method. It is not required to define a tp_new member, and indeed many extension types will simply reuse PyType_GenericNew() as done in the first version of the Custom type above. In this case, we use the tp_new handler to initialize the first and last attributes to non-NULL default values.

tp_new is passed the type being instantiated (not necessarily CustomType, if a subclass is instantiated) and any arguments passed when the type was called, and is expected to return the instance created. tp_new handlers always accept positional and keyword arguments, but they often ignore the arguments, leaving the argument handling to initializer (a.k.a. tp_init in C or __init__ in Python) methods.

注釈

tp_new は明示的に tp_init を呼び出してはいけません、これはインタープリタが自分で行うためです。

この tp_new の実装は、tp_alloc スロットを呼び出してメモリを割り当てます:

self = (CustomObject *) type->tp_alloc(type, 0);

Since memory allocation may fail, we must check the tp_alloc result against NULL before proceeding.

注釈

We didn't fill the tp_alloc slot ourselves. Rather PyType_Ready() fills it for us by inheriting it from our base class, which is object by default. Most types use the default allocation strategy.

注釈

If you are creating a co-operative tp_new (one that calls a base type's tp_new or __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 tp_new directly, or via 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 TypeError.)

We also define an initialization function which accepts arguments to provide initial values for our instance:

static int
Custom_init(CustomObject *self, PyObject *args, PyObject *kwds)
{
    static char *kwlist[] = {"first", "last", "number", NULL};
    PyObject *first = NULL, *last = NULL, *tmp;

    if (!PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist,
                                     &first, &last,
                                     &self->number))
        return -1;

    if (first) {
        tmp = self->first;
        Py_INCREF(first);
        self->first = first;
        Py_XDECREF(tmp);
    }
    if (last) {
        tmp = self->last;
        Py_INCREF(last);
        self->last = last;
        Py_XDECREF(tmp);
    }
    return 0;
}

これは tp_init メンバに代入されます。

.tp_init = (initproc) Custom_init,

The tp_init slot is exposed in Python as the __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 0 on success or -1 on error.

Unlike the tp_new handler, there is no guarantee that tp_init is called at all (for example, the pickle module by default doesn't call __init__() on unpickled instances). It can also be called multiple times. Anyone can call the __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 first member like this:

if (first) {
    Py_XDECREF(self->first);
    Py_INCREF(first);
    self->first = first;
}

But this would be risky. Our type doesn't restrict the type of the 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 first member; or that destructor could release the Global interpreter Lock 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?

その参照カウントが 1 より大きいと確信できる場合

when we know that deallocation of the object [1] will neither release the GIL nor cause any calls back into our type's code;

when decrementing a reference count in a tp_dealloc handler on a type which doesn't support cyclic garbage collection [2].

ここではインスタンス変数を属性として見えるようにしたいのですが、これにはいくつもの方法があります。もっとも簡単な方法は、メンバの定義を与えることです:

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 */
};

そして、この定義を tp_members スロットに入れましょう:

.tp_members = Custom_members,

Each member definition has a member name, type, offset, access flags and documentation string. See the 総称的な属性を管理する 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 NULL. Even though we can make sure the members are initialized to non-NULL values, the members can be set to NULL if the attributes are deleted.

We define a single method, Custom.name(), that outputs the objects name as the concatenation of the first and last names.

static PyObject *
Custom_name(CustomObject *self, PyObject *Py_UNUSED(ignored))
{
    if (self->first == NULL) {
        PyErr_SetString(PyExc_AttributeError, "first");
        return NULL;
    }
    if (self->last == NULL) {
        PyErr_SetString(PyExc_AttributeError, "last");
        return NULL;
    }
    return PyUnicode_FromFormat("%S %S", self->first, self->last);
}

The method is implemented as a C function that takes a Custom (or 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:

def name(self):
    return "%s %s" % (self.first, self.last)

Note that we have to check for the possibility that our first and last members are NULL. This is because they can be deleted, in which case they are set to 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.

さて、メソッドを定義したので、ここでメソッド定義用の配列を作成する必要があります:

static PyMethodDef Custom_methods[] = {
    {"name", (PyCFunction) Custom_name, METH_NOARGS,
     "Return the name, combining the first and last name"
    },
    {NULL}  /* Sentinel */
};

(note that we used the METH_NOARGS flag to indicate that the method is expecting no arguments other than self)

and assign it to the tp_methods slot:

.tp_methods = Custom_methods,

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 Py_TPFLAGS_BASETYPE to our class flag definition:

.tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,

We rename PyInit_custom() to PyInit_custom2(), update the module name in the PyModuleDef struct, and update the full class name in the PyTypeObject struct.

Finally, we update our setup.py file to include the new module,

from setuptools import Extension, setup
setup(ext_modules=[
    Extension("custom", ["custom.c"]),
    Extension("custom2", ["custom2.c"]),
])

and then we re-install so that we can import custom2:

$ python -m pip install .

2.3. データ属性をこまかく制御する

In this section, we'll provide finer control over how the first and last attributes are set in the Custom example. In the previous version of our module, the instance variables first and last could be set to non-string values or even deleted. We want to make sure that these attributes always contain strings.

#define PY_SSIZE_T_CLEAN
#include <Python.h>
#include <stddef.h> /* for offsetof() */

typedef struct {
    PyObject_HEAD
    PyObject *first; /* first name */
    PyObject *last;  /* last name */
    int number;
} CustomObject;

static void
Custom_dealloc(CustomObject *self)
{
    Py_XDECREF(self->first);
    Py_XDECREF(self->last);
    Py_TYPE(self)->tp_free((PyObject *) self);
}

static PyObject *
Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
{
    CustomObject *self;
    self = (CustomObject *) type->tp_alloc(type, 0);
    if (self != NULL) {
        self->first = PyUnicode_FromString("");
        if (self->first == NULL) {
            Py_DECREF(self);
            return NULL;
        }
        self->last = PyUnicode_FromString("");
        if (self->last == NULL) {
            Py_DECREF(self);
            return NULL;
        }
        self->number = 0;
    }
    return (PyObject *) self;
}

static int
Custom_init(CustomObject *self, PyObject *args, PyObject *kwds)
{
    static char *kwlist[] = {"first", "last", "number", NULL};
    PyObject *first = NULL, *last = NULL;

    if (!PyArg_ParseTupleAndKeywords(args, kwds, "|UUi", kwlist,
                                     &first, &last,
                                     &self->number))
        return -1;

    if (first) {
        Py_SETREF(self->first, Py_NewRef(first));
    }
    if (last) {
        Py_SETREF(self->last, Py_NewRef(last));
    }
    return 0;
}

static PyMemberDef Custom_members[] = {
    {"number", Py_T_INT, offsetof(CustomObject, number), 0,
     "custom number"},
    {NULL}  /* Sentinel */
};

static PyObject *
Custom_getfirst(CustomObject *self, void *closure)
{
    return Py_NewRef(self->first);
}

static int
Custom_setfirst(CustomObject *self, PyObject *value, void *closure)
{
    if (value == NULL) {
        PyErr_SetString(PyExc_TypeError, "Cannot delete the first attribute");
        return -1;
    }
    if (!PyUnicode_Check(value)) {
        PyErr_SetString(PyExc_TypeError,
                        "The first attribute value must be a string");
        return -1;
    }
    Py_SETREF(self->first, Py_NewRef(value));
    return 0;
}

static PyObject *
Custom_getlast(CustomObject *self, void *closure)
{
    return Py_NewRef(self->last);
}

static int
Custom_setlast(CustomObject *self, PyObject *value, void *closure)
{
    if (value == NULL) {
        PyErr_SetString(PyExc_TypeError, "Cannot delete the last attribute");
        return -1;
    }
    if (!PyUnicode_Check(value)) {
        PyErr_SetString(PyExc_TypeError,
                        "The last attribute value must be a string");
        return -1;
    }
    Py_SETREF(self->last, Py_NewRef(value));
    return 0;
}

static PyGetSetDef Custom_getsetters[] = {
    {"first", (getter) Custom_getfirst, (setter) Custom_setfirst,
     "first name", NULL},
    {"last", (getter) Custom_getlast, (setter) Custom_setlast,
     "last name", NULL},
    {NULL}  /* Sentinel */
};

static PyObject *
Custom_name(CustomObject *self, PyObject *Py_UNUSED(ignored))
{
    return PyUnicode_FromFormat("%S %S", self->first, self->last);
}

static PyMethodDef Custom_methods[] = {
    {"name", (PyCFunction) Custom_name, METH_NOARGS,
     "Return the name, combining the first and last name"
    },
    {NULL}  /* Sentinel */
};

static PyTypeObject CustomType = {
    .ob_base = PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "custom3.Custom",
    .tp_doc = PyDoc_STR("Custom objects"),
    .tp_basicsize = sizeof(CustomObject),
    .tp_itemsize = 0,
    .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,
    .tp_new = Custom_new,
    .tp_init = (initproc) Custom_init,
    .tp_dealloc = (destructor) Custom_dealloc,
    .tp_members = Custom_members,
    .tp_methods = Custom_methods,
    .tp_getset = Custom_getsetters,
};

static PyModuleDef custommodule = {
    .m_base = PyModuleDef_HEAD_INIT,
    .m_name = "custom3",
    .m_doc = "Example module that creates an extension type.",
    .m_size = -1,
};

PyMODINIT_FUNC
PyInit_custom3(void)
{
    PyObject *m;
    if (PyType_Ready(&CustomType) < 0)
        return NULL;

    m = PyModule_Create(&custommodule);
    if (m == NULL)
        return NULL;

    if (PyModule_AddObjectRef(m, "Custom", (PyObject *) &CustomType) < 0) {
        Py_DECREF(m);
        return NULL;
    }

    return m;
}

To provide greater control, over the first and last attributes, we'll use custom getter and setter functions. Here are the functions for getting and setting the first attribute:

static PyObject *
Custom_getfirst(CustomObject *self, void *closure)
{
    Py_INCREF(self->first);
    return self->first;
}

static int
Custom_setfirst(CustomObject *self, PyObject *value, void *closure)
{
    PyObject *tmp;
    if (value == NULL) {
        PyErr_SetString(PyExc_TypeError, "Cannot delete the first attribute");
        return -1;
    }
    if (!PyUnicode_Check(value)) {
        PyErr_SetString(PyExc_TypeError,
                        "The first attribute value must be a string");
        return -1;
    }
    tmp = self->first;
    Py_INCREF(value);
    self->first = value;
    Py_DECREF(tmp);
    return 0;
}

The getter function is passed a 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 Custom object, the new value, and the closure. The new value may be 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.

ここでは PyGetSetDef 構造体の配列をつくります:

static PyGetSetDef Custom_getsetters[] = {
    {"first", (getter) Custom_getfirst, (setter) Custom_setfirst,
     "first name", NULL},
    {"last", (getter) Custom_getlast, (setter) Custom_setlast,
     "last name", NULL},
    {NULL}  /* Sentinel */
};

そしてこれを tp_getset スロットに登録します:

.tp_getset = Custom_getsetters,

The last item in a PyGetSetDef structure is the "closure" mentioned above. In this case, we aren't using a closure, so we just pass NULL.

また、メンバ定義からはこれらの属性を除いておきましょう:

static PyMemberDef Custom_members[] = {
    {"number", Py_T_INT, offsetof(CustomObject, number), 0,
     "custom number"},
    {NULL}  /* Sentinel */
};

また、ここでは tp_init ハンドラも渡されるものとして文字列のみを許可するように修正する必要があります [3]:

static int
Custom_init(CustomObject *self, PyObject *args, PyObject *kwds)
{
    static char *kwlist[] = {"first", "last", "number", NULL};
    PyObject *first = NULL, *last = NULL, *tmp;

    if (!PyArg_ParseTupleAndKeywords(args, kwds, "|UUi", kwlist,
                                     &first, &last,
                                     &self->number))
        return -1;

    if (first) {
        tmp = self->first;
        Py_INCREF(first);
        self->first = first;
        Py_DECREF(tmp);
    }
    if (last) {
        tmp = self->last;
        Py_INCREF(last);
        self->last = last;
        Py_DECREF(tmp);
    }
    return 0;
}

With these changes, we can assure that the first and last members are never NULL so we can remove checks for NULL values in almost all cases. This means that most of the Py_XDECREF() calls can be converted to Py_DECREF() calls. The only place we can't change these calls is in the tp_dealloc implementation, where there is the possibility that the initialization of these members failed in tp_new.

さて、先ほどもしたように、このモジュール初期化関数と初期化関数内にあるモジュール名を変更しましょう。そして setup.py ファイルに追加の定義をくわえます。

2.4. 循環ガベージコレクションをサポートする

Python は 循環ガベージコレクタ (GC) 機能 をもっており、これは不要なオブジェクトを、たとえ参照カウントがゼロでなくても発見することができます。そのような状況はオブジェクトの参照が循環しているときに起こりえます。たとえば以下の例を考えてください:

>>> l = []
>>> l.append(l)
>>> del l

この例では、自分自身をふくむリストを作りました。たとえこのリストを 削除しても、それは自分自身への参照をまだ持ちつづけますから、参照カウントはゼロにはなりません。嬉しいことに Python には循環ガベージコレクタは最終的にはこのリストが不要であることを検出し、解放できます。

In the second version of the Custom example, we allowed any kind of object to be stored in the first or last attributes [4]. Besides, in the second and third versions, we allowed subclassing Custom, and subclasses may add arbitrary attributes. For any of those two reasons, Custom objects can participate in cycles:

>>> import custom3
>>> class Derived(custom3.Custom): pass
...
>>> n = Derived()
>>> n.some_attribute = n

To allow a Custom instance participating in a reference cycle to be properly detected and collected by the cyclic GC, our Custom type needs to fill two additional slots and to enable a flag that enables these slots:

#define PY_SSIZE_T_CLEAN
#include <Python.h>
#include <stddef.h> /* for offsetof() */

typedef struct {
    PyObject_HEAD
    PyObject *first; /* first name */
    PyObject *last;  /* last name */
    int number;
} CustomObject;

static int
Custom_traverse(CustomObject *self, visitproc visit, void *arg)
{
    Py_VISIT(self->first);
    Py_VISIT(self->last);
    return 0;
}

static int
Custom_clear(CustomObject *self)
{
    Py_CLEAR(self->first);
    Py_CLEAR(self->last);
    return 0;
}

static void
Custom_dealloc(CustomObject *self)
{
    PyObject_GC_UnTrack(self);
    Custom_clear(self);
    Py_TYPE(self)->tp_free((PyObject *) self);
}

static PyObject *
Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
{
    CustomObject *self;
    self = (CustomObject *) type->tp_alloc(type, 0);
    if (self != NULL) {
        self->first = PyUnicode_FromString("");
        if (self->first == NULL) {
            Py_DECREF(self);
            return NULL;
        }
        self->last = PyUnicode_FromString("");
        if (self->last == NULL) {
            Py_DECREF(self);
            return NULL;
        }
        self->number = 0;
    }
    return (PyObject *) self;
}

static int
Custom_init(CustomObject *self, PyObject *args, PyObject *kwds)
{
    static char *kwlist[] = {"first", "last", "number", NULL};
    PyObject *first = NULL, *last = NULL;

    if (!PyArg_ParseTupleAndKeywords(args, kwds, "|UUi", kwlist,
                                     &first, &last,
                                     &self->number))
        return -1;

    if (first) {
        Py_SETREF(self->first, Py_NewRef(first));
    }
    if (last) {
        Py_SETREF(self->last, Py_NewRef(last));
    }
    return 0;
}

static PyMemberDef Custom_members[] = {
    {"number", Py_T_INT, offsetof(CustomObject, number), 0,
     "custom number"},
    {NULL}  /* Sentinel */
};

static PyObject *
Custom_getfirst(CustomObject *self, void *closure)
{
    return Py_NewRef(self->first);
}

static int
Custom_setfirst(CustomObject *self, PyObject *value, void *closure)
{
    if (value == NULL) {
        PyErr_SetString(PyExc_TypeError, "Cannot delete the first attribute");
        return -1;
    }
    if (!PyUnicode_Check(value)) {
        PyErr_SetString(PyExc_TypeError,
                        "The first attribute value must be a string");
        return -1;
    }
    Py_XSETREF(self->first, Py_NewRef(value));
    return 0;
}

static PyObject *
Custom_getlast(CustomObject *self, void *closure)
{
    return Py_NewRef(self->last);
}

static int
Custom_setlast(CustomObject *self, PyObject *value, void *closure)
{
    if (value == NULL) {
        PyErr_SetString(PyExc_TypeError, "Cannot delete the last attribute");
        return -1;
    }
    if (!PyUnicode_Check(value)) {
        PyErr_SetString(PyExc_TypeError,
                        "The last attribute value must be a string");
        return -1;
    }
    Py_XSETREF(self->last, Py_NewRef(value));
    return 0;
}

static PyGetSetDef Custom_getsetters[] = {
    {"first", (getter) Custom_getfirst, (setter) Custom_setfirst,
     "first name", NULL},
    {"last", (getter) Custom_getlast, (setter) Custom_setlast,
     "last name", NULL},
    {NULL}  /* Sentinel */
};

static PyObject *
Custom_name(CustomObject *self, PyObject *Py_UNUSED(ignored))
{
    return PyUnicode_FromFormat("%S %S", self->first, self->last);
}

static PyMethodDef Custom_methods[] = {
    {"name", (PyCFunction) Custom_name, METH_NOARGS,
     "Return the name, combining the first and last name"
    },
    {NULL}  /* Sentinel */
};

static PyTypeObject CustomType = {
    .ob_base = PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "custom4.Custom",
    .tp_doc = PyDoc_STR("Custom objects"),
    .tp_basicsize = sizeof(CustomObject),
    .tp_itemsize = 0,
    .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC,
    .tp_new = Custom_new,
    .tp_init = (initproc) Custom_init,
    .tp_dealloc = (destructor) Custom_dealloc,
    .tp_traverse = (traverseproc) Custom_traverse,
    .tp_clear = (inquiry) Custom_clear,
    .tp_members = Custom_members,
    .tp_methods = Custom_methods,
    .tp_getset = Custom_getsetters,
};

static PyModuleDef custommodule = {
    .m_base = PyModuleDef_HEAD_INIT,
    .m_name = "custom4",
    .m_doc = "Example module that creates an extension type.",
    .m_size = -1,
};

PyMODINIT_FUNC
PyInit_custom4(void)
{
    PyObject *m;
    if (PyType_Ready(&CustomType) < 0)
        return NULL;

    m = PyModule_Create(&custommodule);
    if (m == NULL)
        return NULL;

    if (PyModule_AddObjectRef(m, "Custom", (PyObject *) &CustomType) < 0) {
        Py_DECREF(m);
        return NULL;
    }

    return m;
}

First, the traversal method lets the cyclic GC know about subobjects that could participate in cycles:

static int
Custom_traverse(CustomObject *self, visitproc visit, void *arg)
{
    int vret;
    if (self->first) {
        vret = visit(self->first, arg);
        if (vret != 0)
            return vret;
    }
    if (self->last) {
        vret = visit(self->last, arg);
        if (vret != 0)
            return vret;
    }
    return 0;
}

For each subobject that can participate in cycles, we need to call the visit() function, which is passed to the traversal method. The 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 Py_VISIT() macro that automates calling visit functions. With Py_VISIT(), we can minimize the amount of boilerplate in Custom_traverse:

static int
Custom_traverse(CustomObject *self, visitproc visit, void *arg)
{
    Py_VISIT(self->first);
    Py_VISIT(self->last);
    return 0;
}

注釈

The tp_traverse implementation must name its arguments exactly visit and arg in order to use Py_VISIT().

Second, we need to provide a method for clearing any subobjects that can participate in cycles:

static int
Custom_clear(CustomObject *self)
{
    Py_CLEAR(self->first);
    Py_CLEAR(self->last);
    return 0;
}

Notice the use of the 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 Py_XDECREF() instead on the attribute before setting it to 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).

注釈

You could emulate Py_CLEAR() by writing:

PyObject *tmp;
tmp = self->first;
self->first = NULL;
Py_XDECREF(tmp);

Nevertheless, it is much easier and less error-prone to always use Py_CLEAR() when deleting an attribute. Don't try to micro-optimize at the expense of robustness!

The deallocator 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 PyObject_GC_UnTrack() before clearing members. Here is our reimplemented deallocator using PyObject_GC_UnTrack() and Custom_clear:

static void
Custom_dealloc(CustomObject *self)
{
    PyObject_GC_UnTrack(self);
    Custom_clear(self);
    Py_TYPE(self)->tp_free((PyObject *) self);
}

Finally, we add the Py_TPFLAGS_HAVE_GC flag to the class flags:

.tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC,

これで完了です。 tp_alloc スロットまたは tp_free ハンドラが書かれていれば、それらを循環ガベージコレクションに使えるよう修正すればよいのです。ほとんどの拡張機能は自動的に提供されるバージョンを使うでしょう。

2.5. 他の型のサブクラスを作る

既存の型を継承した新しい拡張型を作成することができます。組み込み型から継承するのは特に簡単です。必要な PyTypeObject を簡単に利用できるからです。それに比べて、 PyTypeObject 構造体を拡張モジュール間で共有するのは難しいです。

In this example we will create a SubList type that inherits from the built-in list type. The new type will be completely compatible with regular lists, but will have an additional increment() method that increases an internal counter:

>>> import sublist
>>> s = sublist.SubList(range(3))
>>> s.extend(s)
>>> print(len(s))
6
>>> print(s.increment())
1
>>> print(s.increment())
2

#define PY_SSIZE_T_CLEAN
#include <Python.h>

typedef struct {
    PyListObject list;
    int state;
} SubListObject;

static PyObject *
SubList_increment(SubListObject *self, PyObject *unused)
{
    self->state++;
    return PyLong_FromLong(self->state);
}

static PyMethodDef SubList_methods[] = {
    {"increment", (PyCFunction) SubList_increment, METH_NOARGS,
     PyDoc_STR("increment state counter")},
    {NULL},
};

static int
SubList_init(SubListObject *self, PyObject *args, PyObject *kwds)
{
    if (PyList_Type.tp_init((PyObject *) self, args, kwds) < 0)
        return -1;
    self->state = 0;
    return 0;
}

static PyTypeObject SubListType = {
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "sublist.SubList",
    .tp_doc = PyDoc_STR("SubList objects"),
    .tp_basicsize = sizeof(SubListObject),
    .tp_itemsize = 0,
    .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,
    .tp_init = (initproc) SubList_init,
    .tp_methods = SubList_methods,
};

static PyModuleDef sublistmodule = {
    PyModuleDef_HEAD_INIT,
    .m_name = "sublist",
    .m_doc = "Example module that creates an extension type.",
    .m_size = -1,
};

PyMODINIT_FUNC
PyInit_sublist(void)
{
    PyObject *m;
    SubListType.tp_base = &PyList_Type;
    if (PyType_Ready(&SubListType) < 0)
        return NULL;

    m = PyModule_Create(&sublistmodule);
    if (m == NULL)
        return NULL;

    Py_INCREF(&SubListType);
    if (PyModule_AddObject(m, "SubList", (PyObject *) &SubListType) < 0) {
        Py_DECREF(&SubListType);
        Py_DECREF(m);
        return NULL;
    }

    return m;
}

As you can see, the source code closely resembles the Custom examples in previous sections. We will break down the main differences between them.

typedef struct {
    PyListObject list;
    int state;
} SubListObject;

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 PyObject_HEAD() at the beginning of its structure.

When a Python object is a SubList instance, its PyObject * pointer can be safely cast to both PyListObject * and SubListObject *:

static int
SubList_init(SubListObject *self, PyObject *args, PyObject *kwds)
{
    if (PyList_Type.tp_init((PyObject *) self, args, kwds) < 0)
        return -1;
    self->state = 0;
    return 0;
}

We see above how to call through to the __init__() method of the base type.

This pattern is important when writing a type with custom tp_new and tp_dealloc members. The tp_new handler should not actually create the memory for the object with its tp_alloc, but let the base class handle it by calling its own tp_new.

The PyTypeObject struct supports a 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 PyList_Type; it should be done later in the module initialization function:

PyMODINIT_FUNC
PyInit_sublist(void)
{
    PyObject* m;
    SubListType.tp_base = &PyList_Type;
    if (PyType_Ready(&SubListType) < 0)
        return NULL;

    m = PyModule_Create(&sublistmodule);
    if (m == NULL)
        return NULL;

    Py_INCREF(&SubListType);
    if (PyModule_AddObject(m, "SubList", (PyObject *) &SubListType) < 0) {
        Py_DECREF(&SubListType);
        Py_DECREF(m);
        return NULL;
    }

    return m;
}

PyType_Read() を呼ぶ前に、型の構造体の tp_base スロットは埋められていなければなりません。既存の型を継承する際には、 tp_alloc スロットを PyType_GenericNew() で埋める必要はありません。 -- 基底型のアロケーション関数が継承されます。

After that, calling PyType_Ready() and adding the type object to the module is the same as with the basic Custom examples.

脚注

[1]

これはそのオブジェクトが文字列や実数などの基本タイプであるような時に成り立ちます。

[2]

We relied on this in the tp_dealloc handler in this example, because our type doesn't support garbage collection.

[3]

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.

[4]

Also, even with our attributes restricted to strings instances, the user could pass arbitrary str subclasses and therefore still create reference cycles.

3. Defining Extension Types: Assorted Topics

この節ではさまざまな実装可能なタイプメソッドと、それらが何をするものであるかについて、ざっと説明します。

Here is the definition of PyTypeObject, with some fields only used in debug builds omitted:

typedef struct _typeobject {
    PyObject_VAR_HEAD
    const char *tp_name; /* For printing, in format "<module>.<name>" */
    Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */

    /* Methods to implement standard operations */

    destructor tp_dealloc;
    Py_ssize_t tp_vectorcall_offset;
    getattrfunc tp_getattr;
    setattrfunc tp_setattr;
    PyAsyncMethods *tp_as_async; /* formerly known as tp_compare (Python 2)
                                    or tp_reserved (Python 3) */
    reprfunc tp_repr;

    /* Method suites for standard classes */

    PyNumberMethods *tp_as_number;
    PySequenceMethods *tp_as_sequence;
    PyMappingMethods *tp_as_mapping;

    /* More standard operations (here for binary compatibility) */

    hashfunc tp_hash;
    ternaryfunc tp_call;
    reprfunc tp_str;
    getattrofunc tp_getattro;
    setattrofunc tp_setattro;

    /* Functions to access object as input/output buffer */
    PyBufferProcs *tp_as_buffer;

    /* Flags to define presence of optional/expanded features */
    unsigned long tp_flags;

    const char *tp_doc; /* Documentation string */

    /* Assigned meaning in release 2.0 */
    /* call function for all accessible objects */
    traverseproc tp_traverse;

    /* delete references to contained objects */
    inquiry tp_clear;

    /* Assigned meaning in release 2.1 */
    /* rich comparisons */
    richcmpfunc tp_richcompare;

    /* weak reference enabler */
    Py_ssize_t tp_weaklistoffset;

    /* Iterators */
    getiterfunc tp_iter;
    iternextfunc tp_iternext;

    /* Attribute descriptor and subclassing stuff */
    struct PyMethodDef *tp_methods;
    struct PyMemberDef *tp_members;
    struct PyGetSetDef *tp_getset;
    // Strong reference on a heap type, borrowed reference on a static type
    struct _typeobject *tp_base;
    PyObject *tp_dict;
    descrgetfunc tp_descr_get;
    descrsetfunc tp_descr_set;
    Py_ssize_t tp_dictoffset;
    initproc tp_init;
    allocfunc tp_alloc;
    newfunc tp_new;
    freefunc tp_free; /* Low-level free-memory routine */
    inquiry tp_is_gc; /* For PyObject_IS_GC */
    PyObject *tp_bases;
    PyObject *tp_mro; /* method resolution order */
    PyObject *tp_cache;
    PyObject *tp_subclasses;
    PyObject *tp_weaklist;
    destructor tp_del;

    /* Type attribute cache version tag. Added in version 2.6 */
    unsigned int tp_version_tag;

    destructor tp_finalize;
    vectorcallfunc tp_vectorcall;

    /* bitset of which type-watchers care about this type */
    unsigned char tp_watched;
} PyTypeObject;

たくさんの メソッドがありますね。でもそんなに心配する必要はありません。定義したい型があるなら、実装するのはこのうちのごくわずかですむことがほとんどです。

すでに予想されているでしょうが、この構造体について入念に見ていき、様々なハンドラについてより詳しい情報を提供します。しかしこれらのメンバが構造体中で定義されている順番は無視します。というのは、これらのメンバの現れる順序は歴史的な遺産によるものだからです。多くの場合いちばん簡単なのは、必要とするメンバがすべて含まれている例をとってきて、新しく作る型に合わせて値を変更することです。

const char *tp_name; /* For printing */

これは型の名前です。前の章で説明したように、これは色々な場面で現れ、ほとんどは診断目的で使われるものです。それなので、そのような場面で役に立つであろう名前を選んでください!

Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */

これらのフィールドは、この型のオブジェクトが新しく作成されるときにどれだけのメモリを割り当てればよいのかをランタイムに指示します。Python には可変長の構造体 (文字列やタプルなどを想像してください) に対する組み込みのサポートがある程度あり、ここで tp_itemsize メンバが使われます。これらについてはあとでふれます。

const char *tp_doc;

ここには Python スクリプトリファレンス obj.__doc__ が doc string を返すときの文字列 (あるいはそのアドレス) を入れます。

では次に、型の基本的なメソッドに進みます。ほとんどの拡張の型がこのメソッドを実装します。

3.1. ファイナライズとメモリ解放

destructor tp_dealloc;

型のインスタンスの参照カウントがゼロになり、Python インタプリタがそれを潰して再利用したくなると、この関数が呼ばれます。解放すべきメモリをその型が保持していたり、それ以外にも実行すべき後処理がある場合は、それらをここに入れられます。オブジェクトそれ自体もここで解放される必要があります。この関数の例は、以下のようなものです:

static void
newdatatype_dealloc(newdatatypeobject *obj)
{
    free(obj->obj_UnderlyingDatatypePtr);
    Py_TYPE(obj)->tp_free((PyObject *)obj);
}

If your type supports garbage collection, the destructor should call PyObject_GC_UnTrack() before clearing any member fields:

static void
newdatatype_dealloc(newdatatypeobject *obj)
{
    PyObject_GC_UnTrack(obj);
    Py_CLEAR(obj->other_obj);
    ...
    Py_TYPE(obj)->tp_free((PyObject *)obj);
}

メモリ解放関数でひとつ重要なのは、処理待ちの例外にいっさい手をつけないことです。なぜなら、解放用の関数は Python インタプリタがスタックを元の状態に戻すときに呼ばれることが多いからです。そして (通常の関数からの復帰でなく) 例外のためにスタックが巻き戻されるときは、すでに発生している例外からメモリ解放関数を守るものはありません。解放用の関数がおこなう動作が追加の Python のコードを実行してしまうと、それらは例外が発生していることを検知するかもしれません。これはインタプリタが誤解させるエラーを発生させることにつながります。これを防ぐ正しい方法は、安全でない操作を実行する前に処理待ちの例外を保存しておき、終わったらそれを元に戻すことです。これは PyErr_Fetch() および PyErr_Restore() 関数を使うことによって可能になります:

static void
my_dealloc(PyObject *obj)
{
    MyObject *self = (MyObject *) obj;
    PyObject *cbresult;

    if (self->my_callback != NULL) {
        PyObject *err_type, *err_value, *err_traceback;

        /* This saves the current exception state */
        PyErr_Fetch(&err_type, &err_value, &err_traceback);

        cbresult = PyObject_CallNoArgs(self->my_callback);
        if (cbresult == NULL)
            PyErr_WriteUnraisable(self->my_callback);
        else
            Py_DECREF(cbresult);

        /* This restores the saved exception state */
        PyErr_Restore(err_type, err_value, err_traceback);

        Py_DECREF(self->my_callback);
    }
    Py_TYPE(obj)->tp_free((PyObject*)self);
}

注釈

メモリ解放関数の中で安全に行えることにはいくつか制限があります。 1つ目は、その型が (tp_traverse および tp_clear を使って) ガベージコレクションをサポートしている場合、 tp_dealloc が呼び出されるまでに、消去されファイナライズされてしまうオブジェクトのメンバーが有り得ることです。 2つ目は、 tp_dealloc の中ではオブジェクトは不安定な状態にあることです: つまり参照カウントが0であるということです。 (上の例にあるような) 複雑なオブジェクトや API の呼び出しでは、 tp_dealloc を再度呼び出し、二重解放からクラッシュすることになるかもしれません。

Python 3.4 からは、複雑なファイナライズのコードは tp_dealloc に置かず、代わりに新しく導入された tp_finalize という型メソッドを使うことが推奨されています。

参考

PEP 442 [https://peps.python.org/pep-0442/] で新しいファイナライズの仕組みが説明されています。

3.2. オブジェクト表現

Python では、オブジェクトの文字列表現を生成するのに 2つのやり方があります: repr() 関数を使う方法と、 str() 関数を使う方法です。 (print() 関数は単に str() を呼び出します。) これらのハンドラはどちらも省略できます。

reprfunc tp_repr;
reprfunc tp_str;

tp_repr ハンドラは呼び出されたインスタンスの文字列表現を格納した文字列オブジェクトを返す必要があります。簡単な例は以下のようなものです:

static PyObject *
newdatatype_repr(newdatatypeobject *obj)
{
    return PyUnicode_FromFormat("Repr-ified_newdatatype{{size:%d}}",
                                obj->obj_UnderlyingDatatypePtr->size);
}

If no tp_repr handler is specified, the interpreter will supply a representation that uses the type's tp_name and a uniquely identifying value for the object.

tp_str ハンドラと str() の関係は、上の tp_repr ハンドラと repr() の関係に相当します。つまり、これは Python のコードがオブジェクトのインスタンスに対して str() を呼び出したときに呼ばれます。この関数の実装は tp_repr ハンドラのそれと非常に似ていますが、得られる文字列表現は人間が読むことを意図されています。 tp_str が指定されていない場合、かわりに tp_repr ハンドラが使われます。

以下は簡単な例です:

static PyObject *
newdatatype_str(newdatatypeobject *obj)
{
    return PyUnicode_FromFormat("Stringified_newdatatype{{size:%d}}",
                                obj->obj_UnderlyingDatatypePtr->size);
}

3.3. 属性を管理する

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 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 PyObject*. Each type can use whichever pair makes more sense for the implementation's convenience.

getattrfunc  tp_getattr;        /* char * version */
setattrfunc  tp_setattr;
/* ... */
getattrofunc tp_getattro;       /* PyObject * version */
setattrofunc tp_setattro;

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

3.3.1. 総称的な属性を管理する

ほとんどの型は 単純な 属性を使うだけです。では、どのような属性が単純だといえるのでしょうか? それが満たすべき条件はごくわずかです:

PyType_Ready() が呼ばれたとき、すでに属性の名前がわかっていること。

属性を参照したり設定したりするときに、特別な記録のための処理が必要でなく、また参照したり設定した値に対してどんな操作も実行する必要がないこと。

これらの条件は、属性の値や、値が計算されるタイミング、または格納されたデータがどの程度妥当なものであるかといったことになんら制約を課すものではないことに注意してください。

When PyType_Ready() is called, it uses three tables referenced by the type object to create descriptors 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 NULL, instances of the type will only have attributes that are inherited from their base type, and should leave the tp_getattro and tp_setattro fields NULL as well, allowing the base type to handle attributes.

テーブルはタイプオブジェクト中の 3つのメンバとして宣言されています:

struct PyMethodDef *tp_methods;
struct PyMemberDef *tp_members;
struct PyGetSetDef *tp_getset;

If tp_methods is not NULL, it must refer to an array of PyMethodDef structures. Each entry in the table is an instance of this structure:

typedef struct PyMethodDef {
    const char  *ml_name;       /* method name */
    PyCFunction  ml_meth;       /* implementation function */
    int          ml_flags;      /* flags */
    const char  *ml_doc;        /* docstring */
} PyMethodDef;

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 ml_name field of the sentinel must be NULL.

2番目のテーブルは、インスタンス中に格納されるデータと直接対応づけられた属性を定義するのに使います。いくつもの C の原始的な型がサポートされており、アクセスを読み出し専用にも読み書き可能にもできます。このテーブルで使われる構造体は次のように定義されています:

typedef struct PyMemberDef {
    const char *name;
    int         type;
    int         offset;
    int         flags;
    const char *doc;
} PyMemberDef;

For each entry in the table, a descriptor will be constructed and added to the type which will be able to extract a value from the instance structure. The type field should contain a type code like Py_T_INT or Py_T_DOUBLE; the value will be used to determine how to convert Python values to and from C values. The flags field is used to store flags which control how the attribute can be accessed: you can set it to Py_READONLY to prevent Python code from setting it.

An interesting advantage of using the 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 __doc__ attribute.

As with the tp_methods table, a sentinel entry with a ml_name value of NULL is required.

3.3.2. 特定の型に特化した属性の管理

For simplicity, only the char* version will be demonstrated here; the type of the name parameter is the only difference between the char* and 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 tp_getattr handler is called when the object requires an attribute look-up. It is called in the same situations where the __getattr__() method of a class would be called.

以下に例を示します。:

static PyObject *
newdatatype_getattr(newdatatypeobject *obj, char *name)
{
    if (strcmp(name, "data") == 0)
    {
        return PyLong_FromLong(obj->data);
    }

    PyErr_Format(PyExc_AttributeError,
                 "'%.100s' object has no attribute '%.400s'",
                 Py_TYPE(obj)->tp_name, name);
    return NULL;
}

The tp_setattr handler is called when the __setattr__() or __delattr__() method of a class instance would be called. When an attribute should be deleted, the third parameter will be NULL. Here is an example that simply raises an exception; if this were really all you wanted, the tp_setattr handler should be set to NULL.

static int
newdatatype_setattr(newdatatypeobject *obj, char *name, PyObject *v)
{
    PyErr_Format(PyExc_RuntimeError, "Read-only attribute: %s", name);
    return -1;
}

3.4. オブジェクトの比較

richcmpfunc tp_richcompare;

The tp_richcompare handler is called when comparisons are needed. It is analogous to the rich comparison methods, like __lt__(), and also called by PyObject_RichCompare() and PyObject_RichCompareBool().

This function is called with two Python objects and the operator as arguments, where the operator is one of Py_EQ, Py_NE, Py_LE, Py_GE, Py_LT or Py_GT. It should compare the two objects with respect to the specified operator and return Py_True or Py_False if the comparison is successful, Py_NotImplemented to indicate that comparison is not implemented and the other object's comparison method should be tried, or NULL if an exception was set.

これは内部ポインタのサイズが等しければ等しいと見なすデータ型のサンプル実装です:

static PyObject *
newdatatype_richcmp(newdatatypeobject *obj1, newdatatypeobject *obj2, int op)
{
    PyObject *result;
    int c, size1, size2;

    /* code to make sure that both arguments are of type
       newdatatype omitted */

    size1 = obj1->obj_UnderlyingDatatypePtr->size;
    size2 = obj2->obj_UnderlyingDatatypePtr->size;

    switch (op) {
    case Py_LT: c = size1 <  size2; break;
    case Py_LE: c = size1 <= size2; break;
    case Py_EQ: c = size1 == size2; break;
    case Py_NE: c = size1 != size2; break;
    case Py_GT: c = size1 >  size2; break;
    case Py_GE: c = size1 >= size2; break;
    }
    result = c ? Py_True : Py_False;
    Py_INCREF(result);
    return result;
 }

3.5. 抽象的なプロトコルのサポート

Python はいくつもの 抽象的な “プロトコル”をサポートしています。これらを使用する特定のインターフェイスについては 抽象オブジェクトレイヤ (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-NULL. The flag may be set to indicate the presence of a slot, but a slot may still be unfilled.)

PyNumberMethods   *tp_as_number;
PySequenceMethods *tp_as_sequence;
PyMappingMethods  *tp_as_mapping;

お使いのオブジェクトを数値やシーケンス、あるいは辞書のようにふるまうようにしたいならば、それぞれに C の PyNumberMethods 構造体、 PySequenceMethods 構造体、または PyMappingMethods 構造体のアドレスを入れます。これらに適切な値を入れても入れなくてもかまいません。これらを使った例は Python の配布ソースにある Objects でみつけることができるでしょう。

hashfunc tp_hash;

この関数は、もし使うことにしたならば、データ型のインスタンスのハッシュ番号を返すようにします。次のは単純な例です:

static Py_hash_t
newdatatype_hash(newdatatypeobject *obj)
{
    Py_hash_t result;
    result = obj->some_size + 32767 * obj->some_number;
    if (result == -1)
       result = -2;
    return result;
}

Py_hash_t is a signed integer type with a platform-varying width. Returning -1 from tp_hash indicates an error, which is why you should be careful to avoid returning it when hash computation is successful, as seen above.

ternaryfunc tp_call;

この関数は、その型のインスタンスが「関数として呼び出される」ときに呼ばれます。たとえばもし obj1 にそのインスタンスが入っていて、Python スクリプトで obj1('hello') を実行したとすると、 tp_call ハンドラが呼ばれます。

この関数は 3つの引数をとります:

self は呼び出しの対象となるデータ型のインスタンスです。たとえば呼び出しが obj1('hello') の場合、self は obj1 になります。

args は呼び出しの引数を格納しているタプルです。ここから引数を取り出すには PyArg_ParseTuple() を使います。

kwds is a dictionary of keyword arguments that were passed. If this is non-NULL and you support keyword arguments, use PyArg_ParseTupleAndKeywords() to extract the arguments. If you do not want to support keyword arguments and this is non-NULL, raise a TypeError with a message saying that keyword arguments are not supported.

以下は tp_call の簡易な実装です:

static PyObject *
newdatatype_call(newdatatypeobject *obj, PyObject *args, PyObject *kwds)
{
    PyObject *result;
    const char *arg1;
    const char *arg2;
    const char *arg3;

    if (!PyArg_ParseTuple(args, "sss:call", &arg1, &arg2, &arg3)) {
        return NULL;
    }
    result = PyUnicode_FromFormat(
        "Returning -- value: [%d] arg1: [%s] arg2: [%s] arg3: [%s]\n",
        obj->obj_UnderlyingDatatypePtr->size,
        arg1, arg2, arg3);
    return result;
}

/* Iterators */
getiterfunc tp_iter;
iternextfunc tp_iternext;

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 NULL. tp_iter corresponds to the Python __iter__() method, while tp_iternext corresponds to the Python __next__() method.

Any iterable object must implement the tp_iter handler, which must return an iterator object. Here the same guidelines apply as for Python classes:

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

Objects which can only be iterated over once (usually due to side effects of iteration, such as file objects) can implement tp_iter by returning a new reference to themselves -- and should also therefore implement the tp_iternext handler.

Any iterator object should implement both tp_iter and tp_iternext. An iterator's tp_iter handler should return a new reference to the iterator. Its 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, tp_iternext may return NULL without setting an exception, or it may set StopIteration in addition to returning NULL; avoiding the exception can yield slightly better performance. If an actual error occurs, tp_iternext should always set an exception and return NULL.

3.6. 弱参照(Weak Reference)のサポート

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

参考

Documentation for the weakref module.

For an object to be weakly referencable, the extension type must set the Py_TPFLAGS_MANAGED_WEAKREF bit of the tp_flags field. The legacy tp_weaklistoffset field should be left as zero.

Concretely, here is how the statically declared type object would look:

static PyTypeObject TrivialType = {
    PyVarObject_HEAD_INIT(NULL, 0)
    /* ... other members omitted for brevity ... */
    .tp_flags = Py_TPFLAGS_MANAGED_WEAKREF | ...,
};

The only further addition is that tp_dealloc needs to clear any weak references (by calling PyObject_ClearWeakRefs()):

static void
Trivial_dealloc(TrivialObject *self)
{
    /* Clear weakrefs first before calling any destructors */
    PyObject_ClearWeakRefs((PyObject *) self);
    /* ... remainder of destruction code omitted for brevity ... */
    Py_TYPE(self)->tp_free((PyObject *) self);
}

3.7. その他いろいろ

In order to learn how to implement any specific method for your new data type, get the CPython source code. Go to the Objects directory, then search the C source files for tp_ plus the function you want (for example, 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 PyObject_TypeCheck() function. A sample of its use might be something like the following:

if (!PyObject_TypeCheck(some_object, &MyType)) {
    PyErr_SetString(PyExc_TypeError, "arg #1 not a mything");
    return NULL;
}

参考

Download CPython source releases.

https://www.python.org/downloads/source/

The CPython project on GitHub, where the CPython source code is developed.

https://github.com/python/cpython

4. C および C++ 拡張のビルド

CPython の C 拡張は 初期化関数 をエクスポートした共有ライブラリ (例、 Linux の .so ファイルや Windows の .pyd ファイル) です。

To be importable, the shared library must be available on PYTHONPATH, and must be named after the module name, with an appropriate extension. When using setuptools, the correct filename is generated automatically.

初期化関数のシグネチャは次のとおりです:

PyObject *PyInit_modulename(void)

この関数は完全に初期化されたモジュールか、 PyModuleDef インスタンスを返します。詳しいことは Cモジュールの初期化 を参照してください。

名前にASCIIしか使っていないモジュールの場合、関数名は PyInit_<modulename> の <modulename> をモジュール名で置き換えたものでなければなりません。多段階初期化 を使っているときは、モジュール名にASCII以外の文字も使えます。この場合、初期化関数の名前は PyInitU_<modulename> で、 <modulename> はハイフンをアンダースコアで置き換えて Python の punycode エンコーディングでエンコードしたものになります。 Python で書くと次のような処理になります:

def initfunc_name(name):
    try:
        suffix = b'_' + name.encode('ascii')
    except UnicodeEncodeError:
        suffix = b'U_' + name.encode('punycode').replace(b'-', b'_')
    return b'PyInit' + suffix

1つの共有ライブラリに複数の初期化関数を定義することで、複数のモジュールをエクスポートすることは可能です。しかし、デフォルトではファイル名に対応した関数しか見付けようとしないので、複数のモジュールをインポートさせるにはシンボリックリンクか独自のインポーターを使う必要があります。詳しいことは PEP 489 [https://peps.python.org/pep-0489/] の "Multiple modules in one library" 節を参照してください。

4.1. Building C and C++ Extensions with setuptools

Python 3.12 and newer no longer come with distutils. Please refer to the setuptools documentation at https://setuptools.readthedocs.io/en/latest/setuptools.html to learn more about how build and distribute C/C++ extensions with setuptools.

5. Windows 上での C および C++ 拡張モジュールのビルド

この章では Windows 向けの Python 拡張モジュールを Microsoft Visual C++ を使って作成する方法について簡単に述べ、その後に拡張モジュールのビルドがどのように動作するのかについて詳しい背景を述べます。この説明は、Python 拡張モジュールを作成する Windows プログラマと、Unix と Windows の双方でうまくビルドできるようなソフトウェアの作成に興味がある Unix プログラマの双方にとって有用です。

モジュールの作者には、この節で説明している方法よりも、distutils によるアプローチで拡張モジュールをビルドするよう勧めます。また、Python をビルドした際に使われた C コンパイラが必要です; 通常は Microsoft Visual C++です。

注釈

この章では、Python のバージョン番号が符号化されて入っているたくさんのファイル名について触れます。これらのファイル名は XY で表されるバージョン名付きで表現されます; 'X' は使っている Python リリースのメジャーバージョン番号、'Y' はマイナーバージョン番号です。例えば、Python 2.2.1 を使っているなら、XY は実際には 22 になります。

5.1. 型どおりのアプローチ

There are two approaches to building extension modules on Windows, just as there are on Unix: use the setuptools package to control the build process, or do things manually. The setuptools approach works well for most extensions; documentation on using setuptools to build and package extension modules is available in Building C and C++ Extensions with setuptools. If you find you really need to do things manually, it may be instructive to study the project file for the winsound [https://github.com/python/cpython/tree/3.12/PCbuild/winsound.vcxproj] standard library module.

5.2. Unix と Windows の相違点

Unix と Windows では、コードの実行時読み込みに全く異なるパラダイムを用いています。動的ロードされるようなモジュールをビルドしようとする前に、自分のシステムがどのように動作するか知っておいてください。

Unix では、共有オブジェクト (.so) ファイルにプログラムが使うコード、そしてプログラム内で使う関数名やデータが入っています。ファイルがプログラムに結合されると、これらの関数やデータに対するファイルのコード内の全ての参照は、メモリ内で関数やデータが配置されている、プログラム中の実際の場所を指すように変更されます。これは基本的にはリンク操作にあたります。

Windows では、動的リンクライブラリ (.dll) ファイルにはぶら下がり参照 (dangling reference) はありません。その代わり、関数やデータへのアクセスはルックアップテーブルを介します。従って DLL コードの場合、実行時にポインタがプログラムメモリ上の正しい場所を指すように修正する必要はありません; その代わり、コードは常に DLL のルックアップテーブルを使い、ルックアップテーブル自体は実行時に実際の関数やデータを指すように修正されます。

Unix には、唯一のライブラリファイル形式 (.a) しかありません。 .a ファイルには複数のオブジェクトファイル (.o) 由来のコードが入っています。共有オブジェクトファイル (.so) を作成するリンク処理の段階中に、リンカは定義場所の不明な識別子に遭遇することがあります。このときリンカはライブラリ内のオブジェクトファイルを検索します; もし識別子が見つかると、リンカはそのオブジェクトファイルから全てのコードを取り込みます。

Windows では、二つの形式のライブラリ、静的ライブラリとインポートライブラリがあります (どちらも .lib と呼ばれています)。静的ライブラリは Unix における .a ファイルに似ています; このファイルには、必要に応じて取り込まれるようなコードが入っています。インポートライブラリは、基本的には特定の識別子が不正ではなく、 DLL がロードされた時点で存在することを保証するためにだけ使われます。リンカはインポートライブラリからの情報を使ってルックアップテーブルを作成し、DLL に入っていない識別子を使えるようにします。アプリケーションや DLL がリンクされるさい、インポートライブラリが生成されることがあります。このライブラリは、アプリケーションや DLL 内のシンボルに依存するような、将来作成される全ての DLL で使うために必要になります。

二つの動的ロードモジュール、B と C を作成し、別のコードブロック A を共有するとします。Unix では、 A.a を B.so や C.so をビルドするときのリンカに渡したりは しません ; そんなことをすれば、コードは二度取り込まれ、B と C のそれぞれが自分用のコピーを持ってしまいます。 Windows では、 A.dll をビルドすると A.lib もビルドされます。 B や C のリンクには A.lib を渡します。 A.lib にはコードは入っていません; 単に A のコードにアクセスするするために実行時に用いられる情報が入っているだけです。

Windows ではインポートライブラリの使用は import spam とするようなものです; この操作によって spam の名前にアクセスできますが、コードのコピーを個別に作成したりはしません。Unix では、ライブラリとのリンクはむしろ from spam import * に似ています; この操作では個別にコードのコピーを生成します。

5.3. DLL 使用の実際

Windows Python is built in Microsoft Visual C++; using other compilers may or may not work. The rest of this section is MSVC++ specific.

Windows で DLL を作成する際は、 pythonXY.lib をリンカに渡さねばなりません。例えば二つの DLL 、spam と ni (spam の中には C 関数が入っているとします) をビルドするには、以下のコマンドを実行します:

cl /LD /I/python/include spam.c ../libs/pythonXY.lib
cl /LD /I/python/include ni.c spam.lib ../libs/pythonXY.lib

最初のコマンドで、三つのファイル: spam.obj 、 spam.dll および spam.lib ができます。 Spam.dll には (PyArg_ParseTuple() のような) Python 関数は全く入っていませんが、 pythonXY.lib のおかげで Python コードを見つけることはできます。

二つ目のコマンドでは、 ni.dll (および .obj と .lib) ができ、このライブラリは spam と Python 実行形式中の必要な関数をどうやって見つければよいか知っています。

全ての識別子がルックアップテーブル上に公開されるわけではありません。他のモジュール (Python 自体を含みます) から、自作の識別子が見えるようにするには、void _declspec(dllexport) initspam(void) や PyObject _declspec(dllexport) *NiGetSpamData(void) のように、_declspec(dllexport) で宣言せねばなりません。

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 msvcrtxx.lib to the list of libraries.

1. 他のアプリケーションへの Python の埋め込み

前章では、 Python を拡張する方法、すなわち C 関数のライブラリを Python に結びつけて機能を拡張する方法について述べました。同じようなことを別の方法でも実行できます: それは、自分の C/C++ アプリケーションに Python を埋め込んで機能を強化する、というものです。埋め込みを行うことで、アプリケーションの何らかの機能を C や C++ の代わりに Python で実装できるようになります。埋め込みは多くの用途で利用できます; ユーザが Python でスクリプトを書き、アプリケーションを自分好みに仕立てられるようにする、というのがその一例です。プログラマが、特定の機能を Python でより楽に書ける場合に自分自身のために埋め込みを行うこともできます。

Python の埋め込みは Python の拡張と似ていますが、全く同じというわけではありません。その違いは、Python を拡張した場合にはアプリケーションのメインプログラムは依然として Python インタプリタである一方、 Python を組み込みんだ場合には、メインプログラムには Python が関係しない --- その代わりに、アプリケーションのある一部分が時折 Python インタプリタを呼び出して何らかの Python コードを実行させる --- かもしれない、ということです。

従って、 Python の埋め込みを行う場合、自作のメインプログラムを提供しなければなりません。メインプログラムがやらなければならないことの一つに、 Python インタプリタの初期化があります。とにかく少なくとも関数 Py_Initialize() を呼び出さねばなりません。オプションとして、Python 側にコマンドライン引数を渡すために関数呼び出しを行います。その後、アプリケーションのどこでもインタプリタを呼び出せるようになります。

インタプリタを呼び出すには、異なるいくつかの方法があります: Python 文が入った文字列を PyRun_SimpleString() に渡す、 stdio ファイルポインタとファイル名 (これはエラーメッセージ内でコードを識別するためだけのものです) を PyRun_SimpleFile() に渡す、といった具合です。これまでの各章で説明した低水準の操作を呼び出して、Python オブジェクトを構築したり使用したりもできます。

参考

Python/C API リファレンスマニュアル

Python C インターフェースの詳細はこのマニュアルに書かれています。必要な情報の大部分はここにあるはずです。

1.1. 高水準の埋め込み

Python の埋め込みの最も簡単な形式は、超高水準インターフェースの利用です。このインターフェースは、アプリケーションとやり取りする必要がない Python スクリプトを実行するためのものです。例えばこれは、一つのファイル上で何らかの操作を実現するのに利用できます。

#define PY_SSIZE_T_CLEAN
#include <Python.h>

int
main(int argc, char *argv[])
{
    wchar_t *program = Py_DecodeLocale(argv[0], NULL);
    if (program == NULL) {
        fprintf(stderr, "Fatal error: cannot decode argv[0]\n");
        exit(1);
    }
    Py_SetProgramName(program);  /* optional but recommended */
    Py_Initialize();
    PyRun_SimpleString("from time import time,ctime\n"
                       "print('Today is', ctime(time()))\n");
    if (Py_FinalizeEx() < 0) {
        exit(120);
    }
    PyMem_RawFree(program);
    return 0;
}

The Py_SetProgramName() function should be called before Py_Initialize() to inform the interpreter about paths to Python run-time libraries. Next, the Python interpreter is initialized with Py_Initialize(), followed by the execution of a hard-coded Python script that prints the date and time. Afterwards, the Py_FinalizeEx() call shuts the interpreter down, followed by the end of the program. In a real program, you may want to get the Python script from another source, perhaps a text-editor routine, a file, or a database. Getting the Python code from a file can better be done by using the PyRun_SimpleFile() function, which saves you the trouble of allocating memory space and loading the file contents.

1.2. 超高水準の埋め込みから踏み出す: 概要

高水準インターフェースは、断片的な Python コードをアプリケーションから実行できるようにしてくれますが、アプリケーションと Python コードの間でのデータのやり取りは、控えめに言っても煩わしいものです。データのやり取りをしたいなら、より低水準のインターフェース呼び出しを利用しなくてはなりません。より多く C コードを書かねばならない代わりに、ほぼ何でもできるようになります。

Python の拡張と埋め込みは、趣旨こそ違え、同じ作業であるということに注意せねばなりません。これまでの章で議論してきたトピックのほとんどが埋め込みでもあてはまります。これを示すために、 Python から C への拡張を行うコードが実際には何をするか考えてみましょう:

データ値を Python から C に変換する。

変換された値を使って C ルーチンの関数呼び出しを行い、

呼び出しで得られたデータ値 C から Python に変換する。

Python を埋め込む場合には、インターフェースコードが行う作業は以下のようになります:

データ値を C から Python に変換する。

変換された値を使って Python インターフェースルーチンの関数呼び出しを行い、

呼び出しで得られたデータ値 Python から C に変換する。

一見して分かるように、データ変換のステップは、言語間でデータを転送する方向が変わったのに合わせて単に入れ替えただけです。唯一の相違点は、データ変換の間にあるルーチンです。拡張を行う際には C ルーチンを呼び出しますが、埋め込みの際には Python ルーチンを呼び出します。

この章では、Python から C へ、そしてその逆へとデータを変換する方法については議論しません。また、正しい参照の使い方やエラーの扱い方についてすでに理解しているものと仮定します。これらの側面についてはインタプリタの拡張と何ら変わるところがないので、必要な情報については以前の章を参照できます。

1.3. 純粋な埋め込み

最初に例示するプログラムは、Python スクリプト内の関数を実行するためのものです。超高水準インターフェースに関する節で挙げた例と同様に、Python インタプリタはアプリケーションと直接やりとりはしません (が、次の節でやりとりするよう変更します)。

Python スクリプト内で定義されている関数を実行するためのコードは以下のようになります:

#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;
}

このコードは argv[1] を使って Python スクリプトをロードし、 argv[2] 内に指定された名前の関数を呼び出します。関数の整数引数は argv 配列中の他の値になります。このプログラムを コンパイルしてリンク し (できた実行可能形式を call と呼びましょう)、以下のような Python スクリプトを実行することにします:

def multiply(a,b):
    print("Will compute", a, "times", b)
    c = 0
    for i in range(0, a):
        c = c + b
    return c

実行結果は以下のようになるはずです:

$ call multiply multiply 3 2
Will compute 3 times 2
Result of call: 6

この程度の機能を実現するにはプログラムがいささか大きすぎますが、ほとんどは Python から C へのデータ変換やエラー報告のためのコードです。Python の埋め込みという観点から最も興味深い部分は以下のコードから始まる部分です:

Py_Initialize();
pName = PyUnicode_DecodeFSDefault(argv[1]);
/* Error checking of pName left out */
pModule = PyImport_Import(pName);

インタプリタの初期化後、スクリプトは PyImport_Import() を使って読み込まれます。このルーチンは Python 文字列を引数に取る必要があり、データ変換ルーチン PyUnicode_FromString() で構築します。

pFunc = PyObject_GetAttrString(pModule, argv[2]);
/* pFunc is a new reference */

if (pFunc && PyCallable_Check(pFunc)) {
    ...
}
Py_XDECREF(pFunc);

ひとたびスクリプトが読み込まれると、 PyObject_GetAttrString() を使って必要な名前を取得できます。名前がスクリプト中に存在し、取得したオブジェクトが呼び出し可能オブジェクトであれば、このオブジェクトが関数であると考えて差し支えないでしょう。そこでプログラムは定石どおりに引数のタプル構築に進みます。その後、Python 関数を以下のコードで呼び出します:

pValue = PyObject_CallObject(pFunc, pArgs);

関数が処理を戻す際、 pValue は NULL になるか、関数の戻り値への参照が入っています。値を調べた後には忘れずに参照を解放してください。

1.4. 埋め込まれた Python の拡張

ここまでは、埋め込み Python インタプリタはアプリケーション本体の機能にアクセスする手段がありませんでした。 Python API を使うと、埋め込みインタプリタを拡張することでアプリケーション本体へのアクセスを可能にします。つまり、アプリケーションで提供されているルーチンを使って、埋め込みインタプリタを拡張するのです。複雑なことのように思えますが、それほどひどいわけではありません。さしあたって、アプリケーションが Python インタプリタを起動したということをちょっと忘れてみてください。その代わり、アプリケーションがサブルーチンの集まりで、あたかも普通の Python 拡張モジュールを書くかのように、Python から各ルーチンにアクセスできるようにするグルー(glue, 糊) コードを書くと考えてください。例えば以下のようにです:

static int numargs=0;

/* Return the number of arguments of the application command line */
static PyObject*
emb_numargs(PyObject *self, PyObject *args)
{
    if(!PyArg_ParseTuple(args, ":numargs"))
        return NULL;
    return PyLong_FromLong(numargs);
}

static PyMethodDef EmbMethods[] = {
    {"numargs", emb_numargs, METH_VARARGS,
     "Return the number of arguments received by the process."},
    {NULL, NULL, 0, NULL}
};

static PyModuleDef EmbModule = {
    PyModuleDef_HEAD_INIT, "emb", NULL, -1, EmbMethods,
    NULL, NULL, NULL, NULL
};

static PyObject*
PyInit_emb(void)
{
    return PyModule_Create(&EmbModule);
}

上のコードを main() 関数のすぐ上に挿入します。また、以下の二つの文を Py_Initialize() の呼び出しの前に挿入します:

numargs = argc;
PyImport_AppendInittab("emb", &PyInit_emb);

These two lines initialize the numargs variable, and make the emb.numargs() function accessible to the embedded Python interpreter. With these extensions, the Python script can do things like

import emb
print("Number of arguments", emb.numargs())

実際のアプリケーションでは、こうしたメソッドでアプリケーション内の API を Python に公開することになります。

1.5. C++による Python の埋め込み

C++ プログラム中にも Python を埋め込めます; 厳密に言うと、どうやって埋め込むかは使っているC++ 処理系の詳細に依存します; 一般的には、メインプログラムをC++で書き、C++ コンパイラを使ってプログラムをコンパイル・リンクする必要があるでしょう。 Python 自体を C++でコンパイルしなおす必要はありません。

1.6. Unix 系システムにおけるコンパイルとリンク

Python インタプリタをアプリケーションに埋め込むためにコンパイラ (とリンカ) に渡すべき正しいフラグを見出すのは簡単でないかもしれません。これは特に、Python がライブラリモジュールに対してリンクされた C 動的拡張 (.so ファイル) として実装されたものをロードする必要があるためです。

必要なコンパイル・リンクのオプションを知るために、 pythonX.Y-config スクリプトが使えます(これは Python インストール時に生成されたもので、 python3-config スクリプトも利用出来るかもしれません)。このスクリプトにはオプションが多くありますが、直接的に有用なのはこれでしょう:

pythonX.Y-config --cflags は推奨のコンパイルオプションを出力します:

$ /opt/bin/python3.11-config --cflags
-I/opt/include/python3.11 -I/opt/include/python3.11 -Wsign-compare  -DNDEBUG -g -fwrapv -O3 -Wall

pythonX.Y-config --ldflags --embed は推奨のリンクオプションを出力します:

$ /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

注釈

複数 Python バージョン共存(とりわけシステムの Python とあなた自身でビルドした Python)での混乱を避けるために、上での例のように pythonX.Y-config は絶対パスで起動したほうが良いです。

もしこの手順でうまくいかなければ(たしかにこれは全ての Unix 的なプラットフォームで動作することを保障するものではないですが、 bug reports は歓迎です)、あなたのシステムのダイナミックリンクについてのドキュメントを読み、Python の Makefile のコンパイルオプションを調べる必要があるでしょう(Makefile の場所を調べるには sysconfig.get_makefile_filename() を使ってください)。この場合、 sysconfig モジュールが役に立つ道具になります。これによってあなたが付け加えたいコンパイル・リンクのオプション構成をプログラム的に抽出できます。例えば:

>>> import sysconfig
>>> sysconfig.get_config_var('LIBS')
'-lpthread -ldl  -lutil'
>>> sysconfig.get_config_var('LINKFORSHARED')
'-Xlinker -export-dynamic'

Python/C API リファレンスマニュアル

このマニュアルでは、拡張モジュールを書いたり Python インタプリタをアプリケーションに埋め込んだりしたい C/C++ プログラマが利用できる API について述べています。 Python インタプリタの拡張と埋め込み は拡張モジュールを書く際の一般的な決まりごとについて記述していますが、 API の詳細までは記述していないので、このドキュメントが手引きになります。

はじめに

コーディング基準

インクルードファイル

便利なマクロ

オブジェクト、型および参照カウント

例外

Python の埋め込み

デバッグ版ビルド (Debugging Builds)

C API の安定性

Unstable C API

安定 ABI (Stable Appliction Binary Interface)

プラットフォームで考慮すべき点

限定版APIの内容

超高水準レイヤ

参照カウント

例外処理

出力とクリア

例外の送出

警告

エラーインジケータの問い合わせ

シグナルハンドリング

例外クラス

例外オブジェクト

Unicode 例外オブジェクト

再帰の管理

標準例外

標準警告カテゴリ

ユーティリティ

オペレーティングシステム関連のユーティリティ

システム関数

プロセス制御

モジュールのインポート

データ整列化 (data marshalling) のサポート

引数の解釈と値の構築

文字列の変換と書式化

PyHash API

リフレクション

codec レジストリとサポート関数

Support for Perf Maps

抽象オブジェクトレイヤ (Abstract Objects Layer)

オブジェクトプロトコル (object protocol)

Call プロトコル

数値型プロトコル (number protocol)

シーケンス型プロトコル (sequence protocol)

マップ型プロトコル (mapping protocol)

イテレータプロトコル (iterator protocol)

バッファプロトコル (buffer Protocol)

古いバッファプロトコル

具象オブジェクト (concrete object) レイヤ

基本オブジェクト (fundamental object)

数値型オブジェクト (numeric object)

シーケンスオブジェクト (sequence object)

Container オブジェクト

Function オブジェクト

その他のオブジェクト

初期化 (initialization)、終了処理 (finalization)、スレッド

Python 初期化以前

グローバルな設定変数

インタープリタの初期化と終了処理

プロセスワイドのパラメータ

スレッド状態 (thread state) とグローバルインタプリタロック (global interpreter lock)

サブインタプリタサポート

非同期通知

プロファイルとトレース (profiling and tracing)

高度なデバッガサポート (advanced debugger support)

スレッドローカルストレージのサポート

Python 初期化設定

使用例

PyWideStringList

PyStatus

PyPreConfig

Preinitialize Python with PyPreConfig

PyConfig

Initialization with PyConfig

Isolated Configuration

Python Configuration

Python Path Configuration

Py_RunMain()

Py_GetArgcArgv()

Multi-Phase Initialization Private Provisional API

メモリ管理

概要

Allocator Domains

生メモリインターフェース

メモリインターフェース

オブジェクトアロケータ

Default Memory Allocators

メモリアロケータをカスタマイズする

Debug hooks on the Python memory allocators

pymalloc アロケータ

tracemalloc C API

使用例

オブジェクト実装サポート (object implementation support)

オブジェクトをヒープ上にメモリ確保する

共通のオブジェクト構造体 (common object structure)

型オブジェクト

数値オブジェクト構造体

マップオブジェクト構造体

シーケンスオブジェクト構造体

バッファオブジェクト構造体 (buffer object structure)

async オブジェクト構造体

Slot Type typedefs

使用例

循環参照ガベージコレクションをサポートする

API と ABI のバージョニング

はじめに

Python のアプリケーションプログラマ用インタフェース (Application Programmer's Interface, API) は、 Python インタプリタに対する様々なレベルでのアクセス手段を C や C++ のプログラマに提供しています。この API は通常 C++ からも全く同じように利用できるのですが、簡潔な呼び名にするために Python/C API と名づけられています。根本的に異なる二つの目的から、 Python/C API が用いられます。第一は、特定用途の 拡張モジュール (extension module) 、すなわち Python インタプリタを拡張する C で書かれたモジュールを記述する、という目的です。第二は、より大規模なアプリケーション内で Python を構成要素 (component) として利用するという目的です; このテクニックは、一般的にはアプリケーションへの Python の埋め込み (embedding) と呼びます。

拡張モジュールの作成は比較的わかりやすいプロセスで、 "手引書 (cookbook)" 的なアプローチでうまく実現できます。作業をある程度まで自動化してくれるツールもいくつかあります。一方、他のアプリケーションへの Python の埋め込みは、Python ができてから早い時期から行われてきましたが、拡張モジュールの作成に比べるとやや難解です。

多くの API 関数は、Python の埋め込みであるか拡張であるかに関わらず役立ちます; とはいえ、Python を埋め込んでいるほとんどのアプリケーションは、同時に自作の拡張モジュールも提供する必要が生じることになるでしょうから、Python を実際にアプリケーションに埋め込んでみる前に拡張モジュールの書き方に詳しくなっておくのはよい考えだと思います。

コーディング基準

CPython に含める C コードを書いている場合は、 PEP 7 [https://peps.python.org/pep-0007/] のガイドラインと基準に従わなければ なりません 。このガイドラインは、コントリビュート対象の Python のバージョンに関係無く適用されます。自身のサードパーティーのモジュールでは、それをいつか Python にコントリビュートするつもりでなければ、この慣習に従う必要はありません。

インクルードファイル

Python/C API を使うために必要な、関数、型およびマクロの全ての定義をインクルードするには、以下の行:

#define PY_SSIZE_T_CLEAN
#include <Python.h>

をソースコードに記述します。この行を記述すると、標準ヘッダ: <stdio.h>, <string.h>, <errno.h>, <limits.h>, <assert.h>, <stdlib.h> を (利用できれば) インクルードします。

注釈

Python は、システムによっては標準ヘッダの定義に影響するようなプリプロセッサ定義を行っているので、 Python.h をいずれの標準ヘッダよりも前にインクルード せねばなりません 。

Python.h をインクルードする前に、常に PY_SSIZE_T_CLEAN を定義することが推奨されます。このマクロの解説については 引数の解釈と値の構築 を参照してください。

Python.h で定義されている、ユーザから見える名前全て (Python.h がインクルードしている標準ヘッダの名前は除きます) には、接頭文字列 Py または _Py が付きます。_Py で始まる名前は Python 実装で内部使用するための名前で、拡張モジュールの作者は使ってはなりません。構造体のメンバには予約済みの接頭文字列はありません。

注釈

API のユーザは、Py や _Py で始まる名前を定義するコードを絶対に書いてはなりません。後からコードを読む人を混乱させたり、将来の Python のバージョンで同じ名前が定義されて、ユーザの書いたコードの可搬性を危うくする可能性があります。

ヘッダファイル群は通常 Python と共にインストールされます。 Unixでは prefix/include/pythonversion/ および exec_prefix/include/pythonversion/ に置かれます。 prefix と exec_prefix は Python をビルドする際の configure スクリプトに与えたパラメタに対応し、 version は '%d.%d' % sys.version_info[:2] に対応します。 Windows では、ヘッダは prefix/include に置かれます。 prefix はインストーラに指定したインストールディレクトリです。

ヘッダをインクルードするには、各ヘッダの入ったディレクトリ (別々のディレクトリの場合は両方) を、コンパイラがインクルードファイルを検索するためのパスに入れます。親ディレクトリをサーチパスに入れて、 #include <pythonX.Y/Python.h> のようにしては なりません ; prefix 内のプラットフォームに依存しないヘッダは、 exec_prefix からプラットフォーム依存のヘッダをインクルードしているので、このような操作を行うと複数のプラットフォームでのビルドができなくなります。

C++ users should note that although the API is defined entirely using C, the header files properly declare the entry points to be extern "C". As a result, there is no need to do anything special to use the API from C++.

便利なマクロ

Python のヘッダーファイルには便利なマクロがいくつか定義されています。多くのマクロは、それが役に立つところ (例えば、 Py_RETURN_NONE) の近くに定義があります。より一般的な使われかたをする他のマクロはこれらのヘッダーファイルに定義されています。ただし、ここで完全に列挙されているとは限りません。

PyMODINIT_FUNC

Declare an extension module PyInit initialization function. The function return type is PyObject*. The macro declares any special linkage declarations required by the platform, and for C++ declares the function as extern "C".

The initialization function must be named PyInit_name, where name is the name of the module, and should be the only non-static item defined in the module file. Example:

static struct PyModuleDef spam_module = {
    PyModuleDef_HEAD_INIT,
    .m_name = "spam",
    ...
};

PyMODINIT_FUNC
PyInit_spam(void)
{
    return PyModule_Create(&spam_module);
}

Py_ABS(x)

x の絶対値を返します。

Added in version 3.3.

Py_ALWAYS_INLINE

Ask the compiler to always inline a static inline function. The compiler can ignore it and decides to not inline the function.

It can be used to inline performance critical static inline functions when building Python in debug mode with function inlining disabled. For example, MSC disables function inlining when building in debug mode.

Marking blindly a static inline function with Py_ALWAYS_INLINE can result in worse performances (due to increased code size for example). The compiler is usually smarter than the developer for the cost/benefit analysis.

If Python is built in debug mode (if the Py_DEBUG macro is defined), the Py_ALWAYS_INLINE macro does nothing.

It must be specified before the function return type. Usage:

static inline Py_ALWAYS_INLINE int random(void) { return 4; }

Added in version 3.11.

Py_CHARMASK(c)

引数は文字か、[-128, 127] あるいは [0, 255] の範囲の整数でなければなりません。このマクロは 符号なし文字 にキャストした c を返します。

Py_DEPRECATED(version)

Use this for deprecated declarations. The macro must be placed before the symbol name.

以下はプログラム例です:

Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);

バージョン 3.8 で変更: MSVC サポートが追加されました。

Py_GETENV(s)

Like getenv(s), but returns NULL if -E was passed on the command line (see PyConfig.use_environment).

Py_MAX(x, y)

x と y の最大値を返します。

Added in version 3.3.

Py_MEMBER_SIZE(type, member)

(type) 構造体の member のサイズをバイト単位で返します。

Added in version 3.6.

Py_MIN(x, y)

x と y の最小値を返します。

Added in version 3.3.

Py_NO_INLINE

Disable inlining on a function. For example, it reduces the C stack consumption: useful on LTO+PGO builds which heavily inline code (see bpo-33720 [https://bugs.python.org/issue?@action=redirect&bpo=33720]).

使い方:

Py_NO_INLINE static int random(void) { return 4; }

Added in version 3.11.

Py_STRINGIFY(x)

x を C 文字列へ変換します。例えば、 Py_STRINGIFY(123) は "123" を返します。

Added in version 3.4.

Py_UNREACHABLE()

Use this when you have a code path that cannot be reached by design. For example, in the default: clause in a switch statement for which all possible values are covered in case statements. Use this in places where you might be tempted to put an assert(0) or abort() call.

In release mode, the macro helps the compiler to optimize the code, and avoids a warning about unreachable code. For example, the macro is implemented with __builtin_unreachable() on GCC in release mode.

A use for Py_UNREACHABLE() is following a call a function that never returns but that is not declared _Py_NO_RETURN.

If a code path is very unlikely code but can be reached under exceptional case, this macro must not be used. For example, under low memory condition or if a system call returns a value out of the expected range. In this case, it's better to report the error to the caller. If the error cannot be reported to caller, Py_FatalError() can be used.

Added in version 3.7.

Py_UNUSED(arg)

Use this for unused arguments in a function definition to silence compiler warnings. Example: int func(int a, int Py_UNUSED(b)) { return a; }.

Added in version 3.4.

PyDoc_STRVAR(name, str)

Creates a variable with name name that can be used in docstrings. If Python is built without docstrings, the value will be empty.

Use PyDoc_STRVAR for docstrings to support building Python without docstrings, as specified in PEP 7 [https://peps.python.org/pep-0007/].

以下はプログラム例です:

PyDoc_STRVAR(pop_doc, "Remove and return the rightmost element.");

static PyMethodDef deque_methods[] = {
    // ...
    {"pop", (PyCFunction)deque_pop, METH_NOARGS, pop_doc},
    // ...
}

PyDoc_STR(str)

Creates a docstring for the given input string or an empty string if docstrings are disabled.

Use PyDoc_STR in specifying docstrings to support building Python without docstrings, as specified in PEP 7 [https://peps.python.org/pep-0007/].

以下はプログラム例です:

static PyMethodDef pysqlite_row_methods[] = {
    {"keys", (PyCFunction)pysqlite_row_keys, METH_NOARGS,
        PyDoc_STR("Returns the keys of the row.")},
    {NULL, NULL}
};

オブジェクト、型および参照カウント

Python/C API 関数は、 PyObject* 型の一つ以上の引数と戻り値を持ちます。この型は、任意の Python オブジェクトを表現する不透明 (opaque) なデータ型へのポインタです。 Python 言語は、全ての Python オブジェクト型をほとんどの状況 (例えば代入、スコープ規則 (scope rule)、引数渡し) で同様に扱います。ほとんど全ての Python オブジェクトはヒープ (heap) 上に置かれます: このため、 PyObject 型のオブジェクトは、自動記憶 (automatic) としても静的記憶 (static) としても宣言できません。 PyObject* 型のポインタ変数のみ宣言できます。唯一の例外は、型オブジェクトです; 型オブジェクトはメモリ解放 (deallocate) してはならないので、通常は静的記憶の PyTypeObject オブジェクトにします。

全ての Python オブジェクトには (Python 整数型ですら) 型 (type) と参照カウント (reference count) があります。あるオブジェクトの型は、そのオブジェクトがどの種類のオブジェクトか (例えば整数、リスト、ユーザ定義関数、など; その他多数については 標準型の階層 で説明しています) を決定します。よく知られている型については、各々マクロが存在して、あるオブジェクトがその型かどうか調べられます; 例えば、 PyList_Check(a) は、 a で示されたオブジェクトが Python リスト型のとき (かつそのときに限り) 真値を返します。

参照カウント法

The reference count is important because today's computers have a finite (and often severely limited) memory size; it counts how many different places there are that have a strong reference to an object. Such a place could be another object, or a global (or static) C variable, or a local variable in some C function. When the last strong reference to an object is released (i.e. its reference count becomes zero), the object is deallocated. If it contains references to other objects, those references are released. Those other objects may be deallocated in turn, if there are no more references to them, and so on. (There's an obvious problem with objects that reference each other here; for now, the solution is "don't do that.")

Reference counts are always manipulated explicitly. The normal way is to use the macro Py_INCREF() to take a new reference to an object (i.e. increment its reference count by one), and Py_DECREF() to release that reference (i.e. decrement the reference count by one). The Py_DECREF() macro is considerably more complex than the incref one, since it must check whether the reference count becomes zero and then cause the object's deallocator to be called. The deallocator is a function pointer contained in the object's type structure. The type-specific deallocator takes care of releasing references for other objects contained in the object if this is a compound object type, such as a list, as well as performing any additional finalization that's needed. There's no chance that the reference count can overflow; at least as many bits are used to hold the reference count as there are distinct memory locations in virtual memory (assuming sizeof(Py_ssize_t) >= sizeof(void*)). Thus, the reference count increment is a simple operation.

It is not necessary to hold a strong reference (i.e. increment the reference count) for every local variable that contains a pointer to an object. In theory, the object's reference count goes up by one when the variable is made to point to it and it goes down by one when the variable goes out of scope. However, these two cancel each other out, so at the end the reference count hasn't changed. The only real reason to use the reference count is to prevent the object from being deallocated as long as our variable is pointing to it. If we know that there is at least one other reference to the object that lives at least as long as our variable, there is no need to take a new strong reference (i.e. increment the reference count) temporarily. An important situation where this arises is in objects that are passed as arguments to C functions in an extension module that are called from Python; the call mechanism guarantees to hold a reference to every argument for the duration of the call.

However, a common pitfall is to extract an object from a list and hold on to it for a while without taking a new reference. Some other operation might conceivably remove the object from the list, releasing that reference, and possibly deallocating it. The real danger is that innocent-looking operations may invoke arbitrary Python code which could do this; there is a code path which allows control to flow back to the user from a Py_DECREF(), so almost any operation is potentially dangerous.

A safe approach is to always use the generic operations (functions whose name begins with PyObject_, PyNumber_, PySequence_ or PyMapping_). These operations always create a new strong reference (i.e. increment the reference count) of the object they return. This leaves the caller with the responsibility to call Py_DECREF() when they are done with the result; this soon becomes second nature.

参照カウントの詳細

The reference count behavior of functions in the Python/C API is best explained in terms of ownership of references. Ownership pertains to references, never to objects (objects are not owned: they are always shared). "Owning a reference" means being responsible for calling Py_DECREF on it when the reference is no longer needed. Ownership can also be transferred, meaning that the code that receives ownership of the reference then becomes responsible for eventually releasing it by calling Py_DECREF() or Py_XDECREF() when it's no longer needed---or passing on this responsibility (usually to its caller). When a function passes ownership of a reference on to its caller, the caller is said to receive a new reference. When no ownership is transferred, the caller is said to borrow the reference. Nothing needs to be done for a borrowed reference.

逆に、ある関数呼び出しで、あるオブジェクトへの参照を呼び出される関数に渡す際には、二つの可能性: 関数がオブジェクトへの参照を 盗み取る (steal) 場合と、そうでない場合があります。参照を盗む とは、関数に参照を渡したときに、参照の所有者がその関数になったと仮定し、関数の呼び出し元には所有権がなくなるということです。

参照を盗み取る関数はほとんどありません; 例外としてよく知られているのは、 PyList_SetItem() と PyTuple_SetItem() で、これらはシーケンスに入れる要素に対する参照を盗み取ります (しかし、要素の入る先のタプルやリストの参照は盗み取りません!)。これらの関数は、リストやタプルの中に新たに作成されたオブジェクトを入れていく際の常套的な書き方をしやすくするために、参照を盗み取るように設計されています; 例えば、 (1, 2, "three") というタプルを生成するコードは以下のようになります (とりあえず例外処理のことは忘れておきます; もっとよい書き方を後で示します):

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"));

ここで、 PyLong_FromLong() は新しい参照を返し、すぐに PyTuple_SetItem() に盗まれます。参照が盗まれた後もそのオブジェクトを利用したい場合は、参照盗む関数を呼び出す前に、 Py_INCREF() を利用してもう一つの参照を取得してください。

ちなみに、 PyTuple_SetItem() はタプルに値をセットするための 唯一の 方法です; タプルは変更不能なデータ型なので、 PySequence_SetItem() や PyObject_SetItem() を使うと上の操作は拒否されてしまいます。自分でタプルの値を入れていくつもりなら、 PyTuple_SetItem() だけしか使えません。

同じく、リストに値を入れていくコードは PyList_New() と PyList_SetItem() で書けます。

しかし実際には、タプルやリストを生成して値を入れる際には、上記のような方法はほとんど使いません。より汎用性のある関数、 Py_BuildValue() があり、ほとんどの主要なオブジェクトをフォーマット文字列 format string の指定に基づいて C の値から生成できます。例えば、上の二種類のコードブロックは、以下のように置き換えられます (エラーチェックにも配慮しています):

PyObject *tuple, *list;

tuple = Py_BuildValue("(iis)", 1, 2, "three");
list = Py_BuildValue("[iis]", 1, 2, "three");

It is much more common to use PyObject_SetItem() and friends with items whose references you are only borrowing, like arguments that were passed in to the function you are writing. In that case, their behaviour regarding references is much saner, since you don't have to take a new reference just so you can give that reference away ("have it be stolen"). For example, this function sets all items of a list (actually, any mutable sequence) to a given item:

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;
}

関数の戻り値の場合には、状況は少し異なります。ほとんどの関数については、参照を渡してもその参照に対する所有権が変わることがない一方で、あるオブジェクトに対する参照を返すような多くの関数は、参照に対する所有権を呼び出し側に与えます。理由は簡単です: 多くの場合、関数が返すオブジェクトはその場で (on the fly) 生成されるため、呼び出し側が得る参照は生成されたオブジェクトに対する唯一の参照になるからです。従って、 PyObject_GetItem() や PySequence_GetItem() のように、オブジェクトに対する参照を返す汎用の関数は、常に新たな参照を返します (呼び出し側が参照の所有者になります)。

重要なのは、関数が返す参照の所有権を持てるかどうかは、どの関数を呼び出すかだけによる、と理解することです --- 関数呼び出し時の お飾り (関数に引数として渡したオブジェクトの型) は この問題には関係ありません! 従って、 PyList_GetItem() を使ってリスト内の要素を得た場合には、参照の所有者にはなりません --- が、同じ要素を同じリストから PySequence_GetItem() (図らずもこの関数は全く同じ引数をとります) を使って取り出すと、返されたオブジェクトに対する参照を得ます。

以下は、整数からなるリストに対して各要素の合計を計算する関数をどのようにして書けるかを示した例です; 一つは PyList_GetItem() を使っていて、もう一つは PySequence_GetItem() を使っています。

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;
}

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;
}

型

他にも Python/C API において重要な役割を持つデータ型がいくつかあります; ほとんどは int, long, double, および char* といった、単なる C のデータ型です。また、モジュールで公開している関数を列挙する際に用いられる静的なテーブルや、新しいオブジェクト型におけるデータ属性を記述したり、複素数の値を記述したりするために構造体をいくつか使っています。これらの型については、その型を使う関数とともに説明してゆきます。

type Py_ssize_t

Part of the Stable ABI.

A signed integral type such that sizeof(Py_ssize_t) == sizeof(size_t). C99 doesn't define such a thing directly (size_t is an unsigned integral type). See PEP 353 [https://peps.python.org/pep-0353/] for details. PY_SSIZE_T_MAX is the largest positive value of type Py_ssize_t.

例外

Python プログラマは、特定のエラー処理が必要なときだけしか例外を扱う必要はありません; 処理しなかった例外は、処理の呼び出し側、そのまた呼び出し側、といった具合に、トップレベルのインタプリタ層まで自動的に伝播します。インタプリタ層は、スタックトレースバックと合わせて例外をユーザに報告します。

ところが、 C プログラマの場合、エラーチェックは常に明示的に行わねばなりません。 Python/C API の全ての関数は、関数のドキュメントで明確に説明がない限り例外を発行する可能性があります。一般的な話として、ある関数が何らかのエラーに遭遇すると、関数は例外を設定して、関数内における参照の所有権を全て放棄し、エラー値 (error indicator) を返します。ドキュメントに書かれてない場合、このエラー値は関数の戻り値の型によって、 NULL か -1 のどちらかになります。いくつかの関数ではブール型で真/偽を返し、偽はエラーを示します。きわめて少数の関数では明確なエラー指標を返さなかったり、あいまいな戻り値を返したりするので、 PyErr_Occurred() で明示的にエラーテストを行う必要があります。これらの例外は常に明示的にドキュメント化されます。

例外時の状態情報 (exception state)は、スレッド単位に用意された記憶領域 (per-thread storage) 内で管理されます (この記憶領域は、スレッドを使わないアプリケーションではグローバルな記憶領域と同じです)。一つのスレッドは二つの状態のどちらか: 例外が発生したか、まだ発生していないか、をとります。関数 PyErr_Occurred() を使うと、この状態を調べられます: この関数は例外が発生した際にはその例外型オブジェクトに対する借用参照 (borrowed reference) を返し、そうでないときには NULL を返します。例外状態を設定する関数は数多くあります: PyErr_SetString() はもっともよく知られている (が、もっとも汎用性のない) 例外を設定するための関数で、 PyErr_Clear() は例外状態情報を消し去る関数です。

完全な例外状態情報は、3 つのオブジェクト: 例外の型、例外の値、そしてトレースバック、からなります (どのオブジェクトも NULL を取り得ます)。これらの情報は、 Python の sys.exc_info() の結果と同じ意味を持ちます; とはいえ、 C と Python の例外状態情報は全く同じではありません: Python における例外オブジェクトは、Python の try ... except 文で最近処理したオブジェクトを表す一方、 C レベルの例外状態情報が存続するのは、渡された例外情報を sys.exc_info() その他に転送するよう取り計らう Python のバイトコードインタプリタのメインループに到達するまで、例外が関数の間で受け渡しされている間だけです。

Python 1.5 からは、Python で書かれたコードから例外状態情報にアクセスする方法として、推奨されていてスレッドセーフな方法は sys.exc_info() になっているので注意してください。この関数は Python コードの実行されているスレッドにおける例外状態情報を返します。また、これらの例外状態情報に対するアクセス手段は、両方とも意味づけ (semantics) が変更され、ある関数が例外を捕捉すると、その関数を実行しているスレッドの例外状態情報を保存して、呼び出し側の例外状態情報を維持するようになりました。この変更によって、無害そうに見える関数が現在扱っている例外を上書きすることで引き起こされる、例外処理コードでよくおきていたバグを抑止しています; また、トレースバック内のスタックフレームで参照されているオブジェクトがしばしば不必要に寿命を永らえていたのをなくしています。

一般的な原理として、ある関数が別の関数を呼び出して何らかの作業をさせるとき、呼び出し先の関数が例外を送出していないか調べなくてはならず、もし送出していれば、その例外状態情報は呼び出し側に渡されなければなりません。呼び出し元の関数はオブジェクト参照の所有権をすべて放棄し、エラー指標を返さなくてはなりませんが、余計に例外を設定する必要は ありません --- そんなことをすれば、たった今送出されたばかりの例外を上書きしてしまい、エラーの原因そのものに関する重要な情報を失うことになります。

A simple example of detecting exceptions and passing them on is shown in the sum_sequence() example above. It so happens that this example doesn't need to clean up any owned references when it detects an error. The following example function shows some error cleanup. First, to remind you why you like Python, we show the equivalent Python code:

def incr_item(dict, key):
    try:
        item = dict[key]
    except KeyError:
        item = 0
    dict[key] = item + 1

以下は対応するコードを C で完璧に書いたものです:

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 */
}

なんとこの例は C で goto 文を使うお勧めの方法まで示していますね! この例では、特定の例外を処理するために PyErr_ExceptionMatches() および PyErr_Clear() をどう使うかを示しています。また、所有権を持っている参照で、値が NULL になるかもしれないものを捨てるために Py_XDECREF() をどう使うかも示しています (関数名に 'X' が付いていることに注意してください; Py_DECREF() は NULL 参照に出くわすとクラッシュします)。正しく動作させるためには、所有権を持つ参照を保持するための変数を NULL で初期化することが重要です; 同様に、あらかじめ戻り値を定義する際には値を -1 (失敗) で初期化しておいて、最後の関数呼び出しまでうまくいった場合にのみ 0 (成功) に設定します。

Python の埋め込み

Python インタプリタの埋め込みを行う人 (いわば拡張モジュールの書き手の対極) が気にかけなければならない重要なタスクは、Python インタプリタの初期化処理 (initialization)、そしておそらくは終了処理 (finalization) です。インタプリタのほとんどの機能は、インタプリタの起動後しか使えません。

基本的な初期化処理を行う関数は Py_Initialize() です。この関数はロード済みのモジュールからなるテーブルを作成し、土台となるモジュール builtins, __main__, および sys を作成します。また、モジュール検索パス (sys.path) の初期化も行います。

Py_Initialize() does not set the "script argument list" (sys.argv). If this variable is needed by Python code that will be executed later, setting PyConfig.argv and PyConfig.parse_argv must be set: see Python Initialization Configuration.

ほとんどのシステムでは (特に Unix と Windows は、詳細がわずかに異なりはしますが)、 Py_Initialize() は標準の Python インタプリタ実行形式の場所に対する推定結果に基づいて、 Python のライブラリが Python インタプリタ実行形式からの相対パスで見つかるという仮定の下にモジュール検索パスを計算します。とりわけこの検索では、シェルコマンド検索パス (環境変数 PATH) 上に見つかった python という名前の実行ファイルの置かれているディレクトリの親ディレクトリからの相対で、 lib/pythonX.Y という名前のディレクトリを探します。

例えば、 Python 実行形式が /usr/local/bin/python で見つかったとすると、 Py_Initialize() はライブラリが /usr/local/lib/pythonX.Y にあるものと仮定します。 (実際には、このパスは "フォールバック (fallback)" のライブラリ位置でもあり、 python が PATH 上に無い場合に使われます。) ユーザは PYTHONHOME を設定することでこの動作をオーバライドしたり、 PYTHONPATH を設定して追加のディレクトリを標準モジュール検索パスの前に挿入したりできます。

The embedding application can steer the search by calling Py_SetProgramName(file) before calling Py_Initialize(). Note that PYTHONHOME still overrides this and PYTHONPATH is still inserted in front of the standard path. An application that requires total control has to provide its own implementation of Py_GetPath(), Py_GetPrefix(), Py_GetExecPrefix(), and Py_GetProgramFullPath() (all defined in Modules/getpath.c).

たまに、 Python を初期化前の状態にもどしたいことがあります。例えば、あるアプリケーションでは実行を最初からやりなおし (start over) させる (Py_Initialize() をもう一度呼び出させる) ようにしたいかもしれません。あるいは、アプリケーションが Python を一旦使い終えて、Python が確保したメモリを解放させたいかもしれません。 Py_FinalizeEx() を使うとこうした処理を実現できます。また、関数 Py_IsInitialized() は、Python が現在初期化済みの状態にある場合に真を返します。これらの関数についてのさらなる情報は、後の章で説明します。 Py_FinalizeEx() がPythonインタプリタに確保された全てのメモリを 解放するわけではない ことに注意してください。例えば、拡張モジュールによって確保されたメモリは、現在のところ解放する事ができません。

デバッグ版ビルド (Debugging Builds)

インタプリタと拡張モジュールに対しての追加チェックをするためのいくつかのマクロを有効にしてPythonをビルドすることができます。これらのチェックは、実行時に大きなオーバーヘッドを生じる傾向があります。なので、デフォルトでは有効にされていません。

Pythonデバッグ版ビルドの全ての種類のリストが、Pythonソース配布(source distribution)の中の Misc/SpecialBuilds.txt にあります。参照カウントのトレース、メモリアロケータのデバッグ、インタプリタのメインループの低レベルプロファイリングが利用可能です。よく使われるビルドについてのみ、この節の残りの部分で説明します。

Py_DEBUG

Compiling the interpreter with the Py_DEBUG macro defined produces what is generally meant by a debug build of Python. Py_DEBUG is enabled in the Unix build by adding --with-pydebug to the ./configure command. It is also implied by the presence of the not-Python-specific _DEBUG macro. When Py_DEBUG is enabled in the Unix build, compiler optimization is disabled.

In addition to the reference count debugging described below, extra checks are performed, see Python Debug Build.

Py_TRACE_REFS を宣言すると、参照トレースが有効になります (configure --with-trace-refs オプション を参照してください)。全ての PyObject に二つのフィールドを追加することで、使用中のオブジェクトの循環二重連結リストが管理されます。全ての割り当て(allocation)がトレースされます。終了時に、全ての残っているオブジェクトが表示されます。 (インタラクティブモードでは、インタプリタによる文の実行のたびに表示されます。)

より詳しい情報については、Pythonのソース配布(source distribution)の中の Misc/SpecialBuilds.txt を参照してください。

C API の安定性

Unless documented otherwise, Python's C API is covered by the Backwards Compatibility Policy, PEP 387 [https://peps.python.org/pep-0387/]. Most changes to it are source-compatible (typically by only adding new API). Changing existing API or removing API is only done after a deprecation period or to fix serious issues.

CPython's Application Binary Interface (ABI) is forward- and backwards-compatible across a minor release (if these are compiled the same way; see プラットフォームで考慮すべき点 below). So, code compiled for Python 3.10.0 will work on 3.10.8 and vice versa, but will need to be compiled separately for 3.9.x and 3.11.x.

There are two tiers of C API with different stability expectations:

Unstable API, may change in minor versions without a deprecation period. It is marked by the PyUnstable prefix in names.

Limited API, is compatible across several minor releases. When Py_LIMITED_API is defined, only this subset is exposed from Python.h.

These are discussed in more detail below.

Names prefixed by an underscore, such as _Py_InternalState, are private API that can change without notice even in patch releases. If you need to use this API, consider reaching out to CPython developers [https://discuss.python.org/c/core-dev/c-api/30] to discuss adding public API for your use case.

Unstable C API

Any API named with the PyUnstable prefix exposes CPython implementation details, and may change in every minor release (e.g. from 3.9 to 3.10) without any deprecation warnings. However, it will not change in a bugfix release (e.g. from 3.10.0 to 3.10.1).

It is generally intended for specialized, low-level tools like debuggers.

Projects that use this API are expected to follow CPython development and spend extra effort adjusting to changes.

安定 ABI (Stable Appliction Binary Interface)

For simplicity, this document talks about extensions, but the Limited API and Stable ABI work the same way for all uses of the API – for example, embedding Python.

Limited C API

Python 3.2 introduced the Limited API, a subset of Python's C API. Extensions that only use the Limited API can be compiled once and work with multiple versions of Python. Contents of the Limited API are listed below.

Py_LIMITED_API

このマクロを Python.h をインクルードする前に定義することで、 Limited API のみを使用することを選択し、 Limited API バージョンを選択することができます。

Define Py_LIMITED_API to the value of PY_VERSION_HEX corresponding to the lowest Python version your extension supports. The extension will work without recompilation with all Python 3 releases from the specified one onward, and can use Limited API introduced up to that version.

PY_VERSION_HEX マクロを直接使うのではなく、将来の Python のバージョンでコンパイルするときの安定性のために、最小のマイナーバージョン(例えば、 Python 3.10なら 0x030A0000 )をハードコードします。

また、 Py_LIMITED_API を 3 に定義することができます。これは 0x03020000 (Python 3.2, Limited API が導入されたバージョン)と同じように動作します。

Stable ABI

To enable this, Python provides a Stable ABI: a set of symbols that will remain compatible across Python 3.x versions.

The Stable ABI contains symbols exposed in the Limited API, but also other ones – for example, functions necessary to support older versions of the Limited API.

Windows では、 Stable ABI を使用する拡張機能は、 python39.dll のようなバージョン固有のライブラリではなく、 python3.dll に対してリンクする必要があります。

いくつかのプラットフォームでは、 Python は abi3 タグで名付けられた共有ライブラリファイルを探して読み込みます(例: mymodule.abi3.so)。このような拡張モジュールが Stable ABI に適合しているかどうかはチェックされません。ユーザー(またはそのパッケージングツール)は、たとえば 3.10+ Limited API でビルドされた拡張モジュールが、それ以下のバージョンの Python にインストールされないことを確認する必要があります。

Stable ABI に含まれるすべての関数は、マクロとしてだけでなく、 Python の共有ライブラリの関数として存在します。そのため、Cプリプロセッサを使用しない言語から使用することができます。

APIスコープとパフォーマンスの制限

Limited API の目標は、フル C API で可能なすべてのことを実現することですが、おそらく性能上の制約があります。

例えば、 PyList_GetItem() は利用可能ですが、その “unsafe” マクロの変種 PyList_GET_ITEM() は利用できません。このマクロは、リストオブジェクトのバージョン固有の実装の詳細に依存することができるため、より高速に処理することができます。

Py_LIMITED_API を定義しないと、いくつかの C API 関数がインライン化されたり、マクロに置き換わったりします。Py_LIMITED_API を定義すると、このインライン化が無効になり、 Python のデータ構造が改善されても安定した動作が可能になりますが、性能が低下する可能性があります。

Py_LIMITED_API の定義を省くことで、 Limited API 拡張をバージョン固有の ABI でコンパイルすることが可能です。これにより、その Python のバージョンでパフォーマンスを向上させることができますが、互換性は制限されます。Py_LIMITED_API でコンパイルすると、バージョンに依存しない拡張機能が利用できない場合、例えば、次期 Python バージョンのプレリリースに対応した拡張モジュールを配布することができるようになります。

制限付きAPIの注意点

Note that compiling with Py_LIMITED_API is not a complete guarantee that code conforms to the Limited API or the Stable ABI. Py_LIMITED_API only covers definitions, but an API also includes other issues, such as expected semantics.

Py_LIMITED_API が防げない問題の1つは、 Python の下位バージョンでは無効な引数を持つ関数を呼び出すことです。例えば、引数に NULL を受け取る関数を考えてみましょう。Python 3.9 では NULL はデフォルトの挙動を選択しますが、Python 3.8 ではこの引数は直接使用され、 NULL の参照外れを起こしクラッシュします。同様の引数は、構造体のフィールドに対しても機能します。

もう一つの問題は、一部の構造体フィールドがLimited APIの一部であるにもかかわらず、 Py_LIMITED_API が定義されたときに現在非表示になっていないことです。

これらの理由から、私たちは拡張モジュールがサポートする すべての マイナーな Python バージョンでテストすること、そしてできれば 最も低い バージョンでビルドすることを推奨します。

また、使用するすべての API のドキュメントを確認し、それが明示的に Limited API の一部であるかどうかをチェックすることをお勧めします。Py_LIMITED_API が定義されていても、技術的な理由で(あるいはバグとして意図せず)いくつかのプライベート宣言が公開されることがあります。

Python 3.8 で Py_LIMITED_API をコンパイルすると、その拡張モジュールは Python 3.12 で動作しますが、必ずしも Python 3.12 で コンパイル できるとは限らないことに注意してください。特に、Limited API の一部は、 Stable ABI が安定している限り、非推奨で削除されるかもしれません。

プラットフォームで考慮すべき点

ABI stability depends not only on Python, but also on the compiler used, lower-level libraries and compiler options. For the purposes of the Stable ABI, these details define a “platform”. They usually depend on the OS type and processor architecture

特定のプラットフォーム上のすべての Python バージョンが安定版 ABI を破壊しない方法でビルドされていることを保証するのは、 Python の各特定配布者の責任です。これは python.org や多くのサードパーティーの配布元からの Windows と macOS のリリースの場合です。

限定版APIの内容

Currently, the Limited API includes the following items:

PY_VECTORCALL_ARGUMENTS_OFFSET

PyAIter_Check()

PyArg_Parse()

PyArg_ParseTuple()

PyArg_ParseTupleAndKeywords()

PyArg_UnpackTuple()

PyArg_VaParse()

PyArg_VaParseTupleAndKeywords()

PyArg_ValidateKeywordArguments()

PyBaseObject_Type

PyBool_FromLong()

PyBool_Type

PyBuffer_FillContiguousStrides()

PyBuffer_FillInfo()

PyBuffer_FromContiguous()

PyBuffer_GetPointer()

PyBuffer_IsContiguous()

PyBuffer_Release()

PyBuffer_SizeFromFormat()

PyBuffer_ToContiguous()

PyByteArrayIter_Type

PyByteArray_AsString()

PyByteArray_Concat()

PyByteArray_FromObject()

PyByteArray_FromStringAndSize()

PyByteArray_Resize()

PyByteArray_Size()

PyByteArray_Type

PyBytesIter_Type

PyBytes_AsString()

PyBytes_AsStringAndSize()

PyBytes_Concat()

PyBytes_ConcatAndDel()

PyBytes_DecodeEscape()

PyBytes_FromFormat()

PyBytes_FromFormatV()

PyBytes_FromObject()

PyBytes_FromString()

PyBytes_FromStringAndSize()

PyBytes_Repr()

PyBytes_Size()

PyBytes_Type

PyCFunction

PyCFunctionWithKeywords

PyCFunction_Call()

PyCFunction_GetFlags()

PyCFunction_GetFunction()

PyCFunction_GetSelf()

PyCFunction_New()

PyCFunction_NewEx()

PyCFunction_Type

PyCMethod_New()

PyCallIter_New()

PyCallIter_Type

PyCallable_Check()

PyCapsule_Destructor

PyCapsule_GetContext()

PyCapsule_GetDestructor()

PyCapsule_GetName()

PyCapsule_GetPointer()

PyCapsule_Import()

PyCapsule_IsValid()

PyCapsule_New()

PyCapsule_SetContext()

PyCapsule_SetDestructor()

PyCapsule_SetName()

PyCapsule_SetPointer()

PyCapsule_Type

PyClassMethodDescr_Type

PyCodec_BackslashReplaceErrors()

PyCodec_Decode()

PyCodec_Decoder()

PyCodec_Encode()

PyCodec_Encoder()

PyCodec_IgnoreErrors()

PyCodec_IncrementalDecoder()

PyCodec_IncrementalEncoder()

PyCodec_KnownEncoding()

PyCodec_LookupError()

PyCodec_NameReplaceErrors()

PyCodec_Register()

PyCodec_RegisterError()

PyCodec_ReplaceErrors()

PyCodec_StreamReader()

PyCodec_StreamWriter()

PyCodec_StrictErrors()

PyCodec_Unregister()

PyCodec_XMLCharRefReplaceErrors()

PyComplex_FromDoubles()

PyComplex_ImagAsDouble()

PyComplex_RealAsDouble()

PyComplex_Type

PyDescr_NewClassMethod()

PyDescr_NewGetSet()

PyDescr_NewMember()

PyDescr_NewMethod()

PyDictItems_Type

PyDictIterItem_Type

PyDictIterKey_Type

PyDictIterValue_Type

PyDictKeys_Type

PyDictProxy_New()

PyDictProxy_Type

PyDictRevIterItem_Type

PyDictRevIterKey_Type

PyDictRevIterValue_Type

PyDictValues_Type

PyDict_Clear()

PyDict_Contains()

PyDict_Copy()

PyDict_DelItem()

PyDict_DelItemString()

PyDict_GetItem()

PyDict_GetItemString()

PyDict_GetItemWithError()

PyDict_Items()

PyDict_Keys()

PyDict_Merge()

PyDict_MergeFromSeq2()

PyDict_New()

PyDict_Next()

PyDict_SetItem()

PyDict_SetItemString()

PyDict_Size()

PyDict_Type

PyDict_Update()

PyDict_Values()

PyEllipsis_Type

PyEnum_Type

PyErr_BadArgument()

PyErr_BadInternalCall()

PyErr_CheckSignals()

PyErr_Clear()

PyErr_Display()

PyErr_DisplayException()

PyErr_ExceptionMatches()

PyErr_Fetch()

PyErr_Format()

PyErr_FormatV()

PyErr_GetExcInfo()

PyErr_GetHandledException()

PyErr_GetRaisedException()

PyErr_GivenExceptionMatches()

PyErr_NewException()

PyErr_NewExceptionWithDoc()

PyErr_NoMemory()

PyErr_NormalizeException()

PyErr_Occurred()

PyErr_Print()

PyErr_PrintEx()

PyErr_ProgramText()

PyErr_ResourceWarning()

PyErr_Restore()

PyErr_SetExcFromWindowsErr()

PyErr_SetExcFromWindowsErrWithFilename()

PyErr_SetExcFromWindowsErrWithFilenameObject()

PyErr_SetExcFromWindowsErrWithFilenameObjects()

PyErr_SetExcInfo()

PyErr_SetFromErrno()

PyErr_SetFromErrnoWithFilename()

PyErr_SetFromErrnoWithFilenameObject()

PyErr_SetFromErrnoWithFilenameObjects()

PyErr_SetFromWindowsErr()

PyErr_SetFromWindowsErrWithFilename()

PyErr_SetHandledException()

PyErr_SetImportError()

PyErr_SetImportErrorSubclass()

PyErr_SetInterrupt()

PyErr_SetInterruptEx()

PyErr_SetNone()

PyErr_SetObject()

PyErr_SetRaisedException()

PyErr_SetString()

PyErr_SyntaxLocation()

PyErr_SyntaxLocationEx()

PyErr_WarnEx()

PyErr_WarnExplicit()

PyErr_WarnFormat()

PyErr_WriteUnraisable()

PyEval_AcquireLock()

PyEval_AcquireThread()

PyEval_CallFunction()

PyEval_CallMethod()

PyEval_CallObjectWithKeywords()

PyEval_EvalCode()

PyEval_EvalCodeEx()

PyEval_EvalFrame()

PyEval_EvalFrameEx()

PyEval_GetBuiltins()

PyEval_GetFrame()

PyEval_GetFuncDesc()

PyEval_GetFuncName()

PyEval_GetGlobals()

PyEval_GetLocals()

PyEval_InitThreads()

PyEval_ReleaseLock()

PyEval_ReleaseThread()

PyEval_RestoreThread()

PyEval_SaveThread()

PyEval_ThreadsInitialized()

PyExc_ArithmeticError

PyExc_AssertionError

PyExc_AttributeError

PyExc_BaseException

PyExc_BaseExceptionGroup

PyExc_BlockingIOError

PyExc_BrokenPipeError

PyExc_BufferError

PyExc_BytesWarning

PyExc_ChildProcessError

PyExc_ConnectionAbortedError

PyExc_ConnectionError

PyExc_ConnectionRefusedError

PyExc_ConnectionResetError

PyExc_DeprecationWarning

PyExc_EOFError

PyExc_EncodingWarning

PyExc_EnvironmentError

PyExc_Exception

PyExc_FileExistsError

PyExc_FileNotFoundError

PyExc_FloatingPointError

PyExc_FutureWarning

PyExc_GeneratorExit

PyExc_IOError

PyExc_ImportError

PyExc_ImportWarning

PyExc_IndentationError

PyExc_IndexError

PyExc_InterruptedError

PyExc_IsADirectoryError

PyExc_KeyError

PyExc_KeyboardInterrupt

PyExc_LookupError

PyExc_MemoryError

PyExc_ModuleNotFoundError

PyExc_NameError

PyExc_NotADirectoryError

PyExc_NotImplementedError

PyExc_OSError

PyExc_OverflowError

PyExc_PendingDeprecationWarning

PyExc_PermissionError

PyExc_ProcessLookupError

PyExc_RecursionError

PyExc_ReferenceError

PyExc_ResourceWarning

PyExc_RuntimeError

PyExc_RuntimeWarning

PyExc_StopAsyncIteration

PyExc_StopIteration

PyExc_SyntaxError

PyExc_SyntaxWarning

PyExc_SystemError

PyExc_SystemExit

PyExc_TabError

PyExc_TimeoutError

PyExc_TypeError

PyExc_UnboundLocalError

PyExc_UnicodeDecodeError

PyExc_UnicodeEncodeError

PyExc_UnicodeError

PyExc_UnicodeTranslateError

PyExc_UnicodeWarning

PyExc_UserWarning

PyExc_ValueError

PyExc_Warning

PyExc_WindowsError

PyExc_ZeroDivisionError

PyExceptionClass_Name()

PyException_GetArgs()

PyException_GetCause()

PyException_GetContext()

PyException_GetTraceback()

PyException_SetArgs()

PyException_SetCause()

PyException_SetContext()

PyException_SetTraceback()

PyFile_FromFd()

PyFile_GetLine()

PyFile_WriteObject()

PyFile_WriteString()

PyFilter_Type

PyFloat_AsDouble()

PyFloat_FromDouble()

PyFloat_FromString()

PyFloat_GetInfo()

PyFloat_GetMax()

PyFloat_GetMin()

PyFloat_Type

PyFrameObject

PyFrame_GetCode()

PyFrame_GetLineNumber()

PyFrozenSet_New()

PyFrozenSet_Type

PyGC_Collect()

PyGC_Disable()

PyGC_Enable()

PyGC_IsEnabled()

PyGILState_Ensure()

PyGILState_GetThisThreadState()

PyGILState_Release()

PyGILState_STATE

PyGetSetDef

PyGetSetDescr_Type

PyImport_AddModule()

PyImport_AddModuleObject()

PyImport_AppendInittab()

PyImport_ExecCodeModule()

PyImport_ExecCodeModuleEx()

PyImport_ExecCodeModuleObject()

PyImport_ExecCodeModuleWithPathnames()

PyImport_GetImporter()

PyImport_GetMagicNumber()

PyImport_GetMagicTag()

PyImport_GetModule()

PyImport_GetModuleDict()

PyImport_Import()

PyImport_ImportFrozenModule()

PyImport_ImportFrozenModuleObject()

PyImport_ImportModule()

PyImport_ImportModuleLevel()

PyImport_ImportModuleLevelObject()

PyImport_ImportModuleNoBlock()

PyImport_ReloadModule()

PyIndex_Check()

PyInterpreterState

PyInterpreterState_Clear()

PyInterpreterState_Delete()

PyInterpreterState_Get()

PyInterpreterState_GetDict()

PyInterpreterState_GetID()

PyInterpreterState_New()

PyIter_Check()

PyIter_Next()

PyIter_Send()

PyListIter_Type

PyListRevIter_Type

PyList_Append()

PyList_AsTuple()

PyList_GetItem()

PyList_GetSlice()

PyList_Insert()

PyList_New()

PyList_Reverse()

PyList_SetItem()

PyList_SetSlice()

PyList_Size()

PyList_Sort()

PyList_Type

PyLongObject

PyLongRangeIter_Type

PyLong_AsDouble()

PyLong_AsLong()

PyLong_AsLongAndOverflow()

PyLong_AsLongLong()

PyLong_AsLongLongAndOverflow()

PyLong_AsSize_t()

PyLong_AsSsize_t()

PyLong_AsUnsignedLong()

PyLong_AsUnsignedLongLong()

PyLong_AsUnsignedLongLongMask()

PyLong_AsUnsignedLongMask()

PyLong_AsVoidPtr()

PyLong_FromDouble()

PyLong_FromLong()

PyLong_FromLongLong()

PyLong_FromSize_t()

PyLong_FromSsize_t()

PyLong_FromString()

PyLong_FromUnsignedLong()

PyLong_FromUnsignedLongLong()

PyLong_FromVoidPtr()

PyLong_GetInfo()

PyLong_Type

PyMap_Type

PyMapping_Check()

PyMapping_GetItemString()

PyMapping_HasKey()

PyMapping_HasKeyString()

PyMapping_Items()

PyMapping_Keys()

PyMapping_Length()

PyMapping_SetItemString()

PyMapping_Size()

PyMapping_Values()

PyMem_Calloc()

PyMem_Free()

PyMem_Malloc()

PyMem_Realloc()

PyMemberDef

PyMemberDescr_Type

PyMember_GetOne()

PyMember_SetOne()

PyMemoryView_FromBuffer()

PyMemoryView_FromMemory()

PyMemoryView_FromObject()

PyMemoryView_GetContiguous()

PyMemoryView_Type

PyMethodDef

PyMethodDescr_Type

PyModuleDef

PyModuleDef_Base

PyModuleDef_Init()

PyModuleDef_Type

PyModule_AddFunctions()

PyModule_AddIntConstant()

PyModule_AddObject()

PyModule_AddObjectRef()

PyModule_AddStringConstant()

PyModule_AddType()

PyModule_Create2()

PyModule_ExecDef()

PyModule_FromDefAndSpec2()

PyModule_GetDef()

PyModule_GetDict()

PyModule_GetFilename()

PyModule_GetFilenameObject()

PyModule_GetName()

PyModule_GetNameObject()

PyModule_GetState()

PyModule_New()

PyModule_NewObject()

PyModule_SetDocString()

PyModule_Type

PyNumber_Absolute()

PyNumber_Add()

PyNumber_And()

PyNumber_AsSsize_t()

PyNumber_Check()

PyNumber_Divmod()

PyNumber_Float()

PyNumber_FloorDivide()

PyNumber_InPlaceAdd()

PyNumber_InPlaceAnd()

PyNumber_InPlaceFloorDivide()

PyNumber_InPlaceLshift()

PyNumber_InPlaceMatrixMultiply()

PyNumber_InPlaceMultiply()

PyNumber_InPlaceOr()

PyNumber_InPlacePower()

PyNumber_InPlaceRemainder()

PyNumber_InPlaceRshift()

PyNumber_InPlaceSubtract()

PyNumber_InPlaceTrueDivide()

PyNumber_InPlaceXor()

PyNumber_Index()

PyNumber_Invert()

PyNumber_Long()

PyNumber_Lshift()

PyNumber_MatrixMultiply()

PyNumber_Multiply()

PyNumber_Negative()

PyNumber_Or()

PyNumber_Positive()

PyNumber_Power()

PyNumber_Remainder()

PyNumber_Rshift()

PyNumber_Subtract()

PyNumber_ToBase()

PyNumber_TrueDivide()

PyNumber_Xor()

PyOS_AfterFork()

PyOS_AfterFork_Child()

PyOS_AfterFork_Parent()

PyOS_BeforeFork()

PyOS_CheckStack()

PyOS_FSPath()

PyOS_InputHook

PyOS_InterruptOccurred()

PyOS_double_to_string()

PyOS_getsig()

PyOS_mystricmp()

PyOS_mystrnicmp()

PyOS_setsig()

PyOS_sighandler_t

PyOS_snprintf()

PyOS_string_to_double()

PyOS_strtol()

PyOS_strtoul()

PyOS_vsnprintf()

PyObject

PyObject.ob_refcnt

PyObject.ob_type

PyObject_ASCII()

PyObject_AsCharBuffer()

PyObject_AsFileDescriptor()

PyObject_AsReadBuffer()

PyObject_AsWriteBuffer()

PyObject_Bytes()

PyObject_Call()

PyObject_CallFunction()

PyObject_CallFunctionObjArgs()

PyObject_CallMethod()

PyObject_CallMethodObjArgs()

PyObject_CallNoArgs()

PyObject_CallObject()

PyObject_Calloc()

PyObject_CheckBuffer()

PyObject_CheckReadBuffer()

PyObject_ClearWeakRefs()

PyObject_CopyData()

PyObject_DelItem()

PyObject_DelItemString()

PyObject_Dir()

PyObject_Format()

PyObject_Free()

PyObject_GC_Del()

PyObject_GC_IsFinalized()

PyObject_GC_IsTracked()

PyObject_GC_Track()

PyObject_GC_UnTrack()

PyObject_GenericGetAttr()

PyObject_GenericGetDict()

PyObject_GenericSetAttr()

PyObject_GenericSetDict()

PyObject_GetAIter()

PyObject_GetAttr()

PyObject_GetAttrString()

PyObject_GetBuffer()

PyObject_GetItem()

PyObject_GetIter()

PyObject_GetTypeData()

PyObject_HasAttr()

PyObject_HasAttrString()

PyObject_Hash()

PyObject_HashNotImplemented()

PyObject_Init()

PyObject_InitVar()

PyObject_IsInstance()

PyObject_IsSubclass()

PyObject_IsTrue()

PyObject_Length()

PyObject_Malloc()

PyObject_Not()

PyObject_Realloc()

PyObject_Repr()

PyObject_RichCompare()

PyObject_RichCompareBool()

PyObject_SelfIter()

PyObject_SetAttr()

PyObject_SetAttrString()

PyObject_SetItem()

PyObject_Size()

PyObject_Str()

PyObject_Type()

PyObject_Vectorcall()

PyObject_VectorcallMethod()

PyProperty_Type

PyRangeIter_Type

PyRange_Type

PyReversed_Type

PySeqIter_New()

PySeqIter_Type

PySequence_Check()

PySequence_Concat()

PySequence_Contains()

PySequence_Count()

PySequence_DelItem()

PySequence_DelSlice()

PySequence_Fast()

PySequence_GetItem()

PySequence_GetSlice()

PySequence_In()

PySequence_InPlaceConcat()

PySequence_InPlaceRepeat()

PySequence_Index()

PySequence_Length()

PySequence_List()

PySequence_Repeat()

PySequence_SetItem()

PySequence_SetSlice()

PySequence_Size()

PySequence_Tuple()

PySetIter_Type

PySet_Add()

PySet_Clear()

PySet_Contains()

PySet_Discard()

PySet_New()

PySet_Pop()

PySet_Size()

PySet_Type

PySlice_AdjustIndices()

PySlice_GetIndices()

PySlice_GetIndicesEx()

PySlice_New()

PySlice_Type

PySlice_Unpack()

PyState_AddModule()

PyState_FindModule()

PyState_RemoveModule()

PyStructSequence_Desc

PyStructSequence_Field

PyStructSequence_GetItem()

PyStructSequence_New()

PyStructSequence_NewType()

PyStructSequence_SetItem()

PyStructSequence_UnnamedField

PySuper_Type

PySys_AddWarnOption()

PySys_AddWarnOptionUnicode()

PySys_AddXOption()

PySys_FormatStderr()

PySys_FormatStdout()

PySys_GetObject()

PySys_GetXOptions()

PySys_HasWarnOptions()

PySys_ResetWarnOptions()

PySys_SetArgv()

PySys_SetArgvEx()

PySys_SetObject()

PySys_SetPath()

PySys_WriteStderr()

PySys_WriteStdout()

PyThreadState

PyThreadState_Clear()

PyThreadState_Delete()

PyThreadState_Get()

PyThreadState_GetDict()

PyThreadState_GetFrame()

PyThreadState_GetID()

PyThreadState_GetInterpreter()

PyThreadState_New()

PyThreadState_SetAsyncExc()

PyThreadState_Swap()

PyThread_GetInfo()

PyThread_ReInitTLS()

PyThread_acquire_lock()

PyThread_acquire_lock_timed()

PyThread_allocate_lock()

PyThread_create_key()

PyThread_delete_key()

PyThread_delete_key_value()

PyThread_exit_thread()

PyThread_free_lock()

PyThread_get_key_value()

PyThread_get_stacksize()

PyThread_get_thread_ident()

PyThread_get_thread_native_id()

PyThread_init_thread()

PyThread_release_lock()

PyThread_set_key_value()

PyThread_set_stacksize()

PyThread_start_new_thread()

PyThread_tss_alloc()

PyThread_tss_create()

PyThread_tss_delete()

PyThread_tss_free()

PyThread_tss_get()

PyThread_tss_is_created()

PyThread_tss_set()

PyTraceBack_Here()

PyTraceBack_Print()

PyTraceBack_Type

PyTupleIter_Type

PyTuple_GetItem()

PyTuple_GetSlice()

PyTuple_New()

PyTuple_Pack()

PyTuple_SetItem()

PyTuple_Size()

PyTuple_Type

PyTypeObject

PyType_ClearCache()

PyType_FromMetaclass()

PyType_FromModuleAndSpec()

PyType_FromSpec()

PyType_FromSpecWithBases()

PyType_GenericAlloc()

PyType_GenericNew()

PyType_GetFlags()

PyType_GetModule()

PyType_GetModuleState()

PyType_GetName()

PyType_GetQualName()

PyType_GetSlot()

PyType_GetTypeDataSize()

PyType_IsSubtype()

PyType_Modified()

PyType_Ready()

PyType_Slot

PyType_Spec

PyType_Type

PyUnicodeDecodeError_Create()

PyUnicodeDecodeError_GetEncoding()

PyUnicodeDecodeError_GetEnd()

PyUnicodeDecodeError_GetObject()

PyUnicodeDecodeError_GetReason()

PyUnicodeDecodeError_GetStart()

PyUnicodeDecodeError_SetEnd()

PyUnicodeDecodeError_SetReason()

PyUnicodeDecodeError_SetStart()

PyUnicodeEncodeError_GetEncoding()

PyUnicodeEncodeError_GetEnd()

PyUnicodeEncodeError_GetObject()

PyUnicodeEncodeError_GetReason()

PyUnicodeEncodeError_GetStart()

PyUnicodeEncodeError_SetEnd()

PyUnicodeEncodeError_SetReason()

PyUnicodeEncodeError_SetStart()

PyUnicodeIter_Type

PyUnicodeTranslateError_GetEnd()

PyUnicodeTranslateError_GetObject()

PyUnicodeTranslateError_GetReason()

PyUnicodeTranslateError_GetStart()

PyUnicodeTranslateError_SetEnd()

PyUnicodeTranslateError_SetReason()

PyUnicodeTranslateError_SetStart()

PyUnicode_Append()

PyUnicode_AppendAndDel()

PyUnicode_AsASCIIString()

PyUnicode_AsCharmapString()

PyUnicode_AsDecodedObject()

PyUnicode_AsDecodedUnicode()

PyUnicode_AsEncodedObject()

PyUnicode_AsEncodedString()

PyUnicode_AsEncodedUnicode()

PyUnicode_AsLatin1String()

PyUnicode_AsMBCSString()

PyUnicode_AsRawUnicodeEscapeString()

PyUnicode_AsUCS4()

PyUnicode_AsUCS4Copy()

PyUnicode_AsUTF16String()

PyUnicode_AsUTF32String()

PyUnicode_AsUTF8AndSize()

PyUnicode_AsUTF8String()

PyUnicode_AsUnicodeEscapeString()

PyUnicode_AsWideChar()

PyUnicode_AsWideCharString()

PyUnicode_BuildEncodingMap()

PyUnicode_Compare()

PyUnicode_CompareWithASCIIString()

PyUnicode_Concat()

PyUnicode_Contains()

PyUnicode_Count()

PyUnicode_Decode()

PyUnicode_DecodeASCII()

PyUnicode_DecodeCharmap()

PyUnicode_DecodeCodePageStateful()

PyUnicode_DecodeFSDefault()

PyUnicode_DecodeFSDefaultAndSize()

PyUnicode_DecodeLatin1()

PyUnicode_DecodeLocale()

PyUnicode_DecodeLocaleAndSize()

PyUnicode_DecodeMBCS()

PyUnicode_DecodeMBCSStateful()

PyUnicode_DecodeRawUnicodeEscape()

PyUnicode_DecodeUTF16()

PyUnicode_DecodeUTF16Stateful()

PyUnicode_DecodeUTF32()

PyUnicode_DecodeUTF32Stateful()

PyUnicode_DecodeUTF7()

PyUnicode_DecodeUTF7Stateful()

PyUnicode_DecodeUTF8()

PyUnicode_DecodeUTF8Stateful()

PyUnicode_DecodeUnicodeEscape()

PyUnicode_EncodeCodePage()

PyUnicode_EncodeFSDefault()

PyUnicode_EncodeLocale()

PyUnicode_FSConverter()

PyUnicode_FSDecoder()

PyUnicode_Find()

PyUnicode_FindChar()

PyUnicode_Format()

PyUnicode_FromEncodedObject()

PyUnicode_FromFormat()

PyUnicode_FromFormatV()

PyUnicode_FromObject()

PyUnicode_FromOrdinal()

PyUnicode_FromString()

PyUnicode_FromStringAndSize()

PyUnicode_FromWideChar()

PyUnicode_GetDefaultEncoding()

PyUnicode_GetLength()

PyUnicode_InternFromString()

PyUnicode_InternInPlace()

PyUnicode_IsIdentifier()

PyUnicode_Join()

PyUnicode_Partition()

PyUnicode_RPartition()

PyUnicode_RSplit()

PyUnicode_ReadChar()

PyUnicode_Replace()

PyUnicode_Resize()

PyUnicode_RichCompare()

PyUnicode_Split()

PyUnicode_Splitlines()

PyUnicode_Substring()

PyUnicode_Tailmatch()

PyUnicode_Translate()

PyUnicode_Type

PyUnicode_WriteChar()

PyVarObject

PyVarObject.ob_base

PyVarObject.ob_size

PyVectorcall_Call()

PyVectorcall_NARGS()

PyWeakReference

PyWeakref_GetObject()

PyWeakref_NewProxy()

PyWeakref_NewRef()

PyWrapperDescr_Type

PyWrapper_New()

PyZip_Type

Py_AddPendingCall()

Py_AtExit()

Py_BEGIN_ALLOW_THREADS

Py_BLOCK_THREADS

Py_BuildValue()

Py_BytesMain()

Py_CompileString()

Py_DecRef()

Py_DecodeLocale()

Py_END_ALLOW_THREADS

Py_EncodeLocale()

Py_EndInterpreter()

Py_EnterRecursiveCall()

Py_Exit()

Py_FatalError()

Py_FileSystemDefaultEncodeErrors

Py_FileSystemDefaultEncoding

Py_Finalize()

Py_FinalizeEx()

Py_GenericAlias()

Py_GenericAliasType

Py_GetBuildInfo()

Py_GetCompiler()

Py_GetCopyright()

Py_GetExecPrefix()

Py_GetPath()

Py_GetPlatform()

Py_GetPrefix()

Py_GetProgramFullPath()

Py_GetProgramName()

Py_GetPythonHome()

Py_GetRecursionLimit()

Py_GetVersion()

Py_HasFileSystemDefaultEncoding

Py_IncRef()

Py_Initialize()

Py_InitializeEx()

Py_Is()

Py_IsFalse()

Py_IsInitialized()

Py_IsNone()

Py_IsTrue()

Py_LeaveRecursiveCall()

Py_Main()

Py_MakePendingCalls()

Py_NewInterpreter()

Py_NewRef()

Py_ReprEnter()

Py_ReprLeave()

Py_SetPath()

Py_SetProgramName()

Py_SetPythonHome()

Py_SetRecursionLimit()

Py_UCS4

Py_UNBLOCK_THREADS

Py_UTF8Mode

Py_VaBuildValue()

Py_Version

Py_XNewRef()

Py_buffer

Py_intptr_t

Py_ssize_t

Py_uintptr_t

allocfunc

binaryfunc

descrgetfunc

descrsetfunc

destructor

getattrfunc

getattrofunc

getbufferproc

getiterfunc

getter

hashfunc

initproc

inquiry

iternextfunc

lenfunc

newfunc

objobjargproc

objobjproc

releasebufferproc

reprfunc

richcmpfunc

setattrfunc

setattrofunc

setter

ssizeargfunc

ssizeobjargproc

ssizessizeargfunc

ssizessizeobjargproc

symtable

ternaryfunc

traverseproc

unaryfunc

vectorcallfunc

visitproc

超高水準レイヤ

この章の関数を使うとファイルまたはバッファにある Python ソースコードを実行できますが、より詳細なやり取りをインタプリタとすることはできないでしょう。

Several of these functions accept a start symbol from the grammar as a parameter. The available start symbols are Py_eval_input, Py_file_input, and 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 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.

int Py_Main(int argc, wchar_t **argv)

Part of the Stable ABI.

標準インタプリタのためのメインプログラム。Pythonを組み込むプログラムのためにこれを利用できるようにしています。 argc と argv 引数をCプログラムの main() 関数 (ユーザのロケールに従って wchar_t に変換されます) へ渡されるものとまったく同じに作成すべきです。引数リストが変更される可能性があるという点に注意することは重要です。 (しかし、引数リストが指している文字列の内容は変更されません)。戻り値はインタプリタが(例外などではなく)普通に終了した時は 0 に、例外で終了したときには 1 に、引数リストが正しい Python コマンドラインが渡されなかったときは 2 になります。

Note that if an otherwise unhandled SystemExit is raised, this function will not return 1, but exit the process, as long as PyConfig.inspect is zero.

int Py_BytesMain(int argc, char **argv)

Part of the Stable ABI since version 3.8.

Similar to Py_Main() but argv is an array of bytes strings.

Added in version 3.8.

int PyRun_AnyFile(FILE *fp, const char *filename)

下記の PyRun_AnyFileExFlags() の closeit を 0 に、 flags を NULL にして単純化したインターフェースです。

int PyRun_AnyFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)

下記の PyRun_AnyFileExFlags() の closeit を 0 にして単純化したインターフェースです。

int PyRun_AnyFileEx(FILE *fp, const char *filename, int closeit)

下記の PyRun_AnyFileExFlags() の flags を NULL にして単純化したインターフェースです。

int PyRun_AnyFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)

fp が対話的デバイス (コンソールや端末入力あるいは Unix 仮想端末) と関連づけられたファイルを参照している場合は、 PyRun_InteractiveLoop() の値を返します。それ以外の場合は、 PyRun_SimpleFile() の結果を返します。 filename はファイルシステムのエンコーディング (sys.getfilesystemencoding()) でデコードされます。 filename が NULL ならば、この関数はファイル名として "???" を使います。closeit が真なら、ファイルは PyRun_SimpleFileExFlags() が処理を戻す前に閉じられます。

int PyRun_SimpleString(const char *command)

下記の PyRun_SimpleStringFlags() の PyCompilerFlags* を NULL にして単純化したインタフェースです。

int PyRun_SimpleStringFlags(const char *command, PyCompilerFlags *flags)

__main__ モジュールの中で flags に従って command に含まれる Python ソースコードを実行します。 __main__ がまだ存在しない場合は作成されます。正常終了の場合は 0 を返し、また例外が発生した場合は -1 を返します。エラーがあっても、例外情報を得る方法はありません。 flags の意味については、後述します。

Note that if an otherwise unhandled SystemExit is raised, this function will not return -1, but exit the process, as long as PyConfig.inspect is zero.

int PyRun_SimpleFile(FILE *fp, const char *filename)

下記の PyRun_SimpleFileExFlags() の closeit を 0 に、 flags を NULL にして単純化したインターフェースです。

int PyRun_SimpleFileEx(FILE *fp, const char *filename, int closeit)

下記の PyRun_SimpleFileExFlags() の flags を NULL にして単純化したインターフェースです。

int PyRun_SimpleFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)

PyRun_SimpleStringFlags() と似ていますが、Pythonソースコードをメモリ内の文字列ではなく fp から読み込みます。 filename はそのファイルの名前でなければならず、 ファイルシステムのエンコーディングとエラーハンドラ でデコードされます。 closeit に真を指定した場合は、PyRun_SimpleFileExFlags() が処理を戻す前にファイルを閉じます。

注釈

Windowsでは、 fp はバイナリモードで開くべきです (例えば fopen(filename, "rb"))。そうしない場合は、 Python は行末が LF のスクリプトを正しく扱えないでしょう。

int PyRun_InteractiveOne(FILE *fp, const char *filename)

下記の PyRun_InteractiveOneFlags() の flags を NULL にして単純化したインターフェースです。

int PyRun_InteractiveOneFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)

対話的デバイスに関連付けられたファイルから文を一つ読み込み、 flags に従って実行します。 sys.ps1 と sys.ps2 を使って、ユーザにプロンプトを表示します。 filename は ファイルシステムのエンコーディングとエラーハンドラ でデコードされます。

入力が正常に実行されたときは 0 を返します。例外が発生した場合は -1 を返します。パースエラーの場合はPythonの一部として配布されている errcode.h インクルードファイルにあるエラーコードを返します。 (Python.h は errcode.h をインクルードしません。従って、 必要な場合はその都度インクルードしなければならないことに注意してください。)

int PyRun_InteractiveLoop(FILE *fp, const char *filename)

下記の PyRun_InteractiveLoopFlags() の flags を NULL にして単純化したインターフェースです。

int PyRun_InteractiveLoopFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)

対話的デバイスに関連付けられたファイルから EOF に達するまで文を読み込み実行します。 sys.ps1 と sys.ps2 を使って、ユーザにプロンプトを表示します。 filename は ファイルシステムのエンコーディングとエラーハンドラ でデコードされます。 EOFに達すると 0 を返すか、失敗したら負の数を返します。

int (*PyOS_InputHook)(void)

Part of the Stable ABI.

int func(void) というプロトタイプの関数へのポインタが設定できます。この関数は、 Python のインタプリタのプロンプトがアイドル状態になりターミナルからのユーザの入力を待つようになったときに呼び出されます。返り値は無視されます。このフックを上書きすることで、 Python のソースコードの中で Modules/_tkinter.c がやっているように、インタプリタのプロンプトと他のイベントループを統合できます。

バージョン 3.12 で変更: This function is only called from the main interpreter.

char *(*PyOS_ReadlineFunctionPointer)(FILE*, FILE*, const char*)

char *func(FILE *stdin, FILE *stdout, char *prompt) というプロトタイプの関数へのポインタが設定でき、デフォルトの関数を上書きすることでインタプリタのプロンプトへの入力を1行だけ読めます。この関数は、文字列 prompt が NULL でない場合は prompt を出力し、与えられた標準入力ファイルから入力を1行読み、結果の文字列を返すという動作が期待されています。例えば、 readline モジュールはこのフックを設定して、行編集機能やタブ補完機能を提供しています。

返り値は PyMem_RawMalloc() または PyMem_RawRealloc() でメモリ確保した文字列、あるいはエラーが起きた場合には NULL でなければなりません。

バージョン 3.4 で変更: 返り値は、 PyMem_Malloc() や PyMem_Realloc() ではなく、 PyMem_RawMalloc() または PyMem_RawRealloc() でメモリ確保したものでなければなりません。

バージョン 3.12 で変更: This function is only called from the main interpreter.

PyObject *PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals)

Return value: New reference.

下記の PyRun_StringFlags() の flags を NULL にして単純化したインターフェースです。

PyObject *PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)

Return value: New reference.

オブジェクトの globals と locals で指定されるコンテキストで、コンパイラフラグに flags を設定した状態で、 str にある Python ソースコードを実行します。 globals は辞書でなければなりません; locals はマッピングプロトコルを実装したオブジェクトなら何でも構いません。引数 start はソースコードをパースするために使われるべき開始トークンを指定します。

コードを実行した結果をPythonオブジェクトとして返します。または、例外が発生したならば NULL を返します。

PyObject *PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals)

Return value: New reference.

下記の PyRun_FileExFlags() の closeit を 0 にし、 flags を NULL にして単純化したインターフェースです。

PyObject *PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit)

Return value: New reference.

下記の PyRun_FileExFlags() の flags を NULL にして単純化したインターフェースです。

PyObject *PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)

Return value: New reference.

下記の PyRun_FileExFlags() の closeit を 0 にして単純化したインターフェースです。

PyObject *PyRun_FileExFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags)

Return value: New reference.

PyRun_StringFlags() と似ていますが、Pythonソースコードをメモリ内の文字列ではなく fp から読み込みます。 filename はそのファイルの名前でなければならず、 ファイルシステムのエンコーディングとエラーハンドラ でデコードされます。 closeit に真を指定した場合は、PyRun_FileExFlags() が処理を戻す前にファイルを閉じます。

PyObject *Py_CompileString(const char *str, const char *filename, int start)

Return value: New reference. Part of the Stable ABI.

下記の Py_CompileStringFlags() の flags を NULL にして単純化したインターフェースです。

PyObject *Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags)

Return value: New reference.

下記の Py_CompileStringExFlags() の optimize を -1 にして単純化したインターフェースです。

PyObject *Py_CompileStringObject(const char *str, PyObject *filename, int start, PyCompilerFlags *flags, int optimize)

Return value: New reference.

Parse and compile the Python source code in str, returning the resulting code object. The start token is given by start; this can be used to constrain the code which can be compiled and should be Py_eval_input, Py_file_input, or Py_single_input. The filename specified by filename is used to construct the code object and may appear in tracebacks or SyntaxError exception messages. This returns NULL if the code cannot be parsed or compiled.

整数 optimize は、コンパイラの最適化レベルを指定します; -1 は、インタプリタの -O オプションで与えられるのと同じ最適化レベルを選びます。明示的なレベルは、 0 (最適化なし、 __debug__ は真)、 1 (assert は取り除かれ、 __debug__ は偽)、 2 (docstring も取り除かれる) です。

Added in version 3.4.

PyObject *Py_CompileStringExFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize)

Return value: New reference.

Py_CompileStringObject() と似ていますが、 filename は ファイルシステムのエンコーディングとエラーハンドラ でデコードされたバイト文字列です。

Added in version 3.2.

PyObject *PyEval_EvalCode(PyObject *co, PyObject *globals, PyObject *locals)

Return value: New reference. Part of the Stable ABI.

PyEval_EvalCodeEx() のシンプルなインターフェースで、コードオブジェクトと、グローバル変数とローカル変数だけを受け取ります。他の引数には NULL が渡されます。

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)

Return value: New reference. Part of the Stable ABI.

与えられた特定の環境で、コンパイル済みのコードオブジェクトを評価します。この環境はグローバル変数の辞書と、ローカル変数のマッピングオブジェクト、引数の配列、キーワードとデフォルト値、キーワード専用 引数のデフォルト値の辞書と、セルのクロージャタプルで構成されます。

PyObject *PyEval_EvalFrame(PyFrameObject *f)

Return value: New reference. Part of the Stable ABI.

実行フレームを評価します。これは PyEval_EvalFrameEx() に対するシンプルなインターフェースで、後方互換性のためのものです。

PyObject *PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)

Return value: New reference. Part of the Stable ABI.

Python のインタープリタの主要な、直接的な関数です。実行フレーム f に関連付けられたコードオブジェクトを実行します。 バイトコードを解釈して、必要に応じて呼び出しを実行します。 追加の throwflag 引数はほとんど無視できます。 - もし true なら、 すぐに例外を発生させます。これはジェネレータオブジェクトの throw() メソッドで利用されます。

バージョン 3.4 で変更: アクティブな例外を黙って捨てないことを保証するのに便利なように、この関数はデバッグアサーションを含むようになりました。

int PyEval_MergeCompilerFlags(PyCompilerFlags *cf)

現在の評価フレームのフラグを変更します。成功したら true を、失敗したら false を返します。

int Py_eval_input

単独の式に対するPython文法の開始記号で、 Py_CompileString() と一緒に使います。

int Py_file_input

ファイルあるいは他のソースから読み込まれた文の並びに対するPython文法の開始記号で、 Py_CompileString() と一緒に使います。これは任意の長さのPythonソースコードをコンパイルするときに使う記号です。

int Py_single_input

単一の文に対するPython文法の開始記号で、 Py_CompileString() と一緒に使います。これは対話式のインタプリタループのための記号です。

struct PyCompilerFlags

コンパイラフラグを収めておくための構造体です。コードをコンパイルするだけの場合、この構造体が int flags として渡されます。コードを実行する場合には PyCompilerFlags *flags として渡されます。この場合、from __future__ import は flags の内容を変更できます。

Whenever PyCompilerFlags *flags is NULL, cf_flags is treated as equal to 0, and any modification due to from __future__ import is discarded.

int cf_flags

コンパイラフラグ。

int cf_feature_version

cf_feature_version is the minor Python version. It should be initialized to PY_MINOR_VERSION.

The field is ignored by default, it is used if and only if PyCF_ONLY_AST flag is set in cf_flags.

バージョン 3.8 で変更: Added cf_feature_version field.

int CO_FUTURE_DIVISION

このビットを flags にセットすると、除算演算子 / は PEP 238 [https://peps.python.org/pep-0238/] による「真の除算 (true division)」として扱われます。

参照カウント

The functions and macros in this section are used for managing reference counts of Python objects.

Py_ssize_t Py_REFCNT(PyObject *o)

Get the reference count of the Python object o.

Note that the returned value may not actually reflect how many references to the object are actually held. For example, some objects are "immortal" and have a very high refcount that does not reflect the actual number of references. Consequently, do not rely on the returned value to be accurate, other than a value of 0 or 1.

Use the Py_SET_REFCNT() function to set an object reference count.

バージョン 3.10 で変更: Py_REFCNT() is changed to the inline static function.

バージョン 3.11 で変更: The parameter type is no longer const PyObject*.

void Py_SET_REFCNT(PyObject *o, Py_ssize_t refcnt)

Set the object o reference counter to refcnt.

Note that this function has no effect on immortal [https://peps.python.org/pep-0683/] objects.

Added in version 3.9.

バージョン 3.12 で変更: Immortal objects are not modified.

void Py_INCREF(PyObject *o)

Indicate taking a new strong reference to object o, indicating it is in use and should not be destroyed.

This function is usually used to convert a borrowed reference to a strong reference in-place. The Py_NewRef() function can be used to create a new strong reference.

When done using the object, release it by calling Py_DECREF().

オブジェクトが NULL であってはいけません。それが NULL ではないと確信が持てないならば、 Py_XINCREF() を使ってください。

Do not expect this function to actually modify o in any way. For at least some objects [https://peps.python.org/pep-0683/], this function has no effect.

バージョン 3.12 で変更: Immortal objects are not modified.

void Py_XINCREF(PyObject *o)

Similar to Py_INCREF(), but the object o can be NULL, in which case this has no effect.

See also Py_XNewRef().

PyObject *Py_NewRef(PyObject *o)

Part of the Stable ABI since version 3.10.

Create a new strong reference to an object: call Py_INCREF() on o and return the object o.

When the strong reference is no longer needed, Py_DECREF() should be called on it to release the reference.

The object o must not be NULL; use Py_XNewRef() if o can be NULL.

例えば:

Py_INCREF(obj);
self->attr = obj;

can be written as:

self->attr = Py_NewRef(obj);

See also Py_INCREF().

Added in version 3.10.

PyObject *Py_XNewRef(PyObject *o)

Part of the Stable ABI since version 3.10.

Similar to Py_NewRef(), but the object o can be NULL.

If the object o is NULL, the function just returns NULL.

Added in version 3.10.

void Py_DECREF(PyObject *o)

Release a strong reference to object o, indicating the reference is no longer used.

Once the last strong reference is released (i.e. the object's reference count reaches 0), the object's type's deallocation function (which must not be NULL) is invoked.

This function is usually used to delete a strong reference before exiting its scope.

オブジェクトが NULL であってはいけません。それが NULL ではないと確信が持てないならば、 Py_XDECREF() を使ってください。

Do not expect this function to actually modify o in any way. For at least some objects [https://peps.python.org/pep-0683/], this function has no effect.

警告

The deallocation function can cause arbitrary Python code to be invoked (e.g. when a class instance with a __del__() method is deallocated). While exceptions in such code are not propagated, the executed code has free access to all Python global variables. This means that any object that is reachable from a global variable should be in a consistent state before Py_DECREF() is invoked. For example, code to delete an object from a list should copy a reference to the deleted object in a temporary variable, update the list data structure, and then call Py_DECREF() for the temporary variable.

バージョン 3.12 で変更: Immortal objects are not modified.

void Py_XDECREF(PyObject *o)

Similar to Py_DECREF(), but the object o can be NULL, in which case this has no effect. The same warning from Py_DECREF() applies here as well.

void Py_CLEAR(PyObject *o)

Release a strong reference for object o. The object may be NULL, in which case the macro has no effect; otherwise the effect is the same as for Py_DECREF(), except that the argument is also set to NULL. The warning for Py_DECREF() does not apply with respect to the object passed because the macro carefully uses a temporary variable and sets the argument to NULL before releasing the reference.

It is a good idea to use this macro whenever releasing a reference to an object that might be traversed during garbage collection.

バージョン 3.12 で変更: The macro argument is now only evaluated once. If the argument has side effects, these are no longer duplicated.

void Py_IncRef(PyObject *o)

Part of the Stable ABI.

Indicate taking a new strong reference to object o. A function version of Py_XINCREF(). It can be used for runtime dynamic embedding of Python.

void Py_DecRef(PyObject *o)

Part of the Stable ABI.

Release a strong reference to object o. A function version of Py_XDECREF(). It can be used for runtime dynamic embedding of Python.

Py_SETREF(dst, src)

Macro safely releasing a strong reference to object dst and setting dst to src.

As in case of Py_CLEAR(), "the obvious" code can be deadly:

Py_DECREF(dst);
dst = src;

The safe way is:

Py_SETREF(dst, src);

That arranges to set dst to src _before_ releasing the reference to the old value of dst, so that any code triggered as a side-effect of dst getting torn down no longer believes dst points to a valid object.

Added in version 3.6.

バージョン 3.12 で変更: The macro arguments are now only evaluated once. If an argument has side effects, these are no longer duplicated.

Py_XSETREF(dst, src)

Variant of Py_SETREF macro that uses Py_XDECREF() instead of Py_DECREF().

Added in version 3.6.

バージョン 3.12 で変更: The macro arguments are now only evaluated once. If an argument has side effects, these are no longer duplicated.

例外処理

この章で説明する関数を使うと、 Python の例外の処理や例外の送出ができるようになります。 Python の例外処理の基本をいくらか理解することが大切です。例外は POSIX errno 変数にやや似た機能を果たします: 発生した中で最も新しいエラーの (スレッド毎の) グローバルなインジケータがあります。実行に成功した場合にはほとんどの C API 関数がこれをクリアしませんが、失敗したときにはエラーの原因を示すために設定します。ほとんどの C API 関数はエラーインジケータも返し、通常は関数がポインタを返すことになっている場合は NULL であり、関数が整数を返す場合は -1 です。(例外: PyArg_* 関数は実行に成功したときに 1 を返し、失敗したときに 0 を返します).

具体的には、エラーインジケータは、例外の型、例外の値、トレースバックオブジェクトの３つのオブジェクトポインタで構成されます。これらのポインタはどれでも、設定されない場合は NULL になりえます（ただし、いくつかの組み合わせは禁止されており、例えば、例外の型が NULL の場合は、トレースバックは非 NULL の値になりません）

ある関数が呼び出した関数がいくつか失敗したために、その関数が失敗しなければならないとき、一般的にエラーインジケータを設定しません。呼び出した関数がすでに設定しています。エラーを処理して例外をクリアするか、あるいは (オブジェクト参照またはメモリ割り当てのような)それが持つどんなリソースも取り除いた後に戻るかのどちらか一方を行う責任があります。エラーを処理する準備をしていなければ、普通に続けるべきでは ありません。エラーのために戻る場合は、エラーが設定されていると呼び出し元に知らせることが大切です。エラーが処理されていない場合または丁寧に伝えられている場合には、Python/C APIのさらなる呼び出しは意図した通りには動かない可能性があり、不可解な形で失敗するかもしれません。

注釈

エラー識別子は sys.exc_info() の結果 ではありません。エラー識別子はまだ捕捉されていない例外 (したがってまだ伝播します) に対応しているのに対し、 sys.exc_info() の結果は捕捉された後の例外を返します (したがってもう伝播しません)。

出力とクリア

void PyErr_Clear()

Part of the Stable ABI.

エラーインジケータをクリアします。エラーインジケータが設定されていないならば、効果はありません。

void PyErr_PrintEx(int set_sys_last_vars)

Part of the Stable ABI.

標準のトレースバックを sys.stderr に出力し、エラーインジケータをクリアします。ただし、エラーが SystemExit である場合を除いて です。その場合、トレースバックは出力されず、 Python プロセスは SystemExit インスタンスで指定されたエラーコードで終了します。

エラーインジケータが設定されているときに だけ、この関数を呼び出してください。それ以外の場合、致命的なエラーを引き起こすでしょう!

If set_sys_last_vars is nonzero, the variable sys.last_exc is set to the printed exception. For backwards compatibility, the deprecated variables sys.last_type, sys.last_value and sys.last_traceback are also set to the type, value and traceback of this exception, respectively.

バージョン 3.12 で変更: The setting of sys.last_exc was added.

void PyErr_Print()

Part of the Stable ABI.

PyErr_PrintEx(1) のエイリアスです。

void PyErr_WriteUnraisable(PyObject *obj)

Part of the Stable ABI.

現在の例外と obj 引数で sys.unraisablehook() を呼び出します。

This utility function prints a warning message to 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 __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 NULL, only the traceback is printed.

この関数を呼び出すときには、例外がセットされていなければなりません。

バージョン 3.4 で変更: Print a traceback. Print only traceback if obj is NULL.

バージョン 3.8 で変更: Use sys.unraisablehook().

void PyErr_DisplayException(PyObject *exc)

Part of the Stable ABI since version 3.12.

Print the standard traceback display of exc to sys.stderr, including chained exceptions and notes.

Added in version 3.12.

例外の送出

以下の関数は、現在のスレッドのエラーインジケータの設定を補助します。利便性のため、これらの関数のいくつかは、 return 文で利用できるように常に NULL ポインタを返します。

void PyErr_SetString(PyObject *type, const char *message)

Part of the Stable ABI.

This is the most common way to set the error indicator. The first argument specifies the exception type; it is normally one of the standard exceptions, e.g. PyExc_RuntimeError. You need not create a new strong reference to it (e.g. with Py_INCREF()). The second argument is an error message; it is decoded from 'utf-8'.

void PyErr_SetObject(PyObject *type, PyObject *value)

Part of the Stable ABI.

この関数は PyErr_SetString() に似ていますが、例外の "値(value)" として任意のPythonオブジェクトを指定することができます。

PyObject *PyErr_Format(PyObject *exception, const char *format, ...)

Return value: Always NULL. Part of the Stable ABI.

この関数はエラーインジケータを設定し NULL を返します。 exception はPython例外クラスであるべきです。 format と以降の引数はエラーメッセージを作るためのもので, PyUnicode_FromFormat() の引数と同じ意味を持っています。 format は ASCII エンコードされた文字列です。

PyObject *PyErr_FormatV(PyObject *exception, const char *format, va_list vargs)

Return value: Always NULL. Part of the Stable ABI since version 3.5.

PyErr_Format() と同じですが、可変長引数の代わりに va_list 引数を受け取ります。

Added in version 3.5.

void PyErr_SetNone(PyObject *type)

Part of the Stable ABI.

これは PyErr_SetObject(type, Py_None) を省略したものです。

int PyErr_BadArgument()

Part of the Stable ABI.

これは PyErr_SetString(PyExc_TypeError, message) を省略したもので、ここで message は組み込み操作が不正な引数で呼び出されたということを表しています。主に内部で使用するためのものです。

PyObject *PyErr_NoMemory()

Return value: Always NULL. Part of the Stable ABI.

これは PyErr_SetNone(PyExc_MemoryError) を省略したもので、NULL を返します。したがって、メモリ不足になったとき、オブジェクト割り当て関数は return PyErr_NoMemory(); と書くことができます。

PyObject *PyErr_SetFromErrno(PyObject *type)

Return value: Always NULL. Part of the Stable ABI.

This is a convenience function to raise an exception when a C library function has returned an error and set the C variable errno. It constructs a tuple object whose first item is the integer errno value and whose second item is the corresponding error message (gotten from strerror()), and then calls PyErr_SetObject(type, object). On Unix, when the errno value is EINTR, indicating an interrupted system call, this calls PyErr_CheckSignals(), and if that set the error indicator, leaves it set to that. The function always returns NULL, so a wrapper function around a system call can write return PyErr_SetFromErrno(type); when the system call returns an error.

PyObject *PyErr_SetFromErrnoWithFilenameObject(PyObject *type, PyObject *filenameObject)

Return value: Always NULL. Part of the Stable ABI.

Similar to PyErr_SetFromErrno(), with the additional behavior that if filenameObject is not NULL, it is passed to the constructor of type as a third parameter. In the case of OSError exception, this is used to define the filename attribute of the exception instance.

PyObject *PyErr_SetFromErrnoWithFilenameObjects(PyObject *type, PyObject *filenameObject, PyObject *filenameObject2)

Return value: Always NULL. Part of the Stable ABI since version 3.7.

PyErr_SetFromErrnoWithFilenameObject() に似てますが、ファイル名を2つ取る関数が失敗したときに例外を送出するために、2つ目のファイル名オブジェクトを受け取ります。

Added in version 3.4.

PyObject *PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)

Return value: Always NULL. Part of the Stable ABI.

PyErr_SetFromErrnoWithFilenameObject() に似ていますが、ファイル名は C 文字列として与えられます。 filename は ファイルシステムのエンコーディングとエラーハンドラ でデコードされます。

PyObject *PyErr_SetFromWindowsErr(int ierr)

Return value: Always NULL. Part of the Stable ABI on Windows since version 3.7.

This is a convenience function to raise OSError. If called with ierr of 0, the error code returned by a call to GetLastError() is used instead. It calls the Win32 function FormatMessage() to retrieve the Windows description of error code given by ierr or GetLastError(), then it constructs a OSError object with the winerror attribute set to the error code, the strerror attribute set to the corresponding error message (gotten from FormatMessage()), and then calls PyErr_SetObject(PyExc_OSError, object). This function always returns NULL.

利用可能な環境: Windows 。

PyObject *PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)

Return value: Always NULL. Part of the Stable ABI on Windows since version 3.7.

PyErr_SetFromWindowsErr() に似ていますが、送出する例外の型を指定する引数が追加されています。

利用可能な環境: Windows 。

PyObject *PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)

Return value: Always NULL. Part of the Stable ABI on Windows since version 3.7.

Similar to PyErr_SetFromWindowsErr(), with the additional behavior that if filename is not NULL, it is decoded from the filesystem encoding (os.fsdecode()) and passed to the constructor of OSError as a third parameter to be used to define the filename attribute of the exception instance.

利用可能な環境: Windows 。

PyObject *PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename)

Return value: Always NULL. Part of the Stable ABI on Windows since version 3.7.

Similar to PyErr_SetExcFromWindowsErr(), with the additional behavior that if filename is not NULL, it is passed to the constructor of OSError as a third parameter to be used to define the filename attribute of the exception instance.

利用可能な環境: Windows 。

PyObject *PyErr_SetExcFromWindowsErrWithFilenameObjects(PyObject *type, int ierr, PyObject *filename, PyObject *filename2)

Return value: Always NULL. Part of the Stable ABI on Windows since version 3.7.

PyErr_SetExcFromWindowsErrWithFilenameObject() に似てますが、2つ目のファイル名オブジェクトを受け取ります。

利用可能な環境: Windows 。

Added in version 3.4.

PyObject *PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, const char *filename)

Return value: Always NULL. Part of the Stable ABI on Windows since version 3.7.

PyErr_SetFromWindowsErrWithFilename() に似ていますが、送出する例外の型を指定する引数が追加されています。

利用可能な環境: Windows 。

PyObject *PyErr_SetImportError(PyObject *msg, PyObject *name, PyObject *path)

Return value: Always NULL. Part of the Stable ABI since version 3.7.

ImportError を簡単に送出するための関数です。 msg は例外のメッセージ文字列としてセットされます。 name と path はどちらも NULL にしてよく、それぞれ ImportError の name 属性と path 属性としてセットされます。

Added in version 3.3.

PyObject *PyErr_SetImportErrorSubclass(PyObject *exception, PyObject *msg, PyObject *name, PyObject *path)

Return value: Always NULL. Part of the Stable ABI since version 3.6.

PyErr_SetImportError() とよく似ていますが、この関数は送出する例外として、 ImportError のサブクラスを指定できます。

Added in version 3.6.

void PyErr_SyntaxLocationObject(PyObject *filename, int lineno, int col_offset)

現在の例外のファイル、行、オフセットの情報をセットします。現在の例外が SyntaxError でない場合は、例外を表示するサブシステムが、例外が SyntaxError であると思えるように属性を追加します。

Added in version 3.4.

void PyErr_SyntaxLocationEx(const char *filename, int lineno, int col_offset)

Part of the Stable ABI since version 3.7.

PyErr_SyntaxLocationObject() と似ていますが、 filename は ファイルシステムのエンコーディングとエラーハンドラ でデコードされたバイト文字列です。

Added in version 3.2.

void PyErr_SyntaxLocation(const char *filename, int lineno)

Part of the Stable ABI.

PyErr_SyntaxLocationEx() と似ていますが、 col_offset 引数が除去されています。

void PyErr_BadInternalCall()

Part of the Stable ABI.

PyErr_SetString(PyExc_SystemError, message) を省略したものです。ここで message は内部操作(例えば、Python/C API関数)が不正な引数とともに呼び出されたということを示しています。主に内部で使用するためのものです。

警告

以下の関数を使い、 C コードで起きた警告を報告します。 Python の warnings モジュールで公開されている同様の関数とよく似てます。これらの関数は通常警告メッセージを sys.stderr へ出力しますが、ユーザが警告をエラーへ変更するように指定することもでき、その場合は、関数は例外を送出します。警告機構がもつ問題のためにその関数が例外を送出するということも有り得ます。例外が送出されない場合は戻り値は 0 で、例外が送出された場合は -1 です。 (警告メッセージが実際に出力されるか、およびその例外の原因が何かについては判断できません; これは意図的なものです。) 例外が送出された場合、呼び出し元は通常の例外処理を行います (例えば、保持していた参照に対し Py_DECREF() を行い、エラー値を返します)。

int PyErr_WarnEx(PyObject *category, const char *message, Py_ssize_t stack_level)

Part of the Stable ABI.

警告メッセージを発行します。 category 引数は警告カテゴリ(以下を参照) かまたは NULL で、 message 引数は UTF-8 エンコードされた文字列です。 stacklevel はスタックフレームの数を示す正の整数です; 警告はそのスタックフレームの中の実行している行から発行されます。 stacklevel が 1 だと PyErr_WarnEx() を呼び出している関数が、2 だとその上の関数が Warning の発行元になります。

警告カテゴリは PyExc_Warning のサブクラスでなければなりません。 PyExc_Warning は PyExc_Exception のサブクラスです。デフォルトの警告カテゴリは PyExc_RuntimeWarning です。標準の Python 警告カテゴリは、 標準警告カテゴリ で名前が列挙されているグローバル変数として利用可能です。

警告をコントロールするための情報については、 warnings モジュールのドキュメンテーションとコマンドライン・ドキュメンテーションの -W オプションを参照してください。警告コントロールのためのC APIはありません。

int PyErr_WarnExplicitObject(PyObject *category, PyObject *message, PyObject *filename, int lineno, PyObject *module, PyObject *registry)

すべての警告の属性を明示的に制御した警告メッセージを出します。これは Python 関数 warnings.warn_explicit() の直接的なラッパーで、さらに情報を得るにはそちらを参照してください。そこに説明されているデフォルトの効果を得るために、 module と registry 引数は NULL に設定することができます。

Added in version 3.4.

int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry)

Part of the Stable ABI.

PyErr_WarnExplicitObject() に似ていますが、 message と module が UTF-8 エンコードされた文字列であるところが異なり、 filename は ファイルシステムのエンコーディングとエラーハンドラ でデコードされます。

int PyErr_WarnFormat(PyObject *category, Py_ssize_t stack_level, const char *format, ...)

Part of the Stable ABI.

PyErr_WarnEx() に似たような関数ですが、警告メッセージをフォーマットするのに PyUnicode_FromFormat() を使用します。 format は ASCII にエンコードされた文字列です。

Added in version 3.2.

int PyErr_ResourceWarning(PyObject *source, Py_ssize_t stack_level, const char *format, ...)

Part of the Stable ABI since version 3.6.

Function similar to PyErr_WarnFormat(), but category is ResourceWarning and it passes source to warnings.WarningMessage.

Added in version 3.6.

エラーインジケータの問い合わせ

PyObject *PyErr_Occurred()

Return value: Borrowed reference. Part of the Stable ABI.

エラーインジケータが設定されているかテストします。設定されている場合は、例外の 型 (PyErr_Set* 関数の一つあるいは PyErr_Restore() への最も新しい呼び出しに対する第一引数)を返します。設定されていない場合は NULL を返します。あなたは戻り値への参照を持っていませんので、それに Py_DECREF() する必要はありません。

呼び出し側はGILを獲得する必要があります

注釈

戻り値を特定の例外と比較しないでください。その代わりに、下に示す PyErr_ExceptionMatches() を使ってください。(比較は簡単に失敗するでしょう。なぜなら、例外はクラスではなくインスタンスかもしれないし、あるいは、クラス例外の場合は期待される例外のサブクラスかもしれないからです。)

int PyErr_ExceptionMatches(PyObject *exc)

Part of the Stable ABI.

PyErr_GivenExceptionMatches(PyErr_Occurred(), exc) と同じ。例外が実際に設定されたときにだけ、これを呼び出だすべきです。例外が発生していないならば、メモリアクセス違反が起きるでしょう。

int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)

Part of the Stable ABI.

例外 given が exc の例外型と適合する場合に真を返します。 exc がクラスオブジェクトである場合も、 given がサブクラスのインスタンスであるときに真を返します。 exc がタプルの場合は、タプルにある (およびそのサブタプルに再帰的にある) すべての例外型が適合するか調べられます。

PyObject *PyErr_GetRaisedException(void)

Return value: New reference. Part of the Stable ABI since version 3.12.

Return the exception currently being raised, clearing the error indicator at the same time. Return 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.

例えば:

{
   PyObject *exc = PyErr_GetRaisedException();

   /* ... code that might produce other errors ... */

   PyErr_SetRaisedException(exc);
}

参考

PyErr_GetHandledException(), to save the exception currently being handled.

Added in version 3.12.

void PyErr_SetRaisedException(PyObject *exc)

Part of the Stable ABI since version 3.12.

Set exc as the exception currently being raised, clearing the existing exception if one is set.

警告

This call steals a reference to exc, which must be a valid exception.

Added in version 3.12.

void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)

Part of the Stable ABI.

バージョン 3.12 で非推奨: Use PyErr_GetRaisedException() instead.

エラーインジケータをアドレスを渡す三つの変数の中へ取り出します。エラーインジケータが設定されていない場合は、三つすべての変数を NULL に設定します。エラーインジケータが設定されている場合はクリアされ、あなたは取り出されたそれぞれのオブジェクトへの参照を持つことになります。型オブジェクトが NULL でないときでさえ、その値とトレースバックオブジェクトは NULL かもしれません。

注釈

This function is normally only used by legacy code that needs to catch exceptions or save and restore the error indicator temporarily.

例えば:

{
   PyObject *type, *value, *traceback;
   PyErr_Fetch(&type, &value, &traceback);

   /* ... code that might produce other errors ... */

   PyErr_Restore(type, value, traceback);
}

void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback)

Part of the Stable ABI.

バージョン 3.12 で非推奨: Use PyErr_SetRaisedException() instead.

Set the error indicator from the three objects, type, value, and traceback, clearing the existing exception if one is set. If the objects are NULL, the error indicator is cleared. Do not pass a NULL type and non-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.)

注釈

This function is normally only used by legacy code that needs to save and restore the error indicator temporarily. Use PyErr_Fetch() to save the current error indicator.

void PyErr_NormalizeException(PyObject **exc, PyObject **val, PyObject **tb)

Part of the Stable ABI.

バージョン 3.12 で非推奨: Use PyErr_GetRaisedException() instead, to avoid any possible de-normalization.

ある状況では、以下の PyErr_Fetch() が返す値は "正規化されていない" 可能性があります。つまり、 *exc はクラスオブジェクトだが *val は同じクラスのインスタンスではないという意味です。この関数はそのような場合にそのクラスをインスタンス化するために使われます。その値がすでに正規化されている場合は何も起きません。遅延正規化はパフォーマンスを改善するために実装されています。

注釈

This function does not implicitly set the __traceback__ attribute on the exception value. If setting the traceback appropriately is desired, the following additional snippet is needed:

if (tb != NULL) {
  PyException_SetTraceback(val, tb);
}

PyObject *PyErr_GetHandledException(void)

Part of the Stable ABI since version 3.11.

Retrieve the active exception instance, as would be returned by 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 NULL. Does not modify the interpreter's exception state.

注釈

この関数は、通常は例外を扱うコードでは使用されません。正確に言うと、これは例外の状態を一時的に保存し、元に戻す必要があるコードで使用することができます。例外の状態を元に戻す、もしくはクリアするには PyErr_SetHandledException() を使ってください。

Added in version 3.11.

void PyErr_SetHandledException(PyObject *exc)

Part of the Stable ABI since version 3.11.

Set the active exception, as known from 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 NULL.

注釈

この関数は、通常は例外を扱うコードでは使用されません。正確に言うと、これは例外の状態を一時的に保存し、元に戻す必要があるコードで使用することができます。例外の状態を取得するには PyErr_GetHandledException() を使ってください。

Added in version 3.11.

void PyErr_GetExcInfo(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)

Part of the Stable ABI since version 3.7.

Retrieve the old-style representation of the exception info, as known from 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 NULL. Does not modify the exception info state. This function is kept for backwards compatibility. Prefer using PyErr_GetHandledException().

注釈

この関数は、通常は例外を扱うコードでは使用されません。正確に言うと、これは例外の状態を一時的に保存し、元に戻す必要があるコードで使用することができます。例外の状態を元に戻す、もしくはクリアするには PyErr_SetExcInfo() を使ってください。

Added in version 3.3.

void PyErr_SetExcInfo(PyObject *type, PyObject *value, PyObject *traceback)

Part of the Stable ABI since version 3.7.

Set the exception info, as known from 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 NULL for all three arguments. This function is kept for backwards compatibility. Prefer using PyErr_SetHandledException().

注釈

この関数は、通常は例外を扱うコードでは使用されません。正確に言うと、これは例外の状態を一時的に保存し、元に戻す必要があるコードで使用することができます。例外の状態を取得するには PyErr_GetExcInfo() を使ってください。

Added in version 3.3.

バージョン 3.11 で変更: The type and traceback arguments are no longer used and can be NULL. The interpreter now derives them from the exception instance (the value argument). The function still steals references of all three arguments.

シグナルハンドリング

int PyErr_CheckSignals()

Part of the Stable ABI.

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 signal module is supported, this can invoke a signal handler written in Python.

The function attempts to handle all pending signals, and then returns 0. However, if a Python signal handler raises an exception, the error indicator is set and the function returns -1 immediately (such that other pending signals may not have been handled yet: they will be on the next 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 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).

注釈

The default Python signal handler for SIGINT raises the KeyboardInterrupt exception.

void PyErr_SetInterrupt()

Part of the Stable ABI.

Simulate the effect of a SIGINT signal arriving. This is equivalent to PyErr_SetInterruptEx(SIGINT).

注釈

This function is async-signal-safe. It can be called without the GIL and from a C signal handler.

int PyErr_SetInterruptEx(int signum)

Part of the Stable ABI since version 3.10.

シグナルが到達した効果をシミュレートします。次に PyErr_CheckSignals() が呼ばれたとき、与えられたシグナル番号用の Python のシグナルハンドラが呼び出されます。

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 signal.SIG_DFL or signal.SIG_IGN), it will be ignored.

If signum is outside of the allowed range of signal numbers, -1 is returned. Otherwise, 0 is returned. The error indicator is never changed by this function.

注釈

This function is async-signal-safe. It can be called without the GIL and from a C signal handler.

Added in version 3.10.

int PySignal_SetWakeupFd(int fd)

このユーティリティ関数は、シグナルを受け取ったときにシグナル番号をバイトとして書き込むファイル記述子を指定します。 fd はノンブロッキングでなければなりません。この関数は、1つ前のファイル記述子を返します。

値 -1 を渡すと、この機能を無効にします; これが初期状態です。この関数は Python の signal.set_wakeup_fd() と同等ですが、どんなエラーチェックも行いません。 fd は有効なファイル記述子であるべきです。この関数はメインスレッドからのみ呼び出されるべきです。

バージョン 3.5 で変更: Windowsで、この関数はソケットハンドルをサポートするようになりました。

例外クラス

PyObject *PyErr_NewException(const char *name, PyObject *base, PyObject *dict)

Return value: New reference. Part of the Stable ABI.

このユーティリティ関数は新しい例外クラスを作成して返します。 name 引数は新しい例外の名前、 module.classname 形式の C文字列でなければならない。 base と dict 引数は通常 NULL です。これはすべての例外のためのルート、組み込み名 Exception (Cでは PyExc_Exception としてアクセス可能)をルートとして派生したクラスオブジェクトを作成します。

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

PyObject *PyErr_NewExceptionWithDoc(const char *name, const char *doc, PyObject *base, PyObject *dict)

Return value: New reference. Part of the Stable ABI.

PyErr_NewException() とほぼ同じですが、新しい例外クラスに簡単に docstring を設定できます。 doc が NULL で無い場合、それが例外クラスの docstring になります。

Added in version 3.2.

例外オブジェクト

PyObject *PyException_GetTraceback(PyObject *ex)

Return value: New reference. Part of the Stable ABI.

Python で __traceback__ 属性からアクセスできるものと同じ、例外に関する traceback の新しい参照を返します。関係する traceback が無い場合は、 NULL を返します。

int PyException_SetTraceback(PyObject *ex, PyObject *tb)

Part of the Stable ABI.

その例外に関する traceback に tb をセットします。クリアするには Py_None を使用してください。

PyObject *PyException_GetContext(PyObject *ex)

Return value: New reference. Part of the Stable ABI.

Return the context (another exception instance during whose handling ex was raised) associated with the exception as a new reference, as accessible from Python through the __context__ attribute. If there is no context associated, this returns NULL.

void PyException_SetContext(PyObject *ex, PyObject *ctx)

Part of the Stable ABI.

例外に関するコンテキストに ctx をセットします。クリアするには NULL を使用してください。ctx が例外インスタンスかどうかを確かめる型チェックは行われません。これは ctx への参照を盗みます。

PyObject *PyException_GetCause(PyObject *ex)

Return value: New reference. Part of the Stable ABI.

Return the cause (either an exception instance, or None, set by raise ... from ...) associated with the exception as a new reference, as accessible from Python through the __cause__ attribute.

void PyException_SetCause(PyObject *ex, PyObject *cause)

Part of the Stable ABI.

Set the cause associated with the exception to cause. Use NULL to clear it. There is no type check to make sure that cause is either an exception instance or None. This steals a reference to cause.

The __suppress_context__ attribute is implicitly set to True by this function.

PyObject *PyException_GetArgs(PyObject *ex)

Return value: New reference. Part of the Stable ABI since version 3.12.

Return args of exception ex.

void PyException_SetArgs(PyObject *ex, PyObject *args)

Part of the Stable ABI since version 3.12.

Set args of exception ex to args.

PyObject *PyUnstable_Exc_PrepReraiseStar(PyObject *orig, PyObject *excs)

これは Unstable API. It may change without warning in minor releases.

Implement part of the interpreter's implementation of 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 except* clauses (so they have a different traceback from orig) and those that were reraised (and have the same traceback as orig). Return the ExceptionGroup that needs to be reraised in the end, or None if there is nothing to reraise.

Added in version 3.12.

Unicode 例外オブジェクト

以下の関数は C言語から Unicode 例外を作ったり修正したりするために利用します。

PyObject *PyUnicodeDecodeError_Create(const char *encoding, const char *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)

Return value: New reference. Part of the Stable ABI.

encoding, object, length, start, end, reason 属性をもった UnicodeDecodeError オブジェクトを作成します。 encoding および reason は UTF-8 エンコードされた文字列です。

PyObject *PyUnicodeDecodeError_GetEncoding(PyObject *exc)

PyObject *PyUnicodeEncodeError_GetEncoding(PyObject *exc)

Return value: New reference. Part of the Stable ABI.

与えられた例外オブジェクトの encoding 属性を返します。

PyObject *PyUnicodeDecodeError_GetObject(PyObject *exc)

PyObject *PyUnicodeEncodeError_GetObject(PyObject *exc)

PyObject *PyUnicodeTranslateError_GetObject(PyObject *exc)

Return value: New reference. Part of the Stable ABI.

与えられた例外オブジェクトの object 属性を返します。

int PyUnicodeDecodeError_GetStart(PyObject *exc, Py_ssize_t *start)

int PyUnicodeEncodeError_GetStart(PyObject *exc, Py_ssize_t *start)

int PyUnicodeTranslateError_GetStart(PyObject *exc, Py_ssize_t *start)

Part of the Stable ABI.

渡された例外オブジェクトから start 属性を取得して *start に格納します。start は NULL であってはなりません。成功したら 0 を、失敗したら -1 を返します。

int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start)

int PyUnicodeEncodeError_SetStart(PyObject *exc, Py_ssize_t start)

int PyUnicodeTranslateError_SetStart(PyObject *exc, Py_ssize_t start)

Part of the Stable ABI.

渡された例外オブジェクトの start 属性を start に設定します。成功したら 0 を、失敗したら -1 を返します。

int PyUnicodeDecodeError_GetEnd(PyObject *exc, Py_ssize_t *end)

int PyUnicodeEncodeError_GetEnd(PyObject *exc, Py_ssize_t *end)

int PyUnicodeTranslateError_GetEnd(PyObject *exc, Py_ssize_t *end)

Part of the Stable ABI.

渡された例外オブジェクトから end 属性を取得して *end に格納します。end は NULL であってはなりません。成功したら 0 を、失敗したら -1 を返します。

int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end)

int PyUnicodeEncodeError_SetEnd(PyObject *exc, Py_ssize_t end)

int PyUnicodeTranslateError_SetEnd(PyObject *exc, Py_ssize_t end)

Part of the Stable ABI.

渡された例外オブジェクトの end 属性を end に設定します。成功したら 0 を、失敗したら -1 を返します。

PyObject *PyUnicodeDecodeError_GetReason(PyObject *exc)

PyObject *PyUnicodeEncodeError_GetReason(PyObject *exc)

PyObject *PyUnicodeTranslateError_GetReason(PyObject *exc)

Return value: New reference. Part of the Stable ABI.

渡された例外オブジェクトの reason 属性を返します。

int PyUnicodeDecodeError_SetReason(PyObject *exc, const char *reason)

int PyUnicodeEncodeError_SetReason(PyObject *exc, const char *reason)

int PyUnicodeTranslateError_SetReason(PyObject *exc, const char *reason)

Part of the Stable ABI.

渡された例外オブジェクトの reason 属性を reason に設定します。成功したら 0 を、失敗したら -1 を返します。

再帰の管理

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 call protocol takes care of recursion handling.

int Py_EnterRecursiveCall(const char *where)

Part of the Stable ABI since version 3.9.

C レベルの再帰呼び出しをしようとしているところに印を付けます。

If USE_STACKCHECK is defined, this function checks if the OS stack overflowed using PyOS_CheckStack(). If this is the case, it sets a MemoryError and returns a nonzero value.

次にこの関数は再帰の上限に達していないかをチェックします。上限に達している場合、 RecursionError をセットしゼロでない値を返します。そうでない場合はゼロを返します。

where は " in instance check" のような UTF-8 エンコードされた文字列にして、再帰の深さの限界に達したことで送出される RecursionError のメッセージに連結できるようにすべきです。

バージョン 3.9 で変更: This function is now also available in the limited API.

void Py_LeaveRecursiveCall(void)

Part of the Stable ABI since version 3.9.

Py_EnterRecursiveCall() を終了させます。 Py_EnterRecursiveCall() の 成功した 呼び出しに対し 1 回呼ばなければなりません。

バージョン 3.9 で変更: This function is now also available in the limited API.

コンテナ型に対し tp_repr を適切に実装するには、特殊な再帰の処理が求められます。スタックの防護に加え、 tp_repr は循環処理を避けるためにオブジェクトを辿っていく必要があります。次の 2 つの関数はその機能を容易にします。実質的には、これらは reprlib.recursive_repr() と同等な C の実装です。

int Py_ReprEnter(PyObject *object)

Part of the Stable ABI.

循環処理を検知するために、 tp_repr の実装の先頭で呼び出します。

そのオブジェクトが既に処理されたものだった場合、この関数は正の整数を返します。その場合、 tp_repr の実装は、循環を示す文字列オブジェクトを返すべきです。例えば、 dict オブジェクトは {...} を返しますし、 list オブジェクトは [...] を返します。

再帰回数の上限に達した場合は、この関数は負の整数を返します。この場合、 tp_repr の実装は一般的には NULL を返すべきです。

それ以外の場合は、関数はゼロを返し、 tp_repr の実装は通常どおり処理を続けてかまいません。

void Py_ReprLeave(PyObject *object)

Part of the Stable ABI.

Py_ReprEnter() を終了させます。 0 を返した Py_ReprEnter() の呼び出しに対し 1 回呼ばなければなりません。

標準例外

PyExc_ の後ろにPythonの例外名が続く名前をもつグローバル変数として、すべての標準Python例外が利用可能です。これらは型 PyObject* を持ち、すべてクラスオブジェクトです。完璧を期するために、すべての変数を以下に列挙します:

C名

Python名

注釈

PyExc_BaseException

BaseException

[1]

PyExc_Exception

Exception

[1]

PyExc_ArithmeticError

ArithmeticError

[1]

PyExc_AssertionError

AssertionError

PyExc_AttributeError

AttributeError

PyExc_BlockingIOError

BlockingIOError

PyExc_BrokenPipeError

BrokenPipeError

PyExc_BufferError

BufferError

PyExc_ChildProcessError

ChildProcessError

PyExc_ConnectionAbortedError

ConnectionAbortedError

PyExc_ConnectionError

ConnectionError

PyExc_ConnectionRefusedError

ConnectionRefusedError

PyExc_ConnectionResetError

ConnectionResetError

PyExc_EOFError

EOFError

PyExc_FileExistsError

FileExistsError

PyExc_FileNotFoundError

FileNotFoundError

PyExc_FloatingPointError

FloatingPointError

PyExc_GeneratorExit

GeneratorExit

PyExc_ImportError

ImportError

PyExc_IndentationError

IndentationError

PyExc_IndexError

IndexError

PyExc_InterruptedError

InterruptedError

PyExc_IsADirectoryError

IsADirectoryError

PyExc_KeyError

KeyError

PyExc_KeyboardInterrupt

KeyboardInterrupt

PyExc_LookupError

LookupError

[1]

PyExc_MemoryError

MemoryError

PyExc_ModuleNotFoundError

ModuleNotFoundError

PyExc_NameError

NameError

PyExc_NotADirectoryError

NotADirectoryError

PyExc_NotImplementedError

NotImplementedError

PyExc_OSError

OSError

[1]

PyExc_OverflowError

OverflowError

PyExc_PermissionError

PermissionError

PyExc_ProcessLookupError

ProcessLookupError

PyExc_RecursionError

RecursionError

PyExc_ReferenceError

ReferenceError

PyExc_RuntimeError

RuntimeError

PyExc_StopAsyncIteration

StopAsyncIteration

PyExc_StopIteration

StopIteration

PyExc_SyntaxError

SyntaxError

PyExc_SystemError

SystemError

PyExc_SystemExit

SystemExit

PyExc_TabError

TabError

PyExc_TimeoutError

TimeoutError

PyExc_TypeError

TypeError

PyExc_UnboundLocalError

UnboundLocalError

PyExc_UnicodeDecodeError

UnicodeDecodeError

PyExc_UnicodeEncodeError

UnicodeEncodeError

PyExc_UnicodeError

UnicodeError

PyExc_UnicodeTranslateError

UnicodeTranslateError

PyExc_ValueError

ValueError

PyExc_ZeroDivisionError

ZeroDivisionError

Added in version 3.3: PyExc_BlockingIOError 、 PyExc_BrokenPipeError 、 PyExc_ChildProcessError 、 PyExc_ConnectionError 、 PyExc_ConnectionAbortedError 、 PyExc_ConnectionRefusedError 、 PyExc_ConnectionResetError 、 PyExc_FileExistsError 、 PyExc_FileNotFoundError 、 PyExc_InterruptedError 、 PyExc_IsADirectoryError 、 PyExc_NotADirectoryError 、 PyExc_PermissionError 、 PyExc_ProcessLookupError 、 PyExc_TimeoutError は PEP 3151 [https://peps.python.org/pep-3151/] により導入されました。

Added in version 3.5: PyExc_StopAsyncIteration および PyExc_RecursionError 。

Added in version 3.6: PyExc_ModuleNotFoundError.

これらは互換性のある PyExc_OSError のエイリアスです:

C名

注釈

PyExc_EnvironmentError

PyExc_IOError

PyExc_WindowsError

[2]

バージョン 3.3 で変更: これらのエイリアスは例外の種類を分けるために使われます。

注釈:

[1] (1,2,3,4,5)

これは別の標準例外のためのベースクラスです。

[2]

Windowsでのみ定義されています。プリプロセッサマクロ MS_WINDOWS が定義されているかテストすることで、これを使うコードを保護してください。

標準警告カテゴリ

PyExc_ の後ろにPythonの例外名が続く名前をもつグローバル変数として、すべての標準Python警告カテゴリが利用可能です。これらは型 PyObject* を持ち、すべてクラスオブジェクトです。完璧を期するために、すべての変数を以下に列挙します:

C名

Python名

注釈

PyExc_Warning

Warning

[3]

PyExc_BytesWarning

BytesWarning

PyExc_DeprecationWarning

DeprecationWarning

PyExc_FutureWarning

FutureWarning

PyExc_ImportWarning

ImportWarning

PyExc_PendingDeprecationWarning

PendingDeprecationWarning

PyExc_ResourceWarning

ResourceWarning

PyExc_RuntimeWarning

RuntimeWarning

PyExc_SyntaxWarning

SyntaxWarning

PyExc_UnicodeWarning

UnicodeWarning

PyExc_UserWarning

UserWarning

Added in version 3.2: PyExc_ResourceWarning.

注釈:

[3]

これは別の標準警告カテゴリのためのベースクラスです。

ユーティリティ

この章の関数は、C で書かれたコードをプラットフォーム間で可搬性のあるものにする上で役立つものから、C から Python モジュールを使うもの、そして関数の引数を解釈したり、C の値から Python の値を構築するものまで、様々なユーティリティ的タスクを行います。

オペレーティングシステム関連のユーティリティ

システム関数

プロセス制御

モジュールのインポート

データ整列化 (data marshalling) のサポート

引数の解釈と値の構築

引数を解析する

文字列とバッファ

数

その他のオブジェクト

API 関数

値の構築

文字列の変換と書式化

PyHash API

リフレクション

codec レジストリとサポート関数

コーデック検索API

Unicode エラーハンドラ用レジストリ API

Support for Perf Maps

オペレーティングシステム関連のユーティリティ

PyObject *PyOS_FSPath(PyObject *path)

Return value: New reference. Part of the Stable ABI since version 3.6.

Return the file system representation for path. If the object is a str or bytes object, then a new strong reference is returned. If the object implements the os.PathLike interface, then __fspath__() is returned as long as it is a str or bytes object. Otherwise TypeError is raised and NULL is returned.

Added in version 3.6.

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 isatty(fileno(fp)) is true. If the PyConfig.interactive is non-zero, this function also returns true if the filename pointer is NULL or if the name is equal to one of the strings '<stdin>' or '???'.

This function must not be called before Python is initialized.

void PyOS_BeforeFork()

Part of the Stable ABI on platforms with fork() since version 3.7.

プロセスがフォークする前に、いくつかの内部状態を準備するための関数です。fork() や現在のプロセスを複製するその他の類似の関数を呼び出す前にこの関数を呼びださなければなりません。fork() が定義されているシステムでのみ利用できます。

警告

The C fork() call should only be made from the "main" thread (of the "main" interpreter). The same is true for PyOS_BeforeFork().

Added in version 3.7.

void PyOS_AfterFork_Parent()

Part of the Stable ABI on platforms with fork() since version 3.7.

プロセスがフォークした後に内部状態を更新するための関数です。 fork() や、現在のプロセスを複製するその他の類似の関数を呼び出した後に、プロセスの複製が成功したかどうかにかかわらず、親プロセスからこの関数を呼び出さなければなりません。fork() が定義されているシステムでのみ利用できます。

警告

The C fork() call should only be made from the "main" thread (of the "main" interpreter). The same is true for PyOS_AfterFork_Parent().

Added in version 3.7.

void PyOS_AfterFork_Child()

Part of the Stable ABI on platforms with fork() since version 3.7.

Function to update internal interpreter state after a process fork. This must be called from the child process after calling 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 fork() is defined.

警告

The C fork() call should only be made from the "main" thread (of the "main" interpreter). The same is true for PyOS_AfterFork_Child().

Added in version 3.7.

参考

os.register_at_fork() を利用すると PyOS_BeforeFork()、PyOS_AfterFork_Parent() PyOS_AfterFork_Child() によって呼び出されるカスタムのPython関数を登録できます。

void PyOS_AfterFork()

Part of the Stable ABI on platforms with fork().

プロセスが fork した後の内部状態を更新するための関数です; fork 後 Python インタプリタを使い続ける場合、新たなプロセス内でこの関数を呼び出さねばなりません。新たなプロセスに新たな実行可能物をロードする場合、この関数を呼び出す必要はありません。

バージョン 3.7 で非推奨: この関数は PyOS_AfterFork_Child() によって置き換えられました。

int PyOS_CheckStack()

Part of the Stable ABI on platforms with USE_STACKCHECK since version 3.7.

Return true when the interpreter runs out of stack space. This is a reliable check, but is only available when USE_STACKCHECK is defined (currently on certain versions of Windows using the Microsoft Visual C++ compiler). USE_STACKCHECK will be defined automatically; you should never change the definition in your own code.

typedef void (*PyOS_sighandler_t)(int)

Part of the Stable ABI.

PyOS_sighandler_t PyOS_getsig(int i)

Part of the Stable ABI.

Return the current signal handler for signal i. This is a thin wrapper around either sigaction() or signal(). Do not call those functions directly!

PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)

Part of the Stable ABI.

Set the signal handler for signal i to be h; return the old signal handler. This is a thin wrapper around either sigaction() or signal(). Do not call those functions directly!

wchar_t *Py_DecodeLocale(const char *arg, size_t *size)

Part of the Stable ABI since version 3.7.

警告

This function should not be called directly: use the PyConfig API with the PyConfig_SetBytesString() function which ensures that Python is preinitialized.

This function must not be called before Python is preinitialized and so that the LC_CTYPE locale is properly configured: see the Py_PreInitialize() function.

ファイルシステムのエンコーディングとエラーハンドラ からバイト文字列をデコードします。エラーハンドラが surrogateescape エラーハンドラ なら、デコードできないバイトは U+DC80 から U+DCFF までの範囲の文字としてデコードされ、バイト列がサロゲート文字としてデコードできる場合は、デコードするのではなく surrogateescape エラーハンドラを使ってバイト列がエスケープされます。

新しくメモリ確保されたワイドキャラクター文字列へのポインタを返します。このメモリを解放するのには PyMem_RawFree() を使ってください。引数 size が NULL でない場合は、 null 文字以外のワイドキャラクターの数を *size へ書き込みます。

デコードもしくはメモリ確保でエラーが起きると NULL を返します。 size が NULL でない場合は、メモリエラーのときは (size_t)-1 を、デコードでのエラーのときは (size_t)-2 を *size に設定します。

The filesystem encoding and error handler are selected by PyConfig_Read(): see filesystem_encoding and filesystem_errors members of PyConfig.

C ライブラリーにバグがない限り、デコードでのエラーは起こりえません。

キャラクター文字列をバイト文字列に戻すには Py_EncodeLocale() 関数を使ってください。

参考

PyUnicode_DecodeFSDefaultAndSize() および PyUnicode_DecodeLocaleAndSize() 関数。

Added in version 3.5.

バージョン 3.7 で変更: この関数は、Python UTF-8 Mode ではUTF-8エンコーディングを利用するようになりました。

バージョン 3.8 で変更: The function now uses the UTF-8 encoding on Windows if PyPreConfig.legacy_windows_fs_encoding is zero;

char *Py_EncodeLocale(const wchar_t *text, size_t *error_pos)

Part of the Stable ABI since version 3.7.

ワイドキャラクター文字列を ファイルシステムのエンコーディングとエラーハンドラ にエンコードします。エラーハンドラが surrogateescape エラーハンドラ なら、 U+DC80 から U+DCFF までの範囲のサロゲート文字は 0x80 から 0xFF までのバイトに変換されます。

新しくメモリ確保されたバイト文字列へのポインタを返します。このメモリを解放するのには PyMem_Free() を使ってください。エンコードエラーかメモリ確保エラーのときは NULL を返します。

If error_pos is not NULL, *error_pos is set to (size_t)-1 on success, or set to the index of the invalid character on encoding error.

The filesystem encoding and error handler are selected by PyConfig_Read(): see filesystem_encoding and filesystem_errors members of PyConfig.

バイト文字列をワイドキャラクター文字列に戻すには Py_DecodeLocale() 関数を使ってください。

警告

This function must not be called before Python is preinitialized and so that the LC_CTYPE locale is properly configured: see the Py_PreInitialize() function.

参考

PyUnicode_EncodeFSDefault() および PyUnicode_EncodeLocale() 関数。

Added in version 3.5.

バージョン 3.7 で変更: この関数は、Python UTF-8 Mode ではUTF-8エンコーディングを利用するようになりました。

バージョン 3.8 で変更: The function now uses the UTF-8 encoding on Windows if PyPreConfig.legacy_windows_fs_encoding is zero.

システム関数

sys モジュールが提供している機能にCのコードからアクセスする関数です。すべての関数は現在のインタプリタスレッドの sys モジュールの辞書に対して動作します。この辞書は内部のスレッド状態構造体に格納されています。

PyObject *PySys_GetObject(const char *name)

Return value: Borrowed reference. Part of the Stable ABI.

sys モジュールの name オブジェクトを返すか、存在しなければ例外を設定せずに NULL を返します。

int PySys_SetObject(const char *name, PyObject *v)

Part of the Stable ABI.

v が NULL で無い場合、 sys モジュールの name に v を設定します。 v が NULL なら、 sys モジュールから name を削除します。成功したら 0 を、エラー時は -1 を返します。

void PySys_ResetWarnOptions()

Part of the Stable ABI.

Reset sys.warnoptions to an empty list. This function may be called prior to Py_Initialize().

void PySys_AddWarnOption(const wchar_t *s)

Part of the Stable ABI.

This API is kept for backward compatibility: setting PyConfig.warnoptions should be used instead, see Python Initialization Configuration.

Append s to sys.warnoptions. This function must be called prior to Py_Initialize() in order to affect the warnings filter list.

バージョン 3.11 で非推奨.

void PySys_AddWarnOptionUnicode(PyObject *unicode)

Part of the Stable ABI.

This API is kept for backward compatibility: setting PyConfig.warnoptions should be used instead, see Python Initialization Configuration.

Append unicode to sys.warnoptions.

Note: this function is not currently usable from outside the CPython implementation, as it must be called prior to the implicit import of warnings in Py_Initialize() to be effective, but can't be called until enough of the runtime has been initialized to permit the creation of Unicode objects.

バージョン 3.11 で非推奨.

void PySys_SetPath(const wchar_t *path)

Part of the Stable ABI.

This API is kept for backward compatibility: setting PyConfig.module_search_paths and PyConfig.module_search_paths_set should be used instead, see Python Initialization Configuration.

Set sys.path to a list object of paths found in path which should be a list of paths separated with the platform's search path delimiter (: on Unix, ; on Windows).

バージョン 3.11 で非推奨.

void PySys_WriteStdout(const char *format, ...)

Part of the Stable ABI.

format で指定された出力文字列を sys.stdout に出力します。切り詰めが起こった場合を含め、例外は一切発生しません (後述)。

format は、フォーマット後の出力文字列のトータルの大きさを1000バイト以下に抑えるべきです。-- 1000 バイト以降の出力文字列は切り詰められます。特に、制限のない "%s" フォーマットを使うべきではありません。"%.<N>s" のようにして N に10進数の値を指定し、<N> + その他のフォーマット後の最大サイズが1000を超えないように設定するべきです。同じように "%f" にも気を付ける必要があります。非常に大きい数値に対して、数百の数字を出力する可能性があります。

問題が発生したり、 sys.stdout が設定されていなかった場合、フォーマット後のメッセージは本物の(Cレベルの) stdout に出力されます。

void PySys_WriteStderr(const char *format, ...)

Part of the Stable ABI.

PySys_WriteStdout() と同じですが、 sys.stderr もしくは stderr に出力します。

void PySys_FormatStdout(const char *format, ...)

Part of the Stable ABI.

PySys_WriteStdout() に似た関数ですが、 PyUnicode_FromFormatV() を使ってメッセージをフォーマットし、メッセージを任意の長さに切り詰めたりはしません。

Added in version 3.2.

void PySys_FormatStderr(const char *format, ...)

Part of the Stable ABI.

PySys_FormatStdout() と同じですが、 sys.stderr もしくは stderr に出力します。

Added in version 3.2.

void PySys_AddXOption(const wchar_t *s)

Part of the Stable ABI since version 3.7.

This API is kept for backward compatibility: setting PyConfig.xoptions should be used instead, see Python Initialization Configuration.

Parse s as a set of -X options and add them to the current options mapping as returned by PySys_GetXOptions(). This function may be called prior to Py_Initialize().

Added in version 3.2.

バージョン 3.11 で非推奨.

PyObject *PySys_GetXOptions()

Return value: Borrowed reference. Part of the Stable ABI since version 3.7.

sys._xoptions と同様、 -X オプションの現在の辞書を返します。エラーが起きると、 NULL が返され、例外がセットされます。

Added in version 3.2.

int PySys_Audit(const char *event, const char *format, ...)

Raise an auditing event with any active hooks. Return zero for success and non-zero with an exception set on failure.

If any hooks have been added, format and other arguments will be used to construct a tuple to pass. Apart from N, the same format characters as used in Py_BuildValue() are available. If the built value is not a tuple, it will be added into a single-element tuple. (The N format option 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 # format characters should always be treated as Py_ssize_t, regardless of whether PY_SSIZE_T_CLEAN was defined.

sys.audit() performs the same function from Python code.

Added in version 3.8.

バージョン 3.8.2 で変更: Require Py_ssize_t for # format characters. Previously, an unavoidable deprecation warning was raised.

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.

userData ポインタはフック関数に渡されます。フック関数は別なランタイムから呼び出されるかもしれないので、このポインタは直接 Python の状態を参照すべきではありません。

This function is safe to call before Py_Initialize(). When called after runtime initialization, existing audit hooks are notified and may silently abort the operation by raising an error subclassed from Exception (other errors will not be silenced).

The hook function is always called with the GIL held by the Python interpreter that raised the event.

See PEP 578 [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 audit events table. Details are in each function's documentation.

引数無しで 監査イベント sys.addaudithook を送出します。

typedef int (*Py_AuditHookFunction)(const char *event, PyObject *args, void *userData)

The type of the hook function. event is the C string event argument passed to PySys_Audit(). args is guaranteed to be a PyTupleObject. userData is the argument passed to PySys_AddAuditHook().

Added in version 3.8.

プロセス制御

void Py_FatalError(const char *message)

Part of the Stable ABI.

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 abort() is called which will attempt to produce a core file.

The Py_FatalError() function is replaced with a macro which logs automatically the name of the current function, unless the Py_LIMITED_API macro is defined.

バージョン 3.9 で変更: Log the function name automatically.

void Py_Exit(int status)

Part of the Stable ABI.

現在のプロセスを終了します。Py_FinalizeEx() を呼び出した後、標準Cライブラリ関数の exit(status) を呼び出します。Py_FinalizeEx() がエラーになった場合、終了ステータスは 120に設定されます。

バージョン 3.6 で変更: 終了処理のエラーは無視されなくなりました。

int Py_AtExit(void (*func)())

Part of the Stable ABI.

Py_FinalizeEx() から呼び出される後始末処理を行う関数 (cleanup function) を登録します。後始末関数は引数無しで呼び出され、値を返しません。最大で 32 の後始末処理関数を登録できます。登録に成功すると、 Py_AtExit() は 0 を返します; 失敗すると -1 を返します。最後に登録した後始末処理関数から先に呼び出されます。各関数は高々一度しか呼び出されません。 Python の内部的な終了処理は後始末処理関数より以前に完了しているので、 func からはいかなる Python API も呼び出してはなりません。

モジュールのインポート

PyObject *PyImport_ImportModule(const char *name)

Return value: New reference. Part of the Stable ABI.

This is a wrapper around PyImport_Import() which takes a const char* as an argument instead of a PyObject*.

PyObject *PyImport_ImportModuleNoBlock(const char *name)

Return value: New reference. Part of the Stable ABI.

この関数は、 PyImport_ImportModule() の廃止予定のエイリアスです。

バージョン 3.3 で変更: この関数は、従来は別のスレッドによってインポートロックが行われていた場合は即座に失敗していました。しかし Python 3.3 では、大部分の目的でロックスキームがモジュールごとのロックに移行したので、この関数の特別な振る舞いはもはや必要ではありません。

PyObject *PyImport_ImportModuleEx(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)

Return value: New reference.

モジュールをインポートします。モジュールのインポートについては組み込みの Python 関数 __import__() を読むとよくわかります。

戻り値は、インポートされたモジュールかトップレベルパッケージへの新しい参照か、失敗した場合は例外を設定して NULL を返します。 __import__() と同じように、パッケージのサブモジュールが要求されたときは、空でない fromlist を渡された時以外は、トップレベルのパッケージを返します。

インポートが失敗した場合は、PyImport_ImportModule() と同様に不完全なモジュールのオブジェクトを削除します。

PyObject *PyImport_ImportModuleLevelObject(PyObject *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)

Return value: New reference. Part of the Stable ABI since version 3.7.

モジュールをインポートします。モジュールのインポートについては組み込みの Python 関数 __import__() を読むとよく分かります。というのも、標準の __import__() はこの関数を直接呼び出しているからです。

戻り値は、インポートされたモジュールかトップレベルパッケージへの新しい参照か、失敗した場合は例外を設定して NULL を返します。 __import__() と同じように、パッケージのサブモジュールが要求されたときは、空でない fromlist を渡された時以外は、トップレベルのパッケージを返します。

Added in version 3.3.

PyObject *PyImport_ImportModuleLevel(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)

Return value: New reference. Part of the Stable ABI.

PyImport_ImportModuleLevelObject() と似ていますが、name が Unicode オブジェクトではなく UTF-8 でエンコードされた文字列である点で異なります。

バージョン 3.3 で変更: level にはもはや負の値は使用できません。

PyObject *PyImport_Import(PyObject *name)

Return value: New reference. Part of the Stable ABI.

現在の "インポートフック関数" を呼び出すための高水準のインターフェースです (level に 0 を明示すると、絶対インポートを意味します)。 この関数は現在のグローバル変数辞書内の __builtins__ から __import__() 関数を呼び出します。すなわち、現在の環境にインストールされているインポートフック使ってインポートを行います。

この関数は常に絶対インポートを使用します。

PyObject *PyImport_ReloadModule(PyObject *m)

Return value: New reference. Part of the Stable ABI.

モジュールを再ロード (reload) します。戻り値は再ロードしたモジュールかトップレベルパッケージへの新たな参照になります。失敗した場合には例外をセットし、NULL を返します (その場合でも、モジュールは生成されている場合があります)。

PyObject *PyImport_AddModuleObject(PyObject *name)

Return value: Borrowed reference. Part of the Stable ABI since version 3.7.

Return the module object corresponding to a module name. The name argument may be of the form 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 NULL with an exception set on failure.

注釈

This function does not load or import the module; if the module wasn't already loaded, you will get an empty module object. Use PyImport_ImportModule() or one of its variants to import a module. Package structures implied by a dotted name for name are not created if not already present.

Added in version 3.3.

PyObject *PyImport_AddModule(const char *name)

Return value: Borrowed reference. Part of the Stable ABI.

Similar to PyImport_AddModuleObject(), but the name is a UTF-8 encoded string instead of a Unicode object.

PyObject *PyImport_ExecCodeModule(const char *name, PyObject *co)

Return value: New reference. Part of the Stable ABI.

Given a module name (possibly of the form package.module) and a code object read from a Python bytecode file or obtained from the built-in function compile(), load the module. Return a new reference to the module object, or NULL with an exception set if an error occurred. name is removed from sys.modules in error cases, even if name was already in sys.modules on entry to PyImport_ExecCodeModule(). Leaving incompletely initialized modules in 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 __spec__ and __loader__ will be set, if not set already, with the appropriate values. The spec's loader will be set to the module's __loader__ (if set) and to an instance of SourceFileLoader otherwise.

The module's __file__ attribute will be set to the code object's co_filename. If applicable, __cached__ will also be set.

この関数は、すでにインポートされているモジュールの場合には再ロードを行います。意図的にモジュールの再ロードを行う方法は PyImport_ReloadModule() を参照してください。

name が package.module 形式のドット名表記であった場合、まだ作成されていないパッケージ構造はその作成されないままになります。

PyImport_ExecCodeModuleEx() と PyImport_ExecCodeModuleWithPathnames() も参照してください。

バージョン 3.12 で変更: The setting of __cached__ and __loader__ is deprecated. See ModuleSpec for alternatives.

PyObject *PyImport_ExecCodeModuleEx(const char *name, PyObject *co, const char *pathname)

Return value: New reference. Part of the Stable ABI.

PyImport_ExecCodeModule() と似ていますが、pathname が NULL でない場合にモジュールオブジェクトの __file__ 属性に pathname が設定される点が異なります。

PyImport_ExecCodeModuleWithPathnames() も参照してください。

PyObject *PyImport_ExecCodeModuleObject(PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)

Return value: New reference. Part of the Stable ABI since version 3.7.

PyImport_ExecCodeModuleEx() と似ていますが、cpathname が NULL でない場合にモジュールオブジェクトの __cached__ 属性に cpathname が設定される点が異なります。これらの 3 つの関数のうち、この関数の使用が望ましいです。

Added in version 3.3.

バージョン 3.12 で変更: Setting __cached__ is deprecated. See ModuleSpec for alternatives.

PyObject *PyImport_ExecCodeModuleWithPathnames(const char *name, PyObject *co, const char *pathname, const char *cpathname)

Return value: New reference. Part of the Stable ABI.

PyImport_ExecCodeModuleObject() と似ていますが、 name と pathname、 cpathname が UTF-8 でエンコードされた文字列である点が異なります。もし pathname が NULL の場合、cpathname から、pathname どのような値になるべきかを知る試みもなされます。

Added in version 3.2.

バージョン 3.3 で変更: Uses imp.source_from_cache() in calculating the source path if only the bytecode path is provided.

バージョン 3.12 で変更: No longer uses the removed imp module.

long PyImport_GetMagicNumber()

Part of the Stable ABI.

Python バイトコードファイル (別名 .pyc ファイル) のマジックナンバーを返します。マジックナンバーはバイトコードファイルの最初の4バイトに、リトルエンディアンバイトオーダーで現れるべきです。エラーの場合は -1 を返します。

バージョン 3.3 で変更: 失敗した場合は -1 の値を返します。

const char *PyImport_GetMagicTag()

Part of the Stable ABI.

マジックタグ文字列を Python バイトコードファイル名の PEP 3147 [https://peps.python.org/pep-3147/] フォーマットで返します。sys.implementation.cache_tag の値が信頼でき、かつこの関数の代わりに使用すべきであることを肝に命じましょう。

Added in version 3.2.

PyObject *PyImport_GetModuleDict()

Return value: Borrowed reference. Part of the Stable ABI.

モジュール管理のための辞書 (いわゆる sys.modules)を返します。この辞書はインタプリタごとに一つだけある変数なので注意してください。

PyObject *PyImport_GetModule(PyObject *name)

Return value: New reference. Part of the Stable ABI since version 3.8.

与えられた名前の既にインポート済みのモジュールを返します。モジュールがインポートされていなかった場合は、 NULL を返しますが、エラーはセットしません。モジュールの検索に失敗した場合は、 NULL を返し、エラーをセットします。

Added in version 3.7.

PyObject *PyImport_GetImporter(PyObject *path)

Return value: New reference. Part of the Stable ABI.

Return a finder object for a sys.path/pkg.__path__ item path, possibly by fetching it from the sys.path_importer_cache dict. If it wasn't yet cached, traverse sys.path_hooks until a hook is found that can handle the path item. Return None if no hook could; this tells our caller that the path based finder could not find a finder for this path item. Cache the result in sys.path_importer_cache. Return a new reference to the finder object.

int PyImport_ImportFrozenModuleObject(PyObject *name)

Part of the Stable ABI since version 3.7.

name という名前のフリーズ (freeze) されたモジュールをロードします。成功すると 1 を、モジュールが見つからなかった場合には 0 を、初期化が失敗した場合には例外をセットして -1 を返します。ロードに成功したモジュールにアクセスするには PyImport_ImportModule() を使ってください。 (Note この関数はいささか誤解を招く名前です --- この関数はモジュールがすでにインポートされていたらリロードしてしまいます。)

Added in version 3.3.

バージョン 3.4 で変更: __file__ 属性はもうモジュールにセットされません。

int PyImport_ImportFrozenModule(const char *name)

Part of the Stable ABI.

PyImport_ImportFrozenModuleObject() と似ていますが、name は UTF-8 でエンコードされた文字列の代わりに、 Unicode オブジェクトを使用する点が異なります。

struct _frozen

freeze ユーティリティが生成するようなフリーズ化モジュールデスクリプタの構造体型定義です。 (Python ソース配布物の Tools/freeze/ を参照してください) この構造体の定義は Include/import.h にあり、以下のようになっています:

struct _frozen {
    const char *name;
    const unsigned char *code;
    int size;
    bool is_package;
};

バージョン 3.11 で変更: The new is_package field indicates whether the module is a package or not. This replaces setting the size field to a negative value.

const struct _frozen *PyImport_FrozenModules

このポインタは _frozen のレコードからなり、終端の要素のメンバが NULL かゼロになっているような配列を指すよう初期化されます。フリーズされたモジュールをインポートするとき、このテーブルを検索します。サードパーティ製のコードからこのポインタに仕掛けを講じて、動的に生成されたフリーズ化モジュールの集合を提供するようにできます。

int PyImport_AppendInittab(const char *name, PyObject *(*initfunc)(void))

Part of the Stable ABI.

既存の組み込みモジュールテーブルに単一のモジュールを追加します。この関数は利便性を目的とした PyImport_ExtendInittab() のラッパー関数で、テーブルが拡張できないときには -1 を返します。新たなモジュールは name でインポートでき、最初にインポートを試みた際に呼び出される関数として initfunc を使います。 Py_Initialize() よりも前に呼び出さなければなりません。

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 PyImport_ExtendInittab() to provide additional built-in modules. The structure consists of two members:

const char *name

The module name, as an ASCII encoded string.

PyObject *(*initfunc)(void)

Initialization function for a module built into the interpreter.

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 NULL for the name field; failure to provide the sentinel value can result in a memory fault. Returns 0 on success or -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 Py_Initialize().

Python が複数回初期化される場合、PyImport_AppendInittab() または PyImport_ExtendInittab() は、それぞれの初期化の前に呼び出される必要があります。

データ整列化 (data marshalling) のサポート

以下のルーチン群は、 marshal モジュールと同じ形式を使った整列化オブジェクトを C コードから使えるようにします。整列化形式でデータを書き出す関数に加えて、データを読み戻す関数もあります。整列化されたデータを記録するファイルはバイナリモードで開かれていなければなりません。

数値は最小桁が先にくるように記録されます。

このモジュールでは、3つのバージョンのデータ形式をサポートしています。バージョン 0 は従来のもので、バージョン 1 は intern 化された文字列をファイル内で共有し、逆マーシャル化の時にも共有されるようにします。バージョン2は、浮動小数点数に対してバイナリフォーマットを利用します。 Py_MARSHAL_VERSION は現在のバージョン (バージョン 2) を示します。

void PyMarshal_WriteLongToFile(long value, FILE *file, int version)

long 型の整数値 value を file へ整列化します。この関数は value の下桁 32 ビットを書き込むだけです; ネイティブの long 型サイズには関知しません。 version はファイルフォーマットを示します。

この関数は失敗することがあり、その場合はエラー指示子を設定します。それを確認するために PyErr_Occurred() を使います。

void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)

Python オブジェクト value を file へ整列化します。version はファイルフォーマットを示します。

この関数は失敗することがあり、その場合はエラー指示子を設定します。それを確認するために PyErr_Occurred() を使います。

PyObject *PyMarshal_WriteObjectToString(PyObject *value, int version)

Return value: New reference.

value の整列化表現が入ったバイト列オブジェクトを返します。version はファイルフォーマットを示します。

以下の関数を使うと、整列化された値を読み戻せます。

long PyMarshal_ReadLongFromFile(FILE *file)

読み出し用に開かれた FILE* 内のデータストリームから、 C の long 型データを読み出して返します。この関数は、ネイティブの long のサイズに関係なく、 32 ビットの値だけを読み出せます。

エラーの場合、適切な例外 (EOFError) を設定し -1 を返します。

int PyMarshal_ReadShortFromFile(FILE *file)

読み出し用に開かれた FILE* 内のデータストリームから、 C の short 型データを読み出して返します。この関数は、ネイティブの short のサイズに関係なく、 16 ビットの値だけを読み出せます。

エラーの場合、適切な例外 (EOFError) を設定し -1 を返します。

PyObject *PyMarshal_ReadObjectFromFile(FILE *file)

Return value: New reference.

読み出し用に開かれた FILE* 内のデータストリームから Python オブジェクトを返します。

エラーの場合、適切な例外 (EOFError, ValueError, TypeError) を設定し NULL を返します。

PyObject *PyMarshal_ReadLastObjectFromFile(FILE *file)

Return value: New reference.

読み出し用に開かれた FILE* 内のデータストリームから、 Python オブジェクトを読み出して返します。 PyMarshal_ReadObjectFromFile() と違い、この関数はファイル中に後続のオブジェクトが存在しないと仮定し、ファイルからメモリ上にファイルデータを一気にメモリにロードして、逆整列化機構がファイルから一バイトづつ読み出す代わりにメモリ上のデータを操作できるようにします。対象のファイルから他に何も読み出さないと分かっている場合にのみ、この関数を使ってください。

エラーの場合、適切な例外 (EOFError, ValueError, TypeError) を設定し NULL を返します。

PyObject *PyMarshal_ReadObjectFromString(const char *data, Py_ssize_t len)

Return value: New reference.

data が指す len バイトのバイト列バッファ内のデータストリームから Python オブジェクトを返します。

エラーの場合、適切な例外 (EOFError, ValueError, TypeError) を設定し NULL を返します。

引数の解釈と値の構築

これらの関数は独自の拡張モジュール用の関数やメソッドを作成する際に便利です。詳しい情報や用例は Python インタプリタの拡張と埋め込み にあります。

最初に説明する 3 つの関数、 PyArg_ParseTuple(), PyArg_ParseTupleAndKeywords(),および PyArg_Parse() はいずれも 書式文字列 (format string) を使います。書式文字列は、関数が受け取るはずの引数に関する情報を伝えるのに用いられます。いずれの関数における書式文字列も、同じ書式を使っています。

引数を解析する

書式文字列は、ゼロ個またはそれ以上の "書式単位 (format unit)" から成り立ちます。 1つの書式単位は1つの Python オブジェクトを表します; 通常は単一の文字か、書式単位からなる文字列を括弧で囲ったものになります。例外として、括弧で囲われていない書式単位文字列が単一のアドレス引数に対応する場合がいくつかあります。以下の説明では、引用符のついた形式は書式単位です; (丸)括弧で囲った部分は書式単位に対応する Python のオブジェクト型です; [角] 括弧は値をアドレス渡しする際に使う C の変数型です。

文字列とバッファ

以下のフォーマットはオブジェクトに連続したメモリチャンクとしてアクセスするためのものです。返される unicode や bytes のために生のストレージを用意する必要はありません。

特に言及されていない場合、バッファーは NUL 終端されていません。

There are three ways strings and buffers can be converted to C:

Formats such as y* and s* fill a Py_buffer structure. This locks the underlying buffer so that the caller can subsequently use the buffer even inside a Py_BEGIN_ALLOW_THREADS block without the risk of mutable data being resized or destroyed. As a result, you have to call PyBuffer_Release() after you have finished processing the data (or in any early abort case).

The es, es#, et and et# formats allocate the result buffer. You have to call PyMem_Free() after you have finished processing the data (or in any early abort case).

Other formats take a str or a read-only bytes-like object, such as bytes, and provide a 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 PyBufferProcs.bf_releasebuffer field must be NULL. This disallows common mutable objects such as bytearray, but also some read-only objects such as memoryview of bytes.

Besides this 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).

注釈

For all # variants of formats (s#, y#, etc.), the macro PY_SSIZE_T_CLEAN must be defined before including Python.h. On Python 3.9 and older, the type of the length argument is Py_ssize_t if the PY_SSIZE_T_CLEAN macro is defined, or int otherwise.

s (str) [const char *]

Unicode オブジェクトを、キャラクタ文字列を指す C のポインタに変換します。キャラクタ型ポインタ変数のアドレスを渡すと、すでに存在している文字列へのポインタをその変数に記録します。C 文字列は NUL で終端されています。Python の文字列型は、 null コードポイントが途中に埋め込まれていてはなりません; もし埋め込まれていれば ValueError 例外を送出します。Unicode オブジェクトは 'utf-8' を使って C 文字列に変換されます。変換に失敗すると UnicodeError を送出します。

注釈

このフォーマットは bytes-like objects をサポートしません。ファイルシステムパスを受け取って C 言語の文字列に変換したい場合は、 O& フォーマットを、 converter に PyUnicode_FSConverter() を指定して利用すると良いです。

バージョン 3.5 で変更: 以前は Python 文字列に null コードポイントが埋め込まれていたときに TypeError を送出していました。

s* (str または bytes-like object) [Py_buffer]

このフォーマットは Unicode オブジェクトと bytes-like object を受け付けて、呼び出し元から渡された Py_buffer 構造体に値を格納します。結果の C 文字列は NUL バイトを含むかもしれません。 Unicode オブジェクトは 'utf-8' エンコーディングで C 文字列に変換されます。

s# (str, 読み取り専用の bytes-like object) [const char *, Py_ssize_t]

Like s*, except that it provides a 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 'utf-8' encoding.

z (str または None) [const char *]

s に似ていますが、Python オブジェクトは None でもよく、その場合には C のポインタは NULL にセットされます。

z* (str, bytes-like object または None) [Py_buffer]

s* と同じですが、 Python の None オブジェクトを受け取ることができます。その場合、 Py_buffer 構造体の buf メンバーは NULL になります。

z# (str, 読み出し専用の bytes-like object または None) [const char *, Py_ssize_t]

s# に似ていますが、Python オブジェクトは None でもよく、その場合には C のポインタは NULL にセットされます。

y (読み出し専用の bytes-like object) [const char *]

This format converts a bytes-like object to a C pointer to a borrowed character string; it does not accept Unicode objects. The bytes buffer must not contain embedded null bytes; if it does, a ValueError exception is raised.

バージョン 3.5 で変更: 以前は bytes バッファにヌルバイトが埋め込まれていたときに TypeError を送出していました。

y* (bytes-like object) [Py_buffer]

s* の変形で、 Unicode オブジェクトを受け付けず、 bytes-like object のみを受け付けます。バイナリデータを受け付ける目的には、このフォーマットを使うことを推奨します。

y# (読み出し専用の bytes-like object) [const char *, Py_ssize_t]

s# の変形で、 Unicode オブジェクトを受け付けず、bytes-like object だけを受け付けます。

S (bytes) [PyBytesObject *]

Pythonオブジェクトとして、 bytes オブジェクトを要求し、いかなる変換も行いません。オブジェクトが bytes オブジェクトでなければ、 TypeError を送出します。C 変数は PyObject* と宣言しても構いません。

Y (bytearray) [PyByteArrayObject *]

Python オブジェクトとして bytearray オブジェクトを要求し、いかなる変換もおこないません。 もしオブジェクトが bytearray でなければ、 TypeError を送出します。C 変数は PyObject* として宣言しても構いません。

U (str) [PyObject *]

Python オブジェクトとして Unicode オブジェクトを要求し、いかなる変換も行いません。オブジェクトが Unicode オブジェクトではない場合、 TypeError が送出されます。C変数は PyObject* として宣言しても構いません。

w* (読み書き可能な bytes-like object) [Py_buffer]

このフォーマットは、読み書き可能な buffer interface を実装したオブジェクトを受け付けます。 呼び出し元から渡された Py_buffer 構造体に値を格納します。バッファは nullバイトを含むかもしれず、呼び出し元はバッファを使い終わったら PyBuffer_Release() を呼び出さなければなりません。

es (str) [const char *encoding, char **buffer]

これは s の変化形で、Unicodeをキャラクタ型バッファにエンコードするために用いられます。NULバイトが埋め込まれていないデータでのみ動作します。

この書式には二つの引数が必要です。一つ目は入力にのみ用いられ、 NUL で終端されたエンコード名文字列を指す const char* 型または、 'utf-8' が使われることを表す NULL でなければなりません。指定したエンコード名を Python が理解できない場合には例外を送出します。第二の引数は char** でなければなりません; この引数が参照しているポインタの値は、引数に指定したテキストの内容が入ったバッファへのポインタになります。テキストは最初の引数に指定したエンコード方式でエンコードされます。

PyArg_ParseTuple() を使うと、必要なサイズのバッファを確保し、そのバッファにエンコード後のデータをコピーして、 *buffer がこの新たに確保された記憶領域を指すように変更します。呼び出し側には、確保されたバッファを使い終わった後に PyMem_Free() で解放する責任があります。

et (str, bytes または bytearray) [const char *encoding, char **buffer]

es と同じです。ただし、バイト文字列オブジェクトをエンコードし直さずに渡します。その代わり、実装ではバイト文字列オブジェクトがパラメタに渡したエンコードを使っているものと仮定します。

es# (str) [const char *encoding, char **buffer, Py_ssize_t *buffer_length]

s# の変化形で、Unicode をキャラクタ型バッファにエンコードするために用いられます。es 書式違って、この変化形はバイトが埋め込まれていてもかまいません。

この書式には三つの引数が必要です。一つ目は入力にのみ用いられ、 NUL で終端されたエンコード名文字列を指す const char* 型か NULL でなければなりません。 NULL の場合には 'utf-8' を使います。指定したエンコード名を Python が理解できない場合には例外を送出します。第二の引数は char** でなければなりません; この引数が参照しているポインタの値は、引数に指定したテキストの内容が入ったバッファへのポインタになります。テキストは最初の引数に指定したエンコード方式でエンコードされます。第三の引数は整数へのポインタでなければなりません; ポインタが参照している整数の値は出力バッファ内のバイト数にセットされます。

この書式の処理には二つのモードがあります:

*buffer が NULL ポインタを指している場合、関数は必要なサイズのバッファを確保し、そのバッファにエンコード後のデータをコピーして、 *buffer がこの新たに確保された記憶領域を指すように変更します。呼び出し側には、確保されたバッファを使い終わった後に PyMem_Free() で解放する責任があります。

*buffer が非 NULL のポインタ (すでにメモリ確保済みのバッファ) を指している場合、 PyArg_ParseTuple() はこのメモリ位置をバッファとして用い、 *buffer_length の初期値をバッファサイズとして用います。 PyArg_ParseTuple は次にエンコード済みのデータをバッファにコピーして、NUL で終端します。バッファの大きさが足りなければ ValueError がセットされます。

どちらの場合も、 *buffer_length は終端の NUL バイトを含まないエンコード済みデータの長さにセットされます。

et# (str, bytes または bytearray) [const char *encoding, char **buffer, Py_ssize_t *buffer_length]

es# と同じです。ただし、バイト文字列オブジェクトをエンコードし直さずに渡します。その代わり、実装ではバイト文字列オブジェクトがパラメタに渡したエンコードを使っているものと仮定します。

バージョン 3.12 で変更: u, u#, Z, and Z# are removed because they used a legacy Py_UNICODE* representation.

数

b (int) [unsigned char]

Python の非負の整数を、 C の unsigned char 型の小さな符号無し整数に変換します。

B (int) [unsigned char]

Python の整数を、オーバフローチェックを行わずに、 C の unsigned char 型の小さな整数に変換します。

h (int) [short int]

Python の整数を、 C の short int 型に変換します。

H (int) [unsigned short int]

Python の整数を、オーバフローチェックを行わずに、 C の unsigned short int 型に変換します。

i (int) [int]

Python の整数を、 C の int 型に変換します。

I (int) [unsigned int]

Python の整数を、オーバフローチェックを行わずに、 C の unsigned int 型に変換します。

l (int) [long int]

Python の整数を、 C の long int 型に変換します。

k (int) [unsigned long]

Python の整数を、オーバフローチェックを行わずに、 C の unsigned long 型に変換します。

L (int) [long long]

Python の整数を、 C の long long 型に変換します。

K (int) [unsigned long long]

PythonのintをC unsigned long long へオーバーフローの確認をせず変換する

n (int) [Py_ssize_t]

Python の整数をCの Py_ssize_t 型に変換します。

c (長さ 1 の、 bytes または bytearray) [char]

長さ 1 の bytes または bytearray オブジェクトとして表現されている Python バイトを C の char 型に変換します。

バージョン 3.3 で変更: bytearray を受け付けるようになりました。

C (長さ 1 の str) [int]

長さ 1 の str オブジェクトとして表現されている Python キャラクタを C の int 型に変換します。

f (float) [float]

Python の浮動小数点型を、 C の float 型に変換します。

d (float) [double]

Python の浮動小数点型を、 C の double 型に変換します。

D (complex) [Py_complex]

Python の複素数型を、 C の Py_complex 構造体に変換します。

その他のオブジェクト

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 strong reference to the object is not created (i.e. its reference count is not increased). The pointer stored is not NULL.

O! (object) [typeobject, PyObject *]

Python オブジェクトを C の Python オブジェクト型ポインタに保存します。 O に似ていますが、二つの C の引数をとります: 一つ目の引数は Python の型オブジェクトへのアドレスで、二つ目の引数はオブジェクトへのポインタが保存されている (PyObject* の) C の変数へのアドレスです。Python オブジェクトが指定した型ではない場合、 TypeError を送出します。

O& (object) [converter, anything]

Python オブジェクトを converter 関数を介して C の変数に変換します。二つの引数をとります: 一つ目は関数で、二つ目は (任意の型の) C 変数へのアドレスを void* 型に変換したものです。 converter は以下のようにして呼び出されます:

status = converter(object, address);

ここで object は変換対象の Python オブジェクトで、 address は PyArg_Parse* に渡した void* 型の引数です。戻り値 status は変換に成功した際に 1,失敗した場合には 0 になります。変換に失敗した場合、 converter 関数は address の内容を変更せずに例外を送出しなくてはなりません。

もし converter が Py_CLEANUP_SUPPORTED を返すと、引数のパースが失敗した際に、コンバーターをもう一度呼び出し、すでに割り当てたメモリを開放するチャンスを与えます。二度目の呼び出しでは object 引数は NULL になり、address は最初の呼び出しと同じ値になります。

バージョン 3.1 で変更: Py_CLEANUP_SUPPORTED の追加。

p (bool) [int]

真偽値が求められる箇所 (a boolean predicate) に渡された値を判定し、その結果を等価な C の true/false 整数値に変換します。もし式が真なら int には 1 が、偽なら 0 が設定されます。この関数は任意の有効なPython値を受け付けます。 Pythonが値の真偽をどのように判定するかを知りたければ、 真理値判定 を参照してください。

Added in version 3.3.

(items) (tuple) [matching-items]

オブジェクトは items に入っている書式単位の数だけの長さを持つ Python のシーケンス型でなければなりません。各 C 引数は items 内の個々の書式単位に対応づけできなければなりません。シーケンスの書式単位は入れ子構造にできます。

It is possible to pass "long" integers (integers whose value exceeds the platform's LONG_MAX) however no proper range checking is done --- the most significant bits are silently truncated when the receiving field is too small to receive the value (actually, the semantics are inherited from downcasts in C --- your mileage may vary).

その他、書式文字列において意味を持つ文字がいくつかあります。それらの文字は括弧による入れ子内には使えません。以下に文字を示します:

|

Python 引数リスト中で、この文字以降の引数がオプションであることを示します。オプションの引数に対応する C の変数はデフォルトの値で初期化しておかなければなりません --- オプションの引数が省略された場合、 PyArg_ParseTuple() は対応する C 変数の内容に手を加えません。

$

PyArg_ParseTupleAndKeywords() でのみ使用可能: 後続のPython引数がキーワード専用であることを示します。現在、すべてのキーワード専用引数は任意の引数でなければならず、そのため フォーマット文字列中の | は常に $ より前に指定されなければなりません。

Added in version 3.3.

:

この文字があると、書式単位の記述はそこで終わります; コロン以降の文字列は、エラーメッセージにおける関数名 (PyArg_ParseTuple() が送出する例外の "付属値 (associated value)") として使われます。

;

この文字があると、書式単位の記述はそこで終わります; セミコロン以降の文字列は、デフォルトエラーメッセージを 置き換える エラーメッセージとして使われます。 : と ; は相互に排他の文字です。

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 argument) は、書式文字列から決定される型へのアドレスでなければなりません; 補助引数に指定したアドレスは、タプルから入力された値を保存するために使います。上の書式単位のリストで説明したように、補助引数を入力値として使う場合がいくつかあります; その場合、対応する書式単位の指定する形式に従うようにしなければなりません。

変換を正しく行うためには、 arg オブジェクトは書式文字に一致しなければならず、かつ書式文字列内の書式単位に全て値が入るようにしなければなりません。成功すると、 PyArg_Parse* 関数は真を返します。それ以外の場合には偽を返し、適切な例外を送出します。書式単位のどれかの変換失敗により PyArg_Parse* が失敗した場合、失敗した書式単位に対応するアドレスとそれ以降のアドレスの内容は変更されません。

API 関数

int PyArg_ParseTuple(PyObject *args, const char *format, ...)

Part of the Stable ABI.

位置引数のみを引数にとる関数のパラメタを解釈して、ローカルな変数に変換します。成功すると真を返します;失敗すると偽を返し、適切な例外を送出します。

int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)

Part of the Stable ABI.

PyArg_ParseTuple() と同じですが、可変長の引数ではなく va_list を引数にとります。

int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)

Part of the Stable ABI.

Parse the parameters of a function that takes both positional and keyword parameters into local variables. The keywords argument is a NULL-terminated array of keyword parameter names. Empty names denote positional-only parameters. Returns true on success; on failure, it returns false and raises the appropriate exception.

バージョン 3.6 で変更: 位置専用引数 を追加した。

int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)

Part of the Stable ABI.

PyArg_ParseTupleAndKeywords() と同じですが、可変長の引数ではなく va_list を引数にとります。

int PyArg_ValidateKeywordArguments(PyObject*)

Part of the Stable ABI.

キーワード引数を格納した辞書のキーが文字列であることを確認します。この関数は PyArg_ParseTupleAndKeywords() を使用しないときにのみ必要で、その理由は後者の関数は同様のチェックを実施するためです。

Added in version 3.2.

int PyArg_Parse(PyObject *args, const char *format, ...)

Part of the Stable ABI.

Function used to deconstruct the argument lists of "old-style" functions --- these are functions which use the METH_OLDARGS parameter parsing method, which has been removed in Python 3. This is not recommended for use in parameter parsing in new code, and most code in the standard interpreter has been modified to no longer use this for that purpose. It does remain a convenient way to decompose other tuples, however, and may continue to be used for that purpose.

int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)

Part of the Stable ABI.

A simpler form of parameter retrieval which does not use a format string to specify the types of the arguments. Functions which use this method to retrieve their parameters should be declared as 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 PyObject* variable; these will be filled in with the values from args; they will contain 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 _weakref helper module for weak references:

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;
}

この例における PyArg_UnpackTuple() 呼び出しは、 PyArg_ParseTuple() を使った以下の呼び出しと全く等価です:

PyArg_ParseTuple(args, "O|O:ref", &object, &callback)

値の構築

PyObject *Py_BuildValue(const char *format, ...)

Return value: New reference. Part of the Stable ABI.

PyArg_Parse* ファミリの関数が受け取るのと似た形式の書式文字列および値列に基づいて、新たな値を生成します。生成した値を返します。エラーの場合には NULL を返します; NULL を返す場合、例外を送出するでしょう。

Py_BuildValue() は常にタプルを生成するとは限りません。この関数がタプルを生成するのは、書式文字列に二つ以上の書式単位が入っているときだけです。書式文字列が空の場合 None を返します; 書式単位が厳密に一つだけ入っている場合、書式単位で指定されている何らかのオブジェクト単体を返します。サイズがゼロや 1 のタプルを返すように強制するには、丸括弧で囲われた書式文字列を使います。

書式単位 s や s# の場合のように、オブジェクトを構築する際にデータを供給するためにメモリバッファをパラメタとして渡す場合には、指定したデータはコピーされます。 Py_BuildValue() が生成したオブジェクトは、呼び出し側が提供したバッファを決して参照しません。別の言い方をすれば、 malloc() を呼び出してメモリを確保し、それを Py_BuildValue() に渡した場合、コード内で Py_BuildValue() が返った後で free() を呼び出す責任があるということです。

以下の説明では、引用符のついた形式は書式単位です; (丸)括弧で囲った部分は書式単位が返す Python のオブジェクト型です; [角] 括弧は関数に渡す値の C 変数型です。

書式文字列内では、(s# のような書式単位を除いて) スペース、タブ、コロンおよびコンマは無視されます。これらの文字を使うと、長い書式文字列をちょっとだけ読みやすくできます。

s (str または None) [const char *]

null終端された C 文字列を、 'utf-8' エンコーディングを用いて、 Python str オブジェクトに変換します。もし C 文字列ポインタが NULL の場合、 None になります。

s# (str or None) [const char *, Py_ssize_t]

C 文字列とその長さを 'utf-8' エンコーディングを使って Python str オブジェクトに変換します。C 文字列ポインタが NULL の場合、長さは無視され、 None になります。

y (bytes) [const char *]

C 文字列をPython bytes オブジェクトに変換します。もしC 文字列ポインタが NULL だった場合、None を返します。

y# (bytes) [const char *, Py_ssize_t]

これは C 文字列とその長さから Python オブジェクトに変換します。C 文字列ポインタが NULL の場合、長さは無視され None になります。

z (str または None) [const char *]

s と同じです。

z# (str または None) [const char *, Py_ssize_t]

s# と同じです。

u (str) [const wchar_t *]

null 終端された Unicode (UTF-16 または UCS-4) データの wchar_t バッファから Python Unicode オブジェクトに変換します。 Unicode バッファポインタが NULL の場合、 None になります。

u# (str) [const wchar_t *, Py_ssize_t]

Unicode (UTF-16 または UCS-4) データのバッファとその長さから Python Unicode オブジェクトに変換します。 Unicode バッファポインタが NULL の場合、長さは無視され None になります。

U (str または None) [const char *]

s と同じです。

U# (str または None) [const char *, Py_ssize_t]

s# と同じです。

i (int) [int]

通常の C の int を Python の整数オブジェクトに変換します。

b (int) [char]

通常のC の char を Python の整数オブジェクトに変換します。

h (int) [short int]

通常のC の short int を Python の整数オブジェクトに変換します。

l (int) [long int]

C の long int を Python の整数オブジェクトに変換します。

B (int) [unsigned char]

C の unsigned char を Python の整数オブジェクトに変換します。

H (int) [unsigned short int]

C の unsigned short int を Python の整数オブジェクトに変換します。

I (int) [unsigned int]

C の unsigned int を Python の整数オブジェクトに変換します。

k (int) [unsigned long]

C の unsigned long を Python の整数オブジェクトに変換します。

L (int) [long long]

C の long long を Python の整数オブジェクトに変換します。

K (int) [unsigned long long]

C unsigned long long をPythonのintオブジェクトへ変換する。

n (int) [Py_ssize_t]

C の Py_ssize_t を Python の整数オブジェクトに変換します。

c (長さが 1 の bytes) [char]

バイトを表す通常の C の int を、長さ 1 の Python の bytes オブジェクトに変換します。

C (長さ 1 の str) [int]

文字を表す通常の C の int を、長さ 1 の Python の str オブジェクトに変換します。

d (float) [double]

C の double を Python の浮動小数点数に変換します。

f (float) [float]

C の float を Python の浮動小数点数に変換します。

D (complex) [Py_complex *]

C の Py_complex 構造体を Python の複素数型に変換します。

O (object) [PyObject *]

Pass a Python object untouched but create a new strong reference to it (i.e. its reference count is incremented by one). If the object passed in is a NULL pointer, it is assumed that this was caused because the call producing the argument found an error and set an exception. Therefore, Py_BuildValue() will return NULL but won't raise an exception. If no exception has been raised yet, SystemError is set.

S (object) [PyObject *]

O と同じです。

N (object) [PyObject *]

Same as O, except it doesn't create a new strong reference. Useful when the object is created by a call to an object constructor in the argument list.

O& (object) [converter, anything]

anything を converter 関数を介して Python オブジェクトに変換します。この関数は anything (void* と互換の型でなければなりません) を引数にして呼び出され、"新たな" オブジェクトを返すか、失敗した場合には NULL を返すようにしなければなりません。

(items) (tuple) [matching-items]

C の値からなる配列を、同じ要素数を持つ Python のタプルに変換します。

[items] (list) [matching-items]

C の値からなる配列を、同じ要素数を持つ Python のリストに変換します。

{items} (dict) [matching-items]

C の値からなる配列を Python の辞書に変換します。一連のペアからなる C の値が、それぞれキーおよび値となって辞書に追加されます。

書式文字列に関するエラーが生じると、 SystemError 例外をセットして NULL を返します。

PyObject *Py_VaBuildValue(const char *format, va_list vargs)

Return value: New reference. Part of the Stable ABI.

Py_BuildValue() と同じですが、可変長引数の代わりに va_list を受け取ります。

文字列の変換と書式化

数値変換と、書式化文字列出力のための関数群。

int PyOS_snprintf(char *str, size_t size, const char *format, ...)

Part of the Stable ABI.

書式文字列 format と追加の引数から、 size バイトを超えない文字列を str に出力します。 Unix man page の snprintf(3) [https://manpages.debian.org/snprintf(3)] を参照してください。

int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)

Part of the Stable ABI.

書式文字列 format と可変長引数リスト va から、 size バイトを超えない文字列を str に出力します。 Unix man page の vsnprintf(3) [https://manpages.debian.org/vsnprintf(3)] を参照してください。

PyOS_snprintf() と PyOS_vsnprintf() は標準Cライブラリの snprintf() と vsnprintf() 関数をラップします。これらの関数の目的は、C標準ライブラリが保証していないコーナーケースでの動作を保証することです。

The wrappers ensure that str[size-1] is always '\0' upon return. They never write more than size bytes (including the trailing '\0') into str. Both functions require that str != NULL, size > 0, format != NULL and size < INT_MAX. Note that this means there is no equivalent to the C99 n = snprintf(NULL, 0, ...) which would determine the necessary buffer size.

これらの関数の戻り値 (以下では rv とします) は以下の意味を持ちます:

0 <= rv < size のとき、変換出力は成功して、(最後の str[rv] にある '\0' を除いて) rv 文字が str に出力された。

rv >= size のとき、変換出力は切り詰められており、成功するためには rv + 1 バイトが必要だったことを示します。str[size-1] は '\0' です。

rv < 0 のときは、何か悪いことが起こった時です。この場合でも str[size-1] は '\0' ですが、str のそれ以外の部分は未定義です。エラーの正確な原因はプラットフォーム依存です。

以下の関数は locale 非依存な文字列から数値への変換を行ないます。

unsigned long PyOS_strtoul(const char *str, char **ptr, int base)

Part of the Stable ABI.

Convert the initial part of the string in str to an unsigned long value according to the given base, which must be between 2 and 36 inclusive, or be the special value 0.

Leading white space and case of characters are ignored. If base is zero it looks for a leading 0b, 0o or 0x to tell which base. If these are absent it defaults to 10. Base must be 0 or between 2 and 36 (inclusive). If ptr is non-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 (errno is set to ERANGE) and ULONG_MAX is returned. If no conversion can be performed, 0 is returned.

See also the Unix man page strtoul(3) [https://manpages.debian.org/strtoul(3)].

Added in version 3.2.

long PyOS_strtol(const char *str, char **ptr, int base)

Part of the Stable ABI.

Convert the initial part of the string in str to an long value according to the given base, which must be between 2 and 36 inclusive, or be the special value 0.

Same as PyOS_strtoul(), but return a long value instead and LONG_MAX on overflows.

See also the Unix man page strtol(3) [https://manpages.debian.org/strtol(3)].

Added in version 3.2.

double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)

Part of the Stable ABI.

文字列 s を double に変換します。失敗したときは Python の例外を発生させます。受け入れられる文字列は、 Python の float() コンストラクタが受け付ける文字列に準拠しますが、 s の先頭と末尾に空白文字があってはならないという部分が異なります。この変換は現在のロケールに依存しません。

endptr が NULL の場合、変換は文字列全体に対して行われます。文字列が正しい浮動小数点数の表現になっていない場合は -1.0 を返して ValueError を発生させます。

endptr が NULL で無い場合、文字列を可能な範囲で変換して、*endptr に最初の変換されなかった文字へのポインタを格納します。文字列の先頭に正しい浮動小数点数の表現が無かった場合、*endptr を文字列の先頭に設定して、ValueError を発生させ、-1.0 を返します。

s が float に格納し切れないほど大きい値を表現していた場合、(例えば、"1e500" は多くのプラットフォームで表現できません) overflow_exception が NULL なら Py_HUGE_VAL に適切な符号を付けて返します。他の場合は overflow_exception は Python の例外オブジェクトへのポインタでなければならず、その例外を発生させて -1.0 を返します。どちらの場合でも、*endptr には変換された値の直後の最初の文字へのポインタが設定されます。

それ以外のエラーが変換中に発生した場合(例えば out-of-memory エラー)、適切な Python の例外を設定して -1.0 を返します。

Added in version 3.1.

char *PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)

Part of the Stable ABI.

double val を指定された format_code, precision, flags に基づいて文字列に変換します。

format_code は 'e', 'E', 'f', 'F', 'g', 'G', 'r' のどれかでなければなりません。 'r' の場合、 precision は 0 でなければならず、無視されます。 'r' フォーマットコードは標準の repr() フォーマットを指定しています。

flags は 0 か、 Py_DTSF_SIGN, Py_DTSF_ADD_DOT_0, Py_DTSF_ALT か、これらの or を取ったものです:

Py_DTSF_SIGN は、val が負で無いときも常に符号文字を先頭につけることを意味します。

Py_DTSF_ADD_DOT_0 は文字列が整数のように見えないことを保証します。

Py_DTSF_ALT は "alternate" フォーマットルールを適用することを意味します。詳細は PyOS_snprintf() の '#' 指定を参照してください。

ptype が NULL で無い場合、val が有限数、無限数、NaNのどれかに合わせて、Py_DTST_FINITE, Py_DTST_INFINITE, Py_DTST_NAN のいずれかに設定されます。

戻り値は変換後の文字列が格納された buffer へのポインタか、変換が失敗した場合は NULL です。呼び出し側は、返された文字列を PyMem_Free() を使って解放する責任があります。

Added in version 3.1.

int PyOS_stricmp(const char *s1, const char *s2)

Case insensitive comparison of strings. The function works almost identically to strcmp() except that it ignores the case.

int PyOS_strnicmp(const char *s1, const char *s2, Py_ssize_t size)

Case insensitive comparison of strings. The function works almost identically to strncmp() except that it ignores the case.

PyHash API

See also the PyTypeObject.tp_hash member.

type Py_hash_t

Hash value type: signed integer.

Added in version 3.2.

type Py_uhash_t

Hash value type: unsigned integer.

Added in version 3.2.

type PyHash_FuncDef

Hash function definition used by PyHash_GetFuncDef().

const char *name

Hash function name (UTF-8 encoded string).

const int hash_bits

Internal size of the hash value in bits.

const int seed_bits

Size of seed input in bits.

Added in version 3.4.

PyHash_FuncDef *PyHash_GetFuncDef(void)

Get the hash function definition.

参考

PEP 456 [https://peps.python.org/pep-0456/] "Secure and interchangeable hash algorithm".

Added in version 3.4.

リフレクション

PyObject *PyEval_GetBuiltins(void)

Return value: Borrowed reference. Part of the Stable ABI.

現在の実行フレーム内のビルトインの辞書か、もし実行中のフレームがなければスレッド状態のインタプリタのビルトイン辞書を返します。

PyObject *PyEval_GetLocals(void)

Return value: Borrowed reference. Part of the Stable ABI.

現在の実行フレーム内のローカル変数の辞書か、実行中のフレームがなければ NULL を返します。

PyObject *PyEval_GetGlobals(void)

Return value: Borrowed reference. Part of the Stable ABI.

現在の実行フレーム内のグローバル変数の辞書か、実行中のフレームがなければ NULL を返します。

PyFrameObject *PyEval_GetFrame(void)

Return value: Borrowed reference. Part of the Stable ABI.

現在のスレッド状態のフレームを返します。現在実行中のフレームがなければ NULL を返します。

See also PyThreadState_GetFrame().

const char *PyEval_GetFuncName(PyObject *func)

Part of the Stable ABI.

func が関数、クラス、インスタンスオブジェクトであればその名前を、そうでなければ func の型を返します。

const char *PyEval_GetFuncDesc(PyObject *func)

Part of the Stable ABI.

func の型に依存する、解説文字列(description string)を返します。戻り値は、関数とメソッドに対しては "()", " constructor", " instance", " object" です。 PyEval_GetFuncName() と連結された結果、 func の解説になります。

codec レジストリとサポート関数

int PyCodec_Register(PyObject *search_function)

Part of the Stable ABI.

新しい codec 検索関数を登録します。

As side effect, this tries to load the encodings package, if not yet done, to make sure that it is always first in the list of search functions.

int PyCodec_Unregister(PyObject *search_function)

Part of the Stable ABI since version 3.10.

Unregister a codec search function and clear the registry's cache. If the search function is not registered, do nothing. Return 0 on success. Raise an exception and return -1 on error.

Added in version 3.10.

int PyCodec_KnownEncoding(const char *encoding)

Part of the Stable ABI.

encoding のための登録された codec が存在するかどうかに応じて 1 か 0 を返します。この関数は常に成功します。

PyObject *PyCodec_Encode(PyObject *object, const char *encoding, const char *errors)

Return value: New reference. Part of the Stable ABI.

汎用の codec ベースの encode API.

encoding に応じて見つかったエンコーダ関数に対して object を渡します。エラーハンドリングメソッドは errors で指定します。 errors は NULL でもよく、その場合はその codec のデフォルトのメソッドが利用されます。エンコーダが見つからなかった場合は LookupError を発生させます。

PyObject *PyCodec_Decode(PyObject *object, const char *encoding, const char *errors)

Return value: New reference. Part of the Stable ABI.

汎用の codec ベースのデコード API.

encoding に応じて見つかったデコーダ関数に対して object を渡します。エラーハンドリングメソッドは errors で指定します。 errors は NULL でもよく、その場合はその codec のデフォルトのメソッドが利用されます。デコーダが見つからなかった場合は LookupError を発生させます。

コーデック検索API

次の関数では、文字列 encoding は全て小文字に変換することで、効率的に、大文字小文字を無視した検索をします。コーデックが見つからない場合、 KeyError を設定して NULL を返します。

PyObject *PyCodec_Encoder(const char *encoding)

Return value: New reference. Part of the Stable ABI.

与えられた encoding のエンコーダ関数を返します。

PyObject *PyCodec_Decoder(const char *encoding)

Return value: New reference. Part of the Stable ABI.

与えられた encoding のデコーダ関数を返します。

PyObject *PyCodec_IncrementalEncoder(const char *encoding, const char *errors)

Return value: New reference. Part of the Stable ABI.

与えられた encoding の IncrementalEncoder オブジェクトを返します。

PyObject *PyCodec_IncrementalDecoder(const char *encoding, const char *errors)

Return value: New reference. Part of the Stable ABI.

与えられた encoding の IncrementalDecoder オブジェクトを返します。

PyObject *PyCodec_StreamReader(const char *encoding, PyObject *stream, const char *errors)

Return value: New reference. Part of the Stable ABI.

与えられた encoding の StreamReader ファクトリ関数を返します。

PyObject *PyCodec_StreamWriter(const char *encoding, PyObject *stream, const char *errors)

Return value: New reference. Part of the Stable ABI.

与えられた encoding の StreamWriter ファクトリ関数を返します。

Unicode エラーハンドラ用レジストリ API

int PyCodec_RegisterError(const char *name, PyObject *error)

Part of the Stable ABI.

エラーハンドルのためのコールバック関数 error を name で登録します。このコールバック関数は、コーデックがエンコードできない文字/デコードできないバイトに遭遇した時に、そのエンコード/デコード関数の呼び出しで name が指定されていたら呼び出されます。

コールバックは1つの引数として、 UnicodeEncodeError, UnicodeDecodeError, UnicodeTranslateError のどれかのインスタンスを受け取ります。このインスタンスは問題のある文字列やバイト列に関する情報と、その元の文字列中のオフセットを持っています。(その情報を取得するための関数については Unicode 例外オブジェクト を参照してください。) コールバックは渡された例外を発生させるか、2要素のタプルに問題のシーケンスの代替と、 encode/decode を再開する元の文字列中のオフセットとなる整数を格納して返します。

成功したら 0 を、エラー時は -1 を返します。

PyObject *PyCodec_LookupError(const char *name)

Return value: New reference. Part of the Stable ABI.

name で登録されたエラーハンドリングコールバック関数を検索します。特別な場合として、NULL が渡された場合、"strict" のエラーハンドリングコールバック関数を返します。

PyObject *PyCodec_StrictErrors(PyObject *exc)

Return value: Always NULL. Part of the Stable ABI.

exc を例外として発生させます。

PyObject *PyCodec_IgnoreErrors(PyObject *exc)

Return value: New reference. Part of the Stable ABI.

unicode エラーを無視し、問題の入力をスキップします。

PyObject *PyCodec_ReplaceErrors(PyObject *exc)

Return value: New reference. Part of the Stable ABI.

unicode エラーを ? か U+FFFD で置き換えます。

PyObject *PyCodec_XMLCharRefReplaceErrors(PyObject *exc)

Return value: New reference. Part of the Stable ABI.

unicode encode エラーを XML文字参照で置き換えます。

PyObject *PyCodec_BackslashReplaceErrors(PyObject *exc)

Return value: New reference. Part of the Stable ABI.

unicode encode エラーをバックスラッシュエスケープ (\x, \u, \U) で置き換えます。

PyObject *PyCodec_NameReplaceErrors(PyObject *exc)

Return value: New reference. Part of the Stable ABI since version 3.7.

unicode encode エラーを \N{...} で置き換えます。

Added in version 3.5.

Support for Perf Maps

On supported platforms (as of this writing, only Linux), the runtime can take advantage of perf map files to make Python functions visible to an external profiling tool (such as perf [https://perf.wiki.kernel.org/index.php/Main_Page]). A running process may create a file in the /tmp directory, which contains entries that can map a section of executable code to a name. This interface is described in the documentation of the Linux Perf tool [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/perf/Documentation/jit-interface.txt].

In Python, these helper APIs can be used by libraries and features that rely on generating machine code on the fly.

Note that holding the Global Interpreter Lock (GIL) is not required for these APIs.

int PyUnstable_PerfMapState_Init(void)

これは Unstable API. It may change without warning in minor releases.

Open the /tmp/perf-$pid.map file, unless it's already opened, and create a lock to ensure thread-safe writes to the file (provided the writes are done through PyUnstable_WritePerfMapEntry()). Normally, there's no need to call this explicitly; just use PyUnstable_WritePerfMapEntry() and it will initialize the state on first call.

Returns 0 on success, -1 on failure to create/open the perf map file, or -2 on failure to create a lock. Check errno for more information about the cause of a failure.

int PyUnstable_WritePerfMapEntry(const void *code_addr, unsigned int code_size, const char *entry_name)

これは Unstable API. It may change without warning in minor releases.

Write one single entry to the /tmp/perf-$pid.map file. This function is thread safe. Here is what an example entry looks like:

# address      size  name
7f3529fcf759 b     py::bar:/run/t.py

Will call PyUnstable_PerfMapState_Init() before writing the entry, if the perf map file is not already opened. Returns 0 on success, or the same error codes as PyUnstable_PerfMapState_Init() on failure.

void PyUnstable_PerfMapState_Fini(void)

これは Unstable API. It may change without warning in minor releases.

Close the perf map file opened by PyUnstable_PerfMapState_Init(). This is called by the runtime itself during interpreter shut-down. In general, there shouldn't be a reason to explicitly call this, except to handle specific scenarios such as forking.

抽象オブジェクトレイヤ (Abstract Objects Layer)

この章で説明する関数は、オブジェクトの型に依存しないような Python オブジェクトの操作や、(数値型全て、シーケンス型全てといった) 大まかな型のオブジェクトに対する操作を行ないます。関数を適用対象でないオブジェクトに対して使った場合、Python の例外が送出されることになります。

これらの関数は、 PyList_New() で作成された後に NULL 以外の値を設定されていないリストのような、適切に初期化されていないオブジェクトに対して使うことはできません。

オブジェクトプロトコル (object protocol)

Call プロトコル

The tp_call Protocol

The Vectorcall Protocol

再帰の管理

Vectorcall Support API

Object Calling API

Call Support API

数値型プロトコル (number protocol)

シーケンス型プロトコル (sequence protocol)

マップ型プロトコル (mapping protocol)

イテレータプロトコル (iterator protocol)

バッファプロトコル (buffer Protocol)

buffer 構造体

バッファリクエストのタイプ

リクエストに依存しないフィールド

readonly, format

shape, strides, suboffsets

隣接性のリクエスト

複合リクエスト

複雑な配列

NumPy スタイル: shape, strides

PIL スタイル: shape, strides, suboffsets

バッファ関連の関数

古いバッファプロトコル

オブジェクトプロトコル (object protocol)

PyObject *Py_NotImplemented

与えられたオブジェクトとメソッドの引数の型の組み合わせの処理が未実装である印として使われる、 未実装 (NotImplemented) シングルトン。

Py_RETURN_NOTIMPLEMENTED

Properly handle returning Py_NotImplemented from within a C function (that is, create a new strong reference to NotImplemented and return it).

Py_PRINT_RAW

Flag to be used with multiple functions that print the object (like PyObject_Print() and PyFile_WriteObject()). If passed, these function would use the str() of the object instead of the repr().

int PyObject_Print(PyObject *o, FILE *fp, int flags)

Print an object o, on file fp. Returns -1 on error. The flags argument is used to enable certain printing options. The only option currently supported is Py_PRINT_RAW; if given, the str() of the object is written instead of the repr().

int PyObject_HasAttr(PyObject *o, PyObject *attr_name)

Part of the Stable ABI.

Returns 1 if o has the attribute attr_name, and 0 otherwise. This is equivalent to the Python expression hasattr(o, attr_name). This function always succeeds.

注釈

Exceptions that occur when this calls __getattr__() and __getattribute__() methods are silently ignored. For proper error handling, use PyObject_GetAttr() instead.

int PyObject_HasAttrString(PyObject *o, const char *attr_name)

Part of the Stable ABI.

This is the same as PyObject_HasAttr(), but attr_name is specified as a const char* UTF-8 encoded bytes string, rather than a PyObject*.

注釈

Exceptions that occur when this calls __getattr__() and __getattribute__() methods or while creating the temporary str object are silently ignored. For proper error handling, use PyObject_GetAttrString() instead.

PyObject *PyObject_GetAttr(PyObject *o, PyObject *attr_name)

Return value: New reference. Part of the Stable ABI.

オブジェクト o から、名前 attr_name の属性を取得します。成功すると属性値を返し失敗すると NULL を返します。この関数は Python の式 o.attr_name と同じです。

PyObject *PyObject_GetAttrString(PyObject *o, const char *attr_name)

Return value: New reference. Part of the Stable ABI.

This is the same as PyObject_GetAttr(), but attr_name is specified as a const char* UTF-8 encoded bytes string, rather than a PyObject*.

PyObject *PyObject_GenericGetAttr(PyObject *o, PyObject *name)

Return value: New reference. Part of the Stable ABI.

型オブジェクトの tp_getattro スロットに置かれる、属性を取得する総称的な関数です。この関数は、 (もし存在すれば) オブジェクトの属性 __dict__ に加え、オブジェクトの MRO にあるクラスの辞書にあるデスクリプタを探します。 デスクリプタ (descriptor) の実装 で概要が述べられている通り、データのデスクリプタはインスタンスの属性より優先され、非データデスクリプタは後回しにされます。見付からなかった場合は AttributeError を送出します。

int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)

Part of the Stable ABI.

オブジェクト o の attr_name という名の属性に、値 v を設定します。失敗すると例外を送出し -1 を返します; 成功すると 0 を返します。この関数は Python の式 o.attr_name = v と同じです。

v が NULL のとき、アトリビュートは削除されます。この動作は PyObject_DelAttr() のため、非推奨となっていますが、削除される予定はありません。

int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)

Part of the Stable ABI.

This is the same as PyObject_SetAttr(), but attr_name is specified as a const char* UTF-8 encoded bytes string, rather than a PyObject*.

v が NULL の場合は属性が削除されますが、この機能は非推奨であり PyObject_DelAttrString() を使うのが望ましいです。

int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)

Part of the Stable ABI.

属性の設定と削除を行う汎用的な関数で、型オブジェクトの tp_setattro スロットに置かれます。オブジェクトの MRO にあるクラスの辞書からデータディスクリプタを探し、見付かった場合はインスタンスの辞書にある属性の設定や削除よりも優先されます。そうでない場合は、(もし存在すれば) オブジェクトの __dict__ に属性を設定もしくは削除します。成功すると 0 が返され、そうでない場合は AttributeError が送出され -1 が返されます。

int PyObject_DelAttr(PyObject *o, PyObject *attr_name)

オブジェクト o の attr_name という名の属性を削除します。失敗すると -1 を返します。この関数は Python の文 del o.attr_name と同じです。

int PyObject_DelAttrString(PyObject *o, const char *attr_name)

This is the same as PyObject_DelAttr(), but attr_name is specified as a const char* UTF-8 encoded bytes string, rather than a PyObject*.

PyObject *PyObject_GenericGetDict(PyObject *o, void *context)

Return value: New reference. Part of the Stable ABI since version 3.10.

__dict__ デスクリプタの getter の総称的な実装です。必要な場合は、辞書を作成します。

This function may also be called to get the __dict__ of the object o. Pass NULL for context when calling it. Since this function may need to allocate memory for the dictionary, it may be more efficient to call PyObject_GetAttr() when accessing an attribute on the object.

On failure, returns NULL with an exception set.

Added in version 3.3.

int PyObject_GenericSetDict(PyObject *o, PyObject *value, void *context)

Part of the Stable ABI since version 3.7.

__dict__ デスクリプタの setter の総称的な実装です。この実装では辞書を削除することは許されていません。

Added in version 3.3.

PyObject **_PyObject_GetDictPtr(PyObject *obj)

Return a pointer to __dict__ of the object obj. If there is no __dict__, return NULL without setting an exception.

This function may need to allocate memory for the dictionary, so it may be more efficient to call PyObject_GetAttr() when accessing an attribute on the object.

PyObject *PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)

Return value: New reference. Part of the Stable ABI.

Compare the values of o1 and o2 using the operation specified by opid, which must be one of Py_LT, Py_LE, Py_EQ, Py_NE, Py_GT, or Py_GE, corresponding to <, <=, ==, !=, >, or >= respectively. This is the equivalent of the Python expression o1 op o2, where op is the operator corresponding to opid. Returns the value of the comparison on success, or NULL on failure.

int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)

Part of the Stable ABI.

Compare the values of o1 and o2 using the operation specified by opid, like PyObject_RichCompare(), but returns -1 on error, 0 if the result is false, 1 otherwise.

注釈

If o1 and o2 are the same object, PyObject_RichCompareBool() will always return 1 for Py_EQ and 0 for Py_NE.

PyObject *PyObject_Format(PyObject *obj, PyObject *format_spec)

Part of the Stable ABI.

Format obj using format_spec. This is equivalent to the Python expression format(obj, format_spec).

format_spec may be NULL. In this case the call is equivalent to format(obj). Returns the formatted string on success, NULL on failure.

PyObject *PyObject_Repr(PyObject *o)

Return value: New reference. Part of the Stable ABI.

オブジェクト o の文字列表現を計算します。成功すると文字列表現を返し、失敗すると NULL を返します。 Python 式 repr(o) と同じです。この関数は組み込み関数 repr() の処理で呼び出されます。

バージョン 3.4 で変更: アクティブな例外を黙って捨てないことを保証するのに便利なように、この関数はデバッグアサーションを含むようになりました。

PyObject *PyObject_ASCII(PyObject *o)

Return value: New reference. Part of the Stable ABI.

PyObject_Repr() と同様、オブジェクト o の文字列表現を計算しますが、 PyObject_Repr() によって返された文字列に含まれる非 ASCII 文字を、エスケープ文字 \x 、 \u 、 \U でエスケープします。この関数は Pythoh 2 の PyObject_Repr() が返す文字列と同じ文字列を生成します。 ascii() によって呼び出されます。

PyObject *PyObject_Str(PyObject *o)

Return value: New reference. Part of the Stable ABI.

オブジェクト o の文字列表現を計算します。成功すると文字列表現を返し、失敗すると NULL を返します。 Python 式 str(o) と同じです。この関数は組み込み関数 str() や、 print() 関数の処理で呼び出されます。

バージョン 3.4 で変更: アクティブな例外を黙って捨てないことを保証するのに便利なように、この関数はデバッグアサーションを含むようになりました。

PyObject *PyObject_Bytes(PyObject *o)

Return value: New reference. Part of the Stable ABI.

オブジェクト o のバイト列表現を計算します。失敗すると NULL を返し、成功すると bytes オブジェクトを返します。 o が整数でないときの、 Python 式 bytes(o) と同じです。 bytes(o) と違って、 o が整数のときには、ゼロで初期化された bytes オブジェクトを返すのではなく TypeError が送出されます。

int PyObject_IsSubclass(PyObject *derived, PyObject *cls)

Part of the Stable ABI.

クラス derived がクラス cls と同一であるか、そこから派生したクラスである場合は 1 を返し、そうでない場合は 0 を返します。エラーが起きた場合は -1 を返します。

cls がタプルの場合、 cls の全ての要素に対してチェックします。少なくとも1つのチェックで 1 が返ったとき、結果は 1 となり、それ以外のとき 0 になります。

cls に __subclasscheck__() メソッドがある場合は、子クラスの状態が PEP 3119 [https://peps.python.org/pep-3119/] にある通りかどうかを判定するために呼ばれます。そうでないとき derived が cls の子クラスになるのは、直接的あるいは間接的な子クラスである場合、つまり cls.__mro__ に含まれる場合です。

Normally only class objects, i.e. instances of type or a derived class, are considered classes. However, objects can override this by having a __bases__ attribute (which must be a tuple of base classes).

int PyObject_IsInstance(PyObject *inst, PyObject *cls)

Part of the Stable ABI.

inst がクラス cls もしくは cls の子クラスのインスタンスである場合に 1 を返し、そうでない場合に 0 を返します。エラーが起きると -1 を返し例外を設定します。

cls がタプルの場合、 cls の全ての要素に対してチェックします。少なくとも1つのチェックで 1 が返ったとき、結果は 1 となり、それ以外のとき 0 になります。

cls に __instancecheck__() メソッドがある場合は、子クラスの状態が PEP 3119 [https://peps.python.org/pep-3119/] にある通りかどうかを判定するために呼ばれます。そうでないとき inst が cls のインスタンスになるのは、そのクラスが cls の子クラスである場合です。

An instance inst can override what is considered its class by having a __class__ attribute.

An object cls can override if it is considered a class, and what its base classes are, by having a __bases__ attribute (which must be a tuple of base classes).

Py_hash_t PyObject_Hash(PyObject *o)

Part of the Stable ABI.

オブジェクト o のハッシュ値を計算して返します。失敗すると -1 を返します。 Python の式 hash(o) と同じです。

バージョン 3.2 で変更: 返り値の型が Py_hash_t になりました。この型は、 Py_ssize_t と同じサイズをもつ符号付き整数です。

Py_hash_t PyObject_HashNotImplemented(PyObject *o)

Part of the Stable ABI.

Set a TypeError indicating that type(o) is not hashable and return -1. This function receives special treatment when stored in a tp_hash slot, allowing a type to explicitly indicate to the interpreter that it is not hashable.

int PyObject_IsTrue(PyObject *o)

Part of the Stable ABI.

o が真を表すとみなせる場合には 1 を、そうでないときには 0 を返します。 Python の式 not not o と同じです。失敗すると -1 を返します。

int PyObject_Not(PyObject *o)

Part of the Stable ABI.

o が真を表すとみなせる場合には 0 を、そうでないときには 1 を返します。 Python の式 not o と同じです。失敗すると -1 を返します。

PyObject *PyObject_Type(PyObject *o)

Return value: New reference. Part of the Stable ABI.

When o is non-NULL, returns a type object corresponding to the object type of object o. On failure, raises SystemError and returns NULL. This is equivalent to the Python expression type(o). This function creates a new strong reference to the return value. There's really no reason to use this function instead of the Py_TYPE() function, which returns a pointer of type PyTypeObject*, except when a new strong reference is needed.

int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)

Return non-zero if the object o is of type type or a subtype of type, and 0 otherwise. Both parameters must be non-NULL.

Py_ssize_t PyObject_Size(PyObject *o)

Py_ssize_t PyObject_Length(PyObject *o)

Part of the Stable ABI.

o の長さを返します。ただしオブジェクト o がシーケンス型プロトコルとマップ型プロトコルの両方を提供している場合、シーケンスとしての長さを返します。エラーが生じると -1 を返します。 Python の式 len(o) と同じです。

Py_ssize_t PyObject_LengthHint(PyObject *o, Py_ssize_t defaultvalue)

オブジェクト o の概算の長さを返します。最初に実際の長さを、次に __length_hint__() を使って概算の長さを、そして最後にデフォルトの値を返そうとします。この関数は Python の式 operator.length_hint(o, defaultvalue) と同じです。

Added in version 3.4.

PyObject *PyObject_GetItem(PyObject *o, PyObject *key)

Return value: New reference. Part of the Stable ABI.

オブジェクト key に対応する o の要素を返します。失敗すると NULL を返します。Python の式 o[key] と同じです。

int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)

Part of the Stable ABI.

オブジェクト key を値 v に対応付けます。失敗すると、例外を送出し -1 を返します。成功すると 0 を返します。これは Python の文 o[key] = v と同等です。この関数は v への参照を 盗み取りません 。

int PyObject_DelItem(PyObject *o, PyObject *key)

Part of the Stable ABI.

オブジェクト o から key に関する対応付けを削除します。失敗すると -1 を返します。Python の文 del o[key] と同じです。

PyObject *PyObject_Dir(PyObject *o)

Return value: New reference. Part of the Stable ABI.

この関数は Python の式 dir(o) と同じで、オブジェクトの変数名に割り当てている文字列からなるリスト (空の場合もあります) を返します。エラーの場合には NULL を返します。引数を NULL にすると、Python における dir() と同様に、現在のローカルな名前を返します; この場合、アクティブな実行フレームがなければ NULL を返しますが、 PyErr_Occurred() は偽を返します。

PyObject *PyObject_GetIter(PyObject *o)

Return value: New reference. Part of the Stable ABI.

Python の式 iter(o) と同じです。引数にとったオブジェクトに対する新たなイテレータか、オブジェクトがすでにイテレータの場合にはオブジェクト自身を返します。オブジェクトが反復処理不可能であった場合には TypeError を送出して NULL を返します。

PyObject *PyObject_GetAIter(PyObject *o)

Return value: New reference. Part of the Stable ABI since version 3.10.

This is the equivalent to the Python expression aiter(o). Takes an AsyncIterable object and returns an AsyncIterator for it. This is typically a new iterator but if the argument is an AsyncIterator, this returns itself. Raises TypeError and returns NULL if the object cannot be iterated.

Added in version 3.10.

void *PyObject_GetTypeData(PyObject *o, PyTypeObject *cls)

Part of the Stable ABI since version 3.12.

Get a pointer to subclass-specific data reserved for cls.

The object o must be an instance of cls, and cls must have been created using negative PyType_Spec.basicsize. Python does not check this.

On error, set an exception and return NULL.

Added in version 3.12.

Py_ssize_t PyType_GetTypeDataSize(PyTypeObject *cls)

Part of the Stable ABI since version 3.12.

Return the size of the instance memory space reserved for cls, i.e. the size of the memory PyObject_GetTypeData() returns.

This may be larger than requested using -PyType_Spec.basicsize; it is safe to use this larger size (e.g. with memset()).

The type cls must have been created using negative PyType_Spec.basicsize. Python does not check this.

On error, set an exception and return a negative value.

Added in version 3.12.

void *PyObject_GetItemData(PyObject *o)

Get a pointer to per-item data for a class with Py_TPFLAGS_ITEMS_AT_END.

On error, set an exception and return NULL. TypeError is raised if o does not have Py_TPFLAGS_ITEMS_AT_END set.

Added in version 3.12.

Call プロトコル

CPython supports two different calling protocols: tp_call and vectorcall.

The tp_call Protocol

Instances of classes that set tp_call are callable. The signature of the slot is:

PyObject *tp_call(PyObject *callable, PyObject *args, PyObject *kwargs);

A call is made using a tuple for the positional arguments and a dict for the keyword arguments, similarly to callable(*args, **kwargs) in Python code. args must be non-NULL (use an empty tuple if there are no arguments) but kwargs may be NULL if there are no keyword arguments.

This convention is not only used by tp_call: tp_new and tp_init also pass arguments this way.

To call an object, use PyObject_Call() or another call API.

The Vectorcall Protocol

Added in version 3.9.

The vectorcall protocol was introduced in PEP 590 [https://peps.python.org/pep-0590/] as an additional protocol for making calls more efficient.

As rule of thumb, CPython will prefer the vectorcall for internal calls if the callable supports it. However, this is not a hard rule. Additionally, some third-party extensions use tp_call directly (rather than using PyObject_Call()). Therefore, a class supporting vectorcall must also implement tp_call. Moreover, the callable must behave the same regardless of which protocol is used. The recommended way to achieve this is by setting tp_call to PyVectorcall_Call(). This bears repeating:

警告

A class supporting vectorcall must also implement tp_call with the same semantics.

バージョン 3.12 で変更: The Py_TPFLAGS_HAVE_VECTORCALL flag is now removed from a class when the class's __call__() method is reassigned. (This internally sets tp_call only, and thus may make it behave differently than the vectorcall function.) In earlier Python versions, vectorcall should only be used with immutable or static types.

A class should not implement vectorcall if that would be slower than tp_call. For example, if the callee needs to convert the arguments to an args tuple and kwargs dict anyway, then there is no point in implementing vectorcall.

Classes can implement the vectorcall protocol by enabling the Py_TPFLAGS_HAVE_VECTORCALL flag and setting tp_vectorcall_offset to the offset inside the object structure where a vectorcallfunc appears. This is a pointer to a function with the following signature:

typedef PyObject *(*vectorcallfunc)(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)

Part of the Stable ABI since version 3.12.

callable is the object being called.

args is a C array consisting of the positional arguments followed by the

values of the keyword arguments. This can be NULL if there are no arguments.

nargsf is the number of positional arguments plus possibly the

PY_VECTORCALL_ARGUMENTS_OFFSET flag. To get the actual number of positional arguments from nargsf, use PyVectorcall_NARGS().

kwnames is a tuple containing the names of the keyword arguments;

in other words, the keys of the kwargs dict. These names must be strings (instances of str or a subclass) and they must be unique. If there are no keyword arguments, then kwnames can instead be NULL.

PY_VECTORCALL_ARGUMENTS_OFFSET

Part of the Stable ABI since version 3.12.

If this flag is set in a vectorcall nargsf argument, the callee is allowed to temporarily change args[-1]. In other words, args points to argument 1 (not 0) in the allocated vector. The callee must restore the value of args[-1] before returning.

For PyObject_VectorcallMethod(), this flag means instead that args[0] may be changed.

Whenever they can do so cheaply (without additional allocation), callers are encouraged to use PY_VECTORCALL_ARGUMENTS_OFFSET. Doing so will allow callables such as bound methods to make their onward calls (which include a prepended self argument) very efficiently.

Added in version 3.8.

To call an object that implements vectorcall, use a call API function as with any other callable. PyObject_Vectorcall() will usually be most efficient.

注釈

In CPython 3.8, the vectorcall API and related functions were available provisionally under names with a leading underscore: _PyObject_Vectorcall, _Py_TPFLAGS_HAVE_VECTORCALL, _PyObject_VectorcallMethod, _PyVectorcall_Function, _PyObject_CallOneArg, _PyObject_CallMethodNoArgs, _PyObject_CallMethodOneArg. Additionally, PyObject_VectorcallDict was available as _PyObject_FastCallDict. The old names are still defined as aliases of the new, non-underscored names.

再帰の管理

When using tp_call, callees do not need to worry about recursion: CPython uses Py_EnterRecursiveCall() and Py_LeaveRecursiveCall() for calls made using tp_call.

For efficiency, this is not the case for calls done using vectorcall: the callee should use Py_EnterRecursiveCall and Py_LeaveRecursiveCall if needed.

Vectorcall Support API

Py_ssize_t PyVectorcall_NARGS(size_t nargsf)

Part of the Stable ABI since version 3.12.

Given a vectorcall nargsf argument, return the actual number of arguments. Currently equivalent to:

(Py_ssize_t)(nargsf & ~PY_VECTORCALL_ARGUMENTS_OFFSET)

However, the function PyVectorcall_NARGS should be used to allow for future extensions.

Added in version 3.8.

vectorcallfunc PyVectorcall_Function(PyObject *op)

If op does not support the vectorcall protocol (either because the type does not or because the specific instance does not), return NULL. Otherwise, return the vectorcall function pointer stored in op. This function never raises an exception.

This is mostly useful to check whether or not op supports vectorcall, which can be done by checking PyVectorcall_Function(op) != NULL.

Added in version 3.9.

PyObject *PyVectorcall_Call(PyObject *callable, PyObject *tuple, PyObject *dict)

Part of the Stable ABI since version 3.12.

Call callable's vectorcallfunc with positional and keyword arguments given in a tuple and dict, respectively.

This is a specialized function, intended to be put in the tp_call slot or be used in an implementation of tp_call. It does not check the Py_TPFLAGS_HAVE_VECTORCALL flag and it does not fall back to tp_call.

Added in version 3.8.

Object Calling API

Various functions are available for calling a Python object. Each converts its arguments to a convention supported by the called object – either tp_call or vectorcall. In order to do as little conversion as possible, pick one that best fits the format of data you have available.

The following table summarizes the available functions; please see individual documentation for details.

関数

callable

args

kwargs

PyObject_Call()

PyObject *

tuple

dict/NULL

PyObject_CallNoArgs()

PyObject *

---

---

PyObject_CallOneArg()

PyObject *

1 object

---

PyObject_CallObject()

PyObject *

tuple/NULL

---

PyObject_CallFunction()

PyObject *

format

---

PyObject_CallMethod()

obj + char*

format

---

PyObject_CallFunctionObjArgs()

PyObject *

variadic

---

PyObject_CallMethodObjArgs()

obj + name

variadic

---

PyObject_CallMethodNoArgs()

obj + name

---

---

PyObject_CallMethodOneArg()

obj + name

1 object

---

PyObject_Vectorcall()

PyObject *

vectorcall

vectorcall

PyObject_VectorcallDict()

PyObject *

vectorcall

dict/NULL

PyObject_VectorcallMethod()

arg + name

vectorcall

vectorcall

PyObject *PyObject_Call(PyObject *callable, PyObject *args, PyObject *kwargs)

Return value: New reference. Part of the Stable ABI.

呼び出し可能な Python のオブジェクト callable を、タプル args として与えられる引数と辞書 kwargs として与えられる名前付き引数とともに呼び出します。

args は NULL であってはならず、引数を必要としない場合は空のタプルを使ってください。 kwargs は NULL でも構いません。

成功したら呼び出しの結果を返し、失敗したら例外を送出し NULL を返します。

これは次の Python の式と同等です: callable(*args, **kwargs) 。

PyObject *PyObject_CallNoArgs(PyObject *callable)

Return value: New reference. Part of the Stable ABI since version 3.10.

Call a callable Python object callable without any arguments. It is the most efficient way to call a callable Python object without any argument.

成功したら呼び出しの結果を返し、失敗したら例外を送出し NULL を返します。

Added in version 3.9.

PyObject *PyObject_CallOneArg(PyObject *callable, PyObject *arg)

Return value: New reference.

Call a callable Python object callable with exactly 1 positional argument arg and no keyword arguments.

成功したら呼び出しの結果を返し、失敗したら例外を送出し NULL を返します。

Added in version 3.9.

PyObject *PyObject_CallObject(PyObject *callable, PyObject *args)

Return value: New reference. Part of the Stable ABI.

呼び出し可能な Python のオブジェクト callable を、タプル args として与えられる引数とともに呼び出します。引数が必要な場合は、 args は NULL で構いません。

成功したら呼び出しの結果を返し、失敗したら例外を送出し NULL を返します。

これは次の Python の式と同等です: callable(*args) 。

PyObject *PyObject_CallFunction(PyObject *callable, const char *format, ...)

Return value: New reference. Part of the Stable ABI.

呼び出し可能な Python オブジェクト callable を可変数個の C 引数とともに呼び出します。 C 引数は Py_BuildValue() 形式のフォーマット文字列を使って記述します。 format は NULL かもしれず、与える引数がないことを表します。

成功したら呼び出しの結果を返し、失敗したら例外を送出し NULL を返します。

これは次の Python の式と同等です: callable(*args) 。

PyObject* args だけを引数に渡す場合は、 PyObject_CallFunctionObjArgs() がより速い方法であることを覚えておいてください。

バージョン 3.4 で変更: format の型が char * から変更されました。

PyObject *PyObject_CallMethod(PyObject *obj, const char *name, const char *format, ...)

Return value: New reference. Part of the Stable ABI.

オブジェクト obj の name という名前のメソッドを、いくつかの C 引数とともに呼び出します。 C 引数はタプルを生成する Py_BuildValue() 形式のフォーマット文字列で記述されています。

format は NULL でもよく、引数が与えられないことを表します。

成功したら呼び出しの結果を返し、失敗したら例外を送出し NULL を返します。

これは次の Python の式と同等です: obj.name(arg1, arg2, ...) 。

PyObject* args だけを引数に渡す場合は、 PyObject_CallMethodObjArgs() がより速い方法であることを覚えておいてください。

バージョン 3.4 で変更: name と format の型が char * から変更されました。

PyObject *PyObject_CallFunctionObjArgs(PyObject *callable, ...)

Return value: New reference. Part of the Stable ABI.

呼び出し可能な Python オブジェクト callable を可変数個の PyObject* 引数とともに呼び出します。引数列は末尾に NULL がついた可変数個のパラメタとして与えます。

成功したら呼び出しの結果を返し、失敗したら例外を送出し NULL を返します。

これは次の Python の式と同等です: callable(arg1, arg2, ...) 。

PyObject *PyObject_CallMethodObjArgs(PyObject *obj, PyObject *name, ...)

Return value: New reference. Part of the Stable ABI.

Python オブジェクト obj のメソッドを呼び出します、メソッド名は Python 文字列オブジェクト name で与えます。可変数個の PyObject* 引数と共に呼び出されます. 引数列は末尾に NULL がついた可変数個のパラメタとして与えます。

成功したら呼び出しの結果を返し、失敗したら例外を送出し NULL を返します。

PyObject *PyObject_CallMethodNoArgs(PyObject *obj, PyObject *name)

Call a method of the Python object obj without arguments, where the name of the method is given as a Python string object in name.

成功したら呼び出しの結果を返し、失敗したら例外を送出し NULL を返します。

Added in version 3.9.

PyObject *PyObject_CallMethodOneArg(PyObject *obj, PyObject *name, PyObject *arg)

Call a method of the Python object obj with a single positional argument arg, where the name of the method is given as a Python string object in name.

成功したら呼び出しの結果を返し、失敗したら例外を送出し NULL を返します。

Added in version 3.9.

PyObject *PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)

Part of the Stable ABI since version 3.12.

Call a callable Python object callable. The arguments are the same as for vectorcallfunc. If callable supports vectorcall, this directly calls the vectorcall function stored in callable.

成功したら呼び出しの結果を返し、失敗したら例外を送出し NULL を返します。

Added in version 3.9.

PyObject *PyObject_VectorcallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict)

Call callable with positional arguments passed exactly as in the vectorcall protocol, but with keyword arguments passed as a dictionary kwdict. The args array contains only the positional arguments.

Regardless of which protocol is used internally, a conversion of arguments needs to be done. Therefore, this function should only be used if the caller already has a dictionary ready to use for the keyword arguments, but not a tuple for the positional arguments.

Added in version 3.9.

PyObject *PyObject_VectorcallMethod(PyObject *name, PyObject *const *args, size_t nargsf, PyObject *kwnames)

Part of the Stable ABI since version 3.12.

Call a method using the vectorcall calling convention. The name of the method is given as a Python string name. The object whose method is called is args[0], and the args array starting at args[1] represents the arguments of the call. There must be at least one positional argument. nargsf is the number of positional arguments including args[0], plus PY_VECTORCALL_ARGUMENTS_OFFSET if the value of args[0] may temporarily be changed. Keyword arguments can be passed just like in PyObject_Vectorcall().

If the object has the Py_TPFLAGS_METHOD_DESCRIPTOR feature, this will call the unbound method object with the full args vector as arguments.

成功したら呼び出しの結果を返し、失敗したら例外を送出し NULL を返します。

Added in version 3.9.

Call Support API

int PyCallable_Check(PyObject *o)

Part of the Stable ABI.

オブジェクト o が呼び出し可能オブジェクトかどうか調べます。オブジェクトが呼び出し可能であるときに 1 を返し、そうでないときには 0 を返します。この関数呼び出しは常に成功します。

数値型プロトコル (number protocol)

int PyNumber_Check(PyObject *o)

Part of the Stable ABI.

オブジェクト o が数値型プロトコルを提供している場合に 1 を返し、そうでないときには偽を返します。この関数呼び出しは常に成功します。

バージョン 3.8 で変更: o がインデックス整数だった場合、 1 を返します。

PyObject *PyNumber_Add(PyObject *o1, PyObject *o2)

Return value: New reference. Part of the Stable ABI.

成功すると o1 と o2 を加算した結果を返し、失敗すると NULL を返します。Python の式 o1 + o2 と同じです。

PyObject *PyNumber_Subtract(PyObject *o1, PyObject *o2)

Return value: New reference. Part of the Stable ABI.

成功すると o1 から o2 を減算した結果を返し、失敗すると NULL を返します。Python の式 o1 - o2 と同じです。

PyObject *PyNumber_Multiply(PyObject *o1, PyObject *o2)

Return value: New reference. Part of the Stable ABI.

成功すると o1 と o2 を乗算した結果を返し、失敗すると NULL を返します。Python の式 o1 * o2 と同じです。

PyObject *PyNumber_MatrixMultiply(PyObject *o1, PyObject *o2)

Return value: New reference. Part of the Stable ABI since version 3.7.

成功すると o1 と o2 を行列乗算した結果を返し、失敗すると NULL を返します。 Python の式 o1 @ o2 と同じです。

Added in version 3.5.

PyObject *PyNumber_FloorDivide(PyObject *o1, PyObject *o2)

Return value: New reference. Part of the Stable ABI.

Return the floor of o1 divided by o2, or NULL on failure. This is the equivalent of the Python expression o1 // o2.

PyObject *PyNumber_TrueDivide(PyObject *o1, PyObject *o2)

Return value: New reference. Part of the Stable ABI.

成功すると、数学的な o1 の o2 による除算値に対する妥当な近似 (reasonable approximation) を返し、失敗すると NULL を返します。全ての実数を 2 を基数として表現するのは不可能なため、二進の浮動小数点数は "近似値" しか表現できません。このため、戻り値も近似になります。この関数に二つの整数を渡した際、浮動小数点の値を返すことがあります。Python の式 o1 / o2 と同じです。

PyObject *PyNumber_Remainder(PyObject *o1, PyObject *o2)

Return value: New reference. Part of the Stable ABI.

成功すると o1 を o2 で除算した剰余を返し、失敗すると NULL を返します。Python の式 o1 % o2 と同じです。

PyObject *PyNumber_Divmod(PyObject *o1, PyObject *o2)

Return value: New reference. Part of the Stable ABI.

組み込み関数 divmod() を参照してください。失敗すると NULL を返します。 Python の式 divmod(o1, o2) と同じです。

PyObject *PyNumber_Power(PyObject *o1, PyObject *o2, PyObject *o3)

Return value: New reference. Part of the Stable ABI.

組み込み関数 pow() を参照してください。失敗すると NULL を返します。 Python の式 pow(o1, o2, o3) と同じです。 o3 はオプションです。 o3 を無視させたいなら、 Py_None を入れてください (o3 に NULL を渡すと、不正なメモリアクセスを引き起こすことがあります)。

PyObject *PyNumber_Negative(PyObject *o)

Return value: New reference. Part of the Stable ABI.

成功すると o の符号反転を返し、失敗すると NULL を返します。Python の式 -o と同じです。

PyObject *PyNumber_Positive(PyObject *o)

Return value: New reference. Part of the Stable ABI.

成功すると o を返し、失敗すると NULL を返します。Python の式 +o と同じです。

PyObject *PyNumber_Absolute(PyObject *o)

Return value: New reference. Part of the Stable ABI.

成功すると o の絶対値を返し、失敗すると NULL を返します。Python の式 abs(o) と同じです。

PyObject *PyNumber_Invert(PyObject *o)

Return value: New reference. Part of the Stable ABI.

成功すると o のビット単位反転 (bitwise negation) を返し、失敗すると NULL を返します。Python の式 ~o と同じです。

PyObject *PyNumber_Lshift(PyObject *o1, PyObject *o2)

Return value: New reference. Part of the Stable ABI.

成功すると o1 を o2 だけ左シフトした結果を返し、失敗すると NULL を返します。Python の式 o1 << o2 と同じです。

PyObject *PyNumber_Rshift(PyObject *o1, PyObject *o2)

Return value: New reference. Part of the Stable ABI.

成功すると o1 を o2 だけ右シフトした結果を返し、失敗すると NULL を返します。Python の式 o1 >> o2 と同じです。

PyObject *PyNumber_And(PyObject *o1, PyObject *o2)

Return value: New reference. Part of the Stable ABI.

成功すると o1 と o2 の "ビット単位論理積 (bitwise and)" を返し、失敗すると NULL を返します。Python の式 o1 & o2 と同じです。

PyObject *PyNumber_Xor(PyObject *o1, PyObject *o2)

Return value: New reference. Part of the Stable ABI.

成功すると o1 と o2 の "ビット単位排他的論理和 (bitwise exclusive or)" を返し、失敗すると NULL を返します。Python の式 o1 ^ o2 と同じです。

PyObject *PyNumber_Or(PyObject *o1, PyObject *o2)

Return value: New reference. Part of the Stable ABI.

成功すると o1 と o2 の "ビット単位論理和 (bitwise or)" を返し失敗すると NULL を返します。Python の式 o1 | o2 と同じです。

PyObject *PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2)

Return value: New reference. Part of the Stable ABI.

成功すると o1 と o2 を加算した結果を返し、失敗すると NULL を返します。o1 が in-place 演算をサポートする場合、in-place 演算を行います。Python の文 o1 += o2 と同じです。

PyObject *PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2)

Return value: New reference. Part of the Stable ABI.

成功すると o1 から o2 を減算した結果を返し、失敗すると NULL を返します。o1 が in-place 演算をサポートする場合、in-place 演算を行います。Python の文 o1 -= o2 と同じです。

PyObject *PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2)

Return value: New reference. Part of the Stable ABI.

成功すると o1 と o2 を乗算した結果を返し、失敗すると NULL を返します。o1 が in-place 演算をサポートする場合、in-place 演算を行います。Python の文 o1 *= o2 と同じです。

PyObject *PyNumber_InPlaceMatrixMultiply(PyObject *o1, PyObject *o2)

Return value: New reference. Part of the Stable ABI since version 3.7.

成功すると o1 と o2 を行列乗算した結果を返し、失敗すると NULL を返します。 o1 が in-place 演算をサポートする場合、 in-place 演算を行います。 Python の文 o1 @= o2 と同じです。

Added in version 3.5.

PyObject *PyNumber_InPlaceFloorDivide(PyObject *o1, PyObject *o2)

Return value: New reference. Part of the Stable ABI.

成功すると o1 を o2 で除算した切捨て値を返し、失敗すると NULL を返します。o1 が in-place 演算をサポートする場合、in-place 演算を行います。Python の文 o1 //= o2 と同じです。

PyObject *PyNumber_InPlaceTrueDivide(PyObject *o1, PyObject *o2)

Return value: New reference. Part of the Stable ABI.

成功すると、数学的な o1 の o2 による除算値に対する妥当な近似 (reasonable approximation) を返し、失敗すると NULL を返します。全ての実数を 2 を基数として表現するのは不可能なため、二進の浮動小数点数は "近似値" しか表現できません。このため、戻り値も近似になります。この関数に二つの整数を渡した際、浮動小数点の値を返すことがあります。o1 が in-place 演算をサポートする場合、in-place 演算を行います。Python の文 o1 /= o2 と同じです。

PyObject *PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2)

Return value: New reference. Part of the Stable ABI.

成功すると o1 を o2 で除算した剰余を返し、, 失敗すると NULL を返します。o1 が in-place 演算をサポートする場合、in-place 演算を行います。Python の文 o1 %= o2 と同じです。

PyObject *PyNumber_InPlacePower(PyObject *o1, PyObject *o2, PyObject *o3)

Return value: New reference. Part of the Stable ABI.

組み込み関数 pow() を参照してください。失敗すると NULL を返します。 o1 が in-place 演算をサポートする場合、in-place 演算を行います。この関数は o3 が Py_None の場合は Python 文 o1 **= o2 と同じで、それ以外の場合は pow(o1, o2, o3) の in-place 版です。 o3 を無視させたいなら、 Py_None を入れてください (o3 に NULL を渡すと、不正なメモリアクセスを引き起こすことがあります)。

PyObject *PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2)

Return value: New reference. Part of the Stable ABI.

成功すると o1 を o2 だけ左シフトした結果を返し、失敗すると NULL を返します。o1 が in-place 演算をサポートする場合、in-place 演算を行います。Python の文 o1 <<= o2 と同じです。

PyObject *PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2)

Return value: New reference. Part of the Stable ABI.

成功すると o1 を o2 だけ右シフトした結果を返し、失敗すると NULL を返します。o1 が in-place 演算をサポートする場合、in-place 演算を行います。Python の文 o1 >>= o2 と同じです。

PyObject *PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2)

Return value: New reference. Part of the Stable ABI.

成功すると o1 と o2 の "ビット単位論理積 (bitwise and)" を返し、失敗すると NULL を返します。o1 が in-place 演算をサポートする場合、in-place 演算を行います。Python の文 o1 &= o2 と同じです。

PyObject *PyNumber_InPlaceXor(PyObject *o1, PyObject *o2)

Return value: New reference. Part of the Stable ABI.

成功すると o1 と o2 の "ビット単位排他的論理和 (bitwise exclusive or)" を返し、失敗すると NULL を返します。o1 が in-place 演算をサポートする場合、in-place 演算を行います。Python の文 o1 ^= o2 と同じです。

PyObject *PyNumber_InPlaceOr(PyObject *o1, PyObject *o2)

Return value: New reference. Part of the Stable ABI.

成功すると o1 と o2 の "ビット単位論理和 (bitwise or)" を返し失敗すると NULL を返します。o1 が in-place 演算をサポートする場合、in-place 演算を行います。Python の文 o1 |= o2 と同じです。

PyObject *PyNumber_Long(PyObject *o)

Return value: New reference. Part of the Stable ABI.

成功すると o を整数に変換したものを返し、失敗すると NULL を返します。Python の式 int(o) と同じです。

PyObject *PyNumber_Float(PyObject *o)

Return value: New reference. Part of the Stable ABI.

成功すると o を浮動小数点数に変換したものを返し、失敗すると NULL を返します。Python の式 float(o) と同じです。

PyObject *PyNumber_Index(PyObject *o)

Return value: New reference. Part of the Stable ABI.

o をPythonのint型に変換し、成功したらその値を返します。失敗したら NULL が返され、 TypeError 例外が送出されます。

バージョン 3.10 で変更: 結果は常に厳密な int 型です。以前は、結果は int のサブクラスのインスタンスのこともありました。

PyObject *PyNumber_ToBase(PyObject *n, int base)

Return value: New reference. Part of the Stable ABI.

base 進数に変換された整数 n を文字列として返します。 base 引数は2, 8, 10または16のいずれかでなければなりません。 基数2、8、16について、返される文字列の先頭には基数マーカー '0b' 、 '0o' または '0x' が、それぞれ付与されます。 もし n が Python のint型でなければ、まず PyNumber_Index() で変換されます。

Py_ssize_t PyNumber_AsSsize_t(PyObject *o, PyObject *exc)

Part of the Stable ABI.

o を整数として解釈可能だった場合、Py_ssize_t 型の値に変換して返します。呼び出しが失敗したら、例外が送出され、 -1 が返されます。

もし o がPythonのintに変換できたのに、Py_ssize_t への変換が OverflowError になる場合は、 exc 引数で渡された型 (普通は IndexError か OverflowError) の例外を送出します。もし、 exc が NULL なら、例外はクリアされて、値が負の場合は PY_SSIZE_T_MIN へ、正の場合は PY_SSIZE_T_MAX へと制限されます。

int PyIndex_Check(PyObject *o)

Part of the Stable ABI since version 3.8.

o がインデックス整数である場合 (tp_as_number 構造体の nb_index スロットが埋まっている場合) に 1 を返し、そうでない場合に 0 を返します。この関数は常に成功します。

シーケンス型プロトコル (sequence protocol)

int PySequence_Check(PyObject *o)

Part of the Stable ABI.

Return 1 if the object provides the sequence protocol, and 0 otherwise. Note that it returns 1 for Python classes with a __getitem__() method, unless they are dict subclasses, since in general it is impossible to determine what type of keys the class supports. This function always succeeds.

Py_ssize_t PySequence_Size(PyObject *o)

Py_ssize_t PySequence_Length(PyObject *o)

Part of the Stable ABI.

成功するとシーケンス o 中のオブジェクトの数を返し、失敗すると -1 を返します。これは、Python の式 len(o) と同じになります。

PyObject *PySequence_Concat(PyObject *o1, PyObject *o2)

Return value: New reference. Part of the Stable ABI.

成功すると o1 と o2 の連結 (concatenation) を返し、失敗すると NULL を返します。Python の式 o1 + o2 と同じです。

PyObject *PySequence_Repeat(PyObject *o, Py_ssize_t count)

Return value: New reference. Part of the Stable ABI.

成功するとオブジェクト o の count 回繰り返しを返し、失敗すると NULL を返します。Python の式 o * count と同じです。

PyObject *PySequence_InPlaceConcat(PyObject *o1, PyObject *o2)

Return value: New reference. Part of the Stable ABI.

成功すると o1 と o2 の連結 (concatenation) を返し、失敗すると NULL を返します。o1 が in-place 演算をサポートする場合、in-place 演算を行います。Python の式 o1 += o2 と同じです。

PyObject *PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count)

Return value: New reference. Part of the Stable ABI.

成功するとオブジェクト o の count 回繰り返しを返し、失敗すると NULL を返します。o が in-place 演算をサポートする場合、in-place 演算を行います。Python の式 o *= count と同じです。

PyObject *PySequence_GetItem(PyObject *o, Py_ssize_t i)

Return value: New reference. Part of the Stable ABI.

成功すると o の i 番目の要素を返し、失敗すると NULL を返します。Python の式 o[i] と同じです。

PyObject *PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)

Return value: New reference. Part of the Stable ABI.

成功すると o の i1 から i2 までの間のスライスを返し、失敗すると NULL を返します。Python の式 o[i1:i2] と同じです。

int PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v)

Part of the Stable ABI.

o の i 番目の要素に v を代入します。失敗すると、例外を送出し -1 を返します; 成功すると 0 を返します。これは Python の文 o[i] = v と同じです。この関数は v への参照を 盗み取りません 。

v が NULL の場合はその要素が削除されますが、この機能は非推奨であり、 PyObject_DelAttr() を使うのが望ましいです。

int PySequence_DelItem(PyObject *o, Py_ssize_t i)

Part of the Stable ABI.

o の i 番目の要素を削除します。失敗すると -1 を返します。Python の文 del o[i] と同じです。

int PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2, PyObject *v)

Part of the Stable ABI.

o の i1 から i2 までの間のスライスに v を代入します。Python の文 o[i1:i2] = v と同じです。

int PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)

Part of the Stable ABI.

シーケンスオブジェクト o の i1 から i2 までの間のスライスを削除します。失敗すると -1 を返します。Python の文 del o[i1:i2] と同じです。

Py_ssize_t PySequence_Count(PyObject *o, PyObject *value)

Part of the Stable ABI.

o における value の出現回数、すなわち o[key] == value となる key の個数を返します。失敗すると -1 を返します。Python の式 o.count(value) と同じです。

int PySequence_Contains(PyObject *o, PyObject *value)

Part of the Stable ABI.

o に value が入っているか判定します。o のある要素が value と等価 (equal) ならば 1 を返し、それ以外の場合には 0 を返します。エラーが発生すると -1 を返します。Python の式 value in o と同じです。

Py_ssize_t PySequence_Index(PyObject *o, PyObject *value)

Part of the Stable ABI.

o[i] == value となる最初に見つかったインデクス i を返します。エラーが発生すると -1 を返します。Python の式 o.index(value) と同じです。

PyObject *PySequence_List(PyObject *o)

Return value: New reference. Part of the Stable ABI.

シーケンスもしくはイテラブル o と同じ内容を持つリストオブジェクトを返します。失敗したら NULL を返します。返されるリストは新しく作られたことが保証されています。これは Python の式 list(o) と同等です。

PyObject *PySequence_Tuple(PyObject *o)

Return value: New reference. Part of the Stable ABI.

シーケンスあるいはイテラブルである o と同じ内容を持つタプルオブジェクトを返します。失敗したら NULL を返します。o がタプルの場合、新たな参照を返します。それ以外の場合、適切な内容が入ったタプルを構築して返します。 Pythonの式 tuple(o) と同等です。

PyObject *PySequence_Fast(PyObject *o, const char *m)

Return value: New reference. Part of the Stable ABI.

シーケンスまたはイテラブルの o を PySequence_Fast* ファミリの関数で利用できるオブジェクトとして返します。オブジェクトがシーケンスでもイテラブルでもない場合は、メッセージ m を持つ、 TypeError を送出します。失敗したら NULL を返します。

PySequence_Fast* ファミリの関数は、o が PyTupleObject または PyListObject と仮定し、o のデータフィールドに直接アクセスするため、そのように名付けられています。

CPythonの実装では、もし o が 既にシーケンスかタプルであれば、o そのものを返します。

Py_ssize_t PySequence_Fast_GET_SIZE(PyObject *o)

o が NULL でなく、 PySequence_Fast() が返したオブジェクトであると仮定して、 o の長さを返します。 o のサイズは PySequence_Size() を呼び出しても得られますが、 PySequence_Fast_GET_SIZE() の方が o をリストかタプルであると仮定して処理するため、より高速です。

PyObject *PySequence_Fast_GET_ITEM(PyObject *o, Py_ssize_t i)

Return value: Borrowed reference.

o が NULL でなく、 PySequence_Fast() が返したオブジェクトであり、かつ i がインデクスの範囲内にあると仮定して、 o の i 番目の要素を返します。

PyObject **PySequence_Fast_ITEMS(PyObject *o)

PyObject ポインタの背後にあるアレイを返します。この関数では、 o は PySequence_Fast() の返したオブジェクトであり、 NULL でないものと仮定しています。

リストのサイズが変更されるとき、メモリ再確保が要素の配列を再配置するかもしれないことに注意してください。そのため、シーケンスの変更が発生しないコンテキストでのみ背後にあるポインタを使ってください。

PyObject *PySequence_ITEM(PyObject *o, Py_ssize_t i)

Return value: New reference.

o の i 番目の要素を返し、失敗すると NULL を返します。 PySequence_GetItem() の高速版であり、PySequence_Check() で o が真を返すかどうかの検証や、負の添え字の調整を行いません。

マップ型プロトコル (mapping protocol)

PyObject_GetItem(), PyObject_SetItem(), PyObject_DelItem() も参照してください。

int PyMapping_Check(PyObject *o)

Part of the Stable ABI.

Return 1 if the object provides the mapping protocol or supports slicing, and 0 otherwise. Note that it returns 1 for Python classes with a __getitem__() method, since in general it is impossible to determine what type of keys the class supports. This function always succeeds.

Py_ssize_t PyMapping_Size(PyObject *o)

Py_ssize_t PyMapping_Length(PyObject *o)

Part of the Stable ABI.

成功するとオブジェクト o 中のキーの数を返し、失敗すると -1 を返します。これは、Python の式 len(o) と同じになります。

PyObject *PyMapping_GetItemString(PyObject *o, const char *key)

Return value: New reference. Part of the Stable ABI.

This is the same as PyObject_GetItem(), but key is specified as a const char* UTF-8 encoded bytes string, rather than a PyObject*.

int PyMapping_SetItemString(PyObject *o, const char *key, PyObject *v)

Part of the Stable ABI.

This is the same as PyObject_SetItem(), but key is specified as a const char* UTF-8 encoded bytes string, rather than a PyObject*.

int PyMapping_DelItem(PyObject *o, PyObject *key)

This is an alias of PyObject_DelItem().

int PyMapping_DelItemString(PyObject *o, const char *key)

This is the same as PyObject_DelItem(), but key is specified as a const char* UTF-8 encoded bytes string, rather than a PyObject*.

int PyMapping_HasKey(PyObject *o, PyObject *key)

Part of the Stable ABI.

マップ型オブジェクトがキー key を持つ場合に 1 を返し、そうでないときには 0 を返します。これは、Python の式 key in o と等価です。この関数呼び出しは常に成功します。

注釈

Exceptions which occur when this calls __getitem__() method are silently ignored. For proper error handling, use PyObject_GetItem() instead.

int PyMapping_HasKeyString(PyObject *o, const char *key)

Part of the Stable ABI.

This is the same as PyMapping_HasKey(), but key is specified as a const char* UTF-8 encoded bytes string, rather than a PyObject*.

注釈

Exceptions that occur when this calls __getitem__() method or while creating the temporary str object are silently ignored. For proper error handling, use PyMapping_GetItemString() instead.

PyObject *PyMapping_Keys(PyObject *o)

Return value: New reference. Part of the Stable ABI.

成功するとオブジェクト o のキーからなるリストを返します。失敗すると NULL を返します。

バージョン 3.7 で変更: 以前は、関数はリストもしくはタプルを返していました。

PyObject *PyMapping_Values(PyObject *o)

Return value: New reference. Part of the Stable ABI.

成功するとオブジェクト o の値からなるリストを返します。失敗すると NULL を返します。

バージョン 3.7 で変更: 以前は、関数はリストもしくはタプルを返していました。

PyObject *PyMapping_Items(PyObject *o)

Return value: New reference. Part of the Stable ABI.

成功するとオブジェクト o の要素からなるリストを返し、各要素はキーと値のペアが入ったタプルになっています。失敗すると NULL を返します。

バージョン 3.7 で変更: 以前は、関数はリストもしくはタプルを返していました。

イテレータプロトコル (iterator protocol)

イテレータを扱うための固有の関数は二つあります。

int PyIter_Check(PyObject *o)

Part of the Stable ABI since version 3.8.

Return non-zero if the object o can be safely passed to PyIter_Next(), and 0 otherwise. This function always succeeds.

int PyAIter_Check(PyObject *o)

Part of the Stable ABI since version 3.10.

Return non-zero if the object o provides the AsyncIterator protocol, and 0 otherwise. This function always succeeds.

Added in version 3.10.

PyObject *PyIter_Next(PyObject *o)

Return value: New reference. Part of the Stable ABI.

Return the next value from the iterator o. The object must be an iterator according to PyIter_Check() (it is up to the caller to check this). If there are no remaining values, returns NULL with no exception set. If an error occurs while retrieving the item, returns NULL and passes along the exception.

イテレータの返す要素にわたって反復処理を行うループを書くと、C のコードは以下のようになるはずです:

PyObject *iterator = PyObject_GetIter(obj);
PyObject *item;

if (iterator == NULL) {
    /* propagate error */
}

while ((item = PyIter_Next(iterator))) {
    /* do something with item */
    ...
    /* release reference when done */
    Py_DECREF(item);
}

Py_DECREF(iterator);

if (PyErr_Occurred()) {
    /* propagate error */
}
else {
    /* continue doing useful work */
}

type PySendResult

The enum value used to represent different results of PyIter_Send().

Added in version 3.10.

PySendResult PyIter_Send(PyObject *iter, PyObject *arg, PyObject **presult)

Part of the Stable ABI since version 3.10.

Sends the arg value into the iterator iter. Returns:

PYGEN_RETURN if iterator returns. Return value is returned via presult.

PYGEN_NEXT if iterator yields. Yielded value is returned via presult.

PYGEN_ERROR if iterator has raised and exception. presult is set to NULL.

Added in version 3.10.

バッファプロトコル (buffer Protocol)

Pythonで利用可能ないくつかのオブジェクトは、下層にあるメモリ配列または buffer へのアクセスを提供します。このようなオブジェクトとして、組み込みの bytes や bytearray 、 array.array のようないくつかの拡張型が挙げられます。サードバーティのライブラリは画像処理や数値解析のような特別な目的のために、それら自身の型を定義することができます。

それぞれの型はそれ自身のセマンティクスを持ちますが、おそらく大きなメモリバッファからなるという共通の特徴を共有します。いくつかの状況では仲介するコピーを行うことなく直接バッファにアクセスすることが望まれます。

Pythonは buffer protocol の形式で C レベルの仕組みを提供します。このプロトコルには二つの側面があります:

提供する側では、ある型は、そのオブジェクトの下層にあるバッファに関する情報を提供できる "buffer インターフェース" をエクスポートすることができます。このインターフェースは バッファオブジェクト構造体 (buffer object structure) の節で説明します。

利用する側では、オブジェクトの下層にある生データへのポインタを得るいくつかの手段が利用できます（たとえばメソッド引数）。

bytes や bytearray などのシンプルなオブジェクトは、内部のバッファーをバイト列の形式で公開します。バイト列以外の形式も利用可能です。例えば、 array.array が公開する要素はマルチバイト値になることがあります。

bufferインターフェースの利用者の一例は、ファイルオブジェクトの write() メソッドです: bufferインターフェースを通して一連のバイト列を提供できるどんなオブジェクトでもファイルに書き込むことができます。 write() は、その引数として渡されたオブジェクトの内部要素に対する読み出し専用アクセスのみを必要としますが、 readinto() のような他のメソッドでは、その引数の内容に対する書き込みアクセスが必要です。bufferインターフェースにより、オブジェクトは読み書き両方、読み出し専用バッファへのアクセスを許可するかそれとも拒否するか選択することができます。

bufferインターフェースの利用者には、対象となるオブジェクトのバッファを得る二つの方法があります:

正しい引数で PyObject_GetBuffer() を呼び出す;

PyArg_ParseTuple() (またはその同族のひとつ) を y* 、 w* または s* format codes のいずれかとともに呼び出す。

どちらのケースでも、bufferが必要なくなった時に PyBuffer_Release() を呼び出さなければなりません。これを怠ると、リソースリークのような様々な問題につながる恐れがあります。

buffer 構造体

バッファ構造体（または単純に "buffers"）は別のオブジェクトのバイナリデータをPythonプログラマに提供するのに便利です。これはまた、ゼロコピースライシング機構としても使用できます。このメモリブロックを参照する機能を使うことで、どんなデータでもとても簡単にPythonプログラマに提供することができます。メモリは、C 拡張の大きな配列定数かもしれませんし、オペレーティングシステムライブラリに渡す前のメモリブロックかもしれませんし、構造化データをネイティブのインメモリ形式受け渡すのに使用されるかもしれません。

Pythonインタプリタによって提供される多くのデータ型とは異なり、バッファは PyObject ポインタではなく、シンプルなC 構造体です。そのため、作成とコピーが非常に簡単に行えます。バッファの一般的なラッパーが必要なときは、 memoryview オブジェクトが作成されます。

エクスポートされるオブジェクトを書く方法の短い説明には、 Buffer Object Structures を参照してください。バッファを取得するには、 PyObject_GetBuffer() を参照してください。

type Py_buffer

Part of the Stable ABI (including all members) since version 3.11.

void *buf

バッファフィールドが表している論理構造の先頭を指すポインタ。バッファを提供するオブジェクトの下層物理メモリブロック中のどの位置にもなりえます。例えば strides が負だと、この値はメモリブロックの末尾かもしれません。

連続 配列の場合この値はメモリブロックの先頭を指します。

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 NULL by PyBuffer_Release(). The field is the equivalent of the return value of any standard C-API function.

PyMemoryView_FromBuffer() または PyBuffer_FillInfo() によってラップされた 一時的な バッファである特別なケースでは、このフィールドは NULL です。一般的に、エクスポートオブジェクトはこの方式を使用してはなりません。

Py_ssize_t len

product(shape) * itemsize。contiguous配列では、下層のメモリブロックの長さになります。非contiguous 配列では、contiguous表現にコピーされた場合に論理構造がもつ長さです。

((char *)buf)[0] から ((char *)buf)[len-1] の範囲へのアクセスは、連続性 (contiguity) を保証するリクエストによって取得されたバッファに対してのみ許されます。多くの場合に、そのようなリクエストは PyBUF_SIMPLE または PyBUF_WRITABLE です。

int readonly

バッファが読み出し専用であるか示します。このフィールドは PyBUF_WRITABLE フラグで制御できます。

Py_ssize_t itemsize

要素一つ分のbyte単位のサイズ。 struct.calcsize() を非 NULL の format 値に対して呼び出した結果と同じです。

重要な例外: 消費者が PyBUF_FORMAT フラグを設定することなくバッファを要求した場合、 format は NULL に設定されます。しかし itemsize は元のフォーマットに従った値を保持します。

shape が存在する場合、 product(shape) * itemsize == len の等式が守られ、利用者は itemsize を buffer を読むために利用できます。

PyBUF_SIMPLE または PyBUF_WRITABLE で要求した結果、 shape が NULL であれば、消費者は itemsize を無視して itemsize == 1 と見なさなければなりません。

const char *format

要素一つ分の内容を指定する、 struct モジュールスタイル文法の、 NUL 終端文字列。 このポインタの値が NULL なら、 "B" (符号無しバイト) として扱われます。

このフィールドは PyBUF_FORMAT フラグによって制御されます。

int ndim

The number of dimensions the memory represents as an n-dimensional array. If it is 0, buf points to a single item representing a scalar. In this case, shape, strides and suboffsets MUST be NULL. The maximum number of dimensions is given by PyBUF_MAX_NDIM.

Py_ssize_t *shape

メモリ上のN次元配列の形を示す、長さが ndim である Py_ssize_t の配列です。 shape[0] * ... * shape[ndim-1] * itemsize は len と等しくなければなりません。

shape の値は shape[n] >= 0 に制限されます。 shape[n] == 0 の場合に特に注意が必要です。詳細は complex arrays を参照してください。

shepe (形状) 配列は利用者からは読み出し専用です。

Py_ssize_t *strides

各次元において新しい値を得るためにスキップするバイト数を示す、長さ ndim の Py_ssize_t の配列。

ストライド値は、任意の整数を指定できます。規定の配列では、ストライドは通常でいけば有効です。しかし利用者は、strides[n] <= 0 のケースを処理することができる必要があります。詳細については complex arrays を参照してください。

消費者にとって、この strides 配列は読み出し専用です。

Py_ssize_t *suboffsets

Py_ssize_t 型の要素を持つ長さ ndim の配列。 suboffsets[n] >= 0 の場合は、 n 番目の次元に沿って保存されている値はポインタで、 suboffset 値は各ポインタの参照を解決した後に何バイト加えればいいかを示しています。 suboffset の値が負の数の場合は、ポインタの参照解決は不要 (連続したメモリブロック内に直接配置されいる) ということになります。

全ての suboffset が負数の場合 (つまり参照解決が不要) な場合、このフィールドは NULL (デフォルト値) でなければなりません。

この種の配列表現は Python Imaging Library (PIL) で使われています。このような配列で要素にアクセスする方法についてさらに詳しことは complex arrays を参照してください。

消費者にとって、suboffsets 配列は読み出し専用です。

void *internal

バッファを提供する側のオブジェクトが内部的に利用するための変数です。例えば、提供側はこの変数に整数型をキャストして、shape, strides, suboffsets といった配列をバッファを開放するときに同時に解放するべきかどうかを管理するフラグに使うことができるでしょう。バッファを受け取る側は、この値を決して変更してはなりません。

Constants:

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 PyBUF_MAX_NDIM dimensions. Currently set to 64.

バッファリクエストのタイプ

バッファは通常、 PyObject_GetBuffer() を使うことで、エクスポートするオブジェクトにバッファリクエストを送ることで得られます。メモリの論理的な構造の複雑性は多岐にわたるため、消費者は flags 引数を使って、自身が扱えるバッファの種類を指定します。

All Py_buffer fields are unambiguously defined by the request type.

リクエストに依存しないフィールド

下記のフィールドは flags の影響を受けずに、常に正しい値で設定されます。: obj, buf, len, itemsize, ndim.

readonly, format

PyBUF_WRITABLE

readonly フィールドを制御します。もしこのフラグが設定されている場合、exporter は、書き込み可能なバッファを提供するか、さもなければ失敗を報告しなければなりません。フラグが設定されていない場合、exporterは、読み出し専用と書き込み可能なバッファのどちらを提供しても構いませんが、どちらで提供するかどうかは全ての消費者に対して一貫性がなければなりません。

PyBUF_FORMAT

format フィールドを制御します。もしフラグが設定されていれば、このフィールドを正しく埋めなければなりません。フラグが設定されていなければ、このフィールドを NULL に設定しなければなりません。

PyBUF_WRITABLE は、次の節に出てくるどのフラグとも | を取ってかまいません。 PyBUF_SIMPLE は 0 と定義されているので、 PyBUF_WRITABLE は単純な書き込み可能なバッファを要求する単独のフラグとして使えます。

PyBUF_FORMAT は、PyBUF_SIMPLE 以外のどのフラグとも | を取ってかまいません。後者のフラグは B (符号なしバイト) フォーマットを既に指示しています。

shape, strides, suboffsets

このフラグは、以下で複雑性が大きい順に並べたメモリの論理的な構造を制御します。個々のフラグは、それより下に記載されたフラグのすべてのビットを含むことに注意してください。

リクエスト

shape

strides

suboffsets

PyBUF_INDIRECT

yes

yes

必要な場合

PyBUF_STRIDES

yes

yes

NULL

PyBUF_ND

yes

NULL

NULL

PyBUF_SIMPLE

NULL

NULL

NULL

隣接性のリクエスト

ストライドの情報があってもなくても、C または Fortran の 連続性 が明確に要求される可能性があります。ストライド情報なしに、バッファーは C と隣接している必要があります。

リクエスト

shape

strides

suboffsets

contig

PyBUF_C_CONTIGUOUS

yes

yes

NULL

C

PyBUF_F_CONTIGUOUS

yes

yes

NULL

F

PyBUF_ANY_CONTIGUOUS

yes

yes

NULL

C か F

PyBUF_ND

yes

NULL

NULL

C

複合リクエスト

有り得る全てのリクエストの値は、前の節でのフラグの組み合わせで網羅的に定義されています。便利なように、バッファープロトコルでは頻繁に使用される組み合わせを単一のフラグとして提供してます。

次のテーブルの U は連続性が未定義であることを表します。利用者は PyBuffer_IsContiguous() を呼び出して連続性を判定する必要があるでしょう。

リクエスト

shape

strides

suboffsets

contig

readonly

format

PyBUF_FULL

yes

yes

必要な場合

U

0

yes

PyBUF_FULL_RO

yes

yes

必要な場合

U

1 か 0

yes

PyBUF_RECORDS

yes

yes

NULL

U

0

yes

PyBUF_RECORDS_RO

yes

yes

NULL

U

1 か 0

yes

PyBUF_STRIDED

yes

yes

NULL

U

0

NULL

PyBUF_STRIDED_RO

yes

yes

NULL

U

1 か 0

NULL

PyBUF_CONTIG

yes

NULL

NULL

C

0

NULL

PyBUF_CONTIG_RO

yes

NULL

NULL

C

1 か 0

NULL

複雑な配列

NumPy スタイル: shape, strides

NumPy スタイルの配列の論理的構造は itemsize, ndim, shape, strides で定義されます。

ndim == 0 の場合は、 buf が指すメモリの場所は、サイズが itemsize のスカラ値として解釈されます。この場合、 shape と strides の両方とも NULL です。

strides が NULL の場合は、配列は標準の n 次元 C 配列として解釈されます。そうでない場合は、利用者は次のように n 次元配列にアクセスしなければなりません:

ptr = (char *)buf + indices[0] * strides[0] + ... + indices[n-1] * strides[n-1];
item = *((typeof(item) *)ptr);

上記のように、 buf はメモリブロック内のどの場所でも指すことが可能です。エクスポーターはこの関数を使用することによってバッファの妥当性を確認出来ます。

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

PIL スタイル: shape, strides, suboffsets

PIL スタイルの配列では通常の要素の他に、ある次元の上で次の要素を取得するために辿るポインタを持てます。例えば、通常の3次元 C 配列 char v[2][2][3] は、2次元配列への 2 つのポインタからなる配列 char (*v[2])[2][3] と見ることもできます。 suboffset 表現では、これらの 2 つのポインタは buf の先頭に埋め込め、メモリのどこにでも配置できる 2 つの char x[2][3] 配列を指します。

次の例は、 strides も suboffsets も NULL でない場合の、N 次元インデックスによって指されている N 次元配列内の要素へのポインタを返す関数です:

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;
}

バッファ関連の関数

int PyObject_CheckBuffer(PyObject *obj)

Part of the Stable ABI since version 3.11.

obj がbuffer インターフェースをサポートしている場合は 1 を返し、そうでない場合は 0 を返します。 1 を返したとしても、 PyObject_GetBuffer() が成功することは保証されません。この関数は常に成功します。

int PyObject_GetBuffer(PyObject *exporter, Py_buffer *view, int flags)

Part of the Stable ABI since version 3.11.

Send a request to exporter to fill in view as specified by flags. If the exporter cannot provide a buffer of the exact type, it MUST raise BufferError, set view->obj to NULL and return -1.

成功したときは、 view を埋め、 view->obj に exporter への新しい参照を設定し、0を返します。チェイン状のバッファプロバイダがリクエストを単一のオブジェクトにリダイレクトするケースでは、 view->obj は exporter の代わりにこのオブジェクトを参照します (バッファオブジェクト構造体 を参照してください)。

malloc() と free() のように、呼び出しに成功した PyObject_GetBuffer() と対になる PyBuffer_Release() の呼び出しがなけれなればなりません。従って、バッファの利用が済んだら PyBuffer_Release() が厳密に1回だけ呼び出されなければなりません。

void PyBuffer_Release(Py_buffer *view)

Part of the Stable ABI since version 3.11.

Release the buffer view and release the strong reference (i.e. decrement the reference count) to the view's supporting object, view->obj. This function MUST be called when the buffer is no longer being used, otherwise reference leaks may occur.

PyObject_GetBuffer() を通して取得していないバッファに対してこの関数を呼び出すのは間違いです。

Py_ssize_t PyBuffer_SizeFromFormat(const char *format)

Part of the Stable ABI since version 3.11.

Return the implied itemsize from format. On error, raise an exception and return -1.

Added in version 3.9.

int PyBuffer_IsContiguous(const Py_buffer *view, char order)

Part of the Stable ABI since version 3.11.

view で定義されているメモリが、 C スタイル (order == 'C') のときか、 Fortran スタイル (order == 'F') 連続 のときか、そのいずれか (order == 'A') であれば 1 を返します。それ以外の場合は 0 を返します。この関数は常に成功します。

void *PyBuffer_GetPointer(const Py_buffer *view, const Py_ssize_t *indices)

Part of the Stable ABI since version 3.11.

与えられた view 内にある indices が指すメモリ領域を取得します。 indices は view->ndim 個のインデックスからなる配列を指していなければなりません。

int PyBuffer_FromContiguous(const Py_buffer *view, const void *buf, Py_ssize_t len, char fort)

Part of the Stable ABI since version 3.11.

連続する len バイトを buf から view にコピーします。fort には 'C' か 'F' を指定できます（それぞれC言語スタイルとFortranスタイルの順序を表します)。成功時には 0、エラー時には -1 を返します。

int PyBuffer_ToContiguous(void *buf, const Py_buffer *src, Py_ssize_t len, char order)

Part of the Stable ABI since version 3.11.

src から len バイトを連続表現で buf 上にコピーします。 order は 'C' または 'F' または 'A' (C スタイル順序または Fortran スタイル順序またはそれ以外) が指定できます。成功したら 0 が返り、エラーなら -1 が返ります。

len != src->len の場合、この関数は失敗します。

int PyObject_CopyData(PyObject *dest, PyObject *src)

Part of the Stable ABI since version 3.11.

Copy data from src to dest buffer. Can convert between C-style and or Fortran-style buffers.

成功したら 0 が、エラー時には -1 が返されます。

void PyBuffer_FillContiguousStrides(int ndims, Py_ssize_t *shape, Py_ssize_t *strides, int itemsize, char order)

Part of the Stable ABI since version 3.11.

strides 配列を、 itemsize の大きさの要素がバイト単位の、 shape の形をした 連続な (order が 'C' なら C-style 、 'F' なら Fortran-style の) 多次元配列として埋める。

int PyBuffer_FillInfo(Py_buffer *view, PyObject *exporter, void *buf, Py_ssize_t len, int readonly, int flags)

Part of the Stable ABI since version 3.11.

サイズが len の buf を readonly に従った書き込み可/不可の設定で公開するバッファリクエストを処理します。 buf は符号無しバイトの列として解釈されます。

flags 引数はリクエストのタイプを示します。この関数は、 buf が読み出し専用と指定されていて、 flags に PyBUF_WRITABLE が設定されていない限り、常にフラグに指定された通りに view を埋めます。

On success, set view->obj to a new reference to exporter and return 0. Otherwise, raise BufferError, set view->obj to NULL and return -1;

この関数を getbufferproc の一部として使う場合には、 exporter はエクスポートするオブジェクトに設定しなければならず、さらに flags は変更せずに渡さなければなりません。そうでない場合は、 exporter は NULL でなければなりません。

古いバッファプロトコル

バージョン 3.0 で非推奨.

これらの関数は、 Python 2 の「古いバッファプロトコル」 API の一部です。 Python 3 では、もうこのプロトコルは存在しませんが、 2.x のコードを移植しやすいように関数は公開されています。 新しいバッファプロトコル と互換性のあるラッパー関数のように振る舞いますが、バッファがエクスポートされるときに取得されるリソースの生存期間を管理することはできません。

従って、あるオブジェクトのバッファビューを取得するために、 PyObject_GetBuffer() (もしくは y* および w* フォーマットコード で PyArg_ParseTuple() やその仲間) を呼び出し、バッファビューを解放するときには PyBuffer_Release() を呼び出します。

int PyObject_AsCharBuffer(PyObject *obj, const char **buffer, Py_ssize_t *buffer_len)

Part of the Stable ABI.

文字ベースの入力として使える読み出し専用メモリ上の位置へのポインタを返します。 obj 引数は単一セグメントからなる文字バッファインターフェースをサポートしていなければなりません。成功すると 0 を返し、 buffer をメモリの位置に、 buffer_len をバッファの長さに設定します。エラーの際には -1 を返し、 TypeError をセットします。

int PyObject_AsReadBuffer(PyObject *obj, const void **buffer, Py_ssize_t *buffer_len)

Part of the Stable ABI.

任意のデータを収めた読み出し専用のメモリ上の位置へのポインタを返します。 obj 引数は単一セグメントからなる読み出し可能バッファインターフェースをサポートしていなければなりません。成功すると 0 を返し、 buffer をメモリの位置に、 buffer_len をバッファの長さに設定します。エラーの際には -1 を返し、 TypeError をセットします。

int PyObject_CheckReadBuffer(PyObject *o)

Part of the Stable ABI.

o が単一セグメントからなる読み出し可能バッファインターフェースをサポートしている場合に 1 を返します。それ以外の場合には 0 を返します。この関数は常に成功します。

この関数は試しにバッファの取得と解放を行い、それぞれ対応する関数の呼び出し中に起こる例外は抑制されることに注意してください。エラーを報告させるには、 PyObject_GetBuffer() を代わりに使ってください。

int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len)

Part of the Stable ABI.

書き込み可能なメモリ上の位置へのポインタを返します。 obj 引数は単一セグメントからなる文字バッファインターフェースをサポートしていなければなりません。成功すると 0 を返し、 buffer をメモリの位置に、 buffer_len をバッファの長さに設定します。エラーの際には -1 を返し、 TypeError をセットします。

具象オブジェクト (concrete object) レイヤ

この章では、特定の Python オブジェクト型固有の関数について述べています。これらの関数に間違った型のオブジェクトを渡すのは良い考えではありません; Python プログラムから何らかのオブジェクトを受け取ったとき、そのオブジェクトが正しい型になっているか確信をもてないのなら、まず型チェックを行わなければなりません; 例えば、あるオブジェクトが辞書型か調べるには、 PyDict_Check() を使います。この章は Python のオブジェクト型における "家計図" に従って構成されています。

警告

この章で述べている関数は、渡されたオブジェクトの型を注意深くチェックしはするものの、多くの関数は渡されたオブジェクトが有効な NULL なのか有効なオブジェクトなのかをチェックしません。これらの関数に NULL を渡させてしまうと、関数はメモリアクセス違反を起こして、インタプリタを即座に終了させてしまうはずです。

基本オブジェクト (fundamental object)

この節では、Python の型オブジェクトとシングルトン(singleton)オブジェクト None について述べます。

型オブジェクト

Creating Heap-Allocated Types

None オブジェクト

数値型オブジェクト (numeric object)

整数型オブジェクト (integer object)

Boolean オブジェクト

浮動小数点型オブジェクト (floating point object)

Pack and Unpack functions

Pack functions

Unpack functions

複素数オブジェクト

C 構造体としての複素数

Python オブジェクトとしての複素数型

シーケンスオブジェクト (sequence object)

シーケンスオブジェクトに対する一般的な操作については前の章ですでに述べました; この節では、Python 言語にもともと備わっている特定のシーケンスオブジェクトについて扱います。

バイトオブジェクト

bytearray オブジェクト

型チェックマクロ

ダイレクト API 関数

マクロ

Unicode オブジェクトと codec

Unicode オブジェクト

Unicode 型

Unicode 文字プロパティ

Unicode 文字列の生成とアクセス

ロケールエンコーディング

ファイルシステムエンコーディング

wchar_t サポート

組み込み codec (built-in codec)

汎用 codec

UTF-8 Codecs

UTF-32 Codecs

UTF-16 Codecs

UTF-7 Codecs

Unicode-Escape Codecs

Raw-Unicode-Escape Codecs

Latin-1 Codecs

ASCII Codecs

Character Map Codecs

Windows 用の MBCS codec

メソッドとスロット

メソッドおよびスロット関数 (slot function)

タプルオブジェクト (tuple object)

Struct Sequence オブジェクト

リストオブジェクト

Container オブジェクト

辞書オブジェクト (dictionary object)

Set オブジェクト

Function オブジェクト

Function オブジェクト

インスタンスメソッドオブジェクト(Instance Method Objects)

メソッドオブジェクト

セルオブジェクト (cell object)

コードオブジェクト

Extra information

その他のオブジェクト

ファイルオブジェクト

モジュールオブジェクト (module object)

Cモジュールの初期化

一段階初期化

多段階初期化

低水準モジュール作成関数

サポート関数

モジュール検索

イテレータオブジェクト (iterator object)

デスクリプタオブジェクト (descriptor object)

スライスオブジェクト (slice object)

Ellipsis オブジェクト

memoryview オブジェクト

弱参照オブジェクト

カプセル

フレーム (frame) オブジェクト

Internal Frames

ジェネレータオブジェクト

コルーチンオブジェクト

コンテキスト変数オブジェクト

DateTime オブジェクト

型ヒントのためのオブジェクト

型オブジェクト

type PyTypeObject

Part of the Limited API (as an opaque struct).

組み込み型を記述する際に用いられる、オブジェクトを表す C 構造体です。

PyTypeObject PyType_Type

Part of the Stable ABI.

型オブジェクト自身の型オブジェクトです; Python レイヤにおける type と同じオブジェクトです。

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.

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.

unsigned int PyType_ClearCache()

Part of the Stable ABI.

内部の検索キャッシュをクリアします。現在のバージョンタグを返します。

unsigned long PyType_GetFlags(PyTypeObject *type)

Part of the Stable ABI.

Return the tp_flags member of type. This function is primarily meant for use with Py_LIMITED_API; the individual flag bits are guaranteed to be stable across Python releases, but access to tp_flags itself is not part of the limited API.

Added in version 3.2.

バージョン 3.4 で変更: 返り値の型が long ではなく unsigned long になりました。

PyObject *PyType_GetDict(PyTypeObject *type)

Return the type object's internal namespace, which is otherwise only exposed via a read-only proxy (cls.__dict__). This is a replacement for accessing 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 PyObject_GetAttr()) isn't adequate.

Extension modules should continue to use tp_dict, directly or indirectly, when setting up their own types.

Added in version 3.12.

void PyType_Modified(PyTypeObject *type)

Part of the Stable ABI.

内部の検索キャッシュを、その type とすべてのサブタイプに対して無効にします。この関数は type の属性や基底クラス列を変更したあとに手動で呼び出さなければなりません。

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 PyType_Watch(). In case of error (e.g. no more watcher IDs available), return -1 and set an exception.

Added in version 3.12.

int PyType_ClearWatcher(int watcher_id)

Clear watcher identified by watcher_id (previously returned from PyType_AddWatcher()). Return 0 on success, -1 on error (e.g. if watcher_id was never registered.)

An extension should never call PyType_ClearWatcher with a watcher_id that was not returned to it by a previous call to PyType_AddWatcher().

Added in version 3.12.

int PyType_Watch(int watcher_id, PyObject *type)

Mark type as watched. The callback granted watcher_id by PyType_AddWatcher() will be called whenever PyType_Modified() reports a change to type. (The callback may be called only once for a series of consecutive modifications to type, if _PyType_Lookup() is not called on type between the modifications; this is an implementation detail and subject to change.)

An extension should never call PyType_Watch with a watcher_id that was not returned to it by a previous call to PyType_AddWatcher().

Added in version 3.12.

typedef int (*PyType_WatchCallback)(PyObject *type)

Type of a type-watcher callback function.

The callback must not modify type or cause PyType_Modified() to be called on type or any type in its MRO; violating this rule could cause infinite recursion.

Added in version 3.12.

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.

int PyType_IS_GC(PyTypeObject *o)

Return true if the type object includes support for the cycle detector; this tests the type flag Py_TPFLAGS_HAVE_GC.

int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b)

Part of the Stable ABI.

a が b のサブタイプの場合に真を返します。

この関数は実際のサブクラスをチェックするだけです。つまり、 __subclasscheck__() は b に対し呼ばれません。 issubclass() と同じチェックをするには PyObject_IsSubclass() を呼んでください。

PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)

Return value: New reference. Part of the Stable ABI.

型オブジェクトの tp_alloc に対するジェネリックハンドラです。 Python のデフォルトのメモリアロケートメカニズムを使って新しいインスタンスをアロケートし、すべての内容を NULL で初期化します。

PyObject *PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)

Return value: New reference. Part of the Stable ABI.

型オブジェクトの tp_new に対するジェネリックハンドラです。型の tp_alloc スロットを使って新しいインスタンスを作成します。

int PyType_Ready(PyTypeObject *type)

Part of the Stable ABI.

型オブジェクトのファイナライズを行います。この関数は全てのオブジェクトで初期化を完了するために呼び出されなくてはなりません。この関数は、基底クラス型から継承したスロットを型オブジェクトに追加する役割があります。成功した場合には 0 を返し、エラーの場合には -1 を返して例外情報を設定します。

注釈

If some of the base classes implements the GC protocol and the provided type does not include the 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 Py_TPFLAGS_HAVE_GC in its flags then it must implement the GC protocol itself by at least implementing the tp_traverse handle.

PyObject *PyType_GetName(PyTypeObject *type)

Return value: New reference. Part of the Stable ABI since version 3.11.

Return the type's name. Equivalent to getting the type's __name__ attribute.

Added in version 3.11.

PyObject *PyType_GetQualName(PyTypeObject *type)

Return value: New reference. Part of the Stable ABI since version 3.11.

Return the type's qualified name. Equivalent to getting the type's __qualname__ attribute.

Added in version 3.11.

void *PyType_GetSlot(PyTypeObject *type, int slot)

Part of the Stable ABI since version 3.4.

与えられたスロットに格納されている関数ポインタを返します。返り値が NULL の場合は、スロットが NULL か、関数が不正な引数で呼ばれたことを示します。通常、呼び出し側は返り値のポインタを適切な関数型にキャストします。

See PyType_Slot.slot for possible values of the slot argument.

Added in version 3.4.

バージョン 3.10 で変更: PyType_GetSlot() can now accept all types. Previously, it was limited to heap types.

PyObject *PyType_GetModule(PyTypeObject *type)

Part of the Stable ABI since version 3.10.

Return the module object associated with the given type when the type was created using PyType_FromModuleAndSpec().

If no module is associated with the given type, sets TypeError and returns NULL.

This function is usually used to get the module in which a method is defined. Note that in such a method, PyType_GetModule(Py_TYPE(self)) may not return the intended result. 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 PyCMethod to get the class that defines the method. See PyType_GetModuleByDef() for cases when PyCMethod cannot be used.

Added in version 3.9.

void *PyType_GetModuleState(PyTypeObject *type)

Part of the Stable ABI since version 3.10.

Return the state of the module object associated with the given type. This is a shortcut for calling PyModule_GetState() on the result of PyType_GetModule().

If no module is associated with the given type, sets TypeError and returns NULL.

If the type has an associated module but its state is NULL, returns NULL without setting an exception.

Added in version 3.9.

PyObject *PyType_GetModuleByDef(PyTypeObject *type, struct PyModuleDef *def)

Find the first superclass whose module was created from the given PyModuleDef def, and return that module.

If no module is found, raises a TypeError and returns NULL.

This function is intended to be used together with PyModule_GetState() to get module state from slot methods (such as tp_init or nb_add) and other places where a method's defining class cannot be passed using the PyCMethod calling convention.

Added in version 3.11.

int PyUnstable_Type_AssignVersionTag(PyTypeObject *type)

これは Unstable API. It may change without warning in minor releases.

Attempt to assign a version tag to the given type.

Returns 1 if the type already had a valid version tag or a new one was assigned, or 0 if a new tag could not be assigned.

Added in version 3.12.

Creating Heap-Allocated Types

The following functions and structs are used to create heap types.

PyObject *PyType_FromMetaclass(PyTypeObject *metaclass, PyObject *module, PyType_Spec *spec, PyObject *bases)

Part of the Stable ABI since version 3.12.

Create and return a heap type from the spec (see Py_TPFLAGS_HEAPTYPE).

The metaclass metaclass is used to construct the resulting type object. When metaclass is NULL, the metaclass is derived from bases (or Py_tp_base[s] slots if bases is NULL, see below).

Metaclasses that override tp_new are not supported, except if tp_new is NULL. (For backwards compatibility, other PyType_From* functions allow such metaclasses. They ignore tp_new, which may result in incomplete initialization. This is deprecated and in Python 3.14+ such metaclasses will not be supported.)

The bases argument can be used to specify base classes; it can either be only one class or a tuple of classes. If bases is NULL, the Py_tp_bases slot is used instead. If that also is NULL, the Py_tp_base slot is used instead. If that also is NULL, the new type derives from 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 NULL. If not NULL, the module is associated with the new type and can later be retrieved with PyType_GetModule(). The associated module is not inherited by subclasses; it must be specified for each class individually.

This function calls PyType_Ready() on the new type.

Note that this function does not fully match the behavior of calling type() or using the class statement. With user-provided base types or metaclasses, prefer calling type (or the metaclass) over PyType_From* functions. Specifically:

__new__() is not called on the new class (and it must be set to type.__new__).

__init__() is not called on the new class.

__init_subclass__() is not called on any bases.

__set_name__() is not called on new descriptors.

Added in version 3.12.

PyObject *PyType_FromModuleAndSpec(PyObject *module, PyType_Spec *spec, PyObject *bases)

Return value: New reference. Part of the Stable ABI since version 3.10.

Equivalent to PyType_FromMetaclass(NULL, module, spec, bases).

Added in version 3.9.

バージョン 3.10 で変更: The function now accepts a single class as the bases argument and NULL as the tp_doc slot.

バージョン 3.12 で変更: The function now finds and uses a metaclass corresponding to the provided base classes. Previously, only type instances were returned.

The tp_new of the metaclass is ignored. which may result in incomplete initialization. Creating classes whose metaclass overrides tp_new is deprecated and in Python 3.14+ it will be no longer allowed.

PyObject *PyType_FromSpecWithBases(PyType_Spec *spec, PyObject *bases)

Return value: New reference. Part of the Stable ABI since version 3.3.

Equivalent to PyType_FromMetaclass(NULL, NULL, spec, bases).

Added in version 3.3.

バージョン 3.12 で変更: The function now finds and uses a metaclass corresponding to the provided base classes. Previously, only type instances were returned.

The tp_new of the metaclass is ignored. which may result in incomplete initialization. Creating classes whose metaclass overrides tp_new is deprecated and in Python 3.14+ it will be no longer allowed.

PyObject *PyType_FromSpec(PyType_Spec *spec)

Return value: New reference. Part of the Stable ABI.

Equivalent to 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 type instances were returned.

The tp_new of the metaclass is ignored. which may result in incomplete initialization. Creating classes whose metaclass overrides tp_new is deprecated and in Python 3.14+ it will be no longer allowed.

type PyType_Spec

Part of the Stable ABI (including all members).

Structure defining a type's behavior.

const char *name

Name of the type, used to set PyTypeObject.tp_name.

int basicsize

If positive, specifies the size of the instance in bytes. It is used to set PyTypeObject.tp_basicsize.

If zero, specifies that 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 PyObject_GetTypeData() to get a pointer to subclass-specific memory reserved this way.

バージョン 3.12 で変更: Previously, this field could not be negative.

int itemsize

Size of one element of a variable-size type, in bytes. Used to set PyTypeObject.tp_itemsize. See tp_itemsize documentation for caveats.

If zero, 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 itemsize is only possible in the following situations:

The base is not variable-sized (its tp_itemsize).

The requested PyType_Spec.basicsize is positive, suggesting that the memory layout of the base class is known.

The requested PyType_Spec.basicsize is zero, suggesting that the subclass does not access the instance's memory directly.

With the Py_TPFLAGS_ITEMS_AT_END flag.

unsigned int flags

Type flags, used to set PyTypeObject.tp_flags.

If the Py_TPFLAGS_HEAPTYPE flag is not set, PyType_FromSpecWithBases() sets it automatically.

PyType_Slot *slots

Array of PyType_Slot structures. Terminated by the special slot value {0, NULL}.

Each slot ID should be specified at most once.

type PyType_Slot

Part of the Stable ABI (including all members).

Structure defining optional functionality of a type, containing a slot ID and a value pointer.

int slot

A slot ID.

Slot IDs are named like the field names of the structures PyTypeObject, PyNumberMethods, PySequenceMethods, PyMappingMethods and PyAsyncMethods with an added Py_ prefix. For example, use:

Py_tp_dealloc to set PyTypeObject.tp_dealloc

Py_nb_add to set PyNumberMethods.nb_add

Py_sq_length to set PySequenceMethods.sq_length

The following “offset” fields cannot be set using PyType_Slot:

tp_weaklistoffset (use Py_TPFLAGS_MANAGED_WEAKREF instead if possible)

tp_dictoffset (use Py_TPFLAGS_MANAGED_DICT instead if possible)

tp_vectorcall_offset (use "__vectorcalloffset__" in PyMemberDef)

If it is not possible to switch to a MANAGED flag (for example, for vectorcall or to support Python older than 3.12), specify the offset in Py_tp_members. See PyMemberDef documentation for details.

The following fields cannot be set at all when creating a heap type:

tp_vectorcall (use tp_new and/or tp_init)

Internal fields: tp_dict, tp_mro, tp_cache, tp_subclasses, and tp_weaklist.

Setting Py_tp_bases or Py_tp_base may be problematic on some platforms. To avoid issues, use the bases argument of PyType_FromSpecWithBases() instead.

バージョン 3.9 で変更: Slots in PyBufferProcs may be set in the unlimited API.

バージョン 3.11 で変更: bf_getbuffer and bf_releasebuffer are now available under the limited API.

void *pfunc

The desired value of the slot. In most cases, this is a pointer to a function.

Slots other than Py_tp_doc may not be NULL.

None オブジェクト

Note that the PyTypeObject for None is not directly exposed in the Python/C API. Since None is a singleton, testing for object identity (using == in C) is sufficient. There is no PyNone_Check() function for the same reason.

PyObject *Py_None

The Python None object, denoting lack of value. This object has no methods and is immortal [https://peps.python.org/pep-0683/].

バージョン 3.12 で変更: Py_None is immortal.

Py_RETURN_NONE

Return Py_None from a function.

整数型オブジェクト (integer object)

すべての整数は任意の長さをもつ "long" 整数として実装されます。

エラーが起きると、ほとんどの PyLong_As* API は (return type)-1 を返しますが、これは数値と見分けが付きません。見分けを付けるためには PyErr_Occurred() を使ってください。

type PyLongObject

Part of the Limited API (as an opaque struct).

この PyObject のサブタイプは整数型を表現します。

PyTypeObject PyLong_Type

Part of the Stable ABI.

この PyTypeObject のインスタンスは Python 整数型を表現します。これは Python レイヤにおける int と同じオブジェクトです。

int PyLong_Check(PyObject *p)

引数が PyLongObject か PyLongObject のサブタイプであるときに真を返します。この関数は常に成功します。

int PyLong_CheckExact(PyObject *p)

引数が PyLongObject であるが PyLongObject のサブタイプでないときに真を返します。この関数は常に成功します。

PyObject *PyLong_FromLong(long v)

Return value: New reference. Part of the Stable ABI.

v から新たな PyLongObject オブジェクトを生成して返します。失敗のときには NULL を返します。

現在の実装では、-5 から 256 までの全ての整数に対する整数オブジェクトの配列を保持します。この範囲の数を生成すると、実際には既存のオブジェクトに対する参照が返るようになっています。

PyObject *PyLong_FromUnsignedLong(unsigned long v)

Return value: New reference. Part of the Stable ABI.

Cの unsigned long から新たな PyLongObject オブジェクトを生成して返します。失敗した際には NULL を返します。

PyObject *PyLong_FromSsize_t(Py_ssize_t v)

Return value: New reference. Part of the Stable ABI.

C の Py_ssize_t 型から新たな PyLongObject オブジェクトを生成して返します。 失敗のときには NULL を返します。

PyObject *PyLong_FromSize_t(size_t v)

Return value: New reference. Part of the Stable ABI.

C の size_t 型から新たな PyLongObject オブジェクトを生成して返します。 失敗のときには NULL を返します。

PyObject *PyLong_FromLongLong(long long v)

Return value: New reference. Part of the Stable ABI.

C の long long 型から新たな PyLongObject オブジェクトを生成して返します。失敗のときには NULL を返します。

PyObject *PyLong_FromUnsignedLongLong(unsigned long long v)

Return value: New reference. Part of the Stable ABI.

C の unsigned long long 型から新たな PyLongObject オブジェクトを生成して返します。失敗のときには NULL を返します。

PyObject *PyLong_FromDouble(double v)

Return value: New reference. Part of the Stable ABI.

v の整数部から新たな PyLongObject オブジェクトを生成して返します。失敗のときには NULL を返します。

PyObject *PyLong_FromString(const char *str, char **pend, int base)

Return value: New reference. Part of the Stable ABI.

Return a new PyLongObject based on the string value in str, which is interpreted according to the radix in base, or NULL on failure. If pend is non-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 0, str is interpreted using the 整数リテラル definition; in this case, leading zeros in a non-zero decimal number raises a ValueError. If base is not 0, it must be between 2 and 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, ValueError will be raised.

参考

Python methods int.to_bytes() and int.from_bytes() to convert a PyLongObject to/from an array of bytes in base 256. You can call those from C using PyObject_CallMethod().

PyObject *PyLong_FromUnicodeObject(PyObject *u, int base)

Return value: New reference.

Convert a sequence of Unicode digits in the string u to a Python integer value.

Added in version 3.3.

PyObject *PyLong_FromVoidPtr(void *p)

Return value: New reference. Part of the Stable ABI.

ポインタ p から Python 整数値を生成します。ポインタの値は PyLong_AsVoidPtr() を適用した結果から取得されます。

long PyLong_AsLong(PyObject *obj)

Part of the Stable ABI.

Return a C long representation of obj. If obj is not an instance of PyLongObject, first call its __index__() method (if present) to convert it to a PyLongObject.

もし obj の値が long の範囲外であれば、 OverflowError を送出します。

エラーが起きたときに -1 を返します。見分けを付けるためには PyErr_Occurred() を使ってください。

バージョン 3.8 で変更: 可能であれば __index__() を使うようになりました。

バージョン 3.10 で変更: This function will no longer use __int__().

long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)

Part of the Stable ABI.

Return a C long representation of obj. If obj is not an instance of PyLongObject, first call its __index__() method (if present) to convert it to a PyLongObject.

If the value of obj is greater than LONG_MAX or less than LONG_MIN, set *overflow to 1 or -1, respectively, and return -1; otherwise, set *overflow to 0. If any other exception occurs set *overflow to 0 and return -1 as usual.

エラーが起きたときに -1 を返します。見分けを付けるためには PyErr_Occurred() を使ってください。

バージョン 3.8 で変更: 可能であれば __index__() を使うようになりました。

バージョン 3.10 で変更: This function will no longer use __int__().

long long PyLong_AsLongLong(PyObject *obj)

Part of the Stable ABI.

Return a C long long representation of obj. If obj is not an instance of PyLongObject, first call its __index__() method (if present) to convert it to a PyLongObject.

もし obj の値が long long の範囲外であれば、 OverflowError を送出します。

エラーが起きたときに -1 を返します。見分けを付けるためには PyErr_Occurred() を使ってください。

バージョン 3.8 で変更: 可能であれば __index__() を使うようになりました。

バージョン 3.10 で変更: This function will no longer use __int__().

long long PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow)

Part of the Stable ABI.

Return a C long long representation of obj. If obj is not an instance of PyLongObject, first call its __index__() method (if present) to convert it to a PyLongObject.

If the value of obj is greater than LLONG_MAX or less than LLONG_MIN, set *overflow to 1 or -1, respectively, and return -1; otherwise, set *overflow to 0. If any other exception occurs set *overflow to 0 and return -1 as usual.

エラーが起きたときに -1 を返します。見分けを付けるためには PyErr_Occurred() を使ってください。

Added in version 3.2.

バージョン 3.8 で変更: 可能であれば __index__() を使うようになりました。

バージョン 3.10 で変更: This function will no longer use __int__().

Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)

Part of the Stable ABI.

pylong を表す C の Py_ssize_t を返します。 pylong は PyLongObject のインスタンスでなければなりません。

もし pylong の値が Py_ssize_t の範囲外であれば、 OverflowError を送出します。

エラーが起きたときに -1 を返します。見分けを付けるためには PyErr_Occurred() を使ってください。

unsigned long PyLong_AsUnsignedLong(PyObject *pylong)

Part of the Stable ABI.

pylong を表す C の unsigned long を返します。 pylong は PyLongObject のインスタンスでなければなりません。

もし pylong の値が unsigned long の範囲外であれば、 OverflowError を送出します。

エラーが起きたときに (unsigned long)-1 を返します。見分けを付けるためには PyErr_Occurred() を使ってください。

size_t PyLong_AsSize_t(PyObject *pylong)

Part of the Stable ABI.

pylong を表す C の size_t を返します。 pylong は PyLongObject のインスタンスでなければなりません。

もし pylong の値が size_t の範囲外であれば、 OverflowError を送出します。

エラーが起きたときに (size_t)-1 を返します。見分けを付けるためには PyErr_Occurred() を使ってください。

unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong)

Part of the Stable ABI.

pylong を表す C の unsigned long long を返します。 pylong は PyLongObject のインスタンスでなければなりません。

もし pylong の値が unsigned long long の範囲外であれば、 OverflowError を送出します。

エラーが起きたときに (unsigned long long)-1 を返します。見分けを付けるためには PyErr_Occurred() を使ってください。

バージョン 3.1 で変更: 負 pylong を指定した際に TypeError ではなく、 OverflowError を送出するようになりました。

unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)

Part of the Stable ABI.

Return a C unsigned long representation of obj. If obj is not an instance of PyLongObject, first call its __index__() method (if present) to convert it to a PyLongObject.

obj の値が unsigned long の範囲から外れていた場合は、 ULONG_MAX + 1 を法とした剰余を返します。

エラーが起きたときに (unsigned long)-1 を返します。見分けを付けるためには PyErr_Occurred() を使ってください。

バージョン 3.8 で変更: 可能であれば __index__() を使うようになりました。

バージョン 3.10 で変更: This function will no longer use __int__().

unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj)

Part of the Stable ABI.

Return a C unsigned long long representation of obj. If obj is not an instance of PyLongObject, first call its __index__() method (if present) to convert it to a PyLongObject.

obj の値が unsigned long long の範囲から外れていた場合は、 ULLONG_MAX + 1 を法とした剰余を返します。

エラーが起きたときに (unsigned long long)-1 を返します。見分けを付けるためには PyErr_Occurred() を使ってください。

バージョン 3.8 で変更: 可能であれば __index__() を使うようになりました。

バージョン 3.10 で変更: This function will no longer use __int__().

double PyLong_AsDouble(PyObject *pylong)

Part of the Stable ABI.

pylong を表す C の double を返します。 pylong は PyLongObject のインスタンスでなければなりません。

もし pylong の値が double の範囲外であれば、 OverflowError を送出します。

エラーが起きたときに -1.0 を返します。見分けを付けるためには PyErr_Occurred() を使ってください。

void *PyLong_AsVoidPtr(PyObject *pylong)

Part of the Stable ABI.

Python の整数型を指す pylong を、 C の void ポインタに変換します。 pylong を変換できなければ、 OverflowError を送出します。この関数は PyLong_FromVoidPtr() で値を生成するときに使うような void ポインタ型を生成できるだけです。

エラーが起きたときに NULL を返します。見分けを付けるためには PyErr_Occurred() を使ってください。

int PyUnstable_Long_IsCompact(const PyLongObject *op)

これは Unstable API. It may change without warning in minor releases.

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 PyUnstable_Long_CompactValue(); for others fall back to a PyLong_As* function or calling int.to_bytes().

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.

Py_ssize_t PyUnstable_Long_CompactValue(const PyLongObject *op)

これは Unstable API. It may change without warning in minor releases.

If op is compact, as determined by PyUnstable_Long_IsCompact(), return its value.

Otherwise, the return value is undefined.

Boolean オブジェクト

Python の Bool 型は整数のサブクラスとして実装されています。ブール型の値は、 Py_False と Py_True の 2 つしかありません。従って、通常の生成／削除関数はブール型にはあてはまりません。とはいえ、以下のマクロが利用できます。

PyTypeObject PyBool_Type

Part of the Stable ABI.

この PyTypeObject のインスタンスは Python の boolean 型を表現します; Python レイヤにおける bool と同じオブジェクトです。

int PyBool_Check(PyObject *o)

o が PyBool_Type 型の場合に真を返します。この関数は常に成功します。

PyObject *Py_False

The Python False object. This object has no methods and is immortal [https://peps.python.org/pep-0683/].

バージョン 3.12 で変更: Py_False is immortal.

PyObject *Py_True

The Python True object. This object has no methods and is immortal [https://peps.python.org/pep-0683/].

バージョン 3.12 で変更: Py_True is immortal.

Py_RETURN_FALSE

Return Py_False from a function.

Py_RETURN_TRUE

Return Py_True from a function.

PyObject *PyBool_FromLong(long v)

Return value: New reference. Part of the Stable ABI.

v の値に応じて Py_True または Py_False を返します。

浮動小数点型オブジェクト (floating point object)

type PyFloatObject

この PyObject のサブタイプは Python 浮動小数点オブジェクトを表現します。

PyTypeObject PyFloat_Type

Part of the Stable ABI.

この PyTypeObject のインスタンスは Python 浮動小数点型を表現します。これは Python レイヤにおける float と同じオブジェクトです。

int PyFloat_Check(PyObject *p)

引数が PyFloatObject か PyFloatObject のサブタイプであるときに真を返します。この関数は常に成功します。

int PyFloat_CheckExact(PyObject *p)

引数が PyFloatObject であるが PyFloatObject のサブタイプでないときに真を返します。この関数は常に成功します。

PyObject *PyFloat_FromString(PyObject *str)

Return value: New reference. Part of the Stable ABI.

str の文字列値をもとに PyFloatObject オブジェクトを生成します。失敗すると NULL を返します。

PyObject *PyFloat_FromDouble(double v)

Return value: New reference. Part of the Stable ABI.

v から PyFloatObject オブジェクトを生成して返します。失敗すると NULL を返します。

double PyFloat_AsDouble(PyObject *pyfloat)

Part of the Stable ABI.

Return a C double representation of the contents of pyfloat. If pyfloat is not a Python floating point object but has a __float__() method, this method will first be called to convert pyfloat into a float. If __float__() is not defined then it falls back to __index__(). This method returns -1.0 upon failure, so one should call PyErr_Occurred() to check for errors.

バージョン 3.8 で変更: 可能であれば __index__() を使うようになりました。

double PyFloat_AS_DOUBLE(PyObject *pyfloat)

pyfloat の指す値を、 C の double 型表現で返しますが、エラーチェックを行いません。

PyObject *PyFloat_GetInfo(void)

Return value: New reference. Part of the Stable ABI.

float の精度、最小値、最大値に関する情報を含む structseq インスタンスを返します。これは、 float.h ファイルの薄いラッパーです。

double PyFloat_GetMax()

Part of the Stable ABI.

float の表現できる最大限解値 DBL_MAX を C の double 型で返します。

double PyFloat_GetMin()

Part of the Stable ABI.

float の正規化された最小の正の値 DBL_MIN を C の double 型で返します。

Pack and Unpack functions

The pack and unpack functions provide an efficient platform-independent way to store floating-point values as byte strings. The Pack routines produce a bytes string from a C double, and the Unpack routines produce a C double from such a bytes string. The suffix (2, 4 or 8) specifies the number of bytes in the bytes string.

On platforms that appear to use IEEE 754 formats these functions work by copying bits. On other platforms, the 2-byte format is identical to the IEEE 754 binary16 half-precision format, the 4-byte format (32-bit) is identical to the IEEE 754 binary32 single precision format, and the 8-byte format to the IEEE 754 binary64 double precision format, although the packing of INFs and NaNs (if such things exist on the platform) isn't handled correctly, and attempting to unpack a bytes string containing an IEEE INF or NaN will raise an exception.

On non-IEEE platforms with more precision, or larger dynamic range, than IEEE 754 supports, not all values can be packed; on non-IEEE platforms with less precision, or smaller dynamic range, not all values can be unpacked. What happens in such cases is partly accidental (alas).

Added in version 3.11.

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 p+1, p+3, or p+6 p+7), zero if you want big-endian format (exponent first, at p). The PY_BIG_ENDIAN constant can be used to use the native endian: it is equal to 1 on big endian processor, or 0 on little endian processor.

Return value: 0 if all is OK, -1 if error (and an exception is set, most likely OverflowError).

There are two problems on non-IEEE platforms:

What this does is undefined if x is a NaN or infinity.

-0.0 and +0.0 produce the same bytes string.

int PyFloat_Pack2(double x, unsigned char *p, int le)

Pack a C double as the IEEE 754 binary16 half-precision format.

int PyFloat_Pack4(double x, unsigned char *p, int le)

Pack a C double as the IEEE 754 binary32 single precision format.

int PyFloat_Pack8(double x, unsigned char *p, int le)

Pack a C double as the IEEE 754 binary64 double precision format.

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 p+1, p+3 or p+6 and p+7), zero if big-endian (exponent first, at p). The PY_BIG_ENDIAN constant can be used to use the native endian: it is equal to 1 on big endian processor, or 0 on little endian processor.

Return value: The unpacked double. On error, this is -1.0 and PyErr_Occurred() is true (and an exception is set, most likely OverflowError).

Note that on a non-IEEE platform this will refuse to unpack a bytes string that represents a NaN or infinity.

double PyFloat_Unpack2(const unsigned char *p, int le)

Unpack the IEEE 754 binary16 half-precision format as a C double.

double PyFloat_Unpack4(const unsigned char *p, int le)

Unpack the IEEE 754 binary32 single precision format as a C double.

double PyFloat_Unpack8(const unsigned char *p, int le)

Unpack the IEEE 754 binary64 double precision format as a C double.

複素数オブジェクト

Python の複素数オブジェクトは、C API 側から見ると二つの別個の型として実装されています: 一方は Python プログラムに対して公開されている Python のオブジェクトで、他方は実際の複素数値を表現する C の構造体です。API では、これら双方を扱う関数を提供しています。

C 構造体としての複素数

複素数の C 構造体を引数として受理したり、戻り値として返したりする関数は、ポインタ渡しを行うのではなく 値渡し を行うので注意してください。これは API 全体を通して一貫しています。

type Py_complex

Python 複素数オブジェクトの値の部分に対応する C の構造体です。複素数オブジェクトを扱うほとんどの関数は、この型の構造体を場合に応じて入力や出力として使います。構造体は以下のように定義されています:

typedef struct {
   double real;
   double imag;
} Py_complex;

Py_complex _Py_c_sum(Py_complex left, Py_complex right)

二つの複素数の和を C の Py_complex 型で返します。

Py_complex _Py_c_diff(Py_complex left, Py_complex right)

二つの複素数の差を C の Py_complex 型で返します。

Py_complex _Py_c_neg(Py_complex num)

複素数 num の符号反転 C の Py_complex 型で返します。

Py_complex _Py_c_prod(Py_complex left, Py_complex right)

二つの複素数の積を C の Py_complex 型で返します。

Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)

二つの複素数の商を C の Py_complex 型で返します。

divisor が null の場合は、このメソッドはゼロを返し、 errno に EDOM をセットします。

Py_complex _Py_c_pow(Py_complex num, Py_complex exp)

指数 exp の num 乗を C の Py_complex 型で返します。

num が null で exp が正の実数でない場合は、このメソッドはゼロを返し、 errno に EDOM をセットします。

Python オブジェクトとしての複素数型

type PyComplexObject

この PyObject のサブタイプは Python の複素数型を表現します。

PyTypeObject PyComplex_Type

Part of the Stable ABI.

この PyTypeObject のインスタンスは Python の複素数型を表現します。 Pythonレイヤの complex と同じオブジェクトです。

int PyComplex_Check(PyObject *p)

引数が PyComplexObject か PyComplexObject のサブタイプであるときに真を返します。この関数は常に成功します。

int PyComplex_CheckExact(PyObject *p)

引数が PyComplexObject であるが PyComplexObject のサブタイプでないときに真を返します。この関数は常に成功します。

PyObject *PyComplex_FromCComplex(Py_complex v)

Return value: New reference.

C の Py_complex 型から Python の複素数値を生成します。

PyObject *PyComplex_FromDoubles(double real, double imag)

Return value: New reference. Part of the Stable ABI.

新たな PyComplexObject オブジェクトを real と imag から生成します。

double PyComplex_RealAsDouble(PyObject *op)

Part of the Stable ABI.

op の実数部分を C の double 型で返します。

double PyComplex_ImagAsDouble(PyObject *op)

Part of the Stable ABI.

op の虚数部分を C の double 型で返します。

Py_complex PyComplex_AsCComplex(PyObject *op)

複素数値 op から Py_complex 型を生成します。

op が Python の複素数オブジェクトではないが、 __complex__() メソッドを持っていた場合、このメソッドが最初に呼ばれ、 op が Python の複素数オブジェクトに変換されます。 __complex__() が定義されていない場合は、 __float__() にフォールバックされます。 __float__() が定義されていない場合は、 __index__() にフォールバックされます。処理が失敗した場合は、このメソッドは実数の -1.0 を返します。

バージョン 3.8 で変更: 可能であれば __index__() を使うようになりました。

バイトオブジェクト

下記の関数は、バイトオブジェクトを期待している引数にバイトオブジェクトでないパラメタを指定して呼び出されると、 TypeError を送出します。

type PyBytesObject

この PyObject のサブタイプは、Python バイトオブジェクトを表します。

PyTypeObject PyBytes_Type

Part of the Stable ABI.

この PyTypeObject のインスタンスは、Python バイト型を表します; Pythonレイヤの bytes と同じオブジェクトです。

int PyBytes_Check(PyObject *o)

オブジェクト o が bytes オブジェクトか bytes 型のサブタイプのインスタンスである場合に真を返します。この関数は常に成功します。

int PyBytes_CheckExact(PyObject *o)

オブジェクト o が bytes オブジェクトだが bytes 型のサブタイプのインスタンスでない場合に真を返します。この関数は常に成功します。

PyObject *PyBytes_FromString(const char *v)

Return value: New reference. Part of the Stable ABI.

成功時に、文字列 v のコピーを値とする新しいバイトオブジェクトを返し、失敗時に NULL を返します。引数 v は NULL であってはなりません; そのチェックは行われません。

PyObject *PyBytes_FromStringAndSize(const char *v, Py_ssize_t len)

Return value: New reference. Part of the Stable ABI.

成功時に、文字列 v のコピーを値とする長さ len の新しいバイトオブジェクトを返し、失敗時に NULL を返します。引数 v が NULL の場合、バイトオブジェクトの中身は初期化されていません。

PyObject *PyBytes_FromFormat(const char *format, ...)

Return value: New reference. Part of the Stable ABI.

C 関数の printf() スタイルの format 文字列と可変長の引数を取り、結果のPython バイトオブジェクトのサイズを計算し、値を指定した書式にしたがって変換したバイトオブジェクトを返します。可変長の引数は C のデータ型でなければならず、 format 文字列中のフォーマット文字と厳密に関連付けられていなければなりません。下記のフォーマット文字が使用できます:

書式指定文字

型

備考

%%

n/a

リテラルの % 文字

%c

int

C の整数型で表現される単一のバイト。

%d

int

printf("%d") と同等。 [1]

%u

unsigned int

printf("%u") と同等。 [1]

%ld

long

printf("%ld") と同等。 [1]

%lu

unsigned long

printf("%lu") と同等。 [1]

%zd

Py_ssize_t

printf("%zd") と同等。 [1]

%zu

size_t

printf("%zu") と同等。 [1]

%i

int

printf("%i") と同等。 [1]

%x

int

printf("%x") と同等。 [1]

%s

const char*

null で終端された C の文字列。

%p

const void*

C ポインタの 16 進表記。printf("%p") とほとんど同じですが、プラットフォームにおける printf の定義に関わりなく先頭にリテラル 0x が付きます。

識別できない書式指定文字があった場合、残りの書式文字列はそのまま結果のオブジェクトにコピーされ、残りの引数は無視されます。

[1] (1,2,3,4,5,6,7,8)

整数指定子 (d, u, ld, lu, zd, zu, i, x): 精度が与えられていても、0指定子は有効です。

PyObject *PyBytes_FromFormatV(const char *format, va_list vargs)

Return value: New reference. Part of the Stable ABI.

ちょうど２つの引数を取ることを除いて、 PyBytes_FromFormat() と同じです。

PyObject *PyBytes_FromObject(PyObject *o)

Return value: New reference. Part of the Stable ABI.

バッファプロトコルを実装するオブジェクト o のバイト表現を返します。

Py_ssize_t PyBytes_Size(PyObject *o)

Part of the Stable ABI.

バイトオブジェクト o のバイト単位の長さを返します。

Py_ssize_t PyBytes_GET_SIZE(PyObject *o)

PyBytes_Size() に似ていますが、エラーチェックを行いません。

char *PyBytes_AsString(PyObject *o)

Part of the Stable ABI.

o の中身へのポインタを返します。ポインタは、 len(o) + 1 バイトからなる o の内部バッファを参照します。他に null のバイトがあるかどうかにかかわらず、バッファの最後のバイトは必ず null になります。 PyBytes_FromStringAndSize(NULL, size) で生成された場合を除いて、データを修正してはなりません。またポインタを解放（deallocated）してはなりません。もし、 o が bytes オブジェクトでなければ、 PyBytes_AsString() は NULL を返し TypeError を送出します。

char *PyBytes_AS_STRING(PyObject *string)

PyBytes_AsString() に似ていますが、エラーチェックを行いません。

int PyBytes_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)

Part of the Stable ABI.

Return the null-terminated contents of the object obj through the output variables buffer and length. Returns 0 on success.

length の値が NULL の場合、バイトオブジェクトが null バイトを含まない可能性があります。その場合、関数は -1 を返し、 ValueError を送出します。

buffer は obj の内部バッファを参照していて、これには末尾の null バイトも含んでいます (これは length には数えられません)。オブジェクトが PyBytes_FromStringAndSize(NULL, size) で生成された場合を除いて、何があってもデータを改変してはいけません。オブジェクトを解放 (deallocate) してもいけません。 obj が bytes オブジェクトでなかった場合は、 PyBytes_AsStringAndSize() は -1 を返し TypeError を送出します。

バージョン 3.5 で変更: 以前は bytes オブジェクトにヌルバイトが埋め込まれていたときに TypeError を送出していました。

void PyBytes_Concat(PyObject **bytes, PyObject *newpart)

Part of the Stable ABI.

newpart の内容を bytes の後ろに連結した新しいバイトオブジェクトを *bytes に生成します。呼び出し側は新しい参照を所有します。 bytes の古い値の参照は盗まれます。もし新しいオブジェクトが生成できない場合、古い bytes の参照は放棄され、 *bytes の値は NULL に設定されます; 適切な例外が設定されます。

void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)

Part of the Stable ABI.

Create a new bytes object in *bytes containing the contents of newpart appended to bytes. This version releases the strong reference to newpart (i.e. decrements its reference count).

int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)

A way to resize a bytes object even though it is "immutable". Only use this to build up a brand new bytes object; don't use this if the bytes may already be known in other parts of the code. It is an error to call this function if the refcount on the input bytes object is not one. 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 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 NULL, MemoryError is set, and -1 is returned.

bytearray オブジェクト

type PyByteArrayObject

この PyObject のサブタイプは Python の bytearray オブジェクトを表します。

PyTypeObject PyByteArray_Type

Part of the Stable ABI.

この PyTypeObject のインスタンスは、 Python bytearray 型を示します。 Python レイヤでの bytearray と同じオブジェクトです。

型チェックマクロ

int PyByteArray_Check(PyObject *o)

オブジェクト o が bytearray オブジェクトか bytearray 型のサブタイプのインスタンスである場合に真を返します。この関数は常に成功します。

int PyByteArray_CheckExact(PyObject *o)

オブジェクト o が bytearray オブジェクトだが bytearray 型のサブタイプのインスタンスでない場合に真を返します。この関数は常に成功します。

ダイレクト API 関数

PyObject *PyByteArray_FromObject(PyObject *o)

Return value: New reference. Part of the Stable ABI.

buffer protocol を実装した任意のオブジェクト o から、新しいbytearrayオブジェクトを作成し、返します。

PyObject *PyByteArray_FromStringAndSize(const char *string, Py_ssize_t len)

Return value: New reference. Part of the Stable ABI.

string とその長さ len から新しい bytearray オブジェクトを返します。失敗した場合は NULL を返します。

PyObject *PyByteArray_Concat(PyObject *a, PyObject *b)

Return value: New reference. Part of the Stable ABI.

bytearray a と b を連結した結果を新しい bytearray として返します。

Py_ssize_t PyByteArray_Size(PyObject *bytearray)

Part of the Stable ABI.

NULL ポインタチェックの後に bytearray のサイズを返します。

char *PyByteArray_AsString(PyObject *bytearray)

Part of the Stable ABI.

NULL ポインタチェックの後に bytearray の内容を char 配列として返します。返される配列には、常に余分な null バイトが追加されます。

int PyByteArray_Resize(PyObject *bytearray, Py_ssize_t len)

Part of the Stable ABI.

bytearray の内部バッファを len へリサイズします。

マクロ

以下のマクロは、ポインタのチェックをしないことにより安全性を犠牲にしてスピードを優先しています。

char *PyByteArray_AS_STRING(PyObject *bytearray)

PyByteArray_AsString() に似ていますが、エラーチェックを行いません。

Py_ssize_t PyByteArray_GET_SIZE(PyObject *bytearray)

PyByteArray_Size() に似ていますが、エラーチェックを行いません。

Unicode オブジェクトと codec

Unicode オブジェクト

Python3.3 の PEP 393 [https://peps.python.org/pep-0393/] 実装から、メモリ効率を維持しながらUnicode文字の完全な範囲を扱えるように、Unicodeオブジェクトは内部的に多様な表現形式を用いています。すべてのコードポイントが128、256または65536以下の文字列に対して特別なケースが存在しますが、それ以外ではコードポイントは1114112以下(これはすべてのUnicode範囲です)でなければなりません。

UTF-8 representation is created on demand and cached in the Unicode object.

注釈

The Py_UNICODE representation has been removed since Python 3.12 with deprecated APIs. See PEP 623 [https://peps.python.org/pep-0623/] for more information.

Unicode 型

以下は Python の Unicode 実装に用いられている基本 Unicode オブジェクト型です:

type Py_UCS4

type Py_UCS2

type Py_UCS1

Part of the Stable ABI.

これらの型は、それぞれ、32ビット、16ビット、そして8ビットの文字を保持するのに充分な幅を持つ符号なしの整数型のtypedefです。単一のUnicode文字を扱う場合は、 Py_UCS4 を用いてください。

Added in version 3.3.

type Py_UNICODE

これは、wchar_t のtypedef で、プラットフォームに依存して16ビットか32ビットの型になります。

バージョン 3.3 で変更: 以前のバージョンでは、Pythonをビルドした際に "narrow" または "wide" Unicode バージョンのどちらを選択したかによって、 16ビットか32ビットのどちらかの型になっていました。

type PyASCIIObject

type PyCompactUnicodeObject

type PyUnicodeObject

これらの PyObject のサブタイプは Python Unicode オブジェクトを表現します。 Unicode オブジェクトを扱う全ての API 関数は PyObject へのポインタを受け取って PyObject へのポインタを返すので、ほとんどの場合、これらの型を直接使うべきではありません。

Added in version 3.3.

PyTypeObject PyUnicode_Type

Part of the Stable ABI.

この PyTypeObject のインスタンスは、Python Unicode型を表します。これは、Pythonコードに str として露出されます。

The following APIs are C macros and static inlined functions for fast checks and access to internal read-only data of Unicode objects:

int PyUnicode_Check(PyObject *obj)

オブジェクト obj が Unicode オブジェクトか Unicode 型のサブタイプのインスタンスである場合に真を返します。この関数は常に成功します。

int PyUnicode_CheckExact(PyObject *obj)

オブジェクト obj が Unicode オブジェクトだがサブタイプのインスタンスでない場合に真を返します。この関数は常に成功します。

int PyUnicode_READY(PyObject *unicode)

Returns 0. This API is kept only for backward compatibility.

Added in version 3.3.

バージョン 3.10 で非推奨: This API does nothing since Python 3.12.

Py_ssize_t PyUnicode_GET_LENGTH(PyObject *unicode)

Unicode 文字列のコードポイントでの長さを返します。 unicode は "正統な" 表現形式の Unicode オブジェクトでなければなりません (ただしチェックはしません)。

Added in version 3.3.

Py_UCS1 *PyUnicode_1BYTE_DATA(PyObject *unicode)

Py_UCS2 *PyUnicode_2BYTE_DATA(PyObject *unicode)

Py_UCS4 *PyUnicode_4BYTE_DATA(PyObject *unicode)

文字に直接アクセスするために、 UCS1, UCS2, UCS4 のいずれかの整数型にキャストされた正統な表現形式へのポインタを返します。正統な表現が適正な文字サイズになっているかどうかのチェックはしません; PyUnicode_KIND() を使って正しい関数を選んでください。

Added in version 3.3.

PyUnicode_1BYTE_KIND

PyUnicode_2BYTE_KIND

PyUnicode_4BYTE_KIND

PyUnicode_KIND() マクロの返り値です。

Added in version 3.3.

バージョン 3.12 で変更: PyUnicode_WCHAR_KIND は削除されました。

int PyUnicode_KIND(PyObject *unicode)

この Unicode がデータを保存するのに1文字あたり何バイト使っているかを示す PyUnicode 種別の定数 (上を読んでください) のうち1つを返します。 unicode は "正統な" 表現形式の Unicode オブジェクトでなければなりません (ただしチェックはしません)。

Added in version 3.3.

void *PyUnicode_DATA(PyObject *unicode)

生の Unicode バッファへの void ポインタを返します。 unicode は "正統な" 表現形式の Unicode オブジェクトでなければなりません (ただしチェックはしません)。

Added in version 3.3.

void PyUnicode_WRITE(int kind, void *data, Py_ssize_t index, Py_UCS4 value)

正統な表現形式となっている (PyUnicode_DATA() で取得した) data に書き込みます。この関数は正常性のチェックを行わない、ループで使われるためのものです。呼び出し側は、他の呼び出しで取得した kind 値と data ポインタをキャッシュすべきです。 index は文字列の (0始まりの) インデックスで、 value はその場所に書き込まれることになる新しいコードポイントの値です。

Added in version 3.3.

Py_UCS4 PyUnicode_READ(int kind, void *data, Py_ssize_t index)

正統な表現形式となっている (PyUnicode_DATA() で取得した) data からコードポイントを読み取ります。チェックや事前確認のマクロ呼び出しは一切行われません。

Added in version 3.3.

Py_UCS4 PyUnicode_READ_CHAR(PyObject *unicode, Py_ssize_t index)

Unicode オブジェクト unicode から文字を読み取ります。この Unicode オブジェクトは "正統な" 表現形式でなければなりません。何度も連続して読み取る場合には、このマクロは PyUnicode_READ() よりも非効率的です。

Added in version 3.3.

Py_UCS4 PyUnicode_MAX_CHAR_VALUE(PyObject *unicode)

unicode に基づいて他の文字列を作るのに適した最大のコードポイントを返します。この Unicode オブジェクトは "正統な" 表現形式でなければなりません。この値は常に概算値ですが、文字列全体を調べるよりも効率的です。

Added in version 3.3.

int PyUnicode_IsIdentifier(PyObject *unicode)

Part of the Stable ABI.

文字列が、 識別子 (identifier) およびキーワード (keyword) 節の言語定義における有効な識別子であれば 1 を返します。それ以外の場合は 0 を返します。

バージョン 3.9 で変更: The function does not call Py_FatalError() anymore if the string is not ready.

Unicode 文字プロパティ

Unicode は数多くの異なる文字プロパティ (character property) を提供しています。よく使われる文字プロパティは、以下のマクロで利用できます。これらのマクロは Python の設定に応じて、各々 C の関数に対応付けられています。

int Py_UNICODE_ISSPACE(Py_UCS4 ch)

ch が空白文字かどうかに応じて 1 または 0 を返します。

int Py_UNICODE_ISLOWER(Py_UCS4 ch)

ch が小文字かどうかに応じて 1 または 0 を返します。

int Py_UNICODE_ISUPPER(Py_UCS4 ch)

ch が大文字かどうかに応じて 1 または 0 を返します。

int Py_UNICODE_ISTITLE(Py_UCS4 ch)

ch がタイトルケース文字 (titlecase character) かどうかに応じて 1 または 0 を返します。

int Py_UNICODE_ISLINEBREAK(Py_UCS4 ch)

ch が改行文字かどうかに応じて 1 または 0 を返します。

int Py_UNICODE_ISDECIMAL(Py_UCS4 ch)

ch が decimal 文字かどうかに応じて 1 または 0 を返します。

int Py_UNICODE_ISDIGIT(Py_UCS4 ch)

ch が digit 文字かどうかに応じて 1 または 0 を返します。

int Py_UNICODE_ISNUMERIC(Py_UCS4 ch)

ch が数字 (numeric) 文字かどうかに応じて 1 または 0 を返します。

int Py_UNICODE_ISALPHA(Py_UCS4 ch)

ch がアルファベット文字かどうかに応じて 1 または 0 を返します。

int Py_UNICODE_ISALNUM(Py_UCS4 ch)

ch が英数文字かどうかに応じて 1 または 0 を返します。

int Py_UNICODE_ISPRINTABLE(Py_UCS4 ch)

ch が文字が印字可能な文字かどうかに基づいて 1 または 0 を返します。非印字可能文字は、 Unicode 文字データベースで "Other" または "Separator" と定義されている文字の、印字可能と見なされる ASCII space (0x20) 以外のものです。 (なお、この文脈での印字可能文字は、文字列に repr() が呼び出されるときにエスケープすべきでない文字のことです。これは sys.stdout や sys.stderr に書き込まれる文字列の操作とは関係ありません。)

以下の API は、高速に直接文字変換を行うために使われます:

Py_UCS4 Py_UNICODE_TOLOWER(Py_UCS4 ch)

ch を小文字に変換したものを返します。

バージョン 3.3 で非推奨: This function uses simple case mappings.

Py_UCS4 Py_UNICODE_TOUPPER(Py_UCS4 ch)

ch を大文字に変換したものを返します。

バージョン 3.3 で非推奨: This function uses simple case mappings.

Py_UCS4 Py_UNICODE_TOTITLE(Py_UCS4 ch)

ch をタイトルケース文字に変換したものを返します。

バージョン 3.3 で非推奨: This function uses simple case mappings.

int Py_UNICODE_TODECIMAL(Py_UCS4 ch)

Return the character ch converted to a decimal positive integer. Return -1 if this is not possible. This function does not raise exceptions.

int Py_UNICODE_TODIGIT(Py_UCS4 ch)

Return the character ch converted to a single digit integer. Return -1 if this is not possible. This function does not raise exceptions.

double Py_UNICODE_TONUMERIC(Py_UCS4 ch)

ch を double に変換したものを返します。不可能ならば -1.0 を返します。この関数は例外を送出しません。

これらの API はサロゲートにも使えます:

int Py_UNICODE_IS_SURROGATE(Py_UCS4 ch)

ch がサロゲートかどうか (0xD800 <= ch <= 0xDFFF) をチェックします。

int Py_UNICODE_IS_HIGH_SURROGATE(Py_UCS4 ch)

ch が上位サロゲートかどうか (0xD800 <= ch <= 0xDBFF) をチェックします。

int Py_UNICODE_IS_LOW_SURROGATE(Py_UCS4 ch)

ch が下位サロゲートかどうか (0xDC00 <= ch <= 0xDFFF) をチェックします。

Py_UCS4 Py_UNICODE_JOIN_SURROGATES(Py_UCS4 high, Py_UCS4 low)

Join two surrogate characters and return a single 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].

Unicode 文字列の生成とアクセス

Unicode オブジェクトを生成したり、Unicode のシーケンスとしての基本的なプロパティにアクセスしたりするには、以下の API を使ってください:

PyObject *PyUnicode_New(Py_ssize_t size, Py_UCS4 maxchar)

Return value: New reference.

新しい Unicode オブジェクトを生成します。 maxchar は文字列に並べるコードポイントの正しい最大値にすべきです。その値は概算値として 127, 255, 65535, 1114111 の一番近い値に切り上げられます。

これは新しい Unicode オブジェクトを生成する推奨された方法です。この関数を使って生成されたオブジェクトはサイズ変更は不可能です。

Added in version 3.3.

PyObject *PyUnicode_FromKindAndData(int kind, const void *buffer, Py_ssize_t size)

Return value: New reference.

与えられた kind (取り得る値は PyUnicode_1BYTE_KIND などの PyUnicode_KIND() が返す値です) の Unicode オブジェクトを生成します。 buffer は、与えられた kind に従って1文字あたり 1, 2, 4 バイトのいずれかを単位として、長さ size の配列へのポインタでなければなりません。

If necessary, the input buffer is copied and transformed into the canonical representation. For example, if the buffer is a UCS4 string (PyUnicode_4BYTE_KIND) and it consists only of codepoints in the UCS1 range, it will be transformed into UCS1 (PyUnicode_1BYTE_KIND).

Added in version 3.3.

PyObject *PyUnicode_FromStringAndSize(const char *str, Py_ssize_t size)

Return value: New reference. Part of the Stable ABI.

Create a Unicode object from the char buffer str. The bytes will be interpreted as being UTF-8 encoded. The buffer is copied into the new object. The return value might be a shared object, i.e. modification of the data is not allowed.

This function raises SystemError when:

size < 0,

str is NULL and size > 0

バージョン 3.12 で変更: str == NULL with size > 0 is not allowed anymore.

PyObject *PyUnicode_FromString(const char *str)

Return value: New reference. Part of the Stable ABI.

UTF-8 エンコードされたnull終端のchar 型バッファ str から Unicode オブジェクトを生成します。

PyObject *PyUnicode_FromFormat(const char *format, ...)

Return value: New reference. Part of the Stable ABI.

Take a C 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.

一つの変換指定子は 2 またはそれ以上の文字を含み、その構成要素は以下からなりますが、示した順に出現しなければなりません:

指定子の開始を示す文字 '%' 。

変換フラグ (オプション)。一部の変換型の結果に影響します。

Minimum field width (optional). If specified as an '*' (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.

Precision (optional), given as a '.' (dot) followed by the precision. If specified as '*' (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.

精度長変換子 (オプション)。

変換型。

変換フラグ文字を以下に示します:

Flag

意味

0

数値型に対してゼロによるパディングを行います。

-

The converted value is left adjusted (overrides the 0 flag if both are given).

The length modifiers for following integer conversions (d, i, o, u, x, or X) specify the type of the argument (int by default):

修飾子

型

l

long または unsigned long

ll

long long または unsigned long long

j

intmax_t or uintmax_t

z

size_t or ssize_t

t

ptrdiff_t

The length modifier l for following conversions s or V specify that the type of the argument is const wchar_t*.

The conversion specifiers are:

Conversion Specifier

型

備考

%

n/a

The literal % character.

d, i

Specified by the length modifier

The decimal representation of a signed C integer.

u

Specified by the length modifier

The decimal representation of an unsigned C integer.

o

Specified by the length modifier

The octal representation of an unsigned C integer.

x

Specified by the length modifier

The hexadecimal representation of an unsigned C integer (lowercase).

X

Specified by the length modifier

The hexadecimal representation of an unsigned C integer (uppercase).

c

int

A single character.

s

const char* または const wchar_t*

null で終端された C の文字列。

p

const void*

C ポインタの 16 進表記。printf("%p") とほとんど同じですが、プラットフォームにおける printf の定義に関わりなく先頭にリテラル 0x が付きます。

A

PyObject*

ascii() の戻り値。

U

PyObject*

Unicode オブジェクト。

V

PyObject*, const char* or const wchar_t*

A Unicode object (which may be NULL) and a null-terminated C character array as a second parameter (which will be used, if the first parameter is NULL).

S

PyObject*

PyObject_Str() の戻り値。

R

PyObject*

PyObject_Repr() の戻り値。

注釈

The width formatter unit is number of characters rather than bytes. The precision formatter unit is number of bytes or wchar_t items (if the length modifier l is used) for "%s" and "%V" (if the PyObject* argument is NULL), and a number of characters for "%A", "%U", "%S", "%R" and "%V" (if the PyObject* argument is not NULL).

注釈

Unlike to C printf() the 0 flag has effect even when a precision is given for integer conversions (d, i, u, o, x, or X).

バージョン 3.2 で変更: "%lld", "%llu" のサポートが追加されました。

バージョン 3.3 で変更: "%li", "%lli", "%zi" のサポートが追加されました。

バージョン 3.4 で変更: "%s", "%A", "%U", "%V", "%S", "%R" での幅フォーマッタおよび精度フォーマッタのサポートが追加されました。

バージョン 3.12 で変更: Support for conversion specifiers o and X. Support for length modifiers j and t. Length modifiers are now applied to all integer conversions. Length modifier l is now applied to conversion specifiers s and V. Support for variable width and precision *. Support for flag -.

An unrecognized format character now sets a 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.

PyObject *PyUnicode_FromFormatV(const char *format, va_list vargs)

Return value: New reference. Part of the Stable ABI.

ちょうど２つの引数を取ることを除いて、 PyUnicode_FromFormat() と同じです。

PyObject *PyUnicode_FromObject(PyObject *obj)

Return value: New reference. Part of the Stable ABI.

Copy an instance of a Unicode subtype to a new true Unicode object if necessary. If obj is already a true Unicode object (not a subtype), return a new strong reference to the object.

Unicode やそのサブタイプ以外のオブジェクトでは TypeError が引き起こされます。

PyObject *PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)

Return value: New reference. Part of the Stable ABI.

エンコードされている obj を Unicode オブジェクトにデコードします。

bytes や bytearray や他の bytes-like objects は、与えられた encoding に従ってデコードされ、 errors で定義されたエラーハンドリングが使われます。これらの引数は両方とも NULL にでき、その場合この API はデフォルト値を使います (詳しことは 組み込み codec (built-in codec) を参照してください)。

その他のUnicodeオブジェクトを含むオブジェクトは TypeError 例外を引き起こします。

この API は、エラーが生じたときには NULL を返します。呼び出し側は返されたオブジェクトに対し参照カウンタを 1 つ減らす (decref) する責任があります。

Py_ssize_t PyUnicode_GetLength(PyObject *unicode)

Part of the Stable ABI since version 3.7.

Unicode オブジェクトの長さをコードポイントで返します。

Added in version 3.3.

Py_ssize_t PyUnicode_CopyCharacters(PyObject *to, Py_ssize_t to_start, PyObject *from, Py_ssize_t from_start, Py_ssize_t how_many)

ある Unicode オブジェクトから他へ文字をコピーします。この関数は必要なときに文字変換を行い、可能な場合は memcpy() へ差し戻します。失敗のときには -1 を返し、例外を設定します。そうでない場合は、コピーした文字数を返します。

Added in version 3.3.

Py_ssize_t PyUnicode_Fill(PyObject *unicode, Py_ssize_t start, Py_ssize_t length, Py_UCS4 fill_char)

文字列を文字で埋めます: unicode[start:start+length] で fill_char を埋めることになります。

fill_char が文字列の最大文字よりも大きい場合や、文字列2つ以上の参照を持ってた場合は失敗します。

書き込んだ文字数を返すか、失敗のときには -1 を返し例外を送出します。

Added in version 3.3.

int PyUnicode_WriteChar(PyObject *unicode, Py_ssize_t index, Py_UCS4 character)

Part of the Stable ABI since version 3.7.

文字列に文字を書き込みます。文字列は PyUnicode_New() で作成しなければなりません。 Unicode 文字列は不変とされているので、この文字列は共有されていたり、これまでにハッシュ化されていてはいけません。

この関数は unicode が Unicode オブジェクトであること、インデックスが範囲内であること、オブジェクトが安全に変更できる (つまり参照カウントが1である) ことをチェックします。

Added in version 3.3.

Py_UCS4 PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index)

Part of the Stable ABI since version 3.7.

文字列から文字を読み取ります。エラーチェックを行わない PyUnicode_READ_CHAR() とは対照的に、この関数は unicode が Unicode オブジェクトであること、インデックスが範囲内であることをチェックします。

Added in version 3.3.

PyObject *PyUnicode_Substring(PyObject *unicode, Py_ssize_t start, Py_ssize_t end)

Return value: New reference. Part of the Stable ABI since version 3.7.

Return a substring of unicode, from character index start (included) to character index end (excluded). Negative indices are not supported.

Added in version 3.3.

Py_UCS4 *PyUnicode_AsUCS4(PyObject *unicode, Py_UCS4 *buffer, Py_ssize_t buflen, int copy_null)

Part of the Stable ABI since version 3.7.

Copy the string unicode into a UCS4 buffer, including a null character, if copy_null is set. Returns NULL and sets an exception on error (in particular, a SystemError if buflen is smaller than the length of unicode). buffer is returned on success.

Added in version 3.3.

Py_UCS4 *PyUnicode_AsUCS4Copy(PyObject *unicode)

Part of the Stable ABI since version 3.7.

文字列 unicode を PyMem_Malloc() でメモリ確保された新しい UCS4 型のバッファにコピーします。これが失敗した場合は、 NULL を返し MemoryError をセットします。返されたバッファは必ず null コードポイントが追加されています。

Added in version 3.3.

ロケールエンコーディング

現在のロケールエンコーディングはオペレーティングシステムのテキストをデコードするのに使えます。

PyObject *PyUnicode_DecodeLocaleAndSize(const char *str, Py_ssize_t length, const char *errors)

Return value: New reference. Part of the Stable ABI since version 3.7.

Decode a string from UTF-8 on Android and VxWorks, or from the current locale encoding on other platforms. The supported error handlers are "strict" and "surrogateescape" (PEP 383 [https://peps.python.org/pep-0383/]). The decoder uses "strict" error handler if errors is NULL. str must end with a null character but cannot contain embedded null characters.

Use PyUnicode_DecodeFSDefaultAndSize() to decode a string from the filesystem encoding and error handler.

This function ignores the Python UTF-8 Mode.

参考

Py_DecodeLocale() 関数。

Added in version 3.3.

バージョン 3.7 で変更: この関数は、 Android 以外では現在のロケールエンコーディングを surrogateescape エラーハンドラで使うようになりました。以前は、 Py_DecodeLocale() が surrogateescape で使われ、現在のロケールエンコーディングは strict で使われていました。

PyObject *PyUnicode_DecodeLocale(const char *str, const char *errors)

Return value: New reference. Part of the Stable ABI since version 3.7.

Similar to PyUnicode_DecodeLocaleAndSize(), but compute the string length using strlen().

Added in version 3.3.

PyObject *PyUnicode_EncodeLocale(PyObject *unicode, const char *errors)

Return value: New reference. Part of the Stable ABI since version 3.7.

Encode a Unicode object to UTF-8 on Android and VxWorks, or to the current locale encoding on other platforms. The supported error handlers are "strict" and "surrogateescape" (PEP 383 [https://peps.python.org/pep-0383/]). The encoder uses "strict" error handler if errors is NULL. Return a bytes object. unicode cannot contain embedded null characters.

Use PyUnicode_EncodeFSDefault() to encode a string to the filesystem encoding and error handler.

This function ignores the Python UTF-8 Mode.

参考

Py_EncodeLocale() 関数。

Added in version 3.3.

バージョン 3.7 で変更: この関数は、 Android 以外では現在のロケールエンコーディングを surrogateescape エラーハンドラで使うようになりました。以前は、 Py_EncodeLocale() が surrogateescape で使われ、現在のロケールエンコーディングは strict で使われていました。

ファイルシステムエンコーディング

Functions encoding to and decoding from the filesystem encoding and error handler (PEP 383 [https://peps.python.org/pep-0383/] and PEP 529 [https://peps.python.org/pep-0529/]).

To encode file names to bytes during argument parsing, the "O&" converter should be used, passing PyUnicode_FSConverter() as the conversion function:

int PyUnicode_FSConverter(PyObject *obj, void *result)

Part of the Stable ABI.

ParseTuple converter: encode str objects -- obtained directly or through the os.PathLike interface -- to bytes using PyUnicode_EncodeFSDefault(); bytes objects are output as-is. result must be a PyBytesObject* which must be released when it is no longer used.

Added in version 3.1.

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

引数の構文解析中にファイル名を str にデコードするには、 "O&" コンバーターを使い、 PyUnicode_FSDecoder() を変換関数として渡すのがよいです:

int PyUnicode_FSDecoder(PyObject *obj, void *result)

Part of the Stable ABI.

ParseTuple converter: decode bytes objects -- obtained either directly or indirectly through the os.PathLike interface -- to str using PyUnicode_DecodeFSDefaultAndSize(); str objects are output as-is. result must be a PyUnicodeObject* which must be released when it is no longer used.

Added in version 3.2.

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

PyObject *PyUnicode_DecodeFSDefaultAndSize(const char *str, Py_ssize_t size)

Return value: New reference. Part of the Stable ABI.

Decode a string from the filesystem encoding and error handler.

If you need to decode a string from the current locale encoding, use PyUnicode_DecodeLocaleAndSize().

参考

Py_DecodeLocale() 関数。

バージョン 3.6 で変更: The filesystem error handler is now used.

PyObject *PyUnicode_DecodeFSDefault(const char *str)

Return value: New reference. Part of the Stable ABI.

Decode a null-terminated string from the filesystem encoding and error handler.

If the string length is known, use PyUnicode_DecodeFSDefaultAndSize().

バージョン 3.6 で変更: The filesystem error handler is now used.

PyObject *PyUnicode_EncodeFSDefault(PyObject *unicode)

Return value: New reference. Part of the Stable ABI.

Encode a Unicode object to the filesystem encoding and error handler, and return bytes. Note that the resulting bytes object can contain null bytes.

If you need to encode a string to the current locale encoding, use PyUnicode_EncodeLocale().

参考

Py_EncodeLocale() 関数。

Added in version 3.2.

バージョン 3.6 で変更: The filesystem error handler is now used.

wchar_t サポート

wchar_t をサポートするプラットフォームでの wchar_t サポート:

PyObject *PyUnicode_FromWideChar(const wchar_t *wstr, Py_ssize_t size)

Return value: New reference. Part of the Stable ABI.

Create a Unicode object from the wchar_t buffer wstr of the given size. Passing -1 as the size indicates that the function must itself compute the length, using wcslen(). Return NULL on failure.

Py_ssize_t PyUnicode_AsWideChar(PyObject *unicode, wchar_t *wstr, Py_ssize_t size)

Part of the Stable ABI.

Copy the Unicode object contents into the wchar_t buffer wstr. At most size wchar_t characters are copied (excluding a possibly trailing null termination character). Return the number of wchar_t characters copied or -1 in case of an error.

When wstr is 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.

wchar_t *PyUnicode_AsWideCharString(PyObject *unicode, Py_ssize_t *size)

Part of the Stable ABI since version 3.7.

Convert the Unicode object to a wide character string. The output string always ends with a null character. If size is not NULL, write the number of wide characters (excluding the trailing null termination character) into *size. Note that the resulting wchar_t string might contain null characters, which would cause the string to be truncated when used with most C functions. If size is NULL and the wchar_t* string contains null characters a ValueError is raised.

Returns a buffer allocated by PyMem_New (use PyMem_Free() to free it) on success. On error, returns NULL and *size is undefined. Raises a MemoryError if memory allocation is failed.

Added in version 3.2.

バージョン 3.7 で変更: Raises a ValueError if size is NULL and the wchar_t* string contains null characters.

組み込み codec (built-in codec)

Python には、処理速度を高めるために C で書かれた codec が揃えてあります。これら全ての codec は以下の関数を介して直接利用できます。

以下の API の多くが、 encoding と errors という二つの引数をとります。これらのパラメータは、組み込みの文字列コンストラクタである str() における同名のパラメータと同じ意味を持ちます。

Setting encoding to NULL causes the default encoding to be used which is UTF-8. The file system calls should use PyUnicode_FSConverter() for encoding file names. This uses the filesystem encoding and error handler internally.

errors で指定するエラー処理もまた、 NULL を指定できます。 NULL を指定すると、codec で定義されているデフォルト処理の使用を意味します。全ての組み込み codec で、デフォルトのエラー処理は "strict" (ValueError を送出する) になっています。

個々の codec は全て同様のインターフェースを使っています。個別の codec の説明では、説明を簡単にするために以下の汎用のインターフェースとの違いだけを説明しています。

汎用 codec

以下は汎用 codec の API です:

PyObject *PyUnicode_Decode(const char *str, Py_ssize_t size, const char *encoding, const char *errors)

Return value: New reference. Part of the Stable ABI.

Create a Unicode object by decoding size bytes of the encoded string str. encoding and errors have the same meaning as the parameters of the same name in the str() built-in function. The codec to be used is looked up using the Python codec registry. Return NULL if an exception was raised by the codec.

PyObject *PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)

Return value: New reference. Part of the Stable ABI.

Unicode オブジェクトをエンコードし、その結果を Python の bytes オブジェクトとして返します。 encoding および errors は Unicode 型の encode() メソッドに与える同名のパラメータと同じ意味を持ちます。使用する codec の検索は、 Python の codec レジストリを使って行います。 codec が例外を送出した場合には NULL を返します。

UTF-8 Codecs

以下は UTF-8 codec の APIです:

PyObject *PyUnicode_DecodeUTF8(const char *str, Py_ssize_t size, const char *errors)

Return value: New reference. Part of the Stable ABI.

UTF-8 でエンコードされた size バイトの文字列 str から Unicode オブジェクトを生成します。codec が例外を送出した場合には NULL を返します。

PyObject *PyUnicode_DecodeUTF8Stateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)

Return value: New reference. Part of the Stable ABI.

consumed が NULL の場合、 PyUnicode_DecodeUTF8() と同じように動作します。 consumed が NULL でない場合、末尾の不完全な UTF-8 バイト列はエラーとみなされません。これらのバイト列はデコードされず、デコードされたバイト数は consumed に格納されます。

PyObject *PyUnicode_AsUTF8String(PyObject *unicode)

Return value: New reference. Part of the Stable ABI.

UTF-8 で Unicode オブジェクトをエンコードし、結果を Python バイト列オブジェクトとして返します。エラー処理は "strict" です。 codec が例外を送出した場合には NULL を返します。

const char *PyUnicode_AsUTF8AndSize(PyObject *unicode, Py_ssize_t *size)

Part of the Stable ABI since version 3.10.

Unicode オブジェクトを UTF-8 でエンコードしたものへのポインタを返し、エンコードされた表現形式でのサイズ (バイト単位) を size に格納します。 size 引数は NULL でも構いません; その場合はサイズは格納されません。返されるバッファには、 null コードポイントがあるかどうかに関わらず、常に null バイトが終端に付加されています (これは size には勘定されません)。

In the case of an error, NULL is returned with an exception set and no size is stored.

This caches the UTF-8 representation of the string in the Unicode object, and subsequent calls will return a pointer to the same buffer. The caller is not responsible for deallocating the buffer. The buffer is deallocated and pointers to it become invalid when the Unicode object is garbage collected.

Added in version 3.3.

バージョン 3.7 で変更: 返り値の型が char * ではなく const char * になりました。

バージョン 3.10 で変更: This function is a part of the limited API.

const char *PyUnicode_AsUTF8(PyObject *unicode)

PyUnicode_AsUTF8AndSize() とほぼ同じですが、サイズを格納しません。

Added in version 3.3.

バージョン 3.7 で変更: 返り値の型が char * ではなく const char * になりました。

UTF-32 Codecs

以下は UTF-32 codec API です:

PyObject *PyUnicode_DecodeUTF32(const char *str, Py_ssize_t size, const char *errors, int *byteorder)

Return value: New reference. Part of the Stable ABI.

UTF-32 でエンコードされたバッファ文字列から size バイトをデコードし、 Unicodeオブジェクトとして返します。 errors は (NULL でないなら) エラーハンドラを指定します。デフォルトは "strict" です。

byteorder が NULL でない時、デコーダは与えられたバイトオーダーでデコードを開始します。

*byteorder == -1: little endian
*byteorder == 0:  native order
*byteorder == 1:  big endian

*byteorder が 0 で、入力データの最初の 4 バイトが byte order mark (BOM) ならば、デコーダはこのバイトオーダーに切り替え、BOM は結果の Unicode 文字列にコピーされません。 *byteorder が -1 または 1 ならば、全ての byte order mark は出力にコピーされます。

デコードが完了した後、入力データの終端に来た時点でのバイトオーダーを *byteorder にセットします。

byteorder が NULL のとき、 codec は native order モードで開始します。

codec が例外を発生させたときは NULL を返します。

PyObject *PyUnicode_DecodeUTF32Stateful(const char *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)

Return value: New reference. Part of the Stable ABI.

consumed が NULL のとき、 PyUnicode_DecodeUTF32() と同じように振る舞います。 consumed が NULL でないとき、 PyUnicode_DecodeUTF32Stateful() は末尾の不完全な (4 で割り切れない長さのバイト列などの) UTF-32 バイト列をエラーとして扱いません。末尾の不完全なバイト列はデコードされず、デコードされたバイト数が consumed に格納されます。

PyObject *PyUnicode_AsUTF32String(PyObject *unicode)

Return value: New reference. Part of the Stable ABI.

ネイティブバイトオーダーで UTF-32 エンコーディングされた Python バイト文字列を返します。文字列は常に BOM マークで始まります。エラーハンドラは "strict" です。 codec が例外を発生させたときは NULL を返します。

UTF-16 Codecs

以下は UTF-16 codec の APIです:

PyObject *PyUnicode_DecodeUTF16(const char *str, Py_ssize_t size, const char *errors, int *byteorder)

Return value: New reference. Part of the Stable ABI.

UTF-16 でエンコードされたバッファ s から size バイトだけデコードして、結果を Unicode オブジェクトで返します。 errors は (NULL でない場合) エラー処理方法を定義します。デフォルト値は "strict" です。

byteorder が NULL でない時、デコーダは与えられたバイトオーダーでデコードを開始します。

*byteorder == -1: little endian
*byteorder == 0:  native order
*byteorder == 1:  big endian

*byteorder が 0 で、入力データの先頭2バイトがバイトオーダーマーク (BOM) だった場合、デコーダは BOM が示すバイトオーダーに切り替え、そのBOMを結果の Unicode 文字列にコピーしません。 *byteorder が -1 か 1 だった場合、すべてのBOMは出力へコピーされます (出力では \ufeff か \ufffe のどちらかになるでしょう)。

デコードが完了した後、入力データの終端に来た時点でのバイトオーダーを *byteorder にセットします。

byteorder が NULL のとき、 codec は native order モードで開始します。

codec が例外を発生させたときは NULL を返します。

PyObject *PyUnicode_DecodeUTF16Stateful(const char *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)

Return value: New reference. Part of the Stable ABI.

consumed が NULL の場合、 PyUnicode_DecodeUTF16() と同じように動作します。 consumed が NULL でない場合、 PyUnicode_DecodeUTF16Stateful() は末尾の不完全な UTF-16 バイト列 (奇数長のバイト列や分割されたサロゲートペア) をエラーとみなしません。これらのバイト列はデコードされず、デコードされたバイト数を consumed に返します。

PyObject *PyUnicode_AsUTF16String(PyObject *unicode)

Return value: New reference. Part of the Stable ABI.

ネイティブバイトオーダーで UTF-16 エンコーディングされた Python バイト文字列を返します。文字列は常に BOM マークで始まります。エラーハンドラは "strict" です。 codec が例外を発生させたときは NULL を返します。

UTF-7 Codecs

以下は UTF-7 codec の API です:

PyObject *PyUnicode_DecodeUTF7(const char *str, Py_ssize_t size, const char *errors)

Return value: New reference. Part of the Stable ABI.

Create a Unicode object by decoding size bytes of the UTF-7 encoded string str. Return NULL if an exception was raised by the codec.

PyObject *PyUnicode_DecodeUTF7Stateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)

Return value: New reference. Part of the Stable ABI.

consumed が NULL のとき、 PyUnicode_DecodeUTF7() と同じように動作します。 consumed が NULL でないとき、末尾の不完全な UTF-7 base-64 部分をエラーとしません。不完全な部分のバイト列はデコードせずに、デコードしたバイト数を consumed に格納します。

Unicode-Escape Codecs

以下は "Unicode Escape" codec の API です:

PyObject *PyUnicode_DecodeUnicodeEscape(const char *str, Py_ssize_t size, const char *errors)

Return value: New reference. Part of the Stable ABI.

Create a Unicode object by decoding size bytes of the Unicode-Escape encoded string str. Return NULL if an exception was raised by the codec.

PyObject *PyUnicode_AsUnicodeEscapeString(PyObject *unicode)

Return value: New reference. Part of the Stable ABI.

Unicode-Escape を使い Unicode オブジェクトをエンコードし、結果を bytes オブジェクトとして返します。エラー処理は "strict" です。 codec が例外を送出した場合には NULL を返します。

Raw-Unicode-Escape Codecs

以下は "Raw Unicode Escape" codec の APIです:

PyObject *PyUnicode_DecodeRawUnicodeEscape(const char *str, Py_ssize_t size, const char *errors)

Return value: New reference. Part of the Stable ABI.

Create a Unicode object by decoding size bytes of the Raw-Unicode-Escape encoded string str. Return NULL if an exception was raised by the codec.

PyObject *PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)

Return value: New reference. Part of the Stable ABI.

Raw-Unicode-Escape を使い Unicode オブジェクトをエンコードし、結果を bytes オブジェクトとして返します。エラー処理は "strict" です。 codec が例外を送出した場合には NULL を返します。

Latin-1 Codecs

以下は Latin-1 codec の APIです: Latin-1 は、 Unicode 序数の最初の 256 個に対応し、エンコード時にはこの 256 個だけを受理します。

PyObject *PyUnicode_DecodeLatin1(const char *str, Py_ssize_t size, const char *errors)

Return value: New reference. Part of the Stable ABI.

Latin-1 でエンコードされた size バイトの文字列 str から Unicode オブジェクトを生成します。codec が例外を送出した場合には NULL を返します。

PyObject *PyUnicode_AsLatin1String(PyObject *unicode)

Return value: New reference. Part of the Stable ABI.

Latin-1 で Unicode オブジェクトをエンコードし、結果を Python bytes オブジェクトとして返します。エラー処理は "strict" です。 codec が例外を送出した場合には NULL を返します。

ASCII Codecs

以下は ASCII codec の APIです。 7 ビットの ASCII データだけを受理します。その他のコードはエラーになります。

PyObject *PyUnicode_DecodeASCII(const char *str, Py_ssize_t size, const char *errors)

Return value: New reference. Part of the Stable ABI.

Create a Unicode object by decoding size bytes of the ASCII encoded string str. Return NULL if an exception was raised by the codec.

PyObject *PyUnicode_AsASCIIString(PyObject *unicode)

Return value: New reference. Part of the Stable ABI.

ASCII で Unicode オブジェクトをエンコードし、結果を Python bytes オブジェクトとして返します。エラー処理は "strict" です。 codec が例外を送出した場合には NULL を返します。

Character Map Codecs

この codec は、多くの様々な codec を実装する際に使われるという点で特殊な codec です (実際、 encodings パッケージに入っている標準 codecs のほとんどは、この codec を使っています)。この codec は、文字のエンコードやデコードに対応表を使います。提供される対応表のオブジェクトは __getitem__() マッピングインターフェースをサポートしていなければなりません; 辞書やシーケンスがそれに適しています。

以下は mapping codec の APIです:

PyObject *PyUnicode_DecodeCharmap(const char *str, Py_ssize_t length, PyObject *mapping, const char *errors)

Return value: New reference. Part of the Stable ABI.

与えられた mapping オブジェクトを使って、 size バイトのエンコードされた文字列 str をデコードして Unicode オブジェクトを作成します。 codec が例外を発生させたときは NULL を返します。

If mapping is 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 None. Unmapped data bytes -- ones which cause a LookupError, as well as ones which get mapped to None, 0xFFFE or '\ufffe', are treated as undefined mappings and cause an error.

PyObject *PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)

Return value: New reference. Part of the Stable ABI.

Unicode オブジェクトを mapping に指定されたオブジェクトを使ってエンコードし、結果を bytes オブジェクトとして返します。エラー処理は "strict" です。 codec が例外を送出した場合には NULL を返します。

The mapping object must map Unicode ordinal integers to bytes objects, integers in the range from 0 to 255 or None. Unmapped character ordinals (ones which cause a LookupError) as well as mapped to None are treated as "undefined mapping" and cause an error.

以下の codec API は Unicode から Unicode への対応付けを行う特殊なものです。

PyObject *PyUnicode_Translate(PyObject *unicode, PyObject *table, const char *errors)

Return value: New reference. Part of the Stable ABI.

文字列に文字対応表 table を適用して変換し、変換結果を Unicode オブジェクトで返します。codec が例外を発行した場合には NULL を返します。

対応表は、Unicode 序数を表す整数を Unicode 序数を表す整数または None (その文字を削除する) に対応付けなければなりません。

Mapping tables need only provide the __getitem__() interface; dictionaries and sequences work well. Unmapped character ordinals (ones which cause a LookupError) are left untouched and are copied as-is.

errors は codecs で通常使われるのと同じ意味を持ちます。 errors は NULL にしてもよく、デフォルトエラー処理の使用を意味します。

Windows 用の MBCS codec

以下は MBCS codec の API です。この codec は現在のところ、 Windows 上だけで利用でき、変換の実装には Win32 MBCS 変換機構 (Win32 MBCS converter) を使っています。 MBCS (または DBCS) はエンコード方式の種類 (class) を表す言葉で、単一のエンコード方式を表すわけでなないので注意してください。利用されるエンコード方式 (target encoding) は、 codec を動作させているマシン上のユーザ設定で定義されています。

PyObject *PyUnicode_DecodeMBCS(const char *str, Py_ssize_t size, const char *errors)

Return value: New reference. Part of the Stable ABI on Windows since version 3.7.

Create a Unicode object by decoding size bytes of the MBCS encoded string str. Return NULL if an exception was raised by the codec.

PyObject *PyUnicode_DecodeMBCSStateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)

Return value: New reference. Part of the Stable ABI on Windows since version 3.7.

consumed が NULL のとき、 PyUnicode_DecodeMBCS() と同じ動作をします。 consumed が NULL でないとき、 PyUnicode_DecodeMBCSStateful() は文字列の最後にあるマルチバイト文字の前半バイトをデコードせず、 consumed にデコードしたバイト数を格納します。

PyObject *PyUnicode_AsMBCSString(PyObject *unicode)

Return value: New reference. Part of the Stable ABI on Windows since version 3.7.

MBCS で Unicode オブジェクトをエンコードし、結果を Python バイト列オブジェクトとして返します。エラー処理は "strict" です。 codec が例外を送出した場合には NULL を返します。

PyObject *PyUnicode_EncodeCodePage(int code_page, PyObject *unicode, const char *errors)

Return value: New reference. Part of the Stable ABI on Windows since version 3.7.

Encode the Unicode object using the specified code page and return a Python bytes object. Return NULL if an exception was raised by the codec. Use CP_ACP code page to get the MBCS encoder.

Added in version 3.3.

メソッドとスロット

メソッドおよびスロット関数 (slot function)

以下の API は Unicode オブジェクトおよび文字列を入力に取り (説明では、どちらも文字列と表記しています)、場合に応じて Unicode オブジェクトか整数を返す機能を持っています。

これらの関数は全て、例外が発生した場合には NULL または -1 を返します。

PyObject *PyUnicode_Concat(PyObject *left, PyObject *right)

Return value: New reference. Part of the Stable ABI.

二つの文字列を結合して、新たな Unicode 文字列を生成します。

PyObject *PyUnicode_Split(PyObject *unicode, PyObject *sep, Py_ssize_t maxsplit)

Return value: New reference. Part of the Stable ABI.

Unicode 文字列のリストを分割して、 Unicode 文字列からなるリストを返します。 sep が NULL の場合、全ての空白文字を使って分割を行います。それ以外の場合、指定された文字を使って分割を行います。最大で maxsplit 個までの分割を行います。 maxsplit が負ならば分割数に制限を設けません。分割結果のリスト内には分割文字は含みません。

PyObject *PyUnicode_Splitlines(PyObject *unicode, int keepends)

Return value: New reference. Part of the Stable ABI.

Split a Unicode string at line breaks, returning a list of Unicode strings. CRLF is considered to be one line break. If keepends is 0, the Line break characters are not included in the resulting strings.

PyObject *PyUnicode_Join(PyObject *separator, PyObject *seq)

Return value: New reference. Part of the Stable ABI.

指定した separator で文字列からなるシーケンスを連結 (join) し、連結結果を Unicode 文字列で返します。

Py_ssize_t PyUnicode_Tailmatch(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)

Part of the Stable ABI.

Return 1 if substr matches unicode[start:end] at the given tail end (direction == -1 means to do a prefix match, direction == 1 a suffix match), 0 otherwise. Return -1 if an error occurred.

Py_ssize_t PyUnicode_Find(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)

Part of the Stable ABI.

unicode[start:end] 中に substr が最初に出現する場所を返します。このとき指定された検索方向 direction (direction == 1 は順方向検索、 direction == -1 は逆方向検索) で検索します。戻り値は最初にマッチが見つかった場所のインデックスです; 戻り値 -1 はマッチが見つからなかったことを表し、 -2 はエラーが発生して例外情報が設定されていることを表します。

Py_ssize_t PyUnicode_FindChar(PyObject *unicode, Py_UCS4 ch, Py_ssize_t start, Py_ssize_t end, int direction)

Part of the Stable ABI since version 3.7.

unicode[start:end] 中に文字 ch が最初に出現する場所を返します。このとき指定された検索方向 direction (direction == 1 は順方向検索、 direction == -1 は逆方向検索) で検索します。戻り値は最初にマッチが見つかった場所のインデックスです; 戻り値 -1 はマッチが見つからなかったことを表し、 -2 はエラーが発生して例外情報が設定されていることを表します。

Added in version 3.3.

バージョン 3.7 で変更: start and end are now adjusted to behave like unicode[start:end].

Py_ssize_t PyUnicode_Count(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end)

Part of the Stable ABI.

unicode[start:end] に substr が重複することなく出現する回数を返します。エラーが発生した場合には -1 を返します。

PyObject *PyUnicode_Replace(PyObject *unicode, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)

Return value: New reference. Part of the Stable ABI.

unicode 中に出現する substr を最大で maxcount 個 replstr に置換し、置換結果である Unicode オブジェクトを返します。 maxcount == -1 にすると、文字列中に現れる全ての substr を置換します。

int PyUnicode_Compare(PyObject *left, PyObject *right)

Part of the Stable ABI.

二つの文字列を比較して、左引数が右引数より小さい場合、左右引数が等価の場合、左引数が右引数より大きい場合に対して、それぞれ -1, 0, 1 を返します。

この関数は、失敗したときに -1 を返すので、 PyErr_Occurred() を呼び出して、エラーをチェックすべきです。

int PyUnicode_CompareWithASCIIString(PyObject *unicode, const char *string)

Part of the Stable ABI.

Unicode オブジェクト unicode と string を比較して、左引数が右引数より小さい場合、左右引数が等価の場合、左引数が右引数より大きい場合に対して、それぞれ -1, 0, 1 を返します。 ASCII エンコードされた文字列だけを渡すのが最も良いですが、入力文字列に非 ASCII 文字が含まれている場合は ISO-8859-1 として解釈します。

この関数は例外を送出しません。

PyObject *PyUnicode_RichCompare(PyObject *left, PyObject *right, int op)

Return value: New reference. Part of the Stable ABI.

二つのUnicode文字列を比較して、下のうちの一つを返します:

NULL を、例外が発生したときに返します。

Py_True もしくは Py_False を、正しく比較できた時に返します。

Py_NotImplemented in case the type combination is unknown

Possible values for op are Py_GT, Py_GE, Py_EQ, Py_NE, Py_LT, and Py_LE.

PyObject *PyUnicode_Format(PyObject *format, PyObject *args)

Return value: New reference. Part of the Stable ABI.

新たな文字列オブジェクトを format および args から生成して返します; このメソッドは format % args のようなものです。

int PyUnicode_Contains(PyObject *unicode, PyObject *substr)

Part of the Stable ABI.

substr が unicode 内にあるか調べ、その結果に応じて真または偽を返します。

substr は単要素の Unicode 文字に型強制できなければなりません。エラーが生じた場合には -1 を返します。

void PyUnicode_InternInPlace(PyObject **p_unicode)

Part of the Stable ABI.

Intern the argument *p_unicode in place. The argument must be the address of a pointer variable pointing to a Python Unicode string object. If there is an existing interned string that is the same as *p_unicode, it sets *p_unicode to it (releasing the reference to the old string object and creating a new strong reference to the interned string object), otherwise it leaves *p_unicode alone and interns it (creating a new strong reference). (Clarification: even though there is a lot of talk about references, think of this function as reference-neutral; you own the object after the call if and only if you owned it before the call.)

PyObject *PyUnicode_InternFromString(const char *str)

Return value: New reference. Part of the Stable ABI.

PyUnicode_FromString() と PyUnicode_InternInPlace() を組み合わせたもので、収容済みの新たな文字列オブジェクトを返すか、同じ値を持つ収容済みの Unicode 文字列オブジェクトに対する新たな ("所有権のある") 参照を返します。

タプルオブジェクト (tuple object)

type PyTupleObject

この PyObject のサブタイプは Python のタプルオブジェクトを表現します。

PyTypeObject PyTuple_Type

Part of the Stable ABI.

この PyTypeObject のインスタンスは Python のタプル型を表現します; Python レイヤにおける tuple と同じオブジェクトです。

int PyTuple_Check(PyObject *p)

p がタプルオブジェクトかタプル型のサブタイプのインスタンスである場合に真を返します。この関数は常に成功します。

int PyTuple_CheckExact(PyObject *p)

p がタプルオブジェクトだがタプル型のサブタイプのインスタンスでない場合に真を返します。この関数は常に成功します。

PyObject *PyTuple_New(Py_ssize_t len)

Return value: New reference. Part of the Stable ABI.

サイズが len の新たなタプルオブジェクトを返します。失敗すると NULL を返します。

PyObject *PyTuple_Pack(Py_ssize_t n, ...)

Return value: New reference. Part of the Stable ABI.

サイズが n の新たなタプルオブジェクトを返します。失敗すると NULL を返します。タプルの値は後続の n 個の Python オブジェクトを指す C 引数になります。PyTuple_Pack(2, a, b) は Py_BuildValue("(OO)", a, b) と同じです。

Py_ssize_t PyTuple_Size(PyObject *p)

Part of the Stable ABI.

タプルオブジェクトへのポインタを引数にとり、そのタプルのサイズを返します。

Py_ssize_t PyTuple_GET_SIZE(PyObject *p)

タプル p のサイズを返しますが、p は非 NULL でなくてはならず、タプルオブジェクトを指していなければなりません; この関数はエラーチェックを行いません。

PyObject *PyTuple_GetItem(PyObject *p, Py_ssize_t pos)

Return value: Borrowed reference. Part of the Stable ABI.

p の指すタプルオブジェクト内の、位置 pos にあるオブジェクトを返します。 pos が負であるか範囲を超えている場合、 NULL を返して IndexError 例外をセットします。

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 strong reference, use Py_NewRef(PyTuple_GetItem(...)) or PySequence_GetItem().

PyObject *PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)

Return value: Borrowed reference.

PyTuple_GetItem() に似ていますが、引数に対するエラーチェックを行いません。

PyObject *PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)

Return value: New reference. Part of the Stable ABI.

Return the slice of the tuple pointed to by p between low and high, or NULL on failure. This is the equivalent of the Python expression p[low:high]. Indexing from the end of the tuple is not supported.

int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)

Part of the Stable ABI.

p の指すタプルオブジェクト内の、位置 pos にあるオブジェクトへの参照を入れます。成功すれば 0 を返します。 pos が範囲を超えている場合、 -1 を返して IndexError 例外をセットします。

注釈

この関数は o への参照を "盗み取り" ます。また、変更先のインデクスにすでに別の要素が入っている場合、その要素に対する参照を放棄します。

void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)

PyTuple_SetItem() に似ていますが、エラーチェックを行わず、新たなタプルに値を入れるとき 以外には使ってはなりません 。

注釈

この関数は o への参照を "盗み取り" ます。また、 PyTuple_SetItem() と違って、要素の置き換えが生じても置き換えられるオブジェクトへの参照を放棄 しません ; その結果、タプル中の位置 pos で参照されていたオブジェクトがメモリリークを引き起こします。

int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)

タプルをリサイズする際に使えます。 newsize はタプルの新たな長さです。タプルは変更不能なオブジェクト ということになっている ので、この関数はこのオブジェクトに対してただ一つしか参照がない時以外には使ってはなりません。タプルがコード中の他の部分ですでに参照されている場合には、この関数を 使ってはなりません 。タプルは常に指定サイズの末尾まで伸縮します。成功した場合には 0 を返します。クライアントコードは、 *p の値が呼び出し前と同じになると期待してはなりません。 *p が置き換えられた場合、オリジナルの *p は破壊されます。失敗すると -1 を返し、 *p を NULL に設定して、 MemoryError または SystemError を送出します。

Struct Sequence オブジェクト

struct sequence オブジェクトは namedtuple() オブジェクトと等価なC オブジェクトです。 つまり、その要素に属性を通してアクセスすることができるシーケンスです。 struct sequence を生成するには、まず特定のstruct sequence 型を生成しなければなりません。

PyTypeObject *PyStructSequence_NewType(PyStructSequence_Desc *desc)

Return value: New reference. Part of the Stable ABI.

後述の desc 中のデータから新しい struct sequence 型を生成します。返される型のインスタンスは PyStructSequence_New() で生成できます。

void PyStructSequence_InitType(PyTypeObject *type, PyStructSequence_Desc *desc)

struct sequence 型である type を desc をもとにその場で初期化します。

int PyStructSequence_InitType2(PyTypeObject *type, PyStructSequence_Desc *desc)

PyStructSequence_InitType と同じですが、成功した場合には 0 を、失敗した場合には -1 を返します。

Added in version 3.4.

type PyStructSequence_Desc

Part of the Stable ABI (including all members).

生成するstruct sequence 型のメタデータを保持します。

const char *name

Name of the struct sequence type.

const char *doc

Pointer to docstring for the type or NULL to omit.

PyStructSequence_Field *fields

Pointer to NULL-terminated array with field names of the new type.

int n_in_sequence

Number of fields visible to the Python side (if used as tuple).

type PyStructSequence_Field

Part of the Stable ABI (including all members).

Describes a field of a struct sequence. As a struct sequence is modeled as a tuple, all fields are typed as PyObject*. The index in the fields array of the PyStructSequence_Desc determines which field of the struct sequence is described.

const char *name

Name for the field or NULL to end the list of named fields, set to PyStructSequence_UnnamedField to leave unnamed.

const char *doc

Field docstring or NULL to omit.

const char *const PyStructSequence_UnnamedField

Part of the Stable ABI since version 3.11.

フィールド名を名前がないままするための特殊な値。

バージョン 3.9 で変更: 型が char * から変更されました。

PyObject *PyStructSequence_New(PyTypeObject *type)

Return value: New reference. Part of the Stable ABI.

type のインスタンスを生成します。 type は PyStructSequence_NewType() によって事前に生成していなければなりません。

PyObject *PyStructSequence_GetItem(PyObject *p, Py_ssize_t pos)

Return value: Borrowed reference. Part of the Stable ABI.

Return the object at position pos in the struct sequence pointed to by p. No bounds checking is performed.

PyObject *PyStructSequence_GET_ITEM(PyObject *p, Py_ssize_t pos)

Return value: Borrowed reference.

Macro equivalent of PyStructSequence_GetItem().

void PyStructSequence_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)

Part of the Stable ABI.

struct sequence p の pos の位置にあるフィールドに値 o を設定します。PyTuple_SET_ITEM() のように、生成したてのインスタンスに対してのみ使用すべきです。

注釈

この関数は o への参照を "盗み取り" ます。

void PyStructSequence_SET_ITEM(PyObject *p, Py_ssize_t *pos, PyObject *o)

Similar to PyStructSequence_SetItem(), but implemented as a static inlined function.

注釈

この関数は o への参照を "盗み取り" ます。

リストオブジェクト

type PyListObject

この PyObject のサブタイプは Python のリストオブジェクトを表現します。

PyTypeObject PyList_Type

Part of the Stable ABI.

この PyTypeObject のインスタンスは Python のリスト型を表現します。これは Python レイヤにおける list と同じオブジェクトです。

int PyList_Check(PyObject *p)

p がリストオブジェクトかリスト型のサブタイプのインスタンスである場合に真を返します。この関数は常に成功します。

int PyList_CheckExact(PyObject *p)

p がリストオブジェクトだがリスト型のサブタイプのインスタンスでない場合に真を返します。この関数は常に成功します。

PyObject *PyList_New(Py_ssize_t len)

Return value: New reference. Part of the Stable ABI.

サイズが len 新たなリストオブジェクトを返します。失敗すると NULL を返します。

注釈

len が0より大きいとき、返されるリストオブジェクトの要素には NULL がセットされています。なので、 PyList_SetItem() で本当にオブジェクトをセットするまでは、Pythonコードにこのオブジェクトを渡したり、 PySequence_SetItem() のような抽象APIを利用してはいけません。

Py_ssize_t PyList_Size(PyObject *list)

Part of the Stable ABI.

リストオブジェクト list の長さを返します; リストオブジェクトにおける len(list) と同じです。

Py_ssize_t PyList_GET_SIZE(PyObject *list)

PyList_Size() に似ていますが、エラーチェックを行いません。

PyObject *PyList_GetItem(PyObject *list, Py_ssize_t index)

Return value: Borrowed reference. Part of the Stable ABI.

Return the object at position index in the list pointed to by list. The position must be non-negative; indexing from the end of the list is not supported. If index is out of bounds (<0 or >=len(list)), return NULL and set an IndexError exception.

PyObject *PyList_GET_ITEM(PyObject *list, Py_ssize_t i)

Return value: Borrowed reference.

PyList_GetItem() に似ていますが、エラーチェックを行いません。

int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)

Part of the Stable ABI.

リストオブジェクト内の位置 index に、オブジェクト item を挿入します。成功した場合には 0 を返します。 index が範囲を越えている場合、 -1 を返して IndexError をセットします。

注釈

この関数は item への参照を "盗み取り" ます。また、変更先のインデクスにすでに別の要素が入っている場合、その要素に対する参照を放棄します。

void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)

PyList_SetItem() をマクロによる実装で、エラーチェックを行いません。このマクロは、新たなリストのまだ要素を入れたことのない位置に要素を入れるときにのみ使います。

注釈

このマクロは item への参照を "盗み取り" ます。また、 PyList_SetItem() と違って、要素の置き換えが生じても置き換えられるオブジェクトへの参照を放棄 しません ; その結果、 list 中の位置 i で参照されていたオブジェクトがメモリリークを引き起こします。

int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)

Part of the Stable ABI.

要素 item をリスト list のインデックス index の前に挿入します。成功すると 0 を返します。失敗すると -1 を返し、例外をセットします。list.insert(index, item) に類似した機能です。

int PyList_Append(PyObject *list, PyObject *item)

Part of the Stable ABI.

オブジェクト item を list の末尾に追加します。成功すると 0 を返します; 失敗すると -1 を返し、例外をセットします。list.append(item) に類似した機能です。

PyObject *PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)

Return value: New reference. Part of the Stable ABI.

list 内の、low から high までの オブジェクトからなるリストを返します。失敗すると NULL を返し、例外をセットします。 list[low:high] に類似した機能です。ただし、リストの末尾からのインデックスはサポートされていません。

int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)

Part of the Stable ABI.

low から high までの list のスライスを、 itemlist の内容にします。 list[low:high] = itemlist と類似の機能です。 itemlist は NULL でもよく、空リストの代入 (指定スライスの削除) になります。成功した場合には 0 を、失敗した場合には -1 を返します。ただし、リストの末尾からのインデックスはサポートされていません。

int PyList_Sort(PyObject *list)

Part of the Stable ABI.

list の内容をインプレースでソートします。成功した場合には 0 を、失敗した場合には -1 を返します。list.sort() と同じです。

int PyList_Reverse(PyObject *list)

Part of the Stable ABI.

list の要素をインプレースで反転します。成功した場合には 0 を、失敗した場合には -1 を返します。list.reverse() と同じです。

PyObject *PyList_AsTuple(PyObject *list)

Return value: New reference. Part of the Stable ABI.

list の内容が入った新たなタプルオブジェクトを返します; tuple(list) と同じです。

辞書オブジェクト (dictionary object)

type PyDictObject

この PyObject のサブタイプは Python の辞書オブジェクトを表現します。

PyTypeObject PyDict_Type

Part of the Stable ABI.

この PyTypeObject のインスタンスは Python の辞書を表現します。このオブジェクトは、Python レイヤにおける dict と同じオブジェクトです。

int PyDict_Check(PyObject *p)

p が辞書オブジェクトか辞書型のサブタイプのインスタンスである場合に真を返します。この関数は常に成功します。

int PyDict_CheckExact(PyObject *p)

p が辞書オブジェクトだが辞書型のサブタイプのインスタンスでない場合に真を返します。この関数は常に成功します。

PyObject *PyDict_New()

Return value: New reference. Part of the Stable ABI.

空の新たな辞書を返します。失敗すると NULL を返します。

PyObject *PyDictProxy_New(PyObject *mapping)

Return value: New reference. Part of the Stable ABI.

あるマップ型オブジェクトに対して、読み出し専用に制限された types.MappingProxyType オブジェクトを返します。通常、この関数は動的でないクラス型 (non-dynamic class type) のクラス辞書が変更されないようにビューを作成するために使われます。

void PyDict_Clear(PyObject *p)

Part of the Stable ABI.

現在辞書に入っている全てのキーと値のペアを除去して空にします。

int PyDict_Contains(PyObject *p, PyObject *key)

Part of the Stable ABI.

辞書 p に key が入っているか判定します。p の要素が key に一致した場合は 1 を返し、それ以外の場合には 0 を返します。エラーの場合 -1 を返します。この関数は Python の式 key in p と等価です。

PyObject *PyDict_Copy(PyObject *p)

Return value: New reference. Part of the Stable ABI.

p と同じキーと値のペアが入った新たな辞書を返します。

int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)

Part of the Stable ABI.

辞書 p に、 key をキーとして値 val を挿入します。 key はハッシュ可能(hashable)でなければなりません。ハッシュ可能でない場合、 TypeError を送出します。成功した場合には 0 を、失敗した場合には -1 を返します。この関数は val への参照を盗み取り ません。

int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)

Part of the Stable ABI.

This is the same as PyDict_SetItem(), but key is specified as a const char* UTF-8 encoded bytes string, rather than a PyObject*.

int PyDict_DelItem(PyObject *p, PyObject *key)

Part of the Stable ABI.

辞書 p から key をキーとするエントリを除去します。 key は ハッシュ可能 でなければなりません; ハッシュ可能でない場合、 TypeError を送出します。key が辞書になければ、KeyError を送出します。成功した場合には 0 を、失敗した場合には -1 を返します。

int PyDict_DelItemString(PyObject *p, const char *key)

Part of the Stable ABI.

This is the same as PyDict_DelItem(), but key is specified as a const char* UTF-8 encoded bytes string, rather than a PyObject*.

PyObject *PyDict_GetItem(PyObject *p, PyObject *key)

Return value: Borrowed reference. Part of the Stable ABI.

Return the object from dictionary p which has a key key. Return NULL if the key key is not present, but without setting an exception.

注釈

Exceptions that occur while this calls __hash__() and __eq__() methods are silently ignored. Prefer the PyDict_GetItemWithError() function instead.

バージョン 3.10 で変更: Calling this API without GIL held had been allowed for historical reason. It is no longer allowed.

PyObject *PyDict_GetItemWithError(PyObject *p, PyObject *key)

Return value: Borrowed reference. Part of the Stable ABI.

PyDict_GetItem() の変種で例外を隠しません。例外が発生した場合は、例外をセット した上で NULL を返します。キーが存在しなかった場合は、例外をセット せずに NULL を返します。

PyObject *PyDict_GetItemString(PyObject *p, const char *key)

Return value: Borrowed reference. Part of the Stable ABI.

This is the same as PyDict_GetItem(), but key is specified as a const char* UTF-8 encoded bytes string, rather than a PyObject*.

注釈

Exceptions that occur while this calls __hash__() and __eq__() methods or while creating the temporary str object are silently ignored. Prefer using the PyDict_GetItemWithError() function with your own PyUnicode_FromString() key instead.

PyObject *PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj)

Return value: Borrowed reference.

これは Python レベルの dict.setdefault() と同じです。もしあれば、辞書 p から key に対応する値を返します。キーが辞書になければ、値 defaultobj を挿入し defaultobj を返します。この関数は、 key のハッシュ値を検索と挿入ごとに別々に評価するのではなく、一度だけしか評価しません。

Added in version 3.4.

PyObject *PyDict_Items(PyObject *p)

Return value: New reference. Part of the Stable ABI.

辞書内の全ての要素対が入った PyListObject を返します。

PyObject *PyDict_Keys(PyObject *p)

Return value: New reference. Part of the Stable ABI.

辞書内の全てのキーが入った PyListObject を返します。

PyObject *PyDict_Values(PyObject *p)

Return value: New reference. Part of the Stable ABI.

辞書 p 内の全ての値が入った PyListObject を返します。

Py_ssize_t PyDict_Size(PyObject *p)

Part of the Stable ABI.

辞書内の要素の数を返します。辞書に対して len(p) を実行するのと同じです。

int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)

Part of the Stable ABI.

辞書 p 内の全てのキー/値のペアにわたる反復処理を行います。 ppos が参照している Py_ssize_t 型は、この関数で反復処理を開始する際に、最初に関数を呼び出すよりも前に 0 に初期化しておかなければなりません。この関数は辞書内の各ペアを取り上げるごとに真を返し、全てのペアを取り上げたことが分かると偽を返します。パラメーター pkey および pvalue には、それぞれ辞書の各々のキーと値が埋められた PyObject* 変数を指すポインタか、または NULL が入ります。この関数から返される参照はすべて借用参照になります。反復処理中に ppos を変更してはなりません。この値は内部的な辞書構造体のオフセットを表現しており、構造体はスパースなので、オフセットの値に一貫性がないためです。

例えば:

PyObject *key, *value;
Py_ssize_t pos = 0;

while (PyDict_Next(self->dict, &pos, &key, &value)) {
    /* do something interesting with the values... */
    ...
}

反復処理中に辞書 p を変更してはなりません。辞書を反復処理する際に、キーに対応する値を変更しても大丈夫になりましたが、キーの集合を変更しないことが前提です。以下に例を示します:

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);
}

int PyDict_Merge(PyObject *a, PyObject *b, int override)

Part of the Stable ABI.

マップ型オブジェクト b の全ての要素にわたって、反復的にキー/値のペアを辞書 a に追加します。 b は辞書か、 PyMapping_Keys() または PyObject_GetItem() をサポートする何らかのオブジェクトにできます。 override が真ならば、 a のキーと一致するキーが b にある際に、既存のペアを置き換えます。それ以外の場合は、 b のキーに一致するキーが a にないときのみ追加を行います。成功した場合には 0 を返し、例外が送出された場合には -1 を返します。

int PyDict_Update(PyObject *a, PyObject *b)

Part of the Stable ABI.

C で表せば PyDict_Merge(a, b, 1) と同じで、また Python の a.update(b) と似ていますが、 PyDict_Update() は第二引数が "keys" 属性を持たない場合にキー/値ペアのシーケンスを反復することはありません。成功した場合には 0 を返し、例外が送出された場合には -1 を返します。

int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)

Part of the Stable ABI.

seq2 内のキー/値ペアを使って、辞書 a の内容を更新したり統合したりします。seq2 は、キー/値のペアとみなせる長さ 2 の反復可能オブジェクト(iterable object) を生成する反復可能オブジェクトでなければなりません。重複するキーが存在する場合、override が真ならば先に出現したキーを使い、そうでない場合は後に出現したキーを使います。成功した場合には 0 を返し、例外が送出された場合には -1 を返します。(戻り値以外は) 等価な Python コードを書くと、以下のようになります:

def PyDict_MergeFromSeq2(a, seq2, override):
    for key, value in seq2:
        if override or key not in a:
            a[key] = value

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 PyDict_Watch(). In case of error (e.g. no more watcher IDs available), return -1 and set an exception.

Added in version 3.12.

int PyDict_ClearWatcher(int watcher_id)

Clear watcher identified by watcher_id previously returned from PyDict_AddWatcher(). Return 0 on success, -1 on error (e.g. if the given watcher_id was never registered.)

Added in version 3.12.

int PyDict_Watch(int watcher_id, PyObject *dict)

Mark dictionary dict as watched. The callback granted watcher_id by PyDict_AddWatcher() will be called when dict is modified or deallocated. Return 0 on success or -1 on error.

Added in version 3.12.

int PyDict_Unwatch(int watcher_id, PyObject *dict)

Mark dictionary dict as no longer watched. The callback granted watcher_id by PyDict_AddWatcher() will no longer be called when dict is modified or deallocated. The dict must previously have been watched by this watcher. Return 0 on success or -1 on error.

Added in version 3.12.

type PyDict_WatchEvent

Enumeration of possible dictionary watcher events: PyDict_EVENT_ADDED, PyDict_EVENT_MODIFIED, PyDict_EVENT_DELETED, PyDict_EVENT_CLONED, PyDict_EVENT_CLEARED, or PyDict_EVENT_DEALLOCATED.

Added in version 3.12.

typedef int (*PyDict_WatchCallback)(PyDict_WatchEvent event, PyObject *dict, PyObject *key, PyObject *new_value)

Type of a dict watcher callback function.

If event is PyDict_EVENT_CLEARED or PyDict_EVENT_DEALLOCATED, both key and new_value will be NULL. If event is PyDict_EVENT_ADDED or PyDict_EVENT_MODIFIED, new_value will be the new value for key. If event is PyDict_EVENT_DELETED, key is being deleted from the dictionary and new_value will be NULL.

PyDict_EVENT_CLONED occurs when dict was previously empty and another dict is merged into it. To maintain efficiency of this operation, per-key PyDict_EVENT_ADDED events are not issued in this case; instead a single 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 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 -1; this exception will be printed as an unraisable exception using PyErr_WriteUnraisable(). Otherwise it should return 0.

There may already be a pending exception set on entry to the callback. In this case, the callback should return 0 with the same exception still set. This means the callback may not call any other API that can set an exception unless it saves and clears the exception state first, and restores it before returning.

Added in version 3.12.

Set オブジェクト

このセクションでは set と frozenset の公開 API について詳しく述べます。以降で説明していない機能は、抽象オブジェクトプロトコル (PyObject_CallMethod(), PyObject_RichCompareBool(), PyObject_Hash(), PyObject_Repr(), PyObject_IsTrue(), PyObject_Print(), PyObject_GetIter() を含む) か抽象数値プロトコル (PyNumber_And(), PyNumber_Subtract(), PyNumber_Or(), PyNumber_Xor(), PyNumber_InPlaceAnd(), PyNumber_InPlaceSubtract(), PyNumber_InPlaceOr(), PyNumber_InPlaceXor() を含む) を使って利用できます。

type PySetObject

この PyObject を継承した型は、 set と frozenset 両方の内部データを保存するのに用いられます。 PyDictObject と同じように、小さい集合(set)に対しては(タプルのように)固定サイズであり、そうでない集合に対しては(リストと同じように)可変長のメモリブロックを用います。この構造体のどのフィールドも、公開されていると考えるべきではなく、変更される可能性があります。すべてのアクセスは、構造体の中の値を直接操作するのではなく、ドキュメントされた API を用いて行うべきです。

PyTypeObject PySet_Type

Part of the Stable ABI.

この PyTypeObject のインスタンスは、Python の set 型を表します。

PyTypeObject PyFrozenSet_Type

Part of the Stable ABI.

この PyTypeObject のインスタンスは、Python の frozenset 型を表します。

以降の型チェックマクロはすべての Python オブジェクトに対するポインタに対して動作します。同様に、コンストラクタはすべてのイテレート可能な Python オブジェクトに対して動作します。

int PySet_Check(PyObject *p)

p が set かそのサブタイプのオブジェクトであるときに true を返します。この関数は常に成功します。

int PyFrozenSet_Check(PyObject *p)

p が frozenset かそのサブタイプのオブジェクトであるときに true を返します。この関数は常に成功します。

int PyAnySet_Check(PyObject *p)

p が set か frozenset 、あるいはそのサブタイプのオブジェクトであれば、true を返します。この関数は常に成功します。

int PySet_CheckExact(PyObject *p)

p が set オブジェクトだがサブタイプのインスタンスでない場合に真を返します。この関数は常に成功します。

Added in version 3.10.

int PyAnySet_CheckExact(PyObject *p)

p が set か frozenset のどちらかのオブジェクトであるときに true を返します。サブタイプのオブジェクトは含みません。この関数は常に成功します。

int PyFrozenSet_CheckExact(PyObject *p)

p が frozenset オブジェクトだがサブタイプのインスタンスでない場合に真を返します。この関数は常に成功します。

PyObject *PySet_New(PyObject *iterable)

Return value: New reference. Part of the Stable ABI.

iterable が返すオブジェクトを含む新しい set を返します。 iterable が NULL のときは、空の set を返します。成功したら新しい set を、失敗したら NULL を返します。 iterable がイテレート可能でない場合は、 TypeError を送出します。このコンストラクタは set をコピーするときにも使えます (c=set(s))。

PyObject *PyFrozenSet_New(PyObject *iterable)

Return value: New reference. Part of the Stable ABI.

iterable が返すオブジェクトを含む新しい frozenset を返します。 iterable が NULL のときは、空の frozenset を返します。成功時には新しい set を、失敗時には NULL を返します。 iterable がイテレート可能でない場合は、 TypeError を送出します。

以降の関数やマクロは、 set と frozenset とそのサブタイプのインスタンスに対して利用できます。

Py_ssize_t PySet_Size(PyObject *anyset)

Part of the Stable ABI.

Return the length of a set or frozenset object. Equivalent to len(anyset). Raises a SystemError if anyset is not a set, frozenset, or an instance of a subtype.

Py_ssize_t PySet_GET_SIZE(PyObject *anyset)

エラーチェックを行わない、 PySet_Size() のマクロ形式。

int PySet_Contains(PyObject *anyset, PyObject *key)

Part of the Stable ABI.

Return 1 if found, 0 if not found, and -1 if an error is encountered. Unlike the Python __contains__() method, this function does not automatically convert unhashable sets into temporary frozensets. Raise a TypeError if the key is unhashable. Raise SystemError if anyset is not a set, frozenset, or an instance of a subtype.

int PySet_Add(PyObject *set, PyObject *key)

Part of the Stable ABI.

set のインスタンスに key を追加します。 frozenset に対しても動作します (PyTuple_SetItem() のように、他のコードに見える前の新しい frozenset の値を埋めるために使用できます)。成功したら 0 を、失敗したら -1 を返します。 key がハッシュ可能でない場合は、 TypeError を送出します。 set を大きくする余裕がない場合は、 MemoryError を送出します。 set が set かそのサブタイプのインスタンスでない場合は、 SystemError を送出します。

以降の関数は、 set とそのサブタイプに対して利用可能です。 frozenset とそのサブタイプには利用できません。

int PySet_Discard(PyObject *set, PyObject *key)

Part of the Stable ABI.

Return 1 if found and removed, 0 if not found (no action taken), and -1 if an error is encountered. Does not raise KeyError for missing keys. Raise a TypeError if the key is unhashable. Unlike the Python discard() method, this function does not automatically convert unhashable sets into temporary frozensets. Raise SystemError if set is not an instance of set or its subtype.

PyObject *PySet_Pop(PyObject *set)

Return value: New reference. Part of the Stable ABI.

set の中の要素のどれかに対する新しい参照を返し、そのオブジェクトを set から削除します。失敗したら NULL を返します。 set が空の場合には KeyError を送出します。 set が set とそのサブタイプのインスタンスでない場合は、 SystemError を送出します。

int PySet_Clear(PyObject *set)

Part of the Stable ABI.

Empty an existing set of all elements. Return 0 on success. Return -1 and raise SystemError if set is not an instance of set or its subtype.

Function オブジェクト

Functionオブジェクト固有の関数はわずかです。

type PyFunctionObject

関数に使われるCの構造体。

PyTypeObject PyFunction_Type

PyTypeObject 型のインスタンスで、 Python の関数型を表します。これは Python プログラムに types.FunctionType として公開されています。

int PyFunction_Check(PyObject *o)

o が関数オブジェクト (PyFunction_Type 型である) 場合に真を返します。パラメータは NULL にできません。この関数は常に成功します。

PyObject *PyFunction_New(PyObject *code, PyObject *globals)

Return value: New reference.

コードオブジェクト code に関連付けられた新しい関数オブジェクトを返します。globals はこの関数からアクセスできるグローバル変数の辞書でなければなりません。

関数のドキュメント文字列と名前はコードオブジェクトから取得されます。 __module__ は globals から取得されます。引数のデフォルト値やアノテーション、クロージャは NULL に設定されます。 __qualname__ はコードオブジェクトの co_qualname フィールドと同じ値に設定されます。

PyObject *PyFunction_NewWithQualName(PyObject *code, PyObject *globals, PyObject *qualname)

Return value: New reference.

PyFunction_New() に似ていますが、関数オブジェクトの __qualname__ 属性に値をセットできます。 qualname はユニコードオブジェクトか NULL でなくてはなりません。NULL だった場合、 __qualname__ 属性にはコードオブジェクトの co_qualname フィールドと同じ値がセットされます。

Added in version 3.3.

PyObject *PyFunction_GetCode(PyObject *op)

Return value: Borrowed reference.

関数オブジェクト op に関連付けられたコードオブジェクトを返します。

PyObject *PyFunction_GetGlobals(PyObject *op)

Return value: Borrowed reference.

関数オブジェクト op に関連付けられたglobals辞書を返します。

PyObject *PyFunction_GetModule(PyObject *op)

Return value: Borrowed reference.

Return a borrowed reference to the __module__ attribute of the function object op. It can be NULL.

This is normally a string containing the module name, but can be set to any other object by Python code.

PyObject *PyFunction_GetDefaults(PyObject *op)

Return value: Borrowed reference.

関数オブジェクト op の引数のデフォルト値を返します。引数のタプルか NULL になります。

int PyFunction_SetDefaults(PyObject *op, PyObject *defaults)

関数オブジェクト op の引数のデフォルト値を設定します。 defaults は Py_None かタプルでなければいけません。

失敗した時は、 SystemError を発生させ、 -1 を返します。

void PyFunction_SetVectorcall(PyFunctionObject *func, vectorcallfunc vectorcall)

Set the vectorcall field of a given function object func.

Warning: extensions using this API must preserve the behavior of the unaltered (default) vectorcall function!

Added in version 3.12.

PyObject *PyFunction_GetClosure(PyObject *op)

Return value: Borrowed reference.

関数オブジェクト op に設定されたクロージャを返します。 NULL か cell オブジェクトのタプルです。

int PyFunction_SetClosure(PyObject *op, PyObject *closure)

関数オブジェクト op にクロージャを設定します。 closure は、Py_None もしくは cell オブジェクトのタプルでなければなりません。

失敗した時は、 SystemError を発生させ、 -1 を返します。

PyObject *PyFunction_GetAnnotations(PyObject *op)

Return value: Borrowed reference.

関数オブジェクト op のアノテーションを返します。返り値は修正可能な辞書か NULL になります。

int PyFunction_SetAnnotations(PyObject *op, PyObject *annotations)

関数オブジェクト op のアノテーションを設定します。 annotations は辞書か、Py_None でなければなりません。

失敗した時は、 SystemError を発生させ、 -1 を返します。

int PyFunction_AddWatcher(PyFunction_WatchCallback callback)

Register callback as a function watcher for the current interpreter. Return an ID which may be passed to PyFunction_ClearWatcher(). In case of error (e.g. no more watcher IDs available), return -1 and set an exception.

Added in version 3.12.

int PyFunction_ClearWatcher(int watcher_id)

Clear watcher identified by watcher_id previously returned from PyFunction_AddWatcher() for the current interpreter. Return 0 on success, or -1 and set an exception on error (e.g. if the given watcher_id was never registered.)

Added in version 3.12.

type PyFunction_WatchEvent

Enumeration of possible function watcher events: - PyFunction_EVENT_CREATE - PyFunction_EVENT_DESTROY - PyFunction_EVENT_MODIFY_CODE - PyFunction_EVENT_MODIFY_DEFAULTS - PyFunction_EVENT_MODIFY_KWDEFAULTS

Added in version 3.12.

typedef int (*PyFunction_WatchCallback)(PyFunction_WatchEvent event, PyFunctionObject *func, PyObject *new_value)

Type of a function watcher callback function.

If event is PyFunction_EVENT_CREATE or PyFunction_EVENT_DESTROY then new_value will be NULL. Otherwise, new_value will hold a 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 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 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 -1; this exception will be printed as an unraisable exception using PyErr_WriteUnraisable(). Otherwise it should return 0.

There may already be a pending exception set on entry to the callback. In this case, the callback should return 0 with the same exception still set. This means the callback may not call any other API that can set an exception unless it saves and clears the exception state first, and restores it before returning.

Added in version 3.12.

インスタンスメソッドオブジェクト(Instance Method Objects)

An instance method is a wrapper for a PyCFunction and the new way to bind a PyCFunction to a class object. It replaces the former call PyMethod_New(func, NULL, class).

PyTypeObject PyInstanceMethod_Type

PyTypeObject のインスタンスは Python のインスタンスメソッドの型を表現します。これは Python のプログラムには公開されません。

int PyInstanceMethod_Check(PyObject *o)

o がインスタンスメソッドオブジェクト (PyInstanceMethod_Type 型である) 場合に真を返します。パラメータは NULL にできません。この関数は常に成功します。

PyObject *PyInstanceMethod_New(PyObject *func)

Return value: New reference.

任意の呼び出し可能オブジェクト func を使った新たなインスタンスメソッドオブジェクトを返します。func はインスタンスメソッドが呼び出されたときに呼び出される関数です。

PyObject *PyInstanceMethod_Function(PyObject *im)

Return value: Borrowed reference.

インスタンスメソッド im に関連付けられた関数オブジェクトを返します。

PyObject *PyInstanceMethod_GET_FUNCTION(PyObject *im)

Return value: Borrowed reference.

PyInstanceMethod_Function() のマクロ版で、エラーチェックを行いません。

メソッドオブジェクト

メソッドは関数オブジェクトに束縛されています。メソッドは常にあるユーザー定義のクラスに束縛されているのです。束縛されていないメソッド(クラスオブジェクトに束縛されたメソッド)は利用することができません。

PyTypeObject PyMethod_Type

この PyTypeObject のインスタンスは Python のメソッド型を表現します。このオブジェクトは、 types.MethodType として Python プログラムに公開されています。

int PyMethod_Check(PyObject *o)

o がメソッドオブジェクト (PyMethod_Type 型である) 場合に真を返します。パラメータは NULL にできません。この関数は常に成功します。

PyObject *PyMethod_New(PyObject *func, PyObject *self)

Return value: New reference.

任意の呼び出し可能オブジェクト func とメソッドが束縛されるべきインスタンス self を使った新たなメソッドオブジェクトを返します。関数 func は、メソッドが呼び出された時に呼び出されるオブジェクトです。 self は NULL にできません。

PyObject *PyMethod_Function(PyObject *meth)

Return value: Borrowed reference.

メソッド meth に関連付けられている関数オブジェクトを返します。

PyObject *PyMethod_GET_FUNCTION(PyObject *meth)

Return value: Borrowed reference.

PyMethod_Function() のマクロ版で、エラーチェックを行いません。

PyObject *PyMethod_Self(PyObject *meth)

Return value: Borrowed reference.

メソッド meth に関連付けられたインスタンスを返します。

PyObject *PyMethod_GET_SELF(PyObject *meth)

Return value: Borrowed reference.

PyMethod_Self() のマクロ版で、エラーチェックを行いません。

セルオブジェクト (cell object)

"セル (cell)" オブジェクトは、複数のスコープから参照される変数群を実装するために使われます。セルは各変数について作成され、各々の値を記憶します; この値を参照する各スタックフレームにおけるローカル変数には、そのスタックフレームの外側で同じ値を参照しているセルに対する参照が入ります。セルで表現された値にアクセスすると、セルオブジェクト自体の代わりにセル内の値が使われます。このセルオブジェクトを使った間接参照 (dereference) は、インタプリタによって生成されたバイトコード内でサポートされている必要があります; セルオブジェクトにアクセスした際に、自動的に間接参照は起こりません。上記以外の状況では、セルオブジェクトは役に立たないはずです。

type PyCellObject

セルオブジェクトに使われる C 構造体です。

PyTypeObject PyCell_Type

セルオブジェクトに対応する型オブジェクトです。

int PyCell_Check(PyObject *ob)

ob がセルオブジェクトの場合に真を返します; ob は NULL であってはなりません。この関数は常に成功します。

PyObject *PyCell_New(PyObject *ob)

Return value: New reference.

値 ob の入った新たなセルオブジェクトを生成して返します。引数を NULL にしてもかまいません。

PyObject *PyCell_Get(PyObject *cell)

Return value: New reference.

cell の内容を返します。

PyObject *PyCell_GET(PyObject *cell)

Return value: Borrowed reference.

cell の内容を返しますが、cell が非 NULL かつセルオブジェクトであるかどうかはチェックしません。

int PyCell_Set(PyObject *cell, PyObject *value)

セルオブジェクト cell の内容を value に設定します。この関数は現在のセルの全ての内容に対する参照を解放します。 value は NULL でもかまいません。 cell は非 NULL でなければなりません。cell がセルオブジェクトでない場合、-1 を返します。成功すると 0 を返します。

void PyCell_SET(PyObject *cell, PyObject *value)

セルオブジェクト cell の値を value に設定します。参照カウントに対する変更はなく、安全のためのチェックは何も行いません。cell は非 NULL でなければならず、かつセルオブジェクトでなければなりません。

コードオブジェクト

コードオブジェクト(Code objects)は CPython 実装の低レベルな詳細部分です。各オブジェクトは関数に束縛されていない実行可能コードの塊を表現しています。

type PyCodeObject

コードオブジェクトを表現するために利用されるC構造体。この型のフィールドは何時でも変更され得ます。

PyTypeObject PyCode_Type

This is an instance of PyTypeObject representing the Python code object.

int PyCode_Check(PyObject *co)

Return true if co is a code object. This function always succeeds.

Py_ssize_t PyCode_GetNumFree(PyCodeObject *co)

Return the number of free variables in a code object.

int PyCode_GetFirstFree(PyCodeObject *co)

Return the position of the first free variable in a code object.

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)

これは Unstable API. It may change without warning in minor releases.

Return a new code object. If you need a dummy code object to create a frame, use PyCode_NewEmpty() instead.

Since the definition of the bytecode changes often, calling PyUnstable_Code_New() directly can bind you to a precise Python version.

The many arguments of this function are inter-dependent in complex ways, meaning that subtle changes to values are likely to result in incorrect execution or VM crashes. Use this function only with extreme care.

バージョン 3.11 で変更: Added qualname and exceptiontable parameters.

バージョン 3.12 で変更: Renamed from PyCode_New as part of Unstable C API. The old name is deprecated, but will remain available until the signature changes again.

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)

これは Unstable API. It may change without warning in minor releases.

Similar to PyUnstable_Code_New(), but with an extra "posonlyargcount" for positional-only arguments. The same caveats that apply to PyUnstable_Code_New also apply to this function.

Added in version 3.8: as PyCode_NewWithPosOnlyArgs

バージョン 3.11 で変更: Added qualname and exceptiontable parameters.

バージョン 3.12 で変更: Renamed to PyUnstable_Code_NewWithPosOnlyArgs. The old name is deprecated, but will remain available until the signature changes again.

PyCodeObject *PyCode_NewEmpty(const char *filename, const char *funcname, int firstlineno)

Return value: New reference.

Return a new empty code object with the specified filename, function name, and first line number. The resulting code object will raise an Exception if executed.

int PyCode_Addr2Line(PyCodeObject *co, int byte_offset)

Return the line number of the instruction that occurs on or before byte_offset and ends after it. If you just need the line number of a frame, use PyFrame_GetLineNumber() instead.

For efficiently iterating over the line numbers in a code object, use the API described in PEP 626 [https://peps.python.org/pep-0626/#out-of-process-debuggers-and-profilers].

int PyCode_Addr2Location(PyObject *co, int byte_offset, int *start_line, int *start_column, int *end_line, int *end_column)

Sets the passed int pointers to the source code line and column numbers for the instruction at byte_offset. Sets the value to 0 when information is not available for any particular element.

Returns 1 if the function succeeds and 0 otherwise.

Added in version 3.11.

PyObject *PyCode_GetCode(PyCodeObject *co)

Equivalent to the Python code getattr(co, 'co_code'). Returns a strong reference to a PyBytesObject representing the bytecode in a code object. On error, NULL is returned and an exception is raised.

This PyBytesObject may be created on-demand by the interpreter and does not necessarily represent the bytecode actually executed by CPython. The primary use case for this function is debuggers and profilers.

Added in version 3.11.

PyObject *PyCode_GetVarnames(PyCodeObject *co)

Equivalent to the Python code getattr(co, 'co_varnames'). Returns a new reference to a PyTupleObject containing the names of the local variables. On error, NULL is returned and an exception is raised.

Added in version 3.11.

PyObject *PyCode_GetCellvars(PyCodeObject *co)

Equivalent to the Python code getattr(co, 'co_cellvars'). Returns a new reference to a PyTupleObject containing the names of the local variables that are referenced by nested functions. On error, NULL is returned and an exception is raised.

Added in version 3.11.

PyObject *PyCode_GetFreevars(PyCodeObject *co)

Equivalent to the Python code getattr(co, 'co_freevars'). Returns a new reference to a PyTupleObject containing the names of the free variables. On error, NULL is returned and an exception is raised.

Added in version 3.11.

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 PyCode_ClearWatcher(). In case of error (e.g. no more watcher IDs available), return -1 and set an exception.

Added in version 3.12.

int PyCode_ClearWatcher(int watcher_id)

Clear watcher identified by watcher_id previously returned from PyCode_AddWatcher() for the current interpreter. Return 0 on success, or -1 and set an exception on error (e.g. if the given watcher_id was never registered.)

Added in version 3.12.

type PyCodeEvent

Enumeration of possible code object watcher events: - PY_CODE_EVENT_CREATE - PY_CODE_EVENT_DESTROY

Added in version 3.12.

typedef int (*PyCode_WatchCallback)(PyCodeEvent event, PyCodeObject *co)

Type of a code object watcher callback function.

If event is 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 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 -1; this exception will be printed as an unraisable exception using PyErr_WriteUnraisable(). Otherwise it should return 0.

There may already be a pending exception set on entry to the callback. In this case, the callback should return 0 with the same exception still set. This means the callback may not call any other API that can set an exception unless it saves and clears the exception state first, and restores it before returning.

Added in version 3.12.

Extra information

To support low-level extensions to frame evaluation, such as external just-in-time compilers, it is possible to attach arbitrary extra data to code objects.

These functions are part of the unstable C API tier: this functionality is a CPython implementation detail, and the API may change without deprecation warnings.

Py_ssize_t PyUnstable_Eval_RequestCodeExtraIndex(freefunc free)

これは Unstable API. It may change without warning in minor releases.

Return a new an opaque index value used to adding data to code objects.

You generally call this function once (per interpreter) and use the result with PyCode_GetExtra and PyCode_SetExtra to manipulate data on individual code objects.

If free is not NULL: when a code object is deallocated, free will be called on non-NULL data stored under the new index. Use Py_DecRef() when storing PyObject.

Added in version 3.6: as _PyEval_RequestCodeExtraIndex

バージョン 3.12 で変更: Renamed to PyUnstable_Eval_RequestCodeExtraIndex. The old private name is deprecated, but will be available until the API changes.

int PyUnstable_Code_GetExtra(PyObject *code, Py_ssize_t index, void **extra)

これは Unstable API. It may change without warning in minor releases.

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 NULL and return 0 without setting an exception.

Added in version 3.6: as _PyCode_GetExtra

バージョン 3.12 で変更: Renamed to PyUnstable_Code_GetExtra. The old private name is deprecated, but will be available until the API changes.

int PyUnstable_Code_SetExtra(PyObject *code, Py_ssize_t index, void *extra)

これは Unstable API. It may change without warning in minor releases.

Set the extra data stored under the given index to extra. Return 0 on success. Set an exception and return -1 on failure.

Added in version 3.6: as _PyCode_SetExtra

バージョン 3.12 で変更: Renamed to PyUnstable_Code_SetExtra. The old private name is deprecated, but will be available until the API changes.

ファイルオブジェクト

これらの API は、 Python 2 の組み込みのファイルオブジェクトの C API を最低限エミュレートするためのものです。それらは、標準 C ライブラリでサポートされているバッファ付き I/O (FILE*) に頼るために使われます。 Python 3 では、ファイルとストリームは新しい io モジュールを使用され、そこに OS の低レベルなバッファ付き I/O の上にいくつかの層が定義されています。下で解説されている関数は、それらの新しい API の便利な C ラッパーであり、インタプリタでの内部的なエラー通知に向いています; サードパーティーのコードは代わりに io の API を使うことが推奨されます。

PyObject *PyFile_FromFd(int fd, const char *name, const char *mode, int buffering, const char *encoding, const char *errors, const char *newline, int closefd)

Return value: New reference. Part of the Stable ABI.

既に開かれているファイル fd のファイルディスクリプタから Python のファイルオブジェクトを作成します。引数 name 、 encoding 、 errors 、 newline には、デフォルトの値として NULL が使えます。 buffering には -1 を指定してデフォルトの値を使うことができます。 name は無視されるのですが、後方互換性のために残されています。失敗すると NULL を返します。より包括的な引数の解説は、 io.open() 関数のドキュメントを参照してください。

警告

Python ストリームは自身のバッファリング層を持つため、ファイル記述子のOSレベルのバッファリングと併用すると、様々な問題 (予期せぬデータ順) などを引き起こします。

バージョン 3.2 で変更: name 属性の無視。

int PyObject_AsFileDescriptor(PyObject *p)

Part of the Stable ABI.

p に関連づけられる ファイルディスクリプタを int として返します。オブジェクトが整数なら、その値を返します。 整数でない場合、オブジェクトに fileno() メソッドがあれば呼び出します; このメソッドの返り値は、ファイル記述子の値として返される整数でなければなりません。失敗すると例外を設定して -1 を返します。

PyObject *PyFile_GetLine(PyObject *p, int n)

Return value: New reference. Part of the Stable ABI.

p.readline([n]) と同じで、この関数はオブジェクト p の各行を読み出します。 p はファイルオブジェクトか、 readline() メソッドを持つ何らかのオブジェクトでかまいません。 n が 0 の場合、行の長さに関係なく正確に 1 行だけ読み出します。 n が 0 より大きければ、 n バイト以上のデータは読み出しません; 従って、行の一部だけが返される場合があります。 どちらの場合でも、読み出し後すぐにファイルの終端に到達した場合には空文字列を 返します。 n が 0 より小さければ、長さに関わらず 1 行だけを 読み出しますが、すぐにファイルの終端に到達した場合には EOFError を送出します。

int PyFile_SetOpenCodeHook(Py_OpenCodeHookFunction handler)

io.open_code() の通常の振る舞いを上書きして、そのパラメーターを提供されたハンドラで渡します。

The handler is a function of type:

type Py_OpenCodeHookFunction

PyObject *(*)(PyObject *path, void *userData) と等価で、 path は PyUnicodeObject であることが保証されています。

userData ポインタはフック関数に渡されます。フック関数は別なランタイムから呼び出されるかもしれないので、このポインタは直接 Python の状態を参照すべきではありません。

このフック関数はインポート中に使われることを意図しているため、モジュールが frozen なモジュールであるか sys.modules にある利用可能なモジュールであることが分かっている場合を除いては、フック関数の実行中に新しいモジュールをインポートするのは避けてください。

いったんフック関数が設定されたら、削除や置き換えもできず、後からの PyFile_SetOpenCodeHook() の呼び出しは失敗します。この関数が失敗したときは、インタープリタが初期化されていた場合、 -1 を返して例外をセットします。

この関数は Py_Initialize() より前に呼び出しても安全です。

引数無しで 監査イベント setopencodehook を送出します。

Added in version 3.8.

int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)

Part of the Stable ABI.

オブジェクト obj をファイルオブジェクト p に書き込みます。 flags がサポートするフラグは Py_PRINT_RAW だけです; このフラグを指定すると、オブジェクトに repr() ではなく str() を適用した結果をファイルに書き出します。成功した場合には 0 を返し、失敗すると -1 を返して適切な例外をセットします。

int PyFile_WriteString(const char *s, PyObject *p)

Part of the Stable ABI.

文字列 s をファイルオブジェクト p に書き出します。成功した場合には 0 を返し、失敗すると -1 を返して適切な例外をセットします。

モジュールオブジェクト (module object)

PyTypeObject PyModule_Type

Part of the Stable ABI.

この PyTypeObject のインスタンスは Python のモジュールオブジェクト型を表現します。このオブジェクトは、Python プログラムには types.ModuleType として公開されています。

int PyModule_Check(PyObject *p)

p がモジュールオブジェクトかモジュールオブジェクトのサブタイプであるときに真を返します。この関数は常に成功します。

int PyModule_CheckExact(PyObject *p)

p がモジュールオブジェクトで、かつ PyModule_Type のサブタイプでないときに真を返します。この関数は常に成功します。

PyObject *PyModule_NewObject(PyObject *name)

Return value: New reference. Part of the Stable ABI since version 3.7.

__name__ 属性に name が設定された新しいモジュールオブジェクトを返します。モジュールの __name__, __doc__, __package__, __loader__ 属性に値が入っています (__name__ 以外は全て None です); __file__ 属性に値を入れるのは呼び出し側の責任です。

Added in version 3.3.

バージョン 3.4 で変更: __package__ と __loader__ は None に設定されます。

PyObject *PyModule_New(const char *name)

Return value: New reference. Part of the Stable ABI.

PyModule_NewObject() に似ていますが、 name は Unicode オブジェクトではなく UTF-8 でエンコードされた文字列です。

PyObject *PyModule_GetDict(PyObject *module)

Return value: Borrowed reference. Part of the Stable ABI.

module の名前空間を実装する辞書オブジェクトを返します; このオブジェクトは、モジュールオブジェクトの __dict__ 属性と同じものです。 module がモジュールオブジェクト (もしくはモジュールオブジェクトのサブタイプ) でない場合は、 SystemError が送出され NULL が返されます。

拡張モジュールでは、モジュールの __dict__ を直接操作するよりも、 PyModule_* および PyObject_* 関数を使う方が推奨されます。

PyObject *PyModule_GetNameObject(PyObject *module)

Return value: New reference. Part of the Stable ABI since version 3.7.

module の __name__ の値を返します。モジュールがこの属性を提供していない場合や文字列型でない場合、 SystemError を送出して NULL を返します。

Added in version 3.3.

const char *PyModule_GetName(PyObject *module)

Part of the Stable ABI.

PyModule_GetNameObject() に似ていますが、 'utf-8' でエンコードされた name を返します。

void *PyModule_GetState(PyObject *module)

Part of the Stable ABI.

モジュールの "state"(モジュールを生成したタイミングで確保されるメモリブロックへのポインター) か、なければ NULL を返します。 PyModuleDef.m_size を参照してください。

PyModuleDef *PyModule_GetDef(PyObject *module)

Part of the Stable ABI.

モジュールが作られる元となった PyModuleDef 構造体へのポインタを返します。モジュールが定義によって作られていなかった場合は NULL を返します。

PyObject *PyModule_GetFilenameObject(PyObject *module)

Return value: New reference. Part of the Stable ABI.

module の __file__ 属性をもとに module がロードされたもとのファイル名を返します。もしファイル名が定義されていない場合や、 Unicode 文字列ではない場合、 SystemError を発生させて NULL を返します。それ以外の場合は Unicode オブジェクトへの参照を返します。

Added in version 3.2.

const char *PyModule_GetFilename(PyObject *module)

Part of the Stable ABI.

PyModule_GetFilenameObject() と似ていますが、 'utf-8' でエンコードされたファイル名を返します。

バージョン 3.2 で非推奨: PyModule_GetFilename() raises UnicodeEncodeError on unencodable filenames, use PyModule_GetFilenameObject() instead.

Cモジュールの初期化

通常、モジュールオブジェクトは拡張モジュール (初期化関数をエクスポートしている共有ライブラリ) または組み込まれたモジュール (PyImport_AppendInittab() を使って初期化関数が追加されているモジュール) から作られます。詳細については C および C++ 拡張のビルド または 埋め込まれた Python の拡張 を見てください。

初期化関数は、モジュール定義のインスタンスを PyModule_Create() に渡して出来上がったモジュールオブジェクトを返してもよいですし、もしくは定義構造体そのものを返し"多段階初期化"を要求しても構いません。

type PyModuleDef

Part of the Stable ABI (including all members).

モジュール定義構造体はモジュールオブジェクトを生成するのに必要なすべての情報を保持します。通常は、それぞれのモジュールごとに静的に初期化されたこの型の変数が1つだけ存在します。

PyModuleDef_Base m_base

Always initialize this member to PyModuleDef_HEAD_INIT.

const char *m_name

新しいモジュールの名前。

const char *m_doc

モジュールの docstring。たいてい docstring は PyDoc_STRVAR を利用して生成されます。

Py_ssize_t m_size

モジュールの状態は、静的なグローバルな領域ではなく PyModule_GetState() で取得できるモジュールごとのメモリ領域に保持されていることがあります。これによってモジュールは複数のサブ・インタプリターで安全に使えます。

This memory area is allocated based on m_size on module creation, and freed when the module object is deallocated, after the m_free function has been called, if present.

m_size に -1 を設定すると、そのモジュールはグローバルな状態を持つためにサブ・インタープリターをサポートしていないということになります。

m_size を非負の値に設定すると、モジュールは再初期化でき、その状態のために必要となる追加のメモリ量を指定できるということになります。非負の m_size は多段階初期化で必要になります。

詳細は PEP 3121 [https://peps.python.org/pep-3121/] を参照。

PyMethodDef *m_methods

PyMethodDef で定義される、モジュールレベル関数のテーブルへのポインター。関数が存在しない場合は NULL を設定することが可能。

PyModuleDef_Slot *m_slots

多段階初期化のためのスロット定義の配列で、 {0, NULL} 要素が終端となります。一段階初期化を使うときは、 m_slots は NULL でなければなりません。

バージョン 3.5 で変更: バージョン 3.5 より前は、このメンバは常に NULL に設定されていて、次のものとして定義されていました:

inquiry m_reload

traverseproc m_traverse

GC走査がモジュールオブジェクトを走査する際に呼び出される走査関数。必要ない場合は NULL.

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 (Py_mod_exec function). More precisely, this function is not called if m_size is greater than 0 and the module state (as returned by PyModule_GetState()) is NULL.

バージョン 3.9 で変更: No longer called before the module state is allocated.

inquiry m_clear

GCがこのモジュールオブジェクトをクリアーする時に呼び出されるクリアー関数。必要ない場合は、NULL.

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 (Py_mod_exec function). More precisely, this function is not called if m_size is greater than 0 and the module state (as returned by PyModule_GetState()) is NULL.

Like 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 m_free is called directly.

バージョン 3.9 で変更: No longer called before the module state is allocated.

freefunc m_free

GCがこのモジュールオブジェクトを解放するときに呼び出される関数。必要ない場合は NULL.

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 (Py_mod_exec function). More precisely, this function is not called if m_size is greater than 0 and the module state (as returned by PyModule_GetState()) is NULL.

バージョン 3.9 で変更: No longer called before the module state is allocated.

一段階初期化

モジュールの初期化関数が直接モジュールオブジェクトを生成して返す場合があります。これは"一段階初期化"と呼ばれ、次の2つのモジュール生成関数のどちらか1つを使います:

PyObject *PyModule_Create(PyModuleDef *def)

Return value: New reference.

Create a new module object, given the definition in def. This behaves like PyModule_Create2() with module_api_version set to PYTHON_API_VERSION.

PyObject *PyModule_Create2(PyModuleDef *def, int module_api_version)

Return value: New reference. Part of the Stable ABI.

APIバージョンを module_api_version として def での定義に従って新しいモジュールオブジェクトを生成します。もし指定されたバージョンが実行しているインタープリターのバージョンと異なる場合は、 RuntimeWarning を発生させます。

注釈

ほとんどの場合、この関数ではなく PyModule_Create() を利用するべきです。この関数は、この関数の必要性を理解しているときにだけ利用してください。

モジュールオブジェクトが初期化関数から返される前に、たいていは PyModule_AddObjectRef() などの関数を使ってモジュールオブジェクトにメンバを所属させます。

多段階初期化

An alternate way to specify extensions is to request "multi-phase initialization". Extension modules created this way behave more like Python modules: the initialization is split between the creation phase, when the module object is created, and the execution phase, when it is populated. The distinction is similar to the __new__() and __init__() methods of classes.

Unlike modules created using single-phase initialization, these modules are not singletons: if the sys.modules entry is removed and the module is re-imported, a new module object is created, and the old module is subject to normal garbage collection -- as with Python modules. By default, multiple modules created from the same definition should be independent: changes to one should not affect the others. This means that all state should be specific to the module object (using e.g. using PyModule_GetState()), or its contents (such as the module's __dict__ or individual classes created with PyType_FromSpec()).

多段階初期化を使って生成される全てのモジュールは サブ・インタプリター をサポートすることが求められます。複数のモジュールが独立していることを保証するのには、たいていはこのサポートをするだけで十分です。

多段階初期化を要求するために、初期化関数 (PyInit_modulename) は空でない m_slots を持つ PyModuleDef を返します。これを返す前に、 PyModuleDef インスタンスは次の関数で初期化されなくてはいけません:

PyObject *PyModuleDef_Init(PyModuleDef *def)

Return value: Borrowed reference. Part of the Stable ABI since version 3.5.

モジュール定義が型と参照カウントを正しく報告する、適切に初期化された Python オブジェクトであること保証します。

PyObject* にキャストされた def を返します。エラーが発生した場合 NULL を返します。

Added in version 3.5.

モジュール定義の m_slots メンバは PyModuleDef_Slot 構造体の配列を指さなければなりません:

type PyModuleDef_Slot

int slot

スロット ID で、以下で説明されている利用可能な値から選ばれます。

void *value

スロットの値で、意味はスロット ID に依存します。

Added in version 3.5.

m_slots 配列はID 0 のスロットで終端されていなければなりません。

利用可能なスロットの型は以下です:

Py_mod_create

モジュールオブジェクト自身を生成するために呼ばれる関数を指定します。このスロットの value ポインタは次のシグネチャを持つ関数を指していなくてはいけません:

PyObject *create_module(PyObject *spec, PyModuleDef *def)

PEP 451 [https://peps.python.org/pep-0451/] で定義された ModuleSpec インスタンスと、モジュール定義を受け取る関数です。これは新しいモジュールオブジェクトを返すか、エラーを設定して NULL を返すべきです。

この関数は最小限に留めておくべきです。特に任意のPythonコードを呼び出すべきではなく、同じモジュールをインポートしようとすると無限ループに陥るでしょう。

複数の Py_mod_create スロットを1つのモジュール定義に設定しない方がよいです。

Py_mod_create が設定されていない場合は、インポート機構は PyModule_New() を使って通常のモジュールオブジェクトを生成します。モジュールの名前は定義ではなく spec から取得され、これによって拡張モジュールが動的にモジュール階層における位置を調整できたり、シンボリックリンクを通して同一のモジュール定義を共有しつつ別の名前でインポートできたりします。

返されるオブジェクトが PyModule_Type のインスタンスである必要はありません。インポートに関連する属性の設定と取得ができる限りは、どんな型でも使えます。しかし、 PyModuleDef が NULL でない m_traverse, m_clear, m_free 、もしくはゼロでない m_size 、もしくは Py_mod_create 以外のスロットを持つ場合は、 PyModule_Type インスタンスのみが返されるでしょう。

Py_mod_exec

モジュールを 実行する ときに呼ばれる関数を指定します。これはPythonモジュールのコードを実行するのと同等です: この関数はたいていはクラスと定数をモジュールにします。この関数のシグネチャは以下です:

int exec_module(PyObject *module)

複数の Py_mod_exec スロットが設定されていた場合は、 m_slots 配列に現れた順に処理されていきます。

Py_mod_multiple_interpreters

Specifies one of the following values:

Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED

The module does not support being imported in subinterpreters.

Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED

The module supports being imported in subinterpreters, but only when they share the main interpreter's GIL. (See 拡張モジュールを分離する.)

Py_MOD_PER_INTERPRETER_GIL_SUPPORTED

The module supports being imported in subinterpreters, even when they have their own GIL. (See 拡張モジュールを分離する.)

This slot determines whether or not importing this module in a subinterpreter will fail.

Multiple Py_mod_multiple_interpreters slots may not be specified in one module definition.

If Py_mod_multiple_interpreters is not specified, the import machinery defaults to Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED.

Added in version 3.12.

多段階初期化についてより詳しくは PEP 489 [https://peps.python.org/pep-0489/] を見てください。

低水準モジュール作成関数

以下の関数は、多段階初期化を使うときに裏側で呼び出されます。例えばモジュールオブジェクトを動的に生成するときに、これらの関数を直接使えます。 PyModule_FromDefAndSpec および PyModule_ExecDef のどちらも、呼び出した後にはモジュールが完全に初期化されていなければなりません。

PyObject *PyModule_FromDefAndSpec(PyModuleDef *def, PyObject *spec)

Return value: New reference.

Create a new module object, given the definition in def and the ModuleSpec spec. This behaves like PyModule_FromDefAndSpec2() with module_api_version set to PYTHON_API_VERSION.

Added in version 3.5.

PyObject *PyModule_FromDefAndSpec2(PyModuleDef *def, PyObject *spec, int module_api_version)

Return value: New reference. Part of the Stable ABI since version 3.7.

APIバージョンを module_api_version として、 def と ModuleSpec オブジェクトの spec で定義されたとおりに新しいモジュールオブジェクトを生成します。もし指定されたバージョンが実行しているインタープリターのバージョンと異なる場合は、 RuntimeWarning を発生させます。

注釈

ほとんどの場合、この関数ではなく PyModule_FromDefAndSpec() を利用するべきです。この関数は、この関数の必要性を理解しているときにだけ利用してください。

Added in version 3.5.

int PyModule_ExecDef(PyObject *module, PyModuleDef *def)

Part of the Stable ABI since version 3.7.

def で与えられた任意の実行スロット (Py_mod_exec) を実行します。

Added in version 3.5.

int PyModule_SetDocString(PyObject *module, const char *docstring)

Part of the Stable ABI since version 3.7.

module の docstring を docstring に設定します。この関数は、 PyModuleDef から PyModule_Create もしくは PyModule_FromDefAndSpec を使ってモジュールを生成するときに自動的に呼び出されます。

Added in version 3.5.

int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)

Part of the Stable ABI since version 3.7.

終端が NULL になっている functions 配列にある関数を module に追加します。 PyMethodDef 構造体の個々のエントリについては PyMethodDef の説明を参照してください (モジュールの名前空間が共有されていないので、 C で実装されたモジュールレベル "関数" はたいていモジュールを1つ目の引数として受け取り、 Python クラスのインスタンスメソッドに似た形にします)。この関数は、 PyModuleDef から PyModule_Create もしくは PyModule_FromDefAndSpec を使ってモジュールを生成するときに自動的に呼び出されます。

Added in version 3.5.

サポート関数

モジュールの初期化関数 (一段階初期化を使う場合) 、あるいはモジュールの実行スロットから呼び出される関数 (多段階初期化を使う場合) は次の関数を使うと、モジュールの state の初期化を簡単にできます:

int PyModule_AddObjectRef(PyObject *module, const char *name, PyObject *value)

Part of the Stable ABI since version 3.10.

module にオブジェクトを name として追加します。この関数はモジュールの初期化関数から利用される便利関数です。

On success, return 0. On error, raise an exception and return -1.

Return NULL if value is NULL. It must be called with an exception raised in this case.

使用例:

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;
 }

The example can also be written without checking explicitly if obj is NULL:

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;
 }

Note that Py_XDECREF() should be used instead of Py_DECREF() in this case, since obj can be NULL.

Added in version 3.10.

int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)

Part of the Stable ABI.

Similar to PyModule_AddObjectRef(), but steals a reference to value on success (if it returns 0).

The new PyModule_AddObjectRef() function is recommended, since it is easy to introduce reference leaks by misusing the PyModule_AddObject() function.

注釈

Unlike other functions that steal references, PyModule_AddObject() only releases the reference to value on success.

This means that its return value must be checked, and calling code must Py_DECREF() value manually on error.

使用例:

static int
add_spam(PyObject *module, int value)
{
    PyObject *obj = PyLong_FromLong(value);
    if (obj == NULL) {
        return -1;
    }
    if (PyModule_AddObject(module, "spam", obj) < 0) {
        Py_DECREF(obj);
        return -1;
    }
    // PyModule_AddObject() stole a reference to obj:
    // Py_DECREF(obj) is not needed here
    return 0;
}

The example can also be written without checking explicitly if obj is NULL:

static int
add_spam(PyObject *module, int value)
{
    PyObject *obj = PyLong_FromLong(value);
    if (PyModule_AddObject(module, "spam", obj) < 0) {
        Py_XDECREF(obj);
        return -1;
    }
    // PyModule_AddObject() stole a reference to obj:
    // Py_DECREF(obj) is not needed here
    return 0;
}

Note that Py_XDECREF() should be used instead of Py_DECREF() in this case, since obj can be NULL.

int PyModule_AddIntConstant(PyObject *module, const char *name, long value)

Part of the Stable ABI.

module に整数定数を name として追加します。この便宜関数はモジュールの初期化関数から利用されています。エラーのときには -1 を、成功したときには 0 を返します。

int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)

Part of the Stable ABI.

module に文字列定数を name として追加します。この便利関数はモジュールの初期化関数から利用されています。文字列 value は NULL 終端されていなければなりません。エラーのときには -1 を、成功したときには 0 を返します。

PyModule_AddIntMacro(module, macro)

module に int 定数を追加します。名前と値は macro から取得されます。例えば、 PyModule_AddIntMacro(module, AF_INET) とすると、 AF_INET という名前の int 型定数を AF_INET の値で module に追加します。エラー時には -1 を、成功時には 0 を返します。

PyModule_AddStringMacro(module, macro)

文字列定数を module に追加します。

int PyModule_AddType(PyObject *module, PyTypeObject *type)

Part of the Stable ABI since version 3.10.

Add a type object to module. The type object is finalized by calling internally PyType_Ready(). The name of the type object is taken from the last component of tp_name after dot. Return -1 on error, 0 on success.

Added in version 3.9.

モジュール検索

一段階初期化は、現在のインタプリタのコンテキストから探せるシングルトンのモジュールを生成します。これによって、後からモジュール定義への参照だけでモジュールオブジェクトが取得できます。

多段階初期化を使うと単一の定義から複数のモジュールが作成できるので、これらの関数は多段階初期化を使って作成されたモジュールには使えません。

PyObject *PyState_FindModule(PyModuleDef *def)

Return value: Borrowed reference. Part of the Stable ABI.

現在のインタプリタの def から作られたモジュールオブジェクトを返します。このメソッドの前提条件として、前もって PyState_AddModule() でインタプリタの state にモジュールオブジェクトを連結しておくことを要求します。対応するモジュールオブジェクトが見付からない、もしくは事前にインタプリタの state に連結されていない場合は、 NULL を返します。

int PyState_AddModule(PyObject *module, PyModuleDef *def)

Part of the Stable ABI since version 3.3.

関数に渡されたモジュールオブジェクトを、インタプリタの state に連結します。この関数を使うことで PyState_FindModule() からモジュールオブジェクトにアクセスできるようになります。

一段階初期化を使って作成されたモジュールにのみ有効です。

Python calls PyState_AddModule automatically after importing a module, so it is unnecessary (but harmless) to call it from module initialization code. An explicit call is needed only if the module's own init code subsequently calls 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).

呼び出し側はGILを獲得しなければなりません。

成功したら 0 を、失敗したら -1 を返します。

Added in version 3.3.

int PyState_RemoveModule(PyModuleDef *def)

Part of the Stable ABI since version 3.3.

def から作られたモジュールオブジェクトをインタプリタ state から削除します。成功したら 0 を、失敗したら -1 を返します。

呼び出し側はGILを獲得しなければなりません。

Added in version 3.3.

イテレータオブジェクト (iterator object)

Python では二種類のイテレータオブジェクトを提供しています。一つ目はシーケンスイテレータで、 __getitem__() メソッドをサポートする任意のシーケンスを取り扱います。二つ目は呼び出し可能オブジェクトと番兵 (sentinel value) を扱い、シーケンス内の要素ごとに呼び出し可能オブジェクトを呼び出して、センチネル値が返されたときに反復処理を終了します。

PyTypeObject PySeqIter_Type

Part of the Stable ABI.

PySeqIter_New() や、組み込みシーケンス型に対して 1 引数形式の組み込み関数 iter() を呼び出したときに返される、イテレータオブジェクトの型オブジェクトです。

int PySeqIter_Check(PyObject *op)

op の型が PySeqlter_Type 型の場合に真を返します。この関数は常に成功します。

PyObject *PySeqIter_New(PyObject *seq)

Return value: New reference. Part of the Stable ABI.

一般的なシーケンスオブジェクト seq を扱うイテレータを返します。反復処理は、シーケンスが添字指定操作の際に IndexError を返したときに終了します。

PyTypeObject PyCallIter_Type

Part of the Stable ABI.

PyCallIter_New() や、組み込み関数 iter() の 2 引数形式が返すイテレータオブジェクトの型オブジェクトです。

int PyCallIter_Check(PyObject *op)

op の型が PyCallIter_Type 型の場合に真を返します。この関数は常に成功します。

PyObject *PyCallIter_New(PyObject *callable, PyObject *sentinel)

Return value: New reference. Part of the Stable ABI.

新たなイテレータを返します。最初のパラメタ callable は引数なしで呼び出せる Python の呼び出し可能オブジェクトならなんでもかまいません; callable は、呼び出されるたびに次の反復処理対象オブジェクトを返さなければなりません。生成されたイテレータは、callable が sentinel に等しい値を返すと反復処理を終了します。

デスクリプタオブジェクト (descriptor object)

"デスクリプタ (descriptor)" は、あるオブジェクトのいくつかの属性について記述したオブジェクトです。デスクリプタオブジェクトは型オブジェクトの辞書内にあります。

PyTypeObject PyProperty_Type

Part of the Stable ABI.

組み込みデスクリプタ型の型オブジェクトです。

PyObject *PyDescr_NewGetSet(PyTypeObject *type, struct PyGetSetDef *getset)

Return value: New reference. Part of the Stable ABI.

PyObject *PyDescr_NewMember(PyTypeObject *type, struct PyMemberDef *meth)

Return value: New reference. Part of the Stable ABI.

PyObject *PyDescr_NewMethod(PyTypeObject *type, struct PyMethodDef *meth)

Return value: New reference. Part of the Stable ABI.

PyObject *PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *wrapper, void *wrapped)

Return value: New reference.

PyObject *PyDescr_NewClassMethod(PyTypeObject *type, PyMethodDef *method)

Return value: New reference. Part of the Stable ABI.

int PyDescr_IsData(PyObject *descr)

デスクリプタオブジェクト descr がデータ属性のデスクリプタの場合には非ゼロ値を、メソッドデスクリプタの場合には 0 を返します。descr はデスクリプタオブジェクトでなければなりません。エラーチェックは行いません。

PyObject *PyWrapper_New(PyObject*, PyObject*)

Return value: New reference. Part of the Stable ABI.

スライスオブジェクト (slice object)

PyTypeObject PySlice_Type

Part of the Stable ABI.

スライスオブジェクトの型オブジェクトです。これは、Pythonレイヤにおける slice と同じオブジェクトです。

int PySlice_Check(PyObject *ob)

ob がスライスオブジェクトの場合に真を返します; ob は NULL であってはなりません。この関数は常に成功します。

PyObject *PySlice_New(PyObject *start, PyObject *stop, PyObject *step)

Return value: New reference. Part of the Stable ABI.

指定した値から新たなスライスオブジェクトを返します。パラメタ start, stop, および step はスライスオブジェクトにおける同名の属性として用いられます。これらの値はいずれも NULL にでき、対応する値には None が使われます。新たなオブジェクトをアロケーションできない場合には NULL を返します。

int PySlice_GetIndices(PyObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step)

Part of the Stable ABI.

スライスオブジェクト slice における start, stop, および step のインデクス値を取得します。このときシーケンスの長さを length と仮定します。length よりも大きなインデクスになるとエラーとして扱います。

Returns 0 on success and -1 on error with no exception set (unless one of the indices was not None and failed to be converted to an integer, in which case -1 is returned with an exception set).

おそらく、あなたはこの関数を使いたくないでしょう。

バージョン 3.2 で変更: 以前は、slice 引数の型は PySliceObject* でした。

int PySlice_GetIndicesEx(PyObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step, Py_ssize_t *slicelength)

Part of the Stable ABI.

PySlice_GetIndices() の便利な代替です。 slice における、start, stop および step のインデクス値を取得をします。シーケンスの長さを length 、スライスの長さを slicelength に格納します。境界外のインデクスは通常のスライスと一貫した方法でクリップされます。

成功のときには 0 を、エラーのときには例外をセットして -1 を返します。

注釈

This function is considered not safe for resizable sequences. Its invocation should be replaced by a combination of PySlice_Unpack() and PySlice_AdjustIndices() where

if (PySlice_GetIndicesEx(slice, length, &start, &stop, &step, &slicelength) < 0) {
    // return error
}

is replaced by

if (PySlice_Unpack(slice, &start, &stop, &step) < 0) {
    // return error
}
slicelength = PySlice_AdjustIndices(length, &start, &stop, step);

バージョン 3.2 で変更: 以前は、slice 引数の型は PySliceObject* でした。

バージョン 3.6.1 で変更: If Py_LIMITED_API is not set or set to the value between 0x03050400 and 0x03060000 (not including) or 0x03060100 or higher PySlice_GetIndicesEx() is implemented as a macro using PySlice_Unpack() and PySlice_AdjustIndices(). Arguments start, stop and step are evaluated more than once.

バージョン 3.6.1 で非推奨: If Py_LIMITED_API is set to the value less than 0x03050400 or between 0x03060000 and 0x03060100 (not including) PySlice_GetIndicesEx() is a deprecated function.

int PySlice_Unpack(PyObject *slice, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step)

Part of the Stable ABI since version 3.7.

Extract the start, stop and step data members from a slice object as C integers. Silently reduce values larger than PY_SSIZE_T_MAX to PY_SSIZE_T_MAX, silently boost the start and stop values less than PY_SSIZE_T_MIN to PY_SSIZE_T_MIN, and silently boost the step values less than -PY_SSIZE_T_MAX to -PY_SSIZE_T_MAX.

Return -1 on error, 0 on success.

Added in version 3.6.1.

Py_ssize_t PySlice_AdjustIndices(Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t step)

Part of the Stable ABI since version 3.7.

Adjust start/end slice indices assuming a sequence of the specified length. Out of bounds indices are clipped in a manner consistent with the handling of normal slices.

Return the length of the slice. Always successful. Doesn't call Python code.

Added in version 3.6.1.

Ellipsis オブジェクト

PyObject *Py_Ellipsis

The Python Ellipsis object. This object has no methods. Like Py_None, it is an immortal [https://peps.python.org/pep-0683/]. singleton object.

バージョン 3.12 で変更: Py_Ellipsis is immortal.

memoryview オブジェクト

memoryview オブジェクトは、他のオブジェクトと同じように扱える Python オブジェクトの形をした C 言語レベルの バッファのインターフェース です。

PyObject *PyMemoryView_FromObject(PyObject *obj)

Return value: New reference. Part of the Stable ABI.

バッファインターフェースを提供するオブジェクトからmemoryview オブジェクトを生成します。もし obj が書き込み可能なバッファのエクスポートをサポートするなら、その memoryview オブジェクトは読み書き可能です。そうでなければ読出しのみになるか、エクスポーターの分別にもとづいて読み書きが可能となります。

PyBUF_READ

Flag to request a readonly buffer.

PyBUF_WRITE

Flag to request a writable buffer.

PyObject *PyMemoryView_FromMemory(char *mem, Py_ssize_t size, int flags)

Return value: New reference. Part of the Stable ABI since version 3.7.

mem を配下のバッファとしてmemoryview オブジェクトを作成します。 flags は PyBUF_READ か PyBUF_WRITE のどちらかになります。

Added in version 3.3.

PyObject *PyMemoryView_FromBuffer(const Py_buffer *view)

Return value: New reference. Part of the Stable ABI since version 3.11.

view として与えられたバッファ構造をラップする memoryview オブジェクトを作成します。単なるバイトバッファ向けには、 PyMemoryView_FromMemory() のほうが望ましいです。

PyObject *PyMemoryView_GetContiguous(PyObject *obj, int buffertype, char order)

Return value: New reference. Part of the Stable ABI.

buffer インターフェースを定義しているオブジェクトから ('C' か 'F'ortran の order で) 連続した メモリチャンクへの memoryview オブジェクトを作ります。メモリが連続している場合、 memoryview オブジェクトは元のメモリを参照します。それ以外の場合、メモリはコピーされて、 memoryview オブジェクトは新しい bytes オブジェクトを参照します。

buffertype can be one of PyBUF_READ or PyBUF_WRITE.

int PyMemoryView_Check(PyObject *obj)

obj が memoryview オブジェクトの場合に真を返します。現在のところ、 memoryview のサブクラスの作成は許可されていません。この関数は常に成功します。

Py_buffer *PyMemoryView_GET_BUFFER(PyObject *mview)

書きだされたバッファーの memoryview のプライベート コピーに、ポインターを返します。 mview は memoryview インスタンスでなければなりません; このマクロは型をチェックしないので自前で型チェックしなければならず、それを怠るとクラッシュする恐れがあります。

PyObject *PyMemoryView_GET_BASE(PyObject *mview)

memoryview をエクスポートしているオブジェクトへのポインタを返します。 memoryview が PyMemoryView_FromMemory() か PyMemoryView_FromBuffer() のどちらかで作成されていた場合、 NULL を返します。

弱参照オブジェクト

Python は 弱参照 を第一級オブジェクト (first-class object) としてサポートします。弱参照を直接実装する二種類の固有のオブジェクト型があります。第一は単純な参照オブジェクトで、第二はオリジナルのオブジェクトに対して可能な限りプロキシとして振舞うオブジェクトです。

int PyWeakref_Check(PyObject *ob)

Return true if ob is either a reference or proxy object. This function always succeeds.

int PyWeakref_CheckRef(PyObject *ob)

Return true if ob is a reference object. This function always succeeds.

int PyWeakref_CheckProxy(PyObject *ob)

Return true if ob is a proxy object. This function always succeeds.

PyObject *PyWeakref_NewRef(PyObject *ob, PyObject *callback)

Return value: New reference. Part of the Stable ABI.

Return a weak reference object for the object ob. This will always return a new reference, but is not guaranteed to create a new object; an existing reference object may be returned. The second parameter, callback, can be a callable object that receives notification when ob is garbage collected; it should accept a single parameter, which will be the weak reference object itself. callback may also be None or NULL. If ob is not a weakly referencable object, or if callback is not callable, None, or NULL, this will return NULL and raise TypeError.

PyObject *PyWeakref_NewProxy(PyObject *ob, PyObject *callback)

Return value: New reference. Part of the Stable ABI.

Return a weak reference proxy object for the object ob. This will always return a new reference, but is not guaranteed to create a new object; an existing proxy object may be returned. The second parameter, callback, can be a callable object that receives notification when ob is garbage collected; it should accept a single parameter, which will be the weak reference object itself. callback may also be None or NULL. If ob is not a weakly referencable object, or if callback is not callable, None, or NULL, this will return NULL and raise TypeError.

PyObject *PyWeakref_GetObject(PyObject *ref)

Return value: Borrowed reference. Part of the Stable ABI.

Return the referenced object from a weak reference, ref. If the referent is no longer live, returns Py_None.

注釈

This function returns a borrowed reference to the referenced object. This means that you should always call Py_INCREF() on the object except when it cannot be destroyed before the last usage of the borrowed reference.

PyObject *PyWeakref_GET_OBJECT(PyObject *ref)

Return value: Borrowed reference.

Similar to PyWeakref_GetObject(), but does no error checking.

void PyObject_ClearWeakRefs(PyObject *object)

Part of the Stable ABI.

This function is called by the 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.

カプセル

using-capsules 以下のオブジェクトを使う方法については 拡張モジュールに C API を提供する を参照してください。

Added in version 3.1.

type PyCapsule

この PyObject のサブタイプは、任意の値を表し、C拡張モジュールから Pythonコードを経由して他のC言語のコードに任意の値を(void* ポインタの形で)渡す必要があるときに有用です。あるモジュール内で定義されているC言語関数のポインタを、他のモジュールに渡してそこから呼び出せるようにするためによく使われます。これにより、動的にロードされるモジュールの中の C API に通常の import 機構を通してアクセスすることができます。

type PyCapsule_Destructor

Part of the Stable ABI.

カプセルに対するデストラクタコールバック型. 次のように定義されます:

typedef void (*PyCapsule_Destructor)(PyObject *);

PyCapsule_Destructor コールバックの動作については PyCapsule_New() を参照してください。

int PyCapsule_CheckExact(PyObject *p)

引数が PyCapsule の場合に真を返します。この関数は常に成功します。

PyObject *PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)

Return value: New reference. Part of the Stable ABI.

pointer を格納する PyCapsule を作成します。 pointer 引数は NULL であってはなりません。

失敗した場合、例外を設定して NULL を返します。

name 文字列は NULL か、有効なC文字列へのポインタです。NULL で無い場合、この文字列は少なくともカプセルより長く生存する必要があります。(destructor の中で解放することは許可されています)

destructor が NULL で無い場合、カプセルが削除されるときにそのカプセルを引数として呼び出されます。

このカプセルがモジュールの属性として保存される場合、 name は modulename.attributename と指定されるべきです。こうすると、他のモジュールがそのカプセルを PyCapsule_Import() でインポートすることができます。

void *PyCapsule_GetPointer(PyObject *capsule, const char *name)

Part of the Stable ABI.

カプセルに保存されている pointer を取り出します。失敗した場合は例外を設定して NULL を返します。

The name parameter must compare exactly to the name stored in the capsule. If the name stored in the capsule is NULL, the name passed in must also be NULL. Python uses the C function strcmp() to compare capsule names.

PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)

Part of the Stable ABI.

カプセルに保存されている現在のデストラクタを返します。失敗した場合、例外を設定して NULL を返します。

カプセルは NULL をデストラクタとして持つことができます。従って、戻り値の NULL がエラーを指してない可能性があります。 PyCapsule_IsValid() か PyErr_Occurred() を利用して確認してください。

void *PyCapsule_GetContext(PyObject *capsule)

Part of the Stable ABI.

カプセルに保存されている現在のコンテキスト(context)を返します。失敗した場合、例外を設定して NULL を返します。

カプセルは NULL をコンテキストとして持つことができます。従って、戻り値の NULL がエラーを指してない可能性があります。 PyCapsule_IsValid() か PyErr_Occurred() を利用して確認してください。

const char *PyCapsule_GetName(PyObject *capsule)

Part of the Stable ABI.

カプセルに保存されている現在の name を返します。失敗した場合、例外を設定して NULL を返します。

カプセルは NULL を name として持つことができます。従って、戻り値の NULL がエラーを指してない可能性があります。 PyCapsule_IsValid() か PyErr_Occurred() を利用して確認してください。

void *PyCapsule_Import(const char *name, int no_block)

Part of the Stable ABI.

Import a pointer to a C object from a capsule attribute in a module. The name parameter should specify the full name to the attribute, as in module.attribute. The name stored in the capsule must match this string exactly.

成功した場合、カプセルの内部 ポインタ を返します。失敗した場合、例外を設定して NULL を返します。

バージョン 3.3 で変更: no_block has no effect anymore.

int PyCapsule_IsValid(PyObject *capsule, const char *name)

Part of the Stable ABI.

capsule が有効なカプセルであるかどうかをチェックします。有効な capsule は、非 NULL で、 PyCapsule_CheckExact() をパスし、非 NULL なポインタを格納していて、内部の name が引数 name とマッチします。 (name の比較方法については PyCapsule_GetPointer() を参照)

In other words, if PyCapsule_IsValid() returns a true value, calls to any of the accessors (any function starting with PyCapsule_Get) are guaranteed to succeed.

オブジェクトが有効で name がマッチした場合に非 0 を、それ以外の場合に 0 を返します。この関数は絶対に失敗しません。

int PyCapsule_SetContext(PyObject *capsule, void *context)

Part of the Stable ABI.

capsule 内部のコンテキストポインタを context に設定します。

成功したら 0 を、失敗したら例外を設定して非 0 を返します。

int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)

Part of the Stable ABI.

capsule 内部のデストラクタを destructor に設定します。

成功したら 0 を、失敗したら例外を設定して非 0 を返します。

int PyCapsule_SetName(PyObject *capsule, const char *name)

Part of the Stable ABI.

capsule 内部の name を name に設定します。name が非 NULL のとき、それは capsule よりも長い寿命を持つ必要があります。もしすでに capsule に非 NULL の name が保存されていた場合、それに対する解放は行われません。

成功したら 0 を、失敗したら例外を設定して非 0 を返します。

int PyCapsule_SetPointer(PyObject *capsule, void *pointer)

Part of the Stable ABI.

capsule 内部のポインタを pointer に設定します。pointer は NULL であってはなりません。

成功したら 0 を、失敗したら例外を設定して非 0 を返します。

フレーム (frame) オブジェクト

type PyFrameObject

Part of the Limited API (as an opaque struct).

フレームオブジェクトを記述する際に用いられる、オブジェクトを表す C 構造体です。

There are no public members in this structure.

バージョン 3.11 で変更: The members of this structure were removed from the public C API. Refer to the What's New entry for details.

The PyEval_GetFrame() and PyThreadState_GetFrame() functions can be used to get a frame object.

See also Reflection.

PyTypeObject PyFrame_Type

The type of frame objects. It is the same object as types.FrameType in the Python layer.

バージョン 3.11 で変更: Previously, this type was only available after including <frameobject.h>.

int PyFrame_Check(PyObject *obj)

Return non-zero if obj is a frame object.

バージョン 3.11 で変更: Previously, this function was only available after including <frameobject.h>.

PyFrameObject *PyFrame_GetBack(PyFrameObject *frame)

Get the frame next outer frame.

Return a strong reference, or NULL if frame has no outer frame.

Added in version 3.9.

PyObject *PyFrame_GetBuiltins(PyFrameObject *frame)

Get the frame's f_builtins attribute.

Return a strong reference. The result cannot be NULL.

Added in version 3.11.

PyCodeObject *PyFrame_GetCode(PyFrameObject *frame)

Part of the Stable ABI since version 3.10.

Get the frame code.

Return a strong reference.

The result (frame code) cannot be NULL.

Added in version 3.9.

PyObject *PyFrame_GetGenerator(PyFrameObject *frame)

Get the generator, coroutine, or async generator that owns this frame, or NULL if this frame is not owned by a generator. Does not raise an exception, even if the return value is NULL.

Return a strong reference, or NULL.

Added in version 3.11.

PyObject *PyFrame_GetGlobals(PyFrameObject *frame)

Get the frame's f_globals attribute.

Return a strong reference. The result cannot be NULL.

Added in version 3.11.

int PyFrame_GetLasti(PyFrameObject *frame)

Get the frame's f_lasti attribute.

Returns -1 if frame.f_lasti is None.

Added in version 3.11.

PyObject *PyFrame_GetVar(PyFrameObject *frame, PyObject *name)

Get the variable name of frame.

Return a strong reference to the variable value on success.

Raise NameError and return NULL if the variable does not exist.

Raise an exception and return NULL on error.

name type must be a str.

Added in version 3.12.

PyObject *PyFrame_GetVarString(PyFrameObject *frame, const char *name)

Similar to PyFrame_GetVar(), but the variable name is a C string encoded in UTF-8.

Added in version 3.12.

PyObject *PyFrame_GetLocals(PyFrameObject *frame)

Get the frame's f_locals attribute (dict).

Return a strong reference.

Added in version 3.11.

int PyFrame_GetLineNumber(PyFrameObject *frame)

Part of the Stable ABI since version 3.10.

frame が現在実行している行番号を返します。

Internal Frames

Unless using PEP 523 [https://peps.python.org/pep-0523/], you will not need this.

struct _PyInterpreterFrame

The interpreter's internal frame representation.

Added in version 3.11.

PyObject *PyUnstable_InterpreterFrame_GetCode(struct _PyInterpreterFrame *frame);

これは Unstable API. It may change without warning in minor releases.

Return a strong reference to the code object for the frame.

Added in version 3.12.

int PyUnstable_InterpreterFrame_GetLasti(struct _PyInterpreterFrame *frame);

これは Unstable API. It may change without warning in minor releases.

Return the byte offset into the last executed instruction.

Added in version 3.12.

int PyUnstable_InterpreterFrame_GetLine(struct _PyInterpreterFrame *frame);

これは Unstable API. It may change without warning in minor releases.

Return the currently executing line number, or -1 if there is no line number.

Added in version 3.12.

ジェネレータオブジェクト

ジェネレータオブジェクトは、 Python がジェネレータイテレータを実装するのに使っているオブジェクトです。ジェネレータオブジェクトは通常、 PyGen_New() や PyGen_NewWithQualName() の明示的な呼び出しではなく、値を yield する関数のイテレーションにより生成されます。

type PyGenObject

ジェネレータオブジェクトに使われている C 構造体です。

PyTypeObject PyGen_Type

ジェネレータオブジェクトに対応する型オブジェクトです。

int PyGen_Check(PyObject *ob)

ob がジェネレータオブジェクトの場合に真を返ます、 ob は NULL であってはなりません。この関数は常に成功します。

int PyGen_CheckExact(PyObject *ob)

ob が PyGen_Type の場合に真を返します。 o は NULL であってはなりません。この関数は常に成功します。

PyObject *PyGen_New(PyFrameObject *frame)

Return value: New reference.

frame オブジェクトに基づいて新たなジェネレータオブジェクトを生成して返します。この関数は frame への参照を盗みます。引数が NULL であってはなりません。

PyObject *PyGen_NewWithQualName(PyFrameObject *frame, PyObject *name, PyObject *qualname)

Return value: New reference.

frame オブジェクトから新たなジェネレータオブジェクトを生成し、 __name__ と __qualname__ を name と qualname に設定して返します。この関数は frame への参照を盗みます。 frame 引数は NULL であってはなりません。

コルーチンオブジェクト

Added in version 3.5.

コルーチンオブジェクトは async キーワードを使って定義した関数が返すオブジェクトです。

type PyCoroObject

コルーチンオブジェクトのための C 構造体。

PyTypeObject PyCoro_Type

コルーチンオブジェクトに対応する型オブジェクト。

int PyCoro_CheckExact(PyObject *ob)

ob が PyCoro_Type の場合に真を返します。 ob は NULL であってはなりません。この関数は常に成功します。

PyObject *PyCoro_New(PyFrameObject *frame, PyObject *name, PyObject *qualname)

Return value: New reference.

frame オブジェクトから新しいコルーチンオブジェクトを生成して、 __name__ と __qualname__ を name と qualname に設定して返します。この関数は frame への参照を奪います。 frame 引数は NULL であってはなりません。

コンテキスト変数オブジェクト

Added in version 3.7.

バージョン 3.7.1 で変更:

注釈

Python 3.7.1 で全てのコンテキスト変数の C API のシグネチャは、 PyContext, PyContextVar, PyContextToken の代わりに PyObject ポインタを使うように 変更 されました。例えば:

// in 3.7.0:
PyContext *PyContext_New(void);

// in 3.7.1+:
PyObject *PyContext_New(void);

詳細は bpo-34762 [https://bugs.python.org/issue?@action=redirect&bpo=34762] を参照してください。

この節では、 contextvars モジュールの公開 C API の詳細について説明します。

type PyContext

contextvars.Context オブジェクトを表現するための C 構造体。

type PyContextVar

contextvars.ContextVar オブジェクトを表現するための C 構造体。

type PyContextToken

contextvars.Token オブジェクトを表現するための C 構造体。

PyTypeObject PyContext_Type

コンテキスト 型を表現する型オブジェクト。

PyTypeObject PyContextVar_Type

コンテキスト変数 型を表現する型オブジェクト。

PyTypeObject PyContextToken_Type

コンテキスト変数トークン 型を表現する型オブジェクト。

型チェックマクロ:

int PyContext_CheckExact(PyObject *o)

o が PyContext_Type の場合に真を返します。 o は NULL であってはなりません。この関数は常に成功します。

int PyContextVar_CheckExact(PyObject *o)

o が PyContextVar_Type の場合に真を返します。 o は NULL であってはなりません。この関数は常に成功します。

int PyContextToken_CheckExact(PyObject *o)

o が PyContextToken_Type の場合に真を返します。 o は NULL であってはなりません。この関数は常に成功します。

コンテキストオブジェクトを取り扱う関数:

PyObject *PyContext_New(void)

Return value: New reference.

新しい空のコンテキストオブジェクトを作成します。エラーが起きた場合は NULL を返します。

PyObject *PyContext_Copy(PyObject *ctx)

Return value: New reference.

渡された ctx コンテキストオブジェクトの浅いコピーを作成します。エラーが起きた場合は NULL を返します。

PyObject *PyContext_CopyCurrent(void)

Return value: New reference.

現在のコンテキストオブジェクトの浅いコピーを作成します。エラーが起きた場合は NULL を返します。

int PyContext_Enter(PyObject *ctx)

ctx を現在のスレッドの現在のコンテキストに設定します。成功したら 0 を、失敗したら -1 を返します。

int PyContext_Exit(PyObject *ctx)

ctx コンテキストを無効にし、1 つ前のコンテキストを現在のスレッドの現在のコンテキストに復元します。成功したら 0 を、失敗したら -1 を返します。

コンテキスト変数の関数:

PyObject *PyContextVar_New(const char *name, PyObject *def)

Return value: New reference.

新しい``ContextVar``オブジェクトをさくせいします。name 引数は内部走査とデバッグの目的で使われます。def 引数はコンテキスト変数のデフォルト値を指定するか、デフォルトがない場合は``NULL``です。エラーが起きた場合は、関数は``NULL``を返します。

int PyContextVar_Get(PyObject *var, PyObject *default_value, PyObject **value)

コンテキスト変数の値を取得します。取得中にエラーが起きた場合は -1 を、値が見付かっても見付からなくてもエラーが起きなかった場合は 0 を返します。

コンテキスト変数が見付かった場合、 value はそれを指すポインタになっています。コンテキスト変数が見付から なかった 場合は、 value が指すものは次のようになっています:

(NULL でなければ) default_value

(NULL でなければ) var のデフォルト値

NULL

``NULL``を除けば、この関数は新しい参照を返します。

PyObject *PyContextVar_Set(PyObject *var, PyObject *value)

Return value: New reference.

現在のコンテキストにおいて var の値を value にセットします。この変更による新しいトークンオブジェクトか、エラーが起こった場合は``NULL``を返します。

int PyContextVar_Reset(PyObject *var, PyObject *token)

var コンテキスト変数の状態をリセットし、 token を返した PyContextVar_Set() が呼ばれる前の状態に戻します。この関数は成功したら 0 、失敗したら -1 を返します。

DateTime オブジェクト

datetime モジュールでは、様々な日付オブジェクトや時刻オブジェクトを提供しています。以下に示す関数を使う場合には、あらかじめヘッダファイル datetime.h をソースに include し (Python.h はこのファイルを include しません)、 PyDateTime_IMPORT マクロを、通常はモジュール初期化関数から、起動しておく必要があります。このマクロは以下のマクロで使われる静的変数 PyDateTimeAPI に C 構造体へのポインタを入れます。

type PyDateTime_Date

この PyObject のサブタイプは、Pythonの日付オブジェクトを表します。

type PyDateTime_DateTime

この PyObject のサブタイプは Python の datetime オブジェクトを表します。

type PyDateTime_Time

この PyObject のサブタイプは Python の time オブジェクトを表現します。

type PyDateTime_Delta

この PyObject のサブタイプは二つの datetime の値の差分を表します。

PyTypeObject PyDateTime_DateType

この PyTypeObject のインスタンスは Python の date 型を表します; Python レイヤにおける datetime.date と同じオブジェクトです。

PyTypeObject PyDateTime_DateTimeType

この PyTypeObject のインスタンスは Python の datetime 型を表現します; Python レイヤにおける datetime.datetime と同じオブジェクトです。

PyTypeObject PyDateTime_TimeType

この PyTypeObject のインスタンスは Python の time 型を表します; Python レイヤにおける datetime.time と同じオブジェクトです。

PyTypeObject PyDateTime_DeltaType

This instance of PyTypeObject represents Python type for the difference between two datetime values; it is the same object as datetime.timedelta in the Python layer.

PyTypeObject PyDateTime_TZInfoType

この PyTypeObject のインスタンスは Python の タイムゾーン情報型を表します; Python レイヤにおける datetime.tzinfo と同じオブジェクトです。

UTCシングルトンにアクセスするためのマクロ:

PyObject *PyDateTime_TimeZone_UTC

UTCタイムゾーンに相当するシングルトンを返します。これは datetime.timezone.utc と同じオブジェクトです。

Added in version 3.7.

型チェックマクロ:

int PyDate_Check(PyObject *ob)

ob が PyDateTime_DateType 型か PyDateTime_DateType 型のサブタイプのオブジェクトの場合に真を返します; ob は NULL であってはなりません。この関数は常に成功します。

int PyDate_CheckExact(PyObject *ob)

ob が PyDateTime_DateType の場合に真を返します。 ob は NULL であってはなりません。この関数は常に成功します。

int PyDateTime_Check(PyObject *ob)

ob が PyDateTime_DateTimeType 型か PyDateTime_DateTimeType 型のサブタイプのオブジェクトの場合に真を返します; ob は NULL であってはなりません。この関数は常に成功します。

int PyDateTime_CheckExact(PyObject *ob)

ob が PyDateTime_DateTimeType の場合に真を返します。 ob は NULL であってはなりません。この関数は常に成功します。

int PyTime_Check(PyObject *ob)

ob が PyDateTime_TimeType 型か PyDateTime_TimeType 型のサブタイプのオブジェクトの場合に真を返します; ob は NULL であってはなりません。この関数は常に成功します。

int PyTime_CheckExact(PyObject *ob)

ob が PyDateTime_TimeType の場合に真を返します。 ob は NULL であってはなりません。この関数は常に成功します。

int PyDelta_Check(PyObject *ob)

ob が PyDateTime_DeltaType 型か PyDateTime_DeltaType 型のサブタイプのオブジェクトの場合に真を返します; ob は NULL であってはなりません。この関数は常に成功します。

int PyDelta_CheckExact(PyObject *ob)

ob が PyDateTime_DeltaType の場合に真を返します。 ob は NULL であってはなりません。この関数は常に成功します。

int PyTZInfo_Check(PyObject *ob)

ob が PyDateTime_TZInfoType 型か PyDateTime_TZInfoType 型のサブタイプのオブジェクトの場合に真を返します; ob は NULL であってはなりません。この関数は常に成功します。

int PyTZInfo_CheckExact(PyObject *ob)

ob が PyDateTime_TZInfoType の場合に真を返します。 ob は NULL であってはなりません。この関数は常に成功します。

以下はオブジェクトを作成するためのマクロです:

PyObject *PyDate_FromDate(int year, int month, int day)

Return value: New reference.

指定した年、月、日の datetime.date オブジェクトを返します。

PyObject *PyDateTime_FromDateAndTime(int year, int month, int day, int hour, int minute, int second, int usecond)

Return value: New reference.

指定した年、月、日、時、分、秒、マイクロ秒の datetime.datetime オブジェクトを返します。

PyObject *PyDateTime_FromDateAndTimeAndFold(int year, int month, int day, int hour, int minute, int second, int usecond, int fold)

Return value: New reference.

指定された年、月、日、時、分、秒、マイクロ秒、fold の datetime.datetime オブジェクトを返します。

Added in version 3.6.

PyObject *PyTime_FromTime(int hour, int minute, int second, int usecond)

Return value: New reference.

指定された時、分、秒、マイクロ秒の datetime.time オブジェクトを返します。

PyObject *PyTime_FromTimeAndFold(int hour, int minute, int second, int usecond, int fold)

Return value: New reference.

指定された時、分、秒、マイクロ秒、fold の datetime.time オブジェクトを返します。

Added in version 3.6.

PyObject *PyDelta_FromDSU(int days, int seconds, int useconds)

Return value: New reference.

指定された日、秒、マイクロ秒の datetime.timedelta オブジェクトを返します。マイクロ秒と秒が datetime.timedelta オブジェクトで定義されている範囲に入るように正規化を行います。

PyObject *PyTimeZone_FromOffset(PyObject *offset)

Return value: New reference.

offset 引数で指定した固定オフセットを持つ、名前のない datetime.timezone オブジェクトを返します。

Added in version 3.7.

PyObject *PyTimeZone_FromOffsetAndName(PyObject *offset, PyObject *name)

Return value: New reference.

offset*引数で指定した固定のオフセットと、*name のタイムゾーン名を持つ datetime.timezone オブジェクトを返します。

Added in version 3.7.

以下のマクロは date オブジェクトからフィールド値を取り出すためのものです。引数は PyDateTime_Date またはそのサブクラス (例えば PyDateTime_DateTime)の インスタンスでなければなりません。引数を NULL にしてはならず、型チェックは行いません:

int PyDateTime_GET_YEAR(PyDateTime_Date *o)

年を正の整数で返します。

int PyDateTime_GET_MONTH(PyDateTime_Date *o)

月を 1 から 12 の間の整数で返します。

int PyDateTime_GET_DAY(PyDateTime_Date *o)

日を 1 から 31 の間の整数で返します。

以下のマクロは datetime オブジェクトからフィールド値を取り出すためのものです。引数は PyDateTime_DateTime またはそのサブクラスのインスタンスでなければなりません。引数を NULL にしてはならず、型チェックは行いません:

int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o)

時を 0 から 23 の間の整数で返します。

int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o)

分を 0 から 59 の間の整数で返します。

int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o)

秒を 0 から 59 の間の整数で返します。

int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o)

マイクロ秒を 0 から 999999 の間の整数で返します。

int PyDateTime_DATE_GET_FOLD(PyDateTime_DateTime *o)

フォールド(訳注: サマータイムによる時間のずれのこと)を 0 から 1 までの整数で返します。

Added in version 3.6.

PyObject *PyDateTime_DATE_GET_TZINFO(PyDateTime_DateTime *o)

Return the tzinfo (which may be None).

Added in version 3.10.

以下のマクロは time オブジェクトからフィールド値を取り出すためのものです。引数は PyDateTime_Time またはそのサブクラスのインスタンスでなければなりません。引数を NULL にしてはならず、型チェックは行いません:

int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o)

時を 0 から 23 の間の整数で返します。

int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o)

分を 0 から 59 の間の整数で返します。

int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o)

秒を 0 から 59 の間の整数で返します。

int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o)

マイクロ秒を 0 から 999999 の間の整数で返します。

int PyDateTime_TIME_GET_FOLD(PyDateTime_Time *o)

フォールド(訳注: サマータイムによる時間のずれのこと)を 0 から 1 までの整数で返します。

Added in version 3.6.

PyObject *PyDateTime_TIME_GET_TZINFO(PyDateTime_Time *o)

Return the tzinfo (which may be None).

Added in version 3.10.

以下のマクロは time delta オブジェクトからフィールド値をとりだすためのものです。引数は PyDateTime_Delta かそのサブクラスのインスタンスでなければなりません。引数を NULL にしてはならず、型チェックは行いません:

int PyDateTime_DELTA_GET_DAYS(PyDateTime_Delta *o)

日数を -999999999 から 999999999 の間の整数で返します。

Added in version 3.3.

int PyDateTime_DELTA_GET_SECONDS(PyDateTime_Delta *o)

秒数を 0 から 86399 の間の整数で返します。

Added in version 3.3.

int PyDateTime_DELTA_GET_MICROSECONDS(PyDateTime_Delta *o)

マイクロ秒を 0 から 999999 の間の整数で返します。

Added in version 3.3.

以下のマクロは DB API を実装する上での便宜用です:

PyObject *PyDateTime_FromTimestamp(PyObject *args)

Return value: New reference.

datetime.datetime.fromtimestamp() に渡すのに適した引数タプルから新たな datetime.datetime オブジェクトを生成して返します。

PyObject *PyDate_FromTimestamp(PyObject *args)

Return value: New reference.

datetime.date.fromtimestamp() に渡すのに適した引数タプルから新たな datetime.date オブジェクトを生成して返します。

型ヒントのためのオブジェクト

Various built-in types for type hinting are provided. Currently, two types exist -- GenericAlias and Union. Only GenericAlias is exposed to C.

PyObject *Py_GenericAlias(PyObject *origin, PyObject *args)

Part of the Stable ABI since version 3.9.

GenericAlias オブジェクトを生成します。Pythonクラス types.GenericAlias を呼び出すことと同等です。引数 origin と args は GenericAlias の __origin__ および __args__ 属性をそれぞれ設定します。 origin は PyTypeObject* でなければならず、 args は PyTupleObject* または任意の PyObject* です。 args がタプルでない場合には1タプルが自動的に生成され、__args__ には (args,) が設定されます。引数チェックは最小限なため、たとえ origin が型を示すオブジェクトでなくても関数呼び出しは成功します。GenericAlias の __parameters__ 属性は __args__ から必要に応じて遅延生成されます。失敗した場合、例外が送出されて NULL を返します。

以下は拡張の型をジェネリックにする例です。

...
static PyMethodDef my_obj_methods[] = {
    // Other methods.
    ...
    {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, "See PEP 585"}
    ...
}

参考

The data model method __class_getitem__().

Added in version 3.9.

PyTypeObject Py_GenericAliasType

Part of the Stable ABI since version 3.9.

Py_GenericAlias() により返されるCの型オブジェクトです。Pythonの types.GenericAlias と同等です。

Added in version 3.9.

初期化 (initialization)、終了処理 (finalization)、スレッド

Python 初期化設定 も参照してください。

Python 初期化以前

Python が埋め込まれているアプリケーションでは、他の Python/C API 関数を使う前に Py_Initialize() 関数を呼ばなければなりません。これには例外として、いくつかの関数と グローバルな設定変数 があります。

次の関数は Python の初期化の前でも安全に呼び出せます:

設定関数:

PyImport_AppendInittab()

PyImport_ExtendInittab()

PyInitFrozenExtensions()

PyMem_SetAllocator()

PyMem_SetupDebugHooks()

PyObject_SetArenaAllocator()

Py_SetPath()

Py_SetProgramName()

Py_SetPythonHome()

Py_SetStandardStreamEncoding()

PySys_AddWarnOption()

PySys_AddXOption()

PySys_ResetWarnOptions()

情報取得の関数:

Py_IsInitialized()

PyMem_GetAllocator()

PyObject_GetArenaAllocator()

Py_GetBuildInfo()

Py_GetCompiler()

Py_GetCopyright()

Py_GetPlatform()

Py_GetVersion()

ユーティリティ:

Py_DecodeLocale()

メモリアロケータ:

PyMem_RawMalloc()

PyMem_RawRealloc()

PyMem_RawCalloc()

PyMem_RawFree()

注釈

次の関数は Py_Initialize() より前に 呼び出すべき ではありません : Py_EncodeLocale(), Py_GetPath(), Py_GetPrefix(), Py_GetExecPrefix(), Py_GetProgramFullPath(), Py_GetPythonHome(), Py_GetProgramName(), PyEval_InitThreads() 。

グローバルな設定変数

Python には、様々な機能やオプションを制御するグローバルな設定のための変数があります。デフォルトでは、これらのフラグは コマンドラインオプション で制御されます。

オプションでフラグがセットされると、フラグの値はそのオプションがセットされた回数になります。例えば、 -b では Py_BytesWarningFlag が 1 に設定され、 -bb では Py_BytesWarningFlag が 2 に設定されます。

int Py_BytesWarningFlag

This API is kept for backward compatibility: setting PyConfig.bytes_warning should be used instead, see Python Initialization Configuration.

bytes または bytearray を str と比較した場合、または、 bytes を int と比較した場合に警告を発生させます。 2 以上の値を設定している場合は、エラーを発生させます。

-b オプションで設定します。

バージョン 3.12 で非推奨.

int Py_DebugFlag

This API is kept for backward compatibility: setting PyConfig.parser_debug should be used instead, see Python Initialization Configuration.

パーサーのデバッグ出力を有効にします。(専門家専用です。コンパイルオプションに依存します)。

-d オプションと PYTHONDEBUG 環境変数で設定します。

バージョン 3.12 で非推奨.

int Py_DontWriteBytecodeFlag

This API is kept for backward compatibility: setting PyConfig.write_bytecode should be used instead, see Python Initialization Configuration.

非ゼロに設定した場合、Python はソースモジュールのインポート時に .pyc ファイルの作成を試みません。

-B オプションと PYTHONDONTWRITEBYTECODE 環境変数で設定します。

バージョン 3.12 で非推奨.

int Py_FrozenFlag

This API is kept for backward compatibility: setting PyConfig.pathconfig_warnings should be used instead, see Python Initialization Configuration.

Py_GetPath() の中でモジュール検索パスを割り出しているときのエラーメッセージを抑制します。

_freeze_module プログラムと frozenmain プログラムが使用する非公開フラグです。

バージョン 3.12 で非推奨.

int Py_HashRandomizationFlag

This API is kept for backward compatibility: setting PyConfig.hash_seed and PyConfig.use_hash_seed should be used instead, see Python Initialization Configuration.

PYTHONHASHSEED 環境変数が空でない文字列に設定された場合に、 1 が設定されます。

フラグがゼロでない場合、 PYTHONHASHSEED 環境変数を読みシークレットハッシュシードを初期化します。

バージョン 3.12 で非推奨.

int Py_IgnoreEnvironmentFlag

This API is kept for backward compatibility: setting PyConfig.use_environment should be used instead, see Python Initialization Configuration.

Ignore all PYTHON* environment variables, e.g. PYTHONPATH and PYTHONHOME, that might be set.

-E オプションと -I オプションで設定します。

バージョン 3.12 で非推奨.

int Py_InspectFlag

This API is kept for backward compatibility: setting PyConfig.inspect should be used instead, see Python Initialization Configuration.

最初の引数にスクリプトが指定されたときや -c オプションが利用された際に、 sys.stdin がターミナルに出力されないときであっても、スクリプトかコマンドを実行した後にインタラクティブモードに入ります。

-i オプションと PYTHONINSPECT 環境変数で設定します。

バージョン 3.12 で非推奨.

int Py_InteractiveFlag

This API is kept for backward compatibility: setting PyConfig.interactive should be used instead, see Python Initialization Configuration.

-i オプションで設定します。

バージョン 3.12 で非推奨.

int Py_IsolatedFlag

This API is kept for backward compatibility: setting PyConfig.isolated should be used instead, see Python Initialization Configuration.

Python を隔離モードで実行します。隔離モードでは sys.path はスクリプトのディレクトリやユーザのサイトパッケージのディレクトリを含みません。

-I オプションで設定します。

Added in version 3.4.

バージョン 3.12 で非推奨.

int Py_LegacyWindowsFSEncodingFlag

This API is kept for backward compatibility: setting PyPreConfig.legacy_windows_fs_encoding should be used instead, see Python Initialization Configuration.

If the flag is non-zero, use the mbcs encoding with replace error handler, instead of the UTF-8 encoding with surrogatepass error handler, for the filesystem encoding and error handler.

PYTHONLEGACYWINDOWSFSENCODING 環境変数が空でない文字列に設定された場合に、 1 に設定されます。

より詳しくは PEP 529 [https://peps.python.org/pep-0529/] を参照してください。

利用可能な環境: Windows 。

バージョン 3.12 で非推奨.

int Py_LegacyWindowsStdioFlag

This API is kept for backward compatibility: setting PyConfig.legacy_windows_stdio should be used instead, see Python Initialization Configuration.

If the flag is non-zero, use io.FileIO instead of io._WindowsConsoleIO for sys standard streams.

PYTHONLEGACYWINDOWSSTDIO 環境変数が空でない文字列に設定された場合に、 1 に設定されます。

より詳しくは PEP 528 [https://peps.python.org/pep-0528/] を参照してください。

利用可能な環境: Windows 。

バージョン 3.12 で非推奨.

int Py_NoSiteFlag

This API is kept for backward compatibility: setting PyConfig.site_import should be used instead, see Python Initialization Configuration.

site モジュールの import と、そのモジュールが行なっていた site ごとの sys.path への操作を無効にします。後で site を明示的に import しても、これらの操作は実行されません (実行したい場合は、 site.main() を呼び出してください)。

-S オプションで設定します。

バージョン 3.12 で非推奨.

int Py_NoUserSiteDirectory

This API is kept for backward compatibility: setting PyConfig.user_site_directory should be used instead, see Python Initialization Configuration.

ユーザのサイトパッケージのディレクトリ を sys.path に追加しません。

-s オプション、 -I 、 PYTHONNOUSERSITE 環境変数で設定します。

バージョン 3.12 で非推奨.

int Py_OptimizeFlag

This API is kept for backward compatibility: setting PyConfig.optimization_level should be used instead, see Python Initialization Configuration.

-O オプションと PYTHONOPTIMIZE 環境変数で設定します。

バージョン 3.12 で非推奨.

int Py_QuietFlag

This API is kept for backward compatibility: setting PyConfig.quiet should be used instead, see Python Initialization Configuration.

インタラクティブモードでも copyright とバージョンのメッセージを表示しません。

-q オプションで設定します。

Added in version 3.2.

バージョン 3.12 で非推奨.

int Py_UnbufferedStdioFlag

This API is kept for backward compatibility: setting PyConfig.buffered_stdio should be used instead, see Python Initialization Configuration.

標準出力と標準エラーをバッファリングしないように強制します。

-u オプションと PYTHONUNBUFFERED 環境変数で設定します。

バージョン 3.12 で非推奨.

int Py_VerboseFlag

This API is kept for backward compatibility: setting PyConfig.verbose should be used instead, see Python Initialization Configuration.

モジュールが初期化されるたびにメッセージを出力し、それがどこ (ファイル名やビルトインモジュール) からロードされたのかを表示します。値が 2 以上の場合は、モジュールを検索するときにチェックしたファイルごとにメッセージを出力します。また、終了時のモジュールクリーンアップに関する情報も提供します。

-v オプションと PYTHONVERBOSE 環境変数で設定します。

バージョン 3.12 で非推奨.

インタープリタの初期化と終了処理

void Py_Initialize()

Part of the Stable ABI.

Python インタープリタを初期化します。 Python の埋め込みを行うアプリケーションでは、他のあらゆる Python/C API を使用するよりも前にこの関数を呼び出さなければなりません。いくつかの例外については Python 初期化以前 を参照してください。

This initializes the table of loaded modules (sys.modules), and creates the fundamental modules builtins, __main__ and sys. It also initializes the module search path (sys.path). It does not set sys.argv; use PySys_SetArgvEx() for that. This is a no-op when called for a second time (without calling Py_FinalizeEx() first). There is no return value; it is a fatal error if the initialization fails.

Use the Py_InitializeFromConfig() function to customize the Python Initialization Configuration.

注釈

Windows では O_TEXT から O_BINARY へコンソールモードが変更されますが、これはその C ランタイムを使っているコンソールでの Python 以外の使い勝手にも影響を及ぼします。

void Py_InitializeEx(int initsigs)

Part of the Stable ABI.

initsigs に 1 を指定した場合、この関数は Py_Initialize() と同じように動作します。 initsigs に 0 を指定した場合、初期化時のシグナルハンドラの登録をスキップすることができ、これは Python の埋め込みで便利でしょう。

Use the Py_InitializeFromConfig() function to customize the Python Initialization Configuration.

int Py_IsInitialized()

Part of the Stable ABI.

Python インタプリタが初期化済みであれば真(非ゼロ)を、さもなければ偽(ゼロ)を返します。Py_FinalizeEx() を呼び出した後は、Py_Initialize() を再び呼び出すまで、この関数は偽を返します。

int Py_FinalizeEx()

Part of the Stable ABI since version 3.6.

Py_Initialize() とそれ以後の Python/C API 関数で行った全ての初期化処理を取り消し、最後の Py_Initialize() 呼び出し以後に Python インタプリタが生成した全てのサブインタプリタ (sub-interpreter, 下記の Py_NewInterpreter() を参照) を消去します。理想的な状況では、この関数によって Python インタプリタが確保したメモリは全て解放されます。この関数を (Py_Initialize() を呼ばずに) 再度呼び出しても何も行いません。通常は返り値は 0 です。終了処理中 (バッファリングされたデータの書き出し) のエラーがあった場合は -1 が返されます。

この関数が提供されている理由はいくつかあります。Python の埋め込みを行っているアプリケーションでは、アプリケーションを再起動することなく Python を再起動したいことがあります。また、動的ロード可能イブラリ (あるいは DLL) から Python インタプリタをロードするアプリケーションでは、DLL をアンロードする前に Python が確保したメモリを全て解放したいと考えるかもしれません。アプリケーション内で起きているメモリリークを追跡する際に、開発者は Python が確保したメモリをアプリケーションの終了前に解放させたいと思う場合もあります。

Bugs and caveats: The destruction of modules and objects in modules is done in random order; this may cause destructors (__del__() methods) to fail when they depend on other objects (even functions) or modules. Dynamically loaded extension modules loaded by Python are not unloaded. Small amounts of memory allocated by the Python interpreter may not be freed (if you find a leak, please report it). Memory tied up in circular references between objects is not freed. Some memory allocated by extension modules may not be freed. Some extensions may not work properly if their initialization routine is called more than once; this can happen if an application calls Py_Initialize() and Py_FinalizeEx() more than once.

引数無しで 監査イベント cpython._PySys_ClearAuditHooks を送出します。

Added in version 3.6.

void Py_Finalize()

Part of the Stable ABI.

この関数は Py_FinalizeEx() の後方互換性バージョンで、戻り値がありません。

プロセスワイドのパラメータ

int Py_SetStandardStreamEncoding(const char *encoding, const char *errors)

This API is kept for backward compatibility: setting PyConfig.stdio_encoding and PyConfig.stdio_errors should be used instead, see Python Initialization Configuration.

This function should be called before Py_Initialize(), if it is called at all. It specifies which encoding and error handling to use with standard IO, with the same meanings as in str.encode().

It overrides PYTHONIOENCODING values, and allows embedding code to control IO encoding when the environment variable does not work.

encoding and/or errors may be NULL to use PYTHONIOENCODING and/or default values (depending on other settings).

Note that sys.stderr always uses the "backslashreplace" error handler, regardless of this (or any other) setting.

If Py_FinalizeEx() is called, this function will need to be called again in order to affect subsequent calls to Py_Initialize().

Returns 0 if successful, a nonzero value on error (e.g. calling after the interpreter has already been initialized).

Added in version 3.4.

バージョン 3.11 で非推奨.

void Py_SetProgramName(const wchar_t *name)

Part of the Stable ABI.

This API is kept for backward compatibility: setting PyConfig.program_name should be used instead, see Python Initialization Configuration.

この関数を呼び出すなら、最初に Py_Initialize() を呼び出すよりも前に呼び出さなければなりません。この関数はインタプリタにプログラムの main() 関数に指定した argv[0] 引数の値を教えます (ワイドキャラクタに変換されます)。この引数値は、 Py_GetPath() や、以下に示すその他の関数が、インタプリタの実行可能形式から Python ランタイムライブラリへの相対パスを取得するために使われます。デフォルトの値は 'python' です。引数はゼロ終端されたワイドキャラクタ文字列で、静的な記憶領域に入っていなければならず、その内容はプログラムの実行中に変更してはなりません。 Python インタプリタ内のコードで、この記憶領域の内容を変更するものは一切ありません。

Use Py_DecodeLocale() to decode a bytes string to get a wchar_t* string.

バージョン 3.11 で非推奨.

wchar_t *Py_GetProgramName()

Part of the Stable ABI.

Return the program name set with Py_SetProgramName(), or the default. The returned string points into static storage; the caller should not modify its value.

This function should not be called before Py_Initialize(), otherwise it returns NULL.

バージョン 3.10 で変更: It now returns NULL if called before Py_Initialize().

wchar_t *Py_GetPrefix()

Part of the Stable ABI.

Return the prefix for installed platform-independent files. This is derived through a number of complicated rules from the program name set with Py_SetProgramName() and some environment variables; for example, if the program name is '/usr/local/bin/python', the prefix is '/usr/local'. The returned string points into static storage; the caller should not modify its value. This corresponds to the prefix variable in the top-level Makefile and the --prefix argument to the configure script at build time. The value is available to Python code as sys.prefix. It is only useful on Unix. See also the next function.

This function should not be called before Py_Initialize(), otherwise it returns NULL.

バージョン 3.10 で変更: It now returns NULL if called before Py_Initialize().

wchar_t *Py_GetExecPrefix()

Part of the Stable ABI.

Return the exec-prefix for installed platform-dependent files. This is derived through a number of complicated rules from the program name set with Py_SetProgramName() and some environment variables; for example, if the program name is '/usr/local/bin/python', the exec-prefix is '/usr/local'. The returned string points into static storage; the caller should not modify its value. This corresponds to the exec_prefix variable in the top-level Makefile and the --exec-prefix argument to the configure script at build time. The value is available to Python code as sys.exec_prefix. It is only useful on Unix.

背景: プラットフォーム依存のファイル (実行形式や共有ライブラリ) が別のディレクトリツリー内にインストールされている場合、 exec-prefix は prefix と異なります。典型的なインストール形態では、プラットフォーム非依存のファイルが /usr/local に収められる一方、プラットフォーム依存のファイルは /usr/local/plat サブツリーに収められます。

一般的に、プラットフォームとは、ハードウェアとソフトウェアファミリの組み合わせを指します。例えば、Solaris 2.x を動作させている Sparc マシンは全て同じプラットフォームであるとみなしますが、Solaris 2.x を動作させている Intel マシンは違うプラットフォームになりますし、同じ Intel マシンでも Linux を動作させているならまた別のプラットフォームです。一般的には、同じオペレーティングシステムでも、メジャーリビジョンの違うものは異なるプラットフォームです。非 Unix のオペレーティングシステムの場合は話はまた別です; 非 Unix のシステムでは、インストール方法はとても異なっていて、prefix や exec-prefix には意味がなく、空文字列が設定されています。コンパイル済みの Python バイトコードはプラットフォームに依存しないので注意してください (ただし、どのバージョンの Python でコンパイルされたかには依存します!)。

システム管理者は、 mount や automount プログラムを使って、各プラットフォーム用の /usr/local/plat を異なったファイルシステムに置き、プラットフォーム間で /usr/local を共有するための設定方法を知っているでしょう。

This function should not be called before Py_Initialize(), otherwise it returns NULL.

バージョン 3.10 で変更: It now returns NULL if called before Py_Initialize().

wchar_t *Py_GetProgramFullPath()

Part of the Stable ABI.

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 Py_SetProgramName() above). The returned string points into static storage; the caller should not modify its value. The value is available to Python code as sys.executable.

This function should not be called before Py_Initialize(), otherwise it returns NULL.

バージョン 3.10 で変更: It now returns NULL if called before Py_Initialize().

wchar_t *Py_GetPath()

Part of the Stable ABI.

Return the default module search path; this is computed from the program name (set by Py_SetProgramName() above) 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 ':' on Unix and macOS, ';' on Windows. The returned string points into static storage; the caller should not modify its value. The list sys.path is initialized with this value on interpreter startup; it can be (and usually is) modified later to change the search path for loading modules.

This function should not be called before Py_Initialize(), otherwise it returns NULL.

バージョン 3.10 で変更: It now returns NULL if called before Py_Initialize().

void Py_SetPath(const wchar_t*)

Part of the Stable ABI since version 3.7.

This API is kept for backward compatibility: setting PyConfig.module_search_paths and PyConfig.module_search_paths_set should be used instead, see Python Initialization Configuration.

Set the default module search path. If this function is called before Py_Initialize(), then Py_GetPath() won't attempt to compute a default search path but uses the one provided instead. This is useful if Python is embedded by an application that has full knowledge of the location of all modules. The path components should be separated by the platform dependent delimiter character, which is ':' on Unix and macOS, ';' on Windows.

This also causes sys.executable to be set to the program full path (see Py_GetProgramFullPath()) and for sys.prefix and sys.exec_prefix to be empty. It is up to the caller to modify these if required after calling Py_Initialize().

バイト文字列を wchar_* 文字列にデコードするには Py_DecodeLocale() を使ってください。

The path argument is copied internally, so the caller may free it after the call completes.

バージョン 3.8 で変更: The program full path is now used for sys.executable, instead of the program name.

バージョン 3.11 で非推奨.

const char *Py_GetVersion()

Part of the Stable ABI.

Python インタプリタのバージョンを返します。バージョンは、次のような形式の文字列です

"3.0a5+ (py3k:63103M, May 12 2008, 00:53:55) \n[GCC 4.2.3]"

第一ワード (最初のスペース文字まで) は、現在の Python のバージョンです; 最初の文字は、ピリオドで区切られたメジャーバージョンとマイナーバージョンです。関数が返す文字列ポインタは静的な記憶領域を返します; 関数の呼び出し側はこの値を変更できません。この値は Python コードからは sys.version として利用できます。

See also the Py_Version constant.

const char *Py_GetPlatform()

Part of the Stable ABI.

現在のプラットフォームのプラットフォーム識別文字列を返します。Unixでは、オペレーティングシステムの "公式の" 名前を小文字に変換し、後ろにメジャーリビジョン番号を付けた構成になっています。例えば Solaris 2.x は、SunOS 5.x, としても知られていますが、'sunos5' になります。macOS では 'darwin' です。Windows では 'win' です。関数が返す文字列ポインタは静的な記憶領域を返します; 関数の呼び出し側はこの値を変更できません。この値は Python コードからは sys.platform として利用できます。

const char *Py_GetCopyright()

Part of the Stable ABI.

現在の Python バージョンに対する公式の著作権表示文字列を返します。例えば

'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'

関数が返す文字列ポインタは静的な記憶領域を返します; 関数の呼び出し側はこの値を変更できません。この値は Python コードからは sys.copyright として利用できます。

const char *Py_GetCompiler()

Part of the Stable ABI.

現在使っているバージョンの Python をビルドする際に用いたコンパイラを示す文字列を、角括弧で囲った文字列を返します。例えば:

"[GCC 2.7.2.2]"

関数が返す文字列ポインタは静的な記憶領域を返します; 関数の呼び出し側はこの値を変更できません。この値は Python コードからは sys.version の一部として取り出せます。

const char *Py_GetBuildInfo()

Part of the Stable ABI.

現在使っている Python インタプリタインスタンスの、シーケンス番号とビルド日時に関する情報を返します。例えば

"#67, Aug  1 1997, 22:34:28"

関数が返す文字列ポインタは静的な記憶領域を返します; 関数の呼び出し側はこの値を変更できません。この値は Python コードからは sys.version の一部として取り出せます。

void PySys_SetArgvEx(int argc, wchar_t **argv, int updatepath)

Part of the Stable ABI.

This API is kept for backward compatibility: setting PyConfig.argv, PyConfig.parse_argv and PyConfig.safe_path should be used instead, see Python Initialization Configuration.

argc および argv に基づいて sys.argv を設定します。これらの引数はプログラムの main() に渡した引数に似ていますが、最初の要素が Python インタプリタの宿主となっている実行形式の名前ではなく、実行されるスクリプト名を参照しなければならない点が違います。実行するスクリプトがない場合、 argv の最初の要素は空文字列にしてもかまいません。この関数が sys.argv の初期化に失敗した場合、致命的エラーを Py_FatalError() で知らせます。

updatepath が 0 の場合、ここまでの動作がこの関数がすることの全てです。 updatepath が 0 でない場合、この関数は sys.path を以下のアルゴリズムに基づいて修正します:

存在するスクリプトの名前が argv[0] に渡された場合、そのスクリプトがある場所の絶対パスを sys.path の先頭に追加します。

それ以外の場合 (argc が 0 だったり、 argv[0] が存在するファイル名を指していない場合)、 sys.path の先頭に空の文字列を追加します。これは現在の作業ディレクトリ (".") を先頭に追加するのと同じです。

バイト文字列を wchar_* 文字列にデコードするには Py_DecodeLocale() を使ってください。

See also PyConfig.orig_argv and PyConfig.argv members of the Python Initialization Configuration.

注釈

It is recommended that applications embedding the Python interpreter for purposes other than executing a single script pass 0 as updatepath, and update sys.path themselves if desired. See CVE-2008-5983 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2008-5983].

3.1.3 より前のバージョンでは、 PySys_SetArgv() の呼び出しが完了した後に sys.path の先頭の要素を取り出すことで、同じ効果が得られます。例えばこのように使います:

PyRun_SimpleString("import sys; sys.path.pop(0)\n");

Added in version 3.1.3.

バージョン 3.11 で非推奨.

void PySys_SetArgv(int argc, wchar_t **argv)

Part of the Stable ABI.

This API is kept for backward compatibility: setting PyConfig.argv and PyConfig.parse_argv should be used instead, see Python Initialization Configuration.

この関数は、 python インタプリタが -I オプション付きで実行されている場合を除き PySys_SetArgvEx() の updatepath に 1 を設定したのと同じように動作します。

バイト文字列を wchar_* 文字列にデコードするには Py_DecodeLocale() を使ってください。

See also PyConfig.orig_argv and PyConfig.argv members of the Python Initialization Configuration.

バージョン 3.4 で変更: updatepath の値は -I オプションに依存します。

バージョン 3.11 で非推奨.

void Py_SetPythonHome(const wchar_t *home)

Part of the Stable ABI.

This API is kept for backward compatibility: setting PyConfig.home should be used instead, see Python Initialization Configuration.

Python の標準ライブラリがある、デフォルトの "home" ディレクトリを設定します。引数の文字列の意味については PYTHONHOME を参照してください。

引数は静的なストレージに置かれてプログラム実行中に書き換えられないようなゼロ終端の文字列であるべきです。Python インタプリタはこのストレージの内容を変更しません。

バイト文字列を wchar_* 文字列にデコードするには Py_DecodeLocale() を使ってください。

バージョン 3.11 で非推奨.

wchar_t *Py_GetPythonHome()

Part of the Stable ABI.

Return the default "home", that is, the value set by a previous call to Py_SetPythonHome(), or the value of the PYTHONHOME environment variable if it is set.

This function should not be called before Py_Initialize(), otherwise it returns NULL.

バージョン 3.10 で変更: It now returns NULL if called before Py_Initialize().

スレッド状態 (thread state) とグローバルインタプリタロック (global interpreter lock)

Python インタプリタは完全にはスレッドセーフではありません。マルチスレッドの Python プログラムをサポートするために、 グローバルインタプリタロック あるいは GIL と呼ばれるグローバルなロックが存在していて、現在のスレッドが Python オブジェクトに安全にアクセスする前に必ずロックを獲得しなければならなくなっています。ロック機構がなければ、単純な操作でさえ、マルチスレッドプログラムの実行に問題を引き起こす可能性があります。たとえば、二つのスレッドが同じオブジェクトの参照カウントを同時にインクリメントすると、結果的に参照カウントは二回でなく一回だけしかインクリメントされないかもしれません。

このため、 GIL を獲得したスレッドだけが Python オブジェクトを操作したり、 Python/C API 関数を呼び出したりできるというルールがあります。並行処理をエミュレートするために、インタプリタは定期的にロックを解放したり獲得したりします。 (sys.setswitchinterval() を参照) このロックはブロックが起こりうる I/O 操作の付近でも解放・獲得され、 I/O を要求するスレッドが I/O 操作の完了を待つ間、他のスレッドが動作できるようにしています。

Python インタプリタはスレッドごとに必要な情報を PyThreadState と呼ばれるデータ構造の中に保存します。そしてグローバル変数として現在の PyThreadState を指すポインタを1つ持ちます。このグローバル変数は PyThreadState_Get() を使って取得できます。

拡張コード内で GIL を解放する

GIL を操作するほとんどのコードは、次のような単純な構造になります:

Save the thread state in a local variable.
Release the global interpreter lock.
... Do some blocking I/O operation ...
Reacquire the global interpreter lock.
Restore the thread state from the local variable.

この構造は非常に一般的なので、作業を単純にするために2つのマクロが用意されています:

Py_BEGIN_ALLOW_THREADS
... Do some blocking I/O operation ...
Py_END_ALLOW_THREADS

Py_BEGIN_ALLOW_THREADS マクロは新たなブロックを開始し、隠しローカル変数を宣言します; Py_END_ALLOW_THREADS はブロックを閉じます。

上のブロックは次のコードに展開されます:

PyThreadState *_save;

_save = PyEval_SaveThread();
... Do some blocking I/O operation ...
PyEval_RestoreThread(_save);

これらの関数の動作を説明します。GIL は現在のスレッド状態を指すポインタを保護するために使われます。ロックを解放してスレッド状態を退避する際、ロックを解放する前に現在のスレッド状態ポインタを取得しておかなければなりません (他のスレッドがすぐさまロックを獲得して、自らのスレッド状態をグローバル変数に保存してしまうかもしれないからです)。逆に、ロックを獲得してスレッド状態を復帰する際には、グローバル変数にスレッド状態ポインタを保存する前にロックを獲得しておかなければなりません。

注釈

GIL を解放するのはほとんどがシステムのI/O関数を呼び出す時ですが、メモリバッファに対する圧縮や暗号化のように、 Python のオブジェクトにアクセスしない長時間かかる計算処理を呼び出すときも GIL を解放することは有益です。例えば、 zlib や hashlib モジュールは圧縮やハッシュ計算の前に GIL を解放します。

Python 以外で作られたスレッド

Python API を通して作られたスレッド (threading モジュールなど) では自動的にスレッド状態が割り当てられて、上記のコードは正しく動きます。しかし、(自前でスレッド管理を行う外部のライブラリなどにより)C言語でスレッドを生成した場合、そのスレッドには GIL がなく、スレッド状態データ構造体もないことに注意する必要があります。

このようなスレッドから Python コードを呼び出す必要がある場合 (外部のライブラリからコールバックするAPIなどがよくある例です)、Python/C API を呼び出す前に、スレッド状態データ構造体を生成し、GIL を獲得し、スレッド状態ポインタを保存することで、スレッドをインタプリタに登録しなければなりません。スレッドが作業を終えたら、スレッド状態ポインタをリセットして、ロックを解放し、最後にスレッド状態データ構造体のメモリを解放しなければなりません。

PyGILState_Ensure() と PyGILState_Release() はこの処理を自動的に行います。 Cのスレッドから Python を呼び出す典型的な方法は以下のとおりです:

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);

PyGILState_* 関数は、(Py_Initialize() によって自動的に作られる) グローバルインタプリタ1つだけが存在すると仮定する事に気をつけて下さい。 Python は (Py_NewInterpreter() を使って) 追加のインタプリタを作成できることに変わりはありませんが、複数インタプリタと PyGILState_* API を混ぜて使うことはサポートされていません。

Cautions about fork()

Another important thing to note about threads is their behaviour in the face of the C fork() call. On most systems with 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 os.fork() by acquiring the locks it uses internally before the fork, and releasing them afterwards. In addition, it resets any 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 pthread_atfork() would need to be used to accomplish the same thing. Additionally, when extending or embedding Python, calling fork() directly rather than through 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. 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 os.fork() does. This means finalizing all other PyThreadState objects belonging to the current interpreter and all other PyInterpreterState objects. Due to this and the special nature of the "main" interpreter, fork() should only be called in that interpreter's "main" thread, where the CPython global runtime was originally initialized. The only exception is if exec() will be called immediately after.

高レベルAPI

C拡張を書いたりPythonインタプリタを埋め込むときに最も一般的に使われる型や関数は次のとおりです:

type PyInterpreterState

Part of the Limited API (as an opaque struct).

このデータ構造体は、協調動作する多数のスレッド間で共有されている状態を表現します。同じインタプリタに属するスレッドはモジュール管理情報やその他いくつかの内部的な情報を共有しています。この構造体には公開 (public) のメンバはありません。

異なるインタプリタに属するスレッド間では、利用可能なメモリ、開かれているファイルデスクリプタなどといったプロセス状態を除いて、初期状態では何も共有されていません。GILもまた、スレッドがどのインタプリタに属しているかに関わらずすべてのスレッドで共有されています。

type PyThreadState

Part of the Limited API (as an opaque struct).

This data structure represents the state of a single thread. The only public data member is:

PyInterpreterState *interp

This thread's interpreter state.

void PyEval_InitThreads()

Part of the Stable ABI.

Deprecated function which does nothing.

In Python 3.6 and older, this function created the GIL if it didn't exist.

バージョン 3.9 で変更: The function now does nothing.

バージョン 3.7 で変更: この関数は Py_Initialize() から呼び出されるようになり、わざわざ呼び出す必要はもう無くなりました。

バージョン 3.2 で変更: この関数は Py_Initialize() より前に呼び出すことができなくなりました。

バージョン 3.9 で非推奨.

int PyEval_ThreadsInitialized()

Part of the Stable ABI.

Returns a non-zero value if PyEval_InitThreads() has been called. This function can be called without holding the GIL, and therefore can be used to avoid calls to the locking API when running single-threaded.

バージョン 3.7 で変更: The GIL is now initialized by Py_Initialize().

バージョン 3.9 で非推奨.

PyThreadState *PyEval_SaveThread()

Part of the Stable ABI.

(GIL が生成されている場合) GILを解放して、スレッドの状態を NULL にし、以前のスレッド状態 (NULL にはなりません) を返します。ロックがすでに生成されている場合、現在のスレッドがロックを獲得していなければなりません。

void PyEval_RestoreThread(PyThreadState *tstate)

Part of the Stable ABI.

(GIL が生成されている場合) GIL を獲得して、現在のスレッド状態を tstate に設定します。 tstate は NULL であってはなりません。 GIL が生成されていて、この関数を呼び出したスレッドがすでにロックを獲得している場合、デッドロックに陥ります。

注釈

Calling this function from a thread when the runtime is finalizing will terminate the thread, even if the thread was not created by Python. You can use _Py_IsFinalizing() or sys.is_finalizing() to check if the interpreter is in process of being finalized before calling this function to avoid unwanted termination.

PyThreadState *PyThreadState_Get()

Part of the Stable ABI.

現在のスレッド状態を返します。GIL を保持していなければなりません。現在のスレッド状態が NULL なら、(呼び出し側が NULL チェックをしなくてすむように) この関数は致命的エラーを起こすようになっています。

PyThreadState *PyThreadState_Swap(PyThreadState *tstate)

Part of the Stable ABI.

現在のスレッド状態を tstate に指定したスレッド状態と入れ変えます。tstate は NULL の場合があります。GIL を保持していなければならず、解放しません。

以下の関数はスレッドローカルストレージを利用していて、サブインタプリタとの互換性がありません:

PyGILState_STATE PyGILState_Ensure()

Part of the Stable ABI.

Pythonの状態やGILに関わらず、実行中スレッドでPython C APIの呼び出しが可能となるようにします。この関数はスレッド内で何度でも呼び出すことができますが、必ず全ての呼び出しに対応して PyGILState_Release() を呼び出す必要があります。通常、 PyGILState_Ensure() 呼び出しと PyGILState_Release() 呼び出しの間でこれ以外のスレッド関連API を使用することができますが、Release()の前にスレッド状態は復元されていなければなりません。例えば、通常の Py_BEGIN_ALLOW_THREADS マクロと Py_END_ALLOW_THREADS は使用することができます。

戻り値は PyGILState_Ensure() 呼び出し時のスレッド状態を隠蔽した"ハンドル"で、 PyGILState_Release() に渡してPythonを同じ状態に保たなければなりません。再起呼び出しも可能ですが、ハンドルを共有することは できません - それぞれの PyGILState_Ensure() 呼び出しでハンドルを保存し、対応する PyGILState_Release() 呼び出しで渡してください。

関数から復帰したとき、実行中のスレッドはGILを所有していて、任意の Python コードを実行できます。処理の失敗は致命的なエラーです。

注釈

Calling this function from a thread when the runtime is finalizing will terminate the thread, even if the thread was not created by Python. You can use _Py_IsFinalizing() or sys.is_finalizing() to check if the interpreter is in process of being finalized before calling this function to avoid unwanted termination.

void PyGILState_Release(PyGILState_STATE)

Part of the Stable ABI.

獲得したすべてのリソースを解放します。この関数を呼び出すと、Pythonの状態は対応する PyGILState_Ensure() を呼び出す前と同じとなります (通常、この状態は呼び出し元でははわかりませんので、GILState APIを利用するようにしてください)。

PyGILState_Ensure() を呼び出す場合は、必ず同一スレッド内で対応する PyGILState_Release() を呼び出してください。

PyThreadState *PyGILState_GetThisThreadState()

Part of the Stable ABI.

このスレッドの現在のスレッドの状態を取得します。これまで現在のスレッドで GILState API を使ったことが無い場合は、NULL が返ります。メインスレッドで自身のスレッド状態に関する呼び出しを全くしないとしても、メインスレッドは常にスレッド状態の情報を持っていることに注意してください。こうなっている目的は主にヘルパ機能もしくは診断機能のためです。

int PyGILState_Check()

現在のスレッドが GILを保持しているならば 1 を、そうでなければ 0 を返します。この関数はいつでもどのスレッドからでも呼び出すことができます。 Python スレッドの状態が初期化されており、現在 GIL を保持している場合にのみ 1 を返します。これは主にヘルパー/診断用の関数です。この関数は、例えばコールバックのコンテキストやメモリ割り当て機能で有益でしょう。なぜなら、 GIL がロックされていると知っていれば、呼び出し元は sensitive な行動を実行することができ、そうでなければ異なるやりかたで振る舞うことができるからです。

Added in version 3.4.

以下のマクロは、通常末尾にセミコロンを付けずに使います; Python ソース配布物内の使用例を見てください。

Py_BEGIN_ALLOW_THREADS

Part of the Stable ABI.

このマクロを展開すると { PyThreadState *_save; _save = PyEval_SaveThread(); になります。マクロに開き波括弧が入っていることに注意してください; この波括弧は後で Py_END_ALLOW_THREADS マクロと対応させなければなりません。マクロについての詳しい議論は上記を参照してください。

Py_END_ALLOW_THREADS

Part of the Stable ABI.

このマクロを展開すると PyEval_RestoreThread(_save); } になります。マクロに開き波括弧が入っていることに注意してください; この波括弧は事前の Py_BEGIN_ALLOW_THREADS マクロと対応していなければなりません。マクロについての詳しい議論は上記を参照してください。

Py_BLOCK_THREADS

Part of the Stable ABI.

このマクロを展開すると PyEval_RestoreThread(_save); になります: 閉じ波括弧のない Py_END_ALLOW_THREADS と同じです。

Py_UNBLOCK_THREADS

Part of the Stable ABI.

このマクロを展開すると _save = PyEval_SaveThread(); になります: 開き波括弧のない Py_BEGIN_ALLOW_THREADS と同じです。

低レベルAPI

次の全ての関数は Py_Initialize() の後に呼び出さなければなりません。

バージョン 3.7 で変更: Py_Initialize() は GIL を初期化するようになりました。

PyInterpreterState *PyInterpreterState_New()

Part of the Stable ABI.

新しいインタプリタ状態オブジェクトを生成します。GIL を保持しておく必要はありませんが、この関数を次々に呼び出す必要がある場合には保持しておいたほうがよいでしょう。

引数無しで 監査イベント cpython.PyInterpreterState_New を送出します。

void PyInterpreterState_Clear(PyInterpreterState *interp)

Part of the Stable ABI.

インタプリタ状態オブジェクト内の全ての情報をリセットします。GIL を保持していなければなりません。

引数無しで 監査イベント cpython.PyInterpreterState_Clear を送出します。

void PyInterpreterState_Delete(PyInterpreterState *interp)

Part of the Stable ABI.

インタプリタ状態オブジェクトを破壊します。GIL を保持しておく必要はありません。インタプリタ状態は PyInterpreterState_Clear() であらかじめリセットしておかなければなりません。

PyThreadState *PyThreadState_New(PyInterpreterState *interp)

Part of the Stable ABI.

指定したインタプリタオブジェクトに属する新たなスレッド状態オブジェクトを生成します。GIL を保持しておく必要はありませんが、この関数を次々に呼び出す必要がある場合には保持しておいたほうがよいでしょう。

void PyThreadState_Clear(PyThreadState *tstate)

Part of the Stable ABI.

スレッド状態オブジェクト内の全ての情報をリセットします。GIL を保持していなければなりません。

バージョン 3.9 で変更: This function now calls the PyThreadState.on_delete callback. Previously, that happened in PyThreadState_Delete().

void PyThreadState_Delete(PyThreadState *tstate)

Part of the Stable ABI.

スレッド状態オブジェクトを破壊します。GIL を保持する必要はありません。スレッド状態は PyThreadState_Clear() であらかじめリセットしておかなければなりません。

void PyThreadState_DeleteCurrent(void)

Destroy the current thread state and release the global interpreter lock. Like PyThreadState_Delete(), the global interpreter lock need not be held. The thread state must have been reset with a previous call to PyThreadState_Clear().

PyFrameObject *PyThreadState_GetFrame(PyThreadState *tstate)

Part of the Stable ABI since version 3.10.

Get the current frame of the Python thread state tstate.

Return a strong reference. Return NULL if no frame is currently executing.

See also PyEval_GetFrame().

tstate must not be NULL.

Added in version 3.9.

uint64_t PyThreadState_GetID(PyThreadState *tstate)

Part of the Stable ABI since version 3.10.

Get the unique thread state identifier of the Python thread state tstate.

tstate must not be NULL.

Added in version 3.9.

PyInterpreterState *PyThreadState_GetInterpreter(PyThreadState *tstate)

Part of the Stable ABI since version 3.10.

Get the interpreter of the Python thread state tstate.

tstate must not be NULL.

Added in version 3.9.

void PyThreadState_EnterTracing(PyThreadState *tstate)

Suspend tracing and profiling in the Python thread state tstate.

Resume them using the PyThreadState_LeaveTracing() function.

Added in version 3.11.

void PyThreadState_LeaveTracing(PyThreadState *tstate)

Resume tracing and profiling in the Python thread state tstate suspended by the PyThreadState_EnterTracing() function.

See also PyEval_SetTrace() and PyEval_SetProfile() functions.

Added in version 3.11.

PyInterpreterState *PyInterpreterState_Get(void)

Part of the Stable ABI since version 3.9.

Get the current interpreter.

Issue a fatal error if there no current Python thread state or no current interpreter. It cannot return NULL.

呼び出し側はGILを獲得する必要があります

Added in version 3.9.

int64_t PyInterpreterState_GetID(PyInterpreterState *interp)

Part of the Stable ABI since version 3.7.

インタプリタの一意な ID を返します。処理中に何かエラーが起きたら、 -1 が返され、エラーがセットされます。

呼び出し側はGILを獲得する必要があります

Added in version 3.7.

PyObject *PyInterpreterState_GetDict(PyInterpreterState *interp)

Part of the Stable ABI since version 3.8.

インタプリタ固有のデータを保持している辞書を返します。この関数が NULL を返した場合は、ここまでで例外は送出されておらず、呼び出し側はインタプリタ固有の辞書は利用できないと考えなければなりません。

この関数は PyModule_GetState() を置き換えるものではなく、拡張モジュールがインタプリタ固有の状態情報を格納するのに使うべきものです。

Added in version 3.8.

typedef PyObject *(*_PyFrameEvalFunction)(PyThreadState *tstate, _PyInterpreterFrame *frame, int throwflag)

Type of a frame evaluation function.

The throwflag parameter is used by the 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 PyFrameObject* to _PyInterpreterFrame*.

_PyFrameEvalFunction _PyInterpreterState_GetEvalFrameFunc(PyInterpreterState *interp)

Get the frame evaluation function.

See the PEP 523 [https://peps.python.org/pep-0523/] "Adding a frame evaluation API to CPython".

Added in version 3.9.

void _PyInterpreterState_SetEvalFrameFunc(PyInterpreterState *interp, _PyFrameEvalFunction eval_frame)

Set the frame evaluation function.

See the PEP 523 [https://peps.python.org/pep-0523/] "Adding a frame evaluation API to CPython".

Added in version 3.9.

PyObject *PyThreadState_GetDict()

Return value: Borrowed reference. Part of the Stable ABI.

拡張モジュールがスレッド固有の状態情報を保存できるような辞書を返します。各々の拡張モジュールが辞書に状態情報を保存するためには唯一のキーを使わなければなりません。現在のスレッド状態がない時にこの関数を呼び出してもかまいません。この関数が NULL を返す場合、例外はまったく送出されず、呼び出し側は現在のスレッド状態が利用できないと考えなければなりません。

int PyThreadState_SetAsyncExc(unsigned long id, PyObject *exc)

Part of the Stable ABI.

Asynchronously raise an exception in a thread. The id argument is the thread id of the target thread; exc is the exception object to be raised. This function does not steal any references to exc. To prevent naive misuse, you must write your own C extension to call this. Must be called with the GIL held. Returns the number of thread states modified; this is normally one, but will be zero if the thread id isn't found. If exc is NULL, the pending exception (if any) for the thread is cleared. This raises no exceptions.

バージョン 3.7 で変更: id 引数の型が long から unsigned long へ変更されました。

void PyEval_AcquireThread(PyThreadState *tstate)

Part of the Stable ABI.

GIL を獲得し、現在のスレッド状態を tstate に設定します。 tstate は NULL であってはなりません。ロックはあらかじめ作成されていなければなりません。この関数を呼び出したスレッドがすでにロックを獲得している場合、デッドロックに陥ります。

注釈

Calling this function from a thread when the runtime is finalizing will terminate the thread, even if the thread was not created by Python. You can use _Py_IsFinalizing() or sys.is_finalizing() to check if the interpreter is in process of being finalized before calling this function to avoid unwanted termination.

バージョン 3.8 で変更: Updated to be consistent with PyEval_RestoreThread(), Py_END_ALLOW_THREADS(), and PyGILState_Ensure(), and terminate the current thread if called while the interpreter is finalizing.

PyEval_RestoreThread() はいつでも (スレッドが初期化されたいないときでも) 利用可能な高レベル関数です。

void PyEval_ReleaseThread(PyThreadState *tstate)

Part of the Stable ABI.

現在のスレッド状態をリセットして NULL にし、GIL を解放します。ロックはあらかじめ作成されていなければならず、かつ現在のスレッドが保持していなければなりません。tstate は NULL であってはなりませんが、その値が現在のスレッド状態を表現しているかどうかを調べるためにだけ使われます --- もしそうでなければ、致命的エラーが報告されます。

PyEval_SaveThread() はより高レベルな関数で常に (スレッドが初期化されていないときでも) 利用できます。

void PyEval_AcquireLock()

Part of the Stable ABI.

Acquire the global interpreter lock. The lock must have been created earlier. If this thread already has the lock, a deadlock ensues.

バージョン 3.2 で非推奨: This function does not update the current thread state. Please use PyEval_RestoreThread() or PyEval_AcquireThread() instead.

注釈

Calling this function from a thread when the runtime is finalizing will terminate the thread, even if the thread was not created by Python. You can use _Py_IsFinalizing() or sys.is_finalizing() to check if the interpreter is in process of being finalized before calling this function to avoid unwanted termination.

バージョン 3.8 で変更: Updated to be consistent with PyEval_RestoreThread(), Py_END_ALLOW_THREADS(), and PyGILState_Ensure(), and terminate the current thread if called while the interpreter is finalizing.

void PyEval_ReleaseLock()

Part of the Stable ABI.

Release the global interpreter lock. The lock must have been created earlier.

バージョン 3.2 で非推奨: This function does not update the current thread state. Please use PyEval_SaveThread() or PyEval_ReleaseThread() instead.

サブインタプリタサポート

ほとんどの場合は埋め込む Python インタプリタは1つだけですが、いくつかの場合に同一プロセス内、あるいは同一スレッド内で、複数の独立したインタプリタを作成する必要があります。これを可能にするのがサブインタプリタです。

"メイン" インタプリタとは、ランタイムが初期化を行ったときに最初に作成されたインタプリタのことです。サブインタプリタと違い、メインインタプリタにはシグナルハンドリングのような、プロセス全域で唯一な責務があります。メインインタプリタにはランタイムの初期化中の処理実行という責務もあり、通常はランタイムの終了処理中に動いているランタイムでもあります。 PyInterpreterState_Main() 関数は、メインインタプリタの状態へのポインタを返します。

サブインタプリタを切り替えが PyThreadState_Swap() 関数でできます。次の関数を使ってサブインタプリタの作成と削除が行えます:

type PyInterpreterConfig

Structure containing most parameters to configure a sub-interpreter. Its values are used only in Py_NewInterpreterFromConfig() and never modified by the runtime.

Added in version 3.12.

構造体フィールド:

int use_main_obmalloc

If this is 0 then the sub-interpreter will use its own "object" allocator state. Otherwise it will use (share) the main interpreter's.

If this is 0 then check_multi_interp_extensions must be 1 (non-zero). If this is 1 then gil must not be PyInterpreterConfig_OWN_GIL.

int allow_fork

If this is 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 subprocess module still works when fork is disallowed.

int allow_exec

If this is 0 then the runtime will not support replacing the current process via exec (e.g. os.execv()) in any thread where the sub-interpreter is currently active. Otherwise exec is unrestricted.

Note that the subprocess module still works when exec is disallowed.

int allow_threads

If this is 0 then the sub-interpreter's threading module won't create threads. Otherwise threads are allowed.

int allow_daemon_threads

If this is 0 then the sub-interpreter's threading module won't create daemon threads. Otherwise daemon threads are allowed (as long as allow_threads is non-zero).

int check_multi_interp_extensions

If this is 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 PEP 489 [https://peps.python.org/pep-0489/]) may be imported. (Also see Py_mod_multiple_interpreters.)

This must be 1 (non-zero) if use_main_obmalloc is 0.

int gil

This determines the operation of the GIL for the sub-interpreter. It may be one of the following:

PyInterpreterConfig_DEFAULT_GIL

Use the default selection (PyInterpreterConfig_SHARED_GIL).

PyInterpreterConfig_SHARED_GIL

Use (share) the main interpreter's GIL.

PyInterpreterConfig_OWN_GIL

Use the sub-interpreter's own GIL.

If this is PyInterpreterConfig_OWN_GIL then PyInterpreterConfig.use_main_obmalloc must be 0.

PyStatus Py_NewInterpreterFromConfig(PyThreadState **tstate_p, const PyInterpreterConfig *config)

新しいサブインタプリタ (sub-interpreter) を生成します。サブインタプリタとは、(ほぼ完全に) 個別に分割された Python コードの実行環境です。特に、新しいサブインタプリタは、 import されるモジュール全てについて個別のバージョンを持ち、これには基盤となるモジュール builtins, __main__ および sys も含まれます。ロード済みのモジュールからなるテーブル (sys.modules) およびモジュール検索パス (sys.path) もサブインタプリタ毎に別個のものになります。新たなサブインタプリタ環境には sys.argv 変数がありません。また、サブインタプリタは新たな標準 I/O ストリーム sys.stdin, sys.stdout, sys.stderr を持ちます (とはいえ、これらのストリームは根底にある同じファイル記述子を参照しています)。

The given config controls the options with which the interpreter is initialized.

Upon success, tstate_p will be set to the first thread state created in the new sub-interpreter. This thread state is made in the current thread state. Note that no actual thread is created; see the discussion of thread states below. If creation of the new interpreter is unsuccessful, tstate_p is set to NULL; no exception is set since the exception state is stored in the current thread state and there may not be a current thread state.

Like all other Python/C API functions, the global interpreter lock must be held before calling this function and is still held when it returns. Likewise a current thread state must be set on entry. On success, the returned thread state will be set as current. If the sub-interpreter is created with its own GIL then the GIL of the calling interpreter will be released. When the function returns, the new interpreter's GIL will be held by the current thread and the previously interpreter's GIL will remain released here.

Added in version 3.12.

Sub-interpreters are most effective when isolated from each other, with certain functionality restricted:

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 = Py_NewInterpreterFromConfig(&config);

Note that the config is used only briefly and does not get modified. During initialization the config's values are converted into various PyInterpreterState values. A read-only copy of the config may be stored internally on the PyInterpreterState.

Extension modules are shared between (sub-)interpreters as follows:

For modules using multi-phase initialization, e.g. 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.

For modules using single-phase initialization, e.g. 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 init function is not called. Objects in the module's dictionary thus end up shared across (sub-)interpreters, which might cause unwanted behavior (see 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 Py_FinalizeEx() and Py_Initialize(); in that case, the extension's 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.

PyThreadState *Py_NewInterpreter(void)

Part of the Stable ABI.

Create a new sub-interpreter. This is essentially just a wrapper around 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.

void Py_EndInterpreter(PyThreadState *tstate)

Part of the Stable ABI.

Destroy the (sub-)interpreter represented by the given thread state. The given thread state must be the current thread state. See the discussion of thread states below. When the call returns, the current thread state is NULL. All thread states associated with this interpreter are destroyed. The global interpreter lock used by the target interpreter must be held before calling this function. No GIL is held when it returns.

Py_FinalizeEx() will destroy all sub-interpreters that haven't been explicitly destroyed at that point.

A Per-Interpreter GIL

Using 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 PEP 554 [https://peps.python.org/pep-0554/].)

Using an isolated interpreter requires vigilance in preserving that isolation. That especially means not sharing any objects or mutable state without guarantees about thread-safety. Even objects that are otherwise immutable (e.g. None, (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 "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.

Added in version 3.12.

バグと注意事項

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

サブインタプリタを PyGILState_* API と組み合わせるのが難しいことにも注意してください。これらのAPIはPythonのスレッド状態とOSレベルスレッドが1対1で対応していることを前提にしていて、サブインタプリタが存在するとその前提が崩れるからです。対応する PyGILState_Ensure() と PyGILState_Release() の呼び出しのペアの間では、サブインタプリタの切り替えを行わないことを強く推奨します。さらに、(ctypes のような)これらのAPIを使ってPythonの外で作られたスレッドから Pythonコードを実行している拡張モジュールはサブインタプリタを使うと壊れる可能性があります。

非同期通知

インタプリタのメインスレッドに非同期な通知を行うために提供されている仕組みです。これらの通知は関数ポインタと void ポインタ引数という形態を取ります。

int Py_AddPendingCall(int (*func)(void*), void *arg)

Part of the Stable ABI.

インタプリタのメインスレッドから関数が呼び出される予定を組みます。成功すると 0 が返り、func はメインスレッドの呼び出しキューに詰められます。失敗すると、例外をセットせずに -1 が返ります。

無事にキューに詰められると、func は いつかは必ず インタプリタのメインスレッドから、arg を引数として呼び出されます。この関数は、通常の実行中の Python コードに対して非同期に呼び出されますが、次の両方の条件に合致したときに呼び出されます:

bytecode 境界上にいるとき、

メインスレッドが global interpreter lock を保持している (すなわち func が全ての C API を呼び出せる) とき。

成功したら func は 0 を返さねばならず、失敗したら -1 を返し例外をセットしなければいけません。func は、他の非同期通知を行うために、さらに割り込まれることはありませんが、グローバルインタプリタロックが解放された場合は、スレッドの切り替えによって割り込まれる可能性が残っています。

この関数は実行するのに現在のスレッド状態を必要とせず、グローバルインタプリタロックも必要としません。

To call this function in a subinterpreter, the caller must hold the GIL. Otherwise, the function func can be scheduled to be called from the wrong interpreter.

警告

これは、非常に特別な場合にのみ役立つ、低レベルな関数です。 func が可能な限り早く呼び出される保証はありません。メインスレッドがシステムコールを実行するのに忙しい場合は、 func はシステムコールが返ってくるまで呼び出されないでしょう。この関数は一般的には、任意の C スレッドから Python コードを呼び出すのには 向きません 。これの代わりに、 PyGILState API を使用してください。

Added in version 3.1.

バージョン 3.9 で変更: If this function is called in a subinterpreter, the function func is now scheduled to be called from the subinterpreter, rather than being called from the main interpreter. Each subinterpreter now has its own list of scheduled calls.

プロファイルとトレース (profiling and tracing)

Python インタプリタは、プロファイル: 分析 (profile) や実行のトレース: 追跡 (trace) といった機能を組み込むために低水準のサポートを提供しています。このサポートは、プロファイルやデバッグ、適用範囲分析 (coverage analysis) ツールなどに使われます。

この C インターフェースは、プロファイルやトレース作業時に、Python レベルの呼び出し可能オブジェクトが呼び出されることによるオーバヘッドを避け、直接 C 関数呼び出しが行えるようにしています。プロファイルやトレース機能の本質的な特性は変わっていません; インターフェースではトレース関数をスレッドごとにインストールでき、トレース関数に報告される基本イベント (basic event) は以前のバージョンにおいて Python レベルのトレース関数で報告されていたものと同じです。

typedef int (*Py_tracefunc)(PyObject *obj, PyFrameObject *frame, int what, PyObject *arg)

The type of the trace function registered using PyEval_SetProfile() and 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 PyTrace_CALL, PyTrace_EXCEPTION, PyTrace_LINE, PyTrace_RETURN, PyTrace_C_CALL, PyTrace_C_EXCEPTION, PyTrace_C_RETURN, or PyTrace_OPCODE, and arg depends on the value of what:

what の値

arg の意味

PyTrace_CALL

常に Py_None 。

PyTrace_EXCEPTION

sys.exc_info() の返す例外情報です。

PyTrace_LINE

常に Py_None 。

PyTrace_RETURN

呼び出し側に返される予定の値か、例外によって関数を抜ける場合は NULL です。

PyTrace_C_CALL

呼び出される関数オブジェクト。

PyTrace_C_EXCEPTION

呼び出される関数オブジェクト。

PyTrace_C_RETURN

呼び出される関数オブジェクト。

PyTrace_OPCODE

常に Py_None 。

int PyTrace_CALL

関数やメソッドが新たに呼び出されたり、ジェネレータが新たなエントリの処理に入ったことを報告する際の、 Py_tracefunc の what の値です。イテレータやジェネレータ関数の生成は、対応するフレーム内の Python バイトコードに制御の委譲 (control transfer) が起こらないため報告されないので注意してください。

int PyTrace_EXCEPTION

例外が送出された際の Py_tracefunc の what の値です。現在実行されているフレームで例外がセットされ、何らかのバイトコードが処理された後に、 what にこの値がセットされた状態でコールバック関数が呼び出されます。この結果、例外の伝播によって Python が呼び出しスタックを逆戻りする際に、各フレームから処理が戻るごとにコールバック関数が呼び出されます。トレース関数だけがこれらのイベントを受け取ります; プロファイラはこの種のイベントを必要としません。

int PyTrace_LINE

The value passed as the what parameter to a 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 f_trace_lines to 0 on that frame.

int PyTrace_RETURN

呼び出しが返るときに Py_tracefunc 関数に what 引数として渡す値です。

int PyTrace_C_CALL

C関数を呼び出す直前に Py_tracefunc 関数の what 引数として渡す値です。

int PyTrace_C_EXCEPTION

C関数が例外を送出したときに Py_tracefunc 関数の what 引数として渡す値です。

int PyTrace_C_RETURN

C関数から戻るときに Py_tracefunc 関数の what 引数として渡す値です。

int PyTrace_OPCODE

The value for the what parameter to 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 f_trace_opcodes to 1 on the frame.

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 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 PyTrace_LINE PyTrace_OPCODE and PyTrace_EXCEPTION.

sys.setprofile() 関数も参照してください。

呼び出し側は GIL を獲得しなければなりません。

void PyEval_SetProfileAllThreads(Py_tracefunc func, PyObject *obj)

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

呼び出し側は GIL を獲得しなければなりません。

As PyEval_SetProfile(), this function ignores any exceptions raised while setting the profile functions in all threads.

Added in version 3.12.

void PyEval_SetTrace(Py_tracefunc func, PyObject *obj)

Set the tracing function to func. This is similar to 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 PyEval_SetTrace() will not receive PyTrace_C_CALL, PyTrace_C_EXCEPTION or PyTrace_C_RETURN as a value for the what parameter.

sys.settrace() 関数も参照してください。

呼び出し側は GIL を獲得しなければなりません。

void PyEval_SetTraceAllThreads(Py_tracefunc func, PyObject *obj)

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

呼び出し側は GIL を獲得しなければなりません。

As PyEval_SetTrace(), this function ignores any exceptions raised while setting the trace functions in all threads.

Added in version 3.12.

高度なデバッガサポート (advanced debugger support)

以下の関数は高度なデバッグツールでの使用のためだけのものです。

PyInterpreterState *PyInterpreterState_Head()

インタプリタ状態オブジェクトからなるリストのうち、先頭にあるものを返します。

PyInterpreterState *PyInterpreterState_Main()

メインインタプリタの状態オブジェクトを返します。

PyInterpreterState *PyInterpreterState_Next(PyInterpreterState *interp)

インタプリタ状態オブジェクトからなるリストのうち、interp の次にあるものを返します。

PyThreadState *PyInterpreterState_ThreadHead(PyInterpreterState *interp)

インタプリタ interp に関連付けられているスレッドからなるリストのうち、先頭にある PyThreadState オブジェクトを返します。

PyThreadState *PyThreadState_Next(PyThreadState *tstate)

tstate と同じ PyInterpreterState オブジェクトに属しているスレッド状態オブジェクトのうち、 tstate の次にあるものを返します。

スレッドローカルストレージのサポート

Python インタプリタは、スレッドローカルストレージ (thread-local storage, TLS) の低レベルサポートを提供していて、ネイティブの TLS 実装を内部にラップして Python レベルのスレッドローカルストレージ API (threading.local) をサポートしています。 CPython の C レベル API は pthreads や Windows で与えられる TLS と同様です: スレッドキーとスレッドごとに void* 値を関係付ける関数を使います。

API で使われる関数を呼ぶときは、 GIL を取得する必要は ありません 。関数自身のロックがサポートされています。

Python.h は TLS API の宣言を include せず、スレッドローカルストレージを使うには pythread.h を include する必要があることに注意してください。

注釈

この API 関数はどれも void* 値の代わりにメモリ管理を行うことはしません。メモリの確保と解放は自前で行う必要があります。 void* 値がたまたま PyObject* だった場合は、 API 関数はそれぞれの値の参照カウントの操作は行いません。

スレッド固有ストレージ (Thread Specific Storage, TSS) API

TSS API は、 CPython インタプリタに含まれている既存の TLS API を置き換えるために導入されました。この API は、スレッドキーの表現に int の代わりに新しい型 Py_tss_t を使います。

Added in version 3.7.

参考

"CPython のスレッドローカルストレージのための新しい C API" (PEP 539 [https://peps.python.org/pep-0539/])

type Py_tss_t

このデータ構造体はスレッドキーの状態を表現しています。この構造体の定義は、根底の TLS 実装に依存し、キーの初期化状態を表現する内部フィールドを持ちます。この構造体には公開 (public) のメンバはありません。

Py_LIMITED_API が定義されていないときは、この型の Py_tss_NEEDS_INIT による静的メモリ確保ができます。

Py_tss_NEEDS_INIT

このマクロは Py_tss_t 変数の初期化子に展開されます。このマクロは Py_LIMITED_API があるときは定義されません。

動的メモリ確保

動的な Py_tss_t のメモリ確保は Py_LIMITED_API でビルドされた拡張モジュールで必要になりますが、その実装がビルド時に不透明なために、この型の静的なメモリ確保は不可能です。

Py_tss_t *PyThread_tss_alloc()

Part of the Stable ABI since version 3.7.

Return a value which is the same state as a value initialized with Py_tss_NEEDS_INIT, or NULL in the case of dynamic allocation failure.

void PyThread_tss_free(Py_tss_t *key)

Part of the Stable ABI since version 3.7.

Free the given key allocated by PyThread_tss_alloc(), after first calling PyThread_tss_delete() to ensure any associated thread locals have been unassigned. This is a no-op if the key argument is NULL.

注釈

A freed key becomes a dangling pointer. You should reset the key to NULL.

メソッド

The parameter key of these functions must not be NULL. Moreover, the behaviors of PyThread_tss_set() and PyThread_tss_get() are undefined if the given Py_tss_t has not been initialized by PyThread_tss_create().

int PyThread_tss_is_created(Py_tss_t *key)

Part of the Stable ABI since version 3.7.

Return a non-zero value if the given Py_tss_t has been initialized by PyThread_tss_create().

int PyThread_tss_create(Py_tss_t *key)

Part of the Stable ABI since version 3.7.

Return a zero value on successful initialization of a TSS key. The behavior is undefined if the value pointed to by the key argument is not initialized by 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.

void PyThread_tss_delete(Py_tss_t *key)

Part of the Stable ABI since version 3.7.

Destroy a TSS key to forget the values associated with the key across all threads, and change the key's initialization state to uninitialized. A destroyed key is able to be initialized again by PyThread_tss_create(). This function can be called repeatedly on the same key -- calling it on an already destroyed key is a no-op.

int PyThread_tss_set(Py_tss_t *key, void *value)

Part of the Stable ABI since version 3.7.

Return a zero value to indicate successfully associating a void* value with a TSS key in the current thread. Each thread has a distinct mapping of the key to a void* value.

void *PyThread_tss_get(Py_tss_t *key)

Part of the Stable ABI since version 3.7.

Return the void* value associated with a TSS key in the current thread. This returns NULL if no value is associated with the key in the current thread.

スレッドローカルストレージ (TLS) API

バージョン 3.7 で非推奨: This API is superseded by Thread Specific Storage (TSS) API.

注釈

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 int. On such platforms, PyThread_create_key() will return immediately with a failure status, and the other TLS functions will all be no-ops on such platforms.

前述の互換性の問題により、このバージョンのAPIは新規のコードで利用すべきではありません。

int PyThread_create_key()

Part of the Stable ABI.

void PyThread_delete_key(int key)

Part of the Stable ABI.

int PyThread_set_key_value(int key, void *value)

Part of the Stable ABI.

void *PyThread_get_key_value(int key)

Part of the Stable ABI.

void PyThread_delete_key_value(int key)

Part of the Stable ABI.

void PyThread_ReInitTLS()

Part of the Stable ABI.

Python 初期化設定

Added in version 3.8.

Pythonは Py_InitializeFromConfig() と PyConfig 構造体を使って初期化できます。Py_PreInitialize() と PyPreConfig 構造体によって事前に初期化できます。

設定には二つの種類があります:

Python Configuration は、通常の Python と同じ振る舞いをするカスタマイズされた Python を構築するために使用されます。例えば、環境変数やコマンドライン引数がPythonを設定するために使用されます。

The 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.

The Py_RunMain() function can be used to write a customized Python program.

Initialization, Finalization, and Threads も参照してください。

参考

PEP 587 [https://peps.python.org/pep-0587/] "Python 初期化設定"

使用例

Example of customized Python always running in isolated mode:

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);
}

PyWideStringList

type PyWideStringList

wchar_t* 文字列のリスト。

length が非ゼロの場合は、items は非 NULL かつすべての文字列は非 NULL でなければなりません。

メソッド:

PyStatus PyWideStringList_Append(PyWideStringList *list, const wchar_t *item)

item を list に追加します。

Python must be preinitialized to call this function.

PyStatus PyWideStringList_Insert(PyWideStringList *list, Py_ssize_t index, const wchar_t *item)

item を list の index の位置に挿入します。

index が list の長さ以上の場合、item を list の末尾に追加します。

index must be greater than or equal to 0.

Python must be preinitialized to call this function.

構造体フィールド:

Py_ssize_t length

リストの長さ。

wchar_t **items

リストの要素。

PyStatus

type PyStatus

初期化関数のステータス(成功、エラー、終了)を格納する構造体です。

エラー時には、エラーを生成したC関数の名前を格納できます。

構造体フィールド:

int exitcode

終了コード。exit() の引数として渡されます。

const char *err_msg

エラーメッセージ。

const char *func

エラーを生成した関数の名前で、NULL になりえます。

ステータスを生成する関数:

PyStatus PyStatus_Ok(void)

成功。

PyStatus PyStatus_Error(const char *err_msg)

メッセージとともにエラーを初期化します。

err_msg must not be NULL.

PyStatus PyStatus_NoMemory(void)

メモリ割り当ての失敗(メモリ不足)。

PyStatus PyStatus_Exit(int exitcode)

指定した終了コードでPythonを終了します。

ステータスを扱う関数:

int PyStatus_Exception(PyStatus status)

Is the status an error or an exit? If true, the exception must be handled; by calling Py_ExitStatusException() for example.

int PyStatus_IsError(PyStatus status)

Is the result an error?

int PyStatus_IsExit(PyStatus status)

Is the result an exit?

void Py_ExitStatusException(PyStatus status)

Call 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 PyStatus_Exception(status) is non-zero.

注釈

Internally, Python uses macros which set PyStatus.func, whereas functions to create a status set func to NULL.

以下はプログラム例です:

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;
}

PyPreConfig

type PyPreConfig

Structure used to preinitialize Python.

Function to initialize a preconfiguration:

void PyPreConfig_InitPythonConfig(PyPreConfig *preconfig)

Initialize the preconfiguration with Python Configuration.

void PyPreConfig_InitIsolatedConfig(PyPreConfig *preconfig)

Initialize the preconfiguration with Isolated Configuration.

構造体フィールド:

int allocator

Name of the Python memory allocators:

PYMEM_ALLOCATOR_NOT_SET (0): don't change memory allocators (use defaults).

PYMEM_ALLOCATOR_DEFAULT (1): default memory allocators.

PYMEM_ALLOCATOR_DEBUG (2): default memory allocators with debug hooks.

PYMEM_ALLOCATOR_MALLOC (3): use malloc() of the C library.

PYMEM_ALLOCATOR_MALLOC_DEBUG (4): force usage of malloc() with debug hooks.

PYMEM_ALLOCATOR_PYMALLOC (5): Python pymalloc memory allocator.

PYMEM_ALLOCATOR_PYMALLOC_DEBUG (6): Python pymalloc memory allocator with debug hooks.

PYMEM_ALLOCATOR_PYMALLOC and PYMEM_ALLOCATOR_PYMALLOC_DEBUG are not supported if Python is configured using --without-pymalloc.

See Memory Management.

Default: PYMEM_ALLOCATOR_NOT_SET.

int configure_locale

Set the LC_CTYPE locale to the user preferred locale.

If equals to 0, set coerce_c_locale and coerce_c_locale_warn members to 0.

See the locale encoding.

Default: 1 in Python config, 0 in isolated config.

int coerce_c_locale

If equals to 2, coerce the C locale.

If equals to 1, read the LC_CTYPE locale to decide if it should be coerced.

See the locale encoding.

Default: -1 in Python config, 0 in isolated config.

int coerce_c_locale_warn

If non-zero, emit a warning if the C locale is coerced.

Default: -1 in Python config, 0 in isolated config.

int dev_mode

Python Development Mode: see PyConfig.dev_mode.

Default: -1 in Python mode, 0 in isolated mode.

int isolated

Isolated mode: see PyConfig.isolated.

Default: 0 in Python mode, 1 in isolated mode.

int legacy_windows_fs_encoding

If non-zero:

Set PyPreConfig.utf8_mode to 0,

Set PyConfig.filesystem_encoding to "mbcs",

Set PyConfig.filesystem_errors to "replace".

Initialized the from PYTHONLEGACYWINDOWSFSENCODING environment variable value.

Only available on Windows. #ifdef MS_WINDOWS macro can be used for Windows specific code.

Default: 0.

int parse_argv

If non-zero, Py_PreInitializeFromArgs() and Py_PreInitializeFromBytesArgs() parse their argv argument the same way the regular Python parses command line arguments: see Command Line Arguments.

Default: 1 in Python config, 0 in isolated config.

int use_environment

Use environment variables? See PyConfig.use_environment.

Default: 1 in Python config and 0 in isolated config.

int utf8_mode

If non-zero, enable the Python UTF-8 Mode.

Set to 0 or 1 by the -X utf8 command line option and the PYTHONUTF8 environment variable.

Also set to 1 if the LC_CTYPE locale is C or POSIX.

Default: -1 in Python config and 0 in isolated config.

Preinitialize Python with PyPreConfig

The preinitialization of Python:

Set the Python memory allocators (PyPreConfig.allocator)

Configure the LC_CTYPE locale (locale encoding)

Set the Python UTF-8 Mode (PyPreConfig.utf8_mode)

The current preconfiguration (PyPreConfig type) is stored in _PyRuntime.preconfig.

Functions to preinitialize Python:

PyStatus Py_PreInitialize(const PyPreConfig *preconfig)

Preinitialize Python from preconfig preconfiguration.

preconfig must not be NULL.

PyStatus Py_PreInitializeFromBytesArgs(const PyPreConfig *preconfig, int argc, char *const *argv)

Preinitialize Python from preconfig preconfiguration.

Parse argv command line arguments (bytes strings) if parse_argv of preconfig is non-zero.

preconfig must not be NULL.

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 parse_argv of preconfig is non-zero.

preconfig must not be NULL.

The caller is responsible to handle exceptions (error or exit) using PyStatus_Exception() and Py_ExitStatusException().

For Python Configuration (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 -X utf8 command line option enables the Python UTF-8 Mode.

PyMem_SetAllocator() can be called after Py_PreInitialize() and before Py_InitializeFromConfig() to install a custom memory allocator. It can be called before Py_PreInitialize() if PyPreConfig.allocator is set to PYMEM_ALLOCATOR_NOT_SET.

Python memory allocation functions like PyMem_RawMalloc() must not be used before the Python preinitialization, whereas calling directly malloc() and free() is always safe. Py_DecodeLocale() must not be called before the Python preinitialization.

Example using the preinitialization to enable the Python UTF-8 Mode:

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();

PyConfig

type PyConfig

Structure containing most parameters to configure Python.

When done, the PyConfig_Clear() function must be used to release the configuration memory.

Structure methods:

void PyConfig_InitPythonConfig(PyConfig *config)

Initialize configuration with the Python Configuration.

void PyConfig_InitIsolatedConfig(PyConfig *config)

Initialize configuration with the Isolated Configuration.

PyStatus PyConfig_SetString(PyConfig *config, wchar_t *const *config_str, const wchar_t *str)

Copy the wide character string str into *config_str.

Preinitialize Python if needed.

PyStatus PyConfig_SetBytesString(PyConfig *config, wchar_t *const *config_str, const char *str)

Decode str using Py_DecodeLocale() and set the result into *config_str.

Preinitialize Python if needed.

PyStatus PyConfig_SetArgv(PyConfig *config, int argc, wchar_t *const *argv)

Set command line arguments (argv member of config) from the argv list of wide character strings.

Preinitialize Python if needed.

PyStatus PyConfig_SetBytesArgv(PyConfig *config, int argc, char *const *argv)

Set command line arguments (argv member of config) from the argv list of bytes strings. Decode bytes using Py_DecodeLocale().

Preinitialize Python if needed.

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.

Preinitialize Python if needed.

PyStatus PyConfig_Read(PyConfig *config)

Read all Python configuration.

Fields which are already initialized are left unchanged.

Fields for path configuration are no longer calculated or modified when calling this function, as of Python 3.11.

The PyConfig_Read() function only parses PyConfig.argv arguments once: PyConfig.parse_argv is set to 2 after arguments are parsed. Since Python arguments are strippped from PyConfig.argv, parsing arguments twice would parse the application options as Python options.

Preinitialize Python if needed.

バージョン 3.10 で変更: The PyConfig.argv arguments are now only parsed once, PyConfig.parse_argv is set to 2 after arguments are parsed, and arguments are only parsed if PyConfig.parse_argv equals 1.

バージョン 3.11 で変更: PyConfig_Read() no longer calculates all paths, and so fields listed under Python Path Configuration may no longer be updated until Py_InitializeFromConfig() is called.

void PyConfig_Clear(PyConfig *config)

Release configuration memory.

Most PyConfig methods preinitialize Python if needed. In that case, the Python preinitialization configuration (PyPreConfig) in based on the PyConfig. If configuration fields which are in common with PyPreConfig are tuned, they must be set before calling a PyConfig method:

PyConfig.dev_mode

PyConfig.isolated

PyConfig.parse_argv

PyConfig.use_environment

Moreover, if PyConfig_SetArgv() or PyConfig_SetBytesArgv() is used, this method must be called before other methods, since the preinitialization configuration depends on command line arguments (if parse_argv is non-zero).

The caller of these methods is responsible to handle exceptions (error or exit) using PyStatus_Exception() and Py_ExitStatusException().

構造体フィールド:

PyWideStringList argv

Command line arguments: sys.argv.

Set parse_argv to 1 to parse argv the same way the regular Python parses Python command line arguments and then to strip Python arguments from argv.

If argv is empty, an empty string is added to ensure that sys.argv always exists and is never empty.

Default: NULL.

See also the orig_argv member.

int safe_path

If equals to zero, Py_RunMain() prepends a potentially unsafe path to sys.path at startup:

If argv[0] is equal to L"-m" (python -m module), prepend the current working directory.

If running a script (python script.py), prepend the script's directory. If it's a symbolic link, resolve symbolic links.

Otherwise (python -c code and python), prepend an empty string, which means the current working directory.

Set to 1 by the -P command line option and the PYTHONSAFEPATH environment variable.

Default: 0 in Python config, 1 in isolated config.

Added in version 3.11.

wchar_t *base_exec_prefix

sys.base_exec_prefix.

Default: NULL.

Part of the Python Path Configuration output.

wchar_t *base_executable

Python base executable: sys._base_executable.

Set by the __PYVENV_LAUNCHER__ environment variable.

Set from PyConfig.executable if NULL.

Default: NULL.

Part of the Python Path Configuration output.

wchar_t *base_prefix

sys.base_prefix.

Default: NULL.

Part of the Python Path Configuration output.

int buffered_stdio

If equals to 0 and configure_c_stdio is non-zero, disable buffering on the C streams stdout and stderr.

Set to 0 by the -u command line option and the PYTHONUNBUFFERED environment variable.

stdin is always opened in buffered mode.

Default: 1.

int bytes_warning

If equals to 1, issue a warning when comparing bytes or bytearray with str, or comparing bytes with int.

If equal or greater to 2, raise a BytesWarning exception in these cases.

Incremented by the -b command line option.

Default: 0.

int warn_default_encoding

If non-zero, emit a EncodingWarning warning when io.TextIOWrapper uses its default encoding. See Opt-in EncodingWarning for details.

Default: 0.

Added in version 3.10.

int code_debug_ranges

If equals to 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 0 by the PYTHONNODEBUGRANGES environment variable and by the -X no_debug_ranges command line option.

Default: 1.

Added in version 3.11.

wchar_t *check_hash_pycs_mode

Control the validation behavior of hash-based .pyc files: value of the --check-hash-based-pycs command line option.

Valid values:

L"always": Hash the source file for invalidation regardless of value of the 'check_source' flag.

L"never": Assume that hash-based pycs always are valid.

L"default": The 'check_source' flag in hash-based pycs determines invalidation.

Default: L"default".

See also PEP 552 [https://peps.python.org/pep-0552/] "Deterministic pycs".

int configure_c_stdio

If non-zero, configure C standard streams:

On Windows, set the binary mode (O_BINARY) on stdin, stdout and stderr.

If buffered_stdio equals zero, disable buffering of stdin, stdout and stderr streams.

If interactive is non-zero, enable stream buffering on stdin and stdout (only stdout on Windows).

Default: 1 in Python config, 0 in isolated config.

int dev_mode

If non-zero, enable the Python Development Mode.

Set to 1 by the -X dev option and the PYTHONDEVMODE environment variable.

Default: -1 in Python mode, 0 in isolated mode.

int dump_refs

Dump Python references?

If non-zero, dump all objects which are still alive at exit.

Set to 1 by the PYTHONDUMPREFS environment variable.

Need a special build of Python with the Py_TRACE_REFS macro defined: see the configure --with-trace-refs option.

Default: 0.

wchar_t *exec_prefix

The site-specific directory prefix where the platform-dependent Python files are installed: sys.exec_prefix.

Default: NULL.

Part of the Python Path Configuration output.

wchar_t *executable

The absolute path of the executable binary for the Python interpreter: sys.executable.

Default: NULL.

Part of the Python Path Configuration output.

int faulthandler

Enable faulthandler?

If non-zero, call faulthandler.enable() at startup.

Set to 1 by -X faulthandler and the PYTHONFAULTHANDLER environment variable.

Default: -1 in Python mode, 0 in isolated mode.

wchar_t *filesystem_encoding

Filesystem encoding: sys.getfilesystemencoding().

On macOS, Android and VxWorks: use "utf-8" by default.

On Windows: use "utf-8" by default, or "mbcs" if legacy_windows_fs_encoding of PyPreConfig is non-zero.

Default encoding on other platforms:

"utf-8" if PyPreConfig.utf8_mode is non-zero.

"ascii" if Python detects that nl_langinfo(CODESET) announces the ASCII encoding, whereas the mbstowcs() function decodes from a different encoding (usually Latin1).

"utf-8" if nl_langinfo(CODESET) returns an empty string.

Otherwise, use the locale encoding: nl_langinfo(CODESET) result.

At Python startup, the encoding name is normalized to the Python codec name. For example, "ANSI_X3.4-1968" is replaced with "ascii".

See also the filesystem_errors member.

wchar_t *filesystem_errors

Filesystem error handler: sys.getfilesystemencodeerrors().

On Windows: use "surrogatepass" by default, or "replace" if legacy_windows_fs_encoding of PyPreConfig is non-zero.

On other platforms: use "surrogateescape" by default.

Supported error handlers:

"strict"

"surrogateescape"

"surrogatepass" (only supported with the UTF-8 encoding)

See also the filesystem_encoding member.

unsigned long hash_seed

int use_hash_seed

Randomized hash function seed.

If use_hash_seed is zero, a seed is chosen randomly at Python startup, and hash_seed is ignored.

Set by the PYTHONHASHSEED environment variable.

Default use_hash_seed value: -1 in Python mode, 0 in isolated mode.

wchar_t *home

Python home directory.

If Py_SetPythonHome() has been called, use its argument if it is not NULL.

Set by the PYTHONHOME environment variable.

Default: NULL.

Part of the Python Path Configuration input.

int import_time

If non-zero, profile import time.

Set the 1 by the -X importtime option and the PYTHONPROFILEIMPORTTIME environment variable.

Default: 0.

int inspect

Enter interactive mode after executing a script or a command.

If greater than 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 sys.stdin does not appear to be a terminal.

Incremented by the -i command line option. Set to 1 if the PYTHONINSPECT environment variable is non-empty.

Default: 0.

int install_signal_handlers

Install Python signal handlers?

Default: 1 in Python mode, 0 in isolated mode.

int interactive

If greater than 0, enable the interactive mode (REPL).

Incremented by the -i command line option.

Default: 0.

int int_max_str_digits

Configures the integer string conversion length limitation. An initial value of -1 means the value will be taken from the command line or environment or otherwise default to 4300 (sys.int_info.default_max_str_digits). A value of 0 disables the limitation. Values greater than zero but less than 640 (sys.int_info.str_digits_check_threshold) are unsupported and will produce an error.

Configured by the -X int_max_str_digits command line flag or the PYTHONINTMAXSTRDIGITS environment variable.

Default: -1 in Python mode. 4300 (sys.int_info.default_max_str_digits) in isolated mode.

Added in version 3.12.

int isolated

If greater than 0, enable isolated mode:

Set safe_path to 1: don't prepend a potentially unsafe path to sys.path at Python startup, such as the current directory, the script's directory or an empty string.

Set use_environment to 0: ignore PYTHON environment variables.

Set user_site_directory to 0: don't add the user site directory to sys.path.

Python REPL doesn't import readline nor enable default readline configuration on interactive prompts.

Set to 1 by the -I command line option.

Default: 0 in Python mode, 1 in isolated mode.

See also the Isolated Configuration and PyPreConfig.isolated.

int legacy_windows_stdio

If non-zero, use io.FileIO instead of io._WindowsConsoleIO for sys.stdin, sys.stdout and sys.stderr.

PYTHONLEGACYWINDOWSSTDIO 環境変数が空でない文字列に設定された場合に、 1 に設定されます。

Only available on Windows. #ifdef MS_WINDOWS macro can be used for Windows specific code.

Default: 0.

See also the PEP 528 [https://peps.python.org/pep-0528/] (Change Windows console encoding to UTF-8).

int malloc_stats

If non-zero, dump statistics on Python pymalloc memory allocator at exit.

Set to 1 by the PYTHONMALLOCSTATS environment variable.

The option is ignored if Python is configured using the --without-pymalloc option.

Default: 0.

wchar_t *platlibdir

Platform library directory name: sys.platlibdir.

Set by the PYTHONPLATLIBDIR environment variable.

Default: value of the PLATLIBDIR macro which is set by the configure --with-platlibdir option (default: "lib", or "DLLs" on Windows).

Part of the Python Path Configuration input.

Added in version 3.9.

バージョン 3.11 で変更: This macro is now used on Windows to locate the standard library extension modules, typically under DLLs. However, for compatibility, note that this value is ignored for any non-standard layouts, including in-tree builds and virtual environments.

wchar_t *pythonpath_env

Module search paths (sys.path) as a string separated by DELIM (os.pathsep).

Set by the PYTHONPATH environment variable.

Default: NULL.

Part of the Python Path Configuration input.

PyWideStringList module_search_paths

int module_search_paths_set

Module search paths: sys.path.

If module_search_paths_set is equal to 0, Py_InitializeFromConfig() will replace module_search_paths and sets module_search_paths_set to 1.

Default: empty list (module_search_paths) and 0 (module_search_paths_set).

Part of the Python Path Configuration output.

int optimization_level

Compilation optimization level:

0: Peephole optimizer, set __debug__ to True.

1: Level 0, remove assertions, set __debug__ to False.

2: Level 1, strip docstrings.

Incremented by the -O command line option. Set to the PYTHONOPTIMIZE environment variable value.

Default: 0.

PyWideStringList orig_argv

The list of the original command line arguments passed to the Python executable: sys.orig_argv.

If orig_argv list is empty and argv is not a list only containing an empty string, PyConfig_Read() copies argv into orig_argv before modifying argv (if parse_argv is non-zero).

See also the argv member and the Py_GetArgcArgv() function.

Default: empty list.

Added in version 3.10.

int parse_argv

Parse command line arguments?

If equals to 1, parse argv the same way the regular Python parses command line arguments, and strip Python arguments from argv.

The PyConfig_Read() function only parses PyConfig.argv arguments once: PyConfig.parse_argv is set to 2 after arguments are parsed. Since Python arguments are strippped from PyConfig.argv, parsing arguments twice would parse the application options as Python options.

Default: 1 in Python mode, 0 in isolated mode.

バージョン 3.10 で変更: The PyConfig.argv arguments are now only parsed if PyConfig.parse_argv equals to 1.

int parser_debug

Parser debug mode. If greater than 0, turn on parser debugging output (for expert only, depending on compilation options).

Incremented by the -d command line option. Set to the PYTHONDEBUG environment variable value.

Need a debug build of Python (the Py_DEBUG macro must be defined).

Default: 0.

int pathconfig_warnings

If non-zero, calculation of path configuration is allowed to log warnings into stderr. If equals to 0, suppress these warnings.

Default: 1 in Python mode, 0 in isolated mode.

Part of the Python Path Configuration input.

バージョン 3.11 で変更: Now also applies on Windows.

wchar_t *prefix

The site-specific directory prefix where the platform independent Python files are installed: sys.prefix.

Default: NULL.

Part of the Python Path Configuration output.

wchar_t *program_name

Program name used to initialize executable and in early error messages during Python initialization.

If Py_SetProgramName() has been called, use its argument.

On macOS, use PYTHONEXECUTABLE environment variable if set.

If the WITH_NEXT_FRAMEWORK macro is defined, use __PYVENV_LAUNCHER__ environment variable if set.

Use argv[0] of argv if available and non-empty.

Otherwise, use L"python" on Windows, or L"python3" on other platforms.

Default: NULL.

Part of the Python Path Configuration input.

wchar_t *pycache_prefix

Directory where cached .pyc files are written: sys.pycache_prefix.

Set by the -X pycache_prefix=PATH command line option and the PYTHONPYCACHEPREFIX environment variable.

If NULL, sys.pycache_prefix is set to None.

Default: NULL.

int quiet

Quiet mode. If greater than 0, don't display the copyright and version at Python startup in interactive mode.

Incremented by the -q command line option.

Default: 0.

wchar_t *run_command

Value of the -c command line option.

Used by Py_RunMain().

Default: NULL.

wchar_t *run_filename

Filename passed on the command line: trailing command line argument without -c or -m. It is used by the Py_RunMain() function.

For example, it is set to script.py by the python3 script.py arg command line.

See also the PyConfig.skip_source_first_line option.

Default: NULL.

wchar_t *run_module

Value of the -m command line option.

Used by Py_RunMain().

Default: NULL.

int show_ref_count

Show total reference count at exit (excluding immortal objects)?

Set to 1 by -X showrefcount command line option.

Need a debug build of Python (the Py_REF_DEBUG macro must be defined).

Default: 0.

int site_import

Import the site module at startup?

If equal to zero, disable the import of the module site and the site-dependent manipulations of sys.path that it entails.

Also disable these manipulations if the site module is explicitly imported later (call site.main() if you want them to be triggered).

Set to 0 by the -S command line option.

sys.flags.no_site is set to the inverted value of site_import.

Default: 1.

int skip_source_first_line

If non-zero, skip the first line of the PyConfig.run_filename source.

It allows the usage of non-Unix forms of #!cmd. This is intended for a DOS specific hack only.

Set to 1 by the -x command line option.

Default: 0.

wchar_t *stdio_encoding

wchar_t *stdio_errors

Encoding and encoding errors of sys.stdin, sys.stdout and sys.stderr (but sys.stderr always uses "backslashreplace" error handler).

If Py_SetStandardStreamEncoding() has been called, use its error and errors arguments if they are not NULL.

Use the PYTHONIOENCODING environment variable if it is non-empty.

Default encoding:

"UTF-8" if PyPreConfig.utf8_mode is non-zero.

Otherwise, use the locale encoding.

Default error handler:

On Windows: use "surrogateescape".

"surrogateescape" if PyPreConfig.utf8_mode is non-zero, or if the LC_CTYPE locale is "C" or "POSIX".

"strict" otherwise.

int tracemalloc

Enable tracemalloc?

If non-zero, call tracemalloc.start() at startup.

Set by -X tracemalloc=N command line option and by the PYTHONTRACEMALLOC environment variable.

Default: -1 in Python mode, 0 in isolated mode.

int perf_profiling

Enable compatibility mode with the perf profiler?

If non-zero, initialize the perf trampoline. See Python support for the Linux perf profiler for more information.

Set by -X perf command line option and by the PYTHONPERFSUPPORT environment variable.

Default: -1.

Added in version 3.12.

int use_environment

Use environment variables?

If equals to zero, ignore the environment variables.

Set to 0 by the -E environment variable.

Default: 1 in Python config and 0 in isolated config.

int user_site_directory

If non-zero, add the user site directory to sys.path.

Set to 0 by the -s and -I command line options.

Set to 0 by the PYTHONNOUSERSITE environment variable.

Default: 1 in Python mode, 0 in isolated mode.

int verbose

Verbose mode. If greater than 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 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 -v command line option.

Set by the PYTHONVERBOSE environment variable value.

Default: 0.

PyWideStringList warnoptions

Options of the warnings module to build warnings filters, lowest to highest priority: sys.warnoptions.

The warnings module adds sys.warnoptions in the reverse order: the last PyConfig.warnoptions item becomes the first item of warnings.filters which is checked first (highest priority).

The -W command line options adds its value to warnoptions, it can be used multiple times.

The PYTHONWARNINGS environment variable can also be used to add warning options. Multiple options can be specified, separated by commas (,).

Default: empty list.

int write_bytecode

If equal to 0, Python won't try to write .pyc files on the import of source modules.

Set to 0 by the -B command line option and the PYTHONDONTWRITEBYTECODE environment variable.

sys.dont_write_bytecode is initialized to the inverted value of write_bytecode.

Default: 1.

PyWideStringList xoptions

Values of the -X command line options: sys._xoptions.

Default: empty list.

If parse_argv is non-zero, argv arguments are parsed the same way the regular Python parses command line arguments, and Python arguments are stripped from argv.

The xoptions options are parsed to set other options: see the -X command line option.

バージョン 3.9 で変更: The show_alloc_count field has been removed.

Initialization with PyConfig

Function to initialize Python:

PyStatus Py_InitializeFromConfig(const PyConfig *config)

Initialize Python from config configuration.

The caller is responsible to handle exceptions (error or exit) using PyStatus_Exception() and Py_ExitStatusException().

If PyImport_FrozenModules(), PyImport_AppendInittab() or PyImport_ExtendInittab() are used, they must be set or called after Python preinitialization and before the Python initialization. If Python is initialized multiple times, PyImport_AppendInittab() or PyImport_ExtendInittab() must be called before each Python initialization.

The current configuration (PyConfig type) is stored in PyInterpreterState.config.

Example setting the program name:

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);
}

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:

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;
}

Isolated Configuration

PyPreConfig_InitIsolatedConfig() and 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 (PyConfig.argv is not parsed) and user site directory. The C standard streams (ex: 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 PyConfig.home is specified to avoid computing the default path configuration.

Python Configuration

PyPreConfig_InitPythonConfig() and 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 (PEP 538 [https://peps.python.org/pep-0538/]) and Python UTF-8 Mode (PEP 540 [https://peps.python.org/pep-0540/]) depending on the LC_CTYPE locale, PYTHONUTF8 and PYTHONCOERCECLOCALE environment variables.

Python Path Configuration

PyConfig contains multiple fields for the path configuration:

Path configuration inputs:

PyConfig.home

PyConfig.platlibdir

PyConfig.pathconfig_warnings

PyConfig.program_name

PyConfig.pythonpath_env

current working directory: to get absolute paths

PATH environment variable to get the program full path (from PyConfig.program_name)

__PYVENV_LAUNCHER__ environment variable

(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).

Path configuration output fields:

PyConfig.base_exec_prefix

PyConfig.base_executable

PyConfig.base_prefix

PyConfig.exec_prefix

PyConfig.executable

PyConfig.module_search_paths_set, PyConfig.module_search_paths

PyConfig.prefix

If at least one "output field" is not set, Python calculates the path configuration to fill unset fields. If module_search_paths_set is equal to 0, module_search_paths is overridden and module_search_paths_set is set to 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. module_search_paths is considered as set if module_search_paths_set is set to 1. In this case, module_search_paths will be used without modification.

Set pathconfig_warnings to 0 to suppress warnings when calculating the path configuration (Unix only, Windows does not log any warning).

If base_prefix or base_exec_prefix fields are not set, they inherit their value from prefix and exec_prefix respectively.

Py_RunMain() and Py_Main() modify sys.path:

If run_filename is set and is a directory which contains a __main__.py script, prepend run_filename to sys.path.

If isolated is zero:

If run_module is set, prepend the current directory to sys.path. Do nothing if the current directory cannot be read.

If run_filename is set, prepend the directory of the filename to sys.path.

Otherwise, prepend an empty string to sys.path.

If site_import is non-zero, sys.path can be modified by the site module. If user_site_directory is non-zero and the user's site-package directory exists, the site module appends the user's site-package directory to sys.path.

The following configuration files are used by the path configuration:

pyvenv.cfg

._pth file (ex: python._pth)

pybuilddir.txt (Unix only)

If a ._pth file is present:

Set isolated to 1.

Set use_environment to 0.

Set site_import to 0.

Set safe_path to 1.

The __PYVENV_LAUNCHER__ environment variable is used to set PyConfig.base_executable

Py_RunMain()

int Py_RunMain(void)

Execute the command (PyConfig.run_command), the script (PyConfig.run_filename) or the module (PyConfig.run_module) specified on the command line or in the configuration.

By default and when if -i option is used, run the REPL.

Finally, finalizes Python and returns an exit status that can be passed to the exit() function.

See Python Configuration for an example of customized Python always running in isolated mode using Py_RunMain().

Py_GetArgcArgv()

void Py_GetArgcArgv(int *argc, wchar_t ***argv)

Get the original command line arguments, before Python modified them.

See also PyConfig.orig_argv member.

Multi-Phase Initialization Private Provisional API

This section is a private provisional API introducing multi-phase initialization, the core feature of PEP 432 [https://peps.python.org/pep-0432/]:

"Core" initialization phase, "bare minimum Python":

Builtin types;

Builtin exceptions;

Builtin and frozen modules;

The sys module is only partially initialized (ex: sys.path doesn't exist yet).

"Main" initialization phase, Python is fully initialized:

Install and configure importlib;

Apply the Path Configuration;

Install signal handlers;

Finish sys module initialization (ex: create sys.stdout and sys.path);

Enable optional features like faulthandler and tracemalloc;

Import the site module;

etc.

Private provisional API:

PyConfig._init_main: if set to 0, Py_InitializeFromConfig() stops at the "Core" initialization phase.

PyStatus _Py_InitializeMain(void)

Move to the "Main" initialization phase, finish the Python initialization.

No module is imported during the "Core" phase and the importlib module is not configured: the Path Configuration is only applied during the "Main" phase. It may allow to customize Python in Python to override or tune the Path Configuration, maybe install a custom sys.meta_path importer or an import hook, etc.

It may become possible to calculate the Path Configuration in Python, after the Core phase and before the Main phase, which is one of the PEP 432 [https://peps.python.org/pep-0432/] motivation.

The "Core" phase is not properly defined: what should be and what should not be available at this phase is not specified yet. The API is marked as private and provisional: the API can be modified or even be removed anytime until a proper public API is designed.

Example running Python code between "Core" and "Main" initialization phases:

void init_python(void)
{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&config);
    config._init_main = 0;

    /* ... customize 'config' configuration ... */

    status = Py_InitializeFromConfig(&config);
    PyConfig_Clear(&config);
    if (PyStatus_Exception(status)) {
        Py_ExitStatusException(status);
    }

    /* Use sys.stderr because sys.stdout is only created
       by _Py_InitializeMain() */
    int res = PyRun_SimpleString(
        "import sys; "
        "print('Run Python code before _Py_InitializeMain', "
               "file=sys.stderr)");
    if (res < 0) {
        exit(1);
    }

    /* ... put more configuration code here ... */

    status = _Py_InitializeMain();
    if (PyStatus_Exception(status)) {
        Py_ExitStatusException(status);
    }
}

メモリ管理

概要

Python におけるメモリ管理には、全ての Python オブジェクトとデータ構造が入ったプライベートヒープ (private heap) が必須です。プライベートヒープの管理は、内部的には Python メモリマネージャ (Python memory manager) が確実に行います。Python メモリマネージャには、共有 (sharing)、セグメント分割 (segmentation)、事前割り当て (preallocation)、キャッシュ化 (caching) といった、様々な動的記憶管理の側面を扱うために、個別のコンポーネントがあります。

最低水準層では、素のメモリ操作関数 (raw memory allocator) がオペレーティングシステムのメモリ管理機構とやりとりして、プライベートヒープ内にPython 関連の全てのデータを記憶するのに十分な空きがあるかどうか確認します。素のメモリ操作関数の上には、いくつかのオブジェクト固有のメモリ操作関数があります。これらは同じヒープを操作し、各オブジェクト型固有の事情に合ったメモリ管理ポリシを実装しています。例えば、整数オブジェクトは文字列やタプル、辞書とは違ったやり方でヒープ内で管理されます。というのも、整数には値を記憶する上で特別な要件があり、速度/容量のトレードオフが存在するからです。このように、Python メモリマネジャは作業のいくつかをオブジェクト固有のメモリ操作関数に委譲しますが、これらの関数がプライベートヒープからはみ出してメモリ管理を行わないようにしています。

重要なのは、たとえユーザがいつもヒープ内のメモリブロックを指すようなオブジェクトポインタを操作しているとしても、Python 用ヒープの管理はインタプリタ自体が行うもので、ユーザがそれを制御する余地はないと理解することです。Python オブジェクトや内部使用されるバッファを入れるためのヒープ空間のメモリ確保は、必要に応じて、Python メモリマネージャがこのドキュメント内で列挙しているPython/C API 関数群を介して行います。

メモリ管理の崩壊を避けるため、拡張モジュールの作者は決して Python オブジェクトを C ライブラリが公開している関数: malloc() 、 calloc() 、 realloc() および free() で操作しようとしてはなりません。こうした関数を使うと、C のメモリ操作関数と Python メモリマネージャとの間で関数呼び出しが交錯します。 C のメモリ操作関数とPython メモリマネージャは異なるアルゴリズムで実装されていて、異なるヒープを操作するため、呼び出しの交錯は致命的な結果を招きます。とはいえ、個別の目的のためなら、 C ライブラリのメモリ操作関数を使って安全にメモリを確保したり解放したりできます。例えば、以下がそのような例です:

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;

この例では、I/O バッファに対するメモリ要求は C ライブラリのメモリ操作関数を使っています。Python メモリマネージャーは戻り値として返される bytes オブジェクトを確保する時にだけ必要です。

とはいえ、ほとんどの状況では、メモリの操作は Python ヒープに固定して行うよう勧めます。なぜなら、Python ヒープは Python メモリマネジャの管理下にあるからです。例えば、インタプリタを C で書かれた新たなオブジェクト型で拡張する際には、ヒープでのメモリ管理が必要です。Python ヒープを使った方がよいもう一つの理由として、拡張モジュールが必要としているメモリについて Python メモリマネージャに 情報を提供 してほしいということがあります。たとえ必要なメモリが内部的かつ非常に特化した用途に対して排他的に用いられるものだとしても、全てのメモリ操作要求を Python メモリマネージャに委譲すれば、インタプリタはより正確なメモリフットプリントの全体像を把握できます。その結果、特定の状況では、Python メモリマネージャがガベージコレクションやメモリのコンパクト化、その他何らかの予防措置といった、適切な動作をトリガできることがあります。上の例で示したように C ライブラリのメモリ操作関数を使うと、I/O バッファ用に確保したメモリは Python メモリマネージャの管理から完全に外れることに注意してください。

参考

環境変数 PYTHONMALLOC を使用して Python が利用するメモリアロケータを制御することができます。

環境変数 PYTHONMALLOCSTATS を使用して、新たなオブジェクトアリーナが生成される時と、シャットダウン時に pymalloc メモリアロケータ の統計情報を表示できます。

Allocator Domains

All allocating functions belong to one of three different "domains" (see also 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 here. There is no hard requirement to use the memory returned by the allocation functions belonging to a given domain for only the purposes hinted by that domain (although this is the recommended practice). For example, one could use the memory returned by PyMem_RawMalloc() for allocating Python objects or the memory returned by PyObject_Malloc() for allocating memory for buffers.

The three allocation domains are:

Raw domain: intended for allocating memory for general-purpose memory buffers where the allocation must go to the system allocator or where the allocator can operate without the GIL. The memory is requested directly to the system.

"Mem" domain: intended for allocating memory for Python buffers and general-purpose memory buffers where the allocation must be performed with the GIL held. The memory is taken from the Python private heap.

Object domain: intended for allocating memory belonging to Python objects. The memory is taken from the Python private heap.

When freeing memory previously allocated by the allocating functions belonging to a given domain,the matching specific deallocating functions must be used. For example, PyMem_Free() must be used to free memory allocated using PyMem_Malloc().

生メモリインターフェース

以下の関数群はシステムのアロケータをラップします。これらの関数はスレッドセーフで、 GIL を保持していなくても呼び出すことができます。

The default raw memory allocator uses the following functions: malloc(), calloc(), realloc() and free(); call malloc(1) (or calloc(1, 1)) when requesting zero bytes.

Added in version 3.4.

void *PyMem_RawMalloc(size_t n)

n バイトを割り当て、そのメモリを指す void* 型のポインタを返します。要求が失敗した場合 NULL を返します。

0バイトを要求すると、 PyMem_RawMalloc(1) が呼ばれたときと同じように、可能なら NULL でないユニークなポインタを返します。確保されたメモリーにはいかなる初期化も行われません。

void *PyMem_RawCalloc(size_t nelem, size_t elsize)

各要素が elsize バイトの要素 nelem 個分のメモリーを確保し、そのメモリーを指す void* 型のポインタを返します。アロケートに失敗した場合は NULL を返します。確保されたメモリー領域はゼロで初期化されます。

要素数か要素のサイズが0バイトの要求に対しては、可能なら PyMem_RawCalloc(1, 1) が呼ばれたのと同じように、ユニークな NULL でないポインタを返します。

Added in version 3.5.

void *PyMem_RawRealloc(void *p, size_t n)

p が指すメモリブロックを n バイトにリサイズします。古いサイズと新しいサイズの小さい方までの内容は変更されません。

p が NULL の場合呼び出しは PyMem_RawMalloc(n) と等価です。そうでなく、 n がゼロに等しい場合、メモリブロックはリサイズされますが解放されません。返されたポインタは非 NULL です。

p が NULL でない限り、p はそれより前の PyMem_RawMalloc(), PyMem_RawRealloc(), PyMem_RawCalloc() の呼び出しにより返されなければなりません。

要求が失敗した場合 PyMem_RawRealloc() は NULL を返し、 p は前のメモリエリアをさす有効なポインタのままです。

void PyMem_RawFree(void *p)

p が指すメモリブロックを解放します。 p は以前呼び出した PyMem_RawMalloc(), PyMem_RawRealloc(), PyMem_RawCalloc() の返した値でなければなりません。それ以外の場合や PyMem_RawFree(p) を呼び出した後だった場合、未定義の動作になります。

p が NULL の場合何もしません。

メモリインターフェース

以下の関数群が利用して Python ヒープに対してメモリを確保したり解放したり出来ます。これらの関数は ANSI C 標準に従ってモデル化されていますが、0 バイトを要求した際の動作についても定義しています:

The default memory allocator uses the pymalloc memory allocator.

警告

これらの関数を呼ぶときには、 GIL を保持しておく必要があります。

バージョン 3.6 で変更: デフォルトのアロケータがシステムの malloc() から pymalloc になりました。

void *PyMem_Malloc(size_t n)

Part of the Stable ABI.

n バイトを割り当て、そのメモリを指す void* 型のポインタを返します。要求が失敗した場合 NULL を返します。

0バイトを要求すると、 PyMem_Malloc(1) が呼ばれたときと同じように、可能なら NULL でないユニークなポインタを返します。確保されたメモリーにはいかなる初期化も行われません。

void *PyMem_Calloc(size_t nelem, size_t elsize)

Part of the Stable ABI since version 3.7.

各要素が elsize バイトの要素 nelem 個分のメモリーを確保し、そのメモリーを指す void* 型のポインタを返します。アロケートに失敗した場合は NULL を返します。確保されたメモリー領域はゼロで初期化されます。

要素数か要素のサイズが0バイトの要求に対しては、可能なら PyMem_Calloc(1, 1) が呼ばれたのと同じように、ユニークな NULL でないポインタを返します。

Added in version 3.5.

void *PyMem_Realloc(void *p, size_t n)

Part of the Stable ABI.

p が指すメモリブロックを n バイトにリサイズします。古いサイズと新しいサイズの小さい方までの内容は変更されません。

p が NULL の場合呼び出しは PyMem_Malloc(n) と等価です。そうでなく、 n がゼロに等しい場合、メモリブロックはリサイズされますが解放されません。返されたポインタは非 NULL です。

p が NULL でない限り、p はそれより前の PyMem_Malloc(), PyMem_Realloc() または PyMem_Calloc() の呼び出しにより返されなければなりません。

要求が失敗した場合 PyMem_Realloc() は NULL を返し、 p は前のメモリエリアをさす有効なポインタのままです。

void PyMem_Free(void *p)

Part of the Stable ABI.

p が指すメモリブロックを解放します。 p は以前呼び出した PyMem_Malloc()、 PyMem_Realloc()、または PyMem_Calloc() の返した値でなければなりません。それ以外の場合や PyMem_Free(p) を呼び出した後だった場合、未定義の動作になります。

p が NULL の場合何もしません。

以下に挙げる型対象のマクロは利便性のために提供されているものです。TYPE は任意の C の型を表します。

PyMem_New(TYPE, n)

Same as PyMem_Malloc(), but allocates (n * sizeof(TYPE)) bytes of memory. Returns a pointer cast to TYPE*. The memory will not have been initialized in any way.

PyMem_Resize(p, TYPE, n)

Same as PyMem_Realloc(), but the memory block is resized to (n * sizeof(TYPE)) bytes. Returns a pointer cast to TYPE*. On return, p will be a pointer to the new memory area, or NULL in the event of failure.

これは C プリプロセッサマクロです。p は常に再代入されます。エラー処理時にメモリを失うのを避けるには p の元の値を保存してください。

void PyMem_Del(void *p)

PyMem_Free() と同じです。

上記に加えて、C API 関数を介することなく Python メモリ操作関数を直接呼び出すための以下のマクロセットが提供されています。ただし、これらのマクロは Python バージョン間でのバイナリ互換性を保てず、それゆえに拡張モジュールでは撤廃されているので注意してください。

PyMem_MALLOC(size)

PyMem_NEW(type, size)

PyMem_REALLOC(ptr, size)

PyMem_RESIZE(ptr, type, size)

PyMem_FREE(ptr)

PyMem_DEL(ptr)

オブジェクトアロケータ

以下の関数群が利用して Python ヒープに対してメモリを確保したり解放したり出来ます。これらの関数は ANSI C 標準に従ってモデル化されていますが、0 バイトを要求した際の動作についても定義しています:

注釈

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 Customize Memory Allocators section.

The default object allocator uses the pymalloc memory allocator.

警告

これらの関数を呼ぶときには、 GIL を保持しておく必要があります。

void *PyObject_Malloc(size_t n)

Part of the Stable ABI.

n バイトを割り当て、そのメモリを指す void* 型のポインタを返します。要求が失敗した場合 NULL を返します。

0バイトを要求すると、 PyObject_Malloc(1) が呼ばれたときと同じように、可能なら NULL でないユニークなポインタを返します。確保されたメモリーにはいかなる初期化も行われません。

void *PyObject_Calloc(size_t nelem, size_t elsize)

Part of the Stable ABI since version 3.7.

各要素が elsize バイトの要素 nelem 個分のメモリーを確保し、そのメモリーを指す void* 型のポインタを返します。アロケートに失敗した場合は NULL を返します。確保されたメモリー領域はゼロで初期化されます。

要素数か要素のサイズが0バイトの要求に対しては、可能なら PyObject_Calloc(1, 1) が呼ばれたのと同じように、ユニークな NULL でないポインタを返します。

Added in version 3.5.

void *PyObject_Realloc(void *p, size_t n)

Part of the Stable ABI.

p が指すメモリブロックを n バイトにリサイズします。古いサイズと新しいサイズの小さい方までの内容は変更されません。

p が NULL の場合呼び出しは PyObject_Malloc(n) と等価です。そうでなく、 n がゼロに等しい場合、メモリブロックはリサイズされますが解放されません。返されたポインタは非 NULL です。

p が NULL でない限り、p はそれより前の PyObject_Malloc(), PyObject_Realloc() または PyObject_Calloc() の呼び出しにより返されなければなりません。

要求が失敗した場合 PyObject_Realloc() は NULL を返し、 p は前のメモリエリアをさす有効なポインタのままです。

void PyObject_Free(void *p)

Part of the Stable ABI.

p が指すメモリブロックを解放します。 p は以前呼び出した PyObject_Malloc()、 PyObject_Realloc()、または PyObject_Calloc() の返した値でなければなりません。それ以外の場合や PyObject_Free(p) を呼び出した後だった場合、未定義の動作になります。

p が NULL の場合何もしません。

Default Memory Allocators

Default memory allocators:

Configuration

名前

PyMem_RawMalloc

PyMem_Malloc

PyObject_Malloc

リリースビルド

"pymalloc"

malloc

pymalloc

pymalloc

デバッグビルド

"pymalloc_debug"

malloc + debug

pymalloc + debug

pymalloc + debug

pymalloc 無しのリリースビルド

"malloc"

malloc

malloc

malloc

pymalloc 無しのデバッグビルド

"malloc_debug"

malloc + debug

malloc + debug

malloc + debug

説明:

Name: value for PYTHONMALLOC environment variable.

malloc: system allocators from the standard C library, C functions: malloc(), calloc(), realloc() and free().

pymalloc: pymalloc memory allocator.

"+ debug": with debug hooks on the Python memory allocators.

"Debug build": Python build in debug mode.

メモリアロケータをカスタマイズする

Added in version 3.4.

type PyMemAllocatorEx

Structure used to describe a memory block allocator. The structure has the following fields:

フィールド

意味

void *ctx

第一引数として渡されるユーザコンテキスト

void* malloc(void *ctx, size_t size)

メモリブロックを割り当てます

void* calloc(void *ctx, size_t nelem, size_t elsize)

0で初期化されたメモリブロックを割り当てます

void* realloc(void *ctx, void *ptr, size_t new_size)

メモリブロックを割り当てるかリサイズします

void free(void *ctx, void *ptr)

メモリブロックを解放する

バージョン 3.5 で変更: The PyMemAllocator structure was renamed to PyMemAllocatorEx and a new calloc field was added.

type PyMemAllocatorDomain

アロケータドメインを同定するための列挙型です。ドメインは:

PYMEM_DOMAIN_RAW

関数:

PyMem_RawMalloc()

PyMem_RawRealloc()

PyMem_RawCalloc()

PyMem_RawFree()

PYMEM_DOMAIN_MEM

関数:

PyMem_Malloc(),

PyMem_Realloc()

PyMem_Calloc()

PyMem_Free()

PYMEM_DOMAIN_OBJ

関数:

PyObject_Malloc()

PyObject_Realloc()

PyObject_Calloc()

PyObject_Free()

void PyMem_GetAllocator(PyMemAllocatorDomain domain, PyMemAllocatorEx *allocator)

指定されたドメインのメモリブロックアロケータを取得します。

void PyMem_SetAllocator(PyMemAllocatorDomain domain, PyMemAllocatorEx *allocator)

指定されたドメインのメモリブロックアロケータを設定します。

新しいアロケータは、0バイトを要求されたときユニークな NULL でないポインタを返さなければなりません。

For the PYMEM_DOMAIN_RAW domain, the allocator must be thread-safe: the GIL is not held when the allocator is called.

For the remaining domains, the allocator must also be thread-safe: the allocator may be called in different interpreters that do not share a GIL.

新しいアロケータがフックでない (1つ前のアロケータを呼び出さない) 場合、 PyMem_SetupDebugHooks() 関数を呼び出して、新しいアロケータの上にデバッグフックを再度設置しなければなりません。

See also PyPreConfig.allocator and Preinitialize Python with PyPreConfig.

警告

PyMem_SetAllocator() does have the following contract:

It can be called after Py_PreInitialize() and before Py_InitializeFromConfig() to install a custom memory allocator. There are no restrictions over the installed allocator other than the ones imposed by the domain (for instance, the Raw Domain allows the allocator to be called without the GIL held). See the section on allocator domains for more information.

If called after Python has finish initializing (after Py_InitializeFromConfig() has been called) the allocator must wrap the existing allocator. Substituting the current allocator for some other arbitrary one is not supported.

バージョン 3.12 で変更: All allocators must be thread-safe.

void PyMem_SetupDebugHooks(void)

Setup debug hooks in the Python memory allocators to detect memory errors.

Debug hooks on the Python memory allocators

When Python is built in debug mode, the PyMem_SetupDebugHooks() function is called at the Python preinitialization to setup debug hooks on Python memory allocators to detect memory errors.

The PYTHONMALLOC environment variable can be used to install debug hooks on a Python compiled in release mode (ex: PYTHONMALLOC=debug).

The PyMem_SetupDebugHooks() function can be used to set debug hooks after calling PyMem_SetAllocator().

These debug hooks fill dynamically allocated memory blocks with special, recognizable bit patterns. Newly allocated memory is filled with the byte 0xCD (PYMEM_CLEANBYTE), freed memory is filled with the byte 0xDD (PYMEM_DEADBYTE). Memory blocks are surrounded by "forbidden bytes" filled with the byte 0xFD (PYMEM_FORBIDDENBYTE). Strings of these bytes are unlikely to be valid addresses, floats, or ASCII strings.

実行時チェック:

Detect API violations. For example, detect if PyObject_Free() is called on a memory block allocated by PyMem_Malloc().

Detect write before the start of the buffer (buffer underflow).

Detect write after the end of the buffer (buffer overflow).

Check that the GIL is held when allocator functions of PYMEM_DOMAIN_OBJ (ex: PyObject_Malloc()) and PYMEM_DOMAIN_MEM (ex: PyMem_Malloc()) domains are called.

On error, the debug hooks use the tracemalloc module to get the traceback where a memory block was allocated. The traceback is only displayed if tracemalloc is tracing Python memory allocations and the memory block was traced.

Let S = sizeof(size_t). 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 (p[i:j] means the slice of bytes from *(p+i) inclusive up to *(p+j) exclusive; note that the treatment of negative indices differs from a Python slice):

p[-2*S:-S]

Number of bytes originally asked for. This is a size_t, big-endian (easier to read in a memory dump).

p[-S]

API identifier (ASCII character):

'r' for PYMEM_DOMAIN_RAW.

'm' for PYMEM_DOMAIN_MEM.

'o' for PYMEM_DOMAIN_OBJ.

p[-S+1:0]

Copies of PYMEM_FORBIDDENBYTE. Used to catch under- writes and reads.

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.

p[N:N+S]

Copies of PYMEM_FORBIDDENBYTE. Used to catch over- writes and reads.

p[N+S:N+2*S]

Only used if the 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 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.

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 PyMem_SetupDebugHooks() function now also works on Python compiled in release mode. On error, the debug hooks now use tracemalloc to get the traceback where a memory block was allocated. The debug hooks now also check if the GIL is held when functions of PYMEM_DOMAIN_OBJ and PYMEM_DOMAIN_MEM domains are called.

バージョン 3.8 で変更: Byte patterns 0xCB (PYMEM_CLEANBYTE), 0xDB (PYMEM_DEADBYTE) and 0xFB (PYMEM_FORBIDDENBYTE) have been replaced with 0xCD, 0xDD and 0xFD to use the same values than Windows CRT debug malloc() and free().

pymalloc アロケータ

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 PyMem_RawMalloc() and PyMem_RawRealloc() for allocations larger than 512 bytes.

pymalloc is the default allocator of the PYMEM_DOMAIN_MEM (ex: PyMem_Malloc()) and PYMEM_DOMAIN_OBJ (ex: PyObject_Malloc()) domains.

アリーナアロケータは、次の関数を使います:

VirtualAlloc() and VirtualFree() on Windows,

mmap() and munmap() if available,

それ以外の場合は malloc() と free()。

This allocator is disabled if Python is configured with the --without-pymalloc option. It can also be disabled at runtime using the PYTHONMALLOC environment variable (ex: PYTHONMALLOC=malloc).

pymalloc アリーナアロケータのカスタマイズ

Added in version 3.4.

type PyObjectArenaAllocator

アリーナアロケータを記述するための構造体です。3つのフィールドを持ちます:

フィールド

意味

void *ctx

第一引数として渡されるユーザコンテキスト

void* alloc(void *ctx, size_t size)

size バイトのアリーナを割り当てます

void free(void *ctx, void *ptr, size_t size)

アリーナを解放します

void PyObject_GetArenaAllocator(PyObjectArenaAllocator *allocator)

アリーナアロケータを取得します。

void PyObject_SetArenaAllocator(PyObjectArenaAllocator *allocator)

アリーナアロケータを設定します。

tracemalloc C API

Added in version 3.7.

int PyTraceMalloc_Track(unsigned int domain, uintptr_t ptr, size_t size)

Track an allocated memory block in the tracemalloc module.

Return 0 on success, return -1 on error (failed to allocate memory to store the trace). Return -2 if tracemalloc is disabled.

If memory block is already tracked, update the existing trace.

int PyTraceMalloc_Untrack(unsigned int domain, uintptr_t ptr)

Untrack an allocated memory block in the tracemalloc module. Do nothing if the block was not tracked.

Return -2 if tracemalloc is disabled, otherwise return 0.

使用例

最初に述べた関数セットを使って、 概要 節の例を Python ヒープに I/O バッファをメモリ確保するように書き換えたものを以下に示します:

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;

同じコードを型対象の関数セットで書いたものを以下に示します:

PyObject *res;
char *buf = PyMem_New(char, BUFSIZ); /* for I/O */

if (buf == NULL)
    return PyErr_NoMemory();
/* ...Do some I/O operation involving buf... */
res = PyBytes_FromString(buf);
PyMem_Del(buf); /* allocated with PyMem_New */
return res;

上の二つの例では、バッファを常に同じ関数セットに属する関数で操作していることに注意してください。実際、あるメモリブロックに対する操作は、異なるメモリ操作機構を混用する危険を減らすために、同じメモリ API ファミリを使って行うことが必要です。以下のコードには二つのエラーがあり、そのうちの一つには異なるヒープを操作する別のメモリ操作関数を混用しているので 致命的 (Fatal) とラベルづけをしています。

char *buf1 = PyMem_New(char, BUFSIZ);
char *buf2 = (char *) malloc(BUFSIZ);
char *buf3 = (char *) PyMem_Malloc(BUFSIZ);
...
PyMem_Del(buf3);  /* Wrong -- should be PyMem_Free() */
free(buf2);       /* Right -- allocated via malloc() */
free(buf1);       /* Fatal -- should be PyMem_Del()  */

In addition to the functions aimed at handling raw memory blocks from the Python heap, objects in Python are allocated and released with PyObject_New, PyObject_NewVar and PyObject_Del().

これらの関数については、次章の C による新しいオブジェクト型の定義や実装に関する記述の中で説明します。

オブジェクト実装サポート (object implementation support)

この章では、新しいオブジェクトの型を定義する際に使われる関数、型、およびマクロについて説明します。

オブジェクトをヒープ上にメモリ確保する

共通のオブジェクト構造体 (common object structure)

Base object types and macros

Implementing functions and methods

Accessing attributes of extension types

Member flags

Member types

Defining Getters and Setters

型オブジェクト

クイックリファレンス

tp スロット

sub-slots

スロットの定義型 (typedef)

PyTypeObject 定義

PyObject スロット

PyVarObject スロット

PyTypeObject スロット

Static Types

Heap Types

数値オブジェクト構造体

マップオブジェクト構造体

シーケンスオブジェクト構造体

バッファオブジェクト構造体 (buffer object structure)

async オブジェクト構造体

Slot Type typedefs

使用例

循環参照ガベージコレクションをサポートする

Controlling the Garbage Collector State

Querying Garbage Collector State

オブジェクトをヒープ上にメモリ確保する

PyObject *_PyObject_New(PyTypeObject *type)

Return value: New reference.

PyVarObject *_PyObject_NewVar(PyTypeObject *type, Py_ssize_t size)

Return value: New reference.

PyObject *PyObject_Init(PyObject *op, PyTypeObject *type)

Return value: Borrowed reference. Part of the Stable ABI.

新たにメモリ確保されたオブジェクト op に対し、型と初期状態での参照 (initial reference) を初期化します。初期化されたオブジェクトを返します。type からそのオブジェクトが循環参照ガベージ検出の機能を有する場合、検出機構が監視対象とするオブジェクトのセットに追加されます。オブジェクトの他のフィールドには影響を及ぼしません。

PyVarObject *PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)

Return value: Borrowed reference. Part of the Stable ABI.

PyObject_Init() の全ての処理を行い、可変サイズオブジェクトの場合には長さ情報も初期化します。

PyObject_New(TYPE, typeobj)

C の構造体型 TYPE と Python の型オブジェクト typeobj ( PyTypeObject* ) を用いて Python オブジェクトの領域を新規確保します。Python のオブジェクトヘッダに定義されていないフィールドは初期化されません。呼び出し元がオブジェクトへの唯一の参照を持ちます（つまり、参照カウントは１になります）。メモリ割り当ての大きさは型オブジェクトの tp_basicsize フィールドによって定められます。

PyObject_NewVar(TYPE, typeobj, size)

C の構造体型 TYPE と Python の型オブジェクト typeobj ( PyTypeObject* ) を用いて Python オブジェクトの領域を新規確保します。Python のオブジェクトヘッダに定義されていないフィールドは初期化されません。確保されたメモリには、 TYPE 構造体に加え、 typeobj の tp_itemsize フィールドによって定められた大きさのフィールドを size ( Py_ssize_t ) 個分格納できます。これはタプルなどの、生成時に大きさを決定できるオブジェクトを実装する際に便利です。同じメモリ割当にフィールドの配列も埋め込むことで、メモリ割当の回数を減らし、メモリ管理効率を上げることができます。

void PyObject_Del(void *op)

PyObject_New または PyObject_NewVar によって、オブジェクトのために確保されたメモリを解放します。これは通常オブジェクトの型に指定されている tp_dealloc ハンドラから呼び出されます。これの呼び出し後のメモリは既に有効な Python オブジェクトではなくなっているため、オブジェクトのフィールドはアクセスされるべきではありません。

PyObject _Py_NoneStruct

Python からは None に見えるオブジェクトです。この値へのアクセスは、このオブジェクトへのポインタを評価する Py_None マクロを使わなければなりません。

参考

PyModule_Create()

拡張モジュールのアロケートと生成。

共通のオブジェクト構造体 (common object structure)

Python では、オブジェクト型を定義する上で数多くの構造体が使われます。この節では三つの構造体とその利用方法について説明します。

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 PyObject and 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 reference counting.

type PyObject

Part of the Limited API. (Only some members are part of the stable ABI.)

全てのオブジェクト型はこの型を拡張したものです。この型には、あるオブジェクトを指すポインタをオブジェクトとして Python から扱うのに必要な情報が入っています。通常の "リリース" ビルドでは、この構造体にはオブジェクトの参照カウントとオブジェクトに対応する型オブジェクトだけが入っています。実際には PyObject であることは宣言されていませんが、全ての Python オブジェクトへのポインタは PyObject* へキャストできます。メンバにアクセスするには Py_REFCNT マクロと Py_TYPE マクロを使わなければなりません。

type PyVarObject

Part of the Limited API. (Only some members are part of the stable ABI.)

This is an extension of PyObject that adds the ob_size field. This is only used for objects that have some notion of length. This type does not often appear in the Python/C API. Access to the members must be done by using the macros Py_REFCNT, Py_TYPE, and Py_SIZE.

PyObject_HEAD

可変な長さを持たないオブジェクトを表現する新しい型を宣言するときに使うマクロです。 PyObject_HEAD マクロは次のように展開されます:

PyObject ob_base;

上にある PyObject のドキュメントを参照してください。

PyObject_VAR_HEAD

インスタンスごとに異なる長さを持つオブジェクトを表現する新しい型を宣言するときに使うマクロです。 PyObject_VAR_HEAD マクロは次のように展開されます:

PyVarObject ob_base;

上にある PyVarObject のドキュメントを参照してください。

int Py_Is(PyObject *x, PyObject *y)

Part of the Stable ABI since version 3.10.

Test if the x object is the y object, the same as x is y in Python.

Added in version 3.10.

int Py_IsNone(PyObject *x)

Part of the Stable ABI since version 3.10.

Test if an object is the None singleton, the same as x is None in Python.

Added in version 3.10.

int Py_IsTrue(PyObject *x)

Part of the Stable ABI since version 3.10.

Test if an object is the True singleton, the same as x is True in Python.

Added in version 3.10.

int Py_IsFalse(PyObject *x)

Part of the Stable ABI since version 3.10.

Test if an object is the False singleton, the same as x is False in Python.

Added in version 3.10.

PyTypeObject *Py_TYPE(PyObject *o)

Get the type of the Python object o.

Return a borrowed reference.

Use the Py_SET_TYPE() function to set an object type.

バージョン 3.11 で変更: Py_TYPE() is changed to an inline static function. The parameter type is no longer const PyObject*.

int Py_IS_TYPE(PyObject *o, PyTypeObject *type)

Return non-zero if the object o type is type. Return zero otherwise. Equivalent to: Py_TYPE(o) == type.

Added in version 3.9.

void Py_SET_TYPE(PyObject *o, PyTypeObject *type)

Set the object o type to type.

Added in version 3.9.

Py_ssize_t Py_SIZE(PyVarObject *o)

Get the size of the Python object o.

Use the Py_SET_SIZE() function to set an object size.

バージョン 3.11 で変更: Py_SIZE() is changed to an inline static function. The parameter type is no longer const PyVarObject*.

void Py_SET_SIZE(PyVarObject *o, Py_ssize_t size)

Set the object o size to size.

Added in version 3.9.

PyObject_HEAD_INIT(type)

新しい PyObject 型のための初期値に展開するマクロです。このマクロは次のように展開されます。

_PyObject_EXTRA_INIT
1, type,

PyVarObject_HEAD_INIT(type, size)

This is a macro which expands to initialization values for a new PyVarObject type, including the ob_size field. This macro expands to:

_PyObject_EXTRA_INIT
1, type, size,

Implementing functions and methods

type PyCFunction

Part of the Stable ABI.

Type of the functions used to implement most Python callables in C. Functions of this type take two PyObject* parameters and return one such value. If the return value is NULL, an exception shall have been set. If not NULL, the return value is interpreted as the return value of the function as exposed in Python. The function must return a new reference.

関数のシグネチャは次のとおりです

PyObject *PyCFunction(PyObject *self,
                      PyObject *args);

type PyCFunctionWithKeywords

Part of the Stable ABI.

Type of the functions used to implement Python callables in C with signature METH_VARARGS | METH_KEYWORDS. The function signature is:

PyObject *PyCFunctionWithKeywords(PyObject *self,
                                  PyObject *args,
                                  PyObject *kwargs);

type _PyCFunctionFast

Type of the functions used to implement Python callables in C with signature METH_FASTCALL. The function signature is:

PyObject *_PyCFunctionFast(PyObject *self,
                           PyObject *const *args,
                           Py_ssize_t nargs);

type _PyCFunctionFastWithKeywords

Type of the functions used to implement Python callables in C with signature METH_FASTCALL | METH_KEYWORDS. The function signature is:

PyObject *_PyCFunctionFastWithKeywords(PyObject *self,
                                       PyObject *const *args,
                                       Py_ssize_t nargs,
                                       PyObject *kwnames);

type PyCMethod

Type of the functions used to implement Python callables in C with signature METH_METHOD | METH_FASTCALL | METH_KEYWORDS. The function signature is:

PyObject *PyCMethod(PyObject *self,
                    PyTypeObject *defining_class,
                    PyObject *const *args,
                    Py_ssize_t nargs,
                    PyObject *kwnames)

Added in version 3.9.

type PyMethodDef

Part of the Stable ABI (including all members).

拡張型のメソッドを記述する際に用いる構造体です。この構造体には 4 つのフィールドがあります:

const char *ml_name

Name of the method.

PyCFunction ml_meth

Pointer to the C implementation.

int ml_flags

Flags bits indicating how the call should be constructed.

const char *ml_doc

Points to the contents of the docstring.

The ml_meth is a C function pointer. The functions may be of different types, but they always return PyObject*. If the function is not of the PyCFunction, the compiler will require a cast in the method table. Even though PyCFunction defines the first parameter as PyObject*, it is common that the method implementation uses the specific C type of the self object.

The 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:

METH_VARARGS

PyCFunction 型のメソッドで典型的に使われる呼び出し規約です。関数は PyObject* 型の引数値を二つ要求します。最初の引数はメソッドの self オブジェクトです; モジュール関数の場合、これはモジュールオブジェクトです。第二のパラメタ (よく args と呼ばれます) は、全ての引数を表現するタプルオブジェクトです。パラメタは通常、 PyArg_ParseTuple() や PyArg_UnpackTuple() で処理されます。

METH_KEYWORDS

Can only be used in certain combinations with other flags: METH_VARARGS | METH_KEYWORDS, METH_FASTCALL | METH_KEYWORDS and METH_METHOD | METH_FASTCALL | METH_KEYWORDS.

METH_VARARGS | METH_KEYWORDS

Methods with these flags must be of type PyCFunctionWithKeywords. The function expects three parameters: self, args, kwargs where kwargs is a dictionary of all the keyword arguments or possibly NULL if there are no keyword arguments. The parameters are typically processed using PyArg_ParseTupleAndKeywords().

METH_FASTCALL

Fast calling convention supporting only positional arguments. The methods have the type _PyCFunctionFast. The first parameter is self, the second parameter is a C array of PyObject* values indicating the arguments and the third parameter is the number of arguments (the length of the array).

Added in version 3.7.

バージョン 3.10 で変更: METH_FASTCALL is now part of the stable ABI.

METH_FASTCALL | METH_KEYWORDS

Extension of METH_FASTCALL supporting also keyword arguments, with methods of type _PyCFunctionFastWithKeywords. Keyword arguments are passed the same way as in the vectorcall protocol: there is an additional fourth PyObject* parameter which is a tuple representing the names of the keyword arguments (which are guaranteed to be strings) or possibly NULL if there are no keywords. The values of the keyword arguments are stored in the args array, after the positional arguments.

Added in version 3.7.

METH_METHOD

Can only be used in the combination with other flags: METH_METHOD | METH_FASTCALL | METH_KEYWORDS.

METH_METHOD | METH_FASTCALL | METH_KEYWORDS

Extension of 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 Py_TYPE(self).

The method needs to be of type PyCMethod, the same as for METH_FASTCALL | METH_KEYWORDS with defining_class argument added after self.

Added in version 3.9.

METH_NOARGS

Methods without parameters don't need to check whether arguments are given if they are listed with the METH_NOARGS flag. They need to be of type 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 NULL.

The function must have 2 parameters. Since the second parameter is unused, Py_UNUSED can be used to prevent a compiler warning.

METH_O

Methods with a single object argument can be listed with the METH_O flag, instead of invoking PyArg_ParseTuple() with a "O" argument. They have the type PyCFunction, with the self parameter, and a PyObject* parameter representing the single argument.

以下の二つの定数は、呼び出し規約を示すものではなく、クラスのメソッドとして使う際の束縛方式を示すものです。モジュールに対して定義された関数で用いてはなりません。メソッドに対しては、最大で一つしかこのフラグをセットできません。

METH_CLASS

メソッドの最初の引数には、型のインスタンスではなく型オブジェクトが渡されます。このフラグは組み込み関数 classmethod() を使って生成するのと同じ クラスメソッド (class method) を生成するために使われます。

METH_STATIC

メソッドの最初の引数には、型のインスタンスではなく NULL が渡されます。このフラグは、 staticmethod() を使って生成するのと同じ 静的メソッド (static method) を生成するために使われます。

もう一つの定数は、あるメソッドを同名の別のメソッド定義と置き換えるかどうかを制御します。

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 __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.

PyObject *PyCMethod_New(PyMethodDef *ml, PyObject *self, PyObject *module, PyTypeObject *cls)

Return value: New reference. Part of the Stable ABI since version 3.9.

Turn ml into a Python callable object. The caller must ensure that ml outlives the callable. Typically, ml is defined as a static variable.

The self parameter will be passed as the self argument to the C function in ml->ml_meth when invoked. self can be NULL.

The callable object's __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 None or NULL.

参考

function.__module__

The cls parameter will be passed as the defining_class argument to the C function. Must be set if METH_METHOD is set on ml->ml_flags.

Added in version 3.9.

PyObject *PyCFunction_NewEx(PyMethodDef *ml, PyObject *self, PyObject *module)

Return value: New reference. Part of the Stable ABI.

Equivalent to PyCMethod_New(ml, self, module, NULL).

PyObject *PyCFunction_New(PyMethodDef *ml, PyObject *self)

Return value: New reference. Part of the Stable ABI since version 3.4.

Equivalent to PyCMethod_New(ml, self, NULL, NULL).

Accessing attributes of extension types

type PyMemberDef

Part of the Stable ABI (including all members).

Structure which describes an attribute of a type which corresponds to a C struct member. When defining a class, put a NULL-terminated array of these structures in the tp_members slot.

Its fields are, in order:

const char *name

Name of the member. A NULL value marks the end of a PyMemberDef[] array.

The string should be static, no copy is made of it.

int type

The type of the member in the C struct. See Member types for the possible values.

Py_ssize_t offset

The offset in bytes that the member is located on the type’s object struct.

int flags

Zero or more of the Member flags, combined using bitwise OR.

const char *doc

The docstring, or NULL. The string should be static, no copy is made of it. Typically, it is defined using PyDoc_STR.

By default (when flags is 0), members allow both read and write access. Use the Py_READONLY flag for read-only access. Certain types, like Py_T_STRING, imply Py_READONLY. Only Py_T_OBJECT_EX (and legacy T_OBJECT) members can be deleted.

For heap-allocated types (created using PyType_FromSpec() or similar), PyMemberDef may contain a definition for the special member "__vectorcalloffset__", corresponding to tp_vectorcall_offset in type objects. These must be defined with Py_T_PYSSIZET and Py_READONLY, for example:

static PyMemberDef spam_type_members[] = {
    {"__vectorcalloffset__", Py_T_PYSSIZET,
     offsetof(Spam_object, vectorcall), Py_READONLY},
    {NULL}  /* Sentinel */
};

(You may need to #include <stddef.h> for offsetof().)

The legacy offsets tp_dictoffset and tp_weaklistoffset can be defined similarly using "__dictoffset__" and "__weaklistoffset__" members, but extensions are strongly encouraged to use Py_TPFLAGS_MANAGED_DICT and Py_TPFLAGS_MANAGED_WEAKREF instead.

バージョン 3.12 で変更: PyMemberDef is always available. Previously, it required including "structmember.h".

PyObject *PyMember_GetOne(const char *obj_addr, struct PyMemberDef *m)

Part of the Stable ABI.

Get an attribute belonging to the object at address obj_addr. The attribute is described by PyMemberDef m. Returns NULL on error.

バージョン 3.12 で変更: PyMember_GetOne is always available. Previously, it required including "structmember.h".

int PyMember_SetOne(char *obj_addr, struct PyMemberDef *m, PyObject *o)

Part of the Stable ABI.

Set an attribute belonging to the object at address obj_addr to object o. The attribute to set is described by PyMemberDef m. Returns 0 if successful and a negative value on failure.

バージョン 3.12 で変更: PyMember_SetOne is always available. Previously, it required including "structmember.h".

Member flags

The following flags can be used with PyMemberDef.flags:

Py_READONLY

Not writable.

Py_AUDIT_READ

Emit an object.__getattr__ audit event before reading.

Py_RELATIVE_OFFSET

Indicates that the offset of this PyMemberDef entry indicates an offset from the subclass-specific data, rather than from PyObject.

Can only be used as part of Py_tp_members slot when creating a class using negative basicsize. It is mandatory in that case.

This flag is only used in PyType_Slot. When setting tp_members during class creation, Python clears it and sets PyMemberDef.offset to the offset from the PyObject struct.

バージョン 3.10 で変更: The RESTRICTED, READ_RESTRICTED and WRITE_RESTRICTED macros available with #include "structmember.h" are deprecated. READ_RESTRICTED and RESTRICTED are equivalent to Py_AUDIT_READ; WRITE_RESTRICTED does nothing.

バージョン 3.12 で変更: The READONLY macro was renamed to Py_READONLY. The PY_AUDIT_READ macro was renamed with the Py_ prefix. The new names are now always available. Previously, these required #include "structmember.h". The header is still available and it provides the old names.

Member types

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 TypeError or ValueError is raised.

Unless marked (D), attributes defined this way cannot be deleted using e.g. del or delattr().

マクロ名

C の型

Python の型

Py_T_BYTE

char

int

Py_T_SHORT

short

int

Py_T_INT

int

int

Py_T_LONG

long

int

Py_T_LONGLONG

long long

int

Py_T_UBYTE

unsigned char

int

Py_T_UINT

unsigned int

int

Py_T_USHORT

unsigned short

int

Py_T_ULONG

unsigned long

int

Py_T_ULONGLONG

unsigned long long

int

Py_T_PYSSIZET

Py_ssize_t

int

Py_T_FLOAT

float

float

Py_T_DOUBLE

double

float

Py_T_BOOL

char (written as 0 or 1)

bool

Py_T_STRING

const char* (*)

str (RO)

Py_T_STRING_INPLACE

const char[] (*)

str (RO)

Py_T_CHAR

char (0-127)

str (**)

Py_T_OBJECT_EX

PyObject*

object (D)

(*): Zero-terminated, UTF8-encoded C string. With Py_T_STRING the C representation is a pointer; with Py_T_STRING_INPLACE the string is stored directly in the structure.

(**): String of length 1. Only ASCII is accepted.

(RO): Implies Py_READONLY.

(D): Can be deleted, in which case the pointer is set to NULL. Reading a NULL pointer raises AttributeError.

Added in version 3.12: In previous versions, the macros were only available with #include "structmember.h" and were named without the Py_ prefix (e.g. as T_INT). The header is still available and contains the old names, along with the following deprecated types:

T_OBJECT

Like Py_T_OBJECT_EX, but NULL is converted to None. This results in surprising behavior in Python: deleting the attribute effectively sets it to None.

T_NONE

Always None. Must be used with Py_READONLY.

Defining Getters and Setters

type PyGetSetDef

Part of the Stable ABI (including all members).

型のプロパティのようなアクセスを定義するための構造体です。 PyTypeObject.tp_getset スロットの説明も参照してください。

const char *name

属性名

getter get

C function to get the attribute.

setter set

Optional C function to set or delete the attribute. If NULL, the attribute is read-only.

const char *doc

任意のドキュメンテーション文字列

void *closure

Optional user data pointer, providing additional data for getter and setter.

typedef PyObject *(*getter)(PyObject*, void*)

Part of the Stable ABI.

The get function takes one PyObject* parameter (the instance) and a user data pointer (the associated closure):

成功または失敗時に NULL と例外の集合にされたときは新しい参照を返します。

typedef int (*setter)(PyObject*, PyObject*, void*)

Part of the Stable ABI.

set functions take two PyObject* parameters (the instance and the value to be set) and a user data pointer (the associated closure):

属性を削除する場合は、2 番目のパラメータに NULL を指定します。成功した場合は 0 を、失敗した場合は -1 を例外として返します。

型オブジェクト

新スタイルの型を定義する構造体: PyTypeObject 構造体は、おそらく Python オブジェクトシステムの中で最も重要な構造体の1つでしょう。型オブジェクトは PyObject_* 系や PyType_* 系の関数で扱えますが、ほとんどの Python アプリケーションにとって、さして面白みのある機能を提供しません。型オブジェクトはオブジェクトがどのように振舞うかを決める基盤ですから、インタプリタ自体や新たな型を定義する拡張モジュールでは非常に重要な存在です。

型オブジェクトは標準の型 (standard type) に比べるとかなり大きな構造体です。各型オブジェクトは多くの値を保持しており、そのほとんどは C 関数へのポインタで、それぞれの関数はその型の機能の小さい部分を実装しています。この節では、型オブジェクトの各フィールドについて詳細を説明します。各フィールドは、構造体内で出現する順番に説明されています。

以下のクイックリファレンスに加えて、 使用例 節では PyTypeObject の意味と使い方を一目で理解できる例を載せています。

クイックリファレンス

tp スロット

PyTypeObject スロット [1]

型

特殊メソッド/特殊属性

Info [2]

O

T

D

I

<R> tp_name

const char *

__name__

X

X

tp_basicsize

Py_ssize_t

X

X

X

tp_itemsize

Py_ssize_t

X

X

tp_dealloc

destructor

X

X

X

tp_vectorcall_offset

Py_ssize_t

X

X

(tp_getattr)

getattrfunc

__getattribute__, __getattr__

G

(tp_setattr)

setattrfunc

__setattr__, __delattr__

G

tp_as_async

PyAsyncMethods *

sub-slots

%

tp_repr

reprfunc

__repr__

X

X

X

tp_as_number

PyNumberMethods *

sub-slots

%

tp_as_sequence

PySequenceMethods *

sub-slots

%

tp_as_mapping

PyMappingMethods *

sub-slots

%

tp_hash

hashfunc

__hash__

X

G

tp_call

ternaryfunc

__call__

X

X

tp_str

reprfunc

__str__

X

X

tp_getattro

getattrofunc

__getattribute__, __getattr__

X

X

G

tp_setattro

setattrofunc

__setattr__, __delattr__

X

X

G

tp_as_buffer

PyBufferProcs *

%

tp_flags

unsigned long

X

X

?

tp_doc

const char *

__doc__

X

X

tp_traverse

traverseproc

X

G

tp_clear

inquiry

X

G

tp_richcompare

richcmpfunc

__lt__, __le__, __eq__, __ne__, __gt__, __ge__

X

G

(tp_weaklistoffset)

Py_ssize_t

X

?

tp_iter

getiterfunc

__iter__

X

tp_iternext

iternextfunc

__next__

X

tp_methods

PyMethodDef []

X

X

tp_members

PyMemberDef []

X

tp_getset

PyGetSetDef []

X

X

tp_base

PyTypeObject *

__base__

X

tp_dict

PyObject *

__dict__

?

tp_descr_get

descrgetfunc

__get__

X

tp_descr_set

descrsetfunc

__set__, __delete__

X

(tp_dictoffset)

Py_ssize_t

X

?

tp_init

initproc

__init__

X

X

X

tp_alloc

allocfunc

X

?

?

tp_new

newfunc

__new__

X

X

?

?

tp_free

freefunc

X

X

?

?

tp_is_gc

inquiry

X

X

<tp_bases>

PyObject *

__bases__

~

<tp_mro>

PyObject *

__mro__

~

[tp_cache]

PyObject *

[tp_subclasses]

void *

__subclasses__

[tp_weaklist]

PyObject *

(tp_del)

destructor

[tp_version_tag]

unsigned int

tp_finalize

destructor

__del__

X

tp_vectorcall

vectorcallfunc

[tp_watched]

unsigned char

[1]

(): A slot name in parentheses indicates it is (effectively) deprecated.

<>: Names in angle brackets should be initially set to 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-NULL).

[2]

列:

"O": set on PyBaseObject_Type

"T": set on PyType_Type

"D": default (if slot is set to NULL)

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").

"I": inheritance

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

Note that some slots are effectively inherited through the normal attribute lookup chain.

sub-slots

Slot

型

特殊メソッド

am_await

unaryfunc

__await__

am_aiter

unaryfunc

__aiter__

am_anext

unaryfunc

__anext__

am_send

sendfunc

nb_add

binaryfunc

__add__ __radd__

nb_inplace_add

binaryfunc

__iadd__

nb_subtract

binaryfunc

__sub__ __rsub__

nb_inplace_subtract

binaryfunc

__isub__

nb_multiply

binaryfunc

__mul__ __rmul__

nb_inplace_multiply

binaryfunc

__imul__

nb_remainder

binaryfunc

__mod__ __rmod__

nb_inplace_remainder

binaryfunc

__imod__

nb_divmod

binaryfunc

__divmod__ __rdivmod__

nb_power

ternaryfunc

__pow__ __rpow__

nb_inplace_power

ternaryfunc

__ipow__

nb_negative

unaryfunc

__neg__

nb_positive

unaryfunc

__pos__

nb_absolute

unaryfunc

__abs__

nb_bool

inquiry

__bool__

nb_invert

unaryfunc

__invert__

nb_lshift

binaryfunc

__lshift__ __rlshift__

nb_inplace_lshift

binaryfunc

__ilshift__

nb_rshift

binaryfunc

__rshift__ __rrshift__

nb_inplace_rshift

binaryfunc

__irshift__

nb_and

binaryfunc

__and__ __rand__

nb_inplace_and

binaryfunc

__iand__

nb_xor

binaryfunc

__xor__ __rxor__

nb_inplace_xor

binaryfunc

__ixor__

nb_or

binaryfunc

__or__ __ror__

nb_inplace_or

binaryfunc

__ior__

nb_int

unaryfunc

__int__

nb_reserved

void *

nb_float

unaryfunc

__float__

nb_floor_divide

binaryfunc

__floordiv__

nb_inplace_floor_divide

binaryfunc

__ifloordiv__

nb_true_divide

binaryfunc

__truediv__

nb_inplace_true_divide

binaryfunc

__itruediv__

nb_index

unaryfunc

__index__

nb_matrix_multiply

binaryfunc

__matmul__ __rmatmul__

nb_inplace_matrix_multiply

binaryfunc

__imatmul__

mp_length

lenfunc

__len__

mp_subscript

binaryfunc

__getitem__

mp_ass_subscript

objobjargproc

__setitem__, __delitem__

sq_length

lenfunc

__len__

sq_concat

binaryfunc

__add__

sq_repeat

ssizeargfunc

__mul__

sq_item

ssizeargfunc

__getitem__

sq_ass_item

ssizeobjargproc

__setitem__ __delitem__

sq_contains

objobjproc

__contains__

sq_inplace_concat

binaryfunc

__iadd__

sq_inplace_repeat

ssizeargfunc

__imul__

bf_getbuffer

getbufferproc()

bf_releasebuffer

releasebufferproc()

スロットの定義型 (typedef)

定義型 (typedef)

引数型

返り値型

allocfunc

PyTypeObject *

Py_ssize_t

PyObject *

destructor

PyObject *

void

freefunc

void *

void

traverseproc

PyObject *

visitproc

void *

int

newfunc

PyObject *

PyObject *

PyObject *

PyObject *

initproc

PyObject *

PyObject *

PyObject *

int

reprfunc

PyObject *

PyObject *

getattrfunc

PyObject *

const char *

PyObject *

setattrfunc

PyObject *

const char *

PyObject *

int

getattrofunc

PyObject *

PyObject *

PyObject *

setattrofunc

PyObject *

PyObject *

PyObject *

int

descrgetfunc

PyObject *

PyObject *

PyObject *

PyObject *

descrsetfunc

PyObject *

PyObject *

PyObject *

int

hashfunc

PyObject *

Py_hash_t

richcmpfunc

PyObject *

PyObject *

int

PyObject *

getiterfunc

PyObject *

PyObject *

iternextfunc

PyObject *

PyObject *

lenfunc

PyObject *

Py_ssize_t

getbufferproc

PyObject *

Py_buffer *

int

int

releasebufferproc

PyObject *

Py_buffer *

void

inquiry

PyObject *

int

unaryfunc

PyObject *

PyObject *

binaryfunc

PyObject *

PyObject *

PyObject *

ternaryfunc

PyObject *

PyObject *

PyObject *

PyObject *

ssizeargfunc

PyObject *

Py_ssize_t

PyObject *

ssizeobjargproc

PyObject *

Py_ssize_t

PyObject *

int

objobjproc

PyObject *

PyObject *

int

objobjargproc

PyObject *

PyObject *

PyObject *

int

See Slot Type typedefs below for more detail.

PyTypeObject 定義

PyTypeObject の構造体定義は Include/object.h で見つけられるはずです。参照の手間を省くために、ここでは定義を繰り返します:

typedef struct _typeobject {
    PyObject_VAR_HEAD
    const char *tp_name; /* For printing, in format "<module>.<name>" */
    Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */

    /* Methods to implement standard operations */

    destructor tp_dealloc;
    Py_ssize_t tp_vectorcall_offset;
    getattrfunc tp_getattr;
    setattrfunc tp_setattr;
    PyAsyncMethods *tp_as_async; /* formerly known as tp_compare (Python 2)
                                    or tp_reserved (Python 3) */
    reprfunc tp_repr;

    /* Method suites for standard classes */

    PyNumberMethods *tp_as_number;
    PySequenceMethods *tp_as_sequence;
    PyMappingMethods *tp_as_mapping;

    /* More standard operations (here for binary compatibility) */

    hashfunc tp_hash;
    ternaryfunc tp_call;
    reprfunc tp_str;
    getattrofunc tp_getattro;
    setattrofunc tp_setattro;

    /* Functions to access object as input/output buffer */
    PyBufferProcs *tp_as_buffer;

    /* Flags to define presence of optional/expanded features */
    unsigned long tp_flags;

    const char *tp_doc; /* Documentation string */

    /* Assigned meaning in release 2.0 */
    /* call function for all accessible objects */
    traverseproc tp_traverse;

    /* delete references to contained objects */
    inquiry tp_clear;

    /* Assigned meaning in release 2.1 */
    /* rich comparisons */
    richcmpfunc tp_richcompare;

    /* weak reference enabler */
    Py_ssize_t tp_weaklistoffset;

    /* Iterators */
    getiterfunc tp_iter;
    iternextfunc tp_iternext;

    /* Attribute descriptor and subclassing stuff */
    struct PyMethodDef *tp_methods;
    struct PyMemberDef *tp_members;
    struct PyGetSetDef *tp_getset;
    // Strong reference on a heap type, borrowed reference on a static type
    struct _typeobject *tp_base;
    PyObject *tp_dict;
    descrgetfunc tp_descr_get;
    descrsetfunc tp_descr_set;
    Py_ssize_t tp_dictoffset;
    initproc tp_init;
    allocfunc tp_alloc;
    newfunc tp_new;
    freefunc tp_free; /* Low-level free-memory routine */
    inquiry tp_is_gc; /* For PyObject_IS_GC */
    PyObject *tp_bases;
    PyObject *tp_mro; /* method resolution order */
    PyObject *tp_cache;
    PyObject *tp_subclasses;
    PyObject *tp_weaklist;
    destructor tp_del;

    /* Type attribute cache version tag. Added in version 2.6 */
    unsigned int tp_version_tag;

    destructor tp_finalize;
    vectorcallfunc tp_vectorcall;

    /* bitset of which type-watchers care about this type */
    unsigned char tp_watched;
} PyTypeObject;

PyObject スロット

The type object structure extends the PyVarObject structure. The ob_size field is used for dynamic types (created by type_new(), usually called from a class statement). Note that PyType_Type (the metatype) initializes tp_itemsize, which means that its instances (i.e. type objects) must have the ob_size field.

Py_ssize_t PyObject.ob_refcnt

Part of the Stable ABI.

This is the type object's reference count, initialized to 1 by the PyObject_HEAD_INIT macro. Note that for statically allocated type objects, the type's instances (objects whose ob_type points back to the type) do not count as references. But for dynamically allocated type objects, the instances do count as references.

継承:

サブタイプはこのフィールドを継承しません。

PyTypeObject *PyObject.ob_type

Part of the Stable ABI.

型自体の型、別の言い方をするとメタタイプです。 PyObject_HEAD_INIT マクロで初期化され、通常は &PyType_Type になります。しかし、(少なくとも) Windows で利用できる動的ロード可能な拡張モジュールでは、コンパイラは有効な初期化ではないと文句をつけます。そこで、ならわしとして、 PyObject_HEAD_INIT には NULL を渡して初期化しておき、他の操作を行う前にモジュールの初期化関数で明示的にこのフィールドを初期化することになっています。この操作は以下のように行います:

Foo_Type.ob_type = &PyType_Type;

This should be done before any instances of the type are created. PyType_Ready() checks if ob_type is NULL, and if so, initializes it to the ob_type field of the base class. PyType_Ready() will not change this field if it is non-zero.

継承:

サブタイプはこのフィールドを継承します。

PyObject *PyObject._ob_next

PyObject *PyObject._ob_prev

These fields are only present when the macro Py_TRACE_REFS is defined (see the configure --with-trace-refs option).

Their initialization to NULL is taken care of by the PyObject_HEAD_INIT macro. For statically allocated objects, these fields always remain NULL. For dynamically allocated objects, these two fields are used to link the object into a doubly linked list of all live objects on the heap.

This could be used for various debugging purposes; currently the only uses are the sys.getobjects() function and to print the objects that are still alive at the end of a run when the environment variable PYTHONDUMPREFS is set.

継承:

These fields are not inherited by subtypes.

PyVarObject スロット

Py_ssize_t PyVarObject.ob_size

Part of the Stable ABI.

静的にメモリ確保されている型オブジェクト の場合、このフィールドはゼロに初期化されます。動的にメモリ確保されている型オブジェクト の場合、このフィールドは内部使用される特殊な意味を持ちます。

継承:

サブタイプはこのフィールドを継承しません。

PyTypeObject スロット

Each slot has a section describing inheritance. If PyType_Ready() may set a value when the field is set to NULL then there will also be a "Default" section. (Note that many fields set on PyBaseObject_Type and PyType_Type effectively act as defaults.)

const char *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 T defined in module M in subpackage Q in package P should have the tp_name initializer "P.Q.M.T".

動的にメモリ確保される型オブジェクト の場合、このフィールドは単に型の名前になり、モジュール名は型の辞書内でキー '__module__' に対する値として明示的に保存されます。

静的にメモリ確保される型オブジェクト の場合、 tp_name フィールドにはドットが含まれているはずです。最後のドットよりも前にある部分文字列全体は __module__ 属性として、またドットよりも後ろにある部分は __name__ 属性としてアクセスできます。

ドットが入っていない場合、 tp_name フィールドの内容全てが __name__ 属性になり、 __module__ 属性は (前述のように型の辞書内で明示的にセットしないかぎり) 未定義になります。このため、その型は pickle 化できないことになります。さらに、 pydoc が作成するモジュールドキュメントのリストにも載らなくなります。

This field must not be NULL. It is the only required field in PyTypeObject() (other than potentially tp_itemsize).

継承:

サブタイプはこのフィールドを継承しません。

Py_ssize_t PyTypeObject.tp_basicsize

Py_ssize_t PyTypeObject.tp_itemsize

これらのフィールドは、型インスタンスのバイトサイズを計算できるようにします。

型には二つの種類があります: 固定長インスタンスの型は、 tp_itemsize フィールドがゼロで、可変長インスタンスの方は tp_itemsize フィールドが非ゼロの値になります。固定長インスタンスの型の場合、全てのインスタンスは等しく tp_basicsize で与えられたサイズになります。

For a type with variable-length instances, the instances must have an ob_size field, and the instance size is tp_basicsize plus N times tp_itemsize, where N is the "length" of the object. The value of N is typically stored in the instance's ob_size field. There are exceptions: for example, ints use a negative ob_size to indicate a negative number, and N is abs(ob_size) there. Also, the presence of an ob_size field in the instance layout doesn't mean that the instance structure is variable-length (for example, the structure for the list type has fixed-length instances, yet those instances have a meaningful ob_size field).

The basic size includes the fields in the instance declared by the macro PyObject_HEAD or PyObject_VAR_HEAD (whichever is used to declare the instance struct) and this in turn includes the _ob_prev and _ob_next fields if they are present. This means that the only correct way to get an initializer for the tp_basicsize is to use the sizeof operator on the struct used to declare the instance layout. The basic size does not include the GC header size.

アラインメントに関する注釈: 変数の各要素を配置する際に特定のアラインメントが必要となる場合、 tp_basicsize の値に気をつけなければなりません。例: ある型が double の配列を実装しているとします。 tp_itemsize は sizeof(double) です。 tp_basicsize が sizeof(double) (ここではこれを double のアラインメントが要求するサイズと仮定する) の個数分のサイズになるようにするのはプログラマの責任です。

For any type with variable-length instances, this field must not be NULL.

継承:

これらのフィールドはサブタイプに別々に継承されます。基底タイプが 0 でない tp_itemsize を持っていた場合、基底タイプの実装に依存しますが、一般的にはサブタイプで別の 0 で無い値を tp_itemsize に設定するのは安全ではありません。

destructor PyTypeObject.tp_dealloc

インスタンスのデストラクタ関数へのポインタです。この関数は (単量子 None や Ellipsis の場合のように) インスタンスが決してメモリ解放されない型でない限り必ず定義しなければなりません。シグネチャは次の通りです:

void tp_dealloc(PyObject *self);

The destructor function is called by the Py_DECREF() and Py_XDECREF() macros when the new reference count is zero. At this point, the instance is still in existence, but there are no references to it. The destructor function should free all references which the instance owns, free all memory buffers owned by the instance (using the freeing function corresponding to the allocation function used to allocate the buffer), and call the type's tp_free function. If the type is not subtypable (doesn't have the Py_TPFLAGS_BASETYPE flag bit set), it is permissible to call the object deallocator directly instead of via tp_free. The object deallocator should be the one used to allocate the instance; this is normally PyObject_Del() if the instance was allocated using PyObject_New or PyObject_NewVar, or PyObject_GC_Del() if the instance was allocated using PyObject_GC_New or PyObject_GC_NewVar.

If the type supports garbage collection (has the Py_TPFLAGS_HAVE_GC flag bit set), the destructor should call PyObject_GC_UnTrack() before clearing any member fields.

static void foo_dealloc(foo_object *self) {
    PyObject_GC_UnTrack(self);
    Py_CLEAR(self->ref);
    Py_TYPE(self)->tp_free((PyObject *)self);
}

Finally, if the type is heap allocated (Py_TPFLAGS_HEAPTYPE), the deallocator should release the owned reference to its type object (via Py_DECREF()) after calling the type deallocator. In order to avoid dangling pointers, the recommended way to achieve this is:

static void foo_dealloc(foo_object *self) {
    PyTypeObject *tp = Py_TYPE(self);
    // free references and buffers here
    tp->tp_free(self);
    Py_DECREF(tp);
}

継承:

サブタイプはこのフィールドを継承します。

Py_ssize_t PyTypeObject.tp_vectorcall_offset

An optional offset to a per-instance function that implements calling the object using the vectorcall protocol, a more efficient alternative of the simpler tp_call.

This field is only used if the flag Py_TPFLAGS_HAVE_VECTORCALL is set. If so, this must be a positive integer containing the offset in the instance of a vectorcallfunc pointer.

The vectorcallfunc pointer may be NULL, in which case the instance behaves as if Py_TPFLAGS_HAVE_VECTORCALL was not set: calling the instance falls back to tp_call.

Any class that sets Py_TPFLAGS_HAVE_VECTORCALL must also set tp_call and make sure its behaviour is consistent with the vectorcallfunc function. This can be done by setting tp_call to PyVectorcall_Call().

バージョン 3.8 で変更: Before version 3.8, this slot was named 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 mutable heap types to implement the vectorcall protocol. When a user sets __call__ in Python code, only tp_call is updated, likely making it inconsistent with the vectorcall function. Since 3.12, setting __call__ will disable vectorcall optimization by clearing the Py_TPFLAGS_HAVE_VECTORCALL flag.

継承:

This field is always inherited. However, the Py_TPFLAGS_HAVE_VECTORCALL flag is not always inherited. If it's not set, then the subclass won't use vectorcall, except when PyVectorcall_Call() is explicitly called.

getattrfunc PyTypeObject.tp_getattr

オプションのポインタで、get-attribute-string を行う関数を指します。

このフィールドは非推奨です。このフィールドを定義するときは、 tp_getattro 関数と同じように動作し、属性名は Python 文字列 オブジェクトではなく C 文字列で指定するような関数を指すようにしなければなりません。

継承:

Group: tp_getattr, tp_getattro

このフィールドは tp_getattro と共にサブタイプに継承されます: すなわち、サブタイプの tp_getattr および tp_getattro が共に NULL の場合、サブタイプは基底タイプから tp_getattr と tp_getattro を両方とも継承します。

setattrfunc PyTypeObject.tp_setattr

オプションのポインタで、属性の設定と削除を行う関数を指します。

このフィールドは非推奨です。このフィールドを定義するときは、 tp_setattro 関数と同じように動作し、属性名は Python 文字列 オブジェクトではなく C 文字列で指定するような関数を指すようにしなければなりません。

継承:

Group: tp_setattr, tp_setattro

このフィールドは tp_setattro と共にサブタイプに継承されます: すなわち、サブタイプの tp_setattr および tp_setattro が共に NULL の場合、サブタイプは基底タイプから tp_setattr と tp_setattro を両方とも継承します。

PyAsyncMethods *PyTypeObject.tp_as_async

追加の構造体を指すポインタです。この構造体は、 C レベルで awaitable プロトコルと asynchronous iterator プロトコルを実装するオブジェクトだけに関係するフィールドを持ちます。詳しいことは async オブジェクト構造体 を参照してください。

Added in version 3.5: 以前は tp_compare や tp_reserved として知られていました。

継承:

tp_as_async フィールドは継承されませんが、これに含まれるフィールドが個別に継承されます。

reprfunc PyTypeObject.tp_repr

オプションのポインタで、組み込み関数 repr() を実装している関数を指します。

The signature is the same as for PyObject_Repr():

PyObject *tp_repr(PyObject *self);

この関数は文字列オブジェクトか Unicode オブジェクトを返さなければなりません。理想的には、この関数が返す文字列は、適切な環境で eval() に渡した場合、同じ値を持つオブジェクトになるような文字列でなければなりません。不可能な場合には、オブジェクトの型と値から導出した内容の入った '<' から始まって '>' で終わる文字列を返さなければなりません。

継承:

サブタイプはこのフィールドを継承します。

デフォルト

このフィールドが設定されていない場合、 <%s object at %p> の形式をとる文字列が返されます。 %s は型の名前に、 %p はオブジェクトのメモリアドレスに置き換えられます。

PyNumberMethods *PyTypeObject.tp_as_number

数値プロトコルを実装した追加の構造体を指すポインタです。これらのフィールドについては 数値オブジェクト構造体 で説明されています。

継承:

tp_as_number フィールドは継承されませんが、そこの含まれるフィールドが個別に継承されます。

PySequenceMethods *PyTypeObject.tp_as_sequence

シーケンスプロトコルを実装した追加の構造体を指すポインタです。これらのフィールドについては シーケンスオブジェクト構造体 で説明されています。

継承:

tp_as_sequence フィールドは継承されませんが、これに含まれるフィールドが個別に継承されます。

PyMappingMethods *PyTypeObject.tp_as_mapping

マッピングプロトコルを実装した追加の構造体を指すポインタです。これらのフィールドについては マップオブジェクト構造体 で説明されています。

継承:

tp_as_mapping フィールドは継承されませんが、これに含まれるフィールドが個別に継承されます。

hashfunc PyTypeObject.tp_hash

オプションのポインタで、組み込み関数 hash() を実装している関数を指します。

The signature is the same as for PyObject_Hash():

Py_hash_t tp_hash(PyObject *);

通常時には -1 を戻り値にしてはなりません; ハッシュ値の計算中にエラーが生じた場合、関数は例外をセットして -1 を返さねばなりません。

When this field is not set (and tp_richcompare is not set), an attempt to take the hash of the object raises TypeError. This is the same as setting it to PyObject_HashNotImplemented().

このフィールドは明示的に PyObject_HashNotImplemented() に設定することで、親 type からのハッシュメソッドの継承をブロックすることができます。これは Python レベルでの __hash__ = None と同等に解釈され、 isinstance(o, collections.Hashable) が正しく False を返すようになります。逆もまた可能であることに注意してください - Python レベルで __hash__ = None を設定することで tp_hash スロットは PyObject_HashNotImplemented() に設定されます。

継承:

Group: tp_hash, tp_richcompare

このフィールドは tp_richcompare と共にサブタイプに継承されます: すなわち、サブタイプの tp_richcompare および tp_hash が両方とも NULL のとき、サブタイプは基底タイプから tp_richcompare と tp_hash を両方とも継承します。

ternaryfunc PyTypeObject.tp_call

オプションのポインタで、オブジェクトの呼び出しを実装している関数を指します。オブジェクトが呼び出し可能でない場合には NULL にしなければなりません。シグネチャは PyObject_Call() と同じです。

PyObject *tp_call(PyObject *self, PyObject *args, PyObject *kwargs);

継承:

サブタイプはこのフィールドを継承します。

reprfunc PyTypeObject.tp_str

オプションのポインタで、組み込みの演算 str() を実装している関数を指します。(str が型の一つになったため、 str() は str のコンストラクタを呼び出すことに注意してください。このコンストラクタは実際の処理を行う上で PyObject_Str() を呼び出し、さらに PyObject_Str() がこのハンドラを呼び出すことになります。)

The signature is the same as for PyObject_Str():

PyObject *tp_str(PyObject *self);

この関数は文字列オブジェクトか Unicode オブジェクトを返さなければなりません。それはオブジェクトを "分かりやすく (friendly)" 表現した文字列でなければなりません。というのは、この文字列はとりわけ print() 関数で使われることになる表記だからです。

継承:

サブタイプはこのフィールドを継承します。

デフォルト

このフィールドが設定されていない場合、文字列表現を返すためには PyObject_Repr() が呼び出されます。

getattrofunc PyTypeObject.tp_getattro

オプションのポインタで、get-attribute を実装している関数を指します。

The signature is the same as for PyObject_GetAttr():

PyObject *tp_getattro(PyObject *self, PyObject *attr);

通常の属性検索を実装している PyObject_GenericGetAttr() をこのフィールドに設定しておくとたいていの場合は便利です。

継承:

Group: tp_getattr, tp_getattro

このフィールドは tp_getattr と共にサブタイプに継承されます: すなわち、サブタイプの tp_getattr および tp_getattro が共に NULL の場合、サブタイプは基底タイプから tp_getattr と tp_getattro を両方とも継承します。

デフォルト

PyBaseObject_Type uses PyObject_GenericGetAttr().

setattrofunc PyTypeObject.tp_setattro

オプションのポインタで、属性の設定と削除を行う関数を指します。

The signature is the same as for PyObject_SetAttr():

int tp_setattro(PyObject *self, PyObject *attr, PyObject *value);

さらに、value に NULL を指定して属性を削除できるようにしなければなりません。通常のオブジェクト属性設定を実装している PyObject_GenericSetAttr() をこのフィールドに設定しておくとたいていの場合は便利です。

継承:

Group: tp_setattr, tp_setattro

このフィールドは tp_setattr と共にサブタイプに継承されます: すなわち、サブタイプの tp_setattr および tp_setattro が共に NULL の場合、サブタイプは基底タイプから tp_setattr と tp_setattro を両方とも継承します。

デフォルト

PyBaseObject_Type uses PyObject_GenericSetAttr().

PyBufferProcs *PyTypeObject.tp_as_buffer

バッファインターフェースを実装しているオブジェクトにのみ関連する、一連のフィールド群が入った別の構造体を指すポインタです。構造体内の各フィールドは バッファオブジェクト構造体 (buffer object structure) で説明します。

継承:

tp_as_buffer フィールド自体は継承されませんが、これに含まれるフィールドは個別に継承されます。

unsigned long PyTypeObject.tp_flags

このフィールドは様々なフラグからなるビットマスクです。いくつかのフラグは、特定の状況において変則的なセマンティクスが適用されることを示します; その他のフラグは、型オブジェクト (あるいは tp_as_number 、 tp_as_sequence 、 tp_as_mapping 、 および tp_as_buffer が参照している拡張機能構造体) の特定のフィールドのうち、過去から現在までずっと存在していたわけではないものが有効になっていることを示すために使われます; フラグビットがクリアされていれば、フラグが保護しているフィールドにはアクセスしない代わりに、その値はゼロか NULL になっているとみなさなければなりません。

継承:

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 Py_TPFLAGS_HAVE_GC flag bit is inherited together with the tp_traverse and tp_clear fields, i.e. if the Py_TPFLAGS_HAVE_GC flag bit is clear in the subtype and the tp_traverse and tp_clear fields in the subtype exist and have NULL values. .. XXX are most flag bits really inherited individually?

デフォルト

PyBaseObject_Type uses Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE.

Bit Masks:

以下に挙げるビットマスクは現在定義されているものです; フラグは | 演算子で論理和を取って tp_flags フィールドの値を作成できます。 PyType_HasFeature() マクロは型とフラグ値、 tp および f をとり、 tp->tp_flags & f が非ゼロかどうか調べます。

Py_TPFLAGS_HEAPTYPE

This bit is set when the type object itself is allocated on the heap, for example, types created dynamically using PyType_FromSpec(). In this case, the 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 support garbage collection as they can form a reference cycle with their own module object.

継承:

???

Py_TPFLAGS_BASETYPE

型を別の型の基底タイプとして使える場合にセットされるビットです。このビットがクリアならば、この型のサブタイプは生成できません (Java における "final" クラスに似たクラスになります)。

継承:

???

Py_TPFLAGS_READY

型オブジェクトが PyType_Ready() で完全に初期化されるとセットされるビットです。

継承:

???

Py_TPFLAGS_READYING

PyType_Ready() による型オブジェクトの初期化処理中にセットされるビットです。

継承:

???

Py_TPFLAGS_HAVE_GC

This bit is set when the object supports garbage collection. If this bit is set, instances must be created using PyObject_GC_New and destroyed using PyObject_GC_Del(). More information in section 循環参照ガベージコレクションをサポートする. This bit also implies that the GC-related fields tp_traverse and tp_clear are present in the type object.

継承:

Group: Py_TPFLAGS_HAVE_GC, tp_traverse, tp_clear

The Py_TPFLAGS_HAVE_GC flag bit is inherited together with the tp_traverse and tp_clear fields, i.e. if the Py_TPFLAGS_HAVE_GC flag bit is clear in the subtype and the tp_traverse and tp_clear fields in the subtype exist and have NULL values.

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: Py_TPFLAGS_HAVE_STACKLESS_EXTENSION.

継承:

???

Py_TPFLAGS_METHOD_DESCRIPTOR

This bit indicates that objects behave like unbound methods.

If this flag is set for type(meth), then:

meth.__get__(obj, cls)(*args, **kwds) (with obj not None) must be equivalent to meth(obj, *args, **kwds).

meth.__get__(None, cls)(*args, **kwds) must be equivalent to meth(*args, **kwds).

This flag enables an optimization for typical method calls like obj.meth(): it avoids creating a temporary "bound method" object for obj.meth.

Added in version 3.8.

継承:

This flag is never inherited by types without the Py_TPFLAGS_IMMUTABLETYPE flag set. For extension types, it is inherited whenever tp_descr_get is inherited.

Py_TPFLAGS_MANAGED_DICT

This bit indicates that instances of the class have a __dict__ attribute, and that the space for the dictionary is managed by the VM.

If this flag is set, Py_TPFLAGS_HAVE_GC should also be set.

Added in version 3.12.

継承:

This flag is inherited unless the tp_dictoffset field is set in a superclass.

Py_TPFLAGS_MANAGED_WEAKREF

This bit indicates that instances of the class should be weakly referenceable.

Added in version 3.12.

継承:

This flag is inherited unless the tp_weaklistoffset field is set in a superclass.

Py_TPFLAGS_ITEMS_AT_END

Only usable with variable-size types, i.e. ones with non-zero 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 Py_TYPE(obj)->tp_basicsize (which may be different in each subclass).

When setting this flag, be sure that all superclasses either use this memory layout, or are not variable-sized. Python does not check this.

Added in version 3.12.

継承:

This flag is inherited.

Py_TPFLAGS_LONG_SUBCLASS

Py_TPFLAGS_LIST_SUBCLASS

Py_TPFLAGS_TUPLE_SUBCLASS

Py_TPFLAGS_BYTES_SUBCLASS

Py_TPFLAGS_UNICODE_SUBCLASS

Py_TPFLAGS_DICT_SUBCLASS

Py_TPFLAGS_BASE_EXC_SUBCLASS

Py_TPFLAGS_TYPE_SUBCLASS

これらのフラグは PyLong_Check() のような関数が、型がとある組み込み型のサブクラスかどうかを素早く判断するのに使われます; この専用のチェックは PyObject_IsInstance() のような汎用的なチェックよりも高速です。組み込み型を継承した独自の型では tp_flags を適切に設定すべきで、そうしないとその型が関わるコードでは、どんなチェックの方法が使われるかによって振る舞いが異なってしまうでしょう。

Py_TPFLAGS_HAVE_FINALIZE

型構造体に tp_finalize スロットが存在しているときにセットされるビットです。

Added in version 3.4.

バージョン 3.8 で非推奨: This flag isn't necessary anymore, as the interpreter assumes the tp_finalize slot is always present in the type structure.

Py_TPFLAGS_HAVE_VECTORCALL

This bit is set when the class implements the vectorcall protocol. See tp_vectorcall_offset for details.

継承:

This bit is inherited if tp_call is also inherited.

Added in version 3.9.

バージョン 3.12 で変更: This flag is now removed from a class when the class's __call__() method is reassigned.

This flag can now be inherited by mutable classes.

Py_TPFLAGS_IMMUTABLETYPE

This bit is set for type objects that are immutable: type attributes cannot be set nor deleted.

PyType_Ready() automatically applies this flag to static types.

継承:

This flag is not inherited.

Added in version 3.10.

Py_TPFLAGS_DISALLOW_INSTANTIATION

Disallow creating instances of the type: set tp_new to NULL and don't create the __new__ key in the type dictionary.

The flag must be set before creating the type, not after. For example, it must be set before PyType_Ready() is called on the type.

The flag is set automatically on static types if tp_base is NULL or &PyBaseObject_Type and tp_new is NULL.

継承:

This flag is not inherited. However, subclasses will not be instantiable unless they provide a non-NULL tp_new (which is only possible via the C API).

注釈

To disallow instantiating a class directly but allow instantiating its subclasses (e.g. for an abstract base class), do not use this flag. Instead, make tp_new only succeed for subclasses.

Added in version 3.10.

Py_TPFLAGS_MAPPING

This bit indicates that instances of the class may match mapping patterns when used as the subject of a match block. It is automatically set when registering or subclassing collections.abc.Mapping, and unset when registering collections.abc.Sequence.

注釈

Py_TPFLAGS_MAPPING and Py_TPFLAGS_SEQUENCE are mutually exclusive; it is an error to enable both flags simultaneously.

継承:

This flag is inherited by types that do not already set Py_TPFLAGS_SEQUENCE.

参考

PEP 634 [https://peps.python.org/pep-0634/] -- 構造的パターンマッチ: 仕様

Added in version 3.10.

Py_TPFLAGS_SEQUENCE

This bit indicates that instances of the class may match sequence patterns when used as the subject of a match block. It is automatically set when registering or subclassing collections.abc.Sequence, and unset when registering collections.abc.Mapping.

注釈

Py_TPFLAGS_MAPPING and Py_TPFLAGS_SEQUENCE are mutually exclusive; it is an error to enable both flags simultaneously.

継承:

This flag is inherited by types that do not already set Py_TPFLAGS_MAPPING.

参考

PEP 634 [https://peps.python.org/pep-0634/] -- 構造的パターンマッチ: 仕様

Added in version 3.10.

Py_TPFLAGS_VALID_VERSION_TAG

Internal. Do not set or unset this flag. To indicate that a class has changed call PyType_Modified()

警告

This flag is present in header files, but is an internal feature and should not be used. It will be removed in a future version of CPython

const char *PyTypeObject.tp_doc

オプションのポインタで、この型オブジェクトの docstring を与える NUL 終端された C の文字列を指します。この値は型オブジェクトと型のインスタンスにおける __doc__ 属性として公開されます。

継承:

サブタイプはこのフィールドを継承 しません 。

traverseproc PyTypeObject.tp_traverse

An optional pointer to a traversal function for the garbage collector. This is only used if the Py_TPFLAGS_HAVE_GC flag bit is set. The signature is:

int tp_traverse(PyObject *self, visitproc visit, void *arg);

Pythonのガベージコレクションの仕組みについての詳細は、 循環参照ガベージコレクションをサポートする にあります。

The tp_traverse pointer is used by the garbage collector to detect reference cycles. A typical implementation of a tp_traverse function simply calls Py_VISIT() on each of the instance's members that are Python objects that the instance owns. For example, this is function local_traverse() from the _thread extension module:

static int
local_traverse(localobject *self, visitproc visit, void *arg)
{
    Py_VISIT(self->args);
    Py_VISIT(self->kw);
    Py_VISIT(self->dict);
    return 0;
}

Py_VISIT() が循環参照になる恐れのあるメンバにだけ呼び出されていることに注目してください。 self->key メンバもありますが、それは NULL か Python文字列なので、循環参照の一部になることはありません。

一方、メンバが循環参照の一部になり得ないと判っていても、デバッグ目的で巡回したい場合があるかもしれないので、 gc モジュールの get_referents() 関数は循環参照になり得ないメンバも返します。

警告

When implementing tp_traverse, only the members that the instance owns (by having strong references to them) must be visited. For instance, if an object supports weak references via the 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).

Note that Py_VISIT() requires the visit and arg parameters to local_traverse() to have these specific names; don't name them just anything.

Instances of heap-allocated types hold a reference to their type. Their traversal function must therefore either visit Py_TYPE(self), or delegate this responsibility by calling 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.

バージョン 3.9 で変更: Heap-allocated types are expected to visit Py_TYPE(self) in tp_traverse. In earlier versions of Python, due to bug 40217 [https://bugs.python.org/issue40217], doing this may lead to crashes in subclasses.

継承:

Group: Py_TPFLAGS_HAVE_GC, tp_traverse, tp_clear

This field is inherited by subtypes together with tp_clear and the Py_TPFLAGS_HAVE_GC flag bit: the flag bit, tp_traverse, and tp_clear are all inherited from the base type if they are all zero in the subtype.

inquiry PyTypeObject.tp_clear

An optional pointer to a clear function for the garbage collector. This is only used if the Py_TPFLAGS_HAVE_GC flag bit is set. The signature is:

int tp_clear(PyObject *);

tp_clear メンバ関数は GC が検出した循環しているゴミの循環参照を壊すために用いられます。総合的な視点で考えると、システム内の全ての tp_clear 関数が連携して、全ての循環参照を破壊しなければなりません。 (訳注: ある型が tp_clear を実装しなくても全ての循環参照が破壊できるのであれば実装しなくても良い) これはとても繊細で、もし少しでも不確かな部分があるのであれば、 tp_clear 関数を提供するべきです。例えば、タプルは tp_clear を実装しません。なぜなら、タプルだけで構成された循環参照がみつかることは無いからです。従って、タプル以外の型の tp_clear 関数だけで、タプルを含むどんな循環参照も必ず破壊できることになります。これは簡単に判ることではなく、 tp_clear の実装を避ける良い理由はめったにありません。

次の例にあるように、 tp_clear の実装は、インスタンスから Python オブジェクトだと思われるメンバへの参照を外し、それらのメンバへのポインタに NULL をセットすべきです:

static int
local_clear(localobject *self)
{
    Py_CLEAR(self->key);
    Py_CLEAR(self->args);
    Py_CLEAR(self->kw);
    Py_CLEAR(self->dict);
    return 0;
}

The Py_CLEAR() macro should be used, because clearing references is delicate: the reference to the contained object must not be released (via Py_DECREF()) until after the pointer to the contained object is set to 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 NULL at that time, so that self knows the contained object can no longer be used. The Py_CLEAR() macro performs the operations in a safe order.

Note that tp_clear is not always called before an instance is deallocated. For example, when reference counting is enough to determine that an object is no longer used, the cyclic garbage collector is not involved and tp_dealloc is called directly.

tp_clear 関数の目的は参照カウントを破壊することなので、 Python 文字列や Python 整数のような、循環参照に含むことのできないオブジェクトをクリアする必要はありません。一方、所有する全ての Python オブジェクトをクリアするようにし、その型の tp_dealloc 関数が tp_clear 関数を実行するようにすると実装が楽になるでしょう。

Pythonのガベージコレクションの仕組みについての詳細は、 循環参照ガベージコレクションをサポートする にあります。

継承:

Group: Py_TPFLAGS_HAVE_GC, tp_traverse, tp_clear

This field is inherited by subtypes together with tp_traverse and the Py_TPFLAGS_HAVE_GC flag bit: the flag bit, tp_traverse, and tp_clear are all inherited from the base type if they are all zero in the subtype.

richcmpfunc PyTypeObject.tp_richcompare

オプションのポインタで、拡張比較関数を指します。シグネチャは次の通りです:

PyObject *tp_richcompare(PyObject *self, PyObject *other, int op);

The first parameter is guaranteed to be an instance of the type that is defined by PyTypeObject.

この関数は、比較結果を返すべきです。(普通は Py_True か Py_False です。) 比較が未定義の場合は、Py_NotImplemented を、それ以外のエラーが発生した場合には例外状態をセットして NULL を返さなければなりません。

tp_richcompare および PyObject_RichCompare() 関数の第三引数に使うための定数としては以下が定義されています:

定数

比較

Py_LT

<

Py_LE

<=

Py_EQ

==

Py_NE

!=

Py_GT

>

Py_GE

>=

拡張比較関数(rich comparison functions)を簡単に記述するためのマクロが定義されています:

Py_RETURN_RICHCOMPARE(VAL_A, VAL_B, op)

比較した結果に応じて Py_True か Py_False を返します。 VAL_A と VAL_B は C の比較演算によって順序付け可能でなければなりません（例えばこれらは C言語の整数か浮動小数点数になるでしょう）。三番目の引数には PyObject_RichCompare() と同様に要求された演算を指定します。

The returned value is a new strong reference.

エラー時には例外を設定して、関数から NULL でリターンします。

Added in version 3.7.

継承:

Group: tp_hash, tp_richcompare

このフィールドは tp_hash と共にサブタイプに継承されます: すなわち、サブタイプの tp_richcompare および tp_hash が両方とも NULL のとき、サブタイプは基底タイプから tp_richcompare と tp_hash を両方とも継承します。

デフォルト

PyBaseObject_Type provides a tp_richcompare implementation, which may be inherited. However, if only 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.

Py_ssize_t PyTypeObject.tp_weaklistoffset

While this field is still supported, Py_TPFLAGS_MANAGED_WEAKREF should be used instead, if at all possible.

型のインスタンスが弱参照可能な場合、このフィールドはゼロよりも大きな数になり、インスタンス構造体における弱参照リストの先頭を示すオフセットが入ります (GC ヘッダがある場合には無視します); このオフセット値は PyObject_ClearWeakRefs() および PyWeakref_* 関数が利用します。インスタンス構造体には、 NULL に初期化された PyObject* 型のフィールドが入っていなければなりません。

このフィールドを tp_weaklist と混同しないようにしてください; これは型オブジェクト自身への弱参照からなるリストの先頭です。

It is an error to set both the Py_TPFLAGS_MANAGED_WEAKREF bit and tp_weaklist.

継承:

このフィールドはサブタイプに継承されますが、以下の規則を読んでください。サブタイプはこのオフセット値をオーバライドすることがあります; 従って、サブタイプでは弱参照リストの先頭が基底タイプとは異なる場合があります。リストの先頭は常に tp_weaklistoffset で分かるはずなので、このことは問題にはならないはずです。

デフォルト

If the Py_TPFLAGS_MANAGED_WEAKREF bit is set in the tp_dict field, then tp_weaklistoffset will be set to a negative value, to indicate that it is unsafe to use this field.

getiterfunc PyTypeObject.tp_iter

オプションの変数で、そのオブジェクトの イテレータ を返す関数へのポインタです。この値が存在することは、通常この型のインスタンスが イテレート可能 であることを示しています (しかし、シーケンスはこの関数がなくてもイテレート可能です)。

この関数は PyObject_GetIter() と同じシグネチャを持っています:

PyObject *tp_iter(PyObject *self);

継承:

サブタイプはこのフィールドを継承します。

iternextfunc PyTypeObject.tp_iternext

オプションのポインタで、:term:`イテレーター <iterator>`の次の要素を返す関数を指します。シグネチャは次の通りです:

PyObject *tp_iternext(PyObject *self);

イテレータの要素がなくなると、この関数は NULL を返さなければなりません。 StopIteration 例外は設定してもしなくても良いです。その他のエラーが発生したときも、 NULL を返さなければなりません。このフィールドがあると、この型のインスタンスがイテレータであることを示します。

イテレータ型では、 tp_iter 関数も定義されていなければならず、その関数は (新たなイテレータインスタンスではなく) イテレータインスタンス自体を返さねばなりません。

この関数のシグネチャは PyIter_Next() と同じです。

継承:

サブタイプはこのフィールドを継承します。

struct PyMethodDef *PyTypeObject.tp_methods

オプションのポインタで、この型の正規 (regular) のメソッドを宣言している PyMethodDef 構造体からなる、 NULL で終端された静的な配列を指します。

配列の各要素ごとに、メソッドデスクリプタの入った、要素が型の辞書 (下記の tp_dict 参照) に追加されます。

継承:

サブタイプはこのフィールドを継承しません (メソッドは別個のメカニズムで継承されています)。

struct PyMemberDef *PyTypeObject.tp_members

オプションのポインタで、型の正規 (regular) のデータメンバ (フィールドおよびスロット) を宣言している PyMemberDef 構造体からなる、 NULL で終端された静的な配列を指します。

配列の各要素ごとに、メンバデスクリプタの入った要素が型の辞書 (下記の tp_dict 参照) に追加されます。

継承:

サブタイプはこのフィールドを継承しません (メンバは別個のメカニズムで継承されています)。

struct PyGetSetDef *PyTypeObject.tp_getset

オプションのポインタで、インスタンスの算出属性 (computed attribute) を宣言している PyGetSetDef 構造体からなる、 NULL で終端された静的な配列を指します。

配列の各要素ごとに、 getter/setter デスクリプタの入った、要素が型の辞書 (下記の tp_dict 参照) に追加されます。

継承:

サブタイプはこのフィールドを継承しません (算出属性は別個のメカニズムで継承されています)。

PyTypeObject *PyTypeObject.tp_base

オプションのポインタで、型に関するプロパティを継承する基底タイプを指します。このフィールドのレベルでは、単継承 (single inheritance) だけがサポートされています; 多重継承はメタタイプの呼び出しによる動的な型オブジェクトの生成を必要とします。

注釈

Slot initialization is subject to the rules of initializing globals. C99 requires the initializers to be "address constants". Function designators like PyType_GenericNew(), with implicit conversion to a pointer, are valid C99 address constants.

However, the unary '&' operator applied to a non-static variable like 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, tp_base should be set in the extension module's init function.

継承:

(当たり前ですが) サブタイプはこのフィールドを継承しません。

デフォルト

このフィールドのデフォルト値は (Python プログラマは object 型として知っている) &PyBaseObject_Type になります。

PyObject *PyTypeObject.tp_dict

型の辞書は PyType_Ready() によってこのフィールドに収められます。

This field should normally be initialized to NULL before PyType_Ready is called; it may also be initialized to a dictionary containing initial attributes for the type. Once 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 __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 PyType_GetDict() to retrieve the dictionary for an arbitrary type.

バージョン 3.12 で変更: Internals detail: For static builtin types, this is always NULL. Instead, the dict for such types is stored on PyInterpreterState. Use PyType_GetDict() to get the dict for an arbitrary type.

継承:

サブタイプはこのフィールドを継承しません (が、この辞書内で定義されている属性は異なるメカニズムで継承されます)。

デフォルト

If this field is NULL, PyType_Ready() will assign a new dictionary to it.

警告

tp_dict に PyDict_SetItem() を使ったり、辞書 C-API で編集するのは安全ではありません。

descrgetfunc PyTypeObject.tp_descr_get

オプションのポインタで、デスクリプタの get 関数を指します。

関数のシグネチャは次のとおりです

PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type);

継承:

サブタイプはこのフィールドを継承します。

descrsetfunc PyTypeObject.tp_descr_set

オプションのポインタで、デスクリプタの値の設定と削除を行う関数を指します。

関数のシグネチャは次のとおりです

int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value);

値を削除するには、value 引数に NULL を設定します。

継承:

サブタイプはこのフィールドを継承します。

Py_ssize_t PyTypeObject.tp_dictoffset

While this field is still supported, Py_TPFLAGS_MANAGED_DICT should be used instead, if at all possible.

型のインスタンスにインスタンス変数の入った辞書がある場合、このフィールドは非ゼロの値になり、型のインスタンスデータ構造体におけるインスタンス変数辞書へのオフセットが入ります; このオフセット値は PyObject_GenericGetAttr() が使います。

このフィールドを tp_dict と混同しないようにしてください; これは型オブジェクト自身の属性の辞書です。

The value specifies the offset of the dictionary from the start of the instance structure.

The tp_dictoffset should be regarded as write-only. To get the pointer to the dictionary call PyObject_GenericGetDict(). Calling PyObject_GenericGetDict() may need to allocate memory for the dictionary, so it is may be more efficient to call PyObject_GetAttr() when accessing an attribute on the object.

It is an error to set both the Py_TPFLAGS_MANAGED_WEAKREF bit and tp_dictoffset.

継承:

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 Py_TPFLAGS_MANAGED_DICT.

デフォルト

This slot has no default. For static types, if the field is NULL then no __dict__ gets created for instances.

If the Py_TPFLAGS_MANAGED_DICT bit is set in the tp_dict field, then tp_dictoffset will be set to -1, to indicate that it is unsafe to use this field.

initproc PyTypeObject.tp_init

オプションのポインタで、インスタンス初期化関数を指します。

This function corresponds to the __init__() method of classes. Like __init__(), it is possible to create an instance without calling __init__(), and it is possible to reinitialize an instance by calling its __init__() method again.

関数のシグネチャは次のとおりです

int tp_init(PyObject *self, PyObject *args, PyObject *kwds);

The self argument is the instance to be initialized; the args and kwds arguments represent positional and keyword arguments of the call to __init__().

tp_init 関数のフィールドが NULL でない場合、通常の型を呼び出す方法のインスタンス生成において、型の tp_new 関数がインスタンスを返した後に呼び出されます。 tp_new が元の型のサブタイプでない別の型を返す場合、 tp_init は全く呼び出されません; tp_new が元の型のサブタイプのインスタンスを返す場合、サブタイプの tp_init が呼び出されます。

成功のときには 0 を、エラー時には例外をセットして -1 を返します。

継承:

サブタイプはこのフィールドを継承します。

デフォルト

For static types this field does not have a default.

allocfunc PyTypeObject.tp_alloc

オプションのポインタで、インスタンスのメモリ確保関数を指します。

関数のシグネチャは次のとおりです

PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems);

継承:

This field is inherited by static subtypes, but not by dynamic subtypes (subtypes created by a class statement).

デフォルト

For dynamic subtypes, this field is always set to PyType_GenericAlloc(), to force a standard heap allocation strategy.

For static subtypes, PyBaseObject_Type uses PyType_GenericAlloc(). That is the recommended value for all statically defined types.

newfunc PyTypeObject.tp_new

オプションのポインタで、インスタンス生成関数を指します。

関数のシグネチャは次のとおりです

PyObject *tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds);

subtype 引数は生成するオブジェクトの型です; args および kwds 引数は、型を呼び出すときの位置引数およびキーワード引数です。subtype は tp_new 関数を呼び出すときに使う型と同じである必要はないことに注意してください; その型の (無関係ではない) サブタイプのこともあります。

tp_new 関数は subtype->tp_alloc(subtype, nitems) を呼び出してオブジェクトのメモリ領域を確保し、初期化で絶対に必要とされる処理だけを行います。省略したり繰り返したりしても問題のない初期化処理は tp_init ハンドラ内に配置しなければなりません。だいたいの目安としては、変更不能な型では初期化は全て tp_new で行い、一方、変更可能な型ではほとんどの初期化を tp_init に回すべきです。

Set the Py_TPFLAGS_DISALLOW_INSTANTIATION flag to disallow creating instances of the type in Python.

継承:

サブタイプはこのフィールドを継承します。例外として、 tp_base が NULL か &PyBaseObject_Type になっている 静的な型 では継承しません。

デフォルト

For static types this field has no default. This means if the slot is defined as NULL, the type cannot be called to create new instances; presumably there is some other way to create instances, like a factory function.

freefunc PyTypeObject.tp_free

オプションのポインタで、インスタンスのメモリ解放関数を指します。シグネチャは以下の通りです:

void tp_free(void *self);

このシグネチャと互換性のある初期化子は PyObject_Free() です。

継承:

This field is inherited by static subtypes, but not by dynamic subtypes (subtypes created by a class statement)

デフォルト

In dynamic subtypes, this field is set to a deallocator suitable to match PyType_GenericAlloc() and the value of the Py_TPFLAGS_HAVE_GC flag bit.

For static subtypes, PyBaseObject_Type uses PyObject_Del().

inquiry PyTypeObject.tp_is_gc

オプションのポインタで、ガベージコレクタから呼び出される関数を指します。

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 tp_flags field, and check the 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 1 for a collectible instance, and 0 for a non-collectible instance. The signature is:

int tp_is_gc(PyObject *self);

(上記のような型の例は、型オブジェクト自体です。メタタイプ PyType_Type は、型のメモリ確保が静的か 動的 かを区別するためにこの関数を定義しています。)

継承:

サブタイプはこのフィールドを継承します。

デフォルト

This slot has no default. If this field is NULL, Py_TPFLAGS_HAVE_GC is used as the functional equivalent.

PyObject *PyTypeObject.tp_bases

基底型からなるタプルです。

This field should be set to NULL and treated as read-only. Python will fill it in when the type is initialized.

For dynamically created classes, the Py_tp_bases slot can be used instead of the bases argument of PyType_FromSpecWithBases(). The argument form is preferred.

警告

Multiple inheritance does not work well for statically defined types. If you set tp_bases to a tuple, Python will not raise an error, but some slots will only be inherited from the first base.

継承:

このフィールドは継承されません。

PyObject *PyTypeObject.tp_mro

基底タイプ群を展開した集合が入っているタプルです。集合は該当する型自体からはじまり、 object で終わります。メソッド解決順序 (Method Resolution Order) に従って並んでいます。

This field should be set to NULL and treated as read-only. Python will fill it in when the type is initialized.

継承:

このフィールドは継承されません; フィールドの値は PyType_Ready() で毎回計算されます。

PyObject *PyTypeObject.tp_cache

未使用のフィールドです。内部でのみ利用されます。

継承:

このフィールドは継承されません。

void *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 __subclasses__().

バージョン 3.12 で変更: For some types, this field does not hold a valid PyObject*. The type was changed to void* to indicate this.

継承:

このフィールドは継承されません。

PyObject *PyTypeObject.tp_weaklist

この型オブジェクトに対する弱参照からなるリストの先頭です。

バージョン 3.12 で変更: Internals detail: For the static builtin types this is always NULL, even if weakrefs are added. Instead, the weakrefs for each are stored on PyInterpreterState. Use the public C-API or the internal _PyObject_GET_WEAKREFS_LISTPTR() macro to avoid the distinction.

継承:

このフィールドは継承されません。

destructor PyTypeObject.tp_del

このフィールドは廃止されました。tp_finalize を代わりに利用してください。

unsigned int PyTypeObject.tp_version_tag

メソッドキャッシュへのインデックスとして使われます。内部使用だけのための関数です。

継承:

このフィールドは継承されません。

destructor PyTypeObject.tp_finalize

オプションのポインタで、インスタンスの終了処理関数を指します。シグネチャは以下の通りです:

void tp_finalize(PyObject *self);

tp_finalize が設定されている場合、インスタンスをファイナライズするときに、インタプリタがこの関数を1回呼び出します。ガベージコレクタ (このインスタンスが孤立した循環参照の一部だった場合) やオブジェクトが破棄される直前にもこの関数は呼び出されます。どちらの場合でも、循環参照を破壊しようとする前に呼び出されることが保証されていて、確実にオブジェクトが正常な状態にあるようにします。

tp_finalize は現在の例外状態を変更すべきではありません; 従って、単純でないファイナライザを書くには次の方法が推奨されます:

static void
local_finalize(PyObject *self)
{
    PyObject *error_type, *error_value, *error_traceback;

    /* Save the current exception, if any. */
    PyErr_Fetch(&error_type, &error_value, &error_traceback);

    /* ... */

    /* Restore the saved exception. */
    PyErr_Restore(error_type, error_value, error_traceback);
}

また、 Python のガベージコレクションでは、 tp_dealloc を呼び出すのはオブジェクトを生成したスレッドだけではなく、任意の Python スレッドかもしれないという点にも注意して下さい。 (オブジェクトが循環参照の一部の場合、任意のスレッドのガベージコレクションによって解放されてしまうかもしれません)。Python API 側からみれば、 tp_dealloc を呼び出すスレッドはグローバルインタプリタロック (GIL: Global Interpreter Lock) を獲得するので、これは問題ではありません。しかしながら、削除されようとしているオブジェクトが何らかの C や C++ ライブラリ由来のオブジェクトを削除する場合、 tp_dealloc を呼び出すスレッドのオブジェクトを削除することで、ライブラリの仮定している何らかの規約に違反しないように気を付ける必要があります。

継承:

サブタイプはこのフィールドを継承します。

Added in version 3.4.

バージョン 3.8 で変更: Before version 3.8 it was necessary to set the Py_TPFLAGS_HAVE_FINALIZE flags bit in order for this field to be used. This is no longer required.

参考

"オブジェクトの安全な終了処理" (PEP 442 [https://peps.python.org/pep-0442/])

vectorcallfunc PyTypeObject.tp_vectorcall

Vectorcall function to use for calls of this type object. In other words, it is used to implement vectorcall for type.__call__. If tp_vectorcall is NULL, the default call implementation using __new__() and __init__() is used.

継承:

このフィールドは決して継承されません。

Added in version 3.9: （このフィールドは3.8から存在していますが、3.9以降でしか利用できません）

unsigned char PyTypeObject.tp_watched

Internal. Do not use.

Added in version 3.12.

Static Types

Traditionally, types defined in C code are static, that is, a static PyTypeObject structure is defined directly in code and initialized using PyType_Ready().

This results in types that are limited relative to types defined in Python:

Static types are limited to one base, i.e. they cannot use multiple inheritance.

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.

Static type objects are shared across sub-interpreters, so they should not include any subinterpreter-specific state.

Also, since PyTypeObject is only part of the Limited API as an opaque struct, any extension modules using static types must be compiled for a specific Python minor version.

Heap Types

An alternative to static types is heap-allocated types, or heap types for short, which correspond closely to classes created by Python's class statement. Heap types have the Py_TPFLAGS_HEAPTYPE flag set.

This is done by filling a PyType_Spec structure and calling PyType_FromSpec(), PyType_FromSpecWithBases(), PyType_FromModuleAndSpec(), or PyType_FromMetaclass().

数値オブジェクト構造体

type PyNumberMethods

この構造体は数値型プロトコルを実装するために使われる関数群へのポインタを保持しています。以下のそれぞれの関数は 数値型プロトコル (number protocol) で解説されている似た名前の関数から利用されます。

以下は構造体の定義です:

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;

注釈

二項関数と三項関数は、すべてのオペランドの型をチェックしなければならず、必要な変換を実装しなければなりません (すくなくともオペランドの一つは定義している型のインスタンスです). もし与えられたオペランドに対して操作が定義されなければ、二項関数と三項関数は Py_NotImplemented を返さなければならず、他のエラーが起こった場合は、NULL を返して例外を設定しなければなりません。

注釈

The nb_reserved field should always be NULL. It was previously called nb_long, and was renamed in Python 3.0.1.

binaryfunc PyNumberMethods.nb_add

binaryfunc PyNumberMethods.nb_subtract

binaryfunc PyNumberMethods.nb_multiply

binaryfunc PyNumberMethods.nb_remainder

binaryfunc PyNumberMethods.nb_divmod

ternaryfunc PyNumberMethods.nb_power

unaryfunc PyNumberMethods.nb_negative

unaryfunc PyNumberMethods.nb_positive

unaryfunc PyNumberMethods.nb_absolute

inquiry PyNumberMethods.nb_bool

unaryfunc PyNumberMethods.nb_invert

binaryfunc PyNumberMethods.nb_lshift

binaryfunc PyNumberMethods.nb_rshift

binaryfunc PyNumberMethods.nb_and

binaryfunc PyNumberMethods.nb_xor

binaryfunc PyNumberMethods.nb_or

unaryfunc PyNumberMethods.nb_int

void *PyNumberMethods.nb_reserved

unaryfunc PyNumberMethods.nb_float

binaryfunc PyNumberMethods.nb_inplace_add

binaryfunc PyNumberMethods.nb_inplace_subtract

binaryfunc PyNumberMethods.nb_inplace_multiply

binaryfunc PyNumberMethods.nb_inplace_remainder

ternaryfunc PyNumberMethods.nb_inplace_power

binaryfunc PyNumberMethods.nb_inplace_lshift

binaryfunc PyNumberMethods.nb_inplace_rshift

binaryfunc PyNumberMethods.nb_inplace_and

binaryfunc PyNumberMethods.nb_inplace_xor

binaryfunc PyNumberMethods.nb_inplace_or

binaryfunc PyNumberMethods.nb_floor_divide

binaryfunc PyNumberMethods.nb_true_divide

binaryfunc PyNumberMethods.nb_inplace_floor_divide

binaryfunc PyNumberMethods.nb_inplace_true_divide

unaryfunc PyNumberMethods.nb_index

binaryfunc PyNumberMethods.nb_matrix_multiply

binaryfunc PyNumberMethods.nb_inplace_matrix_multiply

マップオブジェクト構造体

type PyMappingMethods

この構造体はマップ型プロトコルを実装するために使われる関数群へのポインタを保持しています。以下の3つのメンバを持っています:

lenfunc PyMappingMethods.mp_length

この関数は PyMapping_Size() や PyObject_Size() から利用され、それらと同じシグネチャを持っています。オブジェクトが定義された長さを持たない場合は、このスロットは NULL に設定されることがあります。

binaryfunc PyMappingMethods.mp_subscript

この関数は PyObject_GetItem() および PySequence_GetSlice() から利用され、PySequence_GetSlice() と同じシグネチャを持っています。このスロットは PyMapping_Check() が 1 を返すためには必要で、そうでなければ NULL の場合があります。

objobjargproc PyMappingMethods.mp_ass_subscript

This function is used by PyObject_SetItem(), PyObject_DelItem(), PySequence_SetSlice() and PySequence_DelSlice(). It has the same signature as PyObject_SetItem(), but v can also be set to NULL to delete an item. If this slot is NULL, the object does not support item assignment and deletion.

シーケンスオブジェクト構造体

type PySequenceMethods

この構造体はシーケンス型プロトコルを実装するために使われる関数群へのポインタを保持しています。

lenfunc PySequenceMethods.sq_length

This function is used by PySequence_Size() and PyObject_Size(), and has the same signature. It is also used for handling negative indices via the sq_item and the sq_ass_item slots.

binaryfunc PySequenceMethods.sq_concat

この関数は PySequence_Concat() で利用され、同じシグネチャを持っています。また、 + 演算子でも、 nb_add スロットによる数値加算を試した後に利用されます。

ssizeargfunc PySequenceMethods.sq_repeat

この関数は PySequence_Repeat() で利用され、同じシグネチャを持っています。また、 * 演算でも、 nb_multiply スロットによる数値乗算を試したあとに利用されます。

ssizeargfunc PySequenceMethods.sq_item

This function is used by PySequence_GetItem() and has the same signature. It is also used by PyObject_GetItem(), after trying the subscription via the mp_subscript slot. This slot must be filled for the PySequence_Check() function to return 1, it can be NULL otherwise.

Negative indexes are handled as follows: if the sq_length slot is filled, it is called and the sequence length is used to compute a positive index which is passed to sq_item. If sq_length is NULL, the index is passed as is to the function.

ssizeobjargproc PySequenceMethods.sq_ass_item

This function is used by PySequence_SetItem() and has the same signature. It is also used by PyObject_SetItem() and PyObject_DelItem(), after trying the item assignment and deletion via the mp_ass_subscript slot. This slot may be left to NULL if the object does not support item assignment and deletion.

objobjproc PySequenceMethods.sq_contains

この関数は PySequence_Contains() から利用され、同じシグネチャを持っています。このスロットは NULL の場合があり、その時 PySequence_Contains() はシンプルにマッチするオブジェクトを見つけるまでシーケンスを巡回します。

binaryfunc PySequenceMethods.sq_inplace_concat

This function is used by PySequence_InPlaceConcat() and has the same signature. It should modify its first operand, and return it. This slot may be left to NULL, in this case PySequence_InPlaceConcat() will fall back to PySequence_Concat(). It is also used by the augmented assignment +=, after trying numeric in-place addition via the nb_inplace_add slot.

ssizeargfunc PySequenceMethods.sq_inplace_repeat

This function is used by PySequence_InPlaceRepeat() and has the same signature. It should modify its first operand, and return it. This slot may be left to NULL, in this case PySequence_InPlaceRepeat() will fall back to PySequence_Repeat(). It is also used by the augmented assignment *=, after trying numeric in-place multiplication via the nb_inplace_multiply slot.

バッファオブジェクト構造体 (buffer object structure)

type PyBufferProcs

この構造体は buffer プロトコル が要求する関数群へのポインタを保持しています。そのプロトコルは、エクスポーターオブジェクトが如何にして、その内部データをコンシューマオブジェクトに渡すかを定義します。

getbufferproc PyBufferProcs.bf_getbuffer

この関数のシグネチャは以下の通りです:

int (PyObject *exporter, Py_buffer *view, int flags);

flags で指定された方法で view を埋めてほしいという exporter に対する要求を処理します。ステップ(3) を除いて、この関数の実装では以下のステップを行わなければなりません:

Check if the request can be met. If not, raise BufferError, set view->obj to NULL and return -1.

要求されたフィールドを埋めます。

エクスポートした回数を保持する内部カウンタをインクリメントします。

view->obj に exporter を設定し、 view->obj をインクリメントします。

0 を返します。

exporter がバッファプロバイダのチェインかツリーの一部であれば、２つの主要な方式が使用できます:

再エクスポート: ツリーの各要素がエクスポートされるオブジェクトとして振る舞い、自身への新しい参照を view->obj へセットします。

リダイレクト: バッファ要求がツリーのルートオブジェクトにリダイレクトされます。ここでは、 view->obj はルートオブジェクトへの新しい参照になります。

view の個別のフィールドは バッファ構造体 の節で説明されており、エクスポートが特定の要求に対しどう対応しなければならないかの規則は、 バッファ要求のタイプ の節にあります。

Py_buffer 構造体の中から参照している全てのメモリはエクスポータに属し、コンシューマがいなくなるまで有効でなくてはなりません。 format 、 shape 、 strides 、 suboffsets 、 internal はコンシューマからは読み出し専用です。

PyBuffer_FillInfo() は、全てのリクエストタイプを正しく扱う際に、単純なバイトバッファを公開する簡単な方法を提供します。

PyObject_GetBuffer() は、この関数をラップするコンシューマ向けのインターフェースです。

releasebufferproc PyBufferProcs.bf_releasebuffer

この関数のシグネチャは以下の通りです:

void (PyObject *exporter, Py_buffer *view);

バッファのリソースを開放する要求を処理します。もし開放する必要のあるリソースがない場合、 PyBufferProcs.bf_releasebuffer は NULL にしても構いません。そうでない場合は、この関数の標準的な実装は、以下の任意の処理手順 (optional step) を行います:

エクスポートした回数を保持する内部カウンタをデクリメントします。

カウンタが 0 の場合は、view に関連付けられた全てのメモリを解放します。

エクスポータは、バッファ固有のリソースを監視し続けるために internal フィールドを使わなければなりません。このフィールドは、コンシューマが view 引数としてオリジナルのバッファのコピーを渡しているであろう間、変わらないことが保証されています。

この関数は、view->obj をデクリメントしてはいけません、なぜならそれは PyBuffer_Release() で自動的に行われるからです(この方式は参照の循環を防ぐのに有用です)。

PyBuffer_Release() は、この関数をラップするコンシューマ向けのインターフェースです。

async オブジェクト構造体

Added in version 3.5.

type PyAsyncMethods

この構造体は awaitable オブジェクトと asynchronous iterator オブジェクトを実装するのに必要な関数へのポインタを保持しています。

以下は構造体の定義です:

typedef struct {
    unaryfunc am_await;
    unaryfunc am_aiter;
    unaryfunc am_anext;
    sendfunc am_send;
} PyAsyncMethods;

unaryfunc PyAsyncMethods.am_await

この関数のシグネチャは以下の通りです:

PyObject *am_await(PyObject *self);

返されるオブジェクトは イテレータ でなければなりません。つまりこのオブジェクトに対して PyIter_Check() が 1 を返さなければなりません。

オブジェクトが awaitable でない場合、このスロットを NULL に設定します。

unaryfunc PyAsyncMethods.am_aiter

この関数のシグネチャは以下の通りです:

PyObject *am_aiter(PyObject *self);

Must return an asynchronous iterator object. See __anext__() for details.

オブジェクトが非同期反復処理のプロトコルを実装していない場合、このスロットを NULL に設定します。

unaryfunc PyAsyncMethods.am_anext

この関数のシグネチャは以下の通りです:

PyObject *am_anext(PyObject *self);

Must return an awaitable object. See __anext__() for details. This slot may be set to NULL.

sendfunc PyAsyncMethods.am_send

この関数のシグネチャは以下の通りです:

PySendResult am_send(PyObject *self, PyObject *arg, PyObject **result);

See PyIter_Send() for details. This slot may be set to NULL.

Added in version 3.10.

Slot Type typedefs

typedef PyObject *(*allocfunc)(PyTypeObject *cls, Py_ssize_t nitems)

Part of the Stable ABI.

The purpose of this function is to separate memory allocation from memory initialization. It should return a pointer to a block of memory of adequate length for the instance, suitably aligned, and initialized to zeros, but with ob_refcnt set to 1 and ob_type set to the type argument. If the type's tp_itemsize is non-zero, the object's ob_size field should be initialized to nitems and the length of the allocated memory block should be tp_basicsize + nitems*tp_itemsize, rounded up to a multiple of sizeof(void*); otherwise, nitems is not used and the length of the block should be tp_basicsize.

この関数では他のいかなるインスタンス初期化も行ってはなりません。追加のメモリ割り当てすらも行ってはなりません。そのような処理は tp_new で行われるべきです。

typedef void (*destructor)(PyObject*)

Part of the Stable ABI.

typedef void (*freefunc)(void*)

tp_free を参照してください。

typedef PyObject *(*newfunc)(PyObject*, PyObject*, PyObject*)

Part of the Stable ABI.

tp_new を参照してください。

typedef int (*initproc)(PyObject*, PyObject*, PyObject*)

Part of the Stable ABI.

tp_init を参照してください。

typedef PyObject *(*reprfunc)(PyObject*)

Part of the Stable ABI.

tp_repr を参照してください。

typedef PyObject *(*getattrfunc)(PyObject *self, char *attr)

Part of the Stable ABI.

オブジェクトの属性の値を返します。

typedef int (*setattrfunc)(PyObject *self, char *attr, PyObject *value)

Part of the Stable ABI.

オブジェクトの属性に値を設定します。属性を削除するには、 value (実) 引数に NULL を設定します。

typedef PyObject *(*getattrofunc)(PyObject *self, PyObject *attr)

Part of the Stable ABI.

オブジェクトの属性の値を返します。

tp_getattro を参照してください。

typedef int (*setattrofunc)(PyObject *self, PyObject *attr, PyObject *value)

Part of the Stable ABI.

オブジェクトの属性に値を設定します。属性を削除するには、 value (実) 引数に NULL を設定します。

tp_setattro を参照してください。

typedef PyObject *(*descrgetfunc)(PyObject*, PyObject*, PyObject*)

Part of the Stable ABI.

tp_descr_get を参照してください。

typedef int (*descrsetfunc)(PyObject*, PyObject*, PyObject*)

Part of the Stable ABI.

tp_descr_set を参照してください。

typedef Py_hash_t (*hashfunc)(PyObject*)

Part of the Stable ABI.

tp_hash を参照してください。

typedef PyObject *(*richcmpfunc)(PyObject*, PyObject*, int)

Part of the Stable ABI.

tp_richcompare を参照してください。

typedef PyObject *(*getiterfunc)(PyObject*)

Part of the Stable ABI.

tp_iter を参照してください。

typedef PyObject *(*iternextfunc)(PyObject*)

Part of the Stable ABI.

tp_iternext を参照してください。

typedef Py_ssize_t (*lenfunc)(PyObject*)

Part of the Stable ABI.

typedef int (*getbufferproc)(PyObject*, Py_buffer*, int)

Part of the Stable ABI since version 3.12.

typedef void (*releasebufferproc)(PyObject*, Py_buffer*)

Part of the Stable ABI since version 3.12.

typedef PyObject *(*unaryfunc)(PyObject*)

Part of the Stable ABI.

typedef PyObject *(*binaryfunc)(PyObject*, PyObject*)

Part of the Stable ABI.

typedef PySendResult (*sendfunc)(PyObject*, PyObject*, PyObject**)

am_send を参照してください。

typedef PyObject *(*ternaryfunc)(PyObject*, PyObject*, PyObject*)

Part of the Stable ABI.

typedef PyObject *(*ssizeargfunc)(PyObject*, Py_ssize_t)

Part of the Stable ABI.

typedef int (*ssizeobjargproc)(PyObject*, Py_ssize_t, PyObject*)

Part of the Stable ABI.

typedef int (*objobjproc)(PyObject*, PyObject*)

Part of the Stable ABI.

typedef int (*objobjargproc)(PyObject*, PyObject*, PyObject*)

Part of the Stable ABI.

使用例

ここでは Python の型定義の簡単な例をいくつか挙げます。これらの例にはあなたが遭遇する共通的な利用例を含んでいます。いくつかの例ではトリッキーなコーナーケースを実演しています。より多くの例や実践的な情報、チュートリアルが必要なら、拡張の型の定義: チュートリアル や Defining Extension Types: Assorted Topics を参照してください。

A basic static type:

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,
};

より冗長な初期化子を用いた古いコードを（特にCPythonのコードベース中で）見かけることがあるかもしれません:

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 */
};

弱参照やインスタンス辞書、ハッシュをサポートする型:

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,
};

A str subclass that cannot be subclassed and cannot be called to create instances (e.g. uses a separate factory func) using Py_TPFLAGS_DISALLOW_INSTANTIATION flag:

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,
};

The simplest static type with fixed-length instances:

typedef struct {
    PyObject_HEAD
} MyObject;

static PyTypeObject MyObject_Type = {
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "mymod.MyObject",
};

The simplest static type with variable-length instances:

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 *),
};

循環参照ガベージコレクションをサポートする

Python が循環参照を含むガベージの検出とコレクションをサポートするには、他のオブジェクトに対する "コンテナ" (他のオブジェクトには他のコンテナも含みます) となるオブジェクト型によるサポートが必要です。他のオブジェクトに対する参照を記憶しないオブジェクトや、(数値や文字列のような) アトム型 (atomic type) への参照だけを記憶するような型では、ガベージコレクションに際して特別これといったサポートを提供する必要はありません。

To create a container type, the tp_flags field of the type object must include the Py_TPFLAGS_HAVE_GC and provide an implementation of the tp_traverse handler. If instances of the type are mutable, a tp_clear implementation must also be provided.

Py_TPFLAGS_HAVE_GC

このフラグをセットした型のオブジェクトは、この節に述べた規則に適合しなければなりません。簡単のため、このフラグをセットした型のオブジェクトをコンテナオブジェクトと呼びます。

コンテナ型のコンストラクタは以下の二つの規則に適合しなければなりません:

The memory for the object must be allocated using PyObject_GC_New or PyObject_GC_NewVar.

他のコンテナへの参照が入るかもしれないフィールドが全て初期化されたら、すぐに PyObject_GC_Track() を呼び出さなければなりません。

同様に、オブジェクトのメモリ解放関数も以下の二つの規則に適合しなければなりません:

他のコンテナを参照しているフィールドを無効化する前に、 PyObject_GC_UnTrack() を呼び出さなければなりません。

オブジェクトのメモリは PyObject_GC_Del() で解放しなければなりません。

警告

If a type adds the Py_TPFLAGS_HAVE_GC, then it must implement at least a tp_traverse handler or explicitly use one from its subclass or subclasses.

When calling PyType_Ready() or some of the APIs that indirectly call it like PyType_FromSpecWithBases() or PyType_FromSpec() the interpreter will automatically populate the tp_flags, tp_traverse and tp_clear fields if the type inherits from a class that implements the garbage collector protocol and the child class does not include the Py_TPFLAGS_HAVE_GC flag.

PyObject_GC_New(TYPE, typeobj)

Analogous to PyObject_New but for container objects with the Py_TPFLAGS_HAVE_GC flag set.

PyObject_GC_NewVar(TYPE, typeobj, size)

Analogous to PyObject_NewVar but for container objects with the Py_TPFLAGS_HAVE_GC flag set.

PyObject *PyUnstable_Object_GC_NewWithExtraData(PyTypeObject *type, size_t extra_size)

これは Unstable API. It may change without warning in minor releases.

Analogous to PyObject_GC_New but allocates extra_size bytes at the end of the object (at offset tp_basicsize). The allocated memory is initialized to zeros, except for the Python object header.

The extra data will be deallocated with the object, but otherwise it is not managed by Python.

警告

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 PyVarObject and tp_itemsize instead.

Added in version 3.12.

PyObject_GC_Resize(TYPE, op, newsize)

Resize an object allocated by PyObject_NewVar. Returns the resized object of type TYPE* (refers to any C type) or NULL on failure.

op must be of type PyVarObject* and must not be tracked by the collector yet. newsize must be of type Py_ssize_t.

void PyObject_GC_Track(PyObject *op)

Part of the Stable ABI.

オブジェクト op を、コレクタによって追跡されるオブジェクトの集合に追加します。コレクタは何回動くのかは予想できないので、追跡されている間はオブジェクトは正しい状態でいなければなりません。 tp_traverse の対象となる全てのフィールドが正しい状態になってすぐに、たいていはコンストラクタの末尾付近で、呼び出すべきです。

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.

int PyObject_GC_IsTracked(PyObject *op)

Part of the Stable ABI since version 3.9.

Returns 1 if the object type of op implements the GC protocol and op is being currently tracked by the garbage collector and 0 otherwise.

This is analogous to the Python function gc.is_tracked().

Added in version 3.9.

int PyObject_GC_IsFinalized(PyObject *op)

Part of the Stable ABI since version 3.9.

Returns 1 if the object type of op implements the GC protocol and op has been already finalized by the garbage collector and 0 otherwise.

This is analogous to the Python function gc.is_finalized().

Added in version 3.9.

void PyObject_GC_Del(void *op)

Part of the Stable ABI.

Releases memory allocated to an object using PyObject_GC_New or PyObject_GC_NewVar.

void PyObject_GC_UnTrack(void *op)

Part of the Stable ABI.

オブジェクト op を、コレクタによって追跡されるオブジェクトの集合から除去します。このオブジェクトに対して PyObject_GC_Track() を再度呼び出して、追跡されるオブジェクトの集合に戻すことも可能です。 tp_traverse ハンドラの対象となるフィールドが正しくない状態になる前に、デアロケータ (tp_dealloc ハンドラ) はオブジェクトに対して、この関数を呼び出すべきです。

バージョン 3.8 で変更: The _PyObject_GC_TRACK() and _PyObject_GC_UNTRACK() macros have been removed from the public C API.

tp_traverse ハンドラはこの型の関数パラメータを受け取ります:

typedef int (*visitproc)(PyObject *object, void *arg)

Part of the Stable ABI.

tp_traverse ハンドラに渡されるビジター関数 (visitor function) の型です。この関数は、探索するオブジェクトを object として、 tp_traverse ハンドラの第 3 引数を arg として呼び出します。 Python のコアはいくつかのビジター関数を使って、ゴミとなった循環参照を検出する仕組みを実装します; ユーザが自身のためにビジター関数を書く必要が出てくることはないでしょう。

tp_traverse ハンドラは次の型を持っていなければなりません:

typedef int (*traverseproc)(PyObject *self, visitproc visit, void *arg)

Part of the Stable ABI.

コンテナオブジェクトのためのトラバーサル関数 (traversal function) です。実装では、self に直接入っている各オブジェクトに対して visit 関数を呼び出さなければなりません。このとき、visit へのパラメタはコンテナに入っている各オブジェクトと、このハンドラに渡された arg の値です。 visit 関数は NULL オブジェクトを引数に渡して呼び出してはなりません。 visit が非ゼロの値を返す場合、エラーが発生し、戻り値をそのまま返すようにしなければなりません。

tp_traverse ハンドラを簡潔に書くために、 Py_VISIT() マクロが提供されています。このマクロを使うためには、 tp_traverse の実装関数の引数は、一文字も違わず visit と arg でなければなりません:

void Py_VISIT(PyObject *o)

o が NULL でなければ、 o と arg を引数にして visit コールバックを呼び出します。 visit がゼロでない値を返した場合、その値を返します。このマクロを使うと、 tp_traverse ハンドラは次のようになります:

static int
my_traverse(Noddy *self, visitproc visit, void *arg)
{
    Py_VISIT(self->foo);
    Py_VISIT(self->bar);
    return 0;
}

tp_clear ハンドラは inquiry 型であるか、オブジェクトが不変 (immutable) な場合は NULL でなければなりません。

typedef int (*inquiry)(PyObject *self)

Part of the Stable ABI.

循環参照を形成しているとおぼしき参照群を放棄します。変更不可能なオブジェクトは循環参照を直接形成することが決してないので、この関数を定義する必要はありません。このメソッドを呼び出した後でもオブジェクトは有効なままでなければならないので注意してください (参照に対して Py_DECREF() を呼ぶだけにしないでください)。ガベージコレクタは、オブジェクトが循環参照を形成していることを検出した際にこのメソッドを呼び出します。

Controlling the Garbage Collector State

The C-API provides the following functions for controlling garbage collection runs.

Py_ssize_t PyGC_Collect(void)

Part of the Stable ABI.

Perform a full garbage collection, if the garbage collector is enabled. (Note that 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 0 immediately. Errors during garbage collection are passed to sys.unraisablehook. This function does not raise exceptions.

int PyGC_Enable(void)

Part of the Stable ABI since version 3.10.

Enable the garbage collector: similar to gc.enable(). Returns the previous state, 0 for disabled and 1 for enabled.

Added in version 3.10.

int PyGC_Disable(void)

Part of the Stable ABI since version 3.10.

Disable the garbage collector: similar to gc.disable(). Returns the previous state, 0 for disabled and 1 for enabled.

Added in version 3.10.

int PyGC_IsEnabled(void)

Part of the Stable ABI since version 3.10.

Query the state of the garbage collector: similar to gc.isenabled(). Returns the current state, 0 for disabled and 1 for enabled.

Added in version 3.10.

Querying Garbage Collector State

The C-API provides the following interface for querying information about the garbage collector.

void PyUnstable_GC_VisitObjects(gcvisitobjects_t callback, void *arg)

これは Unstable API. It may change without warning in minor releases.

Run supplied callback on all live GC-capable objects. arg is passed through to all invocations of callback.

警告

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.

Added in version 3.12.

typedef int (*gcvisitobjects_t)(PyObject *object, void *arg)

Type of the visitor function to be passed to PyUnstable_GC_VisitObjects(). arg is the same as the arg passed to PyUnstable_GC_VisitObjects. Return 0 to continue iteration, return 1 to stop iteration. Other return values are reserved for now so behavior on returning anything else is undefined.

Added in version 3.12.

API と ABI のバージョニング

CPython は以下のマクロでバージョン番号を公開しています。これらはコードが ビルドされた バージョンに対応しており、必ずしも 実行時 に使われるバージョンではないことに注意してください。

バージョン間の API と ABI の安定性については C API の安定性 を参照してください。

PY_MAJOR_VERSION

3.4.1a2 の 3 。

PY_MINOR_VERSION

3.4.1a2 の 4 。

PY_MICRO_VERSION

3.4.1a2 の 1 。

PY_RELEASE_LEVEL

3.4.1a2 の a 。アルファでは 0xA 、ベータでは 0xB 、リリース候補では 0xC 、最終版では 0xF となります。

PY_RELEASE_SERIAL

3.4.1a2 の 2 。最終リリースでは 0 になります。

PY_VERSION_HEX

Python のバージョン番号を単一の整数に符号化したものです。

下記のように32ビットの値として扱うことで、バージョン情報を得ることができます:

bytes

ビット (ビッグエンディアンオーダ)

意味

3.4.1a2 の値

1

1-8

PY_MAJOR_VERSION

0x03

2

9-16

PY_MINOR_VERSION

0x04

3

17-24

PY_MICRO_VERSION

0x01

4

25-28

PY_RELEASE_LEVEL

0xA

29-32

PY_RELEASE_SERIAL

0x2

したがって、 3.4.1a2 は16進数で 0x030401a2 であり、 3.10.0 は16進数で 0x030a00f0 です。

これを数値比較に使用します。例えば、 #if PY_VERSION_HEX >= ... 。

このバージョンはシンボル Py_Version からも入手できます。

const unsigned long Py_Version

Part of the Stable ABI since version 3.11.

PY_VERSION_HEX マクロと同じ書式で、単一の定数整数でエンコードされた Python の実行時のバージョン番号です。これは実行時に使用される Python のバージョンを含んでいます。

Added in version 3.11.

これらのマクロは Include/patchlevel.h [https://github.com/python/cpython/tree/3.12/Include/patchlevel.h] で定義されています。

Python モジュールのインストール

Email:

distutils-sig@python.org

人気のあるオープンソース開発プロジェクトがそうであるように、Python には貢献者たちとユーザたちの活発なサポートコミュニティがあり、またこれらはほかの Python 開発者たちに、彼らのソフトウェアのオープンソースライセンスのもとでの利用も可能にしてくれています。

これはほかの人が既に挙げた共通の(あるいは時折極めて稀有な!)問題や、彼ら自身の解法による潜在的な貢献が共通の場所に蓄えられることによる恩恵によって、Python ユーザに共有と協調を効果的に行なうことの助けとなっています。

This guide covers the installation part of the process. For a guide to creating and sharing your own Python projects, refer to the Python packaging user guide [https://packaging.python.org/en/latest/tutorials/packaging-projects/].

注釈

あなたが企業や組織のユーザであれば、多くの組織がオープンソースソフトウェアの利用と貢献に関する彼ら独自のポリシーを持っていることに気をつけてください。Python によって提供される配布とインストールのツールを利用する際には、そのようなポリシーを考慮に入れてください。

重要用語集

pip は推奨されるインストーラ・プログラムです。 Python 3.4 からは、 Python バイナリ・インストーラに最初から付属するようになりました。

仮想環境 は、システム全体にインストールするのではなく、特定のアプリケーションで使用するためにパッケージをインストールできるようにする半独立型のPython環境です。

venv は仮想環境をつくるための標準ツールです。 Python 3.3 から Python の一部になりました。 Python 3.4 以降では、仮想環境をつくる際はそのすべてで pip をインストールするように、あらかじめ設定されています。

virtualenv は venv のサードパーティの代替案 (で前身) です。 virtualenv により仮想環境を Python 3.4 より前のバージョンで使うことが出来ます。以前のバージョンは venv を提供していませんし、作成された環境に pip を自動的にインストールすることも出来ません。

Python Package Index [https://pypi.org] は Python パッケージのパブリック・リポジトリです。このリポジトリのパッケージは、他の Python ユーザが利用できるように、オープンソースでライセンスされています。

the Python Packaging Authority [https://www.pypa.io/] is the group of developers and documentation authors responsible for the maintenance and evolution of the standard packaging tools and the associated metadata and file format standards. They maintain a variety of tools, documentation, and issue trackers on GitHub [https://github.com/pypa].

distutils はオリジナルのビルド・配布システムで、 Python 標準ライブラリに 1998 年に最初に追加されました。 distutils の直接的な利用は段階的に取り払われていきますが、それは今でも現時点でのパッケージングと配布のインフラストラクチャの基礎として鎮座していて、標準ライブラリの一部として残っているだけでなく、その名前はほかの文脈でも生き続けています(Python のパッケージング標準の開発をまとめるのに使われているメーリングリストの名前のように)。

バージョン 3.5 で変更: 仮想環境の作成には、 venv の使用をお勧めします。

参考

Python Packaging User Guide: Creating and using virtual environments [https://packaging.python.org/installing/#creating-virtual-environments]

基本的な使い方

パッケージングのための標準ツールはすべてコマンドラインから使われることを想定しています。

以下のコマンドは、モジュールの最新バージョンとそれが依存するモジュールを、 Python Package Index からインストールします。

python -m pip install SomePackage

注釈

POSIX ユーザ(macOS と Linux ユーザを含みます)向けには、このガイド内の例は、 virtual environment の利用を前提にしています。

Windows ユーザ向けには、このガイド内の例は、Python インストール時にシステムの PATH 環境変数が調整されていることを前提にしています。

正確なバージョンや最小のバージョンをコマンドライン上で直接指定することもできます。> や < などの比較演算子など、シェルが解釈する特殊文字を使う場合、パッケージ名とバージョンを二重引用符で囲んでください:

python -m pip install SomePackage==1.0.4    # specific version
python -m pip install "SomePackage>=1.0.4"  # minimum version

通常、適合するモジュールがインストール済である場合にそれを再度 install 実行を試みても効果はありません。既に存在しているモジュールのアップグレードには、明示的にそれを要求しなければなりません:

python -m pip install --upgrade SomePackage

pip とその機能についての詳しい情報とリソースは Python Packaging User Guide [https://packaging.python.org] にあります。

仮想環境の作成は venv モジュールを通して行われます。有効な仮想環境にインストールするには 上記のコマンドを使います。

参考

Python Packaging User Guide: Installing Python Distribution Packages [https://packaging.python.org/installing/]

どうすればいいの...？

以下はよくある課題への簡単な回答もしくは回答へのリンクです。

... pip を 3.4 より前のバージョンの Python でインストールするには？

pip が Python に付属するのは 3.4 以降です。それ以前のバージョンでは、 "Python Packaging User Guide" の記載にしたがって pip 自体をインストールする必要があります。

参考

Python Packaging User Guide: Requirements for Installing Packages [https://packaging.python.org/installing/#requirements-for-installing-packages]

... パッケージを現在のユーザ用のみにインストールするには？

python -m pip install に --user オプションを付けてください。パッケージはシステムのすべてのユーザ用にではなく、現在のユーザ用のみにインストールされます。

... 科学技術計算用の Python パッケージをインストールするには？

科学技術計算用の Python パッケージの多くがバイナリモジュールに複雑に依存しており、現在のところ pip を直接使ってインストールすることは容易ではありません。現時点では pip を使ってインストールしようとするよりも、 別の手段 [https://packaging.python.org/science/] を用いてインストールするほうが、多くの場合簡単でしょう。

参考

Python Packaging User Guide: Installing Scientific Packages [https://packaging.python.org/science/]

... インストールされた複数のバージョンの Python を並行して使うには？

Linux や macOS、その他の POSIX システムでは、バージョン番号付きの Python コマンドと -m スイッチを組み合わせて用いて、適切なバージョンの pip を実行してください。

python2   -m pip install SomePackage  # default Python 2
python2.7 -m pip install SomePackage  # specifically Python 2.7
python3   -m pip install SomePackage  # default Python 3
python3.4 -m pip install SomePackage  # specifically Python 3.4

適切にバージョン番号が付された pip コマンドが使えることもあります。

Windows では、 Python ランチャーの py を -m スイッチとの組み合わせで使ってください。

py -2   -m pip install SomePackage  # default Python 2
py -2.7 -m pip install SomePackage  # specifically Python 2.7
py -3   -m pip install SomePackage  # default Python 3
py -3.4 -m pip install SomePackage  # specifically Python 3.4

よくあるインストールに関する問題

Linux で、システムの Python 内にインストールする

Linux システムでは、 Python のインストールは典型的には linux ディストリビューションの一部に含まれています。この Python インストールへのインストールには、システムに対する root 権限が必要で、また、 pip によって期待されているものとは異なるコンポーネントにアップグレードすることで、システムのパッケージマネージャのオペレーションやシステムのほかのコンポーネントの邪魔をするかもしれません。

そのようなシステムでは、 pip でパッケージをインストールする際には仮想環境を使うか、ユーザごとのインストールを行うのが、大抵良い方法です。

pip がインストールされていない

pip がデフォルトでインストールされていないことがあります。次のコマンドで問題の解決が見込めます:

python -m ensurepip --default-pip

他にも pip のインストール [https://packaging.python.org/en/latest/tutorials/installing-packages/#ensure-pip-setuptools-and-wheel-are-up-to-date] についての資料があります。

バイナリの拡張のインストール

Python プロジェクトの多くはソースに基いた配布に強く依存しており、インストールプロセスの一環として、エンドユーザ環境でソースから拡張モジュールをコンパイルすることを期待します。

バイナリ wheel フォーマットのサポートが導入されたことで、また、少なくとも Windows と macOS についての wheels の公開が Python Package Index を通して出来るようになったことで、この問題についての開発者の時間の節約と、ユーザにとっては自身でビルドせずにビルド済み拡張をインストールするさらなる標準化に繋がるかもしれません。

ビルド済み wheel ファイルが未だ入手出来ない scientific software [https://packaging.python.org/science/] インストールにおけるいくつかの解法が、ローカルにビルドすることなく他のバイナリ拡張を得る助けになるかもしれません。

参考

Python Packaging User Guide: Binary Extensions [https://packaging.python.org/extensions/]

Python HOWTO

Python HOWTO は、それぞれが単独の話題を取り扱って自己完結した文書群です。Linux Documentation Project の HOWTO 書庫をモデルに、Python ライブラリリファレンスよりも詳細な文書を作っていこうという努力の成果なのです。

今のところ揃っている HOWTO はこちらです:

Python 3 への拡張モジュール移植

Python で Curses プログラミング

デスクリプタ ガイド

Debugging C API extensions and CPython Internals with GDB

列挙型 HOWTO

関数型プログラミング HOWTO

Logging HOWTO

Logging クックブック

正規表現 HOWTO

ソケットプログラミング HOWTO

Sorting Techniques

Unicode HOWTO

urllib パッケージを使ってインターネット上のリソースを取得するには

Argparse チュートリアル

ipaddressモジュールの紹介

DTrace と SystemTap で CPython を測定する

Python support for the Linux perf profiler

Annotations Best Practices

拡張モジュールを分離する

The Python 2.3 Method Resolution Order

Python 3 への拡張モジュール移植

Python 3 への拡張モジュール移植には、以下のリソースを推奨します:

Supporting Python 3: An in-depth guide の Migrating C extensions [http://python3porting.com/cextensions.html] 章。本は Python 2 から Python 3 への移行全般を扱い、拡張モジュールの移植を読者にガイドします。

Porting guide [https://py3c.readthedocs.io/en/latest/guide.html] は py3c プロジェクトにより提供される、補助コード付きの見解提案です。

Cython [https://cython.org/] と CFFI [https://cffi.readthedocs.io/en/latest/] のライブラリは Python の C API 抽象化を提案します。拡張はたいてい使用時に書き換えが求められますが、これらのライブラリは Python のバージョンや実装にまたがる違いを処理します。

Python で Curses プログラミング

著者:

A.M. Kuchling, Eric S. Raymond

リリース:

2.04

概要

このドキュメントでは curses 拡張モジュールでテキストモードディスプレイを制御する方法について記述します。

curses ってなに?

curses ライブラリは、VT100s や Linux コンソール、さまざまなプログラムが提供するエミュレーション端末といったテキストベースの端末（ターミナル）のために、端末に依存しないスクリーン描画や、キーボードの処理を提供します。端末はカーソルの移動や、画面のスクロール、領域の消去といった共通の操作を行うための様々な制御コードをサポートします。端末の種類によって大きく異なる制御コードを使うことがあり、しばしば独特の癖があります。

グラフィカルなディスプレイが当たり前の今となっては、「なんでわざわざ？」と疑問に思うかもしれません。確かに文字表示端末は時代遅れな技術ではありますが、ニッチな領域が存在していて、意匠を凝らすことができるため、いまだに価値のあるものとなっています。そのような領域の一つは、例えば X サーバーを持たない組み込みのUnixです。ほかにも、OSのインストーラや、カーネル設定などのツールで、これらはグラフィカルサポートが利用可能になる前に動作する必要があります。

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 [https://pypi.org/project/Urwid/].

curses ライブラリは元々 BSD UNIX 向けに書かれました; 後の AT&T から出た Unix System V バージョンで多くの機能と新機能が追加されました。BSD curses はいまやメンテナンスされておらず、これは AT&T インターフェースのオープンソース実装である ncurses にとって置き換えられました。Linux や FreeBSD のようなオープンソース Unix を利用している場合は、おそらくシステムは ncurses を利用しています。現在のほとんどの商用 Unix は System V のコードを基にしているため、ここで述べる全ての関数が利用できるはずです。しかし、古いバージョンの curses を持ついくつかのプロプライエタリ Unix は全てには対応していないでしょう。

The Windows version of Python doesn't include the curses module. A ported version called UniCurses [https://pypi.org/project/UniCurses/] is available.

Python の curses module

The Python module is a fairly simple wrapper over the C functions provided by curses; if you're already familiar with curses programming in C, it's really easy to transfer that knowledge to Python. The biggest difference is that the Python interface makes things simpler by merging different C functions such as addstr(), mvaddstr(), and mvwaddstr() into a single addstr() method. You'll see this covered in more detail later.

この HOWTO は curses と Python を使ってテキストプログラムを書くための入門記事です。 curses API に対する完全な解説をすることは意図していません; その目的のためには Python ライブラリガイドの ncurses 節と C 言語マニュアルのncurses のページを参照してください。とはいえ、この文章は基本的な考えを提供してくれるでしょう。

curses アプリケーションの起動と終了

Before doing anything, curses must be initialized. This is done by calling the initscr() function, which will determine the terminal type, send any required setup codes to the terminal, and create various internal data structures. If successful, initscr() returns a window object representing the entire screen; this is usually called stdscr after the name of the corresponding C variable.

import curses
stdscr = curses.initscr()

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 noecho() function.

curses.noecho()

通常アプリケーションはまた、Enter キーを押すことなく、キーに対してすぐに反応する必要があります; これは cbreak モードと呼ばれ、通常の入力がバッファされるモードと逆に動作します。

curses.cbreak()

端末は通常、カーソルキーや Page Up や Home といった操作キーなどの特別なキーをマルチバイトエスケープシーケンスとして返します。それらのシーケンスを想定して対応する処理を行うアプリケーションを書けるように、 curses はそれを curses.KEY_LEFT のような特別な値を返して行ってくれます。 curses にその仕事をさせるには、キーパッドモードを有効にする必要があります。

stdscr.keypad(True)

curses アプリケーションを終了させるのは起動よりも簡単です。 以下を呼び出す必要があります:

curses.nocbreak()
stdscr.keypad(False)
curses.echo()

cursesに親和性の高い設定をもとに戻します。そして、endwin() 関数を呼び出し、端末を通常の操作モードに復旧します。

curses.endwin()

curses アプリケーションをデバッグするときの一般的な問題は、アプリケーションが端末を以前の状態に復旧することなく異常終了したときに端末がめちゃめちゃになることです。Python ではこの問題はコードにバグがあって、捕捉できない例外が発生したときによく起きます。タイプしたキーはもはやエコーされません、例えば、シェルを使うのが難しくなります。

Pythonでは、これらの複雑さを避けデバッグをより容易にするために、 curses.wrapper() 関数をインポートして、このように使います:

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)

The wrapper() function takes a callable object and does the initializations described above, also initializing colors if color support is present. wrapper() then runs your provided callable. Once the callable returns, wrapper() will restore the original state of the terminal. The callable is called inside a try...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.

ウィンドウとパッド

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 stdscr object returned by the 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 newwin() function creates a new window of a given size, returning the new window object.

begin_x = 20; begin_y = 7
height = 5; width = 40
win = curses.newwin(height, width, begin_y, begin_x)

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 curses.LINES and curses.COLS variables to obtain the y and x sizes. Legal coordinates will then extend from (0,0) to (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 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 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 stdscr.refresh() or the 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.

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)

The 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. refresh() actually does two things:

それぞれのウィンドウの noutrefresh() メソッドを呼び出して、配下にある、スクリーンの望ましい状態を表すデータ構造を更新します。

doupdate() 関数を呼び出して、データ構造に記録された望ましい状態に合致するように、物理スクリーンを更新します。

Instead you can call noutrefresh() on a number of windows to update the data structure, and then call doupdate() to update the screen.

テキストの表示

From a C programmer's point of view, curses may sometimes look like a twisty maze of functions, all subtly different. For example, addstr() displays a string at the current cursor location in the stdscr window, while mvaddstr() moves to a given y,x coordinate first before displaying the string. waddstr() is just like addstr(), but allows specifying a window to use instead of using stdscr by default. mvwaddstr() allows specifying both a window and a coordinate.

幸運にも、Python インターフェースはこれらの詳細を全て隠蔽してくれます。 stdscr は他のものと同様のウィンドウオブジェクトであり、 addstr() のようなメソッドは複数の引数形式を許容してくれます。通常それらは4つの形式です。

形式

説明

str または ch

文字列 str または文字 ch を現在位置に表示します

str または ch, attr

文字列 str または文字 ch を属性 attr を利用して現在位置に表示します

y, x, str または ch

ウィンドウ内の位置 y,x に移動し str または ch を表示します

y, x, str または ch, attr

ウィンドウ内の位置 y,x に移動し属性 attr を利用して str または ch を表示します

属性によって表示するテキストをハイライトすることができます、ボールド体、アンダーライン、反転、カラーなど。より詳しくは次の小節で説明します。

The 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 encoding attribute; this defaults to the default system encoding as returned by locale.getencoding().

The 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, ACS_PLMINUS is a +/- symbol, and ACS_ULCORNER is the upper left corner of a box (handy for drawing borders). You can also use the appropriate Unicode character.

ウィンドウは最後の操作の後のカーソル位置を覚えているため、 y,x 座標をうっかり忘れてしまっても、文字列や文字は最後の操作位置に表示されます。 move(y,x) メソッドでカーソルを移動させることもできます。常に点滅するカーソルを表示する端末もあるため、カーソルが特定の位置にいることを保証して注意が反れないようにしたいと思うかもしれません; ランダムに見える位置でカーソルが点滅すると面を食らってしまいます。

If your application doesn't need a blinking cursor at all, you can call curs_set(False) to make it invisible. For compatibility with older curses versions, there's a leaveok(bool) function that's a synonym for 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.

属性とカラー

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.

属性は整数値で、それぞれのビットが異なる属性を表わします。複数の属性ビットをセットしてテキストの表示を試みることができますが、curses は全ての組み合わせが利用可能であるかや視覚的に区別できるかどうかは保証してくれません、それらは利用している端末の能力に依存しているため、最も安全なのは、最も一般的に利用可能な属性を設定する方法です、ここに列挙します。

属性

説明

A_BLINK

テキストを点滅

A_BOLD

高輝度またはボールドテキスト

A_DIM

低輝度テキスト

A_REVERSE

反転テキスト

A_STANDOUT

利用できる最良のハイライトモード

A_UNDERLINE

下線付きテキスト

つまり、反転するステータスラインを画面の最上部に表示するには、コードをこうします:

stdscr.addstr(0, 0, "Current mode: Typing mode",
              curses.A_REVERSE)
stdscr.refresh()

curses ライブラリはカラー機能を提供している端末でのカラーもサポートしています。そんな端末の中で最も一般的なものは Linux コンソールで、color xterm もそれに続きます。

To use color, you must call the start_color() function soon after calling initscr(), to initialize the default color set (the curses.wrapper() function does this automatically). Once that's done, the 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 color_pair() function; this can be bitwise-OR'ed with other attributes such as A_REVERSE, but again, such combinations are not guaranteed to work on all terminals.

例として、テキスト行をカラーペア 1 を使って表示します:

stdscr.addstr("Pretty text", curses.color_pair(1))
stdscr.refresh()

As I said before, a color pair consists of a foreground and background color. The 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 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 curses module defines named constants for each of these colors: curses.COLOR_BLACK, curses.COLOR_RED, and so forth.

やってみましょう。カラー 1 を白背景に赤に変更してみましょう、こうして呼び出します:

curses.init_pair(1, curses.COLOR_RED, curses.COLOR_WHITE)

カラーペアを変更するときには、既に表示された任意のテキストが利用するカラーペアを新しい色に変更します。新しいテキストをこの色で使うこともできます:

stdscr.addstr(0,0, "RED ALERT!", curses.color_pair(1))

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 can_change_color(), which returns 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.

ユーザ入力

The C curses library offers only very simple input mechanisms. Python's curses module adds a basic text-input widget. (Other libraries such as Urwid [https://pypi.org/project/Urwid/] have more extensive collections of widgets.)

ウィンドウから入力を得るための2つのメソッドがあります。

getch() refreshes the screen and then waits for the user to hit a key, displaying the key if echo() has been called earlier. You can optionally specify a coordinate to which the cursor should be moved before pausing.

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 KEY_UP or ^G.

It's possible to not wait for the user using the nodelay() window method. After nodelay(True), getch() and getkey() for the window become non-blocking. To signal that no input is ready, getch() returns curses.ERR (a value of -1) and getkey() raises an exception. There's also a halfdelay() function, which can be used to (in effect) set a timer on each getch(); if no input becomes available within a specified delay (measured in tenths of a second), curses raises an exception.

The 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 curses.KEY_PPAGE, curses.KEY_HOME, or curses.KEY_LEFT. The main loop of your program may look something like this:

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

The 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, curses.ascii.ctrl() returns the control character corresponding to its argument.

There's also a method to retrieve an entire string, 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.

curses.echo()            # Enable echoing of characters

# Get a 15-character string, with the cursor on the top line
s = stdscr.getstr(0,0, 15)

The curses.textpad module supplies a text box that supports an Emacs-like set of keybindings. Various methods of the Textbox class support editing with input validation and gathering the edit results either with or without trailing spaces. Here's an 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()

さらなる詳細についてはライブラリのドキュメント curses.textpad を参照してください。

より多くの情報

この HOWTO ではいくつかの進んだ話題、スクリーンスクレイピングや xterm インスタンスからマウスイベントを捉えるなど、については扱っていません。しかし、Python の curses モジュールのライブラリページはいまやかなり充実しています。次はこれを見るべきです。

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 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 [https://devguide.python.org/] to learn more about submitting patches to Python.

Writing Programs with NCURSES [https://invisible-island.net/ncurses/ncurses-intro.html]: a lengthy tutorial for C programmers.

The ncurses man page [https://linux.die.net/man/3/ncurses]

The ncurses FAQ [https://invisible-island.net/ncurses/ncurses.faq.html]

"Use curses... don't swear" [https://www.youtube.com/watch?v=eN1eZtjLEnU]: curses または Urwid を使って端末を制御する PyCon 2013 講演ビデオです。

"Console Applications with Urwid" [https://pyvideo.org/video/1568/console-applications-with-urwid]: video of a PyCon CA 2012 talk demonstrating some applications written using Urwid.

デスクリプタ ガイド

著者:

Raymond Hettinger

問い合わせ先:

<python at rcn dot com>

目次

デスクリプタ ガイド

入門

シンプルな例: 定数を返すデスクリプタ

動的なルックアップ

管理された属性

名前のカスタマイズ

まとめ

実践的なサンプル

バリデータクラス

カスタムバリデータ

実践的なアプリケーション

技術的なチュートリアル

概要

定義と導入

デスクリプタプロトコル

デスクリプタ呼び出しの概要

インスタンスからの呼び出し

クラスからの呼び出し

superからの呼び出し

呼び出しロジックのまとめ

自動的の名前の伝達

ORMのサンプル

ピュアPythonの等価実装

プロパティ

関数とメソッド

メソッドの種類

静的メソッド

クラスメソッド

メンバーオブジェクトと __slots__

デスクリプタ を使うと、オブジェクトの属性検索、保存、削除をカスタマイズできます。

本ガイドは4つの大項目から構成されています。

最初の「入門」では基本の紹介をして、シンプルな例から少しずつ概念を説明していきます。もしデスクリプタに触れるのが初めての場合はここから学んでいきましょう。

2つ目のセクションでは完全で実践的なデスクリプタのサンプルを紹介します。もしデスクリプタの基本を理解しているのであれば、ここから読み始めても良いでしょう。

3番目のセクションはより技巧的なチュートリアルを通じて、デスクリプタがどのようなメカニズムで動作しているのかを紹介します。多くの人はこのレベルの理解は不要でしょう。

最後のセクションは、Cで書かれた組み込みのデスクリプタをピュアPythonで実現する方法を紹介します。このセクションがどのように関数が束縛メソッドになるのか、 classmethod() や staticmethod(), property(), __slots__ といった一般的なツールの実装がどのようになっているのか興味を持ったら読んでください。

入門

この入門では、なるべく基礎的なところから開始し、新しい要素を一つずつ紹介していきます。

シンプルな例: 定数を返すデスクリプタ

Ten クラスはデスクリプタで、その __get__() メソッドは常に定数の 10 を返します。

class Ten:
    def __get__(self, obj, objtype=None):
        return 10

このデスクリプタを使うには他のクラスのクラス変数として保存します:

class A:
    x = 5                       # Regular class attribute
    y = Ten()                   # Descriptor instance

インタラクティブセッションを使って、通常の属性ルックアップと、デスクリプタのルックアップの違いを見てみましょう。

>>> a = A()                     # Make an instance of class A
>>> a.x                         # Normal attribute lookup
5
>>> a.y                         # Descriptor lookup
10

a.x 属性ルックアップではドット演算子がクラス辞書の中から 'x': 5 を見つけます。 a.y ルックアップではドット演算子は __get__ メソッドを持つデスクリプタインスタンスを取得します。そのメソッドを呼び出すと、 10 を返します。

10 はクラスの辞書にも、インスタンスの辞書にも格納されていません。その代わり、 10 はオンデマンドに計算されます。

このサンプルは、シンプルなデスクリプタがどのように動作するかを説明するためのものですが、実用的ではありません。定数を返す場合、通常の属性アクセスの方が良いでしょう。

次のセクションでは、より実践的な動的なルックアップを作成します。

動的なルックアップ

単に定数を返すよりも、なにか処理を実行するデスクリプタの方が面白いでしょう。

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

インタラクティブセッションで見たように、この探索は動的です。実行ごとに異なる計算を行い、毎回答えが更新されます。

>>> 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

このサンプルはデスクリプタの中でどのように処理を行うかだけではなく、 __get__() の引数の目的も示しています。 self パラメータは size で、 DirectorySize のインスタンスです。 obj パラメータは g や s といった Directory のインスタンスです。 obj により、 __get__() はターゲットのディレクトリを知れます。 objtype パラメータは Directory クラスです。

管理された属性

デスクリプタで広く使われる用途がインスタンスのデータへのアクセスの管理です。このデスクリプタはクラス辞書のパブリックな属性に割り当てられますが、実際のデータはインスタンス辞書のプライベートな属性に保存します。パブリックなアクセスが行われると、デスクリプタの __get__() と __set__() メソッドが実行されます。

このサンプルでは age はパブリックな属性で、 _age はプライベートな属性です。パブリックな属性がアクセスされると、デスクリプタはルックアップや更新のログ出力をします。

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__()

インタラクティブセッションの結果で見てわかるように、管理された属性の age のログ出力が行われますが、通常の属性の name はログ出力されません。

>>> 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

このサンプル実装には大きな問題があります。プライベートな名前の _age が LoggedAgeAccess クラスの中でハードコードされています。そのため、どのインスタンスも1つしかこのログ出力される属性が作れず、名前を変更できません。次のサンプルでこの問題を解決していきます。

名前のカスタマイズ

クラスがデスクリプタを使うときに、クラスはそれぞれのデスクリプタにどのような変数名を使うかを通知します。

このサンプルでは Person クラスは、 name と age という2つのデスクリプタインスタンスを持っています。 Person が定義されると、 LoggedAccess の __set_name__() にコールバックを行うため、フィールド名を記録できます。それぞれのデスクリプタは、 public_name と private_name を持ちます。

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

インタラクティブセッション上で試すと、 Person クラスが __set_name__() を呼び出し、フィールド名が記録されることが分かるでしょう。 vars() を呼んで、デスクリプタを起動しないでデスクリプタを取得してみましょう。

>>> vars(vars(Person)['name'])
{'public_name': 'name', 'private_name': '_name'}
>>> vars(vars(Person)['age'])
{'public_name': 'age', 'private_name': '_age'}

新しいクラスは name と age の両方でログを出力します。

>>> 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

2つの Person のインスタンスは、プライベート名しか保持していません。

>>> vars(pete)
{'_name': 'Peter P', '_age': 10}
>>> vars(kate)
{'_name': 'Catherine C', '_age': 20}

まとめ

__get__() 、 __set__() 、あるいは __delete__() メソッドを定義したあらゆるオブジェクトが、我々が descriptor と呼ぶものです。

それに追加して、デスクリプタは __set_name__() メソッドを持つこともできます。このメソッドは、デスクリプタが設定されるクラス、あるいはアサインされたクラス変数を知る必要がある場合に利用されます。もし存在していれば、クラスがデスクリプタでなくても呼ばれます。

デスクリプタは属性のルックアップ中に、ドット演算子によって呼び出されます。 vars(some_class)[descriptor_name] という書き方によって間接的にデスクリプタがアクセスされると、デスクリプタを実行することなく、デスクリプタのインスタンスが返されます。

デスクリプタはクラス変数として利用したときにだけ動作します。インスタンスに設定しても効果はありません。

デスクリプタは、クラス変数として格納されているオブジェクトが属性ルックアップ中に発生することを制御できるように、フックを提供することが主なモチベーションとなっています。

伝統的には、呼び出し側のクラスが、ルックアップ中に発生することを制御してきましたが、デスクリプタはその関係を逆転させ、検索されているデータが問題に介入できるようにします。

デスクリプタは、Pythonのさまざまなところで利用されています。これにより、単なる関数は、インスタンスに束縛されたメソッドになります。 classmethod(), staticmethod(), property(), functools.cached_property() といったツールもすべて、デスクリプタとして実装されています。

実践的なサンプル

このサンプルでは、発見が極めて難しいデータ破損バグを特定するのに利用可能な、実践的でパワフルなツールを紹介します。

バリデータクラス

バリデータは管理された属性アクセスのためのデスクリプタです。データを格納する前に、新しい値が型が適合しているか、値の範囲制限に適合しているかを検証します。もし制限に合わなければ、例外を送出し、データが不正な状態になるのを防ぎます。

Validator クラスは abstract base class であり、属性管理デスクリプタでもあります。

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

カスタムバリデータを作成するには Validator を継承し、 validate() メソッドを作成して必要に応じてさまざまな制約の検証を行います。

カスタムバリデータ

ここでは3つの実践的なバリデーションのユーティリティのサンプルを紹介します。

OneOf は制限された候補の集合に含まれる値かどうかを検証します。

Number は値が int か float かどうかを検証します。オプションで、値が指定された最小値と最大値に含まれるかも検証します。

String は値が str かどうか検証します。オプションで、指定された最小、最大の長さの検証をします。ユーザー定義の 術語 [https://en.wikipedia.org/wiki/Predicate_(mathematical_logic)] 検証も行えます。

class OneOf(Validator):

    def __init__(self, *options):
        self.options = set(options)

    def validate(self, value):
        if value not in self.options:
            raise ValueError(f'Expected {value!r} to be one of {self.options!r}')

class Number(Validator):

    def __init__(self, minvalue=None, maxvalue=None):
        self.minvalue = minvalue
        self.maxvalue = maxvalue

    def validate(self, value):
        if not isinstance(value, (int, float)):
            raise TypeError(f'Expected {value!r} to be an int or float')
        if self.minvalue is not None and value < self.minvalue:
            raise ValueError(
                f'Expected {value!r} to be at least {self.minvalue!r}'
            )
        if self.maxvalue is not None and value > self.maxvalue:
            raise ValueError(
                f'Expected {value!r} to be no more than {self.maxvalue!r}'
            )

class String(Validator):

    def __init__(self, minsize=None, maxsize=None, predicate=None):
        self.minsize = minsize
        self.maxsize = maxsize
        self.predicate = predicate

    def validate(self, value):
        if not isinstance(value, str):
            raise TypeError(f'Expected {value!r} to be an str')
        if self.minsize is not None and len(value) < self.minsize:
            raise ValueError(
                f'Expected {value!r} to be no smaller than {self.minsize!r}'
            )
        if self.maxsize is not None and len(value) > self.maxsize:
            raise ValueError(
                f'Expected {value!r} to be no bigger than {self.maxsize!r}'
            )
        if self.predicate is not None and not self.predicate(value):
            raise ValueError(
                f'Expected {self.predicate} to be true for {value!r}'
            )

実践的なアプリケーション

次のコードは実際のクラスでデータバリデータを使う方法のサンプルです。

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

これらのデスクリプタは、不正インスタンスが作成されるのを防ぎます。

>>> 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

技術的なチュートリアル

これから先はデスクリプタのメカニズムや動作の詳細について、よりテクニカルなチュートリアルになります。

概要

デスクリプタの定義、プロトコルのサマリー、デスクリプタがどのように呼び出されるかの説明、ORマッパーがどのように動作するかのサンプルを提示します。

デスクリプタについて学ぶことにより、新しいツールセットが使えるようになるだけでなく、Python の仕組みについてのより深い理解が得られます。

定義と導入

一般に、デスクリプタは、デスクリプタプロトコルで定義されたメソッドを持つ属性値です。このメソッドは、 __get__(), __set__(), および __delete__() です。これらのメソッドのいずれかが、オブジェクトに定義されていれば、それは デスクリプタ と呼ばれます。

属性アクセスのデフォルトの振る舞いは、オブジェクトの辞書の属性の取得、設定、削除です。例えば a.x は、まず a.__dict__['x']、それから type(a).__dict__['x']、さらに type(a) のメソッド探索順序に従ったさらなる探索へと連鎖します。見つかった値が、デスクリプタメソッドのいずれかを定義しているオブジェクトなら、Python はそのデフォルトの振る舞いをオーバーライドし、代わりにデスクリプタメソッドを呼び出します。これがどの連鎖順位で行われるかは、どのデスクリプタメソッドが定義されているかに依ります。

デスクリプタは、強力な、多目的のプロトコルです。これはプロパティ、メソッド、静的メソッド、クラスメソッド、そして super() の背後にある機構です。Python のいたるところで使われています。デスクリプタは、基幹にある C コードを簡潔にし、毎日の Python プログラムに、柔軟な新しいツール群を提供します。

デスクリプタプロトコル

descr.__get__(self, obj, type=None)

descr.__set__(self, obj, value)

descr.__delete__(self, obj)

これで全てです。これらのメソッドのいずれかを定義すれば、オブジェクトはデスクリプタとみなされ、探索された際のデフォルトの振る舞いをオーバーライドできます。

あるオブジェクトが __set__() と __delete__() の両方を定義していたら、それはデータデスクリプタとみなされます。 __get__() だけを定義しているデスクリプタは、非データデスクリプタと呼ばれます (これらはよくメソッドに使われますが、他の使い方も出来ます)。

データデスクリプタと非データデスクリプタでは、オーバーライドがインスタンスの辞書のエントリに関してどのように計算されるかが異なります。インスタンスの辞書に、データデスクリプタと同名の項目があれば、データデスクリプタの方が優先されます。インスタンスの辞書に、非データデスクリプタと同名の項目があれば、辞書の項目の方が優先されます。

読み出し専用のデータデスクリプタを作るには、 __get__() と __set__() の両方を定義し、 __set__() が呼び出されたときに AttributeError が送出されるようにしてください。例外を送出する __set__() メソッドをプレースホルダとして定義すれば、データデスクリプタにするのに十分です。

デスクリプタ呼び出しの概要

desc.__get__(obj) や desc.__get__(None, cls) を使うとデスクリプタを直接呼び出すことができます。

しかし、属性アクセスの際に自動的に呼び出されるのが、一般的なデスクリプタの呼び出し方法です。

式 obj.x は obj の名前空間のチェーンの中で属性 x を探索します。もし、その検索のロジックの中で、インスタンスの __dict__ の外でデスクリプタを見つけた場合、探索ルールのリストのリストに従って、そのデスクリプタの __get__() メソッドが呼び出されます。

呼び出しの詳細は、obj がオブジェクトかクラスか、superのインスタンスかに依ります。

インスタンスからの呼び出し

名前空間のチェーンの中で行われるインスタンスルックアップでは、データデスクリプタが最優先で、次にインスタンス変数、その次にノンデータデスクリプタ、クラス変数、最後に存在したら __getattr__() が呼ばれます。

a.x に対するデスクリプタが見つかった場合、 desc.__get__(a, type(a)) という形式で呼び出されます。

ドットによるルックアップのロジックはobject.__getattribute__() の中で行われます。ピュアPythonで表した等価なロジックは次の通りです。

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)

__getattribute__() のコードには __getattr__() のフックが無いことに注意してください。このため、直接 __getattribute__() を呼び出すか、 super().__getattribute__ で呼び出すと、 __getattr__() が完全にバイパスされます。

その代わりに、 __getattribute__() が AttributeError を発出したときに __getattr__() を呼び出すのは、ドット演算子と getattr() の責任です。これらのロジックはヘルパー関数にカプセル化されています:

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__

クラスからの呼び出し

A.x のようなドットを使ったルックアップのロジックは type.__getattribute__() の中にあります。ロジックのステップは object.__getattribute__() と似ていますが、インスタンス辞書のルックアップはクラスの method resolution order を通じた探索と置き換えられています。

a.x に対するデスクリプタが見つかった場合、 desc.__get__(None, A) という形式で呼び出されます。

完全な C での実装は Objects/typeobject.c [https://github.com/python/cpython/tree/3.12/Objects/typeobject.c] の中の:c:func:!type_getattro と _PyType_Lookup() を参照してください。

superからの呼び出し

superのドットを使ったルックアップは super() が返すオブジェクトの __getattribute__() メソッドの中で行われます。

super(A, obj).m のようなドットを使ったルックアップは obj.__class__.__mro__ を探索して、 A の直前のクラス B をまず探し、 B.__dict__['m'].__get__(obj, A) を返します。もしデスクリプタでなければ m を変更せずに返します。

完全な C での実装は Objects/typeobject.c [https://github.com/python/cpython/tree/3.12/Objects/typeobject.c] の中の super_getattro() を参照してください。純粋な Python での同等なコードは `Guido's Tutorial <https://www.python.org/download/releases/2.2.3/descrintro/#cooperation>`_を参照してください。

呼び出しロジックのまとめ

デスクリプタのメカニズムは、 object 、 type 、 super() の __getattribute__() メソッドの中に組み込まれています。

憶えておくべき重要な点は:

デスクリプタは __getattribute__() メソッドによって呼び出される

クラスはこの機構を object 、 type 、 super() から継承する

すべてのデスクリプタのロジックが __getattribute__() にあるため、このメソッドをオーバーライドすると、すべての自動的なデスクリプタ呼び出しは抑制される

object.__getattribute__() と type.__getattribute__() は __get__() の呼び出し方が異なる。前者はインスタンスとおそらくメソッドを含む。後者はインスタンスとして None を渡し、クラスは常に渡される

データデスクリプタは、必ずインスタンス辞書をオーバーライドする

非データデスクリプタは、インスタンス辞書にオーバーライドされることがある

自動的の名前の伝達

デスクリプタにとって、自分がアサインされるクラス変数名が知りたいことがあります。新しいクラスが作られると、 type メタクラスは新しいクラスの辞書をスキャンします。もし、要素がデスクリプタで、なおかつ __set_name__() メソッドを持っている場合、このメソッドは2つの引数を伴って呼び出されます。 owner はデスクリプタが使用されたクラスで、 name はデスクリプタがアサインされたクラス変数の名前です。

実装の詳細は Objects/typeobject.c [https://github.com/python/cpython/tree/3.12/Objects/typeobject.c] の中の type_new() と set_names() を参照してください。

更新のロジックは type.__new__() にあり、通知はクラス作成のタイミングにしかありません。もしデスクリプタが後からクラスに追加された場合は、 __set_name__() を手動で呼び出す必要があるでしょう。

ORMのサンプル

以下のコードは、 オブジェクト関係マッピング [https://en.wikipedia.org/wiki/Object%E2%80%93relational_mapping] を実装するのにデータディスクリプタを使う方法を示した、簡略化された骨格です。

基本的な考え方は、データが外部のデータベースに保存することです。 Pythonインスタンスは、データベースのテーブルへのキーのみを保持します。デスクリプタがルックアップや更新をします。

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()

Field クラスを使って、データベースのテーブルごとのスキーマを説明するための モデル [https://ja.wikipedia.org/wiki/%E3%83%87%E3%83%BC%E3%82%BF%E3%83%A2%E3%83%87%E3%83%AB] を定義します。

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

モデルを使用するにはまずデータベースに接続します:

>>> import sqlite3
>>> conn = sqlite3.connect('entertainment.db')

次のインタラクティブセッションでは、データベースからのデータの取得と、更新方法を示しています。

>>> 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'

ピュアPythonの等価実装

このプロトコルは単純ですが、ワクワクする可能性も秘めています。ユースケースの中には、あまりに一般的なので組み込みに追加されたものもあります。プロパティ、束縛のメソッド、静的メソッド、クラスメソッド、 __slots__ は、全てデスクリプタプロトコルに基づいています。

プロパティ

property() を呼び出すことで、属性へアクセスすると関数の呼び出しを引き起こす、データデスクリプタを簡潔に組み立てられます。シグネチャはこうです:

property(fget=None, fset=None, fdel=None, doc=None) -> property

このドキュメントでは、管理された属性 x を定義する典型的な使用法を示します:

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.")

デスクリプタの見地から property() がどのように実装されているかを見るために、等価な Python 版をここに挙げます:

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
        self._name = ''

    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(
                f'property {self._name!r} of {type(obj).__name__!r} object has no getter'
             )
        return self.fget(obj)

    def __set__(self, obj, value):
        if self.fset is None:
            raise AttributeError(
                f'property {self._name!r} of {type(obj).__name__!r} object has no setter'
             )
        self.fset(obj, value)

    def __delete__(self, obj):
        if self.fdel is None:
            raise AttributeError(
                f'property {self._name!r} of {type(obj).__name__!r} object has no deleter'
             )
        self.fdel(obj)

    def getter(self, fget):
        prop = type(self)(fget, self.fset, self.fdel, self.__doc__)
        prop._name = self._name
        return prop

    def setter(self, fset):
        prop = type(self)(self.fget, fset, self.fdel, self.__doc__)
        prop._name = self._name
        return prop

    def deleter(self, fdel):
        prop = type(self)(self.fget, self.fset, fdel, self.__doc__)
        prop._name = self._name
        return prop

組み込みの property() 関数は、ユーザインターフェースへの属性アクセスが与えられ、続く変更がメソッドの介入を要求するときに役立ちます。

例えば、スプレッドシートクラスが、Cell('b10').value でセルの値を取得できるとします。続く改良により、プログラムがアクセスの度にセルの再計算をすることを要求しました。しかしプログラマは、その属性に直接アクセスする既存のクライアントコードに影響を与えたくありません。この解決策は、property データデスクリプタ内に値属性へのアクセスをラップすることです:

class Cell:
    ...

    @property
    def value(self):
        "Recalculate the cell before returning value"
        self.recalc()
        return self._value

組み込みの property() も、この Property() も、このサンプルの中で同じように利用できます。

関数とメソッド

Python のオブジェクト指向機能は、関数に基づく環境の上に構築されています。非データデスクリプタを使って、この 2 つはシームレスに組み合わされています。

クラス辞書に格納された関数は、実行時にメソッドに変換されます。メソッドと通常の関数はオブジェクトのインスタンスが他の引数よりも前に渡される点だけが異なります。監修ではインスタンスは self という名前が使われますが、 this や他の変数名も使えます。

メソッドは、ほぼ次のコードと同等な types.MethodType を使えば手動で作れます。

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)

メソッドの自動作成をサポートするには、関数に対し、属性アクセスでメソッドの束縛に利用される __get__() メソッドを追加します。これはつまり、この関数はドットアクセスされたときに束縛されたメソッドを返す非データデスクリプタであることを意味します。次のように動作します。

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)

次のクラスをインタプリタを起動すると、この関数デスクリプタが実際にどう働くかを見られます:

class D:
    def f(self, x):
         return x

この関数はイントロスペクションをサポートするために qualified name も持っています。

>>> D.f.__qualname__
'D.f'

クラス辞書を通じて関数にアクセスすると __get__() が実行されません。そのため、裏にある関数オブジェクトをそのまま返します。

>>> D.__dict__['f']
<function D.f at 0x00C45070>

クラスのドットアクセスは __get__() は呼び出しますが、これも裏にある関数を変更せずに返します。

>>> D.f
<function D.f at 0x00C45070>

インスタンスに対してドットアクセスをすると面白い動作をします。ドットのルックアップは、束縛メソッドオブジェクトを返す __get__() を呼び出します。

>>> d = D()
>>> d.f
<bound method D.f of <__main__.D object at 0x00B18C90>>

内部では、束縛メソッドはオリジナルの関数と束縛されたインスタンスを保持しています。

>>> d.f.__func__
<function D.f at 0x00C45070>

>>> d.f.__self__
<__main__.D object at 0x00B18C90>

もし、通常のメソッドの self や、クラスメソッドの cls がどこから来るの疑問に思っている人がいるとしたら、これがその答えになります！

メソッドの種類

非データデスクリプタは、関数をメソッドに束縛する、各種の一般的なパターンに、単純な機構を提供します。

まとめると、関数は __get__() メソッドを持ち、属性としてアクセスされたとき、メソッドに変換されます。この非データディスクリプタは、 obj.f(*args) の呼び出しを f(obj, *args) に変換します。 cls.f(*args) を呼び出すと f(*args) になります。

このチャートは、束縛と、その 2 つの異なる便利な形をまとめています:

変換

オブジェクトから呼び出される

クラスから呼び出される

関数

f(obj, *args)

f(*args)

静的メソッド

f(*args)

f(*args)

クラスメソッド

f(type(obj), *args)

f(cls, *args)

静的メソッド

静的メソッドは、下にある関数をそのまま返します。 c.f や C.f は、 object.__getattribute__(c, "f") や object.__getattribute__(C, "f") を直接探索するのと同じです。結果として、関数はオブジェクトとクラスから同じようにアクセスできます。

静的メソッドにすると良いのは、 self 変数への参照を持たないメソッドです。

例えば、統計パッケージに、実験データのコンテナがあるとします。そのクラスは、平均、メジアン、その他の、データに依る記述統計を計算する標準メソッドを提供します。しかし、概念上は関係があっても、データには依らないような便利な関数もあります。例えば、 erf(x) は統計上の便利な変換ルーチンですが、特定のデータセットに直接には依存しません。これは、オブジェクトからでもクラスからでも呼び出せます: s.erf(1.5) --> .9332 または Sample.erf(1.5) --> .9332 。

静的メソッドは下にある関数をそのまま返すので、呼び出しの例は面白くありません:

class E:
    @staticmethod
    def f(x):
        return x * 10

>>> E.f(3)
30
>>> E().f(3)
30

非データデスクリプタプロトコルを使うと、pure Python 版の staticmethod() は以下のようになります:

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)

functools.update_wrapper() の呼び出しは、根底にある関数を参照する __wrapped__ 属性を追加します。また、ラッパーがそのラップされた関数のように見えるよう、必要な属性を追加します: __name__ 、 __qualname__ 、 __doc__ 、 __annotations__ 。

クラスメソッド

静的メソッドとは違って、クラスメソッドは関数を呼び出す前にクラス参照を引数リストの先頭に加えます。このフォーマットは、呼び出し元がオブジェクトでもクラスでも同じです:

class F:
    @classmethod
    def f(cls, x):
        return cls.__name__, x

>>> F.f(3)
('F', 3)
>>> F().f(3)
('F', 3)

この振る舞いは、関数がクラス参照のみを必要とし、特定のインスタンスに保存されたデータに依存しないときに便利です。クラスメソッドの使い方の一つは、代わりのクラスコンストラクタを作ることです。例えば、クラスメソッド dict.fromkeys() は新しい辞書をキーのリストから生成します。等価な pure Python 版は:

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

これで一意なキーを持つ新しい辞書が以下のように構成できます:

>>> d = Dict.fromkeys('abracadabra')
>>> type(d) is Dict
True
>>> d
{'a': None, 'b': None, 'r': None, 'c': None, 'd': None}

非データデスクリプタプロトコルを使った、 classmethod() の pure Python 版はこのようになります:

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)
        if hasattr(type(self.f), '__get__'):
            # This code path was added in Python 3.9
            # and was deprecated in Python 3.11.
            return self.f.__get__(cls, cls)
        return MethodType(self.f, cls)

The code path for hasattr(type(self.f), '__get__') was added in Python 3.9 and makes it possible for classmethod() to support chained decorators. For example, a classmethod and property could be chained together. In Python 3.11, this functionality was deprecated.

class G:
    @classmethod
    @property
    def __doc__(cls):
        return f'A doc for {cls.__name__!r}'

>>> G.__doc__
"A doc for 'G'"

ClassMethod 内の functools.update_wrapper() の呼び出しは、根底にある関数を参照する __wrapped__ 属性を追加します。また、ラッパーがそのラップされた関数のように見えるよう、必要な属性を追加します: __name__ 、 __qualname__ 、 __doc__ 、 __annotations__ 。

メンバーオブジェクトと __slots__

クラスが __slots__ を定義すると、インスタンスの辞書が固定超のスロットの値の配列と置き換えられます。ユーザーの目線からみると、いくつかの変化があります。

1. Provides immediate detection of bugs due to misspelled attribute assignments. Only attribute names specified in __slots__ are allowed:

class Vehicle:
    __slots__ = ('id_number', 'make', 'model')

>>> auto = Vehicle()
>>> auto.id_nubmer = 'VYE483814LQEX'
Traceback (most recent call last):
    ...
AttributeError: 'Vehicle' object has no attribute 'id_nubmer'

2. Helps create immutable objects where descriptors manage access to private attributes stored in __slots__:

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

>>> 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'

3. Saves memory. On a 64-bit Linux build, an instance with two attributes takes 48 bytes with __slots__ and 152 bytes without. This flyweight design pattern [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 __slots__ (as measured with Python 3.10 on an Apple M1 processor).

5. Blocks tools like functools.cached_property() which require an instance dictionary to function correctly:

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)))

>>> CP().pi
Traceback (most recent call last):
  ...
TypeError: No '__dict__' attribute on 'CP' instance to cache 'pi' property.

__slots__ はC構造体に直接アクセスし、オブジェクトのメモリ確保を制御する必要があるため、ピュアPythonバージョンを作成することはできません。しかし、プライベートの __slotvalues リストを使ってC構造体のスロットをほぼ忠実にエミュレートすることはできます。そのプライベートな構造体への読み書きはメンバーのデスクリプタによって管理されます。

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}>'

type.__new__() メソッドはクラス変数へのメンバーオブジェクトの追加を処理します。

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)

object.__new__() メソッドはインスタンス辞書の代わりにスロットを持つインスタンスの作成の処理をします。おおざっぱにピュアPythonでのシミュレーションしたコードがこちらです。

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)

実際のクラスでシミュレーションコードを利用するには、 Object を継承し、 metaclass を Type にします。

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

この時点ではメタクラスは x と y のメンバーオブジェクトをロードします。

>>> 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'>}

インスタンスが作成されると、属性が保持される slot_values のリストをインスタンスが保持します:

>>> h = H(10, 20)
>>> vars(h)
{'_slotvalues': [10, 20]}
>>> h.x = 55
>>> vars(h)
{'_slotvalues': [55, 20]}

スペルミスや、未アサインの属性は例外を送出します。

>>> h.xz
Traceback (most recent call last):
    ...
AttributeError: 'H' object has no attribute 'xz'

Debugging C API extensions and CPython Internals with GDB

This document explains how the Python GDB extension, python-gdb.py, can be used with the GDB debugger to debug CPython extensions and the CPython interpreter itself.

When debugging low-level problems such as crashes or deadlocks, a low-level debugger, such as GDB, is useful to diagnose and correct the issue. By default, GDB (or any of its front-ends) doesn't support high-level information specific to the CPython interpreter.

The python-gdb.py extension adds CPython interpreter information to GDB. The extension helps introspect the stack of currently executing Python functions. Given a Python object represented by a PyObject* pointer, the extension surfaces the type and value of the object.

Developers who are working on CPython extensions or tinkering with parts of CPython that are written in C can use this document to learn how to use the python-gdb.py extension with GDB.

注釈

This document assumes that you are familiar with the basics of GDB and the CPython C API. It consolidates guidance from the devguide [https://devguide.python.org] and the Python wiki [https://wiki.python.org/moin/DebuggingWithGdb].

Prerequisites

You need to have:

GDB 7 or later. (For earlier versions of GDB, see Misc/gdbinit in the sources of Python 3.11 or earlier.)

GDB-compatible debugging information for Python and any extension you are debugging.

The python-gdb.py extension.

The extension is built with Python, but might be distributed separately or not at all. Below, we include tips for a few common systems as examples. Note that even if the instructions match your system, they might be outdated.

Setup with Python built from source

When you build CPython from source, debugging information should be available, and the build should add a python-gdb.py file to the root directory of your repository.

To activate support, you must add the directory containing python-gdb.py to GDB's "auto-load-safe-path". If you haven't done this, recent versions of GDB will print out a warning with instructions on how to do this.

注釈

If you do not see instructions for your version of GDB, put this in your configuration file (~/.gdbinit or ~/.config/gdb/gdbinit):

add-auto-load-safe-path /path/to/cpython

You can also add multiple paths, separated by :.

Setup for Python from a Linux distro

Most Linux systems provide debug information for the system Python in a package called python-debuginfo, python-dbg or similar. For example:

Fedora:

sudo dnf install gdb
sudo dnf debuginfo-install python3

Ubuntu:

sudo apt install gdb python3-dbg

On several recent Linux systems, GDB can download debugging symbols automatically using debuginfod. However, this will not install the python-gdb.py extension; you generally do need to install the debug info package separately.

Using the Debug build and Development mode

For easier debugging, you might want to:

Use a debug build of Python. (When building from source, use configure --with-pydebug. On Linux distros, install and run a package like python-debug or python-dbg, if available.)

Use the runtime development mode (-X dev).

Both enable extra assertions and disable some optimizations. Sometimes this hides the bug you are trying to find, but in most cases they make the process easier.

Using the python-gdb extension

When the extension is loaded, it provides two main features: pretty printers for Python values, and additional commands.

Pretty-printers

This is what a GDB backtrace looks like (truncated) when this extension is enabled:

#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

Notice how the dictionary argument to PyDict_GetItemString is displayed as its repr(), rather than an opaque PyObject * pointer.

The extension works by supplying a custom printing routine for values of type PyObject *. If you need to access lower-level details of an object, then cast the value to a pointer of the appropriate type. For example:

(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}}}

Note that the pretty-printers do not actually call repr(). For basic types, they try to match its result closely.

An area that can be confusing is that the custom printer for some types look a lot like GDB's built-in printer for standard types. For example, the pretty-printer for a Python int (PyLongObject*) gives a representation that is not distinguishable from one of a regular machine-level integer:

(gdb) p some_machine_integer
$3 = 42

(gdb) p some_python_integer
$4 = 42

The internal structure can be revealed with a cast to PyLongObject*:

(gdb) p (PyLongObject)some_python_integer $5 = {ob_base = {ob_base = {ob_refcnt = 8, ob_type = 0x3dad39f5e0}, ob_size = 1}, ob_digit = {42}}

A similar confusion can arise with the str type, where the output looks a lot like gdb's built-in printer for char *:

(gdb) p ptr_to_python_str
$6 = '__builtins__'

The pretty-printer for str instances defaults to using single-quotes (as does Python's repr for strings) whereas the standard printer for char * values uses double-quotes and contains a hexadecimal address:

(gdb) p ptr_to_char_star
$7 = 0x6d72c0 "hello world"

Again, the implementation details can be revealed with a cast to PyUnicodeObject*:

(gdb) p *(PyUnicodeObject*)$6
$8 = {ob_base = {ob_refcnt = 33, ob_type = 0x3dad3a95a0}, length = 12,
str = 0x7ffff2128500, hash = 7065186196740147912, state = 1, defenc = 0x0}

py-list

The extension adds a py-list command, which lists the Python source code (if any) for the current frame in the selected thread. The current line is marked with a ">":

(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...

Use py-list START to list at a different line number within the Python source, and py-list START,END to list a specific range of lines within the Python source.

py-up and py-down

The py-up and py-down commands are analogous to GDB's regular up and down commands, but try to move at the level of CPython frames, rather than C frames.

GDB is not always able to read the relevant frame information, depending on the optimization level with which CPython was compiled. Internally, the commands look for C frames that are executing the default frame evaluation function (that is, the core bytecode interpreter loop within CPython) and look up the value of the related PyFrameObject *.

They emit the frame number (at the C level) within the thread.

例えば:

(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

so we're at the top of the Python stack.

The frame numbers correspond to those displayed by GDB's standard backtrace command. The command skips C frames which are not executing Python code.

Going back down:

(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

and we're at the bottom of the Python stack.

Note that in Python 3.12 and newer, the same C stack frame can be used for multiple Python stack frames. This means that py-up and py-down may move multiple Python frames at once. For 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

py-bt

The py-bt command attempts to display a Python-level backtrace of the current thread.

例えば:

(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()

The frame numbers correspond to those displayed by GDB's standard backtrace command.

py-print

The py-print command looks up a Python name and tries to print it. It looks in locals within the current thread, then globals, then finally builtins:

(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

If the current C frame corresponds to multiple Python frames, py-print only considers the first one.

py-locals

The py-locals command looks up all Python locals within the current Python frame in the selected thread, and prints their representations:

(gdb) py-locals
self = <SwappableArea(running=<gtk.Dialog at remote 0x98faaa4>,
main_page=0) at remote 0x98fa6e4>
d = <gtk.Dialog at remote 0x98faaa4>

If the current C frame corresponds to multiple Python frames, locals from all of them will be shown:

(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>

Use with GDB commands

The extension commands complement GDB's built-in commands. For example, you can use a frame numbers shown by py-bt with the frame command to go a specific frame within the selected thread, like this:

(gdb) py-bt
(output snipped)
#68 Frame 0xaa4560, for file Lib/test/regrtest.py, line 1548, in <module> ()
        main()
(gdb) frame 68
#68 0x00000000004cd1e6 in PyEval_EvalFrameEx (f=Frame 0xaa4560, for file Lib/test/regrtest.py, line 1548, in <module> (), throwflag=0) at Python/ceval.c:2665
2665                            x = call_function(&sp, oparg);
(gdb) py-list
1543        # Run the tests in a context manager that temporary changes the CWD to a
1544        # temporary and writable directory. If it's not possible to create or
1545        # change the CWD, the original CWD will be used. The original CWD is
1546        # available from test_support.SAVEDCWD.
1547        with test_support.temp_cwd(TESTCWD, quiet=True):
>1548            main()

The info threads command will give you a list of the threads within the process, and you can use the thread command to select a different one:

(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

You can use thread apply all COMMAND or (t a a COMMAND for short) to run a command on all threads. With py-bt, this lets you see what every thread is doing at the Python level:

(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()

列挙型 HOWTO

Enum は、ユニークな値に束縛されたシンボル名の集合です。グローバル変数に似ていますが、 repr() がより便利だったり、グルーピングの機能、型安全などいくつかの機能があります。

これらは、限られた選択肢の値の一つを取る変数がある場合に便利です。例えば、曜日情報があります:

>>> from enum import Enum
>>> class Weekday(Enum):
...     MONDAY = 1
...     TUESDAY = 2
...     WEDNESDAY = 3
...     THURSDAY = 4
...     FRIDAY = 5
...     SATURDAY = 6
...     SUNDAY = 7

あるいは、RGB三原色でも構いません:

>>> from enum import Enum
>>> class Color(Enum):
...     RED = 1
...     GREEN = 2
...     BLUE = 3

ご覧の通り、 Enum の作成は Enum 自体を継承するクラスを作成するのと同じくらい簡単です。

注釈

Enumメンバーは大文字/小文字？

列挙型は定数を表すために使われるため、また mixin クラスのメソッドや属性との名前の衝突の問題を回避するため、メンバには UPPER_CASE の名前を使うことが強く推奨されており、例でもこのスタイルを用います。

列挙型の性質によって、メンバの値は重要な場合とそうでない場合がありますが、いずれの場合でも、その値は対応するメンバを取得するのに使えます:

>>> Weekday(3)
<Weekday.WEDNESDAY: 3>

ご覧の通り、メンバの repr() は列挙型の名前、メンバの名前、そして値を表示します。メンバの str() は列挙型の名前とメンバの名前のみを表示します。

>>> print(Weekday.THURSDAY)
Weekday.THURSDAY

列挙型のメンバの型はそのメンバの属する列挙型です:

>>> type(Weekday.MONDAY)
<enum 'Weekday'>
>>> isinstance(Weekday.FRIDAY, Weekday)
True

列挙型のメンバはその名前だけを含む属性 name を持っています:

>>> print(Weekday.TUESDAY.name)
TUESDAY

同じように、値のための属性 value もあります:

>>> Weekday.WEDNESDAY.value
3

多くの言語で列挙を名前と値のペアとしてのみ扱うのとは異なり、Pythonの列挙は振る舞いを追加することができます。 例えば、 datetime.date には曜日を返すメソッドに weekday() と isoweekday() の2つがあります。違いは、一方は0から6まで、もう一方は1から7まで数えることです。自分たちでそれらのメソッドの挙動を理解しておく代わりに、Weekday 列挙型にメソッドを追加することで、 date インスタンス から曜日を抽出し、それにマッチするenumメンバーを返すことができます:

@classmethod
def from_date(cls, date):
    return cls(date.isoweekday())

完全な Weekday enumはこのようになります:

>>> 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())

さて、これで今日が何曜日か調べることができます！ 見てみましょう:

>>> from datetime import date
>>> Weekday.from_date(date.today())
<Weekday.TUESDAY: 2>

もちろん、あなたがこれを読んでいるのが他の曜日ならば、その曜日が代わりに表示されます。

この Weekday 列挙型は、変数が1つの曜日を必要とする場合には優れていますが、複数必要な場合はどうでしょうか？ 1週間の家事を記録する関数を作成していて、listは使いたくない場合、別の型の Enum を使用することができます:

>>> from enum import Flag
>>> class Weekday(Flag):
...     MONDAY = 1
...     TUESDAY = 2
...     WEDNESDAY = 4
...     THURSDAY = 8
...     FRIDAY = 16
...     SATURDAY = 32
...     SUNDAY = 64

ここでは2つの変更が行われています。Flag を継承している点と、値がすべて2の累乗である点です。

元々の Weekday 列挙型と同じように、1つの要素を持つことができます:

>>> first_week_day = Weekday.MONDAY
>>> first_week_day
<Weekday.MONDAY: 1>

ただし、Flag は複数のメンバーをひとつの変数にまとめることもできます:

>>> weekend = Weekday.SATURDAY | Weekday.SUNDAY
>>> weekend
<Weekday.SATURDAY|SUNDAY: 96>

Flag 変数は反復することもできます:

>>> for day in weekend:
...     print(day)
Weekday.SATURDAY
Weekday.SUNDAY

さて、いくつかの家事を設定してみましょう:

>>> chores_for_ethan = {
...     'feed the cat': Weekday.MONDAY | Weekday.WEDNESDAY | Weekday.FRIDAY,
...     'do the dishes': Weekday.TUESDAY | Weekday.THURSDAY,
...     'answer SO questions': Weekday.SATURDAY,
...     }

指定された日の家事を表示する関数も作成します:

>>> 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

メンバーの実際の値が重要でない場合は、auto() を使用することで手間を省くことができます:

>>> from enum import auto
>>> class Weekday(Flag):
...     MONDAY = auto()
...     TUESDAY = auto()
...     WEDNESDAY = auto()
...     THURSDAY = auto()
...     FRIDAY = auto()
...     SATURDAY = auto()
...     SUNDAY = auto()
...     WEEKEND = SATURDAY | SUNDAY

列挙型メンバーおよびそれらの属性へのプログラム的アクセス

プログラム的にメンバーに番号でアクセスしたほうが便利な場合があります (すなわち、プログラムを書いている時点で正確な色がまだわからなく、Color.RED と書くのが無理な場合など)。 Enum ではそのようなアクセスも可能です:

>>> Color(1)
<Color.RED: 1>
>>> Color(3)
<Color.BLUE: 3>

列挙型メンバーに 名前 でアクセスしたい場合はアイテムとしてアクセスできます:

>>> Color['RED']
<Color.RED: 1>
>>> Color['GREEN']
<Color.GREEN: 2>

列挙型メンバーの name か value が必要な場合:

>>> member = Color.RED
>>> member.name
'RED'
>>> member.value
1

列挙型メンバーと値の重複

同じ名前の列挙型メンバーを複数持つことはできません:

>>> class Shape(Enum):
...     SQUARE = 2
...     SQUARE = 3
...
Traceback (most recent call last):
...
TypeError: 'SQUARE' already defined as 2

しかし、列挙型メンバー は、別の名前を持つことができます。 同じ値を持つ A と``B`` が与えられた場合（そして A が先に定義されている場合）、 B はメンバー A に対するエイリアスとなります。 A の値での検索では、メンバー A が返されます。 A の名前での検索ではメンバー A を返します。B の名前での検索も、メンバー A を返します:

>>> 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>

注釈

すでに定義されている属性と同じ名前のメンバー (一方がメンバーでもう一方がメソッド、など) の作成、あるいはメンバーと同じ名前の属性の作成はできません。

番号付けの値が一意であることの確認

デフォルトでは、列挙型は同じ値のエイリアスとして複数の名前を許容します。この振る舞いを望まない場合は、 unique() デコレータを使用できます:

>>> 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

値の自動設定を使う

正確な値が重要でない場合、 auto が使えます:

>>> from enum import Enum, auto
>>> class Color(Enum):
...     RED = auto()
...     BLUE = auto()
...     GREEN = auto()
...
>>> [member.value for member in Color]
[1, 2, 3]

その値は _generate_next_value_() によって選ばれ、この関数はオーバーライドできます:

>>> 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']

注釈

_generate_next_value_() メソッドは他のメンバーよりも前に定義される必要があります。

イテレーション

列挙型のメンバーのイテレートは別名をサポートしていません:

>>> 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>]

エイリアスである Shape.ALIAS_FOR_SQUARE と``Weekday.WEEKEND`` が表示されていないことに注意してください。

特殊属性 __members__ は読み出し専用で、順序を保持した、対応する名前と列挙型メンバーのマッピングです。これには別名も含め、列挙されたすべての名前が入っています。

>>> 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>)

属性 __members__ は列挙型メンバーへの詳細なアクセスに使用できます。以下はすべての別名を探す例です:

>>> [name for name, member in Shape.__members__.items() if member.name != name]
['ALIAS_FOR_SQUARE']

注釈

フラグのエイリアスには、 複数のフラグが設定された値（例えば 3）や、 フラグが設定されていない値（例えば 0）が含まれます。

比較

列挙型メンバーは同一性を比較できます:

>>> Color.RED is Color.RED
True
>>> Color.RED is Color.BLUE
False
>>> Color.RED is not Color.BLUE
True

列挙型の値の順序の比較はサポートされて いません。Enum メンバーは整数ではありません (IntEnum を参照してください):

>>> Color.RED < Color.BLUE
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: '<' not supported between instances of 'Color' and 'Color'

ただし等価の比較は定義されています:

>>> Color.BLUE == Color.RED
False
>>> Color.BLUE != Color.RED
True
>>> Color.BLUE == Color.BLUE
True

非列挙型の値との比較は常に不等となります (繰り返しになりますが、IntEnum はこれと異なる挙動になるよう設計されています):

>>> Color.BLUE == 2
False

警告

モジュールは再読み込みすることが可能です。再読み込みされたモジュールに列挙型が含まれている場合、それらは再作成され、新しいメンバーは元のメンバーと同一でない/等しくない可能性があります。

列挙型で許されるメンバーと属性

これまでのほとんどの例では、列挙型の値に整数を使用しています。 整数を使うのは短くて便利（そして、 関数 API ではデフォルトで設定される）ですが、これは強制されているわけではありません。大半の使用例では、列挙値の実際の値が何であるかは意識しません。しかし、値が重要な場合、列挙型は任意の値を持つことができます。

列挙型は Python のクラスであり、通常どおりメソッドや特殊メソッドを持つことができます:

>>> 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
...

上記の結果が以下のようになります:

>>> Mood.favorite_mood()
<Mood.HAPPY: 3>
>>> Mood.HAPPY.describe()
('HAPPY', 3)
>>> str(Mood.FUNKY)
'my custom str! 1'

何が許されているかのルールは次のとおりです。先頭と末尾が 1 個のアンダースコアの名前は列挙型により予約されているため、使用できません。列挙型内で定義されたその他すべての名前は、その列挙型のメンバーとして使用できます。特殊メソッド (__str__(), __add__() など) と、メソッドを含むデスクリプタ(記述子)、 _ignore_ に記載されている変数名は例外です。

注意：列挙型で __new__() および/または __init__() を定義している場合、列挙型メンバーに与えられた値は、それらのメソッドに渡されます。例については Planet を参照してください。

注釈

The __new__() method, if defined, is used during creation of the Enum members; it is then replaced by Enum's __new__() which is used after class creation for lookup of existing members. See __new__() と __init__() のどちらを使うべきか for more details.

Enumのサブクラス化の制限

新しい Enum クラスは、ベースの enum クラスを1つ、具象データ型を1つ、複数の object ベースのミックスインクラスが許容されます。これらのベースクラスの順序は次の通りです:

class EnumName([mix-in, ...,] [data-type,] base-enum):
    pass

列挙型のサブクラスの作成はその列挙型にメンバーが一つも定義されていない場合のみ行なえます。従って以下は許されません:

>>> class MoreColor(Color):
...     PINK = 17
...
Traceback (most recent call last):
...
TypeError: <enum 'MoreColor'> cannot extend <enum 'Color'>

以下のような場合は許されます:

>>> class Foo(Enum):
...     def some_behavior(self):
...         pass
...
>>> class Bar(Foo):
...     HAPPY = 1
...     SAD = 2
...

メンバーが定義された列挙型のサブクラス化を許可すると、いくつかのデータ型およびインスタンスの重要な不変条件の違反を引き起こします。とはいえ、それが許可されると、列挙型のグループ間での共通の挙動を共有するという利点もあります。 (OrderedEnum の例を参照してください。)

データクラスのサポート

dataclass を継承する場合、 __repr__() は継承するクラス名を省略します。 例えば:

>>> 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>

Use the dataclass() argument repr=False to use the standard repr().

バージョン 3.12 で変更: dataclass のフィールドだけが値の領域に表示され、dataclassの名前は表示されなくなりました

Pickle 化

列挙型は pickle 化と unpickle 化が行えます:

>>> from test.test_enum import Fruit
>>> from pickle import dumps, loads
>>> Fruit.TOMATO is loads(dumps(Fruit.TOMATO))
True

通常の pickle 化の制限事項が適用されます: pickle 可能な列挙型はモジュールのトップレベルで定義されていなくてはならず、unpickle 化はモジュールからインポート可能でなければなりません。

注釈

pickle プロトコルバージョン 4 では他のクラスで入れ子になった列挙型の pickle 化も容易です。

It is possible to modify how enum members are pickled/unpickled by defining __reduce_ex__() in the enumeration class. The default method is by-value, but enums with complicated values may want to use by-name:

>>> import enum
>>> class MyEnum(enum.Enum):
...     __reduce_ex__ = enum.pickle_by_enum_name

注釈

Using by-name for flags is not recommended, as unnamed aliases will not unpickle.

関数 API

Enum クラスは呼び出し可能で、以下の関数 API を提供しています:

>>> 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>]

この API の動作は namedtuple と似ています。Enum 呼び出しの第 1 引数は列挙型の名前です。

第 2 引数は列挙型メンバー名の ソース です。空白で区切った名前の文字列、名前のシーケンス、キー/値のペアの 2 要素タプルのシーケンス、あるいは名前と値のマッピング (例: 辞書) を指定できます。最後の 2 個のオプションでは、列挙型へ任意の値を割り当てることができます。前の 2 つのオプションでは、1 から始まり増加していく整数を自動的に割り当てます (別の開始値を指定するには、start 引数を使用します)。Enum から派生した新しいクラスが返されます。言い換えれば、上記の Animal への割り当ては以下と等価です:

>>> class Animal(Enum):
...     ANT = 1
...     BEE = 2
...     CAT = 3
...     DOG = 4
...

0 ではなく``1`` をデフォルトの開始番号とする理由は、0 が真偽値としては False であり、デフォルトの列挙メンバーはすべて 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:

>>> Animal = Enum('Animal', 'ANT BEE CAT DOG', module=__name__)

警告

module が与えられない場合、Enum はそれがなにか決定できないため、新しい Enum メンバーは unpickle 化できなくなります; エラーをソースの近いところで発生させるため、pickle 化は無効になります。

新しい pickle プロトコルバージョン 4 では、一部の状況において、pickle がクラスを発見するための場所の設定に __qualname__ を参照します。例えば、そのクラスがグローバルスコープ内のクラス SomeData 内で利用可能とするには以下のように指定します:

>>> Animal = Enum('Animal', 'ANT BEE CAT DOG', qualname='SomeData.Animal')

完全な構文は以下のようになります:

Enum(
    value='NewEnumName',
    names=<...>,
    *,
    module='...',
    qualname='...',
    type=<mixed-in class>,
    start=1,
    )

value: What the new enum class will record as its name.

names: enumのメンバー。 空白またはカンマで区切られた文字列 (値は特に指定がない限り1から始まります):

'RED GREEN BLUE' | 'RED,GREEN,BLUE' | 'RED, GREEN, BLUE'

または名前のイテレータで指定もできます:

['RED', 'GREEN', 'BLUE']

または (名前, 値) のペアのイテレータでも指定できます:

[('CYAN', 4), ('MAGENTA', 5), ('YELLOW', 6)]

またはマッピングでも指定できます:

{'CHARTREUSE': 7, 'SEA_GREEN': 11, 'ROSEMARY': 42}

module: name of module where new enum class can be found.

qualname: where in module new enum class can be found.

type: 新しい列挙型クラスにミックスインする型。

start：名前だけ渡された場合にカウントを開始する番号。

バージョン 3.5 で変更: start 引数が追加されました。

派生列挙型

IntEnum

提供されている 1 つ目の Enum の派生型であり、 int のサブクラスでもあります。 IntEnum のメンバーは整数と比較できます; さらに言うと、異なる整数列挙型どうしでも比較できます:

>>> 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

ただし、これらも標準の Enum 列挙型とは比較できません:

>>> class Shape(IntEnum):
...     CIRCLE = 1
...     SQUARE = 2
...
>>> class Color(Enum):
...     RED = 1
...     GREEN = 2
...
>>> Shape.CIRCLE == Color.RED
False

IntEnum の値は他の用途では整数のように振る舞います:

>>> int(Shape.CIRCLE)
1
>>> ['a', 'b', 'c'][Shape.CIRCLE]
'b'
>>> [i for i in range(Shape.SQUARE)]
[0, 1]

StrEnum

提供されている2つ目の Enum の派生型もまた、 str のサブクラスでもあります。StrEnum のメンバーは、文字列と比較できます; さらに言うと、異なる文字列列挙型どうしでも比較できます。

Added in version 3.11.

IntFlag

次の Enum の派生型 IntFlag も、int を基底クラスとしています。違いは、 IntFlag のメンバーをビット演算子 (&amp;, |, ^, ~) を使って組み合わせられ、その結果も IntFlag メンバーになることです。 IntEnum と同様、IntFlag のメンバーも整数であり、int が使用されるところであればどこでも使えます。

注釈

IntFlag メンバーに対してビット演算以外のどんな演算をしても、その結果は IntFlag メンバーではなくなります。

ビット単位演算の結果が IntFlag として不正な値な値の場合、値は IntFlag メンバーではなくなります。 詳しくは FlagBoundary を参照してください。

Added in version 3.6.

バージョン 3.11 で変更.

IntFlag クラスの例:

>>> 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

組み合わせにも名前を付けられます:

>>> 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>

注釈

組み合わせに名前をつけたものはエイリアスとみなされます。エイリアスはイテレーション中には表示されませんが、値による検索では返却されます。

バージョン 3.11 で変更.

IntFlag と Enum のもう 1 つの重要な違いは、フラグが設定されていない (値が0である) 場合、その真偽値としての評価は False になることです:

>>> Perm.R & Perm.X
<Perm: 0>
>>> bool(Perm.R & Perm.X)
False

IntFlag メンバーも int のサブクラスであるため、それらと組み合わせることができます（ただし、 IntFlag 型ではなくなる可能性があります）:

>>> Perm.X | 4
<Perm.R|X: 5>

>>> Perm.X + 8
9

注釈

否定の演算子,``~`` は、常に正の値を持つ:class:IntFlag メンバー を返す:

>>> (~Perm.X).value == (Perm.R|Perm.W).value == 6
True

IntFlag メンバーは反復処理することもできます:

>>> list(RW)
[<Perm.R: 4>, <Perm.W: 2>]

Added in version 3.11.

Flag

最後の派生型は Flag です。 IntFlag と同様に、 Flag メンバーもビット演算子 (&, |, ^, ~) を使って組み合わせられます。しかし IntFlag とは違い、他のどの Flag 列挙型とも int とも組み合わせたり、比較したりできません。値を直接指定することも可能ですが、値として auto を使い、 Flag に適切な値を選ばせることが推奨されています。

Added in version 3.6.

IntFlag と同様に、 Flag メンバーの組み合わせがどのフラグも設定されていない状態になった場合、その真偽値としての評価は False となります:

>>> 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

個別のフラグは 2 のべき乗 (1, 2, 4, 8, ...) の値を持つべきですが、フラグの組み合わせはそうはなりません:

>>> class Color(Flag):
...     RED = auto()
...     BLUE = auto()
...     GREEN = auto()
...     WHITE = RED | BLUE | GREEN
...
>>> Color.WHITE
<Color.WHITE: 7>

"フラグが設定されていない" 状態に名前を付けても、その真偽値は変わりません:

>>> class Color(Flag):
...     BLACK = 0
...     RED = auto()
...     BLUE = auto()
...     GREEN = auto()
...
>>> Color.BLACK
<Color.BLACK: 0>
>>> bool(Color.BLACK)
False

Flag members can also be iterated over:

>>> purple = Color.RED | Color.BLUE
>>> list(purple)
[<Color.RED: 1>, <Color.BLUE: 2>]

Added in version 3.11.

注釈

ほとんどの新しいコードでは、 Enum と Flag が強く推奨されます。というのは、 IntEnum と IntFlag は (整数と比較でき、従って推移的に他の無関係な列挙型と比較できてしまうことにより) 列挙型の意味論的な約束に反するからです。 IntEnum と IntFlag は、 Enum や Flag では上手くいかない場合のみに使うべきです; 例えば、整数定数を列挙型で置き換えるときや、他のシステムとの相互運用性を持たせたいときです。

その他

IntEnum は enum モジュールの一部ですが、単独での実装もとても簡単に行なえます:

class IntEnum(int, Enum):
    pass

ここでは似たような列挙型の派生を定義する方法を紹介します; 例えば、FloatEnum は int ではなく float で複合させたものです。

いくつかのルール:

When subclassing Enum, mix-in types must appear before Enum itself in the sequence of bases, as in the IntEnum example above.

複合させる型はサブクラス化可能でなければいけません。例えば、 bool と range はサブクラス化できないため、複合させるとEnum作成時にエラーが発生します。

Enum のメンバーはどんなデータ型でも構いませんが、追加のデータ型 (例えば、上の例の int) と複合させてしまうと、すべてのメンバーの値はそのデータ型でなければならなくなります。この制限は、メソッドの追加するだけの、他のデータ型を指定しない複合には適用されません。

他のデータ型と複合された場合、 value 属性は、たとえ等価であり等価であると比較が行えても、列挙型メンバー自身としては 同じではありません 。

A data type is a mixin that defines __new__(), or a dataclass

%-方式の書式: %s および %r はそれぞれ Enum クラスの __str__() および __repr__() を呼び出します; その他のコード (IntEnum の %i や %h など) は列挙型のメンバーを複合されたデータ型として扱います。

Formatted string literals, str.format(), and format() will use the enum's __str__() method.

注釈

IntEnum 、IntFlag 、StrEnum は、既存の定数のドロップイン置換として設計されているため、それらの:meth:__str__ メソッド は、それらのデータ型の:meth:__str__ メソッド にリセットされている。

__new__() と __init__() のどちらを使うべきか

__new__() は Enum メンバーの実際の値をカスタマイズしたいときに利用します。他の変更を加える場合、 __new__() と __init__() のどちらを利用するかは、__init__() の方が望ましいでしょう。

例えば、複数の値をコンストラクタに渡すが、その中の1つだけを値として使いたい場合は次のようにします:

>>> 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

警告

Do not call super().__new__(), as the lookup-only __new__ is the one that is found; instead, use the data type directly.

細かい点

__dunder__ 名のサポート

__members__ は読み込み専用の、 member_name:member を要素とする順序付きマッピングです。これはクラスでのみ利用可能です。

__new__() が、もし指定されていた場合、列挙型のメンバーを作成し、返します; そのメンバー の _value_ を適切に設定するのも非常によい考えです。いったん全てのメンバーが作成されると、それ以降 __new__() は使われません。

_sunder_ 名のサポート

_name_ -- name of the member

_value_ -- value of the member; can be set / modified in __new__

_missing_ -- a lookup function used when a value is not found; may be overridden

_ignore_ -- a list of names, either as a list or a str, that will not be transformed into members, and will be removed from the final class

_order_ -- used in Python 2/3 code to ensure member order is consistent (class attribute, removed during class creation)

_generate_next_value_ -- used by the Functional API and by auto to get an appropriate value for an enum member; may be overridden

注釈

For standard Enum classes the next value chosen is the last value seen incremented by one.

For Flag classes the next value chosen will be the next highest power-of-two, regardless of the last value seen.

Added in version 3.6: _missing_, _order_, _generate_next_value_

Added in version 3.7: _ignore_

Pythono 2 / Python 3のコードの同期を取りやすくするために _order_ 属性を提供できます。実際の列挙値の順序と比較して一致してなければエラーを送出します:

>>> 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']

注釈

Python 2のコードでは _order_ 属性は定義順が記録される前消えてしまうため、重要です。

_Private__names

Private names は列挙型メンバーには変換されず、通常の属性となります。

バージョン 3.11 で変更.

Enum メンバー型

列挙型メンバーはその列挙型クラスのインスタンスであり、通常は EnumClass.member としてアクセスされます。 振る舞い メンバー しかし、メンバー の名前と、属性/methodsが混在しているクラスとの名前の衝突を避けるために、大文字の名前を使うことを強く推奨します。

バージョン 3.5 で変更.

Creating members that are mixed with other data types

When subclassing other data types, such as int or str, with an Enum, all values after the = are passed to that data type's constructor. For example:

>>> class MyEnum(IntEnum):      # help(int) -> int(x, base=10) -> integer
...     example = '11', 16      # so x='11' and base=16
...
>>> MyEnum.example.value        # and hex(11) is...
17

Enum クラスとメンバーの真偽値

(int, str などのような) 非 Enum 型と複合させた enum クラスは、その複合された型の規則に従って評価されます; そうでない場合は、全てのメンバーは True と評価されます。メンバーの値に依存する独自の enum の真偽値評価を行うには、クラスに次のコードを追加してください:

def __bool__(self):
    return bool(self.value)

プレーンな Enum クラスは True として評価されます。

メソッド付きの Enum クラス

enum サブクラスに追加のメソッドを与えた場合、後述の Planet クラスのように、そのメソッドはメンバーの dir() に表示されますが、クラスの dir() には表示されません:

>>> 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']

Flag のメンバーの組み合わせ

Iterating over a combination of Flag members will only return the members that are comprised of a single bit:

>>> 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>

Flag and IntFlag minutia

例として以下のスニペットを使用します:

>>> class Color(IntFlag):
...     BLACK = 0
...     RED = 1
...     GREEN = 2
...     BLUE = 4
...     PURPLE = RED | BLUE
...     WHITE = RED | GREEN | BLUE
...

the following are true:

単一ビットのフラグは正規形です

複数ビットや0ビットのフラグはエイリアスです

反復処理では正規形のフラグのみ返却されます:

>>> list(Color.WHITE)
[<Color.RED: 1>, <Color.GREEN: 2>, <Color.BLUE: 4>]

negating a flag or flag set returns a new flag/flag set with the corresponding positive integer value:

>>> Color.BLUE
<Color.BLUE: 4>

>>> ~Color.BLUE
<Color.RED|GREEN: 3>

名前のないフラグについては、そのメンバーの名前から名前が生成されます:

>>> (Color.RED | Color.GREEN).name
'RED|GREEN'

multi-bit flags, aka aliases, can be returned from operations:

>>> Color.RED | Color.BLUE
<Color.PURPLE: 5>

>>> Color(7)  # or Color(-1)
<Color.WHITE: 7>

>>> Color(0)
<Color.BLACK: 0>

メンバーシップ/包含 のチェックでは、値が0のフラグは常に含まれるものとして扱われます:

>>> Color.BLACK in Color.WHITE
True

それ以外では、一方のフラグの全ビットが他方のフラグに含まれる場合のみ、Trueが返されます:

>>> Color.PURPLE in Color.WHITE
True

>>> Color.GREEN in Color.PURPLE
False

There is a new boundary mechanism that controls how out-of-range / invalid bits are handled: STRICT, CONFORM, EJECT, and KEEP:

STRICT --> 無効な値が指定された場合に例外を発生させる

CONFORM --> 無効なビットを破棄する

EJECT --> フラグのステータスを失い、指定された値を持つ通常の int となります。

KEEP --> keep the extra bits

keeps Flag status and extra bits

extra bits do not show up in iteration

extra bits do show up in repr() and str()

The default for Flag is STRICT, the default for IntFlag is EJECT, and the default for _convert_ is KEEP (see ssl.Options for an example of when KEEP is needed).

EnumとFlagはどう違うのか？

Enum は Enum 派生クラスやそれらのインスタンス (メンバー) 双方の多くの側面に影響を及ぼすカスタムメタクラスを持っています。

Enum クラス

The EnumType metaclass is responsible for providing the __contains__(), __dir__(), __iter__() and other methods that allow one to do things with an Enum class that fail on a typical class, such as list(Color) or some_enum_var in Color. EnumType is responsible for ensuring that various other methods on the final Enum class are correct (such as __new__(), __getnewargs__(), __str__() and __repr__()).

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 Enum definition of alias, a flag with no value (a.k.a. 0) or with more than one power-of-two value (e.g. 3) is considered an alias.

Enum メンバー (インスタンス)

enum メンバーについて最も興味深いのは、それらがシングルトンであるということです。EnumType は enum クラス自身を作成し、メンバーを作成し、新しいインスタンスが作成されていないかどうかを確認するために既存のメンバーインスタンスだけを返すカスタム __new__() を追加します。

Flag メンバー

フラグのメンバーは、Flag クラスと同様に反復処理することができ、正規のメンバーのみが返されます。 例えば:

>>> list(Color)
[<Color.RED: 1>, <Color.GREEN: 2>, <Color.BLUE: 4>]

（BLACK 、 PURPLE 、 WHITE は表示されないことに注意。）

フラグのメンバーを反転させると、負の値ではなく、対応する正の値が返されます:

>>> ~Color.RED
<Color.GREEN|BLUE: 6>

フラグのメンバーは、それが含む2のべき乗の値の数に対応するlengthを持ちます。 例えば:

>>> len(Color.PURPLE)
2

Enum クックブック

Enum, IntEnum, StrEnum, Flag, IntFlag は用途の大部分をカバーすると予想されますが、そのすべてをカバーできているわけではありません。ここでは、そのまま、あるいは独自の列挙型を作る例として使える、様々なタイプの列挙型を紹介します。

値の省略

多くの用途では、列挙型の実際の値が何かは気にされません。このタイプの単純な列挙型を定義する方法はいくつかあります:

値に auto インスタンスを使用する

値として object インスタンスを使用する

値として解説文字列を使用する

値としてタプルを使用し、独自の __new__() を使用してタプルを int 値で置き換える

これらのどの方法を使ってもユーザーに対して、値は重要ではなく、他のメンバーの番号の振り直しをする必要無しに、メンバーの追加、削除、並べ替えが行えるということを示せます。

auto を使う

auto を使うと次のようになります:

>>> class Color(Enum):
...     RED = auto()
...     BLUE = auto()
...     GREEN = auto()
...
>>> Color.GREEN
<Color.GREEN: 3>

object を使う

object を使うと次のようになります:

>>> class Color(Enum):
...     RED = object()
...     GREEN = object()
...     BLUE = object()
...
>>> Color.GREEN
<Color.GREEN: <object object at 0x...>>

また、これは自分で __repr__() を書きたくなるケースの良い例でもあります:

>>> class Color(Enum):
...     RED = object()
...     GREEN = object()
...     BLUE = object()
...     def __repr__(self):
...         return "<%s.%s>" % (self.__class__.__name__, self._name_)
...
>>> Color.GREEN
<Color.GREEN>

解説文字列を使う

値として文字列を使うと次のようになります:

>>> class Color(Enum):
...     RED = 'stop'
...     GREEN = 'go'
...     BLUE = 'too fast!'
...
>>> Color.GREEN
<Color.GREEN: 'go'>

独自の __new__() を使う

自動で番号を振る __new__() を使うと次のようになります:

>>> 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>

AutoNumber をより広い用途で使うには、シグニチャに *args を追加します:

>>> class AutoNumber(Enum):
...     def __new__(cls, *args):      # this is the only change from above
...         value = len(cls.__members__) + 1
...         obj = object.__new__(cls)
...         obj._value_ = value
...         return obj
...

AutoNumber を継承すると、追加の引数を取り扱える独自の __init__ が書けます。

>>> 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'

注釈

__new__() メソッドが定義されていれば、Enum 番号の作成時に使用されます; これは Enum の __new__() と置き換えられ、クラスが作成された後の既存の番号を取得に使用されます。

警告

Do not call super().__new__(), as the lookup-only __new__ is the one that is found; instead, use the data type directly -- e.g.:

obj = int.__new__(cls, value)

OrderedEnum

IntEnum をベースとしないため、通常の Enum の不変条件 (他の列挙型と比較できないなど) のままで、メンバーを順序付けできる列挙型です:

>>> 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

DuplicateFreeEnum

値が重複するメンバーがある場合に、エイリアスを作成するのではなくエラーを発生させます:

>>> 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'

注釈

これは Enum に別名を無効にするのと同様な振る舞いの追加や変更をおこなうためのサブクラス化に役立つ例です。単に別名を無効にしたいだけなら、 unique() デコレーターを使用して行えます。

Planet

__new__() や __init__() が定義されている場合、列挙型メンバーの値はこれらのメソッドに渡されます:

>>> class Planet(Enum):
...     MERCURY = (3.303e+23, 2.4397e6)
...     VENUS   = (4.869e+24, 6.0518e6)
...     EARTH   = (5.976e+24, 6.37814e6)
...     MARS    = (6.421e+23, 3.3972e6)
...     JUPITER = (1.9e+27,   7.1492e7)
...     SATURN  = (5.688e+26, 6.0268e7)
...     URANUS  = (8.686e+25, 2.5559e7)
...     NEPTUNE = (1.024e+26, 2.4746e7)
...     def __init__(self, mass, radius):
...         self.mass = mass       # in kilograms
...         self.radius = radius   # in meters
...     @property
...     def surface_gravity(self):
...         # universal gravitational constant  (m3 kg-1 s-2)
...         G = 6.67300E-11
...         return G * self.mass / (self.radius * self.radius)
...
>>> Planet.EARTH.value
(5.976e+24, 6378140.0)
>>> Planet.EARTH.surface_gravity
9.802652743337129

TimePeriod

_ignore_ 属性の使用方法のサンプルです:

>>> from datetime import timedelta
>>> class Period(timedelta, Enum):
...     "different lengths of time"
...     _ignore_ = 'Period i'
...     Period = vars()
...     for i in range(367):
...         Period['day_%d' % i] = i
...
>>> list(Period)[:2]
[<Period.day_0: datetime.timedelta(0)>, <Period.day_1: datetime.timedelta(days=1)>]
>>> list(Period)[-2:]
[<Period.day_365: datetime.timedelta(days=365)>, <Period.day_366: datetime.timedelta(days=366)>]

EnumType のサブクラスを作る

While most enum needs can be met by customizing Enum subclasses, either with class decorators or custom functions, EnumType can be subclassed to provide a different Enum experience.

関数型プログラミング HOWTO

著者:

A. M. Kuchling

リリース:

0.32

この文書では、関数型スタイルでプログラムを実装するのにピッタリな Python の機能を見てまわることにしましょう。まず関数型プログラミングという概念を紹介したあと、 iterator や generator のような言語機能、および itertools や functools といった関連するライブラリモジュールを見ることにします。

はじめに

この章は関数型プログラミングの基本概念を説明します; Python の言語機能についてだけ知りたい人は、次の章の イテレータ (iterator) まで飛ばしてください。

プログラミング言語とは問題を分解するものですが、各言語がサポートする分解方法にはいくつかの種類があります:

ほとんどのプログラミング言語は 手続き型 です: プログラムは、入力に対して行うべきことをコンピュータに教える指示リストとなります。 C, Pascal, さらには Unix シェルまでもが手続き型言語に入ります。

宣言型 言語で書くのは、解くべき問題を説明する仕様書であって、それを効率的に計算処理する方法を見付けるのは言語実装の役目です。SQL はおそらく一番よく知られた宣言型言語です; SQL のクエリは取得したいデータセットを説明しているだけで、テーブルを走査するかインデックスを使うか、どのサブクローズから実行するか等々を決めるのは SQL エンジンなのです。

オブジェクト指向 プログラムはオブジェクトの集まりを操作します。オブジェクトには内部状態があり、その状態を調べたり色々と変更したりするためのメソッドがあります。Smalltalk や Java はオブジェクト指向言語です。 C++ と Python はオブジェクト指向プログラミングをサポートしていますが、関連する機能を使わなくても構わないようになっています。

関数型 プログラミングは問題をいくつかの関数にわけて考えます。理想的に言うと、関数は入力を受けて出力を吐くだけで、同じ入力に対して異なる出力をするような内部状態を一切持ちません。有名な関数型言語には ML 一家 (Standard ML, OCaml 等々) と Haskell があります。

設計者が特定のアプローチを強調することにした言語もありますが、そうすると大抵は、別のアプローチを使うプログラムを書きにくくなります。複数のアプローチに対応した言語もあり、Lisp, C++, Python はそうしたマルチパラダイム言語です; この中のどれを使っても、基本的に手続き型な、または基本的にオブジェクト指向な、とか、基本的に関数型なプログラムやライブラリを書くことができます。大きなプログラムでは、各部で別々のアプローチを使って書くことがあるかもしれません; GUI はオブジェクト指向で、でも処理ロジックは手続き型や関数型で、といったようにです。

関数型プログラムでは、入力は一連の関数を通って流れていきます。それぞれの関数は入力に何らかの作業をして出力します。関数型スタイルにおいては、内部状態を変えてしまったり、返り値に現れない変更をしたりといった副作用のある関数はやめるように言われています。副作用のまったくない関数は 純粋関数型 であるとされます。副作用をなくすということは、プログラムの実行中に順次変化していくデータ構造を持たない、つまり各関数の出力はその入力にしか影響を受けてはいけないということです。

ある言語では純粋さにとても厳しく a=3 や c = a + b のような代入文すら存在しないほどですが、画面への表示やディスクファイルへの書き込みなど、すべての副作用を避けるのは難しいです。別の例として、 print() や time.sleep() 関数の呼び出しもありますが、どちらも有用な値を返しません。画面にテキストを送ったり、実行を 1 秒間停めたりといった副作用のためだけに呼ばれるのです。

関数型スタイルで書いた Python プログラムはふつう、I/O や代入を完全になくすといった極端なところまでは行かずに、関数型っぽく見えるインターフェースを提供しつつも内部では非関数型の機能を使います。たとえば、関数内でローカル変数の代入は使いますが、グローバル変数は変更せず、他の副作用もないように実装するのです。

関数型プログラミングはオブジェクト指向プログラミングの反対と考えることもできます。オブジェクト指向において、オブジェクトは内部状態とそれを変更するメソッドコールの入ったカプセルであり、プログラムはその状態を適正に変化させていく手順です。一方で、関数型プログラミングは可能なかぎり状態の変更を避け、関数どうしの間を流れるデータだけを扱おうとします。Python ではこの二つのアプローチを結び合わせることができます。アプリケーション内のオブジェクト (メール、トランザクション、等々) を表現したインスタンスを、関数が受け渡しするようにするのです。

関数型デザインは、わけのわからない制約に見えるかもしれません。どうしてオブジェクトも副作用もないほうが良いのでしょうか。実は、関数型スタイルには理論と実践に基づく次の利点があるのです:

形式的証明可能性。

モジュラー性。

結合性。

デバッグやテストの簡単さ。

形式的証明可能性

理論面の利点としては、プログラムが正しいことの数学的証明を他より簡単に構築できるという点があります。

研究者たちは長いあいだ、プログラムが正しいことを数学的に証明する方法の発見に血道をあげてきました。これは、色々な入力でテストして出力が正しかったからまあ正しいだろう、と結論するのとも違いますし、ソースコードを読んで「間違いはなさそうだ」と言うのとも別の話です; 目指すのは、出現しうる入力すべてに対してプログラムが正しい結果を出すことの厳密な証明なのです。

プログラムを証明するために使われているのは 不変式 を書き出していくというテクニックで、不変式とは入力データやプログラム変数のうち常に真である性質のことです。コードの一行一行で、 実行前 の不変式 X と Y が真なら 実行後に ちょっと違う不変式 X' と Y' が真になることを示していき、これをプログラムの終わりまで続けるわけです。すると最終的な不変式はプログラムの出力に合った条件になっているはずです。

関数型プログラミングが代入を嫌うのは、この不変式テクニックでは代入を扱いにくいからです; 代入は、それまで真だった不変式を壊しておいて、自分は次の行に伝えてゆける不変式を生み出さないことがあるのです。

残念ながら、プログラムの証明はだいたい実際的でもありませんし、Python ソフトウェアにも関係ありません。本当に簡単なプログラムでも、証明には数ページにわたる論文が必要なのです; ある程度の複雑なプログラムではもう尋常でない長さになってしまうので、日常で使っているプログラム (Python インタプリタ、XML パーサ、ウェブブラウザ) はほとんど、あるいはすべて、正しさを証明するのは不可能でしょう。仮に証明を書き出したり生成したりしても、その証明を検証するための疑いが残ります; 証明に間違いがあるかもしれず、その場合は証明したと自分で勝手に思い込んでいただけになるのです。

モジュラー性

より実用的には、関数型プログラミングをすると問題を細かく切り分けることになるという利点があります。結果としてプログラムはモジュラー化されます。複雑な変形を施す大きな関数を書くより、一つのことに絞ってそれだけをする小さな関数のほうが書きやすいものです。それに、小さいほうが読むのもエラーをチェックするのも簡単です。

デバッグやテストの簡単さ

テストやデバッグも関数型プログラムなら簡単です。

関数が一般的に小さくて明確に意味付けされているので、デバッグ方法は単純です。プログラムが正しく動かないときには、関数ひとつひとつがデータの正しさをチェックするポイントになるので、それぞれの時点における入力と出力を見ていけば、バグの原因となる関数を素早く切り出すことができるのです。

ひとつひとつの関数がユニットテストの対象になり得るわけですから、テストも簡単です。関数はシステムの状態に依存しませんので、テストの実行前にそうした状態を再現する必要はありません; 単に適切な入力を合成して、出力が期待どおりかどうかチェックするだけで良いのです。

結合性

関数型スタイルのプログラムを作っていると、色々な入力や出力のために色々な関数を書くことになります。仕方なく特定のアプリケーションに特化した関数を書くこともあるでしょうけれど、広範なプログラムに使える関数もあることでしょう。たとえば、ディレクトリ名を受け取ってその中の XML ファイル一覧を返す関数や、ファイル名を受け取って内容を返す関数などは、多様な場面に適用できそうです。

時たつうちに自分の特製ライブラリやユーティリティが充実してくると、新しいプログラムも、既存の関数を調整して少し今回に特化した関数を書くだけで組み立てられるようになります。

イテレータ (iterator)

まずは関数型スタイルのプログラムを書く際の基礎となる重要な Python 機能から見ていきましょう: イテレータです。

イテレータは連続データを表現するオブジェクトです; このオブジェクトは一度に一つの要素ずつデータを返します。 Python のイテレータは __next__() という、引数を取らず次の要素を返すメソッドを必ずサポートしています。データストリームに要素が残っていない場合、 __next__() は必ず StopIteration 例外を出します。ただし、イテレータの長さは有限である必要はありません; 無限のストリームを生成するイテレータを書くというのもまったく理に適ったことです。

ビルトインの iter() 関数は任意のオブジェクトを受けて、 その中身や要素を返すイテレータを返そうとします。引数のオブジェクトが イテレータを作れないときは TypeError を投げます。Python の ビルトインなデータ型にもいくつかイテレータ化のできるものがあり、 中でもよく使われるのはリストと辞書です。イテレータを作れる オブジェクトは iterable オブジェクトと呼ばれます。

手を動かしてイテレータ化の実験をしてみましょう:

>>> 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
>>>

Python は色々な文脈でイテラブルなオブジェクトを期待しますが、 最も重要なのは for 文です。 for X in Y という文の Y は、 イテレータか、あるいは iter() でイテレータを作れるオブジェクトである必要があります。次の二つは同じ意味になります:

for i in iter(obj):
    print(i)

for i in obj:
    print(i)

イテレータは list() や tuple() といったコンストラクタ関数を使ってリストやタプルに具現化することができます:

>>> L = [1, 2, 3]
>>> iterator = iter(L)
>>> t = tuple(iterator)
>>> t
(1, 2, 3)

シーケンスのアンパックもイテレータに対応しています: イテレータが N 個の要素を返すということが事前にわかっていれば、N-タプルにアンパックすることができます:

>>> L = [1, 2, 3]
>>> iterator = iter(L)
>>> a, b, c = iterator
>>> a, b, c
(1, 2, 3)

ビルトイン関数の max() や min() なども、イテレータ一つだけを引数に取って最大・最小の要素を返すことができます。 "in" や "not in" 演算子もイテレータに対応しています: X in iterator は、そのイテレータから返るストリームに X があれば真です。ですからイテレータが無限長だと、当然ながら問題に直面します; max(), min() はいつまでも戻って来ませんし、 要素 X がストリームに出てこなければ "in", "not in" オペレータも戻りません。

イテレータは次に進むことしかできませんのでご注意ください; 前の要素を手に入れたり、イテレータをリセットしたり、コピーを作ったりする方法はありません。イテレータがオブジェクトとしてそうした追加機能を 持つことはできますが、プロトコルでは __next__() メソッドのことしか指定されていません。ですから関数はイテレータの出力を使い尽くして しまうかもしれませんし、同じストリームに何か別のことをする 必要があるなら新しいイテレータを作らなくてはいけません。

イテレータ対応のデータ型

リストやタプルがイテレータに対応している方法については既に見ましたが、実のところ Python のシーケンス型はどれでも、たとえば文字列なども、自動でイテレータ生成に対応しています。

辞書に対して iter() すると、辞書のキーでループを回すイテレータが返されます:

>>> 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

Python 3.7 から、辞書の反復順序は挿入順序と同じであることが保証されていることに注意してください。以前のバージョンでは、その振る舞いは仕様が定められておらず、実装ごとに異なることがありました。

辞書は iter() を適用するとキーでループを回しますが、辞書には他のイテレータを返すメソッドもあります。明示的に値、あるいはキーと値のペアでイテレートしたければ、values(), items() というメソッドでイテレータを作ることができます。

逆に dict() コンストラクタは、有限な (key, value) タプルのストリームを返すイテレータを受け入れることができます:

>>> L = [('Italy', 'Rome'), ('France', 'Paris'), ('US', 'Washington DC')]
>>> dict(iter(L))
{'Italy': 'Rome', 'France': 'Paris', 'US': 'Washington DC'}

ファイルも、最後の行まで readline() メソッドを呼んでいくことでイテレータ化に対応しています。つまりこうやってファイルの各行を読んでいくことができるわけです:

for line in file:
    # do something for each line
    ...

セットはイテラブルを受け取れますし、そのセットの要素でイテレートすることもできます:

>>> S = {2, 3, 5, 7, 11, 13}
>>> for i in S:
...     print(i)
2
3
5
7
11
13

ジェネレータ式とリスト内包表記

イテレータの出力に対してよく使う操作トップ 2 は、(1) ひとつずつ全要素に操作を実行する、および (2) 条件に合う要素でサブセットを作る、です。たとえば文字列のリストなら、各行のうしろに付いた邪魔なホワイトスペースを削りたいとか、特定の文字列を含む部分をピックアップしたいなどと思うかもしれません。

リスト内包表記とジェネレータ式 (略して「listcomp」と「genexp」) は、そうした操作向けの簡潔な表記方法です。これは関数型プログラミング言語 Haskell (https://www.haskell.org/) にインスパイアされました。文字列のストリームからホワイトスペースをすべて削るのは次のコードでできます:

>>> line_list = ['  line 1\n', 'line 2  \n', ' \n', '']

>>> # Generator expression -- returns iterator
>>> stripped_iter = (line.strip() for line in line_list)

>>> # List comprehension -- returns list
>>> stripped_list = [line.strip() for line in line_list]

特定の要素だけを選び出すのは "if" 条件式を付けることで可能です:

>>> stripped_list = [line.strip() for line in line_list
...                  if line != ""]

リスト内包表記を使うと Python リストが返って来ます; stripped_list は実行結果の行が入ったリストであって、イテレータではありません。ジェネレータ式はイテレータを返し、これだと必要に応じてだけ値を算出しますので、すべての値を一度に出す必要がありません。つまりリスト内包表記のほうは、無限長ストリームや膨大なデータを返すようなイテレータを扱う際には、あまり役に立たないということです。そういった状況ではジェネレータ式のほうが好ましいと言えます。

ジェネレータ式は丸括弧 "()" で囲まれ、リスト内包表記は角括弧 "[]" で囲まれます。ジェネレータ式の形式は次のとおりです:

( 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 )

リスト内包表記も、外側の括弧が違うだけ (丸ではなく角括弧) で、あとは同じです。

生成される出力は expression 部分の値を要素として並べたものになります。 if 節はすべて、なくても大丈夫です; あれば condition が真のときだけ expression が評価されて出力に追加されます。

ジェネレータ式は常に括弧の中に書かなければなりませんが、関数コールの目印になっている括弧でも大丈夫です。関数にすぐ渡すイテレータを作りたければこう書けるのです:

obj_total = sum(obj.count for obj in list_all_objects())

for...in 節は複数つなげられますが、どれにも、イテレートするためのシーケンスが含まれています。それらのシーケンスは並行して ではなく 、左から右へ順番にイテレートされるので、長さが同じである必要はありません。 sequence1 の各要素ごとに毎回最初から sequence2 をループで回すのです。その後 sequence1 と sequence2 から出た要素ペアごとに、 sequence3 でループします。

別の書き方をすると、リスト内包表記やジェネレータ式は次の Python コードと同じ意味になります:

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.

つまり、複数の for...in 節があって if がないときの最終出力は、長さが各シーケンス長の積に等しくなるということです。長さ 3 のリスト二つなら、出力リストの長さは 9 要素です:

>>> 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)]

Python の文法に曖昧さを紛れ込ませないように、 expression でタプルを作るなら括弧で囲わなくてはなりません。下にあるリスト内包表記で、最初のは構文エラーですが、二番目は有効です:

# Syntax error
[x, y for x in seq1 for y in seq2]
# Correct
[(x, y) for x in seq1 for y in seq2]

ジェネレータ (generator)

ジェネレータは、イテレータを書く作業を簡単にする、特殊な関数です。標準的な関数は値を計算して返しますが、ジェネレータが返すのは、一連の値を返すイテレータです。

Python や C の標準的な関数コールについては、よくご存じに違いありません。関数を呼ぶと、ローカル変数を作るプライベートな名前空間ができますね。その関数が return 文まで来ると、ローカル変数が破壊されてから、返り値が呼び出し元に返ります。次に同じ関数をもう一度呼ぶと、新しいプライベート名前空間に新規のローカル変数が作られるのです。しかし、関数を出るときにローカル変数を捨てなければどうなるでしょうか。その出ていったところから関数を続行できたとしたら、どうでしょう。これこそジェネレータが提供する機能です; すなわち、ジェネレータは続行できる関数と考えることができます。

ごく単純なジェネレータ関数の例がこちらにあります:

>>> def generate_ints(N):
...    for i in range(N):
...        yield i

yield キーワードを含む関数はすべてジェネレータ関数です; Python の bytecode コンパイラがこれを検出して、特別な方法でコンパイルしてくれるのです。

ジェネレータ関数は、呼ばれたときに一回だけ値を返すのではなく、イテレータ プロトコルに対応したオブジェクトを返します。上の例で yield を実行したとき、 ジェネレータは return 文のようにして i の値を出力します。 yield と return 文の大きな違いは、 yield に到達した段階でジェネレータの実行状態が一時停止になって、ローカル変数が保存される点です。 次回そのジェネレータの __next__() を呼ぶと、そこから関数が実行を再開します。

上記 generate_ints() ジェネレータの使用例はこちらです:

>>> 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

同じく for i in generate_ints(5) や a, b, c = generate_ints(3) といった書き方もできます。

ジェネレータ関数の中では、return value は __next__() メソッドから送出された StopIteration(value) を引き起こします。これが発生した場合や、関数の終わりに到達した場合は、値の生成が終了してジェネレーターがそれ以上の値を返さない。

自分でクラスを書いて、ジェネレータで言うところのローカル変数をインスタンス変数として全部保管しておけば、同じ効果を得ることは可能です。たとえば整数のリストを返すのは、 self.count を 0 にして、 __next__() メソッドが self.count をインクリメントして返すようにすればできます。しかしながら、ある程度複雑なジェネレータになってくると、同じことをするクラスを書くのは格段にややこしいことになります。

Python のライブラリに含まれているテストスイート Lib/test/test_generators.py [https://github.com/python/cpython/tree/3.12/Lib/test/test_generators.py] には、ほかにも興味深い例が数多く入っています。これは二分木の通りがけ順 (in-order) 探索を再帰で実装したジェネレータです。

# 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

ほかにも test_generators.py には、N-Queens 問題 (N×N コマのチェス盤に、互いに攻撃できないような配置で N 個のクイーンを置く) やナイト・ツアー (N×N 盤の全コマをナイトが一度ずつ通るような経路を探す) の解を出す例が入っています。

ジェネレータに値を渡す

Python 2.4 までのジェネレータは出力することしかできませんでした。ジェネレータのコードを実行してイテレータを作ってしまったあとで、その関数を再開するときに新しい情報を渡す手段はなかったのです。ジェネレータがグローバル変数を見るようにしたり、ミュータブルなオブジェクトを渡しておいて呼び出し元であとからそれを変更したり、といったハックは可能でしたが、どれもゴチャゴチャしていますね。

Python 2.5 で、ジェネレータに値を渡す簡単な手段ができました。 yield が、変数に代入したり演算したりできる値を返す式になったのです:

val = (yield i)

上のように、返り値で何かをするときは yield 式の前後に 必ず 括弧を付けるようお勧めします。括弧は常に必要なわけではありませんが、どんなとき付けなくて良いのかを覚えておくより、いつも付けておくほうが楽ですから。

(PEP 342 [https://peps.python.org/pep-0342/] がその規則を正確に説明していますが、それによると yield-式は、代入式で右辺のトップレベルにあるとき以外はいつも括弧を付ける必要があります。つまり val = yield i とは書けますが、 val = (yield i) + 12 のように演算子があるときは括弧を使わなくてはいけません。)

ジェネレータに値を送るには send(value) メソッドを呼びます。 するとジェネレータのコードが実行を再開し、 yield 式がその値を返すのです。ふつうの __next__() メソッドを呼ぶと、 yield は None を返します。

下にあるのは 1 ずつ増える単純なカウンタですが、内部カウンタの値を変更することができるようになっています。

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

そしてカウンタ変更の例がこちらです:

>>> 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

yield が None を返すことはよくあるのですから、そうなっていないかどうか必ずチェックしておくべきです。ジェネレータ関数を再開するために使うメソッドが send() しかないのだと確定してるのでない限り、式の値をそのまま使ってはいけません。

ジェネレータには、 send() のほかにもメソッドが二つあります:

throw(value) はジェネレータ内で例外を投げるために使います; その例外はジェネレータの実行が停止したところの yield 式によって投げられます。

close() はジェネレータ内で GeneratorExit 例外を投げて、 イテレートを終了させます。この例外を受け取ったジェネレータのコードは GeneratorExit か StopIteration を投げなくてはいけません; この例外を捕捉して何かほかのことをしようとするのは規則違反であり、 RuntimeError を引き起こします。 close() はジェネレータが GC されるときにも呼ばれます。

GeneratorExit が起こったときにクリーンアップ作業をする必要があるなら、 GeneratorExit を捕捉するのではなく try: ... finaly: するようお勧めします。

これらの変更の合わせ技で、ジェネレータは情報の一方的な生産者から、生産者かつ消費者という存在に変貌を遂げたのです。

ジェネレータは コルーチン という、より一般化された形式のサブルーチンにもなります。サブルーチンは一カ所 (関数の冒頭) から入って別の一カ所 (return 文) から出るだけですが、コルーチンはいろいろな場所 (yield 文) から入ったり出たり再開したりできるのです。

組み込み関数 (built-in function)

よくイテレータと一緒に使うビルトイン関数について、もっと詳しく見ていきましょう。

Python のビルトイン関数 map() と filter() は、機能がジェネレータ式と重複しています:

map(f, iterA, iterB, ...) は以下のシーケンスのイテレータを返します

f(iterA[0], iterB[0]), f(iterA[1], iterB[1]), f(iterA[2], iterB[2]), ....

>>> def upper(s):
...     return s.upper()

>>> list(map(upper, ['sentence', 'fragment']))
['SENTENCE', 'FRAGMENT']
>>> [upper(s) for s in ['sentence', 'fragment']]
['SENTENCE', 'FRAGMENT']

もちろん、リスト内包表記でも同じ結果が得られます。

filter(predicate, iter) はある条件を満たす要素に渡るイテレータを返すので、同様にリスト内包表記で再現できます。 predicate は、ある条件に対する真偽値を返す関数です; filter() で使うには、その関数の引数は一つでなければなりません。

>>> def is_even(x):
...     return (x % 2) == 0

>>> list(filter(is_even, range(10)))
[0, 2, 4, 6, 8]

これはリスト内包表記でも書けます:

>>> list(x for x in range(10) if is_even(x))
[0, 2, 4, 6, 8]

enumerate(iter, start=0) はイテラブルの要素に順番に番号を振っていき、(start から数え始めたときの) 番号とそれぞれの要素を含む 2 タプルを返します。

>>> for item in enumerate(['subject', 'verb', 'object']):
...     print(item)
(0, 'subject')
(1, 'verb')
(2, 'object')

enumerate() はよく、リストに対してループさせて、条件に合う所に印を付けていくときに使われます:

f = open('data.txt', 'r')
for i, line in enumerate(f):
    if line.strip() == '':
        print('Blank line at line #%i' % i)

sorted(iterable, key=None, reverse=False) はイテラブルの要素をすべて集めたリストを作り、ソートして返します。 引数 key および reverse は、リストの sort() メソッドにそのまま渡されます。

>>> 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]

(ソートに関する詳細な論議は Sorting Techniques を参照)

組み込みの any(iter) および all(iter) は iterable の値の真偽を調べます。 any() は要素のどれかが真値なら True を返し、 all() は要素が全て真値なら True を返します:

>>> 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

zip(iterA, iterB, ...) はそれぞれの iterable から1つの要素を取り、それらをタプルに入れて返します:

zip(['a', 'b', 'c'], (1, 2, 3)) =>
  ('a', 1), ('b', 2), ('c', 3)

zip() は結果を返す前に入力のイテレーターを全て消費してメモリ上に list を作成しません。代わりに要求されるたびに tuple を生成して返します。(この動作を技術的な用語で lazy evaluation [https://en.wikipedia.org/wiki/Lazy_evaluation] (訳: 遅延評価 [https://ja.wikipedia.org/wiki/%E9%81%85%E5%BB%B6%E8%A9%95%E4%BE%A1]) と呼びます。)

このイテレータの用途には、すべて同じ長さのイテラブルを想定しています。長さが違っていれば、出力されるストリームは一番短いイテラブルと同じ長さになります。

zip(['a', 'b'], (1, 2, 3)) =>
  ('a', 1), ('b', 2)

とは言え、これをやってしまうと長いイテレータから要素をひとつ無駄に多く取って捨ててしまうかもしれませんので、やめておいたほうが良いです。その捨てられた要素を抜かしてしまう危険があるので、もうそのイテレータはそれ以上使えなくなってしまいます。

itertools モジュール

itertools モジュールには、よく使うイテレータや、イテレータ同士の連結に使う関数がたくさん含まれています。この章では、そのモジュールの内容を小さな例で紹介していきたいと思います。

このモジュールの関数を大まかに分けるとこうなります:

既存のイテレータに基づいて新しいイテレータを作る関数。

イテレータの要素を引数として扱う関数。

イテレータの出力から一部を取り出す関数。

イテレータの出力をグループ分けする関数。

新しいイテレータを作る

itertools.count(start, step) は値の間隔が一定の無限ストリームを返します。オプションで開始する数 (デフォルトは 0) や数どうしの間隔 (デフォルトは 1) を与えられます:

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, ...

itertools.cycle(iter) は与えられたイテラブルの内容をコピーして、 その要素を最初から最後まで無限に繰り返していくイテレータを返します。

itertools.cycle([1, 2, 3, 4, 5]) =>
  1, 2, 3, 4, 5, 1, 2, 3, 4, 5, ...

itertools.repeat(elem, [n]) は、与えられた要素を n 回返しますが、 n がなければ永遠に返し続けます。

itertools.repeat('abc') =>
  abc, abc, abc, abc, abc, abc, abc, abc, abc, abc, ...
itertools.repeat('abc', 5) =>
  abc, abc, abc, abc, abc

itertools.chain(iterA, iterB, ...) は任意の数のイテラブルを受け取って、最初のイテレータから要素をすべて返し、次に二番目から 要素をすべて返し、ということを要素がなくなるまで続けます。

itertools.chain(['a', 'b', 'c'], (1, 2, 3)) =>
  a, b, c, 1, 2, 3

itertools.islice(iter, [start], stop, [step]) は、イテレータの スライスをストリームで返します。 stop 引数だけだと、最初の stop 個の要素を返します。開始インデックスを渡すと stop-start 個で、 step の値も渡せばそれに応じて要素を抜かします。Python における文字列やリストのスライスとは違って、マイナスの値は start, stop, step に使えません。

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

itertools.tee(iter, [n]) はイテレータを複製します; 元のイテレータの内容を同じように返す、独立した n 個のイテレータを返すのです。 n の値は、指定しなければ既定が 2 になっています。複製するには元のイテレータの内容を一部保存しておく必要がありますから、大きなイテレータから複製したうちの一つが他よりも進んでいってしまうと、大量のメモリを消費することがあります。

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, ...

要素に対して関数を呼ぶ

いま使った operator モジュールには、Python の演算子に対応する関数が入っています。いくつか例を挙げると、 operator.add(a, b) (二つの値を加算)、 operator.ne(a, b) (a != b と同じ)、 operator.attrgetter('id') (.id 属性を取得するコーラブルを返す) といった関数です。

itertools.starmap(func, iter) は、イテラブルがタプルのストリームを返すとみなして、 そのタプルを引数に使って func を呼びます:

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

要素を選択する

さらに別のグループとして、述語 (predicate) に基づいてイテレータの要素からサブセットを選び出す関数があります。

itertools.filterfalse(predicate, iter) は filter() とは反対に、 述語が偽を返す要素をすべて返します:

itertools.filterfalse(is_even, itertools.count()) =>
  1, 3, 5, 7, 9, 11, 13, 15, ...

itertools.takewhile(predicate, iter) は述語が真を返している間だけ要素を返します。一度でも述語が偽を返すと、イテレータは出力終了の合図をします。

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

itertools.dropwhile(predicate, iter) は、述語が真を返しているうちは要素を無視し、偽になってから残りの出力をすべて返します。

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, ...

itertools.compress(data, selectors) は 2つのイテレータを取り、 どちらかのイテレータを使い果たすまでの、 selectors が真となる要素に対応する data 要素だけを返します:

itertools.compress([1, 2, 3, 4, 5], [True, True, False, False, True]) =>
   1, 2, 5

組合せ関数

itertools.combinations(iterable, r) は、 iterable から r-tuple 選択する全ての組み合わせを提供するイテレータを返します

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)

それぞれのタプル内では、要素は iterable がそれを返したのと同じ順序を保ちます。例えば上の例であれば、 1 はいつでも 2, 3, 4, 5 の前に来ます。似たような関数に itertools.permutations(iterable, r=None) があり、こちらはこの順序についての制約がなく、 r 個選択する全ての順列を返します。

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)

r を与えない場合は iterable の長さが使われます。つまり iterable の全ての要素を選んだ順列を返します。

これらの関数が生成する組み合わせは、位置が基準ですので、 iterable の内容が一意でなくとも良いことに注目してください:

itertools.permutations('aba', 3) =>
  ('a', 'b', 'a'), ('a', 'a', 'b'), ('b', 'a', 'a'),
  ('b', 'a', 'a'), ('a', 'a', 'b'), ('a', 'b', 'a')

全く同じタプル ('a', 'a', 'b') が 2度現れていますが、これは 2つの 'a' が別の位置からのものだからです。

itertools.combinations_with_replacement(iterable, r) 関数は別の制約を取り払います: 一回の選択で同じ要素を繰り返し選んでも良い。概念的には、それぞれのタプルの最初のものとして一つ要素が選ばれ、続いて 2つ目の選択のかわりにそれで置き換わります

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)

要素をグループ分けする

最後に議題に上げる関数 itertools.groupby(iter, key_func=None) は、 これまでで最も複雑です。 key_func(elem) は、イテラブルから返ってきた要素それぞれのキー値を計算する関数です。この関数が指定されていなければ、 キーは単に各要素そのものになります。

groupby() は、元になるイテラブルから同じキー値を持つ連続する要素を集めて、キー値とそのキーに対応する要素のイテレータの 2-タプルのストリームを返します。

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')

groupby() は、元になるイテラブルの内容がキー値でソートされた状態で与えられることを想定しています。ここで、返されるイテレータ自体も元のイテラブルを使うということに注意してください。そのため、 iterator-1 の結果を読み終わるまでは iterator-2 とそれに対応するキー値を要求することはできません。

functools モジュール

functools モジュールには、高階関数がいくつか入っています。 高階関数 とは、入力として関数を受け取って新たな関数を返す関数です。このモジュールで一番便利なツールは functools.partial() 関数です。

関数型スタイルのプログラムでは時折、既存の関数から一部のパラメータを埋めた変種を作りたくなることがあります。Python の関数 f(a, b, c) というものがあるとしてください; f(1, b, c) と同じ意味の g(b, c) という関数を作りたくなることがあります; つまり f() のパラメータを一つ埋めるわけです。これは「関数の部分適用」と呼ばれています。

partial() のコンストラクタは (function, arg1, arg2, ..., kwarg1=value1, kwarg2=value2) という引数を取ります。できあがったオブジェクトはコーラブルなので、それを呼べば、引数の埋まった状態で function を実行したのと同じことになります。

以下にあるのは、小さいけれども現実的な一つの例です:

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')

functools.reduce(func, iter, [initial_value]) はイテラブルの要素に対して次々に演算を実行していった最終結果を出すもので、それゆえ無限長イテラブルには適用できません。 func には、要素を二つ取って値を一つ返す関数が入ります。 functools.reduce() はイテレータが返す最初の二要素 A と B を取って func(A, B) を計算します。それから三番目の要素 C を要求して func(func(A, B), C) を計算すると、その結果をさらに四番目の要素と組み合わせて……ということをイテラブルが尽きるまで続けるのです。 もしイテラブルが一つも値を返さなければ TypeError が発生します。 初期値 initial_value があるときには、最初の計算で func(initial_value, A) が実行されます。

>>> 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

operator.add() を functools.reduce() で使うと、 iterable の全要素を合計することになります。これは使用頻度が高いので、そのための sum() というビルトイン関数があります:

>>> import functools, operator
>>> functools.reduce(operator.add, [1, 2, 3, 4], 0)
10
>>> sum([1, 2, 3, 4])
10
>>> sum([])
0

とはいえ、多くの場合 functools.reduce() を使うよりは、単に for ループを書いたほうがわかりやすくなります:

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

関連する関数は itertools.accumulate(iterable, func=operator.add) です。この関数は同じ計算をしますが、最終結果を返すのではなく、 accumulate() はそれぞれの中間結果を生成するイテレータが返り値となります。

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

operator モジュール

operator モジュールは、既に取り上げましたが、Python の演算子に対応する関数が入っているモジュールです。関数型スタイルのコードにおいて、演算を一つ実行するだけのくだらない関数を書かずに済むので、よく世話になります。

このモジュールの関数を一部だけ紹介しましょう:

数学演算子: add(), sub(), mul(), floordiv(), abs(), ...

論理演算子: not_(), truth()

ビット演算子: and_(), or_(), invert()

比較: eq(), ne(), lt(), le(), gt(), ge()

オブジェクト識別: is_(), is_not()

ちゃんとした一覧は operator モジュールの文書でご覧ください。

小さな関数とラムダ式

関数型スタイルのプログラムを書いていると、述語として働いたり、何らかの形で要素をつなぎ合わせたりするミニサイズの関数を必要とすることがよくあります。

ちょうど良い関数がビルトインやモジュールで存在していれば、新しい関数を定義する必要はまったくありません:

stripped_lines = [line.strip() for line in lines]
existing_files = filter(os.path.exists, file_list)

しかし、欲しい関数がないなら書くしかありません。そうした小さな関数を書く方法の 一つが lambda 式です。 lambda は引数として複数のパラメータと それをつなぐ式を取り、その式の値を返す無名の関数を作ります:

adder = lambda x, y: x+y

print_assign = lambda name, value: name + '=' + str(value)

もう一つの選択肢は、ふつうに def 文で関数を定義するだけです:

def adder(x, y):
    return x + y

def print_assign(name, value):
    return name + '=' + str(value)

どちらのほうが良いのでしょうか。それは好みの問題です; 著者のスタイルとしてはできるだけ lambda を使わないようにしています。

そのようにしている理由の一つに、lambda は定義できる関数が非常に限られているという点があります。一つの式として算出できる結果にしなければいけませんので、if... elif... else や try... except のような分岐を持つことができないのです。lambda 文の中でたくさんのことをやろうとしすぎると、ごちゃごちゃして読みにくい式になってしまいます。さて、次のコードは何をしているでしょうか、素早くお答えください!

import functools
total = functools.reduce(lambda a, b: (0, a[1] + b[1]), items)[1]

わかるにはわかるでしょうが、何がどうなっているのか紐解いていくには時間がかかるはずです。短い def 文で入れ子にすると、少し見通しが良くなりますが:

import functools
def combine(a, b):
    return 0, a[1] + b[1]

total = functools.reduce(combine, items)[1]

でも単純に for ループにすれば良かったのです:

total = 0
for a, b in items:
    total += b

あるいは sum() ビルトインとジェネレータ式でも良いですね:

total = sum(b for a, b in items)

多くの場合、 functools.reduce() を使っているところは for ループに 書き直したほうが見やすいです。

Fredrik Lundh は以前 lambda 利用のリファクタリングに関して以下の指針を提案したことがあります:

ラムダ関数を書く。

そのラムダが一体ぜんたい何をしているのかコメントで説明する。

そのコメントをしばらく研究して、本質をとらえた名前を考える。

ラムダをその名前で def 文に書き換える。

コメントを消す。

著者はこの指針を本当に気に入っていますが、こうしたラムダなしスタイルが他より優れているかどうかについて、異論は認めます。

更新履歴と謝辞

著者は提案の申し出や修正、様々なこの記事の草稿の助けをしてくれた以下の人々に感謝します: 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 functional module written by Collin Winter; adds short section on the operator module; a few other edits.

参考資料

一般論

計算機プログラムの構造と解釈、Harold AbelsonとGerald Jay Sussman、Julie Sussman著。この本は https://mitpress.mit.edu/sicp で見れます。この計算機科学の古典的な教科書では、2章と3章でシーケンスとストリームを使ってプログラム内のデータフローを整理する方法について説明しています。この本では例に Scheme を使っていますが、これらの章で説明されている設計アプローチの多くは、関数型スタイルの Python コードにも適用できます。

https://www.defmacro.org/ramblings/fp.html: 関数プログラミングの一般的な入門で Java での例を利用していて、長大な歴史の紹介があります。

https://en.wikipedia.org/wiki/Functional_programming: 関数プログラミングに関する一般的な内容の記事。

https://en.wikipedia.org/wiki/Coroutine: コルーチンに関する記事。

https://en.wikipedia.org/wiki/Partial_application: 関数の部分適用の概念についての記事。

https://en.wikipedia.org/wiki/Currying: カリー化の概念に関する記事。

Python 特有の話

https://gnosis.cx/TPiP/: David Mertz's の本の最初の章 Text Processing in Python では文書処理のための関数プログラミングについて議論しています、この議論の節には "Utilizing Higher-Order Functions in Text Processing" というタイトルがついています。

Mertz は IBM の DeveloperWorks サイトにも関数型プログラミングに関する 3 部構成の記事を書いています; part 1 [https://developer.ibm.com/articles/l-prog/], part 2 [https://developer.ibm.com/tutorials/l-prog2/], part 3 [https://developer.ibm.com/tutorials/l-prog3/],

Python 文書

itertools モジュールの文書。

functools モジュールについてのドキュメント。

operator モジュールの文書。

PEP 289 [https://peps.python.org/pep-0289/]: "Generator Expressions"

PEP 342 [https://peps.python.org/pep-0342/]: "Coroutines via Enhanced Generators" describes the new generator features in Python 2.5.

Logging HOWTO

著者:

Vinay Sajip <vinay_sajip at red-dove dot com>

このページはチュートリアルです。レファレンスやロギングクックブックは、 その他のリソース を参照してください。

基本 logging チュートリアル

logging は、あるソフトウェアが実行されているときに起こったイベントを追跡するための手段です。ソフトウェアの開発者は、特定のイベントが発生したことを示す logging の呼び出しをコードに加えます。イベントは、メッセージで記述され、これに変数データ (すなわち、イベントが起こる度に異なるかもしれないデータ) を加えることもできます。イベントには、開発者がそのイベントに定めた重要性も含まれます。重要性は、レベル (level) や 重大度 (severity) とも呼ばれます。

logging を使うとき

You can access logging functionality by creating a logger via logger = getLogger(__name__), and then calling the logger's debug(), info(), warning(), error() and 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.

行いたいタスク

そのタスクに最適なツール

コマンドラインスクリプトやプログラムで普通に使う、コンソール出力の表示

print()

プログラムの通常の操作中に発生したイベントの報告 (例えば、状態の監視や障害の分析)

A logger's info() (or debug() method for very detailed output for diagnostic purposes)

特定のランタイムイベントに関わる警告の発行

その発行が避けられるもので、クライアントアプリケーションを修正してその警告を排除するべきなら warnings.warn()

A logger's warning() method if there is nothing the client application can do about the situation, but the event should still be noted

特定のランタイムイベントに関わるエラーの報告

例外の送出

例外の送出をしないエラーの抑制 (例えば、長期のサーバプロセス中のエラーハンドラ)

A logger's error(), exception() or critical() method as appropriate for the specific error and application domain

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):

レベル

いつ使うか

DEBUG

おもに問題を診断するときにのみ関心があるような、詳細な情報。

INFO

想定された通りのことが起こったことの確認。

WARNING

想定外のことが起こった、または問題が近く起こりそうである (例えば、'disk space low') ことの表示。

ERROR

より重大な問題により、ソフトウェアがある機能を実行できないこと。

CRITICAL

プログラム自体が実行を続けられないことを表す、重大なエラー。

The default level is WARNING, which means that only events of this level and above will be tracked, unless the logging package is configured to do otherwise.

追跡されるイベントは、異なる方法で処理されます。追跡されたイベントを処理する最も単純な方法は、それをコンソールに表示することです。その他のよくある方法は、それをディスクファイルに書き出すことです。

簡単な例

ごく簡単な例は:

import logging
logging.warning('Watch out!')  # will print a message to the console
logging.info('I told you so')  # will not print anything

これらの行をスクリプトにタイプして実行すると、次のようにコンソールに出力されます:

WARNING:root:Watch out!

printed out on the console. The INFO message doesn't appear because the default level is 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 logging module, like logging.debug, rather than creating a logger and calling functions on it. These functions operation on the root logger, but can be useful as they will call 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.

ファイルへの logging

logging イベントをファイルに記録するのは非常によくあるパターンなので次はこれを見て行きましょう。以下のサンプルを試すときは Python インタプリタを新しく起動して、上のセッションの続きにならないようにしてください:

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ö')

バージョン 3.9 で変更: encoding 引数が追加されました。以前のバージョンの Python では、あるいは指定されなかったら、エンコーディングには open() が使うデフォルト値が使われます。上の例に出てきていませんが、同じく渡せるようになった errors 引数は、エンコーディングエラーの扱いを決定します。利用可能な値およびデフォルト値については、 open() のドキュメントを参照してください。

そして、ファイルの中身を確認すると、ログメッセージが確認できます:

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ö

この例はまた、追跡のしきい値となるロギングレベルを設定する方法も示しています。この例では、しきい値を DEBUG に設定しているので、全てのメッセージが表示されています。

次のようなコマンドラインオプションでログレベルを設定したいと考え:

--log=INFO

--log に渡されたパラメータの値を変数 loglevel に保存しているとしたら、

getattr(logging, loglevel.upper())

というコードを使い、 basicConfig() の level 引数に渡すべき値が得られます。ユーザの入力値をすべてエラーチェックしたくなり、次の例のように実装することもあるでしょう:

# 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, ...)

The call to basicConfig() should come before any calls to a logger's methods such as debug(), info(), etc. Otherwise, that logging event may not be handled in the desired manner.

上記のスクリプトを複数回実行すると、2 回目以降の実行によるメッセージは example.log に加えられます。以前の実行によるメッセージを記憶せず、実行ごとに新たに始めたいなら、上記の例での呼び出しを次のように変え、filemode 引数を指定する方法がとれます:

logging.basicConfig(filename='example.log', filemode='w', level=logging.DEBUG)

出力は先ほどと同じになりますが、ログファイルは追記されなくなり、以前の実行によるメッセージは失われます。

変数データのロギング

変数データのログを取るには、イベント記述メッセージにフォーマット文字列を使い、引数に変数データを加えてください。例えば:

import logging
logging.warning('%s before you %s', 'Look', 'leap!')

により、次のように表示されます:

WARNING:root:Look before you leap!

ご覧の通り、イベント記述メッセージに変数データを統合するために、古い、% スタイルの文字列フォーマットを使っています。これは後方互換性のためです。logging パッケージは、 str.format() や string.Template のような新しいフォーマットオプションよりも先に生まれました。新しいフォーマットオプションはサポートされて います が、その探求はこのチュートリアルでは対象としません。詳細は 固有の書式化スタイルをアプリケーション全体で使う を参照してください。

表示されるメッセージのフォーマットの変更

メッセージを表示するのに使われるフォーマットを変更するには、使いたいフォーマットを指定する必要があります:

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')

により、次のように表示されます:

DEBUG:This message should appear on the console
INFO:So should this
WARNING:And this, too

ご覧の通り、先の例に現れた 'root' が消失しています。フォーマット文字列に含めることができるものの一覧は、 LogRecord 属性 のドキュメントから参照できますが、単純な用途では、必要なものは levelname (重大度)、 message (変数データを含むイベント記述)、それともしかしたら、イベントがいつ起こったかという表示だけです。これは次の節で解説します。

メッセージ内での日付と時刻の表示

イベントの日付と時刻を表示するには、フォーマット文字列に '%(asctime)s' を置いてください:

import logging
logging.basicConfig(format='%(asctime)s %(message)s')
logging.warning('is when this event was logged.')

これは以下の様なフォーマットで表示されます:

2010-12-12 11:41:42,612 is when this event was logged.

デフォルトの日付と時間の表示フォーマット （上記の結果） は、ISO8601 や RFC 3339 [https://datatracker.ietf.org/doc/html/rfc3339.html] に似ています。日付と時間のフォーマットをより詳細に制御する必要があるなら、以下の例の様に、 basicConfig に datefmt 引数を指定してください:

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.')

これは次のように表示されます:

12/12/2010 11:46:36 AM is when this event was logged.

datefmt 引数のフォーマットは、 time.strftime() でサポートされているものと同じです。

次のステップ

基本チュートリアルはこれで終わりです。あなたがロギングを使っていくためには、これで十分でしょう。logging パッケージが提供するものはもっとありますが、それを使いこなすためには、もうちょっと時間をかけて、以下のセクションを読む必要があります。その用意ができたら、好きな飲み物を持って、次に進みましょう。

ロギングを簡潔に行いたいなら、上記の例を使って、ロギングをあなたのスクリプトに組み込んでください。問題があったり理解出来ないことがあったら、comp.lang.python Usenet group (https://groups.google.com/g/comp.lang.python から利用できます) に質問を投稿してくだされば、そう遠くないうちに助けが得られるでしょう。

まだいますか？もう少し上級の、踏み込んだチュートリアルを綴った、幾つかの節を読み続けることができます。その後で、 Logging クックブック もご覧ください。

上級ロギングチュートリアル

logging ライブラリはモジュール方式のアプローチを取り、いくつかのカテゴリの部品を提供します。ロガー、ハンドラ、フィルタ、フォーマッタです。

ロガーは、アプリケーションコードが直接使うインターフェースを公開します。

ハンドラは、(ロガーによって生成された) ログ記録を適切な送信先に送ります。

フィルタは、どのログ記録を出力するかを決定する、きめ細かい機能を提供します。

フォーマッタは、ログ記録が最終的に出力されるレイアウトを指定します。

ログイベント情報は LogRecord インスタンスの形で、 logger, handler, filter, formatter の間でやりとりされます。

ロギングは、 Logger クラスのインスタンス (以下 ロガー) にメソッドを呼び出すことで実行されます。各インスタンスには名前があり、名前空間階層構造に、ドット (ピリオド) をセパレータとして、概念的に並べられています。例えば、 'scan' という名前のロガーは、ロガー 'scan.text', 'scan.html' および 'scan.pdf'の親です。ロガー名は、何でも望むものにでき、ロギングされたメッセージが発生した場所を指し示します。

ロガーに名前をつけるときの良い習慣は、ロギングを使う各モジュールに、以下のように名付けられた、モジュールレベルロガーを使うことです:

logger = logging.getLogger(__name__)

これにより、ロガー名はパッケージ/モジュール階層をなぞり、ロガー名だけで、どこでイベントのログが取られたか、直感的に明らかになります。

ロガーの階層構造の根源は、ルートロガーと呼ばれます。それが、関数 debug(), info(), warning(), error() および critical() によって使われるロガーとなります。これらの関数は単に、ルートロガーの同名のメソッドを呼び出します。これらの関数とメソッドは、同じ署名をもっています。ルートロガーの名前は、ログ出力では 'root' と表示されます。

もちろん、メッセージを異なる送信先に記録することも出来ます。このパッケージでは、ファイルへ、 HTTP GET/POST 先へ、 SMTP 経由で電子メールへ、汎用のソケットへ、キューへ、または Windows NT イベントログのような OS 毎のログ記録機構への、ログメッセージの書きこみがサポートされています。送信先は、 handler クラスによって取り扱われます。組み込みのハンドラクラスでは満たせないような、特殊な要件があるなら、独自のログ送信先を生成できます。

デフォルトでは、どのロギングメッセージに対しても、送信先は設定されていません。チュートリアルの例のように、 basicConfig() を使って、送信先 (コンソールやファイルなど) を指定できます。関数 debug(), info(), warning(), error() および critical() を呼び出すと、それらは送信先が設定されていないかを調べます。そして設定されていなければ、ルートロガーに委譲して実際にメッセージを出力する前に、コンソール (sys.stderr) を送信先に、デフォルトのフォーマットを表示されるメッセージに設定します。

basicConfig() が設定するデフォルトのメッセージのフォーマットは次のようになります:

severity:logger name:message

basicConfig() の format キーワード引数にフォーマット文字列を渡すことで、これを変更できます。フォーマット文字列を構成するためのすべてのオプションは、 フォーマッタオブジェクト を参照してください。

Logging Flow

次の図はログイベントが logger と handler をどう流れるかを示しています。

ロガー

Logger オブジェクトの仕事は大きく三つに分かれます。一つ目は、アプリケーションが実行中にメッセージを記録できるように、いくつかのメソッドをアプリケーションから呼べるようにしています。二つ目に、ロガーオブジェクトはどのメッセージに対して作用するかを、深刻度 (デフォルトのフィルタ機構) またはフィルタオブジェクトに基づいて決定します。三つ目に、ロガーオブジェクトは関心を持っているすべてのログハンドラに関連するログメッセージを回送します。

とりわけ広く使われるロガーオブジェクトのメソッドは、二つのカテゴリーに分類できます: 設定とメッセージ送信です。

これらが設定メソッドの中でよく使われます:

Logger.setLevel() はロガーが扱うログメッセージの最も低い深刻度を指定します。組み込みの深刻度の中では DEBUG が一番低く、 CRITICAL が一番高くなります。たとえば、深刻度が INFO と設定されたロガーは INFO, WARNING, ERROR, CRITICAL のメッセージしか扱わず、 DEBUG メッセージは無視します。

Logger.addHandler() と Logger.removeHandler() は、ハンドラオブジェクトをロガーオブジェクトから追加または削除します。ハンドラについては、 ハンドラ で詳しく述べます。

Logger.addFilter() と Logger.removeFilter() はロガーオブジェクトにフィルタオブジェクトを追加または削除します。フィルタについては、 フィルタオブジェクト で詳しく述べます。

これらのメソッドを、生成したすべてのロガーに毎回呼び出さなければならないわけではありません。この節の最後の 2 段落を参照してください。

ロガーオブジェクトが設定されれば、以下のメソッドがログメッセージを生成します:

Logger.debug(), Logger.info(), Logger.warning(), Logger.error(), Logger.critical() はすべて、メッセージとメソッド名に対応したレベルでログ記録を作り出します。メッセージは実際にはフォーマット文字列であり、通常の文字列代入に使う %s, %d, %f などを含むことができます。残りの引数はメッセージの代入される位置に対応するオブジェクトのリストです。 **kwargs については、ログ記録メソッドが気にするキーワードは exc_info だけで、例外の情報をログに記録するかを決定するのに使います。

Logger.exception() は Logger.error() と似たログメッセージを作成します。違いは Logger.exception() がスタックトレースを一緒にダンプすることです。このメソッドは例外ハンドラからだけ呼び出すようにしてください。

Logger.log() はログレベルを明示的な引数として受け取ります。これは上に挙げた便宜的なログレベル毎のメソッドを使うより少しコード量が多くなりますが、独自のログレベルを使うことができます。

getLogger() は、指定されればその特定の名前の、そうでなければ root のロガーインスタンスへの参照を返します。ロガーの名前はピリオド区切りの階層構造を表します。同じ名前で getLogger() を複数回呼び出した場合、同一のロガーオブジェクトへの参照が返されます。階層リストを下ったロガーはリスト上位のロガーの子です。たとえば、名前が foo であるロガーがあったとして、 foo.bar, foo.bar.baz, foo.bam といった名前のロガーはすべて foo の子孫になります。

ロガーには、有効レベル (effective level) の概念があります。ロガーにレベルが明示的に設定されていなければ、代わりに親のレベルがその有効レベルとして使われます。親のレベルが設定されなければ、その 親のレベルが確かめられ、以下同様に、明示的に設定されたレベルが見つかるまで祖先が探されます。ルートロガーは、必ず明示的なレベルが設定されています (デフォルトでは WARNING です)。イベントを処理するかを決定するとき、ロガーの有効レベルを使って、イベントがロガーのハンドラに渡されるかが決められます。

子ロガーはメッセージを親ロガーのハンドラに伝えます。このため、アプリケーションが使っているすべてのロガーのためのハンドラを定義して設定する必要はありません。トップレベルのロガーのためのハンドラだけ設定しておいて必要に応じて子ロガーを作成すれば十分です。(しかし、ロガーの propagate 属性を False に設定することで、伝播を抑制できます。)

ハンドラ

Handler オブジェクトは適切なログメッセージを (ログメッセージの深刻度に基づいて) ハンドラの指定された出力先に振り分けることに責任を持ちます。 Logger オブジェクトには addHandler() メソッドで 0 個以上のハンドラを追加することができます。例として、あるアプリケーションがすべてのログメッセージをログファイルに、 error 以上のすべてのログメッセージを標準出力に、 critical のメッセージはすべてメールアドレスに、それぞれ送りたいとします。この場合、 3 つの個別のハンドラがそれぞれの深刻度と宛先に応じて必要になります。

このライブラリには多くのハンドラが用意されています (便利なハンドラ を参照してください) が、このチュートリアルでは StreamHandler と FileHandler だけを例に取り上げます。

アプリケーション開発者にとってハンドラを扱う上で気にするべきメソッドは極々限られています。組み込みのハンドラオブジェクトを使う (つまり自作ハンドラを作らない) 開発者に関係あるハンドラのメソッドは、次の設定用のメソッドだけでしょう:

setLevel() メソッドは、ロガーオブジェクトの場合と同様に、適切な出力先に振り分けられるべき最も低い深刻度を指定します。なぜ 2 つも setLevel() メソッドがあるのでしょうか? ロガーで設定されるレベルは、付随するハンドラにどんな深刻度のメッセージを渡すか決めます。それぞれのハンドラで設定されるレベルは、そのハンドラがどのメッセージを転送するべきか決めます。

setFormatter() でこのハンドラが使用する Formatter オブジェクトを選択します。

addFilter() および removeFilter() はそれぞれハンドラへのフィルタオブジェクトの設定と解除を行います。

アプリケーションのコード中では Handler のインスタンスを直接インスタンス化して使ってはなりません。代わりに、 Handler クラスはすべてのハンドラが持つべきインターフェイスを定義する基底クラスであり、子クラスが使える (もしくはオーバライドできる) いくつかのデフォルトの振る舞いを規定します。

フォーマッタ

フォーマッタオブジェクトは最終的なログメッセージの順序、構造および内容を設定します。基底クラスである logging.Handler とは違って、アプリケーションのコードはフォーマッタクラスをインスタンス化しても構いません。特別な振る舞いをさせたいアプリケーションではフォーマッタのサブクラスを使う可能性もあります。コンストラクタは三つのオプション引数を取ります -- メッセージのフォーマット文字列、日付のフォーマット文字列、スタイル標識です。

logging.Formatter.__init__(fmt=None, datefmt=None, style='%')

フォーマット文字列に何も渡さない場合は、デフォルトで行メッセージが利用されます。また、日付フォーマットに何も渡さない場合は、デフォルトで以下のフォーマットが利用されます:

%Y-%m-%d %H:%M:%S

時刻の末尾にはミリ秒が付きます。 style は '%', '{', または '{TX-PL-LABEL}#x27; のいずれかです。特に指定がなければ '%' が使われます。

style が '%' の場合、メッセージフォーマット文字列では %(<dictionary key>)s 形式の置換文字列が使われます; キーに指定できる属性名は LogRecord 属性 に文書化されています。 style が '{' の場合、メッセージフォーマット文字列は (キーワード引数を使う) str.format() と互換となります。 style が '$' の場合、メッセージフォーマット文字列は string.Template.substitute() で期待されているものと一致します。

バージョン 3.2 で変更: style パラメータが追加されました。

次のメッセージフォーマット文字列は、人が読みやすい形式の時刻、メッセージの深刻度、およびメッセージの内容を、順番に出力します:

'%(asctime)s - %(levelname)s - %(message)s'

フォーマッタは、ユーザが設定できる関数を使って、生成時刻をタプルに記録します。デフォルトでは、 time.localtime() が使われます。特定のフォーマッタインスタンスに対してこれを変更するには、インスタンスの converter 属性を time.localtime() や time.gmtime() と同じ署名をもつ関数に設定してください。すべてのフォーマッタインスタンスに対してこれを変更するには、例えば全てのロギング時刻を GMT で表示するには、フォーマッタクラスの converter 属性を (GMT 表示の time.gmtime に) 設定してください。

ロギングの環境設定

プログラマは、ロギングを 3 種類の方法で設定できます:

上述の設定メソッドを呼び出す Python コードを明示的に使って、ロガー、ハンドラ、そしてフォーマッタを生成する。

ロギング設定ファイルを作り、それを fileConfig() 関数を使って読み込む。

設定情報の辞書を作り、それを dictConfig() 関数に渡す。

最後の2つの選択肢については、 環境設定のための関数 で解説しています。以下の例では、Python コードを使って、とても簡単なロガー、コンソールハンドラ、そして簡単なフォーマッタを設定しています:

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')

このモジュールを実行すると、コマンドラインによって以下の出力がなされます:

$ 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

以下の Python モジュールは、ロガー、ハンドラ、フォーマッタをほとんど上述の例と同じように生成していますが、オブジェクト名だけが異なります:

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')

これが logging.conf ファイルです:

[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

出力は、設定ファイルに基づく例とだいたい同じです:

$ 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

この通り、設定ファイルの方法は、主に設定とコードが分かれ、非コーダがロギングプロパティを変えやすくなるという点で、Python コードの方法より少し優れています。

警告

fileConfig() 関数はデフォルト引数 disable_existing_loggers を取り、後方互換性のためにデフォルト値は True になっています。これはあなたの望むものかもしれませんし、そうでないかもしれません。というのは、設定で明示的に指定したクラス (もしくはその親クラス) を除いて、 fileConfig() が呼び出される前に存在した非ルートロガーを無効化してしまうからです。より詳細なことはリファレンスを参照し、望むならこの引数に False を指定してください。

dictConfig() に渡される辞書でも、キー disable_existing_loggers で真偽値を指定することができ、辞書の中で明示的に指定しなかった場合はデフォルトで True と解釈されます。これは上で説明したロガー無効化につながりますが、それを望まないこともあるでしょう - その場合は、明示的にキーを与えて値を False にしてください。

なお、設定ファイルで参照されるクラス名は、logging モジュールに対して相対であるか、通常のインポート機構を使って解決される絶対である値でなければなりません。従って、(logging モジュールに相対な) WatchedFileHandler または (Python インポートパスとして mypackage が使えるとき、パッケージ mypackage のモジュール mymodule で定義されたクラスに) mypackage.mymodule.MyHandler のどちらかが使えます。

Python 3.2 では、ロギングを設定するのに新しく、辞書に設定情報を持たせる手段が導入されました。これは、上で概説した設定ファイルに基づく方法による機能の上位版を提供し、新しいアプリケーションやデプロイにはこのメソッドが推奨されます。Python の辞書を使って設定情報を保持し、辞書は他の用途にも使えるので、設定の選択肢が広がります。例えば、JSON フォーマットの設定ファイルや、YAML 処理機能が使えれば YAML フォーマットのファイルを使って、設定辞書を構成できます。また、もちろん、Python コードで辞書を構成し、ソケットを通して pickle 化された形式を受け取るなど、アプリケーションで意味があるいかなるやり方でも使えます。

以下は、上記と同じ設定を辞書ベースの新しい手法で記載した YAML 形式の例です:

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]

辞書を使ったロギングについて詳細は、 環境設定のための関数 を参照してください。

環境設定が与えられないとどうなるか

ロギング環境設定を与えられないと、ロギングイベントを出力しなければならないのに、イベントを出力するハンドラが見つからないことがあります。

イベントは、 lastResort に格納された「最終手段ハンドラ」を使用して出力されます。この内部的なハンドラはどんなロガーにも関係しておらず、イベント記述メッセージを現在の sys.stderr の値に書く StreamHandler のように動作します (したがって、あらゆるリダイレクトの効果が反映されます)。メッセージに対してフォーマットは行われません - 裸のイベント記述メッセージだけが印刷されます。ハンドラのレベルは WARNING にセットされ、これより重大度が大きなすべてのイベントが出力されます。

バージョン 3.2 で変更: Python 3.2 より前のバージョンでは、振る舞いは以下の通りです:

raiseExceptions が False (製品モード) なら、イベントは黙って捨てられます。

raiseExceptions が True (開発モード) なら、メッセージ 'No handlers could be found for logger X.Y.Z' が一度表示されます。

3.2 より前の動作にするために、lastResort を None に設定することもできます。

ライブラリのためのロギングの設定

ロギングを使うライブラリを開発するときは、ライブラリがどのようにロギングを使うのか、例えば使われているロガーの名前などを、ドキュメントにしておくべきです。ロギングの設定については、いくつか考えておくべきこともあります。使っているアプリケーションがロギングを使っていなくて、ライブラリコードがロギングを呼び出すと、(前の節で解説したように) 重大度 WARNING 以上のイベントが、sys.stderr に表示されます。これが最高のデフォルトの振る舞いと見なされます。

何らかの理由で、ロギング設定がなされていないときにメッセージを表示 させたくない なら、あなたのライブラリのトップレベルロガーに何もしないハンドラを取り付けられます。このハンドラは何も処理しないというだけで、全てのライブラリイベントに対してハンドラが見つかるので、メッセージが表示されることを防げます。ライブラリのユーザがアプリケーションでの使用のためにロギングを設定したら、それはおそらくハンドラを追加する設定でしょうが、そしてレベルが適切に設定されたら、ライブラリコード内でなされたロギングの呼び出しは、通常通りそのハンドラに出力を送るようになります。

何もしないハンドラ NullHandler (Python 3.1 以降) は、 logging パッケージに含まれます。このハンドラのインスタンスを、 (ロギング設定がなされていないときにライブラリのログイベントを sys.stderr に出力させたく ないなら) ライブラリの名前空間で使われるトップレベルロガーに取り付けられます。ライブラリ foo によるすべてのロギングが、 'foo.x', 'foo.x.y' その他に該当する名前のロガーによってなされるなら:

import logging
logging.getLogger('foo').addHandler(logging.NullHandler())

とすれば望んだ効果が得られるでしょう。組織が複数のライブラリを作り出すなら、指定されるロガー名は単に 'foo' ではなく、'orgname.foo' になります。

注釈

あなたのライブラリから ルートロガーへ直接ログを記録しない ことを強く推奨します。代わりに、あなたのライブラリのトップレベルまたはモジュールレベルの __name__ を使うなど、固有で、簡単に識別できる名前を持ったロガーを使ってください。ルートロガーに直接ログを記録することにより、あなたのライブラリを利用するアプリケーション開発者が、ロギングの詳細度 (verbosity) やハンドラを望みのとおりに設定することを困難にしたり、不可能にしてしまいます。

注釈

ライブラリのロガーには、 NullHandler 以外のハンドラを追加しない ことを強く推奨します。これは、ハンドラの設定が、あなたのライブラリを使うアプリケーション開発者にも伝播するからです。アプリケーション開発者は、対象となる聴衆と、そのアプリケーションにどのハンドラが最も適しているかを知っています。ハンドラを 'ボンネットの中で' 加えてしまうと、ユニットテストをして必要に応じたログを送達する能力に干渉しかねません。

ロギングレベル

ログレベルの数値は以下の表のように与えられています。これらは基本的に自分でレベルを定義したい人のためのもので、定義するレベルを既存のレベルの間に位置づけるためには具体的な値が必要になります。もし数値が他のレベルと同じだったら、既存の値は上書きされその名前は失われます。

レベル

数値

CRITICAL

50

ERROR

40

WARNING

30

INFO

20

DEBUG

10

NOTSET

0

レベルはロガーに関連付けることもでき、開発者が設定することも、保存されたログ記録設定を読み込む際に設定することもできます。ロガーに対してログ記録メソッドが呼び出されると、ロガーは自らのレベルとメソッド呼び出しに関連付けられたレベルを比較します。ロガーのレベルがメソッド呼び出しのレベルよりも高い場合、実際のログメッセージは生成されません。これはログ出力の冗長性を制御するための基本的なメカニズムです。

ログ記録されるメッセージは LogRecord クラスのインスタンスとしてエンコードされます。ロガーがあるイベントを実際にログ出力すると決定した場合、ログメッセージから LogRecord インスタンスが生成されます。

ログ記録されるメッセージは、ハンドラ (handlers) を通してディスパッチ機構にかけられます。ハンドラは Handler クラスのサブクラスのインスタンスで、ログ記録された (LogRecord 形式の) メッセージが、そのメッセージの伝達対象となる相手 (エンドユーザ、サポートデスクのスタッフ、システム管理者、開発者) に行き着くようにする役割を持ちます。ハンドラには特定の出力先を意図された LogRecord インスタンスが渡されます。各ロガーは 0 個以上のハンドラを (Logger の addHandler() メソッド) で関連付けることができます。ロガーに直接関連付けられたハンドラに加えて、ロガーの上位にあるロガーすべてに関連付けられたハンドラ がメッセージを処理する際に呼び出されます (ただしロガーの propagate フラグが false 値にセットされている場合を除きます。その場合は、祖先ハンドラへの伝搬はそこで止まります)。

ロガーと同様に、ハンドラは関連付けられたレベルを持つことができます。ハンドラのレベルはロガーのレベルと同じ方法で、フィルタとして働きます。ハンドラがあるイベントを実際に処理すると決定した場合、 emit() メソッドが使われ、メッセージを出力先に送信します。ほとんどのユーザ定義の Handler のサブクラスで、この emit() をオーバライドする必要があるでしょう。

カスタムレベル

独自のレベルを定義することは可能ですが、必須ではなく、実経験上は既存のレベルが選ばれます。しかし、カスタムレベルが必要だと確信するなら、レベルの定義には多大な注意を払うべきで、ライブラリの開発の際、カスタムレベルを定義することはとても悪いアイデア になり得ます。これは、複数のライブラリの作者がみな独自のカスタムレベルを定義すると、与えられた数値が異なるライブラリで異なる意味になりえるため、開発者がこれを制御または解釈するのが難しくなるからです。

便利なハンドラ

基底の Handler クラスに加え、多くの便利なサブクラスが提供されています:

StreamHandler インスタンスは、メッセージをストリーム (ファイル風オブジェクト) に送ります。

FileHandler インスタンスは、メッセージをディスクファイルに送ります。

BaseRotatingHandler は、ある地点でログファイルを循環させるハンドラの基底クラスです。これを直接インスタンス化することは意図されていません。代わりに、 RotatingFileHandler や TimedRotatingFileHandler を使用してください。

RotatingFileHandler インスタンスは、メッセージをディスクファイルに送り、最大ログファイル数とログファイル循環をサポートします。

TimedRotatingFileHandler インスタンスは、メッセージをディスクファイルに送り、ログファイルを特定時間のインターバルで循環します。

SocketHandler インスタンスは、 TCP/IP ソケットにメッセージを送ります。バージョン3.4　から、 Unixドメインソケットもサポートされます。

DatagramHandler インスタンスは UDP ソケットにメッセージを送ります。バージョン 3.4 から、Unix ドメインソケットもサポートされます。

SMTPHandler インスタンスは、メッセージを指示された email アドレスに送ります。

SysLogHandler インスタンスは、メッセージを、必要ならばリモートマシンの、Unix syslog daemon に送ります。

NTEventLogHandler インスタンスは、メッセージを Windows NT/2000/XP イベントログに送ります。

MemoryHandler インスタンスは、メッセージを、特定の基準が満たされる度に流される、メモリ中のバッファに送ります。

HTTPHandler インスタンスは、メッセージを、 GET または POST セマンティクスを使って、HTTP サーバに送ります。

WatchedFileHandler インスタンスは、ロギングする先のファイルを監視します。ファイルが変更されると、そのファイルは閉じられ、ファイル名を使って再び開かれます。このハンドラは Unix 系のシステムにのみ便利です。Windows は、使われている基の機構をサポートしていません。

QueueHandler インスタンスは、 queue モジュールや multiprocessing モジュールなどで実装されているキューにメッセージを送ります。

NullHandler インスタンスは、エラーメッセージについて何もしません。このクラスはライブラリ開発者が、 logging は使いたいが、ライブラリのユーザーが logging の設定をしなかったときに表示されうる 'No handlers could be found for logger XXX' のようなメッセージを回避したいときに使います。詳しくは、 ライブラリのためのロギングの設定 を参照してください。

Added in version 3.1: NullHandler クラス。

Added in version 3.2: QueueHandler クラス。

コア logging パッケージで、 NullHandler, StreamHandler および FileHandler クラスが定義されています。その他のハンドラは、サブモジュールの logging.handlers で定義されています。(環境設定機能のためのサブモジュール、 logging.config もあります。)

ログメッセージは、 Formatter クラスのインスタンスを通してフォーマット化してから表示されます。このインスタンスは、 % 演算子と辞書で使うのに適切なフォーマット文字列で初期化されます。

複数のメッセージを一括してフォーマット化するには、 BufferingFormatter が使えます。(一連の文字列のそれぞれに適用される) フォーマット文字列に加え、ヘッダとトレーラフォーマット文字列も提供されています。

ロガーレベルおよび/またはハンドラレベルに基づくフィルタリングで十分でなければ、 Filter のインスタンスを Logger と Handler インスタンスの両方に (addFilter() を通して) 加えることができます。メッセージの処理を続ける前に、ロガーもハンドラも、全てのフィルタに許可を求めます。フィルタのいずれかが偽値を返したら、メッセージの処理は続けられません。

基本の Filter 機能では、特定のロガー名でのフィルタリングをできます。この機能が使われると、指名されたロガーに送られたメッセージとその子だけがフィルタを通り、その他は落とされます。

ログ記録中に発生する例外

logging パッケージは、ログを生成している間に起こる例外を飲み込むように設計されています。これは、ログ記録イベントを扱っている間に発生するエラー (ログ記録の設定ミス、ネットワークまたは他の同様のエラー) によってログ記録を使用するアプリケーションが早期に終了しないようにするためです。

SystemExit と KeyboardInterrupt 例外は決して飲み込まれません。 Handler サブクラスの emit() メソッドの間に起こる他の例外は、 handleError() メソッドに渡されます。

Handler の handleError() のデフォルト実装は、モジュールレベル変数 raiseExceptions が設定されているかどうかチェックします。設定されているなら、トレースバックが sys.stderr に出力されます。設定されていないなら、例外は飲み込まれます。

注釈

raiseExceptions のデフォルト値は True です。これは、開発の間に起こるどんな例外についても通常は通知してほしいからです。実運用環境では raiseExceptions を False に設定することをお勧めします。

任意のオブジェクトをメッセージに使用する

前の節とそこで挙げた例では、イベントを記録するときに渡されたメッセージが文字列であると仮定していました。しかし、これは唯一の可能性ではありません。メッセージとして任意のオブジェクトを渡すことができます。そして、ロギングシステムがそのオブジェクトを文字列表現に変換する必要があるとき、オブジェクトの __str__() メソッドが呼び出されます。実際、そうしたければ、文字列表現を計算することを完全に避けることができます - 例えば、 SocketHandler は、イベントを pickle してネットワーク上で送信することでログ出力します。

最適化

message 引数の整形は、必要になるまで延期されます。しかしながら、ログ記録メソッドに渡す引数を計算するだけでもコストがかかる場合があります。ロガーが単にイベントを捨てるなら、その計算を避けたいと考えるかもしれません。どうするかを決定するために isEnabledFor() メソッドを呼ぶことができます。このメソッドは引数にレベルを取って、そのレベルの呼び出しに対して Logger がイベントを生成するなら true を返します。このようにコードを書くことができます:

if logger.isEnabledFor(logging.DEBUG):
    logger.debug('Message with %s, %s', expensive_func1(),
                                        expensive_func2())

このようにすると、ロガーの閾値が DEBUG より上に設定されている場合、 expensive_func1 と expensive_func2 の呼び出しは行われません。

注釈

ある種のケースでは、 isEnabledFor() それ自身があなたが期待するよりも高価になる場合があります(たとえば明示的なレベル指定がロガー階層の上位のみに設定されていて、ロガーが深くネストされているような場合です)。そのようなケース(あるいはタイトなループ内でメソッド呼び出しを避けたい場合)は、 isEnabledFor() 結果をローカルにもしくはインスタンス変数としてキャッシュし、メソッドを毎回呼び出すかわりに使えば良いです。そのようなキャッシュ値は、(まったく一般的ではありませんが)ロギング設定がアプリケーション実行中に動的に変更された場合にのみ再計算が必要でしょう。

これ以外にも、どんなログ情報が集められるかについてより正確なコントロールを必要とする、特定のアプリケーションでできる最適化があります。これは、ログ記録の間の不要な処理を避けるためにできることのリストです:

不要な情報

それを避ける方法

呼び出しがどこから行われたかに関する情報。

logging._srcfile を None にする。このことにより sys._getframe() 呼び出しを避けることが出来、PyPy のような環境(sys._getframe() の高速化が出来ない)において高速化の役に立ちます。

スレッド情報。

logging.logThreads を False にする。

現在のプロセスID(os.getpid())

logging.logProcesses を False にする。

マルチプロセスの制御に multiprocessing を使っているときの、現在のプロセス名

logging.logMultiprocessing を False にする。

asyncio を使っているときの、現在の asyncio.Task の名前。

logging.logAsyncioTasks を False に設定する。

また、コア logging モジュールが基本的なハンドラだけを含んでいることに注意してください。 logging.handlers と logging.config をインポートしなければ、余分なメモリを消費することはありません。

その他のリソース

参考

logging モジュール

logging モジュールの API リファレンス。

logging.config モジュール

logging モジュールの環境設定 API です。

logging.handlers モジュール

logging モジュールに含まれる、便利なハンドラです。

ロギングクックブック

Logging クックブック

著者:

Vinay Sajip <vinay_sajip at red-dove dot com>

このページは、過去に有用であるとされていた、logging に関連するいくつものレシピを含んでいます。チュートリアルやリファレンス情報へのリンクについては その他のリソース を参照してください。

複数のモジュールで logging を使う

logging.getLogger('someLogger') の複数回の呼び出しは同じ logger への参照を返します。これは同じ Python インタプリタプロセス上で動いている限り、一つのモジュールの中からに限らず、モジュールをまたいでも当てはまります。同じオブジェクトへの参照という点でも正しいです。さらに、一つのモジュールの中で親 logger を定義して設定し、別のモジュールで子 logger を定義する (ただし設定はしない) ことが可能で、すべての子 logger への呼び出しは親にまで渡されます。まずはメインのモジュールです:

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()')

そして補助モジュール (auxiliary module) がこちらです:

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"')

出力はこのようになります:

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()

複数のスレッドからのロギング

複数スレッドからのロギングでは特別に何かをする必要はありません。次の例はmain (初期) スレッドとそれ以外のスレッドからのロギングの例です:

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()

実行すると、出力は以下のようになるはずです:

   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

予想した通りかもしれませんが、ログ出力が散らばっているのが分かります。もちろん、この手法はより多くのスレッドでも上手くいきます。

複数の handler と formatter

logger は通常の Python オブジェクトです。 addHandler() メソッドは追加されるハンドラの個数について最小値も最大値も定めていません。時にアプリケーションがすべての深刻度のすべてのメッセージをテキストファイルに記録しつつ、同時にエラーやそれ以上のものをコンソールに出力することが役に立ちます。これを実現する方法は、単に適切なハンドラを設定するだけです。アプリケーションコードの中のログ記録の呼び出しは変更されずに残ります。少し前に取り上げた単純なモジュール式の例を少し変えるとこうなります:

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')

'application' 部分のコードは複数の handler について何も気にしていないことに注目してください。変更した箇所は新しい fh という名の handler を追加して設定したところがすべてです。

新しい handler を、異なる深刻度に対する filter と共に生成できることは、アプリケーションを書いてテストを行うときとても助けになります。デバッグ用にたくさんの print 文を使う代わりに logger.debug を使いましょう。あとで消したりコメントアウトしたりしなければならない print 文と違って、logger.debug 命令はソースコードの中にそのまま残しておいて再び必要になるまで休眠させておけます。その時必要になるのはただ logger および/または handler の深刻度の設定をいじることだけです。

複数の出力先にログを出力する

コンソールとファイルに、別々のメッセージ書式で、別々の状況に応じたログ出力を行わせたいとしましょう。例えば DEBUG よりも高いレベルのメッセージはファイルに記録し、INFO 以上のレベルのメッセージはコンソールに出力したいという場合です。また、ファイルにはタイムスタンプを記録し、コンソールには出力しないとします。以下のようにすれば、こうした挙動を実現できます:

import logging

# set up logging to file - see previous section for more details
logging.basicConfig(level=logging.DEBUG,
                    format='%(asctime)s %(name)-12s %(levelname)-8s %(message)s',
                    datefmt='%m-%d %H:%M',
                    filename='/tmp/myapp.log',
                    filemode='w')
# define a Handler which writes INFO messages or higher to the sys.stderr
console = logging.StreamHandler()
console.setLevel(logging.INFO)
# set a format which is simpler for console use
formatter = logging.Formatter('%(name)-12s: %(levelname)-8s %(message)s')
# tell the handler to use this format
console.setFormatter(formatter)
# add the handler to the root logger
logging.getLogger('').addHandler(console)

# Now, we can log to the root logger, or any other logger. First the root...
logging.info('Jackdaws love my big sphinx of quartz.')

# Now, define a couple of other loggers which might represent areas in your
# application:

logger1 = logging.getLogger('myapp.area1')
logger2 = logging.getLogger('myapp.area2')

logger1.debug('Quick zephyrs blow, vexing daft Jim.')
logger1.info('How quickly daft jumping zebras vex.')
logger2.warning('Jail zesty vixen who grabbed pay from quack.')
logger2.error('The five boxing wizards jump quickly.')

これを実行すると、コンソールには以下のように出力されます:

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.

そして、ファイルには以下のように出力されるはずです:

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.

これを見て分かる通り、DEBUG メッセージはファイルだけに出力され、その他のメッセージは両方に出力されます。

この例ではコンソールとファイルのハンドラだけを使っていますが、実際には任意の数のハンドラや組み合わせを使えます。

ここでファイル名として /tmp/myapp.log を選んだということは、一時ファイルの標準的な場所として POSIX システムを想定していることに注意してください。 Windows の場合、ディレクトリが存在し、そのディレクトリに対してファイルを更新するための適切な権限を有することを保証するために、ログファイル向けのディレクトリ名として異なる選択を取る必要があるでしょう。

ログレベルのカスタム処理

しきい値以上のログレベル全てがハンドラによって処理される標準的な処理に対して、ときにはわずかに異なる振る舞いを必要とすることもあるでしょう。そのような場合はフィルタを使う必要があります。以下のような処理が必要なシナリオについて取り上げてみましょう:

深刻度 INFO と WARNING のメッセージを sys.stdout に送る

深刻度 ERROR 以上のメッセージを sys.stderr に送る

深刻度 DEBUG 以上のメッセージをファイル app.log に送る

logging モジュールを下記の JSON によって構成したとしましょう:

{
    "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"
        ]
    }
}

This configuration does almost what we want, except that sys.stdout would show messages of severity ERROR and above as well as INFO and 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 filters section parallel to formatters and handlers:

{
    "filters": {
        "warnings_and_below": {
            "()" : "__main__.filter_maker",
            "level": "WARNING"
        }
    }
}

そして stdout のハンドラに関するセクションにフィルターを追加します:

{
    "stdout": {
        "class": "logging.StreamHandler",
        "level": "INFO",
        "formatter": "simple",
        "stream": "ext://sys.stdout",
        "filters": ["warnings_and_below"]
    }
}

フィルターは単なる関数なので、 filter_maker (ファクトリ関数) は以下のように定義することができます:

def filter_maker(level):
    level = getattr(logging, level)

    def filter(record):
        return record.levelno <= level

    return filter

この関数は引数として与えられた文字列をログレベルの数値に変換し、ログレコード内のログレベルが指定されたレベル以下の場合に True を返す関数を返します。この例では filter_maker をコマンドラインから実行するテストスクリプト main.py で関数が定義されているため、フィルター設定上のモジュール名は __main__ になります。そのためフィルター設定の中では __main__.filter_maker となります。異なるモジュールで関数を定義した場合、この部分を変更する必要があります。

フィルターを追加した main.py の全体像は以下のようになり、これで実行できる状態になりました:

import json
import logging
import logging.config

CONFIG = '''
{
    "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"
        ]
    }
}
'''

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')

これを以下のように実行します:

python main.py 2>stderr.log >stdout.log

すると期待通りの結果を得ることができます:

$ 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

設定サーバの例

ログ記録設定サーバを使うモジュールの例です:

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()

そしてファイル名を受け取ってそのファイルをサーバに送るスクリプトですが、それに先だってバイナリエンコード長を新しいログ記録の設定として先に送っておきます:

#!/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')

ブロックする handler を扱う

ときどき、logging を行っているスレッドをブロックせずに、handler が動くようにしないといけないときがあります。これは Web アプリケーションではよくあることですし、もちろん他のシナリオでも起きる話です。

動作が鈍くなるときの元凶はたいてい、開発者のコントロール外にあるいくつもの理由で (例えば、残念なパフォーマンスのメールやネットワークのインフラ) 、 SMTPHandler: が電子メールを送るのに時間がかかることです。しかし、ほとんどのネットワークをまたぐ handler はブロックする可能性があります: SocketHandler による処理でさえ、裏で DNS への問い合わせというとても遅い処理を行うことがあります (そしてこの問い合わせ処理は、 Python の層より下のあなたの手の届かない、ソケットライブラリの深いところにある可能性もあります)。

解決策の1つは、2パートに分離したアプローチを用いることです。最初のパートは、パフォーマンスが重要なスレッドからアクセスされる、 QueueHandler だけをアタッチした logger です。この logger は単に、十分大きい、あるいは無制限の容量を持ったキューに書き込むだけです。キューへの書き込みは通常すぐに完了しますが、念の為に queue.Full 例外をキャッチする必要があるかもしれません。もしパフォーマンスクリティカルなスレッドを持つライブラリの開発者であるなら、このことを (QueueHandler だけをアタッチした logger についての言及を添えて) ドキュメントに書いておきましょう。

2つ目のパートは QueueHandler の対向として作られた QueueListener です。 QueueListener はとてもシンプルで、キューと handler を渡され、内部で QueueHandler (もしくは他の LogRecord の出力元) から送られた LogRecord をキューから受け取るスレッドを起動します。 LogRecord をキューから取り出して、 handler に渡して処理させます。

分離した QueueListener クラスを持つメリットは、複数の QueueHandler に対して1つのインスタンスで logging できることです。既存の handler のスレッド利用版を使って handler ごとにスレッドを持つよりはずっとリソースにやさしくなります。

この2つのクラスを利用する例です (import は省略):

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()

実行すると次のように出力します:

MainThread: Look out!

注釈

上述の議論は特に同期コードにについてのものではなく、むしろ遅いロギングハンドラについてでしたが、非同期コードやネットワーク、あるいはファイルハンドラからのロギングでさえも (イベントループをブロックしてしまう) 問題につながる可能性があることには注意すべきでしょう。これはいくつかのロギングが asyncio 内部で行われることが理由です。何らかの非同期コードがアプリケーションの中で使われている場合、ロギングには上記のアプローチを使っていかなるブロッキングコードも QueueListener スレッド内だけで実行されるようにしておくことが最も良いでしょう。

バージョン 3.5 で変更: Python 3.5 以前は、 QueueListener クラスは常にキューから受け取ったメッセージを、初期化元となっているそれぞれのハンドラーに受け渡していました。 ( というのも、レベルフィルターリングは別サイド、つまり、キューが満たされている場所で処理されるということが想定されているからです) Python 3.5以降では、キーワードとなる引数 respect_handler_level=True をリスナーのコントラクターに受け渡すことで、この挙動を変更することができるようになっています。これが行われると、各メッセージのレベルをハンドラーのレベルと比較して、そうすることが適切な場合のみ、メッセージをハンドラーに渡します。

ネットワーク越しの logging イベントの送受信

ログイベントをネットワーク越しに送信し、受信端でそれを処理したいとしましょう。 SocketHandler インスタンスを送信端の root logger にアタッチすれば、簡単に実現できます:

import logging, logging.handlers

rootLogger = logging.getLogger('')
rootLogger.setLevel(logging.DEBUG)
socketHandler = logging.handlers.SocketHandler('localhost',
                    logging.handlers.DEFAULT_TCP_LOGGING_PORT)
# don't bother with a formatter, since a socket handler sends the event as
# an unformatted pickle
rootLogger.addHandler(socketHandler)

# Now, we can log to the root logger, or any other logger. First the root...
logging.info('Jackdaws love my big sphinx of quartz.')

# Now, define a couple of other loggers which might represent areas in your
# application:

logger1 = logging.getLogger('myapp.area1')
logger2 = logging.getLogger('myapp.area2')

logger1.debug('Quick zephyrs blow, vexing daft Jim.')
logger1.info('How quickly daft jumping zebras vex.')
logger2.warning('Jail zesty vixen who grabbed pay from quack.')
logger2.error('The five boxing wizards jump quickly.')

受信端では socketserver モジュールを使って受信プログラムを作成しておきます。簡単な実用プログラムを以下に示します:

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()

先にサーバを起動しておき、次にクライアントを起動します。クライアント側では、コンソールには何も出力されません; サーバ側では以下のようなメッセージを目にするはずです:

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.

注意： pickle にはいくつかのシナリオでセキュリティ上の問題があります。これらが影響する場合は、 makePickle() メソッドをオーバーライドし代替シリアライズ手法を実装して、それを使うように上記のスクリプトを修正することもできます。

作成中のロギングソケットのリスナーを実行する

作成中のロギングリスナーを実行するためには、 Supervisor [http://supervisord.org/] のようなプロセス管理ツールを使う必要があるかもしれません。 こちらの Gist [https://gist.github.com/vsajip/4b227eeec43817465ca835ca66f75e2b] は Supervisor を使って上記の機能を実行するための必要最低限のファイルを提供しています。以下のファイルが必要になります:

ファイル

目的

prepare.sh

試験用の環境を準備する Bash スクリプト

supervisor.conf

リスナーとマルチプロセスの web アプリケーションのための設定を含む Supervisor の設定ファイル

ensure_app.sh

Supervisor が上記の設定で実行されていることを保証するための Bash スクリプト

log_listener.py

ログイベントを受信してファイルに記録するソケットリスナープログラム

main.py

リスナーに接続されたソケットを通じてロギングを実行する簡単な web アプリケーション

webapp.json

web アプリケーションのための JSON 設定ファイル

client.py

web アプリケーションを起動するための Python スクリプト

この web アプリケーションは、リクエストを処理する複数のワーカープロセスを起動する web アプリケーションサーバーである Gunicorn [https://gunicorn.org/] を使っています。ここに例として挙げた設定は、複数のワーカーがいかにして互いに衝突することなく同じログファイルに書き込みを行うことができるかを示しています --- ワーカーは全てソケットリスナーを通じてログを書き込むのです。

これらのファイルを試すためには、 POSIX 環境において以下を行なってください:

Download ZIP ボタンを押して Gist [https://gist.github.com/vsajip/4b227eeec43817465ca835ca66f75e2b] を ZIP アーカイブとしてダウンロードしてください。

アーカイブファイルをスクラッチディレクトリに展開してください。

準備のために、スクラッチディレクトリにおいて bash prepare.sh を実行してください。これにより Supervisor 関連のファイルおよびログファイルのための run サブディレクトリ、および bottle, gunicorn そして supervisor がインストールされる仮想環境を含む venv サブディレクトリが生成されます。

bash ensure_app.sh を実行して Supervisor が上記の設定で実行されていることを確認してください。

venv/bin/python client.py を実行して web アプリケーションを起動してください。これによりログにレコードが書き込まれるはずです。

run サブディレクトリにあるログファイルを調べてください。最新のログは、パターン app.log* に一致する名前のファイルにあるはずです。ログは異なるワーカープロセスによって非決定論的な形で並行に処理されるため、特定の決まった順番にはなりません。

リスナーと web アプリケーションは venv/bin/supervisorctl -c supervisor.conf shutdown を実行することでシャットダウンできます。

ありそうもないことですが、テスト環境で設定したポートが別の設定と衝突してしまった場合、設定ファイルを修正する必要があるかもしれません。

コンテキスト情報をログ記録出力に付加する

時にはログ記録出力にログ関数の呼び出し時に渡されたパラメータに加えてコンテキスト情報を含めたいこともあるでしょう。たとえば、ネットワークアプリケーションで、クライアント固有の情報 (例: リモートクライアントの名前、 IP アドレス) もログ記録に残しておきたいと思ったとしましょう。 extra パラメータをこの目的に使うこともできますが、いつでもこの方法で情報を渡すのが便利なやり方とも限りません。また接続ごとに Logger インスタンスを生成する誘惑に駆られるかもしれませんが、生成した Logger インスタンスはガーベジコレクションで回収されないので、これは良いアイデアとは言えません。この例は現実的な問題ではないかもしれませんが、 Logger インスタンスの個数がアプリケーションの中でログ記録が行われるレベルの粒度に依存する場合、 Logger インスタンスの個数が事実上無制限にならないと、管理が難しくなります。

LoggerAdapter を使ったコンテキスト情報の伝達

logging イベントの情報と一緒に出力されるコンテキスト情報を渡す簡単な方法は、 LoggerAdapter を使うことです。このクラスは Logger のように見えるように設計されていて、 debug(), info(), warning(), error(), exception(), critical(), log() の各メソッドを呼び出せるようになっています。これらのメソッドは対応する Logger のメソッドと同じ引数を取るので、二つの型を取り替えて使うことができます。

LoggerAdapter のインスタンスを生成する際には、 Logger インスタンスとコンテキスト情報を収めた辞書風 (dict-like) のオブジェクトを渡します。 LoggerAdapter のログ記録メソッドを呼び出すと、呼び出しをコンストラクタに渡された配下の Logger インスタンスに委譲し、その際コンテキスト情報をその委譲された呼び出しに埋め込みます。 LoggerAdapter のコードから少し抜き出してみます:

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)

LoggerAdapter の process() メソッドがコンテキスト情報をログ出力に加える場所です。そこではログ記録呼び出しのメッセージとキーワード引数が渡され、加工された (可能性のある) それらの情報を配下のロガーへの呼び出しに渡し直します。このメソッドのデフォルト実装ではメッセージは元のままですが、キーワード引数にはコンストラクタに渡された辞書風オブジェクトを値として "extra" キーが挿入されます。もちろん、呼び出し時に "extra" キーワードを使った場合には何事もなかったかのように上書きされます。

"extra" を用いる利点は辞書風オブジェクトの中の値が LogRecord インスタンスの __dict__ にマージされることで、辞書風オブジェクトのキーを知っている Formatter を用意して文字列をカスタマイズするようにできることです。それ以外のメソッドが必要なとき、たとえばコンテキスト情報をメッセージの前や後ろにつなげたい場合には、 LoggerAdapter から process() を望むようにオーバライドしたサブクラスを作ることが必要なだけです。次に挙げるのはこのクラスを使った例で、コンストラクタで使われる「辞書風」オブジェクトにどの振る舞いが必要なのかも示しています:

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

これを次のように使うことができます:

logger = logging.getLogger(__name__)
adapter = CustomAdapter(logger, {'connid': some_conn_id})

これで、この adapter 経由でログした全てのイベントに対して、some_conn_id の値がログメッセージの前に追加されます。

コンテキスト情報を渡すために dict 以外のオブジェクトを使う

LoggerAdapter に渡すのは本物の dict でなくても構いません。 __getitem__ と __iter__ を実装していて logging が辞書のように扱えるクラスのインスタンスを利用することができます。これは (dict の値が固定されるのに対して) 値を動的に生成できるので便利です。

Filter を使ったコンテキスト情報の伝達

ユーザ定義の Filter を使ってログ出力にコンテキスト情報を加えることもできます。 Filter インスタンスは、渡された LogRecords を修正することができます。これにより、適切なフォーマット文字列や必要なら Formatter を使って、出力となる属性を新しく追加することも出来ます。

例えば、web アプリケーションで、処理されるリクエスト (または、少なくともその重要な部分) は、スレッドローカル (threading.local) な変数に保存して、 Filter からアクセスすることで、 LogRecord にリクエストの情報を追加できます。例えば、リモート IP アドレスやリモートユーザのユーザ名にアクセスしたいなら、上述の LoggerAdapter の例のように属性名 'ip' や 'user' を使うといったようにです。その場合、同じフォーマット文字列を使って以下に示すように似たような出力を得られます。これはスクリプトの例です:

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')

実行すると、以下のようになります:

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

contextvars の利用

Python 3.7 以降、 contextvars モジュールは threading と asyncio の両方の処理上のニーズを満たすコンテキストローカルな変数を提供しています。このタイプの変数はスレッドローカルな変数に適しています。以下の例は、マルチスレッド環境において、 いかにして web アプリケーションによって処理されるリクエスト属性のような処理の文脈上の情報とともにログを投入できるかを示します。

説明のため、同じ Python プロセス上で共通のライブラリを使っている独立した複数の web アプリケーションがあるとします。これらのアプリケーションが、クライアントの IP アドレスや HTTP リクエストメソッド、およびクライアントのユーザー名のようなコンテキスト依存の情報を追加情報として含んだ自身のログを、共通のライブラリ (と他のリクエスト処理のためのコード) から各アプリケーションのログファイルへ適切に振り向けるためにはどのようにしたら良いでしょうか？

ここで、ライブラリは以下のコードで模することができるとします:

# 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)

複数の web アプリケーションは2つの簡単なクラス, Request と WebApp, によって模倣することができます。これらは実際のスレッド化された web アプリケーションがどのように動作するかを模擬的にあらわしています - すなわち各リクエストはスレッドで処理される状況です:

# 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()

上記のコードを実行すると、およそ半分のリクエストが app1.log に、残り半分が app2.log にそれぞれ記録され、同時に全てのリクエストが app.log に記録されることがわかるでしょう。それぞれの web アプリケーション固有のログはそれぞれのアプリケーションからのログエントリだけを含み、リクエスト情報が矛盾なくログに表示されている (すなわち、各ダミーリクエストの情報は常にログの行とともに現れる) はずです。このことは以下のシェルコマンドの出力により例示されています:

~/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

ハンドラ内でのコンテキスト情報の付与

Handler はそれぞれ一連のフィルタを独自に持っています。コンテキスト情報を、他のハンドラに漏らすことなく LogRecord に付加したい場合、以下に示すスクリプトのように、直接レコードを編集する代わりに新しい LogRecord を返すフィルタを使うことができます:

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')

複数のプロセスからの単一ファイルへのログ記録

ログ記録はスレッドセーフであり、単一プロセスの複数のスレッドからの単一ファイルへのログ記録はサポート されています が、 複数プロセス からの単一ファイルへのログ記録はサポート されません 。なぜなら、複数のプロセスをまたいで単一のファイルへのアクセスを直列化する標準の方法が Python には存在しないからです。複数のプロセスから単一ファイルへログ記録しなければならないなら、最も良い方法は、すべてのプロセスが SocketHandler に対してログ記録を行い、独立したプロセスとしてソケットサーバを動かすことです。ソケットサーバはソケットから読み取ってファイルにログを書き出します。 (この機能を実行するために、既存のプロセスの 1 つのスレッドを割り当てることもできます) この節 では、このアプローチをさらに詳細に文書化しています。動作するソケット受信プログラムが含まれているので、アプリケーションに組み込むための出発点として使用できるでしょう。

複数のプロセスからファイルへのアクセスを直列化するために multiprocessing モジュール の Lock クラスを使って独自のハンドラを書くことができます。既存の FileHandler とそのサブクラスは現在のところ multiprocessing を利用していませんが、将来は利用するようになるかもしれません。現在のところ multiprocessing モジュールが提供するロック機能はすべてのプラットホームで動作するわけではないことに注意してください (https://bugs.python.org/issue3770 参照)。

別の方法として、 Queue と QueueHandler を使って、マルチプロセスアプリケーションの1つのプロセスに全ての logging イベントを送る事ができます。次の例はこれを行う方法を示します。この例では独立した listener プロセスが他のプロセスから送られた event を受け取り、それを独自の logging 設定にしたがって保存します。この例は実装の方法の1つを示しているだけ (例えば、 listener プロセスを分離する代わりに listener スレッドを使うこともできます) ですが、これは listener とアプリケーション内の他のプロセスで完全に異なる設定を使う例になっているので、各自の要求に応じたコードを書く叩き台になるでしょう:

# 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()

上のスクリプトの亜種で、logging をメインプロセスの別スレッドで行う例:

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()

こちらは特定の logger に設定を適用する例になっています。foo logger は foo サブシステムの中の全てのイベントを mplog-foo.log に保存する特別な handler を持っています。これはメインプロセス側の log 処理で使われ、(logging イベントは worker プロセス側で生成されますが) 各メッセージを適切な出力先に出力します。

concurrent.futures.ProcessPoolExecutorの利用

もし、ワーカープロセスを起動するために concurrent.futures.ProcessPoolExecutor を使いたいのであれば、少し違う方法でキューを作る必要があります。次のような方法の代わりに

queue = multiprocessing.Queue(-1)

次のコードを利用する必要があります

queue = multiprocessing.Manager().Queue(-1)  # also works with the examples above

そして、次のようなワーカー作成コードがあったとすると:

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()

次のように変更します（最初に concurrent.futures をインポートするのを忘れないようにしましょう）:

with concurrent.futures.ProcessPoolExecutor(max_workers=10) as executor:
    for i in range(10):
        executor.submit(worker_process, queue, worker_configurer)

Gunicorn と uWSGI を用いた Web アプリケーションのデプロイ

Gunicorn [https://gunicorn.org/] や uWSGI [https://uwsgi-docs.readthedocs.io/en/latest/] (またはそれに類するもの) を使って Web アプリケーションをデプロイする場合、クライアントのリクエストを処理するために複数のワーカープロセスが作られます。そのような環境では、 web アプリケーションに直接ファイルベースのハンドラを作ることは避けてください。 代わりに、 SocketHandler を使って別のプロセスとして動作するリスナーに web アプリケーションからログを送信するようにしてください。これは Supervisor のようなプロセス管理ツールを使うことで設定できます - 詳しくは 作成中のロギングソケットのリスナーを実行する を参照してください。

ファイルをローテートする

ログファイルがある大きさに達したら、新しいファイルを開いてそこにログを取りたいことがあります。そのファイルをある数だけ残し、その数のファイルが生成されたらファイルを循環し、ファイルの数も大きさも制限したいこともあるでしょう。この利用パターンのために、 logging パッケージは RotatingFileHandler を提供しています:

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)

この結果として、アプリケーションのログ履歴の一部である、6 つに別れたファイルが得られます:

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

最新のファイルはいつでも logging_rotatingfile_example.out で、サイズの上限に達するたびに拡張子 .1 を付けた名前に改名されます。既にあるバックアップファイルはその拡張子がインクリメントされ (.1 が .2 になるなど)、 .6 ファイルは消去されます。

明らかに、ここでは極端な例示のためにファイルの大きさをかなり小さな値に設定しています。実際に使うときは maxBytes を適切な値に設定してください。

別の format スタイルを利用する

logging が Python 標準ライブラリに追加された時、メッセージを動的な内容でフォーマットする唯一の方法は % を使ったフォーマットでした。その後、 Python には新しい文字列フォーマット機構として string.Template (Python 2.4 で追加) と str.format() (Python 2.6 で追加) が加わりました。

logging は (3.2 から) この2つの追加されたフォーマット方法をサポートしています。 Formatter クラスが style という名前のオプションのキーワード引数を受け取ります。このデフォルト値は '%' ですが、他に '{' と '$' が指定可能で、それぞれのフォーマット方法に対応しています。後方互換性はデフォルト値によって維持されていますが、明示的に style 引数を指定することで、 str.format() か string.Template を使った format を指定する事ができます。次の例はこの機能を使ってみています:

>>> 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
>>>

最終的に出力されるログメッセージの format と、各メッセージを生成する部分は完全に独立していることに注意してください。次の例でわかるように、メッセージを生成する部分では % を使い続けています:

>>> 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
>>>

logging の呼び出し (logger.debug() や logger.info() など) は、ログメッセージのために位置引数しか受け取らず、キーワード引数はそれを処理するときのオプションを指定するためだけに使われます。 (例えば、 exc_info キーワード引数を使ってログを取るトレースバック情報を指定したり、 extra キーワード引数を使ってログに付与する追加のコンテキスト情報を指定します。) logging パッケージは内部で % を使って format 文字列と引数をマージしているので、 str.format() や string.Template を使って logging を呼び出す事はできません。既存の logging 呼び出しは %-format を使っているので、後方互換性のためにこの部分を変更することはできません。

しかし、{} や $ を使ってログメッセージをフォーマットする方法はあります。ログメッセージには任意のオブジェクトを format 文字列として渡すことができ、logging パッケージはそのオブジェクトに対して str() を使って実際の format 文字列を生成します。次の2つのクラスを見てください:

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)

どちらのクラスも format 文字列の代わりに利用して、 {} や $ を使って実際のログの "%(message)s", "{message}", "$message" で指定された "message" 部分を生成することができます。これは何かログを取りたいときに常に使うには使いにくいクラス名ですが、 __ (アンダースコア2つ --- gettext.gettext() やその仲間によくエイリアスとして使われるアンダースコア1つと混同しないように) などの使いやすいエイリアスを使うことができます。

上のクラスは Python には含まれませんが、自分のコードにコピペして使うのは簡単です。これらは次の例のようにして利用できます。(上のクラスが wherever というモジュールで定義されていると仮定します):

>>> 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
>>>

上の例ではフォーマットの動作を示すために print() を使っていますが、もちろん実際にこの方法でログを出力するには logger.debug() などを使います。

注意点として、この方法には大きなパフォーマンスのペナルティはありません。実際のフォーマット操作は logging の呼び出し時ではなくて、メッセージが実際に handler によって出力されるときに起こります。(出力されないならフォーマットもされません) そのため、この方法で注意しないといけないのは、追加の括弧が書式文字列だけではなく引数も囲わないといけないことだけです。これは __ が XXXMessage クラスのコンストラクタ呼び出しのシンタックスシュガーでしか無いからです。

次の例のように、 LoggerAdapter を利用して上と似たような効果を実現する方法もあります:

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()

上のスクリプトは Python 3.8 以降では Hello, world! というメッセージをログするはずです。

LogRecord のカスタマイズ

全ての logging イベントは LogRecord のインスタンスとして表現されます。イベントのログが取られて logger のレベルでフィルタされなかった場合、イベントの情報を含む LogRecord が生成され、その logger (と、 propagate が無効になるまでの上位 logger) の handler に渡されます。 Python 3.2 までは、この生成が行われているのは2箇所だけでした:

Logger.makeRecord(): 通常のイベント logging プロセスで呼ばれます。これは LogRecord を直接読んでインスタンスを生成します。

makeLogRecord(): LogRecord に追加される属性を含む辞書を渡して呼び出されます。これはネットワーク越しに (pickle 形式で SocketHandler 経由で、あるいは JSON 形式で HTTPHandler 経由で) 辞書を受け取った場合などに利用されます。

そのために LogRecord で何か特別なことをしたい場合は、次のどちらかをしなければなりません。

Logger.makeRecord() をオーバーライドした独自の Logger のサブクラスを作り、利用したい logger のどれかがインスタンス化される前に、それを setLoggerClass() を使って登録する。

filter() メソッドで必要な特殊な処理を行う Filter を logger か handler に追加する。

最初の方法は、複数の異なるライブラリが別々のことをしようとした場合にうまく行きません。各ライブラリが独自の Logger のサブクラスを登録しようとして、最後に登録されたライブラリが生き残ります。

2つ目の方法はほとんどのケースでうまくいきますが、たとえば LogRecord を特殊化したサブクラスを使うことなどはできません。ライブラリの開発者は利用している logger に適切な filter を設定できますが、新しい logger を作るたびに忘れずに設定しないといけなくなります。 (新しいパッケージやモジュールを追加し、モジュールレベルで次の式を実行することで、新しい logger が作られます)

logger = logging.getLogger(__name__)

これでは考えることが余計に1つ増えてしまうでしょう。開発者は、最も高いレベルのロガーに取り付けられた NullHandler に、フィルタを追加することもできますが、アプリケーション開発者が、より低いレベルに対するライブラリのロガーにハンドラを取り付けた場合、フィルタは呼び出されません --- 従って、そのハンドラからの出力はライブラリ開発者の意図を反映したものにはなりません。

Python 3.2 以降では、 LogRecord の生成は、指定できるファクトリ経由になります。ファクトリは callable で、 setLogRecordFactory() で登録でき、 getLogRecordFactory() で現在のファクトリを取得できます。ファクトリは LogRecord コンストラクタと同じシグネチャで呼び出され、 LogRecord がデフォルトのファクトリとして設定されています。

このアプローチはカスタムのファクトリが LogRecord の生成のすべての面を制御できるようにしています。たとえば、サブクラスを返したり、次のようなパターンを使って単に属性を追加することができます:

old_factory = logging.getLogRecordFactory()

def record_factory(*args, **kwargs):
    record = old_factory(*args, **kwargs)
    record.custom_attribute = 0xdecafbad
    return record

logging.setLogRecordFactory(record_factory)

このアプローチでは複数の異なるライブラリがファクトリをチェインさせて、お互いに同じ属性を上書きしたり、標準で提供されている属性を意図せず上書きしない限りはうまくいきます。しかし、チェインのつながり全てが、全ての logging の操作に対しての実行時のオーバーヘッドになることを念頭に置き、このテクニックは Filter を利用するだけでは望む結果が得られない場合にのみ使うべきです。

Subclassing QueueHandler and QueueListener- a ZeroMQ example

Subclass QueueHandler

QueueHandler のサブクラスを作ってメッセージを他のキュー、例えば ZeroMQ の 'publish' ソケットに送信することができます。下の例では、ソケットを別に作ってそれを handler に ('queue' として) 渡します:

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)

もちろん同じことを別の設計でもできます。socket を作るのに必要な情報を handler に渡す例です:

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()

Subclass QueueListener

QueueListener のサブクラスを作って、メッセージを他のキュー、例えば ZeroMQ の 'subscribe' ソケットから取得する事もできます。サンプルです:

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, '')  # subscribe to everything
        socket.connect(uri)
        super().__init__(socket, *handlers, **kwargs)

    def dequeue(self):
        msg = self.queue.recv_json()
        return logging.makeLogRecord(msg)

Subclassing QueueHandler and QueueListener- a pynng example

In a similar way to the above section, we can implement a listener and handler using pynng [https://pypi.org/project/pynng/], which is a Python binding to NNG [https://nng.nanomsg.org/], billed as a spiritual successor to ZeroMQ. The following snippets illustrate -- you can test them in an environment which has pynng installed. Just for variety, we present the listener first.

Subclass QueueListener

# 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'' subscription matches all topics
        topics = kwargs.pop('topics', None) or b''
        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'')
listener.start()
print('Press Ctrl-C to stop.')
try:
    while True:
        pass
except KeyboardInterrupt:
    interrupted = True
finally:
    listener.stop()

Subclass QueueHandler

# 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)

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:

$ 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)

In the second sender shell:

$ 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)

In the listener shell:

$ 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)

As you can see, the logging from the two sender processes is interleaved in the listener's output.

辞書ベースで構成する例

次の例は辞書を使った logging の構成です。この例は Django プロジェクトのドキュメント [https://docs.djangoproject.com/en/stable/topics/logging/#configuring-logging] から持ってきました。この辞書を dictConfig() に渡して設定を有効にします:

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']
        }
    }
}

この構成方法についてのより詳しい情報は、 Django のドキュメントの 該当のセクション [https://docs.djangoproject.com/en/stable/topics/logging/#configuring-logging] で見ることができます。

rotator と namer を使ってログローテートをカスタマイズする

namer と rotator を定義する方法の例は以下の実行可能なスクリプトに示されています。ここではログファイルを gzip により圧縮する例を示しています:

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}')

このスクリプトを実行すると、6つの新しいファイルが生成され、そのうち5つは圧縮されています:

$ 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

より手の込んだ multiprocessing の例

次の実際に動作する例は、logging を multiprocessing と設定ファイルを使って利用する方法を示しています。設定内容はかなりシンプルですが、より複雑な構成を実際の multiprocessing を利用するシナリオで実装する方法を示しています。

この例では、メインプロセスは listener プロセスといくつかのワーカープロセスを起動します。メイン、listener、ワーカープロセスはそれぞれ分離した設定を持っています (ワーカープロセス群は同じ設定を共有します)。この例から、メインプロセスの logging, ワーカーが QueueHandler でログを送っているところ、listener が利用する QueueListener の実装、複雑な設定、キューから受け取ったイベントを設定された handler に分配する部分を見ることができます。この設定は説明用のものですが、この例を自分のシナリオに適応させることができるでしょう。

これがそのスクリプトです。docstring とコメントで動作を説明しています:

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()

SysLogHandler に送るメッセージに BOM を挿入する

RFC 5424 [https://datatracker.ietf.org/doc/html/rfc5424.html] は syslog デーモンに Unicode メッセージを送る時、次の構造を要求しています: オプショナルなピュア ASCII部分、続けて UTF-8 の Byte Order Mark (BOM)、続けて UTF-8 でエンコードされた Unicode. ( 仕様の該当セクション [https://datatracker.ietf.org/doc/html/rfc5424.html#section-6] を参照)

Python 3.1 で SysLogHandler に、 message に BOM を挿入するコードが追加されました。しかし、そのときの実装が悪くて、 message の先頭に BOM をつけてしまうのでピュアASCII 部分をその前に書くことができませんでした。

この動作は壊れているので、Python 3.2.4 以降では BOM を挿入するコードが、削除されました。書き直されるのではなく削除されたので、 RFC 5424 [https://datatracker.ietf.org/doc/html/rfc5424.html] 準拠の、BOM と、オプションのピュア ASCII部分をBOMの前に、任意の Unicode を BOM の後ろに持つ UTF-8 でエンコードされた message を生成したい場合、次の手順に従う必要があります:

SysLogHandler のインスタンスに、次のような format 文字列を持った Formatter インスタンスをアタッチする:

'ASCII section\ufeffUnicode section'

Unicode のコードポイント U+FEFF は、UTF-8 でエンコードすると BOM -- b'\xef\xbb\xbf' -- になります。

ASCII セクションを好きなプレースホルダに変更する。ただしその部分の置換結果が常に ASCII になるように注意する(UTF-8 でエンコードされてもその部分が変化しないようにする)。

Unicode セクションを任意のプレースホルダに置き換える。この部分を置換したデータに ASCII 外の文字が含まれていても、それは単に UTF-8 でエンコードされるだけです。

フォーマットされた message は SysLogHandler によって UTF-8 でエンコードされます。上のルールに従えば、RFC 5424 準拠のメッセージを生成できます。上のルールに従わない場合、logging は何もエラーを起こしませんが、message は RFC 5424 [https://datatracker.ietf.org/doc/html/rfc5424.html] に準拠しない形で送られるので、syslog デーモン側で何かエラーが起こる可能性があります。

構造化ログを実装する

多くのログメッセージは人間が読むために書かれるため、機械的に処理しにくくなっていますが、場合によっては (複雑な正規表現を使ってログメッセージをパースしなくても) プログラムがパース できる 構造化されたフォーマットでメッセージを出力したい場合があります。 logging パッケージを使うと、これを簡単に実現できます。実現する方法は幾つもありますが、次の例は JSON を使ってイベントを、機械でパースできる形にシリアライズする単純な方法です:

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))

上のスクリプトを実行すると次のように出力されます:

message 1 >>> {"fnum": 123.456, "num": 123, "bar": "baz", "foo": "bar"}

要素の順序は Python のバージョンによって異なることに注意してください。

より特殊な処理が必要な場合、次の例のように、カスタムの JSON エンコーダを作ることができます:

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()

上のスクリプトを実行すると次のように出力されます:

message 1 >>> {"snowman": "\u2603", "set_value": [1, 2, 3]}

要素の順序は Python のバージョンによって異なることに注意してください。

handler を dictConfig() を使ってカスタマイズする

logging handler に特定のカスタマイズを何度もしたい場合で、 dictConfig() を使っているなら、サブクラスを作らなくてもカスタマイズが可能です。例えば、ログファイルの owner を設定したいとします。これは POSIX 環境では shutil.chown() を使って簡単に実現できますが、標準ライブラリの file handler はこの機能を組み込みでサポートしていません。 handler の生成を通常の関数を使ってカスタマイズすることができます:

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)

そして、 dictConfig() に渡される構成設定の中で、この関数を使って logging handler を生成するように指定することができます:

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',
    },
}

この例は説明用のものですが、owner の user と group を pulse に設定しています。これを動くスクリプトに chowntest.py に組み込んでみます:

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')

これを実行するには、 root 権限で実行する必要があるかもしれません:

$ 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

shutil.chown() が追加されたのが Python 3.3 からなので、この例は Python 3.3 を使っています。このアプローチ自体は dictConfig() をサポートした全ての Python バージョン - Python 2.7, 3.2 以降 - で利用できます。 3.3 以前のバージョンでは、オーナーを変更するのに os.chown() を利用する必要があるでしょう。

実際には、handler を生成する関数はプロジェクト内のどこかにあるユーティリティモジュールに置くことになるでしょう。設定の中で直接関数を参照する代わりに:

'()': owned_file_handler,

次のように書くこともできます:

'()': 'ext://project.util.owned_file_handler',

project.util は関数がある実際の場所に置き換えてください。上のスクリプトでは 'ext://__main__.owned_file_handler' で動くはずです。 dictConfig() は ext:// から実際の callable を見つけます。

この例は他のファイルに対する変更を実装する例にもなっています。例えば os.chmod() を使って、同じ方法で POSIX パーミッションを設定できるでしょう。

もちろん、このアプローチは FileHandler 以外の handler 、ローテートする file handler のいずれかやその他の handler にも適用できます。

固有の書式化スタイルをアプリケーション全体で使う

Python 3.2 では、Formatter クラスが style という名前のオプションのキーワード引数を受け取ります。このデフォルト値は後方互換性を維持するために % となっていますが、 { か $ を指定することで、str.format() か string.Template でサポートされているのと同じ書式化のアプローチを採れます。これは最終的に出力されるログメッセージの書式化に影響を与えますが、個々のログメッセージが構築される方法とは完全に直交していることに注意してください。

ロギングの呼び出し (debug(), info() など) はログメッセージのためには位置引数しか取らず、ロギングの呼び出しを処理する方法を決定するためだけにキーワード引数を指定できます (たとえば exc_info キーワード引数はトレースバックの情報をログに含めるかどうかを指定し、 extra キーワード引数はログに付加する追加のコンテキスト情報を指定します)。ロギングパッケージは内部で %-format を使って書式文字列に可変長引数を埋め込んでいるため、 str.format() や string.Template の構文を使って直接ロギングの呼び出しを行うことはできません。既存のコードにおける全てのロギングの呼び出しは %-format 文字列を使っているため、後方互換性を維持する限りこの部分が変更されることはないでしょう。

特定のロガーに関連付ける書式スタイルへの提案がなされてきましたが、そのアプローチは同時に後方互換性の問題にぶち当たります。あらゆる既存のコードはロガーの名前を使っているでしょうし、 % 形式書式化を使っているでしょう。

あらゆるサードパーティのライブラリ、あらゆるあなたのコードの間で相互運用可能なようにロギングを行うには、書式化についての決定は、個々のログ呼び出しのレベルで行う必要があります。これは受け容れ可能な代替書式化スタイルに様々な手段の可能性を広げます。

LogRecord ファクトリを使う

Python 3.2 において、上述した Formatter の変更とともに、 setLogRecordFactory() 関数を使って LogRecord のサブクラスをユーザに指定することを可能にするロギングパッケージの機能拡張がありました。これにより、 getMessage() をオーバライドして た　だ　し　い　ことをする、あなた自身の手による LogRecord のサブクラスをセットすることが出来ます。このメソッドの実装は基底クラスでは msg % args 書式化をし、あなたの代替の書式化の置換が出来る場所ですが、他のコードとの相互運用性を保障するために、全ての書式化スタイルをサポートするよう注意深く行うべきであり、また、%-書式化をデフォルトで認めるべきです。基底クラスの実装がそうしているように、 str(self.msg) 呼び出しもしてください。

さらに詳しい情報は、リファレンスの setLogRecordFactory(), LogRecord を参照してください。

カスタムなメッセージオブジェクトを使う

あなた独自のログメッセージを構築するのに {}- および $- 書式化を使えるようにするための、もうひとつの、おそらくもっと簡単な方法があります。ロギングの際には、あなたはメッセージ書式文字列として、任意のオブジェクトを使えることを(任意のオブジェクトをメッセージに使用する より)思い出してみましょう、そしてロギングパッケージはそのオブジェクトに対して実際の書式文字列を得るために str() を呼び出すことも。以下 2 つのクラスを検討してみましょう:

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)

どちらのクラスも format 文字列の代わりに利用して、 {} や $ を使って実際のログの “%(message)s”, “{message}”, “$message” で指定された "message" 部分を生成することができます。これは何かログを取りたいときに常に使うには使いにくいクラス名ですが、使いやすいようにエイリアスを作れば良いでしょう、 M であるとか _ のような(あるいは地域化のために既に _ を使っているのであれば __ が良いかもしれません)。

このアプローチによる例をお見せします。最初は str.format() を使ってフォーマットする例です:

>>> __ = 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)

2つめは string.Template でフォーマットする例です:

>>> __ = DollarMessage
>>> print(__('Message with $num $what', num=2, what='placeholders'))
Message with 2 placeholders
>>>

注意点として、この方法には大きなパフォーマンスのペナルティはありません。実際のフォーマット操作は logging の呼び出し時ではなくて、メッセージが実際に handler によって出力されるときに起こります。(出力されないならフォーマットもされません) そのため、この方法で注意しないといけないのは、追加の括弧が書式文字列だけではなく引数も囲わないといけないことだけです。これは上記のとおり __ が XXXMessage クラスのコンストラクタ呼び出しのシンタックスシュガーでしか無いからです。

filter を dictConfig() を使ってカスタマイズする

dictConfig() によってフィルタを設定 出来ます が、どうやってそれを行うのかが初見では明快とは言えないでしょう(そのためのこのレシピです)。 Filter のみが唯一標準ライブラリに含まれているだけですし、それは何の要求にも応えてはくれません(ただの基底クラスですから)ので、典型的には filter() メソッドをオーバライドした Filter のサブクラスをあなた自身で定義する必要があります。これをするには、設定辞書内のフィルタ指定部分に、 () キーでそのフィルタを作るのに使われる callable を指定してください(クラスを指定するのが最もわかりやすいですが、 Filter インスタンスを返却する callable を提供することでも出来ます)。以下に完全な例を示します:

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')

どのようにして設定データとして、そのインスタンスを構築する callable をキーワードパラメータの形で渡すのか、をこの例は教えてくれます。上記スクリプトは実行すると、このような出力をします:

changed: hello

設定した通りに動いていますね。

ほかにもいくつか特筆すべき点があります:

設定内で直接その callable を参照出来ない場合(例えばそれが異なるモジュール内にあり、設定辞書のある場所からそれを直接インポート出来ない、など)には、 外部オブジェクトへのアクセス に記述されている ext://... 形式を使えます。例えば、上記例のように MyFilter と指定する代わりに、 'ext://__main__.MyFilter' と記述することが出来ます。

フィルタについてとともに、このテクニックは、カスタムハンドラ、カスタムフォーマッタに対しても同様に使えます。ロギングが設定において、どのようにユーザ定義のオブジェクトをサポートするのかについてのさらなる詳細については、 ユーザ定義オブジェクト と、本クックブックの上の方のレシピ handler を dictConfig() を使ってカスタマイズする を参照してください。

例外の書式化をカスタマイズする

例外の書式化をカスタマイズしたいことがあるでしょう - わかりやすさのために、例外情報がある場合でもログイベントごとに一行に収まることを死守したいと望むとしましょう。フォーマッタのクラスをカスタマイズして、このように出来ます:

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', '') + '|'
        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()

実行してみましょう。このように正確に2行の出力を生成します:

28/01/2015 07:21:23|INFO|Sample message|
28/01/2015 07:21:23|ERROR|ZeroDivisionError: integer division or modulo by zero|'Traceback (most recent call last):\n  File "logtest7.py", line 30, in main\n    x = 1 / 0\nZeroDivisionError: integer division or modulo by zero'|

これは扱いとしては単純過ぎますが、例外情報をどのようにしてあなた好みの書式化出来るかを示しています。さらに特殊なニーズが必要な場合には traceback モジュールが有用です。

ロギングメッセージを喋る

ロギングメッセージを目で見る形式ではなく音で聴く形式として出力したい、という状況があるかもしれません。これはあなたのシステムで text- to-speech (TTS) 機能が利用可能であれば、容易です。それが Python バインディングを持っていなくとも、です。ほとんどの TTS システムはあなたが実行出来るコマンドラインプログラムを持っていて、このことで、 subprocess を使うことでハンドラが呼び出せます。ここでは、TTS コマンドラインプログラムはユーザとの対話を期待せず、完了には時間がかかり、そしてログメッセージの頻度はユーザをメッセージで圧倒してしまうほどには高くはなく、そして並列で喋るよりはメッセージ一つにつき一回喋ることが受け容れられる、としておきます。ここでお見せする実装例では、次が処理される前に一つのメッセージを喋り終わるまで待ち、結果としてほかのハンドラを待たせることになります。 espeak TTS パッケージが手許にあるとして、このアプローチによる短い例はこのようなものです:

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())

実行すれば、女性の声で "Hello" に続き "Goodbye" と喋るはずです。

このアプローチは、もちろんほかの TTS システムにも採用出来ますし、メッセージをコマンドライン経由で外部プログラムに渡せるようなものであれば、ほかのシステムであっても全く同じです。

ロギングメッセージをバッファリングし、条件に従って出力する

メッセージを一次領域に記録し、ある種の特定の状況になった場合にだけ出力したい、ということがあるかもしれません。たとえばある関数内でのデバッグのためのログ出力をしたくても、エラーなしで終了する限りにおいては収集されたデバッグ情報による混雑は喰らいたくはなく、エラーがあった場合にだけエラー出力とともにデバッグ情報を見たいのだ、のようなことがあるでしょう。

このような振る舞いをするロギングをしたい関数に対して、デコレータを用いてこれを行う例をお見せします。それには logging.handlers.MemoryHandler を使います。これにより何か条件を満たすまでロギングイベントを溜め込むことが出来、条件を満たせば溜め込まれたイベントが flushed として他のハンドラ (target のハンドラ)に渡されます。デフォルトでは、 MemoryHandler はそのバッファが一杯になるか、指定された閾値のレベル以上のイベントが起こるとフラッシュされます。何か特別なフラッシュの振る舞いをしたければ、このレシピはさらに特殊化した MemoryHandler とともに利用出来ます。

スクリプト例では、 foo という、単に全てのログレベルについて、 sys.stderr にもどのレベルを出力したのかについて書き出しながら実際のログ出力も行う、という単純な関数を使っています。 foo に真を与えると ERROR と CRITICAL の出力をし、そうでなければ DEBUG, INFO, WARNING だけを出力します。

スクリプトが行うことは単に、 foo を必要とされている特定の条件でのロギングを行うようにするデコレータで修飾することだけです。このデコレータはパラメータとしてロガーを取り、修飾された関数が呼ばれている間だけメモリハンドラをアタッチします。追加のパラメータとして、ターゲットのハンドラ、フラッシュが発生すべきレベル、バッファの容量(バッファされたレコード数)も受け取れます。これらのデフォルトは順に sys.stderr へ書き出す StreamHandler, logging.ERROR, 100 です。

スクリプトはこれです:

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)

実行すればこのような出力になるはずです:

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

見ての通り、実際のログ出力は重要度 ERROR かそれより大きい場合にのみ行っていますが、この場合はそれよりも重要度の低い ERROR よりも前に発生したイベントも出力されます。

当然のことですが、デコレーションはいつものやり方でどうぞ:

@log_if_errors(logger)
def foo(fail=False):
    ...

バッファリングしながらロギングメッセージを email で送信する

ログメッセージをメールで、特に1つのメールにつき複数のログメッセージを、送信する方法を例示するため、 BufferingHandler を継承します。以下の例は、必要に応じて改変することもできますが、 SMTP 経由でログを送信するのに必要な情報をコマンドライン引数で指定してスクリプトを実行できるように簡単なテストハーネスも提供しています (必須の引数およびオプション引数の詳細を見るためには、ダウンロードしたスクリプトを -h 引数をつけて実行してください)。

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()

SMTP サーバーを正しく設定した上でスクリプトを実行すると、指定したアドレス宛てに11通のメールを受け取るでしょう。最初の10通のメールはそれぞれ10個のログメッセージを含み、11通目のメールは2つのログメッセージを含むはずです。これらのログメッセージはスクリプト内で指定された102個のログメッセージから構成されています。

設定によって時刻を UTC(GMT) で書式化する

時刻を UTC でフォーマットしたい場合もあるでしょう。以下に示すように、そのようなフォーマット処理は UTCFormatter のようなクラスを使って行うことができます:

import logging
import time

class UTCFormatter(logging.Formatter):
    converter = time.gmtime

そしてコード中で UTCFormatter を Formatter の代わりに使えます。これを設定を通して行いたい場合、 dictConfig() API を以下の完全な例で示すようなアプローチで使うことが出来ます:

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())

実行すれば、このような出力になるはずです:

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

時刻をローカル時刻と UTC の両方に書式化するのに、それぞれのハンドラにそれぞれフォーマッタを与えています。

ロギングの選択にコンテキストマネージャを使う

一時的にロギングの設定を変えて、作業をした後に設定を戻せると便利なときがあります。こういうときの、ロギングコンテキストの保存と復元をする方法ではコンテキストマネージャを使うのが一番です。以下にあるのがそのためのコンテキストマネージャの簡単な例で、これを使うと、任意にロギングレベルを変更し、コンテキストマネージャのスコープ内で他に影響を及ぼさずロギングハンドラを追加できるようになります:

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

レベル値を指定した場合、コンテキストマネージャがカバーする with ブロックのスコープ内でロガーのレベルがその値に設定されます。ハンドラーを指定した場合、ブロックに入るときにロガーに追加され、ブロックから抜けるときに取り除かれます。ブロックを抜けるときに、自分で追加したハンドラをクローズするようコンテキストマネージャに指示することもできます - そのハンドラがそれ以降必要無いのであればクローズしてしまって構いません。

どのように動作するのかを示すためには、次のコード群を上のコードに付け加えるとよいです:

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.')

最初はロガーのレベルを INFO に設定しているので、メッセージ #1 は現れ、メッセージ #2 は現れません。次に、その後の with ブロック内で一時的にレベルを DEBUG に変更したため、メッセージ #3 が現れます。そのブロックを抜けた後、ロガーのレベルは INFO に復元され、メッセージ #4 は現れません。次の with ブロック内では、再度レベルを DEBUG に設定し、 sys.stdout に書き出すハンドラを追加します。そのおかげでメッセージ #5 が 2 回 (1回は stderr を通して、もう1回は stdout を通して) コンソールに出力されます。 with 文が完了すると、前の状態になるので (メッセージ #1 のように) メッセージ #6 が現れ、(まさにメッセージ #2 のように) メッセージ #7 は現れません。

出来上がったスクリプトを実行すると、結果は次のようになります:

$ 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.

stderr を /dev/null へパイプした状態でもう一度実行すると、次のようになり、これは stdout の方に書かれたメッセージだけが現れています:

$ python logctx.py 2>/dev/null
5. This should appear twice - once on stderr and once on stdout.

stdout を /dev/null へパイプした状態でさらにもう一度実行すると、こうなります:

$ 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.

この場合では、 stdout の方に出力されたメッセージ #5 は予想通り現れません。

もちろんここで説明した手法は、例えば一時的にロギングフィルターを取り付けたりするのに一般化できます。上のコードは Python 2 だけでなく Python 3 でも動くことに注意してください。

CLIアプリケーションスターターテンプレート

ここのサンプルでは次のことを説明します:

コマンドライン引数に応じてログレベルを使用する

複数のファイルに分割されたサブコマンドにディスパッチする。すべて一貫して同じレベルでログ出力を行う

シンプルで最小限の設定で行えるようにする

サービスを停止したり、開始したり、再起動する役割を持ったコマンドラインアプリケーションがあるとします。説明のために、アプリケーションのメインスクリプトが app.py 、個々のコマンドが start.py 、 stop.py 、 restart.py に実装されているものとします。デフォルトは logging.INFO ですが、コマンドライン引数を使ってアプリケーションのログの冗長性を制御したいとします。 app.py は次のコードのようになるでしょう:

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\'' % 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())

start 、 stop 、 restart コマンドは個別のモジュールとして実装されます。次は起動コマンドのソースです:

# 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)

停止コマンドのソースは次の通りです:

# stop.py
import logging

logger = logging.getLogger(__name__)

def command(options):
    n = len(options.names)
    if n == 1:
        plural = ''
        services = '\'%s\'' % options.names[0]
    else:
        plural = 's'
        services = ', '.join('\'%s\'' % 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)

同様に、再起動のコマンドは次の通りです:

# restart.py
import logging

logger = logging.getLogger(__name__)

def command(options):
    n = len(options.names)
    if n == 1:
        plural = ''
        services = '\'%s\'' % options.names[0]
    else:
        plural = 's'
        services = ', '.join('\'%s\'' % 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)

このアプリケーションをデフォルトのログレベルで実行すると、次のような出力が得られます:

$ 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.

最初のワードはログレベルで、次のワードはイベントのログ出力が行われたモジュールまたはパッケージ名です。

ログレベルを変更し、ログに出力する情報を変更できるようにしましょう。もし、より詳細な情報が必要だとしましょう:

$ 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.

あるいは情報を減らしたい場合もあるでしょう:

$ 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

この場合、コマンドはコンソールに何も出力しなくなります。

Qt GUIのログ出力

A question that comes up from time to time is about how to log to a GUI application. The Qt [https://www.qt.io/] framework is a popular cross-platform UI framework with Python bindings using PySide2 [https://pypi.org/project/PySide2/] or PyQt5 [https://pypi.org/project/PyQt5/] libraries.

次のサンプルはQt GUIでログ出力を行うサンプルです。ここではシンプルな QtHandler クラスを作成しています。これは呼び出し可能オブジェクトを受け取ります。これはGUI更新を行うメインスレッドの中で利用されるスロットです。ワーカースレッドも作成し、UI自身からボタンを使ってログを出力したり、バックグラウンドのタスクを行うワーカースレッドからログ出力を行います（ここではランダムな期間にランダムなレベルでメッセージを出しています）。

ワーカースレッドは threading モジュールではなく、Qtの QThread クラスを使っています。これは他の Qt コンポーネントとうまく統合できるように、 QThread を使う必要があるからです。

The code should work with recent releases of any of PySide6, PyQt6, PySide2 or 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.

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()

RFC5424 をサポートする syslog へのロギング

RFC 5424 [https://datatracker.ietf.org/doc/html/rfc5424.html] は 2009 年から始まっていますが、ほとんどの syslog サーバーはデフォルトで、 2001 年から使われている古い RFC 3164 [https://datatracker.ietf.org/doc/html/rfc3164.html] を使って構成されています。2003年に logging モジュールが Python に追加されたとき、モジュールは古い (そして当時唯一存在した) プロトコルをサポートしていました。 RFC5424 は、それが登場して以来、 syslog サーバーにおいて広く使われることがなかったために、 SysLogHandler の機能は更新されてきませんでした。

RFC 5424 は構造化データのサポートなど、いくつかの有用な機能を持っています。その機能をサポートする syslog サーバーへのロギングを可能にする必要がある場合、以下のような派生ハンドラクラスを使うことで実現することができます:

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 = ''.join(parts)
        return f'{version} {asctime} {hostname} {appname} {procid} {msgid} {sdata} {msg}'

上記のコードを完全に理解するには RFC 5424 を熟知する必要があります。また、上記の例とはやや異なる要求を持つこともあるでしょう (たとえば構造化データをログに渡す方法について)。にもかかわらず、上記のコードは特有の要求に対する順応性があります。上記のハンドラにより、構造化データは以下のように渡すことができるでしょう:

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)

ロガーを出力ストリームのように取り扱う方法

書き込み先として file-like オブジェクトを期待するサードパーティの API に接続する必要がある一方で、その API の出力を直接ロガーに送りたいということがときどきあります。これは file-like な API でロガーをラップするクラスを使うことで実現できます。以下はそのようなクラスを例解する短いスクリプトです:

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()

このスクリプトを実行すると、次のように出力されます。

INFO:demo:An INFO message
DEBUG:demo:A DEBUG message

また、 sys.stdout や sys.stderr をリダイレクトするには LoggerWriter を使って以下のようにします:

import sys

sys.stdout = LoggerWriter(logger, logging.INFO)
sys.stderr = LoggerWriter(logger, logging.WARNING)

上記の操作は、必要に応じてロギングを設定した 後に 行うべきです。上記の例では、 basicConfig() の呼び出しが (LoggerWriter インスタンスで上書きされる 前の sys.stderr を使って) 設定を行います。そして、以下のような結果を得るでしょう:

>>> print('Foo')
INFO:demo:Foo
>>> print('Bar', file=sys.stderr)
WARNING:demo:Bar
>>>

言うまでもなく上記の例は basicConfig() で使われている書式にもとづく出力を示していますが、ロギングの設定で異なるフォーマッタを使うことができます。

上記の例では、バッファリングや奪取した書き込み呼び出しのシーケンスの扱いについてはなすがままになっています。たとえば、上記の LoggerWriter の定義で、次のようなコードの断片があったとします。

sys.stderr = LoggerWriter(logger, logging.WARNING)
1 / 0

このスクリプトを実行すると以下のような結果が得られます。

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

見ての通り、この出力は理想的ではありません。なぜならば sys.stderr に書き込みを行うコードが、それぞれが行として分割されるような複数の書き込み呼び出しをしているからです (たとえば最後の3行を見てください)。これを避けるためには、改行があらわれたときにだけログを出力するように、ログをバッファーに蓄えておく必要があります。そのようなわずかな改良をほどこした LoggerWriter の実装を使ってみましょう:

class BufferingLoggerWriter(LoggerWriter):
    def __init__(self, logger, level):
        super().__init__(logger, level)
        self.buffer = ''

    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)

この実装は改行があらわれるまでログをバッファリングし、行全体をログに出力するだけです。このアプローチにより、より適切な出力が得られます:

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

避けるべきパターン

これまでのセクションではログ出力を行うときに必要なこと、考慮すべきことなどを説明してきました。このセクションでは、 役に立たない 利用パターンについて触れます。これは多くの場合避けるべきことです。これらの説明はどこから読んでも構いません。

同じログファイルを何度も開く

Windowsでは同じファイルを何度も開くことができず「このファイルは他のプロセスから利用されています」というエラーが表示されます。しかし、POSIXプラットフォームではエラーがおきることなく、同じファイルを何度も開けます。これは次のように間違って使われる可能性があります。

同じファイルを指すファイルハンドラを1度以上追加する（例えばコピー＆ペーストして書き換え忘れによるエラー)。

異なる名前を持つ、一見異なる2つのファイルを開くが、片方が他方へのシンボリックリンクとなっている。

プロセスをフォークするが、その後親プロセスと子プロセスが同じファイルへの参照を維持する。これは例えば、 multiprocessing モジュールなどを使うと発生する可能性があります。

ファイルを複数回開くことは、 一見 動作しているように見えますが、さまざまな問題を引き起こす可能性があります:

複数のスレッドが同一ファイルに書き出そうとすると、ログ出力が文字化けする可能性があります。ログモジュールは同じハンドラーのインスタンスに対して並列で利用しても正しく動くようになっていますが、同じファイルを参照する2つの異なるハンドラーのインスタンスに対し、2つのスレッドから同時に書き込みをした場合にはそのような保護は働きません。

(たとえばファイルのローテーションの間に) ファイルを削除しようとすると、そのファイルを指す別の参照が残っているために、何のエラーも発しないまま失敗します。これは混乱や不要なデバッグの時間のもととなる可能性があります - ログが思いもしない場所に記録されたり、完全に失われたりします。もしくは移動したと思われていたファイルが残っていたり、ファイルサイズにもとづくローテーションが行われているにもかかわらずファイルサイズが予想外に増加したりすることもあります。

この問題を回避するには 複数のプロセスからの単一ファイルへのログ記録 で紹介したテクニックを使用してください。

ロガーをクラスの属性にするか、パラメータで渡す

ロガーはシングルトンであるため、一般的には意味がなく、これを行う必要が出てくることは滅多にありません。コードからは名前を使って logging.getLogger(name) 経由でロガーインスタンスにアクセスできるため、インスタンスを持って回って、インスタンス属性として保持することは意味がありません。JavaやC#といった他の言語ではよく静的クラス属性にしてます。しかし、Pythonにおいてはこのパターンはクラスではなくモジュールがソフトウェア分解の単位となっているため、無意味です。

ライブラリ内でロガーに NullHandler 以外のハンドラーを追加する

ハンドラーやフォーマッター、フィルターを追加してログ出力をカスタマイズするのはライブラリ開発者ではなく、アプリケーション開発者の責務です。もしあなたがライブラリのメンテナンスをしているのであれば、 NullHandler インスタンス以外のロガーを追加してはいけない、ということを意味します。

大量のロガーを作成する

ロガーはシングルトンであり、スクリプトの実行中に解放されることがないため、大量のロガーを作成すると、メモリが解放されることなく消費されます。ファイルの処理単位やネットワーク接続単位でロガーを作るのではなく、 既存のメカニズム を使ってコンテキスト依存の情報をログに渡し、ロガーはアプリケーション内の説明の単位（通常はモジュールだが、場合によってはそれよりも小さい可能性もある）で作るように制限してください。

その他のリソース

参考

logging モジュール

logging モジュールの API リファレンス。

logging.config モジュール

logging モジュールの環境設定 API です。

logging.handlers モジュール

logging モジュールに含まれる、便利なハンドラです。

基本チュートリアル

上級チュートリアル

正規表現 HOWTO

著者:

A.M. Kuchling <amk@amk.ca>

概要

このドキュメントは re モジュールを使って Python で正規表現を扱うための導入のチュートリアルです。ライブラリレファレンスの正規表現の節よりもやさしい入門ドキュメントを用意しています。

はじめに

正規表現 regular expressions (REs や regexes または regex patterns と呼ばれます) は本質的に小さく、Python 内部に埋め込まれた高度に特化したプログラミング言語で re モジュールから利用可能です。この小さな言語を利用することで、マッチさせたい文字列に適合するような文字列の集合を指定することができます; この集合は英文や e-mail アドレスや TeX コマンドなど、どんなものでも構いません。「この文字列は指定したパターンにマッチしますか?」「このパターンはこの文字列のどの部分にマッチするのですか?」といったことを問い合わせることができます。正規表現を使って文字列を変更したりいろいろな方法で別々の部分に分割したりすることもできます。

正規表現パターンは一連のバイトコードとしてコンパイルされ、C で書かれたマッチングエンジンによって実行されます。より進んだ利用法では、エンジンがどう与えられた正規表現を実行するかに注意することが必要になり、高速に実行できるバイトコードを生成するように正規表現を書くことになります。このドキュメントでは最適化までは扱いません、それにはマッチングエンジンの内部に対する十分な理解が必要だからです。

正規表現言語は相対的に小さく、制限されています、そのため正規表現を使ってあらゆる文字列処理作業を行なえるわけではありません。正規表現を使って行うことのできる作業もあります、ただ表現はとても複雑なものになります。それらの場合では、Python コードを書いた方がいいでしょう; Python コードは念入りに作られた正規表現より遅くなりますが、おそらくより読み易いでしょう。

単純なパターン

まずはできるだけ簡単な正規表現を学ぶことから始めてみましょう。正規表現は文字列の操作に使われるので、ますは最も一般的な作業である文字のマッチングをしてみます。

正規表現の基礎を成す計算機科学 (決定、非決定有限オートマトン) の詳細な説明については, コンパイラ作成に関するテキストブックをどれでもいいので参照して下さい。

文字のマッチング

多くの活字や文字は単純にそれ自身とマッチします。例えば、 test という正規表現は文字列 test に厳密にマッチします。(大文字小文字を区別しないモードでその正規表現が Test や TEST にも同様にマッチすることもできます; 詳しくは後述します。)

この規則には例外が存在します; いくつかの文字は特別な 特殊文字 (metacharacters) で、それら自身にマッチしません。代わりに通常のマッチするものとは違うという合図を出したり、正規表現の一部に対して繰り返したり、意味を変えたりして影響を与えます。このドキュメントの中の多くは様々な特殊文字とそれが何をするかについて論じることになります。

ここに特殊文字の完全な一覧があります; これらの意味はこの HOWTO の残りの部分で説明します。

. ^ $ * + ? { } [ ] \ | ( )

最初に扱う特殊文字は [ と ] です。これらは文字クラスを指定します、文字クラスはマッチしたい文字の集合です。文字は個別にリストにしても構いませんし、二つの文字を '-' でつなげて文字を範囲で与えてもかまいません。たとえば [abc] は a, b, または c のどの文字列にもマッチします; これは [a-c] で同じ文字集合を範囲で表現しても全く同じです。小文字のアルファベットのみにマッチしたい場合、 [a-z] の正規表現をつかうことになるでしょう。

(\ を除く) 特殊文字は文字クラスの内部では有効になりません。例えば、 [akm$] は 'a', 'k', 'm', または '{TX-PL-LABEL}#x27; のいずれかにマッチします; '{TX-PL-LABEL}#x27; は通常は特殊文字ですが、文字クラス内部ではその特別な性質は取り除かれます。

補集合を取る ことで、文字クラス内のリストにない文字に対してマッチさせられます。補集合は、クラスの最初の文字として '^' を含めることで表せます。例えば、 [^5] は '5' 以外の文字にマッチします。キャレットが文字クラス以外の場所に現れた場合は、特別な意味は持ちません。例えば、 [5^] は '5' や '^' にマッチします。

おそらく最も重要な特殊文字はバックスラッシュ \ でしょう。 Python の文字列リテラルのようにバックスラッシュに続けていろいろな文字を入力することでいろいろな特殊シーケンスの合図を送ることができます。また、バックスラッシュはすべての特殊文字をエスケープするのにも利用されます、つまり、特殊文字をマッチさせることができます; 例えば、 [ または \ にマッチさせたい場合、それらをバックスラッシュに続けることで特殊な意味を除きます: \[ または \\ 。

'\' で始まるいくつかの特殊シーケンスは、数字、アルファベット、空白文字以外など、よく使う文字集合を表しています。

一つ例をお見せしましょう: \w は任意の英数字文字にマッチします。バイト列パターンに対しては、これは文字クラス [a-zA-Z0-9_] と等価です。ユニコードパターンに対しては、 \w は unicodedata モジュールで提供されている Unicode データベースで letters としてマークされている全ての文字とマッチします。正規表現のコンパイル時に re.ASCII フラグを与えることにより、 \w を、より制限された定義で使うことが出来ます。

以下に続く特別な文字列のリストは完全ではありません。特殊シーケンスと拡張クラスについてのユニコードパターンの定義についての完全なリストは、標準ライブラリリファレンスの 正規表現の構文 の最後のパートを参照してください。一般的にユニコードバージョンは、ユニコードデータベース内で相応しいカテゴリに属すればマッチします。

\d

任意の十進数とマッチします; これは集合 [0-9] と同じ意味です。

\D

任意の非数字文字とマッチします; これは集合 [^0-9] と同じ意味です。

\s

任意の空白文字とマッチします; これは集合 [ \t\n\r\f\v] と同じ意味です。

\S

任意の非空白文字とマッチします; これは集合 [^ \t\n\r\f\v] と同じ意味です。

\w

任意の英数文字および下線とマッチします; これは、集合 [a-zA-Z0-9_] と同じ意味です。

\W

任意の非英数文字とマッチします; これは集合 [^a-zA-Z0-9_] と同じ意味です。

これらのシーケンスは文字クラス内に含めることができます。例えば、 [\s,.] は空白文字や ',' または '.' にマッチする文字クラスです。

この節での最後の特殊文字は . です。これは改行文字を除く任意の文字にマッチし、さらに改行文字に対してもマッチさせる代替モード (re.DOTALL) があります。 . は「任意の文字」にマッチさせたい場合に利用されます。

繰り返し

さまざまな文字集合をマッチさせることは正規表現で最初にできるようになることで、これは文字列に対するメソッドですぐにできることではありません。しかし、正規表現がより力を発揮する場面がこれだけだとすると、正規表現はあまり先進的とはいえません。正規表現の力をもう一つの能力は、正規表現の一部が何度も繰り返されるようものを指定できることです。

最初にとりあげる繰り返しのための最初の特殊文字は * です。 * は文字リテラル '*' とはマッチしません; その代わりに、前の文字がぴったり1回ではなく0回以上繰り返されるパターンを指定します。

例えば、 ca*t は 'ct' (文字 'a' が 0 個)、 'cat' ('a' が 1 個)、 'caaat' ('a' が 3 個)、などにマッチします。

* のような繰り返しは 貪欲 (greedy) です; 正規表現を繰り返したいとき、マッチングエンジンは可能な限り何度も繰り返そうと試みます。パターンの後ろの部分にマッチしない場合、マッチングエンジンは戻ってより少ない繰り返しを再び試みます。

一歩ずつ例を進めていくとより明確にわかります。正規表現 a[bcd]*b を考えましょう。この正規表現は文字 'a' 、文字クラス [bcd] の 0 個以上の文字、最後に来る 'b' にマッチします。この正規表現が文字列 'abcbd' に対してマッチする流れを想像してみましょう。

ステップ

マッチした文字列

説明

1

a

正規表現の a がマッチ。

2

abcbd

正規表現エンジンが、文字列の終わりに向かってできるだけ遠くまで [bcd]* をマッチさせる。

3

失敗

正規表現エンジンが b でマッチを試みるが、現在の位置が文字列の最後なので失敗。

4

abcb

[bcd]* が一文字少なくマッチするように戻る。

5

失敗

再び b にマッチするか試みるが、現在の位置は最後の文字 'd' 。

6

abc

[bcd]* は bc のみにマッチするように再び戻る。

6

abcb

再び b を試みる。今回の現在位置の文字は 'b' なので成功。

正規表現の終端に達して、 'abcd' にマッチしました。この説明は、マッチングエンジンが最初に到達できるところまで進みマッチしなかった場合、逐次戻って再度残りの正規表現とのマッチを次々と試みること様子を示しています。正規表現エンジンは [bcd]* の 0 回マッチを試すところまで戻り、その後続の正規表現とのマッチに失敗した場合には、エンジンは正規表現と文字列が完全にマッチしないと結論づけることになります。

別の繰り返しのメタ文字には + があり、この特殊文字は 1 回以上の繰り返しにマッチします。 * と + に違いに対しては十分注意して下さい; * は 0 回 以上の繰り返しにマッチするので、繰り返す部分が全くなくても問題ありません。一方で + は少なくとも 1 回 は表われる必要があります。同様の例を使うと ca+t は 'cat' ('a' 1 文字)、 'caaat' ('a' 3 文字)、とマッチし、'ct' とはマッチしません。

繰り返しをあらわす演算子または数量子がさらに2つ存在します。クエスチョンマーク ? は1回または0回の繰り返しにマッチします; これは、何らかの文字やパターンがオプションであることをあらわすと考えられます。例えば、 home-?brew は 'homebrew' と 'home-brew' のいずれかにマッチします。

最も複雑な数量子は {m,n} でしょう。ここで m と n は10進数の整数です。この数量子は繰り返しの回数が最小で m 回、最大で n 回であることを意味します。例えば、 a/{1,3}b は 'a/b', 'a//b', および 'a///b' にマッチします。一方でスラッシュのない 'ab' やスラッシュが4つある 'a////b' にはマッチしません。

m か n のどちらかは省略することができます; その場合は、省略された値は合理的な値が仮定されます。 m の省略は下限は 0 と解釈され、n の省略は上限は無限として解釈されます。

The simplest case {m} matches the preceding item exactly m times. For example, a/{2}b will only match 'a//b'.

還元主義的傾向のある読者は、他の3つの数量子が全てこの表記を使って表現できることに気づくでしょう。 {0,} は * と同じであり、 {1,} は + と等価です。また {0,1} は ? と同じです。とはいえ、簡潔さと読みやすさの観点から、可能であれば *, +, ? を使う方が望ましいです。

正規表現を使う

これまででいくつかの単純な正規表現に触れてきました、実際に Python ではこれらをどう使えばいいのでしょう? re モジュールは正規表現エンジンに対するインターフェースを提供していて、それらを使うことで正規表現をオブジェクトにコンパイルし、マッチを実行することができます。

正規表現をコンパイルする

正規表現はパターンオブジェクトにコンパイルされます、パターンオブジェクトは多くの操作、パターンマッチの検索や文字列の置換の実行などのメソッドを持っています。

>>> import re
>>> p = re.compile('ab*')
>>> p
re.compile('ab*')

re.compile() はいくつかの flags 引数を受け付けることができます、この引数はさまざまな特別な機能を有効にしたり、構文を変化させたりします。利用できる設定に何があるかは後に飛ばすことにして、簡単な例をやることにしましょう:

>>> p = re.compile('ab*', re.IGNORECASE)

正規表現は文字列として re.compile() に渡されます。正規表現は文字列として扱われますが、それは正規表現が Python 言語のコアシステムに含まれないためです、そのため正規表現を表わす特殊な構文はありません。 (正規表現を全く必要としないアプリケーションも存在します、そのためそれらを含めて言語仕様を無駄に大きくする必要はありません) その代わり、 re モジュールは socket や zlib モジュールのような通常の C 拡張モジュールとして Python に含まれています。

正規表現を文字列としておくことで Python 言語はより簡素に保たれていますが、そのため1つの欠点があります、これについては次の節で話題とします。

バックスラッシュ感染症

先に述べたように、正規表現は特別な形式や特殊な文字の特別な意味を意味を除くことを示すためにバックスラッシュ文字 ('\') を利用します。これは Python が文字列リテラルに対して、同じ文字を同じ目的で使うことと衝突します。

\section という文字列 (これは LaTeX ファイルでみかけます) にマッチする正規表現を書きたいとします。どんなプログラムを書くか考え、マッチして欲しい文字列をはじめに考えます。次に、バックスラッシュや他の特殊文字をバックスラッシュに続けて書くことでエスケープしなければいけません、その結果 \\section のような文字列となります。こうしてできた re.compile() に渡す文字列は \\section でなければいけません。しかし、これを Python の文字列リテラルとして扱うにはこの二つのバックスラッシュを 再び エスケープする必要があります。

文字

段階

\section

マッチさせるテキスト

\\section

re.compile() のためのバックスラッシュエスケープ

"\\\\section"

文字列リテラルのためのバックスラッシュエスケープ

要点だけをいえば、リテラルとしてのバックスラッシュにマッチさせるために、正規表現文字列として '\\\\' と書かなければいけません、なぜなら正規表現は \\ であり、通常の Python の文字列リテラルとしてはそれぞれのバックスラッシュは \\ で表現しなければいけないからです。正規表現に関してこのバックスラッシュの繰り返しの機能は、たくさんのバックスラッシュの繰り返しを生むことになり、その結果として作られる文字列は理解することが難しくなります。

この問題の解決策としては正規表現に対しては Python の raw string 記法を使うことです; 'r' を文字列リテラルの先頭に書くことでバックスラッシュは特別扱いされなくなります、つまり "\n" は改行を含む1つの文字からなる文字列であるのに対して、 r"\n" は2つの文字 '\' と 'n' を含む文字列となります。多くの場合 Python コードの中の正規表現はこの raw string 記法を使って書かれます。

それに加えて、正規表現では有効であるものの Python の文字列リテラルとしては有効でない特殊文字のエスケープシーケンスは、現在では DeprecationWarning を引き起こし、最終的には SyntaxError となります。すなわち、そのようなシーケンスは raw string 記法を使うか、バックスラッシュによるエスケープを使わないかぎり無効になることを意味します。

通常の文字列

Raw string

"ab*"

r"ab*"

"\\\\section"

r"\\section"

"\\w+\\s+\\1"

r"\w+\s+\1"

マッチの実行

一旦コンパイルした正規表現を表現するオブジェクトを作成したら、次に何をしますか? パターンオブジェクトはいくつかのメソッドや属性を持っています。ここでは、その中でも最も重要なものについて扱います; 完全なリストは re ドキュメントを参照して下さい。

メソッド/属性

目的

match()

文字列の先頭で正規表現とマッチするか判定します。

search()

文字列を先頭から走査して、正規表現がどこにマッチするか調べます。

findall()

正規表現にマッチする部分文字列を全て探しだしリストとして返します。

finditer()

正規表現にマッチする部分文字列を全て探しだし iterator として返します。

match() と search() はマッチするものが見つからなければ None を返します。成功すればそれらは Match オブジェクト のインスタンスを返します。このオブジェクトにはマッチした情報が含まれます: マッチの開始と終了位置、マッチした部分文字列、など。

You can learn about this by interactively experimenting with the re module.

この HOWTO では例として標準の Python インタプリタを使います。最初に Python インタプリタを起動して、 re モジュールをインポートし、正規表現をコンパイルします:

>>> import re
>>> p = re.compile('[a-z]+')
>>> p
re.compile('[a-z]+')

さて、いろいろな文字列を使って正規表現 [a-z]+ に対するマッチングを試してみましょう。空の文字列は全くマッチしません、なぜなら + は「1 回以上の繰り返し」を意味するからです。この場合では match() は None を返すべきで、インタプタは何も出力しません。明確にするために match() の結果を明示的に出力することもできます:

>>> p.match("")
>>> print(p.match(""))
None

では、今度はマッチするはずの文字列、例えば tempo を試してみましょう。このケースでは、 match() は match object を返すので、後で使うために結果を変数に記憶しておくべきです。

>>> m = p.match('tempo')
>>> m
<re.Match object; span=(0, 5), match='tempo'>

これでマッチした文字列についての情報を Match オブジェクト に問い合わせることが出来ます。 Match オブジェクトインスタンスはいくつかのメソッドと属性も持っていて、最も重要なのは次のものです:

メソッド/属性

目的

group()

正規表現にマッチした文字列を返す

start()

マッチの開始位置を返す

end()

マッチの終了位置を返す

span()

マッチの位置 (start, end) を含むタプルを返す

これらのメソッドを試せば、その意味はすぐに理解できます:

>>> m.group()
'tempo'
>>> m.start(), m.end()
(0, 5)
>>> m.span()
(0, 5)

group() は正規表現でマッチした部分文字列を返します。 start() と end() はそれぞれ、マッチの開始インデクスと終了インデクスを返します。 span() は開始と終了のインデクスを一つのタプルにして返します。 match() メソッドは正規表現が文字列の開始位置でマッチするかどうかだけをチェックするので、 start() は必ずゼロを返します。しかし、 search() メソッドではパターンを文字列全体について走査するので、マッチの開始はゼロにならないかもしれません。

>>> 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)

実際のプログラムでは Match オブジェクト を変数に記憶しておき, その次に None なのか調べるのが一般的なスタイルです。普通このようにします:

p = re.compile( ... )
m = p.match( 'string goes here' )
if m:
    print('Match found: ', m.group())
else:
    print('No match')

あるパターンにマッチするもの全てを返す Pattern インスタンスのメソッドが2つあります。 findall() はマッチした文字列のリストを返します:

>>> p = re.compile(r'\d+')
>>> p.findall('12 drummers drumming, 11 pipers piping, 10 lords a-leaping')
['12', '11', '10']

この例では、文字列リテラルを raw string リテラルにするプレフィックス r が必要です。これは、正規表現とは異なり、通常の "調理済み" 文字列リテラルにおけるエスケープシーケンスは Python では認識されないためであり、現在では DeprecationWarning を引き起こし、最終的には SyntaxError となります。詳しくは バックスラッシュ感染症 を参照してください。

findall() は結果を返す前に完全なリストを必ず生成してしまいます。いっぽう finditer() メソッドは マッチオブジェクト インスタンスのシーケンスを iterator として返します:

>>> 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)

モジュールレベルの関数

パターンオブジェクトを作ってそのメソッドを呼び出す、とする必要は必ずしもありません。 re モジュールはトップレベルの関数として match(), search(), findall(), sub() などを用意しています。これら関数は、対応するメソッドの最初の引数に RE が追加されただけで後は同じで、 None か Match オブジェクト インスタンスを返すのも同じです:

>>> 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 '>

内部的には、これら関数は単にあなたのためにパターンオブジェクトを生成し、対応するメソッドを呼び出すだけのことです。とともに、将来の呼び出しで同じ RE のパースが何度も何度も必要とならないよう、コンパイル済みオブジェクトはキャッシュされます。

これらモジュールレベル関数を使うのと、パターンを自身で作って自身で呼び出すのとでどちらを使うべきでしょう? 正規表現をループの内側で使うならば、プリコンパイルは関数呼び出しを減らします。ループの外側であれば、内部キャッシュのおかげで、どちらでも大差ありません。

コンパイルフラグ

コンパイルフラグは正規表現の動作をいくつかの側面から変更します。フラグは re モジュール下で二つの名前で利用することができます、例えば長い名前は IGNORECASE で短い名前は1文字で I のようになっています。 (1文字形式は Perl のパターン修飾子と同じ形式を使います; 例えば re.VERBOSE の短かい形式は re.X です。) 複数のフラグが OR ビット演算で指定することができます; 例えば re.I | re.M は I と M フラグの両方を設定します。

ここに利用可能なフラグの表があります、それぞれについてのより詳細な説明が後に続きます。

Flag

意味

ASCII, A

\w, \b, \s, そして \d などをそれぞれのプロパティをもつ ASCII 文字だけにマッチさせます。

DOTALL, S

. を改行を含む任意の文字にマッチするようにします。

IGNORECASE, I

大文字小文字を区別しないマッチを行います。

LOCALE, L

ロケールに対応したマッチを行います。

MULTILINE, M

^ や $ の意味を変更し、複数行文字列に対するマッチングを行います。

VERBOSE, X ('X' は 'extended' の 'X')

冗長な正規表現を利用できるようにして、よりきれいで理解しやすくまとめることができます。

re.I

re.IGNORECASE

大文字と小文字を区別しないマッチングを実行します; 文字クラスと文字列リテラルは大文字か小文字かに関係なくパターンにマッチします。例えば、 [A-Z] は小文字のアルファベットにもマッチします。 ASCII フラグによって非 ASCII 文字のマッチングが無効化されていなければ、完全なユニコードのマッチングも可能です。ユニコードで [a-z] または [A-Z] が IGNORECASE フラグとともに使われると、 52個の ASCII 文字に加えて 次の4つの 非 ASCII 文字にマッチします: 'İ' (U+0130, ラテン語の大文字 I で、上部に点がついたもの), 'ı' (U+0131, ラテン語の小文字 i で上部に点がない), 'ſ' (U+017F, ラテン語の小文字 s), 'K' (U+212A, ケルビン記号)。 Spam は 'Spam', 'spam', 'spAM', そして 'ſpam' にマッチします (ただし最後の文字列はユニコードモードの場合のみマッチします)。この「小文字化」は現在のロケールを考慮しません; ただし LOCALE フラグをセットした場合はロケールを考慮します。

re.L

re.LOCALE

\w, \W, \b, \B と小文字大文字の区別を無視したマッチングを、 Unicode データベースではなく現在のロケールに従って行います。

ロケールは言語の違いを考慮したプログラムを書くことを手助けすることを目的とした C ライブラリの機能です。例えば、エンコードされたフランス語のテキストを処理していて、\w+ を使って単語のマッチを行いたいとします。ですがこの場合、 \w はバイトパターンにおいて文字クラス [A-Za-z] だけにマッチします; すなわち é や ç に対応するバイト列にはマッチしません。もしシステムが適切に設定されていて、ロケールがフランス語に設定されていれば、ある C 関数はプログラムに é に対応するバイト列も文字として考慮するべきであると伝えます。正規表現をコンパイルするときに LOCALE フラグを設定すると、コンパイルされたオブジェクトが \w に対してロケールを考慮する C 関数を使うようになります; これにより処理は遅くなりますが、 \w+ を期待通りフランス語の単語にマッチさせることが可能になります。このフラグを Python 3 で利用することは推奨されません。なぜならロケールの仕組みは非常に信頼性が低く、同時にひとつの "文化" しか扱うことができず、また8ビットのロケールでしか正しく動作しないからです。Python 3 ではユニコード (文字列の) パターンに対してユニコードのマッチングがデフォルトで有効化されており、これにより異なるロケールまたは言語を同時に扱うことができます。

re.M

re.MULTILINE

(^ と $ についてはまだ説明していません; これらは さらなる特殊文字 の節で説明します。)

通常 ^ は文字列の先頭にマッチし、 $ は文字列の末尾と文字列の末尾に改行(があれば)その直前にマッチします。このフラグが指定されると、 ^ は文字列の先頭と文字列の中の改行に続く各行の先頭にマッチします。同様に $ 特殊文字は文字列の末尾と各行の末尾(各改行の直前)のどちらにもマッチします。

re.S

re.DOTALL

特別な文字 '.' を改行を含む全ての任意の文字とマッチするようにします; このフラグが無しでは、 '.' は改行 以外 の全てにマッチします。

re.A

re.ASCII

\w, \W, \b, \B, \s, \S が、完全な Unicode マッチングではなく、ASCII のみのマッチングをするようにします。これは Unicode パターンにのみ意味があり、byte パターンには無視されます。

re.X

re.VERBOSE

このフラグはより柔軟な形式で正規表現を読み易く書けるようにします。このフラグを指定すると、正規表現の中の空白は無視されます、ただし、文字クラス内やエスケープされていないバックスラッシュに続く空白の場合は例外として無視されません; これによって正規表現をまとめたり、インデントしてより明確にすることができます。このフラグはさらにエンジンが無視するコメントを追加することもできます; コメントは '#' で示します、これは文字クラスやエスケープされていないバックスラッシュに続くものであってはいけません。

例えば、ここに re.VERBOSE を利用した正規表現があります; 読み易いと思いませんか?

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)

冗長な表現を利用しない設定の場合、正規表現はこうなります:

charref = re.compile("&#(0[0-7]+"
                     "|[0-9]+"
                     "|x[0-9a-fA-F]+);")

上の例では、Python の文字列リテラルの自動結合によって正規表現を小さな部分に分割しています、それでも re.VERBOSE を使った場合に比べるとまだ難しくなっています。

パターンの能力をさらに

ここまでで、正規表現の機能のほんの一部を扱ってきました。この節では、新たにいくつかの特殊文字とグループを使ってマッチしたテキストの一部をどう取得するかについて扱います。

さらなる特殊文字

これまでで、まだ扱っていない特殊文字がいくつかありました。そのほとんどをこの節で扱っていきます。

残りの特殊文字の内いくつかは ゼロ幅アサーション zero-width-assertions に関するものです。これらは文字列に対してエンジンを進めません; 文字列を全く利用しない代わりに、単純に成功か失敗かを利用します。例えば、 \b は現在位置が単語の境界であることを示します; \b によってエンジンの読んでいる位置は全く変化しません。つまり、これはゼロ幅アサーションは繰り返し使うことがありません、一度ある位置でマッチしたら、明らかに無限回マッチできます。

|

代替 (alternation) または "or" 演算子です。 A と B が正規表現の場合、 A|B は A と B のどちらかにマッチするような文字列にマッチします。複数の文字からなる文字列による代替処理が適切に動作するために、 | の優先度は非常に低く設定されています。 Crow|Servo は 'Crow' か 'Servo' のどちらかにマッチするパターンであり、 「'Cro' に続いて 'w' または 'S' があり、さらに 'ervo' が続く」という意味ではありません。

リテラル '|' にマッチするには、 \| を利用するか、 [|] のように文字クラス内に収めて下さい。

^

行の先頭にマッチします。 MULTILINE フラグが設定されない場合には、文字列の先頭にのみマッチします。 MULTILINE モードでは文字列内の各改行の直後にマッチします。

例えば、行の先頭の From にのみマッチさせたい場合には ^From 正規表現を利用します。

>>> print(re.search('^From', 'From Here to Eternity'))
<re.Match object; span=(0, 4), match='From'>
>>> print(re.search('^From', 'Reciting From Memory'))
None

リテラル '^' にマッチするには \^ を利用してください。

$

行の末尾にマッチします、行の末尾は文字列の末尾と改行文字の直前として定義されます。

>>> 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='}'>

リテラル '$' にマッチするには、 \$ を利用するか、 [$] のように文字クラス内に収めて下さい。

\A

文字列の先頭にのみマッチします。 MULTILINE モードでない場合には \A と ^ は実質的に同じです。 MULTILINE モードでのこれらの違いは: \A は依然として文字列の先頭にのみマッチしますが、 ^ は文字列内に改行文字に続く部分があればそこにマッチすることです。

\Z

文字列の末尾でのみマッチします。

\b

単語の境界。これはゼロ幅アサーションで、単語の始まりか終わりにのみマッチします。単語は英数文字のシーケンスとして定義されます、つまり単語の終わりは空白か非英数文字として表われます。

以下の例では class がそのものの単語のときのみマッチします; 別の単語内に含まれている場合はマッチしません。

>>> 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

この特殊シーケンスを利用するときには二つの微妙な点を心にとめておく必要があります。まずひとつめは Python の文字列リテラルと表現の間の最悪の衝突を引き起すことです。Python の文字列リテラルでは \b は ASCII 値8のバックスペース文字です。raw string を利用していない場合、Python は \b をバックスペースに変換し、正規表現は期待するものとマッチしなくなります。以下の例はさきほどと同じ正規表現のように見えますが、正規表現文字列の前の 'r' が省略されています。

>>> 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'>

ふたつめはこのアサーションが利用できない文字列クラスの内部では Python の文字列リテラルとの互換性のために、 \b はバックスペース文字を表わすことになるということです。

\B

別のゼロ幅アサーションで、 \b と逆で、現在の位置が単語の境界でないときにのみマッチします。

グルーピング

正規表現にマッチするかどうかだけでなく、より多くの情報を得なければいけない場合は多々あります。正規表現はしばしば、正規表現をいくつかのサブグループに分けて興味ある部分にマッチするようにして、文字列を分割するのに使われます。例えば、RFC-822 ヘッダ行は ':' を挟んでこのようにヘッダ名と値に分割されます:

From: author@example.com
User-Agent: Thunderbird 1.5.0.9 (X11/20061227)
MIME-Version: 1.0
To: editor@example.com

これはヘッダ全体にマッチし、そしてヘッダ名にマッチするグループとヘッダの値にマッチする別のグループを持つように正規表現を書くことで扱うことができます。

グループはメタ文字 '(' と ')' であらわされます。 '(' と ')' は数式における意味とほぼ同じ意味を持っています; その中に含まれる表現をひとまとまりにし、それらに対して *, +, ?, または {m,n} のような数量子を使った繰り返しを表現することもできます。例えば、 (ab)* は ab の0回以上の繰り返しにマッチします。

>>> p = re.compile('(ab)*')
>>> print(p.match('ababababab').span())
(0, 10)

'(', ')' で指示されたグループは、マッチしたテキスト開始と終了位置もキャプチャします; group(), start(), end(), span() に引数を与えて取り出せます。グループはゼロ始まりの数値です。グループ 0 は常に使えます; それは RE でマッチした全体で、 Match オブジェクト メソッドの全てはグループ 0 をデフォルト引数にしています。マッチするテキストの範囲をキャプチャしないグループの書き方はのちほど見ることにします。

>>> p = re.compile('(a)b')
>>> m = p.match('ab')
>>> m.group()
'ab'
>>> m.group(0)
'ab'

サブグループは左から右へ1づつ番号付けされます。グループはネストしてもかまいません; 番号を決めるには、単に開き括弧を左から右へ数え上げます。

>>> p = re.compile('(a(b)c)d')
>>> m = p.match('abcd')
>>> m.group(0)
'abcd'
>>> m.group(1)
'abc'
>>> m.group(2)
'b'

group() には一回に複数の引数を渡してもかまいません、その場合にはそれらのグループに対応する値を含むタプルを返します。

>>> m.group(2,1,2)
('b', 'abc', 'b')

groups() メソッドは 1 から全てのサブグループの文字列を含むタプルを返します。:

>>> m.groups()
('abc', 'b')

パターン中で後方参照を利用することで、前に取り出されたグループが文字列の中の現在位置で見つかるように指定できます。例えば、\1 はグループ1の内容が現在位置で見つかった場合成功し、それ以外の場合に失敗します。Python の文字列リテラルでもバックスラッシュに続く数字は任意の文字を文字列に含めるために使われるということを心に留めておいて下さい、そのため正規表現で後方参照を含む場合には raw string を必ず利用して下さい。

例えば、以下の正規表現は二重になった単語を検出します。

>>> p = re.compile(r'\b(\w+)\s+\1\b')
>>> p.search('Paris in the the spring').group()
'the the'

このような後方参照は文字列を検索するだけの用途では多くの場合役に立ちません。--- このように繰り返されるテキストフォーマットは少数です。--- しかし、文字列の置換をする場合には とても 有効であることに気づくでしょう。

取り出さないグループと名前つきグループ

念入りに作られた正規表現は多くのグループを利用します、その利用法には対象となる部分文字列を取り出す、正規表現自身をグループ化したり構造化する、という二つの方法があります。複雑な正規表現では、グループ番号を追っていくことは困難になっていきます。この問題の解決を助ける二つの機能があります。その両方が正規表現を拡張するための一般的な構文を利用します、まずはそれらをみてみましょう。

Perl 5 は標準正規表現にパワフルな拡張を加えたことでよく知られています。それらの新しい機能のために Perl 開発者たちは、Perl正規表現と標準正規表現との混乱を招く違いなしには、新たな一文字メタキャラクタも \ ではじまる新たな特殊シーケンスもどちらも選択出来ませんでした。たとえば彼らがもし & を新たなメタキャラクタとして選んでいたら、 & が通常文字とみなされていた古い正規表現は \& や [&] のように書くことでエスケープされなければならなかったでしょう。

解決策として Perl 開発者が選んだものは (?...) を正規表現構文として利用することでした。括弧の直後の ? は構文エラーとなります、これは ? で繰り返す対象がないためです、そのためこれは互換性の問題を持ち込みません。 ? の直後の文字はどの拡張が利用されるかを示しています、つまり、 (?=foo) は一つの拡張を利用したもの (肯定先読みアサーション) となり、 (?:foo) は別の拡張を利用した表現(foo を含む取り込まないグループ)となります。

Python は Perl の拡張のいくつかをサポートし、また、Perl の拡張に一つ拡張を加えています。クエスチョンマークに続く最初の文字が P のものは、そうです、Python 固有の拡張です。

一般化された拡張構文についてはわかりましたので、いよいよ複雑な正規表現内でのグループの扱いを単純化する機能に話を戻しましょう。

ときとしてあなたは、正規表現の一部として使いたいけれども、その内容を取り出すことに興味がないようなグループを記述する必要に迫られます。このためには、取り出さないグループ: (?:...) を使います。 ... 部分は任意の正規表現です。

>>> m = re.match("([abc])+", "abc")
>>> m.groups()
('c',)
>>> m = re.match("(?:[abc])+", "abc")
>>> m.groups()
()

マッチしたグループの内容を取得しないということを除けば、取り込まないグループは厳密に取り込むグループと同様に振る舞います; この中に何を入れてもかまいません、 * のような繰り返しの特殊文字で繰り返したり、他のグループ (取り込むまたは取り込まない) の入れ子にすることもでいます。 (?:...) は特に、既にあるパターンを変更する際に便利です、なぜなら他の番号づけ新しいグループを変更することなく新しいグループを追加することができます。取り込むグループと取り込まないグループで検索のパフォーマンスに差がないことにも触れておくべきことです; どちらも同じ速度で動作します。

より重要な機能は名前つきグループです: 番号で参照する代わりに、グループに対して名前で参照できます。

名前つきグループのための構文は、 Python 固有拡張の一つ: (?P<name>...) を使います。 name は、もちろん、グループの名前です。名前つきグループは取り込むグループと完全に同じに振る舞い、加えて名前が関連付けられます。 Match オブジェクト の取りこむグループを扱うメソッドは全て、番号によるグループ参照のための整数、名前によるグループ参照のための文字列、ともに許容しています。名前つきグループにも番号が振られますので、グループについての情報を、2つの方法で取り出せます:

>>> p = re.compile(r'(?P<word>\b\w+\b)')
>>> m = p.search( '(((( Lots of punctuation )))' )
>>> m.group('word')
'Lots'
>>> m.group(1)
'Lots'

さらに、名前付きのグループを groupdict() を使って辞書として取り出すこともできます:

>>> m = re.match(r'(?P<first>\w+) (?P<last>\w+)', 'Jane Doe')
>>> m.groupdict()
{'first': 'Jane', 'last': 'Doe'}

名前つきグループは、番号を覚える代わりに簡単に覚えられる名前で管理できるため、便利です。以下は imaplib モジュールで使われている正規表現の例です:

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'"')

取得する番号9を覚えるよりも、 m.group('zonem') で取得した方が明らかに簡単にすみます。

後方参照のための構文 (...)\1 はグループ番号への参照となっています。グループ番号の代わりに、グループ名を利用する変種があるのは当然でしょう。これはもう一つの Python 拡張です: (?P=name) は、 name という名前のグループの内容が、現在の位置で再びマッチすることを示しています。同じ単語が2つ連なっているのを見つける正規表現 \b(\w+)\s+\1\b は \b(?P<word>\w+)\s+(?P=word)\b のように書けます:

>>> p = re.compile(r'\b(?P<word>\w+)\s+(?P=word)\b')
>>> p.search('Paris in the the spring').group()
'the the'

先読みアサーション (Lookahead Assertions)

他のゼロ幅アサーションは先読みアサーションです。先読みアサーションは肯定、否定の両方の形式が利用可能です、これを見てください:

(?=...)

肯定先読みアサーション。 ... で表わす正規表現が現在位置でマッチすれば成功し、それ以外の場合失敗します。しかし、表現が試行された場合でもエンジンは先に進みません; パターンの残りの部分はアサーションの開始時点から右に試行します。

(?!...)

否定先読みアサーション。これは肯定アサーションの逆で、正規表現が文字列の現在位置にマッチ しなかった 場合に成功します。

より具体的にするため、先読みが便利な場合をみてみましょう。ファイル名にマッチし、 . で分けられた基本部分と拡張子に分離する単純なパターンを考えましょう。例えば、 news.rc は news が基本部分で rc がファイル名の拡張子です。

マッチするパターンはとても単純です:

.*[.].*$

. はメタキャラクタですので特別に扱わなければなりませんから、文字クラス内に入れて、そのものとだけマッチするようにしていることに注目です。末尾の $ にも注目してください; これは残り全ての文字列が拡張子に含まれるべきであることを保障するために追加しています。この正規表現は foo.bar, autoexec.bat, sendmail.cf, printers.conf にマッチします。

さて、問題を少し複雑にしてみましょう; 拡張子が bat でないファイル名にマッチしたい場合はどうでしょう？間違った試み:

.*[.][^b].*$ この最初の bat を除く試みは、最初の文字が b でないことを要求します。これは誤っています、なぜなら foo.bar にもマッチしないからです。

.*[.]([^b]..|.[^a].|..[^t])$

正規表現が混乱してきました。最初の解決策を取り繕って、以下の場合に合わせることを要求しています: 拡張子の最初の文字は b でなく; 二番目の文字は a でなく; 三番目の文字は t でない。これは foo.bar を受け付けますが、 autoexec.bat は拒否します。しかし、三文字の拡張子を要求し、 sendmail.cf のような二文字の拡張子を受け付けません。これを修正するのにパターンを再び複雑にすることになります。

.*[.]([^b].?.?|.[^a]?.?|..?[^t]?)$

三番目の試みでは、 sendmail.cf のように三文字より短い拡張子とマッチするために第二第三の文字を全てオプションにしています。

パターンはさらに複雑さを増し、読みにくく、理解が難しくなりました。より悪いことに、問題が bat と exe 両方を拡張子から除きたい場合に変わった場合、パターンはより複雑で混乱しやすいものになります。

否定先読みはこの混乱全てを取り除きます:

.*[.](?!bat$)[^.]*$ 否定先読みは以下を意味します: この位置で拡張子 bat にマッチしない場合、残りのパターンが試行されます; もし bat$ にマッチすればパターン全体が失敗します。$ を続けることで、sample.batch にように bat で始まる拡張子を許容することを保証しています。このパターンで [^.]* を使うことで、ファイル名に複数のドットがあったときにも上手くいくようになります。

他のファイル名の拡張子を除くことも簡単です; 単純にアサーション内に拡張子を代替 (or) で加えます。以下のパターンは bat や exe のどちらかで終わるファイル名を除外します:

.*[.](?!bat$|exe$)[^.]*$

文字列を変更する

ここまででは単純に静的な文字列に対する検索を実行してきました。正規表現は文字列を様々な方法で変更するのにもよく使われます。変更には以下のパターンメソッドが利用されます:

メソッド/属性

目的

split()

文字列をリストに分割する、正規表現がマッチした全ての場所で分割を行う

sub()

正規表現にマッチした全ての文字列を発見し、別の文字列に置き換えます

subn()

sub() と同じことをしますが、新しい文字列と置き換えの回数を返します

文字列の分割

split() メソッドは文字列を正規表現にマッチした場所で分割し、リストで返却します。文字列の split() メソッドに似てはいますが、もっとずっと一般化したデリミタで分割出来ます; 文字列の split() メソッドは単に空白文字か固定文字列で分割出来るだけです。ご想像通り、モジュールレベルの re.split() 関数もあります。

.split(string[, maxsplit=0])

string を正規表現のマッチで分割します。正規表現内に取り込むための括弧が利用されている場合、その内容も結果のリストの一部として返されます。 maxsplit が非ゼロの場合、最大で maxsplit の分割が実行されます。

maxsplit に値を渡すことで、分割される回数を制限することができます。 maxsplit が非ゼロの場合、最大で maxsplit の分割が行なわれ、文字列の残りがリストの最終要素として返されます。以下の例では、デリミタは任意の英数文字のシーケンスです。

>>> 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', '']
>>> p.split('This is a test, short and sweet, of split().', 3)
['This', 'is', 'a', 'test, short and sweet, of split().']

興味の対象がデリミタの間のテキストだけでなく、デリミタが何なのかということを知りたい場合はよくあります。取りこみ用の括弧を正規表現に使った場合、その値もリストの一部として返されます。以下の呼び出しを比較してみましょう:

>>> p = re.compile(r'\W+')
>>> p2 = re.compile(r'(\W+)')
>>> p.split('This... is a test.')
['This', 'is', 'a', 'test', '']
>>> p2.split('This... is a test.')
['This', '... ', 'is', ' ', 'a', ' ', 'test', '.', '']

モジュールレベル関数 re.split() は最初の引数に利用する正規表現を追加しますが、それ以外は同じです。

>>> re.split(r'[\W]+', 'Words, words, words.')
['Words', 'words', 'words', '']
>>> re.split(r'([\W]+)', 'Words, words, words.')
['Words', ', ', 'words', ', ', 'words', '.', '']
>>> re.split(r'[\W]+', 'Words, words, words.', 1)
['Words', 'words, words.']

検索と置換

もう一つのよくある作業は、パターンにマッチする全ての文字列を探し、異なる文字列に置換します。 sub() メソッドは置換する値をとります、文字列と関数の両方をとることができ、文字列を処理します。

.sub(replacement, string[, count=0])

string 内で最も長く、他の部分と重複するところがない正規表現を replacement に置換した文字列を返します。パターンが見つからなかった場合 string は変更されずに返されます。

オプション引数 count はパターンの出現の最大置換回数です; count は非負の整数でなければいけません。デフォルト値 0 は全ての出現で置換することを意味します。

ここに sub() メソッドを使った単純な例があります。これは色の名前を colour に置換します:

>>> 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'

subn() メソッドも同じ働きをしますが、新しい文字列と置換の実行回数を含む 2-タプルを返します:

>>> 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)

空文字列とのマッチは、直前の空文字列とマッチした部分と隣接していない場合にのみ置換されます。

>>> p = re.compile('x*')
>>> p.sub('-', 'abxd')
'-a-b--d-'

replacement が文字列の場合、文字列内のバックスラッシュエスケープは処理されます。つまり、\n は改行文字に \r はキャリッジリターンに、等となります。\& のような未知のエスケープシーケンスはそのまま残されます。\6 のような後方参照は正規表現内の対応するグループにマッチする文字列に置換されます。これを使うことで元のテキストの一部を、置換後の文字列に組み込むことができます。

この例は単語 section に続く { と } で閉じられた文字列にマッチし、 section を subsection に変更します:

>>> p = re.compile('section{ ( [^}]* ) }', re.VERBOSE)
>>> p.sub(r'subsection{\1}','section{First} section{second}')
'subsection{First} subsection{second}'

(?P<name>...) 構文で定義された名前つきグループを参照するための構文もあります。 \g<name> は name で名前づけされたグループにマッチする文字列を利用し、 \g<number> は対応するグループ番号を利用します。つまり \g<2> は \2 と等価ですが、 \g<2>0 のような置換文字列に対しては明確に異なります。 (\20 はグループ番号20への参照と解釈され、グループ2の後にリテラル文字 '0' が続くとは解釈されません。) 以下に示す置換は全て等価ですが、これらは文字列置換に全部で3種の変種を利用しています。

>>> 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}'

より細かな制御を手中にするために replacement として関数を使うことが出来ます。 replacement が関数であれば、その関数は重なり合わない pattern の発生のたびに呼び出されます。それぞれの呼び出しで、マッチした Match オブジェクト が引数として渡されるので、望みの置換と返却のためにこの情報を利用出来ます。

続く例では、置換関数は十進数文字列を十六進数文字列に変換しています:

>>> 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.'

モジュールレベルの re.sub() 関数を使うときには、パターンが最初の引数として渡されます。パターンはオブジェクトや文字列をとります; 正規表現フラグを指定する必要がある場合、パターンオブジェクトを最初の引数として使うか、修飾子を埋め込んだパターン文字列を使うかしなければいけません、例えば sub("(?i)b+", "x", "bbbb BBBB") は 'x x' を返します。

よくある問題

正規表現はいくつかの応用に対して強力なツールですが、いくつかの部分でそれらの振る舞いは直感的ではなく、期待通りに振る舞わないことがあります。この節では最もよくある落とし穴を指摘します。

文字列メソッドを利用する

いくつかの場合 re モジュールを利用することは間違いである場合があります。固定文字列や単一の文字クラスにマッチさせる場合や、 IGNORECASE フラグのような re の機能を利用しない場合、正規表現の全ての能力は必要とされていなでしょう。文字列は固定文字列に対する操作を実行するメソッドを持っていて、大きな汎用化された正規表現エンジンではなく、目的のために最適化された単一の小さな C loop で実装されているため、大抵の場合高速です.

一つの例としては、単一の固定文字列を別の固定文字列に置き換える作業があるでしょう; 例えば word を deed で置換したい場合です。 re.sub() はこの目的で使う関数のように思えますが、 replace() メソッドを利用することを考えた方がいいでしょう。 replace() は単語内の word も置換し、 swordfish を sdeedfish に変えますが、安直な正規表現 word も同様に動作することに注意して下さい。(単語の一部に対する置換の実行を避けるには、パターンを \bword\b として、 word の両側に単語の境界が要求されるようにします。これは replace() の能力を越えた作業です。)

別のよくある作業は、文字列の中に出現する文字を全て削除することと、別の文字で置換することです。この作業を re.sub('\n', ' ', S) のようにして行うかもしれませんが、 translate() は削除と置換の両方の作業をこなし、正規表現操作よりも高速に行うことができます。

要は、 re モジュールに向う前に問題が高速で単純な文字列メソッドで解決できるか考えましょうということです。

match() 対 search()

match() 関数は文字列の先頭に正規表現がマッチするかどうか調べるだけですが、その一方 search() はマッチするために文字列の先の方まで走査します。この違いを覚えておくことは重要なことです。 match() は開始位置0でマッチが成功したときのみ報告する; もし開始位置0でマッチしなければ、 match() はそれを報告 しない 、ということを覚えておいてください。

>>> print(re.match('super', 'superstition').span())
(0, 5)
>>> print(re.match('super', 'insuperable'))
None

一方 search() は文字列の先の方まで走査し、最初にみつけたマッチを報告します。:

>>> print(re.search('super', 'superstition').span())
(0, 5)
>>> print(re.search('super', 'insuperable').span())
(2, 7)

しばしば、 re.match() を使い、 .* を正規表現の最初に付け加える誘惑にからされることがあるでしょう。この誘惑に打ち克って、代わりに re.search() を利用すべきです。正規表現コンパイラはマッチを探す処理の高速化のためにいくつかの解析を行います。そのような解析のうちのひとつはマッチの最初の文字が何であるか評価することです; 例えば、 Crow で始まるパターンは 'C' から始まらなければいけません。解析によってエンジンは速やかに開始文字を探して走査します、 'C' が発見された場合にはじめて完全なマッチを試みます。

.* を追加することはこの最適化を無効にします、文字列の終端までの走査が必要となり、走査後には残りの正規表現とのマッチ部分を見つけるために引き返すことになります。代わりに re.search() を利用して下さい。

貪欲 (greedy) 対非貪欲 (non-greedy)

正規表現を繰り返す場合、たとえば a* のように、できるだけパターンの多くにマッチするように動作することになります。この動作は、例えば角括弧で囲まれた HTML タグのような左右対称のデリミタの対にマッチしようという場合に問題となります。単一の HTML タグにマッチする素朴な正規表現はうまく動作しません、なぜならば .* は貪欲に動作するからです。

>>> 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>

正規表現は '<html>' 内の '<' にマッチし、 .* は残りの文字列の全てにマッチします。しかし、正規表現には依然として残っている部分があって、 > は文字列の終端にマッチしないので、正規表現エンジンは一文字ずつ > とマッチするまで引き返すことになります。最終的にマッチする領域は '<html>' の '<' から '</title>' の '>' まで広がりますが、これは望んだ結果ではありません。

この場合の解決策は、非貪欲 (non-greedy) な数量子 *?, +?, ??, あるいは {m,n}? を使うことです。これらはできるだけ 少ない テキストにマッチしようとします。上記の例では、 '>' は '<' がマッチした直後の文字からマッチするかどうかを調べられ、失敗すると同時にエンジンは文字を先に進めながら、各ステップで '>' のマッチを試みます。この動作は正しい結果を生成します:

>>> print(re.match('<.*?>', s).group())
<html>

(HTML や XML を正規表現でパースすることは苦痛を伴うものであることは記憶に留めておいて下さい。素早く、汚いパターンは大抵の場合うまく動作しますが、HTML と XML は正規表現が破綻する特別な例です; 全ての可能な場合にうまく動作する正規表現を書き上げたときには、パターンは 非常に 複雑なものになります。そのような作業をする場合には HTML や XML パーサを利用しましょう。)

re.VERBOSE の利用

ここまでで、正規表現がとても簡潔な表記であることに気づいたでしょう、また、正規表現は読みやすいものでもないということにも気づいたことでしょう。そこそこに入り組んだ正規表現ははバックスラッシュ、括弧、特殊文字が長く続いて、読みにくく、理解しづらいものになります。

そのような正規表現に対しては、正規表現をコンパイルする時に re.VERBOSE フラグを指定することが助けになります。なぜなら、より明確な書式で正規表現を書けるからです。

re.VERBOSE の効果はいくつかあります。正規表現内の文字クラス内に 無い 空白は無視されます。これは、 dog | cat のような表現が少々可読性の落ちる dog|cat と等価となるということです、しかし、 [a b] は依然として 'a', 'b', または空白にマッチします。加えて、正規表現にコメントを入れることもできるようになります; # 文字から次の改行までがコメントの範囲です。三重クォートを利用することで、正規表現をきちんとフォーマットすることができます:

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)

これは下よりはるかに読みやすいです:

pat = re.compile(r"\s*(?P<header>[^:]+)\s*:(?P<value>.*?)\s*$")

フィードバック

正規表現は複雑な話題です。このドキュメントは助けになったでしょうか？わかりにくかったところや、あなたが遭遇した問題が扱われていない等なかったでしょうか？もしそんな問題があれば、著者に改善の提案を送って下さい。

O'Reilly から出版されている Jeffrey Friedl の Mastering Regular Expressions は正規表現に関するほぼ完璧な書籍です (訳注　日本語訳「詳説　正規表現」が出版されています) 。不幸なことに、この本は Perl と Java の正規表現を集中して扱っていて、 Python の正規表現については全く扱っていません、そのため Python プログラミングのためのレファレンスとして使うことはできません。 (第一版はいまや削除された Python の regex モジュールについて扱っていましたが、これはあまり役に立たないでしょう。) 図書館で調べるのを検討してみましょう。

ソケットプログラミング HOWTO

著者:

Gordon McMillan

概要

ソケットはそこかしこで使われているが、最大級に誤解されている技術でもある。この文書はソケットの全体像を俯瞰しており、チュートリアルとしてはあまり役に立たない。実際に動くモノを完成させるには、他にもやらなければいけないことがあるからだ。この文書はソケットの微妙なところ (たくさんある) まではカバーしていないが、恥ずかしくない使い方ができるようになる程度の情報は得られるはずだ。

ソケット

INET (すなわち IPv4) ソケットのことしか語らないつもりだが、利用率でいうとソケットの 99% 以上はこれだ。さらに中でも STREAM (すなわち TCP) ソケットに話題を絞ろうと思う - 自分が何をしているのか分かっているのでない限り (分かってるならこの HOWTO なんて要らないだろ!)、STREAM ソケットが一番分かりやすく、一番性能が出るのだ。そうやって謎に包まれたソケットの正体を明らかにしてゆくと共に、ブロッキングおよびノンブロッキングなソケットの扱いに関するいくつかのヒントを提示しよう。だが、まずはブロッキングソケットから始めることにする。ノンブロッキングを扱うより先に、ブロッキングの仕組みを知っておかなくてはならないのだ。

話を理解しにくくしている要因として、「ソケット」という言葉が文脈によって微妙に違うものを指すことが挙げられる。そこでまず、「クライアント」ソケット - 対話の両端 - と「サーバ」ソケット - 電話交換手みたいなもの - の区別を付けておこう。クライアントアプリケーション (たとえばブラウザ) は「クライアント」ソケットだけを使うが、話し相手のウェブサーバは「サーバ」ソケットと「クライアント」ソケットの両方を使う。

歴史

各種 IPC (Inter Process Communication (プロセス間通信) の中でも、ソケットは群を抜いて人気がある。どのプラットフォームにも、ソケットより速い IPC はあるだろう。だが、プラットフォームをまたぐ通信はソケットの独擅場だ。

ソケットは BSD Unix の一部としてバークレイで発明され、インターネットの普及と共に野火のごとく広まった。それももっともなことで、ソケットと INET のコンビによって世界中どんなマシンとも、信じられないほど簡単 (少なくとも他のスキームと比べて) に通信できるようになったのだ。

ソケットの作成

あなたがリンクをクリックしてこのページに来たとき、ブラウザは大雑把に言って次のようなことをしたのである:

# 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))

この connect が完了すると、ソケット s を使ってこのページ文章への要求を送ることができるようになる。その同じソケットが返答を読み、そして破壊される。そう、破壊される。クライアントソケットは通常、一回 (か少数の) やり取りで使い捨てになるのだ。

ウェブサーバで起こる事柄はもう少し複雑だ。まず「サーバソケット」を作る:

# 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)

ここで注意すべき点がいくつかある: 今回はソケットが外界に見えるよう、 socket.gethostname() を使った。 s.bind(('localhost', 80)) や s.bind(('127.0.0.1', 80)) でも「サーバ」ソケットにはなるが、それだと同じマシン内にしか見えないものになってしまう。 s.bind(('', 80)) はこのマシンが持っている全てのアドレスで接続可能になるようにという指定になる。

ふたつめ: 小さな番号のポートは大抵、「ウェルノウン (有名)」なサービス (HTTP, SNMP 等々) のために取ってある。お遊びで使うのなら適当に大きな数 (4桁) を使おう。

最後に: listen の引数はソケットライブラリに、接続要求を 5 個 (通常の最大値) まで順番待ちさせるように命じている。これ以降の外部接続は拒否するのだが、コードが適切に書かれていれば、それで十分すぎるほどだ。

よし、「サーバーソケット」ができて、80 番ポートで耳を澄ましているところまで来た。では、ウェブサーバのメインループに入ろう:

while True:
    # accept connections from outside
    (clientsocket, address) = serversocket.accept()
    # now do something with the clientsocket
    # in this case, we'll pretend this is a threaded server
    ct = client_thread(clientsocket)
    ct.run()

このループには実際のところ、3 通りの一般的な動作方法がある - clientsocket を扱うようにスレッドを割り当てたり、clientsocket を扱う新しいプロセスを作ったり、あるいはノンブロッキングソケットを使うようにアプリを作り直して select で「サーバ」ソケットとアクティブな clientsocket の間を多重化したりするのだ。最後のについてはまた後にしよう。ここで理解しておくべき要点はこれだ: 以上が「サーバ」ソケットの仕事の すべて である。データは一切送信しないし、受信しない。「クライアント」ソケットを生み出すだけ。我々のバインドされているホストとポートに connect() してくる 他の 「クライアント」ソケットに応える形で clientsocket を作り、作るや否や、さらなる接続を聞きに戻っていくのだ。このふたつの「クライアント」は、あとは勝手に喋っていればいい - 使うポートは動的に割り当てられ、会話が終わればリサイクルに廻される。

IPC

1つのマシン上の2プロセス間で高速なIPCを行いたい場合は、pipe か共有メモリを検討するべきです。AF_INET ソケットを使用すると決めた場合、「サーバー」ソケットは 'localhost' にバインドしましょう。ほとんどのプラットフォームで、いくつかのネットワークレイヤーをショートカットすることでかなり高速になります。

参考

multiprocessing はクロスプラットフォームなIPCの高級なAPIを提供しています。

ソケットの利用

はじめに憶えておくべきなのは、ウェブブラウザの「クライアント」ソケットとウェブサーバの「クライアント」ソケットがまったく同じ種族だということだ。つまり、これは「ピア・トゥ・ピア」(1 対 1) の会話である。別の言い方をすると、 設計者として自分で会話のエチケット規則を決めなくてはいけない ということでもある。通常は、 connect してくるソケットが要求あるいは宣言をして会話を始める。だが、それはそう設計しただけのことだ - ソケットの規則ではない。

さて、コミュニケーションに使う動詞は二組ある。 send と recv を使うこともできるし、クライアントソケットをファイルっぽい種族に変形して read と write を使っても良い。後者は Java のソケットの表現方法だ。ここで詳しく語るつもりはないが、その場合はソケットも flush しなければいけない、とだけ言っておく。これはバッファリングした「ファイル」なので、何かを write してすぐに返答を read するというのはよくある間違いだ。間に flush を入れないと、要求がまだ出力バッファにあって永遠に返事が来ない、という可能性がある。

さあ、ソケットの主要な難関に進もう - send と recv はネットワークバッファに働きかけるものだ。だから、手渡したもの (や返してもらいたいもの) を 1 バイトも残さず実際に処理してくれているとは限らない。一般的に言って、 send はバッファが埋まるまで、recv はバッファが空になるまで処理をして、そのバイト数を返す。メッセージが完全に処理されるまで繰り返し呼び出すのは 自分の 責任なのだ。

recv が 0 バイトを返したときは、向こう側が接続を閉じてしまった (または閉じようとしている途中) という意味だ。もうこの接続でデータを受け取ることはない。永遠にだ。ただ、データ送信は成功するかもしれない; これについてはあとで語ることにしよう。

HTTP のようなプロトコルでは、ひとつのソケットを1回の転送にしか使わない。クライアントは要求を送り、返答を受ける。以上だ。これでソケットは破棄される。だからこの場合、クライアントは受信 0 バイトの時点で返答の末尾を検出することができる。

だが、以降の転送にもそのソケットを使い回すつもりなら、ソケットに EOT など 存在しない ことを認識する必要がある。もう一度言おう: ソケットの send や recv が 0 バイト処理で返ってきたなら、その接続は終わっている。終わって いない なら、いつまで recv を待てばいいかは分からない。ソケットは「もう読むものが (今のところ) ないぜ」などと 言わない のだから。このことを少し考えれば、ソケットの真実を悟ることになるだろう: メッセージは必ず固定長か (うげぇ) 区切り文字を使うか (やれやれ) 長さ標識を付けておくか (かなりマシ) 接続を閉じて終わらせるかのいずれかでなければいけない のだ。選ぶ権利と責任はまったくもって自分にある (が、正しさの程度に違いはある)。

毎回接続を終わらせるのはイヤだとして、最も単純な解決策は固定長メッセージだろう:

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'':
                raise RuntimeError("socket connection broken")
            chunks.append(chunk)
            bytes_recd = bytes_recd + len(chunk)
        return b''.join(chunks)

この送信コードは、ほぼあらゆるメッセージ通信スキームで使える - 文字列を送るとき、Python なら長さを len() で見極めることができる (中に \0 が埋め込まれていても大丈夫)。難しくしているのは、おもに受信コードである。 (なお、C でも事態はあまり悪くならないが、メッセージに \0 が埋め込まれていると strlen が使えないのは面倒だ。)

最も簡単な改良法は、メッセージの最初の一文字をタイプ標識にして、そのタイプで長さを決定するというものだ。この場合ふたつの recv があることになる - 一番目でその一文字 (だけじゃなくても可) を取って長さを調べ、二番目でループして残りを取るのだ。あるいはもし区切り方式の道を行くのであれば、任意のサイズ (4096 か 8192 がネットワークバッファには最適なことが多い) で受信して区切り文字を走査していくことになる。

心に留めておくべき面倒な点がひとつ: 複数メッセージが次々に (何らかの返事を待たずに) 返ってくることのある会話プロトコルなら、そして任意のサイズを recv に渡しているなら、次のメッセージの冒頭部分まで読んでしまうことがあるかもしれない。そのときは、必要になるまで脇によけて、大切に保管しておく必要がある。

メッセージ冒頭に長さを (たとえば 5 桁の数字で) 付けるのは、それよりもさらに複雑になる。というのも、(信じられないかもしれないが) 一回の recv で 5 文字を全部受け取ることができるとは限らないからだ。お遊びでやっている間はごまかせても、高負荷ネットワークのもとでは、recv ループをふたつ使わないコードは、あっと言う間にダメになってしまう - 一番目は長さを見定める用で、二番目はデータ部分を受け取る用だ。うーむ、いやらしい。さらにこのとき、send も一発で全部を出し切れるとは限らないことに気付くだろう。なお、今こうやって読んでいても、いつか誰もが痛い目を見るのである!

紙面の都合および教育的配慮 (と著者の地位確保) のため、こうした改良は練習問題として残しておく。さあ片付けてしまおう。

バイナリデータ

It is perfectly possible to send binary data over a socket. The major problem is that not all machines use the same formats for binary data. For example, network byte order [https://en.wikipedia.org/wiki/Endianness#Networking] is big-endian, with the most significant byte first, so a 16 bit integer with the value 1 would be the two hex bytes 00 01. However, most common processors (x86/AMD64, ARM, RISC-V), are little-endian, with the least significant byte first - that same 1 would be 01 00.

Socket libraries have calls for converting 16 and 32 bit integers - ntohl, htonl, ntohs, htons where "n" means network and "h" means host, "s" means short and "l" means long. Where network order is host order, these do nothing, but where the machine is byte-reversed, these swap the bytes around appropriately.

In these days of 64-bit machines, the ASCII representation of binary data is frequently smaller than the binary representation. That's because a surprising amount of the time, most integers have the value 0, or maybe 1. The string "0" would be two bytes, while a full 64-bit integer would be 8. Of course, this doesn't fit well with fixed-length messages. Decisions, decisions.

切断

厳密には、ソケットを close する前には shutdown することになっている。 shutdown は相手ソケットに対する報告であり、渡す引数によって「これ以上こっちからは送らないけど、まだ聞いてるぜ」という意味になったり、「もう聞かない。せいせいした!」だったりする。しかしほとんどのソケットライブラリは、このエチケットを怠るプログラマに慣れてしまって、通常 close だけで shutdown(); close() と同じことになる。だから大抵はわざわざ shutdown しなくてもいい。

shutdown の効果的な使い方のひとつは、HTTP 風のやりとりだ。クライアントは要求を出してすぐに shutdown(1) する。これでサーバに、「クライアントは送信完了ですが、まだ受信可能です」と伝わる。サーバは 0 バイト受信で "EOF" を検出することができる。要求を残さず受け取ったことにして良いのだ。対してサーバは返答を送る。その send が成功したなら、クライアントは実際にまだ受信していたことになる。

Python はこの自動 shutdown をもう一歩進めて、ソケットが GC されるときに必要なら自動で close してくれると言っている。しかしこれに頼るクセをつけてはいけない。もしソケットが close せずに姿を消せば、相手ソケットはこちらが遅いだけだと思ってハングしてしまうかもしれない。 お願いだから 終わったらちゃんと close してくれ。

ソケットが死ぬと

ブロッキングソケットを使っていて一番いやなのは多分、相手側が意地悪く (close せずに) ダウンするときに起こる事柄だ。自分側のソケットは高確率でハングするだろう。TCP は信頼性の高いプロトコルなので、ずっとずっと待ち続けて、なかなか見捨てないのだ。スレッドを使っているのであれば、そのスレッド全体が根本から死んだ状態になる。こうなると、もう手の施しようがない。まあ、ブロッキング読み出しの間ロックし続けるといった馬鹿げたことをしていない限り、リソースの点ではたいして消費にならない。だから ぜったいに そのスレッドを殺そうとしてはいけない - プロセスよりスレッドが効率的である理由のひとつは、自動リソース回収にまつわるオーバヘッドを避けられるという点にあるのだ。つまり別の言い方をすると、どうにかしてそのスレッドを殺したなら、プロセス全体がぐちゃぐちゃになってしまうだろうということだ。

ノンブロッキングソケット

ここまで理解してきたなら、もうソケットの仕組みについて必要なことはほとんど知っていることになる。これからも同じコールを、ほぼ同じように使っていくだけ、それだけだ。これをちゃんとやっていれば、そのアプリはだいたい完璧であろう。

Python の場合、ノンブロッキングにするには socket.setblocking(False) を使う。 C ならもっと複雑だ (一例を挙げると、BSD 方式の O_NONBLOCK およびほぼ違いのない POSIX 方式 O_NDELAY のどちらを選ぶか決めなくてはならなくて、後者は TCP_NODELAY とは全然別物だったりする) が、考え方はまったく一緒だ。これは、ソケットを作成した後、使用する前に行う。(実際、常識破りなら、切り替えることができます。)

構造上の大きな違いは、 send, recv, connect, accept が何もしないで戻ってくるかもしれないという点である。選択肢は (当然ながら) いくつかある。返り値とエラーコードをチェックするという方法もある。が、発狂すること請け合いだ。信じないなら、いつかやってみるといい。アプリは肥大化し、バグが増え、CPU を喰い尽くすだろう。だからそんな愚かな解法は飛ばして、正解に進もう。

select を使え。

C において select でコードを書くのはかなり面倒だが、Python なら造作もない。しかし Python で select を理解しておけば C でもほとんど問題なく書ける、という程度には似ている:

ready_to_read, ready_to_write, in_error = \
               select.select(
                  potential_readers,
                  potential_writers,
                  potential_errs,
                  timeout)

select に三つのリストを渡しているが、一番目にはあとで読みたくなるかもしれないソケットすべて、二番目には書き込みたくなるかもしれないソケットすべて、最後に (通常は空のままだが) エラーをチェックしたいソケットが入っている。ひとつのソケットが複数にまたがってリストされても構わないことを憶えておくと良い。なお、 select コールはブロックするが、時間制限を与えることができる。これは、やっておいて損はない - 特に理由がなければ、かなり長い (たとえば 1 分とかの) 時間制限を付けておくことだ。

戻り値として、三つのリストが手に入る。それぞれには、実際に読めるソケット、書けるソケット、エラー中のソケットが入っていて、渡したリストの部分集合 (空集合かもしれない) になっている。

出力のうち、readable リストにあるソケットについては、 recv がとりあえず 何か を返すであろう、ということは史上最高度に確信できる。 writable リストも考え方は同じで、 何か は送れる。送りたいもの全体は無理かもしれないが、 何も ないよりはマシだろう。 (実のところ、ふつうに健康なソケットなら writable で返ってくることができる - それは外向きネットワークバッファに空きがあるというだけの意味しかないのだから)

「サーバ」ソケットは potential_readers リストに入れておこう。それが readable リストに入って出てきたら、 accept は (ほぼ) 確実に成功するはずだ。どこかへ connect するために作った新しいソケットは potential_writers リストに入れる。それが writable リストに現れたら、接続が成功している可能性は高いと言える。

じつは select はブロッキングソケットにも便利に使える。それはブロックするかどうかを見極める方法のひとつである - バッファに何かがあれば readable として返ってくるのだ。しかしこれも、相手の用事がもう済んでいるのか、それとも単に他のことで忙しいだけなのかを見極める役には立たない。

非互換警報: Unix ではソケットにもファイルにも select が使える。これを Windows でやろうとしてはいけない。Windows で select はソケットにしか使えない。また C の場合、高度なソケットオプションの多くは、やり方が Windows では違っている。実際、Windows なら著者は通常、ソケットにスレッドを使っている (これは実に、実にうまくいく)。

Sorting Techniques

著者:

Andrew Dalke and Raymond Hettinger

Python のリストにはリストをインプレースに変更する、組み込みメソッド list.sort() があります。他にもイテラブルからソートしたリストを作成する組み込み関数 sorted() があります。

このドキュメントでは Python を使った様々なソートのテクニックを探索します。

ソートの基本

単純な昇順のソートはとても簡単です: sorted() 関数を呼ぶだけです。そうすれば、新たにソートされたリストが返されます:

>>> sorted([5, 2, 3, 1, 4])
[1, 2, 3, 4, 5]

list.sort() メソッドを呼びだしても同じことができます。この方法はリストをインプレースに変更します (そして sorted との混乱を避けるため None を返します)。多くの場合、こちらの方法は sorted() と比べると不便です - ただし、元々のリストが不要な場合には、わずかですがより効率的です。

>>> a = [5, 2, 3, 1, 4]
>>> a.sort()
>>> a
[1, 2, 3, 4, 5]

違いは他にもあります、 list.sort() メソッドはリストにのみ定義されています。一方 sorted() 関数は任意のイテラブルを受け付けます。

>>> sorted({1: 'D', 2: 'B', 3: 'B', 4: 'E', 5: 'A'})
[1, 2, 3, 4, 5]

Key 関数

list.sort() と sorted() には key パラメータがあります。 これは比較を行う前にリストの各要素に対して呼び出される関数 (または呼び出し可能オブジェクト) を指定するパラメータです。

例えば、大文字小文字を区別しない文字列比較の例:

>>> sorted("This is a test string from Andrew".split(), key=str.casefold)
['a', 'Andrew', 'from', 'is', 'string', 'test', 'This']

key パラメータの値は関数または呼び出し可能オブジェクトであって、単一の引数をとり、ソートに利用されるキー値を返すものでなければいけません。この制約によりソートを高速に行えます、キー関数は各入力レコードに対してきっちり一回だけ呼び出されるからです。

よくある利用パターンはいくつかの要素から成る対象をインデクスのどれかをキーとしてソートすることです。例えば:

>>> student_tuples = [
...     ('john', 'A', 15),
...     ('jane', 'B', 12),
...     ('dave', 'B', 10),
... ]
>>> sorted(student_tuples, key=lambda student: student[2])   # sort by age
[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]

同じテクニックは名前づけされた属性 (named attributes) を使うことでオブジェクトに対しても動作します。例えば:

>>> class Student:
...     def __init__(self, name, grade, age):
...         self.name = name
...         self.grade = grade
...         self.age = age
...     def __repr__(self):
...         return repr((self.name, self.grade, self.age))

>>> student_objects = [
...     Student('john', 'A', 15),
...     Student('jane', 'B', 12),
...     Student('dave', 'B', 10),
... ]
>>> sorted(student_objects, key=lambda student: student.age)   # sort by age
[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]

Objects with named attributes can be made by a regular class as shown above, or they can be instances of dataclass or a named tuple.

Operator Module Functions and Partial Function Evaluation

The key function patterns shown above are very common, so Python provides convenience functions to make accessor functions easier and faster. The operator module has itemgetter(), attrgetter(), and a methodcaller() function.

これらの関数を利用すると、上の例はもっと簡単で高速になります:

>>> 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)]

operator モジュールの関数は複数の段階でのソートを可能にします。例えば、 grade でソートしてさらに age でソートする場合:

>>> 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)]

The functools module provides another helpful tool for making key-functions. The partial() function can reduce the arity [https://en.wikipedia.org/wiki/Arity] of a multi-argument function making it suitable for use as a key-function.

>>> 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']

昇順と降順

list.sort() と sorted() の両方とも reverse パラメータを 真偽値として受け付けます。このパラメータは降順ソートを行うかどうかの フラグとして利用されます。 例えば、学生のデータを age の逆順で得たい場合:

>>> 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)]

ソートの安定性と複合的なソート

ソートは、 安定 (stable) [https://en.wikipedia.org/wiki/Sorting_algorithm#Stability] であることが保証されています。これはレコードの中に同じキーがある場合、元々の順序が維持されるということを意味します。

>>> data = [('red', 1), ('blue', 1), ('red', 2), ('blue', 2)]
>>> sorted(data, key=itemgetter(0))
[('blue', 1), ('blue', 2), ('red', 1), ('red', 2)]

二つの blue のレコードが元々の順序を維持して、 ('blue', 1) が ('blue', 2) の前にあることに注意してください。

この素晴しい性質によって複数のソートを段階的に組み合わせることができます。例えば、学生データを grade の降順にソートし、さらに age の昇順にソートしたい場合には、まず age でソートし、次に grade でもう一度ソートします:

>>> s = sorted(student_objects, key=attrgetter('age'))     # sort on secondary key
>>> sorted(s, key=attrgetter('grade'), reverse=True)       # now sort on primary key, descending
[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]

この処理は、リストおよびフィールド名とソート順序のタプルを複数受け取れるラッパー関数へ抽象化できます。

>>> 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)]

Python では Timsort [https://en.wikipedia.org/wiki/Timsort] アルゴリズムが利用されていて、効率良く複数のソートを行うことができます、これは現在のデータセット中のあらゆる順序をそのまま利用できるからです。

デコレート - ソート - アンデコレート (DSU)

このイディオムは以下の3つのステップにちなんでデコレート-ソート-アンデコレート (Decorate-Sort-Undecorate) と呼ばれています:

まず、元となるリストをソートしたい順序を制御する新しい値でデコレートします。

次に、デコレートしたリストをソートします。

最後に、デコレートを取り除き、新しい順序で元々の値のみを持つリストを作ります。

例えば、DSU アプローチを利用して学生データを grade でソートする場合:

>>> decorated = [(student.grade, i, student) for i, student in enumerate(student_objects)]
>>> decorated.sort()
>>> [student for grade, i, student in decorated]               # undecorate
[('john', 'A', 15), ('jane', 'B', 12), ('dave', 'B', 10)]

このイディオムはタブルが辞書編集的に比較されるため正しく動作します; 最初の要素が比較され、同じ場合には第二の要素が比較され、以下も同様に動きます。

デコレートしたリストのインデクス i は全ての場合で含まれる必要はありませんが、そうすることで二つの利点があります:

ソートが安定になります -- もし二つの要素が同じキーを持つ場合、それらの順序がソートされたリストでも維持されます。

元々の要素が比較可能な要素を持つとは限りません、なぜならデコレートされたタブルの順序は多くの場合、最初の二つの要素で決定されるからです。例として元のリストは直接比較できない複素数を含むことができます。

このイディオムの別名に Schwartzian transform [https://en.wikipedia.org/wiki/Schwartzian_transform] があります。これは Perl プログラマの間で有名な Randal L. Schwartz にちなんでいます。

いまや Python のソートは key 関数による方法を提供しているので、このテクニックは不要でしょう。

比較関数

ソートのための絶対的な値を返すキー関数と違って、2つの入力を受け取り、その相対的な順序を計算するような関数を比較関数といいます。

例えば、 天秤 [https://upload.wikimedia.org/wikipedia/commons/1/17/Balance_à_tabac_1850.JPG] は2つのサンプルを比較し、より軽いか、同じか、より重いかの相対的な順序を与えます。同じように、 cmp(a, b) などの比較関数はより小さいときは負の値を、入力が等しい場合は 0 を、より大きい場合は正の値を返します。

他のプログラミング言語で書かれたアルゴリズムを Python に書き直すときに比較関数を目にすることがよくあります。また、その API の一部として比較関数を提供しているライブラリもあります。例えば、 locale.strcoll() は比較関数です。

このような場合に対処するため、Python は比較関数をラップしてキー関数として使えるようにする関数 functools.cmp_to_key を提供しています。

sorted(words, key=cmp_to_key(strcoll))  # locale-aware sort order

残りのはしばし

ロケールに対応したソートを行うには、キー関数に locale.strxfrm() を使うか、比較関数に locale.strcoll() を使ってください。これが必要なのは、同じアルファベットを使っていたとしても、文化が違えば "アルファベット順" の意味するものが変わることがあるからです。

reverse パラメータはソートの安定性を保ちます (ですから、レコードのキーが等しい場合元々の順序が維持されます)。面白いことにこの影響はパラメータ無しで reversed() 関数を二回使うことで模倣することができます:

>>> 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)]

ソート関数は、2つのオブジェクトを比較する際 < を用います。したがって、クラスに標準のソート順序を追加することは __lt__() メソッドを定義することで達成できます。

>>> Student.__lt__ = lambda self, other: self.age < other.age
>>> sorted(student_objects)
[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]

However, note that < can fall back to using __gt__() if __lt__() is not implemented (see object.__lt__() for details on the mechanics). To avoid surprises, PEP 8 [https://peps.python.org/pep-0008/] recommends that all six comparison methods be implemented. The total_ordering() decorator is provided to make that task easier.

key 関数はソートするオブジェクトに依存する必要はありません。 key 関数は外部リソースにアクセスすることもできます。例えば学生の成績が辞書に保存されている場合、それを利用して別の学生の名前のリストをソートすることができます:

>>> students = ['dave', 'john', 'jane']
>>> newgrades = {'john': 'F', 'jane':'A', 'dave': 'C'}
>>> sorted(students, key=newgrades.__getitem__)
['jane', 'dave', 'john']

Partial Sorts

Some applications require only some of the data to be ordered. The standard library provides several tools that do less work than a full sort:

min() and max() return the smallest and largest values, respectively. These functions make a single pass over the input data and require almost no auxiliary memory.

heapq.nsmallest() and heapq.nlargest() return the n smallest and largest values, respectively. These functions make a single pass over the data keeping only n elements in memory at a time. For values of n that are small relative to the number of inputs, these functions make far fewer comparisons than a full sort.

heapq.heappush() and heapq.heappop() create and maintain a partially sorted arrangement of data that keeps the smallest element at position 0. These functions are suitable for implementing priority queues which are commonly used for task scheduling.

Unicode HOWTO

リリース:

1.12

この HOWTO 文書は、文字データの表現のための Unicode 仕様の Python におけるサポートについて論じ、さらに Unicode を使おうというときによく出喰わす多くの問題について説明します。

Unicode 入門

定義

今日のプログラムは広範囲の文字を扱える必要があります。アプリケーションは国際化され、ユーザーが選べる様々な言語でメッセージや出力を表示します; 同じプログラムが、英語、フランス語、日本語、ヘブライ語、ロシア語でエラーメッセージを出力する必要があるかもしれません。 Webコンテンツはどんな言語でも書かれる可能性がありますし、様々な絵文字が含まれることもあります。 Python の文字列型は文字表現のための Unicode 標準を使っていて、 Python プログラムは有り得る様々な文字を全て扱えます。

Unicode (https://www.unicode.org/) は、人類の言語で使われる全ての文字を列挙し、それぞれの文字自身の一意な符号を与えるのを目的とした仕様です。 Unicode 仕様は継続的に改訂され、新しい言語や記号を追加する更新がなされています。

文字 は文章の最小の構成要素です。 'A', 'B', 'C' などは全て異なる文字です。 'È' と 'Í' も同様に異なる文字です。文字は、話している言語や文脈によって変わってきます。例えば、「ローマ数字の 1」という文字 'Ⅰ' は大文字の 'I' とは別の文字です。両者は通常は同じに見えますが、異なる意味を持つ別々の2つの文字です。

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 [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 U+265E to mean the character with value 0x265e (9,822 in decimal).

Unicode 標準は、文字とそれに対応するコードポイントを列挙した多くの表を含んでいます:

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
...

厳密には、この定義から「これは文字 U+265E です」と言うのは意味の無いことだと分かります。U+265E はコードポイントであり、それはある特定の文字を表しているのです; この場合では、 'BLACK CHESS KNIGHT', '♞' という文字を表しています。形式ばらない文脈では、このコードポイントと文字の区別は忘れ去られることもあります。

文字は画面や紙面上では グリフ (glyph) と呼ばれるグラフィック要素の組で表示されます。大文字の A のグリフは例えば、厳密な形は使っているフォントによって異なりますが、斜めの線と水平の線です。たいていの Python コードではグリフの心配をする必要はありません; 一般的には表示する正しいグリフを見付けることは GUI toolkit や端末のフォントレンダラーの仕事です。

エンコーディング

前の節をまとめると: Unicode 文字列はコードポイントの列であり、コードポイントとは 0 から 0x10FFFF (10 進表記で 1,114,111) までの数値です。このコードポイント列はメモリ上では コードユニット 列として表され、その コードユニット 列は 8-bit のバイト列にマップされます。Unicode 文字列をバイト列として翻訳する規則を 文字エンコーディング または単に エンコーディング と呼びます。

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:

   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

この表現は直接的でわかりやすい方法ですが、この表現を使うにはいくつかの問題があります。

可搬性がない; プロセッサが異なるとバイトの順序づけも変わってしまいます。

無駄な領域が多いです。多くの文書では、コードポイントは 127 未満もしくは 255 未満が多数派を占め、そのため多くの領域が 0x00 というバイトで埋め尽くされます。上の文字列は、ASCII 表現では 6 バイトなのに対し、24 バイトのサイズになっています。RAM の使用量が増加するのはそれほど問題にはなりません (デスクトップコンピュータはギガバイト単位の RAM を持っており、通常、文字列はそんな大きさにはなりません) が、ディスクとネットワーク帯域が 4 倍多く使われてしまうのは我慢できるものではありません。

strlen() のような現存する C 関数と互換性がありません、そのためワイド文字列関数一式が新たに必要となります。

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:

コードポイントが 128 未満だった場合、対応するバイト値で表現します。

コードポイントが 128 以上の場合、128 から 255 までのバイトからなる、2、3 または 4 バイトのシーケンスに変換します。

UTF-8 はいくつかの便利な性質を持っています:

任意の Unicode コードポイントを扱うことができる。

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 strcpy() and sent through protocols that can't handle zero bytes for anything other than end-of-string markers.

ASCII テキストの文字列は UTF-8 テキストとしても有効です。

UTF-8 はかなりコンパクトです; よく使われている文字の大多数は 1 バイトか 2 バイトで表現できます。

バイトが欠落したり、失われた場合、次の UTF-8 でエンコードされたコードポイントの開始を決定し、再同期することができる可能性があります。同様の理由でランダムな 8-bit データは正当な UTF-8 とみなされにくくなっています。

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.

参考資料

Unicode コンソーシアムのサイト [https://www.unicode.org] には文字の図表、用語辞典、PDF 版の Unicode 仕様があります。これ読むのはそれなりに難しいので覚悟してください。Unicode の起源と発展の 年表 [https://www.unicode.org/history/] もサイトにあります。

On the Computerphile Youtube channel, Tom Scott briefly discusses the history of Unicode and UTF-8 [https://www.youtube.com/watch?v=MijmeoH9LT4] (9 minutes 36 seconds).

標準を理解する助けにするために、Jukka Korpela が Unicode 文字表を読むための 入門ガイド [https://jkorpela.fi/unicode/guide.html] を書いています。

Another good introductory article [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 の記事はしばしば役に立ちます; 例えば、"character encoding [https://en.wikipedia.org/wiki/Character_encoding]" や UTF-8 [https://en.wikipedia.org/wiki/UTF-8] の記事を読んでみてください。

Python の Unicode サポート

ここまでで Unicode の基礎を学びました、ここから Python の Unicode 機能に触れます。

文字列型

Since Python 3.0, the language's str type contains Unicode characters, meaning any string created using "unicode rocks!", 'unicode rocks!', or the triple-quoted string syntax is stored as Unicode.

Python ソースコードのデフォルトエンコーディングは UTF-8 なので、文字列リテラルの中に Unicode 文字をそのまま含めることができます:

try:
    with open('/tmp/input.txt', 'r') as f:
        ...
except OSError:
    # 'File not found' error message.
    print("Fichier non trouvé")

追記: Python3 は Unicode 文字を使った識別子もサポートしています:

répertoire = "/tmp/records.log"
with open(répertoire, "w") as f:
    f.write("test\n")

エディタである特定の文字が入力できなかったり、とある理由でソースコードを ASCII のみに保ちたい場合は、文字列リテラルでエスケープシーケンスが使えます。(使ってるシステムによっては、u でエスケープされた文字列ではなく、実物の大文字のラムダのグリフが見えるかもしれません。):

>>> "\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'

加えて、 bytes クラスの decode() メソッドを使って文字列を作ることもできます。このメソッドは UTF-8 のような値を encoding 引数に取り、オプションで errors 引数を取ります。

errors 引数は、入力文字列に対しエンコーディングルールに従った変換ができなかったときの対応方法を指定します。この引数に使える値は 'strict' (UnicodeDecodeError を送出する)、 'replace' (REPLACEMENT CHARACTER である U+FFFD を使う)、 'ignore' (結果となる Unicode から単に文字を除く) 、'backslashreplace' (エスケープシーケンス \xNN を挿入する) です。次の例はこれらの違いを示しています:

>>> 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'

エンコーディングはエンコーディングの名前を含んだ文字列で指定されます。 Python はおよそ 100 の異なるエンコーディングに対応しています; 一覧は Python ライブラリリファレンスの 標準エンコーディング を参照してください。いくつかのエンコーディングは複数の名前を持っています; 例えば、 'latin-1' と 'iso_8859_1' と '8859' は全て同じエンコーディングの別名です。

Unicode 文字列の一つの文字は chr() 組み込み関数で作成することができます、この関数は整数を引数にとり、対応するコードポイントを含む長さ1の Unicode 文字列を返します。逆の操作は ord() 組み込み関数です、この関数は一文字の Unicode 文字列を引数にとり、コードポイント値を返します:

>>> chr(57344)
'\ue000'
>>> ord('\ue000')
57344

バイト列への変換

bytes.decode() とは処理が逆向きのメソッドが str.encode() です。このメソッドは、 Unicode 文字列を指定された encoding でエンコードして、 bytes による表現で返します。

errors 引数は decode() メソッドのパラメータと同じものですが、サポートされているハンドラの数がもう少し多いです。 'strict' 、 'ignore' 、 'replace' (このメソッドでは、エンコードできなかった文字の代わりに疑問符を挿入する) の他に、 'xmlcharrefreplace' (XML 文字参照を挿入する) と backslashreplace (エスケープシーケンス \nNNNN を挿入する)、 namereplace (エスケープシーケンス \N{...} を挿入する) があります。

次の例では、それぞれの異なる処理結果が示されています:

>>> 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'

利用可能なエンコーディングを登録したり、アクセスしたりする低レベルのルーチンは codecs モジュールにあります。新しいエンコーディングを実装するには、 codecs モジュールを理解していることも必要になります。しかし、このモジュールのエンコードやデコードの関数は、使い勝手が良いというより低レベルな関数で、新しいエンコーディングを書くのは特殊な作業なので、この HOWTO では扱わないことにします。

Python ソースコード内の Unicode リテラル

Python のソースコード内では、特定のコードポイントはエスケープシーケンス \u を使い、続けてコードポイントを4桁の16進数を書きます。エスケープシーケンス \U も同様です、ただし4桁ではなく8桁の16進数を使います:

>>> 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]

127 より大きいコードポイントに対してエスケープシーケンスを使うのは、エスケープシーケンスがあまり多くないうちは有効ですが、フランス語等のアクセントを使う言語でメッセージのような多くのアクセント文字を使う場合には邪魔になります。文字を chr() 組み込み関数を使って組み上げることもできますが、それはさらに長くなってしまうでしょう。

理想的にはあなたの言語の自然なエンコーディングでリテラルを書くことでしょう。そうなれば、Python のソースコードをアクセント付きの文字を自然に表示するお気に入りのエディタで編集し、実行時に正しい文字が得られます。

Python はデフォルトでは UTF-8 ソースコードを書くことができます、ただしどのエンコーディングを使うかを宣言すればほとんどのエンコーディングを使えます。それはソースファイルの一行目や二行目に特別なコメントを含めることによってできます:

#!/usr/bin/env python
# -*- coding: latin-1 -*-

u = 'abcdé'
print(ord(u[-1]))

この構文は Emacs のファイル固有の変数を指定する表記から影響を受けています。Emacs は様々な変数をサポートしていますが、Python がサポートしているのは 'coding' のみです。 -*- の記法は Emacs に対してコメントが特別であることを示します。これは Python にとって意味はありませんが慣習で使われています。 Python はコメント中に coding: name または coding=name を探します。

このようなコメントを含んでいない場合、すでに述べた通り、使われるデフォルトエンコーディングは UTF-8 になります。より詳しい情報は PEP 263 [https://peps.python.org/pep-0263/] を参照してください。

Unicode プロパティ

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.

以下のプログラムはいくつかの文字に対する情報を表示し、特定の文字の数値を印字します:

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]))

実行すると、このように出力されます:

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

カテゴリーコードは文字の性質を略記で表したものです。カテゴリーコードは "Letter"、"Number"、"Punctuation"、"Symbol" などのカテゴリーに分類され、さらにサブカテゴリーに細分化されます。上記の出力からコードを拾うと、'Ll' は 'Letter, lowercase'、'No' は "Number, other"、'Mn' は "Mark, nonspacing"、'So' は "Symbol, other" を意味しています。カテゴリーコードの一覧は Unicode Character Database 文書の General Category Values 節 [https://www.unicode.org/reports/tr44/#General_Category_Values] を参照してください。

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 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'.

>>> street = 'Gürzenichstraße'
>>> street.casefold()
'gürzenichstrasse'

A second tool is the unicodedata module's normalize() function that converts strings to one of several normal forms, where letters followed by a combining character are replaced with single characters. normalize() can be used to perform string comparisons that won't falsely report inequality if two strings use combining characters differently:

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))

実行すると、このように出力されます:

$ python compare-strs.py
length of first string= 1
length of second string= 2
True

The first argument to the 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:

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))

This will print True. (Why is NFD() invoked twice? Because there are a few characters that make 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.)

Unicode 正規表現

re モジュールがサポートしている正規表現はバイト列や文字列として与えられます。 \d や \w などのいくつかの特殊な文字シーケンスは、そのパターンがバイト列として与えられたのか文字列として与えられたのかによって、異なる意味を持ちます。例えば、 \d はバイト列では [0-9] の範囲の文字と一致しますが、文字列では 'Nd' カテゴリーにある任意の文字と一致します。

この例にある文字列には、タイ語の数字とアラビア数字の両方で数字の 57 が書いてあります。

import re
p = re.compile(r'\d+')

s = "Over \u0e55\u0e57 57 flavours"
m = p.search(s)
print(repr(m.group()))

実行すると、 \d+ はタイ語の数字と一致し、それを出力します。フラグ re.ASCII を compile() に渡した場合、 \d+ は先程とは違って部分文字列 "57" に一致します。

同様に、 \w は非常に多くの Unicode 文字に一致しますが、バイト列の場合もしくは re.ASCII が渡された場合は [a-zA-Z0-9_] にしか一致しません。 \s は文字列では Unicode 空白文字に、バイト列では [ \t\n\r\f\v] に一致します。

参考資料

Python の Unicode サポートについての参考になる議論は以下の2つです:

Nick Coghlan による Processing Text Files in Python 3 [https://python-notes.curiousefficiency.org/en/latest/python3/text_file_processing.html]

Ned Batchelder による PyCon 2012 での発表 Pragmatic Unicode [https://nedbatchelder.com/text/unipain.html]

str 型については Python ライブラリリファレンスの テキストシーケンス型 --- str で解説されています。

unicodedata モジュールについてのドキュメント。

codecs モジュールについてのドキュメント。

Marc-André Lemburg は EuroPython 2002 で "Python and Unicode" というタイトルのプレゼンテーション (PDF スライド) [https://downloads.egenix.com/python/Unicode-EPC2002-Talk.pdf] を行いました。このスライドは Python 2 の Unicode 機能 (Unicode 文字列型が unicode と呼ばれ、リテラルは u で始まります) の設計について概観する素晴しい資料です。

Unicode データを読み書きする

一旦 Unicode データに対してコードが動作するように書き終えたら、次の問題は入出力です。プログラムは Unicode 文字列をどう受けとり、どう Unicode を外部記憶装置や送受信装置に適した形式に変換するのでしょう?

入力ソースと出力先に依存しないような方法は可能です; アプリケーションに利用されているライブラリが Unicode をそのままサポートしているかを調べなければいけません。例えば XML パーサーは大抵 Unicode データを返します。多くのリレーショナルデータベースも Unicode 値の入ったコラムをサポートしていますし、 SQL の問い合わせで Unicode 値を返すことができます。

Unicode のデータはディスクに書き込まれたり、ソケットを介して送信されたりするにあたって、通常、特定のエンコーディングに変換されます。推奨はされませんが、これを手動で行うことも可能です。ファイルを開き、8バイトオブジェクトを読み込み、バイト列を bytes.decode(encoding) で変換することにより実現できます。

1つの問題はエンコーディングがマルチバイトに渡るという性質です; 1つの Unicode 文字はいくつかのバイトで表現され得ます。任意のサイズのチャンク (例えば、1024 もしくは 4096 バイト) にファイルの内容を読み込みたい場合、ある1つの Unicode 文字をエンコードしたバイト列の一部だけがチャンクの末尾まで読み込まれたケースに対応する、エラー処理コードを書く必要があります。1つの解決策はファイル全体をメモリに読み込み、デコード処理を実行することですが、こうしてしまうと非常に大きなファイルを処理するときの妨げになります; 2 GiB のファイルを読み込む必要がある場合、2 GiB の RAM が必要になります。(実際には、少なくともある瞬間では、エンコードされた文字列と Unicode 文字列の両方をメモリに保持する必要があるため、より多くのメモリが必要です。)

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 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 read() and write(). This works through open()'s encoding and errors parameters which are interpreted just like those in str.encode() and bytes.decode().

そのためファイルから Unicode を読むのは単純です:

with open('unicode.txt', encoding='utf-8') as f:
    for line in f:
        print(repr(line))

読み書きの両方ができる update モードでファイルを開くことも可能です:

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]))

Unicode 文字 U+FEFF は byte-order mark (BOM) として使われ、ファイルのバイト順の自動判定を支援するために、ファイルの最初の文字として書かれます。UTF-16 のようないくつかのエンコーディングは、ファイルの先頭に BOM があることを要求します; そのようなエンコーディングが使われるとき、自動的に BOM が最初の文字として書かれ、ファイルを読むときに暗黙の内に取り除かれます。これらのエンコーディングには、リトルエンディアン (little-endian) 用の 'utf-16-le' やビッグエンディアン (big-endian) 用の 'utf-16-be' というような変種があり、これらは特定の1つのバイト順を指定していて 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.

Unicode ファイル名

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 filesystem encoding. if you've set the LANG or LC_CTYPE environment variables; if you haven't, the default encoding is again UTF-8.

sys.getfilesystemencoding() 関数は現在のシステムで利用するエンコーディングを返し、エンコーディングを手動で設定したい場合利用します、ただしわざわざそうする積極的な理由はありません。読み書きのためにファイルを開く時には、ファイル名を Unicode 文字列として渡すだけで正しいエンコーディングに自動的に変更されます:

filename = 'filename\u4500abc'
with open(filename, 'w') as f:
    f.write('blah\n')

os.stat() のような os モジュールの関数も Unicode のファイル名を受け付けます。

The 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? 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 filesystem encoding is UTF-8, running the following program:

fn = 'filename\u4500abc'
f = open(fn, 'w')
f.close()

import os
print(os.listdir(b'.'))
print(os.listdir('.'))

以下の出力結果が生成されます:

$ python listdir-test.py
[b'filename\xe4\x94\x80abc', ...]
['filename\u4500abc', ...]

最初のリストは UTF-8 でエンコーディングされたファイル名を含み、第二のリストは Unicode 版を含んでいます。

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.

Unicode 対応のプログラムを書くための Tips

この章では Unicode を扱うプログラムを書くためのいくつかの提案を紹介します。

最も重要な助言としては:

ソフトウェアは内部では Unicode 文字列のみを利用し、入力データはできるだけ早期にデコードし、出力の直前でエンコードすべきです。

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. str + bytes, a TypeError will be raised.

web ブラウザから来るデータやその他の信頼できないところからのデータを利用する場合、それらの文字列から生成したコマンド行の実行や、それらの文字列をデータベースに蓄える前に文字列の中に不正な文字が含まれていないか確認するのが一般的です。もしそういう状況になった場合には、エンコードされたバイトデータではなく、デコードされた文字列のチェックを入念に行なって下さい; いくつかのエンコーディングは問題となる性質を持っています、例えば全単射でなかったり、完全に ASCII 互換でないなど。入力データがエンコーディングを指定している場合でもそうして下さい、なぜなら攻撃者は巧みに悪意あるテキストをエンコードした文字列の中に隠すことができるからです。

ファイルエンコーディングの変換

The 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 StreamRecoder to return bytes encoded in UTF-8:

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') )

不明なエンコーディングのファイル

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 surrogateescape error handler:

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)

The 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 surrogateescape error handler is used to encode the data and write it back out.

参考資料

One section of Mastering Python 3 Input/Output [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.

Marc-André Lemburg のプレゼンテーション "Writing Unicode-aware Applications in Python" の PDF スライドが <https://downloads.egenix.com/python/LSM2005-Developing-Unicode-aware-applications-in-Python.pdf> から入手可能です、そして文字エンコーディングの問題と同様にアプリケーションの国際化やローカライズについても議論されています。このスライドは Python 2.x のみをカバーしています。

The Guts of Unicode in Python [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.

謝辞

このドキュメントの最初の草稿は Andrew Kuchling によって書かれました。それからさらに Alexander Belopolsky, Georg Brandl, Andrew Kuchling, Ezio Melotti らで改訂が重ねられています。

この記事中の誤りの指摘や提案を申し出てくれた以下の人々に感謝します: É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.

urllib パッケージを使ってインターネット上のリソースを取得するには

著者:

Michael Foord [https://agileabstractions.com/]

はじめに

Related Articles

同じように Python でインターネットリソースを取得するのに以下の記事が役に立ちます:

Basic Authentication [https://web.archive.org/web/20201215133350/http://www.voidspace.org.uk/python/articles/authentication.shtml]

Basic 認証 についてのチュートリアルで Python の例がついています。

urllib.request は URLs (Uniform Resource Locators) を取得するための Python モジュールです。このモジュールはとても簡単なインターフェースを urlopen 関数の形式で提供しています。また、このモジュールは一般的な状況で利用するためにいくらか複雑なインターフェースも提供しています - basic 認証やクッキー、プロキシ等。これらは handler や opener と呼ばれるオブジェクトとして提供されます。

urllib.request は多くの "URL スキーム" (URL の ":" の前の文字列で識別されるもの - 例えば "ftp://python.org/" では "ftp") の URL を、関連するネットワークプロトコル(例えば FTP, HTTP) を利用することで、取得できます。

単純な状況では urlopen はとても簡単に使うことができます。しかし HTTP の URL を開くときにエラーが起きたり、特殊なケースに遭遇すると、 HyperText Transfer Protocol に関するいくつかのことを理解する必要があります。 HTTP に関して最も包括的で信頼できる文献は RFC 2616 [https://datatracker.ietf.org/doc/html/rfc2616.html] です。この文書は技術文書なので簡単には読めません。この HOWTO の目的は urllib の利用法を例示することです、 HTTP についてはその助けになるのに十分に詳しく載せています。このドキュメントは urllib.request のドキュメントの代わりにはなりませんが、補完する役割を持っています。

URL を取得する

urllib.request を利用する最も簡単な方法は以下です:

import urllib.request
with urllib.request.urlopen('http://python.org/') as response:
   html = response.read()

URL によってリソースを取得し、それを一時的な場所に保存しておきたいときは、 shutil.copyfileobj() と tempfile.NamedTemporaryFile() 関数を使って行うことができます:

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

多くの urllib の利用法はこのように簡単です ('http:' の代わりに URL を 'ftp:' や 'file:' 等で始めればできます)。しかし、このチュートリアルの目的は、特に HTTP に絞って、より複雑な状況を説明することです。

HTTP はリクエスト (request) とレスポンス (response) が基本となっています - クライアントがリクエストし、サーバーがレスポンスを送ります。urllib.request はこれを真似て、作成する HTTP リクエストを表現する Request オブジェクトを備えています。リクエストオブジェクトを作成する最も簡単な方法は取得したい URL を指定することです。urlopen をこのオブジェクトを使って呼び出すと、リクエストした URL のレスポンスオブジェクトが返されます。このレスポンスはファイルライクオブジェクトで、これはつまりレスポンスに .read() と呼び出せることを意味しています:

import urllib.request

req = urllib.request.Request('http://python.org/')
with urllib.request.urlopen(req) as response:
   the_page = response.read()

urllib.request は同じリクエストインターフェースを全ての URL スキームに対して利用できるようにしています。例えば、FTP リクエストの場合はこうできます:

req = urllib.request.Request('ftp://example.com/')

HTTP の場合には、リクエストオブジェクトに対して二つの特別な操作ができます: 一つ目はサーバーに送るデータを渡すことができる、二つ目はサーバーに送るデータやリクエスト自身に ついての 特別な情報 ("metadata")を渡すことができます - これらの送られる情報は HTTP 「ヘッダ」です。今度はこれらに関してひとつひとつ見ていきましょう。

データ

URL にデータを送りたい場合はよくあります (しばしば、その URL は CGI (Common Gateway Interface) スクリプトや他の web アプリケーションを参照することになります)。これは HTTP では、 POST リクエストとして知られる方法で行なわれます。これは web 上で HTML フォームを埋めて送信するときにブラウザが行なっていることです。全ての POST がフォームから送られるとは限りません: 自身のアプリケーションに対して任意のデータを POST を使って送ることができます。一般的な HTML フォームの場合、データは標準的な方法でエンコードされている必要があり、リクエストオブジェクトに data 引数として渡します。エンコーディングは urllib.parse ライブラリの関数を使って行います。

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()

他のエンコーディングが必要な場合があることに注意して下さい (例えば、 HTML フォームからファイルをアップロードするための詳細については HTML Specification, Form Submission [https://www.w3.org/TR/REC-html40/interact/forms.html#h-17.13] を見て下さい)。

data 引数を渡さない場合、urllib は GET リクエストを利用します。GET と POST リクエストの一つの違いは、POST リクエストにしばしば、「副作用」があることです: POST リクエストはいくつかの方法によってシステムの状態を変化させます (例えば100ポンドのスパムの缶詰をドアの前まで配達する注文を web サイトで行う)。とはいえ HTTP 標準で明確にされている内容では、POST は 常に 副作用を持ち、GET リクエストは 決して 副作用を持たないことを意図するけれども、、GET リクエストが副作用を持つことも、POST リクエストが副作用を持たないことも、妨げられません。HTTP の GET リクエストでもデータ自身をエンコーディングすることでデータを渡すことができます。

以下のようにして行います:

>>> 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)

? を URL に加え、それにエンコードされた値が続くことで、完全な URL が作られていることに注意して下さい。

ヘッダ

ここでは特定の HTTP ヘッダについて議論します、 HTTP リクエストにヘッダを追加する方法について例示します。

いくつかの web サイト [1] はプログラムからブラウズされることを嫌っていたり、異なるブラウザに対して異なるバージョンを送ります [2]。デフォルトでは urllib は自身の情報を Python-urllib/x.y として扱います ( x と y は Python のリリースバージョンのメジャーバージョンとマイナーバージョンです、例えば Python-urllib/2.5 など)。これによって web サイト側が混乱したり、動作しないかもしれません。ブラウザは自身の情報を User-Agent ヘッダ [3] を通して扱っています。リクエストオブジェクトを作るときに、ヘッダに辞書を渡すことができます。以下の例は上の例と同じですが、自身を Internet Explorer [4] のバージョンの一つとして扱っています。

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()

レスポンスは二つの便利なメソッドも持っています。 info と geturl の節を見て下さい、この節は後で問題が起きた場合に見ておくべき内容です。

例外を処理する

urlopen raises URLError when it cannot handle a response (though as usual with Python APIs, built-in exceptions such as ValueError, TypeError etc. may also be raised).

HTTPError is the subclass of URLError raised in the specific case of HTTP URLs.

例外クラスは urllib.error モジュールから提供されています。

URLError

URLError が送出されることはよく起こります、それはネットワーク接続が無い場合や、指定したサーバが無い場合です。この場合、例外は 'reason' 属性を持っていて、この属性はエラーコードとエラーメッセージのテキストを含むタプルです。

例:

>>> 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')

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 HTTPError. Typical errors include '404' (page not found), '403' (request forbidden), and '401' (authentication required).

HTTP のエラーコード全てについては RFC 2616 [https://datatracker.ietf.org/doc/html/rfc2616.html] の10節を参照して下さい。

The HTTPError instance raised will have an integer 'code' attribute, which corresponds to the error sent by the server.

エラーコード

デフォルトハンドラーはリダイレクト(コードは300番台にあります) を処理し、100--299番台のコードは成功を意味しているので、たいていの場合は400--599番台のエラーコードのみを見るだけですみます。

http.server.BaseHTTPRequestHandler.responses は RFC 2616 [https://datatracker.ietf.org/doc/html/rfc2616.html] で利用されるレスポンスコード全てを示す便利な辞書です。この辞書は便利なのでここに載せておきます

# Table mapping response codes to messages; entries have the
# form {code: (shortmessage, longmessage)}.
responses = {
    100: ('Continue', 'Request received, please continue'),
    101: ('Switching Protocols',
          'Switching to new protocol; obey Upgrade header'),

    200: ('OK', 'Request fulfilled, document follows'),
    201: ('Created', 'Document created, URL follows'),
    202: ('Accepted',
          'Request accepted, processing continues off-line'),
    203: ('Non-Authoritative Information', 'Request fulfilled from cache'),
    204: ('No Content', 'Request fulfilled, nothing follows'),
    205: ('Reset Content', 'Clear input form for further input.'),
    206: ('Partial Content', 'Partial content follows.'),

    300: ('Multiple Choices',
          'Object has several resources -- see URI list'),
    301: ('Moved Permanently', 'Object moved permanently -- see URI list'),
    302: ('Found', 'Object moved temporarily -- see URI list'),
    303: ('See Other', 'Object moved -- see Method and URL list'),
    304: ('Not Modified',
          'Document has not changed since given time'),
    305: ('Use Proxy',
          'You must use proxy specified in Location to access this '
          'resource.'),
    307: ('Temporary Redirect',
          'Object moved temporarily -- see URI list'),

    400: ('Bad Request',
          'Bad request syntax or unsupported method'),
    401: ('Unauthorized',
          'No permission -- see authorization schemes'),
    402: ('Payment Required',
          'No payment -- see charging schemes'),
    403: ('Forbidden',
          'Request forbidden -- authorization will not help'),
    404: ('Not Found', 'Nothing matches the given URI'),
    405: ('Method Not Allowed',
          'Specified method is invalid for this server.'),
    406: ('Not Acceptable', 'URI not available in preferred format.'),
    407: ('Proxy Authentication Required', 'You must authenticate with '
          'this proxy before proceeding.'),
    408: ('Request Timeout', 'Request timed out; try again later.'),
    409: ('Conflict', 'Request conflict.'),
    410: ('Gone',
          'URI no longer exists and has been permanently removed.'),
    411: ('Length Required', 'Client must specify Content-Length.'),
    412: ('Precondition Failed', 'Precondition in headers is false.'),
    413: ('Request Entity Too Large', 'Entity is too large.'),
    414: ('Request-URI Too Long', 'URI is too long.'),
    415: ('Unsupported Media Type', 'Entity body in unsupported format.'),
    416: ('Requested Range Not Satisfiable',
          'Cannot satisfy request range.'),
    417: ('Expectation Failed',
          'Expect condition could not be satisfied.'),

    500: ('Internal Server Error', 'Server got itself in trouble'),
    501: ('Not Implemented',
          'Server does not support this operation'),
    502: ('Bad Gateway', 'Invalid responses from another server/proxy.'),
    503: ('Service Unavailable',
          'The server cannot process the request due to a high load'),
    504: ('Gateway Timeout',
          'The gateway server did not receive a timely response'),
    505: ('HTTP Version Not Supported', 'Cannot fulfill request.'),
    }

エラーが起きた場合、サーバーは HTTP エラーコード および エラーページを返して応答します。 HTTPError インスタンスはエラーページのレスポンスとして扱えます。これは code 属性だけでなく、 urllib.response モジュールが返すような read, geturl, info メソッドも持つことを意味します:

>>> 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
  ...

エラーをラップする

So if you want to be prepared for HTTPError or URLError there are two basic approaches. I prefer the second approach.

その1

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

注釈

The except HTTPError must come first, otherwise except URLError will also catch an HTTPError.

その2

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

info と geturl

The response returned by urlopen (or the HTTPError instance) has two useful methods info() and geturl() and is defined in the module urllib.response.

geturl - これは取得したページの実際の URL を返します。 urlopen (または利用される opener オブジェクト) はリダイレクトに追従するため、有用です。取得したページの URL は要求した URL と同じとは限りません。

info - これは取得したページ (特にサーバからヘッダ)を表す辞書風オブジェクトを返します。これは現在では http.client.HTTPMessage インスタンスです。

典型的なヘッダは 'Content-length', 'Content-type' 等を含んでいます。 HTTP ヘッダの意味と利用法について簡単な説明つきの便利な一覧 Quick Reference to HTTP Headers [https://jkorpela.fi/http.html] を参照して下さい。

Openers と Handlers

URL を取得する場合、opener (混乱を招きやすい名前ですが、 urllib.request.OpenerDirector のインスタンス) を利用します。標準的にはデフォルトの opener を - urlopen を通して - 利用していますが、カスタムの opener を作成することもできます。 opener は handler を利用します。全ての「一番厄介な仕事」はハンドラによって行なわれます。各 handler は特定の URL スキーム (http, ftp, 等) での URL の開き方を知っていたり、 URL を開く局面でどう処理するかを知っています、例えば HTTP リダイレクションや HTTP のクッキーなど。

インストール済みの特定のハンドラで URL を取得したい場合には、 opener を作成したいと思うでしょう、例えばクッキーを処理する opener が得たい場合や、リダイレクションを処理しない opener を得たい場合。

opener を作成するには、 OpenerDirector をインスタンス化して、続けて、 .add_handler(some_handler_instance) を呼び出します。

それに代わる方法として、 build_opener を利用することもできます、これは opener オブジェクトを一回の関数呼び出しで作成できる便利な関数です。 build_opener はいくつかのハンドラをデフォルトで追加しますが、デフォルトのハンドラに対して追加、継承のどちらかまたは両方を行うのに手っ取り早い方法を提供してくれます。

追加したくなる可能性がある handler としては、プロキシ処理、認証など、一般的ですがいくらか特定の状況に限られるものでしょう。

install_opener も (グローバルな) デフォルト opener オブジェクトの作成に利用できます。つまり、 urlopen を呼び出すと、インストールした opener が利用されます。

opener オブジェクトは open メソッドを持っていて、 urlopen 関数と同じ様に、url を取得するのに直接呼び出すことができます: 利便性を除けば install_opener を使う必要はありません。

Basic 認証

To illustrate creating and installing a handler we will use the HTTPBasicAuthHandler. For a more detailed discussion of this subject -- including an explanation of how Basic Authentication works - see the Basic Authentication Tutorial [https://web.archive.org/web/20201215133350/http://www.voidspace.org.uk/python/articles/authentication.shtml].

認証が必要な場合、サーバは認証を要求するヘッダ (401 のエラーコードとともに) を送ります。これによって認証スキームと 'realm' が指定されます。ヘッダはこのようになっています: WWW-Authenticate: SCHEME realm="REALM" 。

例

WWW-Authenticate: Basic realm="cPanel Users"

クライアントはリクエストヘッダに含まれる realm に対して適切な名前とパスワードとともにリクエストを再試行する必要があります。これが 'basic 認証' です。一連の流れを簡単化するために、 HTTPBasicAuthHandler のインスタンスを作成し、 opener が handler を利用するようにします。

HTTPBasicAuthHandler はパスワードマネージャーと呼ばれる、 URL と realm をパスワードとユーザ名への対応づけを処理する、オブジェクトを利用します。 realm が何なのか(サーバから返される認証ヘッダから) 知りたい場合には、 HTTPPasswordMgr を利用できます。多くの場合、realm が何なのかについて気にすることはありません。そのような場合には HTTPPasswordMgrWithDefaultRealm を使うと便利です。これは URL に対してデフォルトのユーザ名とパスワードを指定できます。これによって特定の realm に対する代替の組み合わせを提供することなしに利用できるようになります。このことは add_password メソッドの realm 引数として None を与えることで明示することができます。

トップレベルの URL が認証が必要なはじめに URL です。この URL よりも「深い」URL を渡しても .add_password() は同様にマッチします。:

# 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)

注釈

In the above example we only supplied our HTTPBasicAuthHandler to build_opener. By default openers have the handlers for normal situations -- ProxyHandler (if a proxy setting such as an http_proxy environment variable is set), UnknownHandler, HTTPHandler, HTTPDefaultErrorHandler, HTTPRedirectHandler, FTPHandler, FileHandler, DataHandler, HTTPErrorProcessor.

top_level_url は実際には "http://example.com/" のような完全な URL ('http:' スキームとホスト名、オプションとしてポート番号、含む) あるいは "example.com" や "example.com:8080" (後者はポート番号を含む) のような "authority" (つまり、ホスト名とオプションとしてポート番号を含む) の どちらでも かまいません。authority の場合には "userinfo" 要素は含んではいけません - 例えば "joe:password@example.com" は不適切です。

プロキシ

urllib は自動でプロキシ設定を認識して使います。これは通常の handler の組に含まれる ProxyHandler を通して行なわれます。たいていの場合はこれでうまくいきますが、役に立たない場合もあります [5]。この問題に対処する一つの方法はプロキシを定義しない ProxyHandler を組み立てることです。この方法は Basic Authentication [https://web.archive.org/web/20201215133350/http://www.voidspace.org.uk/python/articles/authentication.shtml] handler を設定したときと同じような流れで行うことができます:

>>> proxy_support = urllib.request.ProxyHandler({})
>>> opener = urllib.request.build_opener(proxy_support)
>>> urllib.request.install_opener(opener)

注釈

現在 urllib.request はプロキシ経由で https ロケーションを取得する機能をサポートしていません。しかし、urllib.request をこのレシピ [6] で拡張することで可能にすることができます。

注釈

変数 REQUEST_METHOD が設定されている場合、 HTTP_PROXY は無視されます; getproxies() のドキュメンテーションを参照してください。

ソケットとレイヤー

Web 上からリソースを取得する Python の機能はレイヤー化されています。urllib は http.client ライブラリを利用していますが、そのライブラリはさらに socket ライブラリを利用しています。

Python 2.3 ではレスポンスがタイムアウトするまでのソケットの待ち時間を指定することができます。これは web ページを取得する場合に便利に使うことができます。socket モジュールのデフォルトでは タイムアウトが無く ハングしてしまうかもしれません。現在では socket のタイムアウトは http.client や urllib.request のレベルからは隠蔽されていています。しかし、以下を利用することで全てのソケットに対してグローバルにデフォルトタイムアウトを設定することができます

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)

脚注

このドキュメントは John Lee によって査読、改訂されました。

[1]

Google を例題にする。

[2]

ブラウザを検知すること (browser sniffing) は web サイトのデザインにおけるとても悪い習慣です - web 標準を利用する方が賢明でしょう。不幸なことに未だに多くの web サイトが異なるブラウザに対して異なるバージョンを返しています。

[3]

MSIE 6 のユーザエージェントは 'Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; .NET CLR 1.1.4322)' です。

[4]

HTTP リクエストヘッダの詳細については、 Quick Reference to HTTP Headers [https://jkorpela.fi/http.html] を参照して下さい。

[5]

私の場合は仕事中にインターネットにアクセスするにはプロキシを利用する必要があります。localhost の URL に対してこのプロキシを経由してアクセスしようとすれば、ブロックされます。IE を proxy を利用するように設定すれば、urllib はその情報を利用します。localhost のサーバでスクリプトをテストしようとすると、urllib がプロキシを利用するのを止めなければいけません。

[6]

urllib opener for SSL proxy (CONNECT method): ASPN Cookbook Recipe [https://code.activestate.com/recipes/456195-urrlib2-opener-for-ssl-proxy-connect-method/].

Argparse チュートリアル

author:

Tshepang Mbambo

このチュートリアルでは、argparse を丁寧に説明します。argparse は、Python 標準ライブラリの一部であり、おすすめのコマンドライン引数の解析モジュールです。

注釈

同じ機能を実現するモジュールが他に2つあります。 getopt (C 言語の getopt() に相当するもの) と非推奨の optparse です。なお argparse は optparse をもとにしており、従ってその使い方は非常によく似ています。

コンセプト

ls コマンドを使って、このチュートリアルで私たちが学ぶ機能をいくつか見てみましょう:

$ 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.
...

上の４つの実行結果から、以下のことが分かります:

ls コマンドは、まったくオプションを指定せずに実行したとしても役に立ちます。デフォルトの動作は、カレントディレクトリの内容を表示することです。

デフォルトの動作で提供される以上のことをしたい場合、すこしだけオプションを指定する必要があります。別のディレクトリ pypy を表示したい場合、私たちがしたことは、位置引数として知られる引数を指定することです。これは、引数がコマンドラインのどの位置に現れたかということだけを基に、プログラムがその値について何をするのか分かるべきなので、このように名づけられています。このコンセプトは cp のようなコマンドで重要な意味があります。 cp コマンドのもっとも基本的な使い方は、 cp SRC DEST です。最初の引数は 何をコピーしたいか であり、二つ目の引数は どこにコピーしたいか を意味します。

プログラムの振る舞いを変えましょう。例では、単にファイル名を表示する代わりにそれぞれのファイルに関する多くの情報を表示します。このケースでは、-l はoptional引数として知られます。

ヘルプテキストの抜粋です。この実行の仕方は、まだ使用したことがないプログラムにたいして行うと有用で、ヘルプテキストを読むことで、プログラムがどのように動作するかわかります。

基礎

（ほとんど）何もしない、とても簡単な例から始めましょう:

import argparse
parser = argparse.ArgumentParser()
parser.parse_args()

下記がこのコードを実行した結果です:

$ 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

こんなことが起こりました:

オプションなしでスクリプトを実行した結果、なにも標準出力に表示されませんでした。それほど便利ではありませんね。

二つ目の実行結果から argparse モジュールの有用性がわかります。ほとんど何もしていないのに、すてきなヘルプメッセージが手に入りました。

--help （これは -h と短縮できます）だけが無料のオプションです（つまりプログラムで指示する必要はありません）。他のオプションを指定するとエラーになります。エラー時の有用な用法メッセージも、プログラムで指示することなく出力できます。

位置引数の入門

以下に例を示します:

import argparse
parser = argparse.ArgumentParser()
parser.add_argument("echo")
args = parser.parse_args()
print(args.echo)

このコードを実行してみましょう:

$ 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

こんなことが起こりました:

プログラムが受け付けるコマンドラインオプションを指定するメソッドである add_argument() を追加しました。ここでは、その機能にあわせて引数名を echo としました。

プログラムを実行すると、オプションを指定するように要求されます。

parse_args() メソッドは指定されたオプションを、この場合は echo として、返します。

この変数は argparse が自動的に行うある種の魔法です（つまり、値を格納する変数を指定する必要がありません）。変数の名前がメソッドに与えた文字列引数 echo と同じことに気付いたでしょう。

ヘルプメッセージは十分なように見えますが、それほど分かりやすくもありません。たとえば、echo は位置引数であることがわかりますが、それが何であるかを知るためには推測するかソースコードを見なけれなりません。もうすこしヘルプメッセージ分かりやすくしてみましょう:

import argparse
parser = argparse.ArgumentParser()
parser.add_argument("echo", help="echo the string you use here")
args = parser.parse_args()
print(args.echo)

修正した結果は以下のようになります:

$ 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

次は、もっと有益なことをしてみませんか？:

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)

下記がこのコードを実行した結果です:

$ 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'

上手くいきませんでした。 何も伝えなければ、argparse は与えられたオプションを文字列として扱います。 argparse にオプションの値を整数として扱うように伝えましょう:

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)

下記がこのコードを実行した結果です:

$ python prog.py 4
16
$ python prog.py four
usage: prog.py [-h] square
prog.py: error: argument square: invalid int value: 'four'

今度は上手くいきました。このプログラムは不正な入力が与えられるとそれを処理せずに、より親切なメッセージを表示して実行を終了します。

Optional引数の導入

ここまで位置引数を扱ってきました。optional引数を追加する方法についても見ていきましょう:

import argparse
parser = argparse.ArgumentParser()
parser.add_argument("--verbosity", help="increase output verbosity")
args = parser.parse_args()
if args.verbosity:
    print("verbosity turned on")

実行してみましょう:

$ 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

こんなことが起こりました:

プログラムは、--verbosity が指定された場合はなにかしらを表示し、指定されなければ何も表示をしないように書かれています。

オプションの指定が実際に任意であることを示すために、プログラムをオプション指定なしで実行してもエラーにはなっていません。オプション引数が指定されなかった場合、関連する変数、この例では args.verbosity 、の値にはデフォルトで None がセットされます。これが if 文による真偽テストに失敗した理由です。

ヘルプメッセージが少し変わりました。

--verbosity オプションを使うには、そのオプションにひとつの値を指定しなければなりません。

上記の例では、--verbosity に任意の整数を取れます。この簡単なプログラムでは、実際には True または False の二つの値だけが有効です。そうなるようにコードを修正してみましょう:

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")

実行してみましょう:

$ 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

こんなことが起こりました:

オプションは値を必要とするのではなく、単なるフラグになりました。この考え方に沿うようにオプションの名前も変更しています。ここで新しいキーワード action を指定し、値として "store_true" を設定していることに注意してください。これは、オプションが指定された場合に値として True を args.verbose に設定するということを意味します。オプションの指定がない場合の値は False となることを意味します。

フラグは値を取るべきではないので、値を指定するとプログラムはエラーになります。

ヘルプテキストが変わっています。

短いオプション

コマンドラインになれていれば、オプションの短いバージョンの話題に触れていないことに気付いたでしょう。それはとても簡単です:

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")

上記のプログラムを実行するとこうなります:

$ 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

新しい機能がヘルプテキストにも反映されている点に気付いたでしょう。

位置引数とOptional引数の併用

プログラムが複雑になってきました:

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)

出力は以下のようになります:

$ 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

位置引数を元に戻したので、引数を指定しないとエラーになりました。

２つのオプションの順序を考慮しないことに注意してください。

複数の詳細レベルを値にとれるようにプログラムを元に戻して、指定された値を使ってみましょう:

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)

実行してみましょう:

$ 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

プログラムのバグである最後の結果を除いて、上手く行っているようです。このバグを、--verbosity オプションが取れる値を制限することで修正しましょう:

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)

実行してみましょう:

$ 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 {0,1,2}, --verbosity {0,1,2}
                        increase output verbosity

変更がエラーメッセージとヘルプメッセージの両方に反映されていることに注意してください。

詳細レベルついて、違ったアプローチを試してみましょう。これは CPython 実行可能ファイルがその詳細レベル引数を扱う方法と同じです。（ python --help の出力を確認してください）:

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)

もう一つの action である "count" を紹介します。これは指定されたオプションの出現回数を数えます:

$ 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

前のバージョンのスクリプトのようにフラグ (action="store_true" に似ています）になりました。エラーとなる理由がわかります。（訳注: ５つ目の例では -v オプションに引数を与えたため、エラーとなっています。）

これは"store_true" アクションによく似た動作をします。

では "count" アクションが何をもたらすかデモンストレーションをします。おそらくこのような使用方法を前に見たことがあるでしょう。

-v フラグを指定しなければ、フラグの値は None とみなされます。

期待通り、長い形式のフラグを指定しても同じ結果になります。

残念ながら、このヘルプ出力はプログラムが新しく得た機能についてそこまで有益ではありません。しかし、スクリプトのドキュメンテーションを改善することでいつでも修正することができます（例えば、help キーワード引数を使用することで）。

最後の出力はプログラムにバグがあることを示します。

修正しましょう:

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)

これが結果です:

$ 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'

最初の出力は上手くいっていますし、以前のバグが修正されています。最も詳細な出力を得るには、2 以上の値が必要です。

三番目の結果は、よくありません。

このバグを修正しましょう:

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)

もう一つのキーワード引数である default を導入しました。整数値と比較できるように、その値に 0 を設定しました。デフォルトでは、optional 引数が指定されていない場合 None となること、None が整数値と比較できない（よって TypeError 例外となる）ことを思い出してください。

こうなりました:

$ python prog.py 4
16

ここまで学んできたことだけで、さまざまな事が実現できます。しかしまだ表面をなぞっただけです。 argparse モジュールはとても強力ですので、チュートリアルを終える前にもう少しだけ探検してみましょう.

もうちょっとだけ学ぶ

もし、この小さなプログラムを二乗以外の累乗が行えるように拡張するとどうなるでしょうか:

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)

出力:

$ 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

これまで、出力されるテキストを 変更する ために詳細レベルを使ってきました。かわりに下記の例では、追加の テキストを出力するのに詳細レベルを使用します:

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)

出力:

$ 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

多義性のある引数の指定

ある引数の解釈について、位置引数なのか、ある引数に対する追加の引数なのか、あいまいさがあるときは、 -- を使うことで parse_args() に対してこれ以降は位置引数であることを伝えることができます:

>>> 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'])

競合するオプション

これまでのところ、 argparse.ArgumentParser インスタンスの2つのメソッドについて学んできました。ここで3つめのメソッドとして add_mutually_exclusive_group() を導入しましょう。このメソッドは互いに対立する引数の指定を可能にします。また、新しい機能として理解しやすいように、プログラムの残りの部分を変更しましょう: 以下では --quiet オプションを ``--verbose``と反対のオプションとして導入します:

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}")

プログラムはより簡潔になりましたが、デモのための機能が失われました。ともかく下記が実行結果です:

$ 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

これは分かりやすいでしょう。ここで得たちょっとした柔軟性を示すために最後の出力を追加しました、つまり長い形式のオプションと短い形式のオプションの混在です。

結びの前に、恐らくあなたはプログラムの主な目的をユーザに伝えたいでしょう。万が一、彼らがそれを知らないときに備えて:

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}")

使用方法のテキストが少し変化しました。[-v | -q] は -v または -q のどちらかを使用できるが、同時に両方を使用できないことを意味します:

$ 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

argparse の出力を翻訳するには

ヘルプテキストやエラーメッセージなどの argparse モジュールの出力は、すべて gettext モジュールを使って訳せるように作られています。これにより、 argparse によって生成されたメッセージを簡単にローカライズできます。 プログラムやモジュールを国際化する も参照してください。

たとえば、この argparse の出力では:

$ 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

文字列 usage:, positional arguments:, options: と show this help message and exit はすべて訳せます。

これらの文字列を訳すには、それらをまず .po ファイルに抽出する必要があります。たとえば、 Babel [https://babel.pocoo.org/] を使い、次のコマンドを実行します。

$ pybabel extract -o messages.po /usr/lib/python3.12/argparse.py

このコマンドは argparse モジュールからすべての翻訳可能な文字列を抽出し、それらを messages.po という名前のファイルに出力します。このコマンドは Python のインストールが /usr/lib にあることを前提としています。

システム上の argparse モジュールの場所は、次のスクリプトで調べられます:

import argparse
print(argparse.__file__)

.po ファイル内のメッセージが訳され、その訳が gettext を用いてインストールされると、 argparse は翻訳されたメッセージを表示できるようになります。

argparse 出力内のあなたの文字列を翻訳するには、 gettext を使います。

結び

argparse モジュールはここで学んだことより多くの機能を提供します。モジュールのドキュメントはとても詳細で、綿密で、そしてたくさんの例があります。このチュートリアルの体験したことで、気がめいることなくそれらの他の機能を会得できるに違いありません。

ipaddressモジュールの紹介

author:

Peter Moody

author:

Nick Coghlan

概要

このドキュメントは ipaddress モジュールへのやさしい入門を提供するのが目的です。これは主にまだIPネットワーキングの用語に詳しくないユーザーを対象としていますが、ipaddress がどのようにIPネットワークアドレス処理の概念を表現しているかをざっと見るのにも役立つかもしれません。

アドレス/ネットワーク/インターフェースオブジェクトの作成

ipaddress はIPアドレスを検査したり操作したりするためのモジュールであるため、まずはオブジェクトを作成したほうが良いでしょう。文字列および整数を使用して ipaddress を使用してオブジェクトを作成できます。

IPバージョンについての注意

IPアドレッシングに詳しくない読者にとっては、インターネットプロトコル(IP)が現在バージョン4プロトコルからバージョン6へと移行している途中であることを知っておくのが重要です。この移行はプロトコルのバージョン4が世界中の需要に対応するために十分なアドレスを提供できないことが大きな理由で起こっており、特にインターネットへ直接接続する機器が増えている状況を踏まえたものです。

上述した2つのプロトコルバージョンの違いの詳細を説明するのはこの入門ドキュメントの対象範囲を超えていますが、読者は少なくともこれらの2つのバージョンが存在することと、どちらかのバージョンを強制的に使用することが必要になることもあるということを認識する必要があります。

IPホストアドレス

アドレスは多くの場合「ホストアドレス」と呼ばれ、IPアドレッシングを扱う場合の最も基本的な単位です。アドレスを作成する単純な方法は ipaddress.ip_address() ファクトリー関数を使用することで、この方法では渡された値をもとにIPv4かIPv6アドレスのどちらかを自動的に決定します:

>>> ipaddress.ip_address('192.0.2.1')
IPv4Address('192.0.2.1')
>>> ipaddress.ip_address('2001:DB8::1')
IPv6Address('2001:db8::1')

アドレスは整数から直接作成することも可能です。32ビットに収まる値はIPv4アドレスであるとみなされます:

>>> ipaddress.ip_address(3221225985)
IPv4Address('192.0.2.1')
>>> ipaddress.ip_address(42540766411282592856903984951653826561)
IPv6Address('2001:db8::1')

IPv4またはIPv6アドレスの使用を強制するには、適切なクラスを直接呼び出す必要があります。これは特にIPv6アドレスを小さな整数で作成する場合に役立ちます:

>>> ipaddress.ip_address(1)
IPv4Address('0.0.0.1')
>>> ipaddress.IPv4Address(1)
IPv4Address('0.0.0.1')
>>> ipaddress.IPv6Address(1)
IPv6Address('::1')

ネットワークを定義する

ホストアドレスは通常IPネットワークへ統合され、 ipaddress はネットワーク定義の作成、検査、操作の手段を提供します。IPネットワークオブジェクトはネットワークの一部であるホストアドレスの範囲を定義する文字列から生成されます。この情報の最も単純な形式は「ネットワークアドレス/ネットワークプレフィックス」のペアであり、プレフィックスは先頭のビット数として定義され、アドレスがネットワークの一部であるかどうか、それらのビットに期待される値がネットワークアドレスに定義されているかを判断するために比較されます。

アドレスについては、正しいIPバージョンを自動的に判断するファクトリー関数が提供されます:

>>> 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')

ネットワークオブジェクトにはホストビットを設定することができません。これについての実践的な効果は 192.0.2.1/24 がネットワークを表さないということです。次の項でより詳しく説明しますが、ネットワーク内IP表記は一般的に特定のネットワーク上のネットワークインターフェースを表すのに使用されるため、このような定義はインターフェースオブジェクトと呼ばれます。

デフォルトでは、ホストビットセットの指定でネットワークオブジェクトを作成しようとすると ValueError が発生する結果となります。 strict=False フラグをコンストラクタに渡すと、追加分のビットをゼロとして強制的に処理するように要求できます:

>>> 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')

文字列形式では劇的に柔軟性を提供できる一方、ネットワークはちょうどホストアドレスのように整数で定義することもできます。この場合、ネットワークは整数により特定できる単一のアドレスのみを含むものとして処理され、ネットワークプレフィックスはネットワークアドレスの全体を含みます:

>>> ipaddress.ip_network(3221225984)
IPv4Network('192.0.2.0/32')
>>> ipaddress.ip_network(42540766411282592856903984951653826560)
IPv6Network('2001:db8::/128')

アドレスについては、ファクトリー関数を呼ぶ代わりにクラスコンストラクタを直接呼ぶことで、作成対象のネットワークを特定の種類に強制することができます。

ホストインターフェース

直前に述べたように、特定のネットワーク上のアドレスを示したい場合には、アドレスもネットワーククラスも十分ではありません。 192.0.2.1/24 のような表記は「 192.0.2.0/24 のネットワーク上の 192.0.2.1 のホスト」の短縮形として通常ネットワークエンジニアやファイアウォールやルータ用のツールを書く人が使用し、 ipaddress はそれに応じて特定のネットワークとアドレスを関連づけるハイブリッドクラス集を提供します。アドレス部分がネットワークアドレスであることに制限されないことを除き、作成用のインターフェースはネットワーク定義用のインターフェースと同一です。

>>> 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')

整数入力は(ネットワークと同様に)受け入れられ、適切なコンストラクタを直接呼び出すことで特定のIPバージョンの使用を強制できます。

アドレス/ネットワーク/インターフェースオブジェクト

さて、IPv(4|6)(アドレス|ネットワーク|インターフェース)オブジェクトをわざわざ作成したので、多分それについて情報がほしいことでしょう。 ipaddress はこの作業を簡単で直観的にできるようにします。

IPバージョンを抽出する:

>>> addr4 = ipaddress.ip_address('192.0.2.1')
>>> addr6 = ipaddress.ip_address('2001:db8::1')
>>> addr6.version
6
>>> addr4.version
4

インターフェースからネットワークを取得する:

>>> 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')

個別なアドレスがいくつネットワークに存在するかを調べる:

>>> 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

「使用可能」なネットワーク上のアドレスを順番にたどる:

>>> 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

ネットマスクを取得(例: ネットワークプレフィックスに応じてビットを設定)したりホストマスク(ネットマスクの一部ではない任意のビット)を取得する:

>>> 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')

アドレスを展開したり圧縮したりする:

>>> 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'

IPv4は展開や圧縮には対応していませんが、それでも関連したオブジェクトが適切なプロパティを提供し、バージョンに対して中立なコードがIPv4アドレスを正しく処理する一方でIPv6向けには最も簡潔または最も詳細な形式が使用されることを保証します。

アドレスのリストとしてのネットワーク

ネットワークをリストとして扱うと便利な場合があります。これは、ネットワークを次のようにインデックス付けすることが可能なことを意味します:

>>> 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')

以下のようなリストのメンバーシップの判定用文法が使用可能なように、ネットワークオブジェクト自身が適応します:

if address in network:
    # do something

ネットワークプレフィックスに基づき、所属しているかどうかの判定が効果的にできます:

>>> 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

比較

ipaddress はオブジェクトの比較をするための単純で、かつ願わくば直観的な方法を意味が通じるように提供します:

>>> ipaddress.ip_address('192.0.2.1') < ipaddress.ip_address('192.0.2.2')
True

異なるバージョンや異なるタイプのオブジェクトを比較しようとすると TypeError 例外が発生します。

他のモジュールでIPアドレスを使用する

IPアドレスを使用する他のモジュール(socket など)は通常このモジュールからオブジェクトを直接受け付けません。直接渡すのではなく、他のモジュールが受け付ける整数や文字列に強制的に変換する必要があります:

>>> addr4 = ipaddress.ip_address('192.0.2.1')
>>> str(addr4)
'192.0.2.1'
>>> int(addr4)
3221225985

インスタンスの生成に失敗した場合にさらに詳細を取得する

上述したバージョンに関知しないファクトリー関数を使用してアドレス/ネットワーク/インターフェースオブジェクトを作成する場合、渡された値がそのタイプのオブジェクトとして認識されなかったと単純に通知する汎用的なメッセージとともに、どのエラーでも ValueError として報告されます。特定のエラーが提供されないのは、拒否された理由をより詳細に提供するために、値がIPv4またはIPv6である はず かどうかを知る必要があるためです。

追加の詳細を得ると役立つ場合のユースケースに対応するため、個別のクラスのコンストラクタは実際に ValueError のサブクラスである ipaddress.AddressValueError と ipaddress.NetmaskValueError を発生させて具体的に定義のどの部分のパースに失敗したのかを示します。

クラスコンストラクタを直接使用する場合にはこれらのエラーメッセージはさらに非常に詳細になっています。例えば:

>>> 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

しかし、モジュールについて固有の上記例外のどちらも ValueError を親クラスとして持ち、エラーの特定のタイプに興味がない場合でも、以下のようにコードを記述できます:

try:
    network = ipaddress.IPv4Network(address)
except ValueError:
    print('address/netmask is invalid for IPv4:', address)

DTrace と SystemTap で CPython を測定する

author:

David Malcolm

author:

Łukasz Langa

Dtrace と SystemTap はモニタリングツールで、コンピュータシステムのプロセスが何をしているかを調べる方法を提供します。どちらもドメイン固有言語 (domain-specific language) を使用して、次のことができるスクリプトをユーザが書けます:

観測対象のプロセスを絞り込む

関心のあるプロセスからデータを収集する

収集したデータからレポートを生成する

Python 3.6 では、 CPython は "プローブ" としても知られる "マーカー" を埋め込んだビルドが行えます。マーカーは DTrace や SystemTap のスクリプトから観測でき、システムの CPython プロセスが何をしているかを観察するのが簡単になります。

CPython 実装の詳細: DTrace マーカーは CPython インタプリタの実装詳細です。 CPython のバージョン間でプローブの互換性があるという保証はありません。 CPython のバージョンを変えると、 DTrace スクリプトは警告無しに動作しなくなったり、おかしな動作をする可能性があります。

静的マーカーの有効化

macOS には組み込みの DTrace サポートが備わっています。 Linux では SystemTap 用のマーカーを埋め込んで CPython をビルドするためには、 SystemTap 開発ツールをインストールしなければなりません。

Linux マシンでは、 SystemTap 開発ツールのインストールは次のように行えます:

$ yum install systemtap-sdt-devel

もしくは:

$ sudo apt-get install systemtap-sdt-dev

CPython must then be configured with the --with-dtrace option:

checking for --with-dtrace... yes

On macOS, you can list available DTrace probes by running a Python process in the background and listing all probes made available by the Python provider:

$ python3.6 -q &
$ sudo dtrace -l -P python$!  # or: dtrace -l -m python3.6

   ID   PROVIDER            MODULE                          FUNCTION NAME
29564 python18035        python3.6          _PyEval_EvalFrameDefault function-entry
29565 python18035        python3.6             dtrace_function_entry function-entry
29566 python18035        python3.6          _PyEval_EvalFrameDefault function-return
29567 python18035        python3.6            dtrace_function_return function-return
29568 python18035        python3.6                           collect gc-done
29569 python18035        python3.6                           collect gc-start
29570 python18035        python3.6          _PyEval_EvalFrameDefault line
29571 python18035        python3.6                 maybe_dtrace_line line

On Linux, you can verify if the SystemTap static markers are present in the built binary by seeing if it contains a ".note.stapsdt" section.

$ readelf -S ./python | grep .note.stapsdt
[30] .note.stapsdt        NOTE         0000000000000000 00308d78

If you've built Python as a shared library (with the --enable-shared configure option), you need to look instead within the shared library. For example:

$ readelf -S libpython3.3dm.so.1.0 | grep .note.stapsdt
[29] .note.stapsdt        NOTE         0000000000000000 00365b68

十分に新しい readelf ではメタデータを出力できます:

$ 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

The above metadata contains information for SystemTap describing how it can patch strategically placed machine code instructions to enable the tracing hooks used by a SystemTap script.

静的 DTrace プローブ

The following example DTrace script can be used to show the call/return hierarchy of a Python script, only tracing within the invocation of a function called "start". In other words, import-time function invocations are not going to be listed:

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;
}

この例は次のように実行できます:

$ sudo dtrace -q -s call_stack.d -c "python3.6 script.py"

出力はこのようになります:

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

静的 SystemTap マーカー

The low-level way to use the SystemTap integration is to use the static markers directly. This requires you to explicitly state the binary file containing them.

例えば、この SystemTap スクリプトは Python の呼び出し/返却 (call/return) 階層を表示するのに使えます:

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);
}

この例は次のように実行できます:

$ stap \
  show-call-hierarchy.stp \
  -c "./python test.py"

出力はこのようになります:

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

それぞれの列の内容は次の通りです:

スクリプトを起動してからのマイクロ秒単位の時間

実行可能ファイルの名前

プロセスの PID

そして、残りの部分はスクリプトが実行していた呼び出し/返却階層を表示しています。

For a --enable-shared build of CPython, the markers are contained within the libpython shared library, and the probe's dotted path needs to reflect this. For example, this line from the above example:

probe process("python").mark("function__entry") {

should instead read:

probe process("python").library("libpython3.6dm.so.1.0").mark("function__entry") {

(assuming a debug build of CPython 3.6)

利用可能な静的マーカー

function__entry(str filename, str funcname, int lineno)

このマーカーは Python の関数の実行が開始されたことを示しています。このマーカーは、ピュア Python (バイトコード) の関数でしか起動されません。

トレーススクリプトには位置引数として、ファイル名、関数名、行番号が渡され、必ず $arg1, $arg2, $arg3 で渡されます:

$arg1 : (const char *) ファイル名、 user_string($arg1) でアクセスできます

$arg2 : (const char *) 関数名、 user_string($arg2) でアクセスできます

$arg3 : int 行番号

function__return(str filename, str funcname, int lineno)

This marker is the converse of function__entry(), and indicates that execution of a Python function has ended (either via return, or via an exception). It is only triggered for pure-Python (bytecode) functions.

The arguments are the same as for function__entry()

line(str filename, str funcname, int lineno)

このマーカーは、これから実行される Python の行を示しています。これは Python プロファイラによる行ごとのトレースと同等です。このマーカーは C 関数の内部では起動されません。

The arguments are the same as for function__entry().

gc__start(int generation)

Python インタプリタによる循環参照のガベージコレクションが開始されたときに発火します。 gc.collect() と同じように arg0 は走査する対象の世代です。

gc__done(long collected)

Python インタプリタによる循環参照のガベージコレクションが完了したときに発火します。 arg0 は回収したオブジェクトの数です。

import__find__load__start(str modulename)

Fires before importlib attempts to find and load the module. arg0 is the module name.

Added in version 3.7.

import__find__load__done(str modulename, int found)

Fires after importlib's find_and_load function is called. arg0 is the module name, arg1 indicates if module was successfully loaded.

Added in version 3.7.

audit(str event, void *tuple)

Fires when sys.audit() or PySys_Audit() is called. arg0 is the event name as C string, arg1 is a PyObject pointer to a tuple object.

Added in version 3.8.

SystemTap Tapset

The higher-level way to use the SystemTap integration is to use a "tapset": SystemTap's equivalent of a library, which hides some of the lower-level details of the static markers.

Here is a tapset file, based on a non-shared build of CPython:

/*
   Provide a higher-level wrapping around the function__entry and
   function__return markers:
 \*/
probe python.function.entry = process("python").mark("function__entry")
{
    filename = user_string($arg1);
    funcname = user_string($arg2);
    lineno = $arg3;
    frameptr = $arg4
}
probe python.function.return = process("python").mark("function__return")
{
    filename = user_string($arg1);
    funcname = user_string($arg2);
    lineno = $arg3;
    frameptr = $arg4
}

If this file is installed in SystemTap's tapset directory (e.g. /usr/share/systemtap/tapset), then these additional probepoints become available:

python.function.entry(str filename, str funcname, int lineno, frameptr)

This probe point indicates that execution of a Python function has begun. It is only triggered for pure-Python (bytecode) functions.

python.function.return(str filename, str funcname, int lineno, frameptr)

This probe point is the converse of python.function.return, and indicates that execution of a Python function has ended (either via return, or via an exception). It is only triggered for pure-Python (bytecode) functions.

使用例

This SystemTap script uses the tapset above to more cleanly implement the example given above of tracing the Python function-call hierarchy, without needing to directly name the static markers:

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);
}

The following script uses the tapset above to provide a top-like view of all running CPython code, showing the top 20 most frequently entered bytecode frames, each second, across the whole system:

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;
}

Python support for the Linux perf profiler

author:

Pablo Galindo

The Linux perf profiler [https://perf.wiki.kernel.org] is a very powerful tool that allows you to profile and obtain information about the performance of your application. perf also has a very vibrant ecosystem of tools that aid with the analysis of the data that it produces.

The main problem with using the perf profiler with Python applications is that perf only gets information about native symbols, that is, the names of functions and procedures written in C. This means that the names and file names of Python functions in your code will not appear in the output of perf.

Since Python 3.12, the interpreter can run in a special mode that allows Python functions to appear in the output of the perf profiler. When this mode is enabled, the interpreter will interpose a small piece of code compiled on the fly before the execution of every Python function and it will teach perf the relationship between this piece of code and the associated Python function using perf map files.

注釈

Support for the perf profiler is currently only available for Linux on select architectures. Check the output of the configure build step or check the output of python -m sysconfig | grep HAVE_PERF_TRAMPOLINE to see if your system is supported.

For example, consider the following script:

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)

We can run perf to sample CPU stack traces at 9999 hertz:

$ perf record -F 9999 -g -o perf.data python my_script.py

Then we can use perf report to analyze the data:

$ 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
...

As you can see, the Python functions are not shown in the output, only _PyEval_EvalFrameDefault (the function that evaluates the Python bytecode) shows up. Unfortunately that's not very useful because all Python functions use the same C function to evaluate bytecode so we cannot know which Python function corresponds to which bytecode-evaluating function.

Instead, if we run the same experiment with perf support enabled we get:

$ 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

How to enable perf profiling support

perf profiling support can be enabled either from the start using the environment variable PYTHONPERFSUPPORT or the -X perf option, or dynamically using sys.activate_stack_trampoline() and sys.deactivate_stack_trampoline().

The sys functions take precedence over the -X option, the -X option takes precedence over the environment variable.

Example, using the environment variable:

$ PYTHONPERFSUPPORT=1 python script.py
$ perf report -g -i perf.data

Example, using the -X option:

$ python -X perf script.py
$ perf report -g -i perf.data

Example, using the sys APIs in file example.py:

import sys

sys.activate_stack_trampoline("perf")
do_profiled_stuff()
sys.deactivate_stack_trampoline()

non_profiled_stuff()

...then:

$ python ./example.py
$ perf report -g -i perf.data

How to obtain the best results

For best results, Python should be compiled with CFLAGS="-fno-omit-frame-pointer -mno-omit-leaf-frame-pointer" as this allows profilers to unwind using only the frame pointer and not on DWARF debug information. This is because as the code that is interposed to allow perf support is dynamically generated it doesn't have any DWARF debugging information available.

You can check if your system has been compiled with this flag by running:

$ python -m sysconfig | grep 'no-omit-frame-pointer'

If you don't see any output it means that your interpreter has not been compiled with frame pointers and therefore it may not be able to show Python functions in the output of perf.

Annotations Best Practices

author:

Larry Hastings

概要

This document is designed to encapsulate the best practices for working with annotations dicts. If you write Python code that examines __annotations__ on Python objects, we encourage you to follow the guidelines described below.

The document is organized into four sections: best practices for accessing the annotations of an object in Python versions 3.10 and newer, best practices for accessing the annotations of an object in Python versions 3.9 and older, other best practices for __annotations__ that apply to any Python version, and quirks of __annotations__.

Note that this document is specifically about working with __annotations__, not uses for annotations. If you're looking for information on how to use "type hints" in your code, please see the typing module.

Accessing The Annotations Dict Of An Object In Python 3.10 And Newer

Python 3.10 adds a new function to the standard library: inspect.get_annotations(). In Python versions 3.10 and newer, calling this function is the best practice for accessing the annotations dict of any object that supports annotations. This function can also "un-stringize" stringized annotations for you.

If for some reason inspect.get_annotations() isn't viable for your use case, you may access the __annotations__ data member manually. Best practice for this changed in Python 3.10 as well: as of Python 3.10, o.__annotations__ is guaranteed to always work on Python functions, classes, and modules. If you're certain the object you're examining is one of these three specific objects, you may simply use o.__annotations__ to get at the object's annotations dict.

However, other types of callables--for example, callables created by functools.partial()--may not have an __annotations__ attribute defined. When accessing the __annotations__ of a possibly unknown object, best practice in Python versions 3.10 and newer is to call getattr() with three arguments, for example getattr(o, '__annotations__', None).

Before Python 3.10, accessing __annotations__ on a class that defines no annotations but that has a parent class with annotations would return the parent's __annotations__. In Python 3.10 and newer, the child class's annotations will be an empty dict instead.

Accessing The Annotations Dict Of An Object In Python 3.9 And Older

In Python 3.9 and older, accessing the annotations dict of an object is much more complicated than in newer versions. The problem is a design flaw in these older versions of Python, specifically to do with class annotations.

Best practice for accessing the annotations dict of other objects--functions, other callables, and modules--is the same as best practice for 3.10, assuming you aren't calling inspect.get_annotations(): you should use three-argument getattr() to access the object's __annotations__ attribute.

Unfortunately, this isn't best practice for classes. The problem is that, since __annotations__ is optional on classes, and because classes can inherit attributes from their base classes, accessing the __annotations__ attribute of a class may inadvertently return the annotations dict of a base class. As an example:

class Base:
    a: int = 3
    b: str = 'abc'

class Derived(Base):
    pass

print(Derived.__annotations__)

This will print the annotations dict from Base, not Derived.

Your code will have to have a separate code path if the object you're examining is a class (isinstance(o, type)). In that case, best practice relies on an implementation detail of Python 3.9 and before: if a class has annotations defined, they are stored in the class's __dict__ dictionary. Since the class may or may not have annotations defined, best practice is to call the get method on the class dict.

To put it all together, here is some sample code that safely accesses the __annotations__ attribute on an arbitrary object in Python 3.9 and before:

if isinstance(o, type):
    ann = o.__dict__.get('__annotations__', None)
else:
    ann = getattr(o, '__annotations__', None)

After running this code, ann should be either a dictionary or None. You're encouraged to double-check the type of ann using isinstance() before further examination.

Note that some exotic or malformed type objects may not have a __dict__ attribute, so for extra safety you may also wish to use getattr() to access __dict__.

Manually Un-Stringizing Stringized Annotations

In situations where some annotations may be "stringized", and you wish to evaluate those strings to produce the Python values they represent, it really is best to call inspect.get_annotations() to do this work for you.

If you're using Python 3.9 or older, or if for some reason you can't use inspect.get_annotations(), you'll need to duplicate its logic. You're encouraged to examine the implementation of inspect.get_annotations() in the current Python version and follow a similar approach.

In a nutshell, if you wish to evaluate a stringized annotation on an arbitrary object o:

If o is a module, use o.__dict__ as the globals when calling eval().

If o is a class, use sys.modules[o.__module__].__dict__ as the globals, and dict(vars(o)) as the locals, when calling eval().

If o is a wrapped callable using functools.update_wrapper(), functools.wraps(), or functools.partial(), iteratively unwrap it by accessing either o.__wrapped__ or o.func as appropriate, until you have found the root unwrapped function.

If o is a callable (but not a class), use o.__globals__ as the globals when calling eval().

However, not all string values used as annotations can be successfully turned into Python values by eval(). String values could theoretically contain any valid string, and in practice there are valid use cases for type hints that require annotating with string values that specifically can't be evaluated. For example:

PEP 604 [https://peps.python.org/pep-0604/] union types using |, before support for this was added to Python 3.10.

Definitions that aren't needed at runtime, only imported when typing.TYPE_CHECKING is true.

If eval() attempts to evaluate such values, it will fail and raise an exception. So, when designing a library API that works with annotations, it's recommended to only attempt to evaluate string values when explicitly requested to by the caller.

Best Practices For __annotations__ In Any Python Version

You should avoid assigning to the __annotations__ member of objects directly. Let Python manage setting __annotations__.

If you do assign directly to the __annotations__ member of an object, you should always set it to a dict object.

If you directly access the __annotations__ member of an object, you should ensure that it's a dictionary before attempting to examine its contents.

You should avoid modifying __annotations__ dicts.

You should avoid deleting the __annotations__ attribute of an object.

__annotations__ Quirks

In all versions of Python 3, function objects lazy-create an annotations dict if no annotations are defined on that object. You can delete the __annotations__ attribute using del fn.__annotations__, but if you then access fn.__annotations__ the object will create a new empty dict that it will store and return as its annotations. Deleting the annotations on a function before it has lazily created its annotations dict will throw an AttributeError; using del fn.__annotations__ twice in a row is guaranteed to always throw an AttributeError.

Everything in the above paragraph also applies to class and module objects in Python 3.10 and newer.

In all versions of Python 3, you can set __annotations__ on a function object to None. However, subsequently accessing the annotations on that object using fn.__annotations__ will lazy-create an empty dictionary as per the first paragraph of this section. This is not true of modules and classes, in any Python version; those objects permit setting __annotations__ to any Python value, and will retain whatever value is set.

If Python stringizes your annotations for you (using from __future__ import annotations), and you specify a string as an annotation, the string will itself be quoted. In effect the annotation is quoted twice. For example:

from __future__ import annotations
def foo(a: "str"): pass

print(foo.__annotations__)

This prints {'a': "'str'"}. This shouldn't really be considered a "quirk"; it's mentioned here simply because it might be surprising.

拡張モジュールを分離する

概要

Traditionally, state belonging to Python extension modules was kept in C 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.

Who should read this

This guide is written for maintainers of C-API extensions who would like to make that extension safer to use in applications where Python itself is used as a library.

背景

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:

in sequence, with several Py_InitializeEx()/Py_FinalizeEx() cycles, and

in parallel, managing "sub-interpreters" using Py_NewInterpreter()/Py_EndInterpreter().

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 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.

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 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.)

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:

>>> import sys
>>> import binascii
>>> old_binascii = binascii
>>> del sys.modules['binascii']
>>> import binascii  # create a new module object
>>> old_binascii == binascii
False

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 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.

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 example above, note that old_binascii.Error and binascii.Error are separate objects. In the following code, the exception is not caught:

>>> 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

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 sys.modules "manually" counts as a hack.

Making Modules Safe with Multiple Interpreters

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:

The readline module manages the terminal.

A module running on a circuit board wants to control the on-board LED.

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 Opt-Out: Limiting to One Module Object per Process.

Managing Per-Module State

To use per-module state, use multi-phase extension module initialization. This signals that your module supports multiple interpreters correctly.

Set 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 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. csv's field_size_limit) which the C code needs to function.

注釈

Another option is to store state in the module's __dict__, but you must avoid crashing when users modify __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 __dict__ only is a good idea.

If the module state includes PyObject pointers, the module object must hold references to those objects and implement the module-level hooks m_traverse, m_clear and m_free. These work like tp_traverse, tp_clear and 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 [https://github.com/python/cpython/blob/master/Modules/xxlimited.c]; example module initialization shown at the bottom of the file.

Opt-Out: Limiting to One Module Object per Process

A non-negative 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:

static int loaded = 0;

static int
exec_module(PyObject* module)
{
    if (loaded) {
        PyErr_SetString(PyExc_ImportError,
                        "cannot load module more than once per process");
        return -1;
    }
    loaded = 1;
    // ... rest of initialization
}

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 PyModule_GetState:

static PyObject *
func(PyObject *module, PyObject *args)
{
    my_struct *state = (my_struct*)PyModule_GetState(module);
    if (state == NULL) {
        return NULL;
    }
    // ... rest of logic
}

注釈

PyModule_GetState may return NULL without setting an exception if there is no module state, i.e. PyModuleDef.m_size was zero. In your own module, you're in control of m_size, so this is easy to prevent.

Heap Types

Traditionally, types defined in C code are static; that is, static PyTypeObject structures defined directly in code and initialized using 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 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 class statement.

For new modules, using heap types by default is a good rule of thumb.

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):

Unlike static types, heap type objects are mutable by default. Use the Py_TPFLAGS_IMMUTABLETYPE flag to prevent mutability.

Heap types inherit tp_new by default, so it may become possible to instantiate them from Python code. You can prevent this with the Py_TPFLAGS_DISALLOW_INSTANTIATION flag.

Defining Heap Types

Heap types can be created by filling a PyType_Spec structure, a description or "blueprint" of a class, and calling PyType_FromModuleAndSpec() to construct a new class object.

注釈

Other functions, like PyType_FromSpec(), can also create heap types, but PyType_FromModuleAndSpec() associates the module with the class, allowing access to the module state from methods.

The class should generally be stored in both the module state (for safe access from C) and the module's __dict__ (for access from Python code).

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:

Have the Py_TPFLAGS_HAVE_GC flag.

Define a traverse function using Py_tp_traverse, which visits the type (e.g. using Py_VISIT(Py_TYPE(self))).

Please refer to the the documentation of Py_TPFLAGS_HAVE_GC and 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.

tp_traverse in Python 3.8 and lower

The requirement to visit the type from 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:

static int my_traverse(PyObject *self, visitproc visit, void *arg)
{
    if (Py_Version >= 0x03090000) {
        Py_VISIT(Py_TYPE(self));
    }
    return 0;
}

Unfortunately, Py_Version was only added in Python 3.11. As a replacement, use:

PY_VERSION_HEX, if not using the stable ABI, or

sys.version_info (via PySys_GetObject() and PyArg_ParseTuple()).

Delegating tp_traverse

If your traverse function delegates to the tp_traverse of its base class (or another type), ensure that Py_TYPE(self) is visited only once. Note that only heap type are expected to visit the type in tp_traverse.

For example, if your traverse function includes:

base->tp_traverse(self, visit, arg)

...and base may be a static type, then it should also include:

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));
    }
}

It is not necessary to handle the type's reference count in tp_new and tp_clear.

Defining tp_dealloc

If your type has a custom tp_dealloc function, it needs to:

call PyObject_GC_UnTrack() before any fields are invalidated, and

decrement the reference count of the type.

To keep the type valid while tp_free is called, the type's refcount needs to be decremented after the instance is deallocated. For example:

static void my_dealloc(PyObject *self)
{
    PyObject_GC_UnTrack(self);
    ...
    PyTypeObject *type = Py_TYPE(self);
    type->tp_free(self);
    Py_DECREF(type);
}

The default tp_dealloc function does this, so if your type does not override tp_dealloc you don't need to add it.

Not overriding tp_free

The tp_free slot of a heap type must be set to PyObject_GC_Del(). This is the default; do not override it.

Avoiding PyObject_New

GC-tracked objects need to be allocated using GC-aware functions.

If you use use PyObject_New() or PyObject_NewVar():

Get and call type's tp_alloc slot, if possible. That is, replace TYPE *o = PyObject_New(TYPE, typeobj) with:

TYPE *o = typeobj->tp_alloc(typeobj, 0);

Replace o = PyObject_NewVar(TYPE, typeobj, size) with the same, but use size instead of the 0.

If the above is not possible (e.g. inside a custom tp_alloc), call PyObject_GC_New() or PyObject_GC_NewVar():

TYPE *o = PyObject_GC_New(TYPE, typeobj);

TYPE *o = PyObject_GC_NewVar(TYPE, typeobj, size);

Module State Access from Classes

If you have a type object defined with PyType_FromModuleAndSpec(), you can call PyType_GetModule() to get the associated module, and then PyModule_GetState() to get the module's state.

To save a some tedious error-handling boilerplate code, you can combine these two steps with PyType_GetModuleState(), resulting in:

my_struct *state = (my_struct*)PyType_GetModuleState(type);
if (state == NULL) {
    return NULL;
}

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 Py_TYPE(self). If the method is called on a subclass of your type, Py_TYPE(self) will refer to that subclass, which may be defined in different module than yours.

注釈

The following Python code can illustrate the concept. Base.get_defining_class returns Base even if type(self) == Sub:

class Base:
    def get_type_of_self(self):
        return type(self)

    def get_defining_class(self):
        return __class__

class Sub(Base):
    pass

For a method to get its "defining class", it must use the METH_METHOD | METH_FASTCALL | METH_KEYWORDS calling convention and the corresponding PyCMethod signature:

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

Once you have the defining class, call PyType_GetModuleState() to get the state of its associated module.

例えば:

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},
}

Module State Access from Slot Methods, Getters and Setters

注釈

これは Python 3.11 の新機能です。

Slot methods—the fast C equivalents for special methods, such as nb_add for __add__ or tp_new for initialization—have a very simple API that doesn't allow passing in the defining class, unlike with PyCMethod. The same goes for getters and setters defined with PyGetSetDef.

To access the module state in these cases, use the PyType_GetModuleByDef() function, and pass in the module definition. Once you have the module, call PyModule_GetState() to get the state:

PyObject *module = PyType_GetModuleByDef(Py_TYPE(self), &module_def);
my_struct *state = (my_struct*)PyModule_GetState(module);
if (state == NULL) {
    return NULL;
}

PyType_GetModuleByDef() works by searching the method resolution order (i.e. all superclasses) for the first superclass that has a corresponding module.

注釈

In very exotic cases (inheritance chains spanning multiple modules created from the same definition), 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.

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 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.

取り掛かり中の問題

Several issues around per-module state and heap types are still open.

Discussions about improving the situation are best held on the capi-sig mailing list [https://mail.python.org/mailman3/lists/capi-sig.python.org/].

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).

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.

The Python 2.3 Method Resolution Order

注釈

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.

By Michele Simionato [https://www.phyast.pitt.edu/~micheles/].

Abstract:

This document is intended for Python programmers who want to understand the C3 Method Resolution Order used in Python 2.3. Although it is not intended for newbies, it is quite pedagogical with many worked out examples. I am not aware of other publicly available documents with the same scope, therefore it should be useful.

Disclaimer:

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!

Acknowledgments:

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.

The beginning

Felix qui potuit rerum cognoscere causas -- Virgilius

Everything started with a post by Samuele Pedroni to the Python development mailing list [1]. 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 [2]. 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:

Don't be scared!

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.

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.

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.

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.

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.

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.

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.

Here I give an example of this situation. Consider the hierarchy

>>> O = object
>>> class X(O): pass
>>> class Y(O): pass
>>> class A(X,Y): pass
>>> class B(Y,X): pass

which can be represented with the following inheritance graph, where I have denoted with O the object class, which is the beginning of any hierarchy for new style classes:

 -----------
|           |
|    O      |
|  /   \    |
 - X    Y  /
   |  / | /
   | /  |/
   A    B
   \   /
     ?

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).

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:

C1 C2 ... CN

to indicate the list of classes [C1, C2, ... , CN].

The head of the list is its first element:

head = C1

whereas the tail is the rest of the list:

tail = C2 ... CN.

I shall also use the notation:

C + (C1 C2 ... CN) = C C1 C2 ... CN

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:

the linearization of C is the sum of C plus the merge of the linearizations of the parents and the list of the parents.

In symbolic notation:

L[C(B1 ... BN)] = C + merge(L[B1] ... L[BN], B1 ... BN)

In particular, if C is the object class, which has no parents, the linearization is trivial:

L[object] = object.

However, in general one has to compute the merge according to the following prescription:

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.

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:

L[C(B)] = C + merge(L[B],B) = C + L[B]

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 ;-)

Examples

First example. Consider the following hierarchy:

>>> 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

In this case the inheritance graph can be drawn as:

                          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)
                           ---

The linearizations of O,D,E and F are trivial:

L[O] = O
L[D] = D O
L[E] = E O
L[F] = F O

The linearization of B can be computed as:

L[B] = B + merge(DO, EO, DE)

We see that D is a good head, therefore we take it and we are reduced to compute 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 merge(O,O) which gives O. Therefore:

L[B] =  B D E O

Using the same procedure one finds:

L[C] = C + merge(DO,FO,DF)
     = C + D + merge(O,FO,F)
     = C + D + F + merge(O,O)
     = C D F O

Now we can compute:

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

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:

>>> 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

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:

                           6
                          ---
Level 3                  | O |
                       /  ---  \
                      /    |    \
                     /     |     \
                    /      |      \
                  ---     ---    ---
Level 2        2 | E | 4 | D |  | F | 5
                  ---     ---    ---
                   \      / \     /
                    \    /   \   /
                     \  /     \ /
                      ---     ---
Level 1            1 | B |   | C | 3
                      ---     ---
                       \       /
                        \     /
                          ---
Level 0                0 | A |
                          ---

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 .mro() method of class A:

>>> A.mro()
[<class 'A'>, <class 'B'>, <class 'E'>,
<class 'C'>, <class 'D'>, <class 'F'>,
<class 'object'>]

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:

L[O] = 0
L[X] = X O
L[Y] = Y O
L[A] = A X Y O
L[B] = B Y X O

However, it is impossible to compute the linearization for a class C that inherits from A and B:

L[C] = C + merge(AXYO, BYXO, AB)
     = C + A + merge(XYO, BYXO, B)
     = C + A + B + merge(XYO, YXO)

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.

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:

>>> F=type('Food',(),{'remember2buy':'spam'})
>>> E=type('Eggs',(F,),{'remember2buy':'eggs'})
>>> G=type('GoodFood',(F,E),{}) # under Python 2.3 this is an error!

with inheritance diagram

             O
             |
(buy spam)   F
             | \
             | E   (buy eggs)
             | /
             G

      (buy eggs or spam ?)

We see that class G inherits from F and E, with F before E: therefore we would expect the attribute G.remember2buy to be inherited by F.rembermer2buy and not by E.remember2buy: nevertheless Python 2.2 gives

>>> G.remember2buy
'eggs'

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:

L[G,P22]= G E F object   # F *follows* E

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:

>>> class F: remember2buy='spam'
>>> class E(F): remember2buy='eggs'
>>> class G(F,E): pass
>>> G.remember2buy
'spam'

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 viceversa. 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:

merge(FO,EFO,FE)

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.

           O
           |
           F (spam)
         / |
(eggs)   E |
         \ |
           G
             (eggs, no doubt)

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:

>>> 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

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:

despite the name, the MRO determines the resolution order of attributes, not only of methods;

the default food for Pythonistas is spam ! (but you already knew that ;-)

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:

   C
  / \
 /   \
A     B
 \   /
  \ /
   D

One easily discerns the inconsistency:

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!

On the other hand, there are no problems with the Python 2.2 and 2.3 MROs, they give both:

L[D] = D A B C

Guido points out in his essay [3] 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 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:

>>> 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

Here are the linearizations according to the C3 MRO (the reader should verify these linearizations as an exercise and draw the inheritance diagram ;-)

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

Python 2.2 gives exactly the same linearizations for A, B, C, D, E, K1, K2 and K3, but a different linearization for Z:

L[Z,P22] = Z K1 K3 A K2 D B C E O

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.

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.:

#<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>

That's all folks,

enjoy !

Resources

[1]

The thread on python-dev started by Samuele Pedroni: https://mail.python.org/pipermail/python-dev/2002-October/029035.html

[2]

The paper A Monotonic Superclass Linearization for Dylan: https://doi.org/10.1145/236337.236343

[3]

Guido van Rossum's essay, Unifying types and classes in Python 2.2: https://web.archive.org/web/20140210194412/http://www.python.org/download/releases/2.2.2/descrintro

Python よくある質問

一般 Python FAQ

プログラミング FAQ

デザインと歴史 FAQ

ライブラリと拡張 FAQ

拡張と埋め込み FAQ

Windows 上の Python FAQ

グラフィックユーザインターフェース FAQ

"なぜ Python が私のコンピュータにインストールされているのですか？" FAQ

一般 Python FAQ

目次

一般 Python FAQ

一般情報

Python とは何ですか？

Python Software Foundation とは何ですか？

Python を使うのに著作権の制限はありますか？

そもそも Python は何故創られたのですか？

Python は何をするのに向いていますか？

Python のバージョン番号の仕組みはどうなっているのですか？

Python のソースのコピーはどこで手に入りますか？

Python のドキュメントはどこで手に入りますか？

プログラミングをしたことがないのですが、Python のチュートリアルはありますか？

Python のためのニュースグループやメーリングリストはありますか？

Python のベータテスト版はどこで手に入りますか？

Python のバグ報告やパッチを上げるにはどうしたら良いですか？

Python について発行された記事を何か参照できますか？

Python の本はありますか？

www.python.org は世界のどこにあるのですか？

なぜ Python という名前なのですか？

『空飛ぶモンティ・パイソン』を好きでなくてはいけませんか？

現実世界での Python

Python はどれくらい安定していますか？

どれくらいの人が Python を使っていますか？

Python で行われた大きなプロジェクトはありますか？

将来 Python にどのような新しい開発が期待されますか？

Python の互換性を無くすような提案をしてもいいのですか？

Python は初心者プログラマに向いている言語ですか？

一般情報

Python とは何ですか？

Python は、インタプリタ形式の、対話的な、オブジェクト指向プログラミング言語です。この言語には、モジュール、例外、動的な型付け、超高水準の動的なデータ型、およびクラスが取り入れられています。 Pythonは、オブジェクト指向プログラミングを越えて、手続き型プログラミングや関数型プログラミングなど複数のプログラミングパラダイムをサポートしています。 Python は驚くべきパワーと非常に分かりやすい文法を持ち合わせています。そして、多くのシステムコールやライブラリへだけでなく、様々なウィンドウシステムへのインターフェースがあり、C や C++ で拡張することもできます。また、プログラム可能なインターフェースが必要なアプリケーションのための拡張言語としても利用できます。最後に、Python はポータブルです。Linux や macOS を含む多くの Unix の派生システムで動き、Windows でも動きます。

さらに知りたければ、 Python チュートリアル から始めましょう。他にも、 Beginner's Guide to Python [https://wiki.python.org/moin/BeginnersGuide] から、Python 学習のための入門用チュートリアルやリソースを参照できます。

Python Software Foundation とは何ですか？

Python Software Foundation は、Python バージョン 2.1 以降の著作権を保持する独立の非営利組織です。PSF の任務は、Python プログラミング言語に関するオープンソース技術を進め、Python の使用を広めることです。PSF のホームページが https://www.python.org/psf/ にあります。

PSF への寄付は米国で免税されています。Python を利用して役立ったと感じたら、the PSF donation page [https://www.python.org/psf/donations/] で貢献をお願いします。

Python を使うのに著作権の制限はありますか？

あなたが作成する Python に関するドキュメントのすべてに著作権を残し、それらの著作権を表示する限り、ソースコードをどのように扱ってもかまいません。この著作権規則を尊重する限り、商用に Python を利用しても、ソースあるいはバイナリ形式で(変更の有無にかかわらず) Python のコピーを販売しても、Python が何らかの形で組み込まれた製品を販売してかまいません。もちろん、Python のあらゆる商業用途についても同様です。

PSF License のより詳しい説明と全文へのリンクは the license page [https://docs.python.org/3/license.html] を参照してください。

Python のロゴは商標登録されていて、使用に許可が必要な場合があります。詳しい情報は the Trademark Usage Policy [https://www.python.org/psf/trademarks/] を参照してください。

そもそも Python は何故創られたのですか？

Guido van Rossum によると、すべての始まりについての 非常に 簡潔な概要は以下のとおりです:

私は CWI の ABC グループでインタプリタ言語を実装する幅広い経験をしていて、そこで共に働くことで言語設計に関して大いに学びました。これは文のグループ化にインデントを使用することや超高水準のデータ型の包含など、(詳細は Python とは全く異なりますが) Python の多くの特徴のもととなっています。

私は ABC 言語に対して多くの不満を持っていましたが、同時に特徴の多くが好きでもありました。ABC 言語 (やその実装)を拡張して私の不満を解消することは不可能でした (実際、拡張性の欠如は大きな問題だったのです)。私は Modula-2+ を使用することでいくらかの経験を積み、Modula-3 のデザイナーと話して Modula-3 のレポートを読みました。Modula-3 は例外処理に使う構文や語義、その他いくつかの Python の特徴の起源です。

私は CWI で Amoeba 分散オペレーティングシステムのグループで働いていました。Amoeba のシステムコールインターフェースには Bourne シェルからアクセスしにくかったので、C プログラムや Bourne シェルスクリプトを書くよりも良いシステム管理の方法が必要でした。Amoeba のエラー処理の経験から、プログラミング言語の機能としての例外の重要さを強く意識するようになりました。

ABC のような構文と Amoeba のようなシステムコールを合わせ持ったスクリプト言語が必要だろうと思いつきました。Amoeba 専用の言語を書くのは愚かであるだろうと気づき、一般に拡張できるような言語を求めることに決めました。

1989 年のクリスマス休暇の間、自由な時間がたくさんできたので、その言語を実際に作ってみることにしました。翌年の間、勤務時間以外はほとんどその開発に費やし、Python は Amoeba プロジェクトのなかで成果を重ね、同僚からのフィードバックは私の開発を大いに加速させてくれました。

1991 年 2 月、1 年間と少しの開発を経て、USENET に投稿することにしました。それは Misc/HISTORY ファイルに残っています。

Python は何をするのに向いていますか？

Python は、多岐にわたる問題に適用できる高水準な汎用プログラム言語です。

この言語は、文字列処理(正規表現、Unicode、ファイル間の差分の計算)、インターネットプロトコル(HTTP、FTP、SMTP、XML-RPC、POP、IMAP)、ソフトウェアエンジニアリング(Python コードのユニットテスト、ロギング、プロファイリング、解析)、オペレーティングシステムインターフェース(システムコール、ファイルシステム、 TCP/IP ソケット) のような領域をカバーする大規模な標準ライブラリから成り立っています。何ができるかを知るには Python 標準ライブラリ の一覧を参照してください。また、様々なサードパーティの拡張も使えます。 the Python Package Index [https://pypi.org] から興味のあるパッケージを探してみましょう。

Python のバージョン番号の仕組みはどうなっているのですか？

Python のバージョン番号は "A.B.C" または "A.B" が付けられます :

A はメジャーバージョン番号です -- 言語に本当に大きな変更があった場合に増やされます。

B はマイナーバージョン番号です -- 驚きの少ない変更があった場合に増やされます。

C はマイクロバージョン番号です -- バグフィックスリリースごとに増やされます。

すべてのリリースがバグフィックスリリースであるというわけではありません。フィーチャーリリースへの準備段階では、一連の開発リリースが作られ、アルファ版、ベータ版、またはリリース候補と名付けられます。アルファ版はインターフェースが確定されないうちにリリースされる早期リリースで、２つのアルファリリース間でインターフェースが変わるかもしれません。ベータ版はもっと安定していて、現存のインターフェースは保存されますが新しいモジュールが追加されるかもしれません。リリース候補は固まったもので、致命的なバグを直すのでなければ変更されません。

アルファ、ベータとリリース候補のバージョンは、追加の接尾辞を持ちます:

アルファバージョンの接尾辞は、ある小さな数 N に対して "aN "となります。

ベータバージョンの接尾辞は、ある小さな数 N に対して "bN" となります。

リリース候補バージョンの接尾辞は、ある小さな数 N に対して "rcN" となります。

つまり、 2.0aN と付けられたバージョンはすべて 2.0bN に先立ち、 2.0bN は 2.0rcN に先立ち、そして これら は 2.0 に先立ちます。

また、"2.2+" のように "+" 接尾語が付いたバージョン番号もあります。これは未発表のバージョンで、 CPython 開発リポジトリから直接ビルドされています。実際、最後のマイナーリリースが行われた後、バージョンは "2.4a0" のように "a0" がつく次のマイナーバージョンになります。

開発サイクルの詳細は Developer's Guide [https://devguide.python.org/developer-workflow/development-cycle/] を、 Python の後方互換性ポリシーについては PEP 387 [https://peps.python.org/pep-0387/] を参照してください。 ドキュメント sys.version 、 sys.hexversion 、 sys.version_info も参照してください。

Python のソースのコピーはどこで手に入りますか？

最新の Python ソースは python.org (https://www.python.org/downloads/) からいつでも手に入れることができます。最新の開発版ソースは https://github.com/python/cpython/ にアクセスして手に入れることができます。

ソースは gzip された tar ファイルで配布され、完全な C のソース、Sphinx によりフォーマットされたドキュメント、Python ライブラリモジュール、サンプルプログラム、そしていくつかの役立つ配布自由なソフトウェアを含んでいます。このソースはほとんどの UNIX プラットフォームでそのままコンパイルして動かせます。

ソースコードの入手とコンパイルについて、より詳しい情報は Getting Started section of the Python Developer's Guide [https://devguide.python.org/setup/] を参照してください。

Python のドキュメントはどこで手に入りますか？

Python の現行の安定バージョンの標準ドキュメントは https://docs.python.org/3/ から利用できます。また、PDF、プレーンテキスト、ダウンロードできる HTML 版も https://docs.python.org/3/download.html から利用できます。

このドキュメントは reStructuredText で書かれ、the Sphinx documentation tool [https://www.sphinx-doc.org/] で構成されました。このドキュメントに使われた reStructuredText のソースは Python のソース配布に含まれます。

プログラミングをしたことがないのですが、Python のチュートリアルはありますか？

膨大な量の役に立つチュートリアルや書籍があります。標準のドキュメントには Python チュートリアル などがあります。

Python プログラム初心者のための情報のチュートリアルのリストは the Beginner's Guide [https://wiki.python.org/moin/BeginnersGuide] を参照してください。

Python のためのニュースグループやメーリングリストはありますか？

ニュースグループ comp.lang.python やメーリングリスト python-list [https://mail.python.org/mailman/listinfo/python-list] があります。ニュースグループとメーリングリストは互いに接続されていて、ニュースを購読すればメーリングリストに参加する必要はありません。 comp.lang.python は一日に数百のポスティングを受ける高いトラフィックで、USENET 読者は多くの場合、このボリュームに応えることができます。

新しいソフトウェアリリースとイベントの告知は comp.lang.python.announce で見つけられます。これは一日に 5 ポスティング程度を受ける低トラフィックの手頃なメーリングリストです。the python-announce mailing list [https://mail.python.org/mailman3/lists/python-announce-list.python.org/] から利用可能です。

その他のメーリングリストやニュースグループについての詳しい情報は https://www.python.org/community/lists/ にあります。

Python のベータテスト版はどこで手に入りますか？

アルファ/ベータリリースは https://www.python.org/downloads/ で手に入ります。リリースはすべて comp.lang.python や comp.lang.python.announce のニュースグループと Python ホームページ https://www.python.org/ で告知され、RSS ニュースフィードが利用できます。

Git から開発版を手に入れることもできます。詳細は The Python Developer's guide [https://devguide.python.org/] を参照してください。

Python のバグ報告やパッチを上げるにはどうしたら良いですか？

バグの報告やパッチの提出には、issue tracker https://github.com/python/CPython/issues をご利用ください。

Python 開発の工程について、詳しくは the Python Developer's Guide [https://devguide.python.org/] を参照してください。

Python について発行された記事を何か参照できますか？

Python に関するあなたの愛読書を引用するのが一番でしょう。

Python に関する 一番初めの記事 [https://ir.cwi.nl/pub/18204] はとても古く、1991年に書かれています。

Guido van Rossum and Jelke de Boer, "Interactively Testing Remote Servers Using the Python Programming Language", CWI Quarterly, Volume 4, Issue 4 (December 1991), Amsterdam, pp 283--303.

Python の本はありますか？

はい、たくさんあり、そのほとんどは現在も出版されています。リストは python.org wiki https://wiki.python.org/moin/PythonBooks にあります。

また、オンライン書店で "Python" で検索し、Monty Python をフィルタで除外してもいいです (または、"Python" と "言語" で検索してください)。

www.python.org は世界のどこにあるのですか？

Pythonプロジェクトのインフラは世界中にあり、Pythonインフラストラクチャチームによって管理されています。詳細は こちら [https://infra.psf.io].

なぜ Python という名前なのですか？

Python の開発が始まった頃、Guido van Rossum は 1970 年代に始まった BBC のコメディシリーズ "Monty Python's Flying Circus" [https://en.wikipedia.org/wiki/Monty_Python] の台本を読んでいました。Van Rossum は、短くて、ユニークで、少しミステリアスな名前が欲しかったので、この言語の名前を Python と呼ぶことにしたのです。

『空飛ぶモンティ・パイソン』を好きでなくてはいけませんか？

いいえ。でも、好きになってくれるといいな。: ）

現実世界での Python

Python はどれくらい安定していますか？

とても安定しています。1991 年以来新しい安定リリースはおよそ 6 から 18 ヶ月毎に出されていて、このペースが続きそうです。バージョン3.9の時点では、Pythonは12ヶ月に一度のペースで新しいフィーチャーリリースを行っています (PEP 602 [https://peps.python.org/pep-0602/]) 。

開発者が旧バージョンのバグフィックスリリースを公開するので、既存リリースの安定性は徐々に向上していきます。バグフィックスリリースは、バージョン番号の 3 番目の要素によって示され(例: 3.5.3、3.6.2)、安定性のために管理されています。バグフィックスリリースには既知の問題への修正だけが含まれ、一連のバグフィックスリリースを通じて同じインターフェースが保たれることが保証されているのです。

最新の安定版リリースは常に Python download page [https://www.python.org/downloads/] にあります。Pythonには2.xと3.xという、製品に利用可能な2つのバージョンがあります。推奨のバージョンは3.xで、これは広く利用されているライブラリのほとんどでサポートされています。2.xも依然として広く利用されていますが、もうこれ以上はメンテナンスされません [https://peps.python.org/pep-0373/] 。

どれくらいの人が Python を使っていますか？

正確な人数を調べるのは難しいですが、おそらく何百万人ものユーザーがいるでしょう。

Python は自由にダウンロード可能なので、売上高がなく、多数のサイトから利用でき、多くの Linux ディストーションに同梱されているので、ダウンロード統計から全体の状況を知ることはできません。

comp.lang.python ニュースグループはとても活発ですが、すべての Python ユーザーが投稿するわけではなく、読みすらしない人もいます。

Python で行われた大きなプロジェクトはありますか？

Python を利用しているプロジェクトのリストは https://www.python.org/about/success を参照してください。past Python conferences [https://www.python.org/community/workshops/] から議事録を参照すると、多くの会社や組織の貢献がわかるでしょう。

注目されている Python のプロジェクトは the Mailman mailing list manager [https://www.list.org] や the Zope application server [https://www.zope.dev] などです。Red Hat [https://www.redhat.com] をはじめとするいくつかの Linux ディストーションのインストーラやシステムアドミニストレーションソフトウェアは、一部や全部が Python で書かれています。内部で Python を利用している企業には、Google、Yahoo、Lucasfilm Ltd. などがあります。

将来 Python にどのような新しい開発が期待されますか？

Python Enhancement Proposals (PEP) https://peps.python.org/ を参照してください。PEP は Python に提案された新機能について書かれた設計書で、簡潔な技術仕様と原理が提供されています。"Python X.Y Release Schedule" (X.Y はまだリリースされていないバージョン) を探してください。

新しい開発については the python-dev mailing list [https://mail.python.org/mailman3/lists/python-dev.python.org/] で議論されています。

Python の互換性を無くすような提案をしてもいいのですか？

一般的には、してはいけません。世界中にすでに何百万行もの Python コードがあるので、既存のプログラムのどんなに僅かな部分でも無効にしてしまうような言語仕様の変更も認められてはなりません。コンバートするプログラムが出来てさえ、すべてのドキュメントをアップデートしなければならないという問題があります。 Python に関する多くの本が出版されているので、それらを一発で不適切にするようなことはしたくないです。

仕様を変えなければならないのなら、緩やかなアップグレード計画が組まれなくてはなりません。 PEP 5 [https://peps.python.org/pep-0005/] で、ユーザーの受ける分裂を最小限にしながら後方互換性のない変更を行うために従うべき手順について説明しています。

Python は初心者プログラマに向いている言語ですか？

はい。

未だにプログラミング初学者にとって一般的なのは、Pascal、C、C++ のサブセット、 Java など、手続き型の静的型付けの言語です。生徒にとっては、第一の言語として Python を学ぶのが役に立つでしょう。Python には非常に簡潔で一貫した構文と大きな標準ライブラリがあります。そして一番重要なことに、初心者プログラミングのコースで Python を学ぶことで、生徒は問題の分析やデータ型の設計など、重要なプログラミングスキルに集中することができるのです。 Python なら、生徒はループや手続きなどの基本概念をすぐに取り入れられます。最初の課程でいきなりユーザ定義のオブジェクトを操ることさえできるでしょう。

プログラミングをしたことがない初心者にとって、静的型付け言語を使うのは不自然に思われます。習得すべき内容はより複雑になり、学習のペースが遅くなってしまいます。生徒は、コンピュータのように思考し、問題を分析し、一貫したインターフェースを設計して、データをカプセル化することを学ぶことになります。長期的に見れば静的型付け言語を学ぶことは重要ですが、それが最初のプログラミングの授業で学ぶべき最高の話題とは限りません。

Python の良いところは他にもたくさんあります。Python には、Java のように大きな標準ライブラリがあり、生徒が何かを する 段階で非常に早くプログラミングプロジェクトに参加できるようになります。宿題は標準の四則演算機や平均を求めるプログラムに限定されません。標準ライブラリを使用することで、生徒はプログラミングの原理を学びながら現実的なアプリケーションに取り組む満足感を得ることができます。また、標準ライブラリの使用からコードの再利用を学ぶことができます。 PyGame などのサードパーティモジュールもまた手が届く範囲を広げるのに役立ちます。

Python のインタラクティブインタプリタによって、プログラミングをしながら、言語機能を確認することができます。別のウィンドウでプログラムのソースに入っている間、ウィンドウでインタプリタを起動させたままにしておくことができます。リストのメソッドを思い出せないときは、例えばこのようにできます:

>>> 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]

インタプリタがあれば、プログラミングをしている間にドキュメントは生徒のそばを離れません。

Python のための良い IDE もあります。IDLE は Python で Tkinter を使って書かれたクロスプラットフォーム IDE です。Emacs には、ユーザにとって幸運なことに、素晴らしい Python モードがあります。これらすべてのプログラミング環境から、シンタックスハイライト、オートインデント、コーディング中のインタラクティブインタプリタへのアクセスが使えます。the Python wiki [https://wiki.python.org/moin/PythonEditors] から Python 編集環境の一覧を参照してください。

Python の教育における利用についての議論がしたいなら、the edu-sig mailing list [https://www.python.org/community/sigs/current/edu-sig] に参加するとよいでしょう。

プログラミング FAQ

目次

プログラミング FAQ

一般的な質問

ブレークポイントやシングルステップ実行などを備えたソースコードレベルデバッガはありますか？

バグの発見や静的解析に役立つツールはありますか？

どうしたら Python スクリプトからスタンドアロンバイナリを作れますか？

Python プログラムのためのコーディングスタンダードやスタイルガイドはありますか？

コア言語

なぜ変数に値があるのに UnboundLocalError が出るのですか？

Python のローカルとグローバル変数のルールは何ですか？

ループの中で異なる値で定義されたラムダ式が、同じ値を返すのはなぜですか？

グローバル変数をモジュール間で共有するにはどうしたらいいですか？

モジュールで import を使う際の「ベストプラクティス」は何ですか？

なぜオブジェクト間でデフォルト値が共有されるのですか？

オプションパラメータやキーワードパラメータを関数から関数へ渡すにはどうしたらいいですか？

実引数と仮引数の違いは何ですか?

なぜ list 'y' を変更すると list 'x' も変更されるのですか?

出力引数のある関数 (参照渡し) はどのように書きますか？

Python で高次関数はどのようにつくりますか？

Python のオブジェクトはどのようにコピーしますか？

オブジェクトのメソッドや属性はどのように見つけますか？

コードはどのようにオブジェクトの名前を見つけるのですか？

カンマ演算子はなぜ優先されるのですか？

C の "?:" 三項演算子と等価なものはありますか？

Python で解し難いワンライナーを書くことはできますか？

関数の引数リストにあるスラッシュ (/) は何を意味しますか？

数と文字列

十六進数や八進数を指定するにはどうしたらいいですか？

なぜ -22 // 10 は -3 を返すのですか？

どうすれば SyntaxError を起こさずに整数リテラルの属性を得られますか？

文字列を数に変換するにはどうしたらいいですか？

数を文字列に変換するにはどうしたらいいですか？

文字列をインプレースに変更するにはどうしたらいいですか？

関数やメソッドを呼ぶのに文字列を使うにはどうしたらいいですか？

文字列から後端の改行を取り除く Perl の chomp() に相当するものはありますか？

scanf() や sscanf() と同等なものはありますか？

'UnicodeDecodeError' や 'UnicodeEncodeError' はどういう意味ですか？

raw string を奇数個のバックスラッシュで終えることはできますか？

性能

プログラムが遅すぎます。どうしたら速くなりますか？

多くの文字列を結合するのに最も効率的な方法は何ですか？

シーケンス(タプル/リスト)

タプル、リスト間の変更はどのようにするのですか？

負の添え字は何ですか？

シーケンスを逆順にイテレートするにはどうしたらいいですか？

リストから重複を取り除くにはどうしますか？

リストから複数のアイテムを取り除く方法

Python で配列を作るにはどうしますか？

多次元のリストを作るにはどうしますか？

オブジェクトのシーケンスにメソッドや関数を適用するにはどうしますか？

なぜ加算はされるのに a_tuple[i] += ['item'] は例外を送出するのですか?

複雑なソートがしたいのですが、Python でシュワルツ変換はできますか？

リストを別のリストの値によってソートするにはどうしますか？

オブジェクト

クラスとは何ですか？

メソッドとは何ですか？

self とは何ですか？

あるオブジェクトが、与えられたクラスやそのサブクラスのインスタンスであるかを調べるにはどうしますか？

委譲とは何ですか？

基底クラスで定義されたメソッドを、そのクラスを継承した派生クラスから呼び出すにはどうしますか？

基底クラスの名前を変えやすいコードを書くにはどうしますか？

静的なクラスデータや静的なクラスメソッドを作るにはどうしますか？

Python でコンストラクタ(やメソッド)をオーバーロードするにはどうしたらいいですか？

__spam を使おうとしたら _SomeClassName__spam からエラーがでました。

クラスに __del__ メソッドを定義しているのですが、オブジェクトを削除したときに呼ばれません。

与えられたクラスのすべてのインスタンスのリストを得るにはどうしますか？

なぜ id() の結果は一意でないように見えるのですか?

いつ is 演算子での同一性テストが頼れますか？

どうすればサブクラスはイミュータブルなインスタンスに格納されたデータを制御できますか？

メソッド呼び出しをキャッシュするには どうしたらいいですか？

モジュール

.pyc ファイルを作るにはどうしますか？

現在のモジュール名を知るにはどうしますか？

相互にインポートしあうモジュールを作るにはどうしたらいいですか？

__import__('x.y.z') は <module 'x'> を返しますが、z を得るためにはどうしますか？

インポートされたモジュールを編集してから再インポートしましたが、変化が現れません。なぜですか？

一般的な質問

ブレークポイントやシングルステップ実行などを備えたソースコードレベルデバッガはありますか？

はい。

Python 用のデバッガについては次に解説してあり、組み込みの breakpoint() 関数でそれらのデバッガに処理を移せます。

pdb モジュールは簡素にして十分な Python のコンソールモードデバッガです。これは Python の標準ライブラリに含まれているもので、 ライブラリリファレンスマニュアルにドキュメントがあります 。 pdb のコードを手本にして自分用のデバッガを書くこともできます。

Python に同梱されている統合開発環境の IDLE は通常の Python の配布形態の一部 (普通は Tools/scripts/idle3 [https://github.com/python/cpython/blob/main/Tools/scripts/idle3] から利用可能) であり、グラフィカルなデバッガを含んでいます。

PythonWin は、pdb をベースとした GUI デバッガを含む Python IDE です。Pythonwin デバッガは、ブレークポイントの色付けや非 PythonWin プログラムのデバッグなどの素敵な機能をたくさん持っています。PythonWin は pywin32 [https://github.com/mhammond/pywin32] プロジェクトの一部、あるいは ActivePython [https://www.activestate.com/products/python/] ディストリビューションの一部として利用可能です。

Eric [https://eric-ide.python-projects.org/] は PyQt や Scintilla editing component をもとにした IDE です。

trepan3k [https://github.com/rocky/python3-trepan/] は gdbライクなデバッガです。

Visual Studio Code [https://code.visualstudio.com/] はバージョン管理ソフトと一緒になったデバッグツールを備えた IDE です

商業のグラフィカルデバッガ付き Python IDE もあります。例えば:

Wing IDE [https://wingware.com/]

Komodo IDE [https://www.activestate.com/products/komodo-ide/]

PyCharm [https://www.jetbrains.com/pycharm/]

バグの発見や静的解析に役立つツールはありますか？

はい。

Pylint [https://pylint.pycqa.org/en/latest/index.html] と Pyflakes [https://github.com/PyCQA/pyflakes] は、バグの早期発見に役立つ基本的なチェックを行います。

Mypy [https://mypy-lang.org/], Pyre [https://pyre-check.org/], Pytype [https://github.com/google/pytype] などの静的型チェッカーは、 Python ソースコードにある型ヒントをチェックできます。

どうしたら Python スクリプトからスタンドアロンバイナリを作れますか？

ユーザがダウンロードでき、Python ディストリビューションをインストールせずに実行できるようなスタンドアロンプログラムだけでいいなら、Python を C コードにコンパイルできなくても構いません。プログラムに対して必要なモジュールを選び、そのモジュールを Python バイナリに束縛して一つの実行可能ファイルにまとめる多くのツールがあります。

一つは freeze ツールで、Python ソースツリーに Tools/freeze [https://github.com/python/cpython/tree/main/Tools/freeze] として含まれています。これは Python バイトコードを C 配列に変換します。すべてのモジュールを新しいプログラムに埋め込む C コンパイラで、そのプログラムは Python モジュールにリンクされます。

これはあなたのソースの (両方の形式の) import 文を再帰的にスキャンし、import されたモジュールを標準の Python パスと (組み込みモジュールのある) ソースディレクトリから探します。そして Python で書かれたモジュールのバイトコードを C コード (marshal モジュールでコードオブジェクトに変換できる配列) に変換し、実際にそのプログラム内で使われている組み込みモジュールだけが含まれたカスタムメイドの設定ファイルを作成します。そして生成された C コードをコンパイルして Python インタプリタの残りとリンクし、元のスクリプトと全く同じように動作する自己完結的なバイナリを形成します。

以下のパッケージはコンソールやGUIの実行ファイル作成に役立ちます。

Nuitka [https://nuitka.net/] (Cross-platform)

PyInstaller [https://pyinstaller.org/] (Cross-platform)

PyOxidizer [https://pyoxidizer.readthedocs.io/en/stable/] (Cross-platform)

cx_Freeze [https://marcelotduarte.github.io/cx_Freeze/] (Cross-platform)

py2app [https://github.com/ronaldoussoren/py2app] (macOS only)

py2exe [https://www.py2exe.org/] (Windows only)

Python プログラムのためのコーディングスタンダードやスタイルガイドはありますか？

はい。標準ライブラリモジュールに求められるコーディングスタイルは PEP 8 [https://peps.python.org/pep-0008/] として文書化されています。

コア言語

なぜ変数に値があるのに UnboundLocalError が出るのですか？

もともと動いていたコードが、関数の本体のどこかに代入文を加えるという変更をしたら UnboundLocalError を出すのには驚くかもしれません。

このコード:

>>> x = 10
>>> def bar():
...     print(x)
...
>>> bar()
10

は動きますが、このコード:

>>> x = 10
>>> def foo():
...     print(x)
...     x += 1

は UnboundLocalError になります:

>>> foo()
Traceback (most recent call last):
  ...
UnboundLocalError: local variable 'x' referenced before assignment

これは、あるスコープの中で変数に代入を行うとき、その変数はそのスコープに対してローカルになり、外のスコープにある同じ名前の変数を隠すからです。foo の最後の文が x に新しい値を代入しているので、コンパイラはこれをローカル変数であると認識します。その結果、先の print(x) が初期化されていないローカル変数を表示しようとして結果はエラーとなります。

上の例では、グローバルであると宣言することで外のスコープにアクセスできます:

>>> x = 10
>>> def foobar():
...     global x
...     print(x)
...     x += 1
...
>>> foobar()
10

この明示的な宣言は (表面的には似ているクラスとインスタンス変数の例とは違って) あなたは実際は他のスコープの変数の値を変えようとしているのだ、ということを知らせるのに必要です:

>>> print(x)
11

同様のことを、ネストされたスコープで nonlocal 予約語を使うことでもできます:

>>> def foo():
...    x = 10
...    def bar():
...        nonlocal x
...        print(x)
...        x += 1
...    bar()
...    print(x)
...
>>> foo()
10
11

Python のローカルとグローバル変数のルールは何ですか？

Python では、関数内で参照されるだけの変数は暗黙的にグローバルとなります。関数の本体のどこかで値が変数に代入されたなら、それは明示的にグローバルであると宣言されない限り、ローカルであるとみなされます。

最初はちょっと驚くでしょうが、少し考えると納得できます。一方では、代入された変数に global を要求することで、意図しない副作用を防げます。他方では、グローバルな参照の度に global が要求されてしまうと、 global を使ってばかりになってしまいます。ビルトイン関数やインポートされたモジュールの内容を参照するたびにグローバル宣言をしなければならないのです。その乱雑さは副作用を特定するための global 宣言の便利さよりも重大です。

ループの中で異なる値で定義されたラムダ式が、同じ値を返すのはなぜですか？

for ループを使って、少しずつ異なるラムダを定義 (もしくは簡単な関数) するとします。例えば:

>>> squares = []
>>> for x in range(5):
...     squares.append(lambda: x**2)

これで x**2 を計算する 5 つのラムダのリストが得られます。それらを呼び出したとき、それぞれ 0、1、4、9、16 を返すと予想するかもしれません。しかし実際にやってみると、全て 16 が返ってくるのを目にするでしょう:

>>> squares[2]()
16
>>> squares[4]()
16

これは、x がラムダにとってのローカル変数ではなく外側のスコープで定義されていて、ラムダが定義されたときでなく呼び出されたときにアクセスされるために起こります。ループが終わった時点では x は 4 であり、従って、全ての関数は 4**2 つまり 16 を返します。このことは x の値を変えてみることで検証でき、ラムダの返り値がどのように変わるのか観察できます:

>>> x = 8
>>> squares[2]()
64

これを避けるためには、グローバルの x の値に依存しないために、ラムダにとってのローカル変数に値を保存する必要があります:

>>> squares = []
>>> for x in range(5):
...     squares.append(lambda n=x: n**2)

ここで、n=x は新しいラムダにとってのローカル変数 n を作成し、ラムダが定義されるときに計算されるので、ループのその時点での x と同じ値を持っています。これは、1 つ目のラムダでは n の値は 0 になり、2 つ目では 1、3 つ目では 2 以下同様、となることを意味します。従って、それぞれのラムダは今や正しい値を返すようになりました:

>>> squares[2]()
4
>>> squares[4]()
16

この動作はラムダに特有なものではなく、通常の関数にも適用されることに注意してください。

グローバル変数をモジュール間で共有するにはどうしたらいいですか？

一つのプログラムのモジュール間で情報を共有する正準な方法は、特別なモジュール (しばしば config や cfg と呼ばれる) を作ることです。単に設定モジュールをアプリケーションのすべてのモジュールにインポートしてください。このモジュールはグローバルな名前として使えます。それぞれのモジュールのただ一つのインスタンスがあるので、設定モジュールオブジェクトに対するいかなる変更も全体に反映されます。例えば:

config.py:

x = 0   # Default value of the 'x' configuration setting

mod.py:

import config
config.x = 1

main.py:

import config
import mod
print(config.x)

なお、同じ理由から、モジュールを使うということは、シングルトンデザインパターンを実装することの基礎でもあります。

モジュールで import を使う際の「ベストプラクティス」は何ですか？

一般的に from modulename import * を使ってはいけません。そのようにするとインポータの名前空間は汚染され、linter が未定義の名前を発見することが難しくなります。

モジュールはファイルの先頭でインポートしてください。これによってコードが必要とする他のモジュールが明確になり、モジュール名がスコープに含まれるかどうかに迷わなくなります。行に一つのインポートにすると、モジュールのインポートの追加と削除が容易になりますが、行に複数のインポートにすると画面の領域が少なく済みます。

次の手順でモジュールをインポートするのが、良い習慣になります:

標準ライブラリモジュール -- 例 sys、os、argparse、re

サードパーティのライブラリモジュール (Python の site-packages ディレクトリにあるもの) -- 例 dateutil、requests、PIL.Image、など

自前で開発したモジュール

循環参照の問題を避けるために、インポートを関数やクラスに移すことが必要なときもあります。Gordon McMillan によれば:

循環参照は両方のモジュールが "import <module>" 形式のインポートを使っていれば大丈夫です。二つ目のモジュールが最初のモジュールから名前を確保しようとして ("from module import name")、そのインポートがトップレベルにあると駄目です。最初のモジュールが二つ目のモジュールをインポートするのに忙しくて、最初のモジュールの名前が利用可能になっていないからです。

この状況では、二つ目のモジュールが一つの関数の中でのみ使われているならば、そのインポートは簡単に関数の中に移せます。インポートが呼ばれたとき、最初のモジュールは初期化を完了していて、二つ目のモジュールは自分のインポートをできます。

プラットフォーム依存のモジュールがあるときには、インポートをトップレベルの外に動かすことも必要です。この場合、ファイルの先頭ではすべてのモジュールをインポートすることさえできないかもしれません。この場合は、対応するプラットフォームに合わせたコードで正しいモジュールをインポートすることを選ぶと良いです。

循環参照の問題を避けたりモジュールの初期化にかかる時間を減らしたりしたいなら、単にインポートを関数定義の中などのローカルなスコープに移してください。この手法は多くのインポートがプログラムがどのように実行されるかに依存しなくてよいときに特に有効です。ある関数の中でのみモジュールが使われるのなら、インポートをその関数の中に移すことを考えてもいいでしょう。なお、モジュールを読み込む最初の回はモジュールの初期化の時間のために高価になりえますが、複数回目にモジュールを読み込むのは事実上無料、辞書探索の数回のコストだけで済みます。モジュール名がスコープから外れてさえ、そのモジュールはおそらく sys.modules から利用できるでしょう。

なぜオブジェクト間でデフォルト値が共有されるのですか？

この種のバグがよく初心者プログラマに噛み付きます。この関数を考えてみてください:

def foo(mydict={}):  # Danger: shared reference to one dict for all calls
    ... compute something ...
    mydict[key] = value
    return mydict

初めてこの関数を呼び出した時、mydict には一つの要素があります。二回目には、foo() が実行されるときに mydict には初めから一つの要素をすでに持っているので、mydict には二つの要素があります。

関数の呼び出しによって、デフォルトの値に対する新しいオブジェクトが作られるのだと予想しがちです。実はそうなりません。デフォルト値は、関数が定義されたときに一度だけ生成されます。この例の辞書のように、そのオブジェクトが変更されたとき、その後の関数の呼び出しは変更後のオブジェクトを参照します。

定義の時に、数、文字列、タプル、None など、イミュータブルなオブジェクトを使うと変更される危険がありません。辞書、リスト、クラスインスタンスなどのミュータブルなオブジェクトは混乱のもとです。

この性質から、ミュータブルなオブジェクトをデフォルト値として使わないプログラミング手法がいいです。代わりに、None をデフォルト値に使い、そのパラメタが None である時にだけ、関数の内部で新しいリスト/辞書/その他をつくるようにしてください。例えば、こう書かずに:

def foo(mydict={}):
    ...

代わりに:

def foo(mydict=None):
    if mydict is None:
        mydict = {}  # create a new dict for local namespace

この性質が便利なこともあります。時間のかかる計算を行う関数があるときに使われる一般的な技法は、関数が呼び出されるごとにパラメタと結果の値をキャッシュし、再び同じ値が要求されたらキャッシュされた値を返すというものです。これは "memoizing" と呼ばれ、このように実装されます:

# Callers can only provide two parameters and optionally pass _cache by keyword
def expensive(arg1, arg2, *, _cache={}):
    if (arg1, arg2) in _cache:
        return _cache[(arg1, arg2)]

    # Calculate the value
    result = ... expensive computation ...
    _cache[(arg1, arg2)] = result           # Store result in the cache
    return result

デフォルト値の代わりに、辞書を含むグローバル変数も使えます。これは好みの問題です。

オプションパラメータやキーワードパラメータを関数から関数へ渡すにはどうしたらいいですか？

関数のパラメータリストに引数を * と ** 指定子 (specifier) で集めてください。そうすれば、位置引数をタプルとして、キーワード引数を辞書として得られます。これで、他の関数を呼び出すときに * と ** を使ってそれらの引数を渡せます:

def f(x, *args, **kwargs):
    ...
    kwargs['width'] = '14.3c'
    ...
    g(x, *args, **kwargs)

実引数と仮引数の違いは何ですか?

仮引数 (parameter) は関数定義に表れる名前で定義されるのに対し、 実引数 (argument) は関数を呼び出すときに実際に渡す値のことです。仮引数は関数が受け取ることの出来る 実引数の型 を定義します。例えば、以下のような関数定義があったとして:

def func(foo, bar=None, **kwargs):
    pass

foo、bar、kwargs は func の仮引数です。一方、func を呼び出すときには、例えば:

func(42, bar=314, extra=somevar)

42、314、somevar という値は実引数です。

なぜ list 'y' を変更すると list 'x' も変更されるのですか?

次のようなコードを書いたとします:

>>> x = []
>>> y = x
>>> y.append(10)
>>> y
[10]
>>> x
[10]

どうして y への要素の追加が x も変更してしまうのか疑問に思うかもしれません。

このような結果になる2つの要因があります:

変数とは、単にオブジェクトを参照するための名前に過ぎません。 y = x とすることは、リストのコピーを作りません -- それは x が参照するのと同じオブジェクトを参照する新しい変数 y を作ります。つまり、あるのは一つのオブジェクト(この場合リスト)だけであって、 x と y の両方がそれを参照しているのです。

リストは mutable です。内容を変更出来る、ということです。

append() 呼び出しの後、ミュータブルオブジェクトの内容が [] から [10] に変わります。 変数が同じオブジェクトを参照しているので、どちらの名前であっても変更された値 [10] にアクセスします。

代わりに x にイミュータブルを代入すると:

>>> x = 5  # ints are immutable
>>> y = x
>>> x = x + 1  # 5 can't be mutated, we are creating a new object here
>>> x
6
>>> y
5

この場合ご覧の通り x と y はまったく同じではありませんね。これは整数が immutable だからで、 x = x + 1 は整数の 5 の値を変更しているのではありません; 代わりに新しいオブジェクト(整数 6)を作って x に代入しています (つまり x が参照するオブジェクトが変わります)。この代入の後では私たちは 2 つのオブジェクト(整数の 6 と 5)を持っていて、2 つの変数はそれらを参照しています(x はいまや 6 を参照していますが y は 5 を参照したままです)。

ある演算 (たとえば y.append(10), y.sort()) がオブジェクトを変更する一方で、外見上は似た演算 (たとえば y = y + [10], sorted(y)) は新しいオブジェクトを作ります。Python では一般に (そして標準ライブラリの全てのケースで)、このような 2 つのタイプの演算にまつわる混乱を避けるために、オブジェクトを変更するメソッドは None を返します。ですからもしあなたが誤って y の複製の並び替えをするつもりで y.sort() と書いた場合に結果手にするのは None でしょうから、あなたのプログラムは簡単に診断出来るエラーを起こすでしょう。

しかしながら、同じ操作が型ごとに異なる振る舞いをする演算の種類が一つあります: 累算代入演算です。例えば += はリストを変更しますが、タプルや整数は変更しません(a_list += [1, 2, 3] は a_list.extend([1, 2, 3]) と同じ意味で、そして a_list を変更しますが、 some_tuple += (1, 2, 3) と some_int += 1 は新しいオブジェクトを作ります)。

言い換えると:

ミュータブルなオブジェクト(list, dict, set, 等)を持っている場合、私たちはその内容を変更するある種の演算を使うことが出来、それを参照している全ての変数はその変化を見ることになるでしょう。

イミュータブルなオブジェクト(str, int, tuple, 等)を持っている場合、それを参照している全ての変数は同じ値を参照しているでしょうが、持っている値を新しい値に変換する演算はいつでも新しいオブジェクトを返します。

2つの変数が同じオブジェクトを参照しているかどうかが知りたければ、 is 演算子や組み込み関数 id() が使えます。

出力引数のある関数 (参照渡し) はどのように書きますか？

前提として、Python では引数は代入によって渡されます。代入はオブジェクトへの参照を作るだけなので、呼び出し元と呼び出し先にある引数名の間にエイリアスはありませんし、参照渡しそれ自体はありません。望む効果を得るためには幾つかの方法があります。

結果のタプルを返すことによって:

>>> def func1(a, b):
...     a = 'new-value'        # a and b are local names
...     b = b + 1              # assigned to new objects
...     return a, b            # return new values
...
>>> x, y = 'old-value', 99
>>> func1(x, y)
('new-value', 100)

これはたいてい一番明確な方法です。

グローバル変数を使って。これはスレッドセーフでないので、推奨されません。

ミュータブルな (インプレースに変更可能な) オブジェクトを渡すことによって:

>>> def func2(a):
...     a[0] = 'new-value'     # 'a' references a mutable list
...     a[1] = a[1] + 1        # changes a shared object
...
>>> args = ['old-value', 99]
>>> func2(args)
>>> args
['new-value', 100]

変更される辞書に渡すことによって:

>>> def func3(args):
...     args['a'] = 'new-value'     # args is a mutable dictionary
...     args['b'] = args['b'] + 1   # change it in-place
...
>>> args = {'a': 'old-value', 'b': 99}
>>> func3(args)
>>> args
{'a': 'new-value', 'b': 100}

または、クラスインスタンスに値を同梱することによって:

>>> class Namespace:
...     def __init__(self, /, **args):
...         for key, value in args.items():
...             setattr(self, key, value)
...
>>> def func4(args):
...     args.a = 'new-value'        # args is a mutable Namespace
...     args.b = args.b + 1         # change object in-place
...
>>> args = Namespace(a='old-value', b=99)
>>> func4(args)
>>> vars(args)
{'a': 'new-value', 'b': 100}

このような複雑なことをする理由はめったに無いでしょう。

一番の選択は、複数の結果を含むタプルを返すことです。

Python で高次関数はどのようにつくりますか？

二つの方法があります: ネストされたスコープを使う方法と、呼び出し可能オブジェクトを使う方法です。例えば、a*x+b の値を計算する f(x) 関数を返す linear(a,b) を定義したいとします。ネストされたスコープを使うと:

def linear(a, b):
    def result(x):
        return a * x + b
    return result

また、呼び出し可能オブジェクトを使うと:

class linear:

    def __init__(self, a, b):
        self.a, self.b = a, b

    def __call__(self, x):
        return self.a * x + self.b

どちらの場合でも、

taxes = linear(0.3, 2)

とすれば、taxes(10e6) == 0.3 * 10e6 + 2 となるような呼び出し可能オブジェクトを得られます。

呼び出し可能オブジェクトを使う方法は、少し遅くなり、わずかにコードが長くなるという短所があります。ですが、継承を使って呼び出し可能オブジェクト同士で記号を共有することもできます:

class exponential(linear):
    # __init__ inherited
    def __call__(self, x):
        return self.a * (x ** self.b)

オブジェクトはいくつかのメソッドに状態をカプセル化できます:

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

ここで、inc()、dec()、reset() は同じカウント変数を共有する関数のようにふるまいます。

Python のオブジェクトはどのようにコピーしますか？

一般的に、普通は copy.copy() や copy.deepcopy() を試してください。何でもコピーできるとは限りませんが、たいていはできます。

もっと簡単にコピーできるオブジェクトもあります。辞書には copy() メソッドがあります:

newdict = olddict.copy()

シーケンスはスライシングでコピーできます:

new_l = l[:]

オブジェクトのメソッドや属性はどのように見つけますか？

ユーザー定義クラスのインスタンス x で、dir(x),< はインスタンス属性とそのクラスで定義されたメソッドや属性を含む名前のアルファベット順リストを返します。

コードはどのようにオブジェクトの名前を見つけるのですか？

概して、オブジェクトは本当は名前を持たないので、見つけることはできません。本質的には、代入とはいつも値に名前を束縛することです。def と class 文も同じですが、この場合は値はコーラブルです。以下のコードを考えてみましょう:

>>> class A:
...     pass
...
>>> B = A
>>> a = B()
>>> b = a
>>> print(b)
<__main__.A object at 0x16D07CC>
>>> print(a)
<__main__.A object at 0x16D07CC>

おそらく、このクラスには名前があります。このクラスは二つの名前に縛られて、名前 B を通して呼び出されますが、それでもクラス A のインスタンスとして報告されるのです。しかし、両方の名前が同じ値に束縛されている以上、このインスタンスの名前が a か b か決めることはできないのです。

概して、コードにとってある値の「名前を知っている」事は重要ではありません。あなたがわざと内省的なコードを書いているのでない限り、方針を変えた方がいいかもしれないということになるでしょう。

comp.lang.python で、Fredrik Lundh はこの問題の答えとして素晴らしい喩えをしてくれました:

玄関にいた猫の名前を知るのと同じ方法です: その猫 (オブジェクト) 自体はその名前を言うことができないし、それは実は問題ではありません -- その猫が何と呼ばれているかを知る唯一の方法は、すべての隣人 (名前空間) にその猫 (オブジェクト) が何と呼ばれているかを聞くことです。

……そして、その猫が沢山の名前で知られていたり、逆に全く名前が無かったりしても驚かないでください！

カンマ演算子はなぜ優先されるのですか？

カンマは Python では演算子ではありません。このセッションを考えてください:

>>> "a" in "b", "a"
(False, 'a')

カンマは演算子ではなく、式の分離子なので、上の式は次の式と同じように評価されます:

("a" in "b"), "a"

こうではありません:

"a" in ("b", "a")

他のさまざまな演算子(=、+= など)も同じです。これらは真の演算子ではありませんが、代入文の構文上のデリミタです。

C の "?:" 三項演算子と等価なものはありますか？

はい、あります。構文は以下のようになります:

[on_true] if [expression] else [on_false]

x, y = 50, 25
small = x if x < y else y

この構文が導入された 2.5 以前のバージョンに関しては、論理演算子を使ったこのイディオムが一般的でした:

[expression] and [on_true] or [on_false]

しかし、このイディオムは安全ではありません。on_true のブール値が偽であるときに間違った結果を与えることがあります。ですから、いつでも ... if ... else ... 形式を使ったほうが良いです。

Python で解し難いワンライナーを書くことはできますか？

はい。そういうものはたいてい、 lambda の中に lambda がネストされています。Ulf Bartelt によるものを少しアレンジした下の３つの例を見てください:

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

よい子はまねしないでね！

関数の引数リストにあるスラッシュ (/) は何を意味しますか？

パラメータ関数の仮引数にあるスラッシュは、それより前にある仮引数は位置専用引数であることを示します。位置専用引数は、外で使える名前を持たない仮引数です。位置専用引数を受け付ける関数の呼び出しにおいて、実引数はその位置だけに基づいて仮引数に対応付けられます。例えば、 divmod() は位置専用引数を受け付けます。そのドキュメントは次のようになります:

>>> 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.

この引数リストの末尾にスラッシュは、この2つの仮引数が両方とも位置専用引数であることを意味します。したがって、divmod() をキーワード引数を使って呼び出すとエラーになります:

>>> divmod(x=3, y=4)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: divmod() takes no keyword arguments

数と文字列

十六進数や八進数を指定するにはどうしたらいいですか？

八進数を指定するには、八進数での値の先頭に 0 と "o" (小文字または大文字) を加えてください。たとえば、変数 "a" に八進数での "10" (十進数での"8") を代入するには、こう打ってください:

>>> a = 0o10
>>> a
8

十六進数も簡単です。ただ十六進数での値の先頭に 0 と "x" (小文字または大文字) を加えてください。十六進数は小文字でも大文字でも指定できます。たとえば、Python インタプリタで:

>>> a = 0xa5
>>> a
165
>>> b = 0XB2
>>> b
178

なぜ -22 // 10 は -3 を返すのですか？

i % j が j と同じ符号であってほしいことに基づいています。それに加えて以下のようにもしたいとすると:

i == (i // j) * j + (i % j)

整数除算は床を返すことになります。C にも C の一貫性があって、i % j が i と同じ符号を持つように i // j を丸めています。

i % j は、j が負の時には実際にはほとんど使いません。j が正なら、たくさん使います。その事実上すべての場合、i % j は >= 0 となる方が便利です。時計が 10 時を指している時、その 200 時間前は何時でしょうか。-190 % 12 == 2 となるのが便利です。-190 % 12 == -10 は噛み付きかねないバグです。

どうすれば SyntaxError を起こさずに整数リテラルの属性を得られますか？

ふつうの方法で int リテラルの属性を探そうとすると、ピリオドが小数点とみなされ、SyntaxError となります:

>>> 1.__class__
  File "<stdin>", line 1
  1.__class__
   ^
SyntaxError: invalid decimal literal

解決策は、リテラルとピリオドを スペースや括弧で分けることです。

>>> 1 .__class__
<class 'int'>
>>> (1).__class__
<class 'int'>

文字列を数に変換するにはどうしたらいいですか？

整数に変換するには、組み込みの int() 型コンストラクタを使ってください。例えば、 int('144') == 144 です。同様に、 float() は浮動小数点に変換します。例えば、 float('144') == 144.0 です。

デフォルトでは、これらは数を十進数として解釈するので、 int('0144') == 144 は成立しますが int('0x144') は ValueError を送出します。 int(string, base) はオプションの第二引数をとって変換元の基数にします。つまり int( '0x144', 16) == 324 です。基数が 0 と指定された場合、その数は Python の基準によって解釈されます。先頭が '0o' なら八進数で、'0x' なら十六進数を表します。

文字列を数に変換するだけのために eval() を使わないでください。 eval() は特に遅いですし、セキュリティ上のリスクもあります。求められない副作用を持つような Python の式を渡そうとする人がいるかも知れません。例えば、あなたのホームディレクトリを消去する __import__('os').system("rm -rf $HOME") を渡そうとする人がいるかも知れません。

eval() にも数を Python の式として解釈する機能があります。だから例えば、 eval('09') は構文エラー起こします。Python は ('0' 以外の) 十進数を '0' で始めてはならないからです。

数を文字列に変換するにはどうしたらいいですか？

例えば、144 という数を '144' という文字列に変換したいなら、組み込み型のコンストラクタ str() を使ってください。十六進数や八進数にしたければ、組み込み関数の hex() や oct() を使ってください。手の込んだフォーマット形式を使うなら、 f-strings と 書式指定文字列の文法 の節を参照してください。例えば、 "{:04d}".format(144) は '0144' になり、 "{:.3f}".format(1.0/3.0) は '0.333' になります。

文字列をインプレースに変更するにはどうしたらいいですか？

文字列はイミュータブルなので、それはできません。殆どの場合、組み立てたい個別の部品から単純に新しい文字列を構成するべきです。しかし、Unicode データをインプレースに変更できるオブジェクトが必要なら、 array モジュールの io.StringIO オブジェクトを試してください:

>>> 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('u', s)
>>> print(a)
array('u', 'Hello, world')
>>> a[0] = 'y'
>>> print(a)
array('u', 'yello, world')
>>> a.tounicode()
'yello, world'

関数やメソッドを呼ぶのに文字列を使うにはどうしたらいいですか？

様々なテクニックがあります。

一番いいのは、文字列を関数に対応させる辞書を使うことです。このテクニックの一番の利点は、文字列が関数の名前と同じ必要がないことです。この方法は case 構造をエミュレートするための一番のテクニックでもあります:

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

組み込み関数の getattr() を使う方法:

import foo
getattr(foo, 'bar')()

なお、 getattr() はクラス、クラスインスタンス、モジュールなど、どんなオブジェクトにも使えます。

これは標準ライブラリでも何箇所か使われています。このように:

class Foo:
    def do_foo(self):
        ...

    def do_bar(self):
        ...

f = getattr(foo_instance, 'do_' + opname)
f()

locals() を使って関数名を決める方法:

def myFunc():
    print("hello")

fname = "myFunc"

f = locals()[fname]
f()

文字列から後端の改行を取り除く Perl の chomp() に相当するものはありますか？

S.rstrip("\r\n") を使って文字列 S の終端から他の空白文字を取り除くことなくすべての行末記号を取り除くことができます。文字列 S が複数行を表し、終端に空行があるとき、そのすべての空行も取り除かれます:

>>> lines = ("line 1 \r\n"
...          "\r\n"
...          "\r\n")
>>> lines.rstrip("\n\r")
'line 1 '

これは典型的に一度に一行ずつテキストを読みたい時にのみ使われるので、S.rstrip() をこの方法で使うとうまくいきます。

scanf() や sscanf() と同等なものはありますか？

そのようなものはありません。

簡単な入力解析で、多くの場合に一番簡単な方法は、文字列オブジェクトの split() メソッドで行を空白文字で区切られた単語に分け、十進数の文字列を int() や float() で数値に変換することです。 split() にはオプションの "sep" 変数があり、行に空白文字以外の区切りを使っているときに便利です。

もっと複雑な入力解析をしたいなら、C の sscanf よりも正規表現の方が便利ですし、この処理に向いています。

'UnicodeDecodeError' や 'UnicodeEncodeError' はどういう意味ですか？

Unicode HOWTO を参照して下さい。

raw string を奇数個のバックスラッシュで終えることはできますか？

奇数個のバックスラッシュで終わる raw string は文字列のクォートをエスケープします:

>>> r'C:\this\will\not\work\'
  File "<stdin>", line 1
    r'C:\this\will\not\work\'
         ^
SyntaxError: unterminated string literal (detected at line 1)

これにはいくつかの回避策があります。ひとつは通常文字列と二重バックスラッシュを使うことです:

>>> 'C:\\this\\will\\work\\'
'C:\\this\\will\\work\\'

もうひとつは、エスケープされたバックスラッシュを含む通常の文字列を、 raw string に連結します:

>>> r'C:\this\will\work' '\\'
'C:\\this\\will\\work\\'

Windowsでは、 os.path.join() を使ってバックスラッシュを追加することもできます:

>>> os.path.join(r'C:\this\will\work', '')
'C:\\this\\will\\work\\'

注意点として、バックスラッシュは raw string 終端のクォートを「エスケープ」しますが、 raw string の値を解釈する際にはエスケープが生じません。つまり、バックスラッシュは raw string 値の中に残ったままになります:

>>> r'backslash\'preserved'
"backslash\\'preserved"

言語リファレンス の仕様も参照してください。

性能

プログラムが遅すぎます。どうしたら速くなりますか？

これは、一般的に難しい問題です。まず、先に進む前に覚えておいて欲しいことをここに挙げます:

性能の傾向は Python 実装によって変わります。この FAQ では CPython に焦点を当てます。

振る舞いはオペレーティングシステムによって変わりえます。特に、I/O やマルチスレッドに関しては顕著です。

常に、コードの最適化を始める 前に プログラムのホットスポットを見つけるべきです (profile モジュールを参照してください)。

ベンチマークスクリプトを書くことで、改善箇所の捜索を素早く繰り返せます (timeit モジュールを参照してください)。

洗練された最適化に隠れたリグレッションの可能性を生む前に、(ユニットテストやその他の技法で) コードカバレッジを上げることを強く推奨します。

とは言っても、Python コードを高速化する技法はたくさんあります。ここでは、満足な性能のレベルにたどり着くまでの長い道のりを進む、一般的な方針を示します:

コード中に細かい最適化の技法をばらまこうとするよりも、アルゴリズムを高速化 (または高速なアルゴリズムに変更) するほうが、大きな利益を生むことがあります。

適切なデータ構造を使ってください。組み込み型 や collections を調べてください。

何かをするための基本要素が標準ライブラリにあるなら、自分で発明した代用品よりもそちらのほうが、(絶対にとは言えませんが) おそらく速いです。それが組み込み型やある種の拡張型のように C で書かれたものならなおさらです。たとえば、ソートするには、必ず list.sort() 組み込みメソッドか sorted() 関数を使ってください (また、中程度に高度な例は、 Sorting Techniques を参照してください)。

抽象化は、遠回りにしがちで、インタプリタの作業を増やすことになります。この遠回りさが、なされる作業の量より重大になると、プログラムが遅くなってしまいます。過度な抽象化、特に細かい関数やメソッドの形で現れるもの (これは読みにくさも落とします) は防ぐべきです。

pure Python にできる限界に達したなら、更に進むためのツールがあります。例えば、Cython [https://cython.org] は、Python コードのわずかに変形した版を C 拡張にコンパイルし、多種のプラットフォームで使えます。Cython は、コンパイル (と任意の型アノテーション) を利用し、コードの解釈を大幅に速くします。C プログラミングに自信があるなら、自分で write a C extension module こともできます。

参考

パフォーマンス tips [https://wiki.python.org/moin/PythonSpeed/PerformanceTips] が載っている wiki のページ。

多くの文字列を結合するのに最も効率的な方法は何ですか？

str および bytes オブジェクトはイミュータブルなので、多くの文字列の結合は結合ごとに新しいオブジェクトを作成し、効率が悪いです。一般的に、全体の実行時間のコストは文字列の長さの二乗に比例します。

多くの str オブジェクトを累積するのにおすすめのイディオムは、すべてをリストに配置してから最後に str.join() を呼び出すことです:

chunks = []
for s in my_strings:
    chunks.append(s)
result = ''.join(chunks)

(他の割と効率的なイディオムは、 io.StringIO を使うことです)

多くの bytes オブジェクトを累積するのにおすすめのイディオムは、 bytearray オブジェクトをインプレース結合 (+= 演算子) で拡張することです:

result = bytearray()
for b in my_bytes_objects:
    result += b

シーケンス(タプル/リスト)

タプル、リスト間の変更はどのようにするのですか？

型コンストラクタ tuple(seq) はすべてのシーケンス (実際には、すべてのイテラブル) を同じ要素、同じ順序のタプルに変換します。

例えば、 tuple([1, 2, 3]) は (1, 2, 3) を与え、 tuple('abc') は ('a', 'b', 'c') を与えます。引数がタプルなら、コピーを作らずに引数のオブジェクトそのものを返すので、あるオブジェクトが既にタプルになっているか確信が持てないのなら、 tuple() を呼ぶのが手軽です。

型コンストラクタ list(seq) はすべてのシーケンスあるいはイテラブルを同じ要素、同じ順序のリストに変換します。例えば、list((1, 2, 3)) は [1, 2, 3] を与え、list('abc') は ['a', 'b', 'c'] を与えます。引数がリストなら、seq[:] と同様にコピーを作ります。

負の添え字は何ですか？

Python のシーケンスは正の数と負の数でインデクスされます。正の数では、0 が最初のインデクス、1 が 2 番目のインデクス、以下も同様です。負のインデクスでは、-1 が最後のインデクス、-2 が最後から 2 番目のインデクス、以下も同様です。seq[-n] は seq[len(seq)-n] と同じだと考えてください。

負のインデクスを使うと便利なことがあります。例えば、S[:-1] は文字列の最後以外のすべての文字を表すので、文字列の末尾の改行を取り除くときに便利です。

シーケンスを逆順にイテレートするにはどうしたらいいですか？

組み込み関数 reversed() を使ってください。

for x in reversed(sequence):
    ...  # do something with x ...

これは元のシーケンスをいじるのではなく、逆順の新しいコピーを作ってイテレートさせます。

リストから重複を取り除くにはどうしますか？

Python Cookbook の長い議論に多くの方法があるので参照してください:

https://code.activestate.com/recipes/52560/

リストを並び替えて構わないのなら、ソートした上でリストの最初から最後までを調べ、次のように重複を削除してください:

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]

リストのすべての要素が集合のキーとして使える (つまり、すべての要素が hashable) なら、おそらくこのほうが速いです

mylist = list(set(mylist))

リストを集合に変換するときに重複は取り除かれるので、それをリストに戻せばいいのです。

リストから複数のアイテムを取り除く方法

重複除去と同様に、削除条件を付けて明示的に逆回すのも一つの方法です。ですが、明示的/暗黙的な反復でスライス置換する方が速くて簡単です。こちらは３つのバリエーションです。:

mylist[:] = filter(keep_function, mylist)
mylist[:] = (x for x in mylist if keep_condition)
mylist[:] = [x for x in mylist if keep_condition]

リスト内包表記がおそらく最も高速です。

Python で配列を作るにはどうしますか？

リストを使ってください:

["this", 1, "is", "an", "array"]

リストの時間計算量は C や Pascal の配列と同じです。大きな違いは、Python のリストは多くの異なる型のオブジェクトを含めることです。

array モジュールにも固定された型を簡潔に表現する配列を作るためのメソッドがありますが、リストよりもインデクスが遅いです。また、NumPy [https://numpy.org/] やその他のサードパーティー拡張でも、様々な特徴をもつ配列的な構造体が定義されています。

Lisp 方式の連結リストを得るのに、タプルを使って cons cells をエミュレートできます:

lisp_list = ("like",  ("this",  ("example", None) ) )

ミュータブルな必要があるなら、タプルではなくリストを使いましょう。Lisp の car にあたるものが lisp_list[0] で、cdr にあたるものが lisp_list[1] です。本当に必要だと確信できるとき以外はこれはしないでください。たいてい、これは Python のリストを使うよりも非常に遅いですから。

多次元のリストを作るにはどうしますか？

このようにして多次元の配列を作ろうとしてしまったことがあるでしょう:

>>> A = [[None] * 2] * 3

これを表示したときには問題なさそうに見えます:

>>> A
[[None, None], [None, None], [None, None]]

しかし値を代入すると、その値が複数の場所に現れてしまいます:

>>> A[0][0] = 5
>>> A
[[5, None], [5, None], [5, None]]

これは、* を使ったリストの複製がコピーを作らず、存在するオブジェクトへの参照を作るだけだからです。この *3 は長さ 2 の同じリストへの参照を含むリストを作ります。一つの列に対する変更はすべての列に現れますが、これが望んだ結果であることはまずないでしょう。

おすすめの方法は、最初に望んだ長さのリストを作り、それから新しく作ったリストでそれぞれの要素を埋めていくことです:

A = [None] * 3
for i in range(3):
    A[i] = [None] * 2

これは長さ 2 の異なるリスト 3 つを含むリストを生成します。リスト内包表記も使えます:

w, h = 2, 3
A = [[None] * w for i in range(h)]

あるいは、行列データ型を提供している拡張を使用することもできます; NumPy [https://numpy.org/] が最もよく知られています。

オブジェクトのシーケンスにメソッドや関数を適用するにはどうしますか？

メソッドや関数を呼び出して結果を蓄積するのには、 list comprehension （リスト内包表記） がエレガントな解決策です:

result = [obj.method() for obj in mylist]

result = [function(obj) for obj in mylist]

戻り値を保存せずにメソッドや関数を実行するだけなら、ただの for ループで十分です:

for obj in mylist:
    obj.method()

for obj in mylist:
    function(obj)

なぜ加算はされるのに a_tuple[i] += ['item'] は例外を送出するのですか?

これは、累算代入演算子は 代入 演算子だ、という事実と、Python での可変オブジェクトと不変オブジェクトの違いが組み合わさって起きるのです。

この議論は一般的に、可変オブジェクトを指すタプルの要素に、累算代入演算子が適用されたときにも適用できますが、例として list と += を使います。

次のように書いたとします:

>>> a_tuple = (1, 2)
>>> a_tuple[0] += 1
Traceback (most recent call last):
   ...
TypeError: 'tuple' object does not support item assignment

例外が送出された理由は明らかです: 1 が (1) を指すオブジェクト a_tuple[0] に加えられ、結果のオブジェクト 2 が生成されますが、計算結果 2 をタプルの第 0 要素に代入しようとしたときに、エラーが発生します。なぜならば、タプルの要素が何を指すかは変えられないからです。

このような裏事情の元、累算代入文はだいたい次のようなことをしています:

>>> result = a_tuple[0] + 1
>>> a_tuple[0] = result
Traceback (most recent call last):
  ...
TypeError: 'tuple' object does not support item assignment

タプルは不変なので、例外を生み出しているのは操作の代入部分なのです。

次のように書いたとします:

>>> a_tuple = (['foo'], 'bar')
>>> a_tuple[0] += ['item']
Traceback (most recent call last):
  ...
TypeError: 'tuple' object does not support item assignment

この例外にはちょっと驚きますが、もっと驚くべきことは、エラーがあったとしても追記はきちんと動いている、という事実です:

>>> a_tuple[0]
['foo', 'item']

なぜこれが起きるかを調べるためには、次の 2 点を知っている必要があります。(a) オブジェクトに __iadd__() 特殊メソッドが実装されている場合、拡張代入 += が実行されるときにそれが呼び出され、その返り値が代入文で使われます; (b) リストでは、__iadd__() は extend() の呼び出しと等価で、リストを返します。こんな理由で、リストでは += は list.extend() の "略記" だと言ったのでした:

>>> a_list = []
>>> a_list += [1]
>>> a_list
[1]

これは次と等価です:

>>> result = a_list.__iadd__([1])
>>> a_list = result

a_list が指していたオブジェクトは更新され、更新されたオブジェクトへのポインタは再度 a_list に代入されます。代入しているのは、a_list が更新前まで指していた同じオブジェクトへのポインタなので、代入は最終的には何もしていないのですが、代入処理自体は起きています。

従って、今のタプルの例では、次のと同じことが起きています:

>>> result = a_tuple[0].__iadd__(['item'])
>>> a_tuple[0] = result
Traceback (most recent call last):
  ...
TypeError: 'tuple' object does not support item assignment

__iadd__() は成功し、リストは拡張 (extend) されますが、result が a_tuple[0] が既に指しているオブジェクトと同じオブジェクトを指していたとしても、タプルは不変なので、その最後の代入はやはりエラーとなります。

複雑なソートがしたいのですが、Python でシュワルツ変換はできますか？

Perl コミュニティの Randal Schwartz の作とされるこのテクニックは、リストの要素を、それぞれの要素をその「ソート値」に対応付けるメトリックによってソートします。Python では、 list.sort() メソッドに key 引数を使ってください:

Isorted = L[:]
Isorted.sort(key=lambda s: int(s[10:15]))

リストを別のリストの値によってソートするにはどうしますか？

二つのイテレータを混ぜあわせてタプルのイテレータにしてから、必要な要素を選んでください。

>>> 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']

オブジェクト

クラスとは何ですか？

クラスは、class 文の実行で生成される特殊なオブジェクトです。クラスオブジェクトはインスタンスオブジェクトを生成するためのテンプレートとして使われ、あるデータ型に特有のデータ (attribute/属性) とコード (メソッド) の両方を内蔵しています。

新しいクラスを一つ以上の他のクラス (新しいクラスの基底クラスと呼ばれます) に基づいて作ることもできます。この新しいクラスは、基底クラスから属性とメソッドを継承します。これにより、オブジェクトモデルを継承で連続的に洗練できます。メールボックスへの基本的なアクセサを提供する一般的な Mailbox クラスを作って、それからいろいろな特定のメールボックスの形式を扱う MboxMailbox、MaildirMailbox、OutlookMailbox のようなサブクラスを作れるのです。

メソッドとは何ですか？

メソッドは、オブジェクト x が持つ関数で、通常 x.name(arguments...) として呼び出されるものです。メソッドはクラス定義の中で関数として定義されます:

class C:
    def meth(self, arg):
        return arg * 2 + self.attribute

self とは何ですか？

self はメソッドの第一引数に慣習的につけられる名前にすぎません。meth(self, a, b, c) として定義されたメソッドは、その定義がなされたクラスのインスタンス x に対して x.meth(a, b, c) として呼び出されます。呼び出されたメソッドは、meth(x, a, b, c) が呼ばれたものと考えます。

なぜメソッドの定義や呼び出しにおいて 'self' を明示しなければならないのですか？ も参照してください。

あるオブジェクトが、与えられたクラスやそのサブクラスのインスタンスであるかを調べるにはどうしますか？

ビルトイン関数 isinstance(obj, cls) を使ってください。クラスのタプルを与えて isinstance(obj, (class1, class2, ...)) のようにすれば、あるオブジェクトが任意の数のクラスのオブジェクトであるかを調べられますし、isinstance(obj, str) や isinstance(obj, (int, float, complex)) のようにすれば、Python のビルトイン型のオブジェクトであるかも調べられます。

注意： isinstance() は abstract base class (抽象基底クラス)からの仮想継承もチェックします。そのため、登録 (register) されたクラスが直接/間接的にそれを継承していなくても True を返します。「真のインスタンス」をテストする場合は、クラスの MRO を調べます:

from collections.abc import Mapping

class P:
     pass

class C(P):
    pass

Mapping.register(P)

>>> c = C()
>>> isinstance(c, C)        # direct
True
>>> isinstance(c, P)        # indirect
True
>>> isinstance(c, Mapping)  # virtual
True

# Actual inheritance chain
>>> type(c).__mro__
(<class 'C'>, <class 'P'>, <class 'object'>)

# Test for "true inheritance"
>>> Mapping in type(c).__mro__
False

なお、大部分のプログラムでは、 isinstance() をユーザー定義のクラスに何度も使うべきではありません。クラスを自分で開発するときに、適切なオブジェクト指向スタイルは、特定の振る舞いをカプセル化するクラスのメソッドを定義するものであって、オブジェクトのクラスを調べてそのクラスに応じて違うことをするものではありません。例えば、何かをする関数があったとして:

def search(obj):
    if isinstance(obj, Mailbox):
        ...  # code to search a mailbox
    elif isinstance(obj, Document):
        ...  # code to search a document
    elif ...

よりよいアプローチは、search() メソッドをすべてのクラスに定義して、それをただ呼び出すことです:

class Mailbox:
    def search(self):
        ...  # code to search a mailbox

class Document:
    def search(self):
        ...  # code to search a document

obj.search()

委譲とは何ですか？

委譲 (delegation) とは、オブジェクト指向のテクニック (デザインパターンとも呼ばれる) の一つです。オブジェクト x があって、そのメソッドのうちただ一つの振る舞いを変えたいとしましょう。新しいクラスを作成し、変えたいメソッドだけを新しく実装し、他のすべてのメソッドを x の対応するメソッドに委譲する新しいクラスを作れます。

Python プログラマは簡単に委譲を実装できます。例えば、以下のクラスは、ファイルのように振る舞いながらすべての文字を大文字に変換するクラスを実装します:

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)

ここで UpperOut クラスは write() メソッドを定義しなおして、引数の文字列を大文字に変換してから基礎となる self._outfile.write() メソッドを呼び出すようにします。その他すべてのメソッドは基礎となる self._outfile オブジェクトに移譲されます。この委譲は __getattr__() メソッドを通してなされます。属性の制御の詳細は 言語リファレンス を参照してください。

なお、一般的に委譲はトリッキーになりがちです。属性が設定される時には読み出される時と同様に、そのクラスに __setattr__() メソッドを定義する必要があり、それには細心の注意が必要です。 __setattr__() の基本的な実装はおおよそ以下のようになります:

class X:
    ...
    def __setattr__(self, name, value):
        self.__dict__[name] = value
    ...

たいてい、 __setattr__() 実装は self.__dict__ を変更して、無限再帰を起こすことなくローカルな状態を保存するようにしなければなりません。

基底クラスで定義されたメソッドを、そのクラスを継承した派生クラスから呼び出すにはどうしますか？

組み込みの super() 関数を使ってください:

class Derived(Base):
    def meth(self):
        super().meth()  # calls Base.meth

この例では、 super() は呼ばれたインスタンス (self の値) を自動判断し、 type(self).__mro__ で method resolution order (MRO メソッド解決順) を検索し、そしてMRO内で Derived の次行を返します: Base 。

基底クラスの名前を変えやすいコードを書くにはどうしますか？

基底クラスをエイリアス (alias) に代入しておいてから、そのエイリアスを継承するといいかもしれません。そうすればエイリアスに代入する値を変えるだけで済みます。ちなみに、この手法は使用する基底クラスを動的に選びたいとき、例えば使えるリソースによって選びたいときなどにも便利です。例:

class Base:
    ...

BaseAlias = Base

class Derived(BaseAlias):
    ...

静的なクラスデータや静的なクラスメソッドを作るにはどうしますか？

(C++ や Java の意味で) 静的なデータも静的なメソッドも Python でサポートされています。

静的なデータを作るには、単純にクラス属性を定義してください。その属性に新しい値を代入するには、代入するクラス名を明示する必要があります:

class C:
    count = 0   # number of times C.__init__ called

    def __init__(self):
        C.count = C.count + 1

    def getcount(self):
        return C.count  # or return self.count

c そのものや c.__class__ から C にいたるパス探索経路上のクラスによってオーバーライドされない限り、c.count も isinstance(c, C) であるすべての c に対する C.count を参照します。

注意: C のメソッド内では、self.count = 42 のような代入は self 自身の辞書に "count" という名前の新しくて関係ないインスタンスを作ります。クラスの静的なデータの再束縛には、メソッド内であるか否かにかかわらず、いつもクラスを指定しなければなりません:

C.count = 314

静的メソッドが使えます:

class C:
    @staticmethod
    def static(arg1, arg2, arg3):
        # No 'self' parameter!
        ...

しかし、静的メソッドの効果を得るもっと簡単な方法は、単にモジュールレベル関数を使うことです:

def getcount():
    return C.count

モジュールあたりに一つのクラスを定義するように (あるいはクラス組織を厳密に関連させるように) コードが構成されているなら、これで必要なカプセル化ができます。

Python でコンストラクタ(やメソッド)をオーバーロードするにはどうしたらいいですか？

この質問の答えはすべてのメソッドについて言えることですが、この質問はだいたい以下の構造の文脈から出てきます。

C++ では、このように書けます

class C {
    C() { cout << "No arguments\n"; }
    C(int i) { cout << "Argument is " << i << "\n"; }
}

Python では、一つのコンストラクタでデフォルトの引数を使ってすべての場合に対応するように書かなければなりません。例えば:

class C:
    def __init__(self, i=None):
        if i is None:
            print("No arguments")
        else:
            print("Argument is", i)

これで完全に等価とは言えませんが、実用上は十分に近いです。

長さが変えられる引数のリストを試すには、例えば

def __init__(self, *args):
    ...

これと同じやり方がすべてのメソッド定義で使えます。

__spam を使おうとしたら _SomeClassName__spam からエラーがでました。

先頭にアンダースコアが二つ付いた変数名は、クラスのプライベートな変数を、 "マングル化" という単純かつ効率のいい方法で定義します。__spam のような形式 (先頭に二つ以上、末尾にもしあっても一つのアンダースコアがある) のすべての識別子は、classname が先頭のアンダースコアをすべて削除した現在のクラス名とすれば、_classname__spam のように文字上で置換えられます。

これはプライベートであることを保証するものではありません。これでも外部のユーザが "_classname__spam" 属性に直接アクセスできますし、プライベートな変数はオブジェクトの __dict__ から見えます。多くの Python プログラマはわざわざプライベートな変数名を使おうとなど考えません。

クラスに __del__ メソッドを定義しているのですが、オブジェクトを削除したときに呼ばれません。

いくつかの可能性があります。

del 文は必ずしも __del__() を呼び出すとは限りません -- これは単純にオブジェクトの参照カウントを減らすもので、カウントがゼロになったときに __del__() が呼び出されます。

データ構造が循環リンク (子のそれぞれが親の参照を持ち、親のそれぞれが子のリストを持つツリーなど) を含む場合、その参照カウントは決して 0 にはなりません。時々、Python はこのようなサイクルを検出するアルゴリズムを実行しますが、データ構造への参照がなくなってからこのガベージコレクタが実行されるまでいくらか時間が掛かるかもしれないので、 __del__() メソッドは不都合な予期できないタイミングで呼び出されるかもしれません。これは問題を再現しようとするときに不便です。さらに悪いことに、オブジェクトの __del__() メソッドが実行される順序は任意です。 gc.collect() を起動して収集を強制することができますが、オブジェクトが決して回収されないような本当に病的な場合も あります 。

循環参照コレクタがあるとはいえ、オブジェクトに close() メソッドを明示的に定義し、使い終わったらいつでも呼び出せるようにするのはいいことです。 close() メソッドを使うと、サブオブジェクトを参照している属性を取り除けます。 __del__() を直接呼び出さないでください -- __del__() は close() を呼び出すでしょうし、 close() なら同じオブジェクトに対して複数回呼ばれてもいいことが保証されているでしょう。

循環参照を避ける他の方法は、 weakref モジュールを使って、参照カウントを増やすことなくオブジェクトを示すことです。例えばツリー構造は、親と (必要なら！) 兄弟に弱参照を使うべきです。

最後に、 __del__() メソッドが例外を発生させた場合、警告のメッセージが sys.stderr に書きこまれます。

与えられたクラスのすべてのインスタンスのリストを得るにはどうしますか？

Python はクラス (やビルトイン型) のすべてのインスタンスをたどりません。クラスのコンストラクタにそれぞれのインスタンスへの弱参照のリストを作らせることですべてのインスタンスをたどらせられます。

なぜ id() の結果は一意でないように見えるのですか?

組み込みの id() は、オブジェクトが生存している間は一意なことが保証されている整数値を返します。 CPython では、それはオブジェクトのメモリアドレスなので、オブジェクトがメモリから削除された後に、次に新しく生成されたオブジェクトはメモリの同じ場所にメモリ領域を確保されていることが、しばしば起きます。この現象を次の例で示しましょう:

>>> id(1000)
13901272
>>> id(2000)
13901272

2 つの同じ値を持つ id は id() の実行の前に作られてすぐさま削除された異なる整数オブジェクトによるものです。id を調べたいオブジェクトがまだ生きてることを保証したいなら、オブジェクトへの別の参照を作ってください:

>>> a = 1000; b = 2000
>>> id(a)
13901272
>>> id(b)
13891296

いつ is 演算子での同一性テストが頼れますか？

is 演算子はオブジェクトの同一性をテストします。 テスト a is b は id(a) == id(b) と同等です。

同一性テストの最も重要な特性は、オブジェクトは常にそれ自身と同一であり、 a is a は常に True を返すということです。 同一性テストは通常、等価性テストよりも高速です。 また、等価性テストとは異なり、同一性テストは真偽値 True または``False`` を返すことが保証されています。

ただし、同一性テストを等価性テストの代用とできるのは、オブジェクトの同一性が保証されている場合 のみ です。 一般的に、同一性が保証される状況は3つあります:

1） 代入は新しい名前を作りますが、オブジェクトIDは変えません。 new = old 代入の後、 new is old が保証されます。

2） オブジェクト参照を格納するコンテナにオブジェクトを入れても、オブジェクトIDは変わりません。 s[0] = x リスト代入の後、 s[0] is x が保証されます。

3） オブジェクトがシングルトンなら、それはそのオブジェクトのインスタンスは１つだけ存在できることを意味します。 a = None と b = None 代入の後、 a is b が保証されます。None がシングルトンのためです。

多くの他の状況では、同一性テストは賢明でなく、等価性テストをお勧めします。 特に、シングルトンであることが保証されていない int や str などの定数をチェックするために同一性テストを使わないでください。

>>> a = 1000
>>> b = 500
>>> c = b + 500
>>> a is c
False

>>> a = 'Python'
>>> b = 'Py'
>>> c = b + 'thon'
>>> a is c
False

同様に、ミュータブルなコンテナの新しいインスタンスは同一ではありません:

>>> a = []
>>> b = []
>>> a is b
False

標準ライブラリのコードには、同一性テストを正しく使うための一般的なパターンがあります:

1） PEP 8 [https://peps.python.org/pep-0008/] で推奨されるように、同一性テストは None のチェックの良い方法です。 コードの中で平易な英語のように読めますし、 false と評価される真偽値を持ちうる他のオブジェクトとの混同を避けます。

2） None が有効な入力値である場合、省略された引数を検出にはコツがいります。 そのような状況では、他のオブジェクトと区別されることが保証されたシングルトンの番兵オブジェクトを作れます。 例えば、これは dict.pop() のように振る舞うメソッドを実装する方法です:

_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

3） コンテナの実装では、等価性テストを同一性テストで補強しないといけない場合があります。 これは、 float('NaN') のような自分自身と等価でないオブジェクトによってコードが混乱するのを防ぐためです。

例えば、これは collections.abc.Sequence.__contains__(): の実装です:

def __contains__(self, value):
    for v in self:
        if v is value or v == value:
            return True
    return False

どうすればサブクラスはイミュータブルなインスタンスに格納されたデータを制御できますか？

イミュータブル型をサブクラス化する場合、 __init__() ではなく __new__() メソッドを継承します。 前者はインスタンスが生成された 後 に動くため、イミュータブルなインスタンスのデータを変えるには遅すぎます。

これらのイミュータブルクラスはすべて、親クラスと異なるシグネチャを持ちます:

from datetime import date

class FirstOfMonthDate(date):
    "Always choose the first day of the month"
    def __new__(cls, year, month, day):
        return super().__new__(cls, year, month, 1)

class NamedInt(int):
    "Allow text names for some numbers"
    xlat = {'zero': 0, 'one': 1, 'ten': 10}
    def __new__(cls, value):
        value = cls.xlat.get(value, value)
        return super().__new__(cls, value)

class TitleStr(str):
    "Convert str to name suitable for a URL path"
    def __new__(cls, s):
        s = s.lower().replace(' ', '-')
        s = ''.join([c for c in s if c.isalnum() or c == '-'])
        return super().__new__(cls, s)

クラスはこのように使えます:

>>> FirstOfMonthDate(2012, 2, 14)
FirstOfMonthDate(2012, 2, 1)
>>> NamedInt('ten')
10
>>> NamedInt(20)
20
>>> TitleStr('Blog: Why Python Rocks')
'blog-why-python-rocks'

メソッド呼び出しをキャッシュするには どうしたらいいですか？

メソッドキャッシュの主な道具は２つあり、 functools.cached_property() と functools.lru_cache() です。前者はインスタンスレベル、後者はクラスレベルで結果を保存します。

cached_property アプローチは、引数を取らないメソッドでのみ働きます。これはインスタンスへの参照を作りません。キャッシュされたメソッドの結果は、インスタンスが生きている間だけ保持されます。

利点は、インスタンスが使われなくなった場合、キャッシュされたメソッドの結果がすぐに解放されることです。欠点は、インスタンスが溜まると、溜められたメソッドの結果も増えてしまうことです。それらは際限なく増える恐れがあります。

lru_cache アプローチは、 hashable な引数を持つメソッドで働きます。 weak references を渡すための特別な努力がない限り、インスタンスへの参照を作ります。

least recently used アルゴリズム（訳注：LRU 直近に使われたものを残す）の利点は、キャッシュが指定された maxsize で制限されることです。欠点は、キャッシュから期限切れで追い出されるかクリアされるまで、インスタンスが生き続けることです。

この例は各種テクニックを示します:

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.

上の例では、 station_id が常に変わらないことを前提としています。関連するインスタンスの属性が可変である場合、 cached_property アプローチは属性の変更を検出できないため、機能しなくなります。

station_id が可変の場合に lru_cache アプローチを機能させるには、クラスで __eq__() と __hash__() メソッドを定義する必要があります。これにより、キャッシュは関連する属性の更新を検出できます:

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.

モジュール

.pyc ファイルを作るにはどうしますか？

モジュールが初めてインポートされたとき (もしくは、現在のコンパイルされたファイルが作られてから、ソースファイルが変更されたとき) 、コンパイルされたコードが入っている .pyc ファイルが、 .py ファイルのあるディレクトリのサブディレクトリ __pycache__ に作成されます。 .pyc ファイルのファイル名は、 .py ファイルの名前で始まり、 .pyc で終わり、中間部分はこのファイルを作った python バイナリに依存した文字列になります。 (詳細は PEP 3147 [https://peps.python.org/pep-3147/] を参照してください。)

.pyc が作られない理由の 1 つは、ソースファイルがあるディレクトリの権限の問題、つまり __pycache__ サブディレクトリが作れない問題です。これは、例えば、ウェブサーバーでテストを行っているときのような、開発者のユーザと実行者のユーザが別な場合に、起こり得ます。

PYTHONDONTWRITEBYTECODE 環境変数がセットされない限り、モジュールをインポートしていて、 Python に __pycache__ サブディレクトリを作り、そこにコンパイルされたモジュールが置ける能力 (権限、ディスクの空きスペース、など) がある場合は、 .pyc ファイルは自動的に作られます。

最上位のスクリプトを Python で実行するのはインポートとはみなされず、.pyc は作成されません。例えば、最上位のモジュール foo.py が別のモジュール xyz.py をインポートしている場合、(シェルコマンドとして python foo.py と打ち込んで) foo を実行すると、xyz はインポートされるので xyz の .pyc は作成されますが、foo.py はインポートされたわけではないので foo の .pyc は作られません。

foo の .pyc ファイルを作成する -- つまり、インポートされていないモジュールの .pyc ファイルを作成する -- 必要がある場合、 py_compile モジュールと compileall モジュールを使えば可能です。

py_compile モジュールは手動で任意のモジュールをコンパイルできます。やり方の一つは、このモジュールの compile() 関数をインタラクティブに実行することです:

>>> import py_compile
>>> py_compile.compile('foo.py')

このように実行すると、foo.py と同じ場所の __pycache__ サブディレクトリに .pyc が書き出されます (出力ファイルの位置は、オプション引数 cfile で上書きすることもできます)。

compileall モジュールを使えば自動的に一つや複数のディレクトリのすべてのファイルをコンパイルできます。シェルプロンプトから compileall.py を起動して、コンパイルしたいファイルを含むディレクトリのパスを指定してください:

python -m compileall .

現在のモジュール名を知るにはどうしますか？

モジュールは前もって定義されたグローバル変数 __name__ を検索することで自身の名前を決定できます。この値が '__main__' であるとき、そのプログラムはスクリプトとして実行されています。インポートされることによって使われる大抵のモジュールはコマンドラインインターフェースや自己テストも提供していて、__name__ をチェックしてからそのコードだけを実行します:

def main():
    print('Running test...')
    ...

if __name__ == '__main__':
    main()

相互にインポートしあうモジュールを作るにはどうしたらいいですか？

以下のモジュールがあったとしましょう:

foo.py:

from bar import bar_var
foo_var = 1

bar.py:

from foo import foo_var
bar_var = 2

問題はインタプリタが以下の段階を実行することです:

main が foo をインポートする

foo の空のグローバルが生成される

foo がコンパイルされ実行を始める

foo が bar をインポートする

bar の空のグローバルが生成される

bar がコンパイルされ実行を始める

bar が foo をインポートする(すでに foo という名前のモジュールがあるので no-op となる)

インポートメカニズムは foo のグローバルから foo_var を読んで、 bar.foo_var = foo.foo_var に設定しようとします。

この最後の段階は失敗します。Python が foo を解釈し終わっていなくて、foo のグローバルなシンボルの辞書はまだ空ですから。

import foo を使って、グローバルコードの foo.foo_var にアクセスしようとしたときにも、これと同じことが起こります。

この問題には (少なくとも) 三つの解決策があります。

Guido van Rossum は from <module> import ... を全く使わないで、すべてのコードを関数の中に入れることを勧めています。グローバル変数とクラス変数の初期化は定数とビルトイン関数のみで行われるべきです。これでインポートされたすべてのモジュールは <module>.<name> として参照されることになります。

Jim Roskind はそれぞれのモジュールに対して以下の順に進めることを提案しています:

エクスポート (インポートされた基底クラスを必要としないグローバル、関数、クラス)

import 文

アクティブなコード (インポートされた値によって初期化されるグローバルを含む)。

インポートが奇妙な場所に現れることから Van Rossum はこの方法をそれほど好みませんが、これは有効です。

Matthias Urlichs は第一に再帰インポートが必要ないようにコードを構築しなおすことを推奨しています。

これらの解決策はそれぞれ両立させることもできます。

__import__('x.y.z') は <module 'x'> を返しますが、z を得るためにはどうしますか？

importlib に import_module() という便利な関数があるので、代わりにそちらを使用することを検討してください。

z = importlib.import_module('x.y.z')

インポートされたモジュールを編集してから再インポートしましたが、変化が現れません。なぜですか？

効率と一貫性上の理由から、Python はモジュールが最初にインポートされた時にのみモジュールファイルを読み込みます。そうしないと、たくさんのモジュールでできていて、それぞれが同じ基本モジュールをインポートしているようなプログラムでは、その基本モジュールの解析と再解析が繰り返されることになります。変更されさたモジュールの再読込を強制するには、こうしてください:

import importlib
import modname
importlib.reload(modname)

注意:この手法は 100%安全とは言えません。とりわけ

from modname import some_objects

のような文を含むモジュールは、インポートされたオブジェクトの古いバージョンを使い続けます。そのモジュールにクラス定義が含まれていたら、存在するクラスインスタンスは新しいクラス定義を使うようにアップデート されません。これによって以下の矛盾した振舞いがなされえます:

>>> import importlib
>>> import cls
>>> c = cls.C()                # Create an instance of C
>>> importlib.reload(cls)
<module 'cls' from 'cls.py'>
>>> isinstance(c, cls.C)       # isinstance is false?!?
False

この問題の本質は、クラスオブジェクトの "固有値" を印字することで明らかになります:

>>> hex(id(c.__class__))
'0x7352a0'
>>> hex(id(cls.C))
'0x4198d0'

デザインと歴史 FAQ

目次

デザインと歴史 FAQ

Python はなぜ文のグループ化にインデントを使うのですか？

なぜ単純な算術演算が奇妙な結果になるのですか？

なぜ浮動小数点数の計算はこんなに不正確なんですか？

なぜ Python の文字列はイミュータブルなのですか？

なぜメソッドの定義や呼び出しにおいて 'self' を明示しなければならないのですか？

式中で代入ができないのはなぜですか？

Python にメソッドを使う機能 (list.index() 等) と関数を使う機能 (len(list) 等) があるのはなぜですか？

join() がリストやタプルのメソッドではなく文字列のメソッドなのはなぜですか？

例外はどれくらい速いのですか？

Python に switch や case 文がないのはなぜですか？

OS 特有のスレッド実装に依らずにインタプリタでスレッドをエミュレートすることはできないのですか？

なぜラムダ式は文を含むことができないのですか?

Python は C やその他の言語のように機械語にコンパイルできますか？

Python はメモリをどのように管理するのですか？

CPython はなぜ伝統的なガベージコレクションスキームを使わないのですか？

なぜ CPython の終了時にすべてのメモリが解放されるわけではないのですか？

なぜタプルとリストという別のデータ型が用意されているのですか？

CPythonでリストはどのように実装されているのですか？

CPythonで辞書はどのように実装されていますか？

なぜ辞書のキーはイミュータブルでなくてはならないのですか？

なぜ list.sort() はソートされたリストを返さないのですか？

Python ではどのようにインターフェース仕様を特定し適用するのですか？

なぜ goto が無いのですか？

なぜ raw 文字列 (r-strings) はバックスラッシュで終わってはいけないのですか？

属性の代入に "with" 文が使えないのはなぜですか？

なぜジェネレータは with 文をサポートしないのですか？

if/while/def/class 文にコロンが必要なのはなぜですか？

なぜ Python ではリストやタプルの最後にカンマがあっても良いのですか？

Python はなぜ文のグループ化にインデントを使うのですか？

Guido van Rossum の信じるところによれば、インデントによるグループ化は非常にエレガントで、普通の Python プログラムを大いに読みやすくします。しばらくすればほとんどの人はこの仕様を気に入るようになります。

開始/終了の括弧がないので、構文解析器と人間の読者の間にグループ化の解釈の違いは起こりえません。時折、C のプログラマはこのようなコード片に出くわします:

if (x <= y)
        x++;
        y--;
z++;

条件式が真のとき、 x++ 行のみが実行されます。しかしインデントによって、多くの人が別のことを考えてしまいます。経験豊富なCプログラマでさえ、 x > y なのに y がデクリメントされるのはなぜだろうと、このコードをしばらく凝視することがあります。

Python は開始/終了の括弧がないので、コーディングスタイルの争いに余り影響されません。C言語では中括弧の置き方についてさまざまな流儀があります。特定のスタイルを使ってコードを読み書きするのに慣れたあと、別のスタイルでコードを読んだり(あるいは書く必要に迫られたり)するときに、何となく心配になるのはよくあることです。

多くのコーディングスタイルは begin/end の括弧にそれぞれ一行を使います。これではプログラムは冗長になって画面を浪費し、プログラムの見通しが悪くなります。一つの関数は一画面 (例えば 20 から 30 行) に収めるのが理想です。20 行の Python は 20 行の C よりもはるかに多くの作業ができます。これは begin/end の括弧がないからだけではありません -- 宣言が不要なことや高レベルなデータ型もその理由です -- が、インデントに基づく構文は確かに役に立っています。

なぜ単純な算術演算が奇妙な結果になるのですか？

次の質問を参照してください。

なぜ浮動小数点数の計算はこんなに不正確なんですか？

ユーザーはよく次のような結果に驚きます:

>>> 1.2 - 1.0
0.19999999999999996

そしてこれが Python のバグだと考えます。が、これはバグではありません。この結果に Python はほとんど関与しておらず、むしろ基底のプラットフォームによる浮動小数点数の扱い方が関与しています。

CPython における float 型は記憶に C 言語の double 型を使います。 float オブジェクトの値は固定精度 (典型的には 53 bit) の 2 進浮動小数点数として格納され、 Python はプロセッサのハードウェアが実装している C 言語上の演算を使います。つまり、浮動小数点数に関して Python は C 言語や Java のような多くの一般的な言語と同じように振る舞います。

10 進数で簡単に書ける多くの数が、2 進浮動小数点数では正確に表すことができません。例えばこうすると:

>>> x = 1.2

x に保存された値は 10 進数の 1.2 の (とても高い精度の) 近似値であって、厳密な 1.2 ではありません。一般的なコンピューターでは、実際に格納される値は:

1.0011001100110011001100110011001100110011001100110011 (binary)

で、正確には次の値です:

1.1999999999999999555910790149937383830547332763671875 (decimal)

53bit の典型的な精度は、Python の float に 10 進数で 15〜16桁の精度を与えます。

詳しくは、Python チュートリアルの floating point arithmetic の章を参照してください。

なぜ Python の文字列はイミュータブルなのですか？

これにはいくつかの利点があります。

一つはパフォーマンスです。文字列がイミュータブルなら、生成時に領域を割り当てることができるので、必要な記憶域は固定されて、変更されません。これはタプルとリストを区別する理由の一つでもあります。

他の利点は、Python の文字列は数と同じくらい "基本的" なものと考えられることです。8 という値を他の何かに変える手段が無いように、文字列 "eight" を他の何かに変える手段も無いのです。

なぜメソッドの定義や呼び出しにおいて 'self' を明示しなければならないのですか？

このアイデアは Modula-3 から取り入れられました。これは様々な理由からとても便利だと言えます。

まず、ローカル変数ではなく、メソッドやインスタンス属性を扱っていることがより明確になります。 self.x や self.meth() と書いてあれば、そのクラスの定義を憶えていなくても、それがインスタンス変数やメソッドであることは明らかです。C++ では、(グローバルが滅多になかったり、簡単に見分けがつくなら) ローカル変数宣言がないことからある程度わかるでしょう。-- しかし Python にはローカル変数宣言がないので、クラス定義を調べて確かめなくてはなりません。C++ や Java のコーディングスタンダードに、インスタンス属性に m_ 接頭辞をつけるものがあるので、この明示性はそれらの言語においても有用です。

第二に、特定のクラスからメソッドを明示的に参照または呼び出ししたい時に、特別な構文が必要なくなります。C++ では、派生クラスでオーバーライドされた基底クラスからメソッドを使うには、 :: 演算子を使わなければなりません。 -- Python では、 baseclass.methodname(self, <argument list>) と書けます。これは特に、 __init__() メソッドに便利ですし、派生クラスのメソッドが、基底クラスにある同じ名前のメソッドを拡張するために、基底クラスのメソッドをどうにかして呼び出したい時にも便利です。

最後に、インスタンス変数に対する、代入の構文の問題を解決できます。Python のローカル変数は、関数の中で (global が明示的に宣言されることなく) 値が代入された変数 (と定義されています！) です。なので、ある代入が意図するのが、ローカル変数へではなくインスタンス変数への代入であると、インタプリタが判断する手段が必要です。そしてそれは構文を見るだけで分かる方が (効率が) 良いのです。C++ ではその区別を宣言時に行いますが、Python では宣言がないので、この方法でしか区別できなかったら残念です。 self.var を明示すればうまく解決できます。同様に、インスタンス変数を使うのにも self.var と書かなければならないので、メソッドの中の self が付いていない名前への参照は、そのインスタンスのディレクトリを検索するまでもなくローカル変数とわかります。別の言い方をすれば、ローカル変数とインスタンス変数は二つの異なる名前空間に存在し、Python にどちらの名前空間を使うかを伝えなくてはならないのです。

式中で代入ができないのはなぜですか？

Python 3.8 以降ならできるよ!

セイウチ演算子 := を使った代入式は、式の中で変数に代入します:

while chunk := fp.read(200):
   print(chunk)

より詳しくは PEP 572 [https://peps.python.org/pep-0572/] を参照してください。

Python にメソッドを使う機能 (list.index() 等) と関数を使う機能 (len(list) 等) があるのはなぜですか？

Guidoいわく：

(a) 幾つかの演算では、接頭辞は接尾辞よりも単純に読みやすいからです。接頭辞（そして接中辞！）による演算は数学において長い歴史があり、そこでは課題に対する数学者の思考を視覚的に助けるような記法が好まれます。x*(a+b)をx*a + x*bに書き換える容易さと、それと同じことを純粋なオブジェクト指向の記法で行う煩わしさを比較してみてください。

(b) len(x)というコードを読んだ時、私はそれが何かの長さを問うているのだなと知ることができます。これは私に2つの事を知らせています。一つは結果が整数であること、そして引数は何らかのコンテナであることです。対して、x.len()を目にした場合、私はその時点でxが何らかのコンテナであり、それが標準のlen()を持っているクラスを継承しているか、インターフェースを実装していることを知っている必要があります。mappingを実装していないクラスがget()やkeys()メソッドを持っていたり、fileでない何かがwrite()メソッドを持っているような混乱は時折見かけます。

—https://mail.python.org/pipermail/python-3000/2006-November/004643.html

join() がリストやタプルのメソッドではなく文字列のメソッドなのはなぜですか？

文字列は Python 1.6 から他の標準型に大きく近づきました。それ以前は常に string モジュールの関数を使ってできていたことと同等の機能を持つメソッドがこの時に追加されました。その新しいメソッドの多くは広く受け入れられましたが、一部のプログラマに不快を感じさせていると思われるものがこれで:

", ".join(['1', '2', '4', '8', '16'])

結果はこうなります:

"1, 2, 4, 8, 16"

この使い方には二つの議論があります。

一つ目は、「文字列リテラル (文字列定数) のメソッドを使うのは醜すぎる」というようなものです。確かにそうかも知れませんが、文字列リテラルは単なる固定された値に過ぎないというのが答えです。文字列に束縛された名前にメソッドが許されるなら、リテラルに使えないようにする論理的な理由はないでしょう。

二つ目の反対理由は、典型的には「私は実際、要素を文字列定数とともに結合させるよう、シーケンスに命じているのだ」というものです。残念ながら、そうではないのです。いくつかの理由から split() を文字列のメソッドとしておいた方がはるかに簡単です。これを見ると分かりやすいでしょう

"1, 2, 4, 8, 16".split(", ")

これは文字列リテラルに対する、与えられたセパレータ (または、デフォルトでは任意の空白文字の連続) で区切られた部分文字列を返せという指示です。

join() は、セパレータ文字列に、文字列のシーケンスをイテレートして隣り合う要素の間に自身を挿入するように指示しているので、文字列のメソッドです。このメソッドは、独自に定義された新しいクラスを含め、シーケンスの規則を満たすいかなる引数にも使えます。バイト列やバイト配列にも同様のメソッドがあります。

例外はどれくらい速いのですか？

try/except ブロックは例外が送出されなければ極端に効率的です。実際に例外を捕捉するのは高価です。Python 2.0 より前のバージョンでは、このイディオムを使うのが一般的でした:

try:
    value = mydict[key]
except KeyError:
    mydict[key] = getvalue(key)
    value = mydict[key]

これは、辞書がほとんどの場合にキーを持っていると予想できるときにのみ意味をなします。そうでなければ、このように書きます:

if key in mydict:
    value = mydict[key]
else:
    value = mydict[key] = getvalue(key)

この特殊な場合では value = dict.setdefault(key, getvalue(key)) も使えますが、これは getvalue() 呼び出しが十分安価な場合に限ります。なぜならそれが全ての場合に評価されるからです。

Python に switch や case 文がないのはなぜですか？

一般的に、構造化された switch 文は、式が特定の値または値の集合を持つとき、１つのコードブロックを実行します。 Python 3.10 以降では、リテラル値や名前空間内の定数を、 match ... case 文で簡単にマッチさせることができます。より古い手段は一連の if... elif... elif... else です。

非常に大きな数の選択肢から選ぶとき、値を呼び出す関数に対応づける辞書を作れます。例えば:

functions = {'a': function_1,
             'b': function_2,
             'c': self.method_1}

func = functions[value]
func()

オブジェクトのメソッドを呼び出すには、さらに単純に getattr() 組み込み関数で特定の名前のメソッドを検索できます:

class MyVisitor:
    def visit_a(self):
        ...

    def dispatch(self, value):
        method_name = 'visit_' + str(value)
        method = getattr(self, method_name)
        method()

メソッドの名前にこの例の visit_ のような接頭辞を使うことを勧めます。このような接頭辞がないと、信頼できないソースから値が与えられたときに、オブジェクトの任意のメソッドを呼び出す攻撃をされる可能性があります。

C の switch-case-default のような、フォールスルーのある switch を模倣することもできますが、はるかに難しいうえに必要性も少ないでしょう。

OS 特有のスレッド実装に依らずにインタプリタでスレッドをエミュレートすることはできないのですか？

答 1: 残念なことに、インタプリタは Python のスタックフレームごとに少なくとも一つの C のスタックフレームを push します。同様に、拡張もほとんどランダムなときに Python にコールバックすることがあります。よって、完全なスレッド実装には C のスレッドサポートが必要です。

答 2: 幸運なことに、Stackless Python [https://github.com/stackless-dev/stackless/wiki] があります。これは完全に再デザインされたインタープリタで、Cのスタックを回避しています。

なぜラムダ式は文を含むことができないのですか?

Python のラムダ式が文を含むことができないのは、Python の文法的な枠組みが式の中にネストされた文を扱うことができないからです。しかし、Python では、これは深刻な問題ではありません。他の言語のラムダに機能が追加されているのと違い、Python のラムダは単なる、関数を定義するのが面倒すぎる場合のための簡略な記法に過ぎないのです。

関数は既に Python の第一級オブジェクトで、ローカルスコープ内で宣言できます。従って、ローカルで定義された関数ではなくラムダを使う利点は、関数の名前を考える必要が無いことだけです -- しかし、(ラムダ式が生み出すオブジェクトと厳密に同じ型の) 関数オブジェクトが代入される先はただのローカル変数です！

Python は C やその他の言語のように機械語にコンパイルできますか？

Cython [https://cython.org/] は オプションのアノテーション付きのPythonの修正版を C拡張へ変換します。Nuitka [https://www.nuitka.net/] はPythonをC++コードへ変換する将来有望なPythonコンパイラで、完全なPython言語をサポートすることを目的としています。

Python はメモリをどのように管理するのですか？

Python のメモリ管理の詳細は実装に依ります。Python の標準の C 実装 CPython は参照カウントを使って、アクセスできないオブジェクトを探します。また別のメカニズムを使って参照サイクルを集めます。これはサイクル検出アルゴリズムを定期的に実行し、アクセスできないサイクルを探し、巻き込まれたオブジェクトを削除します。 gc モジュールの関数で、ガベージコレクションを実行し、デバッグ統計を取得し、コレクタのパラメタを変更できます。

ただし、他の実装 (例えば Jython [https://www.jython.org] や PyPy [https://www.pypy.org]) は本格的 (full-blown) なガベージコレクタのような別のメカニズムに依存するかもしれません。あなたの Python コードが参照カウントの実装の振る舞いに依存する場合、この違いが微妙な移植上の問題を引き起こすでしょう。

Python の実装によっては、以下の (CPython では通る) コードはおそらく、ファイルディスクリプタを使い果たすでしょう:

for file in very_long_list_of_files:
    f = open(file)
    c = f.read(1)

実際、CPython の参照カウントとデストラクタのスキームを使えば f への新しい代入ごとにファイルは閉じられます。しかし、伝統的な GC を使うと、これらのファイルオブジェクトが回収され (て閉じられる) までに不定な、場合によっては長い、間隔が空くことがあります。

Python の実装に依らずに動くコードを書くには、ファイルを明示的に閉じるか、 with 文を使ってください。これでメモリ管理のスキームに関係なく動きます:

for file in very_long_list_of_files:
    with open(file) as f:
        c = f.read(1)

CPython はなぜ伝統的なガベージコレクションスキームを使わないのですか？

まず、それは C の標準的な機能ではないのでポータブルではありません。(確かに Boehm GC ライブラリはあります。しかし、これにはアセンブリコードが含まれ、ほとんどの 有名なプラットフォームに対応していますが全てではありません。また、ほとんど透過的ですが、完全に透過的ではありません。Python を対応させるにはパッチが必要です。)

伝統的な GC は Python が他のアプリケーションに組み込まれるときにも問題となります。スタンドアロンの Python で動く限りでは、標準の malloc() と free() を GC ライブラリから提供されるものに置き換えても問題ありませんが、Python を実装したアプリケーションは Python のものではない 独自の 代替品を使おうとするかもしれません。現在のようにすることで、CPython は malloc() と free() が適切に実装されている限りどんなものにも対応させられます。

なぜ CPython の終了時にすべてのメモリが解放されるわけではないのですか？

Python モジュールのグローバルな名前空間から参照されるオブジェクトは、Python の終了時にメモリの割り当てを解除されるとは限りません。これは、循環参照があるときに起こりえます。解放できない C ライブラリ (例えば、Purify のようなツールなどが当てはまります) によって割り当てられたいくらかのメモリも含まれます。しかし、Python は終了時にメモリをクリーンアップすることには積極的で、全ての単一のオブジェクトを破棄しようとします。

再割り当て時に Python が特定のものを削除するように強制したいときは、 atexit モジュールを使って削除を強制する関数を実行してください。

なぜタプルとリストという別のデータ型が用意されているのですか？

リストとタプルは、多くの点で似ていますが、一般には本質的に異なる方法で使われます。タプルは、Pascal の レコード や C の　構造体 と同様なものと考えられます。型が異なっても良い関連するデータの小さな集合で、グループとして演算されます。例えば、デカルト座標は 2 つや 3 つの数のタプルとして適切に表せます。

一方、リストは、もっと他の言語の配列に近いものです。全て同じ型の可変数のオブジェクトを持ち、それらが一つ一つ演算される傾向にあります。例えば、 os.listdir('.') はカレントディレクトリ内にあるファイルの文字列表現のリストを返します。この出力を演算する関数は一般に、ディレクトリに一つや二つの別のファイルを加えても壊れません。

タプルはイミュータブルなので、一度タプルが生成されたら、そのどの要素も新しい値に置き換えられません。リストはミュータブルなので、リストの要素はいつでも変更できます。イミュータブルな要素だけが辞書のキーとして使えるので、リストではなくタプルだけがキーとして使えます。

CPythonでリストはどのように実装されているのですか？

CPythonのリストは実際に変数分の長さの配列で、Lispスタイルの連結リストではありません。この実装は他のオブジェクトへの参照の連続した配列を使用していて、この配列へのポインタおよび配列長はリストの先頭の構造体に保存されています。

これにより、リストのインデクシング a[i] は、リストの大きさやインデクスの値に依存しないコストで演算できます。

要素が追加または挿入されるとき、この参照の配列は大きさが変更されます。要素追加の繰り返しのパフォーマンスを上げるために、少し工夫されています。配列が大きくなるとき、次の何回かは実際に大きさを変更する必要がないように、いくらかの追加の領域が割り当てられます。

CPythonで辞書はどのように実装されていますか？

CPython の辞書は大きさを変更できるハッシュテーブルとして実装されています。B 木と比べて、ほとんどの条件下で (特に一般的な演算である) 探索のパフォーマンスが良いですし、実装も単純です。

辞書は、辞書に保存されているそれぞれのキーに対応するハッシュコードを hash() ビルトイン関数で計算することで機能します。このハッシュコードはキーやプロセスごとのシードによって大きく変化します。例えば、 'Python' のハッシュ値は -539294296 ですが、ビットが一つ違うだけの文字列 'python' のハッシュ値は 1142331976 です。そしてこのハッシュコードは、値が保存される内部配列での位置を計算するために使われます。保存しているキーのハッシュ値が全て異なるとすれば、一定の時間 − Big-O 記法では O(1) − でキーを検索できることになります。

なぜ辞書のキーはイミュータブルでなくてはならないのですか？

辞書のハッシュテーブルの実装は、キーを見つけるために、キー値から計算されたハッシュ値を使います。もしキーがミュータブルなオブジェクトだったら、その値は変えられ、それによりハッシュ値も変わってしまいます。しかし、キーオブジェクトを変更したのが何者であれ、値が辞書のキーとして使われていたと気付けないので、辞書の中のエントリを適切な場所に動かせません。そして、同じオブジェクトを探そうとしても、ハッシュ値が違うため見つかりません。古い値を探そうとしても、そのハッシュバイナリから見つかるオブジェクトの値は異なるでしょうから、これも見つかりません。

リストでインデクシングされた辞書が必要なら、まず単純にリストをタプルに変換してください。関数 tuple(L) は、リスト L と同じエントリのタプルを生成します。タプルはイミュータブルなので、辞書のキーとして使えます。

いくつかの受け入れられなかった提案:

アドレス (オブジェクト ID) のハッシュリスト。これは、同じ値の新しいリストを作っても見つからないので駄目です。例えば:

mydict = {[1, 2]: '12'}
print(mydict[[1, 2]])

[1, 2] の2行目のidは1行目のそれと異なってしまうために KeyError 例外を送出するでしょう。言い換えれば、辞書のキーは == を使って比較されるべきであり、 is ではないということです。

リストをキーとして使うときにコピーを作る。リストはミュータブルなので、自分自身への参照を含むことができ、コードをコピーするときに無限ループにハマる可能性があるので、これは駄目です。

リストをキーとして使うことを認めるが、ユーザにそれを変更させないように伝える。もしユーザが忘れたり、偶然にリストが変更されてしまったりしたら、追跡困難なバグの可能性を生じてしまいます。またこれは、 d.keys() のすべての値は辞書のキーとして使えるという、辞書の重要な不変性も潰してしまいます。

リストが一旦辞書のキーとして使われたら、読み出し専用のマークを付ける。問題は、値を変えられるのはトップレベルオブジェクトだけではないことです。リストを含むタプルもキーとして使えます。全てを辞書のキーとして導入すると、そこから到達可能な全てのオブジェクトに読み出し専用のマークを付ける必要があります -- そして再び、自己参照オブジェクトが無限ループを引き起こします。

必要ならばこれを回避する方法がありますが、自己責任のもとで行ってください。ミュータブルな構造を、 __eq__() と __hash__() メソッドの両方を持つクラスインスタンスに含めることができます。その時、辞書 (またはハッシュに基づく別の構造体) に属するような全てのラッパーオブジェクトのハッシュ値が、そのオブジェクトが辞書 (その他の構造体) 中にある間固定され続けることを確実にしてください。

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

なお、リストのメンバーの中にハッシュ化できないものがある可能性や、算術オーバーフローの可能性から、ハッシュ計算は複雑になります。

さらに、そのオブジェクトが辞書に含まれるか否かにかかわらず、 o1 == o2 (すなわち o1.__eq__(o2) is True) ならばいつでも hash(o1) == hash(o2) (すなわち o1.__hash__() == o2.__hash__()) でなくてはなりません。その制限に適合できなければ、辞書やその他のハッシュに基づく構造体は間違いを起こします。

この ListWrapper の例では、異常を避けるため、ラッパオブジェクトが辞書内にある限りラップされたリストが変更されてはなりません。この条件と満たせなかった時の結果について知恵を絞る覚悟がない限り、これをしてはいけません。よく考えてください。

なぜ list.sort() はソートされたリストを返さないのですか？

パフォーマンスが問題となる状況では、ソートするためだけにリストのコピーを作るのは無駄が多いです。そこで、 list.sort() はインプレースにリストをソートします。このことを忘れないため、この関数はソートされたリストを返しません。こうすることで、ソートされたコピーが必要で、ソートされていないものも残しておきたいときに、うっかり上書きしてしまうようなことがなくなります。

新しいリストを返したいなら、代わりに組み込みの sorted() 関数を使ってください。この関数は、与えられたイテレート可能オブジェクトから新しいリストを生成し、ソートして返します。例えば、辞書のキーをソートされた順序でイテレートする方法は:

for key in sorted(mydict):
    ...  # do whatever with mydict[key]...

Python ではどのようにインターフェース仕様を特定し適用するのですか？

C++ や Java のような言語が提供するような、モジュールに対するインターフェース仕様の特定は、モジュールのメソッドや関数の原型を表現します。インターフェースの特定がコンパイル時に適用されることが、大きなプログラムの構成に役立つと、広く感じられています。

Python 2.6 で、抽象基底クラス (Abstract Base Class, ABC) が定義できるようになる abc モジュールが追加されました。なので isinstance() と issubclass() を使って、インスタンスやクラスが、ある ABC を実装しているかどうかチェックできます。collections.abc モジュールでは、 Iterable 、 Container 、 MutableMapping などの便利な ABC が定義されています。

Pythonでは、インターフェース仕様の多くの利点は、コンポーネントへの適切なテスト規律により得られます。

モジュールのための適切なテストスイートは、回帰テストを提供し、モジュールのインターフェース仕様や用例集としても役立ちます。多くの Python モジュールは、簡単な「自己テスト」を提供するスクリプトとして実行できます。複雑な外部インターフェースを使うモジュールさえ、外部インターフェースの細かい「スタブ」エミュレーションで単独にテストできることが多いです。 doctest や unittest モジュール、あるいはサードパーティのテストフレームワークで、モジュールのコードの全ての行に及ぶ徹底的なテストスイートを構成できます。

Python で大きくて複雑なアプリケーションを構築するとき、インターフェース仕様と同様に、適切なテスト規律も役立ちます。実際には、インターフェース仕様ではテストできないプログラムの属性もあるので、それ以上にもなりえます。例えば、 list.append() メソッドは新しい要素をある内部リストの終わりに加えます。インターフェース仕様ではこの list.append() の実装が実際にこれを行うかをテストできませんが、テストスイートならこの機能を簡単に確かめられます。

テストスイートを書くことはとても有用ですし、簡単にテストできるコード設計を心がけると良いでしょう。人気を博している開発手法の一つ、テスト駆動開発は、実際のコードを記述するよりも先に、まずテストスイートの部分を記述するよう求めています。ご心配なく、Python は、あなたがいい加減でもテストケースを全く書かなくても構いません。

なぜ goto が無いのですか？

1970年代、人々は気付きました。秩序なき goto は、理解するのも手直しするのも困難という厄介な"スパゲッティ"コードに陥りがちであると。高水準言語では、分岐とループの手段があれば goto は不要です。 (Pythonだと、分岐には if 文及び or ・ and ・ if/else 式を使います。ループには while 文と for 文を使い、 ループ内に continue ・ break を含むことがあります)

関数の呼び出しをまたいでも動作する "構造化された goto" をまかなうものとして例外を使えます。C、Fortran、その他の言語での go あるいは goto 構造の適切な用途は全て、例外で同じようなことをすれば便利であると、広く感じられています。例えば:

class label(Exception): pass  # declare a label

try:
    ...
    if condition: raise label()  # goto label
    ...
except label:  # where to goto
    pass
...

例外ではループ内へ跳ぶことはできませんが、どちらにしてもそれは goto の乱用と見なされるものです。使うのは控えてください。

なぜ raw 文字列 (r-strings) はバックスラッシュで終わってはいけないのですか？

正確には、奇数個のバックスラッシュで終わってはいけません。終わりの対になっていないバックスラッシュは、閉じ引用文字をエスケープし、終っていない文字列を残してしまいます。

raw 文字列は、独自にバックスラッシュの処理をしようとするプロセッサ (主に正規表現エンジン) への入力を生成しやすいように設計されたものです。このようなプロセッサは、終端の対になっていないバックスラッシュを結局エラーとみなすので、raw 文字列はそれを認めません。その代わりに、バックスラッシュでエスケープすることで、引用文字を文字列として渡すことができます。r-string が意図された目的に使われるときに、この規則が役に立つのです。

Windows のパス名を構築するときには、Windows のシステムコールは普通のスラッシュも受け付けることを憶えておいてください:

f = open("/mydir/file.txt")  # works fine!

DOS コマンドのパス名を構築するときには、例えばこの中のどれかを試してください:

dir = r"\this\is\my\dos\dir" "\\"
dir = r"\this\is\my\dos\dir\ "[:-1]
dir = "\\this\\is\\my\\dos\\dir\\"

属性の代入に "with" 文が使えないのはなぜですか？

Python には、ブロックの実行を包む with 文があり、ブロックに入るときとブロックから出るときに、コードを呼び出します。以下のような構造を持つ言語があります:

with obj:
    a = 1               # equivalent to obj.a = 1
    total = total + 1   # obj.total = obj.total + 1

Python では、このような構造は曖昧になるでしょう。

Object Pascal、Delphi、C++のような他の言語では、静的な型を使うので、曖昧な方法でも、どのメンバに代入されているのか分かります。これが静的型付けの要点です -- コンパイラは いつでも コンパイル時にすべての変数のスコープを知るのです。

Python は動的な型を使います。実行時にどの属性が参照されるか事前に分かりません。動作中にメンバ属性が追加あるいは除去されるかもしれません。これでは、単純に読むだけではどのアトリビュートが参照されているか分かりません。ローカルなのか、グローバルなのか、メンバ属性なのか？

例えば、以下の不完全なコード片を考えましょう:

def foo(a):
    with a:
        print(x)

このコード片では、a は x. というメンバ属性を持っていると仮定されています。しかし、Python ではインタプリタにはこの仮定を伝えられる仕組みはありません。 a が、例えば整数だったら、どうなってしまうでしょうか。 x という名前のグローバル変数があったら、それが with ブロックの中で使われるのでしょうか。この通り、Python の動的な特質から、このような選択はとても難しい物になっています。

しかし、with やそれに類する言語の機能の一番の利点 (コード量の削減) は、 Python では代入により簡単に手に入れられます:

function(args).mydict[index][index].a = 21
function(args).mydict[index][index].b = 42
function(args).mydict[index][index].c = 63

こう書いてください:

ref = function(args).mydict[index][index]
ref.a = 21
ref.b = 42
ref.c = 63

Python では実行時に名前束縛が解決され、後者はその解決が一度で済むため、これには実行速度をあげる副作用もあります。

似た提案として、「先頭のドット」を使うなどして さらにコード量を減らす構文は、明白さを優先をして却下されました (https://mail.python.org/pipermail/python-ideas/2016-May/040070.html 参照)。

なぜジェネレータは with 文をサポートしないのですか？

技術的な理由で、ジェネレータは直接コンテキストマネージャとして使ってもうまく動きません。最も一般的なように、ジェネレータが最後まで回りきるイテレータとして使われる場合、クローズ処理は不要です。必要な場合は、 with 文で contextlib.closing(generator) のようにラップします。

if/while/def/class 文にコロンが必要なのはなぜですか？

主に可読性を高めるため (実験的な ABC 言語の結果の一つ) に、コロンが必要です:

if a == b
    print(a)

と:

if a == b:
    print(a)

を考えれば、後者のほうが少し読みやすいでしょう。さらに言えば、この FAQ の解答例は次のようになるでしょう。これは、英語の標準的な用法です。

他の小さな理由は、コロンによってエディタがシンタックスハイライトをしやすくなることです。プログラムテキストの手の込んだ解析をしなくても、コロンを探せばいつインデントを増やすべきかを決められます。

なぜ Python ではリストやタプルの最後にカンマがあっても良いのですか？

Python では、リスト、タプル、辞書の最後の要素の後端にカンマをつけても良いことになっています:

[1, 2, 3,]
('a', 'b', 'c',)
d = {
    "A": [1, 5],
    "B": [6, 7],  # last trailing comma is optional but good style
}

これを許すのには、いくつかの理由があります。

リストやタプルや辞書のリテラルが複数行に渡っているときに、前の行にカンマを追加するのを覚えておく必要が無いため、要素を追加するのが楽になります。また、文法エラーを起こすこと無く、行の並べ替えを行うことができます。

間違えてカンマを落としてしまうと、診断しづらいエラーにつながります。例えば:

x = [
  "fee",
  "fie"
  "foo",
  "fum"
]

このリストには4つの要素があるように見えますが、実際には3つしかありません。 "fee"、"fiefoo"、"fum" です。常にカンマを付けるようにすれば、この種のエラーが避けられます。

後端にカンマをつけても良いことにすれば、プログラムによるコード生成も簡単になります。

ライブラリと拡張 FAQ

目次

ライブラリと拡張 FAQ

ライブラリ一般の質問

作業 X を行うためのモジュールやアプリケーションを探すにはどうしますか？

math.py (socket.py, regex.py, etc.) のソースファイルはどこにありますか？

Python のスクリプトを Unix で実行可能にするにはどうしますか？

Python には curses/termcap パッケージはありますか？

Python には C の onexit() に相当するものはありますか？

シグナルハンドラが動かないのですがなぜですか？

よくある作業

Python のプログラムやコンポーネントをテストするにはどうしますか？

Python のドキュメント文字列からドキュメントを生成するにはどうしますか？

一度に一つの押鍵を取得するにはどうしますか？

スレッド

スレッドを使ったプログラムを書くにはどうしますか？

スレッドが一つも実行されていないようです。なぜですか？

たくさんのワーカースレッドに作業を割り振るにはどうしますか？

グローバルな値のどんな種類の変更がスレッドセーフになるのですか？

グローバルインタプリタロック (Global Interpreter Lock) を取り除くことはできないのですか？

入力と出力

ファイルを削除するにはどうしますか？ (その他、ファイルに関する質問...)

ファイルをコピーするにはどうしますか？

バイナリデータを読み書きするにはどうしますか？

os.popen() によって作られたパイプで os.read() が使われていないようです。なぜですか？

シリアル (RS232) ポートにアクセスするにはどうしますか？

sys.stdout (stdin, stderr) を閉じようとしても実際に閉じられないのはなぜですか？

ネットワーク/インターネットプログラミング

Python の WWW ツールには何がありますか？

How can I mimic CGI form submission (METHOD=POST)?

どのモジュールが HTML の生成の役に立ちますか？

Python のスクリプトからメールを送るにはどうしますか？

ソケットの connect() メソッドでブロッキングされなくするにはどうしますか？

データベース

Python にはデータベースパッケージへのインターフェースはありますか？

Python で永続的なオブジェクトを実装するにはどうしますか？

数学と数

Python で乱数を生成するにはどうしますか？

ライブラリ一般の質問

作業 X を行うためのモジュールやアプリケーションを探すにはどうしますか？

ライブラリリファンレス から関係がありそうな標準ライブラリモジュールがあるかどうか調べてください。 (標準ライブラリに何があるかが分かるようになると、この段階をスキップすることができます。)

サードパーティのパッケージについては、Python Package Index [https://pypi.org] を探したり、Google [https://www.google.com] その他の web サーチエンジンを試してください。"Python" に加えて一つか二つのキーワードで興味のある話題を検索すれば、たいてい役に立つものが見つかるでしょう。

math.py (socket.py, regex.py, etc.) のソースファイルはどこにありますか？

モジュールのソースファイルが見付けられない場合は、それは C 、 C++ かもしくは別のコンパイル言語で実装された、ビルトインもしくは動的に読み込まれるモジュールかもしれません。この場合、ソースは手に入らないかもしれませんし、 mathmodule.c のようなものが (Python の読み込みパスに無い) C ソースディレクトリのどこかにあるかもしれません。

Python のモジュールには、(少なくとも) 3 種類あります:

Python で書かれたモジュール (.py)。

C で書かれ、動的にロードされるモジュール (.dll, .pyd, .so, .sl, etc)。

C で書かれ、インタプリタにリンクされているモジュール。このリストを得るには、こうタイプしてください:

import sys
print(sys.builtin_module_names)

Python のスクリプトを Unix で実行可能にするにはどうしますか？

二つの条件があります :スクリプトファイルのモードが実行可能で、最初の行が #! で始まり Python インタプリタのパスが続いていなければなりません。

前者は、chmod +x scriptfile 、場合によっては chmod 755 scriptfile を実行すればできます。

後者は、いくつかの方法でできます。最も直接的な方法はこのように

#!/usr/local/bin/python

のようにファイルの一番最初の行に、プラットフォーム上の Python がインストールされているパス名を書くことです。

スクリプトを Python インタプリタの場所に依存させたくない場合は、 env プログラムが使えます。 Python インタプリタがユーザの PATH のディレクトリにあることを前提とすれば、ほとんど全ての Unix 系 OS では次の書き方をサポートしています:

#!/usr/bin/env python

CGI スクリプトでこれをやっては いけません 。 CGI スクリプトの PATH 変数はたいてい最小限のものになっているので、実際のインタプリタの絶対パスを使う必要があります。

ときおり、ユーザ環境に余裕が無く /usr/bin/env プログラムが失敗することがあります; もしくは、 env プログラム自体が無いことがあります。そのような場合は、次の (Alex Rezinsky による) ハックが試せます:

#! /bin/sh
""":"
exec python $0 ${1+"$@"}
"""

これには、スクリプトの __doc__ 文字列を定義するというちょっとした欠点があります。しかし、これを付け足せば直せます:

__doc__ = """...Whatever..."""

Python には curses/termcap パッケージはありますか？

Unix 系 OS において: 標準の Python ソースディストリビューションには Modules [https://github.com/python/cpython/tree/3.12/Modules] サブディレクトリに curses モジュールが付いてきますが、デフォルトではコンパイルされていません。 (これは Windows 用ディストリビューションでは利用できないことに注意してください -- Windows には curses モジュールはありません。)

curses モジュールは基本的な curses の機能や、色付きの表示、別の文字集合サポート、パッド、マウスサポートなどの ncurses や SYSV curses の多くの機能をサポートしています。このことは、モジュールが BSD curses だけしか持っていない OS とは互換性が無いことを意味しますが、現在メンテナンスされている OS でそういう類のものは無さそうです。

Python には C の onexit() に相当するものはありますか？

atexit モジュールは、 C の onexit() と同じような関数登録を提供します。

シグナルハンドラが動かないのですがなぜですか？

最もありがちな問題は、シグナルハンドラが間違った引数リストで宣言されていることです。これは次のように呼び出されます

handler(signum, frame)

だから、これは二つの仮引数で宣言されるべきです:

def handler(signum, frame):
    ...

よくある作業

Python のプログラムやコンポーネントをテストするにはどうしますか？

Python には二つのテストフレームワークがついています。doctest モジュールは、モジュールの docstring から使用例を見つけてそれらを実行し、出力を docstring によって与えられた望まれる出力と比較します。

unittest モジュールは、Java や Smalltalk のテストフレームワークを模した装飾されたテストフレームワークです。

テスト作業を簡単にするために、プログラムにおいてモジュール性の良い設計を使うべきです。プログラムでは、ほぼ全ての処理を関数やクラスのメソッドで包むべきです -- こうすることで、プログラムが速くなるという驚くような愉快な効果がときおり得られることがあります (というのも、ローカル変数へのアクセスはグローバルなアクセスよりも速いからです)。さらに言うと、テストを行うのがより難しくなってしまうため、プログラムは可変なグローバル変数に依存するのを避けるべきです。

プログラムの "global main logic" は

if __name__ == "__main__":
    main_logic()

のように main モジュールの最後に出来る限りシンプルなものを書くのが良いでしょう。

プログラムが整理され、関数やクラスの動作が追いやすい状態になったら、その動作を試すテスト関数を書くべきです。一連のテストを自動化するテストスイートは、それぞれのモジュールに関連付けることができます。これは手間が掛かりそうに思えますが、Python は簡素で融通が効くので、驚くほど簡単です。"製品コード (production code)" と並行でテスト関数を書くことで、バグや設計の不備でさえも早い段階で簡単に見付かるようになるので、コーディング作業をより心地良く楽しいものにできます。

プログラムのメインモジュールとして設計されたのではない "補助モジュール" には、モジュールの自己テストを含めるといいでしょう。

if __name__ == "__main__":
    self_test()

複雑な外部インターフェースと作用し合うプログラムでさえ、外部インターフェースが使えない時でも、Python で実装された "fake" インターフェースを使ってテストできます。

Python のドキュメント文字列からドキュメントを生成するにはどうしますか？

pydoc モジュールで Python ソースコード内のドキュメント文字列から HTML を生成できます。純粋に docstring から API ドキュメントを生成するには、他に epydoc [https://epydoc.sourceforge.net/] という選択肢もあります。 Sphinx [https://www.sphinx-doc.org] も docstring の内容を含めることができます。

一度に一つの押鍵を取得するにはどうしますか？

Unix 系 OS ではいくつか解決方法があります。curses を使うのが素直なやり方ですが、curses は学ぶには少し大き過ぎるモジュールです。

スレッド

スレッドを使ったプログラムを書くにはどうしますか？

_thread モジュールではなく、必ず threading モジュールを使ってください。 threading モジュールは、 _thread モジュールで提供される低レベルな基本要素の、便利な抽象化を構成します。

スレッドが一つも実行されていないようです。なぜですか？

メインスレッドが終了するとともに、全てのスレッドは終了されます。メインスレッドは速く働きすぎるので、スレッドには何をする時間も与えられません。

簡単な解決策は、プログラムの終わりに、スレッドが完了するのに十分な時間のスリープを加えることです:

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)  # <---------------------------!

しかし、実際は (ほとんどのプラットフォームでは) スレッドは並行して実行されるのではなく、一つづつ実行されるのです！なぜなら、OS のスレッドスケジューラは、前のスレッドがブロックされるまで新しいスレッドを開始しないからです。

簡単に直すには、関数の実行の最初にちょっとスリープを加えることです:

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)

time.sleep() の良い遅延時間を推測しようとするよりも、セマフォのような仕組みを使う方が良いでしょう。 1 つのアイディアは queue モジュールを使って、キューオブジェクトを作り、各スレッドが完了したときにキューにトークンを追加し、メインスレッドにスレッドと同じ数のトークンをキューから読み出させることです。

たくさんのワーカースレッドに作業を割り振るにはどうしますか？

最も簡単な方法は、新しい concurrent.futures モジュール、特に ThreadPoolExecutor クラスを使うことです。

もしくは、実行アルゴリズムを上手にコントロールしたい場合は、自身の手でロジックを書くこともできます。 queue モジュールを使って、ジョブのリストを含むキューを作ってください。 Queue クラスはオブジェクトのリストを保持し、キューに要素を追加する .put(obj) メソッド、それら要素を返す .get() メソッドを持っています。このクラスは、それぞれのジョブがきっちり 1 回だけ取り出されることを保証するのに必要なロック処理にも配慮します。

ここにちょっとした例があります:

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)

実行時には、以下のように出力されます:

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
...

より詳しいことはモジュールのドキュメントを調べてください; Queue クラスは多機能なインターフェースを提供しています。

グローバルな値のどんな種類の変更がスレッドセーフになるのですか？

global interpreter lock (GIL) が内部で使われ、Python VM で一度に一つだけのスレッドが実行されることが保証されています。一般に、Python ではスレッド間の切り替えをバイトコード命令の間でのみ行います。切り替えの周期は、 sys.setswitchinterval() で設定できます。したがって、それぞれのバイトコード命令、そしてそれぞれの命令が届く全ての C 実装コードは、 Python プログラムの観点からは、アトミックです。

このことから、理論上は、正確な勘定のためには PVM バイトコードの実装を理解することが必要です。実際上は、組み込みデータ型(整数、リスト、辞書、等)の、変数を共有する "アトミックそうな" 演算は、実際にアトミックです。

例えば、以下の演算は全てアトミックです (L、L1、L2 はリスト、 D、D1、D2 は辞書、x、y はオブジェクト、i、j は整数です):

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()

これらは、アトミックではありません:

i = i+1
L.append(L[-1])
L[i] = L[j]
D[x] = D[x] + 1

他のオブジェクトを置き換えるような演算は、そのオブジェクトの参照カウントがゼロになったときに __del__() メソッドを呼び出すことがあり、これが影響を及ぼすかもしれません。これは特に、辞書やリストの大規模な更新に当てはまります。疑わしければ、mutex を使ってください！

グローバルインタプリタロック (Global Interpreter Lock) を取り除くことはできないのですか？

マルチスレッド Python プログラムは事実上一つの CPU しか使えず、 (ほとんど) 全ての Python コードが グローバルインタプリタロック (GIL) が保持されている間しか作動しなくなるということで、GIL は、 Python をハイエンドなマルチプロセッササーバマシン上に配備する上で邪魔であると見なされがちです。

Back 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 recently did a similar experiment in his python-safethread [https://code.google.com/archive/p/python-safethread] project. Unfortunately, both 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.

This 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 ProcessPoolExecutor class in the new concurrent.futures module provides an easy way of doing so; the multiprocessing module provides a lower-level API in case you want more control over dispatching of tasks.

C 拡張をうまく使うことも役立ちます。C 拡張を時間のかかるタスクの実行に使えば、その拡張は実行が C コードで行われている間 GIL を解放でき、その間に他のスレッドで作業が進められます。 zlib や hashlib など、すでにこれを行なっている標準ライブラリモジュールもあります。

It has been suggested that the GIL should be a per-interpreter-state lock rather than truly global; interpreters then wouldn't be able to share objects. Unfortunately, this isn't likely to happen either. It would be a tremendous amount of work, because many object implementations currently have global state. For example, small integers and short strings are cached; these caches would have to be moved to the interpreter state. Other object types have their own free list; these free lists would have to be moved to the interpreter state. And so on.

And I doubt that it can even be done in finite time, because the same problem exists for 3rd party extensions. It is likely that 3rd party extensions are being written at a faster rate than you can convert them to store all their global state in the interpreter state.

And finally, once you have multiple interpreters not sharing any state, what have you gained over running each interpreter in a separate process?

入力と出力

ファイルを削除するにはどうしますか？ (その他、ファイルに関する質問...)

os.remove(filename) または os.unlink(filename) を使ってください。ドキュメントは、 os モジュールを参照してください。この二つの関数は同じものです。 unlink() は単に、この関数の Unix システムコールの名称です。

ディレクトリを削除するには、os.rmdir() を使ってください。作成には os.mkdir() を使ってください。os.makedirs(path) は path の中間のディレクトリの、存在しないものを作成します。os.removedirs(path) は中間のディレクトリが空である限り、それらを削除します。ディレクトリツリー全体とその中身全てを削除したいなら、shutil.rmtree() を使ってください。

ファイルの名前を変更するには、os.rename(old_path, new_path) を使ってください。

ファイルを切り詰めるには、 f = open(filename, "rb+") を使ってファイルを開き、 f.truncate(offset) を使ってください; offset はデフォルトでは現在のシーク位置です。 os.open() で開かれたファイル用の os.ftruncate(fd, offset) もあります。 fd はファイルディスクリプタ (小さい整数値) です。

shutil モジュールにも、copyfile()、 copytree()、rmtree() 等、ファイルに作用する関数がいくつか含まれます。

ファイルをコピーするにはどうしますか？

shutil モジュールに copyfile() 関数があります。注意点として、これは Windows NTFS ボリューム上の alternate data streams [https://en.wikipedia.org/wiki/NTFS#Alternate_data_stream_(ADS)] も macOS HFS+ 上の resource forks [https://en.wikipedia.org/wiki/Resource_fork] もコピーしません。ただし現在ではどちらも使われることは ほとんどありません。またファイルのパーミッションやメタデータもコピーされませんが、この代わりに shutil.copy2() を使うとそのほとんど (すべてではありませんが) が保持されます。

バイナリデータを読み書きするにはどうしますか？

複雑なバイナリデータ形式の読み書きには、struct モジュールを使うのが一番です。これでバイナリデータ (通常は数) を含む文字列を取って、 Python オブジェクトに変換することができますし、その逆もできます。

例えば、以下のコードはファイルから 2 バイトの整数 2 個と 4 バイトの整数 1 個をビッグエンディアンフォーマットで読み込みます:

import struct

with open(filename, "rb") as f:
    s = f.read(8)
    x, y, z = struct.unpack(">hhl", s)

フォーマット中の '>' はデータを強制的にビッグエンディアンにします。ファイルから、文字 'h' は一つの"整数"(2 バイト)を読み込み、文字 'l' は一つの"long 整数"を読み込みます。

より規則的なデータ (例えば、整数や浮動小数点数の中身の型が揃ったリスト) に対しては、 array モジュールを使うこともできます。

注釈

バイナリデータを読み書きするには、 (ここにあるように "rb" を open() に渡して) ファイルをバイナリモードで開く義務があります。代わりに (デフォルトの) "r" を使った場合は、ファイルはテキストモードで開かれ、 f.read() は bytes オブジェクトではなく str オブジェクトを返します。

os.popen() によって作られたパイプで os.read() が使われていないようです。なぜですか？

os.read() は、開かれたファイルを表す小さな整数、ファイルディスクリプタを引数に取る、低レベルの関数です。 os.popen() は、組み込みの open() 関数の返り値と同じ型の、高レベルなファイルオブジェクトを作成します。従って、 os.popen() によって作成されたパイプ p から n バイト分だけ読み取るには、 p.read(n) を使う必要があります。

シリアル (RS232) ポートにアクセスするにはどうしますか？

Win32、OSX、Linux、BSD、Jython、IronPython では:

pyserial [https://pypi.org/project/pyserial/]

Unix では、Mitch Chapman による Usenet の投稿を参照してください:

https://groups.google.com/groups?selm=34A04430.CF9@ohioee.com

sys.stdout (stdin, stderr) を閉じようとしても実際に閉じられないのはなぜですか？

Python の file object は、低水準の C ファイルディスクリプタ上の、抽象の高水準レイヤです。

組み込みの open() 関数によって生成されたほとんどのファイルオブジェクトでは、 f.close() は Python ファイルオブジェクトが Python の視点からは閉じられているものとする印をつけ、その下にある C ファイルディスクリプタを閉じるように手配します。これは、 f がガベージとなったときにも、 f のデストラクタで自動的に起こります。

しかし、stdin、stdout、stderr は C で特別な立場が与えられていることから、Python でも同様に特別に扱われます。sys.stdout.close() を実行すると、Python レベルのファイルオブジェクトには閉じられているものとする印がつけられますが、C ファイルディスクリプタは 閉じられません。

下にある C ファイルディスクリプタのうち、この三つのどれかを閉じるには、まず本当に閉じる必要があることを確かめるべきです (例えば、拡張モジュールの I/O を混乱させてしまうかもしれません)。本当に必要ならば、 os.close() を使ってください:

os.close(stdin.fileno())
os.close(stdout.fileno())
os.close(stderr.fileno())

または、数の定数としてそれぞれ 0, 1, 2 も使えます。

ネットワーク/インターネットプログラミング

Python の WWW ツールには何がありますか？

ライブラリリファレンスマニュアルの インターネットプロトコルとサポート と インターネット上のデータの操作 という章を参照してください。Python には、サーバサイドとクライアントサイドの web システムを構築するのに便利な多くのモジュールがあります。

利用可能なフレームワークの概要は Paul Boddie によって、 https://wiki.python.org/moin/WebProgramming でメンテナンスされています。

Cameron Laird maintains a useful set of pages about Python web technologies at https://web.archive.org/web/20210224183619/http://phaseit.net/claird/comp.lang.python/web_python.

How can I mimic CGI form submission (METHOD=POST)?

I would like to retrieve web pages that are the result of POSTing a form. Is there existing code that would let me do this easily?

Yes. Here's a simple example that uses urllib.request:

#!/usr/local/bin/python

import urllib.request

# build the query string
qs = "First=Josephine&MI=Q&Last=Public"

# connect and send the server a path
req = urllib.request.urlopen('http://www.some-server.out-there'
                             '/cgi-bin/some-cgi-script', data=qs)
with req:
    msg, hdrs = req.read(), req.info()

Note that in general for percent-encoded POST operations, query strings must be quoted using urllib.parse.urlencode(). For example, to send name=Guy Steele, Jr.:

>>> import urllib.parse
>>> urllib.parse.urlencode({'name': 'Guy Steele, Jr.'})
'name=Guy+Steele%2C+Jr.'

参考

urllib パッケージを使ってインターネット上のリソースを取得するには for extensive examples.

どのモジュールが HTML の生成の役に立ちますか？

Web Programming についての wiki のページ [https://wiki.python.org/moin/WebProgramming] から役に立つリンクが見付けられます。

Python のスクリプトからメールを送るにはどうしますか？

標準ライブラリモジュール smtplib を使ってください。

以下に示すのが、これを使ったごく単純な対話型のメール送信器です。このメソッドは SMTP リスナをサポートするホストならどこででも作動します。

import sys, smtplib

fromaddr = input("From: ")
toaddrs  = input("To: ").split(',')
print("Enter message, end with ^D:")
msg = ''
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()

Unix 限定の代わりの選択肢は sendmail を使うことです。sendmail プログラムの場所はシステムによって様々です; あるときは /usr/lib/sendmail だったり、あるときは /usr/sbin/sendmail だったり。sendmail のマニュアルページが助けになるでしょう。サンプルコードはこのようになります:

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)

ソケットの connect() メソッドでブロッキングされなくするにはどうしますか？

主に select モジュールがソケットの非同期の I/O を扱うのに使われます。

TCP 接続がブロッキングされないようにするために、ソケットをノンブロッキングモードに設定することが出来ます。そして connect() したときに、即座に接続できるか、エラー番号を .errno として含む例外を受け取るかのどちらかになります。errno.EINPROGRESS は、接続が進行中であるが、まだ完了していないということを示します。異なる OS では異なる値が返されるので、あなたのシステムで何が返されるかを確かめておく必要があります。

connect_ex() メソッドを使えば例外を生成しなくて済みます。これは単に errno の値を返すでしょう。ポーリングのためには、後でまた connect_ex() を呼び出すことができます -- 0 または errno.EISCONN は接続されたことを表します -- または、このソケットを select.select() に渡して書き込み可能か調べることができます。

注釈

asyncio モジュールは、ノンブロッキングのネットワークコードを書く作業のためにフレームワークのような方法を提供します。その他の選択肢として、Twisted [https://twisted.org/] は多機能で著名なサードパーティのライブラリです。

データベース

Python にはデータベースパッケージへのインターフェースはありますか？

はい。

標準の Python には、 DBM や GDBM などの、ディスクベースのハッシュへのインターフェースも含まれています。また、 sqlite3 モジュールは、軽量なディスクベースの関係データベースを提供します。

ほとんどの関係データベースがサポートされています。詳細は DatabaseProgramming wiki page [https://wiki.python.org/moin/DatabaseProgramming] を参照してください。

Python で永続的なオブジェクトを実装するにはどうしますか？

pickle ライブラリモジュールで、ごく一般的な方法でこれを解決できます (開かれたファイル、ソケット、ウィンドウのようなものを保管することはできませんが)。 shelve ライブラリモジュールは pickle と (g)dbm を使い、任意の Python オブジェクトを含む永続的なマッピングを生成します。

数学と数

Python で乱数を生成するにはどうしますか？

標準モジュールの random が乱数生成器を実装しています。使い方は単純です:

import random
random.random()

これは区間 [0, 1) 内のランダムな浮動小数点数を返します。

このモジュールにはその他多くの特化した生成器もあります。例えば:

randrange(a, b) は区間 [a, b) から整数を選びます。

uniform(a, b) は区間 [a, b) から浮動小数点数を選びます。

normalvariate(mean, sdev) は正規 (ガウス) 分布をサンプリングします。

シーケンスに直接作用する高水準な関数もあります。例えば:

choice(S) は与えられたシーケンスからランダムな要素を選びます。

shuffle(L) はリストをインプレースにシャッフルします。すなわち、ランダムに並び替えます。

Random クラスのインスタンスを生成して、複数の独立な乱数生成器をつくることもできます。

拡張と埋め込み FAQ

目次

拡張と埋め込み FAQ

C で独自の関数を作ることはできますか？

C++ で独自の関数を作ることはできますか？

C を書くのは大変です。他の方法はありませんか？

C から任意の Python 文を実行するにはどうしますか？

C から任意の Python 式を評価するにはどうしますか？

Python オブジェクトから C の値を取り出すにはどうしますか？

Py_BuildValue() で任意長のタプルを作るにはどうしますか？

C からオブジェクトのメソッドを呼び出すにはどうしますか？

PyErr_Print() (その他 stdout/stderr に印字するもの) からの出力を受け取るにはどうしますか？

C から Python で書かれたモジュールにアクセスするにはどうしますか？

Python から C++ へインターフェースするにはどうしますか？

セットアップファイルでモジュールを追加しようとしたらメイクに失敗しました。なぜですか？

拡張をデバッグするにはどうしますか？

Linux システムで Python モジュールをコンパイルしたいのですが、見つからないファイルがあります。なぜですか？

"不完全 (incomplete) な入力" を "不適切 (invalid) な入力" から区別するにはどうしますか？

未定義の g++ シンボル __builtin_new や __pure_virtual を見つけるにはどうしますか？

メソッドのいくつかは C で、その他は Python で実装されたオブジェクトクラスを (継承などで) 作ることはできますか？

C で独自の関数を作ることはできますか？

はい。関数、変数、例外、そして新しいタイプまで含んだビルトインモジュールを C で作れます。これはドキュメント Python インタプリタの拡張と埋め込み で説明されています。

ほとんどの中級から上級の Python 本もこの話題を扱っています。

C++ で独自の関数を作ることはできますか？

はい。C++ 内にある C 互換機能を使ってできます。 extern "C" { ... } で Python のインクルードファイルを囲み、 extern "C" を Python インタプリタから呼ぶ各関数の前に置いてください。グローバルや静的な C++ オブジェクトの構造体を持つものは良くないでしょう。

C を書くのは大変です。他の方法はありませんか？

独自の C 拡張を書くための別のやり方は、目的によっていくつかあります。

Cython [https://cython.org] とその親戚 Pyrex [https://www.csse.canterbury.ac.nz/greg.ewing/python/Pyrex/] は、わずかに変形した Python を受け取り、対応する C コードを生成します。Cython や Pyrex を使えば Python の C API を習得することなく拡張を書けます。

現時点で Python 拡張が存在しない C や C++ ライブラリへのインターフェースが必要な場合、SWIG [https://www.swig.org] のようなツールを使ってそのライブラリのデータ型や関数をラッピングできます。 SIP [https://github.com/Python-SIP/sip] 、CXX [https://cxx.sourceforge.net/] 、Boost [https://www.boost.org/libs/python/doc/index.html] 、Weave [https://github.com/scipy/weave] でも C++ ライブラリをラッピングできます。

C から任意の Python 文を実行するにはどうしますか？

これを行う最高水準の関数は PyRun_SimpleString() で、一つの文字列引数を取り、モジュール __main__ のコンテキストでそれを実行し、成功なら 0、例外 (SyntaxError を含む) が発生したら -1 を返します。更に制御したければ、 PyRun_String() を使ってください。ソースは Python/pythonrun.c の 'PyRun_SimpleString() を参照してください。

C から任意の Python 式を評価するにはどうしますか？

先の質問の PyRun_String() を、スタートシンボル Py_eval_input を渡して呼び出してください。これは式を解析し、評価してその値を返します。

Python オブジェクトから C の値を取り出すにはどうしますか？

オブジェクトの型に依ります。タプルなら、 PyTuple_Size() が長さを返し、 PyTuple_GetItem() が指定されたインデックスの要素を返します。リストにも同様の関数 PyList_Size() と PyList_GetItem() があります。

bytes では、 PyBytes_Size() がその長さを返し、 PyBytes_AsStringAndSize() がその値へのポインタと長さを提供します。 Python の bytes オブジェクトは null を含むこともできるので、 C の strlen() を使うべきではないことに注意してください。

オブジェクトの型を検査するには、まず最初にそれが NULL でないことを確かめた上で、 PyBytes_Check() 、 PyTuple_Check() 、 PyList_Check() などを使います。

いわゆる 'abstract' インターフェースから提供される、 Python オブジェクトに対する高レベル API もあります -- より詳しいことは Include/abstract.h を読んでください。これを使うと、数値型プロトコル (PyNumber_Index() など) や PyMapping API のマップ型プロトコルなどの役に立つプロトコルに加え、 PySequence_Length() や PySequence_GetItem() などの任意の種類の Python シーケンスへのインターフェースにアクセスできます。

Py_BuildValue() で任意長のタプルを作るにはどうしますか？

できません。代わりに PyTuple_Pack() を使ってください。

C からオブジェクトのメソッドを呼び出すにはどうしますか？

PyObject_CallMethod() 関数でオブジェクトの任意のメソッドを呼び出せます。パラメタは、オブジェクト、呼び出すメソッドの名前、 Py_BuildValue() で使われるようなフォーマット文字列、そして引数です:

PyObject *
PyObject_CallMethod(PyObject *object, const char *method_name,
                    const char *arg_format, ...);

これはメソッドを持ついかなるオブジェクトにも有効で、組み込みかユーザ定義かは関係ありません。返り値に対して Py_DECREF() する必要があることもあります。

例えば、あるファイルオブジェクトの "seek" メソッドを 10, 0 を引数として呼ぶとき (ファイルオブジェクトのポインタを "f" とします):

res = PyObject_CallMethod(f, "seek", "(ii)", 10, 0);
if (res == NULL) {
        ... an exception occurred ...
}
else {
        Py_DECREF(res);
}

なお、 PyObject_CallObject() の引数リストには 常に タプルが必要です。関数を引数なしで呼び出すには、フォーマットに "()" を渡し、関数を一つの引数で呼び出すには、関数を括弧でくくって例えば "(i)" としてください。

PyErr_Print() (その他 stdout/stderr に印字するもの) からの出力を受け取るにはどうしますか？

Python コード内で、 write() メソッドをサポートするオブジェクトを定義してください。そのオブジェクトを sys.stdout と sys.stderr に代入してください。print_error を呼び出すか、単に標準のトレースバック機構を作動させてください。そうすれば、出力は write() が送る任意の所に行きます。

最も簡単な方法は、 io.StringIO クラスを使うことです:

>>> import io, sys
>>> sys.stdout = io.StringIO()
>>> print('foo')
>>> print('hello world!')
>>> sys.stderr.write(sys.stdout.getvalue())
foo
hello world!

これと同じことをするカスタムオブジェクトは次のようになるでしょう:

>>> 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(''.join(sys.stdout.data))
foo
hello world!

C から Python で書かれたモジュールにアクセスするにはどうしますか？

以下のようにモジュールオブジェクトへのポインタを得られます:

module = PyImport_ImportModule("<modulename>");

そのモジュールがまだインポートされていない (つまり、まだ sys.modules に現れていない) なら、これはモジュールを初期化します。そうでなければ、単純に sys.modules["<modulename>"] の値を返します。なお、これはモジュールをいかなる名前空間にも代入しません。これはモジュールが初期化されて 'sys.modules に保管されていることを保証するだけです。

これで、モジュールの属性 (つまり、モジュールで定義された任意の名前) に以下のようにアクセスできるようになります:

attr = PyObject_GetAttrString(module, "<attrname>");

PyObject_SetAttrString() を呼んでモジュールの変数に代入することもできます。

Python から C++ へインターフェースするにはどうしますか？

やりたいことに応じて、いろいろな方法があります。手動でやるなら、 "拡張と埋め込み" ドキュメント を読むことから始めてください。なお、Python ランタイムシステムにとっては、 C と C++ はあまり変わりません。だから、C 構造体 (ポインタ)型に基づいて新しい Python の型を構築する方針は C++ オブジェクトに対しても有効です。

C++ ライブラリに関しては、 C を書くのは大変です。他の方法はありませんか？ を参照してください。

セットアップファイルでモジュールを追加しようとしたらメイクに失敗しました。なぜですか？

セットアップは改行で終わらなければならなくて、改行がないと、ビルド工程は失敗します。(これを直すには、ある種の醜いシェルスクリプトハックが必要ですが、このバグは小さいものですから努力に見合う価値はないでしょう。)

拡張をデバッグするにはどうしますか？

動的にロードされた拡張に GDB を使うとき、拡張がロードされるまでブレークポイントを設定してはいけません。

.gdbinit ファイルに(または対話的に)、このコマンドを加えてください:

br _PyImport_LoadDynamicModule

そして、GDB を起動するときに:

$ 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

Linux システムで Python モジュールをコンパイルしたいのですが、見つからないファイルがあります。なぜですか？

Python の多くのパッケージバージョンには、Python 拡張をコンパイルするのに必要な様々なファイルを含む /usr/lib/python2.x/config/ ディレクトリが含まれていません。

Red Hat では、Python RPM をインストールして必要なファイルを得てください。

Debian では、 apt-get install python-dev を実行してください。

"不完全 (incomplete) な入力" を "不適切 (invalid) な入力" から区別するにはどうしますか？

Python インタラクティブインタプリタでは、入力が不完全なとき (例えば、 "if" 文の始まりをタイプした時や、カッコや三重文字列引用符を閉じていない時など) には継続プロンプトを与えられますが、入力が不適切であるときには即座に構文エラーメッセージが与えられます。このようなふるまいを模倣したいことがあります。

Python では構文解析器のふるまいに十分に近い codeop モジュールが使えます。例えば IDLE がこれを使っています。

これを C で行う最も簡単な方法は、 PyRun_InteractiveLoop() を (おそらく別のスレッドで) 呼び出し、Python インタプリタにあなたの入力を扱わせることです。独自の入力関数を指定するのに PyOS_ReadlineFunctionPointer() を設定することもできます。詳しいヒントは、 Modules/readline.c や Parser/myreadline.c を参照してください。

未定義の g++ シンボル __builtin_new や __pure_virtual を見つけるにはどうしますか？

g++ モジュールを動的にロードするには、Python を再コンパイルし、それを g++ で再リンク (Python Modules Makefile 内の LINKCC を変更) し、拡張を g++ でリンク (例えば g++ -shared -o mymodule.so mymodule.o) しなければなりません。

メソッドのいくつかは C で、その他は Python で実装されたオブジェクトクラスを (継承などで) 作ることはできますか？

はい、 int 、 list 、 dict などのビルトインクラスから継承できます。

The Boost Python Library (BPL, https://www.boost.org/libs/python/doc/index.html) を使えば、これを C++ からできます。 (すなわち、BPL を使って C++ で書かれた拡張クラスを継承できます).

Windows 上の Python FAQ

目次

Windows 上の Python FAQ

Python プログラムを Windows で動かすにはどうしますか？

Python スクリプトを実行可能にするにはどうしますか？

Python の起動に時間がかかることがあるのはなぜですか？

どうすれば Python スクリプトを EXE に出来ますか?

*.pyd ファイルは DLL と同じですか？

Python を Windows アプリケーションに埋め込むにはどうしたらいいですか？

エディタが Python ソースにタブを勝手に挿入しないようにするにはどうしますか？

ブロックすることなく押鍵を検出するにはどうしますか？

missing api-ms-win-crt-runtime-l1-1-0.dll エラーを解決するにはどうしますか？

Python プログラムを Windows で動かすにはどうしますか？

これは必ずしも単純な質問ではありません。Windows コマンドラインからプログラムを実行するのに慣れてしまっている場合は、全て明らかなことに思えるでしょう; そうでない場合は、もう少し手引きが必要でしょう。

ある種の統合開発環境を使っているのでなければ、最終的には "コマンドプロンプト" などと呼ばれているものに、 Windows コマンドをタイプすることになるでしょう。通常そういうウィンドウは検索バーで cmd を検索して起動します。通常は次のような見た目の Windows の "コマンド プロンプト" が現れるので、ウィンドウが起動したのが分かるはずです:

C:\>

この文字は異なっていたり、続きがあったりするので、コンピュータの設定や、あなたが最近何をしたかに依って、このようになっていることもあるでしょう:

D:\YourName\Projects\Python>

このようなウィンドウさえ開けば、Python プログラムを動かす手順は順調に進みます。

Python スクリプトは Python インタプリタ と呼ばれる別のプログラムで処理されなければならないということを、理解する必要があります。インタプリタはスクリプトを読み込み、バイトコードにコンパイルし、バイトコードを実行しプログラムを走らせます。では、インタプリタが Python スクリプトを取り扱うためには、どんな用意をするのでしょうか?

まず最初に、コマンドウィンドウに "py" という単語がインタプリタを起動する指示であると認識させる必要があります。コマンドウィンドウを開いたら、 py というコマンドを入力し、リターンキーを叩いてください。:

C:\Users\YourName> py

次のような出力が見えるでしょう:

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.
>>>

インタプリタの"対話モード"が始まりました。これで Python の文や式を対話的に入力して、待っている間に実行や評価させることができます。これが Python の最強の機能のひとつです。いくつかの式を選んで入力し、結果を見て確かめてみましょう:

>>> print("Hello")
Hello
>>> "Hello" * 3
'HelloHelloHello'

多くの人が対話モードを便利で高度なプログラム可能計算機として使っています。対話式 Python セッションを終わらせたいなら、 exit() 関数を呼び出すか、 Ctrl キーを押しながら Z を入力し "Enter" キーを押して、 Windows コマンドプロンプトに戻ってください。

スタート ‣ すべてのプログラム ‣ Python 3.x ‣ Python (command line) のような項目がスタートメニューに見付かるかもしれません。これを起動すると、新しいウィンドウに >>> というプロンプトが見られるでしょう。その場合、 exit() 関数を呼び出すか Ctrl-Z を入力するとウィンドウは閉じます; Windows は 1 つの "python" コマンドをウィンドウで実行していて、インタプリタを終了させたときに、そのウィンドウを閉じます。

py コマンドが認識されていることが確認できたので、 Python スクリプトを与えられるようになりました。そのためには Python スクリプトの絶対パスあるいは相対パスを与える必要があります。 Python スクリプトがデスクトップにあり、 hellp.py という名前で、ちょうど良いことにコマンドプロンプトがホームディレクトリを開いていると仮定しましょう。そうすると次のような表示が見られます:

C:\Users\YourName>

ここまで来れば py の後ろにスクリプトのパスを入力することで、 Python にスクリプトを渡すよう py コマンドに命令できます:

C:\Users\YourName> py Desktop\hello.py
hello

Python スクリプトを実行可能にするにはどうしますか？

Windows では、標準の Python インストーラはすでに .py 拡張子をあるファイル型 (Python.File) に関連付け、そのファイル型にインタプリタを実行するオープンコマンド (D:\Program Files\Python\python.exe "%1" %*) を与えます。コマンドプロンプトから 'foo.py' としてスクリプトを実行可能にするにはこれで十分です。スクリプトを拡張子なしで 'foo' とだけタイプして実行したいのなら、PATHEXT 環境変数に .py を加えてください。

Python の起動に時間がかかることがあるのはなぜですか？

通常 Python は Windows でとても早く起動しますが、ときどき Python が急にスタートアップに時間がかかるようになったというバグレポートがあります。更に複雑なことに、Python は同様に設定された他の Windows システムではきちんと動くのです。

この問題はそのマシンのウイルス対策ソフトウェアの設定ミスによって起こされることがあります。ウイルススキャナの中には、ファイルシステムからの全ての読み込みを監視するように設定した場合に、二桁のスタートアップオーバーヘッドを引き起すことが知られているものがあります。あなたのシステムのウイルススキャンソフトウェアの設定を確かめて、本当に同様に設定されていることを確実にしてください。

どうすれば Python スクリプトを EXE に出来ますか?

実行可能ファイルを作れるツールの一覧 どうしたら Python スクリプトからスタンドアロンバイナリを作れますか？ を参照してください。

*.pyd ファイルは DLL と同じですか？

はい、.pyd ファイルは dll と同じようなものですが、少し違いがあります。foo.pyd という名前の DLL があったとしたら、それには関数 PyInit_foo() が含まれていなければなりません。そうすれば Python で "import foo" を書けて、Python は foo.pyd (や foo.py、foo.pyc) を探して、あれば、PyInit_foo() を呼び出して初期化しようとします。Windows が DLL の存在を必要とするのと違い、.exe ファイルを foo.lib にリンクするわけではありません。

なお、foo.pyd を検索するパスは PYTHONPATH であり、Windows が foo.dll を検索するパスと同じではありません。また、プログラムを dll にリンクしたときはプログラムの実行に dll が必要ですが、foo.pyd は実行には必要はありません。もちろん、 import foo したいなら foo.pyd は必要です。DLL では、リンクはソースコード内で __declspec(dllexport) によって宣言されます。.pyd では、リンクは使える関数のリストで定義されます。

Python を Windows アプリケーションに埋め込むにはどうしたらいいですか？

Python インタプリタを Windows app に埋め込む方法は、次のように要約できます:

あなたの .exe 内に直接 Python を取り込んでビルド しないで 下さい。Windows では、それ自身が DLL になっているようなモジュールのインポートを処理するために、Python は DLL でなければなりません。(ドキュメント化されていない重大な事実の一つ目です。)代わりに、 pythonNN.dll とリンクしてください; 普通はそれは C:\Windows\System にインストールされています。 NN は Python バージョンで Python 3.3 であれば "33" のような数字です。

Python には、load-time に、または run-time にリンクできます。load-time なリンクは、 pythonNN.lib に対してリンクするもので、run-time なリンクは pythonNN.dll に対してリンクするものです。(一般的な注意: pythonNN.lib は pythonNN.dll に対するいわゆる "インポートライブラリ" です。これは単にリンカに対するシンボルを定義します。)

run-time なリンクは、リンクの選択を大いに単純化します。全ては実行時に行われます。コードは Windows の LoadLibraryEx() ルーチンで pythonNN.dll をロードしなければなりません。コードはまた、Windows の GetProcAddress() ルーチンで得られるポインタで、 pythonNN.dll (すなわち、Python の C API)のルーチンとデータへアクセスしていなければなりません。マクロによって、このポインタを Python の C API のルーチンを呼び出す任意の C コードに通して使えます。

SWIG を使えば、app のデータとメソッドを Python で使えるようにする Python "拡張モジュール"を簡単に作れます。SWIG は雑用を殆どやってくれるでしょう。結果として、.exe ファイル の中に リンクする C コードができます(！)。DLL を作 らなくてもよく、リンクも簡潔になります。

SWIG は拡張の名前に依る名前の init 関数 (C 関数) を作ります。例えば、モジュールの名前が leo なら、init 関数の名前は initleo() になります。SWIG shadow クラスを使ったほうがよく、そうすると init 関数の名前は initleoc() になります。これは shadow クラスが使うほとんど隠れた helper クラスを初期化します。

ステップ 2 の C コードを .exe ファイルにリンクできるのは、初期化関数の呼び出しと Python へのモジュールのインポートが同等だからです！ (ドキュメント化されていない重大な事実の二つ目です)

要するに、以下のコードを使って Python インタプリタを拡張モジュール込みで初期化することができます。

#include <Python.h>
...
Py_Initialize();  // Initialize Python.
initmyAppc();  // Initialize (import) the helper class.
PyRun_SimpleString("import myApp");  // Import the shadow class.

Python の C API には、pythonNN.dll をビルドするのに使われたコンパイラ MSVC 以外のコンパイラを使うと現れる二つの問題があります。

問題 1: コンパイラによって struct FILE に対する概念が異なるため、FILE * 引数を取るいわゆる "超高水準" 関数は、多コンパイラ環境で働きません。実装の観点から、これらは超低水準関数になっています。

問題 2: SWIG は void 関数へのラッパを生成するときに以下のコードを生成します:

Py_INCREF(Py_None);
_resultobj = Py_None;
return _resultobj;

ああ、Py_none は pythonNN.dll 内の _Py_NoneStruct という複雑なデータ構造に展開するマクロです。また、このコードは他コンパイラ環境では失敗します。このコードを次のように置き換えてください:

return Py_BuildValue("");

これで、SWIG をまだ仕事に使えない (私は SWIG の完全な初心者です) 私でも、SWIG の %typemap コマンドを使って自動的に変更できるようになります。

Python シェルスクリプトを使って Windows app 内から Python インタプリタウィンドウを掲示するのはいい方法ではありません。そのように表示されるウィンドウは app のウィンドウシステムとは関係ありません。むしろ "ネイティブな" インタプリタウィンドウを (wxPythonWindow を使ったりして) 作るべきです。そのウィンドウを Python インタプリタにつなぐのは簡単です。Python の i/o は読み書きをサポートする _どんな_ オブジェクトにもリダイレクトできるので、read() と write() メソッドを含む (拡張モジュールで定義された) Python オブジェクトさえあればいいのです。

エディタが Python ソースにタブを勝手に挿入しないようにするにはどうしますか？

この FAQ ではタブを使うことを勧めません。Python スタイルガイド PEP 8 [https://peps.python.org/pep-0008/] では、配布される Python コードにはスペース 4 つを使うことを推奨しています。これは Emacs の python-mode のデフォルトでも同じです。

いかなるエディタでも、タブとスペースを混ぜるのは良くないです。 MSVC も全く同じ立場であり、スペースを使うようにする設定が簡単にできます。 Tools ‣ Options ‣ Tabs を選択し、ファイルタイプの "デフォルト" の "タブ幅" と "インデント幅" に 4 を設定して、 "スペースを挿入する" のラジオボタンを選択してください。

Python は、もしタブとスペースが混在していることで先頭の空白に問題がある場合、IndentationError または TabError を送出します。 tabnanny モジュールを実行することで、ディレクトリーツリーをバッチモードでチェックすることができます。

ブロックすることなく押鍵を検出するにはどうしますか？

msvcrt モジュールを使ってください。これは標準の Windows 専用拡張モジュールです。これはキーボードが打たれているかを調べる関数 kbhit() と、反響することなく一文字を得る getch() を定義します。

missing api-ms-win-crt-runtime-l1-1-0.dll エラーを解決するにはどうしますか？

この問題は更新がインストールされていない Windows 8.1 以前を使っていると Python 3.5 以降で発生することがあります。まずはあなたのオペレーティングシステムがサポートされており最新であることを確認してください。それでも解決しない場合は、 C ランタイムアップデートの手動インストール方法について Microsoft support page [https://support.microsoft.com/en-us/help/3118401/] を参照してください。

グラフィックユーザインターフェース FAQ

目次

グラフィックユーザインターフェース FAQ

一般的な GUI の質問

Python の GUI ツールキットには何がありますか？

Tkinter の質問

Tkinter アプリケーションを凍結するにはどうしますか？

I/O を待つ間に扱われる Tk イベントを作れますか？

Tkinter で働くキーバインディングが得られません。なぜですか？

一般的な GUI の質問

Python の GUI ツールキットには何がありますか？

Python の標準的なビルドには、 tkinter という Tcl/Tk ウィジェットセットのオブジェクト指向インターフェースが含まれています。これは最も簡単にインストールして使えるでしょう (なぜなら、これは Python のほとんどの バイナリディストリビューション [https://www.python.org/downloads/] に同梱されているからです)。ソースへのポインタなど、 Tk に関する詳しい情報は、 Tcl/Tk ホームページ [https://www.tcl.tk] を参照してください。 Tcl/Tk は、 macOS 、Windows 、 Unix プラットフォームに完全にポータブルです。

対象とするプラットフォームによっては他の選択肢もあります。プラットフォーム互換 [https://wiki.python.org/moin/GuiProgramming#Cross-Platform_Frameworks] および プラットフォーム固有 [https://wiki.python.org/moin/GuiProgramming#Platform-specific_Frameworks] の GUI フレームワークのリストを python wiki で参照できます。

Tkinter の質問

Tkinter アプリケーションを凍結するにはどうしますか？

Freeze はスタンドアロンアプリケーションを生成するツールです。Tkinter アプリケーションを凍結するとき、それは Tcl と Tk ライブラリを必要とするので、真のスタンドアロンにはなりません。

一つの解決策は、アプリケーションに Tcl と Tk ライブラリを同梱し、環境変数 TCL_LIBRARY と TK_LIBRARY でランタイムに指定することです。

To get truly stand-alone applications, the Tcl scripts that form the library have to be integrated into the application as well. One tool supporting that is SAM (stand-alone modules), which is part of the Tix distribution (https://tix.sourceforge.net/).

Build Tix with SAM enabled, perform the appropriate call to Tclsam_init(), etc. inside Python's Modules/tkappinit.c, and link with libtclsam and libtksam (you might include the Tix libraries as well).

I/O を待つ間に扱われる Tk イベントを作れますか？

Windows 以外のプラットフォームについては、はい、スレッドさえ必要ありません！ ただし、I/O コードを少し再構成しなければなりません。Tk には Xt の XtAddInput() コールと同等なものがあるので、ファイルディスクリプタ上で I/O が可能なときに Tk メインループから呼ばれるコールバック関数を登録できます。 ファイルハンドラ を参照してください。

Tkinter で働くキーバインディングが得られません。なぜですか？

bind() メソッドでイベントに 結び付けられた イベントハンドラが、適切なキーが押されたときにさえハンドルされないという苦情がよく聞かれます。

最も一般的な原因は、バインディングが適用されるウィジェットが "キーボードフォーカス" を持たないことです。Tk ドキュメントでフォーカスコマンドを確認してください。通常はウィジェットの中をクリックすることでキーボードフォーカスを与えられます (ただしラベルには与えられません。takefocus オプションを参照してください)。

"なぜ Python が私のコンピュータにインストールされているのですか？" FAQ

Python とは何ですか？

Python はプログラミング言語の一つです。Python は様々なアプリケーションに使われています。Python は習得しやすいので、一部の高校や大学で入門用のプログラミング言語として使われています。一方で、Google、NASA、Lucasfilm Ltd. のような組織でプロフェッショナルなソフトウェア開発者にも使われています。

Python についてもっと詳しく知りたいなら、Beginner's Guide to Python [https://wiki.python.org/moin/BeginnersGuide] から始めましょう。

なぜ Python が私のマシンにインストールされているのですか？

インストールした覚えがないのに Python があなたのシステムにインストールされているとしたら、その理由にはいくつかの可能性があります。

もしかしたら、コンピュータの他のユーザがプログラミングを学ぶためにインストールしたのかもしれません。誰がそのマシンを使っていて Python をインストールしたか知る必要があります。

マシンにインストールされているサードパーティのアプリケーションが、Python で書かれていて Python のインストールを含んでいるかもしれません。そのようなアプリケーションは、GUI プログラムからネットワーク・サーバや管理スクリプトまで、たくさんあります。

Windows マシンにも Python がインストールされたものがあります。この執筆時点で Hewlett-Packard や Compaq が Python を組み込んでいることを確認しています。 HP/Compaq の管理ツールの中には、Python で書かれたものもあるようです。

macOS や一部の Linux ディストリビューションなど、多くの Unix 互換オペレーティングシステムシステムには、Python がデフォルトでインストールされています。標準インストールに Python が含まれているのです。

Python を削除してもいいですか？

Python をどこから手に入れたかによります。

誰かが Python を意図してダウンロードしたのであれば、何の問題もなく削除することができます。Windows では、コントロールパネルのプログラムの追加と削除を使ってください。

Python がサードパーティのアプリケーションによってインストールされたなら、同様に削除できますが、そのアプリケーションは動作しなくなります。 Python のディレクトリを削除するのではなく、そのアプリケーションのアンインストーラーを使うべきです。

Python がオペレーティングシステムに含まれて来たなら、削除はお勧めできません。削除してしまうと、Python で書かれたプログラムは全く動かなくなり、その中には重要なものが含まれているかもしれません。その場合、修復にはシステム全体の再インストールが必要になるでしょう。

用語集

>>>

The default Python prompt of the interactive shell. Often seen for code examples which can be executed interactively in the interpreter.

...

次のものが考えられます:

The default Python prompt of the interactive shell when entering the code for an indented code block, when within a pair of matching left and right delimiters (parentheses, square brackets, curly braces or triple quotes), or after specifying a decorator.

組み込みの定数 Ellipsis 。

2to3

A tool that tries to convert Python 2.x code to Python 3.x code by handling most of the incompatibilities which can be detected by parsing the source and traversing the parse tree.

2to3 is available in the standard library as lib2to3; a standalone entry point is provided as Tools/scripts/2to3. See 2to3 --- Python 2 から 3 への自動コード変換.

abstract base class

(抽象基底クラス) 抽象基底クラスは duck-typing を補完するもので、 hasattr() などの別のテクニックでは不恰好であったり微妙に誤る (例えば magic methods の場合) 場合にインターフェースを定義する方法を提供します。ABC は仮想 (virtual) サブクラスを導入します。これは親クラスから継承しませんが、それでも isinstance() や issubclass() に認識されます; abc モジュールのドキュメントを参照してください。Python には、多くの組み込み ABC が同梱されています。その対象は、(collections.abc モジュールで) データ構造、(numbers モジュールで) 数、(io モジュールで) ストリーム、(importlib.abc モジュールで) インポートファインダ及びローダーです。 abc モジュールを利用して独自の ABC を作成できます。

annotation

(アノテーション) 変数、クラス属性、関数のパラメータや返り値に関係するラベルです。慣例により type hint として使われています。

ローカル変数のアノテーションは実行時にはアクセスできませんが、グローバル変数、クラス属性、関数のアノテーションはそれぞれモジュール、クラス、関数の __annotations__ 特殊属性に保持されています。

機能の説明がある variable annotation, function annotation, PEP 484 [https://peps.python.org/pep-0484/], PEP 526 [https://peps.python.org/pep-0526/] を参照してください。また、アノテーションを利用するベストプラクティスとして Annotations Best Practices も参照してください。

引数 (argument)

(実引数) 関数を呼び出す際に、 関数 (または メソッド) に渡す値です。実引数には２種類あります:

キーワード引数: 関数呼び出しの際に引数の前に識別子がついたもの (例: name=) や、 ** に続けた辞書の中の値として渡された引数。例えば、次の complex() の呼び出しでは、 3 と 5 がキーワード引数です:

complex(real=3, imag=5)
complex(**{'real': 3, 'imag': 5})

位置引数: キーワード引数以外の引数。位置引数は引数リストの先頭に書くことができ、また * に続けた iterable の要素として渡すことができます。例えば、次の例では 3 と 5 は両方共位置引数です:

complex(3, 5)
complex(*(3, 5))

実引数は関数の実体において名前付きのローカル変数に割り当てられます。割り当てを行う規則については 呼び出し (call) を参照してください。シンタックスにおいて実引数を表すためにあらゆる式を使うことが出来ます。評価された値はローカル変数に割り当てられます。

仮引数 、FAQ の 実引数と仮引数の違いは何ですか? 、PEP 362 [https://peps.python.org/pep-0362/] を参照してください。

asynchronous context manager

(非同期コンテキストマネージャ) __aenter__() と __aexit__() メソッドを定義することで async with 文内の環境を管理するオブジェクトです。 PEP 492 [https://peps.python.org/pep-0492/] で導入されました。

asynchronous generator

(非同期ジェネレータ) asynchronous generator iterator を返す関数です。 async def で定義されたコルーチン関数に似ていますが、 yield 式を持つ点で異なります。 yield 式は async for ループで使用できる値の並びを生成するのに使用されます。

通常は非同期ジェネレータ関数を指しますが、文脈によっては 非同期ジェネレータイテレータ を指す場合があります。意図された意味が明らかでない場合、 明瞭化のために完全な単語を使用します。

非同期ジェネレータ関数には、 async for 文や async with 文だけでなく await 式もあることがあります。

asynchronous generator iterator

(非同期ジェネレータイテレータ) asynchronous generator 関数で生成されるオブジェクトです。

これは asynchronous iterator で、 __anext__() メソッドを使って呼ばれると awaitable オブジェクトを返します。 この awaitable オブジェクトは、次の yield 式まで非同期ジェネレータ関数の本体を実行します。

各 yield では一時的に処理を中断し、その場の実行状態 (ローカル変数や保留中の try 文を含む) を記憶します。 非同期ジェネレータイテレータ が __anext__() で返された他の awaitable で実際に再開する時には、その中断箇所が選ばれます。 PEP 492 [https://peps.python.org/pep-0492/] および PEP 525 [https://peps.python.org/pep-0525/] を参照してください。

asynchronous iterable

(非同期イテラブル) async for 文の中で使用できるオブジェクトです。 自身の __aiter__() メソッドから asynchronous iterator を返さなければなりません。 PEP 492 [https://peps.python.org/pep-0492/] で導入されました。

asynchronous iterator

(非同期イテレータ) __aiter__() と __anext__() メソッドを実装したオブジェクトです。 __anext__() は awaitable オブジェクトを返さなければなりません。 async for は StopAsyncIteration 例外を送出するまで、非同期イテレータの __anext__() メソッドが返す awaitable を解決します。 PEP 492 [https://peps.python.org/pep-0492/] で導入されました。

属性

(属性) オブジェクトに関連付けられ、ドット表記式によって名前で通常参照される値です。例えば、オブジェクト o が属性 a を持っているとき、その属性は o.a で参照されます。

オブジェクトには、 識別子 (identifier) およびキーワード (keyword) で定義される識別子ではない名前の属性を与えることができます。たとえば setattr() を使い、オブジェクトがそれを許可している場合に行えます。このような属性はドット表記式ではアクセスできず、代わりに getattr() を使って取る必要があります。

awaitable

(待機可能) await 式で使用することが出来るオブジェクトです。 coroutine か、 __await__() メソッドがあるオブジェクトです。 PEP 492 [https://peps.python.org/pep-0492/] を参照してください。

BDFL

慈悲深き終身独裁者 (Benevolent Dictator For Life) の略です。Python の作者、Guido van Rossum [https://gvanrossum.github.io/] のことです。

binary file

(バイナリファイル) bytes-like オブジェクト の読み込みおよび書き込みができる ファイルオブジェクト です。バイナリファイルの例は、バイナリモード ('rb', 'wb' or 'rb+') で開かれたファイル、sys.stdin.buffer、sys.stdout.buffer、 io.BytesIO や gzip.GzipFile. のインスタンスです。

str オブジェクトの読み書きができるファイルオブジェクトについては、 text file も参照してください。

borrowed reference

In Python's C API, a borrowed reference is a reference to an object, where the code using the object does not own the reference. It becomes a dangling pointer if the object is destroyed. For example, a garbage collection can remove the last strong reference to the object and so destroy it.

Calling Py_INCREF() on the borrowed reference is recommended to convert it to a strong reference in-place, except when the object cannot be destroyed before the last usage of the borrowed reference. The Py_NewRef() function can be used to create a new strong reference.

bytes-like object

バッファプロトコル (buffer Protocol) をサポートしていて、 C 言語の意味で 連続した バッファーを提供可能なオブジェクト。 bytes, bytearray, array.array や、多くの一般的な memoryview オブジェクトがこれに当たります。 bytes-like オブジェクトは、データ圧縮、バイナリファイルへの保存、ソケットを経由した送信など、バイナリデータを要求するいろいろな操作に利用することができます。

幾つかの操作ではバイナリデータを変更する必要があります。その操作のドキュメントではよく "読み書き可能な bytes-like オブジェクト" に言及しています。変更可能なバッファーオブジェクトには、 bytearray と bytearray の memoryview などが含まれます。また、他の幾つかの操作では不変なオブジェクト内のバイナリデータ ("読み出し専用の bytes-like オブジェクト") を必要します。それには bytes と bytes の memoryview オブジェクトが含まれます。

bytecode

(バイトコード) Python のソースコードは、 Python プログラムの CPython インタプリタの内部表現であるバイトコードへとコンパイルされます。バイトコードは .pyc ファイルにキャッシュされ、同じファイルが二度目に実行されるときはより高速になります (ソースコードからバイトコードへの再度のコンパイルは回避されます)。この "中間言語 (intermediate language)" は、各々のバイトコードに対応する機械語を実行する 仮想マシン で動作するといえます。重要な注意として、バイトコードは異なる Python 仮想マシン間で動作することや、Python リリース間で安定であることは期待されていません。

バイトコードの命令一覧は dis モジュール にあります。

callable

A callable is an object that can be called, possibly with a set of arguments (see argument), with the following syntax:

callable(argument1, argument2, argumentN)

A function, and by extension a method, is a callable. An instance of a class that implements the __call__() method is also a callable.

callback

(コールバック) 将来のある時点で実行されるために引数として渡される関数

クラス

(クラス) ユーザー定義オブジェクトを作成するためのテンプレートです。クラス定義は普通、そのクラスのインスタンス上の操作をするメソッドの定義を含みます。

class variable

(クラス変数) クラス上に定義され、クラスレベルで (つまり、クラスのインスタンス上ではなしに) 変更されることを目的としている変数です。

complex number

(複素数) よく知られている実数系を拡張したもので、すべての数は実部と虚部の和として表されます。虚数は虚数単位 (-1 の平方根) に実数を掛けたもので、一般に数学では i と書かれ、工学では j と書かれます。Python は複素数に組み込みで対応し、後者の表記を取っています。虚部は末尾に j をつけて書きます。例えば 3+1j です。 math モジュールの複素数版を利用するには、 cmath を使います。複素数の使用はかなり高度な数学の機能です。必要性を感じなければ、ほぼ間違いなく無視してしまってよいでしょう。

context manager

An object which controls the environment seen in a with statement by defining __enter__() and __exit__() methods. See PEP 343 [https://peps.python.org/pep-0343/].

context variable

(コンテキスト変数) コンテキストに依存して異なる値を持つ変数。これは、ある変数の値が各々の実行スレッドで異なり得るスレッドローカルストレージに似ています。しかしコンテキスト変数では、 1 つの実行スレッドにいくつかのコンテキストがあり得、コンテキスト変数の主な用途は並列な非同期タスクの変数の追跡です。 contextvars を参照してください。

contiguous

(隣接、連続) バッファが厳密に C-連続 または Fortran 連続 である場合に、そのバッファは連続しているとみなせます。ゼロ次元バッファは C 連続であり Fortran 連続です。一次元の配列では、その要素は必ずメモリ上で隣接するように配置され、添字がゼロから始まり増えていく順序で並びます。多次元の C-連続な配列では、メモリアドレス順に要素を巡る際には最後の添え字が最初に変わるのに対し、 Fortran 連続な配列では最初の添え字が最初に動きます。

コルーチン

(コルーチン) コルーチンはサブルーチンのより一般的な形式です。サブルーチンには決められた地点から入り、別の決められた地点から出ます。コルーチンには多くの様々な地点から入る、出る、再開することができます。コルーチンは async def 文で実装できます。 PEP 492 [https://peps.python.org/pep-0492/] を参照してください。

coroutine function

(コルーチン関数) coroutine オブジェクトを返す関数です。コルーチン関数は async def 文で実装され、await、async for、 および async with キーワードを持つことが出来ます。これらは PEP 492 [https://peps.python.org/pep-0492/] で導入されました。

CPython

python.org [https://www.python.org] で配布されている、Python プログラミング言語の標準的な実装です。"CPython" という単語は、この実装を Jython や IronPython といった他の実装と区別する必要が有る場合に利用されます。

decorator

(デコレータ) 別の関数を返す関数で、通常、 @wrapper 構文で関数変換として適用されます。デコレータの一般的な利用例は、 classmethod() と staticmethod() です。

デコレータの文法はシンタックスシュガーです。次の2つの関数定義は意味的に同じものです:

def f(arg):
    ...
f = staticmethod(f)

@staticmethod
def f(arg):
    ...

同じ概念がクラスにも存在しますが、あまり使われません。デコレータについて詳しくは、 関数定義 および クラス定義 のドキュメントを参照してください。

descriptor

Any object which defines the methods __get__(), __set__(), or __delete__(). When a class attribute is a descriptor, its special binding behavior is triggered upon attribute lookup. Normally, using a.b to get, set or delete an attribute looks up the object named b in the class dictionary for a, but if b is a descriptor, the respective descriptor method gets called. Understanding descriptors is a key to a deep understanding of Python because they are the basis for many features including functions, methods, properties, class methods, static methods, and reference to super classes.

デスクリプタのメソッドに関しての詳細は、 デスクリプタ (descriptor) の実装 や Descriptor How To Guide を参照してください。

dictionary

An associative array, where arbitrary keys are mapped to values. The keys can be any object with __hash__() and __eq__() methods. Called a hash in Perl.

dictionary comprehension

(辞書内包表記) iterable 内の全てあるいは一部の要素を処理して、その結果からなる辞書を返すコンパクトな書き方です。 results = {n: n ** 2 for n in range(10)} とすると、キー n を値 n ** 2 に対応付ける辞書を生成します。 リスト、集合、辞書の表示 を参照してください。

dictionary view

(辞書ビュー) dict.keys()、dict.values()、dict.items() が返すオブジェクトです。辞書の項目の動的なビューを提供します。すなわち、辞書が変更されるとビューはそれを反映します。辞書ビューを強制的に完全なリストにするには list(dictview) を使用してください。辞書ビューオブジェクト を参照してください。

docstring

A string literal which appears as the first expression in a class, function or module. While ignored when the suite is executed, it is recognized by the compiler and put into the __doc__ attribute of the enclosing class, function or module. Since it is available via introspection, it is the canonical place for documentation of the object.

duck-typing

あるオブジェクトが正しいインターフェースを持っているかを決定するのにオブジェクトの型を見ないプログラミングスタイルです。代わりに、単純にオブジェクトのメソッドや属性が呼ばれたり使われたりします。（「アヒルのように見えて、アヒルのように鳴けば、それはアヒルである。」）インターフェースを型より重視することで、上手くデザインされたコードは、ポリモーフィックな代替を許して柔軟性を向上させます。ダックタイピングは type() や isinstance() による判定を避けます。 (ただし、ダックタイピングを 抽象基底クラス で補完することもできます。) その代わり、典型的に hasattr() 判定や EAFP プログラミングを利用します。

EAFP

「認可をとるより許しを請う方が容易 (easier to ask for forgiveness than permission、マーフィーの法則)」の略です。この Python で広く使われているコーディングスタイルでは、通常は有効なキーや属性が存在するものと仮定し、その仮定が誤っていた場合に例外を捕捉します。この簡潔で手早く書けるコーディングスタイルには、 try 文および except 文がたくさんあるのが特徴です。このテクニックは、C のような言語でよく使われている LBYL スタイルと対照的なものです。

expression

(式) 何かの値と評価される、一まとまりの構文 (a piece of syntax) です。言い換えると、式とはリテラル、名前、属性アクセス、演算子や関数呼び出しなど、値を返す式の要素の積み重ねです。他の多くの言語と違い、Python では言語の全ての構成要素が式というわけではありません。 while のように、式としては使えない 文 もあります。代入も式ではなく文です。

extension module

(拡張モジュール) C や C++ で書かれたモジュールで、Python の C API を利用して Python コアやユーザーコードとやりとりします。

f-string

'f' や 'F' が先頭に付いた文字列リテラルは "f-string" と呼ばれ、これは フォーマット済み文字列リテラル の短縮形の名称です。 PEP 498 [https://peps.python.org/pep-0498/] も参照してください。

file object

An object exposing a file-oriented API (with methods such as read() or write()) to an underlying resource. Depending on the way it was created, a file object can mediate access to a real on-disk file or to another type of storage or communication device (for example standard input/output, in-memory buffers, sockets, pipes, etc.). File objects are also called file-like objects or streams.

ファイルオブジェクトには実際には 3 種類あります: 生の バイナリーファイル、バッファされた バイナリーファイル、そして テキストファイル です。インターフェイスは io モジュールで定義されています。ファイルオブジェクトを作る標準的な方法は open() 関数を使うことです。

file-like object

file object と同義です。

filesystem encoding and error handler

Encoding and error handler used by Python to decode bytes from the operating system and encode Unicode to the operating system.

ファイルシステムのエンコーディングでは、すべてが 128 バイト以下に正常にデコードされることが保証されなくてはなりません。ファイルシステムのエンコーディングでこれが保証されなかった場合は、API 関数が UnicodeError を送出することがあります。

The sys.getfilesystemencoding() and sys.getfilesystemencodeerrors() functions can be used to get the filesystem encoding and error handler.

The filesystem encoding and error handler are configured at Python startup by the PyConfig_Read() function: see filesystem_encoding and filesystem_errors members of PyConfig.

See also the locale encoding.

finder

(ファインダ) インポートされているモジュールの loader の発見を試行するオブジェクトです。

Python 3.3 以降では 2 種類のファインダがあります。 sys.meta_path で使用される meta path finder と、 sys.path_hooks で使用される path entry finder です。

詳細については PEP 302 [https://peps.python.org/pep-0302/]、PEP 420 [https://peps.python.org/pep-0420/] および PEP 451 [https://peps.python.org/pep-0451/] を参照してください。

floor division

(切り捨て除算) 一番近い整数に切り捨てる数学的除算。切り捨て除算演算子は // です。例えば、 11 // 4 は 2 になり、それとは対称に浮動小数点数の真の除算では 2.75 が 返ってきます。 (-11) // 4 は -2.75 を 小さい方に 丸める (訳注: 負の無限大への丸めを行う) ので -3 になることに注意してください。 PEP 238 [https://peps.python.org/pep-0238/] を参照してください。

関数

(関数) 呼び出し側に値を返す一連の文のことです。関数には0以上の 実引数 を渡すことが出来ます。実体の実行時に引数を使用することが出来ます。 仮引数、メソッド、関数定義 を参照してください。

function annotation

(関数アノテーション) 関数のパラメータや返り値の annotation です。

関数アノテーションは、通常は 型ヒント のために使われます: 例えば、この関数は 2 つの int 型の引数を取ると期待され、また int 型の返り値を持つと期待されています。

def sum_two_numbers(a: int, b: int) -> int:
   return a + b

関数アノテーションの文法は 関数定義 の節で解説されています。

機能の説明がある variable annotation, PEP 484 [https://peps.python.org/pep-0484/],を参照してください。また、アノテーションを利用するベストプラクティスとして Annotations Best Practices も参照してください。

__future__

A future statement, from __future__ import <feature>, directs the compiler to compile the current module using syntax or semantics that will become standard in a future release of Python. The __future__ module documents the possible values of feature. By importing this module and evaluating its variables, you can see when a new feature was first added to the language and when it will (or did) become the default:

>>> import __future__
>>> __future__.division
_Feature((2, 2, 0, 'alpha', 2), (3, 0, 0, 'alpha', 0), 8192)

garbage collection

(ガベージコレクション) これ以降使われることのないメモリを解放する処理です。 Pythonは、参照カウントと、循環参照を検出し破壊する循環ガベージコレクタを使ってガベージコレクションを行います。ガベージコレクタは gc モジュールを使って操作できます。

ジェネレータ

(ジェネレータ) generator iterator を返す関数です。通常の関数に似ていますが、 yield 式を持つ点で異なります。 yield 式は、 for ループで使用できたり、next() 関数で値を 1 つずつ取り出したりできる、値の並びを生成するのに使用されます。

通常はジェネレータ関数を指しますが、文脈によっては ジェネレータイテレータ を指す場合があります。意図された意味が明らかでない場合、 明瞭化のために完全な単語を使用します。

generator iterator

(ジェネレータイテレータ) generator 関数で生成されるオブジェクトです。

yield のたびに局所実行状態 (局所変数や未処理の try 文などを含む) を記憶して、処理は一時的に中断されます。ジェネレータイテレータ が再開されると、中断した位置を取得します (通常の関数が実行のたびに新しい状態から開始するのと対照的です)。

generator expression

An expression that returns an iterator. It looks like a normal expression followed by a for clause defining a loop variable, range, and an optional if clause. The combined expression generates values for an enclosing function:

>>> sum(i*i for i in range(10))         # sum of squares 0, 1, 4, ... 81
285

generic function

(ジェネリック関数) 異なる型に対し同じ操作をする関数群から構成される関数です。呼び出し時にどの実装を用いるかはディスパッチアルゴリズムにより決定されます。

single dispatch、functools.singledispatch() デコレータ、PEP 443 [https://peps.python.org/pep-0443/] を参照してください。

generic type

A type that can be parameterized; typically a container class such as list or dict. Used for type hints and annotations.

For more details, see generic alias types, PEP 483 [https://peps.python.org/pep-0483/], PEP 484 [https://peps.python.org/pep-0484/], PEP 585 [https://peps.python.org/pep-0585/], and the typing module.

GIL

global interpreter lock を参照してください。

global interpreter lock

(グローバルインタプリタロック) CPython インタプリタが利用している、一度に Python の バイトコード を実行するスレッドは一つだけであることを保証する仕組みです。これにより (dict などの重要な組み込み型を含む) オブジェクトモデルが同時アクセスに対して暗黙的に安全になるので、 CPython の実装がシンプルになります。インタプリタ全体をロックすることで、マルチプロセッサマシンが生じる並列化のコストと引き換えに、インタプリタを簡単にマルチスレッド化できるようになります。

ただし、標準あるいは外部のいくつかの拡張モジュールは、圧縮やハッシュ計算などの計算の重い処理をするときに GIL を解除するように設計されています。また、I/O 処理をする場合 GIL は常に解除されます。

Past efforts to create a "free-threaded" interpreter (one which locks shared data at a much finer granularity) have not been successful because performance suffered in the common single-processor case. It is believed that overcoming this performance issue would make the implementation much more complicated and therefore costlier to maintain.

hash-based pyc

(ハッシュベース pyc ファイル) 正当性を判別するために、対応するソースファイルの最終更新時刻ではなくハッシュ値を使用するバイトコードのキャッシュファイルです。キャッシュされたバイトコードの無効化 を参照してください。

hashable

An object is hashable if it has a hash value which never changes during its lifetime (it needs a __hash__() method), and can be compared to other objects (it needs an __eq__() method). Hashable objects which compare equal must have the same hash value.

ハッシュ可能なオブジェクトは辞書のキーや集合のメンバーとして使えます。辞書や集合のデータ構造は内部でハッシュ値を使っているからです。

Python のイミュータブルな組み込みオブジェクトは、ほとんどがハッシュ可能です。(リストや辞書のような) ミュータブルなコンテナはハッシュ不可能です。(タプルや frozenset のような) イミュータブルなコンテナは、要素がハッシュ可能であるときのみハッシュ可能です。ユーザー定義のクラスのインスタンスであるようなオブジェクトはデフォルトでハッシュ可能です。それらは全て (自身を除いて) 比較結果は非等価であり、ハッシュ値は id() より得られます。

IDLE

Python の統合開発環境 (Integrated DeveLopment Environment)及び学習環境 (Learning Environment) です。IDLE は Python の標準的な配布に同梱されている基本的な機能のエディタとインタプリタ環境です。

immutable

(イミュータブル) 固定の値を持ったオブジェクトです。イミュータブルなオブジェクトには、数値、文字列、およびタプルなどがあります。これらのオブジェクトは値を変えられません。別の値を記憶させる際には、新たなオブジェクトを作成しなければなりません。イミュータブルなオブジェクトは、固定のハッシュ値が必要となる状況で重要な役割を果たします。辞書のキーがその例です。

import path

path based finder が import するモジュールを検索する場所 (または path entry) のリスト。 import 中、このリストは通常 sys.path から来ますが、サブパッケージの場合は親パッケージの __path__ 属性からも来ます。

importing

あるモジュールの Python コードが別のモジュールの Python コードで使えるようにする処理です。

importer

モジュールを探してロードするオブジェクト。 finder と loader のどちらでもあるオブジェクト。

interactive

Python has an interactive interpreter which means you can enter statements and expressions at the interpreter prompt, immediately execute them and see their results. Just launch python with no arguments (possibly by selecting it from your computer's main menu). It is a very powerful way to test out new ideas or inspect modules and packages (remember help(x)).

interpreted

Python はインタプリタ形式の言語であり、コンパイラ言語の対極に位置します。 (バイトコードコンパイラがあるために、この区別は曖昧ですが。) ここでのインタプリタ言語とは、ソースコードのファイルを、まず実行可能形式にしてから実行させるといった操作なしに、直接実行できることを意味します。インタプリタ形式の言語は通常、コンパイラ形式の言語よりも開発／デバッグのサイクルは短いものの、プログラムの実行は一般に遅いです。 対話的 も参照してください。

interpreter shutdown

Python インタープリターはシャットダウンを要請された時に、モジュールやすべてのクリティカルな内部構造をなどの、すべての確保したリソースを段階的に開放する、特別なフェーズに入ります。このフェーズは ガベージコレクタ を複数回呼び出します。これによりユーザー定義のデストラクターや weakref コールバックが呼び出されることがあります。シャットダウンフェーズ中に実行されるコードは、それが依存するリソースがすでに機能しない(よくある例はライブラリーモジュールや warning 機構です) ために様々な例外に直面します。

インタープリタがシャットダウンする主な理由は __main__ モジュールや実行されていたスクリプトの実行が終了したことです。

iterable

An object capable of returning its members one at a time. Examples of iterables include all sequence types (such as list, str, and tuple) and some non-sequence types like dict, file objects, and objects of any classes you define with an __iter__() method or with a __getitem__() method that implements sequence semantics.

Iterables can be used in a for loop and in many other places where a sequence is needed (zip(), map(), ...). When an iterable object is passed as an argument to the built-in function iter(), it returns an iterator for the object. This iterator is good for one pass over the set of values. When using iterables, it is usually not necessary to call iter() or deal with iterator objects yourself. The for statement does that automatically for you, creating a temporary unnamed variable to hold the iterator for the duration of the loop. See also iterator, sequence, and generator.

iterator

An object representing a stream of data. Repeated calls to the iterator's __next__() method (or passing it to the built-in function next()) return successive items in the stream. When no more data are available a StopIteration exception is raised instead. At this point, the iterator object is exhausted and any further calls to its __next__() method just raise StopIteration again. Iterators are required to have an __iter__() method that returns the iterator object itself so every iterator is also iterable and may be used in most places where other iterables are accepted. One notable exception is code which attempts multiple iteration passes. A container object (such as a list) produces a fresh new iterator each time you pass it to the iter() function or use it in a for loop. Attempting this with an iterator will just return the same exhausted iterator object used in the previous iteration pass, making it appear like an empty container.

詳細な情報は イテレータ型 にあります。

CPython 実装の詳細: CPython does not consistently apply the requirement that an iterator define __iter__().

key function

(キー関数) キー関数、あるいは照合関数とは、ソートや順序比較のための値を返す呼び出し可能オブジェクト(callable)です。例えば、 locale.strxfrm() をキー関数に使えば、ロケール依存のソートの慣習にのっとったソートキーを返します。

Python の多くのツールはキー関数を受け取り要素の並び順やグループ化を管理します。 min(), max(), sorted(), list.sort(), heapq.merge(), heapq.nsmallest(), heapq.nlargest(), itertools.groupby() 等があります。

キー関数を作る方法はいくつかあります。例えば str.lower() メソッドを大文字小文字を区別しないソートを行うキー関数として使うことが出来ます。あるいは、lambda r: (r[0], r[2]) のような lambda 式からキー関数を作ることができます。また、operator.attrgetter(), operator.itemgetter(), operator.methodcaller() の 3 つのキー関数コンストラクタがあります。キー関数の作り方と使い方の例は Sorting HOW TO を参照してください。

keyword argument

実引数 を参照してください。

lambda

(ラムダ) 無名のインライン関数で、関数が呼び出されたときに評価される 1 つの 式 を含みます。ラムダ関数を作る構文は lambda [parameters]: expression です。

LBYL

「ころばぬ先の杖 (look before you leap)」 の略です。このコーディングスタイルでは、呼び出しや検索を行う前に、明示的に前提条件 (pre-condition) 判定を行います。 EAFP アプローチと対照的で、 if 文がたくさん使われるのが特徴的です。

マルチスレッド化された環境では、LBYL アプローチは "見る" 過程と "飛ぶ" 過程の競合状態を引き起こすリスクがあります。例えば、if key in mapping: return mapping[key] というコードは、判定の後、別のスレッドが探索の前に mapping から key を取り除くと失敗します。この問題は、ロックするか EAFP アプローチを使うことで解決できます。

list

A built-in Python sequence. Despite its name it is more akin to an array in other languages than to a linked list since access to elements is O(1).

list comprehension

(リスト内包表記) シーケンス中の全てあるいは一部の要素を処理して、その結果からなるリストを返す、コンパクトな方法です。 result = ['{:#04x}'.format(x) for x in range(256) if x % 2 == 0] とすると、 0 から 255 までの偶数を 16進数表記 (0x..) した文字列からなるリストを生成します。 if 節はオプションです。 if 節がない場合、 range(256) の全ての要素が処理されます。

loader

モジュールをロードするオブジェクト。 load_module() という名前のメソッドを定義していなければなりません。ローダーは一般的に finder から返されます。詳細は PEP 302 [https://peps.python.org/pep-0302/] を、 abstract base class については importlib.abc.Loader を参照してください。

ロケールエンコーディング

On Unix, it is the encoding of the LC_CTYPE locale. It can be set with locale.setlocale(locale.LC_CTYPE, new_locale).

On Windows, it is the ANSI code page (ex: "cp1252").

On Android and VxWorks, Python uses "utf-8" as the locale encoding.

locale.getencoding() can be used to get the locale encoding.

See also the filesystem encoding and error handler.

magic method

special method のくだけた同義語です。

mapping

(マッピング) 任意のキー探索をサポートしていて、 collections.abc.Mapping か collections.abc.MutableMapping の 抽象基底クラス で指定されたメソッドを実装しているコンテナオブジェクトです。例えば、 dict, collections.defaultdict, collections.OrderedDict, collections.Counter などです。

meta path finder

sys.meta_path を検索して得られた finder. meta path finder は path entry finder と関係はありますが、別物です。

meta path finder が実装するメソッドについては importlib.abc.MetaPathFinder を参照してください。

metaclass

(メタクラス) クラスのクラスです。クラス定義は、クラス名、クラスの辞書と、基底クラスのリストを作ります。メタクラスは、それら 3 つを引数として受け取り、クラスを作る責任を負います。ほとんどのオブジェクト指向言語は(訳注:メタクラスの)デフォルトの実装を提供しています。Python が特別なのはカスタムのメタクラスを作成できる点です。ほとんどのユーザーに取って、メタクラスは全く必要のないものです。しかし、一部の場面では、メタクラスは強力でエレガントな方法を提供します。たとえば属性アクセスのログを取ったり、スレッドセーフ性を追加したり、オブジェクトの生成を追跡したり、シングルトンを実装するなど、多くの場面で利用されます。

詳細は メタクラス を参照してください。

メソッド

(メソッド) クラス本体の中で定義された関数。そのクラスのインスタンスの属性として呼び出された場合、メソッドはインスタンスオブジェクトを第一 引数 として受け取ります (この第一引数は通常 self と呼ばれます)。 関数 と ネストされたスコープ も参照してください。

method resolution order

Method Resolution Order is the order in which base classes are searched for a member during lookup. See The Python 2.3 Method Resolution Order for details of the algorithm used by the Python interpreter since the 2.3 release.

module

(モジュール) Python コードの組織単位としてはたらくオブジェクトです。モジュールは任意の Python オブジェクトを含む名前空間を持ちます。モジュールは importing の処理によって Python に読み込まれます。

パッケージ を参照してください。

module spec

モジュールをロードするのに使われるインポート関連の情報を含む名前空間です。 importlib.machinery.ModuleSpec のインスタンスです。

MRO

method resolution order を参照してください。

mutable

(ミュータブル) ミュータブルなオブジェクトは、 id() を変えることなく値を変更できます。 イミュータブル) も参照してください。

named tuple

"名前付きタプル" という用語は、タプルを継承していて、インデックスが付く要素に対し属性を使ってのアクセスもできる任意の型やクラスに応用されています。その型やクラスは他の機能も持っていることもあります。

time.localtime() や os.stat() の返り値を含むいくつかの組み込み型は名前付きタプルです。他の例は sys.float_info です:

>>> sys.float_info[1]                   # indexed access
1024
>>> sys.float_info.max_exp              # named field access
1024
>>> isinstance(sys.float_info, tuple)   # kind of tuple
True

Some named tuples are built-in types (such as the above examples). Alternatively, a named tuple can be created from a regular class definition that inherits from tuple and that defines named fields. Such a class can be written by hand, or it can be created by inheriting typing.NamedTuple, or with the factory function collections.namedtuple(). The latter techniques also add some extra methods that may not be found in hand-written or built-in named tuples.

namespace

(名前空間) 変数が格納される場所です。名前空間は辞書として実装されます。名前空間にはオブジェクトの (メソッドの) 入れ子になったものだけでなく、局所的なもの、大域的なもの、そして組み込みのものがあります。名前空間は名前の衝突を防ぐことによってモジュール性をサポートする。例えば関数 builtins.open と os.open() は名前空間で区別されています。また、どのモジュールが関数を実装しているか明示することによって名前空間は可読性と保守性を支援します。例えば、random.seed() や itertools.islice() と書くと、それぞれモジュール random や itertools で実装されていることが明らかです。

namespace package

(名前空間パッケージ) サブパッケージのコンテナとしてのみ提供される PEP 420 [https://peps.python.org/pep-0420/] で定義された package です。名前空間パッケージは物理的な表現を持たないことができ、 __init__.py ファイルを持たないため、 regular package とは異なります。

module を参照してください。

nested scope

(ネストされたスコープ) 外側で定義されている変数を参照する機能です。例えば、ある関数が別の関数の中で定義されている場合、内側の関数は外側の関数中の変数を参照できます。ネストされたスコープはデフォルトでは変数の参照だけができ、変数の代入はできないので注意してください。ローカル変数は、最も内側のスコープで変数を読み書きします。同様に、グローバル変数を使うとグローバル名前空間の値を読み書きします。 nonlocal で外側の変数に書き込めます。

new-style class

Old name for the flavor of classes now used for all class objects. In earlier Python versions, only new-style classes could use Python's newer, versatile features like __slots__, descriptors, properties, __getattribute__(), class methods, and static methods.

object

(オブジェクト) 状態 (属性や値) と定義された振る舞い (メソッド) をもつ全てのデータ。もしくは、全ての 新スタイルクラス の究極の基底クラスのこと。

package

(パッケージ) サブモジュールや再帰的にサブパッケージを含むことの出来る module のことです。専門的には、パッケージは __path__ 属性を持つ Python オブジェクトです。

regular package と namespace package を参照してください。

parameter

(仮引数) 名前付の実体で 関数 (や メソッド ) の定義において関数が受ける 実引数 を指定します。仮引数には5種類あります:

位置またはキーワード: 位置 であるいは キーワード引数 として渡すことができる引数を指定します。これはたとえば以下の foo や bar のように、デフォルトの仮引数の種類です:

def func(foo, bar=None): ...

位置専用: 位置によってのみ与えられる引数を指定します。位置専用の引数は 関数定義の引数のリストの中でそれらの後ろに / を含めることで定義できます。例えば下記の posonly1 と posonly2 は位置専用引数になります:

def func(posonly1, posonly2, /, positional_or_keyword): ...

キーワード専用: キーワードによってのみ与えられる引数を指定します。キーワード専用の引数を定義できる場所は、例えば以下の kw_only1 や kw_only2 のように、関数定義の仮引数リストに含めた可変長位置引数または裸の * の後です:

def func(arg, *, kw_only1, kw_only2): ...

可変長位置: (他の仮引数で既に受けられた任意の位置引数に加えて) 任意の個数の位置引数が与えられることを指定します。このような仮引数は、以下の args のように仮引数名の前に * をつけることで定義できます:

def func(*args, **kwargs): ...

可変長キーワード: (他の仮引数で既に受けられた任意のキーワード引数に加えて) 任意の個数のキーワード引数が与えられることを指定します。このような仮引数は、上の例の kwargs のように仮引数名の前に ** をつけることで定義できます。

仮引数はオプションと必須の引数のどちらも指定でき、オプションの引数にはデフォルト値も指定できます。

仮引数 、FAQ の 実引数と仮引数の違いは何ですか? 、inspect.Parameter クラス、 関数定義 セクション、PEP 362 [https://peps.python.org/pep-0362/] を参照してください。

path entry

path based finder が import するモジュールを探す import path 上の1つの場所です。

path entry finder

sys.path_hooks にある callable (つまり path entry hook) が返した finder です。与えられた path entry にあるモジュールを見つける方法を知っています。

パスエントリーファインダが実装するメソッドについては importlib.abc.PathEntryFinder を参照してください。

path entry hook

A callable on the sys.path_hooks list which returns a path entry finder if it knows how to find modules on a specific path entry.

path based finder

デフォルトの meta path finder の1つは、モジュールの import path を検索します。

path-like object

(path-like オブジェクト) ファイルシステムパスを表します。 path-like オブジェクトは、パスを表す str オブジェクトや bytes オブジェクト、または os.PathLike プロトコルを実装したオブジェクトのどれかです。 os.PathLike プロトコルをサポートしているオブジェクトは os.fspath() を呼び出すことで str または bytes のファイルシステムパスに変換できます。 os.fsdecode() と os.fsencode() はそれぞれ str あるいは bytes になるのを保証するのに使えます。 PEP 519 [https://peps.python.org/pep-0519/] で導入されました。

PEP

Python Enhancement Proposal。PEP は、Python コミュニティに対して情報を提供する、あるいは Python の新機能やその過程や環境について記述する設計文書です。 PEP は、機能についての簡潔な技術的仕様と提案する機能の論拠 (理論) を伝えるべきです。

PEP は、新機能の提案にかかる、コミュニティによる問題提起の集積と Python になされる設計決断の文書化のための最上位の機構となることを意図しています。PEP の著者にはコミュニティ内の合意形成を行うこと、反対意見を文書化することの責務があります。

PEP 1 [https://peps.python.org/pep-0001/] を参照してください。

portion

PEP 420 [https://peps.python.org/pep-0420/] で定義されている、namespace package に属する、複数のファイルが (zipファイルに格納されている場合もある) 1つのディレクトリに格納されたもの。

位置引数 (positional argument)

実引数 を参照してください。

provisional API

(暫定 API) 標準ライブラリの後方互換性保証から計画的に除外されたものです。そのようなインターフェースへの大きな変更は、暫定であるとされている間は期待されていませんが、コア開発者によって必要とみなされれば、後方非互換な変更 (インターフェースの削除まで含まれる) が行われえます。このような変更はむやみに行われるものではありません -- これは API を組み込む前には見落とされていた重大な欠陥が露呈したときにのみ行われます。

暫定 API についても、後方互換性のない変更は「最終手段」とみなされています。問題点が判明した場合でも後方互換な解決策を探すべきです。

このプロセスにより、標準ライブラリは問題となるデザインエラーに長い間閉じ込められることなく、時代を超えて進化を続けられます。詳細は PEP 411 [https://peps.python.org/pep-0411/] を参照してください。

provisional package

provisional API を参照してください。

Python 3000

Python 3.x リリースラインのニックネームです。(Python 3 が遠い将来の話だった頃に作られた言葉です。) "Py3k" と略されることもあります。

Pythonic

他の言語で一般的な考え方で書かれたコードではなく、Python の特に一般的なイディオムに従った考え方やコード片。例えば、Python の一般的なイディオムでは for 文を使ってイテラブルのすべての要素に渡ってループします。他の多くの言語にはこの仕組みはないので、Python に慣れていない人は代わりに数値のカウンターを使うかもしれません:

for i in range(len(food)):
    print(food[i])

これに対し、きれいな Pythonic な方法は:

for piece in food:
    print(piece)

qualified name

(修飾名) モジュールのグローバルスコープから、そのモジュールで定義されたクラス、関数、メソッドへの、 "パス" を表すドット名表記です。 PEP 3155 [https://peps.python.org/pep-3155/] で定義されています。トップレベルの関数やクラスでは、修飾名はオブジェクトの名前と同じです:

>>> class C:
...     class D:
...         def meth(self):
...             pass
...
>>> C.__qualname__
'C'
>>> C.D.__qualname__
'C.D'
>>> C.D.meth.__qualname__
'C.D.meth'

モジュールへの参照で使われると、完全修飾名 (fully qualified name) はすべての親パッケージを含む全体のドット名表記、例えば email.mime.text を意味します:

>>> import email.mime.text
>>> email.mime.text.__name__
'email.mime.text'

reference count

The number of references to an object. When the reference count of an object drops to zero, it is deallocated. Some objects are "immortal" and have reference counts that are never modified, and therefore the objects are never deallocated. Reference counting is generally not visible to Python code, but it is a key element of the CPython implementation. Programmers can call the sys.getrefcount() function to return the reference count for a particular object.

regular package

伝統的な、 __init__.py ファイルを含むディレクトリとしての package。

namespace package を参照してください。

__slots__

クラス内での宣言で、インスタンス属性の領域をあらかじめ定義しておき、インスタンス辞書を排除することで、メモリを節約します。これはよく使われるテクニックですが、正しく扱うには少しトリッキーなので、稀なケース、例えばメモリが死活問題となるアプリケーションでインスタンスが大量に存在する、といったときを除き、使わないのがベストです。

sequence

An iterable which supports efficient element access using integer indices via the __getitem__() special method and defines a __len__() method that returns the length of the sequence. Some built-in sequence types are list, str, tuple, and bytes. Note that dict also supports __getitem__() and __len__(), but is considered a mapping rather than a sequence because the lookups use arbitrary immutable keys rather than integers.

The collections.abc.Sequence abstract base class defines a much richer interface that goes beyond just __getitem__() and __len__(), adding count(), index(), __contains__(), and __reversed__(). Types that implement this expanded interface can be registered explicitly using register(). For more documentation on sequence methods generally, see Common Sequence Operations.

set comprehension

(集合内包表記) iterable 内の全てあるいは一部の要素を処理して、その結果からなる集合を返すコンパクトな書き方です。 results = {c for c in 'abracadabra' if c not in 'abc'} とすると、{'r', 'd'} という文字列の辞書を生成します。 リスト、集合、辞書の表示 を参照してください。

single dispatch

generic function の一種で実装は一つの引数の型により選択されます。

slice

(スライス) 一般に シーケンス の一部を含むオブジェクト。スライスは、添字表記 [] で与えられた複数の数の間にコロンを書くことで作られます。例えば、 variable_name[1:3:5] です。角括弧 (添字) 記号は slice オブジェクトを内部で利用しています。

special method

(特殊メソッド) ある型に特定の操作、例えば加算をするために Python から暗黙に呼び出されるメソッド。この種類のメソッドは、メソッド名の最初と最後にアンダースコア 2 つがついています。特殊メソッドについては 特殊メソッド名 で解説されています。

statement

(文) 文はスイート (コードの"ブロック") に不可欠な要素です。文は 式 かキーワードから構成されるもののどちらかです。後者には if、while、for があります。

static type checker

An external tool that reads Python code and analyzes it, looking for issues such as incorrect types. See also type hints and the typing module.

strong reference

In Python's C API, a strong reference is a reference to an object which is owned by the code holding the reference. The strong reference is taken by calling Py_INCREF() when the reference is created and released with Py_DECREF() when the reference is deleted.

The Py_NewRef() function can be used to create a strong reference to an object. Usually, the Py_DECREF() function must be called on the strong reference before exiting the scope of the strong reference, to avoid leaking one reference.

See also borrowed reference.

text encoding

A string in Python is a sequence of Unicode code points (in range U+0000--U+10FFFF). To store or transfer a string, it needs to be serialized as a sequence of bytes.

Serializing 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 serialization codecs, which are collectively referred to as "text encodings".

text file

(テキストファイル) str オブジェクトを読み書きできる file object です。しばしば、テキストファイルは実際にバイト指向のデータストリームにアクセスし、 テキストエンコーディング を自動的に行います。テキストファイルの例は、 sys.stdin, sys.stdout, io.StringIO インスタンスなどをテキストモード ('r' or 'w') で開いたファイルです。

bytes-like オブジェクト を読み書きできるファイルオブジェクトについては、 バイナリファイル も参照してください。

triple-quoted string

(三重クォート文字列) 3つの連続したクォート記号(")かアポストロフィー(')で囲まれた文字列。通常の(一重)クォート文字列に比べて表現できる文字列に違いはありませんが、幾つかの理由で有用です。1つか2つの連続したクォート記号をエスケープ無しに書くことができますし、行継続文字(\)を使わなくても複数行にまたがることができるので、ドキュメンテーション文字列を書く時に特に便利です。

type

(型) Python オブジェクトの型はオブジェクトがどのようなものかを決めます。あらゆるオブジェクトは型を持っています。オブジェクトの型は __class__ 属性でアクセスしたり、type(obj) で取得したり出来ます。

type alias

(型エイリアス) 型の別名で、型を識別子に代入して作成します。

型エイリアスは 型ヒント を単純化するのに有用です。例えば:

def remove_gray_shades(
        colors: list[tuple[int, int, int]]) -> list[tuple[int, int, int]]:
    pass

これは次のようにより読みやすくできます:

Color = tuple[int, int, int]

def remove_gray_shades(colors: list[Color]) -> list[Color]:
    pass

機能の説明がある typing と PEP 484 [https://peps.python.org/pep-0484/] を参照してください。

type hint

(型ヒント) 変数、クラス属性、関数のパラメータや返り値の期待される型を指定する annotation です。

Type hints are optional and are not enforced by Python but they are useful to static type checkers. They can also aid IDEs with code completion and refactoring.

グローバル変数、クラス属性、関数で、ローカル変数でないものの型ヒントは typing.get_type_hints() で取得できます。

機能の説明がある typing と PEP 484 [https://peps.python.org/pep-0484/] を参照してください。

universal newlines

テキストストリームの解釈法の一つで、以下のすべてを行末と認識します: Unix の行末規定 '\n'、Windows の規定 '\r\n'、古い Macintosh の規定 '\r'。利用法について詳しくは、 PEP 278 [https://peps.python.org/pep-0278/] と PEP 3116 [https://peps.python.org/pep-3116/] 、さらに bytes.splitlines() も参照してください。

variable annotation

(変数アノテーション) 変数あるいはクラス属性の annotation 。

変数あるいはクラス属性に注釈を付けたときは、代入部分は任意です:

class C:
    field: 'annotation'

変数アノテーションは通常は 型ヒント のために使われます: 例えば、この変数は int の値を取ることを期待されています:

count: int = 0

変数アノテーションの構文については 注釈付き代入文 (annotated assignment statements) 節で解説しています。

機能の説明がある function annotation, PEP 484 [https://peps.python.org/pep-0484/] , PEP 526 [https://peps.python.org/pep-0526/] を参照してください。また、アノテーションを利用するベストプラクティスとして Annotations Best Practices も参照してください。

virtual environment

(仮想環境) 協調的に切り離された実行環境です。これにより Python ユーザとアプリケーションは同じシステム上で動いている他の Python アプリケーションの挙動に干渉することなく Python パッケージのインストールと更新を行うことができます。

venv を参照してください。

virtual machine

(仮想マシン) 完全にソフトウェアにより定義されたコンピュータ。 Python の仮想マシンは、バイトコードコンパイラが出力した バイトコード を実行します。

Zen of Python

(Pythonの悟り) Python を理解し利用する上での導きとなる、Python の設計原則と哲学をリストにしたものです。対話プロンプトで "import this" とするとこのリストを読めます。

このドキュメントについて

このドキュメントは、 Python のドキュメントを主要な目的として作られた ドキュメントプロセッサの Sphinx [https://www.sphinx-doc.org/] を利用して、 reStructuredText [https://docutils.sourceforge.io/rst.html] 形式のソースから生成されました。

ドキュメントとそのツール群の開発は、Python 自身と同様に完全にボランティアの努力です。もしあなたが貢献したいなら、どのようにすればよいかについて バグへの対処 ページをご覧下さい。 新しいボランティアはいつでも歓迎です! （訳注: 日本語訳の問題については、 GitHub 上の Issue Tracker [https://github.com/python-doc-ja/python-doc-ja/issues] で報告をお願いします。）

多大な感謝を:

Fred L. Drake, Jr., オリジナルの Python ドキュメントツールセットの作成者で、ドキュメントの多くを書きました。

Docutils [http://docutils.sourceforge.net/] プロジェクト reStructuredText と Docutils ツールセットを作成しました。

Fredrik Lundh の Alternative Python Reference プロジェクトから Sphinx は多くのアイデアを得ました。

Pythonドキュメント 貢献者

多くの方々が Python 言語、Python 標準ライブラリ、そして Python ドキュメンテーションに貢献してくれています。ソース配布物の Misc/ACKS [https://github.com/python/cpython/tree/3.12/Misc/ACKS] に、それら貢献してくれた人々を部分的にではありますがリストアップしてあります。

Python コミュニティからの情報提供と貢献がなければこの素晴らしいドキュメンテーションは生まれませんでした -- ありがとう!

バグへの対処

Python は安定性について高い評価を得た、成熟した言語です。この評価を守るために、開発者たちはあなたが見つけた Python の不備を知りたいと思っています。

バグを自分で直して Python にパッチを送る方が、やり取りに無駄が無く関わる人数も少なく済むこともあります。ぜひ 貢献 する方法を学んでください。

ドキュメントの不備

このドキュメントの不備を発見したとき、または、改善を提案したいときは、問題点を tracker に報告してください。修正方法の案があるならば、それも含めて。（訳注: 日本語訳の問題については、 GitHub 上の Issue Tracker [https://github.com/python-doc-ja/python-doc-ja/issues] で報告をお願いします。）

または Documentation Discourse forum [https://discuss.python.org/c/documentation/26] でディスカッションを行うこともできます。

ドキュメントのテーマ (HTML / CSS / JavaScript) に不備を見つけたときは、 python-doc-theme bug tracker [https://github.com/python/python-docs-theme] に報告してください。

時間がない場合、ドキュメントの問題を docs@python.org 宛て、メールで報告することもできます。 (Python の動作に関するバグ報告は python-list@python.org 宛になります。) 'docs@' はボランティアで運営されているメーリングリストです。報告が伝わっていても、対応への時間がかかることもあります。

参考

ドキュメントのバグ [https://github.com/python/cpython/issues?q=is%3Aissue+is%3Aopen+label%3Adocs]

Python issue tracker に出されたドキュメントバグのリスト。

イシュートラッカー [https://devguide.python.org/tracker/]

issue tracker への改善報告に関する作業過程の概観。

ドキュメントを手伝う [https://devguide.python.org/docquality/#helping-with-documentation]

Python ドキュメントへの貢献に興味がある個人へ向けた包括的なガイド。

ドキュメントの翻訳 [https://devguide.python.org/documentation/translating/]

ドキュメントの翻訳とその連絡先の載った GitHub pages のリスト。

Python の課題管理システムを使う

Python 自体に関する問題は Githubのissue tracker (https://github.com/python/cpython/issues) で報告してください。このGithub issue trackerは、関連情報を入力して開発者に報告するための Web フォームを提供しています。

レポートを書くには、初めにその問題が既にレポートされていないか確認します。これにより、開発者の時間が無駄にならないだけでなく、あなたが、問題に対して為された対処について知ることもできます。次のリリースに向けて問題が修正されたのかもしれませんし、追加の情報が必要とされているのかもしれません（この場合は是非情報を提供してください）。確認のためにはページの上の検索ボックスを利用してください。

報告しようとしている問題がまだリストにない場合は、GitHub にログインしてください。GitHubのアカウントをまだお持ちでない場合は、「Sign up」リンクから新しいアカウントを作成してください。匿名でバグレポートを提出することはできません。

ログインした状態で、課題を送信することができます。トップバーの「New issue」ボタンをクリックして、新しい課題を報告してください。

報告のフォームには、「Title」と「Comment」の2つのフィールドがあります。

「Title」フィールドには、問題の とても 短い説明を（訳注: 英語で）入力してください。10語以内が望ましいです。

"Comment" フィールドで、あなたが期待した結果と実際の結果も含め、問題の詳細を説明してください。拡張モジュールが関与しているかどうかと、使用しているハードウェアとソフトウェアプラットフォームも (必要に応じてバージョン情報も) 必ず報告に含めてください。

各問題レポートは開発者によってレビューされ、問題を修正するために何が必要かを判断します。issueで何らかの行動があるたびに、最新情報を通知します。

参考

How to Report Bugs Effectively [https://www.chiark.greenend.org.uk/~sgtatham/bugs.html]

有益なバグ報告について詳しく説明した記事です。どんな情報が、なぜ有益なのかを説明しています。

Bug Writing Guidelines [http://developer.mozilla.org/en/docs/Bug_writing_guidelines]

良いバグ報告を書くための情報です。この情報の一部はMozillaプロジェクト独自のものですが、一般的に良い習慣を解説しています。

Python への貢献をはじめる

見つけたバグの報告だけでなく、修正パッチの提出も歓迎します。Python Developer's Guide [https://devguide.python.org/] には Python へのパッチの始め方について詳しい情報があります。疑問があれば、core-mentorship mailing list [https://mail.python.org/mailman3/lists/core-mentorship.python.org/] は Python の問題解決の過程に関するありとあらゆる疑問への答えを得ることが出来るフレンドリーな場所です。

Copyright

Python and this documentation is:

Copyright © 2001-2023 Python Software Foundation. All rights reserved.

Copyright © 2000 BeOpen.com. All rights reserved.

Copyright © 1995-2000 Corporation for National Research Initiatives. All rights reserved.

Copyright © 1991-1995 Stichting Mathematisch Centrum. All rights reserved.

ライセンスおよび許諾に関する完全な情報は、 歴史とライセンス を参照してください。

歴史とライセンス

Python の歴史

Python は 1990 年代の始め、オランダにある Stichting Mathematisch Centrum (CWI, https://www.cwi.nl/ 参照) で Guido van Rossum によって ABC と呼ばれる言語の後継言語として生み出されました。その後多くの人々が Python に貢献していますが、 Guido は今日でも Python 製作者の先頭に立っています。

1995 年、 Guido は米国ヴァージニア州レストンにある Corporation for National Reserch Initiatives (CNRI, https://www.cnri.reston.va.us/ 参照) で Python の開発に携わり、いくつかのバージョンをリリースしました。

2000 年 3 月、 Guido と Python のコア開発チームは BeOpen.com に移り、 BeOpen PythonLabs チームを結成しました。同年 10 月、 PythonLabs チームは Digital Creations (現在の Zope Corporation, https://www.zope.org/ 参照) に移りました。そして 2001 年、 Python に関する知的財産を保有するための非営利組織 Python Software Foundation (PSF、 https://www.python.org/psf/ 参照) を立ち上げました。このとき Zope Corporation は PSF の賛助会員になりました。

Python のリリースは全てオープンソース (オープンソースの定義は https://opensource.org/ を参照してください) です。歴史的にみて、ごく一部を除くほとんどの Python リリースは GPL 互換になっています; 各リリースについては下表にまとめてあります。

リリース

ベース

西暦年

権利

GPL 互換

0.9.0 - 1.2

n/a

1991-1995

CWI

yes

1.3 - 1.5.2

1.2

1995-1999

CNRI

yes

1.6

1.5.2

2000

CNRI

no

2.0

1.6

2000

BeOpen.com

no

1.6.1

1.6

2001

CNRI

no

2.1

2.0+1.6.1

2001

PSF

no

2.0.1

2.0+1.6.1

2001

PSF

yes

2.1.1

2.1+2.0.1

2001

PSF

yes

2.1.2

2.1.1

2002

PSF

yes

2.1.3

2.1.2

2002

PSF

yes

2.2 以降

2.1.1

2001-現在

PSF

yes

注釈

「GPL 互換」という表現は、Python が GPL で配布されているという意味ではありません。Python のライセンスは全て、GPL と違い、変更したバージョンを配布する際に変更をオープンソースにしなくてもかまいません。GPL 互換のライセンスの下では、GPL でリリースされている他のソフトウェアと Python を組み合わせられますが、それ以外のライセンスではそうではありません。

Guido の指示の下、これらのリリースを可能にしてくださった多くのボランティアのみなさんに感謝します。

Terms and conditions for accessing or otherwise using Python

Python software and documentation are licensed under the PSF License Agreement.

Starting with Python 3.8.6, examples, recipes, and other code in the documentation are dual licensed under the PSF License Agreement and the Zero-Clause BSD license.

Some software incorporated into Python is under different licenses. The licenses are listed with code falling under that license. See Licenses and Acknowledgements for Incorporated Software for an incomplete list of these licenses.

PSF LICENSE AGREEMENT FOR PYTHON 3.12.3

1. This LICENSE AGREEMENT is between the Python Software Foundation ("PSF"), and
   the Individual or Organization ("Licensee") accessing and otherwise using Python
   3.12.3 software in source or binary form and its associated documentation.

2. Subject to the terms and conditions of this License Agreement, PSF hereby
   grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce,
   analyze, test, perform and/or display publicly, prepare derivative works,
   distribute, and otherwise use Python 3.12.3 alone or in any derivative
   version, provided, however, that PSF's License Agreement and PSF's notice of
   copyright, i.e., "Copyright © 2001-2023 Python Software Foundation; All Rights
   Reserved" are retained in Python 3.12.3 alone or in any derivative version
   prepared by Licensee.

3. In the event Licensee prepares a derivative work that is based on or
   incorporates Python 3.12.3 or any part thereof, and wants to make the
   derivative work available to others as provided herein, then Licensee hereby
   agrees to include in any such work a brief summary of the changes made to Python
   3.12.3.

4. PSF is making Python 3.12.3 available to Licensee on an "AS IS" basis.
   PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED.  BY WAY OF
   EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND DISCLAIMS ANY REPRESENTATION OR
   WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE
   USE OF PYTHON 3.12.3 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON 3.12.3
   FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF
   MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 3.12.3, OR ANY DERIVATIVE
   THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

6. This License Agreement will automatically terminate upon a material breach of
   its terms and conditions.

7. Nothing in this License Agreement shall be deemed to create any relationship
   of agency, partnership, or joint venture between PSF and Licensee.  This License
   Agreement does not grant permission to use PSF trademarks or trade name in a
   trademark sense to endorse or promote products or services of Licensee, or any
   third party.

8. By copying, installing or otherwise using Python 3.12.3, Licensee agrees
   to be bound by the terms and conditions of this License Agreement.

BEOPEN.COM LICENSE AGREEMENT FOR PYTHON 2.0

BEOPEN PYTHON OPEN SOURCE LICENSE AGREEMENT VERSION 1

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
   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.

CNRI LICENSE AGREEMENT FOR PYTHON 1.6.1

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: 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.

CWI LICENSE AGREEMENT FOR PYTHON 0.9.0 THROUGH 1.2

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.

ZERO-CLAUSE BSD LICENSE FOR CODE IN THE PYTHON 3.12.3 DOCUMENTATION

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.

Licenses and Acknowledgements for Incorporated Software

This section is an incomplete, but growing list of licenses and acknowledgements for third-party software incorporated in the Python distribution.

Mersenne Twister

The _random C extension underlying the random module includes code based on a download from http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/MT2002/emt19937ar.html. The following are the verbatim comments from the original code:

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)

ソケット

The socket module uses the functions, getaddrinfo(), and getnameinfo(), which are coded in separate source files from the WIDE Project, https://www.wide.ad.jp/.

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.

Asynchronous socket services

The test.support.asynchat and test.support.asyncore modules contain the following notice:

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.

Cookie management

The http.cookies module contains the following notice:

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.

Execution tracing

The trace module contains the following notice:

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.

UUencode and UUdecode functions

The uu module contains the following notice:

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

XML Remote Procedure Calls

The xmlrpc.client module contains the following notice:

    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.

test_epoll

The test.test_epoll module contains the following notice:

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.

Select kqueue

select モジュールは kqueue インターフェースについての次の告知を含んでいます:

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.

SipHash24

The file Python/pyhash.c contains Marek Majkowski' implementation of Dan Bernstein's SipHash24 algorithm. It contains the following note:

<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)

strtod と dtoa

The file Python/dtoa.c, which supplies C functions dtoa and strtod for conversion of C doubles to and from strings, is derived from the file of the same name by David M. Gay, currently available from https://web.archive.org/web/20220517033456/http://www.netlib.org/fp/dtoa.c. The original file, as retrieved on March 16, 2009, contains the following copyright and licensing notice:

/****************************************************************
 *
 * 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.
 *
 ***************************************************************/

OpenSSL

The modules hashlib, posix, ssl, crypt use the OpenSSL library for added performance if made available by the operating system. Additionally, the Windows and macOS installers for Python may include a copy of the OpenSSL libraries, so we include a copy of the OpenSSL license here. For the OpenSSL 3.0 release, and later releases derived from that, the Apache License v2 applies:

                              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

expat

The pyexpat extension is built using an included copy of the expat sources unless the build is configured --with-system-expat:

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.

libffi

The _ctypes C extension underlying the ctypes module is built using an included copy of the libffi sources unless the build is configured --with-system-libffi:

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.

zlib

The zlib extension is built using an included copy of the zlib sources if the zlib version found on the system is too old to be used for the build:

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

cfuhash

The implementation of the hash table used by the tracemalloc で使用しているハッシュテーブルの実装は、cfuhashプロジェクトのものに基づきます:

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.

libmpdec

The _decimal C extension underlying the decimal module is built using an included copy of the libmpdec library unless the build is configured --with-system-libmpdec:

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.

W3C C14N test suite

The C14N 2.0 test suite in the test package (Lib/test/xmltestdata/c14n-20/) was retrieved from the W3C website at https://www.w3.org/TR/xml-c14n2-testcases/ and is distributed under the 3-clause BSD license:

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.

Audioop

The audioop module uses the code base in g771.c file of the SoX project. https://sourceforge.net/projects/sox/files/sox/12.17.7/sox-12.17.7.tar.gz

This source code is a product of Sun Microsystems, Inc. and is provided for unrestricted use. Users may copy or modify this source code without charge.

SUN SOURCE CODE IS PROVIDED AS IS WITH NO WARRANTIES OF ANY KIND INCLUDING THE WARRANTIES OF DESIGN, MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE, OR ARISING FROM A COURSE OF DEALING, USAGE OR TRADE PRACTICE.

Sun source code is provided with no support and without any obligation on the part of Sun Microsystems, Inc. to assist in its use, correction, modification or enhancement.

SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY THIS SOFTWARE OR ANY PART THEREOF.

In no event will Sun Microsystems, Inc. be liable for any lost revenue or profits or other special, indirect and consequential damages, even if Sun has been advised of the possibility of such damages.

Sun Microsystems, Inc. 2550 Garcia Avenue Mountain View, California 94043

asyncio

Parts of the asyncio module are incorporated from uvloop 0.16 [https://github.com/MagicStack/uvloop/tree/v0.16.0], which is distributed under the MIT license:

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.

Pythonモジュール索引

_ | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r | s | t | u | v | w | x | z

| _ |
| __future__ | Future statement definitions
| __main__ | The environment where top-level code is run. Covers command-line interfaces, import-time behavior, and ``__name__ == '__main__'``.
| _thread | Low-level threading API.
| _tkinter | A binary module that contains the low-level interface to Tcl/Tk.
| a |
| abc | Abstract base classes according to :pep:`3119`.
| aifc | 非推奨: Read and write audio files in AIFF or AIFC format.
| argparse | Command-line option and argument parsing library.
| array | Space efficient arrays of uniformly typed numeric values.
| ast | Abstract Syntax Tree classes and manipulation.
| asyncio | Asynchronous I/O.
| atexit | Register and execute cleanup functions.
| audioop | 非推奨: Manipulate raw audio data.
| b |
| base64 | RFC 4648: Base16, Base32, Base64 Data Encodings; Base85 and Ascii85
| bdb | Debugger framework.
| binascii | Tools for converting between binary and various ASCII-encoded binary representations.
| bisect | Array bisection algorithms for binary searching.
| builtins | The module that provides the built-in namespace.
| bz2 | Interfaces for bzip2 compression and decompression.
| c |
| calendar | Functions for working with calendars, including some emulation of the Unix cal program.
| cgi | 非推奨: Helpers for running Python scripts via the Common Gateway Interface.
| cgitb | 非推奨: Configurable traceback handler for CGI scripts.
| chunk | 非推奨: Module to read IFF chunks.
| cmath | Mathematical functions for complex numbers.
| cmd | Build line-oriented command interpreters.
| code | Facilities to implement read-eval-print loops.
| codecs | Encode and decode data and streams.
| codeop | Compile (possibly incomplete) Python code.
- | collections | Container datatypes
|     collections.abc | Abstract base classes for containers
| colorsys | Conversion functions between RGB and other color systems.
| compileall | Tools for byte-compiling all Python source files in a directory tree.
- | concurrent |
|     concurrent.futures | Execute computations concurrently using threads or processes.
| configparser | Configuration file parser.
| contextlib | Utilities for with-statement contexts.
| contextvars | Context Variables
| copy | Shallow and deep copy operations.
| copyreg | Register pickle support functions.
| cProfile |
| crypt (Unix) | 非推奨: The crypt() function used to check Unix passwords.
| csv | Write and read tabular data to and from delimited files.
| ctypes | A foreign function library for Python.
- | curses (Unix) | An interface to the curses library, providing portable terminal handling.
|     curses.ascii | Constants and set-membership functions for ASCII characters.
|     curses.panel | A panel stack extension that adds depth to curses windows.
|     curses.textpad | Emacs-like input editing in a curses window.
| d |
| dataclasses | Generate special methods on user-defined classes.
| datetime | Basic date and time types.
- | dbm | Interfaces to various Unix "database" formats.
|     dbm.dumb | Portable implementation of the simple DBM interface.
|     dbm.gnu (Unix) | GNU database manager
|     dbm.ndbm (Unix) | The New Database Manager
| decimal | Implementation of the General Decimal Arithmetic Specification.
| difflib | Helpers for computing differences between objects.
| dis | Disassembler for Python bytecode.
| doctest | Test pieces of code within docstrings.
| e |
- | email | Package supporting the parsing, manipulating, and generating email messages.
|     email.charset | Character Sets
|     email.contentmanager | Storing and Retrieving Content from MIME Parts
|     email.encoders | Encoders for email message payloads.
|     email.errors | The exception classes used by the email package.
|     email.generator | Generate flat text email messages from a message structure.
|     email.header | Representing non-ASCII headers
|     email.headerregistry | Automatic Parsing of headers based on the field name
|     email.iterators | Iterate over a message object tree.
|     email.message | The base class representing email messages.
|     email.mime | Build MIME messages.
|     email.mime.application |
|     email.mime.audio |
|     email.mime.base |
|     email.mime.image |
|     email.mime.message |
|     email.mime.multipart |
|     email.mime.nonmultipart |
|     email.mime.text |
|     email.parser | Parse flat text email messages to produce a message object structure.
|     email.policy | Controlling the parsing and generating of messages
|     email.utils | Miscellaneous email package utilities.
- | encodings |
|     encodings.idna | Internationalized Domain Names implementation
|     encodings.mbcs | Windows ANSI codepage
|     encodings.utf_8_sig | UTF-8 codec with BOM signature
| ensurepip | Bootstrapping the "pip" installer into an existing Python installation or virtual environment.
| enum | Implementation of an enumeration class.
| errno | Standard errno system symbols.
| f |
| faulthandler | Dump the Python traceback.
| fcntl (Unix) | The fcntl() and ioctl() system calls.
| filecmp | Compare files efficiently.
| fileinput | Loop over standard input or a list of files.
| fnmatch | Unix shell style filename pattern matching.
| fractions | Rational numbers.
| ftplib | FTP protocol client (requires sockets).
| functools | Higher-order functions and operations on callable objects.
| g |
| gc | Interface to the cycle-detecting garbage collector.
| getopt | Portable parser for command line options; support both short and long option names.
| getpass | Portable reading of passwords and retrieval of the userid.
| gettext | Multilingual internationalization services.
| glob | Unix shell style pathname pattern expansion.
| graphlib | Functionality to operate with graph-like structures
| grp (Unix) | The group database (getgrnam() and friends).
| gzip | Interfaces for gzip compression and decompression using file objects.
| h |
| hashlib | Secure hash and message digest algorithms.
| heapq | Heap queue algorithm (a.k.a. priority queue).
| hmac | Keyed-Hashing for Message Authentication (HMAC) implementation
- | html | Helpers for manipulating HTML.
|     html.entities | Definitions of HTML general entities.
|     html.parser | A simple parser that can handle HTML and XHTML.
- | http | HTTP status codes and messages
|     http.client | HTTP and HTTPS protocol client (requires sockets).
|     http.cookiejar | Classes for automatic handling of HTTP cookies.
|     http.cookies | Support for HTTP state management (cookies).
|     http.server | HTTP server and request handlers.
| i |
| idlelib | Implementation package for the IDLE shell/editor.
| imaplib | IMAP4 protocol client (requires sockets).
| imghdr | 非推奨: Determine the type of image contained in a file or byte stream.
- | importlib | The implementation of the import machinery.
|     importlib.abc | Abstract base classes related to import
|     importlib.machinery | Importers and path hooks
|     importlib.metadata | Accessing package metadata
|     importlib.resources | Package resource reading, opening, and access
|     importlib.resources.abc | Abstract base classes for resources
|     importlib.util | Utility code for importers
| inspect | Extract information and source code from live objects.
| io | Core tools for working with streams.
| ipaddress | IPv4/IPv6 manipulation library.
| itertools | Functions creating iterators for efficient looping.
| j |
- | json | Encode and decode the JSON format.
|     json.tool | A command line to validate and pretty-print JSON.
| k |
| keyword | Test whether a string is a keyword in Python.
| l |
| lib2to3 | The 2to3 library
| linecache | Provides random access to individual lines from text files.
| locale | Internationalization services.
- | logging | Flexible event logging system for applications.
|     logging.config | Configuration of the logging module.
|     logging.handlers | Handlers for the logging module.
| lzma | A Python wrapper for the liblzma compression library.
| m |
| mailbox | Manipulate mailboxes in various formats
| mailcap | 非推奨: Mailcap file handling.
| marshal | Convert Python objects to streams of bytes and back (with different constraints).
| math | Mathematical functions (sin() etc.).
| mimetypes | Mapping of filename extensions to MIME types.
| mmap | Interface to memory-mapped files for Unix and Windows.
| modulefinder | Find modules used by a script.
| msilib (Windows) | 非推奨: Creation of Microsoft Installer files, and CAB files.
| msvcrt (Windows) | Miscellaneous useful routines from the MS VC++ runtime.
- | multiprocessing | Process-based parallelism.
|     multiprocessing.connection | API for dealing with sockets.
|     multiprocessing.dummy | Dumb wrapper around threading.
|     multiprocessing.managers | Share data between process with shared objects.
|     multiprocessing.pool | Create pools of processes.
|     multiprocessing.shared_memory | Provides shared memory for direct access across processes.
|     multiprocessing.sharedctypes | Allocate ctypes objects from shared memory.
| n |
| netrc | Loading of .netrc files.
| nis (Unix) | 非推奨: Interface to Sun's NIS (Yellow Pages) library.
| nntplib | 非推奨: NNTP protocol client (requires sockets).
| numbers | Numeric abstract base classes (Complex, Real, Integral, etc.).
| o |
| operator | Functions corresponding to the standard operators.
| optparse | 非推奨: Command-line option parsing library.
- | os | Miscellaneous operating system interfaces.
|     os.path | Operations on pathnames.
| ossaudiodev (Linux, FreeBSD) | 非推奨: Access to OSS-compatible audio devices.
| p |
| pathlib | Object-oriented filesystem paths
| pdb | The Python debugger for interactive interpreters.
| pickle | Convert Python objects to streams of bytes and back.
| pickletools | Contains extensive comments about the pickle protocols and pickle-machine opcodes, as well as some useful functions.
| pipes (Unix) | 非推奨: A Python interface to Unix shell pipelines.
| pkgutil | Utilities for the import system.
| platform | Retrieves as much platform identifying data as possible.
| plistlib | Generate and parse Apple plist files.
| poplib | POP3 protocol client (requires sockets).
| posix (Unix) | The most common POSIX system calls (normally used via module os).
| pprint | Data pretty printer.
| profile | Python source profiler.
| pstats | Statistics object for use with the profiler.
| pty (Unix) | Pseudo-Terminal Handling for Unix.
| pwd (Unix) | The password database (getpwnam() and friends).
| py_compile | Generate byte-code files from Python source files.
| pyclbr | Supports information extraction for a Python module browser.
| pydoc | Documentation generator and online help system.
| q |
| queue | A synchronized queue class.
| quopri | Encode and decode files using the MIME quoted-printable encoding.
| r |
| random | Generate pseudo-random numbers with various common distributions.
| re | Regular expression operations.
| readline (Unix) | GNU readline support for Python.
| reprlib | Alternate repr() implementation with size limits.
| resource (Unix) | An interface to provide resource usage information on the current process.
| rlcompleter | Python identifier completion, suitable for the GNU readline library.
| runpy | Locate and run Python modules without importing them first.
| s |
| sched | General purpose event scheduler.
| secrets | Generate secure random numbers for managing secrets.
| select | Wait for I/O completion on multiple streams.
| selectors | High-level I/O multiplexing.
| shelve | Python object persistence.
| shlex | Simple lexical analysis for Unix shell-like languages.
| shutil | High-level file operations, including copying.
| signal | Set handlers for asynchronous events.
| site | Module responsible for site-specific configuration.
| sitecustomize |
| smtplib | SMTP protocol client (requires sockets).
| sndhdr | 非推奨: Determine type of a sound file.
| socket | Low-level networking interface.
| socketserver | A framework for network servers.
| spwd (Unix) | 非推奨: The shadow password database (getspnam() and friends).
| sqlite3 | A DB-API 2.0 implementation using SQLite 3.x.
| ssl | TLS/SSL wrapper for socket objects
| stat | Utilities for interpreting the results of os.stat(), os.lstat() and os.fstat().
| statistics | Mathematical statistics functions
| string | Common string operations.
| stringprep | String preparation, as per RFC 3453
| struct | Interpret bytes as packed binary data.
| subprocess | Subprocess management.
| sunau | 非推奨: Provide an interface to the Sun AU sound format.
| symtable | Interface to the compiler's internal symbol tables.
- | sys | Access system-specific parameters and functions.
|     sys.monitoring | Access and control event monitoring
| sysconfig | Python's configuration information
| syslog (Unix) | An interface to the Unix syslog library routines.
| t |
| tabnanny | Tool for detecting white space related problems in Python source files in a directory tree.
| tarfile | Read and write tar-format archive files.
| telnetlib | 非推奨: Telnet client class.
| tempfile | Generate temporary files and directories.
| termios (Unix) | POSIX style tty control.
- | test | Regression tests package containing the testing suite for Python.
|     test.regrtest | Drives the regression test suite.
|     test.support | Support for Python's regression test suite.
|     test.support.bytecode_helper | Support tools for testing correct bytecode generation.
|     test.support.import_helper | Support for import tests.
|     test.support.os_helper | Support for os tests.
|     test.support.script_helper | Support for Python's script execution tests.
|     test.support.socket_helper | Support for socket tests.
|     test.support.threading_helper | Support for threading tests.
|     test.support.warnings_helper | Support for warnings tests.
| textwrap | Text wrapping and filling
| threading | Thread-based parallelism.
| time | Time access and conversions.
| timeit | Measure the execution time of small code snippets.
- | tkinter | Interface to Tcl/Tk for graphical user interfaces
|     tkinter.colorchooser (Tk) | Color choosing dialog
|     tkinter.commondialog (Tk) | Tkinter base class for dialogs
|     tkinter.dnd (Tk) | Tkinter drag-and-drop interface
|     tkinter.filedialog (Tk) | Dialog classes for file selection
|     tkinter.font (Tk) | Tkinter font-wrapping class
|     tkinter.messagebox (Tk) | Various types of alert dialogs
|     tkinter.scrolledtext (Tk) | Text widget with a vertical scroll bar.
|     tkinter.simpledialog (Tk) | Simple dialog windows
|     tkinter.tix | Tk Extension Widgets for Tkinter
|     tkinter.ttk | Tk themed widget set
| token | Constants representing terminal nodes of the parse tree.
| tokenize | Lexical scanner for Python source code.
| tomllib | Parse TOML files.
| trace | Trace or track Python statement execution.
| traceback | Print or retrieve a stack traceback.
| tracemalloc | Trace memory allocations.
| tty (Unix) | Utility functions that perform common terminal control operations.
| turtle | An educational framework for simple graphics applications
| turtledemo | A viewer for example turtle scripts
| types | Names for built-in types.
| typing | Support for type hints (see :pep:`484`).
| u |
| unicodedata | Access the Unicode Database.
- | unittest | Unit testing framework for Python.
|     unittest.mock | Mock object library.
- | urllib |
|     urllib.error | Exception classes raised by urllib.request.
|     urllib.parse | Parse URLs into or assemble them from components.
|     urllib.request | Extensible library for opening URLs.
|     urllib.response | Response classes used by urllib.
|     urllib.robotparser | Load a robots.txt file and answer questions about fetchability of other URLs.
| usercustomize |
| uu | 非推奨: Encode and decode files in uuencode format.
| uuid | UUID objects (universally unique identifiers) according to RFC 4122
| v |
| venv | Creation of virtual environments.
| w |
| warnings | Issue warning messages and control their disposition.
| wave | Provide an interface to the WAV sound format.
| weakref | Support for weak references and weak dictionaries.
| webbrowser | Easy-to-use controller for web browsers.
| winreg (Windows) | Routines and objects for manipulating the Windows registry.
| winsound (Windows) | Access to the sound-playing machinery for Windows.
- | wsgiref | WSGI Utilities and Reference Implementation.
|     wsgiref.handlers | WSGI server/gateway base classes.
|     wsgiref.headers | WSGI response header tools.
|     wsgiref.simple_server | A simple WSGI HTTP server.
|     wsgiref.types | WSGI types for static type checking
|     wsgiref.util | WSGI environment utilities.
|     wsgiref.validate | WSGI conformance checker.
| x |
| xdrlib | 非推奨: Encoders and decoders for the External Data Representation (XDR).
- | xml | Package containing XML processing modules
|     xml.dom | Document Object Model API for Python.
|     xml.dom.minidom | Minimal Document Object Model (DOM) implementation.
|     xml.dom.pulldom | Support for building partial DOM trees from SAX events.
|     xml.etree.ElementInclude |
|     xml.etree.ElementTree | Implementation of the ElementTree API.
|     xml.parsers.expat | An interface to the Expat non-validating XML parser.
|     xml.parsers.expat.errors |
|     xml.parsers.expat.model |
|     xml.sax | Package containing SAX2 base classes and convenience functions.
|     xml.sax.handler | Base classes for SAX event handlers.
|     xml.sax.saxutils | Convenience functions and classes for use with SAX.
|     xml.sax.xmlreader | Interface which SAX-compliant XML parsers must implement.
- | xmlrpc |
|     xmlrpc.client | XML-RPC client access.
|     xmlrpc.server | Basic XML-RPC server implementations.
| z |
| zipapp | Manage executable Python zip archives
| zipfile | Read and write ZIP-format archive files.
| zipimport | Support for importing Python modules from ZIP archives.
| zlib | Low-level interface to compression and decompression routines compatible with gzip.
| zoneinfo | IANA time zone support

Download Python 3.12.3 Documentation

Last updated on: May 18, 2024 (18:54 UTC).

To download an archive containing all the documents for this version of Python in one of various formats, follow one of links in this table.

Format | Packed as .zip | Packed as .tar.bz2
PDF (US-Letter paper size) | Download (ca. 13 MiB) | Download (ca. 13 MiB)
PDF (A4 paper size) | Download (ca. 13 MiB) | Download (ca. 13 MiB)
HTML | Download (ca. 9 MiB) | Download (ca. 6 MiB)
Plain Text | Download (ca. 3 MiB) | Download (ca. 2 MiB)
EPUB | Download (ca. 5 MiB) |

These archives contain all the content in the documentation.

Unpacking

Unix users should download the .tar.bz2 archives; these are bzipped tar archives and can be handled in the usual way using tar and the bzip2 program. The Info-ZIP unzip program can be used to handle the ZIP archives if desired. The .tar.bz2 archives provide the best compression and fastest download times.

Windows users can use the ZIP archives since those are customary on that platform. These are created on Unix using the Info-ZIP zip program.

Problems

If you have comments or suggestions for the Python documentation, please send email to docs@python.org.

Python 3.12.3 ドキュメント

ようこそ! Python 3.12.3 公式ドキュメントへ。

ドキュメント：

What's new in Python 3.12?
Or all "What's new" documents since Python 2.0

チュートリアル
ここから始めましょう: Python構文と機能のツアー

ライブラリ リファレンス
標準ライブラリとビルトイン

言語リファレンス
構文と言語要素

Pythonのセットアップと使い方
Pythonのインストール方法、configure方法、使い方

Python HOWTO
トピックの より深いマニュアル

Python モジュールのインストール
サードパーティモジュールと PyPI.org

Python モジュールの配布
他の人が使えるようにモジュールを公開する

拡張と埋め込み
C/C++ プログラマ向け

Python の C API
C API リファレンス

FAQ
よくある質問（解答つき！）

索引、用語集、検索：

全モジュール索引
全てのモジュールとライブラリ

総合索引
全ての関数、クラス、用語

用語集
用語の説明

検索
このドキュメントから検索する

全体の目次
章／節一覧

プロジェクト情報：

Reporting issues

ドキュメントへの貢献

Download the documentation

Python の歴史とライセンス

Copyright

このドキュメントについて

Python モジュールの配布

注釈

Python モジュールとパッケージの配布に関する情報とガイダンスは、 Python Packaging User Guide [https://packaging.python.org/] に移動されました。 packaging Python projects [https://packaging.python.org/en/latest/tutorials/packaging-projects/] にはチュートリアルもあります。

Argument Clinic How-To

注釈

Argument Clinic How-TOは、 Python Developer's Guide [https://devguide.python.org/development-tools/clinic/] に移動しました。

How to port Python 2 Code to Python 3

author:

Brett Cannon

Python 2 reached its official end-of-life at the start of 2020. This means that no new bug reports, fixes, or changes will be made to Python 2 - it's no longer supported: see PEP 373 [https://peps.python.org/pep-0373/] and status of Python versions [https://devguide.python.org/versions].

もしあなたが標準 Python ライブラリではなく拡張ライブラリでの移植手段を探しているならば Python 3 への拡張モジュール移植 を参照してください。

The archived python-porting [https://mail.python.org/pipermail/python-porting/] mailing list may contain some useful guidance.

Since Python 3.13 the original porting guide was discontinued. You can find the old guide in the archive [https://docs.python.org/3.12/howto/pyporting.html].

Third-party guides

There are also multiple third-party guides that might be useful:

Guide by Fedora [https://portingguide.readthedocs.io]

PyCon 2020 tutorial [https://www.youtube.com/watch?v=JgIgEjASOlk]

Guide by DigitalOcean [https://www.digitalocean.com/community/tutorials/how-to-port-python-2-code-to-python-3]

Guide by ActiveState [https://www.activestate.com/blog/how-to-migrate-python-2-applications-to-python-3]